docs(plan): the design of record for runicgateway.com #1

wtclaude · 2026-08-19T20:08:04Z

wtclaude commented

2026-08-19 20:08:04 +00:00

Reconnaissance across the nine RunicGateway checkouts, and the plan for the public site + documentation experience built on top of them. Nothing is built — this is the document to argue with before anything is.

The principle

The site is a presentation layer over existing project knowledge, never a competing source of technical truth. Normative contracts (MODULE_API.md, link/INTEGRATION.md, TEAMS.md, INSTALL.md, …) stay canonical in docs/ and are linked, never copied. What the site authors is the journey — install, configure, administer, extend — which no existing document owns end to end, because the repos are organised by component and an operator is not.

Two things worth reading first

§3 — eleven places the repositories contradict each other. Verified against origin/main, and listed rather than resolved quietly. The two that matter:

link/INTEGRATION.md disagrees with itself. Its event catalog fully documents the protocol-4 kinds — guild.roster, guild.leave, a subsection headed "On Protocol 4" — while its normative §2 still declares X-UOLink-Version: 3, "protocol": 3 in /health and ws.hello, and a worked JS client sending "3". This is the contract a third-party integrator implements against.
installer/INSTALL.md still hands operators "Protocol version 3" (line 413) — the value they paste into Admin → Shard. The document's own troubleshooting table says a stale protocol number is answered with 409 and "looks exactly like your shard going offline".

§4 — Phase 0 fixes those before the site quotes anything. Four PRs across docs and .profile. None touch code or a contract; each corrects documentation to match what main already does.

A process failure, recorded

§1 records a mistake and the rule taken from it. An earlier draft of this report claimed the platform was on protocol 3, with 4 "feature-complete on edge, not cut over". Wrong — protocol 4 is on main and released (bundle 2026.08.19, link v2.0.0, overlay v1.0.0).

The cause: all nine checkouts sat on feature branches whose local main ref had never been fetched, so git show main:<path> answered confidently from a months-old blob. Local main was 1–3 commits behind origin/main in seven of nine repos.

Every fact in §2 is now read from origin/main or the Gitea API, and §7 turns that into a build-time check rather than a promise — checkFacts.mjs fails the build when the site's stated versions drift from their authorities, the same mechanism and intent as the Integration Kit's checkCoreApi.js.

What the site will and will not claim

§2 records the verified state — protocol 4, Module API 1.6.0, module-uo v1.0.1, 72 module routes, Teams merged to main — and an equally load-bearing "does not exist" list. Notably Matrix will not be advertised: TEAMS.md §8 is explicit research, and of the five capabilities a shared interface would name, a Matrix implementation could honestly provide two. The original brief for this site listed it as a feature; it is not one.

Still open

§9 leaves five questions rather than assuming answers — whether Phase 0 lands as PRs or issues, whether the lower-severity doc hygiene (§3 items 6–10) is in scope, what to do about the zero web-UI screenshots that exist anywhere in the workspace, the product mark, and how direct the docs should be about maturity.

AI usage

This contribution is AI-assisted. Tool: Claude (Claude Code). Commits carry a Co-Authored-By: Claude trailer.

