feat(nap): measure charter/skill context and add --dry-run --json

.changeset/nap-context-json-safety.md

@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': patch
+---
+
+`squad nap` now measures the agent-loaded context it reports, including charter and skill bytes, while keeping those files read-only. Dry-run output is clearly marked as non-mutating and uses conditional wording, `squad nap --json` exposes structured before/after/action data for tooling in both CLI and interactive shell usage, and the reskill prompt now bases its savings table on measured dry-run JSON instead of hand-written estimates.

docs/src/content/docs/features/context-hygiene.md

@@ -50,22 +50,30 @@ Shutting down Squad every night does **not** perform context hygiene. You must e
 squad nap              # Standard context hygiene
 squad nap --deep       # Thorough cleanup with recursive descent
 squad nap --dry-run    # Preview what would be cleaned up
+squad nap --dry-run --json  # Measure reclaimable context with structured output
 ```
 
 In the interactive shell, use `/compact` for the same effect.
 
+`squad nap --dry-run --json` is the safest way to answer "how much context can we reclaim?" It reports before/after metrics and planned actions without modifying files, so tests and CI can assert real numbers instead of relying on estimates.
+
+Nap also measures loaded-context sources that affect every agent spawn: `charterBytes`, `skillBytes` for markdown under `.squad/skills/`, `charterReducibleBytes` above the 1.5 KB per-charter reskill target, and `historyReducibleBytes` above the 8 KB per-history target. It measures charters and skills, but it never modifies them. Charters define agent identity; automated charter rewriting is not part of nap.
+
 ---
 
 ## Reskill
 
-**What it does:** Tells agents to re-examine their skills, validate them against the current codebase, and potentially discover new patterns.
+**What it does:** Tells agents to audit measured context, re-examine skills, validate them against the current codebase, and potentially discover new patterns.
 
 When you tell the team to "reskill," agents:
 
-1. Review existing skill files in `.copilot/skills/`
-2. Validate that documented patterns still apply
-3. Look for new reusable patterns from recent work
-4. Update skill confidence levels based on current evidence
+1. Start from `squad nap --dry-run --json` to get measured context numbers
+2. Review skill files in `.copilot/skills/` and legacy `.squad/skills/`
+3. Validate that documented patterns still apply
+4. Look for new reusable patterns from recent work
+5. Update skill confidence levels based on current evidence
+
+The nap metrics give reskill a concrete audit baseline: how much agent-loaded context exists, what nap would change, and which charter or history bytes sit above the documented reskill targets. Reskill can use those numbers to guide recommendations, but nap still does not rewrite charters or skills.
 
 ### Availability
 
@@ -101,7 +109,7 @@ This runs both behaviors and gives you a report on how much context was reduced
 - **Nap regularly.** A few sessions of heavy work can bloat history files. Napping keeps context budgets in check.
 - **Don't rely on shutdown.** Closing the CLI preserves files as-is — it does not compact anything.
 - **Reskill after refactors.** If you've restructured the codebase, agent skills may reference outdated patterns.
-- **Check the dry run first.** Use `squad nap --dry-run` to preview cleanup actions before committing to them.
+- **Check the dry run first.** Use `squad nap --dry-run` to preview cleanup actions. The report is clearly labeled `DRY RUN — no files were modified`; add `--json` when you need structured metrics.
 
 ## Sample Prompts
 
@@ -127,4 +135,4 @@ Combines both behaviors and reports back on total context reduction.
 squad nap --dry-run
 ```
 
-Previews what a nap would clean up without making any changes.
+Previews what a nap would clean up without making any changes, with an explicit dry-run banner.

docs/src/content/docs/reference/cli.md

@@ -75,6 +75,7 @@ prerequisites, all supported methods, and update commands.
 | `squad nap` | Context hygiene (compress, prune, archive .squad/ state) | Yes |
 | `squad nap --deep` | Thorough cleanup with recursive descent | Yes |
 | `squad nap --dry-run` | Preview cleanup actions without changes | Yes |
+| `squad nap --json` | Emit machine-readable nap metrics and actions | Yes |
 | `squad scrub-emails [directory]` | Remove email addresses from Squad state files (default: `.squad/`) | No |
 | `squad --version` | Print installed version | No |
 

packages/squad-cli/src/cli-entry.ts

@@ -226,8 +226,8 @@ async function main(): Promise<void> {
     console.log(`                       start --tunnel --model claude-sonnet-4.6`);
     console.log(`                       start --tunnel --command "gh copilot"`);
     console.log(`  ${BOLD}nap${RESET}        Context hygiene (compress, prune, archive .squad/ state)`);
-    console.log(`             Usage: nap [--deep] [--dry-run]`);
-    console.log(`             Flags: --deep (thorough cleanup), --dry-run (preview only)`);
+    console.log(`             Usage: nap [--deep] [--dry-run] [--json]`);
+    console.log(`             Flags: --deep (thorough cleanup), --dry-run (preview only), --json (machine-readable)`);
     console.log(`  ${BOLD}memory${RESET}     Governed memory operations`);
     console.log(`             Usage: memory write --content "..." --class LOCAL`);
     console.log(`             Diagnostics: --log-level info|debug or --verbose`);
@@ -976,8 +976,16 @@ async function main(): Promise<void> {
     }
     const deep = args.includes('--deep');
     const dryRun = args.includes('--dry-run');
+    const json = args.includes('--json');
     const result = await runNap({ squadDir, deep, dryRun });
-    console.log(formatNapReport(result, !!process.env['NO_COLOR']));
+    if (json) {
+      // Stable machine-readable shape mirroring NapResult so downstream
+      // tooling can diff before/after and assert on savings deterministically.
+      // Follows the health.ts:795 `--json` precedent (2-space indent).
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatNapReport(result, !!process.env['NO_COLOR']));
+    }
     return;
   }
 

packages/squad-cli/src/cli/core/command-help.ts

@@ -204,10 +204,11 @@ const COMMAND_HELP: Record<string, HelpPrinter> = {
 
   nap: (version) => {
     header('nap', version, 'Context hygiene — compress, prune, archive .squad/ state');
-    console.log(`Usage: squad nap [--deep] [--dry-run]\n`);
+    console.log(`Usage: squad nap [--deep] [--dry-run] [--json]\n`);
     console.log(`Options:`);
     console.log(`  ${BOLD}--deep${RESET}                      Thorough cleanup, including older history`);
-    console.log(`  ${BOLD}--dry-run${RESET}                   Preview changes without writing\n`);
+    console.log(`  ${BOLD}--dry-run${RESET}                   Preview changes without writing (report shows a DRY RUN banner and conditional verbs)`);
+    console.log(`  ${BOLD}--json${RESET}                      Emit machine-readable JSON ({ dryRun, before, after, actions }) for CI/diffing\n`);
   },
 
   memory: (version) => {