docs: add deny and doctor CLI references

[danielmeppiel]

document(cli): add deny and doctor references

TL;DR

This PR adds standalone reference pages for apm deny and apm doctor, then
completes the CLI reference index for every public top-level command. A dynamic
contract test prevents future commands from shipping without a page or index
link. Closes #2123.

Note

The already-fixed apm install --target help is intentionally unchanged.

Problem (WHY)

• Issue [cli-consistency] CLI Consistency Report -- 2026-07-10 #2123 reports that
  "apm deny command has no documentation page".
• Issue [cli-consistency] CLI Consistency Report -- 2026-07-10 #2123 reports that
  "apm doctor command has no documentation page".
• The same report says
  "Reference index table (reference/index.md) is incomplete":
  nine public commands were absent from the landing-page table.
• [!] No automated contract connected Click's public command registry to the
  documentation artifacts, so future additions could repeat the drift.

Approach (WHAT)

#	Fix
1	Add a focused apm deny page covering scope, precedence, storage, and examples.
2	Add an apm doctor page grounded in the implemented critical and informational checks.
3	Add the nine omitted command links to the existing lifecycle groups in the reference index.
4	Derive public commands from Click and require both a matching page and index link.

Implementation (HOW)

File	Change
docs/src/content/docs/reference/cli/deny.md	Documents project and user denies, deny-wins behavior, pre-emptive blocks, and related commands.
docs/src/content/docs/reference/cli/doctor.md	Documents Git, network, authentication, marketplace, and executable-trust checks plus the exit-code contract.
docs/src/content/docs/reference/index.md	Adds approve, deny, doctor, find, lifecycle, lock, plugin, publish, and self-update without changing existing pages.
tests/unit/test_cli_docs_contract.py	Compares non-hidden Click commands with page filenames and exact index links.

Diagrams

Legend: the new contract derives required artifacts from the actual public
Click registry rather than a second hard-coded command list.

flowchart LR
    subgraph Registry[Public CLI]
        C[cli.commands]
    end
    subgraph Contract[Documentation contract]
        T[test_cli_docs_contract.py]
    end
    subgraph Reference[CLI reference]
        P[command-name.md]
        I[index.md link]
    end
    C --> T
    T --> P
    T --> I
    classDef new stroke-dasharray: 5 5;
    class T,P,I new;

Loading

Trade-offs

• Standalone deny page instead of restructuring approve. This gives the
  public command its expected route while leaving the existing combined trust
  model page intact.
• Dynamic registry check instead of a command allowlist. Importing the
  registered Click group adds a small test startup cost, but avoids maintaining
  another command inventory that can drift.
• Actual doctor behavior over broad help wording. The page explains that
  GitHub CLI is a credential source, not a separately required critical check.

Benefits

1. All 33 public top-level commands now have a same-named reference page.
2. All 33 public top-level commands now have an exact link in the reference
   landing page.
3. Removing a required page or index entry now fails a targeted unit test.
4. The generated site validates both new routes and all internal links.

Validation

uv run --extra dev pytest tests/unit/test_cli_docs_contract.py -q:

..                                                                       [100%]
2 passed in 0.49s

Mutation-break proof

With doctor.md temporarily removed:

FAILED tests/unit/test_cli_docs_contract.py::test_public_commands_have_reference_pages
E         Extra items in the left set:
E         'doctor'
1 failed in 0.47s
Mutation correctly failed; artifact restored

Documentation build and link validation

npm --prefix docs run build:

· All internal links are valid. ·
16:04:58 [build] 123 page(s) built in 16.57s
16:04:58 [build] Complete!

Lint and boundary checks

uv run --extra dev ruff check src/ tests/ and
uv run --extra dev ruff format --check src/ tests/:

All checks passed!
1481 files already formatted

Pylint duplication, auth boundary, architecture boundary, YAML I/O,
file-length, and portable-path guards:

Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)
[+] auth-signal lint clean
[+] architecture boundary lint clean
YAML, file-length, and portable-relpath guards passed

