From c501fcebddf58c038f64e565ecc876b5fab532e8 Mon Sep 17 00:00:00 2001 From: Shai Revivo Date: Wed, 19 Aug 2026 12:51:33 +0300 Subject: [PATCH 1/3] docs(#5598): add CLI-to-documentation cross-reference guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Contributors updating CLI command behavior had no way to discover all documentation locations for a given command group — PR #5596 needed 5 review iterations for this reason. Add docs/contributing/documentation.md mapping the 7 major command groups to their doc touchpoints, plus a general grep-based discovery rule for minor commands. Co-Authored-By: Claude Opus 4.6 Signed-off-by: Shai Revivo --- AGENTS.md | 1 + docs/contributing/documentation.md | 96 ++++++++++++++++++++++++++++++ 2 files changed, 97 insertions(+) create mode 100644 docs/contributing/documentation.md diff --git a/AGENTS.md b/AGENTS.md index 403db843e1..e567072904 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,3 +40,4 @@ Detailed guidance lives in `docs/contributing/` and topic-specific guides under | [Vouch System](docs/contributing/vouch-system.md) | Working with the contributor vouch gate or PR workflows | | [Tier Conventions](docs/contributing/tier-conventions.md) | Using the term "tier" in code or docs — covers the three distinct tier contexts | | [CI Workflows](docs/contributing/ci-workflows.md) | Adding or modifying GitHub Actions workflows under `.github/workflows/`, or adding secrets to `pull_request_target` jobs | +| [Documentation](docs/contributing/documentation.md) | Changing CLI command behavior, adding or removing subcommands, or renaming flags — covers cross-reference of CLI command groups to all documentation touchpoints | diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md new file mode 100644 index 0000000000..7d4a83f3e9 --- /dev/null +++ b/docs/contributing/documentation.md @@ -0,0 +1,96 @@ +--- +title: Documentation Updates +--- + +# Documentation Updates + +When changing CLI command behavior, adding or removing subcommands, or renaming flags, you must update every documentation file that references the affected command. CLI commands are documented across CLI reference pages, user and operator guides, ADRs, and inline Go help text. Missing even one location causes documentation drift that surfaces as review findings on later PRs. + +## General discovery rule + +Before considering a CLI change complete, run: + +```bash +grep -rn '' docs/ +``` + +Review every hit and update references that describe behavior you changed. This catches files not listed in the cross-reference below. + +## ADR annotations + +ADRs are immutable records. When a CLI change supersedes an ADR's decision, **annotate** the ADR (add a status annotation or appendix note per [ADR conventions](adrs.md)) rather than editing the decision text inline. + +## Cross-reference by command group + +Each row lists the documentation touchpoints for a major CLI command group. The **Go source** column is where inline `Short`/`Long` help text lives. + +### `agent` + +| Category | Files | +|----------|-------| +| CLI reference | `docs/cli/agent.md` | +| Guides | `docs/guides/getting-started/operations.md`, `docs/guides/user/bring-your-own-agent.md`, `docs/guides/user/customizing-agents.md`, `docs/guides/user/customizing-with-skills.md`, `docs/guides/dev/cli-internals.md` | +| ADRs | `docs/ADRs/0058-agent-registration.md` | +| Go source | `internal/cli/agent.go` | + +### `admin` + +| Category | Files | +|----------|-------| +| CLI reference | _(no dedicated page)_ | +| Guides | `docs/guides/getting-started/org-mode.md`, `docs/guides/infrastructure/advanced-setup.md`, `docs/guides/infrastructure/mint-administration.md`, `docs/guides/dev/cli-internals.md` | +| ADRs | `docs/ADRs/0044-deprecate-per-org-installation-mode.md`, `docs/ADRs/0060-cross-org-mint-authorization-via-org-variables.md`, `docs/ADRs/0083-repo-level-foreign-allow-list.md` | +| Go source | `internal/cli/admin.go` | + +### `github` + +| Category | Files | +|----------|-------| +| CLI reference | `docs/cli/github.md` | +| Guides | `docs/guides/getting-started/configuring-github.md`, `docs/guides/getting-started/operations.md`, `docs/guides/dev/cli-internals.md`, `docs/guides/dev/e2e-testing.md` | +| ADRs | `docs/ADRs/0057-repos-management.md` | +| Go source | `internal/cli/github.go` | + +### `inference` + +| Category | Files | +|----------|-------| +| CLI reference | `docs/cli/inference.md` | +| Guides | `docs/guides/getting-started/getting-inference.md`, `docs/guides/getting-started/operations.md`, `docs/guides/dev/cli-internals.md` | +| Go source | `internal/cli/inference.go` | + +### `mint` + +| Category | Files | +|----------|-------| +| CLI reference | `docs/cli/mint.md` | +| Guides | `docs/guides/getting-started/operations.md`, `docs/guides/infrastructure/mint-administration.md`, `docs/guides/infrastructure/standalone-mint.md`, `docs/guides/dev/cli-internals.md` | +| ADRs | `docs/ADRs/0059-public-mint-mode-with-wildcard-allowlists.md`, `docs/ADRs/0060-cross-org-mint-authorization-via-org-variables.md`, `docs/ADRs/0073-named-mint-privilege-levels.md`, `docs/ADRs/0077-mint-repos-scope-hardening.md`, `docs/ADRs/0078-simplified-mint-authorization-policy.md`, `docs/ADRs/0082-workflow-host-allow-list.md` | +| Go source | `internal/cli/mint.go`, `internal/cli/mint_setup.go`, `internal/cli/mint_delete.go` | + +### `repos` + +| Category | Files | +|----------|-------| +| CLI reference | `docs/cli/repos.md` | +| Guides | `docs/guides/getting-started/operations.md`, `docs/guides/getting-started/repo-management.md`, `docs/guides/dev/cli-internals.md` | +| ADRs | `docs/ADRs/0057-repos-management.md`, `docs/ADRs/0074-repos-command-consolidation.md` | +| Go source | `internal/cli/repos.go`, `internal/cli/repos_gitlab.go` | + +### `run` + +| Category | Files | +|----------|-------| +| CLI reference | _(no dedicated page)_ | +| Guides | `docs/guides/user/running-agents-locally.md`, `docs/guides/user/building-custom-agents.md`, `docs/guides/dev/cli-internals.md` | +| ADRs | `docs/ADRs/0036-agent-execution-sandbox.md` | +| Contributing | `docs/contributing/sandbox-topology.md` | +| Go source | `internal/cli/run.go` | + +## Minor commands + +The commands below have lighter documentation footprints. Apply the general `grep` rule when changing them: + +`dispatch`, `issues`, `scan`, `lock`, `poll`, `fetch-skill`, `post-review`, `post-comment`, `reconcile-status` + +The most comprehensive single reference for all commands (including minor ones) is `docs/guides/dev/cli-internals.md`, which documents the full command tree with flags. From 28c56c8c04ec6d67e7ed237a88e4f49dc9bf0819 Mon Sep 17 00:00:00 2001 From: Shai Revivo Date: Wed, 19 Aug 2026 14:10:37 +0300 Subject: [PATCH 2/3] =?UTF-8?q?fix(#5598):=20address=20review=20=E2=80=94?= =?UTF-8?q?=20complete=20mint/repos=20cross-refs,=20fix=20heading?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add missing mint touchpoints (infrastructure-reference, advanced-setup, org-mode) and repos touchpoint (getting-inference). Rename heading from "Documentation Updates" to "Documentation" to match contributing doc conventions. Co-Authored-By: Claude Opus 4.6 Signed-off-by: Shai Revivo --- docs/contributing/documentation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index 7d4a83f3e9..36ca91f590 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -1,8 +1,8 @@ --- -title: Documentation Updates +title: Documentation --- -# Documentation Updates +# Documentation When changing CLI command behavior, adding or removing subcommands, or renaming flags, you must update every documentation file that references the affected command. CLI commands are documented across CLI reference pages, user and operator guides, ADRs, and inline Go help text. Missing even one location causes documentation drift that surfaces as review findings on later PRs. @@ -64,7 +64,7 @@ Each row lists the documentation touchpoints for a major CLI command group. The | Category | Files | |----------|-------| | CLI reference | `docs/cli/mint.md` | -| Guides | `docs/guides/getting-started/operations.md`, `docs/guides/infrastructure/mint-administration.md`, `docs/guides/infrastructure/standalone-mint.md`, `docs/guides/dev/cli-internals.md` | +| Guides | `docs/guides/getting-started/operations.md`, `docs/guides/getting-started/org-mode.md`, `docs/guides/infrastructure/mint-administration.md`, `docs/guides/infrastructure/infrastructure-reference.md`, `docs/guides/infrastructure/advanced-setup.md`, `docs/guides/infrastructure/standalone-mint.md`, `docs/guides/dev/cli-internals.md` | | ADRs | `docs/ADRs/0059-public-mint-mode-with-wildcard-allowlists.md`, `docs/ADRs/0060-cross-org-mint-authorization-via-org-variables.md`, `docs/ADRs/0073-named-mint-privilege-levels.md`, `docs/ADRs/0077-mint-repos-scope-hardening.md`, `docs/ADRs/0078-simplified-mint-authorization-policy.md`, `docs/ADRs/0082-workflow-host-allow-list.md` | | Go source | `internal/cli/mint.go`, `internal/cli/mint_setup.go`, `internal/cli/mint_delete.go` | @@ -73,7 +73,7 @@ Each row lists the documentation touchpoints for a major CLI command group. The | Category | Files | |----------|-------| | CLI reference | `docs/cli/repos.md` | -| Guides | `docs/guides/getting-started/operations.md`, `docs/guides/getting-started/repo-management.md`, `docs/guides/dev/cli-internals.md` | +| Guides | `docs/guides/getting-started/operations.md`, `docs/guides/getting-started/repo-management.md`, `docs/guides/getting-started/getting-inference.md`, `docs/guides/dev/cli-internals.md` | | ADRs | `docs/ADRs/0057-repos-management.md`, `docs/ADRs/0074-repos-command-consolidation.md` | | Go source | `internal/cli/repos.go`, `internal/cli/repos_gitlab.go` | From dde47ff483104901637ac7566e4443d5c168b1d9 Mon Sep 17 00:00:00 2001 From: Shai Revivo Date: Thu, 20 Aug 2026 10:01:13 +0300 Subject: [PATCH 3/3] fix(#5598): address review round 2 - Fix ADR guidance to match docs/contributing/adrs.md (write a new superseding ADR, don't edit the original) - Scope admin section to admin foreign (active subcommand); note deprecated per-org tooling per ADR-0044 - Promote issues from minor-commands bucket to its own cross-reference section (has a dedicated user guide) - Add internal/cli/minttoken.go to mint Go source row - Expand grep discovery rule to include internal/cli/ for inline help Co-Authored-By: Claude Opus 4.6 Signed-off-by: Shai Revivo --- docs/contributing/documentation.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md index 36ca91f590..860e38f24a 100644 --- a/docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -11,14 +11,14 @@ When changing CLI command behavior, adding or removing subcommands, or renaming Before considering a CLI change complete, run: ```bash -grep -rn '' docs/ +grep -rn '' docs/ internal/cli/ ``` -Review every hit and update references that describe behavior you changed. This catches files not listed in the cross-reference below. +The `internal/cli/` path covers inline `Short`/`Long` help text in Go source. Review every hit and update references that describe behavior you changed. This catches files not listed in the cross-reference below. ## ADR annotations -ADRs are immutable records. When a CLI change supersedes an ADR's decision, **annotate** the ADR (add a status annotation or appendix note per [ADR conventions](adrs.md)) rather than editing the decision text inline. +When a CLI change makes an ADR's decision obsolete, write a **new ADR** that supersedes the old one rather than editing the original decision text. Minor annotations (status updates, "see also" links) are welcome — see [ADR conventions](adrs.md) for the full rules. ## Cross-reference by command group @@ -33,13 +33,15 @@ Each row lists the documentation touchpoints for a major CLI command group. The | ADRs | `docs/ADRs/0058-agent-registration.md` | | Go source | `internal/cli/agent.go` | -### `admin` +### `admin foreign` + +The `admin` command group's `install`/`uninstall`/`analyze`/`enable`/`disable` subcommands are deprecated per-org installation tooling ([ADR-0044](../ADRs/0044-deprecate-per-org-installation-mode.md)). The actively supported subcommand is `admin foreign` (cross-org mint-authorization allow-list). | Category | Files | |----------|-------| | CLI reference | _(no dedicated page)_ | -| Guides | `docs/guides/getting-started/org-mode.md`, `docs/guides/infrastructure/advanced-setup.md`, `docs/guides/infrastructure/mint-administration.md`, `docs/guides/dev/cli-internals.md` | -| ADRs | `docs/ADRs/0044-deprecate-per-org-installation-mode.md`, `docs/ADRs/0060-cross-org-mint-authorization-via-org-variables.md`, `docs/ADRs/0083-repo-level-foreign-allow-list.md` | +| Guides | `docs/guides/infrastructure/mint-administration.md`, `docs/guides/dev/cli-internals.md`, `docs/guides/dev/e2e-testing.md` | +| ADRs | `docs/ADRs/0060-cross-org-mint-authorization-via-org-variables.md`, `docs/ADRs/0083-repo-level-foreign-allow-list.md` | | Go source | `internal/cli/admin.go` | ### `github` @@ -66,7 +68,7 @@ Each row lists the documentation touchpoints for a major CLI command group. The | CLI reference | `docs/cli/mint.md` | | Guides | `docs/guides/getting-started/operations.md`, `docs/guides/getting-started/org-mode.md`, `docs/guides/infrastructure/mint-administration.md`, `docs/guides/infrastructure/infrastructure-reference.md`, `docs/guides/infrastructure/advanced-setup.md`, `docs/guides/infrastructure/standalone-mint.md`, `docs/guides/dev/cli-internals.md` | | ADRs | `docs/ADRs/0059-public-mint-mode-with-wildcard-allowlists.md`, `docs/ADRs/0060-cross-org-mint-authorization-via-org-variables.md`, `docs/ADRs/0073-named-mint-privilege-levels.md`, `docs/ADRs/0077-mint-repos-scope-hardening.md`, `docs/ADRs/0078-simplified-mint-authorization-policy.md`, `docs/ADRs/0082-workflow-host-allow-list.md` | -| Go source | `internal/cli/mint.go`, `internal/cli/mint_setup.go`, `internal/cli/mint_delete.go` | +| Go source | `internal/cli/mint.go`, `internal/cli/mint_setup.go`, `internal/cli/mint_delete.go`, `internal/cli/minttoken.go` | ### `repos` @@ -87,10 +89,18 @@ Each row lists the documentation touchpoints for a major CLI command group. The | Contributing | `docs/contributing/sandbox-topology.md` | | Go source | `internal/cli/run.go` | +### `issues` + +| Category | Files | +|----------|-------| +| CLI reference | _(no dedicated page)_ | +| Guides | `docs/guides/user/issues-commands.md`, `docs/guides/user/jira-integration.md`, `docs/guides/infrastructure/layered-config-reference.md`, `docs/guides/dev/cli-internals.md` | +| Go source | `internal/cli/issues.go` | + ## Minor commands The commands below have lighter documentation footprints. Apply the general `grep` rule when changing them: -`dispatch`, `issues`, `scan`, `lock`, `poll`, `fetch-skill`, `post-review`, `post-comment`, `reconcile-status` +`dispatch`, `scan`, `lock`, `poll`, `fetch-skill`, `post-review`, `post-comment`, `reconcile-status` The most comprehensive single reference for all commands (including minor ones) is `docs/guides/dev/cli-internals.md`, which documents the full command tree with flags.