Update planning package after Phase 0B

2026-09-01 20:41:23 -04:00
parent ba737de9b4
commit 717670afe0
34 changed files with 2061 additions and 1204 deletions
@@ -1,6 +1,6 @@
 # Adventure Storyteller — Browser UX Specification

-**Status:** Draft v0.1  
+**Status:** v1.0 UX target — selected base is AI-DnD  
 **Purpose:** Define the browser-based user experience for v1, including primary storytelling flow, history controls, campaign management, state inspection, imported knowledge, prompt inspection, and future media extension points.

 ## 1. UX Goal
@@ -1288,39 +1288,38 @@ If a fork contains:

 remove or hide from v1 rather than exposing confusing advanced controls.

-## 94. Candidate Reuse — AI-DnD
+## 94. Selected Base Reuse — AI-DnD

-Evaluate:
- transcript UX,
- alternate take controls,
- Insights/prompt inspection,
- story-tree UI coupling,
- state panels.
+Retain/adapt:
+- React/Vite browser shell,
+- transcript/streaming foundation,
+- alternate-take controls where useful,
+- Insights/prompt inspection concepts,
+- existing story-history controls as the starting point.

-Goal:
- retain strong inspection/rollback behavior,
- simplify RPG-heavy surfaces.
+Production UX must simplify RPG-heavy surfaces and hide branch/tree implementation details behind Undo/Redo/Retry/Save Point behavior.

-## 95. Candidate Reuse — Open Dungeon
+## 95. Reference Reuse — Open Dungeon

-Evaluate:
- main story layout,
- interaction modes,
- Retry/Edit UX,
- image placement,
- visual continuity controls.
+Use as a design reference for:
+- main story reading layout,
+- simple interaction feel,
+- Retry/Edit presentation,
+- inline image placement,
+- visual continuity concepts.

-Goal:
- borrow product feel without adopting destructive history semantics.
+Do not port its destructive history semantics or treat its Next.js UI as a drop-in component source for the React/Vite fork.

-## 96. Candidate Reuse — ai-adventure
+## 96. Reference Reuse — ai-adventure

 Primarily architectural, not UX.

-Potential useful concepts:
+Useful concepts:
 - explicit state transparency,
- checkpoint terminology,
- deterministic operation.
+- checkpoint/head semantics,
+- deterministic operation and auditability.
+
+The browser experience remains owned by the AI-DnD-based application.

 ## 97. V1 Navigation Map

@@ -1463,23 +1462,19 @@ User:
 3. identifies bad source,
 4. disables/corrects it.

-## 103. Phase 0B UX Validation Questions
+## 103. Phase 0B UX Findings Applied

-Codex should answer:
+Phase 0B closed the fork-level UX questions:

-1. Which AI-DnD UI components are reusable without RPG mechanics?
-2. Can its tree/history complexity be hidden behind simple Undo/Retry UX?
-3. How mature is its Insights/context inspector?
-4. Which Open Dungeon components provide a cleaner reading/play experience?
-5. How tightly is Open Dungeon UI coupled to destructive history APIs?
-6. Can its image UI be separated cleanly?
-7. Is a right-side state/context panel practical in the chosen frontend?
-8. Which advanced surfaces can be deferred without losing inspectability?
-9. Can local-only status/model connection be made obvious?
-10. Can campaign/knowledge/export management remain simple enough for a single-user app?
-11. Can the input area reserve a clean extension point for future local STT without coupling microphone/transcription logic to story-state commits?
+- AI-DnD provides the browser shell and prompt/Insights foundation worth retaining.
+- Its tree/history complexity can be hidden behind a simple head-cursor Undo/Redo model.
+- The frontend needs an explicit Redo control and Save Point workflow.
+- RPG-specific presentation must be removed/generalized.
+- Open Dungeon remains the stronger visual reference for a focused story-reading experience and future inline media, but its UI is not directly portable and is coupled to destructive history assumptions.
+- ai-adventure contributes state/checkpoint concepts rather than browser components.
+- the input area should reserve a future local STT affordance, but transcription remains editable draft input and is not implemented in v1.

-## 104. Current Recommendation
+## 104. Selected UX Direction

 Build the browser experience around one uncluttered story screen:

@@ -1497,6 +1492,6 @@ Save Points
 Settings
 ```

-The user should be able to play for an hour without ever seeing a branch graph, database concept, embedding control, or developer diagnostic.
+The user should be able to play for an hour without seeing a branch graph, database concept, embedding control, or developer diagnostic.

-But when something goes wrong, the system should make the underlying state and context inspectable enough to explain and correct it.
+When something goes wrong, the system must make state, provenance, and context inspectable enough to explain and correct it.
@@ -1,163 +1,551 @@
-# Adventure Storyteller — Build Milestones
+# Adventure Storyteller — Production Build Milestones

-**Status:** Placeholder / intentionally incomplete  
-**Do not use for production implementation yet.**
+**Status:** Planning-ready; implementation not yet authorized  
+**Base:** AI-DnD `d72f7c1bda0f34fccd84afb7a25c34eb01c901de`

 ## 1. Purpose

-The detailed production implementation plan will be created at the end of **Phase 0 — Research, Validation & Architecture**.
+This document defines the production implementation sequence after Phase 0.

-A precise plan cannot responsibly be written before the project has selected:
+It is intentionally a milestone plan, **not a Codex execution prompt**. Each milestone should be converted into a separate coding brief only after the previous milestone has been reviewed and accepted.

- the base repository or build strategy,
- the final persistence/story-tree design,
- the final browser architecture,
- the Ollama integration model,
- the memory/retrieval strategy,
- the local-only hardening approach,
- the migration/reuse plan for inherited code.
+The milestone order prioritizes load-bearing correctness and offline safety before broad feature work.

-## 2. Why This Document Is Deliberately Limited
+## 2. Global Rules for Every Milestone

-Different fork choices create fundamentally different engineering work.
+Each implementation milestone must:

-Example:
+- preserve upstream provenance and licensing notices,
+- keep the application runnable whenever practical,
+- add or update automated tests for changed behavior,
+- avoid unrelated refactors,
+- update affected documentation,
+- record schema/migration changes,
+- preserve local-only defaults,
+- stop at the milestone boundary for review,
+- avoid implementing later milestones opportunistically.

-### If Open Dungeon is selected
-Early milestones may require:
+The product specification and acceptance tests outrank convenience inherited from AI-DnD.

- adding immutable story-tree persistence,
- adding branch-aware state restoration,
- introducing structured narrative state,
- adding long-term semantic memory.
+## 3. End-User Capability Progression

-### If AI-DnD is selected
-Early milestones may instead require:
+The application is expected to remain runnable throughout the sequence. **M8 does not create the browser UI from scratch**; AI-DnD already provides a browser interface from M1. M8 is where that inherited/adapted interface is completed and simplified into the intended v1 storyteller experience.

- removing RPG mechanics,
- removing cloud providers,
- removing account/hosted assumptions,
- simplifying world state while preserving story-tree behavior.
+- **M1 — First playable baseline:** The user can open the inherited browser UI, start or resume a story, send prompts to Ollama, receive streamed narration, and persist the story across restart. The interface may still look and behave substantially like AI-DnD, and advanced history/state features are not yet converted to final semantics.
+- **M2 — Clean local storyteller baseline:** Normal story play still works, but cloud/hosted/account/scripting surfaces are removed and Ollama can be either same-host or on an explicitly configured trusted-LAN machine. From the user's perspective this is still basic play, but the environment now matches the intended privacy/deployment model.
+- **M3 — Safe history controls:** The user can play normally with production-grade Undo, Redo, Retry, alternate takes, and divergence without deleting old story history. Export/import also preserves the exact current position even when the user has undone several turns.
+- **M4 — Save Points:** The user can name a point in the story, continue playing, restart, return to that Save Point, and take a different path without losing the later story. This is the first milestone where deliberate long-form experimentation/recovery should feel comfortable.
+- **M5 — Reliable story state:** Characters, locations, possessions, relationships, facts, threads, and current scene become application-owned genre-neutral state rather than RPG-stat machinery. The user can begin inspecting/correcting what the storyteller believes, although the final polished state UI comes later.
+- **M6 — Long-story memory:** The storyteller becomes much better suited to long campaigns because summaries and retrieved older memories remain branch-safe and inspectable. The user should be able to return to old people, promises, clues, and events without abandoned paths contaminating the active story.
+- **M7 — Local knowledge library:** The user can import `.txt`/`.md` material as Canon, Reference, or Inspiration and have it retrieved locally with provenance. The functionality is usable, but some management/inspection surfaces may still be utilitarian until M8.
+- **M8 — Finished v1 browser experience:** The existing browser UI is reorganized and polished around storytelling: streamlined campaign setup, transcript/input, Undo/Redo/Retry, Save Points, state, knowledge, context inspection, and model status. This milestone makes the product feel like the intended storyteller rather than an adapted AI-DnD application.
+- **M9 — Portable/recoverable campaigns:** The user can reliably export, back up, import, and recover complete campaigns including history, Save Points, state, knowledge, and active position. This is where moving or restoring a campaign becomes a supported user workflow rather than merely an underlying capability.
+- **M10 — Media-ready, still text-first:** Little or nothing visibly changes for normal play. The story/scene data and provider boundaries are prepared so image/video/audio/TTS/STT can be added later without redesigning the core application.
+- **M11 — Release-quality v1:** The user experience should be functionally complete; this milestone proves it stays correct through long campaigns, repeated history operations, offline use, failures, export/import, and multiple genres. It is the release-validation milestone rather than a major new feature milestone.

-### If ai-adventure is selected
-Early milestones may instead require:
+---

- adding an Ollama adapter,
- adding a browser API,
- building the browser UI,
- extending lore retrieval beyond current behavior.
+# M1 — Establish Production Fork and Offline Baseline

-A single detailed build plan written now would therefore contain false precision.
+## Objective

-## 3. Expected High-Level Production Phases
+Create the production fork from the pinned AI-DnD commit and make ordinary local story operation genuinely offline-capable before larger changes.

-These are directional only and must be rewritten after Phase 0.
+## Scope

-### Phase 1 — Production Foundation
- establish production fork/repository,
- preserve upstream provenance,
- remove or isolate unwanted functionality,
- establish development/test environment,
- confirm local Ollama integration.
+- establish production repository/fork lineage,
+- record upstream commit and license provenance,
+- establish reproducible dev/test environment,
+- vendor/cache/replace the `tiktoken` first-use encoding dependency so story generation works without Internet,
+- eliminate runtime Google Fonts/remote font dependency,
+- tighten CSP for local runtime assets,
+- verify same-host Ollama story generation with outbound Internet blocked,
+- verify explicitly configured trusted-LAN Ollama story generation while the storyteller UI/API remains loopback-bound,
+- establish baseline regression/test report.

-### Phase 2 — Authoritative Story Persistence
- immutable/recoverable turn history,
- branch parentage,
- checkpoints,
- restore,
- retry/edit semantics,
- transactional commits.
+## Explicit Non-Scope

-### Phase 3 — Narrative State
- generic entities,
+- no history rewrite yet,
+- no RPG-state redesign,
+- no imported knowledge,
+- no UI redesign,
+- no media generation.
+
+## Tests / Acceptance
+
+Must demonstrate:
+
+- A01-A06 as applicable to the inherited base, including the separate-host trusted-LAN inference path,
+- H01-H03 and H11,
+- no unexpected DNS/HTTP requests during ordinary story generation after setup,
+- no remote font request,
+- no tokenizer/BPE download on first production turn,
+- existing relevant AI-DnD tests remain green except documented upstream/environment exceptions.
+
+## Definition of Done
+
+A clean production build can start, open the browser UI, generate and persist story turns through either same-host Ollama or an explicitly configured trusted-LAN Ollama host, restart, and resume with outbound Internet blocked. The storyteller UI/API remains loopback-bound by default.
+
+---
+
+# M2 — Remove Hosted, Cloud, Scripting, and Unneeded Deployment Surface
+
+## Objective
+
+Reduce AI-DnD to the intended single-user local product trust boundary without destabilizing the story/tree/memory foundation.
+
+## Scope
+
+Remove or isolate as appropriate:
+
+- multi-user/account/guest/auth flows,
+- demo API-key behavior,
+- hosted analytics,
+- Render/Neon deployment paths,
+- Postgres/`psycopg` support,
+- cloud providers not required by v1,
+- arbitrary remote model-provider UI/configuration,
+- QuickJS/campaign scripting,
+- AI-Dungeon compatibility code that exists primarily to support scripting/hosted behavior,
+- hosted-only rate-limit/account infrastructure.
+
+Add:
+
+- explicit Ollama endpoint policy: same-host loopback default plus user-configured trusted-LAN inference,
+- clear local-model connection diagnostics,
+- migration/test instrumentation replacements for any tests that depended on JS hooks or removed hosted paths.
+
+## Explicit Non-Scope
+
+- do not redesign story history,
+- do not replace RPG state yet,
+- do not build knowledge/media systems.
+
+## Tests / Acceptance
+
+- local story play still works,
+- existing tree/retry/memory/context behavior remains intact,
+- application requires no cloud API keys,
+- approved trusted-LAN Ollama endpoints work while arbitrary public/Internet provider endpoints are rejected or absent from normal production configuration,
+- removed provider/auth/analytics/scripting paths are no longer reachable from normal production configuration.
+
+## Definition of Done
+
+The codebase has a narrow single-user/local-only surface and the inherited story foundation still passes its relevant regression suite.
+
+---
+
+# M3 — Production Non-Destructive History, Redo, and Active-Head Export
+
+## Objective
+
+Replace destructive Undo with the demonstrated head-cursor model and make Undo/Redo/divergence/export/import production-safe.
+
+## Scope
+
+Promote the Phase 0B spike concept into maintainable production code:
+
+- active head can move behind retained tip,
+- Undo moves head and deletes zero accepted turns,
+- Redo follows the retained continuation,
+- new write behind tip forks on first write,
+- retry/add-take/edit paths use the same safe fork/head rules,
+- prevent Undo from walking before the campaign opening/root semantics,
+- mark displaced/inactive futures/takes as retained/disposable using implementation-appropriate metadata,
+- keep ordinary Redo invalidated after divergence,
+- add browser Redo control and correct disabled/enabled states,
+- keep branch complexity out of normal UI,
+- export active head coordinate/depth as well as active branch,
+- import honors exported active head,
+- preserve backward compatibility for older bundles that lack the new field.
+
+## Explicit Non-Scope
+
+- named checkpoints belong in M4,
+- no general branch-tree UI,
+- no abandoned-history cleanup feature.
+
+## Tests / Acceptance
+
+Must cover:
+
+- D01-D10,
+- D02 minimum-five Undo,
+- D03 practical unlimited Undo behavior across retained history,
+- D04-D05 Redo semantics,
+- E01-E04 lineage isolation,
+- I01-I03 and I07 (undone-head round trip),
+- L01-L02,
+- branch-scoped memory remains isolated under Undo/Redo/divergence,
+- row counts demonstrate Undo deletes zero accepted turns.
+
+## Definition of Done
+
+History operations are non-destructive, Redo works, divergence preserves old futures, and export/import reopens at the exact active head.
+
+---
+
+# M4 — Named Save Points / Checkpoints
+
+## Objective
+
+Add durable user-facing Save Points on top of the active-head model.
+
+## Scope
+
+- named checkpoint storage,
+- checkpoint create/list/rename/delete,
+- restore by moving the active head,
+- later history retained rather than deleted,
+- fork only on first new continuation after restore,
+- checkpoint persistence across restart,
+- checkpoint export/import,
+- browser Save Point UX per `BROWSER-UX-SPEC.md`.
+
+## Explicit Non-Scope
+
+- no branch merge,
+- no automatic discarded-history cleanup,
+- no complex branch explorer required.
+
+## Tests / Acceptance
+
+- D11-D14,
+- E lineage tests after checkpoint restore/divergence,
+- I04,
+- L03.
+
+## Definition of Done
+
+The user can create a named Save Point, continue, restart, restore it, and continue differently without losing later history.
+
+---
+
+# M5 — Genre-Neutral Authoritative Narrative State
+
+## Objective
+
+Replace/generalize AI-DnD's RPG-specific relative-delta state system with the approved genre-neutral typed-event model.
+
+## Scope
+
+Establish generic authoritative state for:
+
+- entities,
+- characters/locations/organizations/items/vehicles as descriptive entity categories,
 - facts,
 - relationships,
+- possession/location/status/conditions,
 - story threads,
- state extraction/validation,
- state inspector.
+- scene state,
+- manual state/canon corrections,
+- state proposal provenance.

-### Phase 4 — Long-Term Memory
- summaries,
- older-turn retrieval,
- token budgeting,
- provenance,
- continuity handling.
+Implement:

-### Phase 5 — Local Knowledge Library
- local file imports,
- Canon / Reference / Inspiration classes,
- chunking,
- local indexing,
- optional local embeddings,
- retrieval inspection.
+- explicit typed state proposal schema,
+- absolute/unambiguous event semantics,
+- event allowlist,
+- validation,
+- atomic accepted-event commit,
+- current/historical snapshot/cache,
+- rollback/reconstruction tied to active lineage,
+- browser current-state inspector foundation.

-### Phase 6 — Browser UX Completion
- campaign management,
- transcript,
- branching visualization,
- checkpoints,
- state/editor,
- library management,
- prompt inspection,
- responsive local UI.
+Remove or demote:

-### Phase 7 — Local-Only Hardening
- remove remote providers,
- remove telemetry/analytics,
- remove runtime CDN dependencies,
- enforce/validate local endpoints,
- network tests,
- offline operation tests.
+- D&D-specific stats/bands/cooldowns/mechanics from the core product model,
+- relative-delta semantics as the generic state protocol.

-### Phase 8 — Export, Backup, and Recovery
- campaign export,
- import,
- backups,
- migration,
- corruption/error recovery.
+## Explicit Non-Scope

-### Phase 9 — Future-Media Hooks
- scene snapshots,
- visual character/location descriptors,
- asset schema,
- media-provider interfaces,
- no required image/video implementation.
+- no optional RPG module,
+- no imported knowledge yet,
+- no final rich state-editing UX if a simpler inspector is enough for this milestone.

-### Phase 10 — v1 Validation and Release
- regression testing,
- long-story testing,
- rollback/branch tests,
- offline test,
- migration test,
- documentation,
- release packaging.
+## Tests / Acceptance

-## 4. Gate Before This Plan Becomes Active
+- C01-C04 and C06,
+- D/E tests verifying state follows head movement,
+- H05 invalid state event rejection,
+- L01-L02,
+- malformed JSON/state proposal handling,
+- realistic-context tests against representative local models,
+- fantasy and science-fiction state fixtures use the same schema.

-Do not convert the high-level phases above into Codex implementation prompts until all of the following exist:
+## Definition of Done

- `SPECIFICATION.md` v1.0,
- `TECHNICAL-DESIGN.md` v1.0,
- completed Phase 0 research reports,
- approved fork/build ADR,
- approved licensing/reuse review.
+Accepted story state is genre-neutral, auditable, reconstructable, and no longer depends on ambiguous relative deltas.

-## 5. Required Format for the Final Build Plan
+---

-When rewritten after Phase 0, every production milestone should contain:
+# M6 — Branch-Safe Context, Summaries, and Long-Term Story Memory

- objective,
- scope,
- explicit non-scope,
- prerequisite milestones,
- files/components expected to change,
- implementation tasks,
- data/schema changes,
- tests required,
- security/privacy checks,
- acceptance criteria,
- rollback/migration notes,
- documentation updates,
- definition of done.
+## Objective

-The final document should be suitable for handing directly to Codex one milestone at a time.
+Align inherited AI-DnD memory/context behavior with the final authority and history model.
+
+## Scope
+
+- preserve recent active-lineage history selection,
+- ensure summaries are anchored to source turn ranges/lineage rather than positional list assumptions,
+- preserve branch-scoped memory isolation,
+- classify memory authority (accepted vs heuristic/inferred),
+- maintain explicit token budgets,
+- preserve/extend prompt-context inspection,
+- ensure memory/summary failures do not corrupt accepted story state,
+- test memory behavior after Undo/Redo/checkpoint/divergence,
+- validate realistic-context prompt construction.
+
+## Explicit Non-Scope
+
+- imported document knowledge belongs in M7,
+- no remote embeddings/vector DB.
+
+## Tests / Acceptance
+
+- F01-F08,
+- E lineage safety,
+- no abandoned-future term appears in active prompt after divergence,
+- negative control proves eligible memory returns when the relevant lineage is active,
+- summary lineage survives head movement correctly,
+- prompt inspector identifies included memories/summaries and token costs.
+
+## Definition of Done
+
+Long-running story context is lineage-safe, authority-aware, local, inspectable, and bounded.
+
+---
+
+# M7 — First-Class Imported Knowledge Library
+
+## Objective
+
+Implement the separate local knowledge subsystem required by the specification rather than overloading AI-DnD Story Cards.
+
+## Scope
+
+- `.txt` and `.md` import,
+- source validation and local copy/storage,
+- Canon / Reference / Inspiration classification,
+- enable/disable/delete,
+- content hash and provenance,
+- heading/paragraph-aware chunking,
+- SQLite FTS5 lexical index,
+- local Ollama embeddings where semantic retrieval is enabled,
+- hybrid retrieval/reranking,
+- authority-aware context insertion,
+- campaign scoping,
+- source/chunk inspector,
+- prompt retrieval provenance,
+- export/import preservation,
+- no automatic URL/image fetch,
+- prompt-injection framing as untrusted data.
+
+## Explicit Non-Scope
+
+- PDF/DOCX/EPUB import,
+- remote URL ingestion,
+- remote vector stores,
+- general plugin/tool framework.
+
+## Tests / Acceptance
+
+- G01-G10,
+- C05 canon beats reference/inspiration,
+- hidden/abandoned story facts cannot leak through lineage-derived knowledge,
+- H06-H09 as applicable to rendering/import/archive handling,
+- I05 knowledge provenance survives export/import.
+
+## Definition of Done
+
+A campaign can import local Canon/Reference/Inspiration files, retrieve them locally with provenance, and maintain authority boundaries.
+
+---
+
+# M8 — Browser UX Completion for v1 Story Operations
+
+## Objective
+
+Turn the adapted AI-DnD interface into the focused interactive-story workspace defined by `BROWSER-UX-SPEC.md`.
+
+## Scope
+
+- campaign library/setup streamlined for non-RPG stories,
+- story transcript and streaming polish,
+- one primary natural-language input flow plus story-direction affordance,
+- Undo/Redo/Retry/alternate-take controls,
+- Save Points UI,
+- edit user input/narrator output with safe lineage semantics,
+- current scene/state side panel,
+- knowledge panel,
+- context inspector,
+- local Ollama status/model selection,
+- no cloud-provider UI,
+- reserve microphone/STT affordance without implementing STT.
+
+## Explicit Non-Scope
+
+- no full branch-management UI,
+- no image/video/TTS/STT implementation,
+- no mobile-native app.
+
+## Tests / Acceptance
+
+- B01-B04,
+- D user-facing behavior,
+- relevant UX acceptance checks,
+- browser state remains consistent after restart/Undo/Redo/checkpoint/failed generation.
+
+## Definition of Done
+
+Normal story creation and play feels like a focused local storyteller rather than an RPG or developer console.
+
+---
+
+# M9 — Export, Backup, Recovery, and Migration Hardening
+
+## Objective
+
+Make campaigns portable and recoverable without losing lineage, state, knowledge, or the active head.
+
+## Scope
+
+- finalize documented campaign bundle format/versioning,
+- preserve active branch/head, retained history, retries, checkpoints,
+- state events/snapshots,
+- prompt/retrieval provenance as selected,
+- knowledge source metadata/content/index rebuild information,
+- scene/media metadata placeholders,
+- safe SQLite backup behavior,
+- import validation,
+- backward-compatible migration rules,
+- corruption/failure handling where practical.
+
+## Tests / Acceptance
+
+- I01-I06,
+- L01-L04,
+- undone-head round trip,
+- branched campaign round trip,
+- checkpoint round trip,
+- knowledge provenance round trip,
+- derived indexes can be rebuilt.
+
+## Definition of Done
+
+A campaign can be safely exported, imported into a clean data directory, and reopened at the exact intended active position with authoritative history/state intact.
+
+---
+
+# M10 — Future Media Extension Hooks Only
+
+## Objective
+
+Preserve the approved future media interfaces without adding a media-generation dependency to v1.
+
+## Scope
+
+- scene snapshots/packets suitable for future providers,
+- optional visual character/location/item descriptors,
+- provider-neutral media request/job/asset types or reserved schema as justified,
+- branch/lineage association for scenes/assets,
+- local-only endpoint contract for future providers,
+- STT contract: local transcription -> editable draft -> normal submission,
+- no core story-engine dependency on media availability.
+
+## Explicit Non-Scope
+
+Do not implement:
+
+- image generation,
+- video generation,
+- TTS,
+- STT,
+- ambience/audio generation,
+- ComfyUI/FLUX integration.
+
+## Tests / Acceptance
+
+- K01-K04 architecture/media-readiness tests,
+- no v1 story flow requires a media service,
+- scene data follows active lineage after Undo/restore/divergence.
+
+## Definition of Done
+
+Future media providers can be added through defined local interfaces without redesigning core story authority/history.
+
+---
+
+# M11 — v1 Security, Long-Run, and Release Validation
+
+## Objective
+
+Validate the full product against the release contract after all functional milestones are integrated.
+
+## Scope
+
+- full outbound-network blocked run,
+- dependency/runtime audit,
+- restrictive browser/CORS/CSP checks,
+- failed-model-call recovery,
+- long-running 100-turn campaign,
+- repeated Undo/Redo/Retry/checkpoint cycles,
+- branch/memory/summary leakage checks,
+- realistic-context state extraction across selected recommended models,
+- fantasy and science-fiction fixtures,
+- export/import/recovery tests,
+- migration tests,
+- documentation and packaging.
+
+## Tests / Acceptance
+
+Release gate in `V1-ACCEPTANCE-TESTS.md`:
+
+- all REQUIRED FOR V1 tests pass,
+- approved exceptions documented in ADRs,
+- 100-turn test passes,
+- offline operation passes,
+- branch/memory isolation passes,
+- export/import recovery passes,
+- both genre fixtures pass.
+
+## Definition of Done
+
+The build meets the v1 black-box acceptance contract and can be packaged as the first production release.
+
+---
+
+## 4. Milestone Dependency Summary
+
+```text
+M1 Production/offline foundation
+  -> M2 Local-only surface reduction
+      -> M3 Non-destructive history + export head
+          -> M4 Save Points
+              -> M5 Narrative state
+                  -> M6 Context/memory
+                      -> M7 Imported knowledge
+                          -> M8 Browser UX completion
+                              -> M9 Export/recovery hardening
+                                  -> M10 Future-media hooks
+                                      -> M11 v1 validation/release
+```
+
+Some implementation work may overlap internally, but milestone acceptance should remain sequential so architectural regressions are discovered early.
+
+## 4. Prompting Rule
+
+When implementation begins, prepare **one Codex prompt per milestone**.
+
+Do not hand the entire plan to Codex as one production task.
+
+Each prompt should contain only:
+
+- milestone objective,
+- relevant source documents,
+- scope/non-scope,
+- specific acceptance tests,
+- stop condition and required report/diff.
+
+No implementation prompt is included in the current planning revision.
@@ -1,9 +1,14 @@
 # Codex Handoff Note

-For the initial Phase 0B validation round, use:
+**Status:** Phase 0B handoff complete; historical only.

-`PHASE-0B-CODEX-BRIEF.md`
+The earlier Phase 0B execution prompts are retained for audit/history:

-This is the current concise execution brief.
+- `PHASE-0B-CODEX-BRIEF.md`
+- `PHASE-0B-CODEX-HANDOFF.md`

-`PHASE-0B-CODEX-HANDOFF.md` is retained as a more detailed reference/appendix and should not be treated as the primary execution prompt unless specifically needed.
+Do **not** execute either as the next production task.
+
+Phase 0B has been completed and the resulting recommendation reviewed. AI-DnD is now the selected production base, and the planning package has been revised accordingly.
+
+The next production Codex prompt has **not** been prepared. It should be created only after the current planning-package revision is reviewed and approved. When authorized, the first implementation prompt should be derived from Production Milestone M1 in `BUILD-MILESTONES.md`, not from the Phase 0B validation briefs.
@@ -1,6 +1,6 @@
 # Adventure Storyteller — Context and Memory

-**Status:** Draft v0.1  
+**Status:** v1.0 — aligned to Phase 0B findings  
 **Purpose:** Define what information is supplied to the narrator on each turn, how long-term memory works, and how authority, lineage, retrieval, summaries, and imported knowledge interact.

 ## 1. Design Goal
@@ -420,7 +420,7 @@ Reason:
 - lexical retrieval is transparent and precise for names/terms,
 - semantic retrieval is useful for conceptually related old events.

-Phase 0B should determine what the selected base already supports.
+Phase 0B confirmed useful local semantic memory in AI-DnD and deterministic lexical lore in ai-adventure. The selected production direction is hybrid local retrieval, implemented incrementally with a lexical path that remains usable when semantic embeddings are unavailable.

 ## 17. Embeddings

@@ -1083,25 +1083,25 @@ If the narrator makes an unexpected choice, the system should support questions

 This is why context provenance is a first-class requirement.

-## 57. Phase 0B Validation Questions
+## 57. Phase 0B Findings Applied

-Codex should answer:
+The selected AI-DnD base was exercised with real local Ollama embeddings and demonstrated useful lineage behavior:

-1. How does AI-DnD currently rank and retrieve memories?
-2. Are AI-DnD memories branch-aware?
-3. Can abandoned-branch memories leak into active context?
-4. How are Story Cards selected and injected?
-5. Can Story Cards be generalized into Canon / Reference / Inspiration classes?
-6. What exact embedding provider does local AI-DnD use with Ollama?
-7. Can memory retrieval work fully offline?
-8. What context components are visible in AI-DnD's Insights view?
-9. How does Open Dungeon decide when to summarize old history?
-10. Can ai-adventure's FTS lore layer be retained as a deterministic lexical retrieval component?
-11. How difficult would hybrid lexical + semantic retrieval be in the selected base?
-12. Can current context budgeting preserve hard canon under pressure?
-13. Are summaries tied explicitly to source lineage?
-14. Can memory extraction failure occur without blocking a successful turn?
-15. Can prompt/context snapshots be retained without excessive database growth?
+- branch-scoped memory retrieval worked,
+- a memory from a later/abandoned depth was excluded after moving the active head backward,
+- the same memory became eligible again after Redo/return to the applicable lineage,
+- switching to a different branch prevented abandoned-branch terms from appearing in the assembled prompt,
+- the context/Insights path exposes labeled prompt sections and token costs.
+
+Planning consequences:
+
+1. Preserve AI-DnD's common lineage filtering/chokepoint rather than replacing memory from scratch.
+2. Make summaries explicitly lineage/turn-range anchored; never rely on a positional message watermark.
+3. Keep accepted story memory distinct from heuristic/inferred memory.
+4. Imported knowledge remains a separate subsystem; do not promote Story Cards into the knowledge store merely because they are prompt-injection primitives.
+5. Use local Ollama embeddings for semantic story memory where enabled; retain a lexical/deterministic path for imported knowledge.
+6. Context/state extraction must be tested at realistic prompt length because Phase 0B showed model protocol adherence can degrade under full application context.
+7. Derived memory/summary failure must not corrupt or roll back an otherwise valid authoritative story commit.

 ## 58. Acceptance Criteria

@@ -1117,6 +1117,8 @@ The final implementation must satisfy:
 - retrieval works locally,
 - no remote embeddings/search are required,
 - abandoned branch memories do not leak,
+- moving the active head backward excludes memories derived after that head,
+- Redo/returning to the valid lineage can make those memories eligible again,
 - context remains bounded,
 - output space is reserved,
 - prompt composition is inspectable,
@@ -1124,7 +1126,7 @@ The final implementation must satisfy:
 - summaries are lineage-safe,
 - memory failures do not corrupt authoritative story state.

-## 59. Current Recommendation
+## 59. Selected Context / Memory Design

 Use a layered, authority-aware context builder:

@@ -1141,13 +1143,13 @@ Use a layered, authority-aware context builder:
                    v
            ----------------
                    +
-            Story Summary
+       Lineage-Anchored Summary
                    +
       Relevant Story Memories
                    +
       Relevant Local Knowledge
                    +
-             Recent History
+       Recent Active-Lineage Turns
                    +
             Current Input
                    |
@@ -1155,14 +1157,14 @@ Use a layered, authority-aware context builder:
                 OLLAMA
 ```

