AGENTS.md - nvsnap documentation

Rules for anyone, person or agent, who adds to or changes nvsnap's documentation under this directory. make check-docs (and the nvsnap docs workflow) enforces the ones a script can check; the rest are for review.

Contents

• Where a document goes
• What every document does
• Numbers
• Figures
• Generated pages
• Before you push

Where a document goes

The top level holds only START-HERE, ARCHITECTURE, RESULTS, GLOSSARY, REFERENCE, README and this file. A new document goes into README.md in the same commit that adds it, with what it answers and its status.

What every document does

• Uses the glossary's words with their meanings, and none of its retired words. A new term goes into the glossary in the same commit.
• Names the code behind a claim by path and symbol (internal/agent/criu_group.go captureOptedIn), not by line number.
• States a rule as the condition and the code that enforces it; states a limit as what is not done.
• Describes a cluster by its hardware ("4x GB300, driver 610"; "H100, EKS with NVMesh storage"), never by its name, and names no internal host, address or personal path.
• Cites no file that is not in this repository, such as a personal agent instructions file.
• When it finds another document that disagrees with the code, adds a row to ARCHITECTURE.md §14 or fixes that document in the same PR.

Numbers

Every number names the hardware, the date and the nvsnap build ("not recorded" when the record does not say), and links the record it comes from. A number with no record is left out. A number found wrong is withdrawn in RESULTS.md, in place, with the reason; it is not silently replaced.

Figures

Review-grade figures follow the NVIDIA Cloud Architecture Diagrams style, through the nvaf-architecture-diagrams skill in .agents/skills/ (copied unchanged from the nvaf repository, as flashbox and bedrock do). Each figure is an SVG drawn by its own script under figures/scripts/, with a light and a dark PNG rendered beside it by figures/scripts/render.sh; a document embeds the SVG with ![alt](figures/<name>.svg). Look at both PNGs before committing, and commit the script, the SVG and the PNGs together. Mermaid is for quick inline sketches. How to regenerate: figures/README.md.

Generated pages

• REFERENCE.md is generated from the Go sources by scripts/docs/reference.py; rerun it after changing an annotation, an environment variable or an agent route.
• Tables of contents are generated by scripts/docs/docs-toc.py between their marker comments; edit the headings, never the list.

Before you push

make -C src/compute-plane-services/nvsnap check-docs

It fails on a broken link, heading anchor or doc path (in documents, code, scripts and the chart), a stale table of contents, a REFERENCE.md that no longer matches the code, and a figure that no longer matches its script. The repository's markdown-lint workflow checks style.