docs(#5598): add CLI-to-documentation cross-reference guide

[shairevivo]

Summary

• Create docs/contributing/documentation.md mapping 7 major CLI command groups (agent, admin, github, inference, mint, repos, run) to all their documentation touchpoints (CLI reference pages, user/dev guides, ADRs, Go source)
• Add a general grep-based discovery rule for minor commands
• Add a row to the AGENTS.md topic-specific guidance table pointing to the new guide

Closes #5598

Test plan

• All file paths listed in the cross-reference verified to exist
• Pre-commit lint passes (excluding lychee link checker not available locally — CI will run it)
• VitePress sidebar auto-discovers the new page under "Contributor Guidelines" (uses getMarkdownFiles())

🤖 Generated with Claude Code

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[qodo-code-review]

PR Summary by Qodo

Add CLI documentation cross-reference guide

📝 Documentation 🕐 10-20 Minutes

AI Description

• Map seven major CLI command groups to their documentation and source touchpoints.
• Add grep-based discovery guidance for minor commands and unlisted references.
• Link the guide from contributor topic-specific guidance.

Diagram

graph TD
  A["AGENTS.md"] --> B["Update Guide"] --> C["Command Groups"] --> D["CLI References"] & E["User Guides"] & F["ADRs"] & G["Go Help"]

Loading

High-Level Assessment

The static, curated guide is appropriate because documentation relevance is semantic and cannot be reliably inferred from grep results alone. Relying only on repository search would be less actionable, while generating the mapping would require new metadata and maintenance tooling disproportionate to this documentation change.

Files changed (2) +97 / -0

Documentation (2) +97 / -0

AGENTS.mdLink CLI documentation maintenance guidance +1/-0

Link CLI documentation maintenance guidance

• Adds the documentation guide to the topic-specific contributor guidance table for CLI behavior, subcommand, and flag changes.

AGENTS.md

documentation.mdDocument CLI-to-documentation cross-references +96/-0

Document CLI-to-documentation cross-references

• Introduces a contributor guide mapping seven major CLI command groups to reference pages, guides, ADRs, and Go help sources. It also defines grep-based discovery for additional references, lists minor commands, and clarifies that superseded ADR decisions should be annotated rather than rewritten.

docs/contributing/documentation.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

1. Discovery skips inline help ✓ Resolved 🐞 Bug ≡ Correctness

Description

The required discovery command searches only docs/, even though the guide classifies inline Go
help as a documentation touchpoint and tells contributors to use this rule for minor commands.
Changes to minor commands can therefore miss their Short, Long, and flag documentation under
internal/cli.

Code

docs/contributing/documentation.md[R14-15]

+grep -rn '<command-name>' docs/
+```

Relevance

●●● Strong

Accepted precedent fixes incomplete CLI documentation coverage; this discovery rule excludes
declared inline-help touchpoints.

PR-#1087
PR-#6138

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new guide identifies inline Go help as documentation and makes the docs-only grep rule the
primary guidance for minor commands. For example, the minor post-comment command's help and flags
reside entirely under internal/cli, which the command never searches.

docs/contributing/documentation.md[7-17]
docs/contributing/documentation.md[90-96]
internal/cli/postcomment.go[25-42]
internal/cli/postcomment.go[80-88]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The general discovery command only searches `docs/`, so it cannot discover inline CLI help under `internal/cli`, particularly for minor commands that have no source mapping.

## Issue Context
The guide explicitly requires inline Go help to remain synchronized and directs minor-command changes to use the general grep rule.

## Fix Focus Areas
- docs/contributing/documentation.md[7-17]
- docs/contributing/documentation.md[90-96]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Comprehensive reference omits flags 🐞 Bug ≡ Correctness

Description

The guide says cli-internals.md documents the full command tree with flags, but its root
post-comment entry omits all six flags defined by that command. This gives contributors an
incomplete fallback reference for a minor command that the new guide explicitly directs them there
to inspect.

Code

docs/contributing/documentation.md[96]

+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.

Relevance

●●● Strong

Recent accepted precedent specifically adds missing CLI subcommands; omitted flags contradict the
claimed comprehensive reference.

PR-#1087
PR-#1015

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The command tree shows the root post-comment entry without child flags, whereas its implementation
defines --repo, --number, --marker, --result, --token, and --dry-run. The separate
issues post-comment entry does not satisfy documentation of this deprecated root command.

docs/contributing/documentation.md[96-96]
docs/guides/dev/cli-internals.md[110-130]
internal/cli/postcomment.go[25-33]
internal/cli/postcomment.go[80-88]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The guide advertises `cli-internals.md` as a full command-and-flag reference, but the deprecated root `post-comment` command is shown without its existing flags.

## Issue Context
This root command is distinct from `issues post-comment` and remains registered with six flags.

## Fix Focus Areas
- docs/guides/dev/cli-internals.md[129-130]
- docs/contributing/documentation.md[96-96]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Mint token source omitted ✓ Resolved 🐞 Bug ≡ Correctness

Description

The mint Go source row omits internal/cli/minttoken.go, even though mint.go registers its
token subcommand and that file contains the subcommand's inline help. Contributors following this
map can miss required help updates for fullsend mint token.

Code

docs/contributing/documentation.md[69]

+| Go source | `internal/cli/mint.go`, `internal/cli/mint_setup.go`, `internal/cli/mint_delete.go` |

Relevance

●●● Strong

Team accepts corrections to incomplete CLI command/source documentation; omitted token help file is
a concrete coverage gap.

PR-#1087
PR-#1252

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The listed mint source files exclude minttoken.go; mint.go registers newMintTokenCmd, while
the omitted file defines the command and its Short and Long text.

docs/contributing/documentation.md[69-69]
internal/cli/mint.go[399-399]
internal/cli/minttoken.go[18-33]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The mint source mapping omits the file implementing the registered `fullsend mint token` subcommand and its inline help.

## Issue Context
The Go source column is described as the location of `Short` and `Long` help text.

## Fix Focus Areas
- docs/contributing/documentation.md[69-69]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 56 rules

✅ Skills: writing-user-docs, writing-adrs

Tip of the day

💡 Did you know, you can copy the agent prompt from any finding and feed it to your IDE agent

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[github-actions]

Site preview

Preview: https://6b21aa82-site.fullsend-ai.workers.dev

Commit: 0260ab297afff4754b8e4f7a47864111d8414831

[ascerra]

/fs-review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:08 AM UTC · Completed 10:23 AM UTC

Commit: c501fce · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [Incomplete cross-reference] docs/contributing/documentation.md:67 — The mint command group cross-reference is missing several files that contain substantive mint CLI command references: docs/guides/infrastructure/infrastructure-reference.md (documents 8+ mint subcommands including deploy, delete, enroll, unenroll, status, add-role, remove-role, workflow-host, token), docs/guides/infrastructure/advanced-setup.md (contains mint deploy and mint enroll invocations), and docs/guides/getting-started/org-mode.md (documents mint unenroll in a teardown procedure). Since the document's purpose is to prevent documentation drift by listing all touchpoints, these omissions risk a contributor modifying mint subcommands and missing updates to these files.
  Remediation: Add the missing files to the mint Guides row.

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected governance file. The change is authorized by issue Add CLI-to-documentation cross-reference in contributing guide #5598 and the PR body explains the rationale (adding a row to the topic-specific guidance table). Human approval is always required for protected-path changes, regardless of context.

Low

• [Incomplete cross-reference] docs/contributing/documentation.md:80 — The repos command group cross-reference is missing docs/guides/getting-started/getting-inference.md, which mentions repos install --inference-project.
  Remediation: Add docs/guides/getting-started/getting-inference.md to the repos Guides row.

• [documentation-structure] docs/contributing/documentation.md:5 — The H1 heading "Documentation Updates" does not match the established pattern for contributing docs. All 13 existing contributing docs use topic-noun phrases ("CI Workflows", "Go Code", "Shell Scripting", etc.). Additionally, the AGENTS.md table row added by this same PR links to the file as "[Documentation]" (without "Updates"), creating an internal inconsistency.
  Remediation: Change the H1 heading to "# Documentation" and update the YAML frontmatter title to match.

[fullsend-ai-review]

See the review comment for full details.

[waynesun09]

Automated review sweep: 3 findings below.

[waynesun09]

Validated at head 0260ab29:

• All 49 docs//internal/ paths referenced in the cross-reference exist on the PR head; both relative links (adrs.md, ADR 0044) resolve.
• Command-group coverage matches the actual root.go registry — the 8 sections plus the minor-commands list account for all 16 registered root commands.
• My round-2 findings are all fixed: ADR guidance now matches adrs.md (supersede via new ADR, minor annotations only), admin is scoped to the supported foreign path with the ADR-0044 deprecation note, issues has its own section pointing at issues-commands.md, and the heading/frontmatter/AGENTS.md link are consistent.
• Bot findings addressed too: grep rule includes internal/cli/, mint row gained infrastructure-reference.md/advanced-setup.md/org-mode.md + minttoken.go, repos gained getting-inference.md.

One residual nit, non-blocking: the admin foreign Go-source row lists only internal/cli/admin.go, but the foreign subcommand's implementation and Short/Long help text live in internal/cli/foreign.go (admin.go only registers it at line 74). Fine to fix in a follow-up; the general grep rule catches it. Qodo's remaining point about cli-internals.md missing post-comment flags concerns a pre-existing file and is out of this PR's scope.