---
title: Documentation Authoring Rules
type: guide
audience: human + agent
authority: canonical — how docs in this corpus are written and edited
status: current
---

# Documentation Authoring Rules

How to create and edit documentation in this repo. These rules exist because the
corpus is meant to read as a coherent, drift-free reference (and a future book) —
not as an accreting pile of notes. Read [`docs/README.md`](./README.md) first for
the map; this file is the *how-to-write* layer.

The rules are not aesthetic. Each one fixes a failure that actually happened
during the corpus migration.

## 1. Link the canon — never copy it

**The one law.** If you need to state a family, an intent, a verb, a size, a
color role, or any other canonical value, **link the canon** — do not paste a
copy.

- Semantic vocabulary → link [`CANON.md`](./CANON.md).
- Token scope / color model → link [`canon/tsc.md`](./canon/tsc.md) and `THEMING.md §25`.
- A second copy is a future drift. This is literal: "7 families" survived in
  three docs for weeks after the canon moved to 8, because each doc had
  re-transcribed the list instead of linking it.

The doctrine fixes the *doctrine*; the code fixes the *numbers*. When a value
lives in code (per-family holds, channel signatures, full verb lists), **link
the `file:symbol`**, don't snapshot it into prose.

## 2. Every doc belongs to one stratum

Decide the stratum before you write; it decides where the file goes and how
timeless it must read.

| Stratum | Kind of doc | Lives in |
| --- | --- | --- |
| **E0 — orientation** | entry point, glossary | `docs/README.md`, `docs/glossary.md` |
| **E1 — architecture** | how the layers fit | `src/uix/active_architecture.md`, per-layer `README.md` (in-place) |
| **E2 — canon** | fixed vocabulary / contracts | `docs/CANON.md`, `eidos/TSC.md` |
| **E3 — decisions / RFC** | why a thing is built this way | `docs/decisions.md` + the RFC / design files |
| **E4 — guides** | how to do a thing | `soma/COMPONENT_GUIDE.md`, `eidos/THEMING_GUIDE.md` |
| **E5 — module reference** | per-artifact docs | `src/arts/{name}/README.md` (in-place) |
| **process** | hand-offs, snapshots, audits | `docs/process/` — ephemeral, never a source of truth |

Layer and module reference stay **in-place** next to the code. Cross-cutting
orientation, canon, decisions and process live under `docs/`.

## 3. Reference docs are timeless

E0–E5 docs must read as if written today, forever.

- **No session hand-offs inside a reference doc.** "Handoff 2026-05-14",
  "Correcciones del engine (2026-06-01)", "Estado actual" blocks belong in
  `docs/process/`, not at the top of a README. Extract them.
- **No fragile numbers or dates in prose.** "66 components", "as of 2026-05-15"
  rot. Convert relative dates to absolute, and prefer pointing at the live
  source over stamping a count.
- **Don't hardcode catalogs.** A list of "implemented components" drifts the day
  the next one ships. Point at the directory tree / the morfos / the registry
  instead.

## 4. One source per concern

If two docs would say the same thing, one **owns** it and the other **links** it.

- Don't duplicate content across docs (the transcription chain, the layer split,
  "what soma is not" lived in 4+ places). Pick the canonical home; everywhere
  else links it.
- Two docs about the same subject must have **distinct roles**, stated in their
  headers. Examples that shipped: `soma/README` (onboarding) vs
  `SOMA_ARCHITECTURE` (deep reference); `COMPONENT_GUIDE` (build steps) vs
  `COMPONENT_COMPLETION_CHECKLIST` (machine-audited acceptance).
- Never write a doc whose only content is re-exporting/redirecting another —
  merge it, or make it a one-line pointer with a clear reason.

## 5. Frontmatter

Canon, index and reference docs open with YAML frontmatter:

```yaml
---
title: <Doc title>
type: canon | index | guide | reference | notes
audience: human + agent
authority: <one line: what makes this authoritative or navigational>
status: current
# optional:
source: <where the content was extracted from>
related: { ... }
---
```

Match the shape of [`CANON.md`](./CANON.md) / [`decisions.md`](./decisions.md).

## 6. Editing rules

- **Sections cited by number are load-bearing.** If a doc's `§N` is referenced
  elsewhere in the corpus or in code comments, **do not renumber it**. To split
  or shrink such a doc, use the **stub pattern**: leave a numbered pointer-stub
  in the slot and move the content out (see THEMING → `TSC.md` / `THEMING_GUIDE.md`
  / `THEMING_NOTES.md`). Renumbering means sweeping every citation in the same
  pass — only do that deliberately.
- **Fix links when you move content, and verify they resolve.** A wrong relative
  path is silent (`soma/layers/GESTURES.md` vs the real `layers/gesture/GESTURES.md`).
- **Surgical.** Touch only what the task needs. Don't "improve" adjacent docs in
  the same edit.

## 7. Language

- Target language is **English** (the migration is gradual; some layer docs are
  still Spanish). When editing an existing doc, match its language — don't mix
  two languages inside one doc.
- **Code comments are always English** (project-wide rule), including comments
  inside fenced code blocks in docs.

## 8. Naming

- New decision/RFC/design docs: `rfc-{topic}.md` / `design-{subsystem}.md`
  (kebab). The legacy `*_ENGINE_RFC.md` / `DESIGN_*.md` names are kept only
  because they are cited as provenance across the code; don't add more in the
  old shape.
- Markdown links, relative paths.

## Before you commit a doc

- [ ] Stratum chosen; file in the right place (in-place vs `docs/`).
- [ ] No canonical value copied — linked instead.
- [ ] No hand-off / dated-status / hardcoded catalog in a reference doc.
- [ ] Frontmatter present (for canon/index/reference).
- [ ] No `§N` renumbered that something cites; links verified to resolve.
- [ ] New doc wired into [`docs/README.md`](./README.md) if it's a top-level entry.