diff --git a/CLAUDE.md b/CLAUDE.md index 9d900563..8d09546e 100644 --- a/CLAUDE.md +++ b/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 ` 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: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index df420de4..1eb654e0 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..3a500ad0 --- /dev/null +++ b/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.