-Retrieval should be:
+Retrieval must be:

 ```text
 local
-+ lineage-aware
+ lineage-aware where derived from story history
 + provenance-preserving
 + authority-aware
 + token-bounded
 ```

-The application should treat context construction as a deterministic subsystem that can be inspected and tested independently of prose generation.
+The application treats context construction as a deterministic, independently testable subsystem. AI-DnD's lineage-aware memory implementation is the starting point; the project's own authority and imported-knowledge rules define the target behavior.
@@ -1,11 +1,11 @@
 # Adventure Storyteller — Data Model

-**Status:** Draft v0.1  
+**Status:** v1.0 conceptual model aligned to Phase 0B decisions  
 **Purpose:** Define the persistent information the application must represent, independent of the final fork or database implementation.

 ## 1. Design Goals

-The data model must support persistent interactive stories, complete authoritative history, non-destructive branching, checkpoints and rollback, genre-independent narrative state, long-term memory, imported local knowledge, prompt/context provenance, future image/video generation, export/restore, and local-only operation.
+The data model must support persistent interactive stories, complete authoritative history, non-destructive branching, checkpoints and rollback, genre-independent narrative state, long-term memory, imported local knowledge, prompt/context provenance, future image/video/audio/TTS/STT generation, export/restore, and local-only operation.

 The same core schema should work for fantasy, science fiction, mystery, horror, historical fiction, westerns, and other narrative genres.

@@ -62,6 +62,7 @@ campaign:
  created_at: timestamp
  updated_at: timestamp
  active_branch_id: uuid
+  active_head_turn_id: optional uuid
  status: active | archived

 story_profile:
@@ -95,14 +96,18 @@ branch:
  created_at: timestamp
  created_from_branch_id: optional uuid
  fork_turn_id: optional uuid
-  head_turn_id: optional uuid
+  tip_turn_id: optional uuid
+  disposition: active | retained | disposable
  status: active | archived
 ```

 Rules:
 - branches may share ancestral turns,
 - shared history should not be duplicated unnecessarily,
- creating a branch must not modify the source branch.
+- creating a branch must not modify the source branch,
+- the campaign active head may sit behind the retained branch tip after Undo,
+- Redo moves the active head forward while the prior continuation remains selected,
+- a new write below the retained tip creates a new continuation and leaves the old future retained/disposable.

 Detailed behavior will be defined separately in `STORY-BRANCH-SEMANTICS.md`.

@@ -162,7 +167,7 @@ take:
  selected: boolean
 ```

-Whether `Take` becomes a separate table or sibling turn nodes will be decided after Phase 0B.
+Physical representation remains implementation-specific. The selected AI-DnD base already models alternate takes within its lineage machinery; production should retain that approach if it satisfies the required Retry/select/retention semantics without forcing a separate table.

 ## 8. Checkpoint

@@ -176,7 +181,7 @@ checkpoint:
  created_at: timestamp
 ```

-A checkpoint is a named pointer to a recoverable story position. It should normally remain tied to the turn where it was created.
+A checkpoint is a named pointer to a recoverable story position. It should normally remain tied to the turn where it was created. Restoring it moves the campaign active head; it does not delete later retained history. A new branch is created on the first divergent write after restore, not merely because the checkpoint was opened.

 ## 9. Narrative Entity

@@ -386,7 +391,7 @@ Excellent auditability, but requires replay.
 ### C. Hybrid
 Validated events plus periodic/current snapshots.

-**Current preference: Hybrid**, pending Phase 0B.
+**Selected for v1: Hybrid.** Store validated authoritative events plus efficient state snapshots/cache for normal reads and restore.

 ## 18. State Change Event

@@ -404,18 +409,21 @@ state_event:

 Potential event types:
 - entity_created,
- entity_updated,
+- set_entity_status,
+- set_entity_attribute,
 - fact_added,
 - fact_invalidated,
 - relationship_added,
 - relationship_ended,
 - thread_opened,
 - thread_resolved,
- location_changed,
- possession_changed,
- scene_changed.
+- current_location_set,
+- possession_set,
+- scene_set.

-Events must be validated before commit.
+Event semantics must be explicit and typed. Prefer unambiguous absolute assignments for mutable values. If incremental operations are ever needed, encode the operation explicitly (for example `increment_value`) rather than relying on one numeric field whose interpretation is implicit.
+
+Events must be schema-validated, semantically checked where deterministic rules exist, and accepted by the application before commit.

 ## 19. State Proposal

@@ -431,7 +439,7 @@ state_proposal:
  validation_status: accepted | partially_accepted | rejected | repair_required
 ```

-The model must never write directly to authoritative state tables.
+The model must never write directly to authoritative state tables. The production protocol must not depend on AI-DnD-style ambiguous relative deltas; see ADR 010.

 ## 20. Scene Snapshot

@@ -598,7 +606,7 @@ media_job:
  scene_id: optional uuid
  source_turn_start_id: optional uuid
  source_turn_end_id: optional uuid
-  type: image | video | audio
+  type: image | video | audio | tts | stt
  provider: string
  model: string
  status: queued | running | completed | failed
@@ -615,7 +623,7 @@ media_asset:
  campaign_id: uuid
  media_job_id: optional uuid
  scene_id: optional uuid
-  type: image | video | audio
+  type: image | video | audio | tts | stt
  file_path: string
  metadata: object
  created_at: timestamp
@@ -645,7 +653,7 @@ A campaign export should be capable of preserving:
 - media metadata,
 - media files if selected.

-Exact format remains open. A ZIP containing a database plus manifest is a strong candidate.
+The physical container format remains an implementation choice, but the export must preserve the exact active branch **and active head position**, even when the head is behind a retained tip after Undo. A ZIP containing a database plus manifest remains a strong candidate.

 ## 30. Deletion vs Archival

@@ -692,54 +700,65 @@ Potential provenance:
 - imported inspiration,
 - derived inference.

-## 33. Open Questions for Phase 0B
+## 33. Phase 0B Decisions Applied

-1. Does AI-DnD already model alternate takes separately from branch nodes in a reusable way?
-2. Can its state snapshots hold generic narrative JSON without major redesign?
-3. Is its branch lineage compatible with immutable turns?
-4. Should checkpoints be branch-independent pointers to turns?
-5. Should memories be physically branch-scoped or lineage-filtered at query time?
-6. Should knowledge sources be reusable across campaigns in v1?
-7. Should media tables physically exist in v1 or only interfaces/types?
-8. How should manual edits to canon/state be versioned?
-9. Which state needs full historical reconstruction versus only current-state storage?
-10. Can ai-adventure's event/replay discipline be adopted without overcomplicating AI-DnD?
+Phase 0B resolved the foundational data-model questions:
+
+- AI-DnD story lineage/alternate-take machinery is the production starting point.
+- The active head is distinct from retained tip history.
+- Undo/Redo use head movement; destructive deletion is not part of ordinary history operations.
+- Named checkpoints are durable pointers to recoverable head positions.
+- State uses a hybrid event + snapshot/cache model.
+- State proposals use explicit typed operations with unambiguous value semantics.
+- Memories/summaries must be lineage-filtered or lineage-anchored.
+- Imported knowledge requires separate source/chunk/index tables rather than overloading Story Cards.
+- Scene/media records remain optional derived extensions and must carry source lineage.
+- Export/import must preserve active head position as well as the retained history graph.

 ## 34. Acceptance Criteria

 The final v1 data model must support all of these without destructive hacks:

 - close/restart/resume exact story,
+- Undo/Redo without deleting accepted turns,
+- active head behind retained tip,
 - branch from an earlier turn while retaining the original future,
+- mark abandoned futures/takes retained/disposable,
 - create and restore named checkpoints,
 - know current characters/locations/relationships/story threads,
 - reconstruct earlier authoritative state,
+- validate typed state proposals before committing events,
 - retrieve old events outside the active context window,
 - identify which imported passages informed a turn,
 - reconstruct what was sent to Ollama,
+- export/import an undone campaign without silently redoing it,
 - run fantasy and science-fiction campaigns without schema changes,
- attach future image/video assets to scenes or turn ranges.
+- attach future image/video/audio/TTS/STT metadata to scenes or turn ranges without making media authoritative.

-## 35. Current Recommendation
-
-The target conceptual model should be:
+## 35. Selected Conceptual Model

 ```text
-Immutable Turn Graph
+Retained Turn/Take Lineage
        |
-        +--> validated state events
+        +--> Active branch + movable active head
        |
-        +--> state snapshot/cache
+        +--> Validated typed state events
+        |       |
+        |       +--> state snapshot/cache
+        |
+        +--> lineage-safe summaries/memories
+        |
+        +--> prompt/retrieval provenance
        |
        +--> scene snapshot
        |
-        +--> prompt/retrieval provenance
+        +--> future optional media records
+
+Separate campaign knowledge subsystem
+        +--> sources
+        +--> chunks
+        +--> FTS/local embeddings
+        +--> authority/provenance
 ```

-This combines the strongest observed concepts from:
-
- AI-DnD's story tree and snapshots,
- ai-adventure's append-only event/replay discipline,
- Open Dungeon's simple story UX and visual continuity.
-
-The physical implementation remains provisional until Phase 0B validates the preferred production base.
+This combines AI-DnD's retained story lineage and snapshot infrastructure with ai-adventure-style explicit event/commit discipline while preserving the project's own specification as the authority.
@@ -4,11 +4,11 @@

 ## Decision

-v1 will target local Ollama inference.
+v1 will target Ollama inference running on user-controlled local infrastructure. The default endpoint is same-host loopback, but v1 must also support an explicitly configured Ollama instance on a trusted local-area network.

 ## Context

-The intended deployment already has a local Ollama inference engine. The project prioritizes local control, privacy, and predictable integration.
+The intended production deployment can eventually run the storyteller and Ollama on one machine, but development and testing may place Ollama on a separate machine on the user's LAN. The project prioritizes local control, privacy, predictable integration, and no dependency on Internet/cloud inference.

 ## Alternatives Considered

@@ -26,4 +26,7 @@ Ollama is already available locally, provides a simple local API, supports both

 - candidate forks supporting multiple cloud providers should be simplified or hardened,
 - candidate projects using another local API need an adapter,
+- the storyteller must support both same-host Ollama and an explicitly configured trusted-LAN Ollama endpoint,
+- LAN inference does not imply LAN exposure of the storyteller UI/API; the storyteller should still bind to loopback by default,
+- arbitrary public Internet/cloud model endpoints remain outside normal v1 configuration,
 - future backend abstraction may be added, but v1 should not be delayed to support it.
@@ -1,14 +1,14 @@
 # ADR 004 — Local-Only Production Default

-**Status:** Accepted
+**Status:** Accepted; Phase 0B hardening requirements identified

 ## Decision

-The production application will be designed to operate without Internet access.
+The production application will operate without Internet access for ordinary v1 story use.

 ## Context

-The project requires control over story data, imported material, prompts, and model outputs, with no unintended disclosure to outside services.
+The project requires control over story data, imported material, prompts, model outputs, memories, embeddings, and future generated media, with no unintended disclosure to outside services.

 ## Alternatives Considered

@@ -18,18 +18,34 @@ The project requires control over story data, imported material, prompts, and mo

 ## Reason

-Local-only operation best matches the privacy and control requirements.
+Local-only operation best matches the privacy and control requirements. For this project, "local-only" means operation on user-controlled local infrastructure without requiring Internet or cloud services; it does not require every component to run on the same physical machine.
+
+## Phase 0B Evidence
+
+The selected AI-DnD base does **not** satisfy this requirement unchanged:
+
+- `tiktoken` attempted a first-use download of its encoding data,
+- the browser requested Google Fonts at runtime,
+- hosted/cloud/auth/analytics/Postgres/provider paths remain present upstream,
+- inherited endpoint guarding is oriented toward hosted deployment rather than enforcing the project's approved-local-infrastructure model boundary.
+
+These are bounded production-hardening tasks rather than reasons to reject the fork.

 ## Consequences

