---
title: Canonical documents
description: Where the normative specifications live — the documents that win whenever this site disagrees with them.
---

import { Aside } from '@astrojs/starlight/components';
import { canonicalDocs } from '../../../../data/reference.mjs';

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**.

<Aside type="note" title="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.
</Aside>

## The documents

<table>
  <thead><tr><th>Document</th><th>Answers</th></tr></thead>
  <tbody>
    {Object.entries(canonicalDocs).map(([docPath, why]) => (
      <tr key={docPath}>
        <td>
          <a href={`https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/${docPath}`}>
            <code>{docPath}</code>
          </a>
        </td>
        <td>{why}</td>
      </tr>
    ))}
  </tbody>
</table>

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 `v4.md` for the current protocol.
- **"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`](https://gitea.whitlocktech.com/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](/docs/modules/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.