fix(web): remember last selected workspace after re-login

Stop clearing multica_workspace_id from localStorage on logout so it
persists as a preference hint. On fresh login, pass the stored ID to
hydrateWorkspace so the user returns to their last workspace instead
of always landing on the first one.

.dockerignore

@@ -1,38 +0,0 @@
-# Dependencies
-node_modules
-.pnpm-store
-
-# Build outputs
-.next
-dist
-server/bin
-server/tmp
-
-# Git
-.git
-.gitignore
-
-# Environment
-.env
-.env.*
-!.env.example
-
-# IDE
-.idea
-.vscode
-*.swp
-*.swo
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Test
-e2e/test-results
-coverage
-
-# Docs
-docs/
-
-# Desktop app (not needed for web self-hosting)
-apps/desktop

.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
@@ -36,25 +21,11 @@ MULTICA_CODEX_MODEL=
 MULTICA_CODEX_WORKDIR=
 MULTICA_CODEX_TIMEOUT=20m
 
-# Self-host image channel
-# Default stable release channel. Pin to an exact release like v0.2.4 if you
-# want to stay on a specific version. If the selected tag has not been
-# published to GHCR yet, use make selfhost-build / the build override instead.
-MULTICA_IMAGE_TAG=latest
-MULTICA_BACKEND_IMAGE=ghcr.io/multica-ai/multica-backend
-MULTICA_WEB_IMAGE=ghcr.io/multica-ai/multica-web
-
 # 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 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
 
 # Google OAuth
-# The web login page reads GOOGLE_CLIENT_ID from /api/config at runtime, so
-# changing it only requires restarting the backend / compose stack. No web
-# rebuild is needed.
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
 GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
@@ -66,55 +37,14 @@ 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)
-LOCAL_UPLOAD_DIR=./data/uploads
-LOCAL_UPLOAD_BASE_URL=http://localhost:8080
-
-# Security
-# Comma-separated list of allowed origins for CORS and WebSocket connections.
-# Defaults to localhost dev origins when unset.
-# Example: ALLOWED_ORIGINS=https://app.multica.ai,https://staging.multica.ai
-ALLOWED_ORIGINS=
-
 # Frontend
 FRONTEND_PORT=3000
 FRONTEND_ORIGIN=http://localhost:3000
-# Leave empty — auto-derived from page origin in browser, set by Makefile for local dev.
-# Only set explicitly if frontend and backend are on different domains.
-NEXT_PUBLIC_API_URL=
-NEXT_PUBLIC_WS_URL=
+NEXT_PUBLIC_API_URL=http://localhost:8080
+NEXT_PUBLIC_WS_URL=ws://localhost:8080/ws
 
 # 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
-# The web UI reads ALLOW_SIGNUP from /api/config at runtime, so toggling this
-# only requires restarting the backend / compose stack — not rebuilding web.
-# It is not hot-reloaded.
-
-# 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=

.gitattributes

@@ -1,6 +0,0 @@
-# Ensure shell scripts always use LF line endings (needed for Docker on Windows)
-*.sh text eol=lf
-docker/entrypoint.sh text eol=lf
-
-# Default behavior
-* text=auto

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,50 +0,0 @@
-name: "Bug Report"
-description: Report a bug — something that's broken, crashes, or behaves incorrectly.
-title: "[Bug]: "
-labels: ["bug"]
-body:
-  - type: dropdown
-    id: deployment
-    attributes:
-      label: Deployment type
-      description: Are you using the hosted version or a self-hosted instance?
-      options:
-        - multica.ai (hosted)
-        - Self-hosted
-    validations:
-      required: true
-
-  - type: textarea
-    id: description
-    attributes:
-      label: What happened?
-      description: Describe the bug and what you expected instead. Screenshots, error messages, or screen recordings are welcome.
-      placeholder: |
-        When I do X, Y happens. I expected Z instead.
-    validations:
-      required: true
-
-  - type: textarea
-    id: reproduction
-    attributes:
-      label: Steps to reproduce
-      description: How can we trigger this bug?
-      placeholder: |
-        1. Go to '...'
-        2. Click on '...'
-        3. See error
-    validations:
-      required: true
-
-  - type: textarea
-    id: screenshots
-    attributes:
-      label: Screenshots (optional)
-      description: If applicable, add screenshots or screen recordings to help explain the problem.
-
-  - type: textarea
-    id: context
-    attributes:
-      label: Additional context (optional)
-      description: Environment info, logs, or anything else that might help.
-      render: shell

.github/ISSUE_TEMPLATE/config.yml

@@ -1 +0,0 @@
-blank_issues_enabled: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,37 +0,0 @@
-name: "Feature Request"
-description: Suggest a new feature or improvement.
-title: "[Feature]: "
-labels: ["enhancement"]
-body:
-  - type: dropdown
-    id: deployment
-    attributes:
-      label: Deployment type
-      description: Are you using the hosted version or a self-hosted instance?
-      options:
-        - multica.ai (hosted)
-        - Self-hosted
-    validations:
-      required: true
-
-  - type: textarea
-    id: description
-    attributes:
-      label: What do you want and why?
-      description: Describe the problem you're trying to solve or the improvement you'd like to see.
-      placeholder: |
-        I'm trying to do X but there's no way to...
-    validations:
-      required: true
-
-  - type: textarea
-    id: solution
-    attributes:
-      label: Proposed solution (optional)
-      description: If you have an idea for how this should work, describe it here.
-
-  - type: textarea
-    id: screenshots
-    attributes:
-      label: Screenshots / mockups (optional)
-      description: If applicable, add screenshots, mockups, or sketches to illustrate your idea.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,58 +0,0 @@
-## What does this PR do?
-
-<!-- Describe the change clearly. What problem does it solve? Why is this approach the right one? -->
-
-
-
-## Related Issue
-
-<!-- Link the issue this PR addresses. If no issue exists, consider creating one first. -->
-
-Closes #
-
-## Type of Change
-
-- [ ] Bug fix (non-breaking change that fixes an issue)
-- [ ] New feature (non-breaking change that adds functionality)
-- [ ] Refactor / code improvement (no behavior change)
-- [ ] Documentation update
-- [ ] Tests (adding or improving test coverage)
-- [ ] CI / infrastructure
-
-## Changes Made
-
-<!-- List the specific changes. Include file paths for code changes. -->
-
--
-
-## How to Test
-
-<!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. -->
-
-1.
-2.
-3.
-
-## Checklist
-
-- [ ] I have included a thinking path that traces from project context to this change
-- [ ] I have run tests locally and they pass
-- [ ] I have added or updated tests where applicable
-- [ ] If this change affects the UI, I have included before/after screenshots
-- [ ] I have updated relevant documentation to reflect my changes
-- [ ] I have considered and documented any risks above
-- [ ] I will address all reviewer comments before requesting merge
-
-## AI Disclosure
-
-<!-- Most PRs involve AI coding tools — that's totally fine! We're curious about your process. -->
-
-**AI tool used:** <!-- e.g. Claude Code, Cursor, GitHub Copilot, Multica Agent, N/A -->
-
-**Prompt / approach:**
-<!-- How did you use AI to produce this code? Share your prompt, conversation link, or describe your approach. This helps the team learn from each other's AI workflows. -->
-
-
-## Screenshots (optional)
-
-<!-- If applicable, add screenshots showing the change in action. -->

.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,48 +3,20 @@ 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
-  packages: write
 
 jobs:
-  verify:
+  release:
     runs-on: ubuntu-latest
-    outputs:
-      tag_name: ${{ steps.release_meta.outputs.tag_name }}
-      is_stable: ${{ steps.release_meta.outputs.is_stable }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Validate tag name
-        id: release_meta
-        shell: bash
-        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
-          echo "tag_name=$tag" >> "$GITHUB_OUTPUT"
-          if [[ "$tag" == *-* ]]; then
-            echo "is_stable=false" >> "$GITHUB_OUTPUT"
-          else
-            echo "is_stable=true" >> "$GITHUB_OUTPUT"
-          fi
-
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
@@ -54,21 +26,6 @@ jobs:
       - name: Run tests
         run: cd server && go test ./...
 
-  release:
-    needs: verify
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Go
-        uses: actions/setup-go@v5
-        with:
-          go-version-file: server/go.mod
-          cache-dependency-path: server/go.sum
-
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v6
         with:
@@ -77,298 +34,3 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
-
-  # Multi-arch images are built natively per platform on dedicated runners
-  # (amd64 on ubuntu-latest, arm64 on ubuntu-24.04-arm) and merged into a
-  # manifest list. This avoids QEMU emulation, which was making the Next.js
-  # arm64 build run for 30+ minutes per release.
-  docker-backend-build:
-    needs: verify
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - platform: linux/amd64
-            runs-on: ubuntu-latest
-          - platform: linux/arm64
-            runs-on: ubuntu-24.04-arm
-    runs-on: ${{ matrix.runs-on }}
-    steps:
-      - name: Prepare
-        run: |
-          platform=${{ matrix.platform }}
-          echo "PLATFORM_PAIR=${platform//\//-}" >> "$GITHUB_ENV"
-
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Compute backend image labels
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ghcr.io/${{ github.repository_owner }}/multica-backend
-          labels: |
-            org.opencontainers.image.title=Multica Backend
-            org.opencontainers.image.description=Multica self-hosted backend
-
-      - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Login to GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build and push by digest
-        id: build
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: Dockerfile
-          pull: true
-          platforms: ${{ matrix.platform }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha,scope=release-backend-${{ env.PLATFORM_PAIR }}
-          cache-to: type=gha,mode=max,scope=release-backend-${{ env.PLATFORM_PAIR }}
-          build-args: |
-            VERSION=${{ needs.verify.outputs.tag_name }}
-            COMMIT=${{ github.sha }}
-          outputs: type=image,name=ghcr.io/${{ github.repository_owner }}/multica-backend,push-by-digest=true,name-canonical=true,push=true
-
-      - name: Export digest
-        run: |
-          mkdir -p /tmp/digests
-          digest="${{ steps.build.outputs.digest }}"
-          touch "/tmp/digests/${digest#sha256:}"
-
-      - name: Upload digest
-        uses: actions/upload-artifact@v4
-        with:
-          name: digests-backend-${{ env.PLATFORM_PAIR }}
-          path: /tmp/digests/*
-          if-no-files-found: error
-          retention-days: 1
-
-  docker-backend-merge:
-    needs: [verify, docker-backend-build]
-    runs-on: ubuntu-latest
-    concurrency:
-      group: release-docker-backend-${{ github.ref }}
-      cancel-in-progress: true
-    steps:
-      - name: Download digests
-        uses: actions/download-artifact@v4
-        with:
-          path: /tmp/digests
-          pattern: digests-backend-*
-          merge-multiple: true
-
-      - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Compute backend image tags
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ghcr.io/${{ github.repository_owner }}/multica-backend
-          flavor: |
-            latest=false
-          tags: |
-            type=raw,value=latest,enable=${{ needs.verify.outputs.is_stable == 'true' }}
-            type=raw,value=${{ needs.verify.outputs.tag_name }}
-            type=sha,prefix=sha-
-
-      - name: Login to GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Create manifest list and push
-        working-directory: /tmp/digests
-        run: |
-          docker buildx imagetools create \
-            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
-            $(printf 'ghcr.io/${{ github.repository_owner }}/multica-backend@sha256:%s ' *)
-
-      - name: Inspect image
-        run: |
-          docker buildx imagetools inspect \
-            ghcr.io/${{ github.repository_owner }}/multica-backend:${{ steps.meta.outputs.version }}
-
-  docker-web-build:
-    needs: verify
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - platform: linux/amd64
-            runs-on: ubuntu-latest
-          - platform: linux/arm64
-            runs-on: ubuntu-24.04-arm
-    runs-on: ${{ matrix.runs-on }}
-    steps:
-      - name: Prepare
-        run: |
-          platform=${{ matrix.platform }}
-          echo "PLATFORM_PAIR=${platform//\//-}" >> "$GITHUB_ENV"
-
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Compute web image labels
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ghcr.io/${{ github.repository_owner }}/multica-web
-          labels: |
-            org.opencontainers.image.title=Multica Web
-            org.opencontainers.image.description=Multica self-hosted web frontend
-
-      - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Login to GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build and push by digest
-        id: build
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: Dockerfile.web
-          pull: true
-          platforms: ${{ matrix.platform }}
-          labels: ${{ steps.meta.outputs.labels }}
-          cache-from: type=gha,scope=release-web-${{ env.PLATFORM_PAIR }}
-          cache-to: type=gha,mode=max,scope=release-web-${{ env.PLATFORM_PAIR }}
-          build-args: |
-            REMOTE_API_URL=http://backend:8080
-            NEXT_PUBLIC_APP_VERSION=${{ needs.verify.outputs.tag_name }}
-          outputs: type=image,name=ghcr.io/${{ github.repository_owner }}/multica-web,push-by-digest=true,name-canonical=true,push=true
-
-      - name: Export digest
-        run: |
-          mkdir -p /tmp/digests
-          digest="${{ steps.build.outputs.digest }}"
-          touch "/tmp/digests/${digest#sha256:}"
-
-      - name: Upload digest
-        uses: actions/upload-artifact@v4
-        with:
-          name: digests-web-${{ env.PLATFORM_PAIR }}
-          path: /tmp/digests/*
-          if-no-files-found: error
-          retention-days: 1
-
-  docker-web-merge:
-    needs: [verify, docker-web-build]
-    runs-on: ubuntu-latest
-    concurrency:
-      group: release-docker-web-${{ github.ref }}
-      cancel-in-progress: true
-    steps:
-      - name: Download digests
-        uses: actions/download-artifact@v4
-        with:
-          path: /tmp/digests
-          pattern: digests-web-*
-          merge-multiple: true
-
-      - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Compute web image tags
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ghcr.io/${{ github.repository_owner }}/multica-web
-          flavor: |
-            latest=false
-          tags: |
-            type=raw,value=latest,enable=${{ needs.verify.outputs.is_stable == 'true' }}
-            type=raw,value=${{ needs.verify.outputs.tag_name }}
-            type=sha,prefix=sha-
-
-      - name: Login to GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ghcr.io
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Create manifest list and push
-        working-directory: /tmp/digests
-        run: |
-          docker buildx imagetools create \
-            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
-            $(printf 'ghcr.io/${{ github.repository_owner }}/multica-web@sha256:%s ' *)
-
-      - name: Inspect image
-        run: |
-          docker buildx imagetools inspect \
-            ghcr.io/${{ github.repository_owner }}/multica-web:${{ steps.meta.outputs.version }}
-
-  # Build the Desktop installers for Linux and Windows and upload them to
-  # the GitHub Release that the `release` job above just published. macOS
-  # Desktop continues to ship via the manual `release-desktop` skill so it
-  # 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

.gitignore

@@ -12,17 +12,10 @@ build
 bin
 dist-electron
 *.tsbuildinfo
-# ...except electron-builder's source resources dir, which holds tracked
-# config files (entitlements, icons) — not build output.
-!apps/desktop/build/
-!apps/desktop/build/**
 
 # env
 .env*
 !.env.example
-# Desktop production config is public (backend URL, etc.) — track it so
-# `pnpm package` produces a release-ready build without extra setup.
-!apps/desktop/.env.production
 
 # test coverage
 coverage
@@ -48,13 +41,7 @@ apps/web/test-results/
 # feature tracking
 _features/
 
-# runtime
-*.pid
-
 # platform specific
 *.dmg
 *.app
 server/server
-data/
-.kilo
-.idea

.goreleaser.yml

@@ -11,39 +11,20 @@ builds:
       - -s -w
       - -X main.version={{.Version}}
       - -X main.commit={{.ShortCommit}}
-      - -X main.date={{.Date}}
     env:
       - CGO_ENABLED=0
     goos:
       - darwin
       - linux
-      - windows
     goarch:
       - amd64
       - 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:
-      - goos: windows
-        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 +39,6 @@ changelog:
 
 brews:
   - name: multica
-    ids:
-      - versioned
     repository:
       owner: multica-ai
       name: homebrew-tap

.vercelignore

@@ -1,85 +0,0 @@
-# Deploy the frontend apps from the monorepo root.
-# Keep apps/web, apps/docs, shared packages, and root workspace metadata.
-# Exclude unrelated workspaces and local artifacts that can make
-# `vercel deploy` upload far more than the app needs.
-
-.agent_context
-.claude
-.context
-.env*
-.envrc
-.tool-versions
-_features
-.kilo
-.idea
-.DS_Store
-.husky
-.vscode
-
-/.dockerignore
-/.goreleaser.yml
-/AGENTS.md
-/CLAUDE.md
-/CLI_AND_DAEMON.md
-/CLI_INSTALL.md
-/CONTRIBUTING.md
-/Dockerfile
-/Dockerfile.web
-/HANDOFF_ARCHITECTURE_AUDIT.md
-/Makefile
-/README.md
-/README.zh-CN.md
-/SELF_HOSTING.md
-/SELF_HOSTING_ADVANCED.md
-/SELF_HOSTING_AI.md
-/docker-compose*.yml
-/playwright.config.ts
-/skills-lock.json
-
-/.github/
-/docker/
-/docs/
-/e2e/
-/server/
-/apps/desktop/
-/scripts/
-
-*.log
-*.pid
-*.tsbuildinfo
-
-.cache
-.next
-.pnpm-store
-.turbo
-.vercel
-coverage
-test-results
-playwright-report
-data
-
-node_modules
-bin
-dist
-out
-build
-dist-electron
-
-# Deployment-only trims: tests and lint configs are not used by `next build`.
-**/__tests__/**
-**/test/**
-**/*.test.*
-**/*.spec.*
-/packages/eslint-config/
-/apps/web/components.json
-/apps/web/eslint.config.mjs
-/apps/web/vitest.config.ts
-
-# Root repo metadata not needed in the deployment source.
-/.env.example
-/.gitattributes
-/.gitignore
-/LICENSE
-
-*.app
-*.dmg

AGENTS.md

@@ -2,46 +2,273 @@
 
 This file provides guidance to AI agents when working with code in this repository.
 
-> **Single source of truth:** This file is a concise pointer document.
-> All authoritative architecture, coding rules, commands, and conventions
-> live in **CLAUDE.md** at the project root. Read that file first.
+## Project Context
 
-## Quick Reference
+Multica is an AI-native task management platform — like Linear, but with AI agents as first-class citizens.
 
-### Architecture
+- Agents can be assigned issues, create issues, comment, and change status
+- Supports local (daemon) and cloud agent runtimes
+- Built for 2-10 person AI-native teams
 
-Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.
+## Architecture
 
-- `server/` — Go backend (Chi router, sqlc, gorilla/websocket)
-- `apps/web/` — Next.js frontend (App Router)
-- `apps/desktop/` — Electron desktop app
-- `packages/core/` — Headless business logic (Zustand stores, React Query hooks, API client)
-- `packages/ui/` — Atomic UI components (shadcn/Base UI, zero business logic)
-- `packages/views/` — Shared business pages/components
-- `packages/tsconfig/` — Shared TypeScript config
+**Go backend + standalone Next.js frontend.**
 
-### State Management (critical)
+- `server/` — Go backend (Chi router, sqlc for DB, gorilla/websocket for real-time)
+- `apps/web/` — Next.js 16 frontend (App Router) — self-contained, no shared package dependencies
+- `e2e/` — Playwright end-to-end tests
+- `scripts/` and root `Makefile` — local setup and verification
 
-- **React Query** owns all server state (issues, members, agents, inbox, workspace list)
-- **Zustand** owns all client state (current workspace selection, view filters, drafts, modals)
-- All Zustand stores live in `packages/core/` — never in `packages/views/` or app directories
-- WS events invalidate React Query — never write directly to stores
+### Web App Structure (`apps/web/`)
 
-### Package Boundaries (hard rules)
+The frontend uses a **feature-based architecture** with four layers:
 
-- `packages/core/` — zero react-dom, zero localStorage, zero process.env
-- `packages/ui/` — zero `@multica/core` imports
-- `packages/views/` — zero `next/*`, zero `react-router-dom`, use `NavigationAdapter` for routing
-- `apps/web/platform/` — only place for Next.js APIs
-
-### Commands
-
-```bash
-make dev              # Auto-setup + start everything
-pnpm typecheck        # TypeScript check
-pnpm test             # TS unit tests (Vitest)
-make test             # Go tests
-make check            # Full verification pipeline
+```
+apps/web/
+├── app/          # Routing layer (thin shells — import from features/)
+├── features/     # Business logic, organized by domain
+├── shared/       # Cross-feature utilities (api client, types, logger)
+├── test/         # Shared test utilities and setup
+├── public/       # Static assets
 ```
 
-See CLAUDE.md for the complete command reference.
+**`app/`** — Next.js App Router pages. Route files should be thin: import and re-export from `features/`. Layout components and route-specific glue (redirects, auth guards) live here. Shared layout components (e.g. `app-sidebar`) stay in `app/(dashboard)/_components/`.
+
+**`features/`** — Domain modules, each with its own components, hooks, stores, and config:
+
+| Feature | Purpose | Exports |
+|---|---|---|
+| `features/auth/` | Authentication state | `useAuthStore`, `AuthInitializer` |
+| `features/workspace/` | Workspace, members, agents | `useWorkspaceStore`, `useActorName` |
+| `features/issues/` | Issue state, components, config | `useIssueStore`, icons, pickers, status/priority config |
+| `features/inbox/` | Inbox notification state | `useInboxStore` |
+| `features/realtime/` | WebSocket connection + sync | `WSProvider`, `useWSEvent`, `useRealtimeSync` |
+| `features/modals/` | Modal registry and state | Modal store and components |
+| `features/skills/` | Skill management | Skill components |
+
+**`shared/`** — Code used across multiple features:
+- `shared/api/` — `ApiClient` (REST) and `WSClient` (WebSocket) for backend communication, plus the `api` singleton.
+- `shared/types/` — Domain types (Issue, Agent, Workspace, etc.) and WebSocket event types.
+- `shared/logger.ts` — Logger utility.
+
+### State Management
+
+- **Zustand** for global client state — one store per feature domain (`features/auth/store.ts`, `features/workspace/store.ts`, `features/issues/store.ts`, `features/inbox/store.ts`).
+- **React Context** only for connection lifecycle (`WSProvider` in `features/realtime/`).
+- **Local `useState`** for component-scoped UI state (forms, modals, filters).
+- Do not use React Context for data that can be a zustand store.
+
+**Store conventions:**
+- One store per feature domain. Import via `useAuthStore(selector)` or `useWorkspaceStore(selector)`.
+- Stores must not call `useRouter` or any React hooks — keep navigation in components.
+- Cross-store reads use `useOtherStore.getState()` inside actions (not hooks).
+- Dependency direction: `workspace` → `auth`, `realtime` → `auth`, `issues` → `workspace`. Never reverse.
+
+### Import Aliases
+
+Use `@/` alias (maps to `apps/web/`):
+```typescript
+import { api } from "@/shared/api";
+import type { Issue } from "@/shared/types";
+import { useAuthStore } from "@/features/auth";
+import { useWorkspaceStore } from "@/features/workspace";
+import { useIssueStore } from "@/features/issues";
+import { useInboxStore } from "@/features/inbox";
+import { useWSEvent } from "@/features/realtime";
+import { StatusIcon } from "@/features/issues/components";
+```
+
+Within a feature, use relative imports. Between features or to shared, use `@/`.
+
+### Data Flow
+
+```
+Browser → ApiClient (shared/api) → REST API (Chi handlers) → sqlc queries → PostgreSQL
+Browser ← WSClient (shared/api) ← WebSocket ← Hub.Broadcast() ← Handlers/TaskService
+```
+
+### Backend Structure (`server/`)
+
+- **Entry points** (`cmd/`): `server` (HTTP API), `multica` (CLI — daemon, agent management, config), `migrate`
+- **Handlers** (`internal/handler/`): One file per domain (issue, comment, agent, auth, daemon, etc.). Each handler holds `Queries`, `DB`, `Hub`, and `TaskService`.
+- **Real-time** (`internal/realtime/`): Hub manages WebSocket clients. Server broadcasts events; inbound WS message routing is still TODO.
+- **Auth** (`internal/auth/` + `internal/middleware/`): JWT (HS256). Middleware sets `X-User-ID` and `X-User-Email` headers. Login creates user on-the-fly if not found.
+- **Task lifecycle** (`internal/service/task.go`): Orchestrates agent work — enqueue → claim → start → complete/fail. Syncs issue status automatically and broadcasts WS events at each transition.
+- **Agent SDK** (`pkg/agent/`): Unified `Backend` interface for executing prompts via Claude Code or Codex. Each backend spawns its CLI and streams results via `Session.Messages` + `Session.Result` channels.
+- **Daemon** (`internal/daemon/`): Local agent runtime — auto-detects available CLIs (claude, codex), registers runtimes, polls for tasks, routes by provider.
+- **CLI** (`internal/cli/`): Shared helpers for the `multica` CLI — API client, config management, output formatting.
+- **Events** (`internal/events/`): Internal event bus for decoupled communication between handlers and services.
+- **Logging** (`internal/logger/`): Structured logging via slog. `LOG_LEVEL` env var controls level (debug, info, warn, error).
+- **Database**: PostgreSQL with pgvector extension (`pgvector/pgvector:pg17`). sqlc generates Go code from SQL in `pkg/db/queries/` → `pkg/db/generated/`. Migrations in `migrations/`.
+- **Routes** (`cmd/server/router.go`): Public routes (auth, health, ws) + protected routes (require JWT) + daemon routes (unauthenticated, separate auth model).
+
+### Multi-tenancy
+
+All queries filter by `workspace_id`. Membership checks gate access. `X-Workspace-ID` header routes requests to the correct workspace.
+
+### Agent Assignees
+
+Assignees are polymorphic — can be a member or an agent. `assignee_type` + `assignee_id` on issues. Agents render with distinct styling (purple background, robot icon).
+
+## Commands
+
+```bash
+# One-click setup & run
+make setup            # First-time: ensure shared DB, create app DB, migrate
+make start            # Start backend + frontend together
+make stop             # Stop app processes for the current checkout
+make db-down          # Stop the shared PostgreSQL container
+
+# Frontend
+pnpm install
+pnpm dev:web          # Next.js dev server (port 3000)
+pnpm build            # Build frontend
+pnpm typecheck        # TypeScript check
+pnpm lint             # ESLint via Next.js
+pnpm test             # TS tests (Vitest)
+
+# Backend (Go)
+make dev              # Run Go server (port 8080)
+make daemon           # Run local daemon
+make build            # Build server + CLI binaries to server/bin/
+make cli ARGS="..."   # Run multica CLI (e.g. make cli ARGS="config")
+make test             # Go tests
+make sqlc             # Regenerate sqlc code after editing SQL in server/pkg/db/queries/
+make migrate-up       # Run database migrations
+make migrate-down     # Rollback migrations
+
+# Run a single Go test
+cd server && go test ./internal/handler/ -run TestName
+
+# Run a single TS test
+pnpm --filter @multica/web exec vitest run src/path/to/file.test.ts
+
+# Run a single E2E test (requires backend + frontend running)
+pnpm exec playwright test e2e/tests/specific-test.spec.ts
+
+# Infrastructure
+make db-up            # Start shared PostgreSQL (pgvector/pg17 image)
+make db-down          # Stop shared PostgreSQL
+```
+
+### CI Requirements
+
+CI runs on Node 22 and Go 1.24 with a `pgvector/pgvector:pg17` PostgreSQL service. See `.github/workflows/ci.yml`.
+
+### Worktree Support
+
+All checkouts share one PostgreSQL container. Isolation is at the database level — each worktree gets its own DB name and unique ports via `.env.worktree`. Main checkouts use `.env`.
+
+```bash
+make worktree-env       # Generate .env.worktree with unique DB/ports
+make setup-worktree     # Setup using .env.worktree
+make start-worktree     # Start using .env.worktree
+```
+
+## Coding Rules
+
+- TypeScript strict mode is enabled; keep types explicit.
+- TypeScript in `apps/web` uses 2-space indentation, double quotes, and semicolons.
+- Prefer PascalCase for React components, camelCase for hooks and helpers, and colocated test files such as `page.test.tsx`.
+- Go code follows standard Go conventions (gofmt, go vet). Use domain-oriented filenames like `issue.go` or `cmd_issue.go`.
+- Do not hand-edit generated code in `server/pkg/db/generated/`.
+- Keep comments in code **English only**.
+- Prefer existing patterns/components over introducing parallel abstractions.
+- Unless the user explicitly asks for backwards compatibility, do **not** add compatibility layers, fallback paths, dual-write logic, legacy adapters, or temporary shims.
+- 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.
+- Treat compatibility code as a maintenance cost, not a default safety mechanism. Avoid "just in case" branches that make the codebase harder to reason about.
+- Avoid broad refactors unless required by the task.
+
+## UI/UX Rules
+
+- Prefer shadcn components over custom implementations. Install missing components via `npx shadcn add`.
+- **Feature-specific components** → `features/<domain>/components/` — issue icons, pickers, and other domain-bound UI live inside their feature module.
+- Use shadcn design tokens for styling (e.g. `bg-primary`, `text-muted-foreground`, `text-destructive`). Avoid hardcoded color values (e.g. `text-red-500`, `bg-gray-100`).
+- Do not introduce extra state (useState, context, reducers) unless explicitly required by the design. Prefer zustand stores for shared state over React Context.
+- Pay close attention to **overflow** (truncate long text, scrollable containers), **alignment**, and **spacing** consistency.
+- When unsure about interaction or state design, ask — the user will provide direction.
+
+## Testing Rules
+
+- **TypeScript**: Vitest with Testing Library. Shared test setup lives in `apps/web/test/`. Mock external/third-party dependencies only.
+- **Go**: Standard `go test`. Tests should create their own fixture data in a test database.
+- End-to-end tests live in `e2e/*.spec.ts`; `make check` will start missing services automatically, while direct Playwright runs expect the app to already be running.
+- Add or update tests whenever you change handlers, CLI commands, daemon behavior, or SQL-backed flows.
+
+## Commit & Pull Request Rules
+
+- Use atomic commits grouped by logical intent.
+- Conventional format with scopes:
+  - `feat(web): ...`, `feat(cli): ...`
+  - `fix(web): ...`, `fix(cli): ...`
+  - `refactor(daemon): ...`
+  - `test(cli): ...`
+  - `docs: ...`
+  - `chore(scope): ...`
+- Keep PRs focused and include a short description, linked issue or PR number when relevant, screenshots for UI work, and notes for migrations, env changes, or CLI surface changes.
+- Before opening a PR, run `make check` or the relevant frontend/backend subset.
+
+## Minimum Pre-Push Checks
+
+```bash
+make check    # Runs all checks: typecheck, unit tests, Go tests, E2E
+```
+
+Run verification only when the user explicitly asks for it.
+
+For targeted checks when requested:
+```bash
+pnpm typecheck        # TypeScript type errors only
+pnpm test             # TS unit tests only (Vitest)
+make test             # Go tests only
+pnpm exec playwright test   # E2E only (requires backend + frontend running)
+```
+
+## AI Agent Verification Loop
+
+After writing or modifying code, always run the full verification pipeline:
+
+```bash
+make check
+```
+
+This runs all checks in sequence:
+1. TypeScript typecheck (`pnpm typecheck`)
+2. TypeScript unit tests (`pnpm test`)
+3. Go tests (`go test ./...`)
+4. E2E tests (auto-starts backend + frontend if needed, runs Playwright)
+
+**Workflow:**
+- Write code to satisfy the requirement
+- Run `make check`
+- If any step fails, read the error output, fix the code, and re-run `make check`
+- Repeat until all checks pass
+- Only then consider the task complete
+
+**Quick iteration:** If you know only TypeScript or Go is affected, run individual checks first for faster feedback, then finish with a full `make check` before marking work complete.
+
+## E2E Test Patterns
+
+E2E tests should be self-contained. Use the `TestApiClient` fixture for data setup/teardown:
+
+```typescript
+import { loginAsDefault, createTestApi } from "./helpers";
+import type { TestApiClient } from "./fixtures";
+
+let api: TestApiClient;
+
+test.beforeEach(async ({ page }) => {
+  api = await createTestApi();       // logged-in API client
+  await loginAsDefault(page);        // browser session
+});
+
+test.afterEach(async () => {
+  await api.cleanup();               // delete any data created during the test
+});
+
+test("example", async ({ page }) => {
+  const issue = await api.createIssue("Test Issue");  // create via API
+  await page.goto(`/issues/${issue.id}`);             // test via UI
+  // api.cleanup() in afterEach removes the issue
+});
+```

CLAUDE.md

@@ -12,71 +12,119 @@ Multica is an AI-native task management platform — like Linear, but with AI ag
 
 ## Architecture
 
-**Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.**
+**Go backend + standalone Next.js frontend.**
 
 - `server/` — Go backend (Chi router, sqlc for DB, gorilla/websocket for real-time)
-- `apps/web/` — Next.js frontend (App Router)
-- `apps/desktop/` — Electron desktop app (electron-vite)
-- `packages/core/` — Headless business logic (zero react-dom, all-platform reuse)
-- `packages/ui/` — Atomic UI components (zero business logic)
-- `packages/views/` — Shared business pages/components (zero next/* imports, zero react-router imports)
-- `packages/tsconfig/` — Shared TypeScript configuration
+- `apps/web/` — Next.js 16 frontend (App Router) — self-contained, no shared package dependencies
 
-### Key Architectural Decisions
+### Web App Structure (`apps/web/`)
 
-**Internal Packages pattern** — all shared packages export raw `.ts`/`.tsx` files (no pre-compilation). The consuming app's bundler compiles them directly. This gives zero-config HMR and instant go-to-definition.
+The frontend uses a **feature-based architecture** with four layers:
 
-**Dependency direction:** `views/ → core/ + ui/`. Core and UI are independent of each other. No package imports from `next/*`, `react-router-dom`, or app-specific code.
+```
+apps/web/
+├── app/          # Routing layer (thin shells — import from features/)
+├── features/     # Business logic, organized by domain
+├── shared/       # Cross-feature utilities (api client, types, logger)
+```
 
-**Platform bridge:** `packages/core/platform/` provides `CoreProvider` — initializes API client, auth/workspace stores, WS connection, and QueryClient. Each app wraps its root with `<CoreProvider>` and provides its own `NavigationAdapter` for routing.
+**`app/`** — Next.js App Router pages. Route files should be thin: import and re-export from `features/`. Layout components and route-specific glue (redirects, auth guards) live here. Shared layout components (e.g. `app-sidebar`) stay in `app/(dashboard)/_components/`.
 
-**pnpm catalog** — `pnpm-workspace.yaml` defines `catalog:` for version pinning. All shared deps use `catalog:` references to guarantee a single version across all packages. When adding new shared deps (including test deps), add to catalog first.
+**`features/`** — Domain modules, each with its own components, hooks, stores, and config:
+
+| Feature | Purpose | Exports |
+|---|---|---|
+| `features/auth/` | Authentication state | `useAuthStore`, `AuthInitializer` |
+| `features/workspace/` | Workspace, members, agents | `useWorkspaceStore`, `useActorName` |
+| `features/issues/` | Issue state, components, config | `useIssueStore`, icons, pickers, status/priority config |
+| `features/inbox/` | Inbox notification state | `useInboxStore` |
+| `features/realtime/` | WebSocket connection + sync | `WSProvider`, `useWSEvent`, `useRealtimeSync` |
+| `features/modals/` | Modal registry and state | Modal store and components |
+| `features/skills/` | Skill management | Skill components |
+
+**`shared/`** — Code used across multiple features:
+- `shared/api/` — `ApiClient` (REST) and `WSClient` (WebSocket) for backend communication, plus the `api` singleton.
+- `shared/types/` — Domain types (Issue, Agent, Workspace, etc.) and WebSocket event types.
+- `shared/logger.ts` — Logger utility.
 
 ### State Management
 
-The architecture relies on a strict split between server state and client state. Mixing them is the most common way to break it.
+- **Zustand** for global client state — one store per feature domain (`features/auth/store.ts`, `features/workspace/store.ts`, `features/issues/store.ts`, `features/inbox/store.ts`).
+- **React Context** only for connection lifecycle (`WSProvider` in `features/realtime/`).
+- **Local `useState`** for component-scoped UI state (forms, modals, filters).
+- Do not use React Context for data that can be a zustand store.
 
-- **TanStack Query owns all server state.** Issues, users, workspaces, inbox — anything fetched from the API lives in the Query cache. WS events keep it fresh via invalidation; no polling, no `staleTime` workarounds.
-- **Zustand owns all client state.** UI selections, filters, drafts, modal state, navigation history. Stores live in `packages/core/` (never in `packages/views/`) so both apps share them.
-- **React Context** is reserved for cross-cutting platform plumbing — `WorkspaceIdProvider`, `NavigationProvider`. Don't reach for it for general state.
-- **Auth and workspace stores are the only stores allowed to call `api.*` directly**, because they manage critical state that must exist before queries can run. They're created via factory + injected dependencies, registered by the platform layer.
+**Store conventions:**
+- One store per feature domain. Import via `useAuthStore(selector)` or `useWorkspaceStore(selector)`.
+- Stores must not call `useRouter` or any React hooks — keep navigation in components.
+- Cross-store reads use `useOtherStore.getState()` inside actions (not hooks).
+- Dependency direction: `workspace` → `auth`, `realtime` → `auth`, `issues` → `workspace`. Never reverse.
 
-**Hard rules — these are how the architecture stays coherent:**
+### Import Aliases
 
-- **Never duplicate server data into Zustand.** If it came from the API, it belongs in the Query cache. Copying it into a store creates two sources of truth and they will drift.
-- **Workspace-scoped queries must key on `wsId`.** This is what makes workspace switching automatic — the cache key changes, the right data appears, no manual invalidation needed.
-- **Mutations are optimistic by default.** Apply the change locally, send the request, roll back on failure, invalidate on settle. The user shouldn't wait for the server.
-- **WS events invalidate queries — they never write to stores directly.** This keeps the cache as the single source of truth and avoids race conditions.
-- **Persist what's worth preserving across restarts** (user preferences, drafts, tab layout). **Don't persist ephemeral UI state** (modal open/close, transient selections) or server data.
+Use `@/` alias (maps to `apps/web/`):
+```typescript
+import { api } from "@/shared/api";
+import type { Issue } from "@/shared/types";
+import { useAuthStore } from "@/features/auth";
+import { useWorkspaceStore } from "@/features/workspace";
+import { useIssueStore } from "@/features/issues";
+import { useInboxStore } from "@/features/inbox";
+import { useWSEvent } from "@/features/realtime";
+import { StatusIcon } from "@/features/issues/components";
+```
 
-**Common Zustand footguns to avoid:**
+Within a feature, use relative imports. Between features or to shared, use `@/`.
 
-- Selectors must return stable references. Returning a freshly built object or array on every call (e.g. `s => ({ a: s.a, b: s.b })` or `s => s.items.map(...)`) triggers infinite re-renders. Either select primitives separately or use shallow comparison.
-- Hooks that need workspace context should accept `wsId` as a parameter, not call `useWorkspaceId()` internally — this lets them work outside the `WorkspaceIdProvider` (e.g. in a sidebar that renders before workspace is loaded).
+### Data Flow
+
+```
+Browser → ApiClient (shared/api) → REST API (Chi handlers) → sqlc queries → PostgreSQL
+Browser ← WSClient (shared/api) ← WebSocket ← Hub.Broadcast() ← Handlers/TaskService
+```
+
+### Backend Structure (`server/`)
+
+- **Entry points** (`cmd/`): `server` (HTTP API), `multica` (CLI — daemon, agent management, config), `migrate`
+- **Handlers** (`internal/handler/`): One file per domain (issue, comment, agent, auth, daemon, etc.). Each handler holds `Queries`, `DB`, `Hub`, and `TaskService`.
+- **Real-time** (`internal/realtime/`): Hub manages WebSocket clients. Server broadcasts events; inbound WS message routing is still TODO.
+- **Auth** (`internal/auth/` + `internal/middleware/`): JWT (HS256). Middleware sets `X-User-ID` and `X-User-Email` headers. Login creates user on-the-fly if not found.
+- **Task lifecycle** (`internal/service/task.go`): Orchestrates agent work — enqueue → claim → start → complete/fail. Syncs issue status automatically and broadcasts WS events at each transition.
+- **Agent SDK** (`pkg/agent/`): Unified `Backend` interface for executing prompts via Claude Code or Codex. Each backend spawns its CLI and streams results via `Session.Messages` + `Session.Result` channels.
+- **Daemon** (`internal/daemon/`): Local agent runtime — auto-detects available CLIs (claude, codex), registers runtimes, polls for tasks, routes by provider.
+- **CLI** (`internal/cli/`): Shared helpers for the `multica` CLI — API client, config management, output formatting.
+- **Events** (`internal/events/`): Internal event bus for decoupled communication between handlers and services.
+- **Logging** (`internal/logger/`): Structured logging via slog. `LOG_LEVEL` env var controls level (debug, info, warn, error).
+- **Database**: PostgreSQL with pgvector extension (`pgvector/pgvector:pg17`). sqlc generates Go code from SQL in `pkg/db/queries/` → `pkg/db/generated/`. Migrations in `migrations/`.
+- **Routes** (`cmd/server/router.go`): Public routes (auth, health, ws) + protected routes (require JWT) + daemon routes (unauthenticated, separate auth model).
+
+### Multi-tenancy
+
+All queries filter by `workspace_id`. Membership checks gate access. `X-Workspace-ID` header routes requests to the correct workspace.
+
+### Agent Assignees
+
+Assignees are polymorphic — can be a member or an agent. `assignee_type` + `assignee_id` on issues. Agents render with distinct styling (purple background, robot icon).
 
 ## Commands
 
 ```bash
-# One-command dev (auto-setup + start everything)
-make dev              # Auto-creates env, installs deps, starts DB, migrates, launches app
-
-# Explicit setup & run (if you prefer separate steps)
+# One-click setup & run
 make setup            # First-time: ensure shared DB, create app DB, migrate
 make start            # Start backend + frontend together
 make stop             # Stop app processes for the current checkout
 make db-down          # Stop the shared PostgreSQL container
 
-# Frontend (all commands go through Turborepo)
+# Frontend
 pnpm install
 pnpm dev:web          # Next.js dev server (port 3000)
-pnpm dev:desktop      # Electron dev (electron-vite, HMR)
-pnpm build            # Build all frontend apps
-pnpm typecheck        # TypeScript check (all packages + apps via turbo)
-pnpm lint             # ESLint
-pnpm test             # TS tests (Vitest, all packages + apps via turbo)
+pnpm build            # Build frontend
+pnpm typecheck        # TypeScript check
+pnpm lint             # ESLint via Next.js
+pnpm test             # TS tests (Vitest)
 
 # Backend (Go)
-make server           # Run Go server only (port 8080)
+make dev              # Run Go server (port 8080)
 make daemon           # Run local daemon
 make build            # Build server + CLI binaries to server/bin/
 make cli ARGS="..."   # Run multica CLI (e.g. make cli ARGS="config")
@@ -85,28 +133,18 @@ make sqlc             # Regenerate sqlc code after editing SQL in server/pkg/db/
 make migrate-up       # Run database migrations
 make migrate-down     # Rollback migrations
 
-# Run a single TS test (works for any package with a test script)
-pnpm --filter @multica/views exec vitest run auth/login-page.test.tsx
-pnpm --filter @multica/core exec vitest run runtimes/version.test.ts
-pnpm --filter @multica/web exec vitest run app/\(auth\)/login/page.test.tsx
-
 # Run a single Go test
 cd server && go test ./internal/handler/ -run TestName
 
+# Run a single TS test
+pnpm --filter @multica/web exec vitest run src/path/to/file.test.ts
+
 # Run a single E2E test (requires backend + frontend running)
 pnpm exec playwright test e2e/tests/specific-test.spec.ts
 
-# Desktop build & package
-pnpm --filter @multica/desktop build      # Compile TS → JS (reads .env.production)
-pnpm --filter @multica/desktop package    # Package into .app/.dmg/.exe (current platform only)
-
-# shadcn — config lives in packages/ui/components.json (Base UI variant, base-nova style)
-pnpm ui:add badge                # Adds component to packages/ui/components/ui/
-
 # Infrastructure
 make db-up            # Start shared PostgreSQL (pgvector/pg17 image)
 make db-down          # Stop shared PostgreSQL
-make db-reset         # Drop + recreate current env's DB, then re-run migrations (local only; stop backend first)
 ```
 
 ### CI Requirements
@@ -117,8 +155,6 @@ CI runs on Node 22 and Go 1.26.1 with a `pgvector/pgvector:pg17` PostgreSQL serv
 
 All checkouts share one PostgreSQL container. Isolation is at the database level — each worktree gets its own DB name and unique ports via `.env.worktree`. Main checkouts use `.env`.
 
-`make dev` auto-detects worktrees and handles everything. For explicit control:
-
 ```bash
 make worktree-env       # Generate .env.worktree with unique DB/ports
 make setup-worktree     # Setup using .env.worktree
@@ -133,167 +169,43 @@ make start-worktree     # Start using .env.worktree
 - Prefer existing patterns/components over introducing parallel abstractions.
 - Unless the user explicitly asks for backwards compatibility, do **not** add compatibility layers, fallback paths, dual-write logic, legacy adapters, or temporary shims.
 - 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.
+- Treat compatibility code as a maintenance cost, not a default safety mechanism. Avoid "just in case" branches that make the codebase harder to reason about.
 - 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
-
-These are hard constraints. Violating them breaks the cross-platform architecture:
-
-- `packages/core/` — zero react-dom, zero localStorage (use StorageAdapter), zero process.env, zero UI libraries. **All shared Zustand stores live here**, even view-related ones (filters, view modes) — stores are pure state, not UI.
-- `packages/ui/` — zero `@multica/core` imports (pure UI, no business logic).
-- `packages/views/` — zero `next/*` imports, zero `react-router-dom` imports, zero stores. Use `NavigationAdapter` for all routing.
-- `apps/web/platform/` — the only place for Next.js APIs (`next/navigation`).
-- `apps/desktop/src/renderer/src/platform/` — the only place for react-router-dom navigation wiring.
-
-### The No-Duplication Rule
-
-**If the same logic exists in both apps, it must be extracted to a shared package.**
-
-This applies to everything: components, hooks, guards, providers, utility functions. The decision process:
-
-1. Does this code depend on Next.js or Electron APIs? → Keep in the respective app.
-2. Does it depend on `react-router-dom` or `next/navigation`? → Keep in app's `platform/` layer.
-3. Everything else → belongs in `packages/core/` (headless logic) or `packages/views/` (UI components).
-
-When the two apps need different behavior for the same concept (e.g., different loading UI), extract the shared logic into a component with props/slots for the differences. Don't duplicate the logic.
-
-### Cross-Platform Development Rules
-
-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*.
-3. **Navigation** → use `useNavigation().push()` or `<AppLink>`. Never use framework-specific link/router APIs in shared code.
-4. **Shared guards/providers** → use `DashboardGuard` from `packages/views/layout/`. Don't create separate guard logic per app.
-5. **Platform-specific UI** → if a feature is web-only or desktop-only, keep it in the respective app. Use props slots (`extra`, `topSlot`) on shared layout components to inject platform-specific UI.
-6. **New hooks that need workspace context** → accept `wsId` as parameter instead of reading from `useWorkspaceId()` Context, so they work both inside and outside `WorkspaceIdProvider`.
-
-### CSS Architecture
-
-Both apps share the same CSS foundation from `packages/ui/styles/`.
-
-- **Design tokens** → use semantic tokens (`bg-background`, `text-muted-foreground`). Never use hardcoded Tailwind colors (`text-red-500`, `bg-gray-100`).
-- **Shared styles** → `packages/ui/styles/`. Never duplicate scrollbar styling, keyframes, or base layer rules in app CSS.
-- **`@source` directives** → both apps scan shared packages so Tailwind sees all class names.
-
-## Desktop-specific Rules
-
-These rules apply to `apps/desktop/` only. Web has different constraints (URL bar, SSR, no tabs) and doesn't share these concerns. Every rule in this section was added after a concrete bug — treat them as enforced, not suggestions.
-
-### Route categories
-
-Every path in the desktop app falls into exactly one category. Choosing the wrong one reproduces bugs we've already fixed.
-
-- **Session routes** — workspace-scoped pages (`/:slug/issues`, `/:slug/settings`). Rendered by the per-tab memory router under `WorkspaceRouteLayout`. These are legitimate tab destinations.
-- **Transition flows** — pre-workspace / one-shot actions (create workspace, accept invite). **NOT routes.** They live as `WindowOverlay` state, dispatched when the navigation adapter sees `push('/workspaces/new')` or `push('/invite/<id>')`. The shared view (`NewWorkspacePage`, `InvitePage`) is the content; the overlay wrapper supplies platform chrome.
-- **Error / stale states** — "workspace not available", tabs pointing at a revoked workspace. **NOT pages.** `WorkspaceRouteLayout` auto-heals by dropping the stale tab group from the store; the user never lands on an explicit error screen. Web keeps `NoAccessPage` (shareable URL makes the error state meaningful); desktop has no URL bar so stale = heal silently.
-
-**Adding a new pre-workspace flow on desktop**: register a new `WindowOverlay` type in `stores/window-overlay-store.ts`. Do NOT add it to `routes.tsx`. If a shared view needs the flow on both platforms, add the route on web (`apps/web/app/(auth)/...`) AND the overlay type on desktop — the shared view component is identical.
-
-### Workspace context
-
-`setCurrentWorkspace(slug, uuid)` from `@multica/core/platform` is the single source of truth for the active workspace. `WorkspaceRouteLayout` sets it on mount; unmount does NOT clear it. Code that leaves workspace context (leave/delete workspace, force-navigate to overlay) must call `setCurrentWorkspace(null, null)` explicitly.
-
-### Workspace destructive operations
-
-Leave / Delete workspace flows must follow this order, otherwise concurrent refetches race and the renderer hard-reloads:
-
-1. Read destination from cached workspace list.
-2. `setCurrentWorkspace(null, null)`.
-3. `navigation.push(destination)`.
-4. THEN `await mutation.mutateAsync(workspaceId)`.
-
-### Tab isolation
-
-Tabs are grouped per workspace in `stores/tab-store.ts`. The TabBar shows only the active workspace's tabs; cross-workspace tab leakage is impossible by construction (no flat global tabs array).
-
-Cross-workspace `push(path)` is detected by the navigation adapter (`platform/navigation.tsx`) and translated into `switchWorkspace(slug, targetPath)` — NOT a navigation within the current tab's router. Don't bypass the adapter; always go through `useNavigation()` from shared code.
-
-### Drag region (macOS)
-
-Every full-window desktop view (anything outside the dashboard shell) must mount `<DragStrip />` from `@multica/views/platform` as the first flex child of the page root, otherwise users can't drag the window. Interactive UI inside the top 48px needs `WebkitAppRegion: "no-drag"` to stay clickable.
 
 ## UI/UX Rules
 
-- Prefer shadcn components over custom implementations. Install via `pnpm ui:add <component>` from project root — adds to `packages/ui/components/ui/`. All components use Base UI primitives (`@base-ui/react`), not Radix.
-- Use shadcn design tokens for styling. Avoid hardcoded color values.
-- Do not introduce extra state (useState, context, reducers) unless explicitly required by the design.
+- Prefer shadcn components over custom implementations. Install missing components via `npx shadcn add`.
+- **Feature-specific components** → `features/<domain>/components/` — issue icons, pickers, and other domain-bound UI live inside their feature module.
+- Use shadcn design tokens for styling (e.g. `bg-primary`, `text-muted-foreground`, `text-destructive`). Avoid hardcoded color values (e.g. `text-red-500`, `bg-gray-100`).
+- Do not introduce extra state (useState, context, reducers) unless explicitly required by the design. Prefer zustand stores for shared state over React Context.
 - Pay close attention to **overflow** (truncate long text, scrollable containers), **alignment**, and **spacing** consistency.
-- **If a component is identical between web and desktop, it belongs in a shared package.** Do not copy-paste between apps.
+- When unsure about interaction or state design, ask — the user will provide direction.
 
 ## Testing Rules
 
-### Where to write tests
-
-Tests follow the code, not the app. This is the most important testing principle in this monorepo:
-
-| What you're testing | Where the test lives | Why |
-|---|---|---|
-| Shared business logic (stores, queries, hooks) | `packages/core/*.test.ts` | No DOM needed, pure logic |
-| Shared UI components (pages, forms, modals) | `packages/views/*.test.tsx` | jsdom, no framework mocks |
-| Platform-specific wiring (cookies, redirects, searchParams) | `apps/web/*.test.tsx` or `apps/desktop/` | Needs framework-specific mocks |
-| End-to-end user flows | `e2e/*.spec.ts` | Real browser, real backend |
-
-**Never test shared component behavior in an app's test file.** If a test requires mocking `next/navigation` or `react-router-dom` to test a component from `@multica/views`, the test is in the wrong place — move it to `packages/views/` and mock `@multica/core` instead.
-
-### Test infrastructure
-
-- `packages/core/` — Vitest, Node environment (no DOM)
-- `packages/views/` — Vitest, jsdom environment, `@testing-library/react`
-- `apps/web/` — Vitest, jsdom environment, framework-specific mocks
-- `e2e/` — Playwright
-- `server/` — Go standard `go test`
-
-All test deps are in the pnpm catalog for unified versioning.
-
-### Mocking conventions
-
-- Mock `@multica/core` stores with `vi.hoisted()` + `Object.assign(selectorFn, { getState })` pattern (Zustand stores are both callable and have `.getState()`).
-- Mock `@multica/core/api` for API calls.
-- In `packages/views/` tests: never mock `next/*` or `react-router-dom` — those don't exist here.
-- In `apps/web/` tests: mock framework-specific APIs only for platform-specific behavior.
-
-### TDD workflow
-
-1. Write failing test in the **correct package** first.
-2. Write implementation.
-3. Run `pnpm test` (Turborepo discovers all packages).
-4. Green → done.
-
-### Go tests
-
-Standard `go test`. Tests should create their own fixture data in a test database.
-
-### E2E tests
-
-E2E tests should be self-contained. Use the `TestApiClient` fixture for data setup/teardown:
-
-```typescript
-import { loginAsDefault, createTestApi } from "./helpers";
-import type { TestApiClient } from "./fixtures";
-
-let api: TestApiClient;
-
-test.beforeEach(async ({ page }) => {
-  api = await createTestApi();
-  await loginAsDefault(page);
-});
-
-test.afterEach(async () => {
-  await api.cleanup();
-});
-
-test("example", async ({ page }) => {
-  const issue = await api.createIssue("Test Issue");
-  await page.goto(`/issues/${issue.id}`);
-});
-```
+- **TypeScript**: Vitest. Mock external/third-party dependencies only.
+- **Go**: Standard `go test`. Tests should create their own fixture data in a test database.
 
 ## Commit Rules
 
 - Use atomic commits grouped by logical intent.
-- Conventional format: `feat(scope)`, `fix(scope)`, `refactor(scope)`, `docs`, `test(scope)`, `chore(scope)`.
+- Conventional format:
+  - `feat(scope): ...`
+  - `fix(scope): ...`
+  - `refactor(scope): ...`
+  - `docs: ...`
+  - `test(scope): ...`
+  - `chore(scope): ...`
+
+## CLI Release
+
+**Prerequisite:** A CLI release must accompany every Production deployment. When deploying to Production, always release a new CLI version as part of the process.
+
+1. Create a tag on the `main` branch: `git tag v0.x.x`
+2. Push the tag: `git push origin v0.x.x`
+3. GitHub Actions automatically triggers `release.yml`: runs Go tests → GoReleaser builds multi-platform binaries → publishes to GitHub Releases + Homebrew tap
+
+By default, bump the patch version each release (e.g. `v0.1.12` → `v0.1.13`), unless the user specifies a specific version.
 
 ## Minimum Pre-Push Checks
 
@@ -306,7 +218,7 @@ Run verification only when the user explicitly asks for it.
 For targeted checks when requested:
 ```bash
 pnpm typecheck        # TypeScript type errors only
-pnpm test             # TS unit tests only (Vitest, all packages)
+pnpm test             # TS unit tests only (Vitest)
 make test             # Go tests only
 pnpm exec playwright test   # E2E only (requires backend + frontend running)
 ```
@@ -319,29 +231,43 @@ After writing or modifying code, always run the full verification pipeline:
 make check
 ```
 
+This runs all checks in sequence:
+1. TypeScript typecheck (`pnpm typecheck`)
+2. TypeScript unit tests (`pnpm test`)
+3. Go tests (`go test ./...`)
+4. E2E tests (auto-starts backend + frontend if needed, runs Playwright)
+
 **Workflow:**
 - Write code to satisfy the requirement
 - Run `make check`
-- If any step fails, read the error output, fix the code, and re-run
+- If any step fails, read the error output, fix the code, and re-run `make check`
 - Repeat until all checks pass
 - Only then consider the task complete
 
 **Quick iteration:** If you know only TypeScript or Go is affected, run individual checks first for faster feedback, then finish with a full `make check` before marking work complete.
 
-## CLI Release
+## E2E Test Patterns
 
-**Prerequisite:** A CLI release must accompany every Production deployment.
+E2E tests should be self-contained. Use the `TestApiClient` fixture for data setup/teardown:
 
-1. Create a tag on the `main` branch: `git tag v0.x.x`
-2. Push the tag: `git push origin v0.x.x`
-3. GitHub Actions automatically triggers `release.yml`: runs Go tests → GoReleaser builds multi-platform binaries → publishes to GitHub Releases + Homebrew tap
+```typescript
+import { loginAsDefault, createTestApi } from "./helpers";
+import type { TestApiClient } from "./fixtures";
 
-By default, bump the patch version each release (e.g. `v0.1.12` → `v0.1.13`), unless the user specifies a specific version.
+let api: TestApiClient;
 
-## Multi-tenancy
+test.beforeEach(async ({ page }) => {
+  api = await createTestApi();       // logged-in API client
+  await loginAsDefault(page);        // browser session
+});
 
-All queries filter by `workspace_id`. Membership checks gate access. `X-Workspace-ID` header routes requests to the correct workspace.
+test.afterEach(async () => {
+  await api.cleanup();               // delete any data created during the test
+});
 
-## Agent Assignees
-
-Assignees are polymorphic — can be a member or an agent. `assignee_type` + `assignee_id` on issues. Agents render with distinct styling (purple background, robot icon).
+test("example", async ({ page }) => {
+  const issue = await api.createIssue("Test Issue");  // create via API
+  await page.goto(`/issues/${issue.id}`);             // test via UI
+  // api.cleanup() in afterEach removes the issue
+});
+```

CLI_AND_DAEMON.md

@@ -7,7 +7,8 @@ The `multica` CLI connects your local machine to Multica. It handles authenticat
 ### Homebrew (macOS/Linux)
 
 ```bash
-brew install multica-ai/tap/multica
+brew tap multica-ai/tap
+brew install multica-cli
 ```
 
 ### Build from Source
@@ -21,30 +22,14 @@ cp server/bin/multica /usr/local/bin/multica
 
 ### Update
 
-```bash
-brew upgrade multica-ai/tap/multica
-```
-
-For install script or manual installs, use:
-
 ```bash
 multica update
 ```
 
-`multica update` auto-detects your installation method and upgrades accordingly.
+This auto-detects your installation method (Homebrew or manual) and upgrades accordingly.
 
 ## Quick Start
 
-```bash
-# One-command setup: configure, authenticate, and start the daemon
-multica setup
-
-# For self-hosted (local) deployments:
-multica setup self-host
-```
-
-Or step by step:
-
 ```bash
 # 1. Authenticate (opens browser for login)
 multica login
@@ -140,12 +125,6 @@ The daemon auto-detects these AI CLIs on your PATH:
 |-----|---------|-------------|
 | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `claude` | Anthropic's coding agent |
 | [Codex](https://github.com/openai/codex) | `codex` | OpenAI's coding agent |
-| 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.
 
@@ -180,56 +159,34 @@ Agent-specific overrides:
 | `MULTICA_CLAUDE_MODEL` | Override the Claude model used |
 | `MULTICA_CODEX_PATH` | Custom path to the `codex` binary |
 | `MULTICA_CODEX_MODEL` | Override the Codex model used |
-| `MULTICA_OPENCODE_PATH` | Custom path to the `opencode` binary |
-| `MULTICA_OPENCODE_MODEL` | Override the OpenCode model used |
-| `MULTICA_OPENCLAW_PATH` | Custom path to the `openclaw` binary |
-| `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
 
-When connecting to a self-hosted Multica instance, the easiest approach is:
+When connecting to a self-hosted Multica instance, point the CLI to your server before logging in:
 
 ```bash
-# One command — configures for localhost, authenticates, starts daemon
-multica setup self-host
-
-# Or for on-premise with custom domains:
-multica setup self-host --server-url https://api.example.com --app-url https://app.example.com
-```
-
-Or configure manually:
-
-```bash
-# Set URLs individually
-multica config set server_url http://localhost:8080
-multica config set app_url http://localhost:3000
-
-# For production with TLS:
-# multica config set server_url https://api.example.com
-# multica config set app_url https://app.example.com
+export MULTICA_APP_URL=https://app.example.com
+export MULTICA_SERVER_URL=wss://api.example.com/ws
 
 multica login
 multica daemon start
 ```
 
+Or set them persistently:
+
+```bash
+multica config set app_url https://app.example.com
+multica config set server_url wss://api.example.com/ws
+```
+
 ### Profiles
 
 Profiles let you run multiple daemons on the same machine — for example, one for production and one for a staging server.
 
 ```bash
-# Set up a staging profile
-multica setup self-host --profile staging --server-url https://api-staging.example.com --app-url https://staging.example.com
-
-# Start its daemon
-multica daemon start --profile staging
+# Start a daemon for the staging server
+multica --profile staging login
+multica --profile staging daemon start
 
 # Default profile runs separately
 multica daemon start
@@ -278,7 +235,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 +250,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 +289,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,88 +306,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
-# One-command setup for Multica Cloud: configure, authenticate, and start the daemon
-multica setup
-
-# For local self-hosted deployments
-multica setup self-host
-
-# Custom ports
-multica setup self-host --port 9090 --frontend-port 4000
-
-# On-premise with custom domains
-multica setup self-host --server-url https://api.example.com --app-url https://app.example.com
-```
-
-`multica setup` configures the CLI, opens your browser for authentication, and starts the daemon — all in one step. Use `multica setup self-host` to connect to a self-hosted server instead of Multica Cloud.
-
 ## Configuration
 
 ### View Config
@@ -465,68 +319,11 @@ Shows config file path, server URL, app URL, and default workspace.
 ### Set Values
 
 ```bash
-multica config set server_url https://api.example.com
+multica config set server_url wss://api.example.com/ws
 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

@@ -1,201 +0,0 @@
-# Multica CLI — Installation Guide for AI Agents
-
-> **Audience:** This document is designed for AI agents (Claude Code, Codex, etc.) to read and execute step-by-step. Each step includes the exact shell commands to run, expected outcomes, and error handling.
-
-## One-Line Instruction for Users
-
-Give this instruction to your AI agent:
-
-```
-Fetch https://github.com/multica-ai/multica/blob/main/CLI_INSTALL.md and follow the instructions to install Multica CLI, log in, and start the daemon on this machine.
-```
-
----
-
-## Step 1: Check if Multica CLI is already installed
-
-Run:
-
-```bash
-multica version
-```
-
-- **If it prints a version string** (e.g. `multica v0.x.x`): skip to **Step 3**.
-- **If command not found**: continue to **Step 2**.
-
----
-
-## Step 2: Install the Multica CLI
-
-> **Windows users:** Skip to [Option C: Windows (PowerShell)](#option-c-windows-powershell) below.
-
-### Option A: Homebrew (preferred — macOS/Linux)
-
-Check if Homebrew is available:
-
-```bash
-which brew
-```
-
-If `brew` is found, install via Homebrew:
-
-```bash
-brew install multica-ai/tap/multica
-```
-
-Then verify:
-
-```bash
-multica version
-```
-
-If the version prints successfully, skip to **Step 3**.
-
-To upgrade later, run:
-
-```bash
-brew upgrade multica-ai/tap/multica
-```
-
-### Option B: Download from GitHub Releases (macOS/Linux, no Homebrew)
-
-If Homebrew is not available, download the binary directly.
-
-Detect OS and architecture, then download the correct archive:
-
-```bash
-OS=$(uname -s | tr '[:upper:]' '[:lower:]')   # "darwin" or "linux"
-ARCH=$(uname -m)                                # "x86_64" or "arm64"
-
-# Normalize architecture name
-if [ "$ARCH" = "x86_64" ]; then
-  ARCH="amd64"
-fi
-
-# Get the latest release tag from GitHub
-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
-tar -xzf /tmp/multica.tar.gz -C /tmp multica
-sudo mv /tmp/multica /usr/local/bin/multica
-rm /tmp/multica.tar.gz
-```
-
-Verify:
-
-```bash
-multica version
-```
-
-**If this fails:**
-- Check that `/usr/local/bin` is in `$PATH`.
-- On Linux, you may need `chmod +x /usr/local/bin/multica`.
-- If `sudo` is not available, install to a user-writable directory: `mv /tmp/multica ~/.local/bin/multica` and ensure `~/.local/bin` is in `$PATH`.
-
-### Option C: Windows (PowerShell)
-
-Run in PowerShell (no admin required):
-
-```powershell
-irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex
-```
-
-This downloads the latest Windows binary from GitHub Releases, installs it to `%USERPROFILE%\.multica\bin\`, and adds it to your user PATH.
-
-Verify:
-
-```powershell
-multica version
-```
-
-**If this fails:**
-- Restart your terminal so the updated PATH takes effect.
-- If you use Scoop, the installer will use it automatically: `scoop bucket add multica https://github.com/multica-ai/scoop-bucket.git && scoop install multica`
-- If your execution policy blocks the script: `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` then re-run.
-
----
-
-## Step 3: Log in
-
-Run:
-
-```bash
-multica login
-```
-
-**Important:** This command opens a browser window for OAuth authentication. Tell the user:
-
-> "A browser window will open for Multica login. Please complete the authentication in your browser, then come back here."
-
-Wait for the command to complete. It will automatically discover and watch all workspaces the user belongs to.
-
-Verify:
-
-```bash
-multica auth status
-```
-
-Expected output should show the authenticated user and server URL.
-
-**If login fails:**
-- If no browser is available (headless environment), the user can generate a Personal Access Token at `https://app.multica.ai/settings` and run: `multica login --token`
-- If the server URL needs to be customized: `multica config set server_url <url>` before logging in.
-
----
-
-## Step 4: Start the daemon
-
-First, check if the daemon is already running:
-
-```bash
-multica daemon status
-```
-
-- **If status is "running"**: skip to **Step 5**.
-- **If status is "stopped"**: start it:
-
-```bash
-multica daemon start
-```
-
-Wait 3 seconds, then verify:
-
-```bash
-multica daemon status
-```
-
-Expected output should show `running` status with detected agents (e.g. `claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, `cursor-agent`).
-
-**If daemon fails to start:**
-- Check logs: `multica daemon logs`
-- If a port conflict occurs, the daemon may already be running under a different profile.
-- If no agents are detected, ensure at least one AI CLI (`claude`, `codex`, `opencode`, `openclaw`, `hermes`, `gemini`, `pi`, or `cursor-agent`) is installed and on the `$PATH`.
-
----
-
-## Step 5: Verify everything is working
-
-Run:
-
-```bash
-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`)
-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`."
-
----
-
-## Summary
-
-When all steps are complete, inform the user:
-
-> "Multica CLI is installed and the daemon is running. Agents in your workspaces can now execute tasks on this machine. You can manage workspaces with `multica workspace list` and view daemon logs with `multica daemon logs -f`."

CONTRIBUTING.md

@@ -9,7 +9,6 @@ It covers:
 - isolated worktree development
 - the shared PostgreSQL model
 - testing and verification
-- full-stack isolated testing (backend + frontend + daemon from source)
 - troubleshooting and destructive reset options
 
 ## Development Model
@@ -95,52 +94,59 @@ FORCE=1 make worktree-env
 
 ## First-Time Setup
 
-### Quick Start (recommended)
+### Main Checkout
 
-From any checkout (main or worktree):
-
-```bash
-make dev
-```
-
-This single command:
-
-- auto-detects whether you're in a main checkout or a worktree
-- creates the appropriate env file (`.env` or `.env.worktree`) if it doesn't exist
-- checks that prerequisites (Node.js, pnpm, Go, Docker) are installed
-- installs JavaScript dependencies
-- ensures the shared PostgreSQL container is running
-- creates the application database if it does not exist
-- runs all migrations
-- starts both backend and frontend
-
-### Explicit Setup (advanced)
-
-If you prefer separate control over setup and startup:
-
-#### Main Checkout
+From the main checkout:
 
 ```bash
 cp .env.example .env
 make setup-main
+```
+
+What `make setup-main` does:
+
+- installs JavaScript dependencies with `pnpm install`
+- ensures the shared PostgreSQL container is running
+- creates the application database if it does not exist
+- runs all migrations against that database
+
+Start the app:
+
+```bash
 make start-main
 ```
 
-Stop:
+Stop the app processes:
 
 ```bash
 make stop-main
 ```
 
-#### Worktree
+This does not stop PostgreSQL.
+
+### Worktree
+
+From the worktree directory:
 
 ```bash
 make worktree-env
 make setup-worktree
+```
+
+What `make setup-worktree` does:
+
+- uses `.env.worktree`
+- ensures the shared PostgreSQL container is running
+- creates the worktree database if it does not exist
+- runs migrations against the worktree database
+
+Start the worktree app:
+
+```bash
 make start-worktree
 ```
 
-Stop:
+Stop the worktree app processes:
 
 ```bash
 make stop-worktree
@@ -165,15 +171,17 @@ Use a worktree when you want isolated data and separate app ports.
 ```bash
 git worktree add ../multica-feature -b feat/my-change main
 cd ../multica-feature
-make dev
+make worktree-env
+make setup-worktree
+make start-worktree
 ```
 
 After that, day-to-day commands are:
 
 ```bash
-make dev              # start (re-runs setup if needed, idempotent)
-make stop-worktree    # stop
-make check-worktree   # verify
+make start-worktree
+make stop-worktree
+make check-worktree
 ```
 
 ## Running Main and Worktree at the Same Time
@@ -309,199 +317,6 @@ make daemon
 The daemon authenticates using the CLI's stored token (`multica login`).
 It registers runtimes for all watched workspaces from the CLI config.
 
-## Full-Stack Isolated Testing
-
-This section covers running the complete stack (backend, frontend, daemon) from
-source in a fully isolated environment. Useful for testing end-to-end changes
-that span multiple components, or for automated CI/AI workflows that need zero
-human intervention.
-
-### Why Not Just `make daemon`?
-
-`make daemon` uses the system-installed CLI's stored token and connects to
-whatever server is configured in `~/.multica/config.json`. That's fine for
-day-to-day development against a shared server, but for fully isolated testing
-you need:
-
-- a local backend and frontend (from source)
-- a local daemon (from source) with its own profile
-- automated authentication (no browser login)
-- no interference with your production CLI config
-
-### Dynamic Profile Naming
-
-Each worktree must use a unique daemon profile to avoid collisions when
-multiple features run in parallel.
-
-The profile name is derived from the worktree directory using the same
-slug + hash pattern as `scripts/init-worktree-env.sh`:
-
-```bash
-WORKTREE_DIR="$(basename "$PWD")"
-SLUG="$(printf '%s' "$WORKTREE_DIR" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/_/g; s/__*/_/g; s/^_//; s/_$//')"
-HASH="$(printf '%s' "$PWD" | cksum | awk '{print $1}')"
-OFFSET=$((HASH % 1000))
-PROFILE="dev-${SLUG}-${OFFSET}"
-```
-
-Example: worktree at `../multica-feat-auth` produces profile
-`dev-multica_feat_auth-347`, matching that worktree's port and database
-allocation.
-
-### Start the Isolated Environment
-
-Run all steps from the worktree root (where the Makefile is).
-
-#### 1. Start backend, frontend, and database
-
-```bash
-make dev
-```
-
-Wait for the backend to be healthy:
-
-```bash
-PORT=$(grep '^PORT=' .env.worktree 2>/dev/null || grep '^PORT=' .env | head -1 | cut -d= -f2)
-PORT=${PORT:-8080}
-SERVER="http://localhost:${PORT}"
-
-for i in $(seq 1 30); do
-  curl -sf "$SERVER/health" > /dev/null 2>&1 && break
-  sleep 2
-done
-```
-
-#### 2. Create a test user and token (automated auth)
-
-In non-production environments the verification code is fixed at `888888`:
-
-```bash
-curl -s -X POST "$SERVER/auth/send-code" \
-  -H "Content-Type: application/json" \
-  -d '{"email": "dev@localhost"}'
-
-JWT=$(curl -s -X POST "$SERVER/auth/verify-code" \
-  -H "Content-Type: application/json" \
-  -d '{"email": "dev@localhost", "code": "888888"}' | jq -r '.token')
-
-PAT=$(curl -s -X POST "$SERVER/api/tokens" \
-  -H "Authorization: Bearer $JWT" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "auto-dev", "expires_in_days": 365}' | jq -r '.token')
-```
-
-#### 3. Create a workspace
-
-```bash
-WS=$(curl -s -X POST "$SERVER/api/workspaces" \
-  -H "Authorization: Bearer $PAT" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "Dev", "slug": "dev"}' | jq -r '.id')
-```
-
-#### 4. Compute profile name and write CLI config
-
-```bash
-# Compute profile (see Dynamic Profile Naming above)
-WORKTREE_DIR="$(basename "$PWD")"
-SLUG="$(printf '%s' "$WORKTREE_DIR" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/_/g; s/__*/_/g; s/^_//; s/_$//')"
-HASH="$(printf '%s' "$PWD" | cksum | awk '{print $1}')"
-OFFSET=$((HASH % 1000))
-PROFILE="dev-${SLUG}-${OFFSET}"
-
-FRONTEND_PORT=$(grep '^FRONTEND_PORT=' .env.worktree 2>/dev/null || grep '^FRONTEND_PORT=' .env | head -1 | cut -d= -f2)
-FRONTEND_PORT=${FRONTEND_PORT:-3000}
-
-CONFIG_DIR="$HOME/.multica/profiles/$PROFILE"
-mkdir -p "$CONFIG_DIR"
-
-cat > "$CONFIG_DIR/config.json" << EOF
-{
-  "server_url": "$SERVER",
-  "app_url": "http://localhost:${FRONTEND_PORT}",
-  "token": "$PAT",
-  "workspace_id": "$WS",
-  "watched_workspaces": [{"id": "$WS", "name": "Dev"}]
-}
-EOF
-```
-
-#### 5. Start the daemon from source
-
-```bash
-make cli ARGS="daemon start --profile $PROFILE"
-```
-
-The daemon runs from the current worktree's Go source, connecting to the
-local backend. Agent-executed `multica` commands automatically use the same
-binary (the daemon prepends its own directory to `PATH`).
-
-### Stop the Isolated Environment
-
-```bash
-# Compute profile (same formula)
-PROFILE="dev-$(printf '%s' "$(basename "$PWD")" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/_/g; s/__*/_/g; s/^_//; s/_$//')-$(( $(printf '%s' "$PWD" | cksum | awk '{print $1}') % 1000 ))"
-
-# 1. Stop daemon
-make cli ARGS="daemon stop --profile $PROFILE"
-
-# 2. Stop backend + frontend
-make stop            # main checkout
-make stop-worktree   # worktree checkout
-
-# 3. (Optional) Stop shared PostgreSQL
-make db-down
-
-# 4. (Optional) Clean build artifacts
-make clean
-
-# 5. (Optional) Remove profile config
-rm -rf "$HOME/.multica/profiles/$PROFILE"
-```
-
-### Desktop App Local Testing
-
-To test the Electron desktop app against a local backend:
-
-```bash
-# After backend is running (make dev)
-pnpm dev:desktop
-```
-
-This automatically:
-
-1. Compiles the `multica` CLI from `server/cmd/multica` into
-   `apps/desktop/resources/bin/multica`
-2. Creates an isolated profile named `desktop-localhost-<PORT>`
-3. Starts and manages its own daemon instance
-4. Connects to the local backend
-
-Login in the Desktop UI with `dev@localhost` and code `888888`.
-
-If the backend runs on a non-default port (worktree), create
-`apps/desktop/.env.development.local`:
-
-```bash
-VITE_API_URL=http://localhost:<backend-port>
-VITE_WS_URL=ws://localhost:<backend-port>/ws
-```
-
-### Isolation Guarantee
-
-Nothing in this flow touches the system-installed `multica` or the default
-`~/.multica/config.json`:
-
-| Resource | System / Production | Local Dev (per-worktree) |
-|---|---|---|
-| Config | `~/.multica/config.json` | `~/.multica/profiles/dev-<slug>-<hash>/config.json` |
-| Daemon PID | `~/.multica/daemon.pid` | `~/.multica/profiles/dev-<slug>-<hash>/daemon.pid` |
-| Health port | `19514` | `19514 + 1 + (name_hash % 1000)` |
-| Workspaces dir | `~/multica_workspaces/` | `~/multica_workspaces_dev-<slug>-<hash>/` |
-| Database | remote / production | local Docker: `multica_<slug>_<hash>` |
-| Desktop profile | `desktop-api.multica.ai` | `desktop-localhost-<port>` |
-
-Multiple worktrees can run simultaneously without conflict.
-
 ## Troubleshooting
 
 ### Missing Env File
@@ -592,19 +407,6 @@ If you want to stop PostgreSQL and keep your local databases:
 make db-down
 ```
 
-If you want a fresh database for the current checkout only (drops the
-database named in `POSTGRES_DB`, recreates it, and runs all migrations):
-
-```bash
-make stop        # stop backend/frontend first
-make db-reset
-make start
-```
-
-- only affects the current env's database; other worktree databases are untouched
-- refuses to run if `DATABASE_URL` points at a remote host
-- pass `ENV_FILE=.env.worktree` to target a specific worktree
-
 If you want to wipe all local PostgreSQL data for this repo:
 
 ```bash
@@ -622,7 +424,9 @@ Warning:
 ### Stable Main Environment
 
 ```bash
-make dev
+cp .env.example .env
+make setup-main
+make start-main
 ```
 
 ### Feature Worktree
@@ -630,7 +434,9 @@ make dev
 ```bash
 git worktree add ../multica-feature -b feat/my-change main
 cd ../multica-feature
-make dev
+make worktree-env
+make setup-worktree
+make start-worktree
 ```
 
 ### Return to a Previously Configured Worktree

Dockerfile

@@ -30,9 +30,7 @@ COPY --from=builder /src/server/bin/server .
 COPY --from=builder /src/server/bin/multica .
 COPY --from=builder /src/server/bin/migrate .
 COPY server/migrations/ ./migrations/
-COPY docker/entrypoint.sh .
-RUN sed -i 's/\r$//' entrypoint.sh && chmod +x entrypoint.sh
 
 EXPOSE 8080
 
-ENTRYPOINT ["./entrypoint.sh"]
+ENTRYPOINT ["./server"]

Dockerfile.web

@@ -1,72 +0,0 @@
-# --- Dependencies ---
-FROM node:22-alpine AS deps
-
-RUN corepack enable && corepack prepare pnpm@10.28.2 --activate
-
-WORKDIR /app
-
-# Copy workspace config and all package.json files for dependency resolution
-COPY pnpm-lock.yaml pnpm-workspace.yaml package.json turbo.json .npmrc ./
-COPY apps/web/package.json apps/web/
-COPY packages/core/package.json packages/core/
-COPY packages/ui/package.json packages/ui/
-COPY packages/views/package.json packages/views/
-COPY packages/tsconfig/package.json packages/tsconfig/
-COPY packages/eslint-config/package.json packages/eslint-config/
-
-RUN pnpm install --frozen-lockfile
-
-# --- Build ---
-FROM node:22-alpine AS builder
-
-RUN corepack enable && corepack prepare pnpm@10.28.2 --activate
-
-WORKDIR /app
-
-# Copy installed dependencies (preserves pnpm symlink structure)
-COPY --from=deps /app ./
-
-# Copy source
-COPY package.json turbo.json pnpm-workspace.yaml ./
-COPY apps/web/ apps/web/
-COPY packages/ packages/
-
-# Re-link after source overlay (fixes any symlinks overwritten by COPY)
-RUN pnpm install --frozen-lockfile --offline
-
-# Set build-time env: tells Next.js rewrites to proxy API calls to the backend service
-ARG REMOTE_API_URL=http://backend:8080
-ARG NEXT_PUBLIC_WS_URL
-ARG NEXT_PUBLIC_APP_VERSION=dev
-ENV REMOTE_API_URL=$REMOTE_API_URL
-ENV NEXT_PUBLIC_WS_URL=$NEXT_PUBLIC_WS_URL
-ENV NEXT_PUBLIC_APP_VERSION=$NEXT_PUBLIC_APP_VERSION
-ENV STANDALONE=true
-
-# Build the web app (standalone output for minimal runtime)
-RUN pnpm --filter @multica/web build
-
-# --- Runtime ---
-FROM node:22-alpine AS runner
-
-WORKDIR /app
-
-ENV NODE_ENV=production
-
-RUN addgroup --system --gid 1001 nodejs && \
-    adduser --system --uid 1001 nextjs
-
-# Copy standalone output (includes traced node_modules)
-COPY --from=builder --chown=nextjs:nodejs /app/apps/web/.next/standalone ./
-# Copy static files (not included in standalone)
-COPY --from=builder --chown=nextjs:nodejs /app/apps/web/.next/static ./apps/web/.next/static
-# Copy public assets
-COPY --from=builder --chown=nextjs:nodejs /app/apps/web/public ./apps/web/public
-
-USER nextjs
-
-EXPOSE 3000
-ENV PORT=3000
-ENV HOSTNAME=0.0.0.0
-
-CMD ["node", "apps/web/server.js"]

HANDOFF_ARCHITECTURE_AUDIT.md

@@ -1,383 +0,0 @@
-# Architecture Audit — Workspace & Realtime Cache
-
-> 基于代码审计整理的 4 个任务。优先级：P0 一个、P1 一个、P2 两个。每个任务都包含问题、根因、受影响的 issue、复现步骤、修复方案、改动范围。
-
----
-
-## 任务 1 — [P0] 空闲后列表数据陈旧
-
-**关联 issue**：[#951](https://github.com/multica-ai/multica/issues/951)
-
-### 问题
-
-用户登录后静置一段时间，Issue 列表里缺失一部分数据（其他成员期间新建/变更的 issue 不出现）。登出再登入可以恢复。`ec5af33b` 声称 "Closes #951"，但 issue 仍为 OPEN 状态 —— 因为它只修了 401 一种场景，没修 WS 半开这一种。
-
-### 根因
-
-系统把 cache 新鲜度的全部责任压给了 WebSocket 推送：
-
-- `packages/core/query-client.ts:7` — `staleTime: Infinity`，cache 永不主动过期
-- `packages/core/query-client.ts:9` — `refetchOnWindowFocus: false`，tab 重新获得焦点也不 refetch
-- 依赖 WS 推送 `issue:created` / `issue:updated` 事件 invalidate cache
-
-但 WS 层存在一个**不对称**：
-
-- **服务端**：`server/internal/realtime/hub.go:83-96, 420-475` 有 54s ping / 60s pongWait，会清理死连接
-- **客户端**：`packages/core/api/ws-client.ts`（142 行全貌）**完全没有心跳检测**，只靠 `onclose` 事件触发重连
-
-浏览器原生 `WebSocket` API 不把 ping/pong 帧暴露给 JS，所以 JS 层无法主动探测 "半开" 连接。当 NAT / 负载均衡器 / 笔记本睡眠导致 TCP 连接被静默切断时：
-
-1. 浏览器 `readyState` 仍是 `OPEN`
-2. `onclose` 不触发
-3. `ws-client.ts:70-73` 的 3 秒重连逻辑不跑
-4. `packages/core/realtime/use-realtime-sync.ts:462-487` 的 `onReconnect` 全量 invalidate 不跑
-5. 期间的 WS 事件进黑洞
-6. cache 保持旧快照
-
-### 复现
-
-**浏览器 DevTools 里的 "Block request URL" 不行** —— 那会触发 `onclose`，走正常重连 → 不复现。真正的半开需要在网络层静默丢包。
-
-**方法 A（推荐，最接近真实场景）**：macOS 用 pfctl 丢包
-
-```bash
-# 假设后端在 8080
-sudo pfctl -E
-echo "block drop out quick proto tcp to any port 8080" | sudo pfctl -f -
-
-# 观察:
-# - Console 里没有 "disconnected, reconnecting in 3s" 日志
-# - Network 里 WS 连接仍显示 Pending / 101
-# 用另一个账号/CLI 创建一个 issue
-# 回到原客户端: 列表不更新
-# 登出再登入: 列表恢复完整
-
-sudo pfctl -d  # 解除
-```
-
-**方法 B（不动网络）**：临时修改代码，在 `packages/core/api/ws-client.ts:52` 的 `onmessage` 处理器里加一行 `return;` 在前面，吞掉所有入站消息。效果等价于半开。
-
-### 修复方案（三个选项，推荐 C）
-
-#### 选项 A — 浏览器端心跳探活（治本，改动大）
-
-在 `ws-client.ts` 加客户端侧的心跳检测：记录 `lastMessageTime`，定时器检查若超过 N 秒没收到任何消息就主动 `ws.close()`，触发现有重连逻辑。
-
-- 优点：从根本上解决半开问题
-- 缺点：浏览器原生 API 没有 ping 能力，需要服务端配合发"应用层 heartbeat"消息供客户端更新 `lastMessageTime`；服务端改 + 客户端改
-
-#### 选项 B — Page Visibility API 触发 invalidate（治标，改动小）
-
-在 `packages/core/platform/core-provider.tsx` 加 `visibilitychange` 监听，tab 重新可见时强制 `queryClient.invalidateQueries({ queryKey: issueKeys.all(wsId) })`（及其他关键 key）。
-
-- 优点：~10 行代码，能兜住 80% 场景（睡眠、切后台 tab）
-- 缺点：treats symptom, 不是真正的半开检测；对"一直保持 tab 可见但网络层断了"的场景无效
-
-#### 选项 C — **A + B 组合**（推荐）
-
-- 短期上 B，立刻止血
-- 中期上 A，把 cache 新鲜度从"只信 WS"改成"WS 是优化，Visibility 是兜底"
-- 可选加 `refetchOnWindowFocus: true` 或把 `staleTime` 改成一个有限值（比如 5 min），作为第三层保险
-
-### 改动范围
-
-| 方案 | 文件 | 改动规模 |
-|---|---|---|
-| B | `packages/core/platform/core-provider.tsx` | ~10 行 |
-| A 客户端 | `packages/core/api/ws-client.ts` | ~30 行 |
-| A 服务端 | `server/internal/realtime/hub.go` | 加 app-level heartbeat message |
-
-### 验证
-
-修完之后：
-
-1. 跑方法 A 复现流程，确认数据不再丢失
-2. 加 e2e 测试：模拟 `document.dispatchEvent(new Event('visibilitychange'))` + 验证 issue list 被 refetch
-
----
-
-## 任务 2 — [P1] Workspace 不在 URL 路径中
-
-**关联 issue**：MUL-723（slug 不在 URL）、MUL-43（切换 workspace 报错）、MUL-509（手机端无法切换）
-
-> **注意**：审计中提到的 MUL-43 / MUL-476 issue 编号需要当面核对一次 —— agent 查询 GitHub 后返回的标题对不上（看起来是别的 PR）。交接时请让执行人以具体症状为准。
-
-### 问题
-
-当前 workspace 身份完全靠 `X-Workspace-ID` HTTP header + Zustand store + localStorage 承载，URL 里没有 workspace 信息。所有路径都是 `/issues`、`/issues/:id` 这种 workspace-agnostic 的。
-
-### 根因
-
-**数据库和 API 已经支持 slug**：
-
-- `server/migrations/001_init.up.sql:15-23` — workspace 表有 `slug TEXT UNIQUE NOT NULL`
-- `server/pkg/db/queries/workspace.sql:11-13` — 有 `GetWorkspaceBySlug` 查询
-- `packages/core/types/workspace.ts:8-19` — Workspace 类型里有 slug 字段
-
-**但前端路由和导航层没用它**：
-
-- Web 路由：`apps/web/app/(dashboard)/` 下 25 个 route file 都是 workspace-implicit
-- Desktop 路由：`apps/desktop/src/renderer/src/routes.tsx:71-143` 同样
-- Navigation 适配器 `apps/web/platform/navigation.tsx` 直接透传 `router.push`，没有任何 workspace 前缀逻辑
-
-**workspace 切换只靠 sidebar UI**（`packages/views/layout/app-sidebar.tsx:284-286`）：
-
-```tsx
-if (ws.id !== workspace?.id) {
-  push("/issues");              // 硬跳 /issues（workspace-implicit！）
-  switchWorkspace(ws);           // 然后改 store
-}
-```
-
-这种设计使得：
-
-- 手机端因为没 sidebar UI，也没 URL 层切换入口，**完全切不了 workspace**（MUL-509）
-- 把 `/issues/xxx` 链接发给处于不同 workspace 的同事，会打开错误 workspace 下的 issue，或找不到报错（MUL-43 系列）
-- 分享链接没有 workspace 上下文，接收方必须先手动切对 workspace
-
-### 复现
-
-1. **MUL-723**：登录 → 观察地址栏，没有任何 workspace 标识
-2. **MUL-43**：
-   - 加入两个 workspace A 和 B
-   - 在 A 中打开某个 issue `/issues/abc123`
-   - 切到 B，URL 不变 → 访问失败 / 显示错数据
-3. **MUL-509**：手机浏览器打开，尝试切 workspace → 无法切换（UI 不显示 sidebar 触发器或触发器无法切）
-
-### 修复方案（三个选项，推荐 A）
-
-#### 选项 A — `/ws/:slug/...` URL 前缀（根本方案，推荐）
-
-所有路径加上 workspace slug 前缀。例如 `/issues/abc123` → `/ws/my-team/issues/abc123`。
-
-**要改的地方**：
-
-1. **Web 路由目录结构**：`apps/web/app/(dashboard)/` 下全部搬到 `apps/web/app/(dashboard)/ws/[slug]/...`（~25 个文件）
-2. **Desktop 路由**：`apps/desktop/src/renderer/src/routes.tsx:71-143` 给所有路径加 `/ws/:slug` 前缀
-3. **Navigation 适配器**：
-   - `apps/web/platform/navigation.tsx` — `push(path)` 内部前置 `/ws/${workspace.slug}`，`pathname` 读取时去掉前缀
-   - `apps/desktop/src/renderer/src/platform/navigation.tsx` — 同上
-4. **Sidebar 切换逻辑**：`packages/views/layout/app-sidebar.tsx:284-286` 改成 `push('/ws/${ws.slug}/issues')`（或依赖适配器自动加前缀就不用改）
-5. **服务端中间件**：`server/internal/middleware/workspace.go:41-46` 增加 "从 URL path 解析 slug → 查 ID → 校验 membership" 的逻辑，header 继续作为 fallback（迁移期兼容）
-
-**预计改动**：~50-100 个文件（大部分是 route 搬迁，不是逻辑改动）、~5-7 人天
-
-**不改也能工作的部分**：
-- `packages/core/api/client.ts` — 仍旧走 header，不用改
-- 所有 `packages/views/` 下的组件 —— 它们用 `useNavigation().push()` 抽象，适配器层处理前缀就行
-
-**风险**：
-- 旧的 bookmark URL 失效（如果产品还没正式 ship，问题不大）
-- E2E 测试需要更新所有 URL 断言
-
-#### 选项 B — `?ws=slug` query param（折中）
-
-URL 形如 `/issues?ws=my-team`。改动更小（~30 个文件），URL 丑但向后兼容。推荐度低于 A。
-
-#### 选项 C — 只修症状不动架构
-
-在 `switchWorkspace` 和各个 query 之间加 debounce、error boundary 等 workaround。不解决根因，技术债越攒越多。**不推荐**。
-
-### 改动范围（选项 A）
-
-| 模块 | 文件数 | 备注 |
-|---|---|---|
-| Web routes | ~25 | 目录搬迁 |
-| Desktop routes | 1 | 路径前缀 |
-| Navigation adapters | 2 | 前缀逻辑 |
-| Server middleware | 1-2 | slug → ID 解析 |
-| 组件（不用改） | 30-40 | 用 `useNavigation` 的不受影响 |
-| E2E tests | 20-30 | URL 断言更新 |
-
----
-
-## 任务 3 — [P1] Workspace 切换时 navigation 状态未隔离
-
-**关联 issue**：MUL-43（切换报错）、MUL-476（本地缓存未按 workspace 隔离）
-
-> 同上，这两个编号建议交接时核对症状。
-
-### 问题
-
-绝大多数 workspace-scoped 的 Zustand store 都正确使用了 `createWorkspaceAwareStorage`（key 后缀加 wsId 自动隔离），但 **`useNavigationStore` 是个例外**：它持久化了 `lastPath`，但用的是 global storage，切换 workspace 后里面仍是上个 workspace 的路径。
-
-### 根因
-
-**`packages/core/navigation/store.ts:15-31`**：
-
-```typescript
-export const useNavigationStore = create<NavigationState>()(
-  persist(
-    (set) => ({
-      lastPath: "/issues",
-      onPathChange: (path) => { /* ... */ set({ lastPath: path }); },
-    }),
-    {
-      name: "multica_navigation",
-      storage: createJSONStorage(() => createPersistStorage(defaultStorage)), // ← 这里用的是 global，不是 workspace-aware
-      partialize: (state) => ({ lastPath: state.lastPath }),
-    }
-  )
-);
-// ← 没有调 registerForWorkspaceRehydration
-```
-
-**对比：其他 store 都是正确的**：
-
-| Store | 是否 workspace-aware | 是否注册 rehydration |
-|---|---|---|
-| useNavigationStore | ❌ | ❌ |
-| useIssuesScopeStore | ✅ | ✅ |
-| useIssueDraftStore | ✅ | ✅ |
-| useRecentIssuesStore | ✅ | ✅ |
-| useIssueViewStore | ✅ | ✅ |
-| myIssuesViewStore | ✅ | ✅ |
-| useChatStore | ✅（手动用 wsKey）| ✅ |
-
-另外 `packages/core/platform/storage-cleanup.ts:10-19` 的 `WORKSPACE_SCOPED_KEYS` 列表里也漏了 `multica_navigation`。
-
-**现有的 workaround**：`packages/views/layout/app-sidebar.tsx:285` 切 workspace 时硬跳到 `/issues`，正是为了绕开这个 bug。修好 navigation store 之后这行 hack 可以删掉。
-
-### 复现
-
-1. 在 workspace A 中打开一个具体 issue `/issues/abc123`
-2. 切到 workspace B
-3. 观察：如果没有 sidebar 的硬跳 workaround，会尝试恢复到 `/issues/abc123`，但那个 issue 不属于 B，导致 404 或错误
-
-目前因为有硬跳 workaround，症状表现为"切 workspace 后总是回到 issue 首页"—— 这本身也是 bug（用户期望记住上次位置）。
-
-### 修复方案（推荐 Option C：组合）
-
-**三处改动**：
-
-1. `packages/core/navigation/store.ts:28` —— 把 `createPersistStorage(defaultStorage)` 改成 `createWorkspaceAwareStorage(defaultStorage)`
-2. 同文件在末尾加：`registerForWorkspaceRehydration(() => useNavigationStore.persist.rehydrate());`
-3. `packages/core/platform/storage-cleanup.ts:10-19` 的 `WORKSPACE_SCOPED_KEYS` 数组里加 `"multica_navigation"`
-
-**可选**：清理 `packages/views/layout/app-sidebar.tsx:285` 的 `push("/issues")` workaround（改完之后不再需要）。
-
-### 改动范围
-
-| 文件 | 改动 |
-|---|---|
-| `packages/core/navigation/store.ts` | 改 storage 类型、加 rehydration 注册（~3 行） |
-| `packages/core/platform/storage-cleanup.ts` | 数组加一行 |
-| `packages/core/platform/workspace-storage.test.ts` | 加 rehydration 的单测 |
-| `packages/views/layout/app-sidebar.tsx`（可选） | 移除硬跳 workaround |
-
-**风险**：极低。只是把 navigation store 对齐到其他 store 已经在用的模式。
-
----
-
-## 任务 4 — [P2] Workspace 生命周期副作用散落
-
-**关联 issue**：MUL-727（创建后闪页）、MUL-728（删除确认）、MUL-820（接受邀请不自动切）
-
-### 问题
-
-创建 / 删除 / 切换 / 加入 workspace 的副作用分散在 mutation 的 `onSuccess` 和各处 UI 回调里，没有统一抽象。几个具体 bug：
-
-### 4.1 MUL-727 — 创建 workspace 后闪一下 `/issues` 再跳 `/onboarding`
-
-**根因**：两个 `onSuccess` 回调同时跑，顺序不确定。
-
-- `packages/core/workspace/mutations.ts:7-21` 的 `useCreateWorkspace.onSuccess` 里调了 `switchWorkspace(newWs)` —— 同步改 Zustand，`/issues` 路由开始用新 workspace 渲染
-- `packages/views/modals/create-workspace.tsx:68-70` 的 UI `onSuccess` 里调了 `router.push("/onboarding")` —— 异步 schedule 导航
-
-于是：`/issues` 先渲染（闪一下）→ 导航到 `/onboarding`。
-
-**修复**：把 `switchWorkspace` 从 mutation 里拿出来，让 UI 层主导。在 `create-workspace.tsx` 的 `onSuccess` 里先 `switchWorkspace` 再 `push`，保证同一个微任务里完成。
-
-**文件**：`packages/core/workspace/mutations.ts`、`packages/views/modals/create-workspace.tsx`、可能 `packages/views/onboarding/step-workspace.tsx`
-
-### 4.2 MUL-728 — 删除 workspace 的"缺少确认"
-
-**核查结果**：`packages/views/settings/components/workspace-tab.tsx:102-119, 236-255` **已经有 AlertDialog 确认**了。
-
-**真实问题**：删除成功后**没有导航**，用户停在 `/settings`，而当前 workspace 已经是删除后系统挑的另一个。
-
-**修复**：在 `handleDeleteWorkspace` 的 `onConfirm` 成功分支里加 `push("/issues")`。
-
-**文件**：`packages/views/settings/components/workspace-tab.tsx`（加一行）
-
-### 4.3 MUL-820 — 接受邀请不自动切换 workspace
-
-**核查结果**：有两条路径：
-
-- ✅ `/invite/:id` 独立页（`packages/views/invite/invite-page.tsx:32-52`）是**正确的**：accept → switchWorkspace → push("/issues")
-- ❌ **Sidebar 下拉里的 "Join" 按钮**（`packages/views/layout/app-sidebar.tsx:203-209, 321-324`）**是错的**：只 invalidate cache，不切也不跳
-
-**修复（推荐 Option 2）**：Sidebar 的 "Join" 改成跳转到 `/invite/:id` 页面，不再就地接受。单一入口、单一行为。
-
-```tsx
-<DropdownMenuItem onClick={() => push(`/invite/${inv.id}`)}>
-  {inv.workspace_name}
-</DropdownMenuItem>
-```
-
-**文件**：`packages/views/layout/app-sidebar.tsx`（~10 行）
-
-### 复现
-
-| Issue | 步骤 |
-|---|---|
-| MUL-727 | 创建新 workspace → 仔细看是否闪了一下 `/issues` 再跳 `/onboarding` |
-| MUL-728 | 删除当前 workspace → 观察删完后是否留在 `/settings` 页面（BUG: 没有自动跳走） |
-| MUL-820 | 被邀请用户登录 → sidebar 下拉 → 点 "Join" → 观察当前 workspace 是否切过去（BUG: 不切）|
-
-### 长期架构建议（可选）
-
-抽一个 `useWorkspaceLifecycle` hook 统一管这些副作用。Agent 报告里有完整设计，文件：`packages/core/workspace/hooks.ts`（新建）。但建议先修 MUL-727/728/820 三个具体 bug，hook 抽象作为后续迭代。
-
-### 改动范围
-
-| Issue | 文件 | 改动规模 |
-|---|---|---|
-| MUL-727 | mutations.ts + create-workspace.tsx | ~10 行 |
-| MUL-728 | workspace-tab.tsx | ~1 行 |
-| MUL-820 | app-sidebar.tsx | ~10 行 |
-
----
-
-## 总览
-
-| 任务 | Issue | 优先级 | 预估规模 | 风险 |
-|---|---|---|---|---|
-| 1. WS 半开 + 陈旧 cache | #951 | **P0** | Option B ~10 行；Option C ~1-2 天 | 低 |
-| 2. Workspace URL 化 | MUL-723/43/509 | P1 | 5-7 人天（大部分是搬迁）| 中（影响面大、e2e 要改）|
-| 3. Navigation store 隔离 | MUL-43/476 | P1 | ~0.5 天 | 低 |
-| 4. Workspace 生命周期 bug | MUL-727/728/820 | P2 | ~1 天 | 低 |
-
-### 建议推进顺序
-
-1. **立刻做**：任务 1 的 Option B（visibilitychange 触发 invalidate）—— 代码最少、收益最明显，能当天止血
-2. **同步开始**：任务 3（navigation store 隔离）—— 影响小、风险低、顺便清掉一个 workaround
-3. **规划立项**：任务 2（URL 化）—— 大改造，需要单独开一个 iteration
-4. **次要修补**：任务 4 的三个小 bug —— 可以拆成独立 PR，各自 review
-
-### 重要澄清
-
-- **Issue 编号核对**：MUL-43 / MUL-476 的编号需要核对一次，agent 查询 GitHub 返回的标题看起来对不上（可能是内部 issue tracker 编号 vs GitHub 编号混用）。以症状为准。
-- **MUL-728 实际状态**：确认对话框已经存在，真实缺的是"删除后跳走"。
-- **MUL-820 实际状态**：`/invite/:id` 页面路径工作正常，只是 sidebar 下拉按钮坏了。
-
-### 所有关键代码位置索引
-
-```
-packages/core/query-client.ts:7-10          # staleTime: Infinity
-packages/core/api/ws-client.ts:1-142        # 客户端 WS，无心跳
-packages/core/realtime/use-realtime-sync.ts:462-487  # onReconnect 全量 invalidate
-packages/core/platform/core-provider.tsx    # 加 visibilitychange 的位置
-packages/core/navigation/store.ts:15-31     # lastPath 未隔离
-packages/core/platform/storage-cleanup.ts:10-19  # WORKSPACE_SCOPED_KEYS
-packages/core/workspace/store.ts:43-77      # hydrateWorkspace / switchWorkspace
-packages/core/workspace/mutations.ts:7-57   # create/leave/delete 三个 mutation
-packages/views/layout/app-sidebar.tsx:203-324  # 侧边栏切 workspace、接受邀请入口
-packages/views/modals/create-workspace.tsx:63-82  # 创建 workspace 入口
-packages/views/settings/components/workspace-tab.tsx:102-119  # 删除 workspace 入口
-packages/views/invite/invite-page.tsx:32-52 # 接受邀请正确实现参考
-
-server/internal/realtime/hub.go:83-96       # 服务端 WS 心跳
-server/internal/middleware/workspace.go:41-46  # wsId resolution
-server/migrations/001_init.up.sql:15-23     # workspace.slug 已存在
-```

LICENSE

@@ -1,44 +1,199 @@
-# Open Source License
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Multica is licensed under a modified version of the Apache License 2.0, with the following additional conditions:
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-1. Multica may be utilized commercially, including as a backend service for
-   other applications or as a task management platform for enterprises.
-   Should the conditions below be met, a commercial license must be obtained
-   from the producer:
+   1. Definitions.
 
-   a. Hosted or embedded service: Unless explicitly authorized by Multica
-      in writing, you may not use the Multica source code to provide a
-      hosted service to third parties, or embed Multica as a component of
-      a product or service that is sold, licensed, or otherwise
-      commercially distributed to third parties.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
 
-      - This restriction applies to offering Multica (in whole or
-        substantial part) as a SaaS platform, a managed service, or as
-        an integrated component within another commercial offering.
-      - Internal use within a single organization (including multiple
-        workspaces) does not require a commercial license.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
 
-   b. LOGO and copyright information: In the process of using Multica's
-      frontend, you may not remove or modify the LOGO or copyright
-      information in the Multica console or applications. This restriction
-      is inapplicable to uses of Multica that do not involve its frontend.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
 
-      - Frontend Definition: For the purposes of this license, the
-        "frontend" of Multica includes all components located in the
-        `apps/web/` directory when running Multica from the raw source
-        code, or the "web" image when running Multica with Docker.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
 
-2. As a contributor, you should agree that:
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
 
-   a. The producer can adjust the open-source agreement to be more strict
-      or relaxed as deemed necessary.
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
 
-   b. Your contributed code may be used for commercial purposes, including
-      but not limited to its cloud business operations.
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
-Apart from the specific conditions mentioned above, all other rights and
-restrictions follow the Apache License 2.0. Detailed information about the
-Apache License 2.0 can be found at http://www.apache.org/licenses/LICENSE-2.0.
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
 
-© 2025 Multica, Inc.
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. Please also get an
+      "Implied Patent License" from your patent counsel.
+
+   Copyright 2025 Multica
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help makehelp dev server daemon cli multica build test migrate-up migrate-down sqlc seed clean setup start stop check worktree-env setup-main start-main stop-main check-main setup-worktree start-worktree stop-worktree check-worktree db-up db-down db-reset selfhost selfhost-build selfhost-stop
+.PHONY: dev daemon cli multica build test migrate-up migrate-down sqlc seed clean setup start stop check worktree-env setup-main start-main stop-main check-main setup-worktree start-worktree stop-worktree check-worktree db-up db-down
 
 MAIN_ENV_FILE ?= .env
 WORKTREE_ENV_FILE ?= .env.worktree
@@ -36,123 +36,10 @@ define REQUIRE_ENV
 	fi
 endef
 
-# Default target changed from selfhost to help: bare `make` now prints this help
-# instead of launching a full Docker Compose build, which is safer for onboarding.
-.DEFAULT_GOAL := help
-
-##@ Help
-
-help: ## Show available make targets and common local workflows
-	@awk 'BEGIN {FS = ":.*## "; printf "\nUsage:\n  make \033[36m<target>\033[0m\n\nQuick start:\n  \033[36mmake dev\033[0m          Bootstrap the current checkout and start everything\n  \033[36mmake check\033[0m        Run the full local verification pipeline\n\nCheckout modes:\n  Main checkout uses \033[36m.env\033[0m\n  Worktrees use \033[36m.env.worktree\033[0m (generate with \033[36mmake worktree-env\033[0m)\n\n"} \
-		/^##@/ {printf "\n\033[1m%s\033[0m\n", substr($$0, 5); next} \
-		/^[a-zA-Z0-9_.-]+:.*## / {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
-
-makehelp: help ## Alias for `make help`
-
-# ---------- Self-hosting (Docker Compose) ----------
-##@ Self-hosting
-
-selfhost: ## Create .env if needed, then pull and start the official self-hosted images
-	@if [ ! -f .env ]; then \
-		echo "==> Creating .env from .env.example..."; \
-		cp .env.example .env; \
-		JWT=$$(openssl rand -hex 32); \
-		if [ "$$(uname)" = "Darwin" ]; then \
-			sed -i '' "s/^JWT_SECRET=.*/JWT_SECRET=$$JWT/" .env; \
-		else \
-			sed -i "s/^JWT_SECRET=.*/JWT_SECRET=$$JWT/" .env; \
-		fi; \
-		echo "==> Generated random JWT_SECRET"; \
-	fi
-	@echo "==> Pulling official Multica images..."
-	@if ! docker compose -f docker-compose.selfhost.yml pull; then \
-		echo ""; \
-		echo "Official images for tag '$${MULTICA_IMAGE_TAG:-latest}' are not published yet."; \
-		echo "If this is before the first GHCR release, build from the current checkout:"; \
-		echo "  make selfhost-build"; \
-		exit 1; \
-	fi
-	@echo "==> Starting Multica via Docker Compose..."
-	docker compose -f docker-compose.selfhost.yml up -d
-	@echo "==> Waiting for backend to be ready..."
-	@for i in $$(seq 1 30); do \
-		if curl -sf http://localhost:$${PORT:-8080}/health > /dev/null 2>&1; then \
-			break; \
-		fi; \
-		sleep 2; \
-	done
-	@if curl -sf http://localhost:$${PORT:-8080}/health > /dev/null 2>&1; then \
-		echo ""; \
-		echo "✓ Multica is running!"; \
-		echo "  Frontend: http://localhost:$${FRONTEND_PORT:-3000}"; \
-		echo "  Backend:  http://localhost:$${PORT:-8080}"; \
-		echo ""; \
-		echo "Images: $${MULTICA_BACKEND_IMAGE:-ghcr.io/multica-ai/multica-backend}:$${MULTICA_IMAGE_TAG:-latest}"; \
-		echo "        $${MULTICA_WEB_IMAGE:-ghcr.io/multica-ai/multica-web}:$${MULTICA_IMAGE_TAG:-latest}"; \
-		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 ""; \
-		echo "Next — install the CLI and connect your machine:"; \
-		echo "  brew install multica-ai/tap/multica"; \
-		echo "  multica setup self-host"; \
-	else \
-		echo ""; \
-		echo "Services are still starting. Check logs:"; \
-		echo "  docker compose -f docker-compose.selfhost.yml logs"; \
-	fi
-
-selfhost-build: ## Build backend/web from the current checkout and start the self-hosted stack
-	@if [ ! -f .env ]; then \
-		echo "==> Creating .env from .env.example..."; \
-		cp .env.example .env; \
-		JWT=$$(openssl rand -hex 32); \
-		if [ "$$(uname)" = "Darwin" ]; then \
-			sed -i '' "s/^JWT_SECRET=.*/JWT_SECRET=$$JWT/" .env; \
-		else \
-			sed -i "s/^JWT_SECRET=.*/JWT_SECRET=$$JWT/" .env; \
-		fi; \
-		echo "==> Generated random JWT_SECRET"; \
-	fi
-	@echo "==> Building Multica from the current checkout..."
-	docker compose -f docker-compose.selfhost.yml -f docker-compose.selfhost.build.yml up -d --build
-	@echo "==> Waiting for backend to be ready..."
-	@for i in $$(seq 1 30); do \
-		if curl -sf http://localhost:$${PORT:-8080}/health > /dev/null 2>&1; then \
-			break; \
-		fi; \
-		sleep 2; \
-	done
-	@if curl -sf http://localhost:$${PORT:-8080}/health > /dev/null 2>&1; then \
-		echo ""; \
-		echo "✓ Multica is running!"; \
-		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 ""; \
-		echo "Built images locally via docker-compose.selfhost.build.yml."; \
-		echo "Local tags: multica-backend:dev and multica-web:dev."; \
-		echo ""; \
-		echo "Next — install the CLI and connect your machine:"; \
-		echo "  brew install multica-ai/tap/multica"; \
-		echo "  multica setup self-host"; \
-	else \
-		echo ""; \
-		echo "Services are still starting. Check logs:"; \
-		echo "  docker compose -f docker-compose.selfhost.yml logs"; \
-	fi
-
-selfhost-stop: ## Stop the self-hosted Docker Compose stack
-	@echo "==> Stopping Multica services..."
-	docker compose -f docker-compose.selfhost.yml down
-	@echo "✓ All services stopped."
-
 # ---------- One-click commands ----------
-##@ One-click
 
-setup: ## Prepare the current checkout from its env file: install deps, ensure DB, run migrations
+# First-time setup: install deps, start DB, run migrations
+setup:
 	$(REQUIRE_ENV)
 	@echo "==> Using env file: $(ENV_FILE)"
 	@echo "==> Installing dependencies..."
@@ -163,78 +50,54 @@ setup: ## Prepare the current checkout from its env file: install deps, ensure D
 	@echo ""
 	@echo "✓ Setup complete! Run 'make start' to launch the app."
 
-start: ## Start backend and frontend for the current checkout and run migrations first
+# Start all services (backend + frontend)
+start:
 	$(REQUIRE_ENV)
 	@echo "Using env file: $(ENV_FILE)"
 	@echo "Backend: http://localhost:$(PORT)"
 	@echo "Frontend: http://localhost:$(FRONTEND_PORT)"
 	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
-	@echo "Running migrations..."
-	cd server && go run ./cmd/migrate up
 	@echo "Starting backend and frontend..."
 	@trap 'kill 0' EXIT; \
 		(cd server && go run ./cmd/server) & \
 		pnpm dev:web & \
 		wait
 
-stop: ## Stop backend and frontend processes for the current checkout
+# Stop all services
+stop:
 	$(REQUIRE_ENV)
 	@echo "Stopping services..."
 	@-lsof -ti:$(PORT) | xargs kill -9 2>/dev/null
 	@-lsof -ti:$(FRONTEND_PORT) | xargs kill -9 2>/dev/null
-	@case "$(DATABASE_URL)" in \
-		""|*@localhost:*|*@localhost/*|*@127.0.0.1:*|*@127.0.0.1/*|*@\[::1\]:*|*@\[::1\]/*) \
-			echo "✓ App processes stopped. Shared PostgreSQL is still running on localhost:$(POSTGRES_PORT)." ;; \
-		*) \
-			echo "✓ App processes stopped. Remote PostgreSQL was not affected." ;; \
-	esac
+	@echo "✓ App processes stopped. Shared PostgreSQL is still running on localhost:5432."
 
-check: ## Run typecheck, TS tests, Go tests, and Playwright E2E for the current checkout
+# Full verification: typecheck + unit tests + Go tests + E2E
+check:
 	$(REQUIRE_ENV)
 	@ENV_FILE="$(ENV_FILE)" bash scripts/check.sh
 
-db-up: ## Start the shared PostgreSQL container used by main and worktrees
+db-up:
 	@$(COMPOSE) up -d postgres
 
-db-down: ## Stop the shared PostgreSQL container without removing its Docker volume
+db-down:
 	@$(COMPOSE) down
 
-# Drop + recreate the current env's database, then run all migrations.
-# Use for a clean slate in local dev. Only affects the DB named in
-# ENV_FILE (POSTGRES_DB); the shared postgres container and other
-# worktree DBs are untouched. Refuses to run against a remote host.
-db-reset: ## Drop and recreate the current env's database, then re-run all migrations
-	$(REQUIRE_ENV)
-	@case "$(DATABASE_URL)" in \
-		""|*@localhost:*|*@localhost/*|*@127.0.0.1:*|*@127.0.0.1/*|*@\[::1\]:*|*@\[::1\]/*) ;; \
-		*) echo "Refusing to reset: DATABASE_URL points at a remote host."; exit 1 ;; \
-	esac
-	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
-	@echo "==> Dropping and recreating database '$(POSTGRES_DB)'..."
-	@$(COMPOSE) exec -T postgres psql -U $(POSTGRES_USER) -d postgres -v ON_ERROR_STOP=1 \
-		-c "DROP DATABASE IF EXISTS \"$(POSTGRES_DB)\" WITH (FORCE);" \
-		-c "CREATE DATABASE \"$(POSTGRES_DB)\";"
-	@echo "==> Running migrations..."
-	cd server && go run ./cmd/migrate up
-	@echo ""
-	@echo "✓ Database '$(POSTGRES_DB)' reset. Run 'make start' to launch the app."
-
-worktree-env: ## Generate .env.worktree with a unique DB name and app ports for this worktree
+worktree-env:
 	@bash scripts/init-worktree-env.sh .env.worktree
 
-setup-main: ## Prepare the main checkout using .env
+setup-main:
 	@$(MAKE) setup ENV_FILE=$(MAIN_ENV_FILE)
 
-start-main: ## Start the main checkout using .env
+start-main:
 	@$(MAKE) start ENV_FILE=$(MAIN_ENV_FILE)
 
-stop-main: ## Stop the main checkout processes defined by .env
+stop-main:
 	@$(MAKE) stop ENV_FILE=$(MAIN_ENV_FILE)
 
-check-main: ## Run the full verification pipeline for the main checkout
+check-main:
 	@ENV_FILE=$(MAIN_ENV_FILE) bash scripts/check.sh
 
-setup-worktree: ## Ensure .env.worktree exists, then prepare this worktree
+setup-worktree:
 	@if [ ! -f "$(WORKTREE_ENV_FILE)" ]; then \
 		echo "==> Generating $(WORKTREE_ENV_FILE) with unique ports..."; \
 		bash scripts/init-worktree-env.sh $(WORKTREE_ENV_FILE); \
@@ -243,68 +106,58 @@ setup-worktree: ## Ensure .env.worktree exists, then prepare this worktree
 	fi
 	@$(MAKE) setup ENV_FILE=$(WORKTREE_ENV_FILE)
 
-start-worktree: ## Start this worktree using .env.worktree
+start-worktree:
 	@$(MAKE) start ENV_FILE=$(WORKTREE_ENV_FILE)
 
-stop-worktree: ## Stop this worktree's backend and frontend processes
+stop-worktree:
 	@$(MAKE) stop ENV_FILE=$(WORKTREE_ENV_FILE)
 
-check-worktree: ## Run the full verification pipeline for this worktree
+check-worktree:
 	@ENV_FILE=$(WORKTREE_ENV_FILE) bash scripts/check.sh
 
 # ---------- Individual commands ----------
-##@ Individual commands
 
-dev: ## Bootstrap this checkout end-to-end: create env if needed, ensure DB, migrate, start services
-	@bash scripts/dev.sh
-
-server: ## Run only the Go server for the current checkout
+# Go server
+dev:
 	$(REQUIRE_ENV)
 	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
 	cd server && go run ./cmd/server
 
-daemon: ## Restart the local agent daemon using the CLI's stored auth/session
-	@$(MAKE) multica MULTICA_ARGS="daemon restart --profile local"
+daemon:
+	@$(MAKE) multica MULTICA_ARGS="daemon"
 
-cli: ## Run the multica CLI with ARGS or MULTICA_ARGS from source
+cli:
 	@$(MAKE) multica MULTICA_ARGS="$(MULTICA_ARGS)"
 
-multica: ## Run the multica CLI entrypoint directly from the Go source tree
+multica:
 	cd server && go run ./cmd/multica $(MULTICA_ARGS)
 
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
 COMMIT  ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
-DATE    ?= $(shell date -u '+%Y-%m-%dT%H:%M:%SZ')
 
-build: ## Build the server, CLI, and migrate binaries into server/bin
+build:
 	cd server && go build -o bin/server ./cmd/server
-	cd server && go build -ldflags "-X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(DATE)" -o bin/multica ./cmd/multica
-	cd server && go build -o bin/migrate ./cmd/migrate
+	cd server && go build -ldflags "-X main.version=$(VERSION) -X main.commit=$(COMMIT)" -o bin/multica ./cmd/multica
 
-test: ## Run Go tests after ensuring the target DB exists and migrations are applied
+test:
 	$(REQUIRE_ENV)
 	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
-	cd server && go run ./cmd/migrate up
 	cd server && go test ./...
 
 # Database
-##@ Database
-
-migrate-up: ## Create the target DB if needed, then apply database migrations
+migrate-up:
 	$(REQUIRE_ENV)
 	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
 	cd server && go run ./cmd/migrate up
 
-migrate-down: ## Create the target DB if needed, then roll back database migrations
+migrate-down:
 	$(REQUIRE_ENV)
 	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
 	cd server && go run ./cmd/migrate down
 
-sqlc: ## Regenerate sqlc code
+sqlc:
 	cd server && sqlc generate
 
 # Cleanup
-##@ Cleanup
-
-clean: ## Remove generated server binaries and temp files
+clean:
 	rm -rf server/bin server/tmp

README.md

@@ -14,13 +14,14 @@
 
 **Your next 10 hires won't be human.**
 
-The open-source managed agents platform.<br/>
-Turn coding agents into real teammates — assign tasks, track progress, compound skills.
+Open-source platform that turns coding agents into real teammates.<br/>
+Assign tasks, track progress, compound skills — manage your human + agent workforce in one place.
 
 [![CI](https://github.com/multica-ai/multica/actions/workflows/ci.yml/badge.svg)](https://github.com/multica-ai/multica/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![GitHub stars](https://img.shields.io/github/stars/multica-ai/multica?style=flat)](https://github.com/multica-ai/multica/stargazers)
 
-[Website](https://multica.ai) · [Cloud](https://multica.ai/app) · [X](https://x.com/MulticaAI) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
+[Website](https://multica.ai) · [Cloud](https://multica.ai/app) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
 
 **English | [简体中文](README.zh-CN.md)**
 
@@ -30,7 +31,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. Works with **Claude Code** and **Codex**.
 
 <p align="center">
   <img src="docs/assets/hero-screenshot.png" alt="Multica board view" width="800">
@@ -38,67 +39,63 @@ No more copy-pasting prompts. No more babysitting runs. Your agents show up on t
 
 ## Features
 
-Multica manages the full agent lifecycle: from task assignment to execution monitoring to skill reuse.
-
 - **Agents as Teammates** — assign to an agent like you'd assign to a colleague. They have profiles, show up on the board, post comments, create issues, and report blockers proactively.
 - **Autonomous Execution** — set it and forget it. Full task lifecycle management (enqueue, claim, start, complete/fail) with real-time progress streaming via WebSocket.
 - **Reusable Skills** — every solution becomes a reusable skill for the whole team. Deployments, migrations, code reviews — skills compound your team's capabilities over time.
 - **Unified Runtimes** — one dashboard for all your compute. Local daemons and cloud runtimes, auto-detection of available CLIs, real-time monitoring.
 - **Multi-Workspace** — organize work across teams with workspace-level isolation. Each workspace has its own agents, issues, and settings.
 
----
-
-## Quick Install
-
-### macOS / Linux (Homebrew - recommended)
-
-```bash
-brew install multica-ai/tap/multica
-```
-
-Use `brew upgrade multica-ai/tap/multica` to keep the CLI current.
-
-### macOS / Linux (install script)
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
-```
-
-Use this if Homebrew is not available. The script installs the Multica CLI on macOS and Linux by using Homebrew when it is on `PATH`, otherwise it downloads the binary directly.
-
-### Windows (PowerShell)
-
-```powershell
-irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex
-```
-
-Then configure, authenticate, and start the daemon in one command:
-
-```bash
-multica setup          # Connect to Multica Cloud, log in, start daemon
-```
-
-> **Self-hosting?** Add `--with-server` to deploy a full Multica server on your machine:
->
-> ```bash
-> curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server
-> multica setup self-host
-> ```
->
-> This pulls the official Multica images from GHCR (latest stable by default). Requires Docker. See the [Self-Hosting Guide](SELF_HOSTING.md) for details.
-> If the selected GHCR tag has not been published yet, fall back to `make selfhost-build` from a checkout.
-
----
-
 ## Getting Started
 
-### 1. Set up and start the daemon
+### Multica Cloud
+
+The fastest way to get started — no setup required: **[multica.ai](https://multica.ai)**
+
+### Self-Host with Docker
 
 ```bash
-multica setup           # Configure, authenticate, and start the daemon
+git clone https://github.com/multica-ai/multica.git
+cd multica
+cp .env.example .env
+# Edit .env — at minimum, change JWT_SECRET
+
+docker compose up -d                              # Start PostgreSQL
+cd server && go run ./cmd/migrate up && cd ..     # Run migrations
+make start                                         # Start the app
 ```
 
-The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `openclaw`, `opencode`, `hermes`, `gemini`, `pi`, `cursor-agent`) on your PATH.
+See the [Self-Hosting Guide](SELF_HOSTING.md) for full instructions.
+
+## CLI
+
+The `multica` CLI connects your local machine to Multica — authenticate, manage workspaces, and run the agent daemon.
+
+```bash
+# Install
+brew tap multica-ai/tap
+brew install multica
+
+# Authenticate and start
+multica login
+multica daemon start
+```
+
+The daemon auto-detects available agent CLIs (`claude`, `codex`) on your PATH. When an agent is assigned a task, the daemon creates an isolated environment, runs the agent, and reports results back.
+
+See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference, daemon configuration, and advanced usage.
+
+## Quickstart
+
+Once you have the CLI installed (or signed up for [Multica Cloud](https://multica.ai)), follow these steps to assign your first task to an agent:
+
+### 1. Log in and start the daemon
+
+```bash
+multica login           # Authenticate with your Multica account
+multica daemon start    # Start the local agent runtime
+```
+
+The daemon runs in the background and keeps your machine connected to Multica. It auto-detects agent CLIs (`claude`, `codex`) available on your PATH.
 
 ### 2. Verify your runtime
 
@@ -108,47 +105,13 @@ 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 or Codex). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
 
 ### 4. Assign your first task
 
 Create an issue from the board (or via `multica issue create`), then assign it to your new agent. The agent will automatically pick up the task, execute it on your runtime, and report progress — just like a human teammate.
 
----
-
-## Multica vs Paperclip
-
-| | Multica | Paperclip |
-|---|---------|-----------|
-| **Focus** | Team AI agent collaboration platform | Solo AI agent company simulator |
-| **User model** | Multi-user teams with roles & permissions | Single board operator |
-| **Agent interaction** | Issues + Chat conversations | Issues + Heartbeat |
-| **Deployment** | Cloud-first | Local-first |
-| **Management depth** | Lightweight (Issues / Projects / Labels) | Heavy governance (Org chart / Approvals / Budgets) |
-| **Extensibility** | Skills system | Skills + Plugin system |
-
-**TL;DR — Multica is built for teams that want to collaborate with AI agents on real projects together.**
-
----
-
-## CLI
-
-The `multica` CLI connects your local machine to Multica — authenticate, manage workspaces, and run the agent daemon.
-
-| Command | Description |
-|---------|-------------|
-| `multica login` | Authenticate (opens browser) |
-| `multica daemon start` | Start the local agent runtime |
-| `multica daemon status` | Check daemon status |
-| `multica setup` | One-command setup for Multica Cloud (configure + login + start daemon) |
-| `multica setup self-host` | Same, but for self-hosted deployments |
-| `multica issue list` | List issues in your workspace |
-| `multica issue create` | Create a new issue |
-| `multica update` | Update to the latest version |
-
-See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference.
-
----
+That's it! Your agent is now part of the team. 🎉
 
 ## Architecture
 
@@ -159,10 +122,9 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
 └──────────────┘     └──────┬───────┘     └──────────────────┘
                             │
                      ┌──────┴───────┐
-                     │ Agent Daemon │  runs on your machine
-                     └──────────────┘  (Claude Code, Codex, OpenCode,
-                                        OpenClaw, Hermes, Gemini,
-                                        Pi, Cursor Agent)
+                     │ Agent Daemon │  (runs on your machine)
+                     │ Claude/Codex │
+                     └──────────────┘
 ```
 
 | Layer | Stack |
@@ -170,7 +132,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 or Codex |
 
 ## Development
 
@@ -179,19 +141,14 @@ For contributors working on the Multica codebase, see the [Contributing Guide](C
 **Prerequisites:** [Node.js](https://nodejs.org/) v20+, [pnpm](https://pnpm.io/) v10.28+, [Go](https://go.dev/) v1.26+, [Docker](https://www.docker.com/)
 
 ```bash
-make dev
+pnpm install
+cp .env.example .env
+make setup
+make start
 ```
 
-`make dev` auto-detects your environment (main checkout or worktree), creates the env file, installs dependencies, sets up the database, runs migrations, and starts all services.
-
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, worktree support, testing, and troubleshooting.
 
-## Star History
+## License
 
-<a href="https://www.star-history.com/?repos=multica-ai%2Fmultica&type=date&legend=bottom-right">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=multica-ai/multica&type=date&legend=top-left" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=multica-ai/multica&type=date&legend=top-left" />
-    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=multica-ai/multica&type=date&legend=top-left" />
-  </picture>
-</a>
+[Apache 2.0](LICENSE)

README.zh-CN.md

@@ -14,13 +14,14 @@
 
 **你的下一批员工，不是人类。**
 
-开源的 Managed Agents 平台。<br/>
-将编码 Agent 变成真正的队友——分配任务、跟踪进度、积累技能。
+开源平台，将编码 Agent 变成真正的队友。<br/>
+分配任务、跟踪进度、积累技能——在一个地方管理你的人类 + Agent 团队。
 
 [![CI](https://github.com/multica-ai/multica/actions/workflows/ci.yml/badge.svg)](https://github.com/multica-ai/multica/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![GitHub stars](https://img.shields.io/github/stars/multica-ai/multica?style=flat)](https://github.com/multica-ai/multica/stargazers)
 
-[官网](https://multica.ai) · [云服务](https://multica.ai/app) · [X](https://x.com/MulticaAI) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
+[官网](https://multica.ai) · [云服务](https://multica.ai/app) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
 
 **[English](README.md) | 简体中文**
 
@@ -30,7 +31,7 @@
 
 Multica 将编码 Agent 变成真正的队友。像分配给同事一样分配给 Agent——它们会自主接手工作、编写代码、报告阻塞问题、更新状态。
 
-不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**OpenClaw**、**OpenCode**、**Hermes**、**Gemini**、**Pi** 和 **Cursor Agent**。
+不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。支持 **Claude Code** 和 **Codex**。
 
 <p align="center">
   <img src="docs/assets/hero-screenshot.png" alt="Multica 看板视图" width="800">
@@ -38,68 +39,63 @@ Multica 将编码 Agent 变成真正的队友。像分配给同事一样分配
 
 ## 功能特性
 
-Multica 管理完整的 Agent 生命周期：从任务分配到执行监控再到技能复用。
-
 - **Agent 即队友** — 像分配给同事一样分配给 Agent。它们有个人档案、出现在看板上、发表评论、创建 Issue、主动报告阻塞问题。
 - **自主执行** — 设置后无需管理。完整的任务生命周期管理（排队、认领、执行、完成/失败），通过 WebSocket 实时推送进度。
 - **可复用技能** — 每个解决方案都成为全团队可复用的技能。部署、数据库迁移、代码审查——技能让团队能力随时间持续增长。
 - **统一运行时** — 一个控制台管理所有算力。本地 daemon 和云端运行时，自动检测可用 CLI，实时监控。
 - **多工作区** — 按团队组织工作，工作区级别隔离。每个工作区有独立的 Agent、Issue 和设置。
 
----
+## 快速开始
 
-## 快速安装
+### Multica 云服务
 
-### macOS / Linux（推荐 Homebrew）
+最快的上手方式，无需任何配置：**[multica.ai](https://multica.ai)**
+
+### Docker 自部署
 
 ```bash
-brew install multica-ai/tap/multica
+git clone https://github.com/multica-ai/multica.git
+cd multica
+cp .env.example .env
+# 编辑 .env — 至少修改 JWT_SECRET
+
+docker compose up -d                              # 启动 PostgreSQL
+cd server && go run ./cmd/migrate up && cd ..     # 运行数据库迁移
+make start                                         # 启动应用
 ```
 
-后续可用 `brew upgrade multica-ai/tap/multica` 更新 CLI。
+完整部署文档请参阅 [自部署指南](SELF_HOSTING.md)。
 
-### macOS / Linux（安装脚本）
+## CLI
+
+`multica` CLI 将你的本地机器连接到 Multica — 用于认证、管理工作区和运行 Agent daemon。
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
+# 安装
+brew tap multica-ai/tap
+brew install multica
+
+# 认证并启动
+multica login
+multica daemon start
 ```
 
-如果没有 Homebrew，可以使用安装脚本。脚本会安装 Multica CLI：检测到 `brew` 时通过 Homebrew 安装，否则直接下载二进制。
+daemon 会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`）。当 Agent 被分配任务时，daemon 会创建隔离环境、运行 Agent、并将结果回传。
 
-### Windows (PowerShell)
-
-```powershell
-irm https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.ps1 | iex
-```
-
-安装完成后，一条命令完成配置、认证和启动：
-
-```bash
-multica setup          # 连接 Multica Cloud，登录，启动 daemon
-```
-
-> **自部署？** 加上 `--with-server` 在本地部署完整的 Multica 服务：
->
-> ```bash
-> curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server
-> multica setup self-host
-> ```
->
-> 需要 Docker。详见 [自部署指南](SELF_HOSTING.md)。
-
----
+完整命令参考请参阅 [CLI 与 Daemon 指南](CLI_AND_DAEMON.md)。
 
 ## 快速上手
 
 安装好 CLI（或注册 [Multica 云服务](https://multica.ai)）后，按以下步骤将第一个任务分配给 Agent：
 
-### 1. 配置并启动 daemon
+### 1. 登录并启动 daemon
 
 ```bash
-multica setup           # 配置、认证、启动 daemon（一条命令搞定）
+multica login           # 使用你的 Multica 账号认证
+multica daemon start    # 启动本地 Agent 运行时
 ```
 
-daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`openclaw`、`opencode`、`hermes`、`gemini`、`pi`、`cursor-agent`）。
+daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`）。
 
 ### 2. 确认运行时已连接
 
@@ -109,7 +105,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），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
 
 ### 4. 分配你的第一个任务
 
@@ -117,21 +113,6 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 
 大功告成！你的 Agent 现在是团队的一员了。 🎉
 
----
-
-## Multica vs Paperclip
-
-| | Multica | Paperclip |
-|---|---------|-----------|
-| **定位** | 团队 AI Agent 协作平台 | 个人 AI Agent 公司模拟器 |
-| **用户模型** | 多人团队，角色权限 | 单人 Board Operator |
-| **Agent 交互** | Issue + Chat 对话 | Issue + Heartbeat |
-| **部署** | 云端优先 | 本地优先 |
-| **管理深度** | 轻量（Issue / Project / Labels） | 重度（组织架构 / 审批 / 预算） |
-| **扩展** | Skills 系统 | Skills + 插件系统 |
-
-**简单来说：Multica 专为团队协作打造，让团队和 AI Agent 一起高效完成项目。**
-
 ## 架构
 
 ```
@@ -141,10 +122,9 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 └──────────────┘     └──────┬───────┘     └──────────────────┘
                             │
                      ┌──────┴───────┐
-                     │ Agent Daemon │  运行在你的机器上
-                     └──────────────┘  （Claude Code、Codex、OpenCode、
-                                        OpenClaw、Hermes、Gemini、
-                                        Pi、Cursor Agent）
+                     │ Agent Daemon │  （运行在你的机器上）
+                     │ Claude/Codex │
+                     └──────────────┘
 ```
 
 | 层级 | 技术栈 |
@@ -152,7 +132,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 |
 
 ## 开发
 
@@ -172,13 +152,3 @@ make start
 ## 开源协议
 
 [Apache 2.0](LICENSE)
-
-## Star History
-
-<a href="https://www.star-history.com/?repos=multica-ai%2Fmultica&type=date&legend=bottom-right">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=multica-ai/multica&type=date&legend=top-left" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=multica-ai/multica&type=date&legend=top-left" />
-    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=multica-ai/multica&type=date&legend=top-left" />
-  </picture>
-</a>

SELF_HOSTING.md

@@ -1,8 +1,10 @@
 # Self-Hosting Guide
 
-Deploy Multica on your own infrastructure in minutes.
+This guide walks you through deploying Multica on your own infrastructure.
 
-## Architecture
+## Architecture Overview
+
+Multica has three components:
 
 | Component | Description | Technology |
 |-----------|-------------|------------|
@@ -10,173 +12,16 @@ Deploy Multica on your own infrastructure in minutes.
 | **Frontend** | Web application | Next.js 16 |
 | **Database** | Primary data store | PostgreSQL 17 with pgvector |
 
-Each user who runs AI agents locally also installs the **`multica` CLI** and runs the **agent daemon** on their own machine.
+Additionally, each user who wants to run AI agents locally installs the **`multica` CLI** and runs the **agent daemon** on their own machine.
 
-## Quick Install (Recommended)
+## Prerequisites
 
-Two commands to set up everything — server, CLI, and configuration:
+- Docker and Docker Compose (recommended), or:
+  - Go 1.26+ (to build from source)
+  - Node.js 20+ and pnpm 10.28+ (to build the frontend)
+  - PostgreSQL 17 with the pgvector extension
 
-```bash
-# 1. Install CLI + provision the self-host server
-curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server
-
-# 2. Configure CLI, authenticate, and start the daemon
-multica setup self-host
-```
-
-This installs the `multica` CLI, checks out the latest self-host assets, pulls the official Multica images from GHCR, and configures everything 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.
-
-> **Prerequisites:** Docker and Docker Compose must be installed. The script checks for this and provides install links if missing.
->
-> **CLI only?** If the self-host server is already running and you only need the CLI on a macOS/Linux machine, install it with Homebrew:
->
-> ```bash
-> brew install multica-ai/tap/multica
-> ```
-
----
-
-## Step-by-Step Setup (Alternative)
-
-If you prefer to run each step manually:
-
-### Step 1 — Start the Server
-
-**Prerequisites:** Docker and Docker Compose.
-
-```bash
-git clone https://github.com/multica-ai/multica.git
-cd multica
-make selfhost
-```
-
-`make selfhost` automatically creates `.env` from the example, generates a random `JWT_SECRET`, and starts all services via Docker Compose.
-
-By default it pulls the latest stable release images from GHCR. To build the backend/web from your current checkout instead, run `make selfhost-build`.
-If the selected GHCR tag has not been published yet, `make selfhost` now tells you to fall back to `make selfhost-build`.
-`make selfhost-build` uses local `multica-backend:dev` / `multica-web:dev` tags, so it does not overwrite the pulled `:latest` images.
-
-Once ready:
-
-- **Frontend:** http://localhost:3000
-- **Backend API:** http://localhost:8080
-
-> **Note:** If you prefer to run the Docker Compose steps manually, see [Manual Docker Compose Setup](#manual-docker-compose-setup) below.
-
-### 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:
-
-- **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.
-
-Changes to `ALLOW_SIGNUP` and `GOOGLE_CLIENT_ID` also take effect after restarting the backend / compose stack. The web UI reads both from `/api/config` at runtime, so no web rebuild is needed.
-
-> **Warning:** do **not** set `APP_ENV=development` on a publicly reachable instance — anyone who knows an email address can then log in with `888888`.
-
-### Step 3 — Install CLI & Start Daemon
-
-The daemon runs on your local machine (not inside Docker). It detects installed AI agent CLIs, registers them with the server, and executes tasks when agents are assigned work.
-
-Each team member who wants to run AI agents locally needs to:
-
-### a) Install the CLI and an AI agent
-
-```bash
-brew install multica-ai/tap/multica
-```
-
-You also need at least one AI agent CLI installed:
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
-- [Codex](https://github.com/openai/codex) (`codex` on PATH)
-- [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
-
-```bash
-multica setup self-host
-```
-
-This automatically:
-1. Configures the CLI to connect to `localhost` (ports 8080/3000)
-2. Opens your browser for authentication
-3. Discovers your workspaces
-4. Starts the daemon in the background
-
-For on-premise deployments with custom domains:
-
-```bash
-multica setup self-host --server-url https://api.example.com --app-url https://app.example.com
-```
-
-To verify the daemon is running:
-
-```bash
-multica daemon status
-```
-
-> **Alternative:** If you prefer manual steps, see [Manual CLI Configuration](#manual-cli-configuration) below.
-
-### Step 4 — Verify & Start Using
-
-1. Open your workspace in the web app at http://localhost:3000
-2. Navigate to **Settings → Runtimes** — you should see your machine listed
-3. Go to **Settings → Agents** and create a new agent
-4. Create an issue and assign it to your agent — it will pick up the task automatically
-
-## Stopping Services
-
-If you installed via the install script:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --stop
-```
-
-If you cloned the repo manually:
-
-```bash
-# Stop the Docker Compose services (backend, frontend, database)
-make selfhost-stop
-
-# Stop the local daemon
-multica daemon stop
-```
-
-## Switching to Multica Cloud
-
-If you've been self-hosting and want to switch your CLI to [Multica Cloud](https://multica.ai):
-
-```bash
-multica setup
-```
-
-This reconfigures the CLI for multica.ai, re-authenticates, and restarts the daemon. You will be prompted before overwriting the existing configuration.
-
-> Your local Docker services are unaffected. Stop them separately if you no longer need them.
-
-## Upgrading
-
-```bash
-docker compose -f docker-compose.selfhost.yml pull
-docker compose -f docker-compose.selfhost.yml up -d
-```
-
-Pin `MULTICA_IMAGE_TAG` in `.env` to an exact version like `v0.2.4` if you want to stay on a specific release. Migrations run automatically on backend startup.
-If the selected GHCR tag has not been published yet, fall back to `make selfhost-build` or `docker compose -f docker-compose.selfhost.yml -f docker-compose.selfhost.build.yml up -d --build`.
-
----
-
-## Manual Docker Compose Setup
-
-If you prefer running Docker Compose steps manually instead of `make selfhost`:
+## Quick Start (Docker Compose)
 
 ```bash
 git clone https://github.com/multica-ai/multica.git
@@ -184,44 +29,250 @@ cd multica
 cp .env.example .env
 ```
 
-Edit `.env` — at minimum, change `JWT_SECRET`:
+Edit `.env` with your production values (see [Configuration](#configuration) below), then:
 
 ```bash
-JWT_SECRET=$(openssl rand -hex 32)
+# Start PostgreSQL
+docker compose up -d
+
+# Build the backend
+make build
+
+# Run database migrations
+DATABASE_URL="your-database-url" ./server/bin/migrate up
+
+# Start the backend server
+DATABASE_URL="your-database-url" PORT=8080 ./server/bin/server
 ```
 
-Then start everything:
+For the frontend:
 
 ```bash
-docker compose -f docker-compose.selfhost.yml pull
-docker compose -f docker-compose.selfhost.yml up -d
+pnpm install
+pnpm build
+
+# Start the frontend (production mode)
+cd apps/web
+REMOTE_API_URL=http://localhost:8080 pnpm start
 ```
 
-## Manual CLI Configuration
+## Configuration
 
-If you prefer configuring the CLI step by step instead of `multica setup`:
+All configuration is done via environment variables. Copy `.env.example` as a starting point.
+
+### Required Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `DATABASE_URL` | PostgreSQL connection string | `postgres://multica:multica@localhost:5432/multica?sslmode=disable` |
+| `JWT_SECRET` | **Must change from default.** Secret key for signing JWT tokens. Use a long random string. | `openssl rand -hex 32` |
+| `FRONTEND_ORIGIN` | URL where the frontend is served (used for CORS) | `https://app.example.com` |
+
+### Email (Required for Authentication)
+
+Multica uses email-based magic link authentication via [Resend](https://resend.com).
+
+| Variable | Description |
+|----------|-------------|
+| `RESEND_API_KEY` | Your Resend API key |
+| `RESEND_FROM_EMAIL` | Sender email address (default: `noreply@multica.ai`) |
+
+### Google OAuth (Optional)
+
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_CLIENT_ID` | Google OAuth client ID |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret |
+| `GOOGLE_REDIRECT_URI` | OAuth callback URL (e.g. `https://app.example.com/auth/callback`) |
+
+### File Storage (Optional)
+
+For file uploads and attachments, configure S3 and CloudFront:
+
+| Variable | Description |
+|----------|-------------|
+| `S3_BUCKET` | S3 bucket name |
+| `S3_REGION` | AWS region (default: `us-west-2`) |
+| `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
+| `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
+| `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
+| `COOKIE_DOMAIN` | Domain for CloudFront auth cookies |
+
+### Server
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `8080` | Backend server port |
+| `FRONTEND_PORT` | `3000` | Frontend port |
+| `CORS_ALLOWED_ORIGINS` | Value of `FRONTEND_ORIGIN` | Comma-separated list of allowed origins |
+| `LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
+
+### CLI / Daemon
+
+These are configured on each user's machine, not on the server:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MULTICA_SERVER_URL` | `ws://localhost:8080/ws` | WebSocket URL for daemon → server connection |
+| `MULTICA_APP_URL` | `http://localhost:3000` | Frontend URL for CLI login flow |
+| `MULTICA_DAEMON_POLL_INTERVAL` | `3s` | How often the daemon polls for tasks |
+| `MULTICA_DAEMON_HEARTBEAT_INTERVAL` | `15s` | Heartbeat frequency |
+
+## Database Setup
+
+Multica requires PostgreSQL 17 with the pgvector extension.
+
+### Using the Included Docker Compose
 
 ```bash
-# Point CLI to your local server
-multica config set server_url http://localhost:8080
-multica config set app_url http://localhost:3000
-
-# Login (opens browser)
-multica login
-
-# Start the daemon
-multica daemon start
+docker compose up -d postgres
 ```
 
-For production deployments with TLS:
+This starts a `pgvector/pgvector:pg17` container on port 5432 with default credentials (`multica`/`multica`).
+
+### Using Your Own PostgreSQL
+
+Ensure the pgvector extension is available:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+### Running Migrations
+
+Migrations must be run before starting the server:
 
 ```bash
-multica config set app_url https://app.example.com
-multica config set server_url https://api.example.com
-multica login
-multica daemon start
+# Using the built binary
+./server/bin/migrate up
+
+# Or from source
+cd server && go run ./cmd/migrate up
 ```
 
-## Advanced Configuration
+## Reverse Proxy
 
-For environment variables, manual setup (without Docker), reverse proxy configuration, database setup, and more, see the [Advanced Configuration Guide](SELF_HOSTING_ADVANCED.md).
+In production, put a reverse proxy in front of both the backend and frontend to handle TLS and routing.
+
+### Caddy (Recommended)
+
+```
+app.example.com {
+    reverse_proxy localhost:3000
+}
+
+api.example.com {
+    reverse_proxy localhost:8080
+}
+```
+
+### Nginx
+
+```nginx
+# Frontend
+server {
+    listen 443 ssl;
+    server_name app.example.com;
+
+    ssl_certificate     /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+
+# Backend API
+server {
+    listen 443 ssl;
+    server_name api.example.com;
+
+    ssl_certificate     /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # WebSocket support
+    location /ws {
+        proxy_pass http://localhost:8080;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 86400;
+    }
+}
+```
+
+When using separate domains for frontend and backend, set these environment variables accordingly:
+
+```bash
+# Backend
+FRONTEND_ORIGIN=https://app.example.com
+CORS_ALLOWED_ORIGINS=https://app.example.com
+
+# Frontend
+REMOTE_API_URL=https://api.example.com
+NEXT_PUBLIC_API_URL=https://api.example.com
+NEXT_PUBLIC_WS_URL=wss://api.example.com/ws
+```
+
+## Health Check
+
+The backend exposes a health check endpoint:
+
+```
+GET /health
+→ {"status":"ok"}
+```
+
+Use this for load balancer health checks or monitoring.
+
+## Setting Up the Agent Daemon
+
+Each team member who wants to run AI agents locally needs to:
+
+1. **Install the CLI**
+
+   ```bash
+   brew tap multica-ai/tap
+   brew install multica-cli
+   ```
+
+2. **Install an AI agent CLI** — at least one of:
+   - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
+   - [Codex](https://github.com/openai/codex) (`codex` on PATH)
+
+3. **Authenticate and start**
+
+   ```bash
+   # Point CLI to your server
+   export MULTICA_APP_URL=https://app.example.com
+   export MULTICA_SERVER_URL=wss://api.example.com/ws
+
+   # Login (opens browser)
+   multica login
+
+   # Start the daemon
+   multica daemon start
+   ```
+
+The daemon auto-detects installed agent CLIs and registers itself with the server. When an agent is assigned a task in Multica, the daemon picks it up, creates an isolated workspace, runs the agent, and reports results back.
+
+## Upgrading
+
+1. Pull the latest code or image
+2. Run migrations: `./server/bin/migrate up`
+3. Restart the backend and frontend
+
+Migrations are forward-only and safe to run on a live database. They are idempotent — running them multiple times has no effect.

SELF_HOSTING_ADVANCED.md

@@ -1,294 +0,0 @@
-# Self-Hosting — Advanced Configuration
-
-This document covers advanced configuration for self-hosted Multica deployments. For the quick start guide, see [SELF_HOSTING.md](SELF_HOSTING.md).
-
-## Configuration
-
-All configuration is done via environment variables. Copy `.env.example` as a starting point.
-
-### Required Variables
-
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `DATABASE_URL` | PostgreSQL connection string | `postgres://multica:multica@localhost:5432/multica?sslmode=disable` |
-| `JWT_SECRET` | **Must change from default.** Secret key for signing JWT tokens. Use a long random string. | `openssl rand -hex 32` |
-| `FRONTEND_ORIGIN` | URL where the frontend is served (used for CORS) | `https://app.example.com` |
-
-### 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).
-
-| Variable | Description |
-|----------|-------------|
-| `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.
-
-### Google OAuth (Optional)
-
-| Variable | Description |
-|----------|-------------|
-| `GOOGLE_CLIENT_ID` | Google OAuth client ID |
-| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret |
-| `GOOGLE_REDIRECT_URI` | OAuth callback URL (e.g. `https://app.example.com/auth/callback`) |
-
-Changes take effect after restarting the backend / compose stack. The web UI reads `GOOGLE_CLIENT_ID` from `/api/config` at runtime, so no web rebuild is needed.
-
-### Signup Controls (Optional)
-
-| Variable | Description |
-|----------|-------------|
-| `ALLOW_SIGNUP` | Set to `false` to disable new user signups on a private instance |
-| `ALLOWED_EMAIL_DOMAINS` | Optional comma-separated allowlist of email domains |
-| `ALLOWED_EMAILS` | Optional comma-separated allowlist of exact email addresses |
-
-Changes take effect after restarting the backend / compose stack. The web UI reads `ALLOW_SIGNUP` from `/api/config` at runtime, so no web rebuild is needed.
-
-### File Storage (Optional)
-
-For file uploads and attachments, configure S3 and CloudFront:
-
-| Variable | Description |
-|----------|-------------|
-| `S3_BUCKET` | S3 bucket name |
-| `S3_REGION` | AWS region (default: `us-west-2`) |
-| `CLOUDFRONT_DOMAIN` | CloudFront distribution domain |
-| `CLOUDFRONT_KEY_PAIR_ID` | CloudFront key pair ID for signed URLs |
-| `CLOUDFRONT_PRIVATE_KEY` | CloudFront private key (PEM format) |
-
-### 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.
-
-### Server
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PORT` | `8080` | Backend server port |
-| `FRONTEND_PORT` | `3000` | Frontend port |
-| `CORS_ALLOWED_ORIGINS` | Value of `FRONTEND_ORIGIN` | Comma-separated list of allowed origins |
-| `LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
-
-### CLI / Daemon
-
-These are configured on each user's machine, not on the server:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `MULTICA_SERVER_URL` | `ws://localhost:8080/ws` | WebSocket URL for daemon → server connection |
-| `MULTICA_APP_URL` | `http://localhost:3000` | Frontend URL for CLI login flow |
-| `MULTICA_DAEMON_POLL_INTERVAL` | `3s` | How often the daemon polls for tasks |
-| `MULTICA_DAEMON_HEARTBEAT_INTERVAL` | `15s` | Heartbeat frequency |
-
-Agent-specific overrides:
-
-| Variable | Description |
-|----------|-------------|
-| `MULTICA_CLAUDE_PATH` | Custom path to the `claude` binary |
-| `MULTICA_CLAUDE_MODEL` | Override the Claude model used |
-| `MULTICA_CODEX_PATH` | Custom path to the `codex` binary |
-| `MULTICA_CODEX_MODEL` | Override the Codex model used |
-| `MULTICA_OPENCODE_PATH` | Custom path to the `opencode` binary |
-| `MULTICA_OPENCODE_MODEL` | Override the OpenCode model used |
-| `MULTICA_OPENCLAW_PATH` | Custom path to the `openclaw` binary |
-| `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
-
-Multica requires PostgreSQL 17 with the pgvector extension.
-
-### Using Docker Compose (Recommended)
-
-The `docker-compose.selfhost.yml` includes PostgreSQL. No separate setup needed.
-
-### Using Your Own PostgreSQL
-
-If you prefer to use an existing PostgreSQL instance, ensure the pgvector extension is available:
-
-```sql
-CREATE EXTENSION IF NOT EXISTS vector;
-```
-
-Set `DATABASE_URL` in your `.env` and remove the `postgres` service from the compose file.
-
-### Running Migrations Manually
-
-The Docker Compose setup runs migrations automatically. If you need to run them manually:
-
-```bash
-# Using the built binary
-./server/bin/migrate up
-
-# Or from source
-cd server && go run ./cmd/migrate up
-```
-
-## Manual Setup (Without Docker Compose)
-
-If you prefer to build and run services manually:
-
-**Prerequisites:** Go 1.26+, Node.js 20+, pnpm 10.28+, PostgreSQL 17 with pgvector.
-
-```bash
-# Start your PostgreSQL (or use: docker compose up -d postgres)
-
-# Build the backend
-make build
-
-# Run database migrations
-DATABASE_URL="your-database-url" ./server/bin/migrate up
-
-# Start the backend server
-DATABASE_URL="your-database-url" PORT=8080 JWT_SECRET="your-secret" ./server/bin/server
-```
-
-For the frontend:
-
-```bash
-pnpm install
-pnpm build
-
-# Start the frontend (production mode)
-cd apps/web
-REMOTE_API_URL=http://localhost:8080 pnpm start
-```
-
-## Reverse Proxy
-
-In production, put a reverse proxy in front of both the backend and frontend to handle TLS and routing.
-
-### Caddy (Recommended)
-
-```
-app.example.com {
-    reverse_proxy localhost:3000
-}
-
-api.example.com {
-    reverse_proxy localhost:8080
-}
-```
-
-### Nginx
-
-```nginx
-# Frontend
-server {
-    listen 443 ssl;
-    server_name app.example.com;
-
-    ssl_certificate     /path/to/cert.pem;
-    ssl_certificate_key /path/to/key.pem;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-
-# Backend API
-server {
-    listen 443 ssl;
-    server_name api.example.com;
-
-    ssl_certificate     /path/to/cert.pem;
-    ssl_certificate_key /path/to/key.pem;
-
-    location / {
-        proxy_pass http://localhost:8080;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-    # WebSocket support
-    location /ws {
-        proxy_pass http://localhost:8080;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-        proxy_set_header Host $host;
-        proxy_read_timeout 86400;
-    }
-}
-```
-
-When using separate domains for frontend and backend, set these environment variables accordingly:
-
-```bash
-# Backend
-FRONTEND_ORIGIN=https://app.example.com
-CORS_ALLOWED_ORIGINS=https://app.example.com
-
-# Frontend (only if you are building the web image from source via docker-compose.selfhost.build.yml)
-REMOTE_API_URL=https://api.example.com
-NEXT_PUBLIC_API_URL=https://api.example.com
-NEXT_PUBLIC_WS_URL=wss://api.example.com/ws
-```
-
-## LAN / Non-localhost Access
-
-By default, Multica works on `localhost`. If you access it from another machine on the LAN (e.g. `http://192.168.1.100:3000`), you need to tell the backend to accept that origin:
-
-```bash
-# .env — replace with your server's LAN IP
-FRONTEND_ORIGIN=http://192.168.1.100:3000
-CORS_ALLOWED_ORIGINS=http://192.168.1.100:3000
-```
-
-Then restart the stack:
-
-```bash
-docker compose -f docker-compose.selfhost.yml up -d
-```
-
-The frontend automatically derives the WebSocket URL from the page address, so real-time features (chat streaming, live issue updates, notifications) work over LAN without extra configuration.
-
-> **Note:** If you need to hard-code a different public API / WebSocket endpoint into the web image, use the source-build override: `docker compose -f docker-compose.selfhost.yml -f docker-compose.selfhost.build.yml up -d --build`.
-
-## Health Check
-
-The backend exposes a health check endpoint:
-
-```
-GET /health
-→ {"status":"ok"}
-```
-
-Use this for load balancer health checks or monitoring.
-
-## Upgrading
-
-```bash
-docker compose -f docker-compose.selfhost.yml pull
-docker compose -f docker-compose.selfhost.yml up -d
-```
-
-Pin `MULTICA_IMAGE_TAG` in `.env` to an exact release like `v0.2.4` if you want to stay on a specific version. Migrations run automatically on backend startup. They are idempotent — running them multiple times has no effect.
-If the selected GHCR tag has not been published yet, fall back to `docker compose -f docker-compose.selfhost.yml -f docker-compose.selfhost.build.yml up -d --build`.

SELF_HOSTING_AI.md

@@ -1,76 +0,0 @@
-# Self-Hosting Setup (for AI Agents)
-
-This document is designed for AI agents to execute. Follow these steps exactly to deploy a local Multica instance and connect to it.
-
-## Prerequisites
-
-- Docker and Docker Compose installed
-- Homebrew installed (for CLI)
-- At least one AI agent CLI on PATH: `claude` or `codex`
-
-## Install
-
-```bash
-# Install CLI + provision self-host server
-curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --with-server
-
-# Configure CLI for localhost, authenticate, and start daemon
-multica setup self-host
-```
-
-Wait for the server output `✓ Multica server is running and CLI is ready!` before running `multica setup self-host`.
-
-**Expected result:**
-- Frontend at http://localhost:3000
-- Backend at http://localhost:8080
-- `multica` CLI installed and configured for localhost
-
-## Alternative: Manual Setup
-
-```bash
-git clone https://github.com/multica-ai/multica.git
-cd multica
-make selfhost
-brew install multica-ai/tap/multica
-multica setup self-host
-```
-
-The `multica setup self-host` command will:
-1. Configure CLI to connect to localhost:8080 / localhost:3000
-2. Open a browser for login — use verification code `888888` with any email
-3. Discover workspaces automatically
-4. Start the daemon in the background
-
-## Verification
-
-```bash
-multica daemon status
-```
-
-Should show `running` with detected agents.
-
-## Stopping
-
-```bash
-# Stop the daemon
-multica daemon stop
-
-# Stop all Docker services
-cd multica
-make selfhost-stop
-```
-
-## Custom Ports
-
-If the default ports (8080/3000) are in use:
-
-1. Edit `.env` and change `PORT` and `FRONTEND_PORT`
-2. Run `make selfhost`
-3. Run `multica setup self-host --port <PORT> --frontend-port <FRONTEND_PORT>`
-
-## Troubleshooting
-
-- **Backend not ready:** `docker compose -f docker-compose.selfhost.yml logs backend`
-- **Frontend not ready:** `docker compose -f docker-compose.selfhost.yml logs frontend`
-- **Daemon issues:** `multica daemon logs`
-- **Health check:** `curl http://localhost:8080/health`

apps/desktop/.env.production

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

apps/desktop/.gitignore

@@ -1,8 +0,0 @@
-node_modules
-dist
-out
-.DS_Store
-.eslintcache
-*.log*
-# CLI binary bundled at build time (from server/bin/)
-resources/bin/

apps/desktop/build/entitlements.mac.plist

@@ -1,24 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <!-- Electron / V8 need JIT and unsigned executable memory under the
-       hardened runtime. -->
-  <key>com.apple.security.cs.allow-jit</key>
-  <true/>
-  <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
-  <true/>
-  <!-- Required so the app can spawn the bundled `multica` Go binary and
-       any other child processes (e.g. agent CLIs) without Gatekeeper
-       blocking exec. -->
-  <key>com.apple.security.cs.disable-library-validation</key>
-  <true/>
-  <key>com.apple.security.cs.allow-dyld-environment-variables</key>
-  <true/>
-  <!-- Network client — the daemon talks to the backend + GitHub releases. -->
-  <key>com.apple.security.network.client</key>
-  <true/>
-  <key>com.apple.security.network.server</key>
-  <true/>
-</dict>
-</plist>

apps/desktop/electron-builder.yml

@@ -1,54 +0,0 @@
-appId: ai.multica.desktop
-productName: Multica
-directories:
-  buildResources: build
-files:
-  - "!**/.vscode/*"
-  - "!src/*"
-  - "!electron.vite.config.*"
-  - "!{.eslintignore,.eslintrc.cjs,.prettierignore,.prettierrc.yaml,dev-app-update.yml,CHANGELOG.md,README.md}"
-  - "!{tsconfig.json,tsconfig.node.json,tsconfig.web.json}"
-protocols:
-  - name: Multica
-    schemes:
-      - multica
-asarUnpack:
-  - resources/**
-mac:
-  entitlementsInherit: build/entitlements.mac.plist
-  target:
-    - dmg
-    - 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}
-  # 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}
-linux:
-  target:
-    - AppImage
-    - deb
-    - rpm
-  artifactName: multica-desktop-${version}-linux-${arch}.${ext}
-win:
-  target:
-    - nsis
-  artifactName: multica-desktop-${version}-windows-${arch}.${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

@@ -1,29 +0,0 @@
-import { resolve } from "path";
-import { defineConfig, externalizeDepsPlugin } from "electron-vite";
-import react from "@vitejs/plugin-react";
-import tailwindcss from "@tailwindcss/vite";
-
-export default defineConfig({
-  main: {
-    plugins: [externalizeDepsPlugin()],
-  },
-  preload: {
-    plugins: [externalizeDepsPlugin()],
-  },
-  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,
-      strictPort: true,
-    },
-    plugins: [react(), tailwindcss()],
-    resolve: {
-      alias: {
-        "@": resolve("src/renderer/src"),
-      },
-      dedupe: ["react", "react-dom"],
-    },
-  },
-});

apps/desktop/eslint.config.mjs

@@ -1,37 +0,0 @@
-import globals from "globals";
-import reactConfig from "@multica/eslint-config/react";
-
-export default [
-  ...reactConfig,
-  { ignores: ["out/", "dist/"] },
-  {
-    files: ["scripts/**/*.{mjs,js}"],
-    languageOptions: {
-      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

@@ -1,74 +0,0 @@
-{
-  "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:staging": "pnpm run bundle-cli && pnpm run brand-dev-electron && electron-vite dev --mode staging",
-    "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"
-  },
-  "dependencies": {
-    "@dnd-kit/core": "^6.3.1",
-    "@dnd-kit/modifiers": "^9.0.0",
-    "@dnd-kit/sortable": "^10.0.0",
-    "@dnd-kit/utilities": "^3.2.2",
-    "@electron-toolkit/preload": "^3.0.2",
-    "@electron-toolkit/utils": "^4.0.0",
-    "@fontsource-variable/inter": "^5.2.5",
-    "@fontsource-variable/source-serif-4": "^5.2.9",
-    "@fontsource/geist-mono": "^5.2.7",
-    "@multica/core": "workspace:*",
-    "@multica/ui": "workspace:*",
-    "@multica/views": "workspace:*",
-    "electron-updater": "^6.8.3",
-    "fix-path": "^5.0.0",
-    "react-router-dom": "^7.6.0",
-    "shadcn": "^4.1.0",
-    "sonner": "^2.0.7",
-    "tw-animate-css": "^1.4.0"
-  },
-  "devDependencies": {
-    "@electron-toolkit/tsconfig": "^2.0.0",
-    "@multica/tsconfig": "workspace:*",
-    "@tailwindcss/vite": "^4",
-    "@testing-library/jest-dom": "catalog:",
-    "@testing-library/react": "catalog:",
-    "@types/node": "catalog:",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
-    "@vitejs/plugin-react": "^5.1.1",
-    "electron": "^39.2.6",
-    "electron-builder": "^26.0.12",
-    "electron-vite": "^5.0.0",
-    "jsdom": "catalog:",
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "tailwindcss": "^4",
-    "typescript": "catalog:",
-    "vitest": "catalog:"
-  }
-}

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

@@ -1,168 +0,0 @@
-#!/usr/bin/env node
-// Builds the `multica` CLI from server/cmd/multica and copies the binary
-// into apps/desktop/resources/bin/ so electron-vite (dev) and electron-
-// builder (prod) pick it up. Running this on every dev/build/package
-// invocation guarantees the bundled CLI always matches the current Go
-// source — no more stale binary surprises. Go's build cache makes the
-// no-op case (nothing changed) effectively free.
-//
-// ldflags mirror `make build` so `multica --version` reports a meaningful
-// version / commit / date.
-//
-// Graceful: if `go` is not installed (e.g. frontend-only contributor), we
-// 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 { constants } from "node:fs";
-import { execFileSync, execSync } from "node:child_process";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-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 destDir = join(repoRoot, "apps", "desktop", "resources", "bin");
-const destBinary = join(destDir, binName);
-
-function sh(cmd) {
-  try {
-    return execSync(cmd, { encoding: "utf-8" }).trim();
-  } catch {
-    return "";
-  }
-}
-
-function hasGo() {
-  try {
-    execSync("go version", { stdio: "pipe" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function exists(p) {
-  try {
-    await access(p, constants.F_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-if (hasGo()) {
-  const version = sh("git describe --tags --always --dirty") || "dev";
-  const commit = sh("git rev-parse --short HEAD") || "unknown";
-  const date = new Date().toISOString().replace(/\.\d+Z$/, "Z");
-  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})`,
-  );
-  await mkdir(join(serverDir, "bin", `${goos}-${goarch}`), { recursive: true });
-  execFileSync(
-    "go",
-    [
-      "build",
-      "-ldflags",
-      ldflags,
-      "-o",
-      srcBinary,
-      "./cmd/multica",
-    ],
-    {
-      cwd: serverDir,
-      stdio: "inherit",
-      env: {
-        ...process.env,
-        CGO_ENABLED: "0",
-        GOOS: goos,
-        GOARCH: goarch,
-      },
-    },
-  );
-} else {
-  console.warn(
-    "[bundle-cli] `go` not found in PATH — skipping CLI build. " +
-      "Desktop will use whatever is already in resources/bin/, or fall back " +
-      "to auto-installing the latest release at runtime.",
-  );
-}
-
-if (!(await exists(srcBinary))) {
-  console.warn(
-    `[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);
-
-// macOS: ad-hoc sign so Gatekeeper doesn't complain when the parent app
-// (which itself may be unsigned in dev) spawns the child.
-if (process.platform === "darwin") {
-  try {
-    execSync(`codesign -s - --force ${JSON.stringify(destBinary)}`, {
-      stdio: "pipe",
-    });
-  } catch {
-    // Non-fatal. Unsigned binaries still run when the parent app is trusted.
-  }
-}
-
-console.log(`[bundle-cli] bundled ${srcBinary} → ${destBinary}`);

apps/desktop/scripts/package.mjs

@@ -1,430 +0,0 @@
-#!/usr/bin/env node
-// Wrapper around `electron-builder` that keeps the Desktop version in
-// lockstep with the CLI. Both are derived from `git describe --tags
-// --always --dirty` — the same source GoReleaser reads for the CLI
-// 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.
-//
-// The electron-vite step is important: electron-builder only packages
-// whatever is already in out/, so skipping it (or relying on stale
-// artifacts from a prior partial build) ships an app with missing
-// renderer code and white-screens on launch.
-//
-// Extra CLI args after `pnpm package --` are forwarded to electron-builder
-// unchanged (e.g. `--mac --arm64`). For an unsigned local smoke-test
-// build, set `CSC_IDENTITY_AUTO_DISCOVERY=false` so electron-builder falls
-// back to an ad-hoc signature instead of requiring a Developer ID cert.
-//
-// The `normalizeGitVersion` helper is exported so tests can cover the
-// version-derivation logic without shelling out.
-
-import { execFileSync, spawnSync, execSync } from "node:child_process";
-import { delimiter, 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 {
-    return execSync(cmd, { encoding: "utf-8" }).trim();
-  } catch {
-    return "";
-  }
-}
-
-/**
- * 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.
- *
- *   - empty input              → null   (caller should fall back)
- *   - "v0.1.36"                → "0.1.36"
- *   - "v0.1.35-14-gf1415e96"   → "0.1.35-14-gf1415e96"  (semver prerelease)
- *   - "v0.1.35-…-dirty"        → same, dirty suffix preserved
- *   - "f1415e96" (no tag)      → "0.0.0-f1415e96"        (fallback)
- *
- * Leading `v` is stripped so the result is valid semver for package.json.
- */
-export function normalizeGitVersion(raw) {
-  if (!raw) return null;
-  const stripped = raw.replace(/^v/, "");
-  if (!/^\d/.test(stripped)) {
-    // No reachable tag — `git describe` fell back to just the commit hash.
-    return `0.0.0-${stripped}`;
-  }
-  return stripped;
-}
-
-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 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(
-      "[package] failed to spawn electron-vite:",
-      viteResult.error.message,
-    );
-    process.exit(1);
-  }
-  if (viteResult.status !== 0) {
-    process.exit(viteResult.status ?? 1);
-  }
-
-  // Step 2: derive the version that should be written into the app.
-  const version = deriveVersion();
-  if (version) {
-    console.log(`[package] Desktop version → ${version} (from git describe)`);
-  } else {
-    console.warn(
-      "[package] could not derive version from git; falling back to package.json",
-    );
-  }
-
-  const disableMacNotarize = !process.env.APPLE_TEAM_ID;
-  if (disableMacNotarize) {
-    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.",
-    );
-  }
-
-  const useScopedOutputDir = buildMatrix.length > 1;
-
-  // 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,
-      },
-    );
-
-    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);
-    }
-  }
-}
-
-// Only run when invoked as a CLI, not when imported by a test file.
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
-  main();
-}

apps/desktop/scripts/package.test.mjs

@@ -1,273 +0,0 @@
-import { delimiter, resolve } from "node:path";
-import { describe, it, expect } from "vitest";
-import {
-  builderArgsForTarget,
-  envWithLocalBins,
-  normalizeGitVersion,
-  parsePackageArgs,
-  resolveBuildMatrix,
-  stripLeadingSeparator,
-} from "./package.mjs";
-
-describe("normalizeGitVersion", () => {
-  it("returns null for empty / nullish input", () => {
-    expect(normalizeGitVersion("")).toBe(null);
-    expect(normalizeGitVersion(null)).toBe(null);
-    expect(normalizeGitVersion(undefined)).toBe(null);
-  });
-
-  it("strips the leading v on a clean tag", () => {
-    expect(normalizeGitVersion("v0.1.36")).toBe("0.1.36");
-    expect(normalizeGitVersion("v1.0.0")).toBe("1.0.0");
-  });
-
-  it("preserves the prerelease suffix between tags", () => {
-    expect(normalizeGitVersion("v0.1.35-14-gf1415e96")).toBe(
-      "0.1.35-14-gf1415e96",
-    );
-  });
-
-  it("preserves the dirty suffix on a modified worktree", () => {
-    expect(normalizeGitVersion("v0.1.35-14-gf1415e96-dirty")).toBe(
-      "0.1.35-14-gf1415e96-dirty",
-    );
-  });
-
-  it("handles v-prefixed prerelease tags", () => {
-    expect(normalizeGitVersion("v1.0.0-alpha")).toBe("1.0.0-alpha");
-    expect(normalizeGitVersion("v1.0.0-rc.2")).toBe("1.0.0-rc.2");
-  });
-
-  it("falls back to 0.0.0-<hash> when no tags are reachable", () => {
-    // `git describe --tags --always` returns just the short commit hash
-    // when there are no tags in the history at all.
-    expect(normalizeGitVersion("f1415e96")).toBe("0.0.0-f1415e96");
-    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

@@ -1,157 +0,0 @@
-import { app } from "electron";
-import { execFile } from "child_process";
-import { createHash } from "crypto";
-import { createReadStream, createWriteStream, existsSync } from "fs";
-import { chmod, mkdir, rename, rm } from "fs/promises";
-import { join, dirname } from "path";
-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.
-
-const GITHUB_LATEST_BASE =
-  "https://github.com/multica-ai/multica/releases/latest/download";
-
-function binaryName(): string {
-  return process.platform === "win32" ? "multica.exe" : "multica";
-}
-
-export function managedCliPath(): string {
-  return join(app.getPath("userData"), "bin", binaryName());
-}
-
-function run(cmd: string, args: string[], cwd?: string): Promise<void> {
-  return new Promise((resolve, reject) => {
-    execFile(cmd, args, { cwd }, (err) => (err ? reject(err) : resolve()));
-  });
-}
-
-async function downloadToFile(url: string, dest: string): Promise<void> {
-  const res = await fetch(url, { redirect: "follow" });
-  if (!res.ok || !res.body) {
-    throw new Error(`download failed: ${res.status} ${res.statusText}`);
-  }
-  await mkdir(dirname(dest), { recursive: true });
-  // Node's fetch returns a web ReadableStream; adapt to a Node stream for pipeline.
-  const nodeStream = Readable.fromWeb(res.body as Parameters<typeof Readable.fromWeb>[0]);
-  await pipeline(nodeStream, createWriteStream(dest));
-}
-
-// Fetch goreleaser's published checksums.txt and parse it into a
-// filename → sha256 lookup. Format is `<hex>  <filename>` per line.
-async function fetchChecksums(): Promise<Map<string, string>> {
-  const url = `${GITHUB_LATEST_BASE}/checksums.txt`;
-  const res = await fetch(url, { redirect: "follow" });
-  if (!res.ok) {
-    throw new Error(
-      `checksums.txt fetch failed: ${res.status} ${res.statusText}`,
-    );
-  }
-  const text = await res.text();
-  const map = new Map<string, string>();
-  for (const rawLine of text.split("\n")) {
-    const line = rawLine.trim();
-    if (!line) continue;
-    const match = line.match(/^([a-f0-9]{64})\s+\*?(\S+)$/i);
-    if (match) map.set(match[2], match[1].toLowerCase());
-  }
-  return map;
-}
-
-async function sha256OfFile(path: string): Promise<string> {
-  const hash = createHash("sha256");
-  await pipeline(createReadStream(path), hash);
-  return hash.digest("hex");
-}
-
-async function verifyChecksum(
-  archivePath: string,
-  assetName: string,
-  expected: string,
-): Promise<void> {
-  const actual = await sha256OfFile(archivePath);
-  if (actual.toLowerCase() !== expected) {
-    throw new Error(
-      `checksum mismatch for ${assetName}: expected ${expected}, got ${actual}`,
-    );
-  }
-}
-
-async function extractArchive(archive: string, dest: string): Promise<void> {
-  await mkdir(dest, { recursive: true });
-  // Modern OSes all ship a `tar` that auto-detects tar.gz and zip:
-  // - macOS/Linux: GNU tar or bsdtar
-  // - Windows 10+: bsdtar is bundled as `tar.exe` since build 17063
-  await run("tar", ["-xf", archive, "-C", dest]);
-}
-
-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 url = `${GITHUB_LATEST_BASE}/${assetName}`;
-
-  const workDir = join(tmpdir(), `multica-cli-${Date.now()}`);
-  await mkdir(workDir, { recursive: true });
-
-  try {
-    const archivePath = join(workDir, assetName);
-    console.log(`[cli-bootstrap] downloading ${url}`);
-    await downloadToFile(url, archivePath);
-
-    console.log(`[cli-bootstrap] verifying ${assetName} against checksums.txt`);
-    await verifyChecksum(archivePath, assetName, expectedChecksum);
-
-    console.log(`[cli-bootstrap] extracting ${assetName}`);
-    await extractArchive(archivePath, workDir);
-
-    const extractedBin = join(workDir, binaryName());
-    if (!existsSync(extractedBin)) {
-      throw new Error(
-        `archive ${assetName} did not contain ${binaryName()} at its root`,
-      );
-    }
-
-    await mkdir(dirname(target), { recursive: true });
-    await rm(target, { force: true }).catch(() => {});
-    await rename(extractedBin, target);
-    await chmod(target, 0o755);
-
-    // macOS: ad-hoc sign so spawning the child never hits a gatekeeper quirk.
-    // Non-fatal: unsigned binaries still execute when the parent app is trusted.
-    if (process.platform === "darwin") {
-      await run("codesign", ["-s", "-", "--force", target]).catch((err) => {
-        console.warn("[cli-bootstrap] ad-hoc codesign failed:", err);
-      });
-    }
-
-    console.log(`[cli-bootstrap] installed CLI at ${target}`);
-    return target;
-  } finally {
-    await rm(workDir, { recursive: true, force: true }).catch(() => {});
-  }
-}
-
-/**
- * Returns the path to a usable `multica` binary. If one is already present at
- * 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> {
-  const target = managedCliPath();
-  if (existsSync(target) && !options.forceInstall) 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

@@ -1,942 +0,0 @@
-import { app, ipcMain, BrowserWindow } from "electron";
-import { execFile } from "child_process";
-import {
-  readFile,
-  writeFile,
-  mkdir,
-  rm,
-  open,
-  stat,
-} from "fs/promises";
-import {
-  existsSync,
-  watchFile,
-  unwatchFile,
-  type StatsListener,
-} from "fs";
-import { join } from "path";
-import { homedir } from "os";
-import type { DaemonStatus, DaemonPrefs } from "../shared/daemon-types";
-import { ensureManagedCli, managedCliPath } from "./cli-bootstrap";
-import { decideVersionAction } from "./version-decision";
-
-const DEFAULT_HEALTH_PORT = 19514;
-const POLL_INTERVAL_MS = 5_000;
-const PREFS_PATH = join(homedir(), ".multica", "desktop_prefs.json");
-const LOG_TAIL_RETRY_MS = 2_000;
-const LOG_TAIL_MAX_RETRIES = 5;
-
-const DEFAULT_PREFS: DaemonPrefs = { autoStart: true, autoStop: false };
-
-interface ActiveProfile {
-  name: string; // "" = default profile
-  port: number;
-}
-
-let statusPollTimer: ReturnType<typeof setInterval> | null = null;
-let logTailWatcher: { path: string; listener: StatsListener } | null = null;
-let currentState: DaemonStatus["state"] = "installing_cli";
-let getMainWindow: () => BrowserWindow | null = () => null;
-let operationInProgress = false;
-let cachedCliBinary: string | null | undefined = undefined;
-let cliResolvePromise: Promise<string | null> | null = null;
-let cachedCliBinaryVersion: string | null | undefined = undefined;
-// Set when a CLI version mismatch was detected but the running daemon is
-// busy executing tasks. The poll loop retries the check on each tick and
-// fires the restart once active_task_count drops to 0.
-let pendingVersionRestart = false;
-let targetApiBaseUrl: string | null = null;
-let activeProfile: ActiveProfile | null = null;
-
-// Serialize all writes to any profile config file. Multiple paths
-// (syncToken, resolveActiveProfile, clearToken, watch/unwatch handlers)
-// may try to write concurrently; chaining them avoids interleaved writes
-// corrupting the JSON.
-let configWriteChain: Promise<void> = Promise.resolve();
-
-// Keep the Go impl in sync: server/cmd/multica/cmd_daemon.go healthPortForProfile.
-function healthPortForProfile(profile: string): number {
-  if (!profile) return DEFAULT_HEALTH_PORT;
-  let sum = 0;
-  for (const b of Buffer.from(profile, "utf-8")) sum += b;
-  return DEFAULT_HEALTH_PORT + 1 + (sum % 1000);
-}
-
-function profileDir(profile: string): string {
-  return profile
-    ? join(homedir(), ".multica", "profiles", profile)
-    : join(homedir(), ".multica");
-}
-
-function profileConfigPath(profile: string): string {
-  return join(profileDir(profile), "config.json");
-}
-
-function profileLogPath(profile: string): string {
-  return join(profileDir(profile), "daemon.log");
-}
-
-// Sidecar file that records which Multica user the cached PAT in config.json
-// was minted for. The Go CLI/daemon never read or write this file, so it
-// survives Go-side config rewrites. Used to detect user switches and mint a
-// fresh PAT instead of reusing a token that belongs to a previous user.
-function profileUserIdPath(profile: string): string {
-  return join(profileDir(profile), ".desktop-user-id");
-}
-
-async function readProfileUserId(profile: string): Promise<string | null> {
-  try {
-    const raw = await readFile(profileUserIdPath(profile), "utf-8");
-    const trimmed = raw.trim();
-    return trimmed || null;
-  } catch {
-    return null;
-  }
-}
-
-async function writeProfileUserId(
-  profile: string,
-  userId: string,
-): Promise<void> {
-  await mkdir(profileDir(profile), { recursive: true });
-  await writeFile(profileUserIdPath(profile), userId, "utf-8");
-}
-
-async function removeProfileUserId(profile: string): Promise<void> {
-  try {
-    await rm(profileUserIdPath(profile));
-  } catch {
-    // Already gone — nothing to do.
-  }
-}
-
-function normalizeUrl(u: string): string {
-  if (!u) return "";
-  try {
-    const parsed = new URL(u);
-    return `${parsed.protocol}//${parsed.host}`.toLowerCase();
-  } catch {
-    return u.replace(/\/+$/, "").toLowerCase();
-  }
-}
-
-function urlsMatch(a: string, b: string): boolean {
-  const na = normalizeUrl(a);
-  const nb = normalizeUrl(b);
-  return na.length > 0 && na === nb;
-}
-
-function sendStatus(status: DaemonStatus): void {
-  const win = getMainWindow();
-  win?.webContents.send("daemon:status", status);
-}
-
-interface HealthPayload {
-  status?: string;
-  pid?: number;
-  uptime?: string;
-  daemon_id?: string;
-  device_name?: string;
-  server_url?: string;
-  cli_version?: string;
-  active_task_count?: number;
-  agents?: string[];
-  workspaces?: unknown[];
-}
-
-async function fetchHealthAtPort(
-  port: number,
-): Promise<HealthPayload | null> {
-  try {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 2_000);
-    const res = await fetch(`http://127.0.0.1:${port}/health`, {
-      signal: controller.signal,
-    });
-    clearTimeout(timeout);
-    if (!res.ok) return null;
-    return (await res.json()) as HealthPayload;
-  } catch {
-    return null;
-  }
-}
-
-// Desktop owns a dedicated CLI profile named after the target API host, so it
-// never reads or writes the user's hand-configured profiles. Profile dir:
-//   ~/.multica/profiles/desktop-<host>/
-function deriveProfileName(targetUrl: string): string {
-  try {
-    const url = new URL(targetUrl);
-    const host = url.host.replace(/:/g, "-").toLowerCase();
-    return `desktop-${host}`;
-  } catch {
-    return "desktop";
-  }
-}
-
-async function readProfileConfig(
-  profile: string,
-): Promise<Record<string, unknown>> {
-  try {
-    const raw = await readFile(profileConfigPath(profile), "utf-8");
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === "object" ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-
-async function writeProfileConfig(
-  profile: string,
-  cfg: Record<string, unknown>,
-): Promise<void> {
-  const op = async () => {
-    await mkdir(profileDir(profile), { recursive: true });
-    await writeFile(
-      profileConfigPath(profile),
-      JSON.stringify(cfg, null, 2),
-      "utf-8",
-    );
-  };
-  const next = configWriteChain.catch(() => {}).then(op);
-  configWriteChain = next.catch(() => {});
-  return next;
-}
-
-/**
- * Returns the Desktop-owned profile for the current target API URL. Creates
- * the profile's config.json on demand with `server_url` pinned to the target.
- *
- * This function never falls back to the default profile, and never touches a
- * profile whose name doesn't start with `desktop-`, so the user's manually
- * configured CLI profiles are untouched.
- */
-async function resolveActiveProfile(): Promise<ActiveProfile> {
-  const target = targetApiBaseUrl;
-  if (!target) return { name: "", port: DEFAULT_HEALTH_PORT };
-
-  const name = deriveProfileName(target);
-  const cfg = await readProfileConfig(name);
-
-  if (cfg.server_url !== target) {
-    cfg.server_url = target;
-    await writeProfileConfig(name, cfg);
-    console.log(`[daemon] initialized profile "${name}" → ${target}`);
-  }
-
-  return { name, port: healthPortForProfile(name) };
-}
-
-async function ensureActiveProfile(): Promise<ActiveProfile> {
-  if (activeProfile) return activeProfile;
-  activeProfile = await resolveActiveProfile();
-  return activeProfile;
-}
-
-function invalidateActiveProfile(): void {
-  activeProfile = null;
-}
-
-async function fetchHealth(): Promise<DaemonStatus> {
-  // While the CLI is being downloaded or has permanently failed, short-circuit
-  // polling — there's nothing to probe yet and /health calls would just return
-  // "stopped", which would overwrite the correct setup state in the UI.
-  if (currentState === "installing_cli" || currentState === "cli_not_found") {
-    return { state: currentState };
-  }
-
-  const active = await ensureActiveProfile();
-  const data = await fetchHealthAtPort(active.port);
-
-  if (!data || data.status !== "running") {
-    return {
-      state: currentState === "starting" ? "starting" : "stopped",
-      profile: active.name,
-    };
-  }
-
-  // Safety: if we have a target URL and the daemon on our port reports a
-  // different server_url, it's not "our" daemon — drop it and re-resolve.
-  if (
-    targetApiBaseUrl &&
-    data.server_url &&
-    !urlsMatch(data.server_url, targetApiBaseUrl)
-  ) {
-    invalidateActiveProfile();
-    return { state: "stopped" };
-  }
-
-  return {
-    state: "running",
-    pid: data.pid,
-    uptime: data.uptime,
-    daemonId: data.daemon_id,
-    deviceName: data.device_name,
-    agents: data.agents ?? [],
-    workspaceCount: Array.isArray(data.workspaces)
-      ? data.workspaces.length
-      : 0,
-    profile: active.name,
-    serverUrl: data.server_url,
-  };
-}
-
-function findCliOnPath(): string | null {
-  const candidates = process.platform === "win32" ? ["multica.exe"] : ["multica"];
-  const paths = (process.env["PATH"] ?? "").split(
-    process.platform === "win32" ? ";" : ":",
-  );
-  if (process.platform === "darwin") {
-    paths.push("/opt/homebrew/bin", "/usr/local/bin");
-  }
-  for (const name of candidates) {
-    for (const dir of paths) {
-      const full = join(dir, name);
-      if (existsSync(full)) return full;
-    }
-  }
-  return null;
-}
-
-/**
- * Returns the path to the CLI binary bundled inside the Desktop app.
- *
- * - Dev (`electron-vite dev`): `app.getAppPath()` → `apps/desktop`, resolving
- *   to `apps/desktop/resources/bin/multica`. `bundle-cli.mjs` populates this
- *   before dev starts, so iterating on Go changes is "make build → restart".
- * - Packaged: `app.getAppPath()` → `<Multica.app>/Contents/Resources/app.asar`.
- *   electron-builder's `asarUnpack: resources/**` extracts the binary to
- *   `app.asar.unpacked/`, so we swap the path segment to execute it.
- */
-function bundledCliPath(): string {
-  const binName = process.platform === "win32" ? "multica.exe" : "multica";
-  return join(app.getAppPath(), "resources", "bin", binName).replace(
-    "app.asar",
-    "app.asar.unpacked",
-  );
-}
-
-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.
- *   2. Bundled binary shipped with the Desktop app (`bundle-cli.mjs`).
- *   3. Managed binary already installed in userData (`managedCliPath`).
- *   4. Download + install latest release into userData.
- *   5. `multica` on PATH (dev convenience / user-installed via brew).
- * Returns `null` only when all of the above fail.
- *
- * Bundled is preferred so Desktop iterates in lockstep with Go changes in
- * the same repo — avoids the 404 / stale-API problem when the Desktop's
- * TS side is ahead of the last published CLI release.
- *
- * This function is idempotent and safe to call concurrently — in-flight
- * installs are de-duplicated via `cliResolvePromise`.
- */
-async function resolveCliBinary(): Promise<string | null> {
-  if (cachedCliBinary !== undefined) return cachedCliBinary;
-  if (cliResolvePromise) return cliResolvePromise;
-
-  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;
-      }
-    }
-
-    const managed = managedCliPath();
-    if (existsSync(managed)) {
-      const version = await probeCliBinary(managed, "managed");
-      if (version) {
-        cachedCliBinary = managed;
-        cachedCliBinaryVersion = version;
-        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`,
-      );
-    } catch (err) {
-      console.warn("[daemon] CLI auto-install failed, falling back to PATH:", err);
-    }
-
-    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 {
-    return await cliResolvePromise;
-  } finally {
-    cliResolvePromise = null;
-  }
-}
-
-/**
- * Reads the version of the currently resolved CLI binary. Cached for the
- * process lifetime — the bundled binary doesn't change after bundle time.
- * Returns null on any failure (unknown `go` at bundle time, broken binary,
- * wrong-arch bundled binary, etc.) so callers can fail open.
- */
-async function getCliBinaryVersion(): Promise<string | null> {
-  if (cachedCliBinaryVersion !== undefined) return cachedCliBinaryVersion;
-  const bin = await resolveCliBinary();
-  if (!bin) {
-    cachedCliBinaryVersion = null;
-    return null;
-  }
-  cachedCliBinaryVersion = await probeCliBinary(bin, "path");
-  return cachedCliBinaryVersion;
-}
-
-/**
- * Compares the running daemon's `cli_version` against the CLI binary we
- * would use to spawn a new one, and restarts only when safe. The decision
- * logic itself is in `version-decision.ts` (pure, unit-tested); this
- * wrapper handles the async plumbing and side effects.
- *
- * Restart is only fired when ALL of:
- *   - a daemon is actually running on the active profile's port
- *   - both sides report a version and the strings differ
- *   - `active_task_count` is 0 (no in-flight agent work would be killed)
- *
- * On a confirmed mismatch while the daemon is busy, `pendingVersionRestart`
- * is set; the poll loop retries this function on each 5s tick and will fire
- * the restart as soon as the daemon drains.
- */
-async function ensureRunningDaemonVersionMatches(): Promise<
-  "restarted" | "deferred" | "ok" | "not_running"
-> {
-  const active = await ensureActiveProfile();
-  const running = await fetchHealthAtPort(active.port);
-  const bundled = await getCliBinaryVersion();
-  const action = decideVersionAction(bundled, running);
-
-  switch (action) {
-    case "not_running":
-      pendingVersionRestart = false;
-      return "not_running";
-    case "ok":
-      pendingVersionRestart = false;
-      return "ok";
-    case "defer": {
-      if (!pendingVersionRestart) {
-        const activeTasks = running?.active_task_count ?? 0;
-        console.log(
-          `[daemon] CLI version mismatch (bundled=${bundled} running=${running?.cli_version}); deferring restart until ${activeTasks} active task(s) finish`,
-        );
-      }
-      pendingVersionRestart = true;
-      return "deferred";
-    }
-    case "restart":
-      console.log(
-        `[daemon] CLI version mismatch (bundled=${bundled} running=${running?.cli_version}) — restarting daemon`,
-      );
-      pendingVersionRestart = false;
-      await restartDaemon();
-      return "restarted";
-  }
-}
-
-/**
- * Exchange the user's JWT for a long-lived PAT via POST /api/tokens. The
- * daemon needs a PAT (or `mul_` / `mdt_` token) because JWTs expire in 30
- * days and signatures are tied to a specific backend instance.
- */
-async function mintPat(jwt: string): Promise<string> {
-  if (!targetApiBaseUrl) {
-    throw new Error("mint PAT: target API URL not set");
-  }
-  const url = `${targetApiBaseUrl.replace(/\/+$/, "")}/api/tokens`;
-  const res = await fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${jwt}`,
-    },
-    // Omit expires_in_days → server treats as null → non-expiring PAT.
-    body: JSON.stringify({ name: "Multica Desktop" }),
-  });
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    throw new Error(`mint PAT failed: ${res.status} ${res.statusText} ${body}`);
-  }
-  const data = (await res.json()) as { token?: unknown };
-  if (typeof data.token !== "string" || !data.token.startsWith("mul_")) {
-    throw new Error("mint PAT: response missing token");
-  }
-  return data.token;
-}
-
-/**
- * Ensure the active profile's config.json has a usable token for the daemon.
- *
- * - Input from the renderer is the user's JWT (from localStorage) plus the
- *   current user's id, so we can detect session changes.
- * - If the profile already has a cached PAT (`mul_...`) AND the sidecar user
- *   id matches the caller, reuse it — minting fresh on every launch would
- *   accumulate garbage in the user's tokens page.
- * - On user mismatch (or first run) call POST /api/tokens with the JWT to
- *   mint a fresh PAT, overwriting any stale cached PAT. This is the critical
- *   path: without it, a previous user's PAT would be used by a new session.
- * - If the caller happens to pass a PAT directly, write it through.
- * - When we mint fresh and a daemon is already running, restart it so the
- *   new credentials take effect (the Go daemon reads config at startup).
- */
-async function syncToken(
-  tokenFromRenderer: string,
-  userId: string,
-): Promise<void> {
-  const active = await ensureActiveProfile();
-  const config = await readProfileConfig(active.name);
-  const previousUserId = await readProfileUserId(active.name);
-  const userChanged = Boolean(previousUserId) && previousUserId !== userId;
-  const sameUserWithCachedPat =
-    !userChanged &&
-    previousUserId === userId &&
-    typeof config.token === "string" &&
-    config.token.startsWith("mul_");
-
-  let finalToken: string;
-  if (tokenFromRenderer.startsWith("mul_")) {
-    finalToken = tokenFromRenderer;
-  } else if (sameUserWithCachedPat) {
-    finalToken = config.token as string;
-  } else {
-    try {
-      finalToken = await mintPat(tokenFromRenderer);
-      console.log(
-        `[daemon] minted PAT for profile "${active.name}" (user_changed=${userChanged})`,
-      );
-    } catch (err) {
-      console.error("[daemon] failed to mint PAT:", err);
-      throw err;
-    }
-  }
-
-  config.token = finalToken;
-  if (targetApiBaseUrl) config.server_url = targetApiBaseUrl;
-  await writeProfileConfig(active.name, config);
-  await writeProfileUserId(active.name, userId);
-
-  // If we just rotated credentials onto a running daemon, restart it so the
-  // in-memory token in the Go process matches the new config.
-  if (userChanged) {
-    try {
-      const existing = await fetchHealthAtPort(active.port);
-      if (existing?.status === "running") {
-        console.log(
-          "[daemon] user switched — restarting daemon with new credentials",
-        );
-        void restartDaemon();
-      }
-    } catch (err) {
-      console.warn("[daemon] restart-on-user-switch failed:", err);
-    }
-  }
-}
-
-async function loadPrefs(): Promise<DaemonPrefs> {
-  try {
-    const raw = await readFile(PREFS_PATH, "utf-8");
-    const parsed = JSON.parse(raw);
-    return { ...DEFAULT_PREFS, ...parsed };
-  } catch {
-    return { ...DEFAULT_PREFS };
-  }
-}
-
-async function savePrefs(prefs: DaemonPrefs): Promise<void> {
-  const dir = join(homedir(), ".multica");
-  await mkdir(dir, { recursive: true });
-  await writeFile(PREFS_PATH, JSON.stringify(prefs, null, 2), "utf-8");
-}
-
-async function clearToken(): Promise<void> {
-  const active = await ensureActiveProfile();
-  const config = await readProfileConfig(active.name);
-  if ("token" in config) {
-    delete config.token;
-    await writeProfileConfig(active.name, config);
-  }
-  // Always drop the sidecar so a subsequent syncToken from any user is
-  // treated as a fresh mint, not a reuse of a stale cached PAT.
-  await removeProfileUserId(active.name);
-}
-
-async function withGuard<T>(fn: () => Promise<T>): Promise<T | { success: false; error: string }> {
-  if (operationInProgress) {
-    return { success: false, error: "Another daemon operation is in progress" };
-  }
-  operationInProgress = true;
-  try {
-    return await fn();
-  } finally {
-    operationInProgress = false;
-  }
-}
-
-function profileArgs(active: ActiveProfile): string[] {
-  return active.name ? ["--profile", active.name] : [];
-}
-
-// Env passed to every CLI child so the daemon process knows it was spawned
-// by the Desktop app. The server uses this to mark runtimes as managed and
-// hide CLI self-update UI. Computed lazily so it picks up the PATH fix
-// applied by fix-path in main/index.ts — as a top-level const it would
-// snapshot process.env at import time, before that block runs.
-function desktopSpawnEnv(): NodeJS.ProcessEnv {
-  return { ...process.env, MULTICA_LAUNCHED_BY: "desktop" };
-}
-
-async function startDaemon(): Promise<{ success: boolean; error?: string }> {
-  const bin = await resolveCliBinary();
-  if (!bin) return { success: false, error: "multica CLI is not installed" };
-
-  const active = await ensureActiveProfile();
-  const existing = await fetchHealthAtPort(active.port);
-  if (existing?.status === "running") {
-    pollOnce();
-    return { success: true };
-  }
-
-  currentState = "starting";
-  sendStatus({ state: "starting" });
-
-  const args = ["daemon", "start", ...profileArgs(active)];
-
-  return new Promise((resolve) => {
-    execFile(
-      bin,
-      args,
-      { timeout: 20_000, env: desktopSpawnEnv() },
-      (err) => {
-        if (err) {
-          currentState = "stopped";
-          sendStatus({ state: "stopped" });
-          resolve({ success: false, error: err.message });
-          return;
-        }
-        // Stay in "starting" until pollOnce confirms /health — the CLI
-        // returning 0 only means the supervisor was spawned, not that the
-        // daemon process is already listening.
-        pollOnce();
-        resolve({ success: true });
-      },
-    );
-  });
-}
-
-async function stopDaemon(): Promise<{ success: boolean; error?: string }> {
-  const bin = await resolveCliBinary();
-  if (!bin) return { success: false, error: "multica CLI is not installed" };
-
-  const active = await ensureActiveProfile();
-  currentState = "stopping";
-  sendStatus({ state: "stopping" });
-
-  const args = ["daemon", "stop", ...profileArgs(active)];
-
-  return new Promise((resolve) => {
-    execFile(bin, args, { timeout: 15_000 }, (err) => {
-      if (err) {
-        resolve({ success: false, error: err.message });
-      } else {
-        resolve({ success: true });
-      }
-      currentState = "stopped";
-      sendStatus({ state: "stopped" });
-    });
-  });
-}
-
-async function restartDaemon(): Promise<{ success: boolean; error?: string }> {
-  const stopResult = await stopDaemon();
-  if (!stopResult.success) return stopResult;
-  return startDaemon();
-}
-
-async function pollOnce(): Promise<void> {
-  const status = await fetchHealth();
-  currentState = status.state;
-  sendStatus(status);
-  // Retry a deferred version-mismatch restart once the daemon drains.
-  if (pendingVersionRestart && status.state === "running") {
-    void ensureRunningDaemonVersionMatches();
-  }
-}
-
-function startPolling(): void {
-  if (statusPollTimer) return;
-  pollOnce();
-  statusPollTimer = setInterval(pollOnce, POLL_INTERVAL_MS);
-}
-
-/**
- * Ensures the CLI binary is available, then transitions into the normal
- * stopped/running state machine. Called once at startup and again on
- * user-triggered `daemon:retry-install`.
- */
-async function bootstrapCli(): Promise<void> {
-  const bin = await resolveCliBinary();
-  if (!bin) {
-    currentState = "cli_not_found";
-    sendStatus({ state: "cli_not_found" });
-    return;
-  }
-  currentState = "stopped";
-  sendStatus({ state: "stopped" });
-  startPolling();
-}
-
-function stopPolling(): void {
-  if (statusPollTimer) {
-    clearInterval(statusPollTimer);
-    statusPollTimer = null;
-  }
-}
-
-const LOG_TAIL_INITIAL_WINDOW_BYTES = 32 * 1024;
-const LOG_TAIL_INITIAL_LINES = 200;
-const LOG_TAIL_POLL_MS = 500;
-
-async function readLogRange(
-  path: string,
-  startAt: number,
-  length: number,
-): Promise<string> {
-  const handle = await open(path, "r");
-  try {
-    const buffer = Buffer.alloc(length);
-    const { bytesRead } = await handle.read(buffer, 0, length, startAt);
-    return buffer.subarray(0, bytesRead).toString("utf-8");
-  } finally {
-    await handle.close();
-  }
-}
-
-function sendLines(win: BrowserWindow, text: string): void {
-  const lines = text.split("\n").filter((line) => line.length > 0);
-  for (const line of lines) {
-    win.webContents.send("daemon:log-line", line);
-  }
-}
-
-// Cross-platform tail -f replacement: read the tail of the file once, then
-// poll its stat with fs.watchFile and forward any new bytes since the last
-// known offset. watchFile works on macOS, Linux, and Windows; spawn("tail")
-// would silently fail on Windows.
-function startLogTail(win: BrowserWindow, retryCount = 0): void {
-  stopLogTail();
-
-  void ensureActiveProfile().then(async (active) => {
-    const logPath = profileLogPath(active.name);
-    if (!existsSync(logPath)) {
-      if (retryCount < LOG_TAIL_MAX_RETRIES) {
-        setTimeout(() => startLogTail(win, retryCount + 1), LOG_TAIL_RETRY_MS);
-      }
-      return;
-    }
-
-    let position = 0;
-    try {
-      const initialStats = await stat(logPath);
-      const windowBytes = Math.min(
-        initialStats.size,
-        LOG_TAIL_INITIAL_WINDOW_BYTES,
-      );
-      const startAt = initialStats.size - windowBytes;
-      if (windowBytes > 0) {
-        const text = await readLogRange(logPath, startAt, windowBytes);
-        const lines = text
-          .split("\n")
-          .filter((line) => line.length > 0)
-          .slice(-LOG_TAIL_INITIAL_LINES);
-        for (const line of lines) {
-          win.webContents.send("daemon:log-line", line);
-        }
-      }
-      position = initialStats.size;
-    } catch (err) {
-      console.warn("[daemon] log tail initial read failed:", err);
-      return;
-    }
-
-    const listener: StatsListener = (curr) => {
-      const target = getMainWindow();
-      if (!target) return;
-      // File rotated/truncated — restart from the new beginning.
-      if (curr.size < position) position = 0;
-      if (curr.size === position) return;
-      const from = position;
-      const length = curr.size - from;
-      position = curr.size;
-      readLogRange(logPath, from, length)
-        .then((text) => sendLines(target, text))
-        .catch((err) => {
-          console.warn("[daemon] log tail read failed:", err);
-        });
-    };
-
-    watchFile(logPath, { interval: LOG_TAIL_POLL_MS }, listener);
-    logTailWatcher = { path: logPath, listener };
-  });
-}
-
-function stopLogTail(): void {
-  if (logTailWatcher) {
-    unwatchFile(logTailWatcher.path, logTailWatcher.listener);
-    logTailWatcher = null;
-  }
-}
-
-export function setupDaemonManager(
-  windowGetter: () => BrowserWindow | null,
-): void {
-  getMainWindow = windowGetter;
-
-  ipcMain.handle("daemon:set-target-api-url", async (_e, url: string) => {
-    const normalized = url || null;
-    if (targetApiBaseUrl !== normalized) {
-      console.log(`[daemon] target API URL set to ${normalized ?? "(none)"}`);
-      targetApiBaseUrl = normalized;
-      invalidateActiveProfile();
-      await pollOnce();
-    }
-  });
-  ipcMain.handle("daemon:start", () => withGuard(() => startDaemon()));
-  ipcMain.handle("daemon:stop", () => withGuard(() => stopDaemon()));
-  ipcMain.handle("daemon:restart", () => withGuard(() => restartDaemon()));
-  ipcMain.handle("daemon:get-status", () => fetchHealth());
-  ipcMain.handle(
-    "daemon:sync-token",
-    (_event, token: string, userId: string) => syncToken(token, userId),
-  );
-  ipcMain.handle("daemon:clear-token", () => clearToken());
-  ipcMain.handle("daemon:is-cli-installed", async () => {
-    const bin = await resolveCliBinary();
-    return bin !== null;
-  });
-  ipcMain.handle("daemon:retry-install", async () => {
-    cachedCliBinary = undefined;
-    cliResolvePromise = null;
-    // A retry-install may land a new CLI at a different version; drop the
-    // cached version string so the next check re-reads the binary.
-    cachedCliBinaryVersion = undefined;
-    await bootstrapCli();
-  });
-  ipcMain.handle("daemon:get-prefs", () => loadPrefs());
-  ipcMain.handle(
-    "daemon:set-prefs",
-    (_event, prefs: Partial<DaemonPrefs>) =>
-      loadPrefs().then((cur) => {
-        const merged = { ...cur, ...prefs };
-        return savePrefs(merged).then(() => merged);
-      }),
-  );
-  ipcMain.handle("daemon:auto-start", async () => {
-    const prefs = await loadPrefs();
-    if (!prefs.autoStart) return;
-    const bin = await resolveCliBinary();
-    if (!bin) return;
-    const health = await fetchHealth();
-    if (health.state === "running") {
-      // Daemon is up but may be running an older CLI than the one we just
-      // bundled. Restart it so the new binary actually takes effect.
-      await ensureRunningDaemonVersionMatches();
-      return;
-    }
-    await startDaemon();
-  });
-
-  ipcMain.on("daemon:start-log-stream", () => {
-    const win = getMainWindow();
-    if (win) startLogTail(win);
-  });
-
-  ipcMain.on("daemon:stop-log-stream", () => {
-    stopLogTail();
-  });
-
-  // First-run CLI install kicks off here. Status bar shows "Setting up…"
-  // until the managed binary is on disk (instant on subsequent launches).
-  currentState = "installing_cli";
-  sendStatus({ state: "installing_cli" });
-  void bootstrapCli();
-
-  let isQuitting = false;
-  app.on("before-quit", (event) => {
-    if (isQuitting) return;
-    stopPolling();
-    stopLogTail();
-
-    loadPrefs().then(async (prefs) => {
-      if (prefs.autoStop) {
-        isQuitting = true;
-        event.preventDefault();
-        try {
-          await stopDaemon();
-        } catch {
-          // Best-effort stop on quit
-        }
-        app.quit();
-      }
-    });
-  });
-}

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,244 +0,0 @@
-import { app, BrowserWindow, ipcMain, nativeImage } 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.).
-// Run the user's login shell once to recover the real PATH so the bundled
-// multica CLI can find agent binaries like claude/codex/opencode. Must run
-// before any child_process.spawn / execFile call in the main process —
-// ES module imports are hoisted, so this block executes before createWindow
-// or any daemon-manager spawn.
-if (process.platform !== "win32") {
-  fixPath();
-  // Fallback: prepend common install locations in case fix-path came up
-  // short (broken shell rc, non-interactive $SHELL, missing entries). Safe
-  // to duplicate — PATH lookups short-circuit on first match.
-  const fallbackPaths = [
-    "/opt/homebrew/bin",
-    "/usr/local/bin",
-    join(homedir(), ".local/bin"),
-  ];
-  process.env.PATH = `${fallbackPaths.join(":")}:${process.env.PATH ?? ""}`;
-}
-
-const PROTOCOL = "multica";
-
-let mainWindow: BrowserWindow | null = null;
-
-// --- Deep link helpers ---------------------------------------------------
-
-function handleDeepLink(url: string): void {
-  try {
-    const parsed = new URL(url);
-    if (parsed.protocol !== `${PROTOCOL}:`) return;
-
-    // multica://auth/callback?token=<jwt>
-    if (parsed.hostname === "auth" && parsed.pathname === "/callback") {
-      const token = parsed.searchParams.get("token");
-      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
-  }
-}
-
-// --- Window creation -----------------------------------------------------
-
-function createWindow(): void {
-  mainWindow = new BrowserWindow({
-    width: 1280,
-    height: 800,
-    minWidth: 900,
-    minHeight: 600,
-    titleBarStyle: "hiddenInset",
-    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,
-      webSecurity: false,
-    },
-  });
-
-  // Strip Origin header from WebSocket upgrade requests so the server's
-  // origin whitelist doesn't reject connections from localhost dev origins.
-  mainWindow.webContents.session.webRequest.onBeforeSendHeaders(
-    { urls: ["wss://*/*", "ws://*/*"] },
-    (details, callback) => {
-      delete details.requestHeaders["Origin"];
-      callback({ requestHeaders: details.requestHeaders });
-    },
-  );
-
-  mainWindow.on("ready-to-show", () => {
-    mainWindow?.show();
-  });
-
-  mainWindow.webContents.setWindowOpenHandler((details) => {
-    openExternalSafely(details.url);
-    return { action: "deny" };
-  });
-
-  if (is.dev && process.env["ELECTRON_RENDERER_URL"]) {
-    mainWindow.loadURL(process.env["ELECTRON_RENDERER_URL"]);
-  } else {
-    mainWindow.loadFile(join(__dirname, "../renderer/index.html"));
-  }
-}
-
-// --- 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) {
-  // In dev, register with the path to the electron binary + app path
-  app.setAsDefaultProtocolClient(PROTOCOL, process.execPath, [
-    app.getAppPath(),
-  ]);
-} else {
-  app.setAsDefaultProtocolClient(PROTOCOL);
-}
-
-// --- Single instance lock ------------------------------------------------
-
-const gotTheLock = app.requestSingleInstanceLock();
-
-if (!gotTheLock) {
-  app.quit();
-} else {
-  // Windows/Linux: second instance passes deep link via argv
-  app.on("second-instance", (_event, argv) => {
-    if (mainWindow) {
-      if (mainWindow.isMinimized()) mainWindow.restore();
-      mainWindow.focus();
-    }
-
-    // On Windows the deep link URL is the last argv entry
-    const deepLinkUrl = argv.find((arg) => arg.startsWith(`${PROTOCOL}://`));
-    if (deepLinkUrl) handleDeepLink(deepLinkUrl);
-  });
-
-  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);
-    }
-
-    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.
-    ipcMain.handle("shell:openExternal", (_event, url: string) => {
-      return openExternalSafely(url);
-    });
-
-    // Sync IPC: app version + normalized OS for preload. Sync (not invoke) so
-    // preload can attach the values to `desktopAPI.appInfo` before any renderer
-    // code reads them, ensuring the very first HTTP request from the renderer
-    // already carries X-Client-Version and X-Client-OS.
-    ipcMain.on("app:get-info", (event) => {
-      const p = process.platform;
-      const os = p === "darwin" ? "macos" : p === "win32" ? "windows" : p === "linux" ? "linux" : "unknown";
-      event.returnValue = { version: app.getVersion(), os };
-    });
-
-    // IPC: toggle immersive mode — hides the macOS traffic lights so full-screen
-    // modals (e.g. create-workspace) can place UI in the top-left corner
-    // without fighting the native window controls' hit-test.
-    ipcMain.handle("window:setImmersive", (_event, immersive: boolean) => {
-      if (process.platform !== "darwin") return;
-      mainWindow?.setWindowButtonVisibility(!immersive);
-    });
-
-    createWindow();
-
-    setupAutoUpdater(() => mainWindow);
-    setupDaemonManager(() => mainWindow);
-
-    // macOS: deep link arrives via open-url event
-    app.on("open-url", (_event, url) => {
-      if (mainWindow) {
-        if (mainWindow.isMinimized()) mainWindow.restore();
-        mainWindow.focus();
-      }
-      handleDeepLink(url);
-    });
-
-    app.on("activate", () => {
-      if (BrowserWindow.getAllWindows().length === 0) createWindow();
-    });
-  });
-
-  // Check argv for deep link on cold start (Windows/Linux)
-  const deepLinkArg = process.argv.find((arg) =>
-    arg.startsWith(`${PROTOCOL}://`),
-  );
-  if (deepLinkArg) {
-    app.whenReady().then(() => handleDeepLink(deepLinkArg));
-  }
-}
-
-app.on("window-all-closed", () => {
-  if (process.platform !== "darwin") app.quit();
-});

apps/desktop/src/main/updater.ts

@@ -1,100 +0,0 @@
-import { autoUpdater } from "electron-updater";
-import { app, 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();
-    win?.webContents.send("updater:update-available", {
-      version: info.version,
-      releaseNotes: info.releaseNotes,
-    });
-  });
-
-  autoUpdater.on("download-progress", (progress) => {
-    const win = getMainWindow();
-    win?.webContents.send("updater:download-progress", {
-      percent: progress.percent,
-    });
-  });
-
-  autoUpdater.on("update-downloaded", () => {
-    const win = getMainWindow();
-    win?.webContents.send("updater:update-downloaded");
-  });
-
-  autoUpdater.on("error", (err) => {
-    console.error("Auto-updater error:", err);
-  });
-
-  ipcMain.handle("updater:download", () => {
-    return autoUpdater.downloadUpdate();
-  });
-
-  ipcMain.handle("updater:install", () => {
-    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.
-  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);
-}

apps/desktop/src/main/version-decision.test.ts

@@ -1,88 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { decideVersionAction } from "./version-decision";
-
-describe("decideVersionAction", () => {
-  it("returns not_running when health payload is null", () => {
-    expect(decideVersionAction("v1.0.0", null)).toBe("not_running");
-  });
-
-  it("returns not_running when status is not 'running'", () => {
-    expect(
-      decideVersionAction("v1.0.0", { status: "stopped", cli_version: "v1.0.0" }),
-    ).toBe("not_running");
-  });
-
-  it("returns ok when bundled version is unknown (fail safe)", () => {
-    expect(
-      decideVersionAction(null, {
-        status: "running",
-        cli_version: "v1.0.0",
-        active_task_count: 0,
-      }),
-    ).toBe("ok");
-  });
-
-  it("returns ok when running daemon does not report cli_version (older daemon)", () => {
-    expect(
-      decideVersionAction("v1.0.0", {
-        status: "running",
-        active_task_count: 0,
-      }),
-    ).toBe("ok");
-  });
-
-  it("returns ok when versions match exactly", () => {
-    expect(
-      decideVersionAction("v1.2.3", {
-        status: "running",
-        cli_version: "v1.2.3",
-        active_task_count: 5,
-      }),
-    ).toBe("ok");
-  });
-
-  it("returns restart when versions differ and daemon is idle", () => {
-    expect(
-      decideVersionAction("v1.2.3", {
-        status: "running",
-        cli_version: "v1.2.2",
-        active_task_count: 0,
-      }),
-    ).toBe("restart");
-  });
-
-  it("treats missing active_task_count as 0 (old daemon that still reports cli_version)", () => {
-    expect(
-      decideVersionAction("v1.2.3", {
-        status: "running",
-        cli_version: "v1.2.2",
-      }),
-    ).toBe("restart");
-  });
-
-  it("returns defer when versions differ but daemon is busy", () => {
-    expect(
-      decideVersionAction("v1.2.3", {
-        status: "running",
-        cli_version: "v1.2.2",
-        active_task_count: 2,
-      }),
-    ).toBe("defer");
-  });
-
-  it("transitions defer → restart as tasks drain", () => {
-    // Same bundled version across three observations while the daemon ages.
-    const bundled = "v2.0.0";
-    const base = { status: "running", cli_version: "v1.9.0" } as const;
-
-    expect(
-      decideVersionAction(bundled, { ...base, active_task_count: 3 }),
-    ).toBe("defer");
-    expect(
-      decideVersionAction(bundled, { ...base, active_task_count: 1 }),
-    ).toBe("defer");
-    expect(
-      decideVersionAction(bundled, { ...base, active_task_count: 0 }),
-    ).toBe("restart");
-  });
-});

apps/desktop/src/main/version-decision.ts

@@ -1,37 +0,0 @@
-// Pure decision logic for the daemon version-check flow. Kept in its own
-// module so it can be unit-tested without mocking Electron, execFile, or
-// the HTTP health probe.
-
-export interface VersionCheckHealth {
-  status?: string;
-  cli_version?: string;
-  active_task_count?: number;
-}
-
-export type VersionAction = "restart" | "defer" | "ok" | "not_running";
-
-/**
- * Decides what the daemon-manager should do given the currently-resolved
- * bundled CLI version and the latest /health payload.
- *
- *   not_running: no daemon is up, nothing to do
- *   ok:          versions match, OR either side is unknown (fail safe)
- *   defer:       versions differ but the daemon is busy — wait for drain
- *   restart:     versions differ and the daemon is idle — safe to restart
- *
- * Pure function: no I/O, no side effects, no module state.
- */
-export function decideVersionAction(
-  bundled: string | null,
-  running: VersionCheckHealth | null,
-): VersionAction {
-  if (!running || running.status !== "running") return "not_running";
-
-  const runningVersion = running.cli_version;
-  if (!bundled || !runningVersion) return "ok";
-  if (runningVersion === bundled) return "ok";
-
-  const activeTasks = running.active_task_count ?? 0;
-  if (activeTasks > 0) return "defer";
-  return "restart";
-}

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

@@ -1,76 +0,0 @@
-import { ElectronAPI } from "@electron-toolkit/preload";
-
-interface DesktopAPI {
-  /** App version + normalized OS, captured synchronously at preload time. */
-  appInfo: {
-    version: string;
-    os: "macos" | "windows" | "linux" | "unknown";
-  };
-  /** 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. */
-  setImmersiveMode: (immersive: boolean) => Promise<void>;
-}
-
-interface DaemonStatus {
-  state: "running" | "stopped" | "starting" | "stopping" | "installing_cli" | "cli_not_found";
-  pid?: number;
-  uptime?: string;
-  daemonId?: string;
-  deviceName?: string;
-  agents?: string[];
-  workspaceCount?: number;
-  profile?: string;
-  serverUrl?: string;
-}
-
-interface DaemonPrefs {
-  autoStart: boolean;
-  autoStop: boolean;
-}
-
-interface DaemonAPI {
-  start: () => Promise<{ success: boolean; error?: string }>;
-  stop: () => Promise<{ success: boolean; error?: string }>;
-  restart: () => Promise<{ success: boolean; error?: string }>;
-  getStatus: () => Promise<DaemonStatus>;
-  onStatusChange: (callback: (status: DaemonStatus) => void) => () => void;
-  setTargetApiUrl: (url: string) => Promise<void>;
-  syncToken: (token: string, userId: string) => Promise<void>;
-  clearToken: () => Promise<void>;
-  isCliInstalled: () => Promise<boolean>;
-  getPrefs: () => Promise<DaemonPrefs>;
-  setPrefs: (prefs: Partial<DaemonPrefs>) => Promise<DaemonPrefs>;
-  autoStart: () => Promise<void>;
-  retryInstall: () => Promise<void>;
-  startLogStream: () => void;
-  stopLogStream: () => void;
-  onLogLine: (callback: (line: string) => void) => () => void;
-}
-
-interface UpdaterAPI {
-  onUpdateAvailable: (callback: (info: { version: string; releaseNotes?: string }) => void) => () => void;
-  onDownloadProgress: (callback: (progress: { percent: number }) => void) => () => void;
-  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 {
-  interface Window {
-    electron: ElectronAPI;
-    desktopAPI: DesktopAPI;
-    daemonAPI: DaemonAPI;
-    updater: UpdaterAPI;
-  }
-}
-
-export {};

apps/desktop/src/preload/index.ts

@@ -1,144 +0,0 @@
-import { contextBridge, ipcRenderer } from "electron";
-import { electronAPI } from "@electron-toolkit/preload";
-
-// Synchronously fetch app metadata from main at preload time so the renderer
-// can pass it into CoreProvider during the initial render — the alternative
-// (async ipc.invoke) would race the ApiClient construction in initCore and
-// the first few HTTP requests would go out without X-Client-Version/OS.
-function fetchAppInfo(): { version: string; os: "macos" | "windows" | "linux" | "unknown" } {
-  try {
-    const info = ipcRenderer.sendSync("app:get-info") as
-      | { version: string; os: "macos" | "windows" | "linux" | "unknown" }
-      | undefined;
-    if (info && typeof info.version === "string" && typeof info.os === "string") return info;
-  } catch {
-    // fall through
-  }
-  // Fallback: derive OS from process.platform; version unknown.
-  const p = process.platform;
-  const os: "macos" | "windows" | "linux" | "unknown" =
-    p === "darwin" ? "macos" : p === "win32" ? "windows" : p === "linux" ? "linux" : "unknown";
-  return { version: "unknown", os };
-}
-
-const appInfo = fetchAppInfo();
-
-const desktopAPI = {
-  /** App version + normalized OS. Read once at preload time so the renderer
-   *  can use it synchronously when initializing the API client. */
-  appInfo,
-  /** Listen for auth token delivered via deep link */
-  onAuthToken: (callback: (token: string) => void) => {
-    const handler = (_event: Electron.IpcRendererEvent, token: string) =>
-      callback(token);
-    ipcRenderer.on("auth:token", handler);
-    return () => {
-      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 */
-  setImmersiveMode: (immersive: boolean) =>
-    ipcRenderer.invoke("window:setImmersive", immersive),
-};
-
-interface DaemonStatus {
-  state: "running" | "stopped" | "starting" | "stopping" | "installing_cli" | "cli_not_found";
-  pid?: number;
-  uptime?: string;
-  daemonId?: string;
-  deviceName?: string;
-  agents?: string[];
-  workspaceCount?: number;
-  profile?: string;
-  serverUrl?: string;
-}
-
-const daemonAPI = {
-  start: (): Promise<{ success: boolean; error?: string }> =>
-    ipcRenderer.invoke("daemon:start"),
-  stop: (): Promise<{ success: boolean; error?: string }> =>
-    ipcRenderer.invoke("daemon:stop"),
-  restart: (): Promise<{ success: boolean; error?: string }> =>
-    ipcRenderer.invoke("daemon:restart"),
-  getStatus: (): Promise<DaemonStatus> =>
-    ipcRenderer.invoke("daemon:get-status"),
-  onStatusChange: (callback: (status: DaemonStatus) => void) => {
-    const handler = (_: unknown, status: DaemonStatus) => callback(status);
-    ipcRenderer.on("daemon:status", handler);
-    return () => ipcRenderer.removeListener("daemon:status", handler);
-  },
-  setTargetApiUrl: (url: string): Promise<void> =>
-    ipcRenderer.invoke("daemon:set-target-api-url", url),
-  syncToken: (token: string, userId: string): Promise<void> =>
-    ipcRenderer.invoke("daemon:sync-token", token, userId),
-  clearToken: (): Promise<void> =>
-    ipcRenderer.invoke("daemon:clear-token"),
-  isCliInstalled: (): Promise<boolean> =>
-    ipcRenderer.invoke("daemon:is-cli-installed"),
-  getPrefs: (): Promise<{ autoStart: boolean; autoStop: boolean }> =>
-    ipcRenderer.invoke("daemon:get-prefs"),
-  setPrefs: (prefs: Partial<{ autoStart: boolean; autoStop: boolean }>): Promise<{ autoStart: boolean; autoStop: boolean }> =>
-    ipcRenderer.invoke("daemon:set-prefs", prefs),
-  autoStart: (): Promise<void> =>
-    ipcRenderer.invoke("daemon:auto-start"),
-  retryInstall: (): Promise<void> =>
-    ipcRenderer.invoke("daemon:retry-install"),
-  startLogStream: () => ipcRenderer.send("daemon:start-log-stream"),
-  stopLogStream: () => ipcRenderer.send("daemon:stop-log-stream"),
-  onLogLine: (callback: (line: string) => void) => {
-    const handler = (_: unknown, line: string) => callback(line);
-    ipcRenderer.on("daemon:log-line", handler);
-    return () => ipcRenderer.removeListener("daemon:log-line", handler);
-  },
-};
-
-const updaterAPI = {
-  onUpdateAvailable: (callback: (info: { version: string; releaseNotes?: string }) => void) => {
-    const handler = (_: unknown, info: { version: string; releaseNotes?: string }) => callback(info);
-    ipcRenderer.on("updater:update-available", handler);
-    return () => ipcRenderer.removeListener("updater:update-available", handler);
-  },
-  onDownloadProgress: (callback: (progress: { percent: number }) => void) => {
-    const handler = (_: unknown, progress: { percent: number }) => callback(progress);
-    ipcRenderer.on("updater:download-progress", handler);
-    return () => ipcRenderer.removeListener("updater:download-progress", handler);
-  },
-  onUpdateDownloaded: (callback: () => void) => {
-    const handler = () => callback();
-    ipcRenderer.on("updater:update-downloaded", handler);
-    return () => ipcRenderer.removeListener("updater:update-downloaded", handler);
-  },
-  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) {
-  contextBridge.exposeInMainWorld("electron", electronAPI);
-  contextBridge.exposeInMainWorld("desktopAPI", desktopAPI);
-  contextBridge.exposeInMainWorld("daemonAPI", daemonAPI);
-  contextBridge.exposeInMainWorld("updater", updaterAPI);
-} else {
-  // @ts-expect-error - fallback for non-isolated context
-  window.electron = electronAPI;
-  // @ts-expect-error - fallback for non-isolated context
-  window.desktopAPI = desktopAPI;
-  // @ts-expect-error - fallback for non-isolated context
-  window.daemonAPI = daemonAPI;
-  // @ts-expect-error - fallback for non-isolated context
-  window.updater = updaterAPI;
-}

apps/desktop/src/renderer/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en" class="h-full">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Multica</title>
-  </head>
-  <body class="h-full overflow-hidden antialiased font-sans">
-    <div id="root" class="h-full"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>

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

@@ -1,227 +0,0 @@
-import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
-import { useQuery, 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 { api } from "@multica/core/api";
-import { useHasOnboarded } from "@multica/core/paths";
-import { ThemeProvider } from "@multica/ui/components/common/theme-provider";
-import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
-import { Toaster } from "sonner";
-import { DesktopLoginPage } from "./pages/login";
-import { DesktopShell } from "./components/desktop-layout";
-import { PageviewTracker } from "./components/pageview-tracker";
-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);
-  const isLoading = useAuthStore((s) => s.isLoading);
-  const qc = useQueryClient();
-  // Deep-link login runs loginWithToken → syncToken → listWorkspaces →
-  // setQueryData sequentially. loginWithToken sets user+isLoading=false
-  // as soon as getMe resolves, which would cause DesktopShell to mount
-  // 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.
-  const [bootstrapping, setBootstrapping] = useState(false);
-
-  // Tell the main process which backend URL we talk to, so daemon-manager
-  // can pick the matching CLI profile (server_url from ~/.multica config).
-  useEffect(() => {
-    window.daemonAPI.setTargetApiUrl(DAEMON_TARGET_API_URL);
-  }, []);
-
-  // 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).
-  useEffect(() => {
-    return window.desktopAPI.onAuthToken(async (token) => {
-      setBootstrapping(true);
-      try {
-        await useAuthStore.getState().loginWithToken(token);
-        // Seed React Query cache with the workspace list so the index-route
-        // redirect (routes.tsx `IndexRedirect`) can resolve the initial
-        // destination without a second fetch. Workspace side-effects
-        // (setCurrentWorkspace, persist namespace) are synced later by
-        // WorkspaceRouteLayout when the URL resolves.
-        const wsList = await api.listWorkspaces();
-        qc.setQueryData(workspaceKeys.list(), wsList);
-      } catch {
-        // Token invalid or expired — user stays on login page
-      } finally {
-        setBootstrapping(false);
-      }
-    });
-  }, [qc]);
-
-  // Sync token and start the daemon whenever the user logs in.
-  useEffect(() => {
-    if (!user) return;
-    const token = localStorage.getItem("multica_token");
-    if (!token) return;
-    const userId = user.id;
-    (async () => {
-      try {
-        await window.daemonAPI.syncToken(token, userId);
-        await window.daemonAPI.autoStart();
-      } catch (err) {
-        console.error("Failed to sync daemon on login", err);
-      }
-    })();
-  }, [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;
-  const hasOnboarded = useHasOnboarded();
-
-  // Onboarding and zero-workspace both resolve to an overlay, but
-  // onboarding wins: a user who hasn't completed it gets the onboarding
-  // overlay regardless of how many workspaces already exist.
-  useEffect(() => {
-    if (!user || !workspaceListFetched) return;
-    const { overlay, open } = useWindowOverlayStore.getState();
-    if (overlay) return;
-    if (!hasOnboarded) {
-      open({ type: "onboarding" });
-      return;
-    }
-    if (wsCount === 0) {
-      open({ type: "new-workspace" });
-    }
-  }, [user, workspaceListFetched, wsCount, workspaces, hasOnboarded]);
-
-  // Validate persisted tab state against the current user's workspace list,
-  // and pick an active workspace if none is set. Runs in useLayoutEffect
-  // (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.
-  //
-  // Gate on `workspaceListFetched`: useQuery defaults `data` to `[]` before
-  // the first fetch, so without this guard we'd run validation against an
-  // empty slug set, wipe the persisted `activeWorkspaceSlug`, then fall
-  // back to `workspaces[0]` once the real list arrives — losing the user's
-  // last-opened workspace on every app start.
-  useLayoutEffect(() => {
-    if (!workspaceListFetched) return;
-    const validSlugs = new Set(workspaces.map((w) => w.slug));
-    useTabStore.getState().validateWorkspaceSlugs(validSlugs);
-    const { activeWorkspaceSlug, switchWorkspace } = useTabStore.getState();
-    if (!activeWorkspaceSlug && workspaces.length > 0) {
-      switchWorkspace(workspaces[0].slug);
-    }
-  }, [workspaces, workspaceListFetched]);
-
-  // 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">
-        <MulticaIcon className="size-6 animate-pulse" />
-      </div>
-    );
-  }
-
-  // Pageview tracker sits at the app root so it covers every visible
-  // surface (login, overlays, tab paths) — mounting it inside DesktopShell
-  // would miss the logged-out and overlay states.
-  return (
-    <>
-      <PageviewTracker />
-      {user ? <DesktopShell /> : <DesktopLoginPage />}
-    </>
-  );
-}
-
-// Backend the daemon should connect to — same URL the renderer talks to.
-const DAEMON_TARGET_API_URL =
-  import.meta.env.VITE_API_URL || "http://localhost:8080";
-
-// On logout, wipe desktop-only in-memory state and stop the daemon so that
-// a subsequent login as a different user never inherits the previous user's
-// 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.
-async function handleDaemonLogout() {
-  useTabStore.getState().reset();
-  useWindowOverlayStore.getState().close();
-  try {
-    await window.daemonAPI.clearToken();
-  } catch {
-    // Best-effort — clearing is followed by stop which also hardens state.
-  }
-  try {
-    await window.daemonAPI.stop();
-  } catch {
-    // Daemon may already be stopped.
-  }
-}
-
-export default function App() {
-  const { version, os } = window.desktopAPI.appInfo;
-  // Stable identity reference so downstream effects (WS reconnect) don't
-  // tear down on every parent render.
-  const identity = useMemo(
-    () => ({ platform: "desktop", version, os }),
-    [version, os],
-  );
-  return (
-    <ThemeProvider>
-      <CoreProvider
-        apiBaseUrl={import.meta.env.VITE_API_URL || "http://localhost:8080"}
-        wsUrl={import.meta.env.VITE_WS_URL || "ws://localhost:8080/ws"}
-        onLogout={handleDaemonLogout}
-        identity={identity}
-      >
-        <AppContent />
-      </CoreProvider>
-      <Toaster />
-      <UpdateNotification />
-    </ThemeProvider>
-  );
-}

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

@@ -1,309 +0,0 @@
-import { useState, useEffect, useRef, useCallback } from "react";
-import {
-  Play,
-  Square,
-  RotateCw,
-  Server,
-  ChevronDown,
-  X,
-} from "lucide-react";
-import { cn } from "@multica/ui/lib/utils";
-import { Button } from "@multica/ui/components/ui/button";
-import { toast } from "sonner";
-import {
-  Sheet,
-  SheetContent,
-  SheetHeader,
-  SheetTitle,
-} from "@multica/ui/components/ui/sheet";
-import type { DaemonStatus, DaemonState } from "../../../shared/daemon-types";
-import { DAEMON_STATE_COLORS, DAEMON_STATE_LABELS } from "../../../shared/daemon-types";
-
-interface DaemonPanelProps {
-  open: boolean;
-  onOpenChange: (open: boolean) => void;
-  status: DaemonStatus;
-}
-
-const LOG_LEVEL_COLORS: Record<string, string> = {
-  INFO: "text-info",
-  WARN: "text-warning",
-  ERROR: "text-destructive",
-  DEBUG: "text-muted-foreground",
-};
-
-function colorizeLogLine(line: string): { level: string; className: string } {
-  for (const [level, className] of Object.entries(LOG_LEVEL_COLORS)) {
-    if (line.includes(level)) return { level, className };
-  }
-  return { level: "", className: "text-muted-foreground" };
-}
-
-function InfoRow({ label, value }: { label: string; value: React.ReactNode }) {
-  return (
-    <div className="flex items-baseline justify-between gap-4 py-1">
-      <span className="shrink-0 text-xs text-muted-foreground">{label}</span>
-      <span className="truncate text-right text-sm">{value}</span>
-    </div>
-  );
-}
-
-function StatusDot({ state }: { state: DaemonState }) {
-  return <span className={cn("inline-block size-2 rounded-full", DAEMON_STATE_COLORS[state])} />;
-}
-
-interface LogEntry {
-  id: number;
-  line: string;
-}
-
-const MAX_LOG_LINES = 500;
-let logIdCounter = 0;
-
-export function DaemonPanel({ open, onOpenChange, status }: DaemonPanelProps) {
-  const [logs, setLogs] = useState<LogEntry[]>([]);
-  const [autoScroll, setAutoScroll] = useState(true);
-  const [actionLoading, setActionLoading] = useState(false);
-  const logContainerRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!open) return;
-
-    window.daemonAPI.startLogStream();
-    const unsub = window.daemonAPI.onLogLine((line) => {
-      setLogs((prev) => {
-        const next = [...prev, { id: ++logIdCounter, line }];
-        return next.length > MAX_LOG_LINES ? next.slice(-MAX_LOG_LINES) : next;
-      });
-    });
-
-    return () => {
-      unsub();
-      window.daemonAPI.stopLogStream();
-    };
-  }, [open]);
-
-  useEffect(() => {
-    if (autoScroll && logContainerRef.current) {
-      logContainerRef.current.scrollTop = logContainerRef.current.scrollHeight;
-    }
-  }, [logs, autoScroll]);
-
-  const handleLogScroll = useCallback(() => {
-    const el = logContainerRef.current;
-    if (!el) return;
-    const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 40;
-    setAutoScroll(atBottom);
-  }, []);
-
-  const scrollToBottom = useCallback(() => {
-    if (logContainerRef.current) {
-      logContainerRef.current.scrollTop = logContainerRef.current.scrollHeight;
-      setAutoScroll(true);
-    }
-  }, []);
-
-  const handleStart = useCallback(async () => {
-    setActionLoading(true);
-    const result = await window.daemonAPI.start();
-    setActionLoading(false);
-    if (!result.success) {
-      toast.error("Failed to start daemon", { description: result.error });
-    }
-  }, []);
-
-  const handleStop = useCallback(async () => {
-    setActionLoading(true);
-    const result = await window.daemonAPI.stop();
-    setActionLoading(false);
-    if (!result.success) {
-      toast.error("Failed to stop daemon", { description: result.error });
-    }
-  }, []);
-
-  const handleRestart = useCallback(async () => {
-    setActionLoading(true);
-    const result = await window.daemonAPI.restart();
-    setActionLoading(false);
-    if (!result.success) {
-      toast.error("Failed to restart daemon", { description: result.error });
-    }
-  }, []);
-
-  const isTransitioning = status.state === "starting" || status.state === "stopping";
-
-  return (
-    <Sheet open={open} onOpenChange={onOpenChange}>
-      <SheetContent
-        side="right"
-        className="flex flex-col sm:max-w-md"
-        showCloseButton={false}
-        style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
-      >
-        <SheetHeader className="flex-row items-center justify-between gap-2 pr-3">
-          <SheetTitle className="flex items-center gap-2">
-            <Server className="size-4" />
-            Local Daemon
-          </SheetTitle>
-          <button
-            type="button"
-            onClick={() => onOpenChange(false)}
-            aria-label="Close"
-            className="flex size-7 shrink-0 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-          >
-            <X className="size-4" />
-          </button>
-        </SheetHeader>
-
-        <div className="flex-1 min-h-0 flex flex-col gap-4 px-4">
-          <div className="shrink-0 space-y-4">
-          {/* Status info */}
-          <div className="rounded-lg border p-3 space-y-0.5">
-            <InfoRow
-              label="Status"
-              value={
-                <span className="flex items-center gap-1.5">
-                  <StatusDot state={status.state} />
-                  {DAEMON_STATE_LABELS[status.state]}
-                </span>
-              }
-            />
-            {status.uptime && <InfoRow label="Uptime" value={status.uptime} />}
-            <InfoRow label="Profile" value={status.profile || "default"} />
-            {status.serverUrl && (
-              <InfoRow
-                label="Server"
-                value={
-                  <span className="font-mono text-xs" title={status.serverUrl}>
-                    {status.serverUrl}
-                  </span>
-                }
-              />
-            )}
-            {status.agents && status.agents.length > 0 && (
-              <InfoRow label="Agents" value={status.agents.join(", ")} />
-            )}
-            {status.deviceName && <InfoRow label="Device" value={status.deviceName} />}
-            {status.daemonId && (
-              <InfoRow
-                label="Daemon ID"
-                value={<span className="font-mono text-xs">{status.daemonId}</span>}
-              />
-            )}
-            {typeof status.workspaceCount === "number" && (
-              <InfoRow label="Workspaces" value={status.workspaceCount} />
-            )}
-            {status.pid && (
-              <InfoRow
-                label="PID"
-                value={<span className="font-mono text-xs">{status.pid}</span>}
-              />
-            )}
-          </div>
-
-          {/* Actions */}
-          {status.state === "installing_cli" ? (
-            <div className="rounded-lg border border-dashed p-3 text-sm text-muted-foreground">
-              Setting up the local runtime… this only happens the first time.
-            </div>
-          ) : status.state === "cli_not_found" ? (
-            <div className="rounded-lg border border-destructive/40 bg-destructive/5 p-3 space-y-2">
-              <p className="text-sm">
-                Couldn&apos;t download the local runtime. Check your network
-                connection and try again.
-              </p>
-              <Button
-                size="sm"
-                variant="outline"
-                onClick={async () => {
-                  setActionLoading(true);
-                  try {
-                    await window.daemonAPI.retryInstall();
-                  } finally {
-                    setActionLoading(false);
-                  }
-                }}
-                disabled={actionLoading}
-              >
-                <RotateCw className="size-3.5 mr-1.5" />
-                Retry
-              </Button>
-            </div>
-          ) : (
-            <div className="flex gap-2">
-              {status.state === "stopped" ? (
-                <Button size="sm" onClick={handleStart} disabled={actionLoading}>
-                  <Play className="size-3.5 mr-1.5" />
-                  Start
-                </Button>
-              ) : (
-                <>
-                  <Button
-                    variant="outline"
-                    size="sm"
-                    onClick={handleStop}
-                    disabled={actionLoading || isTransitioning}
-                  >
-                    <Square className="size-3.5 mr-1.5" />
-                    Stop
-                  </Button>
-                  <Button
-                    variant="outline"
-                    size="sm"
-                    onClick={handleRestart}
-                    disabled={actionLoading || isTransitioning}
-                  >
-                    <RotateCw className="size-3.5 mr-1.5" />
-                    Restart
-                  </Button>
-                </>
-              )}
-            </div>
-          )}
-
-          </div>
-
-          {/* Logs — fills remaining vertical space down to the sheet bottom */}
-          <div className="flex-1 min-h-0 flex flex-col gap-2 pb-4">
-            <div className="flex items-center justify-between shrink-0">
-              <h3 className="text-sm font-medium">Logs</h3>
-              {!autoScroll && (
-                <Button
-                  variant="ghost"
-                  size="sm"
-                  className="h-6 px-2 text-xs"
-                  onClick={scrollToBottom}
-                >
-                  <ChevronDown className="size-3 mr-1" />
-                  Scroll to bottom
-                </Button>
-              )}
-            </div>
-            <div
-              ref={logContainerRef}
-              onScroll={handleLogScroll}
-              className="flex-1 min-h-0 overflow-y-auto rounded-lg border bg-muted/30 p-2 font-mono text-xs leading-relaxed"
-            >
-              {logs.length === 0 ? (
-                <p className="text-muted-foreground/50 text-center py-8">
-                  {status.state === "running"
-                    ? "Waiting for logs…"
-                    : "Start the daemon to see logs"}
-                </p>
-              ) : (
-                logs.map((entry) => {
-                  const { className } = colorizeLogLine(entry.line);
-                  return (
-                    <div key={entry.id} className={cn("whitespace-pre-wrap break-all", className)}>
-                      {entry.line}
-                    </div>
-                  );
-                })
-              )}
-            </div>
-          </div>
-        </div>
-      </SheetContent>
-    </Sheet>
-  );
-}

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

@@ -1,155 +0,0 @@
-import { useState, useEffect, useCallback } from "react";
-import {
-  Play,
-  Square,
-  RotateCw,
-  Server,
-  Activity,
-} from "lucide-react";
-import { cn } from "@multica/ui/lib/utils";
-import { Button } from "@multica/ui/components/ui/button";
-import { toast } from "sonner";
-import { DaemonPanel } from "./daemon-panel";
-import type { DaemonStatus } from "../../../shared/daemon-types";
-import { DAEMON_STATE_COLORS, DAEMON_STATE_LABELS, formatUptime } from "../../../shared/daemon-types";
-
-export function DaemonRuntimeCard() {
-  const [status, setStatus] = useState<DaemonStatus>({ state: "stopped" });
-  const [panelOpen, setPanelOpen] = useState(false);
-  const [actionLoading, setActionLoading] = useState(false);
-
-  useEffect(() => {
-    window.daemonAPI.getStatus().then((s) => setStatus(s));
-    const unsub = window.daemonAPI.onStatusChange((s) => {
-      setStatus(s);
-      setActionLoading(false);
-    });
-    return unsub;
-  }, []);
-
-  const handleStart = useCallback(async () => {
-    setActionLoading(true);
-    const result = await window.daemonAPI.start();
-    if (!result.success) {
-      setActionLoading(false);
-      toast.error("Failed to start daemon", { description: result.error });
-    }
-  }, []);
-
-  const handleStop = useCallback(async () => {
-    setActionLoading(true);
-    const result = await window.daemonAPI.stop();
-    if (!result.success) {
-      toast.error("Failed to stop daemon", { description: result.error });
-    }
-  }, []);
-
-  const handleRestart = useCallback(async () => {
-    setActionLoading(true);
-    const result = await window.daemonAPI.restart();
-    if (!result.success) {
-      toast.error("Failed to restart daemon", { description: result.error });
-    }
-  }, []);
-
-  const isTransitioning = status.state === "starting" || status.state === "stopping";
-  const isRunning = status.state === "running";
-  const isStopped = status.state === "stopped" || status.state === "cli_not_found";
-
-  const stopPropagation = (e: React.MouseEvent) => e.stopPropagation();
-
-  return (
-    <>
-      <div
-        role="button"
-        tabIndex={0}
-        onClick={() => setPanelOpen(true)}
-        onKeyDown={(e) => {
-          if (e.key === "Enter" || e.key === " ") {
-            e.preventDefault();
-            setPanelOpen(true);
-          }
-        }}
-        className="border-b px-4 py-3 cursor-pointer transition-colors hover:bg-muted/40 focus-visible:outline-none focus-visible:bg-muted/40"
-      >
-        <div className="flex items-start justify-between gap-3">
-          <div className="flex items-center gap-2.5">
-            <div className="flex size-8 items-center justify-center rounded-lg bg-muted">
-              <Server className="size-4 text-muted-foreground" />
-            </div>
-            <div>
-              <h3 className="text-sm font-medium">Local Daemon</h3>
-              <div className="flex items-center gap-1.5 mt-0.5">
-                <span className={cn("size-1.5 rounded-full", DAEMON_STATE_COLORS[status.state])} />
-                <span className="text-xs text-muted-foreground">{DAEMON_STATE_LABELS[status.state]}</span>
-                {isRunning && status.uptime && (
-                  <>
-                    <span className="text-xs text-muted-foreground">·</span>
-                    <span className="text-xs text-muted-foreground">{formatUptime(status.uptime)}</span>
-                  </>
-                )}
-                {isRunning && status.agents && status.agents.length > 0 && (
-                  <>
-                    <span className="text-xs text-muted-foreground">·</span>
-                    <span className="text-xs text-muted-foreground">{status.agents.join(", ")}</span>
-                  </>
-                )}
-              </div>
-            </div>
-          </div>
-
-          <div
-            className="flex items-center gap-1.5 shrink-0"
-            onClick={stopPropagation}
-          >
-            {isStopped && (
-              <Button
-                size="sm"
-                variant="outline"
-                onClick={handleStart}
-                disabled={actionLoading || status.state === "cli_not_found"}
-              >
-                {actionLoading ? (
-                  <Activity className="size-3.5 mr-1.5 animate-pulse" />
-                ) : (
-                  <Play className="size-3.5 mr-1.5" />
-                )}
-                Start
-              </Button>
-            )}
-            {isRunning && (
-              <>
-                <Button
-                  size="sm"
-                  variant="ghost"
-                  onClick={handleRestart}
-                  disabled={actionLoading}
-                >
-                  <RotateCw className="size-3.5 mr-1.5" />
-                  Restart
-                </Button>
-                <Button
-                  size="sm"
-                  variant="outline"
-                  onClick={handleStop}
-                  disabled={actionLoading}
-                >
-                  <Square className="size-3.5 mr-1.5" />
-                  Stop
-                </Button>
-              </>
-            )}
-            {isTransitioning && (
-              <Button size="sm" variant="outline" disabled>
-                <Activity className="size-3.5 mr-1.5 animate-pulse" />
-                {DAEMON_STATE_LABELS[status.state]}
-              </Button>
-            )}
-          </div>
-        </div>
-      </div>
-
-      <DaemonPanel open={panelOpen} onOpenChange={setPanelOpen} status={status} />
-    </>
-  );
-}

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

@@ -1,103 +0,0 @@
-import { useState, useEffect, useCallback } from "react";
-import { Button } from "@multica/ui/components/ui/button";
-import { Switch } from "@multica/ui/components/ui/switch";
-import type { DaemonPrefs } from "../../../shared/daemon-types";
-
-function SettingRow({
-  label,
-  description,
-  children,
-}: {
-  label: string;
-  description: string;
-  children: React.ReactNode;
-}) {
-  return (
-    <div className="flex items-center justify-between gap-6 py-4">
-      <div className="min-w-0">
-        <p className="text-sm font-medium">{label}</p>
-        <p className="text-sm text-muted-foreground mt-0.5">{description}</p>
-      </div>
-      <div className="shrink-0">{children}</div>
-    </div>
-  );
-}
-
-export function DaemonSettingsTab() {
-  const [prefs, setPrefs] = useState<DaemonPrefs>({ autoStart: true, autoStop: false });
-  const [cliInstalled, setCliInstalled] = useState<boolean | null>(null);
-  const [saving, setSaving] = useState(false);
-
-  useEffect(() => {
-    window.daemonAPI.getPrefs().then(setPrefs);
-    window.daemonAPI.isCliInstalled().then(setCliInstalled);
-  }, []);
-
-  const updatePref = useCallback(
-    async (key: keyof DaemonPrefs, value: boolean) => {
-      setSaving(true);
-      const updated = await window.daemonAPI.setPrefs({ [key]: value });
-      setPrefs(updated);
-      setSaving(false);
-    },
-    [],
-  );
-
-  return (
-    <div>
-      <h2 className="text-lg font-semibold">Daemon</h2>
-      <p className="text-sm text-muted-foreground mt-1">
-        Configure how the local agent daemon behaves with the desktop app.
-      </p>
-
-      <div className="mt-6 divide-y">
-        <SettingRow
-          label="Auto-start on launch"
-          description="Automatically start the daemon when the app opens and you are logged in."
-        >
-          <Switch
-            checked={prefs.autoStart}
-            onCheckedChange={(checked) => updatePref("autoStart", checked)}
-            disabled={saving}
-          />
-        </SettingRow>
-
-        <SettingRow
-          label="Auto-stop on quit"
-          description="Stop the daemon when the desktop app is closed. Disable this to keep the daemon running in the background."
-        >
-          <Switch
-            checked={prefs.autoStop}
-            onCheckedChange={(checked) => updatePref("autoStop", checked)}
-            disabled={saving}
-          />
-        </SettingRow>
-
-        <div className="py-4">
-          <p className="text-sm font-medium">CLI Status</p>
-          <p className="text-sm text-muted-foreground mt-1">
-            {cliInstalled === null
-              ? "Checking…"
-              : cliInstalled
-                ? "multica CLI is installed and available in PATH."
-                : "multica CLI not found. Install it to enable daemon management."}
-          </p>
-          {cliInstalled === false && (
-            <Button
-              variant="outline"
-              size="sm"
-              className="mt-2"
-              onClick={() =>
-                window.desktopAPI.openExternal(
-                  "https://github.com/multica-ai/multica#cli-installation",
-                )
-              }
-            >
-              Installation Guide
-            </Button>
-          )}
-        </div>
-      </div>
-    </div>
-  );
-}

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

@@ -1,143 +0,0 @@
-import { useEffect, useSyncExternalStore } from "react";
-import { ChevronLeft, ChevronRight } from "lucide-react";
-import { cn } from "@multica/ui/lib/utils";
-import { useTabHistory } from "@/hooks/use-tab-history";
-import { useActiveTitleSync } from "@/hooks/use-tab-sync";
-import { useTabStore, resolveRouteIcon } from "@/stores/tab-store";
-import {
-  SidebarProvider,
-  SidebarTrigger,
-  useSidebar,
-} from "@multica/ui/components/ui/sidebar";
-import { ModalRegistry } from "@multica/views/modals/registry";
-import { AppSidebar } from "@multica/views/layout";
-import { SearchCommand, SearchTrigger } from "@multica/views/search";
-import { ChatFab, ChatWindow } from "@multica/views/chat";
-import { StarterContentPrompt } from "@multica/views/onboarding";
-import { WorkspaceSlugProvider } from "@multica/core/paths";
-import { getCurrentSlug, subscribeToCurrentSlug } from "@multica/core/platform";
-import { DesktopNavigationProvider } from "@/platform/navigation";
-import { TabBar } from "./tab-bar";
-import { TabContent } from "./tab-content";
-import { WindowOverlay } from "./window-overlay";
-
-function SidebarTopBar() {
-  const { canGoBack, canGoForward, goBack, goForward } = useTabHistory();
-
-  return (
-    <div
-      className="h-12 shrink-0 flex items-center justify-end px-2"
-      style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
-    >
-      <div
-        className="flex items-center gap-0.5"
-        style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
-      >
-        <button
-          onClick={goBack}
-          disabled={!canGoBack}
-          aria-label="Go back"
-          className="flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-30 disabled:pointer-events-none"
-        >
-          <ChevronLeft className="size-4" />
-        </button>
-        <button
-          onClick={goForward}
-          disabled={!canGoForward}
-          aria-label="Go forward"
-          className="flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-30 disabled:pointer-events-none"
-        >
-          <ChevronRight className="size-4" />
-        </button>
-      </div>
-    </div>
-  );
-}
-
-// The main area's top bar doubles as a window drag region. When the sidebar
-// is not occupying main-flow width — either user-collapsed (offcanvas) or
-// auto-hidden in mobile mode (<768px, becomes a sheet drawer) — we pad the
-// left side so tabs don't land under the macOS traffic lights (which live at
-// roughly x=16..68 and always hit-test above HTML), and surface a trigger so
-// the sidebar can be brought back without keyboard shortcut.
-function MainTopBar() {
-  const { state, isMobile } = useSidebar();
-  const sidebarHidden = state === "collapsed" || isMobile;
-
-  return (
-    <header
-      className={cn(
-        "h-12 shrink-0 flex items-center gap-2",
-        sidebarHidden && "pl-20",
-      )}
-      style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
-    >
-      {sidebarHidden && (
-        <SidebarTrigger
-          style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
-        />
-      )}
-      <TabBar />
-    </header>
-  );
-}
-
-function useInternalLinkHandler() {
-  useEffect(() => {
-    const handler = (e: Event) => {
-      const path = (e as CustomEvent).detail?.path;
-      if (!path) return;
-      const icon = resolveRouteIcon(path);
-      const store = useTabStore.getState();
-      const tabId = store.openTab(path, path, icon);
-      store.setActiveTab(tabId);
-    };
-    window.addEventListener("multica:navigate", handler);
-    return () => window.removeEventListener("multica:navigate", handler);
-  }, []);
-}
-
-export function DesktopShell() {
-  useInternalLinkHandler();
-  useActiveTitleSync();
-
-  // Reactive read of current workspace slug from the platform singleton.
-  // On first mount, slug is null until WorkspaceRouteLayout (inside the tab
-  // router) sets it. Once set, the sidebar and other shell-level components
-  // can resolve workspace-scoped paths via useWorkspacePaths().
-  const slug = useSyncExternalStore(subscribeToCurrentSlug, getCurrentSlug, () => null);
-
-  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 />}
-              </div>
-            </div>
-          </SidebarProvider>
-        </div>
-        {slug && <ModalRegistry />}
-        {slug && <SearchCommand />}
-        {slug && <StarterContentPrompt />}
-        <WindowOverlay />
-      </WorkspaceSlugProvider>
-    </DesktopNavigationProvider>
-  );
-}

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

@@ -1,39 +0,0 @@
-import { useEffect, useState } from "react";
-import { RuntimesPage } from "@multica/views/runtimes";
-import { DaemonRuntimeCard } from "./daemon-runtime-card";
-import type { DaemonStatus } from "../../../shared/daemon-types";
-
-/**
- * Desktop wrapper around the shared `RuntimesPage`. Bridges the Electron
- * `daemonAPI` (main-process daemon state) into the page so its empty
- * state can distinguish "no runtime registered" from "runtime is on its
- * way" — without the bundled daemon's status, the page shows a
- * misleading "Run multica daemon start" hint during the few seconds
- * between page load and the daemon's first registration.
- *
- * `bootstrapping` is true while the daemon is installing, starting, or
- * already running but hasn't surfaced as a server-side runtime yet.
- * RuntimeList only shows the spinner when the runtime list is also
- * empty, so once the daemon registers (and the list fills) the flag
- * has no visible effect.
- */
-export function DesktopRuntimesPage() {
-  const [status, setStatus] = useState<DaemonStatus>({ state: "stopped" });
-
-  useEffect(() => {
-    window.daemonAPI.getStatus().then(setStatus);
-    return window.daemonAPI.onStatusChange(setStatus);
-  }, []);
-
-  const bootstrapping =
-    status.state === "installing_cli" ||
-    status.state === "starting" ||
-    status.state === "running";
-
-  return (
-    <RuntimesPage
-      topSlot={<DaemonRuntimeCard />}
-      bootstrapping={bootstrapping}
-    />
-  );
-}

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

@@ -1,69 +0,0 @@
-import { useEffect } from "react";
-import { capturePageview } from "@multica/core/analytics";
-import { useAuthStore } from "@multica/core/auth";
-import { useTabStore } from "@/stores/tab-store";
-import { useWindowOverlayStore, type WindowOverlay } from "@/stores/window-overlay-store";
-
-/**
- * Fires a PostHog $pageview whenever the user's visible surface changes.
- *
- * Desktop has three layers that can own the visible page:
- *
- *   1. Logged-out state → `/login`. No workspace context, no tabs.
- *   2. Window overlays (onboarding, new-workspace, invite) → synthetic paths
- *      that match the equivalent web routes. Overlays are NOT tab routes on
- *      desktop (see `stores/window-overlay-store.ts` + `routes.tsx`), so the
- *      tab path alone would either miss them or mislabel them as "/".
- *   3. Otherwise → the active tab's path (workspace-scoped, e.g.
- *      `/acme/issues/123`). Kept in sync by `useTabRouterSync`.
- *
- * The overlay takes precedence over the tab path because it is visually in
- * front of the tab system; the logged-out state shadows both because the
- * shell doesn't render at all yet. This keeps the `$pageview` stream aligned
- * with what the user actually sees.
- *
- * PostHog's `capture_pageview: true` auto-capture is intentionally off (see
- * `initAnalytics`) so this component owns the event shape, matching the web
- * implementation in `apps/web/components/pageview-tracker.tsx`.
- */
-export function PageviewTracker() {
-  const user = useAuthStore((s) => s.user);
-  const overlay = useWindowOverlayStore((s) => s.overlay);
-  const activeTabPath = useTabStore((s) => {
-    const slug = s.activeWorkspaceSlug;
-    if (!slug) return null;
-    const group = s.byWorkspace[slug];
-    if (!group) return null;
-    return group.tabs.find((t) => t.id === group.activeTabId)?.path ?? null;
-  });
-
-  const path = resolvePath(user, overlay, activeTabPath);
-
-  useEffect(() => {
-    if (!path) return;
-    capturePageview(path);
-  }, [path]);
-
-  return null;
-}
-
-function resolvePath(
-  user: unknown,
-  overlay: WindowOverlay | null,
-  activeTabPath: string | null,
-): string | null {
-  if (!user) return "/login";
-  if (overlay) return overlayPath(overlay);
-  return activeTabPath;
-}
-
-function overlayPath(overlay: WindowOverlay): string {
-  switch (overlay.type) {
-    case "new-workspace":
-      return "/workspaces/new";
-    case "onboarding":
-      return "/onboarding";
-    case "invite":
-      return `/invite/${overlay.invitationId}`;
-  }
-}

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

@@ -1,189 +0,0 @@
-import {
-  Inbox,
-  CircleUser,
-  ListTodo,
-  Bot,
-  Monitor,
-  BookOpenText,
-  Settings,
-  X,
-  Plus,
-  type LucideIcon,
-} from "lucide-react";
-import {
-  DndContext,
-  PointerSensor,
-  useSensor,
-  useSensors,
-  closestCenter,
-  type DragEndEvent,
-} from "@dnd-kit/core";
-import {
-  SortableContext,
-  horizontalListSortingStrategy,
-  useSortable,
-} from "@dnd-kit/sortable";
-import {
-  restrictToHorizontalAxis,
-  restrictToParentElement,
-} 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";
-
-const TAB_ICONS: Record<string, LucideIcon> = {
-  Inbox,
-  CircleUser,
-  ListTodo,
-  Bot,
-  Monitor,
-  BookOpenText,
-  Settings,
-};
-
-function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolean; isOnly: boolean }) {
-  const setActiveTab = useTabStore((s) => s.setActiveTab);
-  const closeTab = useTabStore((s) => s.closeTab);
-
-  const {
-    attributes,
-    listeners,
-    setNodeRef,
-    transform,
-    transition,
-    isDragging,
-  } = useSortable({ id: tab.id });
-
-  const Icon = TAB_ICONS[tab.icon];
-
-  const style = {
-    transform: CSS.Transform.toString(transform),
-    transition,
-    WebkitAppRegion: "no-drag",
-    zIndex: isDragging ? 10 : undefined,
-  } as React.CSSProperties;
-
-  const handleClick = () => {
-    if (isActive) return;
-    setActiveTab(tab.id);
-  };
-
-  const handleClose = (e: React.MouseEvent) => {
-    e.stopPropagation();
-    closeTab(tab.id);
-  };
-
-  const stopDragOnClose = (e: React.PointerEvent) => {
-    e.stopPropagation();
-  };
-
-  return (
-    <button
-      ref={setNodeRef}
-      style={style}
-      {...attributes}
-      {...listeners}
-      onClick={handleClick}
-      className={cn(
-        "group flex h-7 w-40 items-center gap-1.5 rounded-md px-2 text-xs transition-colors",
-        "select-none cursor-default",
-        isActive
-          ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground"
-          : "bg-sidebar-accent/50 text-muted-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
-        isDragging && "opacity-60",
-      )}
-    >
-      {Icon && <Icon className="size-3.5 shrink-0" />}
-      <span
-        className="min-w-0 flex-1 overflow-hidden whitespace-nowrap text-left"
-        style={{
-          maskImage: "linear-gradient(to right, black calc(100% - 12px), transparent)",
-          WebkitMaskImage: "linear-gradient(to right, black calc(100% - 12px), transparent)",
-        }}
-      >
-        {tab.title}
-      </span>
-      {!isOnly && (
-        <span
-          onClick={handleClose}
-          onPointerDown={stopDragOnClose}
-          className="hidden size-3.5 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors group-hover:flex hover:bg-muted-foreground/20 hover:text-foreground"
-        >
-          <X className="size-2.5" />
-        </span>
-      )}
-    </button>
-  );
-}
-
-function NewTabButton() {
-  const addTab = useTabStore((s) => s.addTab);
-  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 tabId = addTab(path, "Issues", resolveRouteIcon(path));
-    if (tabId) setActiveTab(tabId);
-  };
-
-  return (
-    <button
-      onClick={handleClick}
-      style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
-      className="flex size-7 shrink-0 items-center justify-center rounded-md text-muted-foreground/70 transition-colors hover:bg-muted/50 hover:text-muted-foreground"
-    >
-      <Plus className="size-3.5" />
-    </button>
-  );
-}
-
-export function TabBar() {
-  const group = useActiveGroup();
-  const moveTab = useTabStore((s) => s.moveTab);
-
-  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) => {
-    const { active, over } = event;
-    if (!over || active.id === over.id) return;
-    const from = tabs.findIndex((t) => t.id === active.id);
-    const to = tabs.findIndex((t) => t.id === over.id);
-    if (from !== -1 && to !== -1) moveTab(from, to);
-  };
-
-  return (
-    <div className="flex h-full items-center gap-0.5 px-2 justify-start">
-      <DndContext
-        sensors={sensors}
-        collisionDetection={closestCenter}
-        modifiers={[restrictToHorizontalAxis, restrictToParentElement]}
-        onDragEnd={handleDragEnd}
-      >
-        <SortableContext items={tabIds} strategy={horizontalListSortingStrategy}>
-          {tabs.map((tab) => (
-            <SortableTabItem
-              key={tab.id}
-              tab={tab}
-              isActive={tab.id === activeTabId}
-              isOnly={tabs.length === 1}
-            />
-          ))}
-        </SortableContext>
-      </DndContext>
-      {group && <NewTabButton />}
-    </div>
-  );
-}

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

@@ -1,55 +0,0 @@
-import { Activity, useEffect } from "react";
-import { RouterProvider } from "react-router-dom";
-import { useActiveGroup } from "@/stores/tab-store";
-import { TabNavigationProvider } from "@/platform/navigation";
-import { useTabRouterSync } from "@/hooks/use-tab-router-sync";
-import 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);
-  return null;
-}
-
-/**
- * Renders the active workspace's tabs using Activity for state preservation.
- * Only the active tab is visible; hidden tabs keep their DOM and React state.
- *
- * 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();
-
-  // Sync document.title when switching tabs within the active workspace.
-  useEffect(() => {
-    if (!group) return;
-    const tab = group.tabs.find((t) => t.id === group.activeTabId);
-    if (tab) document.title = tab.title;
-  }, [group?.activeTabId, group?.tabs]);
-
-  if (!group) return null;
-
-  return (
-    <>
-      {group.tabs.map((tab) => (
-        <Activity
-          key={tab.id}
-          mode={tab.id === group.activeTabId ? "visible" : "hidden"}
-        >
-          <TabNavigationProvider router={tab.router}>
-            <RouterProvider router={tab.router} />
-            <TabRouterInner tab={tab} />
-          </TabNavigationProvider>
-        </Activity>
-      ))}
-    </>
-  );
-}

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

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

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

@@ -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,79 +0,0 @@
-import { useQuery } from "@tanstack/react-query";
-import { NewWorkspacePage } from "@multica/views/workspace/new-workspace-page";
-import { InvitePage } from "@multica/views/invite";
-import { OnboardingFlow } from "@multica/views/onboarding";
-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 (onboarding, create workspace, accept
- * invite).
- *
- * This component is intentionally thin — just a fixed positioning shell
- * that covers the tab system. It does NOT hide traffic lights or provide
- * a drag strip: each contained view (OnboardingFlow, NewWorkspacePage,
- * InvitePage) renders its own `<DragStrip />` as a flex-child at top so
- * native macOS traffic lights stay visible and the page content can fill
- * the window edge-to-edge. This matches the Linear/Notion/Arc pattern for
- * pre-dashboard flows and keeps platform chrome consistent across every
- * "not-in-dashboard" surface.
- *
- * All UX affordances (Back button, Log out button, welcome copy, invite
- * card) live inside the shared view components under `packages/views/`,
- * so web and desktop render identical content.
- */
-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());
-
-  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 overflow-auto bg-background">
-      {overlay.type === "new-workspace" && (
-        <NewWorkspacePage
-          onSuccess={(ws) => push(paths.workspace(ws.slug).issues())}
-          onBack={onBack}
-        />
-      )}
-      {overlay.type === "invite" && (
-        <InvitePage
-          invitationId={overlay.invitationId}
-          onBack={onBack}
-        />
-      )}
-      {overlay.type === "onboarding" && (
-        <OnboardingFlow
-          onComplete={(ws) => {
-            close();
-            // Post-onboarding landing is always the workspace issues
-            // list. The welcome-issue flow moved into a dialog that
-            // renders on that page (StarterContentPrompt), so the
-            // flow doesn't need to thread a target issue id back here.
-            if (ws) {
-              push(paths.workspace(ws.slug).issues());
-            } else {
-              push(paths.root());
-            }
-          }}
-        />
-      )}
-    </div>
-  );
-}

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

@@ -1,88 +0,0 @@
-import { useEffect } 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,
-  workspaceListOptions,
-} from "@multica/core/workspace";
-import { setCurrentWorkspace } 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).
- */
-export function WorkspaceRouteLayout() {
-  const { workspaceSlug } = useParams<{ workspaceSlug: string }>();
-  const navigate = useNavigate();
-  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) {
-    setCurrentWorkspace(workspaceSlug, workspace.id);
-  }
-
-  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.
-  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 (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}>
-      <Outlet />
-    </WorkspaceSlugProvider>
-  );
-}

apps/desktop/src/renderer/src/env.d.ts

@@ -1 +0,0 @@
-/// <reference types="vite/client" />

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

@@ -1,42 +0,0 @@
-@import "tailwindcss";
-@import "tw-animate-css";
-@import "shadcn/tailwind.css";
-@import "@multica/ui/styles/tokens.css";
-@import "@multica/ui/styles/base.css";
-
-@custom-variant dark (&:is(.dark *));
-
-/* Font stack: Inter for Latin UI text + system Chinese fonts for zh content.
-   Web app uses the same stack via next/font/google in apps/web/app/layout.tsx —
-   keep the CJK fallback tail in sync across both files. The Inter primary family
-   differs by design: next/font produces `__Inter_xxx` (with a synthetic size-adjusted
-   fallback face to prevent FOUT layout shift); desktop uses fontsource's "Inter Variable".
-   Both resolve to Inter glyphs, so rendering is identical in practice.
-   Currently covers English + Simplified Chinese. When ja/ko i18n lands, extend
-   the tail with Hiragino Kaku Gothic ProN / Yu Gothic / Apple SD Gothic Neo / Malgun Gothic.
-   Per-character fallback: Latin chars render with Inter, Chinese chars with
-   PingFang SC (macOS) / Microsoft YaHei (Windows) / Noto Sans CJK SC (Linux).
-
-   Mono font has no explicit CJK fallback: CJK chars in code blocks are inherently
-   non-aligned with a mono grid (Chinese is proportional), so listing CJK fonts
-   would falsely signal alignment guarantees. Browser default fallback handles
-   the rare mixed case correctly. */
-:root {
-  --font-sans: "Inter Variable", "Inter", -apple-system, BlinkMacSystemFont,
-               "Segoe UI", "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC",
-               sans-serif;
-  --font-serif: "Source Serif 4 Variable", "Source Serif 4", "Iowan Old Style",
-                "Apple Garamond", Baskerville, "Times New Roman", serif;
-  --font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Consolas,
-               monospace;
-}
-
-@source "../../../../../packages/ui/**/*.tsx";
-@source "../../../../../packages/core/**/*.{ts,tsx}";
-@source "../../../../../packages/views/**/*.{ts,tsx}";
-@source "./**/*.tsx";
-
-/* Desktop-specific: override sidebar container padding for traffic light layout */
-[data-slot="sidebar-container"] {
-  padding: 0 !important;
-}

apps/desktop/src/renderer/src/hooks/use-document-title.ts

@@ -1,8 +0,0 @@
-import { useEffect } from "react";
-
-/** Sets document.title. The tab system observes this automatically. */
-export function useDocumentTitle(title: string) {
-  useEffect(() => {
-    if (title) document.title = title;
-  }, [title]);
-}

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

@@ -1,40 +0,0 @@
-import { useCallback } from "react";
-import type { DataRouter } from "react-router-dom";
-import { useActiveTabRouter, useActiveTabHistory } from "@/stores/tab-store";
-
-/**
- * Shared hint map so useTabRouterSync can distinguish back vs forward POP.
- * Set before calling router.navigate(-1 | 1), read in the synchronous subscription.
- */
-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.
- */
-export function useTabHistory() {
-  const router = useActiveTabRouter();
-  const { historyIndex, historyLength } = useActiveTabHistory();
-
-  const canGoBack = historyIndex > 0;
-  const canGoForward = historyIndex < historyLength - 1;
-
-  const goBack = useCallback(() => {
-    if (!router || historyIndex <= 0) return;
-    popDirectionHints.set(router, "back");
-    router.navigate(-1);
-  }, [router, historyIndex]);
-
-  const goForward = useCallback(() => {
-    if (!router || historyIndex >= historyLength - 1) return;
-    popDirectionHints.set(router, "forward");
-    router.navigate(1);
-  }, [router, historyIndex, historyLength]);
-
-  return { canGoBack, canGoForward, goBack, goForward };
-}

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

@@ -1,49 +0,0 @@
-import { useEffect, useRef } from "react";
-import type { DataRouter } from "react-router-dom";
-import { useTabStore, resolveRouteIcon } from "@/stores/tab-store";
-import { popDirectionHints } from "./use-tab-history";
-
-/**
- * Subscribe to a tab's memory router and sync path + history tracking
- * back into the tab store.
- *
- * Called once per tab inside its RouterProvider subtree.
- */
-export function useTabRouterSync(tabId: string, router: DataRouter) {
-  const indexRef = useRef(0);
-  const lengthRef = useRef(1);
-
-  useEffect(() => {
-    // Sync initial state
-    const initialPath = router.state.location.pathname;
-    const store = useTabStore.getState();
-    store.updateTab(tabId, { path: initialPath, icon: resolveRouteIcon(initialPath) });
-
-    const unsubscribe = router.subscribe((state) => {
-      const { pathname } = state.location;
-      const action = state.historyAction;
-
-      if (action === "PUSH") {
-        indexRef.current += 1;
-        lengthRef.current = indexRef.current + 1;
-      } else if (action === "POP") {
-        // Determine direction from the hint set by goBack/goForward
-        const hint = popDirectionHints.get(router);
-        popDirectionHints.delete(router);
-        if (hint === "forward") {
-          indexRef.current = Math.min(indexRef.current + 1, lengthRef.current - 1);
-        } else {
-          // Default to back
-          indexRef.current = Math.max(0, indexRef.current - 1);
-        }
-      }
-      // REPLACE: index and length stay the same
-
-      const store = useTabStore.getState();
-      store.updateTab(tabId, { path: pathname, icon: resolveRouteIcon(pathname) });
-      store.updateTabHistory(tabId, indexRef.current, lengthRef.current);
-    });
-
-    return unsubscribe;
-  }, [tabId, router]);
-}

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

@@ -1,32 +0,0 @@
-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.
- */
-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);
-      if (activeTab && activeTab.title !== title) {
-        state.updateTab(activeTab.id, { title });
-      }
-    });
-
-    const titleEl = document.querySelector("title");
-    if (titleEl) {
-      observer.observe(titleEl, { childList: true, characterData: true, subtree: true });
-    }
-
-    return () => observer.disconnect();
-  }, []);
-}

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

@@ -1,16 +0,0 @@
-import ReactDOM from "react-dom/client";
-import App from "./App";
-// Inter variable font covers all weights (100-900) in a single file.
-// Geist Mono kept as-is for code blocks; CJK is handled by system font fallback
-// (see globals.css --font-sans chain). Keep font stack in sync with apps/web/app/layout.tsx.
-import "@fontsource-variable/inter";
-// Editorial serif — matches web's next/font Source_Serif_4. Loaded app-wide so
-// onboarding headings and any future editorial surface can use `font-serif`
-// (see tokens.css @theme inline). Variable font = one file covers all weights.
-import "@fontsource-variable/source-serif-4";
-import "@fontsource-variable/source-serif-4/wght-italic.css";
-import "@fontsource/geist-mono/400.css";
-import "@fontsource/geist-mono/700.css";
-import "./globals.css";
-
-ReactDOM.createRoot(document.getElementById("root")!).render(<App />);

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

@@ -1,17 +0,0 @@
-import { useParams } from "react-router-dom";
-import { useQuery } from "@tanstack/react-query";
-import { AutopilotDetailPage as AutopilotDetail } from "@multica/views/autopilots/components";
-import { useWorkspaceId } from "@multica/core/hooks";
-import { autopilotDetailOptions } from "@multica/core/autopilots/queries";
-import { useDocumentTitle } from "@/hooks/use-document-title";
-
-export function AutopilotDetailPage() {
-  const { id } = useParams<{ id: string }>();
-  const wsId = useWorkspaceId();
-  const { data } = useQuery(autopilotDetailOptions(wsId, id!));
-
-  useDocumentTitle(data ? `⚡ ${data.autopilot.title}` : "Autopilot");
-
-  if (!id) return null;
-  return <AutopilotDetail autopilotId={id} />;
-}

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

@@ -1,17 +0,0 @@
-import { useParams } from "react-router-dom";
-import { useQuery } from "@tanstack/react-query";
-import { IssueDetail } from "@multica/views/issues/components";
-import { useWorkspaceId } from "@multica/core/hooks";
-import { issueDetailOptions } from "@multica/core/issues/queries";
-import { useDocumentTitle } from "@/hooks/use-document-title";
-
-export function IssueDetailPage() {
-  const { id } = useParams<{ id: string }>();
-  const wsId = useWorkspaceId();
-  const { data: issue } = useQuery(issueDetailOptions(wsId, id!));
-
-  useDocumentTitle(issue ? `${issue.identifier}: ${issue.title}` : "Issue");
-
-  if (!id) return null;
-  return <IssueDetail issueId={id} />;
-}

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

@@ -1,29 +0,0 @@
-import { LoginPage } from "@multica/views/auth";
-import { DragStrip } from "@multica/views/platform";
-import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
-
-const WEB_URL = import.meta.env.VITE_APP_URL || "http://localhost:3000";
-
-export function DesktopLoginPage() {
-  const handleGoogleLogin = () => {
-    // Open web login page in the default browser with platform=desktop flag.
-    // The web callback will redirect back via multica:// deep link with the token.
-    window.desktopAPI.openExternal(
-      `${WEB_URL}/login?platform=desktop`,
-    );
-  };
-
-  return (
-    <div className="flex h-screen flex-col">
-      <DragStrip />
-      <LoginPage
-        logo={<MulticaIcon bordered size="lg" />}
-        onSuccess={() => {
-          // Auth store update triggers AppContent re-render → shows DesktopShell.
-          // Initial workspace navigation happens in routes.tsx via IndexRedirect.
-        }}
-        onGoogleLogin={handleGoogleLogin}
-      />
-    </div>
-  );
-}

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

@@ -1,17 +0,0 @@
-import { useParams } from "react-router-dom";
-import { useQuery } from "@tanstack/react-query";
-import { ProjectDetail } from "@multica/views/projects/components";
-import { useWorkspaceId } from "@multica/core/hooks";
-import { projectDetailOptions } from "@multica/core/projects/queries";
-import { useDocumentTitle } from "@/hooks/use-document-title";
-
-export function ProjectDetailPage() {
-  const { id } = useParams<{ id: string }>();
-  const wsId = useWorkspaceId();
-  const { data: project } = useQuery(projectDetailOptions(wsId, id!));
-
-  useDocumentTitle(project ? `${project.icon || "📁"} ${project.title}` : "Project");
-
-  if (!id) return null;
-  return <ProjectDetail projectId={id} />;
-}

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

@@ -1,234 +0,0 @@
-import { useEffect, useMemo, useState } from "react";
-import type { DataRouter } from "react-router-dom";
-import {
-  NavigationProvider,
-  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";
-
-// Public web app URL — injected at build time via .env.production. In dev
-// (no VITE_APP_URL set) falls back to the local web dev server so "Copy
-// link" in a dev build yields a URL that points at the running dev
-// frontend, not the prod host. Matches the fallback used in pages/login.tsx.
-const APP_URL = import.meta.env.VITE_APP_URL || "http://localhost:3000";
-
-/**
- * Extract the leading workspace slug from a path, or null if the path isn't
- * 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 === "/onboarding") {
-    overlay.open({ type: "onboarding" });
-    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).
- *
- * Reads from the active tab's memory router via router.subscribe().
- * Does NOT use any react-router hooks — it's above all RouterProviders.
- */
-export function DesktopNavigationProvider({
-  children,
-}: {
-  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 ?? "/",
-  );
-
-  useEffect(() => {
-    if (!router) {
-      setPathname("/");
-      return;
-    }
-    setPathname(router.state.location.pathname);
-    return router.subscribe((state) => {
-      setPathname(state.location.pathname);
-    });
-  }, [activeTabId, router]);
-
-  const adapter: NavigationAdapter = useMemo(
-    () => ({
-      push: (path: string) => {
-        if (path === "/login") {
-          useAuthStore.getState().logout();
-          return;
-        }
-        const active = currentActiveTab();
-        if (tryRouteToOverlay(path, active?.router)) return;
-        if (tryRouteToOtherWorkspace(path)) return;
-        active?.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 });
-      },
-      back: () => {
-        currentActiveTab()?.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 tabId = store.openTab(path, title ?? path, icon);
-        if (tabId) store.setActiveTab(tabId);
-      },
-      getShareableUrl: (path: string) => `${APP_URL}${path}`,
-    }),
-    [pathname],
-  );
-
-  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.
- *
- * This is what @multica/views page components read via useNavigation().
- */
-export function TabNavigationProvider({
-  router,
-  children,
-}: {
-  router: DataRouter;
-  children: React.ReactNode;
-}) {
-  const [location, setLocation] = useState(router.state.location);
-
-  useEffect(() => {
-    setLocation(router.state.location);
-    return router.subscribe((state) => {
-      setLocation(state.location);
-    });
-  }, [router]);
-
-  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 });
-      },
-      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);
-      },
-      getShareableUrl: (path: string) => `${APP_URL}${path}`,
-    }),
-    [router, location],
-  );
-
-  return <NavigationProvider value={adapter}>{children}</NavigationProvider>;
-}

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

@@ -1,155 +0,0 @@
-import { useEffect } from "react";
-import {
-  createMemoryRouter,
-  Navigate,
-  Outlet,
-  useMatches,
-} from "react-router-dom";
-import type { RouteObject } from "react-router-dom";
-import { IssueDetailPage } from "./pages/issue-detail-page";
-import { ProjectDetailPage } from "./pages/project-detail-page";
-import { AutopilotDetailPage } from "./pages/autopilot-detail-page";
-import { IssuesPage } from "@multica/views/issues/components";
-import { ProjectsPage } from "@multica/views/projects/components";
-import { AutopilotsPage } from "@multica/views/autopilots/components";
-import { MyIssuesPage } from "@multica/views/my-issues";
-import { SkillsPage } from "@multica/views/skills";
-import { DesktopRuntimesPage } from "./components/desktop-runtimes-page";
-import { AgentsPage } from "@multica/views/agents";
-import { InboxPage } from "@multica/views/inbox";
-import { SettingsPage } from "@multica/views/settings";
-import { Download, Server } from "lucide-react";
-import { DaemonSettingsTab } from "./components/daemon-settings-tab";
-import { UpdatesSettingsTab } from "./components/updates-settings-tab";
-import { WorkspaceRouteLayout } from "./components/workspace-route-layout";
-
-/**
- * Sets document.title from the deepest matched route's handle.title.
- * The tab system observes document.title via MutationObserver.
- * Pages with dynamic titles (e.g. issue detail) override by setting
- * document.title directly via useDocumentTitle().
- */
-function TitleSync() {
-  const matches = useMatches();
-  const title = [...matches]
-    .reverse()
-    .find((m) => (m.handle as { title?: string })?.title)
-    ?.handle as { title?: string } | undefined;
-
-  useEffect(() => {
-    if (title?.title) document.title = title.title;
-  }, [title?.title]);
-
-  return null;
-}
-
-/** Wrapper that renders route children + TitleSync */
-function PageShell() {
-  return (
-    <>
-      <TitleSync />
-      <Outlet />
-    </>
-  );
-}
-
-/**
- * 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.
- */
-export const appRoutes: RouteObject[] = [
-  {
-    element: <PageShell />,
-    children: [
-      { index: true, element: null },
-      {
-        path: ":workspaceSlug",
-        element: <WorkspaceRouteLayout />,
-        children: [
-          { index: true, element: <Navigate to="issues" replace /> },
-          { path: "issues", element: <IssuesPage />, handle: { title: "Issues" } },
-          {
-            path: "issues/:id",
-            element: <IssueDetailPage />,
-            handle: { title: "Issue" },
-          },
-          {
-            path: "projects",
-            element: <ProjectsPage />,
-            handle: { title: "Projects" },
-          },
-          {
-            path: "projects/:id",
-            element: <ProjectDetailPage />,
-            handle: { title: "Project" },
-          },
-          {
-            path: "autopilots",
-            element: <AutopilotsPage />,
-            handle: { title: "Autopilot" },
-          },
-          {
-            path: "autopilots/:id",
-            element: <AutopilotDetailPage />,
-            handle: { title: "Autopilot" },
-          },
-          {
-            path: "my-issues",
-            element: <MyIssuesPage />,
-            handle: { title: "My Issues" },
-          },
-          {
-            path: "runtimes",
-            element: <DesktopRuntimesPage />,
-            handle: { title: "Runtimes" },
-          },
-          { path: "skills", element: <SkillsPage />, handle: { title: "Skills" } },
-          { path: "agents", element: <AgentsPage />, handle: { title: "Agents" } },
-          { path: "inbox", element: <InboxPage />, handle: { title: "Inbox" } },
-          {
-            path: "settings",
-            element: (
-              <SettingsPage
-                extraAccountTabs={[
-                  {
-                    value: "daemon",
-                    label: "Daemon",
-                    icon: Server,
-                    content: <DaemonSettingsTab />,
-                  },
-                  {
-                    value: "updates",
-                    label: "Updates",
-                    icon: Download,
-                    content: <UpdatesSettingsTab />,
-                  },
-                ]}
-              />
-            ),
-            handle: { title: "Settings" },
-          },
-        ],
-      },
-    ],
-  },
-];
-
-/** Create an independent memory router for a tab. */
-export function createTabRouter(initialPath: string) {
-  return createMemoryRouter(appRoutes, {
-    initialEntries: [initialPath],
-  });
-}

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

@@ -1,705 +0,0 @@
-import { create } from "zustand";
-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 type { DataRouter } from "react-router-dom";
-import { createTabRouter } from "../routes";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface Tab {
-  id: string;
-  /** Every tab path is workspace-scoped: `/{workspaceSlug}/{route}/...`. */
-  path: string;
-  title: string;
-  icon: string;
-  router: DataRouter;
-  historyIndex: number;
-  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;
-
-  /**
-   * 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. */
-  openTab: (path: string, title: string, icon: string) => string;
-  /** Always creates a new tab (no dedupe) in the active workspace. */
-  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.
-   */
-  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.
-   */
-  setActiveTab: (tabId: string) => void;
-  /** Patch metadata of a tab (router-sync, title-sync). Finds across groups. */
-  updateTab: (tabId: string, patch: Partial<Pick<Tab, "path" | "title" | "icon">>) => void;
-  /** Patch history tracking of a tab. Finds across groups. */
-  updateTabHistory: (tabId: string, historyIndex: number, historyLength: number) => void;
-  /** Reorder within the active workspace's group only. */
-  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;
-}
-
-// ---------------------------------------------------------------------------
-// Route → icon mapping (title comes from document.title, not from here)
-// ---------------------------------------------------------------------------
-
-const ROUTE_ICONS: Record<string, string> = {
-  inbox: "Inbox",
-  "my-issues": "CircleUser",
-  issues: "ListTodo",
-  projects: "FolderKanban",
-  autopilots: "ListTodo",
-  agents: "Bot",
-  runtimes: "Monitor",
-  skills: "BookOpenText",
-  settings: "Settings",
-};
-
-/**
- * Resolve a route icon from a pathname.
- *
- * 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.
- *
- * Title is NOT determined here — it comes from document.title.
- */
-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;
-}
-
-// ---------------------------------------------------------------------------
-// Path sanitization (defensive)
-// ---------------------------------------------------------------------------
-
-/**
- * Defensive: catch paths that don't belong in the tab store.
- *
- * 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.
- */
-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
-// ---------------------------------------------------------------------------
-
-function createId(): string {
-  return createSafeId();
-}
-
-function makeTab(path: string, title: string, icon: string): Tab {
-  return {
-    id: createId(),
-    path,
-    title,
-    icon,
-    router: createTabRouter(path),
-    historyIndex: 0,
-    historyLength: 1,
-  };
-}
-
-/** 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
-// ---------------------------------------------------------------------------
-
-export const useTabStore = create<TabStore>()(
-  persist(
-    (set, get) => ({
-      activeWorkspaceSlug: null,
-      byWorkspace: {},
-
-      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];
-
-        // Decide the desired active path for this workspace.
-        const desiredPath = openPath ?? (existing ? null : defaultPathFor(slug));
-
-        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;
-        }
-
-        // 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;
-          }
-        }
-
-        // No openPath (or openPath was rejected) — just restore the group.
-        set({ activeWorkspaceSlug: slug });
-      },
-
-      openTab(path, title, icon) {
-        const { activeWorkspaceSlug, byWorkspace } = get();
-        const clean = sanitizeTabPath(path);
-        if (!activeWorkspaceSlug || !clean) return "";
-        const group = byWorkspace[activeWorkspaceSlug];
-        if (!group) return "";
-
-        const existing = group.tabs.find((t) => t.path === clean);
-        if (existing) {
-          set({
-            byWorkspace: {
-              ...byWorkspace,
-              [activeWorkspaceSlug]: { ...group, activeTabId: existing.id },
-            },
-          });
-          return existing.id;
-        }
-
-        const tab = makeTab(clean, title, icon);
-        set({
-          byWorkspace: {
-            ...byWorkspace,
-            [activeWorkspaceSlug]: {
-              tabs: [...group.tabs, tab],
-              activeTabId: group.activeTabId,
-            },
-          },
-        });
-        return tab.id;
-      },
-
-      addTab(path, title, icon) {
-        const { activeWorkspaceSlug, byWorkspace } = get();
-        const clean = sanitizeTabPath(path);
-        if (!activeWorkspaceSlug || !clean) return "";
-        const group = byWorkspace[activeWorkspaceSlug];
-        if (!group) return "";
-
-        const tab = makeTab(clean, title, icon);
-        set({
-          byWorkspace: {
-            ...byWorkspace,
-            [activeWorkspaceSlug]: {
-              tabs: [...group.tabs, tab],
-              activeTabId: group.activeTabId,
-            },
-          },
-        });
-        return tab.id;
-      },
-
-      closeTab(tabId) {
-        const { byWorkspace } = get();
-        const hit = findTabLocation(byWorkspace, tabId);
-        if (!hit) return;
-        const { slug, group, index } = hit;
-
-        const closing = group.tabs[index];
-        closing.router.dispose();
-
-        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: {} });
-      },
-    }),
-    {
-      name: "multica_tabs",
-      version: 2,
-      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,
-              ),
-            },
-          ]),
-        ),
-      }),
-      merge: (persistedState, currentState) => {
-        const persisted = persistedState as Partial<V2Persisted> | undefined;
-        if (!persisted?.byWorkspace) 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;
-            }
-            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 };
-        }
-
-        const activeWorkspaceSlug =
-          persisted.activeWorkspaceSlug && byWorkspace[persisted.activeWorkspaceSlug]
-            ? persisted.activeWorkspaceSlug
-            : (Object.keys(byWorkspace)[0] ?? null);
-
-        return { ...currentState, byWorkspace, activeWorkspaceSlug };
-      },
-    },
-  ),
-);
-
-// ---------------------------------------------------------------------------
-// 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,30 +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 }
-  | { type: "onboarding" };
-
-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/desktop/src/shared/daemon-types.ts

@@ -1,53 +0,0 @@
-export type DaemonState =
-  | "running"
-  | "stopped"
-  | "starting"
-  | "stopping"
-  | "installing_cli"
-  | "cli_not_found";
-
-export interface DaemonStatus {
-  state: DaemonState;
-  pid?: number;
-  uptime?: string;
-  daemonId?: string;
-  deviceName?: string;
-  agents?: string[];
-  workspaceCount?: number;
-  /** CLI profile this daemon belongs to. Empty string means the default profile. */
-  profile?: string;
-  /** Backend URL the daemon connects to. */
-  serverUrl?: string;
-}
-
-export interface DaemonPrefs {
-  autoStart: boolean;
-  autoStop: boolean;
-}
-
-export const DAEMON_STATE_COLORS: Record<DaemonState, string> = {
-  running: "bg-emerald-500",
-  stopped: "bg-muted-foreground/40",
-  starting: "bg-amber-500 animate-pulse",
-  stopping: "bg-amber-500 animate-pulse",
-  installing_cli: "bg-sky-500 animate-pulse",
-  cli_not_found: "bg-red-500",
-};
-
-export const DAEMON_STATE_LABELS: Record<DaemonState, string> = {
-  running: "Running",
-  stopped: "Stopped",
-  starting: "Starting…",
-  stopping: "Stopping…",
-  installing_cli: "Setting up…",
-  cli_not_found: "Setup Failed",
-};
-
-export function formatUptime(uptime?: string): string {
-  if (!uptime) return "";
-  const match = uptime.match(/(?:(\d+)h)?(\d+)m/);
-  if (!match) return uptime;
-  const h = match[1] ? `${match[1]}h ` : "";
-  const m = match[2] ? `${match[2]}m` : "";
-  return `${h}${m}`.trim() || uptime;
-}

apps/desktop/test/setup.ts

@@ -1 +0,0 @@
-import "@testing-library/jest-dom/vitest";

apps/desktop/tsconfig.json

@@ -1,4 +0,0 @@
-{
-  "files": [],
-  "references": [{ "path": "./tsconfig.node.json" }, { "path": "./tsconfig.web.json" }]
-}

apps/desktop/tsconfig.node.json

@@ -1,8 +0,0 @@
-{
-  "extends": "@electron-toolkit/tsconfig/tsconfig.node.json",
-  "include": ["electron.vite.config.*", "src/main/**/*", "src/preload/**/*"],
-  "compilerOptions": {
-    "composite": true,
-    "types": ["electron-vite/node"]
-  }
-}

apps/desktop/tsconfig.web.json

@@ -1,21 +0,0 @@
-{
-  "extends": "@electron-toolkit/tsconfig/tsconfig.web.json",
-  "include": [
-    "src/renderer/src/env.d.ts",
-    "src/renderer/src/**/*",
-    "src/renderer/src/**/*.tsx",
-    "src/preload/*.d.ts",
-    "test/setup.ts"
-  ],
-  "compilerOptions": {
-    "composite": true,
-    "noImplicitAny": true,
-    "jsx": "react-jsx",
-    "baseUrl": ".",
-    "paths": {
-      "@/*": [
-        "src/renderer/src/*"
-      ]
-    }
-  }
-}

apps/desktop/vitest.config.ts

@@ -1,13 +0,0 @@
-import { defineConfig } from "vitest/config";
-import react from "@vitejs/plugin-react";
-
-export default defineConfig({
-  plugins: [react()],
-  test: {
-    globals: true,
-    include: ["src/**/*.test.{ts,tsx}", "scripts/**/*.test.mjs"],
-    environment: "jsdom",
-    setupFiles: ["./test/setup.ts"],
-    passWithNoTests: true,
-  },
-});

apps/docs/.gitignore

@@ -1,3 +0,0 @@
-.next/
-.source/
-node_modules/

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

@@ -1,49 +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";
-import { docsAlternates } from "@/lib/site";
-
-export default async function Page(props: {
-  params: Promise<{ lang: string; slug: string[] }>;
-}) {
-  const params = await props.params;
-  const page = source.getPage(params.slug, params.lang);
-  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 generateStaticParams() {
-  return source.generateParams().filter((p) => p.slug.length > 0);
-}
-
-export async function generateMetadata(props: {
-  params: Promise<{ lang: string; slug: string[] }>;
-}): Promise<Metadata> {
-  const params = await props.params;
-  const page = source.getPage(params.slug, params.lang);
-  if (!page) notFound();
-
-  return {
-    title: page.data.title,
-    description: page.data.description,
-    alternates: docsAlternates(params.slug),
-  };
-}

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

@@ -1,118 +0,0 @@
-import "../global.css";
-import { RootProvider } from "fumadocs-ui/provider";
-import { DocsLayout } from "fumadocs-ui/layouts/docs";
-import { Inter, Geist_Mono, Source_Serif_4 } from "next/font/google";
-import type { ReactNode } from "react";
-import type { Metadata } from "next";
-import { cn } from "@multica/ui/lib/utils";
-import { baseOptions } from "@/app/layout.config";
-import { source } from "@/lib/source";
-import { i18n, type Lang } from "@/lib/i18n";
-import { uiTranslations, localeLabels } from "@/lib/translations";
-import { DocsSettings } from "@/components/docs-settings";
-
-const inter = Inter({
-  subsets: ["latin"],
-  variable: "--font-sans",
-  fallback: [
-    "-apple-system",
-    "BlinkMacSystemFont",
-    "Segoe UI",
-    "PingFang SC",
-    "Microsoft YaHei",
-    "Noto Sans CJK SC",
-    "sans-serif",
-  ],
-});
-
-const geistMono = Geist_Mono({
-  subsets: ["latin"],
-  variable: "--font-mono",
-  fallback: ["ui-monospace", "SFMono-Regular", "Menlo", "Consolas", "monospace"],
-});
-
-// Editorial serif used for headings and showpiece elements. Italic style is
-// deliberately NOT loaded — italic in CJK is a synthetic slant that breaks
-// glyph design. Emphasis in docs is carried by brand color + weight, never
-// font-style. Mirrors apps/web/app/layout.tsx for the upright family.
-const sourceSerif = Source_Serif_4({
-  subsets: ["latin"],
-  style: ["normal"],
-  variable: "--font-serif",
-  fallback: [
-    "ui-serif",
-    "Iowan Old Style",
-    "Apple Garamond",
-    "Baskerville",
-    "Times New Roman",
-    "serif",
-  ],
-});
-
-export const metadata: Metadata = {
-  title: {
-    template: "%s | Multica Docs",
-    default: "Multica Docs",
-  },
-  description:
-    "Documentation for Multica — the open-source managed agents platform.",
-};
-
-export function generateStaticParams() {
-  return i18n.languages.map((lang) => ({ lang }));
-}
-
-export default async function Layout({
-  params,
-  children,
-}: {
-  params: Promise<{ lang: string }>;
-  children: ReactNode;
-}) {
-  const { lang: rawLang } = await params;
-  const lang = (i18n.languages as readonly string[]).includes(rawLang)
-    ? (rawLang as Lang)
-    : (i18n.defaultLanguage as Lang);
-  const locales = i18n.languages.map((l) => ({
-    locale: l,
-    name: localeLabels[l],
-  }));
-
-  return (
-    <html
-      lang={lang}
-      suppressHydrationWarning
-      className={cn(
-        "antialiased",
-        inter.variable,
-        geistMono.variable,
-        sourceSerif.variable,
-      )}
-    >
-      <body className="font-sans">
-        <RootProvider
-          i18n={{
-            locale: lang,
-            locales,
-            translations: uiTranslations[lang],
-          }}
-          search={{ options: { api: "/docs/api/search" } }}
-        >
-          <DocsLayout
-            tree={source.getPageTree(lang)}
-            // Suppress Fumadocs's default sidebar-footer icons (theme +
-            // language + search). Our custom <DocsSettings> is mounted as
-            // the sidebar footer instead — two labelled buttons, not three
-            // icons.
-            themeSwitch={{ enabled: false }}
-            searchToggle={{ enabled: false }}
-            sidebar={{ footer: <DocsSettings locale={lang} /> }}
-            {...baseOptions}
-          >
-            {children}
-          </DocsLayout>
-        </RootProvider>
-      </body>
-    </html>
-  );
-}

apps/docs/app/[lang]/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/[lang]/page.tsx

@@ -1,84 +0,0 @@
-import { source } from "@/lib/source";
-import { DocsPage, DocsBody } from "fumadocs-ui/page";
-import { notFound } from "next/navigation";
-import defaultMdxComponents from "fumadocs-ui/mdx";
-import type { Metadata } from "next";
-import { DocsHero } from "@/components/hero";
-import { Byline, NumberedCards, NumberedCard, NumberedSteps, Step } from "@/components/editorial";
-import { i18n, type Lang } from "@/lib/i18n";
-import { homeCopy } from "@/lib/translations";
-import { docsAlternates } from "@/lib/site";
-
-function asLang(lang: string): Lang {
-  return (i18n.languages as readonly string[]).includes(lang)
-    ? (lang as Lang)
-    : (i18n.defaultLanguage as Lang);
-}
-
-// A layout's `generateStaticParams` does NOT cascade — every page that
-// wants SSG must declare its own. Without this, both `/docs/` and
-// `/docs/zh` (the busiest URLs on the site) render dynamically on every
-// request.
-export function generateStaticParams() {
-  return i18n.languages.map((lang) => ({ lang }));
-}
-
-export default async function Page({
-  params,
-}: {
-  params: Promise<{ lang: string }>;
-}) {
-  const { lang: rawLang } = await params;
-  const lang = asLang(rawLang);
-  const page = source.getPage([], lang);
-  if (!page) notFound();
-
-  const MDX = page.data.body;
-  const copy = homeCopy[lang];
-
-  return (
-    <DocsPage toc={page.data.toc}>
-      <DocsHero
-        eyebrow={copy.eyebrow}
-        title={
-          <>
-            {copy.titleLead}
-            <em className="font-medium not-italic text-[var(--primary)]">
-              {copy.titleAccent}
-            </em>
-          </>
-        }
-        subtitle={page.data.description}
-      />
-      <Byline items={[...copy.byline]} />
-      <DocsBody>
-        <MDX
-          components={{
-            ...defaultMdxComponents,
-            NumberedCards,
-            NumberedCard,
-            NumberedSteps,
-            Step,
-          }}
-        />
-      </DocsBody>
-    </DocsPage>
-  );
-}
-
-export async function generateMetadata({
-  params,
-}: {
-  params: Promise<{ lang: string }>;
-}): Promise<Metadata> {
-  const { lang: rawLang } = await params;
-  const lang = asLang(rawLang);
-  const page = source.getPage([], lang);
-  if (!page) notFound();
-
-  return {
-    title: page.data.title,
-    description: page.data.description,
-    alternates: docsAlternates([]),
-  };
-}

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

@@ -1,32 +0,0 @@
-import { source } from "@/lib/source";
-import { createFromSource } from "fumadocs-core/search/server";
-
-// Orama doesn't ship a Chinese tokenizer and its built-in English regex
-// strips Han characters entirely, so `locale=zh` would either return empty
-// results or throw. Tokenize CJK input character-by-character and keep
-// Latin/digit runs whole — gives serviceable recall for Chinese docs while
-// letting Romanized terms (product names, CLI commands) still match.
-function tokenizeCJK(raw: string): string[] {
-  const tokens: string[] = [];
-  const regex = /[一-鿿㐀-䶿]|[A-Za-z0-9]+/g;
-  const lower = raw.toLowerCase();
-  let match: RegExpExecArray | null;
-  while ((match = regex.exec(lower)) !== null) {
-    tokens.push(match[0]);
-  }
-  return tokens;
-}
-
-export const { GET } = createFromSource(source, {
-  localeMap: {
-    zh: {
-      components: {
-        tokenizer: {
-          language: "english",
-          normalizationCache: new Map(),
-          tokenize: tokenizeCJK,
-        },
-      },
-    },
-  },
-});

apps/docs/app/global.css

@@ -1,679 +0,0 @@
-@import "tailwindcss";
-@import "fumadocs-ui/css/preset.css";
-@import "../../../packages/ui/styles/tokens.css";
-
-@custom-variant dark (&:is(.dark *));
-
-@source "../../../packages/ui/**/*.{ts,tsx}";
-
-/* ---------------------------------------------------------------------------
- * Multica Docs — editorial visual identity (v2)
- *
- * Docs site is intentionally distinct from the product app: warm-paper
- * background, editorial serif headings (Source Serif 4), indigo accent,
- * ruled dividers. Product app keeps its cool-gray dense Linear-style; docs
- * reads like a literary publication. Same split as Stripe, Cursor, Linear.
- *
- * Implementation: docs-scoped token override on top of Multica tokens
- * (whose @theme inline references read --background / --foreground / etc
- * at runtime, so re-pointing the vars cascades through fumadocs's full
- * --color-fd-* bridge below).
- * ------------------------------------------------------------------------- */
-
-:root {
-  --fd-page-width: 1080px;
-}
-
-/* ---------------------------------------------------------------------------
- * Editorial palette — light
- * ------------------------------------------------------------------------- */
-
-:root {
-  --background: oklch(0.972 0.003 85);          /* near-white, faint warm — matches landing #f7f7f5 */
-  --foreground: oklch(0.182 0.012 50);          /* warm ink */
-  --muted: oklch(0.955 0.006 85);               /* hairline, slightly warmer than bg */
-  --muted-foreground: oklch(0.482 0.012 65);    /* warm muted */
-  --card: oklch(0.99 0.002 85);                 /* paper — near white */
-  --card-foreground: oklch(0.182 0.012 50);
-  --popover: oklch(0.99 0.002 85);
-  --popover-foreground: oklch(0.182 0.012 50);
-  --primary: oklch(0.55 0.16 255);              /* Multica brand */
-  --primary-foreground: oklch(0.985 0.008 85);
-  --secondary: oklch(0.945 0.012 85);
-  --secondary-foreground: oklch(0.182 0.012 50);
-  --accent: oklch(0.945 0.022 255);             /* brand soft wash */
-  --accent-foreground: oklch(0.46 0.16 255);    /* brand ink */
-  --border: oklch(0.91 0.014 85);               /* ruled lines */
-  --input: oklch(0.91 0.014 85);
-  --ring: oklch(0.55 0.16 255);
-  --sidebar: oklch(0.99 0.002 85);              /* paper — same as card */
-  --sidebar-foreground: oklch(0.182 0.012 50);
-  --sidebar-accent: oklch(0.945 0.006 85);      /* subtle cream, hover/active fill */
-  --sidebar-accent-foreground: oklch(0.182 0.012 50);
-  --sidebar-border: oklch(0.91 0.014 85);
-
-  /* Docs-only extras (not bridged to fumadocs slots) */
-  --docs-rule: oklch(0.835 0.018 85);           /* heavier rule */
-  --docs-faint: oklch(0.72 0.018 75);           /* faintest accent */
-  --docs-code-bg: oklch(0.94 0.018 85);         /* warm beige code surface */
-  --docs-code-border: oklch(0.89 0.018 85);
-  --docs-terminal-bg: oklch(0.18 0.012 50);     /* terminal warm dark */
-  --docs-terminal-fg: oklch(0.92 0.012 80);
-  --docs-terminal-accent: oklch(0.65 0.16 255);
-}
-
-/* ---------------------------------------------------------------------------
- * Editorial palette — dark (warm dark, NOT Multica's cool dark)
- * ------------------------------------------------------------------------- */
-
-.dark {
-  --background: oklch(0.18 0.008 50);
-  --foreground: oklch(0.95 0.012 85);
-  --muted: oklch(0.22 0.008 50);
-  --muted-foreground: oklch(0.65 0.012 75);
-  --card: oklch(0.21 0.008 50);
-  --card-foreground: oklch(0.95 0.012 85);
-  --popover: oklch(0.22 0.008 50);
-  --popover-foreground: oklch(0.95 0.012 85);
-  --primary: oklch(0.7 0.15 255);               /* Multica brand — dark */
-  --primary-foreground: oklch(0.18 0.008 50);
-  --secondary: oklch(0.24 0.008 50);
-  --secondary-foreground: oklch(0.95 0.012 85);
-  --accent: oklch(0.3 0.05 255);                /* brand soft wash — dark */
-  --accent-foreground: oklch(0.78 0.14 255);    /* brand ink — dark */
-  --border: oklch(0.28 0.012 50);
-  --input: oklch(0.28 0.012 50);
-  --ring: oklch(0.7 0.15 255);
-  --sidebar: oklch(0.21 0.008 50);
-  --sidebar-foreground: oklch(0.95 0.012 85);
-  --sidebar-accent: oklch(0.26 0.01 50);        /* warm neutral, hover/active fill — dark */
-  --sidebar-accent-foreground: oklch(0.95 0.012 85);
-  --sidebar-border: oklch(0.28 0.012 50);
-
-  --docs-rule: oklch(0.36 0.012 50);
-  --docs-faint: oklch(0.42 0.012 50);
-  --docs-code-bg: oklch(0.165 0.008 50);
-  --docs-code-border: oklch(0.26 0.012 50);
-  --docs-terminal-bg: oklch(0.155 0.012 50);
-  --docs-terminal-fg: oklch(0.92 0.012 80);
-  --docs-terminal-accent: oklch(0.78 0.14 255);
-}
-
-/* ---------------------------------------------------------------------------
- * Fumadocs slot bridge
- *
- * Map fumadocs's --color-fd-* slots to our (now warm) Multica tokens.
- * @theme inline keeps the var() reference live so the cascade resolves
- * at runtime — same pattern tokens.css uses.
- * ------------------------------------------------------------------------- */
-
-@theme inline {
-  --color-fd-background: var(--background);
-  --color-fd-foreground: var(--foreground);
-  --color-fd-muted: var(--muted);
-  --color-fd-muted-foreground: var(--muted-foreground);
-  --color-fd-popover: var(--popover);
-  --color-fd-popover-foreground: var(--popover-foreground);
-  --color-fd-card: var(--card);
-  --color-fd-card-foreground: var(--card-foreground);
-  --color-fd-border: var(--border);
-  --color-fd-primary: var(--primary);
-  --color-fd-primary-foreground: var(--primary-foreground);
-  --color-fd-secondary: var(--secondary);
-  --color-fd-secondary-foreground: var(--secondary-foreground);
-  --color-fd-accent: var(--accent);
-  --color-fd-accent-foreground: var(--accent-foreground);
-  --color-fd-ring: var(--ring);
-}
-
-/* Sidebar uses dedicated --sidebar-* tokens so it sits a hair off the main
- * canvas. Fumadocs renders it as #nd-sidebar (desktop) and
- * #nd-sidebar-mobile (mobile drawer); both IDs need the override. */
-#nd-sidebar,
-#nd-sidebar-mobile {
-  --color-fd-background: var(--sidebar);
-  --color-fd-foreground: var(--sidebar-foreground);
-  --color-fd-muted: var(--sidebar-accent);
-  --color-fd-muted-foreground: var(--sidebar-foreground);
-  --color-fd-accent: var(--sidebar-accent);
-  --color-fd-accent-foreground: var(--sidebar-accent-foreground);
-  --color-fd-border: var(--sidebar-border);
-}
-
-/* ---------------------------------------------------------------------------
- * Editorial typography
- *
- * Body keeps Inter for legibility (especially CJK where serif Latin clashes
- * with sans CJK). Headings switch to Source Serif 4 for the editorial
- * signature. Italic is intentionally avoided — Chinese italic is a CSS
- * synthetic slant against upright-designed glyphs and reads as broken.
- * Emphasis is carried by serif/sans contrast, brand color, and weight.
- *
- * Sizing:
- *   - DocsHero h1 (welcome page only): 44px serif, brand-color em accent
- *   - prose h1 (guide / reference pages): 30px serif
- *   - prose h2: 26px serif (no italic)
- *   - prose h3: 13px sans uppercase label
- *   - body: 15.5px (kept from previous build — proven reading size for CN)
- * ------------------------------------------------------------------------- */
-
-article:has(.prose),
-.prose {
-  font-size: 0.96875rem; /* 15.5px */
-  line-height: 1.7;
-}
-
-/* DocsTitle h1 (Fumadocs hardcodes text-[1.75em] font-semibold — utility
- * specificity 0,1,0 beats plain article > h1 0,0,2; !important wins). */
-article > h1 {
-  font-family: var(--font-serif), ui-serif, serif !important;
-  font-size: 1.875rem !important; /* 30px guide-page heading */
-  font-weight: 400 !important;
-  letter-spacing: -0.018em;
-  line-height: 1.15;
-  margin-bottom: 0.5em;
-  color: var(--foreground);
-}
-
-/* Lead paragraph below DocsTitle */
-article > p.text-lg {
-  font-family: var(--font-serif), ui-serif, serif;
-  font-size: 1.125rem; /* 18px serif lede */
-  line-height: 1.55;
-  margin-bottom: 2rem;
-  color: var(--muted-foreground);
-}
-
-/* Paragraph rhythm */
-.prose :where(p):not(:where([class~="not-prose"] *)) {
-  margin-top: 0;
-  margin-bottom: 0.875rem;
-  color: oklch(from var(--foreground) calc(l + 0.06) c h);
-}
-.prose :where(p):not(:where([class~="not-prose"] *)):last-child {
-  margin-bottom: 0;
-}
-.prose :where(p) strong {
-  color: var(--foreground);
-  font-weight: 600;
-}
-
-.prose :where(ul, ol) {
-  margin-top: 0.5rem;
-  margin-bottom: 1rem;
-}
-
-.prose h1 {
-  font-family: var(--font-serif), ui-serif, serif;
-  font-size: 1.875rem; /* 30px */
-  font-weight: 400;
-  letter-spacing: -0.02em;
-  line-height: 1.1;
-  margin-bottom: 0.5em;
-  color: var(--foreground);
-}
-/* Italic is avoided sitewide (Chinese italic = synthetic slant, looks broken).
- * Force any italicized element to non-italic in prose. Tailwind Typography
- * defaults blockquote to italic; we also undo it here. Emphasis is carried
- * by brand color + font-weight in headings, foreground+weight in body. */
-.prose em,
-.prose i,
-.prose cite,
-.prose blockquote,
-.prose blockquote p {
-  font-style: normal;
-}
-.prose h1 em {
-  color: var(--primary);
-  font-weight: 500;
-}
-.prose p em,
-.prose li em {
-  color: var(--foreground);
-  font-weight: 600;
-}
-
-.prose h2 {
-  font-family: var(--font-serif), ui-serif, serif;
-  font-size: 1.625rem; /* 26px */
-  font-weight: 400;
-  letter-spacing: -0.015em;
-  line-height: 1.3;
-  margin-top: 2em;
-  margin-bottom: 0.5em;
-  color: var(--foreground);
-  scroll-margin-top: 80px;
-}
-
-/* h3 = small uppercase sans label, ruled-bottom — v2 editorial signature */
-.prose h3 {
-  font-family: var(--font-sans), system-ui, sans-serif;
-  font-size: 0.8125rem; /* 13px */
-  font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.1em;
-  color: var(--muted-foreground);
-  margin-top: 2.25em;
-  margin-bottom: 0.75em;
-  padding-bottom: 0.25em;
-  border-bottom: 1px solid var(--border);
-}
-
-.prose h4 {
-  font-family: var(--font-serif), ui-serif, serif;
-  font-size: 1.0625rem; /* 17px */
-  font-weight: 500;
-  letter-spacing: -0.005em;
-  line-height: 1.4;
-  margin-top: 1.5em;
-  margin-bottom: 0.375em;
-  color: var(--foreground);
-}
-
-/* Description paragraph (fumadocs adds text-lg + muted) */
-.prose > p:first-of-type:has(+ *) {
-  line-height: 1.6;
-}
-
-/* ---------------------------------------------------------------------------
- * Links — Vercel-style hairline underline, reveal brand on hover
- *
- * Markdown-heavy prose can put 4+ inline links in a single sentence; a
- * permanent brand-color underline on every one turns the paragraph into
- * highlighter spam. The trick isn't "no underline" — it's underlining
- * in the hairline border color so the line exists but visually recedes.
- * Hover swaps both text and underline to brand color (no thickness
- * change) — the link "arrives" as a single color shift.
- * ------------------------------------------------------------------------- */
-
-.prose a:not([data-card]):not(.not-prose) {
-  color: var(--foreground);
-  font-weight: 500;
-  text-decoration: underline;
-  text-decoration-color: var(--border);
-  text-decoration-thickness: 1px;
-  text-underline-offset: 3px;
-  transition: text-decoration-color 150ms, color 150ms;
-}
-.prose a:not([data-card]):not(.not-prose):hover {
-  color: var(--primary);
-  text-decoration-color: var(--primary);
-}
-
-/* Callout already carries four visual signals (left brand bar, brand-wash
- * bg, uppercase NOTE label, body). Another decoration over-loads it — so
- * links inside a callout drop the underline entirely. Color shift on
- * hover is the full affordance. */
-.prose div.shadow-md:has(> [role="none"]) a:not([data-card]):not(.not-prose),
-.prose div.shadow-md:has(> [role="none"]) a:not([data-card]):not(.not-prose):hover {
-  text-decoration: none;
-}
-
-/* Inline code — warm beige chip, accent-color text */
-.prose :not(pre) > code {
-  background: var(--docs-code-bg);
-  color: var(--accent-foreground);
-  padding: 0.125rem 0.375rem;
-  border-radius: 3px;
-  font-family: var(--font-mono), ui-monospace, monospace;
-  font-size: 0.875em;
-  font-weight: 500;
-  box-decoration-break: clone;
-  -webkit-box-decoration-break: clone;
-}
-.prose :not(pre) > code::before,
-.prose :not(pre) > code::after {
-  content: none;
-}
-
-/* Lists */
-.prose :where(ul, ol) > li {
-  margin-top: 0.375em;
-  margin-bottom: 0.375em;
-  padding-inline-start: 0.375em;
-}
-.prose :where(ul) > li::marker {
-  color: var(--docs-faint);
-  content: "—  ";
-  font-family: var(--font-serif), serif;
-}
-.prose :where(ol) > li::marker {
-  color: var(--muted-foreground);
-}
-
-/* Blockquote — editorial accent rule, serif voice */
-.prose blockquote {
-  font-family: var(--font-serif), ui-serif, serif;
-  font-weight: 400;
-  font-size: 1.0625rem;
-  line-height: 1.55;
-  color: var(--foreground);
-  border-inline-start-width: 2px;
-  border-inline-start-color: var(--primary);
-  padding-inline-start: 1.25em;
-  margin-block: 1.5em;
-  quotes: none;
-}
-.prose blockquote p::before,
-.prose blockquote p::after {
-  content: none;
-}
-
-/* Tables — hairline below thead only, no outer frame (Stripe / Linear
- * docs convention). The heavier ink-color top rule v2 used on its API
- * reference block is intentionally not applied here — that treatment is
- * "this is a formal declaration"; regular guide tables want quiet. */
-.prose table {
-  font-size: 0.9375em;
-  border-collapse: collapse;
-  margin-block: 1.5em;
-}
-.prose thead {
-  border-bottom: 1px solid var(--border);
-}
-.prose thead th {
-  font-family: var(--font-sans), system-ui, sans-serif;
-  font-size: 0.75rem;
-  font-weight: 600;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-  color: var(--muted-foreground);
-  padding-block: 0.5rem 0.625rem;
-  text-align: start;
-}
-.prose tbody tr {
-  border-bottom: 1px solid var(--border);
-}
-.prose tbody td {
-  padding-block: 0.875rem;
-}
-
-/* HR — heavier ruled separator */
-.prose hr {
-  border: none;
-  border-top: 1px solid var(--docs-rule);
-  margin-block: 3em;
-}
-
-/* ---------------------------------------------------------------------------
- * Callout — editorial 2px accent bar + soft accent wash
- * ------------------------------------------------------------------------- */
-
-.prose div.shadow-md:has(> [role="none"]) {
-  box-shadow: none !important;
-  border-radius: 0 4px 4px 0 !important;
-  background: var(--accent) !important;
-  border: none !important;
-  border-inline-start: 2px solid var(--primary) !important;
-  padding: 0.875rem 1.125rem !important;
-  gap: 0.625rem !important;
-  align-items: flex-start;
-  margin-block: 1.5rem;
-}
-
-.prose div.shadow-md:has(> [role="none"]) > [role="none"] {
-  display: none;
-}
-
-.prose div.shadow-md:has(> [role="none"]) > div:last-child > p {
-  font-family: var(--font-sans), system-ui, sans-serif;
-  font-size: 0.6875rem;
-  font-weight: 700;
-  letter-spacing: 0.1em;
-  text-transform: uppercase;
-  color: var(--primary);
-  margin-bottom: 0.375rem;
-}
-
-.prose div.shadow-md:has(> [role="none"]) > div:last-child > div {
-  color: var(--foreground) !important;
-  font-size: 0.9375rem;
-  line-height: 1.6;
-}
-
-/* ---------------------------------------------------------------------------
- * Cards — fallback editorial treatment for fumadocs's <Cards>/<Card>
- * (NumberedCards is the showpiece; this keeps non-showpiece pages on tone)
- * ------------------------------------------------------------------------- */
-
-.prose [data-card]:not(.peer) {
-  border-radius: 4px !important;
-  border: 1px solid var(--border) !important;
-  background: var(--card);
-  padding: 1.125rem !important;
-  transition: border-color 150ms, background-color 150ms !important;
-}
-
-.prose [data-card]:not(.peer):hover {
-  border-color: var(--primary) !important;
-  background: var(--card) !important;
-}
-
-.prose [data-card]:not(.peer) > div:first-child {
-  box-shadow: none !important;
-  border-radius: 0 !important;
-  padding: 0 !important;
-  background: transparent !important;
-  border: none !important;
-  color: var(--accent-foreground) !important;
-  margin-bottom: 0.75rem !important;
-}
-
-.prose [data-card]:not(.peer) > div:first-child svg {
-  color: var(--accent-foreground);
-}
-
-.prose [data-card]:not(.peer) h3 {
-  font-family: var(--font-serif), serif !important;
-  font-size: 1.125rem !important;
-  font-weight: 500 !important;
-  font-style: normal !important;
-  letter-spacing: -0.01em;
-  margin-bottom: 0.25rem !important;
-  margin-top: 0 !important;
-  text-transform: none !important;
-  border-bottom: none !important;
-  padding-bottom: 0 !important;
-  color: var(--foreground) !important;
-}
-
-.prose [data-card]:not(.peer) p {
-  color: var(--muted-foreground) !important;
-  line-height: 1.6;
-  font-size: 0.9375rem !important;
-}
-
-/* ---------------------------------------------------------------------------
- * Sidebar — editorial chrome
- *
- * Section headers: small uppercase sans label, ruled bottom border.
- * Items: muted-foreground at rest, foreground on hover.
- * Active: solid background fill (mirrors product app's app-sidebar.tsx —
- * data-active:bg-sidebar-accent / data-active:text-sidebar-accent-foreground).
- * ------------------------------------------------------------------------- */
-
-#nd-sidebar p,
-#nd-sidebar-mobile p {
-  font-family: var(--font-sans), system-ui, sans-serif;
-  font-size: 0.6875rem; /* 11px */
-  font-weight: 600;
-  letter-spacing: 0.1em;
-  text-transform: uppercase;
-  color: var(--muted-foreground);
-  height: auto;
-  display: block;
-  margin-top: 1.5rem;
-  margin-bottom: 0.375rem;
-  padding-block: 0 0.375rem;
-  padding-inline-start: 0.5rem;
-  border-bottom: 1px solid var(--border);
-}
-
-#nd-sidebar p:first-child,
-#nd-sidebar-mobile p:first-child {
-  margin-top: 0;
-}
-
-#nd-sidebar a[data-active],
-#nd-sidebar-mobile a[data-active] {
-  height: auto;
-  padding: 0.375rem 0.625rem;
-  font-size: 0.84375rem; /* 13.5px */
-  border-radius: var(--radius-sm);
-  font-weight: 400;
-  line-height: 1.4;
-  letter-spacing: -0.005em;
-  display: flex;
-  align-items: center;
-}
-
-#nd-sidebar a[data-active="false"],
-#nd-sidebar-mobile a[data-active="false"] {
-  color: var(--muted-foreground);
-}
-
-#nd-sidebar a[data-active="false"]:hover,
-#nd-sidebar-mobile a[data-active="false"]:hover {
-  background: color-mix(in oklab, var(--sidebar-accent) 70%, transparent);
-  color: var(--foreground);
-}
-
-/* Active — solid background fill, no left mark (matches product app) */
-#nd-sidebar a[data-active="true"],
-#nd-sidebar-mobile a[data-active="true"] {
-  background: var(--sidebar-accent) !important;
-  color: var(--sidebar-accent-foreground) !important;
-  font-weight: 500;
-}
-
-/* Sidebar footer — drop the hard top rule. The scroll viewport already
- * fades content into the footer, so a 1px line on top reads as a
- * double-weight edge. Fumadocs hardcodes `border-t p-4 pt-2` on its
- * SidebarFooter div; target that exact class trio inside the sidebar IDs
- * so we don't touch any other border-t in the app. */
-#nd-sidebar .border-t.p-4.pt-2,
-#nd-sidebar-mobile .border-t.p-4.pt-2 {
-  border-top-width: 0;
-}
-
-/* ---------------------------------------------------------------------------
- * Top nav — quiet, ruled bottom
- * ------------------------------------------------------------------------- */
-
-#nd-nav,
-#nd-subnav {
-  border-bottom: 1px solid var(--border);
-  background: var(--card);
-}
-
-#nd-nav a,
-#nd-subnav a {
-  font-size: 0.875rem;
-  color: var(--muted-foreground);
-  transition: color 150ms;
-}
-
-#nd-nav a:hover,
-#nd-subnav a:hover {
-  color: var(--foreground);
-}
-
-/* ---------------------------------------------------------------------------
- * TOC (right rail) — quiet sans, brand-color when active
- * ------------------------------------------------------------------------- */
-
-#nd-toc a {
-  font-size: 0.84375rem;
-  color: var(--muted-foreground);
-  padding-block: 0.3125rem;
-  letter-spacing: -0.005em;
-  transition: color 150ms;
-}
-
-#nd-toc a:hover {
-  color: var(--foreground);
-}
-
-#nd-toc a[data-active="true"] {
-  color: var(--primary);
-  font-weight: 500;
-}
-
-/* TOC heading (Fumadocs renders "On this page" as an h3 / first p) */
-#nd-toc h3,
-#nd-toc > p:first-child {
-  font-family: var(--font-sans), system-ui, sans-serif;
-  font-size: 0.6875rem;
-  font-weight: 600;
-  letter-spacing: 0.1em;
-  text-transform: uppercase;
-  color: var(--muted-foreground);
-  margin-bottom: 0.625rem;
-  padding-bottom: 0.375rem;
-  border-bottom: 1px solid var(--border);
-}
-
-/* ---------------------------------------------------------------------------
- * Code blocks — warm beige (light) / warm dark (dark), NOT pinned
- *
- * Removes the previous "always-dark hero black" treatment. Code surface
- * now follows page theme so it harmonizes with the warm-paper background
- * in light mode and warm-dark in dark mode. Terminal-style blocks
- * (handled by the custom <Terminal> component, not here) stay pinned to
- * the deeper warm dark for the "shell session" feel.
- * ------------------------------------------------------------------------- */
-
-article figure.shiki {
-  background: var(--docs-code-bg) !important;
-  border: 1px solid var(--docs-code-border) !important;
-  border-radius: 4px !important;
-  box-shadow: none !important;
-  margin-block: 1.25rem !important;
-  color: var(--foreground);
-}
-
-article figure.shiki pre {
-  background: transparent !important;
-  border: none !important;
-  border-radius: 0 !important;
-  color: inherit !important;
-  margin: 0 !important;
-}
-
-article figure.shiki > div[class*="overflow-auto"] {
-  font-size: 0.84375rem !important;
-  line-height: 1.7;
-  padding: 1rem 1.125rem !important;
-}
-
-/* Header bar (filename via ```lang filename="x.ts") */
-article figure.shiki > div[class*="border-b"] {
-  border-bottom-color: var(--docs-code-border) !important;
-  background: var(--muted) !important;
-  color: var(--muted-foreground) !important;
-  font-family: var(--font-mono), ui-monospace, monospace;
-  font-size: 0.75rem;
-  letter-spacing: -0.005em;
-}
-
-/* Shiki tokens — pick the palette that matches page theme.
- * Default (light): use --shiki-light. Override under .dark to --shiki-dark.
- * Specificity: article figure.shiki code span (0,1,4) beats fumadocs's
- * default, so no !important needed for the light path. */
-article figure.shiki code span {
-  color: var(--shiki-light);
-}
-
-.dark article figure.shiki code span {
-  color: var(--shiki-dark);
-}
-
-/* Copy button on code blocks */
-article figure.shiki button {
-  color: var(--muted-foreground) !important;
-  background: transparent !important;
-}
-article figure.shiki button:hover {
-  color: var(--foreground) !important;
-  background: var(--muted) !important;
-}

apps/docs/app/layout.config.tsx

@@ -1,76 +0,0 @@
-import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
-import { ArrowUpRight } from "lucide-react";
-
-// Docs-local stateless Multica mark — matches @multica/ui's MulticaIcon
-// visually (same 8-pointed-asterisk clip-path), but without useState/
-// useEffect so it's safe to render from Server Components such as
-// layout.config.tsx / layout.tsx. Keep in sync with
-// packages/ui/components/common/multica-icon.tsx if the mark changes.
-const MULTICA_CLIP = `polygon(
-  45% 62.1%, 45% 100%, 55% 100%, 55% 62.1%,
-  81.8% 88.9%, 88.9% 81.8%, 62.1% 55%, 100% 55%,
-  100% 45%, 62.1% 45%, 88.9% 18.2%, 81.8% 11.1%,
-  55% 37.9%, 55% 0%, 45% 0%, 45% 37.9%,
-  18.2% 11.1%, 11.1% 18.2%, 37.9% 45%, 0% 45%,
-  0% 55%, 37.9% 55%, 11.1% 81.8%, 18.2% 88.9%
-)`;
-
-function MulticaMark() {
-  return (
-    <span className="inline-block size-[1em]" aria-hidden="true">
-      <span
-        className="block size-full bg-current"
-        style={{ clipPath: MULTICA_CLIP }}
-      />
-    </span>
-  );
-}
-
-// GitHub mark — inlined SVG (lucide-react dropped the Github icon for brand
-// trademark reasons). Path matches apps/web/features/landing/components/
-// shared.tsx GitHubMark.
-function GitHubMark() {
-  return (
-    <svg
-      viewBox="0 0 16 16"
-      aria-hidden="true"
-      className="size-[1em]"
-      fill="currentColor"
-    >
-      <path d="M8 0C3.58 0 0 3.58 0 8a8 8 0 0 0 5.47 7.59c.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2 .37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82A7.65 7.65 0 0 1 8 4.84c.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z" />
-    </svg>
-  );
-}
-
-// External links shown at the top of the sidebar (and in the top nav on
-// desktop). Leading icon = brand identity (GitHub mark / Multica asterisk);
-// trailing ArrowUpRight = "opens externally" glyph, same pattern as
-// `packages/views/layout/help-launcher.tsx` from PR #1560.
-const externalLinkText = (label: string) => (
-  <span className="inline-flex items-center gap-1">
-    {label}
-    <ArrowUpRight className="size-3 translate-y-px text-muted-foreground/60" />
-  </span>
-);
-
-export const baseOptions: BaseLayoutProps = {
-  nav: {
-    title: (
-      <span className="font-semibold text-base">Multica Docs</span>
-    ),
-  },
-  links: [
-    {
-      icon: <GitHubMark />,
-      text: externalLinkText("GitHub"),
-      url: "https://github.com/multica-ai/multica",
-      external: true,
-    },
-    {
-      icon: <MulticaMark />,
-      text: externalLinkText("Multica"),
-      url: "https://multica.ai",
-      external: true,
-    },
-  ],
-};