nvx-rs slimming 5.2.2: the CLI, developer, CI and rustdoc docs, and the migration guide #1131

Parent: #1090, in #1076. Needs: #1091, #1105, #1111, #1112, #1113, #1114, #1119, #1120, #1123, #1124, #1126, #1127, #1129, #1130. Unblocks: #1132. No PR of this group merges before the API-ready commit.

Goal. The rest of the docs match one package: one CLI reference; build, distribution and project-structure docs; features, profiles, the binary matrix, caches, provenance and licenses; CI, contribution and automation docs; a final rustdoc pass with regenerated diagrams; and doc/migrate-from-alpha.7.md. Developers can build and package NVX, and the rustdoc agrees with the final public API.

Notes.

• The final rustdoc pass doesn't excuse earlier PRs from keeping rustdoc right.

PRs, in order. Each PR has one goal, leaves dev green, and names in its description each old test of its area as kept, rewritten or retired, with each change that check_test_changes.py reports. Its tests follow the repository's test layout: a module's unit tests, and the code that only they use, sit in its tests.rs or tests/ and move with it. The estimates count core lines (code, not comments, docs or tests) and counted files; each PR records its measured values. Each PR does what its Scope says and no more: a case, input or layout that its Scope doesn't name, and whatever "Not in this PR" lists, is out of scope. Address every review comment within the scope, and ask before acting on one that asks for more. A PR whose measured core lines pass the stop that its Estimate names (twice the estimate, at most 600) stops and asks before continuing.

1. SL6.10d: Runtime users have one CLI reference.

   • Objective: Runtime users get one consistent CLI reference for the final commands and state model. The documents stop presenting removed raw-restore, buffered-exec and upgrade compatibility behavior as supported.
   • Contents: doc/run.md and the runtime part of doc/usage.md: run, sandbox, snapshots, the refused raw restore, a restore's own network policy, whose DNS and listeners the guest applies before the host releases its input, the exec lock, v2's streamed execs in place of today's buffered output, the RAM upper's cap, and fresh state on upgrade.
   • Scope:
     • Update only doc/run.md and the runtime-command portions of doc/usage.md.
     • Document final run, sandbox, snapshot capture and strict-snapshot restore workflows.
     • Document refusal of raw restores, a restore's own network policy, and guest application of its DNS and listeners before host input is released.
     • Document the per-sandbox exec lock, streamed v2 stdin/stdout/stderr, the RAM upper's cap and fresh state on upgrade.
   • Not in this PR:
     • Build, packaging, project-structure, CI or contribution documentation: SL6.10e and SL6.10f own those documents.
     • New CLI commands, options, compatibility modes or output guarantees.
     • Raw snapshot instructions or a migration path that makes raw restores supported.
     • A second runtime guide, command generator or wholesale rewrite of non-runtime doc/usage.md sections.
     • Library API examples or guest-agent guidance covered by SL6.10a and SL7.9.
   • Approach: Reconcile the two named documents against the final CLI command surface, keeping one canonical explanation and linking rather than duplicating long procedures. Remove obsolete runtime behavior only in their runtime sections. Do not add a generated CLI reference, preserve unsupported compatibility text or broaden the edit to unrelated script commands.
   • Done when:
     • The two named documents agree on run, sandbox, strict snapshots and upgrade state.
     • Raw restore refusal, restore network-policy ordering, the exec lock, streamed executions and the RAM upper's cap are documented.
     • No changed runtime section describes buffered v2 output or reusable pre-upgrade state.
     • The repository Markdown-link check passes.
   • Needs: SL3.8b, in nvx-rs slimming 3.2.2: the CLI captures and restores named snapshots #1114; SL3.9, in nvx-rs slimming 3.1.6: a managed sandbox run, and one exec at a time #1111; SL3.10b, in nvx-rs slimming 3.1.7: the CLI uses only the new interface #1112; SL4.3, in nvx-rs slimming 3.2.1: NVXC asks for a capture and activates a restore, and a blocking driver restores #1113; SL4.4d, in nvx-rs slimming 5.1.2: NVXC v1 and FEATURES are gone #1129; SL6.8c, in nvx-rs slimming 4.3.3: the error codes are private #1126; SL7.8b, in nvx-rs slimming 4.2.4: the exec engine, the process modules and the old layered init are gone #1123.
   • Estimate: 0 core lines (docs), no counted files.

