fix(desktop): show git-described version in dev instead of stale 0.1.0

Packaged builds are unaffected: scripts/package.mjs already injects the
git tag into electron-builder's extraMetadata.version, so the .app users
download from GitHub Release reports the right version through
app.getVersion() and the auto-updater's latest.yml comparison works
correctly.

Dev mode (`pnpm dev:desktop`) didn't go through that path though, so
app.getVersion() returned the static "0.1.0" from package.json — the
new Settings → Updates panel surfaced this and made it look like the
dev build was ancient. Add a tiny getAppVersion() helper that falls
back to `git describe --tags --always --dirty` only when !app.isPackaged,
and use it for the app-info IPC. No change to packaged behavior; if git
is unavailable for any reason, we silently fall back to app.getVersion().

.env.example

@@ -29,22 +29,6 @@ PORT=8080
 JWT_SECRET=change-me-in-production
 MULTICA_SERVER_URL=ws://localhost:8080/ws
 MULTICA_APP_URL=http://localhost:3000
-# Public URL the API is reachable at from the open internet (no trailing
-# slash). Used to mint absolute webhook URLs for autopilot webhook
-# triggers. Leave unset behind a same-origin reverse proxy or for plain
-# localhost dev — the frontend will compose the URL from
-# window.origin + webhook_path in that case. Headers are intentionally
-# not used to derive this value, to avoid Host / X-Forwarded-Host
-# spoofing when a self-hosted reverse proxy is not hardened.
-MULTICA_PUBLIC_URL=
-# Comma-separated CIDR list of reverse proxies whose X-Forwarded-For /
-# X-Real-IP headers the per-IP webhook rate limiter is allowed to trust.
-# Empty (the default) means "trust no headers" — the limiter uses
-# r.RemoteAddr only, which is the safe shape when the backend is
-# exposed directly. Set this when running behind nginx/Caddy/Cloudflare:
-# e.g. "127.0.0.1/32" for a same-host reverse proxy, or the CDN's
-# announced ranges for cloud deployments.
-MULTICA_TRUSTED_PROXIES=
 MULTICA_DAEMON_CONFIG=
 MULTICA_WORKSPACE_ID=
 MULTICA_DAEMON_ID=
@@ -64,26 +48,11 @@ MULTICA_IMAGE_TAG=latest
 MULTICA_BACKEND_IMAGE=ghcr.io/multica-ai/multica-backend
 MULTICA_WEB_IMAGE=ghcr.io/multica-ai/multica-web
 
-# Email
-# Two delivery options - only one needs to be configured:
-#
-# Option A: Resend (SaaS, recommended for cloud deployments)
-#   Set RESEND_API_KEY to a key from resend.com and verify your sending domain there.
-#   For local/dev use, leave RESEND_API_KEY empty - codes print to stdout. To
-#   accept a fixed local code, also set MULTICA_DEV_VERIFICATION_CODE above
-#   (ignored when APP_ENV=production).
+# Email (Resend)
+# For local/dev use, leave RESEND_API_KEY empty — generated codes print to stdout.
+# For production, set your Resend API key and change RESEND_FROM_EMAIL to a domain verified in your Resend account.
 RESEND_API_KEY=
 RESEND_FROM_EMAIL=noreply@multica.ai
-#
-# Option B: SMTP relay (for self-hosted / on-premise deployments)
-#   Takes priority over Resend when SMTP_HOST is set.
-#   Supports unauthenticated relay (leave SMTP_USERNAME empty) and authenticated SMTP.
-#   Set SMTP_TLS_INSECURE=true only for private CA or self-signed certificates.
-SMTP_HOST=
-SMTP_PORT=25
-SMTP_USERNAME=
-SMTP_PASSWORD=
-SMTP_TLS_INSECURE=false
 
 # Google OAuth
 # The web login page reads GOOGLE_CLIENT_ID from /api/config at runtime, so
@@ -94,9 +63,6 @@ GOOGLE_CLIENT_SECRET=
 GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
 
 # S3 / CloudFront
-# S3_BUCKET — bucket NAME only (e.g. "my-bucket"). Do NOT include the
-# ".s3.<region>.amazonaws.com" suffix; the server builds the public URL
-# from S3_BUCKET + S3_REGION. S3_REGION must match the bucket's real region.
 S3_BUCKET=
 S3_REGION=us-west-2
 CLOUDFRONT_KEY_PAIR_ID=
@@ -119,30 +85,8 @@ LOCAL_UPLOAD_BASE_URL=http://localhost:8080
 # Security
 # Comma-separated list of allowed origins for CORS and WebSocket connections.
 # Defaults to localhost dev origins when unset.
-# Example: CORS_ALLOWED_ORIGINS=https://app.multica.ai,https://staging.multica.ai
-CORS_ALLOWED_ORIGINS=
-
-# ==================== Rate limiting (optional Redis) ====================
-# Per-IP fixed-window rate limiter on the public auth endpoints
-# (/auth/send-code, /auth/verify-code, /auth/google). Backed by Redis.
-# When REDIS_URL is unset the limiter is a no-op (fail-open) and the
-# backend logs "rate limiting disabled: REDIS_URL not configured" at
-# startup. The same REDIS_URL is reused by the realtime fan-out hub,
-# the PAT cache, and the daemon-token cache.
-# REDIS_URL=redis://localhost:6379/0
-# Max requests per IP per minute. Defaults are 5 for send-code/google
-# and 20 for verify-code.
-# RATE_LIMIT_AUTH=5
-# RATE_LIMIT_AUTH_VERIFY=20
-# Comma-separated CIDRs whose X-Forwarded-For the auth limiter is
-# allowed to trust. Empty (default) = never trust XFF, only RemoteAddr.
-# REQUIRED behind a reverse proxy — otherwise every real user shares
-# the proxy IP and the whole deployment lands in one bucket, turning
-# /auth/send-code into 5 req/min site-wide. Use e.g. "127.0.0.1/32,::1/128"
-# for same-host Caddy/Nginx, or the CDN's published ranges for ALB/CF.
-# This is a separate list from MULTICA_TRUSTED_PROXIES above (which
-# governs the autopilot webhook limiter).
-# RATE_LIMIT_TRUSTED_PROXIES=
+# Example: ALLOWED_ORIGINS=https://app.multica.ai,https://staging.multica.ai
+ALLOWED_ORIGINS=
 
 # Realtime metrics endpoint (/health/realtime) access control. See MUL-1342.
 # When unset, the endpoint only serves direct loopback (127.0.0.1 / ::1)
@@ -154,13 +98,6 @@ CORS_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
@@ -192,8 +129,5 @@ 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/ISSUE_TEMPLATE/bug_report.yml

@@ -7,10 +7,10 @@ body:
     id: deployment
     attributes:
       label: Deployment type
-      description: Are you using the Official App (multica.ai) or a self-hosted instance?
+      description: Are you using the hosted version or a self-hosted instance?
       options:
-        - Official App
-        - self-host
+        - multica.ai (hosted)
+        - Self-hosted
     validations:
       required: true
 

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -7,10 +7,10 @@ body:
     id: deployment
     attributes:
       label: Deployment type
-      description: Are you using the Official App (multica.ai) or a self-hosted instance?
+      description: Are you using the hosted version or a self-hosted instance?
       options:
-        - Official App
-        - self-host
+        - multica.ai (hosted)
+        - Self-hosted
     validations:
       required: true
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -40,8 +40,6 @@ Closes #
 - [ ] I have added or updated tests where applicable
 - [ ] If this change affects the UI, I have included before/after screenshots
 - [ ] I have updated relevant documentation to reflect my changes
-- [ ] If I added a new runtime / coding tool / UI tab, I synced the change to **landing copy** (`apps/web/features/landing/i18n/`), **starter-content** (`packages/views/onboarding/utils/starter-content-content-*.ts`), and **relevant docs** (`apps/docs/content/docs/`)
-- [ ] If this PR touches Chinese product copy, I checked it against `apps/docs/content/docs/developers/conventions.zh.mdx` (terminology, mixed-rule for `task` / `issue` / `skill`)
 - [ ] I have considered and documented any risks above
 - [ ] I will address all reviewer comments before requesting merge
 

.github/workflows/ci.yml

@@ -29,17 +29,8 @@ 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'
+      - name: Build, type check, and test
+        run: pnpm exec turbo build typecheck test --filter='!@multica/docs'
 
   backend:
     runs-on: ubuntu-latest

CLAUDE.md

@@ -2,21 +2,6 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Conventions reference
-
-The single source of truth for **code naming, the i18n translation glossary, and the Chinese voice guide** is the docs site:
-
-- **`apps/docs/content/docs/developers/conventions.mdx`** (English)
-- **`apps/docs/content/docs/developers/conventions.zh.mdx`** (Chinese)
-
-Read that page before:
-
-- Writing or editing translations (`packages/views/locales/`)
-- Naming a new route, package, file, DB column, or TS type
-- Writing Chinese product copy (UI strings, error messages, docs)
-
-The legacy `packages/views/locales/glossary.md` is now a stub redirecting to the docs page; do not rely on it.
-
 ## Project Context
 
 Multica is an AI-native task management platform — like Linear, but with AI agents as first-class citizens.
@@ -146,27 +131,10 @@ 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 **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.
+- Unless the user explicitly asks for backwards compatibility, do **not** add compatibility layers, fallback paths, dual-write logic, legacy adapters, or temporary shims.
 - 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

@@ -70,10 +70,10 @@ Opens your browser for OAuth authentication, creates a 90-day personal access to
 ### Token Login
 
 ```bash
-multica login --token <mul_...>
+multica login --token
 ```
 
-Authenticate using a personal access token directly. Useful for headless environments. Pass `--token=` with an empty value to be prompted interactively (so the token never lands in shell history).
+Authenticate by pasting a personal access token directly. Useful for headless environments.
 
 ### Check Status
 
@@ -140,7 +140,6 @@ The daemon auto-detects these AI CLIs on your PATH:
 |-----|---------|-------------|
 | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude` | Anthropic's coding agent |
 | [Codex](https://github.com/openai/codex) | `codex` | OpenAI's coding agent |
-| [GitHub Copilot CLI](https://docs.github.com/en/copilot) | `copilot` | GitHub's coding agent (model routed by your GitHub entitlement) |
 | OpenCode | `opencode` | Open-source coding agent |
 | OpenClaw | `openclaw` | Open-source coding agent |
 | Hermes | `hermes` | Nous Research coding agent |
@@ -175,22 +174,6 @@ Daemon behavior is configured via flags or environment variables:
 | Device name | `--device-name` | `MULTICA_DAEMON_DEVICE_NAME` | hostname |
 | Runtime name | `--runtime-name` | `MULTICA_AGENT_RUNTIME_NAME` | `Local Agent` |
 | Workspaces root | — | `MULTICA_WORKSPACES_ROOT` | `~/multica_workspaces` |
-| GC enabled | — | `MULTICA_GC_ENABLED` | `true` (set `false`/`0` to disable) |
-| GC scan interval | — | `MULTICA_GC_INTERVAL` | `1h` |
-| GC TTL (done/cancelled issues) | — | `MULTICA_GC_TTL` | `24h` |
-| GC orphan TTL (no `.gc_meta.json`) | — | `MULTICA_GC_ORPHAN_TTL` | `72h` |
-| GC artifact TTL (open issues) | — | `MULTICA_GC_ARTIFACT_TTL` | `12h` (set `0` to disable) |
-| GC artifact patterns | — | `MULTICA_GC_ARTIFACT_PATTERNS` | `node_modules,.next,.turbo` |
-
-#### Workspace garbage collection
-
-The daemon periodically scans `MULTICA_WORKSPACES_ROOT` and reclaims disk space in three modes:
-
-- **Full task cleanup** — when an issue's status is `done` or `cancelled` and has been idle for `MULTICA_GC_TTL`, the entire task directory is removed.
-- **Orphan cleanup** — task directories with no `.gc_meta.json` (e.g. left over from a daemon crash) are removed once they exceed `MULTICA_GC_ORPHAN_TTL`.
-- **Artifact-only cleanup** — when a task has been completed for at least `MULTICA_GC_ARTIFACT_TTL` but the issue is still open, regenerable build outputs whose directory basename matches `MULTICA_GC_ARTIFACT_PATTERNS` are removed; the rest of the workdir (source, `.git`, `output/`, `logs/`, `.gc_meta.json`) is preserved so the agent can resume the same workdir on the next task.
-
-Patterns are basename-only — entries containing `/` or `\` are silently dropped — and `.git` subtrees are never descended into. The default list (`node_modules`, `.next`, `.turbo`) is intentionally narrow; extend it per deployment if your repos consistently produce other regenerable directories (for example, `MULTICA_GC_ARTIFACT_PATTERNS=node_modules,.next,.turbo,target,__pycache__`). To disable artifact cleanup entirely, set `MULTICA_GC_ARTIFACT_TTL=0`.
 
 Agent-specific overrides:
 
@@ -202,8 +185,6 @@ Agent-specific overrides:
 | `MULTICA_CODEX_PATH` | Custom path to the `codex` binary |
 | `MULTICA_CODEX_MODEL` | Override the Codex model used |
 | `MULTICA_CODEX_ARGS` | Default extra arguments for Codex runs |
-| `MULTICA_COPILOT_PATH` | Custom path to the `copilot` binary |
-| `MULTICA_COPILOT_MODEL` | Override the Copilot model used (note: GitHub Copilot routes models through your account entitlement, so this may not be honoured) |
 | `MULTICA_OPENCODE_PATH` | Custom path to the `opencode` binary |
 | `MULTICA_OPENCODE_MODEL` | Override the OpenCode model used |
 | `MULTICA_OPENCLAW_PATH` | Custom path to the `openclaw` binary |
@@ -305,12 +286,10 @@ multica workspace members <workspace-id>
 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
 ```
 
-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.
+Available filters: `--status`, `--priority`, `--assignee`, `--project`, `--limit`.
 
 ### Get Issue
 
@@ -323,10 +302,9 @@ multica issue get <id> --output json
 
 ```bash
 multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"
-multica issue create --title "Fix login bug" --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 ```
 
-Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee` / `--assignee-id`, `--parent`, `--project`, `--due-date`. Pass `--assignee-id <uuid>` (mutually exclusive with `--assignee`) when scripting against the IDs returned by `multica workspace members --output json` / `multica agent list --output json`.
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--project`, `--due-date`.
 
 ### Update Issue
 
@@ -338,12 +316,9 @@ multica issue update <id> --title "New title" --priority urgent
 
 ```bash
 multica issue assign <id> --to "Lambda"
-multica issue assign <id> --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 multica issue assign <id> --unassign
 ```
 
-Pass `--to-id <uuid>` to assign by canonical UUID (mutually exclusive with `--to`); useful when names overlap across members and agents.
-
 ### Change Status
 
 ```bash
@@ -394,19 +369,17 @@ 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. 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.
+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.
 
 ## Projects
 
@@ -516,12 +489,9 @@ 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

CLI_INSTALL.md

@@ -140,7 +140,7 @@ multica auth status
 Expected output should show the authenticated user and server URL.
 
 **If login fails:**
-- If no browser is available (headless environment), the user can generate a Personal Access Token at `https://app.multica.ai/settings` and run: `multica login --token <mul_...>` (use `--token=` with an empty value to be prompted interactively).
+- If no browser is available (headless environment), the user can generate a Personal Access Token at `https://app.multica.ai/settings` and run: `multica login --token`
 - If the server URL needs to be customized: `multica config set server_url <url>` before logging in.
 
 ---
@@ -166,12 +166,12 @@ Wait 3 seconds, then verify:
 multica daemon status
 ```
 
-Expected output should show `running` status with detected agents (e.g. `claude`, `codex`, `copilot`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, `cursor-agent`).
+Expected output should show `running` status with detected agents (e.g. `claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, `cursor-agent`).
 
 **If daemon fails to start:**
 - Check logs: `multica daemon logs`
 - If a port conflict occurs, the daemon may already be running under a different profile.
-- If no agents are detected, ensure at least one AI CLI (`claude`, `codex`, `copilot`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`) is installed and on the `$PATH`.
+- If no agents are detected, ensure at least one AI CLI (`claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`) is installed and on the `$PATH`.
 
 ---
 
@@ -185,12 +185,12 @@ multica daemon status
 
 Confirm:
 1. Status is `running`
-2. At least one agent is listed (e.g. `claude`, `codex`, `copilot`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`)
+2. At least one agent is listed (e.g. `claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`)
 3. At least one workspace is being watched
 
 If the agents list is empty, tell the user:
 
