# Documentation Layers

Three layers carry the project's knowledge. Each has a different audience, style, and file set.

---

## Layer 1: Sphinx Guides

**Audience:** Human developers, verb authors, game designers.
**Style:** Explanatory prose with worked examples. "Why it works" alongside "what to do."
**Location:** `docs/source/guide/`

| File | Topic |
|------|-------|
| `01_introduction.md` | Project overview, what MOO is |
| `02_architecture.md` | System architecture, process model |
| `03_runtime.md` | Celery tasks, request lifecycle |
| `04_objects.md` | Object model, inheritance, classes |
| `05_caching.md` | Property and verb caching |
| `06_permissions.md` | Permission model, ownership, access control |
| `07_properties.md` | Property types, inheritance, `inherit_owner` |
| `08_verbs.md` | Verb model, argument specifiers, permissions |
| `09_sandbox_security.md` | RestrictedPython environment, allowed builtins and modules |
| `10_parser.md` | Lexer/parser internals, verb search order, preposition synonym groups |
| `11_creating_verbs.md` | Shebang syntax, dspec/ispec, execution environment, output mechanisms, property access |
| `12_more_verbs.md` | Calling verbs, time-aware continuation, return values, SDK utilities, best practices |
| `13_tasks.md` | Background task model |
| `14_builtins.md` | Built-in object hierarchy (`$root_class`, `$thing`, `$player`, etc.) |
| `15_development.md` | Dev setup, test runner, common commands |
| `16_bootstrapping.md` | Bootstrap process, default world |
| `17_connection_control.md` | SSH connection handling, session settings |

**Format split:**

| Content | Format |
|---------|--------|
| Guide pages (`docs/source/guide/*.md`) | MyST Markdown |
| API reference (auto-generated by autodoc) | RST docstrings in `.py` source files |

Python docstrings must use RST format: `:param x:`, `:type x:`, `:return:`, `:rtype:`, `:raises ExcType:`. Napoleon is **not** installed — Google/NumPy-style docstrings will silently render wrong. When syncing content that touches Python modules, check that any new docstrings follow RST syntax, not Google style.

**What Sphinx does NOT cover:**
- AI agent workflow instructions
- Step-by-step audit passes or skill procedures
- Internal implementation details not relevant to verb authors

---

## Layer 2: AI Skill Files

**Audience:** Claude Code (AI agent) when a skill is active.
**Style:** Terse, task-oriented, decision rules. Phases and checklists.
**Location:** `extras/skills/*/SKILL.md` plus `references/` subdirectories.

| Skill | SKILL.md focus | Key references |
|-------|----------------|----------------|
| `verb-author` | Writing, editing, testing verbs | `dispatch.md`, `parser-api.md`, `sdk.md`, `testing.md` |
| `game-designer` | Building multi-room environments via SSH wizard commands | `object-model.md`, `moo-commands.md`, `room-description-principles.md`, `verb-patterns.md`, `build-automation.md` |
| `sandbox-auditor` | Security auditing the RestrictedPython sandbox | `audit-history.md`, `attack-categories.md`, `test-patterns.md`, `known-gaps.md` |
| `tech-librarian` | Syncing the three documentation layers | `layers.md` (this file), `translation.md` |

**Skill quality checklist** — when auditing or authoring a skill:

| Check | Rule |
|-------|------|
| Description | Must state WHAT it does AND WHEN to use it. Agents decide whether to activate based on the description alone — vague descriptions cause misses. |
| SKILL.md length | Stay under 500 lines. Move detail to `references/`. |
| `allowed-tools` | Optional frontmatter field (space-delimited) to pre-approve tools for the skill. Example: `allowed-tools: Bash Read Write` |
| Validation | `skills-ref validate ./skill-name/` checks frontmatter and naming conventions. |

**What skills do NOT cover:**
- Human-readable explanations of "why"
- Narrative introductions for newcomers
- Detailed conceptual background (point to Sphinx instead)

---

## Layer 3: AGENTS.md Files

**Audience:** Claude Code (AI agent) at the start of every conversation.
**Style:** Reference conventions, project rules, quick lookup tables.
**Location:** `AGENTS.md`, `moo/AGENTS.md`, `moo/bootstrap/AGENTS.md`

| File | Scope |
|------|-------|
| `AGENTS.md` | Project-wide: architecture, stack, coding conventions, key entrypoints, testing workflow, security rules |
| `moo/AGENTS.md` | Core module conventions: model patterns, settings, test fixtures |
| `moo/bootstrap/AGENTS.md` | Bootstrap module: default verb patterns, verb naming, test locations |

**AGENTS.md completeness standard** — six core areas from community analysis of 2,500+ repos:

1. **Executable commands** — build, test, deploy commands with full flags (e.g. `uv run pytest -x`, not just "run pytest")
2. **Testing approach** — where tests live, fixtures used, how to run a single test
3. **Project structure** — directory organization, key entry points
4. **Code style** — concrete examples, not just descriptions; include version specifics
5. **Git workflow** — branching, commit message format, PR expectations
6. **Clear boundaries** — what the agent must never touch (secrets, vendor dirs, production configs)

**Limits and quality rules:**
- Maximum 32 KiB (default limit enforced by most AI coding tools)
- Specificity beats vagueness: "uv run pytest -x moo/core/tests/" beats "run the tests"
- Treat as living documentation: update when commands or conventions change
- Avoid duplicating content that is already in skills — link instead

**What AGENTS.md does NOT cover:**
- Step-by-step procedures (those belong in skills)
- Beginner explanations (those belong in Sphinx)
- Content that is already derivable from reading the code

---

## How to Read Each Layer's Current State

| Goal | How |
|------|-----|
| What does Sphinx say about output? | `Read docs/source/guide/11_creating_verbs.md`, search for "print" / "tell" |
| What does verb-author skill say about the parser API? | `Read extras/skills/verb-author/references/parser-api.md` |
| What does AGENTS.md say about test patterns? | `Read moo/AGENTS.md` |
| What got added to the SDK recently? | `git log --oneline -- moo/sdk.py` |
| What verbs were added recently? | `git log --oneline -- moo/bootstrap/default_verbs/` |
