docs(squads): add Squads page and cross-link from related docs

Adds a dedicated bilingual /docs/squads page covering the squad model
(leader + members), assignment, comment trigger rules, archive
semantics, and the squad CLI surface. Wires the new page into
meta.json and meta.zh.json under the Agents section, and adds
short cross-references from agents, assigning-issues,
mentioning-agents, and the CLI reference so users can discover
squads from the pages they're already on.

MUL-2206

Co-authored-by: multica-agent <github@multica.ai>

apps/docs/content/docs/agents.mdx

@@ -45,4 +45,5 @@ New agents default to **private**. To make one available to the whole workspace,
 
 - [Create and configure an agent](/agents-create) — how to build one
 - [Skills](/skills) — attach knowledge packs to an agent
+- [Squads](/squads) — group agents under a leader so the right one picks up the right issue
 - [Daemon and runtimes](/daemon-runtimes) — what an agent needs to actually run

apps/docs/content/docs/agents.zh.mdx

@@ -45,4 +45,5 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 - [创建和配置智能体](/agents-create) —— 怎么把一个智能体捏出来
 - [Skills](/skills) —— 给智能体挂上专业知识包
+- [小队](/squads) —— 把智能体编成一组，由队长决定谁接手哪条 issue
 - [守护进程与运行时](/daemon-runtimes) —— 智能体真正跑起来需要什么

apps/docs/content/docs/assigning-issues.mdx

@@ -5,7 +5,7 @@ description: Hand an issue to an agent and it takes over as the official assigne
 
 import { Callout } from "fumadocs-ui/components/callout";
 
-Assign an [issue](/issues) to an [agent](/agents) and it works as the **official assignee** until the work is done — it can read the full issue context (description + all [comments](/comments)) and change status, post comments, and edit fields. This is the **most common and heaviest** of Multica's four trigger paths.
+Assign an [issue](/issues) to an [agent](/agents) and it works as the **official assignee** until the work is done — it can read the full issue context (description + all [comments](/comments)) and change status, post comments, and edit fields. This is the **most common and heaviest** of Multica's four trigger paths. The same flow also accepts a [squad](/squads) as the assignee — Multica then triggers the squad's **leader agent** instead.
 
 | Path | When to use | Changes the issue | Context | Priority | Auto retry |
 |---|---|---|---|---|---|
@@ -18,7 +18,7 @@ Assign an [issue](/issues) to an [agent](/agents) and it works as the **official
 
 ## Assign from the UI
 
-On the issue detail page, click the **Assignee** picker. It lists every member in the workspace plus all non-archived agents. Pick an agent and the issue is assigned right away.
+On the issue detail page, click the **Assignee** picker. It lists every member in the workspace, all non-archived agents, and every non-archived [squad](/squads). Pick an agent (or squad) and the issue is assigned right away.
 
 A few rules:
 
@@ -78,5 +78,6 @@ But **different agents can work on the same issue in parallel** — for example,
 ## Next
 
 - [**@-mention an agent in a comment**](/mentioning-agents) — a lighter trigger that leaves assignee and status untouched
+- [**Squads**](/squads) — assign to a group of agents and let the leader decide who picks it up
 - [**Chat**](/chat) — one-to-one conversation outside any issue
 - [**Autopilots**](/autopilots) — let agents start work automatically on a schedule

apps/docs/content/docs/assigning-issues.zh.mdx

@@ -5,7 +5,7 @@ description: 把 issue 交给智能体，它作为正式负责人一直工作到
 
 import { Callout } from "fumadocs-ui/components/callout";
 
-把 [issue](/issues) 分配给 [智能体](/agents)，它会作为**正式负责人**一直工作到结束——能读到 issue 的完整上下文（描述 + 所有 [评论](/comments)），也能改状态、发评论、改字段。这是 Multica 四种触发方式里**最常见也最"重"**的一种。
+把 [issue](/issues) 分配给 [智能体](/agents)，它会作为**正式负责人**一直工作到结束——能读到 issue 的完整上下文（描述 + 所有 [评论](/comments)），也能改状态、发评论、改字段。这是 Multica 四种触发方式里**最常见也最"重"**的一种。同样的流程也接受 [小队（squad）](/squads) 作为 assignee——这种情况下 Multica 会触发小队的**队长智能体**。
 
 | 方式 | 何时用 | 改 issue | 上下文 | 优先级 | 自动重试 |
 |---|---|---|---|---|---|
