svelte-kit-vice/docs/authoring.md

title	type	audience	authority	status
Documentation Authoring Rules	guide	human + agent	canonical — how docs in this corpus are written and edited	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 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.
• Token scope / color model → link 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	docs/architecture/ (the book chapters) + in-place stubs
E2 — canon	fixed vocabulary / contracts	docs/CANON.md, docs/canon/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	guides/component-guide.md, theming/guide.md
E5 — module reference	per-artifact docs	src/arts/{name}/README.md, src/packs/{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: architecture/soma (onboarding) vs architecture/soma-architecture (deep reference); guides/component-guide (build steps) vs guides/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:

---
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 / 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 if it's a top-level entry.