From e0876617af481514c0a418d45704c1a45641b27d Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 12:58:44 +1000
Subject: [PATCH 01/12] =?UTF-8?q?fix(cli):=20fix=20migration=20experience?=
 =?UTF-8?q?=20for=20v0.5.x=20=E2=86=92=20v0.8.x=20upgrades?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Shell scaffolds .squad/ when team.md is absent instead of blocking all
  input with a circular 'Run /init' message
- Add 'squad migrate' command: backup → clean → reinit → restore user files
  Supports --dry-run and --backup-dir flags
- Fix scrub-emails default directory (.ai-team/ → .squad/)
- Rewrite docs/scenarios/upgrading.md (remove npx github: references,
  add global/local/npx coverage)
- Update docs/scenarios/troubleshooting.md (Node.js 22→20, remove SSH hang)
- Update docs/get-started/migration.md (Node.js 18→20, @latest, all install
  methods, squad migrate usage)

Closes #197
---
 .changeset/fix-migration-experience.md     |  12 ++
 docs/get-started/migration.md              | 153 +++++++++++----
 docs/scenarios/troubleshooting.md          |  52 ++---
 docs/scenarios/upgrading.md                |  94 ++++-----
 packages/squad-cli/src/cli-entry.ts        |  15 +-
 packages/squad-cli/src/cli/core/migrate.ts | 213 +++++++++++++++++++++
 packages/squad-cli/src/cli/shell/index.ts  |  26 ++-
 test/init-autocast.test.ts                 |   5 +-
 8 files changed, 425 insertions(+), 145 deletions(-)
 create mode 100644 .changeset/fix-migration-experience.md
 create mode 100644 packages/squad-cli/src/cli/core/migrate.ts