@@ -18,7 +18,7 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 ## 在界面里分配
 
-在 issue 详情页点 **Assignee** 选择器，会列出工作区里所有成员和未归档的智能体。选一个智能体，issue 立刻分给它。
+在 issue 详情页点 **Assignee** 选择器，会列出工作区里所有成员、未归档的智能体、以及未归档的 [小队](/squads)。选一个智能体（或小队），issue 立刻分配。
 
 几条规则：
 
@@ -78,5 +78,6 @@ multica issue assign MUL-42 --unassign
 ## 下一步
 
 - [**在评论里 @ 智能体**](/mentioning-agents) —— 更轻量的触发方式，不改 assignee / status
+- [**小队**](/squads) —— 把 issue 分给一组智能体，由队长决定谁接手
 - [**对话**](/chat) —— 脱离 issue 和智能体一对一聊
 - [**Autopilots**](/autopilots) —— 让智能体定时自动开工

apps/docs/content/docs/cli.mdx

@@ -79,6 +79,20 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 | `multica skill import ...` | Import a skill from GitHub, ClawHub, or the local machine |
 | `multica skill files ...` | Nested: manage a skill's files |
 
+## Squads
+
+| Command | Purpose |
+|---|---|
+| `multica squad list` | List squads in the workspace |
+| `multica squad get <id>` | Show a single squad |
+| `multica squad create --name "..." --leader <agent>` | Create a squad (owner / admin) |
+| `multica squad update <id> ...` | Update name, description, instructions, leader, or avatar |
+| `multica squad delete <id>` | Archive (soft-delete) — transfers assigned issues to the leader |
+| `multica squad member list/add/remove <squad-id>` | Manage squad members |
+| `multica squad activity <issue-id> <action\|no_action\|failed> --reason "..."` | Used by squad leader agents to record an evaluation per turn |
+
+See [Squads](/squads) for the full model.
+
 ## Autopilots
 
 | Command | Purpose |

apps/docs/content/docs/cli.zh.mdx

@@ -79,6 +79,20 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 | `multica skill import ...` | 从 GitHub / ClawHub / 本机导入 Skill |
 | `multica skill files ...` | 嵌套：管理 Skill 的文件 |
 
+## 小队
+
+| 命令 | 用途 |
+|---|---|
+| `multica squad list` | 列出工作区里的小队 |
+| `multica squad get <id>` | 查看一个小队 |
+| `multica squad create --name "..." --leader <agent>` | 创建小队（owner / admin）|
+| `multica squad update <id> ...` | 修改名字、描述、instructions、队长、头像 |
+| `multica squad delete <id>` | 归档（软删除）—— 同时把分配给小队的 issue 转给队长 |
+| `multica squad member list/add/remove <squad-id>` | 管理小队成员 |
+| `multica squad activity <issue-id> <action\|no_action\|failed> --reason "..."` | 队长智能体每轮结束时调用，记录 evaluation |
+
+完整模型见 [小队](/squads)。
+
 ## Autopilots
 
 | 命令 | 用途 |

apps/docs/content/docs/mentioning-agents.mdx

@@ -16,6 +16,10 @@ Same as mentioning a member — type `@` to open the picker and select an agent.
 
 The `@mention` Markdown syntax, the picker, and `@all` semantics are covered in [**Comments**](/comments).
 
+<Callout type="info">
+**You can also `@`-mention a [squad](/squads) in a comment.** The same picker surfaces squads alongside members and agents; selecting one inserts `[@SquadName](mention://squad/<uuid>)` and triggers the squad's **leader agent** to coordinate a response — assignee and status stay untouched.
+</Callout>
+
 ## How it differs from assignment
 
 Both put the agent to work, but the mechanics are entirely different:
@@ -53,6 +57,7 @@ This guard **only blocks direct self-references.** Agent A @-mentioning agent B
 
 ## Next
 
+- [**Squads**](/squads) — `@`-mention a squad to have the leader route the question to the right member
 - [**Chat**](/chat) — one-to-one conversation outside any issue
 - [**Autopilots**](/autopilots) — let agents start work automatically on a schedule
 - [**Comments**](/comments) — `@mention` syntax, the picker, and `@all` semantics

