Day-0 prerequisites lack macOS container-runtime alternatives

Context

First-real-world cloud-deployment exercise on macOS (Apple Silicon) hit two prerequisite-table gaps immediately: the operator had no container runtime installed, and brew's docker + docker-compose formulae do not auto-wire the docker compose (no-dash) plugin path that every example in the Day-0 Tutorial and surrounding cloud-deployment guides assumes.

Both gaps are documentation, not substrate — the deployment works once they're resolved — but they block first-run on the most common 2026 macOS dev surface.

The Problem

Gap 1: Container-runtime alternatives are not surfaced

Day0Tutorial.md Prerequisites table (line 43) lists Docker Compose only:

Day0Tutorial.md Failure signatures table (line 49) lists exactly one fix:

docker: command not found → Install Docker Desktop / Docker Engine or run the tutorial on a Docker-capable host.

No mention of Colima (the open-source Docker-compatible runtime that has become the de-facto macOS dev choice given Docker Desktop's commercial licensing posture), Podman, OrbStack, or any other Docker Engine-equivalent.

Grep across learn/agentos/cloud-deployment/ + ai/deploy/ confirms zero matches for colima, podman, or orbstack (V-B-A).

Gap 2: macOS brew compose-plugin wiring is undocumented

Installing docker + docker-compose via brew on macOS does NOT auto-create the ~/.docker/cli-plugins/docker-compose symlink that docker compose (no-dash) resolution depends on. The docker-compose (dash) binary works standalone, but every example in Day0Tutorial.md, PipelineWiring.md, ai/deploy/Caddyfile, and ai/deploy/docker-compose.yml uses the no-dash form.

A first-run user on macOS sees docker: unknown command: docker compose after brew install docker docker-compose and has no signpost from the guide that the symlink fix exists:

mkdir -p ~/.docker/cli-plugins
ln -sf /opt/homebrew/bin/docker-compose ~/.docker/cli-plugins/docker-compose

This is a known macOS+brew quirk but is not currently captured in the substrate.

The Architectural Reality

Affected files (verified at dev HEAD via grep):

• learn/agentos/cloud-deployment/Day0Tutorial.md — Prerequisites + Failure signatures tables (lines 39-51).
• Cross-cutting reference: learn/agentos/cloud-deployment/PipelineWiring.md uses docker compose (no-dash) form throughout; same form in ai/deploy/Caddyfile:9 and ai/deploy/docker-compose.yml:5,131. These need to stay consistent — the Day-0 fix is to make the prerequisite-to-form linkage discoverable, not to switch idioms.

Pure documentation surface — no code or compose changes required.

The Fix

1. Expand the Day-0 Tutorial Prerequisites section with a runtime-choice subsection:

   • List Docker Desktop, Colima, Podman, OrbStack as supported runtimes; brief one-line description + install hint per row.
   • Explicit pointer to the canonical docker compose (no-dash) form that all examples use.

2. Add a Day-0 Tutorial Failure signatures row for the macOS brew quirk:

   | docker: unknown command: docker compose | brew did not wire the compose plugin path. | mkdir -p ~/.docker/cli-plugins && ln -sf /opt/homebrew/bin/docker-compose ~/.docker/cli-plugins/docker-compose |

3. Optional: a one-line sizing hint near the prerequisites pointing at Colima's colima start --cpu N --memory N (Memory Core primary store + Chroma + KB + MC + orchestrator + Ollama embedding model needs ~16 GiB VM minimum; ~24+ GiB once chat models like Gemma 4 31B are loaded).

The implementing PR may choose to inline this into Day-0 or factor out a sibling "Local Dev Setup" guide that Day-0 cross-references — either shape satisfies the AC.

Contract Ledger

Decision Record impact

none — pure documentation enhancement under existing ADR 0014 cloud-topology authority.

Acceptance Criteria

• A first-run macOS user without a pre-installed container runtime can discover Colima (or an equivalent open-source alternative) from Day0Tutorial.md Prerequisites without leaving the guide tree.
• Day0Tutorial.md Failure signatures table includes a row matching the brew compose-plugin symptom (docker: unknown command: docker compose) with the cli-plugins symlink fix.
• No claim that one specific runtime is "required" — the guide remains runtime-agnostic.
• grep -ri 'colima' learn/agentos/cloud-deployment/Day0Tutorial.md returns at least one hit (regression guard).
• If a sibling guide is factored out, Day0Tutorial.md cross-references it from the Prerequisites section.

Out of Scope

• Per-runtime install scripts or automation. The guide lists options; operators choose.
• Linux-host runtime alternatives (rootless Podman, etc.) beyond a mention. The macOS surface is the immediate friction.
• CI/CD runtime guidance — that's PipelineWiring.md scope, not Day-0.
• Resource-sizing benchmarks beyond a single sizing hint.

Avoided Traps

• Recommending Colima as a hard default in the substrate — rejected; this is a docs gap, not a policy mandate. Linux servers, ARM clouds, etc. should keep their existing runtime.
• Inlining the symlink fix at every docker compose usage site — rejected; single-source-of-truth in the Prerequisites section + failure-signature row.
• Filing as a bug — rejected; the guide is functional for users who already have Docker installed, and the gap is additive documentation rather than incorrect content.

Related

• #12014 — sibling first-real-world deployment friction (orchestrator co-location follow-up). Both surfaced by the same external-deployment exercise.
• ADR 0014 — cloud-deployment topology (substrate authority for the guide tree).
• learn/agentos/cloud-deployment/Day0Tutorial.md — primary fix surface.

Handoff Retrieval Hints

• Grep: grep -rni 'colima\|podman\|orbstack' learn/agentos/ ai/deploy/ — pre-fix returns zero matches; post-fix returns at least the prereq table.
• Semantic: "Day-0 prerequisites macOS container runtime", "Colima docker compose plugin brew symlink".
• File anchor: learn/agentos/cloud-deployment/Day0Tutorial.md:39-51 (the Prerequisites + Failure signatures tables).