Docs update: comprehensive new-user experience improvements

docs/src/content/docs/concepts/architecture.md

@@ -0,0 +1,70 @@
+# Architecture
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+How Squad works — one page, no handwaving.
+
+---
+
+## System diagram
+
+```
+User request
+    ↓
+Coordinator (routing engine)
+    ↓
+Spawns agents in parallel
+    ↓
+Agents read memory (.squad/) → work → write results
+    ↓
+Scribe merges decisions, Ralph tracks issues
+    ↓
+Results returned to user
+```
+
+---
+
+## Components
+
+### Coordinator
+
+The coordinator is Squad's routing engine. It reads your request, checks routing rules in `.squad/routing.md`, and decides which agents to spawn. If you say "team," it decomposes the work and launches multiple agents in parallel. If you name an agent, it routes directly to them.
+
+### Agents
+
+Each agent is a specialist with a charter, role, and persistent memory. Agents are spawned as independent subprocesses with their own context windows and tools. They read `.squad/decisions.md` and their own history before working, then write results back. Agents never see each other's conversations — the coordinator orchestrates coordination.
+
+### Memory (.squad/)
+
+All team state lives in `.squad/`. This includes the roster (`team.md`), routing rules (`routing.md`), decisions (`decisions.md`), agent charters and histories (`agents/`), and ceremony schedules (`ceremonies.md`). Agents read this before every spawn. You own these files — edit them anytime.
+
+### Routing
+
+Routing rules in `.squad/routing.md` define which agent handles which work. The coordinator reads these rules before spawning. You can override routing by naming an agent directly in your request.
+
+### Scribe
+
+The Scribe is a silent agent that tracks decisions and logs sessions. Every team has a Scribe. You never talk to them directly — they work in the background, merging decisions from all agents into `.squad/decisions.md`.
+
+### Ralph
+
+Ralph is the work monitor. He watches your GitHub or GitLab issues, tracks work in progress, and alerts the team when something is ready. Every team has a Ralph. He's silent unless you ask him for status.
+
+---
+
+## What happens when you say "Team, build X"?
+
+1. **Coordinator reads the request** and checks `.squad/routing.md` for decomposition rules.
+2. **Coordinator spawns multiple agents in parallel** — one for frontend, one for backend, one for tests, etc.
+3. **Each agent reads `.squad/decisions.md`** and their own history (`agents/{name}/history.md`), then works independently.
+4. **Agents write results** to their history files and propose decisions.
+5. **Scribe merges all decisions** into `.squad/decisions.md`.
+6. **Coordinator returns labeled results** to you, tagged with each agent's name.
+
+---
+
+## Learn more
+
+- [**Work routing**](../features/routing) — How the coordinator decides which agents to spawn
+- [**Memory and knowledge**](memory-and-knowledge) — How decisions, skills, and history persist
+- [**Parallel work**](parallel-work) — How agents work simultaneously without conflicts

docs/src/content/docs/get-started/choosing-your-path.md

@@ -0,0 +1,82 @@
+# Choose your path
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+CLI, Copilot agent, or SDK? Pick the right mode for your workflow.
+
+---
+
+## Three modes
+
+### CLI mode
+
+Install Squad globally or per-project, then use terminal commands to initialize, route work, and manage your team.
+
+```bash
+npm install -g @bradygaster/squad-cli
+squad init
+squad status
+squad watch
+```
+
+**Use for:** Terminal workflows, automation scripts, CI/CD integration.
+
+---
+
+### Copilot agent mode
+
+Talk to Squad in GitHub Copilot CLI or VS Code. Squad is built-in as an agent. Your `.squad/` directory works identically to CLI mode.
+
+```bash
+copilot
+> /agent Squad
+
+Squad: Hey Brady, what are you building?
+```
+
+**Use for:** Conversational workflows, exploratory work, VS Code users.
+
+---
+
+### SDK mode
+
+Write TypeScript code that spawns agents, routes work, and coordinates teams programmatically. Full access to Squad's internals.
+
+```bash
+npm install @bradygaster/squad-sdk
+```
+
+```typescript
+import { Coordinator } from '@bradygaster/squad-sdk';
+
+const coordinator = new Coordinator();
+const result = await coordinator.route('Build a login page');
+```
+
+**Use for:** Building tools on Squad, custom integrations, advanced automation.
+
+---
+
+## Decision table
+
+| **Your goal** | **Use** |
+|---------------|---------|
+| Try Squad quickly | **Copilot agent** — no install |
+| Work in the terminal | **CLI** |
+| Work in VS Code | **Copilot agent** |
+| Automate repetitive tasks | **CLI** or **SDK** |
+| Build custom tooling | **SDK** |
+| CI/CD integration | **CLI** or **SDK** |
+
+---
+
+## Can I use multiple modes?
+
+Yes. Your `.squad/` directory is the source of truth. CLI, Copilot agent, and SDK all read and write the same files. You can switch between modes anytime.
+
+Example workflow:
+1. Use **Copilot agent** to form your team and do exploratory work
+2. Use **CLI** (`squad watch`) to monitor issues in the background
+3. Use **SDK** to build a custom deployment script that spawns agents
+
+All three modes share the same memory and decisions.

docs/src/content/docs/get-started/first-session.md

@@ -48,7 +48,7 @@ Start the Copilot CLI:
 copilot
 ```
 
-Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). Squad greets you by name (pulled from `git config user.name`):
+Select **Squad** from the `/agent` list (CLI) or `/agents` (VS Code). Squad greets you by name:
 
 ```
 Hey Brady, what are you building?
@@ -61,7 +61,7 @@ Describe your project:
 > post recipes, search by ingredient, and save favorites.
 ```
 
-Squad proposes a team. Names come from a fictional universe — the exact universe depends on your project shape and history:
+Squad proposes a team. The coordinator analyzes your description and suggests specialists:
 
 ```
 Here's your team:
@@ -72,6 +72,8 @@ Here's your team:
 🧪  Lambert  — Tester        Tests, quality, edge cases
 📋  Scribe   — (silent)      Memory, decisions, session logs
 
+**Scribe** and **Ralph** are always on every roster — you don't manage them.
+
 Look right? Say yes, add someone, or change a role.
 (Or just give me a task to start!)
 ```
@@ -86,7 +88,7 @@ Say "yes" or skip straight to a task (which is implicit confirmation):
 > Yes. Dallas, set up the Express server with basic routing.
 ```
 
-Squad creates the `.squad/` directory structure — team roster, routing rules, casting state, ceremony config, agent charters, and histories — all seeded with your project context.
+Squad creates the `.squad/` directory structure — team roster, routing rules, casting state, ceremony config, agent charters, and histories — all seeded with your project context. Each agent spawns to do their work.
 
 ### What's inside .squad/?
 
@@ -177,7 +179,7 @@ At any point, check status:
 > Where are we?
 ```
 
-This is a Direct mode response — no agent spawn, just the coordinator reading recent logs:
+The coordinator reads recent logs:
 
 ```
 Last session: Recipe listing page (15 minutes ago)
@@ -274,7 +276,7 @@ squad export
    5 agents, 3 skills, 6 decisions
 ```
 
-This snapshot contains everything — charters, histories, casting state, skills, and decisions. Import into another repo anytime:
+This snapshot contains charters, histories, casting state, skills, and decisions. Import into another repo anytime:
 
 ```bash
 cd ../other-project
@@ -286,8 +288,8 @@ squad import ../my-app/squad-export.json
 
 ## Tips
 
-- **First session is the slowest.** Agents have no history yet. After 2–3 sessions, they know your conventions and stop asking repeated questions.
-- **Commit `.squad/`.** It's your team's brain. Anyone who clones the repo gets the team with all their knowledge.
+- **First session is slowest.** Agents have no history yet. After 2–3 sessions, they know your conventions.
+- **Commit `.squad/`** — your team's brain. Anyone who clones the repo gets the full team.
 - **Say "team" for big tasks.** The word "team" triggers parallel fan-out across multiple agents.
 - **Name an agent for focused work.** `"Dallas, fix the login bug"` sends work to one specific agent.
 - **Directives are sticky.** Once captured, they persist across all future sessions.

docs/src/content/docs/get-started/five-minute-start.md

@@ -0,0 +1,87 @@
+# Quick start
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+Your first 5 minutes with Squad. Prove it works before you learn anything.
+
+---
+
+## Prerequisites
+
+- **Node.js 20+** — Check with `node --version`
+- **Git repository** — New or existing
+
+---
+
+## Install
+
+```bash
+npm install --save-dev @bradygaster/squad-cli
+```
+
+Then initialize:
+
+```bash
+npx squad init
+```
+
+You'll see:
+
+```
+✅ Squad installed.
+   .github/agents/squad.agent.md — coordinator agent
+   .squad/templates/ — 11 template files
+
+Open GitHub Copilot and select Squad from the agent list.
+```
+
+---
+
+## Validate
+
+Check that Squad created your team directory:
+
+```bash
+ls .squad/
+```
+
+You should see: `team.md`, `routing.md`, `decisions.md`, `agents/`, and more.
+
+Confirm Squad is ready:
+
+```bash
+npx squad status
+```
+
+---
+
+## Try it
+
+Open GitHub Copilot in your terminal or VS Code. Select **Squad** from the agent list (`/agent Squad` in CLI or `/agents` in VS Code).
+
+Say something simple:
+
+```
+> I'm building a task management app with React and Node.js.
+> Users can create, update, and delete tasks.
+```
+
+Squad forms your team and responds with agent names and roles. Say yes, or just give your first task:
+
+```
+> Team, create a basic Express server with a /health endpoint.
+```
+
+Squad spawns agents and does the work.
+
+---
+
+## What just happened?
+
+Squad read your description, formed a team of specialists, wrote their charters to `.squad/agents/`, and coordinated parallel work. Check `.squad/decisions.md` to see what they decided.
+
+---
+
+## Next steps
+
+[**Your first session**](first-session) — Step-by-step walkthrough of parallel work, decisions, and memory.

docs/src/content/docs/reference/glossary.md

@@ -0,0 +1,39 @@
+# Glossary
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+Key terms defined in one sentence each. Alphabetical order.
+
+---
+
+**Agent** — A specialist AI team member with a role, charter, and persistent memory that handles specific types of work.
+
+**Casting** — The process of forming your team by proposing agents, confirming roles, and writing their charters to `.squad/`.
+
+**Ceremony** — A scheduled team event like retrospectives, reviews, or planning sessions defined in `.squad/ceremonies.md`.
+
+**Coordinator** — Squad's routing engine that reads your request, checks routing rules, and spawns the right agents.
+
+**Decisions** — Architectural choices, conventions, and directives captured in `.squad/decisions.md` that all agents read before working.
+
+**Directive** — A persistent rule or convention you give the team (like "Always use Zod for validation") that gets written to `decisions.md`.
+
+**History** — Each agent's memory of past work, stored in `.squad/agents/{name}/history.md` and read before every spawn.
+
+**Memory** — All persistent team state stored in the `.squad/` directory, including roster, routing rules, decisions, and agent histories.
+
+**Ralph** — The silent work monitor agent that watches your GitHub or GitLab issues and tracks work in progress.
+
+**Routing** — Rules in `.squad/routing.md` that define which agent handles which type of work, read by the coordinator before spawning.
+
+**Scribe** — The silent agent that tracks decisions and logs sessions, merging proposals from all agents into `.squad/decisions.md`.
+
+**Skill** — A reusable capability stored in `.squad/skills/` that agents can learn and execute.
+
+**Spawn** — The act of starting an agent as an independent subprocess with its own context window, tools, and memory.
+
+**Squad** — Your AI development team, coordinated through the Squad framework.
+
+**.squad/ directory** — The root directory containing all team state: roster, routing, decisions, agent charters and histories, and ceremony config.
+
+**Team** — The collection of agents working on your project, defined in `.squad/team.md`.

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

@@ -4,6 +4,18 @@ Common issues and fixes for Squad installation and usage.
 
 ---
 
+## Quick fixes
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `squad: command not found` | Squad CLI not installed or not in PATH | Run `npm install -g @bradygaster/squad-cli` or use `npx @bradygaster/squad-cli` |
+| `No .squad/ directory found` | Not in a git repo or Squad not initialized | Run `git init` then `npx squad init` |
+| `Cannot find agent "{name}"` | Agent doesn't exist in `.squad/agents/` | Check `.squad/team.md` for roster, or re-run casting |
+| `gh: command not found` | GitHub CLI not installed | Install from [cli.github.com](https://cli.github.com/) then `gh auth login` |
+| `Node.js version error` | Node.js version below v20 | Upgrade Node.js to v20+ (see below) |
+
+---
+
 ## `npx github:bradygaster/squad` appears to hang
 
 **Problem:** Running the install command shows a frozen npm spinner. Nothing happens.

docs/src/navigation.ts

@@ -14,7 +14,9 @@ export const NAV_SECTIONS: NavSection[] = [
     title: 'Get Started',
     dir: 'get-started',
     items: [
+      { title: 'Quick start', slug: 'get-started/five-minute-start' },
       { title: 'Installation', slug: 'get-started/installation' },
+      { title: 'Choose your path', slug: 'get-started/choosing-your-path' },
       { title: 'Your First Session', slug: 'get-started/first-session' },
       { title: 'Migration Guide', slug: 'get-started/migration' },
     ],
@@ -78,6 +80,7 @@ export const NAV_SECTIONS: NavSection[] = [
       { title: 'SDK Integration', slug: 'reference/integration' },
       { title: 'Tools & Hooks', slug: 'reference/tools-and-hooks' },
       { title: 'Config', slug: 'reference/config' },
+      { title: 'Glossary', slug: 'reference/glossary' },
     ],
   },
   {
@@ -115,6 +118,7 @@ export const NAV_SECTIONS: NavSection[] = [
     title: 'Concepts',
     dir: 'concepts',
     items: [
+      { title: 'Architecture', slug: 'concepts/architecture' },
       { title: 'Your Team', slug: 'concepts/your-team' },
       { title: 'Memory & Knowledge', slug: 'concepts/memory-and-knowledge' },
       { title: 'Parallel Work', slug: 'concepts/parallel-work' },