-The production application should avoid:
+The production application must avoid or remove:

 - telemetry,
 - analytics,
 - cloud inference,
+- hosted authentication/accounts,
 - remote vector stores,
 - automatic web retrieval,
 - runtime CDN dependencies,
- remote fonts/assets.
+- remote fonts/assets,
+- first-use runtime tokenizer/model-support downloads,
+- arbitrary remote model-provider configuration in normal v1 UI.

-All inherited network behavior from a fork must be inventoried during Phase 0.
+Production packaging must contain all runtime assets required for ordinary story use after the user has installed the intended local Ollama models.
+
+The storyteller application should bind to loopback by default. Ollama should default to same-host loopback but may be explicitly configured to an approved trusted-LAN endpoint for v1. This LAN inference path does not authorize LAN exposure of the storyteller UI/API. Arbitrary public/Internet inference endpoints remain prohibited in normal v1 configuration.
@@ -1,29 +1,44 @@
 # ADR 005 — Branch-Preserving Story History

-**Status:** Accepted in principle; implementation pending Phase 0
+**Status:** Accepted; implementation direction validated in Phase 0B

 ## Decision

-Returning to an earlier story point should preserve abandoned future history as another branch rather than destructively erasing it.
+Returning to an earlier story point preserves abandoned future history rather than destructively erasing it.
+
+The selected implementation model uses a **movable active head over retained lineage**:
+
+- Undo moves the head backward,
+- Redo moves it forward along the retained continuation,
+- accepted turns are not deleted by ordinary Undo,
+- a new write after moving backward creates a new continuation on first divergent write,
+- the displaced future remains retained/disposable,
+- normal UI presents Undo/Redo/Retry/Save Point rather than branch-management concepts.

 ## Context

 The user must be able to recover from unwanted story developments and explore alternatives while retaining prior work.

+Phase 0B found that AI-DnD's shipped Undo was destructive even though its tree/take infrastructure was otherwise strong. A disposable spike demonstrated non-destructive head-cursor Undo/Redo using existing lineage chokepoints and branch creation while preserving branch-scoped memory isolation.
+
 ## Alternatives Considered

 - destructive undo,
 - overwrite-in-place editing,
 - complete copy of campaigns for every retry,
- branch-preserving turn graph.
+- branch-preserving turn graph with movable active head.

 ## Reason

-A branch-preserving history provides recovery, experimentation, and auditability without unnecessary campaign duplication.
+The selected model provides recovery, experimentation, auditability, and Redo without unnecessary campaign duplication or a complicated user-facing branch workflow.

 ## Consequences

- turn identity/parentage must be first-class,
- state restore must be branch-aware,
- retry/edit semantics must be explicitly defined,
- the selected candidate repository must either support this or be adaptable to it.
+- turn identity/parentage remains first-class,
+- active head and retained tip are distinct concepts,
+- state restore is lineage-aware,
+- retry/edit/add-take must honor fork-if-behind-head behavior,
+- summaries/memories must respect active lineage/head,
+- named checkpoints point to durable story positions,
+- abandoned history is marked disposable but is not automatically cleaned up in v1,
+- export/import must preserve the active head coordinate as well as the retained history graph.
@@ -1,14 +1,14 @@
 # ADR 008 — Complete Phase 0 Before Detailed Build Planning

-**Status:** Accepted
+**Status:** Accepted and completed

 ## Decision

-The project will complete repository research, validation, architecture selection, and critical prototypes before writing the detailed production implementation milestone plan.
+The project completed repository research, validation, architecture selection, and critical prototypes before finalizing the detailed production implementation milestone plan.

 ## Context

-Multiple candidate open-source projects already implement overlapping parts of the desired system. The correct build sequence depends heavily on which codebase is selected.
+Multiple candidate open-source projects implemented overlapping parts of the desired system. The correct build sequence depended on which codebase survived local validation.

 ## Alternatives Considered

@@ -18,10 +18,15 @@ Multiple candidate open-source projects already implement overlapping parts of t

 ## Reason

-The third approach reduces speculative planning and prevents large amounts of rework.
+The bounded Phase 0 prevented false assumptions from becoming production architecture. In particular, runtime testing discovered destructive AI-DnD Undo, an offline tokenizer fetch, remote fonts, Open Dungeon's lack of tests and destructive summary/history assumptions, and the relative-delta state-protocol failure mode.
+
+## Completion Record
+
+Phase 0 selected AI-DnD as the production base, validated the non-destructive head-cursor approach, selected explicit typed narrative-state events, established local-only hardening requirements, and produced the production `BUILD-MILESTONES.md`.

 ## Consequences

- `BUILD-MILESTONES.md` remains intentionally high level during Phase 0,
- production coding should not begin unless explicitly authorized,
- Phase 0 ends with the final build plan.
+- the placeholder build plan has been replaced by a production milestone sequence,
+- `SPECIFICATION.md` and `TECHNICAL-DESIGN.md` are the v1.0 planning baseline,
+- production coding still requires explicit authorization and a milestone-specific prompt,
+- the current review intentionally stops before preparing that prompt.
@@ -0,0 +1,93 @@
+# ADR 009 — AI-DnD Is the Production Base
+
+**Status:** Accepted  
+**Date:** 2026-09-01
+
+## Decision
+
+Use AI-DnD as the production fork/base, pinned initially to upstream commit:
+
+```text
+d72f7c1bda0f34fccd84afb7a25c34eb01c901de
+```
+
+AI-DnD is the ownership center for the production codebase.
+
+Other candidate projects remain implementation references only unless a later explicit decision authorizes compatible code reuse.
+
+## Context
+
+Phase 0A favored AI-DnD because it appeared to contain the most difficult correctness infrastructure. Phase 0B then cloned, built, tested, and exercised the three finalists with local Ollama and targeted experiments.
+
+Phase 0B corrected one major assumption: AI-DnD's shipped Undo hard-deletes history and there is no Redo. A disposable follow-up spike demonstrated that the architecture can support non-destructive head-cursor Undo/Redo with a bounded change while retaining alternate history and branch-scoped memory isolation.
+
+AI-DnD also demonstrated:
+
+- browser UI and FastAPI backend,
+- SQLite persistence,
+- story-tree/lineage machinery,
+- alternate takes,
+- branch switching,
+- per-node state snapshots,
+- local Ollama operation,
+- branch-scoped memory with local embeddings,
+- prompt/context inspection,
+- streaming,
+- export/import foundation,
+- substantial automated regression coverage,
+- ability to run without RPG scenario state.
+
+Open Dungeon would require a foundational history/persistence/summary rewrite with no existing automated test foundation. ai-adventure has the strongest state/privacy core but would require building most of the browser product around it.
+
+## Alternatives Considered
+
+- fork Open Dungeon,
+- use ai-adventure as the core and build browser/API layers,
+- build a new application shell,
+- continue repository-selection research.
+
+## Reason
+
+AI-DnD minimizes the amount of high-risk correctness infrastructure that must be invented while providing the browser/service/test foundation the target product needs.
+
+The remaining work is substantial but is more bounded and testable than the alternatives.
+
+## Consequences
+
+Retain or adapt from AI-DnD:
+
+- React/Vite browser application,
+- FastAPI service boundary,
+- SQLite and migration foundation,
+- story tree and lineage queries,
+- alternate takes,
+- state snapshot pattern,
+- local Ollama integration,
+- Memory Bank concepts and branch scoping,
+- Insights/context snapshots,
+- SSE streaming,
+- export/import framework,
+- relevant automated tests.
+
+Remove or replace:
+
+- hosted/multi-user/auth/demo functionality,
+- analytics,
+- Postgres/Neon/Render paths,
+- cloud model providers,
+- QuickJS/campaign scripting,
+- AI-Dungeon compatibility not needed by the product,
+- RPG-specific presentation and relative-delta state mechanics,
+- runtime remote fonts/assets,
+- first-use remote tokenizer dependency.
+
+Reimplement selected patterns from references:
+
+- ai-adventure: typed state events, validation/commit discipline, checkpoints/head movement, replay/privacy patterns,
+- Open Dungeon: focused story UX and future local-media interaction ideas,
+- Chronicler/IFF: authority/trust concepts,
+- Gamentic: provider-neutral optional media boundary.
+
+## Non-Decision
+
+This ADR does not authorize production coding by itself. Implementation begins only after the revised planning package is approved and a milestone-specific prompt is prepared.
@@ -0,0 +1,100 @@
+# ADR 010 — Use Explicit Typed Narrative-State Events
+
+**Status:** Accepted  
+**Date:** 2026-09-01
+
+## Decision
+
+The production narrative-state engine will use an explicit, typed event/proposal vocabulary with unambiguous values, preferably absolute assignments for mutable values, rather than AI-DnD's relative-delta world-state protocol.
+
+The application remains authoritative:
+
+```text
+Narration/model output
+        |
+        v
+Typed state proposal
+        |
+        v
+Schema + semantic validation
+        |
+        v
+Accepted state events
+        |
+        +--> state snapshot/cache
+        +--> provenance/audit record
+```
+
+## Context
+
+Phase 0B exercised AI-DnD's existing world-state referee against local models under realistic application context.
+
+The protocol requested relative deltas, but the model sometimes emitted absolute values. An emitted value could be syntactically legal as a delta while semantically representing the wrong operation. The referee could therefore accept a valid-looking proposal that caused authoritative state to diverge from the narration.
+
+The failure class is architectural: validation cannot reliably distinguish a legitimate large delta from an absolute value mistakenly expressed in a delta field.
+
+ai-adventure uses a more explicit typed-event approach in which the requested operation and value semantics are directly represented.
+
+## Alternatives Considered
+
+- retain AI-DnD's relative-delta protocol,
+- infer whether a number is absolute or relative,
+- rely on a larger model to follow delta instructions,
+- use explicit typed events with clear value semantics.
+
+## Reason
+
+Explicit event semantics remove the relative-versus-absolute ambiguity and make proposals easier to validate, test, audit, and replay.
+
+This does **not** make model proposals infallible. A model can still propose an incorrect absolute value or incorrect event. The application must still perform:
+
+- schema validation,
+- allowlisted event-type validation,
+- referential-integrity checks,
+- domain/consistency checks where deterministic rules exist,
+- provenance recording,
+- safe failure/repair behavior.
+
+## Event Style
+
+Illustrative event forms:
+
+```yaml
+- type: set_entity_status
+  entity_id: mara
+  value: injured
+
+- type: set_current_location
+  entity_id: aldric
+  location_id: tavern-cellar
+
+- type: set_possession
+  item_id: silver-key
+  owner_id: aldric
+
+- type: add_fact
+  subject_id: mara
+  predicate: knows
+  object_id: silver-key-origin
+  authority: accepted_story
+
+- type: open_story_thread
+  thread_id: investigate-cellar-door
+```
+
+For numeric or bounded values introduced by optional future modules, prefer explicit operations such as:
+
+```text
+set_value
+increment_value
+```
+
+rather than one ambiguous numeric field whose interpretation depends on prompt instructions.
+
+## Consequences
+
+- AI-DnD's existing RPG state/referee implementation is a source to replace/generalize, not preserve as the production narrative-state protocol.
+- Narrative state should remain genre-neutral: entities, facts, relationships, locations, conditions, possessions, threads, scenes, and similar generic concepts.
+- Accepted events and resulting state must be committed atomically with the accepted story turn where practical.
+- State snapshots/cache should make normal reads and restore fast; event history preserves audit/reconstruction value.
+- Tests must exercise state extraction at realistic context length against realistic local models, not only isolated prompts.
@@ -1,6 +1,6 @@
 # Adventure Storyteller — Imported Knowledge Design

-**Status:** Draft v0.1  
+**Status:** v1.0 — selected implementation direction after Phase 0B  
 **Purpose:** Define how local user-supplied knowledge is imported, classified, indexed, retrieved, inspected, disabled, deleted, and kept separate from executable instructions.

 ## 1. Design Goal
@@ -949,16 +949,11 @@ For v1, plain metadata is sufficient.

 ## 65. Campaign-Wide vs Shared Library

-Open question:
+V1 decision:

-Should a source belong to:
- one campaign only,
-or
- reusable global library?
+> **Knowledge sources are campaign-scoped.**

-Current recommendation for v1:
-
-> Campaign-scoped knowledge first.
+A reusable global/shareable library may be considered later, but it is not part of the v1 storage or authority model.

 Reasons:
 - simpler privacy model,
@@ -1082,31 +1077,52 @@ These should be used to test:
 - disable/delete,
 - export/import.

-## 73. Candidate Evaluation Questions
+## 73. Phase 0B Integration Decision

-Codex should answer for AI-DnD:
+The production base is AI-DnD, but its Story Cards are **not** the production imported-knowledge store.

-1. Can Story Cards map cleanly to Canon/Reference/Inspiration?
-2. Are cards campaign-scoped?
-3. How are cards chunked/retrieved?
-4. Can remote/provider dependencies be removed?
-5. Can provenance be shown per retrieved card/chunk?
-6. Can hidden canon be represented?
-7. Can local embeddings work fully offline?
+Phase 0B found that Story Cards do not carry the lineage/provenance structure required for a general imported-knowledge system and do not directly provide the required source classification, chunking, local FTS, semantic indexing, source lifecycle, and inspection model.

-For Open Dungeon:
+Implement imported knowledge as separate first-class tables/services.

-1. Does it currently support imported documents beyond built-in story data?
-2. What new storage/index layer would be required?
-3. Can its local image/story architecture remain separate from knowledge retrieval?
-4. What is the simplest local FTS/embedding integration?
+Recommended conceptual records:

-For ai-adventure:
+```text
+knowledge_source
+knowledge_source_version (optional if v1 keeps simpler version metadata)
+knowledge_chunk
+knowledge_embedding / vector representation
+knowledge_retrieval_record
+```

-1. Can the FTS lore system represent classifications?
-2. Can lore entries retain source provenance?
-3. How difficult is semantic retrieval addition?
-4. Is campaign isolation already strong?
+Every source/chunk must retain enough metadata for:
+
+- campaign scope,
+- Canon / Reference / Inspiration class,
+- source provenance/hash,
+- enable/disable/delete,
+- chunk identity,
+- lexical/semantic retrieval,
+- prompt inspection,
+- export/import.
+
+Normal imported files are campaign-level source material and need not inherit story-branch lineage merely because the story branches. If a future knowledge source or chunk is **derived from story history**, it must carry source turn/lineage coordinates so abandoned-path material cannot leak into active context.
+
+Story Cards may remain as an inherited authored-rule/lore primitive during migration if useful, but they must not become an alternate untracked path around the new knowledge authority/provenance rules.
+
+### Retrieval implementation direction
+
+Use:
+
+```text
+SQLite FTS5 lexical retrieval
+
+local Ollama semantic embeddings where enabled
+
+authority/relevance reranking
+```
+
+Lexical retrieval remains available even if embeddings fail or are disabled.

 ## 74. V1 Acceptance Criteria

