Maintain the documentation

The documentation describes this checkout's behaviour. When implementation and prose differ, inspect schema, entry points and tests, correct the docs and record unimplemented work in TODO.md. Avoid presenting historical project-plan requirements as features. Version examples are illustrative; running versions come from each binary's buildinfo, not a number copied into middleware.

Choose a home

Keep the root README as a bold product presentation with migration/install calls to action and selected screenshots. Index and explain every screenshot in screenshots/README.md. Keep component README files as technical entry points; leave source-asset instructions beside embedded themes when that makes maintaining the assets clearer. Link to canonical docs rather than copying large tables in several places. Do not relocate AGENTS.md, licenses, package manifests or deployment YAML as prose.

Every directory has a detailed index

Every directory under docs and contributing, including both roots, must have README.md. Its immediate-child table links every file (including itself) and every direct subdirectory, with a useful description of scope/audience. A subdirectory link should open its own README. Grandchildren belong in the child's index, not as a substitute for a missing direct-child entry. Explain a suggested reading order and how the directory connects to its parent where useful.

When adding/moving/deleting a file or folder, update its parent index in the same change. Indexes are curated prose; a file listing without descriptions does not explain when a reader should use it.

Write complete procedures

State audience, tools, current working directory, required accounts/permissions, input files, placeholders and commands' effects. Use one coherent example site/ namespace through a procedure. Explain what success looks like, how to check it and what to do on failure. Spell out acronyms or link glossary. Do not assume a standard-named storage class supports RWX, a TLS block issues a certificate, a local build contains the editor, or a health ping proves site health.

Separate save/preview/publish and clarify whole-site effects, confidential data, retained public copies and draft recovery. Explain destructive command scope where it occurs. Keep provider-specific steps honestly provider-specific instead of inventing universally applicable backup, token or certificate commands.

Use relative Markdown links to local files and explicit /README.md for folder indexes. Use heading anchors where they help. Keep source links accurate after moves and avoid links to optional gitignored checkouts. Example API URLs and filesystem trees belong in code spans/fences so validators do not treat them as repository links. Historical examples remain labelled historical.

Validate a documentation change

From repository root with Python 3.9+:

python3 scripts/check-docs.py
git diff --check

The checker reads docs, contributing, screenshot Markdown and tracked entry points. It verifies local links and heading fragments, checks balanced fences, and requires every direct child in docs/contributing to appear in its parent README index table. It does not access external URLs, execute shell examples or prove factual correctness. Review source-backed defaults and procedure ordering manually. Use build/test for application changes or experiments that need runtime validation. Keep documentation-only work separate from deployment.

On relocation, search tracked text for old paths and update inbound links. Link contributor material through the separate contributing index. Keep customer documentation focused on usable tasks, settings and safe operating guidance; move feature wish lists and unfinished work to TODO.md. Re-run checks after the final edit, not just before moving files.