fix(quick-create): remove duplicate keyboard shortcut on agent submit button

The agent submit button rendered the shortcut hint twice — the i18n
string already contained '(⌘↵)' and the JSX appended another
formatShortcut() suffix. Drop the hardcoded shortcut from the
translations and rely on the platform-aware formatShortcut() in JSX.

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

.env.example

@@ -63,6 +63,9 @@ 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=

CLAUDE.md

@@ -2,6 +2,21 @@
 
 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.

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
+multica login --token <mul_...>
 ```
 
-Authenticate by pasting a personal access token directly. Useful for headless environments.
+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).
 
 ### Check Status
 
@@ -140,6 +140,7 @@ 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 |
@@ -174,6 +175,22 @@ 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:
 
@@ -181,8 +198,12 @@ Agent-specific overrides:
 |----------|-------------|
 | `MULTICA_CLAUDE_PATH` | Custom path to the `claude` binary |
 | `MULTICA_CLAUDE_MODEL` | Override the Claude model used |
+| `MULTICA_CLAUDE_ARGS` | Default extra arguments for Claude Code runs |
 | `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 |
@@ -200,6 +221,8 @@ Agent-specific overrides:
 | `MULTICA_KIRO_PATH` | Custom path to the `kiro-cli` binary |
 | `MULTICA_KIRO_MODEL` | Override the Kiro model used |
 
+`MULTICA_CLAUDE_ARGS` and `MULTICA_CODEX_ARGS` are parsed with POSIX shellword quoting, so values such as `--model "gpt-5.1 codex" --sandbox read-only` are split like a shell command line. Agent arguments are applied in this order: hardcoded Multica defaults, daemon-wide env defaults, then per-agent `custom_args` from the task.
+
 ### Self-Hosted Server
 
 When connecting to a self-hosted Multica instance, the easiest approach is:
@@ -282,10 +305,11 @@ 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 --limit 20 --output json
 ```
 
-Available filters: `--status`, `--priority`, `--assignee`, `--project`, `--limit`.
+Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--limit`. Use `--assignee-id <uuid>` for unambiguous filtering when names overlap.
 
 ### Get Issue
 
@@ -298,9 +322,10 @@ 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`, `--parent`, `--project`, `--due-date`.
+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`.
 
 ### Update Issue
 
@@ -312,9 +337,12 @@ 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

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`
+- 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 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`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, `cursor-agent`).
+Expected output should show `running` status with detected agents (e.g. `claude`, `codex`, `copilot`, `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`, `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`, `copilot`, `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`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`)
+2. At least one agent is listed (e.g. `claude`, `codex`, `copilot`, `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`, `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`, `copilot`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`), then restart the daemon with `multica daemon stop && multica daemon start`."
 
 ---
 

README.md

@@ -30,12 +30,24 @@ 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**, **OpenClaw**, **OpenCode**, **Hermes**, **Gemini**, **Pi**, **Cursor Agent**, **Kimi**, and **Kiro CLI**.
+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**.
 
 <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.
@@ -98,7 +110,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`, `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`, `copilot`, `openclaw`, `opencode`, `hermes`, `gemini`, `pi`, `cursor-agent`, `kimi`, `kiro-cli`) on your PATH.
 
 ### 2. Verify your runtime
 
@@ -108,7 +120,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, 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, 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.
 
 ### 4. Assign your first task
 
@@ -160,10 +172,9 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
                             │
                      ┌──────┴───────┐
                      │ Agent Daemon │  runs on your machine
-                     └──────────────┘  (Claude Code, Codex, OpenCode,
-                                        OpenClaw, Hermes, Gemini,
-                                        Pi, Cursor Agent, Kimi,
-                                        Kiro CLI)
+                     └──────────────┘  (Claude Code, Codex, GitHub Copilot CLI,
+                                        OpenCode, OpenClaw, Hermes, Gemini,
+                                        Pi, Cursor Agent, Kimi, Kiro CLI)
 ```
 
 | Layer | Stack |
@@ -171,7 +182,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, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, or Kiro CLI |
+| Agent Runtime | Local daemon executing Claude Code, Codex, GitHub Copilot CLI, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, or Kiro CLI |
 
 ## Development
 

README.zh-CN.md

@@ -30,12 +30,24 @@
 
 Multica 将编码 Agent 变成真正的队友。像分配给同事一样分配给 Agent——它们会自主接手工作、编写代码、报告阻塞问题、更新状态。
 
-不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**OpenClaw**、**OpenCode**、**Hermes**、**Gemini**、**Pi** 和 **Cursor Agent**。
+不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**GitHub Copilot CLI**、**OpenClaw**、**OpenCode**、**Hermes**、**Gemini**、**Pi**、**Cursor Agent**、**Kimi** 和 **Kiro CLI**。
 
 <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 生命周期：从任务分配到执行监控再到技能复用。
@@ -99,7 +111,7 @@ multica setup          # 连接 Multica Cloud，登录，启动 daemon
 multica setup           # 配置、认证、启动 daemon（一条命令搞定）
 ```
 
-daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`openclaw`、`opencode`、`hermes`、`gemini`、`pi`、`cursor-agent`）。
+daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`copilot`、`openclaw`、`opencode`、`hermes`、`gemini`、`pi`、`cursor-agent`、`kimi`、`kiro-cli`）。
 
 ### 2. 确认运行时已连接
 
@@ -109,7 +121,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 
 ### 3. 创建 Agent
 
-进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、OpenClaw、OpenCode、Hermes、Gemini、Pi 或 Cursor Agent），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
+进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、GitHub Copilot CLI、OpenClaw、OpenCode、Hermes、Gemini、Pi、Cursor Agent、Kimi 或 Kiro CLI），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
 
 ### 4. 分配你的第一个任务
 
@@ -142,9 +154,9 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
                             │
                      ┌──────┴───────┐
                      │ Agent Daemon │  运行在你的机器上
-                     └──────────────┘  （Claude Code、Codex、OpenCode、
-                                        OpenClaw、Hermes、Gemini、
-                                        Pi、Cursor Agent）
+                     └──────────────┘  （Claude Code、Codex、GitHub Copilot CLI、
+                                        OpenCode、OpenClaw、Hermes、Gemini、
+                                        Pi、Cursor Agent、Kimi、Kiro CLI）
 ```
 
 | 层级 | 技术栈 |
@@ -152,7 +164,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 | 前端 | Next.js 16 (App Router) |
 | 后端 | Go (Chi router, sqlc, gorilla/websocket) |
 | 数据库 | PostgreSQL 17 with pgvector |
-| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、OpenClaw、OpenCode、Hermes、Gemini、Pi 或 Cursor Agent |
+| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、GitHub Copilot CLI、OpenClaw、OpenCode、Hermes、Gemini、Pi、Cursor Agent、Kimi 或 Kiro CLI |
 
 ## 开发
 

SELF_HOSTING.md

@@ -92,6 +92,7 @@ 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

@@ -56,13 +56,15 @@ Changes take effect after restarting the backend / compose stack. The web UI rea
 
 ### File Storage (Optional)
 
-For file uploads and attachments, configure S3 and CloudFront:
+For file uploads and attachments, configure S3 and (optionally) CloudFront:
 
 | Variable | Description |
 |----------|-------------|
-| `S3_BUCKET` | S3 bucket name |
-| `S3_REGION` | AWS region (default: `us-west-2`) |
-| `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
+| `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 |
 | `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
 | `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
 
@@ -103,6 +105,8 @@ 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 |

apps/desktop/.env.production

@@ -1,12 +0,0 @@
-# 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/src/main/app-version.ts

@@ -0,0 +1,33 @@
+import { app } from "electron";
+import { execSync } from "node:child_process";
+
+/**
+ * Resolve the running app version. In packaged builds this is the value
+ * `electron-builder` baked into package.json via `extraMetadata.version`
+ * (driven by `git describe` — see `apps/desktop/scripts/package.mjs`), so
+ * `app.getVersion()` matches the GitHub Release tag exactly.
+ *
+ * In dev (`pnpm dev:desktop`) `app.getVersion()` only sees the static
+ * `apps/desktop/package.json` value, which is "0.1.0" and never bumped —
+ * the Settings → Updates panel and any other UI surfacing the version
+ * would mislead developers into thinking they're running ancient builds.
+ * Fall back to `git describe --tags --always --dirty` (same source the
+ * packager uses) so dev shows e.g. `0.2.19-14-gabcdef-dirty`. If git is
+ * unavailable for whatever reason, we just return the package.json value.
+ */
+export function getAppVersion(): string {
+  if (app.isPackaged) {
+    return app.getVersion();
+  }
+  try {
+    const raw = execSync("git describe --tags --always --dirty", {
+      cwd: app.getAppPath(),
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!raw) return app.getVersion();
+    return raw.replace(/^v/, "");
+  } catch {
+    return app.getVersion();
+  }
+}

apps/desktop/src/main/index.ts

@@ -7,6 +7,9 @@ import { setupAutoUpdater } from "./updater";
 import { setupDaemonManager } from "./daemon-manager";
 import { openExternalSafely } from "./external-url";
 import { installContextMenu } from "./context-menu";
+import { getAppVersion } from "./app-version";
+import { loadRuntimeConfig } from "./runtime-config-loader";
+import type { RuntimeConfigResult } from "../shared/runtime-config";
 
 // Bundled icon used for dev-mode dock/taskbar branding. In production the
 // app bundle icon (from electron-builder) wins; this path is only consumed
@@ -36,6 +39,10 @@ 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 ---------------------------------------------------
 
@@ -71,7 +78,25 @@ 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,
@@ -88,6 +113,7 @@ function createWindow(): void {
       preload: join(__dirname, "../preload/index.js"),
       sandbox: false,
       webSecurity: false,
+      additionalArguments: [`--multica-locale=${systemLocale}`],
     },
   });
 
@@ -105,11 +131,39 @@ 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" };
   });
 
+  // Prevent Cmd+R / Ctrl+R / Shift+Cmd+R / Shift+Ctrl+R / F5 from
+  // reloading the page. In a desktop app an accidental reload destroys
+  // in-memory state (tabs, drafts, WS connections) with no URL bar to
+  // navigate back. DevTools refresh (via the DevTools UI) still works.
+  mainWindow.webContents.on("before-input-event", (_event, input) => {
+    if (input.type !== "keyDown") return;
+    const cmdOrCtrl =
+      process.platform === "darwin" ? input.meta : input.control;
+    if (
+      (cmdOrCtrl && input.key.toLowerCase() === "r") ||
+      input.key === "F5"
+    ) {
+      _event.preventDefault();
+    }
+  });
+
   installContextMenu(mainWindow.webContents);
 
   if (is.dev && process.env["ELECTRON_RENDERER_URL"]) {
@@ -170,7 +224,25 @@ if (!gotTheLock) {
     if (deepLinkUrl) handleDeepLink(deepLinkUrl);
   });
 
-  app.whenReady().then(() => {
+  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,
+      },
+    });
+
     electronApp.setAppUserModelId(
       is.dev ? "ai.multica.desktop.dev" : "ai.multica.desktop",
     );
@@ -203,7 +275,14 @@ if (!gotTheLock) {
     ipcMain.on("app:get-info", (event) => {
       const p = process.platform;
       const os = p === "darwin" ? "macos" : p === "win32" ? "windows" : p === "linux" ? "linux" : "unknown";
-      event.returnValue = { version: app.getVersion(), os };
+      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

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

@@ -0,0 +1,90 @@
+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://api.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

@@ -0,0 +1,60 @@
+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/preload/index.d.ts

@@ -1,4 +1,5 @@
 import { ElectronAPI } from "@electron-toolkit/preload";
+import type { RuntimeConfigResult } from "../shared/runtime-config";
 
 interface DesktopAPI {
   /** App version + normalized OS, captured synchronously at preload time. */
@@ -6,6 +7,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. */

apps/desktop/src/preload/index.ts

@@ -1,5 +1,6 @@
 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
@@ -21,12 +22,53 @@ 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) =>

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

@@ -1,6 +1,7 @@
 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";
@@ -15,6 +16,8 @@ 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() {
@@ -30,11 +33,16 @@ 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(() => {
-    window.daemonAPI.setTargetApiUrl(DAEMON_TARGET_API_URL);
-  }, []);
+    if (!runtimeConfig) return;
+    window.daemonAPI.setTargetApiUrl(runtimeConfig.apiUrl);
+  }, [runtimeConfig]);
 
   // 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
@@ -110,21 +118,58 @@ function AppContent() {
     : undefined;
   useDaemonIPCBridge(activeWsId);
 
-  // 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.
+  // 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.
   useEffect(() => {
-    if (!user || !workspaceListFetched) return;
+    if (!user || !workspaceListFetched) return undefined;
     const { overlay, open } = useWindowOverlayStore.getState();
-    if (overlay) return;
+    if (overlay) return undefined;
+    if (wsCount > 0) return undefined;
     if (!hasOnboarded) {
-      open({ type: "onboarding" });
-      return;
+      // 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;
+      };
     }
-    if (wsCount === 0) {
-      open({ type: "new-workspace" });
-    }
-  }, [user, workspaceListFetched, wsCount, workspaces, hasOnboarded]);
+    open({ type: "new-workspace" });
+    return undefined;
+  }, [user, workspaceListFetched, wsCount, workspaces, hasOnboarded, qc]);
 
   // Validate persisted tab state against the current user's workspace list,
   // and pick an active workspace if none is set. Runs in useLayoutEffect
@@ -189,9 +234,21 @@ function AppContent() {
   );
 }
 
-// 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";
+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>
+  );
+}
 
 // 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
@@ -215,22 +272,61 @@ 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>
-      <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>
+      {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} />
+      )}
       <Toaster />
       <UpdateNotification />
     </ThemeProvider>

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

@@ -0,0 +1,243 @@
+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,11 +1,17 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { capturePageview } from "@multica/core/analytics";
 import { useAuthStore } from "@multica/core/auth";
-import { useTabStore } from "@/stores/tab-store";
+import {
+  getActiveTab,
+  useActiveTabIdentity,
+  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.
+ * 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.
  *
  * Desktop has three layers that can own the visible page:
  *
@@ -17,10 +23,18 @@ 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`.
  *
- * 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.
+ * 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.
  *
  * PostHog's `capture_pageview: true` auto-capture is intentionally off (see
  * `initAnalytics`) so this component owns the event shape, matching the web
@@ -29,34 +43,75 @@ import { useWindowOverlayStore, type WindowOverlay } from "@/stores/window-overl
 export function PageviewTracker() {
   const user = useAuthStore((s) => s.user);
   const overlay = useWindowOverlayStore((s) => s.overlay);
-  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;
-  });
+  const { slug: activeWorkspaceSlug, tabId: activeTabId } = useActiveTabIdentity();
+  const activeTabPath = useTabStore((s) => getActiveTab(s)?.path ?? null);
 
-  const path = resolvePath(user, overlay, activeTabPath);
+  // (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 });
 
   useEffect(() => {
-    if (!path) return;
+    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;
+
     capturePageview(path);
-  }, [path]);
+    lastSurfaceRef.current = next;
+  }, [user, overlay, activeWorkspaceSlug, activeTabId, activeTabPath]);
 
   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":
@@ -65,5 +120,7 @@ function overlayPath(overlay: WindowOverlay): string {
       return "/onboarding";
     case "invite":
       return `/invite/${overlay.invitationId}`;
+    case "invitations":
+      return "/invitations";
   }
 }

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

@@ -5,12 +5,13 @@ import { Button } from "@multica/ui/components/ui/button";
 type CheckState =
   | { status: "idle" }
   | { status: "checking" }
-  | { status: "up-to-date"; currentVersion: string }
+  | { status: "up-to-date" }
   | { status: "available"; latestVersion: string }
   | { status: "error"; message: string };
 
 export function UpdatesSettingsTab() {
   const [state, setState] = useState<CheckState>({ status: "idle" });
+  const currentVersion = window.desktopAPI.appInfo.version;
 
   const handleCheck = useCallback(async () => {
     setState({ status: "checking" });
@@ -22,7 +23,7 @@ export function UpdatesSettingsTab() {
     setState(
       result.available
         ? { status: "available", latestVersion: result.latestVersion }
-        : { status: "up-to-date", currentVersion: result.currentVersion },
+        : { status: "up-to-date" },
     );
   }, []);
 
@@ -35,6 +36,15 @@ export function UpdatesSettingsTab() {
       </p>
 
       <div className="mt-6 divide-y">
+        <div className="flex items-center justify-between gap-6 py-4">
+          <div className="min-w-0">
+            <p className="text-sm font-medium">Current version</p>
+            <p className="text-sm text-muted-foreground mt-0.5 font-mono">
+              v{currentVersion}
+            </p>
+          </div>
+        </div>
+
         <div className="flex items-start justify-between gap-6 py-4">
           <div className="min-w-0">
             <p className="text-sm font-medium">Check for updates</p>
@@ -45,7 +55,7 @@ export function UpdatesSettingsTab() {
             {state.status === "up-to-date" && (
               <p className="text-sm text-muted-foreground mt-2 inline-flex items-center gap-1.5">
                 <Check className="size-3.5 text-success" />
-                You&apos;re on the latest version (v{state.currentVersion}).
+                You&apos;re on the latest version.
               </p>
             )}
             {state.status === "available" && (

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

@@ -1,6 +1,7 @@
 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";
@@ -58,6 +59,7 @@ function WindowOverlayInner() {
           onBack={onBack}
         />
       )}
+      {overlay.type === "invitations" && <InvitationsPage />}
       {overlay.type === "onboarding" && (
         <OnboardingFlow
           onComplete={(ws) => {

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

@@ -2,14 +2,23 @@ import { LoginPage } from "@multica/views/auth";
 import { DragStrip } from "@multica/views/platform";
 import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
 
-const WEB_URL = import.meta.env.VITE_APP_URL || "http://localhost:3000";
+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;
+}
 
 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(
-      `${WEB_URL}/login?platform=desktop`,
+      `${webUrl}/login?platform=desktop`,
     );
   };
 

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

@@ -0,0 +1,31 @@
+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,11 +15,15 @@ import {
 } from "@/stores/tab-store";
 import { useWindowOverlayStore } from "@/stores/window-overlay-store";
 
-// 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";
+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;
+}
 
 /**
  * Extract the leading workspace slug from a path, or null if the path isn't
@@ -61,6 +65,13 @@ 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 {
@@ -109,6 +120,7 @@ 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.
@@ -179,9 +191,9 @@ export function DesktopNavigationProvider({
         const tabId = store.openTab(path, title ?? path, icon);
         if (tabId) store.setActiveTab(tabId);
       },
-      getShareableUrl: (path: string) => `${APP_URL}${path}`,
+      getShareableUrl: (path: string) => `${appUrl}${path}`,
     }),
-    [location],
+    [appUrl, location],
   );
 
   return <NavigationProvider value={adapter}>{children}</NavigationProvider>;
@@ -204,6 +216,7 @@ export function TabNavigationProvider({
   router: DataRouter;
   children: React.ReactNode;
 }) {
+  const appUrl = requireRuntimeAppUrl("TabNavigationProvider");
   const [location, setLocation] = useState(router.state.location);
 
   useEffect(() => {
@@ -239,9 +252,9 @@ export function TabNavigationProvider({
         const tabId = store.openTab(path, title ?? path, icon);
         if (tabId) store.setActiveTab(tabId);
       },
-      getShareableUrl: (path: string) => `${APP_URL}${path}`,
+      getShareableUrl: (path: string) => `${appUrl}${path}`,
     }),
-    [router, location],
+    [appUrl, router, location],
   );
 
   return <NavigationProvider value={adapter}>{children}</NavigationProvider>;

apps/desktop/src/renderer/src/stores/window-overlay-store.ts

@@ -15,6 +15,7 @@ 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

@@ -0,0 +1,99 @@
+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("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",
+    });
+  });
+});

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

@@ -0,0 +1,157 @@
+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: normalizeHttpUrl(
+      env.appUrl || LOCAL_DEV_RUNTIME_CONFIG.appUrl,
+      "VITE_APP_URL",
+    ),
+  };
+}
+
+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());
+}
+
+export function deriveAppUrl(apiUrl: string): string {
+  const url = new URL(apiUrl);
+  url.pathname = "";
+  url.search = "";
+  url.hash = "";
+  return trimTrailingSlash(url.toString());
+}
+
+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 +1,38 @@
 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,8 +1,14 @@
+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/content/docs/assigning-issues.mdx

@@ -32,9 +32,10 @@ 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. 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.
+`--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.
 
 Unassign:
 

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

@@ -32,9 +32,10 @@ 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` 后跟成员用户名或智能体名字。给智能体起个好记的名字会让这一步顺很多——工作区里重名的会按列出顺序选第一个，建议先改名再分配。
+`--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` 互斥。
 
 取消分配：
 

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
+multica login --token <mul_...>
 ```
 
-Authenticate by pasting a personal access token directly. Useful for headless environments.
+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).
 
 ### Check Status
 
@@ -221,10 +221,11 @@ 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 --limit 20 --output json
 ```
 
-Available filters: `--status`, `--priority`, `--assignee`, `--project`, `--limit`.
+Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--limit`. 在重名 workspace 下用 `--assignee-id <uuid>` 可以精确锁定一个成员或 agent。
 
 ### Get Issue
 
@@ -237,9 +238,10 @@ 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`, `--parent`, `--project`, `--due-date`.
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee` / `--assignee-id`, `--parent`, `--project`, `--due-date`. 脚本里如果已经拿到了 UUID（例如来自 `multica workspace members --output json`），传 `--assignee-id <uuid>`（与 `--assignee` 互斥）以精确锁定。
 
 ### Update Issue
 
@@ -251,9 +253,12 @@ 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

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.
+`--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`.
 
 **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` 后面填智能体或成员的**名字**，子串就行——如果智能体叫 `my-code-reviewer`，填 `reviewer` 也能命中。如果工作区里名字相互重叠或冲突，改用 `--to-id <uuid>`（与 `--to` 互斥）；UUID 来自 `multica agent list --output json` 或 `multica workspace members --output json`。
 
 **接下来守护进程会**：
 

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. 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**.
+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**.
 
 ## Desktop or web — which to pick
 
@@ -66,25 +66,34 @@ 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="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:
+<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.
 
-```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
+Minimal self-host config:
+
+```json
+{
+  "schemaVersion": 1,
+  "apiUrl": "https://api.your-domain"
+}
 ```
 
-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).
+`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).
 </Callout>
 
 ## Next steps
 
 - [Cloud Quickstart](/cloud-quickstart) — the Cloud onboarding flow for Desktop
-- [Self-Host Quickstart](/self-host-quickstart) — running your own backend (Desktop against self-host requires a custom build, see the callout above)
+- [Self-Host Quickstart](/self-host-quickstart) — running your own backend and connecting with the CLI or Desktop runtime config
 - [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 版连同一个后端，看到的数据完全一样，但给了几个 Web 做不到的能力：**[工作区](/workspaces) 独立的多标签页**、**自动启动 [守护进程](/daemon-runtimes)**、**一键升级**。
+Multica Desktop 是原生桌面应用——macOS / Windows / Linux 三个平台。对它当前配置的环境来说，它和 Web 版连同一个后端、看到的数据完全一样。Desktop 默认使用 Multica Cloud；自部署实例可以通过本地运行时配置文件接入。它还给了几个 Web 做不到的能力：**[工作区](/workspaces) 独立的多标签页**、**自动启动 [守护进程](/daemon-runtimes)**、**一键升级**。
 
 ## Desktop 和 Web 该用哪个
 
@@ -66,25 +66,34 @@ macOS 版本已经签名 + 公证，第一次打开不会有"未知开发者"的
 
 安装后第一次打开需要登录——和 Web 版一样的 email + 验证码流程。登录成功后 Desktop 自动把工作区列表同步下来。
 
-<Callout type="warning">
-**发布版的 Desktop 是锁死连 Multica Cloud 的**。后端 / WebSocket / Web 前端 URL（`VITE_API_URL` / `VITE_WS_URL` / `VITE_APP_URL`）在构建时就写死了，应用内**没有切换后端的入口**。要让 Desktop 连自部署后端，需要你自己从源码 build：
+<Callout type="info">
+**Desktop 默认连接 Multica Cloud，但可以通过本地配置文件指向自部署实例。** 应用内仍然没有“连接自部署”的切换入口。Desktop 会在 renderer 启动前读取 `~/.multica/desktop.json`；如果这个文件不存在，就使用 Cloud 默认值。
 
-```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
+最小自部署配置：
+
+```json
+{
+  "schemaVersion": 1,
+  "apiUrl": "https://api.your-domain"
+}
 ```
 
-不想自己 build 的话，自部署的官方路径是 **Web 前端 + CLI**——见 [自部署快速上手](/self-host-quickstart)。Desktop 运行时切换后端的能力跟踪在 [issue #1371](https://github.com/multica-ai/multica/issues/1371)。
+`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)。
 </Callout>
 
 ## 下一步
 
 - [Cloud Quickstart](/cloud-quickstart) —— Desktop 版的 Cloud 接入流程
-- [Self-Host Quickstart](/self-host-quickstart) —— 自部署后端（Desktop 连自部署需要自行构建，见上方提示）
+- [Self-Host Quickstart](/self-host-quickstart) —— 自部署后端，并通过 CLI 或 Desktop 运行时配置连接
 - [守护进程与运行时](/daemon-runtimes) —— 守护进程机制（Desktop 自动起它，但行为一样）

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

@@ -0,0 +1,292 @@
+---
+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.
+
+### Don't translate — entities (lowercase English)
+
+| Term | Render in Chinese | Example |
+| --- | --- | --- |
+| Issue | `issue` (lowercase) | "把 issue 分配给智能体"、"创建子 issue" |
+| Skill | `skill` (lowercase) | "为智能体注入 skill" |
+| Task | `task` (lowercase) | "排队中的 task" |
+
+**Why `issue` / `skill` / `task` stay English while `project` / `autopilot` are translated**:
+
+- **`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`.
+- **`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 | 移除 / 发送 / 打开 / 关闭 |
+| 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.appearance.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/appearance-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

@@ -0,0 +1,292 @@
+---
+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 | `issue`（小写） | "把 issue 分配给智能体"、"创建子 issue" |
+| Skill | `skill`（小写） | "为智能体注入 skill" |
+| Task | `task`（小写） | "排队中的 task" |
+
+**为什么 `issue` / `skill` / `task` 不翻而 `project` / `autopilot` 翻**：
+
+- **`issue` / `task`**：dev 团队习惯说英文，"任务"在中文里和"工作"几乎同义太空泛，"工单"是 IT 工单语义，"议题"是 GitHub 风格但用户场景不匹配。三个候选都不如 `issue` 准确。
+- **`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 | 移除 / 发送 / 打开 / 关闭 |
+| 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.appearance.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/appearance-tab.tsx` —— 语言切换器参考
+
+---
+
+## 修改这一页时
+
+改本页规则的同时还要：
+
+1. 把规则在相关 locale JSON / CLAUDE.md / docs 页面里同步落地
+2. PR 描述里写明改了什么，方便 reviewer 检查下游是否跟着改了
+
+本页是契约，其他文档不能 override。

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

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

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

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

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

@@ -66,13 +66,19 @@ Multica stores user-uploaded attachments (images and files in comments). **S3 is
 
 | Variable | Default | Description |
 |---|---|---|
-| `S3_BUCKET` | empty | Setting this enables S3 storage |
-| `S3_REGION` | `us-west-2` | AWS region |
+| `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 |
 | `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 |

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

@@ -66,13 +66,19 @@ Multica 存储用户上传的附件（评论里的图片、文件等）。**优
 
 | 环境变量 | 默认值 | 说明 |
 |---|---|---|
-| `S3_BUCKET` | 空 | 设了就启用 S3 存储 |
-| `S3_REGION` | `us-west-2` | AWS 区域 |
+| `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 都用它 |
 | `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 未配时）
 
 | 环境变量 | 默认值 | 说明 |

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

@@ -212,13 +212,15 @@ Changes take effect after restarting the backend / compose stack. The web UI rea
 
 ### File Storage (Optional)
 
-For file uploads and attachments, configure S3 and CloudFront:
+For file uploads and attachments, configure S3 and (optionally) CloudFront:
 
 | Variable | Description |
 |----------|-------------|
-| `S3_BUCKET` | S3 bucket name |
-| `S3_REGION` | AWS region (default: `us-west-2`) |
-| `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
+| `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 |
 | `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
 | `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
 

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/`, `.config/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/`, `.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/meta.json

@@ -10,6 +10,7 @@
     "members-roles",
     "issues",
     "comments",
+    "project-resources",
     "---Agents---",
     "agents",
     "agents-create",
@@ -32,6 +33,8 @@
     "---Reference---",
     "cli",
     "auth-tokens",
-    "desktop-app"
+    "desktop-app",
+    "---Developers---",
+    "developers"
   ]
 }

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

@@ -32,6 +32,8 @@
     "---参考---",
     "cli",
     "auth-tokens",
-    "desktop-app"
+    "desktop-app",
+    "---开发者---",
+    "developers"
   ]
 }

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

