refactor(issues): align execution log rows with the chat hover-swap pattern

- Drop the fixed w-20 status column that forced premature truncation of
  the trigger text and left a mid-row gap; status now sizes to content.
- Running tasks render only the spinner (sr-only label retained for a11y
  and tooltip); the redundant "Working" text is removed.
- Hover swaps status for actions in place (RowStatus hidden, RowActions
  inline) instead of an absolute gradient overlay. Applies to both
  active and past ("show past runs") rows via the shared RowShell /
  RowStatus / RowActions.

Known tradeoff: dropping the absolute+opacity slot also drops the
group-focus-within keyboard reveal, so cancel/retry are no longer
Tab-reachable. Matches the chat pattern; revisit if keyboard access for
row actions becomes a requirement.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.agents/skills/web-design-guidelines/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: web-design-guidelines
+description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
+metadata:
+  author: vercel
+  version: "1.0.0"
+  argument-hint: <file-or-pattern>
+---
+
+# Web Interface Guidelines
+
+Review files for compliance with Web Interface Guidelines.
+
+## How It Works
+
+1. Fetch the latest guidelines from the source URL below
+2. Read the specified files (or prompt user for files/pattern)
+3. Check against all rules in the fetched guidelines
+4. Output findings in the terse `file:line` format
+
+## Guidelines Source
+
+Fetch fresh guidelines before each review:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+
+## Usage
+
+When a user provides a file or pattern argument:
+1. Fetch guidelines from the source URL above
+2. Read the specified files
+3. Apply all rules from the fetched guidelines
+4. Output findings using the format specified in the guidelines
+
+If no files specified, ask the user which files to review.

.env.example

@@ -21,14 +21,40 @@ APP_ENV=
 # 888888 and keep APP_ENV non-production. This is ignored when APP_ENV=production.
 MULTICA_DEV_VERIFICATION_CODE=
 PORT=8080
+# Optional aliases for the local/self-host backend port. If one is set, it
+# takes precedence over PORT in compose, Makefile, and installer helpers.
+# BACKEND_PORT=8080
+# API_PORT=8080
+# SERVER_PORT=8080
 # Prometheus metrics are disabled by default. When enabled, bind to loopback
 # unless you protect the listener with private networking, allowlists, or
 # proxy auth. Do not expose this endpoint through the public app/API ingress.
 # HTTP request metrics start accumulating only when this listener is enabled.
 # METRICS_ADDR=127.0.0.1:9090
 JWT_SECRET=change-me-in-production
-MULTICA_SERVER_URL=ws://localhost:8080/ws
-MULTICA_APP_URL=http://localhost:3000
+# Derived by Makefile / local scripts from the backend port.
+# Set explicitly only when the daemon reaches the API through a different URL.
+# MULTICA_SERVER_URL=ws://localhost:8080/ws
+# Derived by docker-compose.selfhost.yml / local scripts from FRONTEND_PORT.
+# Set explicitly only when the app's public URL differs from local frontend.
+# MULTICA_APP_URL=http://localhost:3000
+# Public URL the API is reachable at from the open internet (no trailing
+# slash). Used to mint absolute webhook URLs for autopilot webhook
+# triggers and to show correct daemon setup commands in the web UI. Leave
+# unset behind a same-origin reverse proxy or for plain localhost dev —
+# the frontend will compose the URL from window.origin + webhook_path in
+# that case. Headers are intentionally not used to derive this value, to
+# avoid Host / X-Forwarded-Host spoofing when a self-hosted reverse proxy
+# is not hardened.
+MULTICA_PUBLIC_URL=
+# Comma-separated CIDR list of reverse proxies whose X-Forwarded-For /
+# X-Real-IP headers the per-IP webhook rate limiter is allowed to trust.
+# Empty (the default) means "trust no headers" — the limiter uses
+# r.RemoteAddr only, which is the safe shape when the backend is
+# exposed directly. Set this when running behind nginx/Caddy/Cloudflare:
+# e.g. "127.0.0.1/32" for a same-host reverse proxy, or the CDN's
+# announced ranges for cloud deployments.
+MULTICA_TRUSTED_PROXIES=
 MULTICA_DAEMON_CONFIG=
 MULTICA_WORKSPACE_ID=
 MULTICA_DAEMON_ID=
@@ -63,11 +89,18 @@ RESEND_FROM_EMAIL=noreply@multica.ai
 #   Takes priority over Resend when SMTP_HOST is set.
 #   Supports unauthenticated relay (leave SMTP_USERNAME empty) and authenticated SMTP.
 #   Set SMTP_TLS_INSECURE=true only for private CA or self-signed certificates.
+#   SMTP_TLS controls the TLS mode:
+#     - unset / "starttls" (default): plaintext connect, upgrade via STARTTLS.
+#     - "implicit" (aliases: "smtps", "ssl"): TLS handshake on connect (SMTPS).
+#       Required by providers that only offer port 465 and do not advertise
+#       STARTTLS (e.g. Aliyun enterprise mail). Auto-enabled when SMTP_PORT=465
+#       and SMTP_TLS is unset.
 SMTP_HOST=
 SMTP_PORT=25
 SMTP_USERNAME=
 SMTP_PASSWORD=
 SMTP_TLS_INSECURE=false
+SMTP_TLS=
 
 # Google OAuth
 # The web login page reads GOOGLE_CLIENT_ID from /api/config at runtime, so
@@ -75,7 +108,9 @@ SMTP_TLS_INSECURE=false
 # rebuild is needed.
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
-GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
+# Derived by docker-compose.selfhost.yml / local scripts from FRONTEND_PORT.
+# Set explicitly only when your OAuth callback URL differs from local frontend.
+# GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
 
 # S3 / CloudFront
 # S3_BUCKET — bucket NAME only (e.g. "my-bucket"). Do NOT include the
@@ -96,15 +131,46 @@ CLOUDFRONT_DOMAIN=
 # attribute and browsers silently drop such cookies.
 COOKIE_DOMAIN=
 
+# AUTH_TOKEN_TTL — auth token lifetime. Accepts Go duration strings (e.g.
+# "8760h", "720h30m") or plain integer seconds.
+# Default: 2592000 (30 days). Self-hosted deployments on trusted networks can
+# set a longer value to reduce re-authentication frequency.
+# Note: longer TTL = longer exposure window if a cookie is leaked.
+# AUTH_TOKEN_TTL=2592000
+
 # Local file storage (fallback when S3_BUCKET is not set)
 LOCAL_UPLOAD_DIR=./data/uploads
-LOCAL_UPLOAD_BASE_URL=http://localhost:8080
+# Derived by Makefile / local scripts from the backend port.
+# Set explicitly only when uploads are served through a different public URL.
+# LOCAL_UPLOAD_BASE_URL=http://localhost:8080
 
 # Security
 # Comma-separated list of allowed origins for CORS and WebSocket connections.
 # Defaults to localhost dev origins when unset.
-# Example: ALLOWED_ORIGINS=https://app.multica.ai,https://staging.multica.ai
-ALLOWED_ORIGINS=
+# Example: CORS_ALLOWED_ORIGINS=https://app.multica.ai,https://staging.multica.ai
+CORS_ALLOWED_ORIGINS=
+
+# ==================== Rate limiting (optional Redis) ====================
+# Per-IP fixed-window rate limiter on the public auth endpoints
+# (/auth/send-code, /auth/verify-code, /auth/google). Backed by Redis.
+# When REDIS_URL is unset the limiter is a no-op (fail-open) and the
+# backend logs "rate limiting disabled: REDIS_URL not configured" at
+# startup. The same REDIS_URL is reused by the realtime fan-out hub,
+# the PAT cache, and the daemon-token cache.
+# REDIS_URL=redis://localhost:6379/0
+# Max requests per IP per minute. Defaults are 5 for send-code/google
+# and 20 for verify-code.
+# RATE_LIMIT_AUTH=5
+# RATE_LIMIT_AUTH_VERIFY=20
+# Comma-separated CIDRs whose X-Forwarded-For the auth limiter is
+# allowed to trust. Empty (default) = never trust XFF, only RemoteAddr.
+# REQUIRED behind a reverse proxy — otherwise every real user shares
+# the proxy IP and the whole deployment lands in one bucket, turning
+# /auth/send-code into 5 req/min site-wide. Use e.g. "127.0.0.1/32,::1/128"
+# for same-host Caddy/Nginx, or the CDN's published ranges for ALB/CF.
+# This is a separate list from MULTICA_TRUSTED_PROXIES above (which
+# governs the autopilot webhook limiter).
+# RATE_LIMIT_TRUSTED_PROXIES=
 
 # Realtime metrics endpoint (/health/realtime) access control. See MUL-1342.
 # When unset, the endpoint only serves direct loopback (127.0.0.1 / ::1)
@@ -116,7 +182,7 @@ ALLOWED_ORIGINS=
 # `Authorization: Bearer <token>`.
 # REALTIME_METRICS_TOKEN=
 
-# GitHub App integration (Settings → Integrations "Connect GitHub")
+# GitHub App integration (Settings → GitHub "Connect GitHub")
 # Both must be set for the Connect button to enable and for webhooks to be
 # accepted; leave empty to disable the integration. See docs/github-integration.
 # GITHUB_APP_SLUG is the tail of https://github.com/apps/<slug>.
@@ -125,9 +191,11 @@ GITHUB_WEBHOOK_SECRET=
 
 # Frontend
 FRONTEND_PORT=3000
-FRONTEND_ORIGIN=http://localhost:3000
+# Derived by docker-compose.selfhost.yml / local scripts from FRONTEND_PORT.
+# Set explicitly only when serving frontend on a different origin/domain.
+# FRONTEND_ORIGIN=http://localhost:3000
 # Leave empty — auto-derived from page origin in browser, set by Makefile for local dev.
-# Only set explicitly if frontend and backend are on different domains.
+# NEXT_PUBLIC_API_URL also feeds the Next.js SSR proxy when explicitly set.
 NEXT_PUBLIC_API_URL=
 NEXT_PUBLIC_WS_URL=
 
@@ -148,6 +216,14 @@ ALLOWED_EMAIL_DOMAINS=
 # Optional: Only allow these exact email addresses (comma-separated)
 ALLOWED_EMAILS=
 
+# Set to "true" to disable workspace creation for every caller on this
+# instance (#3433). Operators usually leave this unset, bootstrap the
+# shared workspace, then flip this to "true" and restart so subsequent
+# users join only via invitations and the entire deployment is visible to
+# the platform admin. The web UI reads this from /api/config at runtime,
+# so toggling requires a backend restart but not a frontend rebuild.
+DISABLE_WORKSPACE_CREATION=
+
 # ==================== Analytics (PostHog) ====================
 # Product analytics events feed the acquisition → activation → expansion funnel.
 # Leave POSTHOG_API_KEY empty for local dev / self-hosted instances; the server

.github/PULL_REQUEST_TEMPLATE.md

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

.github/workflows/ci.yml

@@ -29,6 +29,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install
 
+      - name: Test self-host env derivation
+        run: bash scripts/selfhost-config.test.sh
+
       - name: Verify reserved-slugs.ts is up to date
         # Re-runs the generator and fails on any drift from the
         # checked-in TypeScript output. The Go side embeds the JSON
@@ -39,7 +42,12 @@ jobs:
           git diff --exit-code -- packages/core/paths/reserved-slugs.ts
 
       - name: Build, type check, lint, and test
-        run: pnpm exec turbo build typecheck lint test --filter='!@multica/docs'
+        # Mobile lives in a parallel mobile-verify workflow (path-filtered
+        # to apps/mobile/** + packages/core/types/**) so it doesn't add
+        # ~50s of expo-lint + tsc to every web/desktop PR. Keep this
+        # filter in sync with the root package.json scripts, which also
+        # exclude @multica/mobile.
+        run: pnpm exec turbo build typecheck lint test --filter='!@multica/docs' --filter='!@multica/mobile'
 
   backend:
     runs-on: ubuntu-latest
@@ -91,3 +99,20 @@ jobs:
 
       - name: Test
         run: cd server && go test ./...
+
+  installer:
+    # Stub-driven shell tests for scripts/install.sh. Kept off the heavy
+    # backend job so installer regressions surface independently, and
+    # exercised on macOS too because the installer targets macOS/Homebrew
+    # and `tar` / `sed` / `mktemp` differ between BSD and GNU userlands.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Test shell installers
+        run: bash scripts/install.test.sh

.github/workflows/mobile-verify.yml

@@ -0,0 +1,65 @@
+name: Mobile Verify
+
+# Runs lint + typecheck for apps/mobile only, parallel to the main CI
+# workflow. Path-filtered so PRs that don't touch mobile (or anything
+# mobile transitively depends on) pay zero cost.
+#
+# Path scope rationale — mobile transitively depends on:
+# - apps/mobile/**                — the app itself
+# - packages/core/**              — mobile imports types AND pure functions
+#                                   (agents, markdown, permissions, api/schemas, …),
+#                                   not only @multica/core/types
+# - package.json / pnpm-lock.yaml — install graph
+# - pnpm-workspace.yaml           — catalog versions
+# - turbo.json                    — turbo task pipeline
+#
+# Mobile has no vitest suite today; if one lands, add `test` to the turbo
+# task list below.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "apps/mobile/**"
+      - "packages/core/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
+      - ".github/workflows/mobile-verify.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "apps/mobile/**"
+      - "packages/core/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
+      - ".github/workflows/mobile-verify.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  mobile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Type check and lint
+        run: pnpm exec turbo typecheck lint --filter=@multica/mobile

.github/workflows/release.yml

@@ -322,6 +322,47 @@ jobs:
           docker buildx imagetools inspect \
             ghcr.io/${{ github.repository_owner }}/multica-web:${{ steps.meta.outputs.version }}
 
+  helm-chart:
+    needs: [verify, docker-backend-merge, docker-web-merge]
+    if: github.repository_owner == 'multica-ai'
+    runs-on: ubuntu-latest
+    concurrency:
+      group: release-helm-chart-${{ github.ref }}
+      cancel-in-progress: true
+    env:
+      CHART_DIR: deploy/helm/multica
+      OCI_REGISTRY: oci://ghcr.io/${{ github.repository_owner }}/charts
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Helm
+        uses: azure/setup-helm@v4
+
+      - name: Sync chart metadata with release tag
+        env:
+          TAG_NAME: ${{ needs.verify.outputs.tag_name }}
+        run: |
+          chart_version="${TAG_NAME#v}"
+          sed -i -E "s/^version:.*/version: ${chart_version}/" "$CHART_DIR/Chart.yaml"
+          sed -i -E "s/^appVersion:.*/appVersion: \"${TAG_NAME}\"/" "$CHART_DIR/Chart.yaml"
+          echo "CHART_VERSION=${chart_version}" >> "$GITHUB_ENV"
+
+      - name: Lint chart
+        run: helm lint "$CHART_DIR"
+
+      - name: Package chart
+        run: helm package "$CHART_DIR" --destination .chart-packages
+
+      - name: Login to GHCR
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | helm registry login ghcr.io --username "${{ github.actor }}" --password-stdin
+
+      - name: Push chart to GHCR
+        run: helm push ".chart-packages/multica-${CHART_VERSION}.tgz" "$OCI_REGISTRY"
+
+      - name: Verify published chart
+        run: helm show chart "$OCI_REGISTRY/multica" --version "$CHART_VERSION"
+
   # Build the Desktop installers for Linux and Windows and upload them to
   # the GitHub Release that the `release` job above just published. macOS
   # Desktop continues to ship via the manual `release-desktop` skill so it

.gitignore

@@ -23,6 +23,14 @@ dist-electron
 # Desktop production config is public (backend URL, etc.) — track it so
 # `pnpm package` produces a release-ready build without extra setup.
 !apps/desktop/.env.production
+# Mobile staging config is public (staging API URL) — track it so a fresh
+# checkout can run `pnpm dev:mobile:staging` / `ios:mobile*:staging` without
+# the user having to copy `.env.example` first.
+!apps/mobile/.env.staging
+# Mobile production config is public (production API URL) — track it so
+# external users can run `pnpm ios:mobile:device:prod:release` against
+# multica.ai's production backend without copying templates first.
+!apps/mobile/.env.production
 
 # test coverage
 coverage
@@ -40,6 +48,8 @@ apps/web/test-results/
 
 # context (agent workspace)
 .context
+.agent_context/
+.multica/
 
 # local settings
 .claude/

CLAUDE.md

@@ -32,11 +32,14 @@ Multica is an AI-native task management platform — like Linear, but with AI ag
 - `server/` — Go backend (Chi router, sqlc for DB, gorilla/websocket for real-time)
 - `apps/web/` — Next.js frontend (App Router)
 - `apps/desktop/` — Electron desktop app (electron-vite)
-- `packages/core/` — Headless business logic (zero react-dom, all-platform reuse)
+- `apps/mobile/` — Expo / React Native iOS app. See `apps/mobile/CLAUDE.md`.
+- `packages/core/` — Headless business logic (zero react-dom)
 - `packages/ui/` — Atomic UI components (zero business logic)
 - `packages/views/` — Shared business pages/components (zero next/* imports, zero react-router imports)
 - `packages/tsconfig/` — Shared TypeScript configuration
 
+What lives where for sharing purposes is documented in *Sharing Principles* below — read it once.
+
 ### Key Architectural Decisions
 
 **Internal Packages pattern** — all shared packages export raw `.ts`/`.tsx` files (no pre-compilation). The consuming app's bundler compiles them directly. This gives zero-config HMR and instant go-to-definition.
@@ -52,7 +55,7 @@ Multica is an AI-native task management platform — like Linear, but with AI ag
 The architecture relies on a strict split between server state and client state. Mixing them is the most common way to break it.
 
 - **TanStack Query owns all server state.** Issues, users, workspaces, inbox — anything fetched from the API lives in the Query cache. WS events keep it fresh via invalidation; no polling, no `staleTime` workarounds.
-- **Zustand owns all client state.** UI selections, filters, drafts, modal state, navigation history. Stores live in `packages/core/` (never in `packages/views/`) so both apps share them.
+- **Zustand owns all client state.** UI selections, filters, drafts, modal state, navigation history. Stores live in `packages/core/` (never in `packages/views/`) so they're shared.
 - **React Context** is reserved for cross-cutting platform plumbing — `WorkspaceIdProvider`, `NavigationProvider`. Don't reach for it for general state.
 - **Auth and workspace stores are the only stores allowed to call `api.*` directly**, because they manage critical state that must exist before queries can run. They're created via factory + injected dependencies, registered by the platform layer.
 
@@ -69,6 +72,17 @@ The architecture relies on a strict split between server state and client state.
 - Selectors must return stable references. Returning a freshly built object or array on every call (e.g. `s => ({ a: s.a, b: s.b })` or `s => s.items.map(...)`) triggers infinite re-renders. Either select primitives separately or use shallow comparison.
 - Hooks that need workspace context should accept `wsId` as a parameter, not call `useWorkspaceId()` internally — this lets them work outside the `WorkspaceIdProvider` (e.g. in a sidebar that renders before workspace is loaded).
 
+## Sharing Principles
+
+The monorepo splits into two share zones:
+
+- **Web and desktop** share business logic, components, hooks, stores, and views through `packages/core/`, `packages/ui/`, and `packages/views/`. Existing model — keep using it.
+- **Mobile (`apps/mobile/`) is independent.** It shares only **types and pure functions** from `@multica/core/`, with `import type` for types (zero runtime coupling). UI, state, hooks, providers, i18n, React version, build pipeline, release cadence — all mobile-owned.
+
+Mobile is locked to the React version that Expo SDK / React Native ships (which lags React main by 6-12 months). Coupling mobile to the root `catalog:` React would block mobile from upgrading on its own schedule.
+
+See `apps/mobile/CLAUDE.md` for the mobile rules and tech-stack baseline.
+
 ## Commands
 
 ```bash
@@ -111,6 +125,16 @@ cd server && go test ./internal/handler/ -run TestName
 # Run a single E2E test (requires backend + frontend running)
 pnpm exec playwright test e2e/tests/specific-test.spec.ts
 
+# Mobile (Expo) — two environments only: dev and staging
+pnpm dev:mobile                  # Metro, dev env       (reads apps/mobile/.env.development.local)
+pnpm dev:mobile:staging          # Metro, staging env   (reads apps/mobile/.env.staging)
+pnpm ios:mobile                  # Native build + install dev-client to iOS Simulator, dev env
+pnpm ios:mobile:staging          # Native build + install dev-client to iOS Simulator, staging env
+pnpm ios:mobile:device           # Native build + install dev-client to USB iPhone, dev env
+pnpm ios:mobile:device:staging   # Native build + install dev-client to USB iPhone, staging env
+# Daily flow: run `pnpm dev:mobile:staging` (or :dev). Only re-run `ios:mobile*` when
+# native code or any expo-*/react-native-* dependency changes (lockfile drift counts).
+
 # Desktop build & package
 pnpm --filter @multica/desktop build      # Compile TS → JS (reads .env.production)
 pnpm --filter @multica/desktop package    # Package into .app/.dmg/.exe (current platform only)
@@ -179,21 +203,29 @@ Every Go handler in `server/internal/handler/` follows these rules. The conventi
 
 When adding a `Queries.Delete*` or `Queries.Update*` call, ask: "Where did this UUID come from?" If the answer is "raw user input that hasn't been validated," route it through `parseUUIDOrBadRequest` or a loader first.
 
+### Dependency Declaration Rule
+
+Every workspace (`apps/` and `packages/` directories) must explicitly declare all directly imported external packages in its own `package.json`. Relying on pnpm hoist to resolve undeclared imports (phantom deps) is prohibited — it causes production build failures when pnpm creates peer-dep variants.
+
+- Use `"pkg": "catalog:"` to reference the shared version from `pnpm-workspace.yaml`.
+- CI enforces this via `eslint-plugin-import-x/no-extraneous-dependencies`.
+- Exception: `apps/mobile/` uses pinned versions (not `catalog:`) for packages tied to its own React/Expo version.
+
 ### Package Boundary Rules
 
 These are hard constraints. Violating them breaks the cross-platform architecture:
 
-- `packages/core/` — zero react-dom, zero localStorage (use StorageAdapter), zero process.env, zero UI libraries. **All shared Zustand stores live here**, even view-related ones (filters, view modes) — stores are pure state, not UI.
+- `packages/core/` — zero react-dom, zero localStorage (use StorageAdapter), zero process.env, zero UI libraries. **Shared Zustand stores live here**, even view-related ones (filters, view modes) — stores are pure state, not UI.
 - `packages/ui/` — zero `@multica/core` imports (pure UI, no business logic).
 - `packages/views/` — zero `next/*` imports, zero `react-router-dom` imports, zero stores. Use `NavigationAdapter` for all routing.
 - `apps/web/platform/` — the only place for Next.js APIs (`next/navigation`).
 - `apps/desktop/src/renderer/src/platform/` — the only place for react-router-dom navigation wiring.
 
-### The No-Duplication Rule
+### The No-Duplication Rule (web + desktop)
 
-**If the same logic exists in both apps, it must be extracted to a shared package.**
+**If the same logic exists in both web and desktop, it must be extracted to a shared package.**
 
-This applies to everything: components, hooks, guards, providers, utility functions. The decision process:
+This applies to everything between web and desktop: components, hooks, guards, providers, utility functions. The decision process:
 
 1. Does this code depend on Next.js or Electron APIs? → Keep in the respective app.
 2. Does it depend on `react-router-dom` or `next/navigation`? → Keep in app's `platform/` layer.
@@ -201,9 +233,9 @@ This applies to everything: components, hooks, guards, providers, utility functi
 
 When the two apps need different behavior for the same concept (e.g., different loading UI), extract the shared logic into a component with props/slots for the differences. Don't duplicate the logic.
 
-### Cross-Platform Development Rules
+### Cross-Platform Development Rules (web + desktop)
 
-When adding a new page or feature:
+When adding a new page or feature for web/desktop:
 
 1. **New page component** → add to `packages/views/<domain>/`. Never import from `next/*` or `react-router-dom`.
 2. **Wire it in both apps** → add a route in `apps/web/app/` (Next.js page file) AND in the desktop router. **Exception**: pre-workspace transition flows (create workspace, accept invite) are NOT routes on desktop — they're `WindowOverlay` state. See *Desktop-specific Rules → Route categories*.
@@ -212,14 +244,18 @@ When adding a new page or feature:
 5. **Platform-specific UI** → if a feature is web-only or desktop-only, keep it in the respective app. Use props slots (`extra`, `topSlot`) on shared layout components to inject platform-specific UI.
 6. **New hooks that need workspace context** → accept `wsId` as parameter instead of reading from `useWorkspaceId()` Context, so they work both inside and outside `WorkspaceIdProvider`.
 
-### CSS Architecture
+### CSS Architecture (web + desktop)
 
-Both apps share the same CSS foundation from `packages/ui/styles/`.
+Web and desktop share the same CSS foundation from `packages/ui/styles/`.
 
 - **Design tokens** → use semantic tokens (`bg-background`, `text-muted-foreground`). Never use hardcoded Tailwind colors (`text-red-500`, `bg-gray-100`).
 - **Shared styles** → `packages/ui/styles/`. Never duplicate scrollbar styling, keyframes, or base layer rules in app CSS.
 - **`@source` directives** → both apps scan shared packages so Tailwind sees all class names.
 
+## Mobile-specific Rules
+
+Rules for `apps/mobile/` live in `apps/mobile/CLAUDE.md`. Read it before touching anything in `apps/mobile/` — it covers what may be imported from `@multica/core/`, the React version policy, the build/release pipeline, and the locked tech-stack baseline.
+
 ## Desktop-specific Rules
 
 These rules apply to `apps/desktop/` only. Web has different constraints (URL bar, SSR, no tabs) and doesn't share these concerns. Every rule in this section was added after a concrete bug — treat them as enforced, not suggestions.

CLI_AND_DAEMON.md

@@ -269,21 +269,37 @@ Each profile gets its own config directory (`~/.multica/profiles/<name>/`), daem
 
 ## Workspaces
 
+### Working with multiple workspaces
+
+Every command runs against a single workspace. The CLI resolves which one in this order (highest priority first):
+
+1. `--workspace-id <id>` flag on the command
+2. `MULTICA_WORKSPACE_ID` environment variable
+3. The default workspace stored in your current profile (set by `multica workspace switch` or `multica login`)
+
+`multica workspace switch <id|slug>` is the day-to-day way to change the default workspace. For scripting and headless setups where you don't want any stored state, prefer the `--workspace-id` flag or the env variable. `multica config set workspace_id <id>` is the low-level equivalent of `switch` (it writes the same setting but skips the access check).
+
+If you need full isolation between organizations or accounts — separate tokens, separate daemons, separate config dirs — use `--profile <name>` instead. Each profile keeps its own default workspace.
+
 ### List Workspaces
 
 ```bash
 multica workspace list
+multica workspace list --full-id
+multica workspace list --output json
 ```
 
-Watched workspaces are marked with `*`. The daemon only processes tasks for watched workspaces.
+The current default workspace is marked with `*`. Table output shows short UUID prefixes — pass `--full-id` when you need the canonical UUIDs.
 
-### Watch / Unwatch
+### Switch Default Workspace
 
 ```bash
-multica workspace watch <workspace-id>
-multica workspace unwatch <workspace-id>
+multica workspace switch <workspace-id>
+multica workspace switch <slug>
 ```
 
+Verifies you have access to the workspace, then sets it as the default for the current profile. Subsequent commands without `--workspace-id` and `MULTICA_WORKSPACE_ID` target this workspace. Pair `--profile` if you want to change a non-default profile's workspace.
+
 ### Get Details
 
 ```bash
@@ -291,10 +307,12 @@ multica workspace get <workspace-id>
 multica workspace get <workspace-id> --output json
 ```
 
+Passing no `<workspace-id>` resolves to the current default workspace, so `multica workspace get` doubles as "what workspace am I on?".
+
 ### List Members
 
 ```bash
-multica workspace members <workspace-id>
+multica workspace member list <workspace-id>
 ```
 
 ## Issues
@@ -310,7 +328,14 @@ multica issue list --full-id
 multica issue list --limit 20 --output json
 ```
 
-Table output shows a routable issue `KEY` such as `MUL-123`; copy that key into follow-up commands like `issue get`, `issue comment list`, `issue status`, or `--parent`. Add `--full-id` when you need canonical UUIDs. Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--limit`. Use `--assignee-id <uuid>` for unambiguous filtering when names overlap.
+Table output shows a routable issue `KEY` such as `MUL-123`; copy that key into follow-up commands like `issue get`, `issue comment list`, `issue status`, or `--parent`. Add `--full-id` when you need canonical UUIDs. Available filters: `--status`, `--priority`, `--assignee` / `--assignee-id`, `--project`, `--metadata`, `--limit`. Use `--assignee-id <uuid>` for unambiguous filtering when names overlap.
+
+Use `--metadata key=value` (repeatable; combined with AND) to filter by per-issue metadata. The value is JSON-parsed: `true`/`false` become bool, numbers become numbers, anything else is a string. Wrap as `'"42"'` to force a string when the value would otherwise sniff as a number:
+
+```bash
+multica issue list --metadata pipeline_status=waiting_review
+multica issue list --metadata pr_number=482 --metadata is_blocked=true
+```
 
 ### Get Issue
 
@@ -326,7 +351,7 @@ multica issue create --title "Fix login bug" --description "..." --priority high
 multica issue create --title "Fix login bug" --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 ```
 
-Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee` / `--assignee-id`, `--parent`, `--project`, `--due-date`. Pass `--assignee-id <uuid>` (mutually exclusive with `--assignee`) when scripting against the IDs returned by `multica workspace members --output json` / `multica agent list --output json`.
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee` / `--assignee-id`, `--parent`, `--project`, `--due-date`. Pass `--assignee-id <uuid>` (mutually exclusive with `--assignee`) when scripting against the IDs returned by `multica workspace member list --output json` / `multica agent list --output json`.
 
 ### Update Issue
 
@@ -355,9 +380,44 @@ Valid statuses: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`
 ### Comments
 
 ```bash
-# List comments
+# List comments — flat timeline, chronological. Hard cap of 2000 rows; on
+# long-running issues prefer one of the thread-aware reads below to keep
+# context windows tight.
 multica issue comment list <issue-id>
 
+# Single thread (root + every descendant). Anchor may be the root itself
+# or any reply inside the thread — the server walks up to the root.
+multica issue comment list <issue-id> --thread <comment-id>
+
+# Single thread, capped to the N most recent replies. The thread root is
+# always included (even with --tail 0), so an agent landing on a long
+# thread keeps the "what is this about" context without dragging hundreds
+# of replies into its prompt.
+multica issue comment list <issue-id> --thread <comment-id> --tail 30
+
+# Scroll older replies inside the same thread. --before / --before-id are
+# the reply cursor that the previous response emitted on stderr as
+# `Next reply cursor: --before <ts> --before-id <reply-id>`.
+multica issue comment list <issue-id> --thread <comment-id> --tail 30 \
+    --before <ts> --before-id <reply-id>
+
+# Most recently active threads (root + every descendant), grouped by
+# thread. Returns N complete conversational arcs, oldest-active first so
+# the freshest thread sits closest to "now" in an agent prompt.
+multica issue comment list <issue-id> --recent 20
+
+# Scroll older threads. Under --recent, --before / --before-id are a
+# THREAD cursor (thread last_activity_at + root id), emitted on stderr as
+# `Next thread cursor: --before <ts> --before-id <root-id>`.
+multica issue comment list <issue-id> --recent 20 \
+    --before <ts> --before-id <root-id>
+
+# Incremental polling. Combines with --thread or --recent; filters out
+# replies created on or before <ts> from the page (the thread root is
+# exempt so the agent always gets context).
+multica issue comment list <issue-id> --thread <comment-id> --tail 30 \
+    --since <RFC3339-timestamp>
+
 # Add a comment
 multica issue comment add <issue-id> --content "Looks good, merging now"
 
@@ -368,6 +428,56 @@ multica issue comment add <issue-id> --parent <comment-id> --content "Thanks!"
 multica issue comment delete <comment-id>
 ```
 
+**`--before` / `--before-id` semantics depend on the paging mode**, by
+design — same flag, different scope:
+
+| Mode | What the cursor walks | stderr label |
+| --- | --- | --- |
+| `--recent N` | Older *threads* (last_activity_at, root_id) | `Next thread cursor` |
+| `--thread <id> --tail N` | Older *replies* inside that thread (created_at, id) | `Next reply cursor` |
+
+Outside those two modes (`--thread` without `--tail`, or no `--thread`
+and no `--recent`) the cursor flags are rejected so they cannot silently
+no-op. The server emits the cursor headers (`X-Multica-Next-Before` /
+`X-Multica-Next-Before-Id`) only when an older page actually exists —
+exact-boundary pages (e.g. `--tail 3` on a thread with exactly 3
+replies) intentionally return no cursor so callers stop paginating.
+
+When `--since` is combined with `--recent` or `--thread --tail`, the
+server additionally suppresses the cursor once the cursor target itself
+is older than `since`. Older pages walk strictly older rows, so they
+cannot satisfy `> since` either — emitting a cursor there would just
+hand back root-only pages until the caller reaches the start of the
+thread / issue. Incremental polling stops at the first page whose
+cursor target falls before the watermark.
+
+### Metadata
+
+Per-issue metadata is a small KV map agents use to track pipeline state (PR number, pipeline status, waiting_on, ...). Keys match `^[a-zA-Z_][a-zA-Z0-9_.-]{0,63}$`, values are primitives (string / number / bool), max 50 keys per issue, blob capped at 8KB.
+
+The bar for writing is high: pin a value only when it is materially important to the issue AND likely to be re-read by future runs on this same issue (the PR URL, the deploy URL, what we're blocked on). Most runs write zero new keys — that's the expected case. Don't pin runtime bookkeeping like `attempts`, single-run investigation notes, large logs, secrets/tokens, or description/comment copies — see the agent runtime prompt for the full anti-pattern list.
+
+```bash
+# List every key on an issue
+multica issue metadata list <issue-id>
+
+# Read a single key
+multica issue metadata get <issue-id> --key pipeline_status
+
+# Write a single key — value auto-typed (true/false → bool, numbers → number, else string)
+multica issue metadata set <issue-id> --key pipeline_status --value waiting_review
+multica issue metadata set <issue-id> --key pr_number --value 482
+multica issue metadata set <issue-id> --key is_blocked --value true
+
+# Force a specific type when sniffing would pick the wrong one
+multica issue metadata set <issue-id> --key code --value 42 --type string
+
+# Remove a key
+multica issue metadata delete <issue-id> --key pipeline_status
+```
+
+All writes are single-key atomic — concurrent agents writing different keys do not lose each other's updates. To query, use `multica issue list --metadata key=value` (see *List Issues* above).
+
 ### Subscribers
 
 ```bash
@@ -508,6 +618,8 @@ multica config set app_url https://app.example.com
 multica config set workspace_id <workspace-id>
 ```
 
+`config set workspace_id <id>` is the low-level interface — it writes the value verbatim without checking that the workspace exists or that you have access. Prefer `multica workspace switch <id|slug>` for day-to-day workspace changes; it does both checks before saving.
+
 ## Autopilot Commands
 
 Autopilots are scheduled/triggered automations that dispatch agent tasks (either by creating an issue or by running an agent directly).

Dockerfile

@@ -18,6 +18,7 @@ ARG COMMIT=unknown
 RUN cd server && CGO_ENABLED=0 go build -ldflags "-s -w -X main.version=${VERSION} -X main.commit=${COMMIT}" -o bin/server ./cmd/server
 RUN cd server && CGO_ENABLED=0 go build -ldflags "-s -w -X main.version=${VERSION} -X main.commit=${COMMIT}" -o bin/multica ./cmd/multica
 RUN cd server && CGO_ENABLED=0 go build -ldflags "-s -w" -o bin/migrate ./cmd/migrate
+RUN cd server && CGO_ENABLED=0 go build -ldflags "-s -w" -o bin/backfill_task_usage_hourly ./cmd/backfill_task_usage_hourly
 
 # --- Runtime stage ---
 FROM alpine:3.21
@@ -29,6 +30,7 @@ WORKDIR /app
 COPY --from=builder /src/server/bin/server .
 COPY --from=builder /src/server/bin/multica .
 COPY --from=builder /src/server/bin/migrate .
+COPY --from=builder /src/server/bin/backfill_task_usage_hourly .
 COPY server/migrations/ ./migrations/
 COPY docker/entrypoint.sh .
 RUN sed -i 's/\r$//' entrypoint.sh && chmod +x entrypoint.sh

Dockerfile.web

@@ -8,6 +8,8 @@ WORKDIR /app
 # Copy workspace config and all package.json files for dependency resolution
 COPY pnpm-lock.yaml pnpm-workspace.yaml package.json turbo.json .npmrc ./
 COPY apps/web/package.json apps/web/
+# postinstall runs fumadocs-mdx which reads apps/web/source.config.ts
+COPY apps/web/source.config.ts apps/web/source.config.ts
 COPY packages/core/package.json packages/core/
 COPY packages/ui/package.json packages/ui/
 COPY packages/views/package.json packages/views/

Makefile

@@ -12,7 +12,7 @@ POSTGRES_DB ?= multica
 POSTGRES_USER ?= multica
 POSTGRES_PASSWORD ?= multica
 POSTGRES_PORT ?= 5432
-PORT ?= 8080
+PORT := $(or $(BACKEND_PORT),$(API_PORT),$(SERVER_PORT),$(PORT),8080)
 FRONTEND_PORT ?= 3000
 FRONTEND_ORIGIN ?= http://localhost:$(FRONTEND_PORT)
 MULTICA_APP_URL ?= $(FRONTEND_ORIGIN)
@@ -21,6 +21,7 @@ NEXT_PUBLIC_API_URL ?= http://localhost:$(PORT)
 NEXT_PUBLIC_WS_URL ?= ws://localhost:$(PORT)/ws
 GOOGLE_REDIRECT_URI ?= $(FRONTEND_ORIGIN)/auth/callback
 MULTICA_SERVER_URL ?= ws://localhost:$(PORT)/ws
+LOCAL_UPLOAD_BASE_URL ?= http://localhost:$(PORT)
 
 export
 

README.md

@@ -57,6 +57,7 @@ Multica manages the full agent lifecycle: from task assignment to execution moni
 - **Agents as Teammates** — assign to an agent like you'd assign to a colleague. They have profiles, show up on the board, post comments, create issues, and report blockers proactively.
 - **Squads** — group agents (and humans) under a leader agent and assign work to the *squad*. The leader decides who should pick it up, so routing stays stable as the team grows. `@FrontendTeam` instead of `@alice-or-bob-or-carol`.
 - **Autonomous Execution** — set it and forget it. Full task lifecycle management (enqueue, claim, start, complete/fail) with real-time progress streaming via WebSocket.
+- **Autopilots** — schedule recurring work for agents. Cron triggers, webhooks, or manual runs — each autopilot creates the issue and routes it to an agent automatically, so daily standups, weekly reports, and periodic audits run themselves.
 - **Reusable Skills** — every solution becomes a reusable skill for the whole team. Deployments, migrations, code reviews — skills compound your team's capabilities over time.
 - **Unified Runtimes** — one dashboard for all your compute. Local daemons and cloud runtimes, auto-detection of available CLIs, real-time monitoring.
 - **Multi-Workspace** — organize work across teams with workspace-level isolation. Each workspace has its own agents, issues, and settings.
@@ -113,7 +114,7 @@ multica setup          # Connect to Multica Cloud, log in, start daemon
 multica setup           # Configure, authenticate, and start the daemon
 ```
 
-The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `copilot`, `openclaw`, `opencode`, `hermes`, `gemini`, `pi`, `cursor-agent`, `kimi`, `kiro-cli`) on your PATH.
+The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `copilot`, `openclaw`, `opencode`, `hermes`, `gemini`, `pi`, `cursor-agent`, `kimi`, `kiro-cli`, `agy`) on your PATH.
 
 ### 2. Verify your runtime
 
@@ -123,7 +124,7 @@ Open your workspace in the Multica web app. Navigate to **Settings → Runtimes*
 
 ### 3. Create an agent
 
-Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code, Codex, GitHub Copilot CLI, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, or Kiro CLI). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
+Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code, Codex, GitHub Copilot CLI, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, Kiro CLI, or Antigravity). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
 
 ### 4. Assign your first task
 
@@ -142,6 +143,8 @@ The `multica` CLI connects your local machine to Multica — authenticate, manag
 | `multica daemon status` | Check daemon status |
 | `multica setup` | One-command setup for Multica Cloud (configure + login + start daemon) |
 | `multica setup self-host` | Same, but for self-hosted deployments |
+| `multica workspace list` | List your workspaces (current is marked with `*`) |
+| `multica workspace switch <id\|slug>` | Switch the default workspace for this profile |
 | `multica issue list` | List issues in your workspace |
 | `multica issue create` | Create a new issue |
 | `multica update` | Update to the latest version |
@@ -185,3 +188,5 @@ make dev
 `make dev` auto-detects your environment (main checkout or worktree), creates the env file, installs dependencies, sets up the database, runs migrations, and starts all services.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, worktree support, testing, and troubleshooting.
+
+An iOS mobile client lives in [`apps/mobile/`](apps/mobile/) — see its [README](apps/mobile/README.md) for how to build it onto your own iPhone.

README.zh-CN.md

@@ -57,6 +57,7 @@ Multica 管理完整的 Agent 生命周期：从任务分配到执行监控再
 - **Agent 即队友** — 像分配给同事一样分配给 Agent。它们有个人档案、出现在看板上、发表评论、创建 Issue、主动报告阻塞问题。
 - **Squads（小队）** — 把多个 Agent（以及人类成员）组合成由 leader agent 带队的小队，直接把任务分配给小队本身。Leader 会判断谁最适合接手，团队扩容时路由方式保持不变。用 `@前端组` 代替 `@小张或小李或小王`。
 - **自主执行** — 设置后无需管理。完整的任务生命周期管理（排队、认领、执行、完成/失败），通过 WebSocket 实时推送进度。
+- **自动化（Autopilots）** — 为 Agent 安排周期性工作。定时（Cron）、Webhook 或手动触发，自动化会自动创建 Issue 并分配给 Agent——日报、周报、定期巡检都能让它自己跑起来。
 - **可复用技能** — 每个解决方案都成为全团队可复用的技能。部署、数据库迁移、代码审查——技能让团队能力随时间持续增长。
 - **统一运行时** — 一个控制台管理所有算力。本地 daemon 和云端运行时，自动检测可用 CLI，实时监控。
 - **多工作区** — 按团队组织工作，工作区级别隔离。每个工作区有独立的 Agent、Issue 和设置。
@@ -171,6 +172,8 @@ make start
 
 完整的开发流程、worktree 支持、测试和问题排查请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
+iOS 移动端代码位于 [`apps/mobile/`](apps/mobile/)，自己编译装到手机的方法见 [README](apps/mobile/README.md)。
+
 ## 开源协议
 
-[Apache 2.0](LICENSE)
+[Modified Apache 2.0 (with commercial restrictions)](LICENSE)

SELF_HOSTING.md

@@ -73,7 +73,7 @@ Open http://localhost:3000 in your browser. The Docker self-host stack defaults
 - **Without email configured:** the verification code is generated server-side and printed to the backend container logs (look for `[DEV] Verification code for ...:`). Useful for one-off testing on a single machine.
 - **Deterministic local/private testing:** set `APP_ENV=development` and `MULTICA_DEV_VERIFICATION_CODE=888888` in `.env`, then restart the backend. This fixed code is ignored when `APP_ENV=production`.
 
-Changes to `ALLOW_SIGNUP` and `GOOGLE_CLIENT_ID` also take effect after restarting the backend / compose stack. The web UI reads both from `/api/config` at runtime, so no web rebuild is needed.
+Changes to `ALLOW_SIGNUP`, `DISABLE_WORKSPACE_CREATION`, and `GOOGLE_CLIENT_ID` also take effect after restarting the backend / compose stack. The web UI reads all three from `/api/config` at runtime, so no web rebuild is needed. See [Advanced Configuration → Signup Controls](SELF_HOSTING_ADVANCED.md#signup-controls-optional) for the recommended sequence to lock down workspace creation.
 
 > **Warning:** do **not** set `MULTICA_DEV_VERIFICATION_CODE` on a publicly reachable instance — anyone who knows an email address can then log in with that fixed code.
 
@@ -135,6 +135,262 @@ multica daemon status
 3. Go to **Settings → Agents** and create a new agent
 4. Create an issue and assign it to your agent — it will pick up the task automatically
 
+---
+
+## Kubernetes Deployment (Alternative)
+
+If you already run a Kubernetes cluster, you can deploy Multica there instead of Docker Compose using the released OCI Helm chart at `oci://ghcr.io/multica-ai/charts/multica` or the source chart at [`deploy/helm/multica/`](deploy/helm/multica/). It targets a typical k3s / k8s setup with an Ingress controller and a default `ReadWriteOnce` StorageClass — authored against k3s + Traefik + `local-path`, and should work on any cluster with minor tweaks.
+
+The chart creates the following resources in the target namespace:
+
+- `multica-postgres` — `pgvector/pgvector:pg17` backed by a 10Gi PVC
+- `multica-backend` — Go API/WS server backed by a 5Gi uploads PVC
+- `multica-frontend` — Next.js standalone server
+- Two `Ingress` resources: one for the web host, one for the backend host
+- `multica-config` ConfigMap (rendered from `values.yaml`)
+
+The `multica-secrets` Secret is **not** managed by the chart — you create it once with `kubectl` so real values never need to land in git.
+
+> **One release per namespace:** the prebuilt `multica-web` image bakes `REMOTE_API_URL=http://backend:8080` at build time, so the chart ships an ExternalName Service literally named `backend`. Because that name is unprefixed, you can run only one Multica release per namespace, and `helm install` will fail if a `Service/backend` already exists there (pass `--take-ownership`, or use a dedicated namespace). If you build a web image with a patched `REMOTE_API_URL`, set `frontend.compatibility.backendAlias: false` to drop the alias.
+
+> **Prerequisites:** `kubectl` and `helm` (v3.13+ for `--take-ownership`, or v4+) configured for the target cluster, an Ingress controller (Traefik / NGINX), and a default StorageClass.
+
+### Step 1 — Point hostnames at the cluster
+
+The chart defaults to `multica.dev.lan` (web) and `api.multica.dev.lan` (backend). Pick one of:
+
+- **`/etc/hosts`** on every machine that needs access (developer laptops + the machine running the daemon):
+
+  ```text
+  192.168.1.206  multica.dev.lan api.multica.dev.lan
+  ```
+
+  Replace `192.168.1.206` with any node IP where your Ingress controller's Service is reachable.
+
+- **Local DNS** (Pi-hole, Unbound, etc.): add A records for both hostnames pointing at the cluster Ingress IP.
+
+To use different hostnames, override the matching values at install time (see [Step 4](#step-4--install-the-chart)) — `ingress.frontend.host`, `ingress.backend.host`, plus `backend.config.appUrl`, `backend.config.frontendOrigin`, `backend.config.localUploadBaseUrl`, and `backend.config.googleRedirectUri`.
+
+### Step 2 — Create the namespace
+
+```bash
+kubectl create namespace multica
+```
+
+### Step 3 — Create the `multica-secrets` Secret
+
+The chart references this Secret by name. Create it once with random values:
+
+```bash
+kubectl -n multica create secret generic multica-secrets \
+  --from-literal=JWT_SECRET="$(openssl rand -hex 32)" \
+  --from-literal=POSTGRES_PASSWORD="$(openssl rand -hex 16)" \
+  --from-literal=RESEND_API_KEY="" \
+  --from-literal=GOOGLE_CLIENT_SECRET="" \
+  --from-literal=CLOUDFRONT_PRIVATE_KEY="" \
+  --from-literal=MULTICA_DEV_VERIFICATION_CODE=""
+```
+
+Leave optional values empty for now — you can fill them in later (see [Step 5 — Log In](#step-5--log-in)).
+
+### Step 4 — Install the chart
+
+```bash
+helm install multica oci://ghcr.io/multica-ai/charts/multica \
+  --version <chart-version> \
+  -n multica
+```
+
+Released chart versions strip the leading `v` from the Git tag. For example, release tag `v0.3.5` publishes chart version `0.3.5`; the chart defaults the backend and frontend image tags to `v0.3.5`.
+
+To override defaults, export the chart values, edit them, and pass them with `-f`:
+
+```bash
+helm show values oci://ghcr.io/multica-ai/charts/multica \
+  --version <chart-version> > my-values.yaml
+# edit my-values.yaml — e.g. change ingress hosts, image tags, resource limits
+helm install multica oci://ghcr.io/multica-ai/charts/multica \
+  --version <chart-version> \
+  -n multica \
+  -f my-values.yaml
+```
+
+When developing from a checkout, use the local chart path instead:
+
+```bash
+helm install multica deploy/helm/multica -n multica
+```
+
+Watch the pods come up:
+
+```bash
+kubectl -n multica get pods -w
+```
+
+On a cold cluster the backend can sit `Running` but not `Ready` for a few minutes while it waits on PostgreSQL and runs migrations — a startupProbe absorbs this, so the pod should not restart. Once the backend reports `Ready`, migrations have completed and `/healthz` returns OK:
+
+```bash
+curl -H "Host: api.multica.dev.lan" http://<ingress-ip>/healthz
+# {"status":"ok","checks":{"db":"ok","migrations":"ok"}}
+```
+
+Then open http://multica.dev.lan in your browser.
+
+### Step 5 — Log In
+
+The chart defaults to `APP_ENV=production` (set in `values.yaml` under `backend.config.appEnv`), and there is no fixed verification code by default. Pick one of the following to log in — the same three options as the Docker setup:
+
+- **Recommended (production):** patch the Secret with a real Resend key, then restart the backend:
+
+  ```bash
+  kubectl -n multica patch secret multica-secrets --type=merge \
+    -p '{"stringData":{"RESEND_API_KEY":"re_xxx"}}'
+  kubectl -n multica rollout restart deploy/multica-backend
+  ```
+
+  Real verification codes will be sent to the email address you enter. See [Advanced Configuration → Email](SELF_HOSTING_ADVANCED.md#email-required-for-authentication).
+
+- **Without email configured:** the verification code is generated server-side and printed to the backend pod logs (look for `[DEV] Verification code for ...:`). Useful for one-off testing.
+
+  ```bash
+  kubectl -n multica logs -f deploy/multica-backend | grep "Verification code"
+  ```
+
+- **Deterministic local/private testing:** set `backend.config.appEnv: development` in your values file and `MULTICA_DEV_VERIFICATION_CODE=888888` in the Secret, then `helm upgrade` and restart. This fixed code is ignored when `APP_ENV=production`.
+
+  ```bash
+  helm upgrade multica oci://ghcr.io/multica-ai/charts/multica \
+    --version <chart-version> \
+    -n multica \
+    -f my-values.yaml --set backend.config.appEnv=development
+  kubectl -n multica patch secret multica-secrets --type=merge \
+    -p '{"stringData":{"MULTICA_DEV_VERIFICATION_CODE":"888888"}}'
+  kubectl -n multica rollout restart deploy/multica-backend
+  ```
+
+`ALLOW_SIGNUP`, `DISABLE_WORKSPACE_CREATION`, and `GOOGLE_CLIENT_ID` likewise live under `backend.config.*` in `values.yaml` (as `allowSignup`, `disableWorkspaceCreation`, and `googleClientId`). After `helm upgrade`, the backend pod will roll automatically because the ConfigMap hash changes; the web UI reads all three from `/api/config` at runtime, so no web rebuild is needed.
+
+> **Warning:** do **not** set `MULTICA_DEV_VERIFICATION_CODE` on a publicly reachable instance — anyone who knows an email address can then log in with that fixed code.
+
+### Step 6 — Install CLI & Start Daemon
+
+The daemon runs on your local machine, not in the cluster. Install the CLI and an AI agent as in [Step 3](#step-3--install-cli--start-daemon) above, then point the CLI at your Ingress hostnames:
+
+```bash
+multica setup self-host \
+  --server-url http://api.multica.dev.lan \
+  --app-url http://multica.dev.lan
+```
+
+Make sure the machine running the daemon has the same `/etc/hosts` (or DNS) entries from [Step 1](#step-1--point-hostnames-at-the-cluster).
+
+### Updating
+
+To pull the latest images without changing the chart version when your values still use the mutable `latest` image tag:
+
+```bash
+kubectl -n multica rollout restart deploy/multica-backend deploy/multica-frontend
+```
+
+To upgrade to a specific Multica release, upgrade to the matching chart version. The released chart defaults its app images to the matching Git tag:
+
+```bash
+helm upgrade multica oci://ghcr.io/multica-ai/charts/multica \
+  --version <chart-version> \
+  -n multica \
+  -f my-values.yaml
+```
+
+If you need to override the app images independently from the chart version, set the image tags in your values file:
+
+```yaml
+images:
+  backend:
+    tag: v0.2.4
+  frontend:
+    tag: v0.2.4
+```
+
+Then run the same upgrade command with `-f my-values.yaml`:
+
+```bash
+helm upgrade multica oci://ghcr.io/multica-ai/charts/multica \
+  --version <chart-version> \
+  -n multica \
+  -f my-values.yaml
+```
+
+To roll back if an upgrade goes sideways:
+
+```bash
+helm -n multica rollback multica
+```
+
+> **Upgrading from `v0.3.4` to `v0.3.5+` fails with `refusing to drop legacy daily rollups: ...`?** Same migration guard as the Docker path — see [Usage Dashboard Rollup → Option C](#option-c--backfill-history-first-then-schedule). Run the backfill against the same database the chart is using (`kubectl -n multica exec deploy/multica-backend -- ./backfill_task_usage_hourly --sleep-between-slices=2s`), then restart the backend deployment to re-apply migrations.
+
+### Tearing down
+
+```bash
+# Remove the workloads but keep the PVCs and the Secret
+helm -n multica uninstall multica
+
+# Wipe everything, including PostgreSQL data and uploads
+kubectl delete namespace multica
+```
+
+---
+
+## Usage Dashboard Rollup (Required)
+
+Starting with `v0.3.5`, the Usage / Runtime dashboards read from a derived `task_usage_hourly` table rather than directly from `task_usage`. Raw `task_usage` rows are written by the backend on every task, but the dashboard only sees data after `rollup_task_usage_hourly()` runs and aggregates them into `task_usage_hourly`.
+
+**The bundled `pgvector/pgvector:pg17` image does NOT include `pg_cron`.** If nothing schedules the rollup, the dashboard will stay at zero forever even though `task_usage` is populated. You have three supported options — pick one before relying on the dashboard.
+
+> **Upgrading from `v0.3.4` to `v0.3.5+`** with existing `task_usage` history: migration `103` is fail-closed and will abort `migrate up` with `refusing to drop legacy daily rollups: …`. Run `backfill_task_usage_hourly` first (Option C below), then re-run the upgrade. **Fresh installs** are exempted by that guard and migrate cleanly — but the dashboard will still stay at zero until you pick Option A or Option B.
+
+### Option A — External cron / systemd-timer (simplest)
+
+Schedule a 5-minute job that calls `rollup_task_usage_hourly()`. It is idempotent and watermark-driven, so a missed tick catches up on the next run.
+
+```bash
+# /etc/cron.d/multica-rollup — every 5 minutes
+*/5 * * * * root docker compose -f /path/to/multica/docker-compose.selfhost.yml \
+  exec -T postgres psql -U multica -d multica \
+  -c "SELECT rollup_task_usage_hourly();" >/dev/null
+```
+
+Or as a systemd timer + service if you prefer that surface. The function returns the number of (upserted + deleted-empty) rows; it's safe to call concurrently with itself (an advisory lock makes overlapping runs no-op) and safe to call alongside `backfill_task_usage_hourly`.
+
+### Option B — Swap Postgres for an image that ships `pg_cron`
+
+If you'd rather have Postgres schedule itself, replace `pgvector/pgvector:pg17` in `docker-compose.selfhost.yml` with an image that bundles both `pgvector` and `pg_cron` (e.g. `supabase/postgres`, or your own build of `pgvector/pgvector` with `pg_cron` added and `shared_preload_libraries=pg_cron` set on the server). Then, once:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+SELECT cron.schedule(
+  'rollup_task_usage_hourly',
+  '*/5 * * * *',
+  $$SELECT rollup_task_usage_hourly()$$
+);
+```
+
+`shared_preload_libraries` requires a Postgres restart to take effect — set it in `postgresql.conf` (or via the image's documented mechanism) before bringing the container up.
+
+### Option C — Backfill history first, then schedule
+
+If you're upgrading from `v0.3.4 → v0.3.5+` and already have `task_usage` rows (or you just want the dashboard to show historical data on a fresh install that you've been running for a while), run the bundled backfill command once before scheduling the rollup:
+
+```bash
+# Backfills task_usage_hourly from all historical task_usage rows and stamps
+# the rollup watermark. Idempotent — safe to re-run.
+docker compose -f docker-compose.selfhost.yml exec backend \
+  ./backfill_task_usage_hourly --sleep-between-slices=2s
+```
+
+On a database with years of data this can scan tens of millions of rows; `--sleep-between-slices=2s` throttles the read pressure. Use `--months-back N` (plus `--force-partial`) if you only want the last N months. Once it finishes, set up Option A or Option B so new buckets keep flowing.
+
+After upgrading, re-run `migrate up` (or restart the backend container — migrations run automatically on startup) to apply migration `103` cleanly.
+
 ## Stopping Services
 
 If you installed via the install script:
@@ -175,6 +431,8 @@ docker compose -f docker-compose.selfhost.yml up -d
 Pin `MULTICA_IMAGE_TAG` in `.env` to an exact version like `v0.2.4` if you want to stay on a specific release. Migrations run automatically on backend startup.
 If the selected GHCR tag has not been published yet, fall back to `make selfhost-build` or `docker compose -f docker-compose.selfhost.yml -f docker-compose.selfhost.build.yml up -d --build`.
 
+> **Upgrading from `v0.3.4` to `v0.3.5+` fails with `refusing to drop legacy daily rollups: ...`?** That's migration `103`'s fail-closed guard: it requires `task_usage_hourly` to be seeded before the legacy daily rollups are dropped. Run `backfill_task_usage_hourly` first, then re-run the upgrade. Full instructions in [Usage Dashboard Rollup → Option C](#option-c--backfill-history-first-then-schedule).
+
 ---
 
 ## Manual Docker Compose Setup

SELF_HOSTING_ADVANCED.md

@@ -44,9 +44,10 @@ Use this option when your deployment cannot reach the public internet or you alr
 | `SMTP_PORT` | SMTP port | `25` |
 | `SMTP_USERNAME` | SMTP username (leave empty for unauthenticated relay) | - |
 | `SMTP_PASSWORD` | SMTP password | - |
+| `SMTP_TLS` | TLS mode. `implicit` (aliases `smtps`, `ssl`) forces SMTPS on connect; port `465` auto-enables it. Unset / `starttls` upgrades via STARTTLS | `starttls` |
 | `SMTP_TLS_INSECURE` | Set `true` to skip TLS certificate verification (self-signed / private CA certs) | `false` |
 
-STARTTLS is used automatically when advertised by the server. Port 465 (SMTPS / implicit TLS) is not currently supported - use ports 25 or 587 with STARTTLS.
+STARTTLS is used automatically when advertised by the server. Port 465 (SMTPS / implicit TLS) is supported and auto-enables implicit TLS; set `SMTP_TLS=implicit` (aliases `smtps`, `ssl`) to force it on a non-standard port.
 
 > **Note:** If neither Resend nor SMTP is configured, generated verification codes are printed to backend logs — copy them from there to log in. A fixed local testing code (e.g. `888888`) is **opt-in only**: set `MULTICA_DEV_VERIFICATION_CODE=888888` in `.env` and keep `APP_ENV` non-production. The Docker self-host stack pins `APP_ENV=production`, so the shortcut is ignored there. **Never enable a fixed code on a publicly reachable instance.**
 
@@ -67,8 +68,20 @@ Changes take effect after restarting the backend / compose stack. The web UI rea
 | `ALLOW_SIGNUP` | Set to `false` to disable new user signups on a private instance |
 | `ALLOWED_EMAIL_DOMAINS` | Optional comma-separated allowlist of email domains |
 | `ALLOWED_EMAILS` | Optional comma-separated allowlist of exact email addresses |
+| `DISABLE_WORKSPACE_CREATION` | Set to `true` to make `POST /api/workspaces` return 403 for every caller — users can only join workspaces they were invited to |
 
-Changes take effect after restarting the backend / compose stack. The web UI reads `ALLOW_SIGNUP` from `/api/config` at runtime, so no web rebuild is needed.
+Changes take effect after restarting the backend / compose stack. The web UI reads `ALLOW_SIGNUP` and `DISABLE_WORKSPACE_CREATION` from `/api/config` at runtime, so no web rebuild is needed.
+
+#### Locking down workspace creation
+
+`ALLOW_SIGNUP=false` blocks new accounts from being created, but it does **not** block an already-signed-in user from creating another workspace via `POST /api/workspaces`. On a self-hosted instance where every issue/repo/agent must be visible to the platform admin, set `DISABLE_WORKSPACE_CREATION=true` to close that gap. The recommended bootstrap sequence is:
+
+1. Start the instance with `DISABLE_WORKSPACE_CREATION=false` (the default).
+2. Sign in as the admin and create the shared workspace.
+3. Set `DISABLE_WORKSPACE_CREATION=true` and restart the backend. Optionally set `ALLOW_SIGNUP=false` at the same time if you also want to block new account creation.
+4. Going forward, additional users join via invitation only — the "Create workspace" affordance is hidden in the UI and any direct API call returns 403.
+
+> Note: setting `ALLOW_SIGNUP=false` blocks **all** new account creation, including users who already have a pending invitation. If you need invited users to be able to sign up but not create their own workspaces, keep `ALLOW_SIGNUP=true` (optionally combined with `ALLOWED_EMAIL_DOMAINS` / `ALLOWED_EMAILS`) and only flip `DISABLE_WORKSPACE_CREATION=true`.
 
 ### File Storage (Optional)
 
@@ -79,7 +92,7 @@ For file uploads and attachments, configure S3 and (optionally) CloudFront:
 | `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 |
+| `AWS_ENDPOINT_URL` | Custom S3-compatible endpoint (e.g. MinIO, R2, B2). Setting this switches to path-style URLs |
 | `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) |
@@ -166,6 +179,111 @@ The Docker Compose setup runs migrations automatically. If you need to run them
 cd server && go run ./cmd/migrate up
 ```
 
+## Usage Dashboard Rollup
+
+The Usage and Runtime dashboards read from `task_usage_hourly`, a derived table populated by `rollup_task_usage_hourly()`. The function is **not** scheduled out of the box on the default self-host stack: the bundled `pgvector/pgvector:pg17` image ships without `pg_cron`, and the backend does not run the rollup in-process either. Until something calls it on a schedule, raw `task_usage` rows will keep arriving while the dashboard stays at zero.
+
+Pick one of the supported paths:
+
+### Option A — External cron / systemd-timer
+
+The simplest path. Schedule `SELECT rollup_task_usage_hourly()` every five minutes from any out-of-band timer (host crontab, systemd timer, sidecar container, Kubernetes CronJob). It is idempotent and watermark-driven — overlapping runs are no-ops on an internal advisory lock, and a missed tick catches up on the next run.
+
+Docker Compose:
+
+```bash
+# /etc/cron.d/multica-rollup
+*/5 * * * * root docker compose -f /path/to/multica/docker-compose.selfhost.yml \
+  exec -T postgres psql -U multica -d multica \
+  -c "SELECT rollup_task_usage_hourly();" >/dev/null
+```
+
+Kubernetes (one-off `CronJob`):
+
+```yaml
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: multica-usage-rollup
+spec:
+  schedule: "*/5 * * * *"
+  concurrencyPolicy: Forbid
+  jobTemplate:
+    spec:
+      template:
+        spec:
+          restartPolicy: OnFailure
+          containers:
+            - name: psql
+              image: postgres:17-alpine
+              command:
+                - psql
+                - "$(DATABASE_URL)"
+                - -c
+                - "SELECT rollup_task_usage_hourly();"
+              env:
+                - name: DATABASE_URL
+                  valueFrom:
+                    secretKeyRef:
+                      name: multica-secrets
+                      key: DATABASE_URL
+```
+
+### Option B — Postgres with `pg_cron`
+
+If you'd rather have Postgres schedule itself, swap the bundled image for one that ships both `pgvector` and `pg_cron` (e.g. `supabase/postgres`, or a custom build of `pgvector/pgvector` with `pg_cron` added). `pg_cron` requires `shared_preload_libraries=pg_cron` in `postgresql.conf`, which only takes effect on Postgres restart — set it before bringing the container up.
+
+Then register the job once:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+SELECT cron.schedule(
+  'rollup_task_usage_hourly',
+  '*/5 * * * *',
+  $$SELECT rollup_task_usage_hourly()$$
+);
+```
+
+`pg_cron.database_name` defaults to `postgres`; if your Multica database has a different name, point `pg_cron` at it via that GUC or run `cron.schedule_in_database(...)` instead.
+
+### Option C — Backfill historical data first
+
+`rollup_task_usage_hourly()` only processes new buckets after it starts running. If you already have `task_usage` rows from before the rollup was scheduled — most commonly when upgrading from `v0.3.4` to `v0.3.5+`, or on a fresh install that has been collecting usage for a while — run `backfill_task_usage_hourly` once to seed historical buckets, then set up Option A or Option B for ongoing rollups.
+
+```bash
+# Docker Compose
+docker compose -f docker-compose.selfhost.yml exec backend \
+  ./backfill_task_usage_hourly --sleep-between-slices=2s
+
+# Kubernetes
+kubectl -n multica exec deploy/multica-backend -- \
+  ./backfill_task_usage_hourly --sleep-between-slices=2s
+```
+
+The command walks `task_usage`'s full time range in monthly slices and calls the same idempotent primitive the cron path uses, so it's safe to re-run, to interrupt with Ctrl-C, and to run concurrently with an already-scheduled rollup. Flags:
+
+| Flag | Description |
+|---|---|
+| `--sleep-between-slices` | Pause between monthly slices to throttle read pressure on busy databases (e.g. `2s`). Recommended on production DBs with years of history. |
+| `--months-back N` | Only backfill the last N months. **Requires `--force-partial`** because the watermark still advances past the skipped older buckets — those are permanently abandoned. |
+| `--dry-run` | Log slices that would be processed without writing anything. |
+
+After backfill completes, the rollup-state watermark is stamped to `now() - 5 minutes`, so the first scheduled tick after backfill does not redo history.
+
+### `v0.3.4 → v0.3.5+` upgrade order
+
+Migration `103` adds a fail-closed guard that refuses to drop the legacy daily rollups until `task_usage_hourly` has caught up. If you run `migrate up` straight through on a database with existing `task_usage` rows, it aborts with:
+
+```text
+ERROR: refusing to drop legacy daily rollups:
+  task_usage_hourly_rollup_state.watermark_at (1970-01-01 ...) trails
+  task_usage latest event (...) by more than 01:00:00 — backfill is
+  incomplete or pg_cron is not running. Run cmd/backfill_task_usage_hourly
+  (and let pg_cron catch up) before re-running migrate
+```
+
+Recovery is straightforward: run `backfill_task_usage_hourly` (Option C above), then re-run `migrate up` (or restart the backend container — migrations run automatically on startup). **Fresh installs are exempt** — the guard short-circuits when `task_usage` is empty, and migrations succeed, but the dashboard will still stay at zero until you set up Option A or Option B.
+
 ## Manual Setup (Without Docker Compose)
 
 If you prefer to build and run services manually:

apps/desktop/electron.vite.config.ts

@@ -23,7 +23,7 @@ export default defineConfig({
       alias: {
         "@": resolve("src/renderer/src"),
       },
-      dedupe: ["react", "react-dom"],
+      dedupe: ["react", "react-dom", "@tanstack/react-query"],
     },
   },
 });

apps/desktop/package.json

@@ -45,15 +45,21 @@
     "@multica/core": "workspace:*",
     "@multica/ui": "workspace:*",
     "@multica/views": "workspace:*",
+    "@tanstack/react-query": "catalog:",
     "electron-updater": "^6.8.3",
     "fix-path": "^5.0.0",
+    "lucide-react": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
     "react-router-dom": "^7.6.0",
     "shadcn": "^4.1.0",
     "sonner": "^2.0.7",
-    "tw-animate-css": "^1.4.0"
+    "tw-animate-css": "^1.4.0",
+    "zustand": "catalog:"
   },
   "devDependencies": {
     "@electron-toolkit/tsconfig": "^2.0.0",
+    "@multica/eslint-config": "workspace:*",
     "@multica/tsconfig": "workspace:*",
     "@tailwindcss/vite": "^4",
     "@testing-library/jest-dom": "catalog:",
@@ -65,9 +71,8 @@
     "electron": "^39.2.6",
     "electron-builder": "^26.0.12",
     "electron-vite": "^5.0.0",
+    "globals": "^16.0.0",
     "jsdom": "catalog:",
-    "react": "catalog:",
-    "react-dom": "catalog:",
     "tailwindcss": "^4",
     "typescript": "catalog:",
     "vitest": "catalog:"

apps/desktop/src/main/daemon-manager.ts

@@ -15,7 +15,7 @@ import {
   type StatsListener,
 } from "fs";
 import { join } from "path";
-import { homedir } from "os";
+import { homedir, hostname } from "os";
 import type { DaemonStatus, DaemonPrefs } from "../shared/daemon-types";
 import { ensureManagedCli, managedCliPath } from "./cli-bootstrap";
 import { decideVersionAction } from "./version-decision";
@@ -864,6 +864,11 @@ export function setupDaemonManager(
   ipcMain.handle("daemon:stop", () => withGuard(() => stopDaemon()));
   ipcMain.handle("daemon:restart", () => withGuard(() => restartDaemon()));
   ipcMain.handle("daemon:get-status", () => fetchHealth());
+  // The host's OS name, available regardless of daemon state. The Runtimes
+  // page uses it as a fallback identity for "this machine" when no
+  // app-managed daemon is reporting a device name (e.g. the daemon runs
+  // out-of-band in WSL2). See desktop-runtimes-page.tsx.
+  ipcMain.handle("daemon:get-host-name", () => hostname());
   ipcMain.handle(
     "daemon:sync-token",
     (_event, token: string, userId: string) => syncToken(token, userId),

apps/desktop/src/main/index.ts

@@ -5,8 +5,11 @@ import { electronApp, optimizer, is } from "@electron-toolkit/utils";
 import fixPath from "fix-path";
 import { setupAutoUpdater } from "./updater";
 import { setupDaemonManager } from "./daemon-manager";
+import { setupLocalDirectory } from "./local-directory";
 import { openExternalSafely, downloadURLSafely } from "./external-url";
 import { installContextMenu } from "./context-menu";
+import { handleAppShortcut } from "./keyboard-shortcuts";
+import { installNavigationGestures } from "./navigation-gestures";
 import { getAppVersion } from "./app-version";
 import { loadRuntimeConfig } from "./runtime-config-loader";
 import type { RuntimeConfigResult } from "../shared/runtime-config";
@@ -189,23 +192,69 @@ function createWindow(): void {
     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();
+  // Window-level keyboard shortcuts. Calling preventDefault here prevents
+  // both the renderer keydown AND the application menu accelerator, so
+  // anything we own here (reload-block, zoom) is the sole handler for
+  // that combination — no double-fire with the macOS default View menu.
+  mainWindow.webContents.on("before-input-event", (event, input) => {
+    if (handleAppShortcut(input, mainWindow!.webContents)) {
+      event.preventDefault();
     }
   });
 
+  // Dev-mode renderer diagnostics. When the renderer crashes hard enough
+  // that DevTools can't be opened (white screen with no clickable surface),
+  // the only way to recover the actual JS error is to forward it from the
+  // main process to the terminal running `make dev`. Without these, the
+  // user sees only the daemon-manager polling noise (`Render frame was
+  // disposed before WebFrameMain could be accessed`) which is a downstream
+  // symptom, not the cause.
+  //
+  // Gated by `is.dev` to keep production stderr clean — packaged builds
+  // don't have a terminal anyway, and we ship to crash-reporting separately.
+  if (is.dev) {
+    const log = (tag: string, ...args: unknown[]) =>
+      process.stderr.write(`[renderer ${tag}] ${args.map(String).join(" ")}\n`);
+
+    // Forward every renderer-side console.* call. The detail object also
+    // carries source URL + line — included so a thrown stack trace from
+    // window.onerror is traceable back to a file.
+    mainWindow.webContents.on("console-message", (details) => {
+      const { level, message, sourceId, lineNumber } = details;
+      log(level, `${message} (${sourceId}:${lineNumber})`);
+    });
+
+    // Fires when the renderer process dies for any reason (OOM, crash,
+    // killed). `details.reason` is the discriminator: "crashed", "oom",
+    // "killed", "abnormal-exit", "launch-failed", etc.
+    mainWindow.webContents.on("render-process-gone", (_event, details) => {
+      log("process-gone", JSON.stringify(details));
+    });
+
+    // Fires when loadURL / loadFile can't reach its target (dev server
+    // not up yet, network blip, file missing). errorCode is a Chromium
+    // net error number; -3 = ABORTED is normal during HMR and skipped.
+    mainWindow.webContents.on(
+      "did-fail-load",
+      (_event, errorCode, errorDescription, validatedURL, isMainFrame) => {
+        if (errorCode === -3) return;
+        log(
+          "did-fail-load",
+          `code=${errorCode} desc=${errorDescription} url=${validatedURL} mainFrame=${isMainFrame}`,
+        );
+      },
+    );
+
+    // Fires when the preload script throws before the renderer can boot.
+    // This is the one error class that NEVER reaches DevTools (preload
+    // runs before any window) — without this listener it's invisible.
+    mainWindow.webContents.on("preload-error", (_event, preloadPath, error) => {
+      log("preload-error", `path=${preloadPath} err=${error?.stack ?? error}`);
+    });
+  }
+
   installContextMenu(mainWindow.webContents);
+  installNavigationGestures(mainWindow);
 
   if (is.dev && process.env["ELECTRON_RENDERER_URL"]) {
     mainWindow.loadURL(process.env["ELECTRON_RENDERER_URL"]);
@@ -412,6 +461,7 @@ if (!gotTheLock) {
 
     setupAutoUpdater(() => mainWindow);
     setupDaemonManager(() => mainWindow);
+    setupLocalDirectory(() => mainWindow);
 
     // macOS: deep link arrives via open-url event
     app.on("open-url", (_event, url) => {

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

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

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

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

apps/desktop/src/main/local-directory.ts

@@ -0,0 +1,93 @@
+import { ipcMain, dialog, BrowserWindow } from "electron";
+import { access, stat } from "fs/promises";
+import { constants as fsConstants } from "fs";
+import { basename, isAbsolute } from "path";
+
+export interface PickDirectoryResult {
+  ok: boolean;
+  path?: string;
+  basename?: string;
+  /** Set when ok=false. "cancelled" = user dismissed; otherwise an error blurb. */
+  reason?: "cancelled" | "no_window" | "error";
+  error?: string;
+}
+
+export interface ValidateLocalDirectoryResult {
+  ok: boolean;
+  /** When ok=false, identifies which check failed so the renderer can render a
+   *  specific message without parsing free-form text. */
+  reason?:
+    | "not_absolute"
+    | "not_found"
+    | "not_a_directory"
+    | "not_readable"
+    | "not_writable"
+    | "error";
+  error?: string;
+}
+
+async function validateLocalDirectory(
+  path: string,
+): Promise<ValidateLocalDirectoryResult> {
+  if (!path || !isAbsolute(path)) {
+    return { ok: false, reason: "not_absolute" };
+  }
+  try {
+    const st = await stat(path);
+    if (!st.isDirectory()) return { ok: false, reason: "not_a_directory" };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { ok: false, reason: "not_found" };
+    return { ok: false, reason: "error", error: errorMessage(err) };
+  }
+  try {
+    await access(path, fsConstants.R_OK);
+  } catch {
+    return { ok: false, reason: "not_readable" };
+  }
+  try {
+    await access(path, fsConstants.W_OK);
+  } catch {
+    return { ok: false, reason: "not_writable" };
+  }
+  return { ok: true };
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export function setupLocalDirectory(
+  windowGetter: () => BrowserWindow | null,
+): void {
+  ipcMain.handle(
+    "local-directory:pick",
+    async (_event, defaultPath?: string): Promise<PickDirectoryResult> => {
+      const win = windowGetter();
+      if (!win) return { ok: false, reason: "no_window" };
+      try {
+        const result = await dialog.showOpenDialog(win, {
+          // Multiple-selection is intentionally disabled — a project_resource
+          // points at a single directory, and the create flow expects one
+          // path per click. Multi-add would have to be a separate UX.
+          properties: ["openDirectory", "createDirectory"],
+          ...(defaultPath ? { defaultPath } : {}),
+        });
+        if (result.canceled || result.filePaths.length === 0) {
+          return { ok: false, reason: "cancelled" };
+        }
+        const picked = result.filePaths[0];
+        if (!picked) return { ok: false, reason: "cancelled" };
+        return { ok: true, path: picked, basename: basename(picked) };
+      } catch (err) {
+        return { ok: false, reason: "error", error: errorMessage(err) };
+      }
+    },
+  );
+
+  ipcMain.handle(
+    "local-directory:validate",
+    (_event, path: string): Promise<ValidateLocalDirectoryResult> =>
+      validateLocalDirectory(path),
+  );
+}

apps/desktop/src/main/navigation-gestures.test.ts

@@ -0,0 +1,60 @@
+import type { BrowserWindow } from "electron";
+import { describe, expect, it, vi } from "vitest";
+import { NAVIGATION_GESTURE_CHANNEL } from "../shared/navigation-gestures";
+import { installNavigationGestures } from "./navigation-gestures";
+
+function makeWindow() {
+  let swipeHandler:
+    | ((event: unknown, direction: string) => void)
+    | undefined;
+
+  const win = {
+    on: vi.fn(
+      (event: string, handler: (event: unknown, direction: string) => void) => {
+        if (event === "swipe") swipeHandler = handler;
+        return win;
+      },
+    ),
+    webContents: {
+      send: vi.fn(),
+    },
+  };
+
+  return {
+    win: win as unknown as BrowserWindow,
+    send: win.webContents.send,
+    emitSwipe: (direction: string) => swipeHandler?.({}, direction),
+  };
+}
+
+describe("installNavigationGestures", () => {
+  it("registers macOS swipe navigation", () => {
+    const { win, send, emitSwipe } = makeWindow();
+
+    installNavigationGestures(win, "darwin");
+
+    emitSwipe("right");
+    expect(send).toHaveBeenCalledWith(NAVIGATION_GESTURE_CHANNEL, "back");
+
+    emitSwipe("left");
+    expect(send).toHaveBeenCalledWith(NAVIGATION_GESTURE_CHANNEL, "forward");
+  });
+
+  it("ignores non-horizontal swipe directions", () => {
+    const { win, send, emitSwipe } = makeWindow();
+
+    installNavigationGestures(win, "darwin");
+    emitSwipe("up");
+
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it("does not register on non-mac platforms", () => {
+    const { win, send, emitSwipe } = makeWindow();
+
+    installNavigationGestures(win, "linux");
+    emitSwipe("right");
+
+    expect(send).not.toHaveBeenCalled();
+  });
+});

apps/desktop/src/main/navigation-gestures.ts

@@ -0,0 +1,18 @@
+import type { BrowserWindow } from "electron";
+import {
+  NAVIGATION_GESTURE_CHANNEL,
+  navigationGestureFromSwipe,
+} from "../shared/navigation-gestures";
+
+export function installNavigationGestures(
+  win: BrowserWindow,
+  platform: NodeJS.Platform = process.platform,
+): void {
+  if (platform !== "darwin") return;
+
+  win.on("swipe", (_event, direction) => {
+    const gesture = navigationGestureFromSwipe(direction);
+    if (!gesture) return;
+    win.webContents.send(NAVIGATION_GESTURE_CHANNEL, gesture);
+  });
+}

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

@@ -1,5 +1,6 @@
 import { ElectronAPI } from "@electron-toolkit/preload";
 import type { RuntimeConfigResult } from "../shared/runtime-config";
+import type { NavigationGesture } from "../shared/navigation-gestures";
 
 interface DesktopAPI {
   /** App version + normalized OS, captured synchronously at preload time. */
@@ -42,6 +43,34 @@ interface DesktopAPI {
       issueKey: string;
     }) => void,
   ) => () => void;
+  /** Listen for native macOS back/forward swipe gestures. Returns an unsubscribe function. */
+  onNavigationGesture: (callback: (gesture: NavigationGesture) => void) => () => void;
+  /** Open the OS folder picker and return the chosen absolute path.
+   *  Used by the Project settings "Add local directory" flow. */
+  pickDirectory: (
+    defaultPath?: string,
+  ) => Promise<{
+    ok: boolean;
+    path?: string;
+    basename?: string;
+    reason?: "cancelled" | "no_window" | "error";
+    error?: string;
+  }>;
+  /** Validate that a path is an existing readable+writable directory.
+   *  Mirrors the daemon's runtime check so the user sees errors before submit. */
+  validateLocalDirectory: (
+    path: string,
+  ) => Promise<{
+    ok: boolean;
+    reason?:
+      | "not_absolute"
+      | "not_found"
+      | "not_a_directory"
+      | "not_readable"
+      | "not_writable"
+      | "error";
+    error?: string;
+  }>;
 }
 
 interface DaemonStatus {
@@ -66,6 +95,7 @@ interface DaemonAPI {
   stop: () => Promise<{ success: boolean; error?: string }>;
   restart: () => Promise<{ success: boolean; error?: string }>;
   getStatus: () => Promise<DaemonStatus>;
+  getHostName: () => Promise<string>;
   onStatusChange: (callback: (status: DaemonStatus) => void) => () => void;
   setTargetApiUrl: (url: string) => Promise<void>;
   syncToken: (token: string, userId: string) => Promise<void>;

apps/desktop/src/preload/index.ts

@@ -1,6 +1,11 @@
 import { contextBridge, ipcRenderer } from "electron";
 import { electronAPI } from "@electron-toolkit/preload";
 import type { RuntimeConfigResult } from "../shared/runtime-config";
+import {
+  isNavigationGesture,
+  NAVIGATION_GESTURE_CHANNEL,
+  type NavigationGesture,
+} from "../shared/navigation-gestures";
 
 // Synchronously fetch app metadata from main at preload time so the renderer
 // can pass it into CoreProvider during the initial render — the alternative
@@ -141,6 +146,22 @@ const desktopAPI = {
       ipcRenderer.removeListener("inbox:open", handler);
     };
   },
+  /** Listen for native macOS back/forward swipe gestures. */
+  onNavigationGesture: (callback: (gesture: NavigationGesture) => void) => {
+    const handler = (_event: Electron.IpcRendererEvent, gesture: unknown) => {
+      if (isNavigationGesture(gesture)) callback(gesture);
+    };
+    ipcRenderer.on(NAVIGATION_GESTURE_CHANNEL, handler);
+    return () => {
+      ipcRenderer.removeListener(NAVIGATION_GESTURE_CHANNEL, handler);
+    };
+  },
+  /** Open the OS folder picker and return the chosen absolute path. */
+  pickDirectory: (defaultPath?: string) =>
+    ipcRenderer.invoke("local-directory:pick", defaultPath),
+  /** Validate that a path is an existing readable+writable directory. */
+  validateLocalDirectory: (path: string) =>
+    ipcRenderer.invoke("local-directory:validate", path),
 };
 
 interface DaemonStatus {
@@ -164,6 +185,8 @@ const daemonAPI = {
     ipcRenderer.invoke("daemon:restart"),
   getStatus: (): Promise<DaemonStatus> =>
     ipcRenderer.invoke("daemon:get-status"),
+  getHostName: (): Promise<string> =>
+    ipcRenderer.invoke("daemon:get-host-name"),
   onStatusChange: (callback: (status: DaemonStatus) => void) => {
     const handler = (_: unknown, status: DaemonStatus) => callback(status);
     ipcRenderer.on("daemon:status", handler);

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

@@ -3,9 +3,11 @@ 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 { useWelcomeStore } from "@multica/core/onboarding";
 import { workspaceKeys, workspaceListOptions } from "@multica/core/workspace/queries";
 import { api } from "@multica/core/api";
 import { useHasOnboarded } from "@multica/core/paths";
+import { setCurrentWorkspace } from "@multica/core/platform";
 import { ThemeProvider } from "@multica/ui/components/common/theme-provider";
 import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
 import { Toaster } from "@multica/ui/components/ui/sonner";
@@ -118,25 +120,31 @@ function AppContent() {
     : undefined;
   useDaemonIPCBridge(activeWsId);
 
-  // Pre-workspace overlay routing for desktop. Mirrors the web entry-point
-  // judgment in callback / login:
-  //   un-onboarded:
-  //     pending invites on email → /invitations overlay
-  //     no invites               → /onboarding overlay
-  //   already onboarded:
-  //     zero workspaces          → /workspaces/new overlay
-  //     ≥1 workspaces            → no overlay, fall through to dashboard
+  // Pre-workspace overlay routing for desktop. Mirrors the web layout
+  // hard gate via overlays (desktop has no URL bar, so we open the
+  // onboarding overlay instead of router.replace):
+  //   onboarded + has workspace      → no overlay, dashboard
+  //   un-onboarded (any wsCount):
+  //     pending invites on email     → /invitations overlay
+  //     no invites                   → /onboarding overlay
+  //   onboarded + no workspace       → /workspaces/new overlay
   //
-  // 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.
+  // V3 invariant: `onboarded_at != null` is the only path into the
+  // dashboard. CreateWorkspace does not mark onboarded; only Step 3's
+  // CompleteOnboarding (and AcceptInvitation) flip the flag. A user who
+  // somehow has a workspace but no onboarded mark must be sent back to
+  // /onboarding — we also clear the active workspace so the dashboard
+  // doesn't render under the overlay with stale workspace context.
   useEffect(() => {
     if (!user || !workspaceListFetched) return undefined;
     const { overlay, open } = useWindowOverlayStore.getState();
     if (overlay) return undefined;
-    if (wsCount > 0) return undefined;
+    if (hasOnboarded && wsCount > 0) return undefined;
     if (!hasOnboarded) {
+      // Stale workspace context (if any) would leak X-Workspace-Slug
+      // headers into onboarding-time API calls. Clear it before opening
+      // the overlay.
+      setCurrentWorkspace(null, null);
       // 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
@@ -258,6 +266,9 @@ function BlockingRuntimeConfigError({ message }: { message: string }) {
 async function handleDaemonLogout() {
   useTabStore.getState().reset();
   useWindowOverlayStore.getState().close();
+  // Drop any post-onboarding welcome signal so user B logging in next
+  // doesn't inherit user A's pending modal state.
+  useWelcomeStore.getState().reset();
   try {
     await window.daemonAPI.clearToken();
   } catch {

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

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

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

@@ -0,0 +1,54 @@
+import { useEffect, useState } from "react";
+import { AgentsPage } from "@multica/views/agents";
+import type { DaemonStatus } from "../../../shared/daemon-types";
+
+/**
+ * Desktop wrapper around the shared `AgentsPage`. Bridges the Electron
+ * `daemonAPI` (main-process daemon state) into the page so the runtime
+ * machine filter can render the Local section the same way the Runtimes
+ * page does — without these props the page falls back to grouping
+ * every local-mode runtime under "Remote" with a generic title, which
+ * breaks the "drill from a machine into its agents" promise of the
+ * filter.
+ *
+ * Mirrors `DesktopRuntimesPage`: we cache the last seen daemon
+ * identity so the Local row doesn't get reclassified as Remote when
+ * the daemon is stopped (which would null out `status.daemonId`), and
+ * we fall back to the OS hostname so the section label stays useful
+ * even when the app doesn't manage the running daemon (WSL2 etc.).
+ */
+export function DesktopAgentsPage() {
+  const [status, setStatus] = useState<DaemonStatus>({ state: "stopped" });
+  const [lastIdentity, setLastIdentity] = useState<{
+    daemonId: string | null;
+    deviceName: string | null;
+  }>({ daemonId: null, deviceName: null });
+  const [hostName, setHostName] = useState<string | null>(null);
+
+  useEffect(() => {
+    const apply = (s: DaemonStatus) => {
+      setStatus(s);
+      if (s.daemonId) {
+        setLastIdentity({
+          daemonId: s.daemonId,
+          deviceName: s.deviceName ?? null,
+        });
+      }
+    };
+    window.daemonAPI.getStatus().then(apply);
+    window.daemonAPI.getHostName().then((name) => setHostName(name || null));
+    return window.daemonAPI.onStatusChange(apply);
+  }, []);
+
+  return (
+    <AgentsPage
+      localDaemonId={status.daemonId ?? lastIdentity.daemonId}
+      localMachineName={status.deviceName ?? lastIdentity.deviceName ?? hostName}
+      // Desktop owns a local machine for the lifetime of the app, even
+      // while the daemon is stopped or hasn't registered yet. The shared
+      // page synthesizes a placeholder local row so the filter dropdown
+      // still has a Local option to pick in the empty window.
+      hasLocalMachine
+    />
+  );
+}

apps/desktop/src/renderer/src/components/desktop-layout.tsx

@@ -13,7 +13,6 @@ import { ModalRegistry } from "@multica/views/modals/registry";
 import { AppSidebar } from "@multica/views/layout";
 import { SearchCommand, SearchTrigger } from "@multica/views/search";
 import { ChatFab, ChatWindow } from "@multica/views/chat";
-import { StarterContentPrompt } from "@multica/views/onboarding";
 import { WorkspaceSlugProvider, paths, useCurrentWorkspace } from "@multica/core/paths";
 import { getCurrentSlug, subscribeToCurrentSlug } from "@multica/core/platform";
 import { useDesktopUnreadBadge } from "@multica/views/platform";
@@ -35,6 +34,7 @@ function SidebarTopBar() {
         style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
       >
         <button
+          type="button"
           onClick={goBack}
           disabled={!canGoBack}
           aria-label="Go back"
@@ -43,6 +43,7 @@ function SidebarTopBar() {
           <ChevronLeft className="size-4" />
         </button>
         <button
+          type="button"
           onClick={goForward}
           disabled={!canGoForward}
           aria-label="Go forward"
@@ -55,6 +56,20 @@ function SidebarTopBar() {
   );
 }
 
+function useNativeNavigationGestures() {
+  const { goBack, goForward } = useTabHistory();
+
+  useEffect(() => {
+    return window.desktopAPI.onNavigationGesture((gesture) => {
+      if (gesture === "back") {
+        goBack();
+      } else {
+        goForward();
+      }
+    });
+  }, [goBack, goForward]);
+}
+
 // The main area's top bar doubles as a window drag region. When the sidebar
 // is not occupying main-flow width — either user-collapsed (offcanvas) or
 // auto-hidden in mobile mode (<768px, becomes a sheet drawer) — we pad the
@@ -133,6 +148,7 @@ function DesktopInboxBridge() {
 export function DesktopShell() {
   useInternalLinkHandler();
   useActiveTitleSync();
+  useNativeNavigationGestures();
 
   // Reactive read of current workspace slug from the platform singleton.
   // On first mount, slug is null until WorkspaceRouteLayout (inside the tab
@@ -169,7 +185,6 @@ export function DesktopShell() {
         </div>
         {slug && <ModalRegistry />}
         {slug && <SearchCommand />}
-        {slug && <StarterContentPrompt />}
         <WindowOverlay />
       </WorkspaceSlugProvider>
     </DesktopNavigationProvider>

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

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 import { RuntimesPage } from "@multica/views/runtimes";
-import { DaemonRuntimeCard } from "./daemon-runtime-card";
+import { DaemonRuntimeActions } from "./daemon-runtime-card";
 import type { DaemonStatus } from "../../../shared/daemon-types";
 
 /**
@@ -19,10 +19,34 @@ import type { DaemonStatus } from "../../../shared/daemon-types";
  */
 export function DesktopRuntimesPage() {
   const [status, setStatus] = useState<DaemonStatus>({ state: "stopped" });
+  // Remember the last known daemonId/deviceName. After the daemon is
+  // stopped, `status.daemonId` goes back to undefined — without this
+  // sticky cache the local row would either disappear or get reclassified
+  // as a remote machine (since `isCurrent` requires a daemonId match),
+  // taking the Start button with it.
+  const [lastIdentity, setLastIdentity] = useState<{
+    daemonId: string | null;
+    deviceName: string | null;
+  }>({ daemonId: null, deviceName: null });
+  // The host's OS hostname, independent of any daemon. Used as the last
+  // fallback for the local machine name so consolidation still works when
+  // the app doesn't manage the running daemon (e.g. it lives in WSL2) and
+  // thus never reports a device name.
+  const [hostName, setHostName] = useState<string | null>(null);
 
   useEffect(() => {
-    window.daemonAPI.getStatus().then(setStatus);
-    return window.daemonAPI.onStatusChange(setStatus);
+    const apply = (s: DaemonStatus) => {
+      setStatus(s);
+      if (s.daemonId) {
+        setLastIdentity({
+          daemonId: s.daemonId,
+          deviceName: s.deviceName ?? null,
+        });
+      }
+    };
+    window.daemonAPI.getStatus().then(apply);
+    window.daemonAPI.getHostName().then((name) => setHostName(name || null));
+    return window.daemonAPI.onStatusChange(apply);
   }, []);
 
   const bootstrapping =
@@ -32,7 +56,14 @@ export function DesktopRuntimesPage() {
 
   return (
     <RuntimesPage
-      topSlot={<DaemonRuntimeCard />}
+      localDaemonId={status.daemonId ?? lastIdentity.daemonId}
+      localMachineName={status.deviceName ?? lastIdentity.deviceName ?? hostName}
+      localMachineActions={<DaemonRuntimeActions />}
+      // Desktop owns a local machine for the lifetime of the app, even
+      // while the daemon is stopped or hasn't registered yet. The shared
+      // page synthesizes a placeholder local row when no real runtime
+      // matches, so the Start button is always reachable.
+      hasLocalMachine
       bootstrapping={bootstrapping}
     />
   );

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

@@ -116,7 +116,7 @@ describe("PageviewTracker", () => {
     expect(state.capturePageview).not.toHaveBeenCalled();
   });
 
-  it("fires pageview when a new tab is opened (openInNewTab / addTab)", () => {
+  it("fires pageview when a foreground tab is added (addTab path)", () => {
     state.byWorkspace = {
       acme: {
         activeTabId: "tA",
@@ -128,7 +128,11 @@ describe("PageviewTracker", () => {
     const { rerender } = render(<PageviewTracker />);
     state.capturePageview.mockClear();
 
-    // Simulate openInNewTab("/acme/agents") → new tab tC added and activated.
+    // Simulate a foreground new-tab action (e.g. an explicit "Open in new
+    // tab" toolbar button that passes `{ activate: true }`) — tC is
+    // appended AND becomes active. `openInNewTab` defaults to background
+    // (no `setActiveTab`); only the `activate: true` branch produces the
+    // state change this test exercises.
     state.byWorkspace = {
       acme: {
         activeTabId: "tC",

apps/desktop/src/renderer/src/components/tab-bar.test.tsx

@@ -0,0 +1,151 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { render, fireEvent, within } from "@testing-library/react";
+
+type MockTab = {
+  id: string;
+  path: string;
+  title: string;
+  icon: string;
+  pinned: boolean;
+};
+
+const state = vi.hoisted(() => ({
+  activeWorkspaceSlug: "acme" as string | null,
+  byWorkspace: {
+    acme: {
+      activeTabId: "tA",
+      tabs: [
+        { id: "tA", path: "/acme/issues", title: "Issues", icon: "ListTodo", pinned: false },
+        { id: "tB", path: "/acme/projects", title: "Projects", icon: "ListTodo", pinned: false },
+      ] as MockTab[],
+    },
+  } as Record<string, { activeTabId: string; tabs: MockTab[] }>,
+  togglePin: vi.fn<(tabId: string) => void>(),
+  closeTab: vi.fn<(tabId: string) => void>(),
+  setActiveTab: vi.fn<(tabId: string) => void>(),
+  moveTab: vi.fn<(from: number, to: number) => void>(),
+  addTab: vi.fn<(path: string, title: string, icon: string) => string>(),
+}));
+
+vi.mock("@/stores/tab-store", () => {
+  const store = {
+    get activeWorkspaceSlug() {
+      return state.activeWorkspaceSlug;
+    },
+    get byWorkspace() {
+      return state.byWorkspace;
+    },
+    togglePin: state.togglePin,
+    closeTab: state.closeTab,
+    setActiveTab: state.setActiveTab,
+    moveTab: state.moveTab,
+    addTab: state.addTab,
+  };
+  const useTabStore = Object.assign(
+    (selector?: (s: typeof store) => unknown) =>
+      selector ? selector(store) : store,
+    { getState: () => store },
+  );
+  const useActiveGroup = () =>
+    state.activeWorkspaceSlug
+      ? (state.byWorkspace[state.activeWorkspaceSlug] ?? null)
+      : null;
+  const resolveRouteIcon = () => "ListTodo";
+  return { useTabStore, useActiveGroup, resolveRouteIcon };
+});
+
+vi.mock("@multica/core/paths", () => ({
+  paths: {
+    workspace: (slug: string) => ({
+      issues: () => `/${slug}/issues`,
+    }),
+  },
+}));
+
+import { TabBar } from "./tab-bar";
+
+function reset() {
+  state.activeWorkspaceSlug = "acme";
+  state.byWorkspace = {
+    acme: {
+      activeTabId: "tA",
+      tabs: [
+        { id: "tA", path: "/acme/issues", title: "Issues", icon: "ListTodo", pinned: false },
+        { id: "tB", path: "/acme/projects", title: "Projects", icon: "ListTodo", pinned: false },
+      ],
+    },
+  };
+  state.togglePin.mockReset();
+  state.closeTab.mockReset();
+  state.setActiveTab.mockReset();
+  state.moveTab.mockReset();
+  state.addTab.mockReset();
+}
+
+beforeEach(reset);
+
+describe("TabBar hover action buttons", () => {
+  it("renders a Pin button on every unpinned tab and an Unpin button on every pinned tab", () => {
+    state.byWorkspace.acme.tabs = [
+      { id: "tA", path: "/acme/issues", title: "Issues", icon: "ListTodo", pinned: true },
+      { id: "tB", path: "/acme/projects", title: "Projects", icon: "ListTodo", pinned: false },
+    ];
+    const { getAllByLabelText } = render(<TabBar />);
+    expect(getAllByLabelText("Unpin tab")).toHaveLength(1);
+    expect(getAllByLabelText("Pin tab")).toHaveLength(1);
+  });
+
+  it("clicking the Pin button calls togglePin for the tab", () => {
+    const { getAllByLabelText } = render(<TabBar />);
+    const pinButtons = getAllByLabelText("Pin tab");
+    fireEvent.click(pinButtons[1]); // click Pin on tB (Projects)
+    expect(state.togglePin).toHaveBeenCalledWith("tB");
+  });
+
+  it("clicking the Unpin button on a pinned tab calls togglePin", () => {
+    state.byWorkspace.acme.tabs = [
+      { id: "tA", path: "/acme/issues", title: "Issues", icon: "ListTodo", pinned: true },
+      { id: "tB", path: "/acme/projects", title: "Projects", icon: "ListTodo", pinned: false },
+    ];
+    const { getByLabelText } = render(<TabBar />);
+    fireEvent.click(getByLabelText("Unpin tab"));
+    expect(state.togglePin).toHaveBeenCalledWith("tA");
+  });
+
+  it("hides the X close button on a pinned tab but keeps it on an unpinned tab", () => {
+    state.byWorkspace.acme.tabs = [
+      { id: "tA", path: "/acme/issues", title: "Issues", icon: "ListTodo", pinned: true },
+      { id: "tB", path: "/acme/projects", title: "Projects", icon: "ListTodo", pinned: false },
+    ];
+    const { queryAllByLabelText } = render(<TabBar />);
+    // Only the unpinned tab exposes a Close affordance — pinned tab requires
+    // explicit Unpin first (RFC §3 D3c FINAL).
+    expect(queryAllByLabelText("Close tab")).toHaveLength(1);
+  });
+
+  it("keeps the full title visible on a pinned tab (no icon-only collapse)", () => {
+    state.byWorkspace.acme.tabs = [
+      { id: "tA", path: "/acme/issues", title: "Issues", icon: "ListTodo", pinned: true },
+    ];
+    const { getByLabelText } = render(<TabBar />);
+    const pinnedTab = getByLabelText("Issues (pinned)");
+    expect(within(pinnedTab).getByText("Issues")).toBeTruthy();
+  });
+
+  it("renders the Pin glyph as the leading icon on a pinned tab and the route icon on an unpinned tab", () => {
+    state.byWorkspace.acme.tabs = [
+      { id: "tA", path: "/acme/issues", title: "Issues", icon: "ListTodo", pinned: true },
+      { id: "tB", path: "/acme/projects", title: "Projects", icon: "ListTodo", pinned: false },
+    ];
+    const { getByLabelText } = render(<TabBar />);
+    const pinnedTab = getByLabelText("Issues (pinned)");
+    const unpinnedTab = getByLabelText("Projects");
+    // lucide-react renders the icon name into the class list. The leading
+    // slot icon is size-3.5; the hover Pin/Unpin action button is size-2.5,
+    // so we qualify on size to avoid matching the action glyph.
+    expect(pinnedTab.querySelector(".lucide-pin.size-3\\.5")).toBeTruthy();
+    expect(pinnedTab.querySelector(".lucide-list-todo")).toBeNull();
+    expect(unpinnedTab.querySelector(".lucide-list-todo.size-3\\.5")).toBeTruthy();
+    expect(unpinnedTab.querySelector(".lucide-pin.size-3\\.5")).toBeNull();
+  });
+});

apps/desktop/src/renderer/src/components/tab-bar.tsx

@@ -1,3 +1,4 @@
+import { Fragment } from "react";
 import {
   Inbox,
   CircleUser,
@@ -8,6 +9,8 @@ import {
   Settings,
   X,
   Plus,
+  Pin,
+  PinOff,
   type LucideIcon,
 } from "lucide-react";
 import {
@@ -28,8 +31,20 @@ import {
   restrictToParentElement,
 } from "@dnd-kit/modifiers";
 import { CSS } from "@dnd-kit/utilities";
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuTrigger,
+} from "@multica/ui/components/ui/context-menu";
 import { cn } from "@multica/ui/lib/utils";
-import { useTabStore, useActiveGroup, resolveRouteIcon, type Tab } from "@/stores/tab-store";
+import {
+  useTabStore,
+  useActiveGroup,
+  resolveRouteIcon,
+  type Tab,
+} from "@/stores/tab-store";
 import { paths } from "@multica/core/paths";
 
 const TAB_ICONS: Record<string, LucideIcon> = {
@@ -42,9 +57,23 @@ const TAB_ICONS: Record<string, LucideIcon> = {
   Settings,
 };
 
-function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolean; isOnly: boolean }) {
+function SortableTabItem({
+  tab,
+  isActive,
+  isOnly,
+}: {
+  tab: Tab;
+  isActive: boolean;
+  /**
+   * True iff this is the only tab in the workspace. Hiding X on the last
+   * tab matches existing behavior and avoids the surprise of the store's
+   * last-tab reseed kicking in. Pinned tabs always hide X (RFC §3 D3c).
+   */
+  isOnly: boolean;
+}) {
   const setActiveTab = useTabStore((s) => s.setActiveTab);
   const closeTab = useTabStore((s) => s.closeTab);
+  const togglePin = useTabStore((s) => s.togglePin);
 
   const {
     attributes,
@@ -55,7 +84,11 @@ function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolea
     isDragging,
   } = useSortable({ id: tab.id });
 
-  const Icon = TAB_ICONS[tab.icon];
+  // Pinned tabs swap the route icon for a Pin glyph as the static "I am
+  // pinned" indicator (RFC §3 D1v-iv FINAL). The route information is still
+  // present in the title, and this avoids a hard left accent border that read
+  // as visually heavy in light mode.
+  const LeadingIcon = tab.pinned ? Pin : TAB_ICONS[tab.icon];
 
   const style = {
     transform: CSS.Transform.toString(transform),
@@ -74,17 +107,31 @@ function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolea
     closeTab(tab.id);
   };
 
-  const stopDragOnClose = (e: React.PointerEvent) => {
+  const handleTogglePin = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    togglePin(tab.id);
+  };
+
+  const stopDragOnAction = (e: React.PointerEvent) => {
     e.stopPropagation();
   };
 
-  return (
+  // Pinned tabs keep their full title (RFC §3 D1v-ii FINAL). The only visual
+  // differences vs. unpinned tabs are the leading Pin icon (swapped in above)
+  // and the suppressed X (closing requires explicit Unpin). Pin/Unpin is
+  // reachable via the hover action button below and the right-click menu.
+  const showCloseButton = !tab.pinned && !isOnly;
+
+  const tabButton = (
     <button
+      type="button"
       ref={setNodeRef}
       style={style}
       {...attributes}
       {...listeners}
       onClick={handleClick}
+      aria-label={tab.pinned ? `${tab.title} (pinned)` : tab.title}
+      title={tab.pinned ? `${tab.title} (pinned)` : undefined}
       className={cn(
         "group flex h-7 w-40 items-center gap-1.5 rounded-md px-2 text-xs transition-colors",
         "select-none cursor-default",
@@ -94,7 +141,7 @@ function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolea
         isDragging && "opacity-60",
       )}
     >
-      {Icon && <Icon className="size-3.5 shrink-0" />}
+      {LeadingIcon && <LeadingIcon className="size-3.5 shrink-0" />}
       <span
         className="min-w-0 flex-1 overflow-hidden whitespace-nowrap text-left"
         style={{
@@ -104,10 +151,22 @@ function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolea
       >
         {tab.title}
       </span>
-      {!isOnly && (
+      <span
+        onClick={handleTogglePin}
+        onPointerDown={stopDragOnAction}
+        role="button"
+        aria-label={tab.pinned ? "Unpin tab" : "Pin tab"}
+        title={tab.pinned ? "Unpin tab" : "Pin tab"}
+        className="hidden size-3.5 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors group-hover:flex hover:bg-muted-foreground/20 hover:text-foreground"
+      >
+        {tab.pinned ? <PinOff className="size-2.5" /> : <Pin className="size-2.5" />}
+      </span>
+      {showCloseButton && (
         <span
           onClick={handleClose}
-          onPointerDown={stopDragOnClose}
+          onPointerDown={stopDragOnAction}
+          role="button"
+          aria-label="Close tab"
           className="hidden size-3.5 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors group-hover:flex hover:bg-muted-foreground/20 hover:text-foreground"
         >
           <X className="size-2.5" />
@@ -115,6 +174,36 @@ function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolea
       )}
     </button>
   );
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger render={tabButton} />
+      <ContextMenuContent>
+        <ContextMenuItem onClick={() => togglePin(tab.id)}>
+          {tab.pinned ? (
+            <>
+              <PinOff />
+              Unpin tab
+            </>
+          ) : (
+            <>
+              <Pin />
+              Pin tab
+            </>
+          )}
+        </ContextMenuItem>
+        <ContextMenuSeparator />
+        <ContextMenuItem
+          variant="destructive"
+          disabled={tab.pinned || isOnly}
+          onClick={() => closeTab(tab.id)}
+        >
+          <X />
+          Close tab
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  );
 }
 
 function NewTabButton() {
@@ -133,6 +222,7 @@ function NewTabButton() {
 
   return (
     <button
+      type="button"
       onClick={handleClick}
       style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
       className="flex size-7 shrink-0 items-center justify-center rounded-md text-muted-foreground/70 transition-colors hover:bg-muted/50 hover:text-muted-foreground"
@@ -155,12 +245,17 @@ export function TabBar() {
   const tabs = group?.tabs ?? [];
   const activeTabId = group?.activeTabId ?? "";
   const tabIds = tabs.map((t) => t.id);
+  const pinnedCount = tabs.filter((t) => t.pinned).length;
+  const unpinnedCount = tabs.length - pinnedCount;
 
   const handleDragEnd = (event: DragEndEvent) => {
     const { active, over } = event;
     if (!over || active.id === over.id) return;
     const from = tabs.findIndex((t) => t.id === active.id);
     const to = tabs.findIndex((t) => t.id === over.id);
+    // The store clamps the destination to within the source tab's zone
+    // (pinned vs unpinned), so this call is safe even when the user tries
+    // to drag across the boundary — the tab will land at the boundary.
     if (from !== -1 && to !== -1) moveTab(from, to);
   };
 
@@ -173,13 +268,22 @@ export function TabBar() {
         onDragEnd={handleDragEnd}
       >
         <SortableContext items={tabIds} strategy={horizontalListSortingStrategy}>
-          {tabs.map((tab) => (
-            <SortableTabItem
-              key={tab.id}
-              tab={tab}
-              isActive={tab.id === activeTabId}
-              isOnly={tabs.length === 1}
-            />
+          {tabs.map((tab, index) => (
+            <Fragment key={tab.id}>
+              <SortableTabItem
+                tab={tab}
+                isActive={tab.id === activeTabId}
+                isOnly={tabs.length === 1}
+              />
+              {tab.pinned &&
+                index === pinnedCount - 1 &&
+                unpinnedCount > 0 && (
+                  <div
+                    aria-hidden
+                    className="mx-1 h-4 w-px bg-border"
+                  />
+                )}
+            </Fragment>
           ))}
         </SortableContext>
       </DndContext>

apps/desktop/src/renderer/src/components/tab-content.tsx

@@ -3,6 +3,7 @@ import { RouterProvider } from "react-router-dom";
 import { useActiveGroup } from "@/stores/tab-store";
 import { TabNavigationProvider } from "@/platform/navigation";
 import { useTabRouterSync } from "@/hooks/use-tab-router-sync";
+import { useTabScrollRestore } from "@/hooks/use-tab-scroll-restore";
 import type { Tab } from "@/stores/tab-store";
 
 /**
@@ -15,6 +16,28 @@ function TabRouterInner({ tab }: { tab: Tab }) {
   return null;
 }
 
+/**
+ * Wraps a tab's subtree so its scroll position survives the round trip
+ * through `<Activity mode="hidden">`. Lives inside Activity so the hook's
+ * effects cycle with the tab's visibility — see `useTabScrollRestore` for
+ * the mechanism. `display: contents` keeps the wrapper transparent to
+ * the surrounding flex layout.
+ */
+function TabScrollRestoreWrapper({
+  tabPath,
+  children,
+}: {
+  tabPath: string;
+  children: React.ReactNode;
+}) {
+  const ref = useTabScrollRestore(tabPath);
+  return (
+    <div ref={ref} style={{ display: "contents" }}>
+      {children}
+    </div>
+  );
+}
+
 /**
  * Renders the active workspace's tabs using Activity for state preservation.
  * Only the active tab is visible; hidden tabs keep their DOM and React state.
@@ -44,10 +67,12 @@ export function TabContent() {
           key={tab.id}
           mode={tab.id === group.activeTabId ? "visible" : "hidden"}
         >
-          <TabNavigationProvider router={tab.router}>
-            <RouterProvider router={tab.router} />
-            <TabRouterInner tab={tab} />
-          </TabNavigationProvider>
+          <TabScrollRestoreWrapper tabPath={tab.path}>
+            <TabNavigationProvider router={tab.router}>
+              <RouterProvider router={tab.router} />
+              <TabRouterInner tab={tab} />
+            </TabNavigationProvider>
+          </TabScrollRestoreWrapper>
         </Activity>
       ))}
     </>

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

@@ -26,6 +26,7 @@ export function UpdateNotification() {
   return (
     <div className="fixed bottom-4 right-4 z-50 w-80 rounded-lg border border-border bg-background p-4 shadow-lg animate-in slide-in-from-bottom-2 fade-in duration-300">
       <button
+        type="button"
         onClick={() => setDismissed(true)}
         className="absolute top-2 right-2 rounded-md p-1 text-muted-foreground hover:text-foreground transition-colors"
       >
@@ -43,12 +44,14 @@ export function UpdateNotification() {
           </p>
           <div className="mt-2 flex items-center gap-1.5">
             <button
+              type="button"
               onClick={() => setDismissed(true)}
               className="inline-flex items-center rounded-md border border-border bg-background px-3 py-1.5 text-xs font-medium text-foreground hover:bg-accent transition-colors"
             >
               Later
             </button>
             <button
+              type="button"
               onClick={() => window.updater.installUpdate()}
               className="inline-flex items-center rounded-md bg-primary px-3 py-1.5 text-xs font-medium text-primary-foreground hover:bg-primary/90 transition-colors"
             >

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

@@ -1,6 +1,7 @@
 import { useCallback, useState } from "react";
 import { AlertCircle, ArrowDownToLine, Check, Loader2 } from "lucide-react";
 import { Button } from "@multica/ui/components/ui/button";
+import { useT } from "@multica/views/i18n";
 
 type CheckState =
   | { status: "idle" }
@@ -10,6 +11,7 @@ type CheckState =
   | { status: "error"; message: string };
 
 export function UpdatesSettingsTab() {
+  const { t } = useT("settings");
   const [state, setState] = useState<CheckState>({ status: "idle" });
   const currentVersion = window.desktopAPI.appInfo.version;
 
@@ -29,17 +31,15 @@ export function UpdatesSettingsTab() {
 
   return (
     <div>
-      <h2 className="text-lg font-semibold">Updates</h2>
+      <h2 className="text-lg font-semibold">{t(($) => $.desktop.updates.title)}</h2>
       <p className="text-sm text-muted-foreground mt-1">
-        The desktop app checks for new versions automatically once an hour and
-        shortly after launch, downloading them in the background. You&apos;ll
-        be prompted to restart once an update is ready.
+        {t(($) => $.desktop.updates.description)}
       </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 font-medium">{t(($) => $.desktop.updates.current_version)}</p>
             <p className="text-sm text-muted-foreground mt-0.5 font-mono">
               v{currentVersion}
             </p>
@@ -48,23 +48,20 @@ export function UpdatesSettingsTab() {
 
         <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>
+            <p className="text-sm font-medium">{t(($) => $.desktop.updates.check_section_title)}</p>
             <p className="text-sm text-muted-foreground mt-0.5">
-              Trigger a check now instead of waiting for the next automatic
-              poll. Available updates download in the background and show a
-              restart prompt when ready.
+              {t(($) => $.desktop.updates.check_section_description)}
             </p>
             {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.
+                {t(($) => $.desktop.updates.up_to_date)}
               </p>
             )}
             {state.status === "available" && (
               <p className="text-sm text-muted-foreground mt-2 inline-flex items-center gap-1.5">
                 <ArrowDownToLine className="size-3.5 text-primary" />
-                v{state.latestVersion} is downloading in the background —
-                you&apos;ll be notified when it&apos;s ready to install.
+                {t(($) => $.desktop.updates.downloading, { version: state.latestVersion })}
               </p>
             )}
             {state.status === "error" && (
@@ -84,10 +81,10 @@ export function UpdatesSettingsTab() {
               {state.status === "checking" ? (
                 <>
                   <Loader2 className="size-3.5 animate-spin" />
-                  Checking…
+                  {t(($) => $.desktop.updates.checking)}
                 </>
               ) : (
-                "Check now"
+                t(($) => $.desktop.updates.check_now)
               )}
             </Button>
           </div>

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

@@ -62,18 +62,25 @@ function WindowOverlayInner() {
       {overlay.type === "invitations" && <InvitationsPage />}
       {overlay.type === "onboarding" && (
         <OnboardingFlow
-          onComplete={(ws) => {
+          onComplete={(ws, issueId) => {
             close();
-            // Post-onboarding landing is always the workspace issues
-            // list. The welcome-issue flow moved into a dialog that
-            // renders on that page (StarterContentPrompt), so the
-            // flow doesn't need to thread a target issue id back here.
-            if (ws) {
+            // Runtime-connected onboarding lands on its single guide
+            // issue. Runtime-less exits still land on the issues list.
+            if (ws && issueId) {
+              push(paths.workspace(ws.slug).issueDetail(issueId));
+            } else if (ws) {
               push(paths.workspace(ws.slug).issues());
             } else {
               push(paths.root());
             }
           }}
+          // Restart the bundled daemon when the user hits Refresh on
+          // Step 3. The daemon's PATH probe runs once at boot, so a
+          // newly-installed CLI (Claude / Codex / Cursor) doesn't show
+          // up until the daemon is bounced.
+          onRuntimeRefresh={async () => {
+            await window.daemonAPI?.restart?.();
+          }}
         />
       )}
     </div>

apps/desktop/src/renderer/src/components/workspace-route-layout.tsx

@@ -9,8 +9,10 @@ import {
 import { setCurrentWorkspace } from "@multica/core/platform";
 import { useAuthStore } from "@multica/core/auth";
 import { useWorkspaceSeen } from "@multica/views/workspace/use-workspace-seen";
+import { WelcomeAfterOnboarding } from "@multica/views/workspace/welcome-after-onboarding";
 import { WorkspacePresencePrefetch } from "@multica/views/layout";
 import { useTabStore } from "@/stores/tab-store";
+import { useWindowOverlayStore } from "@/stores/window-overlay-store";
 
 /**
  * Desktop equivalent of apps/web/app/[workspaceSlug]/layout.tsx.
@@ -34,6 +36,15 @@ export function WorkspaceRouteLayout() {
   const navigate = useNavigate();
   const user = useAuthStore((s) => s.user);
   const isAuthLoading = useAuthStore((s) => s.isLoading);
+  // While a WindowOverlay is open (onboarding, accept-invite, new-workspace),
+  // the underlying tab is still mounted in the React tree — so this layout
+  // and its WelcomeAfterOnboarding Modal would render UNDER the overlay.
+  // Because the modal uses a Portal that targets document.body, it ends up
+  // rendered LATER in the DOM and visually outranks the overlay's z-50.
+  // Suppress the modal whenever any overlay is active; the moment the
+  // overlay closes the welcome hook re-evaluates and pops if its store
+  // signal is still set.
+  const overlayActive = useWindowOverlayStore((s) => s.overlay !== null);
 
   // Workspace routes require auth. If user is unauthenticated, bounce to /login.
   useEffect(() => {
@@ -85,6 +96,14 @@ export function WorkspaceRouteLayout() {
     <WorkspaceSlugProvider slug={workspaceSlug}>
       <WorkspacePresencePrefetch />
       <Outlet />
+      {/* Reads the welcome-store transient signal parked by
+       *  OnboardingFlow.handleRuntimeNext. Suppressed while a WindowOverlay
+       *  (onboarding / accept-invite / new-workspace) is open so the modal
+       *  doesn't portal-jump in front of an active pre-workspace flow.
+       *  Once the overlay closes the hook re-evaluates and pops the
+       *  Modal — unless the store signal has already been consumed, in
+       *  which case the hook renders null. */}
+      {!overlayActive && <WelcomeAfterOnboarding />}
     </WorkspaceSlugProvider>
   );
 }

apps/desktop/src/renderer/src/font-fallback-order.test.ts

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const chineseFonts = ["PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC"];
+const koreanFonts = ["Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans CJK KR"];
+
+function expectChineseFontsBeforeKoreanFonts(source: string) {
+  const chineseIndexes = chineseFonts.map((font) => source.indexOf(font));
+  const koreanIndexes = koreanFonts.map((font) => source.indexOf(font));
+
+  expect(chineseIndexes).not.toContain(-1);
+  expect(koreanIndexes).not.toContain(-1);
+
+  for (const chineseIndex of chineseIndexes) {
+    for (const koreanIndex of koreanIndexes) {
+      expect(chineseIndex).toBeLessThan(koreanIndex);
+    }
+  }
+}
+
+describe("CJK font fallback order", () => {
+  it("keeps desktop Chinese font fallbacks before Korean font fallbacks", () => {
+    const desktopCss = readFileSync(
+      resolve(process.cwd(), "src/renderer/src/globals.css"),
+      "utf8",
+    );
+
+    expectChineseFontsBeforeKoreanFonts(desktopCss);
+  });
+});

apps/desktop/src/renderer/src/globals.css

@@ -6,16 +6,15 @@
 
 @custom-variant dark (&:is(.dark *));
 
-/* Font stack: Inter for Latin UI text + system Chinese fonts for zh content.
+/* Font stack: Inter for Latin UI text + system CJK fonts for localized content.
    Web app uses the same stack via next/font/google in apps/web/app/layout.tsx —
    keep the CJK fallback tail in sync across both files. The Inter primary family
    differs by design: next/font produces `__Inter_xxx` (with a synthetic size-adjusted
    fallback face to prevent FOUT layout shift); desktop uses fontsource's "Inter Variable".
    Both resolve to Inter glyphs, so rendering is identical in practice.
-   Currently covers English + Simplified Chinese. When ja/ko i18n lands, extend
-   the tail with Hiragino Kaku Gothic ProN / Yu Gothic / Apple SD Gothic Neo / Malgun Gothic.
-   Per-character fallback: Latin chars render with Inter, Chinese chars with
-   PingFang SC (macOS) / Microsoft YaHei (Windows) / Noto Sans CJK SC (Linux).
+   Per-character fallback: Latin chars render with Inter, CJK chars render with
+   the platform-native Chinese/Korean fallback when needed. Chinese fonts must stay
+   before Korean fonts so zh users do not receive Korean Hanja glyph shapes.
 
    Mono font has no explicit CJK fallback: CJK chars in code blocks are inherently
    non-aligned with a mono grid (Chinese is proportional), so listing CJK fonts
@@ -23,8 +22,9 @@
    the rare mixed case correctly. */
 :root {
   --font-sans: "Inter Variable", "Inter", -apple-system, BlinkMacSystemFont,
-               "Segoe UI", "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC",
-               sans-serif;
+               "Segoe UI", "PingFang SC", "Microsoft YaHei",
+               "Noto Sans CJK SC", "Apple SD Gothic Neo", "Malgun Gothic",
+               "Noto Sans CJK KR", sans-serif;
   --font-serif: "Source Serif 4 Variable", "Source Serif 4", "Iowan Old Style",
                 "Apple Garamond", Baskerville, "Times New Roman", serif;
   --font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Consolas,

apps/desktop/src/renderer/src/hooks/use-tab-scroll-restore.test.tsx

@@ -0,0 +1,116 @@
+import { Activity } from "react";
+import { describe, expect, it } from "vitest";
+import { fireEvent, render } from "@testing-library/react";
+import { useTabScrollRestore } from "./use-tab-scroll-restore";
+
+function Harness({ path }: { path: string }) {
+  const ref = useTabScrollRestore(path);
+  return (
+    <div ref={ref} style={{ display: "contents" }}>
+      <div
+        data-tab-scroll-root
+        data-testid="scroller"
+        style={{ height: 100, overflow: "auto" }}
+      >
+        <div style={{ height: 1000 }} />
+      </div>
+      <div
+        data-tab-scroll-root="aside"
+        data-testid="aside"
+        style={{ height: 100, overflow: "auto" }}
+      >
+        <div style={{ height: 1000 }} />
+      </div>
+      <div
+        data-testid="unmarked"
+        style={{ height: 100, overflow: "auto" }}
+      >
+        <div style={{ height: 1000 }} />
+      </div>
+    </div>
+  );
+}
+
+function App({ visible, path }: { visible: boolean; path: string }) {
+  return (
+    <Activity mode={visible ? "visible" : "hidden"}>
+      <Harness path={path} />
+    </Activity>
+  );
+}
+
+function setScroll(el: HTMLElement, top: number) {
+  el.scrollTop = top;
+  fireEvent.scroll(el);
+}
+
+describe("useTabScrollRestore", () => {
+  it("restores scroll position when a tab cycles through hidden -> visible", () => {
+    const { rerender, getByTestId } = render(
+      <App visible={true} path="/acme/issues/1" />,
+    );
+    const scroller = getByTestId("scroller") as HTMLElement;
+
+    setScroll(scroller, 500);
+    expect(scroller.scrollTop).toBe(500);
+
+    // Simulate Activity hiding the subtree: layout would drop the offset.
+    rerender(<App visible={false} path="/acme/issues/1" />);
+    scroller.scrollTop = 0;
+
+    rerender(<App visible={true} path="/acme/issues/1" />);
+    expect(scroller.scrollTop).toBe(500);
+  });
+
+  it("restores multiple named scroll roots independently", () => {
+    const { rerender, getByTestId } = render(
+      <App visible={true} path="/acme/issues/1" />,
+    );
+    const main = getByTestId("scroller") as HTMLElement;
+    const aside = getByTestId("aside") as HTMLElement;
+
+    setScroll(main, 300);
+    setScroll(aside, 150);
+
+    rerender(<App visible={false} path="/acme/issues/1" />);
+    main.scrollTop = 0;
+    aside.scrollTop = 0;
+
+    rerender(<App visible={true} path="/acme/issues/1" />);
+    expect(main.scrollTop).toBe(300);
+    expect(aside.scrollTop).toBe(150);
+  });
+
+  it("ignores scroll on elements without the data-tab-scroll-root marker", () => {
+    const { rerender, getByTestId } = render(
+      <App visible={true} path="/acme/issues/1" />,
+    );
+    const unmarked = getByTestId("unmarked") as HTMLElement;
+
+    setScroll(unmarked, 250);
+
+    rerender(<App visible={false} path="/acme/issues/1" />);
+    unmarked.scrollTop = 0;
+
+    rerender(<App visible={true} path="/acme/issues/1" />);
+    expect(unmarked.scrollTop).toBe(0);
+  });
+
+  it("drops saved offsets when the tab path changes (intra-tab navigation)", () => {
+    const { rerender, getByTestId } = render(
+      <App visible={true} path="/acme/issues/1" />,
+    );
+    const scroller = getByTestId("scroller") as HTMLElement;
+
+    setScroll(scroller, 500);
+
+    // Navigating within the tab swaps the active route — same marker key,
+    // different page. We should NOT restore the prior page's offset.
+    rerender(<App visible={true} path="/acme/issues/2" />);
+    scroller.scrollTop = 0;
+
+    rerender(<App visible={false} path="/acme/issues/2" />);
+    rerender(<App visible={true} path="/acme/issues/2" />);
+    expect(scroller.scrollTop).toBe(0);
+  });
+});

apps/desktop/src/renderer/src/hooks/use-tab-scroll-restore.ts

@@ -0,0 +1,106 @@
+import { useEffect, useLayoutEffect, useRef } from "react";
+
+/**
+ * Persist a tab's scroll positions across <Activity> visibility transitions.
+ *
+ * Tabs render under `<Activity mode="visible|hidden">`, which keeps React
+ * state but loses DOM scrollTop — the subtree is taken out of layout while
+ * hidden and rejoins with scrollTop=0. This hook records every marked
+ * container's `scrollTop` while the tab is visible (continuously, via a
+ * capture-phase scroll listener) and restores them in a `useLayoutEffect`
+ * the next time the tab becomes visible, before the browser paints.
+ *
+ * Mark scroll containers in views with `data-tab-scroll-root`. The
+ * attribute value is the cache key — defaults to `"main"` for unnamed
+ * roots. Most pages have a single scroll container, so a bare attribute
+ * is enough; named keys are only needed when a page has multiple
+ * independently scrollable regions whose positions must all be restored.
+ *
+ * When the tab's path changes (intra-tab navigation), the saved offsets
+ * are dropped — the new route's container shares the same marker key but
+ * is a different page, and restoring the old offset would land the user
+ * somewhere arbitrary on the new page.
+ *
+ * For virtualized children (Virtuoso, react-virtual, etc.) the single
+ * synchronous `scrollTop = saved` inside useLayoutEffect isn't enough:
+ * the child registers its observers in a passive useEffect that fires
+ * later, so at restore time the container's scrollHeight has collapsed
+ * to clientHeight and the browser clamps our assignment to 0. The
+ * restore loops across rAF frames until the assignment sticks, which
+ * lets virtualization rehydrate before we give up.
+ */
+export function useTabScrollRestore(tabPath: string) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const savedRef = useRef<Map<string, number>>(new Map());
+  const prevPathRef = useRef(tabPath);
+
+  if (prevPathRef.current !== tabPath) {
+    savedRef.current.clear();
+    prevPathRef.current = tabPath;
+  }
+
+  // <Activity> cleans up effects on hidden and re-mounts them on visible,
+  // so an empty-deps useLayoutEffect runs exactly on every hidden → visible
+  // transition. Restoring here (before the browser paints) handles the
+  // common case without a flash.
+  //
+  // The synchronous set isn't enough for virtualized lists though
+  // (issue-detail uses Virtuoso with customScrollParent). Virtuoso wires
+  // its scroll/resize observers in a passive useEffect, which fires AFTER
+  // useLayoutEffect — so at the moment we try to restore, the spacer that
+  // gives the container its tall scrollHeight hasn't been re-established
+  // yet. The browser silently clamps `scrollTop = saved` down to 0 because
+  // `scrollHeight === clientHeight` in that window. Retry across rAF
+  // frames until the set sticks (or we time out around the time any sane
+  // child should have laid out, ~500ms).
+  useLayoutEffect(() => {
+    const root = containerRef.current;
+    if (!root) return;
+    const els = root.querySelectorAll<HTMLElement>("[data-tab-scroll-root]");
+    const cancellers: Array<() => void> = [];
+    els.forEach((el) => {
+      const key = scrollKey(el);
+      const saved = savedRef.current.get(key);
+      if (saved === undefined) return;
+      el.scrollTop = saved;
+      if (el.scrollTop === saved) return;
+
+      let cancelled = false;
+      let attempts = 0;
+      const maxAttempts = 30; // ~500ms at 60fps
+      const tick = () => {
+        if (cancelled) return;
+        el.scrollTop = saved;
+        attempts++;
+        if (el.scrollTop === saved) return;
+        if (attempts >= maxAttempts) return;
+        requestAnimationFrame(tick);
+      };
+      requestAnimationFrame(tick);
+      cancellers.push(() => {
+        cancelled = true;
+      });
+    });
+    return () => cancellers.forEach((c) => c());
+  }, []);
+
+  useEffect(() => {
+    const root = containerRef.current;
+    if (!root) return;
+    const onScroll = (e: Event) => {
+      const target = e.target;
+      if (!(target instanceof HTMLElement)) return;
+      if (!target.hasAttribute("data-tab-scroll-root")) return;
+      savedRef.current.set(scrollKey(target), target.scrollTop);
+    };
+    // Scroll events don't bubble, but capture catches them anyway.
+    root.addEventListener("scroll", onScroll, { capture: true, passive: true });
+    return () => root.removeEventListener("scroll", onScroll, true);
+  }, []);
+
+  return containerRef;
+}
+
+function scrollKey(el: HTMLElement): string {
+  return el.getAttribute("data-tab-scroll-root") || "main";
+}

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

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

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

@@ -0,0 +1,421 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { render } from "@testing-library/react";
+import { useEffect } from "react";
+
+// Shared in-memory state that the mocked tab store reads / mutates. The test
+// records every method call so we can assert openInNewTab does NOT activate
+// the new tab (i.e. setActiveTab is never invoked on the same-workspace path).
+type MockRouter = {
+  state: { location: { pathname: string; search: string; hash: string } };
+  navigate: ReturnType<typeof vi.fn>;
+};
+
+type MockTab = {
+  id: string;
+  path: string;
+  pinned: boolean;
+  router: MockRouter;
+};
+
+function makeMockRouter(pathname: string, search = "", hash = ""): MockRouter {
+  return {
+    state: { location: { pathname, search, hash } },
+    navigate: vi.fn(),
+  };
+}
+
+const state = vi.hoisted(() => ({
+  activeWorkspaceSlug: "acme" as string | null,
+  byWorkspace: {
+    acme: {
+      activeTabId: "tA",
+      tabs: [
+        {
+          id: "tA",
+          path: "/acme/issues",
+          pinned: false,
+          router: makeMockRouter("/acme/issues"),
+        },
+      ] as MockTab[],
+    },
+  } as Record<string, { activeTabId: string; tabs: MockTab[] }>,
+  openTab: vi.fn<(path: string, title?: string, icon?: string) => string>(),
+  setActiveTab: vi.fn<(tabId: string) => void>(),
+  switchWorkspace: vi.fn<(slug: string, openPath?: string) => void>(),
+}));
+
+vi.mock("@/stores/tab-store", () => {
+  const store = {
+    get activeWorkspaceSlug() {
+      return state.activeWorkspaceSlug;
+    },
+    get byWorkspace() {
+      return state.byWorkspace;
+    },
+    openTab: state.openTab,
+    setActiveTab: state.setActiveTab,
+    switchWorkspace: state.switchWorkspace,
+  };
+  const useTabStore = Object.assign(
+    (selector?: (s: typeof store) => unknown) =>
+      selector ? selector(store) : store,
+    { getState: () => store },
+  );
+  const getActiveTab = () => {
+    const slug = state.activeWorkspaceSlug;
+    if (!slug) return null;
+    const group = state.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,
+  });
+  const useActiveTabRouter = () => null;
+  const resolveRouteIcon = () => "File";
+  return {
+    useTabStore,
+    getActiveTab,
+    useActiveTabIdentity,
+    useActiveTabRouter,
+    resolveRouteIcon,
+  };
+});
+
+vi.mock("@/stores/window-overlay-store", () => ({
+  useWindowOverlayStore: Object.assign(
+    () => null,
+    { getState: () => ({ overlay: null, open: vi.fn(), close: vi.fn() }) },
+  ),
+}));
+
+vi.mock("@multica/core/auth", () => ({
+  useAuthStore: Object.assign(
+    () => null,
+    { getState: () => ({ logout: vi.fn() }) },
+  ),
+}));
+
+vi.mock("@multica/core/paths", () => ({
+  isReservedSlug: (s: string) =>
+    ["login", "workspaces", "invite", "onboarding", "invitations"].includes(s),
+}));
+
+// DesktopNavigationProvider reads window.desktopAPI.runtimeConfig synchronously.
+beforeEach(() => {
+  state.openTab.mockReset();
+  state.setActiveTab.mockReset();
+  state.switchWorkspace.mockReset();
+  state.openTab.mockImplementation(() => "tNew");
+  state.activeWorkspaceSlug = "acme";
+  state.byWorkspace = {
+    acme: {
+      activeTabId: "tA",
+      tabs: [
+        {
+          id: "tA",
+          path: "/acme/issues",
+          pinned: false,
+          router: makeMockRouter("/acme/issues"),
+        },
+      ],
+    },
+  };
+  Object.defineProperty(window, "desktopAPI", {
+    configurable: true,
+    value: {
+      runtimeConfig: { ok: true, config: { appUrl: "https://app.example" } },
+    },
+  });
+});
+
+import {
+  DesktopNavigationProvider,
+  TabNavigationProvider,
+} from "./navigation";
+import { useNavigation } from "@multica/views/navigation";
+
+function captureAdapter(onAdapter: (adapter: ReturnType<typeof useNavigation>) => void) {
+  function Probe() {
+    const nav = useNavigation();
+    useEffect(() => {
+      onAdapter(nav);
+    }, [nav]);
+    return null;
+  }
+  return Probe;
+}
+
+describe("DesktopNavigationProvider.openInNewTab", () => {
+  it("opens a background tab (no setActiveTab) for a same-workspace path", () => {
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    render(
+      <DesktopNavigationProvider>
+        <Probe />
+      </DesktopNavigationProvider>,
+    );
+    expect(adapter).not.toBeNull();
+    adapter!.openInNewTab!("/acme/agents", "Agents");
+    expect(state.openTab).toHaveBeenCalledWith("/acme/agents", "Agents", "File");
+    expect(state.setActiveTab).not.toHaveBeenCalled();
+    expect(state.switchWorkspace).not.toHaveBeenCalled();
+  });
+
+  it("activates the new tab when opts.activate is true (foreground)", () => {
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    render(
+      <DesktopNavigationProvider>
+        <Probe />
+      </DesktopNavigationProvider>,
+    );
+    adapter!.openInNewTab!("/acme/agents", "Agents", { activate: true });
+    expect(state.openTab).toHaveBeenCalledWith("/acme/agents", "Agents", "File");
+    expect(state.setActiveTab).toHaveBeenCalledWith("tNew");
+    expect(state.switchWorkspace).not.toHaveBeenCalled();
+  });
+
+  it("delegates to switchWorkspace for a cross-workspace path", () => {
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    render(
+      <DesktopNavigationProvider>
+        <Probe />
+      </DesktopNavigationProvider>,
+    );
+    adapter!.openInNewTab!("/butter/inbox");
+    expect(state.switchWorkspace).toHaveBeenCalledWith("butter", "/butter/inbox");
+    expect(state.openTab).not.toHaveBeenCalled();
+    expect(state.setActiveTab).not.toHaveBeenCalled();
+  });
+});
+
+describe("DesktopNavigationProvider.push with pinned active tab", () => {
+  function pinActive(pathname: string) {
+    state.byWorkspace.acme.tabs[0] = {
+      id: "tA",
+      path: pathname,
+      pinned: true,
+      router: makeMockRouter(pathname),
+    };
+  }
+
+  it("redirects push to a new foreground tab when pathname differs", () => {
+    pinActive("/acme/issues");
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    render(
+      <DesktopNavigationProvider>
+        <Probe />
+      </DesktopNavigationProvider>,
+    );
+    adapter!.push("/acme/projects");
+    expect(state.openTab).toHaveBeenCalledWith("/acme/projects", "/acme/projects", "File");
+    expect(state.setActiveTab).toHaveBeenCalledWith("tNew");
+  });
+
+  it("allows in-tab navigation when only search/hash changes", () => {
+    pinActive("/acme/issues");
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    render(
+      <DesktopNavigationProvider>
+        <Probe />
+      </DesktopNavigationProvider>,
+    );
+    adapter!.push("/acme/issues?filter=open");
+    // Pathname unchanged → pinned interception declines and falls through to
+    // the router's own navigate — openTab / setActiveTab must not fire.
+    expect(state.openTab).not.toHaveBeenCalled();
+    expect(state.setActiveTab).not.toHaveBeenCalled();
+  });
+
+  it("leaves cross-workspace push to the workspace switcher (not pin)", () => {
+    pinActive("/acme/issues");
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    render(
+      <DesktopNavigationProvider>
+        <Probe />
+      </DesktopNavigationProvider>,
+    );
+    adapter!.push("/butter/inbox");
+    // Cross-workspace push runs through tryRouteToOtherWorkspace before
+    // tryRouteToPinnedNewTab, so switchWorkspace wins.
+    expect(state.switchWorkspace).toHaveBeenCalledWith("butter", "/butter/inbox");
+    expect(state.openTab).not.toHaveBeenCalled();
+  });
+});
+
+describe("DesktopNavigationProvider.push duplicate path guard", () => {
+  it("does not navigate when the target exactly matches the active tab location", () => {
+    const activeRouter = makeMockRouter("/acme/issues/child");
+    state.byWorkspace.acme.tabs[0] = {
+      id: "tA",
+      path: "/acme/issues/child",
+      pinned: false,
+      router: activeRouter,
+    };
+
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    render(
+      <DesktopNavigationProvider>
+        <Probe />
+      </DesktopNavigationProvider>,
+    );
+
+    adapter!.push("/acme/issues/child");
+
+    expect(activeRouter.navigate).not.toHaveBeenCalled();
+  });
+});
+
+describe("TabNavigationProvider.openInNewTab", () => {
+  function renderTabProvider() {
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    const fakeRouter = {
+      state: { location: { pathname: "/acme/issues", search: "" } },
+      subscribe: () => () => {},
+      navigate: vi.fn(),
+    } as unknown as Parameters<typeof TabNavigationProvider>[0]["router"];
+    render(
+      <TabNavigationProvider router={fakeRouter}>
+        <Probe />
+      </TabNavigationProvider>,
+    );
+    return () => adapter!;
+  }
+
+  it("opens a background tab (no setActiveTab) for a same-workspace path", () => {
+    const getAdapter = renderTabProvider();
+    getAdapter().openInNewTab!("/acme/agents", "Agents");
+    expect(state.openTab).toHaveBeenCalledWith("/acme/agents", "Agents", "File");
+    expect(state.setActiveTab).not.toHaveBeenCalled();
+    expect(state.switchWorkspace).not.toHaveBeenCalled();
+  });
+
+  it("activates the new tab when opts.activate is true (foreground)", () => {
+    const getAdapter = renderTabProvider();
+    getAdapter().openInNewTab!("/acme/agents", "Agents", { activate: true });
+    expect(state.openTab).toHaveBeenCalledWith("/acme/agents", "Agents", "File");
+    expect(state.setActiveTab).toHaveBeenCalledWith("tNew");
+    expect(state.switchWorkspace).not.toHaveBeenCalled();
+  });
+});
+
+describe("TabNavigationProvider.push duplicate path guard", () => {
+  function renderTabProviderAt(
+    pathname: string,
+    search = "",
+    hash = "",
+  ) {
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    const fakeRouter = {
+      state: { location: { pathname, search, hash } },
+      subscribe: () => () => {},
+      navigate: vi.fn(),
+    } as unknown as Parameters<typeof TabNavigationProvider>[0]["router"];
+    render(
+      <TabNavigationProvider router={fakeRouter}>
+        <Probe />
+      </TabNavigationProvider>,
+    );
+    return { getAdapter: () => adapter!, fakeRouter };
+  }
+
+  it("does not navigate when the target exactly matches the current full location", () => {
+    const { getAdapter, fakeRouter } = renderTabProviderAt("/acme/issues/child");
+
+    getAdapter().push("/acme/issues/child");
+
+    expect(fakeRouter.navigate).not.toHaveBeenCalled();
+  });
+
+  it("still navigates when only search or hash differs", () => {
+    const { getAdapter, fakeRouter } = renderTabProviderAt("/acme/issues");
+
+    getAdapter().push("/acme/issues?filter=open#top");
+
+    expect(fakeRouter.navigate).toHaveBeenCalledWith("/acme/issues?filter=open#top");
+  });
+});
+
+describe("TabNavigationProvider.push with pinned active tab", () => {
+  type ProviderRouter = Parameters<typeof TabNavigationProvider>[0]["router"];
+
+  function renderPinnedTabProvider(pathname: string) {
+    // The active tab and the per-tab router must share the same pathname:
+    // tryRouteToPinnedNewTab reads the *active tab's* router for the current
+    // pathname (so query-only pushes routed via React Router still compare
+    // correctly), while the TabNavigationProvider falls back to *its own*
+    // router.navigate when no interception fires. In real desktop usage they
+    // are the same router instance; this helper mirrors that invariant.
+    const fakeRouter = {
+      state: { location: { pathname, search: "", hash: "" } },
+      subscribe: () => () => {},
+      navigate: vi.fn(),
+    } as unknown as ProviderRouter;
+    state.byWorkspace.acme.tabs[0] = {
+      id: "tA",
+      path: pathname,
+      pinned: true,
+      router: fakeRouter as unknown as MockRouter,
+    };
+
+    let adapter: ReturnType<typeof useNavigation> | null = null;
+    const Probe = captureAdapter((a) => {
+      adapter = a;
+    });
+    render(
+      <TabNavigationProvider router={fakeRouter}>
+        <Probe />
+      </TabNavigationProvider>,
+    );
+    return { getAdapter: () => adapter!, fakeRouter };
+  }
+
+  it("redirects push to a new foreground tab when pathname differs", () => {
+    const { getAdapter, fakeRouter } = renderPinnedTabProvider("/acme/issues");
+    getAdapter().push("/acme/projects");
+    expect(state.openTab).toHaveBeenCalledWith("/acme/projects", "/acme/projects", "File");
+    expect(state.setActiveTab).toHaveBeenCalledWith("tNew");
+    // Pinned interception short-circuits — the per-tab router must NOT
+    // navigate, otherwise the pinned tab itself would move off its path.
+    expect(fakeRouter.navigate).not.toHaveBeenCalled();
+  });
+
+  it("allows in-tab navigation when only search/hash changes", () => {
+    const { getAdapter, fakeRouter } = renderPinnedTabProvider("/acme/issues");
+    getAdapter().push("/acme/issues?filter=open");
+    // Same pathname → pinned interception declines, push falls through to
+    // the tab's own router.navigate, and no new tab is opened.
+    expect(state.openTab).not.toHaveBeenCalled();
+    expect(state.setActiveTab).not.toHaveBeenCalled();
+    expect(fakeRouter.navigate).toHaveBeenCalledWith("/acme/issues?filter=open");
+  });
+});

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

@@ -89,6 +89,11 @@ function tryRouteToOverlay(path: string, router?: DataRouter): boolean {
   return false;
 }
 
+function routerLocationPath(router: DataRouter): string {
+  const { pathname, search, hash } = router.state.location;
+  return `${pathname}${search ?? ""}${hash ?? ""}`;
+}
+
 /**
  * Intercept pushes that change workspace. Returns `true` if the navigation
  * was delegated to the tab store (caller should NOT proceed).
@@ -108,6 +113,37 @@ function tryRouteToOtherWorkspace(path: string): boolean {
   return true;
 }
 
+/**
+ * Intercept pushes originating in a pinned tab and force them into a new
+ * tab. Returns `true` if the navigation was redirected (caller should NOT
+ * proceed). Pathname-only changes (search / hash / same-page state) are
+ * allowed through so pinned filter / drawer / form-state interactions
+ * still work — see RFC §3 D2a (FINAL: any pathname change → new tab) and
+ * D2b (FINAL: same pathname → allowed in pinned tab).
+ *
+ * Dedupe is preserved (D4a): `openTab` activates an existing same-path tab
+ * if one exists, otherwise creates a new one. The newly-focused tab is
+ * activated foreground — a pinned-tab push is an explicit user action, not
+ * a background cmd+click, so the focus follows.
+ */
+function tryRouteToPinnedNewTab(path: string): boolean {
+  const store = useTabStore.getState();
+  const active = getActiveTab(store);
+  if (!active?.pinned) return false;
+
+  // Use the live router pathname rather than `active.path` so query-only
+  // navigations performed via React Router (which only sync pathname back
+  // to the store) still compare correctly.
+  const currentPathname = active.router.state.location.pathname;
+  const newPathname = path.split("?")[0].split("#")[0];
+  if (currentPathname === newPathname) return false;
+
+  const icon = resolveRouteIcon(path);
+  const newId = store.openTab(path, path, icon);
+  if (newId) store.setActiveTab(newId);
+  return true;
+}
+
 /**
  * Root-level navigation provider for components outside the per-tab
  * RouterProviders (sidebar, search dialog, modals, WindowOverlay contents).
@@ -164,7 +200,9 @@ export function DesktopNavigationProvider({
         }
         const active = currentActiveTab();
         if (tryRouteToOverlay(path, active?.router)) return;
+        if (active && routerLocationPath(active.router) === path) return;
         if (tryRouteToOtherWorkspace(path)) return;
+        if (tryRouteToPinnedNewTab(path)) return;
         active?.router.navigate(path);
       },
       replace: (path: string) => {
@@ -178,9 +216,16 @@ export function DesktopNavigationProvider({
       },
       pathname: location.pathname,
       searchParams: new URLSearchParams(location.search),
-      openInNewTab: (path: string, title?: string) => {
+      openInNewTab: (
+        path: string,
+        title?: string,
+        opts?: { activate?: boolean },
+      ) => {
         // Cross-workspace "open in new tab" switches workspace and opens
-        // the path there; same-workspace just adds a tab in the current group.
+        // the path there (focus follows the user); same-workspace defaults
+        // to background tab (browser cmd+click semantics). Callers that
+        // represent an explicit "Open in new tab" CTA pass `activate: true`
+        // to bring the new tab to the foreground.
         const slug = extractWorkspaceSlug(path);
         const store = useTabStore.getState();
         if (slug && slug !== store.activeWorkspaceSlug) {
@@ -188,8 +233,10 @@ export function DesktopNavigationProvider({
           return;
         }
         const icon = resolveRouteIcon(path);
-        const tabId = store.openTab(path, title ?? path, icon);
-        if (tabId) store.setActiveTab(tabId);
+        const newId = store.openTab(path, title ?? path, icon);
+        if (opts?.activate && newId) {
+          store.setActiveTab(newId);
+        }
       },
       getShareableUrl: (path: string) => `${appUrl}${path}`,
     }),
@@ -230,7 +277,9 @@ export function TabNavigationProvider({
     () => ({
       push: (path: string) => {
         if (tryRouteToOverlay(path, router)) return;
+        if (routerLocationPath(router) === path) return;
         if (tryRouteToOtherWorkspace(path)) return;
+        if (tryRouteToPinnedNewTab(path)) return;
         router.navigate(path);
       },
       replace: (path: string) => {
@@ -241,7 +290,11 @@ export function TabNavigationProvider({
       back: () => router.navigate(-1),
       pathname: location.pathname,
       searchParams: new URLSearchParams(location.search),
-      openInNewTab: (path: string, title?: string) => {
+      openInNewTab: (
+        path: string,
+        title?: string,
+        opts?: { activate?: boolean },
+      ) => {
         const slug = extractWorkspaceSlug(path);
         const store = useTabStore.getState();
         if (slug && slug !== store.activeWorkspaceSlug) {
@@ -249,8 +302,10 @@ export function TabNavigationProvider({
           return;
         }
         const icon = resolveRouteIcon(path);
-        const tabId = store.openTab(path, title ?? path, icon);
-        if (tabId) store.setActiveTab(tabId);
+        const newId = store.openTab(path, title ?? path, icon);
+        if (opts?.activate && newId) {
+          store.setActiveTab(newId);
+        }
       },
       getShareableUrl: (path: string) => `${appUrl}${path}`,
     }),

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

@@ -13,6 +13,7 @@ import { SkillDetailPage } from "./pages/skill-detail-page";
 import { AgentDetailPage } from "./pages/agent-detail-page";
 import { MemberDetailPage } from "./pages/member-detail-page";
 import { RuntimeDetailPage } from "./pages/runtime-detail-page";
+import { AttachmentPreviewRoute } from "./pages/attachment-preview-page";
 import { IssuesPage } from "@multica/views/issues/components";
 import { ProjectsPage } from "@multica/views/projects/components";
 import { DashboardPage } from "@multica/views/dashboard";
@@ -20,16 +21,44 @@ import { AutopilotsPage } from "@multica/views/autopilots/components";
 import { MyIssuesPage } from "@multica/views/my-issues";
 import { SkillsPage } from "@multica/views/skills";
 import { DesktopRuntimesPage } from "./components/desktop-runtimes-page";
-import { AgentsPage } from "@multica/views/agents";
+import { DesktopAgentsPage } from "./components/desktop-agents-page";
 import { SquadsPage, SquadDetailPage as SquadDetailPageView } from "@multica/views/squads/components";
 import { InboxPage } from "@multica/views/inbox";
 import { SettingsPage } from "@multica/views/settings";
+import { useT } from "@multica/views/i18n";
 import { ErrorBoundary } from "@multica/ui/components/common/error-boundary";
 import { Download, Server } from "lucide-react";
 import { DaemonSettingsTab } from "./components/daemon-settings-tab";
 import { UpdatesSettingsTab } from "./components/updates-settings-tab";
 import { WorkspaceRouteLayout } from "./components/workspace-route-layout";
 
+/**
+ * Wraps `SettingsPage` so the desktop-only extra tabs can pull their labels
+ * from i18n. The route element has to be a component (not a literal JSX
+ * value) for `useT` to run.
+ */
+function DesktopSettingsRoute() {
+  const { t } = useT("settings");
+  return (
+    <SettingsPage
+      extraAccountTabs={[
+        {
+          value: "daemon",
+          label: "Daemon",
+          icon: Server,
+          content: <DaemonSettingsTab />,
+        },
+        {
+          value: "updates",
+          label: t(($) => $.desktop.tabs.updates),
+          icon: Download,
+          content: <UpdatesSettingsTab />,
+        },
+      ]}
+    />
+  );
+}
+
 /**
  * Sets document.title from the deepest matched route's handle.title.
  * The tab system observes document.title via MutationObserver.
@@ -142,7 +171,7 @@ export const appRoutes: RouteObject[] = [
             element: <SkillDetailPage />,
             handle: { title: "Skill" },
           },
-          { path: "agents", element: <AgentsPage />, handle: { title: "Agents" } },
+          { path: "agents", element: <DesktopAgentsPage />, handle: { title: "Agents" } },
           {
             path: "agents/:id",
             element: <AgentDetailPage />,
@@ -160,6 +189,11 @@ export const appRoutes: RouteObject[] = [
             handle: { title: "Squad" },
           },
           { path: "inbox", element: <InboxPage />, handle: { title: "Inbox" } },
+          {
+            path: "attachments/:id/preview",
+            element: <AttachmentPreviewRoute />,
+            handle: { title: "Attachment" },
+          },
           {
             path: "usage",
             element: <DashboardPage />,
@@ -167,24 +201,7 @@ export const appRoutes: RouteObject[] = [
           },
           {
             path: "settings",
-            element: (
-              <SettingsPage
-                extraAccountTabs={[
-                  {
-                    value: "daemon",
-                    label: "Daemon",
-                    icon: Server,
-                    content: <DaemonSettingsTab />,
-                  },
-                  {
-                    value: "updates",
-                    label: "Updates",
-                    icon: Download,
-                    content: <UpdatesSettingsTab />,
-                  },
-                ]}
-              />
-            ),
+            element: <DesktopSettingsRoute />,
             handle: { title: "Settings" },
           },
         ],

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

@@ -17,6 +17,7 @@ vi.mock("../routes", () => ({
 import {
   sanitizeTabPath,
   migrateV1ToV2,
+  migrateV2ToV3,
   useTabStore,
 } from "./tab-store";
 
@@ -277,3 +278,155 @@ describe("useTabStore actions", () => {
     expect(useTabStore.getState().activeWorkspaceSlug).toBe("acme");
   });
 });
+
+describe("togglePin", () => {
+  it("flips a tab's pinned state", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    const tabId = useTabStore.getState().byWorkspace.acme.tabs[0].id;
+    expect(useTabStore.getState().byWorkspace.acme.tabs[0].pinned).toBe(false);
+
+    store.togglePin(tabId);
+    expect(useTabStore.getState().byWorkspace.acme.tabs[0].pinned).toBe(true);
+
+    store.togglePin(tabId);
+    expect(useTabStore.getState().byWorkspace.acme.tabs[0].pinned).toBe(false);
+  });
+
+  it("moves a newly-pinned tab to the start of the pinned zone", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme"); // creates default unpinned tab at index 0
+    store.addTab("/acme/projects", "Projects", "FolderKanban");
+    store.addTab("/acme/agents", "Agents", "Bot");
+    const agentsId = useTabStore.getState().byWorkspace.acme.tabs[2].id;
+
+    store.togglePin(agentsId);
+    const tabs = useTabStore.getState().byWorkspace.acme.tabs;
+    expect(tabs[0].id).toBe(agentsId);
+    expect(tabs[0].pinned).toBe(true);
+    expect(tabs[1].pinned).toBe(false);
+    expect(tabs[2].pinned).toBe(false);
+  });
+
+  it("appends a second pinned tab after the first pinned tab", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.addTab("/acme/projects", "Projects", "FolderKanban");
+    store.addTab("/acme/agents", "Agents", "Bot");
+    const projectsId = useTabStore.getState().byWorkspace.acme.tabs[1].id;
+    const agentsId = useTabStore.getState().byWorkspace.acme.tabs[2].id;
+
+    store.togglePin(agentsId);
+    store.togglePin(projectsId);
+
+    // Both pinned, in the order they were pinned (agents first, projects
+    // second), then the unpinned default tab.
+    const tabs = useTabStore.getState().byWorkspace.acme.tabs;
+    expect(tabs.map((t) => t.id)).toEqual([
+      agentsId,
+      projectsId,
+      tabs[2].id,
+    ]);
+    expect(tabs.map((t) => t.pinned)).toEqual([true, true, false]);
+  });
+
+  it("returns an unpinned tab to the start of the unpinned zone", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.addTab("/acme/projects", "Projects", "FolderKanban");
+    const issuesId = useTabStore.getState().byWorkspace.acme.tabs[0].id;
+    const projectsId = useTabStore.getState().byWorkspace.acme.tabs[1].id;
+
+    // Pin both, then unpin one.
+    store.togglePin(issuesId);
+    store.togglePin(projectsId);
+    store.togglePin(issuesId);
+
+    const tabs = useTabStore.getState().byWorkspace.acme.tabs;
+    expect(tabs.map((t) => t.id)).toEqual([projectsId, issuesId]);
+    expect(tabs.map((t) => t.pinned)).toEqual([true, false]);
+  });
+});
+
+describe("moveTab boundary clamp", () => {
+  it("clamps a pinned-tab move so it never crosses into the unpinned zone", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.addTab("/acme/projects", "Projects", "FolderKanban");
+    store.addTab("/acme/agents", "Agents", "Bot");
+    const issuesId = useTabStore.getState().byWorkspace.acme.tabs[0].id;
+
+    store.togglePin(issuesId); // [issues(pinned), projects, agents]
+
+    // User tries to drag the pinned tab to index 2 (unpinned zone end).
+    store.moveTab(0, 2);
+    const tabs = useTabStore.getState().byWorkspace.acme.tabs;
+    // It should be clamped to index 0 — the only pinned slot — i.e. unchanged.
+    expect(tabs[0].id).toBe(issuesId);
+    expect(tabs.map((t) => t.pinned)).toEqual([true, false, false]);
+  });
+
+  it("clamps an unpinned-tab move so it never crosses into the pinned zone", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.addTab("/acme/projects", "Projects", "FolderKanban");
+    store.addTab("/acme/agents", "Agents", "Bot");
+    const issuesId = useTabStore.getState().byWorkspace.acme.tabs[0].id;
+    const agentsId = useTabStore.getState().byWorkspace.acme.tabs[2].id;
+
+    store.togglePin(issuesId); // [issues(pinned), projects, agents]
+
+    // User tries to drag agents (index 2) to index 0 (pinned zone).
+    store.moveTab(2, 0);
+    const tabs = useTabStore.getState().byWorkspace.acme.tabs;
+    // Clamped to index 1 — start of the unpinned zone.
+    expect(tabs[0].id).toBe(issuesId);
+    expect(tabs[1].id).toBe(agentsId);
+    expect(tabs.map((t) => t.pinned)).toEqual([true, false, false]);
+  });
+
+  it("reorders freely within the same zone", () => {
+    const store = useTabStore.getState();
+    store.switchWorkspace("acme");
+    store.addTab("/acme/projects", "Projects", "FolderKanban");
+    store.addTab("/acme/agents", "Agents", "Bot");
+
+    // All unpinned; move agents (2) to position 0.
+    store.moveTab(2, 0);
+    const tabs = useTabStore.getState().byWorkspace.acme.tabs;
+    expect(tabs.map((t) => t.path)).toEqual([
+      "/acme/agents",
+      "/acme/issues",
+      "/acme/projects",
+    ]);
+  });
+});
+
+describe("migrateV2ToV3", () => {
+  it("adds pinned=false to every persisted tab", () => {
+    const v2 = {
+      activeWorkspaceSlug: "acme",
+      byWorkspace: {
+        acme: {
+          activeTabId: "t1",
+          tabs: [
+            { id: "t1", path: "/acme/issues", title: "Issues", icon: "ListTodo" },
+            { id: "t2", path: "/acme/projects", title: "Projects", icon: "FolderKanban" },
+          ],
+        },
+      },
+    };
+    const v3 = migrateV2ToV3(v2);
+    expect(v3.activeWorkspaceSlug).toBe("acme");
+    expect(v3.byWorkspace.acme.tabs).toEqual([
+      { id: "t1", path: "/acme/issues", title: "Issues", icon: "ListTodo", pinned: false },
+      { id: "t2", path: "/acme/projects", title: "Projects", icon: "FolderKanban", pinned: false },
+    ]);
+  });
+
+  it("handles missing byWorkspace gracefully", () => {
+    const v3 = migrateV2ToV3({ activeWorkspaceSlug: null } as Parameters<typeof migrateV2ToV3>[0]);
+    expect(v3.byWorkspace).toEqual({});
+    expect(v3.activeWorkspaceSlug).toBeNull();
+  });
+});

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

@@ -20,6 +20,14 @@ export interface Tab {
   router: DataRouter;
   historyIndex: number;
   historyLength: number;
+  /**
+   * Pinned tabs render at the left of the tab bar as icon-only, suppress the
+   * X close button, and turn any `navigation.push()` originating in them into
+   * an `openInNewTab()` so they stay parked on their original path. Pinning
+   * is invariant-preserving: pinned tabs always come before unpinned tabs in
+   * a workspace's `tabs` array; `togglePin` / `moveTab` enforce this.
+   */
+  pinned: boolean;
 }
 
 export interface WorkspaceTabGroup {
@@ -78,8 +86,20 @@ interface TabStore {
   updateTab: (tabId: string, patch: Partial<Pick<Tab, "path" | "title" | "icon">>) => void;
   /** Patch history tracking of a tab. Finds across groups. */
   updateTabHistory: (tabId: string, historyIndex: number, historyLength: number) => void;
-  /** Reorder within the active workspace's group only. */
+  /**
+   * Reorder within the active workspace's group only. Clamped so a tab can
+   * never cross the pinned / unpinned boundary — a drag that would move a
+   * pinned tab into the unpinned zone (or vice versa) is dropped at the
+   * boundary instead. This keeps the "pinned tabs first" invariant without
+   * requiring callers to know about it.
+   */
   moveTab: (fromIndex: number, toIndex: number) => void;
+  /**
+   * Flip a tab's pinned state. Pinning moves it to the end of the pinned
+   * zone; unpinning moves it to the start of the unpinned zone. Both
+   * preserve the "pinned tabs before unpinned tabs" invariant.
+   */
+  togglePin: (tabId: string) => void;
   /**
    * After the workspace list arrives/changes (login, realtime delete), drop
    * any tab group whose slug is no longer in `validSlugs`, and repoint
@@ -190,9 +210,17 @@ function makeTab(path: string, title: string, icon: string): Tab {
     router: createTabRouter(path),
     historyIndex: 0,
     historyLength: 1,
+    pinned: false,
   };
 }
 
+/** Index of the first unpinned tab in a group (== pinned count). */
+function pinnedBoundary(tabs: Tab[]): number {
+  let i = 0;
+  while (i < tabs.length && tabs[i].pinned) i++;
+  return i;
+}
+
 /** Default entry point for a workspace — its issues list. */
 function defaultPathFor(slug: string): string {
   return `/${slug}/issues`;
@@ -453,17 +481,63 @@ export const useTabStore = create<TabStore>()(
         if (!activeWorkspaceSlug) return;
         const group = byWorkspace[activeWorkspaceSlug];
         if (!group) return;
+        if (fromIndex < 0 || fromIndex >= group.tabs.length) return;
+
+        // Clamp the drop position to within the source tab's group (pinned vs
+        // unpinned) so the "pinned tabs first" invariant survives drag-reorder.
+        // Pinned zone is [0, boundary); unpinned zone is [boundary, length).
+        const boundary = pinnedBoundary(group.tabs);
+        const source = group.tabs[fromIndex];
+        let clampedTo: number;
+        if (source.pinned) {
+          // boundary is exclusive upper bound for pinned-zone indices.
+          clampedTo = Math.max(0, Math.min(toIndex, boundary - 1));
+        } else {
+          clampedTo = Math.max(boundary, Math.min(toIndex, group.tabs.length - 1));
+        }
+        if (clampedTo === fromIndex) return;
         set({
           byWorkspace: {
             ...byWorkspace,
             [activeWorkspaceSlug]: {
               ...group,
-              tabs: arrayMove(group.tabs, fromIndex, toIndex),
+              tabs: arrayMove(group.tabs, fromIndex, clampedTo),
             },
           },
         });
       },
 
+      togglePin(tabId) {
+        const { byWorkspace } = get();
+        const hit = findTabLocation(byWorkspace, tabId);
+        if (!hit) return;
+        const { slug, group, index } = hit;
+        const current = group.tabs[index];
+        const nextTab: Tab = { ...current, pinned: !current.pinned };
+
+        // Remove from current position, then insert at the new zone boundary:
+        //   pinning   → end of pinned zone (just before first unpinned tab)
+        //   unpinning → start of unpinned zone (right after last pinned tab)
+        const withoutCurrent = [
+          ...group.tabs.slice(0, index),
+          ...group.tabs.slice(index + 1),
+        ];
+        const newBoundary = pinnedBoundary(withoutCurrent);
+        const insertAt = newBoundary;
+        const nextTabs = [
+          ...withoutCurrent.slice(0, insertAt),
+          nextTab,
+          ...withoutCurrent.slice(insertAt),
+        ];
+
+        set({
+          byWorkspace: {
+            ...byWorkspace,
+            [slug]: { ...group, tabs: nextTabs },
+          },
+        });
+      },
+
       validateWorkspaceSlugs(validSlugs) {
         const { activeWorkspaceSlug, byWorkspace } = get();
         let changed = false;
@@ -497,17 +571,23 @@ export const useTabStore = create<TabStore>()(
     }),
     {
       name: "multica_tabs",
-      version: 2,
+      version: 3,
       storage: createJSONStorage(() => createPersistStorage(defaultStorage)),
       migrate: (persistedState, version) => {
         // v1 → v2: flat `tabs` array → per-workspace grouping.
         // Tabs whose path isn't workspace-scoped (root `/`, login, etc.)
         // are dropped — they have no workspace to belong to, and the new
         // model's invariant is "every tab lives in a workspace group".
-        if (version < 2 && persistedState && typeof persistedState === "object") {
-          return migrateV1ToV2(persistedState as Partial<V1Persisted>);
+        let state = persistedState;
+        if (version < 2 && state && typeof state === "object") {
+          state = migrateV1ToV2(state as Partial<V1Persisted>);
         }
-        return persistedState as V2Persisted;
+        // v2 → v3: introduce `Tab.pinned`. Existing tabs default to
+        // unpinned; pin ordering invariant trivially holds (no pinned tabs).
+        if (version < 3 && state && typeof state === "object") {
+          state = migrateV2ToV3(state as V2Persisted);
+        }
+        return state as V3Persisted;
       },
       partialize: (state) => ({
         activeWorkspaceSlug: state.activeWorkspaceSlug,
@@ -517,15 +597,19 @@ export const useTabStore = create<TabStore>()(
             {
               activeTabId: group.activeTabId,
               tabs: group.tabs.map(
-                ({ router: _router, historyIndex: _hi, historyLength: _hl, ...rest }) =>
-                  rest,
+                ({
+                  router: _router,
+                  historyIndex: _hi,
+                  historyLength: _hl,
+                  ...rest
+                }) => rest,
               ),
             },
           ]),
         ),
       }),
       merge: (persistedState, currentState) => {
-        const persisted = persistedState as Partial<V2Persisted> | undefined;
+        const persisted = persistedState as Partial<V3Persisted> | undefined;
         if (!persisted?.byWorkspace) return currentState;
 
         const byWorkspace: Record<string, WorkspaceTabGroup> = {};
@@ -552,9 +636,14 @@ export const useTabStore = create<TabStore>()(
               router: createTabRouter(clean),
               historyIndex: 0,
               historyLength: 1,
+              pinned: pTab.pinned === true,
             });
           }
           if (tabs.length === 0) continue;
+          // Enforce the "pinned first" invariant on rehydration in case a
+          // user (or a buggy older write) persisted the pinned tabs out of
+          // order. Stable sort preserves intra-group order.
+          tabs.sort((a, b) => (a.pinned === b.pinned ? 0 : a.pinned ? -1 : 1));
           const activeTabId = tabs.some((t) => t.id === pGroup.activeTabId)
             ? pGroup.activeTabId
             : tabs[0].id;
@@ -605,6 +694,38 @@ interface V2Persisted {
   byWorkspace: Record<string, V2PersistedGroup>;
 }
 
+interface V3PersistedTab {
+  id: string;
+  path: string;
+  title: string;
+  icon: string;
+  pinned: boolean;
+}
+
+interface V3PersistedGroup {
+  tabs: V3PersistedTab[];
+  activeTabId: string;
+}
+
+interface V3Persisted {
+  activeWorkspaceSlug: string | null;
+  byWorkspace: Record<string, V3PersistedGroup>;
+}
+
+export function migrateV2ToV3(v2: V2Persisted): V3Persisted {
+  const byWorkspace: Record<string, V3PersistedGroup> = {};
+  for (const [slug, group] of Object.entries(v2.byWorkspace ?? {})) {
+    byWorkspace[slug] = {
+      activeTabId: group.activeTabId,
+      tabs: group.tabs.map((t) => ({ ...t, pinned: false })),
+    };
+  }
+  return {
+    activeWorkspaceSlug: v2.activeWorkspaceSlug ?? null,
+    byWorkspace,
+  };
+}
+
 export function migrateV1ToV2(v1: Partial<V1Persisted>): V2Persisted {
   const byWorkspace: Record<string, V2PersistedGroup> = {};
   const oldTabs = v1.tabs ?? [];

apps/desktop/src/shared/navigation-gestures.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import {
+  isNavigationGesture,
+  navigationGestureFromSwipe,
+} from "./navigation-gestures";
+
+describe("navigationGestureFromSwipe", () => {
+  it("maps horizontal macOS swipe directions to browser-style history", () => {
+    expect(navigationGestureFromSwipe("right")).toBe("back");
+    expect(navigationGestureFromSwipe("left")).toBe("forward");
+  });
+
+  it("ignores vertical and unknown directions", () => {
+    expect(navigationGestureFromSwipe("up")).toBeNull();
+    expect(navigationGestureFromSwipe("down")).toBeNull();
+    expect(navigationGestureFromSwipe("sideways")).toBeNull();
+  });
+});
+
+describe("isNavigationGesture", () => {
+  it("accepts only the renderer navigation gestures", () => {
+    expect(isNavigationGesture("back")).toBe(true);
+    expect(isNavigationGesture("forward")).toBe(true);
+    expect(isNavigationGesture("right")).toBe(false);
+    expect(isNavigationGesture(null)).toBe(false);
+  });
+});

apps/desktop/src/shared/navigation-gestures.ts

@@ -0,0 +1,15 @@
+export const NAVIGATION_GESTURE_CHANNEL = "navigation:gesture";
+
+export type NavigationGesture = "back" | "forward";
+
+export function isNavigationGesture(value: unknown): value is NavigationGesture {
+  return value === "back" || value === "forward";
+}
+
+export function navigationGestureFromSwipe(
+  direction: string,
+): NavigationGesture | null {
+  if (direction === "right") return "back";
+  if (direction === "left") return "forward";
+  return null;
+}

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

@@ -11,6 +11,7 @@ import type { Metadata } from "next";
 import { docsAlternates } from "@/lib/site";
 import { i18n, type Lang } from "@/lib/i18n";
 import { DocsLocaleProvider, LocaleLink } from "@/components/locale-link";
+import { docsSlugStaticParams } from "@/lib/static-params";
 
 function asLang(lang: string): Lang {
   return (i18n.languages as readonly string[]).includes(lang)
@@ -22,11 +23,11 @@ export default async function Page(props: {
   params: Promise<{ lang: string; slug: string[] }>;
 }) {
   const params = await props.params;
-  const page = source.getPage(params.slug, params.lang);
+  const lang = asLang(params.lang);
+  const page = source.getPage(params.slug, lang);
   if (!page) notFound();
 
   const MDX = page.data.body;
-  const lang = asLang(params.lang);
 
   return (
     <DocsPage toc={page.data.toc}>
@@ -42,14 +43,15 @@ export default async function Page(props: {
 }
 
 export function generateStaticParams() {
-  return source.generateParams().filter((p) => p.slug.length > 0);
+  return docsSlugStaticParams(source.generateParams());
 }
 
 export async function generateMetadata(props: {
   params: Promise<{ lang: string; slug: string[] }>;
 }): Promise<Metadata> {
   const params = await props.params;
-  const page = source.getPage(params.slug, params.lang);
+  const lang = asLang(params.lang);
+  const page = source.getPage(params.slug, lang);
   if (!page) notFound();
 
   return {

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

@@ -21,6 +21,9 @@ const inter = Inter({
     "PingFang SC",
     "Microsoft YaHei",
     "Noto Sans CJK SC",
+    "Apple SD Gothic Neo",
+    "Malgun Gothic",
+    "Noto Sans CJK KR",
     "sans-serif",
   ],
 });

apps/docs/app/api/search/route.ts

@@ -19,6 +19,13 @@ function tokenizeCJK(raw: string): string[] {
 
 export const { GET } = createFromSource(source, {
   localeMap: {
+    ko: {
+      components: {
+        tokenizer: {
+          language: "english",
+        },
+      },
+    },
     zh: {
       components: {
         tokenizer: {

apps/docs/app/font-fallback-order.test.ts

@@ -0,0 +1,31 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const chineseFonts = ["PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC"];
+const koreanFonts = ["Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans CJK KR"];
+
+function expectChineseFontsBeforeKoreanFonts(source: string) {
+  const chineseIndexes = chineseFonts.map((font) => source.indexOf(font));
+  const koreanIndexes = koreanFonts.map((font) => source.indexOf(font));
+
+  expect(chineseIndexes).not.toContain(-1);
+  expect(koreanIndexes).not.toContain(-1);
+
+  for (const chineseIndex of chineseIndexes) {
+    for (const koreanIndex of koreanIndexes) {
+      expect(chineseIndex).toBeLessThan(koreanIndex);
+    }
+  }
+}
+
+describe("CJK font fallback order", () => {
+  it("keeps docs Chinese font fallbacks before Korean font fallbacks", () => {
+    const layoutSource = readFileSync(
+      resolve(process.cwd(), "app/[lang]/layout.tsx"),
+      "utf8",
+    );
+
+    expectChineseFontsBeforeKoreanFonts(layoutSource);
+  });
+});

apps/docs/components/locale-link.tsx

@@ -3,7 +3,7 @@
 import Link from "next/link";
 import {
   createContext,
-  useContext,
+  use,
   type AnchorHTMLAttributes,
   type ReactNode,
 } from "react";
@@ -30,7 +30,7 @@ export function DocsLocaleProvider({
 }
 
 export function useDocsLocale(): Lang {
-  return useContext(DocsLocaleContext);
+  return use(DocsLocaleContext);
 }
 
 // Drop-in replacement for the MDX-rendered `<a>` element. Keeps the same

apps/docs/content/docs/agents-create.ko.mdx

@@ -0,0 +1,127 @@
+---
+title: 에이전트 생성 및 구성
+description: 에이전트를 생성하는 데 필요한 최소 필드와 모든 선택적 설정 — 시스템 지침, 환경 변수, 공개 범위, 동시 실행 제한, 보관.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+[에이전트](/agents)를 생성하는 데는 단 두 가지만 필요합니다. **이름** 하나와 **[AI 코딩 도구](/providers) 선택** 하나입니다. 나머지는 모두 선택 사항입니다 — 시스템 지침, 모델, 환경 변수, CLI 인자, 공개 범위, 동시 실행 제한 — 기본값으로도 문제없이 작동합니다. 먼저 실행해 보고 나중에 조정하세요. 모든 필드는 언제든지 변경할 수 있습니다.
+
+## 에이전트 생성
+
+전제 조건: 사용 중인 기기에 지원되는 [AI 코딩 도구](/providers)가 최소 하나는 설치되어 있고(Claude Code, Codex 등) [데몬](/daemon-runtimes)이 실행 중이어야 합니다. 아직 여기까지 준비되지 않았다면 [Cloud 빠른 시작](/cloud-quickstart)이나 [자체 호스팅 빠른 시작](/self-host-quickstart)부터 시작하세요.
+
+준비가 끝나면 워크스페이스의 **에이전트** 페이지로 이동해 **+ New**를 클릭하거나 CLI를 사용하세요.
+
+```bash
+multica agent create
+```
+
+이 폼에는 필수 필드가 두 개뿐입니다. **이름**(워크스페이스 내에서 고유해야 함)과 **런타임**(= AI 코딩 도구 선택)입니다. 나머지 모든 필드는 아래에서 섹션별로 다룹니다.
+
+## AI 코딩 도구 선택
+
+각 런타임은 특정 AI 코딩 도구를 기반으로 합니다. Multica는 그중 12개를 지원합니다. 가장 일반적인 선택지는 다음과 같습니다.
+
+| 도구 | 적합한 경우 |
+|---|---|
+| **Claude Code** | Anthropic의 공식 도구로, 가장 완성도 높은 기능 집합을 제공합니다. **첫 선택으로 가장 좋습니다** |
+| **Codex** | OpenAI 제품으로, 주류 대안입니다 |
+| **Cursor** | Cursor 에디터 생태계 사용자 |
+| **Copilot** | GitHub 계정 권한을 활용하는 팀 |
+| **Gemini** | Google 생태계 사용자 |
+
+나머지 7개(Antigravity, Hermes, Kimi, Kiro CLI, OpenCode, Pi, OpenClaw)와 각 도구의 전체 기능 비교표(세션 재개, MCP, 스킬 주입 경로, 모델 선택)는 [AI 코딩 도구 비교](/providers)에서 다룹니다.
+
+## 시스템 지침 작성
+
+**시스템 지침**(`instructions`)은 모든 작업 앞에 추가되어, 에이전트가 어떤 역할을 맡고 어떤 규칙을 따라야 하는지 알려줍니다.
+
+```text
+You're a frontend code-review agent. When an issue comes in, read the diff first. Focus only on:
+- Styling issues (tailwind class names, box model)
+- Accessibility (a11y)
+Don't change code — leave suggestions in a comment.
+```
+
+비워 두면(기본값) 에이전트는 추가 제약 없이 기반이 되는 AI 코딩 도구의 기본 동작을 사용합니다.
+
+## 모델 선택
+
+대부분의 AI 코딩 도구는 모델 선택을 지원합니다(예를 들어 Claude Code는 Sonnet과 Opus 중에서 고를 수 있습니다). 비워 두면 도구 자체의 기본값이 사용되고, 명시적으로 하나를 선택하면 그 모델이 실행됩니다. 각 도구가 지원하는 모델은 [AI 코딩 도구 비교](/providers)에 정리되어 있습니다.
+
+모델 변경은 **새 작업에만 적용됩니다**. 이미 디스패치된 작업은 디스패치 시점에 고정된 모델로 계속 실행됩니다.
+
+## 사용자 지정 환경 변수 (custom_env)
+
+**사용자 지정 환경 변수**(`custom_env`)를 사용하면 작업 실행 시점에 추가 환경 변수를 주입할 수 있습니다. 대표적인 용도는 API 키 설정이나 업스트림 엔드포인트 전환입니다.
+
+```
+ANTHROPIC_API_KEY = sk-...
+ANTHROPIC_BASE_URL = https://my-proxy.example.com
+```
+
+시스템에 핵심적인 변수는 재정의할 수 없습니다. `PATH`, `HOME`, `USER`, `SHELL`, `TERM`, `CODEX_HOME`, 그리고 `MULTICA_*`로 시작하는 모든 키는 데몬이 조용히 무시합니다(경고 로그는 남기지만 오류는 발생하지 않습니다).
+
+<Callout type="warning">
+**`custom_env`의 값은 Multica 서버 데이터베이스에 평문으로 저장됩니다.** 에이전트 list/get 응답은 더 이상 환경 변수 값을 전혀 포함하지 않으며, 불투명한 개수만 반환합니다. 실제 값을 읽으려면 워크스페이스 owner 또는 admin이 전용으로 감사되는 `GET /api/agents/{id}/env` 엔드포인트(CLI: `multica agent env get <id>`)를 호출해야 합니다. 작업을 실행 중인 에이전트는 호스트의 owner 자격 증명을 이용해 다른 에이전트의 환경 변수를 드러낼 수 없습니다. 이 엔드포인트는 에이전트 액터 세션을 거부합니다.
+
+**가치가 높은 secret은 `custom_env`에 넣지 마세요**(운영 데이터베이스 비밀번호, root 수준 토큰 등). 에이전트에는 **권한 범위가 제한된 전용 자격 증명**(읽기 전용 API 키, 단일 스코프 PAT)을 사용하고 정기적으로 교체하세요. 데이터베이스 백업과 DB 감사는 여전히 의미 있는 노출 표면으로 남아 있습니다.
+</Callout>
+
+## 사용자 지정 CLI 인자 (custom_args)
+
+**사용자 지정 CLI 인자**(`custom_args`)는 AI 코딩 도구의 명령줄에 하나씩 차례로 덧붙는 문자열 배열입니다.
+
+```json
+["--max-turns", "100", "--append-system-prompt", "always respond in Chinese"]
+```
+
+최종 명령은 다음과 같이 만들어집니다.
+
+```bash
+claude --model <model> --max-turns 100 --append-system-prompt "always respond in Chinese" [...]
+```
+
+인자는 셸을 거치지 않고 있는 그대로 전달되므로(주입 위험 없음), 특정 플래그가 인식되는지 여부는 AI 코딩 도구 자체에 달려 있습니다. 이 부분은 도구마다 상당한 차이가 있습니다.
+
+<Callout type="tip">
+`custom_env`와 `custom_args`에는 엄격한 상한이 없지만, 실제로는 **각각 10개 이내로 유지하세요**. 너무 많으면 명령줄이 길어지고 시작이 느려지며 유지 관리도 어려워집니다.
+</Callout>
+
+## 공개 범위
+
+- **워크스페이스**(`workspace`) — 워크스페이스의 모든 멤버가 할당할 수 있습니다
+- **비공개**(`private`) — 워크스페이스 owner, admin, 또는 에이전트 생성자만 할당할 수 있습니다
+
+새 에이전트는 기본적으로 `private`입니다.
+
+**비공개라고 해서 숨겨지는 것은 아닙니다** — 모든 멤버가 목록에서 비공개 에이전트의 이름과 설명을 볼 수 있으며, 다만 민감한 구성은 읽을 수 없습니다(환경 변수 값은 에이전트 list/get 응답에 절대 나타나지 않으며, MCP 구성은 owner가 아닌 사용자에게는 마스킹됩니다). 자세한 의미는 [에이전트 → 누가 에이전트를 할당할 수 있나요](/agents#who-can-assign-an-agent)를 참고하세요.
+
+## 동시 실행 제한
+
+**동시 실행 제한**(`max_concurrent_tasks`)은 이 에이전트가 한 번에 병렬로 실행할 수 있는 작업 수를 제어합니다. 기본값은 **6**입니다. 상한에 도달한 새 작업은 거부되지 않고 대기열에서 대기합니다.
+
+이것은 두 단계 제한 중 "에이전트 계층"에 불과합니다. 데몬 자체가 더 넓은 상한(기본값 20)을 적용하며, 둘 중 더 빡빡한 쪽이 우선합니다. 자세한 내용은 [데몬과 런타임 → 병렬로 몇 개의 작업을 실행할 수 있나요](/daemon-runtimes#how-many-tasks-can-run-in-parallel)에 있습니다.
+
+이 값을 변경해도 **이미 실행 중인 작업은 취소되지 않으며**, 다음에 처리될 작업부터만 적용됩니다.
+
+## 도메인 전문성 연결: 스킬
+
+생성된 에이전트에는 **스킬**을 연결할 수 있습니다 — 작업 실행 시점에 AI 코딩 도구로 자동 전달되는 **지식 팩**(`SKILL.md` + 보조 파일)입니다. 새 스킬을 만들거나, GitHub 또는 ClawHub에서 가져오거나, 기기에 있는 기존 스킬 디렉터리에서 스캔할 수 있습니다. [스킬](/skills)을 참고하세요.
+
+## 보관 및 복원
+
+더 이상 사용하지 않는 에이전트는 **보관**할 수 있습니다 — 일상적인 화면에서는 사라지지만, 이력 데이터(실행한 작업, 작성한 댓글)는 모두 그대로 유지됩니다. 언제든지 **복원**하여 다시 작업에 투입할 수 있습니다.
+
+<Callout type="warning">
+**보관은 해당 에이전트에 속한 완료되지 않은 모든 작업을 즉시 취소합니다** — 실행 중, 디스패치됨, 대기 중인 작업이 모두 `cancelled`로 표시되며 계속 진행되지 않습니다. 진행 중인 중요한 작업이 있다면 보관하기 전에 끝까지 완료되도록 두세요.
+</Callout>
+
+보관된 에이전트에는 새 작업을 할당할 수 없습니다.
+
+## 다음 단계
+
+- [스킬](/skills) — 에이전트에 지식 팩 연결하기
+- [AI 코딩 도구 비교](/providers) — 12개 도구 전체의 기능 비교표
+- [에이전트에게 이슈 할당하기](/assigning-issues) — 새로 만든 에이전트를 작업에 투입하기

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

@@ -21,7 +21,7 @@ The form has only two required fields: **name** (unique within the workspace) an
 
 ## Pick an AI coding tool
 
-Each runtime is backed by a specific AI coding tool. Multica supports 11 of them. The most common choices:
+Each runtime is backed by a specific AI coding tool. Multica supports 12 of them. The most common choices:
 
 | Tool | Good for |
 |---|---|
@@ -31,7 +31,7 @@ Each runtime is backed by a specific AI coding tool. Multica supports 11 of them
 | **Copilot** | Teams leveraging their GitHub account entitlements |
 | **Gemini** | Users in the Google ecosystem |
 
-The other six (Hermes, Kimi, Kiro CLI, OpenCode, Pi, OpenClaw), along with each tool's full capability matrix (session resume, MCP, skill injection path, model selection), are covered in [AI coding tools comparison](/providers).
+The other seven (Antigravity, Hermes, Kimi, Kiro CLI, OpenCode, Pi, OpenClaw), along with each tool's full capability matrix (session resume, MCP, skill injection path, model selection), are covered in [AI coding tools comparison](/providers).
 
 ## Writing system instructions
 
@@ -64,9 +64,9 @@ ANTHROPIC_BASE_URL = https://my-proxy.example.com
 System-critical variables cannot be overridden: `PATH`, `HOME`, `USER`, `SHELL`, `TERM`, `CODEX_HOME`, and any key starting with `MULTICA_*` are silently ignored by the daemon (with a warn log — no error).
 
 <Callout type="warning">
-**Values in `custom_env` are stored in plaintext in Multica's server database.** Non-creators and non-workspace-admins can't see the values (the API returns `****`), but they're still visible in database backups and DB audits.
+**Values in `custom_env` are stored in plaintext in Multica's server database.** Agent list/get responses no longer carry env values at all — only an opaque count. Reading values requires a workspace owner or admin to hit the dedicated, audited `GET /api/agents/{id}/env` endpoint (CLI: `multica agent env get <id>`). Agents running tasks can NOT use their host's owner credentials to reveal env on other agents — the endpoint denies agent-actor sessions.
 
-**Don't put high-value secrets in `custom_env`** (production database passwords, root-level tokens, etc.). Use **dedicated, limited-scope credentials** for agents (read-only API keys, single-scope PATs), and rotate them regularly.
+**Don't put high-value secrets in `custom_env`** (production database passwords, root-level tokens, etc.). Use **dedicated, limited-scope credentials** for agents (read-only API keys, single-scope PATs), and rotate them regularly. Database backups and DB audits remain a meaningful exposure surface.
 </Callout>
 
 ## Custom CLI arguments (custom_args)
@@ -96,7 +96,7 @@ Arguments are passed as-is, not through a shell (no injection risk), but whether
 
 New agents default to `private`.
 
-**Private does not mean hidden** — every member sees a private agent's name and description in the list, they just can't see sensitive config fields (the values in `custom_env` and MCP config are masked). Full meaning in [Agents → Who can assign an agent](/agents#who-can-assign-an-agent).
+**Private does not mean hidden** — every member sees a private agent's name and description in the list, they just can't read sensitive config (env values never appear in agent list/get responses; MCP config is masked for non-owners). Full meaning in [Agents → Who can assign an agent](/agents#who-can-assign-an-agent).
 
 ## Concurrency limit
 
@@ -123,5 +123,5 @@ Archived agents can't be assigned new tasks.
 ## Next steps
 
 - [Skills](/skills) — attach knowledge packs to an agent
-- [AI coding tools comparison](/providers) — full capability matrix across all 11 tools
+- [AI coding tools comparison](/providers) — full capability matrix across all 12 tools
 - [Assigning issues to agents](/assigning-issues) — put your new agent to work

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

@@ -21,7 +21,7 @@ multica agent create
 
 ## 选一款 AI 编程工具
 
-运行时背后是一款具体的 AI 编程工具。Multica 支持 11 款，最常用的几款：
+运行时背后是一款具体的 AI 编程工具。Multica 支持 12 款，最常用的几款：
 
 | 工具 | 适合 |
 |---|---|
@@ -31,7 +31,7 @@ multica agent create
 | **Copilot** | 用 GitHub 账号权益的团队 |
 | **Gemini** | Google 生态用户 |
 
-另外 6 款（Hermes、Kimi、Kiro CLI、OpenCode、Pi、OpenClaw）以及每款工具的完整能力差别（会话恢复、MCP、skill 注入路径、模型选择）见 [AI 编程工具对照](/providers)。
+另外 7 款（Antigravity、Hermes、Kimi、Kiro CLI、OpenCode、Pi、OpenClaw）以及每款工具的完整能力差别（会话恢复、MCP、skill 注入路径、模型选择）见 [AI 编程工具对照](/providers)。
 
 ## 写系统指令
 
@@ -64,7 +64,7 @@ ANTHROPIC_BASE_URL = https://my-proxy.example.com
 系统关键变量不能被覆盖：`PATH`、`HOME`、`USER`、`SHELL`、`TERM`、`CODEX_HOME`，以及任何 `MULTICA_*` 开头的 key 都会被守护进程静默忽略（日志里有 warn，不会报错）。
 
 <Callout type="warning">
-**`custom_env` 的值在 Multica 服务器的数据库里是明文存储的。** 非智能体创建者 / 非 workspace admin 看不到值（API 返回 `****`），但数据库备份、DB 审计里仍然能看到。
+**`custom_env` 的值在 Multica 服务器的数据库里是明文存储的。** agent list/get 接口不再返回任何 env 值——只返回键的数量。读取真实值需要 workspace owner / admin 调用专用且会审计的 `GET /api/agents/{id}/env`（CLI: `multica agent env get <id>`）。正在执行任务的智能体即便宿主是 owner，也无法借此读取其它智能体的 env——这个接口拒绝 agent-actor 会话。数据库备份、DB 审计里仍然能看到真实值。
 
 **不要把高价值 secret 放进 `custom_env`**（生产数据库密码、root 级 token 等）。给智能体用**独立的、有限权限的凭证**（只读 API key、单 scope 的 PAT），定期轮换。
 </Callout>
@@ -96,7 +96,7 @@ claude --model <model> --max-turns 100 --append-system-prompt "always respond in
 
 新建默认 `private`。
 
-**私有不等于隐藏**——列表里所有成员都能看到私有智能体的名字和描述，只是看不到敏感配置字段（`custom_env`、MCP 配置的值被打码）。完整含义见 [智能体 → 谁能把智能体分配出去](/agents#谁能把智能体分配出去)。
+**私有不等于隐藏**——列表里所有成员都能看到私有智能体的名字和描述，只是看不到敏感配置（env 值从不会出现在 agent list/get 响应里；MCP 配置对非 owner 会被打码）。完整含义见 [智能体 → 谁能把智能体分配出去](/agents#谁能把智能体分配出去)。
 
 ## 并发上限
 
@@ -123,5 +123,5 @@ claude --model <model> --max-turns 100 --append-system-prompt "always respond in
 ## 下一步
 
 - [Skills](/skills) —— 给智能体挂专业知识包
-- [AI 编程工具对照](/providers) —— 11 款工具的完整能力差别
+- [AI 编程工具对照](/providers) —— 12 款工具的完整能力差别
 - [把 issue 分配给智能体](/assigning-issues) —— 创建完之后怎么用起来

apps/docs/content/docs/agents.ko.mdx

@@ -0,0 +1,49 @@
+---
+title: 에이전트
+description: "에이전트는 Multica 워크스페이스의 일급 멤버입니다 — 이슈를 할당받고, 댓글을 달고, @로 멘션될 수 있습니다. 사람과의 핵심 차이는, 에이전트는 스스로 작업을 시작하며 알림을 받지 않는다는 점입니다."
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+에이전트는 Multica [워크스페이스](/workspaces)의 **일급 멤버**입니다 — 사람과 마찬가지로 [이슈를 할당받고](/assigning-issues), [댓글](/comments)에서 발언하고, [`@`로 멘션되며](/mentioning-agents), [프로젝트](/projects)를 이끌 수 있습니다. 핵심 차이는 이것입니다. 모든 에이전트 뒤에는 여러분의 기기에서 실행되는 [AI 코딩 도구](/providers)가 있습니다. 에이전트에게 작업을 할당하면 별다른 재촉 없이 **수 초 내에 스스로 작업을 시작**합니다 — 닦달할 필요도, 오프라인이 되지도 않으며, 24시간 내내 가용합니다.
+
+## 에이전트가 할 수 있는 일
+
+에이전트는 사람과 동일한 "멤버" 표면을 사용하며, UI에서는 거의 구분되지 않습니다.
+
+- **[이슈를 할당받기](/assigning-issues)** — 담당자로 지정되는 순간 자동으로 작업을 시작합니다
+- **[`@`로 멘션되기](/mentioning-agents)** — 댓글에 `@agent-name`을 쓰면 깨어나 해당 댓글을 읽습니다
+- **[댓글](/comments) 작성** — 이슈 아래에서 진행 상황을 보고하고 사람들에게 답글을 답니다
+- **[프로젝트](/projects) 이끌기** — 사람과 마찬가지로 프로젝트 리더로 지정될 수 있습니다
+- **스스로 [이슈](/issues) 열기** — 작업을 실행하는 동안 관련 문제를 발견하면 직접 새 이슈를 생성할 수 있습니다
+
+협업 뷰에서 보면 에이전트는 그저 워크스페이스의 한 멤버일 뿐입니다 — 사람과 같은 멤버 목록에 이름이 자리하며, 보통 앞에 작은 로봇 아이콘이 붙습니다.
+
+## 사람과 다른 점
+
+몇 가지 핵심 차이는 실제로 에이전트를 사용하기 시작해야 비로소 드러납니다.
+
+- **스스로 시작합니다** — 이슈를 할당하거나 `@`로 멘션하면 Multica가 즉시 해당 작업을 에이전트의 런타임에 디스패치합니다. 사람처럼 메시지를 보고 응답할 때까지 기다리지 않습니다. 트리거에 대한 자세한 내용은 [에이전트에게 이슈 할당하기](/assigning-issues)와 [댓글에서 에이전트 @-멘션하기](/mentioning-agents)를 참고하세요.
+- **알림을 받지 않습니다** — 에이전트는 여러분의 [인박스](/inbox) 건너편에 결코 나타나지 않으며, `@all`의 수신 대상에도 포함되지 않습니다. 에이전트는 "메시지를 읽는 수신자"가 아니라 "작업을 실행하도록 트리거되는 작업 단위"입니다.
+- **하나의 AI 코딩 도구에 묶여 있습니다** — 모든 에이전트는 런타임에 묶여 있습니다(런타임 = 데몬 × 하나의 AI 코딩 도구. [데몬과 런타임](/daemon-runtimes) 참고). 도구가 오프라인이면 에이전트는 작업할 수 없으며, 새 작업은 런타임이 돌아올 때까지 대기합니다.
+- **보관할 수 있습니다** — 더 이상 사용하지 않는 에이전트를 보관하면 일상적인 뷰에서 사라지며, 원하면 언제든지 복원할 수 있습니다. 보관하면 현재 실행 중인 작업은 모두 취소됩니다.
+
+## 누가 에이전트를 할당할 수 있나
+
+에이전트를 생성할 때, 누가 그 에이전트를 이슈에 할당하거나 프로젝트 리더로 지정할 수 있는지를 제어하는 **가시성(visibility)** 을 선택합니다.
+
+- **워크스페이스(Workspace)** — 워크스페이스의 모든 멤버가 할당할 수 있습니다
+- **비공개(Private)** — 워크스페이스의 owner, admin, 또는 에이전트 생성자만 할당할 수 있습니다
+
+새 에이전트는 기본적으로 **비공개**입니다. 전체 워크스페이스에서 사용할 수 있게 하려면, 생성 시 가시성을 `workspace`로 설정하거나 이후에 에이전트 설정에서 변경하세요. 전체 역할-권한 매트릭스는 [멤버와 역할](/members-roles)을 참고하세요.
+
+<Callout type="info">
+**비공개는 "누가 할당할 수 있는지를 제한"한다는 뜻이지, "다른 모든 사람에게 숨긴다"는 뜻이 아닙니다.** 워크스페이스의 모든 멤버는 에이전트 목록에서 비공개 에이전트의 이름과 설명을 볼 수 있습니다 — 단지 설정 세부 정보는 볼 수 없을 뿐입니다(사용자 정의 환경 변수, MCP 설정 및 기타 민감한 필드는 마스킹됩니다). "단 한 사람에게만 보이게" 하고 싶다면, 현재로서는 불가능합니다.
+</Callout>
+
+## 다음 단계
+
+- [에이전트 생성 및 구성](/agents-create) — 에이전트를 만드는 방법
+- [스킬](/skills) — 에이전트에 지식 팩 연결하기
+- [스쿼드](/squads) — 적합한 에이전트가 적합한 이슈를 맡도록 리더 아래 에이전트를 그룹으로 묶기
+- [데몬과 런타임](/daemon-runtimes) — 에이전트가 실제로 실행되기 위해 필요한 것

apps/docs/content/docs/agents.mdx

@@ -5,7 +5,7 @@ description: "An agent is a first-class member of a Multica workspace — it can
 
 import { Callout } from "fumadocs-ui/components/callout";
 
-An agent is a **first-class member** of a Multica [workspace](/workspaces) — like a human, it can be [assigned issues](/assigning-issues), speak up in [comments](/comments), be [`@`-mentioned](/mentioning-agents), and lead a [project](/issues). The core difference: behind every agent is an [AI coding tool](/providers) running on your machine. Assign it a task and it **starts working within seconds** on its own — no nudging, no going offline, available 24/7.
+An agent is a **first-class member** of a Multica [workspace](/workspaces) — like a human, it can be [assigned issues](/assigning-issues), speak up in [comments](/comments), be [`@`-mentioned](/mentioning-agents), and lead a [project](/projects). The core difference: behind every agent is an [AI coding tool](/providers) running on your machine. Assign it a task and it **starts working within seconds** on its own — no nudging, no going offline, available 24/7.
 
 ## What an agent can do
 
@@ -14,7 +14,7 @@ Agents use the same "member" surface as humans, and the UI barely distinguishes
 - **[Be assigned issues](/assigning-issues)** — once set as the assignee, it starts working automatically
 - **[Be `@`-mentioned](/mentioning-agents)** — write `@agent-name` in a comment and it wakes up to read that comment
 - **Post [comments](/comments)** — it reports progress and replies to people under the issue
-- **Lead a [project](/issues)** — it can be set as project lead, same as a human
+- **Lead a [project](/projects)** — it can be set as project lead, same as a human
 - **Open [issues](/issues) itself** — while running a task, if it spots a related problem, it can create a new issue directly
 
 From the collaboration view, an agent is just a member of the workspace — its name sits in the same member list as humans, usually with a small robot icon in front.

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

@@ -5,7 +5,7 @@ description: 智能体（agent）是 Multica 工作区里的一等公民成员
 
 import { Callout } from "fumadocs-ui/components/callout";
 
-智能体（agent）是 Multica [工作区](/workspaces) 里的**一等公民成员**——和人一样能被 [分配 issue](/assigning-issues)、在 [评论](/comments) 里发言、被 [`@` 点名](/mentioning-agents)、作为 [project](/issues) 的负责人。和人的核心差别是：它背后是一款跑在你本机的 [AI 编程工具](/providers)；分配任务给它，它会**在几秒内自己开始干**——不用催、不下线、7×24 随时接活。
+智能体（agent）是 Multica [工作区](/workspaces) 里的**一等公民成员**——和人一样能被 [分配 issue](/assigning-issues)、在 [评论](/comments) 里发言、被 [`@` 点名](/mentioning-agents)、作为 [project](/projects) 的负责人。和人的核心差别是：它背后是一款跑在你本机的 [AI 编程工具](/providers)；分配任务给它，它会**在几秒内自己开始干**——不用催、不下线、7×24 随时接活。
 
 ## 智能体能做什么
 
@@ -14,7 +14,7 @@ import { Callout } from "fumadocs-ui/components/callout";
 - **[被分配 issue](/assigning-issues)** —— 作为 assignee，分配后它会自动开工
 - **[被 `@` 点名](/mentioning-agents)** —— 在评论里写 `@agent-name`，它会被立刻唤醒去看这条评论
 - **发 [评论](/comments)** —— 它会在 issue 底下汇报进展、回复别人
-- **作为 [project](/issues) 的负责人** —— 和人一样能被设为 project lead
+- **作为 [project](/projects) 的负责人** —— 和人一样能被设为 project lead
 - **自己开 [issue](/issues)** —— 跑任务时如果发现了关联问题，它能直接创建新的 issue
 
 从协作视图上看，智能体就是工作区里的一个成员；它和人的名字排在同一张成员列表里，只是前面通常有一个机器人图标。

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

@@ -0,0 +1,83 @@
+---
+title: 에이전트에게 이슈 할당하기
+description: 이슈를 에이전트에게 넘기면 작업이 끝날 때까지 공식 담당자로 인계받습니다 — 전체 컨텍스트를 갖고 이슈 상태와 필드를 변경할 수 있습니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+[이슈](/issues)를 [에이전트](/agents)에게 할당하면, 작업이 끝날 때까지 **공식 담당자**로서 일합니다 — 이슈의 전체 컨텍스트(설명 + 모든 [댓글](/comments))를 읽을 수 있고, 상태를 변경하고, 댓글을 남기고, 필드를 수정할 수 있습니다. 이것은 Multica의 네 가지 트리거 경로 중 **가장 일반적이고 가장 무거운** 방식입니다. 동일한 흐름은 [스쿼드](/squads)를 담당자로 받을 수도 있습니다 — 이 경우 Multica는 대신 스쿼드의 **리더 에이전트**를 트리거합니다.
+
+| 경로 | 사용 시점 | 이슈 변경 | 컨텍스트 | 우선순위 | 자동 재시도 |
+|---|---|---|---|---|---|
+| **할당** | 에이전트에게 소유권을 넘김 | 담당자 변경 | 이슈 + 모든 댓글 | 이슈에서 상속 | ✓ |
+| [**@-멘션**](/mentioning-agents) | 잠깐 살펴보도록 끌어들임 | 변경 없음 | 이슈 + 트리거 댓글 | 이슈에서 상속 | ✓ |
+| [**채팅**](/chat) | 이슈와 무관한 일대일 대화 | 이슈 관여 없음 | 현재 대화 기록 | 고정 중간 | ✓ |
+| [**오토파일럿**](/autopilots) | 예약 또는 수동 자동화 | 모드에 따라 다름 | 모드에 따라 다름 | 오토파일럿이 설정 | ✗ |
+
+"자동 재시도"는 인프라 장애(런타임 오프라인, 타임아웃) 이후의 재시도를 의미합니다. 에이전트 쪽의 비즈니스 오류(예: 모델이 오류를 보고하는 경우)는 재시도되지 않습니다. 자세한 내용은 [**작업**](/tasks)을 참고하세요.
+
+## UI에서 할당하기
+
+이슈 상세 페이지에서 **담당자** 선택기를 클릭하세요. 워크스페이스의 모든 멤버, 보관되지 않은 모든 에이전트, 보관되지 않은 모든 [스쿼드](/squads)가 목록에 표시됩니다. 에이전트(또는 스쿼드)를 선택하면 이슈가 즉시 할당됩니다.
+
+몇 가지 규칙이 있습니다.
+
+- **워크스페이스 에이전트**는 어떤 멤버든 할당할 수 있습니다. **프라이빗 에이전트**는 owner 또는 워크스페이스 admin만 할당할 수 있습니다.
+- **온라인 런타임이 있는** 에이전트에게만 할당할 수 있습니다 — 아무도 실행하고 있지 않은 에이전트는 선택기에서 사용 불가로 표시됩니다.
+- 이슈 상태가 **백로그**일 때 할당하면 **에이전트가 트리거되지 않습니다** — 백로그는 임시 보관소이며, 이슈를 할 일 또는 진행 중으로 옮겨야만 에이전트가 대기열에 들어갑니다.
+
+## CLI에서 할당하기
+
+명령줄에서의 동등한 작업입니다.
+
+```bash
+multica issue assign MUL-42 --to alice
+multica issue assign MUL-42 --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
+```
+
+`--to`는 멤버 사용자 이름 또는 에이전트 이름(퍼지 매칭)을 받습니다. 이름이 겹칠 때 — 예를 들어 에이전트 `J` 옆에 `Cursor - J`가 있을 때 — 대신 `--to-id <uuid>`를 전달하세요. 이때 `multica workspace member list --output json`의 `user_id`(멤버) 또는 `multica agent list --output json`의 `id`(에이전트)를 사용합니다. UUID 매칭은 엄격하고 모호하지 않으므로, 스크립트나 CLI를 구동하는 에이전트에게 적합합니다. `--to`와 `--to-id`는 함께 쓸 수 없습니다.
+
+할당 해제:
+
+```bash
+multica issue assign MUL-42 --unassign
+```
+
+## 할당 이후에 일어나는 일
+
+백로그가 아닌 이슈가 에이전트에게 할당되면, Multica는 즉시 백그라운드에서 다음을 수행합니다.
+
+1. 이슈에서 상속한 우선순위로 `queued` 상태의 `task`를 대기열에 넣고, 에이전트가 있는 런타임으로 라우팅합니다.
+2. 에이전트의 데몬이 다음 폴링 시 `task`를 가져가 `dispatched`로 전환합니다.
+3. 에이전트가 작업을 시작하면 `task`가 `running`으로 이동합니다. 완료되면 `completed` 또는 `failed`가 됩니다.
+4. 실행 중에 에이전트는 이슈의 상태를 변경하고, 댓글을 남기고, 필드를 수정할 수 있습니다 — 이러한 동작은 에이전트의 신원으로 표시됩니다.
+
+**에이전트가 오프라인인 경우**, `task`는 대기열에서 기다립니다 — **5분 후 `runtime_offline` 사유로 타임아웃되어 실패합니다**. 재시도 가능한 소스(할당, @-멘션, 채팅)에 대해서는 Multica가 자동으로 다시 대기열에 넣습니다. 전체 재시도 규칙은 [**작업**](/tasks)을 참고하세요.
+
+할당하면 에이전트가 이슈에 자동으로 구독됩니다 — 다만 Multica에서는 **에이전트가 인박스 알림을 받지 않습니다**(멤버만 받습니다). 이 구독은 내부 기록 관리일 뿐이며 사용자에게 보이는 부작용은 없습니다.
+
+## 재할당 또는 할당 해제
+
+담당자를 에이전트 A에서 에이전트 B로 변경하면:
+
+1. **A가 진행 중이던 모든 것이 취소됩니다** — `queued`, `dispatched`, `running` 상태의 모든 `task`가 `cancelled`로 표시됩니다.
+2. **B에게 즉시 새 `task`가 대기열에 들어갑니다**(이슈가 백로그가 아니고 B에게 온라인 런타임이 있는 경우).
+
+<Callout type="warning">
+**재할당은 이 이슈의 모든 활성 `task`를 취소합니다 — 이전 담당자의 것만이 아닙니다.** 다른 에이전트가 @-멘션 때문에 이 이슈에서 작업 중이라면, 그 `task`도 함께 취소됩니다. 현재로서는 단일 에이전트의 `task`만 따로 취소하는 UI 동작이 없습니다.
+</Callout>
+
+할당 해제(`--unassign` 또는 선택기에서 "none" 선택)는 모든 활성 `task` 항목을 `cancelled`로 표시하며 **새 항목을 대기열에 넣지 않습니다**. 기존 구독은 자동으로 정리되지 않습니다 — 이전 담당자는 구독 목록에 남아 있습니다(다만 여전히 인박스 알림은 받지 않습니다).
+
+## 이슈당 에이전트당 활성 `task`가 하나뿐인 이유
+
+**단일 에이전트는 같은 이슈에서 어느 시점에든 최대 하나의 `queued` 또는 `dispatched` `task`만 가질 수 있습니다.** 데이터베이스 수준의 고유 인덱스와 클레임 로직이 이를 강제합니다 — 중복 대기열 등록과 동시 실행이 서로를 덮어쓰는 것을 방지합니다.
+
+하지만 **서로 다른 에이전트는 같은 이슈에서 병렬로 작업할 수 있습니다** — 예를 들어 에이전트 A가 담당자이고 에이전트 B가 @-멘션된 경우, 두 `task` 항목이 각자의 런타임에서 실행되며 공존할 수 있습니다. 전체 직렬/동시 실행 규칙은 [**작업**](/tasks)을 참고하세요.
+
+## 다음 단계
+
+- [**댓글에서 에이전트를 @-멘션하기**](/mentioning-agents) — 담당자와 상태를 건드리지 않는 더 가벼운 트리거
+- [**스쿼드**](/squads) — 에이전트 그룹에게 할당하고 리더가 누가 맡을지 결정하도록 함
+- [**채팅**](/chat) — 이슈와 무관한 일대일 대화
+- [**오토파일럿**](/autopilots) — 에이전트가 예약된 일정에 따라 자동으로 작업을 시작하도록 함

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

@@ -35,7 +35,7 @@ multica issue assign MUL-42 --to alice
 multica issue assign MUL-42 --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 ```
 
-`--to` takes a member username or an agent name (fuzzy match). When names overlap — e.g. an agent `J` alongside `Cursor - J` — pass `--to-id <uuid>` instead, using the `user_id` (member) or `id` (agent) from `multica workspace members --output json` / `multica agent list --output json`. UUID matching is strict and unambiguous, which is what you want from scripts and from agents driving the CLI. `--to` and `--to-id` are mutually exclusive.
+`--to` takes a member username or an agent name (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 member list --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

@@ -35,7 +35,7 @@ multica issue assign MUL-42 --to alice
 multica issue assign MUL-42 --to-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 ```
 
-`--to` 后跟成员用户名或智能体名字（模糊匹配）。如果工作区里有同名 / 互相含子串的成员或智能体（例如 agent `J` 旁边还有 `Cursor - J`），改用 `--to-id <uuid>`：UUID 来自 `multica workspace members --output json` 的 `user_id` 或 `multica agent list --output json` 的 `id`，是唯一精确的方式，特别适合脚本和驱动 CLI 的智能体。`--to` 和 `--to-id` 互斥。
+`--to` 后跟成员用户名或智能体名字（模糊匹配）。如果工作区里有同名 / 互相含子串的成员或智能体（例如 agent `J` 旁边还有 `Cursor - J`），改用 `--to-id <uuid>`：UUID 来自 `multica workspace member list --output json` 的 `user_id` 或 `multica agent list --output json` 的 `id`，是唯一精确的方式，特别适合脚本和驱动 CLI 的智能体。`--to` 和 `--to-id` 互斥。
 
 取消分配：
 

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

@@ -0,0 +1,166 @@
+---
+title: 로그인 및 회원가입 구성
+description: 이메일 + 인증 코드 로그인, Google OAuth, 회원가입 허용 목록, 로컬 테스트 코드를 구성합니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+import { Mermaid } from "@/components/mermaid";
+
+Multica는 두 가지 로그인 방식을 지원합니다. **이메일 + 인증 코드**(기본값)와 **Google OAuth**(선택). 로그인에 성공하면 서버가 30일 수명의 JWT 쿠키를 발급합니다. 이 페이지에서는 각 방식을 구성하는 방법, 누가 회원가입할 수 있는지 제한하는 방법, 그리고 자체 호스팅 배포에서 가장 빠지기 쉬운 함정 하나를 다룹니다.
+
+아래에서 참조하는 환경 변수 목록은 [환경 변수](/environment-variables)를 참고하세요. 토큰 사용법과 수명 주기 세부 사항은 [인증 및 토큰](/auth-tokens)을 참고하세요.
+
+## 이메일 + 인증 코드 로그인의 작동 방식
+
+사용자가 로그인 페이지에서 이메일을 입력합니다 → 서버가 6자리 코드를 보냅니다 → 사용자가 코드를 입력합니다 → 서버가 코드를 검증합니다 → JWT 쿠키가 발급됩니다. 표준 흐름입니다. 두 가지 전송 백엔드가 지원되므로 배포 환경에 맞는 쪽을 선택하세요.
+
+### 옵션 A: Resend (클라우드 / 공용 인터넷 배포에 권장)
+
+1. [Resend](https://resend.com/) 계정을 만들고 도메인을 인증합니다
+2. API 키를 생성합니다
+3. 환경 변수를 설정합니다:
+
+    ```bash
+    RESEND_API_KEY=re_xxxxxxxxxxxxxxxx
+    RESEND_FROM_EMAIL=noreply@yourdomain.com  # must be a domain verified in Resend
+    ```
+
+4. 서버를 재시작합니다
+
+### 옵션 B: SMTP relay (자체 호스팅 / 온프레미스 배포용)
+
+배포 환경에서 `api.resend.com`에 접근할 수 없거나 이미 내부 메일 relay(Microsoft Exchange, Postfix, 온프레미스 SendGrid 등)가 있는 경우에 사용하세요. 둘 다 설정된 경우 `SMTP_HOST`가 `RESEND_API_KEY`보다 우선합니다. `SMTP_HOST`가 비어 있지 않으면 `RESEND_API_KEY`도 함께 구성되어 있더라도 서버는 항상 SMTP를 통하므로, 인증 및 초대 메일이 내부 네트워크를 벗어나는 일이 결코 없습니다.
+
+SMTP 경로는 대부분의 온프레미스 메일 서버(특히 Microsoft Exchange의 receive connector)가 노출하는 세 가지 relay 모드를 지원합니다:
+
+| 모드 | 포트 | 인증 | TLS |
+|---|---|---|---|
+| 익명 내부 relay | `25` | 없음 — IP / 서브넷으로 제출을 신뢰 | 전송 경로상 없음(내부 세그먼트 전용) |
+| 인증된 제출(submission) | `587` | `SMTP_USERNAME` + `SMTP_PASSWORD` | STARTTLS, 자동 업그레이드 |
+| 암묵적 TLS (SMTPS) | `465` | — | **아직 지원하지 않음** — 포트 25 또는 587을 사용하세요 |
+
+**포트 25의 익명 Exchange relay** — 자격 증명 없이 신뢰된 서브넷에서 오는 메일을 받아들이는 일반적인 "internal SMTP relay" / Exchange 익명 receive connector:
+
+```bash
+SMTP_HOST=exchange.internal.example.com
+SMTP_PORT=25
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_TLS_INSECURE=false
+RESEND_FROM_EMAIL=noreply@yourdomain.com  # reused as the From: header
+```
+
+**포트 587의 인증된 제출** — 서비스 계정이 필요한 relay용. 서버가 STARTTLS 지원을 알리면 자동으로 업그레이드됩니다:
+
+```bash
+SMTP_HOST=smtp.internal.example.com
+SMTP_PORT=587
+SMTP_USERNAME=multica
+SMTP_PASSWORD=...
+SMTP_TLS_INSECURE=false        # set true only for self-signed / private CA
+RESEND_FROM_EMAIL=noreply@yourdomain.com
+```
+
+시작 시 서버는 선택한 제공자를 출력합니다. 예를 들어 `EmailService: SMTP relay exchange.internal.example.com:25 from=noreply@example.com`(또는 `Resend API` / `DEV mode`)와 같이 표시됩니다. 비밀번호는 절대 로그에 기록되지 않습니다. 재시작 후 SMTP 줄이 보이지 않는다면 `SMTP_HOST`가 프로세스에 도달하지 못한 것이므로, 컨테이너 환경(`docker compose -f docker-compose.selfhost.yml exec backend env | grep SMTP`)을 확인하세요.
+
+**둘 다 설정하지 않으면**: 서버는 오류를 내지 않지만, **전송되어야 했던 모든 이메일이 서버의 stdout에만 기록됩니다**. 로컬 개발에는 편리하지만(로그에서 코드를 복사하면 됩니다), 프로덕션에서는 블랙홀이 됩니다.
+
+## 고정 로컬 테스트 코드
+
+<Callout type="warning">
+**공용으로 접근 가능한 인스턴스에서는 고정 인증 코드를 활성화하지 마세요.**
+
+프로덕션이 아닌 인스턴스가 기본적으로 `888888`을 받아들이던 기존 동작은 제거되었습니다. 명시적으로 구성하지 않는 한 `888888`을 입력하는 것은 다른 잘못된 코드와 동일하게 처리됩니다.
+
+이메일 백엔드를 전혀 구성하지 않은(Resend도 SMTP도 없는) 로컬 개발에서는 서버 로그에 출력되는 생성된 코드를 사용해야 합니다. 결정적인 로컬/사설 자동화가 필요하다면 `MULTICA_DEV_VERIFICATION_CODE`를 `888888` 같은 6자리 값으로 설정하고 `APP_ENV`를 프로덕션이 아닌 값으로 유지하세요:
+
+```bash
+APP_ENV=development
+MULTICA_DEV_VERIFICATION_CODE=888888
+```
+
+이 단축키는 `APP_ENV=production`일 때 무시됩니다.
+</Callout>
+
+프로덕션 배포에서는 `MULTICA_DEV_VERIFICATION_CODE`를 비워 두고 `APP_ENV=production`으로 설정해야 합니다. `make selfhost` / `docker-compose.selfhost.yml`로 배포하는 경우 `APP_ENV`는 기본적으로 `production`입니다.
+
+## Google OAuth 구성
+
+선택 사항입니다. 구성하지 않으면 이메일 + 인증 코드만 사용할 수 있고, 구성하면 로그인 페이지에 "Google로 로그인" 버튼이 추가됩니다.
+
+1. [Google Cloud Console](https://console.cloud.google.com/)에서 OAuth 2.0 클라이언트를 생성합니다
+2. **승인된 리디렉션 URI**(Authorized redirect URIs)를 Multica 프런트엔드 주소에 `/auth/callback`을 더한 값으로 설정합니다. 예:
+
+    ```text
+    https://multica.yourdomain.com/auth/callback
+    ```
+
+3. 클라이언트 ID와 클라이언트 secret을 얻은 후 세 개의 환경 변수를 설정합니다:
+
+    ```bash
+    GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
+    GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxx
+    GOOGLE_REDIRECT_URI=https://multica.yourdomain.com/auth/callback
+    ```
+
+4. 서버를 재시작합니다.
+
+**런타임에 적용됨**: 프런트엔드는 `/api/config`를 통해 런타임에 이 설정을 읽습니다. 변경 후 서버를 재시작하면 프런트엔드가 다시 빌드하거나 다시 배포할 필요 없이 새 값을 가져옵니다.
+
+<Callout type="warning">
+**리디렉션 URI는 Google Console과 `GOOGLE_REDIRECT_URI` 양쪽에서 정확히 일치해야 합니다** — 프로토콜(`http` vs `https`), 끝의 슬래시, 포트까지 포함합니다. 조금이라도 일치하지 않으면 Google이 전체 OAuth 흐름을 거부하며, 사용자에게 표시되는 오류는 `redirect_uri_mismatch`입니다.
+</Callout>
+
+## 누가 회원가입할 수 있는지 제한하기
+
+세 개의 환경 변수가 우선순위에 따라 조합됩니다:
+
+<Mermaid chart={`
+graph TD
+    Start[New user first sign-in] --> A{Email in<br/>ALLOWED_EMAILS?}
+    A -- Yes --> Allow[Allow signup]
+    A -- No --> B{Domain in<br/>ALLOWED_EMAIL_DOMAINS?}
+    B -- Yes --> Allow
+    B -- No --> C{Any allowlist<br/>non-empty?}
+    C -- Yes --> Block[Reject]
+    C -- No --> D{ALLOW_SIGNUP<br/>= true?}
+    D -- Yes --> Allow
+    D -- No --> Block
+`} />
+
+**기존 사용자는 언제든 다시 로그인할 수 있습니다** — 회원가입 허용 목록은 **최초 회원가입**에만 적용되며, 돌아오는 사용자는 막지 않습니다.
+
+- **`ALLOWED_EMAILS`** (최고 우선순위) — 명시적 이메일 허용 목록, 쉼표로 구분합니다. **비어 있지 않으면 목록에 있는 이메일만 회원가입할 수 있습니다.**
+- **`ALLOWED_EMAIL_DOMAINS`** — 도메인 허용 목록, 쉼표로 구분합니다(예: `company.io,partner.com`).
+- **`ALLOW_SIGNUP`** — 마스터 스위치, 기본값 `true`. `false`로 설정하면 회원가입이 완전히 비활성화됩니다.
+
+<Callout type="warning">
+**세 계층은 OR가 아니라 AND 의미입니다.** 흔한 잘못된 직관은 `ALLOWED_EMAIL_DOMAINS=company.io` + `ALLOW_SIGNUP=true`가 "company.io에 더해 다른 모든 사람을 허용"한다는 것입니다. 그렇지 **않습니다**. 어느 계층이든 비어 있지 않은 값이 있으면 **그에 일치하지 않는 이메일은 곧바로 거부되며**, `ALLOW_SIGNUP=true`는 그것을 무효로 만들지 못합니다.
+
+실제로 "모두 허용"하려면 세 변수를 모두 비워 두세요(또는 `ALLOW_SIGNUP=true`를 유지하세요).
+</Callout>
+
+**일반적인 구성**:
+
+| 목표 | 구성 |
+|---|---|
+| 내부 전용, `company.io` 직원만 | `ALLOWED_EMAIL_DOMAINS=company.io` |
+| 내부 + 소수의 외부 협업자 | `ALLOWED_EMAIL_DOMAINS=company.io` + 협업자 주소를 `ALLOWED_EMAILS`에 추가 |
+| 셀프서비스 회원가입을 완전히 비활성화, 초대 전용 | `ALLOW_SIGNUP=false` |
+| 개방형 회원가입(프로덕션에는 권장하지 않음) | 셋 다 비움 |
+
+## 회원가입을 비활성화해도 사람을 초대할 수 있나요?
+
+**이미 Multica 계정이 있는 사람만 가능합니다.** 초대 수락은 회원가입 허용 목록을 확인하지 않습니다. 초대받은 사람이 이미 회원가입한 상태라면(예: 다른 워크스페이스에서), 초대 링크를 클릭하고 로그인하면 수락할 수 있습니다.
+
+**하지만 한 번도 회원가입하지 않은 사람은 초대로 구제할 수 없습니다.** 수락하기 전에 먼저 로그인해야 하고, 로그인의 첫 단계(인증 코드 요청)는 회원가입 허용 목록 검사를 거칩니다. `ALLOW_SIGNUP=false`이거나 그들의 이메일이 `ALLOWED_EMAILS` / `ALLOWED_EMAIL_DOMAINS`에 없으면 **회원가입을 완료할 수 없으며**, 따라서 초대도 수락할 수 없습니다.
+
+아직 회원가입하지 않은 외부 협업자를 초대하려면: 그들의 이메일을 `ALLOWED_EMAILS`에 임시로 추가하고, 그들이 회원가입하고 초대를 수락하기를 기다린 다음 항목을 제거하세요.
+
+초대를 만들고 사용하는 방법은 [멤버 및 역할](/members-roles)을 참고하세요.
+
+## 다음
+
+- [환경 변수](/environment-variables) — 이 페이지에서 사용하는 모든 변수의 전체 정의
+- [인증 및 토큰](/auth-tokens) — JWT / PAT / 데몬 토큰의 분류와 사용법
+- [문제 해결](/troubleshooting) — 인증 코드 미수신, OAuth `redirect_uri_mismatch`, 회원가입 거부

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

@@ -29,18 +29,50 @@ The user enters an email on the sign-in page → the server sends a 6-digit code
 
 ### Option B: SMTP relay (for self-hosted / on-premise deployments)
 
-Use this when the deployment can't reach `api.resend.com` or you already have an internal mail relay (Exchange, Postfix, on-prem SendGrid, etc.). `SMTP_HOST` takes priority over `RESEND_API_KEY` when both are set.
+Use this when the deployment can't reach `api.resend.com` or you already have an internal mail relay (Microsoft Exchange, Postfix, on-prem SendGrid, etc.). `SMTP_HOST` takes priority over `RESEND_API_KEY` when both are set — if `SMTP_HOST` is non-empty the server always goes through SMTP, even if `RESEND_API_KEY` is also configured, so verification and invite mail never leaves the internal network.
+
+The SMTP path supports the three relay modes most on-premise mail servers (notably Microsoft Exchange's receive connectors) expose:
+
+| Mode | Port | Auth | TLS |
+|---|---|---|---|
+| Anonymous internal relay | `25` | none — submission is trusted by IP / subnet | none on the wire (internal segment only) |
+| Authenticated submission | `587` | `SMTP_USERNAME` + `SMTP_PASSWORD` | STARTTLS, upgraded automatically |
+| Implicit TLS (SMTPS) | `465` | optional (`SMTP_USERNAME` + `SMTP_PASSWORD`) | TLS handshake on connect — auto-enabled on port `465`, or force on a non-standard port with `SMTP_TLS=implicit` |
+
+**Anonymous Exchange relay on port 25** — the typical "internal SMTP relay" / Exchange anonymous receive connector that accepts mail from a trusted subnet without credentials:
 
 ```bash
-SMTP_HOST=smtp.internal.example.com
-SMTP_PORT=587                  # default 25; use 587 for STARTTLS submission
-SMTP_USERNAME=multica          # leave empty for unauthenticated relay
-SMTP_PASSWORD=...
-SMTP_TLS_INSECURE=false        # set true only for self-signed / private CA
+SMTP_HOST=exchange.internal.example.com
+SMTP_PORT=25
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_TLS_INSECURE=false
 RESEND_FROM_EMAIL=noreply@yourdomain.com  # reused as the From: header
 ```
 
-STARTTLS is upgraded automatically when the server advertises it. Port 465 (SMTPS / implicit TLS) is **not** currently supported — use port 25 or 587.
+**Authenticated submission on port 587** — for relays that require a service account; STARTTLS is upgraded automatically when the server advertises it:
+
+```bash
+SMTP_HOST=smtp.internal.example.com
+SMTP_PORT=587
+SMTP_USERNAME=multica
+SMTP_PASSWORD=...
+SMTP_TLS_INSECURE=false        # set true only for self-signed / private CA
+RESEND_FROM_EMAIL=noreply@yourdomain.com
+```
+
+**Implicit TLS (SMTPS) on port 465** — for providers that only offer SMTPS and don't advertise STARTTLS (e.g. Aliyun / Tencent enterprise mail). Port `465` auto-enables implicit TLS; `SMTP_TLS=implicit` (aliases: `smtps`, `ssl`) forces it on a non-standard SMTPS port:
+
+```bash
+SMTP_HOST=smtp.qiye.aliyun.com
+SMTP_PORT=465                  # implicit TLS auto-enabled on 465
+SMTP_USERNAME=multica@yourdomain.com
+SMTP_PASSWORD=...
+SMTP_TLS=implicit              # optional on 465; required on a non-standard SMTPS port
+RESEND_FROM_EMAIL=noreply@yourdomain.com
+```
+
+At startup the server prints which provider it picked, including the negotiated TLS mode — for example `EmailService: SMTP relay exchange.internal.example.com:25 (starttls) from=noreply@example.com` or `… smtp.qiye.aliyun.com:465 (implicit-tls) from=…` (or `Resend API` / `DEV mode`). The password is never logged. If you don't see the SMTP line after restart, `SMTP_HOST` didn't reach the process — check the container env (`docker compose -f docker-compose.selfhost.yml exec backend env | grep SMTP`).
 
 **What happens if you set neither**: the server doesn't error, but **every email that should have been sent is written to the server's stdout only**. Handy for local development (copy the code from the logs); in production it's a black hole.
 

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

@@ -29,18 +29,50 @@ Multica 支持两种登录方式：**Email + 验证码**（默认）和 **Google
 
 ### Option B：SMTP relay（内网/自部署）
 
-适合内网无法访问 `api.resend.com`，或者已经有内部邮件中继（Exchange、Postfix、自部署 SendGrid 等）的场景。同时设置时 `SMTP_HOST` 优先级高于 `RESEND_API_KEY`。
+适合内网无法访问 `api.resend.com`，或者已经有内部邮件中继（Microsoft Exchange、Postfix、自部署 SendGrid 等）的场景。同时设置时 `SMTP_HOST` 优先级高于 `RESEND_API_KEY`：只要 `SMTP_HOST` 非空，server 一律走 SMTP 路径，即便 `RESEND_API_KEY` 也配着，验证码和邀请邮件也不会经过 Resend 外发出内网。
+
+SMTP 路径覆盖大多数本地邮件服务器（特别是 Microsoft Exchange 的 receive connector）暴露的三种 relay 模式：
+
+| 模式 | 端口 | 认证 | TLS |
+|---|---|---|---|
+| 匿名内部 relay | `25` | 无 —— 按 IP / 子网信任 | 链路上无 TLS（仅限内网段） |
+| 认证提交（submission） | `587` | `SMTP_USERNAME` + `SMTP_PASSWORD` | STARTTLS，自动升级 |
+| 隐式 TLS（SMTPS） | `465` | 可选（`SMTP_USERNAME` + `SMTP_PASSWORD`） | 连上即 TLS 握手 —— 端口 `465` 自动启用；非标准端口设 `SMTP_TLS=implicit` 强制开启 |
+
+**匿名 Exchange relay，端口 25** —— 经典的 "internal SMTP relay" / Exchange 匿名 receive connector，按可信子网放行，不要求凭据：
 
 ```bash
-SMTP_HOST=smtp.internal.example.com
-SMTP_PORT=587                  # 默认 25；STARTTLS 提交端口用 587
-SMTP_USERNAME=multica          # 留空则使用未认证 relay
-SMTP_PASSWORD=...
-SMTP_TLS_INSECURE=false        # 仅在私有 CA / 自签证书时改成 true
+SMTP_HOST=exchange.internal.example.com
+SMTP_PORT=25
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_TLS_INSECURE=false
 RESEND_FROM_EMAIL=noreply@yourdomain.com  # 同时作为 SMTP From: 头
 ```
 
-服务端 advertise STARTTLS 时会自动升级。**暂不支持** 465（SMTPS / 隐式 TLS），请使用 25 或 587。
+**认证提交，端口 587** —— 需要 service account 的 relay；服务端 advertise STARTTLS 时会自动升级：
+
+```bash
+SMTP_HOST=smtp.internal.example.com
+SMTP_PORT=587
+SMTP_USERNAME=multica
+SMTP_PASSWORD=...
+SMTP_TLS_INSECURE=false        # 仅在私有 CA / 自签证书时改成 true
+RESEND_FROM_EMAIL=noreply@yourdomain.com
+```
+
+**隐式 TLS（SMTPS），端口 465** —— 适用于只提供 SMTPS、不广告 STARTTLS 的服务商（例如阿里云 / 腾讯企业邮箱）。端口 `465` 会自动启用隐式 TLS；非标准 SMTPS 端口设置 `SMTP_TLS=implicit`（别名：`smtps`、`ssl`）即可强制开启：
+
+```bash
+SMTP_HOST=smtp.qiye.aliyun.com
+SMTP_PORT=465                  # 465 自动启用隐式 TLS
+SMTP_USERNAME=multica@yourdomain.com
+SMTP_PASSWORD=...
+SMTP_TLS=implicit              # 465 上可省略；在非标准 SMTPS 端口上必填
+RESEND_FROM_EMAIL=noreply@yourdomain.com
+```
+
+启动时 server 会打印当前选择的 provider 和协商出的 TLS 模式，比如 `EmailService: SMTP relay exchange.internal.example.com:25 (starttls) from=noreply@example.com` 或 `… smtp.qiye.aliyun.com:465 (implicit-tls) from=…`（或 `Resend API` / `DEV mode`），密码不会出现在日志里。重启后没看到 SMTP 这行，说明 `SMTP_HOST` 没进到进程，确认下容器环境（`docker compose -f docker-compose.selfhost.yml exec backend env | grep SMTP`）。
 
 **两种都不配**：server 不报错，但所有本该发出去的邮件**只打到 server 的 stdout**。本地开发方便（你从日志抄验证码），生产环境等于黑洞。
 

apps/docs/content/docs/auth-tokens.ko.mdx

@@ -0,0 +1,80 @@
+---
+title: 인증과 토큰
+description: Multica에는 세 종류의 토큰이 있습니다 — 브라우저, CLI, 데몬에 각각 하나씩. 어떤 상황에 무엇을 쓰는지 설명합니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+Multica에는 세 종류의 토큰이 있으며, 각각 하나의 컨텍스트에 대응합니다: 브라우저 Web UI, 명령줄과 스크립트, 그리고 데몬입니다. 세 가지 모두 동일한 당신을 나타내지만, 범위와 수명이 다릅니다.
+
+## 세 가지 토큰
+
+| 토큰 | 형식 | 사용되는 곳 | 수명 |
+|---|---|---|---|
+| **JWT 쿠키** | `multica_auth` 쿠키 (HttpOnly) | 웹 브라우저 | 30일 |
+| **개인 액세스 토큰 (PAT)** | `mul_` 접두사 | CLI, 스크립트, 직접 API 호출 | 기본적으로 만료 없음. API로 생성할 때 `expires_in_days`를 전달할 수 있습니다 |
+| **데몬 토큰** | `mdt_` 접두사 | 데몬-서버 통신 | 데몬 자체가 관리 |
+
+일상적인 사용에서는 앞의 두 가지만 직접 다루게 됩니다. **[데몬](/daemon-runtimes) 토큰**은 `multica daemon login`이 자동으로 생성하고 갱신하므로, 신경 쓸 필요가 없습니다.
+
+## 각 토큰이 접근할 수 있는 것
+
+| API 라우트 | JWT 쿠키 | PAT | 데몬 토큰 |
+|---|---|---|---|
+| `/api/user/*` (사용자 수준 작업) | ✓ | ✓ | ✗ |
+| `/api/workspaces/:id/*` (워크스페이스 수준) | ✓ | ✓ | ✗ |
+| `/api/daemon/*` (데몬 전용) | ✗ | ✓ | ✓ |
+| WebSocket `/ws` (실시간 푸시) | ✓ (쿠키) | ✓ (첫 메시지로 인증) | ✗ |
+
+**PAT는 거의 모든 것에 접근할 수 있습니다** — 이는 "완전한 당신"을 나타냅니다. 데몬 토큰은 데몬에 필요한 일, 즉 작업을 가져오고 결과를 보고하는 것만 할 수 있습니다.
+
+**둘 다 `/api/daemon/*`에 접근할 수 있지만, 범위가 다릅니다.** PAT는 **사용자 전체**를 나타내며 — 일단 인증되면 당신이 속한 모든 워크스페이스를 볼 수 있습니다. 데몬 토큰은 생성 시점에 단일 워크스페이스에 고정되며 해당 워크스페이스의 리소스에만 접근할 수 있습니다. 프로덕션에서는 데몬을 데몬 토큰으로 실행하세요. 편의를 위해 PAT를 사용하는 지름길을 택하지 마세요. 그렇지 않으면 데몬에 필요한 것보다 훨씬 많은 권한을 부여하게 됩니다.
+
+## 로그인
+
+### Email + 인증 코드
+
+1. 이메일을 입력하면 서버가 6자리 코드를 보냅니다.
+2. 코드를 입력하면 서버가 JWT 쿠키를 발급(브라우저)하거나 PAT로 교환(CLI)합니다.
+
+<Callout type="warning">
+**자체 호스팅 운영자는 주의하세요**: 공개 배포에서는 `MULTICA_DEV_VERIFICATION_CODE`를 비워 두세요. 고정된 로컬 테스트 코드를 활성화하면, `APP_ENV`가 production이 아닌 동안 코드를 요청할 수 있는 누구나 그 값으로 로그인할 수 있습니다. [자체 호스팅 인증 구성](/auth-setup)을 참고하세요.
+</Callout>
+
+### Google OAuth
+
+**Sign in with Google**을 클릭하고 표준 OAuth 콜백을 거치세요. 자체 호스팅에는 `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, 그리고 리디렉션 URI를 구성해야 합니다 — [자체 호스팅 인증 구성](/auth-setup)을 참고하세요.
+
+## PAT 생성, 조회, 취소
+
+PAT **생성**은 두 가지 방법으로 할 수 있습니다:
+
+- **Web UI**: 설정 → API 토큰 → 새 토큰
+- **CLI**: `multica login`은 아직 로컬 PAT가 없으면 자동으로 하나를 생성합니다
+
+<Callout type="warning">
+**전체 PAT는 생성될 때 정확히 한 번만 표시됩니다.** 새로 고침하거나 대화상자를 닫은 후에는 다시 볼 수 없습니다.
+
+Multica는 데이터베이스에 PAT의 해시만 저장합니다 — 서버조차 원본을 가져올 수 없습니다. 즉시 복사하여 저장하세요. 분실하면 유일한 방법은 취소하고 새로 생성하는 것입니다.
+</Callout>
+
+기존 PAT **조회**(이름, 생성 시각, 마지막 사용 시각 — 전체 토큰은 **포함하지 않음**)는 설정 → API 토큰에 있습니다.
+
+PAT **취소**: 목록에서 Revoke를 클릭하세요. 취소는 즉시 적용됩니다 — 그 PAT로 보낸 다음 요청은 401로 거부됩니다.
+
+## 로그아웃은 로컬 토큰만 삭제합니다
+
+`multica auth logout`을 실행하거나 Web UI에서 로그아웃을 클릭하면:
+
+- **로컬 토큰이 지워집니다** — CLI는 `~/.multica/config.json`에서 PAT를 제거하고, 브라우저는 쿠키를 삭제합니다.
+- **PAT는 서버에서 여전히 유효합니다** — 로그아웃하기 전에 누군가 당신의 PAT를 입수했다면(예를 들어 다른 기기에 복사했다면), 그들은 **여전히 그것을 사용할 수 있습니다**.
+
+<Callout type="warning">
+**PAT가 유출되었다고 의심되면, 단순히 로그아웃하지 마세요.** 설정 → API 토큰로 가서 그 토큰을 **취소**하세요. 취소만이 유출된 토큰을 즉시 무효화합니다.
+</Callout>
+
+## 다음 단계
+
+- [CLI 명령어 레퍼런스](/cli) — 모든 CLI 명령어의 인증은 자동입니다
+- [자체 호스팅 인증 구성](/auth-setup) — 자체 호스팅 시 이메일, OAuth, 가입 허용 목록을 구성하는 방법
+- [데몬과 런타임](/daemon-runtimes) — 데몬 토큰이 어디서 오는지

apps/docs/content/docs/autopilots.ko.mdx

@@ -0,0 +1,239 @@
+---
+title: 오토파일럿
+description: 에이전트가 cron 스케줄, 인바운드 webhook으로 작업을 시작하거나, UI나 CLI로 한 번 수동 트리거하게 합니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+오토파일럿은 [에이전트](/agents)가 **스케줄에 따라 자동으로 작업을 시작**하게 합니다 — cron 표현식과 타임존을 설정하면, 여러분이 아무것도 트리거하지 않아도 Multica가 알아서 [`task`](/tasks)를 디스패치합니다. 정기 점검, 반복 보고서, 야간 정리 작업 등 "상시 지시(standing order)" 형태의 작업에 잘 맞습니다. 나머지 세 가지 트리거 경로([할당](/assigning-issues), [@-멘션](/mentioning-agents), [채팅](/chat) — 모두 여러분이 직접 시작하는 방식)와 비교했을 때, 오토파일럿의 핵심 차이는 **시간 기반**이라는 점입니다.
+
+## 오토파일럿 구성하기
+
+워크스페이스의 **오토파일럿** 페이지에서 새 오토파일럿을 만듭니다. 다음 항목을 설정합니다.
+
+- **이름(Name)** — 표시 이름
+- **에이전트(Agent)** — 실행을 디스패치할 대상
+- **우선순위(Priority)** — 생성되는 `task`에 상속됩니다(이슈 우선순위와 동일한 의미)
+- **설명 / 프롬프트(Description / prompt)** — 매 실행마다 에이전트가 받는 작업 설명
+- **실행 모드(Execution mode)** — 아래 참고
+- **트리거(Triggers)** — `schedule`(cron + 타임존) 또는 `webhook` 중 최소 하나
+
+## 실행 모드 선택하기
+
+오토파일럿에는 두 가지 실행 모드가 있습니다. **"이슈 생성" 모드부터 시작하세요.**
+
+- **이슈 생성 모드(Create issue mode)**(`create_issue`) — 기본값이며 **권장**됩니다. 각 트리거는 먼저 워크스페이스에 이슈를 생성한 다음(제목에는 현재 단일 플레이스홀더 `{{date}}` 하나만 지원되며, 이는 `YYYY-MM-DD` 형식의 UTC 날짜로 보간됩니다. 그 외의 `{{...}}` 토큰은 생성 시점에 거부되므로, 오타가 이슈 제목에 리터럴 문자열로 조용히 들어가는 일을 막습니다), 일반 할당 흐름을 통해 그 이슈를 에이전트에게 할당합니다. 모든 작업은 수동으로 할당한 이슈와 동일한 히스토리, 댓글, 상태를 가진 채 이슈 보드에 올라갑니다.
+- **실행 전용 모드(Run-only mode)**(`run_only`) — 이슈 생성을 건너뛰고 `task`를 곧바로 대기열에 넣습니다. 이 실행은 보드에 표시되지 않으며 — 오토파일럿의 실행 히스토리에서만 확인할 수 있습니다.
+
+## 스케줄에 따라 실행하기
+
+모든 오토파일럿에는 최소 하나의 `schedule` 트리거가 필요합니다. Cron은 **표준 5필드 형식**(분 시 일 월 요일)을 사용하며, 최소 단위는 **1분**입니다(초 단위는 없음). 타임존은 IANA 형식(예: `Asia/Shanghai`)이며, cron 표현식이 어느 타임존으로 해석될지를 결정합니다.
+
+몇 가지 예시입니다.
+
+- `0 9 * * 1-5`, `Asia/Shanghai` — 평일 베이징 시간 오전 9시
+- `*/30 * * * *`, `UTC` — 30분마다
+- `0 3 * * *`, `UTC` — 매일 UTC 오전 3시
+
+Multica 서버는 **30초**마다 만료된 트리거를 스캔합니다 — **실제 발화 시각은 최대 30초까지 지연될 수 있으며**, 초 단위로 정확하지는 않습니다. 발화 시각 즈음에 서버가 재시작되면, 시작 시 놓친 트리거를 따라잡습니다(아무것도 유실되지 않지만 즉시 발화됩니다).
+
+## 수동으로 한 번 트리거하기
+
+오토파일럿을 디버깅하는 동안 cron을 기다리지 않으려면 수동으로 트리거하세요.
+
+- UI: 오토파일럿 상세 페이지에서 "Run now" 클릭
+- CLI:
+
+```bash
+multica autopilot trigger <autopilot-id>
+```
+
+수동 트리거는 `schedule` 트리거와 완전히 동일한 실행 흐름을 거치며 — 실행 레코드의 `source` 필드만 `manual`로 표시됩니다.
+
+## Webhook으로 트리거하기
+
+오토파일럿은 인바운드 HTTP webhook으로도 발화할 수 있습니다. 오토파일럿 상세 페이지에서 **Webhook** 트리거를 추가하면, Multica가 다음과 같은 형태의 고유 URL을 생성합니다.
+
+```
+https://<your-multica-host>/api/webhooks/autopilots/awt_…
+```
+
+그 URL로 아무 JSON이나 POST하세요 — Multica는 `source = webhook`로 실행을 기록하고, 본문을 실행의 `trigger_payload`로 저장한 다음, schedule 트리거와 정확히 동일한 방식으로 에이전트를 디스패치합니다.
+
+```bash
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H "Content-Type: application/json" \
+  -d '{"event":"demo.received","eventPayload":{"message":"hello"}}'
+```
+
+**이슈 생성 모드**에서는 인바운드 payload가 새 이슈의 설명에 덧붙여져 에이전트가 인라인으로 읽을 수 있습니다. **실행 전용 모드**에서는 payload가 데몬이 에이전트에게 넘기는 실행 컨텍스트의 일부가 됩니다.
+
+### Payload 형태
+
+직접 만든 봉투(envelope)를 보낼 수 있습니다.
+
+```json
+{ "event": "github.pull_request.opened", "eventPayload": { } }
+```
+
+…또는 임의의 JSON 객체/배열을 보낼 수도 있습니다. Multica는 이를 내부 봉투로 정규화합니다.
+
+```json
+{
+  "event": "<inferred>",
+  "eventPayload": <your body>,
+  "request": { "receivedAt": "<rfc3339>", "contentType": "application/json" }
+}
+```
+
+`event` 필드를 제공하지 않으면, Multica는 일반적인 헤더와 본문 필드로부터 이를 추론합니다(`X-GitHub-Event` + 본문 `action`, `X-Gitlab-Event`, `X-Event-Type`, 본문의 `event`/`type`/`action`). 어느 것도 일치하지 않으면 이벤트는 `webhook.received`가 됩니다.
+
+GitHub 같은 소스를 구성할 때는 content type을 `application/json`으로 설정하세요 — 폼 인코딩된 webhook payload는 허용되지 않습니다.
+
+### 이벤트 필터
+
+새 webhook 트리거는 인바운드 POST마다 발화합니다. 단일 용도 URL에는 괜찮지만, 여러 이벤트 타입을 팬아웃하는 소스(GitHub가 대표적입니다 — 단일 저장소 webhook 하나가 `push`, `pull_request`, `workflow_run`, `check_suite` 등을 전달할 수 있습니다)에는 시끄럽습니다. webhook 트리거의 **이벤트 필터(Event filters)** 섹션을 사용하면 실제로 실행을 디스패치할 이벤트를 제한할 수 있으며, 그 외의 모든 것은 `status = ignored`, `reason = event_filtered`로 전달 히스토리에 기록되고 실행이나 이슈는 생성되지 않습니다.
+
+각 행은 하나의 규칙입니다. **이벤트 이름(event name)**과 선택적으로 쉼표로 구분한 **action** 목록으로 구성됩니다. Multica는 **어느 한** 행이라도 일치하면 webhook을 허용합니다. 섹션을 비워 두면 모든 것을 수락합니다(필터링 이전 동작).
+
+예시:
+
+| 이벤트 이름     | Actions             | 일치 대상                                                                  |
+| -------------- | ------------------- | ------------------------------------------------------------------------ |
+| `workflow_run` | `completed, failed` | `action: completed` 또는 `action: failed`인 `workflow_run` 이벤트만        |
+| `workflow_run` | _(비어 있음)_         | action에 상관없이 모든 `workflow_run` 이벤트                                |
+| `push`         | _(비어 있음)_         | 모든 `push` 이벤트                                                          |
+
+#### 이벤트 이름과 action의 출처
+
+Multica는 다음 순서로 인바운드 요청에서 `event` 이름과 `action`을 도출하며 — **첫 번째로 일치하는 것이 우선합니다**.
+
+**1. 본문 봉투(Body envelope).** 본문이 문자열 `event` 필드를 가진 JSON 객체이면, 그 값이 곧 이벤트 이름입니다. 선택적인 `eventPayload` 객체는 자신의 `action` / `state` / `conclusion` / `status` 필드에서 action 후보를 제공합니다.
+
+```bash
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'Content-Type: application/json' \
+  -d '{"event":"trigger","eventPayload":{"action":"true"}}'
+# inferred: event = trigger, action candidate = true
+```
+
+**2. 헤더(Headers).** 본문 봉투가 없을 때, Multica는 다음의 잘 알려진 제공자 헤더를 읽습니다.
+
+- `X-GitHub-Event: <event>` — (있는 경우) 최상위 본문 `action` 필드와 결합해 `github.<event>.<action>`을 형성합니다.
+- `X-Gitlab-Event: <event>` — `gitlab.<event>`가 됩니다.
+- `X-Event-Type: <event>` — 그대로 통과합니다.
+
+```bash
+# GitHub-style: header gives the event name, body gives the action.
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'X-GitHub-Event: workflow_run' \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"completed"}'
+# inferred: event = github.workflow_run.completed
+#        → matches a filter row of workflow_run / completed
+
+# Generic event-type header — no body fields needed.
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'X-Event-Type: trigger.true' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+# inferred: event = trigger.true → matches trigger / true
+```
+
+**3. 본문 폴백(Body fallback).** 본문 봉투도 알려진 헤더도 없으면, Multica는 다음 순서로 최상위 본문 문자열 필드로 폴백합니다: `event` → `type` → `action`.
+
+```bash
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'Content-Type: application/json' \
+  -d '{"type":"trigger","action":"true"}'
+# inferred: event = trigger (from `type`), action candidate = true
+```
+
+**4. 기본값(Default).** 위 어느 것도 일치하지 않으면, 이벤트는 `webhook.received`이고 action 후보는 없습니다.
+
+**action 후보, 전체 목록.** 이벤트가 결정되면, Multica는 아래의 모든 값을 가능한 action 일치 대상으로 고려합니다.
+
+- 이벤트가 `provider.event.<action>` 형태일 때의 이벤트 이름 접미사(예: `github.workflow_run.completed` → `completed`).
+- 본문 필드 `action`, `state`, `conclusion`, `status` — **JSON 문자열일 때만 해당됩니다**. 불리언(`{"action": true}`)이나 숫자는 자격이 없으므로, `event=trigger, action=true`를 기대하는 필터는 `{"trigger": true}` 본문과 절대 일치하지 않습니다. `true`는 문자열이 아니라 bool이기 때문입니다.
+
+**흔한 함정.** `Event name: trigger` / `Actions: true` 같은 필터 행은 "본문에 `trigger: true`가 있으면 발화하라"는 뜻이 **아닙니다** — 이벤트 필터는 임의의 본문 필드가 아니라 *추론된 이벤트와 action*에 일치시킵니다. 이를 적중시키려면 `X-Event-Type`로 `trigger.true`를 보내거나(또는 위에 표시된 본문 봉투를 사용하세요). 저장된 필터 행에서 주변 공백(`" workflow_run "`)은 그대로 저장되어 절대 일치하지 않으므로 — 저장하기 전에 trim하세요.
+
+#### 빠른 테스트
+
+필터를 구성한 후에는 `curl`로 두 분기를 모두 확인할 수 있습니다.
+
+```bash
+# Allowed — header drives event=workflow_run, body drives action=completed
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'X-GitHub-Event: workflow_run' \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"completed"}'
+# → 200 {"status":"accepted", ...}
+
+# Filtered — same event, action not in allowlist
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'X-GitHub-Event: workflow_run' \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"in_progress"}'
+# → 200 {"status":"ignored","reason":"event_filtered"}
+```
+
+### URL은 bearer secret입니다
+
+생성된 URL **자체가** 자격 증명입니다. 그것을 가진 사람은 누구나 오토파일럿을 발화할 수 있습니다. 토큰처럼 다루세요.
+
+- **공개된 이슈 스레드, 스크린샷, 채팅 히스토리에 붙여넣지 마세요.**
+- **유출되면 교체하세요** — 트리거 행에서 "Rotate URL"을 클릭하거나 `multica autopilot trigger-rotate-url <autopilot-id> <trigger-id>`를 실행하세요. 기존 URL은 즉시 작동을 멈춥니다.
+- 강력한 소스 인증이 필요한 소스의 경우, 트리거별 HMAC 서명 검증을 기다리세요. 이 v1 URL은 bearer 방식만 지원합니다.
+- 현재로서는 오토파일럿을 볼 수 있는 워크스페이스 멤버라면 그 webhook URL을 읽을 수 있습니다 — 역할별로 더 엄격한 secret 가시성은 후속 작업입니다.
+
+### 상태 코드 의미
+
+Multica는 정상적인 no-op 결과에 대해 `status` 필드와 함께 `200 OK`를 반환하므로, 제공자의 webhook 재시도 메커니즘이 URL을 계속 두드리지 않습니다.
+
+- `{"status":"accepted","run_id":"…","autopilot_id":"…","trigger_id":"…"}` — 실행이 디스패치되었습니다.
+- `{"status":"skipped","run_id":"…","reason":"agent runtime is offline at dispatch time"}` — 수신 대상의 런타임이 오프라인이며, `skipped` 실행으로 기록됩니다.
+- `{"status":"ignored","reason":"trigger_disabled"}` — 트리거가 비활성화되어 있습니다.
+- `{"status":"ignored","reason":"autopilot_paused"}` — 오토파일럿이 일시 정지되어 있습니다.
+- `{"status":"ignored","reason":"autopilot_archived"}` — 오토파일럿이 보관되어 있습니다.
+
+2xx가 아닌 응답은 실제 실패를 다룹니다.
+
+- `400` — 유효하지 않은 JSON, 스칼라 본문, 빈 본문.
+- `404` — 알 수 없는 토큰(`{"error":"webhook not found"}`).
+- `413` — payload가 256 KiB를 초과했습니다.
+- `429` — 토큰별 속도 제한 초과(기본값 60 req/min).
+
+### 자체 호스팅: 공개 URL 구성하기
+
+서버에 `MULTICA_PUBLIC_URL`이 설정되어 있으면(예: `https://multica.example.com`), 트리거 응답에 절대 경로 `webhook_url`이 포함되고 UI에는 복사 가능한 URL이 바로 표시됩니다. 설정하지 않으면 UI는 클라이언트의 API origin으로부터 URL을 구성합니다 — 데스크톱과 동일 출처 웹에는 괜찮지만, 커스텀 자체 호스팅 리버스 프록시에는 적합하지 않습니다. Multica는 잘못 구성된 리버스 프록시가 공격자가 제어하는 호스트를 가리키는 webhook URL을 서버가 발행하도록 속이지 못하게, `Host` / `X-Forwarded-Host` 헤더로부터 공개 호스트를 도출하지 않도록 의도적으로 설계되었습니다.
+
+## 실행 히스토리 보기
+
+모든 트리거는 **실행 레코드(run record)**를 생성하며, 오토파일럿 상세 페이지의 "History" 탭에서 볼 수 있습니다.
+
+- 트리거 소스(`schedule` / `manual` / `webhook`)
+- 시작 시각, 완료 시각
+- 상태(`issue_created` / `running` / `completed` / `failed` / `skipped`)
+- 연결된 이슈(이슈 생성 모드) 또는 `task`(실행 전용 모드)
+- 실패 사유(실패하거나 건너뛴 경우)
+
+## 오토파일럿이 실패하면 어떻게 되나요
+
+<Callout type="warning">
+**오토파일럿 실패는 자동으로 재시도되지 않으며 인박스 알림도 보내지 않습니다.** 실패는 실행 히스토리에 `failed` 항목을 남길 뿐 — 할당이나 @-멘션처럼 시스템 수준에서 다시 대기열에 넣는 일도 없고, 누구에게도 알림이 가지 않습니다. 오토파일럿이 주기적이라면 **다음 cron 발화가 새 실행을 트리거**하지만, 실패한 작업이 자동으로 다시 실행되지는 않습니다.
+
+오토파일럿이 중요하다면 직접 모니터링을 설계하세요 — 예를 들어 에이전트가 성공 시 댓글을 남기게 하고, 댓글이 누락된 것을 알아채 실패를 잡아내는 식입니다.
+</Callout>
+
+자동 재시도가 없는 이유: 오토파일럿은 이미 주기적이므로, 시스템 수준의 재시도를 추가하면 다음 예약된 실행 위에 겹쳐 중복 실행을 만들어 냅니다. 스케줄링을 전적으로 cron에 맡기면 깔끔하게 유지됩니다.
+
+## 아직 제공되지 않는 기능
+
+**API 종류의 트리거는 아직 연결되어 있지 않습니다.** 트리거 스키마는 `api` 종류를 예약해 두었지만, 그것을 발화하는 인그레스 라우트가 없습니다. UI는 기존 행에 Deprecated 배지를 표시하며 복사/교체 기능을 제공하지 않습니다. 트리거별 HMAC 서명 검증, IP 허용 목록, 제공자별 이벤트 프리셋은 후속 작업으로 추적되고 있으며, v1 URL은 bearer 방식만 지원합니다.
+
+## 다음
+
+- [**에이전트에게 이슈 할당하기**](/assigning-issues) — 이슈를 에이전트에게 일회성으로 넘기기
+- [**댓글에서 에이전트 @-멘션하기**](/mentioning-agents) — 댓글에서 에이전트를 불러 한번 살펴보게 하기
+- [**채팅**](/chat) — 이슈 밖에서의 일대일 대화

apps/docs/content/docs/autopilots.mdx

@@ -1,6 +1,6 @@
 ---
 title: Autopilots
-description: Let agents start work on a cron schedule — or trigger once manually via the UI or CLI.
+description: Let agents start work on a cron schedule, an inbound webhook, or trigger once manually via the UI or CLI.
 ---
 
 import { Callout } from "fumadocs-ui/components/callout";
@@ -16,13 +16,13 @@ Create a new autopilot on the workspace's **Autopilot** page. You set:
 - **Priority** — inherited by the `task` it produces (same semantics as issue priority)
 - **Description / prompt** — the work description the agent receives each run
 - **Execution mode** — see below
-- **Triggers** — at least one `schedule` (cron + timezone)
+- **Triggers** — at least one `schedule` (cron + timezone) or `webhook`
 
 ## Pick an execution mode
 
 An autopilot has two execution modes. **Start with "create issue" mode.**
 
-- **Create issue mode** (`create_issue`) — default, **recommended**. Each trigger first creates an issue in the workspace (the title supports interpolation like `{{date}}`), then assigns the issue to the agent through the normal assignment flow. All work lands on the issue board with the same history, comments, and status as a manually assigned issue.
+- **Create issue mode** (`create_issue`) — default, **recommended**. Each trigger first creates an issue in the workspace (the title currently supports a single placeholder, `{{date}}`, which interpolates to the UTC date in `YYYY-MM-DD` format; any other `{{...}}` token is rejected at create-time so a typo cannot silently land as the literal string in your issue titles), then assigns the issue to the agent through the normal assignment flow. All work lands on the issue board with the same history, comments, and status as a manually assigned issue.
 - **Run-only mode** (`run_only`) — skips issue creation and enqueues a `task` directly. The run is invisible on the board — you can only see it in the autopilot's run history.
 
 ## Run it on a schedule
@@ -50,15 +50,229 @@ multica autopilot trigger <autopilot-id>
 
 A manual trigger goes through the exact same execution flow as a `schedule` trigger — only the `source` field on the run record is marked `manual`.
 
+## Trigger from a webhook
+
+Autopilots can also fire on inbound HTTP webhooks. Add a **Webhook** trigger
+on the autopilot detail page; Multica generates a unique URL of the shape:
+
+```
+https://<your-multica-host>/api/webhooks/autopilots/awt_…
+```
+
+POST any JSON to that URL — Multica records a run with `source = webhook`,
+stores the body as the run's `trigger_payload`, and dispatches the agent
+exactly the way a schedule trigger would.
+
+```bash
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H "Content-Type: application/json" \
+  -d '{"event":"demo.received","eventPayload":{"message":"hello"}}'
+```
+
+In **create issue mode**, the inbound payload is appended to the new issue's
+description so the agent can read it inline. In **run-only mode**, the
+payload is part of the run context the daemon hands the agent.
+
+### Payload shape
+
+You can send your own envelope:
+
+```json
+{ "event": "github.pull_request.opened", "eventPayload": { } }
+```
+
+…or any JSON object/array. Multica normalizes it into an internal envelope:
+
+```json
+{
+  "event": "<inferred>",
+  "eventPayload": <your body>,
+  "request": { "receivedAt": "<rfc3339>", "contentType": "application/json" }
+}
+```
+
+When you don't provide an `event` field, Multica infers it from common
+headers and body fields (`X-GitHub-Event` + body `action`,
+`X-Gitlab-Event`, `X-Event-Type`, body `event`/`type`/`action`). When
+nothing matches, the event is `webhook.received`.
+
+When configuring GitHub or similar sources, set the content type to
+`application/json` — form-encoded webhook payloads are not accepted.
+
+### Event filters
+
+A new webhook trigger fires on every inbound POST, which is fine for a
+single-purpose URL but noisy for sources that fan out many event types
+(GitHub being the obvious one — a single repo webhook can deliver
+`push`, `pull_request`, `workflow_run`, `check_suite`, and more). The
+**Event filters** section on a webhook trigger lets you restrict which
+events actually dispatch a run; everything else is recorded in delivery
+history with `status = ignored` and `reason = event_filtered`, and no
+run or issue is created.
+
+Each row is one rule: an **event name** plus an optional
+comma-separated **actions** list. Multica allows a webhook if **any**
+row matches; leave the section empty to accept everything (the
+pre-filter behavior).
+
+Examples:
+
+| Event name     | Actions             | Matches                                                                  |
+| -------------- | ------------------- | ------------------------------------------------------------------------ |
+| `workflow_run` | `completed, failed` | `workflow_run` events with `action: completed` or `action: failed` only  |
+| `workflow_run` | _(empty)_           | every `workflow_run` event, regardless of action                         |
+| `push`         | _(empty)_           | every `push` event                                                       |
+
+#### Where the event name and action come from
+
+Multica derives the `event` name and `action` from the inbound request
+in this order — **the first match wins**.
+
+**1. Body envelope.** If the body is a JSON object with a string
+`event` field, that value is the event name directly. An optional
+`eventPayload` object then supplies action candidates from its
+`action` / `state` / `conclusion` / `status` fields.
+
+```bash
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'Content-Type: application/json' \
+  -d '{"event":"trigger","eventPayload":{"action":"true"}}'
+# inferred: event = trigger, action candidate = true
+```
+
+**2. Headers.** When no body envelope is present, Multica reads the
+following well-known provider headers:
+
+- `X-GitHub-Event: <event>` — combined with the top-level body
+  `action` field (when present) to form `github.<event>.<action>`.
+- `X-Gitlab-Event: <event>` — becomes `gitlab.<event>`.
+- `X-Event-Type: <event>` — passed through verbatim.
+
+```bash
+# GitHub-style: header gives the event name, body gives the action.
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'X-GitHub-Event: workflow_run' \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"completed"}'
+# inferred: event = github.workflow_run.completed
+#        → matches a filter row of workflow_run / completed
+
+# Generic event-type header — no body fields needed.
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'X-Event-Type: trigger.true' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+# inferred: event = trigger.true → matches trigger / true
+```
+
+**3. Body fallback.** If neither a body envelope nor a known header is
+present, Multica falls back to top-level body string fields in this
+order: `event` → `type` → `action`.
+
+```bash
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'Content-Type: application/json' \
+  -d '{"type":"trigger","action":"true"}'
+# inferred: event = trigger (from `type`), action candidate = true
+```
+
+**4. Default.** If nothing above matches, the event is
+`webhook.received` and there are no action candidates.
+
+**Action candidates, in full.** Once the event is determined, Multica
+considers every value below as a possible action match:
+
+- The event-name suffix, when the event has the form
+  `provider.event.<action>` (e.g. `github.workflow_run.completed` →
+  `completed`).
+- The body fields `action`, `state`, `conclusion`, and `status` —
+  **only when they are JSON strings**. A boolean (`{"action": true}`)
+  or a number does not qualify, so a filter expecting
+  `event=trigger, action=true` will never match a body of
+  `{"trigger": true}` because `true` is a bool, not a string.
+
+**Common gotcha.** A filter row like `Event name: trigger` /
+`Actions: true` does **not** mean "fire when the body has
+`trigger: true`" — Event filters match the *inferred event and
+action*, not arbitrary body fields. Send `trigger.true` via
+`X-Event-Type` (or use the body envelope shown above) to hit it.
+Surrounding whitespace in saved filter rows (`" workflow_run "`) is
+stored verbatim and will never match — trim before saving.
+
+#### Quick test
+
+Once a filter is configured, you can confirm both branches with `curl`:
+
+```bash
+# Allowed — header drives event=workflow_run, body drives action=completed
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'X-GitHub-Event: workflow_run' \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"completed"}'
+# → 200 {"status":"accepted", ...}
+
+# Filtered — same event, action not in allowlist
+curl -X POST "$MULTICA_WEBHOOK_URL" \
+  -H 'X-GitHub-Event: workflow_run' \
+  -H 'Content-Type: application/json' \
+  -d '{"action":"in_progress"}'
+# → 200 {"status":"ignored","reason":"event_filtered"}
+```
+
+### URL is a bearer secret
+
+The generated URL **is** the credential. Anyone with it can fire the
+autopilot. Treat it like a token:
+
+- **Don't paste it into public issue threads, screenshots, or chat history.**
+- **Rotate it if it leaks** — click "Rotate URL" on the trigger row, or run
+  `multica autopilot trigger-rotate-url <autopilot-id> <trigger-id>`. The
+  old URL stops working immediately.
+- For sources that require strong source authentication, wait for
+  per-trigger HMAC signature verification; this v1 URL is bearer-only.
+- Workspace members who can view the autopilot can read its webhook URLs
+  for now — tighter per-role secret visibility is a follow-up.
+
+### Status-code semantics
+
+Multica returns `200 OK` with a `status` field for normal no-op outcomes so
+your provider's webhook-retry machinery doesn't keep hammering the URL:
+
+- `{"status":"accepted","run_id":"…","autopilot_id":"…","trigger_id":"…"}`
+  — a run was dispatched.
+- `{"status":"skipped","run_id":"…","reason":"agent runtime is offline at dispatch time"}`
+  — the assignee's runtime is offline; recorded as a `skipped` run.
+- `{"status":"ignored","reason":"trigger_disabled"}` — the trigger is disabled.
+- `{"status":"ignored","reason":"autopilot_paused"}` — the autopilot is paused.
+- `{"status":"ignored","reason":"autopilot_archived"}` — the autopilot is archived.
+
+Non-2xx responses cover real failures:
+
+- `400` — invalid JSON, scalar body, or empty body.
+- `404` — unknown token (`{"error":"webhook not found"}`).
+- `413` — payload exceeded 256 KiB.
+- `429` — per-token rate limit exceeded (defaults to 60 req/min).
+
+### Self-hosted: configure your public URL
+
+When `MULTICA_PUBLIC_URL` is set on the server (e.g. `https://multica.example.com`),
+the trigger response includes an absolute `webhook_url` and the UI shows a
+ready-to-copy URL. Without it, the UI composes the URL from the client's
+API origin — which is fine for desktop and same-origin web, but not for
+custom self-hosted reverse proxies. Multica deliberately does not derive
+the public host from `Host` / `X-Forwarded-Host` headers so a misconfigured
+reverse proxy cannot trick the server into minting webhook URLs pointing at
+an attacker-controlled host.
+
 ## View run history
 
 Every trigger produces a **run record**, visible on the "History" tab of the autopilot detail page:
 
-- Trigger source (`schedule` / `manual`)
+- Trigger source (`schedule` / `manual` / `webhook`)
 - Start time, completion time
-- Status (`issue_created` / `running` / `completed` / `failed`)
+- Status (`issue_created` / `running` / `completed` / `failed` / `skipped`)
 - The linked issue (create issue mode) or `task` (run-only mode)
-- Failure reason (if failed)
+- Failure reason (if failed or skipped)
 
 ## What happens when an autopilot fails
 
@@ -72,7 +286,11 @@ Why no auto-retry: autopilots are already periodic, so adding system-level retri
 
 ## What's not yet available
 
-**Webhook and API triggers are not available yet.** The autopilot trigger schema reserves `webhook` and `api` types, but **they are not wired up to any ingress route** — the UI can create triggers of either type, but they will not actually fire. Today, **only `schedule` and manual triggers are end-to-end usable.**
+**API-kind triggers are not wired up.** The trigger schema reserves an `api`
+kind, but no ingress route fires it; the UI shows a Deprecated badge for
+existing rows and offers no copy/rotate affordances. Per-trigger HMAC
+signature verification, IP allowlists, and provider-specific event presets
+are tracked as follow-ups; v1 URLs are bearer-only.
 
 ## Next
 

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

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

apps/docs/content/docs/chat.ko.mdx

@@ -0,0 +1,63 @@
+---
+title: 채팅
+description: 어떤 이슈에도 속하지 않는, 에이전트와의 일대일 대화 — 완전히 샌드박스화되어 있습니다. 에이전트는 이슈를 보거나 변경할 수 없으며, 다른 누구도 이 대화를 볼 수 없습니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+**채팅은 당신과 [에이전트](/agents) 사이의 일대일 대화입니다** — [이슈](/issues) 보드에서 벗어나는 것입니다. 에이전트는 어떤 이슈도 보지 못하고 어떤 이슈도 변경할 수 없으며, 대화 전체가 **완전히 비공개**입니다([워크스페이스](/workspaces) 내의 다른 누구도, admin을 포함해서, 이 대화를 볼 수 없습니다). 에이전트와 접근 방식을 논의하거나, 브레인스토밍을 하거나, 어떤 이슈에도 속하지 않는 질문을 하기에 적합합니다.
+
+## 그냥 에이전트를 @-멘션하면 안 되나요?
+
+[@-멘션](/mentioning-agents)은 에이전트를 이슈의 컨텍스트 **안으로 끌어들입니다** — 에이전트는 이슈 설명과 모든 과거 댓글을 읽고, 이슈를 변경할 수 있습니다. 채팅은 이를 뒤집습니다. **당신을 이슈 밖으로 끌어냅니다** — 에이전트는 이 단일 대화만 볼 수 있고, 어떤 이슈의 존재도 인지하지 못하며, 이슈를 수정할 진입점도 없습니다.
+
+두 가지 판단 기준:
+
+- 특정 이슈의 컨텍스트에 기반한 피드백을 원할 때 → [@-멘션](/mentioning-agents)
+- 어떤 이슈와도 무관한 주제를 논의하고 싶을 때(또는 다른 누구에게도 논의를 보이고 싶지 않을 때) → 채팅
+
+## 대화 시작하기
+
+사이드바에서 **채팅**을 열고, 에이전트를 선택한 다음, 새 대화를 시작하세요. 인터페이스는 여느 메시징 앱과 비슷합니다. 메시지를 보내면 에이전트가 답장합니다. 각 메시지는 백그라운드에서 실행을 트리거하므로(대기열에 들어간 `task`), 답장에는 몇 초가 걸릴 수 있습니다.
+
+## 채팅에서 에이전트가 할 수 있는 일과 할 수 없는 일
+
+에이전트는 대화 안에서 **완전히 샌드박스화된** 모드로 실행됩니다.
+
+**할 수 있는 일:**
+
+- 현재 메시지에 담긴 질문에 답하기
+- 구성된 [스킬](/skills)과 MCP 사용하기
+- 자신의 작업 디렉터리에서 파일 읽기 및 쓰기
+- 이슈 컨텍스트가 필요 없는 `multica` CLI 명령 호출하기(예: 기본 워크스페이스 정보 조회)
+
+**할 수 없는 일:**
+
+- **어떤 이슈도 보기** — 에이전트가 받는 프롬프트에는 이슈 ID가 없으며, `multica issue list` 같은 명령은 빈 결과를 반환합니다
+- **어떤 이슈도 변경하기** — 이슈 컨텍스트가 없으면 권한 검사에 의해 API 호출이 차단됩니다
+- **다른 대화 보기** — 대화는 완전히 격리되어 있습니다
+- **누구도, 어떤 에이전트도 @-멘션하기** — 채팅은 다른 사람에게 알릴 경로가 없는 비공개 공간입니다
+
+## 여러 턴에 걸친 컨텍스트가 보존되는 방식
+
+채팅은 **제공자 세션 재개**를 통해 여러 턴에 걸친 컨텍스트를 유지합니다 — 에이전트는 첫 답장에서 제공자 세션을 설정하고(예: Claude 세션), 그 세션 ID가 저장됩니다. 다음 메시지에서는 작업 디스패치가 그 ID를 다시 전달하므로, 에이전트는 매번 기록을 다시 읽지 않고도 **중단했던 지점부터 이어서 재개**합니다.
+
+만약 **한 턴이 실패하면**, Multica는 세션 ID를 설정했던 이전 작업(그 작업이 성공했든 실패했든)을 찾아 재개를 시도합니다 — 중간에 한 번 실패한다고 해서 대화 전체의 기억이 사라지지는 않습니다.
+
+참고: 모든 제공자가 실제로 세션 재개를 구현하는 것은 아닙니다 — 지원 현황은 [**제공자 매트릭스**](/providers)를 참고하세요.
+
+## 대화 보관하기
+
+더 이상 보고 싶지 않은 대화는 보관할 수 있습니다 — 대화 목록에서 우클릭하거나 상세 페이지의 "보관" 버튼을 사용하세요. 보관 후에는:
+
+- 대화가 활성 목록에서 사라집니다("보관됨" 보기에서 여전히 찾을 수 있습니다)
+- 과거 메시지, 세션 ID, 작업 디렉터리가 모두 보존됩니다 — 아무것도 삭제되지 않습니다
+
+<Callout type="warning">
+**보관 후에는 "복원" 버튼이 없습니다.** 현재 보관된 대화를 다시 활성 상태로 되돌리는 진입점이 없습니다. 나중에 그 스레드를 계속 이어가고 싶다면 새 대화를 시작해야 합니다. 보관된 대화의 내용을 다시 보려면 "보관됨" 보기를 열고 기록을 읽어 보세요.
+</Callout>
+
+## 다음
+
+- [**오토파일럿**](/autopilots) — 에이전트가 일정에 따라 자동으로 작업을 시작하도록 하세요
+- [**에이전트에게 이슈 할당하기**](/assigning-issues) — 주제를 이슈 보드로 다시 가져오세요

apps/docs/content/docs/cli.ko.mdx

@@ -0,0 +1,147 @@
+---
+title: CLI 명령어 레퍼런스
+description: "모든 최상위 Multica CLI 명령어를 한 페이지로 정리한 개요입니다. 전체 사용법은 `multica <command> --help`를 실행하세요."
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+Multica CLI는 Web UI에서 할 수 있는 거의 모든 작업을 그대로 제공합니다([이슈](/issues) 생성, [에이전트](/agents) 할당, [데몬](/daemon-runtimes) 시작 등). 이 페이지는 모든 최상위 명령어를 한 줄 설명과 함께 나열합니다. 전체 플래그와 예제는 `multica <command> --help`를 실행하세요.
+
+## 인증하기
+
+CLI를 처음 사용할 때 이 명령을 실행해 **개인 액세스 토큰(personal access token, PAT)**을 발급받으세요:
+
+```bash
+multica login
+```
+
+브라우저가 자동으로 열립니다. 웹 앱에서 승인하면 CLI가 PAT(`mul_` 접두사)를 `~/.multica/config.json`에 저장합니다. 이후 모든 명령은 이 PAT로 인증됩니다.
+
+<Callout type="tip">
+CI나 headless 환경에서는 브라우저 플로우를 건너뛰세요. 웹 앱의 **설정 → API 토큰**에서 PAT를 만든 뒤 `multica login --token <mul_...>`로 직접 전달하면 됩니다.
+</Callout>
+
+토큰 유형 간의 차이는 [인증과 토큰](/auth-tokens)을 참고하세요.
+
+## 인증과 설정
+
+| 명령어 | 용도 |
+|---|---|
+| `multica login` | 로그인하고 PAT 저장 |
+| `multica auth status` | 현재 로그인 상태, 사용자, 워크스페이스 표시 |
+| `multica auth logout` | 로컬 PAT 삭제 |
+| `multica setup cloud` | Multica Cloud용 원샷 설정(로그인 + 데몬 설치) |
+| `multica setup self-host` | 자체 호스팅 백엔드용 원샷 설정 |
+
+## 워크스페이스와 멤버
+
+| 명령어 | 용도 |
+|---|---|
+| `multica workspace list` | 접근할 수 있는 모든 워크스페이스 나열 |
+| `multica workspace get <slug>` | 워크스페이스 하나의 상세 정보 표시 |
+| `multica workspace member list` | 현재 워크스페이스의 멤버 나열 |
+| `multica workspace update <id> --name "..." [--description "..."] [--context "..."] [--issue-prefix "..."]` | 워크스페이스 메타데이터 업데이트(admin/owner). 긴 필드는 `--description-stdin` / `--context-stdin`을 사용할 수 있습니다. |
+
+## 이슈와 프로젝트
+
+<Callout type="info">
+`list` 계열 명령(`multica issue list`, `autopilot list`, `project list` 등)은 기본적으로 짧고 **바로 복사해 붙여 넣을 수 있는** ID를 출력합니다. 이슈는 `MUL-123` 같은 이슈 키이고, 나머지 리소스는 짧은 UUID 접두사입니다. 아래 후속 명령의 `<id>` 인자는 짧은 ID와 전체 UUID를 모두 받으므로, 일반적인 흐름은 `multica issue list` → 키 복사 → `multica issue get MUL-123`입니다. 정식 UUID가 필요할 때는 `list` 명령에 `--full-id`를 전달하세요.
+</Callout>
+
+| 명령어 | 용도 |
+|---|---|
+| `multica issue list` | 이슈 나열(복사해 붙여 넣을 수 있는 이슈 키 출력) |
+| `multica issue get <id>` | 단일 이슈 표시(이슈 키 또는 UUID를 받음) |
+| `multica issue create --title "..."` | 새 이슈 생성 |
+| `multica issue update <id> ...` | 이슈 업데이트(상태, 우선순위, 담당자 등) |
+| `multica issue assign <id> --agent <slug>` | 에이전트에게 할당(즉시 작업을 트리거) |
+| `multica issue status <id> --set <status>` | 상태 변경 단축 명령 |
+| `multica issue search <query>` | 키워드 검색 |
+| `multica issue runs <id>` | 이슈의 에이전트 실행 표시 |
+| `multica issue rerun <id>` | 이슈의 현재 에이전트 담당자에게 새 작업을 다시 큐에 넣기 |
+| `multica issue comment <id> ...` | 중첩: 댓글 보기 / 작성 |
+| `multica issue subscriber <id> ...` | 중첩: 구독 / 구독 취소 |
+| `multica project list/get/create/update/delete/status` | 프로젝트 CRUD |
+
+## 에이전트와 스킬
+
+| 명령어 | 용도 |
+|---|---|
+| `multica agent list` | 워크스페이스의 에이전트 나열 |
+| `multica agent get <slug>` | 에이전트의 구성 표시 |
+| `multica agent create ...` | 에이전트 생성 |
+| `multica agent update <slug> ...` | 에이전트 업데이트 |
+| `multica agent archive <slug>` | 보관 |
+| `multica agent restore <slug>` | 보관된 에이전트 복원 |
+| `multica agent tasks <slug>` | 에이전트의 작업 기록 표시 |
+| `multica agent skills ...` | 중첩: 스킬 연결 / 분리 |
+| `multica skill list/get/create/update/delete` | 스킬 CRUD |
+| `multica skill import ...` | GitHub, ClawHub, 또는 로컬 기기에서 스킬 가져오기 |
+| `multica skill files ...` | 중첩: 스킬의 파일 관리 |
+
+## 스쿼드
+
+| 명령어 | 용도 |
+|---|---|
+| `multica squad list` | 워크스페이스의 스쿼드 나열 |
+| `multica squad get <id>` | 단일 스쿼드 표시 |
+| `multica squad create --name "..." --leader <agent>` | 스쿼드 생성(owner / admin) |
+| `multica squad update <id> ...` | 이름, 설명, 지침, 리더, 또는 아바타 업데이트 |
+| `multica squad delete <id>` | 보관(소프트 삭제) — 할당된 이슈를 리더에게 이관 |
+| `multica squad member list/add/remove/set-role <squad-id>` | 스쿼드 멤버 관리 및 역할 직접 업데이트 |
+| `multica squad activity <issue-id> <action\|no_action\|failed> --reason "..."` | 스쿼드 리더 에이전트가 매 턴마다 평가를 기록할 때 사용 |
+
+전체 모델은 [스쿼드](/squads)를 참고하세요.
+
+## 오토파일럿
+
+| 명령어 | 용도 |
+|---|---|
+| `multica autopilot list` | 워크스페이스의 모든 오토파일럿 나열 |
+| `multica autopilot get <id>` | 단일 오토파일럿 표시 |
+| `multica autopilot create ...` | 오토파일럿 생성 |
+| `multica autopilot update <id> ...` | 업데이트 |
+| `multica autopilot delete <id>` | 삭제 |
+| `multica autopilot runs <id>` | 실행 기록 표시 |
+| `multica autopilot trigger <id>` | 수동으로 실행 트리거 |
+
+## 데몬과 런타임
+
+| 명령어 | 용도 |
+|---|---|
+| `multica daemon start` | 데몬 시작(기본은 백그라운드; `--foreground`를 추가하면 포그라운드 실행) |
+| `multica daemon stop` | 데몬 중지 |
+| `multica daemon restart` | 데몬 재시작 |
+| `multica daemon status` | 데몬의 온라인 여부와 동시 실행 수 확인 |
+| `multica daemon logs` | 데몬 로그 보기 |
+| `multica runtime list` | 현재 워크스페이스의 런타임 나열 |
+| `multica runtime usage` | 리소스 사용량 표시 |
+| `multica runtime activity` | 최근 활동 로그 |
+| `multica runtime update <id> ...` | 런타임의 구성 업데이트 |
+
+## 기타
+
+| 명령어 | 용도 |
+|---|---|
+| `multica repo checkout <url>` | 에이전트가 사용할 수 있도록 리포지토리를 로컬에 클론 |
+| `multica config` | 로컬 CLI 구성 보기 또는 편집 |
+| `multica version` | CLI 버전 출력 |
+| `multica update` | CLI를 최신 릴리스로 업그레이드 |
+| `multica attachment download <id>` | 이슈나 댓글에서 첨부 파일 다운로드 |
+
+## 전체 플래그 확인하기
+
+모든 명령은 `--help`를 지원합니다:
+
+```bash
+multica issue create --help
+multica agent update --help
+```
+
+v2에서는 각 명령마다 전용 상세 레퍼런스 페이지를 제공할 예정입니다.
+
+## 다음 단계
+
+- [인증과 토큰](/auth-tokens) — PAT vs. JWT vs. 데몬 토큰
+- [데몬과 런타임](/daemon-runtimes) — `daemon` 명령이 내부적으로 동작하는 방식
+- [에이전트 생성과 구성](/agents-create) — `multica agent create`의 모든 옵션

apps/docs/content/docs/cli.mdx

@@ -39,7 +39,7 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 |---|---|
 | `multica workspace list` | List every workspace you can access |
 | `multica workspace get <slug>` | Show details for one workspace |
-| `multica workspace members` | List members of the current workspace |
+| `multica workspace member list` | List members of the current workspace |
 | `multica workspace update <id> --name "..." [--description "..."] [--context "..."] [--issue-prefix "..."]` | Update workspace metadata (admin/owner). Long fields accept `--description-stdin` / `--context-stdin`. |
 
 ## Issues and projects
@@ -88,7 +88,7 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 | `multica squad create --name "..." --leader <agent>` | Create a squad (owner / admin) |
 | `multica squad update <id> ...` | Update name, description, instructions, leader, or avatar |
 | `multica squad delete <id>` | Archive (soft-delete) — transfers assigned issues to the leader |
-| `multica squad member list/add/remove <squad-id>` | Manage squad members |
+| `multica squad member list/add/remove/set-role <squad-id>` | Manage squad members and update roles in place |
 | `multica squad activity <issue-id> <action\|no_action\|failed> --reason "..."` | Used by squad leader agents to record an evaluation per turn |
 
 See [Squads](/squads) for the full model.

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

@@ -39,7 +39,7 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 |---|---|
 | `multica workspace list` | 列出你有权访问的所有工作区 |
 | `multica workspace get <slug>` | 查看一个工作区的详情 |
-| `multica workspace members` | 列出当前工作区的成员 |
+| `multica workspace member list` | 列出当前工作区的成员 |
 | `multica workspace update <id> --name "..." [--description "..."] [--context "..."] [--issue-prefix "..."]` | 修改 workspace 元数据（admin/owner 权限）。长文本可用 `--description-stdin` / `--context-stdin`。 |
 
 ## Issue 和 Project
@@ -88,7 +88,7 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 | `multica squad create --name "..." --leader <agent>` | 创建小队（owner / admin）|
 | `multica squad update <id> ...` | 修改名字、描述、instructions、队长、头像 |
 | `multica squad delete <id>` | 归档（软删除）—— 同时把分配给小队的 issue 转给队长 |
-| `multica squad member list/add/remove <squad-id>` | 管理小队成员 |
+| `multica squad member list/add/remove/set-role <squad-id>` | 管理小队成员并原地更新 role |
 | `multica squad activity <issue-id> <action\|no_action\|failed> --reason "..."` | 队长智能体每轮结束时调用，记录 evaluation |
 
 完整模型见 [小队](/squads)。

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

@@ -210,7 +210,7 @@ multica workspace get <workspace-id> --output json
 ### List Members
 
 ```bash
-multica workspace members <workspace-id>
+multica workspace member list <workspace-id>
 ```
 
 ### Update Workspace
@@ -267,7 +267,7 @@ multica issue create --title "Fix login bug" --description "..." --priority high
 multica issue create --title "Fix login bug" --assignee-id 5fb87ac7-23b5-4a7a-81fa-ed295a54545d
 ```
 
-Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee` / `--assignee-id`, `--parent`, `--project`, `--due-date`. 脚本里如果已经拿到了 UUID（例如来自 `multica workspace members --output json`），传 `--assignee-id <uuid>`（与 `--assignee` 互斥）以精确锁定。
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee` / `--assignee-id`, `--parent`, `--project`, `--due-date`. 脚本里如果已经拿到了 UUID（例如来自 `multica workspace member list --output json`），传 `--assignee-id <uuid>`（与 `--assignee` 互斥）以精确锁定。
 
 ### Update Issue
 

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

@@ -0,0 +1,119 @@
+---
+title: Cloud 빠른 시작
+description: 가입부터 에이전트에게 첫 작업을 할당하기까지 5분 만에.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+이 페이지는 Multica Cloud를 처음부터 끝까지 안내합니다 — **가입 → [CLI](/cli) 설치 → [데몬](/daemon-runtimes) 시작 → [에이전트](/agents) 생성 → 첫 [작업](/tasks) 할당**. 약 5분이 걸립니다.
+
+전제 조건은 하나뿐입니다: 로컬에 [AI 코딩 도구](/providers)([Antigravity](/providers#antigravity), [Claude Code](/providers#claude-code), [Codex](/providers#codex), [Cursor](/providers#cursor), [Copilot](/providers#copilot), [Gemini](/providers#gemini), [Hermes](/providers#hermes), [Kimi](/providers#kimi), [Kiro CLI](/providers#kiro-cli), [OpenCode](/providers#opencode), [OpenClaw](/providers#openclaw), [Pi](/providers#pi) 중 하나)를 이미 최소 하나는 설치해 두어야 합니다. 데몬은 시작할 때 이들을 자동으로 감지하며, 하나도 없으면 시작을 거부합니다.
+
+## 1. 계정 만들기
+
+[multica.ai](https://multica.ai)에서 가입하세요. 이메일(6자리 인증 코드) 또는 Google로 로그인할 수 있습니다.
+
+가입 후에는 (계정 이름으로 생성된) 기본 워크스페이스에 자동으로 배치됩니다. 나중에 이름을 변경하거나 새 워크스페이스를 만들 수 있습니다.
+
+## 2. Multica CLI 설치하기
+
+**macOS / Linux (Homebrew 권장)**:
+
+```bash
+brew install multica-ai/tap/multica
+```
+
+**macOS / Linux (Homebrew 없이)**:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
+```
+
+**Windows (PowerShell)**:
+
+```powershell
+irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex
+```
+
+설치를 확인하세요:
+
+```bash
+multica version
+```
+
+## 3. 로그인 + 데몬 시작하기
+
+명령어 하나로 로그인과 데몬 시작을 처리합니다:
+
+```bash
+multica setup
+```
+
+`multica setup`은 다음을 수행합니다:
+
+1. CLI가 Multica Cloud에 연결하도록 구성합니다
+2. 로그인을 위해 브라우저를 엽니다(웹과 동일한 이메일 인증 코드 / Google OAuth)
+3. 생성된 PAT를 `~/.multica/config.json`에 저장합니다
+4. **데몬을 자동으로 시작합니다** — 3초마다 작업을 폴링하고 15초마다 하트비트를 전송하기 시작합니다
+
+<Callout type="info">
+**데스크톱 앱을 사용 중이신가요?** 데스크톱 앱은 실행 시 **데몬을 자동으로 시작합니다** — `multica setup`을 직접 실행할 필요가 없습니다. [데스크톱 앱](/desktop-app)을 참고하세요.
+</Callout>
+
+데몬이 실행 중인지 확인하세요:
+
+```bash
+multica daemon status
+```
+
+`online`은 서버에 등록되었음을 의미합니다.
+
+## 4. 런타임이 온라인인지 확인하기
+
+웹 UI에서 **설정 → 런타임**으로 이동하세요. 방금 시작한 데몬이 하나 이상의 활성 런타임으로 표시되어야 합니다 — 로컬에 설치된 AI 코딩 도구당 하나씩입니다.
+
+오프라인으로 표시되더라도 당황하지 마세요 — [문제 해결 → 데몬이 서버에 연결할 수 없음](/troubleshooting#daemon-cant-connect-to-the-server)을 참고하세요.
+
+## 5. 에이전트 생성하기
+
+웹 UI에서 **설정 → 에이전트**로 이동하여 **새 에이전트**를 클릭하세요:
+
+- **이름** — 보드와 댓글에서 이 에이전트에 표시되는 이름입니다. 원하는 이름을 고르세요
+- **제공자** — 로컬에 설치한 AI 코딩 도구를 선택하세요(드롭다운에는 런타임에서 감지된 도구만 나열됩니다)
+- **모델**(선택) — 해당 도구 내부의 모델 선택(제공자에 따라 정적 목록 또는 동적 발견)
+- **지침**(선택) — 이 에이전트를 위한 시스템 프롬프트
+
+생성되면 에이전트는 워크스페이스 멤버 목록에 나타나며, 사람 멤버처럼 작업을 할당할 수 있습니다.
+
+## 6. 첫 작업 할당하기
+
+웹 UI에서 이슈를 만들거나, CLI에서 만드세요:
+
+```bash
+multica issue create --title "Add an ASCII architecture diagram to the README"
+```
+
+방금 만든 에이전트에게 이슈를 할당하세요 — 웹 UI에서 아바타를 클릭하거나, CLI를 사용하세요:
+
+```bash
+multica issue assign MUL-1 --to my-agent-name
+```
+
+`--to`는 에이전트 또는 멤버의 **이름**을 받습니다. 부분 문자열 일치도 동작합니다 — 에이전트 이름이 `my-code-reviewer`라면 `reviewer`로 해석됩니다. 워크스페이스에 이름이 겹치는 경우, 대신 `--to-id <uuid>`(`--to`와 상호 배타적)를 전달하세요. UUID는 `multica agent list --output json` 또는 `multica workspace member list --output json`으로 조회하세요.
+
+**다음으로 데몬에서 일어나는 일**:
+
+1. 3초 이내에 작업을 가져갑니다(상태가 `queued`에서 `dispatched`로 바뀝니다)
+2. 일치하는 AI 코딩 도구를 호출하여 작업을 시작합니다(상태가 `running`이 됩니다)
+3. AI가 로컬에서 작업합니다 — 코드 디렉터리를 읽고, 명령을 실행하고, 파일을 편집할 수 있습니다
+4. 완료되면 결과를 Multica로 다시 보고합니다(자동 재시도 동작 여부에 따라 상태가 `completed` 또는 `failed`가 됩니다)
+
+웹 UI는 **실시간으로**(WebSocket을 통해) 업데이트됩니다 — 새로 고침이 필요 없습니다.
+
+## 다음 단계
+
+- [데몬과 런타임](/daemon-runtimes) — 데몬이 어떻게 동작하는지와 런타임의 의미
+- [작업](/tasks) — 작업 생명주기와 재시도 규칙
+- [AI 코딩 도구 비교](/providers) — 12개 도구 간의 기능 차이
+- [데스크톱 앱](/desktop-app) — 데몬을 직접 실행하고 싶지 않은 경우
+- [자체 호스팅 빠른 시작](/self-host-quickstart) — 자체 백엔드 실행하기

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

@@ -7,7 +7,7 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 This page walks you end-to-end through Multica Cloud — **sign up → install the [CLI](/cli) → start the [daemon](/daemon-runtimes) → create an [agent](/agents) → assign your first [task](/tasks)**. Takes about 5 minutes.
 
-One prerequisite: you already have at least one [AI coding tool](/providers) installed locally ([Claude Code](/providers#claude-code), [Codex](/providers#codex), [Cursor](/providers#cursor), [Copilot](/providers#copilot), [Gemini](/providers#gemini), [Hermes](/providers#hermes), [Kimi](/providers#kimi), [Kiro CLI](/providers#kiro-cli), [OpenCode](/providers#opencode), [OpenClaw](/providers#openclaw), or [Pi](/providers#pi)). The daemon auto-detects them on startup and refuses to start if none are present.
+One prerequisite: you already have at least one [AI coding tool](/providers) installed locally ([Antigravity](/providers#antigravity), [Claude Code](/providers#claude-code), [Codex](/providers#codex), [Cursor](/providers#cursor), [Copilot](/providers#copilot), [Gemini](/providers#gemini), [Hermes](/providers#hermes), [Kimi](/providers#kimi), [Kiro CLI](/providers#kiro-cli), [OpenCode](/providers#opencode), [OpenClaw](/providers#openclaw), or [Pi](/providers#pi)). The daemon auto-detects them on startup and refuses to start if none are present.
 
 ## 1. Create an account
 
@@ -72,7 +72,7 @@ multica daemon status
 
 In the web UI, go to **Settings → Runtimes**. The daemon you just started should appear as one or more active runtimes — one per AI coding tool installed locally.
 
-If it shows as offline, don't panic — see [Troubleshooting → Daemon can't reach the server](/troubleshooting#daemon-cant-reach-the-server).
+If it shows as offline, don't panic — see [Troubleshooting → Daemon can't connect to the server](/troubleshooting#daemon-cant-connect-to-the-server).
 
 ## 5. Create an agent
 
@@ -99,7 +99,7 @@ Assign the issue to the agent you just created — click its avatar in the web U
 multica issue assign MUL-1 --to my-agent-name
 ```
 
-`--to` takes the **name** of an agent or member. A substring match works — if the agent is called `my-code-reviewer`, `reviewer` resolves to it. If your workspace has overlapping names, pass `--to-id <uuid>` instead (mutually exclusive with `--to`); look up the UUID via `multica agent list --output json` or `multica workspace members --output json`.
+`--to` takes the **name** of an agent or member. A substring match works — if the agent is called `my-code-reviewer`, `reviewer` resolves to it. 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 member list --output json`.
 
 **What happens next from the daemon**:
 
@@ -114,6 +114,6 @@ The web UI updates in **real time** (via WebSocket) — no refresh needed.
 
 - [Daemon and runtimes](/daemon-runtimes) — how the daemon operates and what runtimes mean
 - [Tasks](/tasks) — task lifecycle and retry rules
-- [AI coding tools compared](/providers) — capability differences across the 11 tools
+- [AI coding tools compared](/providers) — capability differences across the 12 tools
 - [Desktop app](/desktop-app) — if you'd rather not run the daemon yourself
 - [Self-host quickstart](/self-host-quickstart) — run your own backend

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

@@ -7,7 +7,7 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 这一页带你走一遍 Multica Cloud 的端到端流程——**注册 → 装 [命令行工具](/cli) → 启动 [守护进程](/daemon-runtimes) → 创建 [智能体](/agents) → 分配第一个 [任务](/tasks)**，约 5 分钟完成。
 
-前置只有一个：你本地已经装了至少一款 [AI 编程工具](/providers)（[Claude Code](/providers#claude-code)、[Codex](/providers#codex)、[Cursor](/providers#cursor)、[Copilot](/providers#copilot)、[Gemini](/providers#gemini)、[Hermes](/providers#hermes)、[Kimi](/providers#kimi)、[Kiro CLI](/providers#kiro-cli)、[OpenCode](/providers#opencode)、[OpenClaw](/providers#openclaw)、[Pi](/providers#pi)）中的一款。守护进程启动时会自动探测它们，没装任何一个的话守护进程会直接拒绝启动。
+前置只有一个：你本地已经装了至少一款 [AI 编程工具](/providers)（[Antigravity](/providers#antigravity)、[Claude Code](/providers#claude-code)、[Codex](/providers#codex)、[Cursor](/providers#cursor)、[Copilot](/providers#copilot)、[Gemini](/providers#gemini)、[Hermes](/providers#hermes)、[Kimi](/providers#kimi)、[Kiro CLI](/providers#kiro-cli)、[OpenCode](/providers#opencode)、[OpenClaw](/providers#openclaw)、[Pi](/providers#pi)）中的一款。守护进程启动时会自动探测它们，没装任何一个的话守护进程会直接拒绝启动。
 
 ## 1. 注册账号
 
@@ -99,7 +99,7 @@ multica issue create --title "给 README 加一段 ASCII 架构图"
 multica issue assign MUL-1 --to my-agent-name
 ```
 
-`--to` 后面填智能体或成员的**名字**，子串就行——如果智能体叫 `my-code-reviewer`，填 `reviewer` 也能命中。如果工作区里名字相互重叠或冲突，改用 `--to-id <uuid>`（与 `--to` 互斥）；UUID 来自 `multica agent list --output json` 或 `multica workspace members --output json`。
+`--to` 后面填智能体或成员的**名字**，子串就行——如果智能体叫 `my-code-reviewer`，填 `reviewer` 也能命中。如果工作区里名字相互重叠或冲突，改用 `--to-id <uuid>`（与 `--to` 互斥）；UUID 来自 `multica agent list --output json` 或 `multica workspace member list --output json`。
 
 **接下来守护进程会**：
 
@@ -114,6 +114,6 @@ Web 界面会**实时**（通过 WebSocket）显示进度——不需要刷新
 
 - [守护进程与运行时](/daemon-runtimes) —— 守护进程怎么运作、运行时概念
 - [执行任务](/tasks) —— 任务生命周期、重试规则
-- [AI 编程工具对照](/providers) —— 11 款工具的能力差异
+- [AI 编程工具对照](/providers) —— 12 款工具的能力差异
 - [桌面应用](/desktop-app) —— 不想自己跑守护进程的话
 - [Self-Host 快速上手](/self-host-quickstart) —— 在自己服务器上跑一套

apps/docs/content/docs/comments.ko.mdx

@@ -0,0 +1,81 @@
+---
+title: 댓글과 멘션
+description: 이슈 아래에서 협업하기 — 댓글, 답글, `@` 멘션, 반응, 그리고 댓글에서 에이전트를 트리거하기.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+모든 [이슈](/issues)에는 댓글 스레드가 있습니다. 댓글을 작성하고, 다른 사람에게 답글을 달고, [멤버](/members-roles)나 [에이전트](/agents)를 `@`로 멘션하고, 반응을 추가하세요 — 지금까지 써온 어떤 작업 관리 도구에서나 하던 것과 똑같은 동작입니다. 단 한 가지 다른 점은: **`@`로 에이전트를 멘션하면 에이전트가 작업을 시작하도록 트리거된다**는 것입니다.
+
+## 댓글 작성하기
+
+이슈 상세 페이지 하단의 입력란에 내용을 입력하고 **보내기**를 누르세요. 댓글이 스레드에 즉시 나타납니다. 댓글은 Markdown을 지원합니다 — 제목, 목록, 코드 블록, 링크를 모두 사용할 수 있습니다.
+
+## 댓글에 답글 달기
+
+어떤 댓글이든 오른쪽 상단의 **답글**을 클릭하면 그 아래에 중첩된 입력란이 열립니다. 작성한 답글은 해당 댓글의 하위 항목으로 표시되어 대화 스레드를 이룹니다. 답글에도 다시 답글을 달 수 있으며, 필요한 만큼 깊이 중첩됩니다.
+
+이슈 목록에는 최상위 댓글 수만 표시되며, 이슈를 열어야 전체 대화 트리를 볼 수 있습니다.
+
+## 반응
+
+각 댓글의 오른쪽 상단에는 빠른 신호를 보내기 위한 반응 버튼이 있습니다(👍, 👀, 🎉) — 동의를 표시하려고 "+1" 댓글을 따로 달 필요가 없습니다.
+
+## `@` 멘션
+
+댓글에 `@`를 입력하면 선택 창이 열립니다. 멤버나 에이전트를 고르면 `@`와 대상의 slug가 함께 삽입됩니다(`@alice` 또는 `@reviewer-bot`). 멘션된 대상은 자신의 [인박스](/inbox)에서 알림을 받습니다.
+
+**에이전트를 멘션하면 자동으로 트리거됩니다** — [댓글에서 에이전트 멘션하기](/mentioning-agents)를 참고하세요.
+
+하나의 댓글에서 같은 사람을 여러 번 멘션해도 알림은 **하나만** 발생합니다.
+
+### `@all`은 워크스페이스 전체에 알립니다
+
+`@all`은 특별한 대상입니다. 워크스페이스의 모든 멤버에게 알림을 보냅니다. 사람과 에이전트 모두 `@all`을 사용할 수 있습니다 — 즉 진행 상황을 보고하는 에이전트도 `@all`을 할 수 있으므로, 에이전트의 지침에 이를 아껴서 사용하라고 일러두세요.
+
+<Callout type="warning">
+**`@all`은 신중하게 사용하세요.** 규모가 큰 워크스페이스에서는 단 한 번의 `@all`이 그만큼의 인박스 알림을 순식간에 생성합니다. 모두가 정말로 알아야 하는 일에만 사용하고 — 일상적인 업데이트에는 쓰지 마세요.
+</Callout>
+
+## 이슈 참조하기
+
+다른 이슈를 링크하려면 `MUL-123`처럼 이슈 키를 입력하세요. Multica는 댓글에서 실제 존재하는 이슈 키를 해석하여 내부적으로 `mention://issue/<uuid>` 링크로 저장합니다. 이슈 링크는 단순한 상호 참조일 뿐입니다. 사람에게 알림을 보내지 않으며 에이전트를 트리거하지도 않습니다.
+
+보통은 `[MUL-123](mention://issue/<uuid>)`을 직접 손으로 작성할 필요가 없습니다. 그 형식은 Multica가 키를 해석한 뒤에 사용하는 표준 내부 표현입니다.
+
+<Callout type="info">
+Markdown 강조는 CommonMark 규칙을 따릅니다. 굵은 텍스트가 문장 부호나 닫는 따옴표로 끝나고 그 뒤에 한국어 조사가 바로 이어지면, 닫는 `**`가 인식되지 않을 수 있습니다.
+
+따옴표를 굵게 표시 범위 밖으로 옮기는 것을 권장합니다:
+
+```markdown
+"**무엇을 먼저 정해두고 시작할지**"가
+```
+
+다음 대신:
+
+```markdown
+**"무엇을 먼저 정해두고 시작할지"**가
+```
+</Callout>
+
+## 댓글 편집과 삭제
+
+댓글은 작성자만 편집하거나 삭제할 수 있습니다.
+
+댓글을 삭제하면 그 아래의 **모든 답글도 함께 삭제됩니다**(답글의 답글 포함). 내용만 바꾸려면 삭제 대신 편집을 사용하세요.
+
+<Callout type="warning">
+**댓글을 편집하면서 `@`를 추가해도 에이전트는 트리거되지 않습니다.** 트리거는 댓글이 **생성되는** 그 순간에 발생합니다 — 나중에 편집해서 새로운 `@`를 추가하거나 대상을 바꿔도 새 알림이 발송되지 않고 에이전트가 깨어나지도 않습니다. 놓친 에이전트를 불러오려면 그 에이전트를 `@`하는 **새 댓글을 작성**하세요.
+</Callout>
+
+---
+
+여기까지 다룬 내용은 모두 "사람의 세계"입니다 — 워크스페이스, 멤버, 이슈, 프로젝트, 댓글. Linear나 Jira를 써본 적이 있다면 지금까지의 내용은 전혀 낯설지 않을 것입니다.
+
+하지만 Multica의 결정적인 특징은 아직 등장하지 않았습니다: **에이전트를 워크스페이스의 일급 멤버로 대우하는 것**입니다. 다음 장에서 바로 이 이야기를 다룹니다.
+
+## 다음
+
+- [에이전트](/agents) — 무엇이며, 사람과 어떻게 다른지
+- [댓글에서 에이전트 멘션하기](/mentioning-agents) — 댓글에서 `@`로 에이전트를 시작시키기

apps/docs/content/docs/comments.mdx

@@ -37,6 +37,28 @@ Mentioning the same person multiple times in one comment still produces **only o
 **Use `@all` carefully.** In a larger workspace, a single `@all` generates that many inbox notifications instantly. Reserve it for things everyone genuinely needs to know — not day-to-day updates.
 </Callout>
 
+## Referencing issues
+
+To link another issue, type its issue key, such as `MUL-123`. Multica resolves real issue keys in comments and stores them as an internal `mention://issue/<uuid>` link. Issue links are cross-references only: they do not notify people and they do not trigger agents.
+
+You normally do not need to write `[MUL-123](mention://issue/<uuid>)` by hand. That format is the canonical internal representation after Multica has resolved the key.
+
+<Callout type="info">
+Markdown emphasis follows CommonMark rules. When bold text ends with punctuation or a closing quote and is immediately followed by a Korean particle, the closing `**` may not be recognized.
+
+Prefer moving the quote outside the bold span:
+
+```markdown
+"**무엇을 먼저 정해두고 시작할지**"가
+```
+
+instead of:
+
+```markdown
+**"무엇을 먼저 정해두고 시작할지"**가
+```
+</Callout>
+
 ## Editing and deleting a comment
 
 Only the author of a comment can edit or delete it.

apps/docs/content/docs/comments.zh.mdx

@@ -37,6 +37,28 @@ import { Callout } from "fumadocs-ui/components/callout";
 **谨慎使用 `@all`**。工作区人数较多时，一条 `@all` 的评论会瞬间生成同等数量的收件箱通知。只在确实需要全员知晓的重大事项上使用——不是日常琐事。
 </Callout>
 
+## 引用 issue
+
+要链接另一个 issue，直接输入它的 issue key，例如 `MUL-123`。Multica 会在评论中解析真实存在的 issue key，并把它存成内部的 `mention://issue/<uuid>` 链接。Issue 链接只是交叉引用：不会通知成员，也不会触发智能体。
+
+通常不需要手写 `[MUL-123](mention://issue/<uuid>)`。这是 Multica 解析 key 之后使用的内部规范格式。
+
+<Callout type="info">
+Markdown 加粗遵循 CommonMark 规则。当加粗文本以标点或闭引号结尾，并且后面紧跟韩语助词时，结尾的 `**` 可能不会被识别。
+
+推荐把引号放到加粗范围外：
+
+```markdown
+"**무엇을 먼저 정해두고 시작할지**"가
+```
+
+而不是：
+
+```markdown
+**"무엇을 먼저 정해두고 시작할지"**가
+```
+</Callout>
+
 ## 编辑和删除评论
 
 只有评论的作者能编辑或删除自己的评论。

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

@@ -0,0 +1,111 @@
+---
+title: 데몬과 런타임
+description: 에이전트는 Multica 서버에서 실행되지 않습니다. 여러분의 기기에서 실행됩니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+import { Mermaid } from "@/components/mermaid";
+
+Multica에서 [에이전트](/agents)는 우리 서버에서 실행되지 **않습니다**. 로컬에 설치된 [AI 코딩 도구](/providers)를 호출하는 **데몬**이라는 작은 프로그램이 구동하여, 여러분 자신의 기기에서 실행됩니다. Multica 서버는 조율만 담당합니다. [이슈](/issues)를 저장하고, [작업](/tasks)을 대기열에 넣고, 알맞은 **런타임**으로 분배합니다(런타임 = 데몬 × AI 코딩 도구 하나).
+
+이 구조가 Multica와 Linear / Jira의 가장 큰 차이점입니다. **여러분의 API 키, 툴체인, 코드 디렉터리는 모두 여러분의 기기에 남아 있으며**, Multica 서버는 그중 어느 것도 보지 못합니다. 따라서 "내 에이전트가 동작하지 않는다"는 거의 항상 로컬 문제입니다. 데몬이 실행 중이 아니거나, AI 도구가 설치되어 있지 않거나, 키가 만료되었을 수 있습니다. 먼저 로컬을 확인하세요. 안내는 [문제 해결](/troubleshooting)을 참고하세요.
+
+## 데몬 시작하기
+
+데몬은 Multica CLI의 일부입니다. [Multica CLI](/cli)를 설치한 뒤, 여러분의 기기에서 실행하세요.
+
+```bash
+multica daemon start
+```
+
+시작 시 데몬은 네 가지 일을 합니다.
+
+1. 로그인할 때 저장된 인증 정보를 읽습니다
+2. `PATH`에 설치된 AI 코딩 도구를 감지합니다(내장 12종: [Antigravity](/providers#antigravity), [Claude Code](/providers#claude-code), [Codex](/providers#codex), [Cursor](/providers#cursor), [Copilot](/providers#copilot), [Gemini](/providers#gemini), [Hermes](/providers#hermes), [Kimi](/providers#kimi), [Kiro CLI](/providers#kiro-cli), [OpenCode](/providers#opencode), [OpenClaw](/providers#openclaw), [Pi](/providers#pi))
+3. 감지된 각 도구에 대한 런타임과 함께 자신을 서버에 등록합니다
+4. **3초마다** 가져올 작업이 있는지 폴링하고, **15초마다 하트비트를 전송**합니다
+
+자주 쓰는 명령:
+
+| 명령 | 용도 |
+|---|---|
+| `multica daemon start` | 시작(기본은 백그라운드. 포그라운드로 실행하려면 `--foreground` 추가) |
+| `multica daemon stop` | 중지 |
+| `multica daemon restart` | 재시작 |
+| `multica daemon status` | 상태 표시 |
+| `multica daemon logs` | 로그 표시(따라가려면 `-f` 추가) |
+
+전체 CLI 참고는 [CLI 명령](/cli)을 확인하세요.
+
+**데스크톱 앱에는 데몬이 포함되어 있습니다.** [데스크톱 앱](/desktop-app)을 사용한다면 `multica daemon start`를 수동으로 실행할 필요가 없습니다. 시작할 때 데몬을 자동으로 띄웁니다. 여러분의 워크플로에 어떤 방식이 맞는지는 [데스크톱 앱](/desktop-app) 페이지를 참고하세요.
+
+## 한 기기에 여러 런타임이 생기는 이유
+
+런타임은 서버도 아니고 컨테이너도 아닙니다. "**데몬 × AI 코딩 도구 하나**"의 조합입니다. 예를 들어, Claude Code와 Codex가 모두 설치된 MacBook에서 데몬을 시작하고, 여러분이 두 개의 워크스페이스 멤버라고 합시다. 그러면 Multica는 4개의 런타임을 등록합니다.
+
+<Mermaid chart={`
+graph TD
+    D["여러분의 데몬<br/>MacBook"]
+    D --> R1["런타임<br/>워크스페이스 A × Claude Code"]
+    D --> R2["런타임<br/>워크스페이스 A × Codex"]
+    D --> R3["런타임<br/>워크스페이스 B × Claude Code"]
+    D --> R4["런타임<br/>워크스페이스 B × Codex"]
+`} />
+
+핵심 포인트:
+
+- **하나의 데몬은 여러 런타임에 매핑될 수 있습니다.** 설치된 도구와 가입한 워크스페이스의 조합마다 하나씩 생깁니다
+- **같은 데몬, 워크스페이스, 도구는 정확히 하나의 런타임을 만듭니다.** 데몬을 재시작해도 중복 레코드가 생기지 않습니다
+- Multica UI의 **런타임** 페이지가 이 행들을 나열합니다
+
+<Callout type="info">
+**클라우드 런타임이 곧 제공됩니다.** 현재는 대기자 명단 단계입니다. 제공이 시작되면 로컬 데몬을 실행하지 않고도 Multica Cloud에서 직접 에이전트 작업을 실행할 수 있습니다. [다운로드 페이지](https://multica.ai/download)에서 이메일로 등록하면 알림을 받을 수 있습니다.
+</Callout>
+
+## 런타임이 오프라인으로 표시되는 시점
+
+Multica는 하트비트로 런타임이 온라인인지 판단합니다. 세 가지 핵심 수치:
+
+| 이벤트 | 임곗값 |
+|---|---|
+| 데몬 하트비트 빈도 | **15초**마다 |
+| 누락으로 표시 | **45초** 동안 하트비트 없음(3회 누락) |
+| 자동 삭제 | 연결된 에이전트 없이 **7일** 넘게 누락 상태 |
+
+누락은 영구적이지 않습니다. 데몬이 다시 하트비트를 보내는 즉시 온라인으로 돌아오며, 런타임 레코드도 보존됩니다. 데몬을 재시작해도 런타임은 사라지지 않습니다.
+
+<Callout type="warning">
+**누락된 런타임에서 실행 중이던 작업은 실패로 표시됩니다**(실패 사유 `runtime_offline`). 재시도 가능한 출처(이슈, 채팅)에 대해서는 Multica가 자동으로 다시 대기열에 넣습니다. 오토파일럿이 트리거한 작업은 자동으로 재시도되지 않습니다. [작업 → 어떤 실패가 자동 재시도되는지](/tasks#which-failures-retry-automatically-which-dont)를 참고하세요.
+</Callout>
+
+## 동시에 실행할 수 있는 작업 수
+
+Multica는 두 계층에서 동시성 제한을 적용합니다.
+
+- **데몬 계층**: 기본 **동시 작업 20개**(환경 변수 `MULTICA_DAEMON_MAX_CONCURRENT_TASKS`로 조정 가능)
+- **에이전트 계층**: 기본 **에이전트당 동시 작업 6개**(에이전트별로 설정)
+
+둘 중 더 엄격한 쪽이 적용됩니다. 데몬이 이미 작업 20개를 실행 중이라면, 어떤 에이전트에 여유가 남아 있어도 새 작업은 대기합니다.
+
+작업이 `dispatched`로 넘어가지 못하고 `queued`에 멈춰 있다면, 보통 이 두 제한 중 하나가 포화 상태인 것입니다.
+
+## 데몬 충돌 후 진행 중이던 작업은 어떻게 되나
+
+데몬이 충돌하거나 강제 종료되면, 데몬이 가져갔던 작업은 `dispatched` 또는 `running` 상태에 남습니다. 다음 시작 시 데몬은 서버에 "이 작업들은 더 이상 제 것이 아니니, 실패로 표시해 주세요"라고 알립니다. 서버는 이를 사유 `runtime_recovery`와 함께 `failed`로 전환합니다. 재시도 가능한 출처에 대해서는 작업이 자동으로 다시 대기열에 들어갑니다.
+
+이 단계가 네트워크 문제로 실패하더라도, 백업으로 **30초마다** 서버 측 스캔이 돕니다. 45초 넘게 하트비트가 없는 런타임은 누락으로 표시되며, 그 위의 작업도 함께 회수됩니다.
+
+## 동작하지 않는 에이전트 문제 해결
+
+"내 에이전트가 동작하지 않는다"는 문제를 만나면, 먼저 이 세 단계 체크리스트를 진행하세요.
+
+1. `multica daemon status`를 실행해 데몬이 실행 중이고 온라인인지 확인하세요
+2. `multica daemon logs -f`를 실행해 오류가 있는지 확인하세요
+3. Multica UI의 **런타임** 페이지를 열어 런타임이 "온라인"으로 표시되는지 확인하세요
+
+더 많은 시나리오는 [문제 해결](/troubleshooting)을 참고하세요.
+
+## 다음
+
+- [작업](/tasks) — 데몬이 작업을 가져온 뒤의 전체 생애 주기
+- [제공자 대조표](/providers) — 12종 AI 코딩 도구의 기능 차이

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

@@ -21,7 +21,7 @@ multica daemon start
 On startup it does four things:
 
 1. Reads the credentials saved when you logged in
-2. Detects AI coding tools installed on your `PATH` (11 built-in: [Claude Code](/providers#claude-code), [Codex](/providers#codex), [Cursor](/providers#cursor), [Copilot](/providers#copilot), [Gemini](/providers#gemini), [Hermes](/providers#hermes), [Kimi](/providers#kimi), [Kiro CLI](/providers#kiro-cli), [OpenCode](/providers#opencode), [OpenClaw](/providers#openclaw), [Pi](/providers#pi))
+2. Detects AI coding tools installed on your `PATH` (12 built-in: [Antigravity](/providers#antigravity), [Claude Code](/providers#claude-code), [Codex](/providers#codex), [Cursor](/providers#cursor), [Copilot](/providers#copilot), [Gemini](/providers#gemini), [Hermes](/providers#hermes), [Kimi](/providers#kimi), [Kiro CLI](/providers#kiro-cli), [OpenCode](/providers#opencode), [OpenClaw](/providers#openclaw), [Pi](/providers#pi))
 3. Registers itself with the server, along with a runtime for each detected tool
 4. Keeps **polling every 3 seconds** for tasks to pick up, and **sends a heartbeat every 15 seconds**
 
@@ -108,4 +108,4 @@ More scenarios in [Troubleshooting](/troubleshooting).
 ## Next
 
 - [Tasks](/tasks) — the full lifecycle of a task once the daemon picks it up
-- [Providers Matrix](/providers) — capability differences across the 11 AI coding tools
+- [Providers Matrix](/providers) — capability differences across the 12 AI coding tools

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

@@ -21,7 +21,7 @@ multica daemon start
 启动后它会做四件事：
 
 1. 读取你登录时保存的凭证
-2. 探测本机 `PATH` 上已安装的 AI 编程工具（内置支持 11 款：[Claude Code](/providers#claude-code)、[Codex](/providers#codex)、[Cursor](/providers#cursor)、[Copilot](/providers#copilot)、[Gemini](/providers#gemini)、[Hermes](/providers#hermes)、[Kimi](/providers#kimi)、[Kiro CLI](/providers#kiro-cli)、[OpenCode](/providers#opencode)、[OpenClaw](/providers#openclaw)、[Pi](/providers#pi)）
+2. 探测本机 `PATH` 上已安装的 AI 编程工具（内置支持 12 款：[Antigravity](/providers#antigravity)、[Claude Code](/providers#claude-code)、[Codex](/providers#codex)、[Cursor](/providers#cursor)、[Copilot](/providers#copilot)、[Gemini](/providers#gemini)、[Hermes](/providers#hermes)、[Kimi](/providers#kimi)、[Kiro CLI](/providers#kiro-cli)、[OpenCode](/providers#opencode)、[OpenClaw](/providers#openclaw)、[Pi](/providers#pi)）
 3. 向服务器注册自己，以及每款检测到的工具对应的运行时
 4. 持续**每 3 秒轮询一次**是否有任务要领，**每 15 秒发一次心跳**
 
@@ -108,4 +108,4 @@ Multica 对并发有两层限额：
 ## 下一步
 
 - [执行任务](/tasks) —— 守护进程领到任务后，它的完整生命周期
-- [Providers Matrix](/providers) —— 11 款 AI 编程工具的能力差异对照
+- [Providers Matrix](/providers) —— 12 款 AI 编程工具的能力差异对照

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

@@ -0,0 +1,99 @@
+---
+title: 데스크톱 앱
+description: Multica Desktop이 무엇인지, 웹 앱과 어떻게 다른지, 언제 쓸 만한지 알아봅니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+Multica Desktop은 macOS, Windows, Linux용 네이티브 데스크톱 앱입니다. 구성된 환경에 대해 웹 앱과 동일한 백엔드에 연결되며 동일한 데이터를 보여줍니다. 기본적으로 Desktop은 Multica Cloud를 사용하며, 자체 호스팅 인스턴스는 로컬 런타임 설정 파일로 구성할 수 있습니다. Desktop은 브라우저가 할 수 없는 몇 가지 기능도 추가로 제공합니다: **[워크스페이스](/workspaces)별 독립적인 탭 그룹**, **[데몬](/daemon-runtimes) 자동 시작**, **원클릭 업그레이드**입니다.
+
+## Desktop 또는 웹 — 무엇을 선택할까
+
+| | 웹 | Desktop |
+|---|---|---|
+| 접근 방식 | 브라우저에서 URL 열기 | 네이티브 앱 설치 |
+| 다중 탭 | 브라우저 자체 탭 (워크스페이스 구분 없음) | **워크스페이스별 독립 탭 그룹 한 개** |
+| 데몬 | `multica daemon start`를 직접 실행 | 실행 시 **자동으로 시작** |
+| 업그레이드 | 새로고침하면 최신 버전 | 앱이 백그라운드에서 확인하고 다음 실행 시 설치 |
+| 로그인 후 데이터 | 동일 | 동일 |
+
+**웹을 선택**: 일회성으로 사용하거나, 다른 사람의 기기에서 작업하거나, 아무것도 설치하고 싶지 않을 때.
+**Desktop을 선택**: 매일 사용하거나, 여러 워크스페이스를 동시에 다루거나, 데몬을 수동으로 관리하고 싶지 않을 때.
+
+## 다중 탭: 워크스페이스를 전환하면 어떻게 되나
+
+Desktop은 **참여한 모든 워크스페이스**마다 독립적인 탭 그룹을 유지합니다. 워크스페이스를 전환하면 현재 워크스페이스의 탭이 하나의 단위로 숨겨지고, 이전 워크스페이스의 탭은 떠났던 그대로 복원됩니다 — VSCode의 멀티 워크스페이스 동작이나 Slack에서 워크스페이스를 전환하는 것과 비슷합니다.
+
+예시: 워크스페이스 A에서 이슈 탭 3개를 열어 둔 상태로 워크스페이스 B로 전환합니다. A의 탭 3개는 사라지고, B에는 B에서 마지막으로 열어 두었던 것이 표시됩니다. 다시 A로 전환하면 그 3개의 탭이 정확히 이전 상태 그대로 돌아옵니다. **탭은 워크스페이스 간에 절대 새어 나가지 않습니다.**
+
+로그아웃하면 **모든 워크스페이스의 탭 상태가 지워지므로**, 여러 사용자가 기기를 공유하더라도 데이터가 새어 나가지 않습니다.
+
+## Desktop의 자동 업데이트 방식
+
+실행 시 Desktop은 GitHub Releases에서 더 최신 버전이 있는지 확인합니다. 새 버전이 발견되면:
+
+1. 백그라운드에서 새 버전을 조용히 다운로드합니다.
+2. "준비 완료 — 다음 실행 시 설치됩니다"라고 알려 줍니다.
+3. 종료(또는 다음 재시작) 시, 앱이 닫히기 전에 업데이트를 설치합니다.
+4. 다음 실행 시 새 버전이 실행됩니다.
+
+이 전체 과정은 **작업 중인 내용을 방해하지 않습니다**.
+
+<Callout type="warning">
+**Windows에서는 ARM64와 x64가 별도의 업데이트 채널입니다** — 잘못된 아키텍처를 설치하면 업데이트가 감지되지 않습니다. 다운로드할 때 기기에 맞는 `.exe`를 선택하세요 (ARM 빌드에는 `arm64` 접미사가 붙어 있습니다).
+</Callout>
+
+macOS 빌드는 서명 및 공증되어 있으므로, 첫 실행 시 "확인되지 않은 개발자" 경고가 표시되지 않습니다. Linux 빌드는 `.AppImage`입니다 — 자동 업데이트는 electron-updater에 의존하는데, 일부 배포판에서는 불안정할 수 있습니다. **자동 업데이트가 작동하지 않으면, 새 버전을 수동으로 다운로드하여 기존 파일을 교체하세요.**
+
+## 별도의 CLI와 데몬이 여전히 필요한가요?
+
+**아닙니다.** Desktop에는 동일한 `multica` CLI 바이너리가 내장되어 있으며, 시작 시 자체 데몬 프로필을 실행합니다 (터미널에서 수동으로 실행 중인 데몬과는 격리됩니다).
+
+이미 CLI를 설치하고 `multica daemon start`를 직접 실행했더라도, Desktop은 그 데몬을 가로채지 않습니다 — 별도의 프로필로 자체 데몬을 시작합니다. 둘은 **서로 다른 런타임**으로 등록되며, UI에서 두 개의 독립된 런타임을 볼 수 있습니다.
+
+터미널에서 CLI 명령을 실행하고 싶다면, Desktop이 특별한 경로를 제공하지는 않습니다 — 별도로 설치한 CLI를 사용하거나, 앱의 리소스 디렉터리 안 `resources/bin/multica`에 있는 번들 사본을 실행하세요.
+
+## 다운로드 및 설치
+
+[Multica 다운로드 페이지](https://multica.ai/download)에서 사용하는 플랫폼의 설치 프로그램을 받으세요:
+
+| 플랫폼 | 파일 |
+|---|---|
+| macOS (Intel 또는 Apple Silicon) | `.dmg` |
+| Windows x64 | `.exe` (표준) |
+| Windows ARM64 | `.exe` (`arm64` 접미사 포함) |
+| Linux | `.AppImage` |
+
+첫 실행 시 로그인이 필요합니다 — 웹 앱과 동일한 이메일 + 인증 코드 흐름입니다. 로그인하면 Desktop이 워크스페이스 목록을 자동으로 동기화합니다.
+
+<Callout type="info">
+**Desktop은 기본적으로 Multica Cloud를 사용하지만, 로컬 설정 파일로 자체 호스팅 인스턴스를 가리키도록 할 수 있습니다.** 앱 안에는 여전히 "자체 호스팅에 연결" 선택기가 없습니다. Desktop은 렌더러가 시작되기 전에 `~/.multica/desktop.json`을 읽습니다. 파일이 없으면 Cloud 기본값을 사용합니다.
+
+최소 자체 호스팅 설정:
+
+```json
+{
+  "schemaVersion": 1,
+  "apiUrl": "https://api.your-domain"
+}
+```
+
+`apiUrl`은 필수이며 `http` 또는 `https`를 사용해야 합니다. Desktop은 동일 오리진에서 `wsUrl`을 `/ws`로 유도하고(`https`이면 `wss`, `http`이면 `ws`), API 오리진에서 `appUrl`을 유도합니다. 배포 환경이 서로 다른 오리진을 사용한다면 명시적으로 설정하세요:
+
+```json
+{
+  "schemaVersion": 1,
+  "apiUrl": "https://api.your-domain",
+  "wsUrl": "wss://api.your-domain/ws",
+  "appUrl": "https://your-domain"
+}
+```
+
+`desktop.json`이 존재하지만 유효하지 않으면, Desktop은 안전하게 동작을 차단하여 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) — 자체 백엔드를 실행하고 CLI 또는 Desktop 런타임 설정으로 연결하기
+- [데몬 및 런타임](/daemon-runtimes) — 데몬의 작동 방식 (Desktop이 대신 시작해 주지만 동작은 동일합니다)

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

@@ -0,0 +1,302 @@
+---
+title: 규약
+description: 코드 네이밍, i18n 번역 용어집, 중국어 보이스 가이드의 단일 진실 공급원.
+---
+
+이 페이지는 코드 네이밍, i18n 번역 용어집, 중국어 보이스 가이드의 단일 진실 공급원입니다. 예전에 `packages/views/locales/glossary.md`나 여기저기 흩어진 주석에 있던 내용은 이제 모두 이곳에 모여 있습니다.
+
+Multica 코드를 작성하거나, 번역을 변경하거나, 중국어 제품 카피를 작성한다면 이 페이지를 참고하세요.
+
+---
+
+## 1. 코드 네이밍
+
+### 라우트
+
+워크스페이스 진입 전 라우트(사용자가 워크스페이스에 들어가기 전에 존재하는 라우트)는 반드시 단일 단어 또는 `/{noun}/{verb}` 패턴을 사용해야 합니다.
+
+- ✅ `/login`, `/inbox`, `/workspaces/new`
+- ❌ `/new-workspace`, `/create-team`, `/accept-invite`
+
+루트에 하이픈으로 연결된 단어 묶음은 사용자가 직접 고른 워크스페이스 slug와 충돌하며, 끝없는 예약어 slug 점검을 강요합니다. 명사(`workspaces`)를 예약해 두면 `/workspaces/*` 하위 트리 전체가 자동으로 보호됩니다.
+
+### 워크스페이스 범위 라우트
+
+항상 `/{slug}/{section}` 아래에 둡니다 — `/{slug}/issues`, `/{slug}/agents`, `/{slug}/settings`. 워크스페이스 라우팅 로직을 절대 중복하지 말고, 공유 코드에서는 프레임워크별 link API 대신 `useNavigation().push()`를 사용하세요.
+
+### 패키지와 모듈
+
+모노레포는 엄격한 패키지 경계를 강제합니다:
+
+| 패키지 | 의존 가능 | 의존 금지 |
+| --- | --- | --- |
+| `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/*` | 다른 앱 |
+| `apps/desktop/.../platform/` | `react-router-dom`, electron | 다른 앱 |
+
+두 앱 모두에 동일한 로직이 나타난다면 반드시 공유 패키지로 추출해야 합니다. "사소한" 중복이라는 예외는 없습니다.
+
+### 파일과 컴포넌트
+
+- 파일: `kebab-case.tsx` / `kebab-case.ts` (예: `agent-row-actions.tsx`)
+- 컴포넌트: `PascalCase` (예: `AgentRowActions`)
+- Hook: `useCamelCase` (예: `useWorkspaceId`)
+- 테스트: `<file>.test.ts(x)`로 같은 위치에 배치
+- Store (Zustand): `<feature>-store.ts`, `use<Feature>Store`로 export
+
+### 데이터베이스 (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 버전), 절대 error를 확인하지 않고 `util.ParseUUID`를 직접 사용하지 마세요.
+
+### TypeScript
+
+- 네트워크상의 API 응답은 `snake_case`이며, api client가 경계에서 `camelCase`로 변환합니다. TS 코드 내부에서는 **항상 camelCase**.
+- 타입: `PascalCase` (`Issue`, `AgentRuntime`); `IPrefix` 금지, `_t` 접미사 금지.
+- 열거형: string literal union을 선호하고, 런타임 순회가 필요한 경우에만 `enum`을 사용.
+- TanStack Query 키: `<feature>/queries.ts` 안의 팩토리 함수, 예: `issueKeys.detail(id)`.
+
+### 이슈 키
+
+모든 이슈에는 `MUL-123` 같은 사람이 읽을 수 있는 키가 있습니다: 워크스페이스 `issue_prefix`(대문자와 숫자, 보통 3자, 최대 10자) + 일련번호. 워크스페이스 admin은 Settings → General에서 접두사를 변경할 수 있는데, 변경하면 기존의 모든 이슈가 다시 번호 매겨지므로 옛 접두사가 박혀 있는 외부 참조(PR 제목, 브랜치 이름, 문서와 채팅 속 링크)는 더 이상 연결되지 않습니다.
+
+### 코드 내 주석
+
+영어만 사용합니다. 레포는 Go와 TypeScript 모두에 이를 강제합니다. 코드에서 중국어 주석을 발견하면 그것은 버그이니 교체하세요.
+
+### 커밋 메시지
+
+Conventional 형식: `feat(scope)`, `fix(scope)`, `refactor(scope)`, `docs`, `test(scope)`, `chore(scope)`. 의도별로 묶인 원자적 커밋.
+
+---
+
+## 2. i18n 번역 용어집
+
+이것은 모든 번역 PR이 **반드시** 지켜야 하는 용어집입니다. 예전에는 `packages/views/locales/glossary.md`에 있었는데, 그 파일은 이제 이곳을 가리키는 stub입니다.
+
+### 핵심 구분: 엔티티 vs 개념
+
+Multica의 제품 명사는 두 가지 범주로 나뉩니다:
+
+- **엔티티(Entity)** — URL, 데이터베이스 row, API 타입을 가집니다. 중국어 텍스트에서는 **소문자 영문**으로 표기하여 시각적으로 타입 이름처럼 읽히게 하고 "이것은 Multica 시스템 엔티티다"라는 신호를 줍니다.
+- **개념(Concept)** — 일반 명사이며, 데이터베이스 엔티티가 아닙니다. **완전히 번역**하여 중국어 사용자가 흐르는 텍스트 속에 들쭉날쭉한 영문을 보지 않도록 합니다.
+
+이 규칙은 `apps/docs/content/docs/*.zh.mdx`와 정렬되어 있습니다 — 이 문서들은 사실상의 중국어 보이스 표준이며 20개 이상의 페이지에서 실전 검증되었습니다.
+
+### 엔티티 — 혼합 규칙 (`issue` / `skill` / `task`)
+
+`issue` / `skill` / `task`는 Multica의 핵심 엔티티입니다. 스키마 컬럼, API 필드, 제품 UI 레이블이 모두 영어입니다. 중국어 텍스트에서는 **혼합 규칙**을 따르며 — 무엇을 사용할지는 단어가 어디에 나타나는지에 따라 달라집니다:
+
+| 맥락 | 표기 | 예시 |
+| --- | --- | --- |
+| **UI 문자열, 상태 이름, 코드 참조** | 소문자 영문 | "排队中的 task"、"创建子 issue"、"为智能体注入 skill" |
+| **문서 제목 / 섹션 헤딩** | Title-case 영문 **또는** 중국어 용어 | "Issue 与 project"、"Skills"、"执行任务" |
+| **장문 문서 산문에서 엔티티가 진행 중인 주어일 때** | 중국어 용어, 첫 언급 시 괄호 안에 영문 | "**执行任务**（task）是智能体每一次工作的单位" |
+| **API / DB 필드** | 항상 `task` / `issue` / `skill` | `task_id`, `issue_status`, `skill_uuid` |
+
+중국어 용어 참고:
+
+- `task` ↔ `执行任务` (맥락이 분명해지면 `任务`로 줄여서 사용)
+- `issue`에는 정착된 중국어 번역이 없습니다 — 영문 유지; 제목에서는 `Issue`처럼 대문자로 표기 가능
+- `skill`에는 정착된 중국어 번역이 없습니다 — 영문 유지; 제목에서는 `Skills`처럼 대문자로 표기 가능
+
+**`issue` / `skill` / `task`가 `project` / `autopilot`처럼 중국어로 강제 번역되지 않는 이유**:
+
+- **`issue` / `task`**: 개발 팀은 영어로 대화합니다. 중국어 후보들("任务" — 너무 모호하고 "工作"과 거의 동의어; "工单" — IT 티켓 어감; "议题" — GitHub 스타일이지만 제품 느낌과 맞지 않음)은 모두 `issue`보다 못하게 읽힙니다. **하지만** 장문 문서 산문에서 소문자 `task`를 50번 반복하면 리듬이 깨지므로 — 산문에서는 `执行任务`를 허용하되, UI 문자열과 상태 이름은 소문자 영문으로 유지합니다.
+- **`skill`**: 정착된 중국어 용어가 없는 Multica 고유 개념입니다.
+- **`project` → "项目"**: 정착된 주류 중국어 단어. Feishu / Tower / Teambition / PingCode / GitHub Projects — 모든 중국어 제품이 이를 번역합니다. 중국어 맥락에서 `project`를 그대로 두는 제품은 없습니다.
+- **`autopilot` → "自动化"**: 중국어에서 "autopilot"은 Tesla의 "自动驾驶"를 연상시키며, 이 기능이 하는 일(일정에 따라 task 실행)과 맞지 않습니다. Notion과 Feishu 모두 "自动化"를 사용하며, 그것이 업계 합의입니다.
+
+### 번역하지 않음 — 브랜드와 약어
+
+| 범주 | 용어 |
+| --- | --- |
+| 브랜드 | **Multica**, GitHub, Slack, Google, Anthropic, OpenAI, Claude, Codex, Cursor, Linear, Jira |
+| 약어 | API, CLI, URL, SDK, OAuth, JWT, SSO, WebSocket, HTTP, JSON, YAML, SQL |
+
+### 완전히 번역 — 개념
+
+| English | Chinese |
+| --- | --- |
+| Workspace | **工作区** |
+| Agent | **智能体** |
+| Project | **项目** |
+| Autopilot | **自动化** |
+| Daemon | **守护进程** |
+| Runtime | **运行时** |
+| Inbox | **收件箱** |
+| Comment | **评论** |
+| Reply | **回复** |
+| Notifications | **通知** |
+| Member | **成员** |
+| Label | **标签** |
+| Settings | **设置** |
+| Onboarding | **上手引导** |
+
+### 완전히 번역 — 일반 UI 단어
+
+| English | Chinese |
+| --- | --- |
+| Invite / Invitation | 邀请 |
+| Search | 搜索 |
+| Email | 邮箱 (label) / 邮件 (action) |
+| Password | 密码 |
+| Sign in / Log in | 登录 |
+| Sign up | 注册 |
+| Sign out / Log out | 退出登录 |
+| Save / Cancel / Delete | 保存 / 取消 / 删除 |
+| Confirm / Continue / Back | 确认 / 继续 / 返回 |
+| Edit / New / Create / Add | 编辑 / 新建 / 创建 / 添加 |
+| Remove / Send / Open / Close | 移除 / 发送 / 打开 / 关闭 |
+| Preview / Download / Upload | 预览 / 下载 / 上传 |
+| Done / Loading... | 完成 / 加载中... |
+| Profile / Account / Appearance | 个人资料 / 账号 / 外观 |
+| Theme / Language | 主题 / 语言 |
+| Light / Dark / System | 浅色 / 深色 / 跟随系统 |
+| Active / Archived | 活跃 (or 启用) / 已归档 |
+| Status / Priority | 状态 / 优先级 |
+| Assignee / Reporter | 负责人 / 报告人 |
+| Description / Title | 描述 / 标题 |
+| Date / Time | 日期 / 时间 |
+| Today / Yesterday / Tomorrow | 今天 / 昨天 / 明天 |
+| Empty / Failed / Success | 空 / 失败 / 成功 |
+| Error / Warning | 错误 / 警告 |
+
+### 역할과 상태 열거형 (소문자 영문, 번역하지 않음)
+
+이것들은 스키마 수준의 식별자입니다; 중국어 맥락에서도 소문자 영문으로 표기합니다.
+
+- 역할: `owner` / `admin` / `member`
+- 이슈 상태: `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}}！" }
+```
+
+### 번역 키 네이밍
+
+3단계 중첩: `feature.component.action`.
+
+```json
+{
+  "feature_or_component": {
+    "subcomponent_or_section": {
+      "action_or_label": "..."
+    }
+  }
+}
+```
+
+예시:
+
+- `issues.toolbar.batch_update_success`
+- `issues.detail.comment_form.placeholder`
+- `inbox.empty.title`
+- `settings.preferences.language.title`
+
+### Web 전용 / Desktop 전용 카피
+
+- 공유 카피: namespace JSON의 최상위
+- Web 전용: `web` 섹션
+- Desktop 전용: `desktop` 섹션
+
+정식 예시는 `auth.json`을 참고하세요(`web` 섹션에 `prefer_desktop` / `desktop_handoff.*`가 포함됨).
+
+---
+
+## 3. 중국어 보이스와 스타일
+
+### 구두점
+
+- 중국어에서는 전각 구두점 사용: `，。：；！？`
+- 따옴표: 영어 원문과 맞추기 위해 곧은 큰따옴표 `"..."`를 사용. `「」`나 둥근 따옴표는 사용하지 마세요.
+- 줄임표: 단일 문자 `…`가 아닌 세 개의 점 `...`. 영어 원문과 일치시키세요.
+- 중국어-영어 혼용: 영문 단어 양옆에 각각 단일 공백(단어 조합 규칙 참고).
+
+### 스타일 원칙
+
+- **간결하고 직접적으로.** 번역투 회피: "对于 X 来说"、"作为 X"、"我们的".
+- **오류 메시지**: 부드럽지만 명확하게. "无法保存修改"가 "保存修改失败了！"보다 낫습니다.
+- **버튼**: 동사를 먼저, 2~4자. "取消"、"保存修改"、"立即同步".
+- **툴팁**: 완결된 짧은 문장. "复制链接到剪贴板".
+- **플레이스홀더**: 예시 형태. "输入 issue 标题...".
+
+### 막힐 때 참고할 곳
+
+용어집이 특정 용어를 다루지 않을 때는 다음을 참고하세요:
+
+1. `apps/docs/content/docs/*.zh.mdx` — 사실상의 중국어 보이스 표준, 일관된 번역 20개 이상 페이지
+2. `packages/views/locales/zh-Hans/auth.json`과 `editor.json` — JSON 구조 + selector API 패턴
+3. `packages/views/auth/login-page.tsx` — 컴포넌트 수준 selector API 호출 지점
+4. `packages/views/settings/components/preferences-tab.tsx` — 언어 전환기 참고
+
+---
+
+## 이 페이지를 업데이트할 때
+
+이곳의 규칙을 변경하면 다음도 함께 수행하세요:
+
+1. 관련 locale JSON / CLAUDE.md / 문서 페이지에 적용
+2. PR 설명에 변경 사항을 기록하여 리뷰어가 다운스트림 정리를 살펴보도록 알리기
+
+이 페이지가 계약입니다; 다른 어떤 것도 이를 무시할 수 없습니다.

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

@@ -70,7 +70,7 @@ If logic appears in both apps, it MUST be extracted to a shared package. There a
 
 ### 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.
+Every issue has a human-readable key like `MUL-123`: workspace `issue_prefix` (uppercase letters and digits, typically 3 chars, max 10) + sequence number. Workspace admins can change the prefix in Settings → General; changing it renumbers every existing issue, so external references that embed the old prefix (PR titles, branch names, links in docs and chat) stop resolving.
 
 ### Comments in code
 

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

@@ -70,7 +70,7 @@ monorepo 的包边界是硬约束：
 
 ### Issue 编号
 
-每个 issue 有人类可读的编号，比如 `MUL-123`：工作区 `issue_prefix`（3 个大写字母）+ 流水号。前缀在工作区创建时定，之后不可改。
+每个 issue 有人类可读的编号，比如 `MUL-123`：工作区 `issue_prefix`（大写字母和数字，通常 3 个字符，最长 10 个）+ 流水号。工作区管理员可以在 Settings → General 中修改前缀；修改会让所有现有 issue 重新编号，外部引用——PR 标题、分支名、文档与聊天里的链接——里的旧前缀会失效。
 
 ### 代码注释
 

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

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

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

@@ -0,0 +1,224 @@
+---
+title: 환경 변수
+description: 자체 호스팅 Multica 서버를 실행하기 위한 환경 변수 전체 목록입니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+자체 호스팅 Multica [서버](/self-host-quickstart)는 시작 시 환경 변수에서 설정을 읽습니다 — 데이터베이스, 로그인, 이메일, 스토리지, 가입 허용 목록이 모두 여기에 있습니다. 이 페이지는 모든 변수를 용도별로 그룹화합니다: 각 섹션은 **설정하지 않으면 어떻게 되는지**, 그리고 **프로덕션에서 반드시 설정해야 하는 변수가 무엇인지**를 명확히 설명합니다. auth 관련 변수를 실제로 어떻게 설정하는지는 [로그인 및 가입 설정](/auth-setup)을 참고하세요.
+
+## 핵심 서버 변수
+
+배포 전에 반드시 고려해야 하는 핵심 변수입니다 — 일부는 서버를 시작할 수 있게 해주는 기본값을 가지고 있지만, 프로덕션에서는 필수 항목을 명시적으로 설정해야 합니다.
+
+| 변수 | 기본값 | 프로덕션 필수? |
+|---|---|---|
+| `DATABASE_URL` | `postgres://multica:multica@localhost:5432/multica?sslmode=disable` | **예** |
+| `PORT` | `8080` | 아니오 (포트를 변경하는 경우 제외) |
+| `JWT_SECRET` | `multica-dev-secret-change-in-production` | **예** (기본값은 안전하지 않음) |
+| `APP_ENV` | 비어 있음 | **예** (`production`이어야 함) |
+| `FRONTEND_ORIGIN` | 비어 있음 | **예** (자체 호스팅은 자체 도메인을 설정해야 함) |
+| `MULTICA_DEV_VERIFICATION_CODE` | 비어 있음 | 아니오 (프로덕션에서는 반드시 비워 두어야 함) |
+
+<Callout type="warning">
+**프로덕션에서는 `MULTICA_DEV_VERIFICATION_CODE`를 비워 두세요.** 고정된 로컬 테스트 코드는 기본적으로 비활성화되어 있지만, `MULTICA_DEV_VERIFICATION_CODE=888888`로 활성화하면 `APP_ENV`가 production이 아닌 동안에는 코드를 요청할 수 있는 누구나 그 고정 값으로 로그인할 수 있습니다. 이 단축 코드는 `APP_ENV=production`일 때 무시됩니다.
+</Callout>
+
+### 데이터베이스 커넥션 풀
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `DATABASE_MAX_CONNS` | `25` | pgxpool 최대 연결 수. 데몬은 자주(3초마다) 폴링하며 연결을 사용하므로, 규모가 큰 배포에서는 더 높은 값이 필요할 수 있습니다 |
+| `DATABASE_MIN_CONNS` | `5` | 최소 유휴 연결 수 |
+
+**설정하지 않으면** 위 값이 사용됩니다 — 이전에 프로덕션에서 풀 고갈을 일으켰던 pgx 내장 기본값 4/NumCPU가 **아닙니다**.
+
+## 이메일 설정
+
+Multica는 두 가지 전송 백엔드를 지원합니다 — 클라우드 배포용 [Resend](https://resend.com/), 또는 내부 / 온프레미스 네트워크용 SMTP relay. 둘 다 설정된 경우 `SMTP_HOST`가 `RESEND_API_KEY`보다 우선합니다.
+
+### Resend
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `RESEND_API_KEY` | 비어 있음 | Resend API key |
+| `RESEND_FROM_EMAIL` | `noreply@multica.ai` | 발신 주소 (Resend 계정에서 검증된 도메인이어야 하며, SMTP를 사용할 때도 `From:` 헤더로 재사용됨) |
+
+### SMTP relay
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `SMTP_HOST` | 비어 있음 | SMTP relay 호스트명. 이를 설정하면 SMTP 모드가 활성화되고 Resend를 덮어씁니다 |
+| `SMTP_PORT` | `25` | SMTP 포트. STARTTLS 제출에는 `587`을 사용하세요; **포트 465(SMTPS / 암묵적 TLS)는 지원되지 않습니다** |
+| `SMTP_USERNAME` | 비어 있음 | SMTP 사용자명. 인증 없는 relay의 경우 비워 두세요 |
+| `SMTP_PASSWORD` | 비어 있음 | SMTP 비밀번호 |
+| `SMTP_TLS_INSECURE` | `false` | TLS 인증서 검증을 건너뛰려면 `true`로 설정 (사설 CA / 자체 서명 인증서만 해당) |
+
+서버가 STARTTLS를 알리면 자동으로 업그레이드됩니다. dial 타임아웃은 10초이고 전체 SMTP 세션에는 30초 데드라인이 있어, 블랙홀이 된 relay가 auth 핸들러를 멈추게 할 수 없습니다.
+
+**둘 다 설정하지 않았을 때의 동작**: 서버는 오류를 내지 않지만, 전송되어야 했던 모든 이메일(인증 코드, 초대 링크)은 **서버의 stdout에만 기록됩니다**. 로컬 개발에는 편리합니다 — 서버 로그에서 코드를 복사해 사용하세요; **프로덕션에서는 이를 설정하는 것을 잊으면 조용한 블랙홀이 되어**, 사용자는 이메일을 전혀 받지 못하고 아무런 오류도 드러나지 않습니다.
+
+## Google OAuth 설정
+
+선택 사항입니다. 이메일 + 인증 코드만 사용하려면 설정하지 않은 채로 두고, 로그인 페이지에 "Sign in with Google"을 추가하려면 설정하세요.
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `GOOGLE_CLIENT_ID` | 비어 있음 | Google Cloud OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | 비어 있음 | Google Cloud OAuth secret |
+| `GOOGLE_REDIRECT_URI` | `http://localhost:3000/auth/callback` | OAuth 콜백 URL (자체 호스팅: 자신의 프론트엔드 도메인으로 교체) |
+
+**런타임에 적용됨**: 프론트엔드는 런타임에 `/api/config`를 통해 이 설정을 읽으므로, **변경해도 프론트엔드 리빌드나 재배포가 필요 없습니다** — 서버를 재시작하면 적용됩니다.
+
+전체 설정(Google Cloud Console 단계 포함)은 [로그인 및 가입 설정](/auth-setup#google-oauth-configuration)에 있습니다.
+
+## 파일 스토리지 설정
+
+Multica는 사용자가 업로드한 첨부 파일(댓글의 이미지와 파일)을 저장합니다. **S3가 권장됩니다**; S3가 설정되어 있지 않으면 로컬 디스크로 폴백합니다.
+
+### S3 / S3 호환 스토리지
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `S3_BUCKET` | 비어 있음 | **버킷 이름만** (예: `my-bucket`). `.s3.<region>.amazonaws.com` 접미사를 포함하지 **마세요** — 서버가 `S3_BUCKET` + `S3_REGION`으로 공개 호스트를 구성합니다. 이를 설정하면 S3 스토리지가 활성화됩니다 |
+| `S3_REGION` | `us-west-2` | AWS 리전. 버킷의 실제 리전과 일치해야 합니다 — 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`을 설정하지 않으면**: 서버는 시작 시 `"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. `https://<S3_BUCKET>.s3.<S3_REGION>.amazonaws.com/<key>` (virtual-hosted-style). `S3_BUCKET`에 점이 포함된 경우, AWS가 발급한 와일드카드 TLS 인증서가 점이 포함된 버킷 호스트를 검증하지 못하므로 서버는 `https://s3.<S3_REGION>.amazonaws.com/<S3_BUCKET>/<key>` (path-style)로 폴백합니다.
+
+### 로컬 디스크 (S3가 설정되지 않은 경우)
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `LOCAL_UPLOAD_DIR` | `./data/uploads` | 로컬 스토리지 디렉터리 |
+| `LOCAL_UPLOAD_BASE_URL` | 비어 있음 (상대 경로 반환) | 공개 base URL — 설정하지 않으면 프론트엔드가 첨부 파일의 전체 URL을 확인할 수 없습니다 |
+
+### CloudFront (선택)
+
+S3 앞에 CloudFront를 두는 경우 세 가지 변수가 적용됩니다: `CLOUDFRONT_DOMAIN`, `CLOUDFRONT_KEY_PAIR_ID`, `CLOUDFRONT_PRIVATE_KEY` (또는 Secrets Manager에서 읽으려면 `CLOUDFRONT_PRIVATE_KEY_SECRET`). CloudFront를 사용하지 않으면 건너뛰세요 — S3 설정과 충돌하지 않습니다.
+
+### Cookie 도메인
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `COOKIE_DOMAIN` | 비어 있음 | 세션 cookie의 범위 |
+
+- **비어 있음**: cookie는 방문한 정확한 호스트에서만 유효합니다 (단일 호스트 배포에 적합)
+- **`.example.com`으로 설정**: cookie가 하위 도메인 간에 공유됩니다 (그래서 `app.example.com`과 `api.example.com`이 로그인 세션을 공유함)
+- 경고: IP 주소일 수 없습니다 (브라우저가 무시함)
+
+## 누가 가입할 수 있는지 제한하기
+
+세 개의 허용 목록 계층이 우선순위에 따라 결합됩니다. **어느 한 계층이라도 비어 있지 않은 값으로 설정되면, 일치하지 않는 이메일은 거부됩니다** — `ALLOW_SIGNUP=true`조차 이를 무시할 수 없습니다.
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `ALLOWED_EMAILS` | 비어 있음 | 명시적 이메일 허용 목록 (쉼표로 구분). 비어 있지 않으면 목록에 있는 이메일만 가입할 수 있습니다 |
+| `ALLOWED_EMAIL_DOMAINS` | 비어 있음 | 도메인 허용 목록 (쉼표로 구분). 비어 있지 않으면 목록에 있는 도메인만 가입할 수 있습니다 |
+| `ALLOW_SIGNUP` | `true` | 가입 마스터 스위치. 가입을 완전히 비활성화하려면 `false`로 설정 |
+
+**직관에 반하는 부분**: `ALLOWED_EMAIL_DOMAINS=company.io` + `ALLOW_SIGNUP=true`는 "company.io 또는 모두를 허용"한다는 뜻이 **아니라** **company.io만 허용**한다는 뜻입니다. 허용 목록 계층은 AND 시맨틱입니다 — 전체 결정 트리는 [로그인 및 가입 설정 → 가입 허용 목록](/auth-setup#restricting-who-can-sign-up)에 있습니다.
+
+**초대 흐름 자체는 가입 허용 목록을 확인하지 않습니다** — 하지만 초대받은 사람은 초대를 수락하기 전에 여전히 **로그인**할 수 있어야 합니다. 이미 Multica 계정이 있다면(예: 다른 워크스페이스에서) 허용 목록의 영향을 받지 않고 바로 수락할 수 있습니다; **한 번도 가입한 적이 없다면**, 로그인의 첫 단계(인증 코드 요청)는 여전히 허용 목록 확인을 거치며, `ALLOW_SIGNUP=false`나 `ALLOWED_EMAILS` / `ALLOWED_EMAIL_DOMAINS`에 의해 거부된 이메일은 **가입을 완료할 수 없고, 따라서 초대를 수락할 수 없습니다**.
+
+## 워크스페이스 생성 잠그기
+
+`ALLOW_SIGNUP=false`는 새 계정을 차단하지만, 이미 로그인한 사용자가 `POST /api/workspaces`를 통해 또 다른 워크스페이스를 생성하는 것은 **차단하지 않습니다**. 모든 이슈, 저장소, 에이전트가 플랫폼 관리자에게 보여야 하는 자체 호스팅 인스턴스에서는, 그 틈을 막기 위해 `DISABLE_WORKSPACE_CREATION=true`로 설정하세요.
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `DISABLE_WORKSPACE_CREATION` | `false` | `true`이면 `POST /api/workspaces`에 대한 모든 호출이 `403 workspace creation is disabled for this instance`를 반환합니다. 웹 UI는 `/api/config`를 통해 모든 "워크스페이스 생성" 요소를 숨깁니다. 역할/owner 예외는 없습니다 — 이 게이트는 인스턴스 단위로 전역 적용됩니다 |
+
+권장 부트스트랩 순서:
+
+1. `DISABLE_WORKSPACE_CREATION`을 설정하지 않은 채로(기본값) 인스턴스를 시작합니다.
+2. 관리자로 로그인하여 공유 워크스페이스를 생성합니다.
+3. `DISABLE_WORKSPACE_CREATION=true`로 설정하고 백엔드를 재시작합니다. 이 시점부터 사용자는 초대를 통해서만 참여할 수 있습니다.
+
+초대받은 사용자가 첫 인증 코드로 가입을 완료할 수 있도록 `ALLOW_SIGNUP=true`를 유지하고 싶다면, `DISABLE_WORKSPACE_CREATION=true`를 `ALLOWED_EMAIL_DOMAINS` / `ALLOWED_EMAILS`와 결합하여 어떤 주소가 가입할 수 있는지 범위를 지정하세요. `ALLOW_SIGNUP=false`로 설정하면 대기 중인 초대 대상자가 계정을 만드는 것조차 추가로 차단됩니다 — 모든 멤버가 이미 Multica 계정을 가지고 있는 인스턴스에서만 유용합니다.
+
+## 속도 제한 (선택적 Redis)
+
+공개 auth 엔드포인트 — `/auth/send-code`, `/auth/verify-code`, `/auth/google` — 앞에는 IP별 고정 윈도우 속도 제한이 있습니다. 리미터는 Redis로 뒷받침됩니다. `REDIS_URL`을 설정하지 않으면 미들웨어는 **no-op**(fail-open)이 되고, 백엔드는 시작 시 `rate limiting disabled: REDIS_URL not configured`를 로깅합니다.
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `REDIS_URL` | 비어 있음 | Redis 연결 URL (예: `redis://localhost:6379/0`). 설정하지 않으면 auth 엔드포인트의 속도 제한이 비활성화됩니다. 동일한 Redis는 실시간 허브 fan-out, PAT 캐시, 데몬 토큰 캐시에서도 사용됩니다 — 설정하지 않으면 모두 인메모리 / 직접 DB 모드로 폴백합니다 |
+| `RATE_LIMIT_AUTH` | `5` | `/auth/send-code` 및 `/auth/google`에 대한 IP당 분당 최대 요청 수 |
+| `RATE_LIMIT_AUTH_VERIFY` | `20` | `/auth/verify-code`에 대한 IP당 분당 최대 요청 수 |
+| `RATE_LIMIT_TRUSTED_PROXIES` | 비어 있음 | 리미터가 그 `X-Forwarded-For` 헤더를 신뢰하도록 허용하는, 쉼표로 구분된 CIDR. 비어 있음(기본값)은 **XFF를 절대 신뢰하지 않음**을 의미합니다 — 리미터는 직접 연결의 `RemoteAddr`만 사용합니다 |
+
+요청이 제한을 초과하면 서버는 `429 Too Many Requests`, `Retry-After: 60`, 그리고 본문 `{"error":"too many requests"}`로 응답합니다.
+
+<Callout type="warning">
+**리버스 프록시 뒤에서는 `RATE_LIMIT_TRUSTED_PROXIES`를 반드시 설정해야 합니다.** 그렇지 않으면 백엔드 관점에서 모든 실제 사용자가 프록시의 IP를 공유하게 되어, 배포 전체가 하나의 버킷에 들어가고, `/auth/send-code`가 사이트 전체에 대해 분당 5회가 됩니다. 일반적인 값: 같은 호스트의 Caddy / Nginx에는 `127.0.0.1/32,::1/128`; Cloudflare / ALB / CloudFront에는 해당 CDN의 공개된 IP 범위. `RemoteAddr`이 이 CIDR 중 하나에 속하는 IP만 `X-Forwarded-For`를 사용해 클라이언트를 식별할 수 있습니다.
+</Callout>
+
+이 별도의 `RATE_LIMIT_TRUSTED_PROXIES`는 오토파일럿 webhook 리미터(`/api/webhooks/autopilots/{token}`)를 제어하는 `MULTICA_TRUSTED_PROXIES`와는 **다릅니다**. 각 리미터는 자체 목록을 파싱하므로, 프록시 뒤에 있는 배포는 둘 다 설정해야 합니다.
+
+## 데몬 튜닝 파라미터
+
+데몬은 사용자의 로컬 기기에서 실행되며, 그 설정도 로컬 환경 변수에서 읽습니다. 일반적으로 사용되는 것들:
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `MULTICA_SERVER_URL` | `ws://localhost:8080/ws` | 서버 주소 (자체 호스팅: 자신의 도메인으로 교체) |
+| `MULTICA_DAEMON_HEARTBEAT_INTERVAL` | `15s` | 하트비트 간격 |
+| `MULTICA_DAEMON_POLL_INTERVAL` | `3s` | 작업 폴링 간격 |
+| `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` | `20` | 최대 동시 작업 수 |
+| `MULTICA_<PROVIDER>_PATH` | CLI 이름과 일치 | 각 AI 코딩 도구 실행 파일의 경로 (예: `MULTICA_CLAUDE_PATH`) |
+| `MULTICA_<PROVIDER>_MODEL` | 비어 있음 | 각 AI 코딩 도구의 기본 모델 |
+
+각 파라미터가 데몬 동작에 어떻게 영향을 미치는지에 대한 전체 설명은 [데몬과 런타임](/daemon-runtimes)을 참고하세요.
+
+## 프론트엔드 액세스 제어
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `FRONTEND_ORIGIN` | 비어 있음 | 프론트엔드 주소. 초대 이메일 링크, CORS 허용 목록, cookie 도메인이 모두 이 값에서 파생됩니다. 설정하지 않으면 초대 이메일 링크는 호스팅 도메인 `https://app.multica.ai`로 폴백합니다 — 자체 호스팅은 이를 명시적으로 설정해야 합니다 |
+| `CORS_ALLOWED_ORIGINS` | 비어 있음 | 추가로 허용할 CORS origin (쉼표로 구분) |
+| `ALLOWED_ORIGINS` | 비어 있음 | WebSocket 전용 origin 허용 목록 (쉼표로 구분); 설정하지 않으면 폴백 순서는 `CORS_ALLOWED_ORIGINS` → `FRONTEND_ORIGIN` → `localhost:3000/5173/5174`입니다 |
+
+<Callout type="warning">
+**`FRONTEND_ORIGIN`을 설정하지 않으면 두 가지 조용한 실패가 발생합니다**: (1) 초대 이메일 링크가 `https://app.multica.ai`(호스팅 도메인)를 가리켜, 클릭해도 사용자가 자체 호스팅 인스턴스로 돌아오지 않습니다; (2) WebSocket Origin 검사가 `localhost:3000 / 5173 / 5174`로 폴백하여, 프로덕션 배포의 모든 WebSocket 연결이 거부되고 프론트엔드가 "실시간 업데이트를 받지 못하는" 것처럼 보입니다.
+</Callout>
+
+## GitHub 연동
+
+[GitHub PR ↔ 이슈 연동](/github-integration)에는 두 개의 변수가 필요합니다. 설정에서 Connect GitHub를 활성화하고 들어오는 webhook을 수락하려면 둘 다 설정하세요.
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `GITHUB_APP_SLUG` | 비어 있음 | GitHub App의 slug (`https://github.com/apps/<slug>`의 끝부분). 설정 → GitHub 설치 버튼 URL을 구성합니다 |
+| `GITHUB_WEBHOOK_SECRET` | 비어 있음 | GitHub App에 설정한 Webhook secret. 모든 `pull_request` / `installation` delivery의 HMAC-SHA256 검증에 사용되며, setup 콜백 state token의 HMAC 키로도 사용됩니다 |
+
+**둘 중 하나라도 설정하지 않았을 때의 동작:**
+
+- 설정 → GitHub의 `Connect GitHub`가 **비활성화**되고 admin에게 "not configured" 힌트를 표시합니다.
+- `/api/webhooks/github` 엔드포인트는 **`503 github webhooks not configured`**를 반환합니다 — Multica는 모든 서명을 유효한 것으로 취급하기보다, secret 없이는 이벤트 처리를 거부합니다.
+
+**참고:** `GITHUB_WEBHOOK_SECRET`은 설치 흐름 state token의 서명 키로 재사용되므로, 운영자는 secret 하나만 관리하면 됩니다. 이것은 GitHub App의 *Client* secret이 **아닙니다** — Client secret은 OAuth 관련이며 이 연동에서는 사용되지 않습니다. 전체 안내는 [GitHub 연동 → 자체 호스팅 설정](/github-integration#self-host-setup)을 참고하세요.
+
+## 사용량 분석
+
+기본적으로 서버는 Multica의 공식 PostHog 인스턴스로 보고합니다. 옵트아웃하려면 `ANALYTICS_DISABLED=true`로 설정하세요.
+
+| 변수 | 기본값 | 설명 |
+|---|---|---|
+| `ANALYTICS_DISABLED` | `false` | 백엔드 분석을 완전히 비활성화하려면 `true`로 설정 |
+| `POSTHOG_API_KEY` | 내장 기본 키 | 자신의 PostHog 인스턴스를 가리킬 때 설정 |
+| `POSTHOG_HOST` | `https://us.i.posthog.com` | PostHog를 자체 호스팅하는 경우 자신의 호스트로 변경 |
+
+## 다음
+
+- [로그인 및 가입 설정](/auth-setup) — 위의 auth 관련 변수를 실제로 어떻게 설정하는지, 그리고 함정이 어디에 있는지
+- [GitHub 연동](/github-integration) — `GITHUB_APP_SLUG` / `GITHUB_WEBHOOK_SECRET`을 뒷받침하는 GitHub App을 어떻게 설정하는지
+- [문제 해결](/troubleshooting) — 흔한 설정 오류의 증상과 해결책
+- [데몬과 런타임](/daemon-runtimes) — `MULTICA_DAEMON_*` 파라미터가 실제로 하는 일

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

@@ -49,9 +49,10 @@ Multica supports two delivery backends — [Resend](https://resend.com/) for clo
 | Variable | Default | Description |
 |---|---|---|
 | `SMTP_HOST` | empty | SMTP relay hostname. Setting this activates SMTP mode and overrides Resend |
-| `SMTP_PORT` | `25` | SMTP port. Use `587` for STARTTLS submission; **port 465 (SMTPS / implicit TLS) is not supported** |
+| `SMTP_PORT` | `25` | SMTP port. Use `587` for STARTTLS submission, or `465` for SMTPS (implicit TLS, auto-enabled) |
 | `SMTP_USERNAME` | empty | SMTP username. Leave empty for unauthenticated relay |
 | `SMTP_PASSWORD` | empty | SMTP password |
+| `SMTP_TLS` | `starttls` | TLS mode. `implicit` (aliases `smtps`, `ssl`) forces an immediate TLS handshake on connect (SMTPS); port `465` auto-enables it. Unset / `starttls` upgrades via STARTTLS after connect |
 | `SMTP_TLS_INSECURE` | `false` | Set `true` to skip TLS certificate verification (private CA / self-signed only) |
 
 STARTTLS is upgraded automatically when the server advertises it. The dial timeout is 10s and the whole SMTP session has a 30s deadline, so a black-holed relay can't hang the auth handler.
@@ -128,6 +129,41 @@ Three allowlist layers combine by priority. **If any layer is set to a non-empty
 
 **Invite flows themselves do not check the signup allowlist** — but the invitee must still be able to **sign in** before accepting the invite. If they already have a Multica account (for example from another workspace), they can accept directly, unaffected by the allowlist; **if they have never signed up**, the first step of sign-in (requesting a verification code) still passes through the allowlist check, and an email rejected by `ALLOW_SIGNUP=false` or by `ALLOWED_EMAILS` / `ALLOWED_EMAIL_DOMAINS` **cannot finish signup, and therefore cannot accept the invite**.
 
+## Locking down workspace creation
+
+`ALLOW_SIGNUP=false` blocks new accounts, but it does **not** block an already-signed-in user from creating another workspace via `POST /api/workspaces`. On a self-hosted instance where every issue, repo, and agent must be visible to the platform admin, set `DISABLE_WORKSPACE_CREATION=true` to close that gap.
+
+| Variable | Default | Description |
+|---|---|---|
+| `DISABLE_WORKSPACE_CREATION` | `false` | When `true`, every call to `POST /api/workspaces` returns `403 workspace creation is disabled for this instance`. The web UI hides every "Create workspace" affordance via `/api/config`. There is no role/owner exception — the gate is global per instance |
+
+Recommended bootstrap sequence:
+
+1. Start the instance with `DISABLE_WORKSPACE_CREATION` unset (the default).
+2. Sign in as the admin and create the shared workspace.
+3. Set `DISABLE_WORKSPACE_CREATION=true` and restart the backend. From this point on, users join via invitation only.
+
+If you also want to keep `ALLOW_SIGNUP=true` so invited users can finish signup with their first verification code, combine `DISABLE_WORKSPACE_CREATION=true` with `ALLOWED_EMAIL_DOMAINS` / `ALLOWED_EMAILS` to scope which addresses can sign up. Setting `ALLOW_SIGNUP=false` will additionally block pending invitees from creating their account at all — useful only on instances where every member already has a Multica account.
+
+## Rate limiting (optional Redis)
+
+Public auth endpoints — `/auth/send-code`, `/auth/verify-code`, `/auth/google` — have per-IP fixed-window rate limiting in front of them. The limiter is backed by Redis. When `REDIS_URL` is unset the middleware is a **no-op** (fail-open) and the backend logs `rate limiting disabled: REDIS_URL not configured` at startup.
+
+| Variable | Default | Description |
+|---|---|---|
+| `REDIS_URL` | empty | Redis connection URL (for example `redis://localhost:6379/0`). When unset, rate limiting on auth endpoints is disabled. The same Redis is also used by the realtime hub fan-out, the PAT cache, and the daemon-token cache — they all fall back to in-memory / direct-DB mode when unset |
+| `RATE_LIMIT_AUTH` | `5` | Max requests per IP per minute against `/auth/send-code` and `/auth/google` |
+| `RATE_LIMIT_AUTH_VERIFY` | `20` | Max requests per IP per minute against `/auth/verify-code` |
+| `RATE_LIMIT_TRUSTED_PROXIES` | empty | Comma-separated CIDRs whose `X-Forwarded-For` header the limiter is allowed to trust. Empty (the default) means **never trust XFF** — the limiter only uses the direct connection's `RemoteAddr` |
+
+When a request is over the limit, the server replies with `429 Too Many Requests`, `Retry-After: 60`, and body `{"error":"too many requests"}`.
+
+<Callout type="warning">
+**Behind a reverse proxy you must set `RATE_LIMIT_TRUSTED_PROXIES`.** Otherwise every real user shares the proxy's IP from the backend's point of view, the whole deployment ends up in one bucket, and `/auth/send-code` becomes 5 req/min for the entire site. Typical values: `127.0.0.1/32,::1/128` for a same-host Caddy / Nginx; the CDN's published ranges for Cloudflare / ALB / CloudFront. Only IPs whose `RemoteAddr` falls inside one of these CIDRs may use `X-Forwarded-For` to identify the client.
+</Callout>
+
+This separate `RATE_LIMIT_TRUSTED_PROXIES` is **not** the same as `MULTICA_TRUSTED_PROXIES`, which controls the autopilot-webhook limiter (`/api/webhooks/autopilots/{token}`). Each limiter parses its own list, so a deployment behind a proxy should set both.
+
 ## Daemon tuning parameters
 
 The daemon runs on the user's local machine, and its config is read from local environment variables too. The common ones:
@@ -148,6 +184,8 @@ For a full explanation of how each parameter affects daemon behavior, see [Daemo
 | Variable | Default | Description |
 |---|---|---|
 | `FRONTEND_ORIGIN` | empty | Frontend address. Invite email links, the CORS allowlist, and the cookie domain are all derived from this. When unset, invite email links fall back to the hosted domain `https://app.multica.ai` — self-host must set this explicitly |
+| `MULTICA_APP_URL` | empty | Frontend URL for CLI login flow. Also used by the web UI to show self-host daemon setup commands with your app domain; for same-origin deployments this is also used as daemon `server_url` when `MULTICA_PUBLIC_URL` is unset |
+| `MULTICA_PUBLIC_URL` | empty | Public API URL, without trailing slash. Used for autopilot webhook URLs and by the web UI as the daemon `server_url` |
 | `CORS_ALLOWED_ORIGINS` | empty | Additional allowed CORS origins (comma-separated) |
 | `ALLOWED_ORIGINS` | empty | WebSocket-specific origin allowlist (comma-separated); when unset, fallback order is `CORS_ALLOWED_ORIGINS` → `FRONTEND_ORIGIN` → `localhost:3000/5173/5174` |
 
@@ -161,12 +199,12 @@ The [GitHub PR ↔ issue integration](/github-integration) needs two variables.
 
 | Variable | Default | Description |
 |---|---|---|
-| `GITHUB_APP_SLUG` | empty | The slug of your GitHub App (the tail of `https://github.com/apps/<slug>`). Drives the Settings → Integrations install button URL |
+| `GITHUB_APP_SLUG` | empty | The slug of your GitHub App (the tail of `https://github.com/apps/<slug>`). Drives the Settings → GitHub install button URL |
 | `GITHUB_WEBHOOK_SECRET` | empty | The Webhook secret you set on the GitHub App. Used for HMAC-SHA256 verification of every `pull_request` / `installation` delivery, and as the HMAC key for the setup-callback state token |
 
 **Behavior when either is unset:**
 
-- `Connect GitHub` in Settings → Integrations is **disabled** and shows a "not configured" hint to admins.
+- `Connect GitHub` in Settings → GitHub is **disabled** and shows a "not configured" hint to admins.
 - The `/api/webhooks/github` endpoint returns **`503 github webhooks not configured`** — Multica refuses to process events with no secret rather than treating every signature as valid.
 
 **Note:** `GITHUB_WEBHOOK_SECRET` is reused as the signing key for the install-flow state token, so operators only need to manage one secret. It is **not** the GitHub App's *Client* secret — Client secrets are OAuth-related and not used by this integration. See [GitHub integration → Self-host setup](/github-integration#self-host-setup) for the full walkthrough.

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

@@ -49,9 +49,10 @@ Multica 支持两种邮件发送通道——[Resend](https://resend.com/) 适合
 | 环境变量 | 默认值 | 说明 |
 |---|---|---|
 | `SMTP_HOST` | 空 | SMTP relay 主机名。设置后即启用 SMTP 模式并覆盖 Resend |
-| `SMTP_PORT` | `25` | SMTP 端口。STARTTLS 提交端口用 `587`；**暂不支持 465（SMTPS / 隐式 TLS）** |
+| `SMTP_PORT` | `25` | SMTP 端口。STARTTLS 提交端口用 `587`；SMTPS（隐式 TLS，自动启用）用 `465` |
 | `SMTP_USERNAME` | 空 | SMTP 用户名。留空表示未认证 relay |
 | `SMTP_PASSWORD` | 空 | SMTP 密码 |
+| `SMTP_TLS` | `starttls` | TLS 模式。`implicit`（别名 `smtps`、`ssl`）在连接时立即进行 TLS 握手（SMTPS）；`465` 端口会自动启用。未设置 / `starttls` 则在连接后通过 STARTTLS 升级 |
 | `SMTP_TLS_INSECURE` | `false` | 设为 `true` 跳过 TLS 证书校验（仅限私有 CA / 自签证书）|
 
 服务端 advertise STARTTLS 时会自动升级。dial 超时 10s，整个 SMTP 会话有 30s deadline，避免 relay 黑洞把 auth handler 挂死。
@@ -128,6 +129,41 @@ Multica 存储用户上传的附件（评论里的图片、文件等）。**优
 
 **邀请流程本身不检查 signup 白名单**——但被邀请人必须先能**登录**才能接受邀请。如果对方已经有 Multica 账号（比如在其他工作区注册过），可以直接接受，不受白名单影响；**如果对方还没注册过**，他们登录的第一步（发送验证码）仍然会过白名单检查，被 `ALLOW_SIGNUP=false` 或 `ALLOWED_EMAILS` / `ALLOWED_EMAIL_DOMAINS` 拒绝的邮箱**无法完成注册，也就没法接受邀请**。
 
+## 锁死工作区创建
+
+`ALLOW_SIGNUP=false` 能挡住新注册，但**挡不住**已经登录的用户继续 `POST /api/workspaces` 自助开新工作区。在希望平台管理员能看到全部 issue / 仓库 / 智能体的自部署实例里，把 `DISABLE_WORKSPACE_CREATION=true` 打开以堵上这个口子。
+
+| 环境变量 | 默认值 | 说明 |
+|---|---|---|
+| `DISABLE_WORKSPACE_CREATION` | `false` | 设为 `true` 时，对 `POST /api/workspaces` 的任何调用都返回 `403 workspace creation is disabled for this instance`。Web UI 通过 `/api/config` 隐藏所有「创建工作区」入口。该开关是实例级的，没有 owner / admin 例外 |
+
+推荐的开服流程：
+
+1. 启动实例时保持 `DISABLE_WORKSPACE_CREATION` 未设置（默认）。
+2. 管理员登录并创建共享工作区。
+3. 把 `DISABLE_WORKSPACE_CREATION=true` 设上并重启 backend。之后新用户只能通过邀请加入。
+
+如果还想让被邀请的新用户能完成首次注册，保留 `ALLOW_SIGNUP=true`（必要时用 `ALLOWED_EMAIL_DOMAINS` / `ALLOWED_EMAILS` 限定可注册邮箱），只把 `DISABLE_WORKSPACE_CREATION=true` 打开即可；如果同时设 `ALLOW_SIGNUP=false`，连有 pending invite 的邮箱都无法完成首次注册，仅适合所有成员都已有 Multica 账号的实例。
+
+## 速率限制（可选 Redis）
+
+公开认证端点——`/auth/send-code`、`/auth/verify-code`、`/auth/google`——前面挂了按 IP 的固定窗口限流。限流器后端是 Redis。`REDIS_URL` 不设时中间件**直通**（fail-open），后端启动会打日志 `rate limiting disabled: REDIS_URL not configured`。
+
+| 环境变量 | 默认值 | 说明 |
+|---|---|---|
+| `REDIS_URL` | 空 | Redis 连接 URL（例如 `redis://localhost:6379/0`）。不设时认证端点的限流功能直接关闭。同一个 Redis 也被实时事件 fan-out、PAT 缓存、守护进程 token 缓存复用；不设时这些组件分别回落到内存模式 / 直查 DB |
+| `RATE_LIMIT_AUTH` | `5` | 单 IP 每分钟对 `/auth/send-code` 和 `/auth/google` 的最大请求数 |
+| `RATE_LIMIT_AUTH_VERIFY` | `20` | 单 IP 每分钟对 `/auth/verify-code` 的最大请求数 |
+| `RATE_LIMIT_TRUSTED_PROXIES` | 空 | 逗号分隔的 CIDR 列表，列在内的来源 IP 才允许通过 `X-Forwarded-For` 标识客户端。默认空 = **永不信任 XFF**，限流器只看直连的 `RemoteAddr` |
+
+被限流的请求会返回 `429 Too Many Requests`，带 `Retry-After: 60` 头和 `{"error":"too many requests"}` 响应体。
+
+<Callout type="warning">
+**部署在反向代理后面时必须设 `RATE_LIMIT_TRUSTED_PROXIES`。** 否则在后端看来所有真实用户都共用代理那个 IP，整个部署落到同一个桶里，`/auth/send-code` 会变成全站每分钟只能发 5 次。常见值：本机 Caddy / Nginx 用 `127.0.0.1/32,::1/128`；Cloudflare / ALB / CloudFront 用各家公开的 CDN IP 段。只有 `RemoteAddr` 落在这些 CIDR 内的请求才被允许通过 `X-Forwarded-For` 改写客户端 IP。
+</Callout>
+
+这里的 `RATE_LIMIT_TRUSTED_PROXIES` 和 `MULTICA_TRUSTED_PROXIES` **不是同一个**变量——后者控制的是 autopilot webhook 端点（`/api/webhooks/autopilots/{token}`）的限流器。两个限流器各自读各自的列表，部署在代理后面的实例需要两个都配上。
+
 ## 守护进程的调节参数
 
 守护进程跑在用户本地机器上，配置也是读本地环境变量。常用的几个：
@@ -148,6 +184,8 @@ Multica 存储用户上传的附件（评论里的图片、文件等）。**优
 | 环境变量 | 默认值 | 说明 |
 |---|---|---|
 | `FRONTEND_ORIGIN` | 空 | 前端地址。邀请邮件里的链接、CORS 白名单、cookie domain 都从这里推导。邮件链接在不设时会 fallback 到托管版域名 `https://app.multica.ai`——self-host 必须显式填 |
+| `MULTICA_APP_URL` | 空 | CLI 登录流程使用的前端 URL。Web UI 也会用它显示带你自己 app domain 的 self-host 守护进程 setup 命令；同源部署中，如果 `MULTICA_PUBLIC_URL` 未设置，它也会作为守护进程的 `server_url` |
+| `MULTICA_PUBLIC_URL` | 空 | 公开 API URL，不带结尾 slash。用于 autopilot webhook URL，也会被 Web UI 用作守护进程的 `server_url` |
 | `CORS_ALLOWED_ORIGINS` | 空 | 额外的 CORS 允许来源（逗号分隔）|
 | `ALLOWED_ORIGINS` | 空 | WebSocket 专用的 origin 白名单（逗号分隔）；不设就按 `CORS_ALLOWED_ORIGINS` → `FRONTEND_ORIGIN` → `localhost:3000/5173/5174` 顺序回落 |
 
@@ -161,12 +199,12 @@ Multica 存储用户上传的附件（评论里的图片、文件等）。**优
 
 | 环境变量 | 默认值 | 说明 |
 |---|---|---|
-| `GITHUB_APP_SLUG` | 空 | 你的 GitHub App slug（`https://github.com/apps/<slug>` 的尾部）。Settings → Integrations 里安装按钮的跳转 URL 用它拼 |
+| `GITHUB_APP_SLUG` | 空 | 你的 GitHub App slug（`https://github.com/apps/<slug>` 的尾部）。Settings → GitHub 里安装按钮的跳转 URL 用它拼 |
 | `GITHUB_WEBHOOK_SECRET` | 空 | 你在 GitHub App 上设置的 Webhook secret。每条 `pull_request` / `installation` delivery 都用它做 HMAC-SHA256 校验；同一个值也用作 setup 回调里 state token 的签名密钥 |
 
 **任一变量未设时：**
 
-- Settings → Integrations 里 `Connect GitHub` 按钮 **disable**，对 admin 显示「not configured」提示
+- Settings → GitHub 里 `Connect GitHub` 按钮 **disable**，对 admin 显示「not configured」提示
 - `/api/webhooks/github` 直接返回 **`503 github webhooks not configured`**——secret 没配置时 Multica 拒绝处理任何 webhook 事件，而不是把所有签名当 valid
 
 **注意：** `GITHUB_WEBHOOK_SECRET` 同时被复用为 install 流程里 state token 的签名密钥，所以运维只需要维护一个 secret。它**不是** GitHub App 的 *Client* secret——Client secret 是 OAuth 用的，和本集成无关。完整配置流程见 [GitHub 集成 → Self-Host 配置](/github-integration#self-host-配置)。

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

@@ -133,6 +133,18 @@ Alternatively, configure step by step: `multica config set server_url http://loc
 3. Go to **Settings → Agents** and create a new agent
 4. Create an issue and assign it to your agent
 
+## Usage Dashboard Rollup (Required)
+
+Starting with `v0.3.5`, the Usage / Runtime dashboards read from a derived `task_usage_hourly` table populated by `rollup_task_usage_hourly()`. The bundled `pgvector/pgvector:pg17` image does **not** include `pg_cron`, and the backend doesn't run the rollup in-process either — until you schedule it yourself, the dashboard will stay at zero even though `task_usage` is populated.
+
+Pick one supported path before relying on the Usage / Runtime dashboard:
+
+- **External cron / systemd-timer / Kubernetes `CronJob`**: schedule `SELECT rollup_task_usage_hourly()` every 5 minutes. Idempotent, watermark-driven — overlapping or skipped ticks are safe.
+- **Postgres with `pg_cron`**: swap the bundled Postgres image for one that ships `pg_cron`, set `shared_preload_libraries=pg_cron`, then `SELECT cron.schedule('rollup_task_usage_hourly', '*/5 * * * *', 'SELECT rollup_task_usage_hourly()')` once.
+- **Backfill historical data**: required on the `v0.3.4 → v0.3.5+` upgrade path when the database already has `task_usage` rows — migration `103` is fail-closed and will abort `migrate up` with `refusing to drop legacy daily rollups: ...` until the hourly table is seeded. Run `./backfill_task_usage_hourly --sleep-between-slices=2s` inside the backend container, then re-run the upgrade and configure one of the schedules above.
+
+Full reference (Compose + Kubernetes templates, flag descriptions, upgrade order) lives in [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup).
+
 ## Stopping Services
 
 ```bash
@@ -219,7 +231,7 @@ For file uploads and attachments, configure S3 and (optionally) CloudFront:
 | `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 |
+| `AWS_ENDPOINT_URL` | Custom S3-compatible endpoint (e.g. MinIO, R2, B2). Setting this switches to path-style URLs |
 | `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/github-integration.ko.mdx

@@ -0,0 +1,183 @@
+---
+title: GitHub 연동
+description: GitHub App을 한 번만 연결하면, 브랜치·제목·본문에 이슈 식별자가 들어간 PR이 해당 이슈에 자동으로 연결됩니다. 그리고 PR을 머지하면 이슈가 완료로 이동합니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+**설정 → GitHub**에서 GitHub 계정 또는 조직을 한 번만 연결하세요. 그 후에는 브랜치 이름, 제목, 본문에 이슈 식별자(예: `MUL-123`)가 들어 있는 모든 pull request가 해당 [이슈](/issues)에 **자동으로 연결**되고, 이슈 사이드바의 **Pull requests** 아래에 표시되며, PR이 머지되면 이슈가 **완료**로 이동합니다.
+
+이슈별 설정은 없습니다. 전체 흐름은 식별자로 동작합니다.
+
+## 연동이 하는 일
+
+| 위치 | 동작 |
+|---|---|
+| **설정 → GitHub** | 워크스페이스 admin에게는 마스터 토글, **Connect GitHub** 버튼, 기능 스위치(PR 사이드바, Co-authored-by, 자동 연결)가 있는 GitHub 탭이 보입니다. 설치 후에는 GitHub 탭으로 다시 돌아옵니다. |
+| **이슈 사이드바 → Pull requests** | 이 이슈에 자동 연결된 모든 PR이 제목, 저장소, 상태(`Open` / `Draft` / `Merged` / `Closed`), 작성자와 함께 표시됩니다. 행을 클릭하면 GitHub의 해당 PR로 이동합니다. |
+| **Webhook(백그라운드)** | 모든 `pull_request` 이벤트에서 Multica는 PR 행을 upsert하고, PR에서 이슈 식별자를 스캔한 뒤, 연결 행을 (다시) 구성합니다. 멱등성이 있어 동일 delivery를 재전송해도 변화가 없습니다. |
+| **머지 시 상태 자동 변경** | PR이 `merged`로 전환되면, 아직 `Done`이나 `Cancelled`가 아닌 모든 연결된 이슈가 `Done`으로 이동합니다. 상태 변경은 source `github_pr_merged`로 타임라인에 기록됩니다. |
+
+미러링되는 것은 PR 자체뿐입니다. 커밋, 열린 PR이 없는 브랜치 ref, CI 체크 상태는 모델링되지 **않습니다**. 이 연동은 의도적으로 좁게 설계되었습니다.
+
+## 식별자 매칭 방식
+
+Webhook은 다음 순서로 세 필드에서 식별자를 추출합니다: **PR head 브랜치**, **PR 제목**, **PR 본문**. 매처는 다음과 같습니다.
+
+- 대소문자를 구분하지 않습니다 — `mul-123`, `MUL-123`, `Mul-123`이 모두 매칭됩니다.
+- 경계가 있습니다 — 왼쪽의 `\b`와 오른쪽의 숫자 앵커 덕분에 `v1.2-3` 같은 버전 번호나 이메일 형식 문자열을 잘못 잡지 않습니다.
+- 워크스페이스 범위로 제한됩니다 — 해당 워크스페이스 고유의 [이슈 prefix](/workspaces)에만 매칭됩니다. prefix가 `MUL`인 워크스페이스에서는 정수가 다른 이슈와 일치하더라도 `FOO-1`이 무시됩니다.
+- 중복이 제거됩니다 — 본문에 `MUL-1, MUL-1`을 나열해도 이슈는 한 번만 연결됩니다.
+
+하나의 PR에서 **여러 이슈**를 참조할 수 있습니다. `Closes MUL-1, MUL-2`는 PR을 두 이슈에 모두 연결하고, 머지하면 두 이슈 모두 `Done`으로 진행됩니다.
+
+## 머지 시 완료 자동 변경 규칙
+
+PR의 `merged` 필드가 `true`로 바뀌면, 연결된 모든 이슈가 평가됩니다.
+
+| 이슈 현재 상태 | 결과 |
+|---|---|
+| `done` | 변화 없음(이미 종료 상태). |
+| `cancelled` | **변화 없음** — 취소됨은 사용자가 작업을 명시적으로 포기했다는 의미이므로, 연동이 이 신호를 덮어쓰지 않습니다. |
+| 그 외 모두(`todo`, `in_progress`, `in_review`, `blocked`, `backlog`) | `done`으로 이동. |
+
+PR을 머지하지 **않고** 닫으면 PR 카드의 상태만 `Closed`로 업데이트됩니다. 연결된 이슈는 그대로 유지됩니다 — 머지 없이 닫는 것이 무엇을 의미하는지는 사용자가 결정합니다.
+
+<Callout type="info">
+이 동작은 타임라인에서 `system` 액터에게 귀속됩니다. 이슈 구독자는 사람이 상태를 옮겼을 때와 동일하게 상태 변경에 대한 인박스 알림을 받습니다.
+</Callout>
+
+## 자동 연결되지 않는 것
+
+- **커밋 메시지의 식별자** — 브랜치 / 제목 / 본문만 스캔됩니다. `MUL-123: fix login`이라는 제목의 커밋은 동일한 문자열이 PR 제목이나 본문에도 나타나지 않는 한 자동 연결되지 않습니다.
+- **PR 댓글의 식별자** — PR 자체의 메타데이터만 스캔되며, 이후의 GitHub 댓글은 무시됩니다.
+- **App이 설치되지 않은 저장소의 PR** — App이 없으면 Multica는 webhook을 전혀 받지 못합니다.
+- **PR을 이슈에 수동으로 연결하기** — 아직 이를 위한 UI는 없습니다. 팀의 규칙상 식별자를 Multica가 읽지 않는 위치에 둔다면, PR 제목이나 본문에 추가하세요.
+
+## 연결 해제
+
+**설정 → GitHub**에는 설치 목록이 없습니다 — 기존 설치는 GitHub에서 직접 관리합니다.
+
+- **GitHub에서** — `https://github.com/settings/installations`(개인) 또는 `https://github.com/organizations/<org>/settings/installations`(조직)에서 Multica GitHub App을 제거합니다. Multica는 `installation.deleted` webhook을 받아 실시간으로 행을 삭제하며, 열려 있는 Settings 탭은 새로고침 없이 업데이트됩니다.
+- **Multica 내부에서의 연결 해제는 admin 전용입니다** — GitHub 탭의 연결 해제 컨트롤은 admin이 아닌 사용자에게는 숨겨집니다. 마스터 GitHub 스위치가 꺼져 있어도 계속 사용할 수 있어, admin이 원클릭으로 기능을 비활성화한 후에도 오래된 설치를 해제할 수 있습니다.
+
+연결 해제 후에도 미러링된 PR 행은 데이터베이스에 남아 과거 이슈 사이드바에서 무엇이 연결되어 있었는지 계속 보여주지만, 해당 설치에서 새로 들어오는 webhook 이벤트는 더 이상 수락되지 않습니다.
+
+## 권한 및 가시성
+
+- **연결 / 연결 해제**에는 워크스페이스 **owner 또는 admin**이 필요합니다. member에게는 카드 설명은 보이지만 Connect 버튼은 보이지 않습니다.
+- 이슈의 **Pull requests** 사이드바는 해당 이슈를 읽을 수 있는 모든 사람에게 보입니다 — 이슈 상세의 나머지 부분과 동일한 권한입니다.
+- GitHub App은 pull request와 메타데이터에 대한 **읽기 전용** 액세스를 요청합니다. Multica는 커밋, 댓글, 상태 체크를 GitHub로 다시 푸시하지 않습니다.
+
+## 자체 호스팅 설정
+
+Multica Cloud에서 Multica를 실행 중이라면 연동이 이미 구성되어 있습니다 — 이 섹션은 건너뛰세요.
+
+자체 호스팅의 경우, GitHub App을 하나 만들고, 서버를 가리키게 한 뒤, 환경 변수 두 개를 설정합니다. 전체 흐름은 아래와 같습니다.
+
+### 1. GitHub App 만들기
+
+다음 중 하나로 이동하세요.
+
+- 개인 계정 → `https://github.com/settings/apps/new`
+- 조직 → `https://github.com/organizations/<org>/settings/apps/new`
+
+다음을 입력하세요.
+
+| 필드 | 값 |
+|---|---|
+| **GitHub App name** | 알아보기 쉬운 이름, 예: `Multica` 또는 `Multica (staging)`. |
+| **Homepage URL** | Multica 프론트엔드, 예: `https://multica.example.com`. |
+| **Callback URL** | 비워 두세요 — Multica는 OAuth 사용자 신원을 사용하지 않습니다. |
+| **Setup URL** | `https://<api-host>/api/github/setup`. **"Redirect on update"를 체크하세요.** |
+| **Webhook → Active** | 활성화. |
+| **Webhook URL** | `https://<api-host>/api/webhooks/github`. |
+| **Webhook secret** | 긴 무작위 문자열을 생성하세요(예: `openssl rand -hex 32`). 2단계에서 동일한 값을 Multica의 env에 붙여넣게 됩니다. |
+| **Permissions → Repository → Pull requests** | **Read-only**. |
+| **Permissions → Repository → Metadata** | Read-only(필수). |
+| **Subscribe to events** | **Pull request**를 체크하세요. |
+| **Where can this GitHub App be installed?** | 선택 사항. 단일 조직 설정에는 `Only on this account`로 충분합니다. |
+
+**Create GitHub App** 후, App 상세 페이지에서 두 가지를 기록해 두세요.
+
+- 상단의 **public link** — 그 꼬리가 slug입니다. `https://github.com/apps/multica-acme` → slug = `multica-acme`.
+- 방금 생성한 **webhook secret**(나중에 GitHub에서 다시 읽을 수 없으니 — 지금 저장하세요).
+
+<Callout type="warning">
+**Webhook secret ≠ Client secret.** App 설정 페이지에는 두 필드가 함께 쌓여 있습니다. **Webhook secret**은 `pull_request` payload에 서명하는 값으로, Multica가 필요로 하는 것입니다. **Client secret**은 OAuth용이며 이 연동에서는 사용되지 않습니다. 이 둘을 혼동하면 모든 webhook delivery에서 혼란스러운 `401 invalid signature`가 발생합니다.
+</Callout>
+
+### 2. 환경 변수 설정
+
+API 서버에서:
+
+```dotenv
+GITHUB_APP_SLUG=multica-acme
+GITHUB_WEBHOOK_SECRET=<the webhook secret you generated>
+```
+
+두 변수 모두 필수입니다. 둘 중 하나라도 누락되면:
+
+- Settings의 `Connect GitHub`이 **비활성화**되고 "not configured" 힌트가 표시됩니다.
+- `/api/webhooks/github` 엔드포인트가 **`503 github webhooks not configured`**를 반환합니다 — Multica는 secret 없이 이벤트를 처리하기를 거부하며, 모든 서명을 조용히 유효한 것으로 취급하지 않습니다.
+
+`FRONTEND_ORIGIN`도 설정되어 있어야 합니다(어떤 프로덕션 자체 호스팅이든 이미 설정되어 있습니다). 설치 후 setup 콜백이 사용자를 `<FRONTEND_ORIGIN>/settings?tab=github`으로 다시 돌려보냅니다.
+
+env 변수를 설정한 후 API를 재시작하세요.
+
+### 3. 마이그레이션 실행
+
+이 연동은 테이블을 마이그레이션 `079_github_integration`으로 제공합니다. 기존 배포를 업그레이드하는 경우:
+
+```bash
+make migrate-up
+```
+
+세 개의 테이블이 생성됩니다: `github_installation`, `github_pull_request`, `issue_pull_request`. 이들은 워크스페이스와 함께 cascade-delete되므로, 워크스페이스를 제거하면 자동으로 정리됩니다.
+
+### 4. UI에서 연결
+
+Multica에서:
+
+1. owner 또는 admin 권한으로 **설정 → GitHub**를 엽니다.
+2. **Connect GitHub**를 클릭합니다. GitHub가 새 탭에서 열립니다.
+3. 액세스를 부여할 저장소를 선택하고 **Install**합니다.
+4. GitHub가 `<api-host>/api/github/setup`으로 리디렉션하여 설치를 기록한 뒤, `<FRONTEND_ORIGIN>/settings?tab=github&github_connected=1`로 돌려보냅니다.
+
+그 후, 브랜치 / 제목 / 본문에 이슈 식별자가 들어 있는 PR을 열어 보세요 — 몇 초 내에 해당 이슈의 상세 페이지에 Pull requests 블록이 나타납니다.
+
+### 5. curl 프로브로 검증
+
+설치 후 GitHub의 **Recent Deliveries** 페이지에서 `401 invalid signature`가 보고된다면, 양쪽의 secret이 다른 것입니다. 어느 쪽이 잘못되었는지 가장 빠르게 찾는 방법은 GitHub를 우회하는 것입니다.
+
+```bash
+SECRET="<the value you put in GITHUB_WEBHOOK_SECRET>"
+BODY='{"zen":"test"}'
+SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')
+curl -i -X POST https://<api-host>/api/webhooks/github \
+  -H "X-Hub-Signature-256: sha256=$SIG" \
+  -H "X-GitHub-Event: ping" \
+  -H "Content-Type: application/json" \
+  -d "$BODY"
+```
+
+| HTTP 상태 | 의미 | 해결 방법 |
+|---|---|---|
+| `200` `{"ok":"pong"}` | 서버가 로드한 secret이 `$SECRET`과 일치합니다. 불일치는 GitHub 쪽에 있습니다. | App → Webhook secret 편집 → **동일한 값을 붙여넣기** → **Save changes**(저장하지 않고 필드 밖을 클릭하면 이전 secret이 유지됩니다). 재전송하세요. |
+| `401 invalid signature` | 서버가 로드한 secret이 생각하는 값이 **아닙니다**. | env 변수가 실행 중인 프로세스에 적용되었는지 확인하세요(예: `kubectl exec` → `echo -n "$GITHUB_WEBHOOK_SECRET" \| wc -c`). 재배포하세요. |
+| `503 github webhooks not configured` | 프로세스에서 `GITHUB_WEBHOOK_SECRET`이 비어 있습니다. | env 변수를 설정하고 API를 재시작하세요. |
+
+## 제한 사항
+
+현재 알아 둬야 할 몇 가지 거친 부분이 있습니다.
+
+- **아직 수동 연결 UI가 없습니다** — PR을 연결하는 유일한 방법은 브랜치, 제목, 본문에 식별자를 두는 것입니다.
+- **CI / 체크 상태가 없습니다** — PR 자체만 미러링됩니다. 빌드 상태, 리뷰 댓글, 리뷰어는 Multica에 표시되지 않습니다.
+- 머지 → 완료 규칙에 대한 **워크스페이스 수준 설정이 없습니다** — 고정된 기본값입니다(`cancelled`가 아닌 한 `merged → done`). 워크스페이스에서 커스터마이즈할 수 있는 매핑은 향후 추가될 예정입니다.
+- **하나의 이슈에 여러 PR이 연결된 경우 머지가 보수적입니다** — 두 PR이 모두 `MUL-123`을 참조하고 첫 번째가 머지되면, 이슈는 즉시 `Done`으로 이동합니다. 진행하기 전에 연결된 모든 PR이 해결되기를 기다리는 후속 변경이 진행 중입니다.
+
+## 다음
+
+- [이슈](/issues) — PR에서 참조하는 이슈 식별자(`MUL-123`)
+- [워크스페이스](/workspaces) — 워크스페이스별 이슈 prefix를 설정하는 곳
+- [환경 변수](/environment-variables) — 위의 GitHub 변수를 포함한 전체 env 참조

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

@@ -5,7 +5,7 @@ description: Connect a GitHub App once, then PRs whose branch, title, or body re
 
 import { Callout } from "fumadocs-ui/components/callout";
 
-Connect a GitHub account or organization once in **Settings → Integrations**. After that, any pull request whose branch name, title, or body contains an issue identifier (for example `MUL-123`) is **auto-linked** to that [issue](/issues), appears under **Pull requests** in the issue sidebar, and — when the PR is merged — moves the issue to **Done**.
+Connect a GitHub account or organization once in **Settings → GitHub**. After that, any pull request whose branch name, title, or body contains an issue identifier (for example `MUL-123`) is **auto-linked** to that [issue](/issues), appears under **Pull requests** in the issue sidebar, and — when the PR is merged — moves the issue to **Done**.
 
 There is no per-issue setup. The whole flow is identifier-driven.
 
@@ -13,7 +13,7 @@ There is no per-issue setup. The whole flow is identifier-driven.
 
 | Surface | Behavior |
 |---|---|
-| **Settings → Integrations** | Workspace admins see a GitHub card with a **Connect GitHub** button. Clicking it opens GitHub's App install page; after install you bounce back to Settings. |
+| **Settings → GitHub** | Workspace admins see the GitHub tab with a master toggle, **Connect GitHub** button, and feature switches (PR sidebar, Co-authored-by, auto-link). After install you bounce back to the GitHub tab. |
 | **Issue sidebar → Pull requests** | Every PR auto-linked to this issue, with title, repo, state (`Open` / `Draft` / `Merged` / `Closed`), and author. Click a row to jump to the PR on GitHub. |
 | **Webhook (background)** | On every `pull_request` event, Multica upserts the PR row, scans the PR for issue identifiers, and (re)builds the link rows. Idempotent — replaying a delivery is a no-op. |
 | **Auto-status on merge** | When a PR transitions to `merged`, every linked issue not already `Done` or `Cancelled` is moved to `Done`. The status change is timeline-logged with source `github_pr_merged`. |
@@ -56,10 +56,10 @@ The action is attributed to the `system` actor on the timeline. Subscribers of t
 
 ## Disconnecting
 
-In **Settings → Integrations** there is no installation list — you manage existing installations from GitHub directly:
+In **Settings → GitHub** there is no installation list — you manage existing installations from GitHub directly:
 
 - **From GitHub** — uninstall the Multica GitHub App at `https://github.com/settings/installations` (personal) or `https://github.com/organizations/<org>/settings/installations` (org). Multica receives the `installation.deleted` webhook and drops the row in real time; any open Settings tab updates without a refresh.
-- **Disconnect from inside Multica is admin-only** — the Settings card is hidden for non-admins.
+- **Disconnect from inside Multica is admin-only** — the Disconnect control on the GitHub tab is hidden for non-admins. It stays available even when the master GitHub switch is off, so admins can still revoke a stale installation after one-click-disabling the feature.
 
 After disconnect, mirrored PR rows stay in the database so historical issue sidebars still show what was linked, but no new webhook events from that installation will be accepted.
 
@@ -121,7 +121,7 @@ Both variables are required. If either is missing:
 - `Connect GitHub` in Settings is **disabled** and shows a "not configured" hint.
 - The `/api/webhooks/github` endpoint returns **`503 github webhooks not configured`** — Multica refuses to process events with no secret, rather than silently treating every signature as valid.
 
-`FRONTEND_ORIGIN` must also be set (it already is for any production self-host); the setup callback bounces the user back to `<FRONTEND_ORIGIN>/settings` after install.
+`FRONTEND_ORIGIN` must also be set (it already is for any production self-host); the setup callback bounces the user back to `<FRONTEND_ORIGIN>/settings?tab=github` after install.
 
 Restart the API after setting the env vars.
 
@@ -139,10 +139,10 @@ Three tables get created: `github_installation`, `github_pull_request`, `issue_p
 
 In Multica:
 
-1. Open **Settings → Integrations** as an owner or admin.
+1. Open **Settings → GitHub** as an owner or admin.
 2. Click **Connect GitHub**. GitHub opens in a new tab.
 3. Pick the repositories to grant access to and **Install**.
-4. GitHub redirects back to `<api-host>/api/github/setup`, which records the installation and bounces you to `<FRONTEND_ORIGIN>/settings?github_connected=1`.
+4. GitHub redirects back to `<api-host>/api/github/setup`, which records the installation and bounces you to `<FRONTEND_ORIGIN>/settings?tab=github&github_connected=1`.
 
 After that, open any PR whose branch / title / body contains an issue identifier — within a few seconds the Pull requests block appears on that issue's detail page.
 

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

@@ -5,7 +5,7 @@ description: 一次性连接 GitHub App，之后 PR 的分支名、标题或正
 
 import { Callout } from "fumadocs-ui/components/callout";
 
-在 **Settings → Integrations** 里一次性连一个 GitHub 账号或组织。之后任何 PR 只要分支名、标题或正文里出现 issue 编号（例如 `MUL-123`），就会**自动关联**到那个 [issue](/issues)，出现在 issue 详情页右侧的 **Pull requests** 区块里——PR 合并时，issue 自动转 **Done**。
+在 **Settings → GitHub** 里一次性连一个 GitHub 账号或组织。之后任何 PR 只要分支名、标题或正文里出现 issue 编号（例如 `MUL-123`），就会**自动关联**到那个 [issue](/issues)，出现在 issue 详情页右侧的 **Pull requests** 区块里——PR 合并时，issue 自动转 **Done**。
 
 没有 per-issue 的配置，整个流程是「编号驱动」的。
 
@@ -13,7 +13,7 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 | 出现位置 | 行为 |
 |---|---|
-| **Settings → Integrations** | 工作区 owner / admin 看到一个 GitHub 卡片，里面有 **Connect GitHub** 按钮。点击会打开 GitHub 的 App 安装页；装好后跳回 Settings。 |
+| **Settings → GitHub** | 工作区 owner / admin 看到 GitHub 这个 tab，里面有主开关、**Connect GitHub** 按钮，以及功能开关（PR 侧栏、Co-authored-by、auto-link）。点 Connect 会打开 GitHub 的 App 安装页；装好后跳回 GitHub tab。 |
 | **Issue 详情侧栏 → Pull requests** | 列出所有自动关联到该 issue 的 PR，含标题、仓库、状态（`Open` / `Draft` / `Merged` / `Closed`）和作者。点一行跳到 GitHub。 |
 | **Webhook（后台）** | 每次 `pull_request` 事件触发：upsert PR 行 → 扫描里面的 issue 编号 →（重新）建立 link。幂等——重投 delivery 不会产生重复记录。 |
 | **Merge 自动改 status** | PR 转 `merged` 时，所有已关联且状态不是 `Done` / `Cancelled` 的 issue 会被推到 `Done`。时间线里以 source 为 `github_pr_merged` 记录。 |
@@ -56,10 +56,10 @@ PR **关闭但没合并**——只更新 PR 卡片的状态为 `Closed`，issue
 
 ## 断开连接
 
-**Settings → Integrations** 里没有 installation 列表——现有 installation 直接到 GitHub 上管理：
+**Settings → GitHub** 里没有 installation 列表——现有 installation 直接到 GitHub 上管理：
 
 - **从 GitHub 卸载** —— 个人在 `https://github.com/settings/installations`、组织在 `https://github.com/organizations/<org>/settings/installations` 卸载 Multica App。Multica 收到 `installation.deleted` webhook 后立刻删行；任何已打开的 Settings tab 实时更新，不用刷新
-- **Multica 这边的断开是 admin only** —— 卡片对非 admin 不显示连接操作
+- **Multica 这边的断开是 admin only** —— GitHub tab 上的 Disconnect 控件对非 admin 不显示；主开关关掉时 Disconnect 仍然可用，方便 admin 一键关闭功能后再单独清理已连接的 installation
 
 断开之后，已经镜像的 PR 行保留在数据库里——历史 issue 侧栏仍能显示当时关联的 PR，但来自这个 installation 的新 webhook 事件不再被接受。
 
@@ -121,7 +121,7 @@ GITHUB_WEBHOOK_SECRET=<你刚生成的 webhook secret>
 - Settings 里 `Connect GitHub` 按钮会被 **disable**，并显示「not configured」提示
 - `/api/webhooks/github` 直接返回 **`503 github webhooks not configured`**——Multica 在 secret 没配置时拒绝处理事件，不会出现「没 secret 也接受 webhook」的安全坑
 
-`FRONTEND_ORIGIN` 也必须设置（任何生产 self-host 都已经设了）——setup 回调结束后用它把用户跳回 `<FRONTEND_ORIGIN>/settings`。
+`FRONTEND_ORIGIN` 也必须设置（任何生产 self-host 都已经设了）——setup 回调结束后用它把用户跳回 `<FRONTEND_ORIGIN>/settings?tab=github`。
 
 设完 env 重启 API。
 
@@ -139,10 +139,10 @@ make migrate-up
 
 到 Multica：
 
-1. 以 owner 或 admin 身份打开 **Settings → Integrations**
+1. 以 owner 或 admin 身份打开 **Settings → GitHub**
 2. 点 **Connect GitHub**，GitHub 在新 tab 打开
 3. 选择要授权的仓库，点 **Install**
-4. GitHub 跳回 `<api-host>/api/github/setup`，落库后再跳到 `<FRONTEND_ORIGIN>/settings?github_connected=1`
+4. GitHub 跳回 `<api-host>/api/github/setup`，落库后再跳到 `<FRONTEND_ORIGIN>/settings?tab=github&github_connected=1`
 
 之后在任意一个仓库开一个分支 / 标题 / 正文带本工作区 issue 编号的 PR——几秒内对应 issue 的详情页上就能看到 Pull requests 区块。
 

apps/docs/content/docs/how-multica-works.ko.mdx

@@ -0,0 +1,54 @@
+---
+title: Multica의 작동 방식
+description: 세 가지 핵심 구성 요소(서버 / 데몬 / AI 코딩 도구)가 어떻게 협력하여 에이전트의 작업을 실행하는지 설명합니다.
+---
+
+import { ArchitectureDiagram } from "@/components/architecture-diagram";
+
+Multica는 **분산형** 플랫폼입니다. 여러분이 보는 웹 인터페이스는 겉으로 드러난 부분일 뿐이고, 실제 작업은 세 가지 구성 요소가 처리합니다. **Multica 서버**는 데이터를 소유합니다([워크스페이스](/workspaces), [이슈](/issues), [멤버](/members-roles), [작업](/tasks) 대기열 등). **[데몬](/daemon-runtimes)**은 여러분 자신의 기기에서 실행되며 작업을 가져와 AI 코딩 도구를 구동합니다. 그리고 **[AI 코딩 도구](/providers)**(Claude Code, Codex, 그 밖의 로컬 CLI)는 실제로 코드를 작성하는 구성 요소입니다. 이것이 Multica와 Linear 또는 Jira의 가장 큰 차이입니다. **[에이전트](/agents)는 우리 서버가 아니라 여러분의 기기에서 실행됩니다.**
+
+## 세 가지 핵심 구성 요소
+
+<ArchitectureDiagram />
+
+- **Multica 서버** — 여러분이 보는 워크스페이스, 이슈 목록, 댓글 스레드는 모두 이곳의 데이터베이스에 저장됩니다. 또한 여러분과 동료 사이의 실시간 업데이트를 푸시하는 WebSocket 허브이기도 합니다. 에이전트 작업은 **실행하지 않습니다.**
+- **데몬** — Multica CLI의 일부로, 여러분 자신의 기기에서 실행됩니다. 시작 시 로컬에 설치된 AI 코딩 도구를 감지하고, 서버에 등록한 다음, 3초마다 작업을 폴링하고 15초마다 하트비트를 전송하기 시작합니다.
+- **AI 코딩 도구** — 다음 열두 가지 중 하나(또는 여러 개를 병렬로): [Antigravity](/providers#antigravity), [Claude Code](/providers#claude-code), [Codex](/providers#codex), [Cursor](/providers#cursor), [Copilot](/providers#copilot), [Gemini](/providers#gemini), [Hermes](/providers#hermes), [Kimi](/providers#kimi), [Kiro CLI](/providers#kiro-cli), [OpenCode](/providers#opencode), [OpenClaw](/providers#openclaw), [Pi](/providers#pi). 데몬이 작업을 가져온 뒤에는 이러한 도구를 사용해 실제 작업을 수행합니다.
+
+도구 체인이 로컬에 유지되므로 **여러분의 API 키, 코드 디렉터리, 인증된 도구**는 오직 여러분의 기기에서만 사용됩니다. Multica 서버는 그중 어떤 것도 보지 못합니다. 이는 자체 호스팅을 하든 Cloud를 사용하든 동일하게 적용됩니다.
+
+## 작업의 수명 주기
+
+가장 흔한 시나리오인, 이슈를 에이전트에게 할당하는 경우를 살펴보겠습니다.
+
+1. 여러분이 웹 UI에서 할당을 클릭합니다. 브라우저가 Multica 서버로 HTTP 요청을 보냅니다.
+2. 서버가 해당 이슈의 담당자를 에이전트로 설정하고, 동시에 작업 대기열에 상태 `queued`인 실행 작업을 생성합니다.
+3. 여러분의 기기에 있는 데몬이 다음 폴링(3초 이내) 때 작업을 가져옵니다. 작업 상태가 `dispatched`로 바뀝니다.
+4. 데몬이 로컬에 격리된 작업 디렉터리를 생성하고 해당 AI 코딩 도구를 호출합니다. 작업 상태가 `running`으로 바뀝니다.
+5. AI가 로컬에서 코드를 작성하고, 테스트를 실행하고, 댓글을 서버로 다시 게시합니다.
+6. 실행이 종료됩니다. 데몬이 결과(성공 / 실패)를 서버에 보고하고, 작업 상태가 `completed` 또는 `failed`로 바뀝니다. 여러분은 웹 UI에서 진행 상황 업데이트를 실시간으로(WebSocket을 통해) 확인합니다.
+
+자세한 동작 원리는 [데몬과 런타임](/daemon-runtimes) 및 [작업](/tasks)을 참조하세요.
+
+## 에이전트를 작동시키는 네 가지 방법
+
+"이슈 할당"만 있는 것은 아닙니다. Multica에는 협업 스타일별로 하나씩, 4가지 트리거가 있습니다.
+
+| 방법 | 일반적인 시나리오 | 문서 |
+|---|---|---|
+| **이슈 할당** | 가장 흔한 방법. 이슈를 에이전트에게 할당하면 스스로 작업을 시작합니다 | [이슈 할당하기](/assigning-issues) |
+| **댓글에서 에이전트 @멘션** | "이거 한번 봐 줘" — 담당자나 상태를 바꾸지 않고 댓글 하나로 실행을 시작합니다 | [에이전트 멘션하기](/mentioning-agents) |
+| **다이렉트 채팅** | 이슈에 묶이지 않은 독립적인 대화 — 질문하거나, 이슈 초안을 작성하게 합니다 | [채팅](/chat) |
+| **오토파일럿(예약)** | 상시 지시 — "매주 월요일 아침에 스탠드업 요약을 해 줘" 같은 것 | [오토파일럿](/autopilots) |
+
+## 런타임: 어디서 실행되고, 도구는 몇 개인가
+
+**런타임**은 "데몬 × 하나의 AI 코딩 도구"의 조합입니다. 한 기기의 데몬에 Claude Code와 Codex가 모두 설치되어 있고 두 개의 워크스페이스에 참여해 있다면, Multica는 4개의 독립적인 런타임(워크스페이스 2개 × 도구 2개)을 등록합니다.
+
+현재는 **로컬 데몬** 런타임 모델만 지원됩니다. 클라우드 런타임(여러분 자신의 기기를 켜 둘 필요가 없는 방식)은 **곧 제공될 예정**이며, 현재는 대기자 명단 등록만 받고 있습니다. [다운로드](https://multica.ai/download) 페이지에서 신청하세요.
+
+## 다음 단계
+
+- [Cloud Quickstart](/cloud-quickstart) — 5분 만에 Multica Cloud에 연결하기
+- [Self-Host Quickstart](/self-host-quickstart) — 자체 백엔드 실행하기
+- [데몬과 런타임](/daemon-runtimes) — 아키텍처가 의존하는 구성 요소에 대한 심층 분석