diff --git a/README.md b/README.md
index 555af1e..c460f2d 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ Then add `inputs.claudebox.packages.${system}.default` to your `environment.syst
 ## What it does
 
 - Starts Claude Code inside a bwrap namespace with `--clearenv`
-- Only allowlisted env vars enter the sandbox (HOME, PATH, TERM, EDITOR, LANG, ANTHROPIC_API_KEY)
+- Only allowlisted env vars enter the sandbox (HOME, PATH, TERM, EDITOR, LANG, ANTHROPIC_API_KEY if set)
 - Mounts CWD read-write, Nix store read-only, everything else is tmpfs
 - Provides `nix shell` and [comma](https://github.com/nix-community/comma) (`, <tool>`) so Claude can install tools on demand
 - Injects a SANDBOX.md so Claude knows it's sandboxed and how to get tools
@@ -37,6 +37,7 @@ Then add `inputs.claudebox.packages.${system}.default` to your `environment.syst
 | `--dry-run` | Print the bwrap command without executing |
 | `--check` | Verify prerequisites and exit |
 | `--shell` | Drop into a bash shell instead of Claude Code |
+| `--gc` | Remove stale per-project instance dirs and exit |
 | `--` | Pass remaining args to Claude Code |
 
 ## Extra env vars
@@ -51,21 +52,26 @@ CLAUDEBOX_EXTRA_ENV=MY_VAR,OTHER_VAR claudebox
 
 ```
 ~/.claudebox/          # persistent config dir (host)
-├── CLAUDE.md          # user-owned, claudebox ensures @SANDBOX.md import
-└── SANDBOX.md         # managed by claudebox, overwritten each launch
+├── SANDBOX.md         # managed by claudebox, overwritten each launch
+├── history.jsonl      # conversation history
+├── .credentials.json  # Claude Code credentials (if present)
+└── projects/
+    └── <16-char-hex>/ # per-project instance dir (keyed by canonical git root)
+        └── project-root  # records the canonical path for this instance
 
 Inside the sandbox:
-  ~/.claudebox  →  bind-mounted from host
-  ~/.claude     →  symlink to ~/.claudebox
+  ~/.claude            →  bind-mounted from host (plugins, skills, hooks, MCP all visible)
+  ~/.claude/projects   →  bind-mounted from ~/.claudebox/projects/<hash>/ (per-project isolation)
+  ~/.claude/history.jsonl → bind-mounted from ~/.claudebox/history.jsonl
+  ~/.claude/SANDBOX.md →  bind-mounted from ~/.claudebox/SANDBOX.md
 ```
 
-Claude Code reads `~/.claude/CLAUDE.md` which imports `@SANDBOX.md` via Claude's `@`-import syntax. Both `~/.claude` and `~/.claudebox` resolve to the same directory inside the sandbox, so hook paths and settings work without fixups.
+Each project gets an isolated `~/.claude/projects/` directory inside the sandbox, so conversation history and project state are separated per repo. Git worktrees share the same instance dir as their main worktree.
 
 ## Requirements
 
 - NixOS or Nix with flakes enabled
 - User namespaces (enabled by default on NixOS)
-- `ANTHROPIC_API_KEY` set in your environment
 
 ## License