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

## Current Status

Phase 0A static research is complete.

The project is now ready for **Phase 0B local validation** of the three finalists:

1. AI-DnD
2. Open Dungeon
3. ai-adventure

**Do not begin production implementation yet.**

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.

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

The detailed design documents describe target behavior; they do not force a particular repository schema when an equivalent implementation satisfies the behavior.

## Recommended Reading Order for Codex

### 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:

- browser-first UI,
- local-only v1 runtime,
- local Ollama inference,
- application-owned authoritative story state,
- complete retained transcript,
- 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,
- 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.

## Detailed Documents

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

## Phase 0A Research

Static repository research was completed on 2026-09-01.

Key reports:

- `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`

Current preliminary architecture hypothesis:

```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
```

This is a hypothesis to test, not a fork decision.

## Overall Workflow

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