PlotDirector/PlotLine/Docs/AI/Scene-Intelligence-Schema-V1.md

# Scene Intelligence Schema V1

## Purpose

This document defines the JSON object returned by the Scene Intelligence engine for one manuscript scene.

Scene Intelligence is an observation and database-population stage. It observes, organises and suggests factual story signals from a single scene so later PlotDirector stages can build character, relationship, location, asset, knowledge, thread and continuity models.

The AI is an assistant archivist. It never critiques, rewrites, judges scene quality, creates final canon or performs cross-scene continuity analysis.

## Output Contract

The engine must return one valid JSON object and no prose outside the JSON.

All arrays must be present, even when empty. Optional scalar properties must be `null` when unsupported by the supplied scene. The model must not invent missing identifiers, motives, locations, assets, chronology or outcomes.

Confidence values use a decimal number from `0.0` to `1.0`:

- `0.90` to `1.00`: directly stated or strongly explicit in the scene.
- `0.70` to `0.89`: strongly implied by the scene.
- `0.40` to `0.69`: plausible but uncertain.
- below `0.40`: normally omit the item.

Metrics use descriptive intensity scores from `1` to `10`. They are not quality ratings.

## Root Object

```json
{
  "schemaVersion": "1.0",
  "sceneReference": {
    "projectId": 12,
    "bookId": 34,
    "chapterId": 56,
    "sceneId": 78,
    "chapterNumber": 4,
    "sceneNumber": 2,
    "sourceLabel": "Chapter 4, Scene 2"
  },
  "summary": {
    "short": "Mara confronts Elias about the missing ledger.",
    "detailed": "Mara finds Elias in the archive and asks why the ledger vanished after the council meeting. Elias avoids naming who took it, but confirms the theft changes their route north.",
    "confidence": 0.92
  },
  "scenePurpose": {
    "observedFunction": "Reveals the missing ledger and changes the characters' immediate situation.",
    "confidence": 0.82
  },
  "pointOfView": {
    "characterName": "Mara",
    "narrativeMode": "third person limited",
    "confidence": 0.88,
    "evidence": "The narration reports Mara's perceptions but not Elias's internal thoughts."
  },
  "setting": {
    "timeOfDay": "night",
    "dateOrTimeReference": null,
    "locationName": "Archive Hall",
    "locationType": "named",
    "genericRoomType": "archive",
    "parentLocationHint": null,
    "confidence": 0.86
  },
  "characters": [],
  "locations": [],
  "assets": [],
  "relationships": [],
  "knowledgeChanges": [],
  "timelineClues": [],
  "questionsRaised": [],
  "questionsAnswered": [],
  "observations": [],
  "metrics": {},
  "sourceLimits": {
    "containsAmbiguity": false,
    "ambiguityNotes": []
  }
}
```

The root object must not include scene-level thread candidates or continuity warning objects. Thread Detection and the Continuity Engine derive those later from structured Scene Intelligence output.

## Property Reference

### `schemaVersion`

- Purpose: Identifies the Scene Intelligence schema version.
- Data type: string.
- Required: yes.
- Confidence usage: none.
- Example: `"1.0"`.
- Notes: Must remain stable for this schema generation.

### `sceneReference`

- Purpose: Carries application-provided scene identity for later persistence and audit.
- Data type: object.
- Required: yes.
- Confidence usage: none; these values come from PlotDirector, not AI inference.
- Example: see root example.
- Notes: Copy supplied identifiers exactly. Do not infer missing identifiers.

#### `sceneReference.projectId`

- Purpose: Project identifier supplied by PlotDirector.
- Data type: integer or null.
- Required: yes.
- Confidence usage: none.
- Example: `12`.
- Notes: May be null in test fixtures before database identifiers are assigned.

#### `sceneReference.bookId`

- Purpose: Book identifier supplied by PlotDirector.
- Data type: integer or null.
- Required: yes.
- Confidence usage: none.
- Example: `34`.
- Notes: Must not be inferred from manuscript text.

#### `sceneReference.chapterId`

