docs: audit-driven dedup, drift fixes, and new guides#1334
Merged
Conversation
Documentation audit cleanup focused on maximum reader value with minimal content. Net -1,890 lines. Duplication removed (canonical home + cross-link): - copilot-instructions.md gutted to a pointer to AGENTS.md/DEVELOPMENT.md (was ~880 lines of duplicated rules/architecture/code). - SECURITY.md trimmed 676->137 lines; operational verification deep-dive relocated to docs/integrator/supply-chain-verification.md. - Agent-deployment, recipe-evidence, and constraint-table content deduped across cli-reference, agent-deployment, kubernetes-deployment, validation, recipe-development, and data-flow. - Six CUJ demos merged into demos/cuj1-training.md + demos/cuj2-inference.md; demos/ext.md deleted (subsumed); GKE TCPXO benchmark moved to docs/integrator/gke-tcpxo-networking.md. Bloat trimmed: automation.md (-461), kubernetes-deployment.md (-250), data-flow.md (-267) — duplicate CI snippets, stub controller, generic K8s boilerplate. Drift fixed: marked version examples illustrative (point to Component Catalog/BOM); fixed stale api-reference server version and chart versions; fixed a pre-existing broken validator anchor. New docs (Diataxis gaps): docs/user/tutorial.md (end-to-end) and docs/user/bundling.md (bundle how-to), wired into the hub and user index. Style: removed manual TOCs (CONTRIBUTING/DEVELOPMENT), fixed CODE_OF_CONDUCT template placeholder, renamed terse demo files for discoverability. Skills: prefixed all project skills with aicr- to avoid collision; added aicr-auditing-docs to make this audit repeatable. Also updated stale demo-path references in UAT test/workflow comments.
mchmarny
added
the
theme/community
Contributor
Coverage Report ✅
Coverage BadgeNo Go source files changed in this PR. |
lalitadithya
approved these changes
Jun 12, 2026
📝 WalkthroughWalkthroughThis pull request consolidates and reorganizes AICR documentation across multiple areas. The PR centralizes AI agent guidance by renaming Claude skills with an Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CONTRIBUTING.md`:
- Around line 181-183: Add a blank line before the fenced code block following
the "Address Feedback" paragraph so the markdown linter MD031 passes; locate the
"3. **Address Feedback**" paragraph and insert an empty line immediately before
the triple-backtick fence that opens the bash example (`git commit -m "address
review: improve error handling"`) so the code block is separated from the
preceding text.
In `@docs/user/api-reference.md`:
- Around line 9-10: The version disclaimer currently only mentions sample
request/response versions but the local-server setup still uses the floating
image tag ghcr.io/nvidia/aicrd:latest; update the docs/user/api-reference.md by
either expanding the existing disclaimer to explicitly cover setup commands and
container image references or change the local-server snippet to use a pinned
tag (e.g., replace ghcr.io/nvidia/aicrd:latest with a specific version like
ghcr.io/nvidia/aicrd:<pin>) so examples do not drift; ensure the change
references the same snippet that contains ghcr.io/nvidia/aicrd:latest.
In `@docs/user/tutorial.md`:
- Around line 15-20: Update the wording around the local cluster sentence to
clarify the dry-run boundary: explicitly state that Kind/KWOK only supports the
recipe and bundle generation phases and cannot perform the deploy or validate
stages, and that steps 5-6 (the deploy and validate stages) require a live
GPU-capable cluster (EKS/GKE/AKS or similar) with kubectl configured; reference
the existing phrases "Kind/KWOK", "recipe/bundle", and "deploy and validate
stages" so readers know which steps cannot be completed locally.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 51a559f1-1ba2-4891-8bac-21c1ec9f9ac9
📒 Files selected for processing (48)
.claude/CLAUDE.md.claude/skills/aicr-analyzing-snapshots/SKILL.md.claude/skills/aicr-auditing-docs/SKILL.md.claude/skills/aicr-creating-guided-demos/SKILL.md.claude/skills/aicr-creating-guided-demos/skeleton.sh.claude/skills/aicr-creating-slide-decks/SKILL.md.claude/skills/aicr-creating-slide-decks/skeleton.html.claude/skills/aicr-managing-openvex/SKILL.md.github/copilot-instructions.md.github/workflows/uat-aws.yaml.github/workflows/uat-gcp.yamlAGENTS.mdCODE_OF_CONDUCT.mdCONTRIBUTING.mdDEVELOPMENT.mdSECURITY.mddemos/README.mddemos/cuj1-eks.mddemos/cuj1-gke.mddemos/cuj1-training.mddemos/cuj2-eks.mddemos/cuj2-gke.mddemos/cuj2-inference.mddemos/cuj2.mddemos/end-to-end-cli.mddemos/examples/CUJ2-Test-Report.mddemos/ext.mddemos/query.mddemos/recipe-data-architecture.mddemos/validation-acceptance.mddocs/README.mddocs/integrator/automation.mddocs/integrator/data-flow.mddocs/integrator/gke-tcpxo-networking.mddocs/integrator/index.mddocs/integrator/kubernetes-deployment.mddocs/integrator/recipe-development.mddocs/integrator/supply-chain-verification.mddocs/user/api-reference.mddocs/user/bundling.mddocs/user/cli-reference.mddocs/user/index.mddocs/user/tutorial.mddocs/user/validation.mdtests/chainsaw/cli/cuj1-training/chainsaw-test.yamltests/uat/aws/tests/cuj1-training/chainsaw-test.yamltests/uat/aws/tests/h100-training-config.yamltests/uat/gcp/tests/h100-training-config.yaml
💤 Files with no reviewable changes (6)
- demos/cuj1-eks.md
- demos/cuj2.md
- demos/cuj2-gke.md
- demos/cuj2-eks.md
- demos/cuj1-gke.md
- demos/ext.md
Comment on lines
+181
to
+183
| 3. **Address Feedback** by pushing new commits (signed per [Developer Certificate of Origin](#developer-certificate-of-origin)): | ||
| ```bash | ||
| git commit -s -m "address review: improve error handling" # external contributors | ||
| # or | ||
| git commit -S -m "address review: improve error handling" # NVIDIA org members / automation | ||
| git commit -m "address review: improve error handling" |
There was a problem hiding this comment.
Add blank line before fenced code block (MD031).
Line 180 contains text, and line 181 immediately starts a code fence without a blank line in between. Markdown linting requires a blank line before fenced code blocks.
📝 Proposed fix
3. **Address Feedback** by pushing new commits (signed per [Developer Certificate of Origin](`#developer-certificate-of-origin`)):
+
```bash
git commit -m "address review: improve error handling"
git push origin your-branch
```🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 182-182: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CONTRIBUTING.md` around lines 181 - 183, Add a blank line before the fenced
code block following the "Address Feedback" paragraph so the markdown linter
MD031 passes; locate the "3. **Address Feedback**" paragraph and insert an empty
line immediately before the triple-backtick fence that opens the bash example
(`git commit -m "address review: improve error handling"`) so the code block is
separated from the preceding text.
Source: Linters/SAST tools
Comment on lines
+9
to
+10
| > Version numbers in the sample requests and responses below (server version, chart versions, driver versions) are illustrative. The authoritative, current versions are in the [Component Catalog](component-catalog.md) and the [Container Images BOM](container-images.md). | ||
|
|
There was a problem hiding this comment.
Broaden the version disclaimer or pin the startup image.
The page still uses ghcr.io/nvidia/aicrd:latest in the local-server snippet below, so the new note does not fully remove version drift. Either scope the disclaimer to setup commands too or switch that example to a pinned tag.
♻️ Suggested wording
-> Version numbers in the sample requests and responses below ...
+> Version numbers in the sample requests, responses, and setup commands below ...🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user/api-reference.md` around lines 9 - 10, The version disclaimer
currently only mentions sample request/response versions but the local-server
setup still uses the floating image tag ghcr.io/nvidia/aicrd:latest; update the
docs/user/api-reference.md by either expanding the existing disclaimer to
explicitly cover setup commands and container image references or change the
local-server snippet to use a pinned tag (e.g., replace
ghcr.io/nvidia/aicrd:latest with a specific version like
ghcr.io/nvidia/aicrd:<pin>) so examples do not drift; ensure the change
references the same snippet that contains ghcr.io/nvidia/aicrd:latest.
Comment on lines
+15
to
+20
| - A GPU-accelerated Kubernetes cluster you can deploy to (EKS, GKE, AKS, or a | ||
| local Kind/KWOK cluster for a dry run). `kubectl` configured to reach it. | ||
| - The `helm` binary on your `PATH` (the default `helm` deployer emits Helm | ||
| commands). | ||
| - About 15 minutes. No NVIDIA hardware is required to generate a recipe or a | ||
| bundle — only the deploy and validate stages touch a real cluster. |
There was a problem hiding this comment.
Clarify the dry-run boundary.
Kind/KWOK can only cover the recipe/bundle portion here; steps 5-6 still need a live GPU-capable cluster. As written, this reads like the entire tutorial can be completed locally, which will strand readers on deployment.
♻️ Suggested wording
-- A GPU-accelerated Kubernetes cluster you can deploy to (EKS, GKE, AKS, or a
- local Kind/KWOK cluster for a dry run). `kubectl` configured to reach it.
+- A GPU-accelerated Kubernetes cluster you can deploy to (EKS, GKE, AKS).
+ `kubectl` configured to reach it. If you want a local Kind/KWOK dry run, you
+ can complete only the recipe/bundle steps; deployment and validation still
+ require a live cluster.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/user/tutorial.md` around lines 15 - 20, Update the wording around the
local cluster sentence to clarify the dry-run boundary: explicitly state that
Kind/KWOK only supports the recipe and bundle generation phases and cannot
perform the deploy or validate stages, and that steps 5-6 (the deploy and
validate stages) require a live GPU-capable cluster (EKS/GKE/AKS or similar)
with kubectl configured; reference the existing phrases "Kind/KWOK",
"recipe/bundle", and "deploy and validate stages" so readers know which steps
cannot be completed locally.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documentation audit cleanup focused on maximum reader value with minimal content: removes cross-file duplication, fixes version drift, trims bloat, adds two missing guides, and makes the audit repeatable as a project skill. Net -1,890 lines across 48 files.
Motivation / Context
A structured audit of all Markdown (README,
docs/persona trees,demos/, and root governance files) found the docs were structurally strong but carried significant duplication and version drift. This PR addresses the findings.Fixes: N/A
Related: N/A
Type of Change
Component(s) Affected
docs/,examples/)demos/, root governance docs,.claude/skills/, UAT comment refsImplementation Notes
Duplication removed (canonical home + cross-link):
.github/copilot-instructions.mdgutted ~880 → 23 lines (now a pointer to AGENTS.md / DEVELOPMENT.md).SECURITY.mdtrimmed 676 → 137 lines; operational verification deep-dive relocated to newdocs/integrator/supply-chain-verification.md.cli-reference,agent-deployment,kubernetes-deployment,validation,recipe-development,data-flow.demos/cuj1-training.md+demos/cuj2-inference.md;demos/ext.mddeleted (subsumed); GKE TCPXO benchmark moved intodocs/integrator/gke-tcpxo-networking.md.Bloat trimmed:
automation.md(-461; removed duplicate CI snippets + stub controller),kubernetes-deployment.md(-250; generic K8s boilerplate),data-flow.md(-267).Drift fixed: version examples marked illustrative (point to Component Catalog / BOM); stale
api-referenceserver + chart versions corrected; one pre-existing broken validator anchor fixed.New docs (Diátaxis gaps):
docs/user/tutorial.md(end-to-end) anddocs/user/bundling.md(bundle how-to), wired into the hub and user index.Style: removed manual TOCs (CONTRIBUTING/DEVELOPMENT, per the repo's auto-anchor rule); fixed
CODE_OF_CONDUCTtemplate placeholder; renamed terse demo files (data/valid/e2e) for discoverability.Skills: prefixed all project skills with
aicr-to avoid collision/improve discovery; addedaicr-auditing-docsto make this audit repeatable.Testing
No Go source changed. Inbound links to renamed/deleted files and removed
SECURITY.mdanchors were verified clean repo-wide.Risk Assessment
Rollout notes: Renamed
demos/*files and the.claude/skills/*directories; any external bookmarks to old paths should update. CI lychee will validatedocs/**anchors on this PR.Checklist
git commit -S)