docs: add agent workflow and reference docs

AGENTS.md defines the session loop; docs/oracle.md and docs/games.md cover table mechanics and the game package contract.
2026-09-13 16:41:26 +08:00
parent c60c9d5072
commit 275ec8531d
4 changed files with 435 additions and 0 deletions
@@ -0,0 +1,54 @@
+# solo-journaling
+
+A workspace for solo TTRPG journaling with an AI GM. You describe what your
+character does; the agent consults the oracle, narrates the outcome, and writes
+it all to a session log.
+
+## How it works
+
+- **You talk, the agent writes.** All files are produced by the agent. You never
+  need to edit anything by hand.
+- **The oracle is a d6.** Yes/and, yes, yes/but, no/but, no, no/and. See
+  `docs/oracle.md`.
+- **Games are packages.** Each game under `games/` ships its rules, spark
+  tables, character backgrounds, and tool scripts. See `docs/games.md`.
+- **Campaigns are play state.** Each campaign under `campaigns/` holds the PC,
+  the world, the clocks, and the session logs, and names the game it runs.
+
+## Getting started
+
+```sh
+pnpm install
+pnpm journal games
+pnpm journal new-campaign my-campaign --game generic
+```
+
+Then tell the agent to start a session. It reads `AGENTS.md` for how to run
+things.
+
+## Layout
+
+```
+AGENTS.md              how the agent runs a session
+docs/oracle.md         oracle and table mechanics
+docs/games.md          the game package contract
+games/<id>/            a game: rules, tables, characters, scripts
+campaigns/<name>/      play data: premise, PC, world, state, sessions
+packages/oracle/       dice, oracle, and CSV table engine
+packages/cli/          the `journal` command
+```
+
+## Commands
+
+```sh
+pnpm journal roll sparks --campaign my-campaign
+pnpm journal oracle "Is the door locked?" --complicate --campaign my-campaign
+pnpm journal background --campaign my-campaign   # a command from the generic game
+pnpm journal dice 2d6+1
+pnpm journal tables --campaign my-campaign
+pnpm journal check --campaign my-campaign
+pnpm journal games
+```
+
+Tables are looked up in the campaign first, then in its game, so a campaign can
+override a single table without copying the rest.