- Purpose: Chapter identifier supplied by PlotDirector.
- Data type: integer or null.
- Required: yes.
- Confidence usage: none.
- Example: `56`.
- Notes: Must not be inferred.

#### `sceneReference.sceneId`

- Purpose: Scene identifier supplied by PlotDirector.
- Data type: integer or null.
- Required: yes.
- Confidence usage: none.
- Example: `78`.
- Notes: Must not be inferred.

#### `sceneReference.chapterNumber`

- Purpose: Human-readable chapter number supplied by the scanner or application.
- Data type: number or null.
- Required: yes.
- Confidence usage: none.
- Example: `4`.
- Notes: Decimal chapter numbers are allowed if PlotDirector uses them.

#### `sceneReference.sceneNumber`

- Purpose: Human-readable scene number within the chapter.
- Data type: number or null.
- Required: yes.
- Confidence usage: none.
- Example: `2`.
- Notes: Decimal scene numbers are allowed if PlotDirector uses them.

#### `sceneReference.sourceLabel`

- Purpose: Display label for audit and review.
- Data type: string.
- Required: yes.
- Confidence usage: none.
- Example: `"Chapter 4, Scene 2"`.
- Notes: Copy from supplied context when available.

### `summary`

- Purpose: Describes what happens in the scene without critique or rewrite advice.
- Data type: object.
- Required: yes.
- Confidence usage: `confidence` applies to accuracy against the supplied scene text.
- Example: see root example.
- Notes: Summaries should be neutral, concise and factual. They should not judge pacing, prose, structure or quality.

#### `summary.short`

- Purpose: One-sentence operational summary for lists and dashboards.
- Data type: string.
- Required: yes.
- Confidence usage: covered by `summary.confidence`.
- Example: `"Mara confronts Elias about the missing ledger."`
- Notes: Usually 12 to 30 words.

#### `summary.detailed`

- Purpose: Fuller scene account for downstream structured processing.
- Data type: string.
- Required: yes.
- Confidence usage: covered by `summary.confidence`.
- Example: `"Mara finds Elias in the archive..."`
- Notes: Preserve uncertainty. Do not add motives, causes or outcomes not supported by the scene.

#### `summary.confidence`

- Purpose: Indicates how directly the scene supports the generated summary.
- Data type: number from `0.0` to `1.0`.
- Required: yes.
- Confidence usage: this is the confidence value.
- Example: `0.92`.
- Notes: Lower confidence for fragmentary, abstract or heavily ambiguous scenes.

### `scenePurpose`

- Purpose: Captures the observed function of the scene in neutral terms.
- Data type: object.
- Required: yes.
- Confidence usage: `confidence` reflects how clearly the function is supported.
- Example:

```json
{
  "observedFunction": "Introduces the missing ledger and changes the immediate situation.",
  "confidence": 0.82
}
```

- Notes: This is descriptive, not evaluative. Avoid author instructions or critique.

### `pointOfView`

- Purpose: Records apparent point-of-view information.
- Data type: object.
- Required: yes.
- Confidence usage: confidence reflects support from narration and internal access.
- Example:

```json
{
  "characterName": "Mara",
  "narrativeMode": "third person limited",
  "confidence": 0.88,
  "evidence": "The narration reports Mara's perceptions."
}
```

- Notes: If unclear, use null for `characterName` and lower confidence.

### `setting`

- Purpose: Records scene-level time and place signals.
- Data type: object.
- Required: yes.
- Confidence usage: confidence reflects how explicitly the setting is supported.
- Example: see root example.
- Notes: Detailed location candidates also appear in `locations`.

#### `setting.timeOfDay`

- Purpose: Broad time-of-day cue.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"night"`.
- Notes: Use null if not stated or strongly implied.

#### `setting.dateOrTimeReference`

- Purpose: Explicit chronology text.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"three days after the coronation"`.
- Notes: Preserve manuscript wording where practical.

#### `setting.locationName`

- Purpose: Primary named location when present.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"Archive Hall"`.
- Notes: Do not convert generic rooms into named locations.

#### `setting.locationType`

- Purpose: Distinguishes named locations from generic spaces.
- Data type: string enum: `"named"`, `"generic"`, `"unclear"`.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"named"`.
- Notes: A kitchen is generic unless the manuscript identifies it as a specific named place.

