docs: Add nap, reskill, and compact behavior documentation

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

@@ -0,0 +1,130 @@
+# Context Hygiene: Nap, Reskill, and Compact
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+
+**Try this to compact your team's memory:**
+```
+Team, take a nap
+```
+
+**Try this to refresh agent skills:**
+```
+Team, reskill
+```
+
+**Try this to do both and report results:**
+```
+Team, reskill, take a nap, and let me know how much context you cleared out collectively for future iterations
+```
+
+Over multiple sessions, Squad's `.squad/` files grow — agent histories, decisions, skill files. Context hygiene commands let you actively manage that growth so agents stay fast and focused.
+
+---
+
+## Nap
+
+**What it does:** Summarizes accumulated work into smaller, more efficient memory files. This is the same as running `/compact` in the CLI or `squad nap` from the command line.
+
+When you tell the team to "take a nap," each agent:
+
+1. Reviews its `history.md` and other state files
+2. Compresses older entries into concise summaries
+3. Archives verbose detail while preserving key decisions and learnings
+4. Reports how much context was reclaimed
+
+### Nap ≠ Shutting Down
+
+This is the most common misconception:
+
+| Action | What happens to `.squad/` files |
+|--------|-------------------------------|
+| **Shutting down Squad** (closing the CLI, killing the process) | Files stay exactly as they are. Nothing is summarized or compacted. |
+| **Nap** (`team, take a nap` or `squad nap`) | Files are actively summarized and compacted. Older entries are archived, working context gets leaner. |
+
+Shutting down Squad every night does **not** perform context hygiene. You must explicitly tell the team to take a nap.
+
+### CLI equivalents
+
+```bash
+squad nap              # Standard context hygiene
+squad nap --deep       # Thorough cleanup with recursive descent
+squad nap --dry-run    # Preview what would be cleaned up
+```
+
+In the interactive shell, use `/compact` for the same effect.
+
+---
+
+## Reskill
+
+**What it does:** Tells agents to re-examine their 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 `.squad/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
+
+### Availability
+
+> **Note:** As of now, reskill requires running Squad from source (via symlink). It is not yet available through `squad upgrade`. This will change in a future release.
+
+---
+
+## Combined Commands
+
+You can trigger nap and reskill together in a single prompt:
+
+```
+Team, reskill, take a nap, and let me know how much context you cleared out collectively for future iterations
+```
+
+This runs both behaviors and gives you a report on how much context was reduced — useful for understanding how lean your team's working memory is before the next session.
+
+---
+
+## When to Use These
+
+| Situation | Command |
+|-----------|---------|
+| After several work sessions, agents feel slow or unfocused | `team, take a nap` |
+| Codebase has changed significantly and skills may be stale | `team, reskill` |
+| Before a major new phase of work | Combine both |
+| End of sprint / milestone | `squad nap --deep` |
+
+---
+
+## Tips
+
+- **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.
+
+## Sample Prompts
+
+```
+team, take a nap
+```
+
+Compacts and summarizes all agent memory files, reclaiming context space.
+
+```
+team, reskill
+```
+
+Agents re-examine and validate their skills against the current codebase.
+
+```
+team, reskill, take a nap, and let me know how much context you cleared out collectively for future iterations
+```
+
+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.

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

@@ -268,10 +268,11 @@ squad doctor
 This performs a comprehensive diagnostic check of your Squad setup, validating:
 
 - `.squad/` directory structure
-- Required configuration files (team.md, routing.md, etc.)
-- Agent definitions and capabilities
-- File permissions and integrity
-- Integration with GitHub and Copilot
+- `config.json` validity and `teamRoot` configuration (if present)
+- Team root resolution (remote mode)
+- Required files: `team.md`, `routing.md`, `decisions.md`
+- `agents/` directory and agent count
+- `casting/registry.json` integrity
 
 ### Usage Examples
 
@@ -289,14 +290,24 @@ git clone my-project && cd my-project && squad doctor
 ### Example Output
 
 ```