2. SL6.10e: Developers can build and package NVX.

   • Objective: Developers can build, package and navigate NVX from its maintained documentation. The documented package, feature, profile, binary, artifact and provenance layout matches what CI and release tooling actually consume.
   • Contents: Build, distribution and project-structure docs; the guest image and setup READMEs; the nvx package, features, profiles, the lockfile, the binary matrix, caches, provenance and licenses; and installing the guest tools from the package with --profile guest. It covers what dev added: the sandbox scratch template in the binary matrix, the caches and provenance, and the Python package that sets up development hosts and CI runners.
   • Scope:
     • Update doc/build.md, doc/distribution.md and doc/project-structure.md for the nvx package.
     • Update the Azure Linux and Ubuntu guest support pages under doc/guests/, plus scripts/setup/README.md and its runner-provisioning README.
     • Document the package's features, Cargo profiles, lockfile, binary matrix, build output, caches, provenance and license inputs.
     • Include the sandbox scratch template in the binary matrix and describe the existing Python runner-setup package.
     • Document installing the guest tools from nvx with --no-default-features --features guest --profile guest.
   • Not in this PR:
     • New build or setup documents beyond the named existing pages.
     • CLI runtime reference, CI workflow policy or migration guidance: SL6.10d, SL6.10f and SL6.10h own those topics.
     • Changing build scripts, package contents, profiles, caches or provenance behavior to fit the prose.
     • Rewriting guest usage material unrelated to image construction and setup.
     • Adding another package manager, package layout or binary target not present in the final repository.
   • Approach: Update the named documents from the final manifest, package layout and setup scripts, using fixed feature, profile and binary tables where the repository has a fixed set. Preserve valid source-delivery and licensing material. Document the package-based guest-tool install directly; do not create a generated inventory, redesign packaging or rewrite unrelated guest documentation.
   • Done when:
     • The named build, distribution, structure, guest-image and setup documents match the final package paths.
     • Features, profiles, the lockfile, binary matrix, caches, provenance and licenses are covered.
     • The scratch template and Python runner-setup package appear in the appropriate existing sections.
     • The guest tools' package-based install uses the guest profile.
     • The repository Markdown-link check passes.
   • Needs: SL1.5, in nvx-rs slimming 1.1.1: the public API is checked, and NVX's programs are hidden from it #1091; SL6.4, in nvx-rs slimming 4.3.1: image staging, artifact discovery, the policy-file reader and the mount syntax are private to the CLI #1124; SL7.8b, in nvx-rs slimming 4.2.4: the exec engine, the process modules and the old layered init are gone #1123.
   • Estimate: 0 core lines (docs), no counted files.

3. SL6.10f: CI and the repository's automation give the right workflow.

   • Objective: Contributors and maintainers have accurate instructions for the final test ownership, gate commands, automation and publishing flow. The documentation no longer directs changes through the deleted adapter or superseded CI paths.
   • Contents: The CI and contribution docs, the repository instructions and the affected operational skills: test ownership, gate commands, the public-API check and its snapshots, and publishing. It starts from today's CI: OpenVMM's own CI and check-openvmm-ci, the merge queue and its superseded groups, the reusable packaging workflow, and publishing split between pushes and full runs.
   • Scope:
     • Update doc/ci.md, doc/contribute.md and the repository instructions for the final package and test ownership.
     • Update only the affected operational skills under .github/skills/ whose gate or publishing instructions changed.
     • Document current gate commands, the public-API check and snapshot updates, OpenVMM's separate CI and check-openvmm-ci, merge-queue handling of superseded groups, and the reusable packaging workflow.
     • Document publishing differences between pushes and full scheduled or dispatched runs, including that only nvx is published.
   • Not in this PR:
     • New CI jobs, actions, skills or publishing mechanisms: this PR documents the final automation.
     • Rewriting unaffected operational skills or repository instructions.
     • Runtime, build, architecture or migration documentation owned by the other documentation PRs.
     • Restoring adapter gates or commands removed by SL5.2.
     • A generalized CI handbook beyond this repository's named workflows and commands.
   • Approach: Trace the final workflows, actions and scripts, then edit only the named CI, contribution, repository-instruction and affected skill sections. Prefer exact existing commands and links, including the public-API snapshot command. Do not change automation to match stale text, add skills or duplicate workflow documentation across every skill.
   • Done when:
     • The named documents assign each retained test and gate, including the public-API snapshot check, to its final owner and command.
     • OpenVMM CI, superseded merge groups, reusable packaging and push-versus-full-run publishing are described accurately.
     • No affected instruction or skill refers to the deleted adapter.
     • The repository Markdown-link check passes.
   • Needs: SL5.2, in nvx-rs slimming 4.1.2: the test adapter is gone #1119; SL7.8b, in nvx-rs slimming 4.2.4: the exec engine, the process modules and the old layered init are gone #1123.
   • Estimate: 0 core lines (docs), no counted files.