#### `setting.genericRoomType`

- Purpose: Generic room or place type when useful.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"archive"`.
- Notes: Required when `locationType` is `"generic"` and the room type is supported.

#### `setting.parentLocationHint`

- Purpose: Supported parent or containing place hint.
- Data type: string or null.
- Required: yes.
- Confidence usage: covered by `setting.confidence`.
- Example: `"Royal Library"`.
- Notes: Use only when the scene supports it. Do not invent hierarchy.

#### `setting.confidence`

- Purpose: Confidence in the scene-level setting summary.
- Data type: number from `0.0` to `1.0`.
- Required: yes.
- Confidence usage: this is the confidence value.
- Example: `0.86`.
- Notes: Lower when inferred from context only.

### `characters`

- Purpose: Lists characters present, active, mentioned or otherwise scene-relevant.
- Data type: array of character objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:

```json
[
  {
    "name": "Mara",
    "roleInScene": "pointOfView",
    "mentionedOnly": false,
    "aliases": [],
    "actions": ["questions Elias about the missing ledger"],
    "confidence": 0.91,
    "notes": "Point-of-view character."
  }
]
```

- Notes: Mentioned-only characters must use `mentionedOnly: true` and `roleInScene: "mentioned"`.

#### Character object properties

- `name`
  - Purpose: Character name or label from the manuscript.
  - Data type: string.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Mara"`.
  - Notes: Use the manuscript's name. Do not merge aliases unless identity is clear in the scene.
- `roleInScene`
  - Purpose: Indicates how the character participates.
  - Data type: string enum: `"present"`, `"pointOfView"`, `"speaker"`, `"mentioned"`, `"unclear"`.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"pointOfView"`.
  - Notes: Use the most specific applicable role.
- `mentionedOnly`
  - Purpose: Separates absent references from active scene participants.
  - Data type: boolean.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `true`.
  - Notes: True when the character is absent and only referred to.
- `aliases`
  - Purpose: Names or titles used for the same character in this scene.
  - Data type: array of strings.
  - Required: yes.
  - Confidence usage: include only clearly supported aliases.
  - Example: `["the captain"]`.
  - Notes: Do not infer aliases across scenes at this stage.
- `actions`
  - Purpose: Factual actions taken in the scene.
  - Data type: array of strings.
  - Required: yes.
  - Confidence usage: include only supported actions.
  - Example: `["hides the letter"]`.
  - Notes: Keep each action concise. Do not include inferred motives.
- `confidence`
  - Purpose: Confidence in the character item.
  - Data type: number from `0.0` to `1.0`.
  - Required: yes.
  - Confidence usage: this is the confidence value.
  - Example: `0.91`.
  - Notes: Lower for ambiguous names, pronoun-only references or unclear presence.
- `notes`
  - Purpose: Short neutral note about scene relevance.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: should reflect item support.
  - Example: `"Mentioned as the previous owner of the ledger."`
  - Notes: No critique or advice.

### `locations`

- Purpose: Lists named locations and meaningful generic places referenced by the scene.
- Data type: array of location objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:

```json
[
  {
    "name": "Archive Hall",
    "locationType": "named",
    "genericRoomType": "archive",
    "parentLocationHint": null,
    "presentInScene": true,
    "mentionedOnly": false,
    "confidence": 0.9,
    "notes": "Primary scene location."
  }
]
```

- Notes: Generic rooms must not become top-level canonical locations. Named locations may later become Location records.

#### Location object properties

- `name`
  - Purpose: Location name or generic label.
  - Data type: string.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Archive Hall"`.
  - Notes: Use `"kitchen"` or `"bedroom"` only as generic labels when unnamed.
- `locationType`
  - Purpose: Indicates whether the location is named or generic.
  - Data type: string enum: `"named"`, `"generic"`, `"unclear"`.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"generic"`.
  - Notes: Named locations are candidates for later Location Intelligence.
- `genericRoomType`
  - Purpose: Normalised generic room or place type.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"kitchen"`.
  - Notes: Should be present for generic rooms when supported.
