docs: simplify agent guidance

AGENTS.md

@@ -3,8 +3,10 @@
 This file provides guidance to AI agents when working with code in this repository.
 
 > **Single source of truth:** This file is a concise pointer document.
-> All authoritative architecture, coding rules, commands, and conventions
+> All authoritative architecture, coding rules, and conventions
 > live in **CLAUDE.md** at the project root. Read that file first.
+> Use `Makefile`, `package.json`, and `pnpm-workspace.yaml` as the
+> source of truth for the full command list.
 
 ## Quick Reference
 
@@ -12,27 +14,27 @@ This file provides guidance to AI agents when working with code in this reposito
 
 Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.
 
-- `server/` — Go backend (Chi router, sqlc, gorilla/websocket)
-- `apps/web/` — Next.js frontend (App Router)
-- `apps/desktop/` — Electron desktop app
-- `packages/core/` — Headless business logic (Zustand stores, React Query hooks, API client)
-- `packages/ui/` — Atomic UI components (shadcn/Base UI, zero business logic)
-- `packages/views/` — Shared business pages/components
-- `packages/tsconfig/` — Shared TypeScript config
+- `server/` - Go backend (Chi router, sqlc, gorilla/websocket)
+- `apps/web/` - Next.js frontend (App Router)
+- `apps/desktop/` - Electron desktop app
+- `packages/core/` - Headless business logic (Zustand stores, React Query hooks, API client)
+- `packages/ui/` - Atomic UI components (shadcn/Base UI, zero business logic)
+- `packages/views/` - Shared business pages/components
+- `packages/tsconfig/` - Shared TypeScript config
 
 ### State Management (critical)
 
 - **React Query** owns all server state (issues, members, agents, inbox, workspace list)
 - **Zustand** owns all client state (current workspace selection, view filters, drafts, modals)
-- All Zustand stores live in `packages/core/` — never in `packages/views/` or app directories
-- WS events invalidate React Query — never write directly to stores
+- All Zustand stores live in `packages/core/` - never in `packages/views/` or app directories
+- WS events invalidate React Query - never write directly to stores
 
 ### Package Boundaries (hard rules)
 
-- `packages/core/` — zero react-dom, zero localStorage, zero process.env
-- `packages/ui/` — zero `@multica/core` imports
-- `packages/views/` — zero `next/*`, zero `react-router-dom`, use `NavigationAdapter` for routing
-- `apps/web/platform/` — only place for Next.js APIs
+- `packages/core/` - zero react-dom, zero localStorage, zero process.env
+- `packages/ui/` - zero `@multica/core` imports
+- `packages/views/` - zero `next/*`, zero `react-router-dom`, use `NavigationAdapter` for routing
+- `apps/web/platform/` - only place for Next.js APIs
 
 ### Commands
 
@@ -44,4 +46,4 @@ make test             # Go tests
 make check            # Full verification pipeline
 ```
 
-See CLAUDE.md for the complete command reference.
+See CLAUDE.md for the authoritative rules and common commands.

CLAUDE.md

@@ -1,427 +1,226 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for Claude Code when working in this repository. Keep this file short and authoritative: rules here should be hard to infer from code or easy to get wrong.
 
-## Conventions reference
+## Conventions
 
-The single source of truth for **code naming, the i18n translation glossary, and the Chinese voice guide** is the docs site:
+The source of truth for code naming, i18n glossary, and Chinese product voice is:
 
-- **`apps/docs/content/docs/developers/conventions.mdx`** (English)
-- **`apps/docs/content/docs/developers/conventions.zh.mdx`** (Chinese)
+- `apps/docs/content/docs/developers/conventions.mdx`
+- `apps/docs/content/docs/developers/conventions.zh.mdx`
 
-Read that page before:
+Read it before editing translations in `packages/views/locales/`, naming routes/packages/files/DB columns/types, or writing Chinese UI/docs copy. Do not rely on `packages/views/locales/glossary.md`; it is only a redirect stub.
 
-- Writing or editing translations (`packages/views/locales/`)
-- Naming a new route, package, file, DB column, or TS type
-- Writing Chinese product copy (UI strings, error messages, docs)
+## Project Shape
 
-The legacy `packages/views/locales/glossary.md` is now a stub redirecting to the docs page; do not rely on it.
+Multica is an AI-native task management platform for small teams, with agents as first-class assignees that can own issues, comment, and change status.
 
-## Project Context
+- `server/`: Go backend, Chi router, sqlc, gorilla/websocket.
+- `apps/web/`: Next.js App Router.
+- `apps/desktop/`: Electron desktop app.
+- `apps/mobile/`: Expo / React Native iOS app. Read `apps/mobile/CLAUDE.md` before touching it.
+- `packages/core/`: headless business logic, API client, React Query hooks, Zustand stores.
+- `packages/ui/`: atomic UI components only.
+- `packages/views/`: shared business pages/components for web and desktop.
+- `packages/tsconfig/`: shared TypeScript config.
 
-Multica is an AI-native task management platform — like Linear, but with AI agents as first-class citizens.
+Shared packages export raw `.ts` / `.tsx` and are compiled by consuming apps. Dependency direction is `views -> core + ui`; `core` and `ui` must stay independent.
 
-- Agents can be assigned issues, create issues, comment, and change status
-- Supports local (daemon) and cloud agent runtimes
-- Built for 2-10 person AI-native teams
+## State Rules
 
-## Architecture
+Keep server state and client state separate.
 
-**Go backend + monorepo frontend (pnpm workspaces + Turborepo) with shared packages.**
+- TanStack Query owns server state: issues, users, workspaces, inbox, agents, members, and anything fetched from the API.
+- Zustand owns client state: selected workspace, filters, drafts, modals, tab layout, and navigation history.
+- Shared Zustand stores live in `packages/core/`, never in `packages/views/` or app directories.
+- React Context is for platform plumbing only, such as `WorkspaceIdProvider` and `NavigationProvider`.
+- Only auth/workspace stores may call `api.*` directly. Other server interaction belongs in queries/mutations.
+- Workspace-scoped query keys must include `wsId`.
+- Mutations should be optimistic by default: patch locally, send request, roll back on failure, invalidate on settle.
+- WebSocket events invalidate or patch Query cache; they never write directly to Zustand stores.
+- Persist durable preferences/drafts/layout. Do not persist server data or ephemeral UI state.
+- Zustand selectors must return stable references. Do not return freshly allocated objects/arrays from selectors without shallow comparison.
+- Hooks that need workspace context should accept `wsId`; do not call `useWorkspaceId()` internally unless the hook is guaranteed to run under the provider.
 
-- `server/` — Go backend (Chi router, sqlc for DB, gorilla/websocket for real-time)
-- `apps/web/` — Next.js frontend (App Router)
-- `apps/desktop/` — Electron desktop app (electron-vite)
-- `apps/mobile/` — Expo / React Native iOS app. See `apps/mobile/CLAUDE.md`.
-- `packages/core/` — Headless business logic (zero react-dom)
-- `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
+## Package Boundaries
 
-What lives where for sharing purposes is documented in *Sharing Principles* below — read it once.
+These are hard constraints:
 
-### Key Architectural Decisions
+- `packages/core/`: no `react-dom`, `localStorage` (use `StorageAdapter`), `process.env`, or UI libraries.
+- `packages/ui/`: no `@multica/core` imports and no business logic.
+- `packages/views/`: no `next/*`, no `react-router-dom`, no stores. Use `NavigationAdapter`, `useNavigation()`, and `<AppLink>`.
+- `apps/web/platform/`: only place for Next.js navigation/platform APIs.
+- `apps/desktop/src/renderer/src/platform/`: only place for `react-router-dom` navigation wiring.
+- Every workspace under `apps/` and `packages/` must declare directly imported external packages in its own `package.json`.
+- Shared dependencies use `catalog:` from `pnpm-workspace.yaml`; `apps/mobile/` pins Expo/React Native related versions directly.
 
-**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.
+## Sharing Rules
 
-**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.
+Web and desktop share business logic, hooks, stores, components, and views through `packages/core/`, `packages/ui/`, and `packages/views/`.
 
-**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.
+If the same logic exists in both web and desktop, extract it unless it depends on platform APIs:
 
-**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.
+1. Next.js, Electron, or router APIs stay in the app/platform layer.
+2. Headless logic belongs in `packages/core/`.
+3. Shared UI or business views belong in `packages/views/`.
+4. Shared primitives belong in `packages/ui/`.
 
