docs: centralize CLI and interface guidance

docs/src/content/docs/get-started/choose-your-interface.md

@@ -0,0 +1,174 @@
+# Choose your interface
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+
+Squad works across multiple interfaces. Pick the one that fits your workflow.
+
+---
+
+## Try this:
+
+```bash
+# Day-to-day work with your squad
+copilot --agent squad
+
+# Setup and diagnostics
+squad init
+squad doctor
+```
+
+---
+
+## What are the ways to use Squad?
+
+Squad runs in multiple modes and across multiple platforms:
+
+### GitHub Copilot CLI (`copilot` command)
+
+The conversational terminal interface. Powered by the GitHub Copilot CLI, this is the recommended way to work with Squad day-to-day.
+
+```bash
+copilot --agent squad
+```
+
+Reads `.squad/` and uses `squad.agent.md` to coordinate your team. Full feature set — sub-agent spawning, per-spawn model selection, background execution, SQL tools, parallel fan-out.
+
+### VS Code (GitHub Copilot in the editor)
+
+Squad works identically in VS Code through GitHub Copilot. Same `.squad/` directory, same agents, same decisions. Full file access, parallel execution, MCP tool inheritance. See [Squad in VS Code](../features/vscode.md) for details.
+
+### Squad CLI (`squad` command)
+
+The Squad CLI provides setup, diagnostics, and automation commands. Not conversational — use this for installation, validation, and operational tasks.
+
+```bash
+# Setup
+squad init
+
+# Validation
+squad doctor
+
+# Monitoring
+squad watch
+
+# Observability
+squad aspire
+```
+
+See [CLI Reference](../reference/cli.md) for all commands.
+
+### Interactive shell (`squad start` / `squad shell`)
+
+REPL mode for conversational interaction directly via the Squad CLI. Enter `squad` with no arguments to start a persistent shell session. See [Interactive Shell Guide](../guide/shell.md).
+
+This works, but **GitHub Copilot CLI is recommended** — richer agent experience, better tools, full MCP integration.
+
+### SDK (`@bradygaster/squad-sdk`)
+
+Programmatic access for building tools on top of Squad. Typed APIs, routing config, agent lifecycle hooks.
+
+```bash
+npm install @bradygaster/squad-sdk
+```
+
+```typescript
+import { resolveSquad, loadConfig, SquadCoordinator } from '@bradygaster/squad-sdk';
+```
+
+See [SDK Reference](../reference/sdk.md) for the complete API.
+
+### Copilot Coding Agent (`@copilot`)
+
+Autonomous GitHub bot that picks up labeled issues and opens draft PRs. Works across your entire organization without human intervention. Issue gets labeled → agent picks it up → PR gets opened → human reviews.
+
+See [Copilot Coding Agent](../features/copilot-coding-agent.md) for setup.
+
+---
+
+## Which should I use?
+
+| You want to... | Use | Why |
+|----------------|-----|-----|
+| **Work with your squad day-to-day** | **GitHub Copilot CLI** or **VS Code** | Conversational interface, full agent spawning, parallel execution. Most natural way to collaborate with your team. |
+| **Set up Squad in a new repo** | **Squad CLI** (`squad init`) | One command initializes `.squad/` directory and all configuration. |
+| **Check if Squad is working** | **Squad CLI** (`squad doctor`) | Validates directory structure, agents, configuration integrity. |
+| **Monitor work 24/7** | **Squad CLI** (`squad watch`) | Persistent polling for new issues, auto-triage, agent assignment. |
+| **View OpenTelemetry traces** | **Squad CLI** (`squad aspire`) | Launches Aspire dashboard for observability. |
+| **Process issues autonomously** | **Copilot Coding Agent** | GitHub Actions workflow watches for labeled issues and dispatches `@copilot`. |
+| **Build tools on top of Squad** | **SDK** | Typed APIs, configuration loading, agent lifecycle hooks. |
+
+---
+
+## Feature availability matrix
+
+Not every feature works everywhere. Here's what's available where:
+
+| Feature | GitHub Copilot CLI | VS Code | Squad CLI | SDK |
+|---------|:------------------:|:-------:|:---------:|:---:|
+| Agent spawning | ✅ | ✅ | ✅ (via shell) | ✅ |
+| Ralph / work monitoring | ✅ | ✅ | ✅ (`squad watch`) | ✅ |
+| Per-spawn model selection | ✅ | ⚠️ (session model only) | ✅ | ✅ |
+| Background execution | ✅ | ⚠️ (parallel sync) | ✅ | ✅ |
+| SQL tool | ✅ | ❌ | ✅ | ✅ |
+| Aspire dashboard | ❌ | ❌ | ✅ | ❌ |
+| `squad doctor` diagnostics | ❌ | ❌ | ✅ | ✅ |
+| Issue assignment to `@copilot` | ❌ | ❌ | ✅ (setup) | ❌ |
+
+**Legend:**
+- ✅ Fully supported
+- ⚠️ Limited or constrained
+- ❌ Not available
+
+For a detailed breakdown of VS Code constraints and CLI parity, see [Client Compatibility Matrix](../scenarios/client-compatibility.md).
+
+---
+
+## Common workflows
+
+### "I use GitHub Copilot CLI for everything"
+
+```bash
+# Terminal 1: Work with Squad
+copilot --agent squad
+
+# Let Squad call `squad` commands when needed (doctor, watch, aspire)
+```
+
+This is the recommended workflow. The CLI automatically invokes Squad CLI commands when needed.
+
+### "I run squad watch in one terminal and use GitHub Copilot CLI in another"
+
+```bash
+# Terminal 1: Monitoring (persistent)
+squad watch --interval 10
+
+# Terminal 2: Work with Squad
+copilot --agent squad
+```
+
+Keep Ralph monitoring issues in the background while you work conversationally.
+
+### "I use VS Code with Copilot for coding and Squad CLI for setup"
+
+```bash
+# One-time setup
+squad init
+squad doctor
+
+# Open VS Code, select Squad from agent picker
+# Same .squad/ directory, same team
+```
+
+Initialize with CLI, work in VS Code.
+
+---
+
+## See also
+
+- [Installation](installation.md) — Install Squad CLI, SDK, or use in VS Code
+- [First Session](first-session.md) — Get started with your first Squad conversation
+- [Client Compatibility Matrix](../scenarios/client-compatibility.md) — Full feature comparison across platforms
+- [CLI Reference](../reference/cli.md) — All Squad CLI commands
+- [Squad in VS Code](../features/vscode.md) — VS Code-specific guidance
+- [SDK Reference](../reference/sdk.md) — Programmatic API

