Skip to content

docs: correct site guidance and complete the first-machine walkthrough - #50

Merged
bketelsen merged 1 commit into
mainfrom
docs/site-review-fixes
Oct 6, 2026
Merged

bketelsen merged 1 commit into
mainfrom
docs/site-review-fixes

Conversation

@bketelsen

@bketelsen bketelsen commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

The first-machine guide left readers inside the guest before showing host-side commands, and several pages misstated command behavior or used stale versions. This change makes the walkthrough show successful creation, the translated directory, returning to the host, and where to find logs and recovery help.

  • Correct required create arguments, VM image revision, root-session behavior, log scope, host-share availability, and the writable-home trust qualification. Include --isolated in CLI help and create usage errors.
  • Document arm64 limitations, a passing doctor check, troubleshooting, and uninstall/state retention. Release downloads use the stable releases/latest/download/ names from build: name release archives without the version #51.
  • Link the home page and README to one first-machine walkthrough, keep the Podman example in the machines guide, and keep local image build examples in the contributor guide. Add terminology, guide/reference links, navigation cards, and decorative image alt text.

Review decisions: the factual findings and first-run improvements are sound. Keep Homebrew first: the live tap cask already installs v0.7.0, matching the latest release; remove the obsolete future-availability wording instead. The short requirements-table row renders correctly, so its change is only source formatting. The existing desktop-lifetime wording remains correct.

Validation: make site (strict), mise exec -- make ci (including race tests and cross builds), compiled CLI help inspection, rendered HTML checks for table structure/troubleshooting links/decorative alt, and git diff --check. No image or runtime behavior changes; no VM integration run or visual contrast audit.

Rebased onto main (3c9eeb6), 2026-10-05.

@bketelsen
bketelsen force-pushed the docs/site-review-fixes branch from e83da53 to 8c96fc6 Compare October 6, 2026 00:40
@bketelsen
bketelsen merged commit f2ef6e8 into main Oct 6, 2026
4 checks passed
@bketelsen
bketelsen deleted the docs/site-review-fixes branch October 6, 2026 00:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant