# How to Read These Docs

> The conventions behind every page — generated versus hand-written sections, badges, verified examples, disclosed drift, date stamps, and the AI reference.

- Source: https://diceytable.com/docs/reading-these-docs
- Last verified: 2026-07-27

These docs make five structural promises. Each one changes how much you should trust a given
page, and each one is enforced by something other than good intentions — a generator, a
compiler, or a test that fails the build.

## Generated pages and hand-written pages

Reference sections are two kinds of file stitched together, and both are visible in the
repository:

- **Generated blocks** are produced directly from the code — the scripting API's `.d.ts`
  declaration, or the mod schemas' Zod definitions. They live under a `_generated/` folder,
  carry a `DO NOT EDIT` header, and are rewritten wholesale whenever the code changes.
  Signatures, parameter names, types and optionality on these pages **cannot drift from the
  code**, because they are read from it mechanically rather than transcribed.
- **Prose fragments** are hand-written and carry the *why*: when to reach for a call, what
  `null` actually means, a worked example, and the gotchas. They are merged into the
  generated skeleton at a stable marker and are never touched by regeneration.

A test re-runs both generators and fails if the committed output differs by a byte, so a
symbol added to the code cannot quietly go undocumented.

If a reference entry looks unusually terse — a signature and one line, nothing else — its
prose fragment has not been written yet. That is a gap, not a statement that the member is
uninteresting.

## The badge legend

Every scripting reference entry carries up to five badges. **The values of each badge are
defined in exactly one place in these docs, and this page links to that place rather than
restating it.** A legend that keeps its own copy of the vocabulary is a legend that will
eventually disagree with the pages it explains.

| Badge | What it tells you | Its values |
|---|---|---|
| **Authority** | Whether a call runs identically on every peer, only on whoever is hosting, or runs anywhere while its *effects* come from the host. | [The three authority values](https://diceytable.com/docs/scripting/concepts/host-authority#the-three-authority-values) |
| **Timing** | Whether the call resolves immediately or only once the result returns on the next state broadcast. | [The two timing values](https://diceytable.com/docs/scripting/concepts/async-and-snapshots#the-two-timing-values) |
| **Availability** | Which attachment points — scene script, per-entity script, mod — can reach the member. | [The four availability values](https://diceytable.com/docs/scripting/concepts/execution-order#the-four-availability-values) |
| **Capability** | For mod scripts, which manifest-declared capability gates the call. Table scripts have no capability system. | [The capability values](https://diceytable.com/docs/scripting/concepts/sandbox-limits#the-capability-values) |
| **Surface** | Which of the two script surfaces the member belongs to. | [The two surface values](https://diceytable.com/docs/scripting/concepts/choosing-a-surface#the-two-surface-values) |

Those five pages are the source of truth. The badge vocabulary is closed: a value outside the
lists they define fails the docs test suite, so a badge you see on a page is always one of
the documented values.

### Why the badges exist at all

DiceyTable is **host-authoritative**. Exactly one connected peer is the host and it owns the
table's real state; every other peer asks. That single fact is why Authority and Timing are
badges rather than prose — an API that looks synchronous can still only take effect once the
host agrees, and a page that did not say so would be misleading by omission.
[Host authority](https://diceytable.com/docs/scripting/concepts/host-authority) is the full treatment.

## Examples are verified, not merely plausible

An example that reads correctly and silently does not run is worse than no example. Every
block on this site presented as runnable code is checked before it can be published:

- **Table-script examples** are compiled against the exact TypeScript declaration that feeds
  the in-editor autocomplete, using the same compiler options the editor enforces — including
  no DOM library, because a table script has no DOM. A change to the scripting API that
  breaks a published example fails the build.
- **Mod examples** get the same treatment against the mod API's declaration and are
  *additionally* run through the same static scanner that gates real publishing. A published
  mod example is therefore guaranteed to be one the scanner would accept, not merely one that
  reads like valid JavaScript.

What this does **not** guarantee: that an example produces the outcome you want at your table.
Compilation proves the call exists and the types line up. Whether shuffling before dealing is
the right order for *your* game is a design question no compiler answers.

## Known drift is disclosed, never papered over

There are two independent script surfaces and three overlapping action vocabularies that do
not line up perfectly. Some of that is a deliberate security boundary — the mod surface is
smaller on purpose — and some of it is real, tracked drift.

Where a page describes a gap like that, it names it instead of presenting the two surfaces as
symmetrical. [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) is the map of which
name means what where, and [Known limitations](https://diceytable.com/docs/reference/known-limitations) is the
running list of what does not work yet.

**If a page and the product disagree, the product is right.** Report the mismatch rather than
assuming you misread; a page that is wrong is a bug in these docs.

## Every page is dated and editable

Every routable page carries two things in its footer:

- **Last verified: `YYYY-MM-DD`** — the day a human last confirmed the page against the
  running product. It is not the file's modification date, and a cosmetic edit does not
  advance it. It is also what the page reports to search engines as its modification date, so
  the stamp you read and the stamp a crawler reads cannot disagree.
- **Edit this page on GitHub** — a direct link to the exact source file that produced the
  page you are reading. For a reference page that is the hand-written shell; the generated
  block beside it is regenerated from code and cannot be edited there.

Version-wise, these docs describe the current release of DiceyTable. There is no archived
copy of the docs for an older build — the platform ships continuously and the pages are
verified against what is deployed, which is what the date stamp records.

## The AI Agents reference is generated too

The [AI Agents](https://diceytable.com/docs/ai-agents) track follows the same split. Its
[tool reference](https://diceytable.com/docs/ai-agents/reference/tools), [field catalogue](https://diceytable.com/docs/ai-agents/reference/fields)
and [diagnostics reference](https://diceytable.com/docs/ai-agents/reference/diagnostics) are generated from the tool
catalogue the bridge and the browser both run on, so a tool's arguments, defaults, limits and
class on those pages are read from the code rather than transcribed. Each tool also has a
hand-written fragment for when and why to use it, and a test fails the build when a tool has
none. Instead of the scripting badges, every tool carries its **class** — **R** read, **W**
write, **D** destructive, **H** human-required — defined once on
[the security model page](https://diceytable.com/docs/ai-agents/concepts/security-model#action-classes).

The setup pages are dated like every other page, and their MCP client configs were checked
against each client's own documentation on that date. Those formats change often; the date
tells you how fresh the check is.

## Conventions inside a page

- **Terminology is normative.** "Component" always means an engine component — `render`,
  `rigidbody`, `collision`, `light`, `camera`, `script` — and never a thing you place on the
  table, which is an **Entity**. Every term is defined once in the
  [Glossary](https://diceytable.com/docs/editor/concepts/glossary), and a test sweeps the whole docs tree for
  retired vocabulary.
- **Three names, three jobs.** `id` addresses an entity, `label` is its slug and uniqueness
  key, `displayName` is the optional human-facing name. They are not interchangeable; see
  [IDs, names and tags](https://diceytable.com/docs/editor/concepts/ids-names-tags).
- **`See also` links go both ways.** A guide links its reference entry and the reference
  entry links back, and a test fails the build on any `/docs/…` link — including its `#anchor`
  — that does not resolve.
- **Search covers headings and symbols, not just page titles.** Press `/` or `Ctrl+K` from
  anywhere in the docs; typing a bare member name such as `spawnObject` jumps straight to
  that member rather than to the page that mentions it.