-### State Management
-
-The architecture relies on a strict split between server state and client state. Mixing them is the most common way to break it.
-
-- **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 they're shared.
-- **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.
-
-**Hard rules — these are how the architecture stays coherent:**
-
-- **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.
-
-**Common Zustand footguns to avoid:**
-
-- 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).
-
-## Sharing Principles
-
-The monorepo splits into two share zones:
-
-- **Web and desktop** share business logic, components, hooks, stores, and views through `packages/core/`, `packages/ui/`, and `packages/views/`. Existing model — keep using it.
-- **Mobile (`apps/mobile/`) is independent.** It shares only **types and pure functions** from `@multica/core/`, with `import type` for types (zero runtime coupling). UI, state, hooks, providers, i18n, React version, build pipeline, release cadence — all mobile-owned.
-
-Mobile is locked to the React version that Expo SDK / React Native ships (which lags React main by 6-12 months). Coupling mobile to the root `catalog:` React would block mobile from upgrading on its own schedule.
-
-See `apps/mobile/CLAUDE.md` for the mobile rules and tech-stack baseline.
+Mobile is independent. It may import types and pure functions from `@multica/core`, with `import type` for types, but owns its UI, state, hooks, providers, i18n, React version, build pipeline, and release cadence.
 
 ## Commands
 
+Use the repo scripts as the source of truth. Common commands:
+
 ```bash
-# One-command dev (auto-setup + start everything)
-make dev              # Auto-creates env, installs deps, starts DB, migrates, launches app
-
-# Explicit setup & run (if you prefer separate steps)
-make setup            # First-time: ensure shared DB, create app DB, migrate
-make start            # Start backend + frontend together
-make stop             # Stop app processes for the current checkout
-make db-down          # Stop the shared PostgreSQL container
-
-# Frontend (all commands go through Turborepo)
-pnpm install
-pnpm dev:web          # Next.js dev server (port 3000)
-pnpm dev:desktop      # Electron dev (electron-vite, HMR)
-pnpm build            # Build all frontend apps
-pnpm typecheck        # TypeScript check (all packages + apps via turbo)
-pnpm lint             # ESLint
-pnpm test             # TS tests (Vitest, all packages + apps via turbo)
-
-# Backend (Go)
-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")
+make dev              # auto-setup and start the app
+make start            # start backend + frontend
+make stop             # stop app processes for this checkout
+make server           # run Go server only
+make daemon           # run local daemon
 make test             # Go tests
-make sqlc             # Regenerate sqlc code after editing SQL in server/pkg/db/queries/
-make migrate-up       # Run database migrations
-make migrate-down     # Rollback migrations
-
-# Run a single 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 E2E test (requires backend + frontend running)
-pnpm exec playwright test e2e/tests/specific-test.spec.ts
-
-# Mobile (Expo) — two environments only: dev and staging
-pnpm dev:mobile                  # Metro, dev env       (reads apps/mobile/.env.development.local)
-pnpm dev:mobile:staging          # Metro, staging env   (reads apps/mobile/.env.staging)
-pnpm ios:mobile                  # Native build + install dev-client to iOS Simulator, dev env
-pnpm ios:mobile:staging          # Native build + install dev-client to iOS Simulator, staging env
-pnpm ios:mobile:device           # Native build + install dev-client to USB iPhone, dev env
-pnpm ios:mobile:device:staging   # Native build + install dev-client to USB iPhone, staging env
-# Daily flow: run `pnpm dev:mobile:staging` (or :dev). Only re-run `ios:mobile*` when
-# native code or any expo-*/react-native-* dependency changes (lockfile drift counts).
-
-# Desktop build & package
-pnpm --filter @multica/desktop build      # Compile TS → JS (reads .env.production)
-pnpm --filter @multica/desktop package    # Package into .app/.dmg/.exe (current platform only)
-
-# shadcn — config lives in packages/ui/components.json (Base UI variant, base-nova style)
-pnpm ui:add badge                # Adds component to packages/ui/components/ui/
-
-# Infrastructure
-make db-up            # Start shared PostgreSQL (pgvector/pg17 image)
-make db-down          # Stop shared PostgreSQL
-make db-reset         # Drop + recreate current env's DB, then re-run migrations (local only; stop backend first)
+make sqlc             # regenerate sqlc code after SQL changes
+pnpm install
+pnpm dev:web
+pnpm dev:desktop
+pnpm build
+pnpm typecheck
+pnpm lint
+pnpm test             # TS/Vitest tests through Turborepo
+pnpm exec playwright test
+pnpm ui:add badge     # shadcn/Base UI component into packages/ui
 ```
 
-### CI Requirements
+Worktrees share one PostgreSQL container and get isolated DB names/ports via `.env.worktree`. `make dev` auto-detects this. For manual setup use `make worktree-env`, `make setup-worktree`, and `make start-worktree`.
 
