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

.gitignore

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

.goreleaser.yml

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

CLAUDE.md

@@ -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
@@ -155,6 +116,8 @@ CI runs on Node 22 and Go 1.26.1 with a `pgvector/pgvector:pg17` PostgreSQL serv
 
 All checkouts share one PostgreSQL container. Isolation is at the database level — each worktree gets its own DB name and unique ports via `.env.worktree`. Main checkouts use `.env`.
 
+`make dev` auto-detects worktrees and handles everything. For explicit control:
+
 ```bash
 make worktree-env       # Generate .env.worktree with unique DB/ports
 make setup-worktree     # Setup using .env.worktree
@@ -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.
@@ -306,6 +324,21 @@ multica issue run-messages <task-id> --since 42 --output json
 
 The `runs` command shows all past and current executions for an issue, including running tasks. The `run-messages` command shows the detailed message log (tool calls, thinking, text, errors) for a single run. Use `--since` for efficient polling of in-progress runs.
 
+## Setup
+
+```bash
+# One-command setup: configure, authenticate, and start the daemon
+multica setup
+
+# For local self-hosted deployments (auto-detects or forces local mode)
+multica setup --local
+
+# Custom ports
+multica setup --local --port 9090 --frontend-port 4000
+```
+
+`multica setup` detects whether a local Multica server is running, configures the CLI, opens your browser for authentication, and starts the daemon — all in one step.
+
 ## Configuration
 
 ### View Config
@@ -316,10 +349,19 @@ multica config show
 
 Shows config file path, server URL, app URL, and default workspace.
 
+### Configure for Local Self-Hosted
+
+```bash
+multica config local                                      # Uses default ports (8080/3000)
+multica config local --port 9090 --frontend-port 4000     # Custom ports
+```
+
+Sets `server_url` and `app_url` for a local Docker Compose deployment in one command.
+
 ### Set Values
 
 ```bash
-multica config set server_url wss://api.example.com/ws
+multica config set server_url https://api.example.com
 multica config set app_url https://app.example.com
 multica config set workspace_id <workspace-id>
 ```

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

@@ -14,14 +14,14 @@
 
 **Your next 10 hires won't be human.**
 
-Open-source platform that turns coding agents into real teammates.<br/>
-Assign tasks, track progress, compound skills — manage your human + agent workforce in one place.
+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) · [Self-Hosting](SELF_HOSTING.md) · [Contributing](CONTRIBUTING.md)
+[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)**
 
@@ -31,7 +31,7 @@ Assign tasks, track progress, compound skills — manage your human + agent work
 
 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. Works with **Claude Code** and **Codex**.
+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">
@@ -39,55 +39,44 @@ No more copy-pasting prompts. No more babysitting runs. Your agents show up on t
 
 ## Features
 
+Multica manages the full agent lifecycle: from task assignment to execution monitoring to skill reuse.
+
 - **Agents as Teammates** — assign to an agent like you'd assign to a colleague. They have profiles, show up on the board, post comments, create issues, and report blockers proactively.
 - **Autonomous Execution** — set it and forget it. Full task lifecycle management (enqueue, claim, start, complete/fail) with real-time progress streaming via WebSocket.
 - **Reusable Skills** — every solution becomes a reusable skill for the whole team. Deployments, migrations, code reviews — skills compound your team's capabilities over time.
 - **Unified Runtimes** — one dashboard for all your compute. Local daemons and cloud runtimes, auto-detection of available CLIs, real-time monitoring.
 - **Multi-Workspace** — organize work across teams with workspace-level isolation. Each workspace has its own agents, issues, and settings.
 
+---
+
+## Quick Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
+```
+
+Installs the Multica CLI on macOS and Linux. Works with Homebrew or downloads the binary directly.
+
+After installation:
+
+```bash
+multica login          # Authenticate (opens browser)
+multica daemon start   # Start the local agent runtime
+multica daemon stop    # Stop the daemon when done
+```
+
+> **Self-hosting?** Add `--local` to deploy a full Multica server on your machine:
+>
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --local
+> ```
+>
+> Requires Docker. See the [Self-Hosting Guide](SELF_HOSTING.md) for details.
+
+---
+
 ## Getting Started
 
-### Multica Cloud
-
-The fastest way to get started — no setup required: **[multica.ai](https://multica.ai)**
-
-### Self-Host with Docker
-
-```bash
-git clone https://github.com/multica-ai/multica.git
-cd multica
-cp .env.example .env
-# Edit .env — at minimum, change JWT_SECRET
-
-docker compose up -d                              # Start PostgreSQL
-cd server && go run ./cmd/migrate up && cd ..     # Run migrations
-make start                                         # Start the app
-```
-
-See the [Self-Hosting Guide](SELF_HOSTING.md) for full instructions.
-
-## CLI
-
-The `multica` CLI connects your local machine to Multica — authenticate, manage workspaces, and run the agent daemon.
-
-```bash
-# Install
-brew tap multica-ai/tap
-brew install multica
-
-# Authenticate and start
-multica login
-multica daemon start
-```
-
-The daemon auto-detects available agent CLIs (`claude`, `codex`) on your PATH. When an agent is assigned a task, the daemon creates an isolated environment, runs the agent, and reports results back.
-
-See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference, daemon configuration, and advanced usage.
-
-## Quickstart
-
-Once you have the CLI installed (or signed up for [Multica Cloud](https://multica.ai)), follow these steps to assign your first task to an agent:
-
 ### 1. Log in and start the daemon
 
 ```bash
