Canonical documents

Everything on this site is a summary. These are the documents it summarises, and where the two disagree, they are right and this site has a bug.

Why say that so bluntly

A documentation site that quietly re-specifies a contract becomes a second source of truth, and second sources of truth drift. Every page here links out for exactly this reason, and this page is the index of what it links to.

If you find a disagreement, it is worth reporting — it means a check is missing.

The documents

Document	Answers
website/ARCHITECTURE.md	How the website fits together — the canonical diagram
website/BACKEND_DESIGN.md	The API, schema and security contract
website/MODULE_SYSTEM.md	Why the module system is shaped this way
website/MODULE_API.md	Everything a module may do — the contract
website/TEAMS.md	Teams as a platform primitive
website/EVENTS.md	The Event System — leases, the ledger, and the module seam
website/SHARD_VISIBILITY.md	The audience ladder, for administrators
website/THEMING_AND_NAV.md	Admin-configurable theme, assets and navigation
website/TRUSTED_DEVICES_MFA.md	Trusted devices and the second factor
link/PLAN.md	The sidecar design of record, the data catalog and the wire protocol
link/INTEGRATION.md	Integrating with the sidecar
link/v7.md	The current protocol, and its cross-repository obligations
link/ADMIN_CONTROLS.md	What the site may command the game to do
installer/INSTALL.md	The operator guide for setting a shard up
installer/PLAN.md	The installer's design of record
modules/rust-dryrun.md	A second module designed on paper, to test that the contract generalises
modules/uo/API.md	module-uo's own API, including its audience rules
android/PLAN.md	The Android app

Every path above is checked to still exist on every build, so a document that is renamed or moved turns this page red rather than leaving a dead link.

Which document answers which question

• “May a module do this?” → MODULE_API.md. It is the contract, and it is the only thing that can answer yes.
• “Why is the module system like this?” → MODULE_SYSTEM.md.
• “What does this API return?” → your own deployment’s /api/docs, then BACKEND_DESIGN.md §4.
• “What can the shard send?” → link/PLAN.md §5, and v7.md for the current protocol.
• “What may a scheduled event do to the world?” → website/EVENTS.md for the model, MODULE_API.md for the verbs a module may declare, and link/ADMIN_CONTROLS.md for what the site may ask a game to do at all.
• “Who may see this?” → SHARD_VISIBILITY.md for the administrator’s view, modules/uo/API.md §4 for the specification.
• “How do I set a shard up?” → installer/INSTALL.md.

Where they live

All of them are in RunicGateway/docs, which is Markdown only and versioned independently of the code it describes.

A code change is not complete until docs reflects it. That is a rule in the project’s own contributor guidance, not an aspiration — a change to behaviour, protocol, endpoints, schema, configuration or the deployment model requires a matching edit there.

Two things that are not in docs

The Integration Kit is its own repository, because its audience is outside this project and it teaches rather than specifies. See The Integration Kit.

The OpenAPI specification is generated and committed in website itself, because it is derived from the routes rather than written alongside them.