diff --git a/PlotLine/Docs/Features/WordCompanionAddInAndSyncAPI.md b/PlotLine/Docs/Archive/WordCompanionAddInAndSyncAPI.md similarity index 100% rename from PlotLine/Docs/Features/WordCompanionAddInAndSyncAPI.md rename to PlotLine/Docs/Archive/WordCompanionAddInAndSyncAPI.md diff --git a/PlotLine/Docs/Features/PlotDirector_Word_Companion_v2_Specification.md b/PlotLine/Docs/Features/PlotDirector_Word_Companion_v2_Specification.md new file mode 100644 index 0000000..00e97e8 --- /dev/null +++ b/PlotLine/Docs/Features/PlotDirector_Word_Companion_v2_Specification.md @@ -0,0 +1,337 @@ +# PlotDirector Microsoft Word Companion v2 - Architecture and Implementation Specification + +## 1. Vision + +The PlotDirector Word Companion exists to eliminate duplicate data entry and allow authors to continue writing naturally inside Microsoft Word. + +The core philosophy is: + +- Word is where authors write. +- PlotDirector is where authors plan and manage story information. +- The companion silently synchronises the two. + +The companion should require almost no interaction during normal writing. + +The author's primary workflow should be: + +> Write naturally in Word. PlotDirector quietly keeps itself up to date. + +--- + +## 2. Design Principles + +1. Never interrupt the author while writing. +2. Never ask the author for information already present in the manuscript. +3. Never automatically delete manuscript text. +4. Prefer suggestion over assumption. +5. Word owns manuscript structure once linked. +6. PlotDirector owns planning metadata. +7. The companion should feel invisible during drafting. +8. Existing manuscripts are the primary onboarding path. +9. The manuscript is sacred. + +## 3. Primary User Journeys + +### Existing Manuscript Workflow (Primary) + +1. Create or select a PlotDirector project. +2. Open existing manuscript in Word. +3. Launch Word Companion. +4. Link manuscript to project/book. +5. Companion scans manuscript. +6. Chapters and scenes are imported. +7. Major character candidates are suggested. +8. Hidden identifiers are inserted. +9. Author continues writing normally. + +**Target onboarding time:** Less than two minutes. + +### Plan First Workflow (Secondary) + +1. Create project. +2. Create characters, locations and assets. +3. Create chapters and scenes. +4. Generate manuscript skeleton. +5. Begin writing. + +## 4. Ownership Model + +### Planned Structures + +Unlinked chapters and scenes created in PlotDirector can be freely created, deleted, reordered and renamed. + +### Linked Structures + +Represented in Word. + +- Word owns existence. +- PlotDirector owns metadata. + +Linked chapters/scenes cannot normally be deleted from PlotDirector. + +Deletion occurs through Word. + +## 5. Manuscript Binding + +Every manuscript must contain a permanent binding. + +Document metadata: + +- DocumentID +- ProjectID +- BookID +- BindingVersion +- LastSyncUtc + +No binding means no synchronisation. + +## 6. Chapter and Scene Rules + +Every chapter must contain at least one scene. + +Creating a chapter automatically creates: + +`Scene 1 (Default)` + +Book settings: + +- Single default scene per chapter. +- Explicit scene breaks. + +Explicit scene breaks may use: + +- *** +- ### +- Future custom markers. + +The first scene always begins at the chapter heading. + +## 7. Character, Asset and Location Identity + +### Characters + +Character model: + +- Display Name +- Aliases + +Retire Short Name. + +Example: + +**Beth** + +Aliases: + +- Elizabeth +- Elizabeth Fletcher +- Nikki +- Susie + +### Assets + +Assets support aliases. + +Example: + +**Beth's Memory Tin** + +Aliases: + +- memory tin +- the tin +- biscuit tin + +### Locations + +Locations support aliases. + +Example: + +**Grace's Shop** + +Aliases: + +- Grace's +- the shop +- newsagent + +Aliases are used for manuscript detection. + +## 8. Manuscript Import + +Companion scans: + +- Heading structure +- Scene separators +- Word counts + +Companion suggests: + +- Major character candidates + +Import wizard: + +1. Import structure. +2. Review major characters. +3. Finish. + +Complex classification should not occur during onboarding. + +## 9. Character Discovery + +Character discovery is suggestion-based. + +Rules: + +- Use mention frequency. +- Ignore common dictionary words. +- Ignore dates/months/days. +- Show examples. +- User confirms creation. + +Unknown names discovered later become: + +- Create Character +- Add Alias +- Ignore + +No automatic creation. + +## 10. Word Structure Markers + +Stable hidden identifiers are inserted into Word. + +Examples: + +- PD_CHAPTER_123 +- PD_SCENE_456 + +Word Content Controls should be used. + +These identifiers become the permanent bridge between Word and PlotDirector. + +## 11. Synchronisation Architecture + +Synchronisation uses: + +- Local queue +- Debounced idle detection +- Selection change events +- Periodic flush + +Sync is batch-based. + +The companion must never continuously rescan the entire manuscript while typing. + +Only the current scene should be processed during normal writing. + +## 12. Word → PlotDirector Synchronisation + +Automatic: + +- Create chapters. +- Create scenes. +- Update word counts. +- Update ordering. +- Detect entities. +- Record activity. + +Deleting linked structures in Word archives them in PlotDirector. + +## 13. PlotDirector → Word Synchronisation + +Automatic: + +- Character updates. +- Alias updates. +- Metadata updates. + +Manual: + +- Insert planned chapters. +- Insert planned scenes. + +PlotDirector must never automatically remove manuscript text. + +## 14. Entity Detection + +Detection types: + +- Character +- Asset +- Location + +Detection results: + +- Confirmed suggestion +- Ambiguous suggestion +- Ignored + +Detected entities are not automatically added. + +They become pending review items. + +## 15. Companion Suggestions + +Suggestions are reviewed inside PlotDirector. + +Suggestions appear at: + +- Chapter level +- Scene level + +User actions: + +- Accept +- Reject +- Ignore +- Add Alias + +## 16. Writer Workflow Integration + +Automatic updates: + +- Scene word counts +- Chapter word counts +- Book word counts +- Project totals +- Daily writing totals +- Writing schedule progress + +The companion should remove the need for manual progress updates wherever possible. + +## 17. Locked Scene Behaviour + +Locked scenes remain editable in Word. + +When editing a locked scene: + +- Show warning. +- Record change. +- Suggest status change. +- Respect collaborator permissions. + +Initial implementation uses soft locks only. + +## 18. Implementation Phases + +1. Base identity model cleanup. +2. Chapter and scene rules. +3. Manuscript binding. +4. Import workflow. +5. Structure markers. +6. Sync engine. +7. Word → PlotDirector sync. +8. Detection engine. +9. Review workflow. +10. Writer workflow integration. +11. PlotDirector → Word planning sync. +12. Locking. +13. Manuscript generation. + +## Central Rule + +> The companion helps the author write. +> +> PlotDirector quietly keeps itself organised.