# PlotDirector – Microsoft Word Companion Add-in & Manuscript Sync API

## Overview

The PlotDirector Microsoft Word Companion Add-in is intended to provide a lightweight bridge between an author’s manuscript in Microsoft Word and their planning data in PlotDirector.

The goal is not to recreate PlotDirector inside Word. The add-in should remain focused, fast and unobtrusive.

The core philosophy is:

> **Word is where the author writes.**  
> **PlotDirector is where the author plans, tracks and manages the book.**

The add-in exists to reduce friction between those two places.

It should help the author:

- See the current scene writing brief while drafting.
- Quickly sync chapters, scenes and word counts.
- Associate characters, assets and locations with the current scene.
- Create missing chapters and scenes found in the Word document.
- Avoid duplicate data entry.

It should not become a full scene editor, timeline editor, schedule planner, continuity dashboard or replacement for the main PlotDirector application.

---

## Primary Goals

The Word Companion should provide:

1. A side panel inside Microsoft Word.
2. A way to connect Word to a PlotDirector account, project and book.
3. Detection of the current chapter and scene from the Word document.
4. Display of the current scene’s writing brief.
5. Quick management of scene links:
   - Characters
   - Assets
   - Locations
6. Sync of chapter and scene structure from Word to PlotDirector.
7. Sync of actual word counts from Word to PlotDirector.
8. Safe creation of missing chapters and scenes.
9. No deletion of PlotDirector planning data from Word.
10. A simple, fast workflow that does not interrupt writing.

---

## Non-Goals

The first version should not include:

- Full scene editing.
- Timeline editing.
- Plot line editing.
- Relationship map editing.
- Story health analytics.
- Story warnings dashboard.
- Writing schedule planner.
- Revision workflow controls.
- AI analysis.
- Automatic entity detection.
- Automatic continuity warnings.
- Full manuscript upload for analysis.
- Deleting chapters or scenes from PlotDirector.
- Reordering PlotDirector scenes automatically without review.
- Editing the scene writing brief directly in Word.

These may be considered later, but they should not be included in the initial implementation.

The add-in should avoid becoming a second version of PlotDirector.

---

## User Experience

### Typical Author Flow

1. Author opens their manuscript in Microsoft Word.
2. Author opens the PlotDirector side panel.
3. Author signs in or confirms they are already connected.
4. Author selects:
   - Project
   - Book
5. Author places the cursor inside a scene.
6. The side panel identifies the current chapter and scene.
7. The panel displays:
   - Current chapter
   - Current scene
   - Scene writing brief
   - Scene word count
   - Character checklist
   - Asset checklist
   - Location checklist
8. Author ticks or unticks relevant characters, assets and locations.
9. Author clicks **Save Scene Links**.
10. Author clicks **Sync Current Scene** or **Sync All Chapters & Scenes** when needed.

---

## Side Panel Layout

The add-in should use a Microsoft Word task pane.

Suggested layout:

```text
PlotDirector

Project:
The Alpha Flame: Reckoning

Book:
Book 2

Current Location
Chapter 12: The Wall
Scene 3: Beth searches the drawer

[Refresh From Document]
[Open Scene in PlotDirector]

Scene Writing Brief
------------------------------------------------
Purpose:
Beth realises Elen may have been involved.

Key Beats:
- Beth checks the memory tin
- Finds the missing note
- Calls Rosie
- Decides not to wait for Graham

Emotional Target:
Fear becoming resolve

Continuity Notes:
Maggie is still missing.
Beth does not yet know about Kevin.

[Refresh Brief]

Scene Links
------------------------------------------------
Characters
[ ] Beth
[ ] Maggie
[ ] Rosie
[ ] Graham
[ ] Rebecca

Assets
[ ] Memory tin
[ ] Deposit box key
[ ] TR6

Locations
[ ] Grace
[ ] Ashdown House
[ ] Lickey Hills

[Save Scene Links]

Sync
------------------------------------------------
Current scene word count:
1,248

[Sync Current Scene]
[Sync All Chapters & Scenes]

Last Sync:
Today 09:42
```

The design should be compact and suitable for a narrow side panel.

---

## Add-in Responsibilities

The Word add-in should be responsible for:

- Providing the user interface inside Word.
- Reading the document structure through Office.js.
- Identifying the current chapter and scene.
- Counting words for the current scene or full manuscript.
- Fetching PlotDirector project/book data through the API.
- Fetching the current scene writing brief.
- Fetching character, asset and location lists.
- Displaying selected scene links.
- Posting scene link updates.
- Posting chapter/scene/word count sync data.
- Showing concise success or error messages.

