From 1d7539252fc8304cf8502babef63c5e89a312e86 Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Sat, 21 Mar 2026 12:39:14 -0700
Subject: [PATCH] docs: expand CLI README and docs site reference

- README: expanded from 77 to 236 lines (3.1x)
  - Added installation, quick start, command reference tables
  - Added .squad/ directory structure guide
  - Added configuration and troubleshooting sections
  - Applied Microsoft Writing Style Guide

- docs/reference/cli.md: expanded from 354 to 608 lines
  - Command coverage: 16 to 40+ commands documented
  - Added 6 common workflow sequences
  - Organized into 9 logical sections
  - Added dual-root mode explanation
  - markdownlint passes clean

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/src/content/docs/reference/cli.md | 523 ++++++++++++++++++-------
 packages/squad-cli/README.md           | 316 +++++++++++++--
 2 files changed, 673 insertions(+), 166 deletions(-)

diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md
index 73c6529da..724446258 100644
--- a/docs/src/content/docs/reference/cli.md
+++ b/docs/src/content/docs/reference/cli.md
@@ -22,74 +22,304 @@ squad init
 
 ---
 
-## CLI Commands (16 commands)
+## CLI Commands (40+ commands)
+
+### Essential Commands
 
 | Command | Description | Requires `.squad/` |
 |---------|-------------|:------------------:|
-| `squad` | Enter interactive shell (no args) | No |
+| `squad` | Enter interactive shell (no args) — routes work to agents | No |
 | `squad init` | Initialize Squad in the current repo (idempotent — safe to run multiple times) | No |
