Skip to content

Workflow status is tracked in GitHub: https://github.com/emulebb/emulebb/issues/117. This local document is retained as an engineering spec/evidence record.

FEAT-103 - Publish Windows Hyper-V run guide for eMuleBB

Summary

Publish a user-facing guide for running eMuleBB inside a local Windows Hyper-V guest using the existing workspace VM lab automation. The guide should make the path approachable for users and contributors who want a clean, repeatable Windows test environment without paying for cloud nested virtualization.

The guide should describe the automation as mostly headless VM orchestration: the host prepares, boots, tests, checkpoints, and restores the guest from commands. It must not describe eMuleBB itself as a headless daemon.

Intended Shape

  • Add a current reference guide under docs/reference/.
  • Explain host prerequisites:
  • Windows Pro, Enterprise, or Server with Hyper-V support
  • elevated PowerShell for VM preparation and test execution
  • enough local RAM, disk, and CPU for at least one Windows guest
  • Tell users to provide their own legal Windows ISO.
  • Point users from vm-lab.example.json to an ignored vm-lab.local.json.
  • Show the supported orchestration commands:
  • python -m emule_workspace vm-lab prepare --matrix win10,win11
  • python -m emule_workspace test windows-vm --profile package-helper-install
  • Explain the clean-checkpoint workflow: build once, restore often.
  • Keep the guide clear that first image preparation is slow, while repeat runs are intended to be cheap and mostly unattended.

Scope Constraints

  • Do not bundle, mirror, or link to unauthorized Windows ISO images.
  • Do not add a product promise that eMuleBB is daemon-only or headless.
  • Do not require public-network live tests in the introductory path.
  • Do not make cloud nested virtualization the default recommendation.
  • Do not hardcode machine-specific absolute paths in the guide.

Candidate Implementation Notes

  • Place the canonical guide at docs/reference/GUIDE-HYPERV-WINDOWS.md.
  • Link the guide from the active docs index or another appropriate current navigation point.
  • Add a short pointer from the build repo README only if it does not duplicate the canonical guide.
  • Include troubleshooting for missing Hyper-V commands, non-elevated shells, Windows Home hosts, ISO edition mismatches, and failed checkpoint restores.
  • Use the current supported target matrix, win10,win11, unless the VM profile catalog changes to support narrower matrices.

Acceptance Criteria

  • [x] A current reference guide documents local Hyper-V setup for eMuleBB.
  • [x] The guide clearly states that users must supply their own Windows ISO.
  • [x] The guide uses supported python -m emule_workspace commands.
  • [x] The guide distinguishes headless VM automation from a headless eMuleBB runtime.
  • [x] The guide explains clean checkpoints and repeatable package smoke runs.
  • [x] The guide includes practical troubleshooting for common host and ISO failures.
  • [x] Current documentation checks pass after the guide is added.

Implementation Evidence

  • Added docs/reference/GUIDE-HYPERV-WINDOWS.md as the current user-facing Hyper-V suite isolation guide.
  • Linked the guide from docs/INDEX.md, docs/reference/GUIDE-SETUP.md, and mkdocs.yml.
  • The guide uses the current command contract from repos/emulebb-build: python -m emule_workspace vm-lab prepare, python -m emule_workspace test windows-vm, and python -m emule_workspace test campaign-scenario.

Validation

  • 2026-06-03: python scripts\docs-item-taxonomy-check.py passed with historical status warnings only.
  • 2026-06-03: python scripts\docs-structure-check.py passed with pre-existing wide-table warnings in docs/reference/WORKSPACE-REPO-MAP.md.
  • 2026-06-03: python -m mkdocs build --strict passed; output retained existing informational messages for historical links.
  • 2026-06-03: manual read-through checked the guide from a clean-user perspective against current emulebb-build CLI help and VM profile requirements.