docs(changelog): add May 14 release notes (#2610)

* docs(changelog): add 2026-05-14 release notes

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

* docs(changelog): update May 14 release notes

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

---------

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

.env.example

@@ -101,6 +101,13 @@ ALLOWED_ORIGINS=
 # `Authorization: Bearer <token>`.
 # REALTIME_METRICS_TOKEN=
 
+# GitHub App integration (Settings → Integrations "Connect GitHub")
+# Both must be set for the Connect button to enable and for webhooks to be
+# accepted; leave empty to disable the integration. See docs/github-integration.
+# GITHUB_APP_SLUG is the tail of https://github.com/apps/<slug>.
+GITHUB_APP_SLUG=
+GITHUB_WEBHOOK_SECRET=
+
 # Frontend
 FRONTEND_PORT=3000
 FRONTEND_ORIGIN=http://localhost:3000
@@ -132,5 +139,8 @@ ALLOWED_EMAILS=
 # will run a no-op analytics client and ship nothing. See docs/analytics.md.
 POSTHOG_API_KEY=
 POSTHOG_HOST=https://us.i.posthog.com
+# Optional override for the `environment` PostHog event property.
+# Defaults from APP_ENV and normalizes to production / staging / dev.
+ANALYTICS_ENVIRONMENT=
 # Force the no-op client even when POSTHOG_API_KEY is set (CI / opt-out).
 ANALYTICS_DISABLED=

.github/workflows/ci.yml

@@ -29,6 +29,15 @@ jobs:
       - name: Install dependencies
         run: pnpm install
 
+      - name: Verify reserved-slugs.ts is up to date
+        # Re-runs the generator and fails on any drift from the
+        # checked-in TypeScript output. The Go side embeds the JSON
+        # source directly, so a passing diff here proves both sides
+        # share one source of truth.
+        run: |
+          pnpm generate:reserved-slugs
+          git diff --exit-code -- packages/core/paths/reserved-slugs.ts
+
       - name: Build, type check, lint, and test
         run: pnpm exec turbo build typecheck lint test --filter='!@multica/docs'
 

CLAUDE.md

@@ -146,10 +146,27 @@ make start-worktree     # Start using .env.worktree
 - Go code follows standard Go conventions (gofmt, go vet).
 - Keep comments in code **English only**.
 - Prefer existing patterns/components over introducing parallel abstractions.
-- Unless the user explicitly asks for backwards compatibility, do **not** add compatibility layers, fallback paths, dual-write logic, legacy adapters, or temporary shims.
+- Unless the user explicitly asks for backwards compatibility, do **not** add compatibility layers, fallback paths, dual-write logic, legacy adapters, or temporary shims **for internal, non-boundary code** (a function calling another function in the same package, a component reading its own state, a store helper, etc.).
+- This rule does **not** apply at API boundaries: the desktop app cannot assume the backend it talks to has the same shape as the one it was built against (older desktop installs will outlive any given server build). API response handling must follow the rules in **API Response Compatibility** below — that is a defensive boundary, not a legacy shim.
 - If a flow or API is being replaced and the product is not yet live, prefer removing the old path instead of preserving both old and new behavior.
 - Avoid broad refactors unless required by the task.
 - New global (pre-workspace) routes MUST use a single word (`/login`, `/inbox`) or a `/{noun}/{verb}` pair (`/workspaces/new`). NEVER add hyphenated word-group root routes (`/new-workspace`, `/create-team`) — they collide with common user workspace names and force endless reserved-slug audits. Reserving the noun (`workspaces`) automatically protects the entire `/workspaces/*` subtree.
+- The reserved-slug list lives in **one** place: `server/internal/handler/reserved_slugs.json`. The Go side embeds the JSON; `packages/core/paths/reserved-slugs.ts` is generated from it by `pnpm generate:reserved-slugs`. Edit the JSON, run the generator, commit both. CI re-runs the generator and fails on any drift, so a stale TS file cannot land.
+
+### API Response Compatibility
+
+The desktop app installed on a user's machine is older than any backend it talks to: a user on 0.2.26 will hit a server running 0.3.x, then 0.4.x, then beyond. Every response shape is a contract that **will** drift, and the frontend must survive drift without white-screening. Three concrete incidents already happened from violating this — #2143, #2147, #2192.
+
+When writing code that consumes an API response, follow these rules:
+
+- **Parse, don't cast.** Untyped JSON crossing the network is not `T`. Use `parseWithFallback` in `packages/core/api/schema.ts` with a `zod` schema and an explicit fallback. On validation failure it logs a warning and returns the fallback; it never throws into the UI.
+- **No bare `as` casts on response bodies.** Every endpoint method whose response is consumed by UI logic must run through a schema before returning.
+- **Optional-chain and default everywhere downstream.** Treat every field as possibly missing. Use explicit boolean checks (`=== true`) over truthy/falsy negation, which silently treats `undefined` and `null` as `false`.
+- **Don't pin a UI affordance to a single backend field.** If a button or indicator depends on exactly one boolean from the server, a backend bug deletes it. Combine signals (cursor presence, page length, etc.) so the affordance stays available in the worst case.
+- **Enum drift downgrades, not crashes.** A new server-side enum value should render a generic fallback. `switch` statements on server-driven strings must have a `default` branch.
+- **When you add or change an endpoint:** add the schema in the same PR, and write at least one test that feeds a malformed response through it (missing field, wrong type, `null` array). The test fails closed if a future change breaks the contract.
+
+This is not premature defense — it is the *only* defense for an installed-app architecture. CSR-only browser apps can ship a fix in minutes; an Electron build sitting on a developer's laptop cannot.
 
 ### Backend Handler UUID Parsing Convention
 

CLI_AND_DAEMON.md

@@ -306,10 +306,11 @@ multica issue list
 multica issue list --status in_progress
 multica issue list --priority urgent --assignee "Agent Name"
 multica issue list --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
+multica issue list --full-id
 multica issue list --limit 20 --output json
 ```
 
-Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--limit`. Use `--assignee-id <uuid>` for unambiguous filtering when names overlap.
+Table output shows a routable issue `KEY` such as `MUL-123`; copy that key into follow-up commands like `issue get`, `issue comment list`, `issue status`, or `--parent`. Add `--full-id` when you need canonical UUIDs. Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--limit`. Use `--assignee-id <uuid>` for unambiguous filtering when names overlap.
 
 ### Get Issue
 
@@ -393,17 +394,19 @@ Subscribers receive notifications about issue activity (new comments, status cha
 ```bash
 # List all execution runs for an issue
 multica issue runs <issue-id>
+multica issue runs <issue-id> --full-id
 multica issue runs <issue-id> --output json
 
 # View messages for a specific execution run
 multica issue run-messages <task-id>
+multica issue run-messages <short-task-id> --issue <issue-id>
 multica issue run-messages <task-id> --output json
 
 # Incremental fetch (only messages after a given sequence number)
 multica issue run-messages <task-id> --since 42 --output json
 ```
 
-The `runs` command shows all past and current executions for an issue, including running tasks. The `run-messages` command shows the detailed message log (tool calls, thinking, text, errors) for a single run. Use `--since` for efficient polling of in-progress runs.
+The `runs` command shows all past and current executions for an issue, including running tasks. Table output uses short task UUID prefixes by default; pass `--full-id` to print canonical task UUIDs. The `run-messages` command accepts full task UUIDs directly; copied short task prefixes must be scoped with `--issue <issue-id>` so the CLI only checks that issue's runs. It shows the detailed message log (tool calls, thinking, text, errors) for a single run. Use `--since` for efficient polling of in-progress runs.
 
 ## Projects
 
@@ -513,9 +516,12 @@ Autopilots are scheduled/triggered automations that dispatch agent tasks (either
 
 ```bash
 multica autopilot list
+multica autopilot list --full-id
 multica autopilot list --status active --output json
 ```
 
+Autopilot table IDs are short UUID prefixes; follow-up autopilot commands accept copied prefixes when they are unique in the current workspace. Use `--full-id` to print canonical UUIDs.
+
 ### Get Autopilot Details
 
 ```bash

README.md

@@ -20,7 +20,7 @@ Turn coding agents into real teammates — assign tasks, track progress, compoun
 [![CI](https://github.com/multica-ai/multica/actions/workflows/ci.yml/badge.svg)](https://github.com/multica-ai/multica/actions/workflows/ci.yml)
 [![GitHub stars](https://img.shields.io/github/stars/multica-ai/multica?style=flat)](https://github.com/multica-ai/multica/stargazers)
 
-[Website](https://multica.ai) · [Cloud](https://multica.ai/app) · [X](https://x.com/MulticaAI) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
+[Website](https://multica.ai) · [Cloud](https://multica.ai) · [X](https://x.com/MulticaAI) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
 
 **English | [简体中文](README.zh-CN.md)**
 

README.zh-CN.md

@@ -20,7 +20,7 @@
 [![CI](https://github.com/multica-ai/multica/actions/workflows/ci.yml/badge.svg)](https://github.com/multica-ai/multica/actions/workflows/ci.yml)
 [![GitHub stars](https://img.shields.io/github/stars/multica-ai/multica?style=flat)](https://github.com/multica-ai/multica/stargazers)
 
-[官网](https://multica.ai) · [云服务](https://multica.ai/app) · [X](https://x.com/MulticaAI) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
+[官网](https://multica.ai) · [云服务](https://multica.ai) · [X](https://x.com/MulticaAI) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
 
 **[English](README.md) | 简体中文**
 

SELF_HOSTING_ADVANCED.md

@@ -186,16 +186,47 @@ In production, put a reverse proxy in front of both the backend and frontend to
 
 ### Caddy (Recommended)
 
+**Single-domain layout** — frontend and backend served on the same hostname (this is what `docker-compose.selfhost.yml` defaults to):
+
+```
+multica.example.com {
+    # WebSocket route — must come before the catch-all
+    @multica_ws path /ws /ws/*
+    handle @multica_ws {
+        reverse_proxy localhost:8080 {
+            flush_interval -1
+        }
+    }
+
+    # Everything else → frontend
+    reverse_proxy localhost:3000
+}
+```
+
+**Separate-domain layout** — frontend and backend on different hostnames:
+
 ```
 app.example.com {
     reverse_proxy localhost:3000
 }
 
 api.example.com {
+    @multica_ws path /ws /ws/*
+    handle @multica_ws {
+        reverse_proxy localhost:8080 {
+            flush_interval -1
+        }
+    }
+
     reverse_proxy localhost:8080
 }
 ```
 
+Two non-obvious bits inside the `/ws` block are worth calling out — both are common reasons real-time updates "stop working" on a Caddy-fronted self-host:
+
+- **`path /ws /ws/*` (not `/ws*`)** — bare `handle /ws` is an exact match, so future path variants under `/ws/` fall through to the frontend block. The obvious shortcut `handle /ws*` overcorrects in the other direction: Caddy's `*` is a glob without a path-segment boundary, so it would also catch unrelated paths like `/ws-foo`, which is a legitimate workspace URL (only the exact slug `ws` is reserved). Listing `/ws` and `/ws/*` explicitly covers both real cases without overreach.
+- **`flush_interval -1`** — disables response buffering so WebSocket frames are forwarded as soon as they arrive. Without it, frames can sit behind Caddy's default flush window, which looks like delayed comments, missing typing indicators, or "comments only appear after a page refresh."
+
 ### Nginx
 
 ```nginx

apps/desktop/electron-builder.yml

@@ -32,6 +32,45 @@ mac:
 dmg:
   artifactName: multica-desktop-${version}-mac-${arch}.${ext}
 linux:
+  # Override the Linux executable name to avoid leaking the scoped npm
+  # package name (`@multica/desktop`) into the installed binary, the
+  # `.desktop` file, and the hicolor icon filename. Without this override
+  # electron-builder defaults `executableName` to the package `name`,
+  # which after slash-stripping becomes `@multicadesktop` — producing
+  # `/usr/share/applications/@multicadesktop.desktop`,
+  # `Icon=@multicadesktop`, and
+  # `/usr/share/icons/hicolor/*/apps/@multicadesktop.png`. The leading `@`
+  # violates the freedesktop desktop-entry naming guidance, so GNOME /
+  # Ubuntu fail to associate the running window with the `.desktop` entry
+  # and fall back to the theme's default app icon (the Settings gear on
+  # Yaru). Forcing `multica` makes every Linux identity slot agree and
+  # matches `StartupWMClass=Multica` (productName-derived).
+  executableName: multica
+  # Pin StartupWMClass to the WM_CLASS Electron emits on X11. Electron
+  # derives WM_CLASS from `app.getName()`, which reads the *packaged*
+  # ASAR's `package.json` — `productName` if present, otherwise `name`.
+  # PR #2437 assumed electron-builder.yml's productName fed app.getName()
+  # directly; it does not. With our source package.json carrying only
+  # `name: "@multica/desktop"`, packaged Electron emitted
+  # `WM_CLASS=@multica/desktop`, which broke association with this entry
+  # and reproduced #2515 on Ubuntu 0.2.31. The fix lives in two places
+  # outside this file — `productName: "Multica"` on the source
+  # package.json (so the ASAR carries it) and `app.setName("Multica")`
+  # in the production branch of `src/main/index.ts` (belt-and-braces).
+  # Keep `StartupWMClass: Multica` pinned here so any future drift in
+  # those two anchors shows up as a diff against this declaration.
+  # Verification on a real Ubuntu install: `xprop WM_CLASS` on a running
+  # window prints `Multica` for both fields.
+  desktop:
+    entry:
+      StartupWMClass: Multica
+  # Point at pre-rendered hicolor sizes. electron-builder *can* generate
+  # 16/24/32/48/64/128/256/512 from a single build/icon.png, but the
+  # auto-generation silently shipped only the 1024×1024 source in our
+  # v0.2.31 .deb (#2515 reproduces this) — leaving GNOME's hicolor lookup
+  # with no usable size and falling back to the theme default. Shipping
+  # the sizes from source removes the toolchain dependency entirely.
+  icon: build/icons
   target:
     - AppImage
     - deb

apps/desktop/eslint.config.mjs

@@ -10,10 +10,11 @@ export default [
       globals: { ...globals.node },
     },
   },
-  // Security: every renderer-controlled URL that reaches the OS shell must
-  // flow through openExternalSafely in src/main/external-url.ts (scheme
-  // allowlist). Enforce it statically so a direct shell.openExternal call
-  // cannot silently regress the protection.
+  // Security: every renderer-controlled URL that reaches the OS shell or the
+  // native download system must flow through the safe wrappers in
+  // src/main/external-url.ts (scheme allowlist). Enforce it statically so
+  // direct shell.openExternal / webContents.downloadURL calls cannot silently
+  // regress the protection.
   {
     files: ["src/main/**/*.ts"],
     rules: {
@@ -25,6 +26,12 @@ export default [
           message:
             "Do not call shell.openExternal directly. Use openExternalSafely from './external-url' so the http/https allowlist stays enforced.",
         },
+        {
+          selector:
+            "CallExpression[callee.object.property.name='webContents'][callee.property.name='downloadURL']",
+          message:
+            "Do not call webContents.downloadURL directly. Use downloadURLSafely from './external-url' so the http/https allowlist stays enforced.",
+        },
       ],
     },
   },

apps/desktop/package.json

@@ -1,5 +1,6 @@
 {
   "name": "@multica/desktop",
+  "productName": "Multica",
   "version": "0.1.0",
   "private": true,
   "description": "Multica Desktop — native desktop client for the Multica platform.",

apps/desktop/src/main/external-url.ts

@@ -1,4 +1,4 @@
-import { shell } from "electron";
+import { shell, type BrowserWindow } from "electron";
 
 // True when the URL parses and uses http/https — the only schemes we let
 // reach `shell.openExternal`. Scheme comparison is safe because the WHATWG
@@ -19,6 +19,19 @@ export function openExternalSafely(url: string): Promise<void> | void {
   return shell.openExternal(url);
 }
 
+// Canonical wrapper around webContents.downloadURL. All renderer-controlled
+// URLs that trigger a native download MUST flow through here; direct calls
+// to `webContents.downloadURL` elsewhere in the main process are banned by
+// the no-restricted-syntax rule in apps/desktop/eslint.config.mjs.
+// Reuses the same http/https allowlist as openExternalSafely.
+export function downloadURLSafely(win: BrowserWindow, url: string): void {
+  if (getHttpProtocol(url) === null) {
+    console.warn(`[security] blocked downloadURL: ${describeScheme(url)}`);
+    return;
+  }
+  win.webContents.downloadURL(url);
+}
+
 function getHttpProtocol(url: string): "http:" | "https:" | null {
   try {
     const { protocol } = new URL(url);

apps/desktop/src/main/index.ts

@@ -5,16 +5,31 @@ import { electronApp, optimizer, is } from "@electron-toolkit/utils";
 import fixPath from "fix-path";
 import { setupAutoUpdater } from "./updater";
 import { setupDaemonManager } from "./daemon-manager";
-import { openExternalSafely } from "./external-url";
+import { openExternalSafely, downloadURLSafely } from "./external-url";
 import { installContextMenu } from "./context-menu";
 import { getAppVersion } from "./app-version";
 import { loadRuntimeConfig } from "./runtime-config-loader";
 import type { RuntimeConfigResult } from "../shared/runtime-config";
 
-// Bundled icon used for dev-mode dock/taskbar branding. In production the
-// app bundle icon (from electron-builder) wins; this path is only consumed
-// by the `is.dev` branch below.
-const DEV_ICON_PATH = join(__dirname, "../../resources/icon.png");
+// Bundled icon used for dock/taskbar branding. macOS/Windows production
+// builds let the OS pick up the icon from the .app bundle / .exe resources,
+// but Linux production needs an explicit BrowserWindow `icon` — AppImage
+// direct-launch doesn't register the .desktop entry, so GNOME has no path
+// from the running window to the hicolor icon and falls back to the
+// theme default. Consumed in createWindow() (all platforms in dev, Linux
+// in prod) and the macOS dev dock branch.
+//
+// `asarUnpack: resources/**` in electron-builder.yml extracts the icon to
+// `app.asar.unpacked/`, but `__dirname` resolves into `app.asar/`. The
+// Linux native window-icon code path expects a real filesystem path
+// (unlike Electron's nativeImage loader which transparently reads from
+// asar), so swap the segment — same pattern as bundledCliPath() in
+// daemon-manager.ts. In dev `__dirname` has no `app.asar`, so the replace
+// is a no-op.
+const BUNDLED_ICON_PATH = join(__dirname, "../../resources/icon.png").replace(
+  "app.asar",
+  "app.asar.unpacked",
+);
 
 // macOS/Linux GUI launches inherit a minimal PATH from launchd that omits
 // the user's shell config (~/.zshrc, Homebrew, nvm, ~/.local/bin, etc.).
@@ -106,13 +121,39 @@ function createWindow(): void {
     trafficLightPosition: { x: 16, y: 13 },
     show: false,
     autoHideMenuBar: true,
-    // Windows/Linux pick up the window/taskbar icon from this option in
-    // dev — on macOS it's ignored (dock comes from app.dock.setIcon below).
-    ...(is.dev ? { icon: DEV_ICON_PATH } : {}),
+    // Windows/Linux pick up the window/taskbar icon from this option.
+    // On macOS it's ignored (dock comes from app.dock.setIcon below).
+    // Linux production needs this explicitly because AppImage direct-launch
+    // does not install a .desktop entry, so the WM has no other path to
+    // the bundled icon; without it Ubuntu falls back to the theme default.
+    ...(is.dev || process.platform === "linux"
+      ? { icon: BUNDLED_ICON_PATH }
+      : {}),
     webPreferences: {
       preload: join(__dirname, "../preload/index.js"),
       sandbox: false,
       webSecurity: false,
+      // Required for the Chromium PDF viewer (PDFium) to activate inside
+      // iframes — used by the attachment preview modal for application/pdf
+      // files. Default is false in Electron; without it <iframe src=*.pdf>
+      // renders blank.
+      //
+      // Security trade-off, accepted intentionally:
+      //   1. This window already runs with `webSecurity: false` + `sandbox: false`,
+      //      so `plugins: true` does NOT meaningfully widen the renderer's
+      //      attack surface beyond what is already accepted.
+      //   2. The only PDFs that reach an iframe here are signed CloudFront URLs
+      //      we ourselves issued (see useDownloadAttachment); user-supplied URLs
+      //      are routed through `setWindowOpenHandler` → `openExternalSafely` and
+      //      cannot land in this renderer.
+      //   3. Chromium's PDFium plugin is itself sandboxed inside its own process
+      //      and only handles the `application/pdf` MIME — it does not expose
+      //      Flash, Java, or other historical plugin surfaces.
+      //
+      // If we ever tighten `webSecurity` / `sandbox`, revisit this by hosting
+      // the PDF viewer in a dedicated BrowserView with `plugins: true` scoped
+      // to that view, keeping the main renderer plugin-free.
+      plugins: true,
       additionalArguments: [`--multica-locale=${systemLocale}`],
     },
   });
@@ -192,6 +233,14 @@ const DEV_APP_NAME = process.env.DESKTOP_APP_SUFFIX
 if (is.dev) {
   app.setName(DEV_APP_NAME);
   app.setPath("userData", join(app.getPath("appData"), DEV_APP_NAME));
+} else {
+  // Pin the production app name in code. Electron's Linux WM_CLASS is set
+  // from app.getName() when the first BrowserWindow is realized; the
+  // packaged ASAR's package.json `productName` already steers app.getName()
+  // to "Multica", but anchoring it here makes WM_CLASS ↔ StartupWMClass
+  // (declared in electron-builder.yml) survive a regression in
+  // productName / the build pipeline. Must run before requestSingleInstanceLock().
+  app.setName("Multica");
 }
 
 // --- Protocol registration -----------------------------------------------
@@ -251,7 +300,7 @@ if (!gotTheLock) {
     // so the Canary dev build is visually distinct from a stock Electron
     // run. `app.dock` is macOS-only — guard the call.
     if (is.dev && process.platform === "darwin" && app.dock) {
-      const icon = nativeImage.createFromPath(DEV_ICON_PATH);
+      const icon = nativeImage.createFromPath(BUNDLED_ICON_PATH);
       if (!icon.isEmpty()) app.dock.setIcon(icon);
     }
 
@@ -268,6 +317,14 @@ if (!gotTheLock) {
       return openExternalSafely(url);
     });
 
+    ipcMain.handle("file:download-url", (_event, url: string) => {
+      if (!mainWindow) {
+        console.warn("[download] ignored file:download-url — mainWindow torn down");
+        return;
+      }
+      downloadURLSafely(mainWindow, url);
+    });
+
     // Sync IPC: app version + normalized OS for preload. Sync (not invoke) so
     // preload can attach the values to `desktopAPI.appInfo` before any renderer
     // code reads them, ensuring the very first HTTP request from the renderer

apps/desktop/src/main/runtime-config-loader.test.ts

@@ -69,7 +69,7 @@ describe("loadRuntimeConfig", () => {
         schemaVersion: 1,
         apiUrl: "https://api.example.com",
         wsUrl: "wss://api.example.com/ws",
-        appUrl: "https://api.example.com",
+        appUrl: "https://example.com",
       },
     });
   });

apps/desktop/src/preload/index.d.ts

@@ -19,6 +19,9 @@ interface DesktopAPI {
   onInviteOpen: (callback: (invitationId: string) => void) => () => void;
   /** Open a URL in the default browser. */
   openExternal: (url: string) => Promise<void>;
+  /** Download a file by URL through Electron's native download system.
+   *  Shows a native save dialog. On non-desktop platforms this is undefined. */
+  downloadURL: (url: string) => Promise<void>;
   /** Hide macOS traffic lights for full-screen modals; restore when false. */
   setImmersiveMode: (immersive: boolean) => Promise<void>;
   /** Show a native OS notification for a new inbox item. */

apps/desktop/src/preload/index.ts

@@ -89,6 +89,11 @@ const desktopAPI = {
   },
   /** Open a URL in the default browser */
   openExternal: (url: string) => ipcRenderer.invoke("shell:openExternal", url),
+  /** Download a file by URL through Electron's native download system.
+   *  Shows a save dialog and saves to disk. Unlike openExternal, this
+   *  avoids browser rendering of HTML files on Linux.
+   *  On non-desktop platforms this property is undefined. */
+  downloadURL: (url: string) => ipcRenderer.invoke("file:download-url", url),
   /** Toggle immersive mode — hide macOS traffic lights for full-screen modals */
   setImmersiveMode: (immersive: boolean) =>
     ipcRenderer.invoke("window:setImmersive", immersive),

apps/desktop/src/renderer/src/pages/issue-detail-page.tsx

@@ -1,6 +1,7 @@
 import { useParams } from "react-router-dom";
 import { useQuery } from "@tanstack/react-query";
 import { IssueDetail } from "@multica/views/issues/components";
+import { ErrorBoundary } from "@multica/ui/components/common/error-boundary";
 import { useWorkspaceId } from "@multica/core/hooks";
 import { issueDetailOptions } from "@multica/core/issues/queries";
 import { useDocumentTitle } from "@/hooks/use-document-title";
@@ -13,5 +14,9 @@ export function IssueDetailPage() {
   useDocumentTitle(issue ? `${issue.identifier}: ${issue.title}` : "Issue");
 
   if (!id) return null;
-  return <IssueDetail issueId={id} />;
+  return (
+    <ErrorBoundary resetKeys={[id]}>
+      <IssueDetail issueId={id} />
+    </ErrorBoundary>
+  );
 }

apps/desktop/src/renderer/src/routes.tsx

@@ -14,13 +14,16 @@ import { AgentDetailPage } from "./pages/agent-detail-page";
 import { RuntimeDetailPage } from "./pages/runtime-detail-page";
 import { IssuesPage } from "@multica/views/issues/components";
 import { ProjectsPage } from "@multica/views/projects/components";
+import { DashboardPage } from "@multica/views/dashboard";
 import { AutopilotsPage } from "@multica/views/autopilots/components";
 import { MyIssuesPage } from "@multica/views/my-issues";
 import { SkillsPage } from "@multica/views/skills";
 import { DesktopRuntimesPage } from "./components/desktop-runtimes-page";
 import { AgentsPage } from "@multica/views/agents";
+import { SquadsPage, SquadDetailPage as SquadDetailPageView } from "@multica/views/squads/components";
 import { InboxPage } from "@multica/views/inbox";
 import { SettingsPage } from "@multica/views/settings";
+import { ErrorBoundary } from "@multica/ui/components/common/error-boundary";
 import { Download, Server } from "lucide-react";
 import { DaemonSettingsTab } from "./components/daemon-settings-tab";
 import { UpdatesSettingsTab } from "./components/updates-settings-tab";
@@ -83,7 +86,15 @@ export const appRoutes: RouteObject[] = [
         element: <WorkspaceRouteLayout />,
         children: [
           { index: true, element: <Navigate to="issues" replace /> },
-          { path: "issues", element: <IssuesPage />, handle: { title: "Issues" } },
+          {
+            path: "issues",
+            element: (
+              <ErrorBoundary>
+                <IssuesPage />
+              </ErrorBoundary>
+            ),
+            handle: { title: "Issues" },
+          },
           {
             path: "issues/:id",
             element: <IssueDetailPage />,
@@ -136,7 +147,18 @@ export const appRoutes: RouteObject[] = [
             element: <AgentDetailPage />,
             handle: { title: "Agent" },
           },
+          { path: "squads", element: <SquadsPage />, handle: { title: "Squads" } },
+          {
+            path: "squads/:id",
+            element: <SquadDetailPageView />,
+            handle: { title: "Squad" },
+          },
           { path: "inbox", element: <InboxPage />, handle: { title: "Inbox" } },
+          {
+            path: "usage",
+            element: <DashboardPage />,
+            handle: { title: "Usage" },
+          },
           {
             path: "settings",
             element: (

apps/desktop/src/renderer/src/stores/tab-store.test.ts

@@ -180,6 +180,61 @@ describe("useTabStore actions", () => {
     expect(s.byWorkspace.acme.tabs[0].id).not.toBe(onlyTabId); // fresh tab
   });
 
+  it("defers disposing the closed tab router until after the store update", () => {
+    vi.useFakeTimers();
+    try {
+      const store = useTabStore.getState();
+      store.switchWorkspace("acme");
+      const closedTabId = store.addTab("/acme/settings", "Settings", "Settings");
+      const closingTab = useTabStore
+        .getState()
+        .byWorkspace.acme.tabs.find((t) => t.id === closedTabId);
+      const dispose = vi.mocked(closingTab!.router.dispose);
+
+      store.closeTab(closedTabId);
+
+      expect(dispose).not.toHaveBeenCalled();
+      expect(
+        useTabStore.getState().byWorkspace.acme.tabs.some((t) => t.id === closedTabId),
+      ).toBe(false);
+
+      vi.runAllTimers();
+
+      expect(dispose).toHaveBeenCalledOnce();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("ignores router-sync updates from a tab after it has been closed", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    const closedTabId = store.addTab("/acme/settings", "Settings", "Settings");
+
+    store.closeTab(closedTabId);
+    const before = useTabStore.getState().byWorkspace.acme;
+
+    store.updateTab(closedTabId, { path: "/acme/runtimes", icon: "Monitor" });
+    store.updateTabHistory(closedTabId, 1, 2);
+
+    expect(useTabStore.getState().byWorkspace.acme).toBe(before);
+    expect(
+      useTabStore.getState().byWorkspace.acme.tabs.some((t) => t.id === closedTabId),
+    ).toBe(false);
+  });
+
+  it("does not replace the tab group for no-op router-sync updates", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    const tab = useTabStore.getState().byWorkspace.acme.tabs[0];
+    const before = useTabStore.getState().byWorkspace.acme;
+
+    store.updateTab(tab.id, { path: tab.path, icon: tab.icon, title: tab.title });
+    store.updateTabHistory(tab.id, tab.historyIndex, tab.historyLength);
+
+    expect(useTabStore.getState().byWorkspace.acme).toBe(before);
+  });
+
   it("validateWorkspaceSlugs drops groups for slugs not in the valid set and repoints active", () => {
     const store = useTabStore.getState();
     store.switchWorkspace("acme");

apps/desktop/src/renderer/src/stores/tab-store.ts

@@ -350,7 +350,10 @@ export const useTabStore = create<TabStore>()(
         const { slug, group, index } = hit;
 
         const closing = group.tabs[index];
-        closing.router.dispose();
+        const disposeClosingRouter = () => {
+          // Let React unmount the tab's RouterProvider before disposing it.
+          window.setTimeout(() => closing.router.dispose(), 0);
+        };
 
         if (group.tabs.length === 1) {
           // Last tab in this workspace — reseed a default so the workspace
@@ -363,6 +366,7 @@ export const useTabStore = create<TabStore>()(
               [slug]: { tabs: [fresh], activeTabId: fresh.id },
             },
           });
+          disposeClosingRouter();
           return;
         }
 
@@ -378,6 +382,7 @@ export const useTabStore = create<TabStore>()(
             [slug]: { tabs: nextTabs, activeTabId: nextActiveTabId },
           },
         });
+        disposeClosingRouter();
       },
 
       setActiveTab(tabId) {
@@ -402,6 +407,13 @@ export const useTabStore = create<TabStore>()(
         const { slug, group, index } = hit;
         const current = group.tabs[index];
         const next: Tab = { ...current, ...patch };
+        if (
+          next.path === current.path &&
+          next.title === current.title &&
+          next.icon === current.icon
+        ) {
+          return;
+        }
         const nextTabs = [...group.tabs];
         nextTabs[index] = next;
         set({
@@ -418,6 +430,12 @@ export const useTabStore = create<TabStore>()(
         if (!hit) return;
         const { slug, group, index } = hit;
         const current = group.tabs[index];
+        if (
+          current.historyIndex === historyIndex &&
+          current.historyLength === historyLength
+        ) {
+          return;
+        }
         const next: Tab = { ...current, historyIndex, historyLength };
         const nextTabs = [...group.tabs];
         nextTabs[index] = next;

apps/desktop/src/shared/runtime-config.test.ts

@@ -32,6 +32,19 @@ describe("runtime config", () => {
     });
   });
 
+  it("strips the leading api. label when deriving appUrl", () => {
+    expect(
+      parseRuntimeConfig(
+        JSON.stringify({ schemaVersion: 1, apiUrl: "https://api.multica.ai" }),
+      ),
+    ).toEqual({
+      schemaVersion: 1,
+      apiUrl: "https://api.multica.ai",
+      wsUrl: "wss://api.multica.ai/ws",
+      appUrl: "https://multica.ai",
+    });
+  });
+
   it("derives ws for http api URLs", () => {
     expect(deriveWsUrl("http://localhost:8080")).toBe("ws://localhost:8080/ws");
   });
@@ -96,4 +109,43 @@ describe("runtime config", () => {
       appUrl: "http://dev-app.example.test:3000",
     });
   });
+
+  it("falls back to local web URL when dev apiUrl is localhost", () => {
+    expect(runtimeConfigFromDevEnv({ apiUrl: "http://localhost:8080" })).toEqual({
+      schemaVersion: 1,
+      apiUrl: "http://localhost:8080",
+      wsUrl: "ws://localhost:8080/ws",
+      appUrl: "http://localhost:3000",
+    });
+  });
+
+  it("derives dev appUrl by stripping the leading api. label", () => {
+    // When the dev renderer is pointed at a remote backend (e.g. a test
+    // environment), copy-link / share URLs must reflect that environment's
+    // public web host, not the api host. Multica's convention exposes the
+    // api at `api.<web-host>`, so stripping the leading label gives the
+    // right web origin without a separate VITE_APP_URL.
+    expect(
+      runtimeConfigFromDevEnv({ apiUrl: "https://api.test.multica.ai" }),
+    ).toEqual({
+      schemaVersion: 1,
+      apiUrl: "https://api.test.multica.ai",
+      wsUrl: "wss://api.test.multica.ai/ws",
+      appUrl: "https://test.multica.ai",
+    });
+  });
+
+  it("dev VITE_APP_URL still wins over apiUrl-derived value", () => {
+    expect(
+      runtimeConfigFromDevEnv({
+        apiUrl: "https://api.test.multica.ai",
+        appUrl: "https://staging.multica.ai",
+      }),
+    ).toEqual({
+      schemaVersion: 1,
+      apiUrl: "https://api.test.multica.ai",
+      wsUrl: "wss://api.test.multica.ai/ws",
+      appUrl: "https://staging.multica.ai",
+    });
+  });
 });

apps/desktop/src/shared/runtime-config.ts

@@ -44,10 +44,9 @@ export function runtimeConfigFromDevEnv(env: RuntimeConfigEnv): RuntimeConfig {
     wsUrl: env.wsUrl
       ? normalizeWsUrl(env.wsUrl, "VITE_WS_URL")
       : deriveWsUrl(apiUrl),
-    appUrl: normalizeHttpUrl(
-      env.appUrl || LOCAL_DEV_RUNTIME_CONFIG.appUrl,
-      "VITE_APP_URL",
-    ),
+    appUrl: env.appUrl
+      ? normalizeHttpUrl(env.appUrl, "VITE_APP_URL")
+      : deriveDevAppUrl(apiUrl),
   };
 }
 
@@ -94,14 +93,37 @@ export function deriveWsUrl(apiUrl: string): string {
   return trimTrailingSlash(url.toString());
 }
 
+// Convention: api hosts are exposed at `api.<web-host>` (api.multica.ai →
+// multica.ai, api.test.multica.ai → test.multica.ai). Strip the leading
+// `api.` label so a single `apiUrl` configuration produces the right
+// shareable web URL. Hosts that don't match the convention (no leading
+// `api.` label, or short two-label hosts like `api.local`) fall through
+// untouched — those deployments must set `appUrl` explicitly.
 export function deriveAppUrl(apiUrl: string): string {
   const url = new URL(apiUrl);
   url.pathname = "";
   url.search = "";
   url.hash = "";
+  if (url.hostname.startsWith("api.") && url.hostname.split(".").length >= 3) {
+    url.hostname = url.hostname.slice("api.".length);
+  }
   return trimTrailingSlash(url.toString());
 }
 
+// Dev variant: when the api host is the local backend (`localhost:8080` /
+// `127.0.0.1:8080`), the renderer is served from a different port (3000),
+// so deriving by host alone is wrong. Fall back to the local dev web URL
+// in that case; for any non-local host (e.g. a remote test environment),
+// trust the production-style derivation so `apiUrl=https://api.test.x`
+// yields `appUrl=https://test.x` without a separate VITE_APP_URL.
+export function deriveDevAppUrl(apiUrl: string): string {
+  const url = new URL(apiUrl);
+  if (url.hostname === "localhost" || url.hostname === "127.0.0.1") {
+    return LOCAL_DEV_RUNTIME_CONFIG.appUrl;
+  }
+  return deriveAppUrl(apiUrl);
+}
+
 function requiredString(value: unknown, field: string): string {
   if (typeof value !== "string" || value.trim().length === 0) {
     throw new Error(`Invalid desktop runtime config: ${field} must be a non-empty string`);

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/autopilots.mdx

@@ -25,10 +25,6 @@ An autopilot has two execution modes. **Start with "create issue" mode.**
 - **Create issue mode** (`create_issue`) — default, **recommended**. Each trigger first creates an issue in the workspace (the title supports interpolation like `{{date}}`), then assigns the issue to the agent through the normal assignment flow. All work lands on the issue board with the same history, comments, and status as a manually assigned issue.
 - **Run-only mode** (`run_only`) — skips issue creation and enqueues a `task` directly. The run is invisible on the board — you can only see it in the autopilot's run history.
 
-<Callout type="warning">
-**Run-only mode is currently unstable.** The CLI labels it "not yet supported end-to-end," and the dispatch path has known issues. New users should stick to create issue mode and wait for run-only mode to ship a stable release before switching.
-</Callout>
-
 ## Run it on a schedule
 
 Every autopilot needs at least one `schedule` trigger. Cron uses the **standard 5-field format** (minute hour day month weekday), with **1-minute** minimum granularity (no seconds). Timezone is IANA-formatted (for example, `Asia/Shanghai`) and determines which timezone the cron expression is interpreted in.

apps/docs/content/docs/autopilots.zh.mdx

@@ -25,10 +25,6 @@ Autopilot 有两种执行模式，**建议从"先建 issue 模式"开始**：
 - **先建 issue 模式**（`create_issue`）—— 默认，**推荐**。每次触发先在工作区里建一个 issue（标题支持 `{{date}}` 这样的插值），再按分配流程把 issue 派给智能体。所有工作都落在 issue 看板上，历史、评论、状态和手动分配的 issue 完全一致。
 - **直跑模式**（`run_only`）—— 不建 issue，直接入队一个 `task`。看板上看不到这一次运行——只能在 Autopilot 的运行历史里看到。
 
-<Callout type="warning">
-**直跑模式当前不稳定**——目前在 CLI 里被标注为"not yet supported end-to-end"，派发路径有已知问题。新用户只使用先建 issue 模式，等直跑模式 ship 稳定版再切。
-</Callout>
-
 ## 让它按时间跑
 
 每个 Autopilot 至少要一个 `schedule` 触发器。Cron 是**标准 5 字段格式**（分 时 日 月 周），最小粒度 **1 分钟**（没有秒级）。时区用 IANA 格式（例如 `Asia/Shanghai`），决定 cron 表达式按哪个时区解读。

apps/docs/content/docs/cli.mdx

@@ -44,17 +44,21 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 
 ## Issues and projects
 
+<Callout type="info">
+`list` commands (`multica issue list`, `autopilot list`, `project list`, etc.) print short, copy-paste-ready IDs by default — issue keys like `MUL-123` for issues, short UUID prefixes for the rest. The `<id>` argument on the follow-up commands below accepts either the short ID or the full UUID, so the typical flow is `multica issue list` → copy the key → `multica issue get MUL-123`. Pass `--full-id` to a list command when you need the canonical UUID.
+</Callout>
+
 | Command | Purpose |
 |---|---|
-| `multica issue list` | List issues |
-| `multica issue get <id>` | Show a single issue |
+| `multica issue list` | List issues (prints copy-paste-ready issue keys) |
+| `multica issue get <id>` | Show a single issue (accepts an issue key or a UUID) |
 | `multica issue create --title "..."` | Create a new issue |
 | `multica issue update <id> ...` | Update an issue (status, priority, assignee, etc.) |
 | `multica issue assign <id> --agent <slug>` | Assign to an agent (triggers a task immediately) |
 | `multica issue status <id> --set <status>` | Shortcut to change status |
 | `multica issue search <query>` | Keyword search |
 | `multica issue runs <id>` | Show agent runs on an issue |
-| `multica issue rerun <id>` | Rerun the most recent agent task |
+| `multica issue rerun <id>` | Re-enqueue a fresh task for the issue's current agent assignee |
 | `multica issue comment <id> ...` | Nested: view / post comments |
 | `multica issue subscriber <id> ...` | Nested: subscribe / unsubscribe |
 | `multica project list/get/create/update/delete/status` | Project CRUD |
@@ -75,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 |
@@ -99,7 +117,6 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 | `multica runtime list` | List runtimes in the current workspace |
 | `multica runtime usage` | Show resource usage |
 | `multica runtime activity` | Recent activity log |
-| `multica runtime ping <id>` | Ping a runtime to check it's online |
 | `multica runtime update <id> ...` | Update a runtime's configuration |
 
 ## Miscellaneous

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

@@ -44,17 +44,21 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 
 ## Issue 和 Project
 
+<Callout type="info">
+`list` 类命令（`multica issue list`、`autopilot list`、`project list` 等）表格里默认显示**可直接复制**的短 ID：issue 是 key（如 `MUL-123`），其余资源是 UUID 短前缀。下面表格里的 `<id>` 同时接受短 ID 和完整 UUID，所以典型用法是 `multica issue list` → 复制 key → `multica issue get MUL-123`。需要完整 UUID 时给 `list` 加 `--full-id`。
+</Callout>
+
 | 命令 | 用途 |
 |---|---|
-| `multica issue list` | 列出 issue |
-| `multica issue get <id>` | 查看单条 issue |
+| `multica issue list` | 列出 issue（默认显示可复制的 issue key） |
+| `multica issue get <id>` | 查看单条 issue（接受 issue key 或 UUID） |
 | `multica issue create --title "..."` | 创建新 issue |
 | `multica issue update <id> ...` | 修改 issue（状态、优先级、分配人等） |
 | `multica issue assign <id> --agent <slug>` | 分配给智能体（立即触发任务） |
 | `multica issue status <id> --set <status>` | 快捷改状态 |
 | `multica issue search <query>` | 关键字搜索 |
 | `multica issue runs <id>` | 查看 issue 上智能体跑过的任务 |
-| `multica issue rerun <id>` | 重跑最近一次智能体任务 |
+| `multica issue rerun <id>` | 给该 issue 当前的智能体分配人重新创建一条任务 |
 | `multica issue comment <id> ...` | 嵌套：看 / 发评论 |
 | `multica issue subscriber <id> ...` | 嵌套：订阅 / 取消订阅 |
 | `multica project list/get/create/update/delete/status` | Project CRUD |
@@ -75,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
 
 | 命令 | 用途 |
@@ -99,7 +117,6 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 | `multica runtime list` | 列出当前工作区的 runtime |
 | `multica runtime usage` | 查看资源使用情况 |
 | `multica runtime activity` | 近期活动记录 |
-| `multica runtime ping <id>` | 立即戳一次 runtime 检查在线 |
 | `multica runtime update <id> ...` | 更新 runtime 配置 |
 
 ## 杂项

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

@@ -244,18 +244,22 @@ multica issue list
 multica issue list --status in_progress
 multica issue list --priority urgent --assignee "Agent Name"
 multica issue list --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
+multica issue list --full-id
 multica issue list --limit 20 --output json
 ```
 
-Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--limit`. 在重名 workspace 下用 `--assignee-id <uuid>` 可以精确锁定一个成员或 agent。
+表格输出默认显示可直接复制到后续命令的 issue `KEY`（例如 `MUL-123`）；需要完整 UUID 时使用 `--full-id`。Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--limit`. 在重名 workspace 下用 `--assignee-id <uuid>` 可以精确锁定一个成员或 agent。
 
 ### Get Issue
 
 ```bash
-multica issue get <id>
+multica issue get MUL-123
+multica issue get <uuid>
 multica issue get <id> --output json
 ```
 
+`<id>` 同时接受 issue key（`multica issue list` 表格里直接显示，例如 `MUL-123`）和完整 UUID（给 `list` 加 `--full-id` 可显示）。同样的规则适用于下面 `update` / `assign` / `status` / `comment` / `subscriber` / `runs` 等接受 `<id>` 的命令。
+
 ### Create Issue
 
 ```bash
@@ -310,16 +314,20 @@ multica issue comment delete <comment-id>
 ```bash
 # List all execution runs for an issue
 multica issue runs <issue-id>
+multica issue runs <issue-id> --full-id
 multica issue runs <issue-id> --output json
 
 # View messages for a specific execution run
 multica issue run-messages <task-id>
+multica issue run-messages <short-task-id> --issue <issue-id>
 multica issue run-messages <task-id> --output json
 
 # Incremental fetch (only messages after a given sequence number)
 multica issue run-messages <task-id> --since 42 --output json
 ```
 
+`runs` 的表格输出默认显示 task UUID 短前缀；需要完整 task UUID 时使用 `--full-id`。`run-messages` 可直接接受完整 task UUID；从 `runs` 表格复制短前缀时需要同时传 `--issue <issue-id>`，CLI 只会在该 issue 的 runs 内解析。
+
 ## Projects
 
 Projects group related issues (e.g. a sprint, an epic, a workstream). Every project

apps/docs/content/docs/developers/conventions.mdx

@@ -160,6 +160,7 @@ Chinese term reference:
 | Confirm / Continue / Back | 确认 / 继续 / 返回 |
 | Edit / New / Create / Add | 编辑 / 新建 / 创建 / 添加 |
 | Remove / Send / Open / Close | 移除 / 发送 / 打开 / 关闭 |
+| Preview / Download / Upload | 预览 / 下载 / 上传 |
 | Done / Loading... | 完成 / 加载中... |
 | Profile / Account / Appearance | 个人资料 / 账号 / 外观 |
 | Theme / Language | 主题 / 语言 |

apps/docs/content/docs/developers/conventions.zh.mdx

@@ -160,6 +160,7 @@ Multica 的产品名词分两类：
 | Confirm / Continue / Back | 确认 / 继续 / 返回 |
 | Edit / New / Create / Add | 编辑 / 新建 / 创建 / 添加 |
 | Remove / Send / Open / Close | 移除 / 发送 / 打开 / 关闭 |
+| Preview / Download / Upload | 预览 / 下载 / 上传 |
 | Done / Loading... | 完成 / 加载中... |
 | Profile / Account / Appearance | 个人资料 / 账号 / 外观 |
 | Theme / Language | 主题 / 语言 |

apps/docs/content/docs/environment-variables.mdx

@@ -141,6 +141,22 @@ For a full explanation of how each parameter affects daemon behavior, see [Daemo
 **Leaving `FRONTEND_ORIGIN` unset creates two silent failures**: (1) invite email links point at `https://app.multica.ai` (the hosted domain), and clicking them doesn't bring users back to your self-hosted instance; (2) WebSocket Origin checks fall back to `localhost:3000 / 5173 / 5174`, so every WebSocket connection in a production deployment is rejected and the frontend appears to "lose real-time updates."
 </Callout>
 
+## GitHub integration
+
+The [GitHub PR ↔ issue integration](/github-integration) needs two variables. Set both to enable Connect GitHub in Settings and accept incoming webhooks.
+
+| Variable | Default | Description |
+|---|---|---|
+| `GITHUB_APP_SLUG` | empty | The slug of your GitHub App (the tail of `https://github.com/apps/<slug>`). Drives the Settings → Integrations install button URL |
+| `GITHUB_WEBHOOK_SECRET` | empty | The Webhook secret you set on the GitHub App. Used for HMAC-SHA256 verification of every `pull_request` / `installation` delivery, and as the HMAC key for the setup-callback state token |
+
+**Behavior when either is unset:**
+
+- `Connect GitHub` in Settings → Integrations is **disabled** and shows a "not configured" hint to admins.
+- The `/api/webhooks/github` endpoint returns **`503 github webhooks not configured`** — Multica refuses to process events with no secret rather than treating every signature as valid.
+
+**Note:** `GITHUB_WEBHOOK_SECRET` is reused as the signing key for the install-flow state token, so operators only need to manage one secret. It is **not** the GitHub App's *Client* secret — Client secrets are OAuth-related and not used by this integration. See [GitHub integration → Self-host setup](/github-integration#self-host-setup) for the full walkthrough.
+
 ## Usage analytics
 
 By default, the server reports to Multica's official PostHog instance. To opt out, set `ANALYTICS_DISABLED=true`.
@@ -154,5 +170,6 @@ By default, the server reports to Multica's official PostHog instance. To opt ou
 ## Next
 
 - [Sign-in and signup configuration](/auth-setup) — how to actually configure the auth-related variables above and where the traps are
+- [GitHub integration](/github-integration) — how to set up the GitHub App that backs `GITHUB_APP_SLUG` / `GITHUB_WEBHOOK_SECRET`
 - [Troubleshooting](/troubleshooting) — symptoms and fixes for common misconfigurations
 - [Daemon and runtimes](/daemon-runtimes) — what the `MULTICA_DAEMON_*` parameters actually do

apps/docs/content/docs/environment-variables.zh.mdx

@@ -141,6 +141,22 @@ Multica 存储用户上传的附件（评论里的图片、文件等）。**优
 **`FRONTEND_ORIGIN` 不设就有两个静默失败**：（1）邀请邮件里的链接指向 `https://app.multica.ai`（托管版的域名），用户点了跳不回你的 self-host 实例；（2）WebSocket 连接的 Origin 校验回落到 `localhost:3000 / 5173 / 5174`，生产部署的 WebSocket 全部被拒，前端看起来「实时更新不工作」。
 </Callout>
 
+## GitHub 集成
+
+[GitHub PR ↔ issue 集成](/github-integration) 依赖两个环境变量。两个都配上才会启用 Settings 里的 Connect GitHub 并接受 webhook。
+
+| 环境变量 | 默认值 | 说明 |
+|---|---|---|
+| `GITHUB_APP_SLUG` | 空 | 你的 GitHub App slug（`https://github.com/apps/<slug>` 的尾部）。Settings → Integrations 里安装按钮的跳转 URL 用它拼 |
+| `GITHUB_WEBHOOK_SECRET` | 空 | 你在 GitHub App 上设置的 Webhook secret。每条 `pull_request` / `installation` delivery 都用它做 HMAC-SHA256 校验；同一个值也用作 setup 回调里 state token 的签名密钥 |
+
+**任一变量未设时：**
+
+- Settings → Integrations 里 `Connect GitHub` 按钮 **disable**，对 admin 显示「not configured」提示
+- `/api/webhooks/github` 直接返回 **`503 github webhooks not configured`**——secret 没配置时 Multica 拒绝处理任何 webhook 事件，而不是把所有签名当 valid
+
+**注意：** `GITHUB_WEBHOOK_SECRET` 同时被复用为 install 流程里 state token 的签名密钥，所以运维只需要维护一个 secret。它**不是** GitHub App 的 *Client* secret——Client secret 是 OAuth 用的，和本集成无关。完整配置流程见 [GitHub 集成 → Self-Host 配置](/github-integration#self-host-配置)。
+
 ## 用量统计
 
 默认上报到 Multica 官方 PostHog 实例。不想上报就把 `ANALYTICS_DISABLED=true`。
@@ -154,5 +170,6 @@ Multica 存储用户上传的附件（评论里的图片、文件等）。**优
 ## 下一步
 
 - [登录与注册配置](/auth-setup) —— 上面 auth 相关的那几个环境变量怎么真的配、陷阱在哪
+- [GitHub 集成](/github-integration) —— `GITHUB_APP_SLUG` / `GITHUB_WEBHOOK_SECRET` 背后的 GitHub App 怎么建
 - [故障排查](/troubleshooting) —— 配错了常见的症状和修复
 - [守护进程与运行时](/daemon-runtimes) —— `MULTICA_DAEMON_*` 参数的行为含义

apps/docs/content/docs/getting-started/self-hosting.zh.mdx

@@ -337,16 +337,47 @@ In production, put a reverse proxy in front of both the backend and frontend to
 
 ### Caddy (Recommended)
 
+**Single-domain layout** — frontend and backend served on the same hostname (this is what `docker-compose.selfhost.yml` defaults to):
+
+```
+multica.example.com {
+    # WebSocket route — must come before the catch-all
+    @multica_ws path /ws /ws/*
+    handle @multica_ws {
+        reverse_proxy localhost:8080 {
+            flush_interval -1
+        }
+    }
+
+    # Everything else → frontend
+    reverse_proxy localhost:3000
+}
+```
+
+**Separate-domain layout** — frontend and backend on different hostnames:
+
 ```
 app.example.com {
     reverse_proxy localhost:3000
 }
 
 api.example.com {
+    @multica_ws path /ws /ws/*
+    handle @multica_ws {
+        reverse_proxy localhost:8080 {
+            flush_interval -1
+        }
+    }
+
     reverse_proxy localhost:8080
 }
 ```
 
+Two non-obvious bits inside the `/ws` block are worth calling out — both are common reasons real-time updates "stop working" on a Caddy-fronted self-host:
+
+- **`path /ws /ws/*` (not `/ws*`)** — bare `handle /ws` is an exact match, so future path variants under `/ws/` fall through to the frontend block. The obvious shortcut `handle /ws*` overcorrects in the other direction: Caddy's `*` is a glob without a path-segment boundary, so it would also catch unrelated paths like `/ws-foo`, which is a legitimate workspace URL (only the exact slug `ws` is reserved). Listing `/ws` and `/ws/*` explicitly covers both real cases without overreach.
+- **`flush_interval -1`** — disables response buffering so WebSocket frames are forwarded as soon as they arrive. Without it, frames can sit behind Caddy's default flush window, which looks like delayed comments, missing typing indicators, or "comments only appear after a page refresh."
+
 ### Nginx
 
 ```nginx

apps/docs/content/docs/github-integration.mdx

@@ -0,0 +1,183 @@
+---
+title: GitHub integration
+description: Connect a GitHub App once, then PRs whose branch, title, or body reference an issue identifier auto-attach to that issue — and merging the PR moves the issue to Done.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+Connect a GitHub account or organization once in **Settings → Integrations**. After that, any pull request whose branch name, title, or body contains an issue identifier (for example `MUL-123`) is **auto-linked** to that [issue](/issues), appears under **Pull requests** in the issue sidebar, and — when the PR is merged — moves the issue to **Done**.
+
+There is no per-issue setup. The whole flow is identifier-driven.
+
+## What the integration does
+
+| Surface | Behavior |
+|---|---|
+| **Settings → Integrations** | Workspace admins see a GitHub card with a **Connect GitHub** button. Clicking it opens GitHub's App install page; after install you bounce back to Settings. |
+| **Issue sidebar → Pull requests** | Every PR auto-linked to this issue, with title, repo, state (`Open` / `Draft` / `Merged` / `Closed`), and author. Click a row to jump to the PR on GitHub. |
+| **Webhook (background)** | On every `pull_request` event, Multica upserts the PR row, scans the PR for issue identifiers, and (re)builds the link rows. Idempotent — replaying a delivery is a no-op. |
+| **Auto-status on merge** | When a PR transitions to `merged`, every linked issue not already `Done` or `Cancelled` is moved to `Done`. The status change is timeline-logged with source `github_pr_merged`. |
+
+Only the PR itself is mirrored. Commits, branch refs without an open PR, and CI check states are **not** modeled. The integration is intentionally narrow.
+
+## How identifiers are matched
+
+The webhook extracts identifiers from three fields, in this order: **PR head branch**, **PR title**, **PR body**. The matcher is:
+
+- Case-insensitive — `mul-123`, `MUL-123`, `Mul-123` all match.
+- Bounded — a `\b` on the left and a digit anchor on the right keep it from grabbing version numbers like `v1.2-3` or email-style strings.
+- Workspace-scoped — only matches the workspace's own [issue prefix](/workspaces). `FOO-1` in a workspace whose prefix is `MUL` is ignored, even if the integer matches another issue.
+- Deduplicated — listing `MUL-1, MUL-1` in the body links the issue once.
+
+You can reference **multiple issues** in one PR. `Closes MUL-1, MUL-2` links the PR to both, and merging it advances both to `Done`.
+
+## The auto-merge-to-Done rule
+
+When a PR's `merged` field flips to `true`, every linked issue is evaluated:
+
+| Issue current status | Result |
+|---|---|
+| `done` | No change (already terminal). |
+| `cancelled` | **No change** — cancelled means the user explicitly abandoned the work; the integration does not override that signal. |
+| Anything else (`todo`, `in_progress`, `in_review`, `blocked`, `backlog`) | Moved to `done`. |
+
+Closing a PR **without** merging it only updates the PR card's state to `Closed`. The linked issues stay where they were — the user is the one who decides what closing-without-merge means.
+
+<Callout type="info">
+The action is attributed to the `system` actor on the timeline. Subscribers of the issue receive an inbox notification for the status change, the same way they would if a human had moved it.
+</Callout>
+
+## What's not auto-linked
+
+- **Identifiers in commit messages** — only branch / title / body are scanned. A commit titled `MUL-123: fix login` does not auto-link unless the same string also appears in the PR title or body.
+- **Identifiers in PR comments** — only the PR's own metadata is scanned; later GitHub comments are ignored.
+- **PRs in repos the App isn't installed on** — without the App, Multica never receives the webhook.
+- **Manually linking a PR to an issue** — there is no UI for this yet. If your team's convention puts identifiers in a place Multica isn't reading, add them to the PR title or body.
+
+## Disconnecting
+
+In **Settings → Integrations** there is no installation list — you manage existing installations from GitHub directly:
+
+- **From GitHub** — uninstall the Multica GitHub App at `https://github.com/settings/installations` (personal) or `https://github.com/organizations/<org>/settings/installations` (org). Multica receives the `installation.deleted` webhook and drops the row in real time; any open Settings tab updates without a refresh.
+- **Disconnect from inside Multica is admin-only** — the Settings card is hidden for non-admins.
+
+After disconnect, mirrored PR rows stay in the database so historical issue sidebars still show what was linked, but no new webhook events from that installation will be accepted.
+
+## Permissions and visibility
+
+- **Connect / disconnect** require workspace **owner or admin**. Members see the card description but no Connect button.
+- The **Pull requests** sidebar on an issue is visible to anyone who can read the issue — same permissions as the rest of issue detail.
+- The GitHub App requests **read-only** access to pull requests and metadata. Multica never pushes commits, comments, or status checks back to GitHub.
+
+## Self-host setup
+
+If you're running Multica on Multica Cloud, the integration is already configured — skip this section.
+
+For self-host, you create one GitHub App, point it at your server, and set two environment variables. The whole flow is below.
+
+### 1. Create a GitHub App
+
+Go to one of:
+
+- Personal account → `https://github.com/settings/apps/new`
+- Organization → `https://github.com/organizations/<org>/settings/apps/new`
+
+Fill in:
+
+| Field | Value |
+|---|---|
+| **GitHub App name** | Anything recognizable, e.g. `Multica` or `Multica (staging)`. |
+| **Homepage URL** | Your Multica frontend, e.g. `https://multica.example.com`. |
+| **Callback URL** | Leave blank — Multica doesn't use OAuth user identity. |
+| **Setup URL** | `https://<api-host>/api/github/setup`. **Check "Redirect on update"**. |
+| **Webhook → Active** | Enabled. |
+| **Webhook URL** | `https://<api-host>/api/webhooks/github`. |
+| **Webhook secret** | Generate a long random string (e.g. `openssl rand -hex 32`). You'll paste the same value into Multica's env in step 2. |
+| **Permissions → Repository → Pull requests** | **Read-only**. |
+| **Permissions → Repository → Metadata** | Read-only (mandatory). |
+| **Subscribe to events** | Tick **Pull request**. |
+| **Where can this GitHub App be installed?** | Your choice. `Only on this account` is fine for single-org setups. |
+
+After **Create GitHub App**, note two things from the App's detail page:
+
+- The **public link** at the top — its tail is the slug. `https://github.com/apps/multica-acme` → slug = `multica-acme`.
+- The **webhook secret** you just generated (you can't read it back from GitHub later — save it now).
+
+<Callout type="warning">
+**Webhook secret ≠ Client secret.** The App settings page has both fields stacked together. The **Webhook secret** is what signs `pull_request` payloads — that's the one Multica needs. The **Client secret** is for OAuth and is not used by this integration. Mixing them up produces a confusing `401 invalid signature` on every webhook delivery.
+</Callout>
+
+### 2. Set environment variables
+
+On the API server:
+
+```dotenv
+GITHUB_APP_SLUG=multica-acme
+GITHUB_WEBHOOK_SECRET=<the webhook secret you generated>
+```
+
+Both variables are required. If either is missing:
+
+- `Connect GitHub` in Settings is **disabled** and shows a "not configured" hint.
+- The `/api/webhooks/github` endpoint returns **`503 github webhooks not configured`** — Multica refuses to process events with no secret, rather than silently treating every signature as valid.
+
+`FRONTEND_ORIGIN` must also be set (it already is for any production self-host); the setup callback bounces the user back to `<FRONTEND_ORIGIN>/settings` after install.
+
+Restart the API after setting the env vars.
+
+### 3. Run migrations
+
+The integration ships its tables in migration `079_github_integration`. If you're upgrading an older deployment:
+
+```bash
+make migrate-up
+```
+
+Three tables get created: `github_installation`, `github_pull_request`, `issue_pull_request`. They cascade-delete with their workspace, so removing a workspace cleans them up automatically.
+
+### 4. Connect from the UI
+
+In Multica:
+
+1. Open **Settings → Integrations** as an owner or admin.
+2. Click **Connect GitHub**. GitHub opens in a new tab.
+3. Pick the repositories to grant access to and **Install**.
+4. GitHub redirects back to `<api-host>/api/github/setup`, which records the installation and bounces you to `<FRONTEND_ORIGIN>/settings?github_connected=1`.
+
+After that, open any PR whose branch / title / body contains an issue identifier — within a few seconds the Pull requests block appears on that issue's detail page.
+
+### 5. Verify with a curl probe
+
+If GitHub's **Recent Deliveries** page reports `401 invalid signature` after install, the two sides have different secrets. The fastest way to find out which side is wrong is to bypass GitHub:
+
+```bash
+SECRET="<the value you put in GITHUB_WEBHOOK_SECRET>"
+BODY='{"zen":"test"}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')
+curl -i -X POST https://<api-host>/api/webhooks/github \
+  -H "X-Hub-Signature-256: sha256=$SIG" \
+  -H "X-GitHub-Event: ping" \
+  -H "Content-Type: application/json" \
+  -d "$BODY"
+```
+
+| HTTP status | Meaning | Fix |
+|---|---|---|
+| `200` `{"ok":"pong"}` | Server's loaded secret matches your `$SECRET`. The mismatch is on GitHub. | Edit the App → Webhook secret → **paste the same value** → **Save changes** (clicking out of the field without Save keeps the old secret). Redeliver. |
+| `401 invalid signature` | Server's loaded secret is **not** what you think it is. | Confirm the env var landed in the running process (e.g. `kubectl exec` → `echo -n "$GITHUB_WEBHOOK_SECRET" | wc -c`). Re-deploy. |
+| `503 github webhooks not configured` | `GITHUB_WEBHOOK_SECRET` is empty in the process. | Set the env var, restart the API. |
+
+## Limitations
+
+A few rough edges to be aware of today:
+
+- **No manual link UI yet** — the only way to link a PR is to have the identifier in its branch, title, or body.
+- **No CI / check state** — only the PR itself is mirrored. Build status, review comments, and reviewers are not surfaced in Multica.
+- **No workspace-level config** for the merge → Done rule — it's a fixed default (`merged → done`, unless `cancelled`). Workspace-customizable mappings are a future addition.
+- **Multi-PR-to-one-issue is conservative on merge** — if two PRs both reference `MUL-123` and the first one merges, the issue is moved to `Done` immediately. A follow-up change to wait for all linked PRs to resolve before advancing is in progress.
+
+## Next
+
+- [Issues](/issues) — the issue identifiers (`MUL-123`) referenced from PRs
+- [Workspaces](/workspaces) — where the workspace-specific issue prefix is set
+- [Environment variables](/environment-variables) — full env reference, including the GitHub variables above

apps/docs/content/docs/github-integration.zh.mdx

@@ -0,0 +1,183 @@
+---
+title: GitHub 集成
+description: 一次性连接 GitHub App，之后 PR 的分支名、标题或正文里写了 issue 编号（例如 MUL-123），就会自动挂到那个 issue 上——PR 合并时 issue 自动转 Done。
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+在 **Settings → Integrations** 里一次性连一个 GitHub 账号或组织。之后任何 PR 只要分支名、标题或正文里出现 issue 编号（例如 `MUL-123`），就会**自动关联**到那个 [issue](/issues)，出现在 issue 详情页右侧的 **Pull requests** 区块里——PR 合并时，issue 自动转 **Done**。
+
+没有 per-issue 的配置，整个流程是「编号驱动」的。
+
+## 集成做了什么
+
+| 出现位置 | 行为 |
+|---|---|
+| **Settings → Integrations** | 工作区 owner / admin 看到一个 GitHub 卡片，里面有 **Connect GitHub** 按钮。点击会打开 GitHub 的 App 安装页；装好后跳回 Settings。 |
+| **Issue 详情侧栏 → Pull requests** | 列出所有自动关联到该 issue 的 PR，含标题、仓库、状态（`Open` / `Draft` / `Merged` / `Closed`）和作者。点一行跳到 GitHub。 |
+| **Webhook（后台）** | 每次 `pull_request` 事件触发：upsert PR 行 → 扫描里面的 issue 编号 →（重新）建立 link。幂等——重投 delivery 不会产生重复记录。 |
+| **Merge 自动改 status** | PR 转 `merged` 时，所有已关联且状态不是 `Done` / `Cancelled` 的 issue 会被推到 `Done`。时间线里以 source 为 `github_pr_merged` 记录。 |
+
+只镜像 PR 本身。Commit、没开 PR 的分支、CI 检查状态都**不**入库——集成有意保持窄边界。
+
+## 编号是怎么匹配的
+
+Webhook 从三个字段抽取编号，顺序是：**PR head 分支** → **PR 标题** → **PR 正文**。匹配规则：
+
+- 大小写不敏感——`mul-123`、`MUL-123`、`Mul-123` 都能匹配
+- 有边界——左侧 `\b`、右侧只接数字，避免误抓 `v1.2-3`、email 地址等
+- 限定到本工作区——只匹配本工作区的 [issue prefix](/workspaces)。前缀是 `MUL` 的工作区里，PR 出现 `FOO-1` 不会匹配，即使数字撞另一个 issue 也不会
+- 自动去重——`Closes MUL-1, MUL-1` 只关联一次
+
+一个 PR 里**可以同时引用多个 issue**。比如 `Closes MUL-1, MUL-2`：PR 同时关联两个 issue，合并时两个 issue 都会转 `Done`。
+
+## Merge 自动转 Done 的规则
+
+PR 的 `merged` 字段翻成 `true` 时，逐个评估关联的 issue：
+
+| Issue 当前状态 | 结果 |
+|---|---|
+| `done` | 不变（已经是终态）|
+| `cancelled` | **不变**——cancelled 是用户明确放弃工作的信号，集成不覆盖 |
+| 其他（`todo` / `in_progress` / `in_review` / `blocked` / `backlog`）| 转成 `done` |
+
+PR **关闭但没合并**——只更新 PR 卡片的状态为 `Closed`，issue 状态不变。"关闭但不合并"语义因团队而异，Multica 不替用户做决定。
+
+<Callout type="info">
+状态变更的 actor 是 `system`。订阅了该 issue 的成员会收到 inbox 通知，和成员手动改状态时一致。
+</Callout>
+
+## 哪些情况不会自动关联
+
+- **Commit message 里的编号**——只扫 PR 的分支 / 标题 / 正文。一个 commit message 写 `MUL-123: fix login` 不会触发关联，除非同样的字符串也出现在 PR 标题或正文里
+- **PR 评论里的编号**——只扫 PR 自己的元数据，后续的 GitHub comment 不读
+- **App 没安装的仓库里的 PR**——没 App，Multica 收不到 webhook
+- **手动把 PR 关联到 issue**——暂时没有这个 UI。如果你们的约定把编号放到 Multica 不扫的地方，请改放到 PR 标题或正文里
+
+## 断开连接
+
+**Settings → Integrations** 里没有 installation 列表——现有 installation 直接到 GitHub 上管理：
+
+- **从 GitHub 卸载** —— 个人在 `https://github.com/settings/installations`、组织在 `https://github.com/organizations/<org>/settings/installations` 卸载 Multica App。Multica 收到 `installation.deleted` webhook 后立刻删行；任何已打开的 Settings tab 实时更新，不用刷新
+- **Multica 这边的断开是 admin only** —— 卡片对非 admin 不显示连接操作
+
+断开之后，已经镜像的 PR 行保留在数据库里——历史 issue 侧栏仍能显示当时关联的 PR，但来自这个 installation 的新 webhook 事件不再被接受。
+
+## 权限和可见性
+
+- **Connect / Disconnect** 需要工作区 **owner 或 admin**。普通成员能看到卡片描述但看不到 Connect 按钮
+- **Pull requests** 侧栏对所有能看到该 issue 的成员可见——和 issue 详情页其他部分权限一致
+- GitHub App 申请的是 PR 和 Metadata 的 **只读** 权限。Multica 从不向 GitHub 推 commit、评论或 status check
+
+## Self-Host 配置
+
+如果你在 Multica Cloud 上，集成已经配好——跳过本节。
+
+Self-Host 需要：建一个 GitHub App、指向你的 server、设两个环境变量。完整流程如下。
+
+### 1. 创建一个 GitHub App
+
+到下面其中一个页面：
+
+- 个人账号 → `https://github.com/settings/apps/new`
+- 组织 → `https://github.com/organizations/<org>/settings/apps/new`
+
+按下表填写：
+
+| 字段 | 值 |
+|---|---|
+| **GitHub App name** | 任何能辨识的名字，例如 `Multica` 或 `Multica (staging)` |
+| **Homepage URL** | 你的 Multica 前端，例如 `https://multica.example.com` |
+| **Callback URL** | 留空——本集成不使用 OAuth 用户身份 |
+| **Setup URL** | `https://<api-host>/api/github/setup`。**勾选 "Redirect on update"** |
+| **Webhook → Active** | 启用 |
+| **Webhook URL** | `https://<api-host>/api/webhooks/github` |
+| **Webhook secret** | 生成一个长随机字符串（例如 `openssl rand -hex 32`）。这个值会同样填到 step 2 的 env 里 |
+| **Permissions → Repository → Pull requests** | **Read-only** |
+| **Permissions → Repository → Metadata** | Read-only（必填）|
+| **Subscribe to events** | 勾选 **Pull request** |
+| **Where can this GitHub App be installed?** | 自选。单组织部署建议选 `Only on this account` |
+
+点 **Create GitHub App** 之后，从详情页记下两件事：
+
+- 顶部 **public link** 的尾部即 slug。`https://github.com/apps/multica-acme` → slug = `multica-acme`
+- 你刚生成的 **webhook secret**（GitHub 之后不会再让你读取这个值——现在就保存好）
+
+<Callout type="warning">
+**Webhook secret ≠ Client secret。** App 设置页里两个字段紧挨着。**Webhook secret** 用于签 `pull_request` payload，这才是 Multica 需要的那个；**Client secret** 是 OAuth 用的，和本集成无关。混淆这两个会得到「每条 webhook 都 `401 invalid signature`」的诡异症状。
+</Callout>
+
+### 2. 配置环境变量
+
+API server 上：
+
+```dotenv
+GITHUB_APP_SLUG=multica-acme
+GITHUB_WEBHOOK_SECRET=<你刚生成的 webhook secret>
+```
+
+两个都必填。任何一个缺失：
+
+- Settings 里 `Connect GitHub` 按钮会被 **disable**，并显示「not configured」提示
+- `/api/webhooks/github` 直接返回 **`503 github webhooks not configured`**——Multica 在 secret 没配置时拒绝处理事件，不会出现「没 secret 也接受 webhook」的安全坑
+
+`FRONTEND_ORIGIN` 也必须设置（任何生产 self-host 都已经设了）——setup 回调结束后用它把用户跳回 `<FRONTEND_ORIGIN>/settings`。
+
+设完 env 重启 API。
+
+### 3. 执行 migration
+
+集成的表在 migration `079_github_integration` 里。如果是升级既有部署：
+
+```bash
+make migrate-up
+```
+
+会创建三张表：`github_installation`、`github_pull_request`、`issue_pull_request`。三张表都 cascade 跟随 workspace——删工作区会自动清理。
+
+### 4. 在 UI 里连接
+
+到 Multica：
+
+1. 以 owner 或 admin 身份打开 **Settings → Integrations**
+2. 点 **Connect GitHub**，GitHub 在新 tab 打开
+3. 选择要授权的仓库，点 **Install**
+4. GitHub 跳回 `<api-host>/api/github/setup`，落库后再跳到 `<FRONTEND_ORIGIN>/settings?github_connected=1`
+
+之后在任意一个仓库开一个分支 / 标题 / 正文带本工作区 issue 编号的 PR——几秒内对应 issue 的详情页上就能看到 Pull requests 区块。
+
+### 5. 用 curl 自检
+
+如果 GitHub 的 **Recent Deliveries** 里第一次 PR 事件就报 `401 invalid signature`，说明两边的 secret 不一致。绕过 GitHub 直接测 server 是最快的定位方法：
+
+```bash
+SECRET="<你填给 GITHUB_WEBHOOK_SECRET 的值>"
+BODY='{"zen":"test"}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')
+curl -i -X POST https://<api-host>/api/webhooks/github \
+  -H "X-Hub-Signature-256: sha256=$SIG" \
+  -H "X-GitHub-Event: ping" \
+  -H "Content-Type: application/json" \
+  -d "$BODY"
+```
+
+| HTTP 状态 | 含义 | 修法 |
+|---|---|---|
+| `200` `{"ok":"pong"}` | server 加载的 secret 和你 `$SECRET` 一致——GitHub 那边的 secret 才是错的 | 编辑 App → Webhook secret 字段**粘相同的值** → **必须点 Save changes**（不点 Save 等于没改）→ Redeliver |
+| `401 invalid signature` | server 加载的 secret **不是**你以为的那个 | 进容器确认 env 实际生效（例如 `kubectl exec` → `echo -n "$GITHUB_WEBHOOK_SECRET" \| wc -c`），重新部署 |
+| `503 github webhooks not configured` | `GITHUB_WEBHOOK_SECRET` 在进程里是空的 | 配上 env，重启 API |
+
+## 已知限制
+
+目前还没做的几个边界：
+
+- **手动 link UI 暂未提供**——关联 PR 的唯一方法是把 issue 编号写到 PR 分支 / 标题 / 正文
+- **不读 CI / check 状态**——只镜像 PR 本身，构建状态、reviewer 评论、reviewer 列表都没接进 Multica
+- **没有工作区级别的 merge → status 映射配置**——默认固定是 `merged → done`（cancelled 除外）。可配置映射是后续迭代
+- **同 issue 多 PR 时，merge 行为偏激进**——两个 PR 都引用 `MUL-123` 时，第一个 merge 就把 issue 转 Done。"等所有关联 PR 都解决再推进 issue 状态"的优化已经在做了
+
+## 下一步
+
+- [Issues](/issues) —— PR 引用的 issue 编号（`MUL-123`）的来源
+- [工作区](/workspaces) —— 工作区 issue prefix 的设置位置
+- [环境变量](/environment-variables) —— 完整 env 清单，包含上面提到的 GitHub 变量

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",
@@ -27,6 +28,8 @@
     "autopilots",
     "---Inbox---",
     "inbox",
+    "---Integrations---",
+    "github-integration",
     "---Self-hosting & ops---",
     "environment-variables",
     "auth-setup",

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

@@ -15,6 +15,7 @@
     "agents",
     "agents-create",
     "skills",
+    "squads",
     "---智能体怎么运行---",
     "daemon-runtimes",
     "tasks",
@@ -26,6 +27,8 @@
     "autopilots",
     "---收件箱---",
     "inbox",
+    "---集成---",
+    "github-integration",
     "---自部署运维---",
     "environment-variables",
     "auth-setup",

apps/docs/content/docs/self-host-quickstart.mdx

@@ -115,5 +115,6 @@ Same flow as Cloud — see [Cloud quickstart → Steps 5-6](/cloud-quickstart#5-
 
 - [Environment variables](/environment-variables) — full env reference
 - [Auth setup](/auth-setup) — Resend / OAuth / signup allowlist in detail
+- [GitHub integration](/github-integration) — connect a GitHub App so PRs auto-link to issues and merging closes them
 - [Troubleshooting](/troubleshooting) — start here when things go wrong
 - [Desktop app](/desktop-app) — optional Desktop setup via `~/.multica/desktop.json`; the web frontend + CLI remains the quickest self-host path

apps/docs/content/docs/self-host-quickstart.zh.mdx

@@ -114,5 +114,6 @@ multica setup self-host
 
 - [环境变量](/environment-variables) —— 完整 env 清单
 - [登录与注册配置](/auth-setup) —— Resend / OAuth / 注册白名单详细配置
+- [GitHub 集成](/github-integration) —— 连一个 GitHub App，让 PR 自动关联 issue、merge 时自动转 Done
 - [故障排查](/troubleshooting) —— 遇到问题先来这里
 - [桌面应用](/desktop-app) —— 可以通过 `~/.multica/desktop.json` 连接 Desktop；Web 前端 + CLI 仍然是最快的自部署路径

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 的完整权限对照

apps/docs/content/docs/tasks.mdx

@@ -69,7 +69,7 @@ Automatic retry also has two extra conditions:
 
 ## Manual rerun vs. automatic retry
 
-A **manual rerun** is one you trigger from the UI or CLI:
+A **manual rerun** is one you trigger from the CLI or the API (`POST /api/issues/{id}/rerun`):
 
 ```bash
 multica issue rerun <issue-id>
@@ -77,9 +77,10 @@ multica issue rerun <issue-id>
 
 Behavior:
 
-- **Cancels** the currently running task (if any)
-- Creates a **brand-new** task — attempt count resets to 1, even if the original task hit the attempt ceiling
-- Inherits the previous session ID; if the corresponding AI coding tool supports session resumption, the new task continues from the previous context
+- Targets the issue's **current agent assignee** — not whoever ran the most recent task. If the assignee changed since the last run, rerun follows the current assignment. To rerun a specific agent that is no longer the assignee, reassign the issue first, then rerun.
+- **Cancels** the assignee's queued or running task on this issue (if any). Tasks owned by other agents on the same issue (e.g. parallel @-mention runs) are left alone.
+- Creates a **brand-new** task — attempt count resets to 1, even if the original task hit the attempt ceiling.
+- Starts a **fresh agent session** — the prior session ID is **not** inherited. A manual rerun means you've judged the previous output bad, so resuming the same conversation would replay the same poisoned state. (Automatic retry, by contrast, does inherit the session — that path is for infrastructure failures, not bad output.)
 
 Comparison:
 
@@ -87,8 +88,9 @@ Comparison:
 |---|---|---|
 | Trigger | System, based on failure reason | You, manually |
 | Ceiling | 2 attempts | No limit |
-| Applicable sources | Issues, chat | All sources |
-| Session inheritance | Yes | Yes |
+| Applicable sources | Issues, chat | Issues with an agent assignee |
+| Agent picked | Same agent as the failed task | Issue's current assignee |
+| Session inheritance | Yes (resumes prior session) | No (fresh session) |
 
 ## How a failed task affects issue status
 
@@ -98,7 +100,7 @@ If an issue-triggered task fails (and no automatic retry succeeds) because the i
 
 Yes — as long as the AI coding tool supports session resumption.
 
-Multica pins the session ID **twice** during a task: once at the start (when the AI tool returns its first system message), and once at the end (on completion or failure). The first lets the daemon recover if it crashes mid-run; the second is reserved for future reruns. On the next rerun or automatic retry, that ID is passed back so the agent can pick up the previous conversation and file state.
+Multica pins the session ID **twice** during a task: once at the start (when the AI tool returns its first system message), and once at the end (on completion or failure). The first lets the daemon recover if it crashes mid-run; the second is reserved for the next **automatic retry**, where that ID is passed back so the agent can pick up the previous conversation and file state. **Manual rerun deliberately skips this** and starts a fresh session — see [Manual rerun vs. automatic retry](#manual-rerun-vs-automatic-retry).
 
 But **which AI coding tools actually support this** varies a lot:
 

apps/docs/content/docs/tasks.zh.mdx

@@ -69,7 +69,7 @@ Multica 服务器每 30 秒扫描一次，有两种超时会触发失败：
 
 ## 手动重跑和自动重试的区别
 
-**手动重跑**（rerun）是你从 UI 或命令行主动发起的：
+**手动重跑**（rerun）是你通过命令行或 API（`POST /api/issues/{id}/rerun`）主动发起的：
 
 ```bash
 multica issue rerun <issue-id>
@@ -77,9 +77,10 @@ multica issue rerun <issue-id>
 
 行为：
 
-- **取消**当前正在跑的任务（如果有）
-- 创建一个**全新**的执行任务——尝试次数重置为 1，即使原任务已达最大尝试
-- 继承上一次的会话 ID；如果对应的 AI 编程工具支持会话恢复，会接着上次的上下文继续
+- 跑的是 issue **当前的智能体分配人**——不是上一次跑过的 agent。如果分配人在上次运行后改了，rerun 会跟着新的分配人走。要重跑一个已经不再是分配人的智能体，先把 issue 改派回它，再 rerun。
+- **取消**该分配人在这条 issue 上 queued / running 的任务（如果有）。同 issue 上其它 agent 的任务（例如 @-mention 触发的并行任务）不会被一起取消。
+- 创建一个**全新**的执行任务——尝试次数重置为 1，即使原任务已达最大尝试。
+- 启动**全新的智能体会话**——**不**继承之前的会话 ID。手动重跑意味着你已经判定上一次的产出不行，再继续之前的对话只会重放被污染的上下文。（自动重试则相反，会继承会话——那条路径处理的是基础设施层面的失败，不是产出不好。）
 
 对比：
 
@@ -87,8 +88,9 @@ multica issue rerun <issue-id>
 |---|---|---|
 | 触发 | 系统基于失败原因自动执行 | 你主动发起 |
 | 上限 | 2 次 | 无上限 |
-| 适用来源 | issue、聊天 | 所有来源 |
-| 会话继承 | 是 | 是 |
+| 适用来源 | issue、聊天 | 有智能体分配人的 issue |
+| 跑哪个 agent | 失败任务原本的 agent | issue 当前的分配人 |
+| 会话继承 | 是（接着上次会话） | 否（全新会话） |
 
 ## 失败的任务对 issue 状态有什么影响
 
@@ -98,7 +100,7 @@ multica issue rerun <issue-id>
 
 可以——前提是对应的 AI 编程工具支持会话恢复。
 
-Multica 在任务过程中**两次**保存会话 ID——任务一开始（AI 工具返回第一条系统消息时）pin 一次，任务结束（完成或失败）时再 pin 一次。前者让守护进程中途崩溃时也能恢复，后者给之后的重跑用。下次重跑或自动重试时把这个 ID 传回去，智能体就能接着上次的对话、文件状态继续。
+Multica 在任务过程中**两次**保存会话 ID——任务一开始（AI 工具返回第一条系统消息时）pin 一次，任务结束（完成或失败）时再 pin 一次。前者让守护进程中途崩溃时也能恢复，后者留给下一次**自动重试**——届时把这个 ID 传回去，智能体就能接着上次的对话和文件状态继续。**手动重跑会主动跳过这一步**，永远从全新会话开始——见 [手动重跑和自动重试的区别](#手动重跑和自动重试的区别)。
 
 但**哪些 AI 编程工具真的支持**差别很大：
 

apps/web/app/[workspaceSlug]/(dashboard)/issues/[id]/page.tsx

@@ -2,6 +2,7 @@
 
 import { use } from "react";
 import { IssueDetail } from "@multica/views/issues/components";
+import { ErrorBoundary } from "@multica/ui/components/common/error-boundary";
 
 export default function IssueDetailPage({
   params,
@@ -9,5 +10,9 @@ export default function IssueDetailPage({
   params: Promise<{ id: string }>;
 }) {
   const { id } = use(params);
-  return <IssueDetail issueId={id} />;
+  return (
+    <ErrorBoundary resetKeys={[id]}>
+      <IssueDetail issueId={id} />
+    </ErrorBoundary>
+  );
 }

apps/web/app/[workspaceSlug]/(dashboard)/issues/page.tsx

@@ -1,7 +1,12 @@
 "use client";
 
 import { IssuesPage } from "@multica/views/issues/components";
+import { ErrorBoundary } from "@multica/ui/components/common/error-boundary";
 
 export default function Page() {
-  return <IssuesPage />;
+  return (
+    <ErrorBoundary>
+      <IssuesPage />
+    </ErrorBoundary>
+  );
 }

apps/web/app/[workspaceSlug]/(dashboard)/squads/[id]/page.tsx

@@ -0,0 +1 @@
+export { SquadDetailPage as default } from "@multica/views/squads";

apps/web/app/[workspaceSlug]/(dashboard)/squads/page.tsx

@@ -0,0 +1 @@
+export { SquadsPage as default } from "@multica/views/squads";

apps/web/app/[workspaceSlug]/(dashboard)/usage/page.tsx

@@ -0,0 +1 @@
+export { DashboardPage as default } from "@multica/views/dashboard";

apps/web/app/custom.css

@@ -39,7 +39,6 @@
     --success: oklch(0.55 0.16 145);
     --warning: oklch(0.75 0.16 85);
     --info: oklch(0.55 0.18 250);
-    --priority: oklch(0.65 0.18 50);
     --scrollbar-thumb: oklch(0 0 0 / 10%);
     --scrollbar-thumb-hover: oklch(0 0 0 / 18%);
     --scrollbar-track: transparent;

apps/web/features/landing/components/landing-header.tsx

@@ -44,6 +44,15 @@ export function LandingHeader({
         </Link>
 
         <div className="flex items-center gap-2.5 sm:gap-3">
+          <Link
+            href="/changelog"
+            className={cn(
+              headerButtonClassName("ghost", variant),
+              "hidden sm:inline-flex",
+            )}
+          >
+            {t.header.changelog}
+          </Link>
           <Link
             href={githubUrl}
             target="_blank"

apps/web/features/landing/i18n/en.ts

@@ -7,6 +7,7 @@ export function createEnDict(allowSignup: boolean): LandingDict {
     github: "GitHub",
     login: "Log in",
     dashboard: "Dashboard",
+    changelog: "Changelog",
   },
 
   hero: {
@@ -283,6 +284,195 @@ export function createEnDict(allowSignup: boolean): LandingDict {
       fixes: "Bug Fixes",
     },
     entries: [
+      {
+        version: "0.3.0",
+        date: "2026-05-14",
+        title: "Squads & Attachment Previews",
+        changes: [],
+        features: [
+          "Squads let teams assign work to a group, with a leader agent coordinating the next step",
+          "Attachments can be previewed in place for PDFs, audio, video, markdown, code, logs, and plain text",
+          "Chinese names can be found by pinyin across mentions, assignees, subscribers, agents, projects, and squads",
+        ],
+        improvements: [
+          "Squad pages now include member management, faster agent creation from a squad, clearer row actions, and a wider detail layout",
+          "Quick-create and picker flows are easier to search and now include squad-aware routing",
+          "Usage charts can switch between cost and token views, with the same timezone controls used by runtimes",
+          "Workspace operators get command-line controls for managing squads and stopping a runaway issue run",
+          "Shared interface labels are translated more consistently in English and Chinese",
+        ],
+        fixes: [
+          "Squad leaders stay quiet when a human already routed the conversation to someone specific",
+          "Mentioning a squad now wakes the right leader while preserving private-agent access rules",
+          "Issue lists stay fresher after deletes and follow-up comments no longer trigger stale Done replies",
+          "Attachment previews keep working for files added while writing or editing issues and comments",
+        ],
+      },
+      {
+        version: "0.2.32",
+        date: "2026-05-13",
+        title: "Usage Insights, Chat Renaming & Smoother Desktop Flows",
+        changes: [],
+        features: [
+          "Usage now shows workspace and project token activity, runtime trends, and per-agent rankings in one place",
+          "Chat sessions can be renamed directly from the chat header",
+          "Feedback reports can include screenshots or files so teams have the context they need",
+        ],
+        improvements: [
+          "The Usage page has clearer naming and a more dynamic agent leaderboard",
+          "New chats and completed chat responses update more smoothly with fewer loading flashes",
+          "Self-hosted GitHub setup is easier to configure and the setup docs point to the right cloud URL",
+          "User-installed Codex skills are available automatically when new tasks run",
+        ],
+        fixes: [
+          "Empty successful agent responses are marked completed instead of blocked",
+          "Pasted mentions in instruction editors keep their mention links",
+          "Desktop attachment downloads use the native Linux flow and tab closing no longer loops",
+          "Gemini and Windows runtime startup checks are more reliable in unattended runs",
+          "Long GitHub repository lists stay usable when adding project resources",
+        ],
+      },
+      {
+        version: "0.2.31",
+        date: "2026-05-12",
+        title: "GitHub Integration, Chat Attachments & Safer Issue Navigation",
+        changes: [],
+        features: [
+          "Connect GitHub so linked pull requests appear on Multica issues, sync their status, and close the Multica issue automatically when the PR closes",
+          "Chat messages can include file attachments and image previews",
+          "Agents and runtimes can now be kept public or private for clearer team access",
+          "Stopping a single agent task now asks for confirmation before it is terminated",
+          "New GitHub integration docs cover both hosted and self-hosted setup",
+        ],
+        improvements: [
+          "Issue links land more reliably on the exact comment or activity you opened",
+          "Long issue timelines scroll more smoothly",
+          "The feedback dialog now points contributors toward GitHub discussions and issues",
+          "Self-hosted Caddy guidance now calls out real-time connection requirements",
+          "Linux desktop packages show the Multica app icon again",
+        ],
+        fixes: [
+          "Downloaded attachments keep their original filenames",
+          "Local attachments are served more reliably, and upload controls stay disabled until files are ready",
+          "Issue creation dialogs keep their text fields at the correct height",
+          "Runtime documentation links point to the correct page",
+        ],
+      },
+      {
+        version: "0.2.30",
+        date: "2026-05-11",
+        title: "Mermaid in Issues, Per-Runtime Timezone & Workspace-Leave Runtime Revocation",
+        changes: [],
+        features: [
+          "Mermaid diagrams render inline in issue descriptions",
+          "Sub-issue rows gain inline status and assignee pickers, with batch select across rows",
+          "Per-runtime timezone for token-usage aggregation, so daily rollups respect your local day",
+          "Private agents are gated by an `allowed_principals` predicate, with fine-grained visibility",
+          "A member leaving or being removed from a workspace now revokes their runtimes automatically",
+          "Set custom per-token prices for unmaintained models so usage reflects real cost",
+          "Landing page header gains a Changelog link",
+        ],
+        improvements: [
+          "Daemon self-heals when a runtime is deleted server-side — no more zombie local entries",
+          "Chat and comment composer share the same `Mod+Enter` send shortcut",
+          "Copilot CLI model catalog expanded with correct dotted IDs",
+          "Copilot failure details now surface in the UI instead of a generic error",
+          "Daemon brief is inlined into the system prompt for providers that need it",
+          "Realtime WebSocket accepts same-origin upgrades from mobile and CLI",
+        ],
+        fixes: [
+          "Recent-issues list no longer leaks across workspaces",
+          "CloudFront attachment download URLs are re-signed at click time, fixing expired previews",
+          "Windows reply templates use `--content-file` across every provider so non-ASCII bodies survive",
+          "Daemon suppresses extra git console pop-ups on Windows",
+          "Pi extension tools are no longer filtered by a hardcoded `--tools` allowlist",
+          "Inbox scrolls to the target comment once the issue finishes loading",
+          "`autopilot create/update` accepts `--mode run_only`",
+          "Changelog header link styled to match the GitHub ghost button",
+          "OpenAI Codex / GPT model pricing populated — cost no longer shows $0",
+        ],
+      },
+      {
+        version: "0.2.29",
+        date: "2026-05-09",
+        title: "Project Picker in Quick Create, Resolvable Comments & Timeline Performance",
+        changes: [],
+        features: [
+          "Quick Create lets you pick a project, and remembers your last choice",
+          "Comment threads can be resolved and collapsed, keeping long discussions tidy",
+          "Issue live banner now shows agent tasks waiting in queue",
+          "Failed or cancelled tasks can be rerun in one click from the Execution Log",
+          "Agent Create modal gains an expand button for editing long descriptions",
+        ],
+        improvements: [
+          "Issue timeline no longer fully re-renders on every WebSocket event — long issues scroll smoothly",
+          "Editor skips parsing very large or JSON pastes, eliminating freezes",
+          "Autopilot skips dispatch when the assignee runtime is offline, avoiding empty runs",
+          "Inbox auto-archives `task_failed` rows once they reach a terminal state",
+          "Hermes sends agent instructions inline with each request",
+          "Timeline and Comment switched to client-side virtualization, dropping server-side pagination",
+          "Reserved slugs share a single JSON between front and back end, with CI guarding drift",
+          "ACP error messages include the JSON-RPC `error.data` field for clearer debugging",
+        ],
+        fixes: [
+          "429 / insufficient-balance agent runs are now marked `failed` instead of `completed`",
+          "Agent sessions stuck on poisoned images can recover, so the issue resumes",
+          "`pi --list-models` table format parses correctly, restoring model discovery",
+          "`pi` colon-to-slash normalization only applies to the legacy format",
+          "`kiro` and `kimi` added to the inline-system-prompt provider allowlist",
+          "Priority dropdown badge colors aligned with PriorityIcon semantic tokens",
+          "Long single-line agent messages now expand correctly",
+          "Desktop \"copy issue link\" uses the current connection URL instead of localhost",
+          "Mobile WebSocket handshake succeeds without cookies",
+          "Workspace slug creation validates reserved words; slug error messages are translated",
+          "Timeline correctly syncs `around` state when props flip to falsy",
+          "DropdownMenu popovers size to their content",
+        ],
+      },
+      {
+        version: "0.2.28",
+        date: "2026-05-08",
+        title: "Daemon Disk-Usage CLI, Timeline Polish & Task Usage Rollup",
+        changes: [],
+        features: [
+          "New `multica daemon disk-usage` CLI surfaces per-task and per-workspace disk footprint",
+          "Skill picker in agent settings has a search box for fast lookup",
+          "Daemon GC extends to chat, autopilot, and quick-create tasks",
+          "Issue detail breadcrumb now shows the MUL-xxxx identifier for quick reference",
+        ],
+        improvements: [
+          "Timeline page size bumped to 50, with per-pool keyset cursors for comments and activities",
+          "'Show older / newer' affordances now appear in edge cases and look clearly clickable",
+          "Server `task_usage` rolls up into a daily aggregate table, dropping DB load significantly",
+          "Daemon health check stays responsive while repo lookups are in flight",
+          "Runtime stats exclude archived agents for accurate active counts",
+        ],
+        fixes: [
+          "Linux daemon self-restart uses `brew prefix` symlinks, so Homebrew Cellar deletion no longer orphans runtimes",
+          "CLI short IDs now route correctly — copied prefixes no longer 404",
+          "Windows non-ASCII comment / description input lands via new `--content-file` / `--description-file` flags",
+          "Windows / Linux desktop replaces the Electron placeholder icon with the Multica asterisk",
+          "Orphaned timeline replies are now correctly surfaced",
+          "Timeline comment pagination budget excludes activities, so heavy activity no longer crowds out real comments",
+        ],
+      },
+      {
+        version: "0.2.27",
+        date: "2026-05-07",
+        title: "Smoother Chat, GitHub Skill Import & Stability Fixes",
+        changes: [],
+        features: [
+          "Import reusable skills directly from GitHub links",
+        ],
+        improvements: [
+          "Chat and Inbox feel smoother, with clearer history, easier reply copying, and faster triage after archiving",
+          "Issue actions keep more context, from easier access to the local folder to sub-issues inheriting the right project and status",
+          "Autopilots pause themselves after repeated failures, so noisy automations are easier to catch and fix",
+        ],
+        fixes: [
+          "Chinese input, desktop updates, long issue timelines, and live status updates are more reliable",
+        ],
+      },
       {
         version: "0.2.26",
         date: "2026-05-06",

apps/web/features/landing/i18n/types.ts

@@ -20,7 +20,7 @@ type FooterGroup = {
 };
 
 export type LandingDict = {
-  header: { github: string; login: string; dashboard: string };
+  header: { github: string; login: string; dashboard: string; changelog: string };
   hero: {
     headlineLine1: string;
     headlineLine2: string;

apps/web/features/landing/i18n/zh.ts

@@ -7,6 +7,7 @@ export function createZhDict(allowSignup: boolean): LandingDict {
     github: "GitHub",
     login: "\u767b\u5f55",
     dashboard: "\u8fdb\u5165\u5de5\u4f5c\u53f0",
+    changelog: "\u66f4\u65b0\u65e5\u5fd7",
   },
 
   hero: {
@@ -283,6 +284,195 @@ export function createZhDict(allowSignup: boolean): LandingDict {
       fixes: "问题修复",
     },
     entries: [
+      {
+        version: "0.3.0",
+        date: "2026-05-14",
+        title: "Squads 与附件预览",
+        changes: [],
+        features: [
+          "Squads 支持把任务交给一个小组，由 leader agent 负责协调下一步",
+          "附件可以直接预览，支持 PDF、音频、视频、Markdown、代码、日志和纯文本",
+          "中文姓名支持用拼音搜索，适用于 mention、负责人、订阅人、agents、projects 和 squads",
+        ],
+        improvements: [
+          "Squad 页面补齐成员管理、从 squad 内快速创建 agent、清晰的成员操作按钮，以及更宽的详情布局",
+          "快速创建和各类选择器更容易搜索，并能识别 squad 相关的指派和提及",
+          "Usage 图表可以在费用和 token 视图之间切换，并复用 runtime 的时区控制",
+          "工作区管理员可以通过命令行管理 squads，并在必要时停止失控的 issue 执行",
+          "共享界面文案的中英文翻译更完整",
+        ],
+        fixes: [
+          "当成员已经明确把讨论指向某个人或小组时，Squad leader 不再重复发言",
+          "提及 squad 时会正确唤起对应 leader，同时保留私有 agent 的访问限制",
+          "删除 Issue 后列表刷新更准确，后续评论也不再触发过期的 Done 回复",
+          "在撰写或编辑 issue 和评论时新增的附件，也可以稳定使用预览",
+        ],
+      },
+      {
+        version: "0.2.32",
+        date: "2026-05-13",
+        title: "用量洞察、聊天重命名与桌面体验优化",
+        changes: [],
+        features: [
+          "Usage 页面集中展示 workspace 和 project 的 token 使用、runtime 趋势和 agent 排名",
+          "聊天会话可以直接在聊天页顶部重命名",
+          "反馈时可以附带截图或文件，方便团队快速理解问题",
+        ],
+        improvements: [
+          "Dashboard 更名为 Usage，并加入更清晰的 agent 排行展示",
+          "新聊天和消息完成状态切换更顺，不再频繁闪加载状态",
+          "自托管 GitHub 配置更完整，文档里的云端链接也已修正",
+          "用户安装的 Codex Skills 会自动带入新的 agent 任务",
+        ],
+        fixes: [
+          "没有输出内容但成功完成的 agent 任务会显示为 completed，不再误判为 blocked",
+          "在指令编辑器中粘贴的 mention 会保留可点击链接",
+          "Linux 桌面端下载附件时走系统原生流程，关闭标签页也不再触发循环跳转",
+          "Gemini 和 Windows runtime 的启动检查更稳定，适合无人值守执行",
+          "添加项目资源时，较长的 GitHub 仓库列表可以正常滚动",
+        ],
+      },
+      {
+        version: "0.2.31",
+        date: "2026-05-12",
+        title: "GitHub 集成、聊天附件与 Issue 定位优化",
+        changes: [],
+        features: [
+          "接入 GitHub 后，关联的 Pull Request 会显示在 Multica Issue 中，状态会同步到 Multica，关闭 PR 后会自动关闭对应 Issue",
+          "聊天消息支持添加文件附件和图片预览",
+          "Agent 和 runtime 可以设置公开或私有，方便控制团队可见范围",
+          "停止单个 agent 任务前会先弹出确认，避免误操作",
+          "新增 GitHub 集成文档，覆盖托管版和自托管配置",
+        ],
+        improvements: [
+          "打开 Issue 链接时，会更稳定地定位到指定评论或动态",
+          "很长的 Issue 时间线滚动更顺畅",
+          "反馈入口更明确地引导用户到 GitHub 参与讨论和反馈",
+          "自托管 Caddy 配置文档补充实时连接要求",
+          "Linux 桌面端安装包恢复显示 Multica 应用图标",
+        ],
+        fixes: [
+          "下载附件时保留原始文件名",
+          "本地附件访问更稳定，上传按钮会等文件准备好后再可用",
+          "创建 Issue 弹窗里的文本框高度显示正确",
+          "Runtime 文档入口跳转到正确页面",
+        ],
+      },
+      {
+        version: "0.2.30",
+        date: "2026-05-11",
+        title: "Issue 内 Mermaid、Runtime 时区聚合与离开 Workspace 自动吊销",
+        changes: [],
+        features: [
+          "Issue 描述内联渲染 Mermaid 图表",
+          "Sub-issue 行支持就地切换状态与 assignee，并支持跨行批量选中",
+          "Token 用量按每个 runtime 自己的时区聚合，每日 rollup 与本地日期对齐",
+          "私有 Agent 通过 `allowed_principals` 判定可见性，权限粒度更细",
+          "成员离开或被移出 workspace 时，自动吊销其名下的 runtime",
+          "对未维护的模型支持自定义 token 价格，使用量真实反映成本",
+          "Landing 页面 header 加入 Changelog 入口",
+        ],
+        improvements: [
+          "服务端删除 runtime 时，daemon 端自我修复，不再留下僵尸条目",
+          "Chat 与评论输入框统一使用 `Mod+Enter` 发送",
+          "Copilot CLI 模型目录补齐正确的 dotted ID",
+          "Copilot 失败详情直接在 UI 中透出，不再只是一个通用错误",
+          "Daemon brief 直接内联进 system prompt，针对需要的 provider 生效",
+          "Realtime WebSocket 放行同源升级，移动端与 CLI 可正常握手",
+        ],
+        fixes: [
+          "Recent issues 列表不再跨 workspace 串扰",
+          "CloudFront 附件下载链接在点击时重新签名，过期预览的问题修复",
+          "所有 provider 的 Windows reply 模板改用 `--content-file`，非 ASCII 内容不再丢失",
+          "Daemon 抑制 Windows 上多余的 git 控制台弹窗",
+          "Pi 插件工具不再被硬编码的 `--tools` allowlist 过滤掉",
+          "Inbox 在 issue 加载完成后再滚动到目标评论",
+          "`autopilot create/update` 允许 `--mode run_only`",
+          "Changelog header 链接样式对齐 GitHub ghost button",
+          "OpenAI Codex / GPT 模型价格补齐，使用成本不再显示为 $0",
+        ],
+      },
+      {
+        version: "0.2.29",
+        date: "2026-05-09",
+        title: "Quick Create 项目选择器、评论可折叠与 Timeline 性能优化",
+        changes: [],
+        features: [
+          "Quick Create 支持选择 project，并记住上一次的选项",
+          "评论 thread 支持解决并折叠，长讨论看起来更清爽",
+          "Issue Live Banner 显示 agent 队列中等待执行的任务",
+          "失败 / 取消的任务可以在 Execution Log 一键重跑",
+          "Agent Create 弹窗新增放大按钮，长描述编辑更舒服",
+        ],
+        improvements: [
+          "Issue Timeline 不再因每个 WS 事件做完整 re-render，长 Issue 滚动更顺",
+          "Editor 跳过对超大文本 / JSON 粘贴的解析，避免卡顿",
+          "Autopilot 在 assignee runtime 离线时跳过 dispatch，避免空跑",
+          "Inbox 自动归档处于终态的 `task_failed` 行",
+          "Hermes 把 agent instructions 直接随请求内联传入",
+          "Timeline / Comment 改为纯客户端虚拟化，去掉服务端分页",
+          "Reserved slugs 前后端共享同一份 JSON，CI 守住漂移",
+          "ACP 错误消息现在带上 JSON-RPC 的 `error.data` 字段，排错更友好",
+        ],
+        fixes: [
+          "429 / 余额不足的 agent run 现在被标记为 `failed` 而不是 `completed`",
+          "因 poisoned image 卡死的 agent session 可以恢复，issue 不再卡住",
+          "`pi --list-models` 表格格式可被正确解析，模型发现恢复",
+          "`pi` colon-to-slash 归一化只作用于 legacy 格式，避免误伤新格式",
+          "`kiro` 与 `kimi` 加入 inline-system-prompt provider 白名单",
+          "Priority Dropdown 徽章颜色对齐 PriorityIcon 的 semantic token",
+          "Agent 单行长消息可正常展开",
+          "桌面端复制 issue link 使用当前连接环境，不再硬编码 localhost",
+          "移动端 WebSocket 在没有 cookie 的情况下也能握手",
+          "创建 workspace 时校验保留字，slug 错误提示已 i18n",
+          "Timeline 在 falsy prop 切换时正确同步 around 状态",
+          "DropdownMenu 弹层尺寸跟随内容",
+        ],
+      },
+      {
+        version: "0.2.28",
+        date: "2026-05-08",
+        title: "Daemon 磁盘占用 CLI、Timeline 打磨与任务用量聚合提速",
+        changes: [],
+        features: [
+          "新增 `multica daemon disk-usage` CLI，按 task / workspace 维度查看磁盘占用",
+          "Skill Picker 弹窗新增搜索框，Agent 设置里挑技能更快",
+          "Daemon GC 覆盖扩展到 chat、autopilot、quick-create 任务",
+          "Issue 详情页面包屑直接显示 MUL-xxxx identifier",
+        ],
+        improvements: [
+          "Timeline 分页 size 提到 50，评论与活动按池独立 keyset 游标，长 Issue 翻页更顺",
+          "Show older / newer 按钮在边界场景也能正确出现，且视觉上更明显是可点击的",
+          "服务端 `task_usage` 聚合到每日 rollup 表，DB 负载明显下降",
+          "Daemon health check 在 repo 查询时不再阻塞，始终保持响应",
+          "Runtime 统计排除已归档的 agent，活跃数字更准",
+        ],
+        fixes: [
+          "Linux 上 daemon self-restart 改走 `brew prefix` 软链，Homebrew Cellar 删除后不再让 runtime 失联",
+          "CLI 短 ID 现在可以正确路由，复制粘贴的短前缀不再 404",
+          "Windows 上非 ASCII 字符评论 / 描述输入新增 `--content-file` / `--description-file`",
+          "Windows / Linux 桌面端用 Multica asterisk 替换 Electron 默认占位图标",
+          "Timeline 中孤立的 reply 现在会被正确捞回展示",
+          "Timeline 评论分页预算不再把 activity 算进去，避免活动多时挤掉真实评论",
+        ],
+      },
+      {
+        version: "0.2.27",
+        date: "2026-05-07",
+        title: "Chat 更顺手，Skill 支持 GitHub 导入，稳定性更好",
+        changes: [],
+        features: [
+          "支持直接通过 GitHub 链接导入可复用 Skill",
+        ],
+        improvements: [
+          "Chat 和 Inbox 更顺手，历史更清晰，复制回复更方便，归档后能更快处理下一项",
+          "Issue 操作会保留更多上下文，例如更容易找到对应本地文件夹，子 Issue 也会带上正确的项目和状态",
+          "Autopilot 连续失败后会自动暂停，异常自动化更容易发现和修复",
+        ],
+        fixes: [
+          "中文输入、桌面端升级、长 Issue 时间线和实时状态展示更稳定",
+        ],
+      },
       {
         version: "0.2.26",
         date: "2026-05-06",

apps/web/platform/navigation.tsx

@@ -22,6 +22,8 @@ function NavigationProviderInner({
     back: router.back,
     pathname,
     searchParams: new URLSearchParams(searchParams.toString()),
+    getShareableUrl: (path: string) =>
+      typeof window === "undefined" ? path : window.location.origin + path,
   };
 
   return <NavigationProvider value={adapter}>{children}</NavigationProvider>;

docker-compose.selfhost.yml

@@ -58,9 +58,11 @@ services:
       APP_ENV: ${APP_ENV:-production}
       MULTICA_DEV_VERIFICATION_CODE: ${MULTICA_DEV_VERIFICATION_CODE:-}
       MULTICA_APP_URL: ${MULTICA_APP_URL:-http://localhost:3000}
-      ALLOW_SIGNUP: ${ALLOW_SIGNUP:-true}                                     
-      ALLOWED_EMAILS: ${ALLOWED_EMAILS:-}                                     
-      ALLOWED_EMAIL_DOMAINS: ${ALLOWED_EMAIL_DOMAINS:-} 
+      ALLOW_SIGNUP: ${ALLOW_SIGNUP:-true}
+      ALLOWED_EMAILS: ${ALLOWED_EMAILS:-}
+      ALLOWED_EMAIL_DOMAINS: ${ALLOWED_EMAIL_DOMAINS:-}
+      GITHUB_APP_SLUG: ${GITHUB_APP_SLUG:-}
+      GITHUB_WEBHOOK_SECRET: ${GITHUB_WEBHOOK_SECRET:-}
     restart: unless-stopped
 
   frontend:

docs/agent-quick-create-plan.md

@@ -0,0 +1,555 @@
+# Agent 快速创建 — 三阶段实施计划
+
+> Status: Draft (设计阶段,未动工)
+> Owner: TBD
+> Last updated: 2026-05-13
+
+## TL;DR
+
+- **目标**:降低用户创建 Agent 的门槛,从「手工填表 + 一个个挑 skill」演进到「一键模板」「AI 推荐 skill」「AI 直接创建 agent」三档
+- **三阶段**:Template(必做、独立)→ Skill Finder(AI 推荐 skill)→ AI Create Agent(AI 直接创建)
+- **架构关键**:Phase 2/3 复用现有 Quick-create Issue 基础设施(派任务给 agent + tool calling + inbox 通知),不引入新 LLM 调用路径
+- **不需要新基础设施**:无 SSE、无 server-side LLM、无新 WS channel
+- **soft blocker**:两处 routine 重构(`createSkillWithFiles` TX 拆分、skill 同名 find-or-create)
+- **不做**:接入 Anthropic 官方 marketplace(plugin 体系跟单体 skill 形态不匹配)、接入 ClawHub(战略对位错误 + 实际使用率低,见 §5)
+
+---
+
+## 1. 背景与目标
+
+### 1.1 当前现状
+
+当前用户创建一个 Agent 需要走的步骤:
+
+1. 进 `/agents` 页面 → 点 "Create Agent"
+2. 手工填 name / description / runtime / model
+3. 手工写 instructions(空白文本框,用户自己思考措辞)
+4. 创建完后进 Agent 详情页 → 点 "Add Skill" → 一个一个挑 skill 关联
+5. 如果 workspace 还没有需要的 skill,得先去别处建/导入 skill(`POST /api/skills/import` 支持 skills.sh / GitHub / ClawHub 三种 URL)
+
+**痛点**:
+- 用户得**预先知道**自己需要哪些 skill,这要求他对 skill 生态熟悉
+- 写 instructions 是空白文本编辑,大多数用户不知道写什么
+- 跨多页操作,体感上"创建一个能用的 Agent"是个项目,不是个动作
+
+### 1.2 三阶段方案
+
+| Phase | 提供给用户的能力 | 是否需要 AI | 独立可发布 |
+|---|---|---|---|
+| **1. Template** | 选模板 → 自动 import 模板带的 skill + 预填 instructions | 否 | ✅ |
+| **2. Skill Finder** | 描述需求 → AI 推荐 skill 列表 → 一键导入到 workspace | ✅ | ✅(独立功能,任何场景都能用) |
+| **3. AI Create Agent** | 描述需求 → AI 自己 find skill + 写 instructions + 创建 agent | ✅ | 依赖 Phase 2 |
+
+每个 phase **本身有用户价值**,不需要等下一个 phase 才能用:
+- Phase 1 用户能用模板创建 agent,即使后两阶段没做
+- Phase 2 用户能在任何地方"用 AI 找 skill"(创建 agent 时、给现有 agent 加 skill 时、单纯逛 skill 时)
+- Phase 3 是 1+2 的组合
+
+### 1.3 不在范围内
+
+明确不做的事(及理由,见 §5):
+- 接入 Anthropic 官方 plugin marketplace(`anthropics/claude-plugins-official`)
+- 接入 ClawHub 的"发现/搜索"层(import 路径已经存在,但是死代码,建议下线)
+- 让 AI 直接装 skill 到用户本地 `~/.claude/skills/`(npx skills CLI 行为)
+- Server-side LLM 调用(后端目前没有 LLM SDK,这条路引入新基础设施,而 Quick-create 模式可以避开)
+
+---
+
+## 2. 关键概念回顾
+
+> 这一节给没参与前期讨论的同事看。已经熟悉 skill 系统的可跳到 §3。
+
+### 2.1 Skill 是什么
+
+Skill 是一个**按需加载的能力包**,本质是 SKILL.md 文件 + 可选附件。Anthropic 2025-12 把它发布为开放标准(agentskills.io),Cursor / OpenAI / GitHub Copilot 等都已采纳——同一份 SKILL.md 跨多个 agent 工具都能用。
+
+每个 runtime(Claude Code / Cursor / Codex 等)启动时**自动扫**自己约定的目录(`~/.claude/skills/`、`.cursor/skills/` 等),读 SKILL.md 的 frontmatter 形成"我手上有这些 skill"的清单注入 system prompt。具体 skill 正文只在被触发时才进 context。
+
+### 2.2 Multica 的 Skill 数据模型
+
+3 张表(migration `008_structured_skills.up.sql`):
+
+| 表 | 关键字段 |
+|---|---|
+| `skill` | `id, workspace_id, name, description, content (=SKILL.md 正文), config (含 origin 元数据)` |
+| `skill_file` | `skill_id, path, content`(SKILL.md 的附件,如 examples/*.md、scripts/*.py) |
+| `agent_skill` | `agent_id, skill_id`(M:N 关联) |
+
+**关键约束**:`UNIQUE(workspace_id, name)` — 同 workspace 内 skill 名字必须唯一。
+
+### 2.3 Skill 流转链路(数据库 → runtime)
+
+任务运行时,skill 从 PG 到 runtime 的完整路径:
+
+```
+1. 数据库:skill + skill_file + agent_skill 三张表的行
+
+2. Daemon claim 任务:
+   POST /api/runtimes/{runtimeId}/tasks/claim
+   handler/daemon.go:1018-1098 (ClaimTaskByRuntime)
+   → service/task.go:1447-1463 (LoadAgentSkills)
+   → 把 agent 关联的所有 skill 全文塞进 HTTP 响应
+
+3. Daemon 算工作目录:
+   server/internal/daemon/execenv/execenv.go:114, 124
+   workDir = {WorkspacesRoot}/{wsID}/{shortTaskID}/workdir
+
+4. Daemon 按 runtime 算 skill 目录:
+   server/internal/daemon/execenv/context.go:121-158 (resolveSkillsDir)
+   claude   → {workDir}/.claude/skills
+   cursor   → {workDir}/.cursor/skills
+   codex    → 特殊:{codexHome}/skills
+
+5. Daemon 把字符串写成磁盘文件:
+   context.go:175-204 (writeSkillFiles)
+   核心就两行 os.WriteFile
+
+6. Daemon 启动 runtime,cwd = workDir
+   runtime 自己扫 .claude/skills/(等)→ 加载 frontmatter
+
+7. 任务结束:os.RemoveAll(workDir)
+   PG 是真相源,workDir 是每次任务临时复印件
+```
+
+**核心 invariant**:Multica 不教 runtime 怎么用 skill,只把文件摆到 runtime 已经会扫的位置。
+
+### 2.4 Template = Instructions + Skill 引用
+
+Template 是个**静态 JSON 定义**,包含:
+- 预写好的 instructions
+- 一组 skill 引用(用 URL 指向 skills.sh / GitHub)
+
+用户选模板时,后端:
+1. 对每个 skill 引用,**复用现有 `/api/skills/import` 的 fetcher**(`fetchFromSkillsSh` / `fetchFromGitHub`)拉内容
+2. 物化到 workspace(同名复用 / 新建)
+3. CreateAgent + setAgentSkills
+4. 整个流程一个事务
+
+skill 引用为什么用 URL 而不是内联 SKILL.md 内容:
+- 复用现有 import 基础设施,零新代码
+- skill 内容跟 GitHub 同步,不需要 vendoring 进 multica 仓库
+- 模板 JSON 体积小,git review 友好
+
+### 2.5 Quick-create Issue 模式(Phase 2/3 复用的基础设施)
+
+当前 `POST /api/issues/quick-create`(handler/issue.go:877-982)的流程:
+
+```
+1. 后端 enqueue 任务:
+   - agent_task_queue 加一行,issue_id = NULL,context JSONB = {type: "quick-create", prompt: ...}
+   - 立即返回 202 Accepted + task_id
+
+2. Daemon claim 任务时识别 quick-create:
+   - 检查 task.Context != nil AND !task.IssueID.Valid
+   - 解析为 QuickCreateContext (service/task.go:1810-1811)
+
+3. Daemon 构造 prompt:
+   - daemon/prompt.go:45-106 (buildQuickCreatePrompt)
+   - 把用户的自然语言 prompt 作为语义核心
+   - 加上"调用 multica issue create CLI 命令"的指令
+
+4. Agent 跑 LLM + tool calling:
+   - LLM 输出形如 `multica issue create --title="..." --description="..."` 的命令
+   - daemon 执行 CLI 命令,CLI 调 POST /api/issues 创建 issue
+   - CLI 自动在请求里带上 MULTICA_QUICK_CREATE_TASK_ID env(daemon/daemon.go:2081)
+     → 让创建出来的 issue 带 origin_type='quick_create' + origin_id=<task_id>
+
+5. 后端 link + 通知:
+   - 完成检测:GetIssueByOrigin(workspace_id, "quick_create", task_id)
+   - LinkTaskToIssue(task_id, issue_id) 把任务行的 issue_id 补上
+   - 写 inbox_item 通知用户(notifyQuickCreateCompleted, service/task.go:1908-1920)
+```
+
+**关键洞察**:这个模式**完全通用化**了。复用它只需要:
+1. 新的 context JSONB type(比如 `"skill-find"`、`"agent-create"`)
+2. 新的 prompt builder
+3. 新的"完成检测 + inbox 通知"
+
+不需要任何 daemon / 任务队列层面的改动。
+
+---
+
+## 3. 三阶段详细设计
+
+### Phase 1:Agent Template
+
+**目标**:用户选模板 → 一键得到一个可用的 agent(自带 skill + instructions),不需要 AI 参与。
+
+#### 设计
+
+- **Template 定义存放**:静态 JSON,commit 在 `server/internal/agenttmpl/templates/*.json`
+- **Template JSON 形态**:
+  ```json
+  {
+    "slug": "code-reviewer",
+    "name": "Code Reviewer",
+    "description": "审代码用的 agent",
+    "instructions": "你审代码,关注 N+1 查询、错误处理、类型安全...",
+    "skills": [
+      { "source_url": "https://skills.sh/obra/superpowers/tdd" },
+      { "source_url": "https://github.com/foo/bar/tree/main/skills/code-style" }
+    ]
+  }
+  ```
+- **新 endpoint**:`POST /api/agents/from-template`
+  - 请求:`{template_slug, name, runtime_id, ...overrides}`
+  - 后端流程(**全部在一个事务里**):
+    1. 加载 template JSON
+    2. 对每个 skill source_url:
+       - 调用 `detectImportSource(url)`(skill.go:586-617)分发到对应 fetcher
+       - 通过 GetSkillByWorkspaceAndName 检查 workspace 是否已有同名 skill
+         - 有 → 复用现有 skill_id
+         - 无 → 调 `createSkillWithFilesInTx`(待重构,见 §4)物化
+    3. `CreateAgent`(复用 agent.go:CreateAgent 的内部逻辑)
+    4. 批量 `AddAgentSkill` 关联
+  - 响应:`{agent: {...}, imported_skill_ids: [...], reused_skill_ids: [...]}`
+- **前端**:`CreateAgentDialog`(packages/views/agents/components/create-agent-dialog.tsx)加 "From template" 模式,跟现有 manual / duplicate 模式并列
+  - 模板选择器 → 预览(instructions + skill 列表)→ 提交调新 endpoint
+  - 响应里的 `reused_skill_ids` 用 toast 提示"以下 skill 已存在,沿用了 workspace 现有版本"
+
+#### 起步模板清单(初版,可调)
+
+- `code-reviewer` — 代码审查
+- `tdd-pair` — TDD 配对编程
+- `db-reviewer` — 数据库 / SQL 审查
+- `pr-summarizer` — PR 摘要
+- `docs-writer` — 文档撰写
+
+具体每个模板选哪些 skill URL,在 Phase 1 启动时单独决定(需要逛 skills.sh 选高质量 skill)。
+
+#### Phase 1 改动清单
+
+| 文件 / 位置 | 改动 |
+|---|---|
+| `server/internal/agenttmpl/`(新包) | 加载 JSON 模板的代码 |
+| `server/internal/agenttmpl/templates/*.json`(新文件) | 5 个起步模板 |
+| `server/internal/handler/agent.go` | 新 handler `CreateAgentFromTemplate` |
+| `server/internal/handler/skill_create.go` | **重构**:拆出 `createSkillWithFilesInTx` 变体(见 §4) |
+| `server/pkg/db/queries/skill.sql` | 加 `GetSkillByWorkspaceAndName`(见 §4) |
+| `server/cmd/server/router.go` | 注册新 endpoint |
+| `packages/views/agents/components/create-agent-dialog.tsx` | 加 template 模式 |
+| `packages/core/api/agent.ts` | 加 `createAgentFromTemplate` API 调用 |
+| `packages/views/agents/components/template-picker.tsx`(新文件) | 模板选择器组件 |
+
+### Phase 2:Skill Finder
+
+**目标**:用户用自然语言描述需求(如"我想审 SQL"),AI 推荐一组 skill,用户勾选一键导入到 workspace。
+
+#### 设计
+
+- **架构选型**:走 quick-create 模式,**不是后端直接调 LLM**
+- **新 endpoint**:`POST /api/skills/find`
+  - 请求:`{prompt, agent_id}`(agent_id 是用来跑这个 LLM 任务的 agent,跟 Quick-create Issue 一样要求预先有 agent)
+  - 后端流程:
+    1. enqueue 任务:`agent_task_queue` 加一行,context JSONB = `{type: "skill-find", prompt}`
+    2. 返回 202 + task_id
+- **Daemon prompt builder**:`daemon/prompt.go` 加 `buildSkillFindPrompt`(类比 buildQuickCreatePrompt)
+  - 喂给 agent 的 prompt 大致:
+    ```
+    用户需求:{user_prompt}
+    
+    你的任务:从以下 curated skill 清单里选 3-5 个最相关的推荐给用户。
+    
+    可选 skill 清单(JSON):
+    {curated_skill_index}
+    
+    输出:调用 `multica skill find --output-results '<JSON>'` 命令,
+    JSON 形态为 [{name, description, source_url, reason}, ...]
+    ```
+- **CLI 命令**(新):`multica skill find --output-results <JSON>`
+  - 不发起 HTTP 请求,只把 JSON 写到 daemon 通过 env 指定的临时文件
+  - daemon 读这个文件,把内容塞进 inbox notification 的 payload
+- **Curated skill 索引**:`server/internal/agenttmpl/skill_index.json`(新文件)
+  - 几十到上百条精选 skill,每条:`{name, description, source_url, tags, install_count}`
+  - 维护方式:工程师/产品手工维护,代码 review 卡内容质量
+  - MVP **不做**实时 GitHub Code Search 或 skills.sh 爬虫
+- **完成通知**:写 inbox_item,type = `skill_find_done`,payload 含推荐结果数组
+- **前端**:
+  - 独立"Find Skill"页面(`/skills/find` 或 `/skills?ai=true`)
+  - skill list page 上"用 AI 找 skill"按钮入口
+  - 用户输入 prompt → 提交 → 等通知 → inbox item 里展示 skill 卡片(name + description + source_url + reason)
+  - 用户勾选 → 一键批量调现有 `POST /api/skills/import`(每个 skill 一次,可考虑加 batch endpoint 但 MVP 不必要)
+
+#### Phase 2 改动清单
+
+| 文件 / 位置 | 改动 |
+|---|---|
+| `server/internal/handler/skill.go` | 新 handler `FindSkill`(enqueue task) |
+| `server/internal/service/task.go` | 加 `EnqueueSkillFindTask` + 完成检测 + inbox 通知 |
+| `server/internal/daemon/prompt.go` | 加 `buildSkillFindPrompt` |
+| `server/internal/daemon/daemon.go` | 加 `SkillFindContext` 识别 + env 注入 |
+| `server/cmd/multica/cmd_skill.go` | 加 `find --output-results` 子命令 |
+| `server/internal/agenttmpl/skill_index.json`(新文件) | curated 清单 |
+| `packages/views/skills/components/find-skills-dialog.tsx`(新文件) | UI |
+| `packages/core/api/skill.ts` | 加 `findSkills` API |
+| `packages/views/inbox/items/skill-find-result.tsx`(新文件) | inbox item 渲染 |
+
+### Phase 3:AI Create Agent
+
+**目标**:用户描述需求,AI 自己 find skill + 写 instructions + 创建 agent。
+
+#### 设计
+
+- **架构选型**:走 quick-create 模式,**组合 Phase 2 的 find 能力 + 新的 agent create CLI**
+- **新 endpoint**:`POST /api/agents/ai-draft`
+  - 请求:`{prompt, host_agent_id}`(host_agent_id 是跑这个元任务的 agent)
+  - 后端:enqueue 任务,context = `{type: "agent-create", prompt}`,返回 202 + task_id
+- **Daemon prompt builder**:`buildAgentCreatePrompt` 指挥 agent 三步走:
+  ```
+  1. 调用 `multica skill find --output-results ...` 选 skill
+     (或直接看 curated 清单选)
+  2. 基于选定 skill 写 instructions
+  3. 调用 `multica agent create --name ... --instructions ... --skill-ids ...`
+     创建 agent 并关联 skill
+  ```
+- **CLI 命令**(新):`multica agent create`
+  - 后端 handler 已存在(handler/agent.go:CreateAgent),只需要绑 CLI(~50 行)
+  - 创建时带 `MULTICA_AI_DRAFT_TASK_ID` env,服务端用它做 origin 标记 + LinkTaskToAgent
+- **完成通知**:inbox_item type = `agent_draft_done`,payload 含 agent_id + 摘要
+- **前端**:`CreateAgentDialog` 加 "AI" 模式
+  - 输入需求 → 提交 → 等通知 → inbox 通知里点击 → 跳新 agent 详情页(用户在那儿编辑/调整)
+
+#### Phase 3 改动清单
+
+| 文件 / 位置 | 改动 |
+|---|---|
+| `server/internal/handler/agent.go` | 新 handler `AIDraftAgent`(enqueue task) |
+| `server/internal/service/task.go` | 加 `EnqueueAgentDraftTask` + 完成检测 + inbox 通知 |
+| `server/internal/daemon/prompt.go` | 加 `buildAgentCreatePrompt` |
+| `server/cmd/multica/cmd_agent.go` | 加 `create` 子命令(handler 已有) |
+| `packages/views/agents/components/create-agent-dialog.tsx` | 加 "AI" 模式 |
+| `packages/core/api/agent.ts` | 加 `aiDraftAgent` API |
+| `packages/views/inbox/items/agent-draft-result.tsx`(新文件) | inbox item 渲染 |
+
+---
+
+## 4. Blocker 清单与修复方案
+
+### 4.1 [SOFT] `createSkillWithFiles` 不可组合事务
+
+**问题**:`server/internal/handler/skill_create.go:21-71` 这个函数自己 `Begin()` 一个事务,执行完 `Commit()`。Phase 1 需要在外层事务里**多次**调用它(import N 个 skill + createAgent + setAgentSkills 都在一个 TX),但现在没法这么用。
+
+**影响范围**:Phase 1
+
+**修复方案**:
+
+```go
+// 拆成两个函数(保持原 API 向后兼容):
+
+// 新增:接受外部 qtx,不管事务
+func createSkillWithFilesInTx(
+    ctx context.Context,
+    qtx *db.Queries,
+    input skillCreateInput,
+) (*SkillWithFilesResponse, error) {
+    // 不 Begin/Commit,只调 qtx.CreateSkill + qtx.UpsertSkillFile loop
+}
+
+// 改造:原函数变成包装层,内部调 InTx 版
+func (h *Handler) createSkillWithFiles(
+    ctx context.Context,
+    input skillCreateInput,
+) (*SkillWithFilesResponse, error) {
+    tx, _ := h.TxStarter.Begin(ctx)
+    defer tx.Rollback()
+    qtx := h.Queries.WithTx(tx)
+    result, err := createSkillWithFilesInTx(ctx, qtx, input)
+    if err != nil { return nil, err }
+    tx.Commit()
+    return result, nil
+}
+```
+
+旧调用方完全不变。Phase 1 新 endpoint 自己 Begin,然后多次调 `*InTx` 变体,最后统一 Commit。
+
+**工作量**:小(< 100 行重构)
+
+### 4.2 [SOFT] Skill 同名冲突
+
+**问题**:`skill` 表有 `UNIQUE(workspace_id, name)` 约束。Phase 1 模板导入时,如果模板里的 skill 跟 workspace 已有 skill 同名,INSERT 会报 PG 错误 23505,整个 from-template 流程挂掉。
+
+**影响范围**:Phase 1
+
+**修复方案**:加 find-or-create 模式:
+
+1. 新 query `GetSkillByWorkspaceAndName`(`server/pkg/db/queries/skill.sql`)
+2. Phase 1 流程改成:
+   - 对每个模板 skill,先查 workspace 是否已有同名
+   - 有 → 复用现有 skill_id,跳过 import
+   - 无 → 调 `createSkillWithFilesInTx` 物化
+3. 响应里返回 `reused_skill_ids: [...]`,前端 toast "以下 skill 已存在,沿用现有版本"
+
+**不选择"覆盖"或"加后缀"的原因**:用户可能已经改过本地版本,覆盖会丢用户修改;加后缀污染 skill 列表。
+
+**工作量**:小(< 50 行 + 1 条 sqlc query)
+
+### 4.3 [SOFT] 缺 `multica skill find` CLI
+
+**影响范围**:Phase 2
+
+**方案**:加一个 CLI 子命令,模仿 `multica skill import` 的实现(`server/cmd/multica/cmd_skill.go:55-60, 323-357`)。**注意**:这个命令不发 HTTP 请求,只是 LLM agent 用来"输出推荐结果"的 channel——它把 LLM 推荐的 JSON 写到 daemon 指定的临时文件,daemon 读完塞进 inbox notification。
+
+**工作量**:小(~80 行)
+
+### 4.4 [SOFT] 缺 `multica agent create` CLI
+
+**影响范围**:Phase 3
+
+**方案**:后端 handler 已有(`handler/agent.go:CreateAgent`),只需在 `server/cmd/multica/cmd_agent.go` 加 `create` 子命令。
+
+**工作量**:小(~50 行)
+
+### 4.5 [非 blocker] System Agent 问题
+
+**之前误判为 hard blocker,实际不是**:
+
+Quick-create Issue 当前的设计就要求用户**预先有一个 agent** 才能用——AI 路径不为"零 agent 起步"服务。Phase 2/3 沿用这个前提,所以**新 workspace 没 agent 时 AI 功能不可用**是符合现有产品模型的,不需要 bootstrap 一个 system agent。
+
+产品自然解锁路径:
+1. 新用户进 workspace
+2. 用 **Phase 1 Template**(无需 AI、无需现有 agent)创建第一个 agent
+3. 之后 Phase 2/3 即可用,host_agent 就用刚创建的那个
+
+---
+
+## 5. 关键设计决策(及理由)
+
+### 5.1 为什么不接 Anthropic 官方 marketplace?
+
+**结构错配**。Anthropic 官方 marketplace(`anthropics/claude-plugins-official`)是 **plugin 体系**:每个 plugin 是个 bundle,包含 `.claude-plugin/plugin.json` + `skills/` + `agents/` + `hooks/` + `.mcp.json`。
+
+Multica 只有**单体 skill**(SKILL.md + skill_file),没有 plugin / bundle 概念。要接入得新写 plugin parser + 拆分逻辑,工作量大,而 skills.sh 已经覆盖了同一批高质量内容(skills.sh 后端就是 GitHub raw,绝大多数 skill 作者就在 GitHub 上,Anthropic plugin 体系里的 skill 通常也在作者的 GitHub repo 里有单体副本)。
+
+### 5.2 为什么走 quick-create 模式而不是后端直接调 LLM?
+
+代码事实:`server/` 目前**完全没有任何 LLM SDK**(grep `anthropic-sdk-go` / `openai-go` / 任何 LLM provider 都是 0 命中)。所有 LLM 调用都通过 daemon → runtime → CLI 这条路。
+
+走 quick-create 模式的优势:
+- **不引入新基础设施**(SSE / LLM client / API key 管理)
+- **复用 agent 的 instructions / model / runtime 配置**(用户已经在某个 agent 里配置过的偏好自动生效)
+- **统一计费 / 用量监控**(LLM 调用都计在用户 agent 的 quota 里)
+
+代价:
+- 用户得**预先有一个 agent**(参见 §4.5,这跟 Quick-create Issue 现状一致)
+- LLM 调用通过 daemon 多一跳,延迟略增(但不阻塞 202 响应)
+
+### 5.3 为什么 Skill Finder 是 endpoint 不是 SKILL.md?
+
+**Skill Finder 名字里的 "Skill" 是它的产物(找的是 skill),不是它自己实现成 SKILL.md**。
+
+如果做成 SKILL.md 文件:
+- 它得装进某个 agent 里才能用 → 单点功能变得需要前置配置
+- skill 教 agent 调什么?调 `npx skills`(装到本地,目标错)?调 Multica API(那要写 tool channel,绕一大圈)
+- AI 创建 Agent(Phase 3)那条路要"启动 agent → agent 调 skill → skill 调 tool",链路复杂三倍
+
+做成 endpoint:
+- 用户独立可用(独立 UI 入口)
+- AI 创建 Agent 后端直接调 endpoint,两个功能共用一段逻辑
+- 简单
+
+### 5.4 Curated Skill 索引 vs 实时搜索
+
+**MVP 用 curated 清单**(几十条精选 URL + 摘要 commit 在 repo 里)。理由:
+- 质量可控
+- 不踩 GitHub Code Search rate limit
+- 不被 LLM 编 URL(LLM 知识 cutoff + hallucinate URL 是真问题)
+- 维护成本低
+
+进阶可加 `search_skills(query)` tool 实时打 GitHub Code Search,等用户反馈"清单太窄"再做。
+
+### 5.5 不做 ClawHub(顺手清理建议)
+
+**现状**:`POST /api/skills/import` 当前支持 3 个 source(`fetchFromClawHub` skill.go:642-744、`fetchFromSkillsSh` skill.go:757-879、`fetchFromGitHub` skill.go:1363-1463)。ClawHub 是个独立 HTTP 客户端,不复用 GitHub 基础设施。
+
+**判断**(详见之前讨论):
+- ClawHub 服务的是 OpenClaw 平台(Multica 同生态位竞品的内容生态)
+- UI 没有发现/搜索层,用户只能粘 URL,而 ClawHub 装机量远低于 skills.sh,用户主动逛的概率极低
+- 独立代码路径,API 演进时单独跟进
+
+**建议**(独立于本计划,可以一起做也可以延后):
+- 跑 `SELECT count(*) FROM skill WHERE config->'origin'->>'type' = 'clawhub'` 看实际使用量
+- 接近 0 → 渐进下线(先去 UI SourceCard,后续 release 删 fetcher)
+- 有量 → 留着,但仍不为它做新功能
+
+---
+
+## 6. 实施依赖与排期
+
+```
+[Phase 1] Template
+  └── 独立,无依赖
+  └── 包含 2 个 soft blocker 的修复(§4.1 §4.2)
+       ↓
+[Phase 2] Skill Finder
+  └── 依赖 Phase 1 中的 skill import 路径(已存在,沿用)
+  └── 含 1 个 soft blocker(§4.3)
+       ↓
+[Phase 3] AI Create Agent
+  └── 依赖 Phase 2(复用 find skill 能力)
+  └── 含 1 个 soft blocker(§4.4)
+```
+
+**真实排期建议**:
+- Phase 1 可单独发版,有独立价值
+- Phase 2 独立可发版(找 skill 是高频独立场景)
+- Phase 3 等 Phase 2 ready 后开始
+
+每个 phase 启动时单独开 PR 设计 doc,本文档只是路线图。
+
+---
+
+## 7. 风险与缓解
+
+| 风险 | 缓解 |
+|---|---|
+| GitHub rate limit(模板 import 多个 skill 时) | 已有 `GITHUB_TOKEN` env 支持(skill.go:1163-1166),5000/h 配额够用。生产环境确保配置 |
+| 模板里引用的 skill repo 被作者删除 | from-template handler 容错:某个 skill fetch 失败 → 整个事务回滚,前端展示具体哪个 URL 挂了。模板自己也定期 review |
+| LLM 推荐编造 URL(Phase 2) | 用 curated 清单作为 context,**不让 LLM 自由发挥 URL**,推荐范围限定在清单内 |
+| Phase 3 LLM 写出离谱 instructions | 用户在 inbox 通知里点击 → 跳新 agent 详情页**编辑模式**,不直接进入"已就绪"状态。用户必须确认 |
+| 模板格式后续要演进(加字段) | Template JSON 加 `version` 字段,后端按 version 兼容老格式 |
+| Curated skill 清单过时(作者改 repo / 删 skill) | 加 CI 任务定期跑一遍清单 URL,挂掉的报警通知维护者 |
+
+---
+
+## 8. 不在本文档范围(已识别的下一步话题)
+
+- 跨 workspace 模板共享 / marketplace 化(用户能把自己的 agent 存成模板分享)
+- 实时 GitHub Code Search tool(Phase 2 进阶)
+- Server-side LLM 调用基础设施(如果未来需要 streaming 等场景)
+- ClawHub 下线决策(独立讨论,见 §5.5)
+- Skill 版本管理(workspace skill 版本号 / 升级提示)
+
+---
+
+## 附录 A:代码索引
+
+> 给接手开发的同事的快速参考。每条 file:line 都在本计划里被引用过,记录在这里方便跳转。
+
+| 主题 | 位置 |
+|---|---|
+| Skill DB 模型 | `server/migrations/008_structured_skills.up.sql:4-32` |
+| Skill 创建 handler + 事务 | `server/internal/handler/skill.go:143-162` + `skill_create.go:21-71` |
+| Skill import 入口(支持 3 个 source) | `server/internal/handler/skill.go:1538` |
+| Skill import source 分发 | `server/internal/handler/skill.go:586-617` (`detectImportSource`) |
+| Skills.sh fetcher | `server/internal/handler/skill.go:757-879` (`fetchFromSkillsSh`) |
+| GitHub fetcher | `server/internal/handler/skill.go:1363-1463` (`fetchFromGitHub`) |
+| ClawHub fetcher | `server/internal/handler/skill.go:642-744` (`fetchFromClawHub`) |
+| Agent 创建 handler | `server/internal/handler/agent.go:380-399` (request) + `:422-564` (CreateAgent) |
+| Agent 创建 sqlc | `server/pkg/db/queries/agent.sql:19-25` |
+| Agent-Skill 关联 sqlc | `server/pkg/db/queries/agent.sql:86-103` |
+| 当前 Agent Duplication(前端模式) | `packages/views/agents/components/agents-page.tsx:286-301`(post-create skill copy) |
+| Agent 创建 dialog | `packages/views/agents/components/create-agent-dialog.tsx` |
+| Skill add dialog | `packages/views/agents/components/skill-add-dialog.tsx` |
+| Quick-create Issue handler | `server/internal/handler/issue.go:877-982` (`QuickCreateIssue`) |
+| Quick-create task enqueue | `server/internal/service/task.go:488+` (`EnqueueQuickCreateTask`) |
+| Daemon claim + load skills | `server/internal/handler/daemon.go:1018-1098` + `service/task.go:1447-1463` |
+| Daemon prompt build | `server/internal/daemon/prompt.go:17-36` (dispatch) + `:45-106` (`buildQuickCreatePrompt`) |
+| Daemon execenv prepare | `server/internal/daemon/execenv/execenv.go:103-176` |
+| Skill 目录约定(runtime mapping) | `server/internal/daemon/execenv/context.go:121-158` (`resolveSkillsDir`) |
+| Skill 文件落盘 | `server/internal/daemon/execenv/context.go:175-204` (`writeSkillFiles`) |
+| Quick-create 完成检测 + inbox | `server/internal/service/task.go:1810-1949` |
+| LinkTaskToIssue | `server/internal/handler/agent.go:97-105` |
+| Quick-create Issue 前端 modal | `packages/views/modals/quick-create-issue.tsx:48-570+` |
+| Multica CLI 入口 | `server/cmd/multica/main.go:62-79` |
+| Skill CLI 命令 | `server/cmd/multica/cmd_skill.go:17-96`(已有 import,无 find) |
+| Agent CLI 命令 | `server/cmd/multica/cmd_agent.go:101-112`(已有 list/get,无 create) |

docs/analytics.md

@@ -14,6 +14,7 @@ All analytics shipping is toggled by environment variables (see `.env.example`):
 |---|---|---|
 | `POSTHOG_API_KEY` | PostHog project API key. Empty = no events are shipped. | `""` |
 | `POSTHOG_HOST` | PostHog host (US or EU cloud, or self-hosted URL). | `https://us.i.posthog.com` |
+| `ANALYTICS_ENVIRONMENT` | Optional override for the standard `environment` event property. Normalized to `production`, `staging`, or `dev`; defaults from `APP_ENV`. | `APP_ENV` / `dev` |
 | `ANALYTICS_DISABLED` | Set to `true`/`1` to force the no-op client even when `POSTHOG_API_KEY` is set. | `""` |
 
 Local dev and self-hosted instances run with `POSTHOG_API_KEY=""`, so **no
@@ -82,6 +83,50 @@ handler → analytics.Client.Capture(Event)   ← non-blocking, returns immediat
   `$set_once` only for values that must never be overwritten (email,
   initial attribution, first-completion timestamp).
 
+## Taxonomy
+
+Every event is assigned to one dashboard category:
+
+| Category | Events |
+|---|---|
+| `core_loop` | `workspace_created`, `runtime_registered`, `runtime_ready`, `runtime_failed`, `runtime_offline`, `agent_created`, `issue_created`, `chat_message_sent`, `agent_task_queued`, `agent_task_dispatched`, `agent_task_started`, `agent_task_completed`, `agent_task_failed`, `agent_task_cancelled`, `autopilot_run_started`, `autopilot_run_completed`, `autopilot_run_failed` |
+| `onboarding_support` | `onboarding_started`, `onboarding_questionnaire_submitted`, `onboarding_completed`, `onboarding_runtime_path_selected`, `onboarding_runtime_detected`, `starter_content_decided` |
+| `acquisition` | `signup`, `download_intent_expressed`, `download_page_viewed`, `download_initiated`, `cloud_waitlist_joined` |
+| `ops_feedback` | `feedback_opened`, `feedback_submitted` |
+| `system/noise` | `$pageview`, `$set`, `$identify`, `$autocapture`, `$rageclick` |
+
+The v0 core dashboard must use only `core_loop` plus the specific
+`onboarding_support` steps used by the activation funnel. Acquisition,
+feedback, and system/noise events stay in separate dashboards.
+
+## Standard core properties
+
+Canonical core events should carry these properties whenever the entity exists:
+
+| Property | Type | Notes |
+|---|---|---|
+| `environment` | string | `production` / `staging` / `dev`; stamped by backend and frontend analytics clients. |
+| `event_schema_version` | int | Current version: `2`. |
+| `user_id` | string UUID | Human user ID when known. Agent/system events may omit it. |
+| `workspace_id` | string UUID | Required for workspace-scoped events. |
+| `agent_id` | string UUID | Required for agent/task events. |
+| `task_id` | string UUID | Required for `agent_task_*` events. |
+| `issue_id` / `chat_session_id` / `autopilot_run_id` | string UUID | Relevant source entity for the task/entry event. |
+| `source` | string | Canonical values: `onboarding`, `manual`, `chat`, `autopilot`, `api`. UI surface details use `surface` or `trigger_source`. |
+| `runtime_mode` | string | `cloud` / `local` when a runtime/agent task is involved. |
+| `provider` | string | `claude`, `codex`, `cursor`, etc. when a runtime/agent task is involved. |
+| `is_demo` | bool | Currently always `false`; reserved for future demo/test workspace filtering. |
+
+Task terminal events additionally carry `duration_ms`; failures carry
+`failure_reason`, `error_type`, and `will_retry`. Runtime failure events carry
+`recoverable`; runtime ready events carry `runtime_id`, `ready_duration_ms`
+only when it is actually measured, and `daemon_id` for local runtimes.
+
+Schema v2 is the first canonical core-metrics schema. It replaces early v1
+drafts that mirrored `failure_reason` into `error_type`, used `recoverable`
+for task/autopilot failures, and emitted `ready_duration_ms: 0` before the
+registration path had a measured duration.
+
 ## Event contract
 
 ### `signup`
@@ -128,6 +173,8 @@ extra query, no race.
 | Property | Type | Description |
 |---|---|---|
 | `runtime_id` | string (UUID) | The newly created agent_runtime row id. |
+| `daemon_id` | string | Local daemon identity when available. |
+| `runtime_mode` | string | Currently `local`; reserved for cloud runtimes. |
 | `provider` | string | e.g. `"codex"`, `"claude"`. |
 | `runtime_version` | string | Version of the agent runtime binary. |
 | `cli_version` | string | Version of the `multica` CLI that registered it. |
@@ -137,6 +184,118 @@ registered via a member's JWT/PAT; daemon-token registrations fall back to
 `workspace:<workspace_id>` so PostHog doesn't bucket unrelated daemons
 under a single "anonymous" person.
 
+### `runtime_ready`
+
+Fires when a runtime is first registered in an online/ready state. This is the
+activation-funnel step that should replace treating `runtime_registered` as
+proof of readiness. The backend emits this only on the INSERT path for a new
+`agent_runtime` row; ordinary daemon reconnects update the existing row and do
+not emit another `runtime_ready`. Dashboard funnels should still count
+distinct `runtime_id`.
+
+| Property | Type | Description |
+|---|---|---|
+| `runtime_id` | string (UUID) | The `agent_runtime` row id. |
+| `daemon_id` | string | Local daemon identity when available. |
+| `ready_duration_ms` | int64 | Optional. Time from registration start to ready; omitted until the registration path can measure it. |
+| `runtime_mode` | string | `local` / `cloud`. |
+| `provider` | string | Runtime provider. |
+
+### `runtime_failed`
+
+Fires when runtime setup/registration fails before a ready runtime can be
+recorded. Today this is scoped to backend registration persistence failures;
+future setup flows should reuse it for provider detection or daemon boot
+failures.
+
+| Property | Type | Description |
+|---|---|---|
+| `daemon_id` | string | Local daemon identity when available. |
+| `provider` | string | Runtime provider attempted. |
+| `failure_reason` | string | Stable coarse reason. |
+| `error_type` | string | Stable error classifier. |
+| `recoverable` | bool | Whether retrying setup may succeed. |
+
+### `runtime_offline`
+
+Fires when a runtime is explicitly deregistered or the backend sweeper marks it
+offline after missed heartbeats. This is not an activation step; it supports
+local runtime retention and drop-off diagnosis.
+
+### `issue_created`
+
+Fires after an issue row is created, including manual UI/API issue creation,
+quick-create issue creation by an agent, and autopilot `create_issue` runs.
+
+| Property | Type | Description |
+|---|---|---|
+| `issue_id` | string (UUID) | Created issue. |
+| `agent_id` | string (UUID) | Agent assignee or creating agent when applicable. |
+| `task_id` | string (UUID) | Present for quick-create issue creation. |
+| `autopilot_run_id` | string (UUID) | Present for autopilot-created issues. |
+| `source` | string | `manual`, `api`, or `autopilot`. |
+
+### `chat_message_sent`
+
+Fires after a user chat message is persisted and the corresponding agent task
+is queued.
+
+| Property | Type | Description |
+|---|---|---|
+| `chat_session_id` | string (UUID) | Chat session. |
+| `task_id` | string (UUID) | Queued agent task. |
+| `agent_id` | string (UUID) | Chat agent. |
+| `source` | string | Always `chat`. |
+
+### `agent_task_queued` / `agent_task_dispatched` / `agent_task_started` / `agent_task_completed`
+
+Canonical task lifecycle events emitted from `agent_task_queue` state
+transitions. `agent_task_dispatched` fires when the backend claims a queued
+task for a runtime, before the daemon marks it running with
+`agent_task_started`. These events replace `issue_executed` for core loop
+success metrics and allow the activation funnel to split queue backlog from
+claim/start handoff.
+
+| Property | Type | Description |
+|---|---|---|
+| `task_id` | string (UUID) | `agent_task_queue.id`; required. |
+| `agent_id` | string (UUID) | Owning agent. |
+| `issue_id` | string (UUID) | Present for issue-linked tasks. |
+| `chat_session_id` | string (UUID) | Present for chat tasks. |
+| `autopilot_run_id` | string (UUID) | Present for run-only autopilot tasks. |
+| `source` | string | `manual`, `chat`, or `autopilot`. |
+| `runtime_mode` | string | `local` / `cloud`. |
+| `provider` | string | Runtime provider. |
+| `duration_ms` | int64 | Terminal events only; measured from `started_at` when available. |
+
+### `agent_task_failed` / `agent_task_cancelled`
+
+Terminal task lifecycle events. They use the same join fields as
+`agent_task_completed`. `agent_task_failed` also carries:
+
+| Property | Type | Description |
+|---|---|---|
+| `failure_reason` | string | Stable reason from `agent_task_queue.failure_reason`, default `agent_error`. |
+| `error_type` | string | Stable coarse classifier, e.g. `runtime`, `timeout`, `agent_output`, `cancelled`, `agent_error`. |
+| `will_retry` | bool | Whether the backend auto-retry policy will create another task attempt. |
+
+### `autopilot_run_started` / `autopilot_run_completed` / `autopilot_run_failed`
+
+Fires from `autopilot_run` lifecycle changes. `source` is always
+`autopilot`; the trigger origin is carried in `trigger_source` (`manual`,
+`schedule`, `webhook`, or `api`).
+
+| Property | Type | Description |
+|---|---|---|
+| `autopilot_id` | string (UUID) | Autopilot definition. |
+| `autopilot_run_id` | string (UUID) | Run row. |
+| `agent_id` | string (UUID) | Assigned agent. |
+| `trigger_source` | string | `manual`, `schedule`, `webhook`, or `api`. |
+| `duration_ms` | int64 | Terminal events only. |
+| `failure_reason` | string | Failed events only. |
+| `error_type` | string | Failed events only; stable coarse classifier such as `configuration`, `issue_terminal`, `dispatch_error`, `task_error`, or `autopilot_error`. |
+| `will_retry` | bool | Failed events only; currently `false` because autopilot retry cadence is owned by triggers/schedules. |
+
 ### `issue_executed`
 
 Fires **at most once per issue** — when the first task on that issue
@@ -149,6 +308,11 @@ distinct issues, not tasks.
 | Property | Type | Description |
 |---|---|---|
 | `issue_id` | string (UUID) | |
+| `task_id` | string (UUID) | Completing task. |
+| `agent_id` | string (UUID) | Completing agent. |
+| `source` | string | `manual`, `chat`, or `autopilot`. |
+| `runtime_mode` | string | `local` / `cloud`. |
+| `provider` | string | Runtime provider. |
 | `task_duration_ms` | int64 | Wall-clock time between `task.started_at` and `task.completed_at`. Zero when the task was created in a completed state (rare). |
 
 `distinct_id` prefers the issue's human creator so agent-executed events
@@ -165,6 +329,10 @@ emit `n=1`. PostHog answers the same question at query time via
 and funnel steps of the form "workspace has had ≥2 `issue_executed`
 events" are expressible without the property. No information is lost.
 
+Compatibility: `issue_executed` remains a historical compatibility event for
+old dashboards. New core-loop success dashboards should use
+`agent_task_completed` and filter by `source`/`issue_id` as needed.
+
 ### `team_invite_sent`
 
 Fires from `CreateInvitation` after the DB row is written.
@@ -188,6 +356,17 @@ accepted and the member row is inserted in the same transaction.
 `distinct_id` is the invitee's user id — this is the event that closes the
 expansion funnel.
 
+### `onboarding_started`
+
+Fires once when the onboarding shell mounts and the initial workspace list has
+resolved. Existing-workspace users carry `workspace_id`; brand-new users do
+not have a workspace yet.
+
+| Property | Type | Description |
+|---|---|---|
+| `workspace_id` | string (UUID) | Present only when the user already has a workspace. |
+| `source` | string | Always `onboarding`. |
+
 ### `onboarding_questionnaire_submitted`
 
 Fires on the first PatchOnboarding that transitions the user's
@@ -226,6 +405,7 @@ isolates the Step 4 signal from later agent additions.
 |---|---|---|
 | `agent_id` | string (UUID) | |
 | `provider` | string | Runtime provider the agent is bound to (`claude`, `codex`, etc). |
+| `runtime_mode` | string | Runtime mode copied from the bound runtime. |
 | `template` | string | Template slug used to seed the agent (`coding` / `planning` / `writing` / `assistant`). Empty when the caller didn't come from a template picker. |
 | `is_first_agent_in_workspace` | bool | `true` when the workspace had zero agents before this insert. |
 
@@ -241,7 +421,8 @@ which exit the user took.
 
 | Property | Type | Description |
 |---|---|---|
-| `completion_path` | string | One of `full` / `runtime_skipped` / `cloud_waitlist` / `skip_existing` / `unknown`. See below. |
+| `workspace_id` | string (UUID) | Present for workspace-linked onboarding completions. |
+| `completion_path` | string | One of `full` / `runtime_skipped` / `cloud_waitlist` / `skip_existing` / `invite_accept` / `unknown`. See below. |
 | `joined_cloud_waitlist` | bool | Derived from `user.cloud_waitlist_email`. Orthogonal to `completion_path` — a user may submit the waitlist form and still pick CLI. |
 
 Person properties set with `$set_once`:
@@ -256,6 +437,7 @@ Person properties set with `$set_once`:
 - `runtime_skipped` — Completed without connecting a runtime (user hit Skip in Step 3).
 - `cloud_waitlist` — Submitted the cloud waitlist form and skipped Step 3.
 - `skip_existing` — "I've done this before" from Welcome. The user already had a workspace.
+- `invite_accept` — Accepted at least one workspace invitation.
 - `unknown` — Legacy fallback when the client didn't send a path. Should stay near zero after rollout.
 
 ### `cloud_waitlist_joined`
@@ -314,11 +496,11 @@ request payload.
   `packages/views/onboarding/steps/step-platform-fork.tsx` when the web
   user clicks one of the three Step 3 fork cards (before any server
   call happens, so it's frontend-only). Properties: `path`
-  (`download_desktop` / `cli` / `cloud_waitlist`), `source` (`step3`;
-  literal today but reserved for future surfaces reusing this event),
-  `is_mac`. Also writes `platform_preference` (`web` / `desktop`) to
-  person properties so every subsequent event on the user can be
-  broken down by chosen platform. **Note**: semantic "download
+  (`download_desktop` / `cli` / `cloud_waitlist`), `source`
+  (`onboarding`), `surface` (`step3`), `workspace_id`, and `is_mac`.
+  Also writes `platform_preference` (`web` / `desktop`) to person
+  properties so every subsequent event on the user can be broken down
+  by chosen platform. **Note**: semantic "download
   intent" is now better served by `download_intent_expressed` below —
   `path: "download_desktop"` signals Step 3 path choice specifically,
   not actual download start.
@@ -334,8 +516,9 @@ request payload.
   `runtime_registered` is silent on that cohort. Splits
   `completion_path=runtime_skipped` into "had CLIs, skipped anyway"
   vs "no CLIs available, had no choice". Properties:
-  - `source`: `step3_desktop` (literal; reserved for a future web
-    emission under a different value).
+  - `source`: `onboarding`.
+  - `surface`: `step3_desktop`.
+  - `workspace_id`: current onboarding workspace.
   - `outcome`: `found` (at least one runtime registered before the
     5 s grace window expired) or `empty` (none registered by then).
   - `runtime_count`: number of runtimes visible to this user at
@@ -419,6 +602,38 @@ request payload.
   `JSON.stringify`, and the entire payload is dropped if it still exceeds
   512 chars. That way PostHog sees either intact JSON or nothing at all.
 
+## Reconciliation
+
+`agent_task_completed` is the canonical PostHog-side task success event. It
+should reconcile daily against the operational source of truth:
+
+```sql
+SELECT date_trunc('day', completed_at AT TIME ZONE 'UTC') AS day,
+       count(*) AS db_completed_tasks
+FROM agent_task_queue
+WHERE status = 'completed'
+  AND completed_at >= now() - interval '30 days'
+GROUP BY 1
+ORDER BY 1;
+```
+
+Equivalent HogQL:
+
+```sql
+SELECT toStartOfDay(timestamp) AS day,
+       count() AS posthog_completed_tasks
+FROM events
+WHERE event = 'agent_task_completed'
+  AND properties.environment = 'production'
+  AND timestamp >= now() - interval 30 day
+GROUP BY day
+ORDER BY day
+```
+
+The expected difference should be near zero. Allow a small delay window for
+PostHog ingestion and backend analytics queue drops; sustained drift means
+either an emission site is missing or PostHog shipping is unhealthy.
+
 ## Governance
 
 Before adding, renaming, or removing any event:

e2e/chat-attachments.spec.ts

@@ -0,0 +1,170 @@
+/**
+ * E2E: chat attachment upload + send back-fills the message link.
+ *
+ * Stays at the HTTP layer (auth → upload-file → send-chat-message → DB
+ * check) so the test doesn't depend on a real agent runtime being online.
+ * The UI wiring is covered by `chat-input.test.tsx` in @multica/views; this
+ * spec is the end-to-end contract proof: the backend really does persist
+ * chat_session_id at upload and back-fill chat_message_id at send.
+ */
+import "./env";
+import { test, expect } from "@playwright/test";
+import pg from "pg";
+import { createTestApi } from "./helpers";
+import type { TestApiClient } from "./fixtures";
+
+const API_BASE =
+  process.env.NEXT_PUBLIC_API_URL || `http://localhost:${process.env.PORT || "8080"}`;
+const DATABASE_URL =
+  process.env.DATABASE_URL ?? "postgres://multica:multica@localhost:5432/multica?sslmode=disable";
+
+interface UploadRow {
+  id: string;
+  url: string;
+  chat_session_id: string | null;
+  chat_message_id: string | null;
+}
+
+async function authedFetch(api: TestApiClient, path: string, init?: RequestInit) {
+  const token = api.getToken();
+  if (!token) throw new Error("test api client not logged in");
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+    ...((init?.headers as Record<string, string>) ?? {}),
+  };
+  return fetch(`${API_BASE}${path}`, { ...init, headers });
+}
+
+test.describe("Chat attachments", () => {
+  let api: TestApiClient;
+  let pgClient: pg.Client | null = null;
+  let createdSessionId: string | null = null;
+  let createdAgentId: string | null = null;
+  let createdRuntimeId: string | null = null;
+
+  test.beforeEach(async () => {
+    api = await createTestApi();
+    pgClient = new pg.Client(DATABASE_URL);
+    await pgClient.connect();
+  });
+
+  test.afterEach(async () => {
+    try {
+      if (pgClient) {
+        if (createdSessionId) {
+          await pgClient.query(`DELETE FROM chat_session WHERE id = $1`, [createdSessionId]);
+        }
+        if (createdAgentId) {
+          await pgClient.query(`DELETE FROM agent WHERE id = $1`, [createdAgentId]);
+        }
+        if (createdRuntimeId) {
+          await pgClient.query(`DELETE FROM agent_runtime WHERE id = $1`, [createdRuntimeId]);
+        }
+      }
+    } finally {
+      if (pgClient) await pgClient.end();
+      pgClient = null;
+      createdSessionId = null;
+      createdAgentId = null;
+      createdRuntimeId = null;
+      await api.cleanup();
+    }
+  });
+
+  test("upload-file binds attachment to the chat_session; send back-fills chat_message_id", async () => {
+    expect(pgClient).not.toBeNull();
+    const pgc = pgClient!;
+
+    // Resolve the workspace + caller so we can seed an agent/runtime/session
+    // directly via SQL. Going through the HTTP API would require modelling
+    // local-daemon ownership which isn't needed for this contract test.
+    const workspaces = await api.getWorkspaces();
+    const ws = workspaces[0]!;
+    api.setWorkspaceSlug(ws.slug);
+    api.setWorkspaceId(ws.id);
+
+    const userRow = await pgc.query(
+      `SELECT id FROM "user" WHERE email = $1 LIMIT 1`,
+      ["e2e@multica.ai"],
+    );
+    if (userRow.rows.length === 0) throw new Error("e2e user missing");
+    const userId = userRow.rows[0].id as string;
+
+    // Seed runtime + agent + chat_session.
+    const runtimeIns = await pgc.query(
+      `INSERT INTO agent_runtime (
+         workspace_id, daemon_id, name, runtime_mode, provider, status,
+         device_info, metadata, last_seen_at
+       )
+       VALUES ($1, NULL, $2, 'cloud', $3, 'online', $4, '{}'::jsonb, now())
+       RETURNING id`,
+      [ws.id, `e2e chat runtime ${Date.now()}`, "e2e_chat_runtime", "E2E chat runtime"],
+    );
+    createdRuntimeId = runtimeIns.rows[0].id as string;
+
+    const agentIns = await pgc.query(
+      `INSERT INTO agent (
+         workspace_id, name, description, runtime_mode, runtime_config,
+         runtime_id, visibility, max_concurrent_tasks, owner_id
+       )
+       VALUES ($1, $2, '', 'cloud', '{}'::jsonb, $3, 'workspace', 1, $4)
+       RETURNING id`,
+      [ws.id, `E2E Chat Agent ${Date.now()}`, createdRuntimeId, userId],
+    );
+    createdAgentId = agentIns.rows[0].id as string;
+
+    const sessionIns = await pgc.query(
+      `INSERT INTO chat_session (workspace_id, agent_id, creator_id, title, status)
+       VALUES ($1, $2, $3, 'E2E Chat Attachment Session', 'active')
+       RETURNING id`,
+      [ws.id, createdAgentId, userId],
+    );
+    createdSessionId = sessionIns.rows[0].id as string;
+
+    // 1. Upload a small PNG against the chat session.
+    const pngBytes = Buffer.from([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, // PNG signature
+      0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52, // IHDR
+    ]);
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(pngBytes)], { type: "image/png" }), "e2e.png");
+    form.append("chat_session_id", createdSessionId);
+    const uploadRes = await authedFetch(api, "/api/upload-file", {
+      method: "POST",
+      body: form,
+      headers: { "X-Workspace-Slug": ws.slug },
+    });
+    expect(uploadRes.status).toBe(200);
+    const uploaded = (await uploadRes.json()) as UploadRow;
+    expect(uploaded.chat_session_id).toBe(createdSessionId);
+    expect(uploaded.chat_message_id).toBeNull();
+    expect(uploaded.url).toBeTruthy();
+
+    // 2. Send a chat message that references the attachment.
+    const sendRes = await authedFetch(api, `/api/chat/sessions/${createdSessionId}/messages`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Workspace-Slug": ws.slug,
+      },
+      body: JSON.stringify({
+        content: `look at this ![](${uploaded.url})`,
+        attachment_ids: [uploaded.id],
+      }),
+    });
+    expect(sendRes.status).toBe(201);
+    const sendBody = (await sendRes.json()) as { message_id: string; task_id: string };
+    expect(sendBody.message_id).toBeTruthy();
+
+    // 3. DB check: the attachment row's chat_message_id matches the new message.
+    const after = await pgc.query<{ chat_message_id: string | null }>(
+      `SELECT chat_message_id::text FROM attachment WHERE id = $1`,
+      [uploaded.id],
+    );
+    expect(after.rows[0]?.chat_message_id).toBe(sendBody.message_id);
+
+    // 4. Clean up the attachment we created (chat_session cascade handles the
+    //    rest in afterEach via chat_session row deletion).
+    await pgc.query(`DELETE FROM attachment WHERE id = $1`, [uploaded.id]);
+  });
+});

package.json

@@ -13,7 +13,8 @@
     "test": "turbo test",
     "lint": "turbo lint",
     "clean": "turbo clean && rm -rf node_modules",
-    "ui:add": "cd packages/ui && npx shadcn@latest add"
+    "ui:add": "cd packages/ui && npx shadcn@latest add",
+    "generate:reserved-slugs": "node scripts/generate-reserved-slugs.mjs"
   },
   "packageManager": "pnpm@10.28.2",
   "pnpm": {

packages/core/agents/derive-presence.test.ts

@@ -49,6 +49,8 @@ function makeRuntime(overrides: Partial<AgentRuntime> = {}): AgentRuntime {
     device_info: "",
     metadata: {},
     owner_id: null,
+    visibility: "private",
+    timezone: "UTC",
     last_seen_at: "2026-04-27T11:59:50Z",
     created_at: "2026-04-01T00:00:00Z",
     updated_at: "2026-04-01T00:00:00Z",

packages/core/agents/queries.ts

@@ -82,3 +82,30 @@ export function agentTasksOptions(wsId: string, agentId: string) {
     refetchOnWindowFocus: true,
   });
 }
+
+// Agent templates are workspace-independent: a static catalog served from
+// the server's embedded JSON. Cache effectively forever — the only way the
+// list / detail change is a server deploy, and a hard reload picks that up.
+export const agentTemplateKeys = {
+  all: () => ["agent-templates"] as const,
+  list: () => [...agentTemplateKeys.all(), "list"] as const,
+  detail: (slug: string) => [...agentTemplateKeys.all(), "detail", slug] as const,
+};
+
+export function agentTemplateListOptions() {
+  return queryOptions({
+    queryKey: agentTemplateKeys.list(),
+    queryFn: () => api.listAgentTemplates(),
+    staleTime: Infinity,
+    gcTime: 30 * 60 * 1000,
+  });
+}
+
+export function agentTemplateDetailOptions(slug: string) {
+  return queryOptions({
+    queryKey: agentTemplateKeys.detail(slug),
+    queryFn: () => api.getAgentTemplate(slug),
+    staleTime: Infinity,
+    gcTime: 30 * 60 * 1000,
+  });
+}

packages/core/agents/use-workspace-presence-prefetch.ts

@@ -1,20 +1,22 @@
 "use client";
 
 import { useQuery } from "@tanstack/react-query";
-import { agentListOptions } from "../workspace/queries";
+import { agentListOptions, squadListOptions } from "../workspace/queries";
 import { runtimeListOptions } from "../runtimes/queries";
 import { agentTaskSnapshotOptions } from "./queries";
 
-// Subscribe to the three queries that power agent presence so they're warm
-// by the time any hover card / inline indicator first renders. Without this
-// warm-up, surfaces that don't otherwise touch the snapshot (inbox, issues,
-// chat) flash a skeleton on first hover while the fetch is in flight.
+// Subscribe to the queries that power agent presence and the @mention
+// suggestion list so they're warm by the time any hover card / inline
+// indicator / mention popup first renders. Without this warm-up, surfaces
+// that don't otherwise touch the snapshot (inbox, issues, chat) flash a
+// skeleton on first hover while the fetch is in flight, and the @mention
+// list may show incomplete results (e.g. missing squads).
 //
-// useRealtimeSync (WS task / agent / daemon invalidations) and the 30s
-// presence tick keep these caches fresh after the initial fetch — this hook
-// only collapses the cold-start window.
+// useRealtimeSync (WS task / agent / daemon / squad invalidations) and the
+// 30s presence tick keep these caches fresh after the initial fetch — this
+// hook only collapses the cold-start window.
 //
-// All three are workspace-scoped; the queryKeys include wsId so workspace
+// All queries are workspace-scoped; the queryKeys include wsId so workspace
 // switch automatically refetches the new workspace's data with no extra
 // wiring here. The workspace-scoped layouts on both apps gate rendering on
 // "workspace resolved", so callers can safely pass useWorkspaceId() — by the
@@ -23,4 +25,5 @@ export function useWorkspacePresencePrefetch(wsId: string | undefined): void {
   useQuery({ ...agentListOptions(wsId ?? ""), enabled: !!wsId });
   useQuery({ ...runtimeListOptions(wsId ?? ""), enabled: !!wsId });
   useQuery({ ...agentTaskSnapshotOptions(wsId ?? ""), enabled: !!wsId });
+  useQuery({ ...squadListOptions(wsId ?? ""), enabled: !!wsId });
 }

packages/core/analytics/index.test.ts

@@ -45,20 +45,33 @@ describe("initAnalytics super-properties", () => {
     expect(posthog.register).toHaveBeenCalledWith({
       client_type: "web",
       app_version: "1.2.3",
+      environment: "dev",
+      event_schema_version: 2,
+      is_demo: false,
     });
   });
 
   it("omits app_version when not provided", async () => {
     const { analytics, posthog } = await loadModule();
     analytics.initAnalytics({ key: "k", host: "" });
-    expect(posthog.register).toHaveBeenCalledWith({ client_type: "web" });
+    expect(posthog.register).toHaveBeenCalledWith({
+      client_type: "web",
+      environment: "dev",
+      event_schema_version: 2,
+      is_demo: false,
+    });
   });
 
   it("detects desktop when window.electron is present", async () => {
     vi.stubGlobal("window", { electron: {} });
     const { analytics, posthog } = await loadModule();
     analytics.initAnalytics({ key: "k", host: "" });
-    expect(posthog.register).toHaveBeenCalledWith({ client_type: "desktop" });
+    expect(posthog.register).toHaveBeenCalledWith({
+      client_type: "desktop",
+      environment: "dev",
+      event_schema_version: 2,
+      is_demo: false,
+    });
   });
 });
 
@@ -76,6 +89,9 @@ describe("resetAnalytics", () => {
     expect(posthog.register).toHaveBeenCalledWith({
       client_type: "web",
       app_version: "1.2.3",
+      environment: "dev",
+      event_schema_version: 2,
+      is_demo: false,
     });
   });
 

packages/core/analytics/index.ts

@@ -14,6 +14,8 @@
 
 import posthog from "posthog-js";
 
+export const EVENT_SCHEMA_VERSION = 2;
+
 const SIGNUP_SOURCE_COOKIE = "multica_signup_source";
 // Per-value cap keeps a long utm_content from blowing the budget. We drop
 // the entire cookie if the JSON still exceeds the overall limit — partial
@@ -34,6 +36,8 @@ let initialized = false;
 // most recent pending identify (only one matters, since it's per-session)
 // and flush it inside initAnalytics.
 let pendingIdentify: { userId: string; props?: Record<string, unknown> } | null = null;
+let currentUserId: string | null = null;
+let analyticsEnvironment = "dev";
 // Likewise pageviews: the initial "/" pageview is the anchor of the
 // acquisition funnel, and the Next.js router fires it on mount before the
 // config fetch resolves. We keep the first pending pageview so that step
@@ -78,6 +82,7 @@ export interface AnalyticsConfig {
    * available.
    */
   appVersion?: string;
+  environment?: string;
 }
 
 export type ClientType = "desktop" | "web";
@@ -135,6 +140,7 @@ export function initAnalytics(config: AnalyticsConfig | null | undefined): boole
     disable_session_recording: true,
     disable_surveys: true,
   });
+  analyticsEnvironment = normalizeEnvironment(config.environment);
   // Register super-properties — attached to every event emitted from this
   // client. `client_type` is the canonical split between desktop and web
   // (PostHog's own `$lib` reports "web" for both because Electron renderers
@@ -142,13 +148,19 @@ export function initAnalytics(config: AnalyticsConfig | null | undefined): boole
   // builds without a version don't pollute the property.
   // We cache the set so resetAnalytics() can re-apply it after
   // posthog.reset() — reset() clears persisted super-properties otherwise.
-  superProperties = { client_type: detectClientType() };
+  superProperties = {
+    client_type: detectClientType(),
+    event_schema_version: EVENT_SCHEMA_VERSION,
+    environment: analyticsEnvironment,
+    is_demo: false,
+  };
   if (config.appVersion) superProperties.app_version = config.appVersion;
   posthog.register(superProperties);
   initialized = true;
 
   // Flush any identify() that arrived before init resolved.
   if (pendingIdentify) {
+    currentUserId = pendingIdentify.userId;
     posthog.identify(pendingIdentify.userId, pendingIdentify.props);
     pendingIdentify = null;
   }
@@ -164,7 +176,7 @@ export function initAnalytics(config: AnalyticsConfig | null | undefined): boole
   while (pendingOps.length > 0) {
     const op = pendingOps.shift()!;
     if (op.kind === "event") {
-      posthog.capture(op.name, op.props);
+      posthog.capture(op.name, withClientEventProperties(op.props));
     } else {
       capturePersonSet(op.props);
     }
@@ -182,6 +194,7 @@ export function initAnalytics(config: AnalyticsConfig | null | undefined): boole
  * config and user in parallel, so identify can arrive first.
  */
 export function identify(userId: string, userProperties?: Record<string, unknown>): void {
+  currentUserId = userId;
   if (!initialized) {
     pendingIdentify = { userId, props: userProperties };
     return;
@@ -194,6 +207,7 @@ export function identify(userId: string, userProperties?: Record<string, unknown
  * and doesn't bleed the previous user's events into a new session.
  */
 export function resetAnalytics(): void {
+  currentUserId = null;
   pendingIdentify = null;
   pendingPageview = null;
   pendingOps.length = 0;
@@ -225,7 +239,7 @@ export function captureEvent(
     pendingOps.push({ kind: "event", name, props });
     return;
   }
-  posthog.capture(name, props);
+  posthog.capture(name, withClientEventProperties(props));
 }
 
 /**
@@ -253,6 +267,43 @@ function capturePersonSet(props: Record<string, unknown>): void {
   posthog.capture("$set", { $set: props });
 }
 
+function withClientEventProperties(
+  props?: Record<string, unknown>,
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...(props ?? {}) };
+  if (currentUserId && next.user_id === undefined) {
+    next.user_id = currentUserId;
+  }
+  if (next.event_schema_version === undefined) {
+    next.event_schema_version = EVENT_SCHEMA_VERSION;
+  }
+  if (next.environment === undefined) {
+    next.environment = analyticsEnvironment;
+  }
+  if (next.is_demo === undefined) {
+    next.is_demo = false;
+  }
+  return next;
+}
+
+function normalizeEnvironment(value: string | undefined): string {
+  switch ((value || "").trim().toLowerCase()) {
+    case "production":
+    case "prod":
+      return "production";
+    case "staging":
+    case "stage":
+      return "staging";
+    case "development":
+    case "dev":
+    case "test":
+    case "local":
+      return "dev";
+    default:
+      return "dev";
+  }
+}
+
 /**
  * Capture a page view. Call once per client-side navigation. We disable
  * posthog's automatic pageview tracking in init() so this module owns the

packages/core/api/client.test.ts

@@ -144,4 +144,177 @@ describe("ApiClient", () => {
     expect(headers["X-Client-Version"]).toBeUndefined();
     expect(headers["X-Client-OS"]).toBeUndefined();
   });
+
+  describe("getAttachment", () => {
+    it("returns the parsed attachment for a well-formed response", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue(
+          new Response(
+            JSON.stringify({
+              id: "att-1",
+              workspace_id: "ws-1",
+              issue_id: null,
+              comment_id: null,
+              uploader_type: "member",
+              uploader_id: "u-1",
+              filename: "report.md",
+              url: "https://static.example.test/ws/att-1.md",
+              download_url:
+                "https://static.example.test/ws/att-1.md?Policy=p&Signature=s&Key-Pair-Id=k",
+              content_type: "text/markdown",
+              size_bytes: 123,
+              created_at: "2026-05-11T00:00:00Z",
+            }),
+            { status: 200, headers: { "Content-Type": "application/json" } },
+          ),
+        ),
+      );
+
+      const client = new ApiClient("https://api.example.test");
+      const att = await client.getAttachment("att-1");
+
+      expect(att.id).toBe("att-1");
+      expect(att.download_url).toContain("Policy=");
+    });
+
+    it("falls back to an empty attachment when the response is missing download_url", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue(
+          new Response(JSON.stringify({ id: "att-1" }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+        ),
+      );
+
+      const client = new ApiClient("https://api.example.test");
+      const att = await client.getAttachment("att-1");
+
+      // parseWithFallback returns the EMPTY_ATTACHMENT record so callers can
+      // safely read `download_url` without crashing — they'll see "" and
+      // surface a user-facing error instead of opening `undefined`.
+      expect(att.id).toBe("");
+      expect(att.download_url).toBe("");
+    });
+  });
+
+  describe("getAttachmentTextContent", () => {
+    it("returns body text and the original content type from the X-* header", async () => {
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue(
+          new Response("# heading\n\nbody\n", {
+            status: 200,
+            headers: {
+              "Content-Type": "text/plain; charset=utf-8",
+              "X-Original-Content-Type": "text/markdown",
+            },
+          }),
+        ),
+      );
+
+      const client = new ApiClient("https://api.example.test");
+      const { text, originalContentType } =
+        await client.getAttachmentTextContent("att-1");
+
+      expect(text).toBe("# heading\n\nbody\n");
+      expect(originalContentType).toBe("text/markdown");
+    });
+
+    it("throws PreviewTooLargeError on 413", async () => {
+      const { PreviewTooLargeError } = await import("./client");
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue(
+          new Response("", { status: 413, statusText: "Payload Too Large" }),
+        ),
+      );
+
+      const client = new ApiClient("https://api.example.test");
+      await expect(client.getAttachmentTextContent("att-1")).rejects.toBeInstanceOf(
+        PreviewTooLargeError,
+      );
+    });
+
+    it("throws PreviewUnsupportedError on 415", async () => {
+      const { PreviewUnsupportedError } = await import("./client");
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue(
+          new Response("", { status: 415, statusText: "Unsupported Media Type" }),
+        ),
+      );
+
+      const client = new ApiClient("https://api.example.test");
+      await expect(client.getAttachmentTextContent("att-1")).rejects.toBeInstanceOf(
+        PreviewUnsupportedError,
+      );
+    });
+  });
+
+  describe("chat attachment wiring", () => {
+    it("uploadFile includes chat_session_id in the FormData body", async () => {
+      const fetchMock = vi.fn().mockResolvedValue(
+        new Response(JSON.stringify({ id: "att-1", url: "https://cdn/x" }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+      );
+      vi.stubGlobal("fetch", fetchMock);
+
+      const client = new ApiClient("https://api.example.test");
+      const file = new File(["hi"], "hi.png", { type: "image/png" });
+      await client.uploadFile(file, { chatSessionId: "session-123" });
+
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+      const [url, init] = fetchMock.mock.calls[0]!;
+      expect(url).toBe("https://api.example.test/api/upload-file");
+      expect(init?.method).toBe("POST");
+      const body = init?.body as FormData;
+      expect(body).toBeInstanceOf(FormData);
+      expect(body.get("chat_session_id")).toBe("session-123");
+      expect(body.get("issue_id")).toBeNull();
+      expect(body.get("comment_id")).toBeNull();
+    });
+
+    it("sendChatMessage serialises attachment_ids onto the JSON body when present", async () => {
+      const fetchMock = vi.fn().mockResolvedValue(
+        new Response(JSON.stringify({ message_id: "m1", task_id: "t1", created_at: "" }), {
+          status: 201,
+          headers: { "Content-Type": "application/json" },
+        }),
+      );
+      vi.stubGlobal("fetch", fetchMock);
+
+      const client = new ApiClient("https://api.example.test");
+      await client.sendChatMessage("session-1", "hello", ["att-1", "att-2"]);
+
+      const [, init] = fetchMock.mock.calls[0]!;
+      expect(JSON.parse(init?.body as string)).toEqual({
+        content: "hello",
+        attachment_ids: ["att-1", "att-2"],
+      });
+    });
+
+    it("sendChatMessage omits attachment_ids when the list is empty or undefined", async () => {
+      const fetchMock = vi.fn().mockImplementation(() =>
+        Promise.resolve(
+          new Response(JSON.stringify({ message_id: "m1", task_id: "t1", created_at: "" }), {
+            status: 201,
+            headers: { "Content-Type": "application/json" },
+          }),
+        ),
+      );
+      vi.stubGlobal("fetch", fetchMock);
+
+      const client = new ApiClient("https://api.example.test");
+      await client.sendChatMessage("session-1", "hello");
+      await client.sendChatMessage("session-1", "again", []);
+
+      expect(JSON.parse(fetchMock.mock.calls[0]![1]?.body as string)).toEqual({ content: "hello" });
+      expect(JSON.parse(fetchMock.mock.calls[1]![1]?.body as string)).toEqual({ content: "again" });
+    });
+  });
 });

packages/core/api/client.ts

@@ -11,6 +11,10 @@ import type {
   ListIssuesParams,
   Agent,
   CreateAgentRequest,
+  AgentTemplate,
+  AgentTemplateSummary,
+  CreateAgentFromTemplateRequest,
+  CreateAgentFromTemplateResponse,
   UpdateAgentRequest,
   AgentTask,
   AgentActivityBucket,
@@ -38,13 +42,15 @@ import type {
   RuntimeHourlyActivity,
   RuntimeUsageByAgent,
   RuntimeUsageByHour,
+  DashboardUsageDaily,
+  DashboardUsageByAgent,
+  DashboardAgentRunTime,
   RuntimeUpdate,
   RuntimeModelListRequest,
   RuntimeLocalSkillListRequest,
   CreateRuntimeLocalSkillImportRequest,
   RuntimeLocalSkillImportRequest,
-  TimelinePage,
-  TimelinePageParam,
+  TimelineEntry,
   AssigneeFrequencyEntry,
   TaskMessagePayload,
   Attachment,
@@ -82,11 +88,37 @@ import type {
   ListAutopilotRunsResponse,
   NotificationPreferenceResponse,
   NotificationPreferences,
+  GitHubPullRequest,
+  ListGitHubInstallationsResponse,
+  GitHubConnectResponse,
+  Squad,
+  SquadMember,
 } from "../types";
 import type { OnboardingCompletionPath } from "../onboarding/types";
 import { type Logger, noopLogger } from "../logger";
 import { createRequestId } from "../utils";
 import { getCurrentSlug } from "../platform/workspace-storage";
+import { parseWithFallback } from "./schema";
+import {
+  AgentTemplateSchema,
+  AgentTemplateSummaryListSchema,
+  AttachmentResponseSchema,
+  ChildIssuesResponseSchema,
+  CommentsListSchema,
+  CreateAgentFromTemplateResponseSchema,
+  DashboardAgentRunTimeListSchema,
+  DashboardUsageByAgentListSchema,
+  DashboardUsageDailyListSchema,
+  EMPTY_AGENT_TEMPLATE_DETAIL,
+  EMPTY_AGENT_TEMPLATE_SUMMARY_LIST,
+  EMPTY_ATTACHMENT,
+  EMPTY_CREATE_AGENT_FROM_TEMPLATE_RESPONSE,
+  EMPTY_LIST_ISSUES_RESPONSE,
+  EMPTY_TIMELINE_ENTRIES,
+  ListIssuesResponseSchema,
+  SubscribersListSchema,
+  TimelineEntriesSchema,
+} from "./schemas";
 
 /** Identifies the calling client to the server.
  *  Sent on every HTTP request as X-Client-Platform / X-Client-Version /
@@ -176,6 +208,27 @@ export class ApiError extends Error {
   }
 }
 
+// Thrown by getAttachmentTextContent when the server refuses to inline a
+// file because it exceeds the 2 MB cap. UI maps to a "too large, please
+// download" affordance with the Download CTA still available.
+export class PreviewTooLargeError extends Error {
+  constructor() {
+    super("attachment too large for inline preview");
+    this.name = "PreviewTooLargeError";
+  }
+}
+
+// Thrown by getAttachmentTextContent when the server's text whitelist
+// rejects the content type. Normally the client's isPreviewable() guard
+// catches this earlier, but the two whitelists can drift — surfacing the
+// 415 as a typed error makes the drift visible.
+export class PreviewUnsupportedError extends Error {
+  constructor() {
+    super("attachment type not supported for inline preview");
+    this.name = "PreviewUnsupportedError";
+  }
+}
+
 export class ApiClient {
   private baseUrl: string;
   private token: string | null = null;
@@ -250,15 +303,23 @@ export class ApiClient {
     }
   }
 
-  private async fetch<T>(path: string, init?: RequestInit): Promise<T> {
+  // Sends the request with the standard headers (auth, CSRF, request id,
+  // client identity) and runs the shared error path (401 → handleUnauthorized,
+  // structured ApiError, status-aware log level). Returns the raw Response so
+  // callers can decide how to decode the body — JSON for the typed `fetch<T>`
+  // path, plain text for the attachment-preview proxy, etc.
+  private async fetchRaw(
+    path: string,
+    init?: RequestInit & { extraHeaders?: Record<string, string> },
+  ): Promise<Response> {
     const rid = createRequestId();
     const start = Date.now();
     const method = init?.method ?? "GET";
 
     const headers: Record<string, string> = {
-      "Content-Type": "application/json",
       "X-Request-ID": rid,
       ...this.authHeaders(),
+      ...(init?.extraHeaders ?? {}),
       ...((init?.headers as Record<string, string>) ?? {}),
     };
 
@@ -279,12 +340,18 @@ export class ApiClient {
     }
 
     this.logger.info(`← ${res.status} ${path}`, { rid, duration: `${Date.now() - start}ms` });
+    return res;
+  }
 
+  private async fetch<T>(path: string, init?: RequestInit): Promise<T> {
+    const res = await this.fetchRaw(path, {
+      ...init,
+      extraHeaders: { "Content-Type": "application/json" },
+    });
     // Handle 204 No Content
     if (res.status === 204) {
       return undefined as T;
     }
-
     return res.json() as Promise<T>;
   }
 
@@ -324,6 +391,7 @@ export class ApiClient {
 
   async markOnboardingComplete(payload?: {
     completion_path?: OnboardingCompletionPath;
+    workspace_id?: string;
   }): Promise<User> {
     return this.fetch("/api/me/onboarding/complete", {
       method: "POST",
@@ -398,7 +466,11 @@ export class ApiClient {
     if (params?.creator_id) search.set("creator_id", params.creator_id);
     if (params?.project_id) search.set("project_id", params.project_id);
     if (params?.open_only) search.set("open_only", "true");
-    return this.fetch(`/api/issues?${search}`);
+    const path = `/api/issues?${search}`;
+    const raw = await this.fetch<unknown>(path);
+    return parseWithFallback(raw, ListIssuesResponseSchema, EMPTY_LIST_ISSUES_RESPONSE, {
+      endpoint: "GET /api/issues",
+    });
   }
 
   async searchIssues(params: { q: string; limit?: number; offset?: number; include_closed?: boolean; signal?: AbortSignal }): Promise<SearchIssuesResponse> {
@@ -428,7 +500,12 @@ export class ApiClient {
     });
   }
 
-  async quickCreateIssue(data: { agent_id: string; prompt: string }): Promise<{ task_id: string }> {
+  async quickCreateIssue(data: {
+    agent_id?: string;
+    squad_id?: string;
+    prompt: string;
+    project_id?: string | null;
+  }): Promise<{ task_id: string }> {
     return this.fetch("/api/issues/quick-create", {
       method: "POST",
       body: JSON.stringify(data),
@@ -454,7 +531,10 @@ export class ApiClient {
   }
 
   async listChildIssues(id: string): Promise<{ issues: Issue[] }> {
-    return this.fetch(`/api/issues/${id}/children`);
+    const raw = await this.fetch<unknown>(`/api/issues/${id}/children`);
+    return parseWithFallback(raw, ChildIssuesResponseSchema, { issues: [] }, {
+      endpoint: "GET /api/issues/:id/children",
+    });
   }
 
   async getChildIssueProgress(): Promise<{ progress: { parent_issue_id: string; total: number; done: number }[] }> {
@@ -481,7 +561,10 @@ export class ApiClient {
 
   // Comments
   async listComments(issueId: string): Promise<Comment[]> {
-    return this.fetch(`/api/issues/${issueId}/comments`);
+    const raw = await this.fetch<unknown>(`/api/issues/${issueId}/comments`);
+    return parseWithFallback(raw, CommentsListSchema, [], {
+      endpoint: "GET /api/issues/:id/comments",
+    });
   }
 
   async createComment(issueId: string, content: string, type?: string, parentId?: string, attachmentIds?: string[]): Promise<Comment> {
@@ -496,27 +579,23 @@ export class ApiClient {
     });
   }
 
-  async listTimeline(
-    issueId: string,
-    pageParam: TimelinePageParam = { mode: "latest" },
-    limit = 50,
-  ): Promise<TimelinePage> {
-    const params = new URLSearchParams();
-    params.set("limit", String(limit));
-    if (pageParam.mode === "before") params.set("before", pageParam.cursor);
-    else if (pageParam.mode === "after") params.set("after", pageParam.cursor);
-    else if (pageParam.mode === "around") params.set("around", pageParam.id);
-    return this.fetch(`/api/issues/${issueId}/timeline?${params.toString()}`);
+  async listTimeline(issueId: string): Promise<TimelineEntry[]> {
+    const raw = await this.fetch<unknown>(
+      `/api/issues/${issueId}/timeline`,
+    );
+    return parseWithFallback(raw, TimelineEntriesSchema, EMPTY_TIMELINE_ENTRIES, {
+      endpoint: "GET /api/issues/:id/timeline",
+    });
   }
 
   async getAssigneeFrequency(): Promise<AssigneeFrequencyEntry[]> {
     return this.fetch("/api/assignee-frequency");
   }
 
-  async updateComment(commentId: string, content: string): Promise<Comment> {
+  async updateComment(commentId: string, content: string, attachmentIds?: string[]): Promise<Comment> {
     return this.fetch(`/api/comments/${commentId}`, {
       method: "PUT",
-      body: JSON.stringify({ content }),
+      body: JSON.stringify({ content, attachment_ids: attachmentIds }),
     });
   }
 
@@ -524,6 +603,14 @@ export class ApiClient {
     await this.fetch(`/api/comments/${commentId}`, { method: "DELETE" });
   }
 
+  async resolveComment(commentId: string): Promise<Comment> {
+    return this.fetch(`/api/comments/${commentId}/resolve`, { method: "POST" });
+  }
+
+  async unresolveComment(commentId: string): Promise<Comment> {
+    return this.fetch(`/api/comments/${commentId}/resolve`, { method: "DELETE" });
+  }
+
   async addReaction(commentId: string, emoji: string): Promise<Reaction> {
     return this.fetch(`/api/comments/${commentId}/reactions`, {
       method: "POST",
@@ -554,7 +641,10 @@ export class ApiClient {
 
   // Subscribers
   async listIssueSubscribers(issueId: string): Promise<IssueSubscriber[]> {
-    return this.fetch(`/api/issues/${issueId}/subscribers`);
+    const raw = await this.fetch<unknown>(`/api/issues/${issueId}/subscribers`);
+    return parseWithFallback(raw, SubscribersListSchema, [], {
+      endpoint: "GET /api/issues/:id/subscribers",
+    });
   }
 
   async subscribeToIssue(issueId: string, userId?: string, userType?: string): Promise<void> {
@@ -596,6 +686,51 @@ export class ApiClient {
     });
   }
 
+  async listAgentTemplates(): Promise<AgentTemplateSummary[]> {
+    const raw = await this.fetch<unknown>("/api/agent-templates");
+    return parseWithFallback(
+      raw,
+      AgentTemplateSummaryListSchema,
+      EMPTY_AGENT_TEMPLATE_SUMMARY_LIST,
+      { endpoint: "GET /api/agent-templates" },
+    );
+  }
+
+  async getAgentTemplate(slug: string): Promise<AgentTemplate> {
+    const raw = await this.fetch<unknown>(
+      `/api/agent-templates/${encodeURIComponent(slug)}`,
+    );
+    // Round-trip the requested slug into the fallback so a malformed
+    // detail response still produces a navigable record matching the URL
+    // the user clicked.
+    return parseWithFallback(
+      raw,
+      AgentTemplateSchema,
+      { ...EMPTY_AGENT_TEMPLATE_DETAIL, slug },
+      { endpoint: "GET /api/agent-templates/:slug" },
+    );
+  }
+
+  /** Creates an agent from a curated template. The server fetches every
+   *  referenced skill URL in parallel, materializes them into the workspace
+   *  (find-or-create by name), and writes the agent + skill bindings in a
+   *  single transaction. On any upstream fetch failure, the entire write is
+   *  rolled back and the API returns 422 with `failed_urls`. */
+  async createAgentFromTemplate(
+    data: CreateAgentFromTemplateRequest,
+  ): Promise<CreateAgentFromTemplateResponse> {
+    const raw = await this.fetch<unknown>("/api/agents/from-template", {
+      method: "POST",
+      body: JSON.stringify(data),
+    });
+    return parseWithFallback(
+      raw,
+      CreateAgentFromTemplateResponseSchema,
+      EMPTY_CREATE_AGENT_FROM_TEMPLATE_RESPONSE,
+      { endpoint: "POST /api/agents/from-template" },
+    );
+  }
+
   async updateAgent(id: string, data: UpdateAgentRequest): Promise<Agent> {
     return this.fetch(`/api/agents/${id}`, {
       method: "PUT",
@@ -630,6 +765,16 @@ export class ApiClient {
     await this.fetch(`/api/runtimes/${runtimeId}`, { method: "DELETE" });
   }
 
+  async updateRuntime(
+    runtimeId: string,
+    patch: { timezone?: string; visibility?: "private" | "public" },
+  ): Promise<AgentRuntime> {
+    return this.fetch(`/api/runtimes/${runtimeId}`, {
+      method: "PATCH",
+      body: JSON.stringify(patch),
+    });
+  }
+
   async getRuntimeUsage(runtimeId: string, params?: { days?: number }): Promise<RuntimeUsage[]> {
     const search = new URLSearchParams();
     if (params?.days) search.set("days", String(params.days));
@@ -658,6 +803,58 @@ export class ApiClient {
     return this.fetch(`/api/runtimes/${runtimeId}/usage/by-hour?${search}`);
   }
 
+  // ---------------------------------------------------------------------------
+  // Workspace dashboard — three independent rollups for `/{slug}/dashboard`.
+  // Each accepts an optional `project_id` to narrow the scope to one project.
+  // Cost is computed client-side from the model pricing table (same contract
+  // as the per-runtime endpoints above).
+  // ---------------------------------------------------------------------------
+
+  async getDashboardUsageDaily(
+    params: { days?: number; project_id?: string | null },
+  ): Promise<DashboardUsageDaily[]> {
+    const search = new URLSearchParams();
+    if (params.days) search.set("days", String(params.days));
+    if (params.project_id) search.set("project_id", params.project_id);
+    const raw = await this.fetch<unknown>(`/api/dashboard/usage/daily?${search}`);
+    return parseWithFallback<DashboardUsageDaily[]>(
+      raw,
+      DashboardUsageDailyListSchema,
+      [],
+      { endpoint: "GET /api/dashboard/usage/daily" },
+    );
+  }
+
+  async getDashboardUsageByAgent(
+    params: { days?: number; project_id?: string | null },
+  ): Promise<DashboardUsageByAgent[]> {
+    const search = new URLSearchParams();
+    if (params.days) search.set("days", String(params.days));
+    if (params.project_id) search.set("project_id", params.project_id);
+    const raw = await this.fetch<unknown>(`/api/dashboard/usage/by-agent?${search}`);
+    return parseWithFallback<DashboardUsageByAgent[]>(
+      raw,
+      DashboardUsageByAgentListSchema,
+      [],
+      { endpoint: "GET /api/dashboard/usage/by-agent" },
+    );
+  }
+
+  async getDashboardAgentRunTime(
+    params: { days?: number; project_id?: string | null },
+  ): Promise<DashboardAgentRunTime[]> {
+    const search = new URLSearchParams();
+    if (params.days) search.set("days", String(params.days));
+    if (params.project_id) search.set("project_id", params.project_id);
+    const raw = await this.fetch<unknown>(`/api/dashboard/agent-runtime?${search}`);
+    return parseWithFallback<DashboardAgentRunTime[]>(
+      raw,
+      DashboardAgentRunTimeListSchema,
+      [],
+      { endpoint: "GET /api/dashboard/agent-runtime" },
+    );
+  }
+
   async initiateUpdate(
     runtimeId: string,
     targetVersion: string,
@@ -766,6 +963,12 @@ export class ApiClient {
     });
   }
 
+  async rerunIssue(issueId: string): Promise<AgentTask> {
+    return this.fetch(`/api/issues/${issueId}/rerun`, {
+      method: "POST",
+    });
+  }
+
   // Inbox
   async listInbox(): Promise<InboxItem[]> {
     return this.fetch("/api/inbox");
@@ -818,6 +1021,7 @@ export class ApiClient {
     google_client_id?: string;
     posthog_key?: string;
     posthog_host?: string;
+    analytics_environment?: string;
   }> {
     return this.fetch("/api/config");
   }
@@ -975,11 +1179,15 @@ export class ApiClient {
   }
 
   // File Upload & Attachments
-  async uploadFile(file: File, opts?: { issueId?: string; commentId?: string }): Promise<Attachment> {
+  async uploadFile(
+    file: File,
+    opts?: { issueId?: string; commentId?: string; chatSessionId?: string },
+  ): Promise<Attachment> {
     const formData = new FormData();
     formData.append("file", file);
     if (opts?.issueId) formData.append("issue_id", opts.issueId);
     if (opts?.commentId) formData.append("comment_id", opts.commentId);
+    if (opts?.chatSessionId) formData.append("chat_session_id", opts.chatSessionId);
 
     const rid = createRequestId();
     const start = Date.now();
@@ -1000,7 +1208,10 @@ export class ApiClient {
     }
 
     this.logger.info(`← ${res.status} /api/upload-file`, { rid, duration: `${Date.now() - start}ms` });
-    return res.json() as Promise<Attachment>;
+    const raw = (await res.json()) as unknown;
+    return parseWithFallback(raw, AttachmentResponseSchema, EMPTY_ATTACHMENT, {
+      endpoint: "POST /api/upload-file",
+    });
   }
 
   // Chat Sessions
@@ -1024,14 +1235,29 @@ export class ApiClient {
     await this.fetch(`/api/chat/sessions/${id}`, { method: "DELETE" });
   }
 
+  async updateChatSession(id: string, data: { title: string }): Promise<ChatSession> {
+    return this.fetch(`/api/chat/sessions/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify(data),
+    });
+  }
+
   async listChatMessages(sessionId: string): Promise<ChatMessage[]> {
     return this.fetch(`/api/chat/sessions/${sessionId}/messages`);
   }
 
-  async sendChatMessage(sessionId: string, content: string): Promise<SendChatMessageResponse> {
+  async sendChatMessage(
+    sessionId: string,
+    content: string,
+    attachmentIds?: string[],
+  ): Promise<SendChatMessageResponse> {
+    const body: { content: string; attachment_ids?: string[] } = { content };
+    if (attachmentIds && attachmentIds.length > 0) {
+      body.attachment_ids = attachmentIds;
+    }
     return this.fetch(`/api/chat/sessions/${sessionId}/messages`, {
       method: "POST",
-      body: JSON.stringify({ content }),
+      body: JSON.stringify(body),
     });
   }
 
@@ -1055,10 +1281,53 @@ export class ApiClient {
     return this.fetch(`/api/issues/${issueId}/attachments`);
   }
 
+  // Fetches a fresh attachment metadata record. The server re-signs
+  // `download_url` on every call (30 min expiry), so the click-time
+  // download flow uses this endpoint to avoid handing the user a stale
+  // signed URL cached in TanStack Query.
+  async getAttachment(id: string): Promise<Attachment> {
+    const raw = await this.fetch<unknown>(`/api/attachments/${id}`);
+    return parseWithFallback(raw, AttachmentResponseSchema, EMPTY_ATTACHMENT, {
+      endpoint: "GET /api/attachments/{id}",
+    });
+  }
+
   async deleteAttachment(id: string): Promise<void> {
     await this.fetch(`/api/attachments/${id}`, { method: "DELETE" });
   }
 
+  // Fetches the raw bytes of a text-previewable attachment.
+  //
+  // The endpoint sidesteps CloudFront CORS (not configured on the CDN) and
+  // bypasses Content-Disposition: attachment for the `text/*` family, both
+  // of which would otherwise prevent the renderer from getting the body.
+  // The server always replies with `text/plain; charset=utf-8` for safety;
+  // the original MIME ships back in the `X-Original-Content-Type` header so
+  // the preview dispatcher can choose between markdown / html / plain code.
+  //
+  // Routes through `fetchRaw` so it inherits the standard auth headers,
+  // 401 → handleUnauthorized recovery, request-id logging, and ApiError
+  // shape. 413 / 415 are translated to typed `Preview*Error` instances so
+  // the modal can render specific fallbacks instead of generic failure.
+  async getAttachmentTextContent(
+    id: string,
+  ): Promise<{ text: string; originalContentType: string }> {
+    let res: Response;
+    try {
+      res = await this.fetchRaw(`/api/attachments/${id}/content`);
+    } catch (err) {
+      if (err instanceof ApiError) {
+        if (err.status === 413) throw new PreviewTooLargeError();
+        if (err.status === 415) throw new PreviewUnsupportedError();
+      }
+      throw err;
+    }
+    return {
+      text: await res.text(),
+      originalContentType: res.headers.get("X-Original-Content-Type") ?? "",
+    };
+  }
+
   // Projects
   async listProjects(params?: { status?: string }): Promise<ListProjectsResponse> {
     const search = new URLSearchParams();
@@ -1181,6 +1450,43 @@ export class ApiClient {
     });
   }
 
+  // Squads
+  async listSquads(): Promise<Squad[]> {
+    return this.fetch(`/api/squads`);
+  }
+
+  async getSquad(id: string): Promise<Squad> {
+    return this.fetch(`/api/squads/${id}`);
+  }
+
+  async createSquad(data: { name: string; description?: string; leader_id: string }): Promise<Squad> {
+    return this.fetch("/api/squads", { method: "POST", body: JSON.stringify(data) });
+  }
+
+  async updateSquad(id: string, data: { name?: string; description?: string; instructions?: string; leader_id?: string; avatar_url?: string }): Promise<Squad> {
+    return this.fetch(`/api/squads/${id}`, { method: "PUT", body: JSON.stringify(data) });
+  }
+
+  async deleteSquad(id: string): Promise<void> {
+    await this.fetch(`/api/squads/${id}`, { method: "DELETE" });
+  }
+
+  async listSquadMembers(squadId: string): Promise<SquadMember[]> {
+    return this.fetch(`/api/squads/${squadId}/members`);
+  }
+
+  async addSquadMember(squadId: string, data: { member_type: string; member_id: string; role?: string }): Promise<SquadMember> {
+    return this.fetch(`/api/squads/${squadId}/members`, { method: "POST", body: JSON.stringify(data) });
+  }
+
+  async removeSquadMember(squadId: string, data: { member_type: string; member_id: string }): Promise<void> {
+    await this.fetch(`/api/squads/${squadId}/members`, { method: "DELETE", body: JSON.stringify(data) });
+  }
+
+  async updateSquadMemberRole(squadId: string, data: { member_type: string; member_id: string; role: string }): Promise<SquadMember> {
+    return this.fetch(`/api/squads/${squadId}/members/role`, { method: "PATCH", body: JSON.stringify(data) });
+  }
+
   // Autopilots
   async listAutopilots(params?: { status?: string }): Promise<ListAutopilotsResponse> {
     const search = new URLSearchParams();
@@ -1238,4 +1544,23 @@ export class ApiClient {
   async deleteAutopilotTrigger(autopilotId: string, triggerId: string): Promise<void> {
     await this.fetch(`/api/autopilots/${autopilotId}/triggers/${triggerId}`, { method: "DELETE" });
   }
+
+  // GitHub integration
+  async getGitHubConnectURL(workspaceId: string): Promise<GitHubConnectResponse> {
+    return this.fetch(`/api/workspaces/${workspaceId}/github/connect`);
+  }
+
+  async listGitHubInstallations(workspaceId: string): Promise<ListGitHubInstallationsResponse> {
+    return this.fetch(`/api/workspaces/${workspaceId}/github/installations`);
+  }
+
+  async deleteGitHubInstallation(workspaceId: string, installationId: string): Promise<void> {
+    await this.fetch(`/api/workspaces/${workspaceId}/github/installations/${installationId}`, {
+      method: "DELETE",
+    });
+  }
+
+  async listIssuePullRequests(issueId: string): Promise<{ pull_requests: GitHubPullRequest[] }> {
+    return this.fetch(`/api/issues/${issueId}/pull-requests`);
+  }
 }

packages/core/api/index.ts

@@ -1,4 +1,9 @@
-export { ApiClient, ApiError } from "./client";
+export {
+  ApiClient,
+  ApiError,
+  PreviewTooLargeError,
+  PreviewUnsupportedError,
+} from "./client";
 export type {
   ApiClientOptions,
   ImportStarterContentPayload,
@@ -6,6 +11,8 @@ export type {
   ImportStarterIssuePayload,
   ImportStarterWelcomeIssueTemplate,
 } from "./client";
+export { parseWithFallback, setSchemaLogger } from "./schema";
+export type { ParseOptions } from "./schema";
 export { WSClient } from "./ws-client";
 
 import type { ApiClient as ApiClientType } from "./client";

packages/core/api/schema.test.ts

@@ -0,0 +1,248 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { ApiClient } from "./client";
+import { parseWithFallback } from "./schema";
+
+// Helper: stub fetch with a single JSON response. Status defaults to 200.
+function stubFetchJson(body: unknown, status = 200) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn().mockResolvedValue(
+      new Response(typeof body === "string" ? body : JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+      }),
+    ),
+  );
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// These tests cover the five failure modes that white-screened the desktop
+// app in past incidents. The contract is: a malformed response degrades to
+// an empty/safe shape, never throws into React.
+describe("ApiClient schema fallback", () => {
+  describe("listTimeline", () => {
+    it("falls back to an empty array when the body is null", async () => {
+      stubFetchJson(null);
+      const client = new ApiClient("https://api.example.test");
+      const entries = await client.listTimeline("issue-1");
+      expect(entries).toEqual([]);
+    });
+
+    it("falls back when the body is not an array", async () => {
+      stubFetchJson({ wrong: "shape" });
+      const client = new ApiClient("https://api.example.test");
+      const entries = await client.listTimeline("issue-1");
+      expect(entries).toEqual([]);
+    });
+
+    it("accepts a new entry type rather than crashing on enum drift", async () => {
+      stubFetchJson([
+        {
+          type: "future_kind", // not in TS union
+          id: "e-1",
+          actor_type: "member",
+          actor_id: "u-1",
+          created_at: "2026-01-01T00:00:00Z",
+        },
+      ]);
+      const client = new ApiClient("https://api.example.test");
+      const entries = await client.listTimeline("issue-1");
+      expect(entries).toHaveLength(1);
+      expect(entries[0]?.type).toBe("future_kind");
+    });
+
+    // Forward-compat: when the server adds a new field to an existing
+    // shape, `.loose()` lets it pass through unchanged. Without `.loose()`
+    // zod 4 strips it, which would silently break a future TS type that
+    // adopts the field — see schemas.ts header comment.
+    it("preserves unknown fields the schema didn't list", async () => {
+      stubFetchJson([
+        {
+          type: "comment",
+          id: "e-1",
+          actor_type: "member",
+          actor_id: "u-1",
+          created_at: "2026-01-01T00:00:00Z",
+          // New server-side field not present in TimelineEntrySchema:
+          future_field: { nested: "value" },
+        },
+      ]);
+      const client = new ApiClient("https://api.example.test");
+      const entries = await client.listTimeline("issue-1");
+      const entry = entries[0] as unknown as Record<string, unknown>;
+      expect(entry.future_field).toEqual({ nested: "value" });
+    });
+  });
+
+  describe("listIssues", () => {
+    it("falls back to an empty list when the response is malformed", async () => {
+      // `issues` having the wrong type triggers the fallback. An object
+      // with only unexpected keys would *succeed* parsing now (every
+      // declared field has a default) and just pass the extras through
+      // via `.loose()`, so we use a wrong-type payload here instead.
+      stubFetchJson({ issues: "not-an-array", total: 0 });
+      const client = new ApiClient("https://api.example.test");
+      const res = await client.listIssues();
+      expect(res).toEqual({ issues: [], total: 0 });
+    });
+  });
+
+  describe("listComments", () => {
+    it("returns [] when the response is not an array", async () => {
+      stubFetchJson({ wrong: "shape" });
+      const client = new ApiClient("https://api.example.test");
+      const comments = await client.listComments("issue-1");
+      expect(comments).toEqual([]);
+    });
+  });
+
+  describe("listIssueSubscribers", () => {
+    it("returns [] when the response is null", async () => {
+      stubFetchJson(null);
+      const client = new ApiClient("https://api.example.test");
+      const subs = await client.listIssueSubscribers("issue-1");
+      expect(subs).toEqual([]);
+    });
+  });
+
+  describe("listChildIssues", () => {
+    it("returns { issues: [] } when the issues field is missing", async () => {
+      stubFetchJson({});
+      const client = new ApiClient("https://api.example.test");
+      const res = await client.listChildIssues("issue-1");
+      expect(res).toEqual({ issues: [] });
+    });
+  });
+
+  // Agent template catalog is hit by the desktop create-agent picker.
+  // Installed desktop builds outlive any given server, so the shape MUST
+  // survive future field renames / wrapping without crashing. Each test
+  // here mirrors a concrete future drift we want to absorb.
+  describe("listAgentTemplates", () => {
+    it("falls back to [] when the body is null", async () => {
+      stubFetchJson(null);
+      const client = new ApiClient("https://api.example.test");
+      const tmpls = await client.listAgentTemplates();
+      expect(tmpls).toEqual([]);
+    });
+
+    it("defaults skills to [] when the field is missing from a template", async () => {
+      // Future server: drops `skills` because the picker no longer reads
+      // them. Picker code calls `template.skills.length` — must not throw.
+      stubFetchJson([{ slug: "x", name: "X" }]);
+      const client = new ApiClient("https://api.example.test");
+      const tmpls = await client.listAgentTemplates();
+      expect(tmpls).toHaveLength(1);
+      expect(tmpls[0]?.skills).toEqual([]);
+    });
+
+    it("accepts the bare-array shape (current contract)", async () => {
+      stubFetchJson([
+        { slug: "a", name: "A", description: "", skills: [] },
+        { slug: "b", name: "B", description: "", skills: [] },
+      ]);
+      const client = new ApiClient("https://api.example.test");
+      const tmpls = await client.listAgentTemplates();
+      expect(tmpls.map((t) => t.slug)).toEqual(["a", "b"]);
+    });
+
+    it("accepts a future {templates: [...]} envelope without breaking", async () => {
+      // Server migrates to a paginated envelope. We unwrap so the picker
+      // keeps working on the older bare-array consumer.
+      stubFetchJson({
+        templates: [{ slug: "a", name: "A", description: "", skills: [] }],
+        total: 1,
+      });
+      const client = new ApiClient("https://api.example.test");
+      const tmpls = await client.listAgentTemplates();
+      expect(tmpls).toHaveLength(1);
+      expect(tmpls[0]?.slug).toBe("a");
+    });
+  });
+
+  describe("getAgentTemplate", () => {
+    it("falls back to a minimal record carrying the requested slug", async () => {
+      // Slug is part of the URL the user clicked — the fallback round-
+      // trips it so the page header still makes sense after a parse miss.
+      stubFetchJson({ wrong: "shape" });
+      const client = new ApiClient("https://api.example.test");
+      const detail = await client.getAgentTemplate("code-reviewer");
+      expect(detail.slug).toBe("code-reviewer");
+      expect(detail.skills).toEqual([]);
+      expect(detail.instructions).toBe("");
+    });
+
+    it("defaults instructions to '' when the field is missing", async () => {
+      stubFetchJson({
+        slug: "code-reviewer",
+        name: "Code Reviewer",
+        description: "",
+        skills: [],
+      });
+      const client = new ApiClient("https://api.example.test");
+      const detail = await client.getAgentTemplate("code-reviewer");
+      expect(detail.instructions).toBe("");
+    });
+  });
+
+  describe("createAgentFromTemplate", () => {
+    it("falls back to an empty agent when the response is malformed", async () => {
+      // The agent was created server-side even though the client can't
+      // parse the response — UI code reads `agent.id === ""` and skips
+      // the navigation step rather than landing on `/agents/`.
+      stubFetchJson({ unexpected: "shape" });
+      const client = new ApiClient("https://api.example.test");
+      const resp = await client.createAgentFromTemplate({
+        template_slug: "x",
+        name: "X",
+        runtime_id: "rt-1",
+      });
+      expect(resp.agent.id).toBe("");
+      expect(resp.imported_skill_ids).toEqual([]);
+      expect(resp.reused_skill_ids).toEqual([]);
+    });
+
+    it("defaults imported_skill_ids / reused_skill_ids to [] when missing", async () => {
+      stubFetchJson({ agent: { id: "agent-1" } });
+      const client = new ApiClient("https://api.example.test");
+      const resp = await client.createAgentFromTemplate({
+        template_slug: "x",
+        name: "X",
+        runtime_id: "rt-1",
+      });
+      expect(resp.agent.id).toBe("agent-1");
+      expect(resp.imported_skill_ids).toEqual([]);
+      expect(resp.reused_skill_ids).toEqual([]);
+    });
+  });
+});
+
+// Direct tests for the helper, decoupled from any specific endpoint —
+// guards against an endpoint refactor masking a regression in the helper.
+describe("parseWithFallback", () => {
+  const opts = { endpoint: "TEST /unit" };
+
+  it("returns parsed data on success", () => {
+    const schema = z.object({ id: z.string() });
+    const out = parseWithFallback({ id: "x" }, schema, { id: "fallback" }, opts);
+    expect(out).toEqual({ id: "x" });
+  });
+
+  it("returns the fallback when validation fails", () => {
+    const schema = z.object({ id: z.string() });
+    const fallback = { id: "fallback" };
+    const out = parseWithFallback({ id: 123 }, schema, fallback, opts);
+    expect(out).toBe(fallback);
+  });
+
+  it("returns the fallback when data is null", () => {
+    const schema = z.object({ id: z.string() });
+    const fallback = { id: "fallback" };
+    const out = parseWithFallback(null, schema, fallback, opts);
+    expect(out).toBe(fallback);
+  });
+});

packages/core/api/schema.ts

@@ -0,0 +1,55 @@
+import type { ZodType } from "zod";
+import { type Logger, noopLogger } from "../logger";
+
+// Module-level logger for schema warnings. Defaults to no-op so test
+// runs don't spam stderr; the platform layer wires a real logger via
+// `setSchemaLogger` at app boot.
+let schemaLogger: Logger = noopLogger;
+
+export function setSchemaLogger(logger: Logger): void {
+  schemaLogger = logger;
+}
+
+export interface ParseOptions {
+  /** Endpoint identifier used in the warning log so we can grep for which
+   *  contract drifted in production telemetry. */
+  endpoint: string;
+}
+
+/**
+ * Validate a JSON value parsed from an API response against a zod schema,
+ * returning the parsed value on success or `fallback` on failure.
+ *
+ * On failure we log a warning with the endpoint and zod's structured error,
+ * but never throw — the UI layer must keep rendering. This is the boundary
+ * defense that turns "API contract drifted" from a white-screen incident
+ * into a degraded-but-rendering page.
+ *
+ * The return type is anchored to `T` (inferred from `fallback`), not to the
+ * schema's `z.infer` type. Schemas are intentionally **lenient** — string
+ * enums kept as `z.string()` so an unknown enum value still parses, etc. —
+ * so the parsed runtime value can be wider than the strict TS type at the
+ * call site. The caller asserts compatibility by typing the fallback to the
+ * expected `T`; downstream code is already responsible for handling unknown
+ * enum values via `default`-bearing switches and optional chaining.
+ *
+ * See CLAUDE.md "API Response Compatibility" for when to reach for this.
+ */
+export function parseWithFallback<T>(
+  data: unknown,
+  schema: ZodType,
+  fallback: T,
+  opts: ParseOptions,
+): T {
+  const result = schema.safeParse(data);
+  if (result.success) return result.data as T;
+  schemaLogger.warn(
+    `API response failed schema validation: ${opts.endpoint}`,
+    {
+      endpoint: opts.endpoint,
+      issues: result.error.issues,
+      received: data,
+    },
+  );
+  return fallback;
+}

packages/core/api/schemas.ts

@@ -0,0 +1,308 @@
+import { z } from "zod";
+import type {
+  Agent,
+  AgentTemplate,
+  AgentTemplateSummary,
+  Attachment,
+  CreateAgentFromTemplateResponse,
+  ListIssuesResponse,
+  TimelineEntry,
+} from "../types";
+
+// ---------------------------------------------------------------------------
+// Schemas for the highest-risk API endpoints — those whose responses drive
+// the issue detail page (timeline, comments, subscribers) and the issues
+// list. These are the surfaces that white-screened in #2143 / #2147 / #2192.
+//
+// These schemas are intentionally LENIENT:
+//   - String enums are stored as `z.string()` rather than `z.enum([...])`.
+//     A new server-side enum value should render as a generic fallback in
+//     the UI, never crash a `safeParse`.
+//   - Optional fields are unioned with `null` and given fallbacks where
+//     existing UI code already coerces them.
+//   - Arrays default to `[]` so a missing `reactions` / `attachments` /
+//     `entries` field doesn't take the page down.
+//   - Every object schema ends with `.loose()` so unknown server-side
+//     fields pass through unchanged. zod 4's `.object()` defaults to STRIP,
+//     which would silently delete fields the schema didn't explicitly list
+//     — fine while the TS type doesn't claim them, but the moment a future
+//     PR adds a TS field without updating the schema, the cast `as T` lies
+//     and the field shows up as `undefined` at runtime. `.loose()` removes
+//     that synchronisation hazard.
+//
+// These schemas are deliberately not typed as `z.ZodType<TimelineEntry>` /
+// `z.ZodType<Issue>` etc. — the strict TS types narrow string fields to
+// literal unions, which would defeat the leniency above. `parseWithFallback`
+// returns the parsed value cast to the caller-supplied `T`, so the strict
+// type still flows out at the call site; the schema only guards shape.
+// ---------------------------------------------------------------------------
+
+const ReactionSchema = z.object({
+  id: z.string(),
+  comment_id: z.string(),
+  actor_type: z.string(),
+  actor_id: z.string(),
+  emoji: z.string(),
+  created_at: z.string(),
+});
+
+// Nested attachments embedded in timeline/comment responses stay lenient on
+// purpose: a single malformed attachment must not knock the whole timeline
+// into the fallback `[]`.
+const AttachmentSchema = z.object({
+  id: z.string(),
+}).loose();
+
+// Standalone attachment lookup (`GET /api/attachments/{id}`) is the source of
+// truth for click-time download URLs. The two fields the download flow opens
+// in a new tab — `download_url` and `url` — must be strings, otherwise we'd
+// happily `window.open(undefined)`. `filename` gates the toast/title and is
+// also enforced so a missing value falls back to the empty record below.
+export const AttachmentResponseSchema = z.object({
+  id: z.string(),
+  url: z.string(),
+  download_url: z.string(),
+  filename: z.string(),
+  chat_session_id: z.string().nullable().optional(),
+  chat_message_id: z.string().nullable().optional(),
+}).loose();
+
+export const EMPTY_ATTACHMENT: Attachment = {
+  id: "",
+  workspace_id: "",
+  issue_id: null,
+  comment_id: null,
+  chat_session_id: null,
+  chat_message_id: null,
+  uploader_type: "",
+  uploader_id: "",
+  filename: "",
+  url: "",
+  download_url: "",
+  content_type: "",
+  size_bytes: 0,
+  created_at: "",
+};
+
+// All object schemas use `.loose()` so unknown server-side fields pass
+// through unchanged. zod 4's `.object()` defaults to STRIP, which would
+// silently drop new fields and surface as a "field neither showed up in
+// the UI" mystery the next time the TS type adopted them but the schema
+// wasn't updated in lock-step. `.loose()` removes that synchronisation
+// hazard — the schema validates the shape it knows about and leaves the
+// rest alone.
+const TimelineEntrySchema = z.object({
+  type: z.string(),
+  id: z.string(),
+  actor_type: z.string(),
+  actor_id: z.string(),
+  created_at: z.string(),
+  action: z.string().optional(),
+  details: z.record(z.string(), z.unknown()).optional(),
+  content: z.string().optional(),
+  parent_id: z.string().nullable().optional(),
+  updated_at: z.string().optional(),
+  comment_type: z.string().optional(),
+  reactions: z.array(ReactionSchema).optional(),
+  attachments: z.array(AttachmentSchema).optional(),
+  coalesced_count: z.number().optional(),
+}).loose();
+
+// /timeline returns a flat array of TimelineEntry, oldest first. The
+// previously cursor-paginated wrapper was removed (#1929) — at observed data
+// sizes (p99 ~30 entries per issue) paged delivery only created bugs.
+export const TimelineEntriesSchema = z.array(TimelineEntrySchema);
+
+export const EMPTY_TIMELINE_ENTRIES: TimelineEntry[] = [];
+
+export const CommentSchema = z.object({
+  id: z.string(),
+  issue_id: z.string(),
+  author_type: z.string(),
+  author_id: z.string(),
+  content: z.string(),
+  type: z.string(),
+  parent_id: z.string().nullable(),
+  reactions: z.array(ReactionSchema).default([]),
+  attachments: z.array(AttachmentSchema).default([]),
+  created_at: z.string(),
+  updated_at: z.string(),
+}).loose();
+
+export const CommentsListSchema = z.array(CommentSchema);
+
+const IssueSchema = z.object({
+  id: z.string(),
+  workspace_id: z.string(),
+  number: z.number(),
+  identifier: z.string(),
+  title: z.string(),
+  description: z.string().nullable(),
+  status: z.string(),
+  priority: z.string(),
+  assignee_type: z.string().nullable(),
+  assignee_id: z.string().nullable(),
+  creator_type: z.string(),
+  creator_id: z.string(),
+  parent_issue_id: z.string().nullable(),
+  project_id: z.string().nullable(),
+  position: z.number(),
+  due_date: z.string().nullable(),
+  reactions: z.array(z.unknown()).optional(),
+  labels: z.array(z.unknown()).optional(),
+  created_at: z.string(),
+  updated_at: z.string(),
+}).loose();
+
+export const ListIssuesResponseSchema = z.object({
+  issues: z.array(IssueSchema).default([]),
+  total: z.number().default(0),
+}).loose();
+
+export const EMPTY_LIST_ISSUES_RESPONSE: ListIssuesResponse = {
+  issues: [],
+  total: 0,
+};
+
+const SubscriberSchema = z.object({
+  issue_id: z.string(),
+  user_type: z.string(),
+  user_id: z.string(),
+  reason: z.string(),
+  created_at: z.string(),
+}).loose();
+
+export const SubscribersListSchema = z.array(SubscriberSchema);
+
+export const ChildIssuesResponseSchema = z.object({
+  issues: z.array(IssueSchema).default([]),
+}).loose();
+
+// ---------------------------------------------------------------------------
+// Workspace dashboard schemas
+//
+// The dashboard hits three independent rollup endpoints. Each returns a flat
+// array, and every field is consumed by chart / KPI math — a missing number
+// silently degrades to NaN downstream, so we coerce missing numbers to 0.
+// String fields stay lenient (no enum narrowing) to survive future model /
+// agent ID drift.
+// ---------------------------------------------------------------------------
+
+const DashboardUsageDailySchema = z.object({
+  date: z.string(),
+  model: z.string(),
+  input_tokens: z.number().default(0),
+  output_tokens: z.number().default(0),
+  cache_read_tokens: z.number().default(0),
+  cache_write_tokens: z.number().default(0),
+  task_count: z.number().default(0),
+}).loose();
+
+export const DashboardUsageDailyListSchema = z.array(DashboardUsageDailySchema);
+
+const DashboardUsageByAgentSchema = z.object({
+  agent_id: z.string(),
+  model: z.string(),
+  input_tokens: z.number().default(0),
+  output_tokens: z.number().default(0),
+  cache_read_tokens: z.number().default(0),
+  cache_write_tokens: z.number().default(0),
+  task_count: z.number().default(0),
+}).loose();
+
+export const DashboardUsageByAgentListSchema = z.array(DashboardUsageByAgentSchema);
+
+const DashboardAgentRunTimeSchema = z.object({
+  agent_id: z.string(),
+  total_seconds: z.number().default(0),
+  task_count: z.number().default(0),
+  failed_count: z.number().default(0),
+}).loose();
+
+export const DashboardAgentRunTimeListSchema = z.array(DashboardAgentRunTimeSchema);
+
+// ---------------------------------------------------------------------------
+// Agent template catalog — `/api/agent-templates*` and the
+// create-from-template response. The desktop app's create-agent picker
+// reaches these endpoints, and a future server change to the template shape
+// would white-screen older installed builds (#2192 pattern) without these
+// parsers. Lenient by the same rules as IssueSchema above: arrays default to
+// `[]`, optional fields stay optional, `.loose()` lets unknown fields pass
+// through unchanged.
+// ---------------------------------------------------------------------------
+
+const AgentTemplateSkillRefSchema = z.object({
+  source_url: z.string(),
+  cached_name: z.string().default(""),
+  cached_description: z.string().default(""),
+}).loose();
+
+const AgentTemplateSummarySchemaBase = z.object({
+  slug: z.string(),
+  name: z.string(),
+  description: z.string().default(""),
+  category: z.string().optional(),
+  icon: z.string().optional(),
+  accent: z.string().optional(),
+  // skills MUST default to [] — picker code reads `template.skills.length`
+  // and `.map(...)`, both of which crash on `undefined`. The most common
+  // future drift (field renamed / wrapped) lands here.
+  skills: z.array(AgentTemplateSkillRefSchema).default([]),
+}).loose();
+
+export const AgentTemplateSummarySchema = AgentTemplateSummarySchemaBase;
+
+// List endpoint historically returns a bare array. Server could legitimately
+// migrate to `{templates: [...]}` later — we accept either shape so an old
+// desktop survives the upgrade.
+export const AgentTemplateSummaryListSchema = z.union([
+  z.array(AgentTemplateSummarySchemaBase),
+  z.object({ templates: z.array(AgentTemplateSummarySchemaBase).default([]) })
+    .loose()
+    .transform((v) => v.templates),
+]);
+
+export const EMPTY_AGENT_TEMPLATE_SUMMARY_LIST: AgentTemplateSummary[] = [];
+
+export const AgentTemplateSchema = AgentTemplateSummarySchemaBase.extend({
+  // Detail-only field. Default "" so a malformed detail still renders the
+  // header + skill list; the user just sees an empty Instructions block.
+  instructions: z.string().default(""),
+}).loose();
+
+// Used as the parse fallback for `GET /api/agent-templates/:slug`. Slug comes
+// from the URL, so we round-trip the requested one back into the fallback
+// at the call site (see `getAgentTemplate` in client.ts).
+export const EMPTY_AGENT_TEMPLATE_DETAIL: AgentTemplate = {
+  slug: "",
+  name: "",
+  description: "",
+  skills: [],
+  instructions: "",
+};
+
+// `agent` is a full Agent record — schematising every field would duplicate
+// a 50-field interface and bit-rot fast. We keep it loose and require only
+// `id`, the one field the create-from-template flow consumes (used to
+// navigate to the new agent's detail page). Downstream code already
+// optional-chains the rest.
+const MinimalAgentSchema = z.object({
+  id: z.string(),
+}).loose();
+
+export const CreateAgentFromTemplateResponseSchema = z.object({
+  agent: MinimalAgentSchema,
+  imported_skill_ids: z.array(z.string()).default([]),
+  reused_skill_ids: z.array(z.string()).default([]),
+}).loose();
+
+// Fallback when the success response fails to parse. The agent server-side
+// has likely been created already, so we can't pretend nothing happened —
+// the caller (`create-agent-dialog.tsx`) is responsible for noticing
+// `agent.id === ""` and skipping navigation while keeping the list
+// invalidation, so the user finds their new agent in the list.
+export const EMPTY_CREATE_AGENT_FROM_TEMPLATE_RESPONSE: CreateAgentFromTemplateResponse = {
+  agent: { id: "" } as Agent,
+  imported_skill_ids: [],
+  reused_skill_ids: [],
+};

packages/core/chat/mutations.ts

@@ -24,14 +24,13 @@ export function useCreateChatSession() {
     },
     onSettled: () => {
       qc.invalidateQueries({ queryKey: chatKeys.sessions(wsId) });
-      qc.invalidateQueries({ queryKey: chatKeys.allSessions(wsId) });
     },
   });
 }
 
 /**
  * Clears the session's unread state server-side. Optimistically flips
- * has_unread to false in the cached lists so the FAB badge drops
+ * has_unread to false in the cached list so the FAB badge drops
  * immediately. The server broadcasts chat:session_read so other devices
  * also sync.
  */
@@ -46,35 +45,69 @@ export function useMarkChatSessionRead() {
     },
     onMutate: async (sessionId) => {
       await qc.cancelQueries({ queryKey: chatKeys.sessions(wsId) });
-      await qc.cancelQueries({ queryKey: chatKeys.allSessions(wsId) });
 
       const prevSessions = qc.getQueryData<ChatSession[]>(chatKeys.sessions(wsId));
-      const prevAll = qc.getQueryData<ChatSession[]>(chatKeys.allSessions(wsId));
 
       const clear = (old?: ChatSession[]) =>
         old?.map((s) => (s.id === sessionId ? { ...s, has_unread: false } : s));
       qc.setQueryData<ChatSession[]>(chatKeys.sessions(wsId), clear);
-      qc.setQueryData<ChatSession[]>(chatKeys.allSessions(wsId), clear);
 
-      return { prevSessions, prevAll };
+      return { prevSessions };
     },
     onError: (err, sessionId, ctx) => {
       logger.error("markChatSessionRead.error.rollback", { sessionId, err });
       if (ctx?.prevSessions) qc.setQueryData(chatKeys.sessions(wsId), ctx.prevSessions);
-      if (ctx?.prevAll) qc.setQueryData(chatKeys.allSessions(wsId), ctx.prevAll);
     },
     onSettled: () => {
       qc.invalidateQueries({ queryKey: chatKeys.sessions(wsId) });
-      qc.invalidateQueries({ queryKey: chatKeys.allSessions(wsId) });
     },
   });
 }
 
 /**
- * Hard-deletes a chat session. Optimistically removes the row from both
- * the active and all-sessions lists so the history panel updates instantly;
- * rolls back on error. The matching `chat:session_deleted` WS event keeps
- * other tabs/devices in sync — see use-realtime-sync.ts.
+ * Renames a chat session. Optimistically swaps the title in the cached
+ * list so the dropdown reflects the new label immediately; rolls back on
+ * error. The matching `chat:session_updated` WS event keeps other
+ * tabs/devices in sync — see use-realtime-sync.ts.
+ */
+export function useUpdateChatSession() {
+  const qc = useQueryClient();
+  const wsId = useWorkspaceId();
+
+  return useMutation({
+    mutationFn: (data: { sessionId: string; title: string }) => {
+      logger.info("updateChatSession.start", {
+        sessionId: data.sessionId,
+        titleLength: data.title.length,
+      });
+      return api.updateChatSession(data.sessionId, { title: data.title });
+    },
+    onMutate: async ({ sessionId, title }) => {
+      await qc.cancelQueries({ queryKey: chatKeys.sessions(wsId) });
+
+      const prevSessions = qc.getQueryData<ChatSession[]>(chatKeys.sessions(wsId));
+
+      const patch = (old?: ChatSession[]) =>
+        old?.map((s) => (s.id === sessionId ? { ...s, title } : s));
+      qc.setQueryData<ChatSession[]>(chatKeys.sessions(wsId), patch);
+
+      return { prevSessions };
+    },
+    onError: (err, vars, ctx) => {
+      logger.error("updateChatSession.error.rollback", { sessionId: vars.sessionId, err });
+      if (ctx?.prevSessions) qc.setQueryData(chatKeys.sessions(wsId), ctx.prevSessions);
+    },
+    onSettled: () => {
+      qc.invalidateQueries({ queryKey: chatKeys.sessions(wsId) });
+    },
+  });
+}
+
+/**
+ * Hard-deletes a chat session. Optimistically removes the row from the
+ * sessions list so the dropdown updates instantly; rolls back on error.
+ * The matching `chat:session_deleted` WS event keeps other tabs/devices
+ * in sync — see use-realtime-sync.ts.
  */
 export function useDeleteChatSession() {
   const qc = useQueryClient();
@@ -87,27 +120,22 @@ export function useDeleteChatSession() {
     },
     onMutate: async (sessionId) => {
       await qc.cancelQueries({ queryKey: chatKeys.sessions(wsId) });
-      await qc.cancelQueries({ queryKey: chatKeys.allSessions(wsId) });
 
       const prevSessions = qc.getQueryData<ChatSession[]>(chatKeys.sessions(wsId));
-      const prevAll = qc.getQueryData<ChatSession[]>(chatKeys.allSessions(wsId));
 
       const drop = (old?: ChatSession[]) => old?.filter((s) => s.id !== sessionId);
       qc.setQueryData<ChatSession[]>(chatKeys.sessions(wsId), drop);
-      qc.setQueryData<ChatSession[]>(chatKeys.allSessions(wsId), drop);
 
       logger.debug("deleteChatSession.optimistic", { sessionId });
-      return { prevSessions, prevAll };
+      return { prevSessions };
     },
     onError: (err, sessionId, ctx) => {
       logger.error("deleteChatSession.error.rollback", { sessionId, err });
       if (ctx?.prevSessions) qc.setQueryData(chatKeys.sessions(wsId), ctx.prevSessions);
-      if (ctx?.prevAll) qc.setQueryData(chatKeys.allSessions(wsId), ctx.prevAll);
     },
     onSettled: (_data, _err, sessionId) => {
       logger.debug("deleteChatSession.settled", { sessionId });
       qc.invalidateQueries({ queryKey: chatKeys.sessions(wsId) });
-      qc.invalidateQueries({ queryKey: chatKeys.allSessions(wsId) });
     },
   });
 }

packages/core/chat/queries.ts

@@ -10,8 +10,8 @@ import { api } from "../api";
 
 export const chatKeys = {
   all: (wsId: string) => ["chat", wsId] as const,
+  /** Full sessions list (active + archived); the dropdown splits locally. */
   sessions: (wsId: string) => [...chatKeys.all(wsId), "sessions"] as const,
-  allSessions: (wsId: string) => [...chatKeys.all(wsId), "sessions", "all"] as const,
   session: (wsId: string, id: string) => [...chatKeys.all(wsId), "session", id] as const,
   messages: (sessionId: string) => ["chat", "messages", sessionId] as const,
   pendingTask: (sessionId: string) => ["chat", "pending-task", sessionId] as const,
@@ -24,14 +24,6 @@ export const chatKeys = {
 export function chatSessionsOptions(wsId: string) {
   return queryOptions({
     queryKey: chatKeys.sessions(wsId),
-    queryFn: () => api.listChatSessions(),
-    staleTime: Infinity,
-  });
-}
-
-export function allChatSessionsOptions(wsId: string) {
-  return queryOptions({
-    queryKey: chatKeys.allSessions(wsId),
     queryFn: () => api.listChatSessions({ status: "all" }),
     staleTime: Infinity,
   });

packages/core/chat/store.ts

@@ -87,7 +87,6 @@ export interface ChatState {
   isOpen: boolean;
   activeSessionId: string | null;
   selectedAgentId: string | null;
-  showHistory: boolean;
   /** Drafts per session: sessionId (or DRAFT_NEW_SESSION) → markdown text. */
   inputDrafts: Record<string, string>;
   /**
@@ -104,7 +103,6 @@ export interface ChatState {
   toggle: () => void;
   setActiveSession: (id: string | null) => void;
   setSelectedAgentId: (id: string) => void;
-  setShowHistory: (show: boolean) => void;
   /** sessionId accepts a real session UUID or DRAFT_NEW_SESSION. */
   setInputDraft: (sessionId: string, draft: string) => void;
   clearInputDraft: (sessionId: string) => void;
@@ -136,7 +134,6 @@ export function createChatStore(options: ChatStoreOptions) {
     isOpen: initialIsOpen,
     activeSessionId: storage.getItem(wsKey(SESSION_STORAGE_KEY)),
     selectedAgentId: storage.getItem(wsKey(AGENT_STORAGE_KEY)),
-    showHistory: false,
     inputDrafts: readDrafts(storage, wsKey(DRAFTS_KEY)),
     focusMode: storage.getItem(FOCUS_MODE_KEY) === "true",
     chatWidth: Number(storage.getItem(CHAT_WIDTH_KEY)) || CHAT_DEFAULT_W,
@@ -167,10 +164,6 @@ export function createChatStore(options: ChatStoreOptions) {
       storage.setItem(wsKey(AGENT_STORAGE_KEY), id);
       set({ selectedAgentId: id });
     },
-    setShowHistory: (show) => {
-      logger.debug("setShowHistory", { to: show });
-      set({ showHistory: show });
-    },
     setInputDraft: (sessionId, draft) => {
       // Debug level — onUpdate fires on every keystroke.
       logger.debug("setInputDraft", { sessionId, length: draft.length });

packages/core/dashboard/index.ts

@@ -0,0 +1 @@
+export * from "./queries";

packages/core/dashboard/queries.ts

@@ -0,0 +1,72 @@
+import { queryOptions } from "@tanstack/react-query";
+import { api } from "../api";
+
+// Workspace dashboard query options. All three endpoints share the same
+// (wsId, days, projectId) key shape so workspace switching, time-range
+// changes, and the project filter each invalidate the cache cleanly.
+//
+// The cache key includes `wsId` explicitly: TanStack Query already isolates
+// per workspace via the key, but threading wsId into the queryFn lets
+// callers fail fast (return [] on empty wsId) instead of issuing a request
+// the server would reject.
+//
+// `projectId` is normalised to `null` (not undefined / "all") so the
+// queryKey shape is stable across renders even when the dropdown sits on
+// "all projects".
+
+export const dashboardKeys = {
+  all: (wsId: string) => ["dashboard", wsId] as const,
+  daily: (wsId: string, days: number, projectId: string | null) =>
+    [...dashboardKeys.all(wsId), "daily", days, projectId] as const,
+  byAgent: (wsId: string, days: number, projectId: string | null) =>
+    [...dashboardKeys.all(wsId), "by-agent", days, projectId] as const,
+  agentRuntime: (wsId: string, days: number, projectId: string | null) =>
+    [...dashboardKeys.all(wsId), "agent-runtime", days, projectId] as const,
+};
+
+// 60s staleTime matches the per-runtime usage queries — the data is rollup-
+// driven on the server (5-min rollup cadence) and the dashboard isn't a
+// real-time view, so background refetches every minute are plenty.
+const STALE_TIME = 60 * 1000;
+
+export function dashboardUsageDailyOptions(
+  wsId: string,
+  days: number,
+  projectId: string | null,
+) {
+  return queryOptions({
+    queryKey: dashboardKeys.daily(wsId, days, projectId),
+    queryFn: () =>
+      api.getDashboardUsageDaily({ days, project_id: projectId ?? undefined }),
+    enabled: !!wsId,
+    staleTime: STALE_TIME,
+  });
+}
+
+export function dashboardUsageByAgentOptions(
+  wsId: string,
+  days: number,
+  projectId: string | null,
+) {
+  return queryOptions({
+    queryKey: dashboardKeys.byAgent(wsId, days, projectId),
+    queryFn: () =>
+      api.getDashboardUsageByAgent({ days, project_id: projectId ?? undefined }),
+    enabled: !!wsId,
+    staleTime: STALE_TIME,
+  });
+}
+
+export function dashboardAgentRunTimeOptions(
+  wsId: string,
+  days: number,
+  projectId: string | null,
+) {
+  return queryOptions({
+    queryKey: dashboardKeys.agentRuntime(wsId, days, projectId),
+    queryFn: () =>
+      api.getDashboardAgentRunTime({ days, project_id: projectId ?? undefined }),
+    enabled: !!wsId,
+    staleTime: STALE_TIME,
+  });
+}

packages/core/github/index.ts

@@ -0,0 +1 @@
+export * from "./queries";

packages/core/github/queries.ts

@@ -0,0 +1,22 @@
+import { queryOptions } from "@tanstack/react-query";
+import { api } from "../api";
+
+export const githubKeys = {
+  all: (wsId: string) => ["github", wsId] as const,
+  installations: (wsId: string) => [...githubKeys.all(wsId), "installations"] as const,
+  pullRequests: (issueId: string) => ["github", "pull-requests", issueId] as const,
+};
+
+export const githubInstallationsOptions = (wsId: string) =>
+  queryOptions({
+    queryKey: githubKeys.installations(wsId),
+    queryFn: () => api.listGitHubInstallations(wsId),
+    enabled: !!wsId,
+  });
+
+export const issuePullRequestsOptions = (issueId: string) =>
+  queryOptions({
+    queryKey: githubKeys.pullRequests(issueId),
+    queryFn: () => api.listIssuePullRequests(issueId),
+    enabled: !!issueId,
+  });

packages/core/hooks/use-file-upload.ts

@@ -5,15 +5,16 @@ import type { ApiClient } from "../api/client";
 import type { Attachment } from "../types";
 import { MAX_FILE_SIZE } from "../constants/upload";
 
-export interface UploadResult {
-  id: string;
-  filename: string;
-  link: string;
-}
+// Carries the full Attachment so editors that need preview metadata
+// (`content_type`, `download_url`) get it directly; `link` is kept as an
+// alias for `url` because many callers persist it into Markdown / avatar
+// fields by that name.
+export type UploadResult = Attachment & { link: string };
 
 export interface UploadContext {
   issueId?: string;
   commentId?: string;
+  chatSessionId?: string;
 }
 
 export function useFileUpload(
@@ -33,8 +34,9 @@ export function useFileUpload(
         const att: Attachment = await api.uploadFile(file, {
           issueId: ctx?.issueId,
           commentId: ctx?.commentId,
+          chatSessionId: ctx?.chatSessionId,
         });
-        return { id: att.id, filename: att.filename, link: att.url };
+        return { ...att, link: att.url };
       } finally {
         setUploading(false);
       }

packages/core/issues/config/priority.ts

@@ -12,9 +12,9 @@ export const PRIORITY_CONFIG: Record<
   IssuePriority,
   { label: string; bars: number; color: string; badgeBg: string; badgeText: string }
 > = {
-  urgent: { label: "Urgent", bars: 4, color: "text-destructive", badgeBg: "bg-priority", badgeText: "text-white" },
-  high: { label: "High", bars: 3, color: "text-warning", badgeBg: "bg-priority/80", badgeText: "text-white" },
-  medium: { label: "Medium", bars: 2, color: "text-warning", badgeBg: "bg-priority/15", badgeText: "text-priority" },
-  low: { label: "Low", bars: 1, color: "text-info", badgeBg: "bg-priority/10", badgeText: "text-priority" },
+  urgent: { label: "Urgent", bars: 4, color: "text-destructive", badgeBg: "bg-destructive/10", badgeText: "text-destructive" },
+  high: { label: "High", bars: 3, color: "text-warning", badgeBg: "bg-warning/10", badgeText: "text-warning" },
+  medium: { label: "Medium", bars: 2, color: "text-warning", badgeBg: "bg-warning/10", badgeText: "text-warning" },
+  low: { label: "Low", bars: 1, color: "text-info", badgeBg: "bg-info/10", badgeText: "text-info" },
   none: { label: "No priority", bars: 0, color: "text-muted-foreground", badgeBg: "bg-muted", badgeText: "text-muted-foreground" },
 };

packages/core/issues/delete-cache.ts

@@ -0,0 +1,166 @@
+import type { QueryClient, QueryKey } from "@tanstack/react-query";
+import {
+  agentActivityKeys,
+  agentRunCountsKeys,
+  agentTaskSnapshotKeys,
+  agentTasksKeys,
+} from "../agents/queries";
+import { labelKeys } from "../labels/queries";
+import type { Issue, ListIssuesCache } from "../types";
+import { findIssueLocation, removeIssueFromBuckets } from "./cache-helpers";
+import { issueKeys } from "./queries";
+
+export type DeletedIssueCacheMetadata = {
+  parentIssueIds: string[];
+};
+
+function collectParentId(
+  parentIssueIds: Set<string>,
+  parentId: string | null | undefined,
+) {
+  if (parentId) parentIssueIds.add(parentId);
+}
+
+function collectParentFromListCache(
+  parentIssueIds: Set<string>,
+  data: ListIssuesCache | undefined,
+  issueId: string,
+) {
+  const parentId = data
+    ? findIssueLocation(data, issueId)?.issue.parent_issue_id
+    : undefined;
+  collectParentId(parentIssueIds, parentId);
+}
+
+function parentIdFromChildrenKey(key: QueryKey) {
+  const parentId = key[key.length - 1];
+  return typeof parentId === "string" ? parentId : null;
+}
+
+export function collectDeletedIssueCacheMetadata(
+  qc: QueryClient,
+  wsId: string,
+  issueId: string,
+): DeletedIssueCacheMetadata {
+  const parentIssueIds = new Set<string>();
+
+  const detail = qc.getQueryData<Issue>(issueKeys.detail(wsId, issueId));
+  collectParentId(parentIssueIds, detail?.parent_issue_id);
+
+  collectParentFromListCache(
+    parentIssueIds,
+    qc.getQueryData<ListIssuesCache>(issueKeys.list(wsId)),
+    issueId,
+  );
+
+  for (const [, data] of qc.getQueriesData<ListIssuesCache>({
+    queryKey: issueKeys.myAll(wsId),
+  })) {
+    collectParentFromListCache(parentIssueIds, data, issueId);
+  }
+
+  for (const [key, data] of qc.getQueriesData<Issue[]>({
+    queryKey: [...issueKeys.all(wsId), "children"],
+  })) {
+    const child = data?.find((issue) => issue.id === issueId);
+    if (!child) continue;
+    collectParentId(parentIssueIds, child.parent_issue_id);
+    collectParentId(parentIssueIds, parentIdFromChildrenKey(key));
+  }
+
+  return { parentIssueIds: Array.from(parentIssueIds) };
+}
+
+export function pruneDeletedIssueFromListCaches(
+  qc: QueryClient,
+  wsId: string,
+  issueId: string,
+) {
+  qc.setQueryData<ListIssuesCache>(issueKeys.list(wsId), (old) =>
+    old ? removeIssueFromBuckets(old, issueId) : old,
+  );
+
+  for (const [key] of qc.getQueriesData<ListIssuesCache>({
+    queryKey: issueKeys.myAll(wsId),
+  })) {
+    qc.setQueryData<ListIssuesCache>(key, (old) =>
+      old ? removeIssueFromBuckets(old, issueId) : old,
+    );
+  }
+}
+
+export function pruneDeletedIssueFromParentChildrenCaches(
+  qc: QueryClient,
+  wsId: string,
+  issueId: string,
+  metadata: DeletedIssueCacheMetadata,
+) {
+  for (const parentId of metadata.parentIssueIds) {
+    qc.setQueryData<Issue[]>(issueKeys.children(wsId, parentId), (old) =>
+      old?.filter((issue) => issue.id !== issueId),
+    );
+  }
+}
+
+export function invalidateDeletedIssueParentCaches(
+  qc: QueryClient,
+  wsId: string,
+  metadata: DeletedIssueCacheMetadata,
+) {
+  if (metadata.parentIssueIds.length === 0) return;
+  for (const parentId of metadata.parentIssueIds) {
+    qc.invalidateQueries({ queryKey: issueKeys.children(wsId, parentId) });
+  }
+  qc.invalidateQueries({ queryKey: issueKeys.childProgress(wsId) });
+}
+
+export function invalidateDeletedIssueDependentCaches(
+  qc: QueryClient,
+  wsId: string,
+) {
+  qc.invalidateQueries({ queryKey: agentTaskSnapshotKeys.list(wsId) });
+  qc.invalidateQueries({ queryKey: agentActivityKeys.last30d(wsId) });
+  qc.invalidateQueries({ queryKey: agentRunCountsKeys.last30d(wsId) });
+  qc.invalidateQueries({ queryKey: agentTasksKeys.all(wsId) });
+}
+
+export function invalidateIssueScopedCaches(
+  qc: QueryClient,
+  wsId: string,
+  issueId: string,
+) {
+  qc.invalidateQueries({ queryKey: issueKeys.timeline(issueId) });
+  qc.invalidateQueries({ queryKey: issueKeys.reactions(issueId) });
+  qc.invalidateQueries({ queryKey: issueKeys.subscribers(issueId) });
+  qc.invalidateQueries({ queryKey: issueKeys.usage(issueId) });
+  qc.invalidateQueries({ queryKey: issueKeys.attachments(issueId) });
+  qc.invalidateQueries({ queryKey: issueKeys.tasks(issueId) });
+  qc.invalidateQueries({ queryKey: issueKeys.children(wsId, issueId) });
+  qc.invalidateQueries({ queryKey: labelKeys.byIssue(wsId, issueId) });
+}
+
+export function cleanupDeletedIssueCaches(
+  qc: QueryClient,
+  wsId: string,
+  issueId: string,
+  metadata = collectDeletedIssueCacheMetadata(qc, wsId, issueId),
+) {
+  pruneDeletedIssueFromListCaches(qc, wsId, issueId);
+  pruneDeletedIssueFromParentChildrenCaches(qc, wsId, issueId, metadata);
+  invalidateDeletedIssueParentCaches(qc, wsId, metadata);
+
+  qc.removeQueries({ queryKey: issueKeys.detail(wsId, issueId) });
+  qc.removeQueries({ queryKey: issueKeys.timeline(issueId) });
+  qc.removeQueries({ queryKey: issueKeys.reactions(issueId) });
+  qc.removeQueries({ queryKey: issueKeys.subscribers(issueId) });
+  qc.removeQueries({ queryKey: issueKeys.usage(issueId) });
+  qc.removeQueries({ queryKey: issueKeys.attachments(issueId) });
+  qc.removeQueries({ queryKey: issueKeys.tasks(issueId) });
+  qc.removeQueries({ queryKey: issueKeys.children(wsId, issueId) });
+  qc.removeQueries({ queryKey: labelKeys.byIssue(wsId, issueId) });
+
+  qc.invalidateQueries({ queryKey: issueKeys.childProgress(wsId) });
+  qc.invalidateQueries({ queryKey: issueKeys.list(wsId) });
+  qc.invalidateQueries({ queryKey: issueKeys.myAll(wsId) });
+  invalidateDeletedIssueDependentCaches(qc, wsId);
+}

packages/core/issues/mutations.ts

@@ -11,9 +11,17 @@ import {
   findIssueLocation,
   getBucket,
   patchIssueInBuckets,
-  removeIssueFromBuckets,
   setBucket,
 } from "./cache-helpers";
+import {
+  cleanupDeletedIssueCaches,
+  collectDeletedIssueCacheMetadata,
+  invalidateDeletedIssueDependentCaches,
+  invalidateDeletedIssueParentCaches,
+  invalidateIssueScopedCaches,
+  pruneDeletedIssueFromListCaches,
+  pruneDeletedIssueFromParentChildrenCaches,
+} from "./delete-cache";
 import { useWorkspaceId } from "../hooks";
 import { useRecentIssuesStore } from "./stores";
 import type { Issue, IssueReaction, IssueStatus } from "../types";
@@ -23,12 +31,6 @@ import type {
   ListIssuesCache,
 } from "../types";
 import type { TimelineEntry, IssueSubscriber, Reaction } from "../types";
-import {
-  mapAllEntries,
-  filterAllEntries,
-  prependToLatestPage,
-  type TimelineCacheData,
-} from "./timeline-cache";
 
 // ---------------------------------------------------------------------------
 // Shared mutation variable types — used by both mutation hooks and
@@ -115,7 +117,7 @@ export function useCreateIssue() {
       );
       // Surface the just-created issue in cmd+k's Recent list without
       // requiring the user to open it first.
-      useRecentIssuesStore.getState().recordVisit(newIssue.id);
+      useRecentIssuesStore.getState().recordVisit(wsId, newIssue.id);
       // Invalidate parent's children query so sub-issues list updates immediately
       if (newIssue.parent_issue_id) {
         qc.invalidateQueries({ queryKey: issueKeys.children(wsId, newIssue.parent_issue_id) });
@@ -145,11 +147,26 @@ export function useUpdateIssue() {
 
       // Resolve parent_issue_id from the freshest source so we can keep the
       // parent's children cache in sync (used by the parent issue's
-      // sub-issues list).
-      const parentId =
+      // sub-issues list). Falls back to scanning loaded children caches —
+      // when the user navigates straight to a parent's detail page, the
+      // child may live only there, not in detail/list.
+      let parentId: string | null =
         prevDetail?.parent_issue_id ??
         (prevList ? findIssueLocation(prevList, id)?.issue.parent_issue_id : null) ??
         null;
+      if (!parentId) {
+        const childrenCaches = qc.getQueriesData<Issue[]>({
+          queryKey: [...issueKeys.all(wsId), "children"],
+        });
+        for (const [key, data] of childrenCaches) {
+          if (!data?.some((c) => c.id === id)) continue;
+          const candidate = key[key.length - 1];
+          if (typeof candidate === "string") {
+            parentId = candidate;
+            break;
+          }
+        }
+      }
       const prevChildren = parentId
         ? qc.getQueryData<Issue[]>(issueKeys.children(wsId, parentId))
         : undefined;
@@ -183,6 +200,13 @@ export function useUpdateIssue() {
     onSettled: (_data, _err, vars, ctx) => {
       qc.invalidateQueries({ queryKey: issueKeys.detail(wsId, vars.id) });
       qc.invalidateQueries({ queryKey: issueKeys.list(wsId) });
+      // Refresh the issue's attachments cache when the description editor
+      // bound new uploads — the description editor reads `issueAttachments`
+      // to resolve text-preview Eye gates, and unlike other mutations this
+      // payload mutates the attachment join table.
+      if (vars.attachment_ids?.length) {
+        qc.invalidateQueries({ queryKey: issueKeys.attachments(vars.id) });
+      }
       // Invalidate old parent's children cache
       if (ctx?.parentId) {
         qc.invalidateQueries({
@@ -208,24 +232,56 @@ export function useDeleteIssue() {
   return useMutation({
     mutationFn: (id: string) => api.deleteIssue(id),
     onMutate: async (id) => {
-      await qc.cancelQueries({ queryKey: issueKeys.list(wsId) });
-      const prevList = qc.getQueryData<ListIssuesCache>(issueKeys.list(wsId));
-      const deleted = prevList ? findIssueLocation(prevList, id)?.issue : undefined;
-      qc.setQueryData<ListIssuesCache>(issueKeys.list(wsId), (old) =>
-        old ? removeIssueFromBuckets(old, id) : old,
+      await Promise.all([
+        qc.cancelQueries({ queryKey: issueKeys.list(wsId) }),
+        qc.cancelQueries({ queryKey: issueKeys.myAll(wsId) }),
+      ]);
+      const metadata = collectDeletedIssueCacheMetadata(qc, wsId, id);
+      await Promise.all(
+        metadata.parentIssueIds.map((parentId) =>
+          qc.cancelQueries({ queryKey: issueKeys.children(wsId, parentId) }),
+        ),
       );
+      const prevList = qc.getQueryData<ListIssuesCache>(issueKeys.list(wsId));
+      const prevMyLists = qc.getQueriesData<ListIssuesCache>({
+        queryKey: issueKeys.myAll(wsId),
+      });
+      const prevDetail = qc.getQueryData<Issue>(issueKeys.detail(wsId, id));
+      const prevChildren = new Map<string, Issue[] | undefined>();
+      for (const parentId of metadata.parentIssueIds) {
+        prevChildren.set(
+          parentId,
+          qc.getQueryData<Issue[]>(issueKeys.children(wsId, parentId)),
+        );
+      }
+
+      pruneDeletedIssueFromListCaches(qc, wsId, id);
+      pruneDeletedIssueFromParentChildrenCaches(qc, wsId, id, metadata);
       qc.removeQueries({ queryKey: issueKeys.detail(wsId, id) });
-      return { prevList, parentIssueId: deleted?.parent_issue_id };
+      return { id, metadata, prevList, prevMyLists, prevDetail, prevChildren };
     },
     onError: (_err, _id, ctx) => {
       if (ctx?.prevList) qc.setQueryData(issueKeys.list(wsId), ctx.prevList);
+      if (ctx?.prevMyLists) {
+        for (const [key, snapshot] of ctx.prevMyLists) {
+          qc.setQueryData(key, snapshot);
+        }
+      }
+      if (ctx?.prevDetail) {
+        qc.setQueryData(issueKeys.detail(wsId, ctx.id), ctx.prevDetail);
+      }
+      if (ctx?.prevChildren) {
+        for (const [parentId, snapshot] of ctx.prevChildren) {
+          qc.setQueryData(issueKeys.children(wsId, parentId), snapshot);
+        }
+      }
+    },
+    onSuccess: (_data, id, ctx) => {
+      cleanupDeletedIssueCaches(qc, wsId, id, ctx?.metadata);
     },
     onSettled: (_data, _err, _id, ctx) => {
       qc.invalidateQueries({ queryKey: issueKeys.list(wsId) });
-      if (ctx?.parentIssueId) {
-        qc.invalidateQueries({ queryKey: issueKeys.children(wsId, ctx.parentIssueId) });
-        qc.invalidateQueries({ queryKey: issueKeys.childProgress(wsId) });
-      }
+      if (ctx?.metadata) invalidateDeletedIssueParentCaches(qc, wsId, ctx.metadata);
     },
   });
 }
@@ -250,13 +306,46 @@ export function useBatchUpdateIssues() {
         for (const id of ids) next = patchIssueInBuckets(next, id, updates);
         return next;
       });
-      return { prevList };
+
+      // Mirror the optimistic patch into any loaded children cache so
+      // sub-issue rows on a parent's detail page reflect the change too.
+      const idSet = new Set(ids);
+      const childrenCaches = qc.getQueriesData<Issue[]>({
+        queryKey: [...issueKeys.all(wsId), "children"],
+      });
+      const prevChildren = new Map<string, Issue[] | undefined>();
+      const affectedParentIds = new Set<string>();
+      for (const [key, data] of childrenCaches) {
+        if (!data?.some((c) => idSet.has(c.id))) continue;
+        const parentId = key[key.length - 1];
+        if (typeof parentId !== "string") continue;
+        affectedParentIds.add(parentId);
+        prevChildren.set(parentId, data);
+        qc.setQueryData<Issue[]>(issueKeys.children(wsId, parentId), (old) =>
+          old?.map((c) => (idSet.has(c.id) ? { ...c, ...updates } : c)),
+        );
+      }
+
+      return { prevList, prevChildren, affectedParentIds };
     },
     onError: (_err, _vars, ctx) => {
       if (ctx?.prevList) qc.setQueryData(issueKeys.list(wsId), ctx.prevList);
+      if (ctx?.prevChildren) {
+        for (const [parentId, snapshot] of ctx.prevChildren) {
+          qc.setQueryData(issueKeys.children(wsId, parentId), snapshot);
+        }
+      }
     },
-    onSettled: () => {
+    onSettled: (_data, _err, _vars, ctx) => {
       qc.invalidateQueries({ queryKey: issueKeys.list(wsId) });
+      if (ctx?.affectedParentIds && ctx.affectedParentIds.size > 0) {
+        for (const parentId of ctx.affectedParentIds) {
+          qc.invalidateQueries({
+            queryKey: issueKeys.children(wsId, parentId),
+          });
+        }
+        qc.invalidateQueries({ queryKey: issueKeys.childProgress(wsId) });
+      }
     },
   });
 }
@@ -267,33 +356,92 @@ export function useBatchDeleteIssues() {
   return useMutation({
     mutationFn: (ids: string[]) => api.batchDeleteIssues(ids),
     onMutate: async (ids) => {
-      await qc.cancelQueries({ queryKey: issueKeys.list(wsId) });
-      const prevList = qc.getQueryData<ListIssuesCache>(issueKeys.list(wsId));
+      await Promise.all([
+        qc.cancelQueries({ queryKey: issueKeys.list(wsId) }),
+        qc.cancelQueries({ queryKey: issueKeys.myAll(wsId) }),
+      ]);
+      const metadataById = new Map(
+        ids.map((id) => [
+          id,
+          collectDeletedIssueCacheMetadata(qc, wsId, id),
+        ]),
+      );
       const parentIssueIds = new Set<string>();
-      if (prevList) {
-        for (const id of ids) {
-          const loc = findIssueLocation(prevList, id);
-          if (loc?.issue.parent_issue_id) parentIssueIds.add(loc.issue.parent_issue_id);
+      for (const metadata of metadataById.values()) {
+        for (const parentId of metadata.parentIssueIds) {
+          parentIssueIds.add(parentId);
         }
       }
-      qc.setQueryData<ListIssuesCache>(issueKeys.list(wsId), (old) => {
-        if (!old) return old;
-        let next = old;
-        for (const id of ids) next = removeIssueFromBuckets(next, id);
-        return next;
+      await Promise.all(
+        Array.from(parentIssueIds).map((parentId) =>
+          qc.cancelQueries({ queryKey: issueKeys.children(wsId, parentId) }),
+        ),
+      );
+      const prevList = qc.getQueryData<ListIssuesCache>(issueKeys.list(wsId));
+      const prevMyLists = qc.getQueriesData<ListIssuesCache>({
+        queryKey: issueKeys.myAll(wsId),
       });
-      return { prevList, parentIssueIds };
+      const prevChildren = new Map<string, Issue[] | undefined>();
+      for (const parentId of parentIssueIds) {
+        prevChildren.set(
+          parentId,
+          qc.getQueryData<Issue[]>(issueKeys.children(wsId, parentId)),
+        );
+      }
+
+      for (const id of ids) {
+        const metadata = metadataById.get(id);
+        pruneDeletedIssueFromListCaches(qc, wsId, id);
+        if (metadata) {
+          pruneDeletedIssueFromParentChildrenCaches(qc, wsId, id, metadata);
+        }
+      }
+      return { prevList, prevMyLists, prevChildren, parentIssueIds, metadataById };
     },
     onError: (_err, _ids, ctx) => {
       if (ctx?.prevList) qc.setQueryData(issueKeys.list(wsId), ctx.prevList);
+      if (ctx?.prevMyLists) {
+        for (const [key, snapshot] of ctx.prevMyLists) {
+          qc.setQueryData(key, snapshot);
+        }
+      }
+      if (ctx?.prevChildren) {
+        for (const [parentId, snapshot] of ctx.prevChildren) {
+          qc.setQueryData(issueKeys.children(wsId, parentId), snapshot);
+        }
+      }
+    },
+    onSuccess: (data, ids, ctx) => {
+      if (data.deleted === ids.length) {
+        for (const id of ids) {
+          cleanupDeletedIssueCaches(qc, wsId, id, ctx?.metadataById.get(id));
+        }
+        return;
+      }
+
+      if (ctx?.prevList) qc.setQueryData(issueKeys.list(wsId), ctx.prevList);
+      if (ctx?.prevMyLists) {
+        for (const [key, snapshot] of ctx.prevMyLists) {
+          qc.setQueryData(key, snapshot);
+        }
+      }
+      if (ctx?.prevChildren) {
+        for (const [parentId, snapshot] of ctx.prevChildren) {
+          qc.setQueryData(issueKeys.children(wsId, parentId), snapshot);
+        }
+      }
+      for (const id of ids) {
+        invalidateIssueScopedCaches(qc, wsId, id);
+      }
+      qc.invalidateQueries({ queryKey: issueKeys.all(wsId) });
+      invalidateDeletedIssueDependentCaches(qc, wsId);
     },
     onSettled: (_data, _err, _ids, ctx) => {
       qc.invalidateQueries({ queryKey: issueKeys.list(wsId) });
       if (ctx?.parentIssueIds && ctx.parentIssueIds.size > 0) {
-        for (const parentId of ctx.parentIssueIds) {
-          qc.invalidateQueries({ queryKey: issueKeys.children(wsId, parentId) });
-        }
-        qc.invalidateQueries({ queryKey: issueKeys.childProgress(wsId) });
+        invalidateDeletedIssueParentCaches(qc, wsId, {
+          parentIssueIds: Array.from(ctx.parentIssueIds),
+        });
       }
     },
   });
@@ -303,6 +451,8 @@ export function useBatchDeleteIssues() {
 // Comments / Timeline
 // ---------------------------------------------------------------------------
 
+type TimelineCache = TimelineEntry[];
+
 export function useCreateComment(issueId: string) {
   const qc = useQueryClient();
   return useMutation({
@@ -318,11 +468,6 @@ export function useCreateComment(issueId: string) {
       attachmentIds?: string[];
     }) => api.createComment(issueId, content, type, parentId, attachmentIds),
     onSuccess: (comment) => {
-      // Write into every paginated timeline cache that's currently at-latest
-      // (around-mode caches viewing older windows skip silently inside
-      // prependToLatestPage). Both the latest cache and any open around-mode
-      // window that has been scrolled all the way to the live tail get the
-      // optimistic entry; everything else falls back to invalidation.
       const entry: TimelineEntry = {
         type: "comment",
         id: comment.id,
@@ -336,43 +481,41 @@ export function useCreateComment(issueId: string) {
         created_at: comment.created_at,
         updated_at: comment.updated_at,
       };
-      qc.setQueriesData<TimelineCacheData>(
-        { queryKey: ["issues", "timeline", issueId] },
-        (old) => prependToLatestPage(old, entry),
-      );
-    },
-    onSettled: () => {
-      qc.invalidateQueries({ queryKey: issueKeys.timeline(issueId) });
+      // Dedupe by id: the `comment:created` WS event may have already added
+      // this entry from the broadcast path before this onSuccess fires. Skip
+      // the append if the entry is already in the cache.
+      qc.setQueryData<TimelineCache>(issueKeys.timeline(issueId), (old) => {
+        if (!old) return [entry];
+        if (old.some((e) => e.id === entry.id)) return old;
+        return [...old, entry];
+      });
     },
+    // No onSettled invalidate. The `comment:created` WS broadcast keeps
+    // the timeline cache fresh after a successful create, and reconnect
+    // recovery in useIssueTimeline already invalidates if the connection
+    // dropped. Re-fetching on every submit replaces every entry's
+    // reference, which forces every memoized CommentCard subtree to
+    // re-render (visible as a flash across sibling threads during AI
+    // streaming).
   });
 }
 
 export function useUpdateComment(issueId: string) {
   const qc = useQueryClient();
   return useMutation({
-    mutationFn: ({ commentId, content }: { commentId: string; content: string }) =>
-      api.updateComment(commentId, content),
+    mutationFn: ({ commentId, content, attachmentIds }: { commentId: string; content: string; attachmentIds?: string[] }) =>
+      api.updateComment(commentId, content, attachmentIds),
     onMutate: async ({ commentId, content }) => {
-      await qc.cancelQueries({ queryKey: ["issues", "timeline", issueId] });
-      // Snapshot every open timeline cache (latest + any around windows) so
-      // an error rollback restores them all atomically.
-      const prevSnapshots = qc.getQueriesData<TimelineCacheData>({
-        queryKey: ["issues", "timeline", issueId],
-      });
-      qc.setQueriesData<TimelineCacheData>(
-        { queryKey: ["issues", "timeline", issueId] },
-        (old) =>
-          mapAllEntries(old, (e) =>
-            e.id === commentId ? { ...e, content } : e,
-          ),
+      await qc.cancelQueries({ queryKey: issueKeys.timeline(issueId) });
+      const prev = qc.getQueryData<TimelineCache>(issueKeys.timeline(issueId));
+      qc.setQueryData<TimelineCache>(issueKeys.timeline(issueId), (old) =>
+        old?.map((e) => (e.id === commentId ? { ...e, content } : e)),
       );
-      return { prevSnapshots };
+      return { prev };
     },
     onError: (_err, _vars, ctx) => {
-      if (ctx?.prevSnapshots) {
-        for (const [key, prev] of ctx.prevSnapshots) {
-          qc.setQueryData(key, prev);
-        }
+      if (ctx?.prev !== undefined) {
+        qc.setQueryData(issueKeys.timeline(issueId), ctx.prev);
       }
     },
     onSettled: () => {
@@ -386,44 +529,69 @@ export function useDeleteComment(issueId: string) {
   return useMutation({
     mutationFn: (commentId: string) => api.deleteComment(commentId),
     onMutate: async (commentId) => {
-      await qc.cancelQueries({ queryKey: ["issues", "timeline", issueId] });
-      const prevSnapshots = qc.getQueriesData<TimelineCacheData>({
-        queryKey: ["issues", "timeline", issueId],
-      });
+      await qc.cancelQueries({ queryKey: issueKeys.timeline(issueId) });
+      const prev = qc.getQueryData<TimelineCache>(issueKeys.timeline(issueId));
 
-      // Cascade: collect all child comment IDs across every loaded page.
+      // Cascade: collect all descendants of the deleted comment.
       const toRemove = new Set<string>([commentId]);
-      for (const [, data] of prevSnapshots) {
-        if (!data) continue;
+      if (prev) {
         let changed = true;
         while (changed) {
           changed = false;
-          for (const page of data.pages) {
-            for (const e of page.entries) {
-              if (
-                e.parent_id &&
-                toRemove.has(e.parent_id) &&
-                !toRemove.has(e.id)
-              ) {
-                toRemove.add(e.id);
-                changed = true;
-              }
+          for (const e of prev) {
+            if (
+              e.parent_id &&
+              toRemove.has(e.parent_id) &&
+              !toRemove.has(e.id)
+            ) {
+              toRemove.add(e.id);
+              changed = true;
             }
           }
         }
       }
 
-      qc.setQueriesData<TimelineCacheData>(
-        { queryKey: ["issues", "timeline", issueId] },
-        (old) => filterAllEntries(old, (e) => toRemove.has(e.id)),
+      qc.setQueryData<TimelineCache>(issueKeys.timeline(issueId), (old) =>
+        old?.filter((e) => !toRemove.has(e.id)),
       );
-      return { prevSnapshots };
+      return { prev };
     },
     onError: (_err, _id, ctx) => {
-      if (ctx?.prevSnapshots) {
-        for (const [key, prev] of ctx.prevSnapshots) {
-          qc.setQueryData(key, prev);
-        }
+      if (ctx?.prev !== undefined) {
+        qc.setQueryData(issueKeys.timeline(issueId), ctx.prev);
+      }
+    },
+    onSettled: () => {
+      qc.invalidateQueries({ queryKey: issueKeys.timeline(issueId) });
+    },
+  });
+}
+
+export function useResolveComment(issueId: string) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: ({ commentId, resolved }: { commentId: string; resolved: boolean }) =>
+      resolved ? api.resolveComment(commentId) : api.unresolveComment(commentId),
+    onMutate: async ({ commentId, resolved }) => {
+      await qc.cancelQueries({ queryKey: issueKeys.timeline(issueId) });
+      const prev = qc.getQueryData<TimelineCache>(issueKeys.timeline(issueId));
+      qc.setQueryData<TimelineCache>(issueKeys.timeline(issueId), (old) =>
+        old?.map((e) =>
+          e.id === commentId
+            ? {
+                ...e,
+                resolved_at: resolved ? new Date().toISOString() : null,
+                resolved_by_type: resolved ? e.resolved_by_type ?? null : null,
+                resolved_by_id: resolved ? e.resolved_by_id ?? null : null,
+              }
+            : e,
+        ),
+      );
+      return { prev };
+    },
+    onError: (_err, _vars, ctx) => {
+      if (ctx?.prev !== undefined) {
+        qc.setQueryData(issueKeys.timeline(issueId), ctx.prev);
       }
     },
     onSettled: () => {

packages/core/issues/queries.ts

@@ -1,11 +1,9 @@
-import { infiniteQueryOptions, queryOptions } from "@tanstack/react-query";
+import { queryOptions } from "@tanstack/react-query";
 import { api } from "../api";
 import type {
   IssueStatus,
   ListIssuesParams,
   ListIssuesCache,
-  TimelinePage,
-  TimelinePageParam,
 } from "../types";
 import { BOARD_STATUSES } from "./config";
 
@@ -23,19 +21,17 @@ export const issueKeys = {
     [...issueKeys.all(wsId), "children", id] as const,
   childProgress: (wsId: string) =>
     [...issueKeys.all(wsId), "child-progress"] as const,
-  /**
-   * Cursor-paginated timeline cache. Around-mode lookups use a separate cache
-   * (keyed by the anchor id) so an Inbox-jump fetch does not pollute the
-   * default latest-page cache that the regular issue list path consumes.
-   */
-  timeline: (issueId: string, around?: string | null) =>
-    around
-      ? (["issues", "timeline", issueId, "around", around] as const)
-      : (["issues", "timeline", issueId] as const),
+  /** Full-issue timeline (single TanStack Query, no cursor). */
+  timeline: (issueId: string) =>
+    ["issues", "timeline", issueId] as const,
   reactions: (issueId: string) => ["issues", "reactions", issueId] as const,
   subscribers: (issueId: string) =>
     ["issues", "subscribers", issueId] as const,
   usage: (issueId: string) => ["issues", "usage", issueId] as const,
+  /** Issue-level attachments — used by the description editor so its
+   *  inline file-card / image NodeViews can re-sign download URLs at
+   *  click time. */
+  attachments: (issueId: string) => ["issues", "attachments", issueId] as const,
   /** Per-issue task list (issue-detail Execution log section). */
   tasks: (issueId: string) => ["issues", "tasks", issueId] as const,
   /** Prefix-match key for invalidating tasks across all issues — used by
@@ -141,39 +137,16 @@ export function childIssuesOptions(wsId: string, id: string) {
 }
 
 /**
- * Infinite-query options for the cursor-paginated timeline. The first page is
- * either the latest 50 entries (no `around`) or a 50-wide window centered on
- * the given comment/activity id (Inbox jump path). `getNextPageParam` walks
- * older; `getPreviousPageParam` walks newer.
+ * Single-fetch timeline options. The endpoint returns the full ordered set of
+ * comments + activities for an issue (server caps at 2000 as a safety net).
+ * Cursor pagination was removed in #1929 — at observed data sizes (p99 ~30
+ * entries per issue) it added complexity without a UX win and broke reply
+ * threads at page boundaries.
  */
-export function issueTimelineInfiniteOptions(
-  issueId: string,
-  around?: string | null,
-) {
-  return infiniteQueryOptions<
-    TimelinePage,
-    Error,
-    { pages: TimelinePage[]; pageParams: TimelinePageParam[] },
-    readonly unknown[],
-    TimelinePageParam
-  >({
-    queryKey: issueKeys.timeline(issueId, around ?? null),
-    initialPageParam: around
-      ? ({ mode: "around", id: around } as TimelinePageParam)
-      : ({ mode: "latest" } as TimelinePageParam),
-    queryFn: ({ pageParam }) => api.listTimeline(issueId, pageParam),
-    // Walk older: append a page below the current oldest (last entry of the
-    // last loaded page). undefined = no more older entries.
-    getNextPageParam: (lastPage) =>
-      lastPage.has_more_before && lastPage.next_cursor
-        ? ({ mode: "before", cursor: lastPage.next_cursor } as TimelinePageParam)
-        : undefined,
-    // Walk newer: prepend a page above the current newest (first entry of the
-    // first loaded page). undefined = at the latest, no newer to fetch.
-    getPreviousPageParam: (firstPage) =>
-      firstPage.has_more_after && firstPage.prev_cursor
-        ? ({ mode: "after", cursor: firstPage.prev_cursor } as TimelinePageParam)
-        : undefined,
+export function issueTimelineOptions(issueId: string) {
+  return queryOptions({
+    queryKey: issueKeys.timeline(issueId),
+    queryFn: () => api.listTimeline(issueId),
   });
 }
 
@@ -200,3 +173,14 @@ export function issueUsageOptions(issueId: string) {
     queryFn: () => api.getIssueUsage(issueId),
   });
 }
+
+// Backs the description editor's fresh-sign download flow: NodeViews resolve
+// an attachment id by matching the markdown URL against this list. The list
+// is workspace-private metadata and lives on the same cache lifetime as the
+// rest of the issue detail surface.
+export function issueAttachmentsOptions(issueId: string) {
+  return queryOptions({
+    queryKey: issueKeys.attachments(issueId),
+    queryFn: () => api.listAttachments(issueId),
+  });
+}

packages/core/issues/stores/comment-draft-store.ts

@@ -0,0 +1,80 @@
+import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+import { createWorkspaceAwareStorage, registerForWorkspaceRehydration } from "../../platform/workspace-storage";
+import { defaultStorage } from "../../platform/storage";
+
+/**
+ * Per-comment draft persistence — survives:
+ *  - virtualization unmount (the reason this exists: when a TipTap editor
+ *    scrolls out of the Virtuoso viewport, its in-memory state is lost)
+ *  - tab close / accidental Cmd-W
+ *  - reload
+ *
+ * Keys are issue-scoped because createWorkspaceAwareStorage only partitions
+ * by workspace, not by issue. Without issueId in the key, two issues with
+ * thread replies open in adjacent desktop tabs would collide.
+ */
+
+export type CommentDraftKey =
+  | `new:${string}`              // top-level CommentInput, key = `new:${issueId}`
+  | `reply:${string}:${string}`  // ReplyInput inside a thread, key = `reply:${issueId}:${rootCommentId}`
+  | `edit:${string}:${string}`;  // inline edit on existing comment, key = `edit:${issueId}:${commentId}`
+
+interface CommentDraft {
+  content: string;
+  updatedAt: number;
+}
+
+interface CommentDraftStore {
+  drafts: Record<string, CommentDraft>;
+  getDraft: (key: CommentDraftKey) => string | undefined;
+  setDraft: (key: CommentDraftKey, content: string) => void;
+  clearDraft: (key: CommentDraftKey) => void;
+}
+
+// Drafts older than 30 days are dropped on store init. Without TTL the store
+// would accumulate every edit attempt across every issue indefinitely and
+// slowly leak localStorage quota.
+const TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+function pruneStaleDrafts(drafts: Record<string, CommentDraft>): Record<string, CommentDraft> {
+  const cutoff = Date.now() - TTL_MS;
+  const out: Record<string, CommentDraft> = {};
+  for (const [k, v] of Object.entries(drafts)) {
+    if (v.updatedAt >= cutoff && v.content.trim().length > 0) {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export const useCommentDraftStore = create<CommentDraftStore>()(
+  persist(
+    (set, get) => ({
+      drafts: {},
+      getDraft: (key) => get().drafts[key]?.content,
+      setDraft: (key, content) =>
+        set((s) => ({
+          drafts: { ...s.drafts, [key]: { content, updatedAt: Date.now() } },
+        })),
+      clearDraft: (key) =>
+        set((s) => {
+          if (!(key in s.drafts)) return s;
+          const next = { ...s.drafts };
+          delete next[key];
+          return { drafts: next };
+        }),
+    }),
+    {
+      name: "multica_comment_drafts",
+      storage: createJSONStorage(() => createWorkspaceAwareStorage(defaultStorage)),
+      onRehydrateStorage: () => (state) => {
+        if (state) {
+          state.drafts = pruneStaleDrafts(state.drafts);
+        }
+      },
+    },
+  ),
+);
+
+registerForWorkspaceRehydration(() => useCommentDraftStore.persist.rehydrate());

packages/core/issues/stores/index.ts

@@ -1,7 +1,11 @@
 export { useIssueSelectionStore } from "./selection-store";
 export { useCreateModeStore, type CreateMode } from "./create-mode-store";
 export { useIssueDraftStore } from "./draft-store";
-export { useRecentIssuesStore, type RecentIssueEntry } from "./recent-issues-store";
+export {
+  useRecentIssuesStore,
+  selectRecentIssues,
+  type RecentIssueEntry,
+} from "./recent-issues-store";
 export {
   ViewStoreProvider,
   useViewStore,
@@ -9,6 +13,7 @@ export {
 } from "./view-store-context";
 export { useIssuesScopeStore, type IssuesScope } from "./issues-scope-store";
 export { useCommentCollapseStore } from "./comment-collapse-store";
+export { useCommentDraftStore, type CommentDraftKey } from "./comment-draft-store";
 export {
   myIssuesViewStore,
   type MyIssuesViewState,

packages/core/issues/stores/quick-create-store.test.ts

@@ -2,7 +2,9 @@ import { beforeEach, describe, expect, it } from "vitest";
 import { useQuickCreateStore } from "./quick-create-store";
 
 const RESET_STATE = {
-  lastAgentId: null,
+  lastActorType: null,
+  lastActorId: null,
+  lastProjectId: null,
   prompt: "",
   keepOpen: false,
 };
@@ -23,4 +25,30 @@ describe("quick create store", () => {
     clearPrompt();
     expect(useQuickCreateStore.getState().prompt).toBe("");
   });
+
+  it("remembers the last project picked so frequent users skip the picker", () => {
+    const { setLastProjectId } = useQuickCreateStore.getState();
+
+    setLastProjectId("proj-1");
+    expect(useQuickCreateStore.getState().lastProjectId).toBe("proj-1");
+
+    setLastProjectId(null);
+    expect(useQuickCreateStore.getState().lastProjectId).toBeNull();
+  });
+
+  it("remembers the last actor (agent or squad) and clears both fields together", () => {
+    const { setLastActor } = useQuickCreateStore.getState();
+
+    setLastActor("agent", "agent-1");
+    expect(useQuickCreateStore.getState().lastActorType).toBe("agent");
+    expect(useQuickCreateStore.getState().lastActorId).toBe("agent-1");
+
+    setLastActor("squad", "squad-1");
+    expect(useQuickCreateStore.getState().lastActorType).toBe("squad");
+    expect(useQuickCreateStore.getState().lastActorId).toBe("squad-1");
+
+    setLastActor(null, null);
+    expect(useQuickCreateStore.getState().lastActorType).toBeNull();
+    expect(useQuickCreateStore.getState().lastActorId).toBeNull();
+  });
 });

packages/core/issues/stores/quick-create-store.ts

@@ -5,16 +5,28 @@ import { createJSONStorage, persist } from "zustand/middleware";
 import { createWorkspaceAwareStorage, registerForWorkspaceRehydration } from "../../platform/workspace-storage";
 import { defaultStorage } from "../../platform/storage";
 
-// Per-workspace memory of the last agent the user picked in the Quick Create
-// modal. Defaulted to that agent on next open so frequent users skip the
-// picker entirely. Persisted with the workspace-aware StateStorage so
-// switching workspaces shows the right default automatically. Per-user
-// scoping comes for free from localStorage being browser-profile-local —
-// matches how draft-store / issues-scope-store / comment-collapse-store
-// already namespace themselves.
+export type QuickCreateActorType = "agent" | "squad";
+
+// Per-workspace memory of the last actor (agent or squad) and project the
+// user picked in the Quick Create modal. Defaulted to those values on next
+// open so frequent users skip the pickers entirely — without this, anyone
+// targeting a single project ends up retyping "in project A" on every
+// prompt. Persisted with the workspace-aware StateStorage so switching
+// workspaces shows the right default automatically. Per-user scoping comes
+// for free from localStorage being browser-profile-local — matches how
+// draft-store / issues-scope-store / comment-collapse-store already
+// namespace themselves.
+//
+// lastActorType + lastActorId replace the prior `lastAgentId` field once
+// squads became selectable. Users who had a persisted agent preference
+// land back on whatever the picker shows first; a one-time re-pick is
+// preferable to the type-tag ambiguity of overloading a single UUID.
 interface QuickCreateState {
-  lastAgentId: string | null;
-  setLastAgentId: (id: string | null) => void;
+  lastActorType: QuickCreateActorType | null;
+  lastActorId: string | null;
+  setLastActor: (type: QuickCreateActorType | null, id: string | null) => void;
+  lastProjectId: string | null;
+  setLastProjectId: (id: string | null) => void;
   prompt: string;
   setPrompt: (prompt: string) => void;
   clearPrompt: () => void;
@@ -25,8 +37,11 @@ interface QuickCreateState {
 export const useQuickCreateStore = create<QuickCreateState>()(
   persist(
     (set) => ({
-      lastAgentId: null,
-      setLastAgentId: (id) => set({ lastAgentId: id }),
+      lastActorType: null,
+      lastActorId: null,
+      setLastActor: (type, id) => set({ lastActorType: type, lastActorId: id }),
+      lastProjectId: null,
+      setLastProjectId: (id) => set({ lastProjectId: id }),
       prompt: "",
       setPrompt: (prompt) => set({ prompt }),
       clearPrompt: () => set({ prompt: "" }),