feat(docs): phase 14 - game-neutral core docs, an Ultima Online group, and checkTerms
All checks were successful
PR checks / checks (pull_request) Successful in 2m10s

PLAN.md §16, D63/D64, plus D67-D69 taken 2026-10-22.

- Core docs use core's words: a Team, a game server, the sidecar, the bridge
  plugin, the game module. Detail that belonged to Ultima Online moved into
  its pages rather than being dropped.
- New "Ultima Online" sidebar group (nine pages): an overview, Connect a
  ServUO shard, Verify the bridge, The shard connection, Client files,
  Troubleshooting, Bridge.cfg, sidecar.toml, Shard event catalog. Five moved
  URLs answer a real 301 (src/config/redirects.mjs, asserted by the served
  test).
- Getting started is game-neutral. "Connect your game server" keeps the old
  URL and hands off to each game; Rust links docs main:rust-link/INSTALL.md
  until phase 15. "Verify the whole stack" stays, neutral (D69).
- D68: GameExample.astro labels a game's real example on a core page with the
  game's name; checkTerms allows that game's words inside it.
- scripts/checkTerms.mjs, the twelfth check: 16 game words, docs pages and
  both sidebar trees, one allowlisted phrase (Discord's "Guild (server) ID").
  Wired into verify and pr-checks.yml.
- canonicalDocs grouped by game; the Rust group carries four documents.
- D67: the screenshot rule from #32 is adopted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
This commit is contained in:
2026-10-22 08:54:37 -05:00
parent 6046214d71
commit 4426d3e339
52 changed files with 1415 additions and 557 deletions

78
PLAN.md
View File

@@ -1,6 +1,6 @@
# runicgateway.com — design of record
**Status:** phases 0–12 are built and deployed. **Revision 4 (2026-10-22) plans phases 13–18** —
**Status:** phases 0–14 are built (13 and 14 as part of revision 4). **Revision 4 (2026-10-22) plans phases 13–18** —
the second game, RunicNPC, and taking game vocabulary out of the site at large — in §16.
**Date:** 2026-08-19 (revision 3) · 2026-10-22 (revision 4)
**Repo:** `RunicGateway/runicgateway.com`
@@ -237,7 +237,7 @@ Taken by the org lead (Colby Whitlock) on 2026-08-19. Recorded so they are not r
**Decisions after D13 are recorded where they were taken**, in the section describing the phase that
raised them, rather than appended here — a decision is only re-litigated when its reasoning is
somewhere other than the thing it decided. The count of record is **sixty-six**:
somewhere other than the thing it decided. The count of record is **sixty-nine**:
| # | Where | What it settled |
|---|---|---|
@@ -256,6 +256,8 @@ somewhere other than the thing it decided. The count of record is **sixty-six**:
| D59 | §6, "How phase 12 delivered it" | The container publishes on every interface (amending D55), with `SITE_BIND_ADDR` to narrow it |
| D60–D65 | §16, "The six decisions" | Per-game sidebar groups, RunicNPC inside Rust with its own page, the RunicNPC API carried in full with a drift check, game names allowed but game vocabulary confined, a twelfth check that enforces it (amending D53), Rust screenshots last and from the rigs |
| D66 | §16, "How phase 13 built it" | The hero and footer show the Module API only; a protocol and a bundle belong to a game |
| D67 | §16, "One rule the phases need" | A screenshot belongs to its game: a capture tagged with a game may carry its words, beside the game's name |
| D68–D69 | §16, "How phase 14 built it" | A game's real example on a core page is a tagged, labelled block; *Verify the whole stack* stays in Getting started, game-neutral (amending D60) |
---
@@ -1669,6 +1671,10 @@ a mechanism rather than diligence:
reflows while it decodes. No browser and no game server — the capture tool is an authoring
script whose output is committed, exactly like the brand assets.
- **`scripts/checkTokens.mjs`** — no colour literal outside the token file (§7).
- **`scripts/checkTerms.mjs`** — added in phase 14 for D63 and D64, the twelfth check. No game's
vocabulary outside that game's section: its docs group, its sidebar group, or a
`<GameExample>` block (D68). Reads the docs and both sidebar trees; phase 17 widens it to all of
`src/`.
- `astro check` plus a production build, in CI on every PR.
---
@@ -1925,7 +1931,9 @@ screen and the NPC profile editor.
### One rule the phases need, recorded so review can object
**A screenshot belongs to its game.** Phase 9's UO captures carry the word "Shard" in the pixels and
Adopted by the org lead on 2026-10-22 as **D67**.
**D67 — A screenshot belongs to its game.** Phase 9's UO captures carry the word "Shard" in the pixels and
in their alt text. Alt text has to describe the image honestly, so a capture tagged with a game in
`screens.mjs` may use that game's words in its caption and alt. The page showing it must name the
game next to it. `checkTerms.mjs` reads the tag. The homepage's "What it looks like" therefore either
@@ -2022,6 +2030,70 @@ cover, and phase 17 is the phase that writes that list. Phase 13 does the half t
check: `checkFacts` now holds Module-Rust's declared capabilities against `platform.json`, so a
capability the module adds turns this repo red today. The page-side assertion lands with the page.
### How phase 14 built it
Three decisions, taken on 2026-10-22 when the restructure reached pages D60 had not placed. The
count of record is now **sixty-nine**. D67 is the screenshot rule above, adopted that day.
**D68 — a game's real example on a core page is a tagged, labelled block.** Some core pages need
a real example rather than an invented one: *The module manifest* shows a manifest, *Scheduled
events* names a module's budget dimensions, and the *Installer CLI* has to print
`--game <servuo|rust>`, because that is the flag. §1 prefers the real thing, since an invented
example is checked by nothing. So the example keeps its game's words and says whose they are:
`src/components/GameExample.astro` prints the game's name above the block, read from
`platform.json` so the label cannot disagree with the attribute, and `checkTerms.mjs` allows that
game's words, and only that game's, between the tags. It is D67's bargain applied to text: a
game's words are honest on a core page when the game is named right beside them. The
alternatives were an invented neutral example (the Integration Kit's template could not serve: it
mounts `/clans`) and prose only, which would have left the core pages less concrete.
**D69 — *Verify the whole stack* stays in Getting started, game-neutral.** This amends D60, which
had Getting started end on the hand-off page. The core page now teaches the four links in the
chain — the plugin loaded, the game server reached the sidecar, the sidecar is healthy, the site
is ingesting — which are the same for both games, and sends the reader to their game for the
commands. The Ultima Online commands became that group's *Verify the bridge*. The Ultima Online
host requirements moved onto *Connect a ServUO shard*, and the Ultima Online rows of
*Troubleshooting* became the group's own *Troubleshooting* page.
**What moved, and what stayed.** The Ultima Online group has nine pages: an overview (*The Ultima
Online module*, which took *Install a game module*'s "what the `uo` module adds"), *Connect a
ServUO shard*, *Verify the bridge*, *The shard connection*, *Client files*, *Troubleshooting*,
*Bridge.cfg*, *sidecar.toml* and the *Shard event catalog*. Five pages changed URL, and each old
URL answers with a real `301` from the server: `src/config/redirects.mjs`, asserted by
`test/headers.test.mjs`. *Connect a game server* did **not** move. Its URL is now the
game-neutral hand-off page (*Connect your game server*), which is a better landing for an old link
than a redirect into one game. Until phase 15, its Rust row links to `docs`
`main:rust-link/INSTALL.md`.
**The core pages use core's words** (D63): a Team, a game server, the sidecar, the bridge plugin,
the game module. Detail that was really one game's moved into that game's pages rather than being
dropped. *The bridge*'s guild-roster passage, for example, is now a general rule about Team rosters,
with the Ultima Online specifics in its event catalog. Three passages were checked against Rust before they were
generalised: both bridges dial loopback newline-delimited JSON with one writer thread, both
sidecars answer `/health` with *plugin connected*, both plugins ship `EventsEnabled` off, and
both modules encrypt their sidecar token with core's key. `canonicalDocs` is now grouped by
game, and the Rust group carries four documents. Discord's *guild* became *Discord server*
everywhere except the one label core's Discord Bot screen really prints, *Guild (server) ID*,
which is the check's only allowlist entry, as D64 predicted.
**`checkTerms.mjs` is the twelfth check.** It reads every docs page, frontmatter included, and
both sidebar trees as data. It knows 16 words, each tagged with its game. Link targets, bare URLs,
imports and `{…}` expressions are not read, because an address is not prose and an expression
renders a value from `src/data/`, which phase 17 brings into scope. Fenced code is read. An
allowlist entry that stops matching fails the check, so the list cannot rot. Before it was
trusted it was run against a planted page: five violations (a word in prose, in a title, in link
text, in a code fence, and inside another game's block) all failed, and a URL and an expression
carrying the same words both passed.
**Two findings outside this repository**, reported rather than fixed (they belong to other
repositories):
- **Core's own Teams panel says "shard".** `website` `client/src/lib/teamAdmin.js` tells an
administrator the list "is not a confirmed empty shard". The docs page now paraphrases it
rather than quoting it.
- **The installer's `--help` says "Which game's shard side"** for `--game`, and `--site-url` names
"Admin → Shard (uo-link)" for both games.
---
[api]: https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/website/MODULE_API.md