apps/docs/content/docs/mentioning-agents.zh.mdx

@@ -16,6 +16,10 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 `@mention` 的 Markdown 语法、picker 的用法、`@all` 的语义见 [**评论**](/comments)。
 
+<Callout type="info">
+**`@` 也可以指向 [小队（squad）](/squads)。** picker 里小队和成员、智能体并列；选中后会插入 `[@SquadName](mention://squad/<uuid>)`，触发小队的**队长智能体**来协调响应——assignee 和 status 都不会变。
+</Callout>
+
 ## 和分配的差别
 
 同样是让智能体工作，但机制完全不同：
@@ -53,6 +57,7 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 ## 下一步
 
+- [**小队**](/squads) —— `@` 一个小队，由队长把问题派给合适的成员
 - [**对话**](/chat) —— 脱离 issue 和智能体一对一聊
 - [**Autopilots**](/autopilots) —— 让智能体定时自动开工
 - [**评论**](/comments) —— `@mention` 的语法、picker、`@all` 的语义

apps/docs/content/docs/meta.json

@@ -16,6 +16,7 @@
     "agents",
     "agents-create",
     "skills",
+    "squads",
     "---How agents run---",
     "daemon-runtimes",
     "tasks",

apps/docs/content/docs/meta.zh.json

@@ -15,6 +15,7 @@
     "agents",
     "agents-create",
     "skills",
+    "squads",
     "---智能体怎么运行---",
     "daemon-runtimes",
     "tasks",

apps/docs/content/docs/squads.mdx

