Add initial planning files from ChatGPT research here

2026-09-01 12:09:38 -04:00
commit f011362494
37 changed files with 14601 additions and 0 deletions
@@ -0,0 +1,139 @@
+# CaoRuiming/ai-adventure — Static Architecture Analysis
+
+**Project name in repository docs:** Local Adventure Engine  
+**Repository:** https://github.com/CaoRuiming/ai-adventure  
+**Date reviewed:** 2026-09-01  
+**Disposition:** Finalist #3; strongest state/privacy reference, possible core candidate.
+
+## Architectural fit
+
+This project most closely matches the desired trust boundary:
+
+> The model proposes narration/events; the application validates and commits authoritative state.
+
+Its architecture separates:
+- authored content,
+- runtime state and pure reducers,
+- SQLite storage/migrations,
+- local lore indexing/retrieval,
+- deterministic bounded context construction,
+- model provider,
+- application turn logic,
+- CLI presentation.
+
+That separation makes it especially valuable even if it is not the final fork.
+
+## Turn/commit model
+
+The documented flow:
+
+1. load/replay state,
+2. synchronize lore,
+3. build deterministic bounded context,
+4. call local model,
+5. parse a structured turn proposal,
+6. validate proposed events,
+7. apply events in memory,
+8. atomically append turn/events and move the session head,
+9. display narration only after commit.
+
+This is the strongest candidate design for “the model is not the database.”
+
+## Persistence and recovery
+
+The project documents:
+- parent-linked turn history,
+- append-only state events,
+- cached reconstructed state,
+- undo by moving session head,
+- named checkpoints,
+- restore,
+- branching into another session that shares ancestors,
+- replayable state.
+
+This satisfies the conceptual checkpoint/branch requirement better than a destructive chat log.
+
+Potential mismatch:
+- branches are represented as sessions rather than necessarily one unified visual story tree.
+- export behavior and cross-branch navigation should be tested for the browser product.
+
+## Lore and long memory
+
+The project currently favors deterministic local retrieval:
+- Markdown lore,
+- SQLite FTS5/fallback,
+- bounded context,
+- summaries.
+
+It intentionally avoids an embedding/vector dependency in the initial architecture.
+
+This is attractive for privacy and auditability, but the target project likely also wants optional local semantic retrieval through Ollama for:
+- old story events,
+- large imported reference/inspiration libraries.
+
+The deterministic lexical layer should still be considered as part of a hybrid retriever.
+
+## Privacy/security fit
+
+This is the strongest static privacy design among the finalists.
+
+The project documentation explicitly addresses:
+- local data directory,
+- loopback model endpoint by default,
+- warning for non-loopback endpoints,
+- no telemetry/cloud account,
+- no MCP,
+- no executable plugins,
+- no shell tools,
+- parameterized SQL,
+- bounded imports,
+- path traversal/symlink restrictions,
+- local world files treated as data.
+
+The default provider is LM Studio rather than Ollama, but the provider boundary appears intentionally small.
+
+## Tests
+
+Project documentation reports an offline test suite that grew during implementation (later milestone notes report 74 tests). Phase 0B should run the actual current suite and treat it as authoritative.
+
+## Major gaps for target product
+
+- terminal UI,
+- LM Studio rather than Ollama as documented primary provider,
+- no browser API/UI,
+- no current media system,
+- no semantic embedding retrieval,
+- authored entity/event model may be more rigid than freeform narrative state,
+- likely more front-end work than either browser finalist.
+
+## Best reuse case
+
+Even if it is not the production base, reuse its architectural rules:
+
+- append-only authoritative events,
+- model proposals never direct state writes,
+- validate before commit,
+- commit narration and state atomically,
+- deterministic replay,
+- non-destructive head movement,
+- imported files are data only,
+- minimal network surface.
+
+If selected as base, Phase 0B must prove that adding Ollama + a browser service/UI is smaller than stripping AI-DnD.
+
+## Phase 0B questions for Codex
+
+1. Can its provider interface talk to Ollama via compatibility mode with a tiny adapter?
+2. Can a native Ollama adapter be added without touching turn/state logic?
+3. How much application code assumes CLI presentation?
+4. Is the app/service layer clean enough to expose through FastAPI without refactoring state internals?
+5. How are branches/checkpoints exported and navigated?
+6. Can generic freeform narrative facts/entities be represented without expanding typed events excessively?
+7. With Internet blocked, is the only runtime network connection the configured local model endpoint?
+
+## Primary source links
+
+- Repository: https://github.com/CaoRuiming/ai-adventure
+- Architecture: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/architecture.md
+- Privacy/security: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/privacy-and-security.md
+- Apache-2.0 license: repository `LICENSE`
@@ -0,0 +1,168 @@
+# AI-DnD — Static Architecture Analysis
+
+**Repository:** https://github.com/parththakkar106/AI-DnD  
+**Date reviewed:** 2026-09-01  
+**Disposition:** Preliminary fork recommendation / Finalist #1.
+
+## Why it moved to first place
+
+The static review indicates that AI-DnD already implements most of the difficult correctness infrastructure that would otherwise need to be invented:
+
+- browser UI (React/Vite),
+- FastAPI backend,
+- local SQLite,
+- Ollama via local OpenAI-compatible endpoint,
+- story as a tree rather than a list,
+- alternate takes,
+- branch lineage that borrows ancestors,
+- state restored when switching branches,
+- non-destructive retry,
+- state snapshots,
+- exact prompt/context snapshots,
+- automatic summaries,
+- embedding-based long-term memory,
+- story cards/world information,
+- export/import of the complete story tree,
+- substantial automated backend testing.
+
+The current README reports 549 backend tests. The design guide contains an older measured-results count of 440, so the clone should treat the live test suite—not prose counts—as authoritative.
+
+## Story tree
+
+This is the strongest reason to prefer AI-DnD.
+
+The project explicitly models:
+
+- branches,
+- actions/nodes,
+- parent/fork lineage,
+- multiple takes at a turn,
+- branch-aware context,
+- state after a node,
+- retry that preserves the replaced attempt.
+
+That matches the user's desired “Git for stories” behavior much more closely than Open Dungeon.
+
+Its documentation also describes measured optimization work so branches do not duplicate the ancestor transcript.
+
+## Turn pipeline
+
+The documented flow is close to the target Story Director:
+
+```text
+player input
+  -> optional input hook
+  -> retrieve memories
+  -> assemble bounded context
+  -> snapshot exact context
+  -> stream provider output
+  -> extract proposed state delta
+  -> Python referee validates state
+  -> save action + resulting state
+  -> background summarize/embed
+```
+
+The target project would simplify this rather than reinvent it.
+
+## Memory/context
+
+AI-DnD already includes three useful layers:
+
+- direct recent history,
+- AI-generated memories,
+- running story summary.
+
+Embedding retrieval pulls old relevant memories back into context and exposes similarity/context details through an Insights UI.
+
+Story cards provide a mature starting point for lore/world-info injection.
+
+The main extension needed is a first-class imported document library with explicit authority classes:
+- Canon,
+- Reference,
+- Inspiration.
+
+## Prompt transparency
+
+The current project stores the exact prompt sent for a turn and provides an Insights view with context components and token costs. This directly satisfies a stated debugging requirement.
+
+## What must be removed or generalized
+
+AI-DnD is not a clean fit out of the box.
+
+### RPG-specific world state
+Current world state is designed around stats, bands, flags, milestones, cooldowns, NPC presence, and state deltas.
+
+Target:
+- retain the proposal/referee/snapshot pattern,
+- replace or supplement RPG stats with generic narrative entities/facts/relationships/story threads/scenes.
+
+### QuickJS scripting
+The project includes AI-Dungeon-compatible user scripting.
+
+For this project, executable campaign content conflicts with the desired narrow trust surface. Unless a compelling future use appears, remove or disable scripting in v1.
+
+### Hosted/multi-user behavior
+Current code supports:
+- optional accounts,
+- guest users,
+- rate limits,
+- demo keys,
+- hosted deployments,
+- Postgres/Neon,
+- Render,
+- remote model providers.
+
+The target is a single-user local application. These paths should be removed or compiled/configured out rather than merely hidden in the UI.
+
+### Analytics
+The project includes its own owner-only aggregate visit analytics for hosted mode. It is not described as a third-party tracker, but it is unnecessary for the local fork and should be removed.
+
+### Cloud providers
+OpenRouter/OpenAI/Groq/vLLM support is broader than desired. v1 should retain only the local Ollama path.
+
+## Security positive
+
+The local/hosted modes are already explicitly separated, and the code contains network-guard thinking around hosted deployments. This is a better starting point than a project with cloud assumptions scattered everywhere, but static review cannot prove that removal is trivial.
+
+## Main risk
+
+The central Phase 0B question is:
+
+> Are the RPG/cloud/scripting systems modular enough that removing them is less work and less risk than adding correct branching/state/memory to Open Dungeon?
+
+Static evidence suggests yes, but this must be tested with a local strip-down experiment.
+
+## Best reuse case
+
+If selected:
+- keep story tree,
+- keep action/state snapshots,
+- keep context/history windowing,
+- keep Memory Bank structure,
+- keep story cards,
+- keep Insights/prompt snapshots,
+- keep SQLite and local FastAPI/React split,
+- keep Ollama adapter path,
+- remove hosted/auth/analytics/cloud,
+- remove QuickJS,
+- generalize world state,
+- add document ingestion,
+- add scene/media schema and provider interface,
+- use Open Dungeon/Gamentic as media UX references.
+
+## Phase 0B questions for Codex
+
+1. Can the app run fully local with only Ollama and no Internet?
+2. Can QuickJS, hosted auth, analytics, Render/Neon, and remote provider paths be removed without destabilizing core tests?
+3. How tightly does branching depend on RPG world-state fields?
+4. Can an adventure run with minimal/no stats while branch rollback still passes?
+5. Can the state snapshot payload be generalized to narrative JSON without rewriting the tree?
+6. How many tests cover branch/undo/retry/context/memory independently of RPG logic?
+7. Does current Memory Bank work with a local Ollama embedding model in practice?
+8. What exact outbound traffic occurs in default local mode?
+
+## Primary source links
+
+- Repository / README: https://github.com/parththakkar106/AI-DnD
+- Design guide: https://github.com/parththakkar106/AI-DnD/blob/main/docs/GUIDE.md
+- MIT license: repository `LICENSE`
@@ -0,0 +1,46 @@
+# aiMultiFool — Static Architecture Analysis
+
+**Repository:** https://github.com/omgboohoo/aimultifool  
+**Date reviewed:** 2026-09-01  
+**Disposition:** Reference only.
+
+## Useful ideas
+
+aiMultiFool is a local roleplay/chat sandbox with:
+- Ollama support,
+- local inference paths,
+- Vector Chat / semantic-memory concepts,
+- save/load,
+- rewind/regenerate,
+- context inspection,
+- optional encrypted local data.
+
+Those are useful implementation references for local memory tooling and diagnostics.
+
+## Why it is not a fork finalist
+
+### Product mismatch
+The interface is terminal/Textual-oriented and character-chat/roleplay focused rather than a browser-first persistent fiction editor.
+
+### History/context mismatch
+Its documented smart-pruning strategy removes older middle messages from active chat state as context pressure grows. That is a reasonable chat optimization but not the target architecture. The target must preserve an immutable authoritative transcript and prune only the prompt representation.
+
+### State model
+The project does not provide the same authoritative event/state/branch model found in AI-DnD or ai-adventure.
+
+### License
+The repository is GPL-3.0. Directly copying substantial GPL code into an MIT/Apache-derived application would change licensing obligations. Unless the final project intentionally adopts GPL-compatible distribution terms, use this project for concepts rather than source copying.
+
+## Recommended reuse
+
+Study:
+- local embedding workflow,
+- vector inspection/debugging,
+- encrypted local payload design,
+- user-facing memory controls.
+
+Do not make it a Phase 0B build finalist.
+
+## Source
+
+- Repository: https://github.com/omgboohoo/aimultifool
@@ -0,0 +1,66 @@
+# Candidate Inventory and Triage
+
+**Phase:** 0A — Static research  
+**Date:** 2026-09-01
+
+## Executive result
+
+Three projects should advance to local validation:
+
+1. **AI-DnD** — strongest implementation of the hardest required backend capabilities.
+2. **Open Dungeon** — strongest direct product/UX fit and strongest near-term media path.
+3. **CaoRuiming/ai-adventure (Local Adventure Engine)** — strongest authoritative-state, replay, checkpoint, and privacy architecture.
+
+Everything else should remain available as a design/source reference but should not consume local build-validation effort unless one of the three finalists fails.
+
+## Triage table
+
+| Project | Browser-first | Ollama | Durable branch/rollback | Long memory | Local knowledge | Future media | Static disposition |
+|---|---|---|---|---|---|---|---|
+| AI-DnD | Yes | Yes | **Strong** | **Strong** | Story cards + memory | Not core | **Finalist #1** |
+| Open Dungeon | **Yes** | **Yes** | Weak / destructive linear tail today | Summary-based | Limited | **Strong; local image generation already present** | **Finalist #2** |
+| ai-adventure | No; CLI | LM Studio today | **Strong** | Summary + lore FTS | **Strong deterministic local lore** | No | **Finalist #3** |
+| Chronicler | Yes | Yes | Not the focus | **Excellent memory model** | Memory-centric | No | Reference |
+| Gamentic | **Yes** | llama.cpp/OpenAI-compatible | Game-state oriented | Strong | World bible | **Excellent image/voice provider design** | Reference |
+| Interactive Fiction Framework | **Yes** | **Yes** | Not established as required story-tree model | Canon/scene/character memory | Story Bible | Not core | Reference |
+| Sonder Engine | **Yes** | **Yes** | Persistent variants/checkpoints, but much more agentic | **Very sophisticated** | Character-scoped retrieval | Not primary | Reference |
+| Corvus Story Core | **Yes** | OpenAI-compatible | No equivalent branch tree established | Summaries + state | World/state | ComfyUI + TTS | Reference |
+| aiMultiFool | No; terminal | **Yes** | Rewind, not target architecture | Vector chat | RAG-oriented | No | Reference only |
+| SillyTavern | **Yes** | Local backends | Chat-oriented | Extensions/lorebooks | **Excellent lorebook UX** | Broad extensions | Reference only |
+| RisuAI | **Yes** | Local/remote ecosystem | Chat-oriented | Hypa/SupaMemory | Lorebooks | Broad media | Reference only |
+| KoboldAI | **Yes** | Local ecosystem | Traditional save/load | Memory/World Info | World Info | Limited | Reference only |
+
+## Why the shortlist is only three
+
+### AI-DnD advances because
+It already implements the expensive correctness work: a parent/lineage story tree, alternate takes, non-destructive retry, state snapshots and rollback, branch-aware context, summaries, embedding retrieval, story cards, exact prompt inspection, export/import of the complete tree, and a substantial automated test suite.
+
+### Open Dungeon advances because
+It is almost exactly the desired product shape: browser-first, simple interactive fiction, Ollama, local SQLite, streaming narration, visual character continuity, and local image-generation hooks. Its key weakness is architectural rather than cosmetic: its current message schema is linear and its retry/erase operation deletes the selected message and the rest of the tail.
+
+### ai-adventure advances because
+Its core philosophy most closely matches the required trust model. SQLite and typed events are authoritative; the model proposes changes; validation occurs before atomic commit; undo/checkpoint/restore/branch work by replaying parent-linked history; lore is local; and the privacy documentation explicitly minimizes network and executable-extension surfaces.
+
+## Projects eliminated from fork contention
+
+### Chronicler
+Excellent source for memory semantics, but the application is centered on long-running roleplay and YantrikDB cognitive memory rather than the simpler interactive-story product. Its memory-tier design should be borrowed conceptually.
+
+### Gamentic
+Technically impressive and very useful for future media design, but it is intentionally a multi-agent RPG with image and voice infrastructure, tuned around a heavier local stack. Forking it would mean removing more game/agent behavior than necessary.
+
+### Interactive Fiction Framework
+Its Story Bible, validation, and application-owned-state design are highly relevant. However, it is oriented toward contributor-authored, schema-driven stories and planner-approved choices rather than the unrestricted natural-language story continuation and branch history required here.
+
+### Sonder Engine
+Strong engineering, but its core differentiator is separate fictional minds with strict perception/knowledge boundaries and a multi-stage agent pipeline. That is substantially more complexity than v1 requires.
+
+### Corvus Story Core
+Useful image/TTS and state-extraction reference, but its persistence is JSON/JSONL-oriented and the static review did not establish the required non-destructive branch/checkpoint model.
+
+### aiMultiFool
+Useful local vector-memory ideas, but it is a terminal character-roleplay application, its context-pruning approach is not the desired immutable-history architecture, and GPL-3.0 complicates direct code reuse into a permissively licensed fork.
+
+## Sources
+
+See `SOURCE-INDEX.md` for repository/source links.
@@ -0,0 +1,67 @@
+# Licensing and Reuse Review
+
+**Date:** 2026-09-01  
+**Nature:** Engineering planning summary, not legal advice.
+
+## Permissive finalists
+
+### AI-DnD
+- License: MIT
+- Direct modification/forking is generally compatible with a permissive local application, subject to preserving required notices.
+
+### Open Dungeon
+- License: MIT
+- Same practical advantage for direct reuse.
+
+### ai-adventure
+- License: Apache-2.0
+- Permissive, but Apache notice/license obligations must be preserved.
+
+These three can plausibly participate in a permissively licensed implementation strategy, subject to checking individual vendored/third-party files.
+
+## Permissive reference projects
+
+Static repository licensing indicates:
+- Chronicler: MIT
+- Interactive Fiction Framework: MIT
+- Gamentic: MIT
+- Sonder Engine: MIT
+- Corvus Story Core: MIT
+
+If source is copied, retain the applicable notices and verify whether particular directories/files carry separate licenses.
+
+## Copyleft references
+
+### aiMultiFool
+- GPL-3.0
+- Treat as a concept/reference source unless the final project intentionally accepts GPL obligations.
+
+### LettuceAI
+- AGPL-3.0
+- Reference only for this project unless there is a deliberate licensing decision.
+
+Mature roleplay ecosystems such as SillyTavern/RisuAI/KoboldAI should have their exact current license verified before any code copying. No direct reuse is currently recommended.
+
+## Media dependencies
+
+Important distinction:
+- application code license,
+- media runtime license,
+- model-weight license
+are separate.
+
+For example Gamentic documents:
+- its own code under MIT,
+- ComfyUI runtime under GPL-3.0,
+- model weights under their own terms.
+
+Using a separately running local service through an API is architecturally different from copying its code into the storyteller, but distribution/bundling choices should be reviewed before release.
+
+## Recommendation
+
+Keep the production application's own code on a permissive-license path if possible:
+- primary fork from MIT or Apache-2.0,
+- copy code only from compatible permissive sources,
+- treat GPL/AGPL projects as design references unless a conscious license change is made,
+- keep optional media providers as external adapters/services where practical,
+- maintain a third-party notices file from the first production milestone.
@@ -0,0 +1,138 @@
+# Open Dungeon — Static Architecture Analysis
+
+**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.
+
+## What maps well to the specification
+
+Open Dungeon already provides a product very close to the desired interaction model:
+
+- browser-first UI,
+- local Ollama text generation,
+- streaming narration,
+- Do / Say / Story-style interaction,
+- Continue / Retry / Erase / Edit controls,
+- SQLite persistence,
+- rolling story summary for long conversations,
+- persistent character records,
+- local inline image generation,
+- character portraits/visual continuity feeding image generation,
+- optional ComfyUI path.
+
+The future-media requirement is therefore not hypothetical in this codebase. It already has a concept of the narrator requesting an image after prose and a local image backend producing it.
+
+## Current stack
+
+From the current package/config:
+
+- Next.js 16
+- React 19
+- TypeScript
+- `better-sqlite3`
+- Node.js 22+
+- Ollama default endpoint at `127.0.0.1:11434`
+- local image worker defaults to loopback
+- optional remote OpenAI-compatible/OpenRouter configuration
+
+## Persistence finding: the major issue
+
+The current database is fundamentally a linear chat model.
+
+The reviewed schema contains:
+
+- chats,
+- messages,
+- characters,
+- app settings,
+- rolling story summary fields.
+
+Messages do not expose a parent-turn/branch-lineage model equivalent to AI-DnD or ai-adventure.
+
+More importantly, the data layer includes an operation named `deleteMessageAndAfter()`. Its own comment says it is used by retry/erase to discard the tail of the story. Prior text can also be updated in place.
+
+That is directly contrary to the target requirement:
+
+> Going backward should preserve the abandoned future as an alternate branch.
+
+This means adding robust branching is not simply a UI feature. It requires changing the persistence semantics and all features that assume a single mutable message sequence, including retry/erase/edit and summary lineage.
+
+## Memory/context model
+
+The prompt builder contains a history-packing mechanism with block eviction. Old story material is compressed into a rolling story summary, while recent history stays direct.
+
+This is a reasonable lightweight storyteller strategy but is below the target design:
+
+- no established semantic retrieval of old story events,
+- no explicit Canon / Reference / Inspiration document library,
+- no branch-aware memory lineage,
+- no rich authoritative generic story-state graph.
+
+Those systems would need to be added.
+
+## Media design
+
+Open Dungeon is the strongest finalist for immediate media UX.
+
+The current narrator prompt exposes a `generate_image` tool after a passage and passes selected character IDs so the image path can preserve visual identity. The app can use local FLUX tooling and supports ComfyUI in recent releases.
+
+Useful ideas to retain even if Open Dungeon is not the base:
+
+1. media is optional; text play does not depend on it,
+2. image generation is scene/turn-associated,
+3. character visual identity is stored rather than reinvented each image,
+4. local backend is behind a service boundary,
+5. generated media appears inline in the story.
+
+For our architecture, image generation should eventually move behind a generic media-provider interface rather than remain hard-coded to one model/workflow.
+
+## Privacy/static network assessment
+
+Positive:
+- local Ollama is the default,
+- local SQLite is the default,
+- local image generation is supported,
+- no telemetry requirement was apparent in the inspected package/config.
+
+Hardening needed:
+- remove or disable OpenRouter and arbitrary remote OpenAI-compatible provider options in v1,
+- review Tailscale/LAN exposure separately from loopback-only default,
+- verify built frontend has no remote runtime assets,
+- verify image setup does not make unexpected runtime downloads after installation,
+- runtime network capture still required.
+
+## Testing concern
+
+The inspected `package.json` exposes build/lint/image checks but no obvious comprehensive automated test command comparable to AI-DnD or Gamentic. This must be verified after clone; if accurate, a branch/persistence rewrite would need a new test foundation before implementation.
+
+## Best reuse case
+
+If Open Dungeon becomes the base:
+- preserve the browser experience,
+- preserve Ollama integration,
+- preserve image/visual-continuity concepts,
+- replace/extend linear message persistence with a parent-linked turn graph,
+- make summary/memory branch-aware,
+- add authoritative generic narrative state,
+- add local document ingestion and retrieval,
+- add prompt/provenance inspection.
+
+If AI-DnD becomes the base:
+- use Open Dungeon primarily as a UX and media-generation reference.
+
+## Phase 0B questions for Codex
+
+1. How many routes/components assume messages are a single ordered list?
+2. Can a parent-linked turn/branch layer be introduced without replacing most chat APIs?
+3. What happens to `story_summary` when retry/erase edits earlier history?
+4. Can current image records attach cleanly to immutable turn IDs/scene IDs?
+5. Is there an automated test suite not visible from the package manifest?
+6. With Internet blocked, does ordinary text + local image play produce only loopback traffic?
+
+## Primary source links
+
+- Repository: https://github.com/newideas99/open-dungeon
+- DB: https://github.com/newideas99/open-dungeon/blob/main/src/lib/db.ts
+- Prompt builder: https://github.com/newideas99/open-dungeon/blob/main/src/lib/story-prompt.ts
+- Environment: https://github.com/newideas99/open-dungeon/blob/main/.env.example
+- Package: https://github.com/newideas99/open-dungeon/blob/main/package.json
@@ -0,0 +1,39 @@
+# Phase 0A Status
+
+**Completed:** 2026-09-01
+
+## Completed statically
+
+- candidate discovery and triage,
+- deep source/document architecture review of the three finalists,
+- static privacy/network-surface review,
+- preliminary licensing/reuse review,
+- subsystem reuse matrix,
+- preliminary fork recommendation,
+- narrowed Codex validation plan.
+
+## Preliminary decision
+
+Validate **AI-DnD first as the production fork candidate**.
+
+Keep:
+- **Open Dungeon** as the fallback fork and primary UI/media reference.
+- **ai-adventure** as the state/replay/privacy architecture reference and third validation candidate.
+
+## Still requires local/Codex work
+
+- pin exact SHAs,
+- clone/install/build,
+- run actual tests,
+- verify Ollama against the user's machine,
+- runtime network capture,
+- offline operation,
+- AI-DnD strip-down experiment,
+- Open Dungeon branch-retrofit impact experiment,
+- ai-adventure Ollama/service-boundary experiment.
+
+See `PHASE-0B-CODEX-HANDOFF.md`.
+
+## Phase gate
+
+Do not finalize `TECHNICAL-DESIGN.md` v1.0 or production `BUILD-MILESTONES.md` until Phase 0B results are reviewed.
@@ -0,0 +1,153 @@
+# Phase 0A Preliminary Recommendation
+
+**Date:** 2026-09-01  
+**Status:** Static recommendation; pending Phase 0B clone/build/runtime experiments.
+
+## Recommendation
+
+### First choice to validate: AI-DnD
+
+Use **AI-DnD as the preliminary production fork candidate**.
+
+This is a change from the earlier slight preference for Open Dungeon.
+
+The deciding evidence is not feature count; it is **where the hard architectural work already lives**.
+
+AI-DnD already implements:
+- parent/lineage story tree,
+- alternate takes,
+- non-destructive retry,
+- branch-aware state rollback,
+- prompt snapshots,
+- context windowing,
+- memory bank + embeddings,
+- story cards,
+- complete tree export/import,
+- local Ollama,
+- a substantial automated test suite.
+
+Those are precisely the systems most dangerous to retrofit after a linear chat application has accumulated behavior.
+
+## Why Open Dungeon is second
+
+Open Dungeon remains the best direct match to the desired *product*:
+- simple browser fiction interface,
+- Ollama,
+- local SQLite,
+- strong local image path,
+- visual continuity.
+
+However, its present persistence semantics are linear and destructive:
+- prior messages can be updated,
+- retry/erase deletes the selected message and the story tail.
+
+To satisfy the specification, we would need to introduce turn parentage/branches, branch-specific summaries/state, and non-destructive editing underneath features already written around a list. That is foundational work.
+
+Open Dungeon should remain the fallback base if Codex proves AI-DnD's RPG/cloud systems are too entangled to remove.
+
+## Why ai-adventure is third
+
+ai-adventure has the cleanest *architecture* for state authority and local-only trust:
+- typed model proposals,
+- validation,
+- atomic commit,
+- append-only events,
+- replay,
+- checkpoints,
+- branches,
+- deterministic local lore,
+- explicit minimal network posture.
+
+Its problem is product distance:
+- CLI presentation,
+- LM Studio primary provider,
+- no browser application,
+- no media,
+- less semantic long-memory machinery.
+
+It should be the architectural control against which the selected browser fork is judged.
+
+## Do not merge repositories
+
+The recommendation is not to combine several projects mechanically.
+
+Fork one project and re-implement selected ideas using compatible patterns/code only where justified.
+
+A merged codebase would import:
+- incompatible assumptions,
+- duplicate persistence models,
+- different provider abstractions,
+- unnecessary dependencies,
+- licensing complexity.
+
+## Proposed target architecture after Phase 0B
+
+If AI-DnD passes validation:
+
+### Retain
+- React/Vite browser shell,
+- FastAPI service boundary,
+- SQLite,
+- story tree/lineage,
+- state snapshots,
+- context budgeting,
+- Memory Bank,
+- story cards,
+- Insights,
+- Ollama path,
+- export/import,
+- relevant tests.
+
+### Remove
+- multi-user/hosted auth,
+- demo keys/rate-limit hosting features,
+- Render/Neon path,
+- analytics,
+- cloud model providers,
+- QuickJS scripting,
+- AI-Dungeon compatibility not needed for core stories,
+- RPG-only presentation/mechanics.
+
+### Generalize
+- world-state engine -> narrative state/facts/entities/threads,
+- Story Cards -> local knowledge sources with authority/provenance,
+- Memory Bank -> branch-safe story memory with Canon/Scene/Heuristic trust classes,
+- scenario -> genre-neutral campaign/story profile.
+
+### Add
+- local document ingestion,
+- Canon / Reference / Inspiration source classification,
+- local lexical + optional Ollama semantic retrieval,
+- scene snapshots,
+- visual character/location fields,
+- media asset/job records,
+- media-provider interface,
+- later local image/video adapters.
+
+## Phase 0B should be narrow
+
+Codex should not repeat the broad research.
+
+It should validate three concrete engineering hypotheses:
+
+### Hypothesis 1 — AI-DnD can be stripped safely
+Prove local Ollama story/branch/memory operation still works after disabling/removing hosted/cloud/analytics/scripting paths and running with minimal RPG state.
+
+### Hypothesis 2 — Open Dungeon branch retrofit is materially larger
+Map exactly how many DB functions/API routes/UI components/summary behaviors must change to make retry/edit non-destructive and branch-aware.
+
+### Hypothesis 3 — ai-adventure is viable but farther from product
+Prove Ollama adapter effort is small and estimate the service/browser wrapper effort without starting production UI development.
+
+Then choose the fork based on measured modification cost.
+
+## Decision gate
+
+Select AI-DnD unless Phase 0B finds one of these blockers:
+
+- branching/state logic is inseparable from RPG mechanics,
+- removing hosted/scripting paths destabilizes a large percentage of tests,
+- local-only configuration still requires hard-to-remove external services,
+- dependency/security burden is materially worse than static review suggests.
+
+If any blocker is confirmed, select Open Dungeon and explicitly budget a story-tree/persistence rewrite as the first production architecture milestone.
@@ -0,0 +1,122 @@
+# Static Privacy and Network Review
+
+**Date:** 2026-09-01  
+**Scope:** Source/config/documentation review only. Runtime capture is still required in Phase 0B.
+
+## Target rule
+
+The final v1 should be able to operate with Internet access physically blocked, with ordinary story data traveling only:
+
+```text
+Browser -> local application -> local Ollama
+```
+
+Future media should similarly use explicitly configured local providers.
+
+## AI-DnD
+
+### Static positives
+- documented local single-user mode,
+- local SQLite,
+- local Ollama support,
+- no auth required in local mode,
+- hosted analytics are first-party application functionality rather than a required third-party browser tracker.
+
+### Unwanted surfaces to remove
+- OpenRouter/OpenAI/Groq/vLLM provider support,
+- hosted account/guest flows,
+- demo API keys,
+- Render deployment,
+- Neon/Postgres cloud deployment path,
+- visit analytics,
+- QuickJS user scripting,
+- Claude CLI shim if not wanted,
+- any hosted-mode rate-limit/account code that adds no local value.
+
+### Risk
+The cloud/hosted code is explicit and documented, which is good, but Phase 0B must prove it can be removed cleanly.
+
+## Open Dungeon
+
+### Static positives
+- Ollama loopback default,
+- local SQLite,
+- local image backend,
+- no telemetry requirement apparent in inspected package/config.
+
+### Unwanted or optional surfaces
+- OpenRouter configuration,
+- arbitrary remote OpenAI-compatible endpoint support,
+- Tailscale/LAN exposure options,
+- any runtime remote assets,
+- any model/image automatic download behavior after setup.
+
+### Risk
+The app is smaller, so hardening may be easier, but no runtime capture has been performed.
+
+## ai-adventure
+
+### Static positives
+This project most closely matches the target from the outset:
+- no telemetry,
+- no cloud account,
+- no MCP,
+- no executable plugins,
+- no shell tools,
+- loopback model endpoint default,
+- non-loopback warning,
+- imported content treated as bounded data,
+- path traversal/symlink defenses documented.
+
+### Unwanted surface
+- configurable non-loopback model endpoint should be prohibited or strongly gated in the target v1.
+- LM Studio provider should be replaced/extended with Ollama.
+
+## Reference projects
+
+### Gamentic
+Local defaults are strong, but the project intentionally supports cloud text/image/audio dialects as alternatives. A target fork would need those disabled. Its Docker/media stack also has setup-time model acquisition concerns separate from story-time privacy.
+
+### Chronicler
+Supports local Ollama but also broader providers and a separate local YantrikDB/MCP memory service. More moving parts than needed.
+
+### Sonder / Corvus
+Both support local backends but also remote provider configurations; Sonder additionally has extension/optional external-service surfaces.
+
+### aiMultiFool
+Primarily local, but direct code reuse is constrained by GPL considerations and it is not a fork finalist.
+
+## Required Phase 0B runtime tests
+
+For each finalist:
+
+1. block outbound Internet access,
+2. start the app,
+3. create/load a story,
+4. generate multiple turns,
+5. trigger summarization/memory,
+6. trigger embeddings where applicable,
+7. save/restore/branch,
+8. for Open Dungeon, generate a local image,
+9. capture socket/DNS/HTTP activity,
+10. fail the test if story content leaves loopback or explicitly approved LAN endpoints.
+
+Record:
+- process,
+- destination IP/hostname,
+- port,
+- trigger,
+- payload classification,
+- whether required or optional.
+
+## Recommended production hardening
+
+- bind app and Ollama to loopback by default,
+- allowlist provider URLs rather than accept arbitrary URLs,
+- no API-key UI in v1,
+- no remote URL ingestion,
+- no executable campaign scripts,
+- no third-party analytics,
+- bundle frontend assets locally,
+- content-security policy that rejects remote scripts/styles/images by default,
+- CI test or integration harness that runs with outbound networking disabled.
@@ -0,0 +1,111 @@
+# Reference Project Findings
+
+**Date:** 2026-09-01
+
+These projects are not recommended as primary forks after static review, but each contributes a useful architectural pattern.
+
+## Chronicler
+
+Repository: https://github.com/yantrikos/chronicler
+
+### Borrow
+Its memory model distinguishes different trust levels rather than treating all remembered text equally.
+
+Useful conceptual tiers:
+- durable canon,
+- scene/recent memory,
+- heuristic/inferred memory.
+
+Its anti-confabulation approach is especially relevant: retrieved hints should not automatically become established historical fact.
+
+### Do not necessarily adopt
+The full YantrikDB/MCP cognitive-memory stack is heavier than v1 needs. Start with a simpler local store and preserve the trust-tier semantics.
+
+## Interactive Fiction Framework
+
+Repository: https://github.com/georgebutler/interactive-fiction-framework
+
+### Borrow
+- Story Bible as highest-authority narrative context,
+- application owns durable state,
+- model enriches prose rather than overriding state,
+- structured output validation,
+- deterministic fallback,
+- separation of director/planner/memory/validator.
+
+### Why not fork
+It is designed around contributor-authored story bundles and planner-approved choices, whereas the target is more freeform collaborative fiction with branch-preserving history.
+
+## Gamentic
+
+Repository: https://github.com/hec-ovi/gamentic
+
+### Borrow
+This is the strongest reference found for future multimodal architecture.
+
+It separates each modality behind a provider layer:
+
+```text
+engine
+  -> text provider
+  -> image provider
+  -> audio provider
+```
+
+The game can continue text-first while images render asynchronously. Character image/voice identity lives in game state rather than in provider-specific code.
+
+It also demonstrates an unusually strong local-project test strategy with over a thousand automated tests documented across backend/frontend/services.
+
+### Why not fork
+The core product is a multi-agent RPG with significant game mechanics and a heavy local image/voice stack. That is broader than the desired v1 storyteller.
+
+## Sonder Engine
+
+Repository: https://github.com/N0819/Sonder_Engine
+
+### Borrow later
+- one persistent commit boundary,
+- objective state distinct from character perception/belief/memory,
+- retrieval scoped by what a character may legitimately know,
+- model stages with different contexts.
+
+### Why not fork
+Its defining feature is separate character minds and a multi-stage agent pipeline. That is valuable for a future sophisticated simulation but unnecessary complexity for v1.
+
+## Corvus Story Core
+
+Repository: https://github.com/JustLateNightAI/Corvus-Story-Core
+
+### Borrow
+- hidden GM/state extraction pass,
+- scene/NPC visual descriptions,
+- ComfyUI scene art,
+- optional TTS,
+- local-first media integration.
+
+### Why not fork
+Static review did not show the same robust branch/checkpoint/replay model; persistence is oriented around local JSON/JSONL rather than the desired transactional story graph.
+
+## SillyTavern / RisuAI / KoboldAI
+
+### Borrow
+- lorebook/world-info UX,
+- author's-note concepts,
+- context placement and triggering,
+- character/world metadata workflows.
+
+### Why not fork
+They are mature but broad roleplay/chat ecosystems. Adapting them would mean carrying a large amount of unrelated general-purpose functionality.
+
+## Design consequence
+
+The production fork should not try to merge these projects.
+
+Use a primary codebase, then deliberately implement selected patterns:
+
+- AI-DnD: story tree, rollback, memory, prompt inspection.
+- ai-adventure: authoritative event/replay/privacy discipline.
+- Open Dungeon: story-focused UX and visual continuity.
+- Chronicler: memory trust tiers.
+- Gamentic: provider-neutral/asynchronous media.
+- IFF: Story Bible authority and validation.
@@ -0,0 +1,62 @@
+# Reuse Matrix
+
+**Date:** 2026-09-01
+
+Legend:
+- **KEEP** — candidate implementation is close to target.
+- **MODIFY** — strong implementation but needs adaptation.
+- **REFERENCE** — borrow pattern/idea; do not make it the ownership center.
+- **BUILD** — target capability is substantially absent.
+
+| Capability | AI-DnD | Open Dungeon | ai-adventure | Best current source |
+|---|---|---|---|---|
+| Browser storyteller UI | **MODIFY/KEEP** | **KEEP** | BUILD | Open Dungeon |
+| Ollama text adapter | **KEEP** | **KEEP** | MODIFY | AI-DnD/Open Dungeon |
+| SQLite local persistence | **KEEP** | MODIFY | **KEEP** | AI-DnD / ai-adventure |
+| Immutable turn parentage | **KEEP** | BUILD | **KEEP** | AI-DnD |
+| Alternate takes | **KEEP** | BUILD | MODIFY | AI-DnD |
+| Named checkpoints | MODIFY | BUILD | **KEEP** | ai-adventure |
+| Branch restore | **KEEP** | BUILD | **KEEP** | AI-DnD / ai-adventure |
+| Complete tree export | **KEEP** | BUILD | MODIFY | AI-DnD |
+| Exact prompt inspection | **KEEP** | BUILD/MODIFY | audit-oriented | AI-DnD |
+| Recent-history budgeting | **KEEP** | **KEEP** | **KEEP** | AI-DnD |
+| Rolling summaries | **KEEP** | **KEEP** | **KEEP** | all |
+| Semantic old-story retrieval | **KEEP/MODIFY** | BUILD | BUILD/MODIFY | AI-DnD |
+| Lexical local lore | MODIFY | BUILD | **KEEP** | ai-adventure |
+| Lore/story cards | **KEEP/MODIFY** | BUILD | MODIFY | AI-DnD |
+| Canon/Reference/Inspiration authority tiers | BUILD | BUILD | MODIFY | Chronicler/IFF concepts |
+| Generic narrative state | MODIFY | BUILD | MODIFY | ai-adventure pattern |
+| Model-proposes/app-validates | **KEEP but RPG-shaped** | BUILD | **KEEP** | ai-adventure |
+| Atomic state + turn commit | VERIFY | VERIFY | **KEEP** | ai-adventure |
+| Local-only privacy posture | MODIFY | MODIFY | **KEEP** | ai-adventure |
+| Local image generation | BUILD | **KEEP** | BUILD | Open Dungeon |
+| Provider-neutral media | BUILD | MODIFY | BUILD | Gamentic reference |
+| Scene/visual continuity | BUILD | **KEEP/MODIFY** | BUILD | Open Dungeon |
+| Large automated test base | **KEEP** | BUILD/VERIFY | **KEEP/VERIFY** | AI-DnD |
+| Genre-neutral core | MODIFY | **MODIFY/KEEP** | MODIFY | IFF/story-state concepts |
+
+## Cross-project architecture we should aim for
+
+Use one primary fork, not a stitched codebase.
+
+Preferred composition of ideas:
+
+```text
+AI-DnD production base
+  + ai-adventure trust/commit/privacy rules
+  + Open Dungeon scene/media UX
+  + Chronicler memory-authority tiers
+  + IFF Story Bible authority/validation
+  + Gamentic media-provider abstraction
+```
+
+If AI-DnD strip-down proves too invasive, invert the first line:
+
+```text
+Open Dungeon production base
+  + new AI-DnD-style immutable story tree
+  + ai-adventure event/commit discipline
+  + local memory/document retrieval
+```
+
+That fallback is viable, but static analysis suggests it recreates more hard correctness work.
@@ -0,0 +1,68 @@
+# Phase 0A 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.
+
+## Finalists
+
+### AI-DnD
+- Repository: https://github.com/parththakkar106/AI-DnD
+- README / architecture summary: https://github.com/parththakkar106/AI-DnD/blob/main/README.md
+- Design guide: https://github.com/parththakkar106/AI-DnD/blob/main/docs/GUIDE.md
+- License: MIT
+
+### Open Dungeon
+- Repository: https://github.com/newideas99/open-dungeon
+- Database layer: https://github.com/newideas99/open-dungeon/blob/main/src/lib/db.ts
+- Prompt/context layer: https://github.com/newideas99/open-dungeon/blob/main/src/lib/story-prompt.ts
+- Environment configuration: https://github.com/newideas99/open-dungeon/blob/main/.env.example
+- Package manifest: https://github.com/newideas99/open-dungeon/blob/main/package.json
+- License: MIT
+
+### Local Adventure Engine / ai-adventure
+- Repository: https://github.com/CaoRuiming/ai-adventure
+- Architecture: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/architecture.md
+- Privacy/security: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/privacy-and-security.md
+- License: Apache-2.0
+
+## High-value reference projects
+
+### aiMultiFool
+- Repository: https://github.com/omgboohoo/aimultifool
+- Role: local roleplay/RAG/encryption ideas
+- License: GPL-3.0
+
+### Chronicler
+- Repository: https://github.com/yantrikos/chronicler
+- Role: memory tiers, canon/heuristic/reflex separation, anti-confabulation patterns
+- License: MIT (application); YantrikDB is separately Apache-2.0
+
+### Interactive Fiction Framework
+- Repository: https://github.com/georgebutler/interactive-fiction-framework
+- Role: Story Bible, model-as-prose-writer/application-as-state-owner, validation/fallback patterns
+- License: MIT
+
+### Gamentic
+- Repository: https://github.com/hec-ovi/gamentic
+- Role: local text/image/voice provider abstraction, asynchronous media generation, large automated test suite
+- License: MIT
+
+### Sonder Engine
+- Repository: https://github.com/N0819/Sonder_Engine
+- Role: objective truth vs perception/memory/belief, commit boundary, sophisticated character knowledge
+- License: MIT
+
+### Corvus Story Core
+- Repository: https://github.com/JustLateNightAI/Corvus-Story-Core
+- Role: structured state + local ComfyUI/TTS integration
+- License: MIT
+
+## Mature ecosystem references
+
+- SillyTavern: https://github.com/SillyTavern/SillyTavern
+- RisuAI: https://github.com/kwaroran/RisuAI
+- KoboldAI Client: https://github.com/KoboldAI/KoboldAI-Client
+
+## Important research caveat
+
+Repository documentation can be stale relative to current source. Phase 0B should pin exact commit SHAs at clone time, run the projects, run their tests, and verify all network behavior locally.