From 5d5b34bb11b351e99e01bf289b18afaec10620be Mon Sep 17 00:00:00 2001 From: Nick Beckley Date: Fri, 3 Jul 2026 20:39:56 +0100 Subject: [PATCH] Added Phase-20-Story-Intelligence-Onboarding document --- .../Phase-20-Story-Intelligence-Onboarding.md | 332 ++++++++++++++++++ 1 file changed, 332 insertions(+) create mode 100644 PlotLine/Docs/Features/Phase-20-Story-Intelligence-Onboarding.md diff --git a/PlotLine/Docs/Features/Phase-20-Story-Intelligence-Onboarding.md b/PlotLine/Docs/Features/Phase-20-Story-Intelligence-Onboarding.md new file mode 100644 index 0000000..4ddc1a3 --- /dev/null +++ b/PlotLine/Docs/Features/Phase-20-Story-Intelligence-Onboarding.md @@ -0,0 +1,332 @@ +# 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.