Reconnaissance across the nine RunicGateway checkouts, and the plan for the public site + documentation experience built on top of them. **Nothing is built** — this is the document to argue with before anything is. ## The principle The site is a **presentation layer over existing project knowledge, never a competing source of technical truth.** Normative contracts (`MODULE_API.md`, `link/INTEGRATION.md`, `TEAMS.md`, `INSTALL.md`, …) stay canonical in `docs/` and are linked, never copied. What the site authors is the **journey** — install, configure, administer, extend — which no existing document owns end to end, because the repos are organised by component and an operator is not. ## Two things worth reading first **§3 — eleven places the repositories contradict each other.** Verified against `origin/main`, and listed rather than resolved quietly. The two that matter: - **`link/INTEGRATION.md` disagrees with itself.** Its event catalog fully documents the protocol-4 kinds — `guild.roster`, `guild.leave`, a subsection headed "On Protocol 4" — while its normative §2 still declares `X-UOLink-Version: 3`, `"protocol": 3` in `/health` and `ws.hello`, and a worked JS client sending `"3"`. This is the contract a third-party integrator implements against. - **`installer/INSTALL.md` still hands operators "Protocol version 3"** (line 413) — the value they paste into Admin → Shard. The document's own troubleshooting table says a stale protocol number is answered with `409` and "looks exactly like your shard going offline". **§4 — Phase 0 fixes those before the site quotes anything.** Four PRs across `docs` and `.profile`. None touch code or a contract; each corrects documentation to match what `main` already does. ## A process failure, recorded §1 records a mistake and the rule taken from it. An earlier draft of this report claimed the platform was on **protocol 3**, with 4 "feature-complete on `edge`, not cut over". Wrong — protocol 4 is on `main` and released (bundle `2026.08.19`, link `v2.0.0`, overlay `v1.0.0`). The cause: all nine checkouts sat on feature branches whose local `main` ref had **never been fetched**, so `git show main:<path>` answered confidently from a months-old blob. Local `main` was 1–3 commits behind `origin/main` in seven of nine repos. Every fact in §2 is now read from `origin/main` or the Gitea API, and **§7 turns that into a build-time check rather than a promise** — `checkFacts.mjs` fails the build when the site's stated versions drift from their authorities, the same mechanism and intent as the Integration Kit's `checkCoreApi.js`. ## What the site will and will not claim §2 records the verified state — protocol 4, Module API 1.6.0, module-uo v1.0.1, 72 module routes, Teams merged to `main` — and an equally load-bearing **"does not exist"** list. Notably **Matrix will not be advertised**: `TEAMS.md` §8 is explicit research, and of the five capabilities a shared interface would name, a Matrix implementation could honestly provide two. The original brief for this site listed it as a feature; it is not one. ## Still open §9 leaves five questions rather than assuming answers — whether Phase 0 lands as PRs or issues, whether the lower-severity doc hygiene (§3 items 6–10) is in scope, what to do about the **zero web-UI screenshots** that exist anywhere in the workspace, the product mark, and how direct the docs should be about maturity. --- ### AI usage - [x] This contribution is AI-assisted. Tool: **Claude (Claude Code)**. Commits carry a `Co-Authored-By: Claude` trailer.

wtclaude added 1 commit 2026-08-19 20:08:06 +00:00

docs(plan): the design of record for runicgateway.com 96f77a87e1

Reconnaissance across the nine RunicGateway checkouts, and the plan for the
public site + documentation experience built on top of them.

The site is a presentation layer over existing project knowledge: normative
contracts stay canonical in docs/ and are linked, never copied. What the site
authors is the journey — install, configure, administer, extend — which no
existing document owns end to end, because the repos are organised by
component and an operator is not.

Two things worth reading before the rest:

- Section 3 lists eleven places the repositories contradict each other,
  verified against origin/main rather than resolved quietly. The sharpest is
  that link/INTEGRATION.md documents the protocol-4 event kinds while its
  normative section 2 still declares X-UOLink-Version: 3 — one document
  disagreeing with itself. installer/INSTALL.md still hands operators
  "Protocol version 3", which is the value they paste into Admin -> Shard,
  and its own troubleshooting table says a stale number looks exactly like
  the shard going offline.

- Section 4 makes fixing those a Phase 0 that lands before the site quotes
  anything: four PRs across docs and .profile, none of which touch code or a
  contract. They correct documentation to match what main already does.

Section 1 also records a process failure and the rule taken from it. An
earlier draft claimed the platform was on protocol 3 with 4 "not cut over".
Every checkout was on a feature branch whose local main ref had never been
fetched, so git show main:<path> answered from a months-old blob. Every fact
in section 2 is now read from origin/main or the Gitea API, and section 7
turns that into a build-time check instead of a promise.

Section 9 leaves five questions open rather than assuming answers.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech merged commit 71ce9d2eb1 into main

2026-08-19 20:09:08 +00:00

whitlocktech deleted branch docs/site-plan

2026-08-19 20:09:08 +00:00

whitlocktech referenced this issue from a commit

2026-08-19 20:09:10 +00:00

Merge pull request 'docs(plan): the design of record for runicgateway.com' (#1) from docs/site-plan into main

wtclaude referenced this pull request

2026-08-19 22:55:25 +00:00

docs(plan): record the org lead's decisions and design against them #2

Sign in to join this conversation.