@@ -1123,16 +1139,19 @@ The final v1 must support:
 - bounded retrieval,
 - canon precedence,
 - no automatic URL fetch,
+- no remote image fetch,
 - no script execution,
+- prompt-injection framing as untrusted data,
 - export/import preservation.

-Strongly preferred:
+Strongly preferred and planned for v1:
+
 - lexical + semantic hybrid retrieval,
 - hidden/narrator-only canon,
 - source inspector,
 - prompt retrieval inspector.

-## 75. Current Recommendation
+## 75. Selected Implementation

 Implement imported knowledge as a first-class local subsystem:

@@ -1140,17 +1159,17 @@ Implement imported knowledge as a first-class local subsystem:
 Local File
   |
   v
-Validate
+Validate / Copy Locally / Hash
   |
   v
 Classify
   |
   v
-Chunk
+Chunk + Provenance
   |
-   +--> SQLite FTS
+   +--> SQLite FTS5
   |
-   +--> Local Embeddings
+   +--> Local Ollama Embeddings
   |
   v
 Hybrid Retrieval
@@ -1162,7 +1181,7 @@ Authority Filter / Rerank
 Bounded Prompt Context
 ```

-And preserve this separation:
+Preserve this separation:

 ```text
 Story authority
@@ -1,6 +1,6 @@
 # Adventure Storyteller — Media Extension Contract

-**Status:** Draft v0.1  
+**Status:** v1.0 architecture contract — providers remain future/optional  
 **Purpose:** Define the stable interfaces and data boundaries needed to add local image, video, and audio generation later without coupling media generation to the core story engine.

 ## 1. Design Goal
@@ -1287,13 +1287,9 @@ Open Dungeon is especially relevant for:
 - character visual continuity,
 - image workflow UX.

-During Phase 0B, inspect:
- how scene prompts are built,
- how images are attached to story,
- provider coupling,
- whether media can be separated from destructive history model.
+Phase 0B confirmed Open Dungeon should remain a media/UX reference rather than the production base. Study its local image worker protocol, scene/image attachment, and character visual-continuity ideas during the future media implementation stage if useful.

-Do not copy its persistence limitations into the core story architecture.
+Do not copy its linear/destructive persistence assumptions into the core story architecture.

 ## 80. Gamentic Reuse

@@ -1313,23 +1309,18 @@ Corvus may be useful for:

 Again, use concepts selectively.

-## 82. V1 Physical Schema Decision
+## 82. V1 Physical Schema Direction

-Open question:
+The v1 requirement is architectural compatibility, not media generation.

-Should media tables physically exist in v1?
+Required now:
+- scene snapshots,
+- stable optional visual profiles,
+- provider-neutral request/result types or equivalent interface contract.

-Recommended:
+A physical media job/asset table may be introduced in the dedicated future-media-hooks milestone if it is inexpensive and useful for schema stability. Its physical presence is an implementation detail, not a prerequisite for story functionality.

-> Include minimal media-ready schema/interfaces if inexpensive, but do not build provider implementation solely to justify them.
-
-Minimum useful v1 fields:
- scene snapshot,
- stable visual profiles,
- media provider interface/types,
- optional media asset table.
-
-Phase 0B should determine cost.
+Do not implement a provider merely to justify a table.

 ## 83. V1 Required Media Readiness

@@ -1383,20 +1374,14 @@ Pass if:
 - abandoned-branch events are not included,
 - media generation does not mutate story.

-## 87. Phase 0B Validation Questions
+## 87. Phase 0B Findings Applied

-Codex should answer:
-
-1. How does Open Dungeon attach generated images to story messages/scenes?
-2. Is image generation coupled to linear/destructive message history?
-3. Can its visual character continuity data be reused independently?
-4. What provider assumptions are hardcoded?
-5. Can ComfyUI/local provider calls run fully offline?
-6. Does AI-DnD already have scene-like structured state suitable for media extraction?
-7. Can scene snapshots be added without RPG schema coupling?
-8. What parts of Gamentic's provider abstraction are worth reimplementing?
-9. Should media asset tables exist in v1 or be deferred?
-10. Can media generation remain entirely optional without special-casing core story logic?
+- Open Dungeon has useful local image-generation and visual-continuity concepts, but they are not a reason to use it as the production fork.
+- The production base has no required media subsystem today; this is acceptable for v1.
+- Media must remain derived from accepted scene/story state and branch-aware.
+- Provider portability for Open Dungeon's image worker is deferred until image generation is actually scheduled.
+- Scene snapshots and visual continuity fields are sufficient near-term architecture commitments.
+- TTS/STT/video remain future providers behind the same local optional boundary.

 ## 88. Acceptance Criteria for Architecture

@@ -1410,11 +1395,11 @@ The architecture passes if:
 - provider-specific syntax stays outside Story Engine,
 - local providers can be substituted,
 - future image/video/audio/TTS types fit the output job/asset model,
- future STT fits the same provider architecture while feeding editable draft input rather than story state,
+- future STT fits the provider architecture while feeding editable draft input rather than story state,
 - generated media never automatically becomes canon,
 - abandoned-history media remains recoverable but inactive.

-## 89. Current Recommendation
+## 89. Selected Contract

 Use this conceptual contract:

@@ -1422,25 +1407,16 @@ Use this conceptual contract:
 Authoritative Story
       |
       v
-Scene Snapshot
+Scene Snapshot / Scene Packet
       |
       v
-Scene Packet
+Optional Media Coordinator
       |
-       v
-Media Coordinator
-       |
-       +--> Local Image Provider
-       +--> Local Video Provider
-       +--> Local Audio Provider
-       +--> Local TTS Provider
-       |
-       v
-Media Asset + Provenance
+       +--> Image Provider
+       +--> Video Provider
+       +--> Audio Provider
+       +--> TTS Provider
+       +--> STT Provider (draft input path)
 ```

-The media subsystem should depend on the story engine.
-
-The story engine should not depend on the media subsystem.
-
-That one-way dependency is the most important architectural requirement in this document.
+No production media provider is required for v1.
@@ -1,6 +1,6 @@
 # Phase 0B — Codex Initial Validation Brief

-**Status:** Ready for execution  
+**Status:** COMPLETE / HISTORICAL — do not execute as a production prompt
 **Purpose:** Run a focused first round of local validation on the three finalist repositories and return a recommendation based on what was actually learned.

 ## 1. Goal
@@ -1,6 +1,6 @@
 # Phase 0B — Codex Local Validation Handoff

-**Status:** Ready for execution  
+**Status:** COMPLETE / HISTORICAL — do not execute as a production prompt
 **Purpose:** Validate the Phase 0A recommendation using local builds, tests, offline runtime observation, and tightly scoped experiments.  
 **Stop rule:** Do not begin production implementation.

@@ -1,3 +1,5 @@
+> **Planning review note (2026-09-01):** This is the coding agent's Phase 0B evidence report. It is retained substantially as delivered. Some recommendations/open questions in the report were superseded during planning review: ai-adventure is an implementation reference rather than the project specification; no automatic abandoned-history cleanup is required in v1; Open Dungeon media portability is deferred; and the architecture decision is closed in ADR 009/010 and `TECHNICAL-DESIGN.md`.
+
 # Phase 0B — Local Validation Findings and Recommendation

 **Date:** 2026-09-01
@@ -0,0 +1,49 @@
+# Planning Update Summary — Post Phase 0B Review
+
+**Date:** 2026-09-01  
+**Purpose:** Review aid. This file summarizes planning changes made after accepting the ten architecture decisions from the Phase 0B review.
+
+## New Decisions Recorded
+
+1. AI-DnD is the production base at pinned Phase 0B commit `d72f7c1b...`.
+2. AI-DnD's browser/service/story-tree/memory/context foundation is retained as the ownership center.
+3. The non-destructive head-cursor Undo/Redo spike is promoted into the production design, but the disposable spike is not treated as merge-ready production code.
+4. Narrative state will use explicit typed events/absolute assignments inspired by ai-adventure, not AI-DnD's relative-delta protocol.
+5. ai-adventure is an implementation reference, not the product specification.
+6. Open Dungeon is a UX/media reference only.
+7. Abandoned history is retained and marked disposable; no automatic cleanup is required in v1.
+8. Export/import must preserve active head position as part of the history work.
+9. Imported knowledge will be a separate first-class subsystem rather than an extension of Story Cards.
+10. Future image/video/audio/TTS/STT extension contracts remain, but no media generation is required for v1.
+11. Local-only inference may span user-controlled machines: same-host Ollama is the default, but an explicitly configured trusted-LAN Ollama host is supported in v1 without exposing the storyteller UI/API to the LAN.
+
+## Documents Materially Revised
+
+- `README.md`
+- `SPECIFICATION.md`
+- `TECHNICAL-DESIGN.md`
+- `DATA-MODEL.md`
+- `STORY-BRANCH-SEMANTICS.md`
+- `CONTEXT-AND-MEMORY.md`
+- `IMPORTED-KNOWLEDGE-DESIGN.md`
+- `SECURITY-THREAT-MODEL.md`
+- `V1-ACCEPTANCE-TESTS.md`
+- `BUILD-MILESTONES.md`
+- `RESEARCH-PLAN.md`
+- `CODEX-HANDOFF-NOTE.md`
+- `004-local-only-production.md`
+- `005-branch-preserving-history.md`
+- `008-phase0-before-build-plan.md`
+
+## New ADRs
+
+- `009-ai-dnd-production-base.md`
+- `010-explicit-typed-narrative-state-events.md`
+
+## Historical Evidence Intentionally Preserved
+
+The Phase 0A candidate reports and the coding agent's `PHASE-0B-RECOMMENDATION.md` remain research evidence. They may contain assumptions that are superseded by the current planning documents. They are not silently rewritten to make the historical analysis appear as if it had reached later conclusions originally.
+
+## Coding Prompt Status
+
+No next Codex implementation prompt is included in this revision.
@@ -1,155 +1,173 @@
 # Adventure Storyteller Planning Package

-This package contains the current product requirements, provisional architecture, Phase 0 research, detailed subsystem designs, acceptance tests, and the Codex Phase 0B validation handoff for the local-only interactive-story project.
+**Status:** Phase 0 complete; architecture selected; planning revision ready for review.  
+**Production coding:** Not yet authorized. Review this package before preparing the first implementation prompt.

-## Current Status
+This package contains the current product requirements, final Phase 0 architecture decisions, detailed subsystem designs, acceptance tests, research evidence, and the production milestone plan for the local-only interactive-story project.

-Phase 0A static research is complete.
+## Current Decision

-The project is now ready for **Phase 0B local validation** of the three finalists:
+Phase 0A static research and Phase 0B local validation are complete.

-1. AI-DnD
-2. Open Dungeon
-3. ai-adventure
+The production starting point is:

-**Do not begin production implementation yet.**
+> **Fork AI-DnD at upstream commit `d72f7c1bda0f34fccd84afb7a25c34eb01c901de`.**

-The purpose of Phase 0B is to validate the fork/base decision and resolve the remaining architecture questions with real builds, tests, offline runs, and tightly scoped experiments.
+The selection is based on measured Phase 0B behavior, not feature count. AI-DnD already contains the highest-value structural machinery: browser UI, FastAPI service boundary, SQLite persistence, parent-linked story history, alternate takes, branch-aware state snapshots, local Ollama operation, branch-scoped memory, prompt/context inspection, streaming, export/import, and a substantial automated test suite.
+
+The selected composition of ideas is:
+
+```text
+AI-DnD production base
+  + ai-adventure state/event/commit/checkpoint/privacy patterns
+  + Open Dungeon story-reading and future-media UX patterns
+  + Chronicler memory-authority concepts
+  + Interactive Fiction Framework canon/validation concepts
+  + Gamentic provider-neutral media concepts
+```
+
+This is **not** a repository merge. AI-DnD is the ownership center. Other projects are implementation references only unless a later milestone explicitly reimplements a compatible idea.
+
+## Phase 0B Findings That Changed the Plan
+
+Phase 0B confirmed the fork choice while correcting several Phase 0A assumptions:
+
+- AI-DnD's shipped Undo was destructive and had no Redo.
+- A disposable spike proved non-destructive head-cursor Undo/Redo in three backend files while preserving branch-scoped memory isolation.
+- A new continuation written after Undo can fork from the moved-back head while retaining the abandoned future.
+- AI-DnD's current relative-delta world-state protocol can produce semantically wrong state under realistic context even when the proposal is syntactically valid.
+- Production narrative state will therefore use explicit typed events/absolute assignments inspired by ai-adventure rather than AI-DnD's relative-delta protocol.
+- AI-DnD requires offline hardening: `tiktoken` attempts a first-use CDN fetch and the SPA requests Google Fonts at runtime.
+- AI-DnD's export format must preserve the active head position; otherwise export/import can silently redo an undone story.
+- AI-DnD Story Cards are not a sufficient imported-knowledge store because they are not designed for the required classification, provenance, chunking, and lineage semantics.
+- Open Dungeon remains useful for UX/media ideas but is no longer a serious production-fork candidate.
+- ai-adventure is not the production base but is the strongest implementation reference for authoritative typed state events, head movement, checkpoints, replay, and narrow local-only behavior.
+
+See `PHASE-0B-RECOMMENDATION.md` for the coding agent's evidence. That report is retained as research evidence; the planning documents in this package record the decisions made after reviewing it.

 ## Document Authority

 Use the documents in this order when requirements appear to conflict:

-1. `SPECIFICATION.md` — product requirements and desired behavior.
-2. Detailed design/behavior documents listed below — elaborations of the specification.
-3. `V1-ACCEPTANCE-TESTS.md` — observable pass/fail interpretation of v1 requirements.
-4. `TECHNICAL-DESIGN.md` — provisional implementation direction, subject to Phase 0B findings.
-5. Phase 0A reports — research evidence and candidate analysis.
-6. `BUILD-MILESTONES.md` — intentionally incomplete until the fork/architecture decision is made.
+1. `SPECIFICATION.md` — product requirements and required behavior.
+2. Detailed behavior/design documents:
+   - `STORY-BRANCH-SEMANTICS.md`
+   - `CONTEXT-AND-MEMORY.md`
+   - `IMPORTED-KNOWLEDGE-DESIGN.md`
+   - `SECURITY-THREAT-MODEL.md`
+   - `MEDIA-EXTENSION-CONTRACT.md`
+   - `BROWSER-UX-SPEC.md`
+   - `DATA-MODEL.md`
+3. `V1-ACCEPTANCE-TESTS.md` — observable pass/fail contract.
+4. `TECHNICAL-DESIGN.md` — selected implementation architecture.
+5. Foundational ADRs (`001-...md` through the current ADR set).
+6. `BUILD-MILESTONES.md` — implementation sequence; it does not override product behavior.
+7. Phase 0 research reports — evidence and historical findings.

-The detailed design documents describe target behavior; they do not force a particular repository schema when an equivalent implementation satisfies the behavior.
+Candidate repositories and research reports are **not** specifications. In particular, ai-adventure is an implementation reference for selected patterns; its behavior does not override this package.

-## Recommended Reading Order for Codex
+## Foundational Decisions

-### A. Product and architectural intent
-
-1. `SPECIFICATION.md`
-2. `DATA-MODEL.md`
-3. `STORY-BRANCH-SEMANTICS.md`
-4. `CONTEXT-AND-MEMORY.md`
-5. `IMPORTED-KNOWLEDGE-DESIGN.md`
-6. `SECURITY-THREAT-MODEL.md`
-7. `MEDIA-EXTENSION-CONTRACT.md`
-8. `BROWSER-UX-SPEC.md`
-
-### B. Test contract
-
-9. `TEST-CAMPAIGN-FIXTURE.md`
-10. `V1-ACCEPTANCE-TESTS.md`
-
-### C. Provisional architecture and research
-
-11. `TECHNICAL-DESIGN.md`
-12. `RESEARCH-PLAN.md`
-13. `reports/PHASE-0A-STATUS.md`
-14. `reports/PRELIMINARY-RECOMMENDATION.md`
-15. `reports/REUSE-MATRIX.md`
-16. Candidate-specific reports in `reports/`
-
-### D. Execute
-
-17. `PHASE-0B-CODEX-HANDOFF.md`
-
-## Core Product Decisions Already Settled
-
-The Phase 0B investigation should treat these as requirements rather than questions:
+The following are settled for v1:

 - browser-first UI,
- local-only v1 runtime,
- local Ollama inference,
- application-owned authoritative story state,
- complete retained transcript,
+- local-only runtime across user-controlled local infrastructure,
+- Ollama inference with same-host loopback as default and explicitly configured trusted-LAN inference supported,
+- single-user deployment,
+- AI-DnD production base at the pinned Phase 0B commit,
+- application-owned authoritative state,
+- complete retained transcript/history,
 - simple user-facing Undo/Redo/Retry/Save Point semantics,
- non-destructive internal lineage,
- abandoned history retained but marked disposable; cleanup later,
- at least five Undo operations; unlimited preferred if technically straightforward,
- Redo and Retry supported,
- named checkpoints retained until explicitly deleted,
- genre-agnostic core schema,
- imported knowledge classes: Canon / Reference / Inspiration,
- local retrieval and embeddings,
+- non-destructive head-cursor history internally,
+- new write after moving backward creates a new continuation while retaining the old future,
+- abandoned history is retained and marked disposable; **no automatic cleanup is required in v1**,
+- named checkpoints remain until explicitly deleted,
+- genre-agnostic core state,
+- explicit typed narrative-state events/absolute assignments rather than ambiguous relative deltas,
+- hybrid state model: validated events plus state snapshots/cache,
+- branch/lineage-safe summaries and memories,
+- imported knowledge is a separate first-class subsystem rather than an extension of AI-DnD Story Cards,
+- knowledge classes: Canon / Reference / Inspiration,
+- local lexical retrieval plus local semantic retrieval where practical,
 - prompt/context provenance and inspection,
- no cloud inference, telemetry, automatic web retrieval, remote runtime assets, shell/MCP/general plugin execution,
- future local image/video/TTS/STT capability must remain possible without coupling it to the core story engine.
+- export/import must preserve active branch **and active head position**, including an undone position,
+- no cloud/Internet inference, telemetry, automatic web retrieval, remote runtime assets, shell/MCP/general plugin execution,
+- LAN inference is distinct from LAN exposure of the storyteller UI/API; the latter is not required for v1,
+- future local image/video/audio/TTS/STT support remains optional and decoupled from the story engine.

-## Detailed Documents
+## Phase 0 Status

- `DATA-MODEL.md` — conceptual target data model and authority/state structures.
- `STORY-BRANCH-SEMANTICS.md` — exact Undo, Redo, Retry, Edit, checkpoint, restore, and disposable-history behavior.
- `CONTEXT-AND-MEMORY.md` — context construction, authority hierarchy, summaries, memory, retrieval, provenance, token budgeting.
- `IMPORTED-KNOWLEDGE-DESIGN.md` — import, classification, chunking, local indexing, retrieval, provenance, isolation, and prompt-injection handling.
- `SECURITY-THREAT-MODEL.md` — local trust boundary, network policy, untrusted input handling, browser security, and offline acceptance.
- `MEDIA-EXTENSION-CONTRACT.md` — future image, video, audio, TTS, and STT extension boundaries. Media remains optional and derived from story state.
- `BROWSER-UX-SPEC.md` — user-facing browser workflow and advanced inspection surfaces.
- `TEST-CAMPAIGN-FIXTURE.md` — deterministic campaign fixture for comparing candidates and later regression testing.
- `V1-ACCEPTANCE-TESTS.md` — black-box requirements and release gate.
+### Complete

-## Phase 0A Research
+- candidate discovery and triage,
+- static architecture/privacy/licensing review,
+- local clone/build/test validation,
+- real Ollama testing,
+- offline/network observation,
+- AI-DnD strip-down/entanglement checks,
+- Open Dungeon history-retrofit analysis,
+- ai-adventure Ollama/service-boundary checks,
+- AI-DnD non-destructive Undo/Redo spike,
+- referee/state-protocol follow-up,
+- export/import head-position follow-up,
+- Story Card lineage review,
+- Postgres removability review,
+- production fork decision,
+- production architecture decision.

-Static repository research was completed on 2026-09-01.
+### Deferred to implementation/release validation

-Key reports:
+These do not block the architecture decision:

- `reports/PHASE-0A-STATUS.md`
- `reports/PRELIMINARY-RECOMMENDATION.md`
- `reports/REUSE-MATRIX.md`
- `reports/AI-DND-ANALYSIS.md`
- `reports/OPEN-DUNGEON-ANALYSIS.md`
- `reports/AI-ADVENTURE-ANALYSIS.md`
- `reports/PRIVACY-STATIC-ANALYSIS.md`
- `reports/LICENSING-REUSE.md`
- `reports/SOURCE-INDEX.md`
+- comparative recommendation of narrator/state models for real users,
+- multi-hour/100-turn long-run behavior,
+- detailed concurrency behavior beyond the single-user turn lock,
+- actual future image/video/TTS/STT provider integration,
+- abandoned-history cleanup UI/policy (not required in v1).

-Current preliminary architecture hypothesis:
+## Recommended Reading Order for the Next Implementation Stage
+
+Do not convert this into a coding prompt until the package review is approved.
+
+When implementation planning resumes, read:
+
+1. `SPECIFICATION.md`
+2. `TECHNICAL-DESIGN.md`
+3. `BUILD-MILESTONES.md`
+4. `STORY-BRANCH-SEMANTICS.md`
+5. `DATA-MODEL.md`
+6. `CONTEXT-AND-MEMORY.md`
+7. `IMPORTED-KNOWLEDGE-DESIGN.md`
+8. `SECURITY-THREAT-MODEL.md`
+9. `BROWSER-UX-SPEC.md`
+10. `V1-ACCEPTANCE-TESTS.md`
+11. ADRs, especially the production-base and narrative-state-event decisions
+12. Phase 0B reports only as supporting evidence
+
+## Workflow From Here

 ```text
