Phase 4: OCI import docs

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>
This commit is contained in:
Thales Maciel 2026-04-16 17:37:07 -03:00
parent fdaf7cce0f
commit 2e4d4b14da
No known key found for this signature in database
GPG key ID: 33112E6833C34679
3 changed files with 170 additions and 0 deletions

View file

@ -102,6 +102,19 @@ Or pull a pre-built kernel from the catalog and reference it by name:
See [`docs/kernel-catalog.md`](docs/kernel-catalog.md) for catalog
maintenance.
Or pull a rootfs directly from any OCI registry (Docker Hub, GHCR, …):
```bash
./build/bin/banger image pull docker.io/library/debian:bookworm \
--kernel-ref void-6.12
```
`image pull` downloads the image, flattens its layers into an ext4
rootfs, and registers it as a managed banger image. Experimental — see
[`docs/oci-import.md`](docs/oci-import.md) for current limitations
(notably: file-ownership caveat means pulled images are a base for
`image build`, not yet directly bootable).
Build a managed image from an existing registered image:
```bash