docs(ai): define documentation truth hierarchy

CLAUDE.md

@@ -38,6 +38,23 @@ Profile resolution priority:
 
 All env values written into settings must be strings.
 
+## Documentation Truth
+
+Use the narrowest authoritative source:
+
+1. Source, tests, package scripts, and workflows define implemented behavior.
+2. `CLAUDE.md` and `CONTRIBUTING.md` define repository workflow.
+3. `docs/README.md` maps maintainer documentation and its owners.
+4. The separate `kaitranntt/ccs-docs` repository and published site own user
+   guides and CLI reference.
+5. Generated artifacts and live runtime checks define what shipped or is
+   currently running.
+
+Do not copy inventories, line counts, locale lists, target lists, or command
+details when a stable source link is enough. Update the owning documentation
+when behavior, commands, setup, architecture, security posture, or maintainer
+workflow changes. Remove stale claims instead of preserving them as TODOs.
+
 ## User-Facing Change Checklist
 
 - Update the matching `--help` handler when CLI behavior changes.
@@ -46,7 +63,10 @@ All env values written into settings must be strings.
 - Use neutral broad examples such as `ccs`, `ccs codex`, `ccs glm`, or
   `ccs <provider>` unless the page is provider-specific.
 - If CLI commands, config, providers, install steps, or user workflows change,
-  update the public CCS docs in `/Users/kaitran/CloudPersonal/ccs/docs`.
+  update the separate public CCS docs repository. Maintainers using the
+  standard CloudPersonal checkout may have it at
+  `/Users/kaitran/CloudPersonal/ccs/docs`; fork contributors can use their own
+  checkout and coordinate the matching docs change in the PR.
 
 Help locations:
 

CONTRIBUTING.md

@@ -20,7 +20,7 @@ If you are new to the project, start with a docs fix, a focused bug fix, or an i
 | CLI runtime | `src/`, `lib/`, `config/`, `scripts/` | Add or update tests in `tests/` |
 | Dashboard UI | `ui/src/` | Run `cd ui && bun run validate` |
 | Web server and config APIs | `src/web-server/`, `src/api/`, `src/config/` | Add unit or integration coverage |
-| Documentation | `https://docs.ccs.kaitran.ca`, `README.md`, `docs/`, `CONTRIBUTING.md` | Keep user-facing docs in sync |
+| Documentation | `https://docs.ccs.kaitran.ca`, `README.md`, [`docs/`](./docs/README.md), `CONTRIBUTING.md` | Update the owning source, not every page |
 | Static assets | `assets/` | Verify screenshots and references still match |
 
 Useful directories:
@@ -92,6 +92,21 @@ If `CI` or `Push CI` stays queued for a long time, it is a maintainer infrastruc
 
 `CONTRIBUTING.md` is the human entry point. For AI agents working in this repo, the authoritative automation and workflow rules live in [CLAUDE.md](./CLAUDE.md).
 
+## Documentation Ownership
+
+Documentation follows this truth order:
+
+1. Source, tests, package scripts, and workflows define implemented behavior.
+2. [CLAUDE.md](./CLAUDE.md) and this guide define repository workflow.
+3. [docs/README.md](./docs/README.md) maps maintainer documentation.
+4. [docs.ccs.kaitran.ca](https://docs.ccs.kaitran.ca) owns detailed user guides
+   and CLI reference.
+
+Update documentation when a change affects behavior, commands, setup,
+architecture, security posture, or contributor workflow. Prefer links to
+authoritative source files over copied trees, counts, and option lists that
+drift quickly.
+
 ## AI Review Lane
 
 CCS PR review no longer depends on `anthropics/claude-code-action`. The repository review lane is self-hosted PR-Agent:

docs/README.md

@@ -0,0 +1,67 @@
+# CCS Maintainer Documentation
+
+This directory explains how the CLI repository is organized and maintained.
+User-facing guides and command reference live at
+[docs.ccs.kaitran.ca](https://docs.ccs.kaitran.ca).
+
+## Truth Hierarchy
+
+Use the narrowest authoritative source:
+
+1. Source, tests, package scripts, and workflows define implemented behavior.
+2. [`CLAUDE.md`](../CLAUDE.md) and
+   [`CONTRIBUTING.md`](../CONTRIBUTING.md) define repository workflow.
+3. The documents below explain architecture, rationale, and maintainer
+   decisions.
+4. Build artifacts, releases, and runtime checks define shipped or observed
+   state.
+
+When sources disagree, verify the implementation first and update or remove the
+stale prose. Avoid copying volatile counts, recursive trees, and exhaustive
+option lists when a source link can remain accurate.
+
+## Start Here
+
+| Need | Owner |
+| --- | --- |
+| Repository domains and source entry points | [Codebase summary](./codebase-summary.md) |
+| Coding, testing, error, and size conventions | [Code standards](./code-standards.md) |
+| System boundaries and data flow | [System architecture](./system-architecture/index.md) |
+| Current maintenance direction | [Project roadmap](./project-roadmap.md) |
+| Release mechanics | [Release process](./release-process.md) |
+| Dashboard localization | [Dashboard i18n](./i18n-dashboard.md) |
+| Test layout and commands | [Test suite](../tests/README.md) |
+| Dashboard development | [UI guide](../ui/README.md) |
+
+Feature-specific maintainer notes remain in this directory. Discover them by
+filename, then verify referenced behavior against the linked source.
+
+## Update Triggers
+
+Update the owning documentation in the same change when any of these move:
+
+- CLI or dashboard behavior, commands, flags, or configuration
+- installation, deployment, release, or contributor workflow
+- architecture, data flow, persistence, security, or public contracts
+- source ownership or the stable entry point named by a guide
+
+Pure refactors need documentation changes only when they invalidate a
+maintainer decision or navigation link. Public behavior changes also require a
+matching update in the separate `kaitranntt/ccs-docs` repository on the same
+target branch. Maintainers using the standard CloudPersonal checkout may have
+that repository at `/Users/kaitran/CloudPersonal/ccs/docs`; fork contributors
+can use their own checkout and coordinate the matching docs change in the PR.
+
+## Validation
+
+Before review:
+
+```bash
+bash tests/docs/quickstart-parity.sh
+git diff --check
+```
+
+The repository-owned docs test currently checks the canonical quickstart
+snippet only. For other changed Markdown, verify each relative link and
+referenced path directly, then run the focused validation command for any code
+or workflow the document describes.