Scenario Evidence

#	Scenario (user promise)	Principle(s)	Test(s) proving it	Type
1	Every public apm command has a reference page at the expected route.	DevX, OSS / community-driven	tests/unit/test_cli_docs_contract.py::test_public_commands_have_reference_pages (regression-trap for #2123)	unit
2	Every public apm command is discoverable from the reference landing page.	DevX, OSS / community-driven	tests/unit/test_cli_docs_contract.py::test_public_commands_are_linked_from_reference_index (regression-trap for #2123)	unit

How to test

• Run uv run --extra dev pytest tests/unit/test_cli_docs_contract.py -q;
  expect two passing tests.
• Run npm --prefix docs run build; expect both new routes to build and
  internal link validation to pass.
• Open the generated reference index; expect all 33 public commands,
  including deny and doctor, to be linked.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

This PR closes a documentation gap by adding standalone CLI reference pages for apm deny and apm doctor, updating the CLI reference landing-page table to include all public top-level commands, and adding a unit-test contract that enforces “every public Click command must have a same-named reference page and an index link”.

Changes:

• Add new CLI reference pages: reference/cli/deny.md and reference/cli/doctor.md.
• Complete docs/src/content/docs/reference/index.md so all public top-level commands are linked.
• Add tests/unit/test_cli_docs_contract.py to assert docs coverage for public (non-hidden) Click commands.

Show a summary per file

File	Description
tests/unit/test_cli_docs_contract.py	Adds a contract test tying Click’s public command registry to docs pages and index links.
docs/src/content/docs/reference/index.md	Extends the CLI reference index table to include previously omitted commands (incl. deny/doctor).
docs/src/content/docs/reference/cli/doctor.md	Introduces the apm doctor reference page (checks, options, exit codes, examples).
docs/src/content/docs/reference/cli/deny.md	Introduces the apm deny reference page (scope, precedence, storage, examples).

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 2
• Review effort level: Low

[danielmeppiel]

APM Review Panel: ship_with_followups

Closes the docs funnel gap for apm deny and apm doctor with a dynamic contract test that prevents future silent drift between the Click command registry and the reference index.

cc @sergio-sisternes-epam -- a fresh advisory pass is ready for your review.

Six active panelists converge on ship. The PR adds real discoverability value and backs it with a contract test that structurally prevents the class of bug it fixes. No blocking-severity findings were raised.

The substantive correction surface is narrow but real: doc-writer, devx-ux-expert, and cli-logging-expert independently flag that doctor.md and the Click help string disagree on whether gh CLI is a standalone diagnostic domain or merely a credential source. The doc-writer also identifies that approve.md still presents itself as the command reference for both approve and deny, creating two authoritative references for one command. Both are in-scope truth-of-docs corrections.

Dissent. No true dissent. The help-versus-docs drift was independently surfaced by three personas with consistent remediation direction.

Aligned with: Pragmatic as npm: the contract test prevents future missing-docs drift. Secure by default: deny and doctor security claims match source. OSS community-driven: closes #2123 with a durable fix.

Growth signal. The dynamic Click-to-docs contract is a compounding discoverability primitive: every future public command inherits a CI check for its reference page and index link.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	0	2	Docs-only PR with a well-designed contract test; no architectural concerns.
CLI Logging Expert	0	0	2	Docs accurately reflect most CLI output contracts; minor wording and duplicate-example concerns.
DevX UX Expert	0	2	2	Discoverability improves, but doctor help/docs drift and cross-reference gaps remain.
Supply Chain Security Expert	0	0	2	Security claims match source; no security-model drift.
OSS Growth Hacker	0	1	2	Strong discoverability win; the contract test prevents future silent funnel gaps.
Doc Writer	0	3	0	Deny needs one canonical reference and complete edge behavior; doctor conflicts with existing help and guide text.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 4 follow-ups

1. [Doc Writer] Make deny.md the sole canonical reference for apm deny by removing deny-specific synopsis, options, and examples from approve.md. -- Two authoritative pages for one command create silent drift.
2. [Doc Writer] Reconcile doctor help and guide text with doctor.md on the gh CLI check claim. -- The implementation has no standalone gh CLI diagnostic.
3. [Doc Writer] Complete the deny execution contract: state that apm.yml is required even with --user, and document the all-types fallback when executable declarations are absent. -- These edge behaviors are implemented but currently omitted or overstated.
4. [DevX UX Expert] Link the deny precedence reference to the specific section in approve.md. -- A precise anchor avoids making readers scan a long page.

Architecture

classDiagram
    direction LR
    class cli {
        +commands dict
    }
    class Command {
        +hidden bool
        +name str
    }
    class DocsContract {
        +public_command_names() set
        +check_pages()
        +check_index_links()
    }
    cli *-- Command : registers
    DocsContract ..> cli : reads canonical registry

Loading

flowchart TD
    A[Public Click commands] --> B[Docs contract]
    B --> C[Same-named reference pages]
    B --> D[Exact index links]
    C --> E[Complete CLI reference]
    D --> E

Loading

Recommendation

Fold the three doc-truth corrections in this PR: establish one deny command reference, align doctor help and guides with implementation, and document deny's project/fallback behavior. The contract test is the durable win; duplicate examples and benefit-first wording are optional polish.

---

Full per-persona findings

Python Architect

• [nit] Contract test assertions could name missing commands at tests/unit/test_cli_docs_contract.py:18.
  Bare set assertions work, but explicit deltas make CI failures faster to act on.
• [nit] Procedural contract test is the right shape at this scope.
  Click remains the canonical owner of the public command surface.

CLI Logging Expert

• [nit] Marketplace authoring wording could mention actionable hints at docs/src/content/docs/reference/cli/doctor.md:37.
• [nit] The CI pre-flight example duplicates the basic invocation at docs/src/content/docs/reference/cli/doctor.md:68.

DevX UX Expert

• [recommended] Doctor help lists gh CLI as a separate diagnostic domain while the page says it is only a credential source at src/apm_cli/commands/doctor.py:20.
• [recommended] Link deny's precedence reference to the relevant section at docs/src/content/docs/reference/cli/deny.md:21.
• [nit] The doctor CI example repeats the basic command at docs/src/content/docs/reference/cli/doctor.md:66.
• [nit] Confirm deny's synopsis argument name mirrors Click help at docs/src/content/docs/reference/cli/deny.md:12.

Supply Chain Security Expert

• [nit] Doctor groups three marketplace authoring sub-checks into one conceptual row at docs/src/content/docs/reference/cli/doctor.md:35.
• [nit] Deny intentionally defers the executable-type list to the approve page at docs/src/content/docs/reference/cli/deny.md:33.

OSS Growth Hacker

• [recommended] Doctor's CI example duplicates the standard example at docs/src/content/docs/reference/cli/doctor.md:68.
• [nit] Deny frontmatter could lead with user intent at docs/src/content/docs/reference/cli/deny.md:3.
• [nit] Doctor frontmatter could lead with troubleshooting benefit at docs/src/content/docs/reference/cli/doctor.md:3.

Auth Expert -- inactive

No auth implementation, token management, credential resolution, or authorization behavior changed.

Doc Writer

• [recommended] Make deny.md the sole command-specific reference at docs/src/content/docs/reference/cli/approve.md:2.
  approve.md still includes deny in its title, synopsis, options, and examples.
• [recommended] Complete the documented deny execution contract at docs/src/content/docs/reference/cli/deny.md:28.
  The command requires apm.yml even with --user, and missing executable declarations use the all-types fallback.
• [recommended] Reconcile doctor check claims across help and documentation at docs/src/content/docs/reference/cli/doctor.md:34.
  Click help and an operating guide describe gh CLI as a separate check that run_doctor does not implement.

Test Coverage Expert -- inactive

Documentation-only PR; no runtime code paths changed.

Performance Expert -- inactive

Docs and contract-test changes do not affect runtime hot paths.

_{This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.}

[danielmeppiel]

APM Review Panel: ship_with_followups

Completes standalone deny/doctor reference docs, adds a dynamic Click-to-docs contract, and closes the top-level CLI index gap.

cc @sergio-sisternes-epam -- a fresh advisory pass is ready for your review.

Six active panelists converged on a clean docs-and-tests change with no blocking-severity findings. Supply-chain security confirmed deny-wins semantics are preserved; Python architecture validated the Click registry as the right canonical source for the docs contract; DevX verified synopsis parity; CLI logging confirmed the doctor help correction. CI is green on the reviewed head, and the doctor help mutation test fails without the correction.

Two panelists did not produce schema-valid returns after the retry cap. Their placeholders are visible below; no findings were accepted from them. Deterministic test and CI evidence was verified independently.

Aligned with: Secure by default: deny-wins semantics remain accurate. Governed by policy: deny behavior and doctor scope match implementation. Pragmatic as npm: complete, Click-aligned references match package-manager expectations. OSS community-driven: future missing command pages fail CI.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	0	1	Dynamic Click-to-docs contract is sound; no architectural concerns.
CLI Logging Expert	0	0	1	Doctor help is accurate and regression-tested.
DevX UX Expert	0	0	2	Deny and doctor follow package-manager reference conventions.
Supply Chain Security Expert	0	0	0	Trust semantics remain accurate; no security weakening.
OSS Growth Hacker	0	0	0	Schema failure; no findings accepted.
Doc Writer	0	0	1	Docs are accurate; align one auxiliary deny synopsis.
Test Coverage Expert	0	0	0	Schema failure; deterministic evidence was checked separately.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 2 follow-ups

1. [DevX UX Expert] Replace the duplicate apm doctor CI example with a distinct exit-code composition. -- The second block should demonstrate its stated CI use rather than repeat the basic invocation.
2. [Doc Writer] Change the apm-guide synopsis from apm deny [PACKAGE_REF...] to apm deny [OPTIONS] PACKAGES.... -- Brackets imply an optional argument, while Click requires at least one package.

Architecture

flowchart TD
    A[Public Click command registry] --> B[Docs contract tests]
    B --> C[Same-named reference pages]
    B --> D[Exact index links]
    C --> E[Complete CLI reference]
    D --> E

Loading

Recommendation

Fold the two small documentation corrections in this cycle. No strategic, security, or breaking-change concern remains.

---

Full per-persona findings

Python Architect

• [nit] A symmetric orphan-page check could complement the missing-page guard at tests/unit/test_cli_docs_contract.py:21.
  Stale pages are lower risk; the requested discoverability contract is already covered.

CLI Logging Expert

• [nit] The operating guide could mirror help-domain wording more literally at docs/src/content/docs/guides/operating-installed-context.md:59.
  The current sentence already names Git, network, authentication, and marketplace config, so this is stylistic.

DevX UX Expert

• [nit] The doctor CI example repeats the basic invocation at docs/src/content/docs/reference/cli/doctor.md:68.
• [nit] The deny Related section repeats the precedence deep-link at docs/src/content/docs/reference/cli/deny.md:61.
  Both links are valid and accurate.

Supply Chain Security Expert

No findings.

OSS Growth Hacker

Schema failure after the retry cap; no findings accepted.

Auth Expert -- inactive

No authentication behavior changed.

Doc Writer

• [nit] Align the apm-guide deny synopsis with Click at packages/apm-guide/.apm/skills/apm-usage/commands.md:274.

Test Coverage Expert

Schema failure after the retry cap; no findings accepted. The doctor help assertion, both docs contract tests, mutation proof, and CI were verified independently.

Performance Expert -- inactive

No performance-relevant path changed.

_{This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.}

[danielmeppiel]

APM Review Panel: ship_now

Clean, uncontroversial change with full panel consensus -- no strategic risk, no breaking surface, ship as-is.

cc @sergio-sisternes-epam -- a fresh advisory pass is ready for your review.

All panelists converged without dissent. The change is bounded, internally consistent, and introduces no breaking behavior. The PR now has standalone deny and doctor references, a complete CLI index, and a dynamic contract that prevents future public commands from shipping without a page and index link. The only remaining panel note is optional test-failure-message polish; correctness is already covered.

Aligned with: OSS community-driven: this is a low-friction contribution with a durable guard against documentation drift.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	0	1	Thin help change and sound docs contract; no architecture concern.
CLI Logging Expert	0	0	0	Doctor help and docs agree on gh CLI as an auth source.
DevX UX Expert	0	0	0	Deny and doctor syntax, examples, index, and guides are aligned.
Supply Chain Security Expert	0	0	0	Deny and doctor semantics match source.
OSS Growth Hacker	0	0	0	Discoverability surfaces improve with no growth concern.
Doc Writer	0	0	0	Pages, index, and cross-references match source.
Test Coverage Expert	0	0	0	Mutation trap and dynamic docs tests cover changed behavior.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Architecture

flowchart TD
    A[Public Click command registry] --> B[Docs contract tests]
    B --> C[Same-named reference pages]
    B --> D[Exact index links]
    C --> E[Complete CLI reference]
    D --> E

Loading

Recommendation

Merge at maintainer convenience. No follow-ups remain to track.

Folded in this run

• (panel) Made deny.md the canonical command reference -- resolved in 3239d24cb.
• (panel) Aligned doctor help and guides with implemented checks -- resolved in 3239d24cb.
• (panel) Documented deny's project requirement and all-types fallback -- resolved in 3239d24cb.
• (panel) Added precise approve/deny precedence cross-links -- resolved in 3239d24cb.
• (panel) Replaced the duplicate doctor example with a CI composition -- resolved in 185d5d993.
• (panel) Aligned the packaged deny synopsis with Click -- resolved in 185d5d993.

Regression-trap evidence (mutation-break gate)

• tests/unit/commands/test_doctor.py::test_apm_doctor_registered_at_top_level -- restored the old standalone gh CLI help claim; test FAILED as expected; corrected help restored.

Lint contract

uv run --extra dev ruff check src/ tests/ and uv run --extra dev ruff format --check src/ tests/ passed. Pylint duplication, YAML I/O, file length, portable-path, auth-signal, and architecture-boundary guards also passed.

CI

All required checks passed on 185d5d9931436323f4ea2092eccaa7dc3c5679a3, including CI run https://github.com/microsoft/apm/actions/runs/29197574325 (after 0 CI fix iterations).

Mergeability status

Captured from gh pr view 2178 --json mergeable,mergeStateStatus,statusCheckRollup after the final push.

PR	head SHA	CEO stance	iters	folds	defers	Copilot rounds	CI	mergeable	mergeStateStatus	notes
#2178	185d5d9	ship_now	2	6	0	2	green	MERGEABLE	BLOCKED	pending required review

Convergence

2 outer iterations; 2 Copilot rounds. Final panel stance: ship_now.

Ready for maintainer review.

---

Full per-persona findings

Python Architect

• [nit] The docs contract assertions could name missing commands at tests/unit/test_cli_docs_contract.py:22.
  Bare set assertions already catch drift; explicit delta messages would only improve failure readability.

CLI Logging Expert

No findings.

DevX UX Expert

No findings.

Supply Chain Security Expert

No findings.

OSS Growth Hacker

No findings.

Auth Expert -- inactive

Only doctor help text, documentation, and tests changed; no auth behavior changed.

Doc Writer

No findings.

Test Coverage Expert

No findings.

Performance Expert -- inactive

Only a Click help string, documentation, and tests changed; no performance path is affected.

_{This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.}