-| `squad init --global` | Create a personal squad in your platform-specific directory | No |
-| `squad init --sdk` | Generate typed `squad.config.ts` with `useRole()` calls | No |
-| `squad init --roles` | Include base role catalog (Lead, Backend, etc.) instead of universe casting | No |
-| `squad init --mode remote <path>` | Initialize linked to a remote team root (dual-root mode) | No |
-| `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 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 |
-| `squad triage` | Auto-triage issues and assign to team (primary name; `watch` is an alias) | Yes |
-| `squad triage --interval <min>` | Continuous triage (default: every 10 min) | Yes |
-| `squad copilot` | Add the @copilot coding agent to the team | Yes |
-| `squad copilot --off` | Remove @copilot from the team | Yes |
-| `squad copilot --auto-assign` | Enable auto-assignment for @copilot | Yes |
-| `squad plugin marketplace add\|remove\|list\|browse` | Manage plugin marketplaces | Yes |
-| `squad export` | Export squad to a portable JSON snapshot | Yes |
-| `squad export --out <path>` | Export to a custom path | Yes |
-| `squad import <file>` | Import a squad from an export file | No |
-| `squad import <file> --force` | Replace existing squad (archives the old one) | No |
-| `squad aspire` | Launch Aspire dashboard for observability | No |
-| `squad aspire --docker` | Force Docker mode for Aspire | No |
-| `squad upstream add\|remove\|list\|sync` | Manage upstream Squad sources | Yes |
-| `copilot --agent squad` | Launch interactive shell explicitly | No |
-| `squad nap` | Context hygiene (compress, prune, archive .squad/ state) | Yes |
-| `squad nap --deep` | Thorough cleanup with recursive descent | Yes |
-| `squad nap --dry-run` | Preview cleanup actions without changes | Yes |
-| `squad scrub-emails [directory]` | Remove email addresses from Squad state files (default: `.squad/`) | No |
-| `squad --version` | Print installed version | No |
-
-### Remote Init Mode
-
-Use `--mode remote` to link your project to a shared team root:
+| `squad status` | Show which squad is active and why | No |
+| `squad doctor` | Validate squad setup integrity and diagnose issues | Yes |
+
+### Setup & Configuration
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `squad init --global` | Create a personal squad in your platform-specific directory | `squad init --global` |
+| `squad init --sdk` | Generate typed `squad.config.ts` with `useRole()` calls | `squad init --sdk` |
+| `squad init --roles` | Include base role catalog (Lead, Backend, etc.) instead of universe casting | `squad init --roles` |
+| `squad init --mode remote <path>` | Initialize linked to a remote team root (dual-root mode) | `squad init --mode remote ../team-repo` |
+| `squad build` | Compile `squad.config.ts` into `.squad/` markdown files | `squad build` |
+| `squad build --check` | Validate TypeScript definitions without writing changes | `squad build --check` |
+| `squad build --dry-run` | Preview generated files without writing | `squad build --dry-run` |
+| `squad link <team-repo-path>` | Link project to a remote team root | `squad link ../team-repo` |
+| `squad init-remote <path>` | Shorthand for `init --mode remote` | `squad init-remote ../team-repo` |
+
+### Team & Roles
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `squad roles` | List all available Squad roles | `squad roles` |
+| `squad roles --category <name>` | Filter roles by category | `squad roles --category engineering` |
+| `squad roles --search <query>` | Search for roles by name or description | `squad roles --search "backend"` |
+| `squad hire` | Team creation wizard (interactive) | `squad hire` |
+| `squad hire --name <name> --role <role>` | Create agent with name and role | `squad hire --name Maya --role backend` |
+| `squad copilot` | Add the @copilot coding agent to the team | `squad copilot` |
+| `squad copilot --off` | Remove @copilot from the team | `squad copilot --off` |
+| `squad copilot --auto-assign` | Enable auto-assignment for @copilot | `squad copilot --auto-assign` |
+
+### Work & Triage
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `squad triage` | Auto-triage issues and assign to team | `squad triage` |
+| `squad triage --interval <min>` | Continuous triage with custom interval (default: 10 min) | `squad triage --interval 5` |
+| `squad watch` | Alias for `triage` — continuous monitoring | `squad watch` |
+| `squad loop` | Work loop with optional filtering | `squad loop --filter "type:bug"` |
+
+### Import & Export
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `squad export` | Export squad to a portable JSON snapshot | `squad export` |
+| `squad export --out <path>` | Export to a custom path | `squad export --out /tmp/my-squad.json` |
+| `squad import <file>` | Import a squad from an export file | `squad import squad-export.json` |
+| `squad import <file> --force` | Replace existing squad (archives the old one) | `squad import squad-export.json --force` |
+
+### Maintenance & Health
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `squad upgrade` | Upgrade Squad-owned files to latest version | `squad upgrade` |
+| `squad upgrade --migrate-directory` | Rename legacy `.ai-team/` to `.squad/` | `squad upgrade --migrate-directory` |
+| `squad migrate` | Convert between markdown-only and SDK-First formats | `squad migrate --to sdk` |
+| `squad migrate --to <sdk\|markdown>` | Specify target format | `squad migrate --to markdown` |
+| `squad nap` | Context hygiene (compress, prune, archive .squad/ state) | `squad nap` |
+| `squad nap --deep` | Thorough cleanup with recursive descent | `squad nap --deep` |
+| `squad nap --dry-run` | Preview cleanup actions without changes | `squad nap --dry-run` |
+| `squad scrub-emails [directory]` | Remove email addresses from Squad state files | `squad scrub-emails .squad/` |
+
+### Remote Control & Observability
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `squad start` | Start Copilot with optional remote access from phone/browser | `squad start` |
+| `squad start --tunnel` | Enable phone/browser access via devtunnel (shows QR code) | `squad start --tunnel` |
+| `squad start --port <n>` | Specific WebSocket port (default: random) | `squad start --port 3456` |
+| `squad start --command <cmd>` | Run a custom command instead of copilot | `squad start --command powershell` |
+| `squad rc` | Start Remote Control bridge (alias: `remote-control`) | `squad rc --tunnel` |
+| `squad rc --tunnel` | Enable devtunnel for remote access | `squad rc --tunnel` |
+| `squad rc --port <n>` | Custom WebSocket port for RC bridge | `squad rc --port 3456` |
+| `squad rc --path <dir>` | Specify source directory for RC bridge | `squad rc --path ./src` |
+| `squad copilot-bridge` | Check Copilot ACP stdio compatibility | `squad copilot-bridge` |
+| `squad rc-tunnel` | Check devtunnel CLI availability | `squad rc-tunnel` |
+| `squad aspire` | Launch .NET Aspire dashboard for observability | `squad aspire` |
+| `squad aspire --docker` | Force Docker mode for Aspire | `squad aspire --docker` |
+| `squad aspire --port <n>` | Custom Aspire dashboard port | `squad aspire --port 18888` |
+
+### Collaboration & Extensions
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `squad plugin marketplace add \| remove \| list \| browse` | Manage plugin marketplaces | `squad plugin marketplace list` |
+| `squad upstream add <source>` | Add upstream Squad source | `squad upstream add github.com/my/upstream` |
+| `squad upstream add <source> --name <n>` | Add with custom name | `squad upstream add github.com/my/upstream --name primary` |
+| `squad upstream add <source> --ref <branch>` | Pin to specific branch | `squad upstream add github.com/my/upstream --ref main` |
+| `squad upstream remove <name>` | Remove upstream source | `squad upstream remove primary` |
+| `squad upstream list` | Show configured upstreams | `squad upstream list` |
+| `squad upstream sync [name]` | Sync from upstream(s) | `squad upstream sync` |
+| `squad discover` | List known squads and their capabilities | `squad discover` |
+| `squad delegate <squad-name> <description>` | Create work in another squad | `squad delegate analytics "Add usage dashboard"` |
+
+### Advanced & Scheduling
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `squad schedule list` | Show configured schedules | `squad schedule list` |
+| `squad schedule run <id>` | Manually trigger a scheduled task | `squad schedule run daily-backup` |
+| `squad schedule init` | Create a default `schedule.json` template | `squad schedule init` |
+| `squad schedule status` | Show last run times and next due dates | `squad schedule status` |
+| `squad subsquads list` | Show configured SubSquads | `squad subsquads list` |
+| `squad subsquads status` | Show activity per SubSquad | `squad subsquads status` |
+| `squad subsquads activate <name>` | Activate a SubSquad for work | `squad subsquads activate backend-team` |
+| `squad cost` | Report token usage from orchestration logs | `squad cost` |
+| `squad cost --all` | Show costs for all agents | `squad cost --all` |
+| `squad cost --agent <name>` | Filter by specific agent | `squad cost --agent Maya` |
+| `squad consult` | Enter consult mode with your personal squad | `squad consult` |
+| `squad consult --status` | Show current consult mode status | `squad consult --status` |
+| `squad extract` | Extract learnings from consult mode session | `squad extract` |
+
+### Meta
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `squad --version` | Print installed version | `squad --version` |
+| `squad help` | Show help message with all commands | `squad help` |
+
+## Common Workflows
+
+### Getting Started
+
+Start a new Squad from scratch:
+
+```bash
+# 1. Initialize Squad in your repo (creates .squad/ directory)
+squad init
+
+# 2. Optional: customize with SDK-first approach
+squad init --sdk
+
+# 3. Launch interactive shell to assign work
+squad
+```
+
+After initialization, run `squad` with no arguments to enter the interactive shell where you can route work to agents.
+
+### Working with Issues
+
+Automate issue triage and assignment:
+
+```bash
+# 1. Start interactive shell
+squad
+
+# 2. From the shell, connect to your GitHub repo:
+squad > /connect my-org/my-repo
+
+# 3. Pick up assigned issues:
+squad > Show me issues assigned to @Neo
+
+# Continuous background triage (runs every 10 minutes by default):
+squad triage
+
+# Check triage results in the shell:
+squad > /status
+```
+
+### Health Check
+
+Validate your Squad setup before and after configuration changes:
+
+```bash
+# Quick diagnostic check
+squad doctor
+
+# After upgrading Squad
+squad upgrade && squad doctor
+
+# After cloning a repo with Squad
+git clone my-project && cd my-project && squad doctor
+```
+
+### Team Building
+
+Add agents to your team interactively:
+
+```bash
+# Interactive wizard
+squad hire
+
+# Or with flags for automation
+squad hire --name Maya --role backend
+
+# View available roles
+squad roles --category engineering
+```
+
+### Remote Collaboration
+
+Enable phone/browser access for remote pair programming:
+
+```bash
+# Start Copilot with local PTY only
+squad start
+
+# Enable remote access with devtunnel (shows QR code for phone scanning)
+squad start --tunnel
+
+# Custom port for local-only access
+squad start --port 3456
+
+# Custom command + remote access
+squad start --tunnel --command powershell
+```
+
+For details, see [Remote Control Guide](../features/remote-control.md).
+
+### Observability
+
+Monitor Squad operations:
+
+```bash
+# View token usage costs by agent
+squad cost --all
+
+# Filter costs for a specific agent
+squad cost --agent Maya
+
+# Launch .NET Aspire dashboard for tracing
+squad aspire
+```
+
+### Maintenance
+
+Keep your Squad configuration clean and up to date:
+
+```bash
+# Upgrade Squad framework files (never touches your team state)
+squad upgrade
+
+# Preview context cleanup without making changes
+squad nap --dry-run
+
+# Perform deep cleanup
+squad nap --deep
+
+# Export your team configuration
+squad export --out my-squad-backup.json
+
+# Migrate from old .ai-team/ format
+squad upgrade --migrate-directory
+```
+
+---
+
+## Dual-Root Mode (Remote Team Root)
+
+You can link your project to a shared team root to support multiple projects with a single team definition.
+
+**Initialize with dual-root mode:**
 
 ```bash
 squad init --mode remote ../team-repo
 ```
 
-In dual-root mode, project-specific state lives in your local `.squad/` while team identity (casting, charters, shared decisions) lives in the remote location. This is useful for monorepos or organizations with a shared team definition.
+**Or link an existing project:**
+
+```bash
+squad link ../team-repo
+```
+
+In dual-root mode:
+- **Project-specific state** lives in your local `.squad/` (decisions, learnings, project-specific files)
+- **Team identity** (casting, charters, shared decisions) lives in the remote location
+- Both locations are needed for the squad to function
+
+This is useful for **monorepos** where multiple projects share a single team definition, or **organizations** with a shared team structure.
 
 ---
 
-### squad start
+### squad start — Remote Control
 
-Start Copilot with optional remote access via phone. Spawns Copilot in a PTY and mirrors to your phone via WebSocket + devtunnel.
+Start Copilot with optional phone/browser access. Spawns Copilot in a PTY and mirrors to your device via WebSocket.
 
 **Flags:**
 
-- `--tunnel` — Create a devtunnel for remote access (shows QR code for phone scanning). Requires `devtunnel` CLI installed and authenticated (`devtunnel user login`).
+- `--tunnel` — Create a devtunnel for remote access (shows QR code). Requires `devtunnel` CLI installed (`devtunnel user login`).
 - `--port <N>` — Specific WebSocket port (default: random). Example: `--port 3456`
-- `--command <cmd>` — Run a custom command instead of copilot. Example: `--command powershell`
-- All copilot flags pass through. Example: `squad start --tunnel --yolo` or `squad start --tunnel --model gpt-4`
+- `--command <cmd>` — Run custom command instead of copilot. Example: `--command powershell`
+- All Copilot flags pass through. Example: `--model gpt-4`, `--yolo`
 
 **Examples:**
 
 ```bash
