[ozbarshalom]

What type of PR is this?

• documentation

What this PR does / why we need it:

Backports the reworked usage guides to the 0.2 line, so 0.2.0 users get the same flow as main and every command in it works against the 0.2.0 chart: README → guides index → framework guide → checkpoint → restore, and eight recipes (vLLM, SGLang and TensorRT-LLM × Qwen3 0.6B, GLM 5.3 and DeepSeek V4.1 Flash) that follow one naming, model-cache, deadline and probe scheme.

It is the 9 commits of #456 and #656 cherry-picked onto release/0.2, plus twelve 0.2-only commits and one review-feedback commit shared with #656.

The one behavior that differs from main: 0.2.0 has no restore proxy. The proxy binary ships, but the NRI plugin that makes it PID 1 and the no-proxy fallback are main-only. A restore Pod therefore has to run an inert placeholder (/bin/sh -c "exec sleep infinity") and the agent restores the workload beside it. With the main profiles, which keep the source command, SGLang crash-loops on 0.2.0 (engine_args required) and vLLM only passes by winning a race. The 0.2 commits:

• docs(guides): restore with the inert placeholder command that 0.2 requires changes the six restore profiles, restore.md and vllm.md.
• test(e2e): keep the 0.2 inert restore placeholder in the framework manifest tests keeps the manifest tests asserting the placeholder, and keeps the e2e files free of main-only helpers (restore_proxy_on and friends).
• docs(install): install chart version 0.2.0 on the 0.2 line bumps the install command in README.md and docs/operations/install.md from 0.1.0 to 0.2.0, the chart these guides were tested against.
• docs(guides): download the example files without installing envsubst rewrites step 2 of the guides index so it says what the example files are and clones the release/0.2 branch (a plain clone would give main's guides, whose restore profiles do not work on 0.2.0), and replaces the four envsubst commands with sed, which every Mac and Linux machine already has. The output is identical to the commands it replaces.
• docs(guides): drop the clean-up and failure sections from the guides index removes the "Clean up and run again" and "If a step fails" sections of the guides index, and the link to the first from restore.md, which keeps its pointer to the troubleshooting page.
• docs(guides): call the eight-GPU section Multi-GPU recipes and shorten it renames that section of the guides index, because nothing in it is specific to eight GPUs, cuts it to the agent-image command and the first-run timing, and updates the five links to it.
• docs(guides): turn the guides index into one flow you follow top to bottom rewrites docs/guides/README.md so you choose a recipe once, by setting FRAMEWORK, MODEL and GPUS, and every later command (prepare, checkpoint with a PodSnapshot or a SnapshotJob, restore, request) uses that choice, instead of selecting again in each stage and translating from vLLM-only examples. It adds a closing "Use your own engine or image" section that points to the workload contract, and retargets the links from the other pages to the new headings. The engine, checkpoint and restore pages still describe the same steps in more detail and are not reworked here.
• docs(guides): call the workload namespace WORKLOAD_NAMESPACE renames SNAPSHOT_NAMESPACE, which read as the namespace Snapshot is installed in (snapshot) but is the namespace the replicas run in, across the six guide pages, and says so in step 3 of the guides index.
• docs(guides): show the recipe table's variable names as plain column titles is a one-line formatting fix to the new recipe table.
• docs(guides): confirm a restore by its condition instead of an inference request removes the port-forward and /generate request from the guides index and the restore page; a restore is confirmed by the Deployment becoming Ready and the pod's nvidia.com/Restored condition.
• docs(guides): apply the source manifest directly unless the recipe is multi-GPU makes Option A a plain kubectl apply for single-GPU recipes; the sed that fills in the agent image is now a marked replacement command for multi-GPU recipes only.
• docs(guides): tell readers which manifest line to edit instead of piping through sed replaces the remaining sed commands (agent image for multi-GPU source manifests, checkpoint name for restore profiles) with a step that says to open the manifest, shows the exact line to change, and then applies the file as it is. This covers the guides index, the restore page and the three engine pages.
• docs(guides): raise the TensorRT-LLM Qwen3 KV-cache fraction and drop redundant settings addresses review feedback on the TensorRT-LLM single-GPU recipe: TRTLLM_MAX_NUM_TOKENS and TRTLLM_MAX_BATCH_SIZE repeated app.py's defaults and are removed, and TRTLLM_FREE_GPU_MEMORY_FRACTION goes from 0.10 to 0.75, as in the GLM recipes, in both the Deployment and the SnapshotJob. It was run through both options (checkpoint, restore, Restored=True) on an install of the main build, not on a 0.2.0 install.

Which issue(s) this PR fixes:

Refs #627

How was this tested?

On a B200 node, against chart ghcr.io/ai-dynamo/snapshot/snapshot 0.2.0 (agent, operator and PageBroker v0.2.0), following the guide's commands with the guide manifests: source Deployment + PodSnapshot, and SnapshotJob, then restore with the 1-gpu/2-gpu profile, check nvidia.com/Restored=True, and send a /generate request to the restored replica. That request was my own end-to-end check; the guides no longer include it. Every restored replica answered "The capital of Italy is Rome…".

Qwen3 0.6B	1 GPU PodSnapshot	1 GPU SnapshotJob	2 GPU PodSnapshot	2 GPU SnapshotJob
vLLM	pass	pass	pass	pass
SGLang	pass	pass	pass	pass
TensorRT-LLM	pass	pass	pass	pass

The new flow, run from the page, on a 0.2.0 install (chart 0.2.0, agent v0.2.0 with no NRI plugin). A fresh clone of this branch, the commands extracted from the guides index and run in its order, with the "edit this line" steps done by changing the line the page names. Two environment deviations, both in my clone of the repository and not in any step: the model-cache claim points at an existing PVC, because this cluster's Kyverno policy rejects a private PVC named model-cache, and the ConfigMaps are named ozbarshalom-<engine>-app, because the namespace already held incompatible ones. vLLM Qwen3 0.6B at one GPU:

• Option A (Deployment + PodSnapshot): pass, nvidia.com/Restored=True.
• Option B (SnapshotJob): pass, nvidia.com/Restored=True.

Also checked: every relative link and anchor in docs/ and the READMEs resolves, and the e2e unit tests that run offline pass (335; the 2 that need a live cluster were not run).

Not run, so not claimed:

• the eight-GPU recipes (GLM 5.3, DeepSeek V4.1 Flash): no node with 8 free GPUs was available. The two-GPU runs used a tensor-parallel-2 copy of the Qwen3 recipe generated from the 8-GPU manifests, which exercises the same multi-GPU path (annotation, snapshot-cuda-install init container, cuinterpose-launch) but is not those recipes;
• the model-download init container: the model was already in the cache;
• the new single-flow index for SGLang and TensorRT-LLM, and at two GPUs. It was run from the page only for vLLM at one GPU (below); the rest of the plan was stopped. Its commands were syntax-checked, and the three values were checked to derive the right manifests and names for all eight recipes in bash and zsh;
• make check test (macOS host, no Linux toolchain) and the GPU e2e suites.

Special notes for your reviewer:

• Review the twelve 0.2-only commits first; the nine before them are unchanged cherry-picks (-x records the source SHAs) with conflicts resolved toward the PR side.
• app.py keeps 0.2's wording in one comment (stdout of the restored process); main says it is connected to the restore container's log, which is proxy behavior.
• docs/reference/restore-pod-contract.md and docs/limitations.md are untouched: on release/0.2 they already describe the inert-placeholder model.
• The main PRs (feat(examples): document and exercise multi-GPU workloads #456, docs(guides): one flow from README to restore, one pattern for every recipe #656) are unchanged by this; follow-ups that apply only to main will go there separately.

Does this PR introduce an API change?

NONE

Additional documentation, e.g. enhancement proposals, usage docs:

docs/guides/ (index, vllm, sglang, tensorrt-llm, checkpoint, restore)

Checklist

• Commits are signed off (git commit -s), per CONTRIBUTING.md
• make check test passes locally (not run; macOS host. Offline e2e unit tests and a link check were)
• Documentation is updated where behavior changed

Prepared with help from Claude Code.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review: 1

• main

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: ai-dynamo/snapshot/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Enterprise
• Run ID: 168572b2-d32e-4b6c-853a-03ede1609e22

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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