guide-maintenance

name	guide-maintenance
description	Maintain the OpenVMM Guide and its code-sync mapping. Load when: (1) adding, removing, or moving Guide pages, (2) adding new device crates or CLI args that need doc coverage, (3) updating the doc-code-sync mapping table, or (4) auditing Guide freshness against code changes.

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

Content type	Path pattern
Emulated device reference	reference/emulated/<DeviceCategory>/<device>.md
VMBus device reference	reference/devices/vmbus/<device>.md
Virtio device reference	reference/devices/virtio/<device>.md
Device backend reference	reference/backends/<category>.md
Architecture deep-dive	reference/architecture/openvmm/ or reference/architecture/openhcl/
CLI / management	reference/openvmm/management/
Developer tool	dev_guide/dev_tools/<tool>.md
Test framework	dev_guide/tests/

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.

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

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

4. Update the "What to Flag" list if the new crate introduces a new category of reviewable change.

---

Adding or Changing CLI Arguments

When openvmm/openvmm_entry/src/cli_args.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
3. 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?
3. 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

Code path	Guide page
openvmm/openvmm_build_info/	reference/openvmm/management/cli.md

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 dev_guide/contrib/openvmm_packaging.md when the packager-facing contract changes.