@@ -0,0 +1,107 @@
+---
+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".
+---
+
+# 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.
@@ -82,6 +82,8 @@ Add to your project's `.devcontainer/devcontainer.json`:
 
 ### Sandbox variant
 
+> **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.
+
 ```jsonc
 {
   "name": "Claude Code Sandbox",
@@ -171,7 +173,24 @@ Default-deny iptables firewall. The image provides the packages and sudo rule; t
 
 See the [devcontainer-claude-bun firewall script](../devcontainer-claude-bun/.devcontainer/init-firewall.sh) for a complete example.
 
-Mark as executable: `chmod +x init-firewall.sh`
+Mark as executable and ensure git tracks the executable bit:
+
+```bash
+chmod +x .devcontainer/claude-sandbox/init-firewall.sh
+git add .devcontainer/claude-sandbox/init-firewall.sh   # ensures git tracks +x (100755)
+```
+
+> **Troubleshooting (macOS):** If the firewall script fails with "command not found" despite correct permissions (`stat` shows `rwxr-xr-x`, git shows `100755`), stale Docker Desktop metadata may be overriding the file mode. Fix by removing the cached extended attribute:
+>
+> ```bash
+> xattr -d com.docker.grpcfuse.ownership .devcontainer/claude-sandbox/init-firewall.sh
+> ```
+
+### Sandbox-only: Claude Code skill for fetching docs
+
+The sandbox firewall blocks vendor doc sites, so Claude Code can't `WebFetch` or `WebSearch` as it normally would. The image includes a [sandbox-fetch-docs](.claude/skills/sandbox-fetch-docs.md) skill that teaches Claude Code how to look up library documentation using only allowed network paths (node_modules, raw.githubusercontent.com, GitHub Contents API, npm registry).
+
+Copy `.claude/skills/sandbox-fetch-docs.md` into your project's `.claude/skills/` directory so Claude Code picks it up automatically.
 
 ### Sandbox Authentication
 
@@ -231,6 +250,9 @@ Add `.env.local` to `.gitignore`. Note: Docker will fail to start if `.env.local
     ├── init-firewall.sh           ← firewall script (customize domain allowlist)
     ├── .env.example               ← template for auth token (checked in)
     └── .env.local                 ← actual auth token (gitignored)
+.claude/
+└── skills/
+    └── sandbox-fetch-docs.md      ← teaches Claude Code to fetch docs within sandbox firewall
 ```
 
 ## Workspace Directory Layout
@@ -260,6 +282,12 @@ The image uses a two-layer strategy so that any project can use any `@playwright
 | System deps (`install-deps`) | OS libraries (libgbm, libnss3, …) | Yes (needs root) | Stable across nearby versions |
 | Browser binary (`install --only-shell`) | Headless Chromium shell | Yes, as cache | Exact match required |
 
+**Prerequisite:** Your project must have `@playwright/test` in `devDependencies`. Without it, `npx` will prompt interactively to download the `playwright` package, which hangs container creation (no TTY). Pin it to the image's baked version (check `$PLAYWRIGHT_VERSION`) or your preferred version:
+
+```bash
+bun add -d @playwright/test    # or: npm install -D @playwright/test
+```
+
 **One-time project setup** — add this to your container creation command (`updateContentCommand` or `postCreateCommand`, as shown in [Quick Start](#quick-start)):
 
 ```bash