fix(agent): surface codex turn errors instead of reporting empty output

When codex emits `turn/completed` with `status="failed"` or a terminal
top-level `error` notification, the daemon previously treated the turn
as successfully completed, saw no accumulated text, and surfaced the
generic "codex returned empty output" — hiding the real reason (auth,
sandbox, API error, etc.).

Capture `turn.error.message` on failed turns and the `error.message`
from non-retrying top-level error notifications, then propagate them
through `Result.Error` with `finalStatus="failed"` so the daemon's
default branch reports the actual cause.

.env.example

@@ -4,23 +4,8 @@ POSTGRES_USER=multica
 POSTGRES_PASSWORD=multica
 POSTGRES_PORT=5432
 DATABASE_URL=postgres://multica:multica@localhost:5432/multica?sslmode=disable
-# Optional pgxpool tuning. Defaults are 25 / 5 per pod and are usually fine.
-# You can also set pool_max_conns / pool_min_conns as query params on
-# DATABASE_URL; env vars below take precedence over URL params.
-# DATABASE_MAX_CONNS=25
-# DATABASE_MIN_CONNS=5
 
 # Server
-# APP_ENV gates dev-only auth shortcuts (primarily the 888888 master code).
-#   - Docker self-host: docker-compose.selfhost.yml already pins APP_ENV to
-#     "production" by default, so 888888 is DISABLED — a public instance can't
-#     be logged into with any email + 888888.
-#   - Local dev (make dev): leave APP_ENV unset so 888888 works out of the box.
-#   - Docker self-host on a private network you fully control, or evaluation
-#     without Resend: set APP_ENV=development to re-enable 888888. Do NOT
-#     enable on a publicly reachable instance.
-# See SELF_HOSTING.md for the full login setup.
-APP_ENV=
 PORT=8080
 JWT_SECRET=change-me-in-production
 MULTICA_SERVER_URL=ws://localhost:8080/ws
@@ -37,8 +22,7 @@ MULTICA_CODEX_WORKDIR=
 MULTICA_CODEX_TIMEOUT=20m
 
 # Email (Resend)
-# For local/dev use, leave RESEND_API_KEY empty — codes print to stdout, and
-# master code 888888 works (only when APP_ENV != "production"; see above).
+# For local/dev use, leave RESEND_API_KEY empty — codes print to stdout, and master code 888888 works.
 # For production, set your Resend API key and change RESEND_FROM_EMAIL to a domain verified in your Resend account.
 RESEND_API_KEY=
 RESEND_FROM_EMAIL=noreply@multica.ai
@@ -56,13 +40,6 @@ CLOUDFRONT_KEY_PAIR_ID=
 CLOUDFRONT_PRIVATE_KEY_SECRET=multica/cloudfront-signing-key
 CLOUDFRONT_PRIVATE_KEY=
 CLOUDFRONT_DOMAIN=
-# COOKIE_DOMAIN — optional Domain attribute on session + CloudFront cookies.
-# Leave empty for single-host deployments (localhost, LAN IP, or a single
-# hostname) — session cookies become host-only, which is what the browser
-# wants. Only set it when the frontend and backend sit on different
-# subdomains of one registered domain (e.g. ".example.com"). Do NOT set it
-# to an IP address: RFC 6265 forbids IP literals in the cookie Domain
-# attribute and browsers silently drop such cookies.
 COOKIE_DOMAIN=
 
 # Local file storage (fallback when S3_BUCKET is not set)
@@ -86,27 +63,3 @@ NEXT_PUBLIC_WS_URL=
 # Remote API (optional) — set to proxy local frontend to a remote backend
 # Leave empty to use local backend (localhost:8080)
 # REMOTE_API_URL=https://multica-api.copilothub.ai
-
-# ==================== Self-hosting: Control Signups (fixes #930) ====================
-# Set to "false" to completely disable new user signups (recommended for private instances)
-ALLOW_SIGNUP=true
-# Must match ALLOW_SIGNUP for the UI to reflect the same signup setting.
-# Note: in typical Next.js builds, NEXT_PUBLIC_* values are baked into the client bundle,
-# so changing this usually requires rebuilding/redeploying the frontend (not just restarting the backend).
-NEXT_PUBLIC_ALLOW_SIGNUP=true
-
-# Optional: Only allow emails from these domains (comma-separated)
-ALLOWED_EMAIL_DOMAINS=
-
-# Optional: Only allow these exact email addresses (comma-separated)
-ALLOWED_EMAILS=
-
-# ==================== Analytics (PostHog) ====================
-# Product analytics events feed the acquisition → activation → expansion funnel.
-# Leave POSTHOG_API_KEY empty for local dev / self-hosted instances; the server
-# will run a no-op analytics client and ship nothing. See docs/analytics.md.
-POSTHOG_API_KEY=
-POSTHOG_HOST=https://us.i.posthog.com
-# Force the no-op client even when POSTHOG_API_KEY is set (CI / opt-out).
-ANALYTICS_DISABLED=
-

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
         run: pnpm install
 
       - name: Build, type check, and test
-        run: pnpm exec turbo build typecheck test --filter='!@multica/docs'
+        run: pnpm build && pnpm typecheck && pnpm test
 
   backend:
     runs-on: ubuntu-latest

.github/workflows/desktop-smoke.yml

@@ -1,59 +0,0 @@
-name: Desktop Smoke Build
-
-on:
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  desktop:
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-latest
-            target: linux
-          - os: windows-latest
-            target: win
-    runs-on: ${{ matrix.os }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Install rpmbuild (Linux)
-        if: matrix.target == 'linux'
-        run: sudo apt-get update && sudo apt-get install -y rpm
-
-      - name: Setup Go
-        uses: actions/setup-go@v5
-        with:
-          go-version-file: server/go.mod
-          cache-dependency-path: server/go.sum
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Package Desktop installers (${{ matrix.target }})
-        working-directory: apps/desktop
-        env:
-          CSC_IDENTITY_AUTO_DISCOVERY: "false"
-        run: node scripts/package.mjs --${{ matrix.target }} --x64 --arm64 --publish never
-
-      - name: Upload Desktop artifacts (${{ matrix.target }})
-        uses: actions/upload-artifact@v4
-        with:
-          name: desktop-${{ matrix.target }}
-          path: apps/desktop/dist
-          if-no-files-found: error

.github/workflows/release.yml

@@ -3,10 +3,7 @@ name: Release
 on:
   push:
     tags:
-      # GitHub Actions uses glob patterns here, not regex. Match versioned
-      # tags broadly at the trigger layer, then enforce strict semver below.
-      - "v*.*.*"
-      - "!v*-dirty*"
+      - "v*"
 
 permissions:
   contents: write
@@ -20,19 +17,6 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Validate tag name
-        run: |
-          tag="${GITHUB_REF_NAME}"
-          echo "Triggered by tag: $tag"
-          if [[ ! "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
-            echo "::error::Release tags must look like vX.Y.Z or vX.Y.Z-suffix; got '$tag'."
-            exit 1
-          fi
-          if [[ "$tag" == *-dirty* ]]; then
-            echo "::error::Refusing to release from dirty tag '$tag'."
-            exit 1
-          fi
-
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
@@ -50,60 +34,3 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
-
-  # Build the Desktop installers for Linux and Windows and upload them to
-  # the GitHub Release that the `release` job above just published. macOS
-  # Desktop continues to ship via the manual `release-desktop` skill so it
-  # can be signed + notarized with Apple Developer credentials that are
-  # not (yet) wired into CI.
-  desktop:
-    needs: release
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-latest
-            target: linux
-          - os: windows-latest
-            target: win
-    runs-on: ${{ matrix.os }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Install rpmbuild (Linux)
-        if: matrix.target == 'linux'
-        run: sudo apt-get update && sudo apt-get install -y rpm
-
-      - name: Setup Go
-        uses: actions/setup-go@v5
-        with:
-          go-version-file: server/go.mod
-          cache-dependency-path: server/go.sum
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Package Desktop installers (${{ matrix.target }})
-        working-directory: apps/desktop
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # electron-builder's GitHub publisher reads this:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Disable code signing on Linux/Windows for now — the public
-          # release is unsigned for these platforms, the CLI carries the
-          # trust boundary. Set CSC_LINK in repo secrets to enable
-          # Windows signing later.
-          CSC_IDENTITY_AUTO_DISCOVERY: "false"
-        run: node scripts/package.mjs --${{ matrix.target }} --x64 --arm64 --publish always

.goreleaser.yml

@@ -21,12 +21,12 @@ builds:
     goarch:
       - amd64
       - arm64
+    ignore:
+      - goos: windows
+        goarch: arm64
 
 archives:
-  # Legacy archive name kept so already-released CLIs (whose `multica update`
-  # looks for `multica_{os}_{arch}.{ext}`) can keep self-updating. Remove
-  # once those versions are no longer in use.
-  - id: legacy
+  - id: default
     formats:
       - tar.gz
     format_overrides:
@@ -34,16 +34,6 @@ archives:
         formats:
           - zip
     name_template: "{{ .ProjectName }}_{{ .Os }}_{{ .Arch }}"
-  # Versioned archive name used by current CLI / install scripts /
-  # desktop bootstrap going forward.
-  - id: versioned
-    formats:
-      - tar.gz
-    format_overrides:
-      - goos: windows
-        formats:
-          - zip
-    name_template: "{{ .ProjectName }}-cli-{{ .Version }}-{{ .Os }}-{{ .Arch }}"
 
 checksum:
   name_template: "checksums.txt"
@@ -58,8 +48,6 @@ changelog:
 
 brews:
   - name: multica
-    ids:
-      - versioned
     repository:
       owner: multica-ai
       name: homebrew-tap

CLAUDE.md

@@ -133,7 +133,6 @@ make start-worktree     # Start using .env.worktree
 - Unless the user explicitly asks for backwards compatibility, do **not** add compatibility layers, fallback paths, dual-write logic, legacy adapters, or temporary shims.
 - If a flow or API is being replaced and the product is not yet live, prefer removing the old path instead of preserving both old and new behavior.
 - Avoid broad refactors unless required by the task.
-- New global (pre-workspace) routes MUST use a single word (`/login`, `/inbox`) or a `/{noun}/{verb}` pair (`/workspaces/new`). NEVER add hyphenated word-group root routes (`/new-workspace`, `/create-team`) — they collide with common user workspace names and force endless reserved-slug audits. Reserving the noun (`workspaces`) automatically protects the entire `/workspaces/*` subtree.
 
 ### Package Boundary Rules
 
@@ -162,7 +161,7 @@ When the two apps need different behavior for the same concept (e.g., different
 When adding a new page or feature:
 
 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*.
+2. **Wire it in both apps** → add a route in `apps/web/app/` (Next.js page file) AND in the desktop router.
 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.
@@ -176,70 +175,6 @@ Both apps share the same CSS foundation from `packages/ui/styles/`.
 - **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.
 
-## 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 identity singleton
-
-`setCurrentWorkspace(slug, uuid)` in `@multica/core/platform` is the single source of truth for "which workspace is active right now". Three consumers depend on it:
-
-1. API client's `X-Workspace-Slug` header.
-2. Zustand per-workspace storage namespace.
-3. Chrome gating (`{slug && <AppSidebar />}` on desktop, similar on web).
-
-Normally set by `WorkspaceRouteLayout` when its route mounts. Critically: **unmount does NOT clear it.** Any code that leaves workspace context (leave workspace, delete workspace, force navigation to overlay) must call `setCurrentWorkspace(null, null)` explicitly — otherwise the realtime `workspace:deleted` handler races the mutation, chrome gating stays truthy while the workspace is gone from cache, and `useWorkspaceId` throws.
-
-### Workspace destructive operations
-
-Leave / Delete workspace flows must follow this order:
-
-1. Read destination from cached workspace list (no extra fetch).
-2. `setCurrentWorkspace(null, null)`.
-3. `navigation.push(destination)` — switch to next workspace or open new-workspace overlay.
-4. THEN `await mutation.mutateAsync(workspaceId)`.
-
-Reversing step 4 with steps 1–3 (mutate first, navigate after) causes a three-way race between the mutation's `onSettled` invalidate, the explicit `navigateAway`, and the realtime handler's `relocateAfterWorkspaceLoss` — all refetching the same `workspaces` query concurrently. One gets cancelled, bubbles as `CancelledError`, and triggers `window.location.assign` → full renderer reload / white screen.
-
-### 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 window-move)
-
-Every full-window desktop view (login, overlay, any page that covers the native title bar) needs a top drag strip so users can move the window. On macOS the traffic lights are hidden via `useImmersiveMode` in overlay-style contexts, so the drag strip also gives back that corner for pointer-drag.
-
-**Pattern**: flex child at top, not absolute overlay.
-
-```tsx
-<div className="fixed inset-0 z-50 flex flex-col bg-background">
-  <div className="h-12 shrink-0" style={{ WebkitAppRegion: "drag" }} />
-  <div className="flex-1 overflow-auto" style={{ WebkitAppRegion: "no-drag" }}>
-    {/* page content — interactive elements need their own "no-drag" */}
-  </div>
-</div>
-```
-
-Why flex, not absolute: the absolute-strip + `z-index` approach relies on stacking-context hit-testing, which isn't reliable for `-webkit-app-region`. A real flex row with no siblings at that pixel is unambiguous. Height matches `MainTopBar` (48px / `h-12`) for consistency.
-
-Canonical examples: `components/window-overlay.tsx`, `pages/login.tsx`.
-
-### UX vs platform chrome
-
-UX affordances (Back button, Log out button, welcome copy, invite card) belong in `packages/views/` so web and desktop render identical content. Platform chrome (drag strip, `useImmersiveMode`, tab system interaction, traffic-light accommodation) lives in desktop-only code. Violating this split always produces platform divergence — if a button exists on desktop but not on web for the same flow, it's a signal the UX escaped into platform code.
-
 ## 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.

CLI_AND_DAEMON.md

@@ -143,9 +143,6 @@ The daemon auto-detects these AI CLIs on your PATH:
 | OpenCode | `opencode` | Open-source coding agent |
 | OpenClaw | `openclaw` | Open-source coding agent |
 | Hermes | `hermes` | Nous Research coding agent |
-| Gemini | `gemini` | Google's coding agent |
-| [Pi](https://pi.dev/) | `pi` | Pi coding agent |
-| [Cursor Agent](https://cursor.com/) | `cursor-agent` | Cursor's headless coding agent |
 
 You need at least one installed. The daemon registers each detected CLI as an available runtime.
 
@@ -186,12 +183,6 @@ Agent-specific overrides:
 | `MULTICA_OPENCLAW_MODEL` | Override the OpenClaw model used |
 | `MULTICA_HERMES_PATH` | Custom path to the `hermes` binary |
 | `MULTICA_HERMES_MODEL` | Override the Hermes model used |
-| `MULTICA_GEMINI_PATH` | Custom path to the `gemini` binary |
-| `MULTICA_GEMINI_MODEL` | Override the Gemini model used |
-| `MULTICA_PI_PATH` | Custom path to the `pi` binary |
-| `MULTICA_PI_MODEL` | Override the Pi model used |
-| `MULTICA_CURSOR_PATH` | Custom path to the `cursor-agent` binary |
-| `MULTICA_CURSOR_MODEL` | Override the Cursor Agent model used |
 
 ### Self-Hosted Server
 
@@ -278,7 +269,7 @@ multica issue list --priority urgent --assignee "Agent Name"
 multica issue list --limit 20 --output json
 ```
 
-Available filters: `--status`, `--priority`, `--assignee`, `--project`, `--limit`.
+Available filters: `--status`, `--priority`, `--assignee`, `--limit`.
 
 ### Get Issue
 
@@ -293,7 +284,7 @@ multica issue get <id> --output json
 multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"
 ```
 
-Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--project`, `--due-date`.
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--due-date`.
 
 ### Update Issue
 
@@ -332,27 +323,6 @@ multica issue comment add <issue-id> --parent <comment-id> --content "Thanks!"
 multica issue comment delete <comment-id>
 ```
 
-### Subscribers
-
-```bash
-# List subscribers of an issue
-multica issue subscriber list <issue-id>
-
-# Subscribe yourself to an issue
-multica issue subscriber add <issue-id>
-
-# Subscribe another member or agent by name
-multica issue subscriber add <issue-id> --user "Lambda"
-
-# Unsubscribe yourself
-multica issue subscriber remove <issue-id>
-
-# Unsubscribe another member or agent
-multica issue subscriber remove <issue-id> --user "Lambda"
-```
-
-Subscribers receive notifications about issue activity (new comments, status changes, etc.). Without `--user`, the command acts on the caller.
-
 ### Execution History
 
 ```bash
@@ -370,70 +340,6 @@ multica issue run-messages <task-id> --since 42 --output json
 
 The `runs` command shows all past and current executions for an issue, including running tasks. The `run-messages` command shows the detailed message log (tool calls, thinking, text, errors) for a single run. Use `--since` for efficient polling of in-progress runs.
 
-## Projects
-
-Projects group related issues (e.g. a sprint, an epic, a workstream). Every project
-belongs to a workspace and can optionally have a lead (member or agent).
-
-### List Projects
-
-```bash
-multica project list
-multica project list --status in_progress
-multica project list --output json
-```
-
-Available filters: `--status`.
-
-### Get Project
-
-```bash
-multica project get <id>
-multica project get <id> --output json
-```
-
-### Create Project
-
-```bash
-multica project create --title "2026 Week 16 Sprint" --icon "🏃" --lead "Lambda"
-```
-
-Flags: `--title` (required), `--description`, `--status`, `--icon`, `--lead`.
-
-### Update Project
-
-```bash
-multica project update <id> --title "New title" --status in_progress
-multica project update <id> --lead "Lambda"
-```
-
-Flags: `--title`, `--description`, `--status`, `--icon`, `--lead`.
-
-### Change Status
-
-```bash
-multica project status <id> in_progress
-```
-
-Valid statuses: `planned`, `in_progress`, `paused`, `completed`, `cancelled`.
-
-### Delete Project
-
-```bash
-multica project delete <id>
-```
-
-### Associating Issues with Projects
-
-Use the `--project` flag on `issue create` / `issue update` to attach an issue to a
-project, or on `issue list` to filter issues by project:
-
-```bash
-multica issue create --title "Login bug" --project <project-id>
-multica issue update <issue-id> --project <project-id>
-multica issue list --project <project-id>
-```
-
 ## Setup
 
 ```bash
@@ -470,63 +376,6 @@ multica config set app_url https://app.example.com
 multica config set workspace_id <workspace-id>
 ```
 
-## Autopilot Commands
-
-Autopilots are scheduled/triggered automations that dispatch agent tasks (either by creating an issue or by running an agent directly).
-
-### List Autopilots
-
-```bash
-multica autopilot list
-multica autopilot list --status active --output json
-```
-
-### Get Autopilot Details
-
-```bash
-multica autopilot get <id>
-multica autopilot get <id> --output json   # includes triggers
-```
-
-### Create / Update / Delete
-
-```bash
-multica autopilot create \
-  --title "Nightly bug triage" \
-  --description "Scan todo issues and prioritize." \
-  --agent "Lambda" \
-  --mode create_issue
-
-multica autopilot update <id> --status paused
-multica autopilot update <id> --description "New prompt"
-multica autopilot delete <id>
-```
-
-`--mode` currently only accepts `create_issue` (creates a new issue on each run and assigns it to the agent). The server data model also defines `run_only`, but the daemon task path doesn't yet resolve a workspace for runs without an issue, so it's not exposed by the CLI. `--agent` accepts either a name or UUID.
-
-### Manual Trigger
-
-```bash
-multica autopilot trigger <id>            # Fires the autopilot once, returns the run
-```
-
-### Run History
-
-```bash
-multica autopilot runs <id>
-multica autopilot runs <id> --limit 50 --output json
-```
-
-### Schedule Triggers
-
-```bash
-multica autopilot trigger-add <autopilot-id> --cron "0 9 * * 1-5" --timezone "America/New_York"
-multica autopilot trigger-update <autopilot-id> <trigger-id> --enabled=false
-multica autopilot trigger-delete <autopilot-id> <trigger-id>
-```
-
-Only cron-based `schedule` triggers are currently exposed via the CLI. The data model also defines `webhook` and `api` kinds, but there is no server endpoint that fires them yet, so they're not surfaced here.
-
 ## Other Commands
 
 ```bash

CLI_INSTALL.md

@@ -76,8 +76,7 @@ fi
 LATEST=$(curl -sI https://github.com/multica-ai/multica/releases/latest | grep -i '^location:' | sed 's/.*tag\///' | tr -d '\r\n')
 
 # Download and extract
-VERSION="${LATEST#v}"
-curl -sL "https://github.com/multica-ai/multica/releases/download/${LATEST}/multica-cli-${VERSION}-${OS}-${ARCH}.tar.gz" -o /tmp/multica.tar.gz
+curl -sL "https://github.com/multica-ai/multica/releases/download/${LATEST}/multica_${OS}_${ARCH}.tar.gz" -o /tmp/multica.tar.gz
 tar -xzf /tmp/multica.tar.gz -C /tmp multica
 sudo mv /tmp/multica /usr/local/bin/multica
 rm /tmp/multica.tar.gz
@@ -166,12 +165,12 @@ Wait 3 seconds, then verify:
 multica daemon status
 ```
 
-Expected output should show `running` status with detected agents (e.g. `claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, `cursor-agent`).
+Expected output should show `running` status with detected agents (e.g. `claude`, `codex`, `opencode`, `openclaw`, `hermes`).
 
 **If daemon fails to start:**
 - Check logs: `multica daemon logs`
 - If a port conflict occurs, the daemon may already be running under a different profile.
-- If no agents are detected, ensure at least one AI CLI (`claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`) is installed and on the `$PATH`.
+- If no agents are detected, ensure at least one AI CLI (`claude`, `codex`, `opencode`, `openclaw`, or `hermes`) is installed and on the `$PATH`.
 
 ---
 
@@ -185,12 +184,12 @@ multica daemon status
 
 Confirm:
 1. Status is `running`
-2. At least one agent is listed (e.g. `claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`)
+2. At least one agent is listed (e.g. `claude`, `codex`, `opencode`, `openclaw`, or `hermes`)
 3. At least one workspace is being watched
 
 If the agents list is empty, tell the user:
 
-> "The Multica daemon is running but no AI agent CLIs were detected. Please install at least one supported CLI (`claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`), then restart the daemon with `multica daemon stop && multica daemon start`."
+> "The Multica daemon is running but no AI agent CLIs were detected. Please install at least one supported CLI (`claude`, `codex`, `opencode`, `openclaw`, or `hermes`), then restart the daemon with `multica daemon stop && multica daemon start`."
 
 ---
 

Makefile

@@ -66,8 +66,7 @@ selfhost:
 		echo "  Frontend: http://localhost:$${FRONTEND_PORT:-3000}"; \
 		echo "  Backend:  http://localhost:$${PORT:-8080}"; \
 		echo ""; \
-		echo "Log in: configure RESEND_API_KEY in .env for email codes,"; \
-		echo "        or set APP_ENV=development in .env (private networks only) to enable code 888888."; \
+		echo "Log in with any email + verification code: 888888"; \
 		echo ""; \
 		echo "Next — install the CLI and connect your machine:"; \
 		echo "  brew install multica-ai/tap/multica"; \
@@ -183,7 +182,7 @@ server:
 	cd server && go run ./cmd/server
 
 daemon:
-	@$(MAKE) multica MULTICA_ARGS="daemon restart --profile local"
+	@$(MAKE) multica MULTICA_ARGS="daemon"
 
 cli:
 	@$(MAKE) multica MULTICA_ARGS="$(MULTICA_ARGS)"

README.md

@@ -30,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**, **OpenClaw**, **OpenCode**, **Hermes**, **Gemini**, **Pi**, and **Cursor Agent**.
+No more copy-pasting prompts. No more babysitting runs. Your agents show up on the board, participate in conversations, and compound reusable skills over time. Think of it as open-source infrastructure for managed agents — vendor-neutral, self-hosted, and designed for human + AI teams. Works with **Claude Code**, **Codex**, **OpenClaw**, and **OpenCode**.
 
 <p align="center">
   <img src="docs/assets/hero-screenshot.png" alt="Multica board view" width="800">
@@ -97,7 +97,7 @@ multica setup          # Connect to Multica Cloud, log in, start daemon
 multica setup           # Configure, authenticate, and start the daemon
 ```
 
-The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `openclaw`, `opencode`, `hermes`, `gemini`, `pi`, `cursor-agent`) on your PATH.
+The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `openclaw`, `opencode`) on your PATH.
 
 ### 2. Verify your runtime
 
@@ -107,7 +107,7 @@ Open your workspace in the Multica web app. Navigate to **Settings → Runtimes*
 
 ### 3. Create an agent
 
-Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code, Codex, OpenClaw, OpenCode, Hermes, Gemini, Pi, or Cursor Agent). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
+Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code, Codex, OpenClaw, or OpenCode). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
 
 ### 4. Assign your first task
 
@@ -158,10 +158,10 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
 └──────────────┘     └──────┬───────┘     └──────────────────┘
                             │
                      ┌──────┴───────┐
-                     │ Agent Daemon │  runs on your machine
-                     └──────────────┘  (Claude Code, Codex, OpenCode,
-                                        OpenClaw, Hermes, Gemini,
-                                        Pi, Cursor Agent)
+                     │ Agent Daemon │  (runs on your machine)
+                     │Claude/Codex/ │
+                     │OpenClaw/Code │
+                     └──────────────┘
 ```
 
 | Layer | Stack |
@@ -169,7 +169,7 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
 | Frontend | Next.js 16 (App Router) |
 | Backend | Go (Chi router, sqlc, gorilla/websocket) |
 | Database | PostgreSQL 17 with pgvector |
-| Agent Runtime | Local daemon executing Claude Code, Codex, OpenClaw, OpenCode, Hermes, Gemini, Pi, or Cursor Agent |
+| Agent Runtime | Local daemon executing Claude Code, Codex, OpenClaw, or OpenCode |
 
 ## Development
 

README.zh-CN.md

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

SELF_HOSTING.md

@@ -26,7 +26,7 @@ multica setup self-host
 
 This clones the repository, starts all services via Docker Compose, installs the `multica` CLI, then configures it for localhost.
 
-Open http://localhost:3000. To log in, configure `RESEND_API_KEY` in `.env` for email-based codes (recommended), or set `APP_ENV=development` in `.env` to enable the dev master code **`888888`**. See [Step 2 — Log In](#step-2--log-in) for details.
+Open http://localhost:3000, log in with any email + verification code **`888888`**.
 
 > **Prerequisites:** Docker and Docker Compose must be installed. The script checks for this and provides install links if missing.
 >
@@ -63,13 +63,9 @@ Once ready:
 
 ### Step 2 — Log In
 
-Open http://localhost:3000 in your browser. The Docker self-host stack defaults to `APP_ENV=production` (set in `docker-compose.selfhost.yml`), so the dev master code is **disabled by default** for safety on public deployments. Pick one of the following to log in:
+Open http://localhost:3000 in your browser. Enter any email address and use verification code **`888888`** to log in.
 
-- **Recommended (production):** configure `RESEND_API_KEY` in `.env`, then restart the backend. Real verification codes will be sent to the email address you enter. See [Advanced Configuration → Email](SELF_HOSTING_ADVANCED.md#email-required-for-authentication).
-- **Evaluation / private network:** set `APP_ENV=development` in `.env` and restart the backend. Verification code **`888888`** will then work for any email address.
-- **Without configuring either:** the verification code is generated server-side and printed to the backend container logs (look for `[DEV] Verification code for ...:`). Useful for one-off testing on a single machine.
-
-> **Warning:** do **not** set `APP_ENV=development` on a publicly reachable instance — anyone who knows an email address can then log in with `888888`.
+> This master code works in all non-production environments (i.e. when `APP_ENV` is not set to `production`). For production, configure an email provider — see [Advanced Configuration](SELF_HOSTING_ADVANCED.md#email-required-for-authentication).
 
 ### Step 3 — Install CLI & Start Daemon
 
@@ -89,9 +85,6 @@ You also need at least one AI agent CLI installed:
 - [OpenClaw](https://github.com/openclaw/openclaw) (`openclaw` on PATH)
 - [OpenCode](https://github.com/anomalyco/opencode) (`opencode` on PATH)
 - [Hermes](https://github.com/NousResearch/hermes) (`hermes` on PATH)
-- Gemini (`gemini` on PATH)
-- [Pi](https://pi.dev/) (`pi` on PATH)
-- [Cursor Agent](https://cursor.com/) (`cursor-agent` on PATH)
 
 ### b) One-command setup
 

SELF_HOSTING_ADVANCED.md

@@ -14,15 +14,6 @@ All configuration is done via environment variables. Copy `.env.example` as a st
 | `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` |
 
-### Database Pool Tuning (Optional)
-
-These have sensible defaults and only need to be set when tuning a large or constrained deployment. Precedence (highest first): env var → `pool_*` query params on `DATABASE_URL` → built-in default.
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `DATABASE_MAX_CONNS` | pgxpool max connections per pod. `pod_count × DATABASE_MAX_CONNS` should stay well below the Postgres `max_connections` ceiling. With a connection pooler (PgBouncer / RDS Proxy / Supavisor) in front, this can be raised significantly. | `25` |
-| `DATABASE_MIN_CONNS` | pgxpool warm baseline connections per pod. Auto-clamped to `DATABASE_MAX_CONNS`. | `5` |
-
 ### Email (Required for Authentication)
 
 Multica uses email-based magic link authentication via [Resend](https://resend.com).
@@ -32,7 +23,7 @@ Multica uses email-based magic link authentication via [Resend](https://resend.c
 | `RESEND_API_KEY` | Your Resend API key |
 | `RESEND_FROM_EMAIL` | Sender email address (default: `noreply@multica.ai`) |
 
-> **Note:** The dev master verification code `888888` is gated by `APP_ENV != "production"`. The Docker self-host stack defaults to `APP_ENV=production` (so `888888` is disabled), which protects publicly reachable instances. For local development without email configured, set `APP_ENV=development` in your `.env` to enable `888888` — never do this on a public instance.
+> **Note:** For local/development deployments without email configured, you can use the master verification code `888888` to log in.
 
 ### Google OAuth (Optional)
 
@@ -53,14 +44,7 @@ For file uploads and attachments, configure S3 and CloudFront:
 | `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
 | `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
 | `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
-
-### Cookies
-
-| Variable | Description |
-|----------|-------------|
-| `COOKIE_DOMAIN` | Optional `Domain` attribute for session + CloudFront cookies. **Leave empty** for single-host deployments (localhost, LAN IP, or a single hostname). Only set it when the frontend and backend sit on different subdomains of one registered domain (e.g. `.example.com`). **Do not use an IP literal** — RFC 6265 forbids IP addresses in the cookie `Domain` attribute and browsers will drop such `Set-Cookie` headers. |
-
-The `Secure` flag on session cookies is derived automatically from the scheme of `FRONTEND_ORIGIN`: HTTPS origins get `Secure` cookies; plain-HTTP origins (LAN / private-network self-host) get non-secure cookies so the browser can actually store them.
+| `COOKIE_DOMAIN` | Domain for CloudFront auth cookies |
 
 ### Server
 
@@ -96,12 +80,6 @@ Agent-specific overrides:
 | `MULTICA_OPENCLAW_MODEL` | Override the OpenClaw model used |
 | `MULTICA_HERMES_PATH` | Custom path to the `hermes` binary |
 | `MULTICA_HERMES_MODEL` | Override the Hermes model used |
-| `MULTICA_GEMINI_PATH` | Custom path to the `gemini` binary |
-| `MULTICA_GEMINI_MODEL` | Override the Gemini model used |
-| `MULTICA_PI_PATH` | Custom path to the `pi` binary |
-| `MULTICA_PI_MODEL` | Override the Pi model used |
-| `MULTICA_CURSOR_PATH` | Custom path to the `cursor-agent` binary |
-| `MULTICA_CURSOR_MODEL` | Override the Cursor Agent model used |
 
 ## Database Setup
 

apps/desktop/electron-builder.yml

@@ -21,34 +21,25 @@ mac:
     - zip
   # Hardcoded name avoids the `@multica/desktop-*` subdirectory that
   # `${name}` produces for scoped package names.
-  # Naming scheme: multica-desktop-<version>-<platform>-<arch>.<ext>
-  # so the filename alone surfaces kind, version, platform, and CPU arch.
-  artifactName: multica-desktop-${version}-mac-${arch}.${ext}
+  artifactName: multica-desktop-${version}-${arch}.${ext}
   # Notarize via notarytool. Requires APPLE_ID + APPLE_APP_SPECIFIC_PASSWORD
   # + APPLE_TEAM_ID env vars at package time. Non-mac contributors are
   # unaffected because `pnpm package` already requires the Developer ID
   # signing cert — notarization is a strict superset.
   notarize: true
 dmg:
-  artifactName: multica-desktop-${version}-mac-${arch}.${ext}
+  artifactName: multica-desktop-${version}-${arch}.${ext}
 linux:
   target:
     - AppImage
     - deb
-    - rpm
-  artifactName: multica-desktop-${version}-linux-${arch}.${ext}
+  artifactName: ${name}-${version}-${arch}.${ext}
 win:
   target:
     - nsis
-  artifactName: multica-desktop-${version}-windows-${arch}.${ext}
+  artifactName: ${name}-${version}-setup.${ext}
 publish:
   provider: github
   owner: multica-ai
   repo: multica
-  # Align with our CLI release flow which pre-creates a *published* GitHub
-  # Release via `gh release create`. The electron-builder default of
-  # `releaseType: draft` conflicts with `existingType=release` and causes
-  # uploads of the DMG/ZIP/blockmaps/latest-mac.yml to be silently skipped,
-  # which breaks electron-updater auto-update on installed clients.
-  releaseType: release
 npmRebuild: false

apps/desktop/electron.vite.config.ts

@@ -12,10 +12,7 @@ export default defineConfig({
   },
   renderer: {
     server: {
-      // Allow parallel worktrees to run `pnpm dev:desktop` side-by-side
-      // (e.g. Multica Canary alongside a primary checkout) by overriding
-      // the renderer port via env. Falls back to 5173 for the common case.
-      port: Number(process.env.DESKTOP_RENDERER_PORT) || 5173,
+      port: 5173,
       strictPort: true,
     },
     plugins: [react(), tailwindcss()],

apps/desktop/eslint.config.mjs

@@ -10,28 +10,4 @@ export default [
       globals: { ...globals.node },
     },
   },
-  // Security: every renderer-controlled URL that reaches the OS shell must
-  // flow through openExternalSafely in src/main/external-url.ts (scheme
-  // allowlist). Enforce it statically so a direct shell.openExternal call
-  // cannot silently regress the protection.
-  {
-    files: ["src/main/**/*.ts"],
-    rules: {
-      "no-restricted-syntax": [
-        "error",
-        {
-          selector:
-            "CallExpression[callee.object.name='shell'][callee.property.name='openExternal']",
-          message:
-            "Do not call shell.openExternal directly. Use openExternalSafely from './external-url' so the http/https allowlist stays enforced.",
-        },
-      ],
-    },
-  },
-  {
-    files: ["src/main/external-url.ts"],
-    rules: {
-      "no-restricted-syntax": "off",
-    },
-  },
 ];

apps/desktop/package.json

@@ -2,30 +2,16 @@
   "name": "@multica/desktop",
   "version": "0.1.0",
   "private": true,
-  "description": "Multica Desktop — native desktop client for the Multica platform.",
-  "homepage": "https://multica.ai",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/multica-ai/multica.git",
-    "directory": "apps/desktop"
-  },
-  "author": {
-    "name": "Multica",
-    "email": "support@multica.ai"
-  },
-  "license": "UNLICENSED",
   "main": "./out/main/index.js",
   "scripts": {
     "bundle-cli": "node scripts/bundle-cli.mjs",
-    "brand-dev-electron": "node scripts/brand-dev-electron.mjs",
-    "dev": "pnpm run bundle-cli && pnpm run brand-dev-electron && electron-vite dev",
+    "dev": "pnpm run bundle-cli && electron-vite dev",
     "build": "pnpm run bundle-cli && electron-vite build",
     "typecheck:node": "tsc --noEmit -p tsconfig.node.json --composite false",
     "typecheck:web": "tsc --noEmit -p tsconfig.web.json --composite false",
     "typecheck": "pnpm run typecheck:node && pnpm run typecheck:web",
     "preview": "electron-vite preview",
     "package": "node scripts/package.mjs",
-    "package:all": "node scripts/package.mjs --all-platforms --publish never",
     "lint": "eslint .",
     "test": "vitest run",
     "postinstall": "electron-builder install-app-deps"

apps/desktop/scripts/brand-dev-electron.mjs

@@ -1,73 +0,0 @@
-#!/usr/bin/env node
-// Rebrand the bundled Electron.app's Info.plist so `pnpm dev:desktop`
-// shows "Multica Canary" in the menu bar, Cmd+Tab switcher, and
-// Activity Monitor. On macOS these titles come from CFBundleName at
-// launch time — `app.setName()` cannot override them at runtime, so
-// patching the plist in node_modules is the only working fix.
-//
-// Idempotent: runs on every dev launch and no-ops once the plist already
-// matches. The patch is isolated to this worktree's node_modules — we
-// unlink the file before rewriting so we never mutate a pnpm-store inode
-// shared with another project.
-
-import { createRequire } from "node:module";
-import { execFileSync } from "node:child_process";
-import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-
-if (process.platform !== "darwin") process.exit(0);
-
-const DESIRED_NAME = "Multica Canary";
-
-const require = createRequire(import.meta.url);
-// `require('electron')` returns the path to the executable
-// (.../Electron.app/Contents/MacOS/Electron). Walk up to Contents/Info.plist.
-const electronBin = require("electron");
-const plistPath = resolve(electronBin, "../../Info.plist");
-
-function plistGet(key) {
-  try {
-    return execFileSync(
-      "/usr/libexec/PlistBuddy",
-      ["-c", `Print :${key}`, plistPath],
-      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
-    ).trim();
-  } catch {
-    return "";
-  }
-}
-
-function plistSet(key, value) {
-  try {
-    execFileSync("/usr/libexec/PlistBuddy", [
-      "-c",
-      `Set :${key} ${value}`,
-      plistPath,
-    ]);
-  } catch {
-    execFileSync("/usr/libexec/PlistBuddy", [
-      "-c",
-      `Add :${key} string ${value}`,
-      plistPath,
-    ]);
-  }
-}
-
-if (
-  plistGet("CFBundleName") === DESIRED_NAME &&
-  plistGet("CFBundleDisplayName") === DESIRED_NAME
-) {
-  process.exit(0);
-}
-
-// Break any pnpm hardlink to the global store: read, unlink, rewrite.
-// PlistBuddy would otherwise write through the hardlink and mutate the
-// shared store file (and every other project's Electron.app with it).
-const original = readFileSync(plistPath);
-unlinkSync(plistPath);
-writeFileSync(plistPath, original);
-
-plistSet("CFBundleName", DESIRED_NAME);
-plistSet("CFBundleDisplayName", DESIRED_NAME);
-
-console.log(`[brand-dev-electron] ${plistPath} → CFBundleName="${DESIRED_NAME}"`);

apps/desktop/scripts/bundle-cli.mjs

@@ -13,7 +13,7 @@
 // skip the build and fall through to auto-install at runtime. A genuine
 // Go compile error is fatal — you want that to block dev, not hide.
 
-import { access, chmod, copyFile, mkdir, rm } from "node:fs/promises";
+import { access, chmod, copyFile, mkdir } from "node:fs/promises";
 import { constants } from "node:fs";
 import { execFileSync, execSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
@@ -23,54 +23,8 @@ const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "..", "..", "..");
 const serverDir = join(repoRoot, "server");
 
-const PLATFORM_TO_GOOS = {
-  darwin: "darwin",
-  linux: "linux",
-  win32: "windows",
-};
-
-const SUPPORTED_ARCHS = new Set(["x64", "arm64"]);
-
-function runtimePlatformFromArgs(argv) {
-  const flagIndex = argv.indexOf("--target-platform");
-  if (flagIndex === -1) return process.platform;
-  return argv[flagIndex + 1] ?? "";
-}
-
-function runtimeArchFromArgs(argv) {
-  const flagIndex = argv.indexOf("--target-arch");
-  if (flagIndex === -1) return process.arch;
-  return argv[flagIndex + 1] ?? "";
-}
-
-function normalizeRuntimePlatform(platform) {
-  if (platform in PLATFORM_TO_GOOS) return platform;
-  throw new Error(
-    `[bundle-cli] unsupported target platform: ${platform}. ` +
-      "Use darwin, linux, or win32.",
-  );
-}
-
-function normalizeRuntimeArch(arch) {
-  if (SUPPORTED_ARCHS.has(arch)) return arch;
-  throw new Error(
-    `[bundle-cli] unsupported target architecture: ${arch}. ` +
-      "Use x64 or arm64.",
-  );
-}
-
-function binaryNameForPlatform(platform) {
-  return platform === "win32" ? "multica.exe" : "multica";
-}
-
-const targetPlatform = normalizeRuntimePlatform(
-  runtimePlatformFromArgs(process.argv.slice(2)),
-);
-const targetArch = normalizeRuntimeArch(runtimeArchFromArgs(process.argv.slice(2)));
-const goos = PLATFORM_TO_GOOS[targetPlatform];
-const goarch = targetArch === "x64" ? "amd64" : targetArch;
-const binName = binaryNameForPlatform(targetPlatform);
-const srcBinary = join(serverDir, "bin", `${goos}-${goarch}`, binName);
+const binName = process.platform === "win32" ? "multica.exe" : "multica";
+const srcBinary = join(serverDir, "bin", binName);
 const destDir = join(repoRoot, "apps", "desktop", "resources", "bin");
 const destBinary = join(destDir, binName);
 
@@ -107,9 +61,8 @@ if (hasGo()) {
   const ldflags = `-X main.version=${version} -X main.commit=${commit} -X main.date=${date}`;
 
   console.log(
-    `[bundle-cli] go build → ${srcBinary} (${goos}/${goarch}, version=${version} commit=${commit})`,
+    `[bundle-cli] go build → ${srcBinary} (version=${version} commit=${commit})`,
   );
-  await mkdir(join(serverDir, "bin", `${goos}-${goarch}`), { recursive: true });
   execFileSync(
     "go",
     [
@@ -117,19 +70,10 @@ if (hasGo()) {
       "-ldflags",
       ldflags,
       "-o",
-      srcBinary,
+      join("bin", binName),
       "./cmd/multica",
     ],
-    {
-      cwd: serverDir,
-      stdio: "inherit",
-      env: {
-        ...process.env,
-        CGO_ENABLED: "0",
-        GOOS: goos,
-        GOARCH: goarch,
-      },
-    },
+    { cwd: serverDir, stdio: "inherit" },
   );
 } else {
   console.warn(
@@ -144,11 +88,9 @@ if (!(await exists(srcBinary))) {
     `[bundle-cli] ${srcBinary} not present — Desktop will fall back to ` +
       `auto-installing the latest release at runtime.`,
   );
-  await rm(destDir, { recursive: true, force: true });
   process.exit(0);
 }
 
-await rm(destDir, { recursive: true, force: true });
 await mkdir(destDir, { recursive: true });
 await copyFile(srcBinary, destBinary);
 await chmod(destBinary, 0o755);

apps/desktop/scripts/package.mjs

@@ -5,11 +5,11 @@
 // binary via the `main.version` ldflag — so a single `vX.Y.Z` tag push
 // produces matching CLI and Desktop versions.
 //
-// Builds the Electron bundles once, then for each requested target
-// (platform + arch) compiles the matching Go CLI into resources/bin/ and
-// invokes electron-builder with `-c.extraMetadata.version=<derived>` so
-// the override applies at build time without mutating the tracked
-// package.json.
+// Runs bundle-cli.mjs first (so the Go binary is compiled and copied
+// into resources/bin/), then `electron-vite build` to produce the
+// main/preload/renderer bundles under out/, then invokes electron-builder
+// with `-c.extraMetadata.version=<derived>` so the override applies at
+// build time without mutating the tracked package.json.
 //
 // The electron-vite step is important: electron-builder only packages
 // whatever is already in out/, so skipping it (or relying on stale
@@ -25,50 +25,11 @@
 // version-derivation logic without shelling out.
 
 import { execFileSync, spawnSync, execSync } from "node:child_process";
-import { delimiter, dirname, resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const desktopRoot = resolve(here, "..");
-const bundleCliScript = resolve(here, "bundle-cli.mjs");
-
-const PLATFORM_CONFIG = {
-  mac: {
-    aliases: new Set(["--mac", "--macos", "-m"]),
-    builderFlag: "--mac",
-    runtimePlatform: "darwin",
-    label: "macOS",
-  },
-  win: {
-    aliases: new Set(["--win", "--windows", "-w"]),
-    builderFlag: "--win",
-    runtimePlatform: "win32",
-    label: "Windows",
-  },
-  linux: {
-    aliases: new Set(["--linux", "-l"]),
-    builderFlag: "--linux",
-    runtimePlatform: "linux",
-    label: "Linux",
-  },
-};
-
-const ARCH_FLAGS = new Map([
-  ["--x64", "x64"],
-  ["--arm64", "arm64"],
-  ["--ia32", "ia32"],
-  ["--armv7l", "armv7l"],
-  ["--universal", "universal"],
-]);
-
-const SUPPORTED_CLI_ARCHS = new Set(["x64", "arm64"]);
-const MAC_ALL_PLATFORM_TARGETS = [
-  { platform: "mac", arch: "arm64" },
-  { platform: "win", arch: "x64" },
-  { platform: "win", arch: "arm64" },
-  { platform: "linux", arch: "x64" },
-  { platform: "linux", arch: "arm64" },
-];
 
 function sh(cmd) {
   try {
@@ -78,18 +39,6 @@ function sh(cmd) {
   }
 }
 
-/**
- * Strip the leading `--` that npm/pnpm insert to separate their own
- * flags from the ones meant for the underlying script.  Without this,
- * `pnpm package -- --mac --arm64 --publish always` forwards the bare
- * `--` into electron-builder's argv, which terminates option parsing
- * and turns `--publish always` into ignored positional arguments.
- */
-export function stripLeadingSeparator(argv) {
-  if (argv.length > 0 && argv[0] === "--") return argv.slice(1);
-  return argv;
-}
-
 /**
  * Pure transformation from the `git describe --tags --always --dirty`
  * output to the value we feed into electron-builder's extraMetadata.version.
@@ -116,231 +65,20 @@ function deriveVersion() {
   return normalizeGitVersion(sh("git describe --tags --always --dirty"));
 }
 
-function uniqueOrdered(values) {
-  return [...new Set(values)];
-}
-
-export function envWithLocalBins(env = process.env, root = desktopRoot) {
-  const pathKey =
-    Object.keys(env).find((key) => key.toUpperCase() === "PATH") ?? "PATH";
-  const existingPath = env[pathKey] ?? "";
-  const localBins = uniqueOrdered([
-    resolve(root, "node_modules", ".bin"),
-    resolve(root, "..", "..", "node_modules", ".bin"),
-  ]);
-  const mergedPath = uniqueOrdered([
-    ...localBins,
-    ...String(existingPath)
-      .split(delimiter)
-      .filter(Boolean),
-  ]).join(delimiter);
-  return { ...env, [pathKey]: mergedPath };
-}
-
-function hostPlatformKey(platform = process.platform) {
-  if (platform === "darwin") return "mac";
-  if (platform === "win32") return "win";
-  if (platform === "linux") return "linux";
-  throw new Error(`[package] unsupported host platform: ${platform}`);
-}
-
-function hostArchKey(arch = process.arch) {
-  if (SUPPORTED_CLI_ARCHS.has(arch)) return arch;
-  throw new Error(
-    `[package] unsupported host architecture for Desktop CLI bundling: ${arch}`,
-  );
-}
-
-function expandPlatformShorthand(token) {
-  if (!/^-[mwl]{2,}$/.test(token)) return null;
-  const expanded = [];
-  for (const char of token.slice(1)) {
-    if (char === "m") expanded.push("mac");
-    if (char === "w") expanded.push("win");
-    if (char === "l") expanded.push("linux");
-  }
-  return uniqueOrdered(expanded);
-}
-
-function platformKeyForToken(token) {
-  for (const [platform, config] of Object.entries(PLATFORM_CONFIG)) {
-    if (config.aliases.has(token)) return platform;
-  }
-  return null;
-}
-
-function platformTargetsTemplate() {
-  return { mac: [], win: [], linux: [] };
-}
-
-export function parsePackageArgs(argv) {
-  const sharedArgs = [];
-  const platformTargets = platformTargetsTemplate();
-  const requestedPlatforms = [];
-  const requestedArchs = [];
-  let allPlatforms = false;
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const token = argv[i];
-    if (token === "--all-platforms") {
-      allPlatforms = true;
-      continue;
-    }
-
-    const expandedPlatforms = expandPlatformShorthand(token);
-    if (expandedPlatforms) {
-      requestedPlatforms.push(...expandedPlatforms);
-      continue;
-    }
-
-    const platform = platformKeyForToken(token);
-    if (platform) {
-      requestedPlatforms.push(platform);
-      while (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
-        platformTargets[platform].push(argv[i + 1]);
-        i += 1;
-      }
-      continue;
-    }
-
-    const arch = ARCH_FLAGS.get(token);
-    if (arch) {
-      requestedArchs.push(arch);
-      continue;
-    }
-
-    sharedArgs.push(token);
-  }
-
-  return {
-    allPlatforms,
-    sharedArgs,
-    platformTargets,
-    requestedPlatforms: uniqueOrdered(requestedPlatforms),
-    requestedArchs: uniqueOrdered(requestedArchs),
-  };
-}
-
-export function resolveBuildMatrix(parsed, platform = process.platform, arch = process.arch) {
-  if (parsed.allPlatforms) {
-    if (parsed.requestedPlatforms.length > 0 || parsed.requestedArchs.length > 0) {
-      throw new Error(
-        "[package] --all-platforms cannot be combined with explicit platform or arch flags",
-      );
-    }
-    if (platform !== "darwin") {
-      throw new Error(
-        `[package] --all-platforms is only supported on macOS hosts (current: ${platform})`,
-      );
-    }
-    return MAC_ALL_PLATFORM_TARGETS.map((target) => ({ ...target }));
-  }
-
-  const platforms =
-    parsed.requestedPlatforms.length > 0
-      ? parsed.requestedPlatforms
-      : [hostPlatformKey(platform)];
-  const archs =
-    parsed.requestedArchs.length > 0
-      ? parsed.requestedArchs
-      : [hostArchKey(arch)];
-
-  const unsupported = archs.filter((value) => !SUPPORTED_CLI_ARCHS.has(value));
-  if (unsupported.length > 0) {
-    throw new Error(
-      `[package] unsupported Desktop CLI architecture(s): ${unsupported.join(", ")}. ` +
-        "Use --x64 or --arm64.",
-    );
-  }
-
-  return platforms.flatMap((targetPlatform) =>
-    archs.map((targetArch) => ({
-      platform: targetPlatform,
-      arch: targetArch,
-    })),
-  );
-}
-
-function formatTarget(target) {
-  return `${PLATFORM_CONFIG[target.platform].label} ${target.arch}`;
-}
-
-export function builderArgsForTarget(
-  target,
-  parsed,
-  version,
-  {
-    disableMacNotarize = false,
-    hostPlatform = process.platform,
-    useScopedOutputDir = false,
-  } = {},
-) {
-  const builderArgs = [];
-  if (version) builderArgs.push(`-c.extraMetadata.version=${version}`);
-  if (disableMacNotarize) builderArgs.push("-c.mac.notarize=false");
-  builderArgs.push(PLATFORM_CONFIG[target.platform].builderFlag);
-  const requestedTargets = parsed.platformTargets[target.platform];
-  if (
-    target.platform === "linux" &&
-    hostPlatform !== "linux" &&
-    requestedTargets.length === 0
-  ) {
-    // electron-builder only guarantees AppImage/Snap when cross-building
-    // Linux from macOS/Windows. Keep `package:all` portable by defaulting
-    // to AppImage unless the caller explicitly requests Linux targets.
-    builderArgs.push("AppImage");
-  } else {
-    builderArgs.push(...requestedTargets);
-  }
-  builderArgs.push(`--${target.arch}`);
-  builderArgs.push(...parsed.sharedArgs);
-  if (useScopedOutputDir) {
-    builderArgs.push(
-      `-c.directories.output=dist/${target.platform}-${target.arch}`,
-    );
-  }
-  // electron-builder's update metadata file is `latest.yml` for Windows
-  // regardless of arch (only Linux gets an arch suffix automatically — see
-  // app-builder-lib's getArchPrefixForUpdateFile). Without an explicit
-  // channel override, building Windows x64 and arm64 in two invocations
-  // makes both publish `latest.yml` to the same GitHub Release, so the
-  // second upload overwrites the first and one of the two architectures
-  // ends up with no auto-update metadata. Route Windows arm64 to its own
-  // channel so x64 keeps `latest.yml` and arm64 ships `latest-arm64.yml`;
-  // the renderer-side updater pins the matching channel per arch.
-  if (target.platform === "win" && target.arch === "arm64") {
-    builderArgs.push("-c.publish.channel=latest-arm64");
-  }
-  return builderArgs;
-}
-
 function main() {
-  const passthrough = stripLeadingSeparator(process.argv.slice(2));
-  const parsed = parsePackageArgs(passthrough);
-  const buildMatrix = resolveBuildMatrix(parsed);
-  console.log(
-    `[package] build matrix → ${buildMatrix.map(formatTarget).join(", ")}`,
-  );
+  // Step 1: build + bundle the Go CLI via the existing script.
+  execFileSync("node", [resolve(here, "bundle-cli.mjs")], {
+    stdio: "inherit",
+    cwd: desktopRoot,
+  });
 
-  // Step 1: build the Electron main/preload/renderer bundles. Without
+  // Step 2: build the Electron main/preload/renderer bundles. Without
   // this step electron-builder silently packages whatever is already in
   // out/, which on a fresh checkout (or after a partial build) ships an
   // app that white-screens because the renderer bundle is missing.
-  //
-  // CI invokes this script via `node scripts/package.mjs`, so we cannot
-  // rely on pnpm/npm to inject package-local binaries into PATH.
-  //
-  // `shell: true` is required on Windows: `node_modules/.bin/electron-vite`
-  // ships as a `.cmd` shim there, and Node's `spawnSync` does not honour
-  // PATHEXT when spawning a bare command without a shell — it would fail
-  // with `ENOENT`. On POSIX hosts the shim is a real executable so going
-  // through the shell is harmless. See
-  // https://nodejs.org/api/child_process.html#spawning-bat-and-cmd-files-on-windows
   const viteResult = spawnSync("electron-vite", ["build"], {
     stdio: "inherit",
     cwd: desktopRoot,
-    env: envWithLocalBins(),
-    shell: true,
   });
   if (viteResult.error) {
     console.error(
@@ -353,7 +91,7 @@ function main() {
     process.exit(viteResult.status ?? 1);
   }
 
-  // Step 2: derive the version that should be written into the app.
+  // Step 3: derive the version that should be written into the app.
   const version = deriveVersion();
   if (version) {
     console.log(`[package] Desktop version → ${version} (from git describe)`);
@@ -363,62 +101,43 @@ function main() {
     );
   }
 
-  const disableMacNotarize = !process.env.APPLE_TEAM_ID;
-  if (disableMacNotarize) {
+  // Step 4: assemble electron-builder args.
+  const passthrough = process.argv.slice(2);
+  const builderArgs = [];
+  if (version) builderArgs.push(`-c.extraMetadata.version=${version}`);
+
+  // Step 5: gracefully degrade for local dev builds. electron-builder.yml
+  // sets `notarize: true` so real releases notarize in-build (keeping the
+  // stapled .app consistent with latest-mac.yml's SHA512). But a mac dev
+  // who just wants to smoke-test a local package doesn't have Apple
+  // credentials, and would otherwise hit a hard failure at the notarize
+  // step. Detect the missing env and flip notarize off for this run only.
+  if (!process.env.APPLE_TEAM_ID) {
     console.warn(
       "[package] APPLE_TEAM_ID not set — skipping notarization (local dev build). " +
         "Set APPLE_ID + APPLE_APP_SPECIFIC_PASSWORD + APPLE_TEAM_ID for a release build.",
     );
+    builderArgs.push("-c.mac.notarize=false");
   }
 
-  const useScopedOutputDir = buildMatrix.length > 1;
+  builderArgs.push(...passthrough);
 
-  // Step 3: for each requested target, build the matching CLI into
-  // resources/bin/ and package that target in isolation.
-  for (const target of buildMatrix) {
-    console.log(`[package] bundling CLI → ${formatTarget(target)}`);
-    execFileSync(
-      "node",
-      [
-        bundleCliScript,
-        "--target-platform",
-        PLATFORM_CONFIG[target.platform].runtimePlatform,
-        "--target-arch",
-        target.arch,
-      ],
-      {
-        stdio: "inherit",
-        cwd: desktopRoot,
-      },
+  // Step 6: invoke electron-builder. pnpm puts node_modules/.bin on PATH
+  // for the script run, so spawnSync finds the binary without needing a
+  // shell wrapper (avoids any risk of argv interpolation).
+  const result = spawnSync("electron-builder", builderArgs, {
+    stdio: "inherit",
+    cwd: desktopRoot,
+  });
+
+  if (result.error) {
+    console.error(
+      "[package] failed to spawn electron-builder:",
+      result.error.message,
     );
-
-    const builderArgs = builderArgsForTarget(target, parsed, version, {
-      disableMacNotarize,
-      hostPlatform: process.platform,
-      useScopedOutputDir,
-    });
-
-    // Step 4: invoke electron-builder for the current target only.
-    // `shell: true` for the same Windows `.cmd` shim reason as the
-    // electron-vite invocation above.
-    const result = spawnSync("electron-builder", builderArgs, {
-      stdio: "inherit",
-      cwd: desktopRoot,
-      env: envWithLocalBins(),
-      shell: true,
-    });
-
-    if (result.error) {
-      console.error(
-        "[package] failed to spawn electron-builder:",
-        result.error.message,
-      );
-      process.exit(1);
-    }
-    if (result.status !== 0) {
-      process.exit(result.status ?? 1);
-    }
+    process.exit(1);
   }
+  process.exit(result.status ?? 1);
 }
 
 // Only run when invoked as a CLI, not when imported by a test file.

apps/desktop/scripts/package.test.mjs

@@ -1,13 +1,5 @@
-import { delimiter, resolve } from "node:path";
 import { describe, it, expect } from "vitest";
-import {
-  builderArgsForTarget,
-  envWithLocalBins,
-  normalizeGitVersion,
-  parsePackageArgs,
-  resolveBuildMatrix,
-  stripLeadingSeparator,
-} from "./package.mjs";
+import { normalizeGitVersion } from "./package.mjs";
 
 describe("normalizeGitVersion", () => {
   it("returns null for empty / nullish input", () => {
@@ -45,229 +37,3 @@ describe("normalizeGitVersion", () => {
     expect(normalizeGitVersion("abc1234")).toBe("0.0.0-abc1234");
   });
 });
-
-describe("stripLeadingSeparator", () => {
-  it("removes the leading -- inserted by npm/pnpm", () => {
-    expect(stripLeadingSeparator(["--", "--mac", "--arm64", "--publish", "always"])).toEqual([
-      "--mac", "--arm64", "--publish", "always",
-    ]);
-  });
-
-  it("leaves args untouched when there is no leading --", () => {
-    expect(stripLeadingSeparator(["--mac", "--arm64"])).toEqual(["--mac", "--arm64"]);
-  });
-
-  it("does not strip a -- that appears mid-argv", () => {
-    expect(stripLeadingSeparator(["--mac", "--", "--arm64"])).toEqual([
-      "--mac", "--", "--arm64",
-    ]);
-  });
-
-  it("handles an empty array", () => {
-    expect(stripLeadingSeparator([])).toEqual([]);
-  });
-});
-
-describe("parsePackageArgs", () => {
-  it("collects per-platform targets and shared args", () => {
-    expect(
-      parsePackageArgs([
-        "--win", "nsis",
-        "--mac", "dmg", "zip",
-        "--arm64",
-        "--publish", "never",
-      ]),
-    ).toEqual({
-      allPlatforms: false,
-      sharedArgs: ["--publish", "never"],
-      platformTargets: {
-        mac: ["dmg", "zip"],
-        win: ["nsis"],
-        linux: [],
-      },
-      requestedPlatforms: ["win", "mac"],
-      requestedArchs: ["arm64"],
-    });
-  });
-
-  it("expands combined short flags", () => {
-    expect(parsePackageArgs(["-mw", "--x64"]).requestedPlatforms).toEqual([
-      "mac",
-      "win",
-    ]);
-  });
-
-  it("tracks the all-platforms shortcut", () => {
-    expect(parsePackageArgs(["--all-platforms", "--publish", "never"]).allPlatforms).toBe(true);
-  });
-});
-
-describe("resolveBuildMatrix", () => {
-  it("defaults to the current host platform and arch", () => {
-    expect(
-      resolveBuildMatrix(
-        {
-          allPlatforms: false,
-          sharedArgs: [],
-          platformTargets: { mac: [], win: [], linux: [] },
-          requestedPlatforms: [],
-          requestedArchs: [],
-        },
-        "darwin",
-        "arm64",
-      ),
-    ).toEqual([{ platform: "mac", arch: "arm64" }]);
-  });
-
-  it("expands all-platforms on macOS", () => {
-    expect(
-      resolveBuildMatrix(
-        {
-          allPlatforms: true,
-          sharedArgs: [],
-          platformTargets: { mac: [], win: [], linux: [] },
-          requestedPlatforms: [],
-          requestedArchs: [],
-        },
-        "darwin",
-        "arm64",
-      ),
-    ).toEqual([
-      { platform: "mac", arch: "arm64" },
-      { platform: "win", arch: "x64" },
-      { platform: "win", arch: "arm64" },
-      { platform: "linux", arch: "x64" },
-      { platform: "linux", arch: "arm64" },
-    ]);
-  });
-
-  it("rejects unsupported architectures", () => {
-    expect(() =>
-      resolveBuildMatrix(
-        {
-          allPlatforms: false,
-          sharedArgs: [],
-          platformTargets: { mac: [], win: [], linux: [] },
-          requestedPlatforms: ["win"],
-          requestedArchs: ["universal"],
-        },
-        "darwin",
-        "arm64",
-      ),
-    ).toThrow(/unsupported Desktop CLI architecture/);
-  });
-});
-
-describe("builderArgsForTarget", () => {
-  it("adds scoped output directories for multi-target builds", () => {
-    expect(
-      builderArgsForTarget(
-        { platform: "win", arch: "arm64" },
-        {
-          allPlatforms: false,
-          sharedArgs: ["--publish", "never"],
-          platformTargets: { mac: [], win: ["nsis"], linux: [] },
-          requestedPlatforms: ["win"],
-          requestedArchs: ["arm64"],
-        },
-        "1.2.3",
-        {
-          disableMacNotarize: true,
-          hostPlatform: "darwin",
-          useScopedOutputDir: true,
-        },
-      ),
-    ).toEqual([
-      "-c.extraMetadata.version=1.2.3",
-      "-c.mac.notarize=false",
-      "--win",
-      "nsis",
-      "--arm64",
-      "--publish",
-      "never",
-      "-c.directories.output=dist/win-arm64",
-      "-c.publish.channel=latest-arm64",
-    ]);
-  });
-
-  it("does not override the publish channel for Windows x64 (default latest.yml)", () => {
-    expect(
-      builderArgsForTarget(
-        { platform: "win", arch: "x64" },
-        {
-          allPlatforms: false,
-          sharedArgs: ["--publish", "always"],
-          platformTargets: { mac: [], win: ["nsis"], linux: [] },
-          requestedPlatforms: ["win"],
-          requestedArchs: ["x64"],
-        },
-        "1.2.3",
-        { hostPlatform: "win32", useScopedOutputDir: true },
-      ),
-    ).toEqual([
-      "-c.extraMetadata.version=1.2.3",
-      "--win",
-      "nsis",
-      "--x64",
-      "--publish",
-      "always",
-      "-c.directories.output=dist/win-x64",
-    ]);
-  });
-
-  it("defaults linux cross-builds to AppImage on non-Linux hosts", () => {
-    expect(
-      builderArgsForTarget(
-        { platform: "linux", arch: "x64" },
-        {
-          allPlatforms: false,
-          sharedArgs: ["--publish", "never"],
-          platformTargets: { mac: [], win: [], linux: [] },
-          requestedPlatforms: ["linux"],
-          requestedArchs: ["x64"],
-        },
-        "1.2.3",
-        { hostPlatform: "darwin" },
-      ),
-    ).toEqual([
-      "-c.extraMetadata.version=1.2.3",
-      "--linux",
-      "AppImage",
-      "--x64",
-      "--publish",
-      "never",
-    ]);
-  });
-});
-
-describe("envWithLocalBins", () => {
-  it("prepends desktop-local binary directories to PATH", () => {
-    const desktopRoot = "/repo/apps/desktop";
-    const result = envWithLocalBins(
-      { PATH: ["/usr/local/bin", "/usr/bin"].join(delimiter) },
-      desktopRoot,
-    );
-    expect(result.PATH.split(delimiter)).toEqual([
-      resolve(desktopRoot, "node_modules", ".bin"),
-      resolve(desktopRoot, "..", "..", "node_modules", ".bin"),
-      "/usr/local/bin",
-      "/usr/bin",
-    ]);
-  });
-
-  it("preserves an existing Path key and avoids duplicate entries", () => {
-    const desktopRoot = "/repo/apps/desktop";
-    const desktopBin = resolve(desktopRoot, "node_modules", ".bin");
-    const workspaceBin = resolve(desktopRoot, "..", "..", "node_modules", ".bin");
-    const result = envWithLocalBins(
-      { Path: [desktopBin, "runner-bin", workspaceBin].join(delimiter) },
-      desktopRoot,
-    );
-    expect(result).not.toHaveProperty("PATH");
-    expect(result.Path.split(delimiter)).toEqual([
-      desktopBin,
-      workspaceBin,
-      "runner-bin",
-    ]);
-  });
-});

apps/desktop/src/main/cli-bootstrap.ts

@@ -8,15 +8,35 @@ import { pipeline } from "stream/promises";
 import { tmpdir } from "os";
 import { Readable } from "stream";
 
-import { selectPlatformReleaseAssetName } from "./cli-release-asset";
-
-// Desktop prefers the bundled `multica` CLI shipped inside the app for
-// same-repo builds, but it can also repair or bootstrap a managed copy in
-// userData on first launch when the bundled binary is missing or unusable.
+// Desktop bootstraps its own copy of the `multica` CLI into userData on first
+// launch, so users never have to brew-install anything. Build-time decoupled:
+// we don't bundle the binary into the .app, we download whatever the upstream
+// release is at first run.
 
 const GITHUB_LATEST_BASE =
   "https://github.com/multica-ai/multica/releases/latest/download";
 
+function platformAssetName(): string {
+  const osMap: Record<string, string> = {
+    darwin: "darwin",
+    linux: "linux",
+    win32: "windows",
+  };
+  const archMap: Record<string, string> = {
+    x64: "amd64",
+    arm64: "arm64",
+  };
+  const os = osMap[process.platform];
+  const arch = archMap[process.arch];
+  if (!os || !arch) {
+    throw new Error(
+      `unsupported platform for CLI auto-install: ${process.platform}/${process.arch}`,
+    );
+  }
+  const ext = process.platform === "win32" ? "zip" : "tar.gz";
+  return `multica_${os}_${arch}.${ext}`;
+}
+
 function binaryName(): string {
   return process.platform === "win32" ? "multica.exe" : "multica";
 }
@@ -72,8 +92,14 @@ async function sha256OfFile(path: string): Promise<string> {
 async function verifyChecksum(
   archivePath: string,
   assetName: string,
-  expected: string,
 ): Promise<void> {
+  const checksums = await fetchChecksums();
+  const expected = checksums.get(assetName);
+  if (!expected) {
+    throw new Error(
+      `no checksum for ${assetName} in checksums.txt — refusing to install unverified binary`,
+    );
+  }
   const actual = await sha256OfFile(archivePath);
   if (actual.toLowerCase() !== expected) {
     throw new Error(
@@ -92,14 +118,7 @@ async function extractArchive(archive: string, dest: string): Promise<void> {
 
 async function installFresh(): Promise<string> {
   const target = managedCliPath();
-  const checksums = await fetchChecksums();
-  const assetName = selectPlatformReleaseAssetName(checksums.keys());
-  const expectedChecksum = checksums.get(assetName);
-  if (!expectedChecksum) {
-    throw new Error(
-      `no checksum for ${assetName} in checksums.txt — refusing to install unverified binary`,
-    );
-  }
+  const assetName = platformAssetName();
   const url = `${GITHUB_LATEST_BASE}/${assetName}`;
 
   const workDir = join(tmpdir(), `multica-cli-${Date.now()}`);
@@ -111,7 +130,7 @@ async function installFresh(): Promise<string> {
     await downloadToFile(url, archivePath);
 
     console.log(`[cli-bootstrap] verifying ${assetName} against checksums.txt`);
-    await verifyChecksum(archivePath, assetName, expectedChecksum);
+    await verifyChecksum(archivePath, assetName);
 
     console.log(`[cli-bootstrap] extracting ${assetName}`);
     await extractArchive(archivePath, workDir);
@@ -124,7 +143,6 @@ async function installFresh(): Promise<string> {
     }
 
     await mkdir(dirname(target), { recursive: true });
-    await rm(target, { force: true }).catch(() => {});
     await rename(extractedBin, target);
     await chmod(target, 0o755);
 
@@ -148,10 +166,8 @@ async function installFresh(): Promise<string> {
  * the managed userData location, returns it immediately. Otherwise downloads
  * the latest release asset for the current platform and installs it.
  */
-export async function ensureManagedCli(
-  options: { forceInstall?: boolean } = {},
-): Promise<string> {
+export async function ensureManagedCli(): Promise<string> {
   const target = managedCliPath();
-  if (existsSync(target) && !options.forceInstall) return target;
+  if (existsSync(target)) return target;
   return installFresh();
 }

apps/desktop/src/main/cli-release-asset.test.ts

@@ -1,59 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { selectPlatformReleaseAssetName } from "./cli-release-asset";
-
-describe("selectPlatformReleaseAssetName", () => {
-  it("prefers the versioned archive name when both exist", () => {
-    const assetNames = [
-      "checksums.txt",
-      "multica_darwin_amd64.tar.gz",
-      "multica-cli-1.2.3-darwin-amd64.tar.gz",
-    ];
-
-    expect(selectPlatformReleaseAssetName(assetNames, "darwin", "x64")).toBe(
-      "multica-cli-1.2.3-darwin-amd64.tar.gz",
-    );
-  });
-
-  it("falls back to the legacy archive name when only legacy is present", () => {
-    const assetNames = ["checksums.txt", "multica_darwin_amd64.tar.gz"];
-
-    expect(selectPlatformReleaseAssetName(assetNames, "darwin", "x64")).toBe(
-      "multica_darwin_amd64.tar.gz",
-    );
-  });
-
-  it("matches the renamed darwin archive from release assets", () => {
-    const assetNames = [
-      "checksums.txt",
-      "multica-cli-1.2.3-darwin-amd64.tar.gz",
-      "multica-cli-1.2.3-darwin-arm64.tar.gz",
-      "multica-cli-1.2.3-linux-amd64.tar.gz",
-    ];
-
-    expect(selectPlatformReleaseAssetName(assetNames, "darwin", "x64")).toBe(
-      "multica-cli-1.2.3-darwin-amd64.tar.gz",
-    );
-  });
-
-  it("matches the renamed windows zip archive", () => {
-    const assetNames = [
-      "multica-cli-1.2.3-windows-amd64.zip",
-      "multica-cli-1.2.3-linux-amd64.tar.gz",
-    ];
-
-    expect(selectPlatformReleaseAssetName(assetNames, "win32", "x64")).toBe(
-      "multica-cli-1.2.3-windows-amd64.zip",
-    );
-  });
-
-  it("fails when the current platform asset is missing", () => {
-    expect(() =>
-      selectPlatformReleaseAssetName(
-        ["multica-cli-1.2.3-linux-amd64.tar.gz", "multica_linux_amd64.tar.gz"],
-        "darwin",
-        "arm64",
-      ),
-    ).toThrow(/no release asset found/);
-  });
-});

apps/desktop/src/main/cli-release-asset.ts

@@ -1,62 +0,0 @@
-const RELEASE_ARCHIVE_PREFIX = "multica-cli-";
-
-function platformArchiveDescriptor(
-  platform: NodeJS.Platform = process.platform,
-  arch: string = process.arch,
-): { os: string; arch: string; ext: string } {
-  const osMap: Record<string, string> = {
-    darwin: "darwin",
-    linux: "linux",
-    win32: "windows",
-  };
-  const archMap: Record<string, string> = {
-    x64: "amd64",
-    arm64: "arm64",
-  };
-  const os = osMap[platform];
-  const mappedArch = archMap[arch];
-  if (!os || !mappedArch) {
-    throw new Error(
-      `unsupported platform for CLI auto-install: ${platform}/${arch}`,
-    );
-  }
-  const ext = platform === "win32" ? "zip" : "tar.gz";
-  return { os, arch: mappedArch, ext };
-}
-
-export function selectPlatformReleaseAssetName(
-  assetNames: Iterable<string>,
-  platform: NodeJS.Platform = process.platform,
-  arch: string = process.arch,
-): string {
-  const { os, arch: mappedArch, ext } = platformArchiveDescriptor(
-    platform,
-    arch,
-  );
-  const names = [...assetNames];
-
-  // Prefer the versioned `multica-cli-<v>-<os>-<arch>.<ext>` name; fall
-  // back to the legacy `multica_<os>_<arch>.<ext>` so older releases that
-  // only ship the legacy archive keep working.
-  const suffix = `-${os}-${mappedArch}.${ext}`;
-  const matches = names.filter(
-    (name) =>
-      name.startsWith(RELEASE_ARCHIVE_PREFIX) && name.endsWith(suffix),
-  );
-
-  if (matches.length === 1) {
-    return matches[0];
-  }
-  if (matches.length > 1) {
-    throw new Error(
-      `multiple release assets matched current platform ${suffix}: ${matches.join(", ")}`,
-    );
-  }
-
-  const legacyName = `multica_${os}_${mappedArch}.${ext}`;
-  if (names.includes(legacyName)) {
-    return legacyName;
-  }
-
-  throw new Error(`no release asset found for current platform: ${suffix}`);
-}

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

@@ -316,36 +316,6 @@ function bundledCliPath(): string {
   );
 }
 
-async function probeCliBinary(
-  bin: string,
-  source: "bundled" | "managed" | "path",
-): Promise<string | null> {
-  try {
-    const stdout = await new Promise<string>((resolve, reject) => {
-      execFile(
-        bin,
-        ["version", "--output", "json"],
-        { timeout: 5_000 },
-        (err, out) => {
-          if (err) reject(err);
-          else resolve(out);
-        },
-      );
-    });
-    const parsed = JSON.parse(stdout) as { version?: string };
-    if (typeof parsed.version === "string" && parsed.version.length > 0) {
-      return parsed.version;
-    }
-    console.warn(
-      `[daemon] ignoring ${source} CLI at ${bin}: version output was missing or invalid`,
-    );
-    return null;
-  } catch (err) {
-    console.warn(`[daemon] ignoring ${source} CLI at ${bin}:`, err);
-    return null;
-  }
-}
-
 /**
  * Returns a usable `multica` binary path. Priority:
  *   1. Cached result from a previous successful resolve.
@@ -369,55 +339,27 @@ async function resolveCliBinary(): Promise<string | null> {
   cliResolvePromise = (async () => {
     const bundled = bundledCliPath();
     if (existsSync(bundled)) {
-      const version = await probeCliBinary(bundled, "bundled");
-      if (version) {
-        console.log(`[daemon] using bundled CLI at ${bundled}`);
-        cachedCliBinary = bundled;
-        cachedCliBinaryVersion = version;
-        return bundled;
-      }
+      console.log(`[daemon] using bundled CLI at ${bundled}`);
+      cachedCliBinary = bundled;
+      return bundled;
     }
 
     const managed = managedCliPath();
     if (existsSync(managed)) {
-      const version = await probeCliBinary(managed, "managed");
-      if (version) {
-        cachedCliBinary = managed;
-        cachedCliBinaryVersion = version;
-        return managed;
-      }
+      cachedCliBinary = managed;
+      return managed;
     }
 
     try {
-      const installed = await ensureManagedCli({
-        forceInstall: existsSync(managed),
-      });
-      const version = await probeCliBinary(installed, "managed");
-      if (version) {
-        cachedCliBinary = installed;
-        cachedCliBinaryVersion = version;
-        return installed;
-      }
-      console.warn(
-        `[daemon] managed CLI at ${installed} failed validation after install`,
-      );
+      const installed = await ensureManagedCli();
+      cachedCliBinary = installed;
+      return installed;
     } catch (err) {
       console.warn("[daemon] CLI auto-install failed, falling back to PATH:", err);
+      const onPath = findCliOnPath();
+      cachedCliBinary = onPath;
+      return onPath;
     }
-
-    const onPath = findCliOnPath();
-    if (onPath) {
-      const version = await probeCliBinary(onPath, "path");
-      if (version) {
-        cachedCliBinary = onPath;
-        cachedCliBinaryVersion = version;
-        return onPath;
-      }
-    }
-
-    cachedCliBinary = null;
-    cachedCliBinaryVersion = null;
-    return null;
   })();
 
   try {
@@ -428,10 +370,11 @@ async function resolveCliBinary(): Promise<string | null> {
 }
 
 /**
- * Reads the version of the currently resolved CLI binary. Cached for the
- * process lifetime — the bundled binary doesn't change after bundle time.
+ * Reads the version of the currently resolved CLI binary by invoking
+ * `multica version --output json`. Cached for the process lifetime — the
+ * bundled binary doesn't change after `bundle-cli.mjs` runs at dev/build time.
  * Returns null on any failure (unknown `go` at bundle time, broken binary,
- * wrong-arch bundled binary, etc.) so callers can fail open.
+ * etc.) so callers can fail open.
  */
 async function getCliBinaryVersion(): Promise<string | null> {
   if (cachedCliBinaryVersion !== undefined) return cachedCliBinaryVersion;
@@ -440,7 +383,24 @@ async function getCliBinaryVersion(): Promise<string | null> {
     cachedCliBinaryVersion = null;
     return null;
   }
-  cachedCliBinaryVersion = await probeCliBinary(bin, "path");
+  try {
+    const stdout = await new Promise<string>((resolve, reject) => {
+      execFile(
+        bin,
+        ["version", "--output", "json"],
+        { timeout: 5_000 },
+        (err, out) => {
+          if (err) reject(err);
+          else resolve(out);
+        },
+      );
+    });
+    const parsed = JSON.parse(stdout) as { version?: string };
+    cachedCliBinaryVersion = parsed.version ?? null;
+  } catch (err) {
+    console.warn("[daemon] failed to read CLI binary version:", err);
+    cachedCliBinaryVersion = null;
+  }
   return cachedCliBinaryVersion;
 }
 

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

@@ -1,73 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from "vitest";
-
-vi.mock("electron", () => ({
-  shell: { openExternal: vi.fn().mockResolvedValue(undefined) },
-}));
-
-import { shell } from "electron";
-import { isSafeExternalHttpUrl, openExternalSafely } from "./external-url";
-
-describe("isSafeExternalHttpUrl", () => {
-  it("allows http and https URLs", () => {
-    expect(isSafeExternalHttpUrl("https://multica.ai")).toBe(true);
-    expect(isSafeExternalHttpUrl("http://localhost:3000/auth")).toBe(true);
-  });
-
-  it("allows https URLs with embedded credentials", () => {
-    // WHATWG URL parses these as https; OS-level handling is the shell's concern.
-    expect(isSafeExternalHttpUrl("https://user:pass@example.com")).toBe(true);
-  });
-
-  it("normalizes scheme casing so uppercase variants can't bypass", () => {
-    expect(isSafeExternalHttpUrl("HTTPS://example.com")).toBe(true);
-    expect(isSafeExternalHttpUrl("FILE:///etc/passwd")).toBe(false);
-  });
-
-  it("rejects dangerous pseudo-schemes", () => {
-    expect(isSafeExternalHttpUrl("javascript:alert(1)")).toBe(false);
-    expect(
-      isSafeExternalHttpUrl("data:text/html,<script>alert(1)</script>"),
-    ).toBe(false);
-  });
-
-  it("rejects filesystem and network transport schemes", () => {
-    expect(isSafeExternalHttpUrl("file:///etc/passwd")).toBe(false);
-    expect(isSafeExternalHttpUrl("ftp://example.com/x")).toBe(false);
-    expect(isSafeExternalHttpUrl("smb://share/x")).toBe(false);
-  });
-
-  it("rejects local-handler schemes used in past RCE chains", () => {
-    expect(isSafeExternalHttpUrl("vscode://file/test")).toBe(false);
-    expect(isSafeExternalHttpUrl("ms-msdt:/id%20PCWDiagnostic")).toBe(false);
-  });
-
-  it("rejects mailto and other non-web schemes", () => {
-    expect(isSafeExternalHttpUrl("mailto:test@example.com")).toBe(false);
-    expect(isSafeExternalHttpUrl("tel:+15551234567")).toBe(false);
-  });
-
-  it("rejects empty, whitespace, and malformed input", () => {
-    expect(isSafeExternalHttpUrl("")).toBe(false);
-    expect(isSafeExternalHttpUrl(" ")).toBe(false);
-    expect(isSafeExternalHttpUrl("not a url")).toBe(false);
-    expect(isSafeExternalHttpUrl("http://")).toBe(false);
-  });
-});
-
-describe("openExternalSafely", () => {
-  beforeEach(() => {
-    vi.mocked(shell.openExternal).mockClear();
-  });
-
-  it("forwards http/https URLs to shell.openExternal", () => {
-    openExternalSafely("https://multica.ai");
-    expect(shell.openExternal).toHaveBeenCalledWith("https://multica.ai");
-  });
-
-  it("does not call shell.openExternal for rejected schemes", () => {
-    openExternalSafely("file:///etc/passwd");
-    openExternalSafely("javascript:alert(1)");
-    openExternalSafely("not a url");
-    expect(shell.openExternal).not.toHaveBeenCalled();
-  });
-});

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

@@ -1,38 +0,0 @@
-import { shell } from "electron";
-
-// True when the URL parses and uses http/https — the only schemes we let
-// reach `shell.openExternal`. Scheme comparison is safe because the WHATWG
-// URL parser lowercases the protocol field.
-export function isSafeExternalHttpUrl(url: string): boolean {
-  return getHttpProtocol(url) !== null;
-}
-
-// Canonical wrapper around shell.openExternal. All renderer-controlled URLs
-// that eventually reach the OS shell MUST flow through here; direct calls
-// to `shell.openExternal` elsewhere in the main process are banned by the
-// no-restricted-syntax rule in apps/desktop/eslint.config.mjs.
-export function openExternalSafely(url: string): Promise<void> | void {
-  if (getHttpProtocol(url) === null) {
-    console.warn(`[security] blocked openExternal: ${describeScheme(url)}`);
-    return;
-  }
-  return shell.openExternal(url);
-}
-
-function getHttpProtocol(url: string): "http:" | "https:" | null {
-  try {
-    const { protocol } = new URL(url);
-    if (protocol === "http:" || protocol === "https:") return protocol;
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-function describeScheme(url: string): string {
-  try {
-    return `scheme=${new URL(url).protocol}`;
-  } catch {
-    return "invalid URL";
-  }
-}

apps/desktop/src/main/index.ts

@@ -1,16 +1,10 @@
-import { app, BrowserWindow, ipcMain, nativeImage } from "electron";
+import { app, shell, BrowserWindow, ipcMain } from "electron";
 import { homedir } from "os";
 import { join } from "path";
 import { electronApp, optimizer, is } from "@electron-toolkit/utils";
 import fixPath from "fix-path";
 import { setupAutoUpdater } from "./updater";
 import { setupDaemonManager } from "./daemon-manager";
-import { openExternalSafely } from "./external-url";
-
-// Bundled icon used for dev-mode dock/taskbar branding. In production the
-// app bundle icon (from electron-builder) wins; this path is only consumed
-// by the `is.dev` branch below.
-const DEV_ICON_PATH = join(__dirname, "../../resources/icon.png");
 
 // macOS/Linux GUI launches inherit a minimal PATH from launchd that omits
 // the user's shell config (~/.zshrc, Homebrew, nvm, ~/.local/bin, etc.).
@@ -49,19 +43,6 @@ function handleDeepLink(url: string): void {
       if (token && mainWindow) {
         mainWindow.webContents.send("auth:token", token);
       }
-      return;
-    }
-
-    // multica://invite/<invitationId>
-    // Dispatched from the web invite page when the user chooses "Open in
-    // desktop app". The renderer opens the invite overlay — no tab, no
-    // route persistence, so deep-linking the same invite twice stays safe.
-    if (parsed.hostname === "invite") {
-      const id = parsed.pathname.replace(/^\//, "");
-      if (id && mainWindow) {
-        mainWindow.webContents.send("invite:open", decodeURIComponent(id));
-      }
-      return;
     }
   } catch {
     // Ignore malformed URLs
@@ -80,9 +61,6 @@ function createWindow(): void {
     trafficLightPosition: { x: 16, y: 13 },
     show: false,
     autoHideMenuBar: true,
-    // Windows/Linux pick up the window/taskbar icon from this option in
-    // dev — on macOS it's ignored (dock comes from app.dock.setIcon below).
-    ...(is.dev ? { icon: DEV_ICON_PATH } : {}),
     webPreferences: {
       preload: join(__dirname, "../preload/index.js"),
       sandbox: false,
@@ -105,7 +83,7 @@ function createWindow(): void {
   });
 
   mainWindow.webContents.setWindowOpenHandler((details) => {
-    openExternalSafely(details.url);
+    shell.openExternal(details.url);
     return { action: "deny" };
   });
 
@@ -116,27 +94,6 @@ function createWindow(): void {
   }
 }
 
-// --- Dev / production isolation -------------------------------------------
-// Give dev mode a separate app name and userData path so it gets its own
-// single-instance lock file and doesn't conflict with the packaged production
-// app. Must run BEFORE requestSingleInstanceLock() because the lock location
-// is derived from the userData path. (Same approach VS Code uses for
-// Stable / Insiders coexistence.)
-
-// DESKTOP_APP_SUFFIX lets parallel worktrees run dev Electron side-by-side
-// without fighting for the shared single-instance lock. The suffix is
-// appended to the app name + userData path, so each worktree gets its own
-// lock file. Default (no env var) keeps behavior unchanged — the common
-// single-worktree case still lands at "Multica Canary".
-const DEV_APP_NAME = process.env.DESKTOP_APP_SUFFIX
-  ? `Multica Canary ${process.env.DESKTOP_APP_SUFFIX}`
-  : "Multica Canary";
-
-if (is.dev) {
-  app.setName(DEV_APP_NAME);
-  app.setPath("userData", join(app.getPath("appData"), DEV_APP_NAME));
-}
-
 // --- Protocol registration -----------------------------------------------
 
 if (process.defaultApp) {
@@ -168,33 +125,19 @@ if (!gotTheLock) {
   });
 
   app.whenReady().then(() => {
-    electronApp.setAppUserModelId(
-      is.dev ? "ai.multica.desktop.dev" : "ai.multica.desktop",
-    );
-
-    // macOS: replace the default Electron dock icon with the bundled logo
-    // so the Canary dev build is visually distinct from a stock Electron
-    // run. `app.dock` is macOS-only — guard the call.
-    if (is.dev && process.platform === "darwin" && app.dock) {
-      const icon = nativeImage.createFromPath(DEV_ICON_PATH);
-      if (!icon.isEmpty()) app.dock.setIcon(icon);
-    }
+    electronApp.setAppUserModelId("ai.multica.desktop");
 
     app.on("browser-window-created", (_, window) => {
       optimizer.watchWindowShortcuts(window);
     });
 
-    // IPC: open URL in default browser (used by renderer for Google login).
-    // All scheme-allowlist enforcement lives in openExternalSafely — this
-    // is the single audit point for renderer-controlled URLs reaching the
-    // OS shell under the app's intentional webSecurity: false + sandbox:
-    // false configuration.
+    // IPC: open URL in default browser (used by renderer for Google login)
     ipcMain.handle("shell:openExternal", (_event, url: string) => {
-      return openExternalSafely(url);
+      return shell.openExternal(url);
     });
 
     // 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
+    // modals (create-workspace, onboarding) can place UI in the top-left corner
     // without fighting the native window controls' hit-test.
     ipcMain.handle("window:setImmersive", (_event, immersive: boolean) => {
       if (process.platform !== "darwin") return;

apps/desktop/src/main/updater.ts

@@ -1,31 +1,9 @@
 import { autoUpdater } from "electron-updater";
-import { app, BrowserWindow, ipcMain } from "electron";
+import { BrowserWindow, ipcMain } from "electron";
 
 autoUpdater.autoDownload = false;
 autoUpdater.autoInstallOnAppQuit = true;
 
-// Windows arm64 ships its own update metadata channel because
-// electron-builder's `latest.yml` is not arch-suffixed on Windows — both
-// arches would otherwise collide on the same file in the GitHub Release.
-// See scripts/package.mjs (builderArgsForTarget) for the publish-side half
-// of this pact. Pin the channel here so arm64 clients fetch
-// `latest-arm64.yml` instead of the x64 metadata.
-if (process.platform === "win32" && process.arch === "arm64") {
-  autoUpdater.channel = "latest-arm64";
-}
-
-const STARTUP_CHECK_DELAY_MS = 5_000;
-const PERIODIC_CHECK_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
-
-export type ManualUpdateCheckResult =
-  | {
-      ok: true;
-      currentVersion: string;
-      latestVersion: string;
-      available: boolean;
-    }
-  | { ok: false; error: string };
-
 export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): void {
   autoUpdater.on("update-available", (info) => {
     const win = getMainWindow();
@@ -59,42 +37,10 @@ export function setupAutoUpdater(getMainWindow: () => BrowserWindow | null): voi
     autoUpdater.quitAndInstall(false, true);
   });
 
-  ipcMain.handle("updater:check", async (): Promise<ManualUpdateCheckResult> => {
-    try {
-      const result = await autoUpdater.checkForUpdates();
-      const currentVersion = app.getVersion();
-      // Trust electron-updater's own decision rather than re-deriving it from
-      // a version-string compare. The two diverge for pre-release channels,
-      // staged rollouts, downgrades, and minimum-system-version gates — in
-      // those cases updateInfo.version differs from app.getVersion() but no
-      // `update-available` event fires, so showing "available" here would
-      // promise a download prompt that never appears.
-      return {
-        ok: true,
-        currentVersion,
-        latestVersion: result?.updateInfo.version ?? currentVersion,
-        available: result?.isUpdateAvailable ?? false,
-      };
-    } catch (err) {
-      return {
-        ok: false,
-        error: err instanceof Error ? err.message : String(err),
-      };
-    }
-  });
-
-  // Initial check shortly after startup so we don't block boot.
+  // Check for updates after a short delay to avoid blocking startup
   setTimeout(() => {
     autoUpdater.checkForUpdates().catch((err) => {
       console.error("Failed to check for updates:", err);
     });
-  }, STARTUP_CHECK_DELAY_MS);
-
-  // Background poll so long-running sessions still pick up new releases
-  // without requiring the user to restart the app.
-  setInterval(() => {
-    autoUpdater.checkForUpdates().catch((err) => {
-      console.error("Periodic update check failed:", err);
-    });
-  }, PERIODIC_CHECK_INTERVAL_MS);
+  }, 5000);
 }

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

@@ -3,8 +3,6 @@ import { ElectronAPI } from "@electron-toolkit/preload";
 interface DesktopAPI {
   /** Listen for auth token delivered via deep link. Returns an unsubscribe function. */
   onAuthToken: (callback: (token: string) => void) => () => void;
-  /** Listen for invitation IDs delivered via deep link. Returns an unsubscribe function. */
-  onInviteOpen: (callback: (invitationId: string) => void) => () => void;
   /** Open a URL in the default browser. */
   openExternal: (url: string) => Promise<void>;
   /** Hide macOS traffic lights for full-screen modals; restore when false. */
@@ -53,10 +51,6 @@ interface UpdaterAPI {
   onUpdateDownloaded: (callback: () => void) => () => void;
   downloadUpdate: () => Promise<void>;
   installUpdate: () => Promise<void>;
-  checkForUpdates: () => Promise<
-    | { ok: true; currentVersion: string; latestVersion: string; available: boolean }
-    | { ok: false; error: string }
-  >;
 }
 
 declare global {

apps/desktop/src/preload/index.ts

@@ -11,15 +11,6 @@ const desktopAPI = {
       ipcRenderer.removeListener("auth:token", handler);
     };
   },
-  /** Listen for invitation IDs delivered via deep link */
-  onInviteOpen: (callback: (invitationId: string) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, invitationId: string) =>
-      callback(invitationId);
-    ipcRenderer.on("invite:open", handler);
-    return () => {
-      ipcRenderer.removeListener("invite:open", handler);
-    };
-  },
   /** Open a URL in the default browser */
   openExternal: (url: string) => ipcRenderer.invoke("shell:openExternal", url),
   /** Toggle immersive mode — hide macOS traffic lights for full-screen modals */
@@ -96,10 +87,6 @@ const updaterAPI = {
   },
   downloadUpdate: () => ipcRenderer.invoke("updater:download"),
   installUpdate: () => ipcRenderer.invoke("updater:install"),
-  checkForUpdates: (): Promise<
-    | { ok: true; currentVersion: string; latestVersion: string; available: boolean }
-    | { ok: false; error: string }
-  > => ipcRenderer.invoke("updater:check"),
 };
 
 if (process.contextIsolated) {

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

@@ -1,8 +1,8 @@
-import { useEffect, useLayoutEffect, useRef, useState } from "react";
-import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
 import { CoreProvider } from "@multica/core/platform";
 import { useAuthStore } from "@multica/core/auth";
-import { workspaceKeys, workspaceListOptions } from "@multica/core/workspace/queries";
+import { workspaceKeys } from "@multica/core/workspace/queries";
 import { api } from "@multica/core/api";
 import { ThemeProvider } from "@multica/ui/components/common/theme-provider";
 import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
@@ -10,9 +10,6 @@ import { Toaster } from "sonner";
 import { DesktopLoginPage } from "./pages/login";
 import { DesktopShell } from "./components/desktop-layout";
 import { UpdateNotification } from "./components/update-notification";
-import { useTabStore } from "./stores/tab-store";
-import { useWindowOverlayStore } from "./stores/window-overlay-store";
-
 
 function AppContent() {
   const user = useAuthStore((s) => s.user);
@@ -23,8 +20,8 @@ function AppContent() {
   // as soon as getMe resolves, which would cause DesktopShell to mount
   // before the workspace list is hydrated and briefly see `!workspace`.
   // This local flag keeps the loading screen up until the whole chain
-  // finishes, so IndexRedirect gets a definitive workspace state on
-  // first render.
+  // finishes, so the shell's "needs onboarding?" check gets a definitive
+  // workspace state on first render.
   const [bootstrapping, setBootstrapping] = useState(false);
 
   // Tell the main process which backend URL we talk to, so daemon-manager
@@ -33,17 +30,6 @@ function AppContent() {
     window.daemonAPI.setTargetApiUrl(DAEMON_TARGET_API_URL);
   }, []);
 
-  // Listen for invite IDs delivered via deep link (multica://invite/<id>).
-  // We open the overlay regardless of login state — if the user isn't logged
-  // in, InvitePage's queries will fail and render the "not found" state,
-  // which is acceptable; the expected pre-flight happens in the web app
-  // (login + next=/invite/... dance) before the deep link is ever dispatched.
-  useEffect(() => {
-    return window.desktopAPI.onInviteOpen((invitationId) => {
-      useWindowOverlayStore.getState().open({ type: "invite", invitationId });
-    });
-  }, []);
-
   // Listen for auth token delivered via deep link (multica://auth/callback?token=...).
   // daemonAPI.syncToken is handled separately by the [user] effect below, which
   // fires whenever a user logs in (deep link, session restore, account switch).
@@ -83,73 +69,6 @@ function AppContent() {
     })();
   }, [user]);
 
-  // When a user who started the session with zero workspaces creates their
-  // first one, restart the daemon so it picks up the new workspace
-  // immediately (otherwise workspaceSyncLoop's next 30s tick would be the
-  // earliest pickup point). Specifically scoped to "started empty" because
-  // account switches (user A logout → user B login) should not trigger a
-  // daemon restart here — daemon-manager already restarts on user change
-  // via syncToken.
-  const { data: workspaces, isFetched: workspaceListFetched } = useQuery({
-    ...workspaceListOptions(),
-    enabled: !!user,
-  });
-  const wsCount = workspaces?.length ?? 0;
-
-  // Validate persisted tab state against the current user's workspace list,
-  // and pick an active workspace if none is set. Runs in useLayoutEffect
-  // (synchronously after render, before paint) rather than the render
-  // phase — the original render-phase pattern triggered React's
-  // "Cannot update a component while rendering a different component"
-  // warning because `switchWorkspace` is a Zustand setState that the
-  // TabBar is subscribed to. useLayoutEffect flushes both renders before
-  // the user sees anything, so there's no visible flicker.
-  useLayoutEffect(() => {
-    if (!workspaces) return;
-    const validSlugs = new Set(workspaces.map((w) => w.slug));
-    const tabStore = useTabStore.getState();
-    tabStore.validateWorkspaceSlugs(validSlugs);
-    if (!tabStore.activeWorkspaceSlug && workspaces.length > 0) {
-      tabStore.switchWorkspace(workspaces[0].slug);
-    }
-  }, [workspaces]);
-
-  // Bidirectional new-workspace overlay: visible when there are no
-  // workspaces to enter, hidden as soon as one exists. Gated on
-  // `workspaceListFetched` so the initial render doesn't flash the
-  // overlay before the list arrives. The overlay's own `invite` type is
-  // not touched here — that's an in-flight task owned by the user.
-  useEffect(() => {
-    if (!user) return;
-    if (!workspaceListFetched) return;
-    const { overlay, open, close } = useWindowOverlayStore.getState();
-    const isEmpty = wsCount === 0;
-    if (isEmpty) {
-      if (!overlay) open({ type: "new-workspace" });
-    } else if (overlay?.type === "new-workspace") {
-      close();
-    }
-  }, [user, workspaceListFetched, wsCount]);
-  // null = undecided (pre-login or list hasn't settled yet)
-  // true  = session started with zero workspaces; next transition to >=1 triggers restart
-  // false = session started with >=1 workspace, OR we've already restarted; skip
-  const sessionStartedEmptyRef = useRef<boolean | null>(null);
-  useEffect(() => {
-    if (!user) {
-      sessionStartedEmptyRef.current = null;
-      return;
-    }
-    if (!workspaceListFetched) return;
-    if (sessionStartedEmptyRef.current === null) {
-      sessionStartedEmptyRef.current = wsCount === 0;
-      return;
-    }
-    if (sessionStartedEmptyRef.current && wsCount >= 1) {
-      void window.daemonAPI.restart();
-      sessionStartedEmptyRef.current = false;
-    }
-  }, [user, workspaceListFetched, wsCount]);
-
   if (isLoading || bootstrapping) {
     return (
       <div className="flex h-screen items-center justify-center">
@@ -166,14 +85,9 @@ function AppContent() {
 const DAEMON_TARGET_API_URL =
   import.meta.env.VITE_API_URL || "http://localhost:8080";
 
-// On logout, wipe desktop-only in-memory state and stop the daemon so that
-// a subsequent login as a different user never inherits the previous user's
-// tabs, overlay, or credentials. Zustand persist only writes to localStorage;
-// useLogout clears the storage key, but the live stores stay populated until
-// we explicitly reset them here.
+// On logout, clear any cached PAT and stop the daemon so that a subsequent
+// login as a different user never inherits the previous user's credentials.
 async function handleDaemonLogout() {
-  useTabStore.getState().reset();
-  useWindowOverlayStore.getState().close();
   try {
     await window.daemonAPI.clearToken();
   } catch {

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

@@ -13,12 +13,13 @@ import { ModalRegistry } from "@multica/views/modals/registry";
 import { AppSidebar } from "@multica/views/layout";
 import { SearchCommand, SearchTrigger } from "@multica/views/search";
 import { ChatFab, ChatWindow } from "@multica/views/chat";
+import { StepWorkspace } from "@multica/views/onboarding";
 import { WorkspaceSlugProvider } from "@multica/core/paths";
 import { getCurrentSlug, subscribeToCurrentSlug } from "@multica/core/platform";
 import { DesktopNavigationProvider } from "@/platform/navigation";
+import { OnboardingGate } from "./onboarding-gate";
 import { TabBar } from "./tab-bar";
 import { TabContent } from "./tab-content";
-import { WindowOverlay } from "./window-overlay";
 
 function SidebarTopBar() {
   const { canGoBack, canGoForward, goBack, goForward } = useTabHistory();
@@ -108,34 +109,39 @@ export function DesktopShell() {
 
   return (
     <DesktopNavigationProvider>
-      {/* WorkspaceSlugProvider accepts null — components that need slug
-          use useWorkspaceSlug() (nullable) or useRequiredWorkspaceSlug()
-          (throws). TabContent MUST always render so the tab router can
-          mount WorkspaceRouteLayout, which calls setCurrentWorkspace()
-          to populate the slug. The sidebar gates on slug being present
-          to avoid the useRequiredWorkspaceSlug throw. Zero-workspace
-          users see the window-level overlay (new-workspace flow)
-          triggered by IndexRedirect, not a route. */}
-      <WorkspaceSlugProvider slug={slug}>
-        <div className="flex h-screen">
-          <SidebarProvider className="flex-1">
-            {slug && <AppSidebar topSlot={<SidebarTopBar />} searchSlot={<SearchTrigger />} />}
-            {/* Right side: header + content container */}
-            <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">
-                <TabContent />
-                {slug && <ChatWindow />}
-                {slug && <ChatFab />}
+      <OnboardingGate
+        onboarding={(onComplete) => (
+          <div className="flex min-h-screen items-center justify-center overflow-auto bg-background px-6 py-12">
+            <StepWorkspace onNext={onComplete} />
+          </div>
+        )}
+      >
+        {/* WorkspaceSlugProvider accepts null — components that need slug
+            use useWorkspaceSlug() (nullable) or useRequiredWorkspaceSlug()
+            (throws). TabContent MUST always render so the tab router can
+            mount WorkspaceRouteLayout, which calls setCurrentWorkspace()
+            to populate the slug. The sidebar gates on slug being present
+            to avoid the useRequiredWorkspaceSlug throw. */}
+        <WorkspaceSlugProvider slug={slug}>
+          <div className="flex h-screen">
+            <SidebarProvider className="flex-1">
+              {slug && <AppSidebar topSlot={<SidebarTopBar />} searchSlot={<SearchTrigger />} />}
+              {/* Right side: header + content container */}
+              <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">
+                  <TabContent />
+                  {slug && <ChatWindow />}
+                  {slug && <ChatFab />}
+                </div>
               </div>
-            </div>
-          </SidebarProvider>
-        </div>
-        {slug && <ModalRegistry />}
-        {slug && <SearchCommand />}
-        <WindowOverlay />
-      </WorkspaceSlugProvider>
+            </SidebarProvider>
+          </div>
+          {slug && <ModalRegistry />}
+          {slug && <SearchCommand />}
+        </WorkspaceSlugProvider>
+      </OnboardingGate>
     </DesktopNavigationProvider>
   );
 }

apps/desktop/src/renderer/src/components/onboarding-gate.test.tsx

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { workspaceKeys } from "@multica/core/workspace/queries";
+import { OnboardingGate } from "./onboarding-gate";
+
+// Prevent actual API calls — the tests seed data via setQueryData.
+vi.mock("@multica/core/api", () => ({
+  api: {
+    listWorkspaces: vi.fn().mockResolvedValue([]),
+  },
+}));
+
+function createTestQueryClient(
+  workspaces: Array<{ id: string; slug: string }> = [],
+) {
+  const qc = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  // Seed the workspace list so the gate can read it synchronously.
+  qc.setQueryData(workspaceKeys.list(), workspaces);
+  return qc;
+}
+
+function renderGate(
+  qc: QueryClient,
+  onboarding?: (onComplete: () => void) => React.ReactNode,
+) {
+  return render(
+    <QueryClientProvider client={qc}>
+      <OnboardingGate
+        onboarding={
+          onboarding ??
+          ((onComplete) => (
+            <button type="button" data-testid="finish" onClick={onComplete}>
+              wizard
+            </button>
+          ))
+        }
+      >
+        <div data-testid="main">main shell</div>
+      </OnboardingGate>
+    </QueryClientProvider>,
+  );
+}
+
+describe("OnboardingGate", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("renders children when workspaces exist in cache", () => {
+    const qc = createTestQueryClient([{ id: "ws-1", slug: "my-team" }]);
+    renderGate(qc);
+
+    expect(screen.getByTestId("main")).toBeInTheDocument();
+    expect(screen.queryByText("wizard")).not.toBeInTheDocument();
+  });
+
+  it("renders onboarding when workspace list is empty", () => {
+    const qc = createTestQueryClient([]);
+    renderGate(qc);
+
+    expect(screen.getByText("wizard")).toBeInTheDocument();
+    expect(screen.queryByTestId("main")).not.toBeInTheDocument();
+  });
+
+  it("keeps the wizard mounted even after workspaces appear in cache mid-flow", () => {
+    const qc = createTestQueryClient([]);
+    renderGate(qc);
+
+    expect(screen.getByText("wizard")).toBeInTheDocument();
+
+    // Simulate the onboarding wizard creating a workspace mid-flow.
+    act(() => {
+      qc.setQueryData(workspaceKeys.list(), [
+        { id: "ws-new", slug: "new-team" },
+      ]);
+    });
+
+    // Wizard should still be visible — only onComplete dismisses it.
+    expect(screen.getByText("wizard")).toBeInTheDocument();
+    expect(screen.queryByTestId("main")).not.toBeInTheDocument();
+  });
+
+  it("transitions to children after the wizard calls onComplete", () => {
+    const qc = createTestQueryClient([]);
+    renderGate(qc);
+
+    expect(screen.getByTestId("finish")).toBeInTheDocument();
+
+    act(() => {
+      screen.getByTestId("finish").click();
+    });
+
+    expect(screen.getByTestId("main")).toBeInTheDocument();
+    expect(screen.queryByTestId("finish")).not.toBeInTheDocument();
+  });
+});

apps/desktop/src/renderer/src/components/onboarding-gate.tsx

@@ -0,0 +1,40 @@
+import { useState, type ReactNode } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { workspaceListOptions } from "@multica/core/workspace/queries";
+
+/**
+ * Renders `onboarding` as a full-screen takeover when the user has no
+ * workspaces, otherwise renders `children`.
+ *
+ * Reads the workspace list directly from React Query — this works regardless
+ * of whether a WorkspaceSlugProvider is mounted, unlike useCurrentWorkspace()
+ * which depends on slug context from the router tree.
+ *
+ * The onboarding decision is frozen at first mount via the lazy useState
+ * initializer: this way the onboarding wizard controls its own exit by
+ * calling the `onComplete` callback, instead of being unmounted the moment
+ * the workspace list updates mid-flow (e.g. after the user creates their
+ * first workspace in step 1 but still has steps 2-3 to complete).
+ *
+ * The frozen decision only triggers when the initial query has settled AND
+ * the list is empty. While the list is loading, children are rendered
+ * (the shell shows its own loading state).
+ */
+export function OnboardingGate({
+  onboarding,
+  children,
+}: {
+  onboarding: (onComplete: () => void) => ReactNode;
+  children: ReactNode;
+}) {
+  const { data: workspaces, isFetched } = useQuery(workspaceListOptions());
+  const hasWorkspaces = !isFetched || (workspaces?.length ?? 0) > 0;
+
+  const [initialNeedsOnboarding] = useState(() => !hasWorkspaces);
+  const [onboardingDone, setOnboardingDone] = useState(false);
+
+  if (initialNeedsOnboarding && !onboardingDone) {
+    return <>{onboarding(() => setOnboardingDone(true))}</>;
+  }
+  return <>{children}</>;
+}

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

@@ -29,8 +29,7 @@ import {
 } from "@dnd-kit/modifiers";
 import { CSS } from "@dnd-kit/utilities";
 import { cn } from "@multica/ui/lib/utils";
-import { useTabStore, useActiveGroup, resolveRouteIcon, type Tab } from "@/stores/tab-store";
-import { paths } from "@multica/core/paths";
+import { useTabStore, resolveRouteIcon, type Tab } from "@/stores/tab-store";
 
 const TAB_ICONS: Record<string, LucideIcon> = {
   Inbox,
@@ -67,13 +66,16 @@ function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolea
   const handleClick = () => {
     if (isActive) return;
     setActiveTab(tab.id);
+    // No navigate() — Activity handles visibility
   };
 
   const handleClose = (e: React.MouseEvent) => {
     e.stopPropagation();
     closeTab(tab.id);
+    // No navigate() — store handles activeTabId switch
   };
 
+  // Stop pointer down on close so it doesn't start a drag on the parent button.
   const stopDragOnClose = (e: React.PointerEvent) => {
     e.stopPropagation();
   };
@@ -122,13 +124,10 @@ function NewTabButton() {
   const setActiveTab = useTabStore((s) => s.setActiveTab);
 
   const handleClick = () => {
-    // New tab opens in the currently active workspace — tabs are scoped
-    // per workspace, so there is no cross-workspace ambiguity to resolve.
-    const activeSlug = useTabStore.getState().activeWorkspaceSlug;
-    if (!activeSlug) return;
-    const path = paths.workspace(activeSlug).issues();
+    const path = "/issues";
     const tabId = addTab(path, "Issues", resolveRouteIcon(path));
-    if (tabId) setActiveTab(tabId);
+    setActiveTab(tabId);
+    // No navigate() — new tab's router starts at /issues automatically
   };
 
   return (
@@ -143,17 +142,17 @@ function NewTabButton() {
 }
 
 export function TabBar() {
-  const group = useActiveGroup();
+  const tabs = useTabStore((s) => s.tabs);
+  const activeTabId = useTabStore((s) => s.activeTabId);
   const moveTab = useTabStore((s) => s.moveTab);
 
+  // distance: 5 — pointer must move 5px to start a drag, otherwise it's a click.
   const sensors = useSensors(
     useSensor(PointerSensor, {
       activationConstraint: { distance: 5 },
     }),
   );
 
-  const tabs = group?.tabs ?? [];
-  const activeTabId = group?.activeTabId ?? "";
   const tabIds = tabs.map((t) => t.id);
 
   const handleDragEnd = (event: DragEndEvent) => {
@@ -183,7 +182,7 @@ export function TabBar() {
           ))}
         </SortableContext>
       </DndContext>
-      {group && <NewTabButton />}
+      <NewTabButton />
     </div>
   );
 }

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

@@ -1,52 +1,40 @@
 import { Activity, useEffect } from "react";
 import { RouterProvider } from "react-router-dom";
-import { useActiveGroup } from "@/stores/tab-store";
+import { useTabStore } from "@/stores/tab-store";
 import { TabNavigationProvider } from "@/platform/navigation";
 import { useTabRouterSync } from "@/hooks/use-tab-router-sync";
-import type { Tab } from "@/stores/tab-store";
 
-/**
- * Inner wrapper rendered inside each tab's RouterProvider. The router
- * reference is stable for a tab's lifetime, so passing it in directly
- * (instead of re-deriving from the store) avoids needless re-renders.
- */
-function TabRouterInner({ tab }: { tab: Tab }) {
-  useTabRouterSync(tab.id, tab.router);
+/** Inner wrapper rendered inside each tab's RouterProvider. */
+function TabRouterInner({ tabId }: { tabId: string }) {
+  const tab = useTabStore((s) => s.tabs.find((t) => t.id === tabId));
+  useTabRouterSync(tabId, tab!.router);
   return null;
 }
 
 /**
- * Renders the active workspace's tabs using Activity for state preservation.
+ * Renders all tabs using Activity for state preservation.
  * Only the active tab is visible; hidden tabs keep their DOM and React state.
- *
- * When switching workspaces, the previous workspace's tabs unmount entirely
- * and the new workspace's tabs mount fresh — cross-workspace state
- * preservation is an explicit non-goal (keeping all workspaces' tabs warm
- * simultaneously would bloat memory and make workspace switching feel
- * anything but "switching").
  */
 export function TabContent() {
-  const group = useActiveGroup();
+  const tabs = useTabStore((s) => s.tabs);
+  const activeTabId = useTabStore((s) => s.activeTabId);
 
-  // Sync document.title when switching tabs within the active workspace.
+  // Sync document.title when switching tabs
   useEffect(() => {
-    if (!group) return;
-    const tab = group.tabs.find((t) => t.id === group.activeTabId);
+    const tab = tabs.find((t) => t.id === activeTabId);
     if (tab) document.title = tab.title;
-  }, [group?.activeTabId, group?.tabs]);
-
-  if (!group) return null;
+  }, [activeTabId, tabs]);
 
   return (
     <>
-      {group.tabs.map((tab) => (
+      {tabs.map((tab) => (
         <Activity
           key={tab.id}
-          mode={tab.id === group.activeTabId ? "visible" : "hidden"}
+          mode={tab.id === activeTabId ? "visible" : "hidden"}
         >
           <TabNavigationProvider router={tab.router}>
             <RouterProvider router={tab.router} />
-            <TabRouterInner tab={tab} />
+            <TabRouterInner tabId={tab.id} />
           </TabNavigationProvider>
         </Activity>
       ))}

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

@@ -1,86 +0,0 @@
-import { useCallback, useState } from "react";
-import { AlertCircle, ArrowDownToLine, Check, Loader2 } from "lucide-react";
-import { Button } from "@multica/ui/components/ui/button";
-
-type CheckState =
-  | { status: "idle" }
-  | { status: "checking" }
-  | { status: "up-to-date"; currentVersion: string }
-  | { status: "available"; latestVersion: string }
-  | { status: "error"; message: string };
-
-export function UpdatesSettingsTab() {
-  const [state, setState] = useState<CheckState>({ status: "idle" });
-
-  const handleCheck = useCallback(async () => {
-    setState({ status: "checking" });
-    const result = await window.updater.checkForUpdates();
-    if (!result.ok) {
-      setState({ status: "error", message: result.error });
-      return;
-    }
-    setState(
-      result.available
-        ? { status: "available", latestVersion: result.latestVersion }
-        : { status: "up-to-date", currentVersion: result.currentVersion },
-    );
-  }, []);
-
-  return (
-    <div>
-      <h2 className="text-lg font-semibold">Updates</h2>
-      <p className="text-sm text-muted-foreground mt-1">
-        The desktop app checks for new versions automatically once an hour and
-        shortly after launch.
-      </p>
-
-      <div className="mt-6 divide-y">
-        <div className="flex items-start justify-between gap-6 py-4">
-          <div className="min-w-0">
-            <p className="text-sm font-medium">Check for updates</p>
-            <p className="text-sm text-muted-foreground mt-0.5">
-              Trigger a check now instead of waiting for the next automatic
-              poll. Available updates appear as a notification in the corner.
-            </p>
-            {state.status === "up-to-date" && (
-              <p className="text-sm text-muted-foreground mt-2 inline-flex items-center gap-1.5">
-                <Check className="size-3.5 text-success" />
-                You&apos;re on the latest version (v{state.currentVersion}).
-              </p>
-            )}
-            {state.status === "available" && (
-              <p className="text-sm text-muted-foreground mt-2 inline-flex items-center gap-1.5">
-                <ArrowDownToLine className="size-3.5 text-primary" />
-                v{state.latestVersion} is available — see the download prompt
-                in the corner.
-              </p>
-            )}
-            {state.status === "error" && (
-              <p className="text-sm text-destructive mt-2 inline-flex items-center gap-1.5">
-                <AlertCircle className="size-3.5" />
-                {state.message}
-              </p>
-            )}
-          </div>
-          <div className="shrink-0">
-            <Button
-              variant="outline"
-              size="sm"
-              onClick={handleCheck}
-              disabled={state.status === "checking"}
-            >
-              {state.status === "checking" ? (
-                <>
-                  <Loader2 className="size-3.5 animate-spin" />
-                  Checking…
-                </>
-              ) : (
-                "Check now"
-              )}
-            </Button>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}

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

@@ -1,85 +0,0 @@
-import { useQuery } from "@tanstack/react-query";
-import { useImmersiveMode } from "@multica/views/platform";
-import { NewWorkspacePage } from "@multica/views/workspace/new-workspace-page";
-import { InvitePage } from "@multica/views/invite";
-import { useNavigation } from "@multica/views/navigation";
-import { paths } from "@multica/core/paths";
-import { workspaceListOptions } from "@multica/core/workspace/queries";
-import { useWindowOverlayStore } from "@/stores/window-overlay-store";
-
-/**
- * Window-level transition overlay: renders above the tab system when the
- * user is in a pre-workspace flow (create workspace, accept invite).
- *
- * This component is a thin **platform shell**:
- *  - Hands the window-drag strip and macOS traffic-light hiding
- *    (`useImmersiveMode`) — both are platform-specific, web has neither
- *  - Covers the tab system (fixed inset, z-50) so the Shell's own TabBar
- *    doesn't leak through
- *
- * All UX affordances (Back button, Log out button, welcome copy, invite
- * card) live inside the shared `NewWorkspacePage` / `InvitePage`
- * components under `packages/views/`, so web and desktop render identical
- * content. The platform split is: UX in shared code, chrome here.
- */
-export function WindowOverlay() {
-  const overlay = useWindowOverlayStore((s) => s.overlay);
-  if (!overlay) return null;
-  return <WindowOverlayInner />;
-}
-
-function WindowOverlayInner() {
-  const overlay = useWindowOverlayStore((s) => s.overlay);
-  const close = useWindowOverlayStore((s) => s.close);
-  const { push } = useNavigation();
-  const { data: wsList = [] } = useQuery(workspaceListOptions());
-
-  useImmersiveMode();
-
-  if (!overlay) return null;
-
-  // Back is only meaningful when there's somewhere to go — i.e. the user
-  // has at least one workspace. Zero-workspace users can only Log out or
-  // complete the flow.
-  const onBack = wsList.length > 0 ? close : undefined;
-
-  return (
-    <div className="fixed inset-0 z-50 flex flex-col bg-background">
-      {/* Window-drag strip. Rendered as a flex *child* (not absolute
-          overlay) so it owns its own 48px of real layout space — the
-          prior absolute-positioned approach relied on z-index stacking
-          to beat the content wrapper's no-drag, which in practice didn't
-          hit-test reliably for `-webkit-app-region` on the welcome
-          screen. A real flex row with nothing else in it has no such
-          ambiguity: any pixel at top-48 is drag, full stop.
-
-          Height matches `MainTopBar` (48px) so the drag-to-grab area
-          feels consistent with the rest of the app. The strip is
-          invisible; macOS traffic lights would normally sit here but
-          `useImmersiveMode` has hidden them for the overlay's lifetime. */}
-      <div
-        aria-hidden
-        className="h-12 shrink-0"
-        style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
-      />
-
-      <div
-        className="flex-1 min-h-0 overflow-auto"
-        style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
-      >
-        {overlay.type === "new-workspace" && (
-          <NewWorkspacePage
-            onSuccess={(ws) => push(paths.workspace(ws.slug).issues())}
-            onBack={onBack}
-          />
-        )}
-        {overlay.type === "invite" && (
-          <InvitePage
-            invitationId={overlay.invitationId}
-            onBack={onBack}
-          />
-        )}
-      </div>
-    </div>
-  );
-}

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

@@ -1,32 +1,21 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { Outlet, useNavigate, useParams } from "react-router-dom";
 import { useQuery } from "@tanstack/react-query";
 import { WorkspaceSlugProvider, paths } from "@multica/core/paths";
+import { workspaceBySlugOptions } from "@multica/core/workspace";
 import {
-  workspaceBySlugOptions,
-  workspaceListOptions,
-} from "@multica/core/workspace";
-import { setCurrentWorkspace } from "@multica/core/platform";
+  setCurrentWorkspace,
+  rehydrateAllWorkspaceStores,
+} from "@multica/core/platform";
 import { useAuthStore } from "@multica/core/auth";
-import { useWorkspaceSeen } from "@multica/views/workspace/use-workspace-seen";
-import { useTabStore } from "@/stores/tab-store";
 
 /**
  * Desktop equivalent of apps/web/app/[workspaceSlug]/layout.tsx.
  *
- * Resolves the URL slug → workspace UUID via the React Query list cache
- * (seeded by AuthInitializer). Children do not render until the workspace
- * is fully resolved — useWorkspaceId() inside child pages is therefore
- * guaranteed non-null when called. Two industry-standard identities are
- * kept distinct: slug (URL / browser) and UUID (API / cache keys).
- *
- * Unlike web, desktop never renders a "workspace not available" page: the
- * app has no URL bar and no clickable links from outside the session, so
- * landing on an inaccessible slug can only mean stale state (a persisted
- * tab group for a workspace the current user no longer has access to, or
- * active eviction). Both cases resolve by dropping the stale tab group
- * from the tab store — the TabBar then renders a different workspace or
- * the WindowOverlay takes over (zero valid workspaces).
+ * Reads :workspaceSlug from react-router params, resolves it to a Workspace
+ * object via the React Query list cache, and syncs the URL-derived workspace
+ * into the platform singleton (slug + UUID). Children (DashboardGuard +
+ * dashboard layout) handle auth check, loading, and workspace-not-found.
  */
 export function WorkspaceRouteLayout() {
   const { workspaceSlug } = useParams<{ workspaceSlug: string }>();
@@ -34,51 +23,34 @@ export function WorkspaceRouteLayout() {
   const user = useAuthStore((s) => s.user);
   const isAuthLoading = useAuthStore((s) => s.isLoading);
 
-  // Workspace routes require auth. If user is unauthenticated, bounce to /login.
-  useEffect(() => {
-    if (!isAuthLoading && !user) navigate(paths.login(), { replace: true });
-  }, [isAuthLoading, user, navigate]);
-
   const { data: workspace, isFetched: listFetched } = useQuery({
     ...workspaceBySlugOptions(workspaceSlug ?? ""),
     enabled: !!user && !!workspaceSlug,
   });
 
-  const { data: wsList } = useQuery({
-    ...workspaceListOptions(),
-    enabled: !!user,
-  });
-
-  // Feed the URL slug into the platform singleton so the API client's
-  // X-Workspace-Slug header and persist namespace follow the active tab.
-  // setCurrentWorkspace self-dedupes on slug equality.
-  if (workspace && workspaceSlug) {
+  // Render-phase sync (same pattern as web layout).
+  const syncedSlugRef = useRef<string | null>(null);
+  if (workspace && workspaceSlug && syncedSlugRef.current !== workspaceSlug) {
     setCurrentWorkspace(workspaceSlug, workspace.id);
+    rehydrateAllWorkspaceStores();
+    // Double-write legacy localStorage key for rollback compatibility — see
+    // apps/web/app/[workspaceSlug]/layout.tsx for the full rationale.
+    try {
+      localStorage.setItem("multica_workspace_id", workspace.id);
+    } catch {
+      // non-critical
+    }
+    syncedSlugRef.current = workspaceSlug;
   }
 
-  const hasBeenSeen = useWorkspaceSeen(workspaceSlug, !!workspace);
-
-  // Stale-slug auto-heal: when this tab's slug fails to resolve, drop the
-  // whole workspace group from the tab store. Per-workspace tab grouping
-  // means the cleanup is a single validator call — the TabContent will
-  // unmount this tab (and all siblings in the stale group) once the store
-  // updates. We don't navigate this tab's router because the tab's path
-  // is scoped to the stale slug; navigating to "/" would create an
-  // inconsistent "tab in group X with path /" state.
+  // Slug doesn't resolve → onboarding. Skip when user is null.
   useEffect(() => {
     if (!user) return;
-    if (!listFetched) return;
-    if (workspace) return;
-    if (hasBeenSeen) return; // active eviction in flight — let the other path win
-    if (!wsList) return;
-    const validSlugs = new Set(wsList.map((w) => w.slug));
-    useTabStore.getState().validateWorkspaceSlugs(validSlugs);
-  }, [user, listFetched, workspace, hasBeenSeen, wsList]);
+    if (listFetched && !workspace) navigate(paths.onboarding(), { replace: true });
+  }, [user, listFetched, workspace, navigate]);
 
   if (isAuthLoading) return null;
   if (!workspaceSlug) return null;
-  if (!listFetched) return null;
-  if (!workspace) return null; // auto-heal effect above handles the cleanup
 
   return (
     <WorkspaceSlugProvider slug={workspaceSlug}>

apps/desktop/src/renderer/src/hooks/use-tab-history.ts

@@ -1,6 +1,6 @@
 import { useCallback } from "react";
 import type { DataRouter } from "react-router-dom";
-import { useActiveTabRouter, useActiveTabHistory } from "@/stores/tab-store";
+import { useTabStore } from "@/stores/tab-store";
 
 /**
  * Shared hint map so useTabRouterSync can distinguish back vs forward POP.
@@ -9,32 +9,32 @@ import { useActiveTabRouter, useActiveTabHistory } from "@/stores/tab-store";
 export const popDirectionHints = new Map<DataRouter, "back" | "forward">();
 
 /**
- * Per-tab back/forward navigation derived from the active workspace's
- * active tab.
- *
- * Subscribed via primitive selectors so this hook only re-renders when
- * the numeric history state actually changes — path ticks on the active
- * tab (which don't shift historyIndex) don't churn the back/forward
- * buttons.
+ * Per-tab back/forward navigation derived from the active tab's history state.
+ * Replaces the old global useNavigationHistory() hook.
  */
 export function useTabHistory() {
-  const router = useActiveTabRouter();
-  const { historyIndex, historyLength } = useActiveTabHistory();
+  // Return the actual tab object from the store — stable reference.
+  // Do NOT create a new object in the selector (causes infinite re-renders).
+  const activeTab = useTabStore((s) =>
+    s.tabs.find((t) => t.id === s.activeTabId),
+  );
 
-  const canGoBack = historyIndex > 0;
-  const canGoForward = historyIndex < historyLength - 1;
+  const canGoBack = (activeTab?.historyIndex ?? 0) > 0;
+  const canGoForward =
+    (activeTab?.historyIndex ?? 0) < (activeTab?.historyLength ?? 1) - 1;
 
   const goBack = useCallback(() => {
-    if (!router || historyIndex <= 0) return;
-    popDirectionHints.set(router, "back");
-    router.navigate(-1);
-  }, [router, historyIndex]);
+    if (!activeTab || activeTab.historyIndex <= 0) return;
+    popDirectionHints.set(activeTab.router, "back");
+    activeTab.router.navigate(-1);
+  }, [activeTab]);
 
   const goForward = useCallback(() => {
-    if (!router || historyIndex >= historyLength - 1) return;
-    popDirectionHints.set(router, "forward");
-    router.navigate(1);
-  }, [router, historyIndex, historyLength]);
+    if (!activeTab || activeTab.historyIndex >= activeTab.historyLength - 1)
+      return;
+    popDirectionHints.set(activeTab.router, "forward");
+    activeTab.router.navigate(1);
+  }, [activeTab]);
 
   return { canGoBack, canGoForward, goBack, goForward };
 }

apps/desktop/src/renderer/src/hooks/use-tab-sync.ts

@@ -2,23 +2,20 @@ import { useEffect } from "react";
 import { useTabStore } from "@/stores/tab-store";
 
 /**
- * Watches document.title via MutationObserver and updates the active tab's
- * title. Pages set document.title via TitleSync (route handle.title) or
- * useDocumentTitle(). This observer picks up the change and syncs it to
- * the tab store.
+ * Watches document.title via MutationObserver and updates the active tab's title.
+ *
+ * Pages set document.title via TitleSync (route handle.title) or useDocumentTitle().
+ * This observer picks up the change and syncs it to the tab store.
  */
 export function useActiveTitleSync() {
   useEffect(() => {
     const observer = new MutationObserver(() => {
       const title = document.title;
       if (!title) return;
-      const state = useTabStore.getState();
-      if (!state.activeWorkspaceSlug) return;
-      const group = state.byWorkspace[state.activeWorkspaceSlug];
-      if (!group) return;
-      const activeTab = group.tabs.find((t) => t.id === group.activeTabId);
+      const { tabs, activeTabId } = useTabStore.getState();
+      const activeTab = tabs.find((t) => t.id === activeTabId);
       if (activeTab && activeTab.title !== title) {
-        state.updateTab(activeTab.id, { title });
+        useTabStore.getState().updateTab(activeTabId, { title });
       }
     });
 

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

@@ -5,94 +5,16 @@ import {
   type NavigationAdapter,
 } from "@multica/views/navigation";
 import { useAuthStore } from "@multica/core/auth";
-import { isReservedSlug } from "@multica/core/paths";
-import {
-  useTabStore,
-  resolveRouteIcon,
-  useActiveTabIdentity,
-  useActiveTabRouter,
-  getActiveTab,
-} from "@/stores/tab-store";
-import { useWindowOverlayStore } from "@/stores/window-overlay-store";
+import { useTabStore, resolveRouteIcon } from "@/stores/tab-store";
 
-// Public web app URL — injected at build time via .env.production. In dev
-// (no VITE_APP_URL set) falls back to the local web dev server so "Copy
-// link" in a dev build yields a URL that points at the running dev
-// frontend, not the prod host. Matches the fallback used in pages/login.tsx.
-const APP_URL = import.meta.env.VITE_APP_URL || "http://localhost:3000";
+// Public web app URL — injected at build time via .env.production. Falls
+// back to the production host for dev builds so "Copy link" yields a URL
+// that actually points somewhere a teammate can open.
+const APP_URL = import.meta.env.VITE_APP_URL || "https://multica.ai";
 
 /**
- * Extract the leading workspace slug from a path, or null if the path isn't
- * workspace-scoped (root, login, any reserved prefix).
- */
-function extractWorkspaceSlug(path: string): string | null {
-  const first = path.split("/").filter(Boolean)[0] ?? "";
-  if (!first) return null;
-  if (isReservedSlug(first)) return null;
-  return first;
-}
-
-/**
- * Intercept navigation to "transition" paths — pre-workspace flows that on
- * desktop are rendered as a window-level overlay instead of a tab route.
- * Returns `true` if the navigation was handled (caller should NOT proceed).
- *
- * Side effect: when opening the new-workspace overlay, the tab router is
- * ALSO reset to "/". Rationale — the only way a push lands on
- * /workspaces/new is that the workspace context is gone (fresh install,
- * delete-last, leave-last). Leaving the tab parked on a workspace-scoped
- * path would keep those components mounted under the overlay; the next
- * render after the list cache updates would then throw (useWorkspaceId
- * etc) because the slug no longer resolves.
- */
-function tryRouteToOverlay(path: string, router?: DataRouter): boolean {
-  const overlay = useWindowOverlayStore.getState();
-  if (path === "/workspaces/new") {
-    overlay.open({ type: "new-workspace" });
-    if (router && router.state.location.pathname !== "/") {
-      router.navigate("/", { replace: true });
-    }
-    return true;
-  }
-  if (path.startsWith("/invite/")) {
-    let id = "";
-    try {
-      id = decodeURIComponent(path.slice("/invite/".length));
-    } catch {
-      return true;
-    }
-    if (id) {
-      overlay.open({ type: "invite", invitationId: id });
-      return true;
-    }
-  }
-  // Any other navigation cancels a live overlay.
-  if (overlay.overlay) overlay.close();
-  return false;
-}
-
-/**
- * Intercept pushes that change workspace. Returns `true` if the navigation
- * was delegated to the tab store (caller should NOT proceed).
- *
- * This is the entry point that makes shared code platform-agnostic:
- * sidebar dropdown, cmd+k "switch workspace", post-delete redirects,
- * invite-accept flow — they all call `useNavigation().push(path)` with a
- * full workspace URL, and on desktop we translate "target slug differs
- * from active" into "switch the tab-group that's visible in the TabBar".
- */
-function tryRouteToOtherWorkspace(path: string): boolean {
-  const targetSlug = extractWorkspaceSlug(path);
-  if (!targetSlug) return false;
-  const { activeWorkspaceSlug, switchWorkspace } = useTabStore.getState();
-  if (targetSlug === activeWorkspaceSlug) return false;
-  switchWorkspace(targetSlug, path);
-  return true;
-}
-
-/**
- * Root-level navigation provider for components outside the per-tab
- * RouterProviders (sidebar, search dialog, modals, WindowOverlay contents).
+ * Root-level navigation provider for components outside the per-tab RouterProviders
+ * (sidebar, search dialog, modals, etc.).
  *
  * Reads from the active tab's memory router via router.subscribe().
  * Does NOT use any react-router hooks — it's above all RouterProviders.
@@ -102,61 +24,50 @@ export function DesktopNavigationProvider({
 }: {
   children: React.ReactNode;
 }) {
-  // Primitive-only subscriptions so this component doesn't re-render on
-  // unrelated store updates (e.g. an inactive tab's router tick). We
-  // resolve the active router here only to subscribe once per tab switch.
-  const { tabId: activeTabId } = useActiveTabIdentity();
-  const router = useActiveTabRouter();
-  const [pathname, setPathname] = useState(
-    router?.state.location.pathname ?? "/",
-  );
+  const activeTab = useTabStore((s) => s.tabs.find((t) => t.id === s.activeTabId));
+  const [pathname, setPathname] = useState(activeTab?.path ?? "/issues");
 
+  // Subscribe to the active tab's router for pathname updates
   useEffect(() => {
-    if (!router) {
-      setPathname("/");
-      return;
-    }
-    setPathname(router.state.location.pathname);
-    return router.subscribe((state) => {
+    if (!activeTab) return;
+    setPathname(activeTab.router.state.location.pathname);
+    return activeTab.router.subscribe((state) => {
       setPathname(state.location.pathname);
     });
-  }, [activeTabId, router]);
+  }, [activeTab?.id]); // eslint-disable-line react-hooks/exhaustive-deps
 
   const adapter: NavigationAdapter = useMemo(
     () => ({
       push: (path: string) => {
         if (path === "/login") {
+          // DashboardGuard token expired — force back to login screen
           useAuthStore.getState().logout();
           return;
         }
-        const active = currentActiveTab();
-        if (tryRouteToOverlay(path, active?.router)) return;
-        if (tryRouteToOtherWorkspace(path)) return;
-        active?.router.navigate(path);
+        const tab = useTabStore.getState().tabs.find(
+          (t) => t.id === useTabStore.getState().activeTabId,
+        );
+        tab?.router.navigate(path);
       },
       replace: (path: string) => {
-        const active = currentActiveTab();
-        if (tryRouteToOverlay(path, active?.router)) return;
-        if (tryRouteToOtherWorkspace(path)) return;
-        active?.router.navigate(path, { replace: true });
+        const tab = useTabStore.getState().tabs.find(
+          (t) => t.id === useTabStore.getState().activeTabId,
+        );
+        tab?.router.navigate(path, { replace: true });
       },
       back: () => {
-        currentActiveTab()?.router.navigate(-1);
+        const tab = useTabStore.getState().tabs.find(
+          (t) => t.id === useTabStore.getState().activeTabId,
+        );
+        tab?.router.navigate(-1);
       },
       pathname,
       searchParams: new URLSearchParams(),
       openInNewTab: (path: string, title?: string) => {
-        // Cross-workspace "open in new tab" switches workspace and opens
-        // the path there; same-workspace just adds a tab in the current group.
-        const slug = extractWorkspaceSlug(path);
-        const store = useTabStore.getState();
-        if (slug && slug !== store.activeWorkspaceSlug) {
-          store.switchWorkspace(slug, path);
-          return;
-        }
         const icon = resolveRouteIcon(path);
+        const store = useTabStore.getState();
         const tabId = store.openTab(path, title ?? path, icon);
-        if (tabId) store.setActiveTab(tabId);
+        store.setActiveTab(tabId);
       },
       getShareableUrl: (path: string) => `${APP_URL}${path}`,
     }),
@@ -166,10 +77,6 @@ export function DesktopNavigationProvider({
   return <NavigationProvider value={adapter}>{children}</NavigationProvider>;
 }
 
-function currentActiveTab() {
-  return getActiveTab(useTabStore.getState());
-}
-
 /**
  * Per-tab navigation provider rendered inside each tab's Activity wrapper.
  * Subscribes to the tab's own router for up-to-date pathname.
@@ -194,29 +101,16 @@ export function TabNavigationProvider({
 
   const adapter: NavigationAdapter = useMemo(
     () => ({
-      push: (path: string) => {
-        if (tryRouteToOverlay(path, router)) return;
-        if (tryRouteToOtherWorkspace(path)) return;
-        router.navigate(path);
-      },
-      replace: (path: string) => {
-        if (tryRouteToOverlay(path, router)) return;
-        if (tryRouteToOtherWorkspace(path)) return;
-        router.navigate(path, { replace: true });
-      },
+      push: (path: string) => router.navigate(path),
+      replace: (path: string) => router.navigate(path, { replace: true }),
       back: () => router.navigate(-1),
       pathname: location.pathname,
       searchParams: new URLSearchParams(location.search),
       openInNewTab: (path: string, title?: string) => {
-        const slug = extractWorkspaceSlug(path);
-        const store = useTabStore.getState();
-        if (slug && slug !== store.activeWorkspaceSlug) {
-          store.switchWorkspace(slug, path);
-          return;
-        }
         const icon = resolveRouteIcon(path);
-        const tabId = store.openTab(path, title ?? path, icon);
-        if (tabId) store.setActiveTab(tabId);
+        const store = useTabStore.getState();
+        const newTabId = store.openTab(path, title ?? path, icon);
+        store.setActiveTab(newTabId);
       },
       getShareableUrl: (path: string) => `${APP_URL}${path}`,
     }),

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

@@ -6,6 +6,7 @@ import {
   useMatches,
 } from "react-router-dom";
 import type { RouteObject } from "react-router-dom";
+import { useQuery } from "@tanstack/react-query";
 import { IssueDetailPage } from "./pages/issue-detail-page";
 import { ProjectDetailPage } from "./pages/project-detail-page";
 import { AutopilotDetailPage } from "./pages/autopilot-detail-page";
@@ -19,9 +20,13 @@ import { DaemonRuntimeCard } from "./components/daemon-runtime-card";
 import { AgentsPage } from "@multica/views/agents";
 import { InboxPage } from "@multica/views/inbox";
 import { SettingsPage } from "@multica/views/settings";
-import { Download, Server } from "lucide-react";
+import { OnboardingWizard } from "@multica/views/onboarding";
+import { InvitePage } from "@multica/views/invite";
+import { useNavigation } from "@multica/views/navigation";
+import { paths } from "@multica/core/paths";
+import { workspaceListOptions } from "@multica/core/workspace/queries";
+import { Server } from "lucide-react";
 import { DaemonSettingsTab } from "./components/daemon-settings-tab";
-import { UpdatesSettingsTab } from "./components/updates-settings-tab";
 import { WorkspaceRouteLayout } from "./components/workspace-route-layout";
 
 /**
@@ -54,28 +59,76 @@ function PageShell() {
   );
 }
 
+function OnboardingRoute() {
+  const nav = useNavigation();
+  return (
+    <OnboardingWizard
+      onComplete={(ws) => nav.push(paths.workspace(ws.slug).issues())}
+    />
+  );
+}
+
+/**
+ * Root index route: resolves the URL-less `/` path to a concrete destination.
+ *
+ * Runs both on first login (App.tsx seeded the cache) and on app reopen
+ * (AuthInitializer seeded the cache). Reading from React Query avoids
+ * duplicate fetches across tabs — each tab's memory router hits this
+ * component independently but the query is deduped.
+ *
+ * Sends first-time users without any workspace to onboarding, everyone
+ * else to their first workspace's issues page. Persisted tab paths that
+ * already carry a workspace slug bypass this component entirely.
+ */
+function IndexRedirect() {
+  const { data: wsList, isFetched } = useQuery(workspaceListOptions());
+
+  // Wait for the query to settle so we don't redirect to onboarding on
+  // the initial render before the seeded/fetched data arrives.
+  if (!isFetched) return null;
+
+  const firstWorkspace = wsList?.[0];
+  if (firstWorkspace) {
+    return <Navigate to={paths.workspace(firstWorkspace.slug).issues()} replace />;
+  }
+  return <Navigate to={paths.onboarding()} replace />;
+}
+
+function InviteRoute() {
+  const matches = useMatches();
+  const match = matches.find((m) => (m.params as { id?: string }).id);
+  const id = (match?.params as { id?: string })?.id ?? "";
+  return <InvitePage invitationId={id} />;
+}
+
 /**
  * Route definitions shared by all tabs.
  *
- * Every tab path is workspace-scoped: `/{slug}/{route}/...`. Pre-workspace
- * flows (create workspace, accept invite) are NOT routes — they render as a
- * window-level overlay via `WindowOverlay`, dispatched by the navigation
- * adapter's transition-path interception. The `activeWorkspaceSlug` in the
- * tab store decides which workspace's tabs are visible in the TabBar;
- * workspace-less state (zero-workspace user) shows the overlay instead.
- *
- * The root index route stays as a harmless safety net. With per-workspace
- * tabs, nothing should construct a tab at `/` — but if one ever slips
- * through (malformed persisted state that dodges the migration, direct
- * router.navigate from unforeseen code), the index falls back to null
- * rather than 404; App.tsx's bootstrap repoints activeWorkspaceSlug on the
- * next render pass.
+ * Structure mirrors the web app's [workspaceSlug]/... layout: all dashboard
+ * pages live under /:workspaceSlug, with WorkspaceRouteLayout resolving the
+ * slug to a workspace and syncing side-effects (api client, persist namespace,
+ * Zustand mirror). Global (pre-workspace) routes — onboarding and invite —
+ * sit at the top level alongside the workspace wrapper.
  */
 export const appRoutes: RouteObject[] = [
   {
     element: <PageShell />,
     children: [
-      { index: true, element: null },
+      // Top-level index: no slug yet. `IndexRedirect` reads the workspace
+      // list from React Query cache (seeded by AuthInitializer on reopen
+      // or App.tsx on deep-link login) and bounces to the first
+      // workspace's issues page — or onboarding if the user has none.
+      { index: true, element: <IndexRedirect /> },
+      {
+        path: "onboarding",
+        element: <OnboardingRoute />,
+        handle: { title: "Get Started" },
+      },
+      {
+        path: "invite/:id",
+        element: <InviteRoute />,
+        handle: { title: "Accept Invite" },
+      },
       {
         path: ":workspaceSlug",
         element: <WorkspaceRouteLayout />,
@@ -131,12 +184,6 @@ export const appRoutes: RouteObject[] = [
                     icon: Server,
                     content: <DaemonSettingsTab />,
                   },
-                  {
-                    value: "updates",
-                    label: "Updates",
-                    icon: Download,
-                    content: <UpdatesSettingsTab />,
-                  },
                 ]}
               />
             ),

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

@@ -1,224 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from "vitest";
-
-// createTabRouter transitively pulls in route modules that expect a browser
-// router context. For pure store tests we stub it to a minimal disposable.
-const createTabRouterMock = vi.hoisted(() =>
-  vi.fn(() => ({
-    dispose: vi.fn(),
-    state: { location: { pathname: "/" } },
-    navigate: vi.fn(),
-    subscribe: vi.fn(() => () => {}),
-  })),
-);
-vi.mock("../routes", () => ({
-  createTabRouter: createTabRouterMock,
-}));
-
-import {
-  sanitizeTabPath,
-  migrateV1ToV2,
-  useTabStore,
-} from "./tab-store";
-
-beforeEach(() => {
-  createTabRouterMock.mockClear();
-  useTabStore.getState().reset();
-});
-
-describe("sanitizeTabPath", () => {
-  it("rejects the root sentinel — tabs must be workspace-scoped", () => {
-    expect(sanitizeTabPath("/")).toBeNull();
-    expect(sanitizeTabPath("")).toBeNull();
-  });
-
-  it("silently rejects transition paths (no warn — navigation adapter intercepts them)", () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    expect(sanitizeTabPath("/workspaces/new")).toBeNull();
-    expect(sanitizeTabPath("/invite/abc")).toBeNull();
-    expect(warn).not.toHaveBeenCalled();
-    warn.mockRestore();
-  });
-
-  it("passes through valid workspace-scoped paths", () => {
-    expect(sanitizeTabPath("/acme/issues")).toBe("/acme/issues");
-    expect(sanitizeTabPath("/my-team/projects/abc")).toBe("/my-team/projects/abc");
-  });
-
-  it("rejects paths whose first segment is a reserved slug (missing workspace prefix)", () => {
-    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
-    expect(sanitizeTabPath("/issues")).toBeNull();
-    expect(sanitizeTabPath("/settings")).toBeNull();
-    expect(warn).toHaveBeenCalled();
-    warn.mockRestore();
-  });
-
-  it("passes through user slugs that happen to look path-like but aren't reserved", () => {
-    expect(sanitizeTabPath("/acme-issues/issues")).toBe("/acme-issues/issues");
-    expect(sanitizeTabPath("/project-x/inbox")).toBe("/project-x/inbox");
-  });
-});
-
-describe("migrateV1ToV2", () => {
-  it("groups v1 flat tabs by workspace slug", () => {
-    const v1 = {
-      tabs: [
-        { id: "t1", path: "/acme/issues", title: "Issues", icon: "ListTodo" },
-        { id: "t2", path: "/acme/projects", title: "Projects", icon: "FolderKanban" },
-        { id: "t3", path: "/butter/issues", title: "Issues", icon: "ListTodo" },
-      ],
-      activeTabId: "t2",
-    };
-    const v2 = migrateV1ToV2(v1);
-    expect(Object.keys(v2.byWorkspace).sort()).toEqual(["acme", "butter"]);
-    expect(v2.byWorkspace.acme.tabs).toHaveLength(2);
-    expect(v2.byWorkspace.butter.tabs).toHaveLength(1);
-    expect(v2.byWorkspace.acme.activeTabId).toBe("t2");
-    expect(v2.byWorkspace.butter.activeTabId).toBe("t3"); // first tab in group
-    expect(v2.activeWorkspaceSlug).toBe("acme"); // contained v1.activeTabId
-  });
-
-  it("drops tabs at root / transition / reserved-slug paths", () => {
-    const v1 = {
-      tabs: [
-        { id: "t1", path: "/", title: "Issues", icon: "ListTodo" },
-        { id: "t2", path: "/workspaces/new", title: "New", icon: "Plus" },
-        { id: "t3", path: "/invite/abc", title: "Invite", icon: "Mail" },
-        { id: "t4", path: "/acme/issues", title: "Issues", icon: "ListTodo" },
-      ],
-      activeTabId: "t1",
-    };
-    const v2 = migrateV1ToV2(v1);
-    expect(Object.keys(v2.byWorkspace)).toEqual(["acme"]);
-    expect(v2.byWorkspace.acme.tabs).toHaveLength(1);
-    // v1.activeTabId was dropped; active falls back to first group's first tab.
-    expect(v2.activeWorkspaceSlug).toBe("acme");
-    expect(v2.byWorkspace.acme.activeTabId).toBe("t4");
-  });
-
-  it("handles empty v1 state gracefully", () => {
-    const v2 = migrateV1ToV2({ tabs: [], activeTabId: "" });
-    expect(v2.byWorkspace).toEqual({});
-    expect(v2.activeWorkspaceSlug).toBeNull();
-  });
-
-  it("handles v1 with no tabs field (corrupted state)", () => {
-    const v2 = migrateV1ToV2({});
-    expect(v2.byWorkspace).toEqual({});
-    expect(v2.activeWorkspaceSlug).toBeNull();
-  });
-});
-
-describe("useTabStore actions", () => {
-  it("switchWorkspace creates a new group with a default tab on first entry", () => {
-    useTabStore.getState().switchWorkspace("acme");
-    const s = useTabStore.getState();
-    expect(s.activeWorkspaceSlug).toBe("acme");
-    expect(s.byWorkspace.acme.tabs).toHaveLength(1);
-    expect(s.byWorkspace.acme.tabs[0].path).toBe("/acme/issues");
-  });
-
-  it("switchWorkspace without openPath restores the group's last active tab", () => {
-    const store = useTabStore.getState();
-    store.switchWorkspace("acme");
-    store.addTab("/acme/projects", "Projects", "FolderKanban");
-    const acmeProjectsId = useTabStore.getState().byWorkspace.acme.tabs[1].id;
-    store.setActiveTab(acmeProjectsId);
-
-    // Enter a different workspace then come back
-    store.switchWorkspace("butter");
-    expect(useTabStore.getState().activeWorkspaceSlug).toBe("butter");
-
-    store.switchWorkspace("acme");
-    const s = useTabStore.getState();
-    expect(s.activeWorkspaceSlug).toBe("acme");
-    expect(s.byWorkspace.acme.activeTabId).toBe(acmeProjectsId);
-  });
-
-  it("switchWorkspace with openPath dedupes into an existing tab with same path", () => {
-    const store = useTabStore.getState();
-    store.switchWorkspace("acme"); // creates default /acme/issues
-    store.addTab("/acme/projects", "Projects", "FolderKanban");
-
-    store.switchWorkspace("acme", "/acme/issues");
-    const s = useTabStore.getState();
-    expect(s.byWorkspace.acme.tabs).toHaveLength(2); // no duplicate created
-    const activeTab = s.byWorkspace.acme.tabs.find(
-      (t) => t.id === s.byWorkspace.acme.activeTabId,
-    );
-    expect(activeTab?.path).toBe("/acme/issues");
-  });
-
-  it("switchWorkspace with openPath not matching any tab adds a new tab", () => {
-    const store = useTabStore.getState();
-    store.switchWorkspace("acme");
-    store.switchWorkspace("acme", "/acme/issues/bug-42");
-    const s = useTabStore.getState();
-    expect(s.byWorkspace.acme.tabs).toHaveLength(2);
-    const activeTab = s.byWorkspace.acme.tabs.find(
-      (t) => t.id === s.byWorkspace.acme.activeTabId,
-    );
-    expect(activeTab?.path).toBe("/acme/issues/bug-42");
-  });
-
-  it("openTab dedupes by path within the active workspace", () => {
-    const store = useTabStore.getState();
-    store.switchWorkspace("acme");
-    const id1 = store.openTab("/acme/projects", "Projects", "FolderKanban");
-    const id2 = store.openTab("/acme/projects", "Projects", "FolderKanban");
-    expect(id1).toBe(id2);
-    expect(useTabStore.getState().byWorkspace.acme.tabs).toHaveLength(2); // default + projects
-  });
-
-  it("closeTab on the last tab in a workspace reseeds the default tab", () => {
-    const store = useTabStore.getState();
-    store.switchWorkspace("acme");
-    const onlyTabId = useTabStore.getState().byWorkspace.acme.tabs[0].id;
-    store.closeTab(onlyTabId);
-    const s = useTabStore.getState();
-    expect(s.byWorkspace.acme.tabs).toHaveLength(1);
-    expect(s.byWorkspace.acme.tabs[0].path).toBe("/acme/issues");
-    expect(s.byWorkspace.acme.tabs[0].id).not.toBe(onlyTabId); // fresh tab
-  });
-
-  it("validateWorkspaceSlugs drops groups for slugs not in the valid set and repoints active", () => {
-    const store = useTabStore.getState();
-    store.switchWorkspace("acme");
-    store.switchWorkspace("butter");
-    store.switchWorkspace("acme");
-    expect(useTabStore.getState().activeWorkspaceSlug).toBe("acme");
-
-    // Admin removed the user from acme
-    store.validateWorkspaceSlugs(new Set(["butter"]));
-    const s = useTabStore.getState();
-    expect(Object.keys(s.byWorkspace)).toEqual(["butter"]);
-    expect(s.activeWorkspaceSlug).toBe("butter");
-  });
-
-  it("validateWorkspaceSlugs sets activeWorkspaceSlug to null when all groups are dropped", () => {
-    const store = useTabStore.getState();
-    store.switchWorkspace("acme");
-    store.validateWorkspaceSlugs(new Set());
-    const s = useTabStore.getState();
-    expect(s.byWorkspace).toEqual({});
-    expect(s.activeWorkspaceSlug).toBeNull();
-  });
-
-  it("reset wipes the whole store", () => {
-    const store = useTabStore.getState();
-    store.switchWorkspace("acme");
-    store.switchWorkspace("butter");
-    store.reset();
-    const s = useTabStore.getState();
-    expect(s.activeWorkspaceSlug).toBeNull();
-    expect(s.byWorkspace).toEqual({});
-  });
-
-  it("setActiveTab across workspaces also flips the active workspace", () => {
-    const store = useTabStore.getState();
-    store.switchWorkspace("acme");
-    store.switchWorkspace("butter");
-    const acmeTabId = useTabStore.getState().byWorkspace.acme.tabs[0].id;
-    store.setActiveTab(acmeTabId);
-    expect(useTabStore.getState().activeWorkspaceSlug).toBe("acme");
-  });
-});

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

@@ -3,7 +3,7 @@ import { createJSONStorage, persist } from "zustand/middleware";
 import { arrayMove } from "@dnd-kit/sortable";
 import { createPersistStorage, defaultStorage } from "@multica/core/platform";
 import { createSafeId } from "@multica/core/utils";
-import { isReservedSlug } from "@multica/core/paths";
+import { isGlobalPath } from "@multica/core/paths";
 import type { DataRouter } from "react-router-dom";
 import { createTabRouter } from "../routes";
 
@@ -13,7 +13,6 @@ import { createTabRouter } from "../routes";
 
 export interface Tab {
   id: string;
-  /** Every tab path is workspace-scoped: `/{workspaceSlug}/{route}/...`. */
   path: string;
   title: string;
   icon: string;
@@ -22,77 +21,24 @@ export interface Tab {
   historyLength: number;
 }
 
-export interface WorkspaceTabGroup {
-  tabs: Tab[];
-  /** Must be a valid tab.id in `tabs`; the empty-tabs state is transient only. */
-  activeTabId: string;
-}
-
 interface TabStore {
-  /**
-   * The workspace currently visible in the TabBar / TabContent. Null in three
-   * cases:
-   *   - Fresh install, before any workspace exists or is selected.
-   *   - Logged-out state (reset() wipes it).
-   *   - Every workspace the user had access to got deleted / revoked.
-   * When null, TabContent renders nothing and the WindowOverlay takes over.
-   */
-  activeWorkspaceSlug: string | null;
+  tabs: Tab[];
+  activeTabId: string;
 
-  /**
-   * Tab groups keyed by workspace slug. Each slug maps to an independent
-   * (tabs, activeTabId) pair; switching workspaces swaps the visible set
-   * without affecting any other group. Cross-workspace tab leakage — the
-   * bug that drove this refactor — is impossible by construction because
-   * there is no global tab array anymore.
-   */
-  byWorkspace: Record<string, WorkspaceTabGroup>;
-
-  /**
-   * Switch to a workspace.
-   *   - If the group doesn't exist yet, create it with a single default tab.
-   *   - If `openPath` is given, find a tab with that exact path and activate
-   *     it; otherwise add a new tab and activate it.
-   *   - If `openPath` is omitted, restore the group's last active tab
-   *     (VSCode / Slack behavior — workspaces resume where you left off).
-   */
-  switchWorkspace: (slug: string, openPath?: string) => void;
-  /** Open-or-activate (dedupes by path) a tab in the active workspace. */
+  /** Open a background tab. Deduplicates by path. Returns the tab id. */
   openTab: (path: string, title: string, icon: string) => string;
-  /** Always creates a new tab (no dedupe) in the active workspace. */
+  /** Always create a new tab (no dedup). Returns the tab id. */
   addTab: (path: string, title: string, icon: string) => string;
-  /**
-   * Close a tab. Finds it across all workspaces (callers like the X button
-   * only know the tab id, not the owning workspace). If this is the last
-   * tab in its workspace, reseed a default tab so the invariant
-   * "every live workspace has at least one tab" holds.
-   */
+  /** Close a tab. Disposes router. */
   closeTab: (tabId: string) => void;
-  /**
-   * Activate a tab. Finds it across all workspaces. Sets both the owning
-   * workspace as active and that group's activeTabId; needed for any code
-   * path that "jumps" to a tab belonging to a non-active workspace.
-   */
+  /** Switch to a tab by id. */
   setActiveTab: (tabId: string) => void;
-  /** Patch metadata of a tab (router-sync, title-sync). Finds across groups. */
+  /** Update a tab's metadata (path, title, icon — partial). */
   updateTab: (tabId: string, patch: Partial<Pick<Tab, "path" | "title" | "icon">>) => void;
-  /** Patch history tracking of a tab. Finds across groups. */
+  /** Update a tab's history tracking. */
   updateTabHistory: (tabId: string, historyIndex: number, historyLength: number) => void;
-  /** Reorder within the active workspace's group only. */
+  /** Reorder tabs by moving one from fromIndex to toIndex. Preserves router/history. */
   moveTab: (fromIndex: number, toIndex: number) => void;
-  /**
-   * After the workspace list arrives/changes (login, realtime delete), drop
-   * any tab group whose slug is no longer in `validSlugs`, and repoint
-   * `activeWorkspaceSlug` if it pointed at one of the dropped groups.
-   */
-  validateWorkspaceSlugs: (validSlugs: Set<string>) => void;
-  /**
-   * Wipe everything. Called from logout so the next user doesn't inherit
-   * the prior user's tabs. Zustand persist only writes to localStorage;
-   * clearing the storage key alone would leave this live store intact
-   * until app restart.
-   */
-  reset: () => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -112,70 +58,38 @@ const ROUTE_ICONS: Record<string, string> = {
 };
 
 /**
- * Resolve a route icon from a pathname.
+ * Resolve a route icon from a pathname. Title is NOT determined here — it
+ * comes from document.title.
  *
- * Tab paths are always workspace-scoped: `/{slug}/{route}/...`, so the route
- * segment lives at index 1. Pre-workspace flows (create, invite) are rendered
- * by the window overlay, never as tabs.
+ * Path shape after the workspace URL refactor:
+ *  - workspace-scoped: `/{workspaceSlug}/{route}/...` → use segment index 1
+ *  - global (onboarding/invite/auth/login): `/{route}/...` → use segment index 0
  *
- * Title is NOT determined here — it comes from document.title.
+ * `isGlobalPath` is the single source of truth for which prefixes are global.
  */
 export function resolveRouteIcon(pathname: string): string {
   const segments = pathname.split("/").filter(Boolean);
-  return ROUTE_ICONS[segments[1] ?? ""] ?? "ListTodo";
-}
-
-/** Extract the leading workspace slug from a path, or null if the path
- *  isn't workspace-scoped (global path, root, or empty). */
-function extractWorkspaceSlug(path: string): string | null {
-  const first = path.split("/").filter(Boolean)[0] ?? "";
-  if (!first) return null;
-  if (isReservedSlug(first)) return null;
-  return first;
+  const routeSegment = isGlobalPath(pathname)
+    ? (segments[0] ?? "")
+    : (segments[1] ?? "");
+  return ROUTE_ICONS[routeSegment] ?? "ListTodo";
 }
 
 // ---------------------------------------------------------------------------
-// Path sanitization (defensive)
+// Store
 // ---------------------------------------------------------------------------
 
 /**
- * Defensive: catch paths that don't belong in the tab store.
+ * Sentinel path for new tabs with no explicit destination. The tab store is
+ * workspace-implicit — it doesn't know which workspace is active, so it can't
+ * build a `/:slug/issues` path itself. Instead we hand off to the router: `/`
+ * matches the top-level index route, which redirects to the workspace default
+ * (slug-aware redirect lives in routes.tsx / App.tsx).
  *
- * Two kinds of rejects:
- *  1. **Transition paths** (`/workspaces/new`, `/invite/...`). These are
- *     pre-workspace flows rendered by the window overlay on desktop, not
- *     tab routes. The navigation adapter normally intercepts these before
- *     they reach the store; this guard catches older persisted state.
- *  2. **Malformed workspace-scoped paths** like a stray `/issues/abc` that
- *     was constructed without the workspace prefix. The router would
- *     interpret `issues` as a workspace slug → NoAccessPage.
- *
- * Returns null for rejects (caller decides how to recover — usually by
- * dropping the tab or substituting a default). Unlike the prior design,
- * there is no root "/" sentinel — tabs are always scoped.
+ * `title` and `icon` on the placeholder tab get overwritten by
+ * useTabRouterSync + useActiveTitleSync once the redirect resolves.
  */
-export function sanitizeTabPath(path: string): string | null {
-  const firstSegment = path.split("/").filter(Boolean)[0] ?? "";
-  if (!firstSegment) return null;
-  if (isReservedSlug(firstSegment)) {
-    // Don't log for known transition paths — these are legitimate inputs
-    // at the interception boundary (older persisted state or stale callers).
-    const isTransition = path === "/workspaces/new" || path.startsWith("/invite/");
-    if (!isTransition) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        `[tab-store] tab path "${path}" starts with reserved slug "${firstSegment}" — ` +
-          `caller likely forgot the workspace prefix. Dropping.`,
-      );
-    }
-    return null;
-  }
-  return path;
-}
-
-// ---------------------------------------------------------------------------
-// Tab factory
-// ---------------------------------------------------------------------------
+const DEFAULT_PATH = "/";
 
 function createId(): string {
   return createSafeId();
@@ -193,513 +107,128 @@ function makeTab(path: string, title: string, icon: string): Tab {
   };
 }
 
-/** Default entry point for a workspace — its issues list. */
-function defaultPathFor(slug: string): string {
-  return `/${slug}/issues`;
-}
-
-function defaultTabFor(slug: string): Tab {
-  const path = defaultPathFor(slug);
-  return makeTab(path, "Issues", resolveRouteIcon(path));
-}
-
-// ---------------------------------------------------------------------------
-// Group helpers
-// ---------------------------------------------------------------------------
-
-function findTabLocation(
-  byWorkspace: Record<string, WorkspaceTabGroup>,
-  tabId: string,
-): { slug: string; group: WorkspaceTabGroup; index: number } | null {
-  for (const slug of Object.keys(byWorkspace)) {
-    const group = byWorkspace[slug];
-    const index = group.tabs.findIndex((t) => t.id === tabId);
-    if (index >= 0) return { slug, group, index };
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Store
-// ---------------------------------------------------------------------------
+const initialTab = makeTab(DEFAULT_PATH, "Issues", resolveRouteIcon(DEFAULT_PATH));
 
 export const useTabStore = create<TabStore>()(
   persist(
     (set, get) => ({
-      activeWorkspaceSlug: null,
-      byWorkspace: {},
+  tabs: [initialTab],
+  activeTabId: initialTab.id,
 
-      switchWorkspace(slug, openPath) {
-        // Defensive no-op if slug is empty/invalid — callers like the
-        // NavigationAdapter's path-parser should already have filtered
-        // these, but belt-and-braces keeps garbage out of the store.
-        if (!slug) return;
-        const { byWorkspace } = get();
-        const existing = byWorkspace[slug];
+  openTab(path, title, icon) {
+    const { tabs } = get();
+    const existing = tabs.find((t) => t.path === path);
+    if (existing) return existing.id;
 
-        // Decide the desired active path for this workspace.
-        const desiredPath = openPath ?? (existing ? null : defaultPathFor(slug));
+    const tab = makeTab(path, title, icon);
+    set({ tabs: [...tabs, tab] });
+    return tab.id;
+  },
 
-        if (!existing) {
-          // First time entering this workspace — create the group.
-          const seedPath =
-            desiredPath && sanitizeTabPath(desiredPath) === desiredPath
-              ? desiredPath
-              : defaultPathFor(slug);
-          const tab = makeTab(seedPath, "Issues", resolveRouteIcon(seedPath));
-          set({
-            activeWorkspaceSlug: slug,
-            byWorkspace: {
-              ...byWorkspace,
-              [slug]: { tabs: [tab], activeTabId: tab.id },
-            },
-          });
-          return;
-        }
+  addTab(path, title, icon) {
+    const tab = makeTab(path, title, icon);
+    set((s) => ({ tabs: [...s.tabs, tab] }));
+    return tab.id;
+  },
 
-        // Workspace already has tabs. Either dedupe into an existing tab or
-        // add a new one (when openPath was supplied and no tab matches it).
-        if (desiredPath) {
-          const clean = sanitizeTabPath(desiredPath);
-          if (clean) {
-            const match = existing.tabs.find((t) => t.path === clean);
-            if (match) {
-              set({
-                activeWorkspaceSlug: slug,
-                byWorkspace: {
-                  ...byWorkspace,
-                  [slug]: { ...existing, activeTabId: match.id },
-                },
-              });
-              return;
-            }
-            const tab = makeTab(clean, "Issues", resolveRouteIcon(clean));
-            set({
-              activeWorkspaceSlug: slug,
-              byWorkspace: {
-                ...byWorkspace,
-                [slug]: {
-                  tabs: [...existing.tabs, tab],
-                  activeTabId: tab.id,
-                },
-              },
-            });
-            return;
-          }
-        }
+  closeTab(tabId) {
+    const { tabs, activeTabId } = get();
 
-        // No openPath (or openPath was rejected) — just restore the group.
-        set({ activeWorkspaceSlug: slug });
-      },
+    const closingTab = tabs.find((t) => t.id === tabId);
 
-      openTab(path, title, icon) {
-        const { activeWorkspaceSlug, byWorkspace } = get();
-        const clean = sanitizeTabPath(path);
-        if (!activeWorkspaceSlug || !clean) return "";
-        const group = byWorkspace[activeWorkspaceSlug];
-        if (!group) return "";
+    // Never close the last tab — replace with default
+    if (tabs.length === 1) {
+      closingTab?.router.dispose();
+      const fresh = makeTab(DEFAULT_PATH, "Issues", resolveRouteIcon(DEFAULT_PATH));
+      set({ tabs: [fresh], activeTabId: fresh.id });
+      return;
+    }
 
-        const existing = group.tabs.find((t) => t.path === clean);
-        if (existing) {
-          set({
-            byWorkspace: {
-              ...byWorkspace,
-              [activeWorkspaceSlug]: { ...group, activeTabId: existing.id },
-            },
-          });
-          return existing.id;
-        }
+    const idx = tabs.findIndex((t) => t.id === tabId);
+    if (idx === -1) return;
 
-        const tab = makeTab(clean, title, icon);
-        set({
-          byWorkspace: {
-            ...byWorkspace,
-            [activeWorkspaceSlug]: {
-              tabs: [...group.tabs, tab],
-              activeTabId: group.activeTabId,
-            },
-          },
-        });
-        return tab.id;
-      },
+    closingTab?.router.dispose();
+    const next = tabs.filter((t) => t.id !== tabId);
 
-      addTab(path, title, icon) {
-        const { activeWorkspaceSlug, byWorkspace } = get();
-        const clean = sanitizeTabPath(path);
-        if (!activeWorkspaceSlug || !clean) return "";
-        const group = byWorkspace[activeWorkspaceSlug];
-        if (!group) return "";
+    if (tabId === activeTabId) {
+      const newActive = next[Math.min(idx, next.length - 1)];
+      set({ tabs: next, activeTabId: newActive.id });
+    } else {
+      set({ tabs: next });
+    }
+  },
 
-        const tab = makeTab(clean, title, icon);
-        set({
-          byWorkspace: {
-            ...byWorkspace,
-            [activeWorkspaceSlug]: {
-              tabs: [...group.tabs, tab],
-              activeTabId: group.activeTabId,
-            },
-          },
-        });
-        return tab.id;
-      },
+  setActiveTab(tabId) {
+    set({ activeTabId: tabId });
+  },
 
-      closeTab(tabId) {
-        const { byWorkspace } = get();
-        const hit = findTabLocation(byWorkspace, tabId);
-        if (!hit) return;
-        const { slug, group, index } = hit;
+  updateTab(tabId, patch) {
+    set((s) => ({
+      tabs: s.tabs.map((t) =>
+        t.id === tabId ? { ...t, ...patch } : t,
+      ),
+    }));
+  },
 
-        const closing = group.tabs[index];
-        closing.router.dispose();
+  updateTabHistory(tabId, historyIndex, historyLength) {
+    set((s) => ({
+      tabs: s.tabs.map((t) =>
+        t.id === tabId ? { ...t, historyIndex, historyLength } : t,
+      ),
+    }));
+  },
 
-        if (group.tabs.length === 1) {
-          // Last tab in this workspace — reseed a default so the workspace
-          // always has at least one tab. Closing a workspace as an explicit
-          // action is a separate concern (Leave/Delete in Settings).
-          const fresh = defaultTabFor(slug);
-          set({
-            byWorkspace: {
-              ...byWorkspace,
-              [slug]: { tabs: [fresh], activeTabId: fresh.id },
-            },
-          });
-          return;
-        }
-
-        const nextTabs = group.tabs.filter((t) => t.id !== tabId);
-        const nextActiveTabId =
-          group.activeTabId === tabId
-            ? nextTabs[Math.min(index, nextTabs.length - 1)].id
-            : group.activeTabId;
-
-        set({
-          byWorkspace: {
-            ...byWorkspace,
-            [slug]: { tabs: nextTabs, activeTabId: nextActiveTabId },
-          },
-        });
-      },
-
-      setActiveTab(tabId) {
-        const { byWorkspace, activeWorkspaceSlug } = get();
-        const hit = findTabLocation(byWorkspace, tabId);
-        if (!hit) return;
-        const { slug, group } = hit;
-        if (slug === activeWorkspaceSlug && group.activeTabId === tabId) return;
-        set({
-          activeWorkspaceSlug: slug,
-          byWorkspace: {
-            ...byWorkspace,
-            [slug]: { ...group, activeTabId: tabId },
-          },
-        });
-      },
-
-      updateTab(tabId, patch) {
-        const { byWorkspace } = get();
-        const hit = findTabLocation(byWorkspace, tabId);
-        if (!hit) return;
-        const { slug, group, index } = hit;
-        const current = group.tabs[index];
-        const next: Tab = { ...current, ...patch };
-        const nextTabs = [...group.tabs];
-        nextTabs[index] = next;
-        set({
-          byWorkspace: {
-            ...byWorkspace,
-            [slug]: { ...group, tabs: nextTabs },
-          },
-        });
-      },
-
-      updateTabHistory(tabId, historyIndex, historyLength) {
-        const { byWorkspace } = get();
-        const hit = findTabLocation(byWorkspace, tabId);
-        if (!hit) return;
-        const { slug, group, index } = hit;
-        const current = group.tabs[index];
-        const next: Tab = { ...current, historyIndex, historyLength };
-        const nextTabs = [...group.tabs];
-        nextTabs[index] = next;
-        set({
-          byWorkspace: {
-            ...byWorkspace,
-            [slug]: { ...group, tabs: nextTabs },
-          },
-        });
-      },
-
-      moveTab(fromIndex, toIndex) {
-        if (fromIndex === toIndex) return;
-        const { activeWorkspaceSlug, byWorkspace } = get();
-        if (!activeWorkspaceSlug) return;
-        const group = byWorkspace[activeWorkspaceSlug];
-        if (!group) return;
-        set({
-          byWorkspace: {
-            ...byWorkspace,
-            [activeWorkspaceSlug]: {
-              ...group,
-              tabs: arrayMove(group.tabs, fromIndex, toIndex),
-            },
-          },
-        });
-      },
-
-      validateWorkspaceSlugs(validSlugs) {
-        const { activeWorkspaceSlug, byWorkspace } = get();
-        let changed = false;
-        const nextByWorkspace: Record<string, WorkspaceTabGroup> = {};
-        for (const slug of Object.keys(byWorkspace)) {
-          if (validSlugs.has(slug)) {
-            nextByWorkspace[slug] = byWorkspace[slug];
-          } else {
-            changed = true;
-            for (const t of byWorkspace[slug].tabs) t.router.dispose();
-          }
-        }
-
-        let nextActive = activeWorkspaceSlug;
-        if (nextActive && !validSlugs.has(nextActive)) {
-          nextActive = Object.keys(nextByWorkspace)[0] ?? null;
-          changed = true;
-        }
-
-        if (!changed) return;
-        set({ byWorkspace: nextByWorkspace, activeWorkspaceSlug: nextActive });
-      },
-
-      reset() {
-        const { byWorkspace } = get();
-        for (const slug of Object.keys(byWorkspace)) {
-          for (const t of byWorkspace[slug].tabs) t.router.dispose();
-        }
-        set({ activeWorkspaceSlug: null, byWorkspace: {} });
-      },
+  moveTab(fromIndex, toIndex) {
+    if (fromIndex === toIndex) return;
+    set((s) => ({ tabs: arrayMove(s.tabs, fromIndex, toIndex) }));
+  },
     }),
     {
       name: "multica_tabs",
-      version: 2,
+      version: 1,
       storage: createJSONStorage(() => createPersistStorage(defaultStorage)),
-      migrate: (persistedState, version) => {
-        // v1 → v2: flat `tabs` array → per-workspace grouping.
-        // Tabs whose path isn't workspace-scoped (root `/`, login, etc.)
-        // are dropped — they have no workspace to belong to, and the new
-        // model's invariant is "every tab lives in a workspace group".
-        if (version < 2 && persistedState && typeof persistedState === "object") {
-          return migrateV1ToV2(persistedState as Partial<V1Persisted>);
-        }
-        return persistedState as V2Persisted;
-      },
       partialize: (state) => ({
-        activeWorkspaceSlug: state.activeWorkspaceSlug,
-        byWorkspace: Object.fromEntries(
-          Object.entries(state.byWorkspace).map(([slug, group]) => [
-            slug,
-            {
-              activeTabId: group.activeTabId,
-              tabs: group.tabs.map(
-                ({ router: _router, historyIndex: _hi, historyLength: _hl, ...rest }) =>
-                  rest,
-              ),
-            },
-          ]),
+        tabs: state.tabs.map(
+          ({ router, historyIndex, historyLength, ...rest }) => rest,
         ),
+        activeTabId: state.activeTabId,
       }),
       merge: (persistedState, currentState) => {
-        const persisted = persistedState as Partial<V2Persisted> | undefined;
-        if (!persisted?.byWorkspace) return currentState;
+        const persisted = persistedState as
+          | Pick<TabStore, "tabs" | "activeTabId">
+          | undefined;
+        if (!persisted?.tabs?.length) return currentState;
 
-        const byWorkspace: Record<string, WorkspaceTabGroup> = {};
-        for (const [slug, pGroup] of Object.entries(persisted.byWorkspace)) {
-          const tabs: Tab[] = [];
-          for (const pTab of pGroup.tabs) {
-            const clean = sanitizeTabPath(pTab.path);
-            // Persisted path may have come from a stale version or a
-            // manual edit. Drop rather than rewrite so we never silently
-            // put users on a path that doesn't match the group's slug.
-            if (!clean || extractWorkspaceSlug(clean) !== slug) {
-              // eslint-disable-next-line no-console
-              console.warn(
-                `[tab-store] dropping persisted tab "${pTab.path}" from ` +
-                  `group "${slug}" — path/slug mismatch`,
-              );
-              continue;
+        const tabs: Tab[] = persisted.tabs.map((tab) => {
+          // Migration: pre-refactor tab paths like "/issues/abc" lack a
+          // workspace slug prefix. These would 404 in the new router.
+          // Reset to "/" so IndexRedirect picks the right workspace.
+          let path = tab.path;
+          if (path !== "/" && !isGlobalPath(path)) {
+            const segments = path.split("/").filter(Boolean);
+            const firstSegment = segments[0] ?? "";
+            // If the first segment IS a known route name (e.g. "issues",
+            // "projects"), it's an old-format path missing the slug prefix.
+            if (ROUTE_ICONS[firstSegment]) {
+              path = "/";
             }
-            tabs.push({
-              id: pTab.id,
-              path: clean,
-              title: pTab.title,
-              icon: pTab.icon,
-              router: createTabRouter(clean),
-              historyIndex: 0,
-              historyLength: 1,
-            });
           }
-          if (tabs.length === 0) continue;
-          const activeTabId = tabs.some((t) => t.id === pGroup.activeTabId)
-            ? pGroup.activeTabId
-            : tabs[0].id;
-          byWorkspace[slug] = { tabs, activeTabId };
-        }
+          return {
+            ...tab,
+            path,
+            router: createTabRouter(path),
+            historyIndex: 0,
+            historyLength: 1,
+          };
+        });
 
-        const activeWorkspaceSlug =
-          persisted.activeWorkspaceSlug && byWorkspace[persisted.activeWorkspaceSlug]
-            ? persisted.activeWorkspaceSlug
-            : (Object.keys(byWorkspace)[0] ?? null);
+        // Validate activeTabId — fall back to first tab if stale
+        const activeTabId = tabs.some((t) => t.id === persisted.activeTabId)
+          ? persisted.activeTabId
+          : tabs[0].id;
 
-        return { ...currentState, byWorkspace, activeWorkspaceSlug };
+        return { ...currentState, tabs, activeTabId };
       },
     },
   ),
 );
-
-// ---------------------------------------------------------------------------
-// Persisted shapes (for migration)
-// ---------------------------------------------------------------------------
-
-interface V1Tab {
-  id: string;
-  path: string;
-  title: string;
-  icon: string;
-}
-
-interface V1Persisted {
-  tabs: V1Tab[];
-  activeTabId: string;
-}
-
-interface V2PersistedTab {
-  id: string;
-  path: string;
-  title: string;
-  icon: string;
-}
-
-interface V2PersistedGroup {
-  tabs: V2PersistedTab[];
-  activeTabId: string;
-}
-
-interface V2Persisted {
-  activeWorkspaceSlug: string | null;
-  byWorkspace: Record<string, V2PersistedGroup>;
-}
-
-export function migrateV1ToV2(v1: Partial<V1Persisted>): V2Persisted {
-  const byWorkspace: Record<string, V2PersistedGroup> = {};
-  const oldTabs = v1.tabs ?? [];
-  for (const tab of oldTabs) {
-    const slug = extractWorkspaceSlug(tab.path);
-    if (!slug) continue; // drop root / global-path tabs
-    if (!byWorkspace[slug]) byWorkspace[slug] = { tabs: [], activeTabId: "" };
-    byWorkspace[slug].tabs.push({
-      id: tab.id,
-      path: tab.path,
-      title: tab.title,
-      icon: tab.icon,
-    });
-  }
-
-  // Each group needs a valid activeTabId. Prefer the one from v1 if it
-  // landed in this group; otherwise fall back to the first tab.
-  for (const slug of Object.keys(byWorkspace)) {
-    const group = byWorkspace[slug];
-    const hasOldActive = group.tabs.some((t) => t.id === v1.activeTabId);
-    group.activeTabId = hasOldActive
-      ? (v1.activeTabId as string)
-      : group.tabs[0].id;
-  }
-
-  // Active workspace: whichever group inherited the v1 activeTab, falling
-  // back to the first group we created (arbitrary but deterministic given
-  // Object.keys iteration order on string keys).
-  let activeWorkspaceSlug: string | null = null;
-  for (const slug of Object.keys(byWorkspace)) {
-    if (byWorkspace[slug].activeTabId === v1.activeTabId) {
-      activeWorkspaceSlug = slug;
-      break;
-    }
-  }
-  if (!activeWorkspaceSlug) {
-    activeWorkspaceSlug = Object.keys(byWorkspace)[0] ?? null;
-  }
-
-  return { activeWorkspaceSlug, byWorkspace };
-}
-
-// ---------------------------------------------------------------------------
-// Selectors (convenience hooks)
-// ---------------------------------------------------------------------------
-
-/**
- * Pure non-hook helper — useful from event handlers / effects that already
- * need `.getState()`. For React subscriptions prefer the stable selectors
- * below.
- */
-export function getActiveTab(s: TabStore): Tab | null {
-  if (!s.activeWorkspaceSlug) return null;
-  const group = s.byWorkspace[s.activeWorkspaceSlug];
-  if (!group) return null;
-  return group.tabs.find((t) => t.id === group.activeTabId) ?? null;
-}
-
-/**
- * The active workspace's tab group, or null when no workspace is active.
- *
- * Zustand compares selector returns with `Object.is`. Because `updateTab`
- * /  `updateTabHistory` replace the group object on every router tick
- * (immutable update), this selector returns a new reference on every
- * router event — that's fine for TabBar which needs to observe tab-list
- * changes, but don't use this selector from components that only care
- * about one primitive (use `useActiveTabHistory` / `useActiveTabRouter`
- * instead).
- */
-export function useActiveGroup(): WorkspaceTabGroup | null {
-  return useTabStore((s) =>
-    s.activeWorkspaceSlug ? (s.byWorkspace[s.activeWorkspaceSlug] ?? null) : null,
-  );
-}
-
-/**
- * Active tab id + active workspace slug as a compact pair. Both primitives
- * are stable across unrelated store updates — e.g. an inactive tab's
- * router tick doesn't churn these, so consumers don't re-render.
- *
- * Useful anywhere you'd previously have reached for `useActiveTab()` and
- * only needed the identity (for memoization, effect deps, ipc).
- */
-export function useActiveTabIdentity(): { slug: string | null; tabId: string | null } {
-  const slug = useTabStore((s) => s.activeWorkspaceSlug);
-  const tabId = useTabStore((s) =>
-    s.activeWorkspaceSlug
-      ? (s.byWorkspace[s.activeWorkspaceSlug]?.activeTabId ?? null)
-      : null,
-  );
-  return { slug, tabId };
-}
-
-/**
- * Active tab's router — a stable reference across tab updates, because
- * routers are created once per tab and never replaced by `updateTab`.
- * Subscribers only re-render when the active tab *changes*, not on
- * router events within the current tab.
- */
-export function useActiveTabRouter(): DataRouter | null {
-  return useTabStore((s) => getActiveTab(s)?.router ?? null);
-}
-
-/**
- * History tracking for the active tab as primitives. Subscribers re-render
- * only when the numeric index / length change (i.e. on actual navigations),
- * not on unrelated store updates.
- */
-export function useActiveTabHistory(): {
-  historyIndex: number;
-  historyLength: number;
-} {
-  const historyIndex = useTabStore((s) => getActiveTab(s)?.historyIndex ?? 0);
-  const historyLength = useTabStore((s) => getActiveTab(s)?.historyLength ?? 1);
-  return { historyIndex, historyLength };
-}

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

@@ -1,29 +0,0 @@
-import { create } from "zustand";
-
-/**
- * Window-level transition overlay: pre-workspace flows that are NOT pages
- * inside a tab. Triggered by navigation-adapter interception, zero-workspace
- * auto-redirect, or deep link; rendered above the tab system as a full-window
- * takeover.
- *
- * These flows used to be routes (`/workspaces/new`, `/invite/:id`) but on
- * desktop the URL is invisible to users — routes are an implementation detail
- * of the tab system. Representing transitions as routes meant tabs tried to
- * persist them, TabBar rendered on top, and invite deep-linking had no clean
- * dispatch target. Modeling them as application state removes all three.
- */
-export type WindowOverlay =
-  | { type: "new-workspace" }
-  | { type: "invite"; invitationId: string };
-
-interface WindowOverlayStore {
-  overlay: WindowOverlay | null;
-  open: (overlay: WindowOverlay) => void;
-  close: () => void;
-}
-
-export const useWindowOverlayStore = create<WindowOverlayStore>((set) => ({
-  overlay: null,
-  open: (overlay) => set({ overlay }),
-  close: () => set({ overlay: null }),
-}));

apps/docs/app/(home)/layout.tsx

@@ -0,0 +1,7 @@
+import type { ReactNode } from "react";
+import { HomeLayout } from "fumadocs-ui/layouts/home";
+import { baseOptions } from "@/app/layout.config";
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return <HomeLayout {...baseOptions}>{children}</HomeLayout>;
+}

apps/docs/app/(home)/page.tsx

@@ -0,0 +1,29 @@
+import Link from "next/link";
+
+export default function HomePage() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-6 text-center px-4">
+      <h1 className="text-4xl font-bold tracking-tight sm:text-5xl">
+        Multica Documentation
+      </h1>
+      <p className="max-w-2xl text-lg text-fd-muted-foreground">
+        The open-source managed agents platform. Turn coding agents into real
+        teammates — assign tasks, track progress, compound skills.
+      </p>
+      <div className="flex gap-4">
+        <Link
+          href="/docs"
+          className="inline-flex items-center rounded-md bg-fd-primary px-6 py-3 text-sm font-medium text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
+        >
+          Get Started
+        </Link>
+        <Link
+          href="https://github.com/multica-ai/multica"
+          className="inline-flex items-center rounded-md border border-fd-border px-6 py-3 text-sm font-medium transition-colors hover:bg-fd-accent"
+        >
+          GitHub
+        </Link>
+      </div>
+    </main>
+  );
+}

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

@@ -10,7 +10,7 @@ import defaultMdxComponents from "fumadocs-ui/mdx";
 import type { Metadata } from "next";
 
 export default async function Page(props: {
-  params: Promise<{ slug: string[] }>;
+  params: Promise<{ slug?: string[] }>;
 }) {
   const params = await props.params;
   const page = source.getPage(params.slug);
@@ -29,12 +29,12 @@ export default async function Page(props: {
   );
 }
 
-export function generateStaticParams() {
-  return source.generateParams().filter((p) => p.slug.length > 0);
+export async function generateStaticParams() {
+  return source.generateParams();
 }
 
 export async function generateMetadata(props: {
-  params: Promise<{ slug: string[] }>;
+  params: Promise<{ slug?: string[] }>;
 }): Promise<Metadata> {
   const params = await props.params;
   const page = source.getPage(params.slug);

apps/docs/app/docs/layout.tsx

@@ -0,0 +1,12 @@
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import type { ReactNode } from "react";
+import { baseOptions } from "@/app/layout.config";
+import { source } from "@/lib/source";
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout tree={source.pageTree} {...baseOptions}>
+      {children}
+    </DocsLayout>
+  );
+}

apps/docs/app/layout.config.tsx

@@ -1,4 +1,5 @@
 import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
+import { BookOpen, Terminal, Rocket, Code } from "lucide-react";
 
 export const baseOptions: BaseLayoutProps = {
   nav: {
@@ -7,6 +8,11 @@ export const baseOptions: BaseLayoutProps = {
     ),
   },
   links: [
+    {
+      text: "Documentation",
+      url: "/docs",
+      active: "nested-url",
+    },
     {
       text: "GitHub",
       url: "https://github.com/multica-ai/multica",

apps/docs/app/layout.tsx

@@ -1,10 +1,7 @@
 import "./global.css";
 import { RootProvider } from "fumadocs-ui/provider";
-import { DocsLayout } from "fumadocs-ui/layouts/docs";
 import type { ReactNode } from "react";
 import type { Metadata } from "next";
-import { baseOptions } from "@/app/layout.config";
-import { source } from "@/lib/source";
 
 export const metadata: Metadata = {
   title: {
@@ -19,11 +16,7 @@ export default function Layout({ children }: { children: ReactNode }) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body>
-        <RootProvider>
-          <DocsLayout tree={source.pageTree} {...baseOptions}>
-            {children}
-          </DocsLayout>
-        </RootProvider>
+        <RootProvider>{children}</RootProvider>
       </body>
     </html>
   );

apps/docs/app/not-found.tsx

@@ -1,18 +0,0 @@
-import Link from "next/link";
-
-export default function NotFound() {
-  return (
-    <main className="flex flex-1 flex-col items-center justify-center gap-4 px-4 py-24 text-center">
-      <h1 className="text-3xl font-semibold">Page not found</h1>
-      <p className="text-fd-muted-foreground">
-        The page you are looking for doesn&apos;t exist.
-      </p>
-      <Link
-        href="/"
-        className="inline-flex items-center rounded-md bg-fd-primary px-4 py-2 text-sm font-medium text-fd-primary-foreground transition-colors hover:bg-fd-primary/90"
-      >
-        Back to docs
-      </Link>
-    </main>
-  );
-}

apps/docs/app/page.tsx

@@ -1,37 +0,0 @@
-import { source } from "@/lib/source";
-import {
-  DocsPage,
-  DocsBody,
-  DocsDescription,
-  DocsTitle,
-} from "fumadocs-ui/page";
-import { notFound } from "next/navigation";
-import defaultMdxComponents from "fumadocs-ui/mdx";
-import type { Metadata } from "next";
-
-export default function Page() {
-  const page = source.getPage([]);
-  if (!page) notFound();
-
-  const MDX = page.data.body;
-
-  return (
-    <DocsPage toc={page.data.toc}>
-      <DocsTitle>{page.data.title}</DocsTitle>
-      <DocsDescription>{page.data.description}</DocsDescription>
-      <DocsBody>
-        <MDX components={{ ...defaultMdxComponents }} />
-      </DocsBody>
-    </DocsPage>
-  );
-}
-
-export function generateMetadata(): Metadata {
-  const page = source.getPage([]);
-  if (!page) notFound();
-
-  return {
-    title: page.data.title,
-    description: page.data.description,
-  };
-}

apps/docs/content/docs/cli/installation.mdx

@@ -68,7 +68,7 @@ multica setup
 
 This configures the CLI for Multica Cloud, opens your browser for login, discovers your workspaces, and starts the agent daemon.
 
-For self-hosted servers, use `multica setup self-host` instead. See [Self-Hosting](/getting-started/self-hosting) for details.
+For self-hosted servers, use `multica setup self-host` instead. See [Self-Hosting](/docs/getting-started/self-hosting) for details.
 
 ## Verify
 
@@ -78,7 +78,7 @@ multica daemon status
 
 Confirm:
 1. Status is `running`
-2. At least one agent is listed (e.g. `claude`, `codex`, `gemini`, `opencode`, `openclaw`, `hermes`, or `pi`)
+2. At least one agent is listed (e.g. `claude`, `codex`, `gemini`, `opencode`, `openclaw`, or `hermes`)
 3. At least one workspace is being watched
 
 If the agents list is empty, install at least one supported AI agent CLI:

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

@@ -212,7 +212,7 @@ multica issue list --priority urgent --assignee "Agent Name"
 multica issue list --limit 20 --output json
 ```
 
-Available filters: `--status`, `--priority`, `--assignee`, `--project`, `--limit`.
+Available filters: `--status`, `--priority`, `--assignee`, `--limit`.
 
 ### Get Issue
 
@@ -227,7 +227,7 @@ multica issue get <id> --output json
 multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"
 ```
 
-Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--project`, `--due-date`.
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--due-date`.
 
 ### Update Issue
 
@@ -281,70 +281,6 @@ multica issue run-messages <task-id> --output json
 multica issue run-messages <task-id> --since 42 --output json
 ```
 
-## Projects
-
-Projects group related issues (e.g. a sprint, an epic, a workstream). Every project
-belongs to a workspace and can optionally have a lead (member or agent).
-
-### List Projects
-
-```bash
-multica project list
-multica project list --status in_progress
-multica project list --output json
-```
-
-Available filters: `--status`.
-
-### Get Project
-
-```bash
-multica project get <id>
-multica project get <id> --output json
-```
-
-### Create Project
-
-```bash
-multica project create --title "2026 Week 16 Sprint" --icon "🏃" --lead "Lambda"
-```
-
-Flags: `--title` (required), `--description`, `--status`, `--icon`, `--lead`.
-
-### Update Project
-
-```bash
-multica project update <id> --title "New title" --status in_progress
-multica project update <id> --lead "Lambda"
-```
-
-Flags: `--title`, `--description`, `--status`, `--icon`, `--lead`.
-
-### Change Status
-
-```bash
-multica project status <id> in_progress
-```
-
-Valid statuses: `planned`, `in_progress`, `paused`, `completed`, `cancelled`.
-
-### Delete Project
-
-```bash
-multica project delete <id>
-```
-
-### Associating Issues with Projects
-
-Use the `--project` flag on `issue create` / `issue update` to attach an issue to a
-project, or on `issue list` to filter issues by project:
-
-```bash
-multica issue create --title "Login bug" --project <project-id>
-multica issue update <issue-id> --project <project-id>
-multica issue list --project <project-id>
-```
-
 ## Configuration
 
 ### View Config

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

@@ -45,7 +45,7 @@ Then configure, authenticate, and start the daemon:
 multica setup
 ```
 
-The daemon auto-detects available agent CLIs (`claude`, `codex`, `gemini`, `openclaw`, `opencode`, `hermes`, `pi`) on your PATH. When an agent is assigned a task, the daemon creates an isolated environment, runs the agent, and reports results back.
+The daemon auto-detects available agent CLIs (`claude`, `codex`, `gemini`, `openclaw`, `opencode`, `hermes`) on your PATH. When an agent is assigned a task, the daemon creates an isolated environment, runs the agent, and reports results back.
 
 ## 3. Verify your runtime
 

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

@@ -31,7 +31,7 @@ curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/ins
 multica setup self-host
 ```
 
-This clones the repo, starts all services, installs the CLI, and configures it for localhost. Then open http://localhost:3000 and pick a login method: configure `RESEND_API_KEY` in `.env` for email-based codes (recommended), or set `APP_ENV=development` in `.env` to enable the dev master code **`888888`**. See [Step 2 — Log In](#step-2--log-in) for details.
+This clones the repo, starts all services, installs the CLI, and configures it for localhost. Then open http://localhost:3000 — log in with any email + code **`888888`**.
 
 <Callout>
 If the self-host server is already running and you only need the CLI on a macOS/Linux machine, install it with Homebrew: `brew install multica-ai/tap/multica`.
@@ -64,14 +64,10 @@ If you prefer running the Docker Compose steps manually: `cp .env.example .env`,
 
 ### Step 2 — Log In
 
-Open http://localhost:3000. The Docker self-host stack defaults to `APP_ENV=production` (set in `docker-compose.selfhost.yml`), so the dev master code is **disabled by default** for safety on public deployments. Pick one of the following to log in:
-
-- **Recommended (production):** configure `RESEND_API_KEY` in `.env`, then restart the backend. Real verification codes will be sent to the email address you enter. See [Configuration](#configuration) below.
-- **Evaluation / private network:** set `APP_ENV=development` in `.env` and restart the backend. Verification code **`888888`** will then work for any email address.
-- **Without configuring either:** the verification code is generated server-side and printed to the backend container logs (look for `[DEV] Verification code for ...:`). Useful for one-off testing on a single machine.
+Open http://localhost:3000. Enter any email address and use verification code **`888888`** to log in.
 
 <Callout>
-**Warning:** do **not** set `APP_ENV=development` on a publicly reachable instance — anyone who knows an email address can then log in with `888888`.
+This master code works in all non-production environments (when `APP_ENV` is not set to `production`). For production, configure an email provider — see [Configuration](#configuration) below.
 </Callout>
 
 ### Step 3 — Install CLI & Start Daemon
@@ -202,14 +198,7 @@ For file uploads and attachments, configure S3 and CloudFront:
 | `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
 | `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
 | `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
-
-### Cookies
-
-| Variable | Description |
-|----------|-------------|
-| `COOKIE_DOMAIN` | Optional `Domain` attribute for session + CloudFront cookies. **Leave empty** for single-host deployments (localhost, LAN IP, or a single hostname). Only set it when the frontend and backend sit on different subdomains of one registered domain (e.g. `.example.com`). **Do not use an IP literal** — RFC 6265 forbids IP addresses in the cookie `Domain` attribute and browsers will drop such `Set-Cookie` headers. |
-
-The `Secure` flag on session cookies is derived automatically from the scheme of `FRONTEND_ORIGIN`: HTTPS origins get `Secure` cookies; plain-HTTP origins (LAN / private-network self-host) get non-secure cookies so the browser can actually store them.
+| `COOKIE_DOMAIN` | Domain for CloudFront auth cookies |
 
 ### Server
 

apps/docs/content/docs/guides/quickstart.mdx

@@ -11,7 +11,7 @@ Once you have the CLI installed (or signed up for [Multica Cloud](https://multic
 multica setup           # Configure, authenticate, and start the daemon
 ```
 
-This configures the CLI, opens your browser for login, discovers your workspaces, and starts the agent daemon in the background. It auto-detects agent CLIs (`claude`, `codex`, `gemini`, `openclaw`, `opencode`, `hermes`, `pi`) available on your PATH.
+This configures the CLI, opens your browser for login, discovers your workspaces, and starts the agent daemon in the background. It auto-detects agent CLIs (`claude`, `codex`, `gemini`, `openclaw`, `opencode`, `hermes`) available on your PATH.
 
 ## 2. Verify your runtime
 

apps/docs/content/docs/index.mdx

@@ -41,7 +41,7 @@ No more copy-pasting prompts. No more babysitting runs. Your agents show up on t
 
 ## Next Steps
 
-- [Cloud Quickstart](/getting-started/cloud-quickstart)
-- [Self-Hosting](/getting-started/self-hosting)
-- [CLI Installation](/cli/installation)
-- [Contributing](/developers/contributing)
+- [Cloud Quickstart](/docs/getting-started/cloud-quickstart)
+- [Self-Hosting](/docs/getting-started/self-hosting)
+- [CLI Installation](/docs/cli/installation)
+- [Contributing](/docs/developers/contributing)

apps/docs/lib/source.ts

@@ -2,6 +2,6 @@ import { docs } from "@/.source";
 import { loader } from "fumadocs-core/source";
 
 export const source = loader({
-  baseUrl: "/",
+  baseUrl: "/docs",
   source: docs.toFumadocsSource(),
 });

apps/docs/next.config.mjs

@@ -5,7 +5,6 @@ const withMDX = createMDX();
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: true,
-  basePath: "/docs",
 };
 
 export default withMDX(config);

apps/web/app/(auth)/invite/[id]/page.tsx

@@ -2,10 +2,8 @@
 
 import { useEffect } from "react";
 import { useRouter, useParams } from "next/navigation";
-import { useQuery } from "@tanstack/react-query";
 import { useAuthStore } from "@multica/core/auth";
 import { paths } from "@multica/core/paths";
-import { workspaceListOptions } from "@multica/core/workspace/queries";
 import { InvitePage } from "@multica/views/invite";
 
 export default function InviteAcceptPage() {
@@ -13,10 +11,6 @@ export default function InviteAcceptPage() {
   const params = useParams<{ id: string }>();
   const user = useAuthStore((s) => s.user);
   const isLoading = useAuthStore((s) => s.isLoading);
-  const { data: wsList = [] } = useQuery({
-    ...workspaceListOptions(),
-    enabled: !!user,
-  });
 
   // Redirect to login if not authenticated, with a redirect back to this page.
   useEffect(() => {
@@ -29,8 +23,5 @@ export default function InviteAcceptPage() {
 
   if (isLoading || !user) return null;
 
-  const onBack =
-    wsList.length > 0 ? () => router.push(paths.root()) : undefined;
-
-  return <InvitePage invitationId={params.id} onBack={onBack} />;
+  return <InvitePage invitationId={params.id} />;
 }

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

@@ -11,51 +11,32 @@ function createWrapper() {
   );
 }
 
-const {
-  mockSendCode,
-  mockVerifyCode,
-  mockIssueCliToken,
-  searchParamsState,
-  authStateRef,
-} = vi.hoisted(() => ({
+const { mockSendCode, mockVerifyCode } = vi.hoisted(() => ({
   mockSendCode: vi.fn(),
   mockVerifyCode: vi.fn(),
-  mockIssueCliToken: vi.fn(),
-  searchParamsState: { params: new URLSearchParams() },
-  authStateRef: {
-    state: {
-      sendCode: vi.fn(),
-      verifyCode: vi.fn(),
-      user: null as null | { id: string; email: string },
-      isLoading: false,
-    },
-  },
 }));
 
 // Mock next/navigation
 vi.mock("next/navigation", () => ({
   useRouter: () => ({ push: vi.fn(), replace: vi.fn() }),
   usePathname: () => "/login",
-  useSearchParams: () => searchParamsState.params,
+  useSearchParams: () => new URLSearchParams(),
 }));
 
 // Mock auth store — shared LoginPage uses getState().sendCode/verifyCode,
-// web wrapper uses useAuthStore((s) => s.user/isLoading). Keep the real
-// sanitizeNextUrl so the redirect-sanitization rules are exercised rather
-// than silently drifting behind a mock reimplementation.
-vi.mock("@multica/core/auth", async () => {
-  const actual =
-    await vi.importActual<typeof import("@multica/core/auth")>(
-      "@multica/core/auth",
-    );
-  authStateRef.state.sendCode = mockSendCode;
-  authStateRef.state.verifyCode = mockVerifyCode;
+// web wrapper uses useAuthStore((s) => s.user/isLoading)
+vi.mock("@multica/core/auth", () => {
+  const authState = {
+    sendCode: mockSendCode,
+    verifyCode: mockVerifyCode,
+    user: null,
+    isLoading: false,
+  };
   const useAuthStore = Object.assign(
-    (selector: (s: typeof authStateRef.state) => unknown) =>
-      selector(authStateRef.state),
-    { getState: () => authStateRef.state },
+    (selector: (s: typeof authState) => unknown) => selector(authState),
+    { getState: () => authState },
   );
-  return { ...actual, useAuthStore };
+  return { useAuthStore };
 });
 
 // Mock auth-cookie
@@ -70,7 +51,6 @@ vi.mock("@multica/core/api", () => ({
     verifyCode: vi.fn(),
     setToken: vi.fn(),
     getMe: vi.fn(),
-    issueCliToken: mockIssueCliToken,
   },
 }));
 
@@ -79,9 +59,6 @@ import LoginPage from "./page";
 describe("LoginPage", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    searchParamsState.params = new URLSearchParams();
-    authStateRef.state.user = null;
-    authStateRef.state.isLoading = false;
   });
 
   it("renders login form with email input and continue button", () => {
@@ -154,44 +131,4 @@ describe("LoginPage", () => {
       expect(screen.getByText("Network error")).toBeInTheDocument();
     });
   });
-
-  // Regression: MUL-1080 — if the user is already authenticated on the web
-  // and the Desktop app redirects them to /login?platform=desktop, the web
-  // must exchange the cookie session for a bearer token and hand it off via
-  // the multica:// deep link, not silently redirect to the workspace page.
-  it("mints a token and deep-links to Desktop when already logged in with platform=desktop", async () => {
-    searchParamsState.params = new URLSearchParams({ platform: "desktop" });
-    authStateRef.state.user = { id: "u1", email: "test@multica.ai" };
-    mockIssueCliToken.mockImplementation(() =>
-      Promise.resolve({ token: "handoff-jwt" }),
-    );
-
-    const hrefSetter = vi.fn();
-    const originalLocation = window.location;
-    Object.defineProperty(window, "location", {
-      configurable: true,
-      value: { ...originalLocation, set href(value: string) { hrefSetter(value); } },
-    });
-
-    try {
-      render(<LoginPage />, { wrapper: createWrapper() });
-
-      await waitFor(() => {
-        expect(mockIssueCliToken).toHaveBeenCalledTimes(1);
-      });
-      await waitFor(() => {
-        expect(hrefSetter).toHaveBeenCalledWith(
-          "multica://auth/callback?token=handoff-jwt",
-        );
-      });
-      expect(
-        await screen.findByRole("button", { name: "Open Multica Desktop" }),
-      ).toBeInTheDocument();
-    } finally {
-      Object.defineProperty(window, "location", {
-        configurable: true,
-        value: originalLocation,
-      });
-    }
-  });
 });

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

@@ -1,22 +1,12 @@
 "use client";
 
-import { Suspense, useEffect, useState } from "react";
+import { Suspense, useEffect } from "react";
 import { useSearchParams, useRouter } from "next/navigation";
 import { useQueryClient } from "@tanstack/react-query";
-import { sanitizeNextUrl, useAuthStore } from "@multica/core/auth";
+import { useAuthStore } from "@multica/core/auth";
 import { workspaceKeys } from "@multica/core/workspace/queries";
 import { paths } from "@multica/core/paths";
-import { api } from "@multica/core/api";
 import type { Workspace } from "@multica/core/types";
-import {
-  Card,
-  CardHeader,
-  CardTitle,
-  CardDescription,
-  CardContent,
-} from "@multica/ui/components/ui/card";
-import { Button } from "@multica/ui/components/ui/button";
-import { Loader2 } from "lucide-react";
 import { setLoggedInCookie } from "@/features/auth/auth-cookie";
 import { LoginPage, validateCliCallback } from "@multica/views/auth";
 
@@ -32,39 +22,16 @@ function LoginPageContent() {
   const cliCallbackRaw = searchParams.get("cli_callback");
   const cliState = searchParams.get("cli_state") || "";
   const platform = searchParams.get("platform");
-  const isDesktopHandoff = platform === "desktop" && !cliCallbackRaw;
   // `next` carries a protected URL the user was originally headed to
   // (e.g. /invite/{id}). With URL-driven workspaces there is no legacy
   // "/issues" default — if `next` is absent we decide after login based on
-  // the user's workspace list. Sanitize first so a crafted `?next=https://evil`
-  // cannot bounce the user off-origin after a successful login.
-  const nextUrl = sanitizeNextUrl(searchParams.get("next"));
+  // the user's workspace list.
+  const nextUrl = searchParams.get("next");
 
-  const [desktopToken, setDesktopToken] = useState<string | null>(null);
-  const [desktopError, setDesktopError] = useState("");
-
-  // Already authenticated — honor ?next= or fall back to first workspace
-  // (or /workspaces/new if the user has none). Skip this entire path when
-  // the user arrived to authorize the CLI.
+  // Already authenticated — honor ?next= or fall back to first workspace /
+  // onboarding. Skip this entire path when the user arrived to authorize the CLI.
   useEffect(() => {
     if (isLoading || !user || cliCallbackRaw) return;
-    if (isDesktopHandoff) {
-      // Desktop opened the browser for login but the web session is already
-      // authenticated — mint a bearer token from the cookie session and hand
-      // it off via deep link instead of silently redirecting to the workspace.
-      api
-        .issueCliToken()
-        .then(({ token }) => {
-          setDesktopToken(token);
-          window.location.href = `multica://auth/callback?token=${encodeURIComponent(token)}`;
-        })
-        .catch((err) => {
-          setDesktopError(
-            err instanceof Error ? err.message : "Failed to prepare Desktop sign-in",
-          );
-        });
-      return;
-    }
     if (nextUrl) {
       router.replace(nextUrl);
       return;
@@ -72,9 +39,9 @@ function LoginPageContent() {
     const list = qc.getQueryData<Workspace[]>(workspaceKeys.list()) ?? [];
     const [first] = list;
     router.replace(
-      first ? paths.workspace(first.slug).issues() : paths.newWorkspace(),
+      first ? paths.workspace(first.slug).issues() : paths.onboarding(),
     );
-  }, [isLoading, user, router, nextUrl, cliCallbackRaw, isDesktopHandoff, qc]);
+  }, [isLoading, user, router, nextUrl, cliCallbackRaw, qc]);
 
   const handleSuccess = () => {
     if (nextUrl) {
@@ -86,7 +53,7 @@ function LoginPageContent() {
     const list = qc.getQueryData<Workspace[]>(workspaceKeys.list()) ?? [];
     const [first] = list;
     router.push(
-      first ? paths.workspace(first.slug).issues() : paths.newWorkspace(),
+      first ? paths.workspace(first.slug).issues() : paths.onboarding(),
     );
   };
 
@@ -99,52 +66,6 @@ function LoginPageContent() {
     .filter(Boolean)
     .join(",") || undefined;
 
-  // While the desktop handoff is in progress (or has produced a token/error),
-  // render a dedicated screen instead of flashing the login form or redirecting
-  // away to a workspace page.
-  if (isDesktopHandoff && user) {
-    if (desktopError) {
-      return (
-        <div className="flex min-h-screen items-center justify-center">
-          <Card className="w-full max-w-sm">
-            <CardHeader className="text-center">
-              <CardTitle className="text-2xl">Sign-in Failed</CardTitle>
-              <CardDescription>{desktopError}</CardDescription>
-            </CardHeader>
-          </Card>
-        </div>
-      );
-    }
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <Card className="w-full max-w-sm">
-          <CardHeader className="text-center">
-            <CardTitle className="text-2xl">Opening Multica</CardTitle>
-            <CardDescription>
-              {desktopToken
-                ? "You should see a prompt to open the Multica desktop app. If nothing happens, click the button below."
-                : "Preparing Desktop sign-in..."}
-            </CardDescription>
-          </CardHeader>
-          <CardContent className="flex justify-center">
-            {desktopToken ? (
-              <Button
-                variant="outline"
-                onClick={() => {
-                  window.location.href = `multica://auth/callback?token=${encodeURIComponent(desktopToken)}`;
-                }}
-              >
-                Open Multica Desktop
-              </Button>
-            ) : (
-              <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
-            )}
-          </CardContent>
-        </Card>
-      </div>
-    );
-  }
-
   return (
     <LoginPage
       onSuccess={handleSuccess}

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

@@ -0,0 +1,26 @@
+"use client";
+
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useAuthStore } from "@multica/core/auth";
+import { paths } from "@multica/core/paths";
+import { OnboardingWizard } from "@multica/views/onboarding";
+
+export default function OnboardingPage() {
+  const router = useRouter();
+  const user = useAuthStore((s) => s.user);
+  const isLoading = useAuthStore((s) => s.isLoading);
+
+  // Redirect to login if not authenticated
+  useEffect(() => {
+    if (!isLoading && !user) router.replace(paths.login());
+  }, [isLoading, user, router]);
+
+  if (isLoading || !user) return null;
+
+  return (
+    <OnboardingWizard
+      onComplete={(ws) => router.push(paths.workspace(ws.slug).issues())}
+    />
+  );
+}

apps/web/app/(auth)/workspaces/new/page.tsx

@@ -1,38 +0,0 @@
-"use client";
-
-import { useRouter } from "next/navigation";
-import { useEffect } from "react";
-import { useQuery } from "@tanstack/react-query";
-import { useAuthStore } from "@multica/core/auth";
-import { paths } from "@multica/core/paths";
-import { workspaceListOptions } from "@multica/core/workspace/queries";
-import { NewWorkspacePage } from "@multica/views/workspace/new-workspace-page";
-
-export default function Page() {
-  const router = useRouter();
-  const user = useAuthStore((s) => s.user);
-  const isLoading = useAuthStore((s) => s.isLoading);
-  const { data: wsList = [] } = useQuery({
-    ...workspaceListOptions(),
-    enabled: !!user,
-  });
-
-  useEffect(() => {
-    if (!isLoading && !user) router.replace(paths.login());
-  }, [isLoading, user, router]);
-
-  if (isLoading || !user) return null;
-
-  // Back goes to the root path — the workspace layout redirects from
-  // there to the user's default workspace. Only show Back when there's
-  // somewhere to go back to (user already has at least one workspace).
-  const onBack =
-    wsList.length > 0 ? () => router.push(paths.root()) : undefined;
-
-  return (
-    <NewWorkspacePage
-      onSuccess={(ws) => router.push(paths.workspace(ws.slug).issues())}
-      onBack={onBack}
-    />
-  );
-}

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

@@ -0,0 +1,28 @@
+import { Skeleton } from "@multica/ui/components/ui/skeleton";
+
+export default function DashboardLoading() {
+  return (
+    <div className="flex flex-1 min-h-0 flex-col">
+      {/* Header skeleton */}
+      <div className="flex h-12 shrink-0 items-center gap-2 border-b px-4">
+        <Skeleton className="h-5 w-5 rounded" />
+        <Skeleton className="h-4 w-32" />
+      </div>
+      {/* Toolbar skeleton */}
+      <div className="flex h-12 shrink-0 items-center justify-between border-b px-4">
+        <Skeleton className="h-5 w-24" />
+        <Skeleton className="h-8 w-24" />
+      </div>
+      {/* Content skeleton */}
+      <div className="flex-1 p-4 space-y-3">
+        {Array.from({ length: 6 }).map((_, i) => (
+          <div key={i} className="flex items-center gap-3">
+            <Skeleton className="h-4 w-4 rounded" />
+            <Skeleton className="h-4 flex-1 max-w-md" />
+            <Skeleton className="h-4 w-16" />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

apps/web/app/[workspaceSlug]/layout.tsx

@@ -1,15 +1,15 @@
 "use client";
 
-import { use, useEffect } from "react";
+import { use, useEffect, useRef } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { useRouter } from "next/navigation";
 import { WorkspaceSlugProvider, paths } from "@multica/core/paths";
 import { workspaceBySlugOptions } from "@multica/core/workspace";
-import { setCurrentWorkspace } from "@multica/core/platform";
+import {
+  setCurrentWorkspace,
+  rehydrateAllWorkspaceStores,
+} from "@multica/core/platform";
 import { useAuthStore } from "@multica/core/auth";
-import { NoAccessPage } from "@multica/views/workspace/no-access-page";
-import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
-import { useWorkspaceSeen } from "@multica/views/workspace/use-workspace-seen";
 
 export default function WorkspaceLayout({
   children,
@@ -23,14 +23,6 @@ export default function WorkspaceLayout({
   const isAuthLoading = useAuthStore((s) => s.isLoading);
   const router = useRouter();
 
-  // Workspace routes require auth. If user is unauthenticated (initial visit
-  // without a session, token expired, another tab logged out, etc.), bounce
-  // to /login. Without this, the layout renders null and the user sees a
-  // blank page stuck on /{slug}/...
-  useEffect(() => {
-    if (!isAuthLoading && !user) router.replace(paths.login());
-  }, [isAuthLoading, user, router]);
-
   // Resolve workspace by slug from the React Query list cache.
   // Enabled only when user is authenticated — otherwise the list query isn't seeded.
   const { data: workspace, isFetched: listFetched } = useQuery({
@@ -38,50 +30,46 @@ export default function WorkspaceLayout({
     enabled: !!user,
   });
 
-  // Render-phase sync: feed the URL slug into the platform singleton so
-  // the first child query's X-Workspace-Slug header is already correct.
-  // setCurrentWorkspace self-dedupes + runs rehydrate as a side effect;
-  // safe to call on every render.
-  if (workspace) {
+  // Render-phase sync: set the current workspace slug + UUID into the
+  // platform singleton BEFORE children render. This ensures the first
+  // child query's X-Workspace-Slug header is already correct.
+  // The ref guard prevents re-running on every render.
+  const syncedSlugRef = useRef<string | null>(null);
+  if (workspace && syncedSlugRef.current !== workspaceSlug) {
     setCurrentWorkspace(workspaceSlug, workspace.id);
+    rehydrateAllWorkspaceStores();
+    syncedSlugRef.current = workspaceSlug;
   }
 
-  // Cookie write (last_workspace_slug) — proxy reads it on next page load
-  // to redirect unauthenticated-URL hits to the user's last workspace.
+  // Cookie write (last_workspace_slug) — proxy reads it on next page load.
+  // ALSO write legacy localStorage["multica_workspace_id"] for forward/back
+  // compatibility: if this version ever gets reverted to the pre-refactor
+  // build, the legacy code reads that localStorage key to know which
+  // workspace to attach to API requests. Without double-writing, a rollback
+  // would leave returning users with empty data (API calls would have no
+  // X-Workspace-ID header). Forward compatible — new code ignores this key.
   useEffect(() => {
     if (!workspace || typeof document === "undefined") return;
     const oneYear = 60 * 60 * 24 * 365;
     const secure = location.protocol === "https:" ? "; Secure" : "";
     document.cookie = `last_workspace_slug=${encodeURIComponent(workspaceSlug)}; path=/; max-age=${oneYear}; SameSite=Lax${secure}`;
+    try {
+      localStorage.setItem("multica_workspace_id", workspace.id);
+    } catch {
+      // localStorage may be unavailable in restricted contexts; non-critical.
+    }
   }, [workspace, workspaceSlug]);
 
-  // Remember whether this slug has resolved before. Used below to avoid
-  // flashing NoAccessPage during active workspace removal (delete, leave,
-  // or realtime eviction) — in those cases the caller is navigating away
-  // and we just need to hold null briefly.
-  const hasBeenSeen = useWorkspaceSeen(workspaceSlug, !!workspace);
+  // Slug doesn't match any workspace the user has access to → onboarding.
+  // Wait for the list query to settle so we don't bounce on first render.
+  // Skip when user is null — DashboardGuard handles the /login redirect.
+  useEffect(() => {
+    if (!user) return;
+    if (listFetched && !workspace) router.replace(paths.onboarding());
+  }, [user, listFetched, workspace, router]);
 
-  const loadingIndicator = (
-    <div className="flex h-svh items-center justify-center">
-      <MulticaIcon className="size-6 animate-pulse" />
-    </div>
-  );
-
-  if (isAuthLoading) return loadingIndicator;
-  // Don't render children until workspace is resolved. useWorkspaceId()
-  // throws when the list hasn't populated or the slug is unknown — gating
-  // here makes that invariant hold for every descendant.
-  if (!listFetched) return loadingIndicator;
-  if (!workspace) {
-    // If we've resolved this slug before in this session, it was just
-    // removed from our list (deleted/left/evicted). A navigate is almost
-    // certainly in flight — render null to avoid a NoAccessPage flash.
-    if (hasBeenSeen) return null;
-    // Otherwise: the URL points at a workspace the user never had access
-    // to. Show explicit feedback instead of silently redirecting. Doesn't
-    // distinguish 404 vs 403 to avoid letting attackers enumerate slugs.
-    return <NoAccessPage />;
-  }
+  // Auth still loading → render nothing (let DashboardGuard show its loader).
+  if (isAuthLoading) return null;
 
   return (
     <WorkspaceSlugProvider slug={workspaceSlug}>

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

@@ -1,86 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, waitFor } from "@testing-library/react";
-import { paths } from "@multica/core/paths";
-
-const { mockPush, mockSearchParams, mockLoginWithGoogle, mockListWorkspaces } =
-  vi.hoisted(() => ({
-    mockPush: vi.fn(),
-    mockSearchParams: new URLSearchParams(),
-    mockLoginWithGoogle: vi.fn(),
-    mockListWorkspaces: vi.fn(),
-  }));
-
-vi.mock("next/navigation", () => ({
-  useRouter: () => ({ push: mockPush }),
-  useSearchParams: () => mockSearchParams,
-}));
-
-vi.mock("@tanstack/react-query", () => ({
-  useQueryClient: () => ({ setQueryData: vi.fn() }),
-}));
-
-// Preserve the real sanitizeNextUrl so the "drop unsafe ?next=" behavior is
-// exercised rather than silently diverging from the source of truth.
-vi.mock("@multica/core/auth", async () => {
-  const actual =
-    await vi.importActual<typeof import("@multica/core/auth")>(
-      "@multica/core/auth",
-    );
-  return {
-    ...actual,
-    useAuthStore: (selector: (s: unknown) => unknown) =>
-      selector({ loginWithGoogle: mockLoginWithGoogle }),
-  };
-});
-
-vi.mock("@multica/core/workspace/queries", () => ({
-  workspaceKeys: { list: () => ["workspaces"] },
-}));
-
-vi.mock("@multica/core/api", () => ({
-  api: {
-    listWorkspaces: mockListWorkspaces,
-    googleLogin: vi.fn(),
-  },
-}));
-
-import CallbackPage from "./page";
-
-describe("CallbackPage", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockSearchParams.forEach((_v, k) => mockSearchParams.delete(k));
-    mockSearchParams.set("code", "test-code");
-    mockLoginWithGoogle.mockResolvedValue(undefined);
-    mockListWorkspaces.mockResolvedValue([]);
-  });
-
-  it("falls back to paths.newWorkspace() when no next= is present and the user has no workspace", async () => {
-    render(<CallbackPage />);
-
-    await waitFor(() => {
-      expect(mockPush).toHaveBeenCalledWith(paths.newWorkspace());
-    });
-  });
-
-  it("ignores unsafe next= targets from the OAuth state and still lands on the default destination", async () => {
-    mockSearchParams.set("state", "next:https://evil.example");
-
-    render(<CallbackPage />);
-
-    await waitFor(() => {
-      expect(mockPush).toHaveBeenCalledWith(paths.newWorkspace());
-    });
-    expect(mockPush).not.toHaveBeenCalledWith("https://evil.example");
-  });
-
-  it("honors a safe next= target (e.g. /invite/{id})", async () => {
-    mockSearchParams.set("state", "next:/invite/abc123");
-
-    render(<CallbackPage />);
-
-    await waitFor(() => {
-      expect(mockPush).toHaveBeenCalledWith("/invite/abc123");
-    });
-  });
-});

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

@@ -3,7 +3,7 @@
 import { Suspense, useEffect, useState } from "react";
 import { useSearchParams, useRouter } from "next/navigation";
 import { useQueryClient } from "@tanstack/react-query";
-import { sanitizeNextUrl, useAuthStore } from "@multica/core/auth";
+import { useAuthStore } from "@multica/core/auth";
 import { workspaceKeys } from "@multica/core/workspace/queries";
 import { paths } from "@multica/core/paths";
 import { api } from "@multica/core/api";
@@ -42,9 +42,7 @@ function CallbackContent() {
     const stateParts = state.split(",");
     const isDesktop = stateParts.includes("platform:desktop");
     const nextPart = stateParts.find((p) => p.startsWith("next:"));
-    // Strip "next:" prefix, then drop anything that isn't a safe relative path
-    // so an attacker-controlled `state=next:https://evil` cannot redirect here.
-    const nextUrl = sanitizeNextUrl(nextPart ? nextPart.slice(5) : null);
+    const nextUrl = nextPart ? nextPart.slice(5) : null; // strip "next:" prefix
 
     const redirectUri = `${window.location.origin}/auth/callback`;
 
@@ -68,11 +66,11 @@ function CallbackContent() {
           // URL is now the source of truth for the current workspace — the
           // [workspaceSlug]/layout syncs stores + cookie once we navigate.
           // Honor ?next= first (e.g. came from /invite/{id}), otherwise land
-          // in the first workspace's issues, or /workspaces/new for zero-workspace users.
+          // in the first workspace's issues, or /onboarding if the user has none.
           const [first] = wsList;
           const defaultDest = first
             ? paths.workspace(first.slug).issues()
-            : paths.newWorkspace();
+            : paths.onboarding();
           router.push(nextUrl || defaultDest);
         })
         .catch((err) => {

apps/web/components/pageview-tracker.tsx

@@ -1,29 +0,0 @@
-"use client";
-
-import { useEffect } from "react";
-import { usePathname, useSearchParams } from "next/navigation";
-import { capturePageview } from "@multica/core/analytics";
-
-/**
- * Fires a PostHog $pageview whenever the Next.js App Router path or query
- * string changes. Mounted once at the root so every route transition is
- * covered, including transitions into workspace-scoped subtrees.
- *
- * PostHog's own `capture_pageview: true` auto-capture is deliberately
- * disabled in `initAnalytics` so we own the event shape — this component
- * is what actually fires the event. Before this existed the acquisition
- * funnel's `/ → signup` step was empty.
- */
-export function PageviewTracker() {
-  const pathname = usePathname();
-  const searchParams = useSearchParams();
-
-  useEffect(() => {
-    if (!pathname) return;
-    const qs = searchParams?.toString();
-    const url = qs ? `${pathname}?${qs}` : pathname;
-    capturePageview(url);
-  }, [pathname, searchParams]);
-
-  return null;
-}

apps/web/components/web-providers.tsx

@@ -1,13 +1,11 @@
 "use client";
 
-import { Suspense } from "react";
 import { CoreProvider } from "@multica/core/platform";
 import { WebNavigationProvider } from "@/platform/navigation";
 import {
   setLoggedInCookie,
   clearLoggedInCookie,
 } from "@/features/auth/auth-cookie";
-import { PageviewTracker } from "./pageview-tracker";
 
 // Legacy token in localStorage → keep this session in token mode so users who
 // logged in before the cookie-auth migration stay authed. They migrate to
@@ -44,11 +42,6 @@ export function WebProviders({ children }: { children: React.ReactNode }) {
       onLogin={setLoggedInCookie}
       onLogout={clearLoggedInCookie}
     >
-      {/* Suspense boundary is required by Next.js for useSearchParams in
-          a client component mounted this high in the tree. */}
-      <Suspense fallback={null}>
-        <PageviewTracker />
-      </Suspense>
       <WebNavigationProvider>{children}</WebNavigationProvider>
     </CoreProvider>
   );

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

@@ -1,5 +1,6 @@
 "use client";
 
+import { useCallback, useState } from "react";
 import Image from "next/image";
 import Link from "next/link";
 import { useAuthStore } from "@multica/core/auth";
@@ -10,6 +11,8 @@ import {
   GeminiCliLogo,
   OpenClawLogo,
   OpenCodeLogo,
+  GitHubMark,
+  githubUrl,
   heroButtonClassName,
 } from "./shared";
 
@@ -42,35 +45,24 @@ export function LandingHero() {
                 {user ? t.header.dashboard : t.hero.cta}
               </Link>
               <Link
-                href="https://github.com/multica-ai/multica/releases/latest"
+                href={githubUrl}
                 target="_blank"
                 rel="noreferrer"
                 className={heroButtonClassName("ghost")}
               >
-                <svg
-                  viewBox="0 0 24 24"
-                  fill="none"
-                  stroke="currentColor"
-                  strokeWidth="2"
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  className="size-4"
-                  aria-hidden="true"
-                >
-                  <rect x="2" y="3" width="20" height="14" rx="2" ry="2" />
-                  <line x1="8" y1="21" x2="16" y2="21" />
-                  <line x1="12" y1="17" x2="12" y2="21" />
-                </svg>
-                {t.hero.downloadDesktop}
+                <GitHubMark className="size-4" />
+                GitHub
               </Link>
             </div>
+
+            <InstallCommand />
           </div>
 
-          <div className="mt-10 flex flex-wrap items-center justify-center gap-x-6 gap-y-3">
+          <div className="mt-10 flex items-center justify-center gap-8">
             <span className="text-[15px] text-white/50">
               {t.hero.worksWith}
             </span>
-            <div className="flex flex-wrap items-center justify-center gap-x-5 gap-y-3">
+            <div className="flex items-center gap-6">
               <div className="flex items-center gap-2.5 text-white/80">
                 <ClaudeCodeLogo className="size-5" />
                 <span className="text-[15px] font-medium">Claude Code</span>
@@ -103,6 +95,64 @@ export function LandingHero() {
   );
 }
 
+const INSTALL_COMMAND =
+  "curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash";
+
+function InstallCommand() {
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(INSTALL_COMMAND);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // ignore
+    }
+  }, []);
+
+  return (
+    <div className="mx-auto mt-6 max-w-fit">
+      <button
+        type="button"
+        onClick={handleCopy}
+        className="group flex items-center gap-3 rounded-lg border border-white/10 bg-white/5 px-4 py-2.5 font-mono text-[13px] text-white/70 backdrop-blur-sm transition-colors hover:border-white/20 hover:bg-white/8 hover:text-white/90"
+      >
+        <span className="text-white/40">$</span>
+        <span className="select-all">{INSTALL_COMMAND}</span>
+        <span className="ml-1 flex size-5 shrink-0 items-center justify-center text-white/40 transition-colors group-hover:text-white/70">
+          {copied ? (
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              className="size-3.5 text-green-400"
+            >
+              <polyline points="20 6 9 17 4 12" />
+            </svg>
+          ) : (
+            <svg
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              className="size-3.5"
+            >
+              <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+              <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+            </svg>
+          )}
+        </span>
+      </button>
+    </div>
+  );
+}
+
 function LandingBackdrop() {
   return (
     <div className="pointer-events-none absolute inset-0">
@@ -110,6 +160,7 @@ function LandingBackdrop() {
         src="/images/landing-bg.jpg"
         alt=""
         fill
+        priority
         className="object-cover object-center"
       />
     </div>
@@ -125,7 +176,6 @@ function ProductImage({ alt }: { alt: string }) {
           alt={alt}
           width={3532}
           height={2382}
-          priority
           className="block h-auto w-full"
           sizes="(max-width: 1320px) 100vw, 1320px"
           quality={85}

apps/web/features/landing/components/redirect-if-authenticated.tsx

@@ -16,7 +16,7 @@ import { paths } from "@multica/core/paths";
  * login* — before the user has ever visited a workspace — the cookie is
  * absent, so the proxy falls through to the landing page. This component
  * covers that gap: once auth is resolved and the workspace list has loaded,
- * push the user into their workspace (or /workspaces/new if they have none).
+ * push the user into their workspace (or onboarding if they have none).
  *
  * Renders nothing. Uses `router.replace` so the landing page never enters
  * browser history for authenticated users.
@@ -35,7 +35,7 @@ export function RedirectIfAuthenticated() {
     if (isLoading || !user || !list) return;
     const [first] = list;
     if (!first) {
-      router.replace(paths.newWorkspace());
+      router.replace(paths.onboarding());
       return;
     }
     router.replace(paths.workspace(first.slug).issues());

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

@@ -1,8 +1,6 @@
 import { githubUrl } from "../components/shared";
 import type { LandingDict } from "./types";
 
-export const ALLOW_SIGNUP = process.env.NEXT_PUBLIC_ALLOW_SIGNUP !== "false";
-
 export const en: LandingDict = {
   header: {
     github: "GitHub",
@@ -16,7 +14,6 @@ export const en: LandingDict = {
     subheading:
       "Multica is an open-source platform that turns coding agents into real teammates. Assign tasks, track progress, compound skills \u2014 manage your human + agent workforce in one place.",
     cta: "Start free trial",
-    downloadDesktop: "Download Desktop",
     worksWith: "Works with",
     imageAlt: "Multica board view \u2014 issues managed by humans and agents",
   },
@@ -122,10 +119,9 @@ export const en: LandingDict = {
     headlineFaded: "in the next hour.",
     steps: [
       {
-        title: ALLOW_SIGNUP ? "Sign up & create your workspace" : "Login to your workspace",
-        description: ALLOW_SIGNUP
-          ? "Enter your email, verify with a code, and you\u2019re in. Your workspace is created automatically \u2014 no setup wizard, no configuration forms."
-          : "Enter your email, verify with a code, and you\u2019re logged into your workspace \u2014 no setup wizard, no configuration forms.",
+        title: "Sign up & create your workspace",
+        description:
+          "Enter your email, verify with a code, and you\u2019re in. Your workspace is created automatically \u2014 no setup wizard, no configuration forms.",
       },
       {
         title: "Install the CLI & connect your machine",
@@ -227,7 +223,6 @@ export const en: LandingDict = {
           { label: "Features", href: "#features" },
           { label: "How it Works", href: "#how-it-works" },
           { label: "Changelog", href: "/changelog" },
-          { label: "Desktop", href: "https://github.com/multica-ai/multica/releases/latest" },
         ],
       },
       resources: {
@@ -282,85 +277,6 @@ export const en: LandingDict = {
       fixes: "Bug Fixes",
     },
     entries: [
-      {
-        version: "0.2.8",
-        date: "2026-04-20",
-        title: "Per-Agent Models, Kimi Runtime & Self-Host Auth",
-        changes: [],
-        features: [
-          "Per-agent `model` field with a provider-aware dropdown — pick the LLM model for each agent from the UI or via `multica agent create/update --model`, with live discovery from each runtime's CLI",
-          "Kimi CLI as a new agent runtime (Moonshot AI's `kimi-cli` over ACP), with model selection, auto-approved tool permissions, and streaming tool-call rendering",
-          "Expand toggle on inline comment and reply editors for composing long text",
-        ],
-        fixes: [
-          "Posting the result comment is now an explicit, numbered step in agent workflows so final replies reach the issue instead of terminal output",
-          "Agent live status card no longer leaks across issues when switching via Cmd+K",
-          "Self-hosted session cookies honor the `FRONTEND_ORIGIN` scheme — plain-HTTP deployments stop silently dropping cookies, and `COOKIE_DOMAIN=<ip>` now falls back to host-only with a warning instead of breaking login",
-        ],
-      },
-      {
-        version: "0.2.7",
-        date: "2026-04-18",
-        title: "Sub-Issues from Editor, Self-Host Gating & MCP",
-        changes: [],
-        features: [
-          "Create sub-issue directly from selected text in the editor bubble menu",
-          "Self-hosted instance gating — `ALLOW_SIGNUP` and `ALLOWED_EMAIL_*` env vars to restrict account creation",
-          "Per-agent `mcp_config` field to restore MCP access",
-          "Desktop app hourly update poll with manual check button in settings",
-        ],
-        fixes: [
-          "Session hand-off to desktop when already logged in on web",
-          "Open redirect vulnerability on `?next=` validated",
-          "OpenClaw stops passing unsupported flags and properly delivers AgentInstructions",
-        ],
-      },
-      {
-        version: "0.2.5",
-        date: "2026-04-17",
-        title: "CLI Autopilot, Cmd+K & Daemon Identity",
-        changes: [],
-        features: [
-          "CLI `autopilot` commands for managing scheduled and triggered automations",
-          "CLI `issue subscriber` commands for subscription management",
-          "Cmd+K palette extended — theme toggle, quick new issue/project, copy link, switch workspace",
-          "Project and sub-issue progress as optional card properties on the issue list",
-          "Persistent daemon UUID identity — CLI and desktop share one daemon across restarts and machine moves",
-          "Sole-owner workspace leave preflight check",
-          "Persist comment collapse state across sessions",
-        ],
-        fixes: [
-          "Agents now triggered on comments regardless of issue status",
-          "Codex sandbox config fixed for macOS network access",
-          "Editor bubble menu rewritten with @floating-ui/dom for reliable scroll hiding",
-          "Autopilot creator automatically subscribed to autopilot-created issues",
-          "Autopilot workspace ID correctly resolved for run-only tasks",
-          "Desktop restricts `shell.openExternal` to http/https schemes (security)",
-          "Duplicate agent names return 409 instead of silently failing",
-          "New tabs in desktop inherit current workspace",
-        ],
-      },
-      {
-        version: "0.2.1",
-        date: "2026-04-16",
-        title: "New Agent Runtimes",
-        changes: [],
-        features: [
-          "GitHub Copilot CLI runtime support",
-          "Cursor Agent CLI runtime support",
-          "Pi agent runtime support",
-          "Workspace URL refactor — slug-first routing (`/{slug}/issues`) with legacy URL redirects",
-        ],
-        fixes: [
-          "Codex threads resume across tasks on the same issue",
-          "Codex turn errors surfaced instead of reporting empty output",
-          "Workspace usage correctly bucketed by task completion time",
-          "Autopilot run history rows fully clickable",
-          "Workspace isolation enforced on additional daemon and GC endpoints (security)",
-          "HTML-escape workspace and inviter names in invitation emails",
-          "Dev and production desktop instances can now coexist",
-        ],
-      },
       {
         version: "0.2.0",
         date: "2026-04-15",

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

@@ -26,7 +26,6 @@ export type LandingDict = {
     headlineLine2: string;
     subheading: string;
     cta: string;
-    downloadDesktop: string;
     worksWith: string;
     imageAlt: string;
   };

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

@@ -1,8 +1,6 @@
 import { githubUrl } from "../components/shared";
 import type { LandingDict } from "./types";
 
-export const ALLOW_SIGNUP = process.env.NEXT_PUBLIC_ALLOW_SIGNUP !== "false";
-
 export const zh: LandingDict = {
   header: {
     github: "GitHub",
@@ -15,9 +13,8 @@ export const zh: LandingDict = {
     headlineLine2: "\u4e0d\u662f\u4eba\u7c7b\u3002",
     subheading:
       "Multica \u662f\u4e00\u4e2a\u5f00\u6e90\u5e73\u53f0\uff0c\u5c06\u7f16\u7801 Agent \u53d8\u6210\u771f\u6b63\u7684\u961f\u53cb\u3002\u5206\u914d\u4efb\u52a1\u3001\u8ddf\u8e2a\u8fdb\u5ea6\u3001\u79ef\u7d2f\u6280\u80fd\u2014\u2014\u5728\u4e00\u4e2a\u5730\u65b9\u7ba1\u7406\u4f60\u7684\u4eba\u7c7b + Agent \u56e2\u961f\u3002",
-    cta: "免费开始",
-    downloadDesktop: "下载桌面端",
-    worksWith: "支持",
+    cta: "\u514d\u8d39\u5f00\u59cb",
+    worksWith: "\u652f\u6301",
     imageAlt: "Multica \u770b\u677f\u89c6\u56fe\u2014\u2014\u4eba\u7c7b\u548c Agent \u534f\u540c\u7ba1\u7406\u4efb\u52a1",
   },
 
@@ -122,10 +119,9 @@ export const zh: LandingDict = {
     headlineFaded: "\u53ea\u9700\u4e00\u5c0f\u65f6\u3002",
     steps: [
       {
-        title: ALLOW_SIGNUP ? "注册并创建您的工作空间" : "登录到您的工作空间",
-        description: ALLOW_SIGNUP
-          ? "输入您的邮箱，验证代码后即可使用。工作空间会自动创建——无需设置向导或配置表单。"
-          : "输入您的邮箱，验证代码后即可登录到您的工作空间——无需设置向导或配置表单。",
+        title: "\u6ce8\u518c\u5e76\u521b\u5efa\u5de5\u4f5c\u533a",
+        description:
+          "\u8f93\u5165\u90ae\u7bb1\uff0c\u9a8c\u8bc1\u7801\u786e\u8ba4\uff0c\u5373\u53ef\u8fdb\u5165\u3002\u5de5\u4f5c\u533a\u81ea\u52a8\u521b\u5efa\u2014\u2014\u65e0\u9700\u8bbe\u7f6e\u5411\u5bfc\uff0c\u65e0\u9700\u914d\u7f6e\u8868\u5355\u3002",
       },
       {
         title: "\u5b89\u88c5 CLI \u5e76\u8fde\u63a5\u4f60\u7684\u673a\u5668",
@@ -226,8 +222,7 @@ export const zh: LandingDict = {
         links: [
           { label: "\u529f\u80fd\u7279\u6027", href: "#features" },
           { label: "\u5982\u4f55\u5de5\u4f5c", href: "#how-it-works" },
-          { label: "更新日志", href: "/changelog" },
-          { label: "桌面端", href: "https://github.com/multica-ai/multica/releases/latest" },
+          { label: "\u66f4\u65b0\u65e5\u5fd7", href: "/changelog" },
         ],
       },
       resources: {
@@ -282,85 +277,6 @@ export const zh: LandingDict = {
       fixes: "问题修复",
     },
     entries: [
-      {
-        version: "0.2.8",
-        date: "2026-04-20",
-        title: "Agent 模型选择、Kimi Runtime 与自部署登录",
-        changes: [],
-        features: [
-          "Agent 新增 `model` 字段及按 Provider 聚合的模型下拉框——可在界面或通过 `multica agent create/update --model` 为每个 Agent 选择 LLM 模型，并从各 Runtime CLI 实时发现可用模型",
-          "新增 Kimi CLI Agent Runtime（Moonshot AI 的 `kimi-cli`，基于 ACP），支持模型选择、自动授权工具权限以及流式工具调用渲染",
-          "评论和回复编辑器新增放大按钮，便于撰写长文本",
-        ],
-        fixes: [
-          "Agent 工作流将“发布结果评论”提升为独立的显式步骤，确保最终回复送达 Issue 而不是只留在终端输出",
-          "通过 Cmd+K 切换 Issue 时不再出现其他 Issue 的 Agent 实时状态残留",
-          "自部署会话 Cookie 的 Secure 标志改由 `FRONTEND_ORIGIN` 协议决定——HTTP 部署不再因浏览器丢弃 Cookie 导致登录失败；`COOKIE_DOMAIN=<ip>` 会自动回退到 host-only 并输出警告",
-        ],
-      },
-      {
-        version: "0.2.7",
-        date: "2026-04-18",
-        title: "编辑器创建子 Issue、自部署门禁与 MCP",
-        changes: [],
-        features: [
-          "直接从编辑器气泡菜单将选中文本创建为子 Issue",
-          "自部署实例账户门禁——`ALLOW_SIGNUP` 和 `ALLOWED_EMAIL_*` 环境变量限制注册",
-          "Agent 新增 `mcp_config` 字段恢复 MCP 支持",
-          "桌面应用每小时检查更新，设置中新增手动检查按钮",
-        ],
-        fixes: [
-          "网页已登录时将会话交接给桌面应用",
-          "修复 `?next=` 开放重定向漏洞",
-          "OpenClaw 停止传递不支持的参数，正确传递 AgentInstructions",
-        ],
-      },
-      {
-        version: "0.2.5",
-        date: "2026-04-17",
-        title: "CLI Autopilot、Cmd+K 与 Daemon 身份",
-        changes: [],
-        features: [
-          "CLI `autopilot` 命令，管理定时和触发式自动化",
-          "CLI `issue subscriber` 订阅管理命令",
-          "Cmd+K 命令面板扩展——主题切换、快速创建 Issue/项目、复制链接、切换工作区",
-          "Issue 列表卡片可选显示项目和子 Issue 进度",
-          "Daemon 持久化 UUID 身份——CLI 和桌面应用共用同一个 daemon，跨重启和机器迁移保持一致",
-          "唯一所有者退出工作区的前置检查",
-          "评论折叠状态跨会话持久化",
-        ],
-        fixes: [
-          "Agent 现在在任意 Issue 状态下都会响应评论触发",
-          "修复 Codex 沙箱在 macOS 上的网络访问配置",
-          "编辑器气泡菜单改用 @floating-ui/dom 重写，滚动时正确隐藏",
-          "Autopilot 创建者自动订阅其生成的 Issue",
-          "Autopilot run-only 任务正确解析工作区 ID",
-          "桌面应用 `shell.openExternal` 限制仅允许 http/https 协议（安全）",
-          "重名 Agent 创建返回 409 而非静默失败",
-          "桌面应用新建标签页继承当前工作区",
-        ],
-      },
-      {
-        version: "0.2.1",
-        date: "2026-04-16",
-        title: "新增 Agent 运行时",
-        changes: [],
-        features: [
-          "支持 GitHub Copilot CLI 运行时",
-          "支持 Cursor Agent CLI 运行时",
-          "支持 Pi Agent 运行时",
-          "工作区 URL 改造——slug 优先路由（`/{slug}/issues`），旧链接自动重定向",
-        ],
-        fixes: [
-          "Codex 同一 Issue 下跨任务恢复会话线程",
-          "Codex 回合错误正确抛出，不再报告空输出",
-          "工作区用量按任务完成时间正确分桶",
-          "Autopilot 运行历史行整行可点击",
-          "Daemon 和 GC 端点加强工作区隔离校验（安全）",
-          "邀请邮件中的工作区和邀请人名称进行 HTML 转义",
-          "桌面应用开发版和生产版现在可以同时运行",
-        ],
-      },
       {
         version: "0.2.0",
         date: "2026-04-15",

apps/web/next.config.ts

@@ -6,7 +6,6 @@ import { resolve } from "path";
 config({ path: resolve(__dirname, "../../.env") });
 
 const remoteApiUrl = process.env.REMOTE_API_URL || "http://localhost:8080";
-const docsUrl = process.env.DOCS_URL || "http://localhost:4000";
 
 // Parse hostnames from CORS_ALLOWED_ORIGINS so that Next.js dev server
 // allows cross-origin HMR / webpack requests (e.g. from Tailscale IPs).
@@ -33,39 +32,24 @@ const nextConfig: NextConfig = {
     qualities: [75, 80, 85],
   },
   async rewrites() {
-    return {
-      // Run before file-system routes so /docs isn't shadowed by the
-      // [workspaceSlug] dynamic segment.
-      beforeFiles: [
-        {
-          source: "/docs",
-          destination: `${docsUrl}/docs`,
-        },
-        {
-          source: "/docs/:path*",
-          destination: `${docsUrl}/docs/:path*`,
-        },
-      ],
-      afterFiles: [
-        {
-          source: "/api/:path*",
-          destination: `${remoteApiUrl}/api/:path*`,
-        },
-        {
-          source: "/ws",
-          destination: `${remoteApiUrl}/ws`,
-        },
-        {
-          source: "/auth/:path*",
-          destination: `${remoteApiUrl}/auth/:path*`,
-        },
-        {
-          source: "/uploads/:path*",
-          destination: `${remoteApiUrl}/uploads/:path*`,
-        },
-      ],
-      fallback: [],
-    };
+    return [
+      {
+        source: "/api/:path*",
+        destination: `${remoteApiUrl}/api/:path*`,
+      },
+      {
+        source: "/ws",
+        destination: `${remoteApiUrl}/ws`,
+      },
+      {
+        source: "/auth/:path*",
+        destination: `${remoteApiUrl}/auth/:path*`,
+      },
+      {
+        source: "/uploads/:path*",
+        destination: `${remoteApiUrl}/uploads/:path*`,
+      },
+    ];
   },
 };
 

apps/web/test/helpers.tsx

@@ -59,7 +59,6 @@ export const mockAgents: Agent[] = [
     custom_env_redacted: false,
     visibility: "workspace",
     max_concurrent_tasks: 3,
-    model: "",
     owner_id: null,
     skills: [],
     created_at: "2026-01-01T00:00:00Z",

docker-compose.selfhost.yml

@@ -21,7 +21,6 @@ services:
       - "${POSTGRES_PORT:-5432}:5432"
     volumes:
       - pgdata:/var/lib/postgresql/data
-    restart: unless-stopped
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-multica} -d ${POSTGRES_DB:-multica}"]
       interval: 5s
@@ -56,9 +55,7 @@ services:
       CLOUDFRONT_KEY_PAIR_ID: ${CLOUDFRONT_KEY_PAIR_ID:-}
       CLOUDFRONT_PRIVATE_KEY: ${CLOUDFRONT_PRIVATE_KEY:-}
       COOKIE_DOMAIN: ${COOKIE_DOMAIN:-}
-      APP_ENV: ${APP_ENV:-production}
       MULTICA_APP_URL: ${MULTICA_APP_URL:-http://localhost:3000}
-    restart: unless-stopped
 
   frontend:
     build:
@@ -74,7 +71,6 @@ services:
       - "${FRONTEND_PORT:-3000}:3000"
     environment:
       HOSTNAME: "0.0.0.0"
-    restart: unless-stopped
 
 volumes:
   pgdata:

docs/analytics.md

@@ -1,207 +0,0 @@
-# Product Analytics
-
-This document is the source of truth for the analytics events Multica ships
-to PostHog. Events feed the acquisition → activation → expansion funnel that
-drives our weekly Active Workspaces (WAW) north-star metric.
-
-See [MUL-1122](https://github.com/multica-ai/multica) for the design context.
-
-## Configuration
-
-All analytics shipping is toggled by environment variables (see `.env.example`):
-
-| Variable | Meaning | Default |
-|---|---|---|
-| `POSTHOG_API_KEY` | PostHog project API key. Empty = no events are shipped. | `""` |
-| `POSTHOG_HOST` | PostHog host (US or EU cloud, or self-hosted URL). | `https://us.i.posthog.com` |
-| `ANALYTICS_DISABLED` | Set to `true`/`1` to force the no-op client even when `POSTHOG_API_KEY` is set. | `""` |
-
-Local dev and self-hosted instances run with `POSTHOG_API_KEY=""`, so **no
-events leave the process unless the operator explicitly opts in**.
-
-### Self-hosted instances
-
-Self-hosters should **never inherit a Multica-issued `POSTHOG_API_KEY`** —
-that would route their users' behavior to our analytics project. The
-defaults guarantee this:
-
-- `.env.example` ships `POSTHOG_API_KEY=` empty. The Docker self-host
-  compose does not set a default either.
-- With the key unset, `NewFromEnv` returns `NoopClient` and logs
-  `analytics: POSTHOG_API_KEY not set, using noop client` at startup — a
-  visible confirmation that nothing is shipped.
-- Operators who want their own analytics can set `POSTHOG_API_KEY` and
-  `POSTHOG_HOST` to point at their own PostHog project (Cloud or
-  self-hosted PostHog).
-- The frontend receives the key via `/api/config` (planned for PR 2), so
-  self-hosts' blank server config also disables frontend event shipping
-  automatically — no separate frontend opt-out plumbing required.
-
-## Architecture
-
-```
-handler → analytics.Client.Capture(Event)   ← non-blocking, returns immediately
-                    │
-                    ▼
-           bounded queue (1024 events)
-                    │
-                    ▼
-     background worker: batch + POST /batch/
-                    │
-                    ▼
-                PostHog
-```
-
-- `analytics.Capture` is **never allowed to block a request handler**. A
-  broken backend must not degrade the product — when the queue is full,
-  events are dropped and counted (visible via `slog` + the `dropped` counter
-  on shutdown).
-- Batches flush either when `BatchSize` is reached or every `FlushEvery`
-  (default 10 s), whichever comes first.
-- `Close()` drains remaining events during graceful shutdown. Called from
-  `server/cmd/server/main.go` via `defer`.
-
-## Identity model
-
-- **`distinct_id`** — always the user's UUID for logged-in events. The
-  frontend's `posthog.identify(user.id)` merges any prior anonymous events
-  under the same identity, so acquisition attribution (UTM / referrer) stays
-  intact across signup.
-- **`workspace_id`** — added to every event as a property when present. v1
-  uses event property filtering (free tier) rather than PostHog Groups
-  Analytics (paid) to compute workspace-level metrics.
-- **PII** — events carry `email_domain` (e.g. `gmail.com`), not the full
-  email. Full email is stored once in person properties via `$set_once` so
-  it's available for individual debugging but not broadcast with every
-  event.
-
-## Event contract
-
-### `signup`
-
-Fires when a new user is created. Covers both verification-code and Google
-OAuth entry points (`findOrCreateUser` is the single emission site).
-
-| Property | Type | Description |
-|---|---|---|
-| `email_domain` | string | Lower-cased domain portion of the user's email. |
-| `signup_source` | string | Opaque attribution bundle from the frontend cookie `multica_signup_source` (UTM + referrer). Empty when the cookie is absent. |
-| `auth_method` | string | Optional. `"google"` for Google OAuth signups. Absent for verification-code signups. |
-
-Person properties set with `$set_once`:
-
-| Property | Type | Description |
-|---|---|---|
-| `email` | string | Full email. Never broadcast per-event. |
-| `signup_source` | string | Same as above; kept on the person for later segmentation. |
-
-### `workspace_created`
-
-Fires after a `CreateWorkspace` transaction commits successfully.
-
-| Property | Type | Description |
-|---|---|---|
-| `workspace_id` | string (UUID) | Added globally; present here for clarity. |
-
-**Note on "first workspace" segmentation** — we deliberately do *not* stamp
-an `is_first_workspace` boolean at emit time. Computing it correctly would
-require an extra column or transaction-scoped logic that still races under
-concurrent creates. Instead, PostHog answers the same question exactly by
-looking at whether the user has a prior `workspace_created` event (use a
-funnel with "first time user does X" or a cohort on
-`person_properties.$initial_event`). No information is lost.
-
-### `runtime_registered`
-
-Fires the first time a `(workspace_id, daemon_id, provider)` tuple is
-upserted. Heartbeats and repeat registrations never re-emit. First-time
-detection uses Postgres `xmax = 0` on the upsert RETURNING clause — no
-extra query, no race.
-
-| Property | Type | Description |
-|---|---|---|
-| `runtime_id` | string (UUID) | The newly created agent_runtime row id. |
-| `provider` | string | e.g. `"codex"`, `"claude"`. |
-| `runtime_version` | string | Version of the agent runtime binary. |
-| `cli_version` | string | Version of the `multica` CLI that registered it. |
-
-`distinct_id` is the authenticated owner's user id when the daemon was
-registered via a member's JWT/PAT; daemon-token registrations fall back to
-`workspace:<workspace_id>` so PostHog doesn't bucket unrelated daemons
-under a single "anonymous" person.
-
-### `issue_executed`
-
-Fires **at most once per issue** — when the first task on that issue
-reaches terminal `done` state. Backed by an atomic
-`UPDATE issue SET first_executed_at = now() WHERE id = $1 AND first_executed_at IS NULL RETURNING *`;
-retries, re-assignments, and comment-triggered follow-up tasks all hit the
-WHERE clause and no-op, so the `≥1 / ≥2 / ≥5 / ≥10` funnel buckets count
-distinct issues, not tasks.
-
-| Property | Type | Description |
-|---|---|---|
-| `issue_id` | string (UUID) | |
-| `task_duration_ms` | int64 | Wall-clock time between `task.started_at` and `task.completed_at`. Zero when the task was created in a completed state (rare). |
-
-`distinct_id` prefers the issue's human creator so agent-executed events
-flow into the issue-author's person profile (same place `signup` and
-`workspace_created` land). Agent-created issues prefix with `agent:` to
-keep PostHog from merging the agent into a user record.
-
-**Note on workspace-Nth ordinals** — we deliberately do *not* stamp
-`nth_issue_for_workspace` at emit time. Computing it correctly would
-require either a serialised transaction or an advisory lock per workspace;
-two concurrent first-completions could otherwise both read `count=1` and
-emit `n=1`. PostHog answers the same question at query time via
-`row_number() OVER (PARTITION BY properties.workspace_id ORDER BY timestamp)`,
-and funnel steps of the form "workspace has had ≥2 `issue_executed`
-events" are expressible without the property. No information is lost.
-
-### `team_invite_sent`
-
-Fires from `CreateInvitation` after the DB row is written.
-
-| Property | Type | Description |
-|---|---|---|
-| `invited_email_domain` | string | Lower-cased domain; full email lives in the invitation row, not the event. |
-| `invite_method` | string | Currently always `"email"`. Future non-email invite flows (share link, SCIM) should pass their own value. |
-
-`distinct_id` is the inviter's user id.
-
-### `team_invite_accepted`
-
-Fires from `AcceptInvitation` after both the invitation row is marked
-accepted and the member row is inserted in the same transaction.
-
-| Property | Type | Description |
-|---|---|---|
-| `days_since_invite` | int64 | Whole days from invitation creation to acceptance. Lets us segment "accepted same day" (warm) from "dug out of email weeks later" (cold). |
-
-`distinct_id` is the invitee's user id — this is the event that closes the
-expansion funnel.
-
-### Frontend-only events
-
-- `$pageview` — fired by `apps/web/components/pageview-tracker.tsx` on
-  every Next.js App Router path or query-string change. The tracker
-  mounts once under `WebProviders` and drives the acquisition funnel's
-  `/ → signup` step. posthog-js's automatic pageview capture is
-  disabled in `initAnalytics` so we own the event shape.
-- Attribution is NOT a separate event; UTM + referrer origin are written
-  to the `multica_signup_source` cookie on the first anonymous pageview
-  and read by the backend's `signup` emission. The cookie carries a JSON
-  payload URL-encoded at write time (`encodeURIComponent`) and
-  URL-decoded at read time (`url.QueryUnescape`) — the JSON is never
-  mid-truncated; individual values are capped at 96 chars before
-  `JSON.stringify`, and the entire payload is dropped if it still exceeds
-  512 chars. That way PostHog sees either intact JSON or nothing at all.
-
-## Governance
-
-Before adding, renaming, or removing any event:
-
-1. Update this document first.
-2. Update `server/internal/analytics/events.go` constants and helpers to
-   match.
-3. PR description must state which existing funnel / insight is affected.

docs/codex-sandbox-troubleshooting.md

@@ -1,107 +0,0 @@
-# Codex sandbox troubleshooting (macOS `no such host`)
-
-This doc explains the failure mode that caused [MUL-963][mul-963] and the
-matrix the daemon now follows when writing Codex's per-task `config.toml`.
-
-[mul-963]: https://multica-api.copilothub.ai/issues/28c34ad2-102a-4f46-91ac-336ed78c5859
-
-## Symptom fingerprint
-
-| Error text                                                    | Likely cause                                                                    |
-| ------------------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `dial tcp: lookup HOST: no such host`                         | **Codex Seatbelt sandbox blocking DNS** (macOS, `workspace-write` mode). |
-| `dial tcp IP:PORT: connect: connection refused`               | Server/daemon not running on that port (app-level, not sandbox).                |
-| `dial tcp IP:PORT: i/o timeout`                               | Container-level network policy or firewall (not Codex sandbox).                 |
-| `x509: certificate signed by unknown authority`               | TLS/CA issue, unrelated.                                                        |
-
-If you see `no such host` *inside a Codex session on macOS* but `curl https://multica-api.copilothub.ai` from a plain shell on the same machine works, you are hitting the Seatbelt bug below.
-
-## Root cause
-
-Upstream issue: [openai/codex#10390][codex-10390]. On macOS, Codex's Seatbelt
-profile for `sandbox_mode = "workspace-write"` silently ignores the
-`[sandbox_workspace_write] network_access = true` setting. The seatbelt
-policy hard-codes `CODEX_SANDBOX_NETWORK_DISABLED=1`, which blocks DNS/UDP
-syscalls. Go's `net.LookupHost` surfaces that as `no such host`.
-
-Linux (Landlock) is **not** affected — only macOS Seatbelt.
-
-[codex-10390]: https://github.com/openai/codex/issues/10390
-
-## What the daemon does now
-
-The daemon writes a *multica-managed* block into each task's
-`$CODEX_HOME/config.toml`, delimited by `# BEGIN multica-managed` /
-`# END multica-managed` markers. Anything outside the markers is left
-untouched so users can still tune Codex behavior.
-
-Decision matrix (see [`server/internal/daemon/execenv/codex_sandbox.go`](../server/internal/daemon/execenv/codex_sandbox.go)):
-
-| Host OS   | Codex version                                    | Managed block emits                                                       |
-| --------- | ------------------------------------------------ | ------------------------------------------------------------------------- |
-| non-darwin | any                                              | `sandbox_mode = "workspace-write"` + `sandbox_workspace_write.network_access = true` (dotted-key form) |
-| darwin    | ≥ `CodexDarwinNetworkAccessFixedVersion`         | same as above (upstream fix in effect)                                    |
-| darwin    | older / unknown (current default)                | `sandbox_mode = "danger-full-access"` + warn-level log                     |
-
-The managed block is always hoisted to the top of `config.toml` and uses
-TOML dotted-key syntax rather than a `[sandbox_workspace_write]` section
-header. Both are load-bearing: if the block sat after a user table like
-`[permissions.multica]`, a bare `sandbox_mode = "..."` line would be parsed
-as `permissions.multica.sandbox_mode` and Codex would silently ignore it.
-
-`CodexDarwinNetworkAccessFixedVersion` is an empty string today, meaning *no
-known fixed release yet*. Bump it once a tagged Codex release includes the
-upstream fix.
-
-When the daemon falls back to `danger-full-access`, it logs at `WARN`:
-
-```
-codex sandbox: falling back to danger-full-access on macOS
-  reason=codex on macOS: seatbelt ignores sandbox_workspace_write.network_access (openai/codex#10390) ...
-  codex_version=0.121.0
-  hint=upgrade Codex CLI (e.g. `brew upgrade codex` or `npm i -g @openai/codex`) ...
-  config_path=/.../codex-home/config.toml
-```
-
-## Quick self-check commands
-
-From the host shell (outside the sandbox):
-
-```bash
-# Is the Multica API reachable at all?
-curl -sSf https://multica-api.copilothub.ai/healthz
-```
-
-From inside a Codex session (after the daemon writes its config):
-
-```bash
-multica issue list --limit 1 --output json >/dev/null && echo OK
-```
-
-If the host curl works but the Codex-session call fails with `no such host`,
-the sandbox is the culprit; confirm the daemon picked the right policy by
-looking at the managed block in `$CODEX_HOME/config.toml`.
-
-## Options and trade-offs
-
-- **A. Domain-scoped `permissions` profile** (tight): when the upstream
-  `network_access` fix is available, prefer writing a `permissions.multica`
-  profile that allows only `multica-api.copilothub.ai` and
-  `multica-static.copilothub.ai`. Keeps filesystem sandbox intact.
-- **B. `danger-full-access`** (current macOS fallback): drops the whole
-  Seatbelt profile. Simplest reliable workaround until the upstream fix is
-  released.
-- **C. Upgrade Codex CLI**: `brew upgrade codex` or `npm i -g @openai/codex`.
-  Once a release containing [openai/codex#10390][codex-10390] is installed,
-  bump `CodexDarwinNetworkAccessFixedVersion` in `codex_sandbox.go` and
-  option A/the workspace-write path takes over automatically.
-
-## If you need to hand-verify
-
-```bash
-# Inspect the managed block the daemon wrote for a given task.
-sed -n '/# BEGIN multica-managed/,/# END multica-managed/p' \
-  ~/multica_workspaces/$WORKSPACE_ID/$TASK_SHORT/codex-home/config.toml
-```
-
-The block is idempotent — re-running a task rewrites it in place.

docs/plans/2026-04-16-unify-workspace-identity-resolver.md

@@ -1,357 +0,0 @@
-# Unify Workspace Identity Resolver Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Fix broken file uploads caused by the workspace slug refactor (v2, PR #1138/#1141), and eliminate the structural bug source that allowed it. File uploads from within a workspace on the desktop and web apps currently land in S3 without a corresponding DB attachment record — the file is orphaned and the UI never sees it.
-
-**Architecture:** The server currently has **two independent implementations** of the same logic — extract the workspace UUID from an HTTP request. One lives in the workspace middleware (post-v2, accepts slug header → DB lookup → UUID). The other lives inside the handler package (pre-v2, only accepts UUID header/query). The v2 refactor updated the middleware one and forgot the handler one; routes that sit *outside* the workspace middleware group (notably `/api/upload-file`) still run through the stale resolver and can't translate the frontend's new `X-Workspace-Slug` header.
-
-The root cause is duplication. The fix is to collapse both resolvers into a single shared function that middleware and handlers both delegate to, so any future change to "how do we read workspace identity" is impossible to forget. The existing middleware's resolver already has the full logic; we extract it into a package-level function and have the handler helper call it.
-
-**Tech Stack:** Go (Chi router, sqlc, pgx).
-
-**Non-goals:**
-- No frontend changes. The frontend has been sending `X-Workspace-Slug` since v2; this plan makes the server finish accepting it everywhere.
-- No route reshuffling. `/api/upload-file` stays outside `RequireWorkspaceMember` because it serves two distinct use cases (avatar upload + workspace attachment); the avatar path needs to work without a workspace context.
-- No change to CLI / daemon clients. They still send `X-Workspace-ID` (UUID); the resolver keeps UUID as a fallback.
-
----
-
-## Overview
-
-| # | Change | Type | Files |
-|---|--------|------|-------|
-| 1 | Extract shared resolver into middleware package | Refactor | `server/internal/middleware/workspace.go` |
-| 2 | Promote handler `resolveWorkspaceID` to `(h *Handler).resolveWorkspaceID` + delegate to shared | Refactor | `server/internal/handler/handler.go` |
-| 3 | Rename 47 call sites from `resolveWorkspaceID(r)` → `h.resolveWorkspaceID(r)` | Mechanical | handler/*.go (see exhaustive list in task 3) |
-| 4 | Add test for upload-file with slug header | Test | `server/internal/handler/file_test.go` |
-| 5 | Add test for shared resolver | Test | `server/internal/middleware/workspace_test.go` |
-| 6 | `make check` and commit | Verify | — |
-
----
-
-## Background: what's broken and why
-
-**Frontend (current, post-v2):** `ApiClient.authHeaders()` in `packages/core/api/client.ts:121` sends:
-```
-X-Workspace-Slug: <slug>
-```
-
-**Server middleware resolver** (`server/internal/middleware/workspace.go:53-86`, `resolveWorkspaceUUID`): accepts the slug header, looks up the slug via `queries.GetWorkspaceBySlug`, and writes the resolved UUID into the request context. Every handler behind `RequireWorkspaceMember` / `RequireWorkspaceRole` / `RequireWorkspaceMemberFromURL` sees the UUID in context and works correctly.
-
-**Handler resolver** (`server/internal/handler/handler.go:155-165`, `resolveWorkspaceID`): a parallel implementation used by handlers that are NOT behind the workspace middleware. It only checks:
-1. `middleware.WorkspaceIDFromContext(r.Context())`
-2. `?workspace_id` query param
-3. `X-Workspace-ID` header
-
-Never touches slug, because it has no `*db.Queries` access (it's a package-level function, not a method).
-
-**Impact:** `/api/upload-file` (registered at `server/cmd/server/router.go:166`, in the user-scoped group, outside workspace middleware) calls `resolveWorkspaceID(r)`, gets `""` because the frontend only sends slug, thinks "no workspace context", and silently skips the DB attachment record creation (`server/internal/handler/file.go:235-245`). The file reaches S3; the UI never sees it.
-
-**Why `/api/upload-file` is outside workspace middleware:** it serves both "avatar upload (no workspace)" and "attachment upload (with workspace)", branching on the resolved workspace ID inside the handler. Moving it under `RequireWorkspaceMember` would break avatar uploads.
-
-**Structural root cause:** two resolvers, same job, divergent capabilities. The duplication is what let v2 ship "mostly working" — most handlers live behind middleware, so the broken handler resolver had a low blast radius that wasn't caught in review.
-
----
-
-### Task 1: Extract shared resolver into middleware package
-
-**Problem:** The middleware's `resolveWorkspaceUUID` closure captures `*db.Queries` and can look up slugs. The handler's `resolveWorkspaceID` is a bare package-level function without queries access. We need a single implementation both sides can reuse. Putting it in the `middleware` package is fine — the `handler` package already imports `middleware`.
-
-**Files:**
-- Modify: `server/internal/middleware/workspace.go`
-
-**Step 1: Add `ResolveWorkspaceIDFromRequest` export**
-
-After `errWorkspaceNotFound` (around line 45), add a package-level exported function that takes `(r *http.Request, queries *db.Queries)` and returns the workspace UUID as a string (empty if none found or slug doesn't resolve).
-
-Priority order (mirrors `resolveWorkspaceUUID`, plus a context lookup first so handlers behind middleware still get the fast path):
-
-```go
-// ResolveWorkspaceIDFromRequest returns the workspace UUID for an HTTP
-// request, using the same priority order as the workspace middleware.
-// Handlers behind workspace middleware get it from context (cheap); handlers
-// outside middleware (e.g. /api/upload-file) still resolve slug → UUID via
-// a DB lookup instead of silently falling through to "no workspace".
-//
-// Priority:
-//  1. middleware-injected context (if the route is behind workspace middleware)
-//  2. X-Workspace-Slug header → GetWorkspaceBySlug → UUID (post-refactor frontend)
-//  3. ?workspace_slug query → GetWorkspaceBySlug → UUID
-//  4. X-Workspace-ID header (CLI/daemon compat)
-//  5. ?workspace_id query (CLI/daemon compat)
-//
-// Returns "" when no identifier was provided OR a slug was provided but doesn't
-// resolve to any workspace. Callers that need the "slug provided but invalid"
-// distinction should use the resolver inside the middleware directly.
-func ResolveWorkspaceIDFromRequest(r *http.Request, queries *db.Queries) string {
-    if id := WorkspaceIDFromContext(r.Context()); id != "" {
-        return id
-    }
-    if slug := r.Header.Get("X-Workspace-Slug"); slug != "" {
-        if ws, err := queries.GetWorkspaceBySlug(r.Context(), slug); err == nil {
-            return util.UUIDToString(ws.ID)
-        }
-    }
-    if slug := r.URL.Query().Get("workspace_slug"); slug != "" {
-        if ws, err := queries.GetWorkspaceBySlug(r.Context(), slug); err == nil {
-            return util.UUIDToString(ws.ID)
-        }
-    }
-    if id := r.Header.Get("X-Workspace-ID"); id != "" {
-        return id
-    }
-    return r.URL.Query().Get("workspace_id")
-}
-```
-
-**Step 2: Refactor `resolveWorkspaceUUID` to delegate**
-
-The existing middleware closure has slightly different semantics (returns `errWorkspaceNotFound` when a slug was provided but doesn't resolve, so middleware can 404 instead of 400). Keep that, but share the resolution logic:
-
-Leave `resolveWorkspaceUUID` as-is for now — it distinguishes "no identifier" (400) from "invalid slug" (404). `ResolveWorkspaceIDFromRequest` returns "" in both cases because handler-level callers don't need that distinction (they just check for empty).
-
-Document in a comment near `resolveWorkspaceUUID` that it's an internal variant that preserves the error distinction for middleware gating, and point to `ResolveWorkspaceIDFromRequest` as the handler-facing API.
-
-**Step 3: Build and verify**
-
-```bash
-cd server && go build ./...
-```
-Expected: clean build.
-
-**Step 4: Commit**
-
-```
-refactor(server): extract ResolveWorkspaceIDFromRequest from middleware
-
-Introduces a shared helper that consolidates the workspace-identity
-resolution logic used by both the workspace middleware and the handler
-package. No behavior change yet — callers still use the old functions.
-Sets up the next commit to fix the /api/upload-file slug bug by routing
-the handler-side resolver through this shared function.
-```
-
----
-
-### Task 2: Promote handler resolver to a method + delegate
-
-**Problem:** The package-level `resolveWorkspaceID(r *http.Request)` in `handler.go` can't call `GetWorkspaceBySlug` because it has no queries access. Promoting it to a method on `*Handler` gives it access to `h.Queries` at no syntactic cost elsewhere.
-
-**Files:**
-- Modify: `server/internal/handler/handler.go:155-165`
-
-**Step 1: Replace `resolveWorkspaceID` with a Handler method**
-
-```go
-// resolveWorkspaceID resolves the workspace UUID for this request.
-// Delegates to middleware.ResolveWorkspaceIDFromRequest so routes inside
-// and outside workspace middleware see identical resolution behavior.
-//
-// Returns "" when no workspace identifier was provided or a slug was
-// provided but doesn't match any workspace.
-func (h *Handler) resolveWorkspaceID(r *http.Request) string {
-    return middleware.ResolveWorkspaceIDFromRequest(r, h.Queries)
-}
-```
-
-Delete the old package-level `resolveWorkspaceID` function.
-
-**Step 2: Build — expect errors at 47 call sites**
-
-```bash
-cd server && go build ./... 2>&1 | head -60
-```
-
-Expected: `resolveWorkspaceID is not a value` or `undefined: resolveWorkspaceID` errors at each existing call site. That's the signal to run Task 3.
-
-**Do not commit yet.** Task 2 and 3 are a single logical change; they commit together after Task 3 fixes the compile.
-
----
-
-### Task 3: Rename 47 call sites to `h.resolveWorkspaceID(r)`
-
-**Problem:** Every `resolveWorkspaceID(r)` call in the handler package now fails to compile because the function became a method. All 47 call sites are inside methods on `*Handler` (or similar receiver types that have access to `h`), so the rename is mechanical.
-
-**Files affected** (verified via `grep -rn "resolveWorkspaceID" server/internal/handler/`):
-
-- `server/internal/handler/handler.go:275, 365, 388` (3 sites)
-- `server/internal/handler/issue.go:447, 559, 731, 783, 1294, 1476` (6 sites)
-- `server/internal/handler/activity.go:133` (1 site)
-- `server/internal/handler/autopilot.go:178, 203, 255, 306, 386, 414, 490, 578, 615, 662` (10 sites)
-- `server/internal/handler/project.go:80, 127, 150, 192, 273, 430` (6 sites)
-- `server/internal/handler/comment.go:443, 510` (2 sites)
-- `server/internal/handler/runtime.go:207, 247, 296` (3 sites)
-- `server/internal/handler/pin.go:59, 105, 175, 202` (4 sites)
-- `server/internal/handler/reaction.go:43, 110` (2 sites)
-- `server/internal/handler/skill.go:126, 146, 187, 384, 815` (5 sites)
-- `server/internal/handler/agent.go:158, 254` (2 sites)
-- `server/internal/handler/file.go:83, 115, 282, 306` (4 sites)
-
-Total: 48 (the resolver declaration itself + 47 callers).
-
-**Step 1: Mechanical rename**
-
-For each file above, change every `resolveWorkspaceID(r)` to `h.resolveWorkspaceID(r)`. In the one case in `file.go:83` inside `groupAttachments`, the receiver is already `*Handler`, so the method is accessible.
-
-**Semantic check:** all 47 call sites are on methods with an `h *Handler` receiver (verifiable by scrolling up a few lines from each grep match). If any call site is inside a non-method function, that site needs to either take `*Handler` as a parameter or be skipped from this rename. Spot-check three sites before doing the rename.
-
-**Step 2: Build**
-
-```bash
-cd server && go build ./...
-```
-Expected: clean build.
-
-**Step 3: Run Go tests**
-
-```bash
-cd server && go test ./...
-```
-Expected: all pass. The 46 call sites behind workspace middleware hit the context branch (identical behavior to before). Only `UploadFile` gains new capability (slug resolution); it wasn't tested before, will be covered in Task 4.
-
-**Step 4: Commit**
-
-```
-fix(server): resolve X-Workspace-Slug in /api/upload-file and other middleware-less handlers
-
-The v2 workspace URL refactor updated the workspace middleware to accept
-X-Workspace-Slug but left the handler-package resolveWorkspaceID helper
-(used by handlers outside the middleware group) stuck on X-Workspace-ID.
-The frontend switched to the slug header, so /api/upload-file was
-receiving a slug it couldn't translate to a UUID, silently falling
-through to the avatar-upload branch and skipping DB attachment record
-creation — files were landing in S3 with no database reference.
-
-Promote resolveWorkspaceID to a Handler method and delegate to the new
-middleware.ResolveWorkspaceIDFromRequest so middleware-behind and
-middleware-outside handlers share the same resolution logic. The 46
-call sites that live inside the workspace middleware group are
-unaffected (context lookup still wins). /api/upload-file now correctly
-recognizes slug requests and creates the attachment record.
-
-Fixes: missing DB attachment rows for files uploaded since v2 (#1141)
-```
-
----
-
-### Task 4: Add handler test for upload-file with slug header
-
-**Problem:** The bug manifested exactly because there was no test covering the "upload-file with only a slug header" code path. Prevent regression.
-
-**Files:**
-- Modify: `server/internal/handler/file_test.go` (or create if absent)
-
-**Step 1: Locate existing upload-file test infrastructure**
-
-```bash
-grep -rn "UploadFile\|upload-file" server/internal/handler/*_test.go
-```
-
-If there's an existing upload-file test, add a new test case alongside it. If not, scaffold one using the same `handler_test.go` fixture pattern (`testWorkspaceID`, `testUserID`, seeded workspace).
-
-**Step 2: Write the test**
-
-Test name: `TestUploadFile_ResolvesWorkspaceViaSlugHeader`.
-
-Flow:
-1. Seed a workspace with a known slug and the default test user as a member.
-2. POST a multipart form to `/api/upload-file` with an `issue_id` field referencing a seeded issue, with only `X-Workspace-Slug: <slug>` in headers (no `X-Workspace-ID`).
-3. Assert response is 200.
-4. Assert a DB row exists in `attachments` with the expected `workspace_id`, `uploader_id`, `issue_id`, and `filename`.
-
-Anti-regression: also add `TestUploadFile_ResolvesWorkspaceViaIDHeaderStill` to confirm legacy `X-Workspace-ID` header still works (CLI / daemon compat).
-
-**Step 3: Run the new test**
-
-```bash
-cd server && go test ./internal/handler/ -run UploadFile
-```
-Expected: both pass.
-
-**Step 4: Commit**
-
-```
-test(server): cover upload-file slug and UUID header resolution
-
-Regression test for the v2 refactor bug: uploads from the frontend
-(which sends X-Workspace-Slug) now reach the workspace-aware branch
-and create attachment records.
-```
-
----
-
-### Task 5: Add unit test for the shared resolver
-
-**Problem:** The shared function will be the single point through which all workspace identity resolution flows. It deserves table-driven test coverage for each priority level.
-
-**Files:**
-- Create or modify: `server/internal/middleware/workspace_test.go`
-
-**Step 1: Table test**
-
-Cases to cover:
-- Context UUID present → returns context UUID, ignores headers/query
-- Only `X-Workspace-Slug` → DB lookup succeeds → returns UUID
-- Only `X-Workspace-Slug` → DB lookup fails → returns ""
-- Only `?workspace_slug` → DB lookup succeeds → returns UUID
-- Only `X-Workspace-ID` → returns UUID
-- Only `?workspace_id` → returns UUID
-- Slug header + UUID header both present → slug wins (frontend priority)
-- Nothing → returns ""
-
-**Step 2: Run**
-
-```bash
-cd server && go test ./internal/middleware/ -run ResolveWorkspaceIDFromRequest
-```
-Expected: all cases pass.
-
-**Step 3: Commit**
-
-```
-test(server): table-driven coverage for ResolveWorkspaceIDFromRequest
-
-Pins down the priority order (context > slug header > slug query >
-UUID header > UUID query) so future changes can't silently diverge.
-```
-
----
-
-### Task 6: Full verification
-
-**Step 1: `make check`**
-
-```bash
-make check
-```
-Expected: typecheck, TS tests, Go tests, E2E (if backend+frontend up) all green.
-
-**Step 2: Manual smoke test**
-
-1. Start desktop dev environment.
-2. Open an issue, attach a file via drag-and-drop or the file picker.
-3. Refresh the issue. The attachment should appear in the attachments list.
-
-Before this fix: attachment silently disappears on refresh (file is in S3, DB has no row).
-
-**Step 3: Open PR**
-
-Branch name: `fix/unify-workspace-identity-resolver`.
-
-Title: `fix(server): resolve X-Workspace-Slug in middleware-less handlers`
-
-Body should:
-- Link to the symptom PR (v2 refactor #1141) and reference that it's a latent follow-up.
-- Describe the structural change (two resolvers → one).
-- Note that 46 of 47 call sites see zero behavior change (context branch wins); only `/api/upload-file` gains capability.
-
----
-
-## Risk / blast radius
-
-**Low risk.** The 46 middleware-protected callers hit the context branch in `ResolveWorkspaceIDFromRequest` identically to how they hit `WorkspaceIDFromContext` before — zero semantic change. The only new code path exercised in production is the slug-header branch for `/api/upload-file`, which is already exercised by every other slug-header-carrying request (just via the middleware's version of the same logic). Task 4 and 5 lock the behavior down with tests.
-
-## Rollback plan
-
-If a regression surfaces after deploy, revert the single commit from Task 3. `ResolveWorkspaceIDFromRequest` and the Handler method remain but are unused — harmless dead code until the next attempt.

packages/core/analytics/index.ts

@@ -1,208 +0,0 @@
-// Frontend analytics glue. Thin wrapper over posthog-js.
-//
-// The source-of-truth event catalog is `docs/analytics.md`. This module only
-// handles the two things the backend can't do itself: attribution capture on
-// first anonymous pageview, and person-identity merge on login. Every funnel
-// event (signup, workspace_created, runtime_registered, issue_executed,
-// invite_sent, invite_accepted) is emitted server-side — see
-// `server/internal/analytics`.
-//
-// Configuration comes from the backend's `/api/config` response (populated
-// from POSTHOG_API_KEY on the server), NOT from NEXT_PUBLIC_* envs. That
-// keeps self-hosted Docker images from leaking our project key — their
-// backend returns an empty key and this module stays inert.
-
-import posthog from "posthog-js";
-
-const SIGNUP_SOURCE_COOKIE = "multica_signup_source";
-// Per-value cap keeps a long utm_content from blowing the budget. We drop
-// the entire cookie if the JSON still exceeds the overall limit — partial
-// JSON is worse than no attribution because PostHog can't parse it.
-const SIGNUP_SOURCE_VALUE_MAX_LEN = 96;
-const SIGNUP_SOURCE_MAX_LEN = 512;
-const UTM_KEYS = [
-  "utm_source",
-  "utm_medium",
-  "utm_campaign",
-  "utm_content",
-  "utm_term",
-] as const;
-
-let initialized = false;
-// auth-initializer fetches /api/config and /api/me in parallel — on a
-// slow-config path, identify() can fire before initAnalytics(). Buffer the
-// most recent pending identify (only one matters, since it's per-session)
-// and flush it inside initAnalytics.
-let pendingIdentify: { userId: string; props?: Record<string, unknown> } | null = null;
-// Likewise pageviews: the initial "/" pageview is the anchor of the
-// acquisition funnel, and the Next.js router fires it on mount before the
-// config fetch resolves. We keep the first pending pageview so that step
-// doesn't silently drop.
-let pendingPageview: string | undefined | null = null;
-
-export interface AnalyticsConfig {
-  key: string;
-  host: string;
-}
-
-/**
- * Initialize posthog-js if a key is present. Safe to call multiple times;
- * subsequent calls with the same config are no-ops.
- *
- * Returns `true` when analytics is actually running; `false` when disabled
- * (no key, SSR, or already initialized with a conflicting key — which we
- * treat as "use the existing instance").
- */
-export function initAnalytics(config: AnalyticsConfig | null | undefined): boolean {
-  if (typeof window === "undefined") return false;
-  if (!config?.key) return false;
-  if (initialized) return true;
-
-  posthog.init(config.key, {
-    api_host: config.host || "https://us.i.posthog.com",
-    // person_profiles=identified_only keeps anonymous drive-by traffic off
-    // the billed events until they actually identify, which aligns with how
-    // our funnel is set up: signup is the first real funnel step.
-    person_profiles: "identified_only",
-    // Turn off every on-by-default auto-capture surface. Our funnel is
-    // narrow and explicit (the events in docs/analytics.md + a manual
-    // $pageview). Autocapture floods the Activity view with anonymous
-    // "clicked button" / "clicked link" noise, burns the billed event
-    // budget, and risks capturing user-typed content in input values.
-    // Turn things back on deliberately if we ever want them.
-    capture_pageview: false,
-    autocapture: false,
-    capture_heatmaps: false,
-    capture_dead_clicks: false,
-    capture_exceptions: false,
-    disable_session_recording: true,
-    disable_surveys: true,
-  });
-  initialized = true;
-
-  // Flush any identify() that arrived before init resolved.
-  if (pendingIdentify) {
-    posthog.identify(pendingIdentify.userId, pendingIdentify.props);
-    pendingIdentify = null;
-  }
-  // And any first pageview we captured while config was loading.
-  if (pendingPageview !== null) {
-    posthog.capture("$pageview", pendingPageview ? { $current_url: pendingPageview } : undefined);
-    pendingPageview = null;
-  }
-  return true;
-}
-
-/**
- * Merge the current anonymous session into the logged-in person. Must be
- * called exactly once per auth transition (login / session-resume). Pulling
- * attribution properties into person_properties on identify is how we keep
- * UTM / referrer on the user profile without re-emitting them per event.
- *
- * Calls before initAnalytics() are buffered — auth-initializer fetches
- * config and user in parallel, so identify can arrive first.
- */
-export function identify(userId: string, userProperties?: Record<string, unknown>): void {
-  if (!initialized) {
-    pendingIdentify = { userId, props: userProperties };
-    return;
-  }
-  posthog.identify(userId, userProperties);
-}
-
-/**
- * Clear the client-side identity on logout so the next login merges cleanly
- * and doesn't bleed the previous user's events into a new session.
- */
-export function resetAnalytics(): void {
-  pendingIdentify = null;
-  pendingPageview = null;
-  if (!initialized) return;
-  posthog.reset();
-}
-
-/**
- * Capture a page view. Call once per client-side navigation. We disable
- * posthog's automatic pageview tracking in init() so this module owns the
- * event shape — that makes it trivial to add properties (e.g. workspace
- * slug) without fighting the SDK.
- *
- * Calls before initAnalytics() buffer the most-recent path so the first
- * pageview isn't dropped on slow /api/config fetches. Subsequent pre-init
- * pageviews overwrite the buffer; after init flushes, every navigation
- * captures synchronously as expected.
- */
-export function capturePageview(path?: string): void {
-  if (!initialized) {
-    pendingPageview = path ?? "";
-    return;
-  }
-  posthog.capture("$pageview", path ? { $current_url: path } : undefined);
-}
-
-/**
- * On the very first anonymous pageview in a browser session, read UTM +
- * referrer and stash them in a cookie that the backend reads during signup.
- *
- * Never use raw `document.referrer` as attribution — it can leak OAuth
- * callback URLs with `code` / `state` in the query string. We keep only the
- * referrer's origin (scheme + host), which is what a funnel actually needs.
- *
- * This cookie is what `signup_source` in the backend's signup event reads
- * from; both fields are intentionally opaque JSON so the schema can evolve
- * without a backend deploy.
- */
-export function captureSignupSource(): void {
-  if (typeof window === "undefined" || typeof document === "undefined") return;
-  if (readCookie(SIGNUP_SOURCE_COOKIE)) return;
-
-  const source: Record<string, string> = {};
-  const cap = (v: string) =>
-    v.length > SIGNUP_SOURCE_VALUE_MAX_LEN ? v.slice(0, SIGNUP_SOURCE_VALUE_MAX_LEN) : v;
-
-  try {
-    const params = new URLSearchParams(window.location.search);
-    for (const key of UTM_KEYS) {
-      const v = params.get(key);
-      if (v) source[key] = cap(v);
-    }
-  } catch {
-    // URL APIs unavailable — skip silently.
-  }
-
-  const refOrigin = safeReferrerOrigin(document.referrer);
-  if (refOrigin) source.referrer_origin = cap(refOrigin);
-
-  if (Object.keys(source).length === 0) return;
-
-  const payload = JSON.stringify(source);
-  // Drop rather than mid-JSON truncate — a half-string would fail to parse
-  // on the backend and the attribution would be worse than missing.
-  if (payload.length > SIGNUP_SOURCE_MAX_LEN) return;
-
-  // 30-day expiry covers the typical signup consideration window. Lax is
-  // the right default — the cookie is only consumed by same-origin auth.
-  const maxAge = 60 * 60 * 24 * 30;
-  document.cookie = `${SIGNUP_SOURCE_COOKIE}=${encodeURIComponent(payload)}; path=/; max-age=${maxAge}; samesite=lax`;
-}
-
-function safeReferrerOrigin(referrer: string): string {
-  if (!referrer) return "";
-  try {
-    const url = new URL(referrer);
-    if (url.origin === window.location.origin) return "";
-    return url.origin;
-  } catch {
-    return "";
-  }
-}
-
-function readCookie(name: string): string {
-  if (typeof document === "undefined") return "";
-  const prefix = `${name}=`;
-  const parts = document.cookie ? document.cookie.split("; ") : [];
-  for (const part of parts) {
-    if (part.startsWith(prefix)) return decodeURIComponent(part.slice(prefix.length));
-  }
-  return "";
-}

packages/core/api/client.ts

@@ -35,7 +35,6 @@ import type {
   RuntimeHourlyActivity,
   RuntimePing,
   RuntimeUpdate,
-  RuntimeModelListRequest,
   TimelineEntry,
   AssigneeFrequencyEntry,
   TaskMessagePayload,
@@ -238,7 +237,6 @@ export class ApiClient {
     if (params?.assignee_id) search.set("assignee_id", params.assignee_id);
     if (params?.assignee_ids?.length) search.set("assignee_ids", params.assignee_ids.join(","));
     if (params?.creator_id) search.set("creator_id", params.creator_id);
-    if (params?.project_id) search.set("project_id", params.project_id);
     if (params?.open_only) search.set("open_only", "true");
     return this.fetch(`/api/issues?${search}`);
   }
@@ -472,17 +470,6 @@ export class ApiClient {
     return this.fetch(`/api/runtimes/${runtimeId}/update/${updateId}`);
   }
 
-  async initiateListModels(runtimeId: string): Promise<RuntimeModelListRequest> {
-    return this.fetch(`/api/runtimes/${runtimeId}/models`, { method: "POST" });
-  }
-
-  async getListModelsResult(
-    runtimeId: string,
-    requestId: string,
-  ): Promise<RuntimeModelListRequest> {
-    return this.fetch(`/api/runtimes/${runtimeId}/models/${requestId}`);
-  }
-
   async listAgentTasks(agentId: string): Promise<AgentTask[]> {
     return this.fetch(`/api/agents/${agentId}/tasks`);
   }
@@ -543,11 +530,7 @@ export class ApiClient {
   }
 
   // App Config
-  async getConfig(): Promise<{
-    cdn_domain: string;
-    posthog_key?: string;
-    posthog_host?: string;
-  }> {
+  async getConfig(): Promise<{ cdn_domain: string }> {
     return this.fetch("/api/config");
   }
 

packages/core/auth/index.ts

@@ -1,6 +1,5 @@
 export { createAuthStore } from "./store";
 export type { AuthStoreOptions, AuthState } from "./store";
-export { sanitizeNextUrl } from "./utils";
 
 import type { createAuthStore as CreateAuthStoreFn } from "./store";
 

packages/core/auth/store.test.ts

@@ -1,93 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { ApiClient } from "../api/client";
-import { ApiError } from "../api/client";
-import type { StorageAdapter, User } from "../types";
-import { createAuthStore } from "./store";
-
-const fakeUser: User = {
-  id: "u1",
-  name: "Alice",
-  email: "alice@example.com",
-  avatar_url: null,
-} as User;
-
-function makeStorage(initial: Record<string, string> = {}): StorageAdapter & {
-  snapshot: () => Record<string, string>;
-} {
-  const data = { ...initial };
-  return {
-    getItem: (k) => data[k] ?? null,
-    setItem: (k, v) => {
-      data[k] = v;
-    },
-    removeItem: (k) => {
-      delete data[k];
-    },
-    snapshot: () => ({ ...data }),
-  };
-}
-
-function makeApi(getMe: () => Promise<User>): ApiClient {
-  return {
-    setToken: vi.fn(),
-    getMe,
-    // Only the methods touched by store.initialize are needed. Cast to
-    // ApiClient for type compatibility — the store treats it opaquely.
-  } as unknown as ApiClient;
-}
-
-describe("authStore.initialize — token mode", () => {
-  it("keeps the stored token when getMe fails with a non-401 ApiError (e.g. 500)", async () => {
-    const storage = makeStorage({ multica_token: "t" });
-    const api = makeApi(() =>
-      Promise.reject(new ApiError("server error", 500, "Internal Server Error")),
-    );
-    const store = createAuthStore({ api, storage });
-
-    await store.getState().initialize();
-
-    expect(store.getState().user).toBeNull();
-    expect(store.getState().isLoading).toBe(false);
-    expect(storage.snapshot().multica_token).toBe("t");
-  });
-
-  it("keeps the stored token on a network failure (non-ApiError throw)", async () => {
-    const storage = makeStorage({ multica_token: "t" });
-    const api = makeApi(() => Promise.reject(new TypeError("fetch failed")));
-    const store = createAuthStore({ api, storage });
-
-    await store.getState().initialize();
-
-    expect(store.getState().user).toBeNull();
-    expect(storage.snapshot().multica_token).toBe("t");
-  });
-
-  it("on 401, leaves storage cleanup to ApiClient.onUnauthorized and resets state", async () => {
-    // Simulate the real path: ApiClient fires onUnauthorized on 401, which
-    // removes the token from storage. The store's catch block must not
-    // duplicate or short-circuit this — it should only reset in-memory
-    // auth state.
-    const storage = makeStorage({ multica_token: "t" });
-    const api = makeApi(() => {
-      storage.removeItem("multica_token"); // stand-in for onUnauthorized
-      return Promise.reject(new ApiError("unauthorized", 401, "Unauthorized"));
-    });
-    const store = createAuthStore({ api, storage });
-
-    await store.getState().initialize();
-
-    expect(store.getState().user).toBeNull();
-    expect(storage.snapshot().multica_token).toBeUndefined();
-  });
-
-  it("populates user when getMe succeeds", async () => {
-    const storage = makeStorage({ multica_token: "t" });
-    const api = makeApi(() => Promise.resolve(fakeUser));
-    const store = createAuthStore({ api, storage });
-
-    await store.getState().initialize();
-
-    expect(store.getState().user).toEqual(fakeUser);
-    expect(storage.snapshot().multica_token).toBe("t");
-  });
-});

packages/core/auth/store.ts

@@ -1,7 +1,6 @@
 import { create } from "zustand";
 import type { User, StorageAdapter } from "../types";
-import { identify as identifyAnalytics, resetAnalytics } from "../analytics";
-import { ApiError, type ApiClient } from "../api/client";
+import type { ApiClient } from "../api/client";
 import { setCurrentWorkspace } from "../platform/workspace-storage";
 
 export interface AuthStoreOptions {
@@ -58,17 +57,10 @@ export function createAuthStore(options: AuthStoreOptions) {
       try {
         const user = await api.getMe();
         set({ user, isLoading: false });
-      } catch (err) {
-        // Only clear the stored token on a genuine auth failure (401). For
-        // transient errors — network blips, backend rolling restarts, 5xx,
-        // aborted fetches — keep the token so the next initialize() (next
-        // page load or focus-refresh) can retry. The 401 path's token
-        // cleanup is handled upstream by ApiClient.handleUnauthorized via
-        // the onUnauthorized callback; we only need to reset the in-memory
-        // user + workspace state here.
-        if (err instanceof ApiError && err.status === 401) {
-          setCurrentWorkspace(null, null);
-        }
+      } catch {
+        api.setToken(null);
+        setCurrentWorkspace(null, null);
+        storage.removeItem("multica_token");
         set({ user: null, isLoading: false });
       }
     },
@@ -85,7 +77,6 @@ export function createAuthStore(options: AuthStoreOptions) {
         api.setToken(token);
       }
       onLogin?.();
-      identifyAnalytics(user.id, { email: user.email, name: user.name });
       set({ user });
       return user;
     },
@@ -97,7 +88,6 @@ export function createAuthStore(options: AuthStoreOptions) {
         api.setToken(token);
       }
       onLogin?.();
-      identifyAnalytics(user.id, { email: user.email, name: user.name });
       set({ user });
       return user;
     },
@@ -107,7 +97,6 @@ export function createAuthStore(options: AuthStoreOptions) {
       api.setToken(token);
       const user = await api.getMe();
       onLogin?.();
-      identifyAnalytics(user.id, { email: user.email, name: user.name });
       set({ user, isLoading: false });
       return user;
     },
@@ -120,7 +109,6 @@ export function createAuthStore(options: AuthStoreOptions) {
       storage.removeItem("multica_token");
       api.setToken(null);
       setCurrentWorkspace(null, null);
-      resetAnalytics();
       onLogout?.();
       set({ user: null });
     },

packages/core/auth/utils.test.ts

@@ -1,45 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { sanitizeNextUrl } from "./utils";
-
-describe("sanitizeNextUrl", () => {
-  it("accepts single-slash relative paths", () => {
-    expect(sanitizeNextUrl("/issues")).toBe("/issues");
-    expect(sanitizeNextUrl("/invite/123")).toBe("/invite/123");
-    expect(sanitizeNextUrl("/issues?tab=assigned#top")).toBe(
-      "/issues?tab=assigned#top",
-    );
-  });
-
-  it("returns null for null or empty input", () => {
-    expect(sanitizeNextUrl(null)).toBeNull();
-    expect(sanitizeNextUrl("")).toBeNull();
-  });
-
-  it("rejects absolute URLs", () => {
-    expect(sanitizeNextUrl("https://evil.example")).toBeNull();
-    expect(sanitizeNextUrl("http://evil.example/path")).toBeNull();
-  });
-
-  it("rejects javascript: and other non-http schemes", () => {
-    // Caught by the leading-slash rule, but named here so future edits
-    // to the regex don't silently drop protection against this vector.
-    expect(sanitizeNextUrl("javascript:alert(1)")).toBeNull();
-    expect(sanitizeNextUrl("data:text/html,<script>")).toBeNull();
-  });
-
-  it("rejects protocol-relative URLs", () => {
-    expect(sanitizeNextUrl("//evil.example")).toBeNull();
-    expect(sanitizeNextUrl("//evil.example/path")).toBeNull();
-  });
-
-  it("rejects paths containing backslashes", () => {
-    expect(sanitizeNextUrl("/\\evil.example")).toBeNull();
-    expect(sanitizeNextUrl("\\\\evil.example")).toBeNull();
-  });
-
-  it("rejects paths containing control characters", () => {
-    expect(sanitizeNextUrl("/safe\u0000bad")).toBeNull();
-    expect(sanitizeNextUrl("/safe\tbad")).toBeNull();
-    expect(sanitizeNextUrl("/safe\r\nbad")).toBeNull();
-  });
-});

packages/core/auth/utils.ts

@@ -1,20 +0,0 @@
-/**
- * Validate a post-login redirect URL and return it only if safe to follow.
- *
- * Only single-slash relative paths (e.g. `/invite/abc`) are accepted. Returns
- * `null` for unsafe or empty input — call sites decide the fallback so this
- * helper never overloads a specific path with "user did not pass next".
- *
- * Rejects:
- *   - `null` / empty string
- *   - absolute URLs (`https://evil.com`, `javascript:alert(1)`, …)
- *   - protocol-relative URLs (`//evil.com`)
- *   - paths containing backslashes (Windows-style or `/\\host`)
- *   - paths containing ASCII control characters (`\x00`–`\x1f`)
- */
-export function sanitizeNextUrl(raw: string | null): string | null {
-  if (!raw) return null;
-  if (!raw.startsWith("/") || raw.startsWith("//")) return null;
-  if (/[\x00-\x1f\\]/.test(raw)) return null;
-  return raw;
-}

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

@@ -1,74 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { QueryClient } from "@tanstack/react-query";
-import { onInboxIssueDeleted, onInboxIssueStatusChanged } from "./ws-updaters";
-import { inboxKeys } from "./queries";
-import type { InboxItem } from "../types";
-
-const wsId = "ws-1";
-
-function makeItem(
-  id: string,
-  issueId: string | null,
-  overrides: Partial<InboxItem> = {},
-): InboxItem {
-  return {
-    id,
-    workspace_id: wsId,
-    recipient_type: "member",
-    recipient_id: "user-1",
-    actor_type: null,
-    actor_id: null,
-    type: "mentioned",
-    severity: "info",
-    issue_id: issueId,
-    title: `item ${id}`,
-    body: null,
-    issue_status: null,
-    read: false,
-    archived: false,
-    created_at: "2025-01-01T00:00:00Z",
-    details: null,
-    ...overrides,
-  };
-}
-
-describe("onInboxIssueDeleted", () => {
-  it("removes all inbox items referencing the deleted issue", () => {
-    const qc = new QueryClient();
-    const items = [
-      makeItem("i1", "issue-a"),
-      makeItem("i2", "issue-a"),
-      makeItem("i3", "issue-b"),
-      makeItem("i4", null),
-    ];
-    qc.setQueryData<InboxItem[]>(inboxKeys.list(wsId), items);
-
-    onInboxIssueDeleted(qc, wsId, "issue-a");
-
-    const after = qc.getQueryData<InboxItem[]>(inboxKeys.list(wsId));
-    expect(after?.map((i) => i.id)).toEqual(["i3", "i4"]);
-  });
-
-  it("is a no-op when the inbox cache is empty", () => {
-    const qc = new QueryClient();
-    expect(() => onInboxIssueDeleted(qc, wsId, "issue-a")).not.toThrow();
-    expect(qc.getQueryData<InboxItem[]>(inboxKeys.list(wsId))).toBeUndefined();
-  });
-});
-
-describe("onInboxIssueStatusChanged", () => {
-  it("updates issue_status only for items referencing the issue", () => {
-    const qc = new QueryClient();
-    const items = [
-      makeItem("i1", "issue-a", { issue_status: "todo" }),
-      makeItem("i2", "issue-b", { issue_status: "todo" }),
-    ];
-    qc.setQueryData<InboxItem[]>(inboxKeys.list(wsId), items);
-
-    onInboxIssueStatusChanged(qc, wsId, "issue-a", "done");
-
-    const after = qc.getQueryData<InboxItem[]>(inboxKeys.list(wsId));
-    expect(after?.find((i) => i.id === "i1")?.issue_status).toBe("done");
-    expect(after?.find((i) => i.id === "i2")?.issue_status).toBe("todo");
-  });
-});

packages/core/inbox/ws-updaters.ts

@@ -25,19 +25,6 @@ export function onInboxIssueStatusChanged(
   );
 }
 
-// Mirrors the DB-level ON DELETE CASCADE on inbox_item.issue_id: when an issue
-// is deleted, all inbox items that referenced it are gone server-side, so drop
-// them from the cache too.
-export function onInboxIssueDeleted(
-  qc: QueryClient,
-  wsId: string,
-  issueId: string,
-) {
-  qc.setQueryData<InboxItem[]>(inboxKeys.list(wsId), (old) =>
-    old?.filter((i) => i.issue_id !== issueId),
-  );
-}
-
 export function onInboxInvalidate(qc: QueryClient, wsId: string) {
   qc.invalidateQueries({ queryKey: inboxKeys.list(wsId) });
 }

packages/core/issues/cache-helpers.ts

@@ -1,100 +0,0 @@
-import type {
-  Issue,
-  IssueStatus,
-  IssueStatusBucket,
-  ListIssuesCache,
-} from "../types";
-import { PAGINATED_STATUSES } from "./queries";
-
-const EMPTY_BUCKET: IssueStatusBucket = { issues: [], total: 0 };
-
-export function getBucket(
-  resp: ListIssuesCache,
-  status: IssueStatus,
-): IssueStatusBucket {
-  return resp.byStatus[status] ?? EMPTY_BUCKET;
-}
-
-export function setBucket(
-  resp: ListIssuesCache,
-  status: IssueStatus,
-  bucket: IssueStatusBucket,
-): ListIssuesCache {
-  return { ...resp, byStatus: { ...resp.byStatus, [status]: bucket } };
-}
-
-/** Locate which status bucket holds `id`, if any. */
-export function findIssueLocation(
-  resp: ListIssuesCache,
-  id: string,
-): { status: IssueStatus; issue: Issue } | null {
-  for (const status of PAGINATED_STATUSES) {
-    const bucket = resp.byStatus[status];
-    const found = bucket?.issues.find((i) => i.id === id);
-    if (found) return { status, issue: found };
-  }
-  return null;
-}
-
-/** Add an issue to its status bucket (no-op if already present). */
-export function addIssueToBuckets(
-  resp: ListIssuesCache,
-  issue: Issue,
-): ListIssuesCache {
-  const bucket = getBucket(resp, issue.status);
-  if (bucket.issues.some((i) => i.id === issue.id)) return resp;
-  return setBucket(resp, issue.status, {
-    issues: [...bucket.issues, issue],
-    total: bucket.total + 1,
-  });
-}
-
-/** Remove an issue from whichever bucket contains it. */
-export function removeIssueFromBuckets(
-  resp: ListIssuesCache,
-  id: string,
-): ListIssuesCache {
-  const loc = findIssueLocation(resp, id);
-  if (!loc) return resp;
-  const bucket = getBucket(resp, loc.status);
-  return setBucket(resp, loc.status, {
-    issues: bucket.issues.filter((i) => i.id !== id),
-    total: Math.max(0, bucket.total - 1),
-  });
-}
-
-/**
- * Merge `patch` into the issue with `id`. If `patch.status` differs from the
- * current bucket, the issue moves to the new bucket and both buckets' totals
- * are adjusted.
- */
-export function patchIssueInBuckets(
-  resp: ListIssuesCache,
-  id: string,
-  patch: Partial<Issue>,
-): ListIssuesCache {
-  const loc = findIssueLocation(resp, id);
-  if (!loc) return resp;
-  const merged: Issue = { ...loc.issue, ...patch };
-  const nextStatus = patch.status ?? loc.status;
-
-  if (nextStatus === loc.status) {
-    const bucket = getBucket(resp, loc.status);
-    return setBucket(resp, loc.status, {
-      ...bucket,
-      issues: bucket.issues.map((i) => (i.id === id ? merged : i)),
-    });
-  }
-
-  const fromBucket = getBucket(resp, loc.status);
-  const toBucket = getBucket(resp, nextStatus);
-  let next = setBucket(resp, loc.status, {
-    issues: fromBucket.issues.filter((i) => i.id !== id),
-    total: Math.max(0, fromBucket.total - 1),
-  });
-  next = setBucket(next, nextStatus, {
-    issues: [...toBucket.issues, merged],
-    total: toBucket.total + 1,
-  });
-  return next;
-}

packages/core/issues/mutations.ts

@@ -1,26 +1,13 @@
 import { useState, useCallback } from "react";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { api } from "../api";
-import {
-  issueKeys,
-  ISSUE_PAGE_SIZE,
-  type MyIssuesFilter,
-} from "./queries";
-import {
-  addIssueToBuckets,
-  findIssueLocation,
-  getBucket,
-  patchIssueInBuckets,
-  removeIssueFromBuckets,
-  setBucket,
-} from "./cache-helpers";
+import { issueKeys, CLOSED_PAGE_SIZE, type MyIssuesFilter } from "./queries";
 import { useWorkspaceId } from "../hooks";
-import { useRecentIssuesStore } from "./stores";
-import type { Issue, IssueReaction, IssueStatus } from "../types";
+import type { Issue, IssueReaction } from "../types";
 import type {
   CreateIssueRequest,
   UpdateIssueRequest,
-  ListIssuesCache,
+  ListIssuesResponse,
 } from "../types";
 import type { TimelineEntry, IssueSubscriber, Reaction } from "../types";
 
@@ -41,18 +28,10 @@ export type ToggleIssueReactionVars = {
 };
 
 // ---------------------------------------------------------------------------
-// Per-status pagination
+// Done issue pagination
 // ---------------------------------------------------------------------------
 
-/**
- * Paginate one status column into the cache. Works for both the workspace
- * issue list and per-scope My Issues lists (pass `myIssues` to target the
- * latter).
- */
-export function useLoadMoreByStatus(
-  status: IssueStatus,
-  myIssues?: { scope: string; filter: MyIssuesFilter },
-) {
+export function useLoadMoreDoneIssues(myIssues?: { scope: string; filter: MyIssuesFilter }) {
   const qc = useQueryClient();
   const wsId = useWorkspaceId();
   const [isLoading, setIsLoading] = useState(false);
@@ -60,38 +39,39 @@ export function useLoadMoreByStatus(
   const queryKey = myIssues
     ? issueKeys.myList(wsId, myIssues.scope, myIssues.filter)
     : issueKeys.list(wsId);
-  const cache = qc.getQueryData<ListIssuesCache>(queryKey);
-  const bucket = cache?.byStatus[status];
-  const loaded = bucket?.issues.length ?? 0;
-  const total = bucket?.total ?? 0;
-  const hasMore = loaded < total;
+  const cache = qc.getQueryData<ListIssuesResponse>(queryKey);
+  const doneLoaded = cache
+    ? cache.issues.filter((i) => i.status === "done").length
+    : 0;
+  const doneTotal = cache?.doneTotal ?? 0;
+  const hasMore = doneLoaded < doneTotal;
 
   const loadMore = useCallback(async () => {
     if (isLoading || !hasMore) return;
     setIsLoading(true);
     try {
       const res = await api.listIssues({
-        status,
-        limit: ISSUE_PAGE_SIZE,
-        offset: loaded,
+        status: "done",
+        limit: CLOSED_PAGE_SIZE,
+        offset: doneLoaded,
         ...myIssues?.filter,
       });
-      qc.setQueryData<ListIssuesCache>(queryKey, (old) => {
+      qc.setQueryData<ListIssuesResponse>(queryKey, (old) => {
         if (!old) return old;
-        const prev = getBucket(old, status);
-        const existingIds = new Set(prev.issues.map((i) => i.id));
-        const appended = res.issues.filter((i) => !existingIds.has(i.id));
-        return setBucket(old, status, {
-          issues: [...prev.issues, ...appended],
-          total: res.total,
-        });
+        const existingIds = new Set(old.issues.map((i) => i.id));
+        const newIssues = res.issues.filter((i) => !existingIds.has(i.id));
+        return {
+          ...old,
+          issues: [...old.issues, ...newIssues],
+          doneTotal: res.total,
+        };
       });
     } finally {
       setIsLoading(false);
     }
-  }, [qc, queryKey, status, loaded, hasMore, isLoading, myIssues?.filter]);
+  }, [qc, queryKey, doneLoaded, hasMore, isLoading, myIssues?.filter]);
 
-  return { loadMore, hasMore, isLoading, total };
+  return { loadMore, hasMore, isLoading, doneTotal };
 }
 
 // ---------------------------------------------------------------------------
@@ -104,12 +84,16 @@ export function useCreateIssue() {
   return useMutation({
     mutationFn: (data: CreateIssueRequest) => api.createIssue(data),
     onSuccess: (newIssue) => {
-      qc.setQueryData<ListIssuesCache>(issueKeys.list(wsId), (old) =>
-        old ? addIssueToBuckets(old, newIssue) : old,
+      qc.setQueryData<ListIssuesResponse>(issueKeys.list(wsId), (old) =>
+        old && !old.issues.some((i) => i.id === newIssue.id)
+          ? {
+              ...old,
+              issues: [...old.issues, newIssue],
+              total: old.total + 1,
+              doneTotal: (old.doneTotal ?? 0) + (newIssue.status === "done" ? 1 : 0),
+            }
+          : old,
       );
-      // Surface the just-created issue in cmd+k's Recent list without
-      // requiring the user to open it first.
-      useRecentIssuesStore.getState().recordVisit(newIssue.id);
       // Invalidate parent's children query so sub-issues list updates immediately
       if (newIssue.parent_issue_id) {
         qc.invalidateQueries({ queryKey: issueKeys.children(wsId, newIssue.parent_issue_id) });
@@ -134,7 +118,7 @@ export function useUpdateIssue() {
       // yield to the event loop, letting @dnd-kit reset its visual state
       // before the optimistic update lands.
       qc.cancelQueries({ queryKey: issueKeys.list(wsId) });
-      const prevList = qc.getQueryData<ListIssuesCache>(issueKeys.list(wsId));
+      const prevList = qc.getQueryData<ListIssuesResponse>(issueKeys.list(wsId));
       const prevDetail = qc.getQueryData<Issue>(issueKeys.detail(wsId, id));
 
       // Resolve parent_issue_id from the freshest source so we can keep the
@@ -142,14 +126,21 @@ export function useUpdateIssue() {
       // sub-issues list).
       const parentId =
         prevDetail?.parent_issue_id ??
-        (prevList ? findIssueLocation(prevList, id)?.issue.parent_issue_id : null) ??
+        prevList?.issues.find((i) => i.id === id)?.parent_issue_id ??
         null;
       const prevChildren = parentId
         ? qc.getQueryData<Issue[]>(issueKeys.children(wsId, parentId))
         : undefined;
 
-      qc.setQueryData<ListIssuesCache>(issueKeys.list(wsId), (old) =>
-        old ? patchIssueInBuckets(old, id, data) : old,
+      qc.setQueryData<ListIssuesResponse>(issueKeys.list(wsId), (old) =>
+        old
+          ? {
+              ...old,
+              issues: old.issues.map((i) =>
+                i.id === id ? { ...i, ...data } : i,
+              ),
+            }
+          : old,
       );
       qc.setQueryData<Issue>(issueKeys.detail(wsId, id), (old) =>
         old ? { ...old, ...data } : old,
@@ -203,11 +194,18 @@ export function useDeleteIssue() {
     mutationFn: (id: string) => api.deleteIssue(id),
     onMutate: async (id) => {
       await qc.cancelQueries({ queryKey: issueKeys.list(wsId) });
-      const prevList = qc.getQueryData<ListIssuesCache>(issueKeys.list(wsId));
-      const deleted = prevList ? findIssueLocation(prevList, id)?.issue : undefined;
-      qc.setQueryData<ListIssuesCache>(issueKeys.list(wsId), (old) =>
-        old ? removeIssueFromBuckets(old, id) : old,
-      );
+      const prevList = qc.getQueryData<ListIssuesResponse>(issueKeys.list(wsId));
+      const deleted = prevList?.issues.find((i) => i.id === id);
+      qc.setQueryData<ListIssuesResponse>(issueKeys.list(wsId), (old) => {
+        if (!old) return old;
+        const d = old.issues.find((i) => i.id === id);
+        return {
+          ...old,
+          issues: old.issues.filter((i) => i.id !== id),
+          total: old.total - 1,
+          doneTotal: (old.doneTotal ?? 0) - (d?.status === "done" ? 1 : 0),
+        };
+      });
       qc.removeQueries({ queryKey: issueKeys.detail(wsId, id) });
       return { prevList, parentIssueId: deleted?.parent_issue_id };
     },
@@ -237,13 +235,17 @@ export function useBatchUpdateIssues() {
     }) => api.batchUpdateIssues(ids, updates),
     onMutate: async ({ ids, updates }) => {
       await qc.cancelQueries({ queryKey: issueKeys.list(wsId) });
-      const prevList = qc.getQueryData<ListIssuesCache>(issueKeys.list(wsId));
-      qc.setQueryData<ListIssuesCache>(issueKeys.list(wsId), (old) => {
-        if (!old) return old;
-        let next = old;
-        for (const id of ids) next = patchIssueInBuckets(next, id, updates);
-        return next;
-      });
+      const prevList = qc.getQueryData<ListIssuesResponse>(issueKeys.list(wsId));
+      qc.setQueryData<ListIssuesResponse>(issueKeys.list(wsId), (old) =>
+        old
+          ? {
+              ...old,
+              issues: old.issues.map((i) =>
+                ids.includes(i.id) ? { ...i, ...updates } : i,
+              ),
+            }
+          : old,
+      );
       return { prevList };
     },
     onError: (_err, _vars, ctx) => {
@@ -262,19 +264,24 @@ export function useBatchDeleteIssues() {
     mutationFn: (ids: string[]) => api.batchDeleteIssues(ids),
     onMutate: async (ids) => {
       await qc.cancelQueries({ queryKey: issueKeys.list(wsId) });
-      const prevList = qc.getQueryData<ListIssuesCache>(issueKeys.list(wsId));
-      const parentIssueIds = new Set<string>();
-      if (prevList) {
-        for (const id of ids) {
-          const loc = findIssueLocation(prevList, id);
-          if (loc?.issue.parent_issue_id) parentIssueIds.add(loc.issue.parent_issue_id);
-        }
-      }
-      qc.setQueryData<ListIssuesCache>(issueKeys.list(wsId), (old) => {
+      const prevList = qc.getQueryData<ListIssuesResponse>(issueKeys.list(wsId));
+      const idSet = new Set(ids);
+      const parentIssueIds = new Set(
+        prevList?.issues
+          .filter((i) => idSet.has(i.id) && i.parent_issue_id)
+          .map((i) => i.parent_issue_id!) ?? [],
+      );
+      qc.setQueryData<ListIssuesResponse>(issueKeys.list(wsId), (old) => {
         if (!old) return old;
-        let next = old;
-        for (const id of ids) next = removeIssueFromBuckets(next, id);
-        return next;
+        const doneDeleted = old.issues.filter(
+          (i) => idSet.has(i.id) && i.status === "done",
+        ).length;
+        return {
+          ...old,
+          issues: old.issues.filter((i) => !idSet.has(i.id)),
+          total: old.total - ids.length,
+          doneTotal: (old.doneTotal ?? 0) - doneDeleted,
+        };
       });
       return { prevList, parentIssueIds };
     },

packages/core/issues/queries.ts

@@ -1,7 +1,6 @@
 import { queryOptions } from "@tanstack/react-query";
 import { api } from "../api";
-import type { IssueStatus, ListIssuesParams, ListIssuesCache } from "../types";
-import { BOARD_STATUSES } from "./config";
+import type { ListIssuesParams } from "../types";
 
 export const issueKeys = {
   all: (wsId: string) => ["issues", wsId] as const,
@@ -24,55 +23,33 @@ export const issueKeys = {
   usage: (issueId: string) => ["issues", "usage", issueId] as const,
 };
 
-export type MyIssuesFilter = Pick<
-  ListIssuesParams,
-  "assignee_id" | "assignee_ids" | "creator_id" | "project_id"
->;
+export type MyIssuesFilter = Pick<ListIssuesParams, "assignee_id" | "assignee_ids" | "creator_id">;
 
-/** Page size per status column. */
-export const ISSUE_PAGE_SIZE = 50;
-
-/** Statuses the issues/my-issues pages paginate. Cancelled is intentionally excluded — it has never been surfaced in the list/board views. */
-export const PAGINATED_STATUSES: readonly IssueStatus[] = BOARD_STATUSES;
-
-/** Flatten a bucketed response to a single Issue[] for consumers that want the whole list. */
-export function flattenIssueBuckets(data: ListIssuesCache) {
-  const out = [];
-  for (const status of PAGINATED_STATUSES) {
-    const bucket = data.byStatus[status];
-    if (bucket) out.push(...bucket.issues);
-  }
-  return out;
-}
-
-async function fetchFirstPages(filter: MyIssuesFilter = {}): Promise<ListIssuesCache> {
-  const responses = await Promise.all(
-    PAGINATED_STATUSES.map((status) =>
-      api.listIssues({ status, limit: ISSUE_PAGE_SIZE, offset: 0, ...filter }),
-    ),
-  );
-  const byStatus: ListIssuesCache["byStatus"] = {};
-  PAGINATED_STATUSES.forEach((status, i) => {
-    const res = responses[i]!;
-    byStatus[status] = { issues: res.issues, total: res.total };
-  });
-  return { byStatus };
-}
+export const CLOSED_PAGE_SIZE = 50;
 
 /**
- * CACHE SHAPE NOTE: The raw cache stores {@link ListIssuesCache} (buckets keyed
- * by status, each with `{ issues, total }`), and `select` flattens it to
- * `Issue[]` for consumers. Mutations and ws-updaters must use
- * `setQueryData<ListIssuesCache>(...)` and preserve the byStatus shape.
+ * CACHE SHAPE NOTE: The raw cache stores ListIssuesResponse ({ issues, total, doneTotal }),
+ * but `select` transforms it to Issue[] for consumers. Mutations and ws-updaters
+ * must use setQueryData<ListIssuesResponse>(...) — NOT setQueryData<Issue[]>.
  *
- * Fetches the first page of each paginated status in parallel. Use
- * {@link useLoadMoreByStatus} to paginate a specific status into the cache.
+ * Fetches all open issues + first page of done issues. Use useLoadMoreDoneIssues()
+ * to paginate additional done items into the cache.
  */
 export function issueListOptions(wsId: string) {
   return queryOptions({
     queryKey: issueKeys.list(wsId),
-    queryFn: () => fetchFirstPages(),
-    select: flattenIssueBuckets,
+    queryFn: async () => {
+      const [openRes, closedRes] = await Promise.all([
+        api.listIssues({ open_only: true }),
+        api.listIssues({ status: "done", limit: CLOSED_PAGE_SIZE, offset: 0 }),
+      ]);
+      return {
+        issues: [...openRes.issues, ...closedRes.issues],
+        total: openRes.total + closedRes.total,
+        doneTotal: closedRes.total,
+      };
+    },
+    select: (data) => data.issues,
   });
 }
 
@@ -87,8 +64,23 @@ export function myIssueListOptions(
 ) {
   return queryOptions({
     queryKey: issueKeys.myList(wsId, scope, filter),
-    queryFn: () => fetchFirstPages(filter),
-    select: flattenIssueBuckets,
+    queryFn: async () => {
+      const [openRes, closedRes] = await Promise.all([
+        api.listIssues({ open_only: true, ...filter }),
+        api.listIssues({
+          status: "done",
+          limit: CLOSED_PAGE_SIZE,
+          offset: 0,
+          ...filter,
+        }),
+      ]);
+      return {
+        issues: [...openRes.issues, ...closedRes.issues],
+        total: openRes.total + closedRes.total,
+        doneTotal: closedRes.total,
+      };
+    },
+    select: (data) => data.issues,
   });
 }
 

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

@@ -1,46 +0,0 @@
-import { create } from "zustand";
-import { createJSONStorage, persist } from "zustand/middleware";
-import { createWorkspaceAwareStorage, registerForWorkspaceRehydration } from "../../platform/workspace-storage";
-import { defaultStorage } from "../../platform/storage";
-
-/**
- * Tracks which comments are collapsed, keyed by issue ID.
- * Only collapsed comment IDs are stored — expanded is the default state.
- */
-interface CommentCollapseStore {
-  collapsedByIssue: Record<string, string[]>;
-  isCollapsed: (issueId: string, commentId: string) => boolean;
-  toggle: (issueId: string, commentId: string) => void;
-}
-
-export const useCommentCollapseStore = create<CommentCollapseStore>()(
-  persist(
-    (set, get) => ({
-      collapsedByIssue: {},
-      isCollapsed: (issueId, commentId) => {
-        const ids = get().collapsedByIssue[issueId];
-        return ids ? ids.includes(commentId) : false;
-      },
-      toggle: (issueId, commentId) =>
-        set((s) => {
-          const current = s.collapsedByIssue[issueId] ?? [];
-          const isCurrentlyCollapsed = current.includes(commentId);
-          if (isCurrentlyCollapsed) {
-            const next = current.filter((id) => id !== commentId);
-            if (next.length === 0) {
-              const { [issueId]: _, ...rest } = s.collapsedByIssue;
-              return { collapsedByIssue: rest };
-            }
-            return { collapsedByIssue: { ...s.collapsedByIssue, [issueId]: next } };
-          }
-          return { collapsedByIssue: { ...s.collapsedByIssue, [issueId]: [...current, commentId] } };
-        }),
-    }),
-    {
-      name: "multica_comment_collapse",
-      storage: createJSONStorage(() => createWorkspaceAwareStorage(defaultStorage)),
-    },
-  ),
-);
-
-registerForWorkspaceRehydration(() => useCommentCollapseStore.persist.rehydrate());

packages/core/issues/stores/index.ts

@@ -7,7 +7,6 @@ export {
   useViewStoreApi,
 } from "./view-store-context";
 export { useIssuesScopeStore, type IssuesScope } from "./issues-scope-store";
-export { useCommentCollapseStore } from "./comment-collapse-store";
 export {
   myIssuesViewStore,
   type MyIssuesViewState,