feat(cli): enhance version command with JSON output and build info

Add --output json flag, build date, Go version, and OS/arch to the
version command. Update Makefile and goreleaser to inject build date.

.dockerignore

@@ -0,0 +1,38 @@
+# 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

.gitattributes

@@ -0,0 +1,6 @@
+# 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

.gitignore

@@ -41,6 +41,9 @@ apps/web/test-results/
 # feature tracking
 _features/
 
+# runtime
+*.pid
+
 # platform specific
 *.dmg
 *.app

.goreleaser.yml

@@ -11,6 +11,7 @@ builds:
       - -s -w
       - -X main.version={{.Version}}
       - -X main.commit={{.ShortCommit}}
+      - -X main.date={{.Date}}
     env:
       - CGO_ENABLED=0
     goos:

CLAUDE.md

@@ -15,212 +15,52 @@ Multica is an AI-native task management platform — like Linear, but with AI ag
 **Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.**
 
 - `server/` — Go backend (Chi router, sqlc for DB, gorilla/websocket for real-time)
-- `apps/web/` — Next.js 16 frontend (App Router)
-- `apps/desktop/` — Electron 39 desktop app (electron-vite + react-router-dom)
+- `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
 
-### Monorepo Tooling
+### Key Architectural Decisions
 
-- **pnpm workspaces** for dependency management. `pnpm-workspace.yaml` defines a `catalog:` for version pinning — all shared deps (React, Zustand, TanStack Query, Tailwind, TypeScript) use `catalog:` references to guarantee a single version across all packages.
-- **Turborepo** for task orchestration — build, typecheck, test, lint all respect the package dependency graph.
-- **Internal Packages pattern** — all shared packages export raw `.ts`/`.tsx` files (no pre-compilation). The consuming app's bundler (Vite for desktop, Next.js for web) compiles them directly. This gives zero-config HMR and instant go-to-definition. If a package is ever published to npm, add a build step then.
-
-### Package Architecture
-
-Three shared packages with single-direction dependencies:
-
-```
-packages/
-├── core/     # @multica/core  — types, API client, stores, queries, mutations, realtime, platform
-├── ui/       # @multica/ui    — 55 shadcn components, common components, markdown, hooks, styles
-├── views/    # @multica/views — issue pages, editor, modals, skills, runtimes, navigation, layout, auth, settings
-└── tsconfig/ # @multica/tsconfig — shared TS base configs
-```
+**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.
 
 **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.
 
-**Platform bridge:** `packages/core/platform/` provides `CoreProvider` — a single component that initializes API client, auth/workspace stores, WS connection, and QueryClient. Each app wraps its root with `<CoreProvider apiBaseUrl wsUrl>` and provides its own `NavigationAdapter` for routing.
+**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.
 
-```
-apps/web:     ThemeProvider > CoreProvider(onLogin=cookie, onLogout=cookie) > WebNavigationProvider > pages
-apps/desktop: ThemeProvider > CoreProvider(apiBaseUrl, wsUrl)               > RouterProvider > DesktopNavigationProvider > pages
-```
-
-### packages/core/ (`@multica/core`)
-
-Headless business logic. **Zero react-dom, zero localStorage, zero process.env.**
-
-| Module | Purpose | Key exports |
-|---|---|---|
-| `core/types/` | Domain types + StorageAdapter interface | `Issue`, `Agent`, `Workspace`, `StorageAdapter` |
-| `core/api/` | API client class + WS client | `ApiClient`, `WSClient`, `setApiInstance()` |
-| `core/auth/` | Auth store factory | `createAuthStore(options)`, `registerAuthStore()` |
-| `core/workspace/` | Workspace store factory + actor hooks | `createWorkspaceStore(api)`, `useActorName()` |
-| `core/issues/` | Issue queries, mutations, stores, config | `issueListOptions`, `useUpdateIssue`, `useIssueStore` |
-| `core/inbox/` | Inbox queries, mutations, WS updaters | `inboxListOptions`, `useMarkInboxRead` |
-| `core/runtimes/` | Runtime queries + mutations | `runtimeListOptions`, `useDeleteRuntime` |
-| `core/realtime/` | WS provider + sync hooks | `WSProvider`, `useWSEvent`, `useRealtimeSync` |
-| `core/hooks.tsx` | Workspace ID context | `useWorkspaceId`, `WorkspaceIdProvider` |
-| `core/modals/` | Modal state store | `useModalStore` |
-| `core/navigation/` | Navigation state store | `useNavigationStore` |
-| `core/platform/` | CoreProvider + auth init + default storage | `CoreProvider`, `AuthInitializer`, `defaultStorage` |
-
-**Store factory pattern:** Auth and workspace stores are created via factory functions that receive platform-specific dependencies:
-```typescript
-createAuthStore({ api, storage, onLogin?, onLogout? })
-createWorkspaceStore(api, { storage?, onError? })
-```
-Each app creates its own instances in its platform layer and registers them via `registerAuthStore()` / `registerWorkspaceStore()`.
-
-**StorageAdapter:** All persistent storage goes through a `StorageAdapter` interface (getItem/setItem/removeItem), injected by the platform. Web uses an SSR-safe localStorage wrapper.
-
-### packages/ui/ (`@multica/ui`)
-
-Atomic UI layer. **Zero business logic, zero `@multica/core` imports.**
-
-- `components/ui/` — 55 shadcn components (button, dialog, card, tooltip, sidebar, etc.)
-- `components/common/` — Pure-props components (actor-avatar, emoji-picker, reaction-bar, multica-icon, theme-provider)
-- `markdown/` — Markdown renderer with `renderMention` slot for platform-specific mention cards
-- `hooks/` — DOM hooks (use-auto-scroll, use-mobile, use-scroll-fade)
-- `lib/utils.ts` — `cn()` function (clsx + tailwind-merge)
-- `styles/tokens.css` — Tailwind CSS v4 design tokens (@theme inline, :root, .dark variables)
-- `styles/base.css` — Shared base layer (scrollbar, shiki themes, entrance-spin animation, sidebar active state, sonner alignment, body/html defaults)
-
-### packages/views/ (`@multica/views`)
-
-Shared business UI pages. **Zero `next/*` imports. Zero `react-router-dom` imports.** Uses `NavigationAdapter` for routing.
-
-- `navigation/` — `NavigationAdapter` interface, `useNavigation()` hook, `AppLink` component
-- `layout/` — `DashboardLayout`, `AppSidebar`, `useDashboardGuard`
-- `auth/` — `LoginPage` (shared login with optional Google OAuth via props)
-- `issues/components/` — IssuesPage, IssueDetail, BoardView, ListView, pickers, icons
-- `editor/` — ContentEditor, TitleEditor, Tiptap extensions
-- `modals/` — CreateIssueModal, CreateWorkspaceModal, ModalRegistry
-- `my-issues/`, `skills/`, `runtimes/`, `agents/`, `inbox/`, `settings/` — domain pages
-- `common/` — Data-aware wrappers (ActorAvatar with useActorName, Markdown with IssueMentionCard)
-
-**NavigationAdapter:** Platform-agnostic routing interface. All shared components use `useNavigation()` and `<AppLink>` — never import from `next/navigation` or `react-router-dom` directly. Optional methods (`openInNewTab`, `getShareableUrl`) are provided by desktop only; shared code checks their existence before calling.
-
-### apps/web/ (Next.js App)
-
-Thin routing shells + platform-specific code.
-
-```
-apps/web/
-├── app/              # Next.js route shells (< 15 lines each, import from @multica/views)
-├── platform/         # Web platform bridge — only navigation.tsx remains
-├── features/
-│   ├── auth/         # Web-only: auth-cookie.ts (cookie for Next.js middleware)
-│   ├── landing/      # Web-only: landing pages (uses next/image, next/link)
-│   └── search/       # Web-only: search dialog
-└── components/       # App-level: web-providers.tsx, locale-sync, loading-indicator
-```
-
-**`platform/navigation.tsx`** — `WebNavigationProvider` wrapping Next.js `useRouter`/`usePathname`. The only web-platform-specific file remaining — core initialization is handled by `CoreProvider` in `packages/core/platform/`.
-
-### apps/desktop/ (Electron App)
-
-Electron 39 + electron-vite + react-router-dom. Uses `createHashRouter` since there's no server for pushState.
-
-Desktop shares all page components from `@multica/views` — the router imports `IssuesPage`, `InboxPage`, `AgentsPage`, etc. directly. Desktop-specific code is limited to: layout shell (tab bar, traffic light region), navigation adapter, and page wrappers for dynamic `document.title`.
-
-**Key conventions:**
-- New routes must include `handle: { title: "..." }` for automatic tab titles
-- Pages with dynamic titles (e.g. issue detail) use `useDocumentTitle(title)` to override
-- `platform/navigation.tsx` adapts react-router to `NavigationAdapter` — the only place that imports from `react-router-dom`
-- Environment variables (`VITE_API_URL`, `VITE_WS_URL`) are baked in at build time via `.env.production`
+**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.
 
 ### State Management
 
-- **TanStack Query** for all server state — issues, inbox, members, agents, skills, runtimes. Query definitions in `@multica/core/<domain>/queries.ts`, mutations in `mutations.ts`.
-- **Zustand** for client-only state — UI selections (`activeIssueId`), view filters, modal state. Auth and workspace stores use factory pattern with injected dependencies.
-- **React Context** for `WorkspaceIdProvider` (provides workspace ID to all dashboard children) and `NavigationProvider` (provides platform-agnostic routing).
-- **Local `useState`** for component-scoped UI state (forms, modals, filters).
+The architecture relies on a strict split between server state and client state. Mixing them is the most common way to break it.
 
-**TanStack Query conventions:**
-- `staleTime: Infinity` — WS events handle cache freshness, no polling or refetch-on-focus.
-- WS events trigger `queryClient.invalidateQueries()` (preferred) or `queryClient.setQueryData()` for granular updates.
-- All workspace-scoped query keys include `wsId` — workspace switch automatically uses new cache.
-- Mutations use `onMutate` for optimistic updates + `onError` for rollback + `onSettled` for invalidation.
+- **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.
 
-**Zustand store conventions:**
-- Stores in `@multica/core` hold only client state. Zero direct `api.*` calls — API access is injected via factory.
-- Auth/workspace stores are created by platform layer and registered via `registerAuthStore()` / `registerWorkspaceStore()`.
-- Other stores (issue, modal, navigation) are plain Zustand stores exported directly.
+**Hard rules — these are how the architecture stays coherent:**
 
-### Import Conventions
+- **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.
 
-```typescript
-// Core (headless business logic) — from @multica/core
-import { issueListOptions } from "@multica/core/issues/queries";
-import { useUpdateIssue } from "@multica/core/issues/mutations";
-import { useWorkspaceId } from "@multica/core/hooks";
-import type { Issue } from "@multica/core/types";
+**Common Zustand footguns to avoid:**
 
-// UI (atomic components) — from @multica/ui
-import { Button } from "@multica/ui/components/ui/button";
-import { cn } from "@multica/ui/lib/utils";
-import { ActorAvatar } from "@multica/ui/components/common/actor-avatar";
-
-// Views (shared pages) — from @multica/views
-import { IssuesPage } from "@multica/views/issues/components";
-import { useNavigation, AppLink } from "@multica/views/navigation";
-import { ModalRegistry } from "@multica/views/modals/registry";
-
-// Platform (web-only) — from @/platform
-import { WebNavigationProvider } from "@/platform/navigation";
-
-// Platform (desktop-only) — from @/ (maps to apps/desktop/src/renderer/src/)
-import { useTabStore } from "@/stores/tab-store";
-import { useDocumentTitle } from "@/hooks/use-document-title";
-import { DesktopNavigationProvider } from "@/platform/navigation";
-
-// Web-only features — from @/features
-import { SearchCommand } from "@/features/search";
-```
-
-`@/` maps to `apps/web/` in the web app and `apps/desktop/src/renderer/src/` in the desktop app. Within a package, use relative imports. Between packages, use `@multica/*`.
-
-### Data Flow
-
-```
-Browser → useQuery (@multica/core) → ApiClient (@multica/core/api) → REST API → sqlc → PostgreSQL
-Browser ← useQuery cache ← invalidateQueries ← WS event handlers ← WSClient ← Hub.Broadcast()
-```
-
-Mutations: `useMutation (@multica/core)` → optimistic cache update → API call → onSettled invalidation.
-WS events: `use-realtime-sync.ts` → `queryClient.invalidateQueries()` for most events, `setQueryData()` for granular issue/inbox updates.
-
-### 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).
+- 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).
 
 ## Commands
 
 ```bash
-# One-click setup & run
+# One-command dev (auto-setup + start everything)
+make dev              # Auto-creates env, installs deps, starts DB, migrates, launches app
+
+# Explicit setup & run (if you prefer separate steps)
 make setup            # First-time: ensure shared DB, create app DB, migrate
 make start            # Start backend + frontend together
 make stop             # Stop app processes for the current checkout
@@ -232,11 +72,11 @@ 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 via Next.js
-pnpm test             # TS tests (Vitest, via turbo)
+pnpm lint             # ESLint
+pnpm test             # TS tests (Vitest, all packages + apps via turbo)
 
 # Backend (Go)
-make dev              # Run Go server (port 8080)
+make server           # Run Go server only (port 8080)
 make daemon           # Run local daemon
 make build            # Build server + CLI binaries to server/bin/
 make cli ARGS="..."   # Run multica CLI (e.g. make cli ARGS="config")
@@ -245,12 +85,14 @@ 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
 
@@ -258,8 +100,8 @@ pnpm exec playwright test e2e/tests/specific-test.spec.ts
 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 (monorepo mode — must specify app)
-npx shadcn add badge -c apps/web
+# 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)
@@ -274,6 +116,8 @@ 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
@@ -288,82 +132,129 @@ 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.
 
 ### Package Boundary Rules
 
-- `packages/core/` — zero react-dom, zero localStorage (use StorageAdapter), zero process.env, zero UI libraries. Exception: `core/platform/storage.ts` has an SSR-safe `defaultStorage` using `localStorage` behind `typeof window` guards.
-- `packages/ui/` — zero `@multica/core` imports (pure UI, no business logic)
-- `packages/views/` — zero `next/*` imports, zero `react-router-dom` imports. Use `NavigationAdapter` for all routing. Use `window.open()` only for external URLs, never for internal navigation.
-- `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
+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 to the shared packages:
+When adding a new page or feature:
 
-1. **New page component** → add to `packages/views/<domain>/`. Import shared components from `@multica/views` and `@multica/ui`. 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 `apps/desktop/src/renderer/src/router.tsx` (react-router route with `handle: { title }`).
-3. **Navigation** → use `useNavigation().push()` or `<AppLink>`. Never use `next/link` or react-router's `<Link>` in shared code.
-4. **Dynamic page titles** → desktop pages that need dynamic titles (from async data) should use `useDocumentTitle(title)`. Static titles are set automatically via route `handle.title`.
-5. **Platform-specific UI** → if a feature is web-only (e.g. SearchCommand) or desktop-only (e.g. TabBar), keep it in the respective app. Use props slots (`extra`, `topSlot`) on shared layout components to inject platform-specific UI.
+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.
+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. Each app's `globals.css` follows the same import pattern:
-
-```css
-@import "tailwindcss";                   /* Core framework */
-@import "tw-animate-css";                /* Animation utilities for shadcn */
-@import "shadcn/tailwind.css";           /* data-* custom variants + no-scrollbar */
-@import "@multica/ui/styles/tokens.css"; /* Design tokens (colors, radius, fonts) */
-@import "@multica/ui/styles/base.css";   /* Shared base styles (scrollbar, shiki, body) */
-```
+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.
-- **App-specific styles** → keep in the app's own CSS. Web: `apps/web/app/custom.css`. Desktop: inline in `globals.css`.
-- **Design tokens** → use semantic tokens (`bg-background`, `text-muted-foreground`, `border-border`). Never use hardcoded Tailwind colors (`text-red-500`, `bg-gray-100`).
-- **`@source` directives** → both apps scan `packages/ui/**/*.tsx`, `packages/core/**/*.{ts,tsx}`, `packages/views/**/*.{ts,tsx}` so Tailwind sees all class names used in shared packages.
+- **`@source` directives** → both apps scan shared packages so Tailwind sees all class names.
 
 ## UI/UX Rules
 
-- Prefer shadcn components over custom implementations. Install via `npx shadcn add <component> -c apps/web` (monorepo flag required).
-- **Shared UI components** → `packages/ui/components/` — shadcn primitives and pure-props common components (multica-icon, theme-provider, actor-avatar, etc.).
-- **Shared business components** → `packages/views/<domain>/components/` — pages and domain-bound UI.
-- **Web-only components** → `apps/web/features/` or `apps/web/components/`.
-- **Desktop-only components** → `apps/desktop/src/renderer/src/components/` (tab-bar, desktop-layout).
-- 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`).
+- Prefer shadcn components over custom implementations. Install via `pnpm ui:add <component>` from project root — adds to `packages/ui/components/ui/`. All components use Base UI primitives (`@base-ui/react`), not Radix.
+- Use shadcn design tokens for styling. Avoid hardcoded color values.
 - Do not introduce extra state (useState, context, reducers) unless explicitly required by the design.
 - Pay close attention to **overflow** (truncate long text, scrollable containers), **alignment**, and **spacing** consistency.
-- When unsure about interaction or state design, ask — the user will provide direction.
 - **If a component is identical between web and desktop, it belongs in a shared package.** Do not copy-paste between apps.
 
 ## Testing Rules
 
-- **TypeScript**: Vitest. Mock external/third-party dependencies only.
-- **Go**: Standard `go test`. Tests should create their own fixture data in a test database.
+### 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}`);
+});
+```
 
 ## Commit Rules
 
 - Use atomic commits grouped by logical intent.
-- 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.
+- Conventional format: `feat(scope)`, `fix(scope)`, `refactor(scope)`, `docs`, `test(scope)`, `chore(scope)`.
 
 ## Minimum Pre-Push Checks
 
@@ -376,7 +267,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)
+pnpm test             # TS unit tests only (Vitest, all packages)
 make test             # Go tests only
 pnpm exec playwright test   # E2E only (requires backend + frontend running)
 ```
@@ -389,43 +280,29 @@ 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 `make check`
+- If any step fails, read the error output, fix the code, and re-run
 - Repeat until all checks pass
 - Only then consider the task complete
 
 **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
+## CLI Release
 
-E2E tests should be self-contained. Use the `TestApiClient` fixture for data setup/teardown:
+**Prerequisite:** A CLI release must accompany every Production deployment.
 
-```typescript
-import { loginAsDefault, createTestApi } from "./helpers";
-import type { TestApiClient } from "./fixtures";
+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
 
-let api: TestApiClient;
+By default, bump the patch version each release (e.g. `v0.1.12` → `v0.1.13`), unless the user specifies a specific version.
 
-test.beforeEach(async ({ page }) => {
-  api = await createTestApi();       // logged-in API client
-  await loginAsDefault(page);        // browser session
-});
+## Multi-tenancy
 
-test.afterEach(async () => {
-  await api.cleanup();               // delete any data created during the test
-});
+All queries filter by `workspace_id`. Membership checks gate access. `X-Workspace-ID` header routes requests to the correct workspace.
 
-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
-});
-```
+## Agent Assignees
+
+Assignees are polymorphic — can be a member or an agent. `assignee_type` + `assignee_id` on issues. Agents render with distinct styling (purple background, robot icon).

CLI_AND_DAEMON.md

@@ -30,6 +30,16 @@ This auto-detects your installation method (Homebrew or manual) and upgrades acc
 
 ## Quick Start
 
+```bash
+# One-command setup: configure, authenticate, and start the daemon
+multica setup
+
+# For self-hosted (local) deployments:
+multica setup --local
+```
+
+Or step by step:
+
 ```bash
 # 1. Authenticate (opens browser for login)
 multica login
@@ -162,23 +172,31 @@ Agent-specific overrides:
 
 ### Self-Hosted Server
 
-When connecting to a self-hosted Multica instance, point the CLI to your server before logging in:
+When connecting to a self-hosted Multica instance, the easiest approach is:
 
 ```bash
-export MULTICA_APP_URL=https://app.example.com
-export MULTICA_SERVER_URL=wss://api.example.com/ws
+# One command — auto-detects local server, configures, authenticates, starts daemon
+multica setup --local
+```
+
+Or configure manually:
+
+```bash
+# Configure for local Docker Compose (default ports)
+multica config local
+
+# Or set URLs individually:
+# multica config set app_url http://localhost:3000
+# multica config set server_url http://localhost:8080
+
+# For production with TLS:
+# multica config set app_url https://app.example.com
+# multica config set server_url https://api.example.com
 
 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.
@@ -306,6 +324,21 @@ 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.
 
+## Setup
+
+```bash
+# One-command setup: configure, authenticate, and start the daemon
+multica setup
+
+# For local self-hosted deployments (auto-detects or forces local mode)
+multica setup --local
+
+# Custom ports
+multica setup --local --port 9090 --frontend-port 4000
+```
+
+`multica setup` detects whether a local Multica server is running, configures the CLI, opens your browser for authentication, and starts the daemon — all in one step.
+
 ## Configuration
 
 ### View Config
@@ -316,10 +349,19 @@ multica config show
 
 Shows config file path, server URL, app URL, and default workspace.
 
+### Configure for Local Self-Hosted
+
+```bash
+multica config local                                      # Uses default ports (8080/3000)
+multica config local --port 9090 --frontend-port 4000     # Custom ports
+```
+
+Sets `server_url` and `app_url` for a local Docker Compose deployment in one command.
+
 ### Set Values
 
 ```bash
-multica config set server_url wss://api.example.com/ws
+multica config set server_url https://api.example.com
 multica config set app_url https://app.example.com
 multica config set workspace_id <workspace-id>
 ```

CONTRIBUTING.md

@@ -94,59 +94,52 @@ FORCE=1 make worktree-env
 
 ## First-Time Setup
 
-### Main Checkout
+### Quick Start (recommended)
 
-From the 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
 
 ```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 the app processes:
+Stop:
 
 ```bash
 make stop-main
 ```
 
-This does not stop PostgreSQL.
-
-### Worktree
-
-From the worktree directory:
+#### Worktree
 
 ```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 the worktree app processes:
+Stop:
 
 ```bash
 make stop-worktree
@@ -171,17 +164,15 @@ 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 worktree-env
-make setup-worktree
-make start-worktree
+make dev
 ```
 
 After that, day-to-day commands are:
 
 ```bash
-make start-worktree
-make stop-worktree
-make check-worktree
+make dev              # start (re-runs setup if needed, idempotent)
+make stop-worktree    # stop
+make check-worktree   # verify
 ```
 
 ## Running Main and Worktree at the Same Time
@@ -424,9 +415,7 @@ Warning:
 ### Stable Main Environment
 
 ```bash
-cp .env.example .env
-make setup-main
-make start-main
+make dev
 ```
 
 ### Feature Worktree
@@ -434,9 +423,7 @@ make start-main
 ```bash
 git worktree add ../multica-feature -b feat/my-change main
 cd ../multica-feature
-make worktree-env
-make setup-worktree
-make start-worktree
+make dev
 ```
 
 ### Return to a Previously Configured Worktree

Dockerfile

@@ -30,7 +30,9 @@ 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 ["./server"]
+ENTRYPOINT ["./entrypoint.sh"]

Dockerfile.web

@@ -0,0 +1,70 @@
+# --- 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_GOOGLE_CLIENT_ID
+ENV REMOTE_API_URL=$REMOTE_API_URL
+ENV NEXT_PUBLIC_GOOGLE_CLIENT_ID=$NEXT_PUBLIC_GOOGLE_CLIENT_ID
+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"]

Makefile

@@ -1,4 +1,4 @@
-.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
+.PHONY: 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 selfhost selfhost-stop
 
 MAIN_ENV_FILE ?= .env
 WORKTREE_ENV_FILE ?= .env.worktree
@@ -36,6 +36,53 @@ define REQUIRE_ENV
 	fi
 endef
 
+# ---------- Self-hosting (Docker Compose) ----------
+
+# One-command self-host: create env, start Docker Compose, wait for health
+selfhost:
+	@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 "==> Starting Multica via Docker Compose..."
+	docker compose -f docker-compose.selfhost.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 with any email + verification code: 888888"; \
+		echo ""; \
+		echo "Next — install the CLI and connect your machine:"; \
+		echo "  brew install multica-ai/tap/multica"; \
+		echo "  multica setup --local"; \
+	else \
+		echo ""; \
+		echo "Services are still starting. Check logs:"; \
+		echo "  docker compose -f docker-compose.selfhost.yml logs"; \
+	fi
+
+# Stop all Docker Compose self-host services
+selfhost-stop:
+	@echo "==> Stopping Multica services..."
+	docker compose -f docker-compose.selfhost.yml down
+	@echo "✓ All services stopped."
+
 # ---------- One-click commands ----------
 
 # First-time setup: install deps, start DB, run migrations
@@ -122,8 +169,12 @@ check-worktree:
 
 # ---------- Individual commands ----------
 
-# Go server
+# One-command dev: auto-setup env/deps/db/migrations, then start all services
 dev:
+	@bash scripts/dev.sh
+
+# Go server only
+server:
 	$(REQUIRE_ENV)
 	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
 	cd server && go run ./cmd/server
@@ -139,10 +190,11 @@ multica:
 
 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:
 	cd server && go build -o bin/server ./cmd/server
-	cd server && go build -ldflags "-X main.version=$(VERSION) -X main.commit=$(COMMIT)" -o bin/multica ./cmd/multica
+	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
 
 test:

README.md

@@ -47,57 +47,36 @@ Multica manages the full agent lifecycle: from task assignment to execution moni
 - **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
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
+```
+
+Installs the Multica CLI on macOS and Linux. Works with Homebrew or downloads the binary directly.
+
+After installation:
+
+```bash
+multica login          # Authenticate (opens browser)
+multica daemon start   # Start the local agent runtime
+multica daemon stop    # Stop the daemon when done
+```
+
+> **Self-hosting?** Add `--local` 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 -- --local
+> ```
+>
+> Requires Docker. See the [Self-Hosting Guide](SELF_HOSTING.md) for details.
+
+---
+
 ## Getting Started
 
-### Multica Cloud
-
-The fastest way to get started — no setup required: **[multica.ai](https://multica.ai)**
-
-### Self-Host with Docker
-
-```bash
-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
-```
-
-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.
-
-**Option A — paste this to your coding agent (Claude Code, Codex, OpenClaw, OpenCode, etc.):**
-
-```
-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.
-```
-
-**Option B — install manually:**
-
-```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`, `openclaw`, `opencode`) 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
@@ -105,7 +84,7 @@ 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`, `openclaw`, `opencode`) available on your PATH.
+The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `openclaw`, `opencode`) on your PATH.
 
 ### 2. Verify your runtime
 
@@ -121,7 +100,27 @@ Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just
 
 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.
 
-That's it! Your agent is now part of the team. 🎉
+---
+
+## 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 (configure + login + start daemon) |
+| `multica setup --local` | Same, but for self-hosted deployments |
+| `multica config local` | Configure CLI for a local self-hosted server |
+| `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.
+
+---
 
 ## Architecture
 
@@ -152,10 +151,9 @@ 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
-pnpm install
-cp .env.example .env
-make setup
-make start
+make dev
 ```
 
+`make dev` auto-detects your environment (main checkout or worktree), creates the env file, installs dependencies, sets up the database, runs migrations, and starts all services.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, worktree support, testing, and troubleshooting.

README.zh-CN.md

@@ -47,52 +47,33 @@ Multica 管理完整的 Agent 生命周期：从任务分配到执行监控再
 - **统一运行时** — 一个控制台管理所有算力。本地 daemon 和云端运行时，自动检测可用 CLI，实时监控。
 - **多工作区** — 按团队组织工作，工作区级别隔离。每个工作区有独立的 Agent、Issue 和设置。
 
-## 快速开始
+---
 
-### Multica 云服务
-
-最快的上手方式，无需任何配置：**[multica.ai](https://multica.ai)**
-
-### Docker 自部署
+## 快速安装
 
 ```bash
-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                                         # 启动应用
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
 ```
 
-完整部署文档请参阅 [自部署指南](SELF_HOSTING.md)。
+安装 Multica CLI，支持 macOS 和 Linux。有 Homebrew 用 Homebrew，没有则直接下载二进制。
 
-## CLI
-
-`multica` CLI 将你的本地机器连接到 Multica — 用于认证、管理工作区和运行 Agent daemon。
-
-**方式 A — 将以下指令粘贴给你的 coding agent（Claude Code、Codex、OpenClaw、OpenCode 等）：**
-
-```
-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.
-```
-
-**方式 B — 手动安装：**
+安装完成后：
 
 ```bash
-# 安装
-brew tap multica-ai/tap
-brew install multica
-
-# 认证并启动
-multica login
-multica daemon start
+multica login          # 认证（打开浏览器）
+multica daemon start   # 启动本地 Agent 运行时
+multica daemon stop    # 停止 daemon
 ```
 
-daemon 会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`openclaw`、`opencode`）。当 Agent 被分配任务时，daemon 会创建隔离环境、运行 Agent、并将结果回传。
+> **自部署？** 加上 `--local` 在本地部署完整的 Multica 服务：
+>
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --local
+> ```
+>
+> 需要 Docker。详见 [自部署指南](SELF_HOSTING.md)。
 
-完整命令参考请参阅 [CLI 与 Daemon 指南](CLI_AND_DAEMON.md)。
+---
 
 ## 快速上手
 

SELF_HOSTING.md

@@ -1,10 +1,8 @@
 # Self-Hosting Guide
 
-This guide walks you through deploying Multica on your own infrastructure.
+Deploy Multica on your own infrastructure in minutes.
 
-## Architecture Overview
-
-Multica has three components:
+## Architecture
 
 | Component | Description | Technology |
 |-----------|-------------|------------|
@@ -12,16 +10,151 @@ Multica has three components:
 | **Frontend** | Web application | Next.js 16 |
 | **Database** | Primary data store | PostgreSQL 17 with pgvector |
 
-Additionally, each user who wants to run AI agents locally installs the **`multica` CLI** and runs the **agent daemon** on their own machine.
+Each user who runs AI agents locally also installs the **`multica` CLI** and runs the **agent daemon** on their own machine.
 
-## Prerequisites
+## Quick Install (Recommended)
 
-- 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
+One command to set up everything — server, CLI, and configuration:
 
-## Quick Start (Docker Compose)
+```bash
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --local
+```
+
+This automatically clones the repository, starts all services via Docker Compose, and installs the `multica` CLI.
+
+Once complete, open http://localhost:3000, log in with any email + verification code **`888888`**, then:
+
+```bash
+multica login          # Authenticate (opens browser)
+multica daemon start   # Start the agent daemon
+```
+
+> **Prerequisites:** Docker and Docker Compose must be installed. The script checks for this and provides install links if missing.
+
+---
+
+## 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.
+
+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. Enter any email address and use verification code **`888888`** to log in.
+
+> This master code works in all non-production environments (i.e. when `APP_ENV` is not set to `production`). For production, configure an email provider — see [Advanced Configuration](SELF_HOSTING_ADVANCED.md#email-required-for-authentication).
+
+### Step 3 — Install CLI & Start Daemon
+
+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)
+
+### b) One-command setup
+
+```bash
+multica setup --local
+```
+
+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
+
+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 config set server_url https://api.multica.ai
+multica config set app_url https://multica.ai
+multica login
+```
+
+Or re-run the install script without `--local` — it will reconfigure the CLI automatically:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
+```
+
+> Your local Docker services are unaffected. Stop them separately if you no longer need them.
+
+## Rebuilding After Updates
+
+```bash
+git pull
+make selfhost
+```
+
+Migrations run automatically on backend startup.
+
+---
+
+## Manual Docker Compose Setup
+
+If you prefer running Docker Compose steps manually instead of `make selfhost`:
 
 ```bash
 git clone https://github.com/multica-ai/multica.git
@@ -29,258 +162,46 @@ cd multica
 cp .env.example .env
 ```
 
-Edit `.env` with your production values (see [Configuration](#configuration) below), then:
+Edit `.env` — at minimum, change `JWT_SECRET`:
 
 ```bash
-# 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
+JWT_SECRET=$(openssl rand -hex 32)
 ```
 
-For the frontend:
+Then start everything:
 
 ```bash
-pnpm install
-pnpm build
-
-# Start the frontend (production mode)
-cd apps/web
-REMOTE_API_URL=http://localhost:8080 pnpm start
+docker compose -f docker-compose.selfhost.yml up -d
 ```
 
-## Configuration
+## Manual CLI 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` |
-
-### 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
+If you prefer configuring the CLI step by step instead of `multica setup`:
 
 ```bash
-docker compose up -d postgres
+# Point CLI to your local server
+multica config local
+
+# Or set URLs manually:
+# multica config set app_url http://localhost:3000
+# multica config set server_url http://localhost:8080
+
+# Login (opens browser)
+multica login
+
+# Start the daemon
+multica daemon start
 ```
 
-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:
+For production deployments with TLS:
 
 ```bash
-# Using the built binary
-./server/bin/migrate up
-
-# Or from source
-cd server && go run ./cmd/migrate up
+multica config set app_url https://app.example.com
+multica config set server_url https://api.example.com
+multica login
+multica daemon start
 ```
 
-## Reverse Proxy
+## Advanced Configuration
 
-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
-   #
-   # For production deployments with TLS:
-   export MULTICA_APP_URL=https://app.example.com
-   export MULTICA_SERVER_URL=wss://api.example.com/ws
-   #
-   # For local deployments without TLS:
-   # export MULTICA_APP_URL=http://localhost:3000
-   # export MULTICA_SERVER_URL=ws://localhost:8080/ws
-
-   # Login (opens browser)
-   multica login
-
-   # Start the daemon
-   multica daemon start
-   ```
-
-   > **Note:** Use `https://` and `wss://` for production deployments behind a TLS-terminating reverse proxy. For local or development deployments without TLS, use `http://` and `ws://` instead.
-
-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.
+For environment variables, manual setup (without Docker), reverse proxy configuration, database setup, and more, see the [Advanced Configuration Guide](SELF_HOSTING_ADVANCED.md).

SELF_HOSTING_ADVANCED.md

@@ -0,0 +1,224 @@
+# 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` |
+
+### 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:** For local/development deployments without email configured, you can use the master verification code `888888` to log in.
+
+### 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 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 (set before building the frontend image)
+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.
+
+## Upgrading
+
+```bash
+git pull
+docker compose -f docker-compose.selfhost.yml up -d --build
+```
+
+Migrations run automatically on backend startup. They are idempotent — running them multiple times has no effect.

SELF_HOSTING_AI.md

@@ -0,0 +1,74 @@
+# 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`
+
+## One-Command Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --local
+```
+
+This installs everything: clones the repo, starts Docker services, and installs the CLI.
+
+Wait for the output `✓ Multica is installed and running!` before proceeding.
+
+**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 --local
+```
+
+The `multica setup --local` 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 --local --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/electron.vite.config.ts

@@ -11,6 +11,10 @@ export default defineConfig({
     plugins: [externalizeDepsPlugin()],
   },
   renderer: {
+    server: {
+      port: 5173,
+      strictPort: true,
+    },
     plugins: [react(), tailwindcss()],
     resolve: {
       alias: {

apps/desktop/package.json

@@ -15,19 +15,25 @@
     "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",
     "@multica/core": "workspace:*",
     "@multica/ui": "workspace:*",
     "@multica/views": "workspace:*",
+    "@fontsource/geist-mono": "^5.2.7",
+    "@fontsource/geist-sans": "^5.2.5",
     "react-router-dom": "^7.6.0",
     "shadcn": "^4.1.0",
     "sonner": "^2.0.7",
     "tw-animate-css": "^1.4.0"
   },
   "devDependencies": {
-    "@multica/tsconfig": "workspace:*",
     "@electron-toolkit/tsconfig": "^2.0.0",
+    "@multica/tsconfig": "workspace:*",
     "@tailwindcss/vite": "^4",
     "@types/node": "catalog:",
     "@types/react": "catalog:",

apps/desktop/src/main/index.ts

@@ -17,6 +17,7 @@ function createWindow(): void {
     webPreferences: {
       preload: join(__dirname, "../preload/index.js"),
       sandbox: false,
+      webSecurity: false,
     },
   });
 

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

@@ -1,8 +1,26 @@
-import { RouterProvider } from "react-router-dom";
 import { CoreProvider } from "@multica/core/platform";
+import { useAuthStore } from "@multica/core/auth";
 import { ThemeProvider } from "@multica/ui/components/common/theme-provider";
+import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
 import { Toaster } from "sonner";
-import { router } from "./router";
+import { DesktopLoginPage } from "./pages/login";
+import { DesktopShell } from "./components/desktop-layout";
+
+function AppContent() {
+  const user = useAuthStore((s) => s.user);
+  const isLoading = useAuthStore((s) => s.isLoading);
+
+  if (isLoading) {
+    return (
+      <div className="flex h-screen items-center justify-center">
+        <MulticaIcon className="size-6 animate-pulse" />
+      </div>
+    );
+  }
+
+  if (!user) return <DesktopLoginPage />;
+  return <DesktopShell />;
+}
 
 export default function App() {
   return (
@@ -11,7 +29,7 @@ export default function App() {
         apiBaseUrl={import.meta.env.VITE_API_URL || "http://localhost:8080"}
         wsUrl={import.meta.env.VITE_WS_URL || "ws://localhost:8080/ws"}
       >
-        <RouterProvider router={router} />
+        <AppContent />
       </CoreProvider>
       <Toaster />
     </ThemeProvider>

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

@@ -1,19 +1,20 @@
 import { useEffect } from "react";
-import { Outlet, useNavigate } from "react-router-dom";
 import { ChevronLeft, ChevronRight } from "lucide-react";
-import { useNavigationHistory } from "@/hooks/use-history-stack";
-import { useTabSync } from "@/hooks/use-tab-sync";
+import { useTabHistory } from "@/hooks/use-tab-history";
+import { useActiveTitleSync } from "@/hooks/use-tab-sync";
 import { useTabStore, resolveRouteIcon } from "@/stores/tab-store";
 import { SidebarProvider } from "@multica/ui/components/ui/sidebar";
-import { WorkspaceIdProvider } from "@multica/core/hooks";
 import { ModalRegistry } from "@multica/views/modals/registry";
-import { AppSidebar, useDashboardGuard } from "@multica/views/layout";
+import { AppSidebar, DashboardGuard } from "@multica/views/layout";
+import { SearchCommand, SearchTrigger } from "@multica/views/search";
+import { ChatFab, ChatWindow } from "@multica/views/chat";
 import { DesktopNavigationProvider } from "@/platform/navigation";
 import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
 import { TabBar } from "./tab-bar";
+import { TabContent } from "./tab-content";
 
 function SidebarTopBar() {
-  const { canGoBack, canGoForward, goBack, goForward } = useNavigationHistory();
+  const { canGoBack, canGoForward, goBack, goForward } = useTabHistory();
 
   return (
     <div
@@ -43,17 +44,7 @@ function SidebarTopBar() {
   );
 }
 
-export function DesktopLayout() {
-  return (
-    <DesktopNavigationProvider>
-      <DesktopLayoutInner />
-    </DesktopNavigationProvider>
-  );
-}
-
 function useInternalLinkHandler() {
-  const navigate = useNavigate();
-
   useEffect(() => {
     const handler = (e: Event) => {
       const path = (e as CustomEvent).detail?.path;
@@ -62,56 +53,50 @@ function useInternalLinkHandler() {
       const store = useTabStore.getState();
       const tabId = store.openTab(path, path, icon);
       store.setActiveTab(tabId);
-      navigate(path);
     };
     window.addEventListener("multica:navigate", handler);
     return () => window.removeEventListener("multica:navigate", handler);
-  }, [navigate]);
+  }, []);
 }
 
-function DesktopLayoutInner() {
-  useTabSync();
+export function DesktopShell() {
   useInternalLinkHandler();
-  const { user, isLoading, workspace } = useDashboardGuard("/login");
-
-  if (isLoading) {
-    return (
-      <div className="flex h-screen items-center justify-center">
-        <MulticaIcon className="size-6" />
-      </div>
-    );
-  }
-
-  if (!user) return null;
+  useActiveTitleSync();
 
   return (
-    <div className="flex h-screen">
-      <SidebarProvider className="flex-1">
-        <AppSidebar topSlot={<SidebarTopBar />} />
-        {/* Right side: header + content container */}
-        <div className="flex flex-1 min-w-0 flex-col">
-          {/* Tab bar + drag region */}
-          <header
-            className="h-12 shrink-0"
-            style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
-          >
-            <TabBar />
-          </header>
-          {/* Content area with inset styling */}
-          <div className="flex flex-1 min-h-0 flex-col overflow-hidden mr-2 mb-2 ml-0.5 rounded-xl shadow-sm bg-background">
-            {workspace ? (
-              <WorkspaceIdProvider wsId={workspace.id}>
-                <Outlet />
-                <ModalRegistry />
-              </WorkspaceIdProvider>
-            ) : (
-              <div className="flex h-full items-center justify-center">
-                <MulticaIcon className="size-6 animate-pulse" />
-              </div>
-            )}
+    <DesktopNavigationProvider>
+      <DashboardGuard
+        loginPath="/login"
+        loadingFallback={
+          <div className="flex h-screen items-center justify-center">
+            <MulticaIcon className="size-6 animate-pulse" />
           </div>
+        }
+      >
+        <div className="flex h-screen">
+          <SidebarProvider className="flex-1">
+            <AppSidebar topSlot={<SidebarTopBar />} searchSlot={<SearchTrigger />} />
+            {/* Right side: header + content container */}
+            <div className="flex flex-1 min-w-0 flex-col">
+              {/* Tab bar + drag region */}
+              <header
+                className="h-12 shrink-0"
+                style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
+              >
+                <TabBar />
+              </header>
+              {/* Content area with inset styling */}
+              <div className="flex flex-1 min-h-0 flex-col overflow-hidden mr-2 mb-2 ml-0.5 rounded-xl shadow-sm bg-background">
+                <TabContent />
+              </div>
+            </div>
+          </SidebarProvider>
         </div>
-      </SidebarProvider>
-    </div>
+        <ModalRegistry />
+        <SearchCommand />
+        <ChatWindow />
+        <ChatFab />
+      </DashboardGuard>
+    </DesktopNavigationProvider>
   );
 }

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

@@ -1,4 +1,3 @@
-import { useNavigate } from "react-router-dom";
 import {
   Inbox,
   CircleUser,
@@ -11,6 +10,24 @@ import {
   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, resolveRouteIcon, type Tab } from "@/stores/tab-store";
 
@@ -24,34 +41,59 @@ const TAB_ICONS: Record<string, LucideIcon> = {
   Settings,
 };
 
-function TabItem({ tab, isActive }: { tab: Tab; isActive: boolean }) {
-  const navigate = useNavigate();
+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);
-    navigate(tab.path);
+    // No navigate() — Activity handles visibility
   };
 
   const handleClose = (e: React.MouseEvent) => {
     e.stopPropagation();
-    const newPath = closeTab(tab.id);
-    if (newPath) navigate(newPath);
+    closeTab(tab.id);
+    // No navigate() — store handles activeTabId switch
+  };
+
+  // Stop pointer down on close so it doesn't start a drag on the parent button.
+  const stopDragOnClose = (e: React.PointerEvent) => {
+    e.stopPropagation();
   };
 
   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 text-sidebar-accent-foreground"
-          : "bg-sidebar-accent/60 text-muted-foreground hover:bg-sidebar-accent/80",
+          ? "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" />}
@@ -64,18 +106,20 @@ function TabItem({ tab, isActive }: { tab: Tab; isActive: boolean }) {
       >
         {tab.title}
       </span>
-      <span
-        onClick={handleClose}
-        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>
+      {!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 navigate = useNavigate();
   const addTab = useTabStore((s) => s.addTab);
   const setActiveTab = useTabStore((s) => s.setActiveTab);
 
@@ -83,12 +127,13 @@ function NewTabButton() {
     const path = "/issues";
     const tabId = addTab(path, "Issues", resolveRouteIcon(path));
     setActiveTab(tabId);
-    navigate(path);
+    // No navigate() — new tab's router starts at /issues automatically
   };
 
   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" />
@@ -99,15 +144,44 @@ function NewTabButton() {
 export function TabBar() {
   const tabs = useTabStore((s) => s.tabs);
   const activeTabId = useTabStore((s) => s.activeTabId);
+  const moveTab = useTabStore((s) => s.moveTab);
+
+  // distance: 5 — pointer must move 5px to start a drag, otherwise it's a click.
+  const sensors = useSensors(
+    useSensor(PointerSensor, {
+      activationConstraint: { distance: 5 },
+    }),
+  );
+
+  const 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"
-      style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
-    >
-      {tabs.map((tab) => (
-        <TabItem key={tab.id} tab={tab} isActive={tab.id === activeTabId} />
-      ))}
+    <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>
       <NewTabButton />
     </div>
   );

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

@@ -0,0 +1,43 @@
+import { Activity, useEffect } from "react";
+import { RouterProvider } from "react-router-dom";
+import { useTabStore } from "@/stores/tab-store";
+import { TabNavigationProvider } from "@/platform/navigation";
+import { useTabRouterSync } from "@/hooks/use-tab-router-sync";
+
+/** Inner wrapper rendered inside each tab's RouterProvider. */
+function TabRouterInner({ tabId }: { tabId: string }) {
+  const tab = useTabStore((s) => s.tabs.find((t) => t.id === tabId));
+  useTabRouterSync(tabId, tab!.router);
+  return null;
+}
+
+/**
+ * Renders all tabs using Activity for state preservation.
+ * Only the active tab is visible; hidden tabs keep their DOM and React state.
+ */
+export function TabContent() {
+  const tabs = useTabStore((s) => s.tabs);
+  const activeTabId = useTabStore((s) => s.activeTabId);
+
+  // Sync document.title when switching tabs
+  useEffect(() => {
+    const tab = tabs.find((t) => t.id === activeTabId);
+    if (tab) document.title = tab.title;
+  }, [activeTabId, tabs]);
+
+  return (
+    <>
+      {tabs.map((tab) => (
+        <Activity
+          key={tab.id}
+          mode={tab.id === activeTabId ? "visible" : "hidden"}
+        >
+          <TabNavigationProvider router={tab.router}>
+            <RouterProvider router={tab.router} />
+            <TabRouterInner tabId={tab.id} />
+          </TabNavigationProvider>
+        </Activity>
+      ))}
+    </>
+  );
+}

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

@@ -6,6 +6,13 @@
 
 @custom-variant dark (&:is(.dark *));
 
+/* Geist font: define CSS variables that tokens.css @theme inline references.
+   Web app gets these from next/font/google; desktop must set them explicitly. */
+:root {
+  --font-sans: "Geist Sans", ui-sans-serif, system-ui, -apple-system, sans-serif;
+  --font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
 @source "../../../../../packages/ui/**/*.tsx";
 @source "../../../../../packages/core/**/*.{ts,tsx}";
 @source "../../../../../packages/views/**/*.{ts,tsx}";

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

@@ -1,57 +0,0 @@
-import { useState, useEffect, useRef, useCallback } from "react";
-import { useLocation } from "react-router-dom";
-
-export function useNavigationHistory() {
-  const [canGoBack, setCanGoBack] = useState(false);
-  const [canGoForward, setCanGoForward] = useState(false);
-  const location = useLocation();
-
-  const seqRef = useRef(1);
-  const maxSeqRef = useRef(1);
-  const isNavRef = useRef(false);
-
-  // Seed initial entry + listen for popstate (browser back/forward)
-  useEffect(() => {
-    window.history.replaceState({ seq: 1 }, "");
-
-    const handlePopState = (event: PopStateEvent) => {
-      const seq = (event.state?.seq as number) ?? 0;
-      seqRef.current = seq;
-      setCanGoBack(seq > 1);
-      setCanGoForward(seq < maxSeqRef.current);
-    };
-
-    window.addEventListener("popstate", handlePopState);
-    return () => window.removeEventListener("popstate", handlePopState);
-  }, []);
-
-  // Stamp seq on each new navigation
-  useEffect(() => {
-    // Skip if this was our own goBack/goForward call
-    if (isNavRef.current) {
-      isNavRef.current = false;
-      return;
-    }
-
-    const nextSeq = seqRef.current + 1;
-    seqRef.current = nextSeq;
-    maxSeqRef.current = nextSeq;
-    window.history.replaceState({ seq: nextSeq }, "");
-    setCanGoBack(nextSeq > 1);
-    setCanGoForward(false);
-  }, [location]);
-
-  const goBack = useCallback(() => {
-    if (!canGoBack) return;
-    isNavRef.current = true;
-    window.history.back();
-  }, [canGoBack]);
-
-  const goForward = useCallback(() => {
-    if (!canGoForward) return;
-    isNavRef.current = true;
-    window.history.forward();
-  }, [canGoForward]);
-
-  return { canGoBack, canGoForward, goBack, goForward };
-}

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

@@ -0,0 +1,40 @@
+import { useCallback } from "react";
+import type { DataRouter } from "react-router-dom";
+import { useTabStore } 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 tab's history state.
+ * Replaces the old global useNavigationHistory() hook.
+ */
+export function useTabHistory() {
+  // Return the actual tab object from the store — stable reference.
+  // Do NOT create a new object in the selector (causes infinite re-renders).
+  const activeTab = useTabStore((s) =>
+    s.tabs.find((t) => t.id === s.activeTabId),
+  );
+
+  const canGoBack = (activeTab?.historyIndex ?? 0) > 0;
+  const canGoForward =
+    (activeTab?.historyIndex ?? 0) < (activeTab?.historyLength ?? 1) - 1;
+
+  const goBack = useCallback(() => {
+    if (!activeTab || activeTab.historyIndex <= 0) return;
+    popDirectionHints.set(activeTab.router, "back");
+    activeTab.router.navigate(-1);
+  }, [activeTab]);
+
+  const goForward = useCallback(() => {
+    if (!activeTab || activeTab.historyIndex >= activeTab.historyLength - 1)
+      return;
+    popDirectionHints.set(activeTab.router, "forward");
+    activeTab.router.navigate(1);
+  }, [activeTab]);
+
+  return { canGoBack, canGoForward, goBack, goForward };
+}

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

@@ -0,0 +1,49 @@
+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,45 +1,13 @@
-import { useEffect, useRef } from "react";
-import { useLocation } from "react-router-dom";
-import { useTabStore, resolveRouteIcon } from "@/stores/tab-store";
+import { useEffect } from "react";
+import { useTabStore } from "@/stores/tab-store";
 
 /**
- * Keeps the active tab in sync with the current URL and document.title.
+ * Watches document.title via MutationObserver and updates the active tab's title.
  *
- * Two sync directions:
- * 1. URL change → update active tab's path (and set a default title from the route)
- * 2. document.title change → update active tab's title (pages set this naturally)
- *
- * Tab switches (clicking another tab) are ignored — the tab already has its metadata.
+ * 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 useTabSync() {
-  const location = useLocation();
-  const isTabSwitch = useRef(false);
-
-  // Detect tab switches so we don't overwrite metadata
-  useEffect(() => {
-    return useTabStore.subscribe((state, prev) => {
-      if (state.activeTabId !== prev.activeTabId) {
-        isTabSwitch.current = true;
-      }
-    });
-  }, []);
-
-  // Sync URL → tab path
-  useEffect(() => {
-    if (isTabSwitch.current) {
-      isTabSwitch.current = false;
-      return;
-    }
-
-    const { tabs, activeTabId } = useTabStore.getState();
-    const activeTab = tabs.find((t) => t.id === activeTabId);
-    if (activeTab && activeTab.path !== location.pathname) {
-      const icon = resolveRouteIcon(location.pathname);
-      useTabStore.getState().updateActiveTab(location.pathname, document.title, icon);
-    }
-  }, [location.pathname]);
-
-  // Sync document.title → tab title
+export function useActiveTitleSync() {
   useEffect(() => {
     const observer = new MutationObserver(() => {
       const title = document.title;
@@ -47,7 +15,7 @@ export function useTabSync() {
       const { tabs, activeTabId } = useTabStore.getState();
       const activeTab = tabs.find((t) => t.id === activeTabId);
       if (activeTab && activeTab.title !== title) {
-        useTabStore.getState().updateActiveTab(activeTab.path, title, activeTab.icon);
+        useTabStore.getState().updateTab(activeTabId, { title });
       }
     });
 

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

@@ -1,5 +1,11 @@
 import ReactDOM from "react-dom/client";
 import App from "./App";
+import "@fontsource/geist-sans/400.css";
+import "@fontsource/geist-sans/500.css";
+import "@fontsource/geist-sans/600.css";
+import "@fontsource/geist-sans/700.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/login.tsx

@@ -1,10 +1,7 @@
-import { useNavigate } from "react-router-dom";
 import { LoginPage } from "@multica/views/auth";
 import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
 
 export function DesktopLoginPage() {
-  const navigate = useNavigate();
-
   return (
     <div className="flex h-screen flex-col">
       {/* Traffic light inset */}
@@ -14,7 +11,9 @@ export function DesktopLoginPage() {
       />
       <LoginPage
         logo={<MulticaIcon bordered size="lg" />}
-        onSuccess={() => navigate("/issues", { replace: true })}
+        onSuccess={() => {
+          // Auth store update triggers AppContent re-render → shows DesktopShell
+        }}
       />
     </div>
   );

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

@@ -0,0 +1,17 @@
+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,33 +1,116 @@
-import { useNavigate, useLocation } from "react-router-dom";
+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 { useTabStore, resolveRouteIcon } from "@/stores/tab-store";
 
+/**
+ * Root-level navigation provider for components outside the per-tab RouterProviders
+ * (sidebar, search dialog, modals, etc.).
+ *
+ * Reads from the active tab's memory router via router.subscribe().
+ * Does NOT use any react-router hooks — it's above all RouterProviders.
+ */
 export function DesktopNavigationProvider({
   children,
 }: {
   children: React.ReactNode;
 }) {
-  const navigate = useNavigate();
-  const location = useLocation();
+  const activeTab = useTabStore((s) => s.tabs.find((t) => t.id === s.activeTabId));
+  const [pathname, setPathname] = useState(activeTab?.path ?? "/issues");
 
-  const adapter: NavigationAdapter = {
-    push: (path) => navigate(path),
-    replace: (path) => navigate(path, { replace: true }),
-    back: () => navigate(-1),
-    pathname: location.pathname,
-    searchParams: new URLSearchParams(location.search),
-    openInNewTab: (path, title?) => {
-      const icon = resolveRouteIcon(path);
-      const store = useTabStore.getState();
-      const tabId = store.openTab(path, title ?? path, icon);
-      store.setActiveTab(tabId);
-      navigate(path);
-    },
-    getShareableUrl: (path) => `https://www.multica.ai${path}`,
-  };
+  // Subscribe to the active tab's router for pathname updates
+  useEffect(() => {
+    if (!activeTab) return;
+    setPathname(activeTab.router.state.location.pathname);
+    return activeTab.router.subscribe((state) => {
+      setPathname(state.location.pathname);
+    });
+  }, [activeTab?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const adapter: NavigationAdapter = useMemo(
+    () => ({
+      push: (path: string) => {
+        if (path === "/login") {
+          // DashboardGuard token expired — force back to login screen
+          useAuthStore.getState().logout();
+          return;
+        }
+        const tab = useTabStore.getState().tabs.find(
+          (t) => t.id === useTabStore.getState().activeTabId,
+        );
+        tab?.router.navigate(path);
+      },
+      replace: (path: string) => {
+        const tab = useTabStore.getState().tabs.find(
+          (t) => t.id === useTabStore.getState().activeTabId,
+        );
+        tab?.router.navigate(path, { replace: true });
+      },
+      back: () => {
+        const tab = useTabStore.getState().tabs.find(
+          (t) => t.id === useTabStore.getState().activeTabId,
+        );
+        tab?.router.navigate(-1);
+      },
+      pathname,
+      searchParams: new URLSearchParams(),
+      openInNewTab: (path: string, title?: string) => {
+        const icon = resolveRouteIcon(path);
+        const store = useTabStore.getState();
+        const tabId = store.openTab(path, title ?? path, icon);
+        store.setActiveTab(tabId);
+      },
+      getShareableUrl: (path: string) => `https://www.multica.ai${path}`,
+    }),
+    [pathname],
+  );
+
+  return <NavigationProvider value={adapter}>{children}</NavigationProvider>;
+}
+
+/**
+ * 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) => router.navigate(path),
+      replace: (path: string) => router.navigate(path, { replace: true }),
+      back: () => router.navigate(-1),
+      pathname: location.pathname,
+      searchParams: new URLSearchParams(location.search),
+      openInNewTab: (path: string, title?: string) => {
+        const icon = resolveRouteIcon(path);
+        const store = useTabStore.getState();
+        const newTabId = store.openTab(path, title ?? path, icon);
+        store.setActiveTab(newTabId);
+      },
+      getShareableUrl: (path: string) => `https://www.multica.ai${path}`,
+    }),
+    [router, location],
+  );
 
   return <NavigationProvider value={adapter}>{children}</NavigationProvider>;
 }

apps/desktop/src/renderer/src/router.tsx

@@ -1,67 +0,0 @@
-import { createHashRouter, Navigate, Outlet, useMatches } from "react-router-dom";
-import { useEffect } from "react";
-import { DesktopLayout } from "./components/desktop-layout";
-import { DesktopLoginPage } from "./pages/login";
-import { IssueDetailPage } from "./pages/issue-detail-page";
-// Extracted pages from @multica/views
-import { IssuesPage } from "@multica/views/issues/components";
-import { MyIssuesPage } from "@multica/views/my-issues";
-import { RuntimesPage } from "@multica/views/runtimes";
-import { SkillsPage } from "@multica/views/skills";
-import { AgentsPage } from "@multica/views/agents";
-import { InboxPage } from "@multica/views/inbox";
-import { SettingsPage } from "@multica/views/settings";
-
-/**
- * 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 />
-    </>
-  );
-}
-
-export const router = createHashRouter([
-  {
-    path: "/",
-    element: <DesktopLayout />,
-    children: [
-      {
-        element: <PageShell />,
-        children: [
-          { index: true, element: <Navigate to="/issues" replace /> },
-          { path: "issues", element: <IssuesPage />, handle: { title: "Issues" } },
-          { path: "issues/:id", element: <IssueDetailPage />, handle: { title: "Issue" } },
-          { path: "my-issues", element: <MyIssuesPage />, handle: { title: "My Issues" } },
-          { path: "runtimes", element: <RuntimesPage />, 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 />, handle: { title: "Settings" } },
-        ],
-      },
-    ],
-  },
-  { path: "/login", element: <DesktopLoginPage /> },
-]);

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

@@ -0,0 +1,99 @@
+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 { IssuesPage } from "@multica/views/issues/components";
+import { ProjectsPage } from "@multica/views/projects/components";
+import { MyIssuesPage } from "@multica/views/my-issues";
+import { RuntimesPage } from "@multica/views/runtimes";
+import { SkillsPage } from "@multica/views/skills";
+import { AgentsPage } from "@multica/views/agents";
+import { InboxPage } from "@multica/views/inbox";
+import { SettingsPage } from "@multica/views/settings";
+
+/**
+ * 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 (no layout wrapper). */
+export const appRoutes: RouteObject[] = [
+  {
+    element: <PageShell />,
+    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: "my-issues",
+        element: <MyIssuesPage />,
+        handle: { title: "My Issues" },
+      },
+      {
+        path: "runtimes",
+        element: <RuntimesPage />,
+        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 />,
+        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.ts

@@ -1,4 +1,9 @@
 import { create } from "zustand";
+import { createJSONStorage, persist } from "zustand/middleware";
+import { arrayMove } from "@dnd-kit/sortable";
+import { createPersistStorage, defaultStorage } from "@multica/core/platform";
+import type { DataRouter } from "react-router-dom";
+import { createTabRouter } from "../routes";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -9,6 +14,9 @@ export interface Tab {
   path: string;
   title: string;
   icon: string;
+  router: DataRouter;
+  historyIndex: number;
+  historyLength: number;
 }
 
 interface TabStore {
@@ -19,12 +27,16 @@ interface TabStore {
   openTab: (path: string, title: string, icon: string) => string;
   /** Always create a new tab (no dedup). Returns the tab id. */
   addTab: (path: string, title: string, icon: string) => string;
-  /** Close a tab. Returns the path to navigate to if active tab changed, or null. */
-  closeTab: (tabId: string) => string | null;
+  /** Close a tab. Disposes router. */
+  closeTab: (tabId: string) => void;
   /** Switch to a tab by id. */
   setActiveTab: (tabId: string) => void;
-  /** Update the active tab's metadata. */
-  updateActiveTab: (path: string, title: string, icon: string) => void;
+  /** Update a tab's metadata (path, title, icon — partial). */
+  updateTab: (tabId: string, patch: Partial<Pick<Tab, "path" | "title" | "icon">>) => void;
+  /** Update a tab's history tracking. */
+  updateTabHistory: (tabId: string, historyIndex: number, historyLength: number) => void;
+  /** Reorder tabs by moving one from fromIndex to toIndex. Preserves router/history. */
+  moveTab: (fromIndex: number, toIndex: number) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -35,6 +47,7 @@ const ROUTE_ICONS: Record<string, string> = {
   "/inbox": "Inbox",
   "/my-issues": "CircleUser",
   "/issues": "ListTodo",
+  "/projects": "FolderKanban",
   "/agents": "Bot",
   "/runtimes": "Monitor",
   "/skills": "BookOpenText",
@@ -43,7 +56,10 @@ const ROUTE_ICONS: Record<string, string> = {
 
 /** Resolve a route icon. Title is NOT determined here — it comes from document.title. */
 export function resolveRouteIcon(pathname: string): string {
-  return ROUTE_ICONS[pathname] ?? (pathname.startsWith("/issues/") ? "ListTodo" : "ListTodo");
+  return ROUTE_ICONS[pathname]
+    ?? (pathname.startsWith("/issues/") ? "ListTodo" : undefined)
+    ?? (pathname.startsWith("/projects/") ? "FolderKanban" : undefined)
+    ?? "ListTodo";
 }
 
 // ---------------------------------------------------------------------------
@@ -56,14 +72,23 @@ function createId(): string {
   return crypto.randomUUID();
 }
 
-const initialTab: Tab = {
-  id: createId(),
-  path: DEFAULT_PATH,
-  title: "Issues",
-  icon: resolveRouteIcon(DEFAULT_PATH),
-};
+function makeTab(path: string, title: string, icon: string): Tab {
+  return {
+    id: createId(),
+    path,
+    title,
+    icon,
+    router: createTabRouter(path),
+    historyIndex: 0,
+    historyLength: 1,
+  };
+}
 
-export const useTabStore = create<TabStore>((set, get) => ({
+const initialTab = makeTab(DEFAULT_PATH, "Issues", resolveRouteIcon(DEFAULT_PATH));
+
+export const useTabStore = create<TabStore>()(
+  persist(
+    (set, get) => ({
   tabs: [initialTab],
   activeTabId: initialTab.id,
 
@@ -72,13 +97,13 @@ export const useTabStore = create<TabStore>((set, get) => ({
     const existing = tabs.find((t) => t.path === path);
     if (existing) return existing.id;
 
-    const tab: Tab = { id: createId(), path, title, icon };
+    const tab = makeTab(path, title, icon);
     set({ tabs: [...tabs, tab] });
     return tab.id;
   },
 
   addTab(path, title, icon) {
-    const tab: Tab = { id: createId(), path, title, icon };
+    const tab = makeTab(path, title, icon);
     set((s) => ({ tabs: [...s.tabs, tab] }));
     return tab.id;
   },
@@ -86,38 +111,85 @@ export const useTabStore = create<TabStore>((set, get) => ({
   closeTab(tabId) {
     const { tabs, activeTabId } = get();
 
+    const closingTab = tabs.find((t) => t.id === tabId);
+
     // Never close the last tab — replace with default
     if (tabs.length === 1) {
-      const fresh: Tab = { id: createId(), path: DEFAULT_PATH, title: "Issues", icon: resolveRouteIcon(DEFAULT_PATH) };
+      closingTab?.router.dispose();
+      const fresh = makeTab(DEFAULT_PATH, "Issues", resolveRouteIcon(DEFAULT_PATH));
       set({ tabs: [fresh], activeTabId: fresh.id });
-      return fresh.path;
+      return;
     }
 
     const idx = tabs.findIndex((t) => t.id === tabId);
-    if (idx === -1) return null;
+    if (idx === -1) return;
 
+    closingTab?.router.dispose();
     const next = tabs.filter((t) => t.id !== tabId);
 
     if (tabId === activeTabId) {
       const newActive = next[Math.min(idx, next.length - 1)];
       set({ tabs: next, activeTabId: newActive.id });
-      return newActive.path;
+    } else {
+      set({ tabs: next });
     }
-
-    set({ tabs: next });
-    return null;
   },
 
   setActiveTab(tabId) {
     set({ activeTabId: tabId });
   },
 
-  updateActiveTab(path, title, icon) {
-    const { tabs, activeTabId } = get();
-    set({
-      tabs: tabs.map((t) =>
-        t.id === activeTabId ? { ...t, path, title, icon } : t,
+  updateTab(tabId, patch) {
+    set((s) => ({
+      tabs: s.tabs.map((t) =>
+        t.id === tabId ? { ...t, ...patch } : t,
       ),
-    });
+    }));
   },
-}));
+
+  updateTabHistory(tabId, historyIndex, historyLength) {
+    set((s) => ({
+      tabs: s.tabs.map((t) =>
+        t.id === tabId ? { ...t, historyIndex, historyLength } : t,
+      ),
+    }));
+  },
+
+  moveTab(fromIndex, toIndex) {
+    if (fromIndex === toIndex) return;
+    set((s) => ({ tabs: arrayMove(s.tabs, fromIndex, toIndex) }));
+  },
+    }),
+    {
+      name: "multica_tabs",
+      version: 1,
+      storage: createJSONStorage(() => createPersistStorage(defaultStorage)),
+      partialize: (state) => ({
+        tabs: state.tabs.map(
+          ({ router, historyIndex, historyLength, ...rest }) => rest,
+        ),
+        activeTabId: state.activeTabId,
+      }),
+      merge: (persistedState, currentState) => {
+        const persisted = persistedState as
+          | Pick<TabStore, "tabs" | "activeTabId">
+          | undefined;
+        if (!persisted?.tabs?.length) return currentState;
+
+        const tabs: Tab[] = persisted.tabs.map((tab) => ({
+          ...tab,
+          router: createTabRouter(tab.path),
+          historyIndex: 0,
+          historyLength: 1,
+        }));
+
+        // Validate activeTabId — fall back to first tab if stale
+        const activeTabId = tabs.some((t) => t.id === persisted.activeTabId)
+          ? persisted.activeTabId
+          : tabs[0].id;
+
+        return { ...currentState, tabs, activeTabId };
+      },
+    },
+  ),
+);

apps/docs/.gitignore

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

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

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

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

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

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

@@ -0,0 +1,4 @@
+import { source } from "@/lib/source";
+import { createFromSource } from "fumadocs-core/search/server";
+
+export const { GET } = createFromSource(source);

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

@@ -0,0 +1,47 @@
+import { source } from "@/lib/source";
+import {
+  DocsPage,
+  DocsBody,
+  DocsDescription,
+  DocsTitle,
+} from "fumadocs-ui/page";
+import { notFound } from "next/navigation";
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import type { Metadata } from "next";
+
+export default async function Page(props: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  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 async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: {
+  params: Promise<{ slug?: string[] }>;
+}): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}

apps/docs/app/docs/layout.tsx

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

apps/docs/app/global.css

@@ -0,0 +1,3 @@
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";

apps/docs/app/layout.config.tsx

@@ -0,0 +1,25 @@
+import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
+import { BookOpen, Terminal, Rocket, Code } from "lucide-react";
+
+export const baseOptions: BaseLayoutProps = {
+  nav: {
+    title: (
+      <span className="font-semibold text-base">Multica Docs</span>
+    ),
+  },
+  links: [
+    {
+      text: "Documentation",
+      url: "/docs",
+      active: "nested-url",
+    },
+    {
+      text: "GitHub",
+      url: "https://github.com/multica-ai/multica",
+    },
+    {
+      text: "Cloud",
+      url: "https://multica.ai",
+    },
+  ],
+};

apps/docs/app/layout.tsx

@@ -0,0 +1,23 @@
+import "./global.css";
+import { RootProvider } from "fumadocs-ui/provider";
+import type { ReactNode } from "react";
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: {
+    template: "%s | Multica Docs",
+    default: "Multica Docs",
+  },
+  description:
+    "Documentation for Multica — the open-source managed agents platform.",
+};
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}

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

@@ -0,0 +1,90 @@
+---
+title: CLI Installation
+description: Install the Multica CLI and start the agent daemon.
+---
+
+## Installation
+
+### Homebrew (macOS/Linux)
+
+```bash
+brew tap multica-ai/tap
+brew install multica
+```
+
+### Build from Source
+
+```bash
+git clone https://github.com/multica-ai/multica.git
+cd multica
+make build
+cp server/bin/multica /usr/local/bin/multica
+```
+
+### Download from GitHub Releases
+
+If Homebrew is not available, download the binary directly:
+
+```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
+curl -sL "https://github.com/multica-ai/multica/releases/download/${LATEST}/multica_${OS}_${ARCH}.tar.gz" \
+  -o /tmp/multica.tar.gz
+tar -xzf /tmp/multica.tar.gz -C /tmp multica
+sudo mv /tmp/multica /usr/local/bin/multica
+rm /tmp/multica.tar.gz
+```
+
+### Update
+
+```bash
+multica update
+```
+
+This auto-detects your installation method (Homebrew or manual) and upgrades accordingly.
+
+## Quick Start
+
+```bash
+# 1. Authenticate (opens browser for login)
+multica login
+
+# 2. Start the agent daemon
+multica daemon start
+
+# 3. Done — agents in your watched workspaces can now execute tasks on your machine
+```
+
+`multica login` automatically discovers all workspaces you belong to and adds them to the daemon watch list.
+
+## Verify
+
+```bash
+multica daemon status
+```
+
+Confirm:
+1. Status is `running`
+2. At least one agent is listed (e.g. `claude`, `codex`)
+3. At least one workspace is being watched
+
+If the agents list is empty, install at least one AI agent CLI:
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`)
+- [Codex](https://github.com/openai/codex) (`codex`)
+
+Then restart the daemon:
+
+```bash
+multica daemon stop && multica daemon start
+```

apps/docs/content/docs/cli/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "CLI & Daemon",
+  "pages": ["installation", "reference"]
+}

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

@@ -0,0 +1,306 @@
+---
+title: CLI Reference
+description: Complete command reference for the Multica CLI and agent daemon.
+---
+
+The `multica` CLI connects your local machine to Multica. It handles authentication, workspace management, issue tracking, and runs the agent daemon that executes AI tasks locally.
+
+## Authentication
+
+### Browser Login
+
+```bash
+multica login
+```
+
+Opens your browser for OAuth authentication, creates a 90-day personal access token, and auto-configures your workspaces.
+
+### Token Login
+
+```bash
+multica login --token
+```
+
+Authenticate by pasting a personal access token directly. Useful for headless environments.
+
+### Check Status
+
+```bash
+multica auth status
+```
+
+Shows your current server, user, and token validity.
+
+### Logout
+
+```bash
+multica auth logout
+```
+
+Removes the stored authentication token.
+
+## Agent Daemon
+
+The daemon is the local agent runtime. It detects available AI CLIs on your machine, registers them with the Multica server, and executes tasks when agents are assigned work.
+
+### Start
+
+```bash
+multica daemon start
+```
+
+By default, the daemon runs in the background and logs to `~/.multica/daemon.log`.
+
+To run in the foreground (useful for debugging):
+
+```bash
+multica daemon start --foreground
+```
+
+### Stop
+
+```bash
+multica daemon stop
+```
+
+### Status
+
+```bash
+multica daemon status
+multica daemon status --output json
+```
+
+Shows PID, uptime, detected agents, and watched workspaces.
+
+### Logs
+
+```bash
+multica daemon logs              # Last 50 lines
+multica daemon logs -f           # Follow (tail -f)
+multica daemon logs -n 100       # Last 100 lines
+```
+
+### Supported Agents
+
+The daemon auto-detects these AI CLIs on your PATH:
+
+| CLI | Command | Description |
+|-----|---------|-------------|
+| [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 |
+
+You need at least one installed. The daemon registers each detected CLI as an available runtime.
+
+### How It Works
+
+1. On start, the daemon detects installed agent CLIs and registers a runtime for each agent in each watched workspace
+2. It polls the server at a configurable interval (default: 3s) for claimed tasks
+3. When a task arrives, it creates an isolated workspace directory, spawns the agent CLI, and streams results back
+4. Heartbeats are sent periodically (default: 15s) so the server knows the daemon is alive
+5. On shutdown, all runtimes are deregistered
+
+### Configuration
+
+Daemon behavior is configured via flags or environment variables:
+
+| Setting | Flag | Env Variable | Default |
+|---------|------|--------------|---------|
+| Poll interval | `--poll-interval` | `MULTICA_DAEMON_POLL_INTERVAL` | `3s` |
+| Heartbeat interval | `--heartbeat-interval` | `MULTICA_DAEMON_HEARTBEAT_INTERVAL` | `15s` |
+| Agent timeout | `--agent-timeout` | `MULTICA_AGENT_TIMEOUT` | `2h` |
+| Max concurrent tasks | `--max-concurrent-tasks` | `MULTICA_DAEMON_MAX_CONCURRENT_TASKS` | `20` |
+| Daemon ID | `--daemon-id` | `MULTICA_DAEMON_ID` | hostname |
+| Device name | `--device-name` | `MULTICA_DAEMON_DEVICE_NAME` | hostname |
+| Runtime name | `--runtime-name` | `MULTICA_AGENT_RUNTIME_NAME` | `Local Agent` |
+| Workspaces root | — | `MULTICA_WORKSPACES_ROOT` | `~/multica_workspaces` |
+
+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 |
+
+### Self-Hosted Server
+
+When connecting to a self-hosted Multica instance, point the CLI to your server before logging in:
+
+```bash
+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
+# Start a daemon for the staging server
+multica --profile staging login
+multica --profile staging daemon start
+
+# Default profile runs separately
+multica daemon start
+```
+
+Each profile gets its own config directory (`~/.multica/profiles/<name>/`), daemon state, health port, and workspace root.
+
+## Workspaces
+
+### List Workspaces
+
+```bash
+multica workspace list
+```
+
+Watched workspaces are marked with `*`. The daemon only processes tasks for watched workspaces.
+
+### Watch / Unwatch
+
+```bash
+multica workspace watch <workspace-id>
+multica workspace unwatch <workspace-id>
+```
+
+### Get Details
+
+```bash
+multica workspace get <workspace-id>
+multica workspace get <workspace-id> --output json
+```
+
+### List Members
+
+```bash
+multica workspace members <workspace-id>
+```
+
+## Issues
+
+### List Issues
+
+```bash
+multica issue list
+multica issue list --status in_progress
+multica issue list --priority urgent --assignee "Agent Name"
+multica issue list --limit 20 --output json
+```
+
+Available filters: `--status`, `--priority`, `--assignee`, `--limit`.
+
+### Get Issue
+
+```bash
+multica issue get <id>
+multica issue get <id> --output json
+```
+
+### Create Issue
+
+```bash
+multica issue create --title "Fix login bug" --description "..." --priority high --assignee "Lambda"
+```
+
+Flags: `--title` (required), `--description`, `--status`, `--priority`, `--assignee`, `--parent`, `--due-date`.
+
+### Update Issue
+
+```bash
+multica issue update <id> --title "New title" --priority urgent
+```
+
+### Assign Issue
+
+```bash
+multica issue assign <id> --to "Lambda"
+multica issue assign <id> --unassign
+```
+
+### Change Status
+
+```bash
+multica issue status <id> in_progress
+```
+
+Valid statuses: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled`.
+
+### Comments
+
+```bash
+# List comments
+multica issue comment list <issue-id>
+
+# Add a comment
+multica issue comment add <issue-id> --content "Looks good, merging now"
+
+# Reply to a specific comment
+multica issue comment add <issue-id> --parent <comment-id> --content "Thanks!"
+
+# Delete a comment
+multica issue comment delete <comment-id>
+```
+
+### Execution History
+
+```bash
+# List all execution runs for an issue
+multica issue runs <issue-id>
+multica issue runs <issue-id> --output json
+
+# View messages for a specific execution run
+multica issue run-messages <task-id>
+multica issue run-messages <task-id> --output json
+
+# Incremental fetch (only messages after a given sequence number)
+multica issue run-messages <task-id> --since 42 --output json
+```
+
+## Configuration
+
+### View Config
+
+```bash
+multica config show
+```
+
+Shows config file path, server URL, app URL, and default workspace.
+
+### Set Values
+
+```bash
+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>
+```
+
+## Other Commands
+
+```bash
+multica version              # Show CLI version and commit hash
+multica update               # Update to latest version
+multica agent list           # List agents in the current workspace
+```
+
+## Output Formats
+
+Most commands support `--output` with two formats:
+
+- `table` — human-readable table (default for list commands)
+- `json` — structured JSON (useful for scripting and automation)
+
+```bash
+multica issue list --output json
+multica daemon status --output json
+```

apps/docs/content/docs/developers/architecture.mdx

@@ -0,0 +1,75 @@
+---
+title: Architecture
+description: Technical architecture of the Multica platform.
+---
+
+## Overview
+
+Multica is a Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
+│   Next.js    │────>│  Go Backend  │────>│   PostgreSQL     │
+│   Frontend   │<────│  (Chi + WS)  │<────│   (pgvector)     │
+└──────────────┘     └──────┬───────┘     └──────────────────┘
+                            │
+                     ┌──────┴───────┐
+                     │ Agent Daemon │  (runs on your machine)
+                     │Claude/Codex/ │
+                     │OpenClaw/Code │
+                     └──────────────┘
+```
+
+## Project Structure
+
+| Directory | Purpose | Technology |
+|-----------|---------|------------|
+| `server/` | Go backend | Chi router, sqlc for DB, gorilla/websocket |
+| `apps/web/` | Next.js frontend | App Router |
+| `apps/desktop/` | Electron desktop app | electron-vite |
+| `apps/docs/` | Documentation site | Fumadocs |
+| `packages/core/` | Headless business logic | Zero react-dom, all-platform reuse |
+| `packages/ui/` | Atomic UI components | Zero business logic, shadcn-based |
+| `packages/views/` | Shared business pages | Zero next/\*, zero react-router imports |
+| `packages/tsconfig/` | Shared TypeScript config | — |
+| `packages/eslint-config/` | Shared ESLint config | — |
+
+## Backend Structure
+
+- **Entry points** (`cmd/`): `server` (HTTP API), `multica` (CLI + daemon), `migrate`
+- **Handlers** (`internal/handler/`): One file per domain (issue, comment, agent, auth, daemon)
+- **Real-time** (`internal/realtime/`): Hub manages WebSocket clients, server broadcasts events
+- **Auth** (`internal/auth/` + `internal/middleware/`): JWT (HS256), middleware sets `X-User-ID` and `X-User-Email` headers
+- **Task lifecycle** (`internal/service/task.go`): enqueue → claim → start → complete/fail
+- **Agent SDK** (`pkg/agent/`): Unified `Backend` interface for executing prompts via Claude Code or Codex
+- **Daemon** (`internal/daemon/`): Auto-detects CLIs, registers runtimes, polls for tasks
+- **Database**: PostgreSQL 17 with pgvector, sqlc generates code from SQL in `pkg/db/queries/`
+
+## Frontend Architecture
+
+### 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.
+
+### Package Boundaries
+
+- `packages/core/` — zero react-dom, zero localStorage, zero UI libs. All Zustand stores live here.
+- `packages/ui/` — pure UI components, zero business logic.
+- `packages/views/` — zero `next/*`, zero `react-router-dom`. Uses `NavigationAdapter` for routing.
+
+### State Management
+
+- **TanStack Query** owns all server state (issues, users, workspaces)
+- **Zustand** owns all client state (UI selections, filters, drafts)
+- **React Context** reserved for cross-cutting plumbing (`WorkspaceIdProvider`, `NavigationProvider`)
+
+### Data Flow
+
+```
+Browser → ApiClient (shared/api) → REST API (Chi handlers) → sqlc queries → PostgreSQL
+Browser ← WSClient (shared/api) ← WebSocket ← Hub.Broadcast() ← Handlers/TaskService
+```
+
+## Multi-tenancy
+
+All queries filter by `workspace_id`. Membership checks gate access. `X-Workspace-ID` header routes requests to the correct workspace.

apps/docs/content/docs/developers/contributing.mdx

@@ -0,0 +1,178 @@
+---
+title: Contributing
+description: Local development workflow for contributors working on the Multica codebase.
+---
+
+## Development Model
+
+Local development uses one shared PostgreSQL container and one database per checkout.
+
+- The main checkout usually uses `.env` and `POSTGRES_DB=multica`
+- Each Git worktree uses its own `.env.worktree`
+- Every checkout connects to the same PostgreSQL host: `localhost:5432`
+- Isolation happens at the database level, not by starting a separate Docker Compose project
+- Backend and frontend ports are still unique per worktree
+
+## Prerequisites
+
+- Node.js `v20+`
+- `pnpm` `v10.28+`
+- Go `v1.26+`
+- Docker
+
+## First-Time Setup
+
+### 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
+```
+
+### Worktree
+
+From the worktree directory:
+
+```bash
+make worktree-env
+make setup-worktree
+```
+
+Start the worktree app:
+
+```bash
+make start-worktree
+```
+
+## Daily Workflow
+
+### Main Checkout
+
+```bash
+make start-main
+make stop-main
+make check-main
+```
+
+### Feature Worktree
+
+```bash
+git worktree add ../multica-feature -b feat/my-change main
+cd ../multica-feature
+make worktree-env
+make setup-worktree
+make start-worktree
+```
+
+Day-to-day:
+
+```bash
+make start-worktree
+make stop-worktree
+make check-worktree
+```
+
+## Running Main and Worktree Simultaneously
+
+This is a first-class workflow. Both checkouts use the same PostgreSQL container but different databases and ports:
+
+| | Main | Worktree |
+|---|---|---|
+| Database | `multica` | `multica_my_feature_702` |
+| Backend port | `8080` | generated (e.g. `18782`) |
+| Frontend port | `3000` | generated (e.g. `13702`) |
+
+## Commands
+
+```bash
+# Frontend (all commands go through Turborepo)
+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
+pnpm lint             # ESLint
+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
+make test             # Go tests
+make sqlc             # Regenerate sqlc code
+make migrate-up       # Run database migrations
+make migrate-down     # Rollback migrations
+```
+
+## Testing
+
+Run all local checks:
+
+```bash
+make check
+```
+
+This runs:
+
+1. TypeScript typecheck
+2. TypeScript unit tests
+3. Go tests
+4. Playwright E2E tests
+
+## Troubleshooting
+
+### Missing Env File
+
+Create the expected env file:
+
+```bash
+# Main checkout
+cp .env.example .env
+
+# Worktree
+make worktree-env
+```
+
+### Check Which Database a Checkout Uses
+
+```bash
+cat .env           # or .env.worktree
+```
+
+Look for `POSTGRES_DB`, `DATABASE_URL`, `PORT`, `FRONTEND_PORT`.
+
+### List All Local Databases
+
+```bash
+docker compose exec -T postgres psql -U multica -d postgres \
+  -At -c "select datname from pg_database order by datname;"
+```
+
+### Destructive Reset
+
+Stop PostgreSQL and keep local databases:
+
+```bash
+make db-down
+```
+
+Wipe all local PostgreSQL data:
+
+```bash
+docker compose down -v
+```
+
+> **Warning:** This deletes the shared Docker volume and all databases. After that you must run `make setup-main` or `make setup-worktree` again.

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

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

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

@@ -0,0 +1,48 @@
+---
+title: Cloud Quickstart
+description: Get started with Multica Cloud — no setup required.
+---
+
+The fastest way to get started with Multica — no setup required.
+
+## 1. Sign up
+
+Go to [multica.ai](https://multica.ai) and create an account.
+
+## 2. Install the CLI and start the daemon
+
+Give this instruction to your AI agent (Claude Code, Codex, OpenClaw, OpenCode, etc.):
+
+```
+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.
+```
+
+Or install manually:
+
+```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`, `openclaw`, `opencode`) on your PATH. When an agent is assigned a task, the daemon creates an isolated environment, runs the agent, and reports results back.
+
+## 3. Verify your runtime
+
+Open your workspace in the Multica web app. Navigate to **Settings → Runtimes** — you should see your machine listed as an active **Runtime**.
+
+> **What is a Runtime?** A Runtime is a compute environment that can execute agent tasks. It can be your local machine (via the daemon) or a cloud instance. Each runtime reports which agent CLIs are available, so Multica knows where to route work.
+
+## 4. 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, or OpenCode). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
+
+## 5. 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.
+
+That's it! Your agent is now part of the team.

apps/docs/content/docs/getting-started/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Getting Started",
+  "pages": ["cloud-quickstart", "self-hosting"]
+}

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

@@ -0,0 +1,370 @@
+---
+title: Self-Hosting Guide
+description: Deploy Multica on your own infrastructure.
+---
+
+## Architecture Overview
+
+Multica has three components:
+
+| Component | Description | Technology |
+|-----------|-------------|------------|
+| **Backend** | REST API + WebSocket server | Go (single binary) |
+| **Frontend** | Web application | Next.js 16 |
+| **Database** | Primary data store | PostgreSQL 17 with pgvector |
+
+Each user who wants to run AI agents locally also installs the **`multica` CLI** and runs the **agent daemon** on their own machine.
+
+## Prerequisites
+
+- Docker and Docker Compose
+
+## Quick Install
+
+One command to set up everything:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --local
+```
+
+This clones the repo, starts all services, installs the CLI, and configures everything. Then:
+
+1. Open http://localhost:3000 — log in with any email + code **`888888`**
+2. Run `multica login` and `multica daemon start`
+
+<Callout>
+For a step-by-step setup, see below.
+</Callout>
+
+## Step-by-Step Setup
+
+### Step 1 — Start the Server
+
+```bash
+git clone https://github.com/multica-ai/multica.git
+cd multica
+make selfhost
+```
+
+`make selfhost` automatically creates `.env`, generates a random `JWT_SECRET`, and starts all services via Docker Compose.
+
+Once ready:
+
+- **Frontend:** http://localhost:3000
+- **Backend API:** http://localhost:8080
+
+<Callout>
+If you prefer running the Docker Compose steps manually: `cp .env.example .env`, edit `JWT_SECRET`, then `docker compose -f docker-compose.selfhost.yml up -d`.
+</Callout>
+
+### Step 2 — Log In
+
+Open http://localhost:3000. Enter any email address and use verification code **`888888`** to log in.
+
+<Callout>
+This master code works in all non-production environments (when `APP_ENV` is not set to `production`). For production, configure an email provider — see [Configuration](#configuration) below.
+</Callout>
+
+### Step 3 — Install CLI & Start Daemon
+
+The daemon runs on your local machine (not inside Docker). It detects installed AI agent CLIs, registers them with the server, and executes tasks.
+
+### a) Install the CLI and an AI agent
+
+```bash
+brew install multica-ai/tap/multica
+```
+
+You also need at least one AI agent CLI:
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
+- [Codex](https://github.com/openai/codex) (`codex` on PATH)
+
+### b) One-command setup
+
+```bash
+multica setup --local
+```
+
+This automatically:
+1. Configures the CLI to connect to `localhost`
+2. Opens your browser for authentication
+3. Discovers your workspaces
+4. Starts the daemon in the background
+
+Verify the daemon is running:
+
+```bash
+multica daemon status
+```
+
+<Callout>
+Alternatively, configure manually: `multica config local && multica login && multica daemon start`
+</Callout>
+
+### Step 4 — Verify & Start Using
+
+1. Open your workspace 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
+
+## Stopping Services
+
+```bash
+# Stop Docker Compose services
+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 config set server_url https://api.multica.ai
+multica config set app_url https://multica.ai
+multica login
+```
+
+Or re-run the install script without `--local` — it will reconfigure the CLI automatically:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
+```
+
+<Callout>
+Your local Docker services are unaffected. Stop them separately if you no longer need them.
+</Callout>
+
+## Rebuilding After Updates
+
+```bash
+git pull
+make selfhost
+```
+
+Migrations run automatically on backend startup.
+
+---
+
+## 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` |
+
+### 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
+docker compose up -d postgres
+```
+
+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
+# 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
+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.
+
+## 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.

apps/docs/content/docs/guides/agents.mdx

@@ -0,0 +1,50 @@
+---
+title: Agents
+description: How AI agents work in Multica — execution model, skills, and runtime guidelines.
+---
+
+## Agents as Teammates
+
+In Multica, agents are first-class citizens. They have profiles, show up on the board, post comments, create issues, and report blockers proactively.
+
+Assignees are polymorphic — an issue can be assigned to a member or an agent. The `assignee_type` + `assignee_id` fields on issues distinguish between the two. Agents render with distinct styling (purple background, robot icon).
+
+## Agent Execution Model
+
+When an agent is assigned a task in Multica:
+
+1. The daemon detects the task assignment
+2. It creates an isolated workspace directory
+3. It spawns the appropriate agent CLI (Claude Code, Codex, OpenClaw, or OpenCode)
+4. The agent executes autonomously, streaming progress back to Multica
+5. Results are reported — success, failure, or blockers
+
+The full task lifecycle is: **enqueue → claim → start → complete/fail**.
+
+Real-time progress is streamed via WebSocket so you can follow along in the Multica UI.
+
+## Supported Agent Providers
+
+| Provider | CLI Command | Description |
+|----------|-------------|-------------|
+| Claude Code | `claude` | Anthropic's coding agent |
+| Codex | `codex` | OpenAI's coding agent |
+| OpenClaw | `openclaw` | Open-source coding agent |
+| OpenCode | `opencode` | Open-source coding agent |
+
+The daemon auto-detects which CLIs are available on your PATH and registers them as available runtimes.
+
+## Reusable Skills
+
+Every solution an agent creates can become a reusable skill for the whole team. Skills compound your team's capabilities over time:
+
+- Deployments
+- Migrations
+- Code reviews
+- Common patterns
+
+Skills are shared across the workspace, so any agent (or human) can leverage them.
+
+## Multi-Workspace Support
+
+Each workspace has its own set of agents, issues, and settings. The daemon can watch multiple workspaces simultaneously, routing tasks to the appropriate agent based on workspace configuration.

apps/docs/content/docs/guides/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Guides",
+  "pages": ["quickstart", "agents"]
+}

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

@@ -0,0 +1,31 @@
+---
+title: Quickstart
+description: Assign your first task to an agent in under 5 minutes.
+---
+
+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`, `openclaw`, `opencode`) available on your PATH.
+
+## 2. Verify your runtime
+
+Open your workspace in the Multica web app. Navigate to **Settings → Runtimes** — you should see your machine listed as an active **Runtime**.
+
+> **What is a Runtime?** A Runtime is a compute environment that can execute agent tasks. It can be your local machine (via the daemon) or a cloud instance. Each runtime reports which agent CLIs are available, so Multica knows where to route work.
+
+## 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, or OpenCode). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
+
+## 4. Assign your first task
+
+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.
+
+That's it! Your agent is now part of the team.

apps/docs/content/docs/index.mdx

@@ -0,0 +1,47 @@
+---
+title: Introduction
+description: Multica — the open-source managed agents platform. Turn coding agents into real teammates.
+---
+
+## What is Multica?
+
+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**, and **OpenCode**.
+
+## Features
+
+- **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.
+
+## Architecture
+
+| Layer | Stack |
+|-------|-------|
+| 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, or OpenCode |
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
+│   Next.js    │────>│  Go Backend  │────>│   PostgreSQL     │
+│   Frontend   │<────│  (Chi + WS)  │<────│   (pgvector)     │
+└──────────────┘     └──────┬───────┘     └──────────────────┘
+                            │
+                     ┌──────┴───────┐
+                     │ Agent Daemon │  (runs on your machine)
+                     │Claude/Codex/ │
+                     │OpenClaw/Code │
+                     └──────────────┘
+```
+
+## Next Steps
+
+- [Cloud Quickstart](/docs/getting-started/cloud-quickstart)
+- [Self-Hosting](/docs/getting-started/self-hosting)
+- [CLI Installation](/docs/cli/installation)
+- [Contributing](/docs/developers/contributing)

apps/docs/content/docs/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Documentation",
+  "pages": [
+    "index",
+    "getting-started",
+    "cli",
+    "guides",
+    "developers"
+  ]
+}

apps/docs/lib/source.ts

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

apps/docs/next-env.d.ts

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

apps/docs/next.config.mjs

@@ -0,0 +1,10 @@
+import { createMDX } from "fumadocs-mdx/next";
+
+const withMDX = createMDX();
+
+/** @type {import('next').NextConfig} */
+const config = {
+  reactStrictMode: true,
+};
+
+export default withMDX(config);

apps/docs/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@multica/docs",
+  "version": "0.2.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev --port 4000",
+    "build": "fumadocs-mdx && next build",
+    "start": "next start",
+    "typecheck": "fumadocs-mdx && tsc --noEmit",
+    "postinstall": "fumadocs-mdx"
+  },
+  "dependencies": {
+    "fumadocs-core": "^15.5.2",
+    "fumadocs-mdx": "^12.0.3",
+    "fumadocs-ui": "^15.5.2",
+    "lucide-react": "catalog:",
+    "next": "^15.3.3",
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "tailwindcss": "catalog:",
+    "typescript": "catalog:"
+  }
+}

apps/docs/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

apps/docs/source.config.ts

@@ -0,0 +1,9 @@
+import { defineDocs, defineConfig } from "fumadocs-mdx/config";
+
+export const docs = defineDocs({
+  dir: "content/docs",
+});
+
+export default defineConfig({
+  mdxOptions: {},
+});

apps/docs/tsconfig.json

@@ -0,0 +1,48 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": [
+      "ESNext",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": true,
+    "noUncheckedIndexedAccess": true,
+    "resolveJsonModule": true,
+    "jsx": "preserve",
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    },
+    "noEmit": true,
+    "allowJs": true,
+    "incremental": true
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    ".source/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

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

@@ -2,37 +2,51 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
+const { mockSendCode, mockVerifyCode, mockHydrateWorkspace } = vi.hoisted(
+  () => ({
+    mockSendCode: vi.fn(),
+    mockVerifyCode: vi.fn(),
+    mockHydrateWorkspace: vi.fn(),
+  }),
+);
+
 // Mock next/navigation
 vi.mock("next/navigation", () => ({
-  useRouter: () => ({ push: vi.fn() }),
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn() }),
   usePathname: () => "/login",
   useSearchParams: () => new URLSearchParams(),
 }));
 
-// Mock auth store
-const mockSendCode = vi.fn();
-const mockVerifyCode = vi.fn();
-vi.mock("@multica/core/auth", () => ({
-  useAuthStore: (selector: (s: any) => any) =>
-    selector({
-      sendCode: mockSendCode,
-      verifyCode: mockVerifyCode,
-    }),
-}));
+// Mock auth store — shared LoginPage uses getState().sendCode/verifyCode,
+// web wrapper uses useAuthStore((s) => s.user/isLoading)
+vi.mock("@multica/core/auth", () => {
+  const authState = {
+    sendCode: mockSendCode,
+    verifyCode: mockVerifyCode,
+    user: null,
+    isLoading: false,
+  };
+  const useAuthStore = Object.assign(
+    (selector: (s: typeof authState) => unknown) => selector(authState),
+    { getState: () => authState },
+  );
+  return { useAuthStore };
+});
 
 // Mock auth-cookie
 vi.mock("@/features/auth/auth-cookie", () => ({
   setLoggedInCookie: vi.fn(),
 }));
 
-// Mock workspace store
-const mockHydrateWorkspace = vi.fn();
-vi.mock("@multica/core/workspace", () => ({
-  useWorkspaceStore: (selector: (s: any) => any) =>
-    selector({
-      hydrateWorkspace: mockHydrateWorkspace,
-    }),
-}));
+// Mock workspace store — shared LoginPage uses getState().hydrateWorkspace
+vi.mock("@multica/core/workspace", () => {
+  const wsState = { hydrateWorkspace: mockHydrateWorkspace };
+  const useWorkspaceStore = Object.assign(
+    (selector: (s: typeof wsState) => unknown) => selector(wsState),
+    { getState: () => wsState },
+  );
+  return { useWorkspaceStore };
+});
 
 // Mock api
 vi.mock("@multica/core/api", () => ({
@@ -54,8 +68,8 @@ describe("LoginPage", () => {
   it("renders login form with email input and continue button", () => {
     render(<LoginPage />);
 
-    expect(screen.getByText("Multica")).toBeInTheDocument();
-    expect(screen.getByText("Turn coding agents into real teammates")).toBeInTheDocument();
+    expect(screen.getByText("Sign in to Multica")).toBeInTheDocument();
+    expect(screen.getByText("Enter your email to get a login code")).toBeInTheDocument();
     expect(screen.getByLabelText("Email")).toBeInTheDocument();
     expect(
       screen.getByRole("button", { name: "Continue" })

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

@@ -1,390 +1,58 @@
 "use client";
 
-import { Suspense, useState, useEffect, useCallback } from "react";
+import { Suspense, useEffect } from "react";
 import { useSearchParams, useRouter } from "next/navigation";
 import { useAuthStore } from "@multica/core/auth";
 import { setLoggedInCookie } from "@/features/auth/auth-cookie";
-import { useWorkspaceStore } from "@multica/core/workspace";
-import { api } from "@multica/core/api";
-import {
-  Card,
-  CardHeader,
-  CardTitle,
-  CardDescription,
-  CardContent,
-  CardFooter,
-} from "@multica/ui/components/ui/card";
-import { Input } from "@multica/ui/components/ui/input";
-import { Button } from "@multica/ui/components/ui/button";
-import { Label } from "@multica/ui/components/ui/label";
-import {
-  InputOTP,
-  InputOTPGroup,
-  InputOTPSlot,
-} from "@multica/ui/components/ui/input-otp";
-import type { User } from "@multica/core/types";
+import { LoginPage, validateCliCallback } from "@multica/views/auth";
 
-function validateCliCallback(cliCallback: string): boolean {
-  try {
-    const cbUrl = new URL(cliCallback);
-    if (cbUrl.protocol !== "http:") return false;
-    if (cbUrl.hostname !== "localhost" && cbUrl.hostname !== "127.0.0.1")
-      return false;
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function redirectToCliCallback(
-  cliCallback: string,
-  token: string,
-  cliState: string
-) {
-  const separator = cliCallback.includes("?") ? "&" : "?";
-  window.location.href = `${cliCallback}${separator}token=${encodeURIComponent(token)}&state=${encodeURIComponent(cliState)}`;
-}
+const googleClientId = process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID;
 
 function LoginPageContent() {
   const router = useRouter();
   const user = useAuthStore((s) => s.user);
   const isLoading = useAuthStore((s) => s.isLoading);
-  const sendCode = useAuthStore((s) => s.sendCode);
-  const verifyCode = useAuthStore((s) => s.verifyCode);
-  const hydrateWorkspace = useWorkspaceStore((s) => s.hydrateWorkspace);
   const searchParams = useSearchParams();
 
-  // Already authenticated — redirect to dashboard
+  const cliCallbackRaw = searchParams.get("cli_callback");
+  const cliState = searchParams.get("cli_state") || "";
+  const nextUrl = searchParams.get("next") || "/issues";
+
+  // Already authenticated — redirect to dashboard (skip if CLI callback)
   useEffect(() => {
-    if (!isLoading && user && !searchParams.get("cli_callback")) {
-      router.replace(searchParams.get("next") || "/issues");
+    if (!isLoading && user && !cliCallbackRaw) {
+      router.replace(nextUrl);
     }
-  }, [isLoading, user, router, searchParams]);
+  }, [isLoading, user, router, nextUrl, cliCallbackRaw]);
 
-  const [step, setStep] = useState<"email" | "code" | "cli_confirm">("email");
-  const [email, setEmail] = useState("");
-  const [code, setCode] = useState("");
-  const [error, setError] = useState("");
-  const [submitting, setSubmitting] = useState(false);
-  const [cooldown, setCooldown] = useState(0);
-  const [existingUser, setExistingUser] = useState<User | null>(null);
-
-  // Check for existing session when CLI callback is present.
-  useEffect(() => {
-    const cliCallback = searchParams.get("cli_callback");
-    if (!cliCallback) return;
-
-    const token = localStorage.getItem("multica_token");
-    if (!token) return;
-
-    if (!validateCliCallback(cliCallback)) return;
-
-    // Verify the existing token is still valid.
-    api.setToken(token);
-    api
-      .getMe()
-      .then((user) => {
-        setExistingUser(user);
-        setStep("cli_confirm");
-      })
-      .catch(() => {
-        // Token expired/invalid — clear and fall through to normal login.
-        api.setToken(null);
-        localStorage.removeItem("multica_token");
-      });
-  }, [searchParams]);
-
-  useEffect(() => {
-    if (cooldown <= 0) return;
-    const timer = setTimeout(() => setCooldown((c) => c - 1), 1000);
-    return () => clearTimeout(timer);
-  }, [cooldown]);
-
-  const handleCliAuthorize = async () => {
-    const cliCallback = searchParams.get("cli_callback");
-    const token = localStorage.getItem("multica_token");
-    if (!cliCallback || !token) return;
-    const cliState = searchParams.get("cli_state") || "";
-    setSubmitting(true);
-    redirectToCliCallback(cliCallback, token, cliState);
-  };
-
-  const handleSendCode = async (e?: React.FormEvent) => {
-    e?.preventDefault();
-    if (!email) {
-      setError("Email is required");
-      return;
-    }
-    setError("");
-    setSubmitting(true);
-    try {
-      await sendCode(email);
-      setStep("code");
-      setCode("");
-      setCooldown(10);
-    } catch (err) {
-      setError(
-        err instanceof Error
-          ? err.message
-          : "Failed to send code. Make sure the server is running."
-      );
-    } finally {
-      setSubmitting(false);
-    }
-  };
-
-  const handleVerifyCode = useCallback(
-    async (value: string) => {
-      if (value.length !== 6) return;
-      setError("");
-      setSubmitting(true);
-      try {
-        const cliCallback = searchParams.get("cli_callback");
-        if (cliCallback) {
-          if (!validateCliCallback(cliCallback)) {
-            setError("Invalid callback URL");
-            setSubmitting(false);
-            return;
-          }
-          const { token } = await api.verifyCode(email, value);
-          // Persist session in the browser so the web app stays logged in
-          localStorage.setItem("multica_token", token);
-          api.setToken(token);
-          setLoggedInCookie();
-          const cliState = searchParams.get("cli_state") || "";
-          redirectToCliCallback(cliCallback, token, cliState);
-          return;
-        }
-
-        await verifyCode(email, value);
-        const wsList = await api.listWorkspaces();
-        const lastWsId = localStorage.getItem("multica_workspace_id");
-        await hydrateWorkspace(wsList, lastWsId);
-        router.push(searchParams.get("next") || "/issues");
-      } catch (err) {
-        setError(
-          err instanceof Error ? err.message : "Invalid or expired code"
-        );
-        setCode("");
-        setSubmitting(false);
-      }
-    },
-    [email, verifyCode, hydrateWorkspace, router, searchParams]
-  );
-
-  const handleResend = async () => {
-    if (cooldown > 0) return;
-    setError("");
-    try {
-      await sendCode(email);
-      setCooldown(10);
-    } catch (err) {
-      setError(
-        err instanceof Error ? err.message : "Failed to resend code"
-      );
-    }
-  };
-
-  // CLI confirm step: user is already logged in, just authorize.
-  if (step === "cli_confirm" && existingUser) {
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <Card className="w-full max-w-sm">
-          <CardHeader className="text-center">
-            <CardTitle className="text-2xl">Authorize CLI</CardTitle>
-            <CardDescription>
-              Allow the CLI to access Multica as{" "}
-              <span className="font-medium text-foreground">
-                {existingUser.email}
-              </span>
-              ?
-            </CardDescription>
-          </CardHeader>
-          <CardContent className="flex flex-col gap-3">
-            <Button
-              onClick={handleCliAuthorize}
-              disabled={submitting}
-              className="w-full"
-              size="lg"
-            >
-              {submitting ? "Authorizing..." : "Authorize"}
-            </Button>
-            <Button
-              variant="ghost"
-              className="w-full"
-              onClick={() => {
-                setExistingUser(null);
-                setStep("email");
-              }}
-            >
-              Use a different account
-            </Button>
-          </CardContent>
-        </Card>
-      </div>
-    );
-  }
-
-  if (step === "code") {
-    return (
-      <div className="flex min-h-screen items-center justify-center">
-        <Card className="w-full max-w-sm">
-          <CardHeader className="text-center">
-            <CardTitle className="text-2xl">Check your email</CardTitle>
-            <CardDescription>
-              We sent a verification code to{" "}
-              <span className="font-medium text-foreground">{email}</span>
-            </CardDescription>
-          </CardHeader>
-          <CardContent className="flex flex-col items-center gap-4">
-            <InputOTP
-              maxLength={6}
-              value={code}
-              onChange={(value) => {
-                setCode(value);
-                if (value.length === 6) handleVerifyCode(value);
-              }}
-              disabled={submitting}
-            >
-              <InputOTPGroup>
-                <InputOTPSlot index={0} />
-                <InputOTPSlot index={1} />
-                <InputOTPSlot index={2} />
-                <InputOTPSlot index={3} />
-                <InputOTPSlot index={4} />
-                <InputOTPSlot index={5} />
-              </InputOTPGroup>
-            </InputOTP>
-            {error && (
-              <p className="text-sm text-destructive">{error}</p>
-            )}
-            <div className="flex items-center gap-2 text-sm text-muted-foreground">
-              <button
-                type="button"
-                onClick={handleResend}
-                disabled={cooldown > 0}
-                className="text-primary underline-offset-4 hover:underline disabled:text-muted-foreground disabled:no-underline disabled:cursor-not-allowed"
-              >
-                {cooldown > 0 ? `Resend in ${cooldown}s` : "Resend code"}
-              </button>
-            </div>
-          </CardContent>
-          <CardFooter>
-            <Button
-              variant="ghost"
-              className="w-full"
-              onClick={() => {
-                setStep("email");
-                setCode("");
-                setError("");
-              }}
-            >
-              Back
-            </Button>
-          </CardFooter>
-        </Card>
-      </div>
-    );
-  }
-
-  const googleClientId = process.env.NEXT_PUBLIC_GOOGLE_CLIENT_ID;
-
-  const handleGoogleLogin = () => {
-    if (!googleClientId) return;
-    const redirectUri = `${window.location.origin}/auth/callback`;
-    const params = new URLSearchParams({
-      client_id: googleClientId,
-      redirect_uri: redirectUri,
-      response_type: "code",
-      scope: "openid email profile",
-      access_type: "offline",
-      prompt: "select_account",
-    });
-    window.location.href = `https://accounts.google.com/o/oauth2/v2/auth?${params}`;
-  };
+  const lastWorkspaceId =
+    typeof window !== "undefined"
+      ? localStorage.getItem("multica_workspace_id")
+      : null;
 
   return (
-    <div className="flex min-h-screen items-center justify-center">
-      <Card className="w-full max-w-sm">
-        <CardHeader className="text-center">
-          <CardTitle className="text-2xl">Multica</CardTitle>
-          <CardDescription>Turn coding agents into real teammates</CardDescription>
-        </CardHeader>
-        <CardContent>
-          <form id="login-form" onSubmit={handleSendCode} className="space-y-4">
-            <div className="space-y-2">
-              <Label htmlFor="email">Email</Label>
-              <Input
-                id="email"
-                type="email"
-                placeholder="you@example.com"
-                value={email}
-                onChange={(e) => setEmail(e.target.value)}
-                required
-              />
-            </div>
-            {error && (
-              <p className="text-sm text-destructive">{error}</p>
-            )}
-          </form>
-        </CardContent>
-        <CardFooter className="flex flex-col gap-3">
-          <Button
-            type="submit"
-            form="login-form"
-            disabled={submitting}
-            className="w-full"
-            size="lg"
-          >
-            {submitting ? "Sending code..." : "Continue"}
-          </Button>
-          {googleClientId && (
-            <>
-              <div className="relative w-full">
-                <div className="absolute inset-0 flex items-center">
-                  <span className="w-full border-t" />
-                </div>
-                <div className="relative flex justify-center text-xs uppercase">
-                  <span className="bg-card px-2 text-muted-foreground">or</span>
-                </div>
-              </div>
-              <Button
-                type="button"
-                variant="outline"
-                className="w-full"
-                size="lg"
-                onClick={handleGoogleLogin}
-                disabled={submitting}
-              >
-                <svg className="mr-2 h-4 w-4" viewBox="0 0 24 24">
-                  <path
-                    d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92a5.06 5.06 0 0 1-2.2 3.32v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.1z"
-                    fill="#4285F4"
-                  />
-                  <path
-                    d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
-                    fill="#34A853"
-                  />
-                  <path
-                    d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
-                    fill="#FBBC05"
-                  />
-                  <path
-                    d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
-                    fill="#EA4335"
-                  />
-                </svg>
-                Continue with Google
-              </Button>
-            </>
-          )}
-        </CardFooter>
-      </Card>
-    </div>
+    <LoginPage
+      onSuccess={() => router.push(nextUrl)}
+      google={
+        googleClientId
+          ? {
+              clientId: googleClientId,
+              redirectUri: `${window.location.origin}/auth/callback`,
+            }
+          : undefined
+      }
+      cliCallback={
+        cliCallbackRaw && validateCliCallback(cliCallbackRaw)
+          ? { url: cliCallbackRaw, state: cliState }
+          : undefined
+      }
+      lastWorkspaceId={lastWorkspaceId}
+      onTokenObtained={setLoggedInCookie}
+    />
   );
 }
 
-export default function LoginPage() {
+export default function Page() {
   return (
     <Suspense fallback={null}>
       <LoginPageContent />

apps/web/app/(dashboard)/issues/[id]/page.test.tsx

@@ -1,581 +0,0 @@
-import { Suspense, forwardRef, useRef, useState, useImperativeHandle } from "react";
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, waitFor, act, fireEvent } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import type { Issue, Comment, TimelineEntry } from "@multica/core/types";
-import { WorkspaceIdProvider } from "@multica/core/hooks";
-
-// Mock next/navigation
-vi.mock("next/navigation", () => ({
-  useRouter: () => ({ push: vi.fn() }),
-  usePathname: () => "/issues/issue-1",
-}));
-
-// Mock next/link
-vi.mock("next/link", () => ({
-  default: ({
-    children,
-    href,
-    ...props
-  }: {
-    children: React.ReactNode;
-    href: string;
-    [key: string]: any;
-  }) => (
-    <a href={href} {...props}>
-      {children}
-    </a>
-  ),
-}));
-
-// Mock auth store
-vi.mock("@/platform/auth", () => ({
-  useAuthStore: (selector: (s: any) => any) =>
-    selector({
-      user: { id: "user-1", name: "Test User", email: "test@multica.ai" },
-      isLoading: false,
-    }),
-}));
-
-// Mock @multica/core/workspace (used by @multica/views components)
-vi.mock("@multica/core/workspace", () => ({
-  useWorkspaceStore: Object.assign(
-    (selector: (s: any) => any) =>
-      selector({
-        workspace: { id: "ws-1", name: "Test WS" },
-        workspaces: [{ id: "ws-1", name: "Test WS" }],
-        members: [{ user_id: "user-1", name: "Test User", email: "test@multica.ai" }],
-        agents: [{ id: "agent-1", name: "Claude Agent" }],
-      }),
-    { getState: () => ({
-        workspace: { id: "ws-1", name: "Test WS" },
-        workspaces: [{ id: "ws-1", name: "Test WS" }],
-        members: [{ user_id: "user-1", name: "Test User", email: "test@multica.ai" }],
-        agents: [{ id: "agent-1", name: "Claude Agent" }],
-      }),
-    },
-  ),
-  registerWorkspaceStore: vi.fn(),
-}));
-
-// Mock @multica/core/auth (used by @multica/views components)
-vi.mock("@multica/core/auth", () => ({
-  useAuthStore: Object.assign(
-    (selector: (s: any) => any) =>
-      selector({
-        user: { id: "user-1", name: "Test User", email: "test@multica.ai" },
-        isLoading: false,
-      }),
-    { getState: () => ({
-        user: { id: "user-1", name: "Test User", email: "test@multica.ai" },
-        isLoading: false,
-      }),
-    },
-  ),
-  registerAuthStore: vi.fn(),
-  createAuthStore: vi.fn(),
-}));
-
-// Mock @multica/views/navigation (AppLink used by views components)
-vi.mock("@multica/views/navigation", () => ({
-  AppLink: ({ children, href, ...props }: any) => <a href={href} {...props}>{children}</a>,
-  useNavigation: () => ({ push: vi.fn(), pathname: "/issues/issue-1" }),
-  NavigationProvider: ({ children }: { children: React.ReactNode }) => children,
-}));
-
-// Mock @multica/views/editor (ContentEditor, TitleEditor used by IssueDetail)
-vi.mock("@multica/views/editor", () => ({
-  ReadonlyContent: ({ content }: { content: string }) => (
-    <div data-testid="readonly-content">{content}</div>
-  ),
-  ContentEditor: forwardRef(({ defaultValue, onUpdate, placeholder, onSubmit }: any, ref: any) => {
-    const valueRef = useRef(defaultValue || "");
-    const [value, setValue] = useState(defaultValue || "");
-    useImperativeHandle(ref, () => ({
-      getMarkdown: () => valueRef.current,
-      clearContent: () => { valueRef.current = ""; setValue(""); },
-      focus: () => {},
-    }));
-    return (
-      <textarea
-        value={value}
-        onChange={(e) => {
-          valueRef.current = e.target.value;
-          setValue(e.target.value);
-          onUpdate?.(e.target.value);
-        }}
-        onKeyDown={(e) => {
-          if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
-            onSubmit?.();
-          }
-        }}
-        placeholder={placeholder}
-        data-testid="rich-text-editor"
-      />
-    );
-  }),
-  TitleEditor: forwardRef(({ defaultValue, placeholder, onBlur, onChange }: any, ref: any) => {
-    const valueRef = useRef(defaultValue || "");
-    const [value, setValue] = useState(defaultValue || "");
-    useImperativeHandle(ref, () => ({
-      getText: () => valueRef.current,
-      focus: () => {},
-    }));
-    return (
-      <input
-        value={value}
-        onChange={(e) => {
-          valueRef.current = e.target.value;
-          setValue(e.target.value);
-          onChange?.(e.target.value);
-        }}
-        onBlur={() => onBlur?.(valueRef.current)}
-        placeholder={placeholder}
-        data-testid="title-editor"
-      />
-    );
-  }),
-}));
-
-// Mock @multica/views/workspace/workspace-avatar
-vi.mock("@multica/views/workspace/workspace-avatar", () => ({
-  WorkspaceAvatar: ({ name }: { name: string }) => <span>{name.charAt(0)}</span>,
-}));
-
-// Mock @multica/views/common/actor-avatar
-vi.mock("@multica/views/common/actor-avatar", () => ({
-  ActorAvatar: ({ actorType, actorId }: any) => <span data-testid="actor-avatar">{actorType}:{actorId}</span>,
-}));
-
-// Mock @multica/views/common/markdown
-vi.mock("@multica/views/common/markdown", () => ({
-  Markdown: ({ children }: { children: string }) => <div>{children}</div>,
-}));
-
-// Mock workspace feature
-vi.mock("@/features/workspace", () => ({
-  useWorkspaceStore: (selector: (s: any) => any) =>
-    selector({
-      workspace: { id: "ws-1", name: "Test WS" },
-      workspaces: [{ id: "ws-1", name: "Test WS" }],
-      members: [{ user_id: "user-1", name: "Test User", email: "test@multica.ai" }],
-      agents: [{ id: "agent-1", name: "Claude Agent" }],
-    }),
-  useActorName: () => ({
-    getMemberName: (id: string) => (id === "user-1" ? "Test User" : "Unknown"),
-    getAgentName: (id: string) => (id === "agent-1" ? "Claude Agent" : "Unknown Agent"),
-    getActorName: (type: string, id: string) => {
-      if (type === "member" && id === "user-1") return "Test User";
-      if (type === "agent" && id === "agent-1") return "Claude Agent";
-      return "Unknown";
-    },
-    getActorInitials: (type: string, id: string) => {
-      if (type === "member") return "TU";
-      if (type === "agent") return "CA";
-      return "??";
-    },
-    getActorAvatarUrl: () => null,
-  }),
-}));
-
-vi.mock("@/platform/workspace", () => ({
-  useWorkspaceStore: (selector: (s: any) => any) =>
-    selector({
-      workspace: { id: "ws-1", name: "Test WS" },
-      workspaces: [{ id: "ws-1", name: "Test WS" }],
-      members: [{ user_id: "user-1", name: "Test User", email: "test@multica.ai" }],
-      agents: [{ id: "agent-1", name: "Claude Agent" }],
-    }),
-}));
-
-// Mock workspace hooks from core
-vi.mock("@multica/core/workspace/hooks", () => ({
-  useActorName: () => ({
-    getMemberName: (id: string) => (id === "user-1" ? "Test User" : "Unknown"),
-    getAgentName: (id: string) => (id === "agent-1" ? "Claude Agent" : "Unknown Agent"),
-    getActorName: (type: string, id: string) => {
-      if (type === "member" && id === "user-1") return "Test User";
-      if (type === "agent" && id === "agent-1") return "Claude Agent";
-      return "Unknown";
-    },
-    getActorInitials: (type: string, id: string) => {
-      if (type === "member") return "TU";
-      if (type === "agent") return "CA";
-      return "??";
-    },
-    getActorAvatarUrl: () => null,
-  }),
-}));
-
-// Mock issue store — only client state remains (activeIssueId)
-vi.mock("@/features/issues", () => ({
-  useIssueStore: Object.assign(
-    (selector: (s: any) => any) => selector({ activeIssueId: null }),
-    { getState: () => ({ activeIssueId: null, setActiveIssue: vi.fn() }) },
-  ),
-}));
-
-vi.mock("@multica/core/issues", () => ({
-  useIssueStore: Object.assign(
-    (selector: (s: any) => any) => selector({ activeIssueId: null }),
-    { getState: () => ({ activeIssueId: null, setActiveIssue: vi.fn() }) },
-  ),
-}));
-
-// Mock ws-context
-vi.mock("@/features/realtime", () => ({
-  useWSEvent: () => {},
-  useWSReconnect: () => {},
-}));
-
-// Mock core realtime (hooks now import from @multica/core/realtime)
-vi.mock("@multica/core/realtime", () => ({
-  useWSEvent: () => {},
-  useWSReconnect: () => {},
-  useWS: () => ({ subscribe: vi.fn(() => () => {}), onReconnect: vi.fn(() => () => {}) }),
-  WSProvider: ({ children }: { children: React.ReactNode }) => children,
-  useRealtimeSync: () => {},
-}));
-
-// Mock calendar (react-day-picker needs browser APIs)
-vi.mock("@/components/ui/calendar", () => ({
-  Calendar: () => null,
-}));
-
-// Mock ContentEditor (Tiptap needs real DOM)
-vi.mock("@/features/editor", () => ({
-  ReadonlyContent: ({ content }: { content: string }) => (
-    <div data-testid="readonly-content">{content}</div>
-  ),
-  ContentEditor: forwardRef(({ defaultValue, onUpdate, placeholder, onSubmit }: any, ref: any) => {
-    const valueRef = useRef(defaultValue || "");
-    const [value, setValue] = useState(defaultValue || "");
-    useImperativeHandle(ref, () => ({
-      getMarkdown: () => valueRef.current,
-      clearContent: () => { valueRef.current = ""; setValue(""); },
-      focus: () => {},
-    }));
-    return (
-      <textarea
-        value={value}
-        onChange={(e) => {
-          valueRef.current = e.target.value;
-          setValue(e.target.value);
-          onUpdate?.(e.target.value);
-        }}
-        onKeyDown={(e) => {
-          if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
-            onSubmit?.();
-          }
-        }}
-        placeholder={placeholder}
-        data-testid="rich-text-editor"
-      />
-    );
-  }),
-  TitleEditor: forwardRef(({ defaultValue, placeholder, onBlur, onChange }: any, ref: any) => {
-    const valueRef = useRef(defaultValue || "");
-    const [value, setValue] = useState(defaultValue || "");
-    useImperativeHandle(ref, () => ({
-      getText: () => valueRef.current,
-      focus: () => {},
-    }));
-    return (
-      <input
-        value={value}
-        onChange={(e) => {
-          valueRef.current = e.target.value;
-          setValue(e.target.value);
-          onChange?.(e.target.value);
-        }}
-        onBlur={() => onBlur?.(valueRef.current)}
-        placeholder={placeholder}
-        data-testid="title-editor"
-      />
-    );
-  }),
-}));
-
-// Mock Markdown renderer
-vi.mock("@/components/markdown", () => ({
-  Markdown: ({ children }: { children: string }) => <div>{children}</div>,
-}));
-
-// Mock api (core queries/mutations use @multica/core/api, some components use @/platform/api)
-
-const mockApiObj = vi.hoisted(() => ({
-  getIssue: vi.fn(),
-  listTimeline: vi.fn(),
-  listComments: vi.fn().mockResolvedValue([]),
-  createComment: vi.fn(),
-  updateComment: vi.fn(),
-  deleteComment: vi.fn(),
-  deleteIssue: vi.fn(),
-  updateIssue: vi.fn(),
-  listIssueSubscribers: vi.fn().mockResolvedValue([]),
-  subscribeToIssue: vi.fn().mockResolvedValue(undefined),
-  unsubscribeFromIssue: vi.fn().mockResolvedValue(undefined),
-  getActiveTasksForIssue: vi.fn().mockResolvedValue({ tasks: [] }),
-  listTasksByIssue: vi.fn().mockResolvedValue([]),
-  listTaskMessages: vi.fn().mockResolvedValue([]),
-  listChildIssues: vi.fn().mockResolvedValue({ issues: [] }),
-  listIssues: vi.fn().mockResolvedValue({ issues: [], total: 0 }),
-  uploadFile: vi.fn(),
-}));
-
-vi.mock("@multica/core/api", () => ({
-  api: mockApiObj,
-  getApi: () => mockApiObj,
-  setApiInstance: vi.fn(),
-}));
-
-vi.mock("@/platform/api", () => ({
-  api: mockApiObj,
-}));
-
-// Mock issue config from core
-vi.mock("@multica/core/issues/config", () => ({
-  ALL_STATUSES: ["backlog", "todo", "in_progress", "in_review", "done", "blocked", "cancelled"],
-  BOARD_STATUSES: ["backlog", "todo", "in_progress", "in_review", "done", "blocked"],
-  STATUS_ORDER: ["backlog", "todo", "in_progress", "in_review", "done", "blocked", "cancelled"],
-  STATUS_CONFIG: {
-    backlog: { label: "Backlog", iconColor: "text-muted-foreground", hoverBg: "hover:bg-accent" },
-    todo: { label: "Todo", iconColor: "text-muted-foreground", hoverBg: "hover:bg-accent" },
-    in_progress: { label: "In Progress", iconColor: "text-warning", hoverBg: "hover:bg-warning/10" },
-    in_review: { label: "In Review", iconColor: "text-success", hoverBg: "hover:bg-success/10" },
-    done: { label: "Done", iconColor: "text-info", hoverBg: "hover:bg-info/10" },
-    blocked: { label: "Blocked", iconColor: "text-destructive", hoverBg: "hover:bg-destructive/10" },
-    cancelled: { label: "Cancelled", iconColor: "text-muted-foreground", hoverBg: "hover:bg-accent" },
-  },
-  PRIORITY_ORDER: ["urgent", "high", "medium", "low", "none"],
-  PRIORITY_CONFIG: {
-    urgent: { label: "Urgent", bars: 4, color: "text-destructive" },
-    high: { label: "High", bars: 3, color: "text-warning" },
-    medium: { label: "Medium", bars: 2, color: "text-warning" },
-    low: { label: "Low", bars: 1, color: "text-info" },
-    none: { label: "No priority", bars: 0, color: "text-muted-foreground" },
-  },
-}));
-
-// Mock modals
-vi.mock("@multica/core/modals", () => ({
-  useModalStore: Object.assign(
-    () => ({ open: vi.fn() }),
-    { getState: () => ({ open: vi.fn() }) },
-  ),
-}));
-
-// Mock utils
-vi.mock("@multica/core/utils", () => ({
-  timeAgo: (date: string) => "1d ago",
-}));
-
-const mockIssue: Issue = {
-  id: "issue-1",
-  workspace_id: "ws-1",
-  number: 1,
-  identifier: "TES-1",
-  title: "Implement authentication",
-  description: "Add JWT auth to the backend",
-  status: "in_progress",
-  priority: "high",
-  assignee_type: "member",
-  assignee_id: "user-1",
-  creator_type: "member",
-  creator_id: "user-1",
-  parent_issue_id: null,
-  project_id: null,
-  position: 0,
-  due_date: "2026-06-01T00:00:00Z",
-  created_at: "2026-01-15T00:00:00Z",
-  updated_at: "2026-01-20T00:00:00Z",
-};
-
-const mockTimeline: TimelineEntry[] = [
-  {
-    type: "comment",
-    id: "comment-1",
-    actor_type: "member",
-    actor_id: "user-1",
-    content: "Started working on this",
-    parent_id: null,
-    created_at: "2026-01-16T00:00:00Z",
-    updated_at: "2026-01-16T00:00:00Z",
-    comment_type: "comment",
-  },
-  {
-    type: "comment",
-    id: "comment-2",
-    actor_type: "agent",
-    actor_id: "agent-1",
-    content: "I can help with this",
-    parent_id: null,
-    created_at: "2026-01-17T00:00:00Z",
-    updated_at: "2026-01-17T00:00:00Z",
-    comment_type: "comment",
-  },
-];
-
-import IssueDetailPage from "./page";
-
-function createTestQueryClient() {
-  return new QueryClient({
-    defaultOptions: {
-      queries: { retry: false, gcTime: 0 },
-      mutations: { retry: false },
-    },
-  });
-}
-
-// React 19 use(Promise) needs the promise to resolve within act + Suspense
-async function renderPage(id = "issue-1") {
-  const queryClient = createTestQueryClient();
-  let result: ReturnType<typeof render>;
-  await act(async () => {
-    result = render(
-      <QueryClientProvider client={queryClient}>
-        <WorkspaceIdProvider wsId="ws-1">
-          <Suspense fallback={<div>Suspense loading...</div>}>
-            <IssueDetailPage params={Promise.resolve({ id })} />
-          </Suspense>
-        </WorkspaceIdProvider>
-      </QueryClientProvider>,
-    );
-  });
-  return result!;
-}
-
-describe("IssueDetailPage", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("renders issue details after loading", async () => {
-    mockApiObj.getIssue.mockResolvedValueOnce(mockIssue);
-    mockApiObj.listTimeline.mockResolvedValueOnce(mockTimeline);
-    await renderPage();
-
-    await waitFor(() => {
-      expect(
-        screen.getAllByText("Implement authentication").length,
-      ).toBeGreaterThanOrEqual(1);
-    });
-
-    expect(
-      screen.getByText("Add JWT auth to the backend"),
-    ).toBeInTheDocument();
-  });
-
-  it("renders issue properties sidebar", async () => {
-    mockApiObj.getIssue.mockResolvedValueOnce(mockIssue);
-    mockApiObj.listTimeline.mockResolvedValueOnce(mockTimeline);
-    await renderPage();
-
-    await waitFor(() => {
-      expect(screen.getByText("Properties")).toBeInTheDocument();
-    });
-
-    expect(screen.getByText("In Progress")).toBeInTheDocument();
-    expect(screen.getByText("High")).toBeInTheDocument();
-  });
-
-  it("renders comments", async () => {
-    mockApiObj.getIssue.mockResolvedValueOnce(mockIssue);
-    mockApiObj.listTimeline.mockResolvedValueOnce(mockTimeline);
-    await renderPage();
-
-    await waitFor(() => {
-      expect(
-        screen.getByText("Started working on this"),
-      ).toBeInTheDocument();
-    });
-
-    expect(screen.getByText("I can help with this")).toBeInTheDocument();
-    expect(screen.getAllByText("Activity").length).toBeGreaterThanOrEqual(1);
-  });
-
-  it("shows 'Issue not found' for missing issue", async () => {
-    // issue-detail fetches getIssue, useIssueReactions also fetches getIssue
-    mockApiObj.getIssue.mockRejectedValue(new Error("Not found"));
-    mockApiObj.listTimeline.mockRejectedValue(new Error("Not found"));
-    await renderPage("nonexistent-id");
-
-    await waitFor(() => {
-      expect(screen.getByText("This issue does not exist or has been deleted in this workspace.")).toBeInTheDocument();
-    });
-  });
-
-  it("submits a new comment", async () => {
-    mockApiObj.getIssue.mockResolvedValueOnce(mockIssue);
-    mockApiObj.listTimeline.mockResolvedValueOnce(mockTimeline);
-
-    const newComment: Comment = {
-      id: "comment-3",
-      issue_id: "issue-1",
-      content: "New test comment",
-      type: "comment",
-      author_type: "member",
-      author_id: "user-1",
-      parent_id: null,
-      reactions: [],
-      attachments: [],
-      created_at: "2026-01-18T00:00:00Z",
-      updated_at: "2026-01-18T00:00:00Z",
-    };
-    mockApiObj.createComment.mockResolvedValueOnce(newComment);
-
-    const user = userEvent.setup();
-    await renderPage();
-
-    await waitFor(() => {
-      expect(
-        screen.getByPlaceholderText("Leave a comment..."),
-      ).toBeInTheDocument();
-    });
-
-    const commentInput = screen.getByPlaceholderText("Leave a comment...");
-
-    // Use fireEvent to update the textarea value and trigger onUpdate
-    await act(async () => {
-      fireEvent.change(commentInput, { target: { value: "New test comment" } });
-    });
-
-    // Find the submit button associated with the "Leave a comment..." input.
-    // Multiple ArrowUp buttons exist (one per ReplyInput), so we find the
-    // button within the same ReplyInput container as our textarea.
-    const allArrowUpBtns = screen.getAllByRole("button").filter(
-      (btn) => btn.querySelector(".lucide-arrow-up") !== null,
-    );
-    // The bottom "Leave a comment..." ReplyInput renders last, so its button is last
-    const submitBtn = allArrowUpBtns[allArrowUpBtns.length - 1]!;
-    await waitFor(() => {
-      expect(submitBtn).not.toBeDisabled();
-    });
-    await user.click(submitBtn);
-
-    await waitFor(() => {
-      expect(mockApiObj.createComment).toHaveBeenCalled();
-      const [issueId, content] = mockApiObj.createComment.mock.calls[0]!;
-      expect(issueId).toBe("issue-1");
-      expect(content).toBe("New test comment");
-    });
-
-    await waitFor(() => {
-      expect(screen.getByText("New test comment")).toBeInTheDocument();
-    });
-  });
-
-  it("renders breadcrumb navigation", async () => {
-    mockApiObj.getIssue.mockResolvedValueOnce(mockIssue);
-    mockApiObj.listTimeline.mockResolvedValueOnce(mockTimeline);
-    await renderPage();
-
-    await waitFor(() => {
-      expect(screen.getByText("Test WS")).toBeInTheDocument();
-    });
-
-    const wsLink = screen.getByText("Test WS");
-    expect(wsLink.closest("a")).toHaveAttribute("href", "/issues");
-  });
-});

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

@@ -1,26 +1,9 @@
 "use client";
 
-import { Search } from "lucide-react";
-import { SidebarMenuButton } from "@multica/ui/components/ui/sidebar";
 import { DashboardLayout } from "@multica/views/layout";
 import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
-import { SearchCommand, useSearchStore } from "@/features/search";
-import { ChatFab, ChatWindow } from "@/features/chat";
-
-function SearchTrigger() {
-  return (
-    <SidebarMenuButton
-      className="text-muted-foreground"
-      onClick={() => useSearchStore.getState().setOpen(true)}
-    >
-      <Search />
-      <span>Search...</span>
-      <kbd className="pointer-events-none ml-auto inline-flex h-5 select-none items-center gap-0.5 rounded border bg-muted px-1.5 font-mono text-[10px] font-medium text-muted-foreground">
-        <span className="text-xs">⌘</span>K
-      </kbd>
-    </SidebarMenuButton>
-  );
-}
+import { SearchCommand, SearchTrigger } from "@multica/views/search";
+import { ChatFab, ChatWindow } from "@multica/views/chat";
 
 export default function Layout({ children }: { children: React.ReactNode }) {
   return (

apps/web/app/(landing)/about/page.tsx

@@ -4,11 +4,11 @@ import { AboutPageClient } from "@/features/landing/components/about-page-client
 export const metadata: Metadata = {
   title: "About",
   description:
-    "Learn about Multica — multiplexed information and computing agent. An open-source AI-native task management platform.",
+    "Learn about Multica — multiplexed information and computing agent. An open-source project management platform for human + agent teams.",
   openGraph: {
     title: "About Multica",
     description:
-      "The story behind Multica and why we're building AI-native task management.",
+      "The story behind Multica and why we're building project management for human + agent teams.",
     url: "/about",
   },
   alternates: {

apps/web/app/(landing)/homepage/page.tsx

@@ -6,7 +6,7 @@ export const metadata: Metadata = {
   description:
     "Multica — open-source platform that turns coding agents into real teammates. Assign tasks, track progress, compound skills.",
   openGraph: {
-    title: "Multica — AI-Native Task Management",
+    title: "Multica — Project Management for Human + Agent Teams",
     description:
       "Manage your human + agent workforce in one place.",
     url: "/homepage",

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

@@ -30,7 +30,7 @@ const jsonLd = {
       applicationCategory: "ProjectManagement",
       operatingSystem: "Web",
       description:
-        "AI-native task management platform that turns coding agents into real teammates.",
+        "Open-source project management platform that turns coding agents into real teammates.",
       offers: {
         "@type": "Offer",
         price: "0",

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

@@ -3,12 +3,12 @@ import { MulticaLanding } from "@/features/landing/components/multica-landing";
 
 export const metadata: Metadata = {
   title: {
-    absolute: "Multica — AI-Native Task Management",
+    absolute: "Multica — Project Management for Human + Agent Teams",
   },
   description:
     "Open-source platform that turns coding agents into real teammates. Assign tasks, track progress, compound skills.",
   openGraph: {
-    title: "Multica — AI-Native Task Management",
+    title: "Multica — Project Management for Human + Agent Teams",
     description:
       "Manage your human + agent workforce in one place.",
     url: "/",

apps/web/app/layout.tsx

@@ -22,7 +22,7 @@ export const viewport: Viewport = {
 export const metadata: Metadata = {
   metadataBase: new URL("https://www.multica.ai"),
   title: {
-    default: "Multica — AI-Native Task Management",
+    default: "Multica — Project Management for Human + Agent Teams",
     template: "%s | Multica",
   },
   description:

apps/web/components/loading-indicator.tsx

@@ -1,30 +0,0 @@
-"use client";
-
-import { Spinner } from "@/components/spinner";
-import { cn } from "@multica/ui/lib/utils";
-
-export type LoadingVariant = "generating" | "streaming";
-
-interface LoadingIndicatorProps {
-  variant: LoadingVariant;
-  className?: string;
-}
-
-const VARIANT_TEXT: Record<LoadingVariant, string> = {
-  generating: "Generating...",
-  streaming: "Streaming...",
-};
-
-/**
- * Unified loading indicator for chat.
- * Use "generating" when waiting for AI response (no content yet).
- * Use "streaming" when content is actively being received.
- */
-export function LoadingIndicator({ variant, className }: LoadingIndicatorProps) {
-  return (
-    <div className={cn("flex items-center gap-2 py-1 text-muted-foreground", className)}>
-      <Spinner className="text-xs" />
-      <span className="text-xs">{VARIANT_TEXT[variant]}</span>
-    </div>
-  );
-}

apps/web/components/markdown/CodeBlock.tsx

@@ -1 +0,0 @@
-export { CodeBlock, InlineCode, type CodeBlockProps } from '@multica/ui/markdown'

apps/web/components/markdown/Markdown.tsx

@@ -1,43 +0,0 @@
-import * as React from 'react'
-import {
-  Markdown as MarkdownBase,
-  MemoizedMarkdown as MemoizedMarkdownBase,
-  type MarkdownProps as MarkdownBaseProps,
-  type RenderMode
-} from '@multica/ui/markdown'
-import { IssueMentionCard } from '@multica/views/issues/components'
-
-export type { RenderMode }
-
-export type MarkdownProps = MarkdownBaseProps
-
-/**
- * Default renderMention that delegates to IssueMentionCard for issue mentions
- * and renders a styled span for other mention types.
- */
-function defaultRenderMention({ type, id }: { type: string; id: string }): React.ReactNode {
-  if (type === 'issue') {
-    return <IssueMentionCard issueId={id} />
-  }
-  return null
-}
-
-/**
- * App-level Markdown wrapper that injects IssueMentionCard via renderMention.
- * Callers that need custom mention rendering can pass their own renderMention prop.
- */
-export function Markdown(props: MarkdownProps): React.JSX.Element {
-  return <MarkdownBase renderMention={defaultRenderMention} {...props} />
-}
-
-export const MemoizedMarkdown = React.memo(Markdown, (prevProps, nextProps) => {
-  if (prevProps.id && nextProps.id) {
-    return (
-      prevProps.id === nextProps.id &&
-      prevProps.children === nextProps.children &&
-      prevProps.mode === nextProps.mode
-    )
-  }
-  return prevProps.children === nextProps.children && prevProps.mode === nextProps.mode
-})
-MemoizedMarkdown.displayName = 'MemoizedMarkdown'

apps/web/components/markdown/StreamingMarkdown.tsx

@@ -1,22 +0,0 @@
-import * as React from 'react'
-import {
-  StreamingMarkdown as StreamingMarkdownBase,
-  type StreamingMarkdownProps as StreamingMarkdownBaseProps
-} from '@multica/ui/markdown'
-import { IssueMentionCard } from '@multica/views/issues/components'
-
-export type StreamingMarkdownProps = StreamingMarkdownBaseProps
-
-function defaultRenderMention({ type, id }: { type: string; id: string }): React.ReactNode {
-  if (type === 'issue') {
-    return <IssueMentionCard issueId={id} />
-  }
-  return null
-}
-
-/**
- * App-level StreamingMarkdown wrapper that injects IssueMentionCard via renderMention.
- */
-export function StreamingMarkdown(props: StreamingMarkdownProps): React.JSX.Element {
-  return <StreamingMarkdownBase renderMention={defaultRenderMention} {...props} />
-}

apps/web/components/markdown/index.ts

@@ -1,5 +0,0 @@
-export { Markdown, MemoizedMarkdown, type MarkdownProps, type RenderMode } from './Markdown'
-export { CodeBlock, InlineCode, type CodeBlockProps } from './CodeBlock'
-export { StreamingMarkdown, type StreamingMarkdownProps } from './StreamingMarkdown'
-export { preprocessLinks, detectLinks, hasLinks } from './linkify'
-export { preprocessMentionShortcodes } from './mentions'

apps/web/components/markdown/linkify.ts

@@ -1 +0,0 @@
-export { preprocessLinks, detectLinks, hasLinks } from '@multica/ui/markdown'

apps/web/components/markdown/mentions.ts

@@ -1 +0,0 @@
-export { preprocessMentionShortcodes } from '@multica/ui/markdown'

apps/web/components/spinner.tsx

@@ -1,47 +0,0 @@
-/**
- * Spinner — 3x3 grid pulse for **active processing / execution** states.
- *
- * Use when the system is actively doing work or waiting for human action
- * (streaming content, generating responses, awaiting approval).
- * For passive content-loading states, use `<Loading />` instead.
- *
- * Inherits color from `currentColor` (use Tailwind `text-*`).
- * Scales with font-size (use Tailwind `text-*` for size).
- */
-import { cn } from "@multica/ui/lib/utils"
-
-export interface SpinnerProps {
-  /** Additional className for styling (color via text-*, size via Tailwind text-*) */
-  className?: string
-}
-
-const DELAYS = [0.2, 0.3, 0.4, 0.1, 0.2, 0.3, 0, 0.1, 0.2]
-
-const cubeStyle: React.CSSProperties = {
-  backgroundColor: "currentColor",
-  animation: "spinner-grid 1.3s infinite ease-in-out",
-  transform: "scale3d(0.5, 0.5, 1)",
-}
-
-export function Spinner({ className }: SpinnerProps) {
-  return (
-    <span
-      className={cn(className)}
-      role="status"
-      aria-label="Loading"
-      style={{
-        display: "inline-grid",
-        gridTemplateColumns: "repeat(3, 1fr)",
-        width: "1em",
-        height: "1em",
-        gap: "0.08em",
-      }}
-    >
-      {DELAYS.map((delay, i) => (
-        <span key={i} style={{ ...cubeStyle, animationDelay: `${delay}s` }} />
-      ))}
-
-      <style>{`@keyframes spinner-grid{0%,70%,100%{transform:scale3d(.5,.5,1)}35%{transform:scale3d(0,0,1)}}`}</style>
-    </span>
-  )
-}

apps/web/components/theme-toggle.tsx

@@ -1,40 +0,0 @@
-"use client"
-
-import { useTheme } from "next-themes"
-import { Sun, Moon, Monitor } from "lucide-react"
-import {
-  DropdownMenu,
-  DropdownMenuTrigger,
-  DropdownMenuContent,
-  DropdownMenuItem,
-} from "@multica/ui/components/ui/dropdown-menu"
-import { SidebarMenuButton } from "@multica/ui/components/ui/sidebar"
-
-export function ThemeToggle() {
-  const { setTheme } = useTheme()
-
-  return (
-    <DropdownMenu>
-      <DropdownMenuTrigger
-        render={
-          <SidebarMenuButton>
-            <Sun className="dark:hidden" />
-            <Moon className="hidden dark:block" />
-            <span>Theme</span>
-          </SidebarMenuButton>
-        }
-      />
-      <DropdownMenuContent side="top" align="start">
-        <DropdownMenuItem onClick={() => setTheme("light")}>
-          <Sun /> Light
-        </DropdownMenuItem>
-        <DropdownMenuItem onClick={() => setTheme("dark")}>
-          <Moon /> Dark
-        </DropdownMenuItem>
-        <DropdownMenuItem onClick={() => setTheme("system")}>
-          <Monitor /> System
-        </DropdownMenuItem>
-      </DropdownMenuContent>
-    </DropdownMenu>
-  )
-}

apps/web/core/chat/ws-updaters.ts

@@ -1,19 +0,0 @@
-import type { QueryClient } from "@tanstack/react-query";
-import type { ChatMessage } from "@multica/core/types";
-import { chatKeys } from "./queries";
-
-export function onChatMessageCreated(
-  qc: QueryClient,
-  sessionId: string,
-  message: ChatMessage,
-) {
-  qc.setQueryData<ChatMessage[]>(chatKeys.messages(sessionId), (old) => {
-    if (!old) return old;
-    if (old.some((m) => m.id === message.id)) return old;
-    return [...old, message];
-  });
-}
-
-export function onChatDone(qc: QueryClient, sessionId: string) {
-  qc.invalidateQueries({ queryKey: chatKeys.messages(sessionId) });
-}

apps/web/features/chat/store.ts

@@ -1,74 +0,0 @@
-import { create } from "zustand";
-
-const AGENT_STORAGE_KEY = "multica:chat:selectedAgentId";
-const SESSION_STORAGE_KEY = "multica:chat:activeSessionId";
-
-function readStored(key: string): string | null {
-  if (typeof window === "undefined") return null;
-  return localStorage.getItem(key);
-}
-
-export interface ChatTimelineItem {
-  seq: number;
-  type: "tool_use" | "tool_result" | "thinking" | "text" | "error";
-  tool?: string;
-  content?: string;
-  input?: Record<string, unknown>;
-  output?: string;
-}
-
-interface ChatState {
-  isOpen: boolean;
-  isFullscreen: boolean;
-  activeSessionId: string | null;
-  pendingTaskId: string | null;
-  selectedAgentId: string | null;
-  showHistory: boolean;
-  timelineItems: ChatTimelineItem[];
-  setOpen: (open: boolean) => void;
-  toggle: () => void;
-  toggleFullscreen: () => void;
-  setActiveSession: (id: string | null) => void;
-  setPendingTask: (taskId: string | null) => void;
-  setSelectedAgentId: (id: string) => void;
-  setShowHistory: (show: boolean) => void;
-  addTimelineItem: (item: ChatTimelineItem) => void;
-  clearTimeline: () => void;
-}
-
-export const useChatStore = create<ChatState>((set) => ({
-  isOpen: false,
-  isFullscreen: false,
-  activeSessionId: readStored(SESSION_STORAGE_KEY),
-  pendingTaskId: null,
-  selectedAgentId: readStored(AGENT_STORAGE_KEY),
-  showHistory: false,
-  timelineItems: [],
-  setOpen: (open) => set({ isOpen: open, ...(open ? {} : { isFullscreen: false }) }),
-  toggle: () => set((s) => ({ isOpen: !s.isOpen, ...(s.isOpen ? { isFullscreen: false } : {}) })),
-  toggleFullscreen: () => set((s) => ({ isFullscreen: !s.isFullscreen })),
-  setActiveSession: (id) => {
-    if (id) {
-      localStorage.setItem(SESSION_STORAGE_KEY, id);
-    } else {
-      localStorage.removeItem(SESSION_STORAGE_KEY);
-    }
-    set({ activeSessionId: id });
-  },
-  setPendingTask: (taskId) => set({ pendingTaskId: taskId, timelineItems: [] }),
-  setSelectedAgentId: (id) => {
-    localStorage.setItem(AGENT_STORAGE_KEY, id);
-    set({ selectedAgentId: id });
-  },
-  setShowHistory: (show) => set({ showHistory: show }),
-  addTimelineItem: (item) =>
-    set((s) => {
-      if (s.timelineItems.some((t) => t.seq === item.seq)) return s;
-      return {
-        timelineItems: [...s.timelineItems, item].sort(
-          (a, b) => a.seq - b.seq,
-        ),
-      };
-    }),
-  clearTimeline: () => set({ timelineItems: [] }),
-}));

apps/web/features/landing/components/changelog-page-client.tsx

@@ -4,8 +4,25 @@ import { LandingHeader } from "./landing-header";
 import { LandingFooter } from "./landing-footer";
 import { useLocale } from "../i18n";
 
+function ChangeList({ items }: { items: string[] }) {
+  return (
+    <ul className="mt-2 space-y-2">
+      {items.map((change) => (
+        <li
+          key={change}
+          className="flex items-start gap-2.5 text-[14px] leading-[1.7] text-[#0a0d12]/60 sm:text-[15px]"
+        >
+          <span className="mt-2.5 h-1 w-1 shrink-0 rounded-full bg-[#0a0d12]/30" />
+          {change}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
 export function ChangelogPageClient() {
   const { t } = useLocale();
+  const categoryLabels = t.changelog.categories;
 
   return (
     <>
@@ -20,32 +37,58 @@ export function ChangelogPageClient() {
           </p>
 
           <div className="mt-16 space-y-16">
-            {t.changelog.entries.map((release) => (
-              <div key={release.version} className="relative">
-                <div className="flex items-baseline gap-3">
-                  <span className="text-[13px] font-semibold tabular-nums">
-                    v{release.version}
-                  </span>
-                  <span className="text-[13px] text-[#0a0d12]/40">
-                    {release.date}
-                  </span>
+            {t.changelog.entries.map((release) => {
+              const hasCategorized =
+                release.features || release.improvements || release.fixes;
+
+              return (
+                <div key={release.version} className="relative">
+                  <div className="flex items-baseline gap-3">
+                    <span className="text-[13px] font-semibold tabular-nums">
+                      v{release.version}
+                    </span>
+                    <span className="text-[13px] text-[#0a0d12]/40">
+                      {release.date}
+                    </span>
+                  </div>
+                  <h2 className="mt-2 text-[20px] font-semibold leading-snug sm:text-[22px]">
+                    {release.title}
+                  </h2>
+
+                  {hasCategorized ? (
+                    <div className="mt-4 space-y-5">
+                      {release.features && release.features.length > 0 && (
+                        <div>
+                          <h3 className="text-[13px] font-semibold uppercase tracking-wide text-[#0a0d12]/50">
+                            {categoryLabels.features}
+                          </h3>
+                          <ChangeList items={release.features} />
+                        </div>
+                      )}
+                      {release.improvements &&
+                        release.improvements.length > 0 && (
+                          <div>
+                            <h3 className="text-[13px] font-semibold uppercase tracking-wide text-[#0a0d12]/50">
+                              {categoryLabels.improvements}
+                            </h3>
+                            <ChangeList items={release.improvements} />
+                          </div>
+                        )}
+                      {release.fixes && release.fixes.length > 0 && (
+                        <div>
+                          <h3 className="text-[13px] font-semibold uppercase tracking-wide text-[#0a0d12]/50">
+                            {categoryLabels.fixes}
+                          </h3>
+                          <ChangeList items={release.fixes} />
+                        </div>
+                      )}
+                    </div>
+                  ) : (
+                    <ChangeList items={release.changes} />
+                  )}
                 </div>
-                <h2 className="mt-2 text-[20px] font-semibold leading-snug sm:text-[22px]">
-                  {release.title}
-                </h2>
-                <ul className="mt-4 space-y-2">
-                  {release.changes.map((change) => (
-                    <li
-                      key={change}
-                      className="flex items-start gap-2.5 text-[14px] leading-[1.7] text-[#0a0d12]/60 sm:text-[15px]"
-                    >
-                      <span className="mt-2.5 h-1 w-1 shrink-0 rounded-full bg-[#0a0d12]/30" />
-                      {change}
-                    </li>
-                  ))}
-                </ul>
-              </div>
-            ))}
+              );
+            })}
           </div>
         </div>
       </main>

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

@@ -271,7 +271,94 @@ export const en: LandingDict = {
   changelog: {
     title: "Changelog",
     subtitle: "New updates and improvements to Multica.",
+    categories: {
+      features: "New Features",
+      improvements: "Improvements",
+      fixes: "Bug Fixes",
+    },
     entries: [
+      {
+        version: "0.1.24",
+        date: "2026-04-11",
+        title: "Security & Notifications",
+        changes: [],
+        features: [
+          "Parent issue subscribers notified on sub-issue changes",
+          "CLI `--project` filter for issue list",
+        ],
+        improvements: [
+          "Meta-skill workflow defers to agent Skills instead of hardcoded logic",
+        ],
+        fixes: [
+          "Workspace ownership checks on all daemon API routes",
+          "Workspace ownership validation for attachment uploads and queries",
+          "Reply mentions no longer inherit parent thread's agent mentions",
+          "Agent comment creation missing workspace ID",
+          "Self-hosting Docker build failures (file permissions, CRLF, missing deps)",
+        ],
+      },
+      {
+        version: "0.1.23",
+        date: "2026-04-11",
+        title: "Pinning, Cmd+K & Projects",
+        changes: [],
+        features: [
+          "Pin issues and projects to sidebar with drag-and-drop reordering",
+          "Cmd+K command palette — recent issues, page navigation, and project search",
+          "Project detail sidebar with properties panel (replaces overview tab)",
+          "Project filter in Issues tab",
+          "Project completion progress in project list",
+          "Auto-fill project when creating issue via 'C' shortcut on project page",
+          "Assignee dropdown sorted by user's assignment frequency",
+        ],
+        fixes: [
+          "Markdown XSS — sanitize HTML rendering in comments with rehype-sanitize and server-side bluemonday",
+          "Project kanban issue counts incorrect",
+          "Self-hosting Docker build missing tsconfig dependencies",
+          "Cmd+K requiring double ESC to close",
+        ],
+      },
+      {
+        version: "0.1.22",
+        date: "2026-04-10",
+        title: "Self-Hosting, ACP & Documentation",
+        changes: [],
+        features: [
+          "Full-stack Docker Compose for one-command self-hosting",
+          "Hermes Agent Provider via ACP protocol",
+          "Documentation site with Fumadocs (Getting Started, CLI reference, Agents guide)",
+          "Mobile-responsive sidebar and inbox layout",
+          "Token usage display per issue in the detail sidebar",
+          "Switch agent runtime from the UI",
+          "'C' keyboard shortcut for quick issue creation",
+          "Chat session history panel for archived conversations",
+          "Minimum CLI version check in daemon for Claude Code and Codex",
+          "OpenClaw and OpenCode added to landing page",
+          "`make dev` one-command local development setup",
+        ],
+        improvements: [
+          "Sidebar redesign — Personal / Workspace grouping, user profile footer, ⌘K search input",
+          "Search ranking — case-insensitive matching, identifier search (MUL-123), multi-word support",
+          "Search result keyword highlighting",
+          "Daily token usage chart with cleaner Y-axis and per-category tooltip",
+          "Master Agent multiline input support",
+          "Unified picker components (Status, Priority, DueDate, Project, Assignee) across all views",
+          "Workspace-scoped storage isolation with auto-rehydration on switch",
+          "Startup warnings for missing env vars in self-hosted deployments",
+        ],
+        fixes: [
+          "Sub-issue deletion not invalidating parent's children cache",
+          "Search index compatibility with pg_bigm 1.2 on RDS",
+          "Create Agent showing \"No runtime available\" when runtimes exist",
+          "Claude stream-json startup hangs",
+          "Multiple agents unable to queue tasks for the same issue",
+          "Logout not clearing workspace and query cache",
+          "Drag-drop overlay too small on empty editors",
+          "Skills import hardcoding \"main\" as default branch",
+          "PAT authentication not working on WebSocket endpoint",
+          "Runtime deletion blocked when all bound agents are archived",
+        ],
+      },
       {
         version: "0.1.21",
         date: "2026-04-09",

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

@@ -85,11 +85,19 @@ export type LandingDict = {
   changelog: {
     title: string;
     subtitle: string;
+    categories: {
+      features: string;
+      improvements: string;
+      fixes: string;
+    };
     entries: {
       version: string;
       date: string;
       title: string;
       changes: string[];
+      features?: string[];
+      improvements?: string[];
+      fixes?: string[];
     }[];
   };
 };

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

@@ -271,7 +271,94 @@ export const zh: LandingDict = {
   changelog: {
     title: "\u66f4\u65b0\u65e5\u5fd7",
     subtitle: "Multica \u7684\u6700\u65b0\u66f4\u65b0\u548c\u6539\u8fdb\u3002",
+    categories: {
+      features: "新功能",
+      improvements: "改进",
+      fixes: "问题修复",
+    },
     entries: [
+      {
+        version: "0.1.24",
+        date: "2026-04-11",
+        title: "安全加固与通知",
+        changes: [],
+        features: [
+          "子 Issue 变更时通知父 Issue 的订阅者",
+          "CLI `--project` 筛选 Issue 列表",
+        ],
+        improvements: [
+          "Meta-skill 工作流改为委托 Agent Skills 而非硬编码逻辑",
+        ],
+        fixes: [
+          "Daemon API 路由新增工作区所有权校验",
+          "附件上传和查询新增工作区所有权验证",
+          "回复评论不再继承父级线程的 Agent 提及",
+          "Agent 创建评论缺少 workspace ID",
+          "自部署 Docker 构建问题修复（文件权限、CRLF 换行、缺失依赖）",
+        ],
+      },
+      {
+        version: "0.1.23",
+        date: "2026-04-11",
+        title: "置顶、Cmd+K 与项目增强",
+        changes: [],
+        features: [
+          "Issue 和项目置顶到侧边栏，支持拖拽排序",
+          "Cmd+K 命令面板——最近访问的 Issue、页面导航、项目搜索",
+          "项目详情侧边栏属性面板（替代原概览标签页）",
+          "Issues 列表新增项目筛选",
+          "项目列表显示完成进度",
+          "在项目页按 'C' 创建 Issue 时自动填充项目",
+          "指派人下拉按用户分配频率排序",
+        ],
+        fixes: [
+          "Markdown XSS 漏洞——评论渲染增加 rehype-sanitize 和服务端 bluemonday 清洗",
+          "项目看板 Issue 计数不正确",
+          "自部署 Docker 构建缺少 tsconfig 依赖",
+          "Cmd+K 需要按两次 ESC 才能关闭",
+        ],
+      },
+      {
+        version: "0.1.22",
+        date: "2026-04-10",
+        title: "自部署、ACP 与文档站",
+        changes: [],
+        features: [
+          "全栈 Docker Compose 一键自部署",
+          "通过 ACP 协议接入 Hermes Agent Provider",
+          "基于 Fumadocs 搭建文档站（快速入门、CLI 参考、Agent 指南）",
+          "侧边栏和收件箱移动端响应式布局",
+          "Issue 详情侧边栏展示 Token 用量",
+          "支持在 UI 中切换 Agent 运行时",
+          "'C' 快捷键快速创建 Issue",
+          "聊天会话历史面板，查看已归档对话",
+          "Daemon 新增 Claude Code 和 Codex 最低版本检查",
+          "官网新增 OpenClaw 和 OpenCode 展示",
+          "`make dev` 一键本地开发环境搭建",
+        ],
+        improvements: [
+          "侧边栏重新设计——个人/工作区分组、用户档案底栏、⌘K 搜索入口",
+          "搜索排序优化——大小写无关匹配、标识符搜索（MUL-123）、多词匹配",
+          "搜索结果关键词高亮",
+          "每日 Token 用量图表优化，Y 轴标签更清晰，新增分类 Tooltip",
+          "Master Agent 支持多行输入",
+          "统一选择器组件（状态、优先级、截止日期、项目、指派人）",
+          "工作区级别存储隔离，切换工作区时自动加载对应数据",
+          "自部署环境变量缺失时给出启动警告",
+        ],
+        fixes: [
+          "删除子 Issue 后父级列表未刷新",
+          "搜索索引兼容 RDS 上的 pg_bigm 1.2",
+          "创建 Agent 对话框错误显示「无可用运行时」",
+          "Claude stream-json 启动卡住",
+          "多个 Agent 无法同时为同一 Issue 排队任务",
+          "退出登录未清除工作区和查询缓存",
+          "编辑器为空时拖放区域过小",
+          "Skills 导入硬编码 main 分支导致 404",
+          "WebSocket 端点不支持 PAT 认证",
+          "所有 Agent 已归档时无法删除运行时",
+        ],
+      },
       {
         version: "0.1.21",
         date: "2026-04-09",

apps/web/features/search/components/search-command.tsx

@@ -1,242 +0,0 @@
-"use client";
-
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useRouter } from "next/navigation";
-import { Loader2, MessageSquare, SearchIcon } from "lucide-react";
-import { Command as CommandPrimitive } from "cmdk";
-import type { SearchIssueResult } from "@multica/core/types";
-import { api } from "@multica/core/api";
-import { StatusIcon } from "@multica/views/issues/components";
-import { STATUS_CONFIG } from "@multica/core/issues/config";
-import {
-  Dialog,
-  DialogContent,
-  DialogHeader,
-  DialogTitle,
-  DialogDescription,
-} from "@multica/ui/components/ui/dialog";
-import { useSearchStore } from "../stores/search-store";
-
-function HighlightText({ text, query }: { text: string; query: string }) {
-  const parts = useMemo(() => {
-    if (!query.trim()) return [{ text, highlight: false }];
-    const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const regex = new RegExp(`(${escaped})`, "gi");
-    const result: { text: string; highlight: boolean }[] = [];
-    let lastIndex = 0;
-    let match: RegExpExecArray | null;
-    while ((match = regex.exec(text)) !== null) {
-      if (match.index > lastIndex) {
-        result.push({ text: text.slice(lastIndex, match.index), highlight: false });
-      }
-      result.push({ text: match[0], highlight: true });
-      lastIndex = regex.lastIndex;
-    }
-    if (lastIndex < text.length) {
-      result.push({ text: text.slice(lastIndex), highlight: false });
-    }
-    return result.length > 0 ? result : [{ text, highlight: false }];
-  }, [text, query]);
-
-  return (
-    <>
-      {parts.map((part, i) =>
-        part.highlight ? (
-          <mark key={i} className="bg-yellow-200 dark:bg-yellow-900/60 text-inherit rounded-sm">
-            {part.text}
-          </mark>
-        ) : (
-          part.text
-        ),
-      )}
-    </>
-  );
-}
-
-export function SearchCommand() {
-  const router = useRouter();
-  const open = useSearchStore((s) => s.open);
-  const setOpen = useSearchStore((s) => s.setOpen);
-  const [query, setQuery] = useState("");
-  const [results, setResults] = useState<SearchIssueResult[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
-  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const abortRef = useRef<AbortController | null>(null);
-
-  // Global Cmd+K / Ctrl+K shortcut
-  useEffect(() => {
-    const handleKeyDown = (e: KeyboardEvent) => {
-      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
-        e.preventDefault();
-        useSearchStore.getState().toggle();
-      }
-    };
-    document.addEventListener("keydown", handleKeyDown);
-    return () => document.removeEventListener("keydown", handleKeyDown);
-  }, []);
-
-  // Cleanup debounce/abort on unmount
-  useEffect(() => {
-    return () => {
-      if (debounceRef.current) clearTimeout(debounceRef.current);
-      if (abortRef.current) abortRef.current.abort();
-    };
-  }, []);
-
-  // Reset state when dialog closes
-  useEffect(() => {
-    if (!open) {
-      setQuery("");
-      setResults([]);
-      setIsLoading(false);
-    }
-  }, [open]);
-
-  const search = useCallback((q: string) => {
-    if (debounceRef.current) clearTimeout(debounceRef.current);
-    if (abortRef.current) abortRef.current.abort();
-
-    if (!q.trim()) {
-      setResults([]);
-      setIsLoading(false);
-      return;
-    }
-
-    setIsLoading(true);
-    debounceRef.current = setTimeout(async () => {
-      const controller = new AbortController();
-      abortRef.current = controller;
-      try {
-        const res = await api.searchIssues({
-          q: q.trim(),
-          limit: 20,
-          include_closed: true,
-          signal: controller.signal,
-        });
-        if (!controller.signal.aborted) {
-          setResults(res.issues);
-          setIsLoading(false);
-        }
-      } catch {
-        if (!controller.signal.aborted) {
-          setIsLoading(false);
-        }
-      }
-    }, 300);
-  }, []);
-
-  const handleValueChange = useCallback(
-    (value: string) => {
-      setQuery(value);
-      search(value);
-    },
-    [search],
-  );
-
-  const handleSelect = useCallback(
-    (issueId: string) => {
-      setOpen(false);
-      router.push(`/issues/${issueId}`);
-    },
-    [router],
-  );
-
-  return (
-    <Dialog open={open} onOpenChange={setOpen}>
-      <DialogContent
-        className="top-[20%] translate-y-0 overflow-hidden rounded-xl! p-0 sm:max-w-xl!"
-        showCloseButton={false}
-      >
-        <DialogHeader className="sr-only">
-          <DialogTitle>Search Issues</DialogTitle>
-          <DialogDescription>
-            Search issues by title, description, or comments
-          </DialogDescription>
-        </DialogHeader>
-        <CommandPrimitive
-          shouldFilter={false}
-          className="flex size-full flex-col overflow-hidden rounded-xl bg-popover text-popover-foreground"
-        >
-          {/* Search input */}
-          <div className="flex items-center gap-3 border-b px-4 py-3">
-            <SearchIcon className="size-5 shrink-0 text-muted-foreground" />
-            <CommandPrimitive.Input
-              placeholder="Type a command or search..."
-              value={query}
-              onValueChange={handleValueChange}
-              className="flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground"
-            />
-            <kbd className="hidden shrink-0 rounded bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground sm:inline">
-              ESC
-            </kbd>
-          </div>
-
-          {/* Results list */}
-          <CommandPrimitive.List className="max-h-[min(400px,50vh)] overflow-y-auto overflow-x-hidden">
-            {isLoading && (
-              <div className="flex items-center justify-center py-10">
-                <Loader2 className="size-5 animate-spin text-muted-foreground" />
-              </div>
-            )}
-
-            {!isLoading && query.trim() && results.length === 0 && (
-              <CommandPrimitive.Empty className="py-10 text-center text-sm text-muted-foreground">
-                No issues found.
-              </CommandPrimitive.Empty>
-            )}
-
-            {!isLoading && results.length > 0 && (
-              <CommandPrimitive.Group className="p-2">
-                {results.map((issue) => (
-                  <CommandPrimitive.Item
-                    key={issue.id}
-                    value={issue.id}
-                    onSelect={handleSelect}
-                    className="flex cursor-default select-none flex-col gap-1 rounded-lg px-3 py-2.5 text-sm outline-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-selected:bg-accent"
-                  >
-                    <div className="flex items-center gap-2.5">
-                      <StatusIcon
-                        status={issue.status}
-                        className="size-4 shrink-0"
-                      />
-                      <span className="text-xs text-muted-foreground shrink-0">
-                        {issue.identifier}
-                      </span>
-                      <span className="truncate">
-                        <HighlightText text={issue.title} query={query} />
-                      </span>
-                      <span
-                        className={`ml-auto text-xs shrink-0 ${STATUS_CONFIG[issue.status].iconColor}`}
-                      >
-                        {STATUS_CONFIG[issue.status].label}
-                      </span>
-                    </div>
-                    {issue.match_source === "comment" &&
-                      issue.matched_snippet && (
-                        <div className="flex items-start gap-2 pl-[26px]">
-                          <MessageSquare className="size-3 shrink-0 text-muted-foreground mt-0.5" />
-                          <span className="text-xs text-muted-foreground truncate">
-                            <HighlightText
-                              text={issue.matched_snippet}
-                              query={query}
-                            />
-                          </span>
-                        </div>
-                      )}
-                  </CommandPrimitive.Item>
-                ))}
-              </CommandPrimitive.Group>
-            )}
-
-            {!isLoading && !query.trim() && (
-              <div className="flex flex-col items-center gap-2 py-10 text-sm text-muted-foreground">
-                <span>Type to search issues...</span>
-                <span className="text-xs">Press <kbd className="rounded bg-muted px-1.5 py-0.5 font-medium">⌘K</kbd> to open this anytime</span>
-              </div>
-            )}
-          </CommandPrimitive.List>
-        </CommandPrimitive>
-      </DialogContent>
-    </Dialog>
-  );
-}

apps/web/features/search/index.ts

@@ -1,2 +0,0 @@
-export { SearchCommand } from "./components/search-command";
-export { useSearchStore } from "./stores/search-store";

apps/web/next.config.ts

@@ -22,6 +22,7 @@ const allowedDevOrigins = process.env.CORS_ALLOWED_ORIGINS
   : undefined;
 
 const nextConfig: NextConfig = {
+  ...(process.env.STANDALONE === "true" ? { output: "standalone" as const } : {}),
   transpilePackages: ["@multica/core", "@multica/ui", "@multica/views"],
   ...(allowedDevOrigins && allowedDevOrigins.length > 0
     ? { allowedDevOrigins }

apps/web/package.json

@@ -12,15 +12,15 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@multica/core": "workspace:*",
-    "@multica/ui": "workspace:*",
-    "@multica/views": "workspace:*",
     "@base-ui/react": "^1.3.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@emoji-mart/data": "^1.2.1",
     "@floating-ui/dom": "^1.7.6",
+    "@multica/core": "workspace:*",
+    "@multica/ui": "workspace:*",
+    "@multica/views": "workspace:*",
     "@tanstack/react-query": "^5.96.2",
     "@tanstack/react-query-devtools": "^5.96.2",
     "@tiptap/extension-code-block-lowlight": "^3.22.1",
@@ -43,13 +43,14 @@
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
+    "dotenv": "^17.4.1",
     "embla-carousel-react": "^8.6.0",
     "emoji-mart": "^5.6.0",
     "input-otp": "^1.4.2",
     "linkify-it": "^5.0.0",
     "lowlight": "^3.3.0",
     "lucide-react": "catalog:",
-    "next": "^16.1.6",
+    "next": "^16.2.3",
     "next-themes": "^0.4.6",
     "react": "catalog:",
     "react-day-picker": "^9.14.0",
@@ -69,15 +70,15 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "catalog:",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
-    "@testing-library/user-event": "^14.6.1",
+    "@testing-library/jest-dom": "catalog:",
+    "@testing-library/react": "catalog:",
+    "@testing-library/user-event": "catalog:",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
-    "@vitejs/plugin-react": "^6.0.1",
-    "jsdom": "^29.0.1",
+    "@vitejs/plugin-react": "catalog:",
+    "jsdom": "catalog:",
     "tailwindcss": "catalog:",
     "typescript": "catalog:",
-    "vitest": "^4.1.0"
+    "vitest": "catalog:"
   }
 }

docker-compose.selfhost.yml

@@ -0,0 +1,73 @@
+# Self-hosting Docker Compose — starts PostgreSQL, backend, and frontend.
+#
+# Usage:
+#   cp .env.example .env
+#   # Edit .env — change JWT_SECRET at minimum
+#   docker compose -f docker-compose.selfhost.yml up -d
+#
+# Frontend: http://localhost:3000
+# Backend:  http://localhost:8080 (also used by CLI/daemon)
+
+name: multica
+
+services:
+  postgres:
+    image: pgvector/pgvector:pg17
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-multica}
+      POSTGRES_USER: ${POSTGRES_USER:-multica}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-multica}
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-multica} -d ${POSTGRES_DB:-multica}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  backend:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "${PORT:-8080}:8080"
+    environment:
+      DATABASE_URL: postgres://${POSTGRES_USER:-multica}:${POSTGRES_PASSWORD:-multica}@postgres:5432/${POSTGRES_DB:-multica}?sslmode=disable
+      PORT: "8080"
+      JWT_SECRET: ${JWT_SECRET:-change-me-in-production}
+      FRONTEND_ORIGIN: ${FRONTEND_ORIGIN:-http://localhost:3000}
+      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:-}
+      RESEND_API_KEY: ${RESEND_API_KEY:-}
+      RESEND_FROM_EMAIL: ${RESEND_FROM_EMAIL:-noreply@multica.ai}
+      GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID:-}
+      GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET:-}
+      GOOGLE_REDIRECT_URI: ${GOOGLE_REDIRECT_URI:-http://localhost:3000/auth/callback}
+      S3_BUCKET: ${S3_BUCKET:-}
+      S3_REGION: ${S3_REGION:-us-west-2}
+      CLOUDFRONT_DOMAIN: ${CLOUDFRONT_DOMAIN:-}
+      CLOUDFRONT_KEY_PAIR_ID: ${CLOUDFRONT_KEY_PAIR_ID:-}
+      CLOUDFRONT_PRIVATE_KEY: ${CLOUDFRONT_PRIVATE_KEY:-}
+      COOKIE_DOMAIN: ${COOKIE_DOMAIN:-}
+      MULTICA_APP_URL: ${MULTICA_APP_URL:-http://localhost:3000}
+
+  frontend:
+    build:
+      context: .
+      dockerfile: Dockerfile.web
+      args:
+        REMOTE_API_URL: http://backend:8080
+        NEXT_PUBLIC_GOOGLE_CLIENT_ID: ${NEXT_PUBLIC_GOOGLE_CLIENT_ID:-}
+    depends_on:
+      - backend
+    ports:
+      - "${FRONTEND_PORT:-3000}:3000"
+    environment:
+      HOSTNAME: "0.0.0.0"
+
+volumes:
+  pgdata:

docker/entrypoint.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+set -e
+
+echo "Running database migrations..."
+./migrate up
+
+echo "Starting server..."
+exec ./server

package.json

@@ -10,7 +10,8 @@
     "typecheck": "turbo typecheck",
     "test": "turbo test",
     "lint": "turbo lint",
-    "clean": "turbo clean && rm -rf node_modules"
+    "clean": "turbo clean && rm -rf node_modules",
+    "ui:add": "cd packages/ui && npx shadcn@latest add"
   },
   "packageManager": "pnpm@10.28.2",
   "pnpm": {

packages/core/api/client.ts

@@ -4,6 +4,7 @@ import type {
   UpdateIssueRequest,
   ListIssuesResponse,
   SearchIssuesResponse,
+  SearchProjectsResponse,
   UpdateMeRequest,
   CreateMemberRequest,
   UpdateMemberRequest,
@@ -30,10 +31,12 @@ import type {
   CreatePersonalAccessTokenRequest,
   CreatePersonalAccessTokenResponse,
   RuntimeUsage,
+  IssueUsageSummary,
   RuntimeHourlyActivity,
   RuntimePing,
   RuntimeUpdate,
   TimelineEntry,
+  AssigneeFrequencyEntry,
   TaskMessagePayload,
   Attachment,
   ChatSession,
@@ -43,6 +46,10 @@ import type {
   CreateProjectRequest,
   UpdateProjectRequest,
   ListProjectsResponse,
+  PinnedItem,
+  CreatePinRequest,
+  PinnedItemType,
+  ReorderPinsRequest,
 } from "../types";
 import { type Logger, noopLogger } from "../logger";
 
@@ -181,6 +188,8 @@ export class ApiClient {
     if (params?.status) search.set("status", params.status);
     if (params?.priority) search.set("priority", params.priority);
     if (params?.assignee_id) search.set("assignee_id", params.assignee_id);
+    if (params?.assignee_ids?.length) search.set("assignee_ids", params.assignee_ids.join(","));
+    if (params?.creator_id) search.set("creator_id", params.creator_id);
     if (params?.open_only) search.set("open_only", "true");
     return this.fetch(`/api/issues?${search}`);
   }
@@ -193,6 +202,14 @@ export class ApiClient {
     return this.fetch(`/api/issues/search?${search}`, params.signal ? { signal: params.signal } : undefined);
   }
 
+  async searchProjects(params: { q: string; limit?: number; offset?: number; include_closed?: boolean; signal?: AbortSignal }): Promise<SearchProjectsResponse> {
+    const search = new URLSearchParams({ q: params.q });
+    if (params.limit !== undefined) search.set("limit", String(params.limit));
+    if (params.offset !== undefined) search.set("offset", String(params.offset));
+    if (params.include_closed) search.set("include_closed", "true");
+    return this.fetch(`/api/projects/search?${search}`, params.signal ? { signal: params.signal } : undefined);
+  }
+
   async getIssue(id: string): Promise<Issue> {
     return this.fetch(`/api/issues/${id}`);
   }
@@ -256,6 +273,10 @@ export class ApiClient {
     return this.fetch(`/api/issues/${issueId}/timeline`);
   }
 
+  async getAssigneeFrequency(): Promise<AssigneeFrequencyEntry[]> {
+    return this.fetch("/api/assignee-frequency");
+  }
+
   async updateComment(commentId: string, content: string): Promise<Comment> {
     return this.fetch(`/api/comments/${commentId}`, {
       method: "PUT",
@@ -418,6 +439,10 @@ export class ApiClient {
     return this.fetch(`/api/issues/${issueId}/task-runs`);
   }
 
+  async getIssueUsage(issueId: string): Promise<IssueUsageSummary> {
+    return this.fetch(`/api/issues/${issueId}/usage`);
+  }
+
   async cancelTask(issueId: string, taskId: string): Promise<AgentTask> {
     return this.fetch(`/api/issues/${issueId}/tasks/${taskId}/cancel`, {
       method: "POST",
@@ -681,4 +706,27 @@ export class ApiClient {
   async deleteProject(id: string): Promise<void> {
     await this.fetch(`/api/projects/${id}`, { method: "DELETE" });
   }
+
+  // Pins
+  async listPins(): Promise<PinnedItem[]> {
+    return this.fetch("/api/pins");
+  }
+
+  async createPin(data: CreatePinRequest): Promise<PinnedItem> {
+    return this.fetch("/api/pins", {
+      method: "POST",
+      body: JSON.stringify(data),
+    });
+  }
+
+  async deletePin(itemType: PinnedItemType, itemId: string): Promise<void> {
+    await this.fetch(`/api/pins/${itemType}/${itemId}`, { method: "DELETE" });
+  }
+
+  async reorderPins(data: ReorderPinsRequest): Promise<void> {
+    await this.fetch("/api/pins/reorder", {
+      method: "PUT",
+      body: JSON.stringify(data),
+    });
+  }
 }

packages/core/auth/store.ts

@@ -72,6 +72,7 @@ export function createAuthStore(options: AuthStoreOptions) {
 
     logout: () => {
       storage.removeItem("multica_token");
+      storage.removeItem("multica_workspace_id");
       api.setToken(null);
       api.setWorkspaceId(null);
       onLogout?.();

packages/core/chat/index.ts

@@ -0,0 +1,38 @@
+export { createChatStore } from "./store";
+export type { ChatStoreOptions, ChatState, ChatTimelineItem } from "./store";
+
+import type { createChatStore as CreateChatStoreFn } from "./store";
+
+type ChatStoreInstance = ReturnType<typeof CreateChatStoreFn>;
+
+/** Module-level singleton — set once at app boot via `registerChatStore()`. */
+let _store: ChatStoreInstance | null = null;
+
+/**
+ * Register the chat store instance created by the app.
+ * Must be called at boot before any component renders.
+ */
+export function registerChatStore(store: ChatStoreInstance) {
+  _store = store;
+}
+
+/**
+ * Singleton accessor — a Zustand hook backed by the registered instance.
+ * Supports `useChatStore(selector)` and `useChatStore.getState()`.
+ */
+export const useChatStore: ChatStoreInstance = new Proxy(
+  (() => {}) as unknown as ChatStoreInstance,
+  {
+    apply(_target, _thisArg, args) {
+      if (!_store)
+        throw new Error(
+          "Chat store not initialised — call registerChatStore() first",
+        );
+      return (_store as unknown as (...a: unknown[]) => unknown)(...args);
+    },
+    get(_target, prop) {
+      if (!_store) return undefined;
+      return Reflect.get(_store, prop);
+    },
+  },
+);

packages/core/chat/mutations.ts

@@ -1,6 +1,6 @@
 import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { api } from "@multica/core/api";
-import { useWorkspaceId } from "@multica/core/hooks";
+import { api } from "../api";
+import { useWorkspaceId } from "../hooks";
 import { chatKeys } from "./queries";
 
 export function useCreateChatSession() {

packages/core/chat/queries.ts

@@ -1,5 +1,12 @@
 import { queryOptions } from "@tanstack/react-query";
-import { api } from "@multica/core/api";
+import { api } from "../api";
+
+// NOTE on workspace scoping:
+// `wsId` is used only as part of queryKey for cache isolation per workspace.
+// The actual workspace context comes from ApiClient's X-Workspace-ID header,
+// which is set by useWorkspaceStore.switchWorkspace(). Callers must ensure the
+// header is in sync with the wsId they pass here — otherwise cache writes will
+// be misattributed during a workspace switch race window.
 
 export const chatKeys = {
   all: (wsId: string) => ["chat", wsId] as const,