-AI-DnD production base
-  + ai-adventure trust/commit/privacy rules
-  + Open Dungeon scene/media UX patterns
-  + Chronicler memory authority tiers
-  + Interactive Fiction Framework Story Bible authority/validation
-  + Gamentic media-provider abstraction
+Phase 0 research and spikes         COMPLETE
+        |
+        v
+Architecture/fork decision         COMPLETE
+        |
+        v
+Planning package revision          CURRENT REVIEW
+        |
+        v
+Approve planning package
+        |
+        v
+Prepare one implementation prompt
+for Production Milestone 1
+        |
+        v
+Implement and review milestone-by-milestone
 ```

-This is a hypothesis to test, not a fork decision.
+## Stop Rule

-## Overall Workflow
+**Do not begin production coding from this package yet.**

-```text
-Specification + detailed behavioral designs
-        |
-        v
-Phase 0A static research
-        |
-        v
-Phase 0B local validation
-        |
-        v
-Fork / architecture decision
-        |
-        v
-SPECIFICATION v1.0
-TECHNICAL-DESIGN v1.0
-        |
-        v
-Detailed BUILD-MILESTONES.md
-        |
-        v
-Production implementation
-```
-
-## Important Stop Rule
-
-Phase 0B ends with evidence and a recommendation.
-
-Codex should **not** begin production coding, repo conversion, or broad feature implementation until the Phase 0B results have been reviewed and the production base has been selected.
+The current action is to review the planning changes. No replacement Codex prompt has been prepared in this revision.
@@ -1,9 +1,11 @@
 # Adventure Storyteller — Phase 0 Research Plan

-**Status:** Ready for execution  
+**Status:** Complete — Phase 0 closed 2026-09-01  
 **Phase:** 0 — Research, Validation & Architecture  
 **Goal:** Determine what to build, what to fork/reuse, and finalize the technical design before production implementation begins.

+**Outcome:** AI-DnD selected as the production base; non-destructive head-cursor history and explicit typed narrative-state events selected; production milestones now defined in `BUILD-MILESTONES.md`.
+
 ## 1. Why Phase 0 Exists

 The project has several promising open-source starting points. They differ substantially in:
@@ -28,6 +30,26 @@ Phase 0 therefore ends when we can answer:

 No production feature work should begin before that decision unless explicitly authorized.

+## 1A. Phase 0 Completion Summary
+
+Phase 0A static research and Phase 0B local validation are complete.
+
+Final dispositions:
+
+- AI-DnD — production fork/base at `d72f7c1bda0f34fccd84afb7a25c34eb01c901de`.
+- ai-adventure — primary implementation reference for authoritative typed state events, checkpoint/head/replay semantics, and narrow local-only behavior.
+- Open Dungeon — UX and future-media reference only.
+
+Critical Phase 0B prototype results:
+
+- non-destructive Undo/Redo with a movable active head was demonstrated on AI-DnD without deleting history and without breaking branch-scoped memory isolation,
+- export/import must preserve active head position,
+- AI-DnD's relative-delta state protocol should not be retained as the generic narrative-state contract,
+- imported knowledge should be a separate subsystem rather than Story Cards,
+- runtime offline hardening is required for tokenizer data and fonts.
+
+The original milestone text below is retained as the research execution record.
+
 ## 2. Candidate Repositories

 Initial candidates:
@@ -575,4 +597,22 @@ Phase 0 is complete only when:
 - the technical design is v1.0,
 - the actual implementation milestone plan has been written.

-At that point, production implementation can begin.
+At that point, production implementation becomes eligible to begin, but still requires explicit approval and a milestone-specific execution prompt.
+
+
+## 17. Final Phase 0 Closure Record
+
+Phase 0 definition of done is satisfied for architecture/planning purposes:
+
+- finalists cloned and run,
+- test suites measured,
+- Ollama exercised locally,
+- offline/network behavior investigated,
+- critical history/state uncertainties prototyped,
+- fork/build strategy selected,
+- specification revised to v1.0,
+- technical design revised to v1.0,
+- production build milestones written,
+- foundational ADRs updated/added.
+
+No production implementation prompt is part of this research plan.
@@ -1,6 +1,6 @@
 # Adventure Storyteller — Security Threat Model

-**Status:** Draft v0.1  
+**Status:** v1.0 — local-only hardening requirements informed by Phase 0B  
 **Purpose:** Define the security and privacy boundaries for a local-only interactive storytelling application.

 ## 1. Security Objective
@@ -79,7 +79,9 @@ Trusted to receive:
 - retrieved local knowledge,
 - user input.

-For v1, Ollama should be accessed through loopback unless the user explicitly configures otherwise in a future release.
+For v1, Ollama may run either on the storyteller machine or on an explicitly configured machine on the user's trusted LAN. Same-host loopback remains the default. When Ollama is on another LAN host, story prompt/context data necessarily crosses the local network to that approved inference machine.
+
+The inference host should restrict access to Ollama using host firewall/network controls appropriate to the local environment. LAN inference does not authorize LAN exposure of the storyteller UI/API.

 ### 4.3 Local browser

@@ -124,10 +126,11 @@ Preferred allowed v1 network paths:
 ```text
 Browser -> local storyteller application
 Storyteller -> 127.0.0.1 Ollama
+        OR -> explicitly approved trusted-LAN Ollama host
 Storyteller -> optional explicitly configured local media service
 ```

-Everything else should be denied or absent.
+Everything else should be denied or absent. An approved LAN Ollama host is inside the v1 local trust boundary; arbitrary Internet/cloud inference is not.

 ## 7. Default Bind Addresses

@@ -139,10 +142,13 @@ Preferred defaults:
 ```

 ### Ollama
+Same-host default:
 ```text
 127.0.0.1
 ```

+A separate inference machine may listen on an explicitly chosen LAN interface/address as required for the storyteller to reach it. That host should use firewall/network policy to limit access to trusted clients.
+
 ### Media services
 ```text
 127.0.0.1
@@ -156,7 +162,7 @@ Do not bind to:

 by default.

-LAN exposure may be considered later as a separate explicit feature.
+LAN exposure of the **storyteller UI/API** may be considered later as a separate explicit feature. This does not prohibit the v1 storyteller backend from connecting outbound to an approved LAN Ollama host.

 ## 8. Forbidden v1 Network Behavior

@@ -209,17 +215,21 @@ creates a data-exfiltration path.

 For v1:

- prefer a fixed local Ollama endpoint,
- or allow only loopback endpoints.
+- default to same-host loopback Ollama,
+- allow an explicitly configured trusted-LAN Ollama endpoint,
+- surface the effective destination clearly in configuration/diagnostics,
+- reject or keep arbitrary public Internet endpoints outside normal v1 configuration.

-Possible allowed forms:
+Examples of allowed forms include:

 ```text
 http://127.0.0.1:11434
 http://localhost:11434
+http://192.168.1.50:11434
+http://inferencebox.local:11434
 ```

-Anything else should be rejected unless a future advanced configuration explicitly enables it.
+The LAN hostname/address must be an intentional user configuration. Do not infer that every non-loopback endpoint is trusted merely because it resolves.

 ## 11. Imported Files Must Be Data Only

@@ -716,15 +726,9 @@ No automatic runtime update check is required.

 ## 48. Dependency Risk

-Phase 0B should inventory:
- Python dependencies,
- npm dependencies,
- native modules,
- optional cloud SDKs,
- abandoned packages,
- packages with install/postinstall scripts.
+Phase 0B inventoried the major inherited surfaces in the selected base and identified concrete removals and runtime leaks. Production milestones must continue dependency review as code is stripped and upgraded, including Python/npm/native modules, optional cloud SDKs, install/postinstall behavior, and security advisories.

-Prefer removing dependencies that only support unwanted cloud features.
+Prefer removing dependencies that only support unwanted cloud/hosted features.

 ## 49. Supply Chain

@@ -766,22 +770,22 @@ The application should only have permissions needed to:

 It should not need broad system access.

-## 53. LAN Mode — Future Only
+## 53. Storyteller LAN Access — Future Only

-If LAN access is added later, it must be a distinct security mode.
+LAN **inference** is supported in v1: the loopback-bound storyteller may connect outbound to an explicitly configured trusted-LAN Ollama machine.

-It should require:
+LAN access to the **storyteller browser UI/API** is different and remains a future security mode. If added later, it should require:
 - explicit enablement,
 - authentication,
 - TLS or trusted local network assumptions,
 - host/firewall documentation,
 - session protection.

-Do not accidentally inherit LAN exposure because a candidate project binds to all interfaces.
+Do not accidentally inherit storyteller LAN exposure because a candidate project binds to all interfaces.

 ## 54. Tailscale / VPN Access

-Same as LAN mode.
+Treat remote access to the storyteller UI/API like storyteller LAN access.

 Useful later, but not a v1 requirement.

@@ -1064,6 +1068,35 @@ Classify each hit:
 - development-only,
 - false positive.

+## 71A. Phase 0B Confirmed Risks in the Selected AI-DnD Base
+
+Phase 0B runtime validation found specific inherited behaviors that production must remove or package differently:
+
+1. **First-use tokenizer download**
+   - `tiktoken` attempted to fetch `cl100k_base` from a Microsoft-hosted endpoint on the first isolated turn.
+   - Production must bundle/cache the required encoding or replace that path so ordinary story use never depends on Internet access.
+
+2. **Runtime Google Fonts**
+   - the SPA requested Google-hosted font assets and the existing CSP permits those hosts.
+   - Production must self-host required fonts or use local/system fonts and remove the remote CSP allowances.
+
+3. **Unneeded cloud/hosted surface**
+   - hosted auth/multi-user/demo/analytics/Render/Neon/Postgres/cloud-provider paths are outside the v1 trust model.
+   - Remove these paths rather than simply hiding them when practical.
+
+4. **QuickJS/campaign scripting**
+   - executable campaign scripting is outside the v1 trust boundary.
+   - Remove/disable the engine and replace any test-only instrumentation that depended on it.
+
+5. **Endpoint policy mismatch**
+   - inherited network guarding is aimed at hosted deployment behavior, not at preventing accidental story-data exfiltration.
+   - Production should default to loopback Ollama, explicitly support a configured trusted-LAN Ollama host, and reject/avoid arbitrary public Internet inference endpoints.
+
+6. **Postgres is removable**
+   - Phase 0B found no architectural blocker to dropping Postgres support; SQLite remains the v1 store.
+
+These are production hardening requirements, not optional polish.
+
 ## 72. Phase 0B Runtime Network Test

 After all dependencies/models are preinstalled:
@@ -1083,13 +1116,13 @@ After all dependencies/models are preinstalled:
 13. generate local image in Open Dungeon if evaluated,
 14. monitor sockets/DNS.

-Record every non-loopback attempt.
+Record every non-loopback attempt and classify it as approved trusted-LAN inference/media traffic or unexpected traffic.

 ## 73. Runtime Pass Condition

 For ordinary v1 story operation:

-> No story content or imported content leaves loopback or explicitly approved local endpoints.
+> No story content or imported content leaves explicitly approved local infrastructure. Same-host loopback and explicitly configured trusted-LAN Ollama/media endpoints are permitted; Internet/cloud destinations are not.

 Unexpected DNS/HTTP attempts must be explained and removed or disabled.

@@ -1098,7 +1131,7 @@ Unexpected DNS/HTTP attempts must be explained and removed or disabled.
 Minimum v1 acceptance:

 - app works with outbound Internet blocked,
- Ollama connection remains local,
+- Ollama connection remains within explicitly approved local infrastructure,
 - no cloud API key required,
 - no external telemetry,
 - imported Markdown does not execute script,
@@ -1139,30 +1172,43 @@ Potential later improvements:

 These are not required for initial v1 unless Phase 0B reveals a specific need.

-## 77. Current Security Recommendation
+## 77. Selected Security Posture

-The production architecture should intentionally be narrow:
+The production architecture is intentionally narrow:

 ```text
 NO:
 cloud providers
+hosted auth/accounts
 web tools
 general plugins
 MCP
 shell execution
+QuickJS/campaign scripting
 remote document fetch
+runtime CDN/fonts/assets
 telemetry
 analytics
+remote embeddings/vector stores

 YES:
 local browser
-local app
+local FastAPI app
 local SQLite/files
-local Ollama
-local retrieval
-optional local media services
+local-infrastructure Ollama (same-host or approved trusted-LAN)
+local lexical/semantic retrieval
+optional explicitly configured local media services in the future
 ```

-The safest implementation is not the one with the most configurable providers.
+Required production defaults:

-It is the one with the fewest ways story data can leave the machine accidentally.
+- storyteller binds loopback by default,
+- Ollama endpoint is same-host loopback by default,
+- explicitly configured trusted-LAN Ollama endpoints are supported,
+- arbitrary public/Internet inference endpoints are rejected or absent from normal v1 configuration,
+- tokenizer assets required for runtime are packaged locally,
+- browser assets/fonts are local,
+- no cloud API-key UI exists in v1,
+- outbound-network-blocked acceptance testing is part of release gating.
+
+The safest implementation is the one with the fewest accidental paths for story data to leave the machine.
@@ -1,6 +1,6 @@
 # Adventure Storyteller — Specification

-**Status:** Draft v0.1  
+**Status:** v1.0 — approved after Phase 0B architecture selection  
 **Purpose:** Define what the system must do, independent of implementation choice.

 ## 1. Product Goal
@@ -17,7 +17,7 @@ The application must preserve story continuity, authoritative world state, long-

 1. **Local first**
   - Primary operation must not require Internet access.
-   - AI inference must use a local Ollama instance for v1.
+   - AI inference must use Ollama on user-controlled local infrastructure for v1; same-host loopback is the default, and an explicitly configured trusted-LAN Ollama host is supported.
   - Imported story/reference material must remain local.
   - No telemetry, analytics, remote fonts, remote assets, or automatic external content retrieval in the production configuration.
   - No cloud inference providers in v1.
@@ -36,6 +36,8 @@ The application must preserve story continuity, authoritative world state, long-
   - Every accepted turn should be recoverable.
   - Users must be able to return to an earlier point.
   - Restoring an earlier point should preserve abandoned future history as an alternate branch rather than destructively erasing it.
+   - Moving backward must move the active story head without deleting retained turns.
+   - If the user continues differently from a moved-back head, the prior future becomes retained/disposable history rather than being overwritten.

 5. **Closed-corpus authority**
   - Story canon may come from:
@@ -241,7 +243,7 @@ Potential mechanisms:
 - local embeddings generated through Ollama,
 - hybrid lexical/vector retrieval.

-The final mechanism will be selected during Phase 0 research.
+Selected v1 direction: local hybrid retrieval using a deterministic lexical index plus local Ollama semantic embeddings where enabled. Lexical retrieval must remain usable if embeddings fail or are disabled.

 Requirements:
 - no remote vector database,
@@ -267,11 +269,15 @@ This should include, directly or indirectly:

 ## 12. Local-Only Security Requirements

+For v1, **local-only** means the storyteller, storage, inference, and retrieval remain on user-controlled local infrastructure and require no Internet/cloud service. Components may run on more than one machine on a trusted LAN.
+
 Production defaults must:

- bind the application to loopback unless intentionally configured otherwise,
- connect to Ollama through a local/approved endpoint,
- reject or warn on non-local model endpoints,
+- bind the storyteller application/UI/API to loopback unless a later explicit storyteller-LAN mode is enabled,
+- default Ollama to same-host loopback,
+- allow an explicitly configured trusted-LAN Ollama endpoint for narration, state extraction, summarization, and local embeddings,
+- make the configured inference destination visible/inspectable,
+- reject or explicitly gate arbitrary public/Internet model endpoints,
 - include no telemetry,
 - include no analytics,
 - avoid remote fonts and CDN-delivered runtime dependencies,
@@ -282,7 +288,7 @@ Production defaults must:
 - document all outbound network behavior,
 - allow operation with the machine disconnected from the Internet.

-A future LAN-access mode may be considered separately.
+LAN inference is supported in v1. LAN access to the storyteller web UI/API is a separate feature and may be considered later; enabling one must not implicitly enable the other.

 ## 13. Browser-First Interface

@@ -293,12 +299,13 @@ Expected areas include:
 - campaign selection,
 - story transcript,
 - input composer,
- checkpoint/story-tree navigation,
+- Save Point/history navigation,
 - narrative state inspector,
 - knowledge/library management,
 - settings,
 - prompt/context inspection,
- future media gallery.
+- future media gallery,
+- reserved local speech-to-text input affordance where appropriate.

 Terminal tooling may exist for administration, migration, diagnostics, or development, but must not be the primary user experience.

@@ -332,7 +339,9 @@ The system should reserve a generic media abstraction for future:
 - storyboards,
 - recap images,
 - multi-turn video clips,
- audio/voice.
+- audio/ambience,
+- text-to-speech,
+- speech-to-text draft input.

 Media generation must remain optional and separable from the core story engine.

@@ -344,19 +353,23 @@ The core application should eventually be able to call provider adapters such as
 Media Provider
 ├── Image Provider
 ├── Video Provider
-└── Audio Provider
+├── Audio Provider
+├── TTS Provider
+└── STT Provider
 ```

 The story engine must not depend on a specific image or video backend.

-Potential local media systems can be evaluated later.
+Potential local media systems can be evaluated later. Speech-to-text output must remain editable draft user input and must enter the story through the normal submission/commit path.

 ## 16. Export and Backup

-A campaign export should eventually be capable of including:
+A campaign export must preserve enough information to restore the exact active story position, including an active head that is behind the retained tip after Undo. The export should be capable of including:

 - transcript,
 - branches,
+- active branch and active head position,
+- retained/disposable alternate history,
 - checkpoints,
 - structured state,
 - campaign configuration,
@@ -366,11 +379,11 @@ A campaign export should eventually be capable of including:
 - generated media metadata,
 - optionally generated media files.

-The export format should be portable and documented.
+The export format should be portable and documented. Importing a campaign must not silently advance the head to the newest retained turn when the exported campaign was intentionally positioned earlier.

 ## 17. Explicit Non-Goals for v1

-Unless Phase 0 changes the decision, v1 should not require:
+v1 does not require:

 - D&D or other RPG rules,
 - dice,
@@ -383,38 +396,39 @@ Unless Phase 0 changes the decision, v1 should not require:
 - automatic online content downloading,
 - image generation,
 - video generation,
+- text-to-speech,
+- speech-to-text,
 - mobile-native apps,
 - hosted SaaS deployment.

-## 18. Candidate Starting Projects
+## 18. Phase 0 Candidate Outcome

-Phase 0 will evaluate at minimum:
+Phase 0 evaluated the principal candidates and selected AI-DnD as the production base.

- Open Dungeon — `newideas99/open-dungeon`
- AI-DnD — `parththakkar106/AI-DnD`
- Local Adventure Engine / ai-adventure — `CaoRuiming/ai-adventure`
- aiMultiFool
- additional credible candidates discovered during research
+Disposition:

-Reference-only projects may include:
+- **AI-DnD** — production fork/base.
+- **ai-adventure / Local Adventure Engine** — primary implementation reference for typed authoritative state events, head/checkpoint/replay semantics, and narrow local-only behavior.
+- **Open Dungeon** — UX and future local-media reference only.
+- **Chronicler, Interactive Fiction Framework, Gamentic, and other reviewed projects** — concept/reference sources only as documented in the research reports.

- SillyTavern,
- RisuAI,
- KoboldAI,
- Chronicler,
- other local interactive-fiction or long-memory systems.
+The project will not mechanically merge candidate repositories.

-## 19. Acceptance Criteria for Specification v1.0
+## 19. Phase 0 Outcome and Specification v1.0 Status

-Before implementation planning begins, the project must have:
+Phase 0 satisfied the architecture-selection prerequisites for this specification:

- a selected base/fork strategy,
- confirmed licensing compatibility,
- confirmed local-only security approach,
- confirmed persistence/story-tree model,
- confirmed memory/retrieval strategy,
- confirmed browser architecture,
- confirmed Ollama integration model,
- confirmed campaign export/backup strategy,
- identified future media extension points,
- technical risks and tradeoffs documented.
+- production base selected: AI-DnD at the pinned Phase 0B commit,
+- licensing path confirmed as permissive for the selected base,
+- local-only hardening requirements identified,
+- story-history approach confirmed as non-destructive active-head movement over retained lineage,
+- state authority confirmed as application-owned with validated proposals,
+- narrative-state implementation direction selected: explicit typed events plus snapshots/cache,
+- memory/retrieval direction confirmed as local, lineage-aware, provenance-preserving, and authority-aware,
+- imported knowledge confirmed as a separate first-class subsystem,
+- browser architecture confirmed as React/Vite + FastAPI from the selected base,
+- Ollama integration validated locally,
+- export/import requirement expanded to preserve active head position,
+- future media extension points preserved without making media a v1 dependency.
+
+The implementation details are defined in `TECHNICAL-DESIGN.md`. Candidate-project behavior does not override this specification.
@@ -1,6 +1,6 @@
 # Adventure Storyteller — Story Branch Semantics

-**Status:** Draft v0.1  
+**Status:** v1.0 — behavior confirmed after Phase 0B  
 **Purpose:** Define exactly how Undo, Redo, Retry, Edit, Restore, checkpoints, and abandoned history should behave.

 ## 1. Design Goal
@@ -121,9 +121,7 @@ If the selected base architecture makes unlimited Undo substantially harder or u

 > At least five consecutive Undo operations.

-Technical validation during Phase 0B should determine whether unlimited Undo is straightforward.
-
-The final implementation should prefer unlimited Undo unless there is a concrete technical reason not to.
+Phase 0B demonstrated repeated non-destructive Undo well beyond the minimum five-step requirement. The selected head-cursor design should therefore support Undo across retained active-lineage history up to the root unless a later implementation defect forces a documented exception.

 ## 6. State Restoration on Undo

@@ -402,6 +400,8 @@ Restoring a checkpoint:
 4. restores compatible summary/memory lineage,
 5. prepares the story to continue from that position.

+Restore itself does not need to create a new branch immediately. The existing continuation remains the Redo/retained path until the user creates a different continuation; the first divergent write then creates the new continuation.
+
 The original later story remains retained as abandoned/disposable history.

 ## 21. Restore Does Not Delete
@@ -613,6 +613,19 @@ Every generated narrator take should preserve enough information to determine:

 This remains true even for abandoned/disposable history until it is explicitly pruned.