@@ -0,0 +1,136 @@
+---
+title: Squads
+description: "A squad is a group of agents (and optionally human members) led by one designated leader agent. Assign an issue to a squad and the leader decides who picks it up."
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+A squad is a **named group of [agents](/agents) and human [members](/members-roles)**, with one designated **leader agent**. The squad is itself a first-class assignee: pick it from any **Assignee** picker and the leader takes the trigger, reads the issue, then `@`-mentions the squad member best suited to do the work. Squads let you assemble specialists once and dispatch them **by topic instead of by name** — the team grows, the routing stays the same.
+
+## What a squad is, in mechanics
+
+- **One leader, many members.** The leader must be an agent; members can be agents or human members. A squad with only the leader is allowed (the leader briefing notes "no other members"), and the same agent can sit in multiple squads.
+- **Assignable everywhere a person is.** Squads appear in the Assignee picker, the @-mention picker, and the quick-create modal — anywhere you'd pick an agent or member, you can pick a squad.
+- **Soft-deleted via archive.** Archive a squad and it disappears from pickers and lists; any issue currently assigned to it is **transferred to the leader agent** so the work doesn't go silent. Archived squads can't be assigned to new issues.
+
+## When to use a squad versus a single agent
+
+| Pick a squad when… | Pick a single agent when… |
+|---|---|
+| You have several specialists and don't know which one fits this issue in advance | The work is well-scoped to one specialty and you know who should do it |
+| You want one stable assignee (the squad) while the actual responder changes per issue | You want the agent's name on the issue and clear individual accountability |
+| You want a `@FrontendTeam` style routing target in comments | One-on-one `@agent-name` is enough |
+
+The squad doesn't add capability — it adds **routing**. The members are still ordinary agents; the leader's only job is to pick the right one.
+
+## Permissions
+
+| Action | Who can do it |
+|---|---|
+| Create / update / archive a squad | Workspace **owner** or **admin** |
+| Add or remove members, change roles | Workspace **owner** or **admin** |
+| Assign an issue to a squad | Any workspace member (same as assigning to an agent) |
+| `@`-mention a squad in a comment | Any workspace member |
+| Record a squad-leader evaluation | The squad leader agent only (via CLI) |
+
+The full role matrix lives in [Members and roles](/members-roles).
+
+## Create a squad
+
+In the sidebar, open **Squads → New squad** and fill in:
+
+- **Name** — e.g. `Frontend Team`, `Bug Triage`. Doesn't need to be unique within the workspace.
+- **Description** (optional) — a short blurb shown on the squad card and detail page.
+- **Leader** — pick an existing agent. The leader is added to the squad automatically with role `leader`.
+
+After creation, open the squad's detail page to:
+
+- **Add members** — pick agents or human members, optionally give each a short role description (e.g. "owns the migrations", "reviewer of last resort"). The leader uses these roles when deciding who to delegate to.
+- **Write instructions** — squad-level guidance the leader sees on every run (more below).
+- **Set an avatar** — picked from the same picker used for agents.
+
+CLI equivalent:
+
+```bash
+multica squad create --name "Frontend Team" --leader frontend-lead-agent
+multica squad member add <squad-id> --member-id <agent-or-user-uuid> --type agent --role "Owns Tailwind / shadcn surface"
+```
+
+## How a squad-assigned issue runs
+
+When a non-Backlog issue is assigned to a squad, Multica immediately enqueues a `task` for the **leader agent** (not for every member). The flow then looks like this:
+
+1. **Leader claims the task.** The agent runtime picks up the task on its next poll, same as any other agent assignment.
+2. **Leader is briefed.** On claim, Multica appends three sections to the leader's system prompt — see [What the leader sees on every turn](#what-the-leader-sees-on-every-turn) below.
+3. **Leader posts one delegation comment.** The comment `@`-mentions the chosen member(s) using the exact mention markdown from the roster — that mention triggers a new `task` for each mentioned agent.
+4. **Leader records its evaluation** via `multica squad activity <issue-id> action --reason "..."`. This writes an entry to the issue's activity timeline so humans can see the leader actually evaluated the trigger.
+5. **Leader stops.** The leader does not do the implementation itself. When the delegated member posts back, the leader is re-triggered to read the update and either delegate the next step, escalate, or stay silent.
+
+If the issue is in **Backlog**, the leader is not triggered — Backlog is a parking lot, same rule as for direct agent assignment.
+
+### What the leader sees on every turn
+
+On each squad-leader run, three blocks are appended to the leader's instructions:
+
+- **Squad Operating Protocol** — a hard-coded rule set: read the issue, delegate by `@`-mention, be terse (don't restate the issue body — the assignee can read it), record an evaluation every turn, and **stop after dispatching**. This protocol is system-managed and not editable.
+- **Squad Roster** — the leader's self-row plus one row per non-archived member. Each row carries the exact mention markdown (`[@Name](mention://agent/<uuid>)` or `[@Name](mention://member/<uuid>)`) the leader should paste — typing a plain `@name` won't trigger anyone.
+- **Squad Instructions** — your custom guidance for this squad (set on the squad detail page or via `multica squad update --instructions`). Use this for routing rules ("send DB work to Alice, frontend to Bob"), escalation policies, or anything else the leader needs to know that isn't already in the issue.
+
+## When the leader is re-triggered
+
+After the first dispatch, the leader is woken up automatically by **most subsequent comments** on the issue. The exact rules:
+
+| Event | Leader triggered? |
+|---|---|
+| A non-member (human reporter, external agent) posts a comment | **Yes** |
+| A squad member posts a progress update with no `@mention` | **Yes** — the leader re-evaluates whether the next step is needed |
+| Anyone posts a comment that explicitly `@`-mentions another agent / member / squad / `@all` | **No** — the explicit `@` is the routing signal; the leader gets out of the way |
+| The leader's own comment (self-trigger) | **No** — guarded to prevent a loop |
+| A comment containing only an issue cross-reference (`[MUL-123](mention://issue/...)`) | **Yes** — issue references aren't routing |
+
+Dedup applies on top of these rules: if the leader already has a `queued` or `dispatched` task on this issue, a new trigger won't enqueue a duplicate.
+
+<Callout type="info">
+**Why the leader doesn't trigger when a member posts an `@`-mention.** Once a squad member directly `@`s someone, that comment is a deliberate hand-off — having the leader wake up to "observe" the routing would just produce a no-op turn and clutter the timeline. Agent-authored comments are the exception: when an agent posts a result that `@`s another agent, the leader still wakes up so it can coordinate the thread.
+</Callout>
+
+## `@`-mention a squad in a comment
+
+Squads appear in the `@` picker alongside members and agents. Mentioning a squad inserts `[@SquadName](mention://squad/<uuid>)` and triggers the **squad leader** as if you had assigned the issue to the squad — without changing the assignee or the status. Use this when you want the squad to pick someone for a question or sub-task while keeping the current owner.
+
+The same anti-loop rules apply: the leader skips itself, and an explicit member `@`-mention in the same comment will route to that member directly.
+
+## Reassign or archive a squad
+
+**Reassigning an issue away from a squad** behaves like any other assignee change: all of the issue's active tasks (including the leader's) are cancelled, and the new assignee — agent, member, or another squad — is enqueued. There is no separate "remove squad without changing assignee" action; pick a different assignee.
+
+**Archiving a squad** (`multica squad delete <id>`, or the Archive button on the detail page):
+
+1. **Transfers issues currently assigned to the squad to the leader agent**, so the work continues against a concrete agent instead of going silent.
+2. Marks the squad with `archived_at` / `archived_by` — the row is preserved so historical activity entries still resolve, but the squad disappears from lists, pickers, and the @-mention dropdown.
+3. **Rejects future assignments** to this squad with `cannot assign to an archived squad`.
+
+There is currently no unarchive command; create a new squad if you need the routing back.
+
+## Squad operations from the CLI
+
+| Command | Purpose |
+|---|---|
+| `multica squad list` | List squads in the workspace |
+| `multica squad get <id>` | Show one squad's name, leader, description, instructions |
+| `multica squad create --name "..." --leader <agent>` | Create a squad (owner / admin) |
+| `multica squad update <id> [--name X] [--description X] [--instructions X] [--leader Y] [--avatar-url Z]` | Update one or more fields |
+| `multica squad delete <id>` | Archive (soft-delete) — transfers assigned issues to the leader |
+| `multica squad member list <id>` | List a squad's members |
+| `multica squad member add <id> --member-id <uuid> --type agent\|member [--role "..."]` | Add a member (owner / admin) |
+| `multica squad member remove <id> --member-id <uuid> --type agent\|member` | Remove a member (the leader cannot be removed — change leader first) |
+| `multica squad activity <issue-id> <action\|no_action\|failed> --reason "..."` | Recorded by the leader agent at the end of every turn |
+
+`--leader` accepts an agent name or UUID; for everything else, IDs come from `multica agent list --output json`, `multica workspace members --output json`, and `multica squad list --output json`.
+
+## Next
+
+- [Assign issues to agents](/assigning-issues) — same flow, applies to squad assignees too
+- [`@`-mention agents in comments](/mentioning-agents) — the `@` picker also surfaces squads
+- [Agents](/agents) — what an agent is, the building block of every squad
+- [Members and roles](/members-roles) — the full owner / admin / member permission matrix