-CI runs on Node 22 and Go 1.26.1 with a `pgvector/pgvector:pg17` PostgreSQL service. See `.github/workflows/ci.yml`.
-
-### Worktree Support
-
-All checkouts share one PostgreSQL container. Isolation is at the database level — each worktree gets its own DB name and unique ports via `.env.worktree`. Main checkouts use `.env`.
-
-`make dev` auto-detects worktrees and handles everything. For explicit control:
-
-```bash
-make worktree-env       # Generate .env.worktree with unique DB/ports
-make setup-worktree     # Setup using .env.worktree
-make start-worktree     # Start using .env.worktree
-```
+CI runs Node 22, Go 1.26.1, and a `pgvector/pgvector:pg17` PostgreSQL service.
 
 ## Coding Rules
 
 - TypeScript strict mode is enabled; keep types explicit.
-- Go code follows standard Go conventions (gofmt, go vet).
-- Keep comments in code **English only**.
-- Prefer existing patterns/components over introducing parallel abstractions.
-- Unless the user explicitly asks for backwards compatibility, do **not** add compatibility layers, fallback paths, dual-write logic, legacy adapters, or temporary shims **for internal, non-boundary code** (a function calling another function in the same package, a component reading its own state, a store helper, etc.).
-- This rule does **not** apply at API boundaries: the desktop app cannot assume the backend it talks to has the same shape as the one it was built against (older desktop installs will outlive any given server build). API response handling must follow the rules in **API Response Compatibility** below — that is a defensive boundary, not a legacy shim.
-- 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.
+- Go follows standard conventions: `gofmt`, `go vet`, checked errors.
+- Code comments must be English.
+- Prefer existing patterns/components over new parallel abstractions.
 - Avoid broad refactors unless required by the task.
-- New global (pre-workspace) routes MUST use a single word (`/login`, `/inbox`) or a `/{noun}/{verb}` pair (`/workspaces/new`). NEVER add hyphenated word-group root routes (`/new-workspace`, `/create-team`) — they collide with common user workspace names and force endless reserved-slug audits. Reserving the noun (`workspaces`) automatically protects the entire `/workspaces/*` subtree.
-- The reserved-slug list lives in **one** place: `server/internal/handler/reserved_slugs.json`. The Go side embeds the JSON; `packages/core/paths/reserved-slugs.ts` is generated from it by `pnpm generate:reserved-slugs`. Edit the JSON, run the generator, commit both. CI re-runs the generator and fails on any drift, so a stale TS file cannot land.
-- When you change a CLI command or flag, an API request/response field, or product behavior that a built-in skill documents (`server/internal/service/builtin_skills/*`), update that skill's `SKILL.md` **and** its `references/*-source-map.md` in the same PR. The built-in skills are source-traced contracts shipped to agents — if the code moves and the skill doesn't, it silently teaches stale behavior.
+- For internal, non-boundary code, do not add compatibility layers, fallback paths, dual writes, legacy adapters, or temporary shims unless explicitly requested.
+- API boundaries are different: installed desktop clients can talk to newer backends, so response parsing must follow the API compatibility rules below.
+- If a flow or API is being replaced and the product is not live, prefer removing the old path instead of preserving both.
+- New global pre-workspace routes must be a single word (`/login`, `/inbox`) or `/{noun}/{verb}` (`/workspaces/new`). Do not add hyphenated root routes like `/new-workspace`.
+- Reserved slugs live in `server/internal/handler/reserved_slugs.json`. Edit it, run `pnpm generate:reserved-slugs`, and commit the generated `packages/core/paths/reserved-slugs.ts`.
+- When changing CLI commands/flags, API fields, or product behavior documented by built-in skills under `server/internal/service/builtin_skills/*`, update the relevant `SKILL.md` and `references/*-source-map.md` in the same PR.
 
-### API Response Compatibility
+## API Compatibility
 
-The desktop app installed on a user's machine is older than any backend it talks to: a user on 0.2.26 will hit a server running 0.3.x, then 0.4.x, then beyond. Every response shape is a contract that **will** drift, and the frontend must survive drift without white-screening. Three concrete incidents already happened from violating this — #2143, #2147, #2192.
+Frontend code must survive backend response drift, especially in installed desktop builds.
 
