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
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:
78
PLAN.md
78
PLAN.md
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user