# Phase 20 -- Story Intelligence Onboarding

## Functional Design Specification

### Overview

The purpose of the Story Intelligence Onboarding Wizard is to transform
a new user's manuscript into a structured PlotDirector project with as
little manual effort as possible.

Rather than expecting the user to manually create chapters, scenes,
characters and summaries, PlotDirector will guide them through an
onboarding process appropriate to the way they write.

The wizard has two distinct objectives:

1.  Remove the "blank project" experience that new users currently
    encounter.
2.  Demonstrate PlotDirector's capabilities immediately by building a
    rich story model from the user's existing manuscript.

The wizard is website-led throughout. The PlotDirector Word Companion
acts only as a document scanner and synchronisation agent where
Microsoft Word is used.

------------------------------------------------------------------------

# Design Principles

-   The onboarding should feel like a conversation rather than a
    configuration screen.
-   The user should never be presented with options that are irrelevant
    to the software they use.
-   AI is entirely optional.
-   The user always remains in control.
-   No manuscript is analysed using AI without explicit consent.
-   The Word Companion remains the preferred workflow but is never
    mandatory.

------------------------------------------------------------------------

# Wizard Flow

## Step 1 -- Welcome

Display a friendly welcome explaining that PlotDirector will tailor the
setup to the author's workflow.

------------------------------------------------------------------------

## Step 2 -- Where are you in your writing journey?

-   I'm planning a brand new story
-   I've already started writing
-   My manuscript is largely complete

------------------------------------------------------------------------

## Step 3 -- What software do you write in?

-   Microsoft Word (Recommended)
-   Google Docs
-   Scrivener
-   LibreOffice / OpenOffice
-   Markdown / Obsidian
-   Other

Store this preference against the user profile.

------------------------------------------------------------------------

## Step 4 -- Create your first project

Collect:

-   Project Name
-   Optional Description

------------------------------------------------------------------------

## Step 5 -- Create your first book

Collect:

-   Book Title
-   Subtitle
-   Genre
-   Estimated Word Count (optional)
-   Cover Image (optional)

------------------------------------------------------------------------

# Path A -- Microsoft Word

## A1 -- Install the Word Companion

Provide:

-   Download button
-   Installation guide
-   Short demonstration video
-   Troubleshooting link

------------------------------------------------------------------------

## A2 -- Open the manuscript

The user opens the manuscript in Word, starts the Companion, signs in
and links the document to the selected Project and Book.

------------------------------------------------------------------------

## A3 -- Companion Detection

The Companion silently registers itself with PlotDirector, including:

-   User
-   Companion Version
-   Current Document
-   Linked Project
-   Linked Book
-   SignalR Session

The website updates immediately to show **Word Companion Connected**.

Until this point the Companion status is hidden from the application
header.

------------------------------------------------------------------------

## A4 -- Scan Manuscript

The website instructs the Companion (via SignalR) to scan the document.

The Companion detects:

-   Chapters
-   Scenes
-   Word Counts
-   Character Candidates
-   Hidden Document IDs
-   Document Metadata

Progress is streamed continuously back to PlotDirector.

------------------------------------------------------------------------

## A5 -- Review Scan

Display the detected:

-   Chapters
-   Scenes
-   Character Suggestions

Allow editing before import.

------------------------------------------------------------------------

## A6 -- Import Structure

Create:

-   Chapters
-   Scenes
-   Characters
-   Initial Scene Metadata

Return created IDs to the Companion so hidden document markers can be
updated.

------------------------------------------------------------------------

## A7 -- Story Intelligence (Optional)

Explain that PlotDirector can analyse the manuscript using AI.

Explain:

-   Entirely optional.
-   Manuscript is securely processed using the OpenAI API.
-   API content is not used to train AI models.
-   Show estimated time.
-   Show cost or included credits.

Buttons:

-   Analyse Now
-   Skip

------------------------------------------------------------------------

# Path B -- Other Writing Software

## B1 -- Export

Guide the user to export their manuscript as **.docx**.

## B2 -- Upload

Upload the document.

Use the same scanning engine as the Word Companion.

## B3 -- Review

Display detected structure.

## B4 -- Import

Create the project structure.

Explain that future updates can be imported by uploading a fresh Word
export.

## B5 -- Story Intelligence

Offer the same optional AI analysis.

------------------------------------------------------------------------

# Story Intelligence Pipeline

The pipeline should progressively build a structured Story Model.

1.  Scene analysis
2.  Character profiles
3.  Relationship summaries
4.  Location summaries
5.  Asset summaries
6.  Plot thread suggestions
7.  Timeline observations
8.  Continuity and warning generation

Each stage should consume structured data from earlier stages wherever
possible rather than repeatedly analysing the manuscript.

------------------------------------------------------------------------

# Progress Experience

Progress should be streamed live using SignalR.

Example messages:

-   Preparing manuscript
-   Reading Chapter 12 of 38
-   Summarising Scene 54
-   Identifying recurring characters
-   Building relationship map
-   Finding important locations
-   Tracking story assets
-   Constructing timeline
-   Generating character biographies
-   Building your Story Model
-   Finalising project

Display live counters for:

-   Chapters
-   Scenes
-   Characters
-   Locations
-   Assets
-   Relationships
-   Plot Threads

------------------------------------------------------------------------

# Completion Screen

Present a dedicated completion page.

Example summary:

-   42 Chapters
-   186 Scenes
-   38 Characters
-   24 Locations
-   18 Assets
-   31 Relationships
-   11 Plot Threads
-   315 AI Suggestions

Buttons:

-   Review AI Suggestions
-   Open Project Overview
-   Open Writer Workspace
-   Take a Quick Tour

------------------------------------------------------------------------

# Dashboard Behaviour

If Microsoft Word was selected but the Companion has never connected:

Display a dashboard reminder.

Once connected:

-   Hide installation prompts.
-   Show Companion status in the application header.
-   Future connections occur silently.

------------------------------------------------------------------------

# Future Enhancements

-   Automatic manuscript update detection.
-   Incremental re-analysis.
-   Selective AI regeneration.
-   AI confidence scores.
-   Author approval queue.
-   Background processing.
-   Analysis history.
-   Version comparison.
-   Additional writing platform support.

------------------------------------------------------------------------

# Guiding Philosophy

The onboarding wizard is not simply importing a manuscript.

It is constructing a structured **Story Model** that powers
PlotDirector's timelines, continuity analysis, relationships, locations,
assets, plot threads, reports and writing tools.

The end result should leave authors feeling that PlotDirector has
genuinely understood their story rather than simply copied their
document into a database.
