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,81 @@
+# Oracle and tables
+
+## The d6 oracle
+
+A single d6 answers yes/no questions about the world.
+
+| d6 | Result | Meaning |
+|----|--------|---------|
+| 6 | **Yes, and…** | It works, and there is a fortunate extra. |
+| 5 | **Yes** | It works, plainly. |
+| 4 | **Yes, but…** | It works, at a cost or with a complication. |
+| 3 | **No, but…** | It fails, but there is a consolation or opening. |
+| 2 | **No** | It fails, plainly. |
+| 1 | **No, and…** | It fails, and there is an additional setback. |
+
+Ask one question at a time, and phrase it so both answers are interesting. The
+oracle answers the world; it does not decide what the PC wants.
+
+```
+journal oracle "Is the gate locked?" --campaign ashfall
+```
+
+## Complications
+
+The complication table supplies a twist. Roll it on `and`/`but` results, or
+whenever the fiction needs one:
+
+```
+journal oracle "Is the gate locked?" --complicate --campaign ashfall
+journal roll complication-themes --campaign ashfall
+```
+
+The table is resolved like any other (see below), so a campaign without its own
+`complication-themes.csv` falls back to the one the game ships.
+
+## Spark tables
+
+Any CSV in a campaign's or game's `tables/` directory is a spark table. The
+header must contain `min`, `max`, and `text`; `tags` is optional.
+
+```csv
+min,max,text,tags
+1,1,"A sign of recent passage",exploration
+2,2,"Something out of place",mystery
+```
+
+- `min`/`max` are inclusive integers and define the die range. `1..6` is a d6;
+  `1..66` reads as a d66; any contiguous range works.
+- `text` is the result, quoted if it contains a comma.
+- `tags` holds one or more tags separated by `;` or `|`.
+
+### Lookup order
+
+`journal roll <name>` searches:
+
+1. `campaigns/<campaign>/tables/<name>.csv`
+2. `games/<game>/tables/<name>.csv`
+
+So a campaign can override a single game table without copying the rest. Use
+`journal tables` to see both sources, labelled.
+
+```
+journal roll sparks --campaign ashfall
+journal roll sparks --tag mystery --campaign ashfall
+journal roll sparks --count 3 --campaign ashfall
+journal roll sparks --game generic
+```
+
+A tagged roll picks uniformly among matching entries rather than rolling on the
+range, since ranges stop being meaningful once the table is filtered.
+
+## Validation
+
+`journal check` parses every table for a campaign and its game, reporting
+overlapping ranges and parse failures as errors, and range gaps and missing
+directories as warnings.
+
+```
+journal check --campaign ashfall
+journal check --game generic
+```