@@ -0,0 +1,111 @@
+---
+name: sandbox-fetch-docs
+description: Use when needing to verify implementation against official library docs, check API contracts, or look up how a dependency works — especially after bugs caused by wrong assumptions about a library's API. Triggers on "check the docs", "verify against docs", "official documentation", "how does X API work", "canonical implementation".
+metadata:
+  author: Serge Gatezh
+  url: https://github.com/gatezh
+  version: "1.0.0"
+---
+
+# Fetch Documentation in Sandbox
+
+## Overview
+
+This sandbox only has network access to GitHub and npm registry. All other domains (vendor doc sites, CDNs, search engines) are firewalled. Use these approaches in priority order — do NOT attempt blocked approaches.
+
+## Approach Priority
+
+```dot
+digraph fetch_docs {
+  rankdir=TB;
+  "Need library docs?" [shape=doublecircle];
+  "Installed in node_modules?" [shape=diamond];
+  "Read local source + types" [shape=box, style=filled, fillcolor="#d4edda"];
+  "Public repo on GitHub?" [shape=diamond];
+  "Fetch via raw.githubusercontent.com" [shape=box, style=filled, fillcolor="#d4edda"];
+  "Browse via GitHub Contents API" [shape=box, style=filled, fillcolor="#d4edda"];
+  "Need package metadata?" [shape=diamond];
+  "Query npm registry" [shape=box, style=filled, fillcolor="#d4edda"];
+  "Ask user for help" [shape=box, style=filled, fillcolor="#fff3cd"];
+
+  "Need library docs?" -> "Installed in node_modules?";
+  "Installed in node_modules?" -> "Read local source + types" [label="yes"];
+  "Installed in node_modules?" -> "Public repo on GitHub?" [label="no"];
+  "Read local source + types" -> "Public repo on GitHub?" [label="need more context"];
+  "Public repo on GitHub?" -> "Fetch via raw.githubusercontent.com" [label="know file path"];
+  "Public repo on GitHub?" -> "Browse via GitHub Contents API" [label="need to discover files"];
+  "Public repo on GitHub?" -> "Need package metadata?" [label="no repo"];
+  "Fetch via raw.githubusercontent.com" -> "Need package metadata?" [label="need more"];
+  "Browse via GitHub Contents API" -> "Fetch via raw.githubusercontent.com" [label="found path"];
+  "Need package metadata?" -> "Query npm registry" [label="yes"];
+  "Need package metadata?" -> "Ask user for help" [label="no"];
+}
+```
+
+## 1. Installed node_modules (fastest, always works)
+
+The definitive source for how a library behaves at the exact version you're using:
+
+```bash
+# Find the package (Bun layout — other managers use different paths, e.g. node_modules/PACKAGE)
+find node_modules/.bun -path "*PACKAGE_NAME*" -type d -maxdepth 3
+
+# Read type definitions (the API contract)
+# Look for index.d.mts, index.d.ts, or index.d.cts
+Read: node_modules/.bun/PACKAGE@VERSION/node_modules/PACKAGE/dist/index.d.mts
+
+# Read source implementation (how it actually works)
+Grep: pattern in node_modules/.bun/PACKAGE@VERSION/node_modules/PACKAGE/dist/index.mjs
+```
+
+**When to use:** Always start here. Types show the API contract, source shows the implementation. This is more reliable than docs which may be outdated or describe a different version.
+
+## 2. Raw GitHub content (no auth needed)
+
+Fetch files directly from public repos via `raw.githubusercontent.com`:
+
+```bash
+# WebFetch or curl — both work
+WebFetch: https://raw.githubusercontent.com/OWNER/REPO/BRANCH/path/to/file.ts
+
+# Common branches to try: main, master, canary
+# Example: Resend SDK email handling
+WebFetch: https://raw.githubusercontent.com/resend/resend-node/main/src/emails/emails.ts
+```
+
+If `main` returns 404, try `master` or `canary`. Use the Contents API (below) to discover the default branch and file paths.
+
+## 3. GitHub Contents API (no auth, ~60 req/hr)
+
+Browse repo structure when you don't know file paths:
+
+```bash
+# List directory contents
+curl -s https://api.github.com/repos/OWNER/REPO/contents/src/path
+
+# Read repo README
+curl -s https://api.github.com/repos/OWNER/REPO/readme
+
+# Get file content (base64-encoded, decode with jq)
+curl -s https://api.github.com/repos/OWNER/REPO/contents/path/to/file | jq -r '.content' | base64 -d
+```
+
+## 4. npm registry (package metadata only)
+
+```bash
+curl -s https://registry.npmjs.org/PACKAGE/latest | jq '.version, .description, .repository'
+```
+
+Useful for finding the GitHub repo URL when you don't know it.
+
+## What NEVER works in this sandbox
+
+| Approach | Why |
+|----------|-----|
+| WebFetch to vendor sites (resend.com, hono.dev, drizzle.team, etc.) | Firewall blocks non-GitHub domains |
+| WebSearch | Search engines not whitelisted |
+| `gh` CLI | Installed but not authenticated |
+| GitHub code search API (`/search/code`) | Requires authentication |
+| CDNs (unpkg, jsdelivr, cdnjs) | Not whitelisted |
+
+Do NOT attempt these — they waste time with connection timeouts and auth errors.
@@ -1,6 +1,10 @@
 ---
 name: sandbox-fetch-docs
 description: Use when needing to verify implementation against official library docs, check API contracts, or look up how a dependency works — especially after bugs caused by wrong assumptions about a library's API. Triggers on "check the docs", "verify against docs", "official documentation", "how does X API work", "canonical implementation".
