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