4. SL6.10g: The rustdoc agrees with the final public API.

   • Objective: The public Rust documentation and module diagrams describe exactly the final public API after all privatization and deletions. Links, examples and nightly diagram publication continue to work from the final module locations.
   • Contents: A final pass over public terms, links and examples; the diagram generator's scope and its regenerated diagrams. It doesn't excuse earlier PRs from keeping the rustdoc right. Its scope covers the final public modules, omits NVX's private program code, and keeps the diagrams' nightly publication.
   • Scope:
     • Make a final rustdoc pass over nvx's public terms, intra-doc links and examples.
     • Cover the final public modules, caller-owned responsibilities and removed supervisor, while omitting NVX's private program code from the public narrative.
     • Update scripts/module_diagrams.py only for the final diagram scope, then regenerate the files under doc/modules/.
     • Keep .github/workflows/module-diagrams.yml publishing the generated diagrams nightly.
   • Not in this PR:
     • New public APIs, module moves or compatibility aliases: earlier implementation PRs establish the crate graph.
     • A new diagram generator, renderer or documentation site.
     • Hand-editing generated diagrams instead of regenerating them.
     • Unrelated prose guides or design rewrites owned by SL6.10a through SL6.10f.
     • Deferring rustdoc fixes that earlier code PRs require; this is only the final consistency pass.
   • Approach: Run the existing rustdoc and diagram paths against the final package, fix stale terms and links at their sources, adjust the generator's fixed public-module inventory, and regenerate its checked-in outputs. Keep the nightly workflow and generator architecture; do not introduce discovery, a new rendering pipeline or unrelated API examples.
   • Done when:
     • Rustdoc builds for nvx with its public links and examples checked.
     • No rustdoc term or link names a removed module as current API.
     • scripts/module_diagrams.py regenerates the diagrams in its final scope without manual edits.
     • The nightly module-diagram workflow still publishes the regenerated set.
   • Needs: SL6.8c, in nvx-rs slimming 4.3.3: the error codes are private #1126; SL6.11a, in nvx-rs slimming 4.2.4: the exec engine, the process modules and the old layered init are gone #1123; SL6.11b, in nvx-rs slimming 4.2.4: the exec engine, the process modules and the old layered init are gone #1123; SL6.11c, in nvx-rs slimming 4.2.1: the code that stays stops using what leaves #1120; SL6.12, in nvx-rs slimming 4.3.4: NVXC, the host's platform layer and the guest's space are private #1127; SL6.13b, in nvx-rs slimming 4.3.4: NVXC, the host's platform layer and the guest's space are private #1127; SL6.13c, in nvx-rs slimming 4.2.1: the code that stays stops using what leaves #1120; SL6.14, in nvx-rs slimming 4.3.4: NVXC, the host's platform layer and the guest's space are private #1127; SL7.3, in nvx-rs slimming 2.4.2: activation holds no fence, and a capture is one guest call #1105; SL7.4b, in nvx-rs slimming 2.4.2: activation holds no fence, and a capture is one guest call #1105.
   • Estimate: 0 core lines (docs), no counted files.

5. SL6.10h: Users know what the release breaks.

   • Objective: Users upgrading from alpha.7 get one bounded migration guide for every intentional break in the release. They can map features and APIs, understand the hidden program entry points, identify caller-owned responsibilities, discard incompatible state and pin the new artifacts correctly.
   • Contents: doc/migrate-from-alpha.7.md: the features and hidden program entry points, the API crosswalk, the caller's obligations, the incompatible records, keys and snapshots, fresh state on upgrade, and the install pins.
   • Scope:
     • Add only doc/migrate-from-alpha.7.md.
     • List the final feature changes and hidden program entry points, with an API crosswalk from alpha.7 names to replacements or removals.
     • Summarize caller obligations moved out of the library, including durable state, path and image policy, locking, I/O, timing and recovery.
     • State that old records, keys and snapshots are incompatible and that upgrade starts with fresh state.
     • Give the documented Cargo and installation pins for the one release version.
   • Not in this PR:
     • Compatibility shims, readers or converters for alpha.7 records, keys or snapshots.
     • Migration guides from other versions or additional release-note documents.
     • A repeat of the full library, CLI, build or architecture guides; link to those final documents.
     • Promises of backward compatibility or in-place state upgrade that the release does not provide.
     • New features, entry points or install methods beyond those shipped by the release.
   • Approach: Write one task-oriented crosswalk from the final manifest, APIs and guides, grouping breaks by features, hidden entry points, calls, caller obligations and state. Link to authoritative final documents instead of copying them. Use explicit removed/replaced entries and a fresh-state warning; do not build a compatibility table generator or speculate about unshipped migrations.
   • Done when:
     • doc/migrate-from-alpha.7.md covers features, hidden entry points, the API crosswalk, caller obligations, incompatible state and install pins.
     • Every crosswalk entry names a final replacement, caller responsibility or removal.
     • The guide clearly requires fresh state rather than conversion of old records, keys or snapshots.
     • The repository Markdown-link check passes.
   • Needs: SL6.10a, in nvx-rs slimming 5.2.1: the library's guide, its design and the guest-agent guidelines #1130; SL6.10b, in nvx-rs slimming 5.2.1: the library's guide, its design and the guest-agent guidelines #1130; SL6.10c, in nvx-rs slimming 5.2.1: the library's guide, its design and the guest-agent guidelines #1130; SL6.10d, above; SL6.10e, above; SL6.10f, above; SL6.10g, above; SL7.9, in nvx-rs slimming 5.2.1: the library's guide, its design and the guest-agent guidelines #1130.
   • Estimate: 0 core lines (docs), no counted files.

Tests. The Markdown-link check passes. Rustdoc builds with links and examples checked. The diagram generator regenerates its diagrams. Packaging docs and checks cover nvx, its features and profiles, and installing the guest tools from the package with the guest profile.

Done when: every PR above has merged, with dev green.