feat: CLI/core split — shim + versioned core binary

[donbader]

Summary

Replace the Go CLI binary with a POSIX shell shim that auto-downloads and delegates to a versioned core binary. Core becomes the primary release artifact.

Architecture

User runs agent-sandbox <cmd>
        │
        ▼
┌─────────────────────────────┐
│  Shim (~/.agent-sandbox/bin)│
│  POSIX shell, ~80 lines    │
├─────────────────────────────┤
│  Owns: upgrade, version    │
│  Everything else → core    │
└──────────────┬──────────────┘
               │ resolve version → download/cache → exec
               ▼
┌─────────────────────────────┐
│  Core Binary (Go)           │
│  agent-sandbox-core         │
├─────────────────────────────┤
│  init, generate, compose,   │
│  gateway-url, audit         │
└─────────────────────────────┘

What Changed

• scripts/shim.sh — POSIX shell version-resolving shim (the new agent-sandbox command)
• scripts/install.sh — curl | sh installer
• cmd/agent-sandbox-core/ — new Go binary with all real CLI logic (no release fetching, resolves assets from own directory)
• cmd/agent-sandbox/main.go — upgrade command becomes migration to shim (v1.27.0 final release)
• internal/release/fetcher.go — cache aligned to ~/.agent-sandbox/core/
• .github/workflows/core-release.yml — builds 4 platform-specific tarballs with host binary
• .github/workflows/shim-release.yml — tags shim versions
• .github/workflows/ci.yml — builds + tests core binary, shellcheck for scripts
• docs/ — full documentation update (getting-started, cli reference, migration guide, architecture)

Migration Path

Existing users run agent-sandbox upgrade (v1.27.0) which installs the shim. After updating PATH and removing the old binary, they're on the new system.

What's NOT in this PR

• Task 10 (removing old cmd/agent-sandbox/ and GoReleaser workflow) — happens after migration period
• Checksum verification for downloads — future enhancement

Testing

• Both binaries build: go build ./cmd/agent-sandbox/ and go build ./cmd/agent-sandbox-core/
• All existing tests pass: go test ./...

Spec: docs/superpowers/specs/2025-06-09-cli-core-split-design.md
Plan: docs/superpowers/plans/2025-06-09-cli-core-split.md