- `parentLocationHint`
  - Purpose: Supported parent or containing location.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Manor House"`.
  - Notes: Use only when the scene supports it.
- `presentInScene`
  - Purpose: Indicates that scene action occurs there.
  - Data type: boolean.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `true`.
  - Notes: False for locations only discussed.
- `mentionedOnly`
  - Purpose: Indicates an absent location reference.
  - Data type: boolean.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `false`.
  - Notes: Usually true when `presentInScene` is false.
- `confidence`
  - Purpose: Confidence in location identification.
  - Data type: number from `0.0` to `1.0`.
  - Required: yes.
  - Confidence usage: this is the confidence value.
  - Example: `0.9`.
  - Notes: Lower for implied or ambiguous place references.
- `notes`
  - Purpose: Neutral location note.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: should match support level.
  - Example: `"Mentioned as the next destination."`
  - Notes: Do not invent worldbuilding.

### `assets`

- Purpose: Lists meaningful story objects, documents, weapons, tools, vehicles or other assets.
- Data type: array of asset objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:

```json
[
  {
    "name": "missing ledger",
    "assetType": "document",
    "status": "missing",
    "ownerOrHolder": null,
    "mentionedOnly": false,
    "confidence": 0.89,
    "notes": "The scene turns on its disappearance."
  }
]
```

- Notes: Do not list ordinary props unless they have story relevance.

#### Asset object properties

- `name`
  - Purpose: Asset name or label.
  - Data type: string.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"missing ledger"`.
  - Notes: Use manuscript wording where possible.
- `assetType`
  - Purpose: Broad asset category.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"document"`.
  - Notes: Keep simple and descriptive.
- `status`
  - Purpose: Scene-supported state of the asset.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"missing"`.
  - Notes: Use null if no meaningful status is supported.
- `ownerOrHolder`
  - Purpose: Character or group currently owning, holding or controlling the asset.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Elias"`.
  - Notes: Use null if unsupported.
- `mentionedOnly`
  - Purpose: Indicates whether the asset is only referred to and not physically present.
  - Data type: boolean.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `false`.
  - Notes: Helps later Asset Intelligence separate present objects from references.
- `confidence`
  - Purpose: Confidence in asset identification.
  - Data type: number from `0.0` to `1.0`.
  - Required: yes.
  - Confidence usage: this is the confidence value.
  - Example: `0.89`.
  - Notes: Lower for unclear object significance.
- `notes`
  - Purpose: Neutral note about asset relevance.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: should match item support.
  - Example: `"Discussed as stolen after the council meeting."`
  - Notes: No speculation beyond scene evidence.

### `relationships`

- Purpose: Captures scene-local relationship signals between characters.
- Data type: array of relationship signal objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:

```json
[
  {
    "characterA": "Mara",
    "characterB": "Elias",
    "relationshipSignal": "mistrust",
    "evidence": "Mara questions Elias about what he is hiding.",
    "confidence": 0.78
  }
]
```

- Notes: These are evidence-backed scene-local signals, not final relationship records. Neutral signal terms include `trust`, `mistrust`, `affection`, `fear`, `authority`, `secrecy`, `conflict`, `dependence`, `protection`, `rivalry` and `obligation`.

### `knowledgeChanges`

- Purpose: Records when a character gains, confirms, suspects or misunderstands knowledge during this scene.
- Data type: array of knowledge change objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:

```json
[
  {
    "recipientCharacter": "Mara",
    "knowledgeItem": "The ledger was taken after the council meeting.",
    "changeType": "IsTold",
    "sourceCharacter": "Elias",
    "sourceType": "dialogue",
    "evidence": "Elias says it vanished after the council adjourned.",
    "confidence": 0.88
  }
]
```

- Notes: Do not use this for information the reader learns but no character learns. Do not assume a character did not know something before unless the scene supports that.

#### Knowledge change object properties