-✓ .squad/ directory exists
-✓ team.md is readable and valid
-✓ 4 agents registered
-⚠ skills/ directory is empty — consider adding documentation
-✓ .gitattributes rules applied
+🩺 Squad Doctor
+═══════════════
+
+Mode: local
+
+✅  .squad/ directory exists — directory present
+✅  team.md found with ## Members header — file present, header found
+✅  routing.md found — file present
+✅  agents/ directory exists — directory present (4 agents)
+✅  casting/registry.json exists — file present, valid JSON
+✅  decisions.md exists — file present
+
+Summary: 6 passed, 0 failed, 0 warnings
 ```
 
-The doctor always exits cleanly (no error code) because it's a diagnostic tool, not a gate. Use it to troubleshoot setup issues, validate team state, or run before opening an issue on GitHub.
+The doctor always exits cleanly (exit code 0) because it's a diagnostic tool, not a gate. Use it to troubleshoot setup issues, validate team state, or run before opening an issue on GitHub.
+
+For a full reference of every check, warning, and fix, see [Troubleshooting: `squad doctor` warnings and failures](../scenarios/troubleshooting.md#squad-doctor-warnings-and-failures).
 
 ### Common Issues
 

docs/src/content/docs/reference/config.md

@@ -85,6 +85,46 @@ Commit this directory. It's your team's brain. Anyone who clones the repo gets t
 
 ---
 
+## .squad/ — Required vs Optional Files
+
+`squad init` creates a working team. Here's what's required and what's optional.
+
+### Required Files
+
+These are always created by `squad init`. The loader expects them.
+
+| File | Purpose | Can You Edit? |
+|------|---------|---------------|
+| `.squad/team.md` | Team roster — loader requires it | Yes |
+| `.squad/decisions.md` | Shared decision log — agents read before work | Yes (append only) |
+| `.squad/routing.md` | Work assignment rules | Yes |
+| `.squad/ceremonies.md` | Team meeting definitions | Yes |
+| `.squad/config.json` | SDK settings (teamRoot, version) | Rarely |
+| `.squad/agents/{name}/charter.md` | Agent identity — compiled at spawn | Yes |
+| `.squad/agents/{name}/history.md` | Agent learnings — grows over time | Append only |
+| `.squad/identity/now.md` | Current team focus | Auto-updated |
+| `.squad/identity/wisdom.md` | Accumulated team patterns | Auto-updated |
+| `.gitattributes` | Merge drivers for append-only files | Merge rules only |
+
+### Optional Files
+
+These are created only when you opt in during init.
+
+- **`.squad/templates/`** — SDK templates, overwritten on upgrade
+- **`.github/workflows/*.yml`** — CI/CD workflows (opt-in: `--include-workflows`)
+- **`.copilot/mcp-config.json`** — MCP server config (opt-in: `--include-mcp-config`)
+
+> ⚠️ **Hard rule:** Squad NEVER writes temp files, logs, or memory to your repo root. All team state lives in `.squad/` only. Your project tree stays clean.
+
+### Quick Recovery
+
+```bash
+squad doctor                        # Check for issues
+rm -rf .squad && squad init         # Full reset (back up agents/decisions first)
+```
+
+---
+
 ## Routing Rules
 
 Control which agent gets which work. Edit `.squad/routing.md` or configure in `squad.config.ts`:

docs/src/content/docs/scenarios/troubleshooting.md

@@ -134,6 +134,152 @@ If below v20, upgrade to the latest LTS:
 
 ---
 
+## `squad doctor` warnings and failures
+
+`squad doctor` validates your `.squad/` setup and reports each check as ✅ pass, ❌ fail, or ⚠️ warn. It always exits 0 — it's a diagnostic tool, not a gate.
+
+Run it any time something feels off:
+
+```bash
+squad doctor
+```
+
+### Checks and how to fix them
+
+#### ❌ `.squad/` directory not found
+
+**Cause:** No squad has been initialized in this project.
+
+**Fix:** Run `squad init` (or `squad init --mode remote <path>` for dual-root setups).
+
+---
+
+#### ❌ `config.json` — file exists but is not valid JSON
+
+**Cause:** The `.squad/config.json` file is corrupted or was hand-edited with a syntax error.
+
+**Fix:** Open `.squad/config.json` and fix the JSON syntax, or delete it and re-run `squad init`.
+
+---
+
+#### ❌ `config.json` — teamRoot must be a string
+
+**Cause:** The `teamRoot` value in `.squad/config.json` is not a string (e.g., it's a number or object).
+
+**Fix:** Edit `.squad/config.json` so `teamRoot` is a quoted string path:
+
+```json
+{ "teamRoot": "../my-team-repo" }
+```
+
+---
+
+#### ⚠️ Absolute path warning — teamRoot is absolute
+
+**Cause:** `teamRoot` in `.squad/config.json` uses an absolute path (e.g., `/home/user/team-repo`). This works locally but breaks portability across machines.
+
+**Fix:** Change `teamRoot` to a relative path:
+
+```json
+{ "teamRoot": "../my-team-repo" }
+```
+
+---
+
+#### ❌ Team root — directory not found
+
+**Cause:** The `teamRoot` path in `.squad/config.json` points to a directory that doesn't exist. The team-root repo may not be cloned, or the relative path is wrong.
+
+**Fix:**
+1. Clone the team-root repo to the expected location.
+2. Or update `teamRoot` in `.squad/config.json` to the correct relative path.
+3. Or re-link with `squad link <correct-path>`.
+
+---
+
+#### ❌ `team.md` — file not found
+
+**Cause:** The `.squad/team.md` file is missing. This file defines your team roster.
+
+**Fix:** Run `squad init` to regenerate it, or create `.squad/team.md` manually with a `## Members` section.
+
+---
+
+#### ⚠️ `team.md` — missing `## Members` header
+
+**Cause:** The file exists but doesn't contain the expected `## Members` markdown header that Squad uses to discover team members.
+
+**Fix:** Add a `## Members` section to `.squad/team.md`:
+
+```markdown
+## Members
+
+- **Kaylee** — Engineering Lead
+- **Ralph** — GitHub Operations
+```
+
+---
+
+#### ❌ `routing.md` — file not found
+
+**Cause:** The `.squad/routing.md` file is missing. This file tells Squad how to route tasks to agents.
+
+**Fix:** Run `squad init` to regenerate it, or create `.squad/routing.md` manually.
+
+---
+
+#### ❌ `agents/` directory — directory not found
+
+**Cause:** No agent definitions exist. Squad needs at least one agent directory under `.squad/agents/`.
+
+**Fix:** Run `squad init` to scaffold the default agents, or create `.squad/agents/<agent-name>/` directories manually.
+
+---
+
+#### ❌ `casting/registry.json` — file not found or invalid JSON
+
+**Cause:** The casting registry is missing or corrupted. This file tracks agent role assignments.
+
+**Fix:** Run `squad init` to regenerate it. If you need to preserve existing casting data, fix the JSON syntax in `.squad/casting/registry.json`.
+
+---
+
+#### ❌ `decisions.md` — file not found
+
+**Cause:** The `.squad/decisions.md` file is missing. This file records team decisions for context continuity.
+
+**Fix:** Create an empty `.squad/decisions.md` file:
+
+```bash
+touch .squad/decisions.md
+```
+
+---
+
+### Reading the summary
+
+Doctor output ends with a summary line:
+
+```
+Summary: 7 passed, 1 failed, 1 warnings
+```
+
+- **All passed:** Your setup is healthy.
+- **Warnings:** Non-blocking issues worth fixing (e.g., absolute paths).
+- **Failures:** Missing or broken files that will affect Squad behavior.
+
+### Modes
+
+Doctor detects three setup modes automatically:
+
+| Mode | Trigger | Meaning |
+|------|---------|---------|
+| `local` | Default | Single-repo squad, everything in `.squad/` |
+| `remote` | `config.json` has `teamRoot` | Dual-root setup with a separate team repo |
+| `hub` | `squad-hub.json` exists in cwd | Hub layout for multi-project teams |
+
+---
+
 ## Windows-specific issues
 
 **Problem:** Path errors or file operations fail on Windows.

test/docs-build.test.ts

@@ -53,6 +53,7 @@ const EXPECTED_FEATURES = [
   'built-in-roles',
   'ceremonies',
   'consult-mode',
+  'context-hygiene',
   'copilot-coding-agent',
   'directives',
   'distributed-mesh',