@@ -0,0 +1,144 @@
+---
+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/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 | ✅ | ❌ | `.config/opencode/skills/` | Dynamic discovery |
+| **OpenCode** | SST | ✅ | ❌ | `.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 | `.config/opencode/skills/` | ✅ Native |
+| OpenCode | `.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 | ✅ | ❌ | `.config/opencode/skills/` | 动态发现 |
+| **OpenCode** | SST | ✅ | ❌ | `.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 | `.config/opencode/skills/` | ✅ 原生 |
+| OpenCode | `.opencode/skills/` | ✅ 原生 |
 | Pi | `.pi/skills/` | ✅ 原生 |
 | Gemini | `.agent_context/skills/` | ⚠️ 通用 fallback |
 | Hermes | `.agent_context/skills/` | ⚠️ 通用 fallback |

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

@@ -116,4 +116,4 @@ Same flow as Cloud — see [Cloud quickstart → Steps 5-6](/cloud-quickstart#5-
 - [Environment variables](/environment-variables) — full env reference
 - [Auth setup](/auth-setup) — Resend / OAuth / signup allowlist in detail
 - [Troubleshooting](/troubleshooting) — start here when things go wrong
-- [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)
+- [Desktop app](/desktop-app) — optional Desktop setup via `~/.multica/desktop.json`; the web frontend + CLI remains the quickest self-host path

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

@@ -115,4 +115,4 @@ multica setup self-host
 - [环境变量](/environment-variables) —— 完整 env 清单
 - [登录与注册配置](/auth-setup) —— Resend / OAuth / 注册白名单详细配置
 - [故障排查](/troubleshooting) —— 遇到问题先来这里
-- [桌面应用](/desktop-app) —— 发布版 Desktop 只连 Multica Cloud；要让 Desktop 连自部署后端需要自行构建（详见 desktop-app 页的提示）
+- [桌面应用](/desktop-app) —— 可以通过 `~/.multica/desktop.json` 连接 Desktop；Web 前端 + CLI 仍然是最快的自部署路径

apps/web/app/(auth)/invitations/page.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useAuthStore } from "@multica/core/auth";
+import { paths } from "@multica/core/paths";
+import { InvitationsPage } from "@multica/views/invitations";
+
+export default function InvitationsRoutePage() {
+  const router = useRouter();
+  const user = useAuthStore((s) => s.user);
+  const isLoading = useAuthStore((s) => s.isLoading);
+
+  // Unauthenticated users have nowhere meaningful to land here — kick them
+  // through login and bring them back. The login page will eventually run
+  // its own listMyInvitations() check and route them here again.
+  useEffect(() => {
+    if (!isLoading && !user) {
+      router.replace(
+        `${paths.login()}?next=${encodeURIComponent(paths.invitations())}`,
+      );
+    }
+  }, [isLoading, user, router]);
+
+  if (isLoading || !user) return null;
+
+  return <InvitationsPage />;
+}

apps/web/app/(auth)/login/page.test.tsx

@@ -2,12 +2,22 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { I18nProvider } from "@multica/core/i18n/react";
+import enCommon from "@multica/views/locales/en/common.json";
+import enAuth from "@multica/views/locales/en/auth.json";
+import enSettings from "@multica/views/locales/en/settings.json";
 import type { ReactNode } from "react";
 
+const TEST_RESOURCES = {
+  en: { common: enCommon, auth: enAuth, settings: enSettings },
+};
+
 function createWrapper() {
   const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
   return ({ children }: { children: ReactNode }) => (
-    <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+    <I18nProvider locale="en" resources={TEST_RESOURCES}>
+      <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+    </I18nProvider>
   );
 }
 

apps/web/app/(auth)/login/page.tsx

@@ -2,7 +2,7 @@
 
 import { Suspense, useEffect, useState } from "react";
 import { useSearchParams, useRouter } from "next/navigation";
-import { useQueryClient } from "@tanstack/react-query";
+import { useQueryClient, type QueryClient } from "@tanstack/react-query";
 import { sanitizeNextUrl, useAuthStore } from "@multica/core/auth";
 import { useConfigStore } from "@multica/core/config";
 import { workspaceKeys } from "@multica/core/workspace/queries";
@@ -26,10 +26,38 @@ import { captureDownloadIntent } from "@multica/core/analytics";
 import { setLoggedInCookie } from "@/features/auth/auth-cookie";
 import Link from "next/link";
 import { LoginPage, validateCliCallback } from "@multica/views/auth";
+import { useT } from "@multica/views/i18n";
+
+/**
+ * Pick where a logged-in user with no explicit `?next=` should land.
+ * Un-onboarded users with pending invitations on their email get routed to
+ * the batch /invitations page; everyone else falls through to the standard
+ * resolver. A network blip on listMyInvitations is non-fatal — we fall
+ * through rather than trap the user on an error screen.
+ */
+async function resolveLoggedInDestination(
+  qc: QueryClient,
+  hasOnboarded: boolean,
+  workspaces: Workspace[],
+): Promise<string> {
+  if (!hasOnboarded) {
+    try {
+      const invites = await api.listMyInvitations();
+      if (invites.length > 0) {
+        qc.setQueryData(workspaceKeys.myInvitations(), invites);
+        return paths.invitations();
+      }
+    } catch {
+      // fall through
+    }
+  }
+  return resolvePostAuthDestination(workspaces, hasOnboarded);
+}
 
 function LoginPageContent() {
   const router = useRouter();
   const qc = useQueryClient();
+  const { t } = useT("auth");
   const googleClientId = useConfigStore((state) => state.googleClientId);
   const user = useAuthStore((s) => s.user);
   const isLoading = useAuthStore((s) => s.isLoading);
@@ -67,38 +95,35 @@ function LoginPageContent() {
         })
         .catch((err) => {
           setDesktopError(
-            err instanceof Error ? err.message : "Failed to prepare Desktop sign-in",
+            err instanceof Error
+              ? err.message
+              : t(($) => $.web.desktop_handoff.prepare_failed),
           );
         });
       return;
     }
-    if (!hasOnboarded) {
-      router.replace(paths.onboarding());
-      return;
-    }
     if (nextUrl) {
       router.replace(nextUrl);
       return;
     }
     const list = qc.getQueryData<Workspace[]>(workspaceKeys.list()) ?? [];
-    router.replace(resolvePostAuthDestination(list, hasOnboarded));
+    void resolveLoggedInDestination(qc, hasOnboarded, list).then((dest) =>
+      router.replace(dest),
+    );
   }, [isLoading, user, router, nextUrl, cliCallbackRaw, isDesktopHandoff, hasOnboarded, qc]);
 
-  const handleSuccess = () => {
+  const handleSuccess = async () => {
     // Read the latest user snapshot directly — the closure's `hasOnboarded`
     // was captured before login completed and would be stale here.
     const currentUser = useAuthStore.getState().user;
     const onboarded = currentUser?.onboarded_at != null;
-    if (!onboarded) {
-      router.push(paths.onboarding());
-      return;
-    }
     if (nextUrl) {
       router.push(nextUrl);
       return;
     }
     const list = qc.getQueryData<Workspace[]>(workspaceKeys.list()) ?? [];
-    router.push(resolvePostAuthDestination(list, onboarded));
+    const dest = await resolveLoggedInDestination(qc, onboarded, list);
+    router.push(dest);
   };
 
   // Build Google OAuth state: encode platform + next URL so the callback
@@ -119,7 +144,9 @@ function LoginPageContent() {
         <div className="flex min-h-screen items-center justify-center">
           <Card className="w-full max-w-sm">
             <CardHeader className="text-center">
-              <CardTitle className="text-2xl">Sign-in Failed</CardTitle>
+              <CardTitle className="text-2xl">
+                {t(($) => $.web.desktop_handoff.failed_title)}
+              </CardTitle>
               <CardDescription>{desktopError}</CardDescription>
             </CardHeader>
           </Card>
@@ -130,11 +157,13 @@ function LoginPageContent() {
       <div className="flex min-h-screen items-center justify-center">
         <Card className="w-full max-w-sm">
           <CardHeader className="text-center">
-            <CardTitle className="text-2xl">Opening Multica</CardTitle>
+            <CardTitle className="text-2xl">
+              {t(($) => $.web.desktop_handoff.opening_title)}
+            </CardTitle>
             <CardDescription>
               {desktopToken
-                ? "You should see a prompt to open the Multica desktop app. If nothing happens, click the button below."
-                : "Preparing Desktop sign-in..."}
+                ? t(($) => $.web.desktop_handoff.opening_description)
+                : t(($) => $.web.desktop_handoff.preparing)}
             </CardDescription>
           </CardHeader>
           <CardContent className="flex justify-center">
@@ -145,7 +174,7 @@ function LoginPageContent() {
                   window.location.href = `multica://auth/callback?token=${encodeURIComponent(desktopToken)}`;
                 }}
               >