diff --git a/.changeset/fix-migration-experience.md b/.changeset/fix-migration-experience.md
new file mode 100644
index 000000000..6f68d6bdb
--- /dev/null
+++ b/.changeset/fix-migration-experience.md
@@ -0,0 +1,12 @@
+---
+"@bradygaster/squad-cli": patch
+---
+
+Fix migration experience for users upgrading from v0.5.x
+
+- Shell now scaffolds `.squad/` via `sdkInitSquad()` when `team.md` is absent, instead of blocking all input with a circular "Run /init" message
+- Add `squad migrate` command: backs up `.squad/`, cleans squad-owned files, reinitializes, then restores user-owned files. Supports `--dry-run` and `--backup-dir` flags
+- Fix `scrub-emails` default directory (`.ai-team/` → `.squad/`)
+- Rewrite `docs/scenarios/upgrading.md`: remove stale `npx github:bradygaster/squad` references, add correct commands for global/local/npx install methods
+- Update `docs/scenarios/troubleshooting.md`: fix Node.js version requirement (22→20), remove SSH hang section specific to removed distribution
+- Update `docs/get-started/migration.md`: fix Node.js version (18→20), use `@latest` instead of pinned version, document all three install methods, add `squad migrate` usage
diff --git a/docs/get-started/migration.md b/docs/get-started/migration.md
index 11eecb5c3..38179e843 100644
--- a/docs/get-started/migration.md
+++ b/docs/get-started/migration.md
@@ -16,7 +16,7 @@
 - [Scenario 9: Using Squad SDK Programmatically](#scenario-9-using-squad-sdk-programmatically)
 - [Troubleshooting](#troubleshooting)
 - [Rolling Back](#rolling-back)
-- [What's New in v0.8.18](#whats-new-in-v0818)
+- [What's New in v0.8.21+](#whats-new-in-v0821)
 
 ---
 
@@ -27,7 +27,7 @@
 | `npx github:bradygaster/squad` | `npx @bradygaster/squad-cli` |
 | `@bradygaster/create-squad` | `@bradygaster/squad-cli` |
 | `.ai-team/` directory | `.squad/` directory |
-| v0.5.4 (beta) | v0.8.18 |
+| v0.5.4 (beta) | v0.8.x |
 
 ---
 
@@ -37,21 +37,29 @@ Never used Squad before? Start here.
 
 ### Prerequisites
 
-- Node.js 18 or later
+- Node.js 20 or later
 - npm 9 or later
 - A GitHub account with [GitHub Copilot](https://github.com/features/copilot) enabled
 - `gh` CLI authenticated (`gh auth status` should show you logged in)
 
 ### Install
 
+**Global (recommended for personal use):**
+
 ```bash
 npm install -g @bradygaster/squad-cli
 ```
 
-Or run without installing:
+**Project-local (recommended for team repos):**
 
 ```bash
-npx @bradygaster/squad-cli
+npm install --save-dev @bradygaster/squad-cli
+```
+
+**No install required (one-off):**
+
+```bash
+npx @bradygaster/squad-cli init
 ```
 
 ### Initialize a Project
@@ -80,12 +88,60 @@ This is the biggest jump. The codebase was rewritten in TypeScript, the `.squad/
 ### What Changed
 
 - **TypeScript rewrite:** Entire codebase ported from JavaScript to TypeScript (strict mode).
-- **`.squad/` directory format:** v0.5.4 format is incompatible with v0.8.18. You must reinitialize.
+- **`.squad/` directory format:** v0.5.4 format is incompatible with v0.8.x. You must reinitialize.
 - **Command structure:** Some commands were reorganized or renamed.
 - **SDK API:** The public API changed significantly if you were using Squad programmatically.
 - **Distribution:** npm-only. The `npx github:` install path is gone.
 
-### Step-by-Step
+### Automated Migration (Recommended)
+
+Squad v0.8.20+ includes a `migrate` command that handles backup, cleanup, and reinit in one step.
+
+First, install or update to the latest version using whichever method you prefer:
+
+```bash
+# Global install
+npm install -g @bradygaster/squad-cli@latest
+
+# Project-local
+npm install --save-dev @bradygaster/squad-cli@latest
+
+# One-off (no install)
+# (use npx @bradygaster/squad-cli migrate directly below)
+```
+
+Then run the migration from your repo root:
+
+```bash
+# Global or local install
+squad migrate
+
+# npx (no install)
+npx @bradygaster/squad-cli migrate
+```
+
+Preview what it will do first (nothing is changed):
+
+```bash
+squad migrate --dry-run
+```
+
+`squad migrate` will:
+
+1. Back up your existing `.squad/` to `.squad-backup-{timestamp}/`
+2. Remove Squad-owned scaffold files
+3. Run `squad init` for a clean, current scaffold
+4. Restore your user-owned files: `agents/`, `decisions.md`, `routing.md`, `team.md`, `skills/`
+
+Then verify:
+
+```bash
+squad doctor
+```
+
+### Manual Step-by-Step
+
+If you prefer to migrate manually or can't run the CLI yet:
 
 1. **Back up your existing `.squad/` directory:**
 
@@ -93,16 +149,20 @@ This is the biggest jump. The codebase was rewritten in TypeScript, the `.squad/
    cp -r .squad .squad-v054-backup
    ```
 
-2. **Uninstall the old version (if globally installed):**
+2. **Uninstall the old package (if you had it globally):**
 
    ```bash
    npm uninstall -g @bradygaster/create-squad
    ```
 
-3. **Install v0.8.18:**
+3. **Install the latest version:**
 
    ```bash
-   npm install -g @bradygaster/squad-cli@0.8.18
+   # Global
+   npm install -g @bradygaster/squad-cli@latest
+
+   # Project-local
+   npm install --save-dev @bradygaster/squad-cli@latest
    ```
 
 4. **Remove the old `.squad/` directory:**
@@ -114,7 +174,11 @@ This is the biggest jump. The codebase was rewritten in TypeScript, the `.squad/
 5. **Reinitialize:**
 
    ```bash
+   # Global or local install
    squad init
+
+   # npx (no install)
+   npx @bradygaster/squad-cli init
    ```
 
 6. **Manually migrate your customizations.** Open `.squad-v054-backup/` and copy over any custom agent charters, team roster entries, or decisions into the new `.squad/` directory structure. The new format uses Markdown files (not JSON).
@@ -144,8 +208,8 @@ This is the biggest jump. The codebase was rewritten in TypeScript, the `.squad/
 
 ### Key Format Changes
 
-| v0.5.4 | v0.8.18 |
-|--------|---------|
+| v0.5.4 | v0.8.x |
+|--------|--------|
 | `.squad/config.json` | `.squad/team.md` (Markdown with YAML front matter) |
 | JSON decision log | `.squad/decisions.md` (append-only Markdown) |
 | Flat agent files | `.squad/agents/{name}/charter.md` (directory per agent) |
@@ -157,7 +221,11 @@ This is the biggest jump. The codebase was rewritten in TypeScript, the `.squad/
 If you're already on any v0.8.x release, this is a simple update.
 
 ```bash
+# Global
 npm install -g @bradygaster/squad-cli@latest
+
+# Project-local
+npm install --save-dev @bradygaster/squad-cli@latest
 ```
 
 Verify the version:
@@ -166,8 +234,6 @@ Verify the version:
 squad --version
 ```
 
-Expected output: `0.8.18` (or `0.8.18-preview.N`).
-
 Your `.squad/` directory is compatible — no reinitialization needed.
 
 ---
@@ -216,7 +282,21 @@ If you had this in scripts or CI/CD workflows, update every reference.
 
 ## Scenario 6: My .squad/ Directory Broke After Upgrading
 
-If `squad doctor` fails or commands error out after upgrading, follow these steps.
+If `squad doctor` fails or commands error out after upgrading, the fastest fix is `squad migrate`.
+
+### Automated (Recommended)
+
+```bash
+# Global or local install
+squad migrate
+
+# npx (no install)
+npx @bradygaster/squad-cli migrate
+```
+
+Preview first with `--dry-run` if you want to see what it will do before committing.
+
+### Manual
 
 ### 1. Back Up
 
@@ -290,15 +370,15 @@ If you run Squad in GitHub Actions or another CI/CD system, update your workflow
   run: npx github:bradygaster/squad
 ```
 
-### After (v0.8.18)
+### After
 
 ```yaml
 - uses: actions/setup-node@v4
   with:
-    node-version: '18'
+    node-version: '20'
 
 - name: Install Squad
-  run: npm install -g @bradygaster/squad-cli@0.8.18
+  run: npm install -g @bradygaster/squad-cli@latest
 
 - name: Run Squad
   run: squad doctor && squad status
@@ -309,9 +389,9 @@ If you run Squad in GitHub Actions or another CI/CD system, update your workflow
 ### Key CI/CD Notes
 
 - Set `GITHUB_TOKEN` as an environment variable. Squad requires it for GitHub Copilot operations.
-- Pin to a specific version (`@0.8.18`) in CI to avoid surprise upgrades.
-- If you use `npx`, use `npx @bradygaster/squad-cli@0.8.18` with a pinned version.
-- Node.js 18+ is required. Update your workflow's `setup-node` action if needed.
+- Pin to a specific version (e.g., `@0.8.21`) in CI to avoid surprise upgrades.
+- If you use `npx`, use `npx @bradygaster/squad-cli@latest` or a pinned version.
+- Node.js 20+ is required. Update your workflow's `setup-node` action if needed.
 
 ---
 
@@ -428,13 +508,13 @@ Clear the npx cache and retry:
 
 ```bash
 npx clear-npx-cache
-npx @bradygaster/squad-cli@0.8.18
+npx @bradygaster/squad-cli@latest
 ```
 
 Or install globally to bypass npx caching entirely:
 
 ```bash
-npm install -g @bradygaster/squad-cli@0.8.18
+npm install -g @bradygaster/squad-cli@latest
 ```
 
 ### Wrong version installed
@@ -449,7 +529,7 @@ If it shows an old version:
 
 ```bash
 npm uninstall -g @bradygaster/squad-cli
-npm install -g @bradygaster/squad-cli@0.8.18
+npm install -g @bradygaster/squad-cli@latest
 ```
 
 ### Team roster gone after upgrade
@@ -473,54 +553,55 @@ Common causes:
 
 - Missing `.squad/` directory — run `squad init`.
 - Missing `GITHUB_TOKEN` — see [GITHUB_TOKEN issues](#github_token-issues) above.
-- Node.js too old — upgrade to Node.js 18+.
+- Node.js too old — upgrade to Node.js 20+.
 - Corrupted `.squad/` files — back up, remove, and reinitialize.
 
 ### Node.js version too old
 
-Squad requires Node.js 18 or later. Check your version:
+Squad requires Node.js 20 or later. Check your version:
 
 ```bash
 node --version
 ```
 
-If below 18, upgrade via [nodejs.org](https://nodejs.org/) or your preferred version manager:
+If below 20, upgrade via [nodejs.org](https://nodejs.org/) or your preferred version manager:
 
 ```bash
 # nvm
-nvm install 18
-nvm use 18
+nvm install 20
+nvm use 20
 
 # fnm
-fnm install 18
-fnm use 18
+fnm install 20
+fnm use 20
 ```
 
 ---
 
 ## Rolling Back
 
-If you need to downgrade from v0.8.18:
+If you need to downgrade from the current version, specify the version you want:
 
 ```bash
-npm install -g @bradygaster/squad-cli@0.8.17
+npm install -g @bradygaster/squad-cli@0.8.18
 ```
 
 ### Warnings
 
 - **The GitHub-native distribution (`npx github:bradygaster/squad`) is permanently removed.** You cannot roll back to that install method.
 - **`.squad/` directory format changed between v0.5.4 and v0.8.x.** If you roll back to v0.5.4, your current `.squad/` directory will not be compatible. Keep backups.
-- Rolling back within the v0.8.x line (e.g., 0.8.18 to 0.8.17) should be safe — the `.squad/` format is stable across v0.8.x releases.
+- Rolling back within the v0.8.x line (e.g., 0.8.21 to 0.8.18) should be safe — the `.squad/` format is stable across v0.8.x releases.
 
 ---
 
-## What's New in v0.8.18
+## What's New in v0.8.21+
 
+- **`squad migrate`:** New command for automated backup, clean, and reinit — the recommended path for any major version migration.
+- **Shell `/init` fix:** The interactive shell now scaffolds `.squad/` automatically if it's missing, so `/init "description"` works even after deleting the directory.
 - **Remote Squad Mode:** `squad link`, `squad init --mode remote`, and dual-root path resolution for team identity directories.
 - **`squad doctor`:** 9-check setup validation with clear pass/fail output.
 - **npm-only distribution:** Simpler install, semantic versioning, stable and insider channels.
 - **TypeScript strict mode:** Full type safety across the SDK and CLI.
-- **Semver fix:** Version format now follows the semver spec (`0.8.18-preview.N` instead of `0.8.18.N-preview`).
 
 For the full list of changes, see the [CHANGELOG](../CHANGELOG.md).
 
diff --git a/docs/scenarios/troubleshooting.md b/docs/scenarios/troubleshooting.md
index 89763683f..62f2dce5d 100644
--- a/docs/scenarios/troubleshooting.md
+++ b/docs/scenarios/troubleshooting.md
@@ -4,35 +4,6 @@ Common issues and fixes for Squad installation and usage.
 
 ---
 
-## `npx github:bradygaster/squad` appears to hang
-
-**Problem:** Running the install command shows a frozen npm spinner. Nothing happens.
-
-**Cause:** npm resolves `github:` package specifiers via `git+ssh://git@github.com/...`. If no SSH agent is running (or your key isn't loaded), git prompts for your passphrase on the TTY — but npm's progress spinner overwrites the prompt, making it invisible. This is an npm TTY handling issue, not a Squad bug.
-
-**Fix (choose one):**
-
-1. **Start your SSH agent first** (recommended):
-   ```bash
-   eval "$(ssh-agent -s)"
-   ssh-add
-   ```
-   Then re-run `npx github:bradygaster/squad`.
-
-2. **Disable npm's progress spinner** to reveal the prompt:
-   ```bash
-   npx --progress=false github:bradygaster/squad
-   ```
-
-3. **Use HTTPS instead of SSH** by configuring git:
-   ```bash
-   git config --global url."https://github.com/".insteadOf git@github.com:
-   ```
-
-**Reference:** [#30](https://github.com/bradygaster/squad/issues/30)
-
----
-
 ## `gh` CLI not authenticated
 
 **Problem:** GitHub Issues, PRs, Ralph, or Project Boards commands fail with authentication errors.
@@ -60,9 +31,9 @@ Common issues and fixes for Squad installation and usage.
 
 ## Node.js version too old
 
-**Problem:** `npx github:bradygaster/squad` fails with an engine compatibility error, or Squad behaves unexpectedly.
+**Problem:** Squad fails with an engine compatibility error, or behaves unexpectedly.
 
-**Cause:** Squad requires Node.js 22.0.0 or later (enforced via `engines` in `package.json`).
+**Cause:** Squad requires Node.js 20 or later (enforced via `engines` in `package.json`).
 
 **Fix:**
 
@@ -70,9 +41,9 @@ Common issues and fixes for Squad installation and usage.
 node --version
 ```
 
-If below v22, upgrade Node.js:
-- **nvm (macOS/Linux):** `nvm install 22 && nvm use 22`
-- **nvm-windows:** `nvm install 22 && nvm use 22`
+If below v20, upgrade Node.js:
+- **nvm (macOS/Linux):** `nvm install 20 && nvm use 20`
+- **nvm-windows:** `nvm install 20 && nvm use 20`
 - **Direct download:** [nodejs.org](https://nodejs.org/)
 
 ---
@@ -89,7 +60,7 @@ If below v22, upgrade Node.js:
    ```bash
    ls .github/agents/squad.agent.md
    ```
-   If missing, re-run `npx github:bradygaster/squad`.
+   If missing, re-run `squad init` (or `npx @bradygaster/squad-cli init`).
 
 2. Restart your Copilot session — close and reopen the terminal or editor.
 
@@ -97,17 +68,20 @@ If below v22, upgrade Node.js:
 
 ## Upgrade doesn't change anything
 
-**Problem:** Running `npx github:bradygaster/squad upgrade` completes but nothing changes.
+**Problem:** Running `squad upgrade` completes but nothing changes.
 
 **Cause:** You may already be on the latest version, or npm cached an old version.
 
 **Fix:**
 
-1. Check current version in `.github/agents/squad.agent.md` (frontmatter `version:` field).
+1. Check current version:
+   ```bash
+   squad --version
+   ```
 
-2. Clear npm cache and retry:
+2. If stale, clear the npm cache and reinstall:
    ```bash
-   npx --yes github:bradygaster/squad upgrade
+   npm install -g @bradygaster/squad-cli@latest
    ```
 
 ---
diff --git a/docs/scenarios/upgrading.md b/docs/scenarios/upgrading.md
index 75b93a91a..9f721ef31 100644
--- a/docs/scenarios/upgrading.md
+++ b/docs/scenarios/upgrading.md
@@ -9,18 +9,25 @@ Update Squad-owned files to the latest version without touching your team state.
 From your repo root:
 
 ```bash
-npx github:bradygaster/squad upgrade
+# Global install
+squad upgrade
+
+# Local install (npm --save-dev)
+npx squad upgrade
+
+# One-off (no install)
+npx @bradygaster/squad-cli upgrade
 ```
 
 Squad detects your installed version, updates Squad-owned files, and runs any needed migrations:
 
 ```
-✅ upgraded coordinator from 0.1.0 to 0.2.0
-✅ upgraded .ai-team-templates/
+✅ upgraded coordinator from 0.8.18 to 0.8.21
+✅ upgraded .squad/templates/
 
-.ai-team/ untouched — your team state is safe
+.squad/ untouched — your team state is safe
 
-Squad is upgraded. (v0.2.0)
+Squad is upgraded. (v0.8.21)
 ```
 
 That's it.
@@ -32,14 +39,14 @@ That's it.
 | File | Updated? | Notes |
 |------|----------|-------|
 | `.github/agents/squad.agent.md` | ✅ Yes | Overwritten with latest coordinator logic |
-| `.ai-team-templates/` | ✅ Yes | Overwritten with latest templates |
+| `.squad/templates/` | ✅ Yes | Overwritten with latest templates |
 | `.github/workflows/squad-*.yml` | ✅ Yes | Overwritten with latest squad workflows |
 | `.github/copilot-instructions.md` | ⚡ Conditional | Updated only if @copilot is enabled on the team |
-| `.ai-team/` | ❌ Never | Your team's knowledge, decisions, casting state, skills |
+| `.squad/` | ❌ Never | Your team's knowledge, decisions, casting state, skills |
 
-Squad-owned files (`squad.agent.md` and `.ai-team-templates/`) are replaced entirely. Don't put custom changes in them — they'll be lost on upgrade.
+Squad-owned files (`squad.agent.md` and `.squad/templates/`) are replaced entirely. Don't put custom changes in them — they'll be lost on upgrade.
 
-Your team state in `.ai-team/` is never touched. Agent charters, histories, decisions, casting state, skills, and session logs are all safe.
+Your team state in `.squad/` is never touched. Agent charters, histories, decisions, casting state, skills, and session logs are all safe.
 
 ---
 
@@ -51,40 +58,21 @@ Migrations are:
 - **Additive** — they only create new files or directories, never modify existing ones
 - **Idempotent** — safe to re-run; if the change already exists, it's skipped
 
-Example: upgrading to v0.2.0 creates `.ai-team/skills/` if it doesn't already exist.
-
 ---
 
-## Migrating .ai-team/ → .squad/ (v0.5.0+)
-
-In Squad v0.5.0, the team state directory was renamed from `.ai-team/` to `.squad/`. Existing repos continue to work — Squad detects both. If you're still on `.ai-team/`, you'll see a deprecation warning.
-
-**To migrate your repo:**
-
-```bash
-# Step 1: Upgrade to get the latest migration tooling
-npx github:bradygaster/squad upgrade
-
-# Step 2: Rename the directory
-npx github:bradygaster/squad upgrade --migrate-directory
-```
+## Migrating .ai-team/ → .squad/
 
-Then commit:
+Very early versions of Squad used `.ai-team/` instead of `.squad/`. The `upgrade --migrate-directory` flag handles this rename:
 
 ```bash
-git add -A
-git commit -m "chore: migrate .ai-team/ → .squad/"
+squad upgrade --migrate-directory
 ```
 
-**What the migration does:**
+What it does:
 - Renames `.ai-team/` → `.squad/`
 - Updates `.gitignore` and `.gitattributes` references
 - Scrubs email addresses from migrated files (PII cleanup)
 
-**Timeline:** `.ai-team/` support continues through v0.6.0. Migration becomes required in v1.0.0.
-
-**Full details:** See the [Migration Guide](../migration/v0.5.0-squad-rename.md).
-
 ---
 
 ## Version Stamping
@@ -95,56 +83,47 @@ git commit -m "chore: migrate .ai-team/ → .squad/"
 
 The version is displayed in the agent picker across all Copilot hosts (VS Code, CLI, Visual Studio):
 
-```yaml
-name: Squad (vX.Y.Z)
+```
+Squad (vX.Y.Z)
 ```
 
 When you select agents in Copilot, you'll see **"Squad (vX.Y.Z)"** in the dropdown — making it immediately clear which version you're running.
 
-### 2. Version Field (For Reference)
-
-The frontmatter also includes a standalone version field:
-
-```yaml
-version: "X.Y.Z"
-```
-
-### 3. CLI Check
+### 2. CLI Check
 
 You can also check your installed version from the command line:
 
 ```bash
-npx github:bradygaster/squad --version
-```
+# Global install
+squad --version
 
-The output will show your installed version (e.g., `X.Y.Z`).
+# Local install
+npx squad --version
+
+# One-off
+npx @bradygaster/squad-cli --version
+```
 
 ---
 
 ## Already Up to Date
 
-If you're already on the latest version:
+If you're already on the latest version, `squad upgrade` reports it and still runs any pending migrations:
 
-```bash
-npx github:bradygaster/squad upgrade
 ```
-
+✅ Already up to date (v0.8.21)
 ```
-✅ Already up to date (v0.2.0)
-```
-
-Squad still runs any missing migrations in case a prior upgrade was interrupted.
 
 ---
 
 ## 2. Commit the Upgrade
 
 ```bash
-git add .github/agents/squad.agent.md .ai-team-templates/
-git commit -m "Upgrade Squad to v0.2.0"
+git add .github/agents/squad.agent.md .squad/templates/
+git commit -m "Upgrade Squad to vX.Y.Z"
 ```
 
-No changes to `.ai-team/` — the diff is limited to Squad-owned files.
+No changes to `.squad/` — the diff is limited to Squad-owned files.
 
 ---
 
@@ -153,3 +132,4 @@ No changes to `.ai-team/` — the diff is limited to Squad-owned files.
 - **Upgrade is safe.** It only overwrites files that Squad owns. Your team state is never modified.
 - **Don't customize `squad.agent.md`.** Any changes you make will be overwritten on the next upgrade. If you need custom behavior, use directives in `decisions.md` instead.
 - **Re-running upgrade is harmless.** If you're not sure whether an upgrade completed, run it again. It's idempotent.
+- **After a major version jump**, consider running `squad migrate` instead of `squad upgrade` — it performs a full backup, clean, and reinit in one step. See the [Migration Guide](../get-started/migration.md).
diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts
index e0989212e..90ddb867a 100644
--- a/packages/squad-cli/src/cli-entry.ts
+++ b/packages/squad-cli/src/cli-entry.ts
@@ -43,6 +43,8 @@ async function main(): Promise<void> {
     console.log(`             Overwrites: squad.agent.md, templates dir (.squad/templates/)`);
     console.log(`             Never touches: .squad/ or .ai-team/ (your team state)`);
     console.log(`             Flags: --global (upgrade personal squad), --migrate-directory (rename .ai-team/ → .squad/)`);
+    console.log(`  ${BOLD}migrate${RESET}    Back up, clean, and reinitialize .squad/ (version migration helper)`);
+    console.log(`             Flags: --dry-run (preview), --backup-dir <path> (custom backup location)`);
     console.log(`  ${BOLD}status${RESET}     Show which squad is active and why`);
     console.log(`  ${BOLD}triage${RESET}     Scan for work and categorize issues`);
     console.log(`             Usage: triage [--interval <minutes>]`);
@@ -61,7 +63,7 @@ async function main(): Promise<void> {
     console.log(`  ${BOLD}import${RESET}     Import squad from an export file`);
     console.log(`             Usage: import <file> [--force]`);
     console.log(`  ${BOLD}scrub-emails${RESET}  Remove email addresses from Squad state files`);
-    console.log(`             Usage: scrub-emails [directory] (default: .ai-team/)`);
+    console.log(`             Usage: scrub-emails [directory] (default: .squad/)`);
     console.log(`  ${BOLD}start${RESET}      Start Copilot with remote access from phone/browser`);
     console.log(`             Usage: start [--tunnel] [--port <n>] [--command <cmd>] [copilot flags...]`);
     console.log(`             Examples: start --tunnel --yolo`);
@@ -191,7 +193,7 @@ async function main(): Promise<void> {
 
   if (cmd === 'scrub-emails') {
     const { scrubEmails } = await import('./cli/core/email-scrub.js');
-    const targetDir = args[1] || '.ai-team';
+    const targetDir = args[1] || '.squad';
     const count = await scrubEmails(targetDir);
     if (count > 0) {
       console.log(`Scrubbed ${count} email address(es).`);
@@ -201,6 +203,15 @@ async function main(): Promise<void> {
     return;
   }
 
+  if (cmd === 'migrate') {
+    const { runMigrate } = await import('./cli/core/migrate.js');
+    const dryRun = args.includes('--dry-run');
+    const backupDirIdx = args.indexOf('--backup-dir');
+    const backupDir = backupDirIdx !== -1 ? args[backupDirIdx + 1] : undefined;
+    await runMigrate(process.cwd(), { dryRun, backupDir });
+    return;
+  }
+
   if (cmd === 'status') {
     const repoSquad = resolveSquad(process.cwd());
     const globalPath = resolveGlobalSquadPath();
diff --git a/packages/squad-cli/src/cli/core/migrate.ts b/packages/squad-cli/src/cli/core/migrate.ts
new file mode 100644
index 000000000..3a7deb160
--- /dev/null
+++ b/packages/squad-cli/src/cli/core/migrate.ts
@@ -0,0 +1,213 @@
+/**
+ * Squad migrate command — backs up, cleans, and reinitialises .squad/
+ * Safe for all install methods: global npm, local npm, npx.
+ * @module cli/core/migrate
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { initSquad as sdkInitSquad } from '@bradygaster/squad-sdk';
+import { success, warn, info, DIM, BOLD, RESET } from './output.js';
+import { getPackageVersion } from './version.js';
+
+export interface MigrateOptions {
+  /** Preview what would happen without making changes. */
+  dryRun?: boolean;
+  /** Custom directory to write the backup into. Defaults to .squad-backup-{timestamp}/ */
+  backupDir?: string;
+}
+
+/** Files and directories that Squad owns and regenerates — never restored from backup. */
+const SQUAD_OWNED = [
+  'templates',
+  'casting',
+];
+
+/** Files and directories that belong to the user — restored from backup after reinit. */
+const USER_OWNED = [
+  'agents',
+  'decisions.md',
+  'decisions',
+  'routing.md',
+  'team.md',
+  'skills',
+  'log',
+  'orchestration-log',
+  'identity',
+];
+
+function formatTimestamp(): string {
+  const now = new Date();
+  return now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+}
+
+function copyRecursive(src: string, dest: string): void {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+  }
+}
+
+function removeRecursive(target: string): void {
+  if (!fs.existsSync(target)) return;
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+export async function runMigrate(cwd: string, options: MigrateOptions = {}): Promise<void> {
+  const { dryRun = false } = options;
+
+  const prefix = dryRun ? `${DIM}[dry-run]${RESET} ` : '';
+
+  console.log();
+  console.log(`${BOLD}Squad Migrate${RESET}${dryRun ? ` ${DIM}(dry-run — no changes will be made)${RESET}` : ''}`);
+  console.log();
+
+  // Detect the squad directory — support both .squad/ and legacy .ai-team/
+  let squadDir = path.join(cwd, '.squad');
+  const legacyDir = path.join(cwd, '.ai-team');
+
+  if (!fs.existsSync(squadDir)) {
+    if (fs.existsSync(legacyDir)) {
+      warn(`Found legacy .ai-team/ directory. This migration will move it to .squad/.`);
+      squadDir = legacyDir;
+    } else {
+      info('No .squad/ or .ai-team/ directory found. Running a fresh init instead.');
+      if (!dryRun) {
+        const version = getPackageVersion();
+        await sdkInitSquad({
+          teamRoot: cwd,
+          projectName: path.basename(cwd) || 'my-project',
+          agents: [{ name: 'scribe', role: 'scribe', displayName: 'Scribe' }],
+          skipExisting: true,
+          includeWorkflows: true,
+          includeTemplates: true,
+          version,
+        });
+        success('Initialized fresh .squad/ directory.');
+      } else {
+        console.log(`${prefix}Would run: squad init`);
+      }
+      return;
+    }
+  }
+
+  // Step 1: Back up
+  const timestamp = formatTimestamp();
+  const backupRoot = options.backupDir
+    ? path.resolve(cwd, options.backupDir)
+    : path.join(cwd, `.squad-backup-${timestamp}`);
+
+  console.log(`  Step 1/4  Backup`);
+  console.log(`           ${squadDir}`);
+  console.log(`        →  ${backupRoot}`);
+  console.log();
+
+  if (!dryRun) {
+    if (fs.existsSync(backupRoot)) {
+      warn(`Backup directory already exists: ${backupRoot}`);
+      process.exit(1);
+    }
+    copyRecursive(squadDir, backupRoot);
+    success(`Backed up to ${path.relative(cwd, backupRoot)}/`);
+  } else {
+    console.log(`${prefix}Would copy ${path.relative(cwd, squadDir)}/ → ${path.relative(cwd, backupRoot)}/`);
+  }
+
+  // Step 2: Remove squad-owned files from the existing directory
+  console.log();
+  console.log(`  Step 2/4  Remove Squad-owned files`);
+
+  for (const owned of SQUAD_OWNED) {
+    const target = path.join(squadDir, owned);
+    if (fs.existsSync(target)) {
+      if (!dryRun) {
+        removeRecursive(target);
+        console.log(`           removed: ${path.relative(cwd, target)}`);
+      } else {
+        console.log(`${prefix}Would remove: ${path.relative(cwd, target)}`);
+      }
+    }
+  }
+
+  // Also remove the top-level squad.agent.md (Squad-owned in project root)
+  const agentFile = path.join(cwd, '.github', 'agents', 'squad.agent.md');
+  if (fs.existsSync(agentFile)) {
+    if (!dryRun) {
+      removeRecursive(agentFile);
+      console.log(`           removed: ${path.relative(cwd, agentFile)}`);
+    } else {
+      console.log(`${prefix}Would remove: ${path.relative(cwd, agentFile)}`);
+    }
+  }
+
+  // If migrating from .ai-team/, remove it entirely now (after backup)
+  if (squadDir === legacyDir) {
+    if (!dryRun) {
+      removeRecursive(legacyDir);
+      console.log(`           removed legacy: .ai-team/`);
+    } else {
+      console.log(`${prefix}Would remove: .ai-team/`);
+    }
+  }
+
+  // Step 3: Reinitialize
+  console.log();
+  console.log(`  Step 3/4  Reinitialize .squad/`);
+
+  if (!dryRun) {
+    const version = getPackageVersion();
+    await sdkInitSquad({
+      teamRoot: cwd,
+      projectName: path.basename(cwd) || 'my-project',
+      agents: [{ name: 'scribe', role: 'scribe', displayName: 'Scribe' }],
+      skipExisting: true,
+      includeWorkflows: true,
+      includeTemplates: true,
+      version,
+    });
+    success('Scaffolded fresh .squad/ directory.');
+  } else {
+    console.log(`${prefix}Would run: sdkInitSquad (fresh scaffold)`);
+  }
+
+  // Step 4: Restore user-owned files
+  console.log();
+  console.log(`  Step 4/4  Restore user files from backup`);
+
+  for (const userFile of USER_OWNED) {
+    const backupSrc = path.join(backupRoot, userFile);
+    const restoreDest = path.join(cwd, '.squad', userFile);
+
+    if (!fs.existsSync(backupSrc)) continue;
+
+    if (!dryRun) {
+      // Skip if reinit already wrote this file and the user had nothing custom
+      // (user-owned files that exist in the fresh scaffold are still overwritten by the backup)
+      copyRecursive(backupSrc, restoreDest);
+      console.log(`           restored: .squad/${userFile}`);
+    } else {
+      console.log(`${prefix}Would restore: backup/${userFile} → .squad/${userFile}`);
+    }
+  }
+
+  console.log();
+  if (dryRun) {
+    console.log(`${DIM}Dry run complete. No changes were made.${RESET}`);
+    console.log(`${DIM}Run without --dry-run to apply.${RESET}`);
+  } else {
+    success('Migration complete.');
+    console.log();
+    console.log(`  Your backup is at: ${DIM}${path.relative(cwd, backupRoot)}/${RESET}`);
+    console.log(`  Run ${BOLD}squad doctor${RESET} to verify the new setup.`);
+    console.log();
+    console.log(`  ${DIM}When you're happy everything works, you can delete the backup:${RESET}`);
+    console.log(`  ${DIM}  rm -rf ${path.relative(cwd, backupRoot)}${RESET}`);
+  }
+  console.log();
+}
diff --git a/packages/squad-cli/src/cli/shell/index.ts b/packages/squad-cli/src/cli/shell/index.ts
index 101b37d4b..bb2015808 100644
--- a/packages/squad-cli/src/cli/shell/index.ts
+++ b/packages/squad-cli/src/cli/shell/index.ts
@@ -7,7 +7,7 @@
 
 import { createRequire } from 'node:module';
 import { existsSync, readFileSync, unlinkSync } from 'node:fs';
-import { join, resolve as pathResolve } from 'node:path';
+import { join, resolve as pathResolve, basename } from 'node:path';
 import React from 'react';
 import { render } from 'ink';
 import { App } from './components/App.js';
@@ -21,7 +21,7 @@ import { SquadClient } from '@bradygaster/squad-sdk/client';
 import type { SquadSession } from '@bradygaster/squad-sdk/client';
 import type { SquadPermissionHandler } from '@bradygaster/squad-sdk/client';
 import type { ShellMessage } from './types.js';
-import { initSquadTelemetry, TIMEOUTS, StreamingPipeline, recordAgentSpawn, recordAgentDuration, recordAgentError, recordAgentDestroy, RuntimeEventBus } from '@bradygaster/squad-sdk';
+import { initSquad as sdkInitSquad, initSquadTelemetry, TIMEOUTS, StreamingPipeline, recordAgentSpawn, recordAgentDuration, recordAgentError, recordAgentDestroy, RuntimeEventBus } from '@bradygaster/squad-sdk';
 import type { UsageEvent } from '@bradygaster/squad-sdk';
 import { enableShellMetrics, recordShellSessionDuration, recordAgentResponseLatency, recordShellError } from './shell-metrics.js';
 import { buildCoordinatorPrompt, buildInitModePrompt, parseCoordinatorResponse, hasRosterEntries } from './coordinator.js';
@@ -1001,15 +1001,23 @@ export async function runShell(): Promise<void> {
       return;
     }
 
-    // Guard: require a Squad team before processing work requests
+    // Guard: require a Squad team before processing work requests.
+    // If .squad/ is missing entirely, scaffold it so /init and plain messages work.
     const teamFile = join(teamRoot, '.squad', 'team.md');
     if (!existsSync(teamFile)) {
-      shellApi?.addMessage({
-        role: 'system',
-        content: '\u26A0 No Squad team found. Run /init to create your team first.',
-        timestamp: new Date(),
-      });
-      return;
+      try {
+        await sdkInitSquad({
+          teamRoot,
+          projectName: basename(teamRoot) || 'my-project',
+          agents: [{ name: 'scribe', role: 'scribe', displayName: 'Scribe' }],
+          skipExisting: true,
+          includeWorkflows: true,
+          includeTemplates: true,
+          version: pkg.version,
+        });
+      } catch {
+        // If scaffold fails, fall through — the roster check below will enter init mode
+      }
     }
 
     // Check if roster is actually populated — if not, enter Init Mode (cast a team)
diff --git a/test/init-autocast.test.ts b/test/init-autocast.test.ts
index b0d255dfb..23bc1b009 100644
--- a/test/init-autocast.test.ts
+++ b/test/init-autocast.test.ts
@@ -174,7 +174,7 @@ describe('auto-cast trigger conditions', () => {
     // Missing .init-prompt → auto-cast must NOT fire
   });
 
-  it('auto-cast should NOT fire: team.md does not exist at all', () => {
+  it('auto-cast should fire after scaffold: team.md does not exist at all', () => {
     // Setup: no team.md, just .init-prompt
     fs.writeFileSync(path.join(squadDir, '.init-prompt'), 'Build something');
 
@@ -183,7 +183,8 @@ describe('auto-cast trigger conditions', () => {
 
     expect(teamFileExists).toBe(false);
     expect(initPromptExists).toBe(true);
-    // No team.md → auto-cast guard in index.ts (line 906) prevents firing
+    // No team.md → shell scaffolds .squad/ first (creating team.md with empty roster),
+    // then falls through to handleInitCast which uses the stored .init-prompt.
   });
 
   it('stored .init-prompt content is trimmed before use', () => {

From 24d96505fa298824fc550afaab4ba64405594c8d Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 13:08:11 +1000
Subject: [PATCH 02/12] docs: add backup restoration steps to migration guide

- Add 'If Something Went Wrong' subsection to Scenario 2 showing
  how to restore from the .squad-backup-{timestamp}/ backup
- Add 'How do I restore from a migrate backup?' troubleshooting entry
  with ls -d tip for finding the backup folder

Closes #197 (partial)
---
 docs/get-started/migration.md | 42 +++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/get-started/migration.md b/docs/get-started/migration.md
index 38179e843..81ebc8501 100644
--- a/docs/get-started/migration.md
+++ b/docs/get-started/migration.md
@@ -139,6 +139,30 @@ Then verify:
 squad doctor
 ```
 
+#### If Something Went Wrong
+
+Your backup is still intact at `.squad-backup-{timestamp}/`. To fully restore your previous state:
+
+```bash
+# Remove the new .squad/ directory
+rm -rf .squad
+
+# Restore from backup (replace the timestamp with your actual backup folder name)
+cp -r .squad-backup-{timestamp} .squad
+```
+
+Once restored, you can retry the migration or revert to your previous Squad version:
+
+```bash
+npm install -g @bradygaster/squad-cli@0.8.18
+```
+
+When you're satisfied everything works, you can delete the backup:
+
+```bash
+rm -rf .squad-backup-{timestamp}
+```
+
 ### Manual Step-by-Step
 
 If you prefer to migrate manually or can't run the CLI yet:
@@ -532,6 +556,24 @@ npm uninstall -g @bradygaster/squad-cli
 npm install -g @bradygaster/squad-cli@latest
 ```
 
+### How do I restore from a `squad migrate` backup?
+
+`squad migrate` saves a full backup to `.squad-backup-{timestamp}/` before making any changes. To restore:
+
+```bash
+# Remove the current .squad/ directory
+rm -rf .squad
+
+# Restore from backup (use your actual backup folder name)
+cp -r .squad-backup-{timestamp} .squad
+```
+
+To find your backup folder if you've forgotten the timestamp:
+
+```bash
+ls -d .squad-backup-*/
+```
+
 ### Team roster gone after upgrade
 
 Your `.squad/team.md` may not have survived the upgrade. Reinitialize and restore from backup:

From 3248cf867b8ee0f774757257cb2842d2143eeadc Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 13:23:35 +1000
Subject: [PATCH 03/12] fix(migrate): add --restore flag and auto-rollback on
 error

- Add runRestore() to restore the entire .squad/ from a backup snapshot
- squad migrate --restore auto-detects the most recent .squad-backup-*/
- squad migrate --restore <path> restores from a specific backup
- Wrap migration steps 2-4 in try/catch: on any error, auto-restore the
  backup and exit with a clear message before the user is left stranded
- Update docs to replace manual rm/cp restore instructions with
  squad migrate --restore
- Update help text to document the new --restore flag
---
 docs/get-started/migration.md              |  26 +--
 packages/squad-cli/src/cli-entry.ts        |  10 +-
 packages/squad-cli/src/cli/core/migrate.ts | 193 +++++++++++++++------
 3 files changed, 161 insertions(+), 68 deletions(-)

diff --git a/docs/get-started/migration.md b/docs/get-started/migration.md
index 81ebc8501..a7c6ab625 100644
--- a/docs/get-started/migration.md
+++ b/docs/get-started/migration.md
@@ -141,14 +141,16 @@ squad doctor
 
 #### If Something Went Wrong
 
-Your backup is still intact at `.squad-backup-{timestamp}/`. To fully restore your previous state:
+Your backup is still intact at `.squad-backup-{timestamp}/`. To fully restore your previous state in one command:
 
 ```bash
-# Remove the new .squad/ directory
-rm -rf .squad
+squad migrate --restore
+```
 
-# Restore from backup (replace the timestamp with your actual backup folder name)
-cp -r .squad-backup-{timestamp} .squad
+This auto-detects the most recent backup and restores it. To restore from a specific backup:
+
+```bash
+squad migrate --restore .squad-backup-{timestamp}
 ```
 
 Once restored, you can retry the migration or revert to your previous Squad version:
@@ -558,17 +560,19 @@ npm install -g @bradygaster/squad-cli@latest
 
 ### How do I restore from a `squad migrate` backup?
 
-`squad migrate` saves a full backup to `.squad-backup-{timestamp}/` before making any changes. To restore:
+`squad migrate` saves a full backup to `.squad-backup-{timestamp}/` before making any changes. To restore in one command:
 
 ```bash
-# Remove the current .squad/ directory
-rm -rf .squad
+squad migrate --restore
+```
 
-# Restore from backup (use your actual backup folder name)
-cp -r .squad-backup-{timestamp} .squad
+This auto-detects the most recent backup. To restore from a specific backup:
+
+```bash
+squad migrate --restore .squad-backup-{timestamp}
 ```
 
-To find your backup folder if you've forgotten the timestamp:
+To find available backups:
 
 ```bash
 ls -d .squad-backup-*/
diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts
index 90ddb867a..a6d91550d 100644
--- a/packages/squad-cli/src/cli-entry.ts
+++ b/packages/squad-cli/src/cli-entry.ts
@@ -45,6 +45,7 @@ async function main(): Promise<void> {
     console.log(`             Flags: --global (upgrade personal squad), --migrate-directory (rename .ai-team/ → .squad/)`);
     console.log(`  ${BOLD}migrate${RESET}    Back up, clean, and reinitialize .squad/ (version migration helper)`);
     console.log(`             Flags: --dry-run (preview), --backup-dir <path> (custom backup location)`);
+    console.log(`                    --restore [path] (restore from backup; auto-detects latest if no path given)`);
     console.log(`  ${BOLD}status${RESET}     Show which squad is active and why`);
     console.log(`  ${BOLD}triage${RESET}     Scan for work and categorize issues`);
     console.log(`             Usage: triage [--interval <minutes>]`);
@@ -208,7 +209,14 @@ async function main(): Promise<void> {
     const dryRun = args.includes('--dry-run');
     const backupDirIdx = args.indexOf('--backup-dir');
     const backupDir = backupDirIdx !== -1 ? args[backupDirIdx + 1] : undefined;
-    await runMigrate(process.cwd(), { dryRun, backupDir });
+    const restoreIdx = args.indexOf('--restore');
+    let restore: boolean | string | undefined;
+    if (restoreIdx !== -1) {
+      // --restore with an optional path argument (path won't start with --)
+      const restoreArg = args[restoreIdx + 1];
+      restore = (restoreArg && !restoreArg.startsWith('--')) ? restoreArg : true;
+    }
+    await runMigrate(process.cwd(), { dryRun, backupDir, restore });
     return;
   }
 
diff --git a/packages/squad-cli/src/cli/core/migrate.ts b/packages/squad-cli/src/cli/core/migrate.ts
index 3a7deb160..9683cd96f 100644
--- a/packages/squad-cli/src/cli/core/migrate.ts
+++ b/packages/squad-cli/src/cli/core/migrate.ts
@@ -15,6 +15,12 @@ export interface MigrateOptions {
   dryRun?: boolean;
   /** Custom directory to write the backup into. Defaults to .squad-backup-{timestamp}/ */
   backupDir?: string;
+  /**
+   * Restore from a backup instead of running a migration.
+   * - true  → auto-detect the most recent .squad-backup-{timestamp} directory
+   * - string → path to a specific backup directory
+   */
+  restore?: boolean | string;
 }
 
 /** Files and directories that Squad owns and regenerates — never restored from backup. */
@@ -41,6 +47,58 @@ function formatTimestamp(): string {
   return now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
 }
 
+/** Find the most recently created .squad-backup-{timestamp} directory, or return undefined. */
+function findLatestBackup(cwd: string): string | undefined {
+  const entries = fs.existsSync(cwd) ? fs.readdirSync(cwd) : [];
+  const backups = entries
+    .filter((e) => e.startsWith('.squad-backup-'))
+    .map((e) => path.join(cwd, e))
+    .filter((p) => fs.statSync(p).isDirectory())
+    .sort(); // ISO timestamp suffix → lexicographic sort = chronological
+  return backups.length > 0 ? backups[backups.length - 1] : undefined;
+}
+
+/**
+ * Restore a previous .squad/ directory from a backup snapshot.
+ * Removes the current .squad/ and replaces it with the backup contents.
+ */
+async function runRestore(cwd: string, backupPath?: string): Promise<void> {
+  console.log();
+  console.log(`${BOLD}Squad Migrate --restore${RESET}`);
+  console.log();
+
+  const squadDir = path.join(cwd, '.squad');
+
+  // Resolve which backup to use
+  let resolvedBackup: string | undefined;
+  if (backupPath) {
+    resolvedBackup = path.resolve(cwd, backupPath);
+  } else {
+    resolvedBackup = findLatestBackup(cwd);
+  }
+
+  if (!resolvedBackup || !fs.existsSync(resolvedBackup)) {
+    const tried = backupPath ? path.resolve(cwd, backupPath) : '.squad-backup-*/';
+    console.error(`Error: No backup found at ${tried}`);
+    console.error('');
+    console.error('List available backups with:');
+    console.error('  ls -d .squad-backup-*/');
+    process.exit(1);
+  }
+
+  console.log(`  Restoring from: ${DIM}${path.relative(cwd, resolvedBackup)}/${RESET}`);
+  console.log(`  Restoring to:   ${DIM}.squad/${RESET}`);
+  console.log();
+
+  removeRecursive(squadDir);
+  copyRecursive(resolvedBackup, squadDir);
+
+  success(`Restored .squad/ from ${path.relative(cwd, resolvedBackup)}/`);
+  console.log();
+  console.log(`  Run ${BOLD}squad doctor${RESET} to verify.`);
+  console.log();
+}
+
 function copyRecursive(src: string, dest: string): void {
   const stat = fs.statSync(src);
   if (stat.isDirectory()) {
@@ -62,6 +120,13 @@ function removeRecursive(target: string): void {
 export async function runMigrate(cwd: string, options: MigrateOptions = {}): Promise<void> {
   const { dryRun = false } = options;
 
+  // --restore mode: find backup and reinstate it
+  if (options.restore !== undefined && options.restore !== false) {
+    const backupPath = typeof options.restore === 'string' ? options.restore : undefined;
+    await runRestore(cwd, backupPath);
+    return;
+  }
+
   const prefix = dryRun ? `${DIM}[dry-run]${RESET} ` : '';
 
   console.log();
@@ -123,77 +188,93 @@ export async function runMigrate(cwd: string, options: MigrateOptions = {}): Pro
   console.log();
   console.log(`  Step 2/4  Remove Squad-owned files`);
 
-  for (const owned of SQUAD_OWNED) {
-    const target = path.join(squadDir, owned);
-    if (fs.existsSync(target)) {
+  try {
+    for (const owned of SQUAD_OWNED) {
+      const target = path.join(squadDir, owned);
+      if (fs.existsSync(target)) {
+        if (!dryRun) {
+          removeRecursive(target);
+          console.log(`           removed: ${path.relative(cwd, target)}`);
+        } else {
+          console.log(`${prefix}Would remove: ${path.relative(cwd, target)}`);
+        }
+      }
+    }
+
+    // Also remove the top-level squad.agent.md (Squad-owned in project root)
+    const agentFile = path.join(cwd, '.github', 'agents', 'squad.agent.md');
+    if (fs.existsSync(agentFile)) {
       if (!dryRun) {
-        removeRecursive(target);
-        console.log(`           removed: ${path.relative(cwd, target)}`);
+        removeRecursive(agentFile);
+        console.log(`           removed: ${path.relative(cwd, agentFile)}`);
       } else {
-        console.log(`${prefix}Would remove: ${path.relative(cwd, target)}`);
+        console.log(`${prefix}Would remove: ${path.relative(cwd, agentFile)}`);
       }
     }
-  }
 
-  // Also remove the top-level squad.agent.md (Squad-owned in project root)
-  const agentFile = path.join(cwd, '.github', 'agents', 'squad.agent.md');
-  if (fs.existsSync(agentFile)) {
-    if (!dryRun) {
-      removeRecursive(agentFile);
-      console.log(`           removed: ${path.relative(cwd, agentFile)}`);
-    } else {
-      console.log(`${prefix}Would remove: ${path.relative(cwd, agentFile)}`);
+    // If migrating from .ai-team/, remove it entirely now (after backup)
+    if (squadDir === legacyDir) {
+      if (!dryRun) {
+        removeRecursive(legacyDir);
+        console.log(`           removed legacy: .ai-team/`);
+      } else {
+        console.log(`${prefix}Would remove: .ai-team/`);
+      }
     }
-  }
 
-  // If migrating from .ai-team/, remove it entirely now (after backup)
-  if (squadDir === legacyDir) {
+    // Step 3: Reinitialize
+    console.log();
+    console.log(`  Step 3/4  Reinitialize .squad/`);
+
     if (!dryRun) {
-      removeRecursive(legacyDir);
-      console.log(`           removed legacy: .ai-team/`);
+      const version = getPackageVersion();
+      await sdkInitSquad({
+        teamRoot: cwd,
+        projectName: path.basename(cwd) || 'my-project',
+        agents: [{ name: 'scribe', role: 'scribe', displayName: 'Scribe' }],
+        skipExisting: true,
+        includeWorkflows: true,
+        includeTemplates: true,
+        version,
+      });
+      success('Scaffolded fresh .squad/ directory.');
     } else {
-      console.log(`${prefix}Would remove: .ai-team/`);
+      console.log(`${prefix}Would run: sdkInitSquad (fresh scaffold)`);
     }
-  }
 
-  // Step 3: Reinitialize
-  console.log();
-  console.log(`  Step 3/4  Reinitialize .squad/`);
-
-  if (!dryRun) {
-    const version = getPackageVersion();
-    await sdkInitSquad({
-      teamRoot: cwd,
-      projectName: path.basename(cwd) || 'my-project',
-      agents: [{ name: 'scribe', role: 'scribe', displayName: 'Scribe' }],
-      skipExisting: true,
-      includeWorkflows: true,
-      includeTemplates: true,
-      version,
-    });
-    success('Scaffolded fresh .squad/ directory.');
-  } else {
-    console.log(`${prefix}Would run: sdkInitSquad (fresh scaffold)`);
-  }
-
-  // Step 4: Restore user-owned files
-  console.log();
-  console.log(`  Step 4/4  Restore user files from backup`);
+    // Step 4: Restore user-owned files
+    console.log();
+    console.log(`  Step 4/4  Restore user files from backup`);
 
-  for (const userFile of USER_OWNED) {
-    const backupSrc = path.join(backupRoot, userFile);
-    const restoreDest = path.join(cwd, '.squad', userFile);
+    for (const userFile of USER_OWNED) {
+      const backupSrc = path.join(backupRoot, userFile);
+      const restoreDest = path.join(cwd, '.squad', userFile);
 
-    if (!fs.existsSync(backupSrc)) continue;
+      if (!fs.existsSync(backupSrc)) continue;
 
-    if (!dryRun) {
-      // Skip if reinit already wrote this file and the user had nothing custom
-      // (user-owned files that exist in the fresh scaffold are still overwritten by the backup)
-      copyRecursive(backupSrc, restoreDest);
-      console.log(`           restored: .squad/${userFile}`);
-    } else {
-      console.log(`${prefix}Would restore: backup/${userFile} → .squad/${userFile}`);
+      if (!dryRun) {
+        // user-owned files overwrite whatever reinit wrote
+        copyRecursive(backupSrc, restoreDest);
+        console.log(`           restored: .squad/${userFile}`);
+      } else {
+        console.log(`${prefix}Would restore: backup/${userFile} → .squad/${userFile}`);
+      }
+    }
+  } catch (err) {
+    console.log();
+    console.error(`Migration failed: ${err instanceof Error ? err.message : String(err)}`);
+    if (!dryRun && fs.existsSync(backupRoot)) {
+      console.error('');
+      console.error('Rolling back from backup...');
+      removeRecursive(path.join(cwd, '.squad'));
+      copyRecursive(backupRoot, path.join(cwd, '.squad'));
+      console.error(`Restored .squad/ from ${path.relative(cwd, backupRoot)}/`);
+      console.error('');
+      console.error(`Your backup is still at: ${path.relative(cwd, backupRoot)}/`);
+      console.error('You can retry the migration or restore manually with:');
+      console.error(`  squad migrate --restore ${path.relative(cwd, backupRoot)}`);
     }
+    process.exit(1);
   }
 
   console.log();

From a28d1893a36456055e2802480431204ac62d6d20 Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 13:31:42 +1000
Subject: [PATCH 04/12] docs: documentation sweep for migrate --restore

Update cli.md, disaster-recovery.md, keep-my-squad.md, README.md
to reflect squad migrate, --restore flag, and current .squad/ paths.

Refs #197
---
 .squad/agents/mcmanus/history.md | 43 ++++++++++++++++++++++++++++++++
 .squad/decisions.md              | 22 ++++++++++++++++
 2 files changed, 65 insertions(+)

diff --git a/.squad/agents/mcmanus/history.md b/.squad/agents/mcmanus/history.md
index fecb358f5..5c5d436ff 100644
--- a/.squad/agents/mcmanus/history.md
+++ b/.squad/agents/mcmanus/history.md
@@ -1005,3 +1005,46 @@ Multi-agent build of Rock-Paper-Scissors game with 10 AI strategies, Docker infr
 
 
 📌 Team update (2026-03-04T17:52:00Z): Migration docs file-safety guidance added — doctor command now live in CLI (fixes #188) — decided by Keaton, implemented by McManus
+
+### 2026-03-[Current]: Documentation sweep for `squad migrate` consistency (Issue #197)
+
+**Status:** Complete. Sweep across migration-related docs to ensure consistency with new `squad migrate` command and restore functionality.
+
+**What was fixed:**
+1. **docs/reference/cli.md** — Added missing `squad migrate` and related flags to command table (count: 16 → 17 commands)
+   - Added: `squad migrate`, `squad migrate --dry-run`, `squad migrate --restore [path]`
+2. **docs/scenarios/disaster-recovery.md** — Updated all 9 sections from `.ai-team/` → `.squad/`
+   - Changed: directory paths, commands, file references
+   - Added: explicit mention of `squad migrate` in section 6 (Upgrade broke something) as the recovery tool
+   - Added: tip about using `squad migrate` for broken `.squad/` directories
+3. **docs/scenarios/keep-my-squad.md** — Updated from deprecated `npx github:bradygaster/squad` to `squad init` and modern npm install
+   - Changed: export/import examples, version upgrade examples, command references
+   - Updated: `.ai-team/` → `.squad/`, `.ai-team-templates/` → `.squad/templates/`
+4. **README.md** — Added `squad migrate` command to commands table
+   - Count: 15 → 16 commands
+   - Added full description with --dry-run and --restore flags
+
+**Files not changed (determined out of scope):**
+- Blog posts (historical, not end-user facing in current release)
+- General scenario docs (mid-project, new-project, etc.) — these use old commands but not migration-specific
+
+**Consistency check performed:**
+- All three key migration docs (migration.md, upgrading.md, troubleshooting.md) already had proper `squad migrate` coverage
+- No inconsistencies found between what migrate does across these files
+- `--restore` flag well-documented in migration.md and troubleshooting.md
+
+**Tone and style:**
+- Maintained consistent, action-oriented voice ("Back up", "Reinitialize", "Restore")
+- No marketing language added — purely functional updates
+- All changes are substantiated by actual code behavior described in the migration context
+
+**Learnings:**
+1. **Documentation fragmentation risk:** Scenario docs referencing `.ai-team/` should be addressed in a separate sweep targeting all scenario files (not just migration-focused ones).
+2. **Command inventory pattern:** CLI reference and README command counts need to stay synchronized. This is a manual maintenance risk — consider automation.
+3. **Major version boundaries:** The `.ai-team/` → `.squad/` transition is a hard boundary (v0.5.4 → v0.8.x). Docs should clearly signal this is non-backwards-compatible, which they now do.
+4. **Restore UX:** Having both `--restore` (auto-detect) and `--restore [path]` (explicit) is well-documented and matches actual CLI behavior.
+
+
+---
+
+📌 **Team update (2026-03-05T03:25:00Z):** Documentation sweep for migrate --restore changes completed by McManus. Updated cli.md, disaster-recovery.md, keep-my-squad.md, README.md to reflect new command and flag. Migration-related docs now synchronized.
diff --git a/.squad/decisions.md b/.squad/decisions.md
index ccb7a2d61..fbeaaba6d 100644
--- a/.squad/decisions.md
+++ b/.squad/decisions.md
@@ -2001,4 +2001,26 @@ This is low-effort, high-value — a broken link on the GitHub Pages site erodes
 **Judgment Call:** Preserved both origin/insider (singular, existing) and origin/insiders (plural, new). Conservative approach pending Brady confirmation.
 **Action Required:** Brady to decide: keep origin/insiders (matches decision) + delete origin/insider, or keep origin/insider and delete origin/insiders.
 **Status:** Infrastructure ready. Awaiting final branch naming confirmation.
+### 2026-03-05: Documentation Sweep — migrate --restore Changes
+**By:** McManus (DevRel)
+**What:** Performed targeted documentation sweep to synchronize docs after adding `squad migrate` command and `--restore` flag. Updated 4 files:
+- docs/reference/cli.md (added `squad migrate` command documentation)
+- docs/scenarios/disaster-recovery.md (modernized `.ai-team/` → `.squad/`, all paths updated)
+- docs/scenarios/keep-my-squad.md (updated commands and examples)
+- README.md (updated command table, added 16th command)
+
+Verified 3 files already consistent:
+- docs/get-started/migration.md (full `squad migrate` coverage present)
+- docs/scenarios/upgrading.md (already references migrate for major upgrades)
+- docs/scenarios/troubleshooting.md (already documents --restore)
+
+**Why:** After PR adding migrate command merged, reference docs, README, and scenario docs needed consistency sweep. Users need to know to use `squad migrate --restore` for recovery, not manual steps.
+
+**Outcomes:**
+1. All migration-related docs now synchronously reference `squad migrate` and `--restore` flag
+2. Disaster recovery guidance modernized — users know to use migrate, not manual restore
+3. No manual restore steps remain — all restore guidance points to `squad migrate --restore`
+4. General scenario docs (non-migration) still reference old distribution methods, deferred for future sweep
+
+**Implications:** Users upgrading from v0.5.4 or recovering from `.squad/` corruption now have clear, consistent guidance pointing to migrate command.
 

From d977e03bbd4aa2ef22dd82dd4cf7c4882f81a6cb Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 13:32:29 +1000
Subject: [PATCH 05/12] docs: update cli reference and scenario docs for squad
 migrate

---
 README.md                           |  3 +-
 docs/reference/cli.md               |  5 +-
 docs/scenarios/disaster-recovery.md | 85 +++++++++++++++++++----------
 docs/scenarios/keep-my-squad.md     | 40 ++++++++------
 4 files changed, 86 insertions(+), 47 deletions(-)

diff --git a/README.md b/README.md
index e0d501d01..bffa3b91c 100644
--- a/README.md
+++ b/README.md
@@ -61,11 +61,12 @@ Squad proposes a team — each member named from a persistent thematic cast. You
 
 ---
 
-## All Commands (15 commands)
+## All Commands (16 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 migrate` | **Migrate** — automated backup, cleanup, and reinit for major version upgrades; use `--dry-run` to preview, `--restore [path]` to restore from backup |
 | `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 status` | Show which squad is active and why |
 | `squad triage` | Watch issues and auto-triage to team (aliases: `watch`, `loop`); use `--interval <minutes>` to set polling frequency (default: 10) |
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index a91fbdbd0..6385a5810 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -22,7 +22,7 @@ squad init
 
 ---
 
-## CLI Commands (16 commands)
+## CLI Commands (17 commands)
 
 | Command | Description | Requires `.squad/` |
 |---------|-------------|:------------------:|
@@ -33,6 +33,9 @@ squad init
 | `squad start [--tunnel] [--port N] [--command cmd]` | Start Copilot with remote phone access via PTY and WebSocket | No |
 | `squad status` | Show which squad is active and why | Yes |
 | `squad doctor` | Validate squad setup integrity and diagnose issues (alias: `heartbeat`) | Yes |
+| `squad migrate` | Backup, clean, reinitialize, and restore user files for major version upgrades | Yes |
+| `squad migrate --dry-run` | Preview migration steps without making changes | Yes |
+| `squad migrate --restore [path]` | Restore from a backup (auto-detects latest or accepts explicit `.squad-backup-*` path) | No |
 | `squad upgrade` | Upgrade Squad-owned files to latest version | Yes |
 | `squad upgrade --migrate-directory` | Rename legacy `.ai-team/` directory to `.squad/` | Yes |
 | `squad link <team-repo-path>` | Link project to a remote team root | Yes |
diff --git a/docs/scenarios/disaster-recovery.md b/docs/scenarios/disaster-recovery.md
index 320c7b6c8..8cef934cd 100644
--- a/docs/scenarios/disaster-recovery.md
+++ b/docs/scenarios/disaster-recovery.md
@@ -2,7 +2,7 @@
 
 **Try this to recover from data loss:**
 ```
-My .ai-team/ directory was deleted — help me recover the team state
+My .squad/ directory was deleted — help me recover the team state
 ```
 
 **Try this to revert bad code:**
@@ -15,33 +15,33 @@ An agent wrote bad code — how do I revert it?
 The squad is confused — reset their context
 ```
 
-Recovery procedures for deleted `.ai-team/`, bad agent code, confused squads, and upgrade issues. Most problems are fixable with Git or re-init.
+Recovery procedures for deleted `.squad/`, bad agent code, confused squads, and upgrade issues. Most problems are fixable with Git or re-init.
 
 ---
 
-## 1. "I accidentally deleted `.ai-team/`"
+## 1. "I accidentally deleted `.squad/`"
 
-Recovery scenarios: deleted `.ai-team/`, bad agent code, confused squad, upgrade issues.
+Recovery scenarios: deleted `.squad/`, bad agent code, confused squad, upgrade issues.
 
 **Solution:** It's in Git. Restore it.
 
 ```bash
-git checkout .ai-team/
+git checkout .squad/
 ```
 
-If you haven't committed `.ai-team/` yet, it's gone. Rebuild:
+If you haven't committed `.squad/` yet, it's gone. Rebuild:
 
 ```bash
-npx github:bradygaster/squad
+npx @bradygaster/squad-cli init
 ```
 
 Start from scratch. If you exported your squad before, import the export:
 
 ```bash
-npx github:bradygaster/squad import squad-export-2025-07-15.zip
+squad import squad-export-2025-07-15.zip
 ```
 
-**Prevention:** Commit `.ai-team/` early. Don't let it stay uncommitted for long.
+**Prevention:** Commit `.squad/` early. Don't let it stay uncommitted for long.
 
 ---
 
@@ -85,7 +85,29 @@ Sonny reads the code, fixes the issue, commits.
 
 ## 3. "An agent made a wrong decision"
 
-**What happened:** Neo decided to use REST when GraphQL was the better choice. The decision is logged in `.ai-team/decisions.md`.
+**What happened:** Neo decided to use REST when GraphQL was the better choice. The decision is logged in `.squad/decisions.md`.
+
+**Solution:** Add a directive to override it.
+
+```
+> Team, I'm overriding Neo's decision from last session. We're using
+> GraphQL, not REST. The client needs flexible queries. Document this.
+```
+
+```
+📋 Scribe — logged decision override
+
+### 2025-07-15: Using GraphQL instead of REST
+**By:** You (overriding Neo's recommendation)
+**What:** API will use GraphQL, not REST
+**Why:** Client needs flexible queries, REST would require too many endpoints
+
+Neo's previous recommendation archived.
+```
+
+Agents now read the new decision and build accordingly.
+
+**Prevention:** Review major decisions before agents implement them. Use the Lead as a sounding board, not a dictator.
 
 **Solution:** Add a directive to override it.
 
@@ -125,7 +147,7 @@ Agents now read the new decision and build accordingly.
 ```
 📋 Scribe — archiving recent session histories
 
-Moved to .ai-team/history-archive/:
+Moved to .squad/history-archive/:
   - Neo's session from 2025-07-14
   - Morpheus's session from 2025-07-14
   - Trinity's session from 2025-07-14
@@ -141,11 +163,11 @@ Agents **forget** the bad session. They still have their long-term skills and de
 
 ## 5. "I want to start over completely"
 
-**Solution:** Delete `.ai-team/` and reinstall.
+**Solution:** Delete `.squad/` and reinitialize.
 
 ```bash
-rm -rf .ai-team/
-npx github:bradygaster/squad
+rm -rf .squad/
+squad init
 ```
 
 ```
@@ -162,13 +184,19 @@ You're back to day one. Clean slate.
 
 **What happened:** You upgraded Squad to a new version, and now something doesn't work.
 
-**Solution:** Squad upgrades **never touch** `.ai-team/`. The issue is likely in:
+**Solution:** Squad upgrades **never touch** `.squad/`. The issue is likely in:
 
-1. **Workflow templates** — check `.ai-team-templates/`
+1. **Workflow templates** — check `.squad/templates/`
 2. **Squad agent definition** — check `.github/agents/squad.agent.md`
-3. **Model configuration** — check `.ai-team/model-config.json`
+3. **Model configuration** — check `.squad/config.json` (if present)
+
+If the Squad agent definition is corrupted, use `squad migrate` to restore:
+
+```bash
+squad migrate
+```
 
-Roll back the Squad agent definition:
+Or roll back the Squad agent definition:
 
 ```bash
 git checkout HEAD^ .github/agents/squad.agent.md
@@ -177,10 +205,10 @@ git checkout HEAD^ .github/agents/squad.agent.md
 Or reinstall the previous version:
 
 ```bash
-npx github:bradygaster/squad@0.1.5
+npm install -g @bradygaster/squad-cli@0.8.18
 ```
 
-**Your team's knowledge is safe.** `.ai-team/` is untouched.
+**Your team's knowledge is safe.** `.squad/` is untouched.
 
 **Prevention:** Check the CHANGELOG before upgrading. If the upgrade is major, test in a branch first.
 
@@ -211,17 +239,17 @@ Or just close the Copilot session (Ctrl+C) and start a new one.
 
 ## 8. "Skills are outdated or wrong"
 
-**What happened:** A skill file in `.ai-team/skills/` contains outdated information. Agents are following bad advice.
+**What happened:** A skill file in `.squad/skills/` contains outdated information. Agents are following bad advice.
 
 **Solution:** Edit or delete the skill file.
 
 ```bash
 # Edit the skill
-code .ai-team/skills/auth-rate-limiting.md
+code .squad/skills/auth-rate-limiting.md
 
 # Or delete it
-rm .ai-team/skills/auth-rate-limiting.md
-git add .ai-team/skills/
+rm .squad/skills/auth-rate-limiting.md
+git add .squad/skills/
 git commit -m "Remove outdated auth rate limiting skill"
 ```
 
@@ -231,13 +259,13 @@ git commit -m "Remove outdated auth rate limiting skill"
 
 ## 9. "Decisions.md is a mess"
 
-**What happened:** `.ai-team/decisions.md` has 200 entries and it's hard to find anything.
+**What happened:** `.squad/decisions.md` has 200 entries and it's hard to find anything.
 
 **Solution:** Archive old decisions.
 
 ```
 > Scribe, archive decisions older than 3 months. Move them to
-> .ai-team/decisions-archive.md.
+> .squad/decisions-archive.md.
 ```
 
 ```
@@ -284,10 +312,11 @@ Each agent logs what they did in their `history.md`.
 
 ## Tips
 
-- **`.ai-team/` is in Git.** If you delete it, restore from Git. If it's uncommitted, it's gone.
+- **`.squad/` is in Git.** If you delete it, restore from Git. If it's uncommitted, it's gone.
 - **Code review catches bad agent code.** Use the Lead to review before merging.
 - **Override bad decisions with directives.** If an agent made the wrong call, tell the team the correct one.
 - **Archive confused histories.** If a session went badly, archive the learnings so agents forget.
-- **Upgrades don't touch `.ai-team/`.** Your team's knowledge is safe across upgrades.
+- **Upgrades don't touch `.squad/`.** Your team's knowledge is safe across upgrades.
+- **Use `squad migrate` for broken `.squad/`** after major version upgrades. It backs up, cleans, and restores in one command.
 - **Edit skill files directly.** They're just markdown. If a skill is wrong, fix it or delete it.
 - **Agent histories are the audit log.** Check them to see what each agent did.
diff --git a/docs/scenarios/keep-my-squad.md b/docs/scenarios/keep-my-squad.md
index ca98ac408..55d2b2114 100644
--- a/docs/scenarios/keep-my-squad.md
+++ b/docs/scenarios/keep-my-squad.md
@@ -25,12 +25,12 @@ Squad persistence and portability. Your squad remembers skills, casting, and kno
 
 After working on a project for a few weeks, your squad has learned:
 
-- **Skills** — patterns, conventions, best practices (23 skill files in `.ai-team/skills/`)
-- **Decisions** — architectural choices, why you picked X over Y (`.ai-team/decisions.md`)
-- **Histories** — project-specific context each agent accumulated (`.ai-team/agents/{name}/history.md`)
-- **Casting state** — the chosen agent names, roles, universe (`.ai-team/casting-state.json`)
+- **Skills** — patterns, conventions, best practices (23 skill files in `.squad/skills/`)
+- **Decisions** — architectural choices, why you picked X over Y (`.squad/decisions.md`)
+- **Histories** — project-specific context each agent accumulated (`.squad/agents/{name}/history.md`)
+- **Casting state** — the chosen agent names, roles, universe (`.squad/casting-state.json`)
 
-All of this lives in `.ai-team/`. Commit it, and anyone who clones your repo gets the full team.
+All of this lives in `.squad/`. Commit it, and anyone who clones your repo gets the full team.
 
 ---
 
@@ -40,7 +40,7 @@ When you finish a project or want to take your squad to a new one:
 
 ```bash
 cd ~/projects/finished-saas-app
-npx github:bradygaster/squad export
+squad export
 ```
 
 ```
@@ -69,10 +69,10 @@ Start a new project:
 mkdir ~/projects/new-mobile-app
 cd ~/projects/new-mobile-app
 git init
-npx github:bradygaster/squad
+squad init
 ```
 
-When Squad asks what you're building:
+When Squad asks what you're building, import your squad:
 
 ```
 > Import my squad from squad-export-2025-07-15.zip
@@ -133,29 +133,35 @@ This is intentional. Skills are **reusable**. Project details are **not**.
 
 ---
 
-## 5. Version Upgrades Don't Touch `.ai-team/`
+## 5. Version Upgrades Don't Touch `.squad/`
 
 When Squad releases a new version:
 
 ```bash
-npx github:bradygaster/squad@latest
+npm install -g @bradygaster/squad-cli@latest
+```
+
+Then:
+
+```bash
+squad upgrade
 ```
 
 ```
-🔄 Upgrading Squad from v0.1.5 to v0.2.0
+🔄 Upgrading Squad from v0.8.18 to v0.8.21
 
-✅ .github/agents/squad.agent.md (updated to v0.2.0)
-✅ .ai-team-templates/ (new workflow templates)
+✅ .github/agents/squad.agent.md (updated to v0.8.21)
+✅ .squad/templates/ (new workflow templates)
 ✅ .gitattributes (merge=union rules verified)
 
-⚠️  Your .ai-team/ directory was NOT modified.
+⚠️  Your .squad/ directory was NOT modified.
    Your team's memory, skills, and decisions are untouched.
 ```
 
 Upgrades only change:
 
 - The Squad agent definition (`.github/agents/squad.agent.md`)
-- Workflow templates (`.ai-team-templates/`)
+- Workflow templates (`.squad/templates/`)
 - The installer itself
 
 Your **team's knowledge is safe**.
@@ -164,10 +170,10 @@ Your **team's knowledge is safe**.
 
 ## 6. Git Commit Means Everyone Gets the Team
 
-You commit `.ai-team/`:
+You commit `.squad/`:
 
 ```bash
-git add .ai-team/
+git add .squad/
 git commit -m "Add Squad team with 3 weeks of accumulated knowledge"
 git push
 ```

From a5fa4dcdb775c98bc248411c01291de1bdc0f514 Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 13:51:39 +1000
Subject: [PATCH 06/12] fix(cli): prevent shell re-init and agent overwrite
 after migrate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After migrate runs sdkInitSquad() in step 3, it creates .first-run and
potentially .init-prompt. The shell treats these as signals that no team
exists yet and prompts the user to cast a team — even though migrate just
restored a full team roster. If the user follows that prompt and confirms,
createTeam() runs without guards and overwrites all existing agent files.

Two fixes:
1. migrate.ts: after sdkInitSquad(), delete .first-run and .init-prompt if
   present so the shell sees a normal (not first-run) state.
2. cast.ts createTeam(): guard charter.md and history.md writes so they only
   happen when the file is absent or empty — existing agent work is preserved
   even if init mode accidentally triggers.
---
 packages/squad-cli/src/cli/core/cast.ts    | 29 ++++++++++++++--------
 packages/squad-cli/src/cli/core/migrate.ts | 13 ++++++++++
 2 files changed, 31 insertions(+), 11 deletions(-)

diff --git a/packages/squad-cli/src/cli/core/cast.ts b/packages/squad-cli/src/cli/core/cast.ts
index dacd77524..422e77733 100644
--- a/packages/squad-cli/src/cli/core/cast.ts
+++ b/packages/squad-cli/src/cli/core/cast.ts
@@ -392,20 +392,27 @@ export async function createTeam(teamRoot: string, proposal: CastProposal): Prom
     await mkdir(agentDir, { recursive: true });
 
     const charterPath = join(agentDir, 'charter.md');
-    let charter: string;
-    if (member.name === 'Scribe' && !hasScribe) {
-      charter = scribeCharter();
-    } else if (member.name === 'Ralph' && !hasRalph) {
-      charter = ralphCharter();
-    } else {
-      charter = generateCharter(member);
+    // Protect existing charter files — only write if absent or truly empty
+    // (i.e., previous /init or migrate left a real charter in place)
+    if (!existsSync(charterPath) || (await readFile(charterPath, 'utf8')).trim().length === 0) {
+      let charter: string;
+      if (member.name === 'Scribe' && !hasScribe) {
+        charter = scribeCharter();
+      } else if (member.name === 'Ralph' && !hasRalph) {
+        charter = ralphCharter();
+      } else {
+        charter = generateCharter(member);
+      }
+      await writeFile(charterPath, charter);
+      filesCreated.push(charterPath);
     }
-    await writeFile(charterPath, charter);
-    filesCreated.push(charterPath);
 
     const historyPath = join(agentDir, 'history.md');
-    await writeFile(historyPath, generateHistory(member, proposal.projectDescription));
-    filesCreated.push(historyPath);
+    // Protect existing history — only write if absent or empty
+    if (!existsSync(historyPath) || (await readFile(historyPath, 'utf8')).trim().length === 0) {
+      await writeFile(historyPath, generateHistory(member, proposal.projectDescription));
+      filesCreated.push(historyPath);
+    }
 
     membersCreated.push(member.name);
   }
diff --git a/packages/squad-cli/src/cli/core/migrate.ts b/packages/squad-cli/src/cli/core/migrate.ts
index 9683cd96f..89b34d854 100644
--- a/packages/squad-cli/src/cli/core/migrate.ts
+++ b/packages/squad-cli/src/cli/core/migrate.ts
@@ -238,8 +238,21 @@ export async function runMigrate(cwd: string, options: MigrateOptions = {}): Pro
         version,
       });
       success('Scaffolded fresh .squad/ directory.');
+
+      // Clean up first-run markers so the shell doesn't treat the migrated
+      // install as a brand-new setup. If these exist, the shell shows "no team
+      // yet" hints — which would be wrong after a migration that restores a
+      // full team roster.
+      for (const marker of ['.first-run', '.init-prompt']) {
+        const markerPath = path.join(cwd, '.squad', marker);
+        if (fs.existsSync(markerPath)) {
+          fs.unlinkSync(markerPath);
+        }
+      }
     } else {
       console.log(`${prefix}Would run: sdkInitSquad (fresh scaffold)`);
+      console.log(`${prefix}Would remove: .squad/.first-run (if present)`);
+      console.log(`${prefix}Would remove: .squad/.init-prompt (if present)`);
     }
 
     // Step 4: Restore user-owned files

From b68c837d3df701fa658a08fea5bdf5ee019b4d79 Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 14:03:35 +1000
Subject: [PATCH 07/12] test: add unit, integration, and E2E tests for squad
 migrate and cast guard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- test/migrate-command.test.ts: 19 unit/integration tests for runMigrate,
  runRestore, findLatestBackup — dry-run, auto-rollback, .first-run cleanup,
  legacy .ai-team/ migration, restore (auto and explicit)
- test/cast-guard.test.ts: 11 tests for createTeam() charter/history guard —
  verifies existing non-empty files are not overwritten on /init
- test/migrate-e2e.test.ts: 23 E2E tests exercising the built CLI via
  execFileSync — full flow, restore, shell reinit guard assertions

All 53 tests pass. Closes gap in coverage for #197 migration fixes.
---
 .squad/.first-run                             |   1 +
 .squad/agents/breedan/history.md              |  31 ++
 .squad/agents/hockney/history.md              |  25 +-
 .squad/config.json                            |   4 +
 .squad/decisions.md                           |  82 +++
 .squad/log/2026-03-05T03-25-00Z-doc-sweep.md  |  22 +
 .../log/2026-03-05T04-02-47Z-migrate-tests.md |  25 +
 .../2026-03-05T03-25-00Z-mcmanus.md           |  34 ++
 .../2026-03-05T04-02-47Z-breedan.md           |  41 ++
 .../2026-03-05T04-02-47Z-hockney.md           |  40 ++
 test/cast-guard.test.ts                       | 251 +++++++++
 test/migrate-command.test.ts                  | 350 ++++++++++++
 test/migrate-e2e.test.ts                      | 519 ++++++++++++++++++
 13 files changed, 1424 insertions(+), 1 deletion(-)
 create mode 100644 .squad/.first-run
 create mode 100644 .squad/config.json
 create mode 100644 .squad/log/2026-03-05T03-25-00Z-doc-sweep.md
 create mode 100644 .squad/log/2026-03-05T04-02-47Z-migrate-tests.md
 create mode 100644 .squad/orchestration-log/2026-03-05T03-25-00Z-mcmanus.md
 create mode 100644 .squad/orchestration-log/2026-03-05T04-02-47Z-breedan.md
 create mode 100644 .squad/orchestration-log/2026-03-05T04-02-47Z-hockney.md
 create mode 100644 test/cast-guard.test.ts
 create mode 100644 test/migrate-command.test.ts
 create mode 100644 test/migrate-e2e.test.ts

diff --git a/.squad/.first-run b/.squad/.first-run
new file mode 100644
index 000000000..076510880
--- /dev/null
+++ b/.squad/.first-run
@@ -0,0 +1 @@
+2026-03-04T23:48:26.577Z
diff --git a/.squad/agents/breedan/history.md b/.squad/agents/breedan/history.md
index ec742e15b..c9e97f18a 100644
--- a/.squad/agents/breedan/history.md
+++ b/.squad/agents/breedan/history.md
@@ -172,3 +172,34 @@ What a real user would encounter that no test catches:
 3. [CORRECTED] Fixed timestamp format on public readiness entry — changed from mixed ISO-T format to standard (2026-02-24) for consistency with other history entries
 
 **Status:** Clean after corrections.
+
+### Squad Migrate E2E Tests — 2025-03-05
+
+**Requested by:** William Hallatt — test coverage for `squad migrate` command and shell reinit guard bug fix from branch `williamhallatt/197-migration-experience`.
+
+**Context:** The migrate command was added to safely upgrade .squad/ directories (backup → clean → reinit → restore). A critical bug where re-launching shell after migrate would trigger re-initialization (overwriting agent files) was fixed by cleaning up `.first-run` and `.init-prompt` markers after migration.
+
+**Tests created:** `test/migrate-e2e.test.ts` — 23 tests, all passing.
+
+#### Test Coverage (6 groups)
+1. **--dry-run:** Exit 0, outputs [dry-run] marker, no backups created, .squad/ untouched (3 tests)
+2. **Full migrate flow:** Creates backup, preserves user files (agents/, team.md), removes .first-run/.init-prompt markers (6 tests)
+3. **--restore (auto-detect):** Finds latest .squad-backup-*, restores content correctly (3 tests)
+4. **--restore <path>:** Works with relative and absolute paths (3 tests)
+5. **No .squad/ directory:** Fresh init path works (creates .squad/, .first-run IS present since it's genuinely first run) (3 tests)
+6. **Shell reinit guard:** Verifies .first-run/.init-prompt cleanup after migrate prevents unwanted shell reinit (5 tests)
+
+#### Key Implementation Details
+- Used `execFileSync` (not node-pty) since migrate is non-interactive
+- Built CLI at `packages/squad-cli/dist/cli-entry.js` instead of root `index.js` (which has CJS syntax despite package.json type:module)
+- Helper `createPopulatedSquadDir()` scaffolds realistic post-init .squad/ with agents, charters, history
+- Tests validate filesystem state before/after migrate (marker files, backup dirs, user content preservation)
+- Important behavior: fresh init via migrate (no existing .squad/) DOES create .first-run (correct), but migrating existing .squad/ removes it (prevents shell reinit)
+
+#### Learnings
+1. **CLI entry points matter:** Root index.js is CJS syntax but package.json has type:module, causing syntax errors. Built CLI works correctly.
+2. **Marker cleanup location:** migrate.ts lines 246-251 clean up .first-run/.init-prompt ONLY after migrating existing .squad/, not during fresh init path (which is correct behavior).
+3. **Test isolation:** temp dirs + afterEach cleanup ensure no cross-test pollution.
+4. **Backup validation:** Verified both auto-detect (latest .squad-backup-*) and explicit path restore scenarios work.
+
+**Test execution:** 23/23 passing in ~10s. All scenarios covered.
diff --git a/.squad/agents/hockney/history.md b/.squad/agents/hockney/history.md
index dc7a6f667..d0a6d57b3 100644
--- a/.squad/agents/hockney/history.md
+++ b/.squad/agents/hockney/history.md
@@ -802,4 +802,27 @@ All labeled squad:hockney for routing. Each issue includes: what's missing, why
 - **What:** Updated test description and path from `.squad-templates/` to `.squad/templates/` to match the corrected install path in `init.ts`.
 - **Key finding:** The SDK dist was stale (still had old `.squad-templates` path). Source was already updated but `npm run build` hadn't been run. Rebuilt SDK to verify test passes.
 - **Pre-existing failure:** Line 94 gitattributes content mismatch (unrelated, not introduced by this change).
-- **Lesson:** On Windows, use `join(root, '.squad', 'templates')` not `join(root, '.squad/templates')` — forward-slash segments in `join` args work on Node but it's better practice to use separate args.
+- **Lesson:** On Windows, use `join(root, '.squad', 'templates')` not `join(root, '.squad/templates')` — forward-slash segments in `join` args work on Node but it's better practice to use separate args.
+
+### Migration command test coverage — branch williamhallatt/197-migration-experience (2026-03-05)
+**Status:** Complete — 30 tests added, all pass.
+- **Files created:**
+  - `test/migrate-command.test.ts` (19 tests for `runMigrate`)
+  - `test/cast-guard.test.ts` (11 tests for `createTeam` guard logic)
+- **Coverage highlights:**
+  - `findLatestBackup` tested via `--restore` flag with 0, 1, and 3 backups
+  - Dry-run mode: no filesystem changes, no sdkInitSquad call
+  - Normal migration: backup creation, SQUAD_OWNED removal, USER_OWNED restoration, first-run marker cleanup
+  - Legacy `.ai-team/` migration
+  - Auto-rollback on sdkInitSquad failure
+  - Explicit and auto-detected restore paths
+  - Cast guard: protects non-empty charter.md and history.md from overwrite; writes when absent or whitespace-only
+- **Key patterns:**
+  - `vi.spyOn(process, 'exit').mockImplementation(() => { throw new Error() })` to test error paths without actually exiting
+  - `vi.mock('@bradygaster/squad-sdk')` to isolate CLI logic from SDK behavior
+  - `mkdtempSync(join(tmpdir(), ...))` for clean temp dirs per test
+- **Learnings:**
+  - Migration has solid error handling (auto-rollback is critical)
+  - Cast guard protects against accidental overwrite after migrate (BUG FIX)
+  - Tests are structural — they verify the logic without caring about console output
+  - All 30 tests pass on first run (implementation is solid)
diff --git a/.squad/config.json b/.squad/config.json
new file mode 100644
index 000000000..a1f09ba0a
--- /dev/null
+++ b/.squad/config.json
@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "teamRoot": "/home/williamh/code/squad"
+}
\ No newline at end of file
diff --git a/.squad/decisions.md b/.squad/decisions.md
index fbeaaba6d..36a225e98 100644
--- a/.squad/decisions.md
+++ b/.squad/decisions.md
@@ -2024,3 +2024,85 @@ Verified 3 files already consistent:
 
 **Implications:** Users upgrading from v0.5.4 or recovering from `.squad/` corruption now have clear, consistent guidance pointing to migrate command.
 
+# Hockney — Migration Test Patterns
+
+**Date:** 2026-03-05  
+**Status:** Complete  
+**Requestor:** williamhallatt
+
+## Decision
+
+Test suite patterns for migration command and cast guard are now standardized:
+
+### 1. Error Path Testing (process.exit)
+
+Migration calls `process.exit(1)` on error. Mock pattern:
+
+```typescript
+const exitSpy = vi.spyOn(process, 'exit').mockImplementation((code?: any) => {
+  throw new Error(`process.exit: ${code}`);
+});
+
+await expect(runMigrate(...)).rejects.toThrow('process.exit: 1');
+```
+
+### 2. SDK Mocking for CLI Commands
+
+CLI commands that call SDK functions must mock them:
+
+```typescript
+vi.mock('@bradygaster/squad-sdk', () => ({
+  initSquad: vi.fn(async (opts) => {
+    // Simulate filesystem changes
+    mkdirSync(join(opts.teamRoot, '.squad'), { recursive: true });
+  }),
+}));
+```
+
+### 3. Temp Directory Hygiene
+
+Use OS temp dirs with cleanup:
+
+```typescript
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), 'squad-migrate-test-'));
+});
+
+afterEach(() => {
+  if (existsSync(testDir)) {
+    rmSync(testDir, { recursive: true, force: true });
+  }
+});
+```
+
+### 4. Guard Logic Testing (cast.ts)
+
+Test both the positive and negative cases:
+- **Negative:** File exists with content → guard fires, no overwrite
+- **Positive:** File absent or empty → write happens
+
+```typescript
+it('should NOT overwrite an existing non-empty charter.md', async () => {
+  writeFileSync(join(agentDir, 'charter.md'), '# Real Charter\n');
+  await createTeam(testDir, proposal);
+  expect(readFileSync(join(agentDir, 'charter.md'), 'utf8')).toBe('# Real Charter\n');
+});
+```
+
+## Coverage Achieved
+
+- **19 tests** for `migrate.ts` (dry-run, normal flow, legacy `.ai-team/`, rollback, restore)
+- **11 tests** for `cast.ts` guard logic (charter.md and history.md protection)
+- **All 30 tests pass** on first run
+
+## Why This Matters
+
+1. Migration is a high-risk operation (user data). Tests verify rollback on error.
+2. Cast guard prevents accidental overwrites when `/init` is triggered after migrate.
+3. These patterns are reusable for future CLI command tests.
+
+## Related
+
+- Branch: `williamhallatt/197-migration-experience`
+- Files: `test/migrate-command.test.ts`, `test/cast-guard.test.ts`
+- Blocking: None — tests verify existing implementation
diff --git a/.squad/log/2026-03-05T03-25-00Z-doc-sweep.md b/.squad/log/2026-03-05T03-25-00Z-doc-sweep.md
new file mode 100644
index 000000000..816c6274c
--- /dev/null
+++ b/.squad/log/2026-03-05T03-25-00Z-doc-sweep.md
@@ -0,0 +1,22 @@
+# Session: Documentation Sweep for migrate --restore (2026-03-05)
+
+**Agent:** McManus (DevRel)
+**Duration:** Background task
+**Issue:** #197
+
+## What Happened
+Targeted documentation sweep to synchronize CLI docs after adding `squad migrate` command and `--restore` flag.
+
+**Updated:** 4 files
+- docs/reference/cli.md (added migrate command)
+- docs/scenarios/disaster-recovery.md (modernized paths, .ai-team/ → .squad/)
+- docs/scenarios/keep-my-squad.md (updated commands)
+- README.md (updated command table)
+
+**Already consistent:** 3 files
+- docs/get-started/migration.md
+- docs/scenarios/upgrading.md
+- docs/scenarios/troubleshooting.md
+
+## Outcome
+All migration docs synchronized. Disaster recovery is clearer.
diff --git a/.squad/log/2026-03-05T04-02-47Z-migrate-tests.md b/.squad/log/2026-03-05T04-02-47Z-migrate-tests.md
new file mode 100644
index 000000000..67cc54271
--- /dev/null
+++ b/.squad/log/2026-03-05T04-02-47Z-migrate-tests.md
@@ -0,0 +1,25 @@
+# Session Log: Migration Test Suite
+
+**Date:** 2026-03-05T04-02-47Z  
+**Agents:** Hockney (Tester), Breedan (E2E Test Engineer)  
+**Topic:** Test coverage for squad migrate command and cast guard
+
+## Summary
+Spawned two agents to fill test gaps on #197 migration fixes. Hockney wrote 30 unit/integration tests (migrate-command, cast-guard). Breedan wrote 23 E2E tests (migrate-e2e). All 53 tests pass on first run.
+
+## Coverage Added
+1. **test/migrate-command.test.ts** (19 tests) — migrate, restore, dry-run, rollback, .first-run cleanup, legacy .ai-team/ support
+2. **test/cast-guard.test.ts** (11 tests) — createTeam() charter/history guard, prevent overwrites
+3. **test/migrate-e2e.test.ts** (23 tests) — full CLI flow, shell reinit guard, backup/restore
+
+## Key Patterns Documented
+- Error path testing (process.exit mocking)
+- SDK command mocking
+- Temp directory hygiene
+- Guard logic (positive/negative cases)
+
+## Decisions
+- Test patterns published to `.squad/decisions/inbox/hockney-migrate-tests.md`
+
+## Status
+All tests passing. Ready for commit.
diff --git a/.squad/orchestration-log/2026-03-05T03-25-00Z-mcmanus.md b/.squad/orchestration-log/2026-03-05T03-25-00Z-mcmanus.md
new file mode 100644
index 000000000..7d8d82f80
--- /dev/null
+++ b/.squad/orchestration-log/2026-03-05T03-25-00Z-mcmanus.md
@@ -0,0 +1,34 @@
+# Orchestration: McManus Documentation Sweep (2026-03-05T03:25:00Z)
+
+**Agent:** McManus (DevRel)
+**Model:** claude-haiku-4.5
+**Mode:** Background
+**Requested by:** williamhallatt
+**Status:** ✅ Complete
+
+## Objective
+Documentation sweep for `squad migrate --restore` changes. Ensure CLI reference, README, and scenario docs consistently reflect new command and flag.
+
+## Work Completed
+- Reviewed docs/reference/cli.md — added `squad migrate` command documentation
+- Reviewed docs/scenarios/disaster-recovery.md — updated `.ai-team/` → `.squad/`, modernized paths
+- Reviewed docs/scenarios/keep-my-squad.md — updated commands and examples
+- Reviewed README.md — updated command table
+- Verified docs/get-started/migration.md — already accurate
+- Verified docs/scenarios/upgrading.md — already accurate
+- Verified docs/scenarios/troubleshooting.md — already accurate
+
+## Files Modified
+- `docs/reference/cli.md`
+- `docs/scenarios/disaster-recovery.md`
+- `docs/scenarios/keep-my-squad.md`
+- `README.md`
+
+## Decisions Merged
+- Decision: mcmanus-doc-sweep-migrate.md merged into decisions.md
+
+## Key Outcome
+All migration-related documentation now synchronously references `squad migrate` and `--restore` flag. Disaster recovery guidance is modernized. Non-migration scenario docs (general, mid-project) deferred for future sweep.
+
+---
+**End time:** 2026-03-05T03:25:00Z
diff --git a/.squad/orchestration-log/2026-03-05T04-02-47Z-breedan.md b/.squad/orchestration-log/2026-03-05T04-02-47Z-breedan.md
new file mode 100644
index 000000000..afc4e8321
--- /dev/null
+++ b/.squad/orchestration-log/2026-03-05T04-02-47Z-breedan.md
@@ -0,0 +1,41 @@
+# Breedan Orchestration — 2026-03-05T04-02-47Z
+
+## Agent Info
+- **Agent:** Breedan (E2E Test Engineer)
+- **Model:** claude-sonnet-4.5
+- **Mode:** background
+
+## Work Completed
+Created `test/migrate-e2e.test.ts` with 23 end-to-end tests exercising the built CLI via `execFileSync`, covering:
+- Full migration flow (`.ai-team/` → `.squad/` with data preservation)
+- Dry-run mode with no side effects
+- Backup creation and restore operations
+- Legacy `.ai-team/` directory detection and handling
+- Shell reinit guard (prevents re-initializing after migration)
+- Auto-rollback on error scenarios
+- Team root resolution and `.first-run` cleanup
+- Exit code validation
+
+## Test Results
+- **migrate-e2e.test.ts:** 23 tests ✓ PASS
+- **All E2E assertions pass** — CLI behaves correctly end-to-end
+
+## Test Coverage Summary
+Combined with Hockney's unit tests:
+- **Total test suite:** 53 tests (19 unit + 11 integration + 23 E2E)
+- **Coverage areas:** migrate command, restore, backup discovery, guard logic, full CLI flow
+- **All tests passing** on first run
+
+## Files Changed
+- `test/migrate-e2e.test.ts` (new)
+
+## Integration Points Validated
+- CLI compilation and execution
+- Filesystem operations (backup, restore, migration)
+- Error handling and rollback
+- Guard patterns (shell reinit, .first-run cleanup)
+
+## Next Steps
+- Scribe to write session log
+- Merge orchestration logs and decision inbox
+- Commit all test files and squad/ changes
diff --git a/.squad/orchestration-log/2026-03-05T04-02-47Z-hockney.md b/.squad/orchestration-log/2026-03-05T04-02-47Z-hockney.md
new file mode 100644
index 000000000..2a33eae9a
--- /dev/null
+++ b/.squad/orchestration-log/2026-03-05T04-02-47Z-hockney.md
@@ -0,0 +1,40 @@
+# Hockney Orchestration — 2026-03-05T04-02-47Z
+
+## Agent Info
+- **Agent:** Hockney (Tester)
+- **Model:** claude-sonnet-4.5
+- **Mode:** background
+
+## Work Completed
+Created `test/migrate-command.test.ts` with 19 unit/integration tests covering:
+- `runMigrate()` basic flow and error handling
+- `runRestore()` with explicit and auto backup discovery
+- `findLatestBackup()` search logic
+- Dry-run mode (`--dry-run` flag)
+- Auto-rollback on migration error
+- `.first-run` file cleanup post-migration
+- Legacy `.ai-team/` directory migration and backup
+- Process exit mocking pattern (reusable for CLI testing)
+
+Created `test/cast-guard.test.ts` with 11 tests covering:
+- `createTeam()` charter.md protection guard (no overwrite if exists)
+- history.md protection guard (no overwrite if exists)
+- Allow-create when files absent or empty
+- Verify team initialization proceeds when guards pass
+
+## Test Results
+- **migrate-command.test.ts:** 19 tests ✓ PASS
+- **cast-guard.test.ts:** 11 tests ✓ PASS
+- **Total:** 30 tests, all passing
+
+## Decisions Written
+- `.squad/decisions/inbox/hockney-migrate-tests.md` — test patterns for migration and cast guard (error path testing, SDK mocking, temp dir hygiene, guard logic patterns)
+
+## Files Changed
+- `test/migrate-command.test.ts` (new)
+- `test/cast-guard.test.ts` (new)
+
+## Next Steps
+- Merge inbox decision into decisions.md
+- Commit tests and squad/ changes
+- Scribe to write session log and orchestration logs for Breedan
diff --git a/test/cast-guard.test.ts b/test/cast-guard.test.ts
new file mode 100644
index 000000000..870db8615
--- /dev/null
+++ b/test/cast-guard.test.ts
@@ -0,0 +1,251 @@
+/**
+ * Tests for Cast createTeam Guard Logic
+ * Ensures createTeam() does not overwrite existing non-empty charter.md and history.md files.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createTeam, type CastProposal, type CastMember } from '../packages/squad-cli/src/cli/core/cast.js';
+
+describe('Cast createTeam Guard Logic', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = mkdtempSync(join(tmpdir(), 'cast-guard-test-'));
+  });
+
+  afterEach(() => {
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  function createMinimalProposal(members: CastMember[]): CastProposal {
+    return {
+      members,
+      universe: 'Test Universe',
+      projectDescription: 'Test project for cast guard tests'
+    };
+  }
+
+  describe('charter.md guard', () => {
+    it('should NOT overwrite an existing non-empty charter.md', async () => {
+      const squadDir = join(testDir, '.squad');
+      const agentsDir = join(squadDir, 'agents');
+      const testAgentDir = join(agentsDir, 'tester');
+      
+      // Create existing charter with content
+      mkdirSync(testAgentDir, { recursive: true });
+      const existingCharter = '# Existing Charter\n\nThis is my real charter.\n';
+      writeFileSync(join(testAgentDir, 'charter.md'), existingCharter);
+
+      const proposal = createMinimalProposal([
+        { name: 'Tester', role: 'QA Engineer', scope: 'Testing', emoji: '🧪' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      // Charter should remain unchanged
+      const actualCharter = readFileSync(join(testAgentDir, 'charter.md'), 'utf8');
+      expect(actualCharter).toBe(existingCharter);
+    });
+
+    it('should write charter.md if the file does not exist', async () => {
+      const proposal = createMinimalProposal([
+        { name: 'Developer', role: 'Backend Dev', scope: 'APIs', emoji: '🔧' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      const charterPath = join(testDir, '.squad', 'agents', 'developer', 'charter.md');
+      expect(existsSync(charterPath)).toBe(true);
+
+      const content = readFileSync(charterPath, 'utf8');
+      expect(content).toContain('# Developer — Backend Dev');
+    });
+
+    it('should write charter.md if the file exists but is empty', async () => {
+      const squadDir = join(testDir, '.squad');
+      const agentsDir = join(squadDir, 'agents');
+      const devDir = join(agentsDir, 'developer');
+      
+      mkdirSync(devDir, { recursive: true });
+      writeFileSync(join(devDir, 'charter.md'), '');
+
+      const proposal = createMinimalProposal([
+        { name: 'Developer', role: 'Backend Dev', scope: 'APIs', emoji: '🔧' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      const content = readFileSync(join(devDir, 'charter.md'), 'utf8');
+      expect(content).toContain('# Developer — Backend Dev');
+    });
+
+    it('should write charter.md if the file contains only whitespace', async () => {
+      const squadDir = join(testDir, '.squad');
+      const agentsDir = join(squadDir, 'agents');
+      const devDir = join(agentsDir, 'developer');
+      
+      mkdirSync(devDir, { recursive: true });
+      writeFileSync(join(devDir, 'charter.md'), '   \n  \t  \n  ');
+
+      const proposal = createMinimalProposal([
+        { name: 'Developer', role: 'Backend Dev', scope: 'APIs', emoji: '🔧' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      const content = readFileSync(join(devDir, 'charter.md'), 'utf8');
+      expect(content).toContain('# Developer — Backend Dev');
+      expect(content.trim().length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('history.md guard', () => {
+    it('should NOT overwrite an existing non-empty history.md', async () => {
+      const squadDir = join(testDir, '.squad');
+      const agentsDir = join(squadDir, 'agents');
+      const testAgentDir = join(agentsDir, 'tester');
+      
+      // Create existing history with content
+      mkdirSync(testAgentDir, { recursive: true });
+      const existingHistory = '# Tester — History\n\n## Learnings\n\nI found a critical bug.\n';
+      writeFileSync(join(testAgentDir, 'history.md'), existingHistory);
+
+      const proposal = createMinimalProposal([
+        { name: 'Tester', role: 'QA Engineer', scope: 'Testing', emoji: '🧪' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      // History should remain unchanged
+      const actualHistory = readFileSync(join(testAgentDir, 'history.md'), 'utf8');
+      expect(actualHistory).toBe(existingHistory);
+    });
+
+    it('should write history.md if the file does not exist', async () => {
+      const proposal = createMinimalProposal([
+        { name: 'Developer', role: 'Backend Dev', scope: 'APIs', emoji: '🔧' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      const historyPath = join(testDir, '.squad', 'agents', 'developer', 'history.md');
+      expect(existsSync(historyPath)).toBe(true);
+
+      const content = readFileSync(historyPath, 'utf8');
+      expect(content).toContain('# Developer — History');
+    });
+
+    it('should write history.md if the file exists but is empty', async () => {
+      const squadDir = join(testDir, '.squad');
+      const agentsDir = join(squadDir, 'agents');
+      const devDir = join(agentsDir, 'developer');
+      
+      mkdirSync(devDir, { recursive: true });
+      writeFileSync(join(devDir, 'history.md'), '');
+
+      const proposal = createMinimalProposal([
+        { name: 'Developer', role: 'Backend Dev', scope: 'APIs', emoji: '🔧' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      const content = readFileSync(join(devDir, 'history.md'), 'utf8');
+      expect(content).toContain('# Developer — History');
+    });
+
+    it('should write history.md if the file contains only whitespace', async () => {
+      const squadDir = join(testDir, '.squad');
+      const agentsDir = join(squadDir, 'agents');
+      const devDir = join(agentsDir, 'developer');
+      
+      mkdirSync(devDir, { recursive: true });
+      writeFileSync(join(devDir, 'history.md'), '  \n\t\n  ');
+
+      const proposal = createMinimalProposal([
+        { name: 'Developer', role: 'Backend Dev', scope: 'APIs', emoji: '🔧' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      const content = readFileSync(join(devDir, 'history.md'), 'utf8');
+      expect(content).toContain('# Developer — History');
+      expect(content.trim().length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('combined guard behavior', () => {
+    it('should protect both charter.md and history.md when both have content', async () => {
+      const squadDir = join(testDir, '.squad');
+      const agentsDir = join(squadDir, 'agents');
+      const testAgentDir = join(agentsDir, 'tester');
+      
+      mkdirSync(testAgentDir, { recursive: true });
+      
+      const existingCharter = '# My Real Charter\n';
+      const existingHistory = '# My Real History\n';
+      
+      writeFileSync(join(testAgentDir, 'charter.md'), existingCharter);
+      writeFileSync(join(testAgentDir, 'history.md'), existingHistory);
+
+      const proposal = createMinimalProposal([
+        { name: 'Tester', role: 'QA Engineer', scope: 'Testing', emoji: '🧪' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      expect(readFileSync(join(testAgentDir, 'charter.md'), 'utf8')).toBe(existingCharter);
+      expect(readFileSync(join(testAgentDir, 'history.md'), 'utf8')).toBe(existingHistory);
+    });
+
+    it('should write charter.md but protect history.md when only history has content', async () => {
+      const squadDir = join(testDir, '.squad');
+      const agentsDir = join(squadDir, 'agents');
+      const testAgentDir = join(agentsDir, 'tester');
+      
+      mkdirSync(testAgentDir, { recursive: true });
+      
+      writeFileSync(join(testAgentDir, 'charter.md'), '');
+      const existingHistory = '# My Real History\n';
+      writeFileSync(join(testAgentDir, 'history.md'), existingHistory);
+
+      const proposal = createMinimalProposal([
+        { name: 'Tester', role: 'QA Engineer', scope: 'Testing', emoji: '🧪' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      const newCharter = readFileSync(join(testAgentDir, 'charter.md'), 'utf8');
+      expect(newCharter).toContain('# Tester — QA Engineer');
+      
+      expect(readFileSync(join(testAgentDir, 'history.md'), 'utf8')).toBe(existingHistory);
+    });
+
+    it('should write history.md but protect charter.md when only charter has content', async () => {
+      const squadDir = join(testDir, '.squad');
+      const agentsDir = join(squadDir, 'agents');
+      const testAgentDir = join(agentsDir, 'tester');
+      
+      mkdirSync(testAgentDir, { recursive: true });
+      
+      const existingCharter = '# My Real Charter\n';
+      writeFileSync(join(testAgentDir, 'charter.md'), existingCharter);
+      writeFileSync(join(testAgentDir, 'history.md'), '   ');
+
+      const proposal = createMinimalProposal([
+        { name: 'Tester', role: 'QA Engineer', scope: 'Testing', emoji: '🧪' }
+      ]);
+
+      await createTeam(testDir, proposal);
+
+      expect(readFileSync(join(testAgentDir, 'charter.md'), 'utf8')).toBe(existingCharter);
+      
+      const newHistory = readFileSync(join(testAgentDir, 'history.md'), 'utf8');
+      expect(newHistory).toContain('# Tester — History');
+    });
+  });
+});
diff --git a/test/migrate-command.test.ts b/test/migrate-command.test.ts
new file mode 100644
index 000000000..07805a71c
--- /dev/null
+++ b/test/migrate-command.test.ts
@@ -0,0 +1,350 @@
+/**
+ * Comprehensive tests for Squad Migrate Command
+ * Tests migration, backup, restore, and rollback functionality.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync, rmSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { runMigrate, type MigrateOptions } from '../packages/squad-cli/src/cli/core/migrate.js';
+
+// Mock the SDK
+vi.mock('@bradygaster/squad-sdk', () => ({
+  initSquad: vi.fn(async (opts) => {
+    // Simulate what sdkInitSquad does: create .squad/ structure
+    const squadDir = join(opts.teamRoot, '.squad');
+    mkdirSync(squadDir, { recursive: true });
+    mkdirSync(join(squadDir, 'templates'), { recursive: true });
+    mkdirSync(join(squadDir, 'casting'), { recursive: true });
+    writeFileSync(join(squadDir, 'team.md'), '# Team\n\nFresh init team.md\n');
+    // Simulate first-run markers that should be cleaned up
+    writeFileSync(join(squadDir, '.first-run'), '');
+    writeFileSync(join(squadDir, '.init-prompt'), 'some prompt');
+  }),
+}));
+
+describe('Squad Migrate Command', () => {
+  let testDir: string;
+  let exitSpy: any;
+  let sdkInitSquad: any;
+
+  beforeEach(async () => {
+    testDir = mkdtempSync(join(tmpdir(), 'squad-migrate-test-'));
+    exitSpy = vi.spyOn(process, 'exit').mockImplementation((code?: any) => {
+      throw new Error(`process.exit: ${code}`);
+    });
+
+    // Get mocked sdkInitSquad
+    const { initSquad } = await import('@bradygaster/squad-sdk');
+    sdkInitSquad = initSquad;
+    vi.mocked(sdkInitSquad).mockClear();
+  });
+
+  afterEach(() => {
+    exitSpy.mockRestore();
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('findLatestBackup (tested indirectly via restore)', () => {
+    it('should exit(1) when no backups exist', async () => {
+      await expect(
+        runMigrate(testDir, { restore: true })
+      ).rejects.toThrow('process.exit: 1');
+    });
+
+    it('should restore from the only backup when one exists', async () => {
+      // Create .squad/ with content
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(join(squadDir, 'agents'), { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Original Team\n');
+
+      // Run migrate to create a backup
+      await runMigrate(testDir, {});
+
+      // Modify .squad/team.md
+      writeFileSync(join(squadDir, 'team.md'), '# Modified Team\n');
+
+      // Restore
+      await runMigrate(testDir, { restore: true });
+
+      const restoredContent = readFileSync(join(squadDir, 'team.md'), 'utf8');
+      expect(restoredContent).toBe('# Original Team\n');
+    });
+
+    it('should restore from the most recent backup when multiple exist', async () => {
+      const squadDir = join(testDir, '.squad');
+
+      // Create three backups manually
+      const backup1 = join(testDir, '.squad-backup-2024-01-01T10-00-00');
+      const backup2 = join(testDir, '.squad-backup-2024-01-02T10-00-00');
+      const backup3 = join(testDir, '.squad-backup-2024-01-03T10-00-00');
+
+      mkdirSync(backup1, { recursive: true });
+      writeFileSync(join(backup1, 'team.md'), 'backup1');
+
+      mkdirSync(backup2, { recursive: true });
+      writeFileSync(join(backup2, 'team.md'), 'backup2');
+
+      mkdirSync(backup3, { recursive: true });
+      writeFileSync(join(backup3, 'team.md'), 'backup3');
+
+      // Create current .squad/
+      mkdirSync(squadDir, { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), 'current');
+
+      // Restore with auto-detect
+      await runMigrate(testDir, { restore: true });
+
+      const restoredContent = readFileSync(join(squadDir, 'team.md'), 'utf8');
+      expect(restoredContent).toBe('backup3'); // Most recent
+    });
+  });
+
+  describe('runMigrate - dry run', () => {
+    it('should create no files or directories in dry-run mode', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(join(squadDir, 'templates'), { recursive: true });
+      mkdirSync(join(squadDir, 'agents'), { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Team\n');
+
+      const beforeEntries = readdirSync(testDir);
+
+      await runMigrate(testDir, { dryRun: true });
+
+      const afterEntries = readdirSync(testDir);
+      expect(afterEntries).toEqual(beforeEntries);
+    });
+
+    it('should not call sdkInitSquad in dry-run mode', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(squadDir, { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Team\n');
+
+      await runMigrate(testDir, { dryRun: true });
+
+      expect(sdkInitSquad).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('runMigrate - normal flow', () => {
+    it('should create a backup with timestamp format', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(squadDir, { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Original\n');
+
+      await runMigrate(testDir, {});
+
+      const entries = readdirSync(testDir);
+      const backupDirs = entries.filter(e => e.startsWith('.squad-backup-'));
+      expect(backupDirs.length).toBe(1);
+      expect(backupDirs[0]).toMatch(/\.squad-backup-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}/);
+    });
+
+    it('should backup the original contents', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(join(squadDir, 'agents', 'test-agent'), { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Original Team\n');
+      writeFileSync(join(squadDir, 'agents', 'test-agent', 'charter.md'), '# Test Charter\n');
+
+      await runMigrate(testDir, {});
+
+      const entries = readdirSync(testDir);
+      const backupDir = entries.find(e => e.startsWith('.squad-backup-'));
+      expect(backupDir).toBeDefined();
+
+      const backupPath = join(testDir, backupDir!);
+      expect(readFileSync(join(backupPath, 'team.md'), 'utf8')).toBe('# Original Team\n');
+      expect(readFileSync(join(backupPath, 'agents', 'test-agent', 'charter.md'), 'utf8')).toBe('# Test Charter\n');
+    });
+
+    it('should remove SQUAD_OWNED dirs (templates, casting) before reinit', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(join(squadDir, 'templates'), { recursive: true });
+      mkdirSync(join(squadDir, 'casting'), { recursive: true });
+      writeFileSync(join(squadDir, 'templates', 'test.md'), 'template content');
+      writeFileSync(join(squadDir, 'casting', 'proposal.json'), '{}');
+
+      await runMigrate(testDir, {});
+
+      // After migration, these should be freshly created by sdkInitSquad (empty or default)
+      // But the old content should be gone
+      const entries = readdirSync(testDir);
+      const backupDir = entries.find(e => e.startsWith('.squad-backup-'));
+      const backupPath = join(testDir, backupDir!);
+
+      // Backup should have the original files
+      expect(existsSync(join(backupPath, 'templates', 'test.md'))).toBe(true);
+      expect(existsSync(join(backupPath, 'casting', 'proposal.json'))).toBe(true);
+    });
+
+    it('should restore USER_OWNED files after reinit', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(join(squadDir, 'agents', 'my-agent'), { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# My Team\n');
+      writeFileSync(join(squadDir, 'routing.md'), '# My Routing\n');
+      writeFileSync(join(squadDir, 'agents', 'my-agent', 'charter.md'), '# My Charter\n');
+
+      await runMigrate(testDir, {});
+
+      // After migration, user files should be restored
+      expect(readFileSync(join(squadDir, 'team.md'), 'utf8')).toBe('# My Team\n');
+      expect(readFileSync(join(squadDir, 'routing.md'), 'utf8')).toBe('# My Routing\n');
+      expect(readFileSync(join(squadDir, 'agents', 'my-agent', 'charter.md'), 'utf8')).toBe('# My Charter\n');
+    });
+
+    it('should delete .first-run and .init-prompt markers after sdkInitSquad', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(squadDir, { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Team\n');
+
+      await runMigrate(testDir, {});
+
+      // sdkInitSquad creates these markers, but migrate should clean them up
+      expect(existsSync(join(squadDir, '.first-run'))).toBe(false);
+      expect(existsSync(join(squadDir, '.init-prompt'))).toBe(false);
+    });
+  });
+
+  describe('runMigrate - no .squad/ directory', () => {
+    it('should run fresh init when no .squad/ exists', async () => {
+      await runMigrate(testDir, {});
+
+      expect(sdkInitSquad).toHaveBeenCalledWith(
+        expect.objectContaining({
+          teamRoot: testDir,
+          skipExisting: true,
+          includeWorkflows: true,
+          includeTemplates: true,
+        })
+      );
+
+      expect(existsSync(join(testDir, '.squad'))).toBe(true);
+    });
+
+    it('should not create a backup when no .squad/ exists', async () => {
+      await runMigrate(testDir, {});
+
+      const entries = readdirSync(testDir);
+      const backupDirs = entries.filter(e => e.startsWith('.squad-backup-'));
+      expect(backupDirs.length).toBe(0);
+    });
+  });
+
+  describe('runMigrate - legacy .ai-team/ directory', () => {
+    it('should detect and migrate from .ai-team/ when .squad/ absent', async () => {
+      const legacyDir = join(testDir, '.ai-team');
+      mkdirSync(join(legacyDir, 'agents'), { recursive: true });
+      writeFileSync(join(legacyDir, 'team.md'), '# Legacy Team\n');
+
+      await runMigrate(testDir, {});
+
+      // After migration, .squad/ should exist with the legacy content
+      const squadDir = join(testDir, '.squad');
+      expect(existsSync(squadDir)).toBe(true);
+      expect(readFileSync(join(squadDir, 'team.md'), 'utf8')).toBe('# Legacy Team\n');
+
+      // .ai-team/ should be removed
+      expect(existsSync(legacyDir)).toBe(false);
+    });
+
+    it('should back up .ai-team/ contents before removing', async () => {
+      const legacyDir = join(testDir, '.ai-team');
+      mkdirSync(legacyDir, { recursive: true });
+      writeFileSync(join(legacyDir, 'team.md'), '# Legacy Team\n');
+
+      await runMigrate(testDir, {});
+
+      const entries = readdirSync(testDir);
+      const backupDir = entries.find(e => e.startsWith('.squad-backup-'));
+      expect(backupDir).toBeDefined();
+
+      const backupPath = join(testDir, backupDir!);
+      expect(readFileSync(join(backupPath, 'team.md'), 'utf8')).toBe('# Legacy Team\n');
+    });
+  });
+
+  describe('runMigrate - auto-rollback on error', () => {
+    it('should restore .squad/ from backup when sdkInitSquad throws', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(join(squadDir, 'agents'), { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Original Team\n');
+
+      // Make sdkInitSquad throw
+      vi.mocked(sdkInitSquad).mockRejectedValueOnce(new Error('Init failed'));
+
+      await expect(
+        runMigrate(testDir, {})
+      ).rejects.toThrow('process.exit: 1');
+
+      // After rollback, .squad/ should have original content
+      expect(readFileSync(join(squadDir, 'team.md'), 'utf8')).toBe('# Original Team\n');
+    });
+
+    it('should call process.exit(1) after rollback', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(squadDir, { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Team\n');
+
+      vi.mocked(sdkInitSquad).mockRejectedValueOnce(new Error('Init failed'));
+
+      await expect(
+        runMigrate(testDir, {})
+      ).rejects.toThrow('process.exit: 1');
+
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+  });
+
+  describe('runMigrate - restore with auto-detection', () => {
+    it('should remove existing .squad/ and replace with backup contents', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(squadDir, { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Original\n');
+
+      // Run migrate to create backup
+      await runMigrate(testDir, {});
+
+      // Modify current .squad/
+      writeFileSync(join(squadDir, 'team.md'), '# Modified\n');
+      writeFileSync(join(squadDir, 'new-file.md'), '# New\n');
+
+      // Restore
+      await runMigrate(testDir, { restore: true });
+
+      expect(readFileSync(join(squadDir, 'team.md'), 'utf8')).toBe('# Original\n');
+      expect(existsSync(join(squadDir, 'new-file.md'))).toBe(false);
+    });
+  });
+
+  describe('runMigrate - restore with explicit path', () => {
+    it('should restore from explicit absolute path', async () => {
+      const squadDir = join(testDir, '.squad');
+      const backupPath = join(testDir, 'my-custom-backup');
+
+      // Create backup manually
+      mkdirSync(backupPath, { recursive: true });
+      writeFileSync(join(backupPath, 'team.md'), '# Custom Backup\n');
+
+      // Create current .squad/
+      mkdirSync(squadDir, { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '# Current\n');
+
+      // Restore from explicit path
+      await runMigrate(testDir, { restore: backupPath });
+
+      expect(readFileSync(join(squadDir, 'team.md'), 'utf8')).toBe('# Custom Backup\n');
+    });
+
+    it('should exit(1) when explicit restore path does not exist', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(squadDir, { recursive: true });
+
+      await expect(
+        runMigrate(testDir, { restore: '/non/existent/path' })
+      ).rejects.toThrow('process.exit: 1');
+    });
+  });
+});
diff --git a/test/migrate-e2e.test.ts b/test/migrate-e2e.test.ts
new file mode 100644
index 000000000..d421b48fe
--- /dev/null
+++ b/test/migrate-e2e.test.ts
@@ -0,0 +1,519 @@
+/**
+ * E2E tests for `squad migrate` command.
+ *
+ * Tests the full migration flow:
+ * - squad migrate --dry-run
+ * - squad migrate (backup + reinit + restore)
+ * - squad migrate --restore (auto-detect + explicit path)
+ * - Shell reinit guard (no .first-run after migrate)
+ *
+ * Uses execFileSync for non-interactive CLI testing.
+ * @see packages/squad-cli/src/cli/core/migrate.ts
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { rm } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+
+// ─── CLI configuration ──────────────────────────────────────────────────────
+
+// Use the built CLI since index.js has syntax issues (type:module in package.json but CJS syntax)
+const CLI = join(__dirname, '..', 'packages', 'squad-cli', 'dist', 'cli-entry.js');
+
+interface SquadResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+function runSquad(args: string[], cwd: string): SquadResult {
+  try {
+    const stdout = execFileSync(process.execPath, [CLI, ...args], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 30000,
+      env: { ...process.env, NO_COLOR: '1' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { stdout, stderr: '', exitCode: 0 };
+  } catch (err: any) {
+    return {
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      exitCode: err.status ?? 1,
+    };
+  }
+}
+
+// ─── Test fixtures ──────────────────────────────────────────────────────────
+
+/**
+ * Create a realistic populated .squad/ directory with agents and history.
+ * This simulates a project that has been used and has user content.
+ */
+function createPopulatedSquadDir(root: string, opts?: { includeFirstRun?: boolean }): void {
+  const { includeFirstRun = false } = opts ?? {};
+  const squadDir = join(root, '.squad');
+  const agentsDir = join(squadDir, 'agents');
+  const identityDir = join(squadDir, 'identity');
+
+  // Create directory structure
+  mkdirSync(join(agentsDir, 'keaton'), { recursive: true });
+  mkdirSync(join(agentsDir, 'fenster'), { recursive: true });
+  mkdirSync(identityDir, { recursive: true });
+
+  // team.md with populated roster (at least one agent = post-init state)
+  writeFileSync(
+    join(squadDir, 'team.md'),
+    `# Squad Team — Test Project
+
+> A test project for squad migrate E2E tests.
+
+## Members
+
+| Name    | Role       | Charter                                | Status     |
+|---------|------------|----------------------------------------|------------|
+| Keaton  | Lead       | \`.squad/agents/keaton/charter.md\`    | ✅ Active  |
+| Fenster | Core Dev   | \`.squad/agents/fenster/charter.md\`   | ✅ Active  |
+
+## Project
+
+We're building E2E test coverage for Squad.
+`
+  );
+
+  // Agent charters (user-owned files that must be preserved)
+  writeFileSync(
+    join(agentsDir, 'keaton', 'charter.md'),
+    `# Keaton — Lead
+
+## Role
+Technical lead and architect.
+
+## Scope
+- System design
+- Code review
+- Mentoring
+
+## Outputs
+- Architecture docs
+- Design reviews
+`
+  );
+
+  writeFileSync(
+    join(agentsDir, 'fenster', 'charter.md'),
+    `# Fenster — Core Dev
+
+## Role
+Core contributor and implementer.
+
+## Scope
+- Feature implementation
+- Bug fixes
+- Unit tests
+
+## Outputs
+- Working code
+- Test suites
+`
+  );
+
+  // Agent history files (user-owned, must be preserved)
+  writeFileSync(
+    join(agentsDir, 'keaton', 'history.md'),
+    `# Keaton — History
+
+## Learnings
+
+- Always design before coding
+- Document key decisions
+`
+  );
+
+  writeFileSync(
+    join(agentsDir, 'fenster', 'history.md'),
+    `# Fenster — History
+
+## Learnings
+
+- Write tests first
+- Refactor incrementally
+`
+  );
+
+  // Identity file
+  writeFileSync(
+    join(identityDir, 'now.md'),
+    `---
+updated_at: 2025-01-15T12:00:00.000Z
+focus_area: E2E testing
+active_issues: []
+---
+
+# What We're Focused On
+
+Building E2E test coverage.
+`
+  );
+
+  // Add .first-run marker if requested (simulates pre-migration state)
+  if (includeFirstRun) {
+    writeFileSync(join(squadDir, '.first-run'), '');
+  }
+}
+
+/**
+ * Create a backup directory with known content for --restore tests.
+ */
+function createBackupDir(root: string, backupName: string): string {
+  const backupDir = join(root, backupName);
+  mkdirSync(backupDir, { recursive: true });
+
+  writeFileSync(
+    join(backupDir, 'team.md'),
+    `# Squad Team — Backup
+
+> This is backup content.
+
+## Members
+
+| Name   | Role    | Charter                             | Status     |
+|--------|---------|-------------------------------------|------------|
+| Backup | Agent   | \`.squad/agents/backup/charter.md\` | ✅ Active  |
+`
+  );
+
+  const agentsDir = join(backupDir, 'agents', 'backup');
+  mkdirSync(agentsDir, { recursive: true });
+
+  writeFileSync(
+    join(agentsDir, 'charter.md'),
+    `# Backup Agent
+
+This is a backup charter.
+`
+  );
+
+  return backupDir;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Test suite
+// ═══════════════════════════════════════════════════════════════════════════
+
+describe('E2E: squad migrate', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'squad-migrate-e2e-'));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 1. squad migrate --dry-run
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe('migrate --dry-run', () => {
+    it('exits 0 and outputs [dry-run] marker', () => {
+      createPopulatedSquadDir(tempDir);
+      const result = runSquad(['migrate', '--dry-run'], tempDir);
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('[dry-run]');
+    });
+
+    it('creates no .squad-backup-* directories', () => {
+      createPopulatedSquadDir(tempDir);
+      runSquad(['migrate', '--dry-run'], tempDir);
+
+      const entries = readdirSync(tempDir);
+      const backups = entries.filter((e) => e.startsWith('.squad-backup-'));
+      expect(backups).toHaveLength(0);
+    });
+
+    it('leaves .squad/ untouched (contents identical)', () => {
+      createPopulatedSquadDir(tempDir);
+      const beforeTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+      const beforeKeaton = readFileSync(
+        join(tempDir, '.squad', 'agents', 'keaton', 'charter.md'),
+        'utf8'
+      );
+
+      runSquad(['migrate', '--dry-run'], tempDir);
+
+      const afterTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+      const afterKeaton = readFileSync(
+        join(tempDir, '.squad', 'agents', 'keaton', 'charter.md'),
+        'utf8'
+      );
+
+      expect(afterTeam).toBe(beforeTeam);
+      expect(afterKeaton).toBe(beforeKeaton);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 2. squad migrate (full migration flow)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe('migrate (full flow)', () => {
+    it('creates exactly one .squad-backup-* directory', () => {
+      createPopulatedSquadDir(tempDir);
+      const result = runSquad(['migrate'], tempDir);
+
+      expect(result.exitCode).toBe(0);
+      const entries = readdirSync(tempDir);
+      const backups = entries.filter((e) => e.startsWith('.squad-backup-'));
+      expect(backups).toHaveLength(1);
+    });
+
+    it('backup contains the original team.md', () => {
+      createPopulatedSquadDir(tempDir);
+      const originalTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+
+      runSquad(['migrate'], tempDir);
+
+      const entries = readdirSync(tempDir);
+      const backupDir = entries.find((e) => e.startsWith('.squad-backup-'));
+      expect(backupDir).toBeTruthy();
+
+      const backedUpTeam = readFileSync(join(tempDir, backupDir!, 'team.md'), 'utf8');
+      expect(backedUpTeam).toBe(originalTeam);
+    });
+
+    it('removes .squad/.first-run after migration', () => {
+      createPopulatedSquadDir(tempDir, { includeFirstRun: true });
+      expect(existsSync(join(tempDir, '.squad', '.first-run'))).toBe(true);
+
+      runSquad(['migrate'], tempDir);
+
+      expect(existsSync(join(tempDir, '.squad', '.first-run'))).toBe(false);
+    });
+
+    it('removes .squad/.init-prompt after migration', () => {
+      createPopulatedSquadDir(tempDir);
+      writeFileSync(join(tempDir, '.squad', '.init-prompt'), 'init prompt data');
+      expect(existsSync(join(tempDir, '.squad', '.init-prompt'))).toBe(true);
+
+      runSquad(['migrate'], tempDir);
+
+      expect(existsSync(join(tempDir, '.squad', '.init-prompt'))).toBe(false);
+    });
+
+    it('preserves agents/ directory with user content', () => {
+      createPopulatedSquadDir(tempDir);
+      const originalCharter = readFileSync(
+        join(tempDir, '.squad', 'agents', 'keaton', 'charter.md'),
+        'utf8'
+      );
+
+      runSquad(['migrate'], tempDir);
+
+      expect(existsSync(join(tempDir, '.squad', 'agents'))).toBe(true);
+      expect(
+        existsSync(join(tempDir, '.squad', 'agents', 'keaton', 'charter.md'))
+      ).toBe(true);
+
+      const restoredCharter = readFileSync(
+        join(tempDir, '.squad', 'agents', 'keaton', 'charter.md'),
+        'utf8'
+      );
+      expect(restoredCharter).toBe(originalCharter);
+    });
+
+    it('preserves user team.md content after migration', () => {
+      createPopulatedSquadDir(tempDir);
+      const originalTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+
+      runSquad(['migrate'], tempDir);
+
+      // team.md should have user roster preserved
+      const migratedTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+      expect(migratedTeam).toContain('Keaton');
+      expect(migratedTeam).toContain('Fenster');
+      // Basic structure should be maintained (not identical due to reinit template)
+      expect(migratedTeam).toContain('## Members');
+    });
+
+    it('exit code is 0 for successful migration', () => {
+      createPopulatedSquadDir(tempDir);
+      const result = runSquad(['migrate'], tempDir);
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 3. squad migrate --restore (auto-detect)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe('migrate --restore (auto-detect)', () => {
+    it('finds and restores from .squad-backup-* directory', () => {
+      createPopulatedSquadDir(tempDir);
+      const backupDir = createBackupDir(tempDir, '.squad-backup-20250115-120000');
+
+      // Overwrite current .squad/team.md with different content
+      writeFileSync(join(tempDir, '.squad', 'team.md'), '# Modified Team\n');
+
+      const result = runSquad(['migrate', '--restore'], tempDir);
+
+      expect(result.exitCode).toBe(0);
+      const restoredTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+      expect(restoredTeam).toContain('# Squad Team — Backup');
+      expect(restoredTeam).toContain('Backup');
+    });
+
+    it('team.md after restore matches backup team.md', () => {
+      createPopulatedSquadDir(tempDir);
+      const backupDir = createBackupDir(tempDir, '.squad-backup-20250115-120000');
+      const backupTeam = readFileSync(join(backupDir, 'team.md'), 'utf8');
+
+      runSquad(['migrate', '--restore'], tempDir);
+
+      const restoredTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+      expect(restoredTeam).toBe(backupTeam);
+    });
+
+    it('exit code is 0 for successful restore', () => {
+      createPopulatedSquadDir(tempDir);
+      createBackupDir(tempDir, '.squad-backup-20250115-120000');
+
+      const result = runSquad(['migrate', '--restore'], tempDir);
+      expect(result.exitCode).toBe(0);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 4. squad migrate --restore <explicit-path>
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe('migrate --restore <explicit-path>', () => {
+    it('restores from explicit relative path', () => {
+      createPopulatedSquadDir(tempDir);
+      const backupName = '.squad-backup-explicit';
+      createBackupDir(tempDir, backupName);
+
+      const result = runSquad(['migrate', '--restore', backupName], tempDir);
+
+      expect(result.exitCode).toBe(0);
+      const restoredTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+      expect(restoredTeam).toContain('# Squad Team — Backup');
+    });
+
+    it('restores from explicit absolute path', () => {
+      createPopulatedSquadDir(tempDir);
+      const backupName = '.squad-backup-absolute';
+      const backupPath = createBackupDir(tempDir, backupName);
+
+      const result = runSquad(['migrate', '--restore', backupPath], tempDir);
+
+      expect(result.exitCode).toBe(0);
+      const restoredTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+      expect(restoredTeam).toContain('# Squad Team — Backup');
+    });
+
+    it('team.md after restore matches explicit backup', () => {
+      createPopulatedSquadDir(tempDir);
+      const backupName = '.squad-backup-explicit2';
+      const backupPath = createBackupDir(tempDir, backupName);
+      const backupTeam = readFileSync(join(backupPath, 'team.md'), 'utf8');
+
+      runSquad(['migrate', '--restore', backupName], tempDir);
+
+      const restoredTeam = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+      expect(restoredTeam).toBe(backupTeam);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 5. No .squad/ directory (fresh init)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe('migrate with no .squad/ directory', () => {
+    it('exits 0 and creates .squad/ (fresh init path)', () => {
+      // tempDir has no .squad/ at all
+      const result = runSquad(['migrate'], tempDir);
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain('Initialized fresh .squad/');
+      expect(existsSync(join(tempDir, '.squad'))).toBe(true);
+      expect(existsSync(join(tempDir, '.squad', 'team.md'))).toBe(true);
+    });
+
+    it('creates fresh team.md with roster', () => {
+      runSquad(['migrate'], tempDir);
+
+      const teamMd = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+      expect(teamMd).toContain('## Members');
+    });
+
+    it('fresh init via migrate leaves .first-run marker (IS a first run)', () => {
+      // When migrate does a fresh init, it's genuinely a first run
+      runSquad(['migrate'], tempDir);
+
+      // .first-run SHOULD exist because this is a brand new initialization
+      expect(existsSync(join(tempDir, '.squad', '.first-run'))).toBe(true);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // 6. Shell reinit guard: .first-run absent after migrate
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe('shell reinit guard (filesystem assertion)', () => {
+    it('.first-run does NOT exist after migrate (ONLY when migrating existing .squad/)', () => {
+      createPopulatedSquadDir(tempDir, { includeFirstRun: true });
+
+      // Pre-condition: .first-run exists
+      expect(existsSync(join(tempDir, '.squad', '.first-run'))).toBe(true);
+
+      runSquad(['migrate'], tempDir);
+
+      // Post-condition: .first-run is removed by migrate (line 246-251 in migrate.ts)
+      // This is the critical bug fix: migrate cleans up .first-run after reinit
+      expect(existsSync(join(tempDir, '.squad', '.first-run'))).toBe(false);
+    });
+
+    it('agents/ directory still exists after migrate', () => {
+      createPopulatedSquadDir(tempDir, { includeFirstRun: true });
+
+      runSquad(['migrate'], tempDir);
+
+      expect(existsSync(join(tempDir, '.squad', 'agents'))).toBe(true);
+      expect(
+        existsSync(join(tempDir, '.squad', 'agents', 'keaton', 'charter.md'))
+      ).toBe(true);
+    });
+
+    it('.init-prompt cleanup prevents orphan state', () => {
+      createPopulatedSquadDir(tempDir);
+      writeFileSync(join(tempDir, '.squad', '.init-prompt'), 'orphan data');
+
+      runSquad(['migrate'], tempDir);
+
+      // .init-prompt should be cleaned up by migrate (line 246-251)
+      expect(existsSync(join(tempDir, '.squad', '.init-prompt'))).toBe(false);
+    });
+
+    it('team.md with populated roster blocks shell reinit', () => {
+      createPopulatedSquadDir(tempDir, { includeFirstRun: true });
+
+      runSquad(['migrate'], tempDir);
+
+      const teamMd = readFileSync(join(tempDir, '.squad', 'team.md'), 'utf8');
+
+      // Verify roster has entries (hasRosterEntries() would return true)
+      expect(teamMd).toMatch(/\|\s*Keaton\s*\|/);
+      expect(teamMd).toMatch(/\|\s*Fenster\s*\|/);
+
+      // Combined with no .first-run, shell won't trigger init
+      expect(existsSync(join(tempDir, '.squad', '.first-run'))).toBe(false);
+    });
+  });
+});

From ad5761df2bc6d5744fe39c7c06fc3eb994ca549e Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 14:25:24 +1000
Subject: [PATCH 08/12] fix(migrate): create casting state after migration when
 registry missing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two-case fix for casting/registry.json not existing after squad migrate:
- Case A (v0.8.x repos): backup had casting/ → restore entire casting/
  directory from backup, preserving existing names and universe assignments
- Case B (v0.5.x repos): backup lacked casting/ → scan restored agents/
  and create registry.json with each agent as legacy_named:true, plus
  default policy.json and empty history.json

Fixes squad doctor ❌ casting/registry.json after migration.

Adds 4 new tests covering both migration cases (57 total, all pass).
---
 packages/squad-cli/src/cli/core/migrate.ts | 79 ++++++++++++++++++++++
 test/migrate-command.test.ts               | 75 ++++++++++++++++++++
 2 files changed, 154 insertions(+)

diff --git a/packages/squad-cli/src/cli/core/migrate.ts b/packages/squad-cli/src/cli/core/migrate.ts
index 89b34d854..20a4789a8 100644
--- a/packages/squad-cli/src/cli/core/migrate.ts
+++ b/packages/squad-cli/src/cli/core/migrate.ts
@@ -273,6 +273,85 @@ export async function runMigrate(cwd: string, options: MigrateOptions = {}): Pro
         console.log(`${prefix}Would restore: backup/${userFile} → .squad/${userFile}`);
       }
     }
+
+    // Step 4b: Restore or initialize casting state.
+    // casting/ is SQUAD_OWNED so sdkInitSquad() gets a clean slate, but the SDK does
+    // not create registry.json — that's the Coordinator's job during Init Mode.
+    // Handle two cases:
+    //   A: backup had casting state (v0.8.x repo) → restore it (preserves names/universe)
+    //   B: backup had no casting state (v0.5.x repo) → create legacy registry from agents/
+    const castingDir = path.join(cwd, '.squad', 'casting');
+    const registryPath = path.join(castingDir, 'registry.json');
+    const backupCastingRegistry = path.join(backupRoot, 'casting', 'registry.json');
+
+    if (!dryRun) {
+      if (fs.existsSync(backupCastingRegistry)) {
+        // Case A: restore casting state from backup
+        copyRecursive(path.join(backupRoot, 'casting'), castingDir);
+        console.log('           restored: .squad/casting (from backup)');
+      } else if (!fs.existsSync(registryPath)) {
+        // Case B: legacy repo — create casting state from restored agents/
+        const agentsDir = path.join(cwd, '.squad', 'agents');
+        const registryAgents: Record<string, object> = {};
+        const now = new Date().toISOString();
+
+        if (fs.existsSync(agentsDir)) {
+          for (const entry of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+              const agentKey = entry.name.toLowerCase();
+              registryAgents[agentKey] = {
+                created_at: now,
+                persistent_name: entry.name.charAt(0).toUpperCase() + entry.name.slice(1),
+                universe: 'legacy',
+                legacy_named: true,
+                status: 'active',
+              };
+            }
+          }
+        }
+
+        fs.mkdirSync(castingDir, { recursive: true });
+        fs.writeFileSync(registryPath, JSON.stringify({ agents: registryAgents }, null, 2) + '\n');
+
+        const policyPath = path.join(castingDir, 'policy.json');
+        if (!fs.existsSync(policyPath)) {
+          const defaultPolicy = {
+            casting_policy_version: '1.1',
+            allowlist_universes: [
+              'The Usual Suspects', 'Reservoir Dogs', 'Alien', "Ocean's Eleven",
+              'Arrested Development', 'Star Wars', 'The Matrix', 'Firefly',
+              'The Goonies', 'The Simpsons', 'Breaking Bad', 'Lost',
+              'Marvel Cinematic Universe', 'DC Universe',
+            ],
+            universe_capacity: {
+              'The Usual Suspects': 6, 'Reservoir Dogs': 8, 'Alien': 8,
+              "Ocean's Eleven": 14, 'Arrested Development': 15, 'Star Wars': 12,
+              'The Matrix': 10, 'Firefly': 10, 'The Goonies': 8,
+              'The Simpsons': 20, 'Breaking Bad': 12, 'Lost': 18,
+              'Marvel Cinematic Universe': 25, 'DC Universe': 18,
+            },
+          };
+          fs.writeFileSync(policyPath, JSON.stringify(defaultPolicy, null, 2) + '\n');
+        }
+
+        const historyPath = path.join(castingDir, 'history.json');
+        if (!fs.existsSync(historyPath)) {
+          const emptyHistory = { assignment_cast_snapshots: {}, universe_usage_history: [] };
+          fs.writeFileSync(historyPath, JSON.stringify(emptyHistory, null, 2) + '\n');
+        }
+
+        const agentCount = Object.keys(registryAgents).length;
+        success(`Initialized casting state (${agentCount} legacy agent${agentCount === 1 ? '' : 's'} registered).`);
+      }
+    } else {
+      if (fs.existsSync(backupCastingRegistry)) {
+        console.log(`${prefix}Would restore: backup/casting/ → .squad/casting/`);
+      } else {
+        console.log(`${prefix}Would create: .squad/casting/registry.json (legacy agents)`);
+        console.log(`${prefix}Would create: .squad/casting/policy.json (defaults)`);
+        console.log(`${prefix}Would create: .squad/casting/history.json (empty)`);
+      }
+    }
   } catch (err) {
     console.log();
     console.error(`Migration failed: ${err instanceof Error ? err.message : String(err)}`);
diff --git a/test/migrate-command.test.ts b/test/migrate-command.test.ts
index 07805a71c..bd78bf927 100644
--- a/test/migrate-command.test.ts
+++ b/test/migrate-command.test.ts
@@ -347,4 +347,79 @@ describe('Squad Migrate Command', () => {
       ).rejects.toThrow('process.exit: 1');
     });
   });
+
+  describe('runMigrate - casting state initialization', () => {
+    it('should create legacy casting registry when backup has no casting state (v0.5.x repo)', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(join(squadDir, 'agents', 'alice'), { recursive: true });
+      mkdirSync(join(squadDir, 'agents', 'bob'), { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '## Members\n- alice\n- bob\n');
+
+      await runMigrate(testDir, {});
+
+      const registryPath = join(squadDir, 'casting', 'registry.json');
+      expect(existsSync(registryPath)).toBe(true);
+
+      const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+      expect(registry.agents).toBeDefined();
+      expect(registry.agents['alice']).toMatchObject({ legacy_named: true, universe: 'legacy', status: 'active' });
+      expect(registry.agents['bob']).toMatchObject({ legacy_named: true, universe: 'legacy', status: 'active' });
+    });
+
+    it('should create policy.json and history.json alongside registry.json', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(join(squadDir, 'agents', 'charlie'), { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '## Members\n- charlie\n');
+
+      await runMigrate(testDir, {});
+
+      const castingDir = join(squadDir, 'casting');
+      expect(existsSync(join(castingDir, 'policy.json'))).toBe(true);
+      expect(existsSync(join(castingDir, 'history.json'))).toBe(true);
+
+      const policy = JSON.parse(readFileSync(join(castingDir, 'policy.json'), 'utf8'));
+      expect(policy.casting_policy_version).toBe('1.1');
+      expect(Array.isArray(policy.allowlist_universes)).toBe(true);
+
+      const history = JSON.parse(readFileSync(join(castingDir, 'history.json'), 'utf8'));
+      expect(history.assignment_cast_snapshots).toBeDefined();
+    });
+
+    it('should restore casting from backup when backup has casting state (v0.8.x repo)', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(join(squadDir, 'casting'), { recursive: true });
+      const existingRegistry = {
+        agents: {
+          dave: { created_at: '2026-01-01T00:00:00Z', persistent_name: 'Dave', universe: 'Reservoir Dogs', legacy_named: false, status: 'active' },
+        },
+      };
+      writeFileSync(join(squadDir, 'casting', 'registry.json'), JSON.stringify(existingRegistry, null, 2));
+      writeFileSync(join(squadDir, 'team.md'), '## Members\n- dave\n');
+
+      await runMigrate(testDir, {});
+
+      const registryPath = join(squadDir, 'casting', 'registry.json');
+      expect(existsSync(registryPath)).toBe(true);
+
+      const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+      // Original casting state preserved, not replaced with legacy
+      expect(registry.agents['dave']).toMatchObject({ universe: 'Reservoir Dogs', legacy_named: false });
+    });
+
+    it('should not overwrite existing casting state when sdkInitSquad already created it', async () => {
+      const squadDir = join(testDir, '.squad');
+      mkdirSync(squadDir, { recursive: true });
+      writeFileSync(join(squadDir, 'team.md'), '## Members\n');
+
+      // Pre-populate what the mock sdkInitSquad would create (empty casting dir, no registry)
+      // In this test the mock doesn't write registry.json, so we verify our code creates it
+      await runMigrate(testDir, {});
+
+      // After migration with no agents, registry should exist but be empty
+      const registryPath = join(squadDir, 'casting', 'registry.json');
+      expect(existsSync(registryPath)).toBe(true);
+      const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+      expect(registry.agents).toEqual({});
+    });
+  });
 });

From 4f9a5f918d65fc35c4477764fd3c7f22998af2e7 Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 14:55:14 +1000
Subject: [PATCH 09/12] fix(migrate): address pre-PR review blockers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Security: constrain --restore and --backup-dir paths to cwd (Baer)
- Security: prevent path traversal in copyRecursive restore targets
- Correctness: track backupComplete flag; gate rollback on verified backup (Fenster)
- Feature: add config.json to USER_OWNED so user config survives migration (Keaton)
- UX: replace sdkInitSquad internal name in --dry-run output (Marquez)
- UX: style rollback/error path with error()/warn()/info() helpers (Marquez)
- UX: add success() completion markers to Steps 2 and 4 (Marquez)
- Docs: add v0.8.21 section to whatsnew.md (McManus)
- Docs: fix cli.md install section — replace 'squad init' with correct insider install command (McManus)
---
 docs/reference/cli.md                      |  4 +-
 docs/whatsnew.md                           | 11 +++-
 packages/squad-cli/src/cli/core/migrate.ts | 63 +++++++++++++++-------
 3 files changed, 57 insertions(+), 21 deletions(-)

diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 6385a5810..5e335ad4e 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -16,8 +16,8 @@ npm install -g @bradygaster/squad-cli
 # One-off with npx
 npx @bradygaster/squad-cli init
 
-# Latest from GitHub (bleeding edge)
-squad init
+# Insider builds (bleeding edge)
+npm install -g @bradygaster/squad-cli@insider
 ```
 
 ---
diff --git a/docs/whatsnew.md b/docs/whatsnew.md
index 11712d39d..ae5cb2bfb 100644
--- a/docs/whatsnew.md
+++ b/docs/whatsnew.md
@@ -7,7 +7,16 @@ Full release history for Squad — from beta through the v1 TypeScript replatfor
 
 ---
 
-## v0.8.2 — Current Release
+## v0.8.21 — Current Release
+
+- **`squad migrate` command** — New automated migration command that backs up, cleans, and reinitialises `.squad/` in one step. Supports `--dry-run`, `--backup-dir`, and `--restore [path]` flags. Auto-rollback on failure.
+- **Shell re-init fix** — After `squad migrate`, the interactive shell no longer incorrectly treats a migrated install as brand-new (deletes stale `.first-run` / `.init-prompt` markers post-reinit).
+- **Casting registry fix** — `squad migrate` now restores or synthesises `casting/registry.json` after reinit. Handles both v0.8.x repos (restore from backup) and v0.5.x repos (generate from restored `agents/` directory).
+- **Cast overwrite guard** — `createTeam()` no longer overwrites existing `charter.md` or non-empty `history.md` when re-casting after a migration.
+
+---
+
+## v0.8.2
 
 - **Version alignment** — CLI (0.8.1) and SDK (0.8.0) snapped to 0.8.2 across all packages
 - **Published to npm** — `@bradygaster/squad-sdk@0.8.2` and `@bradygaster/squad-cli@0.8.2`
diff --git a/packages/squad-cli/src/cli/core/migrate.ts b/packages/squad-cli/src/cli/core/migrate.ts
index 20a4789a8..126085b15 100644
--- a/packages/squad-cli/src/cli/core/migrate.ts
+++ b/packages/squad-cli/src/cli/core/migrate.ts
@@ -7,7 +7,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { initSquad as sdkInitSquad } from '@bradygaster/squad-sdk';
-import { success, warn, info, DIM, BOLD, RESET } from './output.js';
+import { success, error, warn, info, DIM, BOLD, RESET } from './output.js';
 import { getPackageVersion } from './version.js';
 
 export interface MigrateOptions {
@@ -32,6 +32,7 @@ const SQUAD_OWNED = [
 /** Files and directories that belong to the user — restored from backup after reinit. */
 const USER_OWNED = [
   'agents',
+  'config.json',
   'decisions.md',
   'decisions',
   'routing.md',
@@ -68,21 +69,27 @@ async function runRestore(cwd: string, backupPath?: string): Promise<void> {
   console.log();
 
   const squadDir = path.join(cwd, '.squad');
+  const cwdResolved = path.resolve(cwd);
 
   // Resolve which backup to use
   let resolvedBackup: string | undefined;
   if (backupPath) {
     resolvedBackup = path.resolve(cwd, backupPath);
+    if (!resolvedBackup.startsWith(cwdResolved + path.sep)) {
+      error(`--restore path must be within the current directory.`);
+      info(`  Resolved: ${resolvedBackup}`);
+      info(`  Expected: inside ${cwdResolved}/`);
+      process.exit(1);
+    }
   } else {
     resolvedBackup = findLatestBackup(cwd);
   }
 
   if (!resolvedBackup || !fs.existsSync(resolvedBackup)) {
     const tried = backupPath ? path.resolve(cwd, backupPath) : '.squad-backup-*/';
-    console.error(`Error: No backup found at ${tried}`);
-    console.error('');
-    console.error('List available backups with:');
-    console.error('  ls -d .squad-backup-*/');
+    error(`No backup found at ${tried}`);
+    info('List available backups with:');
+    info('  ls -d .squad-backup-*/');
     process.exit(1);
   }
 
@@ -164,10 +171,21 @@ export async function runMigrate(cwd: string, options: MigrateOptions = {}): Pro
 
   // Step 1: Back up
   const timestamp = formatTimestamp();
-  const backupRoot = options.backupDir
-    ? path.resolve(cwd, options.backupDir)
-    : path.join(cwd, `.squad-backup-${timestamp}`);
+  const cwdResolved = path.resolve(cwd);
+  let backupRoot: string;
+  if (options.backupDir) {
+    backupRoot = path.resolve(cwd, options.backupDir);
+    if (!backupRoot.startsWith(cwdResolved + path.sep)) {
+      error(`--backup-dir path must be within the current directory.`);
+      info(`  Resolved: ${backupRoot}`);
+      info(`  Expected: inside ${cwdResolved}/`);
+      process.exit(1);
+    }
+  } else {
+    backupRoot = path.join(cwd, `.squad-backup-${timestamp}`);
+  }
 
+  let backupComplete = false;
   console.log(`  Step 1/4  Backup`);
   console.log(`           ${squadDir}`);
   console.log(`        →  ${backupRoot}`);
@@ -179,6 +197,7 @@ export async function runMigrate(cwd: string, options: MigrateOptions = {}): Pro
       process.exit(1);
     }
     copyRecursive(squadDir, backupRoot);
+    backupComplete = true;
     success(`Backed up to ${path.relative(cwd, backupRoot)}/`);
   } else {
     console.log(`${prefix}Would copy ${path.relative(cwd, squadDir)}/ → ${path.relative(cwd, backupRoot)}/`);
@@ -222,6 +241,10 @@ export async function runMigrate(cwd: string, options: MigrateOptions = {}): Pro
       }
     }
 
+    if (!dryRun) {
+      success('Removed Squad-owned files.');
+    }
+
     // Step 3: Reinitialize
     console.log();
     console.log(`  Step 3/4  Reinitialize .squad/`);
@@ -250,7 +273,7 @@ export async function runMigrate(cwd: string, options: MigrateOptions = {}): Pro
         }
       }
     } else {
-      console.log(`${prefix}Would run: sdkInitSquad (fresh scaffold)`);
+      console.log(`${prefix}Would reinitialize .squad/ (fresh scaffold)`);
       console.log(`${prefix}Would remove: .squad/.first-run (if present)`);
       console.log(`${prefix}Would remove: .squad/.init-prompt (if present)`);
     }
@@ -274,6 +297,10 @@ export async function runMigrate(cwd: string, options: MigrateOptions = {}): Pro
       }
     }
 
+    if (!dryRun) {
+      success('User files restored.');
+    }
+
     // Step 4b: Restore or initialize casting state.
     // casting/ is SQUAD_OWNED so sdkInitSquad() gets a clean slate, but the SDK does
     // not create registry.json — that's the Coordinator's job during Init Mode.
@@ -354,17 +381,17 @@ export async function runMigrate(cwd: string, options: MigrateOptions = {}): Pro
     }
   } catch (err) {
     console.log();
-    console.error(`Migration failed: ${err instanceof Error ? err.message : String(err)}`);
-    if (!dryRun && fs.existsSync(backupRoot)) {
-      console.error('');
-      console.error('Rolling back from backup...');
+    error(`Migration failed: ${err instanceof Error ? err.message : String(err)}`);
+    if (!dryRun && backupComplete && fs.existsSync(backupRoot)) {
+      console.log();
+      warn('Rolling back from backup...');
       removeRecursive(path.join(cwd, '.squad'));
       copyRecursive(backupRoot, path.join(cwd, '.squad'));
-      console.error(`Restored .squad/ from ${path.relative(cwd, backupRoot)}/`);
-      console.error('');
-      console.error(`Your backup is still at: ${path.relative(cwd, backupRoot)}/`);
-      console.error('You can retry the migration or restore manually with:');
-      console.error(`  squad migrate --restore ${path.relative(cwd, backupRoot)}`);
+      success(`Restored .squad/ from ${path.relative(cwd, backupRoot)}/`);
+      console.log();
+      info(`Your backup is still at: ${path.relative(cwd, backupRoot)}/`);
+      console.log('You can retry the migration or restore manually with:');
+      console.log(`  squad migrate --restore ${path.relative(cwd, backupRoot)}`);
     }
     process.exit(1);
   }

From 0e08594d24487fa00bd8d560833bad592b175701 Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 16:45:14 +1000
Subject: [PATCH 10/12] fix(cli): restore NODE_NO_WARNINGS, bare semver,
 whitespace-arg UX, doctor hint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add process.env.NODE_NO_WARNINGS='1' before first import (re-adds line
  from ceb599b that was dropped in subsequent cli-entry.ts restructure)
- --version / -v now outputs bare semver without 'squad ' prefix
- Empty/whitespace-only args now show help and exit 0 (was: exit 1 + unknown command)
- Unknown command error now mentions 'squad doctor' as remediation hint

Fixes test/cli-p0-regressions.test.ts (all 6 assertions now pass) and
test/first-run-gating.test.ts #624 NODE_NO_WARNINGS assertion.

The banner spacer test (first-run-gating.test.ts:658) remains failing —
pre-existing App.tsx regex mismatch on upstream/dev, not in scope for this PR.
---
 packages/squad-cli/src/cli-entry.ts | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts
index a6d91550d..34d320335 100644
--- a/packages/squad-cli/src/cli-entry.ts
+++ b/packages/squad-cli/src/cli-entry.ts
@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+process.env.NODE_NO_WARNINGS = '1';
 
 /**
  * Squad CLI — entry point for command-line invocation.
@@ -20,13 +21,13 @@ import { runShell } from './cli/shell/index.js';
 import { VERSION } from '@bradygaster/squad-sdk';
 
 async function main(): Promise<void> {
-  const args = process.argv.slice(2);
+  const args = process.argv.slice(2).filter((a) => a.trim() !== '');
   const hasGlobal = args.includes('--global');
-  const cmd = args[0];
+  const cmd = args[0] ?? '--help';
 
   // --version / -v
   if (cmd === '--version' || cmd === '-v') {
-    console.log(`squad ${VERSION}`);
+    console.log(VERSION);
     return;
   }
 
@@ -285,7 +286,7 @@ async function main(): Promise<void> {
   }
 
   // Unknown command
-  fatal(`Unknown command: ${cmd}\n       Run 'squad help' for usage information.`);
+  fatal(`Unknown command: ${cmd}\n       Run 'squad doctor' to check your setup, or 'squad help' for usage information.`);
 }
 
 main().catch(err => {

From 80180c22d266e9016fbc8e9b4d8de7ea554d5e2f Mon Sep 17 00:00:00 2001
From: William Hallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 19:27:56 +1000
Subject: [PATCH 11/12] delete/ randomly created .squad/config.json

---
 .squad/config.json | 4 ----
 1 file changed, 4 deletions(-)
 delete mode 100644 .squad/config.json

diff --git a/.squad/config.json b/.squad/config.json
deleted file mode 100644
index a1f09ba0a..000000000
--- a/.squad/config.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-  "version": 1,
-  "teamRoot": "/home/williamh/code/squad"
-}
\ No newline at end of file

From 52778bc2042d8dedba989883b482e8ccd404e563 Mon Sep 17 00:00:00 2001
From: williamhallatt <williamhallatt+github@proton.me>
Date: Thu, 5 Mar 2026 21:11:02 +1000
Subject: [PATCH 12/12] chore: clean session metadata from history files;
 gitignore .squad/config.json

Remove requester attribution and branch name from breedan and hockney
history entries. Add .squad/config.json to .gitignore (machine-local
teamRoot path, must not be committed). See #202 for follow-up.
---
 .gitignore                       | 1 +
 .squad/agents/breedan/history.md | 2 --
 .squad/agents/hockney/history.md | 2 +-
 3 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index 862a7cfa5..0856ac704 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,7 @@ coverage/
 # Squad: ignore generated logs
 .squad/orchestration-log/
 .squad/log/
+.squad/config.json
 .test-cli-*
 # Docs site generated files
 docs/dist/
diff --git a/.squad/agents/breedan/history.md b/.squad/agents/breedan/history.md
index c9e97f18a..5bf1200f1 100644
--- a/.squad/agents/breedan/history.md
+++ b/.squad/agents/breedan/history.md
@@ -175,8 +175,6 @@ What a real user would encounter that no test catches:
 
 ### Squad Migrate E2E Tests — 2025-03-05
 
-**Requested by:** William Hallatt — test coverage for `squad migrate` command and shell reinit guard bug fix from branch `williamhallatt/197-migration-experience`.
-
 **Context:** The migrate command was added to safely upgrade .squad/ directories (backup → clean → reinit → restore). A critical bug where re-launching shell after migrate would trigger re-initialization (overwriting agent files) was fixed by cleaning up `.first-run` and `.init-prompt` markers after migration.
 
 **Tests created:** `test/migrate-e2e.test.ts` — 23 tests, all passing.
diff --git a/.squad/agents/hockney/history.md b/.squad/agents/hockney/history.md
index d0a6d57b3..06be3ee40 100644
--- a/.squad/agents/hockney/history.md
+++ b/.squad/agents/hockney/history.md
@@ -804,7 +804,7 @@ All labeled squad:hockney for routing. Each issue includes: what's missing, why
 - **Pre-existing failure:** Line 94 gitattributes content mismatch (unrelated, not introduced by this change).
 - **Lesson:** On Windows, use `join(root, '.squad', 'templates')` not `join(root, '.squad/templates')` — forward-slash segments in `join` args work on Node but it's better practice to use separate args.
 
-### Migration command test coverage — branch williamhallatt/197-migration-experience (2026-03-05)
+### Migration command test coverage (2026-03-05)
 **Status:** Complete — 30 tests added, all pass.
 - **Files created:**
   - `test/migrate-command.test.ts` (19 tests for `runMigrate`)