-When writing code that consumes an API response, follow these rules:
+- Parse API JSON with `parseWithFallback` in `packages/core/api/schema.ts` and a zod schema. Do not cast network JSON to `T`.
+- Endpoint responses consumed by UI logic must pass through a schema before returning.
+- Downstream UI should optional-chain and default fields defensively.
+- Prefer explicit boolean checks (`=== true`) over truthy/falsy checks on server fields.
+- Do not pin critical affordances to one backend boolean; combine signals when possible.
+- Server-driven enum switches need a `default` branch.
+- When adding or changing an endpoint, add/update the schema and include a malformed-response test.
 
-- **Parse, don't cast.** Untyped JSON crossing the network is not `T`. Use `parseWithFallback` in `packages/core/api/schema.ts` with a `zod` schema and an explicit fallback. On validation failure it logs a warning and returns the fallback; it never throws into the UI.
-- **No bare `as` casts on response bodies.** Every endpoint method whose response is consumed by UI logic must run through a schema before returning.
-- **Optional-chain and default everywhere downstream.** Treat every field as possibly missing. Use explicit boolean checks (`=== true`) over truthy/falsy negation, which silently treats `undefined` and `null` as `false`.
-- **Don't pin a UI affordance to a single backend field.** If a button or indicator depends on exactly one boolean from the server, a backend bug deletes it. Combine signals (cursor presence, page length, etc.) so the affordance stays available in the worst case.
-- **Enum drift downgrades, not crashes.** A new server-side enum value should render a generic fallback. `switch` statements on server-driven strings must have a `default` branch.
-- **When you add or change an endpoint:** add the schema in the same PR, and write at least one test that feeds a malformed response through it (missing field, wrong type, `null` array). The test fails closed if a future change breaks the contract.
+## Backend UUID Rules
 
-This is not premature defense — it is the *only* defense for an installed-app architecture. CSR-only browser apps can ship a fix in minutes; an Electron build sitting on a developer's laptop cannot.
+In `server/internal/handler/`, always know where a UUID came from before using it in write queries.
 
-### Backend Handler UUID Parsing Convention
+- Resource path params that may be UUIDs or human-readable IDs must be resolved through loaders such as `loadIssueForUser`, `loadSkillForUser`, `loadAgentForUser`, or `requireDaemonRuntimeAccess`; subsequent writes use the resolved `entity.ID`.
+- Pure UUID inputs from request boundaries use `parseUUIDOrBadRequest(w, s, fieldName)` and return immediately on `ok=false`.
+- Trusted UUID round-trips from sqlc results or test fixtures use `parseUUID(s)`, which panics on invalid input.
+- Outside handlers, `util.ParseUUID(s) (pgtype.UUID, error)` is the safe variant; always check the error.
 
-Every Go handler in `server/internal/handler/` follows these rules. The convention exists because `util.ParseUUID` used to silently return a zero UUID on invalid input, which caused #1661 — a `DELETE` returning 204 success while the SQL `DELETE` matched zero rows.
+## Web/Desktop Features
 
-- **Resource path params that accept either a UUID or a human-readable identifier** (e.g. `chi.URLParam(r, "id")` for an issue, which accepts both `MUL-123` and a UUID) MUST be resolved through the dedicated loader (`loadIssueForUser` / `loadSkillForUser` / `loadAgentForUser` / `requireDaemonRuntimeAccess`). After resolution, all subsequent DB calls — especially `Queries.Delete*` / `Queries.Update*` — MUST use `entity.ID` from the resolved object. Never round-trip the raw URL string through `parseUUID` for a write query.
-- **Pure-UUID inputs from request boundaries** (URL params that are always UUIDs, request body fields, query params, headers) MUST be validated with `parseUUIDOrBadRequest(w, s, fieldName)`. On invalid input it writes a 400 and returns `ok=false` — return immediately.
-- **Trusted UUID round-trips** (sqlc-returned UUIDs being passed back into queries, test fixtures) use `parseUUID(s)` which calls `util.MustParseUUID` and panics on invalid input. A panic here means an unguarded user-input string slipped in — that is a real bug. `chi`'s `middleware.Recoverer` translates the panic into a 500 so the process keeps running.
-- **`util.ParseUUID(s) (pgtype.UUID, error)`** is the only safe variant outside the handler package. Always check the error.
+When adding a shared page or feature for web and desktop:
 
-When adding a `Queries.Delete*` or `Queries.Update*` call, ask: "Where did this UUID come from?" If the answer is "raw user input that hasn't been validated," route it through `parseUUIDOrBadRequest` or a loader first.
+1. Put the page/component in `packages/views/<domain>/`.
+2. Add platform wiring in both `apps/web/app/` and the desktop router, unless the desktop flow is a transition overlay.
+3. Use `useNavigation().push()` or `<AppLink>` in shared code.
+4. Use shared guards/providers such as `DashboardGuard` from `packages/views/layout/`.
+5. Keep platform-only UI in the app or inject it through props/slots.
+6. Hooks that need workspace context should accept `wsId`.
 
