Added new Word Companion specification document and moved old one to archive.

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.