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,36 @@
+# ADR 001 — Browser-First User Interface
+
+**Status:** Accepted
+
+## Decision
+
+The primary user interface will be browser-based.
+
+## Context
+
+The application must support persistent interactive storytelling, campaign management, branch/checkpoint navigation, state inspection, imported knowledge management, and future images/video. These requirements are substantially better suited to a graphical browser interface than a terminal-only interface.
+
+## Alternatives Considered
+
+- terminal-only UI,
+- Open WebUI as the primary product UI,
+- native desktop application,
+- browser-based application.
+
+## Reason
+
+A browser interface provides the best path for:
+
+- transcript interaction,
+- story-tree visualization,
+- state/library panels,
+- streaming text,
+- local deployment,
+- future generated graphics/video,
+- cross-platform use without separate native clients.
+
+## Consequences
+
+- terminal-first candidate projects will require a browser layer if selected,
+- runtime browser dependencies must remain local/offline-capable,
+- remote CDN assets should not be required in production.
@@ -0,0 +1,29 @@
+# ADR 002 — Ollama Is the v1 Model Backend
+
+**Status:** Accepted
+
+## Decision
+
+v1 will target local Ollama inference.
+
+## Context
+
+The intended deployment already has a local Ollama inference engine. The project prioritizes local control, privacy, and predictable integration.
+
+## Alternatives Considered
+
+- multiple cloud providers,
+- LM Studio,
+- llama.cpp direct integration,
+- arbitrary OpenAI-compatible endpoints,
+- Ollama.
+
+## Reason
+
+Ollama is already available locally, provides a simple local API, supports both text-generation and embedding models, and avoids requiring external inference services.
+
+## Consequences
+
+- candidate forks supporting multiple cloud providers should be simplified or hardened,
+- candidate projects using another local API need an adapter,
+- future backend abstraction may be added, but v1 should not be delayed to support it.
@@ -0,0 +1,36 @@
+# ADR 003 — Application-Owned Authoritative State
+
+**Status:** Accepted
+
+## Decision
+
+The application, not the language model, will own authoritative story history and state.
+
+## Context
+
+Language models do not reliably preserve long-term continuity and should not be trusted as the sole record of facts, branches, checkpoints, or campaign history.
+
+## Alternatives Considered
+
+- rely on chat transcript/model context,
+- rely on rolling summaries only,
+- application-owned structured state plus immutable history.
+
+## Reason
+
+Application-owned state enables:
+
+- persistence,
+- rollback,
+- branching,
+- continuity,
+- inspection,
+- export,
+- deterministic recovery,
+- debugging.
+
+## Consequences
+
+- model outputs that imply state changes should be treated as proposals,
+- state updates require validation,
+- the database must remain authoritative even if the model contradicts it.
@@ -0,0 +1,35 @@
+# ADR 004 — Local-Only Production Default
+
+**Status:** Accepted
+
+## Decision
+
+The production application will be designed to operate without Internet access.
+
+## Context
+
+The project requires control over story data, imported material, prompts, and model outputs, with no unintended disclosure to outside services.
+
+## Alternatives Considered
+
+- hybrid local/cloud,
+- optional cloud providers enabled by default,
+- local-only default with future explicitly enabled extensions.
+
+## Reason
+
+Local-only operation best matches the privacy and control requirements.
+
+## Consequences
+
+The production application should avoid:
+
+- telemetry,
+- analytics,
+- cloud inference,
+- remote vector stores,
+- automatic web retrieval,
+- runtime CDN dependencies,
+- remote fonts/assets.
+
+All inherited network behavior from a fork must be inventoried during Phase 0.
@@ -0,0 +1,29 @@
+# ADR 005 — Branch-Preserving Story History
+
+**Status:** Accepted in principle; implementation pending Phase 0
+
+## Decision
+
+Returning to an earlier story point should preserve abandoned future history as another branch rather than destructively erasing it.
+
+## Context
+
+The user must be able to recover from unwanted story developments and explore alternatives while retaining prior work.
+
+## Alternatives Considered
+
+- destructive undo,
+- overwrite-in-place editing,
+- complete copy of campaigns for every retry,
+- branch-preserving turn graph.
+
+## Reason
+
+A branch-preserving history provides recovery, experimentation, and auditability without unnecessary campaign duplication.
+
+## 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.
@@ -0,0 +1,27 @@
+# ADR 006 — Genre-Agnostic Core
+
+**Status:** Accepted
+
+## Decision
+
+Core data structures and workflows will not hard-code fantasy or science-fiction concepts.
+
+## Context
+
+The same application should support swords-and-sorcery, hard science fiction, space opera, mystery, and other interactive-fiction genres.
+
+## Alternatives Considered
+
+- fantasy-specific schema,
+- separate engine per genre,
+- generic story engine with campaign profiles.
+
+## Reason
+
+The underlying requirements—characters, locations, relationships, history, facts, scenes, memory, and branches—are common across genres.
+
+## Consequences
+
+- genre-specific rules belong in profiles/configuration/canon,
+- avoid schema columns such as `spell`, `sword`, `spaceship`, etc.,
+- use generic concepts such as entities, items, vehicles, locations, organizations, and facts.
@@ -0,0 +1,33 @@
+# ADR 007 — Preserve Future Image and Video Extension Points
+
+**Status:** Accepted
+
+## Decision
+
+v1 will not require media generation, but the story/state model will preserve scene and visual metadata so local image/video generation can be added later.
+
+## Context
+
+Future desired experiences include:
+
+- generating an image when entering a location,
+- generating character portraits,
+- generating illustrations from important scenes,
+- generating video recaps from multi-turn action sequences.
+
+## Alternatives Considered
+
+- defer all media concerns until later,
+- integrate image/video immediately,
+- reserve scene/asset abstractions now without implementing providers.
+
+## Reason
+
+Scene and character continuity information is inexpensive to preserve now and expensive to reconstruct later.
+
+## Consequences
+
+- scene snapshots should be part of the v1 data model,
+- characters/locations should allow visual descriptors,
+- asset/media tables or interfaces may be reserved,
+- the story engine must not depend on a specific image/video backend.
@@ -0,0 +1,27 @@
+# ADR 008 — Complete Phase 0 Before Detailed Build Planning
+
+**Status:** Accepted
+
+## Decision
+
+The project will complete repository research, validation, architecture selection, and critical prototypes before writing 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.
+
+## Alternatives Considered
+
+- write full implementation plan immediately,
+- begin coding against the first plausible project,
+- perform a bounded Phase 0 and then finalize the build plan.
+
+## Reason
+
+The third approach reduces speculative planning and prevents large amounts of rework.
+
+## 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.