Guide Maintenance Skill

Procedures for keeping the OpenVMM Guide (Guide/src/) in sync with the codebase. The doc-code-sync mapping table is maintained in this skill file; .github/instructions/doc-code-sync.instructions.md contains the instructions and heuristics that are automatically loaded during Copilot code review on *.rs and Cargo.toml files.

Adding a New Guide Page

1. Choose the right location

2. Create the page

• Follow the style in .github/instructions/guide-docs.instructions.md
• Include a brief overview, key concepts, and links to relevant rustdoc
• Reference crate names in backticks
• Use relative paths from repo root when pointing at code

3. Update SUMMARY.md

Add the page to Guide/src/SUMMARY.md in the correct section. Pages with content get a path; placeholder topics for future work get an empty link ().

- [Page Title](./reference/path/to/page.md)

4. Update the doc-code-sync mapping

This is the critical step. Add a row to the mapping table in this file:

| `path/to/code/crate/` | `reference/path/to/page.md` |

Also add a bullet to the "What to Flag" section if the new page covers a category of change (e.g., "New frobulator variant added → update frobulator.md").

Removing or Moving a Guide Page

1. Update or remove the entry in Guide/src/SUMMARY.md
2. Remove or update the corresponding row in the doc-code-sync mapping table
3. Check for cross-references from other Guide pages (grep for the old path)
4. If moving: ensure the SUMMARY.md link and the mapping table both point to

the new location

Adding a New Device Crate

When a new crate is added under vm/devices/:

1. Does it need a Guide page? If it's a user-visible device or backend,

yes. Internal plumbing crates (e.g., resources, protocol) usually don't need their own page but should be mentioned in the parent device page.

1. Create the page following the "Adding a New Guide Page" procedure above.

1. Update the mapping table with the crate path → Guide page.

1. Update the "What to Flag" list if the new crate introduces a new

category of reviewable change.

Adding or Changing CLI Arguments

When openvmm/openvmmentry/src/cliargs.rs changes:

1. Update Guide/src/reference/openvmm/management/cli.md
2. The CLI page has a disclaimer that it may be out of date — keep it honest,

but still update the page when making changes

1. New arguments should include: flag syntax, description, default value,

and any interactions with other flags

Auditing Guide Freshness

To check whether the Guide is in sync with the code:

1. Scan the mapping table in this file
2. For each row, check whether the Guide page content still matches the code:

- Crate names still correct? - Struct/enum names still exist? - Behavioral descriptions still accurate? - Links to rustdoc still resolve?

1. Check Guide/src/SUMMARY.md for placeholder links () — these are

topics that need content. Prioritize ones whose code areas have been actively developed.

Quick audit commands

# Find Guide pages that reference a crate name
grep -r "crate_name" Guide/src/

# Find placeholder topics (empty links) in SUMMARY.md
grep '()\s*$' Guide/src/SUMMARY.md

# Find code crates with no Guide mapping
# Compare vm/devices/*/Cargo.toml crate names against the mapping table

Mapping Table Format

Each row in the mapping table follows:

| `code/path/` | `guide/path.md` |

• Code paths use repo-root-relative paths with trailing / for directories
• Guide paths are relative to Guide/src/
• Multiple Guide pages for one code path: comma-separated
• Use glob-style in code paths for crate families (e.g., nvme/)

Code-to-Guide Mapping

What to Flag

• Changes to the reported build identity -- the -V / --version strings, the

version format, dirty detection, or what a Git-free tree reports -- must update reference/openvmm/management/cli.md, and devguide/contrib/openvmmpackaging.md when the packager-facing contract changes.