The add-in should remain lightweight.

It should not perform heavy processing that risks making Word feel unresponsive.

---

## PlotDirector Responsibilities

PlotDirector should be responsible for:

- Authentication and authorisation.
- Storing project, book, chapter and scene records.
- Storing actual word counts.
- Storing scene links.
- Returning the writing brief for a scene.
- Creating missing chapters and scenes safely.
- Matching incoming Word structure to existing PlotDirector records.
- Validating user access to projects and books.
- Recording sync history.
- Protecting planning data from accidental deletion or overwrite.

---

## Document Structure Assumptions

The first version should rely on Word heading styles.

Recommended convention:

```text
Heading 1 = Chapter
Heading 2 = Scene
```

Example:

```text
Chapter 1: Echoes of the Past       Heading 1
Scene 1: The Memory Tin             Heading 2
Scene 2: St Luke’s                  Heading 2

Chapter 2: The Weight of Redemption Heading 1
Scene 1: Sunday Morning             Heading 2
```

This avoids brittle parsing based on plain text patterns.

The add-in can later support alternative structures, such as:

- Scene separators.
- Custom markers.
- Content controls.
- Imported document mapping rules.

However, the first version should keep the rules simple.

---

## Current Scene Detection

When the cursor is inside the document, the add-in should identify the current scene by walking backwards through the document structure until it finds the nearest preceding Heading 2.

It should then identify the current chapter by walking backwards until it finds the nearest preceding Heading 1.

If no scene heading is found, the add-in should show:

```text
No scene detected.

Place the cursor inside a scene or use Heading 2 for scene titles.
```

If no chapter heading is found, the add-in should show:

```text
No chapter detected.

Use Heading 1 for chapter titles.
```

---

## Word Count Calculation

### Current Scene Word Count

The add-in should count words between:

- The current scene Heading 2.
- The next Heading 2 or Heading 1.
- Or the end of the document.

This value should be posted to PlotDirector as the scene’s actual word count.

### Full Manuscript Sync

For a full sync, the add-in should:

1. Read all Heading 1 chapters.
2. Read all Heading 2 scenes under each chapter.
3. Count words for each scene.
4. Count words for each chapter.
5. Send the structure to PlotDirector.

---

## Sync Behaviour

### Safe Sync Rules

The sync process should follow these rules:

| Word Document State | PlotDirector Action |
|--------------------|--------------------|
| Chapter exists in Word and PlotDirector | Update word count / sync metadata |
| Scene exists in Word and PlotDirector | Update actual word count / sync metadata |
| Chapter exists in Word but not PlotDirector | Create chapter |
| Scene exists in Word but not PlotDirector | Create scene |
| Chapter exists in PlotDirector but not Word | Leave unchanged |
| Scene exists in PlotDirector but not Word | Leave unchanged |
| Scene order differs | Do not automatically reorder in MVP |
| Scene title differs | Match cautiously; do not overwrite without confidence |

The add-in must not delete chapters or scenes from PlotDirector.

This is important because PlotDirector is the planning source. Chapters and scenes may exist in PlotDirector long before they are written in Word.

---

## Matching Strategy

### MVP Matching

The first version can match records by:

- Project ID
- Book ID
- Chapter title
- Scene title

This is simple and sufficient for early use.

However, title-based matching can break if the author renames chapters or scenes.

### Future Matching Improvement

A later version should introduce stable external sync IDs.

Options:

1. Store PlotDirector IDs in hidden Word content controls.
2. Store PlotDirector IDs in custom document properties.
3. Store a document-level mapping table in the add-in state.
4. Store sync IDs in hidden metadata associated with chapter/scene headings.

Recommended future direction:

```text
Use Word content controls or custom XML metadata to store stable PlotDirector ChapterID and SceneID values.
```

This would allow authors to rename chapters and scenes without breaking sync.

---

## Scene Writing Brief

The add-in should display the current scene writing brief from PlotDirector.

The brief should be read-only in the first version.

Reason:

- PlotDirector remains the planning source.
- Authors know where to edit planning information.
- It avoids confusion about whether Word or PlotDirector owns the brief.
- It keeps the add-in simple.

The panel should provide:

```text
[Open Scene in PlotDirector]
```

This allows authors to edit the scene brief in the main application when needed.

### Suggested Brief Fields

