# Story Intelligence Architecture

## Purpose

Story Intelligence is the optional AI-assisted pipeline that turns a manuscript into a structured Story Model for PlotDirector.

The system helps an author understand the story already present in the manuscript. It observes, organises and suggests. It does not critique, rewrite, judge scene quality or take control away from the author.

This document describes the intended processing architecture. It is design documentation only.

## Pipeline

```text
Word document

-> Scene Scanner

-> Scene Intelligence

-> Character Intelligence

-> Relationship Intelligence

-> Location Intelligence

-> Asset Intelligence

-> Knowledge Engine

-> Thread Detection

-> Continuity Engine

-> Reports
```

## Stage 1: Word Document

The Word document is the author's manuscript source.

Purpose:

- Preserve the manuscript as the source of truth.
- Provide raw scene text, document structure and document metadata.
- Carry hidden manuscript markers once PlotDirector links chapters and scenes back to the document.

Notes:

- The Word Companion acts as a scanner and synchronisation agent.
- The website remains the user-facing onboarding controller.
- AI analysis is optional and requires explicit user consent.

## Stage 2: Scene Scanner

The Scene Scanner identifies manuscript structure before AI analysis begins.

Purpose:

- Detect chapters.
- Detect scenes.
- Count words.
- Identify candidate character names.
- Preserve document and scene references.
- Produce scene-sized text units for later analysis.

Output:

- Project, book, chapter and scene references.
- Scene text boundaries.
- Initial chapter and scene metadata.
- Candidate names for user review.

Why this comes first:

- Scene Intelligence needs reliable scene boundaries.
- Later stages should work from structured scene units rather than an entire manuscript blob.

## Stage 3: Scene Intelligence

Scene Intelligence analyses one scene at a time.

Purpose:

- Summarise the scene neutrally.
- Identify present and mentioned-only characters.
- Identify named locations and generic rooms.
- Identify meaningful story assets.
- Capture timeline clues.
- Capture recipient-focused knowledge changes.
- Capture questions raised and answered.
- Capture scene-local relationship signals.
- Record entity-mappable observations.
- Record descriptive 1-10 scene metrics.

Output:

- Scene Intelligence JSON using `Scene-Intelligence-Schema-V1`.

Important boundaries:

- Scene Intelligence does not create final canon.
- Scene Intelligence does not output direct plot thread records.
- Scene Intelligence does not output direct continuity warnings.
- Scene Intelligence produces structured observations and evidence-backed signals for later stages.

Why scene-level analysis:

- Scenes are the natural unit of story action.
- Smaller inputs reduce hallucination risk.
- Scene-local outputs are easier to audit.
- Later stages can aggregate structured facts instead of repeatedly reading prose.

## Stage 4: Character Intelligence

Character Intelligence consumes Scene Intelligence results across scenes.

Purpose:

- Consolidate character mentions.
- Separate active appearances from mentioned-only references.
- Build character profiles from observed actions, knowledge changes and relationship signals.
- Identify aliases where supported.
- Track character knowledge over time.

Input:

- Scene character arrays.
- Knowledge changes.
- Relationship signals.
- Entity-mappable observations.
- Timeline clues.

Output:

- Candidate character profiles.
- Appearance history.
- Mention history.
- Knowledge history.
- Confidence-backed character observations.

Why it consumes structured scene data:

- The scene stage already extracts who appears, who is mentioned and what each character factually does.
- Character Intelligence can focus on consolidation and longitudinal patterns instead of re-reading every scene.

## Stage 5: Relationship Intelligence

Relationship Intelligence builds relationship understanding from character interactions and signals.

Purpose:

- Identify relationships between characters.
- Track relationship changes across scenes.
- Preserve uncertainty.
- Distinguish one-scene signals from durable relationships.

Input:

- Scene-local relationship signals.
- Character co-presence.
- Dialogue and action summaries.
- Character knowledge changes.
- Entity-mappable observations.

Output:

- Candidate relationship records.
- Relationship evolution notes.
- Confidence-backed relationship observations.

Why it follows Character Intelligence:

- Relationships require stable character identities.
- Alias and mentioned-only handling should be settled before relationship consolidation.

## Stage 6: Location Intelligence

Location Intelligence builds the location model.

Purpose:

- Consolidate named locations.
- Avoid turning every generic room into a canonical location.
- Track which scenes occur in each location.
- Capture supported parent or containing location hints.
- Capture important location observations.

Input:

- Scene setting objects.
- Scene location arrays.
- Generic room classifications.
- Location observations.

Output:

- Candidate named locations.
- Scene-location links.
- Generic room groupings where useful.
- Location notes and confidence values.

Why it follows Scene Intelligence:

- Scene Intelligence separates named places from generic rooms at source.
- Location Intelligence can aggregate without overcreating top-level locations.

## Stage 7: Asset Intelligence

Asset Intelligence identifies meaningful story objects.

Purpose:

- Consolidate important documents, weapons, tools, vehicles and other story assets.
- Track asset status changes.
- Track ownership, possession or relevance where supported.
- Avoid ordinary prop inflation.

Input:

- Scene asset arrays.
- Asset interaction observations.
- Scene summaries.
- Questions raised and answered.
- Timeline clues.

Output:

- Candidate asset records.
- Asset appearance history.
- Asset status history.
- Confidence-backed asset notes.

Why it follows Scene Intelligence:

- Scene Intelligence filters ordinary props from meaningful story objects.
- Asset Intelligence can focus on recurring significance and status changes.

## Stage 8: Knowledge Engine

The Knowledge Engine models who knows what and when.

Purpose:

- Track character-specific knowledge.
- Distinguish reader knowledge from character knowledge.
- Track confirms, suspicions and misunderstandings.
- Support later continuity checks involving secrets, reveals and misunderstandings.

Input:

- Recipient-focused scene knowledge changes.
- Questions answered.
- Character appearances.
- Timeline clues.
- Knowledge observations.

Output:

- Character knowledge timeline.
- Reveal history.
- Misunderstanding history.
- Knowledge facts available to later continuity processing.

Why it comes after character and scene stages:

- Knowledge requires stable character identities.
- Scene-level knowledge changes provide structured evidence without re-reading prose.

## Stage 9: Thread Detection

Thread Detection identifies ongoing story questions, problems and movements across scenes.

Purpose:

- Derive thread candidates from structured scene data.
- Track questions raised and answered.
- Detect introduced, advanced, complicated, resolved and referenced story movements.
- Prepare author-reviewable thread candidates.

Input:

- Scene summaries.
- Questions raised.
- Questions answered.
- Timeline clues.
- Knowledge changes.
- Relationship signals.
- Asset records and observations.
- Entity-mappable observations.

Output:

- Candidate plot threads.
- Thread event history.
- Open questions.
- Resolved questions.

Why this is separate from Scene Intelligence:

- Threads span scenes.
- One scene can provide thread evidence, but it should not create final thread records.
- Thread Detection can compare structured evidence across the manuscript instead of relying on isolated scene-level guesses.

## Stage 10: Continuity Engine

The Continuity Engine identifies possible story consistency issues for author review.

Purpose:

- Derive possible contradictions.
- Derive timeline conflicts.
- Derive knowledge inconsistencies.
- Derive relationship or asset continuity concerns.
- Produce review flags, not criticism.

Input:

- Character Intelligence output.
- Relationship Intelligence output.
- Location Intelligence output.
- Asset Intelligence output.
- Knowledge Engine output.
- Thread Detection output.
- Scene timeline clues.
- Source ambiguity notes.

Output:

- Possible continuity warnings.
- Confidence values.
- Evidence references.
- Author-reviewable status.

Why this is separate from Scene Intelligence:

- Continuity concerns require cross-scene comparison.
- Scene Intelligence may record ambiguity in `sourceLimits`, but it does not create continuity warnings directly.
- Running continuity too early would force repeated manuscript analysis and increase hallucination risk.

## Stage 11: Reports

Reports present the structured Story Model to the author.

Purpose:

- Summarise what PlotDirector observed.
- Show characters, relationships, locations, assets, threads and continuity review flags.
- Provide review workflows.
- Keep the author in control of acceptance, editing and rejection.

Input:

- All prior structured outputs.

Output:

- Author-facing reports.
- Review queues.
- Dashboard summaries.
- Exportable story intelligence views.

## Why Progressive Structured Data Matters

The pipeline intentionally consumes progressively smaller structured data rather than repeatedly analysing the manuscript.

Reasons:

- Reduces hallucination risk by narrowing each stage's task.
- Improves auditability because each claim can trace back to scene-level evidence.
- Reduces repeated processing of the same prose.
- Allows author review at meaningful boundaries.
- Lets later stages improve without changing the scanner.
- Supports incremental re-analysis when only some scenes change.
- Keeps the AI role as archivist rather than free-form critic.

The manuscript remains the source of truth, but each stage should use the most structured reliable input available.

## Prompt Loading and Versioning

Story Intelligence prompts are versioned Markdown assets loaded from `/Docs/AI/` at runtime. Prompt text should not be embedded directly in C# services. Each analysis result must record the prompt version and model used so generated data remains auditable, reproducible and regenerable. New prompt versions should be introduced as new files, such as `Scene-Prompt-V2.md`, rather than silently changing the behaviour of existing analysis records.

Prompts are treated as versioned application assets. This allows prompt improvements without recompiling application code while preserving the historical behaviour used for earlier analysis records.

## Consent and Control

Story Intelligence is optional.

No manuscript analysis should run without explicit user consent.

The author should be able to:

- start analysis deliberately;
- monitor progress;
- cancel where supported;
- review generated suggestions;
- accept, edit or ignore outputs.

## Non-Goals

Story Intelligence does not:

- rewrite manuscript prose;
- critique writing quality;
- score author ability;
- replace author judgment;
- make automatic story changes without review;
- treat AI suggestions as canonical without author approval.
