docs: deprecate REPL/interactive shell references, redirect to Copilot CLI

README.md

@@ -106,7 +106,7 @@ Use `--force` to re-apply updates even when your installed version already match
 | `squad link <team-repo-path>` | Connect to a remote team |
 | `squad externalize` | Move `.squad/` state outside the working tree; survives branch switches; use `--key <name>` for custom project key |
 | `squad internalize` | Move externalized state back into `.squad/` |
-| `squad shell` | Launch interactive shell explicitly |
+| `squad shell` | **Deprecated** — Launch interactive shell explicitly. Use `copilot --agent squad` instead. |
 | `squad export` | Export squad to a portable JSON snapshot |
 | `squad import <file>` | Import squad from an export file |
 | `squad plugin marketplace add\|remove\|list\|browse` | Manage plugin marketplaces |
@@ -271,6 +271,14 @@ Round: 42 / 1200
 
 ## Interactive Shell
 
+> ⚠️ **Deprecated:** The interactive shell (`squad` with no arguments) has been deprecated. For the best Squad experience, use the [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) instead.
+>
+> ```bash
+> copilot --agent squad
+> ```
+>
+> See [Choose your interface](docs/src/content/docs/get-started/choose-your-interface.md) for current options.
+
 Tired of typing `squad` followed by a command every time? Enter the interactive shell.
 
 ### Entering the Shell

README.zh.md

@@ -103,7 +103,7 @@ squad upgrade
 | `squad copilot` | 添加/移除 Copilot 编码智能体 (@copilot)；使用 `--off` 移除，`--auto-assign` 启用自动分配 |
 | `squad doctor` | 检查环境配置并诊断问题（别名：`heartbeat`） |
 | `squad link <team-repo-path>` | 连接到远程团队仓库 |
-| `squad shell` | 显式启动交互式 shell |
+| `squad shell` | **已弃用** — 显式启动交互式 shell。请改用 `copilot --agent squad`。 |
 | `squad export` | 将小队导出为可移植的 JSON 快照 |
 | `squad import <file>` | 从导出文件导入小队 |
 | `squad plugin marketplace add\|remove\|list\|browse` | 管理插件市场 |
@@ -116,6 +116,14 @@ squad upgrade
 
 ## 交互式 Shell
 
+> ⚠️ **已弃用：** 交互式 shell（`squad` 无参数）已弃用。为了获得最佳的 Squad 体验，请改用 [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli)。
+>
+> ```bash
+> copilot --agent squad
+> ```
+>
+> 详见[选择您的界面](docs/src/content/docs/get-started/choose-your-interface.md)了解当前选项。
+
 厌倦了每次都输入 `squad` 加命令？进入交互式 shell。
 
 ### 进入 Shell

docs/src/content/blog/015-wave-2-the-repl-moment.md

@@ -10,6 +10,8 @@ hero: "We built an interactive shell that makes you forget you're talking to age
 
 # Wave 2: The REPL Moment
 
+> 📌 **Archive note:** The interactive shell described in this post has been deprecated. For the best Squad experience, use the [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli). See [Choose your interface](/docs/get-started/choose-your-interface/) for current options.
+
 > ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
 
 

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

@@ -60,9 +60,13 @@ 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).
+> ⚠️ **Deprecated:** The interactive shell is no longer recommended. Use [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) instead for a richer agent experience.
+>
+> ```bash
+> copilot --agent squad
+> ```
 
-This works, but **GitHub Copilot CLI is recommended** — richer agent experience, better tools, full MCP integration.
+REPL mode for conversational interaction directly via the Squad CLI. Enter `squad` with no arguments to start a persistent shell session.
 
 ### SDK (`@bradygaster/squad-sdk`)
 
@@ -104,16 +108,16 @@ See [Copilot Coding Agent](../features/copilot-coding-agent.md) for setup.
 
 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) | ❌ |
+| Feature | GitHub Copilot CLI | VS Code | Squad CLI | Interactive shell | SDK |
+|---------|:------------------:|:-------:|:---------:|:--------:|:---:|
+| Agent spawning | ✅ | ✅ | ✅ | ⚠️ (deprecated) | ✅ |
+| 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

docs/src/content/docs/guide.md

@@ -16,7 +16,7 @@ It is not a chatbot wearing hats. Each team member is spawned as a real sub-agen
 - Initial setup: `squad init`
 - Build from config: `squad build`
 - Diagnostics: `squad doctor`
-- Interactive shell: `squad shell`
+- Interactive shell: `squad shell` — **Deprecated** (use `copilot --agent squad`)
 - Continuous triage: `squad triage --interval 10`
 - Watch mode: `squad watch`
 - Aspire dashboard: `squad aspire`
@@ -547,7 +547,7 @@ Squad maintains a clear ownership model:
 | `squad build` | Generate `.squad/` from `squad.config.ts` |
 | `squad build --check` | Validate generated files match disk (for CI) |
 | `squad doctor` | Run 9 setup validation checks |
-| `squad shell` | Enter the interactive shell |
+| `squad shell` | **Deprecated** — Enter the interactive shell (use `copilot --agent squad`) |
 | `squad triage` | Run a single triage pass |
 | `squad triage --interval 10` | Continuous triage every 10 minutes |
 | `squad watch` | Ralph watchdog mode |

docs/src/content/docs/reference/cli.md

@@ -26,7 +26,7 @@ squad init
 
 | Command | Description | Requires `.squad/` |
 |---------|-------------|:------------------:|
-| `squad` | Enter interactive shell (no args) | No |
+| `squad` | **Deprecated** — Enter interactive shell (no args). Use `copilot --agent squad` instead. | 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 --mode remote <path>` | Initialize linked to a remote team root (dual-root mode) | No |
@@ -52,6 +52,7 @@ squad init
 | `squad watch --max-concurrent N` | Max parallel issues per round (default: 1) | Yes |
 | `squad watch --timeout N` | Per-issue timeout in minutes (default: 30) | Yes |
 | `squad watch --copilot-flags "..."` | Extra flags for Copilot CLI | Yes |
+| `squad shell` | **Deprecated** — Launch interactive shell explicitly. Use `copilot --agent squad` instead. | No |
 | `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 |