Docs: consolidate active planning and archive historical material
The planning package had grown to where a new agent could not tell what was authoritative. Phase 0 execution prompts sat beside the specification; four completed milestone reports sat beside the current one; and upstream AI-DnD's own `plan/` build log and `docs/` project site still described a hosted, scripted, multi-user product with accounts — every screenshot in it showed a Scripts tab and a Sign up button, none of which has existed since M2. `planning/archive/` now holds the history and says so in its own README: `phase0/` for the research that chose AI-DnD, `milestone-reports/` for M1 and M2, `decisions/` for ADR 008, the Phase-0-before-build gate Phase 0 satisfied. `planning/reports/` holds only the current milestone's report, because that is the one M4 planning has to read; it moves to the archive when M4's replaces it. Deleted rather than archived: the Phase 0B execution prompts and the handoff/status/summary documents, the Phase 0A discovery and triage reports, upstream's `plan/` and `docs/` trees, and `frontend/README.md`, which was Vite's template boilerplate. All of it is in Git history, and the two recommendation reports carry every conclusion the deleted research reached. Archived documents are kept verbatim. Paths written inside them point at where those files were when the document was written, which is the point: an evidence record that has been quietly edited is no longer evidence. Active documentation is corrected where it pointed at the removed trees or described removed capability as present. `DEVELOPMENT.md`'s "things M1 did not touch" list had gone stale at M2 and claimed QuickJS scripting was still tested; its test count was 604 against an actual 638. `README.md` loses the upstream CI badge, which reported upstream's pipeline rather than this fork's, and a reference to `backend/app/worldstate/engine.py`, a file that does not exist. `planning/README.md` is rewritten as the documentation index. New: `planning/PROJECT-SOURCES.md` and `planning/project-sources.txt`, the manifest of what belongs in the ChatGPT project's Sources. Source comments referring to the deleted trees are reworded; no behaviour changes. 638 backend tests pass, frontend lints and builds, and a reference scan over all 48 tracked Markdown files reports no unresolved path in active documentation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NCbwH7yLGKsj1rhXXzKSCu
This commit is contained in:
co-authored by
Claude Opus 5
parent
c8755c21c2
commit
d27ee34901
@@ -1,6 +1,5 @@
|
||||
# AI D&D
|
||||
# Adventure Storyteller
|
||||
|
||||
[](https://github.com/parththakkar106/AI-DnD/actions/workflows/ci.yml)
|
||||
[](LICENSE)
|
||||
|
||||
An interactive storytelling app that runs entirely on your own machine, with your own model.
|
||||
@@ -18,19 +17,17 @@ disabled. What is left is a storyteller you can run offline.
|
||||
> public address. There is no telemetry, no account, no cloud inference, and nothing is fetched
|
||||
> at runtime from the Internet.
|
||||
>
|
||||
> For the internals, read the **[design notes](docs/GUIDE.md)**. They walk through the context
|
||||
> budgeting, the world-state referee, and the memory bank, and state the reasoning behind each
|
||||
> one. Some sections still describe upstream subsystems this fork has removed.
|
||||
> For the internals, read [`planning/TECHNICAL-DESIGN.md`](planning/TECHNICAL-DESIGN.md) and
|
||||
> [`planning/CONTEXT-AND-MEMORY.md`](planning/CONTEXT-AND-MEMORY.md), which cover the context
|
||||
> budgeting, the state model and the memory bank as this fork builds them.
|
||||
|
||||
Built with FastAPI and SQLAlchemy on the backend and React (Vite) on the frontend, storing
|
||||
everything in one SQLite file.
|
||||
|
||||

|
||||
|
||||
*The play screen. The left rail shows live world state. The AI proposes changes each turn, and
|
||||
a Python engine decides what actually sticks. The chip under the narration reports what
|
||||
changed. The `‹ 2/2 ›` under a turn steps between the takes it has. Writing below a take that
|
||||
isn't the live one starts a new branch.*
|
||||
On the play screen, the left rail carries live world state. The AI proposes changes each turn
|
||||
and a Python engine decides what actually sticks; the chip under the narration reports what
|
||||
changed. The `‹ 2/2 ›` under a turn steps between the takes it has, and writing below a take
|
||||
that isn't the live one starts a new branch.
|
||||
|
||||
## Features
|
||||
|
||||
@@ -49,7 +46,8 @@ isn't the live one starts a new branch.*
|
||||
cast; the adventure carries their live values. The AI proposes deltas, and a Python engine
|
||||
referees them: it clamps values to range, enforces per-turn caps and cooldowns, keeps counters
|
||||
monotonic and milestones sticky, then strips the machine-readable block out of the prose
|
||||
(`backend/app/worldstate/engine.py`). Word-labeled bands (`40–60: minor damage`) make the
|
||||
(`backend/app/worldstate/`: `apply.py` clamps, `parse.py` reads the block back).
|
||||
Word-labeled bands (`40–60: minor damage`) make the
|
||||
model reliable at it. No dice and no scripting are required.
|
||||
- **AI Dungeon-compatible context engine.** Memory, author's note, and story cards (world
|
||||
info) are triggered by keywords in recent story text, then assembled under a token budget
|
||||
@@ -88,14 +86,10 @@ isn't the live one starts a new branch.*
|
||||
|
||||
## Screenshots
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
|  |  |
|
||||
| **Insights**: the exact prompt for the next turn, broken into components with token counts and the trigger word that pulled each story card in. | **Authoring**: stats with ranges, per-turn caps, cooldowns, and word-labeled bands; NPCs the AI addresses by id. |
|
||||
|  |  |
|
||||
| **Home**: continue a story in progress or start from a scenario. | **The tree**: one lane per line, from the moment it left its parent to the moment it ends. The horizontal axis is the story's own clock, so a short branch reads as short. |
|
||||
|  | |
|
||||
| **Branches**: every line the story has taken, and the three things you can do to one. A line the one you're reading was forked from can't be deleted, and says so. | |
|
||||
None yet. The inherited screenshots showed upstream's UI — a Scripts tab, Log in and Sign up,
|
||||
a guest banner, scripting demo scenarios — none of which this fork has since M2, so they were
|
||||
removed rather than left standing as a picture of a product that no longer exists. New ones
|
||||
are taken when the browser smoke test M3 still owes is run.
|
||||
|
||||
## Quick start
|
||||
|
||||
@@ -248,16 +242,15 @@ most interesting engineering in the repo.
|
||||
- `planning/` is this fork's own package: the product specification, the architecture
|
||||
decisions, the milestone plan, the acceptance contract, and a review report for every
|
||||
milestone shipped. Start at [`planning/README.md`](planning/README.md).
|
||||
- `plan/` holds the *upstream* project's phased implementation plan, kept as a build log. The
|
||||
later files (11, 12, 14) still serve as design notes for the state-revert, world-state, and
|
||||
story-tree work this fork inherited.
|
||||
- [`docs/GUIDE.md`](docs/GUIDE.md) holds upstream's design notes: how each subsystem works and
|
||||
why it was built that way, with the measurements behind the decisions. Sections covering
|
||||
scripting, accounts and hosted deployment describe subsystems this fork removed.
|
||||
- [`planning/archive/`](planning/archive/README.md) holds the Phase 0 research that chose this
|
||||
base and the completed milestone reports. It is history, not instruction.
|
||||
- [`DEVELOPMENT.md`](DEVELOPMENT.md) is how to set the project up, point it at a model, and run
|
||||
the tests. [`PROVENANCE.md`](PROVENANCE.md) records what came from upstream and what changed.
|
||||
- `backend/.env.example` lists the two environment variables the backend reads. Everything
|
||||
about the model is a runtime setting on the Settings page instead.
|
||||
- [`docs/self-review.md`](docs/self-review.md) records a full-codebase self-review pass and
|
||||
what came out of it. All correctness findings are resolved.
|
||||
- Upstream's own `plan/` build log and `docs/` project site were removed in the 2026-09-03
|
||||
documentation pass: they described AI-DnD's hosted, scripted, multi-user product. Both are
|
||||
still in Git history, and in upstream.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in New Issue
Block a user