Documentation maintenance

AGENTS.md delegates the authoring format to this document. Repository policy remains in AGENTS and the constitution; this contract explains how to maintain the documentation within that policy.

Write for a reader opening one page

Start with the purpose and result. Define domain terms before using them, give a worked example where behaviour is difficult, and keep limitations beside the claims they qualify. Use plain sentences, descriptive headings, and tables for comparisons. A short summary should help someone decide whether they have opened the right page.

The same page serves human developers, AI development and end users. The reading paths provide different entry points; audience labels are not permissions. A future retrieval may deliver one section without its neighbours, so give examples their units, identity, date basis and assumptions locally.

Schema

Every document starts with this shape:

---
title: Example title
type: concept
status: active
created: 2026-09-14
updated: 2026-09-14
---

# Example title

> [!tip] TL;DR
> A concise explanation of the subject and what the reader can do with it.

There is no summary or audience property. The listing extracts its summary from the TL;DR. Draft and archived are recognised editorial states for local material, not exceptions to the active-only commit rule. Every published page ends with Related links and, when it asserts behaviour, Evidence.

Evidence and uncertainty

Name the source path and method behind a technical claim. Prefer method names to line numbers that move easily. Record a revision when it helps reproduce a check, but do not leave an old revision claim on newly checked behaviour. Distinguish code inspection from local execution, and do not present either as a check of production data.

Commercial definitions come from the data owner; code only establishes how they are implemented. Preserve that distinction. For an unresolved meaning, record the question in coverage and obtain an answer. Do not invent a definition, a business owner or an environment statistic. An upstream retention limit or a proxy's unknown window is a boundary of that service; state the boundary without claiming CCC configures it.

Navigation-only indexes need no Evidence. If an index or the coverage ledger makes its own access or behaviour claim, cite that claim just as a content page would.

Links and supported rendering

The canonical is the lowercase filename without .md, globally unique under docs/. A folder move preserves it; a rename changes the /docs/view/<canonical> URL. Update inbound links and screen claims when renaming a page or an addressed heading.

Author document links as relative Markdown paths, with a heading fragment when useful. Link to a folder's actual index document rather than its directory. The app adapter resolves the exact file and rewrites document links before rendering. Use root-relative URLs for screens, and HTTPS links for external pages. Code references can be plain repository paths in backticks; the app does not serve source files as documentation routes.

In particular, Obsidian comments are visible rather than private. No .base or canvas files belong in this collection. The obsidian-markdown skill has the renderer-specific feature notes.

Keep definitions maintainable

• Put the full explanation in one concept or object page, then link to it from guides and screens. A short local summary is useful; a second independent definition is not.
• Author field descriptions in config/dictionary/fields/ or the classification dictionary. Regenerate the readable field reference after edits. Prose may explain a formula or join, but should not duplicate the entire column inventory.
• A source page describes inputs and refresh behaviour; an object page describes what CCC builds and publishes. A guide gives a task, and a runbook gives diagnosis, repair and verification.
• Use synthetic examples, never customer records, credentials or production query output.
• Keep inventories that can be derived out of hand-written prose. Generated counts are labelled as generated; current environment counts belong on their screens.
• Record planned scope in coverage or the feature artifacts, not as empty sections or unfinished task checkboxes in published pages. Future MCP proposals must be labelled as proposals.

When to update

AGENTS requires a documentation update in the same change when published field meaning, rule behaviour, source windows, identity logic, screen workflows or recovery procedures change. Correct all summaries that repeat the changed fact, including README and governance files where applicable. A constitution edit follows its amendment process.

A screen gets Help from exactly one active document's pages claim. A shared guide may claim several related screens. Record every intentionally unclaimed screen and its reason in coverage.

Review before committing

Run from the repository root:

python3 .agents/skills/checkdocs/scripts/checkdocs.py .
git diff --check

The scanner checks links, screen references, collisions, duplicate claims, coverage, orphans, frontmatter, Evidence, writing conventions and editorial dates. Its exit status proves those checks only; it does not prove factual accuracy, useful coverage or successful rendering.

Read the explanations against their code evidence, validate arithmetic and synthetic examples, and exercise changed renderer or generator behaviour in the PHP container. Reopen changed Help pages when the app is available. Check generated output against its source and verify that no personal _*.md working files are staged.

Related

• Coverage
• Verification
• Documentation index
• Field meaning

Evidence

Authoring policy is delegated by AGENTS.md, Documentation changes. Supported document parsing, canonical links and Help selection are implemented in app/models/docs.php and the maintained app/models/markdown.php fork. The mechanical checks are in .agents/skills/checkdocs/scripts/checkdocs.py. Code-checked during this review; the upstream Obsidian skill's supported subset is recorded in .agents/skills/obsidian-markdown/SKILL.md.