# 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.
