fix(setup): document the Docker CLI and plugin paths the socket allowlist misses

[potiuk]

The Docker / Podman command fails with a socket error recipe cannot produce a working docker. It has three gaps — one on every platform, two specific to macOS with Docker Desktop.

1. allowUnixSockets — every platform

Listing a socket in sandbox.filesystem.allowRead grants permission to read the file, not to connect to it. Socket connections are gated by the separate sandbox.network.allowUnixSockets list, which the recipe never mentions. With the path allowed for reading but absent from that list:

$ docker ps
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

This is not macOS-specific — a Linux adopter on /var/run/docker.sock hits it identically. As published, the recipe could not produce a working docker on any platform.

2. The CLI itself — macOS

Docker Desktop installs the docker binary inside the denied directory:

docker (on PATH) = ~/.docker/bin/docker -> /Applications/Docker.app/Contents/Resources/bin/docker

Denied, the shell cannot execute it at all — operation not permitted: docker, before the socket is ever consulted.

3. The CLI plugins — macOS

Allowing ~/.docker/bin/ gets docker ps working, so it looks fixed. But docker compose and docker buildx are not builtins — they are plugin binaries under ~/.docker/cli-plugins/, also inside the denial:

$ docker ps
CONTAINER ID   IMAGE ...          # works

$ docker compose version
docker: unknown command: docker compose

Any compose-driven workflow stays broken, which reads as a Docker Desktop fault rather than a sandbox one.

Symptom section

The listed symptoms were all "daemon not running" errors. None of the three failures above produces one, so an adopter had nothing to match against and no reason to land on this entry. All three forms added.

Verification

macOS 26, Docker Desktop, server 29.7.2.

	before	after
docker ps	operation not permitted: docker	exit 0
docker compose version	unknown command	v5.5.1
docker buildx version	unknown command	v0.36.1
~/.docker/config.json	denied	still denied

Gap 1 was isolated by removing allowUnixSockets while leaving the allowRead socket paths in place: docker compose version still ran — the plugin binary never touches the daemon — while docker ps failed at connect. Restoring it fixed docker ps with nothing else changed, which is what distinguishes the two permissions.

The credential denial is unaffected throughout: docker emits a benign Error loading config file warning and works normally, preserving the intended split — Bash may use the socket, the agent may not read the tokens.

prek run --files docs/setup/sandbox-troubleshooting.md: all green.

---

Generated-by: Claude Code (Opus 5)