diff --git a/TODO.md b/TODO.md index 643806b..16acd52 100644 --- a/TODO.md +++ b/TODO.md @@ -106,7 +106,7 @@ Not items. Things that are true of every change, and that have gone wrong when s 7. **Play balance** — #61 #62 #63 #64 #67 #68 #69 #70 #71 #72 #73 #66 #65 #74 8. **The bot** — #104 #105 #106 #41 #57 #59 #54 #58 #55 #56 #60 9. **Code health and housekeeping** — #46 #45 #84 #87 -10. **Documentation and assets** — #15a #86 #88 +10. **Documentation and assets** — #15a #86 #88 #111 Then, at the back: **Reference** (the measurements, rulings and rejected approaches behind the items above) and **Done** (everything closed, kept because several of them are the only record of a @@ -606,6 +606,11 @@ What the project says about itself, and what it ships alongside the code. - [ ] **#88** — `card-reference.md`'s industry table may still be stale beyond Grocer's Warehouse and the Oil Refinery. See **Reference · #88**. +- [ ] **#111** — A full pass over the five player-facing documents: strip the playtest commentary and + the pointers into the code, publish the card counts, and take out every section number and + repository-file reference. Jesse's read after the 0.8.2 rendering landed — much better, still + too much of the workshop showing. See **Reference · #111**. + --- ## Reference — measurements, rulings and rejected approaches @@ -2041,7 +2046,9 @@ unbuilt, each row citing the file that reads it); the same honesty is what makes reference worth more than a transcription. `enhancementText()` and `mainlineDescription()` are the model: prose composed from the data, so a tooltip cannot drift from the rule it describes. -**Deliberately NOT including card counts per category.** Jesse's call in the same breath: the +**Deliberately NOT including card counts per category — REVERSED 2026-09-23, see #111.** The +ruling below stood from 2026-08-22 until Jesse asked for the counts to be published; generation +answers the staleness it was guarding against. Read it as history. Jesse's call in the same breath: the counts move with play balance, so a document that prints them is stale on the next retune. The same rule was applied to `content.ts`'s own comments on 2026-08-22 — see the pass recorded in CHANGELOG for what came out and what was kept. @@ -2108,6 +2115,82 @@ placeholder said. **The balance question the entry was really guarding is #70** supply and the uniform 1/1/1 industry model, both marked provisional in `content.ts`) — that is where it belongs, and it is still open. +#### #111 — A full editorial pass over the player-facing documentation. + +**Raised by Jesse 2026-09-23**, on reading the rendered guide and the rewritten wrapper +instructions that shipped in 0.8.2. The verdict was that both are dramatically better and that the +workshop is still visible through them: *"There is still far too much of the feedback from +playtesting, pointing directly into code, commentary about decisions made versus gaps… People +playing the game do not need reference to old, outdated source material. They just want the +rules."* Four things to fix, and they are separable. + +**1. Take the section numbers out.** Measured on 2026-09-23: `rules.md` 11, `home-deck.md` 5, +`mainline-deck.md` 5, `components.md` 4, `quickstart.md` 0. They are two different problems wearing +the same notation: + +- **References to a rulebook nobody has.** §8.1, §8.2, §8.3, §10, §2.2 and the §7 cited in the deck + documents do not resolve to anything published — they are the numbering of the prototype rules + document. `rules.md:456` is the worst of them: a section whose own heading is + `## §8.1 in practice`, named after a document the reader cannot open. `rules.md:203` quotes one + outright — `§6.2: *"If any of the Department decks is empty…"*`. +- **References that do resolve, but only by number.** §3.5, §4.2–§4.6 and §6 are real sections of + `rules.md`, which numbers its own headings 1–7. These are not wrong, they are brittle and + unfriendly: `home-deck.md:207` "see Rules §4.4" asks a player to go count. + + **The renderer settles how to fix these.** `scripts/markdown.ts`'s `slug()` deliberately strips a + leading section number, so §4.6 has no anchor to link to — the target is + `rules.html#passenger-work`. A cross-reference therefore becomes a named link + (`[Passenger work](rules.md#passenger-work)`) and the heading numbers themselves come off. Do + that first: it is what makes the rest of the pass mechanical. + +**2. Take the pointers into the repository out.** Four of the five documents cite +`src/engine/content.ts` by path — `home-deck.md:8`, `mainline-deck.md:8`, `rules.md:8`, +`components.md:10` — to vouch that a table is generated. The guarantee is worth keeping and the +path is not; say the tables are generated from the game itself. No `.ts`, `.md` or `docs/` path +belongs in a player's document. (`docs/design.md` is a developer document and out of scope.) + +**3. Publish the card counts.** *"It will change as playtesting evolves and things alter, but the +current count should be listed here. That is crucial information."* + +> **This reverses a standing ruling — #15a's "Deliberately NOT including card counts per +> category", Jesse's call of 2026-08-22 — and it is the same person reversing it.** Two years of +> that ruling are baked into the files and all of it has to come out: the banner at +> `home-deck.md:12` (*"Card counts are not published…"*) and the clause at `components.md:11` +> (*"per-category CARD counts are not published, because they move with play balance"*). Update +> #15a's reference entry so it does not read as still in force. + +The staleness the old ruling guarded against is answered by generation, not by omission. Every +catalogue row already carries its own count — `copiesInDeck` on track and office cards, `copies` on +industries, modifiers, enhancements, Mainline cards and Second Section — so +`scripts/build-card-reference.ts` gains a **Copies** column and `test/card-reference.test.ts` keeps +it honest for free. Nothing is typed by hand, and the count cannot drift from the deck. + +**The one hard part is which deck a printed count describes.** Since 0.8.2 the office cards dealt +depend on the house rule: a game opening on Depots pulls the four Depot cards, one opening on +Whistle Posts keeps them. A single number is wrong for one of those two games. Print the default +game — every district opens on a Depot — and say so where the office table gives its counts. +`deckComposition()` and `SOLITAIRE_DECK_SIZE` are the totals to reconcile against. + +**4. Strip the build-status commentary, without deleting true information.** Measured lines: +`rules.md` 5, `home-deck.md` 4, `mainline-deck.md` 3, `quickstart.md` 2, `components.md` 0. The +distinction that matters: + +- **Commentary about the project — goes.** `rules.md:6` "this document reports **executable + behaviour** and marks unimplemented material"; `mainline-deck.md:104` "**It is not implemented, + and never has been.**"; the `live` / `dormantSolo` / `unbuilt` vocabulary in `home-deck.md`'s + enhancement table (251, 265, 273, 276) — that is an engineering status column printed for + players. +- **The fact underneath it — stays, in the player's language.** A player does need to know that + the opponent-directed cards are not in the deck, that the Interchange does not sort cars, and + that Facing Point Locks and the Water Column do nothing to a solitaire opponent. Say what happens + at the table ("this card is not dealt", "this card has no effect in a solitaire game"), not what + the code has got round to. A pass that deletes the sentence and the fact together makes the + documents wrong rather than clean. + +**Where this leaves #15a.** Nothing here reopens it — the tables are generated and that holds. This +is the editorial half that generation was never going to do. + + ## Done Closed items, kept because several are the only record of a ruling or a lesson. Newest first within