DOCS_AUTHORING_GUIDE.gd

# Docs Authoring Guide

Canonical authoring rules for all repo documentation. The docs system is optimized for coding agents, not humans: prioritize retrieval quality, unambiguous ownership, and token efficiency. It's the single source of truth for doc structure, naming, status taxonomy, cross-references, and anti-duplication. Owner: `AGENTS.md` routes here; this doc owns the rules.

Key Files: N/A

Status: IMPLEMENTED

## Audience and intent

- Primary audience: autonomous coding agents (Claude Code, Codex, review agents, loop agents)
- Secondary audience: the human maintainer (Jamon) skimming the same docs
- Goal: an agent landing cold on a task can grep, traverse, and act safely without re-reading the whole repo
- "Avoid" = generally don't do this, but important 
- "Never" = strictly never do this

## Hard rules (read first)

- One concept = one canonical doc. Other docs link, never redefine; avoid duplication which risks drift.
- Document actual implemented behavior. Mark planned or partial work with the `Status:` line and in-doc notation.
- Bullet lists beat prose. Short declarative sentences beat paragraphs.
- Never duplicate `CODING_CONVENTIONS.md`, `GAME_ARCHITECTURE.md`, or any system doc's content elsewhere — link to it.
- Do not paste source code. Important public APIs should usually show a tiny usage example.
- Update the owning doc in the same task that changes behavior.
- Avoid migration content (see `AGENTS.md` hard rules).
- Two-way references: code files in ./Scripts should reference the system doc(s) that describe them; system docs should reference code files
- Don't record defaults or values in docs; point to their canonical locations (usually in code or scene files)

## Required system-doc header

Every doc in `Docs/Systems/` and most docs in `Docs/Workflow/` must open with this exact shape. Agents grep only the first ~3 lines to decide whether to load a doc — keep them dense and information-rich.

```
# TITLE

Short summary paragraph. Max 150–250 words. No line breaks. Must state: purpose, ownership, major dependencies, critical constraints.

Key Files: one-liner, comma-separated list of all scripts that own this document, such as: "AutoPilot.gd, AutoPilotLand.gd, AutoPilotNav.gd, ..." etc. Do not list more general scripts such as Me.gd or Game.gd unless specifically describing their function in this doc.

Status: IMPLEMENTED | PARTIAL | PLANNED | DEPRECATED
```

Notes:

- Line 1 is the H1 title. Line 3 is the summary paragraph as a single physical line — no soft wraps. Line 5 is the list of associated scripts. Line 7 is the `Status:` line.
- Title casing: `# System Name` (e.g. `# Missile & Rocket System`). No trailing punctuation.
- Summary must be self-contained — an agent that reads only the first 7 lines should know whether to load the file.
- Workflow and cross-cutting docs (e.g. `CODING_CONVENTIONS.md`, `AGENT_WORKFLOW.md`) may use a thinner header but still need a one-paragraph summary and a `Status:` line.

### Status taxonomy

- `IMPLEMENTED` — behavior described matches the running code.
- `PARTIAL` — described behavior is partially in code; doc must list what is and isn't live in a `## Status` section.
- `PLANNED` — design only, no production code yet. Flag every section that is speculative.
- `DEPRECATED` — kept for history; link to the replacement doc on line 4 or in the summary. Also note a recommendation on how to clean this up in the future.

If a doc mixes statuses (rare), use the highest-uncertainty level for the header and split per-section status inside the body.

## Canonical structure

System docs should use these sections in order. If a section doesn't apply, simply say "N/A" under the heading and move forward. In some more ambiguous cases, you may say "N/A. Reason: ..." and explain why, succinctly. For example, "# Authority & Multiplayer\n\nN/A. This system has no multiplayer concerns.\n"

1. Header (title + summary + key files + Status, as above)
2. `## Key Files` — bullet list of the source files that own this system. One line each: path + one-line role. Should match line 5 in the header.
3. `## Architecture Overview` — short prose. Show ownership and data flow (usually as an outline), not full call graphs.
4. `## Execution Order` — for any system with frame-ordered or lifecycle-ordered logic, document the sequence explicitly.
5. `## Invariants` — bullet list of properties that must always hold. (See "Invariants" below.)
6. `## Authority & Multiplayer` — who runs what (server, client, all peers), RPC names, what is synchronized vs derived.
7. `## Persistence` — what is saved/loaded, where, and any versioning quirks. Omit if nothing persists.
8. `## Performance` — hot paths, frame-budget concerns, caching rules. Omit if not performance-sensitive. Don't repeat stuff in PERFORMANCE docs, reference other docs instead
9. `## Failure Modes` — known edge cases, error handling, recovery behavior.
10. `## Public API` — short. Method signatures + 1–3 line usage examples only.
11. `## Related Docs` — see "Cross-references" below.
12. `## Future Work` / `## Open Questions` — explicitly speculative; never blends with implemented sections.

Workflow docs (`Docs/Workflow/*`) follow a looser structure but must still open with the header and end with `## Related Docs`.

## Writing standards

- Voice: declarative, second-person sparing. e.g. "The radar emits ping events." not "You can think of the radar as emitting events."
- Write as if instructing new dev, not following existing dev journey. e.g. "Use > to reference section headers." not "Use > instead of § to reference section headers." A new reader would not understand why you'd even mention § at all; by the point they read the code base, the conversion will be done
- Write for devs new to project, not explaining history. e.g. "Use > to reference section headers" not "Use > instead of § to reference section headers"
- One claim per bullet. If you need two, split
- Prefer no trailing punctuation in bullet lists
- No filler. Drop "It's worth noting that", "In general", "Basically"
- Code references use backticks with the path: `Missile.gd`
- Do not provide line refs in durable docs; they change frequently. Exceptions: specs & worksheets
- Don't use markdown links, can easily find docs by name
- Use canonical terminology, no synonyms
- Avoid section dividers (`---`)
- Prefer bullet lists over tables. Tabular data often lives in code instead such as WeaponDataTable.gd; reference that if possible instead.
- Diagrams: Avoid diagrams; prefer outlines. Use diagrams only when it is too ambiguous when written any other way.
- Numbers, units, and tunable constants: state the unit and where the constant lives in code (`Scripts/Foo.gd`).
- Do not write "see code for details" without a path. Always reference the filename.
- Files should omit path when obvious for token preservation: for example, most *.gd files live in `./Scripts`, so simply state the filename `Foo.gd`. Exceptions: when the file is located somewhere other than `./Scripts`. E.g. `addons/jammin_lobby/Lobby.gd`.

## Retrieval optimization

Agents discover docs by:

1. Reading `AGENTS.md` (the router).
2. Grepping the first 7 lines of candidate docs.
3. Reading the full doc only if those lines look relevant.

Implications:

- The title, the summary paragraph, and the `Status:` line must contain the key nouns an agent would grep for. Example: a missile doc summary should contain "missile", "guidance", "warhead", "Hellfire", "HYDRA", "projectile" — not just "munition".
- Put domain synonyms in the summary if the doc owns them (e.g. `radar / detection / contact tracking`).
- The `Key Files` section is the second retrieval anchor — agents grep for filenames here when working in code.
- Do not bury the purpose under TOCs or preamble. The first paragraph after `# Title` is the summary.

## Cross-reference strategy

- Every doc ends with `## Related Docs`, a flat bullet list of references to other docs an agent might need next. No prose.
- Use repo-relative paths in references only if not obvious: `addons/jammin_lobby/README.md`. Otherwise, use only the filename: `MULTIPLAYER.md` is obviously in `Docs/Systems/MULTIPLAYER.md`, and referenced in `AGENTS.md` anyway so it'll be obvious where to find it.
- One reference = one reason. If two docs cover overlapping concerns, link both with a one-line "why":
  - `MUNITION_SYSTEM.md` — impact pipeline shared by all projectiles
  - `DAMAGE_SYSTEM.md` — what happens after impact
- Inline references inside paragraphs are fine for canonical handoffs ("authority rules live in `MULTIPLAYER.md`").
- Do not link the same doc twice from the same section. If you find yourself wanting to, the section itself probably belongs in the linked doc.

## Anti-duplication rules

- Before writing a new concept, grep for it. If another doc already owns it, link instead, or consider moving it into the current doc and linking from the other.
- If two docs describe the same concept differently, pick one as canonical, replace the other with a link, and note the canonical choice in a one-line comment at the top of the linked-from doc if helpful.
- It's more important that the docs are _right_ than that updating is trivial; undertake extensive updates as needed, but in the case of extensive updates, always ask for a second opinion from another agent (Codex or Claude) to validate the need first, and reference THIS doc in your prompt so it knows how to determine this, along with provided context.
- "Examples in context" are not duplication, as long as they don't redefine semantics. Example: HMD_SYSTEM can mention "weapon slots" without redefining them, but must not re-document WeaponSlot fields.
- Glossary terms (rare): if a term needs definition for many docs, define it in `Docs/Systems/GAME_ARCHITECTURE.md` and link there.
- When in doubt: shorter doc + a link beats a longer doc that copies content.

## Invariants documentation

Invariants are properties of the system that must always be true at runtime. Document them explicitly so agents don't accidentally break them. Format:

- One bullet per invariant
- State the property, not the mechanism. "Only the authority peer mutates `unit_node.hp`." beats "We call `set_hp` from the server."
- Where useful, append `(enforced by: <file or check>)` so an agent can audit

Examples of invariants worth documenting:

- Authority: who can mutate this state
- Ordering: which init step must precede which
- Threading / frame timing: what runs in `_process`, `_physics_process`, or deferred
- Determinism: what must be reproducible across peers given the same inputs
- Lifetime: when an object is valid; when it has been freed

If an invariant is enforced by an `assert`, mention the file and the assertion message.

## Authority, multiplayer, and execution order

These three are the most common sources of agent-introduced bugs. Every system that touches them needs an explicit section.

