svelte-kit-vice/docs/authoring.md

---
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 [`eidos/TSC.md`](../src/uix/eidos/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.
-												docs(corpus): add docs/authoring.md — the rules for writing docs here

So a session or agent that creates or edits documentation does it consistently
with the corpus, not against it. Codifies what the migration learned, each rule
tied to the failure it fixes:

1. Link the canon, never copy it (the anti-drift law — "7 families" survived in
   three docs because they re-transcribed instead of linking).
2. Every doc belongs to one stratum (E0-E5 / process); where each kind lives.
3. Reference docs are timeless — hand-offs, dated status and hardcoded catalogs
   go to process/ or become pointers.
4. One source per concern; two docs on a subject get distinct stated roles.
5. Frontmatter convention.
6. Sections cited by §N are load-bearing — stub-split, never silently renumber;
   verify moved links resolve.
7. English target; code comments always English.
8. Naming (rfc-* / design-*), markdown relative links, pre-commit checklist.

Wired into docs/README.md ("I want to… write a doc" + a note after the strata).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

											
										
										
											4 months ago
+								---
 								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 [`eidos/TSC.md`](../src/uix/eidos/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.