-### Dependency Declaration Rule
+CSS for web/desktop is shared from `packages/ui/styles/`. Use semantic tokens such as `bg-background` and `text-muted-foreground`; avoid hardcoded Tailwind colors and duplicated base styles.
 
-Every workspace (`apps/` and `packages/` directories) must explicitly declare all directly imported external packages in its own `package.json`. Relying on pnpm hoist to resolve undeclared imports (phantom deps) is prohibited — it causes production build failures when pnpm creates peer-dep variants.
+## Desktop Rules
 
-- Use `"pkg": "catalog:"` to reference the shared version from `pnpm-workspace.yaml`.
-- CI enforces this via `eslint-plugin-import-x/no-extraneous-dependencies`.
-- Exception: `apps/mobile/` uses pinned versions (not `catalog:`) for packages tied to its own React/Expo version.
+Desktop routing has three categories:
 
-### Package Boundary Rules
+- Session routes: workspace-scoped tab destinations such as `/:slug/issues`.
+- Transition flows: pre-workspace one-shot actions such as create workspace or accept invite. These are `WindowOverlay` state, not routes.
+- Error/stale states: stale workspace tabs should auto-heal by dropping stale tab groups, not render desktop error pages.
 
-These are hard constraints. Violating them breaks the cross-platform architecture:
+More desktop constraints:
 
-- `packages/core/` — zero react-dom, zero localStorage (use StorageAdapter), zero process.env, zero UI libraries. **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.
+- New pre-workspace desktop flows register a `WindowOverlay` type in `stores/window-overlay-store.ts`; do not add them to `routes.tsx`.
+- `setCurrentWorkspace(slug, uuid)` from `@multica/core/platform` is the active workspace source of truth.
+- Code that leaves workspace context must call `setCurrentWorkspace(null, null)` explicitly.
+- Leave/delete workspace flow order: read cached destination, clear current workspace, navigate, then run the mutation.
+- Cross-workspace navigation must go through the navigation adapter so it can call `switchWorkspace(slug, targetPath)`.
+- Full-window desktop views outside the dashboard shell must mount `<DragStrip />` from `@multica/views/platform` as the first flex child. Interactive controls in the top 48px need `WebkitAppRegion: "no-drag"`.
 
-### The No-Duplication Rule (web + desktop)
+## Mobile Rules
 
-**If the same logic exists in both web and desktop, it must be extracted to a shared package.**
+Read `apps/mobile/CLAUDE.md` before touching `apps/mobile/`. It contains the mandatory pre-flight process, import limits, parity rules, tech stack, UI rules, data helpers, realtime strategy, and mobile release flow.
 
-This applies to everything between web and desktop: components, hooks, guards, providers, utility functions. The decision process:
+Root-level reminders:
 
-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).
+- Mobile shares only `@multica/core` types and pure functions.
+- Mobile must match web/desktop product semantics: counts, permissions, enums/transitions, and data identity.
+- Mobile may differ in UI/interaction when the phone context requires it.
 
-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.
+## UI Rules
 
-### Cross-Platform Development Rules (web + desktop)
+- Prefer shadcn/Base UI components over custom implementations. Add them with `pnpm ui:add <component>` from the repo root.
+- Use design tokens and semantic classes; avoid hardcoded colors.
+- Do not introduce extra local state unless the design requires it.
+- Handle overflow, long text, scrolling, alignment, and spacing deliberately.
+- If a component is identical between web and desktop, it belongs in a shared package.
 
-When adding a new page or feature for web/desktop:
+## Testing
 
-1. **New page component** → add to `packages/views/<domain>/`. Never import from `next/*` or `react-router-dom`.
-2. **Wire it in both apps** → add a route in `apps/web/app/` (Next.js page file) AND in the desktop router. **Exception**: pre-workspace transition flows (create workspace, accept invite) are NOT routes on desktop — they're `WindowOverlay` state. See *Desktop-specific Rules → Route categories*.
-3. **Navigation** → use `useNavigation().push()` or `<AppLink>`. Never use framework-specific link/router APIs in shared code.
-4. **Shared guards/providers** → use `DashboardGuard` from `packages/views/layout/`. Don't create separate guard logic per app.
-5. **Platform-specific UI** → if a feature is web-only or desktop-only, keep it in the respective app. Use props slots (`extra`, `topSlot`) on shared layout components to inject platform-specific UI.
-6. **New hooks that need workspace context** → accept `wsId` as parameter instead of reading from `useWorkspaceId()` Context, so they work both inside and outside `WorkspaceIdProvider`.
+Tests follow the code:
 
-### CSS Architecture (web + desktop)
+| What is tested | Location |
+| --- | --- |
+| Shared business logic, stores, queries, hooks | `packages/core/*.test.ts` |
+| Shared UI components, pages, forms, modals | `packages/views/*.test.tsx` |
+| Platform wiring such as cookies, redirects, search params | `apps/web/*.test.tsx` or `apps/desktop/` |
+| End-to-end flows | `e2e/*.spec.ts` |
+| Backend | `server/` Go tests |
 
-Web and desktop share the same CSS foundation from `packages/ui/styles/`.
+Rules:
 
-- **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.
-
-## Mobile-specific Rules
-
-Rules for `apps/mobile/` live in `apps/mobile/CLAUDE.md`. Read it before touching anything in `apps/mobile/` — it covers what may be imported from `@multica/core/`, the React version policy, the build/release pipeline, and the locked tech-stack baseline.
-
-## Desktop-specific Rules
-
-These rules apply to `apps/desktop/` only. Web has different constraints (URL bar, SSR, no tabs) and doesn't share these concerns. Every rule in this section was added after a concrete bug — treat them as enforced, not suggestions.
-
-### Route categories
-
-Every path in the desktop app falls into exactly one category. Choosing the wrong one reproduces bugs we've already fixed.
-
-- **Session routes** — workspace-scoped pages (`/:slug/issues`, `/:slug/settings`). Rendered by the per-tab memory router under `WorkspaceRouteLayout`. These are legitimate tab destinations.
-- **Transition flows** — pre-workspace / one-shot actions (create workspace, accept invite). **NOT routes.** They live as `WindowOverlay` state, dispatched when the navigation adapter sees `push('/workspaces/new')` or `push('/invite/<id>')`. The shared view (`NewWorkspacePage`, `InvitePage`) is the content; the overlay wrapper supplies platform chrome.
-- **Error / stale states** — "workspace not available", tabs pointing at a revoked workspace. **NOT pages.** `WorkspaceRouteLayout` auto-heals by dropping the stale tab group from the store; the user never lands on an explicit error screen. Web keeps `NoAccessPage` (shareable URL makes the error state meaningful); desktop has no URL bar so stale = heal silently.
-
-**Adding a new pre-workspace flow on desktop**: register a new `WindowOverlay` type in `stores/window-overlay-store.ts`. Do NOT add it to `routes.tsx`. If a shared view needs the flow on both platforms, add the route on web (`apps/web/app/(auth)/...`) AND the overlay type on desktop — the shared view component is identical.
-
-### Workspace context
-
-`setCurrentWorkspace(slug, uuid)` from `@multica/core/platform` is the single source of truth for the active workspace. `WorkspaceRouteLayout` sets it on mount; unmount does NOT clear it. Code that leaves workspace context (leave/delete workspace, force-navigate to overlay) must call `setCurrentWorkspace(null, null)` explicitly.
-
-### Workspace destructive operations
-
-Leave / Delete workspace flows must follow this order, otherwise concurrent refetches race and the renderer hard-reloads:
-
-1. Read destination from cached workspace list.
-2. `setCurrentWorkspace(null, null)`.
-3. `navigation.push(destination)`.
-4. THEN `await mutation.mutateAsync(workspaceId)`.
-
-### Tab isolation
-
-Tabs are grouped per workspace in `stores/tab-store.ts`. The TabBar shows only the active workspace's tabs; cross-workspace tab leakage is impossible by construction (no flat global tabs array).
-
-Cross-workspace `push(path)` is detected by the navigation adapter (`platform/navigation.tsx`) and translated into `switchWorkspace(slug, targetPath)` — NOT a navigation within the current tab's router. Don't bypass the adapter; always go through `useNavigation()` from shared code.
-
-### Drag region (macOS)
-
-Every full-window desktop view (anything outside the dashboard shell) must mount `<DragStrip />` from `@multica/views/platform` as the first flex child of the page root, otherwise users can't drag the window. Interactive UI inside the top 48px needs `WebkitAppRegion: "no-drag"` to stay clickable.
-
-## UI/UX Rules
-
-- Prefer shadcn components over custom implementations. Install via `pnpm ui:add <component>` from project root — adds to `packages/ui/components/ui/`. All components use Base UI primitives (`@base-ui/react`), not Radix.
-- Use shadcn design tokens for styling. Avoid hardcoded color values.
-- Do not introduce extra state (useState, context, reducers) unless explicitly required by the design.
-- Pay close attention to **overflow** (truncate long text, scrollable containers), **alignment**, and **spacing** consistency.
-- **If a component is identical between web and desktop, it belongs in a shared package.** Do not copy-paste between apps.
-
-## Testing Rules
-
-### Where to write tests
-
-Tests follow the code, not the app. This is the most important testing principle in this monorepo:
-
-| What you're testing | Where the test lives | Why |
-|---|---|---|
-| Shared business logic (stores, queries, hooks) | `packages/core/*.test.ts` | No DOM needed, pure logic |
-| Shared UI components (pages, forms, modals) | `packages/views/*.test.tsx` | jsdom, no framework mocks |
-| Platform-specific wiring (cookies, redirects, searchParams) | `apps/web/*.test.tsx` or `apps/desktop/` | Needs framework-specific mocks |
-| End-to-end user flows | `e2e/*.spec.ts` | Real browser, real backend |
-
-**Never test shared component behavior in an app's test file.** If a test requires mocking `next/navigation` or `react-router-dom` to test a component from `@multica/views`, the test is in the wrong place — move it to `packages/views/` and mock `@multica/core` instead.
-
-### Test infrastructure
-
-- `packages/core/` — Vitest, Node environment (no DOM)
-- `packages/views/` — Vitest, jsdom environment, `@testing-library/react`
-- `apps/web/` — Vitest, jsdom environment, framework-specific mocks
-- `e2e/` — Playwright
-- `server/` — Go standard `go test`
-
-All test deps are in the pnpm catalog for unified versioning.
-
-### Mocking conventions
-
-- Mock `@multica/core` stores with `vi.hoisted()` + `Object.assign(selectorFn, { getState })` pattern (Zustand stores are both callable and have `.getState()`).
+- Never test shared component behavior in an app test file.
+- `packages/views/` tests must not mock `next/*` or `react-router-dom`.
+- Mock `@multica/core` stores with the Zustand callable-store shape (`selectorFn` plus `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.
+- E2E tests should use `TestApiClient` for setup/teardown.
+- Prefer writing the failing test in the correct package before implementation when the change is behavioral.
 
-### TDD workflow
+## Verification
 
-1. Write failing test in the **correct package** first.
-2. Write implementation.
-3. Run `pnpm test` (Turborepo discovers all packages).
-4. Green → done.
+For code changes, run the narrowest useful checks while iterating, then run broader verification when risk justifies it or when asked.
 
-### 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)`.
-
-## Minimum Pre-Push Checks
-
-```bash
-make check    # Runs all checks: typecheck, unit tests, Go tests, E2E
-```
-
-Run verification only when the user explicitly asks for it.
-
-For targeted checks when requested:
-```bash
-pnpm typecheck        # TypeScript type errors only
-pnpm test             # TS unit tests only (Vitest, all packages)
-make test             # Go tests only
-pnpm exec playwright test   # E2E only (requires backend + frontend running)
-```
-
-## AI Agent Verification Loop
-
-After writing or modifying code, always run the full verification pipeline:
+Useful checks:
 
 ```bash
+pnpm typecheck
+pnpm test
+make test
+pnpm exec playwright test
 make check
 ```
 
-**Workflow:**
-- Write code to satisfy the requirement
-- 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
+Do not claim verification passed unless you ran it. If you skip checks because the change is docs-only or the user asked not to run them, say so.
 
-**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.
+## Commits and Releases
 
-## CLI Release
+- Commits should be atomic and use conventional prefixes: `feat(scope)`, `fix(scope)`, `refactor(scope)`, `docs`, `test(scope)`, `chore(scope)`.
+- A production deployment requires a CLI release tag on `main`: create `v0.x.x`, push it, and let `release.yml` publish binaries and the Homebrew tap.
+- Bump patch by default unless the user specifies a version.
 
-**Prerequisite:** A CLI release must accompany every Production deployment.
+## Domain Reminders
 
-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.
-
-## 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).
+- All queries filter by `workspace_id`; membership gates access; `X-Workspace-ID` selects the workspace.
+- Issue assignees are polymorphic: `assignee_type` plus `assignee_id` can reference a member or an agent.