- `## Authority & Multiplayer`: list which peer owns each piece of state, the RPC method names, and what is replicated vs derived
- `## Execution Order`: list the ordered steps for any lifecycle, frame, or pipeline behavior. Use a numbered list, not prose
- If a system has no multiplayer concern at all, write `## Authority & Multiplayer` with the single bullet `Local only — no networked state.` so the absence is documented

## Persistence and migration

- `## Persistence` lists what is saved, where (file path or resource type), and when (autosave, mission end, etc.).
- This project explicitly avoids migration code at this point in development (see `AGENTS.md`). If a save format changes, the doc should simply describe the current state of the system rather than describe a migration or narrative.

## Terminology consistency

Use the canonical term everywhere. When introducing a new term, pick one and stick with it across all docs.

- `helicopter` (player vehicle), not "chopper" or "heli" in prose. Code identifiers may shorten (`Heli3D`).
- `station` and `seat` — these refer to the pilot/gunner/copilot slot system; do not invent new words.
- `munition` — the unified term for projectiles + missiles + rockets at impact time. Use it in cross-cutting contexts (`MUNITION_SYSTEM.md`). For type-specific behavior use `missile`, `rocket`, `projectile`, `bullet`.
- `unit` — any damageable entity. Owned by `DAMAGE_SYSTEM.md`.
- `contact` — a radar-detected entity. Owned by `RADAR_SCAN_SYSTEM.md`.
- `authority` — the peer responsible for mutating a piece of state. Owned by `MULTIPLAYER.md`.
- `mission` vs `campaign` vs `career` — three distinct scopes; see `MISSION_SYSTEM.md`, `CAMPAIGNS.md`, `ACCOUNTS_PLATOONS_PILOTS.md`.
- `autopilot` — covers both NPC flight and player-assist; owned by `AUTOPILOT_SYSTEM.md`.

When a doc owns a term, the owning doc is responsible for its definition. Other docs link.

## Token efficiency expectations

- System docs: target 100–500 lines. If you exceed 500, consider splitting (see below). Exception: when the lines are short and mostly lists, you can exceed 500
- Summary paragraph: 150–250 words.
- No multi-paragraph prose where bullets work.
- Strip example code that doesn't teach behavior. A single canonical example beats five variants.
- Remove stale TODOs, dead "Future Work" entries, and superseded notes when you touch a doc.
- Avoid restating `AGENTS.md` rules in individual docs.

## When to split a doc

Split when any of:

- The doc exceeds ~500 lines
- Two clearly different audiences (e.g. data modeling vs runtime behavior) share the file
- A subsystem has independent ownership, lifecycle, or multiplayer rules
- Grepping the doc returns the same hit for two unrelated agent tasks consistently

When splitting:

- Keep the original file as the canonical hub if other docs already link to it; move detail into siblings and link. You may rename this file if a more general name would make more sense.
- Update `AGENTS.md` Docs Index.
- Update inbound references across all docs.

## When to merge or delete

- Merge when two docs cover overlapping concerns with no clean ownership split. Keep the doc with more inbound links; redirect the other to a one-line stub link or delete it and fix inbound references.
- Delete a doc only after grep confirms no inbound references remain. Update `AGENTS.md` Docs Index in the same commit.

## File and path conventions

- File names are `UPPER_SNAKE_CASE.md`.
- All system docs live in `Docs/Systems/`.
- Workflow docs live in `Docs/Workflow/`.
- Game-design docs live in `Docs/GameDesign/`.
- Cross-cutting top-level docs live in `Docs/` (`CODING_CONVENTIONS.md`, `TODOS.md`, `PROGRESS.md`, this guide).
- Changelogs live in `Docs/Changelogs/`.
- `AGENTS.md` lives at the repo root and is the only router. Do not create secondary router docs.
- `README.md` is for humans only.

## Editing checklist (use before committing a doc change)

- [ ] Header follows the canonical shape (title + 150–250 word summary + Key Files + Status).
- [ ] First 7 lines are dense and greppable.
- [ ] No unnecessarily duplicated concept from another doc.
- [ ] Canonical terminology used throughout.
- [ ] Invariants section present for systems with shared state.
- [ ] Authority & Multiplayer section present (even if "Local only").
- [ ] Related Docs section present and accurate.
- [ ] `AGENTS.md` Docs Index updated if the file is new, renamed, or has a substantially changed role.
- [ ] No stale TODO or "Future Work" left over.
- [ ] Reflects actually-implemented behavior unless `Status:` says otherwise.

## Related Docs

- `AGENTS.md` — root router. Docs Index lives there.
- `Docs/Conventions/CODING_CONVENTIONS.md` — code-level conventions; analogous in scope to this guide.
- `Docs/Systems/GAME_ARCHITECTURE.md` — canonical architecture overview; owns cross-cutting terminology.
- `Docs/Workflow/AGENT_WORKFLOW.md` — single-task workflow; updates to owning docs happen inside it.
- `Docs/Workflow/AGENT_LOOP.md` — loop workflow; the loop's wrap step expects this guide's structure.
- `Docs/TODOS.md` — destination for large speculative sections that outgrow a system doc.