Depending on the existing PlotDirector model, the side panel may display:

- Scene purpose
- Scene summary
- Writing brief
- Key beats
- Emotional target
- Continuity notes
- Practical blockers
- Blocked reason

The first implementation should display whatever scene brief field already exists, then expand later if needed.

---

## Scene Links

The add-in should allow quick association of the current scene with:

- Characters
- Assets
- Locations

These should be shown as checklists.

### Character Checklist

Displays characters from the current project/book.

Each character item should show:

- Character name
- Existing checked state for current scene

Author actions:

- Tick character to add appearance.
- Untick character to remove appearance.
- Save changes.

### Asset Checklist

Displays assets from the current project/book.

Each asset item should show:

- Asset name
- Existing checked state for current scene

Author actions:

- Tick asset to add scene usage.
- Untick asset to remove scene usage.
- Save changes.

### Location Checklist

Displays locations from the current project/book.

Each location item should show:

- Location name
- Existing checked state for current scene

Author actions:

- Tick location to add scene association.
- Untick location to remove scene association.
- Save changes.

---

## Scene Link Detail Level

The first version should keep associations simple.

For example:

```text
Character appears in scene.
Asset is used or mentioned in scene.
Location is associated with scene.
```

Do not require detailed involvement classification in the Word add-in.

More detailed classification can remain in PlotDirector.

Examples of details that should stay in PlotDirector:

- POV character.
- Present vs mentioned only.
- Active participant vs background.
- Asset owner.
- Asset state.
- Character location state.
- Relationship changes.

The add-in should provide fast capture, not detailed modelling.

---

## API Requirements

The feature requires a small API surface in PlotDirector.

All endpoints must require authentication and must validate project/book access.

The exact route names can be adjusted to match PlotDirector conventions.

---

# API Design

## Authentication

The add-in should authenticate against PlotDirector.

Possible approaches:

1. Existing web login session if hosted under the same domain.
2. OAuth-style flow.
3. Device code flow.
4. Personal access token.
5. Add-in-specific API token.

For MVP, if feasible, use the existing PlotDirector authentication mechanism with secure cookies and HTTPS.

If cookie authentication is awkward inside the Office task pane, introduce add-in tokens.

Recommended long-term approach:

```text
Add-in-specific access tokens scoped to the user and project.
```

Tokens should be revocable from the user’s PlotDirector account page.

---

## Endpoint: Get User Projects

```http
GET /api/word/projects
```

Returns projects available to the signed-in user.

Example response:

```json
{
  "projects": [
    {
      "projectId": 12,
      "title": "The Alpha Flame"
    }
  ]
}
```

---

## Endpoint: Get Project Books

```http
GET /api/word/projects/{projectId}/books
```

Returns books in the selected project.

Example response:

```json
{
  "books": [
    {
      "bookId": 4,
      "title": "The Alpha Flame: Reckoning",
      "sortOrder": 2
    }
  ]
}
```

---

## Endpoint: Get Book Structure

```http
GET /api/word/books/{bookId}/structure
```

Returns chapters and scenes for the selected book.

Example response:

```json
{
  "bookId": 4,
  "chapters": [
    {
      "chapterId": 101,
      "title": "Chapter 1: Echoes of the Past",
      "sortOrder": 1,
      "scenes": [
        {
          "sceneId": 5001,
          "title": "Scene 1: The Memory Tin",
          "sortOrder": 1,
          "revisionStatus": "Outlined",
          "estimatedWords": 1800,
          "actualWords": 0
        }
      ]
    }
  ]
}
```

---

## Endpoint: Get Scene Companion Data

```http
GET /api/word/scenes/{sceneId}/companion
```

Returns everything needed to populate the side panel for one scene.

Example response:

```json
{
  "sceneId": 5001,
  "chapterId": 101,
  "chapterTitle": "Chapter 1: Echoes of the Past",
  "sceneTitle": "Scene 1: The Memory Tin",
  "actualWords": 1248,
  "estimatedWords": 1800,
  "writingBrief": "Beth searches through the memory tin and realises the poem may contain a clue.",
  "blocked": false,
  "blockedReason": null,
  "characters": [
    {
      "characterId": 22,
      "name": "Beth",
      "linked": true
    },
    {
      "characterId": 23,
      "name": "Maggie",
      "linked": false
    }
  ],
  "assets": [
    {
      "assetId": 8,
      "name": "Memory tin",
      "linked": true
    }
  ],
  "locations": [
    {
      "locationId": 5,
      "name": "Grace",
      "linked": true
    }
  ]
}
```

---

## Endpoint: Resolve Scene by Titles

```http
POST /api/word/books/{bookId}/resolve-scene
```

Used when the add-in has chapter and scene titles but not a SceneID.

Request:

```json
{
  "chapterTitle": "Chapter 1: Echoes of the Past",
  "sceneTitle": "Scene 1: The Memory Tin"
}
```

Response:

```json
{
  "matched": true,
  "chapterId": 101,
  "sceneId": 5001,
  "matchType": "ExactTitle"
}
```

If not matched:

```json
{
  "matched": false
}
```

---

## Endpoint: Sync Current Scene

```http
POST /api/word/books/{bookId}/sync-scene
```

Creates or updates one chapter/scene and updates actual word count.

Request:

```json
{
  "chapterTitle": "Chapter 1: Echoes of the Past",
  "chapterSortOrder": 1,
  "sceneTitle": "Scene 1: The Memory Tin",
  "sceneSortOrder": 1,
  "actualWords": 1248,
  "documentId": "word-doc-abc123",
  "contentHash": "optional-hash"
}
```

Response:

```json
{
  "chapterId": 101,
  "sceneId": 5001,
  "chapterCreated": false,
  "sceneCreated": false,
  "actualWordsUpdated": true,
  "message": "Scene synced successfully."
}
```

---

## Endpoint: Sync Full Manuscript Structure

```http
POST /api/word/books/{bookId}/sync-manuscript
```

Creates missing chapters/scenes and updates actual word counts.

Request:

```json
{
  "documentId": "word-doc-abc123",
  "chapters": [
    {
      "title": "Chapter 1: Echoes of the Past",
      "sortOrder": 1,
      "wordCount": 4260,
      "scenes": [
        {
          "title": "Scene 1: The Memory Tin",
          "sortOrder": 1,
          "wordCount": 1800,
          "contentHash": "optional-hash"
        },
        {
          "title": "Scene 2: St Luke's",
          "sortOrder": 2,
          "wordCount": 2460,
          "contentHash": "optional-hash"
        }
      ]
    }
  ]
}
```

Response:

```json
{
  "chaptersCreated": 1,
  "chaptersUpdated": 4,
  "scenesCreated": 3,
  "scenesUpdated": 18,
  "itemsNotMatched": [],
  "message": "Manuscript sync completed."
}
```

---

## Endpoint: Update Scene Links

```http
PUT /api/word/scenes/{sceneId}/links
```

Updates character, asset and location associations for a scene.

Request:

```json
{
  "characterIds": [22, 23],
  "assetIds": [8],
  "locationIds": [5]
}
```

Response:

```json
{
  "sceneId": 5001,
  "charactersUpdated": 2,
  "assetsUpdated": 1,
  "locationsUpdated": 1,
  "message": "Scene links updated."
}
```

The server should treat this as the selected set from the add-in.

If detailed link records exist, the server should preserve fields not controlled by the add-in wherever possible.

---

## Endpoint: Update Scene Word Count

```http
PATCH /api/word/scenes/{sceneId}/word-count
```

Request:

```json
{
  "actualWords": 1248
}
```

Response:

```json
{
  "sceneId": 5001,
  "actualWords": 1248,
  "message": "Word count updated."
}
```

This endpoint may be optional if word count updates are always included in sync calls.

---

## Data Model Changes

The MVP may only require minor database additions.

Suggested additions:

### Scene Sync Metadata

If not already present, add fields to scenes:

```text
ActualWords
LastSyncedFromWordUtc
WordDocumentId
WordContentHash
```

Some of these may already exist in PlotDirector.

If so, reuse existing fields.

### Add-in Connection / Token Table

If API tokens are used:

```text
UserWordAddInTokens
```

Suggested fields:

```text
TokenID
UserID
TokenHash
CreatedUtc
LastUsedUtc
RevokedUtc
DeviceName
```

Do not store raw tokens.

### Sync History

Optional but useful:

```text
WordSyncHistory
```

Suggested fields:

```text
SyncHistoryID
UserID
ProjectID
BookID
DocumentID
SyncType
StartedUtc
CompletedUtc
ChaptersCreated
ChaptersUpdated
ScenesCreated
ScenesUpdated
WordCountsUpdated
ErrorMessage
```

This helps with diagnostics.

---

## Stored Procedures

Depending on existing PlotDirector conventions, add or update stored procedures for:

- Getting user projects available to the add-in.
- Getting project books.
- Getting book structure.
- Resolving a chapter/scene by title.
- Creating a missing chapter.
- Creating a missing scene.
- Updating scene actual word count.
- Updating scene sync metadata.
- Getting scene companion data.
- Updating scene character links.
- Updating scene asset links.
- Updating scene location links.
- Inserting sync history.

All database changes should follow the established migration policy:

- Do not modify committed migration scripts.
- Add new migration scripts.
- Stored procedure changes should use `ALTER PROCEDURE`.
- Seed data must be idempotent.
- New installations run all migrations in order.
- Existing installations run only new migrations.

---

## Security Considerations

### Authentication

All API endpoints must require authentication.

The add-in must never expose unrestricted project or book data.

### Authorisation

Each endpoint must verify:

- The authenticated user has access to the project.
- The selected book belongs to a project the user can access.
- The requested scene belongs to that book/project.
- The requested character/asset/location IDs belong to the same project or valid scope.

### HTTPS

The add-in and API should run over HTTPS.

Office add-ins generally require secure origins.

### CSRF

If cookie authentication is used, CSRF protection must be handled properly.

For API token authentication, CSRF risk is reduced, but token storage becomes important.

### Token Storage

If the add-in uses tokens:

- Store tokens securely.
- Store only token hashes server-side.
- Allow users to revoke tokens.
- Scope tokens to the authenticated user.
- Consider scoping tokens to specific projects later.

### Data Protection

The add-in should not upload full manuscript text in the MVP.

It should upload:

- Chapter titles.
- Scene titles.
- Word counts.
- Optional content hashes.

This avoids privacy concerns and keeps sync lightweight.

---

## Performance Considerations

The add-in should feel quick.

Avoid:

- Full manuscript parsing on every cursor move.
- Heavy document reads during selection change events.
- Fuzzy matching inside Word.
- Entity detection inside Word.
- Large API calls during typing.
- Blocking modal workflows.

Recommended approach:

- Use explicit sync buttons.
- Use debounced current scene detection.
- Cache project/book lists in the task pane.
- Cache character/asset/location lists for the selected book/project.
- Fetch scene companion data only when the current scene changes.
- Keep Office.js calls small and deliberate.
- Perform heavier matching and validation server-side.

The side panel should behave like a lightweight helper, not a background process constantly inspecting the document.

---

## Error Handling

The add-in should show clear, concise messages.

Examples:

```text
Could not detect a scene. Use Heading 2 for scene titles.
```

```text
You are not connected to PlotDirector.
```

```text
This book could not be found.
```

```text
Sync failed. Please try again.
```

```text
Scene links saved.
```

For detailed errors, use a collapsible diagnostics section or developer log mode.

Do not expose raw stack traces to users.

---

## UX Rules

The add-in should follow these rules:

1. Do not interrupt the author while typing.
2. Do not show large modal workflows during writing.
3. Do not ask users to confirm every minor update.
4. Do not delete planning data.
5. Do not silently overwrite scene briefs.
6. Do not duplicate full PlotDirector pages inside Word.
7. Keep the panel narrow and readable.
8. Prefer checklists and single-click actions.
9. Show a clear last sync time.
10. Provide links back to PlotDirector for deeper editing.

---

## Suggested Implementation Phases

## Phase W1 – API Foundation

Build the PlotDirector API required by the add-in.

Deliverables:

- Authenticated API area for Word Companion.
- Get projects endpoint.
- Get books endpoint.
- Get book structure endpoint.
- Resolve scene by title endpoint.
- Get scene companion data endpoint.
- Sync current scene endpoint.
- Sync full manuscript endpoint.
- Update scene links endpoint.
- Optional word count endpoint.
- Database changes for sync metadata if needed.
- Sync history table if desired.

Testing:

- Verify unauthorised access is rejected.
- Verify users cannot access another user’s projects.
- Verify chapters/scenes are created only when missing.
- Verify existing PlotDirector-only scenes are not deleted.
- Verify word counts update correctly.
- Verify scene links update correctly.

---

## Phase W2 – Add-in Shell

Create the Word add-in project and basic task pane.

Deliverables:

- Office add-in manifest.
- Task pane UI shell.
- PlotDirector connection screen.
- Project selector.
- Book selector.
- Stored selected project/book in add-in state.
- Basic API connectivity test.
- Friendly connection status.

Testing:

- Add-in loads in Word.
- User can connect to PlotDirector.
- User can select project and book.
- API failures are handled cleanly.

---

## Phase W3 – Document Structure Detection

Add Office.js document reading.

Deliverables:

- Detect Heading 1 chapters.
- Detect Heading 2 scenes.
- Detect current chapter/scene from cursor position.
- Display current chapter and scene in the panel.
- Calculate current scene word count.
- Manual refresh button.

Testing:

- Works with normal chapter/scene headings.
- Handles cursor outside any scene.
- Handles missing Heading 1.
- Handles missing Heading 2.
- Handles empty scenes.
- Performs acceptably on long manuscripts.

---

## Phase W4 – Current Scene Companion Panel

Connect detected scene to PlotDirector.

Deliverables:

- Resolve detected chapter/scene to PlotDirector IDs.
- Display scene writing brief.
- Display estimated and actual words.
- Display blocked status and blocked reason if useful.
- Provide **Open Scene in PlotDirector** link.
- Provide **Sync Current Scene** button.

Testing:

- Existing scenes resolve correctly.
- Missing scenes can be created through sync.
- Word count updates correctly.
- Brief displays read-only.
- Link opens correct PlotDirector page.

---

## Phase W5 – Scene Links

Add character, asset and location checklists.

Deliverables:

- Fetch characters for current project/book.
- Fetch assets for current project/book.
- Fetch locations for current project/book.
- Display checked state for current scene.
- Save selected links back to PlotDirector.
- Show success/failure message.

Testing:

- Existing scene links load correctly.
- Ticking a character creates the appearance/link.
- Unticking removes the appearance/link.
- Asset links update correctly.
- Location links update correctly.
- Invalid IDs are rejected server-side.

---

## Phase W6 – Full Manuscript Sync

Allow the author to sync the full document structure.

Deliverables:

- Read all Heading 1 chapters.
- Read all Heading 2 scenes.
- Count words.
- Send full structure to PlotDirector.
- Create missing chapters.
- Create missing scenes.
- Update word counts.
- Show sync summary.

Testing:

- Creates missing chapters.
- Creates missing scenes.
- Does not delete existing PlotDirector-only scenes.
- Updates word counts.
- Handles duplicate heading names gracefully.
- Handles long manuscripts without freezing Word noticeably.

---

## Phase W7 – Refinement and Hardening

Polish the feature for real usage.

Deliverables:

- Better loading states.
- Better error handling.
- Caching project/book/entity lists.
- Last sync status.
- Sync history view in PlotDirector.
- User-facing documentation.
- Developer diagnostics mode.
- Add-in token revocation if tokens are used.
- Deployment packaging.

Testing:

- Test against several real manuscripts.
- Test poor network behaviour.
- Test expired authentication.
- Test large book documents.
- Test duplicate chapter/scene titles.
- Test renamed scenes.
- Test copy/pasted chapters.

---

## Future Enhancements

Possible later additions:

- Stable hidden chapter/scene IDs inside Word.
- Optional editing of scene brief from Word.
- Optional quick notes from Word.
- Optional manuscript text analysis.
- Suggested character/asset/location links.
- Continuity warning suggestions.
- Writing schedule progress integration.
- Sync of selected scene only on save.
- Multi-document book support.
- Scrivener or Google Docs integration.
- Add-in marketplace publication.

These should not be included until the lightweight companion workflow has proven useful.

---

## Recommended MVP Scope

The recommended MVP is:

1. Side panel loads in Word.
2. User connects to PlotDirector.
3. User selects project and book.
4. Add-in detects current chapter and scene using headings.
5. Add-in displays read-only scene writing brief.
6. Add-in displays character, asset and location checklists.
7. User can save scene links.
8. User can sync current scene word count.
9. User can sync all chapters/scenes.
10. PlotDirector creates missing chapters/scenes but deletes nothing.

This gives immediate practical value while keeping the feature focused.

---

## Summary

The Microsoft Word Companion Add-in should make PlotDirector feel closer to the writing process without moving PlotDirector’s planning responsibilities into Word.

The add-in should be:

- Lightweight.
- Fast.
- Focused.
- Safe.
- Side-by-side with the manuscript.
- Useful during drafting.

The API should provide a secure and narrow bridge between Word and PlotDirector.

The first version should focus on:

- Scene brief visibility.
- Chapter/scene sync.
- Word count sync.
- Character/asset/location association.

The central rule is:

> **The add-in helps the author write. PlotDirector remains the source of planning truth.**
