docs: Mac bridge soft-link guide (cloud agent ↔ Mac mini M4)

[FluffyAIcode]

What

Adds docs/mac-bridge.md — a consolidated, reader-friendly guide to the "soft link" between a Linux cloud agent (no Apple Silicon) and the local Mac mini M4 runner. The link is pure git-bus: no socket / SSH / VPN / tunnel — git is the wire, the Actions runner is the executor, the request branch is the session.

The guide covers:

• Why (the C1–C4 constraints: no inbound path to the Mac, ephemeral git-native agents, allowlist-only command surface, on-device evidence gate).
• Architecture at a glance — an end-to-end request/response flow diagram (agent → push → mac-bridge.yaml on kakeya-mac-m4 → results pushed back → agent fetch).
• The five components (client, manifest+allowlist, request manifest, executor, runner).
• Security model (fixed-argv presets, typed/bounded params, trigger surface = existing push population, on-device evidence gate, single-Mac concurrency).
• Quickstart for both sides (kakeya_mac.py doctor/run/status; setup_mac.sh).
• Current preset allowlist (snapshot; manifest.py is the contract).
• Roadmap boundary: M1 git-bus (now) / M2 tailnet-SSH / M3 fleet capability, with the hard rule WAN = control + tool plane, LAN = data plane.

It is the entry-point complement to the existing deeper docs, which are cross-linked:

• docs/design/mac-bridge-cloud-agent-access.md (transports + fleet-integration evaluation)
• docs/ops/mac-m4-runner-setup.md (operator setup)

Files

• docs/mac-bridge.md (new guide)
• docs/design/mac-bridge-cloud-agent-access.md (top-of-doc pointer to the new guide)
• README.md (Mac-bridge bullet now links the guide)

Testing

• ✅ Markdown sanity: code fences balanced; all relative links resolve (scripts/mac_bridge/, manifest.py, mac-bridge.yaml, design doc, ops doc).
• Docs-only change; content verified against the live implementation (manifest.py presets/bounds, mac-bridge.yaml flow).