- `recipientCharacter`
  - Purpose: Character receiving, confirming, suspecting or misunderstanding the knowledge.
  - Data type: string.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Mara"`.
  - Notes: Must be a character supported by the scene.
- `knowledgeItem`
  - Purpose: The knowledge gained or changed.
  - Data type: string.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"The ledger was taken after the council meeting."`
  - Notes: State the knowledge neutrally.
- `changeType`
  - Purpose: Type of knowledge change.
  - Data type: string enum: `"Learns"`, `"Realises"`, `"IsTold"`, `"Discovers"`, `"Confirms"`, `"Suspects"`, `"Misunderstands"`.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"IsTold"`.
  - Notes: Choose the most specific supported value.
- `sourceCharacter`
  - Purpose: Character source of the knowledge, if any.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Elias"`.
  - Notes: Null for discovery, narration or unclear source.
- `sourceType`
  - Purpose: How the knowledge reaches the recipient.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"dialogue"`.
  - Notes: Examples include `"dialogue"`, `"observation"`, `"document"`, `"memory"`, `"deduction"`, `"narration"`.
- `evidence`
  - Purpose: Short evidence note from the scene.
  - Data type: string.
  - Required: yes.
  - Confidence usage: should support item confidence.
  - Example: `"Elias says it vanished after the council adjourned."`
  - Notes: Keep concise; do not quote long passages.
- `confidence`
  - Purpose: Confidence in the knowledge change.
  - Data type: number from `0.0` to `1.0`.
  - Required: yes.
  - Confidence usage: this is the confidence value.
  - Example: `0.88`.
  - Notes: Lower for implied realisations or unclear recipients.

### `timelineClues`

- Purpose: Captures chronology details needed by Timeline and Continuity stages.
- Data type: array of timeline clue objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:

```json
[
  {
    "clue": "The ledger disappeared after the council meeting.",
    "relativeOrder": "after council meeting",
    "absoluteDate": null,
    "evidence": "Elias says it vanished after the council adjourned.",
    "confidence": 0.86
  }
]
```

- Notes: Do not create exact dates from vague references.

### `questionsRaised`

- Purpose: Lists open story questions created or sharpened by the scene.
- Data type: array of question objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:

```json
[
  {
    "question": "Who took the ledger?",
    "scope": "plot",
    "evidence": "The ledger is missing and no culprit is named.",
    "confidence": 0.84
  }
]
```

- Notes: Questions should be story-state questions, not critique questions.

### `questionsAnswered`

- Purpose: Lists scene-supported answers to previously open or scene-local questions.
- Data type: array of answer objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:

```json
[
  {
    "question": "When did the ledger disappear?",
    "answer": "After the council meeting.",
    "evidence": "Elias says it vanished after the council adjourned.",
    "confidence": 0.86
  }
]
```

- Notes: Preserve uncertainty when an answer is partial.

### `observations`

- Purpose: Preserves neutral, entity-mappable factual signals that later stages can map into PlotDirector entities.
- Data type: array of observation objects.
- Required: yes.
- Confidence usage: each item has its own confidence.
- Example:

```json
[
  {
    "observationType": "AssetInteraction",
    "subjectEntityType": "Character",
    "subjectName": "Mara",
    "objectEntityType": "Asset",
    "objectName": "missing ledger",
    "predicate": "asksAbout",
    "description": "Mara questions Elias about the missing ledger.",
    "evidence": "Mara asks why the ledger vanished.",
    "confidence": 0.87
  }
]
```

- Notes: Observations are not final canon. They remain neutral and evidence-backed.

#### Observation object properties

- `observationType`
  - Purpose: Categorises the factual signal for later mapping.
  - Data type: string enum: `"CharacterAction"`, `"CharacterKnowledge"`, `"CharacterLocation"`, `"RelationshipSignal"`, `"AssetInteraction"`, `"LocationSignal"`, `"TimelineSignal"`, `"QuestionSignal"`.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"AssetInteraction"`.
  - Notes: Choose the closest supported category.
- `subjectEntityType`
  - Purpose: Entity type for the subject.
  - Data type: string enum: `"Character"`, `"Location"`, `"Asset"`, `"Knowledge"`, `"Relationship"`, `"Timeline"`, `"Scene"`, `"Unknown"`.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Character"`.
  - Notes: Use PlotDirector concepts where possible.
- `subjectName`
  - Purpose: Name or label of the subject entity.
  - Data type: string.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Mara"`.
  - Notes: Use manuscript wording where possible.
- `objectEntityType`
  - Purpose: Entity type for the object, if the observation has one.
  - Data type: string enum or null: `"Character"`, `"Location"`, `"Asset"`, `"Knowledge"`, `"Relationship"`, `"Timeline"`, `"Scene"`, `"Unknown"`, null.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Asset"`.
  - Notes: Use null when there is no object.
- `objectName`
  - Purpose: Name or label of the object entity, if any.
  - Data type: string or null.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"missing ledger"`.
  - Notes: Use null when there is no object.
- `predicate`
  - Purpose: Short relationship/action phrase connecting subject and object.
  - Data type: string.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"asksAbout"`.
  - Notes: Prefer controlled lowerCamelCase predicate values where possible because they make later mapping and querying easier. Preferred predicates include `speaksTo`, `asksAbout`, `answers`, `reveals`, `learns`, `reads`, `writes`, `finds`, `takes`, `gives`, `carries`, `hides`, `loses`, `travelsTo`, `isPresentAt`, `mentions`, `observes`, `discovers`, `confirms`, `suspects` and `misunderstands`. If none of the preferred predicates fit, use a concise factual predicate. Predicates must remain neutral and evidence-backed.
- `description`
  - Purpose: Human-readable neutral observation.
  - Data type: string.
  - Required: yes.
  - Confidence usage: covered by item `confidence`.
  - Example: `"Mara questions Elias about the missing ledger."`
  - Notes: No critique, rewrite advice or author instruction.
- `evidence`
  - Purpose: Short evidence note from the scene.
  - Data type: string.
  - Required: yes.
  - Confidence usage: should support item confidence.
  - Example: `"Mara asks why the ledger vanished."`
  - Notes: Keep concise.
- `confidence`
  - Purpose: Confidence in the observation.
  - Data type: number from `0.0` to `1.0`.
  - Required: yes.
  - Confidence usage: this is the confidence value.
  - Example: `0.87`.
  - Notes: Lower for implied signals.

### `metrics`

- Purpose: Provides descriptive scene-local intensity scores for later comparison and reporting.
- Data type: object.
- Required: yes.
- Confidence usage: each metric has `score` and `confidence`.
- Example:

```json
{
  "action": { "score": 3, "confidence": 0.76 },
  "emotion": { "score": 6, "confidence": 0.72 },
  "tension": { "score": 8, "confidence": 0.8 },
  "conflict": { "score": 7, "confidence": 0.78 },
  "mystery": { "score": 8, "confidence": 0.84 },
  "romance": { "score": 1, "confidence": 0.68 },
  "humour": { "score": 1, "confidence": 0.7 },
  "revelation": { "score": 9, "confidence": 0.84 },
  "pacingIntensity": { "score": 5, "confidence": 0.62 }
}
```

- Notes: Scores are descriptive intensity values from 1 to 10, not quality ratings. A low score does not mean poor writing.

#### Metric names

Preferred V1 metrics:

- `action`
- `emotion`
- `tension`
- `conflict`
- `mystery`
- `romance`
- `humour`
- `revelation`
- `pacingIntensity`

#### Metric score scale

- `1`: barely present.
- `2`: very low.
- `3`: low.
- `4`: mild.
- `5`: moderate.
- `6`: noticeable.
- `7`: strong.
- `8`: very strong.
- `9`: dominant.
- `10`: defining feature of the scene.

### `sourceLimits`

- Purpose: Records limitations caused by the supplied scene text.
- Data type: object.
- Required: yes.
- Confidence usage: none.
- Example:

```json
{
  "containsAmbiguity": true,
  "ambiguityNotes": ["The scene excerpt begins mid-conversation."]
}
```

- Notes: Use this to preserve uncertainty without producing direct continuity or parsing flags.