docs(03-01): complete sandbox-aware prompting plan

.planning/phases/03-sandbox-aware-prompting/03-01-SUMMARY.md

@@ -0,0 +1,57 @@
+---
+phase: 03-sandbox-aware-prompting
+plan: 01
+subsystem: sandbox-prompting
+tags: [shell, claude-code, sandbox-context]
+dependency_graph:
+  requires: []
+  provides: [SANDBOX.md-generation, CLAUDE.md-import]
+  affects: [claudebox.sh]
+tech_stack:
+  added: []
+  patterns: [heredoc-generation, atomic-file-prepend]
+key_files:
+  created: []
+  modified: [claudebox.sh]
+decisions:
+  - Used head-1 string comparison instead of grep for first-line check (simpler, no grep dependency needed)
+metrics:
+  duration: 76s
+  completed: 2026-04-09
+  tasks: 2
+  files: 1
+---
+
+# Phase 03 Plan 01: Sandbox-Aware Prompting Summary
+
+SANDBOX.md heredoc generation and CLAUDE.md import management via head-1 check with atomic mktemp+mv prepend
+
+## What Was Done
+
+### Task 1: Add SANDBOX.md generation and CLAUDE.md import check
+
+Inserted a new block in claudebox.sh between `mkdir -p ~/.claudebox` and gitconfig generation. The block:
+
+1. Writes `~/.claudebox/SANDBOX.md` via single-quoted heredoc (no variable expansion) on every launch. Content covers: sandbox overview, tool installation (comma + nix shell), default restrictions with "by default" phrasing, and git identity/HTTPS guidance.
+
+2. Manages `~/.claudebox/CLAUDE.md` import line: creates file with `@SANDBOX.md` if missing, or prepends the import if first line doesn't match. Uses mktemp+mv for atomic write, preserving existing user content.
+
+### Task 2: End-to-end verification
+
+Verified three scenarios via `claudebox --dry-run --yes`:
+- **First run** (no files): SANDBOX.md created with correct content, CLAUDE.md created with `@SANDBOX.md`
+- **Idempotency**: Second run produces no duplicate import lines
+- **Prepend**: User content without import gets `@SANDBOX.md` prepended, existing content preserved
+
+## Commits
+
+| Task | Commit | Description |
+|------|--------|-------------|
+| 1 | 27d9db4 | feat(03-01): add SANDBOX.md generation and CLAUDE.md import check |
+| 2 | (verification only, no code changes) | |
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Self-Check: PASSED