docs/src/content/docs/get-started/installation.md

@@ -100,6 +100,12 @@ The SDK gives you typed configuration, routing, model selection, and the full ag
 
 ---
 
+## Not sure which interface to use?
+
+See [Choose your interface](choose-your-interface.md) for a complete breakdown of GitHub Copilot CLI, VS Code, Squad CLI, SDK, and the Copilot Coding Agent.
+
+---
+
 ### Personal squad (cross-project)
 
 Want the same agents across all your projects?

docs/src/content/docs/guide.md

@@ -10,14 +10,15 @@ It is not a chatbot wearing hats. Each team member is spawned as a real sub-agen
 
 ## Supported Platforms
 
-Squad is designed for **GitHub Copilot CLI** and ships with full support. **VS Code is now fully supported with zero code changes** — agents work identically on both platforms.
+Squad works across multiple interfaces — GitHub Copilot CLI, VS Code, Squad CLI, SDK, and the Copilot Coding Agent. Pick the one that fits your workflow:
 
-**Current state:**
-- ✅ **GitHub Copilot CLI** — fully supported. This is the primary platform. Uses the stable `task` tool for sub-agent spawning, per-spawn model selection, and background mode.
-- ✅ **VS Code Copilot** — fully supported (v0.4.0+). VS Code uses `runSubagent` for parallel execution and supports full `.ai-team/` read/write. See [Client Compatibility Matrix](scenarios/client-compatibility.md) for details.
-- ❌ **Other platforms** — JetBrains IDEs and other runtimes are untested. GitHub.com web-based Copilot is untested.
+- **GitHub Copilot CLI** — Day-to-day conversational work with your squad (recommended)
+- **VS Code** — Same experience, editor-integrated
+- **Squad CLI** — Setup, diagnostics, monitoring (`squad init`, `squad doctor`, `squad watch`)
+- **SDK** — Build tools on top of Squad
+- **Copilot Coding Agent** — Autonomous issue processing via `@copilot`
 
-For a detailed feature comparison across platforms (model selection, background execution, file access, etc.), see [Client Compatibility Matrix](scenarios/client-compatibility.md).
+Not sure which to use? See [Choose your interface](get-started/choose-your-interface.md) for a complete comparison and decision tree.
 
 ---
 

docs/src/content/docs/scenarios/client-compatibility.md

@@ -1,5 +1,7 @@
 # Copilot Client Compatibility Matrix
 
+> **Quick answer:** Not sure which interface to use? See [Choose your interface](../get-started/choose-your-interface.md) for a concise decision tree and comparison.
+
 Squad runs on multiple Copilot surfaces — each with its own agent spawning mechanism, tool set, and constraints. This document maps Squad's core capabilities across CLI, VS Code, JetBrains, and GitHub.com to help you understand what works where.
 
 ## Quick Reference

test/docs-build.test.ts

@@ -15,7 +15,7 @@ const BLOG_CONTENT_DIR = join(CONTENT_DIR, 'blog');
 const DIST_DIR = join(DOCS_DIR, 'dist');
 
 // Expected content directories in src/content/docs/
-const EXPECTED_GET_STARTED = ['installation', 'first-session'];
+const EXPECTED_GET_STARTED = ['installation', 'first-session', 'choose-your-interface'];
 
 const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell'];