docs(builder): phase 8 — modules, architecture and reference #12
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: RunicGateway/runicgateway.com#12
Reference in New Issue
Block a user
No description provided.
Delete Branch "feat/phase-8-docs"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Twenty pages completing the tree §10 planned — Modules (8), Architecture (5), Reference (7). With phase 7's twenty, the documentation is now whole.
The four decisions (D38–D41)
Taken before anything was written; recorded in PLAN.md §10, How phase 8 built the builder and reference docs. The count of record is now forty-one.
/architecture/'s drawn diagrams rather than importing themplannedSidebarstops being a checklist and becomes a checked invariantD39, and the line it draws
§1 forbids re-specifying a contract, and a Reference section is exactly where that rule is most tempting to break. The line: names are on the page, semantics are not. Every environment variable, config key, installer command, visibility rung and canonical document is listed with one terse line saying what it is for. Shapes, defaults that matter, interactions and every "why" stay in the canonical document.
That is only safe because the names are checked.
scripts/checkReference.mjscompares six enumerations against the repositories that own them —website,link,installer,servuo-plugins,Module-uo,docs— over the Gitea API, never from a working tree, as set comparisons in both directions.The second direction is the one that earns its keep: a reference page does not usually rot by describing something that vanished — it rots by quietly not mentioning the three things added since it was written.
The alternative on the table was strict summary-plus-link with nothing enumerated. It needs no machinery and cannot rot, but a Reference section that cannot answer "what variables are there?" without a click-through is a link farm — and the machinery turned out to be one script.
Descriptions are deliberately not checked, and the script says so. Nothing can know whether a one-line summary is still true; keeping them short enough to re-read is the mitigation, not a check.
The check went green first try, so I broke it seven times
That is the least trustworthy possible outcome, and this repo has been bitten by it twice already (the
load-vs-transformguard; phase 7'smark). Every mutation was caught:The ladder case is the one worth keeping. It is a security boundary, and a set comparison alone would have passed a reordering — so it is compared as an ordered sequence. A reader reasoning about "staff and above" depends on the rungs being in the right order.
What the phase found before any page shipped
plannedSidebarhad already drifted. Phase 7 added the Content page under D37 and never updated the planned list. Nothing failed, because nothing read it — which is the entire argument for D41. Reproduced by deleting the entry again and watching the new check catch it.module.json'smountsand the SPA's paths are different mechanisms, and no single document said so plainly.module-uodeclaresadmin: ["/shard", "/uo-link"]while its screen lives at/admin/uo/link— API routes are deliberately not namespaced; SPA routes are. That is exactly the distinction the installer got wrong in v0.1.0, and it now has a named home on The module system, with the "it redirects to the dashboard so it looks like it worked" failure mode spelled out.D40, briefly
/architecture/'s three diagrams are Astro components carrying marketing chrome and depending onsrc/styles/diagram.css, which Starlight does not load. Importing them would couple the two layouts for one page's benefit. The docs use text diagrams in code blocks — which also paste into an issue — and link out to the drawn versions.Verification
npm run verifygreen end to end:plannedSidebarwebsite mainastro check0 errors / 0 warnings, 36 tests passcheck:sidebarruns early in CI (no token, no build, fails fast);check:referenceruns at the end with the other networked checks, using the sameREGISTRY_TOKENmapping.Note
Everything in these twenty pages is a summary that links out, and Canonical documents says so in as many words: where this site and
docsdisagree,docsis right and this site has a bug. If you spot one, it means a check is missing.AI-assisted: written with Claude Code (Opus 5).
🤖 Generated with Claude Code
Recovering installer's orphan tag published v0.1.1, which moved the platform under this branch and turned checkFacts red -- the check working exactly as it should, since a version this site quotes had changed. FAIL release installer platform.json says : v0.1.0 installer releases/latest says : v0.1.1 The 500 that orphaned the tag was a race with the tag push one second earlier, not a structural failure: re-running the workflow took the built-in orphan-tag recovery path and published all four assets unchanged. So the stale-path Aside stops saying "v0.1.0 is still the current download", which is no longer true, and says the durable thing instead -- v0.1.0 prints the old path, v0.1.1 prints the real one -- which stays correct however many releases follow. platform.json and the PLAN.md version table move to v0.1.1, and the phase 7 findings record the pipeline defect as a fourth finding. Co-Authored-By: Claude <noreply@anthropic.com>Twenty pages completing the tree section 10 planned: Modules (8), Architecture (5) and Reference (7). Four decisions, D38-D41, recorded in PLAN.md section 10. D39 is the one that shaped the phase. Section 1 forbids re-specifying a contract, and a Reference section is exactly where that rule is most tempting to break, so the line is drawn at names: every environment variable, config key, installer command, visibility rung and canonical document is listed with one terse line saying what it is FOR, while shapes, semantics and every "why" stay in the canonical document. That is only safe because the names are checked. checkReference.mjs compares six enumerations against the repositories that own them, over the Gitea API, as set comparisons in BOTH directions -- and the second direction is the one that earns its keep, because a reference page does not usually rot by describing something that vanished, it rots by quietly not mentioning what was added since. The check went green on its first run, which is the least trustworthy possible outcome, so it was verified by breaking it: seven mutations, all caught. The one worth keeping is the visibility ladder REORDERED with its membership unchanged -- it is a security boundary, and a set comparison alone would have passed it. D41 turns plannedSidebar from a checklist into a checked invariant, and finding out why was the phase's first defect: it had already drifted, because phase 7 added the Content page under D37 and never updated the list. Nothing failed, because nothing read it. checkSidebar.mjs now asserts the two trees agree on groups, labels and order -- order because the order of Getting started IS the installation path. Two more things the writing found. PLAN.md's page count was wrong and had been since section 10 was written ("roughly 38, 37 planned" for a tree of forty). And module.json's `mounts` and the SPA's paths are different mechanisms that no single document stated plainly -- module-uo declares admin: ["/shard", "/uo-link"] while its screen lives at /admin/uo/link, because API routes are deliberately NOT namespaced while SPA routes are. That is precisely the distinction the installer got wrong in v0.1.0, and it now has a named home. D40: the docs link to /architecture/'s drawn diagrams rather than importing them. Those components carry marketing chrome and depend on diagram.css, which Starlight does not load; the docs use text diagrams, which paste into an issue. npm run verify green: 40 pages across 5 groups agree with plannedSidebar, 2390 internal links resolve, 123 repository links point at a branch, 19 facts, 59 quickstart checks, 22 reference enumerations, astro check 0 errors, 36 tests. Co-Authored-By: Claude <noreply@anthropic.com>