Update planning package after Phase 0B

planning/SPECIFICATION.md

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