feat(cli): squad upgrade --self to update the CLI package

.changeset/self-upgrade.md

@@ -0,0 +1,12 @@
+---
+"@bradygaster/squad-cli": minor
+---
+
+Add `squad upgrade --self` to upgrade the CLI package itself (#798)
+
+- `squad upgrade --self` → installs `@bradygaster/squad-cli@latest` (stable)
+- `squad upgrade --self --insider` → installs `@bradygaster/squad-cli@insider` (prerelease)
+- After self-upgrade, automatically continues with repo upgrade to apply new templates
+- Detects package manager (npm/pnpm/yarn) from npm_config_user_agent
+- Clear error on permission denied (suggests sudo or npx)
+- Help text updated with new flags

README.md

@@ -92,17 +92,20 @@ Use `--force` to re-apply updates even when your installed version already match
 
 ---
 
-## All Commands (15 commands)
+## All Commands (17 commands)
 
 | Command | What it does |
 |---------|-------------|
 | `squad init` | **Init** — scaffold Squad in the current directory (idempotent — safe to run multiple times); alias: `hire`; use `--global` to init in personal squad directory, `--mode remote <path>` for dual-root mode |
 | `squad upgrade` | Update Squad-owned files to latest; never touches your team state; use `--global` to upgrade personal squad, `--migrate-directory` to rename `.ai-team/` → `.squad/` |
+| `squad upgrade --self` | Update the Squad CLI package itself; add `--insider` for prerelease builds |
 | `squad status` | Show which squad is active and why |
 | `squad triage` | **Watch mode** — poll for issues and auto-triage to team (aliases: `watch`, `loop`); use `--interval <minutes>` to set polling frequency (default: 10); with `--execute` dispatch Copilot agents; use `--agent-cmd`, `--copilot-flags`, `--auth-user` to customize agent execution; `--health` shows watch status; `--log-file` for diagnostics |
 | `squad copilot` | Add/remove the Copilot coding agent (@copilot); use `--off` to remove, `--auto-assign` to enable auto-assignment |
 | `squad doctor` | Check your setup and diagnose issues (alias: `heartbeat`) |
 | `squad link <team-repo-path>` | Connect to a remote team |
+| `squad externalize` | Move `.squad/` state outside the working tree; survives branch switches; use `--key <name>` for custom project key |
+| `squad internalize` | Move externalized state back into `.squad/` |
 | `squad shell` | Launch interactive shell explicitly |
 | `squad export` | Export squad to a portable JSON snapshot |
 | `squad import <file>` | Import squad from an export file |

docs/src/content/docs/features/built-in-roles.md

@@ -14,7 +14,7 @@
 - **Higher quality** — curated expertise, boundaries, and voice instead of generic boilerplate.
 - **Broad coverage** — not just software dev; marketing, sales, product, game dev, and more.
 
-## Software Development Roles (12)
+## Software Development Roles (13)
 
 | Emoji | ID | Title | Vibe |
 |-------|----|-------|------|
@@ -30,6 +30,7 @@
 | 📝 | `docs` | Technical Writer | Turns complexity into clarity. If the docs are wrong, the product is wrong. |
 | 🤖 | `ai` | AI / ML Engineer | Builds intelligent systems that learn, reason, and adapt. |
 | 🎨 | `designer` | UI/UX Designer | Pixel-aware and user-obsessed. If it looks off by one, it is off by one. |
+| 🔍 | `fact-checker` | Fact Checker | Trust, but verify. Every claim gets a source check before it ships. |
 
 ## Business & Operations Roles (8)
 

docs/src/content/docs/features/cleanup.md

@@ -0,0 +1,163 @@
+# Cleanup Watch
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+
+**Try this to trigger a cleanup cycle:**
+```
+squad watch --execute
+```
+
+**Try this to configure cleanup frequency:**
+```json
+{
+  "cleanup": {
+    "everyNRounds": 10,
+    "maxAgeDays": 30
+  }
+}
+```
+
+Ralph runs automated housekeeping during `squad watch` to keep `.squad/` clean — clearing temp files, archiving old logs, and flagging stale decisions.
+
+---
+
+## What Gets Cleaned
+
+### Scratch Directory
+
+Clears all files in `.squad/.scratch/` — the ephemeral temp directory used for prompt files, commit drafts, and processing artifacts. These are temporary by design and safe to delete between sessions.
+
+### Log Archives
+
+Archives orchestration-log and session-log entries older than the configured `maxAgeDays` (default: 30 days):
+- Orchestration logs (work dispatch, agent lifecycle)
+- Session logs (Copilot session metadata)
+
+Archived logs are moved to `.squad/logs/archive/{YYYY-MM}/` for long-term storage without cluttering active logs.
+
+### Decision Inbox Warnings
+
+Scans `.squad/decisions/inbox/` for files older than 7 days and warns you. Decision inbox files represent unmerged decisions — leaving them stale means the team's decision log is out of sync with actual project state.
+
+```
+⚠️  Stale decision inbox files detected:
+    - inbox/auth-strategy-2025-01-15.md (12 days old)
+    - inbox/api-versioning-2025-01-10.md (17 days old)
+
+    Run: squad decisions merge
+```
+
+Cleanup doesn't auto-merge — it just warns. You decide when to merge.
+
+---
+
+## When Cleanup Runs
+
+Cleanup runs during the **housekeeping phase** of `squad watch` — after all work is processed for the round, before the next polling interval. This happens every `N` rounds based on your config.
+
+**Default behavior:**
+- Cleanup runs every **10 rounds** of `squad watch`
+- Archives logs older than **30 days**
+- Warns about decision inbox files older than **7 days**
+
+---
+
+## Configuration
+
+Add a `cleanup` section to your `.squad/config.json`:
+
+```json
+{
+  "cleanup": {
+    "everyNRounds": 10,
+    "maxAgeDays": 30
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `everyNRounds` | number | 10 | Run cleanup every N watch rounds |
+| `maxAgeDays` | number | 30 | Archive logs older than this many days |
+
+**Examples:**
+
+Run cleanup every 5 rounds, keep 60 days of logs:
+```json
+{
+  "cleanup": {
+    "everyNRounds": 5,
+    "maxAgeDays": 60
+  }
+}
+```
+
+Run cleanup every round (aggressive), keep 14 days:
+```json
+{
+  "cleanup": {
+    "everyNRounds": 1,
+    "maxAgeDays": 14
+  }
+}
+```
+
+---
+
+## What Cleanup Does NOT Touch
+
+- Earned skills in `.squad/skills/` — never deleted
+- Decision log in `.squad/decisions/log.md` — never deleted
+- Active session data
+- Router state, team config, and other core Squad files
+
+Cleanup is safe and conservative — it only removes temporary files and archives old logs. Core squad state is never touched.
+
+---
+
+## Manual Cleanup
+
+You can manually trigger cleanup without running `squad watch`:
+
+```bash
+# Clean scratch dir only
+rm -rf .squad/.scratch/*
+
+# Archive old logs manually
+squad logs archive --before 2025-01-01
+
+# Merge stale decision inbox
+squad decisions merge
+```
+
+---
+
+## Notes
+
+- Cleanup is **opt-in** — it only runs during `squad watch`, not in standalone Copilot sessions
+- Cleanup logs are written to the orchestration log for audit trail
+- Archived logs are still accessible but separated from active logs
+- Decision inbox warnings are informational only — no auto-merge
+
+---
+
+## Sample Prompts
+
+```
+Ralph, run cleanup now
+```
+
+Triggers a cleanup cycle immediately (if Ralph is active in `squad watch`).
+
+```
+Show me what cleanup will do
+```
+
+Dry-run preview of cleanup actions without actually running them.
+
+```
+How often does cleanup run?
+```
+
+Reports the current `everyNRounds` setting from config.