-                Open Multica Desktop
+                {t(($) => $.web.desktop_handoff.open_button)}
               </Button>
             ) : (
               <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
@@ -175,18 +204,14 @@ function LoginPageContent() {
       }
       onTokenObtained={setLoggedInCookie}
       extra={
-        // Web-only nudge toward the desktop app. Copy is hardcoded EN
-        // for now because the login route sits outside the landing
-        // group's LocaleProvider — if this page ever becomes
-        // locale-aware, the strings live in positioning doc §3.3.
         <span className="text-xs text-muted-foreground">
-          Prefer the desktop app?{" "}
+          {t(($) => $.web.prefer_desktop)}{" "}
           <Link
             href="/download"
             onClick={() => captureDownloadIntent("login")}
             className="font-medium text-foreground underline decoration-foreground/30 underline-offset-4 hover:decoration-foreground/70"
           >
-            Download
+            {t(($) => $.web.download)}
           </Link>
         </span>
       }

apps/web/app/(auth)/onboarding/page.tsx

@@ -32,7 +32,7 @@ export default function OnboardingPage() {
   const hasOnboarded = useHasOnboarded();
   const { data: workspaces = [], isFetched: workspacesFetched } = useQuery({
     ...workspaceListOptions(),
-    enabled: !!user && hasOnboarded,
+    enabled: !!user,
   });
 
   useEffect(() => {
@@ -40,7 +40,15 @@ export default function OnboardingPage() {
       if (!isLoading && !user) router.replace(paths.login());
       return;
     }
-    if (hasOnboarded && workspacesFetched) {
+    if (!workspacesFetched) return;
+    // Bounce out only when onboarding genuinely doesn't apply: the user is
+    // already onboarded. We deliberately don't bounce on `workspaces.length`
+    // here — Step 3 of the flow creates a workspace mid-onboarding, and a
+    // hasWorkspaces bounce here would kick the user out before Steps 4–5
+    // (runtime / agent / first issue) can run. The new entry-point
+    // judgment in callback / login handles "where should this user go on
+    // login" so OnboardingPage no longer needs to second-guess it.
+    if (hasOnboarded) {
       router.replace(resolvePostAuthDestination(workspaces, hasOnboarded));
     }
   }, [isLoading, user, hasOnboarded, workspacesFetched, workspaces, router]);

apps/web/app/(landing)/layout.tsx

@@ -1,5 +1,6 @@
 import { cookies, headers } from "next/headers";
 import { Instrument_Serif, Noto_Serif_SC } from "next/font/google";
+import { LOCALE_COOKIE } from "@multica/core/i18n";
 import { LocaleProvider } from "@/features/landing/i18n";
 import type { Locale } from "@/features/landing/i18n";
 
@@ -43,7 +44,7 @@ const jsonLd = {
 async function getInitialLocale(): Promise<Locale> {
   // 1. User's explicit preference (cookie set when they switch language)
   const cookieStore = await cookies();
-  const stored = cookieStore.get("multica-locale")?.value;
+  const stored = cookieStore.get(LOCALE_COOKIE)?.value;
   if (stored === "en" || stored === "zh") return stored;
 
   // 2. Detect from Accept-Language header

apps/web/app/auth/callback/page.test.tsx

@@ -2,13 +2,21 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render, waitFor } from "@testing-library/react";
 import { paths } from "@multica/core/paths";
 
-const { mockPush, mockSearchParams, mockLoginWithGoogle, mockListWorkspaces } =
-  vi.hoisted(() => ({
-    mockPush: vi.fn(),
-    mockSearchParams: new URLSearchParams(),
-    mockLoginWithGoogle: vi.fn(),
-    mockListWorkspaces: vi.fn(),
-  }));
+const {
+  mockPush,
+  mockSearchParams,
+  mockLoginWithGoogle,
+  mockListWorkspaces,
+  mockListMyInvitations,
+  mockSetQueryData,
+} = vi.hoisted(() => ({
+  mockPush: vi.fn(),
+  mockSearchParams: new URLSearchParams(),
+  mockLoginWithGoogle: vi.fn(),
+  mockListWorkspaces: vi.fn(),
+  mockListMyInvitations: vi.fn(),
+  mockSetQueryData: vi.fn(),
+}));
 
 const makeUser = (overrides: Partial<{ onboarded_at: string | null }> = {}) => ({
   id: "user-1",
@@ -28,7 +36,7 @@ vi.mock("next/navigation", () => ({
 }));
 
 vi.mock("@tanstack/react-query", () => ({
-  useQueryClient: () => ({ setQueryData: vi.fn() }),
+  useQueryClient: () => ({ setQueryData: mockSetQueryData }),
 }));
 
 // Preserve the real sanitizeNextUrl so the "drop unsafe ?next=" behavior is
@@ -46,12 +54,16 @@ vi.mock("@multica/core/auth", async () => {
 });
 
 vi.mock("@multica/core/workspace/queries", () => ({
-  workspaceKeys: { list: () => ["workspaces"] },
+  workspaceKeys: {
+    list: () => ["workspaces"],
+    myInvitations: () => ["invitations", "mine"],
+  },
 }));
 
 vi.mock("@multica/core/api", () => ({
   api: {
     listWorkspaces: mockListWorkspaces,
+    listMyInvitations: mockListMyInvitations,
     googleLogin: vi.fn(),
   },
 }));
@@ -61,26 +73,78 @@ import CallbackPage from "./page";
 describe("CallbackPage", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mockSearchParams.forEach((_v, k) => mockSearchParams.delete(k));
+    // Snapshot keys before deleting — forEach + delete skips entries because
+    // the iteration index advances while the underlying list shrinks.
+    Array.from(mockSearchParams.keys()).forEach((k) =>
+      mockSearchParams.delete(k),
+    );
     mockSearchParams.set("code", "test-code");
     mockLoginWithGoogle.mockResolvedValue(makeUser());
     mockListWorkspaces.mockResolvedValue([]);
+    mockListMyInvitations.mockResolvedValue([]);
   });
 
-  it("unonboarded user lands on /onboarding regardless of next=", async () => {
+  it("unonboarded user honors a safe next= (e.g. /invite/{id}) so invitees aren't trapped", async () => {
     mockSearchParams.set("state", "next:/invite/abc123");
     render(<CallbackPage />);
     await waitFor(() => {
-      expect(mockPush).toHaveBeenCalledWith(paths.onboarding());
+      expect(mockPush).toHaveBeenCalledWith("/invite/abc123");
     });
-    expect(mockPush).not.toHaveBeenCalledWith("/invite/abc123");
+    expect(mockPush).not.toHaveBeenCalledWith(paths.onboarding());
+    // nextUrl is a fast path — listMyInvitations should not be queried.
+    expect(mockListMyInvitations).not.toHaveBeenCalled();
   });
 
-  it("unonboarded user with no next= also lands on /onboarding", async () => {
+  it("unonboarded user with no next= and no pending invitations lands on /onboarding", async () => {
     render(<CallbackPage />);
     await waitFor(() => {
       expect(mockPush).toHaveBeenCalledWith(paths.onboarding());
     });
+    expect(mockListMyInvitations).toHaveBeenCalled();
+  });
+
+  it("unonboarded user with pending invitations lands on /invitations", async () => {
+    mockListMyInvitations.mockResolvedValue([
+      {
+        id: "inv-1",
+        workspace_id: "ws-1",
+        workspace_name: "Acme",
+        role: "member",
+        status: "pending",
+      },
+    ]);
+    render(<CallbackPage />);
+    await waitFor(() => {
+      expect(mockPush).toHaveBeenCalledWith(paths.invitations());
+    });
+    expect(mockPush).not.toHaveBeenCalledWith(paths.onboarding());
+  });
+
+  it("onboarded user with workspace lands in that workspace", async () => {
+    mockLoginWithGoogle.mockResolvedValue(
+      makeUser({ onboarded_at: "2026-01-01T00:00:00Z" }),
+    );
+    mockListWorkspaces.mockResolvedValue([
+      {
+        id: "ws-1",
+        name: "Acme",
+        slug: "acme",
+        description: null,
+        context: null,
+        settings: {},
+        repos: [],
+        issue_prefix: "ACME",
+        created_at: "",
+        updated_at: "",
+      },
+    ]);
+    render(<CallbackPage />);
+    await waitFor(() => {
+      expect(mockPush).toHaveBeenCalledWith(paths.workspace("acme").issues());
+    });
+    // Already-onboarded users skip the listMyInvitations check; new invites
+    // surface in the sidebar instead of the wall.
+    expect(mockListMyInvitations).not.toHaveBeenCalled();
   });
 
   it("onboarded user ignores unsafe next= targets and lands on the default destination", async () => {
@@ -109,4 +173,12 @@ describe("CallbackPage", () => {
       expect(mockPush).toHaveBeenCalledWith("/invite/abc123");
     });
   });
+
+  it("falls through to /onboarding when listMyInvitations errors", async () => {
+    mockListMyInvitations.mockRejectedValue(new Error("network"));
+    render(<CallbackPage />);
+    await waitFor(() => {
+      expect(mockPush).toHaveBeenCalledWith(paths.onboarding());
+    });
+  });
 });

apps/web/app/auth/callback/page.tsx

@@ -66,13 +66,42 @@ function CallbackContent() {
           const wsList = await api.listWorkspaces();
           qc.setQueryData(workspaceKeys.list(), wsList);
           const onboarded = loggedInUser.onboarded_at != null;
-          if (!onboarded) {
-            router.push(paths.onboarding());
+
+          // 1. nextUrl wins: a `next=/invite/<id>` always survives the OAuth
+          //    round-trip — the user clicked a specific link and we should
+          //    honor exactly that destination.
+          if (nextUrl) {
+            router.push(nextUrl);
             return;
           }
-          router.push(
-            nextUrl || resolvePostAuthDestination(wsList, onboarded),
-          );
+
+          // 2. Un-onboarded users may have pending invitations on their
+          //    email even when no `next=` was carried (came from a fresh
+          //    login on app.multica.ai instead of clicking the email link,
+          //    or `state` was lost across the round-trip). Look them up by
+          //    email and route to the batch /invitations page if any.
+          //    Already-onboarded users skip this lookup — their new invites
+          //    surface in the sidebar dropdown, not as a forced wall.
+          if (!onboarded) {
+            try {
+              const invites = await api.listMyInvitations();
+              if (invites.length > 0) {
+                qc.setQueryData(workspaceKeys.myInvitations(), invites);
+                router.push(paths.invitations());
+                return;
+              }
+            } catch {
+              // Network blip on the invite lookup is non-fatal — fall through
+              // to the normal post-auth destination so the user isn't stuck
+              // on a blank callback screen. Worst case they land on
+              // /onboarding and the sidebar will surface invites later.
+            }
+          }
+
+          // 3. Default: hand off to the resolver (onboarding for first-timers,
+          //    first workspace for returning users, /workspaces/new for
+          //    onboarded users with zero workspaces).
+          router.push(resolvePostAuthDestination(wsList, onboarded));
         })
         .catch((err) => {
           setError(err instanceof Error ? err.message : "Login failed");

apps/web/app/layout.tsx

@@ -1,10 +1,16 @@
 import type { Metadata, Viewport } from "next";
+import { headers } from "next/headers";
 import { Inter, Geist_Mono, Source_Serif_4 } from "next/font/google";
 import { ThemeProvider } from "@/components/theme-provider";
 import { Toaster } from "@multica/ui/components/ui/sonner";
 import { cn } from "@multica/ui/lib/utils";
 import { WebProviders } from "@/components/web-providers";
-import { LocaleSync } from "@/components/locale-sync";
+import {
+  DEFAULT_LOCALE,
+  SUPPORTED_LOCALES,
+  type SupportedLocale,
+} from "@multica/core/i18n";
+import { RESOURCES } from "@multica/views/locales";
 import "./globals.css";
 
 // Font stack: Inter for Latin UI text + system Chinese fonts for zh content.
@@ -97,21 +103,40 @@ export const metadata: Metadata = {
   },
 };
 
-export default function RootLayout({
+function isSupportedLocale(value: string | null): value is SupportedLocale {
+  return value !== null && (SUPPORTED_LOCALES as readonly string[]).includes(value);
+}
+
+// HTML lang attribute uses BCP-47 region tags that screen readers and font
+// stacks recognize widely. i18next keeps `zh-Hans` as its internal locale
+// (script subtag is what we actually translate against), but the html element
+// expects a region-flavoured tag for accessibility tooling and CJK fallback.
+const HTML_LANG: Record<SupportedLocale, string> = {
+  en: "en",
+  "zh-Hans": "zh-CN",
+};
+
+export default async function RootLayout({
   children,
 }: {
   children: React.ReactNode;
 }) {
+  const h = await headers();
+  const headerLocale = h.get("x-multica-locale");
+  const locale: SupportedLocale = isSupportedLocale(headerLocale)
+    ? headerLocale
+    : DEFAULT_LOCALE;
+  const resources = { [locale]: RESOURCES[locale] };
+
   return (
     <html
-      lang="en"
+      lang={HTML_LANG[locale]}
       suppressHydrationWarning
       className={cn("antialiased font-sans h-full", inter.variable, geistMono.variable, sourceSerif.variable)}
     >
       <body className="h-full overflow-hidden">
-        <LocaleSync />
         <ThemeProvider>
-          <WebProviders>
+          <WebProviders locale={locale} resources={resources}>
             {children}
           </WebProviders>
           <Toaster />

apps/web/app/not-found.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import Link from "next/link";
+import { buttonVariants } from "@multica/ui/components/ui/button";
+
+export default function NotFound() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-6 px-6 py-24 text-center">
+      <p className="text-sm font-medium text-muted-foreground">404</p>
+      <h1 className="text-2xl font-semibold tracking-tight">Page not found</h1>
+      <p className="max-w-md text-sm text-muted-foreground">
+        The page you are looking for doesn&rsquo;t exist or has been moved.
+      </p>
+      <Link href="/" className={buttonVariants({ className: "mt-2" })}>
+        Back to Multica
+      </Link>
+    </main>
+  );
+}

apps/web/components/locale-sync.tsx

@@ -1,20 +0,0 @@
-"use client";
-
-import { useEffect } from "react";
-
-/**
- * Reads the locale cookie on the client and updates <html lang>.
- * This avoids calling cookies() in the root Server Component layout,
- * which would mark the entire app as dynamic and disable the Router Cache.
- */
-export function LocaleSync() {
-  useEffect(() => {
-    const match = document.cookie.match(/(?:^|;\s*)multica-locale=(\w+)/);
-    const locale = match?.[1];
-    if (locale === "zh") {
-      document.documentElement.lang = "zh";
-    }
-  }, []);
-
-  return null;
-}

apps/web/components/web-providers.tsx

@@ -2,6 +2,8 @@
 
 import { Suspense, useMemo } from "react";
 import { CoreProvider } from "@multica/core/platform";
+import { createBrowserCookieLocaleAdapter } from "@multica/core/i18n/browser";
+import type { LocaleResources, SupportedLocale } from "@multica/core/i18n";
 import packageJson from "../package.json";
 import { WebNavigationProvider } from "@/platform/navigation";
 import {
@@ -41,7 +43,15 @@ function deriveWsUrl(): string | undefined {
 const WEB_VERSION =
   process.env.NEXT_PUBLIC_APP_VERSION || packageJson.version || "dev";
 
-export function WebProviders({ children }: { children: React.ReactNode }) {
+export function WebProviders({
+  children,
+  locale,
+  resources,
+}: {
+  children: React.ReactNode;
+  locale: SupportedLocale;
+  resources: Record<string, LocaleResources>;
+}) {
   const cookieAuth = !hasLegacyToken();
   // Stable identity reference so downstream effects keyed on it don't see a
   // new object on every parent render.
@@ -49,6 +59,7 @@ export function WebProviders({ children }: { children: React.ReactNode }) {
     () => ({ platform: "web", version: WEB_VERSION }),
     [],
   );
+  const localeAdapter = useMemo(() => createBrowserCookieLocaleAdapter(), []);
   return (
     <CoreProvider
       apiBaseUrl={process.env.NEXT_PUBLIC_API_URL}
@@ -57,6 +68,9 @@ export function WebProviders({ children }: { children: React.ReactNode }) {
       onLogin={setLoggedInCookie}
       onLogout={clearLoggedInCookie}
       identity={identity}
+      locale={locale}
+      resources={resources}
+      localeAdapter={localeAdapter}
     >
       {/* Suspense boundary is required by Next.js for useSearchParams in
           a client component mounted this high in the tree. */}

apps/web/features/landing/i18n/context.tsx

@@ -2,6 +2,7 @@
 
 import { createContext, useContext, useState, useCallback, useMemo } from "react";
 import { useConfigStore } from "@multica/core/config";
+import { LOCALE_COOKIE } from "@multica/core/i18n";
 import { createEnDict } from "./en";
 import { createZhDict } from "./zh";
 import type { LandingDict, Locale } from "./types";
@@ -11,7 +12,6 @@ const dictionaryFactories: Record<Locale, (allowSignup: boolean) => LandingDict>
   zh: createZhDict,
 };
 
-const COOKIE_NAME = "multica-locale";
 const COOKIE_MAX_AGE = 60 * 60 * 24 * 365; // 1 year
 
 type LocaleContextValue = {
@@ -38,7 +38,11 @@ export function LocaleProvider({
 
   const setLocale = useCallback((l: Locale) => {
     setLocaleState(l);
-    document.cookie = `${COOKIE_NAME}=${l}; path=/; max-age=${COOKIE_MAX_AGE}; SameSite=Lax`;
+    const secure =
+      typeof location !== "undefined" && location.protocol === "https:"
+        ? "; Secure"
+        : "";
+    document.cookie = `${LOCALE_COOKIE}=${l}; path=/; max-age=${COOKIE_MAX_AGE}; SameSite=Lax${secure}`;
   }, []);
 
   return (

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

@@ -283,6 +283,81 @@ export function createEnDict(allowSignup: boolean): LandingDict {
       fixes: "Bug Fixes",
     },
     entries: [
+      {
+        version: "0.2.24",
+        date: "2026-05-03",
+        title: "Repo Checkout `--ref`, Hermes Replay Fix & Multi-Replica Model Picker",
+        changes: [],
+        features: [
+          "`multica repo checkout --ref` targets a branch, tag, or specific commit when pulling a repo into the workspace",
+          "`multica agent avatar` uploads an agent avatar straight from the CLI",
+          "Inbox shows an archive button on done tasks; the redundant mark-as-done hover button is gone",
+        ],
+        improvements: [
+          "Long-timeline issues open instantly from Inbox — the markdown render pipeline is memoized so unrelated WS events no longer re-render thousands of comments",
+          "Model picker works on multi-replica deployments — pending requests persist via Redis, with daemon retries on transient report failures",
+          "Daemon empty-claim cache TTL bumped, further reducing idle DB load",
+        ],
+        fixes: [
+          "Newly created agents show up everywhere immediately — the agent cache is hydrated on create",
+          "Hermes no longer replays the previous answer when a new turn starts — historical chunks are gated behind a per-turn flag",
+          "Codex runtime model picker exposes the GPT-5.5 family",
+          "`multica login --token <PAT>` accepts the PAT as a flag value instead of rejecting it",
+          "CLI update completion status is now reliable",
+          "Session resume is guarded by runtime, preventing cross-runtime resume",
+          "Kanban display settings survive when dragging issues across columns",
+          "Autopilot list is responsive on mobile viewports",
+          "Quick Create prompts produce higher-fidelity descriptions from the user's input",
+          "Skill upsert sanitizes null bytes, fixing a PostgreSQL UTF8 error",
+          "Connect Remote dialog points to the correct install script URL",
+        ],
+      },
+      {
+        version: "0.2.21",
+        date: "2026-04-30",
+        title: "Quick Capture Overhaul, Mermaid Diagrams & Typed Project Resources",
+        changes: [],
+        features: [
+          "Quick Capture replaces the old New Issue dialog — continuous-create mode, file uploads, and automatic enrichment from pasted URLs",
+          "Mermaid diagrams render inline in markdown, with a fullscreen lightbox for complex graphs",
+          "Projects can bind their own repo, separate from the workspace default",
+          "Permission-aware UI across agents, comments, runtimes, and skills — actions you can't take are no longer offered",
+        ],
+        improvements: [
+          "Daemon `/tasks/claim` polling uses a Redis empty-claim fast-path, dropping idle DB load and reclaiming disk on long-open issues",
+          "Multica Agent commits include a `Co-authored-by` trailer for proper Git attribution",
+          "Desktop blocks Cmd+R / Ctrl+R / F5 from reloading the app and shows the real version in dev and Updates settings",
+        ],
+        fixes: [
+          "Quick Create no longer invents requirements beyond user input, and subscribes the requester to the issue it creates",
+          "Inbox jumps straight to the targeted comment, and auto-archives when the issue is marked Done from the detail page",
+          "Task rerun starts a fresh session and skips poisoned resume state",
+          "Invitees land on their workspace after sign-in instead of being forced through `/onboarding`",
+        ],
+      },
+      {
+        version: "0.2.20",
+        date: "2026-04-29",
+        title: "Create Issue by Agent, Agent Presence v3 & Daemon WebSocket Heartbeat",
+        changes: [],
+        features: [
+          "Create Issue by Agent — press `c`, write one line, pick an agent; issue creation runs async and the result lands in your inbox",
+          "Agent Presence v3 — availability and last-task split into clearer signals, with an execution log on the issue panel showing active and recent runs",
+          "Daemon ↔ server heartbeat now flows over WebSocket with HTTP fallback, cutting task wakeup latency",
+          "Mention picker ranks suggestions by your local recency",
+        ],
+        improvements: [
+          "Server caches PAT / daemon token lookups in Redis, so large fleets stop hammering the database on every request",
+          "Backend default agent CLI args via `MULTICA_CLAUDE_ARGS` / `MULTICA_CODEX_ARGS` env vars",
+          "Manual and agent create-issue flows share one dialog shell, and picker agents become the default assignee",
+        ],
+        fixes: [
+          "Create-issue-by-agent no longer leaves tasks stuck queued, and no longer duplicates the issue when an attachment upload fails",
+          "Agent comments respect newlines instead of rendering literal `\\n`, and multi-line replies keep their formatting",
+          "Agent-authored root comments no longer inherit parent @mentions, breaking accidental agent loops",
+          "Cursor agent on Windows preserves multi-line prompts",
+        ],
+      },
       {
         version: "0.2.19",
         date: "2026-04-28",

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

@@ -283,6 +283,81 @@ export function createZhDict(allowSignup: boolean): LandingDict {
       fixes: "问题修复",
     },
     entries: [
+      {
+        version: "0.2.24",
+        date: "2026-05-03",
+        title: "Repo Checkout `--ref`、Hermes 历史回放修复与多副本 Model Picker",
+        changes: [],
+        features: [
+          "`multica repo checkout --ref` 支持按分支、tag 或指定 commit 拉取仓库",
+          "`multica agent avatar` 命令支持直接通过 CLI 上传 Agent 头像",
+          "Inbox 中已完成任务新增 archive 按钮，移除冗余的 mark-as-done 悬浮按钮",
+        ],
+        improvements: [
+          "长 timeline 的 Issue 从 Inbox 打开不再卡顿 —— Markdown 渲染管线已 memoize，无关的 WS 事件不会再重渲染数千条评论",
+          "Model Picker 在多副本部署下可用 —— pending 请求改走 Redis 持久化，Daemon 上报失败也会自动重试",
+          "Daemon 空认领缓存 TTL 调高，空闲态 DB 压力进一步下降",
+        ],
+        fixes: [
+          "新创建的 Agent 立刻在各处可见 —— 创建时即 hydrate Agent 缓存",
+          "Hermes 在新一轮对话开始时不再重放上一轮答案 —— 历史 chunk 受单轮门禁限制",
+          "Codex runtime 模型选择器开放 GPT-5.5 系列",
+          "`multica login --token <PAT>` 正确接收 PAT 作为参数值",
+          "CLI update 完成状态上报更可靠",
+          "Session resume 按 runtime 正确守卫，避免跨 runtime 复用 session",
+          "看板拖拽 Issue 时显示设置不再丢失",
+          "Autopilot 列表在移动端 viewport 下响应式排版",
+          "Quick Create 生成的描述更贴合用户输入",
+          "Skill upsert 清理 null bytes，修复 PostgreSQL UTF8 错误",
+          "Connect Remote 弹窗的安装脚本 URL 修正",
+        ],
+      },
+      {
+        version: "0.2.21",
+        date: "2026-04-30",
+        title: "Quick Capture 全面升级、Mermaid 图表与 Typed Project Resources",
+        changes: [],
+        features: [
+          "Quick Capture 取代旧的 New Issue 弹窗 —— 支持连续创建、文件上传，并能根据粘贴的 URL 自动丰富标题与描述",
+          "Markdown 内联渲染 Mermaid 图表，复杂图支持全屏 lightbox",
+          "Project 支持单独绑定 repo，无需依赖 workspace 默认配置",
+          "Agent / 评论 / Runtime / Skill 全面接入权限感知 UI，没有权限的操作不再展示",
+        ],
+        improvements: [
+          "Daemon `/tasks/claim` 轮询走 Redis 空认领 fast-path，空闲态 DB 压力下降，长期 open 的 Issue 自动回收磁盘",
+          "Multica Agent 的 Git 提交自动追加 `Co-authored-by` trailer，归属更清晰",
+          "Desktop 拦截 Cmd+R / Ctrl+R / F5 防止意外刷新，开发模式与 Updates 设置中均展示真实版本号",
+        ],
+        fixes: [
+          "Quick Create 不再凭空脑补需求，并自动把发起人订阅到 Issue",
+          "Inbox 点击通知后立即跳到目标评论；从 Issue 详情页 Mark as Done 时自动归档",
+          "Task rerun 启动全新 session，跳过被污染的 resume 状态",
+          "受邀成员登录后路由到所在 workspace，不再强制带去 `/onboarding`",
+        ],
+      },
+      {
+        version: "0.2.20",
+        date: "2026-04-29",
+        title: "Create Issue by Agent、Agent Presence v3 与 Daemon WebSocket 心跳",
+        changes: [],
+        features: [
+          "Create Issue by Agent —— 按 `c` 输入一句话并选 Agent，Issue 异步创建，结果回执送达 Inbox",
+          "Agent Presence v3 —— 可用性与最近任务拆成两条更清晰的信号；Issue 详情右侧新增 Execution Log，可看到当前 active run 与历史 run",
+          "Daemon ↔ Server 心跳改走 WebSocket，HTTP 自动 fallback，任务起跑延迟更低",
+          "Mention 选择器按本机最近使用排序",
+        ],
+        improvements: [
+          "Server 用 Redis 缓存 PAT / Daemon Token 校验，大型团队不再让 DB 抗下每次请求",
+          "后端支持通过 `MULTICA_CLAUDE_ARGS` / `MULTICA_CODEX_ARGS` 配置 Agent CLI 默认参数",
+          "Manual 与 Agent 创建 Issue 共享同一个 Dialog 外壳，picker Agent 会被默认设为 assignee",
+        ],
+        fixes: [
+          "Create Issue by Agent 不再卡住 queued 任务，也不再因附件上传失败而重复创建 Issue",
+          "Agent 评论保留换行，不再渲染成字面量 `\\n`，多行回复的格式也被完整保留",
+          "Agent 自身发出的根评论不再继承父评论的 @mention，避免互相唤起的死循环",
+          "Windows 下 Cursor Agent 启动时保留多行 prompt",
+        ],
+      },
       {
         version: "0.2.19",
         date: "2026-04-28",

apps/web/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

apps/web/proxy.ts

@@ -1,4 +1,5 @@
 import { NextResponse, type NextRequest } from "next/server";
+import { matchLocale, LOCALE_COOKIE } from "@multica/core/i18n";
 
 // Old workspace-scoped route segments that existed before the URL refactor
 // (pre-#1131). Any URL with these as the FIRST segment is a legacy URL that
@@ -16,7 +17,34 @@ const LEGACY_ROUTE_SEGMENTS = new Set([
   "settings",
 ]);
 
-// Next.js 16 renamed `middleware` → `proxy`. The runtime API is identical.
+// Resolve the active locale per request. Cookie wins over Accept-Language;
+// matchLocale() falls back to DEFAULT_LOCALE when neither yields a match.
+function resolveLocale(req: NextRequest): string {
+  const cookieLocale = req.cookies.get(LOCALE_COOKIE)?.value;
+  const acceptLanguage = req.headers.get("accept-language") ?? "";
+  const candidates: string[] = [];
+  if (cookieLocale) candidates.push(cookieLocale);
+  for (const part of acceptLanguage.split(",")) {
+    const tag = part.split(";")[0]?.trim();
+    if (tag) candidates.push(tag);
+  }
+  return matchLocale(candidates);
+}
+
+// Forward the resolved locale to RSC layouts via the `x-multica-locale`
+// request header. layout.tsx reads it through `await headers()`. The
+// `request: { headers }` form is what makes the header land on the upstream
+// request — without it the value would only sit on the response.
+function nextWithLocale(req: NextRequest): NextResponse {
+  const headers = new Headers(req.headers);
+  headers.set("x-multica-locale", resolveLocale(req));
+  return NextResponse.next({ request: { headers } });
+}
+
+// Next.js 16 renamed `middleware` → `proxy`. API surface (NextRequest /
+// NextResponse / cookies / matcher) is identical; the only behavioral
+// change is the runtime — proxy is forced to nodejs and cannot opt into
+// edge.
 export function proxy(req: NextRequest) {
   const { pathname } = req.nextUrl;
   const hasSession = req.cookies.has("multica_logged_in");
@@ -48,34 +76,21 @@ export function proxy(req: NextRequest) {
   }
 
   // --- Root path: redirect logged-in users to their last workspace ---
-  if (pathname === "/") {
-    if (!hasSession) return NextResponse.next();
-
-    if (lastSlug) {
-      const url = req.nextUrl.clone();
-      url.pathname = `/${lastSlug}/issues`;
-      return NextResponse.redirect(url);
-    }
-
-    // No last_workspace_slug cookie → let landing page pick the first workspace
-    // client-side (features/landing/components/redirect-if-authenticated.tsx).
-    return NextResponse.next();
+  if (pathname === "/" && hasSession && lastSlug) {
+    const url = req.nextUrl.clone();
+    url.pathname = `/${lastSlug}/issues`;
+    return NextResponse.redirect(url);
   }
 
-  return NextResponse.next();
+  // --- Default: forward locale header to RSC, no redirect/rewrite ---
+  // Covers logged-out root path, /login, /:slug/*, and everything else.
+  return nextWithLocale(req);
 }
 
 export const config = {
-  matcher: [
-    "/",
-    "/issues/:path*",
-    "/projects/:path*",
-    "/agents/:path*",
-    "/inbox/:path*",
-    "/my-issues/:path*",
-    "/autopilots/:path*",
-    "/runtimes/:path*",
-    "/skills/:path*",
-    "/settings/:path*",
-  ],
+  // i18n header must land on every page request, so we use the standard
+  // negative-lookahead pattern from Next's i18n guide: skip API routes
+  // (Go backend), Next internals, and any path with a file extension
+  // (favicons, sw.js, public/* assets).
+  matcher: ["/((?!api|_next/static|_next/image|favicon.ico|.*\\.).*)"],
 };

apps/web/test/helpers.tsx

@@ -14,6 +14,7 @@ export const mockUser: User = {
   // Matches real server behavior for anyone who onboarded before this
   // field shipped — migration 054 backfills 'skipped_legacy'.
   starter_content_state: "skipped_legacy",
+  language: null,
   created_at: "2026-01-01T00:00:00Z",
   updated_at: "2026-01-01T00:00:00Z",
 };

docs/product-overview.md

@@ -372,7 +372,7 @@ skill
 3. **注入**：当 agent 认领任务时，daemon 把挂载的 skill 内容写到任务工作目录的 **provider 原生位置**：
    - Claude Code → `.claude/skills/{name}/SKILL.md`
    - Codex → `CODEX_HOME/skills/{name}/`
-   - OpenCode → `.config/opencode/skills/{name}/SKILL.md`
+   - OpenCode → `.opencode/skills/{name}/SKILL.md`
    - Pi → `.pi/skills/{name}/SKILL.md`
    - Cursor → `.cursor/skills/{name}/SKILL.md`
    - GitHub Copilot → `.github/skills/{name}/SKILL.md`

packages/core/agents/index.ts

@@ -5,3 +5,5 @@ export * from "./use-agent-presence";
 export * from "./use-agent-activity";
 export * from "./use-workspace-presence-prefetch";
 export * from "./constants";
+export * from "./visibility-label";
+export * from "./use-workspace-agent-availability";

packages/core/agents/use-workspace-agent-availability.ts

@@ -0,0 +1,60 @@
+"use client";
+
+import { useQuery } from "@tanstack/react-query";
+import { useWorkspaceId } from "../hooks";
+import { useAuthStore } from "../auth";
+import { agentListOptions, memberListOptions } from "../workspace/queries";
+import { canAssignAgentToIssue } from "../permissions";
+
+/**
+ * Three-state availability for "does the current user have any agent
+ * they can chat with in this workspace?".
+ *
+ * Why three states (not a boolean): the answer to "is there an agent?"
+ * lives on the server. Until the agent-list query resolves, the answer
+ * is genuinely *unknown*. Callers must distinguish "loading" from
+ * "confirmed empty" — collapsing them to a boolean causes UIs to flash
+ * disabled/empty states for the first few hundred ms after mount, even
+ * when the workspace actually has agents.
+ *
+ *   "loading"   — agent or member list still in flight (be neutral in UI)
+ *   "none"      — both queries resolved, user has zero assignable agents
+ *   "available" — at least one agent passes archive + visibility filters
+ */
+export type WorkspaceAgentAvailability = "loading" | "none" | "available";
+
+/**
+ * Mirrors the per-agent visibility/archived filter used by AssigneePicker
+ * and the chat agent dropdown, so the three pickers can never disagree on
+ * "is this agent reachable?".
+ *
+ * Members are queried because `canAssignAgentToIssue` reads the caller's
+ * role to decide visibility for `private` agents — without member data,
+ * a freshly-loaded agent list could still produce wrong answers.
+ */
+export function useWorkspaceAgentAvailability(): WorkspaceAgentAvailability {
+  const wsId = useWorkspaceId();
+  const userId = useAuthStore((s) => s.user?.id);
+  const { data: agents, isFetched: agentsFetched } = useQuery(
+    agentListOptions(wsId),
+  );
+  const { data: members, isFetched: membersFetched } = useQuery(
+    memberListOptions(wsId),
+  );
+
+  if (!agentsFetched || !membersFetched) return "loading";
+
+  const rawRole = members?.find((m) => m.user_id === userId)?.role;
+  const role =
+    rawRole === "owner" || rawRole === "admin" || rawRole === "member"
+      ? rawRole
+      : null;
+
+  const hasVisibleAgent = (agents ?? []).some(
+    (a) =>
+      !a.archived_at &&
+      canAssignAgentToIssue(a, { userId: userId ?? null, role }).allowed,
+  );
+
+  return hasVisibleAgent ? "available" : "none";
+}

packages/core/agents/visibility-label.ts

@@ -0,0 +1,31 @@
+import type { AgentVisibility } from "../types";
+
+/**
+ * Display labels for agent visibility. The DB stores `private` as the value
+ * but the UI surface name is "Personal" — better matches what the field
+ * actually means now that workspace admins can also assign private agents.
+ */
+export const VISIBILITY_LABEL: Record<AgentVisibility, string> = {
+  workspace: "Workspace",
+  private: "Personal",
+};
+
+/**
+ * Honest descriptions for assignability. The previous "Only you can assign"
+ * text was a lie — workspace owners and admins can assign private agents too
+ * (server `issue.go:1471-1490`).
+ */
+export const VISIBILITY_DESCRIPTION: Record<AgentVisibility, string> = {
+  workspace: "All members can assign",
+  private: "Only you and workspace admins can assign",
+};
+
+/** Tooltip suitable for read-only badges on hover/list rows. */
+export const VISIBILITY_TOOLTIP: Record<AgentVisibility, string> = {
+  workspace: "Workspace — all members can assign",
+  private: "Personal — only you and workspace admins can assign",
+};
+
+export function visibilityLabel(v: AgentVisibility): string {
+  return VISIBILITY_LABEL[v];
+}

packages/core/api/client.ts

@@ -42,7 +42,8 @@ import type {
   RuntimeLocalSkillListRequest,
   CreateRuntimeLocalSkillImportRequest,
   RuntimeLocalSkillImportRequest,
-  TimelineEntry,
+  TimelinePage,
+  TimelinePageParam,
   AssigneeFrequencyEntry,
   TaskMessagePayload,
   Attachment,
@@ -55,6 +56,9 @@ import type {
   CreateProjectRequest,
   UpdateProjectRequest,
   ListProjectsResponse,
+  ProjectResource,
+  CreateProjectResourceRequest,
+  ListProjectResourcesResponse,
   Label,
   CreateLabelRequest,
   UpdateLabelRequest,
@@ -75,6 +79,8 @@ import type {
   ListAutopilotsResponse,
   GetAutopilotResponse,
   ListAutopilotRunsResponse,
+  NotificationPreferenceResponse,
+  NotificationPreferences,
 } from "../types";
 import type { OnboardingCompletionPath } from "../onboarding/types";
 import { type Logger, noopLogger } from "../logger";
@@ -489,8 +495,17 @@ export class ApiClient {
     });
   }
 
-  async listTimeline(issueId: string): Promise<TimelineEntry[]> {
-    return this.fetch(`/api/issues/${issueId}/timeline`);
+  async listTimeline(
+    issueId: string,
+    pageParam: TimelinePageParam = { mode: "latest" },
+    limit = 50,
+  ): Promise<TimelinePage> {
+    const params = new URLSearchParams();
+    params.set("limit", String(limit));
+    if (pageParam.mode === "before") params.set("before", pageParam.cursor);
+    else if (pageParam.mode === "after") params.set("after", pageParam.cursor);
+    else if (pageParam.mode === "around") params.set("around", pageParam.id);
+    return this.fetch(`/api/issues/${issueId}/timeline?${params.toString()}`);
   }
 
   async getAssigneeFrequency(): Promise<AssigneeFrequencyEntry[]> {
@@ -783,6 +798,18 @@ export class ApiClient {
     return this.fetch("/api/inbox/archive-completed", { method: "POST" });
   }
 
+  // Notification preferences
+  async getNotificationPreferences(): Promise<NotificationPreferenceResponse> {
+    return this.fetch("/api/notification-preferences");
+  }
+
+  async updateNotificationPreferences(preferences: NotificationPreferences): Promise<NotificationPreferenceResponse> {
+    return this.fetch("/api/notification-preferences", {
+      method: "PUT",
+      body: JSON.stringify({ preferences }),
+    });
+  }
+
   // App Config
   async getConfig(): Promise<{
     cdn_domain: string;
@@ -992,7 +1019,7 @@ export class ApiClient {
     });
   }
 
-  async archiveChatSession(id: string): Promise<void> {
+  async deleteChatSession(id: string): Promise<void> {
     await this.fetch(`/api/chat/sessions/${id}`, { method: "DELETE" });
   }
 
@@ -1060,6 +1087,32 @@ export class ApiClient {
     await this.fetch(`/api/projects/${id}`, { method: "DELETE" });
   }
 
+  // Project resources
+  async listProjectResources(
+    projectId: string,
+  ): Promise<ListProjectResourcesResponse> {
+    return this.fetch(`/api/projects/${projectId}/resources`);
+  }
+
+  async createProjectResource(
+    projectId: string,
+    data: CreateProjectResourceRequest,
+  ): Promise<ProjectResource> {
+    return this.fetch(`/api/projects/${projectId}/resources`, {
+      method: "POST",
+      body: JSON.stringify(data),
+    });
+  }
+
+  async deleteProjectResource(
+    projectId: string,
+    resourceId: string,
+  ): Promise<void> {
+    await this.fetch(`/api/projects/${projectId}/resources/${resourceId}`, {
+      method: "DELETE",
+    });
+  }
+
   // Labels
   async listLabels(): Promise<ListLabelsResponse> {
     return this.fetch(`/api/labels`);

packages/core/chat/mutations.ts

@@ -70,14 +70,20 @@ export function useMarkChatSessionRead() {
   });
 }
 
-export function useArchiveChatSession() {
+/**
+ * Hard-deletes a chat session. Optimistically removes the row from both
+ * the active and all-sessions lists so the history panel updates instantly;
+ * rolls back on error. The matching `chat:session_deleted` WS event keeps
+ * other tabs/devices in sync — see use-realtime-sync.ts.
+ */
+export function useDeleteChatSession() {
   const qc = useQueryClient();
   const wsId = useWorkspaceId();
 
   return useMutation({
     mutationFn: (sessionId: string) => {
-      logger.info("archiveChatSession.start", { sessionId });
-      return api.archiveChatSession(sessionId);
+      logger.info("deleteChatSession.start", { sessionId });
+      return api.deleteChatSession(sessionId);
     },
     onMutate: async (sessionId) => {
       await qc.cancelQueries({ queryKey: chatKeys.sessions(wsId) });
@@ -86,26 +92,20 @@ export function useArchiveChatSession() {
       const prevSessions = qc.getQueryData<ChatSession[]>(chatKeys.sessions(wsId));
       const prevAll = qc.getQueryData<ChatSession[]>(chatKeys.allSessions(wsId));
 
-      // Optimistic: remove from active, mark as archived in allSessions
-      qc.setQueryData<ChatSession[]>(chatKeys.sessions(wsId), (old) =>
-        old ? old.filter((s) => s.id !== sessionId) : old,
-      );
-      qc.setQueryData<ChatSession[]>(chatKeys.allSessions(wsId), (old) =>
-        old?.map((s) =>
-          s.id === sessionId ? { ...s, status: "archived" as const } : s,
-        ),
-      );
+      const drop = (old?: ChatSession[]) => old?.filter((s) => s.id !== sessionId);
+      qc.setQueryData<ChatSession[]>(chatKeys.sessions(wsId), drop);
+      qc.setQueryData<ChatSession[]>(chatKeys.allSessions(wsId), drop);
 
-      logger.debug("archiveChatSession.optimistic", { sessionId });
+      logger.debug("deleteChatSession.optimistic", { sessionId });
       return { prevSessions, prevAll };
     },
     onError: (err, sessionId, ctx) => {
-      logger.error("archiveChatSession.error.rollback", { sessionId, err });
+      logger.error("deleteChatSession.error.rollback", { sessionId, err });
       if (ctx?.prevSessions) qc.setQueryData(chatKeys.sessions(wsId), ctx.prevSessions);
       if (ctx?.prevAll) qc.setQueryData(chatKeys.allSessions(wsId), ctx.prevAll);
     },
     onSettled: (_data, _err, sessionId) => {
-      logger.debug("archiveChatSession.settled", { sessionId });
+      logger.debug("deleteChatSession.settled", { sessionId });
       qc.invalidateQueries({ queryKey: chatKeys.sessions(wsId) });
       qc.invalidateQueries({ queryKey: chatKeys.allSessions(wsId) });
     },

packages/core/chat/store.ts

@@ -16,6 +16,14 @@ const CHAT_HEIGHT_KEY = "multica:chat:height";
 const CHAT_EXPANDED_KEY = "multica:chat:expanded";
 /** Focus mode is a personal preference — global across workspaces/sessions. */
 const FOCUS_MODE_KEY = "multica:chat:focusMode";
+/**
+ * Open/closed preference, persisted globally (not per-workspace) — most users
+ * have one habitual chat-panel preference across workspaces. Missing key =
+ * new user (or cleared storage); default to OPEN so the chat is discoverable.
+ * Once the user toggles even once, their explicit choice is respected on
+ * every subsequent reload.
+ */
+const OPEN_KEY = "multica:chat:isOpen";
 
 function readDrafts(storage: StorageAdapter, key: string): Record<string, string> {
   const raw = storage.getItem(key);
@@ -43,7 +51,7 @@ function writeDrafts(storage: StorageAdapter, key: string, drafts: Record<string
 
 export const CHAT_MIN_W = 360;
 export const CHAT_MIN_H = 480;
-export const CHAT_DEFAULT_W = 420;
+export const CHAT_DEFAULT_W = 380;
 export const CHAT_DEFAULT_H = 600;
 
 /**
@@ -118,8 +126,14 @@ export function createChatStore(options: ChatStoreOptions) {
     return slug ? `${base}:${slug}` : base;
   };
 
+  // Resolve initial isOpen from storage. The three-state read (null /
+  // "true" / "false") is what enables the "new user → open" default while
+  // still honouring an explicit "I closed it" choice on every reload.
+  const storedOpen = storage.getItem(OPEN_KEY);
+  const initialIsOpen = storedOpen === null ? true : storedOpen === "true";
+
   const store = create<ChatState>((set, get) => ({
-    isOpen: false,
+    isOpen: initialIsOpen,
     activeSessionId: storage.getItem(wsKey(SESSION_STORAGE_KEY)),
     selectedAgentId: storage.getItem(wsKey(AGENT_STORAGE_KEY)),
     showHistory: false,
@@ -130,11 +144,13 @@ export function createChatStore(options: ChatStoreOptions) {
     isExpanded: storage.getItem(wsKey(CHAT_EXPANDED_KEY)) === "true",
     setOpen: (open) => {
       logger.debug("setOpen", { from: get().isOpen, to: open });
+      storage.setItem(OPEN_KEY, String(open));
       set({ isOpen: open });
     },
     toggle: () => {
       const next = !get().isOpen;
       logger.debug("toggle", { to: next });
+      storage.setItem(OPEN_KEY, String(next));
       set({ isOpen: next });
     },
     setActiveSession: (id) => {

packages/core/feedback/draft-store.ts

@@ -0,0 +1,41 @@
+import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+import { createWorkspaceAwareStorage, registerForWorkspaceRehydration } from "../platform/workspace-storage";
+import { defaultStorage } from "../platform/storage";
+
+interface FeedbackDraft {
+  message: string;
+}
+
+const EMPTY_DRAFT: FeedbackDraft = {
+  message: "",
+};
+
+interface FeedbackDraftStore {
+  draft: FeedbackDraft;
+  setDraft: (patch: Partial<FeedbackDraft>) => void;
+  clearDraft: () => void;
+  hasDraft: () => boolean;
+}
+
+export const useFeedbackDraftStore = create<FeedbackDraftStore>()(
+  persist(
+    (set, get) => ({
+      draft: { ...EMPTY_DRAFT },
+      setDraft: (patch) =>
+        set((s) => ({ draft: { ...s.draft, ...patch } })),
+      clearDraft: () =>
+        set({ draft: { ...EMPTY_DRAFT } }),
+      hasDraft: () => {
+        const { draft } = get();
+        return !!draft.message;
+      },
+    }),
+    {
+      name: "multica_feedback_draft",
+      storage: createJSONStorage(() => createWorkspaceAwareStorage(defaultStorage)),
+    },
+  ),
+);
+
+registerForWorkspaceRehydration(() => useFeedbackDraftStore.persist.rehydrate());

packages/core/feedback/index.ts

@@ -1 +1,2 @@
 export * from "./mutations";
+export { useFeedbackDraftStore } from "./draft-store";

packages/core/i18n/adapter-context.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+import type { LocaleAdapter } from "./types";
+
+const LocaleAdapterContext = createContext<LocaleAdapter | null>(null);
+
+export function LocaleAdapterProvider({
+  adapter,
+  children,
+}: {
+  adapter: LocaleAdapter;
+  children: ReactNode;
+}) {
+  return (
+    <LocaleAdapterContext.Provider value={adapter}>
+      {children}
+    </LocaleAdapterContext.Provider>
+  );
+}
+
+export function useLocaleAdapter(): LocaleAdapter {
+  const ctx = useContext(LocaleAdapterContext);
+  if (!ctx) {
+    throw new Error(
+      "useLocaleAdapter must be used within <LocaleAdapterProvider>",
+    );
+  }
+  return ctx;
+}

packages/core/i18n/browser-cookie-adapter.test.ts

@@ -0,0 +1,59 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  LOCALE_COOKIE,
+  createBrowserCookieLocaleAdapter,
+} from "./browser-cookie-adapter";
+
+function clearCookies() {
+  document.cookie
+    .split(";")
+    .map((c) => c.trim().split("=")[0])
+    .filter(Boolean)
+    .forEach((name) => {
+      document.cookie = `${name}=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+    });
+}
+
+describe("createBrowserCookieLocaleAdapter", () => {
+  beforeEach(clearCookies);
+  afterEach(clearCookies);
+
+  it("getUserChoice returns null when no cookie is set", () => {
+    const adapter = createBrowserCookieLocaleAdapter();
+    expect(adapter.getUserChoice()).toBe(null);
+  });
+
+  it("getUserChoice round-trips a persisted value", () => {
+    const adapter = createBrowserCookieLocaleAdapter();
+    adapter.persist("zh-Hans");
+    expect(adapter.getUserChoice()).toBe("zh-Hans");
+  });
+
+  it("getUserChoice decodes URI-encoded cookie values", () => {
+    document.cookie = `${LOCALE_COOKIE}=${encodeURIComponent("zh-Hans")}; path=/`;
+    expect(createBrowserCookieLocaleAdapter().getUserChoice()).toBe("zh-Hans");
+  });
+
+  it("getUserChoice ignores unrelated cookies that share a prefix", () => {
+    document.cookie = `${LOCALE_COOKIE}-other=should-not-match; path=/`;
+    expect(createBrowserCookieLocaleAdapter().getUserChoice()).toBe(null);
+  });
+
+  it("persist writes a cookie with SameSite=Lax", () => {
+    const adapter = createBrowserCookieLocaleAdapter();
+    adapter.persist("en");
+    expect(document.cookie).toContain(`${LOCALE_COOKIE}=en`);
+  });
+
+  it("getSystemPreferences mirrors navigator.languages", () => {
+    Object.defineProperty(navigator, "languages", {
+      value: ["zh-Hans-CN", "en-US"],
+      configurable: true,
+    });
+    expect(createBrowserCookieLocaleAdapter().getSystemPreferences()).toEqual([
+      "zh-Hans-CN",
+      "en-US",
+    ]);
+  });
+});

packages/core/i18n/browser-cookie-adapter.ts

@@ -0,0 +1,35 @@
+import type { LocaleAdapter, SupportedLocale } from "./types";
+
+export const LOCALE_COOKIE = "multica-locale";
+const COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+
+// Web-only adapter: persists via document.cookie so the Next.js proxy can
+// read the active locale on the next request. Desktop has no server-side
+// proxy and must use createDesktopLocaleAdapter (apps/desktop/.../i18n-adapter)
+// which persists via window.localStorage instead.
+export function createBrowserCookieLocaleAdapter(): LocaleAdapter {
+  return {
+    getUserChoice() {
+      if (typeof document === "undefined") return null;
+      const m = document.cookie.match(
+        new RegExp(`(?:^|;\\s*)${LOCALE_COOKIE}=([^;]+)`),
+      );
+      const value = m?.[1];
+      return value ? decodeURIComponent(value) : null;
+    },
+    getSystemPreferences() {
+      if (typeof navigator === "undefined") return [];
+      return [...navigator.languages];
+    },
+    persist(locale: SupportedLocale) {
+      if (typeof document === "undefined") return;
+      const secure =
+        typeof location !== "undefined" && location.protocol === "https:"
+          ? ";Secure"
+          : "";
+      document.cookie =
+        `${LOCALE_COOKIE}=${encodeURIComponent(locale)};` +
+        `path=/;max-age=${COOKIE_MAX_AGE};SameSite=Lax${secure}`;
+    },
+  };
+}

packages/core/i18n/browser.ts

@@ -0,0 +1,8 @@
+// Browser-only entry: anything that touches `document` / `navigator` /
+// `window` lives here, so accidental imports from RSC, Edge middleware, or
+// nodejs proxy.ts crash at the import site instead of at first call.
+//
+// `LOCALE_COOKIE` (a plain string constant) is also exported from the
+// server-safe `@multica/core/i18n` entry — proxy.ts needs it to read the
+// cookie from a NextRequest. Only the adapter factory is browser-restricted.
+export { createBrowserCookieLocaleAdapter } from "./browser-cookie-adapter";

packages/core/i18n/create-i18n.ts

@@ -0,0 +1,23 @@
+import i18next, { type i18n as I18n } from "i18next";
+import { initReactI18next } from "react-i18next";
+import type { LocaleResources, SupportedLocale } from "./types";
+
+// Both server (RSC) and client must call this with the SAME locale + resources
+// to avoid hydration mismatch. `initAsync: false` forces synchronous init
+// (renamed from `initImmediate` in i18next v25+); `useSuspense: false`
+// prevents fallback rendering during hydration.
+export function createI18n(
+  locale: SupportedLocale,
+  resources: Record<string, LocaleResources>,
+): I18n {
+  const instance = i18next.createInstance();
+  instance.use(initReactI18next).init({
+    lng: locale,
+    fallbackLng: "en",
+    resources,
+    interpolation: { escapeValue: false },
+    initAsync: false,
+    react: { useSuspense: false },
+  });
+  return instance;
+}

packages/core/i18n/index.ts

@@ -0,0 +1,20 @@
+// Server-safe i18n entry: zero React imports + zero DOM/document/navigator
+// access anywhere in this transitive graph. Safe to import from proxy.ts /
+// RSC / Edge / nodejs middleware.
+//
+// React-side helpers (I18nProvider, useLocaleAdapter, createI18n) live in
+// "@multica/core/i18n/react" — split because Next.js gives RSC a vendored
+// React build that lacks createContext, and react-i18next's top-level
+// React.createContext() call would crash any non-client load of this file.
+//
+// Browser-only helpers (createBrowserCookieLocaleAdapter) live in
+// "@multica/core/i18n/browser" — they read document.cookie / navigator.languages
+// at construction time and would crash in any non-DOM context.
+export type {
+  LocaleAdapter,
+  LocaleResources,
+  SupportedLocale,
+} from "./types";
+export { DEFAULT_LOCALE, SUPPORTED_LOCALES } from "./types";
+export { matchLocale, pickLocale } from "./pick-locale";
+export { LOCALE_COOKIE } from "./browser-cookie-adapter";

packages/core/i18n/pick-locale.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import { matchLocale, pickLocale } from "./pick-locale";
+import type { LocaleAdapter } from "./types";
+
+function makeAdapter(
+  overrides: Partial<LocaleAdapter> = {},
+): LocaleAdapter {
+  return {
+    getUserChoice: () => null,
+    getSystemPreferences: () => [],
+    persist: () => {},
+    ...overrides,
+  };
+}
+
+describe("matchLocale", () => {
+  it("returns DEFAULT_LOCALE when given an empty list", () => {
+    expect(matchLocale([])).toBe("en");
+  });
+
+  it("matches a clean supported tag", () => {
+    expect(matchLocale(["zh-Hans"])).toBe("zh-Hans");
+    expect(matchLocale(["en"])).toBe("en");
+  });
+
+  it("collapses region-tagged BCP-47 to the supported base", () => {
+    expect(matchLocale(["en-US"])).toBe("en");
+    expect(matchLocale(["zh-Hans-CN"])).toBe("zh-Hans");
+  });
+
+  it("falls back to DEFAULT_LOCALE when no candidate matches", () => {
+    expect(matchLocale(["fr", "ja", "ko"])).toBe("en");
+  });
+
+  it("zh-Hant (traditional) collapses to zh-Hans — same base subtag, better UX than English fallback", () => {
+    expect(matchLocale(["zh-Hant"])).toBe("zh-Hans");
+  });
+
+  it("uses the first supported candidate when multiple appear", () => {
+    expect(matchLocale(["fr", "zh-Hans", "en"])).toBe("zh-Hans");
+  });
+
+  it("returns DEFAULT_LOCALE for malformed BCP-47 tags rather than throwing", () => {
+    expect(matchLocale(["----"])).toBe("en");
+    expect(matchLocale(["x-private-only"])).toBe("en");
+  });
+});
+
+describe("pickLocale", () => {
+  it("prefers explicit user choice over system signal", () => {
+    const adapter = makeAdapter({
+      getUserChoice: () => "zh-Hans",
+      getSystemPreferences: () => ["en-US"],
+    });
+    expect(pickLocale(adapter)).toBe("zh-Hans");
+  });
+
+  it("falls back to system preferences when no user choice", () => {
+    const adapter = makeAdapter({
+      getSystemPreferences: () => ["zh-Hans-CN", "en-US"],
+    });
+    expect(pickLocale(adapter)).toBe("zh-Hans");
+  });
+
+  it("returns DEFAULT_LOCALE when neither choice nor preference yields a match", () => {
+    const adapter = makeAdapter({
+      getUserChoice: () => null,
+      getSystemPreferences: () => ["fr", "ja"],
+    });
+    expect(pickLocale(adapter)).toBe("en");
+  });
+
+  it("ignores empty-string user choice and falls through to system", () => {
+    const adapter = makeAdapter({
+      getUserChoice: () => "",
+      getSystemPreferences: () => ["zh-Hans"],
+    });
+    expect(pickLocale(adapter)).toBe("zh-Hans");
+  });
+});

packages/core/i18n/pick-locale.ts

@@ -0,0 +1,26 @@
+import { match } from "@formatjs/intl-localematcher";
+import {
+  DEFAULT_LOCALE,
+  SUPPORTED_LOCALES,
+  type LocaleAdapter,
+  type SupportedLocale,
+} from "./types";
+
+export function matchLocale(candidates: string[]): SupportedLocale {
+  if (candidates.length === 0) return DEFAULT_LOCALE;
+  try {
+    return match(
+      candidates,
+      SUPPORTED_LOCALES,
+      DEFAULT_LOCALE,
+    ) as SupportedLocale;
+  } catch {
+    return DEFAULT_LOCALE;
+  }
+}
+
+export function pickLocale(adapter: LocaleAdapter): SupportedLocale {
+  const choice = adapter.getUserChoice();
+  if (choice) return matchLocale([choice]);
+  return matchLocale(adapter.getSystemPreferences());
+}

packages/core/i18n/provider.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import { useState, type ReactNode } from "react";
+import { I18nextProvider } from "react-i18next";
+import { createI18n } from "./create-i18n";
+import type { LocaleResources, SupportedLocale } from "./types";
+
+export interface I18nProviderProps {
+  locale: SupportedLocale;
+  resources: Record<string, LocaleResources>;
+  children: ReactNode;
+}
+
+export function I18nProvider({
+  locale,
+  resources,
+  children,
+}: I18nProviderProps) {
+  // Lazy init via useState so the instance survives re-renders.
+  // Locale + resources are determined at boot and never change at runtime —
+  // language switching goes through window.location.reload().
+  const [instance] = useState(() => createI18n(locale, resources));
+  return <I18nextProvider i18n={instance}>{children}</I18nextProvider>;
+}

packages/core/i18n/react.ts

@@ -0,0 +1,9 @@
+// React-only i18n entry: depends on react-i18next, which calls
+// React.createContext() at module load. Importing this from a non-client
+// context (RSC / proxy.ts) will crash with "createContext is not a function"
+// because Next.js vendors a stripped React build for those contexts.
+// Always pair with "use client" or import only inside client trees.
+export { createI18n } from "./create-i18n";
+export { I18nProvider, type I18nProviderProps } from "./provider";
+export { LocaleAdapterProvider, useLocaleAdapter } from "./adapter-context";
+export { UserLocaleSync } from "./user-locale-sync";

packages/core/i18n/types.ts

@@ -0,0 +1,12 @@
+export type SupportedLocale = "en" | "zh-Hans";
+
+export const SUPPORTED_LOCALES: SupportedLocale[] = ["en", "zh-Hans"];
+export const DEFAULT_LOCALE: SupportedLocale = "en";
+
+export type LocaleResources = Record<string, Record<string, unknown>>;
+
+export interface LocaleAdapter {
+  getUserChoice(): string | null;
+  getSystemPreferences(): string[];
+  persist(locale: SupportedLocale): void;
+}

packages/core/i18n/user-locale-sync.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import { useEffect } from "react";
+import { useTranslation } from "react-i18next";
+import { useAuthStore } from "../auth";
+import { useLocaleAdapter } from "./adapter-context";
+import { SUPPORTED_LOCALES, type SupportedLocale } from "./types";
+
+// Pulls the server-stored `user.language` into the local locale adapter on
+// login. Without this, switching device (macOS → Windows, browser → desktop)
+// loses the user's language preference: pickLocale only consults the local
+// adapter (cookie / localStorage), never user.language.
+//
+// Mounts inside CoreProvider so it has access to the auth store + locale
+// adapter + i18n instance. Renders nothing.
+//
+// Loop safety: reload only fires when user.language is a supported locale AND
+// differs from the active i18n.language. After reload, pickLocale reads the
+// freshly-persisted value from the adapter, locales match, effect no-ops.
+export function UserLocaleSync() {
+  const userLanguage = useAuthStore((s) => s.user?.language ?? null);
+  const adapter = useLocaleAdapter();
+  const { i18n } = useTranslation();
+
+  useEffect(() => {
+    if (!userLanguage) return;
+    if (!(SUPPORTED_LOCALES as readonly string[]).includes(userLanguage)) {
+      return;
+    }
+    if (userLanguage === i18n.language) return;
+    adapter.persist(userLanguage as SupportedLocale);
+    if (typeof window !== "undefined") window.location.reload();
+  }, [userLanguage, i18n.language, adapter]);
+
+  return null;
+}

packages/core/issues/mutations.ts

@@ -23,6 +23,12 @@ import type {
   ListIssuesCache,
 } from "../types";
 import type { TimelineEntry, IssueSubscriber, Reaction } from "../types";
+import {
+  mapAllEntries,
+  filterAllEntries,
+  prependToLatestPage,
+  type TimelineCacheData,
+} from "./timeline-cache";
 
 // ---------------------------------------------------------------------------
 // Shared mutation variable types — used by both mutation hooks and
@@ -312,26 +318,27 @@ export function useCreateComment(issueId: string) {
       attachmentIds?: string[];
     }) => api.createComment(issueId, content, type, parentId, attachmentIds),
     onSuccess: (comment) => {
-      qc.setQueryData<TimelineEntry[]>(
-        issueKeys.timeline(issueId),
-        (old) => {
-          if (!old) return old;
-          const entry: TimelineEntry = {
-            type: "comment",
-            id: comment.id,
-            actor_type: comment.author_type,
-            actor_id: comment.author_id,
-            content: comment.content,
-            parent_id: comment.parent_id,
-            comment_type: comment.type,
-            reactions: comment.reactions ?? [],
-            attachments: comment.attachments ?? [],
-            created_at: comment.created_at,
-            updated_at: comment.updated_at,
-          };
-          if (old.some((e) => e.id === comment.id)) return old;
-          return [...old, entry];
-        },
+      // Write into every paginated timeline cache that's currently at-latest
+      // (around-mode caches viewing older windows skip silently inside
+      // prependToLatestPage). Both the latest cache and any open around-mode
+      // window that has been scrolled all the way to the live tail get the
+      // optimistic entry; everything else falls back to invalidation.
+      const entry: TimelineEntry = {
+        type: "comment",
+        id: comment.id,
+        actor_type: comment.author_type,
+        actor_id: comment.author_id,
+        content: comment.content,
+        parent_id: comment.parent_id,
+        comment_type: comment.type,
+        reactions: comment.reactions ?? [],
+        attachments: comment.attachments ?? [],
+        created_at: comment.created_at,
+        updated_at: comment.updated_at,
+      };
+      qc.setQueriesData<TimelineCacheData>(
+        { queryKey: ["issues", "timeline", issueId] },
+        (old) => prependToLatestPage(old, entry),
       );
     },
     onSettled: () => {
@@ -346,18 +353,27 @@ export function useUpdateComment(issueId: string) {
     mutationFn: ({ commentId, content }: { commentId: string; content: string }) =>
       api.updateComment(commentId, content),
     onMutate: async ({ commentId, content }) => {
-      await qc.cancelQueries({ queryKey: issueKeys.timeline(issueId) });
-      const prev = qc.getQueryData<TimelineEntry[]>(issueKeys.timeline(issueId));
-      qc.setQueryData<TimelineEntry[]>(
-        issueKeys.timeline(issueId),
+      await qc.cancelQueries({ queryKey: ["issues", "timeline", issueId] });
+      // Snapshot every open timeline cache (latest + any around windows) so
+      // an error rollback restores them all atomically.
+      const prevSnapshots = qc.getQueriesData<TimelineCacheData>({
+        queryKey: ["issues", "timeline", issueId],
+      });
+      qc.setQueriesData<TimelineCacheData>(
+        { queryKey: ["issues", "timeline", issueId] },
         (old) =>
-          old?.map((e) => (e.id === commentId ? { ...e, content } : e)),
+          mapAllEntries(old, (e) =>
+            e.id === commentId ? { ...e, content } : e,
+          ),
       );
-      return { prev };
+      return { prevSnapshots };
     },
     onError: (_err, _vars, ctx) => {
-      if (ctx?.prev)
-        qc.setQueryData(issueKeys.timeline(issueId), ctx.prev);
+      if (ctx?.prevSnapshots) {
+        for (const [key, prev] of ctx.prevSnapshots) {
+          qc.setQueryData(key, prev);
+        }
+      }
     },
     onSettled: () => {
       qc.invalidateQueries({ queryKey: issueKeys.timeline(issueId) });
@@ -370,33 +386,45 @@ export function useDeleteComment(issueId: string) {
   return useMutation({
     mutationFn: (commentId: string) => api.deleteComment(commentId),
     onMutate: async (commentId) => {
-      await qc.cancelQueries({ queryKey: issueKeys.timeline(issueId) });
-      const prev = qc.getQueryData<TimelineEntry[]>(issueKeys.timeline(issueId));
+      await qc.cancelQueries({ queryKey: ["issues", "timeline", issueId] });
+      const prevSnapshots = qc.getQueriesData<TimelineCacheData>({
+        queryKey: ["issues", "timeline", issueId],
+      });
 
-      // Cascade: collect all child comment IDs
+      // Cascade: collect all child comment IDs across every loaded page.
       const toRemove = new Set<string>([commentId]);
-      if (prev) {
+      for (const [, data] of prevSnapshots) {
+        if (!data) continue;
         let changed = true;
         while (changed) {
           changed = false;
-          for (const e of prev) {
-            if (e.parent_id && toRemove.has(e.parent_id) && !toRemove.has(e.id)) {
-              toRemove.add(e.id);
-              changed = true;
+          for (const page of data.pages) {
+            for (const e of page.entries) {
+              if (
+                e.parent_id &&
+                toRemove.has(e.parent_id) &&
+                !toRemove.has(e.id)
+              ) {
+                toRemove.add(e.id);
+                changed = true;
+              }
             }
           }
         }
       }
 
-      qc.setQueryData<TimelineEntry[]>(
-        issueKeys.timeline(issueId),
-        (old) => old?.filter((e) => !toRemove.has(e.id)),
+      qc.setQueriesData<TimelineCacheData>(
+        { queryKey: ["issues", "timeline", issueId] },
+        (old) => filterAllEntries(old, (e) => toRemove.has(e.id)),
       );
-      return { prev };
+      return { prevSnapshots };
     },
     onError: (_err, _id, ctx) => {
-      if (ctx?.prev)
-        qc.setQueryData(issueKeys.timeline(issueId), ctx.prev);
+      if (ctx?.prevSnapshots) {
+        for (const [key, prev] of ctx.prevSnapshots) {
+          qc.setQueryData(key, prev);
+        }
+      }
     },
     onSettled: () => {
       qc.invalidateQueries({ queryKey: issueKeys.timeline(issueId) });

packages/core/issues/queries.ts

@@ -1,6 +1,12 @@
-import { queryOptions } from "@tanstack/react-query";
+import { infiniteQueryOptions, queryOptions } from "@tanstack/react-query";
 import { api } from "../api";
-import type { IssueStatus, ListIssuesParams, ListIssuesCache } from "../types";
+import type {
+  IssueStatus,
+  ListIssuesParams,
+  ListIssuesCache,
+  TimelinePage,
+  TimelinePageParam,
+} from "../types";
 import { BOARD_STATUSES } from "./config";
 
 export const issueKeys = {
@@ -17,7 +23,15 @@ export const issueKeys = {
     [...issueKeys.all(wsId), "children", id] as const,
   childProgress: (wsId: string) =>
     [...issueKeys.all(wsId), "child-progress"] as const,
-  timeline: (issueId: string) => ["issues", "timeline", issueId] as const,
+  /**
+   * Cursor-paginated timeline cache. Around-mode lookups use a separate cache
+   * (keyed by the anchor id) so an Inbox-jump fetch does not pollute the
+   * default latest-page cache that the regular issue list path consumes.
+   */
+  timeline: (issueId: string, around?: string | null) =>
+    around
+      ? (["issues", "timeline", issueId, "around", around] as const)
+      : (["issues", "timeline", issueId] as const),
   reactions: (issueId: string) => ["issues", "reactions", issueId] as const,
   subscribers: (issueId: string) =>
     ["issues", "subscribers", issueId] as const,
@@ -126,10 +140,40 @@ export function childIssuesOptions(wsId: string, id: string) {
   });
 }
 
-export function issueTimelineOptions(issueId: string) {
-  return queryOptions({
-    queryKey: issueKeys.timeline(issueId),
-    queryFn: () => api.listTimeline(issueId),
+/**
+ * Infinite-query options for the cursor-paginated timeline. The first page is
+ * either the latest 50 entries (no `around`) or a 50-wide window centered on
+ * the given comment/activity id (Inbox jump path). `getNextPageParam` walks
+ * older; `getPreviousPageParam` walks newer.
+ */
+export function issueTimelineInfiniteOptions(
+  issueId: string,
+  around?: string | null,
+) {
+  return infiniteQueryOptions<
+    TimelinePage,
+    Error,
+    { pages: TimelinePage[]; pageParams: TimelinePageParam[] },
+    readonly unknown[],
+    TimelinePageParam
+  >({
+    queryKey: issueKeys.timeline(issueId, around ?? null),
+    initialPageParam: around
+      ? ({ mode: "around", id: around } as TimelinePageParam)
+      : ({ mode: "latest" } as TimelinePageParam),
+    queryFn: ({ pageParam }) => api.listTimeline(issueId, pageParam),
+    // Walk older: append a page below the current oldest (last entry of the
+    // last loaded page). undefined = no more older entries.
+    getNextPageParam: (lastPage) =>
+      lastPage.has_more_before && lastPage.next_cursor
+        ? ({ mode: "before", cursor: lastPage.next_cursor } as TimelinePageParam)
+        : undefined,
+    // Walk newer: prepend a page above the current newest (first entry of the
+    // first loaded page). undefined = at the latest, no newer to fetch.
+    getPreviousPageParam: (firstPage) =>
+      firstPage.has_more_after && firstPage.prev_cursor
+        ? ({ mode: "after", cursor: firstPage.prev_cursor } as TimelinePageParam)
+        : undefined,
   });
 }
 

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

@@ -0,0 +1,26 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { useQuickCreateStore } from "./quick-create-store";
+
+const RESET_STATE = {
+  lastAgentId: null,
+  prompt: "",
+  keepOpen: false,
+};
+
+describe("quick create store", () => {
+  beforeEach(() => {
+    useQuickCreateStore.setState(RESET_STATE);
+  });
+
+  it("persists the agent prompt draft until explicitly cleared", () => {
+    const { setPrompt, clearPrompt } = useQuickCreateStore.getState();
+
+    setPrompt("Investigate the inbox loading regression");
+    expect(useQuickCreateStore.getState().prompt).toBe(
+      "Investigate the inbox loading regression",
+    );
+
+    clearPrompt();
+    expect(useQuickCreateStore.getState().prompt).toBe("");
+  });
+});

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

@@ -15,6 +15,11 @@ import { defaultStorage } from "../../platform/storage";
 interface QuickCreateState {
   lastAgentId: string | null;
   setLastAgentId: (id: string | null) => void;
+  prompt: string;
+  setPrompt: (prompt: string) => void;
+  clearPrompt: () => void;
+  keepOpen: boolean;
+  setKeepOpen: (v: boolean) => void;
 }
 
 export const useQuickCreateStore = create<QuickCreateState>()(
@@ -22,6 +27,11 @@ export const useQuickCreateStore = create<QuickCreateState>()(
     (set) => ({
       lastAgentId: null,
       setLastAgentId: (id) => set({ lastAgentId: id }),
+      prompt: "",
+      setPrompt: (prompt) => set({ prompt }),
+      clearPrompt: () => set({ prompt: "" }),
+      keepOpen: false,
+      setKeepOpen: (v) => set({ keepOpen: v }),
     }),
     {
       name: "multica_quick_create",

packages/core/issues/timeline-cache.ts

@@ -0,0 +1,73 @@
+import type { InfiniteData } from "@tanstack/react-query";
+import type {
+  TimelineEntry,
+  TimelinePage,
+  TimelinePageParam,
+} from "../types";
+
+/** Shape of the cursor-paginated timeline cache. Exported so consumers (the
+ *  hook, mutations, tests) all reference the same type. */
+export type TimelineCacheData = InfiniteData<TimelinePage, TimelinePageParam>;
+
+/** Map fn over every entry across every page, preserving page identity for
+ *  any page whose entries don't change so React.memo on CommentCard isn't
+ *  defeated by gratuitous reference churn. */
+export function mapAllEntries(
+  data: TimelineCacheData | undefined,
+  fn: (e: TimelineEntry) => TimelineEntry,
+): TimelineCacheData | undefined {
+  if (!data) return data;
+  let pagesChanged = false;
+  const pages = data.pages.map((page) => {
+    let entriesChanged = false;
+    const entries = page.entries.map((e) => {
+      const next = fn(e);
+      if (next !== e) entriesChanged = true;
+      return next;
+    });
+    if (!entriesChanged) return page;
+    pagesChanged = true;
+    return { ...page, entries };
+  });
+  if (!pagesChanged) return data;
+  return { ...data, pages };
+}
+
+/** Filter out entries matching the predicate from every page. */
+export function filterAllEntries(
+  data: TimelineCacheData | undefined,
+  predicate: (e: TimelineEntry) => boolean,
+): TimelineCacheData | undefined {
+  if (!data) return data;
+  let pagesChanged = false;
+  const pages = data.pages.map((page) => {
+    const entries = page.entries.filter((e) => !predicate(e));
+    if (entries.length === page.entries.length) return page;
+    pagesChanged = true;
+    return { ...page, entries };
+  });
+  if (!pagesChanged) return data;
+  return { ...data, pages };
+}
+
+/** Prepend a new entry to the latest page (pages[0]). Caller must verify
+ *  the cache is at-latest before calling — otherwise the entry is hidden
+ *  behind a "show newer" gap and shouldn't be injected. Returns the data
+ *  unchanged if the cache is not at-latest or the entry already exists. */
+export function prependToLatestPage(
+  data: TimelineCacheData | undefined,
+  entry: TimelineEntry,
+): TimelineCacheData | undefined {
+  if (!data || data.pages.length === 0) return data;
+  const first = data.pages[0];
+  if (!first) return data;
+  if (first.has_more_after) return data; // not at latest; skip silently
+  if (first.entries.some((e) => e.id === entry.id)) return data;
+  return {
+    ...data,
+    pages: [
+      { ...first, entries: [entry, ...first.entries] },
+      ...data.pages.slice(1),
+    ],
+  };
+}

packages/core/issues/ws-updaters.test.ts

@@ -0,0 +1,95 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { QueryClient } from "@tanstack/react-query";
+import { onIssueLabelsChanged } from "./ws-updaters";
+import { issueKeys } from "./queries";
+import { labelKeys } from "../labels/queries";
+import type {
+  Issue,
+  IssueLabelsResponse,
+  Label,
+  ListIssuesCache,
+} from "../types";
+
+const WS_ID = "ws-1";
+const ISSUE_ID = "issue-1";
+
+const labelA: Label = {
+  id: "label-a",
+  workspace_id: WS_ID,
+  name: "bug",
+  color: "#ef4444",
+  created_at: "2025-01-01T00:00:00Z",
+  updated_at: "2025-01-01T00:00:00Z",
+};
+
+const labelB: Label = {
+  id: "label-b",
+  workspace_id: WS_ID,
+  name: "feature",
+  color: "#22c55e",
+  created_at: "2025-01-01T00:00:00Z",
+  updated_at: "2025-01-01T00:00:00Z",
+};
+
+const baseIssue: Issue = {
+  id: ISSUE_ID,
+  workspace_id: WS_ID,
+  number: 1,
+  identifier: "MUL-1",
+  title: "Test",
+  description: null,
+  status: "todo",
+  priority: "none",
+  assignee_type: null,
+  assignee_id: null,
+  creator_type: "member",
+  creator_id: "user-1",
+  parent_issue_id: null,
+  project_id: null,
+  position: 0,
+  due_date: null,
+  labels: [labelA],
+  created_at: "2025-01-01T00:00:00Z",
+  updated_at: "2025-01-01T00:00:00Z",
+};
+
+describe("onIssueLabelsChanged", () => {
+  let qc: QueryClient;
+
+  beforeEach(() => {
+    qc = new QueryClient();
+  });
+
+  it("patches the per-issue label cache when present (LabelPicker source)", () => {
+    qc.setQueryData<IssueLabelsResponse>(labelKeys.byIssue(WS_ID, ISSUE_ID), {
+      labels: [labelA],
+    });
+
+    onIssueLabelsChanged(qc, WS_ID, ISSUE_ID, [labelB]);
+
+    expect(
+      qc.getQueryData<IssueLabelsResponse>(labelKeys.byIssue(WS_ID, ISSUE_ID)),
+    ).toEqual({ labels: [labelB] });
+  });
+
+  it("leaves the per-issue label cache untouched when the picker has not fetched", () => {
+    onIssueLabelsChanged(qc, WS_ID, ISSUE_ID, [labelB]);
+
+    expect(qc.getQueryData(labelKeys.byIssue(WS_ID, ISSUE_ID))).toBeUndefined();
+  });
+
+  it("still patches the list and detail caches", () => {
+    qc.setQueryData<ListIssuesCache>(issueKeys.list(WS_ID), {
+      byStatus: { todo: { issues: [baseIssue], total: 1 } },
+    });
+    qc.setQueryData<Issue>(issueKeys.detail(WS_ID, ISSUE_ID), baseIssue);
+
+    onIssueLabelsChanged(qc, WS_ID, ISSUE_ID, [labelB]);
+
+    const list = qc.getQueryData<ListIssuesCache>(issueKeys.list(WS_ID));
+    expect(list?.byStatus.todo?.issues[0]?.labels).toEqual([labelB]);
+
+    const detail = qc.getQueryData<Issue>(issueKeys.detail(WS_ID, ISSUE_ID));
+    expect(detail?.labels).toEqual([labelB]);
+  });
+});

packages/core/issues/ws-updaters.ts

@@ -1,12 +1,13 @@
 import type { QueryClient } from "@tanstack/react-query";
 import { issueKeys } from "./queries";
+import { labelKeys } from "../labels/queries";
 import {
   addIssueToBuckets,
   findIssueLocation,
   patchIssueInBuckets,
   removeIssueFromBuckets,
 } from "./cache-helpers";
-import type { Issue, Label } from "../types";
+import type { Issue, IssueLabelsResponse, Label } from "../types";
 import type { ListIssuesCache } from "../types";
 
 export function onIssueCreated(
@@ -73,9 +74,15 @@ export function onIssueUpdated(
 }
 
 /**
- * Patch an issue's `labels` field in-place across the list cache, my-issues
- * caches, and the detail cache. Triggered by the `issue_labels:changed` WS
- * event after attach/detach so list/board chips update without a refetch.
+ * Patch an issue's labels in-place across the list cache, my-issues caches,
+ * the detail cache, and the per-issue label cache. Triggered by the
+ * `issue_labels:changed` WS event after attach/detach so list/board chips
+ * and the issue-detail Properties LabelPicker update without a refetch.
+ *
+ * The byIssue cache backs `LabelPicker`; without patching it, externally
+ * driven label changes (agents, other tabs) leave the picker stale until it
+ * remounts — `staleTime: Infinity` + `refetchOnWindowFocus: false` (see
+ * `query-client.ts`) means focus changes won't recover it.
  */
 export function onIssueLabelsChanged(
   qc: QueryClient,
@@ -89,6 +96,9 @@ export function onIssueLabelsChanged(
   qc.setQueryData<Issue>(issueKeys.detail(wsId, issueId), (old) =>
     old ? { ...old, labels } : old,
   );
+  qc.setQueryData<IssueLabelsResponse>(labelKeys.byIssue(wsId, issueId), (old) =>
+    old ? { ...old, labels } : old,
+  );
   qc.invalidateQueries({ queryKey: issueKeys.myAll(wsId) });
 }
 

packages/core/notification-preferences/index.ts

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

packages/core/notification-preferences/mutations.ts

@@ -0,0 +1,34 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { api } from "../api";
+import { useWorkspaceId } from "../hooks";
+import { notificationPreferenceKeys } from "./queries";
+import type { NotificationPreferences, NotificationPreferenceResponse } from "../types";
+
+export function useUpdateNotificationPreferences() {
+  const qc = useQueryClient();
+  const wsId = useWorkspaceId();
+
+  return useMutation({
+    mutationFn: (preferences: NotificationPreferences) =>
+      api.updateNotificationPreferences(preferences),
+    onMutate: async (preferences) => {
+      await qc.cancelQueries({ queryKey: notificationPreferenceKeys.all(wsId) });
+      const prev = qc.getQueryData<NotificationPreferenceResponse>(
+        notificationPreferenceKeys.all(wsId),
+      );
+      qc.setQueryData<NotificationPreferenceResponse>(
+        notificationPreferenceKeys.all(wsId),
+        (old) => old ? { ...old, preferences } : { workspace_id: wsId, preferences },
+      );
+      return { prev };
+    },
+    onError: (_err, _vars, ctx) => {
+      if (ctx?.prev) {
+        qc.setQueryData(notificationPreferenceKeys.all(wsId), ctx.prev);
+      }
+    },
+    onSettled: () => {
+      qc.invalidateQueries({ queryKey: notificationPreferenceKeys.all(wsId) });
+    },
+  });
+}

packages/core/notification-preferences/queries.ts

@@ -0,0 +1,13 @@
+import { queryOptions } from "@tanstack/react-query";
+import { api } from "../api";
+
+export const notificationPreferenceKeys = {
+  all: (wsId: string) => ["notification-preferences", wsId] as const,
+};
+
+export function notificationPreferenceOptions(wsId: string) {
+  return queryOptions({
+    queryKey: notificationPreferenceKeys.all(wsId),
+    queryFn: () => api.getNotificationPreferences(),
+  });
+}

packages/core/onboarding/types.ts

@@ -16,7 +16,8 @@ export type OnboardingCompletionPath =
   | "full" // Reached Step 5 (first_issue) with a runtime connected
   | "runtime_skipped" // Step 3 skipped (no runtime) but still completed
   | "cloud_waitlist" // Submitted the cloud waitlist form and skipped Step 3
-  | "skip_existing"; // "I've done this before" from Welcome
+  | "skip_existing" // "I've done this before" from Welcome
+  | "invite_accept"; // Accepted at least one invite from /invitations
 
 export type TeamSize = "solo" | "team" | "other";
 

packages/core/package.json

@@ -24,6 +24,7 @@
     "./issues": "./issues/index.ts",
     "./issues/queries": "./issues/queries.ts",
     "./issues/mutations": "./issues/mutations.ts",
+    "./issues/timeline-cache": "./issues/timeline-cache.ts",
     "./issues/ws-updaters": "./issues/ws-updaters.ts",
     "./issues/config": "./issues/config/index.ts",
     "./issues/config/status": "./issues/config/status.ts",
@@ -35,6 +36,9 @@
     "./inbox/queries": "./inbox/queries.ts",
     "./inbox/mutations": "./inbox/mutations.ts",
     "./inbox/ws-updaters": "./inbox/ws-updaters.ts",
+    "./notification-preferences": "./notification-preferences/index.ts",
+    "./notification-preferences/queries": "./notification-preferences/queries.ts",
+    "./notification-preferences/mutations": "./notification-preferences/mutations.ts",
     "./chat": "./chat/index.ts",
     "./chat/queries": "./chat/queries.ts",
     "./chat/mutations": "./chat/mutations.ts",
@@ -46,6 +50,8 @@
     "./agents/queries": "./agents/queries.ts",
     "./agents/derive-presence": "./agents/derive-presence.ts",
     "./agents/use-agent-presence": "./agents/use-agent-presence.ts",
+    "./agents/visibility-label": "./agents/visibility-label.ts",
+    "./permissions": "./permissions/index.ts",
     "./projects": "./projects/index.ts",
     "./projects/queries": "./projects/queries.ts",
     "./projects/mutations": "./projects/mutations.ts",
@@ -74,12 +80,18 @@
     "./utils": "./utils.ts",
     "./constants/*": "./constants/*.ts",
     "./platform": "./platform/index.ts",
-    "./analytics": "./analytics/index.ts"
+    "./analytics": "./analytics/index.ts",
+    "./i18n": "./i18n/index.ts",
+    "./i18n/react": "./i18n/react.ts",
+    "./i18n/browser": "./i18n/browser.ts"
   },
   "dependencies": {
+    "@formatjs/intl-localematcher": "catalog:",
     "@tanstack/react-query": "catalog:",
     "@tanstack/react-query-devtools": "^5.96.2",
+    "i18next": "catalog:",
     "posthog-js": "catalog:",
+    "react-i18next": "catalog:",
     "zustand": "catalog:"
   },
   "peerDependencies": {
@@ -88,6 +100,7 @@
   "devDependencies": {
     "@multica/tsconfig": "workspace:*",
     "@types/react": "catalog:",
+    "jsdom": "catalog:",
     "typescript": "catalog:",
     "vitest": "catalog:"
   }