-# Basic local PTY (no phone access)
+# Local only (no remote access)
 squad start
 
-# With phone access + devtunnel
+# With phone access via devtunnel QR code
 squad start --tunnel
-# Output: QR Code, URL, Session ID
 
 # Custom port, local only
 squad start --port 3456
@@ -98,47 +328,51 @@ squad start --port 3456
 squad start --tunnel --command powershell
 
 # Copilot flags pass through
+squad start --tunnel --model gpt-4
 squad start --tunnel --yolo
-squad start --tunnel --model gpt-4 --no-config
 ```
 
-For details on architecture, security, mobile keyboard, and troubleshooting, see [Remote Control Guide](../features/remote-control.md).
+For architecture, security, keyboard shortcuts, and troubleshooting, see [Remote Control Guide](../features/remote-control.md).
 
 ---
 
 ## Interactive Shell
 
-Enter the shell with `squad` (no arguments). You'll see:
+Run `squad` with no arguments to enter the interactive shell. You'll see:
 
 ```
 squad >
 ```
 
+The interactive shell lets you assign work to agents, check status, and manage sessions — all without leaving the terminal.
+
 ### Shell Commands
 
 All shell commands start with `/`.
 
 | Command | What it does |
 |---------|-------------|
-| `/status` | Show active agents, sessions, recent decisions |
-| `/history` | View session log — tasks, decisions, agent work |
-| `/agents` | List team members with roles and expertise |
+| `/status` | Show active agents, sessions, and recent decisions |
+| `/history` | View session log with tasks, decisions, and agent work |
+| `/agents` | List team members with their roles and expertise |
 | `/sessions` | List saved sessions |
 | `/resume <id>` | Restore a past session |
-| `/version` | Show version |
+| `/version` | Show squad version |
 | `/clear` | Clear terminal output |
-| `/help` | Show all commands |
+| `/help` | Show all shell commands |
 | `/quit` | Exit the shell (also: `Ctrl+C`) |
 
 ### Addressing Agents
 
+Route work directly to agents by name, or let the coordinator decide:
+
 ```