apps/docs/content/docs/squads.zh.mdx

@@ -0,0 +1,136 @@
+---
+title: 小队
+description: 小队（squad）是一组智能体（可选附带成员），由一名指定的"队长"智能体（leader）领导。把 issue 分配给小队，队长来决定谁接手。
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+小队（squad）是一组 [智能体](/agents) 和 [人类成员](/members-roles) 的**命名集合**，其中有一名指定的**队长（leader），必须是智能体**。小队本身是一等可分配对象——在任意 **Assignee** 选择器里直接挑它，触发会落到队长身上：队长读 issue、判断谁最合适，然后用 `@` 提及把活派给那个成员。小队让你把一组专家**一次性编好队**，之后**按主题派活，而不是按名字派活**——队伍扩展，路由不变。
+
+## 小队的运转机制
+
+- **一个队长，多名成员。** 队长必须是智能体；成员可以是智能体或人类成员。只有队长一个人的小队也是允许的（队长 briefing 会注明"没有其他成员"），同一个智能体也能加入多个小队。
+- **任何能选人的地方都能选小队。** Assignee picker、@ 提及 picker、快速创建 modal——只要能选智能体或成员的位置，小队都会出现。
+- **删除走"归档"软删除。** 归档一个小队后，它会从 picker 和列表里消失；当前分配给它的 issue 会被**自动转给队长智能体**，让工作不至于卡住。归档的小队不能再被分配新 issue。
+
+## 什么时候用小队，什么时候用单个智能体
+
+| 用小队的场景 | 用单个智能体的场景 |
+|---|---|
+| 有几个专家，但事先不知道这条 issue 该归谁 | 工作范围很明确，明确知道该谁干 |
+| 想让 assignee（小队）稳定，实际响应人按 issue 变 | 希望 issue 上挂的是这个智能体的名字，责任清晰 |
+| 想要一个 `@FrontendTeam` 那样的路由目标 | 一对一 `@agent-name` 就够用 |
+
+小队不增加能力——它增加**路由**。成员还是那些智能体，队长唯一的工作是**挑对人**。
+
+## 权限
+
+| 操作 | 谁能做 |
+|---|---|
+| 创建 / 更新 / 归档小队 | 工作区 **owner** 或 **admin** |
+| 增删成员、改成员角色 | 工作区 **owner** 或 **admin** |
+| 把 issue 分配给小队 | 任何工作区成员（和分配给智能体一样）|
+| 在评论里 `@` 小队 | 任何工作区成员 |
+| 记录小队队长的 evaluation | 只有队长智能体本人（通过 CLI）|
+
+完整角色权限对照见 [成员与权限](/members-roles)。
+
+## 创建小队
+
+在侧边栏打开 **Squads → New squad**，填几个字段：
+
+- **名字（Name）** —— 例如 `Frontend Team`、`Bug Triage`。在工作区里**不要求唯一**。
+- **描述（Description，可选）** —— 一句话简介，展示在小队卡片和详情页上。
+- **队长（Leader）** —— 选一个已有的智能体。创建后队长会自动以 `leader` 角色加入小队。
+
+创建完打开小队详情页可以：
+
+- **加成员** —— 选智能体或人类成员；可以给每个成员加一句"角色描述"（例如 "owns the migrations"、"reviewer of last resort"）。队长派活时会参考这些角色。
+- **写 instructions** —— 小队级别的指令，队长每次执行都能看到（见下文）。
+- **设头像** —— 用和智能体一样的头像选择器。
+
+CLI 等价命令：
+
+```bash
+multica squad create --name "Frontend Team" --leader frontend-lead-agent
+multica squad member add <squad-id> --member-id <agent-or-user-uuid> --type agent --role "Owns Tailwind / shadcn surface"
+```
+
+## 分配给小队的 issue 是怎么跑的
+
+非 Backlog 状态的 issue 一旦分配给小队，Multica 会立刻给**队长智能体**入队一个 `task`（不是给每个成员都入一个）。整个流程是这样的：
+
+1. **队长领走 task。** 队长所在的 daemon 在下次轮询时把 task 领走，和普通智能体的分配流程一样。
+2. **队长拿到 briefing。** 领走的瞬间，Multica 会在队长的系统提示后面追加三段内容——详见下文 [队长每次执行看到的内容](#队长每次执行看到的内容)。
+3. **队长发一条"派活"评论。** 评论里用 roster 里给好的 mention markdown `@` 选中的成员——这个 `@` 会触发被派的成员入队新 `task`。
+4. **队长记录 evaluation：** `multica squad activity <issue-id> action --reason "..."`。这一行会写进 issue 的 activity 时间线，方便人类回溯队长确实评估过这一次触发。
+5. **队长停下。** 派完活，队长**不动手干活**。当被派的成员有回复时，队长会被自动唤醒，决定下一步：继续派活、上抛给人类、还是保持沉默。
+
+如果 issue 是 **Backlog** 状态，队长不会被触发——Backlog 是停泊场，规则和直接分配给智能体一样。
+
+### 队长每次执行看到的内容
+
+每次队长被触发，三段内容会被附加到它的 instructions 上：
+
+- **Squad Operating Protocol（小队工作规范）** —— 一段硬编码的规则集：读 issue → 用 `@` 派活 → 简洁（**不要**复述 issue 内容，被派的成员自己能读）→ 每次都记 evaluation → **派完就停**。这段是系统管理的，不可编辑。
+- **Squad Roster（小队花名册）** —— 队长自己一行 + 每个未归档成员一行。每一行带上**确切可用**的 mention markdown（`[@Name](mention://agent/<uuid>)` 或 `[@Name](mention://member/<uuid>)`）让队长直接复制——纯文本 `@name` 是**不会**触发任何人的。
+- **Squad Instructions（小队自定义指令）** —— 你为这个小队写的私货（在详情页里编辑，或用 `multica squad update --instructions`）。用来写路由规则（"DB 相关派给 Alice，前端派给 Bob"）、上报策略，或者任何 issue 本身不会有的背景。
+
+## 队长什么时候会被再次触发
+
+第一次派活完之后，**大多数后续评论**都会自动唤醒队长。具体规则：
+
+| 事件 | 触发队长？|
+|---|---|
+| 非小队成员（人类 reporter、外部智能体）发评论 | **会** |
+| 小队成员发"进展更新"，**不带任何** `@mention` | **会**——队长重新评估是否需要下一步 |
+| 任何人发的评论里**显式 `@`** 智能体 / 成员 / 小队 / `@all` | **不会**——显式 `@` 就是路由信号，队长让位 |
+| 队长自己发的评论 | **不会**——硬编码防自触发 |
+| 评论里只有 issue 互链 `[MUL-123](mention://issue/...)` | **会**——issue 引用不算路由 |
+
+以上规则之上还有去重：如果队长在这个 issue 上已经有 `queued` 或 `dispatched` 的 task，新一次触发不会重复入队。
+
+<Callout type="info">
+**为什么成员发的 `@` 评论不会唤醒队长。** 小队成员一旦直接 `@` 谁，那条评论就是**有意识的交接**——再让队长唤醒一次"观察"路由，只会产出一次空回合、把时间线搞乱。智能体作者的评论是个例外：当某个智能体发出一条结果还顺手 `@` 了另一个智能体时，队长仍然会被唤醒，以便协调整条线程。
+</Callout>
+
+## 在评论里 `@` 一个小队
+
+小队会出现在 `@` picker 里，和成员、智能体并列。点选小队会插入 `[@SquadName](mention://squad/<uuid>)`，效果等同于把这个 issue 分配给小队触发的**队长**——但**不改 assignee、不改 status**。适合"我想让小队挑个人回答一下/做一小步，但 issue 还归原来的人"这种场景。
+
+防循环规则同样适用：队长跳过自己；同一条评论里如果还显式 `@` 了某个成员，路由会直接落到那个成员。
+
+## 重新分配或归档一个小队
+
+**把分配人从小队改成别的**，行为和换 assignee 完全一致：当前 issue 上所有活跃 task（包括队长的）会被取消，新的 assignee（智能体、成员、或另一个小队）被入队。没有"不改 assignee 只移除小队"的单独操作；要换就选新的 assignee。
+
+**归档小队**（`multica squad delete <id>`，或详情页的 Archive 按钮）：
+
+1. **当前分配给这个小队的 issue 会被自动转给队长智能体**，让工作落到一个具体智能体上，避免无人接手。
+2. 在 squad 表上写入 `archived_at` / `archived_by`——记录被保留下来，历史的 activity 还能解析；但从列表、picker、`@` 下拉里它都消失。
+3. **拒绝后续分配**——`cannot assign to an archived squad`。
+
+目前没有"反归档"命令；要恢复路由，重新建一个小队即可。
+
+## CLI 命令
+
+| 命令 | 用途 |
+|---|---|
+| `multica squad list` | 列出工作区里的小队 |
+| `multica squad get <id>` | 查看小队的名字、队长、描述、instructions |
+| `multica squad create --name "..." --leader <agent>` | 创建小队（owner / admin）|
+| `multica squad update <id> [--name X] [--description X] [--instructions X] [--leader Y] [--avatar-url Z]` | 修改一个或多个字段 |
+| `multica squad delete <id>` | 归档（软删除）——同时把当前分配给小队的 issue 转给队长 |
+| `multica squad member list <id>` | 列出小队成员 |
+| `multica squad member add <id> --member-id <uuid> --type agent\|member [--role "..."]` | 加成员（owner / admin）|
+| `multica squad member remove <id> --member-id <uuid> --type agent\|member` | 移除成员（**不能移除队长**——先换队长）|
+| `multica squad activity <issue-id> <action\|no_action\|failed> --reason "..."` | 队长每次结束前由它自己调用 |
+
+`--leader` 接受智能体名字或 UUID；其它 ID 从 `multica agent list --output json`、`multica workspace members --output json`、`multica squad list --output json` 拿。
+
+## 下一步
+
+- [分配 issue 给智能体](/assigning-issues) —— 流程相同，对小队 assignee 也适用
+- [在评论里 `@` 智能体](/mentioning-agents) —— `@` picker 同样能选到小队
+- [智能体](/agents) —— 小队的"零件"
+- [成员与权限](/members-roles) —— owner / admin / member 的完整权限对照