docs: doc sweep for stale references, casing, and index gaps

[yuanchen8911]

Summary

Release-prep proofreading sweep over the root governance docs and the docs/ tree: stale version references, terminology casing, a wrong package path, and index/nav gaps. Documentation only — no code, schema, or build inputs changed.

Motivation / Context

Ahead of cutting the next release, the user-facing docs needed a pass for errors, inconsistencies, and drift that had accumulated since the last sweep.

Generated artifacts (THIRD_PARTY_NOTICES.md, docs/conformance/** evidence) and historical ADRs under docs/design/ were deliberately left untouched — the former are regenerated, the latter are historical records.

Fixes: N/A
Related: #2336

Relationship to #2336. Reviewing this PR surfaced a matching stale 1.33 in a Go comment on defaults.MirrorDefaultKubeVersion, which claims to track the project's minimum supported Kubernetes version. That is almost certainly the same bad assumption this PR removes from the Tech Stack line, restated in code. It is pre-existing and untouched here, so it is fixed separately in #2336 rather than widening this docs-only diff. The two PRs are independent — they share no files and can merge in either order.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Build/CI/tooling

Component(s) Affected

• CLI (cmd/aicr, pkg/cli)
• API server (cmd/aicrd, pkg/server)
• Recipe engine / data (pkg/recipe)
• Bundlers (pkg/bundler, pkg/component/*)
• Collectors / snapshotter (pkg/collector, pkg/snapshotter)
• Validator (pkg/validator)
• Core libraries (pkg/errors, pkg/k8s)
• Docs/examples (docs/, examples/)
• Other: AGENTS.md / .claude/CLAUDE.md (kept in sync)

Implementation Notes

Correctness fixes.

• The Key Packages table listed pkg/validator/helper, which does not exist — the package is validators/helper. Description corrected as well.
• docs/README.md "Find Your Path" pointed the Integrator row at integrator/automation.md, while the User and Contributor rows point at their section index. Now integrator/index.md.
• The Tech Stack line claimed Kubernetes 1.33+, unchanged since chore: init repo. Nothing in the tree matches it: k8s.io/{api,apimachinery,client-go} are at v0.36.3, kind_node_image is kindest/node:v1.36.1, and recipe constraint floors are per-recipe (1.25 through 1.34). Rather than pick a number that would read as a support floor it cannot be, the version is unpinned from that line — the same treatment golangci-lint got in chore(docs): document make tools-update and unpin version from Tech Stack line #925, leaving .settings.yaml and go.mod as the single source of truth.
• docs/contributor/recipe.md claimed that deployers other than argocd-helm have no supported install-time value surface. --dynamic is supported on helm, flux, and helmfile (bundler.go); only plain argocd rejects it. Reworded to state the real split: the bundle-time gate is the whole enforcement for those three, whose install-time surface is closed to the paths --dynamic declares; argocd-helm needs an additional template-time guard because it deliberately exposes the parent chart's .Values openly; plain argocd has no such surface. This matches the CLI contract already documented at cli-reference.md (--dynamic flag row, and the argocd-helm deployer notes).

Stale versions. Three example image/tarball tags had drifted apart (0.15.0, v0.11.1, v0.1.0); normalized to v0.19.0, matching what the rest of the docs already use.

Terminology. Each of these was a small minority against an already-dominant convention: ArgoCD → Argo CD (3 sites vs 101 correct), TCPxO → TCPXO (3 vs 37), GPU Daemonsets → DaemonSets, vanilla kubernetes → Kubernetes. A sentence-initial Argocd-helm was reworded to "The argocd-helm deployer".

Completeness.

• The api-reference component table was missing 7 registry components (k8s-aibom, slinky-topograph, and 5 OCP variants while including 6 others) and had the mariadb-* rows out of alphabetical order. Now complete and sorted, with the "illustrative" caveat replaced by an accurate pointer to the catalog.
• docs/user/index.md was missing fabric-attached-training.md.
• docs/contributor/index.md was missing four pages that exist but were unlinked: uat.md, rekor-v2-signing.md, registry-egress.md, inference-perf-fluctuation.md.
• Dropped an agent attribution from an investigation-doc byline, per the no-attribution policy.

One change made and reverted. docs/user/container-images.md is the only user-facing page absent from docs/index.yml, so it was added — and check-docs-mdx correctly rejected it. The exclusion is deliberate: the file's <!-- BEGIN AICR-BOM --> markers are not MDX-safe, and the tool derives its scan list from the nav. Reverted; the page stays reachable from docs/user/index.md.

Testing

Doc-only change, so the scoped gates were run rather than full make qualify — no Go, YAML schema, or build inputs are touched, so tests, e2e, and Go lint cannot regress from this diff.

./tools/check-docs-filenames    # OK: all doc filenames follow kebab-case convention
./tools/check-docs-mdx          # OK: all doc files are MDX-safe
./tools/check-docs-mdx-parse    # OK: 54 doc file(s) parse as MDX
./tools/check-agents-sync       # OK: AGENTS.md is in sync with .claude/CLAUDE.md
yamllint -c .yamllint.yaml docs/index.yml

Beyond the repo's own gates, the sweep was driven by mechanical checks across all 88 in-scope Markdown files, each re-run clean after the edits:

• Every relative link and #anchor resolved against generated heading slugs.
• Whitespace, tabs, EOF newlines, blank-line runs, smart quotes/NBSP, code-fence balance, heading-level jumps, table column counts.
• aspell over fence-stripped prose.
• Documented --flags and aicr subcommands checked against pkg/cli; criteria enums against pkg/recipe/criteria.go and every enum: block in api/aicr/v1/server.yaml; component lists against recipes/registry.yaml; backticked repo paths against the tree.

Risk Assessment

• Low — Isolated change, well-tested, easy to revert
• Medium — Touches multiple components or has broader impact
• High — Breaking change, affects critical paths, or complex rollout

Rollout notes: N/A — prose, links, and table content only.

Checklist

• Tests pass locally (make test with -race) — N/A, no Go changes; scoped doc gates run instead (see Testing)
• Linter passes (make lint) — doc-lint subset run: filenames, MDX, MDX-parse, agents-sync, yamllint
• I did not skip/disable tests to make CI green
• I added/updated tests for new functionality — N/A, documentation only
• I updated docs if user-facing behavior changed — N/A, no behavior change
• Changes follow existing patterns in the codebase
• Commits are cryptographically signed (git commit -S)

[github-actions]

🌿 Preview your docs: https://nvidia-preview-docs-release-proofread-sweep.docs.buildwithfern.com/aicr

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: da37a516-f827-4c44-8f56-d87d3f266e6a

📥 Commits

Reviewing files that changed from the base of the PR and between c956247 and 801a8c8.

📒 Files selected for processing (1)

• docs/contributor/recipe.md

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Walkthrough

Walkthrough

The pull request updates documentation across contributor, integrator, and user guides. It corrects product and platform terminology, updates component listings and release-version examples, changes navigation links, adds contributor and user guide links, and revises validator helper documentation. It also removes an explicit Kubernetes version requirement from documented toolchain descriptions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 801a8

This PR updates documentation references, terminology, navigation, and release-preparation content without changing code, schemas, build inputs, or runtime behavior. No actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: mchmarny

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the documentation sweep for stale references, terminology casing, and missing index entries.
Description check	✅ Passed	The description accurately explains the documentation-only release-preparation sweep and its main corrections.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[njhensley]

Review method: three independent persona reviewers (docs-correctness/link-integrity, domain & architecture accuracy, release/CI-DX) in parallel, then adversarial meta-review of every finding against the resolved tree at head 801a8c8b.
Legend: 🔴 Blocker · 🟠 Major · 🟡 Minor · 🔵 Nitpick.

Overall assessment

A clean, well-scoped, low-risk documentation sweep. Every substantive factual claim in the diff was verified against the actual tree (not just the PR description):

• ✅ validators/helper path fix is correct — pkg/validator/helper does not exist.
• ✅ integrator/index.md retarget + all 5 newly-added nav links exist on disk and are registered in docs/index.yml.
• ✅ The api-reference component table now matches recipes/registry.yaml exactly — all 43 components, alphabetized, 2 columns per row; spot-checked descriptions (k8s-aibom, slinky-topograph, the *-ocp variants, mariadb-operator*) match the registry.
• ✅ The reworded recipe.md --dynamic/deployer paragraph is accurate: helm/flux/helmfile expose a closed dynamic-path surface; argocd-helm alone emits the structural template-time guard (pkg/bundler/deployer/argocdhelm/argocdhelm.go, the aicr-profile-lock template); plain argocd rejects --dynamic (bundler.go:763-766).
• ✅ Dropping "Kubernetes 1.33+" is correct — deps are at v0.36.3, kind image v1.36.1, recipe floors span 1.25–1.34, so a single pin was unsupportable in both directions.
• ✅ All in-scope aicr:/tarball tags normalized to v0.19.0 with no stragglers; no residual TCPxO / ArgoCD; AGENTS.md↔.claude/CLAUDE.md byte-in-sync; all four doc gates green.

Recommendation: Approve. Two optional 🟡 minor follow-ups below — both in files this PR does not touch, so neither blocks; either fold them in or leave for a separate one-liner.

Findings (both non-blocking, out-of-diff)

🟡 F1 — GPU daemonsets prose left lowercase after the header was cased — docs/user/cli-reference.md L1529 & L1547.
The PR cased the table header (L1520) to GPU DaemonSets, but the same section's Note and bullet still read GPU daemonsets, a new within-section mismatch the edit created. Fix: case both to GPU DaemonSets.

🟡 F2 — Stale aicrd:v0.8.0 upgrade command missed by the version sweep — docs/integrator/kubernetes-deployment.md L612.
A copy-pasteable rolling-update command pins the server image aicrd to v0.8.0 (~11 releases old). The sweep normalized the client aicr: tags; the aicrd: server image slipped through the grep pattern. Bumping :v0.8.0 → :v0.19.0 would make the "normalize example tags" claim complete.

Confirmed non-issue (examined, dismissed)

🔵 v0.8.12 in the SBOM/attestation sample (docs/integrator/supply-chain-verification.md) — refuted. That tag is used consistently across 5 sites as one coherent, historically-captured attestation + SBOM example; a partial bump would break its internal consistency and a full bump is out of scope. Correct as-is.

Tier table

🔴 Blocker	🟠 Major	🟡 Minor	🔵 Nitpick
0	0	2	0

Recommendation: Approve (2 optional minor follow-ups).