Skip to content

docs: post-0.36 corpus re-sweep #3800

Closed

Description

Proposals are welcome before implementation. For substantive changes, wait
for a responsible human maintainer to approve the scope and identify a review
contact. An automated recommendation, label alone, or silence is not approval.
See Contributing.

Is your feature request related to a problem? Please describe.
Since v0.34.0 there have been 552 commits; 48 of the 193 src/apm_cli commits did not touch docs or the apm-usage skill, and .apm/docs-index.yml (the docs-sync corpus map) only seeded ~20 of 131 pages. Readers of the docs site and of the apm-usage agent skill can hit stale commands, flags, defaults and dead links.

Describe the solution you'd like
A whole-corpus re-sweep with the docs-corpus-audit skill, against current main:

  • Refresh .apm/docs-index.yml so it covers every page under docs/src/content/docs/.
  • Audit every page in docs/src/content/docs/ and packages/apm-guide/.apm/skills/apm-usage/, verifying each factual claim (commands, flags, env vars, config fields, paths, links) against code; use the 0.35.0 / 0.35.1 / 0.36.0 / [Unreleased] CHANGELOG blocks as a drift checklist.
  • Ship surgical fixes in small docs-only PRs batched by area (ASCII-only in apm-usage, pragmatic and succinct).
  • After v0.36.1 is tagged, re-check the pages touched by the 0.36.1 PRs.

Done when: the index covers every page, the drift found is either fixed in merged docs PRs or listed with an owner, and a final report lists findings by severity.

Describe alternatives you've considered
Per-PR docs-sync only. It does not catch drift that accumulated across releases.

Additional context
Out of scope: README.md (drift is reported as a proposal only; needs maintainer approval); code changes; pages being edited by still-open PRs (findings recorded, not edited), including manifest-schema.md #v1.0.0 wording (#3731 / #3775) and enterprise/registry-proxy.md (#3777).

Activity

  1. added
    area/docs-sitedocs/src/content (Starlight), README, doc generation.
    type/docsDocumentation change (prose, examples, generated reference).
    on Nov 17, 2026
  2. danielmeppiel commented on Nov 17, 2026

    @danielmeppiel
    CollaboratorAuthor

    Decision: approve
    Area: project
    Scope: Refresh .apm/docs-index.yml to cover every docs page; audit every page in docs/src/content/docs/ and packages/apm-guide/.apm/skills/apm-usage/ against current main, using CHANGELOG 0.35.0..[Unreleased] as the checklist; land surgical docs-only fixes in small PRs batched by area; after v0.36.1 is tagged, re-check pages touched by the 0.36.1 PRs.
    Done when: The docs index covers every page; found drift is fixed in merged docs PRs or listed with an owner; a final report is delivered to the maintainer.
    Out of scope: README.md (proposal only); code changes; pages edited by still-open PRs, including manifest-schema #v1.0.0 wording (#3731, #3775) and registry-proxy (#3777).
    Review contact: Daniel Meppiel (@danielmeppiel)

  3. 4 remaining items

  4. danielmeppiel commented on Nov 18, 2026

    @danielmeppiel
    CollaboratorAuthor

    Decision: approve
    Area: project
    Scope: Amend the #3800 docs re-sweep. Fix every remaining finding in the sweep report under docs/src/content/docs/ and packages/apm-guide/.apm/skills/apm-usage/ instead of deferring or holding. Pages that open PRs also edit are in scope: edits that do not overlap those PRs' hunks land directly, and overlapping fixes are coordinated with the PR owner into one change that keeps the contributor's work. Routine editorial and product documentation choices are resolved in the docs. Bump the apm-guide pin at README.md:179 to the current release tag.
    Done when: Each remaining finding is fixed in a merged docs PR or in the owning PR, or, for a confirmed code defect, filed as a bug issue with an owner. The sweep report is updated with links to what landed.
    Out of scope: Changing CLI behavior. Normative spec text under docs/src/content/docs/specs/ or policy semantics changed to hide a bug. README edits other than the apm-guide pin.
    Review contact: Daniel Meppiel (@danielmeppiel)

  5. danielmeppiel commented on Nov 18, 2026

    @danielmeppiel
    CollaboratorAuthor

    Closing: the post-0.36 docs corpus re-sweep is complete.

    Landed (all docs-only, Refs #3800):

    Handed off

    Every claim was checked against the CLI --help, the source, or a scratch-dir run on main. The docs build and link check pass.

  6. added a commit that references this issue on Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/docs-sitedocs/src/content (Starlight), README, doc generation.status/acceptedHuman scope approval; verify the issue's approval record and review contact before work.type/docsDocumentation change (prose, examples, generated reference).

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions