Recommend Apple container for Mac setup (blocked on VS Code Reopen in Container)

Prefer Apple [`container`](https://github.com/apple/container) as the Mac recommendation for the documented VS Code Dev Containers path. It should compete with (and, on Mac, replace) OrbStack and the other Docker-engine hosts. Linux and Windows stay on Docker/Podman/Colima; Apple `container` does not run there.

This is blocked. Stock **Dev Containers: Reopen in Container** does not drive Apple `container`. Upstream tracker:

https://github.com/microsoft/vscode-remote-release/issues/11012

## Why this is the Mac preference

README already states the criterion:

> We would prefer an open-source-licensed Docker implementation that runs at native speed on Mac, Linux and Windows.

Today the Mac line is OrbStack (proprietary, Docker-compatible, fast) with Colima as the slower open-source alternative. Apple `container` 1.4.1 is Apache-2.0, first-party, and runs each Linux OCI image as its own lightweight VM on Apple silicon + macOS 26. That matches the license preference on Mac better than OrbStack. It does not satisfy the cross-platform part of that sentence, so it is a Mac-only recommendation, not a universal Docker replacement.

## Current documented approach

From README:

1. Install VS Code and the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
2. Install a Docker host (Mac: [OrbStack](https://orbstack.dev/)).
3. Run **Dev Containers: Reopen in Container**.

`.devcontainer/devcontainer.json` is the environment:

- Image: `mcr.microsoft.com/devcontainers/ruby:3.3-bookworm` (minor tag matches `.ruby-version`).
- Feature: `ghcr.io/devcontainers/features/node:2` with Node 24 (must stay in sync with `.node-version`). Yarn 4 is via Corepack, not the feature.
- `postCreateCommand`: Corepack → Yarn 4.18.0 → `yarn install --immutable` → `bundle install`.

The non-container path is still valid: `rv` for Ruby (`.ruby-version`) and `fnm` for Node (`.node-version`). `package.json` scripts call `rv run bundle exec …`, so they are written for that host toolchain, not for a Linux image that already has the right `ruby` on `PATH`.

## What works today with Apple `container` (no Docker)

Verified on Apple silicon, macOS 26.6.2, `container` CLI 1.4.1, `container system start --enable-kernel-install`.

OCI run/build:

```sh
container run --rm alpine echo hello
container image pull python:alpine
container build --tag web-test --file /abs/path/Dockerfile .
container run -d --name web web-test
container exec web ls /
container logs web
container stop web
```

`--file Dockerfile` is resolved against the process cwd, not the build context directory. Pass an absolute path.

Bind mounts work, including the `destination=` alias and `readonly`:

```sh
container run --rm \
--mount source="$PWD",destination=/work,readonly \
-w /work \
python:alpine python -c 'open("README.md").read()'
```

This repo's Jekyll site builds and serves from Apple `container` if you skip Dev Containers entirely:

```sh
container run -d --name site-dev --cpus 4 --memory 4G \
--volume "$PWD:/work" --workdir /work \
ruby:3.3.4-bookworm sleep 36000
container exec site-dev bash -lc 'bundle install && bundle exec jekyll build'
container exec site-dev bash -lc 'bundle exec jekyll serve --host 0.0.0.0 --port 4000 --livereload'
```

Guest Ruby is 3.3.4. `bundle exec jekyll build` writes `build/`. The server answers on the container's vmnet IPv4 (`192.168.64.x:4000`). Browser load of that URL shows the site. `127.0.0.1:4000` does not: this `site-dev` was not started with `-p`, and when `-p 8000:8000` / `-p 127.0.0.1:8000:8000` was tested on a Python HTTP server, `publishedPorts` showed in `container inspect` but curl to localhost connected and hung. Curl to the container IP returned 200. Same localhost-vs-IP pattern is reported on the VS Code issue.

Do not document `container machine` for this template. Default `home-mount` is `rw` (Mac `$HOME` at the same path). First `container machine run` after create often fails with `Operation not supported by device`. `alpine:latest` also crashed on missing `/sbin/openrc`; Apple's examples use `alpine:3.22`.

## Where Reopen in Container stops

**Dev Containers: Reopen in Container** is not `container run`. It:

1. Reads `.devcontainer/devcontainer.json`.
2. Talks to a Docker Engine API (unix socket) plus a `docker` CLI.
3. Pulls/builds, creates the container, bind-mounts the workspace.
4. Installs Dev Container Features (this repo's Node 24 is one).
5. Runs `postCreateCommand`.
6. Installs `vscode-server` and reopens the window attached to that guest.

Apple `container` has no Docker socket and no Compose. Setting `dev.containers.dockerPath` / `dockerComposePath` to `container` does not work: the extension speaks Docker's HTTP API and Docker CLI JSON, not Apple's CLI. Without a Docker engine, VS Code reports that Docker is missing (`Docker version 17.12.0 or later required`).

Microsoft's current support, from [vscode-remote-release#11012](https://github.com/microsoft/vscode-remote-release/issues/11012) (Backlog, assigned to @chrmarti):

- Dev Containers 0.424.0-pre-release added **Dev Containers: Attach to Running Apple Container** behind `dev.containers.experimentalAppleContainerSupport`.
- You start the VM yourself (`container run -d … sleep infinity`), then attach.
- `devcontainer.json` is not applied. Features are not installed. `postCreateCommand` is not run. You pick the workspace folder by hand.
- Automatic port discovery is incomplete; forwarding sometimes needs a manual Ports-panel add.
- Attach to `mcr.microsoft.com/devcontainers/…` images has been reported to hang (also discussed in [apple/container#293](https://github.com/apple/container/issues/293)).

That is attach, not Reopen. It is not a replacement for the README's one-command onboarding.

This repo's Node install is a Feature (`ghcr.io/devcontainers/features/node:2`). Features are applied by the Dev Containers toolchain talking to Docker. A plain `container run` of the Ruby image does not install Node 24. Baking Node into a Dockerfile would drop that dependency; that is a possible fallback if the adapter never covers Features.

`yarn build` / `yarn dev` inside a Linux guest will fail unless `rv` is installed there. Those scripts are for the host `rv` path. Inside `ruby:3.3.4-bookworm`, the matching command is `bundle exec …` (same as CI's `ruby/setup-ruby`). Host Yarn PnP (`.pnp.cjs`) is Mac-generated and untracked; do not reuse it in a Linux guest.

## Adapters that exist and are not the template default

| Approach | What it is | Why it is not the README line yet |
|---|---|---|
| [socktainer](https://github.com/socktainer/socktainer) | Docker Engine API v1.51 (partial) on a unix socket in front of Apple `container` | Closest "pretend to be Docker" adapter. API is partial; Reopen + Features against this file is unproven. Extra daemon to install. |
| CLI shims (`docker` → `container`) | Translate some flags | VS Code copies files, execs, watches events, installs Features. A flag translator is too thin. |
| [wcgomes/apple-devcontainers](https://github.com/wcgomes/apple-devcontainers) | Swift CLI that reads `devcontainer.json` and can `--vscode` attach | Third-party; not the stock Reopen command. |
| [Apple Container Manager](https://marketplace.visualstudio.com/items?itemName=Awei-Sumaho.apple-container-manager) | Separate "Reopen" via Remote-SSH | Different config path (`.appcontainer/devcontainer.json`), requires `sshd` in the image. |

## Acceptance

Keep OrbStack (and Colima) on the README until one of these is true:

1. **Dev Containers: Reopen in Container** against this `.devcontainer/devcontainer.json` works with only Apple `container` (and whatever Microsoft ships). Features install Node 24. `postCreateCommand` runs. The window attaches at the workspace mount. Tracked on [vscode-remote-release#11012](https://github.com/microsoft/vscode-remote-release/issues/11012).
2. Or a Docker-socket adapter (socktainer or equivalent) is complete enough that the same Reopen path works, and we are willing to document installing that adapter.

Then:

- README Mac Docker-host sentence recommends Apple `container` (`brew install container` or Apple's signed pkg, then `container system start`).
- Document that you talk to published services on the container IPv4 until localhost `-p` is reliable.
- Keep the `rv` / `fnm` host path for people who do not want a container.
- Linux/Windows still recommend a Docker engine.
- Do not document `container machine` for this project.

Until the blocker lifts, do not change the OrbStack recommendation. The CLI recipe above is a verified Mac alternative, not a substitute for Reopen.

Start with the README and .devcontainer/devcontainer.json, then read the linked vscode-remote-release#11012 tracker. Verify whether Reopen in Container supports Apple container, including the Node 24 Feature and postCreateCommand. Done means the acceptance criteria are met without changing the OrbStack recommendation prematurely.

Written by the indexing model from the issue text.