@@ -95,7 +84,7 @@ multica login           # Authenticate with your Multica account
 multica daemon start    # Start the local agent runtime
 ```
 
-The daemon runs in the background and keeps your machine connected to Multica. It auto-detects agent CLIs (`claude`, `codex`) available on your PATH.
+The daemon runs in the background and auto-detects agent CLIs (`claude`, `codex`, `openclaw`, `opencode`) on your PATH.
 
 ### 2. Verify your runtime
 
@@ -105,13 +94,33 @@ Open your workspace in the Multica web app. Navigate to **Settings → Runtimes*
 
 ### 3. Create an agent
 
-Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code or Codex). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
+Go to **Settings → Agents** and click **New Agent**. Pick the runtime you just connected and choose a provider (Claude Code, Codex, OpenClaw, or OpenCode). Give your agent a name — this is how it will appear on the board, in comments, and in assignments.
 
 ### 4. Assign your first task
 
 Create an issue from the board (or via `multica issue create`), then assign it to your new agent. The agent will automatically pick up the task, execute it on your runtime, and report progress — just like a human teammate.
 
-That's it! Your agent is now part of the team. 🎉
+---
+
+## CLI
+
+The `multica` CLI connects your local machine to Multica — authenticate, manage workspaces, and run the agent daemon.
+
+| Command | Description |
+|---------|-------------|
+| `multica login` | Authenticate (opens browser) |
+| `multica daemon start` | Start the local agent runtime |
+| `multica daemon status` | Check daemon status |
+| `multica setup` | One-command setup (configure + login + start daemon) |
+| `multica setup --local` | Same, but for self-hosted deployments |
+| `multica config local` | Configure CLI for a local self-hosted server |
+| `multica issue list` | List issues in your workspace |
+| `multica issue create` | Create a new issue |
+| `multica update` | Update to the latest version |
+
+See the [CLI and Daemon Guide](CLI_AND_DAEMON.md) for the full command reference.
+
+---
 
 ## Architecture
 
@@ -123,7 +132,8 @@ That's it! Your agent is now part of the team. 🎉
                             │
                      ┌──────┴───────┐
                      │ Agent Daemon │  (runs on your machine)
-                     │ Claude/Codex │
+                     │Claude/Codex/ │
+                     │OpenClaw/Code │
                      └──────────────┘
 ```
 
@@ -132,7 +142,7 @@ That's it! Your agent is now part of the team. 🎉
 | 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 |
+| Agent Runtime | Local daemon executing Claude Code, Codex, OpenClaw, or OpenCode |
 
 ## Development
 
