refactor(server/lark): collapse HTTP_ENABLED + WS_ENABLED into the SECRET_KEY gate (MUL-2671)

MULTICA_LARK_HTTP_ENABLED and MULTICA_LARK_WS_ENABLED were staging
knobs from the multi-PR rollout of the Lark MVP — they let the DB
schema + inbound dispatcher land before the HTTP wire was real, and
before the WS long-conn protocol was wired. Now that the MVP has
shipped end-to-end, "I set SECRET_KEY but I don't want to talk to
Lark" is not a useful production state: setting the at-rest master
key is the operator's opt-in for the integration as a whole.

Collapse the gate down to MULTICA_LARK_SECRET_KEY alone. When the
key is present, wire the real HTTPAPIClient + the real
WSLongConnConnector. CI / integration tests that want stub-style
behaviour can point MULTICA_LARK_HTTP_BASE_URL at a mock server
(already supported) instead of toggling a separate flag. Host
overrides (HTTP_BASE_URL, REGISTRATION_DOMAIN, CALLBACK_BASE_URL)
stay — those are real ops needs for international tenants / staging.

stubAPIClient + NoopConnectorFactory remain exported because the
test suite uses them directly; only the router boot path stops
reaching for them. The connector factory keeps its noop fallback
for the case where the endpoint fetcher fails to construct, so a
malformed MULTICA_LARK_CALLBACK_BASE_URL degrades gracefully
(visible as "connector=noop" in the boot log) instead of panicking
the server.

Lark integration + handler tests still pass; go vet clean.

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

.env.example

@@ -21,16 +21,11 @@ APP_ENV=
 # 888888 and keep APP_ENV non-production. This is ignored when APP_ENV=production.
 MULTICA_DEV_VERIFICATION_CODE=
 PORT=8080
-# Docker Compose consumes flat port values. Set BACKEND_PORT directly to
-# override the backend host port.
-BACKEND_PORT=8080
-# Optional aliases for local/self-host backend port helpers outside compose.
+# 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
-FRONTEND_PORT=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:${FRONTEND_PORT}
 # 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.
@@ -40,9 +35,9 @@ JWT_SECRET=change-me-in-production
 # 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_ORIGIN.
+# 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=${FRONTEND_ORIGIN}
+# 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
@@ -100,16 +95,12 @@ RESEND_FROM_EMAIL=noreply@multica.ai
 #       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_EHLO_NAME is the EHLO/HELO name announced to the relay. Defaults to the
-#     machine hostname; set a real FQDN when a strict relay (e.g. Google Workspace
-#     smtp-relay.gmail.com) rejects the default and the connection drops as an EOF.
 SMTP_HOST=
 SMTP_PORT=25
 SMTP_USERNAME=
 SMTP_PASSWORD=
 SMTP_TLS_INSECURE=false
 SMTP_TLS=
-SMTP_EHLO_NAME=
 
 # Google OAuth
 # The web login page reads GOOGLE_CLIENT_ID from /api/config at runtime, so
@@ -117,9 +108,9 @@ SMTP_EHLO_NAME=
 # rebuild is needed.
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
-# Derived by docker-compose.selfhost.yml / local scripts from FRONTEND_ORIGIN.
+# 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=${FRONTEND_ORIGIN}/auth/callback
+# GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
 
 # S3 / CloudFront
 # S3_BUCKET — bucket NAME only (e.g. "my-bucket"). Do NOT include the
@@ -127,15 +118,6 @@ GOOGLE_REDIRECT_URI=${FRONTEND_ORIGIN}/auth/callback
 # from S3_BUCKET + S3_REGION. S3_REGION must match the bucket's real region.
 S3_BUCKET=
 S3_REGION=us-west-2
-AWS_ACCESS_KEY_ID=
-AWS_SECRET_ACCESS_KEY=
-# AWS_ENDPOINT_URL — optional S3-compatible endpoint (MinIO, RustFS, R2, etc.).
-# For internal Docker/VPC hosts such as http://rustfs:9000, leave
-# ATTACHMENT_DOWNLOAD_MODE=auto or set proxy explicitly so browsers/CLI do
-# not need direct access to the object store.
-AWS_ENDPOINT_URL=
-ATTACHMENT_DOWNLOAD_MODE=auto
-ATTACHMENT_DOWNLOAD_URL_TTL=30m
 CLOUDFRONT_KEY_PAIR_ID=
 CLOUDFRONT_PRIVATE_KEY_SECRET=multica/cloudfront-signing-key
 CLOUDFRONT_PRIVATE_KEY=
@@ -206,35 +188,12 @@ CORS_ALLOWED_ORIGINS=
 # GITHUB_APP_SLUG is the tail of https://github.com/apps/<slug>.
 GITHUB_APP_SLUG=
 GITHUB_WEBHOOK_SECRET=
-# Optional: GitHub App identity for App-authenticated REST calls. When set,
-# the setup callback enriches the installation row with the real account
-# login (org / user name) immediately after install. When unset, the row
-# is created with the "unknown" placeholder and the next `installation`
-# webhook from GitHub overwrites it — set both to skip that interim flash.
-# GITHUB_APP_ID is the numeric "App ID" shown on the App's settings page.
-# GITHUB_APP_PRIVATE_KEY is the full PEM block (including BEGIN/END lines)
-# generated under "Private keys" on that same page; preserve newlines.
-GITHUB_APP_ID=
-GITHUB_APP_PRIVATE_KEY=
-
-# Lark / Feishu bot integration (Settings → Integrations "Bind to Lark")
-# Off until MULTICA_LARK_SECRET_KEY is set — a base64-encoded 32-byte key
-# that encrypts each Bot's app secret at rest. Leave empty to disable.
-# Generate one with: openssl rand -base64 32
-MULTICA_LARK_SECRET_KEY=
-# Mainland 飞书 and international Lark are auto-detected per installation
-# (at QR scan) and served side by side — LEAVE THESE EMPTY for normal use.
-# They are optional deployment-wide overrides that force EVERY installation
-# onto one host (a proxy, a mock for tests, or a single-cloud staging
-# setup); HTTP drives outbound Open Platform API calls, CALLBACK the inbound
-# long-conn bootstrap. NOTE: if you previously ran international Lark by
-# setting these to https://open.larksuite.com, the server relabels your
-# existing installs to region=lark on first boot after upgrade, so you can
-# clear these afterwards. See docs/lark-bot-integration.
-MULTICA_LARK_HTTP_BASE_URL=
-MULTICA_LARK_CALLBACK_BASE_URL=
 
 # Frontend
+FRONTEND_PORT=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.
 # NEXT_PUBLIC_API_URL also feeds the Next.js SSR proxy when explicitly set.
 NEXT_PUBLIC_API_URL=

.github/workflows/ci.yml

@@ -98,7 +98,7 @@ jobs:
         run: cd server && go run ./cmd/migrate up
 
       - name: Test
-        run: cd server && go test -race ./...
+        run: cd server && go test ./...
 
   installer:
     # Stub-driven shell tests for scripts/install.sh. Kept off the heavy

.github/workflows/mobile-verify.yml

@@ -13,9 +13,8 @@ name: Mobile Verify
 # - pnpm-workspace.yaml           — catalog versions
 # - turbo.json                    — turbo task pipeline
 #
-# Mobile's vitest suite is intentionally narrow (Node env, pure-function
-# tests under apps/mobile/lib/*.test.ts — see apps/mobile/vitest.config.ts).
-# RN component-level rendering is not exercised here.
+# Mobile has no vitest suite today; if one lands, add `test` to the turbo
+# task list below.
 
 on:
   push:
@@ -62,5 +61,5 @@ jobs:
       - name: Install dependencies
         run: pnpm install
 
-      - name: Type check, lint, and test
-        run: pnpm exec turbo typecheck lint test --filter=@multica/mobile
+      - name: Type check and lint
+        run: pnpm exec turbo typecheck lint --filter=@multica/mobile

.github/workflows/release.yml

@@ -52,7 +52,7 @@ jobs:
           cache-dependency-path: server/go.sum
 
       - name: Run tests
-        run: cd server && go test -race ./...
+        run: cd server && go test ./...
 
   release:
     needs: verify

AGENTS.md

@@ -3,10 +3,8 @@
 This file provides guidance to AI agents when working with code in this repository.
 
 > **Single source of truth:** This file is a concise pointer document.
-> All authoritative architecture, coding rules, and conventions
+> All authoritative architecture, coding rules, commands, and conventions
 > live in **CLAUDE.md** at the project root. Read that file first.
-> Use `Makefile`, `package.json`, and `pnpm-workspace.yaml` as the
-> source of truth for the full command list.
 
 ## Quick Reference
 
@@ -14,27 +12,27 @@ This file provides guidance to AI agents when working with code in this reposito
 
 Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.
 
-- `server/` - Go backend (Chi router, sqlc, gorilla/websocket)
-- `apps/web/` - Next.js frontend (App Router)
-- `apps/desktop/` - Electron desktop app
-- `packages/core/` - Headless business logic (Zustand stores, React Query hooks, API client)
-- `packages/ui/` - Atomic UI components (shadcn/Base UI, zero business logic)
-- `packages/views/` - Shared business pages/components
-- `packages/tsconfig/` - Shared TypeScript config
+- `server/` — Go backend (Chi router, sqlc, gorilla/websocket)
+- `apps/web/` — Next.js frontend (App Router)
+- `apps/desktop/` — Electron desktop app
+- `packages/core/` — Headless business logic (Zustand stores, React Query hooks, API client)
+- `packages/ui/` — Atomic UI components (shadcn/Base UI, zero business logic)
+- `packages/views/` — Shared business pages/components
+- `packages/tsconfig/` — Shared TypeScript config
 
 ### State Management (critical)
 
 - **React Query** owns all server state (issues, members, agents, inbox, workspace list)
 - **Zustand** owns all client state (current workspace selection, view filters, drafts, modals)
-- All Zustand stores live in `packages/core/` - never in `packages/views/` or app directories
-- WS events invalidate React Query - never write directly to stores
+- All Zustand stores live in `packages/core/` — never in `packages/views/` or app directories
+- WS events invalidate React Query — never write directly to stores
 
 ### Package Boundaries (hard rules)
 
-- `packages/core/` - zero react-dom, zero localStorage, zero process.env
-- `packages/ui/` - zero `@multica/core` imports
-- `packages/views/` - zero `next/*`, zero `react-router-dom`, use `NavigationAdapter` for routing
-- `apps/web/platform/` - only place for Next.js APIs
+- `packages/core/` — zero react-dom, zero localStorage, zero process.env
+- `packages/ui/` — zero `@multica/core` imports
+- `packages/views/` — zero `next/*`, zero `react-router-dom`, use `NavigationAdapter` for routing
+- `apps/web/platform/` — only place for Next.js APIs
 
 ### Commands
 
@@ -46,4 +44,4 @@ make test             # Go tests
 make check            # Full verification pipeline
 ```
 
-See CLAUDE.md for the authoritative rules and common commands.
+See CLAUDE.md for the complete command reference.

CLAUDE.md

@@ -1,226 +1,427 @@
 # CLAUDE.md
 
-Guidance for Claude Code when working in this repository. Keep this file short and authoritative: rules here should be hard to infer from code or easy to get wrong.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Conventions
+## Conventions reference
 
-The source of truth for code naming, i18n glossary, and Chinese product voice is:
+The single source of truth for **code naming, the i18n translation glossary, and the Chinese voice guide** is the docs site:
 
-- `apps/docs/content/docs/developers/conventions.mdx`
-- `apps/docs/content/docs/developers/conventions.zh.mdx`
+- **`apps/docs/content/docs/developers/conventions.mdx`** (English)
+- **`apps/docs/content/docs/developers/conventions.zh.mdx`** (Chinese)
 
-Read it before editing translations in `packages/views/locales/`, naming routes/packages/files/DB columns/types, or writing Chinese UI/docs copy. Do not rely on `packages/views/locales/glossary.md`; it is only a redirect stub.
+Read that page before:
 
-## Project Shape
+- Writing or editing translations (`packages/views/locales/`)
+- Naming a new route, package, file, DB column, or TS type
+- Writing Chinese product copy (UI strings, error messages, docs)
 
-Multica is an AI-native task management platform for small teams, with agents as first-class assignees that can own issues, comment, and change status.
+The legacy `packages/views/locales/glossary.md` is now a stub redirecting to the docs page; do not rely on it.
 
-- `server/`: Go backend, Chi router, sqlc, gorilla/websocket.
-- `apps/web/`: Next.js App Router.
-- `apps/desktop/`: Electron desktop app.
-- `apps/mobile/`: Expo / React Native iOS app. Read `apps/mobile/CLAUDE.md` before touching it.
-- `packages/core/`: headless business logic, API client, React Query hooks, Zustand stores.
-- `packages/ui/`: atomic UI components only.
-- `packages/views/`: shared business pages/components for web and desktop.
-- `packages/tsconfig/`: shared TypeScript config.
+## Project Context
 
-Shared packages export raw `.ts` / `.tsx` and are compiled by consuming apps. Dependency direction is `views -> core + ui`; `core` and `ui` must stay independent.
+Multica is an AI-native task management platform — like Linear, but with AI agents as first-class citizens.
 
-## State Rules
+- Agents can be assigned issues, create issues, comment, and change status
+- Supports local (daemon) and cloud agent runtimes
+- Built for 2-10 person AI-native teams
 
-Keep server state and client state separate.
+## Architecture
 
-- TanStack Query owns server state: issues, users, workspaces, inbox, agents, members, and anything fetched from the API.
-- Zustand owns client state: selected workspace, filters, drafts, modals, tab layout, and navigation history.
-- Shared Zustand stores live in `packages/core/`, never in `packages/views/` or app directories.
-- React Context is for platform plumbing only, such as `WorkspaceIdProvider` and `NavigationProvider`.
-- Only auth/workspace stores may call `api.*` directly. Other server interaction belongs in queries/mutations.
-- Workspace-scoped query keys must include `wsId`.
-- Mutations should be optimistic by default: patch locally, send request, roll back on failure, invalidate on settle.
-- WebSocket events invalidate or patch Query cache; they never write directly to Zustand stores.
-- Persist durable preferences/drafts/layout. Do not persist server data or ephemeral UI state.
-- Zustand selectors must return stable references. Do not return freshly allocated objects/arrays from selectors without shallow comparison.
-- Hooks that need workspace context should accept `wsId`; do not call `useWorkspaceId()` internally unless the hook is guaranteed to run under the provider.
+**Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.**
 
-## Package Boundaries
+- `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)
+- `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
 
-These are hard constraints:
+What lives where for sharing purposes is documented in *Sharing Principles* below — read it once.
 
-- `packages/core/`: no `react-dom`, `localStorage` (use `StorageAdapter`), `process.env`, or UI libraries.
-- `packages/ui/`: no `@multica/core` imports and no business logic.
-- `packages/views/`: no `next/*`, no `react-router-dom`, no stores. Use `NavigationAdapter`, `useNavigation()`, and `<AppLink>`.
-- `apps/web/platform/`: only place for Next.js navigation/platform APIs.
-- `apps/desktop/src/renderer/src/platform/`: only place for `react-router-dom` navigation wiring.
-- Every workspace under `apps/` and `packages/` must declare directly imported external packages in its own `package.json`.
-- Shared dependencies use `catalog:` from `pnpm-workspace.yaml`; `apps/mobile/` pins Expo/React Native related versions directly.
+### Key Architectural Decisions
 
-## Sharing Rules
+**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.
 
-Web and desktop share business logic, hooks, stores, components, and views through `packages/core/`, `packages/ui/`, and `packages/views/`.
+**Dependency direction:** `views/ → core/ + ui/`. Core and UI are independent of each other. No package imports from `next/*`, `react-router-dom`, or app-specific code.
 
-If the same logic exists in both web and desktop, extract it unless it depends on platform APIs:
+**Platform bridge:** `packages/core/platform/` provides `CoreProvider` — initializes API client, auth/workspace stores, WS connection, and QueryClient. Each app wraps its root with `<CoreProvider>` and provides its own `NavigationAdapter` for routing.
 
-1. Next.js, Electron, or router APIs stay in the app/platform layer.
-2. Headless logic belongs in `packages/core/`.
-3. Shared UI or business views belong in `packages/views/`.
-4. Shared primitives belong in `packages/ui/`.
+**pnpm catalog** — `pnpm-workspace.yaml` defines `catalog:` for version pinning. All shared deps use `catalog:` references to guarantee a single version across all packages. When adding new shared deps (including test deps), add to catalog first.
 
-Mobile is independent. It may import types and pure functions from `@multica/core`, with `import type` for types, but owns its UI, state, hooks, providers, i18n, React version, build pipeline, and release cadence.
+### State Management
+
+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 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.
+
+**Hard rules — these are how the architecture stays coherent:**
+
+- **Never duplicate server data into Zustand.** If it came from the API, it belongs in the Query cache. Copying it into a store creates two sources of truth and they will drift.
+- **Workspace-scoped queries must key on `wsId`.** This is what makes workspace switching automatic — the cache key changes, the right data appears, no manual invalidation needed.
+- **Mutations are optimistic by default.** Apply the change locally, send the request, roll back on failure, invalidate on settle. The user shouldn't wait for the server.
+- **WS events invalidate queries — they never write to stores directly.** This keeps the cache as the single source of truth and avoids race conditions.
+- **Persist what's worth preserving across restarts** (user preferences, drafts, tab layout). **Don't persist ephemeral UI state** (modal open/close, transient selections) or server data.
+
+**Common Zustand footguns to avoid:**
+
+- 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
 
-Use the repo scripts as the source of truth. Common commands:
-
 ```bash
-make dev              # auto-setup and start the app
-make start            # start backend + frontend
-make stop             # stop app processes for this checkout
-make server           # run Go server only
-make daemon           # run local daemon
-make test             # Go tests
-make sqlc             # regenerate sqlc code after SQL changes
+# One-command dev (auto-setup + start everything)
+make dev              # Auto-creates env, installs deps, starts DB, migrates, launches app
+
+# Explicit setup & run (if you prefer separate steps)
+make setup            # First-time: ensure shared DB, create app DB, migrate
+make start            # Start backend + frontend together
+make stop             # Stop app processes for the current checkout
+make db-down          # Stop the shared PostgreSQL container
+
+# Frontend (all commands go through Turborepo)
 pnpm install
-pnpm dev:web
-pnpm dev:desktop
-pnpm build
-pnpm typecheck
-pnpm lint
-pnpm test             # TS/Vitest tests through Turborepo
-pnpm exec playwright test
-pnpm ui:add badge     # shadcn/Base UI component into packages/ui
+pnpm dev:web          # Next.js dev server (port 3000)
+pnpm dev:desktop      # Electron dev (electron-vite, HMR)
+pnpm build            # Build all frontend apps
+pnpm typecheck        # TypeScript check (all packages + apps via turbo)
+pnpm lint             # ESLint
+pnpm test             # TS tests (Vitest, all packages + apps via turbo)
+
+# Backend (Go)
+make server           # Run Go server only (port 8080)
+make daemon           # Run local daemon
+make build            # Build server + CLI binaries to server/bin/
+make cli ARGS="..."   # Run multica CLI (e.g. make cli ARGS="config")
+make test             # Go tests
+make sqlc             # Regenerate sqlc code after editing SQL in server/pkg/db/queries/
+make migrate-up       # Run database migrations
+make migrate-down     # Rollback migrations
+
+# Run a single TS test (works for any package with a test script)
+pnpm --filter @multica/views exec vitest run auth/login-page.test.tsx
+pnpm --filter @multica/core exec vitest run runtimes/version.test.ts
+pnpm --filter @multica/web exec vitest run app/\(auth\)/login/page.test.tsx
+
+# Run a single Go test
+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)
+
+# shadcn — config lives in packages/ui/components.json (Base UI variant, base-nova style)
+pnpm ui:add badge                # Adds component to packages/ui/components/ui/
+
+# Infrastructure
+make db-up            # Start shared PostgreSQL (pgvector/pg17 image)
+make db-down          # Stop shared PostgreSQL
+make db-reset         # Drop + recreate current env's DB, then re-run migrations (local only; stop backend first)
 ```
 
-Worktrees share one PostgreSQL container and get isolated DB names/ports via `.env.worktree`. `make dev` auto-detects this. For manual setup use `make worktree-env`, `make setup-worktree`, and `make start-worktree`.
+### CI Requirements
 
-CI runs Node 22, Go 1.26.1, and a `pgvector/pgvector:pg17` PostgreSQL service.
+CI runs on Node 22 and Go 1.26.1 with a `pgvector/pgvector:pg17` PostgreSQL service. See `.github/workflows/ci.yml`.
+
+### Worktree Support
+
+All checkouts share one PostgreSQL container. Isolation is at the database level — each worktree gets its own DB name and unique ports via `.env.worktree`. Main checkouts use `.env`.
+
+`make dev` auto-detects worktrees and handles everything. For explicit control:
+
+```bash
+make worktree-env       # Generate .env.worktree with unique DB/ports
+make setup-worktree     # Setup using .env.worktree
+make start-worktree     # Start using .env.worktree
+```
 
 ## Coding Rules
 
 - TypeScript strict mode is enabled; keep types explicit.
-- Go follows standard conventions: `gofmt`, `go vet`, checked errors.
-- Code comments must be English.
-- Prefer existing patterns/components over new parallel abstractions.
+- Go code follows standard Go conventions (gofmt, go vet).
+- Keep comments in code **English only**.
+- Prefer existing patterns/components over introducing parallel abstractions.
+- Unless the user explicitly asks for backwards compatibility, do **not** add compatibility layers, fallback paths, dual-write logic, legacy adapters, or temporary shims **for internal, non-boundary code** (a function calling another function in the same package, a component reading its own state, a store helper, etc.).
+- This rule does **not** apply at API boundaries: the desktop app cannot assume the backend it talks to has the same shape as the one it was built against (older desktop installs will outlive any given server build). API response handling must follow the rules in **API Response Compatibility** below — that is a defensive boundary, not a legacy shim.
+- If a flow or API is being replaced and the product is not yet live, prefer removing the old path instead of preserving both old and new behavior.
 - Avoid broad refactors unless required by the task.
-- For internal, non-boundary code, do not add compatibility layers, fallback paths, dual writes, legacy adapters, or temporary shims unless explicitly requested.
-- API boundaries are different: installed desktop clients can talk to newer backends, so response parsing must follow the API compatibility rules below.
-- If a flow or API is being replaced and the product is not live, prefer removing the old path instead of preserving both.
-- New global pre-workspace routes must be a single word (`/login`, `/inbox`) or `/{noun}/{verb}` (`/workspaces/new`). Do not add hyphenated root routes like `/new-workspace`.
-- Reserved slugs live in `server/internal/handler/reserved_slugs.json`. Edit it, run `pnpm generate:reserved-slugs`, and commit the generated `packages/core/paths/reserved-slugs.ts`.
-- When changing CLI commands/flags, API fields, or product behavior documented by built-in skills under `server/internal/service/builtin_skills/*`, update the relevant `SKILL.md` and `references/*-source-map.md` in the same PR.
+- New global (pre-workspace) routes MUST use a single word (`/login`, `/inbox`) or a `/{noun}/{verb}` pair (`/workspaces/new`). NEVER add hyphenated word-group root routes (`/new-workspace`, `/create-team`) — they collide with common user workspace names and force endless reserved-slug audits. Reserving the noun (`workspaces`) automatically protects the entire `/workspaces/*` subtree.
+- The reserved-slug list lives in **one** place: `server/internal/handler/reserved_slugs.json`. The Go side embeds the JSON; `packages/core/paths/reserved-slugs.ts` is generated from it by `pnpm generate:reserved-slugs`. Edit the JSON, run the generator, commit both. CI re-runs the generator and fails on any drift, so a stale TS file cannot land.
+- When you change a CLI command or flag, an API request/response field, or product behavior that a built-in skill documents (`server/internal/service/builtin_skills/*`), update that skill's `SKILL.md` **and** its `references/*-source-map.md` in the same PR. The built-in skills are source-traced contracts shipped to agents — if the code moves and the skill doesn't, it silently teaches stale behavior.
 
-## API Compatibility
+### API Response Compatibility
 
-Frontend code must survive backend response drift, especially in installed desktop builds.
+The desktop app installed on a user's machine is older than any backend it talks to: a user on 0.2.26 will hit a server running 0.3.x, then 0.4.x, then beyond. Every response shape is a contract that **will** drift, and the frontend must survive drift without white-screening. Three concrete incidents already happened from violating this — #2143, #2147, #2192.
 
-- Parse API JSON with `parseWithFallback` in `packages/core/api/schema.ts` and a zod schema. Do not cast network JSON to `T`.
-- Endpoint responses consumed by UI logic must pass through a schema before returning.
-- Downstream UI should optional-chain and default fields defensively.
-- Prefer explicit boolean checks (`=== true`) over truthy/falsy checks on server fields.
-- Do not pin critical affordances to one backend boolean; combine signals when possible.
-- Server-driven enum switches need a `default` branch.
-- When adding or changing an endpoint, add/update the schema and include a malformed-response test.
+When writing code that consumes an API response, follow these rules:
 
-## Backend UUID Rules
+- **Parse, don't cast.** Untyped JSON crossing the network is not `T`. Use `parseWithFallback` in `packages/core/api/schema.ts` with a `zod` schema and an explicit fallback. On validation failure it logs a warning and returns the fallback; it never throws into the UI.
+- **No bare `as` casts on response bodies.** Every endpoint method whose response is consumed by UI logic must run through a schema before returning.
+- **Optional-chain and default everywhere downstream.** Treat every field as possibly missing. Use explicit boolean checks (`=== true`) over truthy/falsy negation, which silently treats `undefined` and `null` as `false`.
+- **Don't pin a UI affordance to a single backend field.** If a button or indicator depends on exactly one boolean from the server, a backend bug deletes it. Combine signals (cursor presence, page length, etc.) so the affordance stays available in the worst case.
+- **Enum drift downgrades, not crashes.** A new server-side enum value should render a generic fallback. `switch` statements on server-driven strings must have a `default` branch.
+- **When you add or change an endpoint:** add the schema in the same PR, and write at least one test that feeds a malformed response through it (missing field, wrong type, `null` array). The test fails closed if a future change breaks the contract.
 
-In `server/internal/handler/`, always know where a UUID came from before using it in write queries.
+This is not premature defense — it is the *only* defense for an installed-app architecture. CSR-only browser apps can ship a fix in minutes; an Electron build sitting on a developer's laptop cannot.
 
-- Resource path params that may be UUIDs or human-readable IDs must be resolved through loaders such as `loadIssueForUser`, `loadSkillForUser`, `loadAgentForUser`, or `requireDaemonRuntimeAccess`; subsequent writes use the resolved `entity.ID`.
-- Pure UUID inputs from request boundaries use `parseUUIDOrBadRequest(w, s, fieldName)` and return immediately on `ok=false`.
-- Trusted UUID round-trips from sqlc results or test fixtures use `parseUUID(s)`, which panics on invalid input.
-- Outside handlers, `util.ParseUUID(s) (pgtype.UUID, error)` is the safe variant; always check the error.
+### Backend Handler UUID Parsing Convention
 
-## Web/Desktop Features
+Every Go handler in `server/internal/handler/` follows these rules. The convention exists because `util.ParseUUID` used to silently return a zero UUID on invalid input, which caused #1661 — a `DELETE` returning 204 success while the SQL `DELETE` matched zero rows.
 
-When adding a shared page or feature for web and desktop:
+- **Resource path params that accept either a UUID or a human-readable identifier** (e.g. `chi.URLParam(r, "id")` for an issue, which accepts both `MUL-123` and a UUID) MUST be resolved through the dedicated loader (`loadIssueForUser` / `loadSkillForUser` / `loadAgentForUser` / `requireDaemonRuntimeAccess`). After resolution, all subsequent DB calls — especially `Queries.Delete*` / `Queries.Update*` — MUST use `entity.ID` from the resolved object. Never round-trip the raw URL string through `parseUUID` for a write query.
+- **Pure-UUID inputs from request boundaries** (URL params that are always UUIDs, request body fields, query params, headers) MUST be validated with `parseUUIDOrBadRequest(w, s, fieldName)`. On invalid input it writes a 400 and returns `ok=false` — return immediately.
+- **Trusted UUID round-trips** (sqlc-returned UUIDs being passed back into queries, test fixtures) use `parseUUID(s)` which calls `util.MustParseUUID` and panics on invalid input. A panic here means an unguarded user-input string slipped in — that is a real bug. `chi`'s `middleware.Recoverer` translates the panic into a 500 so the process keeps running.
+- **`util.ParseUUID(s) (pgtype.UUID, error)`** is the only safe variant outside the handler package. Always check the error.
 
-1. Put the page/component in `packages/views/<domain>/`.
-2. Add platform wiring in both `apps/web/app/` and the desktop router, unless the desktop flow is a transition overlay.
-3. Use `useNavigation().push()` or `<AppLink>` in shared code.
-4. Use shared guards/providers such as `DashboardGuard` from `packages/views/layout/`.
-5. Keep platform-only UI in the app or inject it through props/slots.
-6. Hooks that need workspace context should accept `wsId`.
+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.
 
-CSS for web/desktop is shared from `packages/ui/styles/`. Use semantic tokens such as `bg-background` and `text-muted-foreground`; avoid hardcoded Tailwind colors and duplicated base styles.
+### Dependency Declaration Rule
 
-## Desktop Rules
+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.
 
-Desktop routing has three categories:
+- 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.
 
-- Session routes: workspace-scoped tab destinations such as `/:slug/issues`.
-- Transition flows: pre-workspace one-shot actions such as create workspace or accept invite. These are `WindowOverlay` state, not routes.
-- Error/stale states: stale workspace tabs should auto-heal by dropping stale tab groups, not render desktop error pages.
+### Package Boundary Rules
 
-More desktop constraints:
+These are hard constraints. Violating them breaks the cross-platform architecture:
 
-- New pre-workspace desktop flows register a `WindowOverlay` type in `stores/window-overlay-store.ts`; do not add them to `routes.tsx`.
-- `setCurrentWorkspace(slug, uuid)` from `@multica/core/platform` is the active workspace source of truth.
-- Code that leaves workspace context must call `setCurrentWorkspace(null, null)` explicitly.
-- Leave/delete workspace flow order: read cached destination, clear current workspace, navigate, then run the mutation.
-- Cross-workspace navigation must go through the navigation adapter so it can call `switchWorkspace(slug, targetPath)`.
-- Full-window desktop views outside the dashboard shell must mount `<DragStrip />` from `@multica/views/platform` as the first flex child. Interactive controls in the top 48px need `WebkitAppRegion: "no-drag"`.
+- `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.
 
-## Mobile Rules
+### The No-Duplication Rule (web + desktop)
 
-Read `apps/mobile/CLAUDE.md` before touching `apps/mobile/`. It contains the mandatory pre-flight process, import limits, parity rules, tech stack, UI rules, data helpers, realtime strategy, and mobile release flow.
+**If the same logic exists in both web and desktop, it must be extracted to a shared package.**
 
-Root-level reminders:
+This applies to everything between web and desktop: components, hooks, guards, providers, utility functions. The decision process:
 
-- Mobile shares only `@multica/core` types and pure functions.
-- Mobile must match web/desktop product semantics: counts, permissions, enums/transitions, and data identity.
-- Mobile may differ in UI/interaction when the phone context requires it.
+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.
+3. Everything else → belongs in `packages/core/` (headless logic) or `packages/views/` (UI components).
 
-## UI Rules
+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.
 
-- Prefer shadcn/Base UI components over custom implementations. Add them with `pnpm ui:add <component>` from the repo root.
-- Use design tokens and semantic classes; avoid hardcoded colors.
-- Do not introduce extra local state unless the design requires it.
-- Handle overflow, long text, scrolling, alignment, and spacing deliberately.
-- If a component is identical between web and desktop, it belongs in a shared package.
+### Cross-Platform Development Rules (web + desktop)
 
-## Testing
+When adding a new page or feature for web/desktop:
 
-Tests follow the code:
+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*.
+3. **Navigation** → use `useNavigation().push()` or `<AppLink>`. Never use framework-specific link/router APIs in shared code.
+4. **Shared guards/providers** → use `DashboardGuard` from `packages/views/layout/`. Don't create separate guard logic per app.
+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`.
 
-| What is tested | Location |
-| --- | --- |
-| Shared business logic, stores, queries, hooks | `packages/core/*.test.ts` |
-| Shared UI components, pages, forms, modals | `packages/views/*.test.tsx` |
-| Platform wiring such as cookies, redirects, search params | `apps/web/*.test.tsx` or `apps/desktop/` |
-| End-to-end flows | `e2e/*.spec.ts` |
-| Backend | `server/` Go tests |
+### CSS Architecture (web + desktop)
 
-Rules:
+Web and desktop share the same CSS foundation from `packages/ui/styles/`.
 
-- Never test shared component behavior in an app test file.
-- `packages/views/` tests must not mock `next/*` or `react-router-dom`.
-- Mock `@multica/core` stores with the Zustand callable-store shape (`selectorFn` plus `getState`).
+- **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.
+
+### Route categories
+
+Every path in the desktop app falls into exactly one category. Choosing the wrong one reproduces bugs we've already fixed.
+
+- **Session routes** — workspace-scoped pages (`/:slug/issues`, `/:slug/settings`). Rendered by the per-tab memory router under `WorkspaceRouteLayout`. These are legitimate tab destinations.
+- **Transition flows** — pre-workspace / one-shot actions (create workspace, accept invite). **NOT routes.** They live as `WindowOverlay` state, dispatched when the navigation adapter sees `push('/workspaces/new')` or `push('/invite/<id>')`. The shared view (`NewWorkspacePage`, `InvitePage`) is the content; the overlay wrapper supplies platform chrome.
+- **Error / stale states** — "workspace not available", tabs pointing at a revoked workspace. **NOT pages.** `WorkspaceRouteLayout` auto-heals by dropping the stale tab group from the store; the user never lands on an explicit error screen. Web keeps `NoAccessPage` (shareable URL makes the error state meaningful); desktop has no URL bar so stale = heal silently.
+
+**Adding a new pre-workspace flow on desktop**: register a new `WindowOverlay` type in `stores/window-overlay-store.ts`. Do NOT add it to `routes.tsx`. If a shared view needs the flow on both platforms, add the route on web (`apps/web/app/(auth)/...`) AND the overlay type on desktop — the shared view component is identical.
+
+### Workspace context
+
+`setCurrentWorkspace(slug, uuid)` from `@multica/core/platform` is the single source of truth for the active workspace. `WorkspaceRouteLayout` sets it on mount; unmount does NOT clear it. Code that leaves workspace context (leave/delete workspace, force-navigate to overlay) must call `setCurrentWorkspace(null, null)` explicitly.
+
+### Workspace destructive operations
+
+Leave / Delete workspace flows must follow this order, otherwise concurrent refetches race and the renderer hard-reloads:
+
+1. Read destination from cached workspace list.
+2. `setCurrentWorkspace(null, null)`.
+3. `navigation.push(destination)`.
+4. THEN `await mutation.mutateAsync(workspaceId)`.
+
+### Tab isolation
+
+Tabs are grouped per workspace in `stores/tab-store.ts`. The TabBar shows only the active workspace's tabs; cross-workspace tab leakage is impossible by construction (no flat global tabs array).
+
+Cross-workspace `push(path)` is detected by the navigation adapter (`platform/navigation.tsx`) and translated into `switchWorkspace(slug, targetPath)` — NOT a navigation within the current tab's router. Don't bypass the adapter; always go through `useNavigation()` from shared code.
+
+### Drag region (macOS)
+
+Every full-window desktop view (anything outside the dashboard shell) must mount `<DragStrip />` from `@multica/views/platform` as the first flex child of the page root, otherwise users can't drag the window. Interactive UI inside the top 48px needs `WebkitAppRegion: "no-drag"` to stay clickable.
+
+## UI/UX Rules
+
+- Prefer shadcn components over custom implementations. Install via `pnpm ui:add <component>` from project root — adds to `packages/ui/components/ui/`. All components use Base UI primitives (`@base-ui/react`), not Radix.
+- Use shadcn design tokens for styling. Avoid hardcoded color values.
+- Do not introduce extra state (useState, context, reducers) unless explicitly required by the design.
+- Pay close attention to **overflow** (truncate long text, scrollable containers), **alignment**, and **spacing** consistency.
+- **If a component is identical between web and desktop, it belongs in a shared package.** Do not copy-paste between apps.
+
+## Testing Rules
+
+### Where to write tests
+
+Tests follow the code, not the app. This is the most important testing principle in this monorepo:
+
+| What you're testing | Where the test lives | Why |
+|---|---|---|
+| Shared business logic (stores, queries, hooks) | `packages/core/*.test.ts` | No DOM needed, pure logic |
+| Shared UI components (pages, forms, modals) | `packages/views/*.test.tsx` | jsdom, no framework mocks |
+| Platform-specific wiring (cookies, redirects, searchParams) | `apps/web/*.test.tsx` or `apps/desktop/` | Needs framework-specific mocks |
+| End-to-end user flows | `e2e/*.spec.ts` | Real browser, real backend |
+
+**Never test shared component behavior in an app's test file.** If a test requires mocking `next/navigation` or `react-router-dom` to test a component from `@multica/views`, the test is in the wrong place — move it to `packages/views/` and mock `@multica/core` instead.
+
+### Test infrastructure
+
+- `packages/core/` — Vitest, Node environment (no DOM)
+- `packages/views/` — Vitest, jsdom environment, `@testing-library/react`
+- `apps/web/` — Vitest, jsdom environment, framework-specific mocks
+- `e2e/` — Playwright
+- `server/` — Go standard `go test`
+
+All test deps are in the pnpm catalog for unified versioning.
+
+### Mocking conventions
+
+- Mock `@multica/core` stores with `vi.hoisted()` + `Object.assign(selectorFn, { getState })` pattern (Zustand stores are both callable and have `.getState()`).
 - Mock `@multica/core/api` for API calls.
-- E2E tests should use `TestApiClient` for setup/teardown.
-- Prefer writing the failing test in the correct package before implementation when the change is behavioral.
+- In `packages/views/` tests: never mock `next/*` or `react-router-dom` — those don't exist here.
+- In `apps/web/` tests: mock framework-specific APIs only for platform-specific behavior.
 
-## Verification
+### TDD workflow
 
-For code changes, run the narrowest useful checks while iterating, then run broader verification when risk justifies it or when asked.
+1. Write failing test in the **correct package** first.
+2. Write implementation.
+3. Run `pnpm test` (Turborepo discovers all packages).
+4. Green → done.
 
-Useful checks:
+### Go tests
+
+Standard `go test`. Tests should create their own fixture data in a test database.
+
+### E2E tests
+
+E2E tests should be self-contained. Use the `TestApiClient` fixture for data setup/teardown:
+
+```typescript
+import { loginAsDefault, createTestApi } from "./helpers";
+import type { TestApiClient } from "./fixtures";
+
+let api: TestApiClient;
+
+test.beforeEach(async ({ page }) => {
+  api = await createTestApi();
+  await loginAsDefault(page);
+});
+
+test.afterEach(async () => {
+  await api.cleanup();
+});
+
+test("example", async ({ page }) => {
+  const issue = await api.createIssue("Test Issue");
+  await page.goto(`/issues/${issue.id}`);
+});
+```
+
+## Commit Rules
+
+- Use atomic commits grouped by logical intent.
+- Conventional format: `feat(scope)`, `fix(scope)`, `refactor(scope)`, `docs`, `test(scope)`, `chore(scope)`.
+
+## Minimum Pre-Push Checks
+
+```bash
+make check    # Runs all checks: typecheck, unit tests, Go tests, E2E
+```
+
+Run verification only when the user explicitly asks for it.
+
+For targeted checks when requested:
+```bash
+pnpm typecheck        # TypeScript type errors only
+pnpm test             # TS unit tests only (Vitest, all packages)
+make test             # Go tests only
+pnpm exec playwright test   # E2E only (requires backend + frontend running)
+```
+
+## AI Agent Verification Loop
+
+After writing or modifying code, always run the full verification pipeline:
 
 ```bash
-pnpm typecheck
-pnpm test
-make test
-pnpm exec playwright test
 make check
 ```
 
-Do not claim verification passed unless you ran it. If you skip checks because the change is docs-only or the user asked not to run them, say so.
+**Workflow:**
+- Write code to satisfy the requirement
+- Run `make check`
+- If any step fails, read the error output, fix the code, and re-run
+- Repeat until all checks pass
+- Only then consider the task complete
 
-## Commits and Releases
+**Quick iteration:** If you know only TypeScript or Go is affected, run individual checks first for faster feedback, then finish with a full `make check` before marking work complete.
 
-- Commits should be atomic and use conventional prefixes: `feat(scope)`, `fix(scope)`, `refactor(scope)`, `docs`, `test(scope)`, `chore(scope)`.
-- A production deployment requires a CLI release tag on `main`: create `v0.x.x`, push it, and let `release.yml` publish binaries and the Homebrew tap.
-- Bump patch by default unless the user specifies a version.
+## CLI Release
 
-## Domain Reminders
+**Prerequisite:** A CLI release must accompany every Production deployment.
 
-- All queries filter by `workspace_id`; membership gates access; `X-Workspace-ID` selects the workspace.
-- Issue assignees are polymorphic: `assignee_type` plus `assignee_id` can reference a member or an agent.
+1. Create a tag on the `main` branch: `git tag v0.x.x`
+2. Push the tag: `git push origin v0.x.x`
+3. GitHub Actions automatically triggers `release.yml`: runs Go tests → GoReleaser builds multi-platform binaries → publishes to GitHub Releases + Homebrew tap
+
+By default, bump the patch version each release (e.g. `v0.1.12` → `v0.1.13`), unless the user specifies a specific version.
+
+## Multi-tenancy
+
+All queries filter by `workspace_id`. Membership checks gate access. `X-Workspace-ID` header routes requests to the correct workspace.
+
+## Agent Assignees
+
+Assignees are polymorphic — can be a member or an agent. `assignee_type` + `assignee_id` on issues. Agents render with distinct styling (purple background, robot icon).

CLI_AND_DAEMON.md

@@ -149,7 +149,6 @@ The daemon auto-detects these AI CLIs on your PATH:
 | [Cursor Agent](https://cursor.com/) | `cursor-agent` | Cursor's headless coding agent |
 | Kimi | `kimi` | Moonshot coding agent |
 | Kiro CLI | `kiro-cli` | Kiro ACP coding agent |
-| [Qoder CLI](https://docs.qoder.com/) | `qodercli` | Qoder ACP coding agent |
 
 You need at least one installed. The daemon registers each detected CLI as an available runtime.
 
@@ -169,7 +168,7 @@ Daemon behavior is configured via flags or environment variables:
 |---------|------|--------------|---------|
 | Poll interval | `--poll-interval` | `MULTICA_DAEMON_POLL_INTERVAL` | `3s` |
 | Heartbeat interval | `--heartbeat-interval` | `MULTICA_DAEMON_HEARTBEAT_INTERVAL` | `15s` |
-| Agent timeout | `--agent-timeout` | `MULTICA_AGENT_TIMEOUT` | `0` (no cap; bounded by the watchdogs) |
+| Agent timeout | `--agent-timeout` | `MULTICA_AGENT_TIMEOUT` | `2h` |
 | Codex semantic inactivity timeout | `--codex-semantic-inactivity-timeout` | `MULTICA_CODEX_SEMANTIC_INACTIVITY_TIMEOUT` | `10m` |
 | Max concurrent tasks | `--max-concurrent-tasks` | `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` | `20` |
 | Daemon ID | `--daemon-id` | `MULTICA_DAEMON_ID` | hostname |
@@ -221,10 +220,6 @@ Agent-specific overrides:
 | `MULTICA_KIMI_MODEL` | Override the Kimi model used |
 | `MULTICA_KIRO_PATH` | Custom path to the `kiro-cli` binary |
 | `MULTICA_KIRO_MODEL` | Override the Kiro model used |
-| `MULTICA_QODER_PATH` | Custom path to the `qodercli` binary |
-| `MULTICA_QODER_MODEL` | Override the Qoder model used |
-
-The daemon launches Qoder as `qodercli --yolo --acp`, matching Qoder’s ACP “bypass permissions” mode so tool runs do not block on interactive approval in headless runs.
 
 `MULTICA_CLAUDE_ARGS` and `MULTICA_CODEX_ARGS` are parsed with POSIX shellword quoting, so values such as `--model "gpt-5.1 codex" --sandbox read-only` are split like a shell command line. Agent arguments are applied in this order: hardcoded Multica defaults, daemon-wide env defaults, then per-agent `custom_args` from the task.
 
@@ -409,12 +404,12 @@ multica issue comment list <issue-id> --thread <comment-id> --tail 30 \
 # 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 10
+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 10 \
+multica issue comment list <issue-id> --recent 20 \
     --before <ts> --before-id <root-id>
 
 # Incremental polling. Combines with --thread or --recent; filters out
@@ -519,14 +514,8 @@ multica issue run-messages <task-id> --output json
 
 # Incremental fetch (only messages after a given sequence number)
 multica issue run-messages <task-id> --since 42 --output json
-
-# Aggregated token usage for an issue (sum across all its task runs)
-multica issue usage <issue-id>
-multica issue usage <issue-id> --output json
 ```
 
-The `usage` command returns the aggregated token usage for an issue, summed across all of its task runs: input tokens, output tokens, cache read/write tokens, and the run count (`task_count`). It wraps `GET /api/issues/<id>/usage` — the same figures the issue detail view shows. Use `--output json` to feed billing/cost tooling.
-
 The `runs` command shows all past and current executions for an issue, including running tasks. Table output uses short task UUID prefixes by default; pass `--full-id` to print canonical task UUIDs. The `run-messages` command accepts full task UUIDs directly; copied short task prefixes must be scoped with `--issue <issue-id>` so the CLI only checks that issue's runs. It shows the detailed message log (tool calls, thinking, text, errors) for a single run. Use `--since` for efficient polling of in-progress runs.
 
 ## Projects
@@ -659,18 +648,14 @@ multica autopilot create \
   --title "Nightly bug triage" \
   --description "Scan todo issues and prioritize." \
   --agent "Lambda" \
-  --mode create_issue \
-  --subscriber "Alice"
+  --mode create_issue
 
 multica autopilot update <id> --status paused
 multica autopilot update <id> --description "New prompt"
-multica autopilot update <id> --subscriber "Alice" --subscriber "Bob"
-multica autopilot update <id> --clear-subscribers
 multica autopilot delete <id>
 ```
 
 `--mode` accepts `create_issue` (creates a new issue on each run and assigns it to the agent) or `run_only` (enqueues a direct agent task without creating an issue). `--agent` accepts either a name or UUID.
-`--subscriber` accepts a workspace member name or user ID and may be repeated; on update it replaces the autopilot's subscriber template. Subscribers receive inbox notifications for issues created by a `create_issue` autopilot. Use `--clear-subscribers` to remove all autopilot subscribers.
 
 ### Manual Trigger
 
@@ -714,79 +699,3 @@ Most commands support `--output` with two formats:
 multica issue list --output json
 multica daemon status --output json
 ```
-
-## Error Messages
-
-The CLI funnels command errors returned to the top-level handler through a
-single user-facing translation layer (`server/internal/cli/errors.go`) so that
-what you see on the terminal is a short, actionable sentence rather than a raw
-Go error, an HTTP status line, or an internal `resolve issue: ...` chain. (A
-few commands print their own output or run deliberate fast probes — for example
-`setup`'s short `/health` reachability check — and don't go through this
-layer.) The underlying detail is still available on demand (see `--debug`).
-
-### What you see
-
-- **Friendly, single-line message.** Transport failures (timeout, DNS,
-  connection refused, TLS) and HTTP status failures (401/403/404/409/400·422/
-  429/5xx) are each rendered as one clear sentence with a next step — for
-  example a timeout suggests checking the network or raising
-  `MULTICA_HTTP_TIMEOUT`, and a 401 tells you to run `multica login`.
-- **Server-provided validation messages are preserved.** For a 400/422 that
-  carries a message from the server, that message is shown verbatim
-  (`Invalid request: <server message>`); only when there is none do you get the
-  generic "check your values / run with --help" hint.
-- **No leaked internals by default.** Raw URLs, status lines, JSON bodies, and
-  the internal verb chain are hidden unless you ask for them.
-
-### Language
-
-Messages default to **English**, matching the rest of the CLI's help output.
-If a Chinese locale is detected in `LC_ALL`, `LC_MESSAGES`, or `LANG` (in that
-precedence order), messages switch to **Chinese**. No flag is needed; set the
-locale as usual:
-
-```bash
-LANG=zh_CN.UTF-8 multica issue get MUL-9999   # 错误信息显示为中文
-```
-
-### Exit codes
-
-The process exit code is tiered so scripts can branch on the failure class:
-
-| Exit code | Meaning |
-| --- | --- |
-| `0` | success |
-| `1` | generic / unclassified error |
-| `2` | network error (timeout, DNS, connection refused, TLS, offline) |
-| `3` | authentication / authorization (HTTP 401, 403) |
-| `4` | not found (HTTP 404) |
-| `5` | validation (HTTP 400, 422) |
-
-```bash
-multica issue get MUL-9999
-if [ $? -eq 4 ]; then echo "no such issue"; fi
-```
-
-### Seeing the full detail (`--debug`)
-
-Pass the global `--debug` flag (or set `MULTICA_DEBUG=1`) to print the complete
-original error chain — the internal verb chain, the request method/path/status,
-and the raw server body — underneath the friendly message. Use it when you need
-to file a bug or understand exactly what the server returned:
-
-```bash
-multica issue list --debug
-MULTICA_DEBUG=1 multica issue update MUL-1234 --title "x"
-```
-
-### Request timeout
-
-API requests use a default timeout of 30 seconds. Override it with
-`MULTICA_HTTP_TIMEOUT` when you are on a slow network; it accepts a Go duration
-(`45s`, `2m`) or a plain number of seconds (`45`). Command-level deadlines are
-always at least this value, so raising it takes effect across all commands.
-
-```bash
-MULTICA_HTTP_TIMEOUT=60s multica issue list
-```

Dockerfile

@@ -15,12 +15,10 @@ COPY server/ ./server/
 # Build binaries
 ARG VERSION=dev
 ARG COMMIT=unknown
-ARG DATE=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} -X main.date=${DATE}" -o bin/multica ./cmd/multica
+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
-RUN cd server && CGO_ENABLED=0 go build -ldflags "-s -w" -o bin/backfill_codex_usage_cache ./cmd/backfill_codex_usage_cache
 
 # --- Runtime stage ---
 FROM alpine:3.21
@@ -33,7 +31,6 @@ 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 --from=builder /src/server/bin/backfill_codex_usage_cache .
 COPY server/migrations/ ./migrations/
 COPY docker/entrypoint.sh .
 RUN sed -i 's/\r$//' entrypoint.sh && chmod +x entrypoint.sh

Makefile

@@ -58,17 +58,12 @@ selfhost: ## Create .env if needed, then pull and start the official self-hosted
 		echo "==> Creating .env from .env.example..."; \
 		cp .env.example .env; \
 		JWT=$$(openssl rand -hex 32); \
-		PGPASS=$$(openssl rand -hex 24); \
 		if [ "$$(uname)" = "Darwin" ]; then \
 			sed -i '' "s/^JWT_SECRET=.*/JWT_SECRET=$$JWT/" .env; \
-			sed -i '' "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$$PGPASS/" .env; \
-			sed -i '' -E "s#^(DATABASE_URL=postgres://[^:]+:)[^@]*(@.*)#\1$$PGPASS\2#" .env; \
 		else \
 			sed -i "s/^JWT_SECRET=.*/JWT_SECRET=$$JWT/" .env; \
-			sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$$PGPASS/" .env; \
-			sed -i -E "s#^(DATABASE_URL=postgres://[^:]+:)[^@]*(@.*)#\1$$PGPASS\2#" .env; \
 		fi; \
-		echo "==> Generated random JWT_SECRET and POSTGRES_PASSWORD"; \
+		echo "==> Generated random JWT_SECRET"; \
 	fi
 	@echo "==> Pulling official Multica images..."
 	@if ! docker compose -f docker-compose.selfhost.yml pull; then \
@@ -113,17 +108,12 @@ selfhost-build: ## Build backend/web from the current checkout and start the sel
 		echo "==> Creating .env from .env.example..."; \
 		cp .env.example .env; \
 		JWT=$$(openssl rand -hex 32); \
-		PGPASS=$$(openssl rand -hex 24); \
 		if [ "$$(uname)" = "Darwin" ]; then \
 			sed -i '' "s/^JWT_SECRET=.*/JWT_SECRET=$$JWT/" .env; \
-			sed -i '' "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$$PGPASS/" .env; \
-			sed -i '' -E "s#^(DATABASE_URL=postgres://[^:]+:)[^@]*(@.*)#\1$$PGPASS\2#" .env; \
 		else \
 			sed -i "s/^JWT_SECRET=.*/JWT_SECRET=$$JWT/" .env; \
-			sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$$PGPASS/" .env; \
-			sed -i -E "s#^(DATABASE_URL=postgres://[^:]+:)[^@]*(@.*)#\1$$PGPASS\2#" .env; \
 		fi; \
-		echo "==> Generated random JWT_SECRET and POSTGRES_PASSWORD"; \
+		echo "==> Generated random JWT_SECRET"; \
 	fi
 	@echo "==> Building Multica from the current checkout..."
 	docker compose -f docker-compose.selfhost.yml -f docker-compose.selfhost.build.yml up -d --build
@@ -296,7 +286,7 @@ test: ## Run Go tests after ensuring the target DB exists and migrations are app
 	$(REQUIRE_ENV)
 	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
 	cd server && go run ./cmd/migrate up
-	cd server && go test -race ./...
+	cd server && go test ./...
 
 # Database
 ##@ Database
@@ -317,10 +307,5 @@ sqlc: ## Regenerate sqlc code
 # Cleanup
 ##@ Cleanup
 
-clean: ## Remove build caches, generated binaries, and temp files
+clean: ## Remove generated server binaries and temp files
 	rm -rf server/bin server/tmp
-	rm -rf apps/*/.next apps/*/.source apps/*/.expo
-	rm -rf apps/*/out apps/*/dist apps/*/dist-electron packages/*/dist
-	rm -rf .turbo apps/*/.turbo packages/*/.turbo
-	rm -rf apps/*/*.tsbuildinfo packages/*/*.tsbuildinfo
-	@echo "✓ Clean complete."

README.md

@@ -19,9 +19,8 @@ Turn coding agents into real teammates — assign tasks, track progress, compoun
 
 [![CI](https://github.com/multica-ai/multica/actions/workflows/ci.yml/badge.svg)](https://github.com/multica-ai/multica/actions/workflows/ci.yml)
 [![GitHub stars](https://img.shields.io/github/stars/multica-ai/multica?style=flat)](https://github.com/multica-ai/multica/stargazers)
-[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/W8gYBn226t)
 
-[Website](https://multica.ai) · [Cloud](https://multica.ai) · [Discord](https://discord.gg/W8gYBn226t) · [X](https://x.com/MulticaAI) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
+[Website](https://multica.ai) · [Cloud](https://multica.ai) · [X](https://x.com/MulticaAI) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
 
 **English | [简体中文](README.zh-CN.md)**
 
@@ -31,7 +30,7 @@ Turn coding agents into real teammates — assign tasks, track progress, compoun
 
 Multica turns coding agents into real teammates. Assign issues to an agent like you'd assign to a colleague — they'll pick up the work, write code, report blockers, and update statuses autonomously.
 
-No more copy-pasting prompts. No more babysitting runs. Your agents show up on the board, participate in conversations, and compound reusable skills over time. Think of it as open-source infrastructure for managed agents — vendor-neutral, self-hosted, and designed for human + AI teams. Works with **Claude Code**, **Codex**, **GitHub Copilot CLI**, **OpenClaw**, **OpenCode**, **Hermes**, **Gemini**, **Pi**, **Cursor Agent**, **Kimi**, **Kiro CLI**, and **Qoder CLI**.
+No more copy-pasting prompts. No more babysitting runs. Your agents show up on the board, participate in conversations, and compound reusable skills over time. Think of it as open-source infrastructure for managed agents — vendor-neutral, self-hosted, and designed for human + AI teams. Works with **Claude Code**, **Codex**, **GitHub Copilot CLI**, **OpenClaw**, **OpenCode**, **Hermes**, **Gemini**, **Pi**, **Cursor Agent**, **Kimi**, and **Kiro CLI**.
 
 For larger teams, Squads add a stable routing layer: assign work to a group led by an agent, and the leader delegates to the right member.
 
@@ -115,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`, `agy`, `qodercli`) 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
 
@@ -125,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, Kiro CLI, Antigravity, or Qoder 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
 
@@ -166,7 +165,7 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
                      │ Agent Daemon │  runs on your machine
                      └──────────────┘  (Claude Code, Codex, GitHub Copilot CLI,
                                         OpenCode, OpenClaw, Hermes, Gemini,
-                                        Pi, Cursor Agent, Kimi, Kiro CLI, Qoder CLI)
+                                        Pi, Cursor Agent, Kimi, Kiro CLI)
 ```
 
 | Layer | Stack |
@@ -174,7 +173,7 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
 | Frontend | Next.js 16 (App Router) |
 | Backend | Go (Chi router, sqlc, gorilla/websocket) |
 | Database | PostgreSQL 17 with pgvector |
-| Agent Runtime | Local daemon executing Claude Code, Codex, GitHub Copilot CLI, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, Kiro CLI, or Qoder CLI |
+| Agent Runtime | Local daemon executing Claude Code, Codex, GitHub Copilot CLI, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent, Kimi, or Kiro CLI |
 
 ## Development
 

README.zh-CN.md

@@ -19,9 +19,8 @@
 
 [![CI](https://github.com/multica-ai/multica/actions/workflows/ci.yml/badge.svg)](https://github.com/multica-ai/multica/actions/workflows/ci.yml)
 [![GitHub stars](https://img.shields.io/github/stars/multica-ai/multica?style=flat)](https://github.com/multica-ai/multica/stargazers)
-[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/W8gYBn226t)
 
-[官网](https://multica.ai) · [云服务](https://multica.ai) · [Discord](https://discord.gg/W8gYBn226t) · [X](https://x.com/MulticaAI) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
+[官网](https://multica.ai) · [云服务](https://multica.ai) · [X](https://x.com/MulticaAI) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
 
 **[English](README.md) | 简体中文**
 
@@ -31,7 +30,7 @@
 
 Multica 将编码 Agent 变成真正的队友。像分配给同事一样分配给 Agent——它们会自主接手工作、编写代码、报告阻塞问题、更新状态。
 
-不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**GitHub Copilot CLI**、**OpenClaw**、**OpenCode**、**Hermes**、**Gemini**、**Pi**、**Cursor Agent**、**Kimi**、**Kiro CLI** 与 **Qoder CLI**。
+不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**GitHub Copilot CLI**、**OpenClaw**、**OpenCode**、**Hermes**、**Gemini**、**Pi**、**Cursor Agent**、**Kimi** 和 **Kiro CLI**。
 
 面向更大的团队，Squads（小队）提供稳定的路由层：把任务分给由 Agent 带队的小队，由队长判断谁最适合接手。
 
@@ -116,7 +115,7 @@ multica setup          # 连接 Multica Cloud，登录，启动 daemon
 multica setup           # 配置、认证、启动 daemon（一条命令搞定）
 ```
 
-daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`copilot`、`openclaw`、`opencode`、`hermes`、`gemini`、`pi`、`cursor-agent`、`kimi`、`kiro-cli`、`qodercli`）。
+daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`copilot`、`openclaw`、`opencode`、`hermes`、`gemini`、`pi`、`cursor-agent`、`kimi`、`kiro-cli`）。
 
 ### 2. 确认运行时已连接
 
@@ -126,7 +125,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 
 ### 3. 创建 Agent
 
-进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、GitHub Copilot CLI、OpenClaw、OpenCode、Hermes、Gemini、Pi、Cursor Agent、Kimi、Kiro CLI 或 Qoder CLI），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
+进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、GitHub Copilot CLI、OpenClaw、OpenCode、Hermes、Gemini、Pi、Cursor Agent、Kimi 或 Kiro CLI），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
 
 ### 4. 分配你的第一个任务
 
@@ -148,7 +147,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
                      │ Agent Daemon │  运行在你的机器上
                      └──────────────┘  （Claude Code、Codex、GitHub Copilot CLI、
                                         OpenCode、OpenClaw、Hermes、Gemini、
-                                        Pi、Cursor Agent、Kimi、Kiro CLI、Qoder CLI）
+                                        Pi、Cursor Agent、Kimi、Kiro CLI）
 ```
 
 | 层级 | 技术栈 |
@@ -156,7 +155,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 | 前端 | Next.js 16 (App Router) |
 | 后端 | Go (Chi router, sqlc, gorilla/websocket) |
 | 数据库 | PostgreSQL 17 with pgvector |
-| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、GitHub Copilot CLI、OpenClaw、OpenCode、Hermes、Gemini、Pi、Cursor Agent、Kimi、Kiro CLI 或 Qoder CLI |
+| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、GitHub Copilot CLI、OpenClaw、OpenCode、Hermes、Gemini、Pi、Cursor Agent、Kimi 或 Kiro CLI |
 
 ## 开发
 

SELF_HOSTING.md

@@ -101,7 +101,6 @@ You also need at least one AI agent CLI installed:
 - [Cursor Agent](https://cursor.com/) (`cursor-agent` on PATH)
 - Kimi (`kimi` on PATH)
 - Kiro CLI (`kiro-cli` on PATH)
-- Qoder CLI (`qodercli` on PATH)
 
 ### b) One-command setup
 
@@ -327,7 +326,7 @@ To roll back if an upgrade goes sideways:
 helm -n multica rollback multica
 ```
 
-> **Upgrading from `v0.3.4` to `v0.3.5+` fails with `refusing to drop legacy daily rollups: ...`?** As of MUL-2957 the `migrate up` command runs an idempotent monthly-slice backfill automatically before applying migration `103`, so a clean upgrade is a single `helm upgrade` + backend rollout. If you are still on a pre-MUL-2957 binary or the auto-hook fails, run the standalone 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. See [Advanced Configuration → Usage Dashboard Rollup](SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup) for the full recovery flow.
+> **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
 
@@ -341,52 +340,56 @@ kubectl delete namespace multica
 
 ---
 
-## Usage Dashboard Rollup
+## Usage Dashboard Rollup (Required)
 
-The Usage / Runtime dashboards read from a derived `task_usage_hourly` table populated by `rollup_task_usage_hourly()`. As of MUL-2957 the backend runs this rollup **in-process** on every replica via a DB-backed scheduler (`sys_cron_executions`); a fresh self-host install needs no operator action and the bundled `pgvector/pgvector:pg17` image works without changes — you do **not** need to swap it for an image that ships `pg_cron`, register an external cron job, set up a systemd timer, or run a Kubernetes `CronJob`.
+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`.
 
-Multiple backend replicas are safe: each replica ticks every 30 seconds and tries to claim the current 5-minute UTC plan, but the unique key `(job_name, scope_kind, scope_id, plan_time)` means only one wins each plan. Inspect steady-state operation:
+**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.
 
-```sql
-SELECT plan_time, status, attempt, runner_id,
-       error_code, error_msg, started_at, finished_at
-  FROM sys_cron_executions
- WHERE job_name = 'rollup_task_usage_hourly'
- ORDER BY plan_time DESC
- LIMIT 20;
+> **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
 ```
 
-Full reference (audit table semantics, advisory lock 4246, the standalone backfill command, flag descriptions, the `v0.3.4 → v0.3.5+` migration auto-hook) lives in [Advanced Configuration → Usage Dashboard Rollup](SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup).
+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`.
 
-> **Upgrading from `v0.3.4` to `v0.3.5+`?** As of MUL-2957 the `migrate up` command runs an idempotent monthly-slice backfill automatically right before applying migration `103`, so the upgrade completes in a single invocation — no operator step required. If you are still on a pre-MUL-2957 binary or the auto-hook fails for an environmental reason, run `backfill_task_usage_hourly` against the same database and re-run the upgrade. See [Advanced Configuration → Usage Dashboard Rollup](SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup) for the recovery flow.
+### Option B — Swap Postgres for an image that ships `pg_cron`
 
-### Compatibility paths (existing deployments only)
+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:
 
-External schedulers — **`pg_cron` registered on the database, an external cron job, a systemd timer, or a Kubernetes `CronJob`** — that call `SELECT rollup_task_usage_hourly()` directly were the only option before MUL-2957 and remain a supported compatibility path. They are no longer the recommended setup; new deployments should rely on the in-process scheduler instead. The SQL function holds advisory lock 4246 internally, so the in-process scheduler and any pre-existing external schedule can coexist without ever double-writing the rollup.
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+SELECT cron.schedule(
+  'rollup_task_usage_hourly',
+  '*/5 * * * *',
+  $$SELECT rollup_task_usage_hourly()$$
+);
+```
 
-If you already have a `pg_cron` job in production, the safe sequence to retire it is:
+`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.
 
-1. Confirm the in-process scheduler is healthy on at least one backend replica — recent SUCCESS rows should be landing in `sys_cron_executions` for `rollup_task_usage_hourly`:
+### Option C — Backfill history first, then schedule
 
-   ```sql
-   SELECT plan_time, status, runner_id, finished_at
-     FROM sys_cron_executions
-    WHERE job_name = 'rollup_task_usage_hourly'
-      AND status = 'SUCCESS'
-    ORDER BY plan_time DESC
-    LIMIT 5;
-   ```
+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:
 
-2. Once SUCCESS rows are arriving on schedule, unschedule the redundant `pg_cron` entry:
+```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
+```
 
-   ```sql
-   SELECT cron.unschedule('rollup_task_usage_hourly')
-     FROM cron.job WHERE jobname = 'rollup_task_usage_hourly';
-   ```
+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.
 
-3. Leave the `pg_cron` extension itself installed unless you are sure no other workload depends on it. The bundled `pgvector/pgvector:pg17` image does **not** ship `pg_cron`, so nothing in Multica's default install needs it; uninstalling `pg_cron` from a custom image that other workloads still use is a separate decision.
-
-External cron / systemd timer / Kubernetes `CronJob` setups that call `SELECT rollup_task_usage_hourly()` directly can be retired the same way — once `sys_cron_executions` shows steady SUCCESS rows from the in-process scheduler, the external job is redundant and can be removed.
+After upgrading, re-run `migrate up` (or restart the backend container — migrations run automatically on startup) to apply migration `103` cleanly.
 
 ## Stopping Services
 
@@ -428,7 +431,7 @@ 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. As of MUL-2957 `migrate up` runs that backfill automatically right before applying `103`, so the upgrade completes in a single invocation. If you are still on a pre-MUL-2957 binary or the auto-hook fails, run `backfill_task_usage_hourly` manually first, then re-run the upgrade. Full instructions in [Advanced Configuration → Usage Dashboard Rollup](SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup).
+> **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).
 
 ---
 

SELF_HOSTING_ADVANCED.md

@@ -46,7 +46,6 @@ Use this option when your deployment cannot reach the public internet or you alr
 | `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` |
-| `SMTP_EHLO_NAME` | EHLO/HELO name announced to the relay. Set a real FQDN when a strict relay (e.g. Google Workspace) rejects the default greeting from a public IP | machine hostname |
 
 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.
 
@@ -94,8 +93,6 @@ For file uploads and attachments, configure S3 and (optionally) CloudFront:
 | `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 to path-style URLs |
-| `ATTACHMENT_DOWNLOAD_MODE` | Attachment download behavior: `auto` (default), `cloudfront`, `presign`, or `proxy`. Use `proxy` for private buckets behind Docker/VPC-only endpoints such as `http://rustfs:9000` |
-| `ATTACHMENT_DOWNLOAD_URL_TTL` | TTL for CloudFront signed URLs and S3 presigned download URLs (default: `30m`) |
 | `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) |
@@ -184,35 +181,74 @@ 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()`. As of MUL-2957 the backend runs this rollup **in-process** on every replica via a DB-backed scheduler (`sys_cron_executions`); a fresh self-host install needs no operator action — the bundled `pgvector/pgvector:pg17` image works without changes.
+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.
 
-### How the in-process scheduler works
+Pick one of the supported paths:
 
-Every backend replica ticks every 30 seconds and tries to claim the current 5-minute UTC plan in `sys_cron_executions`. The unique key `(job_name, scope_kind, scope_id, plan_time)` makes the claim a single-winner contest across all replicas, so multi-instance deployments do not double-write. The handler then calls `SELECT rollup_task_usage_hourly()`; the SQL function holds advisory lock `4246` internally, so a stray `pg_cron` job or manual call can run alongside the scheduler without ever colliding on the rollup itself. Inspect the audit table for steady-state operation:
+### Option A — External cron / systemd-timer
 
-```sql
-SELECT plan_time, status, attempt, runner_id,
-       error_code, error_msg, started_at, finished_at
-  FROM sys_cron_executions
- WHERE job_name = 'rollup_task_usage_hourly'
- ORDER BY plan_time DESC
- LIMIT 20;
+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
 ```
 
-### Compatibility — existing `pg_cron` registrations
+Kubernetes (one-off `CronJob`):
 
-If you previously registered the rollup as a `pg_cron` job (`SELECT cron.schedule('rollup_task_usage_hourly', '*/5 * * * *', …)`), it is safe to leave it in place: advisory lock 4246 prevents double-writes, and the loser path no-ops cleanly. To drop the redundant entry once the in-process scheduler is up:
-
-```sql
-SELECT cron.unschedule('rollup_task_usage_hourly')
-  FROM cron.job WHERE jobname = 'rollup_task_usage_hourly';
+```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
 ```
 
-External cron / systemd / Kubernetes `CronJob` setups that call `SELECT rollup_task_usage_hourly()` directly are also still valid — they were the only option before MUL-2957 and remain a supported compatibility path. They are no longer the recommended setup; new deployments should rely on the in-process scheduler.
+### Option B — Postgres with `pg_cron`
 
-### Standalone backfill command
+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.
 
-`rollup_task_usage_hourly()` only processes new buckets after it starts running. If you already have `task_usage` rows from before the rollup was claimed for the first time — most commonly when upgrading from `v0.3.4` to `v0.3.5+` on a database that already has months of usage — you can run `backfill_task_usage_hourly` to seed historical buckets:
+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
@@ -224,7 +260,7 @@ 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 in-process scheduler uses, so it's safe to re-run, to interrupt with Ctrl-C, and to run concurrently with the scheduler (advisory lock 4246 serialises them). Flags:
+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 |
 |---|---|
@@ -236,9 +272,17 @@ After backfill completes, the rollup-state watermark is stamped to `now() - 5 mi
 
 ### `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. As of MUL-2957 the migrate command runs an idempotent monthly-slice backfill (under advisory lock 4246) **automatically** immediately before applying migration `103`, so v0.3.4 → v0.3.5+ upgrades complete in a single `migrate up` invocation — no operator step is required.
+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:
 
-If you are upgrading from a binary that pre-dates MUL-2957 (or the auto-hook fails for an environmental reason), recovery is the manual path: run `backfill_task_usage_hourly` against the database, 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 the in-process scheduler picks up new buckets from the first tick.
+```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)
 

apps/desktop/package.json

@@ -49,7 +49,6 @@
     "electron-updater": "^6.8.3",
     "fix-path": "^5.0.0",
     "lucide-react": "catalog:",
-    "motion": "^12.38.0",
     "react": "catalog:",
     "react-dom": "catalog:",
     "react-router-dom": "^7.6.0",

apps/desktop/scripts/package.mjs

@@ -98,29 +98,16 @@ export function stripLeadingSeparator(argv) {
  *   - "v0.1.36"                → "0.1.36"
  *   - "v0.1.35-14-gf1415e96"   → "0.1.35-14-gf1415e96"  (semver prerelease)
  *   - "v0.1.35-…-dirty"        → same, dirty suffix preserved
- *   - "f1415e96" (no tag)      → "0.0.0-gf1415e96"       (fallback)
- *   - "2f24057b" (no tag, hash begins with a digit) → "0.0.0-g2f24057b"
- *   - "0123456"  (no tag, all-digit hash w/ leading zero) → "0.0.0-g0123456"
+ *   - "f1415e96" (no tag)      → "0.0.0-f1415e96"        (fallback)
  *
  * Leading `v` is stripped so the result is valid semver for package.json.
- * The fallback matters because a bare commit hash is never valid semver —
- * even one that happens to start with a digit (e.g. "2f24057b") — and
- * electron-updater throws on launch if package.json carries such a version.
- * The hash is prefixed with `g` so the pre-release identifier is always
- * alphanumeric; a bare all-digit hash with a leading zero (e.g. "0123456")
- * would otherwise form `0.0.0-0123456`, which is invalid semver.
  */
 export function normalizeGitVersion(raw) {
   if (!raw) return null;
   const stripped = raw.replace(/^v/, "");
-  // A real version begins with major.minor.patch. The bare commit hash
-  // that `git describe --always` falls back to (no reachable tag) does not,
-  // so coerce it to a 0.0.0 prerelease rather than passing it through.
-  // Prefix the hash with `g` (mirroring `git describe`'s own `g<hash>`
-  // shorthand) so a hash like "0123456" yields "0.0.0-g0123456" — a single
-  // alphanumeric identifier — instead of the invalid "0.0.0-0123456".
-  if (!/^\d+\.\d+\.\d+/.test(stripped)) {
-    return `0.0.0-g${stripped}`;
+  if (!/^\d/.test(stripped)) {
+    // No reachable tag — `git describe` fell back to just the commit hash.
+    return `0.0.0-${stripped}`;
   }
   return stripped;
 }

apps/desktop/scripts/package.test.mjs

@@ -38,27 +38,11 @@ describe("normalizeGitVersion", () => {
     expect(normalizeGitVersion("v1.0.0-rc.2")).toBe("1.0.0-rc.2");
   });
 
-  it("falls back to 0.0.0-g<hash> when no tags are reachable", () => {
+  it("falls back to 0.0.0-<hash> when no tags are reachable", () => {
     // `git describe --tags --always` returns just the short commit hash
-    // when there are no tags in the history at all. A hash that begins with
-    // a digit (e.g. "2f24057b") is still not valid semver and must fall
-    // through — otherwise electron-updater rejects it on launch. The `g`
-    // prefix mirrors git describe's own `g<hash>` shorthand and keeps the
-    // pre-release identifier a single alphanumeric token.
-    expect(normalizeGitVersion("f1415e96")).toBe("0.0.0-gf1415e96");
-    expect(normalizeGitVersion("abc1234")).toBe("0.0.0-gabc1234");
-    expect(normalizeGitVersion("2f24057b")).toBe("0.0.0-g2f24057b");
-  });
-
-  it("prefixes an all-digit hash so the pre-release is valid semver", () => {
-    // A short hash that is all decimal digits with a leading zero would
-    // produce `0.0.0-0123456` — a numeric pre-release identifier must not
-    // have a leading zero, so that value is invalid semver and
-    // electron-updater would throw on the no-tag builds this fallback
-    // exists to protect. The `g` prefix makes it a single alphanumeric
-    // identifier, which is always valid.
-    expect(normalizeGitVersion("0123456")).toBe("0.0.0-g0123456");
-    expect(normalizeGitVersion("04567")).toBe("0.0.0-g04567");
+    // when there are no tags in the history at all.
+    expect(normalizeGitVersion("f1415e96")).toBe("0.0.0-f1415e96");
+    expect(normalizeGitVersion("abc1234")).toBe("0.0.0-abc1234");
   });
 });
 

apps/desktop/src/main/context-menu.test.ts

@@ -1,221 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from "vitest";
-
-// Capture every MenuItem the SUT constructs so each test can assert
-// on the menu that would appear at popup time without booting an
-// actual Electron window. State is created via `vi.hoisted` because
-// `vi.mock` factories are hoisted above all top-level statements; a
-// plain `const` would be a TDZ ReferenceError when the factory runs.
-type CapturedMenuItem = {
-  label?: string;
-  role?: string;
-  type?: string;
-  click?: () => void;
-};
-const ctx = vi.hoisted(() => ({
-  capturedItems: [] as CapturedMenuItem[][],
-  browserWindowFromWebContents: vi.fn(),
-  popupSpy: vi.fn(),
-  clipboardWriteText: vi.fn(),
-  openExternalSpy: vi.fn().mockResolvedValue(undefined),
-  preferredLanguagesRef: { current: ["en-US"] as string[] },
-}));
-
-vi.mock("electron", () => {
-  class MockMenu {
-    items: CapturedMenuItem[] = [];
-    constructor() {
-      ctx.capturedItems.push(this.items);
-    }
-    append(item: CapturedMenuItem) {
-      this.items.push(item);
-    }
-    popup(opts: unknown) {
-      ctx.popupSpy(opts);
-    }
-  }
-  class MockMenuItem {
-    label?: string;
-    role?: string;
-    type?: string;
-    click?: () => void;
-    constructor(opts: CapturedMenuItem) {
-      Object.assign(this, opts);
-    }
-  }
-  return {
-    BrowserWindow: { fromWebContents: ctx.browserWindowFromWebContents },
-    Menu: MockMenu,
-    MenuItem: MockMenuItem,
-    app: {
-      getPreferredSystemLanguages: () => ctx.preferredLanguagesRef.current,
-    },
-    clipboard: { writeText: ctx.clipboardWriteText },
-    shell: { openExternal: ctx.openExternalSpy },
-  };
-});
-
-import { installContextMenu } from "./context-menu";
-
-type ContextMenuParams = {
-  selectionText: string;
-  isEditable: boolean;
-  linkURL: string;
-  editFlags: {
-    canCut: boolean;
-    canCopy: boolean;
-    canPaste: boolean;
-    canSelectAll: boolean;
-  };
-};
-
-type Listener = (event: unknown, params: ContextMenuParams) => void;
-
-// Tiny WebContents stub — we only need the `.on("context-menu", ...)`
-// hook the SUT installs and a way to fire it back at our own listener
-// list. Everything else (clipboard, link opening, label resolution) is
-// mocked above.
-function makeWebContents() {
-  const handlers: Listener[] = [];
-  return {
-    on(event: string, fn: Listener) {
-      if (event === "context-menu") handlers.push(fn);
-    },
-    fire(params: ContextMenuParams) {
-      for (const h of handlers) h({}, params);
-    },
-  };
-}
-
-const baseEditFlags = {
-  canCut: false,
-  canCopy: false,
-  canPaste: false,
-  canSelectAll: false,
-};
-
-describe("installContextMenu — link items", () => {
-  beforeEach(() => {
-    ctx.capturedItems.length = 0;
-    ctx.popupSpy.mockClear();
-    ctx.clipboardWriteText.mockClear();
-    ctx.openExternalSpy.mockClear();
-    ctx.browserWindowFromWebContents.mockReset();
-    ctx.preferredLanguagesRef.current = ["en-US"];
-  });
-
-  it("adds 'Open Link in Browser' and 'Copy Link Address' when right-clicking an http(s) link", () => {
-    // The link case is the one this test file is here to cover —
-    // before MUL-3083 follow-up, right-clicking an <a> in the
-    // renderer only surfaced 'copy' (when the user happened to have
-    // text selected) and gave no way to open the URL externally.
-    const wc = makeWebContents();
-    installContextMenu(wc as never);
-    wc.fire({
-      ...baseSelection({ linkURL: "https://multica.ai/welcome" }),
-    });
-
-    const labels = lastMenuLabels();
-    expect(labels).toContain("Open Link in Browser");
-    expect(labels).toContain("Copy Link Address");
-
-    // The two click handlers must route to the existing
-    // openExternalSafely allowlist + clipboard.writeText.
-    invokeByLabel("Open Link in Browser");
-    expect(ctx.openExternalSpy).toHaveBeenCalledWith("https://multica.ai/welcome");
-
-    invokeByLabel("Copy Link Address");
-    expect(ctx.clipboardWriteText).toHaveBeenCalledWith(
-      "https://multica.ai/welcome",
-    );
-    expect(ctx.popupSpy).toHaveBeenCalledTimes(1);
-  });
-
-  it("does NOT add link items when the cursor is over a non-http(s) URL", () => {
-    // Only http(s) links are surfaced — we don't promise anything for
-    // mailto:, javascript:, custom app schemes, etc. Surfacing them
-    // would shell out via openExternalSafely (which would block the
-    // call anyway) or write a non-URL string to the clipboard, both
-    // of which violate user expectations for a "link" item.
-    const wc = makeWebContents();
-    installContextMenu(wc as never);
-    wc.fire(baseSelection({ linkURL: "javascript:alert(1)" }));
-    const labels = lastMenuLabelsOrEmpty();
-    expect(labels).not.toContain("Open Link in Browser");
-    expect(labels).not.toContain("Copy Link Address");
-  });
-
-  it("does NOT add link items when there is no link under the cursor", () => {
-    const wc = makeWebContents();
-    installContextMenu(wc as never);
-    wc.fire({
-      selectionText: "hello",
-      isEditable: false,
-      linkURL: "",
-      editFlags: { ...baseEditFlags, canCopy: true },
-    });
-    const labels = lastMenuLabelsOrEmpty();
-    expect(labels).not.toContain("Open Link in Browser");
-    // Selection-only context still surfaces copy as before — guards
-    // against a regression where adding the link branch broke the
-    // base path.
-    expect(menuItemRoles()).toContain("copy");
-  });
-
-  it("uses zh-Hans labels when the OS preferred language is Chinese", () => {
-    // Locale fallback is intentionally permissive: every zh-* variant
-    // routes to zh-Hans so users on zh-CN / zh-TW / zh-HK still see
-    // Chinese rather than dropping to English. The renderer ships only
-    // zh-Hans translations, so this matches the rest of the app.
-    ctx.preferredLanguagesRef.current = ["zh-CN"];
-    const wc = makeWebContents();
-    installContextMenu(wc as never);
-    wc.fire(baseSelection({ linkURL: "https://multica.ai" }));
-    expect(lastMenuLabels()).toContain("在浏览器中打开链接");
-    expect(lastMenuLabels()).toContain("复制链接地址");
-  });
-
-  it("falls back to English when the OS preferred language is something we don't ship", () => {
-    ctx.preferredLanguagesRef.current = ["fr-FR"];
-    const wc = makeWebContents();
-    installContextMenu(wc as never);
-    wc.fire(baseSelection({ linkURL: "https://multica.ai" }));
-    expect(lastMenuLabels()).toContain("Open Link in Browser");
-  });
-});
-
-// --- helpers ---
-
-function baseSelection(over: Partial<ContextMenuParams>): ContextMenuParams {
-  return {
-    selectionText: "",
-    isEditable: false,
-    linkURL: "",
-    editFlags: { ...baseEditFlags },
-    ...over,
-  };
-}
-
-function lastMenu(): CapturedMenuItem[] {
-  const last = ctx.capturedItems[ctx.capturedItems.length - 1];
-  if (!last) throw new Error("no menu was constructed");
-  return last;
-}
-
-function lastMenuLabelsOrEmpty(): string[] {
-  const last = ctx.capturedItems[ctx.capturedItems.length - 1] ?? [];
-  return last.map((i) => i.label ?? "");
-}
-
-function lastMenuLabels(): string[] {
-  return lastMenu().map((i) => i.label ?? "");
-}
-
-function menuItemRoles(): string[] {
-  return lastMenu().map((i) => i.role ?? "");
-}
-
-function invokeByLabel(label: string): void {
-  const item = lastMenu().find((i) => i.label === label);
-  if (!item) throw new Error(`menu item not found: ${label}`);
-  item.click?.();
-}

apps/desktop/src/main/context-menu.ts

@@ -1,38 +1,12 @@
-import {
-  BrowserWindow,
-  Menu,
-  MenuItem,
-  app,
-  clipboard,
-  type WebContents,
-} from "electron";
-import { isSafeExternalHttpUrl, openExternalSafely } from "./external-url";
+import { BrowserWindow, Menu, MenuItem, type WebContents } from "electron";
 
 // Electron ships with no default right-click menu, so a user selecting text
 // in the renderer has no way to copy it. Mirror Chrome's minimal clipboard
 // menu using `roles`, which keeps i18n + accelerator handling native.
-//
-// Custom (non-role) link items below are NOT auto-localized by Electron —
-// roles like "copy" pull labels from the OS, but a custom MenuItem only
-// shows the `label` you give it. We translate by OS-preferred language so
-// the link items at least track Chinese / Japanese / Korean speakers
-// alongside the English default; everything else falls through to English,
-// which matches Chrome's behavior on those locales without app-level
-// translation files.
 export function installContextMenu(webContents: WebContents): void {
   webContents.on("context-menu", (_event, params) => {
-    const { editFlags, selectionText, isEditable, linkURL } = params;
+    const { editFlags, selectionText, isEditable } = params;
     const hasSelection = selectionText.trim().length > 0;
-    // params.linkURL is the resolved absolute URL of the anchor under the
-    // cursor; Electron normalizes relative hrefs against the page URL for
-    // us, so we only need to gate on the http(s) scheme allowlist
-    // (mirrors openExternalSafely + the renderer's <a> usage). Empty for
-    // non-link right-clicks; other schemes (mailto:, javascript:, custom
-    // app schemes) are intentionally not surfaced — opening them via
-    // shell.openExternal would route through the OS handler and is
-    // outside what this menu promises.
-    const linkIsHttpUrl = !!linkURL && isSafeExternalHttpUrl(linkURL);
-    const labels = pickLabels();
 
     const menu = new Menu();
 
@@ -52,87 +26,8 @@ export function installContextMenu(webContents: WebContents): void {
       menu.append(new MenuItem({ role: "selectAll" }));
     }
 
-    // Link items — only when the cursor is over an actual http(s) <a>.
-    // Without these the renderer's <a target="_blank"> gives users no
-    // standard right-click affordance ("Open in new window", "Copy link
-    // address"); the default click handler does forward to
-    // setWindowOpenHandler → openExternalSafely, but discoverability via
-    // the keyboard / mouse context menu was missing.
-    if (linkIsHttpUrl) {
-      if (menu.items.length > 0) {
-        menu.append(new MenuItem({ type: "separator" }));
-      }
-      menu.append(
-        new MenuItem({
-          label: labels.openLink,
-          click: () => {
-            // openExternalSafely re-validates the scheme — defense in
-            // depth in case Electron ever surfaces a non-http linkURL
-            // we forgot to filter at this layer.
-            void openExternalSafely(linkURL);
-          },
-        }),
-      );
-      menu.append(
-        new MenuItem({
-          label: labels.copyLinkAddress,
-          click: () => {
-            clipboard.writeText(linkURL);
-          },
-        }),
-      );
-    }
-
     if (menu.items.length === 0) return;
     const window = BrowserWindow.fromWebContents(webContents) ?? undefined;
     menu.popup({ window });
   });
 }
-
-// Labels for the two link-related menu items in the user's OS-preferred
-// language, with English as the fallback. Kept inline because the main
-// process has no shared i18n loader (the renderer's i18next is per-window
-// and not reachable from here), and pulling one in for two strings would
-// be more rope than payload. Matches the four locales the renderer ships.
-type ContextMenuLabels = {
-  openLink: string;
-  copyLinkAddress: string;
-};
-
-const labelsByLocale: Record<string, ContextMenuLabels> = {
-  en: {
-    openLink: "Open Link in Browser",
-    copyLinkAddress: "Copy Link Address",
-  },
-  "zh-Hans": {
-    openLink: "在浏览器中打开链接",
-    copyLinkAddress: "复制链接地址",
-  },
-  ja: {
-    openLink: "ブラウザでリンクを開く",
-    copyLinkAddress: "リンクのアドレスをコピー",
-  },
-  ko: {
-    openLink: "브라우저에서 링크 열기",
-    copyLinkAddress: "링크 주소 복사",
-  },
-};
-
-// pickLabels resolves the OS-preferred language to one of the four
-// locales we ship copy for. We say "Open Link in Browser" rather than
-// "Open Link in New Window" because the link is opened via
-// shell.openExternal — it lands in the user's default browser, not in
-// another Multica window — so the wording matches what actually
-// happens.
-function pickLabels(): ContextMenuLabels {
-  const preferred = app.getPreferredSystemLanguages()[0]?.toLowerCase() ?? "";
-  if (preferred.startsWith("zh")) {
-    // All Chinese variants get the Simplified copy — Multica only
-    // ships zh-Hans, and zh-Hant users falling through to en would be
-    // worse than reading Simplified Chinese.
-    return labelsByLocale["zh-Hans"];
-  }
-  if (preferred.startsWith("ja")) return labelsByLocale.ja;
-  if (preferred.startsWith("ko")) return labelsByLocale.ko;
-  return labelsByLocale.en;
-}

apps/desktop/src/main/daemon-auth-probe.test.ts

@@ -1,56 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { classifyAuthProbe, isAuthStatusError } from "./daemon-auth-probe";
-
-describe("classifyAuthProbe", () => {
-  it("treats a 401 as expired login", () => {
-    expect(classifyAuthProbe({ status: 401 })).toBe("auth_expired");
-  });
-
-  it("treats a missing token as expired login", () => {
-    expect(classifyAuthProbe({ noToken: true })).toBe("auth_expired");
-  });
-
-  it("treats a 2xx as a valid token (failure is non-auth)", () => {
-    expect(classifyAuthProbe({ status: 200 })).toBe("ok");
-    expect(classifyAuthProbe({ status: 204 })).toBe("ok");
-  });
-
-  // The headline guard: a network failure must never be reported as an auth
-  // problem — the daemon is just as unreachable for non-auth reasons.
-  it("does NOT classify a network error as expired login", () => {
-    expect(classifyAuthProbe({ networkError: true })).toBe("unknown");
-  });
-
-  it("leaves 5xx and other statuses inconclusive", () => {
-    expect(classifyAuthProbe({ status: 500 })).toBe("unknown");
-    expect(classifyAuthProbe({ status: 503 })).toBe("unknown");
-    expect(classifyAuthProbe({ status: 403 })).toBe("unknown");
-  });
-
-  it("is inconclusive when nothing is known", () => {
-    expect(classifyAuthProbe({})).toBe("unknown");
-  });
-});
-
-describe("isAuthStatusError", () => {
-  it("is true only for a 401-tagged error (session token is dead)", () => {
-    expect(isAuthStatusError(Object.assign(new Error("x"), { status: 401 }))).toBe(
-      true,
-    );
-  });
-
-  // The reviewer's must-fix: transient failures must NOT be treated as auth
-  // failures (which would log the user out). A 5xx mint, a thrown fetch, a
-  // file-write error — none carry status 401.
-  it("is false for transient / non-401 failures", () => {
-    expect(isAuthStatusError(Object.assign(new Error("x"), { status: 503 }))).toBe(
-      false,
-    );
-    expect(isAuthStatusError(new Error("network down"))).toBe(false);
-    expect(isAuthStatusError(new Error("EACCES: write failed"))).toBe(false);
-    expect(isAuthStatusError(undefined)).toBe(false);
-    expect(isAuthStatusError(null)).toBe(false);
-    expect(isAuthStatusError("401")).toBe(false);
-  });
-});

apps/desktop/src/main/daemon-auth-probe.ts

@@ -1,58 +0,0 @@
-/**
- * Pure classification for the daemon auth probe. Kept free of Electron imports
- * so it can be unit-tested in jsdom.
- *
- * When the local daemon fails to reach "running" shortly after a start, the
- * main process probes the daemon's token against the backend (GET /api/me) to
- * tell "the daemon can't authenticate" apart from "the daemon is slow / the
- * network is down / it crashed for another reason". Misclassifying a network
- * blip as an auth failure would be worse than the original silent-Starting bug,
- * so the rules below are deliberately conservative: only an explicit 401 (or a
- * missing credential) is treated as auth-expired.
- */
-
-export interface AuthProbeOutcome {
-  /** HTTP status code returned by the probe request, if one completed. */
-  status?: number;
-  /** The daemon profile has no token at all — there is nothing to validate. */
-  noToken?: boolean;
-  /** The probe request threw (timeout, connection refused, DNS, TLS). */
-  networkError?: boolean;
-}
-
-export type AuthProbeResult = "auth_expired" | "ok" | "unknown";
-
-/**
- * Whether an error represents a genuine auth rejection (HTTP 401) as opposed to
- * a transient failure (5xx, network, local I/O). Used by the re-authenticate
- * flow so that only a real 401 — the session token itself is dead — forces a
- * full re-login; transient failures keep the user signed in to retry.
- *
- * `mintPat` attaches the response status to the error it throws, so a 401
- * surfaces here as `{ status: 401 }`. Everything else (no status, 5xx, a thrown
- * fetch, a file-write error) is treated as non-auth.
- */
-export function isAuthStatusError(err: unknown): boolean {
-  return (
-    typeof err === "object" &&
-    err !== null &&
-    (err as { status?: unknown }).status === 401
-  );
-}
-
-export function classifyAuthProbe(outcome: AuthProbeOutcome): AuthProbeResult {
-  // No credential to validate → the user must sign in.
-  if (outcome.noToken) return "auth_expired";
-  // Couldn't reach the server → this is a network problem, not an auth one.
-  // Stay "unknown" so the caller keeps showing "starting"/"stopped" instead of
-  // wrongly prompting for re-login.
-  if (outcome.networkError) return "unknown";
-  // The server explicitly rejected the token.
-  if (outcome.status === 401) return "auth_expired";
-  // The token is accepted — the daemon is failing for some other reason.
-  if (outcome.status !== undefined && outcome.status >= 200 && outcome.status < 300) {
-    return "ok";
-  }
-  // 5xx and everything else are inconclusive about the token's validity.
-  return "unknown";
-}

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

@@ -17,37 +17,14 @@ import {
 import { join } from "path";
 import { homedir, hostname } from "os";
 import type { DaemonStatus, DaemonPrefs } from "../shared/daemon-types";
-import { daemonStatusAlive } from "../shared/daemon-types";
 import { ensureManagedCli, managedCliPath } from "./cli-bootstrap";
 import { decideVersionAction } from "./version-decision";
-import {
-  daemonLifecycleUnreachable,
-  isDaemonExternallyManaged,
-  normalizeHostOS,
-} from "./daemon-os";
-import {
-  classifyAuthProbe,
-  isAuthStatusError,
-  type AuthProbeResult,
-} from "./daemon-auth-probe";
 
 const DEFAULT_HEALTH_PORT = 19514;
 const POLL_INTERVAL_MS = 5_000;
 const PREFS_PATH = join(homedir(), ".multica", "desktop_prefs.json");
 const LOG_TAIL_RETRY_MS = 2_000;
 const LOG_TAIL_MAX_RETRIES = 5;
-// How long a start may sit in "starting" (with no /health) before we probe the
-// token to find out whether login expired. The daemon's own startup can legitimately
-// take a while (it renews the PAT and lists workspaces before serving /health), so we
-// wait past the common case to avoid probing healthy-but-slow starts.
-const AUTH_PROBE_GRACE_MS = 10_000;
-// `multica daemon start` blocks until the daemon reports ready, polling /health
-// for up to its own startup timeout (45s in server/cmd/multica/cmd_daemon.go) to
-// cover cold-start agent-version detection. This execFile timeout MUST stay
-// above that — otherwise Electron kills the CLI supervisor mid-startup and a
-// healthy-but-slow start is misreported as a failure (the detached daemon child
-// keeps running, so the UI flashes "stopped" then "running").
-const DAEMON_START_EXEC_TIMEOUT_MS = 60_000;
 
 const DEFAULT_PREFS: DaemonPrefs = { autoStart: true, autoStop: false };
 
@@ -71,15 +48,6 @@ let pendingVersionRestart = false;
 let targetApiBaseUrl: string | null = null;
 let activeProfile: ActiveProfile | null = null;
 
-// Auth-probe state for the current start attempt. When a start fails to reach
-// "running", we probe the daemon's token once (after AUTH_PROBE_GRACE_MS) to
-// decide whether the cause is an expired/invalid login. `authExpired` is sticky
-// until the next start attempt or a successful /health, so the UI keeps showing
-// the re-login prompt instead of flapping back to "starting". See #3512.
-let startingSince: number | null = null;
-let authProbeDone = false;
-let authExpired = false;
-
 // Serialize all writes to any profile config file. Multiple paths
 // (syncToken, resolveActiveProfile, clearToken, watch/unwatch handlers)
 // may try to write concurrently; chaining them avoids interleaved writes
@@ -166,8 +134,6 @@ function sendStatus(status: DaemonStatus): void {
 interface HealthPayload {
   status?: string;
   pid?: number;
-  /** Daemon's runtime.GOOS. Absent on daemons older than the #3916 fix. */
-  os?: string;
   uptime?: string;
   daemon_id?: string;
   device_name?: string;
@@ -195,36 +161,6 @@ async function fetchHealthAtPort(
   }
 }
 
-/**
- * Validates the daemon profile's token against the backend to find out whether
- * a stuck start is an auth problem. Hits the same endpoint `multica auth status`
- * uses (GET /api/me) with the exact token the daemon loads from config.json, so
- * the verdict matches what the daemon itself would get from the server.
- *
- * Only the HTTP status is inspected (never the body) so a future change to the
- * /api/me response shape can't break this — a 401 means the token is rejected,
- * a 2xx means it's fine, and a thrown request means the network is the problem,
- * not auth. See classifyAuthProbe for the full rule set.
- */
-async function probeTokenValidity(profile: string): Promise<AuthProbeResult> {
-  if (!targetApiBaseUrl) return "unknown";
-  const cfg = await readProfileConfig(profile);
-  const token = typeof cfg.token === "string" ? cfg.token : "";
-  if (!token) return classifyAuthProbe({ noToken: true });
-  try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 4_000);
-    const res = await fetch(`${targetApiBaseUrl.replace(/\/+$/, "")}/api/me`, {
-      headers: { Authorization: `Bearer ${token}` },
-      signal: controller.signal,
-    });
-    clearTimeout(timeout);
-    return classifyAuthProbe({ status: res.status });
-  } catch {
-    return classifyAuthProbe({ networkError: true });
-  }
-}
-
 // Desktop owns a dedicated CLI profile named after the target API host, so it
 // never reads or writes the user's hand-configured profiles. Profile dir:
 //   ~/.multica/profiles/desktop-<host>/
@@ -313,57 +249,12 @@ async function fetchHealth(): Promise<DaemonStatus> {
   const data = await fetchHealthAtPort(active.port);
 
   if (!data || data.status !== "running") {
-    // A start that never reaches "running" is the symptom; an expired/invalid
-    // login is the most common cause and the one with no other signal (the
-    // daemon exits before it can serve /health, so we can't read the reason
-    // from it). Probe the token once per attempt, after a grace period, to
-    // surface a re-login prompt instead of spinning on "starting" forever.
-    if (
-      currentState === "starting" &&
-      !authExpired &&
-      !authProbeDone &&
-      startingSince !== null &&
-      Date.now() - startingSince >= AUTH_PROBE_GRACE_MS
-    ) {
-      authProbeDone = true;
-      if ((await probeTokenValidity(active.name)) === "auth_expired") {
-        authExpired = true;
-      }
-    }
-    // Sticky: once login is known-expired, keep reporting it (even after
-    // currentState flips away from "starting") until the next start attempt or
-    // a successful /health clears the flag.
-    if (authExpired) {
-      return { state: "auth_expired", profile: active.name };
-    }
-    // The daemon binds /health before preflight finishes and self-reports
-    // "starting" until it's ready. Trust that over our own currentState, so a
-    // daemon booting on its own — or started via the CLI — surfaces as
-    // "starting" instead of "stopped".
-    if (data?.status === "starting") {
-      return { state: "starting", profile: active.name };
-    }
     return {
       state: currentState === "starting" ? "starting" : "stopped",
       profile: active.name,
     };
   }
 
-  // A live, authenticated daemon clears any prior auth-failure verdict so the
-  // re-login prompt disappears once the user reconnects.
-  authExpired = false;
-  startingSince = null;
-
-  // A running daemon whose OS differs from this host's is one we can't drive
-  // via the native lifecycle CLI (e.g. Linux-in-WSL2 behind a Windows desktop,
-  // reachable only over localhost forwarding). Surface it so the UI disables
-  // the auto-start/auto-stop toggles instead of letting them silently no-op,
-  // and so before-quit skips a stop that would never land. See #3916.
-  const externallyManaged = isDaemonExternallyManaged(
-    data.os,
-    normalizeHostOS(process.platform),
-  );
-
   // Safety: if we have a target URL and the daemon on our port reports a
   // different server_url, it's not "our" daemon — drop it and re-resolve.
   if (
@@ -387,7 +278,6 @@ async function fetchHealth(): Promise<DaemonStatus> {
       : 0,
     profile: active.name,
     serverUrl: data.server_url,
-    externallyManaged,
   };
 }
 
@@ -574,15 +464,6 @@ async function ensureRunningDaemonVersionMatches(): Promise<
 > {
   const active = await ensureActiveProfile();
   const running = await fetchHealthAtPort(active.port);
-
-  // Don't try to version-match a daemon we can't restart (e.g. WSL2). Treat it
-  // as up-to-date — restartDaemon would no-op anyway, and skipping here avoids
-  // a misleading "restarting daemon" log on every auto-start. #3916.
-  if (isDaemonExternallyManaged(running?.os, normalizeHostOS(process.platform))) {
-    pendingVersionRestart = false;
-    return "ok";
-  }
-
   const bundled = await getCliBinaryVersion();
   const action = decideVersionAction(bundled, running);
 
@@ -634,13 +515,7 @@ async function mintPat(jwt: string): Promise<string> {
   });
   if (!res.ok) {
     const body = await res.text().catch(() => "");
-    // Attach the status so callers can tell a genuine auth rejection (401 — the
-    // session token is dead) apart from a transient failure (5xx, etc.) without
-    // string-matching the message.
-    throw Object.assign(
-      new Error(`mint PAT failed: ${res.status} ${res.statusText} ${body}`),
-      { status: res.status },
-    );
+    throw new Error(`mint PAT failed: ${res.status} ${res.statusText} ${body}`);
   }
   const data = (await res.json()) as { token?: unknown };
   if (typeof data.token !== "string" || !data.token.startsWith("mul_")) {
@@ -705,10 +580,7 @@ async function syncToken(
   if (userChanged) {
     try {
       const existing = await fetchHealthAtPort(active.port);
-      if (daemonStatusAlive(existing?.status)) {
-        // Restart whether it's "running" or still "starting" — a booting daemon
-        // already loaded the old token at startup, so it must be restarted to
-        // pick up the rotated credentials.
+      if (existing?.status === "running") {
         console.log(
           "[daemon] user switched — restarting daemon with new credentials",
         );
@@ -748,52 +620,6 @@ async function clearToken(): Promise<void> {
   await removeProfileUserId(active.name);
 }
 
-// Result of a user-initiated daemon re-authentication. The distinction matters:
-// only `session_invalid` justifies signing the user out of the whole app; a
-// `transient` failure must keep them logged in so they can retry.
-export type ReauthResult =
-  | { ok: true }
-  | { ok: false; reason: "session_invalid" }
-  | { ok: false; reason: "transient"; message: string };
-
-function errorMessage(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}
-
-/**
- * Recover the local daemon from the "auth_expired" state. Drops the stale
- * cached PAT, mints a fresh one from the current session token, and restarts
- * the daemon so it loads the new credential.
- *
- * Failures are classified rather than collapsed: a 401 from the mint means the
- * session token itself is dead (`session_invalid` → the renderer drives a full
- * re-login); anything else — mint 5xx, a network blip, a config write error, a
- * restart hiccup — is `transient`, leaving the user signed in so they can retry.
- * This mirrors the conservative classification the startup probe already uses.
- */
-async function reauthenticate(
-  token: string,
-  userId: string,
-): Promise<ReauthResult> {
-  try {
-    await clearToken();
-    // syncToken mints a fresh PAT because clearToken just removed any cache.
-    await syncToken(token, userId);
-  } catch (err) {
-    if (isAuthStatusError(err)) return { ok: false, reason: "session_invalid" };
-    return { ok: false, reason: "transient", message: errorMessage(err) };
-  }
-  const restart = await restartDaemon();
-  if (!restart.success) {
-    return {
-      ok: false,
-      reason: "transient",
-      message: restart.error ?? "failed to restart daemon",
-    };
-  }
-  return { ok: true };
-}
-
 async function withGuard<T>(fn: () => Promise<T>): Promise<T | { success: false; error: string }> {
   if (operationInProgress) {
     return { success: false, error: "Another daemon operation is in progress" };
@@ -825,19 +651,12 @@ async function startDaemon(): Promise<{ success: boolean; error?: string }> {
 
   const active = await ensureActiveProfile();
   const existing = await fetchHealthAtPort(active.port);
-  if (daemonStatusAlive(existing?.status)) {
-    // A daemon is already up ("running") or booting ("starting") on this port —
-    // don't spawn a second one (the CLI rejects that as "already running").
-    // Let polling track it through to "running".
+  if (existing?.status === "running") {
     pollOnce();
     return { success: true };
   }
 
   currentState = "starting";
-  // Begin a fresh auth-probe window for this attempt.
-  startingSince = Date.now();
-  authProbeDone = false;
-  authExpired = false;
   sendStatus({ state: "starting" });
 
   const args = ["daemon", "start", ...profileArgs(active)];
@@ -846,7 +665,7 @@ async function startDaemon(): Promise<{ success: boolean; error?: string }> {
     execFile(
       bin,
       args,
-      { timeout: DAEMON_START_EXEC_TIMEOUT_MS, env: desktopSpawnEnv() },
+      { timeout: 20_000, env: desktopSpawnEnv() },
       (err) => {
         if (err) {
           currentState = "stopped";
@@ -864,40 +683,12 @@ async function startDaemon(): Promise<{ success: boolean; error?: string }> {
   });
 }
 
-/**
- * Fresh boundary preflight for stop/restart: read the active profile's CURRENT
- * /health and decide whether the daemon runs somewhere the app can't drive
- * (WSL2 etc.). Done per call rather than off the poll cache, so a lifecycle op
- * never shells out to a CLI that can't reach the daemon's process — even on
- * paths that didn't just poll (e.g. restart-on-user-switch in syncToken, which
- * calls restartDaemon directly). See #3916.
- */
-async function lifecycleBlockedByForeignDaemon(): Promise<boolean> {
-  const active = await ensureActiveProfile();
-  return daemonLifecycleUnreachable(
-    async () => (await fetchHealthAtPort(active.port))?.os,
-    normalizeHostOS(process.platform),
-  );
-}
-
 async function stopDaemon(): Promise<{ success: boolean; error?: string }> {
-  // Central lifecycle guard: a daemon running in an environment we can't drive
-  // (e.g. Linux in WSL2 behind a Windows desktop) can't be stopped by the
-  // native CLI — it would act on the host process namespace and no-op, while
-  // still flipping our state to "stopped". Bail as a successful no-op so every
-  // caller (logout, quit, restart, the Runtime card) is covered in one place
-  // rather than each remembering to check. Preflighted against live /health so
-  // it holds even when no poll ran first. #3916.
-  if (await lifecycleBlockedByForeignDaemon()) return { success: true };
-
   const bin = await resolveCliBinary();
   if (!bin) return { success: false, error: "multica CLI is not installed" };
 
   const active = await ensureActiveProfile();
   currentState = "stopping";
-  // An explicit stop is a clean reset — drop any pending auth-failure verdict.
-  authExpired = false;
-  startingSince = null;
   sendStatus({ state: "stopping" });
 
   const args = ["daemon", "stop", ...profileArgs(active)];
@@ -916,11 +707,6 @@ async function stopDaemon(): Promise<{ success: boolean; error?: string }> {
 }
 
 async function restartDaemon(): Promise<{ success: boolean; error?: string }> {
-  // Same central, live-preflighted guard as stopDaemon: we can neither stop nor
-  // start a daemon we don't manage, so don't try (user-switch, reauth,
-  // first-workspace, and any future restart caller all route through here).
-  // #3916.
-  if (await lifecycleBlockedByForeignDaemon()) return { success: true };
   const stopResult = await stopDaemon();
   if (!stopResult.success) return stopResult;
   return startDaemon();
@@ -1088,10 +874,6 @@ export function setupDaemonManager(
     (_event, token: string, userId: string) => syncToken(token, userId),
   );
   ipcMain.handle("daemon:clear-token", () => clearToken());
-  ipcMain.handle(
-    "daemon:reauthenticate",
-    (_event, token: string, userId: string) => reauthenticate(token, userId),
-  );
   ipcMain.handle("daemon:is-cli-installed", async () => {
     const bin = await resolveCliBinary();
     return bin !== null;
@@ -1168,8 +950,6 @@ export function setupDaemonManager(
         isQuitting = true;
         event.preventDefault();
         try {
-          // stopDaemon no-ops for an externally-managed daemon (WSL2 etc.), so
-          // this is safe and instant in that case — the guard lives there. #3916
           await stopDaemon();
         } catch {
           // Best-effort stop on quit

apps/desktop/src/main/daemon-os.test.ts

@@ -1,80 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import {
-  daemonLifecycleUnreachable,
-  isDaemonExternallyManaged,
-  normalizeHostOS,
-} from "./daemon-os";
-
-describe("normalizeHostOS", () => {
-  it("maps win32 to the GOOS spelling 'windows'", () => {
-    expect(normalizeHostOS("win32")).toBe("windows");
-  });
-
-  it("passes darwin and linux through unchanged (already GOOS spellings)", () => {
-    expect(normalizeHostOS("darwin")).toBe("darwin");
-    expect(normalizeHostOS("linux")).toBe("linux");
-  });
-});
-
-describe("isDaemonExternallyManaged", () => {
-  it("flags a Linux (WSL2) daemon behind a Windows desktop — the #3916 case", () => {
-    expect(isDaemonExternallyManaged("linux", normalizeHostOS("win32"))).toBe(
-      true,
-    );
-  });
-
-  // These three are the "不误伤" guarantees: a native daemon on each platform
-  // must keep its auto-start/auto-stop toggles.
-  it("does NOT flag a native Windows daemon under a Windows desktop", () => {
-    expect(isDaemonExternallyManaged("windows", normalizeHostOS("win32"))).toBe(
-      false,
-    );
-  });
-
-  it("does NOT flag a native macOS daemon under a macOS desktop", () => {
-    expect(isDaemonExternallyManaged("darwin", normalizeHostOS("darwin"))).toBe(
-      false,
-    );
-  });
-
-  it("does NOT flag a native Linux daemon under a Linux desktop", () => {
-    expect(isDaemonExternallyManaged("linux", normalizeHostOS("linux"))).toBe(
-      false,
-    );
-  });
-
-  // Fail safe: an older daemon that predates the `os` field reports nothing.
-  // Hiding a toggle on a guess would 误伤, so unknown OS = treat as manageable.
-  it("fails safe to false when the daemon reports no OS", () => {
-    expect(isDaemonExternallyManaged(undefined, "windows")).toBe(false);
-    expect(isDaemonExternallyManaged("", "windows")).toBe(false);
-  });
-});
-
-// The stop/restart lifecycle boundary funnels through this. It must read the
-// daemon's LIVE OS (not a cached poll value), so a restart on a path that
-// didn't just poll — e.g. user-switch — still can't shell out at a WSL2 daemon.
-describe("daemonLifecycleUnreachable", () => {
-  it("consults the live OS reader and blocks a foreign-OS (WSL2) daemon", async () => {
-    const readDaemonOS = vi.fn().mockResolvedValue("linux");
-    expect(await daemonLifecycleUnreachable(readDaemonOS, "windows")).toBe(true);
-    // Proves the decision came from a fresh read, not a stale cache.
-    expect(readDaemonOS).toHaveBeenCalledTimes(1);
-  });
-
-  it("allows a native daemon whose live OS matches the host", async () => {
-    expect(
-      await daemonLifecycleUnreachable(async () => "windows", "windows"),
-    ).toBe(false);
-    expect(
-      await daemonLifecycleUnreachable(async () => "darwin", "darwin"),
-    ).toBe(false);
-  });
-
-  it("fails safe to false when the live OS is unknown (older daemon / none running)", async () => {
-    expect(
-      await daemonLifecycleUnreachable(async () => undefined, "windows"),
-    ).toBe(false);
-  });
-});

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

@@ -1,67 +0,0 @@
-/**
- * Detecting a daemon the desktop app can't manage.
- *
- * The app reads daemon liveness over HTTP at 127.0.0.1:{port}/health, but it
- * starts/stops the daemon by shelling out to the bundled native CLI, which acts
- * on the *host* OS process namespace. On Windows with the daemon running inside
- * WSL2, /health is reachable via localhost forwarding (so status looks fine) but
- * the daemon's process lives in a separate Linux namespace the Windows CLI can't
- * touch — so auto-start / auto-stop silently do nothing (#3916).
- *
- * The reliable, low-false-positive signal is the daemon's own OS (reported as
- * `os` on /health, = runtime.GOOS) vs the desktop host OS. They only disagree
- * when the daemon runs in a foreign environment we can't drive. This module is
- * the single source of truth for that comparison so it stays unit-tested — the
- * cost of a false positive is hiding a working toggle from a native user, so the
- * logic must fail safe (treat unknown / matching as manageable).
- */
-
-/**
- * Normalize a Node `process.platform` value to the daemon's `runtime.GOOS`
- * vocabulary so the two are directly comparable. Only `win32` -> `windows`
- * actually differs across the platforms we ship (darwin/linux already match);
- * any other value passes through unchanged.
- */
-export function normalizeHostOS(platform: NodeJS.Platform): string {
-  return platform === "win32" ? "windows" : platform;
-}
-
-/**
- * Whether a running daemon is in an environment the desktop app can't control.
- *
- * Returns true ONLY when the daemon reports a concrete OS that differs from the
- * host's. Fails safe to false when:
- *   - `daemonOS` is missing/empty (older daemon that predates the `os` field, or
- *     a malformed response) — we can't prove it's foreign, so keep toggles live.
- *   - the OSes match — a normally-managed native daemon.
- *
- * Callers must only invoke this for a daemon that is actually running; a stopped
- * daemon has no OS to compare and its toggles must stay enabled.
- */
-export function isDaemonExternallyManaged(
-  daemonOS: string | undefined,
-  hostOS: string,
-): boolean {
-  if (typeof daemonOS !== "string" || daemonOS.length === 0) return false;
-  return daemonOS !== hostOS;
-}
-
-/**
- * Boundary preflight for daemon lifecycle ops (stop / restart): resolve the
- * daemon's CURRENT OS via `readDaemonOS` and return true when it's running
- * somewhere the app can't drive.
- *
- * `readDaemonOS` is a live `/health` read performed at the call site — never a
- * cached poll value. That is the whole point: a stale "manageable" cache would
- * let a lifecycle op shell out to a native CLI that can't reach a WSL2 daemon
- * (the PID lives in another namespace), which is exactly the bug. Taking the
- * reader as a parameter keeps this unit-testable without the electron-coupled
- * daemon-manager module, and lets the test prove the live value — not a cache —
- * drives the decision. See #3916.
- */
-export async function daemonLifecycleUnreachable(
-  readDaemonOS: () => Promise<string | undefined>,
-  hostOS: string,
-): Promise<boolean> {
-  return isDaemonExternallyManaged(await readDaemonOS(), hostOS);
-}

apps/desktop/src/main/freeze-breadcrumb.test.ts

@@ -1,90 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { mkdtempSync, rmSync, writeFileSync, existsSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import {
-  writeFreezeBreadcrumb,
-  readAndClearFreezeBreadcrumb,
-  clearFreezeBreadcrumb,
-  type FreezeBreadcrumb,
-} from "./freeze-breadcrumb";
-
-// Each test gets its own temp dir so the on-disk breadcrumb is isolated.
-const dirs: string[] = [];
-function tempFile(): string {
-  const dir = mkdtempSync(join(tmpdir(), "freeze-breadcrumb-"));
-  dirs.push(dir);
-  return join(dir, "last-client-failure.json");
-}
-
-afterEach(() => {
-  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
-});
-
-const sample: FreezeBreadcrumb = {
-  kind: "unresponsive",
-  context: { desktopRoute: { path: "/acme/issues" } },
-  ts: 1_700_000_000_000,
-  version: "0.3.1",
-};
-
-describe("freeze breadcrumb round-trip", () => {
-  it("writes then reads back the breadcrumb", () => {
-    const file = tempFile();
-    writeFreezeBreadcrumb(file, sample);
-    expect(readAndClearFreezeBreadcrumb(file)).toEqual(sample);
-  });
-
-  it("read clears the file so a failure reports exactly once", () => {
-    const file = tempFile();
-    writeFreezeBreadcrumb(file, sample);
-    expect(readAndClearFreezeBreadcrumb(file)).toEqual(sample);
-    expect(existsSync(file)).toBe(false);
-    expect(readAndClearFreezeBreadcrumb(file)).toBeNull();
-  });
-
-  it("clearFreezeBreadcrumb removes a pending breadcrumb (hang recovered)", () => {
-    const file = tempFile();
-    writeFreezeBreadcrumb(file, sample);
-    clearFreezeBreadcrumb(file);
-    expect(readAndClearFreezeBreadcrumb(file)).toBeNull();
-  });
-});
-
-// The breadcrumb crosses a process boundary (main writes, renderer flushes via
-// IPC) and lives across app versions — a future write shape or a corrupt file
-// must never throw into boot. CLAUDE.md "API Response Compatibility".
-describe("freeze breadcrumb defends against malformed input", () => {
-  it("returns null when no file exists", () => {
-    expect(readAndClearFreezeBreadcrumb(tempFile())).toBeNull();
-  });
-
-  it("returns null on corrupt JSON", () => {
-    const file = tempFile();
-    writeFileSync(file, "{ not valid json", "utf8");
-    expect(readAndClearFreezeBreadcrumb(file)).toBeNull();
-  });
-
-  it("returns null when `kind` is missing", () => {
-    const file = tempFile();
-    writeFileSync(file, JSON.stringify({ ts: 1, version: "x" }), "utf8");
-    expect(readAndClearFreezeBreadcrumb(file)).toBeNull();
-  });
-
-  it("returns null when `kind` is the wrong type", () => {
-    const file = tempFile();
-    writeFileSync(file, JSON.stringify({ kind: 42, context: {} }), "utf8");
-    expect(readAndClearFreezeBreadcrumb(file)).toBeNull();
-  });
-
-  it("returns null on a JSON null payload", () => {
-    const file = tempFile();
-    writeFileSync(file, "null", "utf8");
-    expect(readAndClearFreezeBreadcrumb(file)).toBeNull();
-  });
-
-  it("clearing a non-existent file is a no-op, never throws", () => {
-    expect(() => clearFreezeBreadcrumb(tempFile())).not.toThrow();
-  });
-});

apps/desktop/src/main/freeze-breadcrumb.ts

@@ -1,76 +0,0 @@
-import { writeFileSync, readFileSync, rmSync } from "node:fs";
-import type { FreezeBreadcrumb } from "../shared/freeze-breadcrumb";
-
-// When the renderer truly hangs or its process dies, it can't send telemetry
-// itself — the thread is blocked or gone. The main process (always alive) is
-// the only watcher that can react, but during the hang it can't reach the
-// renderer's posthog-js either. So it writes a breadcrumb to disk; the next
-// time a renderer boots, it reads + clears the file and reports the event.
-// This survives even a force-quit, which is the whole point.
-
-export type { FreezeBreadcrumb };
-
-/**
- * Best-effort write. A breadcrumb we can't persist is lost, never fatal.
- *
- * Known limitation: this is a single slot — last write wins. Multiple failures
- * within one session collapse to the last one, so per-session failure counts
- * are undercounted. Acceptable for now: telemetry aggregates presence and
- * frequency across users, not exhaustive per-session sequences. Upgrade to an
- * append/ring buffer if per-session failure chains become a question.
- */
-export function writeFreezeBreadcrumb(filePath: string, breadcrumb: FreezeBreadcrumb): void {
-  try {
-    writeFileSync(filePath, JSON.stringify(breadcrumb), "utf8");
-  } catch {
-    // Disk full / permissions — drop silently.
-  }
-}
-
-/**
- * Delete a persisted breadcrumb. Called when the renderer recovers from a hang
- * (a `responsive` event after `unresponsive`): the breadcrumb was written
- * pre-emptively while the thread was stuck, but since it came back, the
- * in-thread long-task watchdog already reports it — keeping the breadcrumb
- * would double-count it AND mislabel a recovered window as `recovered: false`.
- * Best-effort; a stale breadcrumb only costs one duplicate report.
- */
-export function clearFreezeBreadcrumb(filePath: string): void {
-  try {
-    rmSync(filePath, { force: true });
-  } catch {
-    // Nothing to clear / permissions — ignore.
-  }
-}
-
-/**
- * Read the breadcrumb and delete it in the same call, so a failure is reported
- * exactly once. Returns null when there's no breadcrumb (the normal case) or
- * when the file is unreadable / corrupt.
- */
-export function readAndClearFreezeBreadcrumb(filePath: string): FreezeBreadcrumb | null {
-  let raw: string;
-  try {
-    raw = readFileSync(filePath, "utf8");
-  } catch {
-    return null;
-  }
-  try {
-    rmSync(filePath, { force: true });
-  } catch {
-    // If we can't delete it we'd re-report next launch; acceptable over throwing.
-  }
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    if (
-      parsed &&
-      typeof parsed === "object" &&
-      typeof (parsed as FreezeBreadcrumb).kind === "string"
-    ) {
-      return parsed as FreezeBreadcrumb;
-    }
-  } catch {
-    // Corrupt JSON — drop.
-  }
-  return null;
-}

apps/desktop/src/main/index.ts

@@ -13,21 +13,11 @@ import { installNavigationGestures } from "./navigation-gestures";
 import { getAppVersion } from "./app-version";
 import { loadRuntimeConfig } from "./runtime-config-loader";
 import type { RuntimeConfigResult } from "../shared/runtime-config";
-import {
-  RENDERER_ROUTE_CONTEXT_CHANNEL,
-  sanitizeRendererRouteContext,
-  type RendererRouteContext,
-} from "../shared/renderer-route-context";
 import {
   createElectronReloadPrompt,
   installRendererRecoveryHandlers,
   type RendererRecoveryWindow,
 } from "./renderer-recovery";
-import {
-  writeFreezeBreadcrumb,
-  readAndClearFreezeBreadcrumb,
-  clearFreezeBreadcrumb,
-} from "./freeze-breadcrumb";
 
 // Bundled icon used for dock/taskbar branding. macOS/Windows production
 // builds let the OS pick up the icon from the .app bundle / .exe resources,
@@ -71,15 +61,7 @@ if (process.platform !== "win32") {
 
 const PROTOCOL = "multica";
 
-// Where the main process parks a freeze/crash breadcrumb until the next
-// renderer boot flushes it to telemetry. Lives in userData so it survives a
-// force-quit. Resolved lazily — app.getPath is only valid after `ready`.
-function freezeBreadcrumbPath(): string {
-  return join(app.getPath("userData"), "last-client-failure.json");
-}
-
 let mainWindow: BrowserWindow | null = null;
-let latestRendererRouteContext: RendererRouteContext | null = null;
 let runtimeConfigResult: RuntimeConfigResult = {
   ok: false,
   error: { message: "Runtime config has not loaded yet" },
@@ -144,7 +126,7 @@ function createWindow(): void {
     minWidth: 900,
     minHeight: 600,
     titleBarStyle: "hiddenInset",
-    trafficLightPosition: { x: 16, y: 17 },
+    trafficLightPosition: { x: 16, y: 13 },
     show: false,
     autoHideMenuBar: true,
     // Windows/Linux pick up the window/taskbar icon from this option.
@@ -183,19 +165,10 @@ function createWindow(): void {
       additionalArguments: [`--multica-locale=${systemLocale}`],
     },
   });
-  const window = mainWindow;
-  latestRendererRouteContext = null;
-
-  window.on("closed", () => {
-    if (mainWindow === window) {
-      mainWindow = null;
-      latestRendererRouteContext = null;
-    }
-  });
 
   // Strip Origin header from WebSocket upgrade requests so the server's
   // origin whitelist doesn't reject connections from localhost dev origins.
-  window.webContents.session.webRequest.onBeforeSendHeaders(
+  mainWindow.webContents.session.webRequest.onBeforeSendHeaders(
     { urls: ["wss://*/*", "ws://*/*"] },
     (details, callback) => {
       delete details.requestHeaders["Origin"];
@@ -203,8 +176,8 @@ function createWindow(): void {
     },
   );
 
-  window.on("ready-to-show", () => {
-    window.show();
+  mainWindow.on("ready-to-show", () => {
+    mainWindow?.show();
   });
 
   // Detect OS language changes while the app is running. Electron has no
@@ -212,28 +185,24 @@ function createWindow(): void {
   // catches the common case where users switch System Settings → Language
   // and bring the app back. The renderer decides whether to act (it ignores
   // the signal when the user has an explicit Settings choice).
-  window.on("focus", () => {
+  mainWindow.on("focus", () => {
     const current = getSystemLocale();
     if (current === lastKnownSystemLocale) return;
     lastKnownSystemLocale = current;
-    window.webContents.send("locale:system-changed", current);
+    mainWindow?.webContents.send("locale:system-changed", current);
   });
 
-  window.webContents.setWindowOpenHandler((details) => {
+  mainWindow.webContents.setWindowOpenHandler((details) => {
     openExternalSafely(details.url);
     return { action: "deny" };
   });
 
   // Window-level keyboard shortcuts. Calling preventDefault here prevents
   // both the renderer keydown AND the application menu accelerator, so
-  // anything we own here (reload-block, zoom, tab-close) is the sole handler
-  // for that combination — no double-fire with the macOS default View menu.
-  window.webContents.on("before-input-event", (event, input) => {
-    const result = handleAppShortcut(input, window.webContents);
-    if (result === "close-tab") {
-      event.preventDefault();
-      window.webContents.send("tab:close-active");
-    } else if (result) {
+  // 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();
     }
   });
@@ -255,7 +224,7 @@ function createWindow(): void {
     // 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.
-    window.webContents.on("console-message", (details) => {
+    mainWindow.webContents.on("console-message", (details) => {
       const { level, message, sourceId, lineNumber } = details;
       log(level, `${message} (${sourceId}:${lineNumber})`);
     });
@@ -263,7 +232,7 @@ function createWindow(): void {
     // 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.
-    window.webContents.on(
+    mainWindow.webContents.on(
       "did-fail-load",
       (_event, errorCode, errorDescription, validatedURL, isMainFrame) => {
         if (errorCode === -3) return;
@@ -276,41 +245,20 @@ function createWindow(): void {
 
   }
 
-  installRendererRecoveryHandlers(window as unknown as RendererRecoveryWindow, {
+  installRendererRecoveryHandlers(mainWindow as unknown as RendererRecoveryWindow, {
     isDev: is.dev,
     showReloadPrompt: createElectronReloadPrompt((options) =>
-      dialog.showMessageBox(window, options),
+      dialog.showMessageBox(mainWindow!, options),
     ),
-    getDiagnosticContext: () => ({
-      windowUrl: window.webContents.getURL(),
-      ...(latestRendererRouteContext
-        ? { desktopRoute: latestRendererRouteContext }
-        : {}),
-    }),
-    // Only persist in production: a true hang/crash can't report itself, so we
-    // write a breadcrumb and the next renderer boot flushes it to PostHog. Dev
-    // is excluded to keep field telemetry clean.
-    persistBreadcrumb: is.dev
-      ? undefined
-      : (payload) =>
-          writeFreezeBreadcrumb(freezeBreadcrumbPath(), {
-            kind: payload.kind,
-            context: payload.context,
-            ts: Date.now(),
-            version: getAppVersion(),
-          }),
-    clearBreadcrumb: is.dev
-      ? undefined
-      : () => clearFreezeBreadcrumb(freezeBreadcrumbPath()),
   });
 
-  installContextMenu(window.webContents);
-  installNavigationGestures(window);
+  installContextMenu(mainWindow.webContents);
+  installNavigationGestures(mainWindow);
 
   if (is.dev && process.env["ELECTRON_RENDERER_URL"]) {
-    window.loadURL(process.env["ELECTRON_RENDERER_URL"]);
+    mainWindow.loadURL(process.env["ELECTRON_RENDERER_URL"]);
   } else {
-    window.loadFile(join(__dirname, "../renderer/index.html"));
+    mainWindow.loadFile(join(__dirname, "../renderer/index.html"));
   }
 }
 
@@ -417,11 +365,6 @@ if (!gotTheLock) {
       return openExternalSafely(url);
     });
 
-    // Renderer requests window close (e.g. Cmd+W on last tab).
-    ipcMain.on("window:close", () => {
-      mainWindow?.close();
-    });
-
     ipcMain.handle("file:download-url", (_event, url: string) => {
       if (!mainWindow) {
         console.warn("[download] ignored file:download-url — mainWindow torn down");
@@ -440,14 +383,6 @@ if (!gotTheLock) {
       event.returnValue = { version: getAppVersion(), os };
     });
 
-    // Sync IPC: read + clear any freeze/crash breadcrumb left by a previous
-    // session. The renderer flushes it to telemetry on boot (it couldn't be
-    // reported when it happened — the renderer was hung or gone). Read-and-
-    // clear so a failure reports exactly once.
-    ipcMain.on("freeze:get-last", (event) => {
-      event.returnValue = readAndClearFreezeBreadcrumb(freezeBreadcrumbPath());
-    });
-
     // Sync IPC: preload exposes the validated runtime config before renderer
     // boot. If desktop.json exists but is invalid, renderer receives the
     // blocking error and must not silently fall back to the cloud defaults.
@@ -455,13 +390,6 @@ if (!gotTheLock) {
       event.returnValue = runtimeConfigResult;
     });
 
-    ipcMain.on(RENDERER_ROUTE_CONTEXT_CHANNEL, (event, context: unknown) => {
-      if (!mainWindow || event.sender !== mainWindow.webContents) return;
-      const sanitized = sanitizeRendererRouteContext(context);
-      if (!sanitized) return;
-      latestRendererRouteContext = sanitized;
-    });
-
     // IPC: toggle immersive mode — hides the macOS traffic lights so full-screen
     // modals (e.g. create-workspace) can place UI in the top-left corner
     // without fighting the native window controls' hit-test.

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

@@ -14,14 +14,13 @@ function makeWc(initialLevel = 0) {
 
 function key(
   k: string,
-  mods: Partial<Pick<ShortcutInput, "control" | "meta" | "shift">> = {},
+  mods: Partial<Pick<ShortcutInput, "control" | "meta">> = {},
 ): ShortcutInput {
   return {
     type: "keyDown",
     key: k,
     control: false,
     meta: false,
-    shift: false,
     ...mods,
   };
 }
@@ -151,36 +150,3 @@ describe("handleAppShortcut — unrelated keys pass through", () => {
     expect(handleAppShortcut(key("k", { meta: true }), wc, "darwin")).toBe(false);
   });
 });
-
-describe("handleAppShortcut — close tab (Cmd/Ctrl+W)", () => {
-  it('returns "close-tab" on Cmd+W (macOS)', () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("w", { meta: true }), wc, "darwin")).toBe("close-tab");
-  });
-
-  it('returns "close-tab" on Cmd+W uppercase', () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("W", { meta: true }), wc, "darwin")).toBe("close-tab");
-  });
-
-  it('returns "close-tab" on Ctrl+W (Linux/Windows)', () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("w", { control: true }), wc, "linux")).toBe("close-tab");
-    expect(handleAppShortcut(key("w", { control: true }), wc, "win32")).toBe("close-tab");
-  });
-
-  it("does not trigger without Cmd/Ctrl modifier", () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("w"), wc, "darwin")).toBe(false);
-  });
-
-  it("does not trigger on Cmd+Shift+W (reserved for close-window)", () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("W", { meta: true, shift: true }), wc, "darwin")).toBe(false);
-  });
-
-  it("does not trigger on Ctrl+Shift+W (reserved for close-window)", () => {
-    const wc = makeWc();
-    expect(handleAppShortcut(key("W", { control: true, shift: true }), wc, "linux")).toBe(false);
-  });
-});

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

@@ -8,7 +8,6 @@ export type ShortcutInput = {
   key: string;
   control: boolean;
   meta: boolean;
-  shift: boolean;
 };
 
 // Subset of WebContents the zoom handler needs. Keeps the test mock tiny.
@@ -35,19 +34,11 @@ const ZOOM_MAX = 4.5;
  * Handling the shortcuts here gives identical behavior on every platform
  * and every layout.
  */
-/**
- * Result of handleAppShortcut:
- * - `false`: not handled, let Electron continue
- * - `true`: handled (preventDefault), no further action
- * - `"close-tab"`: Cmd/Ctrl+W intercepted — caller should send IPC to renderer
- */
-export type ShortcutResult = boolean | "close-tab";
-
 export function handleAppShortcut(
   input: ShortcutInput,
   webContents: ZoomTarget,
   platform: NodeJS.Platform = process.platform,
-): ShortcutResult {
+): boolean {
   if (input.type !== "keyDown") return false;
   const cmdOrCtrl = platform === "darwin" ? input.meta : input.control;
 
@@ -79,12 +70,5 @@ export function handleAppShortcut(
     return true;
   }
 
-  // Cmd/Ctrl + W → close active tab (or window if last tab).
-  // Cmd/Ctrl + Shift + W is reserved for "close window" — do not intercept.
-  // Return a signal so the caller can send IPC to the renderer.
-  if (input.key.toLowerCase() === "w" && !input.shift) {
-    return "close-tab";
-  }
-
   return false;
 }

apps/desktop/src/main/renderer-recovery.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
-import { createElectronReloadPrompt, installRendererRecoveryHandlers } from "./renderer-recovery";
+import { installRendererRecoveryHandlers } from "./renderer-recovery";
 
 type Handler = (...args: unknown[]) => void;
 
@@ -83,50 +83,10 @@ describe("installRendererRecoveryHandlers", () => {
     vi.useFakeTimers();
     const fixture = makeWindow();
     const showReloadPrompt = vi.fn(async () => "dismiss" as const);
-    const desktopRoute = {
-      surface: "tab",
-      path: "/acme/issues/MUL-3239",
-      workspaceSlug: "acme",
-      tabId: "tab-1",
-      reportedAt: "2026-06-15T00:00:00.000Z",
-    };
 
     installRendererRecoveryHandlers(fixture.window, {
       isDev: false,
       showReloadPrompt,
-      getDiagnosticContext: () => ({
-        windowUrl:
-          "file:///Applications/Multica.app/Contents/Resources/app.asar/index.html",
-        desktopRoute,
-      }),
-      unresponsivePromptDelayMs: 100,
-    });
-
-    fixture.windowHandlers.get("unresponsive")?.();
-    await vi.advanceTimersByTimeAsync(100);
-
-    expect(showReloadPrompt).toHaveBeenCalledWith({
-      kind: "unresponsive",
-      context: {
-        windowUrl:
-          "file:///Applications/Multica.app/Contents/Resources/app.asar/index.html",
-        desktopRoute,
-      },
-    });
-    expect(fixture.reload).not.toHaveBeenCalled();
-  });
-
-  it("keeps prompting when diagnostic context collection fails", async () => {
-    vi.useFakeTimers();
-    const fixture = makeWindow();
-    const showReloadPrompt = vi.fn(async () => "dismiss" as const);
-
-    installRendererRecoveryHandlers(fixture.window, {
-      isDev: false,
-      showReloadPrompt,
-      getDiagnosticContext: () => {
-        throw new Error("diagnostics unavailable");
-      },
       unresponsivePromptDelayMs: 100,
     });
 
@@ -134,6 +94,7 @@ describe("installRendererRecoveryHandlers", () => {
     await vi.advanceTimersByTimeAsync(100);
 
     expect(showReloadPrompt).toHaveBeenCalledWith({ kind: "unresponsive", context: {} });
+    expect(fixture.reload).not.toHaveBeenCalled();
   });
 
   it("keeps dev diagnostics non-prompting", async () => {
@@ -148,124 +109,4 @@ describe("installRendererRecoveryHandlers", () => {
     expect(showReloadPrompt).not.toHaveBeenCalled();
     expect(fixture.reload).not.toHaveBeenCalled();
   });
-
-  it("shows actionable recovery guidance before diagnostic details", async () => {
-    let detail = "";
-    const showMessageBox = vi.fn(
-      async (options: { title: string; message: string; detail: string }) => {
-        detail = options.detail;
-        return { response: 1 };
-      },
-    );
-    const showReloadPrompt = createElectronReloadPrompt(showMessageBox);
-
-    await showReloadPrompt({ kind: "unresponsive", context: {} });
-
-    expect(showMessageBox).toHaveBeenCalledWith(
-      expect.objectContaining({
-        title: "Multica needs to reload",
-        message: "The desktop window has been stuck for a few seconds.",
-        detail: expect.stringContaining(
-          "Click Reload to refresh this window and keep using Multica.",
-        ),
-      }),
-    );
-    expect(detail).toContain("what you were doing right before this message appeared");
-    expect(detail).toContain("Activity Monitor sample");
-    expect(detail).toContain("Diagnostic details:\nkind: unresponsive\ncontext: {}");
-  });
-});
-
-describe("freeze/crash breadcrumb state machine", () => {
-  beforeEach(() => vi.clearAllMocks());
-  afterEach(() => vi.useRealTimers());
-
-  function install(fixture: ReturnType<typeof makeWindow>) {
-    const persistBreadcrumb = vi.fn();
-    const clearBreadcrumb = vi.fn();
-    installRendererRecoveryHandlers(fixture.window, {
-      isDev: false,
-      showReloadPrompt: vi.fn(async () => "dismiss" as const),
-      persistBreadcrumb,
-      clearBreadcrumb,
-      unresponsivePromptDelayMs: 100,
-    });
-    return { persistBreadcrumb, clearBreadcrumb };
-  }
-
-  it("a sustained hang writes exactly one unresponsive breadcrumb", async () => {
-    vi.useFakeTimers();
-    const fixture = makeWindow();
-    const { persistBreadcrumb, clearBreadcrumb } = install(fixture);
-
-    fixture.windowHandlers.get("unresponsive")?.();
-    await vi.advanceTimersByTimeAsync(100);
-
-    expect(persistBreadcrumb).toHaveBeenCalledTimes(1);
-    expect(persistBreadcrumb).toHaveBeenCalledWith(
-      expect.objectContaining({ kind: "unresponsive" }),
-    );
-    expect(clearBreadcrumb).not.toHaveBeenCalled();
-  });
-
-  it("recovering after a written breadcrumb clears it (no double-count, no false recovered:false)", async () => {
-    vi.useFakeTimers();
-    const fixture = makeWindow();
-    const { persistBreadcrumb, clearBreadcrumb } = install(fixture);
-
-    fixture.windowHandlers.get("unresponsive")?.();
-    await vi.advanceTimersByTimeAsync(100);
-    expect(persistBreadcrumb).toHaveBeenCalledTimes(1);
-
-    fixture.windowHandlers.get("responsive")?.();
-    expect(clearBreadcrumb).toHaveBeenCalledTimes(1);
-  });
-
-  it("recovering before the delay never writes a breadcrumb, so nothing to clear", async () => {
-    vi.useFakeTimers();
-    const fixture = makeWindow();
-    const { persistBreadcrumb, clearBreadcrumb } = install(fixture);
-
-    fixture.windowHandlers.get("unresponsive")?.();
-    fixture.windowHandlers.get("responsive")?.();
-    await vi.advanceTimersByTimeAsync(100);
-
-    expect(persistBreadcrumb).not.toHaveBeenCalled();
-    expect(clearBreadcrumb).not.toHaveBeenCalled();
-  });
-
-  it("a hang that never recovers (force-quit) keeps its breadcrumb for next-boot reporting", async () => {
-    vi.useFakeTimers();
-    const fixture = makeWindow();
-    const { persistBreadcrumb, clearBreadcrumb } = install(fixture);
-
-    fixture.windowHandlers.get("unresponsive")?.();
-    await vi.advanceTimersByTimeAsync(100);
-
-    // No "responsive" ever fires — the breadcrumb must survive uncleared.
-    expect(persistBreadcrumb).toHaveBeenCalledTimes(1);
-    expect(clearBreadcrumb).not.toHaveBeenCalled();
-  });
-
-  it("a recoverable crash writes a breadcrumb and never clears it (a dead process never recovers)", () => {
-    const fixture = makeWindow();
-    const { persistBreadcrumb, clearBreadcrumb } = install(fixture);
-
-    fixture.webContentsHandlers.get("render-process-gone")?.({}, { reason: "crashed" });
-
-    expect(persistBreadcrumb).toHaveBeenCalledTimes(1);
-    expect(persistBreadcrumb).toHaveBeenCalledWith(
-      expect.objectContaining({ kind: "render-process-gone" }),
-    );
-    expect(clearBreadcrumb).not.toHaveBeenCalled();
-  });
-
-  it("a clean (non-crash) renderer exit writes no breadcrumb", () => {
-    const fixture = makeWindow();
-    const { persistBreadcrumb } = install(fixture);
-
-    fixture.webContentsHandlers.get("render-process-gone")?.({}, { reason: "clean-exit" });
-
-    expect(persistBreadcrumb).not.toHaveBeenCalled();
-  });
 });

apps/desktop/src/main/renderer-recovery.ts

@@ -17,22 +17,6 @@ type ReloadPromptResult = "reload" | "dismiss";
 type RendererRecoveryOptions = {
   isDev: boolean;
   showReloadPrompt: (payload: ReloadPromptPayload) => Promise<ReloadPromptResult>;
-  getDiagnosticContext?: () => Record<string, unknown>;
-  /**
-   * Persist a freeze/crash breadcrumb to disk. The renderer can't report a
-   * true hang or process death itself (blocked / gone), so the main process
-   * writes it here and the next renderer boot flushes it to telemetry. Omit
-   * in dev to keep field telemetry clean.
-   */
-  persistBreadcrumb?: (payload: ReloadPromptPayload) => void;
-  /**
-   * Delete a previously-persisted unresponsive breadcrumb. Called when the
-   * renderer recovers (`responsive` after `unresponsive`): the window came
-   * back, so the in-thread watchdog reports the freeze and the breadcrumb
-   * would only double-count it. Crash breadcrumbs are never cleared — a dead
-   * process never recovers.
-   */
-  clearBreadcrumb?: () => void;
   log?: (tag: string, ...args: unknown[]) => void;
   unresponsivePromptDelayMs?: number;
 };
@@ -42,21 +26,11 @@ export function installRendererRecoveryHandlers(
   {
     isDev,
     showReloadPrompt,
-    getDiagnosticContext,
-    persistBreadcrumb,
-    clearBreadcrumb,
     log = defaultDevLog,
     unresponsivePromptDelayMs = 1500,
   }: RendererRecoveryOptions,
 ) {
   let unresponsivePromptTimer: ReturnType<typeof setTimeout> | null = null;
-  // True once a breadcrumb has been written for the current hang. A later
-  // `responsive` clears it; only a hang that never returns survives to report.
-  let unresponsiveBreadcrumbWritten = false;
-  const mergeDiagnosticContext = (context: Record<string, unknown>) => ({
-    ...readDiagnosticContext(getDiagnosticContext),
-    ...context,
-  });
   const maybePromptReload = (payload: ReloadPromptPayload) => {
     if (isDev) return;
     void showReloadPrompt(payload).then((result) => {
@@ -69,23 +43,14 @@ export function installRendererRecoveryHandlers(
   window.webContents.on("render-process-gone", (_event, details) => {
     if (isDev) log("process-gone", JSON.stringify(details));
     if (!isRecoverableRendererExit(details)) return;
-    const payload: ReloadPromptPayload = {
-      kind: "render-process-gone",
-      context: mergeDiagnosticContext({ details }),
-    };
-    persistBreadcrumb?.(payload);
-    maybePromptReload(payload);
+    maybePromptReload({ kind: "render-process-gone", context: { details } });
   });
 
-  // preload-error intentionally does NOT persist a breadcrumb: it's a startup
-  // failure of the preload script itself, and the breadcrumb-flush path depends
-  // on that same preload exposing `getLastFreeze` — if preload is broken, the
-  // next boot couldn't read it back anyway. We only prompt for reload here.
   window.webContents.on("preload-error", (_event, preloadPath, error) => {
     if (isDev) log("preload-error", `path=${preloadPath} err=${formatError(error)}`);
     maybePromptReload({
       kind: "preload-error",
-      context: mergeDiagnosticContext({ preloadPath, error: formatError(error) }),
+      context: { preloadPath, error: formatError(error) },
     });
   });
 
@@ -93,27 +58,14 @@ export function installRendererRecoveryHandlers(
     if (isDev || unresponsivePromptTimer) return;
     unresponsivePromptTimer = setTimeout(() => {
       unresponsivePromptTimer = null;
-      const payload: ReloadPromptPayload = {
-        kind: "unresponsive",
-        context: mergeDiagnosticContext({}),
-      };
-      persistBreadcrumb?.(payload);
-      unresponsiveBreadcrumbWritten = true;
-      maybePromptReload(payload);
+      maybePromptReload({ kind: "unresponsive", context: {} });
     }, unresponsivePromptDelayMs);
   });
 
   window.on("responsive", () => {
-    if (unresponsivePromptTimer) {
-      clearTimeout(unresponsivePromptTimer);
-      unresponsivePromptTimer = null;
-    }
-    // The window came back: drop any breadcrumb written during this hang so it
-    // isn't re-reported (and mislabeled `recovered: false`) on next boot.
-    if (unresponsiveBreadcrumbWritten) {
-      clearBreadcrumb?.();
-      unresponsiveBreadcrumbWritten = false;
-    }
+    if (!unresponsivePromptTimer) return;
+    clearTimeout(unresponsivePromptTimer);
+    unresponsivePromptTimer = null;
   });
 }
 
@@ -157,30 +109,18 @@ function isRecoverableRendererExit(details: unknown) {
 function rendererRecoveryMessage(kind: ReloadPromptPayload["kind"]) {
   switch (kind) {
     case "render-process-gone":
-      return "The desktop window stopped unexpectedly.";
+      return "The desktop renderer process stopped responding or crashed.";
     case "preload-error":
-      return "The desktop window could not finish starting.";
+      return "The desktop preload script failed before the app could start.";
     case "unresponsive":
-      return "The desktop window has been stuck for a few seconds.";
+      return "The desktop window is not responding.";
   }
 }
 
 function rendererRecoveryDetail(payload: ReloadPromptPayload) {
-  const guidance = [
-    "Click Reload to refresh this window and keep using Multica.",
-    "If this keeps happening, please tell us what you were doing right before this message appeared and whether Reload recovered the window.",
-  ];
-
-  if (payload.kind === "unresponsive") {
-    guidance.push(
-      "For macOS reports, an Activity Monitor sample of the Multica Helper (Renderer) process helps us find what blocked the app.",
-    );
-  }
-
   return [
-    ...guidance,
+    "Reloading is the safest recovery path for this window.",
     "",
-    "Diagnostic details:",
     `kind: ${payload.kind}`,
     `context: ${JSON.stringify(payload.context)}`,
   ].join("\n");
@@ -190,17 +130,6 @@ function defaultDevLog(tag: string, ...args: unknown[]) {
   process.stderr.write(`[renderer ${tag}] ${args.map(String).join(" ")}\n`);
 }
 
-function readDiagnosticContext(
-  getDiagnosticContext: (() => Record<string, unknown>) | undefined,
-) {
-  if (!getDiagnosticContext) return {};
-  try {
-    return getDiagnosticContext();
-  } catch {
-    return {};
-  }
-}
-
 function formatError(error: unknown) {
   return error instanceof Error ? (error.stack ?? error.message) : String(error);
-}
+}

apps/desktop/src/main/updater.test.ts

@@ -1,170 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { BrowserWindow, WebContents } from "electron";
-
-type Handler = (...args: unknown[]) => void;
-
-const ctx = vi.hoisted(() => ({
-  handlers: new Map<string, Handler[]>(),
-  ipcHandle: vi.fn(),
-  checkForUpdates: vi.fn(async () => ({
-    updateInfo: { version: "0.3.18" },
-    isUpdateAvailable: false,
-  })),
-  downloadUpdate: vi.fn(),
-  quitAndInstall: vi.fn(),
-  getVersion: vi.fn(() => "0.3.17"),
-}));
-
-vi.mock("electron-updater", () => {
-  const autoUpdater = {
-    autoDownload: false,
-    autoInstallOnAppQuit: false,
-    channel: undefined as string | undefined,
-    on: vi.fn((event: string, handler: Handler) => {
-      const handlers = ctx.handlers.get(event) ?? [];
-      handlers.push(handler);
-      ctx.handlers.set(event, handlers);
-      return autoUpdater;
-    }),
-    checkForUpdates: ctx.checkForUpdates,
-    downloadUpdate: ctx.downloadUpdate,
-    quitAndInstall: ctx.quitAndInstall,
-  };
-  return { autoUpdater };
-});
-
-vi.mock("electron", () => ({
-  app: {
-    getVersion: ctx.getVersion,
-  },
-  BrowserWindow: class BrowserWindow {},
-  ipcMain: {
-    handle: ctx.ipcHandle,
-  },
-}));
-
-import { setupAutoUpdater } from "./updater";
-
-function emitUpdater(event: string, ...args: unknown[]) {
-  for (const handler of ctx.handlers.get(event) ?? []) {
-    handler(...args);
-  }
-}
-
-function makeWindow() {
-  const send = vi.fn();
-  return {
-    win: {
-      isDestroyed: () => false,
-      webContents: {
-        isDestroyed: () => false,
-        send,
-      },
-    } as unknown as BrowserWindow,
-    send,
-  };
-}
-
-function makeDestroyedWindow() {
-  return {
-    isDestroyed: () => true,
-    get webContents(): WebContents {
-      throw new TypeError("Object has been destroyed");
-    },
-  } as unknown as BrowserWindow;
-}
-
-function makeWindowWithDestroyedWebContents() {
-  const send = vi.fn(() => {
-    throw new TypeError("Object has been destroyed");
-  });
-  return {
-    win: {
-      isDestroyed: () => false,
-      webContents: {
-        isDestroyed: () => true,
-        send,
-      },
-    } as unknown as BrowserWindow,
-    send,
-  };
-}
-
-function makeWindowWithThrowingSend(error: Error) {
-  const send = vi.fn(() => {
-    throw error;
-  });
-  return {
-    win: {
-      isDestroyed: () => false,
-      webContents: {
-        isDestroyed: () => false,
-        send,
-      },
-    } as unknown as BrowserWindow,
-    send,
-  };
-}
-
-describe("setupAutoUpdater", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-    ctx.handlers.clear();
-    ctx.ipcHandle.mockClear();
-    ctx.checkForUpdates.mockClear();
-    ctx.downloadUpdate.mockClear();
-    ctx.quitAndInstall.mockClear();
-    ctx.getVersion.mockClear();
-  });
-
-  afterEach(() => {
-    vi.clearAllTimers();
-    vi.useRealTimers();
-  });
-
-  it("forwards update progress to a live renderer", () => {
-    const { win, send } = makeWindow();
-    setupAutoUpdater(() => win);
-
-    emitUpdater("download-progress", { percent: 42 });
-
-    expect(send).toHaveBeenCalledWith("updater:download-progress", {
-      percent: 42,
-    });
-  });
-
-  it("skips update progress when the BrowserWindow has already been destroyed", () => {
-    setupAutoUpdater(() => makeDestroyedWindow());
-
-    expect(() => emitUpdater("download-progress", { percent: 42 })).not.toThrow();
-  });
-
-  it("skips update progress when the BrowserWindow webContents has already been destroyed", () => {
-    const { win, send } = makeWindowWithDestroyedWebContents();
-    setupAutoUpdater(() => win);
-
-    expect(() => emitUpdater("download-progress", { percent: 42 })).not.toThrow();
-    expect(send).not.toHaveBeenCalled();
-  });
-
-  it("skips update progress when webContents.send loses a destroy race", () => {
-    const { win, send } = makeWindowWithThrowingSend(
-      new TypeError("Object has been destroyed"),
-    );
-    setupAutoUpdater(() => win);
-
-    expect(() => emitUpdater("download-progress", { percent: 42 })).not.toThrow();
-    expect(send).toHaveBeenCalledWith("updater:download-progress", {
-      percent: 42,
-    });
-  });
-
-  it("rethrows non-destroy errors from webContents.send", () => {
-    const { win } = makeWindowWithThrowingSend(new Error("boom"));
-    setupAutoUpdater(() => win);
-
-    expect(() => emitUpdater("download-progress", { percent: 42 })).toThrow(
-      "boom",
-    );
-  });
-});

apps/desktop/src/main/updater.ts

@@ -1,5 +1,5 @@
-import { autoUpdater, type UpdateDownloadedEvent } from "electron-updater";
-import { app, type BrowserWindow, ipcMain } from "electron";
+import { autoUpdater, UpdateDownloadedEvent } from "electron-updater";
+import { app, BrowserWindow, ipcMain } from "electron";
 
 // Silent background updates: electron-updater downloads on its own as soon
 // as `update-available` fires; we only surface UI when the package is fully
@@ -29,32 +29,6 @@ export type ManualUpdateCheckResult =
     }
   | { ok: false; error: string };
 
-type RendererChannel =
-  | "updater:update-available"
-  | "updater:download-progress"
-  | "updater:update-downloaded";
-
-function isDestroyedObjectError(err: unknown): boolean {
-  return err instanceof Error && err.message.includes("Object has been destroyed");
-}
-
-function sendToLiveRenderer(
-  win: BrowserWindow | null,
-  channel: RendererChannel,
-  payload: unknown,
-): void {
-  if (!win || win.isDestroyed()) return;
-
-  try {
-    const { webContents } = win;
-    if (webContents.isDestroyed()) return;
-    webContents.send(channel, payload);
-  } catch (err) {
-    if (isDestroyedObjectError(err)) return;
-    throw err;
-  }
-}
-
 // Single-flight guard around checkForUpdates(). With autoDownload=true the
 // startup, periodic, and manual triggers can all kick off downloads, and
 // overlapping calls have caused duplicate download warnings in the past
@@ -88,20 +62,23 @@ export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): voi
   autoUpdater.on("update-available", (info) => {
     // Forwarded for renderer-side state tracking only; the notification UI
     // does not render an "available" affordance with autoDownload=true.
-    sendToLiveRenderer(getMainWindow(), "updater:update-available", {
+    const win = getMainWindow();
+    win?.webContents.send("updater:update-available", {
       version: info.version,
       releaseNotes: info.releaseNotes,
     });
   });
 
   autoUpdater.on("download-progress", (progress) => {
-    sendToLiveRenderer(getMainWindow(), "updater:download-progress", {
+    const win = getMainWindow();
+    win?.webContents.send("updater:download-progress", {
       percent: progress.percent,
     });
   });
 
   autoUpdater.on("update-downloaded", (info: UpdateDownloadedEvent) => {
-    sendToLiveRenderer(getMainWindow(), "updater:update-downloaded", {
+    const win = getMainWindow();
+    win?.webContents.send("updater:update-downloaded", {
       version: info.version,
       releaseNotes: info.releaseNotes,
     });

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

@@ -1,8 +1,6 @@
 import { ElectronAPI } from "@electron-toolkit/preload";
 import type { RuntimeConfigResult } from "../shared/runtime-config";
 import type { NavigationGesture } from "../shared/navigation-gestures";
-import type { RendererRouteContextInput } from "../shared/renderer-route-context";
-import type { FreezeBreadcrumb } from "../shared/freeze-breadcrumb";
 
 interface DesktopAPI {
   /** App version + normalized OS, captured synchronously at preload time. */
@@ -16,9 +14,6 @@ interface DesktopAPI {
   onSystemLocaleChanged: (callback: (locale: string) => void) => () => void;
   /** Validated runtime endpoint config, or a blocking config error. */
   runtimeConfig: RuntimeConfigResult;
-  /** Read + clear any freeze/crash breadcrumb from a previous session, so the
-   *  renderer can flush it to telemetry on boot. Null when nothing's pending. */
-  getLastFreeze: () => FreezeBreadcrumb | null;
   /** Listen for auth token delivered via deep link. Returns an unsubscribe function. */
   onAuthToken: (callback: (token: string) => void) => () => void;
   /** Listen for invitation IDs delivered via deep link. Returns an unsubscribe function. */
@@ -50,8 +45,6 @@ interface DesktopAPI {
   ) => () => void;
   /** Listen for native macOS back/forward swipe gestures. Returns an unsubscribe function. */
   onNavigationGesture: (callback: (gesture: NavigationGesture) => void) => () => void;
-  /** Report the renderer's memory-router path for recovery diagnostics. */
-  setRendererRouteContext: (context: RendererRouteContextInput) => void;
   /** Open the OS folder picker and return the chosen absolute path.
    *  Used by the Project settings "Add local directory" flow. */
   pickDirectory: (
@@ -78,22 +71,10 @@ interface DesktopAPI {
       | "error";
     error?: string;
   }>;
-  /** Listen for Cmd/Ctrl+W tab-close requests from the main process.
-   *  Returns an unsubscribe function. */
-  onCloseActiveTab: (callback: () => void) => () => void;
-  /** Ask the main process to close the window. */
-  closeWindow: () => void;
 }
 
 interface DaemonStatus {
-  state:
-    | "running"
-    | "stopped"
-    | "starting"
-    | "stopping"
-    | "installing_cli"
-    | "cli_not_found"
-    | "auth_expired";
+  state: "running" | "stopped" | "starting" | "stopping" | "installing_cli" | "cli_not_found";
   pid?: number;
   uptime?: string;
   daemonId?: string;
@@ -109,11 +90,6 @@ interface DaemonPrefs {
   autoStop: boolean;
 }
 
-type DaemonReauthResult =
-  | { ok: true }
-  | { ok: false; reason: "session_invalid" }
-  | { ok: false; reason: "transient"; message: string };
-
 interface DaemonAPI {
   start: () => Promise<{ success: boolean; error?: string }>;
   stop: () => Promise<{ success: boolean; error?: string }>;
@@ -124,10 +100,6 @@ interface DaemonAPI {
   setTargetApiUrl: (url: string) => Promise<void>;
   syncToken: (token: string, userId: string) => Promise<void>;
   clearToken: () => Promise<void>;
-  reauthenticate: (
-    token: string,
-    userId: string,
-  ) => Promise<DaemonReauthResult>;
   isCliInstalled: () => Promise<boolean>;
   getPrefs: () => Promise<DaemonPrefs>;
   setPrefs: (prefs: Partial<DaemonPrefs>) => Promise<DaemonPrefs>;

apps/desktop/src/preload/index.ts

@@ -1,11 +1,6 @@
 import { contextBridge, ipcRenderer } from "electron";
 import { electronAPI } from "@electron-toolkit/preload";
 import type { RuntimeConfigResult } from "../shared/runtime-config";
-import type { FreezeBreadcrumb } from "../shared/freeze-breadcrumb";
-import {
-  RENDERER_ROUTE_CONTEXT_CHANNEL,
-  type RendererRouteContextInput,
-} from "../shared/renderer-route-context";
 import {
   isNavigationGesture,
   NAVIGATION_GESTURE_CHANNEL,
@@ -79,16 +74,6 @@ const desktopAPI = {
   },
   /** Validated runtime endpoint config, or a blocking config error. */
   runtimeConfig,
-  /** Read + clear any freeze/crash breadcrumb left by a previous session, so
-   *  the renderer can flush it to telemetry on boot. Returns null when there's
-   *  nothing pending (the normal case). */
-  getLastFreeze: (): FreezeBreadcrumb | null => {
-    try {
-      return ipcRenderer.sendSync("freeze:get-last") as FreezeBreadcrumb | null;
-    } catch {
-      return null;
-    }
-  },
   /** Listen for auth token delivered via deep link */
   onAuthToken: (callback: (token: string) => void) => {
     const handler = (_event: Electron.IpcRendererEvent, token: string) =>
@@ -171,38 +156,16 @@ const desktopAPI = {
       ipcRenderer.removeListener(NAVIGATION_GESTURE_CHANNEL, handler);
     };
   },
-  /** Report the renderer's memory-router path for recovery diagnostics. */
-  setRendererRouteContext: (context: RendererRouteContextInput) =>
-    ipcRenderer.send(RENDERER_ROUTE_CONTEXT_CHANNEL, context),
   /** 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),
-  /** Listen for Cmd/Ctrl+W tab-close requests from the main process.
-   *  The renderer should close the active tab; if it was the last tab,
-   *  call `closeWindow()` to dismiss the window. Returns an unsubscribe fn. */
-  onCloseActiveTab: (callback: () => void) => {
-    const handler = () => callback();
-    ipcRenderer.on("tab:close-active", handler);
-    return () => {
-      ipcRenderer.removeListener("tab:close-active", handler);
-    };
-  },
-  /** Ask the main process to close the window (used after closing the last tab). */
-  closeWindow: () => ipcRenderer.send("window:close"),
 };
 
 interface DaemonStatus {
-  state:
-    | "running"
-    | "stopped"
-    | "starting"
-    | "stopping"
-    | "installing_cli"
-    | "cli_not_found"
-    | "auth_expired";
+  state: "running" | "stopped" | "starting" | "stopping" | "installing_cli" | "cli_not_found";
   pid?: number;
   uptime?: string;
   daemonId?: string;
@@ -213,11 +176,6 @@ interface DaemonStatus {
   serverUrl?: string;
 }
 
-type DaemonReauthResult =
-  | { ok: true }
-  | { ok: false; reason: "session_invalid" }
-  | { ok: false; reason: "transient"; message: string };
-
 const daemonAPI = {
   start: (): Promise<{ success: boolean; error?: string }> =>
     ipcRenderer.invoke("daemon:start"),
@@ -240,11 +198,6 @@ const daemonAPI = {
     ipcRenderer.invoke("daemon:sync-token", token, userId),
   clearToken: (): Promise<void> =>
     ipcRenderer.invoke("daemon:clear-token"),
-  reauthenticate: (
-    token: string,
-    userId: string,
-  ): Promise<DaemonReauthResult> =>
-    ipcRenderer.invoke("daemon:reauthenticate", token, userId),
   isCliInstalled: (): Promise<boolean> =>
     ipcRenderer.invoke("daemon:is-cli-installed"),
   getPrefs: (): Promise<{ autoStart: boolean; autoStop: boolean }> =>

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

@@ -19,7 +19,6 @@ import { useTabStore } from "./stores/tab-store";
 import { useWindowOverlayStore } from "./stores/window-overlay-store";
 import { useDaemonIPCBridge } from "./platform/daemon-ipc-bridge";
 import { createDesktopLocaleAdapter } from "./platform/i18n-adapter";
-import { captureEvent } from "@multica/core/analytics";
 import { RESOURCES } from "@multica/views/locales";
 
 // BCP-47 region tags for the <html lang> attribute, mirroring
@@ -35,42 +34,10 @@ const HTML_LANG: Record<SupportedLocale, string> = {
 };
 
 
-/**
- * Cmd/Ctrl+W: close the active tab. When the last real tab is closed
- * (or no tabs/workspace exist — e.g. login page), close the window.
- *
- * Mounted at the App root so every renderer state — including login,
- * loading, onboarding, and runtime-config errors — has a working Cmd+W
- * handler. Without this, states outside the tab shell would swallow the
- * shortcut and do nothing.
- */
-function useCmdWCloseTab() {
-  useEffect(() => {
-    return window.desktopAPI.onCloseActiveTab(() => {
-      const store = useTabStore.getState();
-      const { activeWorkspaceSlug, byWorkspace } = store;
-      if (!activeWorkspaceSlug) {
-        // No workspace — nothing to close, dismiss the window.
-        window.desktopAPI.closeWindow();
-        return;
-      }
-      const group = byWorkspace[activeWorkspaceSlug];
-      if (!group || group.tabs.length <= 1) {
-        // Last tab (or no tabs) — close the window.
-        window.desktopAPI.closeWindow();
-        return;
-      }
-      // Multiple tabs — close the active one.
-      store.closeActiveTab();
-    });
-  }, []);
-}
-
 function AppContent() {
   const user = useAuthStore((s) => s.user);
   const isLoading = useAuthStore((s) => s.isLoading);
   const qc = useQueryClient();
-
   // Deep-link login runs loginWithToken → syncToken → listWorkspaces →
   // setQueryData sequentially. loginWithToken sets user+isLoading=false
   // as soon as getMe resolves, which would cause DesktopShell to mount
@@ -331,28 +298,6 @@ export default function App() {
   const { version, os } = window.desktopAPI.appInfo;
   const systemLocale = window.desktopAPI.systemLocale;
   const runtimeConfigResult = window.desktopAPI.runtimeConfig;
-  useCmdWCloseTab();
-
-  // Flush a freeze/crash breadcrumb the main process parked from a previous
-  // session. A true hang or process death can't report itself when it happens
-  // (the renderer is blocked or gone), so the main process persists it and we
-  // emit it here on the next boot. The in-thread, recoverable freeze tier is
-  // handled separately by the shared watchdog in CoreProvider.
-  useEffect(() => {
-    const last = window.desktopAPI.getLastFreeze();
-    if (!last) return;
-    const crashed = last.kind === "render-process-gone";
-    captureEvent(crashed ? "client_crash" : "client_unresponsive", {
-      // Spread context FIRST so our explicit fields below always win — a
-      // future context key (e.g. its own `source`) must not silently override.
-      ...last.context,
-      source: crashed ? "render-process-gone" : "main-unresponsive",
-      recovered: false,
-      breadcrumb_ts: last.ts,
-      crashed_version: last.version,
-    });
-  }, []);
-
   // Stable identity reference so downstream effects (WS reconnect) don't
   // tear down on every parent render.
   const identity = useMemo(

apps/desktop/src/renderer/src/components/daemon-panel.tsx

@@ -16,7 +16,6 @@ import {
   X,
 } from "lucide-react";
 import { cn } from "@multica/ui/lib/utils";
-import { copyText } from "@multica/ui/lib/clipboard";
 import { Button } from "@multica/ui/components/ui/button";
 import {
   Dialog,
@@ -195,12 +194,15 @@ export function DaemonPanel({
 
   const handleCopy = useCallback(async () => {
     const text = filtered.map((l) => l.raw).join("\n");
-    if (await copyText(text)) {
+    try {
+      await navigator.clipboard.writeText(text);
       toast.success(
         `Copied ${filtered.length} line${filtered.length === 1 ? "" : "s"}`,
       );
-    } else {
-      toast.error("Failed to copy");
+    } catch (err) {
+      toast.error("Failed to copy", {
+        description: err instanceof Error ? err.message : String(err),
+      });
     }
   }, [filtered]);
 

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

@@ -1,66 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { render, screen } from "@testing-library/react";
-
-import type { DaemonStatus } from "../../../shared/daemon-types";
-
-// The component only needs these to render; stub them so the test focuses on
-// the externally-managed branching, not data fetching.
-vi.mock("@tanstack/react-query", () => ({
-  useQuery: () => ({ data: [] }),
-}));
-vi.mock("@multica/core/hooks", () => ({
-  useWorkspaceId: () => "ws-1",
-}));
-vi.mock("@multica/core/runtimes", () => ({
-  runtimeListOptions: () => ({ queryKey: ["runtimes"] }),
-}));
-vi.mock("@multica/core/agents", () => ({
-  agentTaskSnapshotOptions: () => ({ queryKey: ["snapshot"] }),
-}));
-vi.mock("./daemon-panel", () => ({ DaemonPanel: () => null }));
-vi.mock("../platform/daemon-reauth", () => ({
-  reauthenticateDaemon: vi.fn(),
-}));
-vi.mock("sonner", () => ({
-  toast: { error: vi.fn(), success: vi.fn() },
-}));
-
-import { DaemonRuntimeActions } from "./daemon-runtime-card";
-
-function stubDaemonAPI(status: DaemonStatus) {
-  Object.defineProperty(window, "daemonAPI", {
-    configurable: true,
-    value: {
-      getStatus: vi.fn().mockResolvedValue(status),
-      onStatusChange: vi.fn(() => () => {}),
-    },
-  });
-}
-
-describe("DaemonRuntimeActions — externally managed daemon (#3916)", () => {
-  it("hides Stop/Restart and shows the managed-outside hint for a daemon the app can't control", async () => {
-    stubDaemonAPI({ state: "running", daemonId: "d1", externallyManaged: true });
-    render(<DaemonRuntimeActions />);
-
-    // View logs still renders, confirming the running branch mounted.
-    expect(await screen.findByText("View logs")).toBeInTheDocument();
-    expect(screen.getByText("Managed outside the app")).toBeInTheDocument();
-    expect(screen.queryByText("Restart")).not.toBeInTheDocument();
-    expect(screen.queryByText("Stop")).not.toBeInTheDocument();
-  });
-
-  it("shows Stop/Restart for a normally-managed running daemon (no 误伤)", async () => {
-    stubDaemonAPI({
-      state: "running",
-      daemonId: "d1",
-      externallyManaged: false,
-    });
-    render(<DaemonRuntimeActions />);
-
-    expect(await screen.findByText("Restart")).toBeInTheDocument();
-    expect(screen.getByText("Stop")).toBeInTheDocument();
-    expect(
-      screen.queryByText("Managed outside the app"),
-    ).not.toBeInTheDocument();
-  });
-});

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

@@ -6,8 +6,6 @@ import {
   RotateCw,
   Activity,
   ScrollText,
-  LogIn,
-  Info,
 } from "lucide-react";
 import { useQuery } from "@tanstack/react-query";
 import { useWorkspaceId } from "@multica/core/hooks";
@@ -24,7 +22,6 @@ import {
 } from "@multica/ui/components/ui/dialog";
 import { toast } from "sonner";
 import { DaemonPanel } from "./daemon-panel";
-import { reauthenticateDaemon } from "../platform/daemon-reauth";
 import type { DaemonStatus } from "../../../shared/daemon-types";
 import { DAEMON_STATE_LABELS } from "../../../shared/daemon-types";
 
@@ -118,24 +115,9 @@ export function DaemonRuntimeActions() {
     }
   }, []);
 
-  const handleReauth = useCallback(async () => {
-    setActionLoading(true);
-    await reauthenticateDaemon();
-    // onStatusChange resets actionLoading on the next status push; reset here
-    // too in case reauth logged out (unmount) or produced no status change.
-    setActionLoading(false);
-  }, []);
-
   const isRunning = status.state === "running";
-  // The daemon runs somewhere the app can't drive (e.g. inside WSL2): the
-  // lifecycle CLI acts on the host process namespace and can't reach it. Hide
-  // Stop/Restart so they don't silently no-op, mirroring the Settings tab. The
-  // real guard is in the main process (stopDaemon/restartDaemon); this is the
-  // matching UX. See #3916.
-  const externallyManaged = status.externallyManaged === true;
   const isStopped = status.state === "stopped";
   const isCliMissing = status.state === "cli_not_found";
-  const isAuthExpired = status.state === "auth_expired";
   const isTransitioning =
     status.state === "starting" || status.state === "stopping";
   const isInstalling = status.state === "installing_cli";
@@ -149,33 +131,24 @@ export function DaemonRuntimeActions() {
               <ScrollText className="size-3.5 mr-1.5" />
               View logs
             </Button>
-            {externallyManaged ? (
-              <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
-                <Info className="size-3.5 shrink-0" />
-                Managed outside the app
-              </span>
-            ) : (
-              <>
-                <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>
-              </>
-            )}
+            <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>
           </>
         )}
 
@@ -202,23 +175,6 @@ export function DaemonRuntimeActions() {
           </Button>
         )}
 
-        {isAuthExpired && (
-          <>
-            <span className="inline-flex items-center gap-1.5 text-xs text-destructive">
-              <AlertCircle className="size-3.5 shrink-0" />
-              Sign-in expired
-            </span>
-            <Button size="sm" onClick={handleReauth} disabled={actionLoading}>
-              {actionLoading ? (
-                <Activity className="size-3.5 mr-1.5 animate-pulse" />
-              ) : (
-                <LogIn className="size-3.5 mr-1.5" />
-              )}
-              Sign in again
-            </Button>
-          </>
-        )}
-
         {(isTransitioning || isInstalling) && (
           <Button size="sm" variant="outline" disabled>
             <Activity className="size-3.5 mr-1.5 animate-pulse" />

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

@@ -1,9 +1,7 @@
 import { useState, useEffect, useCallback, type ReactNode } from "react";
-import { AlertCircle, Info, LogIn } from "lucide-react";
 import { Button } from "@multica/ui/components/ui/button";
 import { Switch } from "@multica/ui/components/ui/switch";
 import { cn } from "@multica/ui/lib/utils";
-import { reauthenticateDaemon } from "../platform/daemon-reauth";
 import type { DaemonPrefs, DaemonStatus } from "../../../shared/daemon-types";
 import {
   DAEMON_STATE_COLORS,
@@ -63,7 +61,6 @@ export function DaemonSettingsTab() {
   const [cliInstalled, setCliInstalled] = useState<boolean | null>(null);
   const [saving, setSaving] = useState(false);
   const [status, setStatus] = useState<DaemonStatus>({ state: "stopped" });
-  const [reauthLoading, setReauthLoading] = useState(false);
 
   useEffect(() => {
     window.daemonAPI.getPrefs().then(setPrefs);
@@ -72,12 +69,6 @@ export function DaemonSettingsTab() {
     return window.daemonAPI.onStatusChange(setStatus);
   }, []);
 
-  const handleReauth = useCallback(async () => {
-    setReauthLoading(true);
-    await reauthenticateDaemon();
-    setReauthLoading(false);
-  }, []);
-
   const updatePref = useCallback(
     async (key: keyof DaemonPrefs, value: boolean) => {
       setSaving(true);
@@ -88,12 +79,6 @@ export function DaemonSettingsTab() {
     [],
   );
 
-  // The daemon runs somewhere the app can't drive (e.g. inside WSL2 behind a
-  // Windows desktop): /health is reachable but the lifecycle CLI can't reach
-  // its process. Auto-start/auto-stop can't work, so disable them and say why
-  // rather than letting the toggles silently no-op. See #3916.
-  const externallyManaged = status.externallyManaged === true;
-
   return (
     <div>
       <h2 className="text-lg font-semibold">Daemon</h2>
@@ -101,43 +86,6 @@ export function DaemonSettingsTab() {
         Configure how the local agent daemon behaves with the desktop app.
       </p>
 
-      {status.state === "auth_expired" && (
-        <div className="mt-4 flex items-start gap-3 rounded-lg border border-destructive/40 bg-destructive/5 px-4 py-3">
-          <AlertCircle className="mt-0.5 size-4 shrink-0 text-destructive" />
-          <div className="min-w-0 flex-1">
-            <p className="text-sm font-medium text-destructive">
-              Sign-in expired
-            </p>
-            <p className="mt-0.5 text-sm text-muted-foreground">
-              The local daemon couldn&apos;t authenticate, so this device
-              can&apos;t take tasks. Sign in again to restore it.
-            </p>
-          </div>
-          <Button
-            size="sm"
-            className="shrink-0"
-            onClick={handleReauth}
-            disabled={reauthLoading}
-          >
-            <LogIn className="size-3.5 mr-1.5" />
-            Sign in again
-          </Button>
-        </div>
-      )}
-
-      {externallyManaged && (
-        <div className="mt-4 flex items-start gap-3 rounded-lg border bg-muted/30 px-4 py-3">
-          <Info className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
-          <p className="min-w-0 text-sm text-muted-foreground">
-            This device&apos;s daemon runs outside the app — for example inside
-            WSL2 — so the app can&apos;t start or stop it. Start or stop it from
-            that environment with{" "}
-            <code className="font-mono text-xs">multica daemon start</code> /{" "}
-            <code className="font-mono text-xs">multica daemon stop</code>.
-          </p>
-        </div>
-      )}
-
       <div className="mt-6 divide-y">
         <SettingRow
           label="Auto-start on launch"
@@ -146,7 +94,7 @@ export function DaemonSettingsTab() {
           <Switch
             checked={prefs.autoStart}
             onCheckedChange={(checked) => updatePref("autoStart", checked)}
-            disabled={saving || externallyManaged}
+            disabled={saving}
           />
         </SettingRow>
 
@@ -157,7 +105,7 @@ export function DaemonSettingsTab() {
           <Switch
             checked={prefs.autoStop}
             onCheckedChange={(checked) => updatePref("autoStop", checked)}
-            disabled={saving || externallyManaged}
+            disabled={saving}
           />
         </SettingRow>
 

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

@@ -1,6 +1,5 @@
-import { useEffect, useRef, useSyncExternalStore } from "react";
+import { useEffect, useSyncExternalStore } from "react";
 import { ChevronLeft, ChevronRight } from "lucide-react";
-import { motion } from "motion/react";
 import { cn } from "@multica/ui/lib/utils";
 import { useTabHistory } from "@/hooks/use-tab-history";
 import { useActiveTitleSync } from "@/hooks/use-tab-sync";
@@ -15,7 +14,6 @@ import { AppSidebar } from "@multica/views/layout";
 import { SearchCommand, SearchTrigger } from "@multica/views/search";
 import { ChatFab, ChatWindow } from "@multica/views/chat";
 import { WorkspaceSlugProvider, paths, useCurrentWorkspace } from "@multica/core/paths";
-import { useNavigation } from "@multica/views/navigation";
 import { getCurrentSlug, subscribeToCurrentSlug } from "@multica/core/platform";
 import { useDesktopUnreadBadge } from "@multica/views/platform";
 import { DesktopNavigationProvider } from "@/platform/navigation";
@@ -23,69 +21,41 @@ import { TabBar } from "./tab-bar";
 import { TabContent } from "./tab-content";
 import { WindowOverlay } from "./window-overlay";
 
-const TOP_BAR_HEIGHT_CLASS = "h-12";
-const WINDOW_TOOLBAR_CLEARANCE = 184;
-const toolbarMotion = {
-  type: "spring",
-  stiffness: 420,
-  damping: 38,
-  mass: 0.8,
-} as const;
-
-function WindowToolbar() {
+function SidebarTopBar() {
   const { canGoBack, canGoForward, goBack, goForward } = useTabHistory();
-  const navButtonClassName =
-    "flex size-7 items-center justify-center rounded-md text-muted-foreground/70 transition-colors hover:bg-sidebar-accent hover:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-30";
 
   return (
     <div
-      className={cn(
-        "fixed left-0 top-0 z-30 flex w-[184px] shrink-0 items-center px-3",
-        TOP_BAR_HEIGHT_CLASS,
-      )}
+      className="h-12 shrink-0 flex items-center justify-end px-2"
       style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
     >
       <div
-        className="flex items-center gap-1 pl-[70px]"
+        className="flex items-center gap-0.5"
         style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
       >
-        <SidebarTrigger
-          className="size-7 text-muted-foreground/70 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"
-          style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
-        />
-        <div className="flex items-center gap-1">
-          <button
-            type="button"
-            onClick={goBack}
-            disabled={!canGoBack}
-            aria-label="Go back"
-            title="Go back"
-            className={navButtonClassName}
-            style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
-          >
-            <ChevronLeft className="size-4" />
-          </button>
-          <button
-            type="button"
-            onClick={goForward}
-            disabled={!canGoForward}
-            aria-label="Go forward"
-            title="Go forward"
-            className={navButtonClassName}
-            style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
-          >
-            <ChevronRight className="size-4" />
-          </button>
-        </div>
+        <button
+          type="button"
+          onClick={goBack}
+          disabled={!canGoBack}
+          aria-label="Go back"
+          className="flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-30 disabled:pointer-events-none"
+        >
+          <ChevronLeft className="size-4" />
+        </button>
+        <button
+          type="button"
+          onClick={goForward}
+          disabled={!canGoForward}
+          aria-label="Go forward"
+          className="flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-30 disabled:pointer-events-none"
+        >
+          <ChevronRight className="size-4" />
+        </button>
       </div>
     </div>
   );
 }
 
-function SidebarTopSpacer() {
-  return <div className={cn("shrink-0", TOP_BAR_HEIGHT_CLASS)} />;
-}
-
 function useNativeNavigationGestures() {
   const { goBack, goForward } = useTabHistory();
 
@@ -101,31 +71,30 @@ function useNativeNavigationGestures() {
 }
 
 // The main area's top bar doubles as a window drag region. When the sidebar
-// is not occupying main-flow width, leave room for the fixed window toolbar
-// so tabs do not land beneath the traffic lights / navigation controls.
+// is not occupying main-flow width — either user-collapsed (offcanvas) or
+// auto-hidden in mobile mode (<768px, becomes a sheet drawer) — we pad the
+// left side so tabs don't land under the macOS traffic lights (which live at
+// roughly x=16..68 and always hit-test above HTML), and surface a trigger so
+// the sidebar can be brought back without keyboard shortcut.
 function MainTopBar() {
   const { state, isMobile } = useSidebar();
   const sidebarHidden = state === "collapsed" || isMobile;
 
   return (
-    <motion.header
-      animate={{ paddingLeft: sidebarHidden ? WINDOW_TOOLBAR_CLEARANCE : 0 }}
-      className={cn("relative shrink-0 flex items-center gap-2", TOP_BAR_HEIGHT_CLASS)}
-      initial={false}
-      transition={toolbarMotion}
+    <header
+      className={cn(
+        "h-12 shrink-0 flex items-center gap-2",
+        sidebarHidden && "pl-20",
+      )}
+      style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
     >
-      <motion.div
-        aria-hidden
-        animate={{ left: sidebarHidden ? WINDOW_TOOLBAR_CLEARANCE : 0 }}
-        className="absolute inset-y-0 right-0"
-        initial={false}
-        transition={toolbarMotion}
-        style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
-      />
-      <div className="relative z-10 flex h-full items-center">
-        <TabBar />
-      </div>
-    </motion.header>
+      {sidebarHidden && (
+        <SidebarTrigger
+          style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
+        />
+      )}
+      <TabBar />
+    </header>
   );
 }
 
@@ -158,30 +127,18 @@ function useInternalLinkHandler() {
  *      inbox even if the user has since switched to workspace B. Marking
  *      the row read is handled by InboxPage's selected-item effect, which
  *      covers both click-to-select and URL-param-select paths.
- *
- * The click routes through `useNavigation().push` — NOT the
- * `multica:navigate` event, whose handler `openTab`s into the ACTIVE
- * workspace's tab group. The navigation adapter detects a cross-workspace
- * path and translates it into `switchWorkspace(slug, path)`, so clicking a
- * workspace-A notification while B is active performs a real workspace
- * switch instead of mounting A's inbox inside B's tab group (#3766).
  */
 function DesktopInboxBridge() {
   const workspace = useCurrentWorkspace();
   useDesktopUnreadBadge(workspace?.id ?? null);
-  const { push } = useNavigation();
-  // The adapter identity changes with the active tab's location; the ref
-  // keeps the main-process subscription stable across navigations.
-  const pushRef = useRef(push);
-  useEffect(() => {
-    pushRef.current = push;
-  }, [push]);
 
   useEffect(() => {
     return window.desktopAPI.onInboxOpen(({ slug, issueKey }) => {
       if (!slug) return;
       const inboxPath = `${paths.workspace(slug).inbox()}?issue=${encodeURIComponent(issueKey)}`;
-      pushRef.current(inboxPath);
+      window.dispatchEvent(
+        new CustomEvent("multica:navigate", { detail: { path: inboxPath } }),
+      );
     });
   }, []);
 
@@ -213,10 +170,9 @@ export function DesktopShell() {
         <DesktopInboxBridge />
         <div className="flex h-screen">
           <SidebarProvider className="flex-1">
-            {slug && <WindowToolbar />}
-            {slug && <AppSidebar topSlot={<SidebarTopSpacer />} searchSlot={<SearchTrigger />} />}
+            {slug && <AppSidebar topSlot={<SidebarTopBar />} searchSlot={<SearchTrigger />} />}
             {/* Right side: header + content container */}
-            <motion.div layout transition={toolbarMotion} className="flex flex-1 min-w-0 flex-col">
+            <div className="flex flex-1 min-w-0 flex-col">
               <MainTopBar />
               {/* Content area with inset styling — relative so ChatWindow/ChatFab are constrained here */}
               <div className="relative flex flex-1 min-h-0 flex-col overflow-hidden mr-2 mb-2 ml-0.5 rounded-xl shadow-sm bg-background">
@@ -224,7 +180,7 @@ export function DesktopShell() {
                 {slug && <ChatWindow />}
                 {slug && <ChatFab />}
               </div>
-            </motion.div>
+            </div>
           </SidebarProvider>
         </div>
         {slug && <ModalRegistry />}

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

@@ -7,7 +7,6 @@ import {
   useTabStore,
 } from "@/stores/tab-store";
 import { useWindowOverlayStore, type WindowOverlay } from "@/stores/window-overlay-store";
-import type { RendererRouteContextInput } from "../../../shared/renderer-route-context";
 
 /**
  * Fires a PostHog $pageview whenever the user's visible surface changes,
@@ -91,16 +90,6 @@ export function PageviewTracker() {
     const last = lastSurfaceRef.current;
     const next = { kind, key, path };
 
-    const routeContext: RendererRouteContextInput = {
-      surface: kind,
-      path,
-    };
-    if (kind === "tab") {
-      routeContext.workspaceSlug = activeWorkspaceSlug ?? undefined;
-      routeContext.tabId = activeTabId ?? undefined;
-    }
-    reportRendererRouteContext(routeContext);
-
     if (kind === "tab" && key !== null) {
       const knownPath = observed.get(key);
       const isReactivation =
@@ -123,13 +112,6 @@ export function PageviewTracker() {
   return null;
 }
 
-function reportRendererRouteContext(context: RendererRouteContextInput) {
-  const desktopAPI = window.desktopAPI as
-    | { setRendererRouteContext?: (context: RendererRouteContextInput) => void }
-    | undefined;
-  desktopAPI?.setRendererRouteContext?.(context);
-}
-
 function overlayPath(overlay: WindowOverlay): string {
   switch (overlay.type) {
     case "new-workspace":

apps/desktop/src/renderer/src/main.tsx

@@ -13,18 +13,4 @@ import "@fontsource/geist-mono/400.css";
 import "@fontsource/geist-mono/700.css";
 import "./globals.css";
 
-// react-grab: dev-only element inspector. Hold ⌘C (Mac) / Ctrl+C and click any
-// element to copy its source path + line + component stack for pasting to an AI.
-// Opt-in per developer: only loads when VITE_REACT_GRAB is set in a local,
-// gitignored apps/desktop/.env.development.local — it never activates for anyone
-// else, and the whole branch is tree-shaken out of production builds. The web app
-// wires the same tool via next/script in apps/web/app/layout.tsx.
-// See https://www.react-grab.com/
-if (import.meta.env.DEV && import.meta.env.VITE_REACT_GRAB) {
-  const grab = document.createElement("script");
-  grab.src = "//unpkg.com/react-grab/dist/index.global.js";
-  grab.crossOrigin = "anonymous";
-  document.head.appendChild(grab);
-}
-
 ReactDOM.createRoot(document.getElementById("root")!).render(<App />);

apps/desktop/src/renderer/src/platform/daemon-ipc-bridge.ts

@@ -11,14 +11,7 @@ import type { AgentRuntime } from "@multica/core/types";
  * to the desktop preload typings (which live in apps/desktop/src/preload).
  */
 interface DaemonStatusLike {
-  state:
-    | "running"
-    | "stopped"
-    | "starting"
-    | "stopping"
-    | "installing_cli"
-    | "cli_not_found"
-    | "auth_expired";
+  state: "running" | "stopped" | "starting" | "stopping" | "installing_cli" | "cli_not_found";
   daemonId?: string;
 }
 
@@ -32,11 +25,7 @@ interface DaemonStatusLike {
  * within 75s.
  */
 function mergeDaemonStatus(rt: AgentRuntime, status: DaemonStatusLike): AgentRuntime {
-  if (
-    status.state === "stopped" ||
-    status.state === "stopping" ||
-    status.state === "auth_expired"
-  ) {
+  if (status.state === "stopped" || status.state === "stopping") {
     return { ...rt, status: "offline" };
   }
   if (status.state === "running") {

apps/desktop/src/renderer/src/platform/daemon-reauth.test.ts

@@ -1,98 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const { mockGetState, logout } = vi.hoisted(() => ({
-  mockGetState: vi.fn(),
-  logout: vi.fn(),
-}));
-
-const { toastError } = vi.hoisted(() => ({ toastError: vi.fn() }));
-
-vi.mock("@multica/core/auth", () => ({
-  useAuthStore: { getState: mockGetState },
-}));
-
-vi.mock("sonner", () => ({
-  toast: { error: toastError },
-}));
-
-import { reauthenticateDaemon } from "./daemon-reauth";
-
-const daemonAPI = {
-  reauthenticate: vi.fn(),
-};
-
-beforeEach(() => {
-  vi.clearAllMocks();
-  localStorage.clear();
-  (window as unknown as { daemonAPI: typeof daemonAPI }).daemonAPI = daemonAPI;
-  mockGetState.mockReturnValue({ user: { id: "user-1" }, logout });
-});
-
-describe("reauthenticateDaemon", () => {
-  it("re-mints + restarts the daemon when signed in, without logging out", async () => {
-    localStorage.setItem("multica_token", "jwt-abc");
-    daemonAPI.reauthenticate.mockResolvedValue({ ok: true });
-
-    await reauthenticateDaemon();
-
-    expect(daemonAPI.reauthenticate).toHaveBeenCalledWith("jwt-abc", "user-1");
-    expect(logout).not.toHaveBeenCalled();
-    expect(toastError).not.toHaveBeenCalled();
-  });
-
-  it("logs out only when the session token itself is rejected (401)", async () => {
-    localStorage.setItem("multica_token", "jwt-abc");
-    daemonAPI.reauthenticate.mockResolvedValue({
-      ok: false,
-      reason: "session_invalid",
-    });
-
-    await reauthenticateDaemon();
-
-    expect(logout).toHaveBeenCalledOnce();
-    expect(toastError).not.toHaveBeenCalled();
-  });
-
-  // The reviewer's must-fix: a non-401 (transient) failure must NOT log the
-  // user out — they stay signed in and can retry.
-  it("does NOT log out on a transient failure; shows a retryable toast", async () => {
-    localStorage.setItem("multica_token", "jwt-abc");
-    daemonAPI.reauthenticate.mockResolvedValue({
-      ok: false,
-      reason: "transient",
-      message: "mint PAT failed: 503 Service Unavailable",
-    });
-
-    await reauthenticateDaemon();
-
-    expect(logout).not.toHaveBeenCalled();
-    expect(toastError).toHaveBeenCalledOnce();
-  });
-
-  it("does NOT log out when the IPC call itself throws unexpectedly", async () => {
-    localStorage.setItem("multica_token", "jwt-abc");
-    daemonAPI.reauthenticate.mockRejectedValue(new Error("ipc boom"));
-
-    await reauthenticateDaemon();
-
-    expect(logout).not.toHaveBeenCalled();
-    expect(toastError).toHaveBeenCalledOnce();
-  });
-
-  it("routes to login when there is no session token", async () => {
-    await reauthenticateDaemon();
-
-    expect(logout).toHaveBeenCalledOnce();
-    expect(daemonAPI.reauthenticate).not.toHaveBeenCalled();
-  });
-
-  it("routes to login when there is no signed-in user", async () => {
-    localStorage.setItem("multica_token", "jwt-abc");
-    mockGetState.mockReturnValue({ user: null, logout });
-
-    await reauthenticateDaemon();
-
-    expect(logout).toHaveBeenCalledOnce();
-    expect(daemonAPI.reauthenticate).not.toHaveBeenCalled();
-  });
-});

apps/desktop/src/renderer/src/platform/daemon-reauth.ts

@@ -1,48 +0,0 @@
-import { useAuthStore } from "@multica/core/auth";
-import { toast } from "sonner";
-
-/**
- * Re-establish the local daemon's credentials after it failed to authenticate
- * (daemon state "auth_expired", surfaced by daemon-manager's token probe — see
- * #3512).
- *
- * The desktop owns the daemon's PAT: it mints one from the user's session token
- * and caches it per profile. A stale/revoked cached PAT is the common cause (and
- * merely restarting the app reuses the same bad PAT), so the main process drops
- * the cached token, mints a fresh one, and restarts the daemon.
- *
- * Failure handling is deliberately conservative — we only force a full re-login
- * when the session token itself is rejected (a real 401). A transient failure
- * (mint 5xx, network blip, config write error, restart hiccup) keeps the user
- * signed in and shows a retryable toast, so a momentary glitch never logs them
- * out. The 401-vs-transient classification happens in the main process where the
- * real HTTP status is available; here we just act on the verdict.
- */
-export async function reauthenticateDaemon(): Promise<void> {
-  const user = useAuthStore.getState().user;
-  const token = localStorage.getItem("multica_token");
-  if (!user || !token) {
-    // No usable session at all — the standard recovery is the login page.
-    useAuthStore.getState().logout();
-    return;
-  }
-
-  try {
-    const result = await window.daemonAPI.reauthenticate(token, user.id);
-    if (result.ok) return; // daemon restarting; status flips via onStatusChange
-    if (result.reason === "session_invalid") {
-      // The session token itself is rejected (401) — full re-login.
-      useAuthStore.getState().logout();
-      return;
-    }
-    // Transient failure — keep the user signed in and let them retry.
-    toast.error("Couldn't reconnect the daemon", {
-      description: result.message || "Please try again in a moment.",
-    });
-  } catch (err) {
-    // An unexpected IPC error is not an auth failure — never log out on it.
-    toast.error("Couldn't reconnect the daemon", {
-      description: err instanceof Error ? err.message : "Please try again.",
-    });
-  }
-}

apps/desktop/src/shared/daemon-types.test.ts

@@ -1,22 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { daemonStatusAlive } from "./daemon-types";
-
-describe("daemonStatusAlive", () => {
-  it("treats a ready daemon as alive", () => {
-    expect(daemonStatusAlive("running")).toBe(true);
-  });
-
-  it("treats a still-booting daemon as alive", () => {
-    // /health binds before preflight and reports "starting" until ready; the
-    // Desktop must not spawn a second daemon over it (the CLI rejects that as
-    // "already running").
-    expect(daemonStatusAlive("starting")).toBe(true);
-  });
-
-  it("treats stopped / unknown / missing as not alive", () => {
-    expect(daemonStatusAlive("stopped")).toBe(false);
-    expect(daemonStatusAlive("bogus")).toBe(false);
-    expect(daemonStatusAlive("")).toBe(false);
-    expect(daemonStatusAlive(undefined)).toBe(false);
-  });
-});

apps/desktop/src/shared/daemon-types.ts

@@ -4,11 +4,7 @@ export type DaemonState =
   | "starting"
   | "stopping"
   | "installing_cli"
-  | "cli_not_found"
-  // The daemon can't start because the server rejected its credentials (the
-  // cached PAT expired / was revoked, or the session token is dead). Without
-  // this, an auth failure silently sticks at "starting" forever — see #3512.
-  | "auth_expired";
+  | "cli_not_found";
 
 export interface DaemonStatus {
   state: DaemonState;
@@ -22,16 +18,6 @@ export interface DaemonStatus {
   profile?: string;
   /** Backend URL the daemon connects to. */
   serverUrl?: string;
-  /**
-   * True when a daemon is running but in an environment the app can't control
-   * — its reported OS differs from the desktop host's (e.g. a Linux daemon
-   * inside WSL2 behind a Windows desktop, reachable only via localhost
-   * forwarding). The app's start/stop CLI acts on the host process namespace,
-   * so auto-start/auto-stop can't reach it; the UI disables those toggles
-   * instead of silently no-op'ing. Only ever set on a running daemon, so it
-   * never disables the toggles for a normally-managed native daemon. See #3916.
-   */
-  externallyManaged?: boolean;
 }
 
 export interface DaemonPrefs {
@@ -46,7 +32,6 @@ export const DAEMON_STATE_COLORS: Record<DaemonState, string> = {
   stopping: "bg-amber-500 animate-pulse",
   installing_cli: "bg-sky-500 animate-pulse",
   cli_not_found: "bg-red-500",
-  auth_expired: "bg-red-500",
 };
 
 export const DAEMON_STATE_LABELS: Record<DaemonState, string> = {
@@ -56,7 +41,6 @@ export const DAEMON_STATE_LABELS: Record<DaemonState, string> = {
   stopping: "Stopping…",
   installing_cli: "Setting up…",
   cli_not_found: "Setup Failed",
-  auth_expired: "Sign-in required",
 };
 
 export function formatUptime(uptime?: string): string {
@@ -68,19 +52,6 @@ export function formatUptime(uptime?: string): string {
   return `${h}${m}`.trim() || uptime;
 }
 
-/**
- * Whether a raw daemon `/health` `status` value means a live daemon is on the
- * port — either fully "running" (ready) or still "starting" (port bound,
- * preflight in progress). Mirrors the Go `daemonAlive()` in
- * server/cmd/multica/cmd_daemon.go so the Desktop lifecycle agrees with the
- * CLI: a "starting" daemon is already there and must not be spawned over (the
- * CLI rejects that as "already running"). This is liveness, not readiness —
- * version-restart decisions still gate on the stricter "running".
- */
-export function daemonStatusAlive(status: string | undefined): boolean {
-  return status === "running" || status === "starting";
-}
-
 /**
  * User-facing description for the local daemon's current state. Replaces the
  * raw state label ("Running" / "Stopped") with a sentence that answers
@@ -110,7 +81,5 @@ export function daemonStateDescription(state: DaemonState, runtimeCount: number)
       return "Setting up the runtime for the first time. Only happens once.";
     case "cli_not_found":
       return "Setup failed · couldn't download the runtime. Check your network.";
-    case "auth_expired":
-      return "Sign-in expired · sign in again to bring this device back online.";
   }
 }

apps/desktop/src/shared/freeze-breadcrumb.ts

@@ -1,16 +0,0 @@
-/**
- * A freeze/crash breadcrumb persisted by the main process and flushed to
- * telemetry by the next renderer boot. Shared across main, preload, and
- * renderer because all three touch it. See main/freeze-breadcrumb.ts for the
- * read/write logic and the rationale.
- */
-export interface FreezeBreadcrumb {
-  /** "unresponsive" (hang) or "render-process-gone" (crash). */
-  kind: string;
-  /** Diagnostic context captured at failure time (route, window url, …). */
-  context: Record<string, unknown>;
-  /** Epoch ms when the failure was recorded. */
-  ts: number;
-  /** App version at failure time. */
-  version: string;
-}

apps/desktop/src/shared/renderer-route-context.ts

@@ -1,51 +0,0 @@
-export const RENDERER_ROUTE_CONTEXT_CHANNEL = "renderer:route-context";
-
-export type RendererRouteSurface = "login" | "overlay" | "tab";
-
-export type RendererRouteContextInput = {
-  surface: RendererRouteSurface;
-  path: string;
-  workspaceSlug?: string;
-  tabId?: string;
-};
-
-export type RendererRouteContext = RendererRouteContextInput & {
-  reportedAt: string;
-};
-
-const MAX_ROUTE_CONTEXT_STRING_LENGTH = 512;
-
-export function sanitizeRendererRouteContext(
-  value: unknown,
-  reportedAt = new Date(),
-): RendererRouteContext | null {
-  if (!value || typeof value !== "object") return null;
-
-  const input = value as Record<string, unknown>;
-  if (!isRendererRouteSurface(input.surface)) return null;
-
-  const path = sanitizeString(input.path);
-  if (!path) return null;
-
-  const workspaceSlug = sanitizeString(input.workspaceSlug);
-  const tabId = sanitizeString(input.tabId);
-
-  return {
-    surface: input.surface,
-    path,
-    ...(workspaceSlug ? { workspaceSlug } : {}),
-    ...(tabId ? { tabId } : {}),
-    reportedAt: reportedAt.toISOString(),
-  };
-}
-
-function isRendererRouteSurface(value: unknown): value is RendererRouteSurface {
-  return value === "login" || value === "overlay" || value === "tab";
-}
-
-function sanitizeString(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  if (!trimmed) return undefined;
-  return trimmed.slice(0, MAX_ROUTE_CONTEXT_STRING_LENGTH);
-}

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

@@ -37,7 +37,7 @@ SMTP 経路は、ほとんどのオンプレミスメールサーバー（特に
 |---|---|---|---|
 | 匿名内部 relay | `25` | なし — IP / サブネットで送信を信頼 | 伝送経路上はなし（内部セグメント専用） |
 | 認証付き送信（submission） | `587` | `SMTP_USERNAME` + `SMTP_PASSWORD` | STARTTLS、自動アップグレード |
-| 暗黙的 TLS（SMTPS） | `465` | 任意（`SMTP_USERNAME` + `SMTP_PASSWORD`） | 接続時に TLS ハンドシェイク — ポート `465` で自動的に有効化、非標準ポートでは `SMTP_TLS=implicit` で強制 |
+| 暗黙的 TLS（SMTPS） | `465` | — | **まだサポートされていません** — ポート 25 または 587 を使用してください |
 
 **ポート 25 の匿名 Exchange relay** — 認証情報なしで信頼されたサブネットからのメールを受け入れる、典型的な「internal SMTP relay」/ Exchange 匿名 receive connector:
 
@@ -61,27 +61,7 @@ SMTP_TLS_INSECURE=false        # set true only for self-signed / private CA
 RESEND_FROM_EMAIL=noreply@yourdomain.com
 ```
 
-**ポート 465 の暗黙的 TLS（SMTPS）** — SMTPS のみを提供し STARTTLS を通知しないプロバイダー（例: Aliyun / Tencent のエンタープライズメール）向け。ポート `465` は暗黙的 TLS を自動的に有効化します。`SMTP_TLS=implicit`（別名: `smtps`、`ssl`）は非標準の SMTPS ポートでこれを強制します:
-
-```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
-```
-
-**厳格な公開 relay（例: Google Workspace `smtp-relay.gmail.com`）** はさらに有効な EHLO 名を必要とします。これらの relay は公開 IP からのデフォルトの `localhost` 挨拶を拒否し、relay が接続を切断します — これは挨拶の時点ではなく、後続のコマンドで不明瞭な `EOF`（`smtp auth: EOF`）として表面化します。`SMTP_EHLO_NAME` を relay が期待する FQDN に設定してください。デフォルトはマシンのホスト名で、コンテナ内では通常は有効な FQDN ではありません。
-
-```bash
-SMTP_HOST=smtp-relay.gmail.com
-SMTP_PORT=587
-SMTP_EHLO_NAME=mail.yourdomain.com   # FQDN the relay accepts; defaults to the (non-FQDN) container hostname
-RESEND_FROM_EMAIL=noreply@yourdomain.com
-```
-
-起動時に、サーバーは選択したプロバイダーを、ネゴシエートされた 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`）を確認してください。
+起動時に、サーバーは選択したプロバイダーを出力します。例えば `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 にのみ書き出されます**。ローカル開発には便利ですが（ログからコードをコピーできます）、プロダクションではブラックホールになります。
 

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

@@ -37,7 +37,7 @@ SMTP 경로는 대부분의 온프레미스 메일 서버(특히 Microsoft Excha
 |---|---|---|---|
 | 익명 내부 relay | `25` | 없음 — IP / 서브넷으로 제출을 신뢰 | 전송 경로상 없음(내부 세그먼트 전용) |
 | 인증된 제출(submission) | `587` | `SMTP_USERNAME` + `SMTP_PASSWORD` | STARTTLS, 자동 업그레이드 |
-| 암묵적 TLS (SMTPS) | `465` | 선택 사항(`SMTP_USERNAME` + `SMTP_PASSWORD`) | 연결 시 TLS 핸드셰이크 — 포트 `465`에서 자동 활성화, 비표준 포트에서는 `SMTP_TLS=implicit`로 강제 |
+| 암묵적 TLS (SMTPS) | `465` | — | **아직 지원하지 않음** — 포트 25 또는 587을 사용하세요 |
 
 **포트 25의 익명 Exchange relay** — 자격 증명 없이 신뢰된 서브넷에서 오는 메일을 받아들이는 일반적인 "internal SMTP relay" / Exchange 익명 receive connector:
 
@@ -61,27 +61,7 @@ SMTP_TLS_INSECURE=false        # set true only for self-signed / private CA
 RESEND_FROM_EMAIL=noreply@yourdomain.com
 ```
 
-**포트 465의 암묵적 TLS(SMTPS)** — SMTPS만 제공하고 STARTTLS를 알리지 않는 제공자(예: Aliyun / Tencent 엔터프라이즈 메일)용. 포트 `465`는 암묵적 TLS를 자동으로 활성화하며, `SMTP_TLS=implicit`(별칭: `smtps`, `ssl`)는 비표준 SMTPS 포트에서 이를 강제합니다:
-
-```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
-```
-
-**엄격한 공개 relay(예: Google Workspace `smtp-relay.gmail.com`)** 는 추가로 유효한 EHLO 이름을 요구합니다. 이들은 공개 IP에서 보내는 기본 `localhost` greeting을 거부하며, relay가 연결을 끊습니다 — 이는 greeting 단계가 아니라 이후 명령에서 불투명한 `EOF`(`smtp auth: EOF`)로 나타납니다. relay가 기대하는 FQDN으로 `SMTP_EHLO_NAME`을 설정하세요. 기본값은 머신 호스트명이며, 컨테이너 안에서는 보통 유효한 FQDN이 아닙니다:
-
-```bash
-SMTP_HOST=smtp-relay.gmail.com
-SMTP_PORT=587
-SMTP_EHLO_NAME=mail.yourdomain.com   # FQDN the relay accepts; defaults to the (non-FQDN) container hostname
-RESEND_FROM_EMAIL=noreply@yourdomain.com
-```
-
-시작 시 서버는 협상된 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`)을 확인하세요.
+시작 시 서버는 선택한 제공자를 출력합니다. 예를 들어 `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에만 기록됩니다**. 로컬 개발에는 편리하지만(로그에서 코드를 복사하면 됩니다), 프로덕션에서는 블랙홀이 됩니다.
 

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

@@ -72,15 +72,6 @@ SMTP_TLS=implicit              # optional on 465; required on a non-standard SMT
 RESEND_FROM_EMAIL=noreply@yourdomain.com
 ```
 
-**Strict public relays (e.g. Google Workspace `smtp-relay.gmail.com`)** additionally require a valid EHLO name. They reject the default `localhost` greeting from a public IP, and the relay drops the connection — which surfaces as an opaque `EOF` on a later command (`smtp auth: EOF`) rather than at the greeting. Set `SMTP_EHLO_NAME` to the FQDN the relay expects; it defaults to the machine hostname, which inside a container is usually not a valid FQDN:
-
-```bash
-SMTP_HOST=smtp-relay.gmail.com
-SMTP_PORT=587
-SMTP_EHLO_NAME=mail.yourdomain.com   # FQDN the relay accepts; defaults to the (non-FQDN) container hostname
-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

@@ -72,15 +72,6 @@ SMTP_TLS=implicit              # 465 上可省略；在非标准 SMTPS 端口上
 RESEND_FROM_EMAIL=noreply@yourdomain.com
 ```
 
-**严格公网 relay（例如 Google Workspace `smtp-relay.gmail.com`）**还要求一个合法的 EHLO 名称。它们会拒绝来自公网 IP 的默认 `localhost` 问候，relay 随即断开连接——这不会在问候阶段报错，而是在后续某条命令上表现为一个不知所云的 `EOF`（`smtp auth: EOF`）。把 `SMTP_EHLO_NAME` 设成 relay 期望的 FQDN；它默认取机器主机名，而在容器内这通常不是合法的 FQDN：
-
-```bash
-SMTP_HOST=smtp-relay.gmail.com
-SMTP_PORT=587
-SMTP_EHLO_NAME=mail.yourdomain.com   # relay 接受的 FQDN；默认取（非 FQDN 的）容器主机名
-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/cli.ja.mdx

@@ -54,23 +54,14 @@ CI やヘッドレス環境では、ブラウザフローをスキップでき
 | `multica issue get <id>` | 単一のイシューを表示（イシューキーまたは UUID を受け取る） |
 | `multica issue create --title "..."` | 新しいイシューを作成 |
 | `multica issue update <id> ...` | イシューを更新（ステータス、優先度、担当者など） |
-| `multica issue assign <id> --to <name>` | メンバー、エージェント、またはスクワッドに割り当て（エージェントへの割り当ては実行をトリガー） |
-| `multica issue status <id> <status>` | ステータス変更のショートカット |
+| `multica issue assign <id> --agent <slug>` | エージェントに割り当て（即座にタスクをトリガー） |
+| `multica issue status <id> --set <status>` | ステータス変更のショートカット |
 | `multica issue search <query>` | キーワード検索 |
-| `multica issue children <id>` | サブイシューを stage ごとに一覧 |
-| `multica issue pull-requests <id>` | 紐付いた pull request と状態を一覧 |
 | `multica issue runs <id>` | イシュー上のエージェント実行を表示 |
-| `multica issue run-messages <task-id>` | 1 回の実行メッセージを表示 |
-| `multica issue usage <id>` | イシュー単位の集計 token 使用量を表示 |
 | `multica issue rerun <id>` | イシューの現在のエージェント担当者向けに新しいタスクを再キューイング |
-| `multica issue cancel-task <task-id>` | キュー中または実行中のタスクをキャンセル |
 | `multica issue comment <id> ...` | ネスト: コメントの表示 / 投稿 |
-| `multica issue comment resolve/unresolve <comment-id>` | コメントスレッドを解決済み / 未解決にする |
 | `multica issue subscriber <id> ...` | ネスト: 購読 / 購読解除 |
-| `multica issue metadata <id> ...` | ネスト: イシューメタデータの読み書き |
-| `multica issue label <id> ...` | ネスト: イシューのラベルを管理 |
 | `multica project list/get/create/update/delete/status` | プロジェクトの CRUD |
-| `multica label list/create/update/delete` | ワークスペースラベルの CRUD |
 
 ## エージェントとスキル
 
@@ -83,26 +74,11 @@ CI やヘッドレス環境では、ブラウザフローをスキップでき
 | `multica agent archive <slug>` | アーカイブ |
 | `multica agent restore <slug>` | アーカイブ済みのエージェントを復元 |
 | `multica agent tasks <slug>` | エージェントのタスク履歴を表示 |
-| `multica agent avatar <slug>` | エージェントのアバターをアップロード |
-| `multica agent env <slug> ...` | エージェントの custom environment variables を読み取り / 置換 |
 | `multica agent skills ...` | ネスト: スキルのアタッチ / デタッチ |
 | `multica skill list/get/create/update/delete` | スキルの CRUD |
 | `multica skill import ...` | GitHub、ClawHub、またはローカルマシンからスキルをインポート |
 | `multica skill files ...` | ネスト: スキルのファイルを管理 |
 
-### スキルインポートの競合
-
-`multica skill import --url <url>` の既定値は `--on-conflict fail` です。同じ名前のスキルがすでに存在する場合、コマンドは構造化された `conflict` 結果で終了し、ワークスペースは変更されません。
-
-既存スキルの作成者で、スキル ID とエージェントの紐付けを維持したまま内容を置き換える場合は `--on-conflict overwrite` を使います。既存スキルを残してコピーを取り込む場合は `--on-conflict rename` を使うと、`-2` のような接尾辞が自動で付きます。同名の項目を単に飛ばす場合は `--on-conflict skip` を使います。
-
-```bash
-multica skill import --url https://skills.sh/acme/repo/review-helper
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict overwrite
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict rename
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict skip
-```
-
 ## スクワッド
 
 | コマンド | 用途 |
@@ -128,10 +104,6 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica autopilot delete <id>` | 削除 |
 | `multica autopilot runs <id>` | 実行履歴を表示 |
 | `multica autopilot trigger <id>` | 手動で実行をトリガー |
-| `multica autopilot trigger-add/update/delete <id>` | schedule または webhook trigger を管理 |
-| `multica autopilot trigger-rotate-url <id> <trigger-id>` | webhook trigger URL をローテート |
-
-`multica autopilot create/update` は、`create_issue` モードの autopilot が作成するイシューの既定購読者を設定する `--subscriber` も受け取ります。`update` では `--clear-subscribers` で削除できます。
 
 ## デーモンとランタイム
 
@@ -145,9 +117,7 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica runtime list` | 現在のワークスペースのランタイムを一覧 |
 | `multica runtime usage` | リソース使用量を表示 |
 | `multica runtime activity` | 最近のアクティビティログ |
-| `multica runtime update <id> ...` | ランタイム上で CLI 更新を開始 |
-| `multica runtime delete <id> [--cascade]` | ランタイムを削除し、必要なら紐付くエージェントもアーカイブ |
-| `multica runtime profile ...` | カスタム runtime profile とローカルパス上書きを管理 |
+| `multica runtime update <id> ...` | ランタイムの構成を更新 |
 
 ## その他
 

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

@@ -54,23 +54,14 @@ CI나 headless 환경에서는 브라우저 플로우를 건너뛰세요. 웹
 | `multica issue get <id>` | 단일 이슈 표시(이슈 키 또는 UUID를 받음) |
 | `multica issue create --title "..."` | 새 이슈 생성 |
 | `multica issue update <id> ...` | 이슈 업데이트(상태, 우선순위, 담당자 등) |
-| `multica issue assign <id> --to <name>` | 멤버, 에이전트, 또는 스쿼드에 할당(에이전트에 할당하면 실행이 트리거됨) |
-| `multica issue status <id> <status>` | 상태 변경 단축 명령 |
+| `multica issue assign <id> --agent <slug>` | 에이전트에게 할당(즉시 작업을 트리거) |
+| `multica issue status <id> --set <status>` | 상태 변경 단축 명령 |
 | `multica issue search <query>` | 키워드 검색 |
-| `multica issue children <id>` | 하위 이슈를 stage별로 나열 |
-| `multica issue pull-requests <id>` | 연결된 pull request와 상태 나열 |
 | `multica issue runs <id>` | 이슈의 에이전트 실행 표시 |
-| `multica issue run-messages <task-id>` | 한 실행의 메시지 표시 |
-| `multica issue usage <id>` | 이슈의 집계 token 사용량 표시 |
 | `multica issue rerun <id>` | 이슈의 현재 에이전트 담당자에게 새 작업을 다시 큐에 넣기 |
-| `multica issue cancel-task <task-id>` | 대기 중이거나 실행 중인 작업 취소 |
 | `multica issue comment <id> ...` | 중첩: 댓글 보기 / 작성 |
-| `multica issue comment resolve/unresolve <comment-id>` | 댓글 스레드를 해결 / 미해결로 표시 |
 | `multica issue subscriber <id> ...` | 중첩: 구독 / 구독 취소 |
-| `multica issue metadata <id> ...` | 중첩: 이슈 metadata 읽기 / 쓰기 |
-| `multica issue label <id> ...` | 중첩: 이슈의 label 관리 |
 | `multica project list/get/create/update/delete/status` | 프로젝트 CRUD |
-| `multica label list/create/update/delete` | 워크스페이스 label CRUD |
 
 ## 에이전트와 스킬
 
@@ -83,26 +74,11 @@ CI나 headless 환경에서는 브라우저 플로우를 건너뛰세요. 웹
 | `multica agent archive <slug>` | 보관 |
 | `multica agent restore <slug>` | 보관된 에이전트 복원 |
 | `multica agent tasks <slug>` | 에이전트의 작업 기록 표시 |
-| `multica agent avatar <slug>` | 에이전트 아바타 업로드 |
-| `multica agent env <slug> ...` | 에이전트 custom environment variables 읽기 / 교체 |
 | `multica agent skills ...` | 중첩: 스킬 연결 / 분리 |
 | `multica skill list/get/create/update/delete` | 스킬 CRUD |
 | `multica skill import ...` | GitHub, ClawHub, 또는 로컬 기기에서 스킬 가져오기 |
 | `multica skill files ...` | 중첩: 스킬의 파일 관리 |
 
-### 스킬 가져오기 충돌
-
-`multica skill import --url <url>`의 기본값은 `--on-conflict fail`입니다. 같은 이름의 스킬이 이미 있으면 명령은 구조화된 `conflict` 결과로 종료되며 워크스페이스를 변경하지 않습니다.
-
-기존 스킬을 만든 사용자이고, 스킬 ID와 에이전트 연결은 유지한 채 내용을 바꾸려면 `--on-conflict overwrite`를 사용하세요. 기존 스킬을 그대로 두고 복사본을 가져오려면 `--on-conflict rename`을 사용하면 `-2` 같은 접미사가 자동으로 붙습니다. 같은 이름의 항목을 그냥 건너뛰려면 `--on-conflict skip`을 사용하세요.
-
-```bash
-multica skill import --url https://skills.sh/acme/repo/review-helper
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict overwrite
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict rename
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict skip
-```
-
 ## 스쿼드
 
 | 명령어 | 용도 |
@@ -128,10 +104,6 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica autopilot delete <id>` | 삭제 |
 | `multica autopilot runs <id>` | 실행 기록 표시 |
 | `multica autopilot trigger <id>` | 수동으로 실행 트리거 |
-| `multica autopilot trigger-add/update/delete <id>` | schedule 또는 webhook trigger 관리 |
-| `multica autopilot trigger-rotate-url <id> <trigger-id>` | webhook trigger URL 회전 |
-
-`multica autopilot create/update`는 `create_issue` 모드 autopilot이 만드는 이슈의 기본 구독자를 설정하는 `--subscriber`도 받습니다. `update`에서는 `--clear-subscribers`로 제거할 수 있습니다.
 
 ## 데몬과 런타임
 
@@ -145,9 +117,7 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica runtime list` | 현재 워크스페이스의 런타임 나열 |
 | `multica runtime usage` | 리소스 사용량 표시 |
 | `multica runtime activity` | 최근 활동 로그 |
-| `multica runtime update <id> ...` | 런타임에서 CLI 업데이트 시작 |
-| `multica runtime delete <id> [--cascade]` | 런타임 삭제, 필요하면 연결된 에이전트도 보관 |
-| `multica runtime profile ...` | 사용자 지정 runtime profile과 로컬 경로 override 관리 |
+| `multica runtime update <id> ...` | 런타임의 구성 업데이트 |
 
 ## 기타
 

apps/docs/content/docs/cli.mdx

@@ -54,23 +54,14 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 | `multica issue get <id>` | Show a single issue (accepts an issue key or a UUID) |
 | `multica issue create --title "..."` | Create a new issue |
 | `multica issue update <id> ...` | Update an issue (status, priority, assignee, etc.) |
-| `multica issue assign <id> --to <name>` | Assign to a member, agent, or squad (assigning to an agent triggers a run) |
-| `multica issue status <id> <status>` | Shortcut to change status |
+| `multica issue assign <id> --agent <slug>` | Assign to an agent (triggers a task immediately) |
+| `multica issue status <id> --set <status>` | Shortcut to change status |
 | `multica issue search <query>` | Keyword search |
-| `multica issue children <id>` | List sub-issues grouped by stage |
-| `multica issue pull-requests <id>` | List linked pull requests and their status |
 | `multica issue runs <id>` | Show agent runs on an issue |
-| `multica issue run-messages <task-id>` | Show messages for one execution |
-| `multica issue usage <id>` | Show aggregated token usage for an issue |
 | `multica issue rerun <id>` | Re-enqueue a fresh task for the issue's current agent assignee |
-| `multica issue cancel-task <task-id>` | Cancel a queued or running task |
 | `multica issue comment <id> ...` | Nested: view / post comments |
-| `multica issue comment resolve/unresolve <comment-id>` | Mark a comment thread resolved or unresolved |
 | `multica issue subscriber <id> ...` | Nested: subscribe / unsubscribe |
-| `multica issue metadata <id> ...` | Nested: read / write issue metadata |
-| `multica issue label <id> ...` | Nested: manage labels on an issue |
 | `multica project list/get/create/update/delete/status` | Project CRUD |
-| `multica label list/create/update/delete` | Workspace label CRUD |
 
 ## Agents and skills
 
@@ -83,32 +74,11 @@ For the difference between token types, see [Authentication and tokens](/auth-to
 | `multica agent archive <slug>` | Archive |
 | `multica agent restore <slug>` | Restore an archived agent |
 | `multica agent tasks <slug>` | Show an agent's task history |
-| `multica agent avatar <slug>` | Upload an agent avatar |
-| `multica agent env <slug> ...` | Read or replace an agent's custom environment variables |
 | `multica agent skills ...` | Nested: attach / detach skills |
 | `multica skill list/get/create/update/delete` | Skill CRUD |
 | `multica skill import ...` | Import a skill from GitHub, ClawHub, or the local machine |
 | `multica skill files ...` | Nested: manage a skill's files |
 
-### Skill import conflicts
-
-`multica skill import --url <url>` defaults to `--on-conflict fail`. If a skill
-with the same name already exists, the command exits with a structured
-`conflict` result and does not change the workspace.
-
-Use `--on-conflict overwrite` when you created the existing skill and want to
-replace its content while preserving its ID and agent bindings. Use
-`--on-conflict rename` to import a copy with an automatic suffix such as `-2`.
-Use `--on-conflict skip` to leave the existing skill untouched and report
-`skipped`.
-
-```bash
-multica skill import --url https://skills.sh/acme/repo/review-helper
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict overwrite
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict rename
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict skip
-```
-
 ## Squads
 
 | Command | Purpose |
@@ -134,12 +104,6 @@ See [Squads](/squads) for the full model.
 | `multica autopilot delete <id>` | Delete |
 | `multica autopilot runs <id>` | Show run history |
 | `multica autopilot trigger <id>` | Trigger a run manually |
-| `multica autopilot trigger-add/update/delete <id>` | Manage schedule or webhook triggers |
-| `multica autopilot trigger-rotate-url <id> <trigger-id>` | Rotate a webhook trigger URL |
-
-`multica autopilot create/update` also accepts `--subscriber` to set default
-subscribers for issues created by a `create_issue` autopilot; update accepts
-`--clear-subscribers` to remove them.
 
 ## Daemon and runtimes
 
@@ -153,9 +117,7 @@ subscribers for issues created by a `create_issue` autopilot; update accepts
 | `multica runtime list` | List runtimes in the current workspace |
 | `multica runtime usage` | Show resource usage |
 | `multica runtime activity` | Recent activity log |
-| `multica runtime update <id> ...` | Initiate a CLI update on a runtime |
-| `multica runtime delete <id> [--cascade]` | Delete a runtime, optionally archiving bound agents |
-| `multica runtime profile ...` | Manage custom runtime profiles and local path overrides |
+| `multica runtime update <id> ...` | Update a runtime's configuration |
 
 ## Miscellaneous
 

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

@@ -54,23 +54,14 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 | `multica issue get <id>` | 查看单条 issue（接受 issue key 或 UUID） |
 | `multica issue create --title "..."` | 创建新 issue |
 | `multica issue update <id> ...` | 修改 issue（状态、优先级、分配人等） |
-| `multica issue assign <id> --to <name>` | 分配给成员、智能体或小队（分配给智能体会触发一次运行） |
-| `multica issue status <id> <status>` | 快捷改状态 |
+| `multica issue assign <id> --agent <slug>` | 分配给智能体（立即触发任务） |
+| `multica issue status <id> --set <status>` | 快捷改状态 |
 | `multica issue search <query>` | 关键字搜索 |
-| `multica issue children <id>` | 按 stage 分组查看子 issue |
-| `multica issue pull-requests <id>` | 查看关联 PR 及其状态 |
 | `multica issue runs <id>` | 查看 issue 上智能体跑过的任务 |
-| `multica issue run-messages <task-id>` | 查看某次执行的消息 |
-| `multica issue usage <id>` | 查看单个 issue 聚合 token 用量 |
 | `multica issue rerun <id>` | 给该 issue 当前的智能体分配人重新创建一条任务 |
-| `multica issue cancel-task <task-id>` | 取消排队中或运行中的任务 |
 | `multica issue comment <id> ...` | 嵌套：看 / 发评论 |
-| `multica issue comment resolve/unresolve <comment-id>` | 标记评论线程已解决 / 未解决 |
 | `multica issue subscriber <id> ...` | 嵌套：订阅 / 取消订阅 |
-| `multica issue metadata <id> ...` | 嵌套：读写 issue metadata |
-| `multica issue label <id> ...` | 嵌套：管理 issue 上的 label |
 | `multica project list/get/create/update/delete/status` | Project CRUD |
-| `multica label list/create/update/delete` | Workspace label CRUD |
 
 ## 智能体和 Skill
 
@@ -83,26 +74,11 @@ Token 类型的详细区分见 [认证与令牌](/auth-tokens)。
 | `multica agent archive <slug>` | 归档 |
 | `multica agent restore <slug>` | 恢复归档的智能体 |
 | `multica agent tasks <slug>` | 查看智能体的任务历史 |
-| `multica agent avatar <slug>` | 上传智能体头像 |
-| `multica agent env <slug> ...` | 读取或替换智能体的 custom environment variables |
 | `multica agent skills ...` | 嵌套：挂载 / 卸载 Skill |
 | `multica skill list/get/create/update/delete` | Skill CRUD |
 | `multica skill import ...` | 从 GitHub / ClawHub / 本机导入 Skill |
 | `multica skill files ...` | 嵌套：管理 Skill 的文件 |
 
-### Skill 导入冲突
-
-`multica skill import --url <url>` 默认等同于 `--on-conflict fail`。如果工作区里已经有同名 Skill，命令会返回结构化 `conflict` 结果并退出，不会修改工作区。
-
-如果你是已有 Skill 的 creator，并且想用新导入内容覆盖它，同时保留原 Skill 的 ID 和 agent 绑定，用 `--on-conflict overwrite`。如果想保留已有 Skill、另存一份，用 `--on-conflict rename`，系统会自动加 `-2` 这类后缀。如果只是批量导入时遇到同名项就跳过，用 `--on-conflict skip`。
-
-```bash
-multica skill import --url https://skills.sh/acme/repo/review-helper
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict overwrite
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict rename
-multica skill import --url https://skills.sh/acme/repo/review-helper --on-conflict skip
-```
-
 ## 小队
 
 | 命令 | 用途 |
@@ -128,10 +104,6 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica autopilot delete <id>` | 删除 |
 | `multica autopilot runs <id>` | 查看运行历史 |
 | `multica autopilot trigger <id>` | 手动触发一次 |
-| `multica autopilot trigger-add/update/delete <id>` | 管理 schedule 或 webhook trigger |
-| `multica autopilot trigger-rotate-url <id> <trigger-id>` | 轮换 webhook trigger URL |
-
-`multica autopilot create/update` 还支持 `--subscriber`，为 `create_issue` 模式创建的 issue 设置默认订阅人；`update` 支持 `--clear-subscribers` 清空默认订阅人。
 
 ## 守护进程和运行时
 
@@ -145,9 +117,7 @@ multica skill import --url https://skills.sh/acme/repo/review-helper --on-confli
 | `multica runtime list` | 列出当前工作区的 runtime |
 | `multica runtime usage` | 查看资源使用情况 |
 | `multica runtime activity` | 近期活动记录 |
-| `multica runtime update <id> ...` | 在某个 runtime 上触发 CLI 更新 |
-| `multica runtime delete <id> [--cascade]` | 删除 runtime，可选择同时归档绑定的智能体 |
-| `multica runtime profile ...` | 管理自定义 runtime profile 和本机路径覆盖 |
+| `multica runtime update <id> ...` | 更新 runtime 配置 |
 
 ## 杂项
 

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

@@ -115,7 +115,7 @@ Daemon behavior is configured via flags or environment variables:
 |---------|------|--------------|---------|
 | Poll interval | `--poll-interval` | `MULTICA_DAEMON_POLL_INTERVAL` | `3s` |
 | Heartbeat interval | `--heartbeat-interval` | `MULTICA_DAEMON_HEARTBEAT_INTERVAL` | `15s` |
-| Agent timeout | `--agent-timeout` | `MULTICA_AGENT_TIMEOUT` | `0`（不限制，由看门狗兜底）|
+| Agent timeout | `--agent-timeout` | `MULTICA_AGENT_TIMEOUT` | `2h` |
 | Max concurrent tasks | `--max-concurrent-tasks` | `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` | `20` |
 | Daemon ID | `--daemon-id` | `MULTICA_DAEMON_ID` | hostname |
 | Device name | `--device-name` | `MULTICA_DAEMON_DEVICE_NAME` | hostname |

apps/docs/content/docs/comments.ja.mdx

@@ -39,9 +39,9 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 ## イシューを参照する
 
-別のイシューをリンクするには、コメントの mention ピッカーからそのイシューを選択してください。Multica はイシューリンクを明示的な `[MUL-123](mention://issue/<uuid>)` mention リンクとして保存します。イシューリンクは単なる相互参照にすぎません。人に通知を送ることはなく、エージェントをトリガーすることもありません。
+別のイシューをリンクするには、`MUL-123` のようにそのイシューキーを入力してください。Multica はコメント内で実在するイシューキーを解決し、内部的に `mention://issue/<uuid>` リンクとして保存します。イシューリンクは単なる相互参照にすぎません。人に通知を送ることはなく、エージェントをトリガーすることもありません。
 
-`MUL-123` のような裸のイシューキーを入力しても、通常のテキストのまま残ります。そのため、`feature/MUL-123` のようなコメント内のブランチ名やパスも書き換えられません。
+通常は `[MUL-123](mention://issue/<uuid>)` を手で書く必要はありません。その形式は、Multica がキーを解決した後に使う標準的な内部表現です。
 
 <Callout type="info">
 Markdown の強調は CommonMark のルールに従います。太字テキストが句読点や閉じ引用符で終わり、その直後に韓国語の助詞が続く場合、閉じの `**` が認識されないことがあります。

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

@@ -39,9 +39,9 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 ## 이슈 참조하기
 
-다른 이슈를 링크하려면 댓글 mention 선택기에서 해당 이슈를 선택하세요. Multica는 이슈 링크를 명시적인 `[MUL-123](mention://issue/<uuid>)` mention 링크로 저장합니다. 이슈 링크는 단순한 상호 참조일 뿐입니다. 사람에게 알림을 보내지 않으며 에이전트를 트리거하지도 않습니다.
+다른 이슈를 링크하려면 `MUL-123`처럼 이슈 키를 입력하세요. Multica는 댓글에서 실제 존재하는 이슈 키를 해석하여 내부적으로 `mention://issue/<uuid>` 링크로 저장합니다. 이슈 링크는 단순한 상호 참조일 뿐입니다. 사람에게 알림을 보내지 않으며 에이전트를 트리거하지도 않습니다.
 
-`MUL-123` 같은 bare 이슈 키를 입력하면 일반 텍스트로 유지됩니다. 따라서 `feature/MUL-123` 같은 댓글 안의 브랜치 이름과 경로도 다시 작성되지 않습니다.
+보통은 `[MUL-123](mention://issue/<uuid>)`을 직접 손으로 작성할 필요가 없습니다. 그 형식은 Multica가 키를 해석한 뒤에 사용하는 표준 내부 표현입니다.
 
 <Callout type="info">
 Markdown 강조는 CommonMark 규칙을 따릅니다. 굵은 텍스트가 문장 부호나 닫는 따옴표로 끝나고 그 뒤에 한국어 조사가 바로 이어지면, 닫는 `**`가 인식되지 않을 수 있습니다.

apps/docs/content/docs/comments.mdx

@@ -39,9 +39,9 @@ Mentioning the same person multiple times in one comment still produces **only o
 
 ## Referencing issues
 
-To link another issue, choose it from the comment mention picker. Multica stores issue links as an explicit `[MUL-123](mention://issue/<uuid>)` mention link. Issue links are cross-references only: they do not notify people and they do not trigger agents.
+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.
 
-Typing a bare issue key, such as `MUL-123`, keeps it as plain text. This also keeps branch names and paths, such as `feature/MUL-123`, from being rewritten inside comments.
+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.

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

@@ -39,9 +39,9 @@ import { Callout } from "fumadocs-ui/components/callout";
 
 ## 引用 issue
 
-要链接另一个 issue，请在评论的 mention 选择器里选择它。Multica 会把 issue 链接存成显式的 `[MUL-123](mention://issue/<uuid>)` mention 链接。Issue 链接只是交叉引用：不会通知成员，也不会触发智能体。
+要链接另一个 issue，直接输入它的 issue key，例如 `MUL-123`。Multica 会在评论中解析真实存在的 issue key，并把它存成内部的 `mention://issue/<uuid>` 链接。Issue 链接只是交叉引用：不会通知成员，也不会触发智能体。
 
-直接输入裸 issue key，例如 `MUL-123`，会保持为普通文本。这样评论里的分支名和路径，例如 `feature/MUL-123`，也不会被改写。
+通常不需要手写 `[MUL-123](mention://issue/<uuid>)`。这是 Multica 解析 key 之后使用的内部规范格式。
 
 <Callout type="info">
 Markdown 加粗遵循 CommonMark 规则。当加粗文本以标点或闭引号结尾，并且后面紧跟韩语助词时，结尾的 `**` 可能不会被识别。

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

@@ -58,29 +58,6 @@ graph TD
 - **同じデーモン、ワークスペース、ツールは、ちょうど 1 つのランタイムを作ります** — デーモンを再起動しても重複レコードは生まれません
 - Multica UI の**ランタイム**ページがこれらの行を一覧表示します
 
-## カスタムランタイムプロファイル
-
-組み込み provider 検出は一般的なツールを対象にしていますが、Multica が対応するプロトコルファミリーで動作し、ワークスペース固有の起動コマンドが必要な AI CLI には **custom runtime profile** を定義できます。Runtimes UI か CLI で管理します。
-
-```bash
-multica runtime profile list
-multica runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
-multica runtime profile update <profile-id> --command-name agent
-multica runtime profile delete <profile-id>
-```
-
-入力するコマンドは shell 文字列ではなく argv 形式です。Multica は実行ファイル名と固定引数を保存し、デーモンは `exec.Command(command_name, fixed_args...)` で直接起動します。通常の引数、引用符、バックスラッシュエスケープは使えますが、パイプ、リダイレクト、`&&`、`;`、バッククォート、`$VAR` / `$(...)` 展開は使えません。shell の動作が必要な場合は wrapper script を使ってください。
-現在、コマンドと引数の解析は Runtimes UI が担当します。CLI の profile コマンドは profile 行とローカルのパス上書きを管理します。
-
-デスクトップアプリから起動したデーモンが、ターミナルでは動くコマンドを見つけられない場合は、そのマシンで絶対パスを固定できます。
-
-```bash
-multica runtime profile set-path <profile-id> --path /abs/path/to/agent
-multica runtime profile unset-path <profile-id>
-```
-
-profile のコマンドや引数の変更は、デーモンが再登録された後に新しく取得するタスクへ適用されます。実行中のタスクは開始時の引数を使い続けます。混在デプロイでは、先に server をアップグレードしてから daemon を順次更新することを推奨します。`fixed_args` の入力は server 側の Runtimes UI が担い、`failed_profiles` 登録レポートも server が表示します。古いコンポーネントは未知のフィールドを明示的に失敗させず無視することがあるため、server を先に更新すると rollout を観測しやすくなります。
-
 <Callout type="info">
 **クラウドランタイムが近日提供されます。** 現在は順番待ちリストの段階です。提供が始まれば、ローカルのデーモンを実行せずに Multica Cloud 上で直接エージェントタスクを実行できるようになります。[ダウンロードページ](https://multica.ai/download)でメールアドレスを登録すると通知を受け取れます。
 </Callout>

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

@@ -58,29 +58,6 @@ graph TD
 - **같은 데몬, 워크스페이스, 도구는 정확히 하나의 런타임을 만듭니다.** 데몬을 재시작해도 중복 레코드가 생기지 않습니다
 - Multica UI의 **런타임** 페이지가 이 행들을 나열합니다
 
-## 사용자 지정 런타임 프로필
-
-기본 provider 감지는 일반적인 도구를 다룹니다. 팀에서 Multica가 지원하는 프로토콜 패밀리로 동작하지만 워크스페이스별 실행 명령이 필요한 AI CLI를 쓰는 경우에는 **custom runtime profile**을 정의할 수 있습니다. Runtimes UI 또는 CLI에서 관리합니다.
-
-```bash
-multica runtime profile list
-multica runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
-multica runtime profile update <profile-id> --command-name agent
-multica runtime profile delete <profile-id>
-```
-
-명령은 shell 문자열이 아니라 argv 형식입니다. Multica는 실행 파일 이름과 고정 인수를 저장하고, 데몬은 `exec.Command(command_name, fixed_args...)`로 직접 실행합니다. 일반 인수, 따옴표, 백슬래시 이스케이프는 지원하지만 파이프, 리다이렉션, `&&`, `;`, 백틱, `$VAR` / `$(...)` 확장은 지원하지 않습니다. shell 동작이 필요하면 wrapper script를 사용하세요.
-현재 명령과 인수 파싱은 Runtimes UI가 담당합니다. CLI의 profile 명령은 profile 행과 로컬 경로 override를 관리합니다.
-
-데스크톱 앱에서 시작한 데몬이 터미널에서는 동작하는 명령을 찾지 못한다면, 해당 기기에서 절대 경로를 고정할 수 있습니다.
-
-```bash
-multica runtime profile set-path <profile-id> --path /abs/path/to/agent
-multica runtime profile unset-path <profile-id>
-```
-
-profile의 명령이나 인수 변경은 데몬이 다시 등록된 뒤 새로 가져오는 작업부터 적용됩니다. 이미 실행 중인 작업은 시작할 때의 인수를 유지합니다. 혼합 배포에서는 server를 먼저 업그레이드한 뒤 daemon을 순차적으로 업데이트하는 것을 권장합니다. `fixed_args` 입력은 server 쪽 Runtimes UI가 담당하고, `failed_profiles` 등록 보고도 server가 표시합니다. 오래된 구성요소는 알 수 없는 필드를 명확히 실패시키기보다 무시할 수 있으므로 server를 먼저 올리면 rollout을 더 잘 관찰할 수 있습니다.
-
 <Callout type="info">
 **클라우드 런타임이 곧 제공됩니다.** 현재는 대기자 명단 단계입니다. 제공이 시작되면 로컬 데몬을 실행하지 않고도 Multica Cloud에서 직접 에이전트 작업을 실행할 수 있습니다. [다운로드 페이지](https://multica.ai/download)에서 이메일로 등록하면 알림을 받을 수 있습니다.
 </Callout>

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

@@ -58,44 +58,6 @@ Key points:
 - **The same daemon, workspace, and tool produces exactly one runtime** — restarting the daemon never creates duplicate records
 - The **Runtimes** page in the Multica UI lists these rows
 
-## Custom runtime profiles
-
-Built-in provider detection covers the common tools, but teams can also define
-**custom runtime profiles** for AI CLIs that speak one of Multica's supported
-protocol families and need a workspace-specific launch command. Profiles are
-managed from the Runtimes UI or the CLI:
-
-```bash
-multica runtime profile list
-multica runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
-multica runtime profile update <profile-id> --command-name agent
-multica runtime profile delete <profile-id>
-```
-
-The command is argv-oriented, not a shell string. Multica stores an executable
-name plus fixed arguments, then the daemon launches it directly with
-`exec.Command(command_name, fixed_args...)`. Plain arguments, quotes, and
-backslash escaping are supported; pipes, redirects, `&&`, `;`, backticks, and
-`$VAR` / `$(...)` expansion are not. Use a wrapper script when the runtime needs
-shell behavior. Today the Runtimes UI owns command-and-argument parsing; the CLI
-profile commands manage the profile row and local path overrides.
-
-If a desktop-launched daemon cannot find a command that works in your terminal,
-pin the absolute path on that machine:
-
-```bash
-multica runtime profile set-path <profile-id> --path /abs/path/to/agent
-multica runtime profile unset-path <profile-id>
-```
-
-Profile command or argument edits apply to newly claimed tasks after the daemon
-re-registers. Running tasks keep the launch arguments they started with. For
-mixed deployments, upgrade the server before rolling out newer daemons: the
-server-side Runtimes UI stores `fixed_args`, and the server is what surfaces
-`failed_profiles` registration reports. Older components may ignore fields they
-do not understand instead of failing loudly, so treating the server upgrade as
-the first step keeps the rollout observable.
-
 <Callout type="info">
 **Cloud runtimes are coming**, currently in a waitlist phase. Once available, you'll be able to execute agent tasks directly on Multica Cloud without running a local daemon. Sign up with your email on the [download page](https://multica.ai/download) to get notified.
 </Callout>

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

@@ -58,29 +58,6 @@ graph TD
 - **同一个守护进程在同一个工作区同一款工具上只会有一条运行时**——重启守护进程不会产生重复记录
 - Multica 界面的 **Runtimes** 页面列的就是这些行
 
-## 自定义运行时配置
-
-内置 provider 探测覆盖常见工具；如果团队有一款兼容 Multica 已支持协议族、但需要工作区级启动命令的 AI CLI，可以定义 **custom runtime profile**。你可以在 Runtimes UI 里管理，也可以用 CLI：
-
-```bash
-multica runtime profile list
-multica runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
-multica runtime profile update <profile-id> --command-name agent
-multica runtime profile delete <profile-id>
-```
-
-这里填写的是 argv 风格命令，不是 shell 字符串。Multica 存的是可执行文件名和固定参数，守护进程会直接用 `exec.Command(command_name, fixed_args...)` 启动。支持普通参数、引号和反斜杠转义；不支持管道、重定向、`&&`、`;`、反引号、`$VAR` / `$(...)` 展开。需要 shell 行为时，用 wrapper script 包一层。
-目前命令和参数的解析入口在 Runtimes UI；CLI 的 profile 命令负责管理 profile 记录和本机路径覆盖。
-
-如果桌面应用拉起的守护进程找不到你在终端里能运行的命令，可以在这台机器上固定绝对路径：
-
-```bash
-multica runtime profile set-path <profile-id> --path /abs/path/to/agent
-multica runtime profile unset-path <profile-id>
-```
-
-修改 profile 的命令或参数后，已开始的任务仍使用启动时的参数；守护进程重新注册后，新领取的任务才会使用新配置。混合版本部署时，建议先升级 server，再逐步升级 daemon：`fixed_args` 的录入在 server 侧 Runtimes UI，`failed_profiles` 注册报告也由 server 展示。旧组件可能会忽略自己不认识的字段，而不是明确报错；先升 server 能让 rollout 更可观察。
-
 <Callout type="info">
 **云端运行时即将开放**，目前处于等待名单阶段。上线后，你无需在本地运行守护进程，即可在 Multica Cloud 上直接执行智能体任务。在 [下载页面](https://multica.ai/download) 登记邮箱以获取通知。
 </Callout>

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

@@ -49,12 +49,10 @@ Multica は 2 つの配信バックエンドをサポートします — クラ
 | 変数 | デフォルト | 説明 |
 |---|---|---|
 | `SMTP_HOST` | 空 | SMTP relay のホスト名。これを設定すると SMTP モードが有効になり、Resend を上書きします |
-| `SMTP_PORT` | `25` | SMTP ポート。STARTTLS サブミッションには `587` を、SMTPS（暗黙的 TLS、自動有効化）には `465` を使用します |
+| `SMTP_PORT` | `25` | SMTP ポート。STARTTLS サブミッションには `587` を使用してください。**ポート 465（SMTPS / 暗黙的 TLS）はサポートされていません** |
 | `SMTP_USERNAME` | 空 | SMTP ユーザー名。認証なしの relay の場合は空のままにしてください |
 | `SMTP_PASSWORD` | 空 | SMTP パスワード |
-| `SMTP_TLS` | `starttls` | TLS モード。`implicit`（別名 `smtps`、`ssl`）は接続時に即座に TLS ハンドシェイクを行います（SMTPS）。`465` ポートでは自動的に有効になります。未設定 / `starttls` の場合は接続後に STARTTLS でアップグレードします |
 | `SMTP_TLS_INSECURE` | `false` | TLS 証明書の検証をスキップするには `true` に設定（プライベート CA / 自己署名証明書のみ） |
-| `SMTP_EHLO_NAME` | マシンのホスト名 | relay に通知する EHLO/HELO 名。厳格な relay（例: Google Workspace `smtp-relay.gmail.com`）が公開 IP からのデフォルトの挨拶を拒否する場合は、実際の FQDN を設定してください — そうしないと relay が接続を切断し、後続のコマンドで不明瞭な `EOF` として表面化します |
 
 サーバーが STARTTLS を通知すると自動的にアップグレードされます。dial タイムアウトは 10 秒で、SMTP セッション全体には 30 秒のデッドラインがあるため、ブラックホール化した relay が auth ハンドラーをハングさせることはできません。
 
@@ -86,19 +84,15 @@ Multica はユーザーがアップロードした添付ファイル（コメン
 | `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 に切り替わります |
-| `ATTACHMENT_DOWNLOAD_MODE` | `auto` | 添付ファイルのダウンロード方式: `auto`、`cloudfront`、`presign`、`proxy`。`auto` では CloudFront が完全に設定されている場合は優先し、内部/プライベート endpoint host は server proxy、公開 S3 互換 endpoint は対応時に presigned GET を使います |
-| `ATTACHMENT_DOWNLOAD_URL_TTL` | `30m` | CloudFront signed URL と S3 presigned download URL の有効期間。Go duration 形式を受け付けます |
 
 **`S3_BUCKET` を設定しない場合**: サーバーは起動時に `"S3_BUCKET not set, cloud upload disabled"` をログに記録し、すべてのアップロードはローカルディスクにフォールバックします。
 
-**保存されるオブジェクト URL** は次の優先順位で構築されます。
+**公開 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）にフォールバックします。
 
-API の `download_url` は、CloudFront 署名が設定されていない場合 `GET /api/attachments/{id}/download` を使います。この endpoint は安全な場合 CloudFront/S3 presigned URL にリダイレクトし、`http://rustfs:9000` のようなプライベート/内部 endpoint では server がストリーミングします。Docker/VPC 内部のオブジェクトストアでは `ATTACHMENT_DOWNLOAD_MODE=proxy` を明示できます。
-
 ### ローカルディスク（S3 が設定されていない場合）
 
 | 変数 | デフォルト | 説明 |
@@ -198,24 +192,18 @@ S3 の前段に CloudFront を置く場合、3 つの変数が適用されます
 
 ## GitHub 連携
 
-[GitHub PR ↔ イシュー連携](/github-integration)には 2 つの必須変数が必要です。設定で Connect GitHub を有効にし、受信 webhook を受け付けるには両方を設定してください。さらに 2 つの任意変数を設定すると、インストール時点で連携先のアカウント名を取得できます。
+[GitHub PR ↔ イシュー連携](/github-integration)には 2 つの変数が必要です。設定で 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_APP_ID` | 空 | 任意。App 設定ページに表示される数値の App ID。`GITHUB_APP_PRIVATE_KEY` と併せて設定すると、setup コールバックがインストール時点で GitHub から連携先のアカウント名を取得できます |
-| `GITHUB_APP_PRIVATE_KEY` | 空 | 任意。App の RSA 秘密鍵の完全な PEM ブロック（`-----BEGIN/END-----` 行を含み、改行を保ったまま）。GitHub の App 認証 REST 呼び出しに必要な短命 JWT の発行に使われます |
 
-**いずれかの必須変数が設定されていない場合の動作:**
+**どちらかが設定されていない場合の動作:**
 
 - 設定 → GitHub の `Connect GitHub` が**無効**になり、admin に「not configured」というヒントを表示します。
 - `/api/webhooks/github` エンドポイントは **`503 github webhooks not configured`** を返します — Multica はすべての署名を有効として扱うのではなく、secret なしではイベント処理を拒否します。
 
-**任意の `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` が設定されていない場合の動作:**
-
-- インストール直後、接続カードには一時的に `Connected to unknown` と表示されます。GitHub から `installation.created` webhook が届くと（通常は数秒以内）、Multica は行を実際の組織名/ユーザー名に更新し、リアルタイムブロードキャストを発行するため、開いている Settings → GitHub タブは手動更新なしで反映されます。
-
 **注:** `GITHUB_WEBHOOK_SECRET` はインストールフローの state token の署名キーとして再利用されるため、運用者は secret を 1 つだけ管理すればよいです。これは GitHub App の *Client* secret では**ありません** — Client secret は OAuth 関連であり、この連携では使われません。完全な手順は [GitHub 連携 → セルフホストのセットアップ](/github-integration#self-host-setup)を参照してください。
 
 ## 使用量分析

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

@@ -49,12 +49,10 @@ Multica는 두 가지 전송 백엔드를 지원합니다 — 클라우드 배
 | 변수 | 기본값 | 설명 |
 |---|---|---|
 | `SMTP_HOST` | 비어 있음 | SMTP relay 호스트명. 이를 설정하면 SMTP 모드가 활성화되고 Resend를 덮어씁니다 |
-| `SMTP_PORT` | `25` | SMTP 포트. STARTTLS 제출에는 `587`을, SMTPS(암묵적 TLS, 자동 활성화)에는 `465`를 사용하세요 |
+| `SMTP_PORT` | `25` | SMTP 포트. STARTTLS 제출에는 `587`을 사용하세요; **포트 465(SMTPS / 암묵적 TLS)는 지원되지 않습니다** |
 | `SMTP_USERNAME` | 비어 있음 | SMTP 사용자명. 인증 없는 relay의 경우 비워 두세요 |
 | `SMTP_PASSWORD` | 비어 있음 | SMTP 비밀번호 |
-| `SMTP_TLS` | `starttls` | TLS 모드. `implicit`(별칭 `smtps`, `ssl`)은 연결 시 즉시 TLS 핸드셰이크를 수행합니다(SMTPS). `465` 포트에서는 자동으로 활성화됩니다. 미설정 / `starttls`는 연결 후 STARTTLS로 업그레이드합니다 |
 | `SMTP_TLS_INSECURE` | `false` | TLS 인증서 검증을 건너뛰려면 `true`로 설정 (사설 CA / 자체 서명 인증서만 해당) |
-| `SMTP_EHLO_NAME` | 머신 호스트명 | relay에 알리는 EHLO/HELO 이름. 엄격한 relay(예: Google Workspace `smtp-relay.gmail.com`)가 공개 IP에서 보내는 기본 greeting을 거부하는 경우 실제 FQDN을 설정하세요 — 그렇지 않으면 relay가 연결을 끊고, 이는 이후 명령에서 불투명한 `EOF`로 나타납니다 |
 
 서버가 STARTTLS를 알리면 자동으로 업그레이드됩니다. dial 타임아웃은 10초이고 전체 SMTP 세션에는 30초 데드라인이 있어, 블랙홀이 된 relay가 auth 핸들러를 멈추게 할 수 없습니다.
 
@@ -86,19 +84,15 @@ Multica는 사용자가 업로드한 첨부 파일(댓글의 이미지와 파일
 | `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로 전환됩니다 |
-| `ATTACHMENT_DOWNLOAD_MODE` | `auto` | 첨부 파일 다운로드 방식: `auto`, `cloudfront`, `presign`, `proxy`. `auto`에서는 CloudFront가 완전히 설정되어 있으면 우선 사용하고, 내부/프라이빗 endpoint host는 server proxy를, 공개 S3 호환 endpoint는 지원되는 경우 presigned GET을 사용합니다 |
-| `ATTACHMENT_DOWNLOAD_URL_TTL` | `30m` | CloudFront signed URL 및 S3 presigned download URL의 유효 기간. Go duration 형식을 받습니다 |
 
 **`S3_BUCKET`을 설정하지 않으면**: 서버는 시작 시 `"S3_BUCKET not set, cloud upload disabled"`를 로깅하고, 모든 업로드는 로컬 디스크로 폴백합니다.
 
-**저장된 객체 URL**은 다음 우선순위 순서로 구성됩니다:
+**공개 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)로 폴백합니다.
 
-API `download_url` 값은 CloudFront 서명이 설정되지 않은 경우 `GET /api/attachments/{id}/download`를 사용합니다. 이 endpoint는 안전한 경우 CloudFront/S3 presigned URL로 리디렉션하고, `http://rustfs:9000` 같은 프라이빗/내부 endpoint에서는 server가 스트리밍합니다. Docker/VPC 내부 객체 저장소에서는 `ATTACHMENT_DOWNLOAD_MODE=proxy`를 명시할 수 있습니다.
-
 ### 로컬 디스크 (S3가 설정되지 않은 경우)
 
 | 변수 | 기본값 | 설명 |
@@ -198,24 +192,18 @@ S3 앞에 CloudFront를 두는 경우 세 가지 변수가 적용됩니다: `CLO
 
 ## GitHub 연동
 
-[GitHub PR ↔ 이슈 연동](/github-integration)에는 두 개의 필수 변수가 필요합니다. 설정에서 Connect GitHub를 활성화하고 들어오는 webhook을 수락하려면 둘 다 설정하세요. 추가로 두 개의 선택 변수를 설정하면 설치 시점에 연결된 계정 이름을 즉시 가져올 수 있습니다.
+[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_APP_ID` | 비어 있음 | 선택. App 설정 페이지에 표시되는 숫자 App ID. `GITHUB_APP_PRIVATE_KEY`와 함께 설정하면 setup 콜백이 설치 시점에 GitHub에서 연결된 계정 이름을 가져올 수 있습니다 |
-| `GITHUB_APP_PRIVATE_KEY` | 비어 있음 | 선택. App RSA 비공개 키의 전체 PEM 블록 (`-----BEGIN/END-----` 줄 포함, 줄바꿈 유지). GitHub의 App 인증 REST 호출에 필요한 단명 JWT를 발급하는 데 사용됩니다 |
 
-**필수 변수 중 하나라도 설정하지 않았을 때의 동작:**
+**둘 중 하나라도 설정하지 않았을 때의 동작:**
 
 - 설정 → GitHub의 `Connect GitHub`가 **비활성화**되고 admin에게 "not configured" 힌트를 표시합니다.
 - `/api/webhooks/github` 엔드포인트는 **`503 github webhooks not configured`**를 반환합니다 — Multica는 모든 서명을 유효한 것으로 취급하기보다, secret 없이는 이벤트 처리를 거부합니다.
 
-**선택 `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY`가 설정되지 않았을 때의 동작:**
-
-- 설치 직후 연결 카드에 잠시 `Connected to unknown`이 표시됩니다. GitHub의 `installation.created` 웹훅이 도착하면(보통 몇 초 이내) Multica가 행을 실제 조직/사용자 이름으로 갱신하고 실시간 브로드캐스트를 보내, 열려 있는 Settings → GitHub 탭이 수동 새로고침 없이 업데이트됩니다.
-
 **참고:** `GITHUB_WEBHOOK_SECRET`은 설치 흐름 state token의 서명 키로 재사용되므로, 운영자는 secret 하나만 관리하면 됩니다. 이것은 GitHub App의 *Client* secret이 **아닙니다** — Client secret은 OAuth 관련이며 이 연동에서는 사용되지 않습니다. 전체 안내는 [GitHub 연동 → 자체 호스팅 설정](/github-integration#self-host-setup)을 참고하세요.
 
 ## 사용량 분석

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

@@ -54,7 +54,6 @@ Multica supports two delivery backends — [Resend](https://resend.com/) for clo
 | `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) |
-| `SMTP_EHLO_NAME` | machine hostname | EHLO/HELO name announced to the relay. Set a real FQDN when a strict relay (e.g. Google Workspace `smtp-relay.gmail.com`) rejects the default greeting from a public IP — otherwise the relay drops the connection and it surfaces as an opaque `EOF` on a later command |
 
 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.
 
@@ -86,19 +85,15 @@ Multica stores user-uploaded attachments (images and files in comments). **S3 is
 | `S3_REGION` | `us-west-2` | AWS region. Must match the bucket's actual region — it is used both for SDK signing and for building the public URL |
 | `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | empty | Static credentials. When both are unset, the AWS SDK default credential chain is used (IAM role / environment credentials) |
 | `AWS_ENDPOINT_URL` | empty | Custom S3-compatible endpoint (for example [MinIO](https://min.io/)). Setting this switches to path-style URLs |
-| `ATTACHMENT_DOWNLOAD_MODE` | `auto` | Attachment download path: `auto`, `cloudfront`, `presign`, or `proxy`. In `auto`, CloudFront is preferred when fully configured; internal/private endpoint hosts use the server proxy; public S3-compatible endpoints use presigned GET URLs when supported |
-| `ATTACHMENT_DOWNLOAD_URL_TTL` | `30m` | TTL for CloudFront signed URLs and S3 presigned download URLs. Accepts Go duration strings |
 
 **When `S3_BUCKET` is unset**: the server logs `"S3_BUCKET not set, cloud upload disabled"` at startup, and all uploads fall back to local disk.
 
-**Stored object URLs** are constructed in this order of priority:
+**Public URLs** are constructed in this order of priority:
 
 1. `https://<CLOUDFRONT_DOMAIN>/<key>` if `CLOUDFRONT_DOMAIN` is set.
 2. `<AWS_ENDPOINT_URL>/<S3_BUCKET>/<key>` (path-style) if `AWS_ENDPOINT_URL` is set.
 3. `https://<S3_BUCKET>.s3.<S3_REGION>.amazonaws.com/<key>` (virtual-hosted-style). When `S3_BUCKET` contains dots, the server falls back to `https://s3.<S3_REGION>.amazonaws.com/<S3_BUCKET>/<key>` (path-style) because the AWS-issued wildcard TLS certificate does not validate dotted bucket hosts.
 
-API `download_url` values use `GET /api/attachments/{id}/download` unless CloudFront signing is configured. The endpoint redirects to CloudFront/S3 presigned URLs when safe, or streams through the server for private/internal endpoints such as `http://rustfs:9000`. For Docker/VPC-only object stores, set `ATTACHMENT_DOWNLOAD_MODE=proxy` if auto detection is not conservative enough for your network.
-
 ### Local disk (when S3 is not configured)
 
 | Variable | Default | Description |
@@ -200,24 +195,18 @@ For a full explanation of how each parameter affects daemon behavior, see [Daemo
 
 ## GitHub integration
 
-The [GitHub PR ↔ issue integration](/github-integration) needs two variables. Set both to enable Connect GitHub in Settings and accept incoming webhooks. Two additional variables are optional but populate the connected account name on install.
+The [GitHub PR ↔ issue integration](/github-integration) needs two variables. Set both to enable Connect GitHub in Settings and accept incoming webhooks.
 
 | Variable | Default | Description |
 |---|---|---|
 | `GITHUB_APP_SLUG` | empty | The slug of your GitHub App (the tail of `https://github.com/apps/<slug>`). Drives the Settings → 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 |
-| `GITHUB_APP_ID` | empty | Optional. Numeric App ID from the App's settings page. Combined with `GITHUB_APP_PRIVATE_KEY`, lets the setup callback fetch the connected account name from GitHub immediately on install |
-| `GITHUB_APP_PRIVATE_KEY` | empty | Optional. Full PEM block of the App's RSA private key (including `-----BEGIN/END-----` lines, newlines preserved). Used to mint the short-lived JWT GitHub requires for App-authenticated REST calls |
 
-**Behavior when either of the required variables is unset:**
+**Behavior when either is unset:**
 
 - `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.
 
-**Behavior when the optional `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` are unset:**
-
-- The connection card briefly shows `Connected to unknown` after install. Multica refreshes the row to the real org/user name as soon as GitHub delivers the `installation.created` webhook (typically within a few seconds), and broadcasts a realtime update so any open Settings → GitHub tab reflects the change without a manual refresh.
-
 **Note:** `GITHUB_WEBHOOK_SECRET` is reused as the signing key for the install-flow state token, so operators only need to manage one secret. It is **not** the GitHub App's *Client* secret — Client secrets are OAuth-related and not used by this integration. See [GitHub integration → Self-host setup](/github-integration#self-host-setup) for the full walkthrough.
 
 ## Usage analytics

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

@@ -54,7 +54,6 @@ Multica 支持两种邮件发送通道——[Resend](https://resend.com/) 适合
 | `SMTP_PASSWORD` | 空 | SMTP 密码 |
 | `SMTP_TLS` | `starttls` | TLS 模式。`implicit`（别名 `smtps`、`ssl`）在连接时立即进行 TLS 握手（SMTPS）；`465` 端口会自动启用。未设置 / `starttls` 则在连接后通过 STARTTLS 升级 |
 | `SMTP_TLS_INSECURE` | `false` | 设为 `true` 跳过 TLS 证书校验（仅限私有 CA / 自签证书）|
-| `SMTP_EHLO_NAME` | 机器主机名 | 向 relay 通告的 EHLO/HELO 名称。当严格的 relay（例如 Google Workspace `smtp-relay.gmail.com`）拒绝来自公网 IP 的默认问候时，填一个真实的 FQDN——否则 relay 会直接断开连接，并在后续某条命令上表现为一个不知所云的 `EOF` |
 
 服务端 advertise STARTTLS 时会自动升级。dial 超时 10s，整个 SMTP 会话有 30s deadline，避免 relay 黑洞把 auth handler 挂死。
 
@@ -86,19 +85,15 @@ Multica 存储用户上传的附件（评论里的图片、文件等）。**优
 | `S3_REGION` | `us-west-2` | AWS 区域。必须和 bucket 所在区域一致——SDK 签名和公开 URL 都用它 |
 | `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | 空 | 静态凭证。全未设时用 AWS SDK 默认凭证链（IAM role / 环境凭证）|
 | `AWS_ENDPOINT_URL` | 空 | 自定义 S3 兼容端点（例如 [MinIO](https://min.io/)）。设了会切到 path-style URL |
-| `ATTACHMENT_DOWNLOAD_MODE` | `auto` | 附件下载路径：`auto`、`cloudfront`、`presign` 或 `proxy`。`auto` 下 CloudFront 配完整时优先 CloudFront；内网/私有 endpoint host 走 server proxy；公网 S3 兼容 endpoint 在支持时走 presigned GET |
-| `ATTACHMENT_DOWNLOAD_URL_TTL` | `30m` | CloudFront signed URL 和 S3 presigned download URL 的有效期。使用 Go duration 格式 |
 
 **`S3_BUCKET` 未设时**：server 启动时打 info 日志 `"S3_BUCKET not set, cloud upload disabled"`，所有上传回落到本地磁盘。
 
-**对象存储 URL** 按优先级拼装：
+**公开 URL** 按优先级拼装：
 
 1. 设了 `CLOUDFRONT_DOMAIN` → `https://<CLOUDFRONT_DOMAIN>/<key>`
 2. 设了 `AWS_ENDPOINT_URL` → `<AWS_ENDPOINT_URL>/<S3_BUCKET>/<key>`（path-style）
 3. 默认走 AWS S3 → `https://<S3_BUCKET>.s3.<S3_REGION>.amazonaws.com/<key>`（virtual-hosted-style）。bucket 名含点时会回落到 `https://s3.<S3_REGION>.amazonaws.com/<S3_BUCKET>/<key>`（path-style），因为 AWS 通配证书无法覆盖含点 host。
 
-API 返回的 `download_url` 在未配置 CloudFront 签名时会指向 `GET /api/attachments/{id}/download`。这个端点会在安全时跳转到 CloudFront/S3 presigned URL；遇到 `http://rustfs:9000` 这类私有或内网 endpoint 时则由 server 流式转发。Docker/VPC 内部对象存储建议显式设置 `ATTACHMENT_DOWNLOAD_MODE=proxy`。
-
 ### 本地磁盘（S3 未配时）
 
 | 环境变量 | 默认值 | 说明 |
@@ -179,9 +174,6 @@ API 返回的 `download_url` 在未配置 CloudFront 签名时会指向 `GET /ap
 | `MULTICA_DAEMON_HEARTBEAT_INTERVAL` | `15s` | 心跳频率 |
 | `MULTICA_DAEMON_POLL_INTERVAL` | `3s` | 任务轮询频率 |
 | `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` | `20` | 并发任务上限 |
-| `MULTICA_AGENT_TIMEOUT` | `0` | 单次任务的绝对墙钟上限；`0` = 不设上限，任务只受看门狗约束（活跃任务不会因为跑得久被杀）。想要硬性成本/资源天花板时再设一个正值 |
-| `MULTICA_AGENT_IDLE_WATCHDOG` | `30m` | 空闲看门狗：backend 持续静默（无消息、消息队列为空、且没有工具在途）这么久就 force-stop。`0` = 关闭整套看门狗 |
-| `MULTICA_AGENT_TOOL_WATCHDOG` | `2h` | 工具在途时的静默上限：某个工具调用发出后长时间无任何输出（疑似卡死的子进程）这么久就 force-stop。`0` = 关闭该兜底（在途工具永不被停）|
 | `MULTICA_<PROVIDER>_PATH` | 对应 CLI 名 | 各 AI 编程工具的可执行文件路径（如 `MULTICA_CLAUDE_PATH`）|
 | `MULTICA_<PROVIDER>_MODEL` | 空 | 各 AI 编程工具的默认模型 |
 
@@ -203,24 +195,18 @@ API 返回的 `download_url` 在未配置 CloudFront 签名时会指向 `GET /ap
 
 ## GitHub 集成
 
-[GitHub PR ↔ issue 集成](/github-integration) 依赖两个必填环境变量。两个都配上才会启用 Settings 里的 Connect GitHub 并接受 webhook。另外两个可选变量用于在安装时直接拿到关联账号名。
+[GitHub PR ↔ issue 集成](/github-integration) 依赖两个环境变量。两个都配上才会启用 Settings 里的 Connect GitHub 并接受 webhook。
 
 | 环境变量 | 默认值 | 说明 |
 |---|---|---|
 | `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 的签名密钥 |
-| `GITHUB_APP_ID` | 空 | 可选。App 设置页上的数字 App ID。配合 `GITHUB_APP_PRIVATE_KEY` 使用，让 setup 回调在安装那一刻直接从 GitHub 取到关联账号名 |
-| `GITHUB_APP_PRIVATE_KEY` | 空 | 可选。App RSA 私钥的完整 PEM 块（包含 `-----BEGIN/END-----` 两行，保留换行）。用于签发 GitHub App 鉴权 REST 调用所需的短效 JWT |
 
-**任一必填变量未设时：**
+**任一变量未设时：**
 
 - Settings → GitHub 里 `Connect GitHub` 按钮 **disable**，对 admin 显示「not configured」提示
 - `/api/webhooks/github` 直接返回 **`503 github webhooks not configured`**——secret 没配置时 Multica 拒绝处理任何 webhook 事件，而不是把所有签名当 valid
 
-**可选 `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` 未设时：**
-
-- 安装完成后，连接卡片会先短暂显示 `已连接到 unknown`。等 GitHub 的 `installation.created` webhook 到达（通常几秒内），Multica 会把 row 刷成真实的组织/用户名，并通过 realtime 推送让正在打开的 Settings → GitHub 页面无需手动刷新即可更新。
-
 **注意：** `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

@@ -51,7 +51,7 @@ cd multica
 make selfhost
 ```
 
-`make selfhost` automatically creates `.env`, generates a random `JWT_SECRET` and Postgres password, and starts all services via Docker Compose.
+`make selfhost` automatically creates `.env`, generates a random `JWT_SECRET`, and starts all services via Docker Compose.
 
 By default it pulls the latest stable release images from GHCR. To build the backend/web from your current checkout instead, run `make selfhost-build`.
 If the selected GHCR tag has not been published yet, `make selfhost` now tells you to fall back to `make selfhost-build`.
@@ -63,7 +63,7 @@ Once ready:
 - **Backend API:** http://localhost:8080
 
 <Callout>
-If you prefer running the Docker Compose steps manually: `cp .env.example .env`, edit `JWT_SECRET`, `POSTGRES_PASSWORD`, and the password segment in `DATABASE_URL`, then `docker compose -f docker-compose.selfhost.yml pull && docker compose -f docker-compose.selfhost.yml up -d`.
+If you prefer running the Docker Compose steps manually: `cp .env.example .env`, edit `JWT_SECRET`, then `docker compose -f docker-compose.selfhost.yml pull && docker compose -f docker-compose.selfhost.yml up -d`.
 </Callout>
 
 ### Step 2 — Log In
@@ -133,54 +133,17 @@ 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
+## Usage Dashboard Rollup (Required)
 
-The Usage / Runtime dashboards read from a derived `task_usage_hourly` table populated by `rollup_task_usage_hourly()`. As of MUL-2957 the backend runs this rollup **in-process** on every replica via a DB-backed scheduler (`sys_cron_executions`). A fresh self-host install needs no operator action — the bundled `pgvector/pgvector:pg17` image works as-is, and you do **not** need to swap it for an image that ships `pg_cron`, register an external cron job, run a systemd timer, or schedule a Kubernetes `CronJob`.
+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.
 
-Multiple backend replicas are safe: every replica ticks every 30 seconds and tries to claim the current 5-minute UTC plan, but the unique key `(job_name, scope_kind, scope_id, plan_time)` means only one wins each plan. Inspect the audit table to confirm steady-state operation:
+Pick one supported path before relying on the Usage / Runtime dashboard:
 
-```sql
-SELECT plan_time, status, attempt, runner_id,
-       error_code, error_msg, started_at, finished_at
-  FROM sys_cron_executions
- WHERE job_name = 'rollup_task_usage_hourly'
- ORDER BY plan_time DESC
- LIMIT 20;
-```
+- **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.
 
-<Callout>
-**Upgrading from `v0.3.4` to `v0.3.5+`?** As of MUL-2957 the `migrate up` command runs an idempotent monthly-slice backfill automatically right before applying migration `103`, so the upgrade completes in a single invocation — no operator step required. If you are on a pre-MUL-2957 binary or the auto-hook fails for an environmental reason, run `backfill_task_usage_hourly` against the same database and re-run the upgrade. Full recovery flow lives in [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup).
-</Callout>
-
-### Compatibility paths (existing deployments only)
-
-External schedulers — **`pg_cron` registered on the database, an external cron job, a systemd timer, or a Kubernetes `CronJob`** — that call `SELECT rollup_task_usage_hourly()` directly were the only option before MUL-2957 and remain a supported compatibility path. They are no longer the recommended setup; new deployments should rely on the in-process scheduler. The SQL function holds advisory lock 4246 internally, so the in-process scheduler and any pre-existing external schedule can coexist without ever double-writing the rollup.
-
-If you already have a `pg_cron` job in production and want to retire it, the safe sequence is:
-
-1. Confirm the in-process scheduler is healthy on at least one backend replica — recent SUCCESS rows should be landing in `sys_cron_executions` for `rollup_task_usage_hourly`:
-
-   ```sql
-   SELECT plan_time, status, runner_id, finished_at
-     FROM sys_cron_executions
-    WHERE job_name = 'rollup_task_usage_hourly'
-      AND status = 'SUCCESS'
-    ORDER BY plan_time DESC
-    LIMIT 5;
-   ```
-
-2. Once SUCCESS rows are arriving on schedule, unschedule the redundant `pg_cron` entry:
-
-   ```sql
-   SELECT cron.unschedule('rollup_task_usage_hourly')
-     FROM cron.job WHERE jobname = 'rollup_task_usage_hourly';
-   ```
-
-3. Leave the `pg_cron` extension itself installed unless you are sure no other workload depends on it. The bundled `pgvector/pgvector:pg17` image does **not** ship `pg_cron`, so nothing in Multica's default install needs it; uninstalling `pg_cron` from a custom image that other workloads still use is a separate decision.
-
-External cron / systemd timer / Kubernetes `CronJob` setups that call `SELECT rollup_task_usage_hourly()` directly can be retired the same way — once `sys_cron_executions` shows steady SUCCESS rows from the in-process scheduler, the external job is redundant and can be removed.
-
-Full reference (audit table semantics, advisory lock 4246, the standalone backfill command, flag descriptions, the migration auto-hook) lives in [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup).
+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
 
@@ -226,8 +189,7 @@ All configuration is done via environment variables. Copy `.env.example` as a st
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `DATABASE_URL` | PostgreSQL connection string. Keep the password segment in sync with `POSTGRES_PASSWORD`. | `postgres://multica:<postgres-password>@localhost:5432/multica?sslmode=disable` |
-| `POSTGRES_PASSWORD` | **Must change from default.** Password used by the bundled Postgres container. Keep it in sync with `DATABASE_URL`. | `openssl rand -hex 24` |
+| `DATABASE_URL` | PostgreSQL connection string | `postgres://multica:multica@localhost:5432/multica?sslmode=disable` |
 | `JWT_SECRET` | **Must change from default.** Secret key for signing JWT tokens. Use a long random string. | `openssl rand -hex 32` |
 | `FRONTEND_ORIGIN` | URL where the frontend is served (used for CORS) | `https://app.example.com` |
 

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

@@ -114,20 +114,13 @@ API サーバーで:
 ```dotenv
 GITHUB_APP_SLUG=multica-acme
 GITHUB_WEBHOOK_SECRET=<the webhook secret you generated>
-
-# 任意（推奨）— インストール時点で接続済みアカウント名を取得できるため、
-# 最初の webhook が届くまで待たなくて済みます:
-GITHUB_APP_ID=<App 設定ページに表示される数値の App ID>
-GITHUB_APP_PRIVATE_KEY=<BEGIN/END 行を含む完全な PEM ブロック>
 ```
 
-`GITHUB_APP_SLUG` と `GITHUB_WEBHOOK_SECRET` は必須です。どちらかが欠けていると:
+両方の変数が必須です。どちらかが欠けていると:
 
 - Settings の `Connect GitHub` が**無効**になり、「not configured」のヒントが表示されます。
 - `/api/webhooks/github` エンドポイントが **`503 github webhooks not configured`** を返します — Multica は secret なしでイベントを処理することを拒否し、すべての署名を黙って有効として扱うことはありません。
 
-`GITHUB_APP_ID` と `GITHUB_APP_PRIVATE_KEY` は**任意**です。これらを設定すると、setup コールバックが GitHub の App 認証された `/app/installations/{id}` エンドポイントを呼び出して、インストール時点で実際の組織名やユーザー名を取得できます。設定しない場合、接続カードには一時的に `Connected to unknown` と表示され、GitHub から `installation.created` webhook が届くと（通常は数秒以内に）Multica が行を更新し、リアルタイムブロードキャストを発行するため、開いている Settings タブは手動更新なしで反映されます。秘密鍵は App 設定ページの **Private keys → Generate a private key** で生成し、PEM ブロック全体（`-----BEGIN/END RSA PRIVATE KEY-----` の行を含む）を改行を保ったまま env 変数に貼り付けてください。
-
 `FRONTEND_ORIGIN` も設定されている必要があります（どのプロダクションのセルフホストでもすでに設定されています）。インストール後、setup コールバックがユーザーを `<FRONTEND_ORIGIN>/settings?tab=github` に戻します。
 
 env 変数を設定した後は API を再起動してください。

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

@@ -114,20 +114,13 @@ API 서버에서:
 ```dotenv
 GITHUB_APP_SLUG=multica-acme
 GITHUB_WEBHOOK_SECRET=<the webhook secret you generated>
-
-# 선택(권장) — 설치 직후 연결된 계정 이름을 바로 확보합니다.
-# 설정하지 않으면 첫 webhook이 도착할 때까지 대기해야 합니다:
-GITHUB_APP_ID=<App 설정 페이지에 표시되는 숫자 App ID>
-GITHUB_APP_PRIVATE_KEY=<BEGIN/END 줄을 포함한 전체 PEM 블록>
 ```
 
-`GITHUB_APP_SLUG`와 `GITHUB_WEBHOOK_SECRET`은 필수입니다. 둘 중 하나라도 누락되면:
+두 변수 모두 필수입니다. 둘 중 하나라도 누락되면:
 
 - Settings의 `Connect GitHub`이 **비활성화**되고 "not configured" 힌트가 표시됩니다.
 - `/api/webhooks/github` 엔드포인트가 **`503 github webhooks not configured`**를 반환합니다 — Multica는 secret 없이 이벤트를 처리하기를 거부하며, 모든 서명을 조용히 유효한 것으로 취급하지 않습니다.
 
-`GITHUB_APP_ID`와 `GITHUB_APP_PRIVATE_KEY`는 **선택 사항**입니다. 설정하면 setup 콜백이 GitHub의 App 인증 `/app/installations/{id}` 엔드포인트를 호출해 설치 직후에 실제 조직명/사용자명을 가져옵니다. 설정하지 않으면 연결 카드에 잠시 `Connected to unknown`이 표시되며, GitHub의 `installation.created` 웹훅이 도착하면(보통 몇 초 이내) Multica가 행을 갱신하고 실시간 브로드캐스트를 보내므로 열려 있는 Settings 탭이 수동 새로고침 없이 업데이트됩니다. 비공개 키는 App 설정 페이지의 **Private keys → Generate a private key**에서 생성한 뒤, PEM 블록 전체(`-----BEGIN/END RSA PRIVATE KEY-----` 줄 포함)를 줄바꿈을 유지한 채 env 값에 붙여넣으세요.
-
 `FRONTEND_ORIGIN`도 설정되어 있어야 합니다(어떤 프로덕션 자체 호스팅이든 이미 설정되어 있습니다). 설치 후 setup 콜백이 사용자를 `<FRONTEND_ORIGIN>/settings?tab=github`으로 다시 돌려보냅니다.
 
 env 변수를 설정한 후 API를 재시작하세요.

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

@@ -114,20 +114,13 @@ On the API server:
 ```dotenv
 GITHUB_APP_SLUG=multica-acme
 GITHUB_WEBHOOK_SECRET=<the webhook secret you generated>
-
-# Optional but recommended — populates the connected account name on
-# install instead of waiting for the first webhook to refresh it:
-GITHUB_APP_ID=<numeric App ID from the App's settings page>
-GITHUB_APP_PRIVATE_KEY=<full PEM block, including BEGIN/END lines>
 ```
 
-`GITHUB_APP_SLUG` and `GITHUB_WEBHOOK_SECRET` are required. If either is missing:
+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.
 
-`GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` are **optional**. They let the setup callback call GitHub's App-authenticated `/app/installations/{id}` endpoint to fetch the real organization or user name during install. Without them, the connection card briefly shows `Connected to unknown` until GitHub delivers the `installation.created` webhook (typically within a few seconds), at which point Multica refreshes the row and broadcasts a realtime update so any open Settings tab updates without a manual refresh. Generate the private key under **Private keys → Generate a private key** on the App's settings page; paste the full PEM block (including the `-----BEGIN/END RSA PRIVATE KEY-----` lines) into the env var, preserving newlines.
-
 `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.

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

@@ -114,19 +114,13 @@ API server 上：
 ```dotenv
 GITHUB_APP_SLUG=multica-acme
 GITHUB_WEBHOOK_SECRET=<你刚生成的 webhook secret>
-
-# 可选但建议配置——安装完成时直接拿到关联账号名，而不是等第一次 webhook 才刷新：
-GITHUB_APP_ID=<App 设置页上的数字 App ID>
-GITHUB_APP_PRIVATE_KEY=<完整 PEM 块，包含 BEGIN/END 行>
 ```
 
-`GITHUB_APP_SLUG` 和 `GITHUB_WEBHOOK_SECRET` 必填。任何一个缺失：
+两个都必填。任何一个缺失：
 
 - Settings 里 `Connect GitHub` 按钮会被 **disable**，并显示「not configured」提示
 - `/api/webhooks/github` 直接返回 **`503 github webhooks not configured`**——Multica 在 secret 没配置时拒绝处理事件，不会出现「没 secret 也接受 webhook」的安全坑
 
-`GITHUB_APP_ID` 和 `GITHUB_APP_PRIVATE_KEY` **可选**。配上之后，setup 回调可以用 App JWT 鉴权调用 GitHub `/app/installations/{id}`，安装完成那一刻就拿到真实的组织名/用户名。不配的话，连接卡片会先显示 `已连接到 unknown`，等 GitHub 的 `installation.created` webhook 到达（通常几秒内），Multica 会刷新 row 并通过 realtime 推送让 Settings 页面无需手动刷新即可更新。私钥从 App 设置页 **Private keys → Generate a private key** 生成，把整段 PEM（含 `-----BEGIN/END RSA PRIVATE KEY-----` 两行）粘到 env 里，保留换行。
-
 `FRONTEND_ORIGIN` 也必须设置（任何生产 self-host 都已经设了）——setup 回调结束后用它把用户跳回 `<FRONTEND_ORIGIN>/settings?tab=github`。
 
 设完 env 重启 API。

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

@@ -48,7 +48,7 @@ multica daemon restart
 
 ### Codex (OpenAI)
 
-よりきめ細かい承認ゲートを備えた JSON-RPC 2.0 のトランスポートです。**セッション再開は動作します** — Multica は Codex app-server の `thread/resume` で再開し、古いまたは存在しない thread では新しい thread にフォールバックします。
+よりきめ細かい承認ゲートを備えた JSON-RPC 2.0 のトランスポートです。**セッション再開のコードは存在しますが、現在は到達できません** — 再開が必要な場合は Claude Code か ACP 系列のいずれかを選んでください。
 
 | | |
 |---|---|
@@ -58,7 +58,7 @@ multica daemon restart
 
 ### Cursor (Anysphere)
 
-Cursor エディタに対応する CLI です。**セッション再開は動作します** — 現在の Cursor Agent は stream-json イベントで `session_id` を返し、Multica は次回実行時に `--resume <id>` でそれを渡します。
+Cursor エディタに対応する CLI です。**セッション再開は動作しません** — Cursor の CLI がセッション id を返さないため、再開時に渡す値は常に無効です。
 
 | | |
 |---|---|

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

@@ -48,7 +48,7 @@ multica daemon restart
 
 ### Codex (OpenAI)
 
-더 세분화된 승인 게이트를 갖춘 JSON-RPC 2.0 전송 방식입니다. MCP 구성은 작업별 `$CODEX_HOME/config.toml`에 기록됩니다. **세션 재개가 동작합니다** — Multica는 Codex app-server의 `thread/resume`으로 재개하며, 오래되었거나 없는 thread는 새 thread로 폴백합니다.
+더 세분화된 승인 게이트를 갖춘 JSON-RPC 2.0 전송 방식입니다. MCP 구성은 작업별 `$CODEX_HOME/config.toml`에 기록됩니다. **세션 재개 코드는 존재하지만 현재 도달할 수 없습니다** — 재개가 필요하다면 Claude Code 또는 ACP 계열 중 하나를 선택하세요.
 
 | | |
 |---|---|
@@ -58,7 +58,7 @@ multica daemon restart
 
 ### Cursor (Anysphere)
 
-Cursor 에디터에 대응하는 CLI입니다. **세션 재개가 동작합니다** — 현재 Cursor Agent는 stream-json 이벤트에서 `session_id`를 반환하고, Multica는 다음 실행 때 이를 `--resume <id>`로 전달합니다.
+Cursor 에디터에 대응하는 CLI입니다. **세션 재개가 작동하지 않습니다** — Cursor의 CLI가 세션 id를 반환하지 않으므로 재개 시 전달하는 값은 항상 유효하지 않습니다.
 
 | | |
 |---|---|

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

@@ -48,7 +48,7 @@ The most complete integration. Session resumption works, MCP works, and it consu
 
 ### Codex (OpenAI)
 
-JSON-RPC 2.0 transport with finer-grained approval gates. MCP config is written into the per-task `$CODEX_HOME/config.toml`. **Session resumption works** through Codex app-server `thread/resume`; stale or missing threads fall back to a fresh thread.
+JSON-RPC 2.0 transport with finer-grained approval gates. MCP config is written into the per-task `$CODEX_HOME/config.toml`. **Session resumption code exists but is currently unreachable** — pick Claude Code or one of the ACP family if you need resume.
 
 | | |
 |---|---|
@@ -58,7 +58,7 @@ JSON-RPC 2.0 transport with finer-grained approval gates. MCP config is written
 
 ### Cursor (Anysphere)
 
-The CLI counterpart to the Cursor editor. **Session resumption works** with current Cursor Agent releases: Multica reads `session_id` from the stream-json events and passes it back with `--resume <id>`.
+The CLI counterpart to the Cursor editor. **Session resumption is broken** — Cursor's CLI doesn't return a session id, so the value you pass on resume is always invalid.
 
 | | |
 |---|---|

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

@@ -48,7 +48,7 @@ multica daemon restart
 
 ### Codex（OpenAI）
 
-JSON-RPC 2.0 传输，审批粒度更细。MCP 配置会写入单次任务的 `$CODEX_HOME/config.toml`。**会话续接可用**——Multica 通过 Codex app-server 的 `thread/resume` 续接；thread 过期或不存在时会回退到新 thread。
+JSON-RPC 2.0 传输，审批粒度更细。MCP 配置会写入单次任务的 `$CODEX_HOME/config.toml`。**会话续接的代码在，但调不到** —— 要续接的话选 Claude Code 或 ACP 系列。
 
 | | |
 |---|---|
@@ -58,7 +58,7 @@ JSON-RPC 2.0 传输，审批粒度更细。MCP 配置会写入单次任务的 `$
 
 ### Cursor（Anysphere）
 
-Cursor 编辑器的 CLI 对应物。**会话续接可用**——当前 Cursor Agent 会在 stream-json 事件里返回 `session_id`，Multica 会在下一次运行时用 `--resume <id>` 传回去。
+Cursor 编辑器的 CLI 对应物。**会话续接是坏的** —— Cursor CLI 不返回 session id，你传过去的续接 id 永远无效。
 
 | | |
 |---|---|

apps/docs/content/docs/lark-bot-integration.ja.mdx

@@ -1,95 +0,0 @@
----
-title: Lark Bot 連携
-description: Multica エージェントを Lark（飞书）Bot に紐づければ、Lark の DM やグループからそのまま対話できます——@ でメンションして自然に話しかけたり、/issue と入力して Lark を離れずに Multica イシューを起票したりできます。
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-任意の[エージェント](/agents)を Lark（飞书）Bot に紐づければ、チームは Lark の中から直接それを使えます——Bot に DM したり、グループで @ メンションしたり、`/issue` と入力してアプリを開かずに [Multica イシュー](/issues)を起票したりできます。エージェントの返信は、作業の進行に合わせて更新されるライブカードとしてチャットに戻ってきます。
-
-各 Bot は 1 つの Multica エージェントと **1 対 1** で紐づきます。2 つ目のエージェントを紐づけると 2 つ目の Bot が作られます。1 つのエージェントが 2 つの Bot を持つことはありません。
-
-## この連携でできること
-
-| 場所 | 動作 |
-|---|---|
-| **エージェント → 連携** | エージェント詳細ページには **連携（Integrations）** タブがあります（左サイドバーにも対応する区画があります）。owner と admin はそこに **Lark に紐づける** が表示され、紐づけると **Lark に接続済み** バッジと **Lark で管理** リンクに切り替わります。 |
-| **Bot に DM** | ワークスペースメンバーが Lark の中で Bot に直接メッセージを送ります。各会話はそのエージェントとの Multica [chat](/chat) セッションになり、エージェントはスレッド内で返信します。 |
-| **グループで @ メンション** | Bot を Lark グループに追加して @ メンションします。読み取られるのはメンションしたメッセージだけで、Bot はグループ全体を聞いているわけではありません。 |
-| **`/issue` コマンド** | `/issue <タイトル>`（本文を続けてもよい）と入力すると、ワークスペースに新しい Multica イシューが作られ、あなたの名義になります。 |
-| **ライブ返信カード** | Bot はインタラクティブなカードを投稿し、エージェントの実行に合わせて更新し続けます——進捗、最終的な回答、あるいはエラーが反映されます。 |
-
-## エージェントを紐づける（owner / admin）
-
-紐づけはスキャンしてインストールするフローです——アプリのシークレットをコピーする必要も、開発者コンソールでの操作も不要です。
-
-1. **Agents → あなたのエージェント** からそのエージェントを開きます。
-2. **連携（Integrations）** タブ（または左サイドバーの **連携** 区画）を開き、**Lark に紐づける** をクリックします。
-3. QR コードが表示されます。スマートフォンで **Lark → スキャン** を開き、新しい PersonalAgent Bot を認可します。
-4. スキャンが完了するとダイアログが閉じ、エージェントに **Lark に接続済み** と表示されます。あなた自身の Lark アイデンティティは自動であなたの Multica アカウントに紐づくので、すぐに Bot と対話を始められます。
-
-<Callout type="info">
-QR は使い切りで、短い時間が過ぎると失効します。認可する前に失効してしまったら、**もう一度スキャン** をクリックして新しいコードを取得してください。
-</Callout>
-
-エージェントが接続されると、**Lark に紐づける** ボタンは **Lark で管理** リンクに置き換わります。スコープの調整、名前の変更、追加の権限の申請が必要なときは、これを使って Lark 内の Bot のアプリページを開いてください——再スキャンは意図的に無効化されており、既存の Bot を取り残してしまわないようにしています。
-
-## Bot を使う（メンバー）
-
-### 最初のメッセージ：Lark アイデンティティを紐づける
-
-初めて Bot にメッセージを送ると、Bot は **Lark アイデンティティを紐づける** よう促すカードで返信します。リンクをタップして Multica にサインインすると、あなたの Lark アカウントがあなたの Multica メンバーシップに紐づきます。これによって、エージェントがあなたとして振る舞えるようになります——たとえば `/issue` はあなたの名義でイシューを起票します。
-
-<Callout type="warning">
-Bot を使えるのは **ワークスペースのメンバー** だけです。メンバーでない場合や、アイデンティティの紐づけをスキップした場合、Bot は返信しません——あなたのメッセージは破棄されます（内容は保存せず、監査のために記録されます）。
-</Callout>
-
-### 対話と `/issue`
-
-- **エージェントに何でも聞く** —— Bot に DM するか、グループで @ メンションします。会話は通常のエージェント chat セッションで、エージェントはカードの中で返信します。
-- **イシューを起票する** —— `/issue Fix the login redirect` と送れば、Multica は新しいイシューを作るのと同じやり方でそのイシューをワークスペースに作ります。タイトルの後ろに行を足せば、それが説明になります。
-- **作業を見守る** —— 返信カードはエージェントの実行に合わせて自身を更新するので、進捗と結果がその場で見えます。
-
-エージェントが **オフライン**（ランタイムが接続されていない）または **アーカイブ済み** の場合、Bot はメッセージを黙って破棄するのではなく、短いステータス通知で返信します。
-
-## 管理と切断
-
-ワークスペース全体の管理は **設定 → 連携** にあります。
-
-- **接続済みの Bot** は、ワークスペース内のすべての Bot と、それぞれが紐づくエージェントを一覧表示します。この一覧はすべてのメンバーから見えます。
-- **切断** は **owner / admin 専用** です。切断すると Bot は Lark メッセージの受信を停止し、その接続が破棄されます。インストール記録は監査のために保持され、あとで同じエージェントを再び紐づけられます。
-
-## 権限
-
-- **紐づけ / 切断** にはワークスペースの **owner** または **admin** が必要です。member には接続済み Bot 一覧は見えますが、紐づけや切断の操作は見えません。
-- **Bot との対話** には、Lark アイデンティティを紐づけたワークスペースメンバーであることが必要です。それ以外の人のメッセージは一律に破棄されます。
-- この連携は破棄されたメッセージの本文を保存することはありません——監査のために破棄理由だけを記録します。
-
-## セルフホストのセットアップ
-
-Multica Cloud では連携はすでに利用可能です——このセクションは飛ばしてください。
-
-セルフホストの場合、**保存時の暗号化キーを設定するまで Lark はオフ** です。このキーは、各 Bot の app secret がデータベースに触れる前にそれを暗号化します。
-
-1. 32 バイトのキーを生成し、API サーバーに設定します。
-
-   ```dotenv
-   MULTICA_LARK_SECRET_KEY=<base64-encoded 32-byte key>
-   ```
-
-2. API を再起動します。キーを設定するまで、**設定 → 連携** には「Lark integration not enabled」という通知が表示され、**Lark に紐づける** のエントリポイントは非表示のままになります。
-
-<Callout type="info">
-**Feishu と Lark 国際版の両対応。** 各 Bot がどのクラウド（中国大陸の Feishu = `open.feishu.cn`、国際版 Lark = `open.larksuite.com`）に属するかは、QR コードをスキャンした時点で自動的に判定され、そのインストールに保存されて、その Bot へのすべての呼び出しに使われます。1 つのデプロイで両方を同時に提供できるため、どちらのテナントのチームも追加設定なしでバインドできます。
-
-`MULTICA_LARK_HTTP_BASE_URL` / `MULTICA_LARK_CALLBACK_BASE_URL` は、デプロイ全体を上書きする任意のオプション（プロキシやモック用）としてのみ残っています。通常運用では未設定のままにして、各インストールがそれぞれのクラウドに到達するようにしてください。
-
-**単一クラウド構成からのアップグレード？** これらを `https://open.larksuite.com` に設定して国際版 Lark を運用していた場合、アップグレード後の初回起動時にサーバーが既存のインストールを Lark リージョンへ付け替えるので、その後はこの上書きを外せます。中国大陸の Feishu デプロイでは操作は不要です。
-</Callout>
-
-## 次に
-
-- [エージェント](/agents) — 各 Bot はちょうど 1 つのエージェントに紐づきます
-- [Chat](/chat) — Bot の会話が Multica 内で対応するもの
-- [イシュー](/issues) — `/issue` が作るもの
-- [環境変数](/environment-variables) — セルフホスト構成の完全なリファレンス

apps/docs/content/docs/lark-bot-integration.ko.mdx

@@ -1,95 +0,0 @@
----
-title: Lark Bot 연동
-description: Multica 에이전트를 Lark(飞书) 봇에 바인딩하면, Lark에서 직접 대화할 수 있습니다 — 개인 메시지나 그룹에서 @로 멘션하거나, 자연스럽게 대화하거나, /issue를 입력해 Lark를 벗어나지 않고 Multica 이슈를 생성하세요.
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-아무 [에이전트](/agents)나 Lark(飞书) 봇에 바인딩하면, 팀이 Lark 안에서 바로 그 에이전트를 사용할 수 있습니다 — 봇에게 개인 메시지를 보내거나, 그룹에서 `@`로 멘션하거나, `/issue`를 입력해 앱을 열지 않고도 [Multica 이슈](/issues)를 생성하세요. 에이전트의 답변은 실시간 카드로 채팅에 돌아오며, 작업이 진행되는 동안 계속 업데이트됩니다.
-
-각 봇은 하나의 Multica 에이전트와 **일대일**로 바인딩됩니다. 두 번째 에이전트를 바인딩하면 두 번째 봇이 생성되며, 하나의 에이전트가 두 개의 봇을 갖는 일은 없습니다.
-
-## 연동이 하는 일
-
-| 위치 | 동작 |
-|---|---|
-| **에이전트 → Integrations** | 에이전트 상세 페이지에 **Integrations** 탭이 있습니다(왼쪽 사이드바에도 대응하는 섹션이 있습니다). owner와 admin에게는 여기에 **Bind to Lark**가 보이며, 바인딩되면 **Connected to Lark** 배지와 **Manage in Lark** 링크로 바뀝니다. |
-| **봇에게 개인 메시지** | 워크스페이스 멤버가 Lark에서 봇에게 직접 메시지를 보냅니다. 각 대화는 그 에이전트와의 Multica [chat](/chat) 세션이 되며, 에이전트는 해당 스레드에서 답변합니다. |
-| **그룹에서 `@` 멘션** | 봇을 Lark 그룹에 추가하고 `@`로 멘션하세요. 멘션한 메시지만 읽으며, 봇이 그룹 전체를 듣지는 않습니다. |
-| **`/issue` 명령** | `/issue <제목>`(본문 추가 가능)을 입력하면 워크스페이스에 새 Multica 이슈가 생성되고, 당신 이름으로 귀속됩니다. |
-| **실시간 답변 카드** | 봇은 인터랙티브 카드를 게시하고 에이전트가 실행되는 동안 계속 갱신합니다 — 진행 상황, 최종 답변, 또는 오류. |
-
-## 에이전트 바인딩하기 (owner / admin)
-
-바인딩은 스캔하여 설치하는 방식입니다 — 복사할 앱 시크릿도, 개발자 콘솔 작업도 없습니다.
-
-1. **Agents → _당신의 에이전트_**에서 에이전트를 엽니다.
-2. **Integrations** 탭으로 이동하거나(또는 왼쪽 사이드바의 **Integrations** 섹션 사용) **Bind to Lark**를 클릭합니다.
-3. QR 코드가 나타납니다. 휴대폰에서 **Lark → 스캔**을 열고, 새로 생긴 PersonalAgent 봇을 인증하세요.
-4. 스캔이 완료되면 대화상자가 닫히고 에이전트에 **Connected to Lark**가 표시됩니다. 당신의 Lark 신원이 자동으로 Multica 계정에 바인딩되므로, 곧바로 봇과 대화를 시작할 수 있습니다.
-
-<Callout type="info">
-QR 코드는 일회용이며 짧은 시간 후에 만료됩니다. 인증하기 전에 만료되면 **Scan again**을 클릭해 새 코드를 받으세요.
-</Callout>
-
-에이전트가 연결되면 **Bind to Lark** 버튼이 **Manage in Lark** 링크로 바뀝니다. 권한 범위를 조정하거나, 이름을 바꾸거나, 추가 권한을 요청해야 할 때 이 링크로 Lark에서 봇의 앱 페이지를 여세요 — 기존 봇이 고아가 되지 않도록 재스캔은 의도적으로 비활성화되어 있습니다.
-
-## 봇 사용하기 (멤버)
-
-### 첫 메시지: Lark 신원 바인딩하기
-
-봇에게 처음 메시지를 보내면, **Lark 신원을 바인딩**하라는 카드로 답합니다. 링크를 탭하고 Multica에 로그인하면, 당신의 Lark 계정이 Multica 멤버십에 연결됩니다. 바로 이 단계가 에이전트로 하여금 당신을 대신해 행동하게 합니다 — 예를 들어 `/issue`는 이슈를 당신 이름으로 생성합니다.
-
-<Callout type="warning">
-**워크스페이스 멤버**만 봇을 사용할 수 있습니다. 멤버가 아니거나 신원 바인딩을 건너뛰면 봇은 응답하지 않으며, 메시지는 폐기됩니다(감사 목적으로 기록되며, 내용은 저장하지 않습니다).
-</Callout>
-
-### 대화와 `/issue`
-
-- **무엇이든 에이전트에게 물어보기** — 봇에게 개인 메시지를 보내거나 그룹에서 `@`로 멘션하세요. 이 대화는 일반적인 에이전트 chat 세션이며, 에이전트는 카드에서 답변합니다.
-- **이슈 생성** — `/issue 로그인 리디렉션 수정`을 보내면 Multica가 워크스페이스에 그 이슈를 생성하며, 새 이슈가 으레 할당되는 방식 그대로 처리됩니다. 제목 뒤에 줄을 더 추가하면 설명이 됩니다.
-- **작업 지켜보기** — 답변 카드는 에이전트가 실행되는 동안 스스로 갱신되므로, 진행 상황과 결과를 그 자리에서 볼 수 있습니다.
-
-에이전트가 **오프라인**(런타임이 연결되지 않음)이거나 **보관됨** 상태라면, 봇은 메시지를 조용히 폐기하는 대신 짧은 상태 안내로 답합니다.
-
-## 관리 및 연결 해제
-
-워크스페이스 전체 관리는 **설정 → Integrations**에 있습니다.
-
-- **Connected bots**는 워크스페이스 내 모든 봇과 각 봇이 바인딩된 에이전트를 나열합니다. 이 목록은 모든 멤버에게 보입니다.
-- **Disconnect**는 **owner / admin 전용**입니다. 연결을 해제하면 봇이 Lark 메시지 수신을 멈추고 연결이 해체됩니다. 설치 기록은 감사용으로 유지되며, 이후 같은 에이전트를 다시 바인딩할 수 있습니다.
-
-## 권한
-
-- **바인딩 / 연결 해제**에는 워크스페이스 **owner** 또는 **admin**이 필요합니다. 멤버에게는 connected-bots 목록은 보이지만 바인딩이나 연결 해제 컨트롤은 보이지 않습니다.
-- **봇과 대화하기**에는 Lark 신원이 바인딩된 워크스페이스 멤버여야 합니다. 그 외의 사람은 모두 폐기됩니다.
-- 연동은 폐기된 메시지의 본문을 절대 저장하지 않으며 — 감사용 폐기 사유만 기록합니다.
-
-## 자체 호스팅 설정
-
-Multica Cloud에서는 연동이 이미 사용 가능합니다 — 이 섹션은 건너뛰세요.
-
-자체 호스팅의 경우, **at-rest 암호화 키를 설정하기 전까지 Lark는 꺼져 있습니다**. 이 키는 각 봇의 앱 시크릿이 데이터베이스에 닿기 전에 암호화합니다.
-
-1. 32바이트 키를 생성해 API 서버에 설정합니다.
-
-   ```dotenv
-   MULTICA_LARK_SECRET_KEY=<base64-encoded 32-byte key>
-   ```
-
-2. API를 재시작하세요. 키가 설정되기 전까지 **설정 → Integrations**에는 "Lark integration not enabled" 안내가 표시되고, **Bind to Lark** 진입점은 숨겨진 채로 유지됩니다.
-
-<Callout type="info">
-**Feishu와 Lark 국제판을 동시에 지원.** 각 Bot이 어느 클라우드(중국 본토 Feishu = `open.feishu.cn`, 국제판 Lark = `open.larksuite.com`)에 속하는지는 QR 코드를 스캔할 때 자동으로 감지되어 해당 설치에 저장되고, 그 Bot에 대한 모든 호출에 사용됩니다. 하나의 배포로 둘을 동시에 제공하므로, 어느 테넌트의 팀이든 추가 설정 없이 바인딩할 수 있습니다.
-
-`MULTICA_LARK_HTTP_BASE_URL` / `MULTICA_LARK_CALLBACK_BASE_URL`는 배포 전체를 덮어쓰는 선택적 오버라이드(프록시나 mock용)로만 남아 있습니다. 일반 운영에서는 설정하지 않은 채로 두어 각 설치가 자기 클라우드에 도달하도록 하세요.
-
-**단일 클라우드 구성에서 업그레이드하나요?** 이 변수들을 `https://open.larksuite.com`으로 설정해 국제판 Lark를 운영했다면, 업그레이드 후 첫 부팅 시 서버가 기존 설치를 Lark 리전으로 다시 표시하므로 이후에는 오버라이드를 지울 수 있습니다. 중국 본토 Feishu 배포에서는 별도 작업이 필요 없습니다.
-</Callout>
-
-## 다음
-
-- [에이전트](/agents) — 각 봇은 정확히 하나의 에이전트에 바인딩됩니다
-- [Chat](/chat) — 봇 대화가 Multica 내부에서 무엇에 대응하는지
-- [이슈](/issues) — `/issue`가 생성하는 것
-- [환경 변수](/environment-variables) — 전체 자체 호스팅 구성 참조

apps/docs/content/docs/lark-bot-integration.mdx

@@ -1,95 +0,0 @@
----
-title: Lark Bot integration
-description: Bind a Multica agent to a Lark (飞书) Bot, then talk to it from a Lark DM or group — @-mention it, chat naturally, or type /issue to file a Multica issue without leaving Lark.
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-Bind any [agent](/agents) to a Lark (飞书) Bot and your team can work with it from inside Lark — DM the Bot, @-mention it in a group, or type `/issue` to file a [Multica issue](/issues) without opening the app. The agent's replies stream back into the chat as a live card that updates while it works.
-
-Each Bot is bound **one-to-one** to a single Multica agent. Binding a second agent creates a second Bot; one agent never has two Bots.
-
-## What the integration does
-
-| Surface | Behavior |
-|---|---|
-| **Agent → Integrations** | The agent detail page has an **Integrations** tab (and a matching section in the left sidebar). Owners and admins see **Bind to Lark** there; once bound it flips to a **Connected to Lark** badge with a **Manage in Lark** link. |
-| **DM the Bot** | A workspace member messages the Bot directly in Lark. Each conversation becomes a Multica [chat](/chat) session with the agent; the agent answers in-thread. |
-| **@-mention in a group** | Add the Bot to a Lark group and @-mention it. Only the mentioning message is read — the Bot does not listen to the whole group. |
-| **`/issue` command** | Typing `/issue <title>` (optionally with a body) creates a new Multica issue in the workspace, attributed to you. |
-| **Live reply card** | The Bot posts an interactive card and keeps patching it as the agent runs — progress, the final answer, or an error. |
-
-## Bind an agent (owner / admin)
-
-Binding uses a scan-to-install flow — no app secrets to copy, no developer console steps.
-
-1. Open the agent in **Agents → _your agent_**.
-2. Go to the **Integrations** tab (or use the **Integrations** section in the left sidebar) and click **Bind to Lark**.
-3. A QR code appears. On your phone, open **Lark → Scan**, then authorize the new PersonalAgent Bot.
-4. When the scan completes the dialog closes and the agent shows **Connected to Lark**. Your own Lark identity is bound to your Multica account automatically, so you can start chatting with the Bot right away.
-
-<Callout type="info">
-The QR is single-use and expires after a short window. If it lapses before you authorize, click **Scan again** for a fresh code.
-</Callout>
-
-Once an agent is connected, the **Bind to Lark** button is replaced by a **Manage in Lark** link. Use it to open the Bot's app page in Lark when you need to adjust scopes, rename it, or request additional permissions — re-scanning is intentionally disabled so you don't strand the existing Bot.
-
-## Use the Bot (members)
-
-### First message: bind your Lark identity
-
-The first time you message the Bot, it replies with a card asking you to **bind your Lark identity**. Tap the link, sign in to Multica, and your Lark account is linked to your Multica membership. This is what lets the agent act as you — for example, `/issue` files the issue under your name.
-
-<Callout type="warning">
-Only people who are **members of the workspace** can use the Bot. If you aren't a member, or you skip the identity bind, the Bot won't respond — your message is dropped (and recorded for audit, without its contents).
-</Callout>
-
-### Chat and `/issue`
-
-- **Ask the agent anything** — DM the Bot or @-mention it in a group. The conversation is a normal agent chat session; the agent replies in the card.
-- **File an issue** — send `/issue Fix the login redirect` and Multica creates that issue in the workspace, assigned the way any new issue would be. Add more lines after the title for a description.
-- **Watch it work** — the reply card patches itself while the agent runs, so you see progress and the result in place.
-
-If the agent is **offline** (its runtime isn't connected) or **archived**, the Bot replies with a short status notice instead of silently dropping your message.
-
-## Manage and disconnect
-
-Workspace-wide management lives in **Settings → Integrations**:
-
-- **Connected bots** lists every Bot in the workspace and the agent each one is bound to. This list is visible to all members.
-- **Disconnect** is **owner / admin only**. Disconnecting stops the Bot from receiving Lark messages and tears down its connection; the installation record is kept for audit, and you can re-bind the same agent later.
-
-## Permissions
-
-- **Bind / disconnect** require workspace **owner** or **admin**. Members see the connected-bots list but no bind or disconnect controls.
-- **Talking to the Bot** requires being a workspace member with a bound Lark identity. Everyone else is dropped.
-- The integration never stores message bodies for dropped messages — only a drop reason, for audit.
-
-## Self-host setup
-
-On Multica Cloud the integration is already available — skip this section.
-
-For self-host, Lark is **off until you set an at-rest encryption key**. The key encrypts each Bot's app secret before it touches the database.
-
-1. Generate a 32-byte key and set it on the API server:
-
-   ```dotenv
-   MULTICA_LARK_SECRET_KEY=<base64-encoded 32-byte key>
-   ```
-
-2. Restart the API. Until the key is set, **Settings → Integrations** shows a "Lark integration not enabled" notice and the **Bind to Lark** entry points stay hidden.
-
-<Callout type="info">
-**Feishu and Lark international, side by side.** The cloud each Bot belongs to — mainland Feishu (`open.feishu.cn`) or Lark international (`open.larksuite.com`) — is detected automatically when you scan the QR, stored on the installation, and used for every call to that Bot. A single deployment serves both at once, so teams on either tenant can bind without any extra configuration.
-
-The `MULTICA_LARK_HTTP_BASE_URL` / `MULTICA_LARK_CALLBACK_BASE_URL` env vars remain only as an optional deployment-wide override (a proxy or a mock); leave them unset for normal operation so each installation keeps reaching its own cloud.
-
-**Upgrading from a single-cloud setup?** If you ran an international-Lark deployment by setting those vars to `https://open.larksuite.com`, the server relabels your existing installations to the Lark region on first boot after upgrade — you can then clear the override. Mainland deployments need no action.
-</Callout>
-
-## Next
-
-- [Agents](/agents) — each Bot is bound to exactly one agent
-- [Chat](/chat) — what a Bot conversation maps to inside Multica
-- [Issues](/issues) — what `/issue` creates
-- [Environment variables](/environment-variables) — full self-host configuration reference

apps/docs/content/docs/lark-bot-integration.zh.mdx

@@ -1,95 +0,0 @@
----
-title: 飞书 Bot 接入
-description: 把 Multica 智能体绑定到飞书（Lark）Bot，就能直接在飞书里和它对话——私聊、群里 @ 它，或者输入 /issue 直接创建 Multica issue，全程不用离开飞书。
----
-
-import { Callout } from "fumadocs-ui/components/callout";
-
-把任意[智能体](/agents)绑定到飞书 Bot，团队就能在飞书里直接使用它——私聊 Bot、在群里 @ 它，或者输入 `/issue` 直接创建一个 [Multica issue](/issues)，不用打开应用。智能体的回复会以一张实时卡片的形式回到聊天里，随着它干活不断更新。
-
-每个 Bot 与一个 Multica 智能体**一对一**绑定。再绑定一个智能体会创建另一个 Bot；一个智能体永远不会有两个 Bot。
-
-## 这个集成能做什么
-
-| 入口 | 行为 |
-|---|---|
-| **智能体 → 集成** | 智能体详情页有一个 **集成（Integrations）** tab（左侧栏也有对应的区块）。所有者和管理员能在这里看到 **绑定到飞书**；绑定后会变成 **已连接到飞书** 徽标，并带一个 **在飞书中管理** 链接。 |
-| **私聊 Bot** | 工作区成员在飞书里直接给 Bot 发消息。每段对话都会成为该智能体的一个 Multica [chat](/chat) 会话，智能体在会话里回复。 |
-| **群里 @ 它** | 把 Bot 加进飞书群再 @ 它。Bot 只读取 @ 它的那条消息，不会监听整个群。 |
-| **`/issue` 命令** | 输入 `/issue <标题>`（可附正文）会在工作区创建一个新的 Multica issue，记在你名下。 |
-| **实时回复卡片** | Bot 会发出一张可交互卡片，并随着智能体运行不断更新——进度、最终答复或报错。 |
-
-## 绑定智能体（所有者 / 管理员）
-
-绑定走的是扫码安装流程——不用复制任何应用密钥，也不用进开发者后台。
-
-1. 在 **Agents → 你的智能体** 打开该智能体。
-2. 进入 **集成（Integrations）** tab（或使用左侧栏的 **集成** 区块），点击 **绑定到飞书**。
-3. 弹出一个二维码。用手机打开 **飞书 → 扫一扫**，然后授权这个新的 PersonalAgent Bot。
-4. 扫码完成后弹窗关闭，智能体显示 **已连接到飞书**。你自己的飞书身份会自动绑定到你的 Multica 账号，绑完即可开始和 Bot 对话。
-
-<Callout type="info">
-二维码是一次性的，并且会在较短时间后过期。如果在授权前就过期了，点 **重新扫码** 获取新码即可。
-</Callout>
-
-智能体连接后，**绑定到飞书** 按钮会替换成 **在飞书中管理** 链接。需要调整权限范围、改名或申请更多权限时，用它打开 Bot 在飞书里的应用页面——重新扫码被刻意禁用，以免把已有的 Bot 弄成孤儿。
-
-## 使用 Bot（成员）
-
-### 第一条消息：绑定你的飞书身份
-
-第一次给 Bot 发消息时，它会回一张卡片，让你 **绑定飞书身份**。点开链接、登录 Multica，你的飞书账号就会关联到你的 Multica 成员身份。正是这一步让智能体能以你的身份行事——比如 `/issue` 会把 issue 记在你名下。
-
-<Callout type="warning">
-只有**工作区成员**才能使用 Bot。如果你不是成员，或者跳过了身份绑定，Bot 不会回复——你的消息会被丢弃（仅出于审计目的记录，不保存消息内容）。
-</Callout>
-
-### 对话与 `/issue`
-
-- **随便问智能体** —— 私聊 Bot，或在群里 @ 它。对话就是一段普通的智能体 chat 会话，智能体在卡片里回复。
-- **创建 issue** —— 发送 `/issue 修复登录跳转`，Multica 会在工作区创建这个 issue，和新建任何 issue 一样。标题后面再加几行就是描述。
-- **看它干活** —— 回复卡片会随着智能体运行不断更新，进度和结果都在原处呈现。
-
-如果智能体**离线**（运行时未连接）或**已归档**，Bot 会回一条简短的状态提示，而不是悄悄丢掉你的消息。
-
-## 管理与断开
-
-工作区级别的管理在 **设置 → 集成**：
-
-- **已连接的 Bot** 列出工作区里每个 Bot 以及它绑定的智能体。这个列表所有成员都能看到。
-- **断开连接** 仅限 **所有者 / 管理员**。断开后 Bot 停止接收飞书消息、连接被销毁；安装记录会保留以便审计，之后你可以重新绑定同一个智能体。
-
-## 权限
-
-- **绑定 / 断开** 需要工作区**所有者**或**管理员**。成员能看到已连接 Bot 列表，但看不到绑定或断开的操作。
-- **和 Bot 对话** 需要你是工作区成员且已绑定飞书身份。其余的人一律被丢弃。
-- 对于被丢弃的消息，集成不会保存消息内容——只记录一个丢弃原因，用于审计。
-
-## 自部署配置
-
-在 Multica Cloud 上这个集成已经可用——可跳过本节。
-
-自部署时，**在你设置好静态加密密钥之前，飞书集成是关闭的**。这个密钥会在每个 Bot 的 app secret 落库之前对其加密。
-
-1. 生成一个 32 字节的密钥并设置到 API 服务器：
-
-   ```dotenv
-   MULTICA_LARK_SECRET_KEY=<base64 编码的 32 字节密钥>
-   ```
-
-2. 重启 API。在密钥设置好之前，**设置 → 集成** 会显示「未启用飞书集成」提示，**绑定到飞书** 入口也会保持隐藏。
-
-<Callout type="info">
-**同时支持飞书与海外版 Lark。** 每个 Bot 属于哪个云——中国大陆飞书（`open.feishu.cn`）还是海外版 Lark（`open.larksuite.com`）——会在你扫码时自动识别、记录在该安装上，并用于对这个 Bot 的所有调用。同一个部署可以同时服务两者，因此两个租户的团队都能直接绑定，无需任何额外配置。
-
-`MULTICA_LARK_HTTP_BASE_URL` / `MULTICA_LARK_CALLBACK_BASE_URL` 仅作为可选的部署级覆盖项保留（用于代理或 mock）；正常运行时请保持不设置，让每个安装各自连到自己的云。
-
-**从单云部署升级？** 如果你之前是把这两个变量设为 `https://open.larksuite.com` 来跑海外版 Lark，升级后服务会在首次启动时自动把存量安装重标记为 Lark region，之后你就可以清掉这个覆盖项。国内飞书部署无需任何操作。
-</Callout>
-
-## 下一步
-
-- [智能体](/agents) —— 每个 Bot 都绑定到恰好一个智能体
-- [Chat](/chat) —— 一段 Bot 对话在 Multica 里对应什么
-- [Issues](/issues) —— `/issue` 创建的是什么
-- [环境变量](/environment-variables) —— 完整的自部署配置参考

apps/docs/content/docs/meta.ja.json

@@ -31,7 +31,6 @@
     "inbox",
     "---連携---",
     "github-integration",
-    "lark-bot-integration",
     "---セルフホスト & 運用---",
     "environment-variables",
     "auth-setup",

apps/docs/content/docs/meta.json

@@ -31,7 +31,6 @@
     "inbox",
     "---Integrations---",
     "github-integration",
-    "lark-bot-integration",
     "---Self-hosting & ops---",
     "environment-variables",
     "auth-setup",

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

@@ -31,7 +31,6 @@
     "inbox",
     "---연동---",
     "github-integration",
-    "lark-bot-integration",
     "---자체 호스팅 & 운영---",
     "environment-variables",
     "auth-setup",

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

@@ -30,7 +30,6 @@
     "inbox",
     "---集成---",
     "github-integration",
-    "lark-bot-integration",
     "---自部署运维---",
     "environment-variables",
     "auth-setup",

apps/docs/content/docs/providers.ja.mdx

@@ -13,32 +13,32 @@ Multica は **12 個の AI コーディングツール**を標準でサポート
 
 | ツール | ベンダー | セッション再開 | MCP | スキル注入パス | モデル選択 |
 |---|---|---|---|---|---|
-| **Antigravity** | Google | ✅ (`--conversation <id>`) | ❌ | `.agents/skills/` | 動的探索（`agy models`） |
-| **Claude Code** | Anthropic | ✅ | ✅ | `.claude/skills/` | 静的 + flag |
-| **Codex** | OpenAI | ✅ | ✅ | `$CODEX_HOME/skills/` | 静的 |
+| **Antigravity** | Google | ✅ (`--conversation <id>`) | ❌ | `.agents/skills/` | Antigravity CLI 自体の内部で管理 |
+| **Claude Code** | Anthropic | ✅ | **✅（実際に使用する唯一のツール）** | `.claude/skills/` | 静的 + flag |
+| **Codex** | OpenAI | ⚠️ コードは存在するが到達不可 | ❌ | `$CODEX_HOME/skills/` | 静的 |
 | **Copilot** | GitHub | ✅ | ❌ | `.github/skills/` | 静的（アカウントの権限で決定） |
-| **Cursor** | Anysphere | ✅ | ✅ | `.cursor/skills/` | 動的探索 |
+| **Cursor** | Anysphere | ⚠️ コードは存在するが使用不可 | ❌ | `.cursor/skills/` | 動的探索 |
 | **Gemini** | Google | ❌ | ❌ | `.agent_context/skills/` | 静的 |
-| **Hermes** | Nous Research | ✅ | ✅ | `.agent_context/skills/`（フォールバック） | 動的探索 |
-| **Kimi** | Moonshot | ✅ | ✅ | `.kimi/skills/` | 動的探索 |
-| **Kiro CLI** | Amazon | ✅ | ✅ | `.kiro/skills/` | 動的探索 |
-| **OpenCode** | SST | ✅ | ✅ | `.opencode/skills/` | 動的探索 + variant |
-| **OpenClaw** | オープンソース | ✅ | ✅ | `.agent_context/skills/`（フォールバック） | エージェントにバインドされ、タスクごとに切り替え不可 |
+| **Hermes** | Nous Research | ✅ | ❌ | `.agent_context/skills/`（フォールバック） | 動的探索 |
+| **Kimi** | Moonshot | ✅ | ❌ | `.kimi/skills/` | 動的探索 |
+| **Kiro CLI** | Amazon | ✅ | ❌ | `.kiro/skills/` | 動的探索 |
+| **OpenCode** | SST | ✅ | ❌ | `.opencode/skills/` | 動的探索 |
+| **OpenClaw** | オープンソース | ✅ | ❌ | `.agent_context/skills/`（フォールバック） | エージェントにバインドされ、タスクごとに切り替え不可 |
 | **Pi** | Inflection AI | ✅（セッションがファイルパス） | ❌ | `.pi/skills/` | 動的探索 |
 
 ## 各ツールの用途
 
 ### Antigravity
 
-Google が提供します。CLI バイナリ名は `agy` です。Google の Antigravity サービスと連携し、Gemini ベースのデフォルトモデルが付属しています。**セッション再開が動作します** — `--conversation <id>` を通じて行われ、stdout が構造化されたイベントストリームではなくプレーンテキストであるため、デーモンが CLI のログファイルから conversation UUID をキャプチャします。**モデル選択が動作します** — `--model` flag（agy 1.0.6 で追加）を通じて行われ、デーモンが `agy models` でカタログを列挙し、選択された値をそのまま渡します。これらは `provider/model` slug ではなく `Claude Opus 4.6 (Thinking)` のような人間が読める表示名である点に注意してください。また agy は認識できない値を渡すと黙って空実行するため、手入力ではなく検出されたリストから選ぶことをおすすめします。スキルは `.agents/skills/` に配置されます（CLI が Gemini CLI のワークスペーススキルレイアウトをそのまま継承します — [Antigravity 移行ドキュメント](https://antigravity.google/docs/gcli-migration)を参照）。
+Google が提供します。CLI バイナリ名は `agy` です。Google の Antigravity サービスと連携し、Gemini ベースのデフォルトモデルが付属しています。**セッション再開が動作します** — `--conversation <id>` を通じて行われ、stdout が構造化されたイベントストリームではなくプレーンテキストであるため、デーモンが CLI のログファイルから conversation UUID をキャプチャします。`--model` flag はありません — モデル選択は Antigravity CLI の設定内にあるため、Multica はこのプロバイダーに対してエージェントごとのモデルピッカーを無効にします。スキルは `.agents/skills/` に配置されます（CLI が Gemini CLI のワークスペーススキルレイアウトをそのまま継承します — [Antigravity 移行ドキュメント](https://antigravity.google/docs/gcli-migration)を参照）。
 
 ### Claude Code
 
-Anthropic が提供します。**新規ユーザーにとって第一の選択肢**であり、最も完成度の高い機能セットを備えています: セッション再開が実際に動作し、MCP 構成を読み取り、`--max-turns` や `--append-system-prompt` のような細かな調整 flag をサポートします。Anthropic API キーが必要です。
+Anthropic が提供します。**新規ユーザーにとって第一の選択肢**であり、最も完成度の高い機能セットを備えています: セッション再開が実際に動作し、**11 個の中で MCP 構成を本当に読み取る唯一のツール**であり、`--max-turns` や `--append-system-prompt` のような細かな調整 flag をサポートします。Anthropic API キーが必要です。
 
 ### Codex
 
-OpenAI が提供します。JSON-RPC 2.0 を使用し、ステートフルな能力がより強く、よりきめ細かい承認メカニズム（`exec_command` および `patch_apply` に対する手動承認）を備えています。MCP 構成はタスクごとの `$CODEX_HOME/config.toml` に書き込まれます。**セッション再開は動作します** — Multica は Codex app-server の `thread/resume` で再開します。保存済み thread が見つからない、または古い場合は、新しい thread にフォールバックしてタスクを続行します。
+OpenAI が提供します。JSON-RPC 2.0 を使用し、ステートフルな能力がより強く、よりきめ細かい承認メカニズム（`exec_command` および `patch_apply` に対する手動承認）を備えています。**セッション再開のコードは存在しますが、現在は到達できません** — 再開が必要なら、Claude Code または ACP 系のいずれかを選んでください。
 
 ### Copilot
 
@@ -46,7 +46,7 @@ GitHub が提供します。モデルルーティングは GitHub アカウン
 
 ### Cursor
 
-Anysphere が提供し、Cursor エディターに対応する CLI です。**セッション再開は動作します** — 現在の Cursor Agent の stream-json イベントには `session_id` が含まれ、Multica は次回実行時に `--resume <id>` でそれを渡します。MCP 構成はタスクワークスペースの `.cursor/mcp.json` に書き込まれ、Cursor のプロジェクト approval ファイルはタスクごとの `CURSOR_DATA_DIR` 配下に置かれるため、管理対象 MCP server はユーザーのグローバル Cursor approvals に依存しません。
+Anysphere が提供し、Cursor エディターに対応する CLI です。**セッション再開のコードは存在しますが、実際には動作しません** — Cursor CLI のイベントストリームがセッション ID を返さないため、渡す再開値は常に無効です。再開が必要なら、別のものを選んでください。
 
 ### Gemini
 
@@ -54,23 +54,23 @@ Google が提供し、Gemini 2.5 および 3 シリーズをサポートしま
 
 ### Hermes
 
-Nous Research が提供します。ACP プロトコルを使用します（Kimi とトランスポート層を共有します）。セッション再開が動作し、MCP 構成は ACP `mcpServers` として渡されます。しかし**スキル注入パスは専用のものではなく汎用のフォールバック**（`.agent_context/skills/`）です — Hermes CLI 自体がこのパスを読み取らない場合、スキルが適用されないことがあります。テストで確認してください。
+Nous Research が提供します。ACP プロトコルを使用します（Kimi とトランスポート層を共有します）。セッション再開が動作します。しかし**スキル注入パスは専用のものではなく汎用のフォールバック**（`.agent_context/skills/`）です — Hermes CLI 自体がこのパスを読み取らない場合、スキルが適用されないことがあります。テストで確認してください。
 
 ### Kimi
 
-Moonshot が提供し、中国市場を対象としています。Hermes と ACP プロトコルを共有し、MCP 構成も ACP `mcpServers` として渡されますが、スキルパス `.kimi/skills/` は Kimi CLI のネイティブな探索メカニズムであり、Hermes のフォールバックとは異なります。
+Moonshot が提供し、中国市場を対象としています。Hermes と ACP プロトコルを共有しますが、スキルパス `.kimi/skills/` は Kimi CLI のネイティブな探索メカニズムであり、Hermes のフォールバックとは異なります。
 
 ### Kiro CLI
 
-Amazon が提供します。`kiro-cli acp` を通じて stdio 上で ACP を使用します。セッション再開は ACP `session/load` で動作し、MCP 構成は ACP `mcpServers` として渡され、モデル選択は `session/set_model` で動作し、スキルはプロジェクトレベルのネイティブ探索のために `.kiro/skills/` にコピーされます。
+Amazon が提供します。`kiro-cli acp` を通じて stdio 上で ACP を使用します。セッション再開は ACP `session/load` で動作し、モデル選択は `session/set_model` で動作し、スキルはプロジェクトレベルのネイティブ探索のために `.kiro/skills/` にコピーされます。
 
 ### OpenCode
 
-SST が提供するオープンソースです。利用可能なモデルと model variant を動的に探索します（CLI の構成ファイルをスキャン）。セッション再開が動作し、エージェントの `mcp_config` フィールドを消費します。Multica は `OPENCODE_CONFIG_CONTENT` 環境変数でインライン注入するため、エージェントの MCP server はタスク workdir の `opencode.json`（エージェントまたはユーザーが所有するファイル）を書き換えずに OpenCode に届きます。モデルが variant を公開している場合、Multica はそれをエージェントの thinking selector として表示し、選択値を `opencode run --variant` で OpenCode に渡します。**自分のモデルカタログをカスタマイズしたい、いじるのが好きなユーザーに適しています。**
+SST が提供するオープンソースです。利用可能なモデルを動的に探索します（CLI の構成ファイルをスキャン）。セッション再開が動作します。**自分のモデルカタログをカスタマイズしたい、いじるのが好きなユーザーに適しています。**
 
 ### OpenClaw
 
-オープンソースプロジェクトであり、CLI エージェントオーケストレーターです。MCP 構成は Multica のタスクごとの config wrapper 経由で書き込まれます。**モデルはエージェント層にバインドされます**（`openclaw agents add --model`） — タスクごとに上書きできません。構成は厳格に制御されます: ユーザーは `--model` や `--system-prompt` を渡せず、エージェント登録時の構成が決定します。
+オープンソースプロジェクトであり、CLI エージェントオーケストレーターです。**モデルはエージェント層にバインドされます**（`openclaw agents add --model`） — タスクごとに上書きできません。構成は厳格に制御されます: ユーザーは `--model` や `--system-prompt` を渡せず、エージェント登録時の構成が決定します。
 
 ### Pi
 
@@ -82,19 +82,18 @@ Inflection AI が提供し、ミニマルです。**セッション再開の方
 
 | 状態 | ツール | 意味 |
 |---|---|---|
-| ✅ 実際に動作 | Antigravity, Claude Code, Codex, Copilot, Cursor, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw, Pi | 再開 id を渡すと以前のコンテキストから続行します |
+| ✅ 実際に動作 | Antigravity, Claude Code, Copilot, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw, Pi | 再開 id を渡すと以前のコンテキストから続行します |
+| ⚠️ コードは存在するが到達不可 | Codex, Cursor | コードに再開パスがありますが、実際には到達しません（Codex は静かにフォールバックし、Cursor はセッション id を返しません） — **未サポートとみなしてください** |
 | ❌ なし | Gemini | CLI に再開メカニズムがありません |
 
 **意思決定のために**: ワークフローでエージェントがタスク間でコンテキストを保持する必要がある場合（失敗時のリトライ、手動の再実行、対話的な反復）、✅ の行にあるツールだけを選んでください。
 
-## MCP 構成: ツールごとの対応
+## MCP 構成: Claude Code だけが実際に読み取る
 
-**12 個のツールのうち、`mcp_config` を実際に消費するのは 8 個です: Claude Code、Codex、Cursor、Hermes、Kimi、Kiro CLI、OpenCode、OpenClaw**。残りの 4 個はこのフィールドを受け取りますが、**無視します** — エラーも警告もなく、構成はただ効果を発揮しません。
-
-接続方式はツールごとに異なります: Claude Code は `--mcp-config` と `--strict-mcp-config` で受け取り、Codex は daemon 管理の `mcp_servers` ブロックをタスクごとの `$CODEX_HOME/config.toml` に書き込み、Cursor は `.cursor/mcp.json` とタスクごとの `CURSOR_DATA_DIR` 配下のプロジェクト approval を書き込みます。Hermes、Kimi、Kiro CLI は ACP `mcpServers` で受け取ります。OpenCode は `OPENCODE_CONFIG_CONTENT` 環境変数でインライン構成を受け取り、OpenClaw は Multica のタスクごとの config wrapper 経由で `mcp.servers` を受け取ります。OpenCode の経路はプロジェクトの `opencode.json` を書き換えません。
+**12 個のツールのうち、`mcp_config` を実際に消費するのは Claude Code だけです**。残りの 11 個はこのフィールドを受け取りますが、**完全に無視します** — エラーも警告もなく、構成はただ効果を発揮しません。
 
 <Callout type="warning">
-エージェント構成で `mcp_config` を設定しても、MCP 列に ✅ がないツールを選んだ場合、MCP サーバーはそのエージェントに**何の効果**も及ぼしません。MCP 連携はツールごとに実装されています。
+エージェント構成で `mcp_config` を設定しても、Claude Code 以外のツールを選んだ場合、MCP サーバーはそのエージェントに**何の効果**も及ぼしません。現在、MCP 連携は Claude Code のみをカバーしています。
 </Callout>
 
 ## スキルファイルが置かれる場所
@@ -118,8 +117,6 @@ Inflection AI が提供し、ミニマルです。**セッション再開の方
 
 フォールバックパスを使うツールが実際にこのディレクトリを読み取るかどうかは、そのツール自体のドキュメントによって異なり、保証されません。Gemini / Hermes / OpenClaw でスキルが適用されない場合は、まずこの点を確認してください。
 
-ネイティブなプロジェクトレベルのパスでは、リポジトリスコープの探索は想定された挙動です。チェックアウトされたリポジトリが対応するディレクトリをすでに含んでいる場合、基盤となるツールはそのコミット済みスキルを自分で検出できます。そのリポジトリで使うためだけに、これらの repo skills を Multica へインポートする必要はありません。Multica はそれらのリポジトリファイルをそのまま保持します。ワークスペーススキルの自然なディレクトリ名が同じ場合、デーモンは `review-helper-multica` のような衝突しない兄弟ディレクトリへワークスペースコピーを書き込みます。
-
 スキルの作成と使用については、[スキル](/skills)を参照してください。
 
 ## 次へ

apps/docs/content/docs/providers.ko.mdx

@@ -13,11 +13,11 @@ Multica는 **12개의 AI 코딩 도구**를 기본 지원합니다. 이들은
 
 | 도구 | 공급사 | 세션 재개 | MCP | 스킬 주입 경로 | 모델 선택 |
 |---|---|---|---|---|---|
-| **Antigravity** | Google | ✅ (`--conversation <id>`) | ❌ | `.agents/skills/` | 동적 탐색(`agy models`) |
+| **Antigravity** | Google | ✅ (`--conversation <id>`) | ❌ | `.agents/skills/` | Antigravity CLI 자체 내부에서 관리 |
 | **Claude Code** | Anthropic | ✅ | ✅ | `.claude/skills/` | 정적 + flag |
-| **Codex** | OpenAI | ✅ | ✅ | `$CODEX_HOME/skills/` | 정적 |
+| **Codex** | OpenAI | ⚠️ 코드는 존재하지만 도달 불가 | ✅ | `$CODEX_HOME/skills/` | 정적 |
 | **Copilot** | GitHub | ✅ | ❌ | `.github/skills/` | 정적 (계정 권한으로 결정) |
-| **Cursor** | Anysphere | ✅ | ✅ | `.cursor/skills/` | 동적 탐색 |
+| **Cursor** | Anysphere | ⚠️ 코드는 존재하지만 사용 불가 | ❌ | `.cursor/skills/` | 동적 탐색 |
 | **Gemini** | Google | ❌ | ❌ | `.agent_context/skills/` | 정적 |
 | **Hermes** | Nous Research | ✅ | ✅ | `.agent_context/skills/` (fallback) | 동적 탐색 |
 | **Kimi** | Moonshot | ✅ | ✅ | `.kimi/skills/` | 동적 탐색 |
@@ -30,7 +30,7 @@ Multica는 **12개의 AI 코딩 도구**를 기본 지원합니다. 이들은
 
 ### Antigravity
 
-Google에서 제공합니다. CLI 바이너리 이름은 `agy`입니다. Google의 Antigravity 서비스와 연동되며 Gemini 기반의 기본 모델을 함께 제공합니다. **세션 재개가 동작합니다** — `--conversation <id>`를 통해서이며, stdout이 구조화된 이벤트 스트림이 아니라 일반 텍스트이기 때문에 데몬이 CLI의 로그 파일에서 conversation UUID를 캡처합니다. **모델 선택이 동작합니다** — `--model` flag(agy 1.0.6에서 추가)를 통해서이며, 데몬이 `agy models`로 카탈로그를 열거하고 선택된 값을 그대로 전달합니다. 이 값들은 `provider/model` slug가 아니라 `Claude Opus 4.6 (Thinking)` 같은 사람이 읽는 표시 이름이라는 점에 유의하세요. 또한 agy는 인식할 수 없는 값을 받으면 조용히 빈 실행을 하므로, 직접 입력하기보다 발견된 목록에서 선택하는 것을 권장합니다. 스킬은 `.agents/skills/`에 들어갑니다(CLI가 Gemini CLI의 워크스페이스 스킬 레이아웃을 그대로 따릅니다 — [Antigravity 마이그레이션 문서](https://antigravity.google/docs/gcli-migration) 참고).
+Google에서 제공합니다. CLI 바이너리 이름은 `agy`입니다. Google의 Antigravity 서비스와 연동되며 Gemini 기반의 기본 모델을 함께 제공합니다. **세션 재개가 동작합니다** — `--conversation <id>`를 통해서이며, stdout이 구조화된 이벤트 스트림이 아니라 일반 텍스트이기 때문에 데몬이 CLI의 로그 파일에서 conversation UUID를 캡처합니다. `--model` flag는 없습니다 — 모델 선택은 Antigravity CLI 설정 안에 있으므로, Multica는 이 제공자에 대해 에이전트별 모델 선택기를 비활성화합니다. 스킬은 `.agents/skills/`에 들어갑니다(CLI가 Gemini CLI의 워크스페이스 스킬 레이아웃을 그대로 따릅니다 — [Antigravity 마이그레이션 문서](https://antigravity.google/docs/gcli-migration) 참고).
 
 ### Claude Code
 
@@ -38,7 +38,7 @@ Anthropic에서 제공합니다. **신규 사용자에게 첫 번째 선택지**
 
 ### Codex
 
-OpenAI에서 제공합니다. JSON-RPC 2.0을 사용하고, 상태 유지 능력이 더 강하며, 더 세밀한 승인 메커니즘(`exec_command` 및 `patch_apply`에 대한 수동 승인)을 갖추고 있습니다. MCP 구성은 작업별 `$CODEX_HOME/config.toml`에 기록됩니다. **세션 재개가 동작합니다** — Multica는 Codex app-server의 `thread/resume`으로 재개합니다. 저장된 thread가 없거나 오래된 경우에는 새 thread로 폴백해 작업을 계속 실행합니다.
+OpenAI에서 제공합니다. JSON-RPC 2.0을 사용하고, 상태 유지 능력이 더 강하며, 더 세밀한 승인 메커니즘(`exec_command` 및 `patch_apply`에 대한 수동 승인)을 갖추고 있습니다. MCP 구성은 작업별 `$CODEX_HOME/config.toml`에 기록됩니다. **세션 재개 코드는 존재하지만 현재 도달할 수 없습니다** — 재개가 필요하다면 Claude Code나 ACP 계열 중 하나를 선택하세요.
 
 ### Copilot
 
@@ -46,7 +46,7 @@ GitHub에서 제공합니다. 모델 라우팅은 GitHub 계정 권한을 거칩
 
 ### Cursor
 
-Anysphere에서 제공하며, Cursor 에디터에 대응하는 CLI입니다. **세션 재개가 동작합니다** — 현재 Cursor Agent의 stream-json 이벤트에는 `session_id`가 포함되며, Multica는 다음 실행 때 이를 `--resume <id>`로 다시 전달합니다. MCP 구성은 작업 워크스페이스의 `.cursor/mcp.json`에 기록되고, Cursor의 프로젝트 approval 파일은 작업별 `CURSOR_DATA_DIR` 아래에 기록되므로, 관리되는 MCP 서버는 사용자의 전역 Cursor approval에 의존하지 않습니다.
+Anysphere에서 제공하며, Cursor 에디터에 대응하는 CLI입니다. **세션 재개 코드는 존재하지만 실제로는 동작하지 않습니다** — Cursor CLI 이벤트 스트림이 세션 ID를 반환하지 않으므로, 전달하는 재개 값은 항상 무효입니다. 재개가 필요하다면 다른 것을 선택하세요.
 
 ### Gemini
 
@@ -82,16 +82,17 @@ Inflection AI에서 제공하며, 미니멀합니다. **세션 재개 방식이
 
 | 상태 | 도구 | 의미 |
 |---|---|---|
-| ✅ 실제로 동작 | Antigravity, Claude Code, Codex, Copilot, Cursor, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw, Pi | 재개 id를 전달하면 이전 컨텍스트에서 이어집니다 |
+| ✅ 실제로 동작 | Antigravity, Claude Code, Copilot, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw, Pi | 재개 id를 전달하면 이전 컨텍스트에서 이어집니다 |
+| ⚠️ 코드는 존재하지만 도달 불가 | Codex, Cursor | 코드에 재개 경로가 있지만 실제로는 도달하지 않습니다(Codex는 조용히 폴백하고, Cursor는 세션 id를 반환하지 않습니다) — **미지원으로 간주하세요** |
 | ❌ 없음 | Gemini | CLI에 재개 메커니즘이 없습니다 |
 
 **의사결정을 위해**: 워크플로에서 에이전트가 작업 간에 컨텍스트를 유지해야 한다면(실패 재시도, 수동 재실행, 대화형 반복), ✅ 행에 있는 도구만 선택하세요.
 
 ## MCP 구성: 도구별 지원
 
-**12개 도구 중 `mcp_config`를 실제로 소비하는 것은 8개입니다: Claude Code, Codex, Cursor, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw**. 나머지 4개는 이 필드를 받아들이지만 **무시합니다** — 오류도, 경고도 없으며, 구성이 그저 효과를 내지 못합니다.
+**12개 도구 중 `mcp_config`를 실제로 소비하는 것은 7개입니다: Claude Code, Codex, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw**. 나머지 5개는 이 필드를 받아들이지만 **무시합니다** — 오류도, 경고도 없으며, 구성이 그저 효과를 내지 못합니다.
 
-각 도구의 연결 방식은 다릅니다: Claude Code는 `--mcp-config`와 `--strict-mcp-config`로 받고, Codex는 데몬이 관리하는 `mcp_servers` 블록을 작업별 `$CODEX_HOME/config.toml`에 기록하며, Cursor는 `.cursor/mcp.json`과 작업별 `CURSOR_DATA_DIR` 아래의 프로젝트 approval을 기록합니다. Hermes/Kimi/Kiro CLI는 ACP `mcpServers`로 받습니다. OpenCode는 `OPENCODE_CONFIG_CONTENT` 환경 변수로 인라인 구성을 받고, OpenClaw는 Multica의 작업별 config wrapper를 통해 `mcp.servers`를 받습니다. OpenCode 경로는 프로젝트의 `opencode.json`을 다시 쓰지 않습니다.
+각 도구의 연결 방식은 다릅니다: Claude Code는 `--mcp-config`와 `--strict-mcp-config`로 받고, Codex는 데몬이 관리하는 `mcp_servers` 블록을 작업별 `$CODEX_HOME/config.toml`에 기록하며, Hermes/Kimi/Kiro CLI는 ACP `mcpServers`로 받습니다. OpenCode는 `OPENCODE_CONFIG_CONTENT` 환경 변수로 인라인 구성을 받고, OpenClaw는 Multica의 작업별 config wrapper를 통해 `mcp.servers`를 받습니다. OpenCode 경로는 프로젝트의 `opencode.json`을 다시 쓰지 않습니다.
 
 <Callout type="warning">
 에이전트 구성에서 `mcp_config`를 설정했더라도 MCP 열에 ✅가 없는 도구를 선택하면, MCP 서버가 해당 에이전트에 **아무런 효과**도 미치지 않습니다. MCP 연동은 도구별로 구현됩니다.
@@ -118,8 +119,6 @@ Inflection AI에서 제공하며, 미니멀합니다. **세션 재개 방식이
 
 fallback 경로를 쓰는 도구가 실제로 이 디렉터리를 읽는지는 해당 도구 자체의 문서에 따라 달라지며 — 보장되지 않습니다. Gemini / Hermes / OpenClaw에서 스킬이 적용되지 않는다면, 먼저 이 점을 확인하세요.
 
-기본 프로젝트 수준 경로에서는 저장소 범위 탐색이 의도된 동작입니다. 체크아웃된 저장소가 이미 해당 디렉터리를 포함하고 있으면, 기반 도구가 커밋된 스킬을 자체적으로 탐색할 수 있습니다. 해당 저장소에서 사용하기 위해 이러한 repo skills를 Multica로 먼저 가져올 필요는 없습니다. Multica는 이러한 저장소 파일을 그대로 둡니다. 워크스페이스 스킬의 자연 디렉터리 이름이 같으면 데몬은 `review-helper-multica` 같은 충돌 없는 형제 디렉터리에 워크스페이스 사본을 씁니다.
-
 스킬의 생성과 사용은 [스킬](/skills)을 참고하세요.
 
 ## 다음

apps/docs/content/docs/providers.mdx

@@ -13,11 +13,11 @@ For guidance on picking a tool when creating an agent, see [Creating and configu
 
 | Tool | Vendor | Session resumption | MCP | Skill injection path | Model selection |
 |---|---|---|---|---|---|
-| **Antigravity** | Google | ✅ (`--conversation <id>`) | ❌ | `.agents/skills/` | Dynamic discovery (`agy models`) |
+| **Antigravity** | Google | ✅ (`--conversation <id>`) | ❌ | `.agents/skills/` | Managed inside the Antigravity CLI itself |
 | **Claude Code** | Anthropic | ✅ | ✅ | `.claude/skills/` | Static + flag |
-| **Codex** | OpenAI | ✅ | ✅ | `$CODEX_HOME/skills/` | Static |
+| **Codex** | OpenAI | ⚠️ Code exists but unreachable | ✅ | `$CODEX_HOME/skills/` | Static |
 | **Copilot** | GitHub | ✅ | ❌ | `.github/skills/` | Static (determined by account entitlement) |
-| **Cursor** | Anysphere | ✅ | ✅ | `.cursor/skills/` | Dynamic discovery |
+| **Cursor** | Anysphere | ⚠️ Code exists but unusable | ❌ | `.cursor/skills/` | Dynamic discovery |
 | **Gemini** | Google | ❌ | ❌ | `.agent_context/skills/` | Static |
 | **Hermes** | Nous Research | ✅ | ✅ | `.agent_context/skills/` (fallback) | Dynamic discovery |
 | **Kimi** | Moonshot | ✅ | ✅ | `.kimi/skills/` | Dynamic discovery |
@@ -30,7 +30,7 @@ For guidance on picking a tool when creating an agent, see [Creating and configu
 
 ### Antigravity
 
-From Google. CLI binary name is `agy`. Pairs with Google's Antigravity service and ships with a Gemini-backed default model. **Session resumption works** via `--conversation <id>`; the daemon captures the conversation UUID from the CLI's log file because stdout is plain text rather than a structured event stream. **Model selection works** via the `--model` flag (added in agy 1.0.6): the daemon enumerates the catalog with `agy models` and ships the chosen value verbatim. Note these are human display strings such as `Claude Opus 4.6 (Thinking)`, not `provider/model` slugs — and agy silently no-ops on a value it doesn't recognise, so prefer picking from the discovered list over typing a custom one. Skills land in `.agents/skills/` (the CLI inherits Gemini CLI's workspace skill layout — see [Antigravity migration docs](https://antigravity.google/docs/gcli-migration)).
+From Google. CLI binary name is `agy`. Pairs with Google's Antigravity service and ships with a Gemini-backed default model. **Session resumption works** via `--conversation <id>`; the daemon captures the conversation UUID from the CLI's log file because stdout is plain text rather than a structured event stream. There is no `--model` flag — model selection lives inside the Antigravity CLI settings, so Multica disables the per-agent model picker for this provider. Skills land in `.agents/skills/` (the CLI inherits Gemini CLI's workspace skill layout — see [Antigravity migration docs](https://antigravity.google/docs/gcli-migration)).
 
 ### Claude Code
 
@@ -38,7 +38,7 @@ From Anthropic. **First choice for new users** — the most complete feature set
 
 ### Codex
 
-From OpenAI. Uses JSON-RPC 2.0, has stronger statefulness, and a finer-grained approve mechanism (manual approval for `exec_command` and `patch_apply`). MCP config is materialized into the per-task `$CODEX_HOME/config.toml`. **Session resumption works** through Codex app-server `thread/resume`; if the saved thread is missing or stale, Multica falls back to a fresh thread so the task can still run.
+From OpenAI. Uses JSON-RPC 2.0, has stronger statefulness, and a finer-grained approve mechanism (manual approval for `exec_command` and `patch_apply`). MCP config is materialized into the per-task `$CODEX_HOME/config.toml`. **Session resumption code exists but is currently unreachable** — if you need resume, pick Claude Code or one of the ACP family.
 
 ### Copilot
 
@@ -46,7 +46,7 @@ From GitHub. Model routing goes through your GitHub account entitlement — the
 
 ### Cursor
 
-From Anysphere, the CLI counterpart to the Cursor editor. **Session resumption works** with current Cursor Agent releases: the stream-json event includes a `session_id`, and Multica passes it back with `--resume <id>` on the next run. MCP config is materialized into the task workspace's `.cursor/mcp.json`, with Cursor's project approval file written under a per-task `CURSOR_DATA_DIR` so managed MCP servers do not depend on the user's global Cursor approvals.
+From Anysphere, the CLI counterpart to the Cursor editor. **Session resumption code exists but doesn't actually work** — the Cursor CLI event stream doesn't return a session ID, so any resume value you pass is always invalid. If you need resume, pick something else.
 
 ### Gemini
 
@@ -82,16 +82,17 @@ The session resumption mechanism is covered in [Tasks](/tasks#can-a-task-continu
 
 | Status | Tools | Meaning |
 |---|---|---|
-| ✅ Really works | Antigravity, Claude Code, Codex, Copilot, Cursor, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw, Pi | Pass the resume id and it continues from the previous context |
+| ✅ Really works | Antigravity, Claude Code, Copilot, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw, Pi | Pass the resume id and it continues from the previous context |
+| ⚠️ Code exists but unreachable | Codex, Cursor | Resume paths exist in the code but aren't actually reached (Codex silently falls back; Cursor doesn't return session id) — **treat as unsupported** |
 | ❌ None | Gemini | The CLI has no resume mechanism |
 
 **For your decision**: if your workflow needs agents to preserve context across tasks (failure retries, manual reruns, conversational iteration), pick only from the ✅ row.
 
 ## MCP configuration: provider-specific support
 
-**Of the 12 tools, eight consume `mcp_config`: Claude Code, Codex, Cursor, Hermes, Kimi, Kiro CLI, OpenCode, and OpenClaw**. The other four accept the field but **ignore it** — no error, no warning, the config just has no effect.
+**Of the 12 tools, seven consume `mcp_config`: Claude Code, Codex, Hermes, Kimi, Kiro CLI, OpenCode, and OpenClaw**. The other five accept the field but **ignore it** — no error, no warning, the config just has no effect.
 
-The runtime paths are provider-specific: Claude Code receives it through `--mcp-config` paired with `--strict-mcp-config`; Codex writes a daemon-managed `mcp_servers` block into the per-task `$CODEX_HOME/config.toml`; Cursor writes `.cursor/mcp.json` plus per-task project approvals under `CURSOR_DATA_DIR`; Hermes, Kimi, and Kiro CLI receive ACP `mcpServers`; OpenCode receives inline config through `OPENCODE_CONFIG_CONTENT`; OpenClaw receives `mcp.servers` through Multica's per-task config wrapper. OpenCode's path does **not** rewrite the project's `opencode.json`.
+The runtime paths are provider-specific: Claude Code receives it through `--mcp-config` paired with `--strict-mcp-config`; Codex writes a daemon-managed `mcp_servers` block into the per-task `$CODEX_HOME/config.toml`; Hermes, Kimi, and Kiro CLI receive ACP `mcpServers`; OpenCode receives inline config through `OPENCODE_CONFIG_CONTENT`; OpenClaw receives `mcp.servers` through Multica's per-task config wrapper. OpenCode's path does **not** rewrite the project's `opencode.json`.
 
 <Callout type="warning">
 If you set `mcp_config` in an agent configuration but pick a tool not marked ✅ in the MCP column, your MCP servers have **no effect** on that agent. MCP integration is provider-specific.
@@ -118,8 +119,6 @@ Each tool uses **its own** skill discovery path. Before a task runs, the Multica
 
 Whether a fallback-path tool actually reads this directory depends on the tool's own documentation — no guarantees. If your skills aren't taking effect for Gemini / Hermes / OpenClaw, check this first.
 
-For native project-level paths, repo-scoped discovery is expected: if the checked-out repository already contains a matching directory, the underlying tool can discover those committed skills on its own. You do not need to import those repo skills into Multica just to use them in that repo. Multica keeps the repo files intact. If a workspace skill has the same natural directory name, the daemon writes the workspace copy to a collision-free sibling such as `review-helper-multica`.
-
 For creating and using skills, see [Skills](/skills).
 
 ## Next

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

@@ -13,11 +13,11 @@ Multica 内置支持 **12 款 AI 编程工具**。它们都实现了同一套接
 
 | 工具 | 厂商 | 会话恢复 | MCP | Skill 注入路径 | 模型选择 |
 |---|---|---|---|---|---|
-| **Antigravity** | Google | ✅（`--conversation <id>`）| ❌ | `.agents/skills/` | 动态发现（`agy models`）|
+| **Antigravity** | Google | ✅（`--conversation <id>`）| ❌ | `.agents/skills/` | 由 Antigravity CLI 自己管理 |
 | **Claude Code** | Anthropic | ✅ | ✅ | `.claude/skills/` | 静态 + flag |
-| **Codex** | OpenAI | ✅ | ✅ | `$CODEX_HOME/skills/` | 静态 |
+| **Codex** | OpenAI | ⚠️ 代码存在但不可达 | ✅ | `$CODEX_HOME/skills/` | 静态 |
 | **Copilot** | GitHub | ✅ | ❌ | `.github/skills/` | 静态（账号权益决定）|
-| **Cursor** | Anysphere | ✅ | ✅ | `.cursor/skills/` | 动态发现 |
+| **Cursor** | Anysphere | ⚠️ 代码存在但不可用 | ❌ | `.cursor/skills/` | 动态发现 |
 | **Gemini** | Google | ❌ | ❌ | `.agent_context/skills/` | 静态 |
 | **Hermes** | Nous Research | ✅ | ✅ | `.agent_context/skills/` （fallback）| 动态发现 |
 | **Kimi** | Moonshot | ✅ | ✅ | `.kimi/skills/` | 动态发现 |
@@ -30,7 +30,7 @@ Multica 内置支持 **12 款 AI 编程工具**。它们都实现了同一套接
 
 ### Antigravity
 
-Google 出品。CLI 二进制名为 `agy`，搭配 Google Antigravity 服务，默认走 Gemini 系列模型。**会话恢复真用**——通过 `--conversation <id>`；因为 stdout 是纯文本而非结构化事件流，守护进程从 CLI 的日志文件里抓取 conversation UUID。**模型选择真用**——通过 `--model` flag（agy 1.0.6 新增）：守护进程用 `agy models` 枚举可选项，并把选中的值原样传入。注意这些是 `Claude Opus 4.6 (Thinking)` 这样的人类可读显示名，而非 `provider/model` slug；而且 agy 遇到无法识别的值会静默空跑，所以优先从发现列表里挑选，不要手填。Skill 文件写入 `.agents/skills/`（CLI 沿用 Gemini CLI 的 workspace 布局——见 [Antigravity 迁移文档](https://antigravity.google/docs/gcli-migration)）。
+Google 出品。CLI 二进制名为 `agy`，搭配 Google Antigravity 服务，默认走 Gemini 系列模型。**会话恢复真用**——通过 `--conversation <id>`；因为 stdout 是纯文本而非结构化事件流，守护进程从 CLI 的日志文件里抓取 conversation UUID。CLI 没有 `--model` flag——模型选择保存在 Antigravity 自己的设置里，因此 Multica 禁用了这款工具的模型选择控件。Skill 文件写入 `.agents/skills/`（CLI 沿用 Gemini CLI 的 workspace 布局——见 [Antigravity 迁移文档](https://antigravity.google/docs/gcli-migration)）。
 
 ### Claude Code
 
@@ -38,7 +38,7 @@ Anthropic 出品。**新用户首选**——功能最完整：会话恢复真用
 
 ### Codex
 
-OpenAI 出品。使用 JSON-RPC 2.0 协议，状态化更强，approve 机制更细（手动批准 `exec_command` 和 `patch_apply`）。MCP 配置会写入单次任务的 `$CODEX_HOME/config.toml`。**会话恢复可用**——Multica 通过 Codex app-server 的 `thread/resume` 续接；如果已保存的 thread 不存在或过期，会回退到新 thread，让任务继续执行。
+OpenAI 出品。使用 JSON-RPC 2.0 协议，状态化更强，approve 机制更细（手动批准 `exec_command` 和 `patch_apply`）。MCP 配置会写入单次任务的 `$CODEX_HOME/config.toml`。**会话恢复代码存在但当前不可达**——如果你需要 resume，选 Claude Code 或 ACP 系列。
 
 ### Copilot
 
@@ -46,7 +46,7 @@ GitHub 出品。模型路由走你的 GitHub 账号权益——工具自己不
 
 ### Cursor
 
-Anysphere 出品，Cursor 编辑器的 CLI 对应物。**会话恢复可用**——当前 Cursor Agent 的 stream-json 事件会返回 `session_id`，Multica 会在下一次运行时通过 `--resume <id>` 传回去。MCP 配置会写入任务工作区的 `.cursor/mcp.json`，Cursor 的项目 approval 文件写在单次任务的 `CURSOR_DATA_DIR` 下，因此托管的 MCP server 不依赖用户全局 Cursor approvals。
+Anysphere 出品，Cursor 编辑器的 CLI 对应物。**会话恢复代码存在但实际不工作**——Cursor CLI 的事件流里不回传 session ID，所以你传的 resume 值永远无效。如果要 resume，选别的。
 
 ### Gemini
 
@@ -82,16 +82,17 @@ Inflection AI 出品，极简主义。**会话恢复机制特殊**——session
 
 | 状态 | 工具 | 含义 |
 |---|---|---|
-| ✅ 真用 | Antigravity、Claude Code、Codex、Copilot、Cursor、Hermes、Kimi、Kiro CLI、OpenCode、OpenClaw、Pi | 传 resume id，会从上次上下文接着继续 |
+| ✅ 真用 | Antigravity、Claude Code、Copilot、Hermes、Kimi、Kiro CLI、OpenCode、OpenClaw、Pi | 传 resume id，会从上次上下文接着继续 |
+| ⚠️ 代码存在但不可达 | Codex、Cursor | 代码里有 resume 路径但实际走不到（Codex 静默回落、Cursor session id 不回传）—— **当作不支持** |
 | ❌ 无 | Gemini | CLI 无 resume 机制 |
 
 **对你的决策**：如果工作流需要智能体在多次任务之间保持上下文（失败重试、手动重跑、对话式迭代），只选 ✅ 那一行的工具。
 
 ## MCP 配置：按工具不同
 
-**12 款工具里有 8 款实际消费 `mcp_config`：Claude Code、Codex、Cursor、Hermes、Kimi、Kiro CLI、OpenCode、OpenClaw**。其他 4 款会接收这个字段但**忽略**——不报错、不警告，只是配置不生效。
+**12 款工具里有 7 款实际消费 `mcp_config`：Claude Code、Codex、Hermes、Kimi、Kiro CLI、OpenCode、OpenClaw**。其他 5 款会接收这个字段但**忽略**——不报错、不警告，只是配置不生效。
 
-各工具的接入方式不同：Claude Code 通过 `--mcp-config` 加 `--strict-mcp-config` 接收；Codex 会把 daemon 管理的 `mcp_servers` block 写入单次任务的 `$CODEX_HOME/config.toml`；Cursor 会写入 `.cursor/mcp.json`，并把项目 approval 写到单次任务的 `CURSOR_DATA_DIR`；Hermes、Kimi、Kiro CLI 通过 ACP `mcpServers` 接收；OpenCode 通过 `OPENCODE_CONFIG_CONTENT` 环境变量内联接收；OpenClaw 通过 Multica 的单次任务配置 wrapper 接收 `mcp.servers`。OpenCode 这条路径**不会**改写项目里的 `opencode.json`。
+各工具的接入方式不同：Claude Code 通过 `--mcp-config` 加 `--strict-mcp-config` 接收；Codex 会把 daemon 管理的 `mcp_servers` block 写入单次任务的 `$CODEX_HOME/config.toml`；Hermes、Kimi、Kiro CLI 通过 ACP `mcpServers` 接收；OpenCode 通过 `OPENCODE_CONFIG_CONTENT` 环境变量内联接收；OpenClaw 通过 Multica 的单次任务配置 wrapper 接收 `mcp.servers`。OpenCode 这条路径**不会**改写项目里的 `opencode.json`。
 
 <Callout type="warning">
 如果你在智能体配置里设置了 `mcp_config`，但选了矩阵 MCP 列没有标 ✅ 的工具，你的 MCP server 对这个智能体**没有效果**。MCP 集成是按工具实现的。
@@ -118,8 +119,6 @@ Inflection AI 出品，极简主义。**会话恢复机制特殊**——session
 
 fallback 路径对应的工具是否真的读取这个目录，取决于工具本身的文档——没保证。如果你的 skill 对 Gemini / Hermes / OpenClaw 没起效，先查这个问题。
 
-对原生项目级路径来说，repo-scoped discovery 是预期行为：如果检出的仓库已经包含对应目录，底层工具可以自己发现这些提交在仓库里的 Skill。你不需要为了在这个仓库里使用这些 repo skills 而先把它们导入 Multica。Multica 会保持这些仓库文件不变。如果某个工作区 Skill 的自然目录名相同，守护进程会把工作区副本写到类似 `review-helper-multica` 的无冲突 sibling 目录。
-
 skill 的创建和使用详见 [技能](/skills)。
 
 ## 下一步

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

@@ -30,7 +30,7 @@ make selfhost
 
 `make selfhost` は次のことを行います。
 
-1. `.env` がなければ `.env.example` から生成し、**ランダムな JWT_SECRET と Postgres パスワード** を併せて作成します
+1. `.env` がなければ `.env.example` から生成し、**ランダムな JWT_SECRET** を併せて作成します
 2. 公式の Docker イメージ（PostgreSQL、Multica backend、Multica frontend）を取得します
 3. `docker-compose.selfhost.yml` を使ってすべてのサービスを起動します
 4. バックエンドの `/health` エンドポイントが準備できるまで待機します
@@ -49,7 +49,7 @@ make selfhost
 - **バックエンド**: [http://localhost:8080](http://localhost:8080)
 
 <Callout type="info">
-**ポートは `127.0.0.1` でのみ待ち受けます。** `docker-compose.selfhost.yml` は公開されるすべてのポートを loopback にバインドします — `ss -tlnp` には `0.0.0.0:8080` は表示されず、設計上、他のマシンからはサービスにアクセスできません。サーバーのシークレットと Postgres の認証情報は、公開インターネット上に置いては絶対にいけません。マシン間アクセスが必要な場合は、TLS を終端するリバースプロキシをスタックの前に置いてください — [ステップ5b — マシン間: リバースプロキシを前に置く](#5b-cross-machine-front-with-a-reverse-proxy)を参照してください。
+**ポートは `127.0.0.1` でのみ待ち受けます。** `docker-compose.selfhost.yml` は公開されるすべてのポートを loopback にバインドします — `ss -tlnp` には `0.0.0.0:8080` は表示されず、設計上、他のマシンからはサービスにアクセスできません。デフォルトの `JWT_SECRET` と Postgres の認証情報は、公開インターネット上に置いては絶対にいけません。マシン間アクセスが必要な場合は、TLS を終端するリバースプロキシをスタックの前に置いてください — [ステップ5b — マシン間: リバースプロキシを前に置く](#5b-cross-machine-front-with-a-reverse-proxy)を参照してください。
 </Callout>
 
 ## 2. 重要: プロダクションの安全設定を維持する
@@ -81,7 +81,7 @@ make selfhost
 
 **オプション B — SMTP relay（内部ネットワーク / オンプレミス）:**
 
-デプロイ環境が `api.resend.com` に到達できない場合や、すでに内部メールリレー（Microsoft Exchange、Postfix、オンプレミスの SendGrid など）がある場合に使ってください。両方が設定されている場合は `SMTP_HOST` が Resend より優先されるため、認証メールと招待メールは内部リレーにとどまります。STARTTLS は広告されると自動的にアップグレードされます。ポート `465`（SMTPS / 暗黙的 TLS）は接続直後の TLS ハンドシェイクを自動的に有効化し、`SMTP_TLS=implicit`（別名: `smtps`、`ssl`）は非標準の SMTPS ポートで強制的に有効化します。
+デプロイ環境が `api.resend.com` に到達できない場合や、すでに内部メールリレー（Microsoft Exchange、Postfix、オンプレミスの SendGrid など）がある場合に使ってください。両方が設定されている場合は `SMTP_HOST` が Resend より優先されるため、認証メールと招待メールは内部リレーにとどまります。ポート 465（SMTPS / 暗黙的 TLS）は現在サポートされていません — 25 または 587 を使ってください。
 
 **匿名 Exchange 内部リレー（ポート 25）** — ホストが IP で信頼され、認証情報なしで送信する場合:
 
@@ -105,26 +105,6 @@ SMTP_TLS_INSECURE=false        # set true only for private CA / self-signed
 RESEND_FROM_EMAIL=noreply@yourdomain.com
 ```
 
-**暗黙的 TLS / SMTPS（ポート 465）** — STARTTLS を広告しないアリババクラウド / テンセントの法人メールなどのプロバイダー向け。ポート `465` は暗黙的 TLS を自動的に有効化するため、ここでは `SMTP_TLS` は省略可能です:
-
-```bash
-SMTP_HOST=smtp.qiye.aliyun.com
-SMTP_PORT=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
-```
-
-**厳格な公開 relay（例: Google Workspace `smtp-relay.gmail.com`）** が公開 IP からのデフォルトの `localhost` 挨拶を拒否する場合は、`SMTP_EHLO_NAME` を relay が期待する FQDN に設定してください — そうしないと接続が切断され、後続のコマンドで不明瞭な `EOF` として表面化します。デフォルトはコンテナのホスト名で、これは通常は有効な FQDN ではありません。
-
-```bash
-SMTP_HOST=smtp-relay.gmail.com
-SMTP_PORT=587
-SMTP_EHLO_NAME=mail.yourdomain.com   # FQDN the relay accepts; defaults to the (non-FQDN) container hostname
-RESEND_FROM_EMAIL=noreply@yourdomain.com
-```
-
 その後、再起動します: `docker compose -f docker-compose.selfhost.yml restart backend`。再起動時、バックエンドはどのプロバイダーを選んだかを出力します（`EmailService: SMTP relay …` / `Resend API` / `DEV mode`）— 認証情報は決してログに残らないため、この行はヘルプを求めるときに共有しても安全です。
 
 追加の認証構成（OAuth、サインアップの許可リスト）と SMTP 変数の完全なリファレンスは、[認証設定](/auth-setup)と[環境変数 → メール](/environment-variables#email-configuration)を参照してください。
@@ -154,7 +134,7 @@ multica setup self-host
 
 ### 5b. マシン間: リバースプロキシを前に置く
 
-compose スタックは `127.0.0.1` でのみ待ち受けるため、別のマシンにあるデーモンは `http://<server-ip>:8080` に直接接続できません — そして、そうなることを望むべきでもありません。さもなければサーバーのシークレットが公開インターネットから到達可能になってしまうからです。TLS を終端し、`127.0.0.1:8080`（バックエンド）と `127.0.0.1:3000`（フロントエンド）へ転送するリバースプロキシをサーバーに置き、CLI を公開 HTTPS URL に向けてください。
+compose スタックは `127.0.0.1` でのみ待ち受けるため、別のマシンにあるデーモンは `http://<server-ip>:8080` に直接接続できません — そして、そうなることを望むべきでもありません。さもなければデフォルトの `JWT_SECRET` が公開インターネットから到達可能になってしまうからです。TLS を終端し、`127.0.0.1:8080`（バックエンド）と `127.0.0.1:3000`（フロントエンド）へ転送するリバースプロキシをサーバーに置き、CLI を公開 HTTPS URL に向けてください。
 
 ```bash
 multica setup self-host \
@@ -162,10 +142,6 @@ multica setup self-host \
   --app-url https://<your-domain>
 ```
 
-<Callout type="info">
-フラグより環境変数を使いたい場合は、対応するフラグを省略すると `setup self-host` が `MULTICA_SERVER_URL` と `MULTICA_APP_URL` を読み取ります（両方設定した場合はフラグが優先されます）。`MULTICA_SERVER_URL` は[環境変数](/environment-variables)で示される `ws://…/ws` というデーモン形式も受け付け、HTTP ベース URL に正規化します。
-</Callout>
-
 単一のホスト名でフロントエンドとバックエンドの両方を前段に置く（デーモンと Web アプリの両方に必要な WebSocket サポートを含む）最小限の Caddyfile は次のとおりです。
 
 ```nginx
@@ -196,26 +172,44 @@ multica.example.com {
 
 Cloud と同じ流れです — [Cloud クイックスタート → ステップ5-6](/cloud-quickstart#5-create-an-agent)を参照してください。
 
-<span id="7-usage-rollup-no-operator-action-required" />
+## 7. 使用量ロールアップのスケジューリング（使用量ダッシュボードに必須）
 
-## 7. 使用量ロールアップ（オペレーターの操作は不要）
-
-<Callout type="info">
-使用量 / ランタイムのダッシュボードは、`rollup_task_usage_hourly()` が埋める派生テーブル `task_usage_hourly` からデータを読み取ります。MUL-2957 以降、バックエンドは DB バックドのスケジューラー経由でこのロールアップをインプロセスで実行するようになり、`pg_cron` は不要になりました。外部 cron / systemd タイマーも推奨セットアップではなくなっています。バンドルされた `pgvector/pgvector:pg17` イメージは変更なしで動作します。
+<Callout type="warning">
+使用量 / ランタイムのダッシュボードは、`rollup_task_usage_hourly()` が埋める派生テーブル `task_usage_hourly` からデータを読み取ります。バンドルされた `pgvector/pgvector:pg17` の Postgres イメージには **`pg_cron` が含まれておらず**、バックエンドもロールアップをインプロセスで実行しません。`rollup_task_usage_hourly()` をスケジューリングするものが何もないと、生の `task_usage` 行は届き続けるのに、ダッシュボードは永遠にゼロのままになります。
 </Callout>
 
-インプロセススケジューラーは 30 秒おきにティックし、`sys_cron_executions` テーブルを介して 5 分ごとの UTC プランをクレームします。複数のバックエンドレプリカでも安全です — 一意キー `(job_name, scope_kind, scope_id, plan_time)` により、各プランで勝者は 1 つだけです。新規デプロイでは何の設定も不要です。
+サポートされているオプションのいずれか1つを選んでください — 1つあれば十分です。
 
-**互換性 — 既存の `pg_cron` 登録。** 以前 rollup を `pg_cron` ジョブとして登録していた（`SELECT cron.schedule('rollup_task_usage_hourly', '*/5 * * * *', …)`）場合でも、削除する必要はありません — SQL 関数が内部で advisory lock 4246 を保持するため、アプリのスケジューラーと `pg_cron` が二重書き込みすることはありません。冗長なエントリを削除するには:
+**オプション A — 外部 cron / systemd-timer（最もシンプル）。** 任意の帯域外スケジューラから5分ごとにロールアップを実行します。冪等でウォーターマーク駆動なので、取りこぼしたティックは追いつきます。
 
-```sql
-SELECT cron.unschedule('rollup_task_usage_hourly')
-  FROM cron.job WHERE jobname = 'rollup_task_usage_hourly';
+```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
 ```
 
-**`v0.3.4 → v0.3.5+` からのアップグレード。** 以前のリリースでは、migration 103 を適用する前にオペレーターが手動で `cmd/backfill_task_usage_hourly` を実行する必要があり、そうしないと migration の fail-closed ガードが `migrate up` を中断していました。MUL-2957 以降、これは自動化されました — migrate コマンドが migration 103 を適用する直前に冪等な月単位スライスのバックフィル（advisory lock 4246 の下）を実行してから処理を続行します。忙しい DB では `--sleep-between-slices=2s` で読み取り負荷を絞るためにスタンドアロンの backfill を実行することもできますが、もはや必須ではありません。
+**オプション B — Postgres を `pg_cron` を同梱したイメージに置き換える。** `docker-compose.selfhost.yml` の `pgvector/pgvector:pg17` を、`pgvector` と `pg_cron` の両方を備えたイメージ（`supabase/postgres`、またはカスタムビルド）に置き換え、`shared_preload_libraries=pg_cron` を設定して再起動してから、ジョブを一度登録します。
 
-完全なリファレンス（運用ノートと Kubernetes デプロイ形態を含む）は、リポジトリの [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup) にあります。
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+SELECT cron.schedule(
+  'rollup_task_usage_hourly',
+  '*/5 * * * *',
+  $$SELECT rollup_task_usage_hourly()$$
+);
+```
+
+**オプション C — まず履歴をバックフィルする（アップグレード経路）。** `v0.3.4 → v0.3.5+` へアップグレード中で、既存の `task_usage` 行がある場合、migration `103` は hourly テーブルがシードされるまで `refusing to drop legacy daily rollups: ...` とともに `migrate up` を中断します。バンドルされたバックフィルを一度実行してから、オプション A または B を設定してください。
+
+```bash
+docker compose -f docker-compose.selfhost.yml exec backend \
+  ./backfill_task_usage_hourly --sleep-between-slices=2s
+```
+
+`--sleep-between-slices=2s` は、忙しい DB での読み取り負荷を調整します。完了後、バックエンドのコンテナを再起動すると（起動時に migration が実行されます）アップグレードが完了します。
+
+完全なリファレンス — Kubernetes の `CronJob` テンプレートとアップグレード順序を含む — は、リポジトリの [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup) にあります。
 
 ## Kubernetes デプロイ（代替手段）
 
@@ -269,8 +263,8 @@ multica setup self-host \
 - **バックエンドが起動しない**: `docker compose -f docker-compose.selfhost.yml logs backend` でコンテナのログを確認してください。たいていは `.env` の不正な `DATABASE_URL` または `JWT_SECRET` が原因です
 - **認証コードが届かない**: メールバックエンドが構成されていない場合（Resend も SMTP もない）→ `docker compose logs backend` で `[DEV] Verification code` を探してください
 - **WebSocket が接続できない**: 公開デプロイでは、`FRONTEND_ORIGIN` を実際のフロントエンドのドメインに必ず設定する必要があります。[トラブルシューティング → WebSocket が接続できない](/troubleshooting#websocket-wont-connect)を参照してください
-- **使用量 / ランタイムのダッシュボードがゼロのまま**: `rollup_task_usage_hourly()` がスケジューリングされていません — 上記の [ステップ7](#7-usage-rollup-no-operator-action-required)と[トラブルシューティング → 使用量ダッシュボードがゼロと表示される](/troubleshooting#usage-dashboard-stays-at-zero)を参照してください
-- **`migrate up` が `refusing to drop legacy daily rollups` で失敗する**: `v0.3.4 → v0.3.5+` のアップグレード経路ガードです。MUL-2957 以降、migrate コマンドは migration 103 を適用する前に自動でバックフィルを実行します — [ステップ7](#7-usage-rollup-no-operator-action-required)を参照してください
+- **使用量 / ランタイムのダッシュボードがゼロのまま**: `rollup_task_usage_hourly()` がスケジューリングされていません — 上記の [ステップ7](#7-schedule-the-usage-rollup-required-for-the-usage-dashboard)と[トラブルシューティング → 使用量ダッシュボードがゼロと表示される](/troubleshooting#usage-dashboard-stays-at-zero)を参照してください
+- **`migrate up` が `refusing to drop legacy daily rollups` で失敗する**: `v0.3.4 → v0.3.5+` のアップグレード経路ガードです。まず `backfill_task_usage_hourly` を実行してください — [ステップ7 → オプション C](#7-schedule-the-usage-rollup-required-for-the-usage-dashboard)を参照してください
 
 ## 次のステップ
 

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

@@ -30,7 +30,7 @@ make selfhost
 
 `make selfhost`는 다음을 수행합니다.
 
-1. `.env`가 없으면 `.env.example`로부터 생성하며 **무작위 JWT_SECRET과 Postgres 비밀번호**를 함께 만듭니다
+1. `.env`가 없으면 `.env.example`로부터 생성하며 **무작위 JWT_SECRET**을 함께 만듭니다
 2. 공식 Docker 이미지(PostgreSQL, Multica backend, Multica frontend)를 받아옵니다
 3. `docker-compose.selfhost.yml`을 사용해 모든 서비스를 시작합니다
 4. 백엔드의 `/health` 엔드포인트가 준비될 때까지 기다립니다
@@ -49,7 +49,7 @@ make selfhost
 - **백엔드**: [http://localhost:8080](http://localhost:8080)
 
 <Callout type="info">
-**포트는 `127.0.0.1`에서만 수신합니다.** `docker-compose.selfhost.yml`은 공개된 모든 포트를 loopback에 바인딩합니다 — `ss -tlnp`에서는 `0.0.0.0:8080`이 보이지 않으며, 설계상 다른 기기에서는 서비스에 접근할 수 없습니다. 서버 시크릿과 Postgres 자격 증명이 공개 인터넷에 노출되어서는 절대 안 됩니다. 기기 간 접근이 필요하면 TLS를 종료하는 리버스 프록시를 스택 앞에 두세요 — [5b단계 — 기기 간: 리버스 프록시를 앞에 두기](#5b-cross-machine-front-with-a-reverse-proxy)를 참고하세요.
+**포트는 `127.0.0.1`에서만 수신합니다.** `docker-compose.selfhost.yml`은 공개된 모든 포트를 loopback에 바인딩합니다 — `ss -tlnp`에서는 `0.0.0.0:8080`이 보이지 않으며, 설계상 다른 기기에서는 서비스에 접근할 수 없습니다. 기본 `JWT_SECRET`과 Postgres 자격 증명이 공개 인터넷에 노출되어서는 절대 안 됩니다. 기기 간 접근이 필요하면 TLS를 종료하는 리버스 프록시를 스택 앞에 두세요 — [5b단계 — 기기 간: 리버스 프록시를 앞에 두기](#5b-cross-machine-front-with-a-reverse-proxy)를 참고하세요.
 </Callout>
 
 ## 2. 중요: 프로덕션 안전 설정 유지하기
@@ -81,7 +81,7 @@ make selfhost
 
 **옵션 B — SMTP relay(내부 네트워크 / 온프레미스):**
 
-배포 환경이 `api.resend.com`에 접근할 수 없거나, 이미 내부 메일 릴레이(Microsoft Exchange, Postfix, 온프레미스 SendGrid 등)가 있는 경우에 사용하세요. 둘 다 설정된 경우 `SMTP_HOST`가 Resend보다 우선하므로, 인증 및 초대 메일이 내부 릴레이에 머무릅니다. STARTTLS는 광고될 때 자동으로 업그레이드됩니다. `465` 포트(SMTPS / 암묵적 TLS)는 연결 직후의 TLS 핸드셰이크를 자동으로 활성화하며, `SMTP_TLS=implicit`(별칭: `smtps`, `ssl`)는 비표준 SMTPS 포트에서 강제로 활성화합니다.
+배포 환경이 `api.resend.com`에 접근할 수 없거나, 이미 내부 메일 릴레이(Microsoft Exchange, Postfix, 온프레미스 SendGrid 등)가 있는 경우에 사용하세요. 둘 다 설정된 경우 `SMTP_HOST`가 Resend보다 우선하므로, 인증 및 초대 메일이 내부 릴레이에 머무릅니다. 465 포트(SMTPS / 암묵적 TLS)는 현재 지원하지 않습니다 — 25 또는 587을 사용하세요.
 
 **익명 Exchange 내부 릴레이(포트 25)** — 호스트가 IP로 신뢰되며 자격 증명 없이 제출하는 경우:
 
@@ -105,26 +105,6 @@ SMTP_TLS_INSECURE=false        # 비공개 CA / 자체 서명 인증서일 때
 RESEND_FROM_EMAIL=noreply@yourdomain.com
 ```
 
-**암묵적 TLS / SMTPS(포트 465)** — STARTTLS를 광고하지 않는 알리바바 클라우드 / 텐센트 기업 메일 같은 제공자용. 포트 `465`는 암묵적 TLS를 자동으로 활성화하므로, 여기서 `SMTP_TLS`는 생략할 수 있습니다:
-
-```bash
-SMTP_HOST=smtp.qiye.aliyun.com
-SMTP_PORT=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
-```
-
-공개 IP에서 보내는 기본 `localhost` greeting을 거부하는 **엄격한 공개 relay(예: Google Workspace `smtp-relay.gmail.com`)** 의 경우, relay가 기대하는 FQDN으로 `SMTP_EHLO_NAME`을 설정하세요 — 그렇지 않으면 연결이 끊기고, 이는 이후 명령에서 불투명한 `EOF`로 나타납니다. 기본값은 컨테이너 호스트명이며, 보통 유효한 FQDN이 아닙니다:
-
-```bash
-SMTP_HOST=smtp-relay.gmail.com
-SMTP_PORT=587
-SMTP_EHLO_NAME=mail.yourdomain.com   # relay가 받아들이는 FQDN; 기본값은 (FQDN이 아닌) 컨테이너 호스트명
-RESEND_FROM_EMAIL=noreply@yourdomain.com
-```
-
 그런 다음 재시작합니다: `docker compose -f docker-compose.selfhost.yml restart backend`. 재시작 시 백엔드는 어떤 제공자를 선택했는지 출력합니다(`EmailService: SMTP relay …` / `Resend API` / `DEV mode`) — 자격 증명은 절대 로그에 남지 않으므로, 이 줄은 도움을 요청할 때 공유해도 안전합니다.
 
 추가 인증 구성(OAuth, 가입 허용 목록)과 전체 SMTP 변수 레퍼런스는 [인증 설정](/auth-setup)과 [환경 변수 → 이메일](/environment-variables#email-configuration)을 참고하세요.
@@ -154,7 +134,7 @@ multica setup self-host
 
 ### 5b. 기기 간: 리버스 프록시를 앞에 두기
 
-compose 스택은 `127.0.0.1`에서만 수신하므로, 다른 기기에 있는 데몬은 `http://<server-ip>:8080`에 직접 연결할 수 없습니다 — 그리고 그렇게 되기를 원해서도 안 됩니다. 그렇지 않으면 서버 시크릿이 공개 인터넷에서 접근 가능해지기 때문입니다. 서버에 TLS를 종료하고 `127.0.0.1:8080`(백엔드)과 `127.0.0.1:3000`(프런트엔드)으로 전달하는 리버스 프록시를 두고, CLI를 공개 HTTPS URL로 연결하세요.
+compose 스택은 `127.0.0.1`에서만 수신하므로, 다른 기기에 있는 데몬은 `http://<server-ip>:8080`에 직접 연결할 수 없습니다 — 그리고 그렇게 되기를 원해서도 안 됩니다. 그렇지 않으면 기본 `JWT_SECRET`이 공개 인터넷에서 접근 가능해지기 때문입니다. 서버에 TLS를 종료하고 `127.0.0.1:8080`(백엔드)과 `127.0.0.1:3000`(프런트엔드)으로 전달하는 리버스 프록시를 두고, CLI를 공개 HTTPS URL로 연결하세요.
 
 ```bash
 multica setup self-host \
@@ -162,10 +142,6 @@ multica setup self-host \
   --app-url https://<your-domain>
 ```
 
-<Callout type="info">
-플래그 대신 환경 변수를 선호한다면, 해당 플래그를 생략할 때 `setup self-host`가 `MULTICA_SERVER_URL`과 `MULTICA_APP_URL`을 읽습니다(둘 다 설정하면 플래그가 우선합니다). `MULTICA_SERVER_URL`은 [환경 변수](/environment-variables)에 나오는 `ws://…/ws` 데몬 형식도 허용하며 HTTP 기본 URL로 정규화합니다.
-</Callout>
-
 단일 호스트네임에서 프런트엔드와 백엔드를 모두 앞단에 두는(데몬과 웹 앱 모두에 필요한 WebSocket 지원 포함) 최소 Caddyfile은 다음과 같습니다.
 
 ```nginx
@@ -196,26 +172,44 @@ multica.example.com {
 
 Cloud와 동일한 흐름입니다 — [Cloud 빠른 시작 → 5-6단계](/cloud-quickstart#5-create-an-agent)를 참고하세요.
 
-<span id="7-usage-rollup-no-operator-action-required" />
+## 7. 사용량 롤업 스케줄링(사용량 대시보드에 필수)
 
-## 7. 사용량 롤업(운영자 작업 불필요)
-
-<Callout type="info">
-사용량 / 런타임 대시보드는 `rollup_task_usage_hourly()`가 채우는 파생 테이블 `task_usage_hourly`에서 데이터를 읽습니다. MUL-2957부터 백엔드는 DB 기반 스케줄러를 통해 인프로세스로 이 롤업을 실행하므로 더 이상 `pg_cron`이 필요하지 않으며, 외부 cron / systemd 타이머도 권장 설정이 아닙니다. 번들된 `pgvector/pgvector:pg17` 이미지가 변경 없이 동작합니다.
+<Callout type="warning">
+사용량 / 런타임 대시보드는 `rollup_task_usage_hourly()`가 채우는 파생 테이블 `task_usage_hourly`에서 데이터를 읽습니다. 번들된 `pgvector/pgvector:pg17` Postgres 이미지에는 **`pg_cron`이 포함되어 있지 않으며**, 백엔드도 롤업을 인프로세스로 실행하지 않습니다. `rollup_task_usage_hourly()`를 스케줄링하는 것이 없으면, 원시 `task_usage` 행은 계속 들어오는데 대시보드는 영원히 0에 머무릅니다.
 </Callout>
 
-인프로세스 스케줄러는 30초마다 틱하면서 `sys_cron_executions` 테이블을 통해 5분 단위 UTC 플랜을 클레임합니다. 백엔드 레플리카가 여러 개여도 안전합니다 — 고유 키 `(job_name, scope_kind, scope_id, plan_time)` 덕분에 각 플랜에서 단 하나만이 승자가 됩니다. 신규 배포에는 어떤 설정도 필요 없습니다.
+지원되는 옵션 중 하나를 고르세요 — 하나만 있으면 됩니다.
 
-**호환성 — 기존 `pg_cron` 등록.** 이전에 rollup을 `pg_cron` 잡으로 등록했었다면(`SELECT cron.schedule('rollup_task_usage_hourly', '*/5 * * * *', …)`) 굳이 제거할 필요는 없습니다 — SQL 함수가 내부적으로 advisory lock 4246을 잡기 때문에 앱 스케줄러와 `pg_cron`이 이중 쓰기를 할 수 없습니다. 중복 항목을 제거하려면:
+**옵션 A — 외부 cron / systemd-timer(가장 간단함).** 임의의 외부 스케줄러에서 5분마다 롤업을 실행합니다. 멱등하고 워터마크 기반이므로, 놓친 틱은 따라잡습니다.
 
-```sql
-SELECT cron.unschedule('rollup_task_usage_hourly')
-  FROM cron.job WHERE jobname = 'rollup_task_usage_hourly';
+```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
 ```
 
-**`v0.3.4 → v0.3.5+` 업그레이드.** 이전 릴리스에서는 migration 103을 적용하기 전에 운영자가 직접 `cmd/backfill_task_usage_hourly`를 실행해야 했고, 그러지 않으면 fail-closed 가드가 `migrate up`을 중단했습니다. MUL-2957부터 이 작업은 자동입니다 — migrate 명령이 migration 103을 적용하기 직전에(advisory lock 4246 보호 아래에서) 멱등한 월별 슬라이스 백필을 실행한 뒤 계속 진행합니다. 바쁜 DB에서는 여전히 `--sleep-between-slices=2s`로 읽기 부하를 조절하기 위해 스탠드얼론 backfill을 실행할 수 있지만 더 이상 필수는 아닙니다.
+**옵션 B — Postgres를 `pg_cron`이 포함된 이미지로 교체.** `docker-compose.selfhost.yml`의 `pgvector/pgvector:pg17`을 `pgvector`와 `pg_cron`을 모두 갖춘 이미지(`supabase/postgres` 또는 커스텀 빌드)로 교체하고, `shared_preload_libraries=pg_cron`을 설정한 뒤 재시작하고, 작업을 한 번 등록합니다.
 
-전체 레퍼런스(운영 노트와 Kubernetes 배포 형태 포함)는 저장소의 [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup)에 있습니다.
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+SELECT cron.schedule(
+  'rollup_task_usage_hourly',
+  '*/5 * * * *',
+  $$SELECT rollup_task_usage_hourly()$$
+);
+```
+
+**옵션 C — 먼저 히스토리 백필(업그레이드 경로).** `v0.3.4 → v0.3.5+`로 업그레이드하는 중이고 기존 `task_usage` 행이 있다면, migration `103`이 hourly 테이블이 시드될 때까지 `refusing to drop legacy daily rollups: ...`와 함께 `migrate up`을 중단합니다. 번들된 백필을 한 번 실행한 다음, 옵션 A 또는 B를 설정하세요.
+
+```bash
+docker compose -f docker-compose.selfhost.yml exec backend \
+  ./backfill_task_usage_hourly --sleep-between-slices=2s
+```
+
+`--sleep-between-slices=2s`는 바쁜 DB에서 읽기 부하를 조절합니다. 완료된 후 백엔드 컨테이너를 재시작하면(시작 시 migration이 실행됨) 업그레이드가 완료됩니다.
+
+전체 레퍼런스 — Kubernetes `CronJob` 템플릿과 업그레이드 순서 포함 — 는 저장소의 [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup)에 있습니다.
 
 ## Kubernetes 배포(대체 방안)
 
@@ -269,8 +263,8 @@ multica setup self-host \
 - **백엔드가 시작되지 않음**: `docker compose -f docker-compose.selfhost.yml logs backend`로 컨테이너 로그를 확인하세요. 보통 `.env`의 잘못된 `DATABASE_URL` 또는 `JWT_SECRET`이 원인입니다
 - **인증 코드를 받지 못함**: 이메일 백엔드가 구성되지 않은 경우(Resend도 SMTP도 없음) → `docker compose logs backend`에서 `[DEV] Verification code`를 찾으세요
 - **WebSocket이 연결되지 않음**: 공개 배포에서는 반드시 `FRONTEND_ORIGIN`을 실제 프런트엔드 도메인으로 설정해야 합니다. [문제 해결 → WebSocket이 연결되지 않음](/troubleshooting#websocket-wont-connect)을 참고하세요
-- **사용량 / 런타임 대시보드가 0에 머무름**: `rollup_task_usage_hourly()`가 스케줄링되지 않고 있습니다 — 위의 [7단계](#7-usage-rollup-no-operator-action-required)와 [문제 해결 → 사용량 대시보드가 0으로 표시됨](/troubleshooting#usage-dashboard-stays-at-zero)을 참고하세요
-- **`migrate up`이 `refusing to drop legacy daily rollups`로 실패함**: `v0.3.4 → v0.3.5+` 업그레이드 경로 가드입니다. MUL-2957부터 migrate 명령이 migration 103을 적용하기 전에 백필을 자동으로 실행합니다 — [7단계](#7-usage-rollup-no-operator-action-required)를 참고하세요
+- **사용량 / 런타임 대시보드가 0에 머무름**: `rollup_task_usage_hourly()`가 스케줄링되지 않고 있습니다 — 위의 [7단계](#7-schedule-the-usage-rollup-required-for-the-usage-dashboard)와 [문제 해결 → 사용량 대시보드가 0으로 표시됨](/troubleshooting#usage-dashboard-stays-at-zero)을 참고하세요
+- **`migrate up`이 `refusing to drop legacy daily rollups`로 실패함**: `v0.3.4 → v0.3.5+` 업그레이드 경로 가드입니다. 먼저 `backfill_task_usage_hourly`를 실행하세요 — [7단계 → 옵션 C](#7-schedule-the-usage-rollup-required-for-the-usage-dashboard)를 참고하세요
 
 ## 다음 단계
 

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

@@ -30,7 +30,7 @@ make selfhost
 
 `make selfhost` will:
 
-1. Generate a `.env` from `.env.example` if missing, with a **random JWT_SECRET and Postgres password**
+1. Generate a `.env` from `.env.example` if missing, with a **random JWT_SECRET**
 2. Pull the official Docker images (PostgreSQL, Multica backend, Multica frontend)
 3. Bring up every service using `docker-compose.selfhost.yml`
 4. Wait until the backend's `/health` endpoint is ready
@@ -50,7 +50,7 @@ Once it's up:
 - **Backend**: [http://localhost:8080](http://localhost:8080)
 
 <Callout type="info">
-**Ports listen on `127.0.0.1` only.** `docker-compose.selfhost.yml` binds every published port to loopback — `ss -tlnp` will not show `0.0.0.0:8080`, and the services are unreachable from other machines by design. Secrets and Postgres credentials must never sit on the open internet. For cross-machine access, front the stack with a reverse proxy that terminates TLS — see [Step 5b — Cross-machine: front with a reverse proxy](#5b-cross-machine-front-with-a-reverse-proxy).
+**Ports listen on `127.0.0.1` only.** `docker-compose.selfhost.yml` binds every published port to loopback — `ss -tlnp` will not show `0.0.0.0:8080`, and the services are unreachable from other machines by design. The default `JWT_SECRET` and Postgres credentials must never sit on the open internet. For cross-machine access, front the stack with a reverse proxy that terminates TLS — see [Step 5b — Cross-machine: front with a reverse proxy](#5b-cross-machine-front-with-a-reverse-proxy).
 </Callout>
 
 ## 2. Important: keep production safety on
@@ -117,15 +117,6 @@ SMTP_TLS=implicit              # optional on 465; required on a non-standard SMT
 RESEND_FROM_EMAIL=noreply@yourdomain.com
 ```
 
-For **strict public relays (e.g. Google Workspace `smtp-relay.gmail.com`)** that reject the default `localhost` greeting from a public IP, set `SMTP_EHLO_NAME` to the FQDN the relay expects — otherwise the connection is dropped and surfaces as an opaque `EOF` on a later command. It defaults to the container hostname, which is usually not a valid FQDN:
-
-```bash
-SMTP_HOST=smtp-relay.gmail.com
-SMTP_PORT=587
-SMTP_EHLO_NAME=mail.yourdomain.com   # FQDN the relay accepts; defaults to the (non-FQDN) container hostname
-RESEND_FROM_EMAIL=noreply@yourdomain.com
-```
-
 Then restart: `docker compose -f docker-compose.selfhost.yml restart backend`. On restart, the backend prints which provider it picked and the negotiated TLS mode (`EmailService: SMTP relay <host>:<port> (starttls|implicit-tls) from=…` / `Resend API` / `DEV mode`) — credentials are never logged, so this line is safe to share when asking for help.
 
 For more auth configuration (OAuth, signup allowlist) and the full SMTP variable reference, see [Auth setup](/auth-setup) and [Environment variables → Email](/environment-variables#email-configuration).
@@ -155,7 +146,7 @@ That points the CLI at `http://localhost:8080` (backend) and `http://localhost:3
 
 ### 5b. Cross-machine: front with a reverse proxy
 
-Because the compose stack only listens on `127.0.0.1`, a daemon on a different machine cannot reach `http://<server-ip>:8080` directly — and you do not want it to, since server secrets would otherwise be reachable from the open internet. Put a reverse proxy on the server that terminates TLS and forwards to `127.0.0.1:8080` (backend) and `127.0.0.1:3000` (frontend), then point the CLI at the public HTTPS URL:
+Because the compose stack only listens on `127.0.0.1`, a daemon on a different machine cannot reach `http://<server-ip>:8080` directly — and you do not want it to, since the default `JWT_SECRET` would otherwise be reachable from the open internet. Put a reverse proxy on the server that terminates TLS and forwards to `127.0.0.1:8080` (backend) and `127.0.0.1:3000` (frontend), then point the CLI at the public HTTPS URL:
 
 ```bash
 multica setup self-host \
@@ -163,10 +154,6 @@ multica setup self-host \
   --app-url https://<your-domain>
 ```
 
-<Callout type="info">
-Prefer environment variables over flags? `setup self-host` reads `MULTICA_SERVER_URL` and `MULTICA_APP_URL` when the matching flag is omitted — a flag still takes precedence over the env var. `MULTICA_SERVER_URL` also accepts the `ws://…/ws` daemon form from [Environment variables](/environment-variables) and normalizes it to the HTTP base.
-</Callout>
-
 A minimal Caddyfile that fronts both the frontend and the backend (with WebSocket support, which the daemon and the web app both need) on a single hostname:
 
 ```nginx
@@ -197,24 +184,44 @@ After bringing the proxy up, set `FRONTEND_ORIGIN=https://multica.example.com` i
 
 Same flow as Cloud — see [Cloud quickstart → Steps 5-6](/cloud-quickstart#5-create-an-agent).
 
-## 7. Usage rollup (no operator action required)
+## 7. Schedule the usage rollup (required for the Usage dashboard)
 
-<Callout type="info">
-The Usage / Runtime dashboards read from a derived `task_usage_hourly` table populated by `rollup_task_usage_hourly()`. As of MUL-2957 the backend runs this rollup in-process via the DB-backed scheduler — `pg_cron` is no longer required, and external cron / systemd timers are no longer the recommended setup. The bundled `pgvector/pgvector:pg17` image works without changes.
+<Callout type="warning">
+The Usage / Runtime dashboards read from a derived `task_usage_hourly` table populated by `rollup_task_usage_hourly()`. The bundled `pgvector/pgvector:pg17` Postgres image **does not include `pg_cron`**, and the backend does not run the rollup in-process either. If nothing schedules `rollup_task_usage_hourly()`, raw `task_usage` rows keep arriving while the dashboard stays at zero forever.
 </Callout>
 
-The in-process scheduler ticks every 30 seconds and claims a 5-minute UTC plan via the `sys_cron_executions` table. Multiple backend replicas are safe — the unique key `(job_name, scope_kind, scope_id, plan_time)` means only one wins each plan. No setup is needed for new deployments.
+Pick one of the supported options — only one is needed.
 
-**Compatibility — existing `pg_cron` registrations.** If you previously registered the rollup as a `pg_cron` job (`SELECT cron.schedule('rollup_task_usage_hourly', '*/5 * * * *', …)`), you do not need to remove it — the SQL function holds advisory lock 4246 internally, so the app scheduler and `pg_cron` cannot double-write. To drop the redundant entry:
+**Option A — External cron / systemd-timer (simplest).** Run the rollup every 5 minutes from any out-of-band scheduler. It's idempotent and watermark-driven, so missed ticks catch up:
 
-```sql
-SELECT cron.unschedule('rollup_task_usage_hourly')
-  FROM cron.job WHERE jobname = 'rollup_task_usage_hourly';
+```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
 ```
 
-**Upgrade from `v0.3.4 → v0.3.5+`.** The previous release asked operators to run `cmd/backfill_task_usage_hourly` manually before applying migration 103, otherwise the migration's fail-closed guard would abort `migrate up`. As of MUL-2957 this is automatic: the migrate command runs an idempotent monthly-slice backfill (under advisory lock 4246) immediately before applying migration 103, then continues. You may still run the standalone backfill on a busy DB to throttle read pressure with `--sleep-between-slices=2s`, but it is no longer required.
+**Option B — Swap Postgres for an image that ships `pg_cron`.** Replace `pgvector/pgvector:pg17` in `docker-compose.selfhost.yml` with an image that has both `pgvector` and `pg_cron` (`supabase/postgres`, or a custom build), set `shared_preload_libraries=pg_cron`, restart, then register the job once:
 
-Full reference — including operations notes and the Kubernetes deployment shape — lives in the repo's [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup).
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+SELECT cron.schedule(
+  'rollup_task_usage_hourly',
+  '*/5 * * * *',
+  $$SELECT rollup_task_usage_hourly()$$
+);
+```
+
+**Option C — Backfill history first (upgrade path).** If you're upgrading from `v0.3.4 → v0.3.5+` and have existing `task_usage` rows, migration `103` will abort `migrate up` with `refusing to drop legacy daily rollups: ...` until the hourly table is seeded. Run the bundled backfill once, then set up Option A or B:
+
+```bash
+docker compose -f docker-compose.selfhost.yml exec backend \
+  ./backfill_task_usage_hourly --sleep-between-slices=2s
+```
+
+`--sleep-between-slices=2s` throttles read pressure on a busy DB. After it finishes, restart the backend container (migrations run on startup) and the upgrade completes.
+
+Full reference — including the Kubernetes `CronJob` template and the upgrade order — lives in the repo's [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup).
 
 ## Kubernetes deployment (alternative)
 
@@ -268,8 +275,8 @@ The full reference — three login modes, the `backend` ExternalName workaround
 - **Backend won't start**: check container logs with `docker compose -f docker-compose.selfhost.yml logs backend`; usually it's a bad `DATABASE_URL` or `JWT_SECRET` in `.env`
 - **Verification code not received**: no email backend is configured (neither Resend nor SMTP) → look for `[DEV] Verification code` in `docker compose logs backend`
 - **WebSocket won't connect**: for public deployments you must set `FRONTEND_ORIGIN` to your real frontend domain; see [Troubleshooting → WebSocket won't connect](/troubleshooting#websocket-wont-connect)
-- **Usage / Runtime dashboard stays at zero**: `rollup_task_usage_hourly()` isn't being scheduled — see [Step 7](#7-usage-rollup-no-operator-action-required) above and [Troubleshooting → Usage dashboard shows zero](/troubleshooting#usage-dashboard-stays-at-zero)
-- **`migrate up` fails with `refusing to drop legacy daily rollups`**: upgrade-path guard from `v0.3.4 → v0.3.5+`. As of MUL-2957 the migrate command runs the backfill automatically before applying migration 103 — see [Step 7](#7-usage-rollup-no-operator-action-required)
+- **Usage / Runtime dashboard stays at zero**: `rollup_task_usage_hourly()` isn't being scheduled — see [Step 7](#7-schedule-the-usage-rollup-required-for-the-usage-dashboard) above and [Troubleshooting → Usage dashboard shows zero](/troubleshooting#usage-dashboard-stays-at-zero)
+- **`migrate up` fails with `refusing to drop legacy daily rollups`**: upgrade-path guard from `v0.3.4 → v0.3.5+`. Run `backfill_task_usage_hourly` first — see [Step 7 → Option C](#7-schedule-the-usage-rollup-required-for-the-usage-dashboard)
 
 ## Next steps
 

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

@@ -30,7 +30,7 @@ make selfhost
 
 `make selfhost` 会：
 
-1. 如果没有 `.env` 文件，从 `.env.example` 自动生成一份，并**生成随机 JWT_SECRET 和 Postgres 密码**
+1. 如果没有 `.env` 文件，从 `.env.example` 自动生成一份并**生成随机 JWT_SECRET**
 2. 拉取官方 Docker 镜像（PostgreSQL、Multica backend、Multica frontend）
 3. 用 `docker-compose.selfhost.yml` 启动全部服务
 4. 等后端 `/health` 端点准备就绪
@@ -49,7 +49,7 @@ make selfhost
 - **后端**：[http://localhost:8080](http://localhost:8080)
 
 <Callout type="info">
-**所有端口只监听 `127.0.0.1`。** `docker-compose.selfhost.yml` 把每个 publish 出来的端口都绑到 loopback —— `ss -tlnp` 不会看到 `0.0.0.0:8080`，外网/其它机器默认根本连不上。这是为了避免服务密钥和 Postgres 凭据被直接暴露到公网。要做跨机访问，请用反向代理在前面终结 TLS，详见下方 [Step 5b —— 跨机访问：用反向代理把服务挡在前面](#5b-跨机访问用反向代理把服务挡在前面)。
+**所有端口只监听 `127.0.0.1`。** `docker-compose.selfhost.yml` 把每个 publish 出来的端口都绑到 loopback —— `ss -tlnp` 不会看到 `0.0.0.0:8080`，外网/其它机器默认根本连不上。这是为了避免默认 `JWT_SECRET` 和 Postgres 凭据被直接暴露到公网。要做跨机访问，请用反向代理在前面终结 TLS，详见下方 [Step 5b —— 跨机访问：用反向代理把服务挡在前面](#5b-跨机访问用反向代理把服务挡在前面)。
 </Callout>
 
 ## 2. 重要：保持生产安全配置
@@ -116,15 +116,6 @@ SMTP_TLS=implicit              # 465 上可省略；非标准 SMTPS 端口上必
 RESEND_FROM_EMAIL=noreply@yourdomain.com
 ```
 
-对于**拒绝来自公网 IP 的默认 `localhost` 问候的严格公网 relay（例如 Google Workspace `smtp-relay.gmail.com`）**，把 `SMTP_EHLO_NAME` 设成 relay 期望的 FQDN——否则连接会被直接断开，并在后续某条命令上表现为一个不知所云的 `EOF`。它默认取容器主机名，而后者通常不是合法的 FQDN：
-
-```bash
-SMTP_HOST=smtp-relay.gmail.com
-SMTP_PORT=587
-SMTP_EHLO_NAME=mail.yourdomain.com   # relay 接受的 FQDN；默认取（非 FQDN 的）容器主机名
-RESEND_FROM_EMAIL=noreply@yourdomain.com
-```
-
 之后重启：`docker compose -f docker-compose.selfhost.yml restart backend`。重启时 backend 会打印当前选择的 provider 和协商出的 TLS 模式（`EmailService: SMTP relay <host>:<port> (starttls|implicit-tls) from=…` / `Resend API` / `DEV mode`），密码不会被记录，所以这行截图给同事是安全的。
 
 更多 auth 配置（OAuth、注册白名单）以及完整的 SMTP 变量说明见 [登录与注册配置](/auth-setup) 和 [环境变量](/environment-variables)。
@@ -154,7 +145,7 @@ multica setup self-host
 
 ### 5b. 跨机访问：用反向代理把服务挡在前面
 
-因为 compose 默认只监听 `127.0.0.1`，从别的机器跑的 daemon 是连不上 `http://<server-ip>:8080` 的——这也是有意为之，否则服务密钥会直接暴露在公网。正确做法是在 server 上跑一个反向代理（Caddy / nginx / Cloudflare Tunnel），由它终结 TLS，再反代到 `127.0.0.1:8080`（backend）和 `127.0.0.1:3000`（frontend）。然后把 CLI 指到公开的 HTTPS 域名：
+因为 compose 默认只监听 `127.0.0.1`，从别的机器跑的 daemon 是连不上 `http://<server-ip>:8080` 的——这也是有意为之，否则默认 `JWT_SECRET` 等于直接暴露在公网。正确做法是在 server 上跑一个反向代理（Caddy / nginx / Cloudflare Tunnel），由它终结 TLS，再反代到 `127.0.0.1:8080`（backend）和 `127.0.0.1:3000`（frontend）。然后把 CLI 指到公开的 HTTPS 域名：
 
 ```bash
 multica setup self-host \
@@ -162,10 +153,6 @@ multica setup self-host \
   --app-url https://<你的域名>
 ```
 
-<Callout type="info">
-更习惯用环境变量？省略对应 flag 时，`setup self-host` 会读取 `MULTICA_SERVER_URL` 和 `MULTICA_APP_URL`（同时设置时 flag 优先）。`MULTICA_SERVER_URL` 也接受[环境变量](/environment-variables)里那种 `ws://…/ws` 的 daemon 写法，并自动归一化为 HTTP 地址。
-</Callout>
-
 最小可用的 Caddyfile，单域名同时挂前后端（带 WebSocket 转发，daemon 和网页端都依赖）：
 
 ```nginx
@@ -196,26 +183,44 @@ multica.example.com {
 
 流程和 Cloud 一样——见 [Cloud 快速上手 → 5-6 步](/cloud-quickstart#5-创建智能体)。
 
-<span id="7-usage-rollup-no-operator-action-required" />
+## 7. 调度用量汇总任务（Usage Dashboard 必需）
 
-## 7. 用量汇总（无需运维操作）
-
-<Callout type="info">
-Usage / Runtime 看板读的是派生表 `task_usage_hourly`，由 `rollup_task_usage_hourly()` 周期性填充。从 MUL-2957 起，后端通过 DB 后端的调度器在进程内运行该 rollup —— 不再需要 `pg_cron`，外部 cron / systemd timer 也不再是推荐方案。默认的 `pgvector/pgvector:pg17` 镜像无需改动即可工作。
+<Callout type="warning">
+Usage / Runtime 看板读的是派生表 `task_usage_hourly`，需要 `rollup_task_usage_hourly()` 周期性运行才能填充。**默认的 `pgvector/pgvector:pg17` 镜像不带 `pg_cron`**，后端进程内部也不会跑这个 rollup——什么都没调度的话，原始 `task_usage` 行会继续写入，但 dashboard 会一直停在 0，不会报错。
 </Callout>
 
-进程内调度器每 30 秒 tick 一次，通过 `sys_cron_executions` 表认领 5 分钟一档的 UTC plan。多 backend 副本同时跑也安全 —— 唯一键 `(job_name, scope_kind, scope_id, plan_time)` 保证每个 plan 只有一个赢家。新部署不需要任何额外配置。
+三种支持路径，三选一即可。
 
-**兼容性 —— 已注册的 `pg_cron` 任务。** 如果你之前用 `pg_cron` 注册过 rollup（`SELECT cron.schedule('rollup_task_usage_hourly', '*/5 * * * *', …)`），不删也行 —— SQL 函数内部持有 advisory lock 4246，应用调度器和 `pg_cron` 不会并发双写。要清掉冗余项可以执行：
+**Option A —— 外部 cron / systemd-timer（最简单）。** 在任意外部调度器上每 5 分钟跑一次 rollup。函数是幂等的、按 watermark 推进，丢一两个 tick 下次能补上：
 
-```sql
-SELECT cron.unschedule('rollup_task_usage_hourly')
-  FROM cron.job WHERE jobname = 'rollup_task_usage_hourly';
+```bash
+# /etc/cron.d/multica-rollup —— 每 5 分钟跑一次
+*/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
 ```
 
-**从 `v0.3.4 → v0.3.5+` 升级。** 上一版要求运维在应用 migration 103 之前手动跑 `cmd/backfill_task_usage_hourly`，否则 fail-closed 守卫会中止 `migrate up`。从 MUL-2957 起这一步是自动的：migrate 命令会在应用 migration 103 之前（advisory lock 4246 保护下）运行幂等的按月切片 backfill，然后继续。在繁忙的数据库上你仍可以用 `--sleep-between-slices=2s` 跑独立 backfill 来限制读压力，但已不是必需。
+**Option B —— 换成自带 `pg_cron` 的 Postgres 镜像。** 把 `docker-compose.selfhost.yml` 里的 `pgvector/pgvector:pg17` 换成同时带 `pgvector` 和 `pg_cron` 的镜像（比如 `supabase/postgres`，或自己 build 一份），把 `shared_preload_libraries=pg_cron` 配上、重启 Postgres，然后注册一次任务：
 
-完整参考（含运维注意事项和 Kubernetes 部署形态）见仓库的 [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup)。
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+SELECT cron.schedule(
+  'rollup_task_usage_hourly',
+  '*/5 * * * *',
+  $$SELECT rollup_task_usage_hourly()$$
+);
+```
+
+**Option C —— 先回填历史（升级路径）。** 如果你是从 `v0.3.4` 升级到 `v0.3.5+` 且数据库里已经有 `task_usage` 行，migration `103` 会以 `refusing to drop legacy daily rollups: ...` 报错并中止 `migrate up`，直到 hourly 表被 seed 过。先跑一次内置的 backfill 命令，然后再配 Option A 或 Option B 让新数据持续流进来：
+
+```bash
+docker compose -f docker-compose.selfhost.yml exec backend \
+  ./backfill_task_usage_hourly --sleep-between-slices=2s
+```
+
+`--sleep-between-slices=2s` 用来在繁忙的数据库上限制读压力。回填跑完后重启后端容器（migration 在启动时自动跑），升级就能继续。
+
+完整参考（含 Kubernetes `CronJob` 模板和升级顺序）见仓库的 [`SELF_HOSTING_ADVANCED.md → Usage Dashboard Rollup`](https://github.com/multica-ai/multica/blob/main/SELF_HOSTING_ADVANCED.md#usage-dashboard-rollup)。
 
 ## Kubernetes 部署（替代方案）
 
@@ -269,8 +274,8 @@ multica setup self-host \
 - **后端起不来**：看容器日志 `docker compose -f docker-compose.selfhost.yml logs backend`；常见是 `.env` 里 `DATABASE_URL` 或 `JWT_SECRET` 有问题
 - **验证码收不到**：没配任何邮件后端（Resend 和 SMTP 都没设） → 从 `docker compose logs backend` 里找 `[DEV] Verification code`
 - **WebSocket 连不上**：公网部署必须设 `FRONTEND_ORIGIN` 成你真实的前端域名；见 [故障排查 → WebSocket 连不上](/troubleshooting#websocket-连不上)
-- **Usage / Runtime 看板一直是 0**：没人调度 `rollup_task_usage_hourly()` —— 见上面的 [第 7 步](#7-usage-rollup-no-operator-action-required) 和 [故障排查 → Usage 看板一直是 0](/troubleshooting#usage-看板一直是-0)
-- **`migrate up` 报 `refusing to drop legacy daily rollups`**：`v0.3.4 → v0.3.5+` 升级路径的 fail-closed guard。从 MUL-2957 起 migrate 命令在应用 migration 103 之前会自动跑 backfill —— 见 [第 7 步](#7-usage-rollup-no-operator-action-required)
+- **Usage / Runtime 看板一直是 0**：没人调度 `rollup_task_usage_hourly()` —— 见上面的 [第 7 步](#7-调度用量汇总任务usage-dashboard-必需) 和 [故障排查 → Usage 看板一直是 0](/troubleshooting#usage-看板一直是-0)
+- **`migrate up` 报 `refusing to drop legacy daily rollups`**：`v0.3.4 → v0.3.5+` 升级路径的 fail-closed guard。先跑 `backfill_task_usage_hourly` —— 见 [第 7 步 → Option C](#7-调度用量汇总任务usage-dashboard-必需)
 
 ## 下一步
 

apps/docs/content/docs/skills.ja.mdx

@@ -12,16 +12,10 @@ import { Callout } from "fumadocs-ui/components/callout";
 Multica は 2 つのスキルソースに対応しています。
 
 - **ワークスペーススキル** — Multica のクラウドに保存されます。エージェントに取り付けると、タスク実行時にあなたのデーモンへ同期されます。これが**チーム全体でスキルを共有する標準的な方法**です。
-- **ローカルスキル** — あなたのマシン上のディレクトリに存在します。あなたが要求すると、[デーモン](/daemon-runtimes)がマシンをスキャンし、どれをワークスペースに取り込むかを手動で選びます。デーモンは**2 つのルートを優先順位順に**確認します。まずランタイム自身のスキルディレクトリ（各 AI コーディングツールには慣例的なデフォルトパスがあります。例: Claude Code の `~/.claude/skills/`）、次にツール横断の汎用ディレクトリ `~/.agents/skills/`（Codex や Gemini CLI などのエコシステムが共有する場所）です。同じスキル名が両方に存在する場合は**プロバイダー専用ディレクトリが優先**されるため、汎用ルートは*追加の*スキルを表示するだけで、既存スキルの解決結果を変えることはありません。
+- **ローカルスキル** — あなたのマシン上のディレクトリに存在します（各 AI コーディングツールには慣例的なデフォルトパスがあります。例: Claude Code の `~/.claude/skills/`）。あなたが要求すると、[デーモン](/daemon-runtimes)がマシンをスキャンし、どれをワークスペースに取り込むかを手動で選びます。
 
 ほとんどの場合は**ワークスペーススキル**が望ましいでしょう。一度インポートすれば、すべてのチームメイトのエージェントが使えるからです。ローカルスキルは、まずローカルでテストしたい場合や、内容に機密性の高いローカル資料が含まれる場合に適しています。
 
-## リポジトリスコープのスキル
-
-リポジトリスコープのスキルは想定された挙動です。一部の AI コーディングツールは、`.claude/skills/`、`.cursor/skills/`、`.opencode/skills/`、`.agents/skills/` など、**リポジトリにコミットされたプロジェクトレベルのスキル**を検出します。Multica のタスクがそのリポジトリをチェックアウトすると、それらのファイルは作業ディレクトリに残り、基盤となるツールが自身のネイティブ探索ルールで読み込めます。そのリポジトリで使うためだけに、これらの repo skills を Multica へインポートする必要はありません。また Multica は、それらをワークスペーススキルレジストリへ自動インポートしません。
-
-プロジェクトレベルの探索に対応するツールでは、ワークスペーススキルも同じプロバイダー固有の場所へ同期されます。ワークスペーススキルが既存のリポジトリスキルディレクトリと衝突する場合、Multica はリポジトリのファイルを上書きせず、`review-helper-multica` のような兄弟名でワークスペースコピーを書き込みます。そのためツールには、調整後の名前を持つワークスペースコピーを含めて両方のスキルが見えることがあります。
-
 ## スキルをインポートする
 
 ワークスペーススキルは 4 つのソースから取得します。
@@ -60,7 +54,7 @@ GitHub や ClawHub からインポートしたスキルには、スクリプト
 - **スキル** = 構造化された**ナレッジパック**（静的なコンテンツ + 指示）。エージェントはスキルを読んで「問題 X を見たら、こう考えてこう行動する」を学びます。
 - **MCP**（Model Context Protocol）= **ツールチャネル**。エージェントは MCP を使って外部サービス（データベース、ファイルシステム、サードパーティ API）に接続し、それらを**呼び出します**。
 
-この 2 つは相互補完的です。現在の Multica では、MCP サポートは**ツールごとに実装されています**: Claude Code、Codex、Cursor、Hermes、Kimi、Kiro CLI、OpenCode、OpenClaw は `mcp_config` を使用し、他のツールはこのフィールドを受け取っても実際には使いません。MCP 専用のセクションは今後のリリースで追加される予定です。
+この 2 つは相互補完的です。現在の Multica では、MCP のサポートを**実際に使うのは Claude Code だけ**です — 他のツールは MCP 設定を受け取りはしますが、実際には使いません。MCP 専用のセクションは今後のリリースで追加される予定です。
 
 ---
 

apps/docs/content/docs/skills.ko.mdx

@@ -12,16 +12,10 @@ import { Callout } from "fumadocs-ui/components/callout";
 Multica는 두 가지 스킬 소스를 지원합니다.
 
 - **워크스페이스 스킬** — Multica 클라우드에 저장됩니다. 에이전트에 연결되면 작업 실행 시점에 여러분의 데몬으로 동기화됩니다. 이것이 **팀 전체에서 스킬을 공유하는 표준 방식**입니다.
-- **로컬 스킬** — 여러분의 기기에 있는 디렉터리에 존재합니다. 여러분이 요청하면 [데몬](/daemon-runtimes)이 기기를 스캔하고, 어떤 스킬을 워크스페이스로 가져올지 직접 고릅니다. 데몬은 **두 개의 루트를 우선순위 순서로** 확인합니다. 먼저 런타임 자체의 스킬 디렉터리(각 AI 코딩 도구마다 관례적인 기본 경로가 있습니다. 예: Claude Code의 `~/.claude/skills/`), 그다음 도구 간 공용 디렉터리 `~/.agents/skills/`(Codex, Gemini CLI 등 생태계가 공유하는 위치)입니다. 동일한 스킬 이름이 양쪽에 모두 있으면 **프로바이더 전용 디렉터리가 우선**하므로, 공용 루트는 *추가* 스킬만 노출할 뿐 기존 스킬의 해석 결과를 절대 바꾸지 않습니다.
+- **로컬 스킬** — 여러분의 기기에 있는 디렉터리에 존재합니다(각 AI 코딩 도구마다 관례적인 기본 경로가 있습니다. 예: Claude Code의 `~/.claude/skills/`). 여러분이 요청하면 [데몬](/daemon-runtimes)이 기기를 스캔하고, 어떤 스킬을 워크스페이스로 가져올지 직접 고릅니다.
 
 대부분의 경우 **워크스페이스 스킬**을 원하게 됩니다. 한 번만 가져오면 모든 팀원의 에이전트가 사용할 수 있기 때문입니다. 로컬 스킬은 먼저 로컬에서 테스트하고 싶거나, 콘텐츠에 민감한 로컬 자료가 포함된 경우에 적합합니다.
 
-## 저장소 범위 스킬
-
-저장소 범위 스킬은 의도된 동작입니다. 일부 AI 코딩 도구는 `.claude/skills/`, `.cursor/skills/`, `.opencode/skills/`, `.agents/skills/`처럼 **저장소에 커밋된 프로젝트 수준 스킬**을 탐색합니다. Multica 작업이 해당 저장소를 체크아웃하면 이 파일들은 작업 디렉터리에 남아 있고, 기반 도구가 자체 기본 탐색 규칙에 따라 읽어 들일 수 있습니다. 해당 저장소에서 사용하기 위해 이러한 repo skills를 Multica로 먼저 가져올 필요는 없습니다. Multica도 이를 워크스페이스 스킬 레지스트리로 자동 가져오지 않습니다.
-
-프로젝트 수준 탐색을 지원하는 도구에서는 워크스페이스 스킬도 같은 프로바이더 기본 위치로 동기화됩니다. 워크스페이스 스킬이 기존 저장소 스킬 디렉터리와 충돌하면, Multica는 저장소 파일을 덮어쓰지 않고 `review-helper-multica` 같은 형제 이름으로 워크스페이스 사본을 씁니다. 그러면 도구에는 조정된 이름을 가진 워크스페이스 사본을 포함해 두 스킬이 모두 보일 수 있습니다.
-
 ## 스킬 가져오기
 
 워크스페이스 스킬은 네 가지 소스에서 가져옵니다.
@@ -60,7 +54,7 @@ GitHub나 ClawHub에서 가져온 스킬에는 스크립트와 실행 가능한
 - **스킬** = 구조화된 **지식 팩**(정적 콘텐츠 + 지침). 에이전트는 스킬을 읽어 "문제 X를 만나면 이렇게 생각하고 이렇게 처리하라"를 학습합니다.
 - **MCP**(Model Context Protocol) = **도구 채널**. 에이전트는 MCP를 사용해 외부 서비스(데이터베이스, 파일 시스템, 서드파티 API)에 연결하고 이를 **호출**합니다.
 
-이 둘은 상호 보완적입니다. 현재 Multica에서 MCP 지원은 **도구별로 구현됩니다**: Claude Code, Codex, Cursor, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw는 `mcp_config`를 사용하고, 다른 도구들은 이 필드를 받더라도 실제로 사용하지 않습니다. MCP 전용 섹션은 추후 릴리스에서 추가될 예정입니다.
+이 둘은 상호 보완적입니다. 현재 Multica에서 MCP 지원은 **도구별로 구현됩니다**: Claude Code, Codex, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw는 `mcp_config`를 사용하고, 다른 도구들은 이 필드를 받더라도 실제로 사용하지 않습니다. MCP 전용 섹션은 추후 릴리스에서 추가될 예정입니다.
 
 ---
 

apps/docs/content/docs/skills.mdx

@@ -12,16 +12,10 @@ A Skill is a **knowledge pack** for an [agent](/agents) — a `SKILL.md` plus op
 Multica supports two skill sources:
 
 - **Workspace skill** — stored in Multica's cloud. Once attached to an agent, it's synced down to your daemon at task execution time. This is the **standard way to share skills across a team**.
-- **Local skill** — lives in a directory on your machine. On your request, the [daemon](/daemon-runtimes) scans your machine, and you manually pick which ones to bring into the workspace. The daemon checks **two roots, in priority order**: first the runtime's own skill directory (each AI coding tool has a conventional default path, e.g. Claude Code's `~/.claude/skills/`), then the cross-tool universal directory `~/.agents/skills/` — a shared location used by ecosystems like Codex and Gemini CLI. When the same skill name exists in both, the **provider-specific directory wins**, so the universal root only ever surfaces *additional* skills and never changes what an existing skill resolves to.
+- **Local skill** — lives in a directory on your machine (each AI coding tool has a conventional default path, e.g. Claude Code's `~/.claude/skills/`). On your request, the [daemon](/daemon-runtimes) scans your machine, and you manually pick which ones to bring into the workspace.
 
 Most of the time you want **workspace skills**: import once, every teammate's agent can use it. Local skills are a fit when you want to test locally first, or when the content involves sensitive local material.
 
-## Repository-scoped skills
-
-Repo-scoped skills are expected behavior. Some AI coding tools discover **project-level skills committed inside a repository**, such as `.claude/skills/`, `.cursor/skills/`, `.opencode/skills/`, or `.agents/skills/`. When a Multica task checks out that repository, those files remain in the workdir and the underlying tool can load them through its native discovery rules. You do **not** need to import those repo skills into Multica just to use them in that repo; Multica does **not** import them into the workspace skill registry automatically.
-
-Workspace skills still sync into the same provider-native location for tools that support project-level discovery. If a workspace skill would collide with an existing repo skill directory, Multica writes the workspace copy to a sibling name such as `review-helper-multica` instead of overwriting the repo's files. The tool may then see both skills, with the workspace copy carrying the adjusted name.
-
 ## Importing a skill
 
 Workspace skills come from four sources:
@@ -60,7 +54,7 @@ Both augment what an agent can do, but in different directions:
 - **Skill** = a structured **knowledge pack** (static content + instructions). The agent reads a skill to learn "when I see problem X, here's how to think and what to do."
 - **MCP** (Model Context Protocol) = a **tool channel**. The agent uses MCP to connect to external services (databases, filesystems, third-party APIs) and **invoke** them.
 
-The two are complementary. In Multica today, MCP support is **provider-specific**: Claude Code, Codex, Cursor, Hermes, Kimi, Kiro CLI, OpenCode, and OpenClaw consume `mcp_config`; other tools receive the field but don't actually use it. A dedicated MCP section will come in a later release.
+The two are complementary. In Multica today, MCP support is **provider-specific**: Claude Code, Codex, Hermes, Kimi, Kiro CLI, OpenCode, and OpenClaw consume `mcp_config`; other tools receive the field but don't actually use it. A dedicated MCP section will come in a later release.
 
 ---
 

apps/docs/content/docs/skills.zh.mdx

@@ -12,16 +12,10 @@ Skill 是给 [智能体](/agents) 的**专业知识包**——一个 `SKILL.md`
 Multica 支持两种 Skill 来源：
 
 - **工作区 Skill（workspace skill）** —— 存在 Multica 云端。挂到智能体后，任务执行时自动同步到你本机的守护进程。这是**团队共享 Skill 的标准方式**。
-- **本机 Skill（local skill）** —— 直接存在你本机的某个目录里。[守护进程](/daemon-runtimes) 按你的请求扫描本机，发现后由你手动选入工作区。守护进程会**按优先级扫描两个根目录**：先扫该运行时自己的 skill 目录（每款 AI 编程工具有约定的默认路径，比如 Claude Code 的 `~/.claude/skills/`），再扫跨工具通用目录 `~/.agents/skills/`——这是 Codex、Gemini CLI 等生态共用的位置。当同名 skill 在两处都存在时，**provider 专用目录优先**，所以通用根目录只会*额外*带出新的 skill，绝不会改变已有 skill 的解析结果。
+- **本机 Skill（local skill）** —— 直接存在你本机的某个目录里（每款 AI 编程工具有约定的默认路径，比如 Claude Code 的 `~/.claude/skills/`）。[守护进程](/daemon-runtimes) 按你的请求扫描本机，发现后由你手动选入工作区。
 
 大多数情况用**工作区 Skill**：导入一次，团队所有成员的智能体都能用。本机 Skill 适合先在本地测试、或涉及敏感本地内容的场景。
 
-## 仓库级 Skill
-
-仓库级 Skill 是预期行为。有些 AI 编程工具会发现**提交在仓库里的项目级 Skill**，例如 `.claude/skills/`、`.cursor/skills/`、`.opencode/skills/` 或 `.agents/skills/`。当 Multica 任务检出这个仓库时，这些文件会留在工作目录里，底层工具可以按自己的原生发现规则加载它们。你不需要为了在这个仓库里使用这些 repo skills 而先把它们导入 Multica；Multica 也不会自动把它们导入工作区 Skill 注册表。
-
-对支持项目级发现的工具，工作区 Skill 也会同步到同一个 provider 原生位置。如果某个工作区 Skill 会和已有的仓库 Skill 目录冲突，Multica 会把工作区副本写到类似 `review-helper-multica` 的 sibling 名称下，而不是覆盖仓库文件。工具随后可能会同时看到两个 Skill，其中工作区副本使用调整后的名称。
-
 ## 导入 Skill
 
 工作区 Skill 有四种来源：
@@ -60,7 +54,7 @@ Skill 导入后需要**挂载到具体的智能体**才会生效。一个智能
 - **Skill** = 结构化的**知识包**（静态内容 + 指令）。智能体读 Skill 来学"遇到 X 类问题该怎么想、怎么做"。
 - **MCP**（Model Context Protocol）= **工具通道**。智能体通过 MCP 连外部服务（数据库、文件系统、第三方 API）并**调用**它们。
 
-两者可以同时用。目前 Multica 的 MCP 支持是**按工具实现**的：Claude Code、Codex、Cursor、Hermes、Kimi、Kiro CLI、OpenCode、OpenClaw 会消费 `mcp_config`；其他工具会接收到这个字段但不会实际用。MCP 的专题会在后续版本展开。
+两者可以同时用。目前 Multica 的 MCP 支持是**按工具实现**的：Claude Code、Codex、Hermes、Kimi、Kiro CLI、OpenCode、OpenClaw 会消费 `mcp_config`；其他工具会接收到这个字段但不会实际用。MCP 的专题会在后续版本展开。
 
 ---
 

apps/docs/content/docs/tasks.ja.mdx

@@ -105,7 +105,8 @@ Multica はタスク中にセッション ID を**2 回**固定します: 開始
 
 ただし、**実際にどの AI コーディングツールがこれをサポートするか**は大きく異なります。
 
-- ✅ **実際にサポート** — Antigravity, Claude Code, Codex, Copilot, Cursor, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw, Pi
+- ✅ **実際にサポート** — Antigravity, Claude Code, Copilot, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw, Pi
+- ⚠️ **コードはあるが使用不可** — Codex, Cursor
 - ❌ **サポートなし** — Gemini
 
 [プロバイダー対応表 → セッション再開](/providers#session-resumption-who-really-supports-it)を参照してください。