+## 36A. Export / Import Must Preserve the Active Head
+
+Non-destructive Undo means retained history may extend beyond the current active head.
+
+Export must therefore preserve both:
+
+- the retained history/branch graph, and
+- the exact active branch/head position.
+
+Import must reopen the campaign at that active head. It must not infer that the newest retained turn is current merely because later history still exists.
+
+Backward compatibility may treat the retained tip as the head only for older export formats that contain no explicit head coordinate.
+
 ## 37. Failure During Retry / Edit / Continue

 If generation fails:
@@ -688,7 +701,7 @@ Preferred:

 - unlimited Undo across retained history.

-Phase 0B should determine whether the preferred behavior is already practical in the selected base.
+Phase 0B demonstrated that the preferred behavior is practical in the selected base. The production implementation should retain that capability while enforcing the correct campaign-root floor.

 ## 42. Example: Simple Mistake

@@ -791,45 +804,46 @@ as authoritative.

 If desired, the user may also edit the narration, but that is a separate operation.

-## 46. Phase 0B Validation Questions
+## 46. Phase 0B Findings Applied

-Codex should answer:
+Phase 0B established the following implementation facts for the selected AI-DnD base:

-1. Does AI-DnD already support unlimited practical Undo through its lineage model?
-2. How does AI-DnD distinguish retry takes from full branches?
-3. Can retry/edit preserve prior futures without exposing a complex branch UI?
-4. Can summaries and memories be reliably lineage-filtered after divergence?
-5. Does AI-DnD state rollback restore generic state independently of RPG mechanics?
-6. How difficult would it be to mark abandoned paths disposable without deleting them?
-7. In Open Dungeon, what exact modules assume destructive tail-deletion semantics?
-8. Can checkpoints be implemented as durable turn pointers without duplicating state?
-9. What is the cost of retaining all disposable text/state history in SQLite?
-10. Does any finalist currently leak abandoned branch memories into active retrieval?
+- shipped Undo was destructive and therefore did not satisfy this document,
+- alternate-take Retry and branch lineage were genuinely non-destructive,
+- a disposable spike demonstrated head-cursor Undo/Redo without deleting accepted turns,
+- writes below a moved-back head can fork through existing branch machinery,
+- branch-scoped memory isolation remained correct with real local embeddings,
+- practical repeated Undo across retained history worked beyond the minimum five-step requirement,
+- retry/add-take paths still need to be routed through the production fork-if-behind-head rule,
+- abandoned history still needs explicit disposable/inactive marking,
+- export/import must carry the active head coordinate or it silently redoes an undone story.
+
+These findings select an implementation direction; the disposable spike itself is not production code to merge unchanged.

 ## 47. Acceptance Criteria

 The final implementation must satisfy:

- Undo restores transcript and state together.
- At least five Undo steps are available; unlimited is preferred.
+- Undo restores transcript and state together by moving the active head, not deleting accepted turns.
+- At least five Undo steps are guaranteed; the selected architecture should support Undo across all retained active-lineage history up to the root.
 - Redo works until a new continuation is created.
 - Retry preserves alternate narrator takes.
 - Editing old user input creates a safe new continuation.
 - Editing narrator output re-evaluates state.
 - Named checkpoints remain until explicitly deleted.
 - Restoring a checkpoint does not delete later history.
+- Checkpoint restore may reuse the existing continuation until the first divergent write.
 - Abandoned history is retained and marked disposable.
- No automatic abandoned-history cleanup is required initially.
+- No automatic abandoned-history cleanup is required in v1.
 - Abandoned history does not influence active summaries, memories, state, or prompts.
 - Manual state/canon corrections are auditable.
+- Export/import preserves the exact active head even when retained history exists after it.
 - Normal UI does not require branch management.
- A future discarded-history recovery screen remains possible without schema redesign.
+- A future discarded-history recovery/cleanup screen remains possible without schema redesign.

-## 48. Current Recommendation
+## 48. Selected Implementation Model

-Use a simple linear user experience backed by non-destructive lineage.
-
-Conceptually:
+Use a simple linear user experience backed by retained lineage and a movable active head.

 ```text
 USER EXPERIENCE
@@ -838,19 +852,21 @@ Undo
 Redo
 Retry
 Edit
-Checkpoint
+Save Point
 Restore

        ↓

 INTERNAL MODEL

-Parent-linked history
+Parent-linked retained history
 Alternate takes
-State snapshots/events
-Active head
+Active branch + active head
+Retained branch tip/future
+Typed state events + snapshots/cache
 Disposable abandoned history
 Lineage-aware summaries/memory
+Exported active-head coordinate
 ```

-This provides recovery and correctness without forcing the user to manage a story tree.
+The selected AI-DnD base supplies most of the lineage infrastructure; production work replaces destructive Undo, adds Redo/checkpoints/disposable marking, and preserves the head through export/import.
@@ -1,6 +1,6 @@
 # Adventure Storyteller — V1 Acceptance Tests

-**Status:** Draft v0.1  
+**Status:** v1.0 planning/release contract — updated after Phase 0B  
 **Purpose:** Define black-box acceptance tests for finalist evaluation during Phase 0B and for the eventual v1 release.

 ## 1. Test Philosophy
@@ -229,18 +229,18 @@ Application requires:

 ---

-## A02 — Loopback Default
+## A02 — Storyteller Loopback Default

 **Priority:** REQUIRED FOR V1

 ### Steps
-Inspect application and model listener addresses.
+Inspect the storyteller web/API listener address.

 ### Pass
-Default services bind to loopback or another explicitly approved local-only address.
+The storyteller UI/API binds to loopback by default.

 ### Fail
-Application exposes privileged storyteller APIs on `0.0.0.0` by default without explicit configuration.
+Application exposes privileged storyteller APIs on `0.0.0.0` or the LAN by default without explicit storyteller-LAN configuration.

 ---

@@ -290,6 +290,34 @@ Transcript and authoritative current state are restored.

 ---

+## A06 — Trusted-LAN Ollama Inference
+
+**Priority:** REQUIRED FOR V1
+
+### Preconditions
+- storyteller and browser run on machine A,
+- Ollama runs on a separate user-controlled machine B on the trusted LAN,
+- required models are already installed,
+- outbound Internet access is blocked.
+
+### Steps
+1. Keep the storyteller UI/API bound to loopback on machine A.
+2. Configure the storyteller's Ollama endpoint to machine B.
+3. Verify model discovery/connection diagnostics.
+4. Generate at least three story turns.
+5. Trigger state extraction and embeddings/memory retrieval if enabled.
+6. Restart the storyteller and resume the campaign.
+7. Observe network destinations.
+
+### Pass
+- story operation succeeds through the explicitly configured LAN Ollama host,
+- no cloud API key or Internet access is required,
+- inference/model traffic goes only to the approved LAN host,
+- storyteller UI/API remains loopback-bound,
+- prompts, state, retrieved knowledge, and embedding inputs do not go to any unapproved destination.
+
+---
+
 # B. Basic Story Interaction

 ## B01 — Natural Language Action
@@ -431,6 +459,26 @@ Narrator follows campaign canon rather than imported lower-authority text.

 ---

+## C06 — Structured State Matches Accepted Narrative Consequence
+
+**Priority:** REQUIRED FOR V1
+
+### Purpose
+Catch semantically valid-looking state proposals that do not represent the accepted narration.
+
+### Steps
+1. Use a fixture action with an unambiguous state consequence, such as moving an item, changing location, or applying a known condition.
+2. Run the turn under a realistic application context, not an isolated extraction prompt.
+3. Inspect accepted state events and resulting state.
+
+### Pass
+- accepted state reflects the narration's intended consequence,
+- event semantics are explicit and unambiguous,
+- malformed or contradictory proposals are rejected/repaired rather than silently accepted,
+- the implementation does not rely on one ambiguous numeric value being interpreted as either an absolute value or a relative delta.
+
+---
+
 # D. Undo, Redo, Retry, and Checkpoints

 ## D01 — Undo One Turn
@@ -1082,6 +1130,27 @@ Privileged local APIs do not allow arbitrary wildcard cross-origin writes.

 ---

+## H11 — No First-Use Runtime Asset Download
+
+**Priority:** REQUIRED FOR V1
+
+### Preconditions
+- application installed,
+- Ollama models installed,
+- fresh application data/cache where practical,
+- outbound Internet blocked.
+
+### Steps
+1. Start the application.
+2. Open the browser UI.
+3. Generate the first story turn.
+4. Monitor DNS/network attempts.
+
+### Pass
+The application does not attempt to fetch tokenizer encodings, fonts, scripts, stylesheets, or other runtime assets from the Internet.
+
+---
+
 # I. Export, Backup, and Restore

 ## I01 — Export Campaign
@@ -1146,6 +1215,25 @@ No external API credentials are embedded in campaign export.

 ---

+## I07 — Export/Import Preserves an Undone Active Head
+
+**Priority:** REQUIRED FOR V1
+
+### Steps
+1. Create a story with at least five accepted turns.
+2. Undo at least two turns without deleting the retained future.
+3. Export the campaign while the active head is behind the retained tip.
+4. Import into a fresh data directory.
+5. Open the campaign.
+
+### Pass
+- the campaign opens at the exact exported active head,
+- later retained turns are still present as retained/disposable history,
+- import does not silently Redo to the newest retained turn,
+- Redo/recovery behavior remains coherent after import.
+
+---
+
 # J. Genre Independence

 ## J01 — Science-Fiction Campaign
@@ -1493,8 +1581,10 @@ The release candidate should not be called v1.0 until:
 - any approved exceptions are documented in an ADR,
 - security offline test passes,
 - 100-turn long-run test passes,
- export/import recovery passes,
+- export/import recovery passes, including an undone active-head round trip,
 - Undo/Redo/Retry/checkpoint behavior passes,
+- explicit narrative-state event/coherence tests pass at realistic context length,
+- no first-use runtime tokenizer/font/asset download occurs,
 - branch/memory lineage isolation passes,
 - fantasy and science-fiction fixtures both pass.

@@ -0,0 +1,19 @@
+# Planning Package Version
+
+**Package:** Adventure Storyteller Planning Package v2  
+**Revision date:** 2026-09-01  
+**Status:** Phase 0 complete; architecture selected; production milestone plan approved for milestone-by-milestone implementation.
+
+This v2 package supersedes the earlier planning package produced before the final Phase 0B review and the trusted-LAN Ollama deployment clarification.
+
+Key v2 changes include:
+
+- AI-DnD selected as the production base at the pinned Phase 0B commit.
+- Non-destructive head-cursor Undo/Redo design selected.
+- Explicit typed/absolute narrative-state events selected for production state handling.
+- Imported knowledge separated from AI-DnD Story Cards.
+- Trusted-LAN Ollama inference supported in v1 while the storyteller UI/API remains loopback-bound by default.
+- Offline first-use dependencies and runtime remote assets identified as M1 hardening work.
+- Production implementation divided into milestones M1-M11.
+
+Historical Phase 0 prompts/reports are retained as evidence and should not be treated as current implementation instructions unless a current milestone prompt explicitly refers to them.
@@ -1,5 +1,7 @@
 # CaoRuiming/ai-adventure — Static Architecture Analysis

+**Historical status:** Static Phase 0A analysis. Phase 0B promoted ai-adventure to the primary implementation reference for state/event/head/checkpoint semantics, but not the production base.
+
 **Project name in repository docs:** Local Adventure Engine  
 **Repository:** https://github.com/CaoRuiming/ai-adventure  
 **Date reviewed:** 2026-09-01  
@@ -1,5 +1,7 @@
 # AI-DnD — Static Architecture Analysis

+**Historical status:** Static Phase 0A analysis. Phase 0B corrected the shipped Undo assumption and confirmed AI-DnD as the production base after a successful head-cursor spike.
+
 **Repository:** https://github.com/parththakkar106/AI-DnD  
 **Date reviewed:** 2026-09-01  
 **Disposition:** Preliminary fork recommendation / Finalist #1.
@@ -1,5 +1,7 @@
 # Candidate Inventory and Triage

+**Historical status:** Phase 0A triage. The final production disposition was selected after Phase 0B; see ADR 009.
+
 **Phase:** 0A — Static research  
 **Date:** 2026-09-01

@@ -3,6 +3,14 @@
 **Date:** 2026-09-01  
 **Nature:** Engineering planning summary, not legal advice.

+## Production Selection Update
+
+Phase 0B selected **AI-DnD (MIT)** as the production fork/base. The production strategy therefore remains on a permissive-license path.
+
+The project may reimplement compatible ideas from other projects, but direct source copying must still be reviewed file-by-file and retain applicable notices. GPL/AGPL projects remain concept/reference sources unless a later explicit licensing decision changes that policy.
+
+Maintain third-party notices from the first production milestone.
+
 ## Permissive finalists

 ### AI-DnD
@@ -1,5 +1,7 @@
 # Open Dungeon — Static Architecture Analysis

+**Historical status:** Static Phase 0A analysis. Phase 0B confirmed Open Dungeon is a UX/media reference rather than the production base.
+
 **Repository:** https://github.com/newideas99/open-dungeon  
 **Date reviewed:** 2026-09-01  
 **Disposition:** Finalist #2; strongest product/UI/media fit, but branch persistence requires material redesign.
@@ -1,5 +1,7 @@
 # Phase 0A Status

+**Historical status:** Phase 0A complete. Phase 0B is also complete; see README, ADR 009, ADR 010, and `TECHNICAL-DESIGN.md` for current architecture.
+
 **Completed:** 2026-09-01

 ## Completed statically
@@ -1,5 +1,7 @@
 # Phase 0A Preliminary Recommendation

+**Historical status:** Superseded by Phase 0B runtime validation and ADR 009. Retained as Phase 0A evidence.
+
 **Date:** 2026-09-01  
 **Status:** Static recommendation; pending Phase 0B clone/build/runtime experiments.

@@ -1,5 +1,7 @@
 # Reuse Matrix

+**Historical status:** Phase 0A matrix. Some ratings were corrected by Phase 0B; use the v1 technical design and ADRs for current decisions.
+
 **Date:** 2026-09-01

 Legend:
@@ -1,7 +1,22 @@
-# Phase 0A Source Index
+# Phase 0 Source Index

-**Status:** Static research completed 2026-09-01  
-**Scope:** Public repository source/docs inspection only. No local clone/build/runtime validation has been performed yet.
+**Status:** Phase 0 source inventory; static links plus Phase 0B pinned finalist commits.  
+**Scope:** Repository/source references used during Phase 0. Runtime findings are recorded in `PHASE-0B-RECOMMENDATION.md` and supporting Phase 0B evidence.
+
+## Phase 0B Production Selection
+
+Selected production base:
+
+- AI-DnD
+- pinned Phase 0B commit: `d72f7c1bda0f34fccd84afb7a25c34eb01c901de`
+- license: MIT
+
+Phase 0B also evaluated:
+
+- Open Dungeon `b0a79f96bf852be7b4e53908dff6a7f7c179da23`
+- ai-adventure `873ea9180d5b611576cddb155921fc16a17ae88b`
+
+The source list below records the Phase 0 research set.

 ## Finalists