@@ -141,14 +151,9 @@ For contributors working on the Multica codebase, see the [Contributing Guide](C
 **Prerequisites:** [Node.js](https://nodejs.org/) v20+, [pnpm](https://pnpm.io/) v10.28+, [Go](https://go.dev/) v1.26+, [Docker](https://www.docker.com/)
 
 ```bash
-pnpm install
-cp .env.example .env
-make setup
-make start
+make dev
 ```
 
+`make dev` auto-detects your environment (main checkout or worktree), creates the env file, installs dependencies, sets up the database, runs migrations, and starts all services.
+
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow, worktree support, testing, and troubleshooting.
-
-## License
-
-[Apache 2.0](LICENSE)

README.zh-CN.md

@@ -14,14 +14,14 @@
 
 **你的下一批员工，不是人类。**
 
-开源平台，将编码 Agent 变成真正的队友。<br/>
-分配任务、跟踪进度、积累技能——在一个地方管理你的人类 + Agent 团队。
+开源的 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) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
+[官网](https://multica.ai) · [云服务](https://multica.ai/app) · [X](https://x.com/multica_hq) · [自部署指南](SELF_HOSTING.md) · [参与贡献](CONTRIBUTING.md)
 
 **[English](README.md) | 简体中文**
 
@@ -31,7 +31,7 @@
 
 Multica 将编码 Agent 变成真正的队友。像分配给同事一样分配给 Agent——它们会自主接手工作、编写代码、报告阻塞问题、更新状态。
 
-不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。支持 **Claude Code** 和 **Codex**。
+不再需要复制粘贴 prompt，不再需要盯着运行过程。你的 Agent 出现在看板上、参与对话、随着时间积累可复用的技能。可以理解为开源的 Managed Agents 基础设施——厂商中立、可自部署、专为人类 + AI 团队设计。支持 **Claude Code**、**Codex**、**OpenClaw** 和 **OpenCode**。
 
 <p align="center">
   <img src="docs/assets/hero-screenshot.png" alt="Multica 看板视图" width="800">
@@ -39,50 +39,41 @@ Multica 将编码 Agent 变成真正的队友。像分配给同事一样分配
 
 ## 功能特性
 
+Multica 管理完整的 Agent 生命周期：从任务分配到执行监控再到技能复用。
+
 - **Agent 即队友** — 像分配给同事一样分配给 Agent。它们有个人档案、出现在看板上、发表评论、创建 Issue、主动报告阻塞问题。
 - **自主执行** — 设置后无需管理。完整的任务生命周期管理（排队、认领、执行、完成/失败），通过 WebSocket 实时推送进度。
 - **可复用技能** — 每个解决方案都成为全团队可复用的技能。部署、数据库迁移、代码审查——技能让团队能力随时间持续增长。
 - **统一运行时** — 一个控制台管理所有算力。本地 daemon 和云端运行时，自动检测可用 CLI，实时监控。
 - **多工作区** — 按团队组织工作，工作区级别隔离。每个工作区有独立的 Agent、Issue 和设置。
 
-## 快速开始
+---
 
-### Multica 云服务
-
-最快的上手方式，无需任何配置：**[multica.ai](https://multica.ai)**
-
-### Docker 自部署
+## 快速安装
 
 ```bash
-git clone https://github.com/multica-ai/multica.git
-cd multica
-cp .env.example .env
-# 编辑 .env — 至少修改 JWT_SECRET
-
-docker compose up -d                              # 启动 PostgreSQL
-cd server && go run ./cmd/migrate up && cd ..     # 运行数据库迁移
-make start                                         # 启动应用
+curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash
 ```
 
-完整部署文档请参阅 [自部署指南](SELF_HOSTING.md)。
+安装 Multica CLI，支持 macOS 和 Linux。有 Homebrew 用 Homebrew，没有则直接下载二进制。
 
-## CLI
-
-`multica` CLI 将你的本地机器连接到 Multica — 用于认证、管理工作区和运行 Agent daemon。
+安装完成后：
 
 ```bash
-# 安装
-brew tap multica-ai/tap
-brew install multica
-
-# 认证并启动
-multica login
-multica daemon start
+multica login          # 认证（打开浏览器）
+multica daemon start   # 启动本地 Agent 运行时
+multica daemon stop    # 停止 daemon
 ```
 
-daemon 会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`）。当 Agent 被分配任务时，daemon 会创建隔离环境、运行 Agent、并将结果回传。
+> **自部署？** 加上 `--local` 在本地部署完整的 Multica 服务：
+>
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/multica-ai/multica/main/scripts/install.sh | bash -s -- --local
+> ```
+>
+> 需要 Docker。详见 [自部署指南](SELF_HOSTING.md)。
 
-完整命令参考请参阅 [CLI 与 Daemon 指南](CLI_AND_DAEMON.md)。
+---
 
 ## 快速上手
 
@@ -95,7 +86,7 @@ multica login           # 使用你的 Multica 账号认证
 multica daemon start    # 启动本地 Agent 运行时
 ```
 
-daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`）。
+daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动检测 PATH 中可用的 Agent CLI（`claude`、`codex`、`openclaw`、`opencode`）。
 
 ### 2. 确认运行时已连接
 
@@ -105,7 +96,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 
 ### 3. 创建 Agent
 
-进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code 或 Codex），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
+进入 **设置 → Agents**，点击 **新建 Agent**。选择你刚连接的 Runtime，选择 Provider（Claude Code、Codex、OpenClaw 或 OpenCode），并为 Agent 起个名字——它将以这个名字出现在看板、评论和任务分配中。
 
 ### 4. 分配你的第一个任务
 
@@ -123,7 +114,8 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
                             │
                      ┌──────┴───────┐
                      │ Agent Daemon │  （运行在你的机器上）
-                     │ Claude/Codex │
+                     │Claude/Codex/ │
+                     │OpenClaw/Code │
                      └──────────────┘
 ```
 
@@ -132,7 +124,7 @@ daemon 在后台运行，保持你的机器与 Multica 的连接。它会自动
 | 前端 | Next.js 16 (App Router) |
 | 后端 | Go (Chi router, sqlc, gorilla/websocket) |
 | 数据库 | PostgreSQL 17 with pgvector |
-| Agent 运行时 | 本地 daemon 执行 Claude Code 或 Codex |
+| Agent 运行时 | 本地 daemon 执行 Claude Code、Codex、OpenClaw 或 OpenCode |
 
 ## 开发
 

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("Turn coding agents into real teammates")).toBeInTheDocument();
+    expect(screen.getByText("Sign in to Multica")).toBeInTheDocument();
+    expect(screen.getByText("Enter your email to get a login code")).toBeInTheDocument();
     expect(screen.getByLabelText("Email")).toBeInTheDocument();
     expect(
       screen.getByRole("button", { name: "Continue" })

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

@@ -1,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>Turn coding agents into real teammates</CardDescription>
-        </CardHeader>
-        <CardContent>
-          <form id="login-form" onSubmit={handleSendCode} className="space-y-4">
-            <div className="space-y-2">
-              <Label htmlFor="email">Email</Label>
-              <Input
-                id="email"
-                type="email"
-                placeholder="you@example.com"
-                value={email}
-                onChange={(e) => setEmail(e.target.value)}
-                required
-              />
-            </div>
-            {error && (
-              <p className="text-sm text-destructive">{error}</p>
-            )}
-          </form>
-        </CardContent>
-        <CardFooter>
-          <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,226 +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) {
-                            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,471 +1 @@
-"use client";
-
-import { useState, useEffect, useCallback } from "react";
-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 urlIssue = searchParams.get("issue") ?? "";
-
-  const [selectedKey, setSelectedKeyState] = useState(() => urlIssue);
-
-  // Sync from URL when searchParams change (e.g. Next.js navigation)
-  useEffect(() => {
-    setSelectedKeyState(urlIssue);
-  }, [urlIssue]);
-
-  const setSelectedKey = useCallback((key: string) => {
-    setSelectedKeyState(key);
-    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.id}
-            issueId={selected.issue_id}
-            defaultSidebarOpen={false}
-            layoutId="multica_inbox_issue_detail_layout"
-            highlightCommentId={selected.details?.comment_id ?? undefined}
-            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,383 +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 ContentEditor (Tiptap needs real DOM)
-vi.mock("@/features/editor", () => ({
-  ContentEditor: forwardRef(({ defaultValue, onUpdate, placeholder, onSubmit }: any, ref: any) => {
-    const valueRef = useRef(defaultValue || "");
-    const [value, setValue] = useState(defaultValue || "");
-    useImperativeHandle(ref, () => ({
-      getMarkdown: () => valueRef.current,
-      clearContent: () => { valueRef.current = ""; setValue(""); },
-      focus: () => {},
-    }));
-    return (
-      <textarea
-        value={value}
-        onChange={(e) => {
-          valueRef.current = e.target.value;
-          setValue(e.target.value);
-          onUpdate?.(e.target.value);
-        }}
-        onKeyDown={(e) => {
-          if ((e.metaKey || e.ctrlKey) && e.key === "Enter") {
-            onSubmit?.();
-          }
-        }}
-        placeholder={placeholder}
-        data-testid="rich-text-editor"
-      />
-    );
-  }),
-  TitleEditor: forwardRef(({ defaultValue, placeholder, onBlur, onChange }: any, ref: any) => {
-    const valueRef = useRef(defaultValue || "");
-    const [value, setValue] = useState(defaultValue || "");
-    useImperativeHandle(ref, () => ({
-      getText: () => valueRef.current,
-      focus: () => {},
-    }));
-    return (
-      <input
-        value={value}
-        onChange={(e) => {
-          valueRef.current = e.target.value;
-          setValue(e.target.value);
-          onChange?.(e.target.value);
-        }}
-        onBlur={() => onBlur?.(valueRef.current)}
-        placeholder={placeholder}
-        data-testid="title-editor"
-      />
-    );
-  }),
-}));
-
-// Mock Markdown renderer
-vi.mock("@/components/markdown", () => ({
-  Markdown: ({ children }: { children: string }) => <div>{children}</div>,
-}));
-
-// Mock api
-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,71 +1 @@
-"use client";
-
-import { User, Palette, Key, Settings, Users, FolderGit2 } 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";
-import { RepositoriesTab } from "./_components/repositories-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: "repositories", label: "Repositories", icon: FolderGit2 },
-  { 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="repositories"><RepositoriesTab /></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";

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

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