Lead the README with `banger vm run` (one command, auto-pull default
image + kernel from the catalogs), move `image register` / `image
build` / OCI-pull to a "power-user flows" section. Golden-image
content from customize.sh moves to the golden-image Dockerfile story.
New `docs/image-catalog.md` mirrors `docs/kernel-catalog.md` — the
bundle format, content-addressed filenames, publish flow, trust
model, R2 hosting. Cross-links with oci-import.md.
`docs/oci-import.md` refactored to document the OCI-pull path as the
fallthrough for arbitrary registry refs (it's the secondary path now
that the catalog covers the headline debian-bookworm case). Phase A
caveats removed — ownership fixup, agent injection, and first-boot
sshd install all landed.
AGENTS.md: promotes `vm run` as the smoke-test primitive, notes the
default-image auto-pull behaviour, and points at both catalog docs.
README shrinks 330 → 198 lines, mostly by removing the experimental
void/alpine sections (those flows still work as advanced scripts but
the README no longer advertises them).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs/oci-import.md: removed the "Phase A acquisition-only" framing
and the bootability-gap warnings. Expanded architecture section
with ApplyOwnership + InjectGuestAgents. Added a "guest-side boot
sequence" diagram-in-prose showing network → first-boot → vsock-
agent unit ordering. Added a "how to add distro support" section
pointing at the ID-case dispatch in first-boot.sh.
README.md: replaced the experimental-caveat block with an honest
"boots as a banger VM directly, no image build step required"
description. Pointer to the docs for distro support details.
Tech-debt list trimmed — ownership fixup and first-boot install
are no longer planned work, they shipped. What remains: private-
registry auth (authn.DefaultKeychain), cache eviction, first-boot
timeout UX (retry still works but could be smoother with a
FirstBootPending flag), non-systemd distros.
All 20 packages green. make lint clean.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
New docs/oci-import.md covers the full Phase A story:
- end-user flow (kernel pull + image pull + image list)
- what works now (layer replay + whiteouts, path-traversal
hardening, content-aware sizing, layer caching, composition
with image build)
- what does not work yet (direct boot due to ownership
caveat, private registries, non-amd64 platforms)
- architecture of internal/imagepull + the daemon orchestrator
- path layout (OCI cache, staging, published)
- tech debt: the three plausible ownership-fixup approaches
(debugfs, hcsshim/tar2ext4, user namespaces) with honest
trade-offs for Phase B to choose from later
- trust model (digest chain covers transport; signature
verification out of scope)
README.md gains an image pull example alongside image register
+ --kernel-ref, with a pointer to the docs and an honest "pulled
images are a base for image build, not yet directly bootable"
warning.
AGENTS.md gets the one-line note pointing at the new doc.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
