The guide still has the workshop showing — TODO #111

Jesse's read of the rendered documentation after 0.8.2: dramatically better, and still
carrying too much of what was said about the game rather than what the game is. Four
things to fix, recorded with the measurements so the pass can start without re-surveying.

SECTION NUMBERS, 25 of them — rules 11, home-deck 5, mainline-deck 5, components 4,
quickstart 0. Two problems in the same notation. Sections 8.1, 8.2, 8.3, 10, 2.2 and the
7 cited by the deck documents resolve to nothing published: they are the prototype
rulebook's numbering, and rules.md:456 is a section whose own heading is named after it.
Sections 3.5 and 4.2 through 4.6 do resolve, because rules.md numbers its headings, but a
reader has to go counting. The renderer settles the fix: slug() in scripts/markdown.ts
strips a leading number, so a numbered reference has no anchor to point at and a
cross-reference has to become a named link. Do that first and the rest is mechanical.

REPOSITORY PATHS — four documents cite src/engine/content.ts to vouch that a table is
generated. The guarantee is worth keeping; the path is not.

CARD COUNTS, which reverses a standing ruling. #15a's "deliberately NOT including card
counts per category" was Jesse's call of 2026-08-22 and this is the same person reversing
it, so that entry is marked reversed here rather than left to read as current. The two
places the ruling is written into the documents are named. Generation answers the
staleness the ruling guarded against: every catalogue row already carries copiesInDeck or
copies, so the generator gains a column and the existing test keeps it honest. The one
hard part is recorded too — since 0.8.2 the office cards dealt depend on the starting
Office, so a printed count has to say it describes the default Depot opening.

BUILD-STATUS COMMENTARY, with the line that must not be crossed. "It is not implemented,
and never has been" and the live/dormantSolo/unbuilt column are an engineering status
printed for players, and they go. The facts underneath them do not: a player needs to know
the opponent-directed cards are not dealt and that the Interchange does not sort cars. A
pass that deletes the sentence and the fact together makes the documents wrong instead of
clean.

No code, no documents and no version touched — this is the worklist only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MUizFYCMHRWhbWwXhp7WPR

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