+metadata:
+  author: Serge Gatezh
+  url: https://github.com/gatezh
+  version: "1.0.0"
 ---
 
 # Fetch Documentation in Sandbox
 
@@ -47,16 +47,29 @@ The image rebuilds daily at 5am MT (11:00 UTC) using native runners for both amd
 
 ### Default variant
 
-Add to your project's `.devcontainer/devcontainer.json`:
+Add these files to your project's `.devcontainer/` directory. Docker Compose with `pull_policy: always` ensures "Rebuild Without Cache" always pulls the latest image — the image name stays in one place. All other config stays in `devcontainer.json` using cross-orchestrator properties (`mounts`, `containerEnv`, `capAdd`, `init`) so you keep devcontainer variable substitution (`${devcontainerId}`, `${localEnv:...}`).
+
+`.devcontainer/docker-compose.yml`:
+
+```yaml
+services:
+  devcontainer:
+    image: ghcr.io/gatezh/devcontainer-images/claude-code:latest
+    pull_policy: always
+    volumes:
+      - ..:/workspace:cached
+```
+
+`.devcontainer/devcontainer.json`:
 
 ```jsonc
 {
   "name": "Local Development",
-  "image": "ghcr.io/gatezh/devcontainer-images/claude-code:latest",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "devcontainer",
+  "workspaceFolder": "/workspace",
   "init": true,
   "remoteUser": "node",
-  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
-  "workspaceFolder": "/workspace",
   // Named volumes persist node_modules, Claude config, and fish history across rebuilds.
   // Dirs are pre-created in the image with node:node ownership, so fresh volumes
   // inherit correct permissions via Docker volume population.
@@ -84,16 +97,29 @@ Add to your project's `.devcontainer/devcontainer.json`:
 
 > **No node_modules volumes** — the sandbox variant does not have passwordless sudo (only `sudo /usr/local/bin/init-firewall.sh` is allowed), so the `sudo chown` used in the default variant to fix volume ownership won't work. Let node_modules live in the bind mount instead.
 
+`.devcontainer/claude-sandbox/docker-compose.yml`:
+
+```yaml
+services:
+  devcontainer:
+    image: ghcr.io/gatezh/devcontainer-images/claude-code-sandbox:latest
+    pull_policy: always
+    volumes:
+      - ../..:/workspace:cached
+```
+
+`.devcontainer/claude-sandbox/devcontainer.json`:
+
 ```jsonc
 {
   "name": "Claude Code Sandbox",
-  "image": "ghcr.io/gatezh/devcontainer-images/claude-code-sandbox:latest",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "devcontainer",
+  "workspaceFolder": "/workspace",
   // Capabilities required for iptables firewall setup
   "capAdd": ["NET_ADMIN", "NET_RAW"],
   "init": true,
   "remoteUser": "node",
-  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
-  "workspaceFolder": "/workspace",
   "mounts": [
     "source=sandbox-fish-${devcontainerId},target=/home/node/.local/share/fish,type=volume",
     "source=sandbox-config-${devcontainerId},target=/home/node/.claude,type=volume",
@@ -215,10 +241,13 @@ The sandbox `devcontainer.json` already injects this via `${localEnv:CLAUDE_CODE
 
 **Alternative — per-project `.env.local` file:**
 
-If you prefer file-based configuration over host env vars, add `runArgs` to the sandbox `devcontainer.json`:
+If you prefer file-based configuration over host env vars, add `env_file` to the sandbox `docker-compose.yml` and remove `CLAUDE_CODE_OAUTH_TOKEN` from `containerEnv` in `devcontainer.json`:
 
-```jsonc
-"runArgs": ["--env-file", ".devcontainer/claude-sandbox/.env.local"],
+```yaml
+services:
+  devcontainer:
+    env_file:
+      - .env.local
 ```
 
 Create `.env.local` from the template (git-ignored):
@@ -237,16 +266,18 @@ The `.env.example` template to check into your project:
 CLAUDE_CODE_OAUTH_TOKEN=your-token-here
 ```
 
-Add `.env.local` to `.gitignore`. Note: Docker will fail to start if `.env.local` doesn't exist when using `--env-file`.
+Add `.env.local` to `.gitignore`. Note: Docker Compose fails to start if `.env.local` doesn't exist when using `env_file` (set `required: false` in compose to make it optional).
 
 ### Complete file structure
 
 ```
 .devcontainer/
 ├── devcontainer.json              ← default devcontainer
+├── docker-compose.yml             ← default compose (image + pull_policy)
 ├── init-plugins.sh                ← Claude Code plugin setup (optional)
 └── claude-sandbox/
     ├── devcontainer.json          ← sandbox devcontainer
+    ├── docker-compose.yml         ← sandbox compose (image + pull_policy)
     ├── init-firewall.sh           ← firewall script (customize domain allowlist)
     ├── .env.example               ← template for auth token (checked in)
     └── .env.local                 ← actual auth token (gitignored)
@@ -271,7 +302,7 @@ The image pre-creates these directories with `node:node` ownership so Docker's v
     └── database/node_modules/
 ```
 
-If your project has additional services, create volume mounts in `devcontainer.json` — Docker creates directories at container start. The `sudo chown` in `updateContentCommand` fixes ownership.
+If your project has additional services, add volume mounts in `devcontainer.json` `mounts` — Docker creates directories at container start. The `sudo chown` in `updateContentCommand` fixes ownership.
 
 ## Playwright Version Strategy
 
@@ -322,20 +353,23 @@ docker build --target default -t claude-code:local .devcontainer
 docker build --target sandbox -t claude-code-sandbox:local .devcontainer
 ```
 
-Then update your project's `devcontainer.json` to use the local tag:
+Then update your project's `docker-compose.yml` to use the local tag:
 
-```jsonc
-// Replace the GHCR reference:
-// "image": "ghcr.io/gatezh/devcontainer-images/claude-code:latest",
-// With the local build:
-"image": "claude-code:local",
+```yaml
+services:
+  devcontainer:
+    # Replace the GHCR reference:
+    # image: ghcr.io/gatezh/devcontainer-images/claude-code:latest
+    # With the local build:
+    image: claude-code:local
+    # pull_policy no longer needed for local images
 ```
 
-Everything else (`mounts`, `containerEnv`, `updateContentCommand`, etc.) stays the same — the local image is identical to the pre-built one.
+Everything else in `devcontainer.json` (mounts, containerEnv, lifecycle commands, etc.) stays the same — the local image is identical to the pre-built one.
 
 ### Extending the image for project-specific needs
 
-If you need to layer project-specific tools on top, create a thin Dockerfile in your project:
+If you need to layer project-specific tools on top, create a thin Dockerfile and update your compose file to build it:
 
 ```dockerfile
 # .devcontainer/Dockerfile
@@ -344,12 +378,14 @@ FROM ghcr.io/gatezh/devcontainer-images/claude-code:latest
 RUN npm install -g your-tool
 ```
 
-```jsonc
-// .devcontainer/devcontainer.json
-{
-  "build": { "dockerfile": "Dockerfile" },
-  // ... rest of config (same as Quick Start, minus the "image" key)
-}
+```yaml
+# .devcontainer/docker-compose.yml — replace `image` with `build`
+services:
+  devcontainer:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    # ... rest stays the same (workspace volume, etc.)
 ```
 
 This pulls the pre-built image as a base layer (cached after first pull) and adds your customizations on top.