-squad > @Keaton, analyze the architecture
-squad > Keaton, set up the database schema
-squad > Build a blog post about our casting system
+squad > @Maya, set up database schema
+squad > neo, review the API design
+squad > Build a blog post about our architecture
 ```
 
-Agent name matching is **case-insensitive** — `@keaton`, `@Keaton`, and `@KEATON` all route to the same agent. Name an agent to route directly. Omit the name and the coordinator routes to the best fit.
+Agent name matching is **case-insensitive**. Use `@name` or just the name. Omit the name and the coordinator routes to the best fit.
 
 ### Keyboard Shortcuts
 
@@ -156,39 +390,44 @@ Agent name matching is **case-insensitive** — `@keaton`, `@Keaton`, and `@KEAT
 
 ## Configuration Files
 
+Squad stores all team state in a `.squad/` directory in your project root. Everything is markdown, JSON, or TypeScript — no binary formats.
+
 ### `.squad/` Directory Structure
 
 ```
 .squad/
-├── team.md              # Roster — agent names, roles, human members
-├── routing.md           # Work routing rules
-├── decisions.md         # Architectural decisions log
-├── directives.md        # Permanent team rules and conventions
-├── casting-state.json   # Agent names, universe theme
-├── model-config.json    # Per-agent model overrides
-├── ceremonies.md        # Team ceremonies and rituals
-├── skills/              # Reusable knowledge (markdown files)
+├── team.md              # Team roster — agent names, roles, team members
+├── routing.md           # Work routing rules (which agent gets what)
+├── decisions.md         # Architectural decisions log (append-only)
+├── directives.md        # Permanent team conventions and rules
+├── casting-state.json   # Agent names and universe theme
+├── model-config.json    # Per-agent LLM model overrides
+├── ceremonies.md        # Team meetings, rituals, and review cycles
+├── skills/              # Reusable knowledge files (markdown)
 │   ├── auth-rate-limiting.md
 │   └── ...
 ├── agents/
-│   ├── neo/
-│   │   ├── charter.md   # Role definition, expertise, tools
-│   │   └── history.md   # Accumulated knowledge
+│   ├── maya/
+│   │   ├── charter.md   # Agent's role, expertise, and tools
+│   │   └── history.md   # Agent's accumulated knowledge
 │   └── ...
-└── history-archive/     # Archived old session logs
+├── config.json          # Squad configuration (optional; created by init)
+└── schedule.json        # Scheduled tasks (optional)
 ```
 
-### `team.md`
+Each file serves a specific purpose and is safe to edit manually. Squad respects your changes.
 
