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

.env.example

@@ -29,6 +29,7 @@ RESEND_FROM_EMAIL=noreply@multica.ai
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
 GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
+NEXT_PUBLIC_GOOGLE_CLIENT_ID=
 
 # S3 / CloudFront
 S3_BUCKET=

.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

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+## What
+
+<!-- What does this PR do? Keep it to 1-3 sentences. -->
+
+## Why
+
+<!-- Why is this change needed? Link the related issue. -->
+
+Closes #<!-- issue number -->
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / code improvement
+- [ ] Documentation
+- [ ] CI / infrastructure
+- [ ] Other (describe below)
+
+## How to Test
+
+<!-- How can a reviewer verify this works? Steps, commands, or screenshots. -->
+
+## Checklist
+
+- [ ] `make check` passes (typecheck, unit tests, Go tests, E2E)
+- [ ] Changes follow existing code patterns and conventions
+- [ ] No unrelated changes included
+
+## AI Disclosure (optional)
+
+<!-- If AI tools were used: -->
+<!-- - Which tool? (e.g., Claude Code, Copilot, Cursor) -->
+<!-- - What prompt did you use? Sharing your prompt helps others learn and lets reviewers understand intent. -->

.github/workflows/ci.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.24"
+          go-version: "1.26.1"
           cache-dependency-path: server/go.sum
 
       - name: Build

.gitignore

@@ -36,10 +36,14 @@ apps/web/test-results/
 
 # local settings
 .claude/
+.tool-versions
 
 # 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

@@ -12,119 +12,71 @@ Multica is an AI-native task management platform — like Linear, but with AI ag
 
 ## Architecture
 
-**Go backend + standalone Next.js frontend.**
+**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) — self-contained, no shared package dependencies
+- `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
 
-### Web App Structure (`apps/web/`)
+### Key Architectural Decisions
 
-The frontend uses a **feature-based architecture** with four layers:
+**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.
 
-```
-apps/web/
-├── app/          # Routing layer (thin shells — import from features/)
-├── features/     # Business logic, organized by domain
-├── shared/       # Cross-feature utilities (api client, types, logger)
-```
+**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.
 
-**`app/`** — Next.js App Router pages. Route files should be thin: import and re-export from `features/`. Layout components and route-specific glue (redirects, auth guards) live here. Shared layout components (e.g. `app-sidebar`) stay in `app/(dashboard)/_components/`.
+**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.
 
-**`features/`** — Domain modules, each with its own components, hooks, stores, and config:
-
-| Feature | Purpose | Exports |
-|---|---|---|
-| `features/auth/` | Authentication state | `useAuthStore`, `AuthInitializer` |
-| `features/workspace/` | Workspace, members, agents | `useWorkspaceStore`, `useActorName` |
-| `features/issues/` | Issue state, components, config | `useIssueStore`, icons, pickers, status/priority config |
-| `features/inbox/` | Inbox notification state | `useInboxStore` |
-| `features/realtime/` | WebSocket connection + sync | `WSProvider`, `useWSEvent`, `useRealtimeSync` |
-| `features/modals/` | Modal registry and state | Modal store and components |
-| `features/skills/` | Skill management | Skill components |
-
-**`shared/`** — Code used across multiple features:
-- `shared/api/` — `ApiClient` (REST) and `WSClient` (WebSocket) for backend communication, plus the `api` singleton.
-- `shared/types/` — Domain types (Issue, Agent, Workspace, etc.) and WebSocket event types.
-- `shared/logger.ts` — Logger utility.
+**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
 
-- **Zustand** for global client state — one store per feature domain (`features/auth/store.ts`, `features/workspace/store.ts`, `features/issues/store.ts`, `features/inbox/store.ts`).
-- **React Context** only for connection lifecycle (`WSProvider` in `features/realtime/`).
-- **Local `useState`** for component-scoped UI state (forms, modals, filters).
-- Do not use React Context for data that can be a zustand store.
+The architecture relies on a strict split between server state and client state. Mixing them is the most common way to break it.
 
-**Store conventions:**
-- One store per feature domain. Import via `useAuthStore(selector)` or `useWorkspaceStore(selector)`.
-- Stores must not call `useRouter` or any React hooks — keep navigation in components.
-- Cross-store reads use `useOtherStore.getState()` inside actions (not hooks).
-- Dependency direction: `workspace` → `auth`, `realtime` → `auth`, `issues` → `workspace`. Never reverse.
+- **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.
 
-### Import Aliases
+**Hard rules — these are how the architecture stays coherent:**
 
-Use `@/` alias (maps to `apps/web/`):
-```typescript
-import { api } from "@/shared/api";
-import type { Issue } from "@/shared/types";
-import { useAuthStore } from "@/features/auth";
-import { useWorkspaceStore } from "@/features/workspace";
-import { useIssueStore } from "@/features/issues";
-import { useInboxStore } from "@/features/inbox";
-import { useWSEvent } from "@/features/realtime";
-import { StatusIcon } from "@/features/issues/components";
-```
+- **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.
 
-Within a feature, use relative imports. Between features or to shared, use `@/`.
+**Common Zustand footguns to avoid:**
 
-### Data Flow
-
-```
-Browser → ApiClient (shared/api) → REST API (Chi handlers) → sqlc queries → PostgreSQL
-Browser ← WSClient (shared/api) ← WebSocket ← Hub.Broadcast() ← Handlers/TaskService
-```
-
-### Backend Structure (`server/`)
-
-- **Entry points** (`cmd/`): `server` (HTTP API), `multica` (CLI — daemon, agent management, config), `migrate`
-- **Handlers** (`internal/handler/`): One file per domain (issue, comment, agent, auth, daemon, etc.). Each handler holds `Queries`, `DB`, `Hub`, and `TaskService`.
-- **Real-time** (`internal/realtime/`): Hub manages WebSocket clients. Server broadcasts events; inbound WS message routing is still TODO.
-- **Auth** (`internal/auth/` + `internal/middleware/`): JWT (HS256). Middleware sets `X-User-ID` and `X-User-Email` headers. Login creates user on-the-fly if not found.
-- **Task lifecycle** (`internal/service/task.go`): Orchestrates agent work — enqueue → claim → start → complete/fail. Syncs issue status automatically and broadcasts WS events at each transition.
-- **Agent SDK** (`pkg/agent/`): Unified `Backend` interface for executing prompts via Claude Code or Codex. Each backend spawns its CLI and streams results via `Session.Messages` + `Session.Result` channels.
-- **Daemon** (`internal/daemon/`): Local agent runtime — auto-detects available CLIs (claude, codex), registers runtimes, polls for tasks, routes by provider.
-- **CLI** (`internal/cli/`): Shared helpers for the `multica` CLI — API client, config management, output formatting.
-- **Events** (`internal/events/`): Internal event bus for decoupled communication between handlers and services.
-- **Logging** (`internal/logger/`): Structured logging via slog. `LOG_LEVEL` env var controls level (debug, info, warn, error).
-- **Database**: PostgreSQL with pgvector extension (`pgvector/pgvector:pg17`). sqlc generates Go code from SQL in `pkg/db/queries/` → `pkg/db/generated/`. Migrations in `migrations/`.
-- **Routes** (`cmd/server/router.go`): Public routes (auth, health, ws) + protected routes (require JWT) + daemon routes (unauthenticated, separate auth model).
-
-### Multi-tenancy
-
-All queries filter by `workspace_id`. Membership checks gate access. `X-Workspace-ID` header routes requests to the correct workspace.
-
-### Agent Assignees
-
-Assignees are polymorphic — can be a member or an agent. `assignee_type` + `assignee_id` on issues. Agents render with distinct styling (purple background, robot icon).
+- 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
 make db-down          # Stop the shared PostgreSQL container
 
-# Frontend
+# Frontend (all commands go through Turborepo)
 pnpm install
 pnpm dev:web          # Next.js dev server (port 3000)
-pnpm build            # Build frontend
-pnpm typecheck        # TypeScript check
-pnpm lint             # ESLint via Next.js
-pnpm test             # TS tests (Vitest)
+pnpm dev:desktop      # Electron dev (electron-vite, HMR)
+pnpm build            # Build all frontend apps
+pnpm typecheck        # TypeScript check (all packages + apps via turbo)
+pnpm lint             # ESLint
+pnpm test             # TS tests (Vitest, all packages + apps via turbo)
 
 # Backend (Go)
-make 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")
@@ -133,15 +85,24 @@ make sqlc             # Regenerate sqlc code after editing SQL in server/pkg/db/
 make migrate-up       # Run database migrations
 make migrate-down     # Rollback migrations
 
+# Run a single TS test (works for any package with a test script)
+pnpm --filter @multica/views exec vitest run auth/login-page.test.tsx
+pnpm --filter @multica/core exec vitest run runtimes/version.test.ts
+pnpm --filter @multica/web exec vitest run app/\(auth\)/login/page.test.tsx
+
 # Run a single Go test
 cd server && go test ./internal/handler/ -run TestName
 
-# Run a single TS test
-pnpm --filter @multica/web exec vitest run src/path/to/file.test.ts
-
 # Run a single E2E test (requires backend + frontend running)
 pnpm exec playwright test e2e/tests/specific-test.spec.ts
 
+# Desktop build & package
+pnpm --filter @multica/desktop build      # Compile TS → JS (reads .env.production)
+pnpm --filter @multica/desktop package    # Package into .app/.dmg/.exe (current platform only)
+
+# shadcn — config lives in packages/ui/components.json (Base UI variant, base-nova style)
+pnpm ui:add badge                # Adds component to packages/ui/components/ui/
+
 # Infrastructure
 make db-up            # Start shared PostgreSQL (pgvector/pg17 image)
 make db-down          # Stop shared PostgreSQL
@@ -149,12 +110,14 @@ make db-down          # Stop shared PostgreSQL
 
 ### CI Requirements
 
-CI runs on Node 22 and Go 1.24 with a `pgvector/pgvector:pg17` PostgreSQL service. See `.github/workflows/ci.yml`.
+CI runs on Node 22 and Go 1.26.1 with a `pgvector/pgvector:pg17` PostgreSQL service. See `.github/workflows/ci.yml`.
 
 ### Worktree Support
 
 All checkouts share one PostgreSQL container. Isolation is at the database level — each worktree gets its own DB name and unique ports via `.env.worktree`. Main checkouts use `.env`.
 
+`make dev` auto-detects worktrees and handles everything. For explicit control:
+
 ```bash
 make worktree-env       # Generate .env.worktree with unique DB/ports
 make setup-worktree     # Setup using .env.worktree
@@ -169,43 +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
+
+These are hard constraints. Violating them breaks the cross-platform architecture:
+
+- `packages/core/` — zero react-dom, zero localStorage (use StorageAdapter), zero process.env, zero UI libraries. **All shared Zustand stores live here**, even view-related ones (filters, view modes) — stores are pure state, not UI.
+- `packages/ui/` — zero `@multica/core` imports (pure UI, no business logic).
+- `packages/views/` — zero `next/*` imports, zero `react-router-dom` imports, zero stores. Use `NavigationAdapter` for all routing.
+- `apps/web/platform/` — the only place for Next.js APIs (`next/navigation`).
+- `apps/desktop/src/renderer/src/platform/` — the only place for react-router-dom navigation wiring.
+
+### The No-Duplication Rule
+
+**If the same logic exists in both apps, it must be extracted to a shared package.**
+
+This applies to everything: components, hooks, guards, providers, utility functions. The decision process:
+
+1. Does this code depend on Next.js or Electron APIs? → Keep in the respective app.
+2. Does it depend on `react-router-dom` or `next/navigation`? → Keep in app's `platform/` layer.
+3. Everything else → belongs in `packages/core/` (headless logic) or `packages/views/` (UI components).
+
+When the two apps need different behavior for the same concept (e.g., different loading UI), extract the shared logic into a component with props/slots for the differences. Don't duplicate the logic.
+
+### Cross-Platform Development Rules
+
+When adding a new page or feature:
+
+1. **New page component** → add to `packages/views/<domain>/`. Never import from `next/*` or `react-router-dom`.
+2. **Wire it in both apps** → add a route in `apps/web/app/` (Next.js page file) AND in the desktop router.
+3. **Navigation** → use `useNavigation().push()` or `<AppLink>`. Never use framework-specific link/router APIs in shared code.
+4. **Shared guards/providers** → use `DashboardGuard` from `packages/views/layout/`. Don't create separate guard logic per app.
+5. **Platform-specific UI** → if a feature is web-only or desktop-only, keep it in the respective app. Use props slots (`extra`, `topSlot`) on shared layout components to inject platform-specific UI.
+6. **New hooks that need workspace context** → accept `wsId` as parameter instead of reading from `useWorkspaceId()` Context, so they work both inside and outside `WorkspaceIdProvider`.
+
+### CSS Architecture
+
+Both apps share the same CSS foundation from `packages/ui/styles/`.
+
+- **Design tokens** → use semantic tokens (`bg-background`, `text-muted-foreground`). Never use hardcoded Tailwind colors (`text-red-500`, `bg-gray-100`).
+- **Shared styles** → `packages/ui/styles/`. Never duplicate scrollbar styling, keyframes, or base layer rules in app CSS.
+- **`@source` directives** → both apps scan shared packages so Tailwind sees all class names.
+
 ## UI/UX Rules
 
-- Prefer shadcn components over custom implementations. Install missing components via `npx shadcn add`.
-- **Feature-specific components** → `features/<domain>/components/` — issue icons, pickers, and other domain-bound UI live inside their feature module.
-- Use shadcn design tokens for styling (e.g. `bg-primary`, `text-muted-foreground`, `text-destructive`). Avoid hardcoded color values (e.g. `text-red-500`, `bg-gray-100`).
-- Do not introduce extra state (useState, context, reducers) unless explicitly required by the design. Prefer zustand stores for shared state over React Context.
+- 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
 
@@ -218,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)
 ```
@@ -231,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

@@ -8,7 +8,7 @@ The `multica` CLI connects your local machine to Multica. It handles authenticat
 
 ```bash
 brew tap multica-ai/tap
-brew install multica-cli
+brew install multica
 ```
 
 ### Build from Source
@@ -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.
@@ -289,6 +307,38 @@ multica issue comment add <issue-id> --parent <comment-id> --content "Thanks!"
 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
+```
+
+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
@@ -299,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>
 ```

CLI_INSTALL.md

@@ -0,0 +1,171 @@
+# Multica CLI — Installation Guide for AI Agents
+
+> **Audience:** This document is designed for AI agents (Claude Code, Codex, etc.) to read and execute step-by-step. Each step includes the exact shell commands to run, expected outcomes, and error handling.
+
+## One-Line Instruction for Users
+
+Give this instruction to your AI agent:
+
+```
+Fetch https://github.com/multica-ai/multica/blob/main/CLI_INSTALL.md and follow the instructions to install Multica CLI, log in, and start the daemon on this machine.
+```
+
+---
+
+## Step 1: Check if Multica CLI is already installed
+
+Run:
+
+```bash
+multica version
+```
+
+- **If it prints a version string** (e.g. `multica v0.x.x`): skip to **Step 3**.
+- **If command not found**: continue to **Step 2**.
+
+---
+
+## Step 2: Install the Multica CLI
+
+### Option A: Homebrew (preferred)
+
+Check if Homebrew is available:
+
+```bash
+which brew
+```
+
+If `brew` is found, install via Homebrew:
+
+```bash
+brew tap multica-ai/tap && brew install multica
+```
+
+Then verify:
+
+```bash
+multica version
+```
+
+If the version prints successfully, skip to **Step 3**.
+
+### Option B: Download from GitHub Releases (no Homebrew)
+
+If Homebrew is not available, download the binary directly.
+
+Detect OS and architecture, then download the correct archive:
+
+```bash
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')   # "darwin" or "linux"
+ARCH=$(uname -m)                                # "x86_64" or "arm64"
+
+# Normalize architecture name
+if [ "$ARCH" = "x86_64" ]; then
+  ARCH="amd64"
+fi
+
+# Get the latest release tag from GitHub
+LATEST=$(curl -sI https://github.com/multica-ai/multica/releases/latest | grep -i '^location:' | sed 's/.*tag\///' | tr -d '\r\n')
+
+# Download and extract
+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
+```
+
+Verify:
+
+```bash
+multica version
+```
+
+**If this fails:**
+- Check that `/usr/local/bin` is in `$PATH`.
+- On Linux, you may need `chmod +x /usr/local/bin/multica`.
+- If `sudo` is not available, install to a user-writable directory: `mv /tmp/multica ~/.local/bin/multica` and ensure `~/.local/bin` is in `$PATH`.
+
+---
+
+## Step 3: Log in
+
+Run:
+
+```bash
+multica login
+```
+
+**Important:** This command opens a browser window for OAuth authentication. Tell the user:
+
+> "A browser window will open for Multica login. Please complete the authentication in your browser, then come back here."
+
+Wait for the command to complete. It will automatically discover and watch all workspaces the user belongs to.
+
+Verify:
+
+```bash
+multica auth status
+```
+
+Expected output should show the authenticated user and server URL.
+
+**If login fails:**
+- If no browser is available (headless environment), the user can generate a Personal Access Token at `https://app.multica.ai/settings` and run: `multica login --token`
+- If the server URL needs to be customized: `multica config set server_url <url>` before logging in.
+
+---
+
+## Step 4: Start the daemon
+
+First, check if the daemon is already running:
+
+```bash
+multica daemon status
+```
+
+- **If status is "running"**: skip to **Step 5**.
+- **If status is "stopped"**: start it:
+
+```bash
+multica daemon start
+```
+
+Wait 3 seconds, then verify:
+
+```bash
+multica daemon status
+```
+
+Expected output should show `running` status with detected agents (e.g. `claude`, `codex`).
+
+**If daemon fails to start:**
+- Check logs: `multica daemon logs`
+- If a port conflict occurs, the daemon may already be running under a different profile.
+- If no agents are detected, ensure at least one AI CLI (`claude` or `codex`) is installed and on the `$PATH`.
+
+---
+
+## Step 5: Verify everything is working
+
+Run:
+
+```bash
+multica daemon status
+```
+
+Confirm:
+1. Status is `running`
+2. At least one agent is listed (e.g. `claude`, `codex`)
+3. At least one workspace is being watched
+
+If the agents list is empty, tell the user:
+
+> "The Multica daemon is running but no AI agent CLIs were detected. Please install at least one: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`) or [Codex](https://github.com/openai/codex) (`codex`), then restart the daemon with `multica daemon stop && multica daemon start`."
+
+---
+
+## Summary
+
+When all steps are complete, inform the user:
+
+> "Multica CLI is installed and the daemon is running. Agents in your workspaces can now execute tasks on this machine. You can manage workspaces with `multica workspace list` and view daemon logs with `multica daemon logs -f`."

CONTRIBUTING.md

@@ -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"]

LICENSE

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

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
@@ -69,7 +116,12 @@ stop:
 	@echo "Stopping services..."
 	@-lsof -ti:$(PORT) | xargs kill -9 2>/dev/null
 	@-lsof -ti:$(FRONTEND_PORT) | xargs kill -9 2>/dev/null
-	@echo "✓ App processes stopped. Shared PostgreSQL is still running on localhost:5432."
+	@case "$(DATABASE_URL)" in \
+		""|*@localhost:*|*@localhost/*|*@127.0.0.1:*|*@127.0.0.1/*|*@\[::1\]:*|*@\[::1\]/*) \
+			echo "✓ App processes stopped. Shared PostgreSQL is still running on localhost:$(POSTGRES_PORT)." ;; \
+		*) \
+			echo "✓ App processes stopped. Remote PostgreSQL was not affected." ;; \
+	esac
 
 # Full verification: typecheck + unit tests + Go tests + E2E
 check:
@@ -98,8 +150,12 @@ check-main:
 	@ENV_FILE=$(MAIN_ENV_FILE) bash scripts/check.sh
 
 setup-worktree:
-	@echo "==> Generating $(WORKTREE_ENV_FILE) with unique ports..."
-	@FORCE=1 bash scripts/init-worktree-env.sh $(WORKTREE_ENV_FILE)
+	@if [ ! -f "$(WORKTREE_ENV_FILE)" ]; then \
+		echo "==> Generating $(WORKTREE_ENV_FILE) with unique ports..."; \
+		bash scripts/init-worktree-env.sh $(WORKTREE_ENV_FILE); \
+	else \
+		echo "==> Using existing $(WORKTREE_ENV_FILE)"; \
+	fi
 	@$(MAKE) setup ENV_FILE=$(WORKTREE_ENV_FILE)
 
 start-worktree:
@@ -113,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
@@ -130,14 +190,17 @@ 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:
 	$(REQUIRE_ENV)
 	@bash scripts/ensure-postgres.sh "$(ENV_FILE)"
+	cd server && go run ./cmd/migrate up
 	cd server && go test ./...
 
 # Database

README.md

@@ -1,60 +1,126 @@
+<p align="center">
+  <img src="docs/assets/banner.jpg" alt="Multica — humans and agents, side by side" width="100%">
+</p>
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
+  <img alt="Multica" src="docs/assets/logo-light.svg" width="50">
+</picture>
+
 # Multica
 
-AI-native project management — like Linear, but with AI agents as first-class team members.
+**Your next 10 hires won't be human.**
 
-Multica lets you manage tasks and collaborate with AI agents the same way you work with human teammates. Agents can be assigned issues, post comments, update statuses, and execute work autonomously on your local machine.
+The open-source managed agents platform.<br/>
+Turn coding agents into real teammates — assign tasks, track progress, compound skills.
+
+[![CI](https://github.com/multica-ai/multica/actions/workflows/ci.yml/badge.svg)](https://github.com/multica-ai/multica/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![GitHub stars](https://img.shields.io/github/stars/multica-ai/multica?style=flat)](https://github.com/multica-ai/multica/stargazers)
+
+[Website](https://multica.ai) · [Cloud](https://multica.ai/app) · [X](https://x.com/multica_hq) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
+
+**English | [简体中文](README.zh-CN.md)**
+
+</div>
+
+## 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**.
+
+<p align="center">
+  <img src="docs/assets/hero-screenshot.png" alt="Multica board view" width="800">
+</p>
 
 ## Features
 
-- **AI agents as teammates** — assign issues to agents, mention them in comments, and let them do the work
-- **Local agent runtime** — agents run on your machine using Claude Code or Codex, with full access to your codebase
-- **Real-time collaboration** — WebSocket-powered live updates across the board
-- **Multi-workspace** — organize work across teams with workspace-level isolation
-- **Familiar UX** — if you've used Linear, you'll feel right at home
+Multica manages the full agent lifecycle: from task assignment to execution monitoring to skill reuse.
+
+- **Agents as Teammates** — assign to an agent like you'd assign to a colleague. They have profiles, show up on the board, post comments, create issues, and report blockers proactively.
+- **Autonomous Execution** — set it and forget it. Full task lifecycle management (enqueue, claim, start, complete/fail) with real-time progress streaming via WebSocket.
+- **Reusable Skills** — every solution becomes a reusable skill for the whole team. Deployments, migrations, code reviews — skills compound your team's capabilities over time.
+- **Unified Runtimes** — one dashboard for all your compute. Local daemons and cloud runtimes, auto-detection of available CLIs, real-time monitoring.
+- **Multi-Workspace** — organize work across teams with workspace-level isolation. Each workspace has its own agents, issues, and settings.
+
+---
+
+## Quick Install
+
+```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
 
-### Use Multica Cloud
-
-The fastest way to get started: [multica.ai](https://multica.ai)
-
-### Self-Host
-
-Run Multica on your own infrastructure. See the [Self-Hosting Guide](SELF_HOSTING.md) for full instructions.
-
-Quick start with Docker:
+### 1. Log in and start the daemon
 
 ```bash
-git clone https://github.com/multica-ai/multica.git
-cd multica
-cp .env.example .env
-# Edit .env — at minimum, change JWT_SECRET
-
-# Start PostgreSQL
-docker compose up -d
-
-# Build and run the backend
-cd server && go run ./cmd/migrate up && cd ..
-make start
+multica login           # Authenticate with your Multica account
+multica daemon start    # Start the local agent runtime
 ```
 
+The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `openclaw`, `opencode`) 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.
+
+---
+
 ## CLI
 
 The `multica` CLI connects your local machine to Multica — authenticate, manage workspaces, and run the agent daemon.
 
-```bash
-# Install
-brew tap multica-ai/tap
-brew install multica
+| 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 |
 
-# Authenticate and start
-multica login
-multica daemon start
-```
+See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference.
 
-The daemon auto-detects available agent CLIs (`claude`, `codex`) on your PATH. When an agent is assigned a task, the daemon creates an isolated environment, runs the agent, and reports results back.
-
-See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference, daemon configuration, and advanced usage.
+---
 
 ## Architecture
 
@@ -66,37 +132,28 @@ See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference
                             │
                      ┌──────┴───────┐
                      │ Agent Daemon │  (runs on your machine)
-                     │ Claude/Codex │
+                     │Claude/Codex/ │
+                     │OpenClaw/Code │
                      └──────────────┘
 ```
 
-- **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 or Codex
+| 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 |
 
 ## Development
 
 For contributors working on the Multica codebase, see the [Contributing Guide](CONTRIBUTING.md).
 
-### Prerequisites
-
-- [Node.js](https://nodejs.org/) (v20+)
-- [pnpm](https://pnpm.io/) (v10.28+)
-- [Go](https://go.dev/) (v1.26+)
-- [Docker](https://www.docker.com/)
-
-### Quick Start
+**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.
-
-## License
-
-See [LICENSE](LICENSE) for details.

README.zh-CN.md

@@ -0,0 +1,146 @@
+<p align="center">
+  <img src="docs/assets/banner.jpg" alt="Multica — 人类与 AI，并肩前行" width="100%">
+</p>
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
+  <img alt="Multica" src="docs/assets/logo-light.svg" width="50">
+</picture>
+
+# Multica
+
+**你的下一批员工，不是人类。**
+
+开源的 Managed Agents 平台。<br/>
+将编码 Agent 变成真正的队友——分配任务、跟踪进度、积累技能。
+
+[![CI](https://github.com/multica-ai/multica/actions/workflows/ci.yml/badge.svg)](https://github.com/multica-ai/multica/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![GitHub stars](https://img.shields.io/github/stars/multica-ai/multica?style=flat)](https://github.com/multica-ai/multica/stargazers)
+
+[官网](https://multica.ai) · [云服务](https://multica.ai/app) · [X](https://x.com/multica_hq) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
+
+**[English](README.md) | 简体中文**
+
+</div>
+
+## Multica 是什么？
+
+Multica 将编码 Agent 变成真正的队友。像分配给同事一样分配给 Agent——它们会自主接手工作、编写代码、报告阻塞问题、更新状态。
+
+不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**OpenClaw** 和 **OpenCode**。
+
+<p align="center">
+  <img src="docs/assets/hero-screenshot.png" alt="Multica 看板视图" width="800">
+</p>
+
+## 功能特性
+
+Multica 管理完整的 Agent 生命周期：从任务分配到执行监控再到技能复用。
+
+- **Agent 即队友** — 像分配给同事一样分配给 Agent。它们有个人档案、出现在看板上、发表评论、创建 Issue、主动报告阻塞问题。
+- **自主执行** — 设置后无需管理。完整的任务生命周期管理（排队、认领、执行、完成/失败），通过 WebSocket 实时推送进度。
+- **可复用技能** — 每个解决方案都成为全团队可复用的技能。部署、数据库迁移、代码审查——技能让团队能力随时间持续增长。
+- **统一运行时** — 一个控制台管理所有算力。本地 daemon 和云端运行时，自动检测可用 CLI，实时监控。
+- **多工作区** — 按团队组织工作，工作区级别隔离。每个工作区有独立的 Agent、Issue 和设置。
+
+---
+
+## 快速安装
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
+```
+
+安装 Multica CLI，支持 macOS 和 Linux。有 Homebrew 用 Homebrew，没有则直接下载二进制。
+
+安装完成后：
+
+```bash
+multica login          # 认证（打开浏览器）
+multica daemon start   # 启动本地 Agent 运行时
+multica daemon stop    # 停止 daemon
+```
+
+> **自部署？** 加上 `--local` 在本地部署完整的 Multica 服务：
+>
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --local
+> ```
+>
+> 需要 Docker。详见 [自部署指南](SELF_HOSTING.md)。
+
+---
+
+## 快速上手
+
+安装好 CLI（或注册 [Multica 云服务](https://multica.ai)）后，按以下步骤将第一个任务分配给 Agent：
+
+### 1. 登录并启动 daemon
+
+```bash
+multica login           # 使用你的 Multica 账号认证
+multica daemon start    # 启动本地 Agent 运行时
+```
+
+daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`openclaw`、`opencode`）。
+
+### 2. 确认运行时已连接
+
+在 Multica Web 端打开你的工作区，进入 **设置 → 运行时（Runtimes）**，你应该能看到你的机器已作为一个活跃的 **Runtime** 出现在列表中。
+
+> **什么是 Runtime（运行时）？** Runtime 是可以执行 Agent 任务的计算环境。它可以是你的本地机器（通过 daemon 连接），也可以是云端实例。每个 Runtime 会上报可用的 Agent CLI，Multica 据此决定将任务路由到哪里执行。
+
+### 3. 创建 Agent
+
+进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、OpenClaw 或 OpenCode），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
+
+### 4. 分配你的第一个任务
+
+在看板上创建一个 Issue（或通过 `multica issue create` 命令创建），然后将其分配给你的新 Agent。Agent 会自动接手任务、在你的 Runtime 上执行、并实时汇报进度——就像一个真正的队友一样。
+
+大功告成！你的 Agent 现在是团队的一员了。 🎉
+
+## 架构
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
+│   Next.js    │────>│  Go 后端     │────>│   PostgreSQL     │
+│   前端       │<────│  (Chi + WS)  │<────│   (pgvector)     │
+└──────────────┘     └──────┬───────┘     └──────────────────┘
+                            │
+                     ┌──────┴───────┐
+                     │ Agent Daemon │  （运行在你的机器上）
+                     │Claude/Codex/ │
+                     │OpenClaw/Code │
+                     └──────────────┘
+```
+
+| 层级 | 技术栈 |
+|------|--------|
+| 前端 | Next.js 16 (App Router) |
+| 后端 | Go (Chi router, sqlc, gorilla/websocket) |
+| 数据库 | PostgreSQL 17 with pgvector |
+| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、OpenClaw 或 OpenCode |
+
+## 开发
+
+参与 Multica 代码贡献，请参阅 [贡献指南](CONTRIBUTING.md)。
+
+**环境要求：** [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
+```
+
+完整的开发流程、worktree 支持、测试和问题排查请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+## 开源协议
+
+[Apache 2.0](LICENSE)

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,250 +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
-   export MULTICA_APP_URL=https://app.example.com
-   export MULTICA_SERVER_URL=wss://api.example.com/ws
-
-   # Login (opens browser)
-   multica login
-
-   # Start the daemon
-   multica daemon start
-   ```
-
-The daemon auto-detects installed agent CLIs and registers itself with the server. When an agent is assigned a task in Multica, the daemon picks it up, creates an isolated workspace, runs the agent, and reports results back.
-
-## Upgrading
-
-1. Pull the latest code or image
-2. Run migrations: `./server/bin/migrate up`
-3. Restart the backend and frontend
-
-Migrations are forward-only and safe to run on a live database. They are idempotent — running them multiple times has no effect.
+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/.gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+out
+.DS_Store
+.eslintcache
+*.log*

apps/desktop/electron-builder.yml

@@ -0,0 +1,31 @@
+appId: ai.multica.desktop
+productName: Multica
+directories:
+  buildResources: build
+files:
+  - "!**/.vscode/*"
+  - "!src/*"
+  - "!electron.vite.config.*"
+  - "!{.eslintignore,.eslintrc.cjs,.prettierignore,.prettierrc.yaml,dev-app-update.yml,CHANGELOG.md,README.md}"
+  - "!{tsconfig.json,tsconfig.node.json,tsconfig.web.json}"
+asarUnpack:
+  - resources/**
+mac:
+  entitlementsInherit: build/entitlements.mac.plist
+  target:
+    - dmg
+    - zip
+  artifactName: ${name}-${version}-${arch}.${ext}
+  notarize: false
+dmg:
+  artifactName: ${name}-${version}.${ext}
+linux:
+  target:
+    - AppImage
+    - deb
+  artifactName: ${name}-${version}-${arch}.${ext}
+win:
+  target:
+    - nsis
+  artifactName: ${name}-${version}-setup.${ext}
+npmRebuild: false

apps/desktop/electron.vite.config.ts

@@ -0,0 +1,26 @@
+import { resolve } from "path";
+import { defineConfig, externalizeDepsPlugin } from "electron-vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  main: {
+    plugins: [externalizeDepsPlugin()],
+  },
+  preload: {
+    plugins: [externalizeDepsPlugin()],
+  },
+  renderer: {
+    server: {
+      port: 5173,
+      strictPort: true,
+    },
+    plugins: [react(), tailwindcss()],
+    resolve: {
+      alias: {
+        "@": resolve("src/renderer/src"),
+      },
+      dedupe: ["react", "react-dom"],
+    },
+  },
+});

apps/desktop/eslint.config.mjs

@@ -0,0 +1,6 @@
+import reactConfig from "@multica/eslint-config/react";
+
+export default [
+  ...reactConfig,
+  { ignores: ["out/", "dist/"] },
+];

apps/desktop/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@multica/desktop",
+  "version": "0.1.0",
+  "private": true,
+  "main": "./out/main/index.js",
+  "scripts": {
+    "dev": "electron-vite dev",
+    "build": "electron-vite build",
+    "typecheck:node": "tsc --noEmit -p tsconfig.node.json --composite false",
+    "typecheck:web": "tsc --noEmit -p tsconfig.web.json --composite false",
+    "typecheck": "pnpm run typecheck:node && pnpm run typecheck:web",
+    "preview": "electron-vite preview",
+    "package": "electron-builder",
+    "lint": "eslint .",
+    "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": {
+    "@electron-toolkit/tsconfig": "^2.0.0",
+    "@multica/tsconfig": "workspace:*",
+    "@tailwindcss/vite": "^4",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "@vitejs/plugin-react": "^5.1.1",
+    "electron": "^39.2.6",
+    "electron-builder": "^26.0.12",
+    "electron-vite": "^5.0.0",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "tailwindcss": "^4",
+    "typescript": "catalog:"
+  }
+}

apps/desktop/src/main/index.ts

@@ -0,0 +1,56 @@
+import { app, shell, BrowserWindow } from "electron";
+import { join } from "path";
+import { electronApp, optimizer, is } from "@electron-toolkit/utils";
+
+let mainWindow: BrowserWindow | null = null;
+
+function createWindow(): void {
+  mainWindow = new BrowserWindow({
+    width: 1280,
+    height: 800,
+    minWidth: 900,
+    minHeight: 600,
+    titleBarStyle: "hiddenInset",
+    trafficLightPosition: { x: 16, y: 13 },
+    show: false,
+    autoHideMenuBar: true,
+    webPreferences: {
+      preload: join(__dirname, "../preload/index.js"),
+      sandbox: false,
+      webSecurity: false,
+    },
+  });
+
+  mainWindow.on("ready-to-show", () => {
+    mainWindow?.show();
+  });
+
+  mainWindow.webContents.setWindowOpenHandler((details) => {
+    shell.openExternal(details.url);
+    return { action: "deny" };
+  });
+
+  if (is.dev && process.env["ELECTRON_RENDERER_URL"]) {
+    mainWindow.loadURL(process.env["ELECTRON_RENDERER_URL"]);
+  } else {
+    mainWindow.loadFile(join(__dirname, "../renderer/index.html"));
+  }
+}
+
+app.whenReady().then(() => {
+  electronApp.setAppUserModelId("ai.multica.desktop");
+
+  app.on("browser-window-created", (_, window) => {
+    optimizer.watchWindowShortcuts(window);
+  });
+
+  createWindow();
+
+  app.on("activate", () => {
+    if (BrowserWindow.getAllWindows().length === 0) createWindow();
+  });
+});
+
+app.on("window-all-closed", () => {
+  if (process.platform !== "darwin") app.quit();
+});

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

@@ -0,0 +1,9 @@
+import { ElectronAPI } from "@electron-toolkit/preload";
+
+declare global {
+  interface Window {
+    electron: ElectronAPI;
+  }
+}
+
+export {};

apps/desktop/src/preload/index.ts

@@ -0,0 +1,9 @@
+import { contextBridge } from "electron";
+import { electronAPI } from "@electron-toolkit/preload";
+
+if (process.contextIsolated) {
+  contextBridge.exposeInMainWorld("electron", electronAPI);
+} else {
+  // @ts-expect-error - fallback for non-isolated context
+  window.electron = electronAPI;
+}

apps/desktop/src/renderer/index.html

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

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

@@ -0,0 +1,37 @@
+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 { 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 (
+    <ThemeProvider>
+      <CoreProvider
+        apiBaseUrl={import.meta.env.VITE_API_URL || "http://localhost:8080"}
+        wsUrl={import.meta.env.VITE_WS_URL || "ws://localhost:8080/ws"}
+      >
+        <AppContent />
+      </CoreProvider>
+      <Toaster />
+    </ThemeProvider>
+  );
+}

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

@@ -0,0 +1,102 @@
+import { useEffect } from "react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+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 { ModalRegistry } from "@multica/views/modals/registry";
+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 } = useTabHistory();
+
+  return (
+    <div
+      className="h-12 shrink-0 flex items-center justify-end px-2"
+      style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
+    >
+      <div
+        className="flex items-center gap-0.5"
+        style={{ WebkitAppRegion: "no-drag" } as React.CSSProperties}
+      >
+        <button
+          onClick={goBack}
+          disabled={!canGoBack}
+          className="flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-30 disabled:pointer-events-none"
+        >
+          <ChevronLeft className="size-4" />
+        </button>
+        <button
+          onClick={goForward}
+          disabled={!canGoForward}
+          className="flex size-7 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:opacity-30 disabled:pointer-events-none"
+        >
+          <ChevronRight className="size-4" />
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function useInternalLinkHandler() {
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const path = (e as CustomEvent).detail?.path;
+      if (!path) return;
+      const icon = resolveRouteIcon(path);
+      const store = useTabStore.getState();
+      const tabId = store.openTab(path, path, icon);
+      store.setActiveTab(tabId);
+    };
+    window.addEventListener("multica:navigate", handler);
+    return () => window.removeEventListener("multica:navigate", handler);
+  }, []);
+}
+
+export function DesktopShell() {
+  useInternalLinkHandler();
+  useActiveTitleSync();
+
+  return (
+    <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>
+        <ModalRegistry />
+        <SearchCommand />
+        <ChatWindow />
+        <ChatFab />
+      </DashboardGuard>
+    </DesktopNavigationProvider>
+  );
+}

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

@@ -0,0 +1,188 @@
+import {
+  Inbox,
+  CircleUser,
+  ListTodo,
+  Bot,
+  Monitor,
+  BookOpenText,
+  Settings,
+  X,
+  Plus,
+  type LucideIcon,
+} from "lucide-react";
+import {
+  DndContext,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  closestCenter,
+  type DragEndEvent,
+} from "@dnd-kit/core";
+import {
+  SortableContext,
+  horizontalListSortingStrategy,
+  useSortable,
+} from "@dnd-kit/sortable";
+import {
+  restrictToHorizontalAxis,
+  restrictToParentElement,
+} from "@dnd-kit/modifiers";
+import { CSS } from "@dnd-kit/utilities";
+import { cn } from "@multica/ui/lib/utils";
+import { useTabStore, resolveRouteIcon, type Tab } from "@/stores/tab-store";
+
+const TAB_ICONS: Record<string, LucideIcon> = {
+  Inbox,
+  CircleUser,
+  ListTodo,
+  Bot,
+  Monitor,
+  BookOpenText,
+  Settings,
+};
+
+function SortableTabItem({ tab, isActive, isOnly }: { tab: Tab; isActive: boolean; isOnly: boolean }) {
+  const setActiveTab = useTabStore((s) => s.setActiveTab);
+  const closeTab = useTabStore((s) => s.closeTab);
+
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id: tab.id });
+
+  const Icon = TAB_ICONS[tab.icon];
+
+  const style = {
+    transform: CSS.Transform.toString(transform),
+    transition,
+    WebkitAppRegion: "no-drag",
+    zIndex: isDragging ? 10 : undefined,
+  } as React.CSSProperties;
+
+  const handleClick = () => {
+    if (isActive) return;
+    setActiveTab(tab.id);
+    // No navigate() — Activity handles visibility
+  };
+
+  const handleClose = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    closeTab(tab.id);
+    // No navigate() — store handles activeTabId switch
+  };
+
+  // Stop pointer down on close so it doesn't start a drag on the parent button.
+  const stopDragOnClose = (e: React.PointerEvent) => {
+    e.stopPropagation();
+  };
+
+  return (
+    <button
+      ref={setNodeRef}
+      style={style}
+      {...attributes}
+      {...listeners}
+      onClick={handleClick}
+      className={cn(
+        "group flex h-7 w-40 items-center gap-1.5 rounded-md px-2 text-xs transition-colors",
+        "select-none cursor-default",
+        isActive
+          ? "bg-sidebar-accent font-medium text-sidebar-accent-foreground"
+          : "bg-sidebar-accent/50 text-muted-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+        isDragging && "opacity-60",
+      )}
+    >
+      {Icon && <Icon className="size-3.5 shrink-0" />}
+      <span
+        className="min-w-0 flex-1 overflow-hidden whitespace-nowrap text-left"
+        style={{
+          maskImage: "linear-gradient(to right, black calc(100% - 12px), transparent)",
+          WebkitMaskImage: "linear-gradient(to right, black calc(100% - 12px), transparent)",
+        }}
+      >
+        {tab.title}
+      </span>
+      {!isOnly && (
+        <span
+          onClick={handleClose}
+          onPointerDown={stopDragOnClose}
+          className="hidden size-3.5 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors group-hover:flex hover:bg-muted-foreground/20 hover:text-foreground"
+        >
+          <X className="size-2.5" />
+        </span>
+      )}
+    </button>
+  );
+}
+
+function NewTabButton() {
+  const addTab = useTabStore((s) => s.addTab);
+  const setActiveTab = useTabStore((s) => s.setActiveTab);
+
+  const handleClick = () => {
+    const path = "/issues";
+    const tabId = addTab(path, "Issues", resolveRouteIcon(path));
+    setActiveTab(tabId);
+    // 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" />
+    </button>
+  );
+}
+
+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">
+      <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/env.d.ts

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

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

@@ -0,0 +1,24 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@multica/ui/styles/tokens.css";
+@import "@multica/ui/styles/base.css";
+
+@custom-variant dark (&:is(.dark *));
+
+/* 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}";
+@source "./**/*.tsx";
+
+/* Desktop-specific: override sidebar container padding for traffic light layout */
+[data-slot="sidebar-container"] {
+  padding: 0 !important;
+}

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

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

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

@@ -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

@@ -0,0 +1,29 @@
+import { useEffect } from "react";
+import { useTabStore } from "@/stores/tab-store";
+
+/**
+ * Watches document.title via MutationObserver and updates the active tab's title.
+ *
+ * Pages set document.title via TitleSync (route handle.title) or useDocumentTitle().
+ * This observer picks up the change and syncs it to the tab store.
+ */
+export function useActiveTitleSync() {
+  useEffect(() => {
+    const observer = new MutationObserver(() => {
+      const title = document.title;
+      if (!title) return;
+      const { tabs, activeTabId } = useTabStore.getState();
+      const activeTab = tabs.find((t) => t.id === activeTabId);
+      if (activeTab && activeTab.title !== title) {
+        useTabStore.getState().updateTab(activeTabId, { title });
+      }
+    });
+
+    const titleEl = document.querySelector("title");
+    if (titleEl) {
+      observer.observe(titleEl, { childList: true, characterData: true, subtree: true });
+    }
+
+    return () => observer.disconnect();
+  }, []);
+}

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

@@ -0,0 +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/issue-detail-page.tsx

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

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

@@ -0,0 +1,20 @@
+import { LoginPage } from "@multica/views/auth";
+import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
+
+export function DesktopLoginPage() {
+  return (
+    <div className="flex h-screen flex-col">
+      {/* Traffic light inset */}
+      <div
+        className="h-[38px] shrink-0"
+        style={{ WebkitAppRegion: "drag" } as React.CSSProperties}
+      />
+      <LoginPage
+        logo={<MulticaIcon bordered size="lg" />}
+        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

@@ -0,0 +1,116 @@
+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 activeTab = useTabStore((s) => s.tabs.find((t) => t.id === s.activeTabId));
+  const [pathname, setPathname] = useState(activeTab?.path ?? "/issues");
+
+  // Subscribe to the active tab's router for pathname updates
+  useEffect(() => {
+    if (!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/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

@@ -0,0 +1,195 @@
+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
+// ---------------------------------------------------------------------------
+
+export interface Tab {
+  id: string;
+  path: string;
+  title: string;
+  icon: string;
+  router: DataRouter;
+  historyIndex: number;
+  historyLength: number;
+}
+
+interface TabStore {
+  tabs: Tab[];
+  activeTabId: string;
+
+  /** Open a background tab. Deduplicates by path. Returns the tab id. */
+  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. Disposes router. */
+  closeTab: (tabId: string) => void;
+  /** Switch to a tab by id. */
+  setActiveTab: (tabId: 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;
+}
+
+// ---------------------------------------------------------------------------
+// Route → icon mapping (title comes from document.title, not from here)
+// ---------------------------------------------------------------------------
+
+const ROUTE_ICONS: Record<string, string> = {
+  "/inbox": "Inbox",
+  "/my-issues": "CircleUser",
+  "/issues": "ListTodo",
+  "/projects": "FolderKanban",
+  "/agents": "Bot",
+  "/runtimes": "Monitor",
+  "/skills": "BookOpenText",
+  "/settings": "Settings",
+};
+
+/** 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" : undefined)
+    ?? (pathname.startsWith("/projects/") ? "FolderKanban" : undefined)
+    ?? "ListTodo";
+}
+
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+
+const DEFAULT_PATH = "/issues";
+
+function createId(): string {
+  return crypto.randomUUID();
+}
+
+function makeTab(path: string, title: string, icon: string): Tab {
+  return {
+    id: createId(),
+    path,
+    title,
+    icon,
+    router: createTabRouter(path),
+    historyIndex: 0,
+    historyLength: 1,
+  };
+}
+
+const initialTab = makeTab(DEFAULT_PATH, "Issues", resolveRouteIcon(DEFAULT_PATH));
+
+export const useTabStore = create<TabStore>()(
+  persist(
+    (set, get) => ({
+  tabs: [initialTab],
+  activeTabId: initialTab.id,
+
+  openTab(path, title, icon) {
+    const { tabs } = get();
+    const existing = tabs.find((t) => t.path === path);
+    if (existing) return existing.id;
+
+    const tab = makeTab(path, title, icon);
+    set({ tabs: [...tabs, tab] });
+    return tab.id;
+  },
+
+  addTab(path, title, icon) {
+    const tab = makeTab(path, title, icon);
+    set((s) => ({ tabs: [...s.tabs, tab] }));
+    return tab.id;
+  },
+
+  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) {
+      closingTab?.router.dispose();
+      const fresh = makeTab(DEFAULT_PATH, "Issues", resolveRouteIcon(DEFAULT_PATH));
+      set({ tabs: [fresh], activeTabId: fresh.id });
+      return;
+    }
+
+    const idx = tabs.findIndex((t) => t.id === tabId);
+    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 });
+    } else {
+      set({ tabs: next });
+    }
+  },
+
+  setActiveTab(tabId) {
+    set({ activeTabId: tabId });
+  },
+
+  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/desktop/tsconfig.json

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

apps/desktop/tsconfig.node.json

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

apps/desktop/tsconfig.web.json

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

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,35 +2,54 @@ 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("@/features/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("@/features/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("@/shared/api", () => ({
+vi.mock("@multica/core/api", () => ({
   api: {
     listWorkspaces: vi.fn().mockResolvedValue([]),
     verifyCode: vi.fn(),
@@ -49,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("AI-native task management")).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,328 +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 "@/features/auth";
-import { useWorkspaceStore } from "@/features/workspace";
-import { api } from "@/shared/api";
-import {
-  Card,
-  CardHeader,
-  CardTitle,
-  CardDescription,
-  CardContent,
-  CardFooter,
-} from "@/components/ui/card";
-import { Input } from "@/components/ui/input";
-import { Button } from "@/components/ui/button";
-import { Label } from "@/components/ui/label";
-import {
-  InputOTP,
-  InputOTPGroup,
-  InputOTPSlot,
-} from "@/components/ui/input-otp";
-import type { User } from "@/shared/types";
+import { useAuthStore } from "@multica/core/auth";
+import { setLoggedInCookie } from "@/features/auth/auth-cookie";
+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);
-          const cliState = searchParams.get("cli_state") || "";
-          redirectToCliCallback(cliCallback, token, cliState);
-          return;
-        }
-
-        await verifyCode(email, value);
-        const wsList = await api.listWorkspaces();
-        await hydrateWorkspace(wsList);
-        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 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>AI-native task management</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>
-          <Button
-            type="submit"
-            form="login-form"
-            disabled={submitting}
-            className="w-full"
-            size="lg"
-          >
-            {submitting ? "Sending code..." : "Continue"}
-          </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)/_components/app-sidebar.tsx

@@ -1,227 +0,0 @@
-"use client";
-
-import Link from "next/link";
-import { usePathname, useRouter } from "next/navigation";
-import {
-  Inbox,
-  ListTodo,
-  Bot,
-  Monitor,
-  ChevronDown,
-  Settings,
-  LogOut,
-  Plus,
-  Check,
-  BookOpenText,
-  SquarePen,
-  CircleUser,
-} from "lucide-react";
-import { WorkspaceAvatar } from "@/features/workspace";
-import { useIssueDraftStore } from "@/features/issues/stores/draft-store";
-import {
-  Sidebar,
-  SidebarContent,
-  SidebarGroup,
-  SidebarGroupContent,
-  SidebarHeader,
-  SidebarFooter,
-  SidebarMenu,
-  SidebarMenuButton,
-  SidebarMenuItem,
-  SidebarRail,
-} from "@/components/ui/sidebar";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuGroup,
-  DropdownMenuItem,
-  DropdownMenuLabel,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
-import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip";
-import { useAuthStore } from "@/features/auth";
-import { useWorkspaceStore } from "@/features/workspace";
-import { useInboxStore } from "@/features/inbox";
-import { useModalStore } from "@/features/modals";
-
-const primaryNav = [
-  { href: "/inbox", label: "Inbox", icon: Inbox },
-  { href: "/my-issues", label: "My Issues", icon: CircleUser },
-  { href: "/issues", label: "Issues", icon: ListTodo },
-];
-
-const workspaceNav = [
-  { href: "/agents", label: "Agents", icon: Bot },
-  { href: "/runtimes", label: "Runtimes", icon: Monitor },
-  { href: "/skills", label: "Skills", icon: BookOpenText },
-  { href: "/settings", label: "Settings", icon: Settings },
-];
-
-function DraftDot() {
-  const hasDraft = useIssueDraftStore((s) => !!(s.draft.title || s.draft.description));
-  if (!hasDraft) return null;
-  return <span className="absolute top-0 right-0 size-1.5 rounded-full bg-brand" />;
-}
-
-export function AppSidebar() {
-  const pathname = usePathname();
-  const router = useRouter();
-  const user = useAuthStore((s) => s.user);
-  const authLogout = useAuthStore((s) => s.logout);
-  const workspace = useWorkspaceStore((s) => s.workspace);
-  const workspaces = useWorkspaceStore((s) => s.workspaces);
-  const switchWorkspace = useWorkspaceStore((s) => s.switchWorkspace);
-
-  const unreadCount = useInboxStore((s) => s.unreadCount());
-
-  const logout = () => {
-    router.push("/");
-    authLogout();
-    useWorkspaceStore.getState().clearWorkspace();
-  };
-
-  return (
-      <Sidebar variant="inset">
-        {/* Workspace Switcher */}
-        <SidebarHeader className="py-3">
-          <div className="flex items-center gap-4">
-            <SidebarMenu className="min-w-0 flex-1">
-              <SidebarMenuItem>
-                <DropdownMenu>
-                  <DropdownMenuTrigger
-                    render={
-                      <SidebarMenuButton>
-                        <WorkspaceAvatar name={workspace?.name ?? "M"} size="sm" />
-                        <span className="flex-1 truncate font-medium">
-                          {workspace?.name ?? "Multica"}
-                        </span>
-                        <ChevronDown className="size-3 text-muted-foreground" />
-                      </SidebarMenuButton>
-                    }
-                  />
-                <DropdownMenuContent
-                  className="w-52"
-                  align="start"
-                  side="bottom"
-                  sideOffset={4}
-                >
-                  <DropdownMenuGroup>
-                    <DropdownMenuLabel className="text-xs text-muted-foreground">
-                      {user?.email}
-                    </DropdownMenuLabel>
-                  </DropdownMenuGroup>
-                  <DropdownMenuSeparator />
-                  <DropdownMenuGroup className="group/ws-section">
-                    <DropdownMenuLabel className="flex items-center text-xs text-muted-foreground">
-                      Workspaces
-                      <Tooltip>
-                        <TooltipTrigger
-                          className="ml-auto opacity-0 group-hover/ws-section:opacity-100 transition-opacity rounded hover:bg-accent p-0.5"
-                          onClick={() => useModalStore.getState().open("create-workspace")}
-                        >
-                          <Plus className="h-3.5 w-3.5" />
-                        </TooltipTrigger>
-                        <TooltipContent side="right">
-                          Create workspace
-                        </TooltipContent>
-                      </Tooltip>
-                    </DropdownMenuLabel>
-                    {workspaces.map((ws) => (
-                      <DropdownMenuItem
-                        key={ws.id}
-                        onClick={() => {
-                          if (ws.id !== workspace?.id) {
-                            router.push("/issues");
-                            switchWorkspace(ws.id);
-                          }
-                        }}
-                      >
-                        <WorkspaceAvatar name={ws.name} size="sm" />
-                        <span className="flex-1 truncate">{ws.name}</span>
-                        {ws.id === workspace?.id && (
-                          <Check className="h-3.5 w-3.5 text-primary" />
-                        )}
-                      </DropdownMenuItem>
-                    ))}
-                  </DropdownMenuGroup>
-                  <DropdownMenuSeparator />
-                  <DropdownMenuGroup>
-                    <DropdownMenuItem variant="destructive" onClick={logout}>
-                      <LogOut className="h-3.5 w-3.5" />
-                      Log out
-                    </DropdownMenuItem>
-                  </DropdownMenuGroup>
-                </DropdownMenuContent>
-                </DropdownMenu>
-              </SidebarMenuItem>
-            </SidebarMenu>
-            <Tooltip>
-              <TooltipTrigger
-                className="relative flex h-7 w-7 items-center justify-center rounded-lg bg-background text-foreground shadow-sm hover:bg-accent"
-                onClick={() => useModalStore.getState().open("create-issue")}
-              >
-                <SquarePen className="size-3.5" />
-                <DraftDot />
-              </TooltipTrigger>
-              <TooltipContent side="bottom">New issue</TooltipContent>
-            </Tooltip>
-          </div>
-        </SidebarHeader>
-
-        {/* Navigation */}
-        <SidebarContent>
-          <SidebarGroup>
-            <SidebarGroupContent>
-              <SidebarMenu className="gap-0.5">
-                {primaryNav.map((item) => {
-                  const isActive = pathname === item.href;
-                  return (
-                    <SidebarMenuItem key={item.href}>
-                      <SidebarMenuButton
-                        isActive={isActive}
-                        render={<Link href={item.href} />}
-                        className="text-muted-foreground hover:not-data-active:bg-sidebar-accent/70 data-active:bg-sidebar-accent data-active:text-sidebar-accent-foreground"
-                      >
-                        <item.icon />
-                        <span>{item.label}</span>
-                        {item.label === "Inbox" && unreadCount > 0 && (
-                          <span className="ml-auto text-xs">
-                            {unreadCount > 99 ? "99+" : unreadCount}
-                          </span>
-                        )}
-                      </SidebarMenuButton>
-                    </SidebarMenuItem>
-                  );
-                })}
-              </SidebarMenu>
-            </SidebarGroupContent>
-          </SidebarGroup>
-
-          <SidebarGroup>
-            <SidebarGroupContent>
-              <SidebarMenu className="gap-0.5">
-                {workspaceNav.map((item) => {
-                  const isActive = pathname === item.href;
-                  return (
-                    <SidebarMenuItem key={item.href}>
-                      <SidebarMenuButton
-                        isActive={isActive}
-                        render={<Link href={item.href} />}
-                        className="text-muted-foreground hover:not-data-active:bg-sidebar-accent/70 data-active:bg-sidebar-accent data-active:text-sidebar-accent-foreground"
-                      >
-                        <item.icon />
-                        <span>{item.label}</span>
-                      </SidebarMenuButton>
-                    </SidebarMenuItem>
-                  );
-                })}
-              </SidebarMenu>
-            </SidebarGroupContent>
-          </SidebarGroup>
-        </SidebarContent>
-        <SidebarFooter />
-        <SidebarRail />
-      </Sidebar>
-  );
-}

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

@@ -1,12 +0,0 @@
-export default function AgentDetailPage({
-  params,
-}: {
-  params: Promise<{ id: string }>;
-}) {
-  return (
-    <div className="p-6">
-      <h1 className="text-2xl font-bold">Agent Detail</h1>
-      <p className="mt-2 text-muted-foreground">Agent status and task history</p>
-    </div>
-  );
-}

apps/web/app/(dashboard)/board/page.tsx

@@ -1,10 +0,0 @@
-export default function BoardPage() {
-  return (
-    <div className="p-6">
-      <h1 className="text-2xl font-bold">Board</h1>
-      <p className="mt-2 text-muted-foreground">
-        Kanban board view coming soon.
-      </p>
-    </div>
-  );
-}

apps/web/app/(dashboard)/inbox/page.tsx

@@ -1,460 +1 @@
-"use client";
-
-import { useSearchParams } from "next/navigation";
-import { useDefaultLayout } from "react-resizable-panels";
-import { useInboxStore } from "@/features/inbox";
-import { IssueDetail, StatusIcon, PriorityIcon } from "@/features/issues/components";
-import { STATUS_CONFIG, PRIORITY_CONFIG } from "@/features/issues/config";
-import { useActorName } from "@/features/workspace";
-import { ActorAvatar } from "@/components/common/actor-avatar";
-import { toast } from "sonner";
-import {
-  ArrowRight,
-  MoreHorizontal,
-  Inbox,
-  CheckCheck,
-  Archive,
-  BookCheck,
-  ListChecks,
-} from "lucide-react";
-import type { InboxItem, InboxItemType, IssueStatus, IssuePriority } from "@/shared/types";
-import { Button } from "@/components/ui/button";
-import {
-  ResizablePanelGroup,
-  ResizablePanel,
-  ResizableHandle,
-} from "@/components/ui/resizable";
-import { Skeleton } from "@/components/ui/skeleton";
-import {
-  DropdownMenu,
-  DropdownMenuTrigger,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-} from "@/components/ui/dropdown-menu";
-import { api } from "@/shared/api";
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const typeLabels: Record<InboxItemType, string> = {
-  issue_assigned: "Assigned",
-  unassigned: "Unassigned",
-  assignee_changed: "Assignee changed",
-  status_changed: "Status changed",
-  priority_changed: "Priority changed",
-  due_date_changed: "Due date changed",
-  new_comment: "New comment",
-  mentioned: "Mentioned",
-  review_requested: "Review requested",
-  task_completed: "Task completed",
-  task_failed: "Task failed",
-  agent_blocked: "Agent blocked",
-  agent_completed: "Agent completed",
-  reaction_added: "Reacted",
-};
-
-function timeAgo(dateStr: string): string {
-  const diff = Date.now() - new Date(dateStr).getTime();
-  const minutes = Math.floor(diff / 60000);
-  if (minutes < 1) return "just now";
-  if (minutes < 60) return `${minutes}m`;
-  const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}h`;
-  const days = Math.floor(hours / 24);
-  return `${days}d`;
-}
-
-function shortDate(dateStr: string): string {
-  if (!dateStr) return "";
-  return new Date(dateStr).toLocaleDateString("en-US", {
-    month: "short",
-    day: "numeric",
-  });
-}
-
-// ---------------------------------------------------------------------------
-// InboxDetailLabel — renders rich subtitle per notification type
-// ---------------------------------------------------------------------------
-
-function InboxDetailLabel({ item }: { item: InboxItem }) {
-  const { getActorName } = useActorName();
-  const details = item.details ?? {};
-
-  switch (item.type) {
-    case "status_changed": {
-      if (!details.to) return <span>{typeLabels[item.type]}</span>;
-      const label = STATUS_CONFIG[details.to as IssueStatus]?.label ?? details.to;
-      return (
-        <span className="inline-flex items-center gap-1">
-          Set status to
-          <StatusIcon status={details.to as IssueStatus} className="h-3 w-3" />
-          {label}
-        </span>
-      );
-    }
-    case "priority_changed": {
-      if (!details.to) return <span>{typeLabels[item.type]}</span>;
-      const label = PRIORITY_CONFIG[details.to as IssuePriority]?.label ?? details.to;
-      return (
-        <span className="inline-flex items-center gap-1">
-          Set priority to
-          <PriorityIcon priority={details.to as IssuePriority} className="h-3 w-3" />
-          {label}
-        </span>
-      );
-    }
-    case "issue_assigned": {
-      if (details.new_assignee_id) {
-        return <span>Assigned to {getActorName(details.new_assignee_type ?? "member", details.new_assignee_id)}</span>;
-      }
-      return <span>{typeLabels[item.type]}</span>;
-    }
-    case "unassigned":
-      return <span>Removed assignee</span>;
-    case "assignee_changed": {
-      if (details.new_assignee_id) {
-        return <span>Assigned to {getActorName(details.new_assignee_type ?? "member", details.new_assignee_id)}</span>;
-      }
-      return <span>{typeLabels[item.type]}</span>;
-    }
-    case "due_date_changed": {
-      if (details.to) return <span>Set due date to {shortDate(details.to)}</span>;
-      return <span>Removed due date</span>;
-    }
-    case "new_comment": {
-      if (item.body) return <span>{item.body}</span>;
-      return <span>{typeLabels[item.type]}</span>;
-    }
-    case "reaction_added": {
-      const emoji = details.emoji;
-      if (emoji) return <span>Reacted {emoji} to your comment</span>;
-      return <span>{typeLabels[item.type]}</span>;
-    }
-    default:
-      return <span>{typeLabels[item.type] ?? item.type}</span>;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// InboxListItem
-// ---------------------------------------------------------------------------
-
-function InboxListItem({
-  item,
-  isSelected,
-  onClick,
-  onArchive,
-}: {
-  item: InboxItem;
-  isSelected: boolean;
-  onClick: () => void;
-  onArchive: () => void;
-}) {
-  return (
-    <button
-      onClick={onClick}
-      className={`group flex w-full items-center gap-3 px-4 py-2.5 text-left transition-colors ${
-        isSelected ? "bg-accent" : "hover:bg-accent/50"
-      }`}
-    >
-      <ActorAvatar
-        actorType={item.actor_type ?? item.recipient_type}
-        actorId={item.actor_id ?? item.recipient_id}
-        size={28}
-      />
-      <div className="min-w-0 flex-1">
-        <div className="flex items-center justify-between gap-2">
-          <div className="flex min-w-0 items-center gap-1.5">
-            {!item.read && (
-              <span className="h-1.5 w-1.5 shrink-0 rounded-full bg-brand" />
-            )}
-            <span
-              className={`truncate text-sm ${!item.read ? "font-medium" : "text-muted-foreground"}`}
-            >
-              {item.title}
-            </span>
-          </div>
-          <div className="flex shrink-0 items-center gap-1">
-            <span
-              role="button"
-              tabIndex={-1}
-              title="Archive"
-              onClick={(e) => {
-                e.stopPropagation();
-                onArchive();
-              }}
-              onKeyDown={(e) => {
-                if (e.key === "Enter" || e.key === " ") {
-                  e.stopPropagation();
-                  onArchive();
-                }
-              }}
-              className="hidden rounded p-0.5 text-muted-foreground hover:bg-accent hover:text-foreground group-hover:inline-flex"
-            >
-              <Archive className="h-3.5 w-3.5" />
-            </span>
-            {item.issue_status && (
-              <StatusIcon status={item.issue_status} className="h-3.5 w-3.5 shrink-0" />
-            )}
-          </div>
-        </div>
-        <div className="mt-0.5 flex items-center justify-between gap-2">
-          <p className={`min-w-0 overflow-hidden text-ellipsis whitespace-nowrap text-xs ${item.read ? "text-muted-foreground/60" : "text-muted-foreground"}`}>
-            <InboxDetailLabel item={item} />
-          </p>
-          <span className={`shrink-0 text-xs ${item.read ? "text-muted-foreground/60" : "text-muted-foreground"}`}>
-            {timeAgo(item.created_at)}
-          </span>
-        </div>
-      </div>
-    </button>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Page
-// ---------------------------------------------------------------------------
-
-export default function InboxPage() {
-  const searchParams = useSearchParams();
-  const selectedKey = searchParams.get("issue") ?? "";
-  const setSelectedKey = (key: string) => {
-    const url = key ? `/inbox?issue=${key}` : "/inbox";
-    window.history.replaceState(null, "", url);
-  };
-
-  const items = useInboxStore((s) => s.dedupedItems());
-  const loading = useInboxStore((s) => s.loading);
-
-  const { defaultLayout, onLayoutChanged } = useDefaultLayout({
-    id: "multica_inbox_layout",
-  });
-
-  const selected = items.find((i) => (i.issue_id ?? i.id) === selectedKey) ?? null;
-  const unreadCount = items.filter((i) => !i.read).length;
-
-  // Click-to-read: select + auto-mark-read
-  const handleSelect = async (item: InboxItem) => {
-    setSelectedKey(item.issue_id ?? item.id);
-    if (!item.read) {
-      useInboxStore.getState().markRead(item.id);
-      try {
-        await api.markInboxRead(item.id);
-      } catch {
-        // Rollback: refetch to get server truth
-        useInboxStore.getState().fetch();
-        toast.error("Failed to mark as read");
-      }
-    }
-  };
-
-  const handleArchive = async (id: string) => {
-    try {
-      await api.archiveInbox(id);
-      useInboxStore.getState().archive(id);
-      const archived = items.find((i) => i.id === id);
-      if (archived && (archived.issue_id ?? archived.id) === selectedKey) setSelectedKey("");
-    } catch {
-      toast.error("Failed to archive");
-    }
-  };
-
-  // Batch operations
-  const handleMarkAllRead = async () => {
-    try {
-      useInboxStore.getState().markAllRead();
-      await api.markAllInboxRead();
-    } catch {
-      toast.error("Failed to mark all as read");
-      useInboxStore.getState().fetch();
-    }
-  };
-
-  const handleArchiveAll = async () => {
-    try {
-      useInboxStore.getState().archiveAll();
-      setSelectedKey("");
-      await api.archiveAllInbox();
-    } catch {
-      toast.error("Failed to archive all");
-      useInboxStore.getState().fetch();
-    }
-  };
-
-  const handleArchiveAllRead = async () => {
-    try {
-      const readKeys = items.filter((i) => i.read).map((i) => i.issue_id ?? i.id);
-      useInboxStore.getState().archiveAllRead();
-      if (readKeys.includes(selectedKey)) setSelectedKey("");
-      await api.archiveAllReadInbox();
-    } catch {
-      toast.error("Failed to archive read items");
-      useInboxStore.getState().fetch();
-    }
-  };
-
-  const handleArchiveCompleted = async () => {
-    try {
-      await api.archiveCompletedInbox();
-      setSelectedKey("");
-      await useInboxStore.getState().fetch();
-    } catch {
-      toast.error("Failed to archive completed");
-    }
-  };
-
-  if (loading) {
-    return (
-      <ResizablePanelGroup orientation="horizontal" className="flex-1 min-h-0" defaultLayout={defaultLayout} onLayoutChanged={onLayoutChanged}>
-        <ResizablePanel id="list" defaultSize={320} minSize={240} maxSize={480} groupResizeBehavior="preserve-pixel-size">
-          <div className="flex flex-col border-r h-full">
-            <div className="flex h-12 shrink-0 items-center border-b px-4">
-              <Skeleton className="h-5 w-16" />
-            </div>
-            <div className="flex-1 min-h-0 overflow-y-auto space-y-1 p-2">
-              {Array.from({ length: 5 }).map((_, i) => (
-                <div key={i} className="flex items-center gap-3 px-4 py-2.5">
-                  <Skeleton className="h-7 w-7 shrink-0 rounded-full" />
-                  <div className="flex-1 space-y-2">
-                    <Skeleton className="h-4 w-3/4" />
-                    <Skeleton className="h-3 w-1/2" />
-                  </div>
-                </div>
-              ))}
-            </div>
-          </div>
-        </ResizablePanel>
-        <ResizableHandle />
-        <ResizablePanel id="detail" minSize="40%">
-          <div className="p-6">
-            <Skeleton className="h-6 w-48" />
-            <Skeleton className="mt-4 h-4 w-32" />
-          </div>
-        </ResizablePanel>
-      </ResizablePanelGroup>
-    );
-  }
-
-  return (
-    <ResizablePanelGroup orientation="horizontal" className="flex-1 min-h-0" defaultLayout={defaultLayout} onLayoutChanged={onLayoutChanged}>
-      <ResizablePanel id="list" defaultSize={320} minSize={240} maxSize={480} groupResizeBehavior="preserve-pixel-size">
-      {/* Left column — inbox list */}
-      <div className="flex flex-col border-r h-full">
-        <div className="flex h-12 shrink-0 items-center justify-between border-b px-4">
-          <div className="flex items-center gap-2">
-            <h1 className="text-sm font-semibold">Inbox</h1>
-            {unreadCount > 0 && (
-              <span className="text-xs text-muted-foreground">
-                {unreadCount}
-              </span>
-            )}
-          </div>
-          <DropdownMenu>
-            <DropdownMenuTrigger
-              render={
-                <Button
-                  variant="ghost"
-                  size="icon-xs"
-                  className="text-muted-foreground"
-                />
-              }
-            >
-              <MoreHorizontal className="h-4 w-4" />
-            </DropdownMenuTrigger>
-            <DropdownMenuContent align="end" className="w-auto">
-              <DropdownMenuItem onClick={handleMarkAllRead}>
-                <CheckCheck className="h-4 w-4" />
-                Mark all as read
-              </DropdownMenuItem>
-              <DropdownMenuSeparator />
-              <DropdownMenuItem onClick={handleArchiveAll}>
-                <Archive className="h-4 w-4" />
-                Archive all
-              </DropdownMenuItem>
-              <DropdownMenuItem onClick={handleArchiveAllRead}>
-                <BookCheck className="h-4 w-4" />
-                Archive all read
-              </DropdownMenuItem>
-              <DropdownMenuItem onClick={handleArchiveCompleted}>
-                <ListChecks className="h-4 w-4" />
-                Archive completed
-              </DropdownMenuItem>
-            </DropdownMenuContent>
-          </DropdownMenu>
-        </div>
-
-        <div className="flex-1 min-h-0 overflow-y-auto">
-        {items.length === 0 ? (
-          <div className="flex flex-col items-center justify-center py-16 text-muted-foreground">
-            <Inbox className="mb-3 h-8 w-8 text-muted-foreground/50" />
-            <p className="text-sm">No notifications</p>
-          </div>
-        ) : (
-          <div>
-            {items.map((item) => (
-              <InboxListItem
-                key={item.id}
-                item={item}
-                isSelected={(item.issue_id ?? item.id) === selectedKey}
-                onClick={() => handleSelect(item)}
-                onArchive={() => handleArchive(item.id)}
-              />
-            ))}
-          </div>
-        )}
-        </div>
-      </div>
-      </ResizablePanel>
-      <ResizableHandle />
-      <ResizablePanel id="detail" minSize="40%">
-      {/* Right column — detail */}
-      <div className="flex flex-col min-h-0 h-full">
-        {selected?.issue_id ? (
-          <IssueDetail
-            key={selected.issue_id}
-            issueId={selected.issue_id}
-            defaultSidebarOpen={false}
-            layoutId="multica_inbox_issue_detail_layout"
-            onDelete={() => {
-              handleArchive(selected.id);
-            }}
-          />
-        ) : selected ? (
-          <div className="p-6">
-            <h2 className="text-lg font-semibold">{selected.title}</h2>
-            <p className="mt-1 text-sm text-muted-foreground">
-              {typeLabels[selected.type]} · {timeAgo(selected.created_at)}
-            </p>
-            {selected.body && (
-              <div className="mt-4 whitespace-pre-wrap text-sm leading-relaxed text-foreground/80">
-                {selected.body}
-              </div>
-            )}
-            <div className="mt-4">
-              <Button
-                variant="outline"
-                size="sm"
-                onClick={() => handleArchive(selected.id)}
-              >
-                <Archive className="mr-1.5 h-3.5 w-3.5" />
-                Archive
-              </Button>
-            </div>
-          </div>
-        ) : (
-          <div className="flex h-full flex-col items-center justify-center text-muted-foreground">
-            <Inbox className="mb-3 h-10 w-10 text-muted-foreground/30" />
-            <p className="text-sm">
-              {items.length === 0
-                ? "Your inbox is empty"
-                : "Select a notification to view details"}
-            </p>
-          </div>
-        )}
-      </div>
-      </ResizablePanel>
-    </ResizablePanelGroup>
-  );
-}
+export { InboxPage as default } from "@multica/views/inbox";

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

@@ -1,362 +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 type { Issue, Comment, TimelineEntry } from "@/shared/types";
-
-// 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("@/features/auth", () => ({
-  useAuthStore: (selector: (s: any) => any) =>
-    selector({
-      user: { id: "user-1", name: "Test User", email: "test@multica.ai" },
-      isLoading: false,
-    }),
-}));
-
-// 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,
-  }),
-}));
-
-// Mock issue store — supply a stable full issue object so storeIssue
-// doesn't create a new reference each render (avoids infinite effect loop)
-// and has all required fields for rendering.
-const stableStoreIssues = vi.hoisted(() => [
-  {
-    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,
-    position: 0,
-    due_date: "2026-06-01T00:00:00Z",
-    created_at: "2026-01-15T00:00:00Z",
-    updated_at: "2026-01-20T00:00:00Z",
-  },
-]);
-vi.mock("@/features/issues", () => ({
-  useIssueStore: Object.assign(
-    (selector: (s: any) => any) => selector({ issues: stableStoreIssues }),
-    { getState: () => ({ issues: stableStoreIssues, addIssue: vi.fn(), updateIssue: vi.fn(), removeIssue: vi.fn() }) },
-  ),
-}));
-
-// Mock ws-context
-vi.mock("@/features/realtime", () => ({
-  useWSEvent: () => {},
-  useWSReconnect: () => {},
-}));
-
-// Mock calendar (react-day-picker needs browser APIs)
-vi.mock("@/components/ui/calendar", () => ({
-  Calendar: () => null,
-}));
-
-// Mock RichTextEditor (Tiptap needs real DOM)
-vi.mock("@/components/common/rich-text-editor", () => ({
-  RichTextEditor: 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"
-      />
-    );
-  }),
-}));
-
-// Mock Markdown renderer
-vi.mock("@/components/markdown", () => ({
-  Markdown: ({ children }: { children: string }) => <div>{children}</div>,
-}));
-
-// Mock api
-const mockGetIssue = vi.hoisted(() => vi.fn());
-const mockListTimeline = vi.hoisted(() => vi.fn());
-const mockCreateComment = vi.hoisted(() => vi.fn());
-const mockUpdateComment = vi.hoisted(() => vi.fn());
-const mockDeleteComment = vi.hoisted(() => vi.fn());
-const mockDeleteIssue = vi.hoisted(() => vi.fn());
-const mockUpdateIssue = vi.hoisted(() => vi.fn());
-
-vi.mock("@/shared/api", () => ({
-  api: {
-    getIssue: (...args: any[]) => mockGetIssue(...args),
-    listTimeline: (...args: any[]) => mockListTimeline(...args),
-    listComments: vi.fn().mockResolvedValue([]),
-    createComment: (...args: any[]) => mockCreateComment(...args),
-    updateComment: (...args: any[]) => mockUpdateComment(...args),
-    deleteComment: (...args: any[]) => mockDeleteComment(...args),
-    deleteIssue: (...args: any[]) => mockDeleteIssue(...args),
-    updateIssue: (...args: any[]) => mockUpdateIssue(...args),
-    listIssueSubscribers: vi.fn().mockResolvedValue([]),
-    subscribeToIssue: vi.fn().mockResolvedValue(undefined),
-    unsubscribeFromIssue: vi.fn().mockResolvedValue(undefined),
-    getActiveTaskForIssue: vi.fn().mockResolvedValue({ task: null }),
-    listTasksByIssue: vi.fn().mockResolvedValue([]),
-    listTaskMessages: vi.fn().mockResolvedValue([]),
-  },
-}));
-
-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,
-  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";
-
-// React 19 use(Promise) needs the promise to resolve within act + Suspense
-async function renderPage(id = "issue-1") {
-  let result: ReturnType<typeof render>;
-  await act(async () => {
-    result = render(
-      <Suspense fallback={<div>Suspense loading...</div>}>
-        <IssueDetailPage params={Promise.resolve({ id })} />
-      </Suspense>,
-    );
-  });
-  return result!;
-}
-
-describe("IssueDetailPage", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it("renders issue details after loading", async () => {
-    mockGetIssue.mockResolvedValueOnce(mockIssue);
-    mockListTimeline.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 () => {
-    mockGetIssue.mockResolvedValueOnce(mockIssue);
-    mockListTimeline.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 () => {
-    mockGetIssue.mockResolvedValueOnce(mockIssue);
-    mockListTimeline.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
-    mockGetIssue.mockRejectedValue(new Error("Not found"));
-    mockListTimeline.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 () => {
-    mockGetIssue.mockResolvedValueOnce(mockIssue);
-    mockListTimeline.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",
-    };
-    mockCreateComment.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(mockCreateComment).toHaveBeenCalled();
-      const [issueId, content] = mockCreateComment.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 () => {
-    mockGetIssue.mockResolvedValueOnce(mockIssue);
-    mockListTimeline.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)/issues/[id]/page.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { use } from "react";
-import { IssueDetail } from "@/features/issues/components";
+import { IssueDetail } from "@multica/views/issues/components";
 
 export default function IssueDetailPage({
   params,

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

@@ -1,373 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import type { Issue } from "@/shared/types";
-
-// Mock next/navigation
-vi.mock("next/navigation", () => ({
-  useRouter: () => ({ push: vi.fn() }),
-  usePathname: () => "/issues",
-}));
-
-// 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 workspace feature
-vi.mock("@/features/workspace", () => ({
-  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) =>
-      type === "member" ? "Test User" : "Claude Agent",
-    getActorInitials: () => "TU",
-    getActorAvatarUrl: () => null,
-  }),
-  useWorkspaceStore: Object.assign(
-    (selector?: any) => {
-      const state = { workspace: { id: "ws-1", name: "Test", slug: "test" }, agents: [], members: [] };
-      return selector ? selector(state) : state;
-    },
-    { getState: () => ({ workspace: { id: "ws-1", name: "Test", slug: "test" }, agents: [], members: [] }) },
-  ),
-  WorkspaceAvatar: ({ name }: { name: string }) => <span>{name.charAt(0)}</span>,
-}));
-
-// Mock WebSocket context
-vi.mock("@/features/realtime", () => ({
-  useWSEvent: vi.fn(),
-  useWSReconnect: vi.fn(),
-  useWS: () => ({ subscribe: vi.fn(() => () => {}), onReconnect: vi.fn(() => () => {}) }),
-  WSProvider: ({ children }: { children: React.ReactNode }) => children,
-}));
-
-// Mock sonner toast
-vi.mock("sonner", () => ({
-  toast: { error: vi.fn(), success: vi.fn() },
-}));
-
-// Mock api
-const mockUpdateIssue = vi.fn();
-
-vi.mock("@/shared/api", () => ({
-  api: {
-    listIssues: vi.fn().mockResolvedValue({ issues: [], total: 0 }),
-    updateIssue: (...args: any[]) => mockUpdateIssue(...args),
-  },
-}));
-
-// Mock the issue store
-let mockStoreState: {
-  issues: Issue[];
-  loading: boolean;
-  fetch: () => Promise<void>;
-  setIssues: (issues: Issue[]) => void;
-  addIssue: (issue: Issue) => void;
-  updateIssue: (id: string, updates: Partial<Issue>) => void;
-  removeIssue: (id: string) => void;
-};
-
-vi.mock("@/features/issues/store", () => ({
-  useIssueStore: Object.assign(
-    (selector?: any) => (selector ? selector(mockStoreState) : mockStoreState),
-    { getState: () => mockStoreState },
-  ),
-}));
-
-vi.mock("@/features/issues", () => ({
-  useIssueStore: Object.assign(
-    (selector?: any) => (selector ? selector(mockStoreState) : mockStoreState),
-    { getState: () => mockStoreState },
-  ),
-  StatusIcon: () => null,
-  PriorityIcon: () => null,
-  StatusPicker: ({ value, onChange }: any) => (
-    <button onClick={() => onChange?.("todo")}>{value || "todo"}</button>
-  ),
-  PriorityPicker: ({ value, onChange }: any) => (
-    <button onClick={() => onChange?.("none")}>{value || "none"}</button>
-  ),
-}));
-
-// Mock view store
-const mockViewState = {
-  viewMode: "board" as const,
-  statusFilters: [] as string[],
-  priorityFilters: [] as string[],
-  assigneeFilters: [] as { type: string; id: string }[],
-  includeNoAssignee: false,
-  creatorFilters: [] as { type: string; id: string }[],
-  sortBy: "position" as const,
-  sortDirection: "asc" as const,
-  cardProperties: { priority: true, description: true, assignee: true, dueDate: true },
-  listCollapsedStatuses: [] as string[],
-  setViewMode: vi.fn(),
-  toggleStatusFilter: vi.fn(),
-  togglePriorityFilter: vi.fn(),
-  toggleAssigneeFilter: vi.fn(),
-  toggleNoAssignee: vi.fn(),
-  toggleCreatorFilter: vi.fn(),
-  hideStatus: vi.fn(),
-  showStatus: vi.fn(),
-  clearFilters: vi.fn(),
-  setSortBy: vi.fn(),
-  setSortDirection: vi.fn(),
-  toggleCardProperty: vi.fn(),
-  toggleListCollapsed: vi.fn(),
-};
-
-vi.mock("@/features/issues/stores/view-store", () => ({
-  initFilterWorkspaceSync: vi.fn(),
-  useIssueViewStore: Object.assign(
-    (selector?: any) => (selector ? selector(mockViewState) : mockViewState),
-    { getState: () => mockViewState, setState: vi.fn() },
-  ),
-  SORT_OPTIONS: [
-    { value: "position", label: "Manual" },
-    { value: "priority", label: "Priority" },
-    { value: "due_date", label: "Due date" },
-    { value: "created_at", label: "Created date" },
-    { value: "title", label: "Title" },
-  ],
-  CARD_PROPERTY_OPTIONS: [
-    { key: "priority", label: "Priority" },
-    { key: "description", label: "Description" },
-    { key: "assignee", label: "Assignee" },
-    { key: "dueDate", label: "Due date" },
-  ],
-}));
-
-// Mock view store context (shared components read from context)
-vi.mock("@/features/issues/stores/view-store-context", () => ({
-  ViewStoreProvider: ({ children }: { children: React.ReactNode }) => children,
-  useViewStore: (selector?: any) => (selector ? selector(mockViewState) : mockViewState),
-  useViewStoreApi: () => ({ getState: () => mockViewState, setState: vi.fn(), subscribe: vi.fn() }),
-}));
-
-// Mock issue config
-vi.mock("@/features/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("@/features/modals", () => ({
-  useModalStore: Object.assign(
-    () => ({ open: vi.fn() }),
-    { getState: () => ({ open: vi.fn() }) },
-  ),
-}));
-
-// Mock dnd-kit
-vi.mock("@dnd-kit/core", () => ({
-  DndContext: ({ children }: any) => children,
-  DragOverlay: () => null,
-  PointerSensor: class {},
-  useSensor: () => ({}),
-  useSensors: () => [],
-  useDroppable: () => ({ setNodeRef: vi.fn(), isOver: false }),
-  pointerWithin: vi.fn(),
-  closestCenter: vi.fn(),
-}));
-
-vi.mock("@dnd-kit/sortable", () => ({
-  SortableContext: ({ children }: any) => children,
-  verticalListSortingStrategy: {},
-  useSortable: () => ({
-    attributes: {},
-    listeners: {},
-    setNodeRef: vi.fn(),
-    transform: null,
-    transition: null,
-    isDragging: false,
-  }),
-}));
-
-vi.mock("@dnd-kit/utilities", () => ({
-  CSS: { Transform: { toString: () => undefined } },
-}));
-
-const issueDefaults = {
-  parent_issue_id: null,
-  position: 0,
-};
-
-const mockIssues: Issue[] = [
-  {
-    ...issueDefaults,
-    id: "issue-1",
-    workspace_id: "ws-1",
-    number: 1,
-    identifier: "TES-1",
-    title: "Implement auth",
-    description: "Add JWT authentication",
-    status: "todo",
-    priority: "high",
-    assignee_type: "member",
-    assignee_id: "user-1",
-    creator_type: "member",
-    creator_id: "user-1",
-    due_date: null,
-    created_at: "2026-01-01T00:00:00Z",
-    updated_at: "2026-01-01T00:00:00Z",
-  },
-  {
-    ...issueDefaults,
-    id: "issue-2",
-    workspace_id: "ws-1",
-    number: 2,
-    identifier: "TES-2",
-    title: "Design landing page",
-    description: null,
-    status: "in_progress",
-    priority: "medium",
-    assignee_type: "agent",
-    assignee_id: "agent-1",
-    creator_type: "member",
-    creator_id: "user-1",
-    due_date: "2026-02-01T00:00:00Z",
-    created_at: "2026-01-01T00:00:00Z",
-    updated_at: "2026-01-01T00:00:00Z",
-  },
-  {
-    ...issueDefaults,
-    id: "issue-3",
-    workspace_id: "ws-1",
-    number: 3,
-    identifier: "TES-3",
-    title: "Write tests",
-    description: null,
-    status: "backlog",
-    priority: "low",
-    assignee_type: null,
-    assignee_id: null,
-    creator_type: "member",
-    creator_id: "user-1",
-    due_date: null,
-    created_at: "2026-01-01T00:00:00Z",
-    updated_at: "2026-01-01T00:00:00Z",
-  },
-];
-
-import IssuesPage from "./page";
-
-describe("IssuesPage", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockStoreState = {
-      issues: [],
-      loading: true,
-      fetch: vi.fn(),
-      setIssues: vi.fn(),
-      addIssue: vi.fn(),
-      updateIssue: vi.fn(),
-      removeIssue: vi.fn(),
-    };
-    mockViewState.viewMode = "board";
-    mockViewState.statusFilters = [];
-    mockViewState.priorityFilters = [];
-  });
-
-  it("shows loading state initially", () => {
-    mockStoreState.loading = true;
-    mockStoreState.issues = [];
-    render(<IssuesPage />);
-    expect(screen.getAllByRole("generic").some(el => el.getAttribute("data-slot") === "skeleton")).toBe(true);
-  });
-
-  it("renders issues in board view after loading", async () => {
-    mockStoreState.loading = false;
-    mockStoreState.issues = mockIssues;
-
-    render(<IssuesPage />);
-
-    expect(screen.getByText("Implement auth")).toBeInTheDocument();
-    expect(screen.getByText("Design landing page")).toBeInTheDocument();
-    expect(screen.getByText("Write tests")).toBeInTheDocument();
-  });
-
-  it("renders board columns", async () => {
-    mockStoreState.loading = false;
-    mockStoreState.issues = mockIssues;
-
-    render(<IssuesPage />);
-
-    expect(screen.getAllByText("Backlog").length).toBeGreaterThanOrEqual(1);
-    expect(screen.getAllByText("Todo").length).toBeGreaterThanOrEqual(1);
-    expect(screen.getAllByText("In Progress").length).toBeGreaterThanOrEqual(1);
-    expect(screen.getAllByText("In Review").length).toBeGreaterThanOrEqual(1);
-    expect(screen.getAllByText("Done").length).toBeGreaterThanOrEqual(1);
-  });
-
-  it("shows workspace breadcrumb", () => {
-    mockStoreState.loading = false;
-    mockStoreState.issues = [];
-
-    render(<IssuesPage />);
-
-    expect(screen.getByText("Issues")).toBeInTheDocument();
-  });
-
-  it("shows scope buttons", () => {
-    mockStoreState.loading = false;
-    mockStoreState.issues = [];
-
-    render(<IssuesPage />);
-
-    expect(screen.getByText("All")).toBeInTheDocument();
-    expect(screen.getByText("Members")).toBeInTheDocument();
-    expect(screen.getByText("Agents")).toBeInTheDocument();
-  });
-
-  it("shows filter and display icon buttons", () => {
-    mockStoreState.loading = false;
-    mockStoreState.issues = mockIssues;
-
-    render(<IssuesPage />);
-
-    // Filter and Display are now icon-only buttons, verify they render as buttons
-    const buttons = screen.getAllByRole("button");
-    expect(buttons.length).toBeGreaterThan(0);
-  });
-
-  it("shows empty board view when no issues exist", () => {
-    mockStoreState.loading = false;
-    mockStoreState.issues = [];
-
-    render(<IssuesPage />);
-
-    // Should still render the board/list view, not a "no issues" message
-    expect(screen.queryByText("No matching issues")).not.toBeInTheDocument();
-  });
-});

apps/web/app/(dashboard)/issues/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { IssuesPage } from "@/features/issues/components/issues-page";
+import { IssuesPage } from "@multica/views/issues/components";
 
 export default function Page() {
   return <IssuesPage />;

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

@@ -1,57 +1,18 @@
 "use client";
 
-import { useEffect } from "react";
-import { useRouter, usePathname } from "next/navigation";
-import { MulticaIcon } from "@/components/multica-icon";
-import { useNavigationStore } from "@/features/navigation";
-import { SidebarProvider, SidebarInset } from "@/components/ui/sidebar";
-import { useAuthStore } from "@/features/auth";
-import { useWorkspaceStore } from "@/features/workspace";
-import { AppSidebar } from "./_components/app-sidebar";
-
-export default function DashboardLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const router = useRouter();
-  const pathname = usePathname();
-  const user = useAuthStore((s) => s.user);
-  const isLoading = useAuthStore((s) => s.isLoading);
-  const workspace = useWorkspaceStore((s) => s.workspace);
-
-  useEffect(() => {
-    if (!isLoading && !user) {
-      router.push("/");
-    }
-  }, [user, isLoading, router]);
-
-  useEffect(() => {
-    useNavigationStore.getState().onPathChange(pathname);
-  }, [pathname]);
-
-  if (isLoading) {
-    return (
-      <div className="flex h-screen items-center justify-center">
-        <MulticaIcon className="size-6" />
-      </div>
-    );
-  }
-
-  if (!user) return null;
+import { DashboardLayout } from "@multica/views/layout";
+import { MulticaIcon } from "@multica/ui/components/common/multica-icon";
+import { SearchCommand, SearchTrigger } from "@multica/views/search";
+import { ChatFab, ChatWindow } from "@multica/views/chat";
 
+export default function Layout({ children }: { children: React.ReactNode }) {
   return (
-    <SidebarProvider className="h-svh">
-      <AppSidebar />
-      <SidebarInset className="overflow-hidden">
-        {workspace ? (
-          children
-        ) : (
-          <div className="flex flex-1 items-center justify-center">
-            <MulticaIcon className="size-6 animate-pulse" />
-          </div>
-        )}
-      </SidebarInset>
-    </SidebarProvider>
+    <DashboardLayout
+      loadingIndicator={<MulticaIcon className="size-6" />}
+      searchSlot={<SearchTrigger />}
+      extra={<><SearchCommand /><ChatWindow /><ChatFab /></>}
+    >
+      {children}
+    </DashboardLayout>
   );
 }

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

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

apps/web/app/(dashboard)/my-issues/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { MyIssuesPage } from "@/features/my-issues";
+import { MyIssuesPage } from "@multica/views/my-issues";
 
 export default function Page() {
   return <MyIssuesPage />;

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

@@ -0,0 +1,13 @@
+"use client";
+
+import { use } from "react";
+import { ProjectDetail } from "@multica/views/projects/components";
+
+export default function ProjectDetailPage({
+  params,
+}: {
+  params: Promise<{ id: string }>;
+}) {
+  const { id } = use(params);
+  return <ProjectDetail projectId={id} />;
+}

apps/web/app/(dashboard)/projects/page.tsx

@@ -0,0 +1,7 @@
+"use client";
+
+import { ProjectsPage } from "@multica/views/projects/components";
+
+export default function Page() {
+  return <ProjectsPage />;
+}

apps/web/app/(dashboard)/runtimes/page.tsx

@@ -1 +1 @@
-export { RuntimesPage as default } from "@/features/runtimes";
+export { RuntimesPage as default } from "@multica/views/runtimes";

apps/web/app/(dashboard)/settings/page.tsx

@@ -1,68 +1 @@
-"use client";
-
-import { User, Palette, Key, Settings, Users } from "lucide-react";
-import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs";
-import { useWorkspaceStore } from "@/features/workspace";
-import { AccountTab } from "./_components/account-tab";
-import { AppearanceTab } from "./_components/general-tab";
-import { TokensTab } from "./_components/tokens-tab";
-import { WorkspaceTab } from "./_components/workspace-tab";
-import { MembersTab } from "./_components/members-tab";
-
-const accountTabs = [
-  { value: "profile", label: "Profile", icon: User },
-  { value: "appearance", label: "Appearance", icon: Palette },
-  { value: "tokens", label: "API Tokens", icon: Key },
-];
-
-const workspaceTabs = [
-  { value: "workspace", label: "General", icon: Settings },
-  { value: "members", label: "Members", icon: Users },
-];
-
-export default function SettingsPage() {
-  const workspaceName = useWorkspaceStore((s) => s.workspace?.name);
-
-  return (
-    <Tabs defaultValue="profile" orientation="vertical" className="flex-1 min-h-0 gap-0">
-      {/* Left nav */}
-      <div className="w-52 shrink-0 border-r overflow-y-auto p-4">
-        <h1 className="text-sm font-semibold mb-4 px-2">Settings</h1>
-        <TabsList variant="line" className="flex-col items-stretch">
-          {/* My Account group */}
-          <span className="px-2 pb-1 pt-2 text-xs font-medium text-muted-foreground">
-            My Account
-          </span>
-          {accountTabs.map((tab) => (
-            <TabsTrigger key={tab.value} value={tab.value}>
-              <tab.icon className="h-4 w-4" />
-              {tab.label}
-            </TabsTrigger>
-          ))}
-
-          {/* Workspace group */}
-          <span className="px-2 pb-1 pt-4 text-xs font-medium text-muted-foreground truncate">
-            {workspaceName ?? "Workspace"}
-          </span>
-          {workspaceTabs.map((tab) => (
-            <TabsTrigger key={tab.value} value={tab.value}>
-              <tab.icon className="h-4 w-4" />
-              {tab.label}
-            </TabsTrigger>
-          ))}
-        </TabsList>
-      </div>
-
-      {/* Right content */}
-      <div className="flex-1 min-w-0 overflow-y-auto">
-        <div className="w-full max-w-3xl mx-auto p-6">
-          <TabsContent value="profile"><AccountTab /></TabsContent>
-          <TabsContent value="appearance"><AppearanceTab /></TabsContent>
-          <TabsContent value="tokens"><TokensTab /></TabsContent>
-          <TabsContent value="workspace"><WorkspaceTab /></TabsContent>
-          <TabsContent value="members"><MembersTab /></TabsContent>
-        </div>
-      </div>
-    </Tabs>
-  );
-}
+export { SettingsPage as default } from "@multica/views/settings";

apps/web/app/(dashboard)/skills/page.tsx

@@ -1 +1 @@
-export { SkillsPage as default } from "@/features/skills";
+export { SkillsPage as default } from "@multica/views/skills";