-> "The Multica daemon is running but no AI agent CLIs were detected. Please install at least one supported CLI (`claude`, `codex`, `copilot`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`), then restart the daemon with `multica daemon stop && multica daemon start`."
+> "The Multica daemon is running but no AI agent CLIs were detected. Please install at least one supported CLI (`claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`), then restart the daemon with `multica daemon stop && multica daemon start`."
 
 ---
 

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) · [X](https://x.com/MulticaAI) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
+[Website](https://multica.ai) · [Cloud](https://multica.ai/app) · [X](https://x.com/MulticaAI) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
 
 **English | [简体中文](README.zh-CN.md)**
 
@@ -30,32 +30,17 @@ Turn coding agents into real teammates — assign tasks, track progress, compoun
 
 Multica turns coding agents into real teammates. Assign issues to an agent like you'd assign to a colleague — they'll pick up the work, write code, report blockers, and update statuses autonomously.
 
-No more copy-pasting prompts. No more babysitting runs. Your agents show up on the board, participate in conversations, and compound reusable skills over time. Think of it as open-source infrastructure for managed agents — vendor-neutral, self-hosted, and designed for human + AI teams. Works with **Claude Code**, **Codex**, **GitHub Copilot CLI**, **OpenClaw**, **OpenCode**, **Hermes**, **Gemini**, **Pi**, **Cursor Agent**, **Kimi**, and **Kiro CLI**.
-
-For larger teams, Squads add a stable routing layer: assign work to a group led by an agent, and the leader delegates to the right member.
+No more copy-pasting prompts. No more babysitting runs. Your agents show up on the board, participate in conversations, and compound reusable skills over time. Think of it as open-source infrastructure for managed agents — vendor-neutral, self-hosted, and designed for human + AI teams. Works with **Claude Code**, **Codex**, **OpenClaw**, **OpenCode**, **Hermes**, **Gemini**, **Pi**, **Cursor Agent**, **Kimi**, and **Kiro CLI**.
 
 <p align="center">
   <img src="docs/assets/hero-screenshot.png" alt="Multica board view" width="800">
 </p>
 
-## Why "Multica"?
-
-Multica — **Mul**tiplexed **I**nformation and **C**omputing **A**gent.
-
-The name is a nod to Multics, the pioneering operating system of the 1960s that introduced time-sharing — letting multiple users share a single machine as if each had it to themselves. Unix was born as a deliberate simplification of Multics: one user, one task, one elegant philosophy.
-
-We think the same inflection is happening again. For decades, software teams have been single-threaded — one engineer, one task, one context switch at a time. AI agents change that equation. Multica brings time-sharing back, but for an era where the "users" multiplexing the system are both humans and autonomous agents.
-
-In Multica, agents are first-class teammates. They get assigned issues, report progress, raise blockers, and ship code — just like their human colleagues. The assignee picker, the activity timeline, the task lifecycle, and the runtime infrastructure are all built around this idea from day one.
-
-Like Multics before it, the bet is on multiplexing: a small team shouldn't feel small. With the right system, two engineers and a fleet of agents can move like twenty.
-
 ## Features
 
 Multica manages the full agent lifecycle: from task assignment to execution monitoring to skill reuse.
 
 - **Agents as Teammates** — assign to an agent like you'd assign to a colleague. They have profiles, show up on the board, post comments, create issues, and report blockers proactively.
-- **Squads** — group agents (and humans) under a leader agent and assign work to the *squad*. The leader decides who should pick it up, so routing stays stable as the team grows. `@FrontendTeam` instead of `@alice-or-bob-or-carol`.
 - **Autonomous Execution** — set it and forget it. Full task lifecycle management (enqueue, claim, start, complete/fail) with real-time progress streaming via WebSocket.
 - **Reusable Skills** — every solution becomes a reusable skill for the whole team. Deployments, migrations, code reviews — skills compound your team's capabilities over time.
 - **Unified Runtimes** — one dashboard for all your compute. Local daemons and cloud runtimes, auto-detection of available CLIs, real-time monitoring.
@@ -113,7 +98,7 @@ multica setup          # Connect to Multica Cloud, log in, start daemon
 multica setup           # Configure, authenticate, and start the daemon
 ```
 
-The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `copilot`, `openclaw`, `opencode`, `hermes`, `gemini`, `pi`, `cursor-agent`, `kimi`, `kiro-cli`) on your PATH.
+The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `openclaw`, `opencode`, `hermes`, `gemini`, `pi`, `cursor-agent`, `kimi`, `kiro-cli`) on your PATH.
 
 ### 2. Verify your runtime
 
@@ -123,7 +108,7 @@ Open your workspace in the Multica web app. Navigate to **Settings → Runtimes*
 
 ### 3. Create an agent
 
-Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code, Codex, GitHub Copilot CLI, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, or Kiro CLI). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
+Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code, Codex, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, or Kiro CLI). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
 
 ### 4. Assign your first task
 
@@ -131,6 +116,21 @@ Create an issue from the board (or via `multica issue create`), then assign it t
 
 ---
 
+## Multica vs Paperclip
+
+| | Multica | Paperclip |
+|---|---------|-----------|
+| **Focus** | Team AI agent collaboration platform | Solo AI agent company simulator |
+| **User model** | Multi-user teams with roles & permissions | Single board operator |
+| **Agent interaction** | Issues + Chat conversations | Issues + Heartbeat |
+| **Deployment** | Cloud-first | Local-first |
+| **Management depth** | Lightweight (Issues / Projects / Labels) | Heavy governance (Org chart / Approvals / Budgets) |
+| **Extensibility** | Skills system | Skills + Plugin system |
+
+**TL;DR — Multica is built for teams that want to collaborate with AI agents on real projects together.**
+
+---
+
 ## CLI
 
 The `multica` CLI connects your local machine to Multica — authenticate, manage workspaces, and run the agent daemon.
@@ -160,9 +160,10 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
                             │
                      ┌──────┴───────┐
                      │ Agent Daemon │  runs on your machine
-                     └──────────────┘  (Claude Code, Codex, GitHub Copilot CLI,
-                                        OpenCode, OpenClaw, Hermes, Gemini,
-                                        Pi, Cursor Agent, Kimi, Kiro CLI)
+                     └──────────────┘  (Claude Code, Codex, OpenCode,
+                                        OpenClaw, Hermes, Gemini,
+                                        Pi, Cursor Agent, Kimi,
+                                        Kiro CLI)
 ```
 
 | Layer | Stack |
@@ -170,7 +171,7 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
 | Frontend | Next.js 16 (App Router) |
 | Backend | Go (Chi router, sqlc, gorilla/websocket) |
 | Database | PostgreSQL 17 with pgvector |
-| Agent Runtime | Local daemon executing Claude Code, Codex, GitHub Copilot CLI, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, or Kiro CLI |
+| Agent Runtime | Local daemon executing Claude Code, Codex, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, or Kiro CLI |
 
 ## Development
 

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) · [X](https://x.com/MulticaAI) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
+[官网](https://multica.ai) · [云服务](https://multica.ai/app) · [X](https://x.com/MulticaAI) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
 
 **[English](README.md) | 简体中文**
 
@@ -30,32 +30,17 @@
 
 Multica 将编码 Agent 变成真正的队友。像分配给同事一样分配给 Agent——它们会自主接手工作、编写代码、报告阻塞问题、更新状态。
 
-不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**GitHub Copilot CLI**、**OpenClaw**、**OpenCode**、**Hermes**、**Gemini**、**Pi**、**Cursor Agent**、**Kimi** 和 **Kiro CLI**。
-
-面向更大的团队，Squads（小队）提供稳定的路由层：把任务分给由 Agent 带队的小队，由队长判断谁最适合接手。
+不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**OpenClaw**、**OpenCode**、**Hermes**、**Gemini**、**Pi** 和 **Cursor Agent**。
 
 <p align="center">
   <img src="docs/assets/hero-screenshot.png" alt="Multica 看板视图" width="800">
 </p>
 
-## 为什么叫 "Multica"？
-
-Multica——**Mul**tiplexed **I**nformation and **C**omputing **A**gent。
-
-这个名字是在向 20 世纪 60 年代具有开创意义的操作系统 Multics 致意。Multics 首创了分时系统，让多个用户能够共享同一台机器，同时又像各自独占它一样使用。Unix 则是在有意简化 Multics 的基础上诞生的，强调一个用户、一个任务、一种优雅的哲学。
-
-我们认为，类似的转折点正在再次出现。几十年来，软件团队一直处于一种单线程的工作模式，一个工程师处理一个任务，一次只专注于一个上下文。AI agents 改变了这个等式。Multica 将"分时"重新带回这个时代，只不过今天在系统中进行多路复用的"用户"，既包括人类，也包括自主代理。
-
-在 Multica 中，agents 是一级团队成员。它们会被分配 issue，汇报进展，提出阻塞，并交付代码，就像人类同事一样。任务分配、活动时间线、任务生命周期，以及运行时基础设施，Multica 从第一天起就是围绕这一理念构建的。
-
-和当年的 Multics 一样，这一判断建立在"多路复用"之上。一个小团队不该因为人数少就显得能力有限。有了合适的系统，两名工程师加上一组 agents，就能发挥出二十人团队的推进速度。
-
 ## 功能特性
 
 Multica 管理完整的 Agent 生命周期：从任务分配到执行监控再到技能复用。
 
 - **Agent 即队友** — 像分配给同事一样分配给 Agent。它们有个人档案、出现在看板上、发表评论、创建 Issue、主动报告阻塞问题。
-- **Squads（小队）** — 把多个 Agent（以及人类成员）组合成由 leader agent 带队的小队，直接把任务分配给小队本身。Leader 会判断谁最适合接手，团队扩容时路由方式保持不变。用 `@前端组` 代替 `@小张或小李或小王`。
 - **自主执行** — 设置后无需管理。完整的任务生命周期管理（排队、认领、执行、完成/失败），通过 WebSocket 实时推送进度。
 - **可复用技能** — 每个解决方案都成为全团队可复用的技能。部署、数据库迁移、代码审查——技能让团队能力随时间持续增长。
 - **统一运行时** — 一个控制台管理所有算力。本地 daemon 和云端运行时，自动检测可用 CLI，实时监控。
@@ -114,7 +99,7 @@ multica setup          # 连接 Multica Cloud，登录，启动 daemon
 multica setup           # 配置、认证、启动 daemon（一条命令搞定）
 ```
 
-daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`copilot`、`openclaw`、`opencode`、`hermes`、`gemini`、`pi`、`cursor-agent`、`kimi`、`kiro-cli`）。
+daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`openclaw`、`opencode`、`hermes`、`gemini`、`pi`、`cursor-agent`）。
 
 ### 2. 确认运行时已连接
 
@@ -124,7 +109,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 
 ### 3. 创建 Agent
 
-进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、GitHub Copilot CLI、OpenClaw、OpenCode、Hermes、Gemini、Pi、Cursor Agent、Kimi 或 Kiro CLI），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
+进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、OpenClaw、OpenCode、Hermes、Gemini、Pi 或 Cursor Agent），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
 
 ### 4. 分配你的第一个任务
 
@@ -134,6 +119,19 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 
 ---
 
+## Multica vs Paperclip
+
+| | Multica | Paperclip |
+|---|---------|-----------|
+| **定位** | 团队 AI Agent 协作平台 | 个人 AI Agent 公司模拟器 |
+| **用户模型** | 多人团队，角色权限 | 单人 Board Operator |
+| **Agent 交互** | Issue + Chat 对话 | Issue + Heartbeat |
+| **部署** | 云端优先 | 本地优先 |
+| **管理深度** | 轻量（Issue / Project / Labels） | 重度（组织架构 / 审批 / 预算） |
+| **扩展** | Skills 系统 | Skills + 插件系统 |
+
+**简单来说：Multica 专为团队协作打造，让团队和 AI Agent 一起高效完成项目。**
+
 ## 架构
 
 ```
@@ -144,9 +142,9 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
                             │
                      ┌──────┴───────┐
                      │ Agent Daemon │  运行在你的机器上
-                     └──────────────┘  （Claude Code、Codex、GitHub Copilot CLI、
-                                        OpenCode、OpenClaw、Hermes、Gemini、
-                                        Pi、Cursor Agent、Kimi、Kiro CLI）
+                     └──────────────┘  （Claude Code、Codex、OpenCode、
+                                        OpenClaw、Hermes、Gemini、
+                                        Pi、Cursor Agent）
 ```
 
 | 层级 | 技术栈 |
@@ -154,7 +152,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 | 前端 | Next.js 16 (App Router) |
 | 后端 | Go (Chi router, sqlc, gorilla/websocket) |
 | 数据库 | PostgreSQL 17 with pgvector |
-| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、GitHub Copilot CLI、OpenClaw、OpenCode、Hermes、Gemini、Pi、Cursor Agent、Kimi 或 Kiro CLI |
+| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、OpenClaw、OpenCode、Hermes、Gemini、Pi 或 Cursor Agent |
 
 ## 开发
 

SELF_HOSTING.md

@@ -92,7 +92,6 @@ brew install multica-ai/tap/multica
 You also need at least one AI agent CLI installed:
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
 - [Codex](https://github.com/openai/codex) (`codex` on PATH)
-- [GitHub Copilot CLI](https://docs.github.com/en/copilot) (`copilot` on PATH)
 - [OpenClaw](https://github.com/openclaw/openclaw) (`openclaw` on PATH)
 - [OpenCode](https://github.com/anomalyco/opencode) (`opencode` on PATH)
 - [Hermes](https://github.com/NousResearch/hermes) (`hermes` on PATH)

SELF_HOSTING_ADVANCED.md

@@ -25,30 +25,14 @@ These have sensible defaults and only need to be set when tuning a large or cons
 
 ### Email (Required for Authentication)
 
-Multica supports two email backends. `SMTP_HOST` takes priority when set; otherwise `RESEND_API_KEY` is used. With neither configured, verification codes are printed to the server log — copy them from there to log in.
-
-#### Option A: Resend (recommended for cloud deployments)
+Multica uses email-based magic link authentication via [Resend](https://resend.com).
 
 | Variable | Description |
 |----------|-------------|
 | `RESEND_API_KEY` | Your Resend API key |
 | `RESEND_FROM_EMAIL` | Sender email address (default: `noreply@multica.ai`) |
 
-#### Option B: SMTP relay (for self-hosted / on-premise deployments)
-
-Use this option when your deployment cannot reach the public internet or you already have an internal mail relay (e.g. Exchange, Postfix, SendGrid on-prem).
-
-| Variable | Description | Default |
-|----------|-------------|----------|
-| `SMTP_HOST` | SMTP relay hostname (setting this activates SMTP mode) | - |
-| `SMTP_PORT` | SMTP port | `25` |
-| `SMTP_USERNAME` | SMTP username (leave empty for unauthenticated relay) | - |
-| `SMTP_PASSWORD` | SMTP password | - |
-| `SMTP_TLS_INSECURE` | Set `true` to skip TLS certificate verification (self-signed / private CA certs) | `false` |
-
-STARTTLS is used automatically when advertised by the server. Port 465 (SMTPS / implicit TLS) is not currently supported - use ports 25 or 587 with STARTTLS.
-
-> **Note:** If neither Resend nor SMTP is configured, generated verification codes are printed to backend logs — copy them from there to log in. A fixed local testing code (e.g. `888888`) is **opt-in only**: set `MULTICA_DEV_VERIFICATION_CODE=888888` in `.env` and keep `APP_ENV` non-production. The Docker self-host stack pins `APP_ENV=production`, so the shortcut is ignored there. **Never enable a fixed code on a publicly reachable instance.**
+> **Note:** If Resend is not configured, generated verification codes are printed to backend logs. A fixed local testing code is disabled by default; to opt in on a private test instance, set `APP_ENV=development` and `MULTICA_DEV_VERIFICATION_CODE` to a 6-digit value. It is ignored when `APP_ENV=production`.
 
 ### Google OAuth (Optional)
 
@@ -72,15 +56,13 @@ Changes take effect after restarting the backend / compose stack. The web UI rea
 
 ### File Storage (Optional)
 
-For file uploads and attachments, configure S3 and (optionally) CloudFront:
+For file uploads and attachments, configure S3 and CloudFront:
 
 | Variable | Description |
 |----------|-------------|
-| `S3_BUCKET` | Bucket name only (e.g. `my-bucket`). Do **not** include the `.s3.<region>.amazonaws.com` suffix — the server constructs the public URL from `S3_BUCKET` + `S3_REGION` |
-| `S3_REGION` | AWS region (default: `us-west-2`). Must match the bucket's actual region — used for both SDK signing and public URLs |
-| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | Static credentials. When both are unset, the AWS SDK default credential chain is used |
-| `AWS_ENDPOINT_URL` | Custom S3-compatible endpoint (e.g. MinIO, R2, B2). Setting this switches the public URL to path-style |
-| `CLOUDFRONT_DOMAIN` | CloudFront distribution domain — when set, public URLs use this host instead of the S3 host |
+| `S3_BUCKET` | S3 bucket name |
+| `S3_REGION` | AWS region (default: `us-west-2`) |
+| `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
 | `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
 | `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
 
@@ -121,8 +103,6 @@ Agent-specific overrides:
 | `MULTICA_CLAUDE_MODEL` | Override the Claude model used |
 | `MULTICA_CODEX_PATH` | Custom path to the `codex` binary |
 | `MULTICA_CODEX_MODEL` | Override the Codex model used |
-| `MULTICA_COPILOT_PATH` | Custom path to the `copilot` (GitHub Copilot CLI) binary |
-| `MULTICA_COPILOT_MODEL` | Override the Copilot model used (note: GitHub Copilot routes models through your account entitlement, so this may not be honoured) |
 | `MULTICA_OPENCODE_PATH` | Custom path to the `opencode` binary |
 | `MULTICA_OPENCODE_MODEL` | Override the OpenCode model used |
 | `MULTICA_OPENCLAW_PATH` | Custom path to the `openclaw` binary |
@@ -202,47 +182,16 @@ 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/.env.production

@@ -0,0 +1,12 @@
+# Production environment for `pnpm package` / `pnpm build`.
+# electron-vite (Vite under the hood) reads this automatically in
+# production mode and inlines the values into the renderer bundle via
+# import.meta.env.VITE_*. These are public URLs, not secrets.
+
+# Backend API + websocket the desktop app talks to.
+VITE_API_URL=https://api.multica.ai
+VITE_WS_URL=wss://api.multica.ai/ws
+
+# Public web app URL — used to build shareable links like "Copy link to
+# issue" that users paste into Slack / messages. See platform/navigation.tsx.
+VITE_APP_URL=https://multica.ai

apps/desktop/electron-builder.yml

@@ -32,45 +32,6 @@ 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,11 +10,10 @@ export default [
       globals: { ...globals.node },
     },
   },
-  // 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.
+  // 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.
   {
     files: ["src/main/**/*.ts"],
     rules: {
@@ -26,12 +25,6 @@ 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,6 +1,5 @@
 {
   "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, type BrowserWindow } from "electron";
+import { shell } 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,19 +19,6 @@ 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,32 +5,14 @@ import { electronApp, optimizer, is } from "@electron-toolkit/utils";
 import fixPath from "fix-path";
 import { setupAutoUpdater } from "./updater";
 import { setupDaemonManager } from "./daemon-manager";
-import { openExternalSafely, downloadURLSafely } from "./external-url";
+import { openExternalSafely } from "./external-url";
 import { installContextMenu } from "./context-menu";
-import { handleAppShortcut } from "./keyboard-shortcuts";
 import { getAppVersion } from "./app-version";
-import { loadRuntimeConfig } from "./runtime-config-loader";
-import type { RuntimeConfigResult } from "../shared/runtime-config";
 
-// 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",
-);
+// 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");
 
 // macOS/Linux GUI launches inherit a minimal PATH from launchd that omits
 // the user's shell config (~/.zshrc, Homebrew, nvm, ~/.local/bin, etc.).
@@ -55,10 +37,6 @@ if (process.platform !== "win32") {
 const PROTOCOL = "multica";
 
 let mainWindow: BrowserWindow | null = null;
-let runtimeConfigResult: RuntimeConfigResult = {
-  ok: false,
-  error: { message: "Runtime config has not loaded yet" },
-};
 
 // --- Deep link helpers ---------------------------------------------------
 
@@ -94,25 +72,7 @@ function handleDeepLink(url: string): void {
 
 // --- Window creation -----------------------------------------------------
 
-// Tracks the OS-preferred language as last seen by the running process.
-// Updated on each window-focus check so we can emit a `locale:system-changed`
-// event to the renderer when the user changes their OS language without
-// quitting the app — without restart, app.getPreferredSystemLanguages()
-// would still report the boot value forever.
-let lastKnownSystemLocale = "en";
-
-function getSystemLocale(): string {
-  return app.getPreferredSystemLanguages()[0] ?? "en";
-}
-
 function createWindow(): void {
-  // Pass the OS-preferred language to the renderer via additionalArguments
-  // instead of a sync IPC call. process.argv is available to the preload
-  // script before the first network request, so the renderer's i18next
-  // instance can initialize with the right locale on the very first paint.
-  const systemLocale = getSystemLocale();
-  lastKnownSystemLocale = systemLocale;
-
   mainWindow = new BrowserWindow({
     width: 1280,
     height: 800,
@@ -122,40 +82,13 @@ function createWindow(): void {
     trafficLightPosition: { x: 16, y: 13 },
     show: false,
     autoHideMenuBar: true,
-    // 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 }
-      : {}),
+    // 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 } : {}),
     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}`],
     },
   });
 
@@ -173,33 +106,11 @@ function createWindow(): void {
     mainWindow?.show();
   });
 
-  // Detect OS language changes while the app is running. Electron has no
-  // dedicated event for this on any platform, so we poll on focus regain —
-  // catches the common case where users switch System Settings → Language
-  // and bring the app back. The renderer decides whether to act (it ignores
-  // the signal when the user has an explicit Settings choice).
-  mainWindow.on("focus", () => {
-    const current = getSystemLocale();
-    if (current === lastKnownSystemLocale) return;
-    lastKnownSystemLocale = current;
-    mainWindow?.webContents.send("locale:system-changed", current);
-  });
-
   mainWindow.webContents.setWindowOpenHandler((details) => {
     openExternalSafely(details.url);
     return { action: "deny" };
   });
 
-  // Window-level keyboard shortcuts. Calling preventDefault here prevents
-  // both the renderer keydown AND the application menu accelerator, so
-  // anything we own here (reload-block, zoom) is the sole handler for
-  // that combination — no double-fire with the macOS default View menu.
-  mainWindow.webContents.on("before-input-event", (event, input) => {
-    if (handleAppShortcut(input, mainWindow!.webContents)) {
-      event.preventDefault();
-    }
-  });
-
   installContextMenu(mainWindow.webContents);
 
   if (is.dev && process.env["ELECTRON_RENDERER_URL"]) {
@@ -228,14 +139,6 @@ 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 -----------------------------------------------
@@ -268,25 +171,7 @@ if (!gotTheLock) {
     if (deepLinkUrl) handleDeepLink(deepLinkUrl);
   });
 
-  app.whenReady().then(async () => {
-    const viteEnv = import.meta.env as ImportMetaEnv & {
-      readonly VITE_API_URL?: string;
-      readonly VITE_WS_URL?: string;
-      readonly VITE_APP_URL?: string;
-    };
-
-    runtimeConfigResult = await loadRuntimeConfig({
-      isDev: is.dev,
-      // electron-vite exposes VITE_* on import.meta.env for the main process;
-      // keep dev URL overrides on the same source the renderer used before
-      // runtime config moved endpoint resolution into main/preload.
-      env: {
-        apiUrl: viteEnv.VITE_API_URL,
-        wsUrl: viteEnv.VITE_WS_URL,
-        appUrl: viteEnv.VITE_APP_URL,
-      },
-    });
-
+  app.whenReady().then(() => {
     electronApp.setAppUserModelId(
       is.dev ? "ai.multica.desktop.dev" : "ai.multica.desktop",
     );
@@ -295,7 +180,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(BUNDLED_ICON_PATH);
+      const icon = nativeImage.createFromPath(DEV_ICON_PATH);
       if (!icon.isEmpty()) app.dock.setIcon(icon);
     }
 
@@ -312,14 +197,6 @@ 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
@@ -330,13 +207,6 @@ if (!gotTheLock) {
       event.returnValue = { version: getAppVersion(), os };
     });
 
-    // Sync IPC: preload exposes the validated runtime config before renderer
-    // boot. If desktop.json exists but is invalid, renderer receives the
-    // blocking error and must not silently fall back to the cloud defaults.
-    ipcMain.on("runtime-config:get", (event) => {
-      event.returnValue = runtimeConfigResult;
-    });
-
     // IPC: toggle immersive mode — hides the macOS traffic lights so full-screen
     // modals (e.g. create-workspace) can place UI in the top-left corner
     // without fighting the native window controls' hit-test.

apps/desktop/src/main/keyboard-shortcuts.test.ts

@@ -1,152 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { handleAppShortcut, type ShortcutInput } from "./keyboard-shortcuts";
-
-function makeWc(initialLevel = 0) {
-  let level = initialLevel;
-  return {
-    getZoomLevel: vi.fn(() => level),
-    setZoomLevel: vi.fn((next: number) => {
-      level = next;
-    }),
-    currentLevel: () => level,
-  };
-}
-
-function key(
-  k: string,
-  mods: Partial<Pick<ShortcutInput, "control" | "meta">> = {},
-): ShortcutInput {
-  return {
-    type: "keyDown",
-    key: k,
-    control: false,
-    meta: false,
-    ...mods,
-  };
-}
-
-describe("handleAppShortcut — reload blocking", () => {
-  it("swallows Cmd+R on macOS", () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("r", { meta: true }), wc, "darwin")).toBe(true);
-    expect(wc.setZoomLevel).not.toHaveBeenCalled();
-  });
-
-  it("swallows Ctrl+R on Linux/Windows", () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("r", { control: true }), wc, "linux")).toBe(true);
-    expect(handleAppShortcut(key("R", { control: true }), wc, "win32")).toBe(true);
-  });
-
-  it("swallows F5 regardless of modifier", () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("F5"), wc, "darwin")).toBe(true);
-  });
-
-  it("ignores non-keyDown events", () => {
-    const wc = makeWc();
-    expect(
-      handleAppShortcut({ ...key("r", { meta: true }), type: "keyUp" }, wc, "darwin"),
-    ).toBe(false);
-  });
-});
-
-describe("handleAppShortcut — zoom in", () => {
-  it("zooms in on Cmd+= (unshifted)", () => {
-    const wc = makeWc(0);
-    expect(handleAppShortcut(key("=", { meta: true }), wc, "darwin")).toBe(true);
-    expect(wc.currentLevel()).toBe(0.5);
-  });
-
-  it("zooms in on Cmd++ (Shift+=)", () => {
-    const wc = makeWc(0);
-    expect(handleAppShortcut(key("+", { meta: true }), wc, "darwin")).toBe(true);
-    expect(wc.currentLevel()).toBe(0.5);
-  });
-
-  it("zooms in on Ctrl+= on non-mac", () => {
-    const wc = makeWc(0);
-    expect(handleAppShortcut(key("=", { control: true }), wc, "linux")).toBe(true);
-    expect(wc.currentLevel()).toBe(0.5);
-  });
-
-  it("does nothing without Cmd/Ctrl", () => {
-    const wc = makeWc(0);
-    expect(handleAppShortcut(key("="), wc, "darwin")).toBe(false);
-    expect(wc.setZoomLevel).not.toHaveBeenCalled();
-  });
-
-  it("clamps zoom-in at the upper bound", () => {
-    const wc = makeWc(4.5);
-    expect(handleAppShortcut(key("=", { meta: true }), wc, "darwin")).toBe(true);
-    expect(wc.currentLevel()).toBe(4.5);
-  });
-});
-
-describe("handleAppShortcut — zoom out (regression: MUL-2354)", () => {
-  it("zooms out on Cmd+- (unshifted)", () => {
-    const wc = makeWc(1);
-    expect(handleAppShortcut(key("-", { meta: true }), wc, "darwin")).toBe(true);
-    expect(wc.currentLevel()).toBe(0.5);
-  });
-
-  it("zooms out on Cmd+_ (Shift+-)", () => {
-    const wc = makeWc(1);
-    expect(handleAppShortcut(key("_", { meta: true }), wc, "darwin")).toBe(true);
-    expect(wc.currentLevel()).toBe(0.5);
-  });
-
-  it("zooms out on Ctrl+- on non-mac", () => {
-    const wc = makeWc(1);
-    expect(handleAppShortcut(key("-", { control: true }), wc, "win32")).toBe(true);
-    expect(wc.currentLevel()).toBe(0.5);
-  });
-
-  it("undoes a prior Cmd+= so the user can return to 100%", () => {
-    const wc = makeWc(0);
-    handleAppShortcut(key("=", { meta: true }), wc, "darwin");
-    expect(wc.currentLevel()).toBe(0.5);
-    handleAppShortcut(key("-", { meta: true }), wc, "darwin");
-    expect(wc.currentLevel()).toBe(0);
-  });
-
-  it("clamps zoom-out at the lower bound", () => {
-    const wc = makeWc(-3);
-    expect(handleAppShortcut(key("-", { meta: true }), wc, "darwin")).toBe(true);
-    expect(wc.currentLevel()).toBe(-3);
-  });
-
-  it("does nothing without Cmd/Ctrl", () => {
-    const wc = makeWc(1);
-    expect(handleAppShortcut(key("-"), wc, "darwin")).toBe(false);
-    expect(wc.setZoomLevel).not.toHaveBeenCalled();
-  });
-});
-
-describe("handleAppShortcut — reset zoom", () => {
-  it("resets to 0 on Cmd+0", () => {
-    const wc = makeWc(2);
-    expect(handleAppShortcut(key("0", { meta: true }), wc, "darwin")).toBe(true);
-    expect(wc.currentLevel()).toBe(0);
-  });
-
-  it("resets to 0 on Ctrl+0", () => {
-    const wc = makeWc(-1.5);
-    expect(handleAppShortcut(key("0", { control: true }), wc, "linux")).toBe(true);
-    expect(wc.currentLevel()).toBe(0);
-  });
-
-  it("ignores plain 0 without modifier", () => {
-    const wc = makeWc(2);
-    expect(handleAppShortcut(key("0"), wc, "darwin")).toBe(false);
-    expect(wc.setZoomLevel).not.toHaveBeenCalled();
-  });
-});
-
-describe("handleAppShortcut — unrelated keys pass through", () => {
-  it("does not capture plain letters", () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("a", { meta: true }), wc, "darwin")).toBe(false);
-    expect(handleAppShortcut(key("k", { meta: true }), wc, "darwin")).toBe(false);
-  });
-});

apps/desktop/src/main/keyboard-shortcuts.ts

@@ -1,74 +0,0 @@
-import type { WebContents } from "electron";
-
-// Shape of the input subset we read from Electron's `before-input-event`.
-// Modeled as a structural type so the handler is unit-testable without a
-// real Electron Input instance.
-export type ShortcutInput = {
-  type: string;
-  key: string;
-  control: boolean;
-  meta: boolean;
-};
-
-// Subset of WebContents the zoom handler needs. Keeps the test mock tiny.
-export type ZoomTarget = Pick<WebContents, "getZoomLevel" | "setZoomLevel">;
-
-// Match Electron's built-in zoomIn/zoomOut roles (Chromium default of 0.5
-// per step). Clamp to a range that keeps the UI legible — values outside
-// this band turn the workspace into either confetti or a microfiche.
-const ZOOM_STEP = 0.5;
-const ZOOM_MIN = -3;
-const ZOOM_MAX = 4.5;
-
-/**
- * Inspect a `before-input-event` key and apply (or block) the matching
- * window-level shortcut. Returns `true` when the caller should call
- * `event.preventDefault()` — that both swallows the renderer keydown and
- * prevents the application menu accelerator from firing, so we don't
- * double-trigger zoom on macOS where the default menu also binds these
- * keys.
- *
- * Why we don't rely on the menu's `zoomIn` / `zoomOut` roles: on macOS the
- * default `Cmd+-` accelerator does not fire reliably across keyboard
- * layouts (issue MUL-2354 — Cmd+= zooms in but Cmd+- doesn't undo it).
- * Handling the shortcuts here gives identical behavior on every platform
- * and every layout.
- */
-export function handleAppShortcut(
-  input: ShortcutInput,
-  webContents: ZoomTarget,
-  platform: NodeJS.Platform = process.platform,
-): boolean {
-  if (input.type !== "keyDown") return false;
-  const cmdOrCtrl = platform === "darwin" ? input.meta : input.control;
-
-  // Block reload — accidental Cmd+R / Ctrl+R / F5 destroys in-memory state
-  // (tabs, drafts, WS connections) with no URL bar to recover from.
-  if ((cmdOrCtrl && input.key.toLowerCase() === "r") || input.key === "F5") {
-    return true;
-  }
-
-  if (!cmdOrCtrl) return false;
-
-  // Cmd/Ctrl + "=" (unshifted) or "+" (Shift+=) → zoom in.
-  if (input.key === "=" || input.key === "+") {
-    const next = Math.min(webContents.getZoomLevel() + ZOOM_STEP, ZOOM_MAX);
-    webContents.setZoomLevel(next);
-    return true;
-  }
-
-  // Cmd/Ctrl + "-" (unshifted) or "_" (Shift+-) → zoom out.
-  if (input.key === "-" || input.key === "_") {
-    const next = Math.max(webContents.getZoomLevel() - ZOOM_STEP, ZOOM_MIN);
-    webContents.setZoomLevel(next);
-    return true;
-  }
-
-  // Cmd/Ctrl + 0 → reset zoom to 100%.
-  if (input.key === "0") {
-    webContents.setZoomLevel(0);
-    return true;
-  }
-
-  return false;
-}

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

@@ -1,90 +0,0 @@
-import { mkdtemp, writeFile } from "fs/promises";
-import { join } from "path";
-import { tmpdir } from "os";
-import { describe, expect, it } from "vitest";
-import { loadRuntimeConfig } from "./runtime-config-loader";
-
-describe("loadRuntimeConfig", () => {
-  it("uses dev env and ignores desktop.json during electron-vite dev", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "multica-desktop-config-"));
-    const configPath = join(dir, "desktop.json");
-    await writeFile(
-      configPath,
-      JSON.stringify({ schemaVersion: 1, apiUrl: "https://prod.example.com" }),
-    );
-
-    await expect(
-      loadRuntimeConfig({
-        isDev: true,
-        configPath,
-        env: {
-          apiUrl: "http://localhost:8080",
-          wsUrl: "ws://localhost:8080/ws",
-          appUrl: "http://localhost:3000",
-        },
-      }),
-    ).resolves.toEqual({
-      ok: true,
-      config: {
-        schemaVersion: 1,
-        apiUrl: "http://localhost:8080",
-        wsUrl: "ws://localhost:8080/ws",
-        appUrl: "http://localhost:3000",
-      },
-    });
-  });
-
-  it("uses cloud defaults when packaged config is absent", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "multica-desktop-config-"));
-    await expect(
-      loadRuntimeConfig({
-        isDev: false,
-        configPath: join(dir, "missing.json"),
-        env: {},
-      }),
-    ).resolves.toEqual({
-      ok: true,
-      config: {
-        schemaVersion: 1,
-        apiUrl: "https://api.multica.ai",
-        wsUrl: "wss://api.multica.ai/ws",
-        appUrl: "https://multica.ai",
-      },
-    });
-  });
-
-  it("parses a valid packaged desktop.json", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "multica-desktop-config-"));
-    const configPath = join(dir, "desktop.json");
-    await writeFile(
-      configPath,
-      JSON.stringify({ schemaVersion: 1, apiUrl: "https://api.example.com" }),
-    );
-
-    await expect(
-      loadRuntimeConfig({ isDev: false, configPath, env: {} }),
-    ).resolves.toEqual({
-      ok: true,
-      config: {
-        schemaVersion: 1,
-        apiUrl: "https://api.example.com",
-        wsUrl: "wss://api.example.com/ws",
-        appUrl: "https://example.com",
-      },
-    });
-  });
-
-  it("fails closed when packaged desktop.json is invalid", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "multica-desktop-config-"));
-    const configPath = join(dir, "desktop.json");
-    await writeFile(configPath, "{");
-
-    const result = await loadRuntimeConfig({ isDev: false, configPath, env: {} });
-
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.message).toContain(configPath);
-      expect(result.error.message).toContain("Invalid desktop runtime config JSON");
-    }
-  });
-});

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

@@ -1,60 +0,0 @@
-import { app } from "electron";
-import { readFile } from "fs/promises";
-import { join } from "path";
-import {
-  DEFAULT_RUNTIME_CONFIG,
-  parseRuntimeConfig,
-  runtimeConfigFromDevEnv,
-  type RuntimeConfig,
-  type RuntimeConfigEnv,
-  type RuntimeConfigResult,
-} from "../shared/runtime-config";
-
-export async function loadRuntimeConfig(options: {
-  isDev: boolean;
-  env: RuntimeConfigEnv;
-  configPath?: string;
-}): Promise<RuntimeConfigResult> {
-  if (options.isDev) {
-    try {
-      return { ok: true, config: runtimeConfigFromDevEnv(options.env) };
-    } catch (err) {
-      return { ok: false, error: { message: errorMessage(err) } };
-    }
-  }
-
-  const configPath = options.configPath ?? desktopConfigPath();
-  try {
-    const raw = await readFile(configPath, "utf-8");
-    return { ok: true, config: parseRuntimeConfig(raw) };
-  } catch (err) {
-    if (isMissingFileError(err)) {
-      return { ok: true, config: { ...DEFAULT_RUNTIME_CONFIG } };
-    }
-    return {
-      ok: false,
-      error: {
-        message: `Invalid ${configPath}: ${errorMessage(err)}`,
-      },
-    };
-  }
-}
-
-export function desktopConfigPath(): string {
-  return join(app.getPath("home"), ".multica", "desktop.json");
-}
-
-function isMissingFileError(err: unknown): boolean {
-  return Boolean(
-    err &&
-      typeof err === "object" &&
-      "code" in err &&
-      (err as NodeJS.ErrnoException).code === "ENOENT",
-  );
-}
-
-function errorMessage(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
-
-export type { RuntimeConfig, RuntimeConfigResult };

apps/desktop/src/main/updater.ts

@@ -1,10 +1,7 @@
-import { autoUpdater, UpdateDownloadedEvent } from "electron-updater";
+import { autoUpdater } from "electron-updater";
 import { app, BrowserWindow, ipcMain } from "electron";
 
-// Silent background updates: electron-updater downloads on its own as soon
-// as `update-available` fires; we only surface UI when the package is fully
-// downloaded and ready to install on next quit.
-autoUpdater.autoDownload = true;
+autoUpdater.autoDownload = false;
 autoUpdater.autoInstallOnAppQuit = true;
 
 // Windows arm64 ships its own update metadata channel because
@@ -29,39 +26,8 @@ export type ManualUpdateCheckResult =
     }
   | { ok: false; error: string };
 
-// Single-flight guard around checkForUpdates(). With autoDownload=true the
-// startup, periodic, and manual triggers can all kick off downloads, and
-// overlapping calls have caused duplicate download warnings in the past
-// (see electronjs.org/docs/latest/api/auto-updater). Coalesce concurrent
-// callers onto the same in-flight promise.
-let inFlightCheck: Promise<unknown> | null = null;
-function checkForUpdatesOnce(): Promise<unknown> {
-  if (inFlightCheck) return inFlightCheck;
-  const p = autoUpdater
-    .checkForUpdates()
-    .then((result) => {
-      // checkForUpdates resolves as soon as metadata is fetched; the actual
-      // download (when autoDownload=true) is exposed on result.downloadPromise.
-      // Without a handler a download failure becomes an unhandled rejection
-      // in the main process — Node may terminate it on future versions.
-      void (result as { downloadPromise?: Promise<unknown> } | null)?.downloadPromise?.catch(
-        (err) => {
-          console.error("Failed to download update:", err);
-        },
-      );
-      return result;
-    })
-    .finally(() => {
-      if (inFlightCheck === p) inFlightCheck = null;
-    });
-  inFlightCheck = p;
-  return p;
-}
-
 export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): void {
   autoUpdater.on("update-available", (info) => {
-    // Forwarded for renderer-side state tracking only; the notification UI
-    // does not render an "available" affordance with autoDownload=true.
     const win = getMainWindow();
     win?.webContents.send("updater:update-available", {
       version: info.version,
@@ -76,20 +42,15 @@ export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): voi
     });
   });
 
-  autoUpdater.on("update-downloaded", (info: UpdateDownloadedEvent) => {
+  autoUpdater.on("update-downloaded", () => {
     const win = getMainWindow();
-    win?.webContents.send("updater:update-downloaded", {
-      version: info.version,
-      releaseNotes: info.releaseNotes,
-    });
+    win?.webContents.send("updater:update-downloaded");
   });
 
   autoUpdater.on("error", (err) => {
     console.error("Auto-updater error:", err);
   });
 
-  // Retained for IPC back-compat with older renderer bundles. With
-  // autoDownload=true the renderer no longer triggers this path.
   ipcMain.handle("updater:download", () => {
     return autoUpdater.downloadUpdate();
   });
@@ -100,9 +61,7 @@ export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): voi
 
   ipcMain.handle("updater:check", async (): Promise<ManualUpdateCheckResult> => {
     try {
-      const result = (await checkForUpdatesOnce()) as
-        | { updateInfo: { version: string }; isUpdateAvailable?: boolean }
-        | null;
+      const result = await autoUpdater.checkForUpdates();
       const currentVersion = app.getVersion();
       // Trust electron-updater's own decision rather than re-deriving it from
       // a version-string compare. The two diverge for pre-release channels,
@@ -126,7 +85,7 @@ export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): voi
 
   // Initial check shortly after startup so we don't block boot.
   setTimeout(() => {
-    checkForUpdatesOnce().catch((err) => {
+    autoUpdater.checkForUpdates().catch((err) => {
       console.error("Failed to check for updates:", err);
     });
   }, STARTUP_CHECK_DELAY_MS);
@@ -134,7 +93,7 @@ export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): voi
   // Background poll so long-running sessions still pick up new releases
   // without requiring the user to restart the app.
   setInterval(() => {
-    checkForUpdatesOnce().catch((err) => {
+    autoUpdater.checkForUpdates().catch((err) => {
       console.error("Periodic update check failed:", err);
     });
   }, PERIODIC_CHECK_INTERVAL_MS);

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

@@ -1,5 +1,4 @@
 import { ElectronAPI } from "@electron-toolkit/preload";
-import type { RuntimeConfigResult } from "../shared/runtime-config";
 
 interface DesktopAPI {
   /** App version + normalized OS, captured synchronously at preload time. */
@@ -7,21 +6,12 @@ interface DesktopAPI {
     version: string;
     os: "macos" | "windows" | "linux" | "unknown";
   };
-  /** OS-preferred locale (BCP 47) injected by main via additionalArguments. */
-  systemLocale: string;
-  /** Subscribe to OS language changes detected after boot. Returns an unsubscribe function. */
-  onSystemLocaleChanged: (callback: (locale: string) => void) => () => void;
-  /** Validated runtime endpoint config, or a blocking config error. */
-  runtimeConfig: RuntimeConfigResult;
   /** Listen for auth token delivered via deep link. Returns an unsubscribe function. */
   onAuthToken: (callback: (token: string) => void) => () => void;
   /** Listen for invitation IDs delivered via deep link. Returns an unsubscribe function. */
   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. */
@@ -84,9 +74,7 @@ interface DaemonAPI {
 interface UpdaterAPI {
   onUpdateAvailable: (callback: (info: { version: string; releaseNotes?: string }) => void) => () => void;
   onDownloadProgress: (callback: (progress: { percent: number }) => void) => () => void;
-  onUpdateDownloaded: (
-    callback: (info: { version: string; releaseNotes?: string }) => void,
-  ) => () => void;
+  onUpdateDownloaded: (callback: () => void) => () => void;
   downloadUpdate: () => Promise<void>;
   installUpdate: () => Promise<void>;
   checkForUpdates: () => Promise<

apps/desktop/src/preload/index.ts

@@ -1,6 +1,5 @@
 import { contextBridge, ipcRenderer } from "electron";
 import { electronAPI } from "@electron-toolkit/preload";
-import type { RuntimeConfigResult } from "../shared/runtime-config";
 
 // Synchronously fetch app metadata from main at preload time so the renderer
 // can pass it into CoreProvider during the initial render — the alternative
@@ -22,53 +21,12 @@ function fetchAppInfo(): { version: string; os: "macos" | "windows" | "linux" |
   return { version: "unknown", os };
 }
 
-function fetchRuntimeConfig(): RuntimeConfigResult {
-  try {
-    const result = ipcRenderer.sendSync("runtime-config:get") as RuntimeConfigResult | undefined;
-    if (result && typeof result === "object" && "ok" in result) return result;
-  } catch (err) {
-    return {
-      ok: false,
-      error: {
-        message: err instanceof Error ? err.message : String(err),
-      },
-    };
-  }
-  return { ok: false, error: { message: "Runtime config unavailable" } };
-}
-
 const appInfo = fetchAppInfo();
-const runtimeConfig = fetchRuntimeConfig();
-
-// Read the OS-preferred locale that main injected via additionalArguments.
-// Zero IPC, zero blocking — process.argv is populated before preload runs.
-function fetchSystemLocale(): string {
-  const arg = process.argv.find((a) => a.startsWith("--multica-locale="));
-  return arg?.split("=")[1] ?? "en";
-}
-
-const systemLocale = fetchSystemLocale();
 
 const desktopAPI = {
   /** App version + normalized OS. Read once at preload time so the renderer
    *  can use it synchronously when initializing the API client. */
   appInfo,
-  /** OS-preferred locale (BCP 47), passed from main via additionalArguments.
-   *  Used by the renderer's LocaleAdapter as the system-preference signal. */
-  systemLocale,
-  /** Subscribe to OS language changes detected after boot. The renderer
-   *  decides whether to act (no-op when the user has an explicit Settings
-   *  choice). Returns an unsubscribe function. */
-  onSystemLocaleChanged: (callback: (locale: string) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, locale: string) =>
-      callback(locale);
-    ipcRenderer.on("locale:system-changed", handler);
-    return () => {
-      ipcRenderer.removeListener("locale:system-changed", handler);
-    };
-  },
-  /** Validated runtime endpoint config, or a blocking config error. */
-  runtimeConfig,
   /** Listen for auth token delivered via deep link */
   onAuthToken: (callback: (token: string) => void) => {
     const handler = (_event: Electron.IpcRendererEvent, token: string) =>
@@ -89,11 +47,6 @@ 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),
@@ -207,11 +160,8 @@ const updaterAPI = {
     ipcRenderer.on("updater:download-progress", handler);
     return () => ipcRenderer.removeListener("updater:download-progress", handler);
   },
-  onUpdateDownloaded: (
-    callback: (info: { version: string; releaseNotes?: string }) => void,
-  ) => {
-    const handler = (_: unknown, info: { version: string; releaseNotes?: string }) =>
-      callback(info);
+  onUpdateDownloaded: (callback: () => void) => {
+    const handler = () => callback();
     ipcRenderer.on("updater:update-downloaded", handler);
     return () => ipcRenderer.removeListener("updater:update-downloaded", handler);
   },

apps/desktop/src/renderer/src/App.tsx

@@ -1,7 +1,6 @@
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { CoreProvider } from "@multica/core/platform";
-import { pickLocale } from "@multica/core/i18n";
 import { useAuthStore } from "@multica/core/auth";
 import { workspaceKeys, workspaceListOptions } from "@multica/core/workspace/queries";
 import { api } from "@multica/core/api";
@@ -16,8 +15,6 @@ import { UpdateNotification } from "./components/update-notification";
 import { useTabStore } from "./stores/tab-store";
 import { useWindowOverlayStore } from "./stores/window-overlay-store";
 import { useDaemonIPCBridge } from "./platform/daemon-ipc-bridge";
-import { createDesktopLocaleAdapter } from "./platform/i18n-adapter";
-import { RESOURCES } from "@multica/views/locales";
 
 
 function AppContent() {
@@ -33,16 +30,11 @@ function AppContent() {
   // first render.
   const [bootstrapping, setBootstrapping] = useState(false);
 
-  const runtimeConfig = window.desktopAPI.runtimeConfig.ok
-    ? window.desktopAPI.runtimeConfig.config
-    : null;
-
   // Tell the main process which backend URL we talk to, so daemon-manager
   // can pick the matching CLI profile (server_url from ~/.multica config).
   useEffect(() => {
-    if (!runtimeConfig) return;
-    window.daemonAPI.setTargetApiUrl(runtimeConfig.apiUrl);
-  }, [runtimeConfig]);
+    window.daemonAPI.setTargetApiUrl(DAEMON_TARGET_API_URL);
+  }, []);
 
   // Listen for invite IDs delivered via deep link (multica://invite/<id>).
   // We open the overlay regardless of login state — if the user isn't logged
@@ -118,58 +110,21 @@ function AppContent() {
     : undefined;
   useDaemonIPCBridge(activeWsId);
 
-  // Pre-workspace overlay routing for desktop. Mirrors the web entry-point
-  // judgment in callback / login:
-  //   un-onboarded:
-  //     pending invites on email → /invitations overlay
-  //     no invites               → /onboarding overlay
-  //   already onboarded:
-  //     zero workspaces          → /workspaces/new overlay
-  //     ≥1 workspaces            → no overlay, fall through to dashboard
-  //
-  // The "un-onboarded but in workspace" state is now physically impossible
-  // because backend transactions atomically set onboarded_at when a user
-  // joins the `member` table. Anyone with workspaces is by definition
-  // onboarded.
+  // Onboarding and zero-workspace both resolve to an overlay, but
+  // onboarding wins: a user who hasn't completed it gets the onboarding
+  // overlay regardless of how many workspaces already exist.
   useEffect(() => {
-    if (!user || !workspaceListFetched) return undefined;
+    if (!user || !workspaceListFetched) return;
     const { overlay, open } = useWindowOverlayStore.getState();
-    if (overlay) return undefined;
-    if (wsCount > 0) return undefined;
+    if (overlay) return;
     if (!hasOnboarded) {
-      // Look up pending invitations by email. Network blip is non-fatal —
-      // fall through to onboarding so the user isn't stuck on a blank
-      // window. The sidebar's pending-invitations dropdown will surface
-      // missed invites later once they're onboarded.
-      let cancelled = false;
-      void api
-        .listMyInvitations()
-        .then((invites) => {
-          if (cancelled) return;
-          const { overlay: latestOverlay, open: latestOpen } =
-            useWindowOverlayStore.getState();
-          if (latestOverlay) return;
-          if (invites.length > 0) {
-            qc.setQueryData(workspaceKeys.myInvitations(), invites);
-            latestOpen({ type: "invitations" });
-          } else {
-            latestOpen({ type: "onboarding" });
-          }
-        })
-        .catch(() => {
-          if (cancelled) return;
-          const { overlay: latestOverlay, open: latestOpen } =
-            useWindowOverlayStore.getState();
-          if (latestOverlay) return;
-          latestOpen({ type: "onboarding" });
-        });
-      return () => {
-        cancelled = true;
-      };
+      open({ type: "onboarding" });
+      return;
     }
-    open({ type: "new-workspace" });
-    return undefined;
-  }, [user, workspaceListFetched, wsCount, workspaces, hasOnboarded, qc]);
+    if (wsCount === 0) {
+      open({ type: "new-workspace" });
+    }
+  }, [user, workspaceListFetched, wsCount, workspaces, hasOnboarded]);
 
   // Validate persisted tab state against the current user's workspace list,
   // and pick an active workspace if none is set. Runs in useLayoutEffect
@@ -234,21 +189,9 @@ function AppContent() {
   );
 }
 
-function BlockingRuntimeConfigError({ message }: { message: string }) {
-  return (
-    <div className="flex h-screen items-center justify-center bg-background p-8 text-foreground">
-      <div className="max-w-xl rounded-lg border bg-card p-6 shadow-sm">
-        <h1 className="text-lg font-semibold">Desktop configuration error</h1>
-        <p className="mt-3 text-sm text-muted-foreground">
-          Multica Desktop could not load <code>~/.multica/desktop.json</code>. Fix or remove the file and restart the app.
-        </p>
-        <pre className="mt-4 whitespace-pre-wrap rounded-md bg-muted p-3 text-xs text-muted-foreground">
-          {message}
-        </pre>
-      </div>
-    </div>
-  );
-}
+// Backend the daemon should connect to — same URL the renderer talks to.
+const DAEMON_TARGET_API_URL =
+  import.meta.env.VITE_API_URL || "http://localhost:8080";
 
 // On logout, wipe desktop-only in-memory state and stop the daemon so that
 // a subsequent login as a different user never inherits the previous user's
@@ -272,61 +215,22 @@ async function handleDaemonLogout() {
 
 export default function App() {
   const { version, os } = window.desktopAPI.appInfo;
-  const systemLocale = window.desktopAPI.systemLocale;
-  const runtimeConfigResult = window.desktopAPI.runtimeConfig;
   // Stable identity reference so downstream effects (WS reconnect) don't
   // tear down on every parent render.
   const identity = useMemo(
     () => ({ platform: "desktop", version, os }),
     [version, os],
   );
-  // Locale resolution happens once at app boot. Switching language goes
-  // through window.location.reload() to avoid hydration mismatch.
-  const localeAdapter = useMemo(
-    () => createDesktopLocaleAdapter(systemLocale),
-    [systemLocale],
-  );
-  const locale = useMemo(() => pickLocale(localeAdapter), [localeAdapter]);
-  const resources = useMemo(
-    () => ({ [locale]: RESOURCES[locale] }),
-    [locale],
-  );
-
-  // React to OS-level language changes detected by main on focus regain.
-  // Only act when the user is following the system signal (no explicit
-  // Settings choice) — otherwise their preference wins. Cross-device sync
-  // for the explicit-choice case is handled inside CoreProvider.
-  useEffect(() => {
-    return window.desktopAPI.onSystemLocaleChanged((nextSystemLocale) => {
-      if (localeAdapter.getUserChoice()) return;
-      const next = pickLocale({
-        ...localeAdapter,
-        getSystemPreferences: () =>
-          nextSystemLocale ? [nextSystemLocale] : [],
-      });
-      if (next === locale) return;
-      localeAdapter.persist(next);
-      window.location.reload();
-    });
-  }, [localeAdapter, locale]);
-
   return (
     <ThemeProvider>
-      {runtimeConfigResult.ok ? (
-        <CoreProvider
-          apiBaseUrl={runtimeConfigResult.config.apiUrl}
-          wsUrl={runtimeConfigResult.config.wsUrl}
-          onLogout={handleDaemonLogout}
-          identity={identity}
-          locale={locale}
-          resources={resources}
-          localeAdapter={localeAdapter}
-        >
-          <AppContent />
-        </CoreProvider>
-      ) : (
-        <BlockingRuntimeConfigError message={runtimeConfigResult.error.message} />
-      )}
+      <CoreProvider
+        apiBaseUrl={import.meta.env.VITE_API_URL || "http://localhost:8080"}
+        wsUrl={import.meta.env.VITE_WS_URL || "ws://localhost:8080/ws"}
+        onLogout={handleDaemonLogout}
+        identity={identity}
+      >
+        <AppContent />
+      </CoreProvider>
       <Toaster />
       <UpdateNotification />
     </ThemeProvider>

apps/desktop/src/renderer/src/components/daemon-runtime-card.tsx

@@ -4,6 +4,7 @@ import {
   Play,
   Square,
   RotateCw,
+  Server,
   Activity,
   ScrollText,
 } from "lucide-react";
@@ -11,7 +12,15 @@ import { useQuery } from "@tanstack/react-query";
 import { useWorkspaceId } from "@multica/core/hooks";
 import { runtimeListOptions } from "@multica/core/runtimes";
 import { agentTaskSnapshotOptions } from "@multica/core/agents";
+import { cn } from "@multica/ui/lib/utils";
 import { Button } from "@multica/ui/components/ui/button";
+import {
+  Card,
+  CardAction,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@multica/ui/components/ui/card";
 import {
   Dialog,
   DialogContent,
@@ -23,13 +32,24 @@ import {
 import { toast } from "sonner";
 import { DaemonPanel } from "./daemon-panel";
 import type { DaemonStatus } from "../../../shared/daemon-types";
-import { DAEMON_STATE_LABELS } from "../../../shared/daemon-types";
+import {
+  DAEMON_STATE_COLORS,
+  DAEMON_STATE_LABELS,
+  daemonStateDescription,
+  formatUptime,
+} from "../../../shared/daemon-types";
 
 /**
- * Desktop-only controls for the daemon embedded in this Electron app. The
- * shared runtimes page renders this inside the selected local machine header.
+ * Header card on the desktop Runtimes page that surfaces the daemon embedded
+ * in this Electron app. The same daemon process registers N runtimes with the
+ * server (one per detected CLI), which appear in the runtime list below — so
+ * this card is the parent control surface for "what's running on this Mac".
+ *
+ * Why this lives only on desktop: web users don't have an embedded daemon;
+ * they bring their own (CLI-launched or remote VM) and just see runtimes in
+ * the list. The `desktop-runtimes-page` wrapper is the only mount point.
  */
-export function DaemonRuntimeActions() {
+export function DaemonRuntimeCard() {
   const [status, setStatus] = useState<DaemonStatus>({ state: "stopped" });
   const [panelOpen, setPanelOpen] = useState(false);
   const [actionLoading, setActionLoading] = useState(false);
@@ -37,8 +57,14 @@ export function DaemonRuntimeActions() {
 
   const wsId = useWorkspaceId();
   const { data: runtimes = [] } = useQuery(runtimeListOptions(wsId));
+  // Snapshot also includes each agent's latest terminal; the filter below
+  // drops anything that isn't running/dispatched, so terminal rows pass
+  // through harmlessly.
   const { data: snapshot = [] } = useQuery(agentTaskSnapshotOptions(wsId));
 
+  // Set of runtime IDs registered by THIS daemon (one per detected CLI).
+  // Used both to count "how many CLIs am I contributing" and to figure
+  // out which active tasks would be impacted by a Stop.
   const localRuntimeIds = useMemo(() => {
     if (!status.daemonId) return new Set<string>();
     return new Set(
@@ -50,6 +76,10 @@ export function DaemonRuntimeActions() {
 
   const runtimeCount = localRuntimeIds.size;
 
+  // Tasks that are actually doing work on this daemon right now —
+  // running or dispatched. Queued tasks haven't claimed a runtime yet,
+  // so stopping the daemon won't break them (they'll wait for any
+  // available daemon). The number drives the Stop-confirmation dialog.
   const affectedTasks = useMemo(
     () =>
       snapshot.filter(
@@ -78,6 +108,9 @@ export function DaemonRuntimeActions() {
     }
   }, []);
 
+  // The actual stop call, separated from the click handler so we can call
+  // it both from the direct path (no active tasks) and from the confirm
+  // dialog's confirm button.
   const performStop = useCallback(async () => {
     setActionLoading(true);
     const result = await window.daemonAPI.stop();
@@ -86,6 +119,8 @@ export function DaemonRuntimeActions() {
     }
   }, []);
 
+  // Click on the Stop button. If there's nothing running, just stop;
+  // otherwise pop a confirm dialog explaining the blast radius.
   const handleStopClick = useCallback(() => {
     if (affectedTasks.length === 0) {
       void performStop();
@@ -101,6 +136,9 @@ export function DaemonRuntimeActions() {
       toast.error("Failed to restart daemon", { description: result.error });
       return;
     }
+    // Success feedback — the daemon takes a few seconds to come back online,
+    // and the only other UI signal is the state badge flipping briefly. A
+    // toast confirms the click was received and tells the user what to expect.
     toast.success("Restarting daemon", {
       description: "Runtimes will be back online in a few seconds.",
     });
@@ -124,64 +162,106 @@ export function DaemonRuntimeActions() {
 
   return (
     <>
-      <div className="flex flex-wrap items-center justify-end gap-1.5">
-        {isRunning && (
-          <>
-            <Button size="sm" variant="ghost" onClick={() => setPanelOpen(true)}>
-              <ScrollText className="size-3.5 mr-1.5" />
-              View logs
-            </Button>
-            <Button
-              size="sm"
-              variant="outline"
-              onClick={handleRestart}
-              disabled={actionLoading}
-            >
-              <RotateCw className="size-3.5 mr-1.5" />
-              Restart
-            </Button>
-            <Button
-              size="sm"
-              variant="destructive"
-              onClick={handleStopClick}
-              disabled={actionLoading}
-            >
-              <Square className="size-3.5 mr-1.5" />
-              Stop
-            </Button>
-          </>
-        )}
+      <Card size="sm">
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <Server className="size-4 text-muted-foreground" />
+            Local daemon
+            <span className="inline-flex items-center gap-1.5 rounded-md border bg-background px-1.5 py-0.5 text-xs font-normal">
+              <span
+                className={cn(
+                  "size-1.5 rounded-full",
+                  DAEMON_STATE_COLORS[status.state],
+                )}
+              />
+              <span
+                className={cn(
+                  "tabular-nums",
+                  isRunning ? "text-foreground" : "text-muted-foreground",
+                )}
+              >
+                {DAEMON_STATE_LABELS[status.state]}
+              </span>
+              {isRunning && status.uptime && (
+                <span className="text-muted-foreground">
+                  · {formatUptime(status.uptime)}
+                </span>
+              )}
+            </span>
+          </CardTitle>
+          <CardDescription>
+            {daemonStateDescription(status.state, runtimeCount)}
+          </CardDescription>
+          <CardAction className="self-center">
+            <div className="flex items-center gap-1.5">
+              {isRunning && (
+                <>
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    onClick={() => setPanelOpen(true)}
+                  >
+                    <ScrollText className="size-3.5 mr-1.5" />
+                    View logs
+                  </Button>
+                  <Button
+                    size="sm"
+                    variant="outline"
+                    onClick={handleRestart}
+                    disabled={actionLoading}
+                  >
+                    <RotateCw className="size-3.5 mr-1.5" />
+                    Restart
+                  </Button>
+                  <Button
+                    size="sm"
+                    variant="destructive"
+                    onClick={handleStopClick}
+                    disabled={actionLoading}
+                  >
+                    <Square className="size-3.5 mr-1.5" />
+                    Stop
+                  </Button>
+                </>
+              )}
 
-        {isStopped && (
-          <Button size="sm" onClick={handleStart} disabled={actionLoading}>
-            {actionLoading ? (
-              <Activity className="size-3.5 mr-1.5 animate-pulse" />
-            ) : (
-              <Play className="size-3.5 mr-1.5" />
-            )}
-            Start
-          </Button>
-        )}
+              {isStopped && (
+                <Button
+                  size="sm"
+                  onClick={handleStart}
+                  disabled={actionLoading}
+                >
+                  {actionLoading ? (
+                    <Activity className="size-3.5 mr-1.5 animate-pulse" />
+                  ) : (
+                    <Play className="size-3.5 mr-1.5" />
+                  )}
+                  Start
+                </Button>
+              )}
 
-        {isCliMissing && (
-          <Button
-            size="sm"
-            variant="outline"
-            onClick={handleRetryInstall}
-            disabled={actionLoading}
-          >
-            <RotateCw className="size-3.5 mr-1.5" />
-            Retry setup
-          </Button>
-        )}
+              {isCliMissing && (
+                <Button
+                  size="sm"
+                  variant="outline"
+                  onClick={handleRetryInstall}
+                  disabled={actionLoading}
+                >
+                  <RotateCw className="size-3.5 mr-1.5" />
+                  Retry setup
+                </Button>
+              )}
 
-        {(isTransitioning || isInstalling) && (
-          <Button size="sm" variant="outline" disabled>
-            <Activity className="size-3.5 mr-1.5 animate-pulse" />
-            {DAEMON_STATE_LABELS[status.state]}
-          </Button>
-        )}
-      </div>
+              {(isTransitioning || isInstalling) && (
+                <Button size="sm" variant="outline" disabled>
+                  <Activity className="size-3.5 mr-1.5 animate-pulse" />
+                  {DAEMON_STATE_LABELS[status.state]}
+                </Button>
+              )}
+            </div>
+          </CardAction>
+        </CardHeader>
+      </Card>
 
       <DaemonPanel
         open={panelOpen}

apps/desktop/src/renderer/src/components/desktop-runtimes-page.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 import { RuntimesPage } from "@multica/views/runtimes";
-import { DaemonRuntimeActions } from "./daemon-runtime-card";
+import { DaemonRuntimeCard } from "./daemon-runtime-card";
 import type { DaemonStatus } from "../../../shared/daemon-types";
 
 /**
@@ -32,9 +32,7 @@ export function DesktopRuntimesPage() {
 
   return (
     <RuntimesPage
-      localDaemonId={status.daemonId ?? null}
-      localMachineName={status.deviceName ?? null}
-      localMachineActions={<DaemonRuntimeActions />}
+      topSlot={<DaemonRuntimeCard />}
       bootstrapping={bootstrapping}
     />
   );

apps/desktop/src/renderer/src/components/pageview-tracker.test.tsx

@@ -1,243 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from "vitest";
-import { render } from "@testing-library/react";
-
-// vi.hoisted shared state — every store mock reads the same object so each
-// test can mutate it then re-render to drive the tracker.
-const state = vi.hoisted(() => ({
-  user: null as { id: string } | null,
-  overlay: null as { type: string; invitationId?: string } | null,
-  activeWorkspaceSlug: null as string | null,
-  byWorkspace: {} as Record<
-    string,
-    { activeTabId: string; tabs: { id: string; path: string }[] }
-  >,
-  capturePageview: vi.fn<(path?: string) => void>(),
-}));
-
-vi.mock("@multica/core/analytics", () => ({
-  capturePageview: state.capturePageview,
-}));
-
-// Auth store — single selector pattern (`s => s.user`).
-vi.mock("@multica/core/auth", () => {
-  const useAuthStore = (selector: (s: typeof state) => unknown) =>
-    selector(state);
-  return { useAuthStore };
-});
-
-// Window overlay store — same shape.
-vi.mock("@/stores/window-overlay-store", () => {
-  const useWindowOverlayStore = (selector: (s: typeof state) => unknown) =>
-    selector(state);
-  return { useWindowOverlayStore };
-});
-
-// Tab store — selectors read activeWorkspaceSlug + byWorkspace. Also expose
-// getState() for the seed pass and the helpers the tracker imports
-// (useActiveTabIdentity, getActiveTab) so we don't have to re-import them
-// from the real store inside a mocked module.
-vi.mock("@/stores/tab-store", () => {
-  const useTabStore = Object.assign(
-    (selector: (s: typeof state) => unknown) => selector(state),
-    { getState: () => state },
-  );
-  const getActiveTab = (s: typeof state) => {
-    const slug = s.activeWorkspaceSlug;
-    if (!slug) return null;
-    const group = s.byWorkspace[slug];
-    if (!group) return null;
-    return group.tabs.find((t) => t.id === group.activeTabId) ?? null;
-  };
-  const useActiveTabIdentity = () => ({
-    slug: state.activeWorkspaceSlug,
-    tabId: state.activeWorkspaceSlug
-      ? (state.byWorkspace[state.activeWorkspaceSlug]?.activeTabId ?? null)
-      : null,
-  });
-  return { useTabStore, getActiveTab, useActiveTabIdentity };
-});
-
-import { PageviewTracker } from "./pageview-tracker";
-
-function reset() {
-  state.user = { id: "u1" };
-  state.overlay = null;
-  state.activeWorkspaceSlug = null;
-  state.byWorkspace = {};
-  state.capturePageview.mockClear();
-}
-
-beforeEach(() => {
-  reset();
-});
-
-describe("PageviewTracker", () => {
-  it("suppresses pageview when switching to a previously-visible tab on its existing path", () => {
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tA",
-        tabs: [
-          { id: "tA", path: "/acme/issues" },
-          { id: "tB", path: "/acme/inbox" },
-        ],
-      },
-    };
-    state.activeWorkspaceSlug = "acme";
-
-    const { rerender } = render(<PageviewTracker />);
-    // Initial mount on tA — seeded as observed, no pageview because both
-    // tabs were already in the persisted store before the tracker mounted.
-    expect(state.capturePageview).not.toHaveBeenCalled();
-
-    // Switch to tB (already-known tab on its already-known path).
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tB",
-        tabs: [
-          { id: "tA", path: "/acme/issues" },
-          { id: "tB", path: "/acme/inbox" },
-        ],
-      },
-    };
-    rerender(<PageviewTracker />);
-    expect(state.capturePageview).not.toHaveBeenCalled();
-
-    // Switch back to tA — still no pageview.
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tA",
-        tabs: [
-          { id: "tA", path: "/acme/issues" },
-          { id: "tB", path: "/acme/inbox" },
-        ],
-      },
-    };
-    rerender(<PageviewTracker />);
-    expect(state.capturePageview).not.toHaveBeenCalled();
-  });
-
-  it("fires pageview when a new tab is opened (openInNewTab / addTab)", () => {
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tA",
-        tabs: [{ id: "tA", path: "/acme/issues" }],
-      },
-    };
-    state.activeWorkspaceSlug = "acme";
-
-    const { rerender } = render(<PageviewTracker />);
-    state.capturePageview.mockClear();
-
-    // Simulate openInNewTab("/acme/agents") → new tab tC added and activated.
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tC",
-        tabs: [
-          { id: "tA", path: "/acme/issues" },
-          { id: "tC", path: "/acme/agents" },
-        ],
-      },
-    };
-    rerender(<PageviewTracker />);
-
-    expect(state.capturePageview).toHaveBeenCalledTimes(1);
-    expect(state.capturePageview).toHaveBeenCalledWith("/acme/agents");
-  });
-
-  it("fires pageview when switchWorkspace opens a new path in another workspace", () => {
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tA",
-        tabs: [{ id: "tA", path: "/acme/issues" }],
-      },
-    };
-    state.activeWorkspaceSlug = "acme";
-
-    const { rerender } = render(<PageviewTracker />);
-    state.capturePageview.mockClear();
-
-    // Cross-workspace navigation: switchWorkspace("butter", "/butter/inbox")
-    // creates a fresh tab in the destination workspace and makes it active.
-    state.byWorkspace = {
-      acme: { activeTabId: "tA", tabs: [{ id: "tA", path: "/acme/issues" }] },
-      butter: {
-        activeTabId: "tD",
-        tabs: [{ id: "tD", path: "/butter/inbox" }],
-      },
-    };
-    state.activeWorkspaceSlug = "butter";
-    rerender(<PageviewTracker />);
-
-    expect(state.capturePageview).toHaveBeenCalledTimes(1);
-    expect(state.capturePageview).toHaveBeenCalledWith("/butter/inbox");
-  });
-
-  it("fires pageview on intra-tab navigation (path changes for the same tabId)", () => {
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tA",
-        tabs: [{ id: "tA", path: "/acme/issues" }],
-      },
-    };
-    state.activeWorkspaceSlug = "acme";
-
-    const { rerender } = render(<PageviewTracker />);
-    state.capturePageview.mockClear();
-
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tA",
-        tabs: [{ id: "tA", path: "/acme/issues/123" }],
-      },
-    };
-    rerender(<PageviewTracker />);
-
-    expect(state.capturePageview).toHaveBeenCalledTimes(1);
-    expect(state.capturePageview).toHaveBeenCalledWith("/acme/issues/123");
-  });
-
-  it("fires overlay and login pageviews and suppresses re-entry into the same tab afterward", () => {
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tA",
-        tabs: [{ id: "tA", path: "/acme/issues" }],
-      },
-    };
-    state.activeWorkspaceSlug = "acme";
-
-    const { rerender } = render(<PageviewTracker />);
-    state.capturePageview.mockClear();
-
-    // Open onboarding overlay.
-    state.overlay = { type: "onboarding" };
-    rerender(<PageviewTracker />);
-    expect(state.capturePageview).toHaveBeenLastCalledWith("/onboarding");
-
-    // Close overlay back to the tab — the tab is already observed on
-    // /acme/issues so this is a re-activation, no pageview.
-    state.capturePageview.mockClear();
-    state.overlay = null;
-    rerender(<PageviewTracker />);
-    expect(state.capturePageview).not.toHaveBeenCalled();
-
-    // Logout fires /login.
-    state.user = null;
-    rerender(<PageviewTracker />);
-    expect(state.capturePageview).toHaveBeenLastCalledWith("/login");
-  });
-
-  it("suppresses on initial mount when the active tab was restored from persistence", () => {
-    state.byWorkspace = {
-      acme: {
-        activeTabId: "tA",
-        tabs: [{ id: "tA", path: "/acme/issues" }],
-      },
-    };
-    state.activeWorkspaceSlug = "acme";
-
-    render(<PageviewTracker />);
-    // Restored tab — seeded, treated as a re-activation.
-    expect(state.capturePageview).not.toHaveBeenCalled();
-  });
-});
-

apps/desktop/src/renderer/src/components/pageview-tracker.tsx

@@ -1,17 +1,11 @@
-import { useEffect, useRef } from "react";
+import { useEffect } from "react";
 import { capturePageview } from "@multica/core/analytics";
 import { useAuthStore } from "@multica/core/auth";
-import {
-  getActiveTab,
-  useActiveTabIdentity,
-  useTabStore,
-} from "@/stores/tab-store";
+import { useTabStore } from "@/stores/tab-store";
 import { useWindowOverlayStore, type WindowOverlay } from "@/stores/window-overlay-store";
 
 /**
- * Fires a PostHog $pageview whenever the user's visible surface changes,
- * EXCEPT for re-activations of an already-known tab on its already-known
- * path.
+ * Fires a PostHog $pageview whenever the user's visible surface changes.
  *
  * Desktop has three layers that can own the visible page:
  *
@@ -23,18 +17,10 @@ import { useWindowOverlayStore, type WindowOverlay } from "@/stores/window-overl
  *   3. Otherwise → the active tab's path (workspace-scoped, e.g.
  *      `/acme/issues/123`). Kept in sync by `useTabRouterSync`.
  *
- * Tab-switch suppression: re-activating an already-open tab surfaces a
- * previously-visited path under a `(workspace, tabId)` we have already
- * seen — the pageview was emitted when the user originally navigated
- * there, so re-emitting on every switch just inflates PostHog billing
- * without adding signal (real-data audit: desktop tab switches were
- * ~50% of all `$pageview` events).
- *
- * Newly opened tabs (`openInNewTab`, `addTab`) and cross-workspace
- * `switchWorkspace(slug, path)` to a previously-unseen tab still fire,
- * because their key is not in the observed map yet. The map is seeded
- * from the persisted tab store on first render so tabs restored from a
- * previous session don't all re-emit on first activation.
+ * The overlay takes precedence over the tab path because it is visually in
+ * front of the tab system; the logged-out state shadows both because the
+ * shell doesn't render at all yet. This keeps the `$pageview` stream aligned
+ * with what the user actually sees.
  *
  * PostHog's `capture_pageview: true` auto-capture is intentionally off (see
  * `initAnalytics`) so this component owns the event shape, matching the web
@@ -43,75 +29,34 @@ import { useWindowOverlayStore, type WindowOverlay } from "@/stores/window-overl
 export function PageviewTracker() {
   const user = useAuthStore((s) => s.user);
   const overlay = useWindowOverlayStore((s) => s.overlay);
-  const { slug: activeWorkspaceSlug, tabId: activeTabId } = useActiveTabIdentity();
-  const activeTabPath = useTabStore((s) => getActiveTab(s)?.path ?? null);
+  const activeTabPath = useTabStore((s) => {
+    const slug = s.activeWorkspaceSlug;
+    if (!slug) return null;
+    const group = s.byWorkspace[slug];
+    if (!group) return null;
+    return group.tabs.find((t) => t.id === group.activeTabId)?.path ?? null;
+  });
 
-  // (slug:tabId) → last path observed while that tab was visible. Lets us
-  // tell "re-activating a tab on a path we already saw" (suppress) apart
-  // from "newly opened tab" or "intra-tab navigation" (fire). Seeded
-  // synchronously on first render from the persisted tab store so
-  // session-restored tabs don't re-emit on first click.
-  const observedTabsRef = useRef<Map<string, string> | null>(null);
-  if (observedTabsRef.current === null) {
-    const seed = new Map<string, string>();
-    for (const [slug, group] of Object.entries(useTabStore.getState().byWorkspace)) {
-      for (const tab of group.tabs) {
-        seed.set(`${slug}:${tab.id}`, tab.path);
-      }
-    }
-    observedTabsRef.current = seed;
-  }
-  const lastSurfaceRef = useRef<{
-    kind: "login" | "overlay" | "tab" | null;
-    key: string | null;
-    path: string | null;
-  }>({ kind: null, key: null, path: null });
+  const path = resolvePath(user, overlay, activeTabPath);
 
   useEffect(() => {
-    let kind: "login" | "overlay" | "tab";
-    let path: string;
-    let key: string | null = null;
-
-    if (!user) {
-      kind = "login";
-      path = "/login";
-    } else if (overlay) {
-      kind = "overlay";
-      path = overlayPath(overlay);
-    } else if (activeTabPath && activeTabId && activeWorkspaceSlug) {
-      kind = "tab";
-      key = `${activeWorkspaceSlug}:${activeTabId}`;
-      path = activeTabPath;
-    } else {
-      return;
-    }
-
-    const observed = observedTabsRef.current!;
-    const last = lastSurfaceRef.current;
-    const next = { kind, key, path };
-
-    if (kind === "tab" && key !== null) {
-      const knownPath = observed.get(key);
-      const isReactivation =
-        last.key !== key && knownPath !== undefined && knownPath === path;
-      observed.set(key, path);
-      if (isReactivation) {
-        lastSurfaceRef.current = next;
-        return;
-      }
-    }
-
-    const unchanged =
-      last.kind === kind && last.key === key && last.path === path;
-    if (unchanged) return;
-
+    if (!path) return;
     capturePageview(path);
-    lastSurfaceRef.current = next;
-  }, [user, overlay, activeWorkspaceSlug, activeTabId, activeTabPath]);
+  }, [path]);
 
   return null;
 }
 
+function resolvePath(
+  user: unknown,
+  overlay: WindowOverlay | null,
+  activeTabPath: string | null,
+): string | null {
+  if (!user) return "/login";
+  if (overlay) return overlayPath(overlay);
+  return activeTabPath;
+}
+
 function overlayPath(overlay: WindowOverlay): string {
   switch (overlay.type) {
     case "new-workspace":
@@ -120,7 +65,5 @@ function overlayPath(overlay: WindowOverlay): string {
       return "/onboarding";
     case "invite":
       return `/invite/${overlay.invitationId}`;
-    case "invitations":
-      return "/invitations";
   }
 }

apps/desktop/src/renderer/src/components/update-notification.tsx

@@ -1,27 +1,55 @@
-import { useEffect, useState } from "react";
-import { RefreshCw, X } from "lucide-react";
+import { useCallback, useEffect, useState } from "react";
+import { ArrowDownToLine, RefreshCw, X } from "lucide-react";
 
-// Downloads run silently in the background (main process has
-// autoDownload=true). The renderer only renders UI once the package is fully
-// downloaded and waiting for a restart.
 type UpdateState =
   | { status: "idle" }
-  | { status: "ready"; version: string };
+  | { status: "available"; version: string }
+  | { status: "downloading"; percent: number }
+  | { status: "ready" };
 
 export function UpdateNotification() {
   const [state, setState] = useState<UpdateState>({ status: "idle" });
   const [dismissed, setDismissed] = useState(false);
 
   useEffect(() => {
-    const cleanup = window.updater.onUpdateDownloaded((info) => {
-      setState({ status: "ready", version: info.version });
-      setDismissed(false);
-    });
-    return cleanup;
+    const cleanups: (() => void)[] = [];
+
+    cleanups.push(
+      window.updater.onUpdateAvailable((info) => {
+        setState({ status: "available", version: info.version });
+        setDismissed(false);
+      }),
+    );
+
+    cleanups.push(
+      window.updater.onDownloadProgress((progress) => {
+        setState({ status: "downloading", percent: progress.percent });
+      }),
+    );
+
+    cleanups.push(
+      window.updater.onUpdateDownloaded(() => {
+        setState({ status: "ready" });
+      }),
+    );
+
+    return () => cleanups.forEach((fn) => fn());
   }, []);
 
+  const handleDownload = useCallback(() => {
+    // Prevent double-click: immediately transition to downloading state
+    if (state.status !== "available") return;
+    setState({ status: "downloading", percent: 0 });
+    window.updater.downloadUpdate();
+  }, [state.status]);
+
+  const handleInstall = useCallback(() => {
+    window.updater.installUpdate();
+  }, []);
+
+  // Only allow dismiss when update is available (not during download or ready)
   if (state.status === "idle") return null;
-  if (dismissed) return null;
+  if (dismissed && state.status === "available") return null;
 
   return (
     <div className="fixed bottom-4 right-4 z-50 w-80 rounded-lg border border-border bg-background p-4 shadow-lg animate-in slide-in-from-bottom-2 fade-in duration-300">
@@ -32,31 +60,78 @@ export function UpdateNotification() {
         <X className="size-3.5" />
       </button>
 
-      <div className="flex items-start gap-3">
-        <div className="mt-0.5 rounded-md bg-success/10 p-1.5">
-          <RefreshCw className="size-4 text-success" />
-        </div>
-        <div className="flex-1 min-w-0">
-          <p className="text-sm font-medium">Update ready</p>
-          <p className="text-xs text-muted-foreground mt-0.5">
-            v{state.version} will be applied on next launch.
-          </p>
-          <div className="mt-2 flex items-center gap-1.5">
+      {state.status === "available" && (
+        <div className="flex items-start gap-3">
+          <div className="mt-0.5 rounded-md bg-primary/10 p-1.5">
+            <ArrowDownToLine className="size-4 text-primary" />
+          </div>
+          <div className="flex-1 min-w-0">
+            <p className="text-sm font-medium">New version available</p>
+            <p className="text-xs text-muted-foreground mt-0.5">
+              v{state.version} is ready to download
+            </p>
             <button
-              onClick={() => setDismissed(true)}
-              className="inline-flex items-center rounded-md border border-border bg-background px-3 py-1.5 text-xs font-medium text-foreground hover:bg-accent transition-colors"
+              onClick={handleDownload}
+              className="mt-2 inline-flex items-center rounded-md bg-primary px-3 py-1.5 text-xs font-medium text-primary-foreground hover:bg-primary/90 transition-colors"
             >
-              Later
-            </button>
-            <button
-              onClick={() => window.updater.installUpdate()}
-              className="inline-flex items-center rounded-md bg-primary px-3 py-1.5 text-xs font-medium text-primary-foreground hover:bg-primary/90 transition-colors"
-            >
-              Restart now
+              Download update
             </button>
           </div>
         </div>
-      </div>
+      )}
+
+      {state.status === "downloading" && (
+        <div className="flex items-start gap-3">
+          <div className="mt-0.5 rounded-md bg-primary/10 p-1.5">
+            <ArrowDownToLine className="size-4 text-primary animate-pulse" />
+          </div>
+          <div className="flex-1 min-w-0">
+            <p className="text-sm font-medium">Downloading update...</p>
+            <div className="mt-2 h-1.5 w-full rounded-full bg-muted overflow-hidden">
+              <div
+                className="h-full rounded-full bg-primary transition-all duration-300"
+                style={{ width: `${Math.round(state.percent)}%` }}
+              />
+            </div>
+            <p className="text-xs text-muted-foreground mt-1">
+              {Math.round(state.percent)}%
+            </p>
+          </div>
+        </div>
+      )}
+
+      {state.status === "ready" && (
+        <div className="flex items-start gap-3">
+          <div className="mt-0.5 rounded-md bg-success/10 p-1.5">
+            <RefreshCw className="size-4 text-success" />
+          </div>
+          <div className="flex-1 min-w-0">
+            <p className="text-sm font-medium">Update ready</p>
+            <p className="text-xs text-muted-foreground mt-0.5">
+              Restart to apply the update
+            </p>
+            <div className="mt-2 flex items-center gap-1.5">
+              {/* Secondary "See changes" — gives the user a reason to
+                  restart by surfacing what they're about to get. Opens
+                  in the default browser via the shared openExternal
+                  bridge so the URL hits the same allow-list as every
+                  other outbound link. */}
+              <button
+                onClick={() => window.desktopAPI.openExternal("https://multica.ai/changelog")}
+                className="inline-flex items-center rounded-md border border-border bg-background px-3 py-1.5 text-xs font-medium text-foreground hover:bg-accent transition-colors"
+              >
+                See changes
+              </button>
+              <button
+                onClick={handleInstall}
+                className="inline-flex items-center rounded-md bg-primary px-3 py-1.5 text-xs font-medium text-primary-foreground hover:bg-primary/90 transition-colors"
+              >
+                Restart now
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
     </div>
   );
 }

apps/desktop/src/renderer/src/components/updates-settings-tab.tsx

@@ -32,8 +32,7 @@ export function UpdatesSettingsTab() {
       <h2 className="text-lg font-semibold">Updates</h2>
       <p className="text-sm text-muted-foreground mt-1">
         The desktop app checks for new versions automatically once an hour and
-        shortly after launch, downloading them in the background. You&apos;ll
-        be prompted to restart once an update is ready.
+        shortly after launch.
       </p>
 
       <div className="mt-6 divide-y">
@@ -51,8 +50,7 @@ export function UpdatesSettingsTab() {
             <p className="text-sm font-medium">Check for updates</p>
             <p className="text-sm text-muted-foreground mt-0.5">
               Trigger a check now instead of waiting for the next automatic
-              poll. Available updates download in the background and show a
-              restart prompt when ready.
+              poll. Available updates appear as a notification in the corner.
             </p>
             {state.status === "up-to-date" && (
               <p className="text-sm text-muted-foreground mt-2 inline-flex items-center gap-1.5">
@@ -63,8 +61,8 @@ export function UpdatesSettingsTab() {
             {state.status === "available" && (
               <p className="text-sm text-muted-foreground mt-2 inline-flex items-center gap-1.5">
                 <ArrowDownToLine className="size-3.5 text-primary" />
-                v{state.latestVersion} is downloading in the background —
-                you&apos;ll be notified when it&apos;s ready to install.
+                v{state.latestVersion} is available — see the download prompt
+                in the corner.
               </p>
             )}
             {state.status === "error" && (

apps/desktop/src/renderer/src/components/window-overlay.tsx

@@ -1,7 +1,6 @@
 import { useQuery } from "@tanstack/react-query";
 import { NewWorkspacePage } from "@multica/views/workspace/new-workspace-page";
 import { InvitePage } from "@multica/views/invite";
-import { InvitationsPage } from "@multica/views/invitations";
 import { OnboardingFlow } from "@multica/views/onboarding";
 import { useNavigation } from "@multica/views/navigation";
 import { paths } from "@multica/core/paths";
@@ -59,7 +58,6 @@ function WindowOverlayInner() {
           onBack={onBack}
         />
       )}
-      {overlay.type === "invitations" && <InvitationsPage />}
       {overlay.type === "onboarding" && (
         <OnboardingFlow
           onComplete={(ws) => {

apps/desktop/src/renderer/src/pages/attachment-preview-page.tsx

@@ -1,16 +0,0 @@
-import { useParams, useSearchParams } from "react-router-dom";
-import { AttachmentPreviewPage } from "@multica/views/attachments";
-import { ErrorBoundary } from "@multica/ui/components/common/error-boundary";
-
-export function AttachmentPreviewRoute() {
-  const { id } = useParams<{ id: string }>();
-  const [searchParams] = useSearchParams();
-  const filename = searchParams.get("name") ?? undefined;
-
-  if (!id) return null;
-  return (
-    <ErrorBoundary resetKeys={[id]}>
-      <AttachmentPreviewPage attachmentId={id} filename={filename} />
-    </ErrorBoundary>
-  );
-}

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

@@ -1,7 +1,6 @@
 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";
@@ -14,9 +13,5 @@ export function IssueDetailPage() {
   useDocumentTitle(issue ? `${issue.identifier}: ${issue.title}` : "Issue");
 
   if (!id) return null;
-  return (
-    <ErrorBoundary resetKeys={[id]}>
-      <IssueDetail issueId={id} />
-    </ErrorBoundary>
-  );
+  return <IssueDetail issueId={id} />;
 }

apps/desktop/src/renderer/src/pages/login.tsx

@@ -2,23 +2,14 @@ import { LoginPage } from "@multica/views/auth";
 import { DragStrip } from "@multica/views/platform";
 import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
 
-function requireRuntimeAppUrl(): string {
-  const runtimeConfig = window.desktopAPI.runtimeConfig;
-  if (!runtimeConfig.ok) {
-    throw new Error(
-      "Invariant violated: DesktopLoginPage rendered before App accepted runtime config",
-    );
-  }
-  return runtimeConfig.config.appUrl;
-}
+const WEB_URL = import.meta.env.VITE_APP_URL || "http://localhost:3000";
 
 export function DesktopLoginPage() {
-  const webUrl = requireRuntimeAppUrl();
   const handleGoogleLogin = () => {
     // Open web login page in the default browser with platform=desktop flag.
     // The web callback will redirect back via multica:// deep link with the token.
     window.desktopAPI.openExternal(
-      `${webUrl}/login?platform=desktop`,
+      `${WEB_URL}/login?platform=desktop`,
     );
   };
 

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

@@ -1,18 +0,0 @@
-import { useParams } from "react-router-dom";
-import { useQuery } from "@tanstack/react-query";
-import { MemberDetailPage as SharedMemberDetailPage } from "@multica/views/members";
-import { useWorkspaceId } from "@multica/core/hooks";
-import { memberListOptions } from "@multica/core/workspace/queries";
-import { useDocumentTitle } from "@/hooks/use-document-title";
-
-export function MemberDetailPage() {
-  const { id } = useParams<{ id: string }>();
-  const wsId = useWorkspaceId();
-  const { data: members = [] } = useQuery(memberListOptions(wsId));
-  const member = members.find((m) => m.user_id === id) ?? null;
-
-  useDocumentTitle(member?.name ?? "Member");
-
-  if (!id) return null;
-  return <SharedMemberDetailPage userId={id} />;
-}

apps/desktop/src/renderer/src/platform/i18n-adapter.ts

@@ -1,31 +0,0 @@
-import type { LocaleAdapter, SupportedLocale } from "@multica/core/i18n";
-
-const STORAGE_KEY = "multica-locale";
-
-// Desktop adapter:
-//   - User choice: localStorage (set by Settings switcher).
-//   - System preference: locale main injected via additionalArguments
-//     (read from preload, exposed on window.desktopAPI.systemLocale).
-//   - Persist: localStorage. The Settings switcher additionally PATCHes
-//     /api/me when logged in so user.language follows the user across devices.
-export function createDesktopLocaleAdapter(systemLocale: string): LocaleAdapter {
-  return {
-    getUserChoice() {
-      try {
-        return window.localStorage.getItem(STORAGE_KEY);
-      } catch {
-        return null;
-      }
-    },
-    getSystemPreferences() {
-      return systemLocale ? [systemLocale] : [];
-    },
-    persist(locale: SupportedLocale) {
-      try {
-        window.localStorage.setItem(STORAGE_KEY, locale);
-      } catch {
-        // Best-effort
-      }
-    },
-  };
-}

apps/desktop/src/renderer/src/platform/navigation.tsx

@@ -15,15 +15,11 @@ import {
 } from "@/stores/tab-store";
 import { useWindowOverlayStore } from "@/stores/window-overlay-store";
 
-function requireRuntimeAppUrl(scope: string): string {
-  const runtimeConfig = window.desktopAPI.runtimeConfig;
-  if (!runtimeConfig.ok) {
-    throw new Error(
-      `Invariant violated: ${scope} rendered before App accepted runtime config`,
-    );
-  }
-  return runtimeConfig.config.appUrl;
-}
+// Public web app URL — injected at build time via .env.production. In dev
+// (no VITE_APP_URL set) falls back to the local web dev server so "Copy
+// link" in a dev build yields a URL that points at the running dev
+// frontend, not the prod host. Matches the fallback used in pages/login.tsx.
+const APP_URL = import.meta.env.VITE_APP_URL || "http://localhost:3000";
 
 /**
  * Extract the leading workspace slug from a path, or null if the path isn't
@@ -65,13 +61,6 @@ function tryRouteToOverlay(path: string, router?: DataRouter): boolean {
     }
     return true;
   }
-  if (path === "/invitations") {
-    overlay.open({ type: "invitations" });
-    if (router && router.state.location.pathname !== "/") {
-      router.navigate("/", { replace: true });
-    }
-    return true;
-  }
   if (path.startsWith("/invite/")) {
     let id = "";
     try {
@@ -120,7 +109,6 @@ export function DesktopNavigationProvider({
 }: {
   children: React.ReactNode;
 }) {
-  const appUrl = requireRuntimeAppUrl("DesktopNavigationProvider");
   // Primitive-only subscriptions so this component doesn't re-render on
   // unrelated store updates (e.g. an inactive tab's router tick). We
   // resolve the active router here only to subscribe once per tab switch.
@@ -191,9 +179,9 @@ export function DesktopNavigationProvider({
         const tabId = store.openTab(path, title ?? path, icon);
         if (tabId) store.setActiveTab(tabId);
       },
-      getShareableUrl: (path: string) => `${appUrl}${path}`,
+      getShareableUrl: (path: string) => `${APP_URL}${path}`,
     }),
-    [appUrl, location],
+    [location],
   );
 
   return <NavigationProvider value={adapter}>{children}</NavigationProvider>;
@@ -216,7 +204,6 @@ export function TabNavigationProvider({
   router: DataRouter;
   children: React.ReactNode;
 }) {
-  const appUrl = requireRuntimeAppUrl("TabNavigationProvider");
   const [location, setLocation] = useState(router.state.location);
 
   useEffect(() => {
@@ -252,9 +239,9 @@ export function TabNavigationProvider({
         const tabId = store.openTab(path, title ?? path, icon);
         if (tabId) store.setActiveTab(tabId);
       },
-      getShareableUrl: (path: string) => `${appUrl}${path}`,
+      getShareableUrl: (path: string) => `${APP_URL}${path}`,
     }),
-    [appUrl, router, location],
+    [router, location],
   );
 
   return <NavigationProvider value={adapter}>{children}</NavigationProvider>;

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

@@ -11,21 +11,16 @@ import { ProjectDetailPage } from "./pages/project-detail-page";
 import { AutopilotDetailPage } from "./pages/autopilot-detail-page";
 import { SkillDetailPage } from "./pages/skill-detail-page";
 import { AgentDetailPage } from "./pages/agent-detail-page";
-import { MemberDetailPage } from "./pages/member-detail-page";
 import { RuntimeDetailPage } from "./pages/runtime-detail-page";
-import { AttachmentPreviewRoute } from "./pages/attachment-preview-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";
@@ -88,15 +83,7 @@ export const appRoutes: RouteObject[] = [
         element: <WorkspaceRouteLayout />,
         children: [
           { index: true, element: <Navigate to="issues" replace /> },
-          {
-            path: "issues",
-            element: (
-              <ErrorBoundary>
-                <IssuesPage />
-              </ErrorBoundary>
-            ),
-            handle: { title: "Issues" },
-          },
+          { path: "issues", element: <IssuesPage />, handle: { title: "Issues" } },
           {
             path: "issues/:id",
             element: <IssueDetailPage />,
@@ -149,28 +136,7 @@ export const appRoutes: RouteObject[] = [
             element: <AgentDetailPage />,
             handle: { title: "Agent" },
           },
-          {
-            path: "members/:id",
-            element: <MemberDetailPage />,
-            handle: { title: "Member" },
-          },
-          { path: "squads", element: <SquadsPage />, handle: { title: "Squads" } },
-          {
-            path: "squads/:id",
-            element: <SquadDetailPageView />,
-            handle: { title: "Squad" },
-          },
           { path: "inbox", element: <InboxPage />, handle: { title: "Inbox" } },
-          {
-            path: "attachments/:id/preview",
-            element: <AttachmentPreviewRoute />,
-            handle: { title: "Attachment" },
-          },
-          {
-            path: "usage",
-            element: <DashboardPage />,
-            handle: { title: "Usage" },
-          },
           {
             path: "settings",
             element: (

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

@@ -180,61 +180,6 @@ 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,10 +350,7 @@ export const useTabStore = create<TabStore>()(
         const { slug, group, index } = hit;
 
         const closing = group.tabs[index];
-        const disposeClosingRouter = () => {
-          // Let React unmount the tab's RouterProvider before disposing it.
-          window.setTimeout(() => closing.router.dispose(), 0);
-        };
+        closing.router.dispose();
 
         if (group.tabs.length === 1) {
           // Last tab in this workspace — reseed a default so the workspace
@@ -366,7 +363,6 @@ export const useTabStore = create<TabStore>()(
               [slug]: { tabs: [fresh], activeTabId: fresh.id },
             },
           });
-          disposeClosingRouter();
           return;
         }
 
@@ -382,7 +378,6 @@ export const useTabStore = create<TabStore>()(
             [slug]: { tabs: nextTabs, activeTabId: nextActiveTabId },
           },
         });
-        disposeClosingRouter();
       },
 
       setActiveTab(tabId) {
@@ -407,13 +402,6 @@ 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({
@@ -430,12 +418,6 @@ 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/renderer/src/stores/window-overlay-store.ts

@@ -15,7 +15,6 @@ import { create } from "zustand";
 export type WindowOverlay =
   | { type: "new-workspace" }
   | { type: "invite"; invitationId: string }
-  | { type: "invitations" }
   | { type: "onboarding" };
 
 interface WindowOverlayStore {

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

@@ -1,151 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  DEFAULT_RUNTIME_CONFIG,
-  deriveWsUrl,
-  parseRuntimeConfig,
-  runtimeConfigFromDevEnv,
-} from "./runtime-config";
-
-describe("runtime config", () => {
-  it("uses cloud defaults without a desktop.json file", () => {
-    expect(DEFAULT_RUNTIME_CONFIG).toEqual({
-      schemaVersion: 1,
-      apiUrl: "https://api.multica.ai",
-      wsUrl: "wss://api.multica.ai/ws",
-      appUrl: "https://multica.ai",
-    });
-  });
-
-  it("derives https/wss compatible URLs from apiUrl", () => {
-    expect(
-      parseRuntimeConfig(
-        JSON.stringify({
-          schemaVersion: 1,
-          apiUrl: "https://congvc-x99.taila6fa8a.ts.net:18443",
-        }),
-      ),
-    ).toEqual({
-      schemaVersion: 1,
-      apiUrl: "https://congvc-x99.taila6fa8a.ts.net:18443",
-      wsUrl: "wss://congvc-x99.taila6fa8a.ts.net:18443/ws",
-      appUrl: "https://congvc-x99.taila6fa8a.ts.net:18443",
-    });
-  });
-
-  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");
-  });
-
-  it("accepts explicit appUrl and wsUrl", () => {
-    expect(
-      parseRuntimeConfig(
-        JSON.stringify({
-          schemaVersion: 1,
-          apiUrl: "https://api.example.com/",
-          wsUrl: "wss://ws.example.com/socket/",
-          appUrl: "https://app.example.com/",
-        }),
-      ),
-    ).toEqual({
-      schemaVersion: 1,
-      apiUrl: "https://api.example.com",
-      wsUrl: "wss://ws.example.com/socket",
-      appUrl: "https://app.example.com",
-    });
-  });
-
-  it("rejects invalid JSON", () => {
-    expect(() => parseRuntimeConfig("{")).toThrow(/Invalid desktop runtime config JSON/);
-  });
-
-  it("rejects unsupported schema versions", () => {
-    expect(() =>
-      parseRuntimeConfig(JSON.stringify({ schemaVersion: 2, apiUrl: "https://api.example.com" })),
-    ).toThrow(/schemaVersion/);
-  });
-
-  it("rejects non-http api schemes", () => {
-    expect(() =>
-      parseRuntimeConfig(JSON.stringify({ schemaVersion: 1, apiUrl: "file:///tmp/multica" })),
-    ).toThrow(/apiUrl must use http or https/);
-  });
-
-  it("rejects non-ws websocket schemes", () => {
-    expect(() =>
-      parseRuntimeConfig(
-        JSON.stringify({
-          schemaVersion: 1,
-          apiUrl: "https://api.example.com",
-          wsUrl: "https://api.example.com/ws",
-        }),
-      ),
-    ).toThrow(/wsUrl must use ws or wss/);
-  });
-
-  it("preserves electron-vite dev env precedence", () => {
-    expect(
-      runtimeConfigFromDevEnv({
-        apiUrl: "http://dev-api.example.test:8080/",
-        wsUrl: "ws://dev-api.example.test:8080/ws/",
-        appUrl: "http://dev-app.example.test:3000/",
-      }),
-    ).toEqual({
-      schemaVersion: 1,
-      apiUrl: "http://dev-api.example.test:8080",
-      wsUrl: "ws://dev-api.example.test:8080/ws",
-      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

@@ -1,179 +0,0 @@
-export interface RuntimeConfig {
-  schemaVersion: 1;
-  apiUrl: string;
-  wsUrl: string;
-  appUrl: string;
-}
-
-export interface RuntimeConfigError {
-  message: string;
-}
-
-export type RuntimeConfigResult =
-  | { ok: true; config: RuntimeConfig }
-  | { ok: false; error: RuntimeConfigError };
-
-export const DEFAULT_RUNTIME_CONFIG: RuntimeConfig = Object.freeze({
-  schemaVersion: 1,
-  apiUrl: "https://api.multica.ai",
-  wsUrl: "wss://api.multica.ai/ws",
-  appUrl: "https://multica.ai",
-});
-
-const LOCAL_DEV_RUNTIME_CONFIG: RuntimeConfig = Object.freeze({
-  schemaVersion: 1,
-  apiUrl: "http://localhost:8080",
-  wsUrl: "ws://localhost:8080/ws",
-  appUrl: "http://localhost:3000",
-});
-
-export interface RuntimeConfigEnv {
-  apiUrl?: string;
-  wsUrl?: string;
-  appUrl?: string;
-}
-
-export function runtimeConfigFromDevEnv(env: RuntimeConfigEnv): RuntimeConfig {
-  const apiUrl = normalizeHttpUrl(
-    env.apiUrl || LOCAL_DEV_RUNTIME_CONFIG.apiUrl,
-    "VITE_API_URL",
-  );
-  return {
-    schemaVersion: 1,
-    apiUrl,
-    wsUrl: env.wsUrl
-      ? normalizeWsUrl(env.wsUrl, "VITE_WS_URL")
-      : deriveWsUrl(apiUrl),
-    appUrl: env.appUrl
-      ? normalizeHttpUrl(env.appUrl, "VITE_APP_URL")
-      : deriveDevAppUrl(apiUrl),
-  };
-}
-
-export function parseRuntimeConfig(raw: string): RuntimeConfig {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(
-      `Invalid desktop runtime config JSON: ${err instanceof Error ? err.message : "parse failed"}`,
-    );
-  }
-
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error("Invalid desktop runtime config: expected a JSON object");
-  }
-
-  const obj = parsed as Record<string, unknown>;
-  if (obj.schemaVersion !== 1) {
-    throw new Error("Unsupported desktop runtime config schemaVersion: expected 1");
-  }
-
-  const apiUrl = requiredString(obj.apiUrl, "apiUrl");
-  const appUrl = optionalString(obj.appUrl, "appUrl");
-  const wsUrl = optionalString(obj.wsUrl, "wsUrl");
-
-  const normalizedApiUrl = normalizeHttpUrl(apiUrl, "apiUrl");
-  return {
-    schemaVersion: 1,
-    apiUrl: normalizedApiUrl,
-    wsUrl: wsUrl ? normalizeWsUrl(wsUrl, "wsUrl") : deriveWsUrl(normalizedApiUrl),
-    appUrl: appUrl ? normalizeHttpUrl(appUrl, "appUrl") : deriveAppUrl(normalizedApiUrl),
-  };
-}
-
-export function deriveWsUrl(apiUrl: string): string {
-  const url = new URL(apiUrl);
-  if (url.protocol === "https:") url.protocol = "wss:";
-  else if (url.protocol === "http:") url.protocol = "ws:";
-  else throw new Error("apiUrl must use http or https");
-  url.pathname = joinPath(url.pathname, "/ws");
-  url.search = "";
-  url.hash = "";
-  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`);
-  }
-  return value;
-}
-
-function optionalString(value: unknown, field: string): string | undefined {
-  if (value === undefined) return undefined;
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`Invalid desktop runtime config: ${field} must be a non-empty string when set`);
-  }
-  return value;
-}
-
-function normalizeHttpUrl(value: string, field: string): string {
-  let url: URL;
-  try {
-    url = new URL(value.trim());
-  } catch {
-    throw new Error(`Invalid desktop runtime config: ${field} must be a valid URL`);
-  }
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error(`Invalid desktop runtime config: ${field} must use http or https`);
-  }
-  url.search = "";
-  url.hash = "";
-  return trimTrailingSlash(url.toString());
-}
-
-function normalizeWsUrl(value: string, field: string): string {
-  let url: URL;
-  try {
-    url = new URL(value.trim());
-  } catch {
-    throw new Error(`Invalid desktop runtime config: ${field} must be a valid URL`);
-  }
-  if (url.protocol !== "ws:" && url.protocol !== "wss:") {
-    throw new Error(`Invalid desktop runtime config: ${field} must use ws or wss`);
-  }
-  url.search = "";
-  url.hash = "";
-  return trimTrailingSlash(url.toString());
-}
-
-function joinPath(base: string, suffix: string): string {
-  const normalizedBase = base.endsWith("/") ? base.slice(0, -1) : base;
-  return `${normalizedBase}${suffix}`;
-}
-
-function trimTrailingSlash(value: string): string {
-  return value.replace(/\/+$/, "");
-}

apps/desktop/test/setup.ts

@@ -1,38 +1 @@
 import "@testing-library/jest-dom/vitest";
-
-function createMemoryStorage(): Storage {
-  const values = new Map<string, string>();
-
-  return {
-    get length() {
-      return values.size;
-    },
-    clear: () => values.clear(),
-    getItem: (key: string) => values.get(key) ?? null,
-    key: (index: number) => Array.from(values.keys())[index] ?? null,
-    removeItem: (key: string) => {
-      values.delete(key);
-    },
-    setItem: (key: string, value: string) => {
-      values.set(key, value);
-    },
-  };
-}
-
-const localStorageIsUsable =
-  typeof globalThis.localStorage?.getItem === "function" &&
-  typeof globalThis.localStorage?.setItem === "function" &&
-  typeof globalThis.localStorage?.removeItem === "function" &&
-  typeof globalThis.localStorage?.clear === "function";
-
-if (!localStorageIsUsable) {
-  const storage = createMemoryStorage();
-  Object.defineProperty(globalThis, "localStorage", {
-    configurable: true,
-    value: storage,
-  });
-  Object.defineProperty(window, "localStorage", {
-    configurable: true,
-    value: storage,
-  });
-}

apps/desktop/vitest.config.ts

@@ -1,14 +1,8 @@
-import { resolve } from "path";
 import { defineConfig } from "vitest/config";
 import react from "@vitejs/plugin-react";
 
 export default defineConfig({
   plugins: [react()],
-  resolve: {
-    alias: {
-      "@": resolve(__dirname, "src/renderer/src"),
-    },
-  },
   test: {
     globals: true,
     include: ["src/**/*.test.{ts,tsx}", "scripts/**/*.test.mjs"],

apps/docs/app/[lang]/[...slug]/page.tsx

@@ -9,14 +9,6 @@ import { notFound } from "next/navigation";
 import defaultMdxComponents from "fumadocs-ui/mdx";
 import type { Metadata } from "next";
 import { docsAlternates } from "@/lib/site";
-import { i18n, type Lang } from "@/lib/i18n";
-import { DocsLocaleProvider, LocaleLink } from "@/components/locale-link";
-
-function asLang(lang: string): Lang {
-  return (i18n.languages as readonly string[]).includes(lang)
-    ? (lang as Lang)
-    : (i18n.defaultLanguage as Lang);
-}
 
 export default async function Page(props: {
   params: Promise<{ lang: string; slug: string[] }>;
@@ -26,16 +18,13 @@ export default async function Page(props: {
   if (!page) notFound();
 
   const MDX = page.data.body;
-  const lang = asLang(params.lang);
 
   return (
     <DocsPage toc={page.data.toc}>
       <DocsTitle>{page.data.title}</DocsTitle>
       <DocsDescription>{page.data.description}</DocsDescription>
       <DocsBody>
-        <DocsLocaleProvider lang={lang}>
-          <MDX components={{ ...defaultMdxComponents, a: LocaleLink }} />
-        </DocsLocaleProvider>
+        <MDX components={{ ...defaultMdxComponents }} />
       </DocsBody>
     </DocsPage>
   );

apps/docs/app/[lang]/page.tsx

@@ -8,7 +8,6 @@ import { Byline, NumberedCards, NumberedCard, NumberedSteps, Step } from "@/comp
 import { i18n, type Lang } from "@/lib/i18n";
 import { homeCopy } from "@/lib/translations";
 import { docsAlternates } from "@/lib/site";
-import { DocsLocaleProvider, LocaleLink } from "@/components/locale-link";
 
 function asLang(lang: string): Lang {
   return (i18n.languages as readonly string[]).includes(lang)
@@ -53,18 +52,15 @@ export default async function Page({
       />
       <Byline items={[...copy.byline]} />
       <DocsBody>
-        <DocsLocaleProvider lang={lang}>
-          <MDX
-            components={{
-              ...defaultMdxComponents,
-              a: LocaleLink,
-              NumberedCards,
-              NumberedCard,
-              NumberedSteps,
-              Step,
-            }}
-          />
-        </DocsLocaleProvider>
+        <MDX
+          components={{
+            ...defaultMdxComponents,
+            NumberedCards,
+            NumberedCard,
+            NumberedSteps,
+            Step,
+          }}
+        />
       </DocsBody>
     </DocsPage>
   );

apps/docs/components/editorial.tsx

@@ -1,9 +1,5 @@
-"use client";
-
 import Link from "next/link";
 import type { ReactNode } from "react";
-import { useDocsLocale } from "@/components/locale-link";
-import { prefixLocale } from "@/lib/locale-link";
 
 /**
  * Byline — editorial metadata strip with ruled top + bottom borders.
@@ -59,10 +55,9 @@ export function NumberedCard({
   tag?: string;
   children: ReactNode;
 }) {
-  const lang = useDocsLocale();
   return (
     <Link
-      href={prefixLocale(href, lang)}
+      href={href}
       className="group flex flex-col gap-2.5 border-r border-border px-0 py-5 pr-4 no-underline last:border-r-0 md:px-4 md:first:pl-0 md:last:pr-0"
     >
       <div className="font-mono text-[0.6875rem] uppercase tracking-[0.08em] text-muted-foreground">

apps/docs/components/locale-link.tsx

@@ -1,48 +0,0 @@
-"use client";
-
-import Link from "next/link";
-import {
-  createContext,
-  useContext,
-  type AnchorHTMLAttributes,
-  type ReactNode,
-} from "react";
-import { i18n, type Lang } from "@/lib/i18n";
-import { prefixLocale } from "@/lib/locale-link";
-
-const DocsLocaleContext = createContext<Lang>(i18n.defaultLanguage as Lang);
-
-// Wraps the rendered MDX subtree so descendant <LocaleLink>s and any
-// editorial component using `useDocsLocale()` know which language the page
-// was rendered in. Mounted at each docs page entry; never elsewhere.
-export function DocsLocaleProvider({
-  lang,
-  children,
-}: {
-  lang: Lang;
-  children: ReactNode;
-}) {
-  return (
-    <DocsLocaleContext.Provider value={lang}>
-      {children}
-    </DocsLocaleContext.Provider>
-  );
-}
-
-export function useDocsLocale(): Lang {
-  return useContext(DocsLocaleContext);
-}
-
-// Drop-in replacement for the MDX-rendered `<a>` element. Keeps the same
-// surface shape as the default `a` from `defaultMdxComponents` but routes
-// internal links through the locale prefixer + next/link so client-side
-// navigation stays inside the active locale.
-export function LocaleLink({
-  href,
-  ...rest
-}: AnchorHTMLAttributes<HTMLAnchorElement> & { href?: string }) {
-  const lang = useDocsLocale();
-  if (!href) return <a {...rest} />;
-  const final = prefixLocale(href, lang);
-  return <Link href={final} {...rest} />;
-}

apps/docs/content/docs/agents.mdx

@@ -45,5 +45,4 @@ 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,5 +45,4 @@ 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. The same flow also accepts a [squad](/squads) as the assignee — Multica then triggers the squad's **leader agent** instead.
+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.
 
 | 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, all non-archived agents, and every non-archived [squad](/squads). Pick an agent (or squad) and the issue is assigned right away.
+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.
 
 A few rules:
 
@@ -32,10 +32,9 @@ The command-line equivalent:
 
 ```bash
 multica issue assign MUL-42 --to alice
-multica issue assign MUL-42 --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 ```
 
-`--to` takes a member username or an agent name (fuzzy match). When names overlap — e.g. an agent `J` alongside `Cursor - J` — pass `--to-id <uuid>` instead, using the `user_id` (member) or `id` (agent) from `multica workspace members --output json` / `multica agent list --output json`. UUID matching is strict and unambiguous, which is what you want from scripts and from agents driving the CLI. `--to` and `--to-id` are mutually exclusive.
+`--to` takes a member username or an agent name. Giving agents memorable names makes this step smoother — if multiple agents share a name in the workspace, the first one listed wins, so rename before assigning.
 
 Unassign:
 
@@ -78,6 +77,5 @@ 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 四种触发方式里**最常见也最"重"**的一种。同样的流程也接受 [小队（squad）](/squads) 作为 assignee——这种情况下 Multica 会触发小队的**队长智能体**。
+把 [issue](/issues) 分配给 [智能体](/agents)，它会作为**正式负责人**一直工作到结束——能读到 issue 的完整上下文（描述 + 所有 [评论](/comments)），也能改状态、发评论、改字段。这是 Multica 四种触发方式里**最常见也最"重"**的一种。
 
 | 方式 | 何时用 | 改 issue | 上下文 | 优先级 | 自动重试 |
 |---|---|---|---|---|---|
@@ -18,7 +18,7 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 ## 在界面里分配
 
-在 issue 详情页点 **Assignee** 选择器，会列出工作区里所有成员、未归档的智能体、以及未归档的 [小队](/squads)。选一个智能体（或小队），issue 立刻分配。
+在 issue 详情页点 **Assignee** 选择器，会列出工作区里所有成员和未归档的智能体。选一个智能体，issue 立刻分给它。
 
 几条规则：
 
@@ -32,10 +32,9 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 ```bash
 multica issue assign MUL-42 --to alice
-multica issue assign MUL-42 --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 ```
 
-`--to` 后跟成员用户名或智能体名字（模糊匹配）。如果工作区里有同名 / 互相含子串的成员或智能体（例如 agent `J` 旁边还有 `Cursor - J`），改用 `--to-id <uuid>`：UUID 来自 `multica workspace members --output json` 的 `user_id` 或 `multica agent list --output json` 的 `id`，是唯一精确的方式，特别适合脚本和驱动 CLI 的智能体。`--to` 和 `--to-id` 互斥。
+`--to` 后跟成员用户名或智能体名字。给智能体起个好记的名字会让这一步顺很多——工作区里重名的会按列出顺序选第一个，建议先改名再分配。
 
 取消分配：
 
@@ -78,6 +77,5 @@ multica issue assign MUL-42 --unassign
 ## 下一步
 
 - [**在评论里 @ 智能体**](/mentioning-agents) —— 更轻量的触发方式，不改 assignee / status
-- [**小队**](/squads) —— 把 issue 分给一组智能体，由队长决定谁接手
 - [**对话**](/chat) —— 脱离 issue 和智能体一对一聊
 - [**Autopilots**](/autopilots) —— 让智能体定时自动开工

apps/docs/content/docs/auth-setup.mdx

@@ -12,11 +12,9 @@ For the list of environment variables referenced below, see [Environment variabl
 
 ## How email + verification code sign-in works
 
-The user enters an email on the sign-in page → the server sends a 6-digit code → the user enters it → the server verifies it → a JWT cookie is issued. Standard flow. Two delivery backends are supported — pick whichever fits your deployment:
+The user enters an email on the sign-in page → the server sends a 6-digit code → the user enters it → the server verifies it → a JWT cookie is issued. Standard flow. It requires [Resend](https://resend.com/) as the email provider:
 
-### Option A: Resend (recommended for cloud / public-internet deployments)
-
-1. Create a [Resend](https://resend.com/) account and verify your domain
+1. Create a Resend account and verify your domain
 2. Create an API key
 3. Set the environment variables:
 
@@ -27,22 +25,7 @@ The user enters an email on the sign-in page → the server sends a 6-digit code
 
 4. Restart the server
 
-### Option B: SMTP relay (for self-hosted / on-premise deployments)
-
-Use this when the deployment can't reach `api.resend.com` or you already have an internal mail relay (Exchange, Postfix, on-prem SendGrid, etc.). `SMTP_HOST` takes priority over `RESEND_API_KEY` when both are set.
-
-```bash
-SMTP_HOST=smtp.internal.example.com
-SMTP_PORT=587                  # default 25; use 587 for STARTTLS submission
-SMTP_USERNAME=multica          # leave empty for unauthenticated relay
-SMTP_PASSWORD=...
-SMTP_TLS_INSECURE=false        # set true only for self-signed / private CA
-RESEND_FROM_EMAIL=noreply@yourdomain.com  # reused as the From: header
-```
-
-STARTTLS is upgraded automatically when the server advertises it. Port 465 (SMTPS / implicit TLS) is **not** currently supported — use port 25 or 587.
-
-**What happens if you set neither**: the server doesn't error, but **every email that should have been sent is written to the server's stdout only**. Handy for local development (copy the code from the logs); in production it's a black hole.
+**What happens if you don't set `RESEND_API_KEY`**: the server doesn't error, but **every email that should have been sent is written to the server's stdout only**. Handy for local development (copy the code from the logs); in production it's a black hole.
 
 ## Fixed local testing codes
 
@@ -51,7 +34,7 @@ STARTTLS is upgraded automatically when the server advertises it. Port 465 (SMTP
 
 The old behavior where non-production instances accepted `888888` by default has been removed. Unless you explicitly configure it, typing `888888` is treated like any other wrong code.
 
-Local development without any email backend configured (no Resend, no SMTP) should use the generated code printed in server logs. If you need deterministic local/private automation, set `MULTICA_DEV_VERIFICATION_CODE` to a 6-digit value such as `888888`, and keep `APP_ENV` non-production:
+Local development without Resend should use the generated code printed in server logs. If you need deterministic local/private automation, set `MULTICA_DEV_VERIFICATION_CODE` to a 6-digit value such as `888888`, and keep `APP_ENV` non-production:
 
 ```bash
 APP_ENV=development

apps/docs/content/docs/auth-setup.zh.mdx

@@ -12,11 +12,9 @@ Multica 支持两种登录方式：**Email + 验证码**（默认）和 **Google
 
 ## Email + 验证码登录怎么工作
 
-用户在登录页输邮箱 → server 发 6 位验证码 → 用户填回 → server 验证 → 签发 JWT cookie。是标准流程。支持两种邮件发送通道，按部署环境二选一：
+用户在登录页输邮箱 → server 发 6 位验证码 → 用户填回 → server 验证 → 签发 JWT cookie。是标准流程。需要 [Resend](https://resend.com/) 作为邮件发送服务：
 
-### Option A：Resend（公网/云端部署推荐）
-
-1. 在 [Resend](https://resend.com/) 建账号、验证你的域名
+1. 在 Resend 建账号、验证你的域名
 2. 创建 API key
 3. 设环境变量：
 
@@ -27,22 +25,7 @@ Multica 支持两种登录方式：**Email + 验证码**（默认）和 **Google
 
 4. 重启 server
 
-### Option B：SMTP relay（内网/自部署）
-
-适合内网无法访问 `api.resend.com`，或者已经有内部邮件中继（Exchange、Postfix、自部署 SendGrid 等）的场景。同时设置时 `SMTP_HOST` 优先级高于 `RESEND_API_KEY`。
-
-```bash
-SMTP_HOST=smtp.internal.example.com
-SMTP_PORT=587                  # 默认 25；STARTTLS 提交端口用 587
-SMTP_USERNAME=multica          # 留空则使用未认证 relay
-SMTP_PASSWORD=...
-SMTP_TLS_INSECURE=false        # 仅在私有 CA / 自签证书时改成 true
-RESEND_FROM_EMAIL=noreply@yourdomain.com  # 同时作为 SMTP From: 头
-```
-
-服务端 advertise STARTTLS 时会自动升级。**暂不支持** 465（SMTPS / 隐式 TLS），请使用 25 或 587。
-
-**两种都不配**：server 不报错，但所有本该发出去的邮件**只打到 server 的 stdout**。本地开发方便（你从日志抄验证码），生产环境等于黑洞。
+**不配 `RESEND_API_KEY` 的后果**：server 不报错，但**所有本该发出去的邮件只打到 server 的 stdout**。本地开发方便（你从日志抄验证码），生产环境等于黑洞。
 
 ## 固定本地测试验证码
 
@@ -51,7 +34,7 @@ RESEND_FROM_EMAIL=noreply@yourdomain.com  # 同时作为 SMTP From: 头
 
 旧版「非 production 默认接受 `888888`」的行为已经移除。除非你显式配置，否则输入 `888888` 会和普通错误验证码一样被拒绝。
 
-没配任何邮件后端（Resend 和 SMTP 都没设）的本地开发，应使用 server 日志里打印的随机验证码。如果你需要确定性的本地/私有自动化测试，可以把 `MULTICA_DEV_VERIFICATION_CODE` 设成一个 6 位数字，比如 `888888`，并保持 `APP_ENV` 为非 production：
+不配 Resend 的本地开发，应使用 server 日志里打印的随机验证码。如果你需要确定性的本地/私有自动化测试，可以把 `MULTICA_DEV_VERIFICATION_CODE` 设成一个 6 位数字，比如 `888888`，并保持 `APP_ENV` 为非 production：
 
 ```bash
 APP_ENV=development

apps/docs/content/docs/autopilots.mdx

@@ -1,6 +1,6 @@
 ---
 title: Autopilots
-description: Let agents start work on a cron schedule, an inbound webhook, or trigger once manually via the UI or CLI.
+description: Let agents start work on a cron schedule — or trigger once manually via the UI or CLI.
 ---
 
 import { Callout } from "fumadocs-ui/components/callout";
@@ -16,15 +16,19 @@ Create a new autopilot on the workspace's **Autopilot** page. You set:
 - **Priority** — inherited by the `task` it produces (same semantics as issue priority)
 - **Description / prompt** — the work description the agent receives each run
 - **Execution mode** — see below
-- **Triggers** — at least one `schedule` (cron + timezone) or `webhook`
+- **Triggers** — at least one `schedule` (cron + timezone)
 
 ## Pick an execution mode
 
 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 currently supports a single placeholder, `{{date}}`, which interpolates to the UTC date in `YYYY-MM-DD` format; any other `{{...}}` token is rejected at create-time so a typo cannot silently land as the literal string in your issue titles), 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.
+- **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.
@@ -50,109 +54,15 @@ multica autopilot trigger <autopilot-id>
 
 A manual trigger goes through the exact same execution flow as a `schedule` trigger — only the `source` field on the run record is marked `manual`.
 
-## Trigger from a webhook
-
-Autopilots can also fire on inbound HTTP webhooks. Add a **Webhook** trigger
-on the autopilot detail page; Multica generates a unique URL of the shape:
-
-```
-https://<your-multica-host>/api/webhooks/autopilots/awt_…
-```
-
-POST any JSON to that URL — Multica records a run with `source = webhook`,
-stores the body as the run's `trigger_payload`, and dispatches the agent
-exactly the way a schedule trigger would.
-
-```bash
-curl -X POST "$MULTICA_WEBHOOK_URL" \
-  -H "Content-Type: application/json" \
-  -d '{"event":"demo.received","eventPayload":{"message":"hello"}}'
-```
-
-In **create issue mode**, the inbound payload is appended to the new issue's
-description so the agent can read it inline. In **run-only mode**, the
-payload is part of the run context the daemon hands the agent.
-
-### Payload shape
-
-You can send your own envelope:
-
-```json
-{ "event": "github.pull_request.opened", "eventPayload": { } }
-```
-
-…or any JSON object/array. Multica normalizes it into an internal envelope:
-
-```json
-{
-  "event": "<inferred>",
-  "eventPayload": <your body>,
-  "request": { "receivedAt": "<rfc3339>", "contentType": "application/json" }
-}
-```
-
-When you don't provide an `event` field, Multica infers it from common
-headers and body fields (`X-GitHub-Event` + body `action`,
-`X-Gitlab-Event`, `X-Event-Type`, body `event`/`type`/`action`). When
-nothing matches, the event is `webhook.received`.
-
-When configuring GitHub or similar sources, set the content type to
-`application/json` — form-encoded webhook payloads are not accepted.
-
-### URL is a bearer secret
-
-The generated URL **is** the credential. Anyone with it can fire the
-autopilot. Treat it like a token:
-
-- **Don't paste it into public issue threads, screenshots, or chat history.**
-- **Rotate it if it leaks** — click "Rotate URL" on the trigger row, or run
-  `multica autopilot trigger-rotate-url <autopilot-id> <trigger-id>`. The
-  old URL stops working immediately.
-- For sources that require strong source authentication, wait for
-  per-trigger HMAC signature verification; this v1 URL is bearer-only.
-- Workspace members who can view the autopilot can read its webhook URLs
-  for now — tighter per-role secret visibility is a follow-up.
-
-### Status-code semantics
-
-Multica returns `200 OK` with a `status` field for normal no-op outcomes so
-your provider's webhook-retry machinery doesn't keep hammering the URL:
-
-- `{"status":"accepted","run_id":"…","autopilot_id":"…","trigger_id":"…"}`
-  — a run was dispatched.
-- `{"status":"skipped","run_id":"…","reason":"agent runtime is offline at dispatch time"}`
-  — the assignee's runtime is offline; recorded as a `skipped` run.
-- `{"status":"ignored","reason":"trigger_disabled"}` — the trigger is disabled.
-- `{"status":"ignored","reason":"autopilot_paused"}` — the autopilot is paused.
-- `{"status":"ignored","reason":"autopilot_archived"}` — the autopilot is archived.
-
-Non-2xx responses cover real failures:
-
-- `400` — invalid JSON, scalar body, or empty body.
-- `404` — unknown token (`{"error":"webhook not found"}`).
-- `413` — payload exceeded 256 KiB.
-- `429` — per-token rate limit exceeded (defaults to 60 req/min).
-
-### Self-hosted: configure your public URL
-
-When `MULTICA_PUBLIC_URL` is set on the server (e.g. `https://multica.example.com`),
-the trigger response includes an absolute `webhook_url` and the UI shows a
-ready-to-copy URL. Without it, the UI composes the URL from the client's
-API origin — which is fine for desktop and same-origin web, but not for
-custom self-hosted reverse proxies. Multica deliberately does not derive
-the public host from `Host` / `X-Forwarded-Host` headers so a misconfigured
-reverse proxy cannot trick the server into minting webhook URLs pointing at
-an attacker-controlled host.
-
 ## View run history
 
 Every trigger produces a **run record**, visible on the "History" tab of the autopilot detail page:
 
-- Trigger source (`schedule` / `manual` / `webhook`)
+- Trigger source (`schedule` / `manual`)
 - Start time, completion time
-- Status (`issue_created` / `running` / `completed` / `failed` / `skipped`)
+- Status (`issue_created` / `running` / `completed` / `failed`)
 - The linked issue (create issue mode) or `task` (run-only mode)
-- Failure reason (if failed or skipped)
+- Failure reason (if failed)
 
 ## What happens when an autopilot fails
 
@@ -166,11 +76,7 @@ Why no auto-retry: autopilots are already periodic, so adding system-level retri
 
 ## What's not yet available
 
-**API-kind triggers are not wired up.** The trigger schema reserves an `api`
-kind, but no ingress route fires it; the UI shows a Deprecated badge for
-existing rows and offers no copy/rotate affordances. Per-trigger HMAC
-signature verification, IP allowlists, and provider-specific event presets
-are tracked as follow-ups; v1 URLs are bearer-only.
+**Webhook and API triggers are not available yet.** The autopilot trigger schema reserves `webhook` and `api` types, but **they are not wired up to any ingress route** — the UI can create triggers of either type, but they will not actually fire. Today, **only `schedule` and manual triggers are end-to-end usable.**
 
 ## Next
 

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

@@ -1,6 +1,6 @@
 ---
 title: Autopilots
-description: 让智能体按 cron 定时自己开工，或在 webhook 到来时被触发——也可以通过 UI / CLI 手动触发一次。
+description: 让智能体按 cron 定时自己开工——或通过 UI / CLI 手动触发一次。
 ---
 
 import { Callout } from "fumadocs-ui/components/callout";
@@ -16,15 +16,19 @@ Autopilots 让 [智能体](/agents) **按调度自动开工**——配好 cron
 - **优先级** — 继承给它产生的 `task`（语义同 issue 优先级）
 - **描述 / Prompt** — 智能体每次执行拿到的工作说明
 - **执行模式** — 见下节
-- **触发器** — 至少加一条 `schedule`（cron + 时区）或 `webhook`
+- **触发器** — 至少加一条 `schedule`（cron + 时区）
 
 ## 选择执行模式
 
 Autopilot 有两种执行模式，**建议从"先建 issue 模式"开始**：
 
-- **先建 issue 模式**（`create_issue`）—— 默认，**推荐**。每次触发先在工作区里建一个 issue（标题目前只支持一个占位符 `{{date}}`，会插值成 UTC 日期 `YYYY-MM-DD`；其他 `{{...}}` 形式的占位符会在创建时被拒绝，避免拼错以后悄无声息地把原文当成 issue 标题），再按分配流程把 issue 派给智能体。所有工作都落在 issue 看板上，历史、评论、状态和手动分配的 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 表达式按哪个时区解读。
@@ -50,105 +54,15 @@ multica autopilot trigger <autopilot-id>
 
 手动触发走和 `schedule` 触发完全相同的执行流程，只是运行记录里 `source` 字段标为 `manual`。
 
-## 通过 Webhook 触发
-
-Autopilot 也可以由入站 HTTP webhook 触发。在详情页添加一个 **Webhook**
-触发器，Multica 会生成一个唯一的 URL：
-
-```
-https://<你的 Multica host>/api/webhooks/autopilots/awt_…
-```
-
-向这个 URL POST 任意 JSON——Multica 会记录一条 `source = webhook` 的
-run，把请求体保存为 run 的 `trigger_payload`，然后按和 schedule 触发器
-完全一致的方式派发给智能体。
-
-```bash
-curl -X POST "$MULTICA_WEBHOOK_URL" \
-  -H "Content-Type: application/json" \
-  -d '{"event":"demo.received","eventPayload":{"message":"hello"}}'
-```
-
-在**先建 issue 模式**下，入站 payload 会附加在新 issue 的描述里供智能体
-直接读到；**直跑模式**下，payload 也会随 run 一并交给 daemon。
-
-### Payload 形态
-
-可以发自己的封装：
-
-```json
-{ "event": "github.pull_request.opened", "eventPayload": { } }
-```
-
-也可以直接发任意 JSON 对象 / 数组。Multica 会规范化为内部封装：
-
-```json
-{
-  "event": "<推断>",
-  "eventPayload": <你的 body>,
-  "request": { "receivedAt": "<rfc3339>", "contentType": "application/json" }
-}
-```
-
-不带 `event` 字段时，Multica 会按以下顺序从常见 header 和 body 字段
-推断：`X-GitHub-Event` + body `action`，`X-Gitlab-Event`、
-`X-Event-Type`、body 里的 `event` / `type` / `action`。都不命中时事件
-名退化为 `webhook.received`。
-
-配置 GitHub 之类的来源时，请把 content type 设为 `application/json`——
-表单编码的 webhook payload 在 v1 里不接受。
-
-### URL 即 bearer secret
-
-生成的 URL **就是凭证**，谁拿到都能触发这个 Autopilot。请按 token 对待：
-
-- **不要贴到公开 issue 评论、截图、聊天记录里。**
-- **泄漏后立即重新生成**——在触发器上点"重新生成 URL"，或运行
-  `multica autopilot trigger-rotate-url <autopilot-id> <trigger-id>`。
-  旧 URL 立即失效。
-- 对需要强来源认证的源，等 per-trigger HMAC 签名校验上线；v1 URL 仅
-  bearer。
-- 当前能查看 Autopilot 的工作区成员都能看到它的 webhook URL——更细的
-  权限可见性是后续工作。
-
-### 状态码语义
-
-正常的 no-op 路径都返回 `200 OK` 加 `status` 字段，避免外部 webhook 重试
-机制反复打：
-
-- `{"status":"accepted","run_id":"…","autopilot_id":"…","trigger_id":"…"}`
-  —— 已派发一次 run。
-- `{"status":"skipped","run_id":"…","reason":"agent runtime is offline at dispatch time"}`
-  —— 受派智能体的 runtime 离线，记为 `skipped` run。
-- `{"status":"ignored","reason":"trigger_disabled"}` —— 触发器已禁用。
-- `{"status":"ignored","reason":"autopilot_paused"}` —— Autopilot 已暂停。
-- `{"status":"ignored","reason":"autopilot_archived"}` —— Autopilot 已归档。
-
-非 2xx 是真正的失败：
-
-- `400` —— 无效 JSON、scalar body、空 body。
-- `404` —— 未知 token（`{"error":"webhook not found"}`）。
-- `413` —— 请求体超过 256 KiB。
-- `429` —— 单 token 速率限制（默认 60 次 / 分钟）。
-
-### 自托管：配置公开 URL
-
-服务端设置 `MULTICA_PUBLIC_URL`（例如 `https://multica.example.com`）后，
-触发器响应里会带绝对的 `webhook_url`，UI 直接显示可复制的 URL。没设
-时 UI 会用客户端的 API origin 拼出 URL——desktop 和同源 web 没问题，
-但自定义反向代理就不行了。Multica **故意不**从 `Host` /
-`X-Forwarded-Host` header 推断公开主机，避免反代配置失误时被诱导生成
-指向攻击者域名的 webhook URL。
-
 ## 看运行历史
 
 每次触发都会产生一条**运行记录**（run），可以在 Autopilot 详情页的"历史"tab 看到：
 
-- 触发源（`schedule` / `manual` / `webhook`）
+- 触发源（`schedule` / `manual`）
 - 开始时间、完成时间
-- 状态（`issue_created` / `running` / `completed` / `failed` / `skipped`）
+- 状态（`issue_created` / `running` / `completed` / `failed`）
 - 关联的 issue（先建 issue 模式）或 `task`（直跑模式）
-- 失败原因（失败或跳过时）
+- 失败原因（如果失败）
 
 ## Autopilot 失败会怎样
 
@@ -162,10 +76,7 @@ curl -X POST "$MULTICA_WEBHOOK_URL" \
 
 ## 暂不可用的能力
 
-**API 类型触发器尚未接入。** 触发器 schema 里保留了 `api` 类型但没有
-入站路由会触发它；UI 会给已有的此类记录打 Deprecated 标签，也不显示
-copy / rotate 操作。Per-trigger HMAC 签名校验、IP allowlist、按提供方
-的事件预设是后续工作；v1 URL 仅 bearer。
+**Webhook 和 API 触发暂不可用**。Autopilot 的触发器类型在 schema 里预留了 `webhook` 和 `api` 两种，但**还没接入站路由**——UI 可以创建这两类触发器，不会真的触发。目前**只有 `schedule` 和手动触发是端到端可用的**。
 
 ## 下一步
 

apps/docs/content/docs/cli.mdx

@@ -40,25 +40,20 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 | `multica workspace list` | List every workspace you can access |
 | `multica workspace get <slug>` | Show details for one workspace |
 | `multica workspace members` | List members of the current workspace |
-| `multica workspace update <id> --name "..." [--description "..."] [--context "..."] [--issue-prefix "..."]` | Update workspace metadata (admin/owner). Long fields accept `--description-stdin` / `--context-stdin`. |
 
 ## 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 (prints copy-paste-ready issue keys) |
-| `multica issue get <id>` | Show a single issue (accepts an issue key or a UUID) |
+| `multica issue list` | List issues |
+| `multica issue get <id>` | Show a single issue |
 | `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>` | Re-enqueue a fresh task for the issue's current agent assignee |
+| `multica issue rerun <id>` | Rerun the most recent agent task |
 | `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 |
@@ -79,20 +74,6 @@ 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 |
@@ -117,6 +98,7 @@ See [Squads](/squads) for the full model.
 | `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

@@ -40,25 +40,20 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 | `multica workspace list` | 列出你有权访问的所有工作区 |
 | `multica workspace get <slug>` | 查看一个工作区的详情 |
 | `multica workspace members` | 列出当前工作区的成员 |
-| `multica workspace update <id> --name "..." [--description "..."] [--context "..."] [--issue-prefix "..."]` | 修改 workspace 元数据（admin/owner 权限）。长文本可用 `--description-stdin` / `--context-stdin`。 |
 
 ## 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（默认显示可复制的 issue key） |
-| `multica issue get <id>` | 查看单条 issue（接受 issue key 或 UUID） |
+| `multica issue list` | 列出 issue |
+| `multica issue get <id>` | 查看单条 issue |
 | `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>` | 给该 issue 当前的智能体分配人重新创建一条任务 |
+| `multica issue rerun <id>` | 重跑最近一次智能体任务 |
 | `multica issue comment <id> ...` | 嵌套：看 / 发评论 |
 | `multica issue subscriber <id> ...` | 嵌套：订阅 / 取消订阅 |
 | `multica project list/get/create/update/delete/status` | Project CRUD |
@@ -79,20 +74,6 @@ 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
 
 | 命令 | 用途 |
@@ -117,6 +98,7 @@ 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

@@ -18,10 +18,10 @@ Opens your browser for OAuth authentication, creates a 90-day personal access to
 ### Token Login
 
 ```bash
-multica login --token <mul_...>
+multica login --token
 ```
 
-Authenticate using a personal access token directly. Useful for headless environments. Pass `--token=` with an empty value to be prompted interactively (so the token never lands in shell history).
+Authenticate by pasting a personal access token directly. Useful for headless environments.
 
 ### Check Status
 
@@ -213,28 +213,6 @@ multica workspace get <workspace-id> --output json
 multica workspace members <workspace-id>
 ```
 
-### Update Workspace
-
-需要 admin 或 owner 权限。所有字段都是部分更新（PATCH 语义）：未传的字段保持不变。
-
-```bash
-multica workspace update <workspace-id> --name "Acme Eng"
-multica workspace update <workspace-id> \
-  --description "Engineering team workspace" \
-  --issue-prefix ENG
-```
-
-长文本走 stdin（保留换行/反斜杠）：
-
-```bash
-cat <<'CTX' | multica workspace update <workspace-id> --context-stdin
-我们是一支 5 人 AI-native 团队。
-工作语言：中文 + 英文混合。
-CTX
-```
-
-可编辑字段：`--name`、`--description` / `--description-stdin`、`--context` / `--context-stdin`、`--issue-prefix`。`slug` 创建后只读，不暴露在 CLI。`--description` 与 `--description-stdin`（以及 `context` 同名对）互斥。未传任何字段 flag 时命令拒绝执行，避免空 PATCH 触发无意义的 workspace 更新事件。`--issue-prefix ""` 也会被拒绝：当前后端在 prefix 为空时静默跳过该字段，CLI 在本地拦下避免“看似成功的 no-op”。
-
 ## Issues
 
 ### List Issues
@@ -243,31 +221,25 @@ CTX
 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
 ```
 
-表格输出默认显示可直接复制到后续命令的 issue `KEY`（例如 `MUL-123`）；需要完整 UUID 时使用 `--full-id`。Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--limit`. 在重名 workspace 下用 `--assignee-id <uuid>` 可以精确锁定一个成员或 agent。
+Available filters: `--status`, `--priority`, `--assignee`, `--project`, `--limit`.
 
 ### Get Issue
 
 ```bash
-multica issue get MUL-123
-multica issue get <uuid>
+multica issue get <id>
 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
 multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"
-multica issue create --title "Fix login bug" --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 ```
 
-Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee` / `--assignee-id`, `--parent`, `--project`, `--due-date`. 脚本里如果已经拿到了 UUID（例如来自 `multica workspace members --output json`），传 `--assignee-id <uuid>`（与 `--assignee` 互斥）以精确锁定。
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--project`, `--due-date`.
 
 ### Update Issue
 
@@ -279,12 +251,9 @@ multica issue update <id> --title "New title" --priority urgent
 
 ```bash
 multica issue assign <id> --to "Lambda"
-multica issue assign <id> --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 multica issue assign <id> --unassign
 ```
 
-`--to-id <uuid>`（与 `--to` 互斥）按 UUID 精确分配；适合重名 workspace 下脚本化场景。
-
 ### Change Status
 
 ```bash
@@ -314,20 +283,16 @@ 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/cloud-quickstart.mdx

@@ -99,7 +99,7 @@ Assign the issue to the agent you just created — click its avatar in the web U
 multica issue assign MUL-1 --to my-agent-name
 ```
 
-`--to` takes the **name** of an agent or member. A substring match works — if the agent is called `my-code-reviewer`, `reviewer` resolves to it. If your workspace has overlapping names, pass `--to-id <uuid>` instead (mutually exclusive with `--to`); look up the UUID via `multica agent list --output json` or `multica workspace members --output json`.
+`--to` takes the **name** of an agent or member. A substring match works — if the agent is called `my-code-reviewer`, `reviewer` resolves to it.
 
 **What happens next from the daemon**:
 

apps/docs/content/docs/cloud-quickstart.zh.mdx

@@ -99,7 +99,7 @@ multica issue create --title "给 README 加一段 ASCII 架构图"
 multica issue assign MUL-1 --to my-agent-name
 ```
 
-`--to` 后面填智能体或成员的**名字**，子串就行——如果智能体叫 `my-code-reviewer`，填 `reviewer` 也能命中。如果工作区里名字相互重叠或冲突，改用 `--to-id <uuid>`（与 `--to` 互斥）；UUID 来自 `multica agent list --output json` 或 `multica workspace members --output json`。
+`--to` 后面填智能体或成员的**名字**，子串就行——如果智能体叫 `my-code-reviewer`，填 `reviewer` 也能命中。
 
 **接下来守护进程会**：
 

apps/docs/content/docs/daemon-runtimes.mdx

@@ -37,7 +37,7 @@ Common commands:
 
 Full CLI reference in [CLI commands](/cli).
 
-**The desktop app ships with a daemon.** If you use the [desktop app](/desktop-app), you don't need to run `multica daemon start` manually — it launches the daemon automatically on startup. See the [Desktop app](/desktop-app) page for which option fits your workflow.
+**The desktop app ships with a daemon.** If you use the [desktop app](/desktop-app), you don't need to run `multica daemon start` manually — it launches the daemon automatically on startup.
 
 ## Why one machine has multiple runtimes
 

apps/docs/content/docs/daemon-runtimes.zh.mdx

@@ -37,7 +37,7 @@ multica daemon start
 
 完整 CLI 参考见 [CLI 命令速查](/cli)。
 
-**桌面应用自带守护进程。**用 [桌面应用](/desktop-app) 就不必手动 `multica daemon start`——它启动时会自动拉起守护进程。哪种方式更适合你的工作流，详见 [桌面应用](/desktop-app) 页面。
+**桌面应用自带守护进程。**用 [桌面应用](/desktop-app) 就不必手动 `multica daemon start`——它启动时会自动拉起守护进程。
 
 ## 为什么一台机器会有多个运行时
 

apps/docs/content/docs/desktop-app.mdx

@@ -5,7 +5,7 @@ description: What Multica Desktop is, how it differs from the web app, and when
 
 import { Callout } from "fumadocs-ui/components/callout";
 
-Multica Desktop is a native desktop app for macOS, Windows, and Linux. For the environment it is configured for, it talks to the same backend as the web app and shows the same data. By default Desktop uses Multica Cloud; self-hosted instances can be configured with a local runtime config file. Desktop also adds a few things the browser can't: **independent tab groups per [workspace](/workspaces)**, **automatic [daemon](/daemon-runtimes) startup**, and **one-click upgrades**.
+Multica Desktop is a native desktop app for macOS, Windows, and Linux. It talks to the same backend as the web app and shows the same data, but it adds a few things the browser can't: **independent tab groups per [workspace](/workspaces)**, **automatic [daemon](/daemon-runtimes) startup**, and **one-click upgrades**.
 
 ## Desktop or web — which to pick
 
@@ -66,34 +66,25 @@ Grab the installer for your platform from the [Multica downloads page](https://m
 
 On first launch you'll need to sign in — the same email + verification code flow as the web app. Once you're in, Desktop syncs your workspace list automatically.
 
-<Callout type="info">
-**Desktop defaults to Multica Cloud, but can be pointed at a self-hosted instance with a local config file.** There is still no in-app "connect to self-host" picker. Desktop reads `~/.multica/desktop.json` before the renderer starts; if the file is missing, it uses the Cloud defaults.
+<Callout type="warning">
+**Released Desktop builds are pinned to Multica Cloud.** The backend, websocket, and web URLs are baked in at build time (`VITE_API_URL` / `VITE_WS_URL` / `VITE_APP_URL`) — there is no in-app option to point Desktop at a self-hosted instance. To use Desktop against a self-hosted backend you need to build it yourself:
 
-Minimal self-host config:
-
-```json
-{
-  "schemaVersion": 1,
-  "apiUrl": "https://api.your-domain"
-}
+```bash
+git clone https://github.com/multica-ai/multica.git
+cd multica
+# Edit apps/desktop/.env.production:
+#   VITE_API_URL=https://api.your-domain
+#   VITE_WS_URL=wss://api.your-domain/ws
+#   VITE_APP_URL=https://your-domain
+pnpm install
+pnpm --filter @multica/desktop package
 ```
 
-`apiUrl` is required and must use `http` or `https`. Desktop derives `wsUrl` as `/ws` on the same origin (`wss` for `https`, `ws` for `http`) and derives `appUrl` from the API origin. If your deployment uses different origins, set them explicitly:
-
-```json
-{
-  "schemaVersion": 1,
-  "apiUrl": "https://api.your-domain",
-  "wsUrl": "wss://api.your-domain/ws",
-  "appUrl": "https://your-domain"
-}
-```
-
-If `desktop.json` exists but is invalid, Desktop fails closed and shows a blocking config error instead of silently falling back to Cloud. For development builds, `VITE_API_URL` / `VITE_WS_URL` / `VITE_APP_URL` still take precedence during `electron-vite dev`. Runtime Desktop self-host configuration was implemented for [issue #1371](https://github.com/multica-ai/multica/issues/1371).
+If you'd rather not build from source, the supported self-hosted path is **web frontend + CLI** — see [Self-host quickstart](/self-host-quickstart). Runtime backend configuration in Desktop is tracked in [issue #1371](https://github.com/multica-ai/multica/issues/1371).
 </Callout>
 
 ## Next steps
 
 - [Cloud Quickstart](/cloud-quickstart) — the Cloud onboarding flow for Desktop
-- [Self-Host Quickstart](/self-host-quickstart) — running your own backend and connecting with the CLI or Desktop runtime config
+- [Self-Host Quickstart](/self-host-quickstart) — running your own backend (Desktop against self-host requires a custom build, see the callout above)
 - [Daemon and runtimes](/daemon-runtimes) — how the daemon works (Desktop starts it for you, but the behavior is the same)

apps/docs/content/docs/desktop-app.zh.mdx

@@ -5,7 +5,7 @@ description: Multica Desktop 是什么、和 Web 有什么区别、什么时候
 
 import { Callout } from "fumadocs-ui/components/callout";
 
-Multica Desktop 是原生桌面应用——macOS / Windows / Linux 三个平台。对它当前配置的环境来说，它和 Web 版连同一个后端、看到的数据完全一样。Desktop 默认使用 Multica Cloud；自部署实例可以通过本地运行时配置文件接入。它还给了几个 Web 做不到的能力：**[工作区](/workspaces) 独立的多标签页**、**自动启动 [守护进程](/daemon-runtimes)**、**一键升级**。
+Multica Desktop 是原生桌面应用——macOS / Windows / Linux 三个平台。它和 Web 版连同一个后端，看到的数据完全一样，但给了几个 Web 做不到的能力：**[工作区](/workspaces) 独立的多标签页**、**自动启动 [守护进程](/daemon-runtimes)**、**一键升级**。
 
 ## Desktop 和 Web 该用哪个
 
@@ -66,34 +66,25 @@ macOS 版本已经签名 + 公证，第一次打开不会有"未知开发者"的
 
 安装后第一次打开需要登录——和 Web 版一样的 email + 验证码流程。登录成功后 Desktop 自动把工作区列表同步下来。
 
-<Callout type="info">
-**Desktop 默认连接 Multica Cloud，但可以通过本地配置文件指向自部署实例。** 应用内仍然没有“连接自部署”的切换入口。Desktop 会在 renderer 启动前读取 `~/.multica/desktop.json`；如果这个文件不存在，就使用 Cloud 默认值。
+<Callout type="warning">
+**发布版的 Desktop 是锁死连 Multica Cloud 的**。后端 / WebSocket / Web 前端 URL（`VITE_API_URL` / `VITE_WS_URL` / `VITE_APP_URL`）在构建时就写死了，应用内**没有切换后端的入口**。要让 Desktop 连自部署后端，需要你自己从源码 build：
 
-最小自部署配置：
-
-```json
-{
-  "schemaVersion": 1,
-  "apiUrl": "https://api.your-domain"
-}
+```bash
+git clone https://github.com/multica-ai/multica.git
+cd multica
+# 编辑 apps/desktop/.env.production：
+#   VITE_API_URL=https://api.your-domain
+#   VITE_WS_URL=wss://api.your-domain/ws
+#   VITE_APP_URL=https://your-domain
+pnpm install
+pnpm --filter @multica/desktop package
 ```
 
-`apiUrl` 是必填项，必须使用 `http` 或 `https`。Desktop 会自动从它推导 `wsUrl`（同源 `/ws`，`https` 对应 `wss`，`http` 对应 `ws`）和 `appUrl`（API 的同源地址）。如果你的部署使用不同域名，可以显式设置：
-
-```json
-{
-  "schemaVersion": 1,
-  "apiUrl": "https://api.your-domain",
-  "wsUrl": "wss://api.your-domain/ws",
-  "appUrl": "https://your-domain"
-}
-```
-
-如果 `desktop.json` 存在但内容无效，Desktop 会 fail closed，显示阻塞式配置错误，而不是悄悄回退到 Cloud。开发构建里，`electron-vite dev` 仍然优先使用 `VITE_API_URL` / `VITE_WS_URL` / `VITE_APP_URL`。Desktop 运行时自部署配置能力对应 [issue #1371](https://github.com/multica-ai/multica/issues/1371)。
+不想自己 build 的话，自部署的官方路径是 **Web 前端 + CLI**——见 [自部署快速上手](/self-host-quickstart)。Desktop 运行时切换后端的能力跟踪在 [issue #1371](https://github.com/multica-ai/multica/issues/1371)。
 </Callout>
 
 ## 下一步
 
 - [Cloud Quickstart](/cloud-quickstart) —— Desktop 版的 Cloud 接入流程
-- [Self-Host Quickstart](/self-host-quickstart) —— 自部署后端，并通过 CLI 或 Desktop 运行时配置连接
+- [Self-Host Quickstart](/self-host-quickstart) —— 自部署后端（Desktop 连自部署需要自行构建，见上方提示）
 - [守护进程与运行时](/daemon-runtimes) —— 守护进程机制（Desktop 自动起它，但行为一样）

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

@@ -1,302 +0,0 @@
----
-title: Conventions
-description: Single source of truth for code naming, i18n translation glossary, and Chinese voice guide.
----
-
-This page is the single source of truth for code naming, the i18n translation glossary, and the Chinese voice guide. Anything that used to live in `packages/views/locales/glossary.md` or in scattered comments now lives here.
-
-If you write Multica code, change a translation, or write Chinese product copy, this is the page to reference.
-
----
-
-## 1. Code naming
-
-### Routes
-
-Pre-workspace routes (the routes that exist before the user is in a workspace) MUST use either a single word or the `/{noun}/{verb}` pattern.
-
-- ✅ `/login`, `/inbox`, `/workspaces/new`
-- ❌ `/new-workspace`, `/create-team`, `/accept-invite`
-
-Hyphenated word groups at the root collide with user-chosen workspace slugs and force endless reserved-slug audits. Reserving the noun (`workspaces`) automatically protects the entire `/workspaces/*` subtree.
-
-### Workspace-scoped routes
-
-Always live under `/{slug}/{section}` — `/{slug}/issues`, `/{slug}/agents`, `/{slug}/settings`. Never duplicate workspace routing logic; use `useNavigation().push()` from shared code, never framework-specific link APIs.
-
-### Packages and modules
-
-The monorepo enforces strict package boundaries:
-
-| Package | May depend on | Must NOT depend on |
-| --- | --- | --- |
-| `packages/core` | nothing app-specific | `react-dom`, `localStorage`, `process.env`, `next/*`, UI libraries |
-| `packages/ui` | nothing | `@multica/core`, business logic |
-| `packages/views` | `core/`, `ui/` | `next/*`, `react-router-dom`, stores |
-| `apps/web/platform/` | `next/*` | other apps |
-| `apps/desktop/.../platform/` | `react-router-dom`, electron | other apps |
-
-If logic appears in both apps, it MUST be extracted to a shared package. There are no exceptions for "small" duplication.
-
-### Files and components
-
-- Files: `kebab-case.tsx` / `kebab-case.ts` (e.g. `agent-row-actions.tsx`)
-- Components: `PascalCase` (e.g. `AgentRowActions`)
-- Hooks: `useCamelCase` (e.g. `useWorkspaceId`)
-- Tests: colocated as `<file>.test.ts(x)`
-- Stores (Zustand): `<feature>-store.ts`, exported as `use<Feature>Store`
-
-### Database (Go + sqlc)
-
-- Tables: `snake_case` singular (`user`, `workspace`, `agent_runtime`)
-- Columns: `snake_case` (`workspace_id`, `created_at`, `last_seen_at`)
-- Foreign keys: `<table>_id`
-- Booleans: `is_<state>` or `<state>_at` (timestamp form preferred for state changes)
-- Migration files: `NNN_descriptive_name.up.sql` + `.down.sql` — always provide both directions
-
-### Go
-
-- Standard `gofmt` + `go vet`. No exceptions.
-- Handler files mirror domain: `agent.go`, `auth.go`, `runtime.go`
-- Tests: `<file>_test.go` colocated
-- For UUID parsing in handlers, follow the rule in the root `CLAUDE.md` — `parseUUIDOrBadRequest` for boundary input, `parseUUID` (panicking) for trusted round-trips, never `util.ParseUUID` directly without checking the error.
-
-### TypeScript
-
-- API responses on the wire are `snake_case`; the api client converts to `camelCase` at the boundary. Inside TS code, **always camelCase**.
-- Types: `PascalCase` (`Issue`, `AgentRuntime`); never `IPrefix`, never `_t` suffix.
-- Enums: prefer string literal unions; reserve `enum` for runtime-iterable cases.
-- TanStack Query keys: factory functions in `<feature>/queries.ts`, e.g. `issueKeys.detail(id)`.
-
-### Issue keys
-
-Every issue has a human-readable key like `MUL-123`: workspace `issue_prefix` (3 letters, uppercase) + sequence number. The prefix is set at workspace creation and is never changed afterward.
-
-### Comments in code
-
-English only. The repo enforces this for both Go and TypeScript. If you find a Chinese comment in code, it's a bug — replace it.
-
-### Commit messages
-
-Conventional format: `feat(scope)`, `fix(scope)`, `refactor(scope)`, `docs`, `test(scope)`, `chore(scope)`. Atomic commits grouped by intent.
-
----
-
-## 2. i18n translation glossary
-
-This is the **mandatory** glossary for every translation PR. It used to live at `packages/views/locales/glossary.md`; that file is now a stub pointing here.
-
-### The core distinction: entity vs concept
-
-Multica's product nouns split into two categories:
-
-- **Entity** — has a URL, a database row, an API type. In Chinese text, render as **lowercase English** so it visually reads like a type name and signals "this is a Multica system entity".
-- **Concept** — generic noun, not a database entity. **Translate fully** so Chinese users don't see jagged English embedded in flowing text.
-
-This rule is aligned with `apps/docs/content/docs/*.zh.mdx` — the docs are the de facto Chinese voice standard and have been battle-tested across 20+ pages.
-
-### Entities — mixed rule (`issue` / `skill` / `task`)
-
-`issue` / `skill` / `task` are Multica's core entities. They have schema columns, API fields, and product UI labels that are all English. In Chinese text, they follow a **mixed rule** — what to use depends on where the word appears:
-
-| Context | Render | Example |
-| --- | --- | --- |
-| **UI strings, state names, code references** | lowercase English | "排队中的 task"、"创建子 issue"、"为智能体注入 skill" |
-| **Doc titles / section headings** | Title-case English **or** the Chinese term | "Issue 与 project"、"Skills"、"执行任务" |
-| **Long-form doc prose, when the entity is the running subject** | Chinese term, with English in parentheses on first mention | "**执行任务**（task）是智能体每一次工作的单位" |
-| **API / DB fields** | always `task` / `issue` / `skill` | `task_id`, `issue_status`, `skill_uuid` |
-
-Chinese term reference:
-
-- `task` ↔ `执行任务` (or shortened to `任务` once context is clear)
-- `issue` has no settled Chinese translation — leave English; titles may capitalize as `Issue`
-- `skill` has no settled Chinese translation — leave English; titles may capitalize as `Skills`
-
-**Why `issue` / `skill` / `task` aren't forced into Chinese the way `project` / `autopilot` are**:
-
-- **`issue` / `task`**: dev teams talk in English. The Chinese candidates ("任务" — too vague, almost synonymous with "工作"; "工单" — IT ticket connotation; "议题" — GitHub-style but doesn't match the product feel) all read worse than `issue`. **But** in long-form doc prose, repeating lowercase `task` 50× breaks the rhythm — so prose is allowed to use `执行任务`, while UI strings and state names stay lowercase English.
-- **`skill`**: Multica-specific concept with no established Chinese term.
-- **`project` → "项目"**: settled mainstream Chinese word. Feishu / Tower / Teambition / PingCode / GitHub Projects — every Chinese product translates it. No product keeps `project` in Chinese context.
-- **`autopilot` → "自动化"**: in Chinese, "autopilot" associates with Tesla's "自动驾驶" and doesn't match what the feature does (run tasks on a schedule). Notion and Feishu both use "自动化"; that's the industry consensus.
-
-### Don't translate — brands and acronyms
-
-| Category | Terms |
-| --- | --- |
-| Brands | **Multica**, GitHub, Slack, Google, Anthropic, OpenAI, Claude, Codex, Cursor, Linear, Jira |
-| Acronyms | API, CLI, URL, SDK, OAuth, JWT, SSO, WebSocket, HTTP, JSON, YAML, SQL |
-
-### Translate fully — concepts
-
-| English | Chinese |
-| --- | --- |
-| Workspace | **工作区** |
-| Agent | **智能体** |
-| Project | **项目** |
-| Autopilot | **自动化** |
-| Daemon | **守护进程** |
-| Runtime | **运行时** |
-| Inbox | **收件箱** |
-| Comment | **评论** |
-| Reply | **回复** |
-| Notifications | **通知** |
-| Member | **成员** |
-| Label | **标签** |
-| Settings | **设置** |
-| Onboarding | **上手引导** |
-
-### Translate fully — generic UI words
-
-| English | Chinese |
-| --- | --- |
-| Invite / Invitation | 邀请 |
-| Search | 搜索 |
-| Email | 邮箱 (label) / 邮件 (action) |
-| Password | 密码 |
-| Sign in / Log in | 登录 |
-| Sign up | 注册 |
-| Sign out / Log out | 退出登录 |
-| Save / Cancel / Delete | 保存 / 取消 / 删除 |
-| Confirm / Continue / Back | 确认 / 继续 / 返回 |
-| Edit / New / Create / Add | 编辑 / 新建 / 创建 / 添加 |
-| Remove / Send / Open / Close | 移除 / 发送 / 打开 / 关闭 |
-| Preview / Download / Upload | 预览 / 下载 / 上传 |
-| Done / Loading... | 完成 / 加载中... |
-| Profile / Account / Appearance | 个人资料 / 账号 / 外观 |
-| Theme / Language | 主题 / 语言 |
-| Light / Dark / System | 浅色 / 深色 / 跟随系统 |
-| Active / Archived | 活跃 (or 启用) / 已归档 |
-| Status / Priority | 状态 / 优先级 |
-| Assignee / Reporter | 负责人 / 报告人 |
-| Description / Title | 描述 / 标题 |
-| Date / Time | 日期 / 时间 |
-| Today / Yesterday / Tomorrow | 今天 / 昨天 / 明天 |
-| Empty / Failed / Success | 空 / 失败 / 成功 |
-| Error / Warning | 错误 / 警告 |
-
-### Roles and status enums (lowercase English, not translated)
-
-These are schema-level identifiers; render as lowercase English even in Chinese context.
-
-- Roles: `owner` / `admin` / `member`
-- Issue status: `backlog` / `todo` / `in_progress` / `in_review` / `done` / `blocked` / `cancelled`
-
-In UI, surface them in English (optionally `code-style` wrapped):
-
-- "你需要 owner 权限"
-- "已切换到 in_progress"
-
-### Word combination rules
-
-Always put **a single space** between an English word (entity / brand / acronym) and surrounding Chinese:
-
-- "Create new issue" → "新建 issue"
-- "Assign to agent" → "分配给智能体"
-- "Configure runtime" → "配置运行时"
-- "Stop daemon" → "停止守护进程"
-
-### Plurals and counts
-
-i18next uses `_one` / `_other`; Chinese has no grammatical number, only fill `_other`.
-
-```json
-// en/issues.json
-{
-  "issue_count_one": "{{count}} issue",
-  "issue_count_other": "{{count}} issues"
-}
-
-// zh-Hans/issues.json
-{
-  "issue_count_other": "{{count}} 个 issue"
-}
-```
-
-Common count formats:
-
-- `{{count}} issues` → `{{count}} 个 issue`
-- `{{count}} agents` → `{{count}} 个智能体`
-- `{{count}} workspaces` → `{{count}} 个工作区`
-- `{{count}} comments` → `{{count}} 条评论`
-- `{{count}} members` → `{{count}} 位成员`
-- `{{count}} skills` → `{{count}} 个 skill`
-
-### Interpolation
-
-Use `{{var}}`. Chinese translations may reorder for natural sentence flow.
-
-```json
-// en
-{ "welcome_message": "Welcome back, {{name}}!" }
-
-// zh-Hans
-{ "welcome_message": "欢迎回来，{{name}}！" }
-```
-
-### Translation key naming
-
-Three-level nesting: `feature.component.action`.
-
-```json
-{
-  "feature_or_component": {
-    "subcomponent_or_section": {
-      "action_or_label": "..."
-    }
-  }
-}
-```
-
-Examples:
-
-- `issues.toolbar.batch_update_success`
-- `issues.detail.comment_form.placeholder`
-- `inbox.empty.title`
-- `settings.preferences.language.title`
-
-### Web-only / desktop-only copy
-
-- Shared copy: top level of the namespace JSON
-- Web-only: `web` section
-- Desktop-only: `desktop` section
-
-See `auth.json` for the canonical example (the `web` section contains `prefer_desktop` / `desktop_handoff.*`).
-
----
-
-## 3. Chinese voice and style
-
-### Punctuation
-
-- Full-width punctuation in Chinese: `，。：；！？`
-- Quotes: straight double quotes `"..."` to match the English source. Do not use `「」` or curly quotes.
-- Ellipsis: three dots `...` not the single character `…`. Match the English source.
-- Mixed Chinese-English: a single space on each side of the English word (see Word combination rules).
-
-### Style principles
-
-- **Concise and direct.** Avoid translation-ese: "对于 X 来说"、"作为 X"、"我们的"。
-- **Error messages**: gentle but clear. "无法保存修改" beats "保存修改失败了！".
-- **Buttons**: verb first, 2–4 characters. "取消"、"保存修改"、"立即同步".
-- **Tooltips**: full short sentence. "复制链接到剪贴板".
-- **Placeholders**: example-style. "输入 issue 标题...".
-
-### Where to look when in doubt
-
-When the glossary doesn't cover a term, look at:
-
-1. `apps/docs/content/docs/*.zh.mdx` — the de facto Chinese voice standard, 20+ pages of consistent translation
-2. `packages/views/locales/zh-Hans/auth.json` and `editor.json` — JSON structure + selector API patterns
-3. `packages/views/auth/login-page.tsx` — component-level selector API call site
-4. `packages/views/settings/components/preferences-tab.tsx` — language switcher reference
-
----
-
-## Updating this page
-
-If you change a rule here, also:
-
-1. Apply it in the relevant locale JSONs / CLAUDE.md / docs page
-2. Note the change in the PR description so reviewers know to look for downstream sweep
-
-This page is the contract; nothing else overrides it.

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

@@ -1,302 +0,0 @@
----
-title: 规范
-description: 代码命名规范、i18n 翻译术语表、中文风格指南的唯一权威来源。
----
-
-本页是代码命名规范、i18n 翻译术语表、中文风格指南的唯一权威来源。原本散落在 `packages/views/locales/glossary.md` 和各处注释里的规则现在都收拢到这里。
-
-写 Multica 代码、改翻译、写中文产品文案，都从这一页查。
-
----
-
-## 1. 代码命名
-
-### 路由
-
-工作区前置路由（用户进入工作区之前能访问的路由）必须用单个单词，或者 `/{noun}/{verb}` 格式。
-
-- ✅ `/login`、`/inbox`、`/workspaces/new`
-- ❌ `/new-workspace`、`/create-team`、`/accept-invite`
-
-根目录的连字符词组会跟用户自选 workspace slug 冲突，逼着团队不停审保留字列表。把名词（`workspaces`）保留下来，整个 `/workspaces/*` 子树自动受保护。
-
-### 工作区路由
-
-永远用 `/{slug}/{section}` —— `/{slug}/issues`、`/{slug}/agents`、`/{slug}/settings`。共享代码不要复制路由逻辑，统一走 `useNavigation().push()`，不要直接用框架的 link API。
-
-### 包与模块
-
-monorepo 的包边界是硬约束：
-
-| 包 | 可依赖 | 不能依赖 |
-| --- | --- | --- |
-| `packages/core` | 仅平台无关基础库 | `react-dom`、`localStorage`、`process.env`、`next/*`、UI 库 |
-| `packages/ui` | 无业务依赖 | `@multica/core`、业务逻辑 |
-| `packages/views` | `core/`、`ui/` | `next/*`、`react-router-dom`、stores |
-| `apps/web/platform/` | `next/*` | 其他 app |
-| `apps/desktop/.../platform/` | `react-router-dom`、electron | 其他 app |
-
-两个 app 都有的逻辑，**必须**抽到共享包。"小段重复"也不算例外。
-
-### 文件与组件
-
-- 文件名：`kebab-case.tsx` / `kebab-case.ts`（如 `agent-row-actions.tsx`）
-- 组件：`PascalCase`（如 `AgentRowActions`）
-- Hook：`useCamelCase`（如 `useWorkspaceId`）
-- 测试：与源文件同目录，命名 `<file>.test.ts(x)`
-- Zustand store：`<feature>-store.ts`，导出名 `use<Feature>Store`
-
-### 数据库（Go + sqlc）
-
-- 表名：`snake_case` 单数（`user`、`workspace`、`agent_runtime`）
-- 字段：`snake_case`（`workspace_id`、`created_at`、`last_seen_at`）
-- 外键：`<table>_id`
-- 布尔：`is_<state>` 或者 `<state>_at`（状态变化优先用时间戳形式）
-- 迁移文件：`NNN_descriptive_name.up.sql` + `.down.sql`，**永远写双向**
-
-### Go
-
-- 标准 `gofmt` + `go vet`，无例外
-- Handler 文件按域命名：`agent.go`、`auth.go`、`runtime.go`
-- 测试：`<file>_test.go` 同目录
-- handler 里 UUID 解析遵守根 `CLAUDE.md` 的规则：边界输入用 `parseUUIDOrBadRequest`，可信回环用 `parseUUID`（panic 版），永远不要直接用 `util.ParseUUID` 不查 error
-
-### TypeScript
-
-- 网络上 API 响应是 `snake_case`，api client 在边界处转成 `camelCase`。**TS 代码内部一律 camelCase**
-- 类型：`PascalCase`（`Issue`、`AgentRuntime`），不加 `IPrefix`，不加 `_t` 后缀
-- 枚举：优先用 string literal union，需要 runtime 迭代时才用 `enum`
-- TanStack Query key：用 `<feature>/queries.ts` 里的工厂函数，例如 `issueKeys.detail(id)`
-
-### Issue 编号
-
-每个 issue 有人类可读的编号，比如 `MUL-123`：工作区 `issue_prefix`（3 个大写字母）+ 流水号。前缀在工作区创建时定，之后不可改。
-
-### 代码注释
-
-**只允许英文**。Go 和 TypeScript 都强制。如果在代码里看到中文注释，那就是 bug，替换掉。
-
-### Commit message
-
-Conventional 格式：`feat(scope)`、`fix(scope)`、`refactor(scope)`、`docs`、`test(scope)`、`chore(scope)`。按意图原子化分组。
-
----
-
-## 2. i18n 翻译术语表
-
-这是每个翻译 PR 都必须遵守的术语表。原本在 `packages/views/locales/glossary.md`，那个文件现在是个 stub，指向这一页。
-
-### 核心区分：实体 vs 概念
-
-Multica 的产品名词分两类：
-
-- **实体（typed entity）** —— 有 URL、有数据库 row、是 API 响应里某种 type 的东西。中文里**用小写英文**呈现，视觉上像类型名，告诉读者"这是 Multica 系统里的特定实体"。
-- **概念（concept）** —— 不是数据库实体的普通名词。**完整翻译成中文**，CN 用户看不到生硬的英文。
-
-这套规则与 `apps/docs/content/docs/*.zh.mdx` 完全对齐 —— docs 是已经实战 20+ 篇的 CN voice 标准。
-
-### 实体词的混合规则（`issue` / `skill` / `task`）
-
-`issue` / `skill` / `task` 是 Multica 的核心实体。schema 字段、API 字段、产品 UI 标签都用英文。中文里采用**混合规则** —— 词出现在哪里决定怎么写：
-
-| 场景 | 写法 | 例 |
-| --- | --- | --- |
-| **UI 短句 / 状态名 / 代码上下文** | 小写英文 | "排队中的 task"、"创建子 issue"、"为智能体注入 skill" |
-| **doc 标题 / 章节标题** | 首字母大写英文，**或**对应中文术语 | "Issue 与 project"、"Skills"、"执行任务" |
-| **doc 正文长篇讨论中作为主语** | 中文术语，首次出现配括号英文 | "**执行任务**（task）是智能体每一次工作的单位" |
-| **API / DB 字段** | 永远 `task` / `issue` / `skill` | `task_id`、`issue_status`、`skill_uuid` |
-
-中文术语对照：
-
-- `task` ↔ `执行任务`（上下文清楚后可简写为「任务」）
-- `issue` 没有公认中文译法 —— 保留英文；标题可大写为 `Issue`
-- `skill` 没有公认中文译法 —— 保留英文；标题可大写为 `Skills`
-
-**为什么 `issue` / `skill` / `task` 不强制译，而 `project` / `autopilot` 必译**：
-
-- **`issue` / `task`**：dev 团队习惯说英文，"任务"在中文里和"工作"几乎同义太空泛，"工单"是 IT 工单语义，"议题"是 GitHub 风格但用户场景不匹配 —— 三个候选都不如 `issue` 准确。**但**在长篇 doc 正文里，重复 50 次 `task` 节奏不顺，所以正文允许用 `执行任务`，UI 短句、状态名仍保持小写英文。
-- **`skill`**：Multica 特有概念，没有公认中文译法。
-- **`project` 翻成「项目」**：中文里早就稳定的日常词。飞书 / Tower / Teambition / PingCode / GitHub Projects 中文版 0 例外都翻译成「项目」，没有产品保留 `project`。
-- **`autopilot` 翻成「自动化」**：autopilot 在中文里联想到特斯拉的「自动驾驶」，跟产品功能（按周期跑 task）对应不上。Notion / 飞书都用「自动化」，是行业共识。
-
-### 完整翻译 —— 概念词
-
-| 英 | 中 |
-| --- | --- |
-| Workspace | **工作区** |
-| Agent | **智能体** |
-| Project | **项目** |
-| Autopilot | **自动化** |
-| Daemon | **守护进程** |
-| Runtime | **运行时** |
-| Inbox | **收件箱** |
-| Comment | **评论** |
-| Reply | **回复** |
-| Notifications | **通知** |
-| Member | **成员** |
-| Label | **标签** |
-| Settings | **设置** |
-| Onboarding | **上手引导** |
-
-### 不翻 —— 品牌名 + 通用缩写
-
-| 类别 | 词 |
-| --- | --- |
-| 品牌 | **Multica**、GitHub、Slack、Google、Anthropic、OpenAI、Claude、Codex、Cursor、Linear、Jira |
-| 缩写 | API、CLI、URL、SDK、OAuth、JWT、SSO、WebSocket、HTTP、JSON、YAML、SQL |
-
-### 完整翻译 —— 通用 UI 词
-
-| 英 | 中 |
-| --- | --- |
-| Invite / Invitation | 邀请 |
-| Search | 搜索 |
-| Email | 邮箱（label）/ 邮件（action） |
-| Password | 密码 |
-| Sign in / Log in | 登录 |
-| Sign up | 注册 |
-| Sign out / Log out | 退出登录 |
-| Save / Cancel / Delete | 保存 / 取消 / 删除 |
-| Confirm / Continue / Back | 确认 / 继续 / 返回 |
-| Edit / New / Create / Add | 编辑 / 新建 / 创建 / 添加 |
-| Remove / Send / Open / Close | 移除 / 发送 / 打开 / 关闭 |
-| Preview / Download / Upload | 预览 / 下载 / 上传 |
-| Done / Loading... | 完成 / 加载中... |
-| Profile / Account / Appearance | 个人资料 / 账号 / 外观 |
-| Theme / Language | 主题 / 语言 |
-| Light / Dark / System | 浅色 / 深色 / 跟随系统 |
-| Active / Archived | 活跃（或 启用）/ 已归档 |
-| Status / Priority | 状态 / 优先级 |
-| Assignee / Reporter | 负责人 / 报告人 |
-| Description / Title | 描述 / 标题 |
-| Date / Time | 日期 / 时间 |
-| Today / Yesterday / Tomorrow | 今天 / 昨天 / 明天 |
-| Empty / Failed / Success | 空 / 失败 / 成功 |
-| Error / Warning | 错误 / 警告 |
-
-### 角色名 + 状态名（小写英文，不翻）
-
-这些是 schema-level 标识符，中文环境也保持小写英文：
-
-- 角色：`owner` / `admin` / `member`
-- Issue 状态：`backlog` / `todo` / `in_progress` / `in_review` / `done` / `blocked` / `cancelled`
-
-UI 里展示这些值时保持英文（必要时用 code-style 包起来）：
-
-- "你需要 owner 权限"
-- "已切换到 in_progress"
-
-### 词组组合规则
-
-英文词（实体名 + 品牌名 + 缩写）与中文之间**加单空格**：
-
-- "Create new issue" → "新建 issue"
-- "Assign to agent" → "分配给智能体"
-- "Configure runtime" → "配置运行时"
-- "Stop daemon" → "停止守护进程"
-
-### 复数与计数
-
-i18next 用 `_one` / `_other`；中文不区分语法单复数，只填 `_other`。
-
-```json
-// en/issues.json
-{
-  "issue_count_one": "{{count}} issue",
-  "issue_count_other": "{{count}} issues"
-}
-
-// zh-Hans/issues.json
-{
-  "issue_count_other": "{{count}} 个 issue"
-}
-```
-
-常见计数格式：
-
-- `{{count}} issues` → `{{count}} 个 issue`
-- `{{count}} agents` → `{{count}} 个智能体`
-- `{{count}} workspaces` → `{{count}} 个工作区`
-- `{{count}} comments` → `{{count}} 条评论`
-- `{{count}} members` → `{{count}} 位成员`
-- `{{count}} skills` → `{{count}} 个 skill`
-
-### 插值
-
-用 `{{var}}` 形式。中文翻译可以调整位置以符合中文语序。
-
-```json
-// en
-{ "welcome_message": "Welcome back, {{name}}!" }
-
-// zh-Hans
-{ "welcome_message": "欢迎回来，{{name}}！" }
-```
-
-### Key 命名约定
-
-3 层嵌套：`feature.component.action`。
-
-```json
-{
-  "feature_or_component": {
-    "subcomponent_or_section": {
-      "action_or_label": "..."
-    }
-  }
-}
-```
-
-实例：
-
-- `issues.toolbar.batch_update_success`
-- `issues.detail.comment_form.placeholder`
-- `inbox.empty.title`
-- `settings.preferences.language.title`
-
-### Web-only / Desktop-only 文案位置
-
-- 共享文案：放 namespace JSON 顶层
-- Web-only：放 `web` 段
-- Desktop-only：放 `desktop` 段
-
-参考 `auth.json`（`web` 段含 `prefer_desktop` / `desktop_handoff.*`）。
-
----
-
-## 3. 中文风格
-
-### 标点
-
-- 中文用全角标点：`，。：；！？`
-- 引号：用 `"..."`（直引号），与英文 source 保持一致。**不要**用 `「」` 或弯引号
-- 省略号：用 `...`（三点）而非 `…`（单字符），与英文 source 保持一致
-- 中英混排：英文词左右各加 1 个空格（详见词组组合规则）
-
-### 风格原则
-
-- **简洁直白**：避免翻译腔，"对于 X 来说"、"作为 X"、"我们的"
-- **错误信息**：温和但明确，"无法保存修改" 优于 "保存修改失败了！"
-- **按钮**：动词开头，2-4 字最佳。"取消"、"保存修改"、"立即同步"
-- **Tooltip**：完整短句。"复制链接到剪贴板"
-- **placeholder**：示例性提示。"输入 issue 标题..."
-
-### 拿不准的时候去哪查
-
-术语表没覆盖的词，按这个顺序查：
-
-1. `apps/docs/content/docs/*.zh.mdx` —— CN voice 事实标准，20+ 篇高度一致
-2. `packages/views/locales/zh-Hans/auth.json` 和 `editor.json` —— JSON 结构 + selector API 用法参考
-3. `packages/views/auth/login-page.tsx` —— 组件层 selector API 调用参考
-4. `packages/views/settings/components/preferences-tab.tsx` —— 语言切换器参考
-
----
-
-## 修改这一页时
-
-改本页规则的同时还要：
-
-1. 把规则在相关 locale JSON / CLAUDE.md / docs 页面里同步落地
-2. PR 描述里写明改了什么，方便 reviewer 检查下游是否跟着改了
-
-本页是契约，其他文档不能 override。

apps/docs/content/docs/developers/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "Developers",
-  "pages": ["conventions"]
-}

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

@@ -1,4 +1,4 @@
 {
   "title": "Developers",
-  "pages": ["contributing", "architecture", "conventions"]
+  "pages": ["contributing", "architecture"]
 }

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

@@ -35,28 +35,14 @@ These are the core variables you must think about before deploying — some have
 
 ## Email configuration
 
-Multica supports two delivery backends — [Resend](https://resend.com/) for cloud deployments, or an SMTP relay for internal / on-premise networks. `SMTP_HOST` takes priority over `RESEND_API_KEY` when both are set.
-
-### Resend
+Multica uses [Resend](https://resend.com/) to send verification codes and invite emails.
 
 | Variable | Default | Description |
 |---|---|---|
 | `RESEND_API_KEY` | empty | Resend API key |
-| `RESEND_FROM_EMAIL` | `noreply@multica.ai` | Sender address (must be a domain verified in your Resend account; also reused as the `From:` header when SMTP is in use) |
+| `RESEND_FROM_EMAIL` | `noreply@multica.ai` | Sender address (must be a domain verified in your Resend account) |
 
-### SMTP relay
-
-| Variable | Default | Description |
-|---|---|---|
-| `SMTP_HOST` | empty | SMTP relay hostname. Setting this activates SMTP mode and overrides Resend |
-| `SMTP_PORT` | `25` | SMTP port. Use `587` for STARTTLS submission; **port 465 (SMTPS / implicit TLS) is not supported** |
-| `SMTP_USERNAME` | empty | SMTP username. Leave empty for unauthenticated relay |
-| `SMTP_PASSWORD` | empty | SMTP password |
-| `SMTP_TLS_INSECURE` | `false` | Set `true` to skip TLS certificate verification (private CA / self-signed only) |
-
-STARTTLS is upgraded automatically when the server advertises it. The dial timeout is 10s and the whole SMTP session has a 30s deadline, so a black-holed relay can't hang the auth handler.
-
-**Behavior when neither is set**: the server does not error, but every email that should have been sent (verification codes, invite links) **is written to the server's stdout only**. Convenient for local development — copy the code out of the server logs; **in production, forgetting to set this creates a silent black hole**, with users never receiving email and no error surfaced.
+**Behavior when `RESEND_API_KEY` is unset**: the server does not error, but every email that should have been sent (verification codes, invite links) **is written to the server's stdout only**. Convenient for local development — copy the code out of the server logs; **in production, forgetting to set this creates a silent black hole**, with users never receiving email and no error surfaced.
 
 ## Google OAuth configuration
 
@@ -80,19 +66,13 @@ Multica stores user-uploaded attachments (images and files in comments). **S3 is
 
 | Variable | Default | Description |
 |---|---|---|
-| `S3_BUCKET` | empty | **Bucket name only** (for example `my-bucket`). Do **not** include the `.s3.<region>.amazonaws.com` suffix — the server constructs the public host from `S3_BUCKET` + `S3_REGION`. Setting this enables S3 storage |
-| `S3_REGION` | `us-west-2` | AWS region. Must match the bucket's actual region — it is used both for SDK signing and for building the public URL |
+| `S3_BUCKET` | empty | Setting this enables S3 storage |
+| `S3_REGION` | `us-west-2` | AWS region |
 | `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | empty | Static credentials. When both are unset, the AWS SDK default credential chain is used (IAM role / environment credentials) |
 | `AWS_ENDPOINT_URL` | empty | Custom S3-compatible endpoint (for example [MinIO](https://min.io/)). Setting this switches to path-style URLs |
 
 **When `S3_BUCKET` is unset**: the server logs `"S3_BUCKET not set, cloud upload disabled"` at startup, and all uploads fall back to local disk.
 
-**Public URLs** are constructed in this order of priority:
-
-1. `https://<CLOUDFRONT_DOMAIN>/<key>` if `CLOUDFRONT_DOMAIN` is set.
-2. `<AWS_ENDPOINT_URL>/<S3_BUCKET>/<key>` (path-style) if `AWS_ENDPOINT_URL` is set.
-3. `https://<S3_BUCKET>.s3.<S3_REGION>.amazonaws.com/<key>` (virtual-hosted-style). When `S3_BUCKET` contains dots, the server falls back to `https://s3.<S3_REGION>.amazonaws.com/<S3_BUCKET>/<key>` (path-style) because the AWS-issued wildcard TLS certificate does not validate dotted bucket hosts.
-
 ### Local disk (when S3 is not configured)
 
 | Variable | Default | Description |
@@ -128,25 +108,6 @@ Three allowlist layers combine by priority. **If any layer is set to a non-empty
 
 **Invite flows themselves do not check the signup allowlist** — but the invitee must still be able to **sign in** before accepting the invite. If they already have a Multica account (for example from another workspace), they can accept directly, unaffected by the allowlist; **if they have never signed up**, the first step of sign-in (requesting a verification code) still passes through the allowlist check, and an email rejected by `ALLOW_SIGNUP=false` or by `ALLOWED_EMAILS` / `ALLOWED_EMAIL_DOMAINS` **cannot finish signup, and therefore cannot accept the invite**.
 
-## Rate limiting (optional Redis)
-
-Public auth endpoints — `/auth/send-code`, `/auth/verify-code`, `/auth/google` — have per-IP fixed-window rate limiting in front of them. The limiter is backed by Redis. When `REDIS_URL` is unset the middleware is a **no-op** (fail-open) and the backend logs `rate limiting disabled: REDIS_URL not configured` at startup.
-
-| Variable | Default | Description |
-|---|---|---|
-| `REDIS_URL` | empty | Redis connection URL (for example `redis://localhost:6379/0`). When unset, rate limiting on auth endpoints is disabled. The same Redis is also used by the realtime hub fan-out, the PAT cache, and the daemon-token cache — they all fall back to in-memory / direct-DB mode when unset |
-| `RATE_LIMIT_AUTH` | `5` | Max requests per IP per minute against `/auth/send-code` and `/auth/google` |
-| `RATE_LIMIT_AUTH_VERIFY` | `20` | Max requests per IP per minute against `/auth/verify-code` |
-| `RATE_LIMIT_TRUSTED_PROXIES` | empty | Comma-separated CIDRs whose `X-Forwarded-For` header the limiter is allowed to trust. Empty (the default) means **never trust XFF** — the limiter only uses the direct connection's `RemoteAddr` |
-
-When a request is over the limit, the server replies with `429 Too Many Requests`, `Retry-After: 60`, and body `{"error":"too many requests"}`.
-
-<Callout type="warning">
-**Behind a reverse proxy you must set `RATE_LIMIT_TRUSTED_PROXIES`.** Otherwise every real user shares the proxy's IP from the backend's point of view, the whole deployment ends up in one bucket, and `/auth/send-code` becomes 5 req/min for the entire site. Typical values: `127.0.0.1/32,::1/128` for a same-host Caddy / Nginx; the CDN's published ranges for Cloudflare / ALB / CloudFront. Only IPs whose `RemoteAddr` falls inside one of these CIDRs may use `X-Forwarded-For` to identify the client.
-</Callout>
-
-This separate `RATE_LIMIT_TRUSTED_PROXIES` is **not** the same as `MULTICA_TRUSTED_PROXIES`, which controls the autopilot-webhook limiter (`/api/webhooks/autopilots/{token}`). Each limiter parses its own list, so a deployment behind a proxy should set both.
-
 ## Daemon tuning parameters
 
 The daemon runs on the user's local machine, and its config is read from local environment variables too. The common ones:
@@ -174,22 +135,6 @@ 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`.
@@ -203,6 +148,5 @@ 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

@@ -35,28 +35,14 @@ Multica 的 [自部署](/self-host-quickstart) 服务器启动时从环境变量
 
 ## 怎么配邮件
 
-Multica 支持两种邮件发送通道——[Resend](https://resend.com/) 适合公网部署，SMTP relay 适合内网/自部署。同时设置时 `SMTP_HOST` 优先级高于 `RESEND_API_KEY`。
-
-### Resend
+Multica 用 [Resend](https://resend.com/) 发验证码和邀请邮件。
 
 | 环境变量 | 默认值 | 说明 |
 |---|---|---|
 | `RESEND_API_KEY` | 空 | Resend API key |
-| `RESEND_FROM_EMAIL` | `noreply@multica.ai` | 发件地址（必须是 Resend 账号已验证的域名；走 SMTP 时同时作为 `From:` 头）|
+| `RESEND_FROM_EMAIL` | `noreply@multica.ai` | 发件地址（必须是 Resend 账号已验证的域名）|
 
-### SMTP relay
-
-| 环境变量 | 默认值 | 说明 |
-|---|---|---|
-| `SMTP_HOST` | 空 | SMTP relay 主机名。设置后即启用 SMTP 模式并覆盖 Resend |
-| `SMTP_PORT` | `25` | SMTP 端口。STARTTLS 提交端口用 `587`；**暂不支持 465（SMTPS / 隐式 TLS）** |
-| `SMTP_USERNAME` | 空 | SMTP 用户名。留空表示未认证 relay |
-| `SMTP_PASSWORD` | 空 | SMTP 密码 |
-| `SMTP_TLS_INSECURE` | `false` | 设为 `true` 跳过 TLS 证书校验（仅限私有 CA / 自签证书）|
-
-服务端 advertise STARTTLS 时会自动升级。dial 超时 10s，整个 SMTP 会话有 30s deadline，避免 relay 黑洞把 auth handler 挂死。
-
-**两种都不设的行为**：server 不会报错，但所有本该发出去的邮件（验证码、邀请链接）**只打到 server 的 stdout**。本地开发方便（你从 server 日志里抄验证码）；**生产环境忘记设就是黑洞**，用户收不到邮件也没任何错误提示。
+**不设 `RESEND_API_KEY` 时的行为**：server 不会报错，但所有本该发出去的邮件（验证码、邀请链接）**只打到 server 的 stdout**。本地开发时方便——你从 server 日志里抄验证码；**生产环境忘记设就是黑洞**，用户收不到邮件也没任何错误提示。
 
 ## 怎么配 Google OAuth
 
@@ -80,19 +66,13 @@ Multica 存储用户上传的附件（评论里的图片、文件等）。**优
 
 | 环境变量 | 默认值 | 说明 |
 |---|---|---|
-| `S3_BUCKET` | 空 | **只填 bucket 名**（例如 `my-bucket`），**不要**带 `.s3.<region>.amazonaws.com` 后缀——server 会用 `S3_BUCKET` + `S3_REGION` 自己拼公开 host。设了就启用 S3 存储 |
-| `S3_REGION` | `us-west-2` | AWS 区域。必须和 bucket 所在区域一致——SDK 签名和公开 URL 都用它 |
+| `S3_BUCKET` | 空 | 设了就启用 S3 存储 |
+| `S3_REGION` | `us-west-2` | AWS 区域 |
 | `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | 空 | 静态凭证。全未设时用 AWS SDK 默认凭证链（IAM role / 环境凭证）|
 | `AWS_ENDPOINT_URL` | 空 | 自定义 S3 兼容端点（例如 [MinIO](https://min.io/)）。设了会切到 path-style URL |
 
 **`S3_BUCKET` 未设时**：server 启动时打 info 日志 `"S3_BUCKET not set, cloud upload disabled"`，所有上传回落到本地磁盘。
 
-**公开 URL** 按优先级拼装：
-
-1. 设了 `CLOUDFRONT_DOMAIN` → `https://<CLOUDFRONT_DOMAIN>/<key>`
-2. 设了 `AWS_ENDPOINT_URL` → `<AWS_ENDPOINT_URL>/<S3_BUCKET>/<key>`（path-style）
-3. 默认走 AWS S3 → `https://<S3_BUCKET>.s3.<S3_REGION>.amazonaws.com/<key>`（virtual-hosted-style）。bucket 名含点时会回落到 `https://s3.<S3_REGION>.amazonaws.com/<S3_BUCKET>/<key>`（path-style），因为 AWS 通配证书无法覆盖含点 host。
-
 ### 本地磁盘（S3 未配时）
 
 | 环境变量 | 默认值 | 说明 |
@@ -128,25 +108,6 @@ Multica 存储用户上传的附件（评论里的图片、文件等）。**优
 
 **邀请流程本身不检查 signup 白名单**——但被邀请人必须先能**登录**才能接受邀请。如果对方已经有 Multica 账号（比如在其他工作区注册过），可以直接接受，不受白名单影响；**如果对方还没注册过**，他们登录的第一步（发送验证码）仍然会过白名单检查，被 `ALLOW_SIGNUP=false` 或 `ALLOWED_EMAILS` / `ALLOWED_EMAIL_DOMAINS` 拒绝的邮箱**无法完成注册，也就没法接受邀请**。
 
-## 速率限制（可选 Redis）
-
-公开认证端点——`/auth/send-code`、`/auth/verify-code`、`/auth/google`——前面挂了按 IP 的固定窗口限流。限流器后端是 Redis。`REDIS_URL` 不设时中间件**直通**（fail-open），后端启动会打日志 `rate limiting disabled: REDIS_URL not configured`。
-
-| 环境变量 | 默认值 | 说明 |
-|---|---|---|
-| `REDIS_URL` | 空 | Redis 连接 URL（例如 `redis://localhost:6379/0`）。不设时认证端点的限流功能直接关闭。同一个 Redis 也被实时事件 fan-out、PAT 缓存、守护进程 token 缓存复用；不设时这些组件分别回落到内存模式 / 直查 DB |
-| `RATE_LIMIT_AUTH` | `5` | 单 IP 每分钟对 `/auth/send-code` 和 `/auth/google` 的最大请求数 |
-| `RATE_LIMIT_AUTH_VERIFY` | `20` | 单 IP 每分钟对 `/auth/verify-code` 的最大请求数 |
-| `RATE_LIMIT_TRUSTED_PROXIES` | 空 | 逗号分隔的 CIDR 列表，列在内的来源 IP 才允许通过 `X-Forwarded-For` 标识客户端。默认空 = **永不信任 XFF**，限流器只看直连的 `RemoteAddr` |
-
-被限流的请求会返回 `429 Too Many Requests`，带 `Retry-After: 60` 头和 `{"error":"too many requests"}` 响应体。
-
-<Callout type="warning">
-**部署在反向代理后面时必须设 `RATE_LIMIT_TRUSTED_PROXIES`。** 否则在后端看来所有真实用户都共用代理那个 IP，整个部署落到同一个桶里，`/auth/send-code` 会变成全站每分钟只能发 5 次。常见值：本机 Caddy / Nginx 用 `127.0.0.1/32,::1/128`；Cloudflare / ALB / CloudFront 用各家公开的 CDN IP 段。只有 `RemoteAddr` 落在这些 CIDR 内的请求才被允许通过 `X-Forwarded-For` 改写客户端 IP。
-</Callout>
-
-这里的 `RATE_LIMIT_TRUSTED_PROXIES` 和 `MULTICA_TRUSTED_PROXIES` **不是同一个**变量——后者控制的是 autopilot webhook 端点（`/api/webhooks/autopilots/{token}`）的限流器。两个限流器各自读各自的列表，部署在代理后面的实例需要两个都配上。
-
 ## 守护进程的调节参数
 
 守护进程跑在用户本地机器上，配置也是读本地环境变量。常用的几个：
@@ -174,22 +135,6 @@ 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`。
@@ -203,6 +148,5 @@ 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

@@ -212,15 +212,13 @@ Changes take effect after restarting the backend / compose stack. The web UI rea
 
 ### File Storage (Optional)
 
-For file uploads and attachments, configure S3 and (optionally) CloudFront:
+For file uploads and attachments, configure S3 and CloudFront:
 
 | Variable | Description |
 |----------|-------------|
-| `S3_BUCKET` | Bucket name only (e.g. `my-bucket`). Do **not** include the `.s3.<region>.amazonaws.com` suffix — the server constructs the public URL from `S3_BUCKET` + `S3_REGION` |
-| `S3_REGION` | AWS region (default: `us-west-2`). Must match the bucket's actual region — used for both SDK signing and public URLs |
-| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | Static credentials. When both are unset, the AWS SDK default credential chain is used |
-| `AWS_ENDPOINT_URL` | Custom S3-compatible endpoint (e.g. MinIO, R2, B2). Setting this switches the public URL to path-style |
-| `CLOUDFRONT_DOMAIN` | CloudFront distribution domain — when set, public URLs use this host instead of the S3 host |
+| `S3_BUCKET` | S3 bucket name |
+| `S3_REGION` | AWS region (default: `us-west-2`) |
+| `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
 | `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
 | `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
 
@@ -337,47 +335,16 @@ 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

@@ -1,183 +0,0 @@
----
-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

@@ -1,183 +0,0 @@
----
-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/guides/agents.zh.mdx

@@ -40,7 +40,7 @@ The daemon auto-detects which CLIs are available on your PATH and registers them
 
 Multica supports two layers of skills:
 
-- **Local skills** — Skills already installed in your local runtime (e.g., `.claude/skills/`, `.opencode/skills/`) are automatically discovered and used by agents. You do **not** need to upload them to Multica.
+- **Local skills** — Skills already installed in your local runtime (e.g., `.claude/skills/`, `.config/opencode/skills/`) are automatically discovered and used by agents. You do **not** need to upload them to Multica.
 - **Workspace skills** — Skills created or imported in the Multica Skills page are shared across the workspace. They are automatically injected into agent runs as supplementary context, so every team member's agents benefit from them.
 
 Workspace skills are designed for team-wide sharing and collaboration — codify your team's best practices once, and every agent can leverage them:

apps/docs/content/docs/install-agent-runtime.mdx

@@ -1,169 +0,0 @@
----
-title: Install an agent runtime
-description: Multica drives whichever AI coding tools you have on your machine. This page shows you how to install each of the 11 supported tools so the daemon can detect them.
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-A **runtime** in Multica is the daemon on your machine paired with one AI coding tool the daemon found on your `PATH`. If the onboarding "Connect a runtime" step shows **No supported tools detected**, it means the daemon scanned `PATH` and didn't find any of the 11 tools it knows how to drive. Install one (or several) of the tools below, then come back to the step and re-scan — the runtime will show up within a few seconds.
-
-This page is the install-side companion to:
-
-- [Daemon and runtimes](/daemon-runtimes) — how detection works
-- [AI coding tools matrix](/providers) — what each tool can and can't do (session resumption, MCP, model selection)
-
-<Callout type="info">
-The Multica server never sees your API keys or the tools themselves. Everything below — installation, authentication, model access — lives on your local machine. If something fails, it's almost always a local problem.
-</Callout>
-
-## Before you start
-
-Two prerequisites apply to **every** tool below:
-
-1. **The Multica daemon must be running.** Either run `multica daemon start` after installing the [Multica CLI](/cli), or use the [Multica desktop app](/desktop-app), which launches the daemon automatically. Without a running daemon there is nothing to detect tools.
-2. **The tool's binary must be reachable on `PATH`.** The daemon shells out to each tool by name (see the **Daemon looks for** column in each section). If `which <name>` doesn't find it in your terminal, the daemon won't find it either. After installing, open a fresh terminal (or restart the daemon) so the new `PATH` entry is picked up.
-
-After installing a tool, restart the daemon:
-
-```bash
-multica daemon restart
-```
-
-Or, in the desktop app, just relaunch the app. The daemon re-scans `PATH` on every start.
-
-## The 11 supported tools
-
-Listed roughly from most to least common. Pick whichever ones you already have credentials for — you don't need all 11.
-
-### Claude Code (Anthropic)
-
-The most complete integration. Session resumption works, MCP works, and it's the **only one of the 11 that actually consumes the `mcp_config` field** on agents (see the [matrix](/providers#mcp-configuration-only-claude-code-actually-reads-it)).
-
-| | |
-|---|---|
-| Daemon looks for | `claude` |
-| Install | Follow the official guide at [claude.com/claude-code](https://www.claude.com/claude-code). The standard route is the npm package `@anthropic-ai/claude-code` (Node.js 18+ required). |
-| Authentication | Run `claude` once and follow the in-CLI login flow, or set `ANTHROPIC_API_KEY`. |
-| Notes | First-choice recommendation for new users. |
-
-### Codex (OpenAI)
-
-JSON-RPC 2.0 transport with finer-grained approval gates. **Session resumption code exists but is currently unreachable** — pick Claude Code or one of the ACP family if you need resume.
-
-| | |
-|---|---|
-| Daemon looks for | `codex` |
-| Install | Follow the official guide at [github.com/openai/codex](https://github.com/openai/codex). The standard route is the npm package `@openai/codex`. |
-| Authentication | `codex login` (browser-based) or `OPENAI_API_KEY`. |
-
-### Cursor (Anysphere)
-
-The CLI counterpart to the Cursor editor. **Session resumption is broken** — Cursor's CLI doesn't return a session id, so the value you pass on resume is always invalid.
-
-| | |
-|---|---|
-| Daemon looks for | `cursor-agent` |
-| Install | Install the [Cursor editor](https://cursor.com/) and then the CLI per their docs at [docs.cursor.com](https://docs.cursor.com/). The binary name is `cursor-agent`, not `cursor`. |
-| Authentication | Sign in through the Cursor editor; the CLI reuses that session. |
-
-### GitHub Copilot
-
-Model routing goes through your GitHub account entitlement — the tool doesn't pick a model itself; GitHub decides which model you get.
-
-| | |
-|---|---|
-| Daemon looks for | `copilot` |
-| Install | See GitHub's CLI docs at [github.com/github/copilot-cli](https://github.com/github/copilot-cli). |
-| Authentication | Browser-based GitHub login through the CLI. |
-| Notes | Requires an active GitHub Copilot subscription on the signed-in account. |
-
-### Gemini (Google)
-
-Supports the Gemini 2.5 and 3 series. No session resumption, no MCP — suitable for one-shot tasks.
-
-| | |
-|---|---|
-| Daemon looks for | `gemini` |
-| Install | Follow the official guide at [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli). The standard route is the npm package `@google/gemini-cli`. |
-| Authentication | `gemini` will prompt for a Google account login, or set `GEMINI_API_KEY`. |
-
-### OpenCode (SST)
-
-Open-source CLI agent. Dynamically discovers available models from its own configuration file — good fit for users who want to bring their own model catalog.
-
-| | |
-|---|---|
-| Daemon looks for | `opencode` |
-| Install | Follow the official guide at [opencode.ai](https://opencode.ai/) or the GitHub repo at [github.com/sst/opencode](https://github.com/sst/opencode). The typical route is the install script or the npm package. |
-| Authentication | Configure your model provider(s) per OpenCode's docs (Anthropic, OpenAI, etc.). |
-
-### Kiro CLI (Amazon)
-
-ACP-over-stdio transport. Session resumption works through ACP `session/load`; skills are copied into `.kiro/skills/`.
-
-| | |
-|---|---|
-| Daemon looks for | `kiro-cli` |
-| Install | See the Kiro docs at [kiro.dev](https://kiro.dev/). The binary name is `kiro-cli`, not `kiro`. |
-| Authentication | AWS-account-based; follow Kiro's own onboarding. |
-
-### Kimi (Moonshot)
-
-ACP-protocol agent, primarily aimed at the Chinese market. Skills live under `.kimi/skills/` (native discovery).
-
-| | |
-|---|---|
-| Daemon looks for | `kimi` |
-| Install | Follow the official guide at [github.com/MoonshotAI/kimi-cli](https://github.com/MoonshotAI/kimi-cli). |
-| Authentication | Moonshot API key, configured per the vendor's docs. |
-
-### Hermes (Nous Research)
-
-ACP-protocol agent (shares the transport with Kimi). Session resumption works. The skill injection path falls back to the generic `.agent_context/skills/` — verify your skills are loading before relying on them.
-
-| | |
-|---|---|
-| Daemon looks for | `hermes` |
-| Install | See Nous Research's repository at [github.com/NousResearch](https://github.com/NousResearch) for the latest CLI distribution. |
-| Authentication | Per the vendor's docs. |
-
-### OpenClaw
-
-Open-source CLI agent orchestrator. **Model is bound at the agent layer** (`openclaw agents add --model`) — it can't be overridden per task, and you can't pass `--model` or `--system-prompt` from Multica.
-
-| | |
-|---|---|
-| Daemon looks for | `openclaw` |
-| Install | See the project at [github.com/openclaw-org/openclaw](https://github.com/openclaw-org/openclaw) (community-maintained). |
-| Authentication | Configure the underlying model provider per OpenClaw's docs. |
-
-### Pi (Inflection AI)
-
-Minimalist. **Session resumption is unusual** — the resume id is the path to a session file on disk, not a string id.
-
-| | |
-|---|---|
-| Daemon looks for | `pi` |
-| Install | See Inflection's CLI docs at [pi.ai](https://pi.ai/). |
-| Authentication | Per the vendor's docs. |
-
-## After installing
-
-1. **Confirm the binary is on `PATH`.** Open a fresh terminal and run `which <name>` (for example `which claude`, `which cursor-agent`, `which kiro-cli`). If it prints a path, the daemon will find it. If it prints nothing, fix your shell `PATH` first (the typical cause is a per-shell rc file that wasn't reloaded).
-2. **Restart the daemon.** `multica daemon restart`, or relaunch the desktop app. The daemon only scans `PATH` at startup.
-3. **Check the Runtimes page.** In the Multica UI, the **Runtimes** page should now list one row per `(workspace × tool)` combination. If the row says "offline", see [Daemon and runtimes → When a runtime is marked offline](/daemon-runtimes#when-a-runtime-is-marked-offline).
-4. **Go back to onboarding.** The "Connect a runtime" step polls and will pick up the new runtime within a few seconds — no need to refresh.
-
-## Troubleshooting
-
-- **`which` finds the binary but the daemon doesn't.** The daemon was started with an older `PATH`. Restart it.
-- **The binary exists but launching fails.** Run the tool's own `--version` or `--help` once from the terminal — most failures here are missing auth, expired tokens, or a Node.js / runtime mismatch.
-- **The Runtimes page shows the row, but tasks fail immediately.** Check `multica daemon logs -f` while triggering a task. The daemon surfaces the tool's own error output.
-
-For broader symptoms, see the [Troubleshooting guide](/troubleshooting).
-
-## Next
-
-- [Daemon and runtimes](/daemon-runtimes) — how detection, heartbeats, and offline handling work
-- [AI coding tools matrix](/providers) — capability differences once a tool is connected
-- [Creating and configuring agents](/agents-create) — pick a tool for your agent and start running tasks

apps/docs/content/docs/install-agent-runtime.zh.mdx

@@ -1,169 +0,0 @@
----
-title: 安装一个 Agent 运行时
-description: Multica 驱动本机上已安装的 AI 编程工具。这一页讲清楚怎么安装目前支持的 11 款工具，让守护进程能扫到。
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-在 Multica 里，一个**运行时**（runtime）就是你机器上的守护进程，配上守护进程在 `PATH` 里扫到的某一款 AI 编程工具。如果 onboarding 的 "连接运行时" 这一步显示 **未检测到支持的工具**，说明守护进程扫了 `PATH`，但 11 款它认得的工具一个都没找到。装下面任意一款（或几款），回到这一步重新扫描，几秒内运行时就会出现。
-
-这一页是装机的入口，和它配套的是：
-
-- [守护进程与运行时](/zh/daemon-runtimes) — 检测是怎么工作的
-- [AI 编程工具矩阵](/zh/providers) — 每款工具的能力差异（会话续接、MCP、模型选择）
-
-<Callout type="info">
-Multica 服务器从不接触你的 API key，也不接触工具本身。下面这些操作 —— 安装、登录、模型访问 —— 全部发生在你本机。出问题几乎都是本地问题。
-</Callout>
-
-## 开始前
-
-下面每一款工具都有两个共同前提：
-
-1. **Multica 守护进程在运行。** 装完 [Multica CLI](/zh/cli) 后跑 `multica daemon start`；或者用 [Multica 桌面端](/zh/desktop-app)，它启动时自动拉起守护进程。守护进程没起来，就没人去扫工具。
-2. **工具的可执行文件在 `PATH` 上。** 守护进程通过名字 shell out 调起工具（见每一节里 **守护进程扫描** 那行的命令名）。终端里 `which <名字>` 找不到，守护进程也找不到。装完后打开新终端（或者重启守护进程），让新的 `PATH` 生效。
-
-装完一款工具后，重启守护进程：
-
-```bash
-multica daemon restart
-```
-
-桌面端的话，重启 app 即可。守护进程只在启动时扫一次 `PATH`。
-
-## 11 款支持的工具
-
-大致按常见程度排序。挑你已经有账号 / API key 的那几款就行 —— 不需要 11 个全装。
-
-### Claude Code（Anthropic）
-
-集成最完整的一款。会话续接好用，MCP 好用，而且 **11 款里只有它真正会读 agent 配置里的 `mcp_config` 字段**（见[矩阵](/zh/providers)）。
-
-| | |
-|---|---|
-| 守护进程扫描 | `claude` |
-| 安装 | 看官方指引 [claude.com/claude-code](https://www.claude.com/claude-code)。常见装法是 npm 包 `@anthropic-ai/claude-code`（需要 Node.js 18+）。 |
-| 认证 | 跑一次 `claude`，跟着 CLI 里的登录流程走；或者设置 `ANTHROPIC_API_KEY`。 |
-| 备注 | 新用户首选。 |
-
-### Codex（OpenAI）
-
-JSON-RPC 2.0 传输，审批粒度更细。**会话续接的代码在，但调不到** —— 要续接的话选 Claude Code 或 ACP 系列。
-
-| | |
-|---|---|
-| 守护进程扫描 | `codex` |
-| 安装 | 看官方指引 [github.com/openai/codex](https://github.com/openai/codex)。常见装法是 npm 包 `@openai/codex`。 |
-| 认证 | `codex login`（浏览器登录），或 `OPENAI_API_KEY`。 |
-
-### Cursor（Anysphere）
-
-Cursor 编辑器的 CLI 对应物。**会话续接是坏的** —— Cursor CLI 不返回 session id，你传过去的续接 id 永远无效。
-
-| | |
-|---|---|
-| 守护进程扫描 | `cursor-agent` |
-| 安装 | 先装 [Cursor 编辑器](https://cursor.com/)，再按 [docs.cursor.com](https://docs.cursor.com/) 的说明装 CLI。可执行文件叫 `cursor-agent`，不是 `cursor`。 |
-| 认证 | 在 Cursor 编辑器里登录，CLI 复用同一份会话。 |
-
-### GitHub Copilot
-
-模型走的是你 GitHub 账号的 entitlement —— 工具自己不挑模型，GitHub 决定你拿到哪个模型。
-
-| | |
-|---|---|
-| 守护进程扫描 | `copilot` |
-| 安装 | 看 GitHub 的 CLI 文档 [github.com/github/copilot-cli](https://github.com/github/copilot-cli)。 |
-| 认证 | CLI 里走 GitHub 浏览器登录。 |
-| 备注 | 登录账号必须有有效的 GitHub Copilot 订阅。 |
-
-### Gemini（Google）
-
-支持 Gemini 2.5 和 3 系列。没有会话续接，没有 MCP —— 适合一次性、无需上下文记忆的任务。
-
-| | |
-|---|---|
-| 守护进程扫描 | `gemini` |
-| 安装 | 看官方指引 [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli)。常见装法是 npm 包 `@google/gemini-cli`。 |
-| 认证 | 跑 `gemini` 会提示 Google 账号登录，或设置 `GEMINI_API_KEY`。 |
-
-### OpenCode（SST）
-
-开源 CLI agent。会从自己的配置文件里动态发现可用模型 —— 适合想自己掌控模型清单的用户。
-
-| | |
-|---|---|
-| 守护进程扫描 | `opencode` |
-| 安装 | 看官方指引 [opencode.ai](https://opencode.ai/) 或仓库 [github.com/sst/opencode](https://github.com/sst/opencode)。一般是装脚本或 npm 包。 |
-| 认证 | 按 OpenCode 的文档配你自己的模型供应商（Anthropic、OpenAI 等）。 |
-
-### Kiro CLI（Amazon）
-
-ACP-over-stdio 传输。会话续接通过 ACP `session/load` 工作；skills 拷到 `.kiro/skills/`。
-
-| | |
-|---|---|
-| 守护进程扫描 | `kiro-cli` |
-| 安装 | 看 Kiro 的文档 [kiro.dev](https://kiro.dev/)。可执行文件叫 `kiro-cli`，不是 `kiro`。 |
-| 认证 | 基于 AWS 账号，按 Kiro 自己的引导走。 |
-
-### Kimi（Moonshot）
-
-ACP 协议 agent，主要面向中国市场。Skills 放在 `.kimi/skills/`（原生发现路径）。
-
-| | |
-|---|---|
-| 守护进程扫描 | `kimi` |
-| 安装 | 看官方指引 [github.com/MoonshotAI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)。 |
-| 认证 | Moonshot API key，按厂商文档配置。 |
-
-### Hermes（Nous Research）
-
-ACP 协议 agent（和 Kimi 共享传输层）。会话续接可用。Skill 注入用的是通用回退路径 `.agent_context/skills/` —— 用之前先验证 skills 真的被加载了。
-
-| | |
-|---|---|
-| 守护进程扫描 | `hermes` |
-| 安装 | 看 Nous Research 的仓库 [github.com/NousResearch](https://github.com/NousResearch) 获取最新 CLI。 |
-| 认证 | 按厂商文档。 |
-
-### OpenClaw
-
-开源 CLI agent 编排器。**模型绑在 agent 层**（`openclaw agents add --model`）—— 不能按任务覆盖，从 Multica 也传不了 `--model` / `--system-prompt`。
-
-| | |
-|---|---|
-| 守护进程扫描 | `openclaw` |
-| 安装 | 看项目 [github.com/openclaw-org/openclaw](https://github.com/openclaw-org/openclaw)（社区维护）。 |
-| 认证 | 按 OpenClaw 的文档配底层模型供应商。 |
-
-### Pi（Inflection AI）
-
-极简风格。**会话续接的方式不太一样** —— resume id 是磁盘上的会话文件路径，不是字符串 id。
-
-| | |
-|---|---|
-| 守护进程扫描 | `pi` |
-| 安装 | 看 Inflection 的 CLI 文档 [pi.ai](https://pi.ai/)。 |
-| 认证 | 按厂商文档。 |
-
-## 装完之后
-
-1. **确认可执行文件在 `PATH` 上。** 开一个新终端，跑 `which <名字>`（比如 `which claude`、`which cursor-agent`、`which kiro-cli`）。打印出路径，守护进程就找得到；什么都不打印，先修 shell 的 `PATH`（最常见原因是 rc 文件没重新加载）。
-2. **重启守护进程。** `multica daemon restart`，或者重启桌面端。守护进程只在启动时扫一次 `PATH`。
-3. **看 Runtimes 页面。** Multica UI 的 **Runtimes** 页应该会出现一行 `(工作区 × 工具)`。如果显示 "offline"，看[守护进程与运行时 → 运行时何时被标记为离线](/zh/daemon-runtimes#运行时何时被标记为离线)。
-4. **回到 onboarding。** "连接运行时" 这一步会一直轮询，几秒内就能扫到新运行时，不需要手动刷新。
-
-## 排错
-
-- **`which` 找得到，但守护进程找不到。** 守护进程是用旧 `PATH` 启的，重启它。
-- **可执行文件在，但启动就失败。** 在终端单独跑一次工具的 `--version` 或 `--help`，绝大多数失败都是登录没做、token 过期、Node.js / 运行时版本不对。
-- **Runtimes 页面看到行，但任务一跑就失败。** 一边触发任务一边跑 `multica daemon logs -f`。守护进程会把工具自己的报错原样吐出来。
-
-更宽的症状看[排错指南](/zh/troubleshooting)。
-
-## 接下来
-
-- [守护进程与运行时](/zh/daemon-runtimes) — 检测、心跳、离线处理
-- [AI 编程工具矩阵](/zh/providers) — 工具连上之后的能力差异
-- [创建并配置智能体](/zh/agents-create) — 给你的 agent 挑一款工具，开始跑任务

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

@@ -16,10 +16,6 @@ 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:
@@ -57,7 +53,6 @@ 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,10 +16,6 @@ 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>
-
 ## 和分配的差别
 
 同样是让智能体工作，但机制完全不同：
@@ -57,7 +53,6 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 ## 下一步
 
-- [**小队**](/squads) —— `@` 一个小队，由队长把问题派给合适的成员
 - [**对话**](/chat) —— 脱离 issue 和智能体一对一聊
 - [**Autopilots**](/autopilots) —— 让智能体定时自动开工
 - [**评论**](/comments) —— `@mention` 的语法、picker、`@all` 的语义

apps/docs/content/docs/meta.json

@@ -9,17 +9,13 @@
     "workspaces",
     "members-roles",
     "issues",
-    "projects",
     "comments",
-    "project-resources",
     "---Agents---",
     "agents",
     "agents-create",
     "skills",
-    "squads",
     "---How agents run---",
     "daemon-runtimes",
-    "install-agent-runtime",
     "tasks",
     "providers",
     "---Collaborating with agents---",
@@ -29,8 +25,6 @@
     "autopilots",
     "---Inbox---",
     "inbox",
-    "---Integrations---",
-    "github-integration",
     "---Self-hosting & ops---",
     "environment-variables",
     "auth-setup",
@@ -38,8 +32,6 @@
     "---Reference---",
     "cli",
     "auth-tokens",
-    "desktop-app",
-    "---Developers---",
-    "developers"
+    "desktop-app"
   ]
 }

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

@@ -9,13 +9,11 @@
     "workspaces",
     "members-roles",
     "issues",
-    "projects",
     "comments",
     "---智能体---",
     "agents",
     "agents-create",
     "skills",
-    "squads",
     "---智能体怎么运行---",
     "daemon-runtimes",
     "tasks",
@@ -27,8 +25,6 @@
     "autopilots",
     "---收件箱---",
     "inbox",
-    "---集成---",
-    "github-integration",
     "---自部署运维---",
     "environment-variables",
     "auth-setup",
@@ -36,8 +32,6 @@
     "---参考---",
     "cli",
     "auth-tokens",
-    "desktop-app",
-    "---开发者---",
-    "developers"
+    "desktop-app"
   ]
 }

apps/docs/content/docs/project-resources.mdx

@@ -1,144 +0,0 @@
----
-title: Project Resources
-description: Attach typed pointers (Git repos today, more later) to a project so agents can pick them up as scoped context.
----
-
-A **Project Resource** is a typed pointer — a Git repo URL today, a Notion page or document link tomorrow — attached to a [project](/workspaces). When an [agent](/agents) runs against an issue inside that project, the daemon automatically writes the project's resource list into the agent's working directory and into its [meta-skill](/skills) prompt.
-
-The result: the agent knows which repo to check out, which docs are the "primary references" for this project, without anyone copy-pasting context into the issue body.
-
-## Mental model
-
-A project is no longer just a label. It is a small **resource container**:
-
-- A project has 0..N **resources**.
-- A resource has a `resource_type` (e.g. `github_repo`) and a `resource_ref` (a JSON payload typed by `resource_type`).
-- New resource types add a string + a handler. **No schema migration. No frontend rewrite.**
-
-This shape is intentional — it's the same pattern Multica already uses for agent providers: a `type` discriminator and a typed payload. It keeps the schema stable so adding "Notion page", "Google Doc", "uploaded file", or "external URL" later is a small, additive change.
-
-## Today: `github_repo`
-
-The first resource type ships ready to use:
-
-```json
-{
-  "resource_type": "github_repo",
-  "resource_ref": {
-    "url": "https://github.com/owner/repo",
-    "default_branch_hint": "main"
-  }
-}
-```
-
-`default_branch_hint` is optional — if present, the daemon surfaces it in the meta-skill so the agent knows which branch to base its work on.
-
-## Attaching repos at project creation
-
-In the **Web** or **Desktop** app, opening *New project* now shows a **Repos** pill alongside Status / Priority / Lead. Selecting workspace-bound repos (or pasting an ad-hoc URL) attaches them as `github_repo` resources the moment the project is created.
-
-From the **CLI**:
-
-```bash
-# Create + attach in one shot. The server attaches resources in the same
-# transaction as the project create — invalid resources roll back the whole
-# operation, so you never end up with a project that has half its resources.
-multica project create \
-  --title "Agent UX 2026" \
-  --repo https://github.com/multica-ai/multica
-
-# Manage resources later
-multica project resource list <project-id>
-multica project resource add  <project-id> --type github_repo --url <url>
-multica project resource remove <project-id> <resource-id>
-
-# Generic escape hatch for any resource_type the server understands —
-# no CLI change needed when a new type ships:
-multica project resource add <project-id> \
-  --type notion_page \
-  --ref '{"page_id":"…","title":"…"}'
-```
-
-`--repo` may be repeated; each value is attached as a separate `github_repo` resource.
-
-## What the agent sees at runtime
-
-When the daemon spawns an agent for an issue inside a project, two things happen:
-
-### 1. `.multica/project/resources.json`
-
-A structured pass-through of the API response, written into the agent's working directory:
-
-```json
-{
-  "project_id": "…",
-  "project_title": "Agent UX 2026",
-  "resources": [
-    {
-      "id": "…",
-      "resource_type": "github_repo",
-      "resource_ref": {
-        "url": "https://github.com/multica-ai/multica",
-        "default_branch_hint": "main"
-      }
-    }
-  ]
-}
-```
-
-Skills, helper scripts, or the agent itself can parse this file when they need the *exact* set of resources for the run.
-
-### 2. A "Project Context" section in the meta-skill prompt
-
-The agent's `CLAUDE.md` / `AGENTS.md` (depending on provider) now includes a human-readable summary:
-
-```
-## Project Context
-
-This issue belongs to **Agent UX 2026**.
-
-Project resources (also written to `.multica/project/resources.json`):
-
-- **GitHub repo**: https://github.com/multica-ai/multica (default branch: `main`)
-
-Resources are pointers — open them only when relevant to the task. For
-`github_repo` resources, use `multica repo checkout <url>` to fetch the code.
-```
-
-The text is intentionally minimal. The full payload is on disk; the prompt only orients the agent so it knows the project exists and what's attached.
-
-### Failure mode
-
-Resource fetch is **best-effort**. If the API call fails, the project section is omitted from the prompt and the file is not written, but the task still starts. Agents never block on missing project context.
-
-## Adding a new resource type
-
-The whole point of the abstraction is that new types are cheap. The full path:
-
-1. **Server validator** (`server/internal/handler/project_resource.go`) — add a case in `validateAndNormalizeResourceRef` that parses and normalizes the new payload.
-2. **Daemon meta-skill formatter** (`server/internal/daemon/execenv/runtime_config.go`) — add a case in `formatProjectResource` so the agent prompt renders the new type as a readable bullet.
-3. **TypeScript types** (`packages/core/types/project.ts`) — extend `ProjectResourceType` and add the payload interface.
-4. **UI renderer** (`packages/views/projects/components/project-resources-section.tsx`) — add a case in `ResourceRow` for the new type.
-
-There is **no schema migration**, no new sqlc query, no new endpoint, **and no CLI change** — the CLI's generic `--ref '<json>'` flag accepts any payload the validator understands, so day-one support for a new type is purely the four steps above. (You may *optionally* add a per-type CLI shortcut later; not required.)
-
-The same `project_resource` table and the same three CRUD calls handle every type.
-
-## Workspace repos vs. project repos
-
-The repo list shown to the agent (`## Repositories` block in `CLAUDE.md` / `AGENTS.md`) is chosen by the daemon claim handler with this precedence:
-
-- **Project has at least one `github_repo` resource** → only those repos are surfaced to the agent. Workspace-bound repos are intentionally hidden so the agent doesn't have to guess which one belongs to this issue.
-- **Project has no `github_repo` resources (or the issue isn't in a project)** → fall back to the workspace's repo list as before.
-
-This keeps the agent's working set tight: when a project is explicit about its repos, that's the authoritative answer. The structured resource list at `.multica/project/resources.json` always carries the full set, so a skill that wants to inspect everything still can.
-
-The daemon mirrors this on the checkout side: when a task arrives with project-scoped `github_repo` URLs, those URLs are merged into the per-workspace allowlist *and* synced into the local repo cache before the agent spawns. So a project repo URL that isn't bound at the workspace level is still a valid argument to `multica repo checkout` — the daemon won't reject it as "not configured." The allowlist split is internal: workspace-bound URLs and task-scoped URLs are tracked separately, so a workspace-repos refresh doesn't accidentally revoke a project URL mid-run.
-
-## What's intentionally **not** in scope here
-
-- **Cross-project sharing.** Each resource lives on exactly one project today.
-- **Per-skill resource scoping.** All resources are visible to every skill on the agent's run; type-aware filtering is a follow-up.
-- **Caching / sync.** `github_repo` is just metadata — checkout still happens via `multica repo checkout` on demand. Cached document text for Notion / Google Docs will arrive with those types.
-
-These are deliberate omissions — the goal of the first cut is to validate the abstraction with the smallest set of moving parts.

apps/docs/content/docs/projects.mdx

@@ -1,49 +0,0 @@
----
-title: Projects
-description: Group related issues and track them as one unit — with priority, status, progress, and an owner.
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-A **project** in Multica is a container for related [issues](/issues). Use it when a body of work is bigger than one issue but smaller than a full workspace — a launch, a migration, a feature with multiple parts, an investigation that branches into several threads.
-
-Each project has a name, an icon, a description, a **lead** (a member or an [agent](/agents)), a **status** (`planned` / `in_progress` / `paused` / `completed` / `cancelled`), a **priority** (`urgent` / `high` / `medium` / `low` / `none`), and a **progress** percentage that's auto-derived from the status of its linked issues.
-
-## How projects relate to issues
-
-Projects and issues are independent objects with a many-to-one relationship: an issue can belong to **at most one** project; a project holds **any number of** issues. Linking and unlinking is reversible at any time — drag in the board view, or use the project picker on the issue's right-side properties panel.
-
-The progress bar on a project is computed from its linked issues — the more issues hit `done`, the further it fills. Issues that are `cancelled` are excluded from the count; issues in `backlog` count toward the denominator but not the numerator.
-
-## Pinning to the sidebar
-
-Click the pin icon in a project's top-right corner to add it to your sidebar's pinned list. Pinned projects stay one click away no matter where you are in the workspace; everyone on the team can pin independently — pins are personal.
-
-The sidebar **Workspace → Projects** link always shows every project in the workspace; pinning is a personal shortcut on top of that.
-
-## Attaching resources
-
-Each project has a **Resources** section where you attach GitHub repositories. Once attached, any [agent](/agents) assigned to issues in this project can read and write to those repos when executing tasks — Multica passes the repo URLs as context to the [daemon](/daemon-runtimes).
-
-Resources are per-project; if multiple projects share a repo, attach it to each one.
-
-## Deleting a project
-
-Deleting a project **does not delete its issues**. The linked issues are simply unlinked and revert to the workspace's flat issue list. This is intentional — work that was scoped to a project is rarely throwaway, even when the framing of the project changes.
-
-<Callout type="info">
-If you want to delete the work too, archive or delete the issues first, then delete the project.
-</Callout>
-
-## Project lead
-
-The lead is the person — or agent — accountable for the project. It's a soft signal, not an access control: any workspace member can edit a project regardless of who's lead. A project's lead can be:
-
-- A workspace member (human teammate)
-- An [agent](/agents) — useful when the project's work is mostly delegated to an agent (e.g., "Weekly bug triage" led by a triage agent)
-
-## Next
-
-- [Issues](/issues) — the unit of work that lives inside projects
-- [Agents as project lead](/agents) — when an agent is the right owner
-- [How Multica works](/how-multica-works) — the broader picture

apps/docs/content/docs/projects.zh.mdx

@@ -1,49 +0,0 @@
----
-title: 项目
-description: 把相关的 issue 归为一组当成一个单元来跟进 —— 有优先级、状态、进度和负责人。
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-Multica 里的**项目**（project）是相关 [issue](/issues) 的容器。当一摊工作比单个 issue 大、又比整个工作区小的时候用它 —— 一次发布、一次迁移、一个分多块做的功能、一个会拆出多个线索的调研。
-
-每个项目有名字、图标、描述、**负责人**（lead，可以是成员，也可以是 [智能体](/agents)）、**状态**（`planned` / `in_progress` / `paused` / `completed` / `cancelled`）、**优先级**（`urgent` / `high` / `medium` / `low` / `none`），以及一个根据关联 issue 状态自动算出来的**进度**百分比。
-
-## 项目和 issue 的关系
-
-项目和 issue 是独立对象，多对一关系：一个 issue **最多属于一个**项目；一个项目可以容纳**任意多个** issue。关联和解除关联随时可逆 —— 在看板视图里拖动，或者在 issue 右侧 properties 面板用项目选择器。
-
-项目的进度条是按关联 issue 状态自动算出来的 —— 越多 issue 到 `done`，进度条越满。`cancelled` 的 issue 不计入分母；`backlog` 的 issue 计入分母但不计入分子。
-
-## pin 到侧边栏
-
-点项目右上角的 pin 图标，可以把这个项目加到侧边栏的固定区。pin 过的项目无论你在工作区哪里都一键可达；每个人独立 pin —— pin 是个人偏好。
-
-侧边栏 **Workspace → Projects** 链接始终展示工作区里所有项目；pin 只是在这之上的个人快捷方式。
-
-## 关联 resources
-
-每个项目有一个 **Resources** 区，可以挂 GitHub 仓库。挂上之后，被分配到这个项目里 issue 的 [智能体](/agents) 在执行 task 时可以读写这些仓库 —— Multica 会把仓库 URL 作为上下文传给 [守护进程](/daemon-runtimes)。
-
-Resources 是项目级别的；多个项目要共享同一个仓库，要分别挂上。
-
-## 删除项目
-
-删除项目**不会**删除它的 issue。关联的 issue 只是解除关联，回到工作区的扁平 issue 列表。这是刻意的 —— 即使项目本身的框架变了，里面的工作通常也不会是一次性的。
-
-<Callout type="info">
-如果你确实想把工作也删掉，先归档或删除 issue，再删除项目。
-</Callout>
-
-## 项目负责人
-
-负责人是为这个项目负总责的人 —— 或者智能体。这是一个软信号，不是权限控制：工作区任何成员都可以编辑项目，不管谁是负责人。项目负责人可以是：
-
-- 工作区里的成员（人）
-- [智能体](/agents) —— 当项目里的工作大部分要交给智能体时合适（例如"每周 bug 巡检"由一个巡检智能体担任 lead）
-
-## 下一步
-
-- [Issues](/issues) —— 项目里装的工作单元
-- [智能体担任项目负责人](/agents) —— 什么时候由智能体当 lead 合适
-- [Multica 怎么运转](/how-multica-works) —— 整体视图

apps/docs/content/docs/providers.mdx

@@ -21,7 +21,7 @@ For guidance on picking a tool when creating an agent, see [Creating and configu
 | **Hermes** | Nous Research | ✅ | ❌ | `.agent_context/skills/` (fallback) | Dynamic discovery |
 | **Kimi** | Moonshot | ✅ | ❌ | `.kimi/skills/` | Dynamic discovery |
 | **Kiro CLI** | Amazon | ✅ | ❌ | `.kiro/skills/` | Dynamic discovery |
-| **OpenCode** | SST | ✅ | ❌ | `.opencode/skills/` | Dynamic discovery |
+| **OpenCode** | SST | ✅ | ❌ | `.config/opencode/skills/` | Dynamic discovery |
 | **OpenClaw** | Open source | ✅ | ❌ | `.agent_context/skills/` (fallback) | Bound to the agent, can't be switched per task |
 | **Pi** | Inflection AI | ✅ (session is a file path) | ❌ | `.pi/skills/` | Dynamic discovery |
 
@@ -103,7 +103,7 @@ Each tool uses **its own** skill discovery path. Before a task runs, the Multica
 | Cursor | `.cursor/skills/` | ✅ Native |
 | Kimi | `.kimi/skills/` | ✅ Native |
 | Kiro CLI | `.kiro/skills/` | ✅ Native |
-| OpenCode | `.opencode/skills/` | ✅ Native |
+| OpenCode | `.config/opencode/skills/` | ✅ Native |
 | Pi | `.pi/skills/` | ✅ Native |
 | Gemini | `.agent_context/skills/` | ⚠️ Generic fallback |
 | Hermes | `.agent_context/skills/` | ⚠️ Generic fallback |

apps/docs/content/docs/providers.zh.mdx

@@ -21,7 +21,7 @@ Multica 内置支持 **11 款 AI 编程工具**。它们都实现了同一套接
 | **Hermes** | Nous Research | ✅ | ❌ | `.agent_context/skills/` （fallback）| 动态发现 |
 | **Kimi** | Moonshot | ✅ | ❌ | `.kimi/skills/` | 动态发现 |
 | **Kiro CLI** | Amazon | ✅ | ❌ | `.kiro/skills/` | 动态发现 |
-| **OpenCode** | SST | ✅ | ❌ | `.opencode/skills/` | 动态发现 |
+| **OpenCode** | SST | ✅ | ❌ | `.config/opencode/skills/` | 动态发现 |
 | **OpenClaw** | 开源项目 | ✅ | ❌ | `.agent_context/skills/` （fallback）| 绑定在智能体上，不能在任务里切换 |
 | **Pi** | Inflection AI | ✅（session 为文件路径）| ❌ | `.pi/skills/` | 动态发现 |
 
@@ -103,7 +103,7 @@ Inflection AI 出品，极简主义。**会话恢复机制特殊**——session
 | Cursor | `.cursor/skills/` | ✅ 原生 |
 | Kimi | `.kimi/skills/` | ✅ 原生 |
 | Kiro CLI | `.kiro/skills/` | ✅ 原生 |
-| OpenCode | `.opencode/skills/` | ✅ 原生 |
+| OpenCode | `.config/opencode/skills/` | ✅ 原生 |
 | Pi | `.pi/skills/` | ✅ 原生 |
 | Gemini | `.agent_context/skills/` | ⚠️ 通用 fallback |
 | Hermes | `.agent_context/skills/` | ⚠️ 通用 fallback |

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

@@ -45,10 +45,6 @@ Once it's up:
 - **Frontend**: [http://localhost:3000](http://localhost:3000)
 - **Backend**: [http://localhost:8080](http://localhost:8080)
 
-<Callout type="info">
-**Ports listen on `127.0.0.1` only.** `docker-compose.selfhost.yml` binds every published port to loopback — `ss -tlnp` will not show `0.0.0.0:8080`, and the services are unreachable from other machines by design. The default `JWT_SECRET` and Postgres credentials must never sit on the open internet. For cross-machine access, front the stack with a reverse proxy that terminates TLS — see [Step 5b — Cross-machine: front with a reverse proxy](#5b-cross-machine-front-with-a-reverse-proxy).
-</Callout>
-
 ## 2. Important: keep production safety on
 
 <Callout type="warning">
@@ -63,9 +59,7 @@ Before any public deployment, make sure `.env` has `APP_ENV=production` and `MUL
 
 Without email configured, your users can't receive verification codes by email; the server prints generated codes to stdout instead.
 
-Two delivery backends are supported — pick whichever fits your network:
-
-**Option A — Resend (cloud / public-internet deployments):**
+To actually send verification emails:
 
 1. Sign up at [Resend](https://resend.com/) and get an API key
 2. Verify a sending domain you control
@@ -76,80 +70,36 @@ Two delivery backends are supported — pick whichever fits your network:
     RESEND_FROM_EMAIL=noreply@yourdomain.com
     ```
 
-**Option B — SMTP relay (internal networks / on-premise):**
+4. Restart: `docker compose -f docker-compose.selfhost.yml restart backend`
 
-Use this when the deployment can't reach `api.resend.com`, or you already have an internal mail relay (Exchange, Postfix, on-prem SendGrid, etc.). `SMTP_HOST` takes priority over Resend when both are set.
-
-```bash
-SMTP_HOST=smtp.internal.example.com
-SMTP_PORT=587                  # default 25; use 587 for STARTTLS submission
-SMTP_USERNAME=multica          # leave empty for unauthenticated relay
-SMTP_PASSWORD=...
-RESEND_FROM_EMAIL=noreply@yourdomain.com  # reused as the From: header
-```
-
-Then restart: `docker compose -f docker-compose.selfhost.yml restart backend`.
-
-For more auth configuration (OAuth, signup allowlist) and the full SMTP variable reference, see [Auth setup](/auth-setup) and [Environment variables → Email](/environment-variables#email-configuration).
+For more auth configuration (OAuth, signup allowlist), see [Auth setup](/auth-setup).
 
 ## 4. First login + create a workspace
 
 Open [http://localhost:3000](http://localhost:3000):
 
 - Enter your email
-- Grab the verification code from your configured email backend (Resend or SMTP relay); if neither is configured, copy it from the server container stdout — look for the `[DEV] Verification code` line
+- Grab the verification code from the Resend email (or, if you haven't configured Resend, from the server container stdout — look for the `[DEV] Verification code` line)
 - Do not use `888888` unless you explicitly set `MULTICA_DEV_VERIFICATION_CODE=888888` on a non-production private instance
 - Log in and create your first workspace
 
 ## 5. Point the CLI at your own server
 
-The CLI install is the same as in [Cloud quickstart → 2. Install the CLI](/cloud-quickstart#2-install-the-multica-cli) — Homebrew / script / PowerShell, pick one.
+The CLI install is the same as in [Cloud quickstart → 2. Install the CLI](/cloud-quickstart#2-install-the-multica-cli) — Homebrew / script / PowerShell, pick one. Once installed, **use the self-host variant of the setup command**:
 
-### 5a. Same machine
+```bash
+multica setup self-host --server-url http://<your-server-address>:8080 --app-url http://<your-server-address>:3000
+```
 
-If the CLI and the server run on the same host, the defaults already work:
+If you're running everything on one local machine:
 
 ```bash
 multica setup self-host
 ```
 
-That points the CLI at `http://localhost:8080` (backend) and `http://localhost:3000` (frontend), takes you through browser login, stores the PAT locally, and **starts the daemon automatically**.
+That defaults to `http://localhost:8080` (backend) and `http://localhost:3000` (frontend).
 
-### 5b. Cross-machine: front with a reverse proxy
-
-Because the compose stack only listens on `127.0.0.1`, a daemon on a different machine cannot reach `http://<server-ip>:8080` directly — and you do not want it to, since the default `JWT_SECRET` would otherwise be reachable from the open internet. Put a reverse proxy on the server that terminates TLS and forwards to `127.0.0.1:8080` (backend) and `127.0.0.1:3000` (frontend), then point the CLI at the public HTTPS URL:
-
-```bash
-multica setup self-host \
-  --server-url https://<your-domain> \
-  --app-url https://<your-domain>
-```
-
-A minimal Caddyfile that fronts both the frontend and the backend (with WebSocket support, which the daemon and the web app both need) on a single hostname:
-
-```nginx
-multica.example.com {
-    # WebSocket route — must come before the catch-all
-    @ws path /ws /ws/*
-    handle @ws {
-        reverse_proxy 127.0.0.1:8080 {
-            flush_interval -1
-        }
-    }
-
-    # Backend API
-    handle /api/* {
-        reverse_proxy 127.0.0.1:8080
-    }
-
-    # Everything else → frontend
-    reverse_proxy 127.0.0.1:3000
-}
-```
-
-After bringing the proxy up, set `FRONTEND_ORIGIN=https://multica.example.com` in the server's `.env` and restart the backend — otherwise the WebSocket origin check will reject the browser ([Troubleshooting → WebSocket can't connect](/troubleshooting#websocket-cant-connect)).
-
-[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) is another solid option — it gives you TLS and a public hostname without exposing any port on the host at all. An Nginx equivalent (separate `app.` / `api.` hostnames, `proxy_set_header Upgrade` for WebSockets) works just as well; the key requirements are TLS termination and forwarding the `Upgrade` header on `/ws`.
+`setup self-host` takes you through browser login, stores the PAT locally, and **starts the daemon automatically**.
 
 ## 6. Create an agent + assign your first task
 
@@ -158,13 +108,12 @@ Same flow as Cloud — see [Cloud quickstart → Steps 5-6](/cloud-quickstart#5-
 ## Common issues
 
 - **Backend won't start**: check container logs with `docker compose -f docker-compose.selfhost.yml logs backend`; usually it's a bad `DATABASE_URL` or `JWT_SECRET` in `.env`
-- **Verification code not received**: no email backend is configured (neither Resend nor SMTP) → look for `[DEV] Verification code` in `docker compose logs backend`
+- **Verification code not received**: Resend isn't configured → look for `[DEV] Verification code` in `docker compose logs backend`
 - **WebSocket won't connect**: for public deployments you must set `FRONTEND_ORIGIN` to your real frontend domain; see [Troubleshooting → WebSocket won't connect](/troubleshooting#websocket-wont-connect)
 
 ## Next steps
 
 - [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
+- [Desktop app](/desktop-app) — released Desktop builds connect to Multica Cloud only; using Desktop with self-host requires a custom build (see the callout in the desktop-app page)