-Defines the roster. Squad generates this during init, but you can edit it:
+### team.md
+
+Defines who's on your team (agents and humans):
 
 ```markdown
 ## Team
 
 🏗️  Neo      — Lead          Scope, decisions, code review
 ⚛️  Trinity  — Frontend Dev  React, TypeScript, UI
-🔧  Morpheus — Backend Dev   Node.js, Express, Prisma
-🧪  Tank     — Tester        Jest, integration tests
+🔧  Morpheus — Backend Dev   Node.js, Express, database
+🧪  Tank     — Tester        Jest, integration testing
 📋  Scribe   — (silent)      Memory, decisions, session logs
 
 ## Human Team Members
@@ -197,9 +436,9 @@ Defines the roster. Squad generates this during init, but you can edit it:
 - **Jamal** — Frontend Lead
 ```
 
-### `routing.md`
+### routing.md
 
-Controls which agent gets which work:
+Controls which agent gets assigned which type of work:
 
 ```markdown
 # Routing Rules
@@ -209,12 +448,13 @@ Controls which agent gets which work:
 **Database migrations** → Morpheus
 **Test writing** → Tank
 **Architecture decisions** → Neo
-**Backend architecture decisions** → Sarah (human)
 ```
 
-### `decisions.md`
+Squad reads these rules before assigning tasks.
+
+### decisions.md
 
-Append-only log of architectural decisions. Agents read this before every task:
+An **append-only log** of important decisions. Agents read this before every task to understand the team's choices:
 
 ```markdown
 ### 2025-07-15: Use Zod for API validation
@@ -223,37 +463,50 @@ Append-only log of architectural decisions. Agents read this before every task:
 **Why:** Type-safe, composable, generates TypeScript types
 ```
 
-### `directives.md`
+Never delete or reorder entries — only append.
+
+### directives.md
 
-Permanent rules agents always follow:
+Permanent rules that all agents follow:
 
 ```markdown
 - Always use TypeScript strict mode
 - No any/unknown casts
-- All database queries through Prisma, no raw SQL
+- All database queries through Prisma
+- Write tests for all public APIs
 ```
 
 ---
 
-## Resolution Order
+## Squad Directory Resolution
 
-When Squad starts, it looks for `.squad/` in this order:
+When you run `squad`, it searches for `.squad/` in this order:
 
-1. Current directory (`./.squad/`)
-2. Parent directories (walk up to project root)
-3. Personal squad directory (platform-specific: `~/.config/squad/` on Linux, `~/Library/Application Support/squad/` on macOS, `%APPDATA%\squad\` on Windows)
-4. Global CLI default (fallback only)
+1. **Local project** — `./.squad/` (current directory and parent directories)
+2. **Personal squad** — Platform-specific location:
+   - **Linux:** `~/.config/squad/`
+   - **macOS:** `~/Library/Application Support/squad/`
+   - **Windows:** `%APPDATA%\squad\`
+3. **Global fallback** — CLI default (only if no others found)
 
-First match wins.
+**First match wins.** This means:
+- If your project has `.squad/`, that's used
+- Otherwise, your personal squad is used
+- No personal squad? Squad creates a temporary default
+
+You can override this with flags:
+- `--global` — Force use of personal squad directory
+- `squad init --mode remote <path>` — Link to an external team root
 
 ---
 
 ## Environment Variables
 
-| Variable | Purpose | Values |
-|----------|---------|--------|
-| `SQUAD_CLIENT` | Detected client platform | `cli`, `vscode` |
-| `COPILOT_TOKEN` | Copilot auth token (SDK usage) | Token string |
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `SQUAD_CLIENT` | Detected client platform | `cli`, `vscode`, `web` |
+| `SQUAD_DEBUG` | Enable debug logging | Set to `1` for verbose output |
+| `SQUAD_NO_UPDATE_CHECK` | Skip update availability check | Set to `1` to disable |
 
 ---
 
@@ -267,29 +520,29 @@ When something isn't working, run:
 squad doctor
 ```
 
-This performs a comprehensive diagnostic check of your Squad setup, validating:
+The doctor performs a comprehensive diagnostic check:
 
-- `.squad/` directory structure
-- `config.json` validity and `teamRoot` configuration (if present)
-- Team root resolution (remote mode)
-- Required files: `team.md`, `routing.md`, `decisions.md`
-- `agents/` directory and agent count
-- `casting/registry.json` integrity
+- ✅ `.squad/` directory structure
+- ✅ `config.json` validity
+- ✅ Team root resolution (dual-root mode)
+- ✅ Required files: `team.md`, `routing.md`, `decisions.md`
+- ✅ `agents/` directory and agent count
+- ✅ Agent charters and configuration
 
-### Usage Examples
+**Quick scenarios:**
 
 ```bash
-# Run diagnostics on the current project
-squad doctor
+# After cloning a repo with Squad
+git clone my-project && cd my-project && squad doctor
 
-# Quick check after upgrading Squad
+# After upgrading Squad
 squad upgrade && squad doctor
 
-# Verify setup after cloning a repo with a squad
-git clone my-project && cd my-project && squad doctor
+# Verify setup before opening an issue
+squad doctor
 ```
 
-### Example Output
+**Example output:**
 
 ```
 🩺 Squad Doctor
@@ -297,57 +550,59 @@ git clone my-project && cd my-project && squad doctor
 
 Mode: local
 
-✅  .squad/ directory exists — directory present
-✅  team.md found with ## Members header — file present, header found
-✅  routing.md found — file present
-✅  agents/ directory exists — directory present (4 agents)
-✅  casting/registry.json exists — file present, valid JSON
-✅  decisions.md exists — file present
+✅  .squad/ directory exists
+✅  team.md found with ## Team header
+✅  routing.md found
+✅  agents/ directory exists (4 agents)
+✅  decisions.md exists
 
-Summary: 6 passed, 0 failed, 0 warnings
+Summary: 5 passed, 0 failed, 0 warnings
 ```
 
-The doctor always exits cleanly (exit code 0) because it's a diagnostic tool, not a gate. Use it to troubleshoot setup issues, validate team state, or run before opening an issue on GitHub.
-
-For a full reference of every check, warning, and fix, see [Troubleshooting: `squad doctor` warnings and failures](../scenarios/troubleshooting.md#squad-doctor-warnings-and-failures).
-
 ### Common Issues
 
-**Absolute path warning for teamRoot:**
-
-If you see `⚠ teamRoot uses absolute path — consider making it relative`, it means your `squad.config.ts` or `.squad/config.json` contains an absolute path like `C:\Users\me\squad\` or `/Users/me/squad/`. This breaks portability.
+**Absolute path warning for `teamRoot`:**
 
-**Fix:** Make the path relative to your project root:
-```json
-{
-  "teamRoot": ".squad"
-}
-```
+If you see a warning about absolute paths, make it relative:
 
-For linked teams (dual-root mode), use a relative path:
 ```json
 {
   "teamRoot": "../team-repo/.squad"
 }
 ```
 
-See [FAQ: squad doctor complains about absolute path for teamRoot](../guide/faq.md#squad-doctor-complains-about-absolute-path-for-teamroot) for details.
+The doctor always exits cleanly (exit code 0) because it's diagnostic, not a gate. Use it to troubleshoot setup issues, validate team state, or provide context when reporting bugs.
+
+For detailed doctor checks and fixes, see [Troubleshooting Reference](../scenarios/troubleshooting.md).
 
 ---
 
 ## Version Management
 
+Check your current version and update Squad:
+
 ```bash
-squad --version                              # Check version
-npm install -g @bradygaster/squad-cli@latest # Update
-npm install -g @bradygaster/squad-cli@1.2.3  # Pin version
-npm install -g @bradygaster/squad-cli@insider # Insider builds
+# Check installed version
+squad --version
+
+# Update to latest
+npm install -g @bradygaster/squad-cli@latest
+
+# Pin to specific version
+npm install -g @bradygaster/squad-cli@1.2.3
+
+# Try insider channel (experimental features)
+npm install -g @bradygaster/squad-cli@insider
+
+# Show help and version info
+squad help
 ```
 
 ---
 
 ## See Also
 
-- [SDK Reference](./sdk.md) — Programmatic API
-- [Recipes & Advanced Scenarios](../cookbook/recipes.md) — Prompt-driven cookbook
-- [Adding Squad to an Existing Repo](../scenarios/existing-repo.md) — Getting started walkthrough
+- [SDK Reference](./sdk.md) — Build squads with TypeScript
+- [Remote Control Guide](../features/remote-control.md) — Phone/browser access
+- [Troubleshooting Guide](../scenarios/troubleshooting.md) — Common issues and fixes
+- [Getting Started](../getting-started/index.md) — First steps with Squad
diff --git a/packages/squad-cli/README.md b/packages/squad-cli/README.md
index 4f6a527ce..8853b6595 100644
--- a/packages/squad-cli/README.md
+++ b/packages/squad-cli/README.md
@@ -1,9 +1,19 @@
 # @bradygaster/squad-cli
 
-The programmable multi-agent CLI for GitHub Copilot. Build an AI team, assign roles, and let them work your repo.
+The programmable multi-agent CLI for GitHub Copilot. Build an AI team, assign roles, and let them work your repo—automating issue triage, code review, documentation, and more through orchestrated AI agents.
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
 
 ## Installation
 
+### Prerequisites
+
+- **Node.js ≥ 20** — Squad requires modern JavaScript runtime features
+- **GitHub Copilot** — provides the AI backend for agent orchestration and code analysis
+- **GitHub CLI** (`gh`) — required for issue/PR operations and the work loop
+
+### Install from npm
+
 ```bash
 # Global (recommended)
 npm install -g @bradygaster/squad-cli
@@ -18,60 +28,302 @@ npx @bradygaster/squad-cli
 npm install -g @bradygaster/squad-cli@insider
 ```
 
+### Verify Installation
+
+```bash
+squad --version
+squad doctor    # Validate setup
+```
+
 ## Quick Start
 
+Get a working AI team in three steps:
+
 ```bash
 # 1. Initialize Squad in your repo
 squad init
 
-# 2. Create your first agent
-squad hire --name aria --role "frontend engineer"
-
-# 3. Launch the interactive shell
+# 2. Launch the interactive shell and talk to your team
 squad
 ```
 
-That's it. You have a working AI team.
+The `init` command creates a `.squad/` directory with default agents and configuration. Then `squad` opens a REPL where you can chat with agents, assign work, and monitor progress.
 
-## Commands
+**Example:**
 
-| Command | Description |
-|---------|-------------|
-| `squad` | Launch interactive shell |
-| `squad init` | Initialize Squad in current repo. `--global` for a personal squad. |
-| `squad upgrade` | Update Squad-owned files. `--global`, `--migrate-directory` |
-| `squad status` | Show which squad is active (repo vs personal) and why |
-| `squad triage` | Scan for work and categorize issues |
-| `squad loop` | Continuous work loop. `--filter <pattern>`, `--interval <seconds>` |
-| `squad hire` | Team creation wizard. `--name <name>`, `--role <role>` |
-| `squad copilot` | Add/remove @copilot coding agent. `--off`, `--auto-assign` |
+```
+squad > @Neo, review the authentication module
+squad > Trinity, add unit tests for the login page
+squad > /status    # See what's in progress
+```
+
+## Commands Reference
+
+For detailed documentation on each command, see the [CLI Reference](https://docs.squad.ai/reference/cli) on the docs site.
+
+### Core Commands
+
+| Command | Purpose |
+|---------|---------|
+| `squad` | Enter interactive shell (no arguments) |
+| `squad init` | Initialize Squad in current repo (idempotent) |
+| `squad init --global` | Create a personal squad in your home directory |
+| `squad status` | Show which squad is active and why |
+| `squad doctor` | Validate setup integrity and diagnose issues |
+| `squad upgrade` | Update Squad-owned files to latest version |
+
+### Team Management
+
+| Command | Purpose |
+|---------|---------|
+| `squad hire --name <name> --role <role>` | Add a new agent to your team |
+| `squad copilot` | Add the @copilot coding agent |
+| `squad copilot --off` | Remove @copilot from the team |
+| `squad copilot --auto-assign` | Enable auto-assignment for @copilot |
+
+### Work & Automation
+
+| Command | Purpose |
+|---------|---------|
+| `squad triage` | Auto-triage issues and assign to agents |
+| `squad triage --interval <min>` | Run triage continuously (default: 10 min) |
 | `squad plugin` | Manage plugin marketplaces (add/remove/list/browse) |
-| `squad export` | Export squad to JSON snapshot. `--out <path>` |
-| `squad import <file>` | Import squad from export file. `--force` to overwrite |
-| `squad scrub-emails` | Remove email addresses from Squad state files |
-| `squad help` | Show help |
+
+### Export & Import
+
+| Command | Purpose |
+|---------|---------|
+| `squad export` | Export team to a portable JSON snapshot |
+| `squad export --out <path>` | Export to custom path |
+| `squad import <file>` | Import team from snapshot (or existing squad) |
+| `squad import <file> --force` | Replace existing team (archives old one) |
+
+### Utilities
+
+| Command | Purpose |
+|---------|---------|
+| `squad scrub-emails [directory]` | Remove email addresses from `.squad/` state files |
+| `squad --version` | Print installed version |
+| `squad help` | Show command help |
 
 ## Interactive Shell
 
-Running `squad` with no arguments launches a REPL where you talk directly to your team.
+Run `squad` with no arguments to enter the REPL. You'll see:
 
-- **Slash commands:** `/status`, `/history`, `/agents`, `/clear`, `/help`, `/quit`
-- **@mentions:** Route messages to a specific agent (e.g. `@aria fix the login bug`)
-- **Tab completion:** Agents and commands auto-complete
+```
+squad >
+```
 
-The shell coordinates work across agents, streams responses in real time, and keeps a session history.
+### Shell Commands
 
-## Requirements
+All shell commands start with `/`.
 
-- **Node.js ≥ 20**
-- **GitHub CLI** (`gh`) — required for issue/PR operations and the work loop
-- **GitHub Copilot** — provides the AI backend for agent orchestration
+| Command | Purpose |
+|---------|---------|
+| `/status` | Show active agents, sessions, recent decisions |
+| `/history` | View session log — tasks, decisions, agent work |
+| `/agents` | List team members with roles and expertise |
+| `/sessions` | List saved sessions |
+| `/resume <id>` | Restore a past session |
+| `/clear` | Clear terminal output |
+| `/help` | Show all commands |
+| `/quit` | Exit the shell (also: `Ctrl+C`) |
+
+### Addressing Agents
+
+Use agent names to route messages. Name matching is **case-insensitive**:
+
+```
+squad > @Neo, review the architecture
+squad > @trinity fix the login bug
+squad > Summarize the latest decisions
+```
+
+Omit the agent name and the coordinator routes to the best fit.
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `↑` / `↓` | Scroll command history |
+| `Ctrl+A` | Jump to start of line |
+| `Ctrl+E` | Jump to end of line |
+| `Ctrl+U` | Clear to start of line |
+| `Ctrl+K` | Clear to end of line |
+| `Ctrl+W` | Delete previous word |
+| `Ctrl+C` | Exit shell |
+
+## .squad/ Directory Structure
+
+When you run `squad init`, Squad creates a `.squad/` directory with this structure:
+
+```
+.squad/
+├── team.md                # Roster — agent names, roles, human members
+├── routing.md             # Work routing rules (which agent handles what)
+├── decisions.md           # Architectural decisions log (append-only)
+├── directives.md          # Permanent team rules and conventions
+├── ceremonies.md          # Team ceremonies and rituals
+├── casting-state.json     # Agent names, universe theme
+├── model-config.json      # Per-agent model overrides
+├── manifest.json          # Squad metadata and version
+├── config.json            # Local config (teamRoot, etc.)
+├── agents/                # Agent knowledge files
+│   ├── neo/
+│   │   ├── charter.md     # Role definition, expertise
+│   │   └── history.md     # Accumulated knowledge
+│   └── ...
+├── skills/                # Reusable knowledge (markdown files)
+│   ├── auth-rate-limiting.md
+│   └── ...
+└── sessions/              # Saved REPL sessions
+```
+
+### Key Files
+
+**`team.md`** — Defines your roster:
+
+```markdown
+## Team
+
+🏗️  Neo       — Lead        Scope, decisions, code review
+⚛️  Trinity   — Frontend    React, TypeScript, UI
+🔧  Morpheus — Backend     Node.js, Express, databases
+🧪  Tank     — Tester      Jest, integration tests
+```
+
+**`routing.md`** — Controls work assignment:
+
+```markdown
+# Routing Rules
+
+**Frontend changes** → Trinity
+**Backend API work** → Morpheus
+**Database migrations** → Morpheus
+**Test writing** → Tank
+**Architecture** → Neo
+```
+
+**`decisions.md`** — Append-only architectural log (agents read this before every task):
+
+```markdown
+### 2025-03-20: Use Zod for API validation
+**By:** Morpheus
+**What:** All API input validation uses Zod schemas
+**Why:** Type-safe, composable, generates TypeScript types
+```
+
+**`directives.md`** — Permanent rules agents always follow:
+
+```markdown
+- Always use TypeScript strict mode
+- No any/unknown casts
+- All database queries through Prisma, no raw SQL
+```
+
+## Configuration
+
+### .squadrc / config.json
+
+Squad looks for `.squad/config.json` to customize behavior:
+
+```json
+{
+  "teamRoot": "./team-config",
+  "maxAgents": 10,
+  "modelDefaults": {
+    "temperature": 0.7
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `SQUAD_CLIENT` | Detected platform | `cli`, `vscode` |
+| `COPILOT_TOKEN` | Copilot auth token (SDK usage) | `gho_...` |
+
+### Squad Resolution Order
+
+When Squad starts, it looks for `.squad/` in this order:
+
+1. Current directory (`./.squad/`)
+2. Parent directories (walk up to project root)
+3. Personal squad directory (platform-specific: `~/.config/squad/` on Linux, `~/Library/Application Support/squad/` on macOS, `%APPDATA%\squad\` on Windows)
+4. Global CLI default (fallback only)
+
+First match wins.
+
+## Troubleshooting
+
+### Run `squad doctor`
+
+When something isn't working, run:
+
+```bash
+squad doctor
+```
+
+This performs a comprehensive diagnostic check:
+
+- `.squad/` directory structure
+- Required files: `team.md`, `routing.md`, `decisions.md`
+- Agent directory and count
+- Configuration validity
+- Team root resolution (remote mode)
+
+**Example output:**
+
+```
+🩺 Squad Doctor
+═══════════════
+
+Mode: local
+
+✅  .squad/ directory exists — directory present
+✅  team.md found — file present
+✅  routing.md found — file present
+✅  agents/ directory exists (4 agents)
+✅  decisions.md exists — file present
+
+Summary: 5 passed, 0 failed
+```
+
+### Common Issues
+
+**Missing `.squad/` directory**
+
+Run `squad init` to create it.
+
+**Authentication errors**
+
+Ensure GitHub Copilot is installed and you're authenticated. Check your token:
+
+```bash
+gh auth status
+```
+
+**Node.js version mismatch**
+
+Squad requires Node.js ≥ 20. Check your version:
+
+```bash
+node --version
+```
+
+**ESM import errors**
+
+Squad is an ESM-only module. If you see import errors, ensure your Node.js version is 20+.
 
 ## Links
 
-- **SDK:** [@bradygaster/squad-sdk](https://www.npmjs.com/package/@bradygaster/squad-sdk)
+- **Documentation:** [docs.squad.ai](https://docs.squad.ai)
+- **CLI Reference:** [docs.squad.ai/reference/cli](https://docs.squad.ai/reference/cli) — detailed command docs
+- **SDK:** [@bradygaster/squad-sdk](https://www.npmjs.com/package/@bradygaster/squad-sdk) — programmatic API
+- **GitHub:** [github.com/bradygaster/squad](https://github.com/bradygaster/squad)
 - **Issues:** [github.com/bradygaster/squad/issues](https://github.com/bradygaster/squad/issues)
 
 ## License
 
-See [LICENSE](https://github.com/bradygaster/squad/blob/main/LICENSE) in the repository root.
+MIT. See [LICENSE](https://github.com/bradygaster/squad/blob/main/LICENSE) in the repository root.