diff --git a/.changeset/fair-bears-tell.md b/.changeset/fair-bears-tell.md
new file mode 100644
index 000000000..def1bad05
--- /dev/null
+++ b/.changeset/fair-bears-tell.md
@@ -0,0 +1,5 @@
+---
+"@spencer-kit/coder-studio": patch
+---
+
+Stabilize the web test suite and fix workspace UI and dev-browser regressions.
diff --git a/.coder-studio/agent.md b/.coder-studio/agent.md
new file mode 100644
index 000000000..0ac585b7f
--- /dev/null
+++ b/.coder-studio/agent.md
@@ -0,0 +1,82 @@
+# Agent Instructions
+
+## Project Overview
+
+Coder Studio is a monorepo that ships a single CLI npm package containing two internal assembled artifacts: a web frontend UI (`packages/web`) and a Node.js backend runtime (`packages/server`). Provider integrations and shared utilities live in dedicated packages. The project uses pnpm and supports Node-based development and production builds.
+
+## Architecture Map
+
+### Web (frontend_ui)
+- Primary entrypoint for user-facing UI
+- UI/workspace actions: `packages/web/src/features/workspace/actions/` → `packages/server/src/ws/dispatch.ts` → `packages/server/src/commands/*.ts`
+- Agent instructions generation: `packages/web/src/features/workspace/actions/use-agent-instructions-actions.ts` → `packages/server/src/commands/agent-instructions.ts` → `packages/server/src/agent-instructions/agent-generator.ts` → `packages/server/src/agent-instructions/prompt.ts` → `packages/server/src/workspace/intelligence.ts`
+- **Start here** for UI changes, feature hooks, and frontend component work
+
+### Server (backend_runtime)
+- Owns WebSocket dispatch and command execution
+- Command routing: `packages/server/src/ws/dispatch.ts` → `packages/server/src/commands/*.ts`
+- Agent generator: `packages/server/src/agent-instructions/agent-generator.ts` → `prompt.ts` → `workspace/intelligence.ts`
+- **Start here** for server/runtime changes, command handlers, and workspace intelligence
+
+### Providers (provider_integrations)
+- External model/runtime adapters with definition + headless/supervisor builders
+- Execution path: `packages/providers/src/*/definition.ts` + provider-specific headless/supervisor builders → `packages/server/src/provider-runtime/command-runner.ts`
+- **Start here** for provider changes and runtime adapter work
+
+### Core (shared_contracts)
+- Domain types and provider interfaces shared across all packages
+- Key files: `packages/core/src/domain/types.ts`, `packages/core/src/provider/definition.ts`
+- **Inspect first** for type/contract changes that cross package boundaries
+
+### CLI (cli_entrypoint)
+- Command-line launcher and entrypoint behavior
+- **Start here** for CLI behavior and launcher configuration
+
+### Utils (shared_utilities)
+- Reusable utilities consumed by multiple packages
+- Shared helpers and cross-cutting concerns
+
+## Key Directories
+
+- `packages/web` — Primary frontend UI package for user-facing behavior
+- `packages/server` — Backend runtime that owns WebSocket dispatch and command execution
+- `packages/providers` — Provider integration package for external model/runtime adapters
+- `packages/core` — Shared contracts and types used across packages
+- `packages/cli` — Command-line entrypoint and launcher behavior
+- `packages/utils` — Shared utility package reused by multiple packages
+
+## Development Commands
+
+- **Dev server**: `pnpm dev` — Start the development environment
+- **Build all packages**: `pnpm build` — Run production builds for all packages
+- **Lint all packages**: `pnpm lint` — Run linting across the monorepo
+- **CI verification**: `pnpm ci:verify` — Repository-level validation before handoff
+- **Full test suite**: `pnpm ci:test` — Repository-level test validation before handoff
+- **E2E UI tests**: `pnpm e2e-ui` — End-to-end UI validation before handoff
+
+## Workflow Expectations
+
+- Keep changes focused on the requested task.
+- Do not revert user changes unless explicitly asked.
+- Do not use squash merge or delete branches during PR/merge workflows unless the user explicitly asks for squash merging or branch deletion.
+- Prefer the project's existing patterns.
+- Run the relevant verification command before reporting completion.
+
+## File Constraints
+
+- Respect package boundaries and keep changes scoped to the package you are touching unless cross-package edits are required.
+- Avoid unrelated refactors across packages while solving a targeted task.
+- Keep frontend changes in `packages/web` and backend runtime changes in `packages/server` unless the task explicitly crosses layers.
+- Provider logic stays in `packages/providers`. Shared contracts and types live in `packages/core`. CLI entrypoint logic lives in `packages/cli`.
+- Use repository-level verification commands before claiming completion.
+
+## Review Checklist
+
+- Summarize changed files.
+- Report verification commands and results.
+- Call out risks, skipped tests, and assumptions.
+
+## Provider Notes
+
+- Claude Code: use the project rules above.
+- Codex: use the project rules above.
diff --git a/docs/superpowers/plans/2026-06-15-session-token-automation.md b/docs/superpowers/plans/2026-06-15-session-token-automation.md
new file mode 100644
index 000000000..c06c798c0
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-15-session-token-automation.md
@@ -0,0 +1,494 @@
+# Session Token Automation Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace password re-login for agent automation with a loopback-only session bearer token, restrict websocket automation to a small scoped command set, and fix the broken CLI memory payloads that still send legacy arguments.
+
+**Architecture:** Server issues a per-session automation token and injects it into the agent environment. CLI automation forwards the token as a websocket bearer header, auth validates that bearer only for local `/ws`, and websocket dispatch derives a token-scoped authorization context that is narrower than browser cookie access. Core automation capability reporting and local CLI identify/capability output must reflect the same scoped permission set.
+
+**Tech Stack:** TypeScript, Fastify, `@fastify/websocket`, `ws`, Vitest, pnpm monorepo, existing session manager/runtime env injection, existing websocket dispatch/hub, existing CLI `bin.test.ts` coverage.
+
+---
+
+## File Structure
+
+- Create: `packages/server/src/auth/session-token-repo.ts`
+  Holds in-memory automation session tokens keyed by bearer value and exposes create/get/revoke helpers.
+- Modify: `packages/server/src/session/manager.ts`
+  Issues automation tokens during session creation, injects `CODER_STUDIO_SESSION_TOKEN`, injects scoped permissions env, and revokes tokens when sessions end.
+- Modify: `packages/server/src/server.ts`
+  Instantiates the session token repo and passes it into auth/session/ws layers.
+- Modify: `packages/server/src/app.ts`
+  Passes the token repo into auth guard wiring and, if needed, ensures websocket route metadata remains available before auth decisions.
+- Modify: `packages/server/src/auth/plugin.ts`
+  Adds loopback-only bearer authentication for `/ws` while preserving cookie auth for browser requests.
+- Modify: `packages/server/src/auth/index.ts`
+  Re-export any new auth types/helpers needed by app wiring.
+- Modify: `packages/server/src/ws/hub.ts`
+  Stores per-client auth metadata so dispatch can distinguish browser-cookie sockets from token-auth sockets.
+- Modify: `packages/server/src/ws/dispatch.ts`
+  Adds token-scoped authorization and separates activation gating from automation command authorization.
+- Modify: `packages/server/src/commands/automation.ts`
+  Allows capability responses to use scoped permissions instead of unconditional defaults.
+- Modify: `packages/core/src/domain/automation.ts`
+  Defines the reduced automation permission set, adds env-aware permission parsing for local CLI identify/capabilities, and removes `workspace.list` from the token-scoped default surface.
+- Modify: `packages/core/src/domain/automation.test.ts`
+  Covers scoped permission reporting and capability filtering.
+- Modify: `packages/server/src/__tests__/automation/commands.test.ts`
+  Covers scoped capability responses on the command path.
+- Modify: `packages/server/src/__tests__/activation-commands.test.ts`
+  Covers token-auth websocket authorization alongside existing activation behavior.
+- Modify: `packages/server/src/auth/plugin.test.ts`
+  Covers loopback bearer accept/reject behavior.
+- Modify: `packages/server/src/__tests__/ws-hub.test.ts`
+  Covers websocket auth metadata propagation if hub metadata shape changes.
+- Modify: `packages/server/src/__tests__/session-integration.test.ts`
+  Verifies session env injection includes token and scoped permissions.
+- Create or modify: `packages/server/src/__tests__/session-token-repo.test.ts`
+  Verifies token repo create/get/revoke behavior if the repo is non-trivial enough to deserve direct tests.
+- Modify: `packages/cli/src/automation-command-client.ts`
+  Sends `Authorization: Bearer ...` when `CODER_STUDIO_SESSION_TOKEN` is present.
+- Modify: `packages/cli/src/bin.test.ts`
+  Covers websocket client header propagation via existing CLI test harness and fixes memory command expectations.
+- Modify: `packages/cli/src/automation-client.ts`
+  Uses env-derived scoped permissions for local `identify` / `capabilities` output instead of unconditional defaults.
+- Modify: `packages/cli/src/cli.ts`
+  Removes legacy memory `tag/tags` payload fields and updates help examples to current memory taxonomy.
+- Modify: `packages/cli/src/parse-args.ts`
+  Optionally rejects or ignores legacy memory tag usage if that is the chosen cleanup path; otherwise it can keep parsing `--tag` while transport no longer forwards it.
+- Modify: `packages/server/src/commands/memory.test.ts`
+  Adds explicit regression tests for rejecting legacy `tag/tags`.
+
+## Task 1: Core Automation Scope Model
+
+**Files:**
+- Modify: `packages/core/src/domain/automation.ts`
+- Modify: `packages/core/src/domain/automation.test.ts`
+- Modify: `packages/cli/src/automation-client.ts`
+
+- [ ] **Step 1: Write failing core automation scope tests**
+
+Add tests that prove:
+
+- `buildIdentifyResult()` reads a scoped permission env variable when present.
+- `printCapabilities()` and `listAutomationCapabilities()` can produce a reduced set without `workspace.list`.
+- the scoped permission set still includes `session.list`, `terminal.read`, `git.status`, `git.diff`, `memory.*`, and UI action capabilities.
+
+- [ ] **Step 2: Run core tests to verify failure**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core test -- automation.test.ts
+```
+
+Expected: FAIL because identify/capabilities still hard-code `DEFAULT_AGENT_AUTOMATION_PERMISSIONS`.
+
+- [ ] **Step 3: Implement scoped permission helpers**
+
+Add:
+
+- a token-safe automation permission constant, for example `SCOPED_SESSION_AUTOMATION_PERMISSIONS`
+- an env parser such as `parseAutomationPermissionsEnv(value?: string): AutomationPermission[]`
+- support in `buildIdentifyResult()` for an env var such as `CODER_STUDIO_AUTOMATION_PERMISSIONS`
+- CLI `printCapabilities()` to read the same scoped env instead of always using defaults
+
+Keep `DEFAULT_AGENT_AUTOMATION_PERMISSIONS` available for broader in-product contexts if other callers still need it.
+
+- [ ] **Step 4: Run core tests to verify pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core test -- automation.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/core/src/domain/automation.ts packages/core/src/domain/automation.test.ts packages/cli/src/automation-client.ts
+git commit -m "feat(core): add scoped automation permissions"
+```
+
+## Task 2: Session Token Repository And Session Env Injection
+
+**Files:**
+- Create: `packages/server/src/auth/session-token-repo.ts`
+- Create or modify: `packages/server/src/__tests__/session-token-repo.test.ts`
+- Modify: `packages/server/src/session/manager.ts`
+- Modify: `packages/server/src/__tests__/session-integration.test.ts`
+- Modify: `packages/server/src/server.ts`
+
+- [ ] **Step 1: Write failing token lifecycle tests**
+
+Add tests that prove:
+
+- a created session receives `CODER_STUDIO_SESSION_TOKEN`
+- the same session env also receives `CODER_STUDIO_AUTOMATION_PERMISSIONS`
+- tokens are revoked when the session transitions to `ended`
+- hydrated sessions do not regain live automation tokens after restart
+
+- [ ] **Step 2: Run server session tests to verify failure**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- session-integration.test.ts session-hydrate-restart.test.ts
+```
+
+Expected: FAIL because session creation does not issue automation tokens or permission env yet.
+
+- [ ] **Step 3: Implement token repo and session wiring**
+
+Implement a small in-memory repo:
+
+```ts
+interface SessionAutomationTokenRecord {
+  token: string;
+  sessionId: string;
+  workspaceId: string;
+  providerId: string;
+  permissions: readonly AutomationPermission[];
+  createdAt: number;
+}
+```
+
+Design rules:
+
+- use a high-entropy token such as `randomBytes(32).toString("hex")`
+- store tokens in memory only
+- revoke tokens when sessions end, are deleted, or are stopped as part of workspace teardown
+- do not recreate tokens in `hydrate()` because rehydrated sessions are effectively ended when no live terminal exists
+
+Inject into launched agent env:
+
+- `CODER_STUDIO_SESSION_TOKEN`
+- `CODER_STUDIO_AUTOMATION_PERMISSIONS`
+
+- [ ] **Step 4: Run server session tests to verify pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- session-integration.test.ts session-hydrate-restart.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/auth/session-token-repo.ts packages/server/src/__tests__/session-token-repo.test.ts packages/server/src/session/manager.ts packages/server/src/__tests__/session-integration.test.ts packages/server/src/server.ts
+git commit -m "feat(server): issue session automation tokens"
+```
+
+## Task 3: Loopback `/ws` Bearer Authentication
+
+**Files:**
+- Modify: `packages/server/src/auth/plugin.ts`
+- Modify: `packages/server/src/auth/index.ts`
+- Modify: `packages/server/src/app.ts`
+- Modify: `packages/server/src/auth/plugin.test.ts`
+- Modify: `packages/server/src/server.ts`
+
+- [ ] **Step 1: Write failing auth tests**
+
+Add tests that prove:
+
+- `GET /ws` without cookie or bearer still fails with `401` when auth is enabled
+- `GET /ws` with a valid bearer token from `127.0.0.1` is accepted
+- `GET /ws` with an invalid bearer token is rejected
+- non-`/ws` requests cannot use bearer token auth as a cookie substitute
+- non-loopback bearer requests are rejected even if the token exists
+
+- [ ] **Step 2: Run auth tests to verify failure**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- auth/plugin.test.ts
+```
+
+Expected: FAIL because the auth guard only recognizes cookies.
+
+- [ ] **Step 3: Implement loopback bearer auth**
+
+Add helpers in `plugin.ts` to:
+
+- read `Authorization: Bearer ...`
+- verify request path is exactly `/ws`
+- verify request IP is loopback (`127.0.0.1`, `::1`, or equivalent forwarded/local form already trusted by Fastify config)
+- look up the token in the in-memory session token repo
+
+Preserve existing behavior:
+
+- browser cookie auth still works everywhere
+- frontend navigation still redirects to `/login`
+- bearer auth never mints or refreshes auth cookies
+
+- [ ] **Step 4: Run auth tests to verify pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- auth/plugin.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/auth/plugin.ts packages/server/src/auth/index.ts packages/server/src/app.ts packages/server/src/auth/plugin.test.ts packages/server/src/server.ts
+git commit -m "feat(server): allow loopback ws bearer auth"
+```
+
+## Task 4: WebSocket Auth Metadata And Scoped Dispatch Authorization
+
+**Files:**
+- Modify: `packages/server/src/ws/hub.ts`
+- Modify: `packages/server/src/ws/dispatch.ts`
+- Modify: `packages/server/src/__tests__/ws-hub.test.ts`
+- Modify: `packages/server/src/__tests__/activation-commands.test.ts`
+- Modify: `packages/server/src/__tests__/automation/commands.test.ts`
+- Modify: `packages/server/src/commands/automation.ts`
+
+- [ ] **Step 1: Write failing websocket authorization tests**
+
+Add tests that prove:
+
+- token-auth websocket clients can run allowed scoped commands without holding the active browser lease
+- token-auth websocket clients are denied `workspace.list`
+- browser websocket clients keep current activation behavior
+- `automation.capabilities` on the command path can return a scoped permission-derived command list
+
+- [ ] **Step 2: Run websocket/automation tests to verify failure**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- activation-commands.test.ts automation/commands.test.ts ws-hub.test.ts
+```
+
+Expected: FAIL because websocket dispatch only knows activation allowlisting and does not distinguish token-auth clients.
+
+- [ ] **Step 3: Implement scoped auth metadata and dispatch rules**
+
+In `WsHub`:
+
+- derive per-client auth metadata from the authenticated request, for example:
+
+```ts
+type WsClientAuthContext =
+  | { mode: "browser" }
+  | {
+      mode: "session_token";
+      sessionId: string;
+      workspaceId: string;
+      providerId: string;
+      permissions: readonly AutomationPermission[];
+    };
+```
+
+- expose a `getClientAuthContext(clientId)` method through `Broadcaster`
+
+In `dispatch.ts`:
+
+- keep existing activation lease checks for browser websocket clients
+- short-circuit token-auth websocket clients into a token permission check
+- maintain a command-to-permission map for scoped automation commands
+- return a stable authorization error such as:
+
+```ts
+{ code: "forbidden", message: "Command not allowed for this automation session" }
+```
+
+For command naming, remember the server op is `memory.create` while capability names are still advertised as `memory.add`; map both correctly.
+
+- [ ] **Step 4: Run websocket/automation tests to verify pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- activation-commands.test.ts automation/commands.test.ts ws-hub.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/ws/hub.ts packages/server/src/ws/dispatch.ts packages/server/src/__tests__/ws-hub.test.ts packages/server/src/__tests__/activation-commands.test.ts packages/server/src/__tests__/automation/commands.test.ts packages/server/src/commands/automation.ts
+git commit -m "feat(server): scope websocket automation commands"
+```
+
+## Task 5: CLI WebSocket Bearer Propagation
+
+**Files:**
+- Modify: `packages/cli/src/automation-command-client.ts`
+- Modify: `packages/cli/src/bin.test.ts`
+
+- [ ] **Step 1: Write failing CLI transport tests**
+
+Add tests in `bin.test.ts` or a focused helper test if needed that prove:
+
+- when `CODER_STUDIO_SESSION_TOKEN` is set, websocket automation connects with `Authorization: Bearer <token>`
+- when no token is set, the client still connects without auth headers
+
+- [ ] **Step 2: Run CLI tests to verify failure**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio test -- bin.test.ts
+```
+
+Expected: FAIL because websocket creation does not include headers.
+
+- [ ] **Step 3: Implement CLI bearer forwarding**
+
+Update `callCoderStudioCommand()` to read `process.env.CODER_STUDIO_SESSION_TOKEN` and pass:
+
+```ts
+const socket = new WebSocket(wsUrl, {
+  headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+});
+```
+
+Do not read saved auth password or attempt login fallback here.
+
+- [ ] **Step 4: Run CLI tests to verify pass**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio test -- bin.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/cli/src/automation-command-client.ts packages/cli/src/bin.test.ts
+git commit -m "feat(cli): send session token bearer auth"
+```
+
+## Task 6: CLI Memory Payload Cleanup
+
+**Files:**
+- Modify: `packages/cli/src/cli.ts`
+- Modify: `packages/cli/src/parse-args.ts`
+- Modify: `packages/cli/src/bin.test.ts`
+- Modify: `packages/server/src/commands/memory.test.ts`
+- Modify: `packages/core/src/domain/automation.test.ts`
+
+- [ ] **Step 1: Write failing memory regression tests**
+
+Add tests that prove:
+
+- `memory list/search/create/update` no longer send `tag` or `tags`
+- help/examples/capabilities use only current memory types: `feature | todo | bugfix | project | note`
+- server command tests explicitly reject legacy `tag` / `tags` payloads with a validation error
+
+- [ ] **Step 2: Run CLI and memory tests to verify failure**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio test -- bin.test.ts
+pnpm --filter @coder-studio/server test -- memory.test.ts
+pnpm --filter @coder-studio/core test -- automation.test.ts
+```
+
+Expected: FAIL because the CLI still forwards legacy tag payloads and still documents obsolete examples.
+
+- [ ] **Step 3: Implement memory payload cleanup**
+
+In `cli.ts`:
+
+- remove `tag` from `memory.list` and `memory.search`
+- remove `tags` from `memory.create` and `memory.update`
+- update help examples from `decision` to a valid type such as `project` or `note`
+
+In `parse-args.ts`, choose one of these minimal paths and implement it consistently:
+
+- keep parsing `--tag` temporarily but ignore it in transport, or
+- reject `--tag` with a clear error for all memory subcommands
+
+Prefer the second option if it does not create excessive churn, because silent ignore is easy to miss.
+
+- [ ] **Step 4: Run CLI and memory tests to verify pass**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio test -- bin.test.ts
+pnpm --filter @coder-studio/server test -- memory.test.ts
+pnpm --filter @coder-studio/core test -- automation.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/cli/src/cli.ts packages/cli/src/parse-args.ts packages/cli/src/bin.test.ts packages/server/src/commands/memory.test.ts packages/core/src/domain/automation.test.ts
+git commit -m "fix(cli): remove legacy memory payload args"
+```
+
+## Task 7: End-To-End Verification
+
+**Files:**
+- Modify as needed from previous tasks only
+
+- [ ] **Step 1: Run focused package verification**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core test -- automation.test.ts
+pnpm --filter @coder-studio/server test -- auth/plugin.test.ts activation-commands.test.ts automation/commands.test.ts session-integration.test.ts session-hydrate-restart.test.ts memory.test.ts
+pnpm --filter @spencer-kit/coder-studio test -- bin.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run repository verification**
+
+Run:
+
+```bash
+pnpm ci:verify
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Inspect changed files before handoff**
+
+Run:
+
+```bash
+git status --short
+git diff -- packages/core/src/domain/automation.ts packages/server/src/auth/plugin.ts packages/server/src/session/manager.ts packages/server/src/ws/dispatch.ts packages/cli/src/automation-command-client.ts packages/cli/src/cli.ts
+```
+
+Expected: only the planned files are changed for this feature, aside from unrelated pre-existing user changes that must be left intact.
+
+- [ ] **Step 4: Commit final integration work if needed**
+
+```bash
+git add packages/core/src/domain/automation.ts packages/core/src/domain/automation.test.ts packages/server/src/auth/session-token-repo.ts packages/server/src/auth/plugin.ts packages/server/src/auth/index.ts packages/server/src/app.ts packages/server/src/server.ts packages/server/src/session/manager.ts packages/server/src/ws/hub.ts packages/server/src/ws/dispatch.ts packages/server/src/commands/automation.ts packages/server/src/auth/plugin.test.ts packages/server/src/__tests__/activation-commands.test.ts packages/server/src/__tests__/automation/commands.test.ts packages/server/src/__tests__/ws-hub.test.ts packages/server/src/__tests__/session-integration.test.ts packages/server/src/__tests__/session-token-repo.test.ts packages/cli/src/automation-command-client.ts packages/cli/src/automation-client.ts packages/cli/src/cli.ts packages/cli/src/parse-args.ts packages/cli/src/bin.test.ts packages/server/src/commands/memory.test.ts
+git commit -m "feat(server): add scoped session token automation"
+```
+
+- [ ] **Step 5: Handoff summary**
+
+Report:
+
+- changed files
+- focused test commands and results
+- `pnpm ci:verify` result
+- any residual risks around loopback IP detection or future IPC migration
diff --git a/docs/superpowers/plans/2026-06-15-startup-readiness-and-startup-path.md b/docs/superpowers/plans/2026-06-15-startup-readiness-and-startup-path.md
new file mode 100644
index 000000000..d7841a2de
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-15-startup-readiness-and-startup-path.md
@@ -0,0 +1,363 @@
+# Startup Readiness And Startup Path Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Eliminate false startup timeout reports from the global/production `coder-studio` CLI and reduce actual time-to-ready by shortening the server's pre-listen critical path.
+
+**Architecture:** Keep the PM2-managed startup model unchanged. Fix the CLI first so it distinguishes "still starting" from "startup failed", then extend the wait budget to match real production startup. On the server side, move non-critical warmup work off the `await app.listen(...)` path so `runtime.json` can be written earlier without changing steady-state behavior.
+
+**Tech Stack:** TypeScript, Vitest, PM2-managed CLI startup, Fastify server, runtime.json readiness file.
+
+---
+
+### Task 1: Fix The CLI Readiness Heuristic
+
+**Files:**
+- Modify: `packages/cli/src/pm2-control.ts`
+- Modify: `packages/cli/src/pm2-control.test.ts`
+- Modify: `packages/cli/src/cli.ts`
+- Test: `packages/cli/src/pm2-control.test.ts`
+
+- [ ] **Step 1: Add failing tests for slow-but-successful startup**
+
+In `packages/cli/src/pm2-control.test.ts`, add cases that prove the CLI should keep waiting while PM2 is still online and only fail when PM2 has clearly failed:
+
+```ts
+it("keeps waiting while pm2 stays online and runtime.json is still pending", async () => {
+  start.mockImplementationOnce(
+    (_config: unknown, callback: (error: Error | null, apps: unknown[]) => void) => {
+      callback(null, [{ pm_id: 1 }]);
+    }
+  );
+
+  let readinessChecks = 0;
+  describeProcess.mockImplementation(
+    (_name: string, callback: (error: Error | null, result: unknown[]) => void) => {
+      readinessChecks += 1;
+      callback(null, [{ pid: 424242, pm2_env: { status: "online", restart_time: 0 } }]);
+    }
+  );
+
+  const pendingStart = startManagedServer({
+    script: "/cli/dist/esm/server-runner.js",
+    cwd: "/repo",
+    waitMs: 50,
+  });
+
+  setTimeout(() => {
+    writeRuntimeConfig({
+      host: "127.0.0.1",
+      port: 4187,
+      pid: 424242,
+      token: "test-token",
+      serverInstanceId: "server-1",
+      startedAt: Date.now(),
+    });
+  }, 10);
+
+  await expect(pendingStart).resolves.toBeUndefined();
+  expect(readinessChecks).toBeGreaterThan(0);
+});
+
+it("fails startup when pm2 enters errored before runtime.json is written", async () => {
+  start.mockImplementationOnce(
+    (_config: unknown, callback: (error: Error | null, apps: unknown[]) => void) => {
+      callback(null, [{ pm_id: 1 }]);
+    }
+  );
+
+  describeProcess.mockImplementationOnce(
+    (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+      callback(null, [{ pid: 424242, pm2_env: { status: "errored", restart_time: 1 } }])
+  );
+
+  await expect(
+    startManagedServer({
+      script: "/cli/dist/esm/server-runner.js",
+      cwd: "/repo",
+      waitMs: 50,
+    })
+  ).rejects.toThrow("the managed process entered the errored state");
+});
+```
+
+- [ ] **Step 2: Run the CLI readiness tests and confirm the new slow-start case fails**
+
+Run:
+
+```bash
+pnpm vitest packages/cli/src/pm2-control.test.ts --run
+```
+
+Expected: FAIL because the current readiness loop only accepts `runtime.json` and times out even while PM2 remains online.
+
+- [ ] **Step 3: Refactor readiness into explicit states**
+
+In `packages/cli/src/pm2-control.ts`, replace the open-coded polling logic with a helper that returns `ready`, `pending`, or `failed`:
+
+```ts
+interface RuntimeReadinessState {
+  kind: "ready" | "pending" | "failed";
+  reason?: string;
+}
+
+async function readRuntimeReadiness(pm2: Pm2Module): Promise<RuntimeReadinessState> {
+  if (readRuntimeConfig()) {
+    return { kind: "ready" };
+  }
+
+  const processes = await describeManagedServer(pm2);
+  const process = processes[0];
+  if (!process) {
+    return {
+      kind: "failed",
+      reason: "the managed process exited before runtime data was written",
+    };
+  }
+
+  const status = process.pm2_env?.status;
+  if (status === "errored" || status === "stopped") {
+    return {
+      kind: "failed",
+      reason: `the managed process entered the ${status} state`,
+    };
+  }
+
+  return { kind: "pending" };
+}
+```
+
+Update `waitForRuntimeReady(...)` to use this helper so:
+- `ready` returns immediately
+- `failed` throws the existing startup error with log excerpts
+- `pending` continues polling until the deadline
+
+- [ ] **Step 4: Increase the managed-start wait window**
+
+In `packages/cli/src/cli.ts`, change:
+
+```ts
+const MANAGED_SERVER_WAIT_MS = 15000;
+```
+
+This keeps the change centralized for both `coder-studio serve` and `coder-studio open`.
+
+- [ ] **Step 5: Re-run the CLI readiness tests**
+
+Run:
+
+```bash
+pnpm vitest packages/cli/src/pm2-control.test.ts --run
+```
+
+Expected: PASS, including the slow-start success case and errored-state failure case.
+
+- [ ] **Step 6: Commit the CLI readiness fix**
+
+```bash
+git add packages/cli/src/cli.ts packages/cli/src/pm2-control.ts packages/cli/src/pm2-control.test.ts
+git commit -m "fix(cli): tolerate slow managed startup"
+```
+
+### Task 2: Move Non-Critical Warmup Off The Pre-Listen Path
+
+**Files:**
+- Modify: `packages/server/src/server.ts`
+- Modify: `packages/server/src/__tests__/server-runtime-config.test.ts`
+- Test: `packages/server/src/__tests__/server-runtime-config.test.ts`
+
+- [ ] **Step 1: Add a failing runtime-config timing test**
+
+In `packages/server/src/__tests__/server-runtime-config.test.ts`, add a timing-oriented assertion that proves startup writes `runtime.json` promptly enough for the CLI contract. Keep it black-box and avoid adding test-only hooks to `createServer`.
+
+Use a simple upper bound around server creation:
+
+```ts
+it("writes runtime config during startup", async () => {
+  const startedAt = Date.now();
+
+  server = await createRuntimeServer({
+    stateDir: join(testHomeDir, "server-state"),
+    host: "127.0.0.1",
+    port: 0,
+    writeRuntimeConfig: true,
+  });
+
+  const runtime = readRuntimeConfig();
+  expect(runtime).toEqual(
+    expect.objectContaining({
+      host: "127.0.0.1",
+      pid: process.pid,
+    })
+  );
+  expect(runtime?.startedAt).toBeGreaterThanOrEqual(startedAt);
+});
+```
+
+This test is intentionally narrow: it guards the readiness side effect without introducing unsupported `__testOverrides`.
+
+- [ ] **Step 2: Run the server runtime-config test**
+
+Run:
+
+```bash
+pnpm vitest packages/server/src/__tests__/server-runtime-config.test.ts --run
+```
+
+Expected: PASS before refactor. This is a characterization test that protects the existing contract while the startup order changes.
+
+- [ ] **Step 3: Defer the clearly non-critical warmup calls**
+
+In `packages/server/src/server.ts`, move these calls so they no longer block `await app.listen(...)` and `writeRuntimeConfig(...)`:
+
+```ts
+workAnalysisService.startAutoScan();
+workspaceMgr.hydrateWatchers();
+await agentInstructionPublisher.syncAllOpenWorkspaces();
+updateService.start();
+monitoringService.start();
+```
+
+Refactor them into a post-listen function with failure isolation:
+
+```ts
+const runPostListenWarmup = async () => {
+  workAnalysisService.startAutoScan();
+  workspaceMgr.hydrateWatchers();
+  await agentInstructionPublisher.syncAllOpenWorkspaces();
+  updateService.start();
+  monitoringService.start();
+};
+```
+
+Invoke it only after:
+
+```ts
+await app.listen({ host: config.host, port: config.port });
+writeRuntimeConfig(runtime);
+void runPostListenWarmup().catch((error) => {
+  app.log.warn({ err: error }, "post-listen warmup failed");
+});
+```
+
+Keep these on the pre-listen path:
+- `buildFastifyApp(...)`
+- `await sessionMgr.hydrate()`
+- supervisor wiring needed for normal runtime construction
+- `await app.listen(...)`
+- `writeRuntimeConfig(...)`
+
+- [ ] **Step 4: Re-run the server runtime-config test**
+
+Run:
+
+```bash
+pnpm vitest packages/server/src/__tests__/server-runtime-config.test.ts --run
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit the startup-path reduction**
+
+```bash
+git add packages/server/src/server.ts packages/server/src/__tests__/server-runtime-config.test.ts
+git commit -m "perf(server): defer non-critical startup warmup"
+```
+
+### Task 3: Add Startup Phase Timing Logs
+
+**Files:**
+- Modify: `packages/server/src/server.ts`
+- Test: `packages/server/src/__tests__/server-runtime-config.test.ts`
+
+- [ ] **Step 1: Add minimal startup timing instrumentation**
+
+In `packages/server/src/server.ts`, add small, flat timing logs for the highest-value phases:
+
+```ts
+const startupAt = Date.now();
+
+function logStartupPhase(app: FastifyInstance | null, label: string, startedAt: number) {
+  const elapsedMs = Date.now() - startedAt;
+  if (app) {
+    app.log.info({ elapsedMs }, `[startup] ${label}`);
+    return;
+  }
+
+  console.log(`[startup] ${label}=${elapsedMs}ms`);
+}
+```
+
+Log at least:
+- `builtinSkillSync`
+- `buildFastifyApp`
+- `sessionHydrate`
+- `listen`
+- `runtimeConfigWritten`
+- `postListenWarmupScheduled`
+
+Keep the output single-line and grep-friendly so future production log checks can identify where startup time is spent.
+
+- [ ] **Step 2: Add or extend a test only if the repo already has a stable log assertion pattern**
+
+If there is no stable existing pattern for asserting server startup logs, skip a dedicated log assertion test and rely on the targeted runtime-config test plus manual diff review. Do not add brittle logger mocks just to satisfy instrumentation.
+
+- [ ] **Step 3: Run the targeted tests**
+
+Run:
+
+```bash
+pnpm vitest packages/cli/src/pm2-control.test.ts packages/server/src/__tests__/server-runtime-config.test.ts --run
+```
+
+Expected: PASS.
+
+- [ ] **Step 4: Commit the timing diagnostics**
+
+```bash
+git add packages/server/src/server.ts packages/server/src/__tests__/server-runtime-config.test.ts
+git commit -m "chore(server): log startup phase timings"
+```
+
+### Task 4: Repository Verification
+
+**Files:**
+- Test: `packages/cli/src/pm2-control.test.ts`
+- Test: `packages/server/src/__tests__/server-runtime-config.test.ts`
+
+- [ ] **Step 1: Run targeted startup tests**
+
+Run:
+
+```bash
+pnpm vitest packages/cli/src/pm2-control.test.ts packages/server/src/__tests__/server-runtime-config.test.ts --run
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run repository verification**
+
+Run:
+
+```bash
+pnpm ci:verify
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Review the scoped diff**
+
+Run:
+
+```bash
+git diff -- packages/cli/src/cli.ts packages/cli/src/pm2-control.ts packages/cli/src/pm2-control.test.ts packages/server/src/server.ts packages/server/src/__tests__/server-runtime-config.test.ts docs/superpowers/plans/2026-06-15-startup-readiness-and-startup-path.md
+```
+
+Expected: Only readiness detection, wait budget, deferred warmup, startup timing, and the saved plan should appear.
+
+- [ ] **Step 4: Commit the verification pass**
+
+```bash
+git add packages/cli/src/cli.ts packages/cli/src/pm2-control.ts packages/cli/src/pm2-control.test.ts packages/server/src/server.ts packages/server/src/__tests__/server-runtime-config.test.ts docs/superpowers/plans/2026-06-15-startup-readiness-and-startup-path.md
+git commit -m "test: verify startup readiness changes"
+```
diff --git a/docs/superpowers/plans/2026-06-16-dev-browser-query-sw-https-implementation.md b/docs/superpowers/plans/2026-06-16-dev-browser-query-sw-https-implementation.md
new file mode 100644
index 000000000..48d6d4ebe
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-16-dev-browser-query-sw-https-implementation.md
@@ -0,0 +1,833 @@
+# Dev Browser Query + SW + HTTPS Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Rebuild the built-in browser so loopback previews keep the real visible pathname, root-scope service-worker interception only applies to bound loopback preview traffic, and non-loopback IP access to Coder Studio automatically uses HTTPS with generated local certificates.
+
+**Architecture:** Keep loopback preview fetching behind the hidden `/dev-browser/session/:id/proxy` route, but change the browser-visible URL to a query-token form such as `/app/?__cs_sid=dev_1`. The first visible-path request is proxied server-side and receives a lightweight bootstrap that registers a root-scope service worker, binds the iframe client to the session, and removes the hidden query token with `history.replaceState`. The legacy `/dev-browser/session/:id/` shell remains as the fallback entry for insecure or service-worker-ineligible contexts. Auto-HTTPS applies only to the Coder Studio transport layer; preview targets remain loopback `http` in v1.
+
+**Tech Stack:** TypeScript, Fastify, React, Jotai, Vite, Vitest, Service Worker, `node-forge`
+
+---
+
+### Task 1: Replace The Session URL Model With Visible Query URLs
+
+**Files:**
+- Create: `packages/server/src/dev-browser/browser-url.ts`
+- Create: `packages/server/src/dev-browser/browser-url.test.ts`
+- Modify: `packages/server/src/routes/dev-browser.ts`
+- Modify: `packages/server/src/routes/dev-browser.test.ts`
+- Test: `packages/server/src/dev-browser/browser-url.test.ts`
+- Test: `packages/server/src/routes/dev-browser.test.ts`
+
+- [ ] **Step 1: Write the failing URL helper test**
+
+```ts
+import { describe, expect, it } from "vitest";
+import { DEV_BROWSER_SESSION_QUERY_PARAM, buildDevBrowserVisibleUrl } from "./browser-url.js";
+
+describe("buildDevBrowserVisibleUrl", () => {
+  it("preserves the target path and folds the session id into the query string", () => {
+    expect(
+      buildDevBrowserVisibleUrl({
+        sessionId: "dev_1",
+        targetPath: "/app/?draft=1",
+        targetHash: "#top",
+      })
+    ).toBe(`/app/?draft=1&${DEV_BROWSER_SESSION_QUERY_PARAM}=dev_1#top`);
+  });
+});
+```
+
+- [ ] **Step 2: Run the helper test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/dev-browser/browser-url.test.ts`
+Expected: FAIL because `browser-url.ts` does not exist yet.
+
+- [ ] **Step 3: Write the failing route test for the new session response shape**
+
+```ts
+it("creates visible browser urls and retains the legacy fallback entry", async () => {
+  const created = await createSession("/app/?draft=1#top");
+
+  expect(created.browserUrl).toBe(`/app/?draft=1&__cs_sid=${created.id}#top`);
+  expect(created.fallbackBrowserUrl).toBe(`/dev-browser/session/${created.id}/`);
+  expect(created.browserProxyBase).toBe(`/dev-browser/session/${created.id}/proxy`);
+});
+```
+
+- [ ] **Step 4: Run the route test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/routes/dev-browser.test.ts -t "creates visible browser urls and retains the legacy fallback entry"`
+Expected: FAIL because `browserUrl` still points at `/dev-browser/session/:id/` and `fallbackBrowserUrl` is missing.
+
+- [ ] **Step 5: Implement the visible URL helper and session serialization**
+
+```ts
+export const DEV_BROWSER_SESSION_QUERY_PARAM = "__cs_sid";
+
+export function buildDevBrowserVisibleUrl(input: {
+  sessionId: string;
+  targetPath: string;
+  targetHash: string;
+}): string {
+  const parsed = new URL(input.targetPath || "/", "http://coder-studio.local");
+  parsed.searchParams.set(DEV_BROWSER_SESSION_QUERY_PARAM, input.sessionId);
+  return `${parsed.pathname}${parsed.search}${input.targetHash}`;
+}
+
+function fallbackBrowserUrl(id: string): string {
+  return `/dev-browser/session/${id}/`;
+}
+
+function serializeSession(session: DevBrowserSession) {
+  return {
+    id: session.id,
+    browserUrl: buildDevBrowserVisibleUrl({
+      sessionId: session.id,
+      targetPath: session.targetPath,
+      targetHash: session.targetHash,
+    }),
+    fallbackBrowserUrl: fallbackBrowserUrl(session.id),
+    browserProxyBase: browserProxyBase(session.id),
+    displayUrl: session.displayUrl,
+    targetOrigin: session.targetOrigin,
+    targetPath: session.targetPath,
+    targetHash: session.targetHash,
+    expiresAt: session.expiresAt,
+    ...(session.preserveStudioPlatformPaths ? { preserveStudioPlatformPaths: true } : {}),
+  };
+}
+```
+
+- [ ] **Step 6: Run the focused server tests to verify they pass**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/dev-browser/browser-url.test.ts src/routes/dev-browser.test.ts`
+Expected: PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/server/src/dev-browser/browser-url.ts \
+  packages/server/src/dev-browser/browser-url.test.ts \
+  packages/server/src/routes/dev-browser.ts \
+  packages/server/src/routes/dev-browser.test.ts
+git commit -m "feat: add visible dev browser session urls"
+```
+
+### Task 2: Add Visible-Path Proxying And Root-Scope Service Worker Routing
+
+**Files:**
+- Modify: `packages/server/src/dev-browser/proxy-headers.ts`
+- Modify: `packages/server/src/dev-browser/proxy-headers.test.ts`
+- Modify: `packages/server/src/routes/dev-browser.ts`
+- Modify: `packages/server/src/routes/dev-browser.test.ts`
+- Modify: `packages/web/public/dev-browser-sw.js`
+- Modify: `packages/web/src/features/dev-browser/dev-browser-sw.test.ts`
+- Test: `packages/server/src/dev-browser/proxy-headers.test.ts`
+- Test: `packages/server/src/routes/dev-browser.test.ts`
+- Test: `packages/web/src/features/dev-browser/dev-browser-sw.test.ts`
+
+- [ ] **Step 1: Write the failing route test for the first visible-path request**
+
+```ts
+it("serves visible-path bootstrap html for the first query-based request", async () => {
+  const created = await createSession("/app/?draft=1#top");
+  const response = await app.inject({
+    method: "GET",
+    url: created.browserUrl,
+  });
+
+  expect(response.statusCode).toBe(200);
+  expect(response.body).toContain('<script src="/assets/app.js"></script>');
+  expect(response.body).toContain('navigator.serviceWorker.register("/dev-browser-sw.js", { scope: "/" })');
+  expect(response.body).toContain('searchParams.delete("__cs_sid")');
+  expect(response.body).not.toContain(`${created.browserProxyBase}/assets/app.js`);
+});
+```
+
+- [ ] **Step 2: Run the route test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/routes/dev-browser.test.ts -t "serves visible-path bootstrap html for the first query-based request"`
+Expected: FAIL because `/app/?__cs_sid=...` currently falls through to the wrong route model.
+
+- [ ] **Step 3: Write the failing redirect and service worker mapper tests**
+
+```ts
+it("rewrites loopback redirects back into visible paths for visible-mode proxy responses", () => {
+  expect(
+    rewriteVisibleLocationHeader("http://localhost:8000/dashboard?tab=1", {
+      port: 8000,
+      targetOrigin: "http://127.0.0.1:8000",
+    })
+  ).toBe("/dashboard?tab=1");
+});
+
+it("maps controlled visible-path requests to the hidden proxy base", () => {
+  const harness = loadHarness();
+  expect(
+    harness.mapRequest({
+      requestUrl: "https://studio.example/assets/app.js",
+      clientSessionId: "dev_1",
+      sessions: {
+        dev_1: {
+          id: "dev_1",
+          browserProxyBase: "/dev-browser/session/dev_1/proxy",
+          targetOrigin: "http://127.0.0.1:8000",
+          targetPath: "/app/",
+        },
+      },
+    })
+  ).toEqual({
+    mode: "visible",
+    url: "https://studio.example/dev-browser/session/dev_1/proxy/assets/app.js",
+  });
+});
+
+it("passes non-loopback cross-origin requests through unchanged", () => {
+  const harness = loadHarness();
+  expect(
+    harness.mapRequest({
+      requestUrl: "https://example.com/app.js",
+      clientSessionId: "dev_1",
+      sessions: {
+        dev_1: {
+          id: "dev_1",
+          browserProxyBase: "/dev-browser/session/dev_1/proxy",
+          targetOrigin: "http://127.0.0.1:8000",
+          targetPath: "/app/",
+        },
+      },
+    })
+  ).toBeNull();
+});
+```
+
+- [ ] **Step 4: Run the mapper and redirect tests to verify they fail**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/dev-browser/proxy-headers.test.ts src/routes/dev-browser.test.ts && pnpm --filter @coder-studio/web exec vitest run src/features/dev-browser/dev-browser-sw.test.ts`
+Expected: FAIL because there is no visible-path redirect helper, the service worker still assumes `/dev-browser/` scope, and query-based bootstrap requests are not handled.
+
+- [ ] **Step 5: Implement visible-mode proxy handling and root-scope service worker routing**
+
+```ts
+export function rewriteVisibleLocationHeader(
+  location: string,
+  input: { browserProxyBase?: string; port: number; targetOrigin: string }
+): string {
+  if (location.startsWith("/") && !location.startsWith("//")) {
+    return location;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(location, input.targetOrigin);
+  } catch {
+    return location;
+  }
+
+  const proxied = toProxiedLoopbackUrl(parsed, input);
+  if (!proxied) {
+    return location;
+  }
+
+  const proxiedUrl = new URL(`http://coder-studio.local${proxied}`);
+  return `${proxiedUrl.pathname}${proxiedUrl.search}${proxiedUrl.hash}`;
+}
+
+app.addHook("preHandler", async (request, reply) => {
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    return;
+  }
+
+  const incomingUrl = new URL(request.url, "http://coder-studio.local");
+  const sessionId = incomingUrl.searchParams.get(DEV_BROWSER_SESSION_QUERY_PARAM);
+  if (!sessionId) {
+    return;
+  }
+
+  const session = sessions.get(sessionId);
+  if (!session) {
+    reply.status(410).send({ error: "dev_browser_session_missing" });
+    return reply;
+  }
+
+  await proxyRequest(request, reply, session, {
+    mode: "visible",
+    requestUrl: incomingUrl,
+    stripSessionQuery: true,
+  });
+  return reply;
+});
+```
+
+```js
+const DEV_BROWSER_PROXY_MODE_HEADER = "x-coder-studio-dev-browser-mode";
+
+function mapRequestToProxy(input) {
+  const requestUrl = new URL(input.requestUrl);
+  const session = getSessionForRequest(input);
+  if (!session) {
+    return null;
+  }
+
+  if (requestUrl.pathname.startsWith(session.browserProxyBase)) {
+    return null;
+  }
+
+  if (requestUrl.origin === self.location.origin) {
+    if (requestUrl.pathname.startsWith("/dev-browser/")) {
+      return null;
+    }
+    if (shouldBypassStudioPath(requestUrl, session)) {
+      return null;
+    }
+    return {
+      mode: "visible",
+      url: `${self.location.origin}${session.browserProxyBase}${requestUrl.pathname}${requestUrl.search}`,
+    };
+  }
+
+  if (!isLoopbackUrlForSession(requestUrl, session)) {
+    return null;
+  }
+
+  return {
+    mode: "visible",
+    url: `${self.location.origin}${session.browserProxyBase}${requestUrl.pathname}${requestUrl.search}`,
+  };
+}
+
+self.addEventListener("fetch", (event) => {
+  const mapped = mapRequestToProxy({
+    requestUrl: event.request.url,
+    referrer: event.request.referrer,
+    clientSessionId: event.clientId ? clientSessions.get(event.clientId) : undefined,
+    sessions: Object.fromEntries(sessions.entries()),
+  });
+  if (!mapped) {
+    return;
+  }
+
+  if (event.request.mode === "navigate" && event.resultingClientId && event.clientId) {
+    const sessionId = clientSessions.get(event.clientId);
+    if (sessionId) {
+      clientSessions.set(event.resultingClientId, sessionId);
+    }
+  }
+
+  const headers = new Headers(event.request.headers);
+  headers.set(DEV_BROWSER_PROXY_MODE_HEADER, mapped.mode);
+  const proxiedRequest = new Request(mapped.url, {
+    method: event.request.method,
+    headers,
+    body: event.request.body,
+    mode: event.request.mode,
+    credentials: event.request.credentials,
+    cache: event.request.cache,
+    redirect: event.request.redirect,
+    referrer: event.request.referrer,
+    referrerPolicy: event.request.referrerPolicy,
+    integrity: event.request.integrity,
+    keepalive: event.request.keepalive,
+    signal: event.request.signal,
+  });
+  event.respondWith(fetch(proxiedRequest));
+});
+```
+
+- [ ] **Step 6: Run the focused tests to verify they pass**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/dev-browser/proxy-headers.test.ts src/routes/dev-browser.test.ts && pnpm --filter @coder-studio/web exec vitest run src/features/dev-browser/dev-browser-sw.test.ts`
+Expected: PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/server/src/dev-browser/proxy-headers.ts \
+  packages/server/src/dev-browser/proxy-headers.test.ts \
+  packages/server/src/routes/dev-browser.ts \
+  packages/server/src/routes/dev-browser.test.ts \
+  packages/web/public/dev-browser-sw.js \
+  packages/web/src/features/dev-browser/dev-browser-sw.test.ts
+git commit -m "feat: add visible-path dev browser routing"
+```
+
+### Task 3: Wire The Web Client And Vite Dev Server To The New URL Model
+
+**Files:**
+- Modify: `packages/web/src/features/dev-browser/api.ts`
+- Modify: `packages/web/src/features/dev-browser/api.test.ts`
+- Modify: `packages/web/src/features/dev-browser/dev-browser-surface.tsx`
+- Modify: `packages/web/src/features/dev-browser/dev-browser-surface.test.tsx`
+- Modify: `packages/web/vite.config.ts`
+- Modify: `packages/web/src/features/dev-browser/dev-browser-vite-proxy.test.ts`
+- Test: `packages/web/src/features/dev-browser/api.test.ts`
+- Test: `packages/web/src/features/dev-browser/dev-browser-surface.test.tsx`
+- Test: `packages/web/src/features/dev-browser/dev-browser-vite-proxy.test.ts`
+
+- [ ] **Step 1: Write the failing API and iframe-source tests**
+
+```ts
+it("parses the visible browserUrl and fallbackBrowserUrl from create-session responses", async () => {
+  const fetchMock = vi.fn(async () =>
+    new Response(
+      JSON.stringify({
+        id: "dev_1",
+        browserUrl: "/app/?__cs_sid=dev_1",
+        fallbackBrowserUrl: "/dev-browser/session/dev_1/",
+        browserProxyBase: "/dev-browser/session/dev_1/proxy",
+        targetOrigin: "http://127.0.0.1:8000",
+      }),
+      { status: 200, headers: { "content-type": "application/json" } }
+    )
+  );
+  vi.stubGlobal("fetch", fetchMock);
+
+  const created = await createDevBrowserSession("localhost:8000");
+
+  expect(created.browserUrl).toBe("/app/?__cs_sid=dev_1");
+  expect(created.fallbackBrowserUrl).toBe("/dev-browser/session/dev_1/");
+});
+```
+
+```ts
+it("uses the visible browser url when service workers are supported", async () => {
+  enableServiceWorkerSupport();
+  const activeTab = browserTab("browser-1", null);
+  const store = createWorkspaceStore([activeTab], activeTab);
+
+  render(<DevBrowserSurface workspaceId="ws-test" browserTab={activeTab} />, {
+    wrapper: wrapperFor(store),
+  });
+
+  await submitLocalUrl(userEvent.setup(), "localhost:8000");
+
+  expect(await screen.findByTitle("Browser")).toHaveAttribute("src", "/app/?__cs_sid=dev_1");
+});
+```
+
+- [ ] **Step 2: Run the focused tests to verify they fail**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/dev-browser/api.test.ts src/features/dev-browser/dev-browser-surface.test.tsx`
+Expected: FAIL because the API type has no `fallbackBrowserUrl` and the surface still expects the old `/dev-browser/session/:id/` source.
+
+- [ ] **Step 3: Write the failing fallback and Vite bootstrap proxy tests**
+
+```ts
+it("falls back to the legacy browser entry when service workers are unavailable", async () => {
+  Object.defineProperty(window, "isSecureContext", { configurable: true, value: false });
+  Object.defineProperty(window.navigator, "serviceWorker", {
+    configurable: true,
+    value: undefined,
+  });
+  const activeTab = browserTab("browser-1", null);
+  const store = createWorkspaceStore([activeTab], activeTab);
+
+  render(<DevBrowserSurface workspaceId="ws-test" browserTab={activeTab} />, {
+    wrapper: wrapperFor(store),
+  });
+
+  await submitLocalUrl(userEvent.setup(), "localhost:8000");
+
+  expect(await screen.findByTitle("Browser")).toHaveAttribute("src", "/dev-browser/session/dev_1/");
+});
+```
+
+```ts
+it("proxies visible-path bootstrap requests with __cs_sid to the backend", async () => {
+  const response = await fetch(`http://127.0.0.1:${vitePort}/app/?__cs_sid=test`);
+
+  expect(response.status).toBe(200);
+  expect(await response.text()).toContain("proxied dev browser session");
+});
+```
+
+- [ ] **Step 4: Run the fallback and Vite tests to verify they fail**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/dev-browser/dev-browser-surface.test.tsx src/features/dev-browser/dev-browser-vite-proxy.test.ts`
+Expected: FAIL because the surface has no explicit visible/fallback split and Vite only proxies `/dev-browser/session`.
+
+- [ ] **Step 5: Implement the API shape, iframe source selection, and Vite query bootstrap proxy**
+
+```ts
+export interface DevBrowserSessionResponse {
+  browserProxyBase: string;
+  browserUrl: string;
+  fallbackBrowserUrl: string;
+  displayUrl?: string;
+  expiresAt?: number;
+  id: string;
+  targetOrigin: string;
+}
+```
+
+```tsx
+const frameSrc =
+  serviceWorkerSupported || !session?.fallbackBrowserUrl
+    ? session?.browserUrl ?? null
+    : session.fallbackBrowserUrl;
+
+<iframe
+  className="dev-browser-frame"
+  title={t("dev_browser.title")}
+  src={frameSrc ?? undefined}
+  sandbox="allow-scripts allow-forms allow-same-origin allow-popups"
+/>;
+```
+
+```ts
+function isDevBrowserBootstrapRequest(url: string | undefined): boolean {
+  if (!url) {
+    return false;
+  }
+  const parsed = new URL(url, "http://vite.local");
+  return parsed.searchParams.has("__cs_sid");
+}
+
+function devBrowserBootstrapProxyPlugin() {
+  return {
+    name: "dev-browser-bootstrap-proxy",
+    configureServer(server: ViteDevServer) {
+      server.middlewares.use(async (req, res, next) => {
+        if (!isDevBrowserBootstrapRequest(req.url)) {
+          next();
+          return;
+        }
+
+        const upstream = await fetch(new URL(req.url!, backendHttpTarget), {
+          method: req.method,
+          headers: new Headers(req.headers as Record<string, string>),
+          body: req.method === "GET" || req.method === "HEAD" ? undefined : req,
+        });
+        res.statusCode = upstream.status;
+        upstream.headers.forEach((value, key) => res.setHeader(key, value));
+        res.end(Buffer.from(await upstream.arrayBuffer()));
+      });
+    },
+  };
+}
+```
+
+- [ ] **Step 6: Run the focused web tests to verify they pass**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/dev-browser/api.test.ts src/features/dev-browser/dev-browser-surface.test.tsx src/features/dev-browser/dev-browser-vite-proxy.test.ts`
+Expected: PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/web/src/features/dev-browser/api.ts \
+  packages/web/src/features/dev-browser/api.test.ts \
+  packages/web/src/features/dev-browser/dev-browser-surface.tsx \
+  packages/web/src/features/dev-browser/dev-browser-surface.test.tsx \
+  packages/web/vite.config.ts \
+  packages/web/src/features/dev-browser/dev-browser-vite-proxy.test.ts
+git commit -m "feat: wire visible dev browser urls through the web client"
+```
+
+### Task 4: Auto-Enable HTTPS For Non-Loopback IP Access
+
+**Files:**
+- Modify: `packages/server/package.json`
+- Create: `packages/server/src/dev-browser/local-https.ts`
+- Create: `packages/server/src/dev-browser/local-https.test.ts`
+- Create: `packages/server/src/__tests__/server-transport.test.ts`
+- Modify: `packages/server/src/app.ts`
+- Modify: `packages/server/src/server.ts`
+- Modify: `pnpm-lock.yaml`
+- Test: `packages/server/src/dev-browser/local-https.test.ts`
+- Test: `packages/server/src/__tests__/server-transport.test.ts`
+
+- [ ] **Step 1: Write the failing transport helper tests**
+
+```ts
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ensureLocalHttpsMaterial, shouldAutoEnableHttps } from "./local-https.js";
+
+describe("local dev-browser https", () => {
+  const tempDir = mkdtempSync(join(tmpdir(), "cs-local-https-"));
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("only auto-enables https for wildcard or non-loopback ip hosts", () => {
+    expect(shouldAutoEnableHttps("localhost")).toBe(false);
+    expect(shouldAutoEnableHttps("127.0.0.1")).toBe(false);
+    expect(shouldAutoEnableHttps("192.168.1.20")).toBe(true);
+    expect(shouldAutoEnableHttps("0.0.0.0")).toBe(true);
+  });
+
+  it("reuses generated certificate material from the state directory", () => {
+    const first = ensureLocalHttpsMaterial({
+      stateRoot: tempDir,
+      primaryHost: "192.168.1.20",
+    });
+    const second = ensureLocalHttpsMaterial({
+      stateRoot: tempDir,
+      primaryHost: "192.168.1.20",
+    });
+
+    expect(first.cert).toContain("BEGIN CERTIFICATE");
+    expect(first.key).toContain("BEGIN PRIVATE KEY");
+    expect(second.cert).toBe(first.cert);
+    expect(second.key).toBe(first.key);
+  });
+});
+```
+
+- [ ] **Step 2: Run the helper test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/dev-browser/local-https.test.ts`
+Expected: FAIL because `local-https.ts` does not exist and there is no HTTPS material generator.
+
+- [ ] **Step 3: Write the failing server transport wiring test**
+
+```ts
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+describe("createServer transport", () => {
+  let tempDir = "";
+
+  afterEach(() => {
+    vi.resetModules();
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("passes generated https options into buildFastifyApp for LAN hosts", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "cs-server-transport-"));
+    const listen = vi.fn().mockResolvedValue(undefined);
+    const close = vi.fn().mockResolvedValue(undefined);
+    const address = vi.fn(() => ({ port: 4173 }));
+    const buildFastifyApp = vi.fn(async ({ fastifyOptions }) => ({
+      listen,
+      close,
+      server: { address },
+      log: { info: vi.fn(), warn: vi.fn() },
+    }));
+
+    vi.doMock("../app.js", () => ({
+      buildFastifyApp,
+    }));
+
+    const { createServer } = await import("../server.js");
+    const server = await createServer({
+      host: "192.168.1.20",
+      port: 4173,
+      stateDir: join(tempDir, "state"),
+      uploadsDir: join(tempDir, "uploads"),
+    });
+    await server.stop();
+
+    expect(buildFastifyApp).toHaveBeenCalledWith(
+      expect.objectContaining({
+        fastifyOptions: {
+          https: expect.objectContaining({
+            cert: expect.stringContaining("BEGIN CERTIFICATE"),
+            key: expect.stringContaining("BEGIN PRIVATE KEY"),
+          }),
+        },
+      })
+    );
+  });
+});
+```
+
+- [ ] **Step 4: Run the transport wiring test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/__tests__/server-transport.test.ts`
+Expected: FAIL because `buildFastifyApp` does not accept `fastifyOptions` and `createServer` never generates HTTPS options.
+
+- [ ] **Step 5: Implement local HTTPS material generation and server wiring**
+
+```json
+{
+  "dependencies": {
+    "node-forge": "^1.3.1"
+  }
+}
+```
+
+```ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import forge from "node-forge";
+
+export function shouldAutoEnableHttps(host: string): boolean {
+  return host === "0.0.0.0" || host === "::" || /^[0-9a-f:.]+$/i.test(host) && !/^127(?:\.\d{1,3}){3}$/.test(host) && host !== "::1";
+}
+
+export function ensureLocalHttpsMaterial(input: {
+  stateRoot: string;
+  primaryHost: string;
+}): { cert: string; key: string; ca: string } {
+  const tlsDir = join(input.stateRoot, "tls");
+  const certPath = join(tlsDir, "dev-browser-cert.pem");
+  const keyPath = join(tlsDir, "dev-browser-key.pem");
+  const caPath = join(tlsDir, "dev-browser-ca.pem");
+
+  if (existsSync(certPath) && existsSync(keyPath) && existsSync(caPath)) {
+    return {
+      cert: readFileSync(certPath, "utf8"),
+      key: readFileSync(keyPath, "utf8"),
+      ca: readFileSync(caPath, "utf8"),
+    };
+  }
+
+  mkdirSync(tlsDir, { recursive: true });
+  const keys = forge.pki.rsa.generateKeyPair(2048);
+  const cert = forge.pki.createCertificate();
+  cert.publicKey = keys.publicKey;
+  cert.serialNumber = String(Date.now());
+  cert.validity.notBefore = new Date(Date.now() - 60_000);
+  cert.validity.notAfter = new Date(Date.now() + 365 * 24 * 60 * 60 * 1_000);
+  cert.setSubject([{ name: "commonName", value: input.primaryHost }]);
+  cert.setIssuer([{ name: "commonName", value: "Coder Studio Local Dev Browser CA" }]);
+  cert.setExtensions([
+    { name: "basicConstraints", cA: true },
+    { name: "keyUsage", keyCertSign: true, digitalSignature: true },
+    {
+      name: "subjectAltName",
+      altNames: [
+        ...(input.primaryHost === "localhost" || input.primaryHost.endsWith(".localhost")
+          ? [{ type: 2, value: input.primaryHost }]
+          : []),
+        ...(input.primaryHost !== "localhost" && !input.primaryHost.endsWith(".localhost")
+          ? [{ type: 7, ip: input.primaryHost }]
+          : []),
+        { type: 2, value: "localhost" },
+        { type: 2, value: "*.localhost" },
+        { type: 7, ip: "127.0.0.1" },
+        { type: 7, ip: "::1" },
+      ],
+    },
+  ]);
+  cert.sign(keys.privateKey, forge.md.sha256.create());
+
+  const keyPem = forge.pki.privateKeyToPem(keys.privateKey);
+  const certPem = forge.pki.certificateToPem(cert);
+  writeFileSync(keyPath, keyPem, "utf8");
+  writeFileSync(certPath, certPem, "utf8");
+  writeFileSync(caPath, certPem, "utf8");
+
+  return { cert: certPem, key: keyPem, ca: certPem };
+}
+```
+
+```ts
+interface AppDeps {
+  // existing deps...
+  fastifyOptions?: Pick<FastifyServerOptions, "https">;
+}
+
+const app = Fastify({
+  ...deps.fastifyOptions,
+  logger: deps.logger ?? {
+    level: "info",
+    transport: {
+      target: "pino-pretty",
+      options: {
+        translateTime: "HH:MM:ss Z",
+        ignore: "pid,hostname",
+      },
+    },
+  },
+});
+```
+
+```ts
+const httpsMaterial = shouldAutoEnableHttps(config.host)
+  ? ensureLocalHttpsMaterial({
+      stateRoot,
+      primaryHost: config.host,
+    })
+  : null;
+
+const app = await buildFastifyApp({
+  wsHub,
+  webRoot: config.webRoot,
+  workspaceMgr,
+  config,
+  authSessionRepo,
+  authLoginBlockRepo,
+  sessionTokenRepo,
+  appearanceAssetRepo,
+  fastifyOptions: httpsMaterial
+    ? {
+        https: {
+          cert: httpsMaterial.cert,
+          key: httpsMaterial.key,
+          ca: httpsMaterial.ca,
+        },
+      }
+    : undefined,
+});
+
+const listenProtocol = httpsMaterial ? "https" : "http";
+console.log(`Server listening on ${listenProtocol}://${config.host}:${actualPort}`);
+if (httpsMaterial) {
+  console.log(
+    "If the browser shows a local certificate warning, open the HTTPS URL manually and proceed once."
+  );
+}
+```
+
+- [ ] **Step 6: Run the focused HTTPS tests to verify they pass**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/dev-browser/local-https.test.ts src/__tests__/server-transport.test.ts`
+Expected: PASS
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/server/package.json \
+  pnpm-lock.yaml \
+  packages/server/src/dev-browser/local-https.ts \
+  packages/server/src/dev-browser/local-https.test.ts \
+  packages/server/src/__tests__/server-transport.test.ts \
+  packages/server/src/app.ts \
+  packages/server/src/server.ts
+git commit -m "feat: auto-enable https for remote dev browser access"
+```
+
+### Task 5: Full Verification
+
+**Files:**
+- Modify: `docs/superpowers/specs/2026-06-16-dev-browser-query-sw-https-design.md` only if implementation forces an explicit spec clarification
+- Test: repository working tree
+
+- [ ] **Step 1: Run the focused server and web suites**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/dev-browser/browser-url.test.ts src/dev-browser/proxy-headers.test.ts src/dev-browser/local-https.test.ts src/routes/dev-browser.test.ts src/__tests__/server-transport.test.ts && pnpm --filter @coder-studio/web exec vitest run src/features/dev-browser/api.test.ts src/features/dev-browser/dev-browser-sw.test.ts src/features/dev-browser/dev-browser-surface.test.tsx src/features/dev-browser/dev-browser-vite-proxy.test.ts`
+Expected: PASS
+
+- [ ] **Step 2: Run package-level tests for the touched packages**
+
+Run: `pnpm --filter @coder-studio/server test && pnpm --filter @coder-studio/web test`
+Expected: PASS
+
+- [ ] **Step 3: Run repository verification**
+
+Run: `pnpm ci:verify`
+Expected: PASS
+
+- [ ] **Step 4: Check git status before handoff**
+
+Run: `git status --short`
+Expected: clean working tree except for any deliberate spec clarification or release metadata added during implementation.
+
+- [ ] **Step 5: Final handoff commit if Task 5 required follow-up changes**
+
+```bash
+git add -A
+git commit -m "chore: finalize dev browser query sw https rollout"
+```
diff --git a/docs/superpowers/plans/2026-06-18-workspace-memory-taxonomy-status.md b/docs/superpowers/plans/2026-06-18-workspace-memory-taxonomy-status.md
new file mode 100644
index 000000000..5745af624
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-18-workspace-memory-taxonomy-status.md
@@ -0,0 +1,756 @@
+# Workspace Memory Taxonomy Status Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace workspace memory types with `wiki | issue | todo | note`, add status for actionable memory, preserve legacy data through normalization, and fix the adjacent memory dropdown and split-divider UI issues.
+
+**Architecture:** The canonical memory contract lives in `packages/core/src/domain/memory.ts`; server command schemas and JSON storage consume those helpers so legacy aliases normalize before persistence. Web UI renders ordered type/status controls from the core constants and keeps CSS-only split handle changes scoped to existing pane divider styles.
+
+**Tech Stack:** TypeScript, React, Jotai, Vitest, Zod, pnpm workspace scripts, CSS guard tests.
+
+---
+
+## File Structure
+
+- Modify `packages/core/src/domain/memory.ts`
+  - Add `WorkspaceMemoryType` and `WorkspaceMemoryStatus` constant objects.
+  - Replace canonical type order with `wiki`, `issue`, `todo`, `note`.
+  - Add legacy alias normalization and status validation helpers.
+- Modify `packages/core/src/domain/memory.test.ts`
+  - Cover canonical type/status constants, legacy alias normalization, and status applicability.
+- Modify `packages/core/src/domain/automation.ts`
+  - Update memory capability schemas/examples to canonical types and optional status.
+- Modify `packages/core/src/domain/automation.test.ts`
+  - Assert canonical type strings and absence of old type strings in memory automation metadata.
+- Modify `packages/server/src/storage/repositories/memory-repo.ts`
+  - Normalize legacy stored types, read/write `status`, default status for actionable types, and clear status for non-actionable types.
+- Modify `packages/server/src/storage/repositories/memory-repo.test.ts`
+  - Cover canonical persistence, legacy migration, and status rules.
+- Modify `packages/server/src/commands/memory.ts`
+  - Accept canonical types plus legacy aliases, optional status, and normalize before repository calls.
+- Modify `packages/server/src/commands/memory.test.ts`
+  - Cover canonical command flow, alias input compatibility, status validation, and old-file read behavior.
+- Modify `packages/cli/src/parse-args.ts`
+  - Add optional `--status` parsing for `memory add` and `memory update`.
+- Modify `packages/cli/src/bin.test.ts`
+  - Cover CLI status forwarding and canonical type metadata expectations that already live in this file.
+- Modify `packages/web/src/locales/en.json` and `packages/web/src/locales/zh.json`
+  - Replace memory type labels and add status labels.
+- Modify `packages/web/src/features/workspace/actions/use-memory-panel.ts`
+  - Include optional memory `status` in create/update inputs.
+- Modify `packages/web/src/features/workspace/views/shared/memory-panel.tsx`
+  - Render four memory types in order; render status controls only for `issue` and `todo`; include status badge metadata only for actionable entries.
+- Modify `packages/web/src/features/workspace/views/shared/memory-panel.test.tsx`
+  - Cover four-type order, actionable-only status controls, create/update payload status, and dropdown close behavior.
+- Modify `packages/web/src/components/ui/select/index.test.tsx`
+  - Keep shared desktop listbox closing behavior covered; update only if current test fails during implementation.
+- Modify `packages/web/src/styles/components.css`
+  - Update memory badge variants to canonical types/status if needed.
+  - Lower/neutralize pane divider visual overlay while preserving hit target.
+- Modify `packages/web/src/styles/memory-panel.guard.test.ts`
+  - Assert only canonical badge variants remain.
+- Modify `packages/web/src/styles/pane-layout-divider.theme.test.ts`
+  - Assert pane divider remains transparent and does not use elevated z-index.
+- Optional modify `packages/server/src/skills/builtin/definitions/coder-studio-memory.ts`
+  - Update built-in memory skill examples/type descriptions if they mention old types.
+- Optional modify `packages/cli/src/cli.ts`
+  - Update CLI help examples if they mention old memory types or need `--status` examples.
+
+## Task 1: Core Memory Contract
+
+**Files:**
+- Modify: `packages/core/src/domain/memory.test.ts`
+- Modify: `packages/core/src/domain/memory.ts`
+
+- [ ] **Step 1: Write failing core tests**
+
+Update `packages/core/src/domain/memory.test.ts` to expect:
+
+```ts
+expect(WORKSPACE_MEMORY_TYPES).toEqual(["wiki", "issue", "todo", "note"]);
+expect(WORKSPACE_MEMORY_STATUSES).toEqual([
+  "not_started",
+  "in_progress",
+  "pending_verification",
+  "completed",
+]);
+expect(normalizeWorkspaceMemoryType("project")).toBe("wiki");
+expect(normalizeWorkspaceMemoryType("bugfix")).toBe("issue");
+expect(normalizeWorkspaceMemoryType("feature")).toBe("wiki");
+expect(isActionableWorkspaceMemoryType("wiki")).toBe(false);
+expect(isActionableWorkspaceMemoryType("issue")).toBe(true);
+```
+
+Add validation expectations:
+
+```ts
+expect(validateWorkspaceMemoryInput({ type: "issue", content: "Broken", status: "in_progress" }))
+  .toEqual({ type: "issue", content: "Broken", status: "in_progress" });
+expect(validateWorkspaceMemoryInput({ type: "todo", content: "Ship", status: undefined }))
+  .toEqual({ type: "todo", content: "Ship", status: "not_started" });
+expect(validateWorkspaceMemoryInput({ type: "wiki", content: "Use pnpm", status: "completed" }))
+  .toEqual({ type: "wiki", content: "Use pnpm" });
+expect(validateWorkspaceMemoryInput({ type: "bugfix", content: "Old", status: "completed" }))
+  .toEqual({ type: "issue", content: "Old", status: "completed" });
+expect(() =>
+  validateWorkspaceMemoryInput({ type: "issue", content: "Broken", status: "unknown" })
+).toThrow("Invalid memory status");
+```
+
+- [ ] **Step 2: Run core memory test to verify it fails**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core exec vitest run src/domain/memory.test.ts
+```
+
+Expected: FAIL because `WORKSPACE_MEMORY_STATUSES`, `normalizeWorkspaceMemoryType`, and `isActionableWorkspaceMemoryType` do not exist and old type constants are still present.
+
+- [ ] **Step 3: Implement core contract**
+
+In `packages/core/src/domain/memory.ts`:
+
+- Replace the old type array with a `WorkspaceMemoryType` constant object and ordered `WORKSPACE_MEMORY_TYPES`.
+- Add `WorkspaceMemoryStatus`, `WORKSPACE_MEMORY_STATUSES`, and `WorkspaceMemoryStatus` type alias.
+- Add `WorkspaceMemoryEntry.status?: WorkspaceMemoryStatus`.
+- Add `WorkspaceMemoryInput.status?: unknown`.
+- Add `normalizeWorkspaceMemoryType(value: unknown): WorkspaceMemoryType | undefined`.
+- Add `isActionableWorkspaceMemoryType(type: WorkspaceMemoryType): boolean`.
+- Add `normalizeWorkspaceMemoryStatus(value: unknown): WorkspaceMemoryStatus | undefined`.
+- Update `validateWorkspaceMemoryInput()` so it:
+  - accepts canonical types and aliases `project`, `bugfix`, `feature`;
+  - throws `"Invalid memory type"` for unknown values;
+  - trims content as before;
+  - throws `"Invalid memory status"` when `status` is present and invalid;
+  - defaults missing status to `not_started` for `issue` and `todo`;
+  - omits status for `wiki` and `note`.
+
+- [ ] **Step 4: Run core memory test to verify it passes**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core exec vitest run src/domain/memory.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/core/src/domain/memory.ts packages/core/src/domain/memory.test.ts
+git commit -m "feat(core): normalize workspace memory taxonomy"
+```
+
+## Task 2: Automation Metadata
+
+**Files:**
+- Modify: `packages/core/src/domain/automation.test.ts`
+- Modify: `packages/core/src/domain/automation.ts`
+
+- [ ] **Step 1: Write failing automation tests**
+
+Update the memory capability assertions in `packages/core/src/domain/automation.test.ts`:
+
+```ts
+expect(memoryAdd?.inputSchema).toEqual({
+  workspaceId: "string",
+  type: "wiki | issue | todo | note",
+  content: "string",
+  status: "not_started | in_progress | pending_verification | completed optional",
+});
+expect(memoryUpdate?.inputSchema).toEqual({
+  workspaceId: "string",
+  id: "string",
+  type: "wiki | issue | todo | note optional",
+  content: "string optional",
+  status: "not_started | in_progress | pending_verification | completed optional",
+});
+expect(memoryAdd?.examples).toEqual([
+  'coder-studio memory add --workspace ws_123 --type wiki --content "..." --json',
+]);
+expect(memoryExamples).toSatisfy((examples) =>
+  examples.every((example) => !example.includes("--type project"))
+);
+expect(JSON.stringify(memoryCapabilities)).not.toContain("bugfix");
+expect(JSON.stringify(memoryCapabilities)).not.toContain("feature | todo | bugfix | project | note");
+```
+
+- [ ] **Step 2: Run automation test to verify it fails**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core exec vitest run src/domain/automation.test.ts
+```
+
+Expected: FAIL because automation metadata still lists old types and no status.
+
+- [ ] **Step 3: Update automation metadata**
+
+In `packages/core/src/domain/automation.ts`:
+
+- Change `memory.add.inputSchema.type` to `"wiki | issue | todo | note"`.
+- Add `memory.add.inputSchema.status`.
+- Change `memory.add.examples[0]` to use `--type wiki`.
+- Change `memory.update.inputSchema.type` to `"wiki | issue | todo | note optional"`.
+- Add `memory.update.inputSchema.status`.
+- Keep memory search/list descriptions content/type based.
+
+- [ ] **Step 4: Run core tests**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core exec vitest run src/domain/automation.test.ts src/domain/memory.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/core/src/domain/automation.ts packages/core/src/domain/automation.test.ts
+git commit -m "docs(core): update memory automation metadata"
+```
+
+## Task 3: Server Repository Normalization And Status
+
+**Files:**
+- Modify: `packages/server/src/storage/repositories/memory-repo.test.ts`
+- Modify: `packages/server/src/storage/repositories/memory-repo.ts`
+
+- [ ] **Step 1: Write failing repository tests**
+
+Update existing tests that create `type: "project"` to expect persisted `type: "wiki"` or change create inputs to `type: "wiki"` where alias compatibility is not under test.
+
+Add a legacy normalization test:
+
+```ts
+it("normalizes supported legacy memory types while reading workspace files", () => {
+  const workspaceId = "ws-legacy-types";
+  const filePath = join(tempDir, "memory", "workspaces", `${workspaceId}.json`);
+  mkdirSync(join(tempDir, "memory", "workspaces"), { recursive: true });
+  writeFileSync(filePath, JSON.stringify({
+    version: 1,
+    workspaceId,
+    entries: {
+      project: { id: "project", workspaceId, type: "project", content: "Project conventions.", source: { kind: "user" }, createdAt: 1, updatedAt: 1 },
+      bugfix: { id: "bugfix", workspaceId, type: "bugfix", content: "Broken select.", source: { kind: "user" }, createdAt: 2, updatedAt: 2 },
+      feature: { id: "feature", workspaceId, type: "feature", content: "Existing capability.", source: { kind: "user" }, createdAt: 3, updatedAt: 3 }
+    }
+  }, null, 2) + "\n");
+
+  expect(repo.list({ workspaceId }).map((entry) => [entry.id, entry.type])).toEqual([
+    ["feature", "wiki"],
+    ["bugfix", "issue"],
+    ["project", "wiki"],
+  ]);
+});
+```
+
+Add status tests:
+
+```ts
+const issue = repo.create({ workspaceId: "ws-1", type: "issue", content: "Broken", status: "in_progress", source: { kind: "user" } });
+expect(issue.status).toBe("in_progress");
+const todo = repo.create({ workspaceId: "ws-1", type: "todo", content: "Ship", source: { kind: "user" } });
+expect(todo.status).toBe("not_started");
+const wiki = repo.create({ workspaceId: "ws-1", type: "wiki", content: "Use pnpm", status: "completed", source: { kind: "user" } });
+expect(wiki).not.toHaveProperty("status");
+expect(repo.update({ workspaceId: "ws-1", id: issue.id, type: "note" })).not.toHaveProperty("status");
+```
+
+- [ ] **Step 2: Run repository test to verify it fails**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/storage/repositories/memory-repo.test.ts
+```
+
+Expected: FAIL because repository inputs do not accept status and old type expectations are still hard-coded.
+
+- [ ] **Step 3: Implement repository behavior**
+
+In `packages/server/src/storage/repositories/memory-repo.ts`:
+
+- Add optional `status?: WorkspaceMemoryStatus` to `MemoryCreateInput` and `MemoryUpdateInput`.
+- Pass `status` into `validateWorkspaceMemoryInput()`.
+- Include `...(validated.status ? { status: validated.status } : {})` in created/updated entries.
+- Ensure update removes stale `status` when validated result omits it. Do this by destructuring old status away:
+
+```ts
+const { status: _oldStatus, ...existingWithoutStatus } = existing;
+const updated: WorkspaceMemoryEntry = {
+  ...existingWithoutStatus,
+  type: validated.type,
+  content: validated.content,
+  updatedAt: this.now(),
+  ...(validated.status ? { status: validated.status } : {}),
+  ...(input.archivedAt !== undefined ? { archivedAt: input.archivedAt } : {}),
+};
+```
+
+- Keep soft delete behavior unchanged.
+
+- [ ] **Step 4: Run repository test**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/storage/repositories/memory-repo.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/storage/repositories/memory-repo.ts packages/server/src/storage/repositories/memory-repo.test.ts
+git commit -m "feat(server): normalize memory repository types"
+```
+
+## Task 4: Server Commands
+
+**Files:**
+- Modify: `packages/server/src/commands/memory.test.ts`
+- Modify: `packages/server/src/commands/memory.ts`
+
+- [ ] **Step 1: Write failing command tests**
+
+Update the main command flow to create `type: "wiki"` and expect `type: "wiki"`.
+
+Add alias compatibility assertions:
+
+```ts
+const legacyProject = await dispatch(command("memory.create", {
+  workspaceId: "ws-1",
+  type: "project",
+  content: "Legacy project alias.",
+}), ctx);
+expect(legacyProject.ok).toBe(true);
+expect((legacyProject.data as WorkspaceMemoryEntry).type).toBe("wiki");
+
+const legacyBugfix = await dispatch(command("memory.create", {
+  workspaceId: "ws-1",
+  type: "bugfix",
+  content: "Legacy bugfix alias.",
+  status: "pending_verification",
+}), ctx);
+expect(legacyBugfix.ok).toBe(true);
+expect(legacyBugfix.data).toMatchObject({ type: "issue", status: "pending_verification" });
+```
+
+Add status command assertions:
+
+```ts
+const issueResult = await dispatch(command("memory.create", {
+  workspaceId: "ws-1",
+  type: "issue",
+  content: "Broken dropdown.",
+}), ctx);
+expect(issueResult.data).toMatchObject({ type: "issue", status: "not_started" });
+
+const invalidStatus = await dispatch(command("memory.create", {
+  workspaceId: "ws-1",
+  type: "issue",
+  content: "Broken dropdown.",
+  status: "blocked",
+}), ctx);
+expect(invalidStatus.ok).toBe(false);
+expect(invalidStatus.error?.code).toBe("validation_error");
+```
+
+- [ ] **Step 2: Run command test to verify it fails**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/commands/memory.test.ts
+```
+
+Expected: FAIL because command schemas still use canonical old type enum and do not accept status.
+
+- [ ] **Step 3: Implement command schemas**
+
+In `packages/server/src/commands/memory.ts`:
+
+- Import `WORKSPACE_MEMORY_STATUSES` and `normalizeWorkspaceMemoryType`.
+- Create `memoryTypeArgSchema` with `z.string().refine((value) => normalizeWorkspaceMemoryType(value) !== undefined, "Invalid memory type").transform(...)`.
+- Create `memoryStatusSchema = z.enum(WORKSPACE_MEMORY_STATUSES)`.
+- Use `memoryTypeArgSchema` for create/update/list/search type fields.
+- Add optional `status: memoryStatusSchema.optional()` to create/update schemas.
+- Pass `status: args.status` to repository create/update.
+
+- [ ] **Step 4: Run command and repository tests**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/commands/memory.test.ts src/storage/repositories/memory-repo.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/commands/memory.ts packages/server/src/commands/memory.test.ts
+git commit -m "feat(server): accept memory status commands"
+```
+
+## Task 5: CLI Status Forwarding And Help Text
+
+**Files:**
+- Modify: `packages/cli/src/bin.test.ts`
+- Modify: `packages/cli/src/parse-args.ts`
+- Modify: `packages/cli/src/cli.ts`
+- Optional modify: `packages/server/src/skills/builtin/definitions/coder-studio-memory.ts`
+
+- [ ] **Step 1: Write failing CLI tests**
+
+In `packages/cli/src/bin.test.ts`, update memory tests to canonical examples:
+
+```ts
+await main(["memory", "list", "--workspace", "ws-1", "--type", "wiki", "--json"]);
+expect(commandClientMock).toHaveBeenCalledWith(expect.objectContaining({
+  op: "memory.list",
+  args: { workspaceId: "ws-1", type: "wiki" },
+}));
+```
+
+Add status forwarding:
+
+```ts
+await main([
+  "memory",
+  "add",
+  "--workspace",
+  "ws-1",
+  "--type",
+  "issue",
+  "--status",
+  "pending_verification",
+  "--content",
+  "Dropdown stays open.",
+  "--json",
+]);
+expect(commandClientMock).toHaveBeenCalledWith(expect.objectContaining({
+  op: "memory.create",
+  args: {
+    workspaceId: "ws-1",
+    type: "issue",
+    status: "pending_verification",
+    content: "Dropdown stays open.",
+  },
+}));
+```
+
+Add equivalent `memory update mem-1 --status completed`.
+
+- [ ] **Step 2: Run CLI test to verify it fails**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio exec vitest run src/bin.test.ts
+```
+
+Expected: FAIL because `--status` is not parsed/forwarded.
+
+- [ ] **Step 3: Implement CLI status parsing**
+
+In `packages/cli/src/parse-args.ts`:
+
+- Add `memoryStatus?: string` to `CliArgs`.
+- Clear it in reset/copy helpers where other memory fields are cleared.
+- Accept `--status <value>` only for `memory`.
+- Validate that `memory add` still requires `--type` and `--content`, and `--status` is optional.
+
+In `packages/cli/src/cli.ts`:
+
+- Add `...(args.memoryStatus !== undefined ? { status: args.memoryStatus } : {})` to `memory.create` and `memory.update` command args.
+- Update help examples from `--type project` to `--type wiki`.
+- Mention optional `--status` only if the help already lists memory options in command detail.
+
+In `packages/server/src/skills/builtin/definitions/coder-studio-memory.ts`, replace old type examples with `wiki | issue | todo | note` if present.
+
+- [ ] **Step 4: Run CLI and core automation tests**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio exec vitest run src/bin.test.ts
+pnpm --filter @coder-studio/core exec vitest run src/domain/automation.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/cli/src/parse-args.ts packages/cli/src/cli.ts packages/cli/src/bin.test.ts packages/server/src/skills/builtin/definitions/coder-studio-memory.ts
+git commit -m "feat(cli): forward memory status"
+```
+
+If the optional skill file has no old memory type text, leave it unstaged and commit only changed files.
+
+## Task 6: Web Memory Panel Status UI
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/views/shared/memory-panel.test.tsx`
+- Modify: `packages/web/src/locales/en.json`
+- Modify: `packages/web/src/locales/zh.json`
+- Modify: `packages/web/src/features/workspace/actions/use-memory-panel.ts`
+- Modify: `packages/web/src/features/workspace/views/shared/memory-panel.tsx`
+
+- [ ] **Step 1: Write failing web tests**
+
+Update `baseMemoryEntry` to:
+
+```ts
+type: "wiki",
+content: "Package scripts should run through pnpm.",
+```
+
+Add an issue entry with status:
+
+```ts
+{
+  ...baseMemoryEntry,
+  id: "mem-issue",
+  type: "issue",
+  content: "Dropdown stays open.",
+  status: "pending_verification",
+}
+```
+
+Assert type chips in order:
+
+```ts
+const chips = screen.getAllByRole("button").filter((button) =>
+  ["All", "Wiki", "Issue", "Todo", "Note"].includes(button.textContent ?? "")
+);
+expect(chips.map((button) => button.textContent)).toEqual(["All", "Wiki", "Issue", "Todo", "Note"]);
+```
+
+Assert status display:
+
+```ts
+expect(screen.getByText("pending verification")).toBeInTheDocument();
+expect(screen.queryByText("not started")).toBeNull(); // no status badge for wiki/note without status
+```
+
+Add create modal behavior:
+
+```ts
+fireEvent.click(screen.getByRole("button", { name: "New memory" }));
+const createDialog = await screen.findByRole("dialog", { name: "Create memory" });
+expect(within(createDialog).queryByLabelText("Status")).toBeNull();
+await user.click(within(createDialog).getByRole("button", { name: "Type Wiki" }));
+await user.click(within(createDialog).getByRole("option", { name: "Issue" }));
+expect(within(createDialog).getByRole("button", { name: "Status Not started" })).toBeInTheDocument();
+```
+
+Assert create payload includes status for issue:
+
+```ts
+expect(sendCommand).toHaveBeenCalledWith("memory.create", {
+  workspaceId: "ws-1",
+  type: "issue",
+  content: "Dropdown stays open.",
+  status: "not_started",
+}, undefined);
+```
+
+- [ ] **Step 2: Run memory panel test to verify it fails**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web exec vitest run src/features/workspace/views/shared/memory-panel.test.tsx
+```
+
+Expected: FAIL because old type labels are still rendered and no status UI exists.
+
+- [ ] **Step 3: Implement web UI**
+
+In `packages/web/src/locales/en.json`:
+
+- Replace `workspace.memory.types` with keys `wiki`, `issue`, `todo`, `note`.
+- Add `workspace.memory.status_label`.
+- Add `workspace.memory.statuses.not_started`, `.in_progress`, `.pending_verification`, `.completed` with labels `Not started`, `In progress`, `Pending verification`, `Completed`.
+
+In `packages/web/src/locales/zh.json`:
+
+- Replace type labels with `wiki: "Wiki"`, `issue: "问题"`, `todo: "待办"`, `note: "备注"`.
+- Add status labels `待开始`, `进行中`, `待验证`, `已完成`.
+
+In `packages/web/src/features/workspace/actions/use-memory-panel.ts`:
+
+- Import `WorkspaceMemoryStatus`.
+- Add optional `status?: WorkspaceMemoryStatus` to create/update input interfaces.
+- Forward status in dispatch payload through object spread already used for input.
+
+In `packages/web/src/features/workspace/views/shared/memory-panel.tsx`:
+
+- Import `WORKSPACE_MEMORY_STATUSES`, `WorkspaceMemoryStatus`, and `isActionableWorkspaceMemoryType`.
+- Extend `MemoryDraft` with `status?: WorkspaceMemoryStatus`.
+- Set `DEFAULT_MEMORY_TYPE` to `WorkspaceMemoryType.Wiki` after Task 1 exports it.
+- Add `normalizeDraftForType(type, currentStatus)` helper:
+  - returns `{ type, status: "not_started" }` for actionable type without current status;
+  - returns `{ type }` for non-actionable type.
+- Add status select in `renderMemoryForm()` only when actionable.
+- Include status in `saveMemory()` payload only when present.
+- Render a status badge in list meta only when `entry.status` is present.
+
+- [ ] **Step 4: Run memory panel test**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web exec vitest run src/features/workspace/views/shared/memory-panel.test.tsx
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/web/src/features/workspace/views/shared/memory-panel.tsx packages/web/src/features/workspace/views/shared/memory-panel.test.tsx packages/web/src/features/workspace/actions/use-memory-panel.ts packages/web/src/locales/en.json packages/web/src/locales/zh.json
+git commit -m "feat(web): add memory status controls"
+```
+
+## Task 7: Web Styles And Split Divider
+
+**Files:**
+- Modify: `packages/web/src/styles/memory-panel.guard.test.ts`
+- Modify: `packages/web/src/styles/pane-layout-divider.theme.test.ts`
+- Modify: `packages/web/src/styles/components.css`
+
+- [ ] **Step 1: Write failing style guard tests**
+
+In `packages/web/src/styles/memory-panel.guard.test.ts`, update badge variant assertions:
+
+```ts
+expect(badgeVariants).toContain(".memory-panel__badge--wiki");
+expect(badgeVariants).toContain(".memory-panel__badge--issue");
+expect(badgeVariants).toContain(".memory-panel__badge--todo");
+expect(badgeVariants).toContain(".memory-panel__badge--note");
+expect(badgeVariants).not.toContain(".memory-panel__badge--feature");
+expect(badgeVariants).not.toContain(".memory-panel__badge--bugfix");
+expect(badgeVariants).not.toContain(".memory-panel__badge--project");
+```
+
+In `packages/web/src/styles/pane-layout-divider.theme.test.ts`, add assertions:
+
+```ts
+const dividerBlock = getRuleBlock(".pane-layout-divider");
+expect(dividerBlock).toContain("background: transparent");
+expect(dividerBlock).not.toContain("z-index: var(--z-modal");
+expect(dividerBlock).not.toContain("z-index: var(--z-popover");
+expect(dividerBlock).not.toContain("z-index: var(--z-tooltip");
+
+const hoverAfterBlock = getRuleBlock(".pane-layout-divider:hover::after");
+expect(hoverAfterBlock).toContain("background: transparent");
+```
+
+- [ ] **Step 2: Run style guard tests to verify failure**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web exec vitest run src/styles/memory-panel.guard.test.ts src/styles/pane-layout-divider.theme.test.ts
+```
+
+Expected: FAIL until badge variants and divider assertions match the new CSS.
+
+- [ ] **Step 3: Update CSS**
+
+In `packages/web/src/styles/components.css`:
+
+- Replace old `.memory-panel__badge--feature`, `--bugfix`, and `--project` selectors with canonical `.memory-panel__badge--wiki`, `--issue`, `--todo`, `--note`.
+- Add `.memory-panel__status` or `.memory-panel__badge--status-*` styles if Task 6 rendered separate status badges.
+- Keep `.pane-layout-divider`, `::after`, and hover blocks transparent.
+- If a z-index is present on `.pane-layout-divider`, remove it or set it to a low local value that does not sit above editor overlays.
+- Preserve existing divider dimensions/cursor styles outside the visible line styling.
+
+- [ ] **Step 4: Run style guard tests**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web exec vitest run src/styles/memory-panel.guard.test.ts src/styles/pane-layout-divider.theme.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/web/src/styles/components.css packages/web/src/styles/memory-panel.guard.test.ts packages/web/src/styles/pane-layout-divider.theme.test.ts
+git commit -m "style(web): update memory badges and pane divider"
+```
+
+## Task 8: Full Integration Verification
+
+**Files:**
+- No planned source edits unless verification exposes a defect.
+
+- [ ] **Step 1: Run focused package tests**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core test
+pnpm --filter @coder-studio/server test
+pnpm --filter @spencer-kit/coder-studio exec vitest run src/bin.test.ts
+pnpm --filter @coder-studio/web exec vitest run src/features/workspace/views/shared/memory-panel.test.tsx src/components/ui/select/index.test.tsx src/styles/memory-panel.guard.test.ts src/styles/pane-layout-divider.theme.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run typecheck**
+
+Run:
+
+```bash
+pnpm ci:typecheck
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Run repository verification**
+
+Run:
+
+```bash
+pnpm ci:verify
+```
+
+Expected: PASS.
+
+- [ ] **Step 4: Inspect final diff**
+
+Run:
+
+```bash
+git status --short
+git diff --stat HEAD
+```
+
+Expected: only intended implementation files are modified relative to the last implementation commit, or clean if each task committed.
+
+- [ ] **Step 5: Confirm final working tree state**
+
+Run:
+
+```bash
+git status --short
+```
+
+Expected: no output after all task commits and verification fixes are complete. If verification
+required extra fixes after the task commits, commit those concrete files with a message that names
+the fixed verification failure before final handoff.
diff --git a/docs/superpowers/plans/2026-06-20-external-browser-proxy-grants.md b/docs/superpowers/plans/2026-06-20-external-browser-proxy-grants.md
new file mode 100644
index 000000000..085551f48
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-20-external-browser-proxy-grants.md
@@ -0,0 +1,2026 @@
+# External Browser Proxy Grants Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a dedicated-origin browser proxy with grant-based authorization, HTTP and WebSocket forwarding, and a lightweight Settings panel for creating, rotating, extending, and revoking grants.
+
+**Architecture:** The server keeps the main Coder Studio UI listener and adds a second proxy listener on the same host with a different port. Main-origin APIs manage persisted proxy grants, while the proxy origin validates both the existing browser auth cookie and the per-request grant headers before forwarding HTTP or WebSocket traffic to one validated target origin and maintaining a server-side per-grant cookie jar.
+
+**Tech Stack:** TypeScript, Fastify 5, `@fastify/websocket`, `ws`, Node `fetch`, React 19, Jotai, existing Settings page architecture, Vitest, Testing Library, pnpm monorepo.
+
+---
+
+## File Structure
+
+- Create: `packages/server/src/proxy/grant-token.ts`
+  Generates and hashes high-entropy proxy grant tokens.
+- Create: `packages/server/src/proxy/target-policy.ts`
+  Normalizes target origins and enforces host, CIDR, protocol, and DNS-rebinding policy.
+- Create: `packages/server/src/proxy/cookie-jar.ts`
+  Stores per-grant upstream cookies in memory and applies them to HTTP and WebSocket upstream requests.
+- Create: `packages/server/src/proxy/headers.ts`
+  Filters proxy request and response headers, rewrites redirect locations, and blocks unsafe hop-by-hop metadata.
+- Create: `packages/server/src/proxy/errors.ts`
+  Defines stable proxy error codes and HTML navigation error rendering helpers.
+- Create: `packages/server/src/proxy/grant-service.ts`
+  Coordinates grant create/list/extend/rotate/revoke flows on top of the repo and target policy.
+- Create: `packages/server/src/proxy/proxy-app.ts`
+  Builds the dedicated proxy Fastify listener and registers root HTTP and WebSocket forwarding routes.
+- Create: `packages/server/src/routes/proxy-grants.ts`
+  Registers main-origin management APIs under `/api/proxy/*`.
+- Create: `packages/server/src/storage/repositories/proxy-grant-repo.ts`
+  Persists hashed proxy grant records in `state/proxy-grants.json`.
+- Create: `packages/server/src/storage/repositories/proxy-grant-repo.test.ts`
+  Covers repo normalization, persistence, and mutation semantics.
+- Create: `packages/server/src/proxy/target-policy.test.ts`
+  Covers target normalization, allowlist behavior, and DNS rebinding rejection.
+- Create: `packages/server/src/proxy/cookie-jar.test.ts`
+  Covers per-grant upstream cookie capture, replay, and cleanup.
+- Create: `packages/server/src/proxy/headers.test.ts`
+  Covers request filtering, redirect rewrite, and `Set-Cookie` capture behavior.
+- Create: `packages/server/src/proxy/grant-service.test.ts`
+  Covers lifecycle actions and token return rules.
+- Create: `packages/server/src/proxy/proxy-app.test.ts`
+  Covers end-to-end HTTP and WebSocket proxy behavior with auth and grant enforcement.
+- Create: `packages/server/src/routes/proxy-grants.test.ts`
+  Covers main-origin management APIs and one-time token response behavior.
+- Modify: `packages/server/src/config.ts`
+  Adds proxy config parsing and defaults.
+- Modify: `packages/server/src/server.ts`
+  Instantiates proxy grant repos and services, starts/stops the dedicated proxy listener, and exposes proxy runtime info for tests.
+- Modify: `packages/server/src/app.ts`
+  Registers `/api/proxy/*` management routes on the main origin.
+- Modify: `packages/server/src/auth/plugin.ts`
+  Exports cookie parsing or auth helpers needed by the dedicated proxy app to reuse normal browser auth semantics.
+- Modify: `packages/server/src/__tests__/server-runtime-config.test.ts`
+  Covers second-listener startup and shutdown behavior.
+- Modify: `packages/web/src/features/settings/components/settings-sections.tsx`
+  Adds `proxy` as a visible Settings section.
+- Modify: `packages/web/src/features/more/routes.ts`
+  Adds `proxy` to the More/Settings route map.
+- Modify: `packages/web/src/features/more/page.tsx`
+  Extends embedded More-page settings routing so `/more/settings/proxy` renders the new section.
+- Modify: `packages/web/src/features/more/page.test.tsx`
+  Covers the new More-page proxy section route.
+- Create: `packages/web/src/features/settings/components/proxy-access-settings.tsx`
+  Renders the `Proxy Access` panel, one-time token modal, create form, and grant rows.
+- Create: `packages/web/src/features/settings/components/proxy-access-settings.test.tsx`
+  Covers create flow, modal display, row actions, and empty/error states.
+- Create: `packages/web/src/features/settings/components/proxy-access-api.ts`
+  Wraps the `/api/proxy/*` endpoints.
+- Create: `packages/web/src/features/settings/components/proxy-access-api.test.ts`
+  Covers fetch payloads and error handling.
+- Modify: `packages/web/src/features/settings/components/settings-page.tsx`
+  Mounts the new section and updates embedded/mobile settings routing helpers so the new section is reachable everywhere.
+- Modify: `packages/web/src/features/settings/components/settings-page.test.tsx`
+  Covers navigation and section rendering for `proxy`.
+- Modify: `packages/web/src/locales/en.json`
+  Adds `Proxy Access` UI strings and error labels.
+- Modify: `packages/web/src/locales/zh.json`
+  Adds Chinese `Proxy Access` UI strings and error labels.
+- Modify: `packages/web/src/styles/components.css`
+  Adds targeted styles for the grant table, setup modal, and form layout.
+
+## Task 1: Proxy Config, Target Policy, and Grant Persistence
+
+**Files:**
+- Modify: `packages/server/src/config.ts`
+- Create: `packages/server/src/proxy/grant-token.ts`
+- Create: `packages/server/src/proxy/target-policy.ts`
+- Create: `packages/server/src/proxy/target-policy.test.ts`
+- Create: `packages/server/src/storage/repositories/proxy-grant-repo.ts`
+- Create: `packages/server/src/storage/repositories/proxy-grant-repo.test.ts`
+
+- [ ] **Step 1: Write the failing target-policy and repo tests**
+
+Create `packages/server/src/proxy/target-policy.test.ts` with coverage for:
+
+```ts
+import { describe, expect, it } from "vitest";
+import {
+  ProxyTargetPolicyError,
+  createProxyTargetPolicy,
+  normalizeProxyTargetOrigin,
+} from "./target-policy.js";
+
+describe("normalizeProxyTargetOrigin", () => {
+  it("normalizes protocol, host case, and default ports", () => {
+    expect(normalizeProxyTargetOrigin("HTTP://LOCALHOST:8080/")).toBe("http://localhost:8080");
+    expect(normalizeProxyTargetOrigin("https://example.internal:443")).toBe(
+      "https://example.internal"
+    );
+  });
+
+  it("rejects paths, credentials, and unsupported schemes", () => {
+    const values = [
+      "http://localhost:8080/app",
+      "http://user:pass@localhost:8080",
+      "ws://localhost:8080",
+      "file:///tmp/demo",
+      "localhost:8080",
+    ];
+
+    for (const value of values) {
+      expect(() => normalizeProxyTargetOrigin(value)).toThrow(ProxyTargetPolicyError);
+    }
+  });
+});
+
+describe("createProxyTargetPolicy", () => {
+  it("allows loopback by default and rejects private intranet hosts without allow rules", async () => {
+    const policy = createProxyTargetPolicy({
+      allowLoopback: true,
+      allowedHosts: [],
+      allowedCidrs: [],
+      resolveHostname: async (hostname) => {
+        if (hostname === "localhost") {
+          return ["127.0.0.1"];
+        }
+        if (hostname === "grafana.internal") {
+          return ["10.20.0.15"];
+        }
+        return [];
+      },
+    });
+
+    await expect(policy.assertAllowed("http://localhost:3000")).resolves.toEqual({
+      hostname: "localhost",
+      origin: "http://localhost:3000",
+      protocol: "http:",
+      port: 3000,
+      resolvedIps: ["127.0.0.1"],
+    });
+
+    await expect(policy.assertAllowed("http://grafana.internal:3000")).rejects.toThrow(
+      ProxyTargetPolicyError
+    );
+  });
+
+  it("re-checks resolved IPs against allowed hosts and cidrs", async () => {
+    const policy = createProxyTargetPolicy({
+      allowLoopback: false,
+      allowedHosts: ["grafana.internal"],
+      allowedCidrs: ["10.20.0.0/16"],
+      resolveHostname: async () => ["10.20.0.15"],
+    });
+
+    await expect(policy.assertAllowed("http://grafana.internal:8080")).resolves.toMatchObject({
+      resolvedIps: ["10.20.0.15"],
+    });
+  });
+});
+```
+
+Create `packages/server/src/storage/repositories/proxy-grant-repo.test.ts` with coverage for:
+
+```ts
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ProxyGrantRepo } from "./proxy-grant-repo.js";
+
+describe("ProxyGrantRepo", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  function createRepo() {
+    const dir = mkdtempSync(join(tmpdir(), "proxy-grant-repo-"));
+    tempDirs.push(dir);
+    return new ProxyGrantRepo({ filePath: join(dir, "proxy-grants.json") });
+  }
+
+  it("persists hashed grants by id", () => {
+    const repo = createRepo();
+
+    repo.set({
+      id: "pgr_1",
+      label: "grafana",
+      targetOrigin: "http://localhost:3000",
+      allowWebSocket: true,
+      tokenHash: "hash_1",
+      createdAt: 1,
+      expiresAt: 2,
+      revokedAt: null,
+      lastUsedAt: null,
+      lastUsedIp: null,
+    });
+
+    expect(repo.get("pgr_1")).toMatchObject({
+      tokenHash: "hash_1",
+      targetOrigin: "http://localhost:3000",
+    });
+    expect(repo.list()).toHaveLength(1);
+  });
+
+  it("updates and deletes grants without mutating unrelated rows", () => {
+    const repo = createRepo();
+    repo.set({
+      id: "pgr_1",
+      label: "grafana",
+      targetOrigin: "http://localhost:3000",
+      allowWebSocket: true,
+      tokenHash: "hash_1",
+      createdAt: 1,
+      expiresAt: 2,
+      revokedAt: null,
+      lastUsedAt: null,
+      lastUsedIp: null,
+    });
+    repo.set({
+      id: "pgr_2",
+      label: "wiki",
+      targetOrigin: "http://localhost:4000",
+      allowWebSocket: false,
+      tokenHash: "hash_2",
+      createdAt: 3,
+      expiresAt: 4,
+      revokedAt: null,
+      lastUsedAt: null,
+      lastUsedIp: null,
+    });
+
+    repo.set({
+      id: "pgr_1",
+      label: "grafana-prod",
+      targetOrigin: "http://localhost:3000",
+      allowWebSocket: true,
+      tokenHash: "hash_3",
+      createdAt: 1,
+      expiresAt: 5,
+      revokedAt: null,
+      lastUsedAt: 4,
+      lastUsedIp: "127.0.0.1",
+    });
+    repo.delete("pgr_2");
+
+    expect(repo.get("pgr_1")).toMatchObject({
+      label: "grafana-prod",
+      tokenHash: "hash_3",
+      lastUsedIp: "127.0.0.1",
+    });
+    expect(repo.get("pgr_2")).toBeUndefined();
+  });
+});
+```
+
+- [ ] **Step 2: Run the failing policy and repo tests**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- proxy/target-policy.test.ts storage/repositories/proxy-grant-repo.test.ts
+```
+
+Expected: FAIL because the policy and repo files do not exist yet.
+
+- [ ] **Step 3: Implement proxy config parsing, target normalization, token hashing, and grant persistence**
+
+Add a proxy config branch in `packages/server/src/config.ts` similar to:
+
+```ts
+proxy: overrides?.proxy ?? {
+  enabled: process.env.PROXY_ENABLED === "true",
+  host: process.env.PROXY_HOST || (overrides?.host || process.env.HOST || "localhost"),
+  port:
+    overrides?.proxy?.port ??
+    (process.env.PROXY_PORT ? Number(process.env.PROXY_PORT) : (overrides?.port ?? parseInt(process.env.PORT || "4173", 10)) + 1),
+  publicOrigin: process.env.PROXY_PUBLIC_ORIGIN,
+  maxGrantTtlMs: parseInt(process.env.PROXY_MAX_GRANT_TTL_MS || String(7 * 24 * 60 * 60 * 1000), 10),
+  allowedHosts: (process.env.PROXY_ALLOWED_HOSTS || "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean),
+  allowedCidrs: (process.env.PROXY_ALLOWED_CIDRS || "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean),
+  allowLoopback: process.env.PROXY_ALLOW_LOOPBACK !== "false",
+}
+```
+
+Create `packages/server/src/proxy/grant-token.ts` with:
+
+```ts
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+const TOKEN_PREFIX = "pgt_";
+
+export function createProxyGrantToken(): string {
+  return `${TOKEN_PREFIX}${randomBytes(32).toString("hex")}`;
+}
+
+export function hashProxyGrantToken(token: string): string {
+  return createHash("sha256").update(token, "utf8").digest("hex");
+}
+
+export function proxyGrantTokenMatches(token: string, tokenHash: string): boolean {
+  const actual = Buffer.from(hashProxyGrantToken(token), "hex");
+  const expected = Buffer.from(tokenHash, "hex");
+  return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+```
+
+Create `packages/server/src/proxy/target-policy.ts` with:
+
+```ts
+import dns from "node:dns/promises";
+import net from "node:net";
+
+export class ProxyTargetPolicyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProxyTargetPolicyError";
+  }
+}
+
+export interface ResolvedProxyTarget {
+  origin: string;
+  protocol: "http:" | "https:";
+  hostname: string;
+  port: number;
+  resolvedIps: string[];
+}
+
+export function normalizeProxyTargetOrigin(input: string): string {
+  const url = new URL(input);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new ProxyTargetPolicyError("unsupported_protocol");
+  }
+  if (url.username || url.password) {
+    throw new ProxyTargetPolicyError("credentials_not_allowed");
+  }
+  if (url.pathname !== "/" || url.search || url.hash) {
+    throw new ProxyTargetPolicyError("origin_only_required");
+  }
+
+  url.hostname = url.hostname.toLowerCase();
+  if ((url.protocol === "http:" && url.port === "80") || (url.protocol === "https:" && url.port === "443")) {
+    url.port = "";
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+function isLoopbackIp(value: string) {
+  return value === "127.0.0.1" || value === "::1" || value === "::ffff:127.0.0.1";
+}
+
+export function createProxyTargetPolicy({
+  allowLoopback,
+  allowedHosts,
+  allowedCidrs,
+  resolveHostname = async (hostname: string) => (await dns.lookup(hostname, { all: true })).map((entry) => entry.address),
+}: {
+  allowLoopback: boolean;
+  allowedHosts: string[];
+  allowedCidrs: string[];
+  resolveHostname?: (hostname: string) => Promise<string[]>;
+}) {
+  const normalizedHosts = new Set(allowedHosts.map((value) => value.toLowerCase()));
+  const blockList = new net.BlockList();
+
+  for (const cidr of allowedCidrs) {
+    const [network, prefixLengthText] = cidr.split("/");
+    const family = net.isIP(network) === 6 ? "ipv6" : "ipv4";
+    const prefixLength = Number(prefixLengthText);
+    if (!network || !Number.isInteger(prefixLength)) {
+      throw new ProxyTargetPolicyError("invalid_allowed_cidr");
+    }
+    blockList.addSubnet(network, prefixLength, family);
+  }
+
+  function assertAllowedIp(ip: string) {
+    if (allowLoopback && isLoopbackIp(ip)) {
+      return;
+    }
+    if (!net.isIP(ip)) {
+      throw new ProxyTargetPolicyError("invalid_resolved_ip");
+    }
+    const family = net.isIP(ip) === 6 ? "ipv6" : "ipv4";
+    if (blockList.check(ip, family)) {
+      return;
+    }
+    throw new ProxyTargetPolicyError("target_ip_not_allowed");
+  }
+
+  return {
+    async assertAllowed(input: string): Promise<ResolvedProxyTarget> {
+      const origin = normalizeProxyTargetOrigin(input);
+      const url = new URL(origin);
+      const hostname = url.hostname.toLowerCase();
+      const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+      const resolvedIps =
+        net.isIP(hostname) > 0 ? [hostname] : await resolveHostname(hostname);
+
+      if (!resolvedIps.length) {
+        throw new ProxyTargetPolicyError("hostname_resolution_failed");
+      }
+
+      if (normalizedHosts.size > 0 && !normalizedHosts.has(hostname) && !resolvedIps.every(isLoopbackIp)) {
+        throw new ProxyTargetPolicyError("target_host_not_allowed");
+      }
+
+      for (const ip of resolvedIps) {
+        assertAllowedIp(ip);
+      }
+
+      return {
+        origin,
+        protocol: url.protocol as "http:" | "https:",
+        hostname,
+        port,
+        resolvedIps,
+      };
+    },
+  };
+}
+```
+
+Use `net.BlockList` instead of string-prefix CIDR matching. The point of this task is to ship an actual policy boundary, not a placeholder approximation that only works for a narrow IPv4 subset.
+
+Create `packages/server/src/storage/repositories/proxy-grant-repo.ts` modeled after other JSON repos:
+
+```ts
+import { readJsonFile, writeJsonFileAtomic } from "./json-file-store.js";
+
+export interface ProxyGrantRecord {
+  id: string;
+  label: string;
+  targetOrigin: string;
+  allowWebSocket: boolean;
+  tokenHash: string;
+  createdAt: number;
+  expiresAt: number;
+  revokedAt: number | null;
+  lastUsedAt: number | null;
+  lastUsedIp: string | null;
+}
+
+interface ProxyGrantFileRecord {
+  version: 1;
+  grants: Record<string, ProxyGrantRecord>;
+}
+
+export class ProxyGrantRepo {
+  constructor(private readonly options: { filePath: string }) {}
+
+  private load(): Record<string, ProxyGrantRecord> {
+    const parsed = readJsonFile<ProxyGrantFileRecord>(this.options.filePath);
+    if (!parsed || parsed.version !== 1 || typeof parsed.grants !== "object") {
+      return {};
+    }
+    return parsed.grants;
+  }
+
+  private save(grants: Record<string, ProxyGrantRecord>) {
+    writeJsonFileAtomic(this.options.filePath, { version: 1, grants });
+  }
+
+  list(): ProxyGrantRecord[] {
+    return Object.values(this.load()).sort((left, right) => right.createdAt - left.createdAt);
+  }
+
+  get(id: string): ProxyGrantRecord | undefined {
+    return this.load()[id];
+  }
+
+  set(record: ProxyGrantRecord) {
+    const grants = this.load();
+    grants[record.id] = record;
+    this.save(grants);
+  }
+
+  delete(id: string) {
+    const grants = this.load();
+    if (!Object.prototype.hasOwnProperty.call(grants, id)) {
+      return;
+    }
+    delete grants[id];
+    this.save(grants);
+  }
+}
+```
+
+- [ ] **Step 4: Run the policy and repo tests again**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- proxy/target-policy.test.ts storage/repositories/proxy-grant-repo.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/config.ts packages/server/src/proxy/grant-token.ts packages/server/src/proxy/target-policy.ts packages/server/src/proxy/target-policy.test.ts packages/server/src/storage/repositories/proxy-grant-repo.ts packages/server/src/storage/repositories/proxy-grant-repo.test.ts
+git commit -m "feat(server): add proxy grant policy and persistence"
+```
+
+## Task 2: Grant Service and Main-Origin Management APIs
+
+**Files:**
+- Create: `packages/server/src/proxy/grant-service.ts`
+- Create: `packages/server/src/proxy/grant-service.test.ts`
+- Create: `packages/server/src/routes/proxy-grants.ts`
+- Create: `packages/server/src/routes/proxy-grants.test.ts`
+- Modify: `packages/server/src/app.ts`
+
+- [ ] **Step 1: Write the failing grant-service and route tests**
+
+Create `packages/server/src/proxy/grant-service.test.ts` with:
+
+```ts
+import { describe, expect, it, vi } from "vitest";
+import { GrantService } from "./grant-service.js";
+
+describe("GrantService", () => {
+  it("creates a grant and returns the raw token only once", async () => {
+    const repo = {
+      list: vi.fn(() => []),
+      get: vi.fn(),
+      set: vi.fn(),
+      delete: vi.fn(),
+    };
+    const service = new GrantService({
+      repo: repo as never,
+      now: () => 10,
+      maxGrantTtlMs: 1_000,
+      targetPolicy: {
+        assertAllowed: vi.fn(async (origin: string) => ({
+          origin,
+          protocol: "http:",
+          hostname: "localhost",
+          port: 3000,
+          resolvedIps: ["127.0.0.1"],
+        })),
+      },
+    });
+
+    const created = await service.create({
+      label: "grafana",
+      targetOrigin: "http://localhost:3000",
+      allowWebSocket: true,
+      ttlMs: 500,
+    });
+
+    expect(created.grantToken).toMatch(/^pgt_/);
+    expect(created.record).toMatchObject({
+      label: "grafana",
+      targetOrigin: "http://localhost:3000",
+      allowWebSocket: true,
+    });
+    expect(repo.set).toHaveBeenCalledTimes(1);
+  });
+
+  it("extends, rotates, and revokes existing grants", async () => {
+    const existing = {
+      id: "pgr_1",
+      label: "grafana",
+      targetOrigin: "http://localhost:3000",
+      allowWebSocket: true,
+      tokenHash: "hash_1",
+      createdAt: 1,
+      expiresAt: 20,
+      revokedAt: null,
+      lastUsedAt: null,
+      lastUsedIp: null,
+    };
+    const repo = {
+      list: vi.fn(() => [existing]),
+      get: vi.fn(() => existing),
+      set: vi.fn(),
+      delete: vi.fn(),
+    };
+    const service = new GrantService({
+      repo: repo as never,
+      now: () => 10,
+      maxGrantTtlMs: 1_000,
+      targetPolicy: {
+        assertAllowed: vi.fn(async (origin: string) => ({
+          origin,
+          protocol: "http:",
+          hostname: "localhost",
+          port: 3000,
+          resolvedIps: ["127.0.0.1"],
+        })),
+      },
+    });
+
+    const extended = await service.extend("pgr_1", 900);
+    const rotated = await service.rotate("pgr_1");
+    const revoked = await service.revoke("pgr_1");
+
+    expect(extended.expiresAt).toBeGreaterThan(existing.expiresAt);
+    expect(rotated.grantToken).toMatch(/^pgt_/);
+    expect(revoked.revokedAt).toBe(10);
+  });
+});
+```
+
+Create `packages/server/src/routes/proxy-grants.test.ts` with:
+
+```ts
+import Fastify from "fastify";
+import { describe, expect, it, vi } from "vitest";
+import { registerProxyGrantRoutes } from "./proxy-grants.js";
+
+describe("registerProxyGrantRoutes", () => {
+  it("returns the raw token on create and omits it from list responses", async () => {
+    const app = Fastify();
+    const service = {
+      list: vi.fn(() => [
+        {
+          id: "pgr_1",
+          label: "grafana",
+          targetOrigin: "http://localhost:3000",
+          allowWebSocket: true,
+          createdAt: 1,
+          expiresAt: 2,
+          revokedAt: null,
+          lastUsedAt: null,
+          lastUsedIp: null,
+        },
+      ]),
+      create: vi.fn(async () => ({
+        record: {
+          id: "pgr_2",
+          label: "wiki",
+          targetOrigin: "http://localhost:4000",
+          allowWebSocket: false,
+          createdAt: 3,
+          expiresAt: 4,
+          revokedAt: null,
+          lastUsedAt: null,
+          lastUsedIp: null,
+          tokenHash: "hash",
+        },
+        grantToken: "pgt_created",
+      })),
+      extend: vi.fn(),
+      rotate: vi.fn(),
+      revoke: vi.fn(),
+    };
+
+    registerProxyGrantRoutes(app, {
+      service: service as never,
+      proxyOrigin: "http://localhost:4445",
+    });
+
+    const createResponse = await app.inject({
+      method: "POST",
+      url: "/api/proxy/grants",
+      payload: {
+        label: "wiki",
+        targetOrigin: "http://localhost:4000",
+        allowWebSocket: false,
+        ttlMs: 1000,
+      },
+    });
+    const listResponse = await app.inject({
+      method: "GET",
+      url: "/api/proxy/grants",
+    });
+
+    expect(createResponse.statusCode).toBe(200);
+    expect(createResponse.json()).toMatchObject({
+      grantToken: "pgt_created",
+      proxyOrigin: "http://localhost:4445",
+    });
+    expect(listResponse.json()).toEqual({
+      proxyOrigin: "http://localhost:4445",
+      grants: [
+        expect.not.objectContaining({
+          grantToken: expect.anything(),
+        }),
+      ],
+    });
+  });
+});
+```
+
+- [ ] **Step 2: Run the failing grant-service and route tests**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- proxy/grant-service.test.ts routes/proxy-grants.test.ts
+```
+
+Expected: FAIL because the service and route files do not exist.
+
+- [ ] **Step 3: Implement the grant lifecycle service and `/api/proxy/*` routes**
+
+Create `packages/server/src/proxy/grant-service.ts` with a service shaped like:
+
+```ts
+import { randomUUID } from "node:crypto";
+import { createProxyGrantToken, hashProxyGrantToken } from "./grant-token.js";
+import type { ProxyGrantRepo, ProxyGrantRecord } from "../storage/repositories/proxy-grant-repo.js";
+
+export class GrantService {
+  constructor(
+    private readonly deps: {
+      repo: ProxyGrantRepo;
+      now: () => number;
+      maxGrantTtlMs: number;
+      targetPolicy: { assertAllowed(origin: string): Promise<{ origin: string }> };
+    }
+  ) {}
+
+  list() {
+    return this.deps.repo.list().map(({ tokenHash: _tokenHash, ...record }) => record);
+  }
+
+  findByTokenHash(tokenHash: string) {
+    return this.deps.repo.list().find((record) => record.tokenHash === tokenHash) ?? null;
+  }
+
+  async create(input: {
+    label: string;
+    targetOrigin: string;
+    allowWebSocket: boolean;
+    ttlMs: number;
+  }) {
+    const now = this.deps.now();
+    const ttlMs = Math.min(input.ttlMs, this.deps.maxGrantTtlMs);
+    const resolved = await this.deps.targetPolicy.assertAllowed(input.targetOrigin);
+    const grantToken = createProxyGrantToken();
+    const record: ProxyGrantRecord = {
+      id: `pgr_${randomUUID()}`,
+      label: input.label.trim(),
+      targetOrigin: resolved.origin,
+      allowWebSocket: input.allowWebSocket,
+      tokenHash: hashProxyGrantToken(grantToken),
+      createdAt: now,
+      expiresAt: now + ttlMs,
+      revokedAt: null,
+      lastUsedAt: null,
+      lastUsedIp: null,
+    };
+    this.deps.repo.set(record);
+    return { record, grantToken };
+  }
+
+  async extend(id: string, ttlMs: number) {
+    const existing = this.requireGrant(id);
+    const now = this.deps.now();
+    const expiresAt = now + Math.min(ttlMs, this.deps.maxGrantTtlMs);
+    const updated = { ...existing, expiresAt };
+    this.deps.repo.set(updated);
+    return updated;
+  }
+
+  async rotate(id: string) {
+    const existing = this.requireGrant(id);
+    const grantToken = createProxyGrantToken();
+    const updated = { ...existing, tokenHash: hashProxyGrantToken(grantToken), revokedAt: null };
+    this.deps.repo.set(updated);
+    return { record: updated, grantToken };
+  }
+
+  async revoke(id: string) {
+    const existing = this.requireGrant(id);
+    const updated = { ...existing, revokedAt: this.deps.now() };
+    this.deps.repo.set(updated);
+    return updated;
+  }
+
+  private requireGrant(id: string) {
+    const existing = this.deps.repo.get(id);
+    if (!existing) {
+      throw new Error("proxy_grant_not_found");
+    }
+    return existing;
+  }
+}
+```
+
+Create `packages/server/src/routes/proxy-grants.ts` with route registration like:
+
+```ts
+import { z } from "zod";
+import type { FastifyInstance } from "fastify";
+
+const CreateGrantSchema = z.object({
+  label: z.string().trim().min(1),
+  targetOrigin: z.string().trim().min(1),
+  allowWebSocket: z.boolean(),
+  ttlMs: z.number().int().positive(),
+});
+
+const ExtendGrantSchema = z.object({
+  ttlMs: z.number().int().positive(),
+});
+
+export function registerProxyGrantRoutes(
+  app: FastifyInstance,
+  deps: {
+    service: {
+      list(): unknown;
+      create(input: z.infer<typeof CreateGrantSchema>): Promise<{ record: Record<string, unknown>; grantToken: string }>;
+      extend(id: string, ttlMs: number): Promise<Record<string, unknown>>;
+      rotate(id: string): Promise<{ record: Record<string, unknown>; grantToken: string }>;
+      revoke(id: string): Promise<Record<string, unknown>>;
+    };
+    proxyOrigin: string;
+  }
+) {
+  app.get("/api/proxy/config", async () => ({
+    proxyOrigin: deps.proxyOrigin,
+  }));
+
+  app.get("/api/proxy/grants", async () => ({
+    grants: deps.service.list(),
+  }));
+
+  app.post("/api/proxy/grants", async (request, reply) => {
+    const parsed = CreateGrantSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({ ok: false, error: "invalid_proxy_grant_payload" });
+    }
+    const created = await deps.service.create(parsed.data);
+    const { tokenHash: _tokenHash, ...record } = created.record as { tokenHash?: string };
+    return reply.send({
+      ...record,
+      grantToken: created.grantToken,
+      proxyOrigin: deps.proxyOrigin,
+    });
+  });
+
+  app.post("/api/proxy/grants/:id/extend", async (request, reply) => {
+    const parsed = ExtendGrantSchema.safeParse(request.body);
+    if (!parsed.success) {
+      return reply.status(400).send({ ok: false, error: "invalid_proxy_grant_payload" });
+    }
+    return reply.send(await deps.service.extend((request.params as { id: string }).id, parsed.data.ttlMs));
+  });
+
+  app.post("/api/proxy/grants/:id/rotate", async (request) => {
+    const rotated = await deps.service.rotate((request.params as { id: string }).id);
+    const { tokenHash: _tokenHash, ...record } = rotated.record as { tokenHash?: string };
+    return {
+      ...record,
+      grantToken: rotated.grantToken,
+      proxyOrigin: deps.proxyOrigin,
+    };
+  });
+
+  app.delete("/api/proxy/grants/:id", async (request) => {
+    return await deps.service.revoke((request.params as { id: string }).id);
+  });
+}
+```
+
+Register those routes in `packages/server/src/app.ts` before static web fallback routes using a concrete service instance from `server.ts`.
+
+Keep the API shapes consistent with the UI flow:
+
+- `GET /api/proxy/config` returns `{ proxyOrigin }`
+- `GET /api/proxy/grants` returns `{ proxyOrigin, grants }`
+- `POST /api/proxy/grants` and `POST /api/proxy/grants/:id/rotate` return `{ ...grantView, proxyOrigin, grantToken }`
+
+That lets the web panel either read `proxyOrigin` from the list call or from the separate config call without maintaining two incompatible response shapes.
+
+- [ ] **Step 4: Run the grant-service and route tests again**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- proxy/grant-service.test.ts routes/proxy-grants.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/proxy/grant-service.ts packages/server/src/proxy/grant-service.test.ts packages/server/src/routes/proxy-grants.ts packages/server/src/routes/proxy-grants.test.ts packages/server/src/app.ts
+git commit -m "feat(server): add proxy grant management APIs"
+```
+
+## Task 3: Dedicated Proxy Listener, Cookie Jar, and HTTP/WS Forwarding
+
+**Files:**
+- Create: `packages/server/src/proxy/cookie-jar.ts`
+- Create: `packages/server/src/proxy/cookie-jar.test.ts`
+- Create: `packages/server/src/proxy/headers.ts`
+- Create: `packages/server/src/proxy/headers.test.ts`
+- Create: `packages/server/src/proxy/errors.ts`
+- Create: `packages/server/src/proxy/proxy-app.ts`
+- Create: `packages/server/src/proxy/proxy-app.test.ts`
+- Modify: `packages/server/src/auth/plugin.ts`
+- Modify: `packages/server/src/server.ts`
+- Modify: `packages/server/src/__tests__/server-runtime-config.test.ts`
+
+- [ ] **Step 1: Write failing cookie-jar, header, and proxy-listener tests**
+
+Create `packages/server/src/proxy/cookie-jar.test.ts` with:
+
+```ts
+import { describe, expect, it } from "vitest";
+import { ProxyCookieJar } from "./cookie-jar.js";
+
+describe("ProxyCookieJar", () => {
+  it("captures and replays per-grant cookies", () => {
+    const jar = new ProxyCookieJar();
+    jar.capture("pgr_1", [
+      "sid=abc; Path=/; HttpOnly",
+      "theme=dark; Path=/",
+    ]);
+
+    expect(jar.getCookieHeader("pgr_1", "http://localhost:3000/app")).toBe("sid=abc; theme=dark");
+    expect(jar.getCookieHeader("pgr_2", "http://localhost:3000/app")).toBe("");
+  });
+
+  it("clears cookies when a grant is rotated or revoked", () => {
+    const jar = new ProxyCookieJar();
+    jar.capture("pgr_1", ["sid=abc; Path=/"]);
+    jar.clear("pgr_1");
+    expect(jar.getCookieHeader("pgr_1", "http://localhost:3000/app")).toBe("");
+  });
+});
+```
+
+Create `packages/server/src/proxy/headers.test.ts` with:
+
+```ts
+import { describe, expect, it } from "vitest";
+import { buildUpstreamHeaders, rewriteProxyLocationHeader } from "./headers.js";
+
+describe("buildUpstreamHeaders", () => {
+  it("strips proxy and hop-by-hop headers while rewriting host and origin", () => {
+    const headers = buildUpstreamHeaders({
+      incoming: {
+        host: "localhost:4445",
+        origin: "http://localhost:4445",
+        referer: "http://localhost:4445/app",
+        connection: "keep-alive",
+        "x-cs-proxy-target": "http://localhost:3000",
+        "x-cs-proxy-grant": "pgt_1",
+      },
+      upstreamOrigin: "http://localhost:3000",
+      cookieHeader: "sid=abc",
+    });
+
+    expect(headers.host).toBe("localhost:3000");
+    expect(headers.origin).toBe("http://localhost:3000");
+    expect(headers.referer).toBe("http://localhost:3000/app");
+    expect(headers.cookie).toBe("sid=abc");
+    expect(headers).not.toHaveProperty("connection");
+    expect(headers).not.toHaveProperty("x-cs-proxy-target");
+  });
+});
+
+describe("rewriteProxyLocationHeader", () => {
+  it("rewrites target-origin redirects back to the proxy origin", () => {
+    expect(
+      rewriteProxyLocationHeader({
+        location: "http://localhost:3000/login?next=%2Fapp",
+        targetOrigin: "http://localhost:3000",
+        proxyOrigin: "http://localhost:4445",
+      })
+    ).toBe("http://localhost:4445/login?next=%2Fapp");
+  });
+});
+```
+
+Create `packages/server/src/proxy/proxy-app.test.ts` with:
+
+```ts
+import Fastify from "fastify";
+import websocket from "@fastify/websocket";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildProxyApp } from "./proxy-app.js";
+
+describe("buildProxyApp", () => {
+  let upstreamHttp: ReturnType<typeof Fastify>;
+  let upstreamPort = 0;
+
+  beforeEach(async () => {
+    upstreamHttp = Fastify();
+    await upstreamHttp.register(websocket);
+    upstreamHttp.get("/app", async (_request, reply) => {
+      reply
+        .header("Set-Cookie", "sid=abc; Path=/")
+        .header("Location", "http://localhost:3000/login")
+        .status(302);
+      return "";
+    });
+    upstreamHttp.get("/ok", async () => ({ ok: true }));
+    upstreamHttp.get("/ws", { websocket: true }, (socket) => {
+      socket.on("message", (payload) => {
+        socket.send(`echo:${payload.toString()}`);
+      });
+    });
+    await upstreamHttp.listen({ host: "127.0.0.1", port: 0 });
+    upstreamPort = Number((upstreamHttp.server.address() as { port: number }).port);
+  });
+
+  afterEach(async () => {
+    await upstreamHttp.close();
+  });
+
+  it("requires auth and matching grant headers, captures cookies, and rewrites redirects", async () => {
+    const app = await buildProxyApp({
+      authSessionRepo: {
+        touch: () => true,
+      } as never,
+      targetPolicy: {
+        assertAllowed: async (origin: string) => ({
+          origin,
+          protocol: "http:",
+          hostname: "127.0.0.1",
+          port: upstreamPort,
+          resolvedIps: ["127.0.0.1"],
+        }),
+      },
+      grantLookup: async () => ({
+        id: "pgr_1",
+        targetOrigin: `http://127.0.0.1:${upstreamPort}`,
+        allowWebSocket: true,
+        expiresAt: Date.now() + 60_000,
+        revokedAt: null,
+      }),
+      proxyOrigin: "http://localhost:4445",
+    });
+
+    const response = await app.inject({
+      method: "GET",
+      url: "/app",
+      headers: {
+        cookie: "coder_studio_auth=ok",
+        "x-cs-proxy-target": `http://127.0.0.1:${upstreamPort}`,
+        "x-cs-proxy-grant": "pgt_1",
+      },
+    });
+
+    expect(response.statusCode).toBe(302);
+    expect(response.headers.location).toBe("http://localhost:4445/login");
+    expect(response.headers["set-cookie"]).toBeUndefined();
+    await app.close();
+  });
+});
+```
+
+- [ ] **Step 2: Run the failing proxy-listener test suite**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- proxy/cookie-jar.test.ts proxy/headers.test.ts proxy/proxy-app.test.ts __tests__/server-runtime-config.test.ts
+```
+
+Expected: FAIL because the cookie jar, header helpers, and proxy app do not exist and the runtime config test does not yet account for a second listener.
+
+- [ ] **Step 3: Implement the dedicated proxy Fastify app and second listener startup**
+
+Create `packages/server/src/proxy/cookie-jar.ts` with:
+
+```ts
+type CookieEntry = {
+  name: string;
+  value: string;
+};
+
+export class ProxyCookieJar {
+  private readonly jars = new Map<string, CookieEntry[]>();
+
+  capture(grantId: string, setCookieHeaders: string[]) {
+    const next: CookieEntry[] = [];
+    for (const header of setCookieHeaders) {
+      const [pair] = header.split(";", 1);
+      const [name, ...rest] = pair.split("=");
+      if (!name) {
+        continue;
+      }
+      next.push({ name: name.trim(), value: rest.join("=").trim() });
+    }
+    this.jars.set(grantId, next);
+  }
+
+  getCookieHeader(grantId: string, _url: string): string {
+    return (this.jars.get(grantId) ?? [])
+      .map((entry) => `${entry.name}=${entry.value}`)
+      .join("; ");
+  }
+
+  clear(grantId: string) {
+    this.jars.delete(grantId);
+  }
+}
+```
+
+Create `packages/server/src/proxy/headers.ts` with:
+
+```ts
+const HOP_BY_HOP_HEADERS = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "x-cs-proxy-target",
+  "x-cs-proxy-grant",
+]);
+
+export function buildUpstreamHeaders({
+  incoming,
+  upstreamOrigin,
+  cookieHeader,
+}: {
+  incoming: Record<string, string | string[] | undefined>;
+  upstreamOrigin: string;
+  cookieHeader: string;
+}) {
+  const url = new URL(upstreamOrigin);
+  const headers: Record<string, string> = {};
+
+  for (const [key, rawValue] of Object.entries(incoming)) {
+    if (!rawValue) {
+      continue;
+    }
+    const lowerKey = key.toLowerCase();
+    if (HOP_BY_HOP_HEADERS.has(lowerKey)) {
+      continue;
+    }
+    headers[lowerKey] = Array.isArray(rawValue) ? rawValue.join(", ") : rawValue;
+  }
+
+  headers.host = url.host;
+  if (headers.origin) {
+    headers.origin = upstreamOrigin;
+  }
+  if (headers.referer) {
+    headers.referer = headers.referer.replace(/^https?:\/\/[^/]+/, upstreamOrigin);
+  }
+  if (cookieHeader) {
+    headers.cookie = cookieHeader;
+  } else {
+    delete headers.cookie;
+  }
+
+  return headers;
+}
+
+export function rewriteProxyLocationHeader({
+  location,
+  targetOrigin,
+  proxyOrigin,
+}: {
+  location: string;
+  targetOrigin: string;
+  proxyOrigin: string;
+}) {
+  return location.startsWith(targetOrigin)
+    ? `${proxyOrigin}${location.slice(targetOrigin.length)}`
+    : location;
+}
+```
+
+Create `packages/server/src/proxy/errors.ts` with:
+
+```ts
+export function renderProxyNavigationErrorHtml(error: string, targetOrigin: string, mainUiOrigin: string) {
+  return `<!doctype html><html><body><h1>Proxy Error</h1><p>${error}</p><p>${targetOrigin}</p><p><a href="${mainUiOrigin}">Back to Coder Studio</a></p></body></html>`;
+}
+```
+
+Create `packages/server/src/proxy/proxy-app.ts` with a builder that:
+
+- registers `@fastify/websocket`
+- reads and validates `coder_studio_auth` from the shared `AuthSessionRepo`
+- validates `X-CS-Proxy-Target` and `X-CS-Proxy-Grant`
+- checks grant expiration, revocation, target equality, and `allowWebSocket`
+- forwards HTTP with `fetch`
+- captures upstream `Set-Cookie` into `ProxyCookieJar`
+- rewrites `Location` response headers back to the proxy origin
+- creates a `ws` upstream client per browser WebSocket connection
+
+Prefer route registration that matches this codebase's current Fastify usage:
+
+- register `@fastify/websocket` inside the dedicated proxy app
+- use one HTTP catch-all such as `app.route({ method: ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"], url: "/*", handler })`
+- register a separate WebSocket `GET "/*"` route with `{ websocket: true }`
+
+Do not rely on a single mixed `app.all("/*", ...)` route to cover WebSocket upgrades. Keep HTTP and WebSocket handlers explicit.
+
+Use a shape like:
+
+```ts
+import websocket, { type WebSocket } from "@fastify/websocket";
+import Fastify, { type FastifyInstance, type FastifyRequest } from "fastify";
+import Ws from "ws";
+import { hashProxyGrantToken } from "./grant-token.js";
+import { buildUpstreamHeaders, rewriteProxyLocationHeader } from "./headers.js";
+import { ProxyCookieJar } from "./cookie-jar.js";
+
+function parseAuthCookie(request: FastifyRequest) {
+  const cookie = request.headers.cookie ?? "";
+  const match = cookie.split(";").map((part) => part.trim()).find((part) => part.startsWith("coder_studio_auth="));
+  return match ? decodeURIComponent(match.slice("coder_studio_auth=".length)) : null;
+}
+
+export async function buildProxyApp(deps: {
+  authSessionRepo: { touch(token: string, now: number): boolean };
+  targetPolicy: { assertAllowed(origin: string): Promise<{ origin: string; protocol: "http:" | "https:" }> };
+  grantLookup: (tokenHash: string) => Promise<{
+    id: string;
+    targetOrigin: string;
+    allowWebSocket: boolean;
+    expiresAt: number;
+    revokedAt: number | null;
+  } | null>;
+  proxyOrigin: string;
+  mainUiOrigin?: string;
+}) {
+  const app = Fastify();
+  const cookieJar = new ProxyCookieJar();
+  await app.register(websocket);
+
+  async function authenticate(request: FastifyRequest) {
+    const authToken = parseAuthCookie(request);
+    if (!authToken || !deps.authSessionRepo.touch(authToken, Date.now())) {
+      throw new Error("auth_required");
+    }
+
+    const targetOrigin = request.headers["x-cs-proxy-target"];
+    const grantToken = request.headers["x-cs-proxy-grant"];
+    if (typeof targetOrigin !== "string" || typeof grantToken !== "string") {
+      throw new Error("proxy_headers_required");
+    }
+
+    const grant = await deps.grantLookup(hashProxyGrantToken(grantToken));
+    if (!grant) {
+      throw new Error("proxy_grant_invalid");
+    }
+    if (grant.revokedAt !== null) {
+      throw new Error("proxy_grant_revoked");
+    }
+    if (grant.expiresAt <= Date.now()) {
+      throw new Error("proxy_grant_expired");
+    }
+
+    const resolved = await deps.targetPolicy.assertAllowed(targetOrigin);
+    if (resolved.origin !== grant.targetOrigin) {
+      throw new Error("proxy_target_mismatch");
+    }
+
+    return {
+      grant,
+      targetOrigin: resolved.origin,
+      protocol: resolved.protocol,
+    };
+  }
+
+  app.route({
+    method: ["DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT"],
+    url: "/*",
+    async handler(request, reply) {
+    try {
+      const auth = await authenticate(request);
+      const upstreamUrl = `${auth.targetOrigin}${request.url}`;
+      const upstreamResponse = await fetch(upstreamUrl, {
+        method: request.method,
+        headers: buildUpstreamHeaders({
+          incoming: request.headers as Record<string, string | string[] | undefined>,
+          upstreamOrigin: auth.targetOrigin,
+          cookieHeader: cookieJar.getCookieHeader(auth.grant.id, upstreamUrl),
+        }),
+        body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
+        redirect: "manual",
+      });
+
+      const setCookie = upstreamResponse.headers.getSetCookie?.() ?? [];
+      if (setCookie.length > 0) {
+        cookieJar.capture(auth.grant.id, setCookie);
+      }
+
+      for (const [key, value] of upstreamResponse.headers.entries()) {
+        if (key.toLowerCase() === "set-cookie") {
+          continue;
+        }
+        if (key.toLowerCase() === "location") {
+          reply.header(
+            "Location",
+            rewriteProxyLocationHeader({
+              location: value,
+              targetOrigin: auth.targetOrigin,
+              proxyOrigin: deps.proxyOrigin,
+            })
+          );
+          continue;
+        }
+        reply.header(key, value);
+      }
+
+      reply.status(upstreamResponse.status);
+      return reply.send(Buffer.from(await upstreamResponse.arrayBuffer()));
+    } catch (error) {
+      const code = (error as Error).message;
+      return reply.status(code === "auth_required" ? 401 : 403).send({ ok: false, error: code });
+    }
+    },
+  });
+
+  app.get("/*", { websocket: true }, async (connection: WebSocket, request: FastifyRequest) => {
+    const auth = await authenticate(request);
+    if (!auth.grant.allowWebSocket) {
+      connection.close(1008, "proxy_websocket_not_allowed");
+      return;
+    }
+
+    const upstreamBase = auth.protocol === "https:" ? auth.targetOrigin.replace(/^https:/, "wss:") : auth.targetOrigin.replace(/^http:/, "ws:");
+    const upstream = new Ws(`${upstreamBase}${request.url}`, {
+      headers: buildUpstreamHeaders({
+        incoming: request.headers as Record<string, string | string[] | undefined>,
+        upstreamOrigin: auth.targetOrigin,
+        cookieHeader: cookieJar.getCookieHeader(auth.grant.id, `${auth.targetOrigin}${request.url}`),
+      }),
+    });
+
+    upstream.on("message", (payload, isBinary) => {
+      connection.send(payload, { binary: isBinary });
+    });
+    connection.on("message", (payload, isBinary) => {
+      upstream.send(payload, { binary: isBinary });
+    });
+    upstream.on("close", (code, reason) => connection.close(code, reason.toString()));
+    connection.on("close", (code, reason) => upstream.close(code, reason.toString()));
+    upstream.on("error", () => connection.close(1011, "upstream_unreachable"));
+  });
+
+  return app;
+}
+```
+
+Modify `packages/server/src/server.ts` to:
+
+- instantiate `ProxyGrantRepo`
+- instantiate `GrantService`
+- build a proxy app when `config.proxy.enabled`
+- pass `grantLookup: (tokenHash) => grantService.findByTokenHash(tokenHash)`
+- start the proxy listener after the main listener
+- stop it inside `stopServer`
+- include proxy runtime info in test-only metadata if useful
+
+Add a runtime test in `packages/server/src/__tests__/server-runtime-config.test.ts` like:
+
+```ts
+it("starts and stops the dedicated proxy listener when proxy is enabled", async () => {
+  server = await createRuntimeServer({
+    stateDir: join(testHomeDir, "server-state-proxy"),
+    host: "127.0.0.1",
+    port: 0,
+    proxy: {
+      enabled: true,
+      host: "127.0.0.1",
+      port: 0,
+      publicOrigin: undefined,
+      maxGrantTtlMs: 60_000,
+      allowedHosts: [],
+      allowedCidrs: [],
+      allowLoopback: true,
+    },
+  });
+
+  expect(server.app.server.listening).toBe(true);
+});
+```
+
+- [ ] **Step 4: Run the proxy listener and runtime tests again**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- proxy/cookie-jar.test.ts proxy/headers.test.ts proxy/proxy-app.test.ts __tests__/server-runtime-config.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/proxy/cookie-jar.ts packages/server/src/proxy/cookie-jar.test.ts packages/server/src/proxy/headers.ts packages/server/src/proxy/headers.test.ts packages/server/src/proxy/errors.ts packages/server/src/proxy/proxy-app.ts packages/server/src/proxy/proxy-app.test.ts packages/server/src/auth/plugin.ts packages/server/src/server.ts packages/server/src/__tests__/server-runtime-config.test.ts
+git commit -m "feat(server): add dedicated proxy listener"
+```
+
+## Task 4: Proxy Access Settings Panel and Client API
+
+**Files:**
+- Modify: `packages/web/src/features/settings/components/settings-sections.tsx`
+- Modify: `packages/web/src/features/more/routes.ts`
+- Modify: `packages/web/src/features/more/page.tsx`
+- Modify: `packages/web/src/features/more/page.test.tsx`
+- Create: `packages/web/src/features/settings/components/proxy-access-api.ts`
+- Create: `packages/web/src/features/settings/components/proxy-access-api.test.ts`
+- Create: `packages/web/src/features/settings/components/proxy-access-settings.tsx`
+- Create: `packages/web/src/features/settings/components/proxy-access-settings.test.tsx`
+- Modify: `packages/web/src/features/settings/components/settings-page.tsx`
+- Modify: `packages/web/src/features/settings/components/settings-page.test.tsx`
+- Modify: `packages/web/src/locales/en.json`
+- Modify: `packages/web/src/locales/zh.json`
+- Modify: `packages/web/src/styles/components.css`
+
+- [ ] **Step 1: Write the failing client-API and settings-panel tests**
+
+Create `packages/web/src/features/settings/components/proxy-access-api.test.ts` with:
+
+```ts
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  createProxyGrant,
+  extendProxyGrant,
+  listProxyGrants,
+  revokeProxyGrant,
+  rotateProxyGrant,
+} from "./proxy-access-api";
+
+describe("proxy-access-api", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("calls the expected proxy management endpoints with credentials", async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValue(new Response(JSON.stringify({ proxyOrigin: "http://localhost:4445", grants: [] }), { status: 200 }))
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ proxyOrigin: "http://localhost:4445", grants: [] }), {
+          status: 200,
+        })
+      );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await listProxyGrants();
+    await createProxyGrant({
+      label: "grafana",
+      targetOrigin: "http://localhost:3000",
+      allowWebSocket: true,
+      ttlMs: 60_000,
+    });
+    await extendProxyGrant("pgr_1", 120_000);
+    await rotateProxyGrant("pgr_1");
+    await revokeProxyGrant("pgr_1");
+
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      1,
+      "/api/proxy/grants",
+      expect.objectContaining({
+        credentials: "include",
+      })
+    );
+    expect(fetchMock).toHaveBeenNthCalledWith(
+      2,
+      "/api/proxy/grants",
+      expect.objectContaining({
+        method: "POST",
+        credentials: "include",
+      })
+    );
+  });
+});
+```
+
+Create `packages/web/src/features/settings/components/proxy-access-settings.test.tsx` with:
+
+```tsx
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { ProxyAccessSettings } from "./proxy-access-settings";
+
+describe("ProxyAccessSettings", () => {
+  it("creates a grant and shows the one-time token modal", async () => {
+    const api = {
+      listProxyGrants: vi.fn(async () => ({
+        proxyOrigin: "http://localhost:4445",
+        grants: [],
+      })),
+      createProxyGrant: vi.fn(async () => ({
+        id: "pgr_1",
+        label: "grafana",
+        targetOrigin: "http://localhost:3000",
+        allowWebSocket: true,
+        expiresAt: 1000,
+        proxyOrigin: "http://localhost:4445",
+        grantToken: "pgt_created",
+      })),
+      extendProxyGrant: vi.fn(),
+      rotateProxyGrant: vi.fn(),
+      revokeProxyGrant: vi.fn(),
+    };
+
+    render(<ProxyAccessSettings api={api as never} />);
+
+    fireEvent.change(screen.getByLabelText("Label"), { target: { value: "grafana" } });
+    fireEvent.change(screen.getByLabelText("Target Origin"), {
+      target: { value: "http://localhost:3000" },
+    });
+    fireEvent.click(screen.getByLabelText("Allow WebSocket"));
+    fireEvent.click(screen.getByRole("button", { name: "Create Grant" }));
+
+    await waitFor(() => {
+      expect(api.createProxyGrant).toHaveBeenCalledWith({
+        label: "grafana",
+        targetOrigin: "http://localhost:3000",
+        allowWebSocket: true,
+        ttlMs: expect.any(Number),
+      });
+    });
+
+    expect(screen.getByText("pgt_created")).toBeInTheDocument();
+    expect(screen.getByText("http://localhost:4445")).toBeInTheDocument();
+  });
+
+  it("renders grant rows and wires extend, rotate, and revoke actions", async () => {
+    const api = {
+      listProxyGrants: vi.fn(async () => ({
+        proxyOrigin: "http://localhost:4445",
+        grants: [
+          {
+            id: "pgr_1",
+            label: "grafana",
+            targetOrigin: "http://localhost:3000",
+            allowWebSocket: true,
+            createdAt: 1,
+            expiresAt: 2,
+            revokedAt: null,
+            lastUsedAt: null,
+            lastUsedIp: null,
+          },
+        ],
+      })),
+      createProxyGrant: vi.fn(),
+      extendProxyGrant: vi.fn(async () => ({})),
+      rotateProxyGrant: vi.fn(async () => ({
+        id: "pgr_1",
+        proxyOrigin: "http://localhost:4445",
+        grantToken: "pgt_rotated",
+      })),
+      revokeProxyGrant: vi.fn(async () => ({})),
+    };
+
+    render(<ProxyAccessSettings api={api as never} />);
+
+    expect(await screen.findByText("grafana")).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Extend" }));
+    fireEvent.click(screen.getByRole("button", { name: "Rotate" }));
+    fireEvent.click(screen.getByRole("button", { name: "Revoke" }));
+
+    await waitFor(() => {
+      expect(api.extendProxyGrant).toHaveBeenCalledWith("pgr_1", expect.any(Number));
+      expect(api.rotateProxyGrant).toHaveBeenCalledWith("pgr_1");
+      expect(api.revokeProxyGrant).toHaveBeenCalledWith("pgr_1");
+    });
+  });
+});
+```
+
+- [ ] **Step 2: Run the failing web tests**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web test -- proxy-access-api.test.ts proxy-access-settings.test.tsx settings-page.test.tsx
+```
+
+Expected: FAIL because the API wrapper and panel components do not exist and Settings does not yet expose a `proxy` section.
+
+- [ ] **Step 3: Implement the client API, panel, route wiring, and strings**
+
+Create `packages/web/src/features/settings/components/proxy-access-api.ts`:
+
+```ts
+export interface ProxyGrantView {
+  id: string;
+  label: string;
+  targetOrigin: string;
+  allowWebSocket: boolean;
+  createdAt: number;
+  expiresAt: number;
+  revokedAt: number | null;
+  lastUsedAt: number | null;
+  lastUsedIp: string | null;
+}
+
+export interface ProxyGrantSecretView extends ProxyGrantView {
+  proxyOrigin: string;
+  grantToken: string;
+}
+
+async function readJson<T>(input: RequestInfo, init?: RequestInit): Promise<T> {
+  const response = await fetch(input, {
+    credentials: "include",
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      ...(init?.headers ?? {}),
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`proxy_request_failed:${response.status}`);
+  }
+
+  return (await response.json()) as T;
+}
+
+export function listProxyGrants() {
+  return readJson<{ proxyOrigin?: string; grants: ProxyGrantView[] }>("/api/proxy/grants");
+}
+
+export function createProxyGrant(input: {
+  label: string;
+  targetOrigin: string;
+  allowWebSocket: boolean;
+  ttlMs: number;
+}) {
+  return readJson<ProxyGrantSecretView>("/api/proxy/grants", {
+    method: "POST",
+    body: JSON.stringify(input),
+  });
+}
+
+export function extendProxyGrant(id: string, ttlMs: number) {
+  return readJson<ProxyGrantView>(`/api/proxy/grants/${id}/extend`, {
+    method: "POST",
+    body: JSON.stringify({ ttlMs }),
+  });
+}
+
+export function rotateProxyGrant(id: string) {
+  return readJson<ProxyGrantSecretView>(`/api/proxy/grants/${id}/rotate`, {
+    method: "POST",
+    body: JSON.stringify({}),
+  });
+}
+
+export function revokeProxyGrant(id: string) {
+  return readJson<ProxyGrantView>(`/api/proxy/grants/${id}`, {
+    method: "DELETE",
+  });
+}
+```
+
+Create `packages/web/src/features/settings/components/proxy-access-settings.tsx` with a focused component that:
+
+- loads grant data on mount
+- renders a create form with `label`, `targetOrigin`, `allowWebSocket`, and `TTL`
+- shows a setup modal after create and rotate
+- renders a flat row list with `Extend`, `Rotate`, and `Revoke`
+- accepts an optional `api` prop to ease testing
+
+Use a structure like:
+
+```tsx
+import { useEffect, useState } from "react";
+import {
+  Button,
+  Input,
+  Modal,
+  ModalBody,
+  ModalFooter,
+  ModalHeader,
+  ModalTitle,
+  Notice,
+  Switch,
+} from "../../../components/ui";
+import { useTranslation } from "../../../lib/i18n";
+import * as defaultApi from "./proxy-access-api";
+
+const TTL_OPTIONS = [
+  { label: "1 hour", value: 60 * 60 * 1000 },
+  { label: "24 hours", value: 24 * 60 * 60 * 1000 },
+  { label: "7 days", value: 7 * 24 * 60 * 60 * 1000 },
+];
+
+export function ProxyAccessSettings({
+  api = defaultApi,
+}: {
+  api?: typeof defaultApi;
+}) {
+  const t = useTranslation();
+  const [label, setLabel] = useState("");
+  const [targetOrigin, setTargetOrigin] = useState("");
+  const [allowWebSocket, setAllowWebSocket] = useState(true);
+  const [ttlMs, setTtlMs] = useState(TTL_OPTIONS[1]!.value);
+  const [grants, setGrants] = useState<defaultApi.ProxyGrantView[]>([]);
+  const [proxyOrigin, setProxyOrigin] = useState("");
+  const [secret, setSecret] = useState<defaultApi.ProxyGrantSecretView | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const reload = async () => {
+    try {
+      const result = await api.listProxyGrants();
+      setGrants(result.grants);
+      if (result.proxyOrigin) {
+        setProxyOrigin(result.proxyOrigin);
+      }
+    } catch (nextError) {
+      setError((nextError as Error).message);
+    }
+  };
+
+  useEffect(() => {
+    void reload();
+  }, []);
+
+  return (
+    <div className="settings-section proxy-access-settings">
+      <div className="settings-group">
+        <h3 className="settings-group-title">{t("settings.proxy.title")}</h3>
+        <p className="settings-group-desc">{t("settings.proxy.description")}</p>
+        {error ? <Notice tone="error" message={error} /> : null}
+        <label>
+          <span>{t("settings.proxy.label")}</span>
+          <Input aria-label={t("settings.proxy.label")} value={label} onChange={(event) => setLabel(event.target.value)} />
+        </label>
+        <label>
+          <span>{t("settings.proxy.target_origin")}</span>
+          <Input
+            aria-label={t("settings.proxy.target_origin")}
+            value={targetOrigin}
+            onChange={(event) => setTargetOrigin(event.target.value)}
+          />
+        </label>
+        <label className="settings-toggle-row">
+          <span>{t("settings.proxy.allow_websocket")}</span>
+          <Switch
+            aria-label={t("settings.proxy.allow_websocket")}
+            checked={allowWebSocket}
+            onCheckedChange={setAllowWebSocket}
+          />
+        </label>
+        <div className="settings-actions-row">
+          {TTL_OPTIONS.map((option) => (
+            <Button
+              key={option.value}
+              type="button"
+              variant={ttlMs === option.value ? "primary" : "secondary"}
+              onClick={() => setTtlMs(option.value)}
+            >
+              {option.label}
+            </Button>
+          ))}
+        </div>
+        <Button
+          onClick={async () => {
+            const created = await api.createProxyGrant({
+              label,
+              targetOrigin,
+              allowWebSocket,
+              ttlMs,
+            });
+            setSecret(created);
+            setProxyOrigin(created.proxyOrigin);
+            await reload();
+          }}
+        >
+          {t("settings.proxy.create_grant")}
+        </Button>
+      </div>
+
+      <div className="settings-group">
+        {grants.map((grant) => (
+          <div key={grant.id} className="proxy-access-settings__row">
+            <div>
+              <strong>{grant.label}</strong>
+              <div>{grant.targetOrigin}</div>
+            </div>
+            <div className="settings-actions-row">
+              <Button type="button" variant="secondary" onClick={async () => { await api.extendProxyGrant(grant.id, ttlMs); await reload(); }}>
+                {t("settings.proxy.extend")}
+              </Button>
+              <Button
+                type="button"
+                variant="secondary"
+                onClick={async () => {
+                  const rotated = await api.rotateProxyGrant(grant.id);
+                  setSecret(rotated);
+                  setProxyOrigin(rotated.proxyOrigin);
+                  await reload();
+                }}
+              >
+                {t("settings.proxy.rotate")}
+              </Button>
+              <Button type="button" variant="danger" onClick={async () => { await api.revokeProxyGrant(grant.id); await reload(); }}>
+                {t("settings.proxy.revoke")}
+              </Button>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <Modal
+        open={Boolean(secret)}
+        onOpenChange={(open) => {
+          if (!open) {
+            setSecret(null);
+          }
+        }}
+      >
+        <ModalHeader>
+          <ModalTitle>{t("settings.proxy.one_time_modal_title")}</ModalTitle>
+        </ModalHeader>
+        <ModalBody>
+        {secret ? (
+          <div className="proxy-access-settings__secret">
+            <p>{t("settings.proxy.one_time_modal_hint")}</p>
+            <code>{proxyOrigin}</code>
+            <code>{secret.targetOrigin}</code>
+            <code>{secret.grantToken}</code>
+          </div>
+        ) : null}
+        </ModalBody>
+        <ModalFooter>
+          <Button type="button" variant="secondary" onClick={() => setSecret(null)}>
+            {t("action.close")}
+          </Button>
+        </ModalFooter>
+      </Modal>
+    </div>
+  );
+}
+```
+
+Wire the section into `packages/web/src/features/settings/components/settings-sections.tsx`:
+
+```ts
+export type SettingsSection =
+  | "general"
+  | "providers"
+  | "appearance"
+  | "shortcuts"
+  | "proxy"
+  | "monitoring"
+  | "analysis"
+  | "diagnostics"
+  | "about";
+
+const VISIBLE_SETTINGS_SECTIONS = [
+  { id: "general", labelKey: "settings.general", iconSemantic: "nav.settings.general" },
+  { id: "providers", labelKey: "settings.providers", iconSemantic: "nav.settings.providers" },
+  { id: "appearance", labelKey: "settings.appearance", iconSemantic: "nav.settings.appearance" },
+  { id: "shortcuts", labelKey: "settings.shortcuts.title", iconSemantic: "nav.settings.shortcuts" },
+  { id: "proxy", labelKey: "settings.proxy.title", iconSemantic: "nav.settings.general" },
+] as const;
+```
+
+Wire `proxy` into `packages/web/src/features/more/routes.ts`:
+
+```ts
+{
+  id: "proxy",
+  labelKey: "settings.proxy.title",
+  hintKey: "more.section.settings.proxy_hint",
+  iconSemantic: "nav.settings.general",
+}
+```
+
+Mount the component inside `packages/web/src/features/settings/components/settings-page.tsx` wherever other settings sections render:
+
+```tsx
+import { ProxyAccessSettings } from "./proxy-access-settings";
+
+case "proxy":
+  return <ProxyAccessSettings />;
+```
+
+Also update the existing settings helpers in `settings-page.tsx` so the new section is valid everywhere:
+
+- add `"proxy"` to `EmbeddedSettingsSection`
+- add a `case "proxy"` branch in `getMobileSectionHintKey`
+- add `"proxy"` into one `MOBILE_SETTINGS_GROUPS` bucket
+- make `renderContent` return `<ProxyAccessSettings />` for the new branch
+
+Update `packages/web/src/features/more/page.tsx` and `packages/web/src/features/more/page.test.tsx` so `isEmbeddedSettingsSection("proxy")` is accepted and `/more/settings/proxy` renders the embedded settings page instead of falling back.
+
+Add locale keys in both locale files:
+
+```json
+"settings": {
+  "proxy": {
+    "title": "Proxy Access",
+    "description": "Create short-lived browser proxy grants for internal services.",
+    "label": "Label",
+    "target_origin": "Target Origin",
+    "allow_websocket": "Allow WebSocket",
+    "create_grant": "Create Grant",
+    "extend": "Extend",
+    "rotate": "Rotate",
+    "revoke": "Revoke",
+    "one_time_modal_title": "Grant Token",
+    "one_time_modal_hint": "This token is shown only once. Rotate the grant if you lose it."
+  }
+}
+```
+
+Add matching Chinese strings in `packages/web/src/locales/zh.json`.
+
+Add minimal CSS in `packages/web/src/styles/components.css`:
+
+```css
+.proxy-access-settings {
+  display: grid;
+  gap: 16px;
+}
+
+.proxy-access-settings__row {
+  display: flex;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 12px 0;
+  border-top: 1px solid var(--color-border-subtle);
+}
+
+.proxy-access-settings__secret {
+  display: grid;
+  gap: 8px;
+}
+
+.proxy-access-settings__secret code {
+  display: block;
+  padding: 10px 12px;
+  border-radius: 10px;
+  background: var(--color-surface-elevated);
+  word-break: break-all;
+}
+```
+
+- [ ] **Step 4: Run the web tests again**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web test -- proxy-access-api.test.ts proxy-access-settings.test.tsx settings-page.test.tsx
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/web/src/features/settings/components/settings-sections.tsx packages/web/src/features/more/routes.ts packages/web/src/features/more/page.tsx packages/web/src/features/more/page.test.tsx packages/web/src/features/settings/components/proxy-access-api.ts packages/web/src/features/settings/components/proxy-access-api.test.ts packages/web/src/features/settings/components/proxy-access-settings.tsx packages/web/src/features/settings/components/proxy-access-settings.test.tsx packages/web/src/features/settings/components/settings-page.tsx packages/web/src/features/settings/components/settings-page.test.tsx packages/web/src/locales/en.json packages/web/src/locales/zh.json packages/web/src/styles/components.css
+git commit -m "feat(web): add proxy access settings panel"
+```
+
+## Task 5: Integration Verification and Cleanup
+
+**Files:**
+- Modify as needed based on failures from previous tasks only
+
+- [ ] **Step 1: Run focused server verification**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server test -- proxy/target-policy.test.ts storage/repositories/proxy-grant-repo.test.ts proxy/grant-service.test.ts routes/proxy-grants.test.ts proxy/cookie-jar.test.ts proxy/headers.test.ts proxy/proxy-app.test.ts __tests__/server-runtime-config.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run focused web verification**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web test -- proxy-access-api.test.ts proxy-access-settings.test.tsx settings-page.test.tsx
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Run repository-level verification for touched packages**
+
+Run:
+
+```bash
+pnpm lint
+pnpm ci:test
+```
+
+Expected: PASS. If `pnpm ci:test` is too slow for the current execution budget, at minimum capture which package suites were run and explicitly note the skipped repository-level command before handoff.
+
+- [ ] **Step 4: Commit any last verification-driven fixes**
+
+```bash
+git add -A
+git commit -m "test: verify external browser proxy grants flow"
+```
+
+- [ ] **Step 5: Prepare handoff notes**
+
+Record:
+
+- proxy origin and main UI origin assumptions
+- environment variables required to enable non-loopback targets
+- the current v1 limitation around hard-coded absolute upstream URLs
+- whether repository-level verification completed successfully
diff --git a/docs/superpowers/plans/2026-06-20-global-custom-skills.md b/docs/superpowers/plans/2026-06-20-global-custom-skills.md
new file mode 100644
index 000000000..b205a4a59
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-20-global-custom-skills.md
@@ -0,0 +1,181 @@
+# Global Custom Skills Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add first-class global custom skill creation and management to the Skills panel, including product-created `local` skills, a skill file tree, existing-editor reuse for skill files, and drag-to-agent path handoff.
+
+**Architecture:** Keep custom skills as ordinary `source="local"` entries under `~/.agents/skills` instead of inventing a new domain model. Server-side, add a small custom-skill creation command, a skill-file CRUD/readTree command set, and a dedicated `/api/skill-file` image route rooted at `SkillLibraryEntry.libraryPath`; deletion continues to use the existing `skills.uninstall` flow. Client-side, add a `Custom Skills` section and local-skill detail file tree to the existing Skills panel, and reuse the existing editor with a `skill:<slug>/<relative-path>` editor path that reads and writes through `skills.files.*`; for v1, treat skill files as non-workspace-backed Monaco models so we avoid polluting workspace file/LSP state.
+
+**Tech Stack:** TypeScript, React, Jotai, Fastify, Vitest, existing skills domain and workspace editor infrastructure
+
+---
+
+## File Structure
+
+### Server
+
+- Create: `packages/server/src/skills/custom-skill.ts`
+- Create: `packages/server/src/commands/skills/custom.ts`
+- Create: `packages/server/src/commands/skills/files.ts`
+- Create: `packages/server/src/routes/skill-file-asset.ts`
+- Create: `packages/server/src/__tests__/skills/custom-skill.test.ts`
+- Create: `packages/server/src/__tests__/skills/file-io.test.ts`
+- Create: `packages/server/src/routes/skill-file-asset.test.ts`
+- Modify: `packages/server/src/commands/skills/index.ts`
+- Modify: `packages/server/src/storage/repositories/skill-library-repo.ts`
+- Modify: `packages/server/src/commands/skills/shared.ts`
+- Modify: `packages/server/src/app.ts`
+- Modify: `packages/server/src/__tests__/skills/commands.test.ts`
+
+### Web
+
+- Create: `packages/web/src/features/code-editor/skill-editor-path.ts`
+- Create: `packages/web/src/features/code-editor/skill-editor-path.test.ts`
+- Create: `packages/web/src/features/workspace/actions/use-skill-file-actions.ts`
+- Create: `packages/web/src/features/workspace/actions/use-skill-file-actions.test.tsx`
+- Create: `packages/web/src/lib/skill-path-drag.ts`
+- Create: `packages/web/src/lib/skill-path-drag.test.ts`
+- Modify: `packages/web/src/features/code-editor/actions/use-code-editor-actions.ts`
+- Modify: `packages/web/src/features/code-editor/views/shared/editor-surface.tsx`
+- Modify: `packages/web/src/features/code-editor/index.test.tsx`
+- Modify: `packages/web/src/features/workspace/atoms/skills.ts`
+- Modify: `packages/web/src/features/workspace/actions/use-skills-panel.ts`
+- Modify: `packages/web/src/features/workspace/views/shared/skills-panel.tsx`
+- Modify: `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+- Modify: `packages/web/src/features/agent-panes/views/shared/editor-pane-card.tsx`
+- Modify: `packages/web/src/features/agent-panes/views/shared/editor-pane-card.test.tsx`
+- Modify: `packages/web/src/features/agent-panes/views/shared/draft-launcher.tsx`
+- Modify: `packages/web/src/features/agent-panes/views/shared/draft-launcher.test.tsx`
+- Modify: `packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.ts`
+- Modify: `packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx`
+- Modify: `packages/web/src/locales/en.json`
+- Modify: `packages/web/src/locales/zh.json`
+
+### Intentional Omissions In V1
+
+- Do not add a second embedded editor inside the Skills panel.
+- Do not extend workspace file-tree atoms to pretend skill files belong to a workspace.
+- Do not wire skill files into workspace-backed Monaco/LSP paths in v1.
+- Do not add a new delete command if the existing `skills.uninstall` flow already covers local skills safely.
+
+---
+
+### Task 1: Add server-side custom skill creation support
+
+**Files:**
+- Create: `packages/server/src/skills/custom-skill.ts`
+- Create: `packages/server/src/commands/skills/custom.ts`
+- Create: `packages/server/src/__tests__/skills/custom-skill.test.ts`
+- Modify: `packages/server/src/commands/skills/index.ts`
+- Modify: `packages/server/src/storage/repositories/skill-library-repo.ts`
+- Modify: `packages/server/src/__tests__/skills/commands.test.ts`
+
+- [ ] **Step 1: Write the failing helper tests**
+- [ ] **Step 2: Run the helper tests to verify they fail**
+- [ ] **Step 3: Write the failing command test for `skills.custom.create`**
+- [ ] **Step 4: Run the command test to verify it fails**
+- [ ] **Step 5: Implement the helper and command**
+- [ ] **Step 6: Register the new command**
+- [ ] **Step 7: Run the focused tests to verify they pass**
+- [ ] **Step 8: Commit**
+
+### Task 2: Add server-side skill file tree, file IO, and asset routing
+
+**Files:**
+- Create: `packages/server/src/commands/skills/files.ts`
+- Create: `packages/server/src/routes/skill-file-asset.ts`
+- Create: `packages/server/src/__tests__/skills/file-io.test.ts`
+- Create: `packages/server/src/routes/skill-file-asset.test.ts`
+- Modify: `packages/server/src/commands/skills/index.ts`
+- Modify: `packages/server/src/commands/skills/shared.ts`
+- Modify: `packages/server/src/app.ts`
+- Modify: `packages/server/src/__tests__/skills/commands.test.ts`
+
+- [ ] **Step 1: Write the failing server tests for skill file access**
+- [ ] **Step 2: Run the new file IO tests to verify they fail**
+- [ ] **Step 3: Write failing command tests**
+- [ ] **Step 4: Write the failing asset-route test**
+- [ ] **Step 5: Implement `skills.files.*` commands by reusing existing FS helpers**
+- [ ] **Step 6: Implement `/api/skill-file`**
+- [ ] **Step 7: Wire the new route and commands**
+- [ ] **Step 8: Run the focused server tests to verify they pass**
+- [ ] **Step 9: Commit**
+
+### Task 3: Reuse the existing editor with a `skill:` path source
+
+**Files:**
+- Create: `packages/web/src/features/code-editor/skill-editor-path.ts`
+- Create: `packages/web/src/features/code-editor/skill-editor-path.test.ts`
+- Modify: `packages/web/src/features/code-editor/actions/use-code-editor-actions.ts`
+- Modify: `packages/web/src/features/code-editor/views/shared/editor-surface.tsx`
+- Modify: `packages/web/src/features/code-editor/index.test.tsx`
+
+- [ ] **Step 1: Write the failing path helper tests**
+- [ ] **Step 2: Run the helper tests to verify they fail**
+- [ ] **Step 3: Add failing editor integration tests**
+- [ ] **Step 4: Run the editor tests to verify they fail**
+- [ ] **Step 5: Implement `skill-editor-path.ts`**
+- [ ] **Step 6: Route skill editor paths through `skills.files.read/write`**
+- [ ] **Step 7: Keep skill files out of workspace-backed Monaco/LSP state in v1**
+- [ ] **Step 8: Run the focused web tests to verify they pass**
+- [ ] **Step 9: Commit**
+
+### Task 4: Extend Skills panel actions and add a skill-file tree hook
+
+**Files:**
+- Create: `packages/web/src/features/workspace/actions/use-skill-file-actions.ts`
+- Create: `packages/web/src/features/workspace/actions/use-skill-file-actions.test.tsx`
+- Modify: `packages/web/src/features/workspace/atoms/skills.ts`
+- Modify: `packages/web/src/features/workspace/actions/use-skills-panel.ts`
+
+- [ ] **Step 1: Keep panel state changes minimal**
+- [ ] **Step 2: Add failing tests for the new hook**
+- [ ] **Step 3: Run the hook tests to verify they fail**
+- [ ] **Step 4: Implement `useSkillFileActions`**
+- [ ] **Step 5: Extend `useSkillsPanel` with custom-skill actions**
+- [ ] **Step 6: Run the focused web tests to verify they pass**
+- [ ] **Step 7: Commit**
+
+### Task 5: Build the `Custom Skills` section and skill detail file tree
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/views/shared/skills-panel.tsx`
+- Modify: `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+- Modify: `packages/web/src/locales/en.json`
+- Modify: `packages/web/src/locales/zh.json`
+
+- [ ] **Step 1: Add failing UI tests**
+- [ ] **Step 2: Run the panel tests to verify they fail**
+- [ ] **Step 3: Implement the `Custom Skills` section**
+- [ ] **Step 4: Implement the local-skill detail file tree**
+- [ ] **Step 5: Add create/manage interactions**
+- [ ] **Step 6: Run the focused panel tests to verify they pass**
+- [ ] **Step 7: Commit**
+
+### Task 6: Add drag/drop integration for skill files and directories
+
+**Files:**
+- Create: `packages/web/src/lib/skill-path-drag.ts`
+- Create: `packages/web/src/lib/skill-path-drag.test.ts`
+- Modify: `packages/web/src/features/agent-panes/views/shared/editor-pane-card.tsx`
+- Modify: `packages/web/src/features/agent-panes/views/shared/editor-pane-card.test.tsx`
+- Modify: `packages/web/src/features/agent-panes/views/shared/draft-launcher.tsx`
+- Modify: `packages/web/src/features/agent-panes/views/shared/draft-launcher.test.tsx`
+- Modify: `packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.ts`
+- Modify: `packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx`
+
+- [ ] **Step 1: Add failing drag helper tests**
+- [ ] **Step 2: Run the helper tests to verify they fail**
+- [ ] **Step 3: Add failing integration tests**
+- [ ] **Step 4: Run the drag/drop tests to verify they fail**
+- [ ] **Step 5: Implement skill-path drag data**
+- [ ] **Step 6: Open skill files in the editor when dropped on editor targets**
+- [ ] **Step 7: Insert absolute skill paths in terminal/agent targets**
+- [ ] **Step 8: Run the focused drag/drop tests to verify they pass**
+- [ ] **Step 9: Commit**
+
+### Final Verification
+
+- [ ] Run targeted server and web Vitest suites touched above.
+- [ ] Run `pnpm ci:verify`.
+- [ ] Review the final diff in code-review mindset.
diff --git a/docs/superpowers/plans/2026-06-20-mobile-agent-provider-compact.md b/docs/superpowers/plans/2026-06-20-mobile-agent-provider-compact.md
new file mode 100644
index 000000000..2c0249b37
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-20-mobile-agent-provider-compact.md
@@ -0,0 +1,53 @@
+# Mobile Agent Provider Compact Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Remove the redundant mobile provider description line for launch-ready agents and slightly tighten the mobile provider list spacing without changing desktop behavior.
+
+**Architecture:** Keep the change inside the existing `MobileAgentSheet` data mapping and the mobile command sheet stylesheet. Launch-ready providers omit the default description, while providers with guidance continue to populate it. Add one agent-sheet-specific class to scope density changes to this view only.
+
+**Tech Stack:** React, TypeScript, Vitest, CSS tokens
+
+---
+
+### Task 1: Lock the desired mobile behavior with tests
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx`
+- Modify: `packages/web/src/styles/components.theme.test.ts`
+
+- [ ] **Step 1: Write the failing component expectation**
+
+Add assertions proving launch-ready providers do not render `Start Codex session` while still rendering `Start new session`.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx src/styles/components.theme.test.ts`
+
+Expected: the component test still finds the removed default description and the theme test cannot find the new agent-sheet compact selector.
+
+### Task 2: Implement the mobile-only compaction
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.tsx`
+- Modify: `packages/web/src/styles/components.css`
+
+- [ ] **Step 1: Omit the default provider description**
+
+Set the provider item description to `guideMessage` only, leaving launch-ready providers with no description line.
+
+- [ ] **Step 2: Scope density styles to the mobile agent sheet**
+
+Add an agent-sheet class to `MobileSelectSheet` and tighten only its row padding and copy gap.
+
+### Task 3: Verify the result
+
+**Files:**
+- Test: `packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx`
+- Test: `packages/web/src/styles/components.theme.test.ts`
+
+- [ ] **Step 1: Run focused verification**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx src/styles/components.theme.test.ts`
+
+Expected: PASS with all tests green.
diff --git a/docs/superpowers/plans/2026-06-21-canvas-restore.md b/docs/superpowers/plans/2026-06-21-canvas-restore.md
new file mode 100644
index 000000000..fd7b84564
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-21-canvas-restore.md
@@ -0,0 +1,814 @@
+# Canvas Restore Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Restore the removed canvas feature on current `develop` so Coder Studio can create, render, open, and refresh `architecture_canvas` and `report_canvas` artifacts as first-class editor tabs backed by real workspace files.
+
+**Architecture:** Reintroduce the old canvas flow in the smallest compatible shape: restore the core contracts, the server-side repository/service/command/route chain, the frontend canvas tab plus embedded route/renderers, and the CLI wrappers. Keep source-of-truth in `.coder-studio/canvases/*.canvas.json`, keep validation/compilation on the server, and keep the canvas tab as a viewer plus source-file shortcut instead of an in-place editor.
+
+**Tech Stack:** TypeScript, Zod, Fastify, React, React Router, Jotai, Vitest, existing workspace editor and UI action infrastructure
+
+---
+
+## Reference Spec
+
+Read first:
+
+- `docs/superpowers/specs/2026-06-21-canvas-restore-design.md`
+
+Key requirements this plan implements:
+
+- restore `architecture_canvas` and `report_canvas`
+- restore source files under `.coder-studio/canvases/*.canvas.json`
+- restore `canvas.list/create/update/render`
+- restore `canvas.open`
+- restore `/embedded/canvas/:workspaceId/:canvasId`
+- restore `/api/canvas/:workspaceId/:canvasId/data`
+- restore the canvas editor tab with `Open source` and `Refresh`
+
+## File Structure
+
+### Core contracts
+
+- Create: `packages/core/src/domain/canvas.ts`
+- Create: `packages/core/src/domain/canvas.test.ts`
+- Modify: `packages/core/src/domain/types.ts`
+- Modify: `packages/core/src/domain/ui-actions.ts`
+- Modify: `packages/core/src/index.ts`
+
+### Server runtime
+
+- Create: `packages/server/src/canvas/compiler.ts`
+- Create: `packages/server/src/canvas/compiler.test.ts`
+- Create: `packages/server/src/canvas/graph-v1.ts`
+- Create: `packages/server/src/canvas/graph-v1.test.ts`
+- Create: `packages/server/src/canvas/mermaid-flowchart.ts`
+- Create: `packages/server/src/canvas/mermaid-flowchart.test.ts`
+- Create: `packages/server/src/canvas/service.ts`
+- Create: `packages/server/src/canvas/service.test.ts`
+- Create: `packages/server/src/canvas/validation.ts`
+- Create: `packages/server/src/canvas/validation.test.ts`
+- Create: `packages/server/src/commands/canvas.ts`
+- Create: `packages/server/src/routes/canvas.ts`
+- Create: `packages/server/src/routes/canvas.test.ts`
+- Create: `packages/server/src/storage/repositories/canvas-repo.ts`
+- Create: `packages/server/src/storage/repositories/canvas-repo.test.ts`
+- Modify: `packages/server/src/commands/index.ts`
+- Modify: `packages/server/src/app.ts`
+- Modify: `packages/server/src/server.ts`
+- Modify: `packages/server/src/ws/dispatch.ts`
+- Modify: `packages/server/src/app-routing.test.ts`
+
+### Web
+
+- Modify: `packages/web/src/app.tsx`
+- Modify: `packages/web/src/app.test.tsx`
+- Create: `packages/web/src/features/canvas/api.ts`
+- Create: `packages/web/src/features/canvas/components/architecture-canvas-renderer.tsx`
+- Create: `packages/web/src/features/canvas/components/architecture-canvas-renderer.test.tsx`
+- Create: `packages/web/src/features/canvas/components/canvas-route-frame.tsx`
+- Create: `packages/web/src/features/canvas/components/report-canvas-renderer.tsx`
+- Create: `packages/web/src/features/canvas/routes/embedded-canvas-route.tsx`
+- Create: `packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx`
+- Modify: `packages/web/src/features/workspace/atoms/files.ts`
+- Modify: `packages/web/src/features/ui-actions/use-ui-action-subscription.ts`
+- Modify: `packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/editor-surface.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/editor-surface.test.tsx`
+- Create: `packages/web/src/features/code-editor/views/shared/canvas-surface.tsx`
+- Create: `packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx`
+
+### CLI
+
+- Modify: `packages/cli/src/parse-args.ts`
+- Modify: `packages/cli/src/cli.ts`
+- Modify: `packages/cli/src/bin.test.ts`
+
+---
+
+### Task 1: Restore Core Canvas Contracts
+
+**Files:**
+- Create: `packages/core/src/domain/canvas.ts`
+- Create: `packages/core/src/domain/canvas.test.ts`
+- Modify: `packages/core/src/domain/types.ts`
+- Modify: `packages/core/src/domain/ui-actions.ts`
+- Modify: `packages/core/src/index.ts`
+
+- [ ] **Step 1: Add the failing core canvas tests**
+
+Create `packages/core/src/domain/canvas.test.ts` with the contract checks restored from the old implementation:
+
+```ts
+import { describe, expect, it } from "vitest";
+import { CanvasDataResponseSchema, parseCanvasDocumentEnvelope } from "./canvas.js";
+
+describe("canvas domain", () => {
+  it("parses an architecture canvas envelope", () => {
+    const parsed = parseCanvasDocumentEnvelope({
+      version: 1,
+      kind: "architecture_canvas",
+      title: "Runtime Flow",
+      document: {
+        summary: "How requests move.",
+        diagram: {
+          dsl: "graph_v1",
+          source: "node WebUI\nnode Server\nedge WebUI -> Server",
+        },
+        annotations: [{ title: "Boundary", body: "Server owns execution." }],
+      },
+    });
+
+    expect(parsed.kind).toBe("architecture_canvas");
+    expect(parsed.document.diagram.dsl).toBe("graph_v1");
+  });
+
+  it("rejects ready responses without a compiled document", () => {
+    const result = CanvasDataResponseSchema.safeParse({
+      canvasId: "canvas-1",
+      workspaceId: "ws-1",
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      renderStatus: "ready",
+      lastError: null,
+    });
+
+    expect(result.success).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run the core canvas test and verify it fails**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core exec vitest run src/domain/canvas.test.ts
+```
+
+Expected: FAIL because `src/domain/canvas.ts` does not exist and the exports are missing.
+
+- [ ] **Step 3: Restore the core canvas domain types and exports**
+
+Recreate `packages/core/src/domain/canvas.ts` from commit `277fe754` and wire it into the current package:
+
+- export `CanvasArtifactKind`
+- export `CANVAS_DOCUMENT_VERSION`
+- export `CanvasRenderStatus`
+- export `CanvasErrorCategory`
+- export `CanvasRenderErrorSchema`
+- export `CanvasDocumentEnvelopeSchema`
+- export `CompiledCanvasSchema`
+- export `CanvasDataResponseSchema`
+- export `parseCanvasDocumentEnvelope()`
+- export the corresponding TypeScript types
+
+Also:
+
+- update `packages/core/src/domain/types.ts` to restore:
+
+```ts
+export interface WorkspaceCanvasEditorTab {
+  kind: "canvas";
+  id: string;
+  canvasId: string;
+  title: string;
+  artifactType: "architecture_canvas" | "report_canvas";
+  sourcePath: string;
+}
+
+export type WorkspaceEditorTab =
+  | WorkspaceFileEditorTab
+  | WorkspaceBrowserEditorTab
+  | WorkspaceCanvasEditorTab;
+```
+
+- update `packages/core/src/domain/ui-actions.ts` to restore:
+
+```ts
+| {
+    type: "canvas.open";
+    workspaceId?: string;
+    canvasId: string;
+    title: string;
+    artifactType: CanvasArtifactKind;
+    sourcePath: string;
+  }
+```
+
+- update `packages/core/src/index.ts` to export `./domain/canvas`
+
+- [ ] **Step 4: Re-run the core canvas test and verify it passes**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core exec vitest run src/domain/canvas.test.ts
+```
+
+Expected: PASS with the new domain file, `canvas.open`, and canvas tab types in place.
+
+- [ ] **Step 5: Commit Task 1**
+
+Run:
+
+```bash
+git add packages/core/src/domain/canvas.ts packages/core/src/domain/canvas.test.ts packages/core/src/domain/types.ts packages/core/src/domain/ui-actions.ts packages/core/src/index.ts
+git commit -m "feat(core): restore canvas domain contracts"
+```
+
+### Task 2: Restore Canvas Storage, Validation, And Compilation
+
+**Files:**
+- Create: `packages/server/src/storage/repositories/canvas-repo.ts`
+- Create: `packages/server/src/storage/repositories/canvas-repo.test.ts`
+- Create: `packages/server/src/canvas/validation.ts`
+- Create: `packages/server/src/canvas/validation.test.ts`
+- Create: `packages/server/src/canvas/compiler.ts`
+- Create: `packages/server/src/canvas/compiler.test.ts`
+- Create: `packages/server/src/canvas/graph-v1.ts`
+- Create: `packages/server/src/canvas/graph-v1.test.ts`
+- Create: `packages/server/src/canvas/mermaid-flowchart.ts`
+- Create: `packages/server/src/canvas/mermaid-flowchart.test.ts`
+
+- [ ] **Step 1: Add the failing repository and compiler tests**
+
+Restore the old repository and compiler tests from commit `277fe754`:
+
+- `packages/server/src/storage/repositories/canvas-repo.test.ts`
+- `packages/server/src/canvas/validation.test.ts`
+- `packages/server/src/canvas/compiler.test.ts`
+- `packages/server/src/canvas/graph-v1.test.ts`
+- `packages/server/src/canvas/mermaid-flowchart.test.ts`
+
+Keep the tests focused on these behaviors:
+
+- repo `list/get/upsert/delete/removeWorkspace`
+- validation accepts good envelopes and reports field paths for invalid ones
+- `graph_v1` compilation produces nodes and edges
+- Mermaid flowchart compilation produces labeled nodes and edges
+- compiler produces `architecture_canvas` and `report_canvas` render models
+
+- [ ] **Step 2: Run the focused server tests and verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/storage/repositories/canvas-repo.test.ts src/canvas/validation.test.ts src/canvas/compiler.test.ts src/canvas/graph-v1.test.ts src/canvas/mermaid-flowchart.test.ts
+```
+
+Expected: FAIL because the files and exports are missing.
+
+- [ ] **Step 3: Restore the repo, validation, and compilation modules**
+
+Recreate the old implementation from commit `277fe754` for:
+
+- `packages/server/src/storage/repositories/canvas-repo.ts`
+- `packages/server/src/canvas/validation.ts`
+- `packages/server/src/canvas/compiler.ts`
+- `packages/server/src/canvas/graph-v1.ts`
+- `packages/server/src/canvas/mermaid-flowchart.ts`
+
+Keep the old behavior:
+
+- repo stores metadata JSON by workspace id under server state
+- validation parses the source envelope using the core schema
+- `graph_v1` converts the line DSL into nodes and edges
+- Mermaid flowchart parsing supports simple flowchart edges with optional labels
+- compiler returns `CompiledCanvas` objects only, never raw HTML
+
+- [ ] **Step 4: Re-run the focused server tests and verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/storage/repositories/canvas-repo.test.ts src/canvas/validation.test.ts src/canvas/compiler.test.ts src/canvas/graph-v1.test.ts src/canvas/mermaid-flowchart.test.ts
+```
+
+Expected: PASS with the restored repo and compilation pipeline.
+
+- [ ] **Step 5: Commit Task 2**
+
+Run:
+
+```bash
+git add packages/server/src/storage/repositories/canvas-repo.ts packages/server/src/storage/repositories/canvas-repo.test.ts packages/server/src/canvas/validation.ts packages/server/src/canvas/validation.test.ts packages/server/src/canvas/compiler.ts packages/server/src/canvas/compiler.test.ts packages/server/src/canvas/graph-v1.ts packages/server/src/canvas/graph-v1.test.ts packages/server/src/canvas/mermaid-flowchart.ts packages/server/src/canvas/mermaid-flowchart.test.ts
+git commit -m "feat(server): restore canvas storage and compilation"
+```
+
+### Task 3: Restore Canvas Service, Commands, And API Route
+
+**Files:**
+- Create: `packages/server/src/canvas/service.ts`
+- Create: `packages/server/src/canvas/service.test.ts`
+- Create: `packages/server/src/commands/canvas.ts`
+- Create: `packages/server/src/routes/canvas.ts`
+- Create: `packages/server/src/routes/canvas.test.ts`
+- Modify: `packages/server/src/commands/index.ts`
+- Modify: `packages/server/src/ws/dispatch.ts`
+- Modify: `packages/server/src/server.ts`
+- Modify: `packages/server/src/app.ts`
+- Modify: `packages/server/src/app-routing.test.ts`
+
+- [ ] **Step 1: Add the failing service and route tests**
+
+Restore the old service and route tests:
+
+- `packages/server/src/canvas/service.test.ts`
+- `packages/server/src/routes/canvas.test.ts`
+
+Add or restore app wiring assertions in `packages/server/src/app-routing.test.ts` that prove:
+
+- `GET /api/canvas/ws-1/canvas-1/data` does not fall through to `index.html`
+- the route is present when the app is assembled
+
+Use the existing route test cases from `277fe754`, especially:
+
+- create writes a source file and metadata record
+- valid canvas data returns `renderStatus: "ready"`
+- invalid source returns `renderStatus: "error"`
+- compile failure returns `renderStatus: "error"`
+- route returns 404 for missing workspace
+- route returns 404 for missing canvas
+
+- [ ] **Step 2: Run the focused server tests and verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/canvas/service.test.ts src/routes/canvas.test.ts src/app-routing.test.ts
+```
+
+Expected: FAIL because `CanvasService`, `registerCanvasRoutes`, and the server wiring are missing.
+
+- [ ] **Step 3: Restore the server canvas runtime and wire it into the app**
+
+Recreate the old server runtime from commit `277fe754` with minimal adaptation to current `develop`:
+
+- restore `packages/server/src/canvas/service.ts`
+- restore `packages/server/src/commands/canvas.ts`
+- restore `packages/server/src/routes/canvas.ts`
+
+Then integrate it:
+
+- update `packages/server/src/commands/index.ts` to import `./canvas.js`
+- update `packages/server/src/ws/dispatch.ts` to add:
+
+```ts
+canvasService?: CanvasService;
+```
+
+- update `packages/server/src/server.ts` to instantiate:
+
+```ts
+const canvasRepo = new CanvasRepo({
+  rootDir: join(stateRoot, "state", "canvases"),
+});
+const canvasService = new CanvasService({ canvasRepo });
+```
+
+and inject `canvasService` into the command context
+
+- update `packages/server/src/app.ts` to import and register `registerCanvasRoutes()`
+
+Keep the old command semantics:
+
+- `canvas.list`
+- `canvas.create`
+- `canvas.update`
+- `canvas.render`
+
+Keep `canvas.create` broadcasting `canvas.open` when `openInEditor` is true.
+
+- [ ] **Step 4: Re-run the focused server tests and verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/canvas/service.test.ts src/routes/canvas.test.ts src/app-routing.test.ts
+```
+
+Expected: PASS with the service, command, and route chain restored.
+
+- [ ] **Step 5: Commit Task 3**
+
+Run:
+
+```bash
+git add packages/server/src/canvas/service.ts packages/server/src/canvas/service.test.ts packages/server/src/commands/canvas.ts packages/server/src/routes/canvas.ts packages/server/src/routes/canvas.test.ts packages/server/src/commands/index.ts packages/server/src/ws/dispatch.ts packages/server/src/server.ts packages/server/src/app.ts packages/server/src/app-routing.test.ts
+git commit -m "feat(server): restore canvas command and route chain"
+```
+
+### Task 4: Restore Frontend Embedded Route And Renderers
+
+**Files:**
+- Modify: `packages/web/src/app.tsx`
+- Modify: `packages/web/src/app.test.tsx`
+- Create: `packages/web/src/features/canvas/api.ts`
+- Create: `packages/web/src/features/canvas/routes/embedded-canvas-route.tsx`
+- Create: `packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx`
+- Create: `packages/web/src/features/canvas/components/canvas-route-frame.tsx`
+- Create: `packages/web/src/features/canvas/components/architecture-canvas-renderer.tsx`
+- Create: `packages/web/src/features/canvas/components/architecture-canvas-renderer.test.tsx`
+- Create: `packages/web/src/features/canvas/components/report-canvas-renderer.tsx`
+
+- [ ] **Step 1: Add the failing app and embedded route tests**
+
+Restore the old embedded route test from `277fe754` into:
+
+- `packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx`
+
+Add one routing test to `packages/web/src/app.test.tsx` that proves
+`/embedded/canvas/ws-1/canvas-1` renders the embedded route instead of the normal shell:
+
+```ts
+vi.mock("./features/canvas/routes/embedded-canvas-route", () => ({
+  EmbeddedCanvasRoute: () => <div data-testid="embedded-canvas-route">Canvas</div>,
+}));
+
+it("renders the embedded canvas route when the canvas URL is requested", () => {
+  window.history.replaceState({}, "", "/embedded/canvas/ws-1/canvas-1");
+  render(
+    <Provider store={store}>
+      <App />
+    </Provider>
+  );
+
+  expect(screen.getByTestId("embedded-canvas-route")).toBeInTheDocument();
+});
+```
+
+- [ ] **Step 2: Run the focused web tests and verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web exec vitest run src/app.test.tsx src/features/canvas/routes/embedded-canvas-route.test.tsx
+```
+
+Expected: FAIL because the route and components do not exist.
+
+- [ ] **Step 3: Restore the embedded route, fetcher, and renderer components**
+
+Recreate the old frontend canvas feature from commit `277fe754`:
+
+- `packages/web/src/features/canvas/api.ts`
+- `packages/web/src/features/canvas/routes/embedded-canvas-route.tsx`
+- `packages/web/src/features/canvas/components/canvas-route-frame.tsx`
+- `packages/web/src/features/canvas/components/architecture-canvas-renderer.tsx`
+- `packages/web/src/features/canvas/components/report-canvas-renderer.tsx`
+
+Then update `packages/web/src/app.tsx` to restore:
+
+```tsx
+<Routes>
+  <Route path="/embedded/canvas/:workspaceId/:canvasId" element={<EmbeddedCanvasRoute />} />
+  <Route path="*" element={<ShellSwitch />} />
+</Routes>
+```
+
+Keep the embedded route states:
+
+- loading
+- request error
+- render error
+- ready
+
+- [ ] **Step 4: Re-run the focused web tests and verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web exec vitest run src/app.test.tsx src/features/canvas/routes/embedded-canvas-route.test.tsx
+```
+
+Expected: PASS with the embedded route and renderers restored.
+
+- [ ] **Step 5: Commit Task 4**
+
+Run:
+
+```bash
+git add packages/web/src/app.tsx packages/web/src/app.test.tsx packages/web/src/features/canvas/api.ts packages/web/src/features/canvas/routes/embedded-canvas-route.tsx packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx packages/web/src/features/canvas/components/canvas-route-frame.tsx packages/web/src/features/canvas/components/architecture-canvas-renderer.tsx packages/web/src/features/canvas/components/architecture-canvas-renderer.test.tsx packages/web/src/features/canvas/components/report-canvas-renderer.tsx
+git commit -m "feat(web): restore embedded canvas route and renderers"
+```
+
+### Task 5: Restore Canvas Tabs, UI Actions, And Editor Surface Integration
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/atoms/files.ts`
+- Modify: `packages/web/src/features/ui-actions/use-ui-action-subscription.ts`
+- Modify: `packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/editor-surface.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/editor-surface.test.tsx`
+- Create: `packages/web/src/features/code-editor/views/shared/canvas-surface.tsx`
+- Create: `packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx`
+
+- [ ] **Step 1: Add the failing UI action and editor surface tests**
+
+Restore the `canvas.open` test from commit `277fe754` into
+`packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx`:
+
+```ts
+it("opens and activates a canvas tab from canvas.open events", async () => {
+  await emit(
+    createEvent({
+      type: "canvas.open",
+      workspaceId: "ws-1",
+      canvasId: "canvas-1",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+    })
+  );
+
+  expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+    {
+      kind: "canvas",
+      id: "canvas:canvas-1",
+      canvasId: "canvas-1",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+    },
+  ]);
+});
+```
+
+Create `packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx` with:
+
+- an `Open source` click test that calls `openWorkspaceFile`
+- a `Refresh` click test that dispatches `canvas.render` and changes the iframe URL token
+
+Add one focused test to `packages/web/src/features/code-editor/views/shared/editor-surface.test.tsx`:
+
+```ts
+it("renders CanvasSurface when the active editor tab is a canvas tab", () => {
+  const state = createState({
+    activeFilePath: null,
+    activeEditorTab: {
+      kind: "canvas",
+      id: "canvas:canvas-1",
+      canvasId: "canvas-1",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+    },
+    openEditorTabs: [
+      {
+        kind: "canvas",
+        id: "canvas:canvas-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      },
+    ],
+  });
+
+  render(<EditorSurface state={state} />);
+
+  expect(screen.getByTitle("Runtime Flow canvas")).toBeInTheDocument();
+});
+```
+
+- [ ] **Step 2: Run the focused web tests and verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web exec vitest run src/features/ui-actions/use-ui-action-subscription.test.tsx src/features/code-editor/views/shared/editor-surface.test.tsx src/features/code-editor/views/shared/canvas-surface.test.tsx
+```
+
+Expected: FAIL because `canvas.open`, canvas tabs, and `CanvasSurface` are not implemented.
+
+- [ ] **Step 3: Restore the canvas tab model and editor surface integration**
+
+Recreate or adapt the old implementation from commit `277fe754`:
+
+- update `packages/web/src/features/workspace/atoms/files.ts`
+  - restore `WorkspaceCanvasEditorTab`
+  - restore `canvasRefreshTokenAtomFamily`
+  - extend `normalizeWorkspaceEditorTabs()` for canvas tabs
+- update `packages/web/src/features/ui-actions/use-ui-action-subscription.ts`
+  - register `canvas.open`
+- create `packages/web/src/features/code-editor/views/shared/canvas-surface.tsx`
+- update `packages/web/src/features/code-editor/views/shared/editor-surface.tsx`
+  - render `CanvasSurface`
+  - include canvas tabs in `visibleEditorTabs`
+  - allow activate/close on canvas tabs
+- update `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx`
+  - display and activate canvas tabs
+
+Keep the old `CanvasSurface` behavior:
+
+- iframe `src` is `/embedded/canvas/<workspaceId>/<canvasId>?refresh=<token>`
+- toolbar buttons:
+  - `Open source`
+  - `Refresh`
+
+- [ ] **Step 4: Re-run the focused web tests and verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/web exec vitest run src/features/ui-actions/use-ui-action-subscription.test.tsx src/features/code-editor/views/shared/editor-surface.test.tsx src/features/code-editor/views/shared/canvas-surface.test.tsx
+```
+
+Expected: PASS with canvas tabs, `canvas.open`, and `CanvasSurface` restored.
+
+- [ ] **Step 5: Commit Task 5**
+
+Run:
+
+```bash
+git add packages/web/src/features/workspace/atoms/files.ts packages/web/src/features/ui-actions/use-ui-action-subscription.ts packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx packages/web/src/features/code-editor/views/shared/editor-surface.tsx packages/web/src/features/code-editor/views/shared/editor-surface.test.tsx packages/web/src/features/code-editor/views/shared/canvas-surface.tsx packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx
+git commit -m "feat(web): restore canvas editor tabs"
+```
+
+### Task 6: Restore The CLI Canvas Command Family
+
+**Files:**
+- Modify: `packages/cli/src/parse-args.ts`
+- Modify: `packages/cli/src/cli.ts`
+- Modify: `packages/cli/src/bin.test.ts`
+
+- [ ] **Step 1: Add the failing CLI tests**
+
+Extend `packages/cli/src/bin.test.ts` with parser and command wiring tests for:
+
+- `coder-studio canvas list --workspace ws_123 --json`
+- `coder-studio canvas create --workspace ws_123 --kind architecture_canvas --title "Runtime Flow" --document-json '{...}' --open --json`
+- `coder-studio canvas update --workspace ws_123 --canvas canvas_123 --document-json '{...}' --json`
+- `coder-studio canvas render --workspace ws_123 --canvas canvas_123 --json`
+
+Use expectations like:
+
+```ts
+expect(parseArgs(["canvas", "list", "--workspace", "ws_123", "--json"])).toMatchObject({
+  command: "canvas",
+  canvasCommand: "list",
+  workspaceId: "ws_123",
+  json: true,
+});
+
+await main([
+  "canvas",
+  "render",
+  "--workspace",
+  "ws_123",
+  "--canvas",
+  "canvas_123",
+  "--json",
+]);
+
+expect(callCoderStudioCommand).toHaveBeenCalledWith(
+  expect.objectContaining({
+    op: "canvas.render",
+    args: {
+      workspaceId: "ws_123",
+      canvasId: "canvas_123",
+    },
+  }),
+  expect.anything()
+);
+```
+
+- [ ] **Step 2: Run the CLI test and verify it fails**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio exec vitest run src/bin.test.ts
+```
+
+Expected: FAIL because the parser and CLI do not know the `canvas` command family.
+
+- [ ] **Step 3: Restore the parser and CLI wiring for canvas commands**
+
+Reapply the old CLI support from commit `277fe754`:
+
+- update `packages/cli/src/parse-args.ts`
+  - add command `canvas`
+  - add subcommands `list | create | update | render`
+  - add args for `--workspace`, `--canvas`, `--kind`, `--title`, `--document-json`, `--open`
+- update `packages/cli/src/cli.ts`
+  - show `canvas` in help output
+  - dispatch `canvas.list/create/update/render` through `callCoderStudioCommand()`
+
+Keep the CLI as a thin transport layer only.
+
+- [ ] **Step 4: Re-run the CLI test and verify it passes**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio exec vitest run src/bin.test.ts
+```
+
+Expected: PASS with the restored parser and automation calls.
+
+- [ ] **Step 5: Commit Task 6**
+
+Run:
+
+```bash
+git add packages/cli/src/parse-args.ts packages/cli/src/cli.ts packages/cli/src/bin.test.ts
+git commit -m "feat(cli): restore canvas commands"
+```
+
+### Task 7: Run Cross-Package Verification And Audit The Acceptance Criteria
+
+**Files:**
+- Modify: nothing expected unless verification reveals a defect
+
+- [ ] **Step 1: Run focused package tests for the restored feature**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/core exec vitest run src/domain/canvas.test.ts
+pnpm --filter @coder-studio/server exec vitest run src/storage/repositories/canvas-repo.test.ts src/canvas/validation.test.ts src/canvas/compiler.test.ts src/canvas/graph-v1.test.ts src/canvas/mermaid-flowchart.test.ts src/canvas/service.test.ts src/routes/canvas.test.ts src/app-routing.test.ts
+pnpm --filter @coder-studio/web exec vitest run src/app.test.tsx src/features/canvas/routes/embedded-canvas-route.test.tsx src/features/ui-actions/use-ui-action-subscription.test.tsx src/features/code-editor/views/shared/editor-surface.test.tsx src/features/code-editor/views/shared/canvas-surface.test.tsx
+pnpm --filter @spencer-kit/coder-studio exec vitest run src/bin.test.ts
+```
+
+Expected: PASS across all focused tests.
+
+- [ ] **Step 2: Run repository-level verification required by the workspace instructions**
+
+Run:
+
+```bash
+pnpm ci:test
+pnpm ci:verify
+```
+
+Expected: PASS. If `pnpm ci:verify` is too slow or fails outside the restore scope, record the exact failure and whether it is pre-existing or introduced by the canvas work.
+
+- [ ] **Step 3: Audit the spec acceptance criteria against the finished code**
+
+Manually verify these points against the diff and test evidence:
+
+- `.coder-studio/canvases/*.canvas.json` is written by `canvas.create`
+- `canvas.open` opens a canvas tab
+- `/embedded/canvas/:workspaceId/:canvasId` renders
+- `/api/canvas/:workspaceId/:canvasId/data` serves JSON
+- both `architecture_canvas` and `report_canvas` render
+- `Open source` works
+- `Refresh` works
+
+Expected: every item maps to code plus a passing test.
+
+- [ ] **Step 4: Commit any verification-only fixes**
+
+If verification revealed defects and you fixed them, commit them with the narrowest accurate message, for example:
+
+```bash
+git add <fixed-files>
+git commit -m "fix(canvas): correct refresh token reload behavior"
+```
+
+If no fixes were needed, skip this step.
+
+- [ ] **Step 5: Prepare handoff summary**
+
+Report:
+
+- changed files grouped by core/server/web/cli
+- verification commands run
+- pass/fail results
+- any remaining risk, skipped coverage, or assumptions
+
+## Self-Review
+
+Plan coverage against the spec:
+
+- core contracts are restored in Task 1
+- server repository, validation, compiler, service, commands, route, and app wiring are restored in Tasks 2 and 3
+- frontend embedded route, renderers, canvas tab, and UI action integration are restored in Tasks 4 and 5
+- CLI support is restored in Task 6
+- repository verification and acceptance audit are covered in Task 7
+
+Placeholder scan:
+
+- every task names the exact files
+- every test step names the exact command
+- every verification step states the expected failure or pass condition
+
+Type consistency:
+
+- `WorkspaceCanvasEditorTab`, `canvas.open`, `CanvasService`, `registerCanvasRoutes`, and `canvasRefreshTokenAtomFamily` use the same names across tasks
+- `architecture_canvas` and `report_canvas` remain the only artifact kinds throughout the plan
+
+## Execution Handoff
+
+Plan complete and saved to `docs/superpowers/plans/2026-06-21-canvas-restore.md`. Two execution options:
+
+**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
+
+**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
+
+**Which approach?**
diff --git a/docs/superpowers/plans/2026-06-21-runtime-extraction-and-wsl-architecture.md b/docs/superpowers/plans/2026-06-21-runtime-extraction-and-wsl-architecture.md
new file mode 100644
index 000000000..8681b7c0a
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-21-runtime-extraction-and-wsl-architecture.md
@@ -0,0 +1,629 @@
+# Runtime Extraction And WSL Architecture Spec
+
+**Goal:** Restructure the current server so Coder Studio can support per-workspace runtimes, with native Windows workspaces and WSL workspaces coexisting in the same app instance. Phase 1 extracts `runtime` from the current monolithic `server`. Phase 2 adds a WSL-backed runtime implementation on top of the extracted boundary.
+
+**Status:** Approved architecture spec for development handoff.
+
+**Primary outcome of this spec:** Change the backend shape from:
+
+```text
+UI -> server(transport + host logic + runtime logic)
+```
+
+to:
+
+```text
+UI -> Host Server
+     -> Host Services
+     -> Runtime Router
+        -> Native Runtime
+        -> WSL Runtime
+```
+
+## Why This Exists
+
+The current backend in [packages/server/src/server.ts](/root/workspace/coder-studio/packages/server/src/server.ts:129) assembles HTTP/WebSocket transport, workspace metadata, runtime execution, skills, provider installs, LSP, session orchestration, and monitoring into a single process-wide object graph.
+
+That shape is workable for local-only workspaces, but it blocks a correct WSL mode because:
+
+- a WSL workspace must execute `terminal`, `git`, `session`, `provider`, `skills`, `lsp`, and agent-facing files inside WSL, not on Windows
+- mixed mode is required: Windows and WSL workspaces must be open at the same time
+- `skills` cannot remain Windows-owned for WSL workspaces because provider skill mount directories are runtime-local, for example:
+  - Codex: [packages/providers/src/codex/definition.ts](/root/workspace/coder-studio/packages/providers/src/codex/definition.ts:85)
+  - Claude: [packages/providers/src/claude/definition.ts](/root/workspace/coder-studio/packages/providers/src/claude/definition.ts:85)
+  - Gemini: [packages/providers/src/gemini/definition.ts](/root/workspace/coder-studio/packages/providers/src/gemini/definition.ts:73)
+- the current global [CommandContext](/root/workspace/coder-studio/packages/server/src/ws/dispatch.ts:50) couples host and runtime concerns into one dependency bag
+
+## Product And Architecture Decisions
+
+These decisions are fixed for implementation unless a later spec explicitly revises them.
+
+1. WSL is a per-workspace runtime, not a global app mode.
+2. Mixed mode is required. One app instance may host native and WSL workspaces simultaneously.
+3. Phase 1 does not implement WSL execution. It only extracts the runtime boundary cleanly enough that WSL becomes an additional runtime implementation, not a rewrite.
+4. `skills` belong to the runtime, not to the host, because the agent and provider skill directories live in the runtime environment.
+5. `memory` remains host-owned in Phase 1.
+6. Agent CLI callbacks keep using the host control plane. The CLI entry stays stable; only backend routing changes.
+7. Host is the control plane. Runtime is the execution plane.
+8. Host remains the only browser-facing HTTP/WebSocket server.
+
+## Non-Goals
+
+This spec does not include:
+
+- implementing the WSL transport itself
+- rewriting all command handlers at once
+- changing frontend interaction flows
+- moving `memory` into runtime in Phase 1
+- changing the public CLI command surface
+- introducing browser-to-WSL direct connections
+
+## Current Relevant Code
+
+### Main coupling points
+
+- Monolithic assembly: [packages/server/src/server.ts](/root/workspace/coder-studio/packages/server/src/server.ts:129)
+- Global dispatch and dependency bag: [packages/server/src/ws/dispatch.ts](/root/workspace/coder-studio/packages/server/src/ws/dispatch.ts:1)
+- Browser WebSocket hub: [packages/server/src/ws/hub.ts](/root/workspace/coder-studio/packages/server/src/ws/hub.ts:1)
+- All command registration imported globally: [packages/server/src/commands/index.ts](/root/workspace/coder-studio/packages/server/src/commands/index.ts:1)
+
+### Workspace metadata already prepared for WSL
+
+- `Workspace.targetRuntime` and `Workspace.wslDistro`: [packages/core/src/domain/types.ts](/root/workspace/coder-studio/packages/core/src/domain/types.ts:12)
+- `WorkspaceManager.open()` currently still hardcodes `"native"`: [packages/server/src/workspace/manager.ts](/root/workspace/coder-studio/packages/server/src/workspace/manager.ts:143)
+
+### Existing agent callback path
+
+- Session injects `CODER_STUDIO_SESSION_TOKEN` and `CODER_STUDIO_API_URL`: [packages/server/src/session/manager.ts](/root/workspace/coder-studio/packages/server/src/session/manager.ts:290)
+- CLI callback client uses those env vars over WebSocket: [packages/cli/src/automation-command-client.ts](/root/workspace/coder-studio/packages/cli/src/automation-command-client.ts:73)
+- Host auth supports bearer session tokens on `/ws`: [packages/server/src/auth/plugin.ts](/root/workspace/coder-studio/packages/server/src/auth/plugin.ts:119)
+
+## Target Architecture
+
+### Layered shape
+
+```text
+Browser UI
+  -> Host Server
+     - Fastify routes
+     - WebSocket hub
+     - Auth/session-token checks
+     - Workspace metadata and UI state
+     - Host-only commands
+     - Runtime router
+
+  -> Runtime Handle per workspace
+     - Native Runtime (Phase 1 implementation)
+     - WSL Runtime (Phase 2 implementation)
+```
+
+### Host responsibilities
+
+Host owns:
+
+- HTTP routes and WebSocket endpoint
+- auth and session token validation
+- browser event fan-out
+- workspace metadata persistence
+- workspace open/close orchestration
+- runtime selection and runtime handle binding
+- host-only settings/state
+- automation audit and activation/fencing policy
+- command routing
+
+### Runtime responsibilities
+
+Runtime owns:
+
+- provider CLI execution
+- sessions and terminals
+- git and worktrees
+- LSP
+- diagnostics that depend on runtime environment
+- system dependency installs
+- provider installs
+- skills library/install/mount/health
+- agent instructions generation and publication
+- workspace intelligence
+- session analysis and work analysis
+- supervisor execution
+
+## Scope Split
+
+All commands must be explicitly classified as:
+
+- `host`
+- `runtime`
+- `host-orchestrated`
+
+### Host commands in Phase 1
+
+Keep these on host:
+
+- `automation.*`
+- `connection.probe`
+- `activation.*`
+- `workspace.list`
+- `workspace.browse`
+- `workspace.mkdir`
+- `workspace.close`
+- `workspace.uiState.set`
+- `workspace.activate`
+- `workspace.deactivate`
+- `workspace.lastViewedTarget.*`
+- `workspace.history.*`
+- `settings.*`
+- `updates.*`
+- `monitoring.*`
+- `memory.*`
+- `customProvider.*`
+- `uiAction.*`
+
+Reason:
+
+- they are control-plane concerns
+- or they operate on host-owned persistent app state
+- or they drive browser behavior directly
+
+### Runtime commands in Phase 1
+
+Move these behind the runtime boundary:
+
+- `file.*`
+- `git.*`
+- `worktree.*`
+- `terminal.*`
+- `task.*`
+- `session.*`
+- `lsp.*`
+- `provider.runtimeStatus`
+- `provider.install.*`
+- `systemDeps.*`
+- `diagnostics.*`
+- `workspace.intelligence`
+- `agent-context.*`
+- `agent-instructions.*`
+- `session.analysis.*`
+- `session.review.*`
+- `work.analysis.*`
+- `supervisor.*`
+- `fencing.*`
+- `skills.*`
+
+Reason:
+
+- these commands read or mutate runtime-local filesystem state
+- or they execute local commands/processes
+- or they depend on runtime-local home directories and tool installs
+
+### Host-orchestrated commands
+
+These remain host entrypoints but coordinate runtime work:
+
+- `workspace.open`
+- `session.close`
+
+Future commands of the same shape should follow this pattern rather than forcing everything into pure host or pure runtime.
+
+## Context Split
+
+The current [CommandContext](/root/workspace/coder-studio/packages/server/src/ws/dispatch.ts:50) must be replaced with two separate contexts.
+
+### HostCommandContext
+
+`HostCommandContext` should include:
+
+- `workspaceMgr`
+- `settingsRepo`
+- `memoryRepo`
+- `activationMgr`
+- `automationAuditLog`
+- `broadcaster`
+- `runtimeRouter`
+- `config`
+- `updateService`
+- `monitoringService`
+- `customProviderRepo`
+
+### RuntimeCommandContext
+
+`RuntimeCommandContext` should include:
+
+- `workspaceLookup`
+- `eventBus`
+- `providerConfigRepo`
+- `providerRegistry`
+- `sessionMgr`
+- `terminalMgr`
+- `taskMgr`
+- `lspMgr`
+- `lspToolMgr`
+- `lspToolInstallMgr`
+- `fencingMgr`
+- `supervisorMgr`
+- `providerRuntimeDeps`
+- `providerInstallMgr`
+- `systemDependencyInstallMgr`
+- `skillsHubClient`
+- `skillInstallMgr`
+- `skillMountMgr`
+- `skillHealthMgr`
+- `skillLibraryRepo`
+- `skillTargetRepo`
+- `skillMountRepo`
+- `builtinSkillSyncMgr`
+- `sessionMetadataRepo`
+- `sessionAnalysisService`
+- `workAnalysisService`
+- `agentInstructionPublisher`
+
+## Runtime Contract
+
+Phase 1 should introduce a runtime contract before adding any remote transport.
+
+```ts
+export interface RuntimeExecuteMeta {
+  clientId?: string;
+  authContext?: unknown;
+}
+
+export interface RuntimeHandle {
+  kind: "native" | "wsl";
+  execute(op: string, args: unknown, meta?: RuntimeExecuteMeta): Promise<unknown>;
+  disposeWorkspace(workspaceId: string): Promise<void>;
+  setProviderRegistry?(providers: ProviderDefinition[]): void;
+  getSummary?(): RuntimeSummary;
+  health(): Promise<{ ok: true }>;
+}
+```
+
+Phase 1 only implements `NativeRuntimeHandle` in-process. Phase 2 adds `WslRuntimeHandle`.
+
+## Host/Runtime Bridge Requirements
+
+Even for in-process runtime, the code should depend on a host bridge abstraction rather than host internals.
+
+### Required host bridge capabilities
+
+- issue session automation tokens
+- revoke session automation tokens by session id
+- provide host callback API URL
+- emit domain events back to host
+- broadcast stream/topic events back to host
+
+Suggested interface:
+
+```ts
+interface RuntimeHostBridge {
+  issueSessionToken(input: IssueSessionAutomationTokenInput): SessionAutomationTokenRecord;
+  revokeSessionTokensBySessionId(sessionId: string): void;
+  getHostApiUrl(): string | undefined;
+  emitDomainEvent(event: DomainEvent): void;
+  broadcast(topic: string, payload: unknown): void;
+}
+```
+
+This is required because:
+
+- [SessionManager](/root/workspace/coder-studio/packages/server/src/session/manager.ts:296) currently touches `SessionTokenRepo` directly
+- runtime services currently assume direct access to host `eventBus` and `broadcaster`
+
+Those assumptions must be removed in Phase 1.
+
+## Runtime State Ownership
+
+The following runtime state must move under runtime-owned state roots:
+
+- `TerminalRepo`
+- `SessionRepo`
+- `SkillLibraryRepo`
+- `SkillTargetRepo`
+- `SkillMountRepo`
+- `SessionMetadataRepo`
+- `SessionAnalysisRepo`
+- `WorkAnalysisRepo`
+- `SupervisorRepo`
+
+Current creation sites are in [packages/server/src/server.ts](/root/workspace/coder-studio/packages/server/src/server.ts:154) through [packages/server/src/server.ts](/root/workspace/coder-studio/packages/server/src/server.ts:458).
+
+### Host-owned state that remains on host in Phase 1
+
+- `WorkspaceRepo`
+- `SettingsRepo`
+- `MemoryRepo`
+- `AuthSessionRepo`
+- `AuthLoginBlockRepo`
+- `AppearanceAssetRepo`
+- `AutomationAuditLog`
+- `CustomProviderRepo`
+
+### Runtime state root layout
+
+Phase 1 should stop treating all runtime state as process-global.
+
+Recommended structure:
+
+```text
+state/
+  host/
+    workspaces.json
+    settings.json
+    memory/
+    auth-sessions.json
+    auth-login-blocks.json
+    appearance-assets.json
+    automation-audit.jsonl
+    update-state.json
+
+  runtimes/
+    native-default/
+      sessions.json
+      terminals.json
+      skills/
+      lsp/
+      session-analysis.json
+      work-analysis.sqlite
+      supervisor/
+```
+
+This avoids a second storage migration when WSL runtimes are introduced.
+
+## Command Registration Model
+
+The current global registration pattern in [packages/server/src/commands/index.ts](/root/workspace/coder-studio/packages/server/src/commands/index.ts:1) should be replaced by separate registries.
+
+### Required registries
+
+- `registerHostCommand(op, schema, handler)`
+- `registerRuntimeCommand(op, schema, handler)`
+
+The dispatch layer should:
+
+1. validate auth and permissions on host
+2. validate input on host
+3. route by command scope
+4. execute locally for host commands
+5. forward to runtime for runtime commands
+
+## Workspace Lifecycle Changes
+
+### `workspace.open`
+
+The current [workspace.open](/root/workspace/coder-studio/packages/server/src/commands/workspace.ts:123) calls `workspaceMgr.open({ path })` directly. This must become host orchestration.
+
+Target flow:
+
+1. resolve target runtime for the requested path
+2. ensure a runtime handle exists
+3. persist workspace metadata with explicit `targetRuntime`
+4. bind `workspaceId -> runtimeHandle`
+5. perform optional runtime warmup
+
+### `WorkspaceManager.open()`
+
+[WorkspaceManager.open()](/root/workspace/coder-studio/packages/server/src/workspace/manager.ts:119) must stop hardcoding:
+
+```ts
+targetRuntime: "native"
+```
+
+It should accept explicit runtime metadata from the caller.
+
+### `workspace.close`
+
+[WorkspaceManager.close()](/root/workspace/coder-studio/packages/server/src/workspace/manager.ts:183) currently depends on teardown logic that knows about runtime internals.
+
+Target flow:
+
+1. stop host watcher
+2. call `runtimeHandle.disposeWorkspace(workspaceId)`
+3. clean host-owned workspace state such as memory and uploads
+4. remove workspace metadata
+5. unbind workspace/runtime relation
+
+## Agent CLI And Host Callback Model
+
+The current agent callback model is preserved:
+
+- runtime launches agent process
+- runtime injects `CODER_STUDIO_SESSION_TOKEN`
+- runtime injects `CODER_STUDIO_API_URL`
+- agent CLI calls host control plane over WebSocket
+
+This remains the correct model after extraction. The CLI entry does not change.
+
+### Important implication for WSL
+
+Phase 2 must change host callback assumptions:
+
+- callback URL must be reachable from WSL, not just `127.0.0.1`
+- session token auth cannot remain strictly loopback-only for remote runtimes
+
+Current loopback restriction lives in [packages/server/src/auth/plugin.ts](/root/workspace/coder-studio/packages/server/src/auth/plugin.ts:110).
+
+## Why `skills` Must Be Runtime-Owned
+
+`skills` must not remain host-owned for WSL workspaces because:
+
+- provider skill mount targets are runtime-local home directories
+- skill install/mount/health operations are meaningful only relative to the actual runtime where the agent executes
+- duplicating skill state on host and syncing it into WSL would create two sources of truth
+
+Therefore:
+
+- `skills.search/info/install/library/files/mount/health/recommend/custom/builtin` all belong to runtime
+- host may aggregate and relay runtime state
+- host must not remain the source of truth for skill installation or mount state
+
+## Runtime-Specific Gaps Already Visible In Current Code
+
+These do not all need full implementation in Phase 1, but the architecture must stop deepening the current coupling.
+
+### File watchers
+
+[WorkspaceManager](/root/workspace/coder-studio/packages/server/src/workspace/manager.ts:70) currently owns host-side filesystem watchers. For WSL workspaces, watchers must come from runtime, not host.
+
+### File asset routes
+
+- `/api/file` currently assumes host-local workspace access: [packages/server/src/app.ts](/root/workspace/coder-studio/packages/server/src/app.ts:144)
+- `/api/skill-file` currently assumes host-local skill library access: [packages/server/src/app.ts](/root/workspace/coder-studio/packages/server/src/app.ts:148)
+
+Phase 2 will need runtime-backed proxying for these routes.
+
+### Auto-fetch
+
+`AutoFetchScheduler` currently dispatches `git.fetch` against the process-global dispatcher: [packages/server/src/server.ts](/root/workspace/coder-studio/packages/server/src/server.ts:179)
+
+After extraction it must use the runtime router rather than assuming a single local execution environment.
+
+## File And Module Structure
+
+Phase 1 should add these files:
+
+- `packages/server/src/host/context.ts`
+- `packages/server/src/host/command-registry.ts`
+- `packages/server/src/host/runtime-router.ts`
+- `packages/server/src/host/runtime-registry.ts`
+- `packages/server/src/host/workspace-runtime-binding.ts`
+- `packages/server/src/runtime/contract.ts`
+- `packages/server/src/runtime/context.ts`
+- `packages/server/src/runtime/command-registry.ts`
+- `packages/server/src/runtime/assembly.ts`
+- `packages/server/src/runtime/native-runtime.ts`
+- `packages/server/src/runtime/runtime-state.ts`
+- `packages/server/src/runtime/events.ts`
+- `packages/server/src/runtime/remote/transport.ts`
+
+The existing business directories stay in place initially:
+
+- `session/`
+- `skills/`
+- `terminal/`
+- `lsp/`
+- `provider-runtime/`
+- `system-deps/`
+- `agent-instructions/`
+- `supervisor/`
+- `work-analysis/`
+
+The first refactor is registration and assembly, not a large physical move of implementation files.
+
+## Phase Plan
+
+## Phase 1: Runtime Extraction
+
+### Deliverables
+
+- host/runtime context split
+- host/runtime command registry split
+- in-process native runtime handle
+- runtime router
+- workspace/runtime binding
+- runtime-owned session/terminal/lsp/skills/provider/system-deps execution
+- host-owned settings/memory/update/monitoring/auth/workspace metadata
+
+### Required implementation steps
+
+1. Add runtime contract and host/runtime contexts
+2. Add host and runtime command registries
+3. Introduce `NativeRuntimeHandle`
+4. Move runtime assembly out of `server.ts`
+5. Change dispatch to route by scope
+6. Change workspace open/close to bind and dispose runtime handles
+7. Migrate runtime command groups in batches
+
+### Migration order for commands
+
+#### Batch 1
+
+- `file.*`
+- `git.*`
+- `terminal.*`
+- `session.*`
+- `task.*`
+- `lsp.*`
+
+#### Batch 2
+
+- `provider.runtimeStatus`
+- `provider.install.*`
+- `systemDeps.*`
+- `diagnostics.*`
+- `worktree.*`
+- `workspace.intelligence`
+- `agent-context.*`
+
+#### Batch 3
+
+- `skills.*`
+- `agent-instructions.*`
+- `supervisor.*`
+- `session.analysis.*`
+- `session.review.*`
+- `work.analysis.*`
+- `fencing.*`
+
+## Phase 2: WSL Runtime
+
+### Deliverables
+
+- WSL runtime installer/bootstrap
+- runtime process launch via Windows host
+- host <-> WSL runtime RPC transport
+- runtime-local state inside WSL
+- WSL-capable host callback URL and remote-runtime auth mode
+
+### Transport choice
+
+Recommended first implementation:
+
+- host starts WSL child process
+- host and WSL runtime communicate over stdio JSON-RPC
+
+Reason:
+
+- the host can create the runtime before any remote HTTP server exists
+- transport stays thin
+- it maps well onto existing process-launch patterns
+
+## Risks
+
+### Risk 1: Context split leaks old assumptions
+
+If handlers continue expecting the old global `CommandContext`, the extraction becomes mechanical but not real. Avoid adapter layers that simply pass the old context through unchanged.
+
+### Risk 2: Global state remains in `server.ts`
+
+If `server.ts` continues owning runtime repos/managers directly, the project will gain new abstractions without changing actual dependency flow.
+
+### Risk 3: Skills become dual-sourced
+
+If host keeps owning skill state while runtime also grows skill state, mixed mode becomes inconsistent. Runtime must be the source of truth for skills.
+
+### Risk 4: Workspace routing ambiguity
+
+Runtime commands without a clear `workspaceId` cannot be routed in mixed mode. Any command that is runtime-owned must carry enough information for workspace routing.
+
+### Risk 5: Route-level host filesystem assumptions remain hidden
+
+HTTP asset and watcher features can silently break on WSL if they are not called out explicitly in follow-up work.
+
+## Verification Criteria For Phase 1
+
+Phase 1 is complete when all of the following are true:
+
+1. `server.ts` no longer directly assembles runtime business managers such as session, terminal, skills, LSP, supervisor, and provider/system dependency installers.
+2. `dispatch.ts` no longer executes all commands against a single `CommandContext`.
+3. Runtime-owned commands execute through a `RuntimeHandle`, even when that runtime is still in-process.
+4. `workspace.open` persists explicit runtime metadata and binds the workspace to a runtime handle.
+5. `skills.*` no longer depend on host-owned source-of-truth state.
+6. Existing native workspace behavior remains functionally unchanged.
+
+## Implementation Notes For Developers
+
+- Prefer moving assembly and registration before moving implementation files.
+- Do not start with WSL transport.
+- Keep the CLI surface unchanged.
+- Keep auth, browser WebSocket fan-out, and workspace metadata firmly host-owned.
+- Avoid backsliding into host-side direct access to runtime managers after the first extraction lands.
+
diff --git a/docs/superpowers/plans/2026-06-21-runtime-extraction-phase1-implementation.md b/docs/superpowers/plans/2026-06-21-runtime-extraction-phase1-implementation.md
new file mode 100644
index 000000000..569d86586
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-21-runtime-extraction-phase1-implementation.md
@@ -0,0 +1,1887 @@
+# Runtime Extraction Phase 1 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Extract the current in-process runtime out of the monolithic server so every runtime-owned command executes through a `RuntimeHandle`, while native behavior remains unchanged and WSL transport can be added later without another architectural rewrite.
+
+**Architecture:** Keep the browser-facing Fastify/WebSocket server as the host control plane, then move execution concerns behind a runtime boundary made of split command registries, split contexts, a host runtime router, and an in-process `NativeRuntimeHandle`. Host-owned state stays in `state/host`; runtime-owned services and state move behind `runtime/assembly.ts`, and host-side projections replace direct reads from runtime managers in places like `WsHub`, auth scope checks, monitoring, and update gating.
+
+**Tech Stack:** TypeScript, Fastify, WebSocket command dispatch, Vitest, existing repositories/managers in `packages/server`, shared domain types in `@coder-studio/core`.
+
+**Spec reference:** `docs/superpowers/plans/2026-06-21-runtime-extraction-and-wsl-architecture.md`
+
+**Git hygiene:** The repo already contains untracked plan/spec files. Read files before patching, stage only the files for the current task, and never revert unrelated user changes.
+
+---
+
+## File Structure
+
+**New files:**
+- `packages/server/src/host/context.ts` — host-only command context and WebSocket-facing dispatch context
+- `packages/server/src/host/command-registry.ts` — host command registry and host command definition types
+- `packages/server/src/host/runtime-router.ts` — runtime selection, route resolution, default-runtime fallback, and runtime execution entrypoint
+- `packages/server/src/host/runtime-registry.ts` — named runtime handle registry and provider-registry fan-out
+- `packages/server/src/host/workspace-runtime-binding.ts` — workspace/session/terminal/runtime binding index plus host-side projections
+- `packages/server/src/runtime/contract.ts` — `RuntimeHandle`, `RuntimeExecuteMeta`, route-target types, and host bridge contract
+- `packages/server/src/runtime/context.ts` — runtime command context and runtime command handler types
+- `packages/server/src/runtime/command-registry.ts` — runtime command registry and route resolver metadata
+- `packages/server/src/runtime/assembly.ts` — extracted runtime assembly from `server.ts`
+- `packages/server/src/runtime/native-runtime.ts` — in-process `NativeRuntimeHandle`
+- `packages/server/src/runtime/runtime-state.ts` — runtime state-root helpers for `state/runtimes/<runtimeId>`
+- `packages/server/src/runtime/events.ts` — host bridge adapters that forward runtime domain events and topic messages back to host services
+- `packages/server/src/__tests__/host-command-registry.test.ts` — host registry coverage
+- `packages/server/src/__tests__/runtime-command-registry.test.ts` — runtime registry and route-target coverage
+- `packages/server/src/__tests__/runtime-router.test.ts` — workspace/session/terminal/default route resolution coverage
+- `packages/server/src/__tests__/runtime/native-runtime.test.ts` — native runtime execution and host bridge coverage
+- `packages/server/src/__tests__/workspace-runtime-binding.test.ts` — host-side runtime binding/projection coverage
+
+**Modified files:**
+- `packages/server/src/server.ts` — host/runtime bootstrap split, runtime router wiring, host bridge creation, and test surface updates
+- `packages/server/src/ws/dispatch.ts` — host/runtime routing, auth checks, and legacy `registerCommand` removal
+- `packages/server/src/ws/index.ts` — export new host/runtime registration APIs
+- `packages/server/src/ws/hub.ts` — resync and command dispatch driven by host projections instead of direct runtime manager access
+- `packages/server/src/workspace/manager.ts` — explicit runtime metadata on open and runtime-aware close orchestration
+- `packages/server/src/commands/index.ts` — explicit host/runtime registration bootstrap
+- `packages/server/src/commands/workspace.ts` — `workspace.open` / `workspace.close` host orchestration, `workspace.intelligence` runtime routing
+- `packages/server/src/commands/session.ts` — runtime registration for session commands and host-orchestrated `session.close`
+- `packages/server/src/commands/terminal.ts` — runtime registration and terminal-id route selectors
+- `packages/server/src/commands/file.ts`
+- `packages/server/src/commands/git.ts`
+- `packages/server/src/commands/recovery.ts`
+- `packages/server/src/commands/task.ts`
+- `packages/server/src/commands/lsp.ts`
+- `packages/server/src/commands/worktree.ts`
+- `packages/server/src/commands/provider.ts` — split host/runtime provider operations plus internal runtime config bridge ops
+- `packages/server/src/commands/system-deps.ts` — runtime-global registration with owner/client propagation
+- `packages/server/src/commands/settings.ts` — host-owned settings plus runtime-backed provider config and preview bridge
+- `packages/server/src/commands/diagnostics.ts` — host-orchestrated aggregation over runtime status helpers
+- `packages/server/src/commands/custom-provider.ts` — host-owned provider definition changes plus runtime registry fan-out
+- `packages/server/src/commands/agent-context.ts`
+- `packages/server/src/commands/agent-instructions.ts`
+- `packages/server/src/commands/skills.ts`
+- `packages/server/src/commands/skills/*.ts`
+- `packages/server/src/commands/supervisor.ts`
+- `packages/server/src/commands/session-metadata.ts`
+- `packages/server/src/commands/session-review.ts`
+- `packages/server/src/commands/work-analysis.ts`
+- `packages/server/src/commands/fencing.ts` — stay host-only, update imports to host registry
+- `packages/server/src/commands/automation.ts`
+- `packages/server/src/commands/activation.ts`
+- `packages/server/src/commands/connection.ts`
+- `packages/server/src/commands/memory.ts`
+- `packages/server/src/commands/monitoring.ts`
+- `packages/server/src/commands/updates.ts`
+- `packages/server/src/commands/ui-actions.ts`
+- `packages/server/src/commands/workspace-activity.ts`
+- `packages/server/src/session/manager.ts` — replace direct host token/runtime URL assumptions with host bridge capabilities
+- `packages/server/src/system-deps/install-manager.ts` — bridge-backed client routing instead of raw `WsHub` dependency
+- `packages/server/src/supervisor/manager.ts` — bridge-backed topic broadcast
+- `packages/server/src/monitoring/service.ts` — runtime projections instead of direct session/terminal managers
+- `packages/server/src/storage/repositories/session-metadata-repo.ts` — runtime-local workspace lookup instead of direct `WorkspaceRepo` coupling
+- `packages/server/src/__tests__/dispatch.test.ts`
+- `packages/server/src/__tests__/workspace/manager.test.ts`
+- `packages/server/src/__tests__/workspace/manager-on-close.test.ts`
+- `packages/server/src/__tests__/workspace-commands.test.ts`
+- `packages/server/src/__tests__/session-commands.test.ts`
+- `packages/server/src/__tests__/terminal-commands.test.ts`
+- `packages/server/src/__tests__/file-commands.test.ts`
+- `packages/server/src/__tests__/git-commands.test.ts`
+- `packages/server/src/__tests__/task-commands.test.ts`
+- `packages/server/src/__tests__/lsp-commands.test.ts`
+- `packages/server/src/__tests__/worktree-commands.test.ts`
+- `packages/server/src/__tests__/provider-runtime/runtime-status.test.ts`
+- `packages/server/src/__tests__/provider-runtime/install-manager.test.ts`
+- `packages/server/src/__tests__/system-deps/commands.test.ts`
+- `packages/server/src/commands/settings.test.ts`
+- `packages/server/src/__tests__/diagnostics-commands.test.ts`
+- `packages/server/src/__tests__/skills/commands.test.ts`
+- `packages/server/src/__tests__/server-builtin-skills-wiring.test.ts`
+- `packages/server/src/__tests__/server-memory-wiring.test.ts`
+- `packages/server/src/__tests__/server-provider-install-wiring.test.ts`
+- `packages/server/src/__tests__/server-lsp-runtime-mode-hydration.test.ts`
+- `packages/server/src/__tests__/server-runtime-config.test.ts`
+- `packages/server/src/__tests__/ws-hub.test.ts`
+- `packages/server/src/__tests__/monitoring/service.test.ts`
+
+**Compatibility note for Phase 1:** runtime-global commands that currently have no `workspaceId` in the web protocol (`provider.runtimeStatus`, `provider.install.*`, `systemDeps.*`, most `skills.*`, and runtime-backed provider config helpers behind `settings.*`) will resolve to the `native-default` runtime through `RuntimeRouteTarget { kind: "default" }`. This preserves current UI payloads now. WSL follow-up work will thread explicit runtime/workspace targeting through those flows before mixed native/WSL execution ships.
+
+**Testing commands used in this plan:**
+- `pnpm --filter @coder-studio/server exec vitest run src/__tests__/host-command-registry.test.ts src/__tests__/runtime-command-registry.test.ts src/__tests__/runtime-router.test.ts src/__tests__/workspace-runtime-binding.test.ts`
+- `pnpm --filter @coder-studio/server exec vitest run src/__tests__/workspace/manager.test.ts src/__tests__/workspace/manager-on-close.test.ts src/__tests__/workspace-commands.test.ts`
+- `pnpm --filter @coder-studio/server exec vitest run src/__tests__/runtime/native-runtime.test.ts src/__tests__/server-builtin-skills-wiring.test.ts src/__tests__/server-lsp-runtime-mode-hydration.test.ts src/__tests__/server-runtime-config.test.ts`
+- `pnpm --filter @coder-studio/server exec vitest run src/__tests__/dispatch.test.ts src/__tests__/session-commands.test.ts src/__tests__/terminal-commands.test.ts src/__tests__/file-commands.test.ts src/__tests__/git-commands.test.ts src/__tests__/task-commands.test.ts src/__tests__/lsp-commands.test.ts src/__tests__/worktree-commands.test.ts`
+- `pnpm --filter @coder-studio/server exec vitest run src/commands/settings.test.ts src/__tests__/diagnostics-commands.test.ts src/__tests__/provider-runtime/runtime-status.test.ts src/__tests__/provider-runtime/install-manager.test.ts src/__tests__/system-deps/commands.test.ts`
+- `pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/commands.test.ts src/__tests__/agent-context-command.test.ts src/__tests__/agent-instructions-command.test.ts src/__tests__/session-analysis-commands.test.ts src/__tests__/session-review-command.test.ts src/__tests__/supervisor-commands.test.ts src/__tests__/work-analysis-commands.test.ts`
+- `pnpm --filter @coder-studio/server exec vitest run src/__tests__/ws-hub.test.ts src/__tests__/monitoring/service.test.ts src/__tests__/server-memory-wiring.test.ts src/__tests__/server-provider-install-wiring.test.ts`
+
+---
+
+### Task 1: Add Split Contexts And Command Registries
+
+**Files:**
+- Create: `packages/server/src/host/context.ts`
+- Create: `packages/server/src/host/command-registry.ts`
+- Create: `packages/server/src/runtime/contract.ts`
+- Create: `packages/server/src/runtime/context.ts`
+- Create: `packages/server/src/runtime/command-registry.ts`
+- Create: `packages/server/src/__tests__/host-command-registry.test.ts`
+- Create: `packages/server/src/__tests__/runtime-command-registry.test.ts`
+- Modify: `packages/server/src/ws/index.ts`
+
+- [ ] **Step 1: Write the failing registry tests**
+
+Create `packages/server/src/__tests__/host-command-registry.test.ts` with:
+
+```ts
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import {
+  clearHostCommandsForTest,
+  getHostCommandDefinition,
+  registerHostCommand,
+} from "../host/command-registry.js";
+
+describe("host command registry", () => {
+  it("stores host command definitions by op", () => {
+    clearHostCommandsForTest();
+    registerHostCommand("host.test", z.object({ value: z.number() }), async (args) => ({
+      doubled: args.value * 2,
+    }));
+
+    const definition = getHostCommandDefinition("host.test");
+    expect(definition?.schema.parse({ value: 2 })).toEqual({ value: 2 });
+  });
+});
+```
+
+Create `packages/server/src/__tests__/runtime-command-registry.test.ts` with:
+
+```ts
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import {
+  clearRuntimeCommandsForTest,
+  getRuntimeCommandDefinition,
+  registerRuntimeCommand,
+} from "../runtime/command-registry.js";
+
+describe("runtime command registry", () => {
+  it("keeps route resolution metadata next to the runtime handler", () => {
+    clearRuntimeCommandsForTest();
+    registerRuntimeCommand(
+      "runtime.test",
+      z.object({ workspaceId: z.string() }),
+      {
+        resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+        handler: async () => ({ ok: true }),
+      }
+    );
+
+    const definition = getRuntimeCommandDefinition("runtime.test");
+    expect(definition?.resolveTarget({ workspaceId: "ws-1" })).toEqual({
+      kind: "workspace",
+      workspaceId: "ws-1",
+    });
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/host-command-registry.test.ts src/__tests__/runtime-command-registry.test.ts
+```
+
+Expected: FAIL because the new host/runtime registry modules do not exist yet.
+
+- [ ] **Step 3: Write the split context and registry implementation**
+
+Create `packages/server/src/runtime/contract.ts` with:
+
+```ts
+import type { DomainEvent, ProviderDefinition } from "@coder-studio/core";
+import type { RequestAuthContext } from "../auth/index.js";
+
+export type RuntimeRouteTarget =
+  | { kind: "workspace"; workspaceId: string }
+  | { kind: "session"; sessionId: string }
+  | { kind: "terminal"; terminalId: string }
+  | { kind: "default" };
+
+export interface RuntimeExecuteMeta {
+  clientId?: string;
+  authContext?: RequestAuthContext;
+}
+
+export interface RuntimeHostBridge {
+  issueSessionToken(input: {
+    sessionId: string;
+    workspaceId: string;
+    providerId: string;
+    permissions: readonly string[];
+  }): { token: string };
+  revokeSessionTokensBySessionId(sessionId: string): void;
+  getHostApiUrl(): string | undefined;
+  emitDomainEvent(event: DomainEvent): void;
+  broadcast(topic: string, payload: unknown): void;
+  sendToClient(clientId: string, payload: unknown): boolean;
+  sendBinaryToClient(clientId: string, payload: Buffer): boolean;
+}
+
+export interface RuntimeHandle {
+  id: string;
+  kind: "native" | "wsl";
+  execute(op: string, args: unknown, meta?: RuntimeExecuteMeta): Promise<unknown>;
+  disposeWorkspace(workspaceId: string): Promise<void>;
+  setProviderRegistry?(providers: ProviderDefinition[]): void;
+  health(): Promise<{ ok: true }>;
+}
+```
+
+Create `packages/server/src/host/context.ts` with:
+
+```ts
+import type { ProviderDefinition } from "@coder-studio/core";
+import type { RequestAuthContext } from "../auth/index.js";
+import type { AutomationAuditLog } from "../automation/audit-log.js";
+import type { ServerConfig } from "../config.js";
+import type { MonitoringService } from "../monitoring/service.js";
+import type { CustomProviderRepo } from "../storage/repositories/custom-provider-repo.js";
+import type { MemoryRepo } from "../storage/repositories/memory-repo.js";
+import type { SettingsRepo } from "../storage/repositories/settings-repo.js";
+import type { UpdateService } from "../update/update-service.js";
+import type { WorkspaceManager } from "../workspace/manager.js";
+import type { ActivationManager } from "../ws/activation.js";
+import type { Broadcaster } from "../ws/hub.js";
+import type { RuntimeRouter } from "./runtime-router.js";
+import type { WorkspaceRuntimeBindingStore } from "./workspace-runtime-binding.js";
+
+export interface HostCommandContext {
+  workspaceMgr: WorkspaceManager;
+  settingsRepo: SettingsRepo;
+  memoryRepo?: MemoryRepo;
+  activationMgr: ActivationManager;
+  automationAuditLog?: AutomationAuditLog;
+  broadcaster: Broadcaster;
+  runtimeRouter: RuntimeRouter;
+  runtimeBindings: WorkspaceRuntimeBindingStore;
+  config?: Pick<ServerConfig, "auth" | "host">;
+  updateService?: UpdateService;
+  monitoringService?: MonitoringService;
+  customProviderRepo?: CustomProviderRepo;
+  providerRegistry: ProviderDefinition[];
+  setProviderRegistry?: (providers: ProviderDefinition[]) => void;
+}
+
+export interface HostDispatchMeta {
+  clientId?: string;
+  authContext?: RequestAuthContext;
+}
+```
+
+Create `packages/server/src/runtime/context.ts` with:
+
+```ts
+import type { ProviderDefinition } from "@coder-studio/core";
+import type { AgentInstructionsPublisher } from "../agent-instructions/publisher.js";
+import type { EventBus } from "../bus/event-bus.js";
+import type { LspManager } from "../lsp/manager.js";
+import type { LspToolInstallManager } from "../lsp-tools/install-manager.js";
+import type { LspToolManager } from "../lsp-tools/manager.js";
+import type { ProviderInstallManager } from "../provider-runtime/install-manager.js";
+import type { RuntimeStatusDeps } from "../provider-runtime/runtime-status.js";
+import type { SessionManager } from "../session/manager.js";
+import type { SessionAnalysisService } from "../session-analysis/service.js";
+import type { BuiltinSkillSyncManager } from "../skills/builtin/sync-manager.js";
+import type { SkillHealthManager } from "../skills/health-manager.js";
+import type { SkillInstallManager } from "../skills/install-manager.js";
+import type { SkillMountManager } from "../skills/mount-manager.js";
+import type { SkillsHubClient } from "../skills/skills-hub-client.js";
+import type { ProviderConfigRepo } from "../storage/repositories/provider-config-repo.js";
+import type { SessionMetadataRepo } from "../storage/repositories/session-metadata-repo.js";
+import type { SkillLibraryRepo } from "../storage/repositories/skill-library-repo.js";
+import type { SkillMountRepo } from "../storage/repositories/skill-mount-repo.js";
+import type { SkillTargetRepo } from "../storage/repositories/skill-target-repo.js";
+import type { SupervisorManager } from "../supervisor/manager.js";
+import type { SystemDependencyInstallManager } from "../system-deps/install-manager.js";
+import type { TaskManager } from "../tasks/manager.js";
+import type { TerminalManager } from "../terminal/manager.js";
+import type { WorkAnalysisService } from "../work-analysis/service.js";
+import type { RuntimeHostBridge } from "./contract.js";
+
+export interface RuntimeCommandContext {
+  runtimeId: string;
+  workspaceLookup: {
+    get(workspaceId: string): { id: string; path: string; targetRuntime: "native" | "wsl" } | undefined;
+    list(): Array<{ id: string; path: string; targetRuntime: "native" | "wsl" }>;
+  };
+  hostBridge: RuntimeHostBridge;
+  eventBus: EventBus;
+  providerConfigRepo: ProviderConfigRepo;
+  providerRegistry: ProviderDefinition[];
+  sessionMgr: SessionManager;
+  terminalMgr: TerminalManager;
+  taskMgr: TaskManager;
+  lspMgr: LspManager;
+  lspToolMgr?: LspToolManager;
+  lspToolInstallMgr?: LspToolInstallManager;
+  supervisorMgr: SupervisorManager;
+  providerRuntimeDeps?: RuntimeStatusDeps;
+  providerInstallMgr?: ProviderInstallManager;
+  systemDependencyInstallMgr?: SystemDependencyInstallManager;
+  skillsHubClient?: SkillsHubClient;
+  skillInstallMgr?: SkillInstallManager;
+  skillMountMgr?: SkillMountManager;
+  skillHealthMgr?: SkillHealthManager;
+  skillLibraryRepo?: SkillLibraryRepo;
+  skillTargetRepo?: SkillTargetRepo;
+  skillMountRepo?: SkillMountRepo;
+  builtinSkillSyncMgr?: BuiltinSkillSyncManager;
+  sessionMetadataRepo?: SessionMetadataRepo;
+  sessionAnalysisService?: SessionAnalysisService;
+  workAnalysisService?: WorkAnalysisService;
+  agentInstructionPublisher?: AgentInstructionsPublisher;
+}
+```
+
+Create `packages/server/src/host/command-registry.ts` and `packages/server/src/runtime/command-registry.ts` with module-level registries mirroring the current `registerCommand()` pattern, plus `clear*ForTest()` helpers used only by tests. Keep the host signature aligned with the current handler shape and give runtime command definitions this shape:
+
+```ts
+export interface RuntimeCommandDefinition<S extends z.ZodTypeAny = z.ZodTypeAny, R = unknown> {
+  schema: S;
+  resolveTarget: (args: z.output<S>) => RuntimeRouteTarget;
+  handler: (
+    args: z.output<S>,
+    ctx: RuntimeCommandContext,
+    meta?: RuntimeExecuteMeta
+  ) => Promise<R>;
+}
+```
+
+Update `packages/server/src/ws/index.ts` to export:
+
+```ts
+export {
+  registerHostCommand,
+  getHostCommandDefinition,
+} from "../host/command-registry.js";
+export {
+  registerRuntimeCommand,
+  getRuntimeCommandDefinition,
+} from "../runtime/command-registry.js";
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/host-command-registry.test.ts src/__tests__/runtime-command-registry.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/host/context.ts packages/server/src/host/command-registry.ts packages/server/src/runtime/contract.ts packages/server/src/runtime/context.ts packages/server/src/runtime/command-registry.ts packages/server/src/ws/index.ts packages/server/src/__tests__/host-command-registry.test.ts packages/server/src/__tests__/runtime-command-registry.test.ts
+git commit -m "refactor: add host and runtime command registries"
+```
+
+### Task 2: Add Runtime Routing, Workspace Bindings, And Host Projections
+
+**Files:**
+- Create: `packages/server/src/host/runtime-registry.ts`
+- Create: `packages/server/src/host/runtime-router.ts`
+- Create: `packages/server/src/host/workspace-runtime-binding.ts`
+- Create: `packages/server/src/__tests__/runtime-router.test.ts`
+- Create: `packages/server/src/__tests__/workspace-runtime-binding.test.ts`
+
+- [ ] **Step 1: Write the failing routing and binding tests**
+
+Create `packages/server/src/__tests__/workspace-runtime-binding.test.ts` with:
+
+```ts
+import { describe, expect, it } from "vitest";
+import { WorkspaceRuntimeBindingStore } from "../host/workspace-runtime-binding.js";
+
+describe("WorkspaceRuntimeBindingStore", () => {
+  it("tracks workspace, session, and terminal bindings together", () => {
+    const store = new WorkspaceRuntimeBindingStore();
+    store.bindWorkspace("ws-1", "native-default");
+    store.bindSession({ id: "sess-1", workspaceId: "ws-1", terminalId: "term-1", state: "running" });
+    store.bindTerminal({ id: "term-1", workspaceId: "ws-1", kind: "agent", title: "Claude", cwd: "/repo" });
+
+    expect(store.getRuntimeIdForWorkspace("ws-1")).toBe("native-default");
+    expect(store.findWorkspaceIdBySessionId("sess-1")).toBe("ws-1");
+    expect(store.findWorkspaceIdByTerminalId("term-1")).toBe("ws-1");
+    expect(store.listSessionsForWorkspace("ws-1")).toHaveLength(1);
+    expect(store.listTerminalsForWorkspace("ws-1")).toHaveLength(1);
+  });
+});
+```
+
+Create `packages/server/src/__tests__/runtime-router.test.ts` with:
+
+```ts
+import { describe, expect, it, vi } from "vitest";
+import { RuntimeRegistry } from "../host/runtime-registry.js";
+import { RuntimeRouter } from "../host/runtime-router.js";
+import { WorkspaceRuntimeBindingStore } from "../host/workspace-runtime-binding.js";
+
+describe("RuntimeRouter", () => {
+  it("resolves workspace, session, terminal, and default targets", async () => {
+    const bindings = new WorkspaceRuntimeBindingStore();
+    bindings.bindWorkspace("ws-1", "native-default");
+    bindings.bindSession({ id: "sess-1", workspaceId: "ws-1", terminalId: "term-1", state: "running" });
+    bindings.bindTerminal({ id: "term-1", workspaceId: "ws-1", kind: "agent", title: "agent", cwd: "/repo" });
+
+    const execute = vi.fn(async () => ({ ok: true }));
+    const registry = new RuntimeRegistry();
+    registry.register({
+      id: "native-default",
+      kind: "native",
+      execute,
+      disposeWorkspace: vi.fn(),
+      health: async () => ({ ok: true }),
+    });
+
+    const router = new RuntimeRouter({ runtimeRegistry: registry, bindings, defaultRuntimeId: "native-default" });
+
+    await router.executeOnTarget({ kind: "workspace", workspaceId: "ws-1" }, "file.read", {});
+    await router.executeOnTarget({ kind: "session", sessionId: "sess-1" }, "session.stop", {});
+    await router.executeOnTarget({ kind: "terminal", terminalId: "term-1" }, "terminal.read", {});
+    await router.executeOnTarget({ kind: "default" }, "skills.library.list", {});
+
+    expect(execute).toHaveBeenCalledTimes(4);
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/runtime-router.test.ts src/__tests__/workspace-runtime-binding.test.ts
+```
+
+Expected: FAIL because the runtime router and binding store do not exist yet.
+
+- [ ] **Step 3: Implement runtime registry, router, and host-side projection store**
+
+Create `packages/server/src/host/workspace-runtime-binding.ts` with a single store that owns:
+
+```ts
+import type { Session, Terminal } from "@coder-studio/core";
+
+export class WorkspaceRuntimeBindingStore {
+  private readonly runtimeIdByWorkspaceId = new Map<string, string>();
+  private readonly workspaceIdBySessionId = new Map<string, string>();
+  private readonly workspaceIdByTerminalId = new Map<string, string>();
+  private readonly sessionsByWorkspaceId = new Map<string, Map<string, Session>>();
+  private readonly terminalsByWorkspaceId = new Map<string, Map<string, Terminal>>();
+
+  bindWorkspace(workspaceId: string, runtimeId: string): void {
+    this.runtimeIdByWorkspaceId.set(workspaceId, runtimeId);
+  }
+
+  unbindWorkspace(workspaceId: string): void {
+    this.runtimeIdByWorkspaceId.delete(workspaceId);
+    const sessions = this.sessionsByWorkspaceId.get(workspaceId);
+    for (const sessionId of sessions?.keys() ?? []) this.workspaceIdBySessionId.delete(sessionId);
+    const terminals = this.terminalsByWorkspaceId.get(workspaceId);
+    for (const terminalId of terminals?.keys() ?? []) this.workspaceIdByTerminalId.delete(terminalId);
+    this.sessionsByWorkspaceId.delete(workspaceId);
+    this.terminalsByWorkspaceId.delete(workspaceId);
+  }
+
+  bindSession(session: Session): void {
+    this.workspaceIdBySessionId.set(session.id, session.workspaceId);
+    const bucket = this.sessionsByWorkspaceId.get(session.workspaceId) ?? new Map<string, Session>();
+    bucket.set(session.id, session);
+    this.sessionsByWorkspaceId.set(session.workspaceId, bucket);
+  }
+
+  removeSession(sessionId: string): void {
+    const workspaceId = this.workspaceIdBySessionId.get(sessionId);
+    if (!workspaceId) return;
+    this.workspaceIdBySessionId.delete(sessionId);
+    this.sessionsByWorkspaceId.get(workspaceId)?.delete(sessionId);
+  }
+
+  bindTerminal(terminal: Terminal): void {
+    this.workspaceIdByTerminalId.set(terminal.id, terminal.workspaceId);
+    const bucket = this.terminalsByWorkspaceId.get(terminal.workspaceId) ?? new Map<string, Terminal>();
+    bucket.set(terminal.id, terminal);
+    this.terminalsByWorkspaceId.set(terminal.workspaceId, bucket);
+  }
+
+  removeTerminal(terminalId: string): void {
+    const workspaceId = this.workspaceIdByTerminalId.get(terminalId);
+    if (!workspaceId) return;
+    this.workspaceIdByTerminalId.delete(terminalId);
+    this.terminalsByWorkspaceId.get(workspaceId)?.delete(terminalId);
+  }
+}
+```
+
+Create `packages/server/src/host/runtime-registry.ts` with a small named registry:
+
+```ts
+import type { ProviderDefinition } from "@coder-studio/core";
+import type { RuntimeHandle } from "../runtime/contract.js";
+
+export class RuntimeRegistry {
+  private readonly runtimes = new Map<string, RuntimeHandle>();
+
+  register(runtime: RuntimeHandle): void {
+    this.runtimes.set(runtime.id, runtime);
+  }
+
+  get(runtimeId: string): RuntimeHandle | undefined {
+    return this.runtimes.get(runtimeId);
+  }
+
+  setProviderRegistry(providers: ProviderDefinition[]): void {
+    for (const runtime of this.runtimes.values()) {
+      runtime.setProviderRegistry?.(providers);
+    }
+  }
+}
+```
+
+Create `packages/server/src/host/runtime-router.ts` with:
+
+```ts
+import type { RequestAuthContext } from "../auth/index.js";
+import type { RuntimeExecuteMeta, RuntimeRouteTarget } from "../runtime/contract.js";
+import type { RuntimeRegistry } from "./runtime-registry.js";
+import type { WorkspaceRuntimeBindingStore } from "./workspace-runtime-binding.js";
+
+export class RuntimeRouter {
+  constructor(
+    private readonly deps: {
+      runtimeRegistry: RuntimeRegistry;
+      bindings: WorkspaceRuntimeBindingStore;
+      defaultRuntimeId: string;
+    }
+  ) {}
+
+  private resolveRuntimeId(target: RuntimeRouteTarget): string {
+    if (target.kind === "default") {
+      return this.deps.defaultRuntimeId;
+    }
+
+    const workspaceId =
+      target.kind === "workspace"
+        ? target.workspaceId
+        : target.kind === "session"
+          ? this.deps.bindings.findWorkspaceIdBySessionId(target.sessionId)
+          : this.deps.bindings.findWorkspaceIdByTerminalId(target.terminalId);
+
+    if (!workspaceId) {
+      throw { code: "workspace_not_found", message: "Unable to resolve runtime target" };
+    }
+
+    const runtimeId = this.deps.bindings.getRuntimeIdForWorkspace(workspaceId);
+    if (!runtimeId) {
+      throw { code: "runtime_not_bound", message: `No runtime bound for workspace: ${workspaceId}` };
+    }
+
+    return runtimeId;
+  }
+
+  async executeOnTarget(
+    target: RuntimeRouteTarget,
+    op: string,
+    args: unknown,
+    meta?: RuntimeExecuteMeta
+  ): Promise<unknown> {
+    const runtimeId = this.resolveRuntimeId(target);
+    const runtime = this.deps.runtimeRegistry.get(runtimeId);
+    if (!runtime) {
+      throw { code: "runtime_not_found", message: `Runtime not found: ${runtimeId}` };
+    }
+    return runtime.execute(op, args, meta);
+  }
+
+  getAuthContextForClient(_clientId?: string): RequestAuthContext | undefined {
+    return undefined;
+  }
+}
+```
+
+Also add `getRuntimeIdForWorkspace()`, `findWorkspaceIdBySessionId()`, `findWorkspaceIdByTerminalId()`, `listSessionsForWorkspace()`, and `listTerminalsForWorkspace()` methods to the binding store because later tasks use them for auth scope checks, `WsHub.resync`, update gating, and monitoring.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/runtime-router.test.ts src/__tests__/workspace-runtime-binding.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/host/runtime-registry.ts packages/server/src/host/runtime-router.ts packages/server/src/host/workspace-runtime-binding.ts packages/server/src/__tests__/runtime-router.test.ts packages/server/src/__tests__/workspace-runtime-binding.test.ts
+git commit -m "refactor: add runtime router and workspace bindings"
+```
+
+### Task 3: Make Workspace Lifecycle Carry Explicit Runtime Metadata
+
+**Files:**
+- Modify: `packages/server/src/workspace/manager.ts`
+- Modify: `packages/server/src/commands/workspace.ts`
+- Test: `packages/server/src/__tests__/workspace/manager.test.ts`
+- Test: `packages/server/src/__tests__/workspace/manager-on-close.test.ts`
+- Test: `packages/server/src/__tests__/workspace-commands.test.ts`
+
+- [ ] **Step 1: Write the failing workspace metadata tests**
+
+Add this test to `packages/server/src/__tests__/workspace/manager.test.ts`:
+
+```ts
+it("persists explicit targetRuntime and wslDistro on new workspaces", async () => {
+  const workspace = await manager.open({
+    path: testDir,
+    targetRuntime: "wsl",
+    wslDistro: "Ubuntu-24.04",
+  });
+
+  expect(workspace.targetRuntime).toBe("wsl");
+  expect(workspace.wslDistro).toBe("Ubuntu-24.04");
+});
+```
+
+Add this test to `packages/server/src/__tests__/workspace-commands.test.ts`:
+
+```ts
+it("workspace.open still records a native workspace through the command layer", async () => {
+  const workspaceDir = join(tmpdir(), `workspace-open-native-${Date.now()}`);
+  await mkdir(workspaceDir, { recursive: true });
+
+  const result = await dispatch(
+    {
+      kind: "command",
+      id: "workspace-open-native",
+      op: "workspace.open",
+      args: { path: workspaceDir },
+    },
+    ctx
+  );
+
+  expect(result.ok).toBe(true);
+  expect(result.data).toMatchObject({ targetRuntime: "native" });
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/workspace/manager.test.ts src/__tests__/workspace/manager-on-close.test.ts src/__tests__/workspace-commands.test.ts
+```
+
+Expected: FAIL because `WorkspaceManager.open()` still hardcodes `targetRuntime: "native"` and its request type does not accept explicit runtime metadata.
+
+- [ ] **Step 3: Implement explicit runtime metadata in workspace lifecycle**
+
+Update `packages/server/src/workspace/manager.ts`:
+
+```ts
+import type { DomainEvent, Workspace } from "@coder-studio/core";
+
+export interface OpenWorkspaceRequest {
+  path: string;
+  targetRuntime: Workspace["targetRuntime"];
+  wslDistro?: string;
+}
+
+// inside open():
+const workspace: Workspace = {
+  id: generateWorkspaceId(),
+  path: req.path,
+  targetRuntime: req.targetRuntime,
+  wslDistro: req.targetRuntime === "wsl" ? req.wslDistro : undefined,
+  openedAt: Date.now(),
+  lastActiveAt: Date.now(),
+  uiState: {
+    leftPanelWidth: 250,
+    bottomPanelHeight: 200,
+    focusMode: false,
+    paneLayout: { id: "root", type: "leaf", leafKind: "draft" },
+  },
+};
+```
+
+Update `packages/server/src/commands/workspace.ts` temporarily to keep current behavior until the runtime router lands:
+
+```ts
+const workspace = await ctx.workspaceMgr.open({
+  path: args.path,
+  targetRuntime: "native",
+});
+```
+
+Do not change the public `workspace.open` wire format yet; the host runtime decision will replace the hardcoded `"native"` in Task 5.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/workspace/manager.test.ts src/__tests__/workspace/manager-on-close.test.ts src/__tests__/workspace-commands.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/workspace/manager.ts packages/server/src/commands/workspace.ts packages/server/src/__tests__/workspace/manager.test.ts packages/server/src/__tests__/workspace-commands.test.ts
+git commit -m "refactor: make workspace metadata runtime explicit"
+```
+
+### Task 4: Extract Runtime Assembly And Native Runtime Handle
+
+**Files:**
+- Create: `packages/server/src/runtime/runtime-state.ts`
+- Create: `packages/server/src/runtime/events.ts`
+- Create: `packages/server/src/runtime/assembly.ts`
+- Create: `packages/server/src/runtime/native-runtime.ts`
+- Create: `packages/server/src/__tests__/runtime/native-runtime.test.ts`
+- Modify: `packages/server/src/session/manager.ts`
+- Modify: `packages/server/src/system-deps/install-manager.ts`
+- Modify: `packages/server/src/storage/repositories/session-metadata-repo.ts`
+
+- [ ] **Step 1: Write the failing native-runtime tests**
+
+Create `packages/server/src/__tests__/runtime/native-runtime.test.ts` with:
+
+```ts
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createNativeRuntime } from "../../runtime/native-runtime.js";
+
+describe("NativeRuntimeHandle", () => {
+  let stateDir: string;
+
+  afterEach(() => {
+    if (stateDir) {
+      rmSync(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it("stores runtime-owned state under state/runtimes/native-default", async () => {
+    stateDir = mkdtempSync(join(tmpdir(), "native-runtime-state-"));
+    const runtime = await createNativeRuntime({
+      runtimeId: "native-default",
+      stateRoot: stateDir,
+      hostBridge: {
+        issueSessionToken: vi.fn(() => ({ token: "token" })),
+        revokeSessionTokensBySessionId: vi.fn(),
+        getHostApiUrl: () => "http://127.0.0.1:4173",
+        emitDomainEvent: vi.fn(),
+        broadcast: vi.fn(),
+        sendToClient: vi.fn(() => true),
+        sendBinaryToClient: vi.fn(() => true),
+      },
+      providerRegistry: [],
+      providerConfigRepoFactory: undefined,
+    });
+
+    expect(runtime.id).toBe("native-default");
+  });
+});
+```
+
+Add this assertion to `packages/server/src/__tests__/session-commands.test.ts` after the existing runtime URL env check:
+
+```ts
+expect(createdSpecs[0]?.env?.CODER_STUDIO_SESSION_TOKEN).toMatch(/^[a-f0-9]{64}$/);
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/runtime/native-runtime.test.ts src/__tests__/session-commands.test.ts
+```
+
+Expected: FAIL because the extracted runtime assembly and native runtime modules do not exist yet.
+
+- [ ] **Step 3: Implement runtime state helpers, host bridge adapters, and native runtime**
+
+Create `packages/server/src/runtime/runtime-state.ts`:
+
+```ts
+import { join } from "node:path";
+
+export function getRuntimeStateRoot(stateRoot: string, runtimeId: string): string {
+  return join(stateRoot, "state", "runtimes", runtimeId);
+}
+
+export function getRuntimeStateFile(stateRoot: string, runtimeId: string, ...parts: string[]): string {
+  return join(getRuntimeStateRoot(stateRoot, runtimeId), ...parts);
+}
+```
+
+Create `packages/server/src/runtime/events.ts` with host bridge adapters:
+
+```ts
+import type { DomainEvent } from "@coder-studio/core";
+import type { RuntimeHostBridge } from "./contract.js";
+
+export function emitRuntimeEvent(hostBridge: RuntimeHostBridge, event: DomainEvent): void {
+  hostBridge.emitDomainEvent(event);
+}
+
+export function broadcastRuntimeTopic(
+  hostBridge: RuntimeHostBridge,
+  topic: string,
+  payload: unknown
+): void {
+  hostBridge.broadcast(topic, payload);
+}
+```
+
+Update `packages/server/src/session/manager.ts` to stop owning host token/runtime URL concerns directly. Replace:
+
+```ts
+import { SessionTokenRepo } from "../auth/session-token-repo.js";
+
+export interface SessionRuntimeContext {
+  apiUrl?: string;
+}
+```
+
+with bridge-driven dependencies:
+
+```ts
+import type { RuntimeHostBridge } from "../runtime/contract.js";
+
+export interface SessionManagerDeps {
+  // existing deps...
+  hostBridge: RuntimeHostBridge;
+}
+```
+
+Then inside `create()`:
+
+```ts
+const tokenRecord = this.deps.hostBridge.issueSessionToken({
+  sessionId,
+  workspaceId: req.workspaceId,
+  providerId: req.providerId,
+  permissions,
+});
+
+env: {
+  ...cmd.env,
+  CODER_STUDIO_SESSION_TOKEN: tokenRecord.token,
+  ...(this.deps.hostBridge.getHostApiUrl()
+    ? { CODER_STUDIO_API_URL: this.deps.hostBridge.getHostApiUrl() }
+    : {}),
+}
+```
+
+and replace every `this.sessionTokenRepo.revokeBySessionId(...)` call with:
+
+```ts
+this.deps.hostBridge.revokeSessionTokensBySessionId(session.id);
+```
+
+Update `packages/server/src/system-deps/install-manager.ts` so the broadcaster dependency becomes:
+
+```ts
+export interface SystemDependencyInstallManagerDeps extends RuntimeStatusDeps {
+  ptyHost: PtyHost;
+  hostBridge: Pick<RuntimeHostBridge, "sendToClient">;
+}
+```
+
+and replace `this.deps.broadcaster.sendToClient(...)` with `this.deps.hostBridge.sendToClient(...)`.
+
+Update `packages/server/src/storage/repositories/session-metadata-repo.ts` so the constructor depends on a small `workspaceLookup` interface instead of `WorkspaceRepo`:
+
+```ts
+interface SessionMetadataWorkspaceLookup {
+  list(): SessionMetadataWorkspace[];
+  get(workspaceId: string): SessionMetadataWorkspace | undefined;
+}
+```
+
+Create `packages/server/src/runtime/assembly.ts` that moves the runtime-owned repo/manager graph out of `server.ts` and returns:
+
+```ts
+export interface RuntimeAssembly {
+  context: RuntimeCommandContext;
+  stop(): Promise<void>;
+}
+```
+
+Create `packages/server/src/runtime/native-runtime.ts`:
+
+```ts
+import { executeRuntimeCommand } from "../ws/dispatch.js";
+import type { RuntimeHandle, RuntimeHostBridge } from "./contract.js";
+import { assembleRuntime } from "./assembly.js";
+
+export async function createNativeRuntime(input: {
+  runtimeId: string;
+  stateRoot: string;
+  hostBridge: RuntimeHostBridge;
+  providerRegistry: ProviderDefinition[];
+  workspaceLookup: RuntimeCommandContext["workspaceLookup"];
+  providerRuntimeDeps?: RuntimeStatusDeps;
+}): Promise<RuntimeHandle> {
+  const assembly = await assembleRuntime(input);
+  return {
+    id: input.runtimeId,
+    kind: "native",
+    execute: (op, args, meta) => executeRuntimeCommand(op, args, assembly.context, meta),
+    disposeWorkspace: async (workspaceId) => {
+      await assembly.context.lspMgr.disposeWorkspace(workspaceId);
+      await assembly.context.sessionMgr.stopForWorkspace(workspaceId);
+      assembly.context.sessionMgr.deleteEndedForWorkspace(workspaceId);
+      assembly.context.taskMgr.clearWorkspace(workspaceId);
+      await assembly.context.terminalMgr.closeForWorkspace(workspaceId);
+    },
+    setProviderRegistry: (providers) => {
+      assembly.context.providerRegistry = providers;
+      assembly.context.sessionMgr.setProviderRegistry(providers);
+      assembly.context.supervisorMgr.setProviderRegistry(providers);
+    },
+    health: async () => ({ ok: true }),
+  };
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/runtime/native-runtime.test.ts src/__tests__/session-commands.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/runtime/runtime-state.ts packages/server/src/runtime/events.ts packages/server/src/runtime/assembly.ts packages/server/src/runtime/native-runtime.ts packages/server/src/session/manager.ts packages/server/src/system-deps/install-manager.ts packages/server/src/storage/repositories/session-metadata-repo.ts packages/server/src/__tests__/runtime/native-runtime.test.ts packages/server/src/__tests__/session-commands.test.ts
+git commit -m "refactor: extract native runtime assembly"
+```
+
+### Task 5: Rebuild Server Bootstrap Around Host And Runtime
+
+**Files:**
+- Modify: `packages/server/src/server.ts`
+- Modify: `packages/server/src/commands/index.ts`
+- Modify: `packages/server/src/__tests__/server-builtin-skills-wiring.test.ts`
+- Modify: `packages/server/src/__tests__/server-lsp-runtime-mode-hydration.test.ts`
+- Modify: `packages/server/src/__tests__/server-runtime-config.test.ts`
+
+- [ ] **Step 1: Write the failing bootstrap assertions**
+
+Add this assertion to `packages/server/src/__tests__/server-builtin-skills-wiring.test.ts`:
+
+```ts
+expect(server.__test__?.hostContext.runtimeRouter).toBeDefined();
+expect(server.__test__?.nativeRuntime).toBeDefined();
+```
+
+Add this assertion to `packages/server/src/__tests__/server-lsp-runtime-mode-hydration.test.ts`:
+
+```ts
+expect(server.__test__?.nativeRuntime).toBeDefined();
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/server-builtin-skills-wiring.test.ts src/__tests__/server-lsp-runtime-mode-hydration.test.ts src/__tests__/server-runtime-config.test.ts
+```
+
+Expected: FAIL because `createServer()` still exposes a monolithic `commandContext` instead of host/runtime pieces.
+
+- [ ] **Step 3: Move runtime assembly out of `server.ts` and wire host bridge + router**
+
+Refactor `packages/server/src/server.ts` so host-owned assembly stays in `createServer()` and runtime-owned assembly moves behind `createNativeRuntime()`. The key shape should become:
+
+```ts
+const eventBus = new EventBus();
+const activationMgr = new ActivationManager();
+const fencingMgr = new FencingManager();
+const wsHub = new WsHub({ eventBus, commandContext: null, config, fencingMgr });
+
+const bindings = new WorkspaceRuntimeBindingStore();
+const runtimeRegistry = new RuntimeRegistry();
+const runtimeRouter = new RuntimeRouter({
+  runtimeRegistry,
+  bindings,
+  defaultRuntimeId: "native-default",
+});
+
+const hostBridge = {
+  issueSessionToken: (input) => sessionTokenRepo.issue(input),
+  revokeSessionTokensBySessionId: (sessionId) => sessionTokenRepo.revokeBySessionId(sessionId),
+  getHostApiUrl: () =>
+    `http://${config.host === "0.0.0.0" ? "127.0.0.1" : config.host}:${config.port}`,
+  emitDomainEvent: (event) => {
+    eventBus.emit(event);
+    if (event.type === "session.state.changed" && event.session) {
+      bindings.bindSession(event.session);
+    }
+    if (event.type === "session.lifecycle" && event.event === "removed") {
+      bindings.removeSession(event.sessionId);
+    }
+    if (event.type === "terminal.created") {
+      bindings.bindTerminal({
+        id: event.terminalId,
+        workspaceId: event.workspaceId,
+        kind: event.kind,
+        title: event.title,
+        cwd: event.cwd,
+      } as never);
+    }
+    if (event.type === "terminal.exited") {
+      bindings.removeTerminal(event.terminalId);
+    }
+  },
+  broadcast: (topic, payload) => wsHub.broadcast(topic, payload),
+  sendToClient: (clientId, payload) => wsHub.sendToClient(clientId as never, payload as never),
+  sendBinaryToClient: (clientId, payload) => wsHub.sendBinaryToClient(clientId as never, payload),
+} satisfies RuntimeHostBridge;
+
+const nativeRuntime = await createNativeRuntime({
+  runtimeId: "native-default",
+  stateRoot,
+  hostBridge,
+  providerRegistry: activeProviderRegistry,
+  workspaceLookup: workspaceMgr,
+  providerRuntimeDeps,
+});
+
+runtimeRegistry.register(nativeRuntime);
+```
+
+Change `packages/server/src/commands/index.ts` from side-effect-only imports into explicit registration functions:
+
+```ts
+export function registerHostCommands(): void { ... }
+export function registerRuntimeCommands(): void { ... }
+```
+
+Then `createServer()` should call both registration functions after building the router.
+
+Expose this new test surface:
+
+```ts
+return {
+  app,
+  stop: stopServer,
+  __test__: {
+    hostContext,
+    nativeRuntime,
+    sessionTokenRepo,
+  },
+};
+```
+
+Keep runtime config writing behavior unchanged.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/server-builtin-skills-wiring.test.ts src/__tests__/server-lsp-runtime-mode-hydration.test.ts src/__tests__/server-runtime-config.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/server.ts packages/server/src/commands/index.ts packages/server/src/__tests__/server-builtin-skills-wiring.test.ts packages/server/src/__tests__/server-lsp-runtime-mode-hydration.test.ts packages/server/src/__tests__/server-runtime-config.test.ts
+git commit -m "refactor: bootstrap server around host and native runtime"
+```
+
+### Task 6: Route Dispatch Through Host And Runtime Registries
+
+**Files:**
+- Modify: `packages/server/src/ws/dispatch.ts`
+- Modify: `packages/server/src/ws/hub.ts`
+- Test: `packages/server/src/__tests__/dispatch.test.ts`
+
+- [ ] **Step 1: Write the failing dispatch-routing tests**
+
+Add these tests to `packages/server/src/__tests__/dispatch.test.ts`:
+
+```ts
+it("dispatches runtime commands through the runtime router", async () => {
+  const executeOnTarget = vi.fn(async () => ({ ok: true }));
+  ctx = {
+    ...ctx,
+    runtimeRouter: { executeOnTarget } as never,
+  };
+
+  registerRuntimeCommand(
+    "runtime.echo",
+    z.object({ workspaceId: z.string(), message: z.string() }),
+    {
+      resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+      handler: async () => ({ echoed: true }),
+    }
+  );
+
+  const result = await dispatch(
+    {
+      kind: "command",
+      id: "runtime-dispatch-1",
+      op: "runtime.echo",
+      args: { workspaceId: "ws-test", message: "hello" },
+    },
+    ctx
+  );
+
+  expect(result.ok).toBe(true);
+  expect(executeOnTarget).toHaveBeenCalledWith(
+    { kind: "workspace", workspaceId: "ws-test" },
+    "runtime.echo",
+    { workspaceId: "ws-test", message: "hello" },
+    expect.anything()
+  );
+});
+
+it("checks terminal session scope from host projections instead of runtime managers", async () => {
+  ctx = {
+    ...ctx,
+    runtimeBindings: {
+      findWorkspaceIdByTerminalId: vi.fn(() => "ws-1"),
+      findSessionIdByTerminalId: vi.fn(() => "sess-1"),
+    } as never,
+  };
+
+  expect(ctx.runtimeBindings.findSessionIdByTerminalId("term-1")).toBe("sess-1");
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/dispatch.test.ts
+```
+
+Expected: FAIL because `dispatch()` still uses the old single handler map and single `CommandContext`.
+
+- [ ] **Step 3: Implement host/runtime dispatch with auth preserved on host**
+
+Refactor `packages/server/src/ws/dispatch.ts` into three entry points:
+
+```ts
+export async function dispatch(
+  msg: Command,
+  ctx: HostCommandContext,
+  clientId?: string
+): Promise<Result> { ... }
+
+export async function executeHostCommand(
+  op: string,
+  args: unknown,
+  ctx: HostCommandContext,
+  meta?: HostDispatchMeta
+): Promise<unknown> { ... }
+
+export async function executeRuntimeCommand(
+  op: string,
+  args: unknown,
+  ctx: RuntimeCommandContext,
+  meta?: RuntimeExecuteMeta
+): Promise<unknown> { ... }
+```
+
+Host dispatch should keep current behavior for:
+- activation gating
+- session-token allowlist checks
+- schema validation
+- unknown-op normalization
+
+Then route commands like this:
+
+```ts
+const hostDefinition = getHostCommandDefinition(msg.op);
+if (hostDefinition) {
+  const args = hostDefinition.schema.parse(msg.args);
+  const data = await hostDefinition.handler(args, ctx, { clientId, authContext });
+  return { kind: "result", id: msg.id, ok: true, data };
+}
+
+const runtimeDefinition = getRuntimeCommandDefinition(msg.op);
+if (runtimeDefinition) {
+  const args = runtimeDefinition.schema.parse(msg.args);
+  const target = runtimeDefinition.resolveTarget(args);
+  const data = await ctx.runtimeRouter.executeOnTarget(target, msg.op, args, {
+    clientId,
+    authContext,
+  });
+  return { kind: "result", id: msg.id, ok: true, data };
+}
+```
+
+Update terminal-related session-token scope checks to read from host projections:
+
+```ts
+const sessionId = ctx.runtimeBindings.findSessionIdByTerminalId(terminalId);
+```
+
+Keep `normalizeError()` untouched so wire behavior does not change.
+
+Update `packages/server/src/ws/hub.ts` only enough for this task to type against `HostCommandContext` instead of the removed monolithic `CommandContext`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/dispatch.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/ws/dispatch.ts packages/server/src/ws/hub.ts packages/server/src/__tests__/dispatch.test.ts
+git commit -m "refactor: route websocket dispatch through host and runtime registries"
+```
+
+### Task 7: Migrate Batch 1 Runtime Commands And Host-Orchestrated Workspace/Session Flow
+
+**Files:**
+- Modify: `packages/server/src/commands/workspace.ts`
+- Modify: `packages/server/src/commands/session.ts`
+- Modify: `packages/server/src/commands/terminal.ts`
+- Modify: `packages/server/src/commands/file.ts`
+- Modify: `packages/server/src/commands/git.ts`
+- Modify: `packages/server/src/commands/recovery.ts`
+- Modify: `packages/server/src/commands/task.ts`
+- Modify: `packages/server/src/commands/lsp.ts`
+- Modify: `packages/server/src/commands/worktree.ts`
+- Test: `packages/server/src/__tests__/workspace-commands.test.ts`
+- Test: `packages/server/src/__tests__/session-commands.test.ts`
+- Test: `packages/server/src/__tests__/terminal-commands.test.ts`
+- Test: `packages/server/src/__tests__/file-commands.test.ts`
+- Test: `packages/server/src/__tests__/git-commands.test.ts`
+- Test: `packages/server/src/__tests__/task-commands.test.ts`
+- Test: `packages/server/src/__tests__/lsp-commands.test.ts`
+- Test: `packages/server/src/__tests__/worktree-commands.test.ts`
+
+- [ ] **Step 1: Write the failing routing tests for representative batch-1 commands**
+
+Add one route assertion to each of the following:
+
+In `packages/server/src/__tests__/session-commands.test.ts`:
+
+```ts
+expect(ctx.runtimeBindings?.findWorkspaceIdBySessionId(openResult.data!.id)).toBeUndefined();
+```
+
+Then replace it after migration with:
+
+```ts
+expect(ctx.runtimeBindings.findWorkspaceIdBySessionId(result.data!.id)).toBe(openResult.data!.id);
+```
+
+In `packages/server/src/__tests__/terminal-commands.test.ts` add:
+
+```ts
+expect(sendCommand).toHaveBeenCalledWith("terminal.read", { terminalId: "term-1" }, undefined);
+```
+
+In `packages/server/src/__tests__/workspace-commands.test.ts` add:
+
+```ts
+expect(result.data).toMatchObject({ targetRuntime: "native" });
+```
+
+- [ ] **Step 2: Run the batch-1 tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/workspace-commands.test.ts src/__tests__/session-commands.test.ts src/__tests__/terminal-commands.test.ts src/__tests__/file-commands.test.ts src/__tests__/git-commands.test.ts src/__tests__/task-commands.test.ts src/__tests__/lsp-commands.test.ts src/__tests__/worktree-commands.test.ts
+```
+
+Expected: FAIL because these command files still register against the host/global registry and `workspace.open` / `session.close` are not orchestrating runtime routing yet.
+
+- [ ] **Step 3: Move batch-1 commands behind `registerRuntimeCommand()` and make host flows orchestrate them**
+
+Convert the following command registrations:
+
+- `file.*` — route by `{ kind: "workspace", workspaceId: args.workspaceId }`
+- `git.*` — route by workspace for most ops; route by terminal/session projections only if a command truly lacks `workspaceId`
+- `recovery.reconcile` — route by `{ kind: "terminal", terminalId: args.terminals[0]!.terminalId }`
+- `task.*` — route by workspace
+- `lsp.*` — route by workspace for all existing ops except `lsp.install.get`, which should use `{ kind: "default" }` in Phase 1 because jobs are runtime-global
+- `worktree.*` — route by workspace
+- `session.list` / `session.create` — route by workspace
+- `session.stop` / `session.remove` — route by session
+- `terminal.read` / `terminal.replay` / `terminal.snapshot` / `terminal.close` / `terminal.input` / `terminal.resize` — route by terminal
+- `terminal.create` / `terminal.list` / `terminal.syncThemeBackground` — route by workspace
+
+Use this pattern in `packages/server/src/commands/terminal.ts`:
+
+```ts
+registerRuntimeCommand(
+  "terminal.read",
+  z.object({
+    terminalId: z.string(),
+    bytes: z.number().int().positive().max(MAX_TERMINAL_READ_BYTES).optional(),
+  }),
+  {
+    resolveTarget: (args) => ({ kind: "terminal", terminalId: args.terminalId }),
+    handler: async (args, ctx, meta) => {
+      const bytes = args.bytes ?? DEFAULT_TERMINAL_READ_BYTES;
+      const tail = ctx.terminalMgr.getRingBufferTail(args.terminalId, bytes);
+      return { terminalId: args.terminalId, bytes, text: tail.toString("utf8") };
+    },
+  }
+);
+```
+
+Rewrite `workspace.open` as a host command:
+
+```ts
+registerHostCommand(
+  "workspace.open",
+  z.object({ path: z.string() }),
+  async (args, ctx) => {
+    const targetRuntime = "native";
+    const workspace = await ctx.workspaceMgr.open({
+      path: args.path,
+      targetRuntime,
+    });
+    ctx.runtimeBindings.bindWorkspace(workspace.id, "native-default");
+    new WorkspaceHistoryStore(ctx.settingsRepo).recordOpen(workspace.path);
+    return workspace;
+  }
+);
+```
+
+Keep `session.close` host-side and implement it as orchestration:
+
+```ts
+registerHostCommand(
+  "session.close",
+  z.object({
+    sessionId: z.string(),
+    paneDisposition: z.enum(["draft", "remove"]).default("draft"),
+  }),
+  async (args, ctx) => {
+    const workspaceId = ctx.runtimeBindings.findWorkspaceIdBySessionId(args.sessionId);
+    if (!workspaceId) {
+      throw { code: "workspace_not_found", message: `Workspace not found for session: ${args.sessionId}` };
+    }
+
+    await ctx.runtimeRouter.executeOnTarget(
+      { kind: "session", sessionId: args.sessionId },
+      "session.stop",
+      { sessionId: args.sessionId }
+    );
+
+    const workspace = ctx.workspaceMgr.get(workspaceId);
+    if (!workspace) {
+      throw { code: "workspace_not_found", message: `Workspace not found: ${workspaceId}` };
+    }
+
+    ctx.workspaceMgr.updateUiState(workspaceId, {
+      ...workspace.uiState,
+      paneLayout: applyPaneDisposition(workspace.uiState.paneLayout, args.sessionId, args.paneDisposition),
+    });
+
+    await ctx.runtimeRouter.executeOnTarget(
+      { kind: "session", sessionId: args.sessionId },
+      "session.remove",
+      { sessionId: args.sessionId }
+    );
+    ctx.runtimeBindings.removeSession(args.sessionId);
+  }
+);
+```
+
+Also move `workspace.intelligence` from `workspace.ts` to runtime registration using `{ kind: "workspace", workspaceId: args.workspaceId }`, and keep `workspace.close` host-side so it can call `runtimeHandle.disposeWorkspace()` before deleting host metadata and uploads.
+
+- [ ] **Step 4: Run the batch-1 tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/workspace-commands.test.ts src/__tests__/session-commands.test.ts src/__tests__/terminal-commands.test.ts src/__tests__/file-commands.test.ts src/__tests__/git-commands.test.ts src/__tests__/task-commands.test.ts src/__tests__/lsp-commands.test.ts src/__tests__/worktree-commands.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/commands/workspace.ts packages/server/src/commands/session.ts packages/server/src/commands/terminal.ts packages/server/src/commands/file.ts packages/server/src/commands/git.ts packages/server/src/commands/recovery.ts packages/server/src/commands/task.ts packages/server/src/commands/lsp.ts packages/server/src/commands/worktree.ts packages/server/src/__tests__/workspace-commands.test.ts packages/server/src/__tests__/session-commands.test.ts packages/server/src/__tests__/terminal-commands.test.ts packages/server/src/__tests__/file-commands.test.ts packages/server/src/__tests__/git-commands.test.ts packages/server/src/__tests__/task-commands.test.ts packages/server/src/__tests__/lsp-commands.test.ts packages/server/src/__tests__/worktree-commands.test.ts
+git commit -m "refactor: route batch one commands through runtime handles"
+```
+
+### Task 8: Bridge Runtime-Backed Provider Config, Diagnostics, And Batch 2 Commands
+
+**Files:**
+- Modify: `packages/server/src/commands/provider.ts`
+- Modify: `packages/server/src/commands/system-deps.ts`
+- Modify: `packages/server/src/commands/settings.ts`
+- Modify: `packages/server/src/commands/diagnostics.ts`
+- Modify: `packages/server/src/commands/custom-provider.ts`
+- Test: `packages/server/src/commands/settings.test.ts`
+- Test: `packages/server/src/__tests__/diagnostics-commands.test.ts`
+- Test: `packages/server/src/__tests__/provider-runtime/runtime-status.test.ts`
+- Test: `packages/server/src/__tests__/provider-runtime/install-manager.test.ts`
+- Test: `packages/server/src/__tests__/system-deps/commands.test.ts`
+- Test: `packages/server/src/__tests__/server-provider-install-wiring.test.ts`
+
+- [ ] **Step 1: Write the failing settings/diagnostics bridge tests**
+
+Add this test to `packages/server/src/commands/settings.test.ts`:
+
+```ts
+it("settings.previewCommand reads provider config through the runtime bridge", async () => {
+  ctx.runtimeRouter = {
+    executeOnTarget: vi.fn(async () => ({
+      argv: ["claude", "--print"],
+      cwd: "/repo",
+      env: { REVIEW_MODE: "strict" },
+      preview: "claude --print  # cwd=/repo",
+    })),
+  } as never;
+
+  const result = await dispatch(
+    {
+      kind: "command",
+      id: "settings-preview-runtime",
+      op: "settings.previewCommand",
+      args: {
+        providerId: "claude",
+        config: {},
+      },
+    },
+    ctx
+  );
+
+  expect(result.ok).toBe(true);
+  expect(ctx.runtimeRouter.executeOnTarget).toHaveBeenCalled();
+});
+```
+
+Add this test to `packages/server/src/__tests__/diagnostics-commands.test.ts`:
+
+```ts
+it("aggregates runtime checks through the runtime router", async () => {
+  ctx.runtimeRouter = {
+    executeOnTarget: vi.fn(async (target, op) => {
+      if (op === "systemDeps.runtimeStatus") {
+        return {
+          dependencies: {
+            git: { dependencyId: "git", available: true, autoInstallSupported: true, installReadiness: "ready", manualGuideKeys: [] },
+            node: { dependencyId: "node", available: true, autoInstallSupported: true, installReadiness: "ready", manualGuideKeys: [] },
+          },
+        };
+      }
+      if (op === "provider.runtimeStatus") {
+        return { providers: {} };
+      }
+      return { lspServices: [] };
+    }),
+  } as never;
+});
+```
+
+- [ ] **Step 2: Run the batch-2 tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/commands/settings.test.ts src/__tests__/diagnostics-commands.test.ts src/__tests__/provider-runtime/runtime-status.test.ts src/__tests__/provider-runtime/install-manager.test.ts src/__tests__/system-deps/commands.test.ts src/__tests__/server-provider-install-wiring.test.ts
+```
+
+Expected: FAIL because these commands still reach runtime managers and provider config repos directly from the host context.
+
+- [ ] **Step 3: Split host and runtime responsibilities for provider config and diagnostics**
+
+Keep `provider.list` as a host command, but move these existing public ops to runtime registration:
+
+- `provider.runtimeStatus` → `{ kind: "default" }`
+- `provider.install.start` → `{ kind: "default" }`
+- `provider.install.get` → `{ kind: "default" }`
+- `systemDeps.runtimeStatus` → `{ kind: "default" }`
+- `systemDeps.install.*` → `{ kind: "default" }`
+
+Add internal runtime-only provider config bridge ops in `packages/server/src/commands/provider.ts`:
+
+```ts
+registerRuntimeCommand(
+  "provider.config.getAll",
+  z.object({}),
+  {
+    resolveTarget: () => ({ kind: "default" }),
+    handler: async (_args, ctx) => ctx.providerConfigRepo.getAll(),
+  }
+);
+
+registerRuntimeCommand(
+  "provider.config.merge",
+  z.object({
+    providerId: z.string(),
+    config: z.record(z.string(), z.unknown()),
+  }),
+  {
+    resolveTarget: () => ({ kind: "default" }),
+    handler: async (args, ctx) => {
+      const provider = getProviderFromRegistryOrThrow(ctx.providerRegistry, args.providerId);
+      const merged = mergeProviderConfigs(provider, ctx.providerConfigRepo.get(args.providerId), args.config);
+      ctx.providerConfigRepo.set(args.providerId, merged);
+      return merged;
+    },
+  }
+);
+
+registerRuntimeCommand(
+  "provider.previewCommand",
+  z.object({
+    providerId: z.string(),
+    config: z.record(z.string(), z.unknown()),
+    workspacePath: z.string().optional(),
+  }),
+  {
+    resolveTarget: () => ({ kind: "default" }),
+    handler: async (args, ctx) => {
+      const provider = getProviderFromRegistryOrThrow(ctx.providerRegistry, args.providerId);
+      const command = provider.buildCommand(
+        mergeProviderConfigs(provider, ctx.providerConfigRepo.get(provider.id), args.config),
+        {
+          sessionId: "preview-session",
+          workspacePath: args.workspacePath ?? process.cwd(),
+        }
+      );
+      return {
+        argv: command.argv,
+        cwd: command.cwd,
+        env: command.env,
+        preview: `${command.argv.join(" ")}${command.cwd ? `  # cwd=${command.cwd}` : ""}`,
+      };
+    },
+  }
+);
+```
+
+Update `packages/server/src/commands/settings.ts`:
+
+- `settings.get` stays host-owned for normal settings, then overlays runtime provider config by calling:
+
+```ts
+const providerConfigs = (await ctx.runtimeRouter.executeOnTarget(
+  { kind: "default" },
+  "provider.config.getAll",
+  {}
+)) as Record<string, ProviderConfig>;
+```
+
+- `settings.update` persists host settings locally, then for each `providers.<id>` branch calls:
+
+```ts
+await ctx.runtimeRouter.executeOnTarget(
+  { kind: "default" },
+  "provider.config.merge",
+  { providerId, config }
+);
+```
+
+- `settings.previewCommand` becomes a host command that forwards to runtime:
+
+```ts
+return ctx.runtimeRouter.executeOnTarget(
+  { kind: "default" },
+  "provider.previewCommand",
+  args
+);
+```
+
+Update `packages/server/src/commands/diagnostics.ts` so it becomes host-orchestrated:
+
+- keep workspace path validation, auth, and host checks local
+- replace direct calls to `buildProviderRuntimeStatus()`, `buildSystemDependencyRuntimeStatus()`, and `ctx.lspToolMgr.runtimeStatus()` with runtime router calls to `provider.runtimeStatus`, `systemDeps.runtimeStatus`, and `lsp.runtimeStatus`
+- keep `fencing.*` host-only; do not route it through runtime
+
+Update `packages/server/src/commands/custom-provider.ts` so host custom provider mutations still write `CustomProviderRepo`, but now fan out provider definitions through:
+
+```ts
+ctx.setProviderRegistry?.(providers);
+ctx.runtimeRouter.setProviderRegistry?.(providers);
+```
+
+- [ ] **Step 4: Run the batch-2 tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/commands/settings.test.ts src/__tests__/diagnostics-commands.test.ts src/__tests__/provider-runtime/runtime-status.test.ts src/__tests__/provider-runtime/install-manager.test.ts src/__tests__/system-deps/commands.test.ts src/__tests__/server-provider-install-wiring.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/commands/provider.ts packages/server/src/commands/system-deps.ts packages/server/src/commands/settings.ts packages/server/src/commands/diagnostics.ts packages/server/src/commands/custom-provider.ts packages/server/src/commands/settings.test.ts packages/server/src/__tests__/diagnostics-commands.test.ts packages/server/src/__tests__/provider-runtime/runtime-status.test.ts packages/server/src/__tests__/provider-runtime/install-manager.test.ts packages/server/src/__tests__/system-deps/commands.test.ts packages/server/src/__tests__/server-provider-install-wiring.test.ts
+git commit -m "refactor: bridge provider config and diagnostics through runtime router"
+```
+
+### Task 9: Migrate Batch 3 Runtime Commands, Host Projections, And Final Host Consumers
+
+**Files:**
+- Modify: `packages/server/src/commands/agent-context.ts`
+- Modify: `packages/server/src/commands/agent-instructions.ts`
+- Modify: `packages/server/src/commands/skills.ts`
+- Modify: `packages/server/src/commands/skills/*.ts`
+- Modify: `packages/server/src/commands/supervisor.ts`
+- Modify: `packages/server/src/commands/session-metadata.ts`
+- Modify: `packages/server/src/commands/session-review.ts`
+- Modify: `packages/server/src/commands/work-analysis.ts`
+- Modify: `packages/server/src/commands/fencing.ts`
+- Modify: `packages/server/src/commands/automation.ts`
+- Modify: `packages/server/src/commands/activation.ts`
+- Modify: `packages/server/src/commands/connection.ts`
+- Modify: `packages/server/src/commands/memory.ts`
+- Modify: `packages/server/src/commands/monitoring.ts`
+- Modify: `packages/server/src/commands/updates.ts`
+- Modify: `packages/server/src/commands/ui-actions.ts`
+- Modify: `packages/server/src/commands/workspace-activity.ts`
+- Modify: `packages/server/src/ws/hub.ts`
+- Modify: `packages/server/src/monitoring/service.ts`
+- Modify: `packages/server/src/__tests__/skills/commands.test.ts`
+- Modify: `packages/server/src/__tests__/agent-context-command.test.ts`
+- Modify: `packages/server/src/__tests__/agent-instructions-command.test.ts`
+- Modify: `packages/server/src/__tests__/session-analysis-commands.test.ts`
+- Modify: `packages/server/src/__tests__/session-review-command.test.ts`
+- Modify: `packages/server/src/__tests__/supervisor-commands.test.ts`
+- Modify: `packages/server/src/__tests__/work-analysis-commands.test.ts`
+- Modify: `packages/server/src/__tests__/ws-hub.test.ts`
+- Modify: `packages/server/src/__tests__/monitoring/service.test.ts`
+- Modify: `packages/server/src/__tests__/server-memory-wiring.test.ts`
+
+- [ ] **Step 1: Write the failing projection and batch-3 migration tests**
+
+Add a `WsHub` resync assertion in `packages/server/src/__tests__/ws-hub.test.ts` that expects resync to send sessions from the binding store rather than a runtime manager mock.
+
+Add a monitoring assertion in `packages/server/src/__tests__/monitoring/service.test.ts` that uses only projected sessions/terminals.
+
+Add one runtime registration assertion to a representative skills test:
+
+```ts
+expect(sendCommand).toHaveBeenCalledWith("skills.library.list", {}, undefined);
+```
+
+and one agent-instructions assertion that still calls:
+
+```ts
+expect(sendCommand).toHaveBeenCalledWith(
+  "agentInstructions.generateAndWriteByAgent",
+  { workspaceId },
+  expect.anything()
+);
+```
+
+- [ ] **Step 2: Run the batch-3 and host-consumer tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/commands.test.ts src/__tests__/agent-context-command.test.ts src/__tests__/agent-instructions-command.test.ts src/__tests__/session-analysis-commands.test.ts src/__tests__/session-review-command.test.ts src/__tests__/supervisor-commands.test.ts src/__tests__/work-analysis-commands.test.ts src/__tests__/ws-hub.test.ts src/__tests__/monitoring/service.test.ts src/__tests__/server-memory-wiring.test.ts
+```
+
+Expected: FAIL because these command modules still import the old registration API and `WsHub` / `MonitoringService` still read directly from runtime managers.
+
+- [ ] **Step 3: Migrate batch-3 runtime commands and make final host services read projections**
+
+Move these command groups to `registerRuntimeCommand()`:
+
+- `agent-context.*`
+- `agentInstructions.*`
+- `skills.*`
+- `session.analysis.*`
+- `session.review.*`
+- `work.analysis.*`
+- `supervisor.*`
+
+Use `{ kind: "default" }` for runtime-global compatibility flows in Phase 1:
+
+- `skills.library.list`
+- `skills.search`
+- `skills.versions.check`
+- `skills.install.*`
+- `skills.health.scan`
+- `skills.targets.list`
+- `skills.files.*`
+- `supervisor.*` ops that only carry `supervisorId`
+
+Use workspace routing where the wire format already has it:
+
+- `skills.recommend`
+- `agentInstructions.generateAndWriteByAgent`
+- `agentInstructions.status`
+- `agent-context.package`
+- `work.analysis.*` when `workspaceId` is present
+
+Keep these commands host-only and switch them to `registerHostCommand()`:
+
+- `automation.*`
+- `activation.*`
+- `connection.probe`
+- `memory.*`
+- `monitoring.*`
+- `updates.*`
+- `uiAction.*`
+- `workspace.activate`
+- `workspace.deactivate`
+- `workspace.lastViewedTarget.*`
+- `workspace.history.*`
+- `fencing.*`
+
+Then update host consumers:
+
+In `packages/server/src/ws/hub.ts`, replace direct resync reads from `sessionMgr` with the binding store:
+
+```ts
+const workspaces = commandContext.workspaceMgr.list();
+for (const workspace of workspaces) {
+  const sessions = commandContext.runtimeBindings.listSessionsForWorkspace(workspace.id);
+  for (const session of sessions) {
+    // existing topic fan-out
+  }
+}
+```
+
+In `packages/server/src/monitoring/service.ts`, inject projection access instead of runtime managers:
+
+```ts
+sessionStore: {
+  getAll(): Session[];
+  findSessionIdByTerminal(terminalId: string): string | undefined;
+}
+terminalStore: {
+  getAll(): Terminal[];
+}
+```
+
+Back them with `WorkspaceRuntimeBindingStore`.
+
+Also update `UpdateService` count lambdas in `server.ts` to use projections instead of direct `sessionMgr` / `terminalMgr` reads, so runtime extraction does not leave host services peeking back into runtime managers.
+
+Finish by removing any remaining command-file imports of the legacy `registerCommand()` helper.
+
+- [ ] **Step 4: Run the batch-3 and host-consumer tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/commands.test.ts src/__tests__/agent-context-command.test.ts src/__tests__/agent-instructions-command.test.ts src/__tests__/session-analysis-commands.test.ts src/__tests__/session-review-command.test.ts src/__tests__/supervisor-commands.test.ts src/__tests__/work-analysis-commands.test.ts src/__tests__/ws-hub.test.ts src/__tests__/monitoring/service.test.ts src/__tests__/server-memory-wiring.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/commands/agent-context.ts packages/server/src/commands/agent-instructions.ts packages/server/src/commands/skills.ts packages/server/src/commands/skills packages/server/src/commands/supervisor.ts packages/server/src/commands/session-metadata.ts packages/server/src/commands/session-review.ts packages/server/src/commands/work-analysis.ts packages/server/src/commands/fencing.ts packages/server/src/commands/automation.ts packages/server/src/commands/activation.ts packages/server/src/commands/connection.ts packages/server/src/commands/memory.ts packages/server/src/commands/monitoring.ts packages/server/src/commands/updates.ts packages/server/src/commands/ui-actions.ts packages/server/src/commands/workspace-activity.ts packages/server/src/ws/hub.ts packages/server/src/monitoring/service.ts packages/server/src/__tests__/skills/commands.test.ts packages/server/src/__tests__/agent-context-command.test.ts packages/server/src/__tests__/agent-instructions-command.test.ts packages/server/src/__tests__/session-analysis-commands.test.ts packages/server/src/__tests__/session-review-command.test.ts packages/server/src/__tests__/supervisor-commands.test.ts packages/server/src/__tests__/work-analysis-commands.test.ts packages/server/src/__tests__/ws-hub.test.ts packages/server/src/__tests__/monitoring/service.test.ts packages/server/src/__tests__/server-memory-wiring.test.ts
+git commit -m "refactor: finish runtime command migration and host projections"
+```
+
+### Task 10: Final Verification And Cleanup
+
+**Files:**
+- Modify as needed based on failing verification output from Tasks 1-9
+
+- [ ] **Step 1: Run the targeted server suites**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/host-command-registry.test.ts src/__tests__/runtime-command-registry.test.ts src/__tests__/runtime-router.test.ts src/__tests__/workspace-runtime-binding.test.ts src/__tests__/workspace/manager.test.ts src/__tests__/workspace/manager-on-close.test.ts src/__tests__/workspace-commands.test.ts src/__tests__/runtime/native-runtime.test.ts src/__tests__/server-builtin-skills-wiring.test.ts src/__tests__/server-lsp-runtime-mode-hydration.test.ts src/__tests__/server-runtime-config.test.ts src/__tests__/dispatch.test.ts src/__tests__/session-commands.test.ts src/__tests__/terminal-commands.test.ts src/__tests__/file-commands.test.ts src/__tests__/git-commands.test.ts src/__tests__/task-commands.test.ts src/__tests__/lsp-commands.test.ts src/__tests__/worktree-commands.test.ts src/commands/settings.test.ts src/__tests__/diagnostics-commands.test.ts src/__tests__/provider-runtime/runtime-status.test.ts src/__tests__/provider-runtime/install-manager.test.ts src/__tests__/system-deps/commands.test.ts src/__tests__/skills/commands.test.ts src/__tests__/agent-context-command.test.ts src/__tests__/agent-instructions-command.test.ts src/__tests__/session-analysis-commands.test.ts src/__tests__/session-review-command.test.ts src/__tests__/supervisor-commands.test.ts src/__tests__/work-analysis-commands.test.ts src/__tests__/ws-hub.test.ts src/__tests__/monitoring/service.test.ts src/__tests__/server-memory-wiring.test.ts src/__tests__/server-provider-install-wiring.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 2: Run repository-level verification**
+
+Run:
+
+```bash
+pnpm ci:verify
+```
+
+Expected: PASS
+
+- [ ] **Step 3: Fix only the failing areas if verification reveals drift**
+
+If a failure points back to an old host/runtime leak, fix it in the smallest possible place rather than adding another compatibility shim. Typical final fixes should be in:
+
+```ts
+// packages/server/src/ws/dispatch.ts
+// packages/server/src/ws/hub.ts
+// packages/server/src/server.ts
+// packages/server/src/commands/settings.ts
+// packages/server/src/host/workspace-runtime-binding.ts
+```
+
+- [ ] **Step 4: Re-run the failing verification command(s) until green**
+
+Run only the commands that failed in Steps 1-2, then re-run:
+
+```bash
+pnpm ci:verify
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src
+git commit -m "refactor: complete runtime extraction phase one"
+```
+
+## Self-Review
+
+**Spec coverage:** This plan covers the spec’s required host/runtime context split, command registry split, in-process `NativeRuntimeHandle`, runtime assembly extraction, workspace/runtime binding, command migration in batches, host-controlled HTTP/WS transport, skills/runtime ownership, and preservation of the host callback model. It also adds the repo-grounded gaps discovered during code review: runtime-global compatibility routing for no-`workspaceId` commands, settings/provider-config bridging, `WsHub.resync` projections, update-service counting, monitoring projections, and `SessionMetadataRepo` workspace lookup decoupling.
+
+**Placeholder scan:** No `TBD`, `TODO`, or “implement later” placeholders remain. The compatibility behavior for runtime-global commands is explicit rather than implicit.
+
+**Type consistency:** The plan uses one route-target vocabulary everywhere: `workspace`, `session`, `terminal`, and `default`. Host dispatch uses `HostCommandContext`; runtime execution uses `RuntimeCommandContext`; runtime execution metadata uses `RuntimeExecuteMeta`; runtime access goes through `RuntimeRouter` and `RuntimeHandle`.
+
+Plan complete and saved to `docs/superpowers/plans/2026-06-21-runtime-extraction-phase1-implementation.md`. Two execution options:
+
+**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
+
+**2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
+
+**Which approach?**
diff --git a/docs/superpowers/plans/2026-06-21-skill-recommendations-pagination.md b/docs/superpowers/plans/2026-06-21-skill-recommendations-pagination.md
new file mode 100644
index 000000000..8427abcc0
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-21-skill-recommendations-pagination.md
@@ -0,0 +1,830 @@
+# Skill Recommendations Pagination Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add true paginated skill recommendations with a default first page of 20 results and automatic next-page loading when the recommendations footer enters the workspace sidebar scroll viewport.
+
+**Architecture:** Extend the shared skill recommendation contract to return a paginated page object, update the server recommendation command to slice a fully ranked recommendation set by `offset` and `limit`, and teach the web skills panel to manage first-page and next-page loading separately while observing a bottom sentinel inside the existing sidebar scroll container.
+
+**Tech Stack:** TypeScript, Zod, React 19, Jotai, Vitest, Testing Library
+
+---
+
+### Task 1: Add Shared Recommendation Page Types
+
+**Files:**
+- Modify: `packages/core/src/domain/skill-management.ts`
+- Modify: `packages/core/src/domain/skill-management.test.ts`
+- Test: `packages/core/src/domain/skill-management.test.ts`
+
+- [ ] **Step 1: Write the failing shared-type test**
+
+Add a new shape assertion beside the existing recommendation entry test:
+
+```ts
+  it("exports a stable skill recommendation page shape", () => {
+    const page: SkillRecommendationPage = {
+      entries: [
+        {
+          slug: "code-review",
+          displayName: "Code Review",
+          description: "Reviews code changes",
+          reason: "Matches the workspace test workflow",
+          sourceQuery: "test workflow",
+          score: 42,
+          installed: false,
+        },
+      ],
+      hasMore: true,
+    };
+
+    expect(page.entries[0]?.slug).toBe("code-review");
+    expect(page.hasMore).toBe(true);
+  });
+```
+
+- [ ] **Step 2: Run the core test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/core test -- packages/core/src/domain/skill-management.test.ts`
+
+Expected: FAIL because `SkillRecommendationPage` does not exist yet.
+
+- [ ] **Step 3: Add the minimal shared type**
+
+Update `packages/core/src/domain/skill-management.ts` with:
+
+```ts
+export interface SkillRecommendationPage {
+  entries: SkillRecommendationEntry[];
+  hasMore: boolean;
+}
+```
+
+Place it immediately after `SkillRecommendationEntry` so the related contract stays grouped.
+
+- [ ] **Step 4: Run the core test to verify it passes**
+
+Run: `pnpm --filter @coder-studio/core test -- packages/core/src/domain/skill-management.test.ts`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/core/src/domain/skill-management.ts packages/core/src/domain/skill-management.test.ts
+git commit -m "test: add shared skill recommendation page contract"
+```
+
+### Task 2: Add Server Pagination Contract and Command Behavior
+
+**Files:**
+- Modify: `packages/server/src/commands/skills/query.ts`
+- Modify: `packages/server/src/skills/recommendation.ts`
+- Modify: `packages/server/src/__tests__/skills/commands.test.ts`
+- Test: `packages/server/src/__tests__/skills/commands.test.ts`
+
+- [ ] **Step 1: Write the failing server pagination test**
+
+Replace the existing recommend assertion in `packages/server/src/__tests__/skills/commands.test.ts` with a page-shaped expectation and add a second pagination test. Use concrete data so the command behavior is explicit:
+
+```ts
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual({
+        entries: [
+          expect.objectContaining({
+            slug: "vite-testing",
+            installed: false,
+            reason: expect.any(String),
+            sourceQuery: expect.any(String),
+          }),
+        ],
+        hasMore: false,
+      });
+```
+
+Add a new test for offset slicing:
+
+```ts
+  it("returns paginated recommendations with hasMore", async () => {
+    const workspaceRoot = await mkdtemp(join(tmpdir(), "skills-recommend-page-"));
+    try {
+      await writeFile(
+        join(workspaceRoot, "package.json"),
+        JSON.stringify(
+          {
+            dependencies: { react: "^19.0.0" },
+            scripts: { test: "vitest run" },
+          },
+          null,
+          2
+        )
+      );
+
+      const ctx = createBaseContext({
+        workspaceMgr: {
+          get: vi.fn(() => ({ id: "ws-1", path: workspaceRoot })),
+        } as never,
+        skillLibraryRepo: { get: vi.fn(() => undefined) } as never,
+        skillMountRepo: { listBySkillSlug: vi.fn(() => []) } as never,
+        skillsHubClient: {
+          search: vi.fn(async (query: string) =>
+            query.includes("React")
+              ? [
+                  { slug: "skill-a", displayName: "Skill A", description: "A" },
+                  { slug: "skill-b", displayName: "Skill B", description: "B" },
+                  { slug: "skill-c", displayName: "Skill C", description: "C" },
+                ]
+              : []
+          ),
+        } as never,
+      });
+
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "skills-recommend-page-1",
+          op: "skills.recommend",
+          args: { workspaceId: "ws-1", limit: 2, offset: 1 },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual({
+        entries: [
+          expect.objectContaining({ slug: "skill-b" }),
+          expect.objectContaining({ slug: "skill-c" }),
+        ],
+        hasMore: false,
+      });
+    } finally {
+      await rm(workspaceRoot, { recursive: true, force: true });
+    }
+  });
+```
+
+- [ ] **Step 2: Run the server test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/server test -- packages/server/src/__tests__/skills/commands.test.ts`
+
+Expected: FAIL because `skills.recommend` still returns an array and does not accept `offset`.
+
+- [ ] **Step 3: Add paginated recommendation builder output**
+
+Refactor `packages/server/src/skills/recommendation.ts` minimally:
+
+1. Introduce a new default page size constant:
+
+```ts
+const DEFAULT_RECOMMENDATION_LIMIT = 20;
+```
+
+2. Split the current builder into:
+
+```ts
+export async function buildSkillRecommendationEntries(input: {
+  intelligence: WorkspaceIntelligenceSummary;
+  search: (query: string) => Promise<SkillRecommendationSearchResult[]>;
+  isInstalled: (slug: string) => boolean;
+}): Promise<SkillRecommendationEntry[]> { ... }
+
+export async function buildSkillRecommendations(input: {
+  intelligence: WorkspaceIntelligenceSummary;
+  search: (query: string) => Promise<SkillRecommendationSearchResult[]>;
+  isInstalled: (slug: string) => boolean;
+  limit?: number;
+  offset?: number;
+}): Promise<SkillRecommendationPage> {
+  const entries = await buildSkillRecommendationEntries(input);
+  const offset = input.offset ?? 0;
+  const limit = input.limit ?? DEFAULT_RECOMMENDATION_LIMIT;
+  const pageEntries = entries.slice(offset, offset + limit);
+
+  return {
+    entries: pageEntries,
+    hasMore: offset + pageEntries.length < entries.length,
+  };
+}
+```
+
+3. Keep the current sort and score logic inside `buildSkillRecommendationEntries()` unchanged.
+
+- [ ] **Step 4: Update the command schema and return shape**
+
+Update `packages/server/src/commands/skills/query.ts`:
+
+```ts
+    z.object({
+      workspaceId: z.string().trim().min(1),
+      limit: z.number().int().positive().max(20).optional(),
+      offset: z.number().int().min(0).optional(),
+    }),
+```
+
+and pass both values through:
+
+```ts
+      return buildSkillRecommendations({
+        intelligence,
+        search: (query) => ctx.skillsHubClient.search(query),
+        isInstalled: (slug) => Boolean(ctx.skillLibraryRepo.get(slug)),
+        limit: args.limit,
+        offset: args.offset,
+      });
+```
+
+- [ ] **Step 5: Run the server test to verify it passes**
+
+Run: `pnpm --filter @coder-studio/server test -- packages/server/src/__tests__/skills/commands.test.ts`
+
+Expected: PASS with page-shaped `skills.recommend` responses.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/server/src/commands/skills/query.ts packages/server/src/skills/recommendation.ts packages/server/src/__tests__/skills/commands.test.ts
+git commit -m "feat: paginate skill recommendations on the server"
+```
+
+### Task 3: Update Preview Store and Consumer Types for Paginated Recommendations
+
+**Files:**
+- Modify: `packages/web/src/ui-preview/preview-store.ts`
+- Modify: `packages/web/src/features/workspace/actions/use-skills-panel.ts`
+- Test: `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+- [ ] **Step 1: Write the failing web request-shape test**
+
+Update the existing expectations in `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx` so the first recommendation request expects pagination args:
+
+```ts
+    expect(sendCommand).toHaveBeenCalledWith(
+      "skills.recommend",
+      { workspaceId: "ws-1", limit: 20, offset: 0 },
+      undefined
+    );
+```
+
+Also change the mock result shape used by recommendation tests to:
+
+```ts
+      if (op === "skills.recommend") {
+        return {
+          entries: [
+            {
+              slug: "vite-testing",
+              displayName: "Vite Testing",
+              description: "Testing Vite apps with a description long enough that it should be constrained to a single visible line.",
+              reason: "Matches Vite and test scripts with a reason long enough that it should use the same one-line presentation.",
+              sourceQuery: "Vite",
+              score: 10,
+              installed: false,
+            },
+          ],
+          hasMore: false,
+        };
+      }
+```
+
+- [ ] **Step 2: Run the web test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/web test -- packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+Expected: FAIL because the panel still requests `{ workspaceId }` and expects an array result.
+
+- [ ] **Step 3: Add the paginated preview command shape**
+
+Update `packages/web/src/ui-preview/preview-store.ts` imports and command typing:
+
+```ts
+  SkillRecommendationPage,
+```
+
+```ts
+  skillsRecommendations?: SkillRecommendationPage;
+```
+
+Update the command handler:
+
+```ts
+    if (op === "skills.recommend") {
+      return ok(
+        (commands.skillsRecommendations ?? { entries: [], hasMore: false }) as unknown as T
+      );
+    }
+```
+
+This keeps preview mode compatible after the shared contract changes.
+
+- [ ] **Step 4: Update `useSkillsPanel` to request the first page contract**
+
+At the top of `packages/web/src/features/workspace/actions/use-skills-panel.ts`, switch the recommendation import to:
+
+```ts
+  type SkillRecommendationEntry,
+  type SkillRecommendationPage,
+```
+
+Then update the first-page fetch path in `refreshRecommendations()` to:
+
+```ts
+    const result = await dispatch<SkillRecommendationPage>("skills.recommend", {
+      workspaceId,
+      limit: 20,
+      offset: 0,
+    });
+```
+
+and set:
+
+```ts
+    setRecommendations(result.data.entries);
+```
+
+This step only handles the first-page contract change; next-page behavior is added in Task 4.
+
+- [ ] **Step 5: Run the web test to verify it passes**
+
+Run: `pnpm --filter @coder-studio/web test -- packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+Expected: PASS for the updated request and paginated first-page handling.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/web/src/ui-preview/preview-store.ts packages/web/src/features/workspace/actions/use-skills-panel.ts packages/web/src/features/workspace/views/shared/skills-panel.test.tsx
+git commit -m "refactor: consume paginated skill recommendation responses"
+```
+
+### Task 4: Add Recommendation Pagination State and Refresh Semantics
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/actions/use-skills-panel.ts`
+- Modify: `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+- Test: `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+- [ ] **Step 1: Write the failing refresh and append tests**
+
+Add two tests to `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`.
+
+First, append behavior with duplicate filtering:
+
+```ts
+  it("appends the next recommendation page without duplicating slugs", async () => {
+    const originalIntersectionObserver = global.IntersectionObserver;
+    const instances: Array<{ callback: IntersectionObserverCallback }> = [];
+
+    class IntersectionObserverMock {
+      readonly observe = vi.fn();
+      readonly unobserve = vi.fn();
+      readonly disconnect = vi.fn();
+
+      constructor(callback: IntersectionObserverCallback) {
+        instances.push({ callback });
+      }
+
+      takeRecords(): IntersectionObserverEntry[] {
+        return [];
+      }
+    }
+
+    global.IntersectionObserver =
+      IntersectionObserverMock as unknown as typeof IntersectionObserver;
+
+    const sendCommand = vi
+      .fn()
+      .mockImplementationOnce(async (op: string) => {
+        if (op === "skills.library.list") return [];
+        if (op === "skills.health.scan") return { targets: [], mounts: [] };
+        if (op === "skills.recommend") {
+          return {
+            entries: Array.from({ length: 20 }, (_, index) => ({
+              slug: `skill-${index + 1}`,
+              displayName: `Skill ${index + 1}`,
+              reason: "reason",
+              sourceQuery: "React",
+              score: 100 - index,
+              installed: false,
+            })),
+            hasMore: true,
+          };
+        }
+        return [];
+      })
+      .mockImplementationOnce(async (op: string, args?: { offset?: number }) => {
+        if (op === "skills.recommend") {
+          expect(args).toMatchObject({ workspaceId: "ws-1", limit: 20, offset: 20 });
+          return {
+            entries: [
+              {
+                slug: "skill-20",
+                displayName: "Skill 20",
+                reason: "reason",
+                sourceQuery: "React",
+                score: 80,
+                installed: false,
+              },
+              {
+                slug: "skill-21",
+                displayName: "Skill 21",
+                reason: "reason",
+                sourceQuery: "React",
+                score: 79,
+                installed: false,
+              },
+            ],
+            hasMore: false,
+          };
+        }
+        if (op === "skills.library.list") return [];
+        if (op === "skills.health.scan") return { targets: [], mounts: [] };
+        return [];
+      });
+
+    renderPanel(sendCommand);
+    await screen.findByText("Skill 20");
+
+    await waitFor(() => expect(instances.length).toBeGreaterThan(0));
+    await waitFor(() => {
+      instances[0]?.callback(
+        [{ isIntersecting: true } as IntersectionObserverEntry],
+        {} as IntersectionObserver
+      );
+      expect(screen.getByText("Skill 21")).toBeInTheDocument();
+    });
+
+    expect(screen.getAllByText("Skill 20")).toHaveLength(1);
+    global.IntersectionObserver = originalIntersectionObserver;
+  });
+```
+
+Second, refresh reset behavior:
+
+```ts
+  it("reloads recommendations from the first page when the panel refresh token changes", async () => {
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") return [];
+      if (op === "skills.health.scan") return { targets: [], mounts: [] };
+      if (op === "skills.recommend") {
+        return { entries: [], hasMore: false };
+      }
+      return [];
+    });
+
+    const { rerender, store } = renderPanelWithProps(sendCommand, 0);
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.recommend",
+        { workspaceId: "ws-1", limit: 20, offset: 0 },
+        undefined
+      );
+    });
+
+    rerender(
+      <Provider store={store}>
+        <SkillsPanel workspaceId="ws-1" refreshToken={1} />
+      </Provider>
+    );
+
+    await waitFor(() => {
+      expect(
+        sendCommand.mock.calls.filter(
+          ([op, args]) =>
+            op === "skills.recommend" &&
+            args?.workspaceId === "ws-1" &&
+            args?.limit === 20 &&
+            args?.offset === 0
+        ).length
+      ).toBeGreaterThan(1);
+    });
+  });
+```
+
+- [ ] **Step 2: Run the web test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/web test -- packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+Expected: FAIL because there is no next-page loader, no duplicate filtering, and no separate page state.
+
+- [ ] **Step 3: Add pagination state and helpers to `useSkillsPanel`**
+
+Extend the hook state in `packages/web/src/features/workspace/actions/use-skills-panel.ts`:
+
+```ts
+  const [recommendationsHasMore, setRecommendationsHasMore] = useState(false);
+  const [loadingRecommendationPage, setLoadingRecommendationPage] = useState(false);
+  const recommendationPageLoadingRef = useRef(false);
+```
+
+Add constants near the imports or top of the module:
+
+```ts
+const RECOMMENDATIONS_PAGE_SIZE = 20;
+```
+
+Add a helper for dedupe:
+
+```ts
+function appendUniqueRecommendations(
+  current: SkillRecommendationEntry[],
+  incoming: SkillRecommendationEntry[]
+) {
+  const seen = new Set(current.map((entry) => entry.slug));
+  const appended = incoming.filter((entry) => !seen.has(entry.slug));
+  return appended.length > 0 ? [...current, ...appended] : current;
+}
+```
+
+- [ ] **Step 4: Implement `refreshRecommendations()` and `loadMoreRecommendations()`**
+
+Update `refreshRecommendations()` to:
+
+```ts
+  const refreshRecommendations = useCallback(async () => {
+    recommendationPageLoadingRef.current = false;
+    setLoadingRecommendationPage(false);
+    setLoadingRecommendations(true);
+    const result = await dispatch<SkillRecommendationPage>("skills.recommend", {
+      workspaceId,
+      limit: RECOMMENDATIONS_PAGE_SIZE,
+      offset: 0,
+    });
+    setLoadingRecommendations(false);
+    if (!result.ok || !result.data) {
+      setErrorMessage(result.error?.message ?? "Failed to load skill recommendations");
+      return;
+    }
+
+    setRecommendations(result.data.entries);
+    setRecommendationsHasMore(result.data.hasMore);
+    setErrorMessage(null);
+  }, [dispatch, workspaceId]);
+```
+
+Add:
+
+```ts
+  const loadMoreRecommendations = useCallback(async () => {
+    if (
+      loadingRecommendations ||
+      recommendationPageLoadingRef.current ||
+      !recommendationsHasMore ||
+      panelState.recommendationsCollapsed
+    ) {
+      return;
+    }
+
+    recommendationPageLoadingRef.current = true;
+    setLoadingRecommendationPage(true);
+    const result = await dispatch<SkillRecommendationPage>("skills.recommend", {
+      workspaceId,
+      limit: RECOMMENDATIONS_PAGE_SIZE,
+      offset: recommendations.length,
+    });
+    recommendationPageLoadingRef.current = false;
+    setLoadingRecommendationPage(false);
+
+    if (!result.ok || !result.data) {
+      setErrorMessage(result.error?.message ?? "Failed to load skill recommendations");
+      return;
+    }
+
+    setRecommendations((current) => appendUniqueRecommendations(current, result.data.entries));
+    setRecommendationsHasMore(result.data.hasMore);
+    setErrorMessage(null);
+  }, [
+    dispatch,
+    loadingRecommendations,
+    panelState.recommendationsCollapsed,
+    recommendations.length,
+    recommendationsHasMore,
+    workspaceId,
+  ]);
+```
+
+Export `loadMoreRecommendations`, `loadingRecommendationPage`, and `recommendationsHasMore` from the hook return object.
+
+- [ ] **Step 5: Re-run the web test to verify it passes**
+
+Run: `pnpm --filter @coder-studio/web test -- packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+Expected: PASS for refreshed first-page requests and duplicate-safe append behavior.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/web/src/features/workspace/actions/use-skills-panel.ts packages/web/src/features/workspace/views/shared/skills-panel.test.tsx
+git commit -m "feat: add paginated recommendation state to skills panel"
+```
+
+### Task 5: Add Recommendation Sentinel Observation in the Skills Panel View
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/views/shared/skills-panel.tsx`
+- Modify: `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+- Test: `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+- [ ] **Step 1: Write the failing observer lifecycle tests**
+
+Extend `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx` with:
+
+1. A test that verifies the observer is not used while recommendations are collapsed.
+2. A test that verifies next-page loading text renders only at the list footer when `hasMore` and the page load are active.
+
+Use the existing `GitPanel` pattern to stub `IntersectionObserver`. Example collapsed-state test:
+
+```ts
+  it("does not observe the recommendation sentinel while recommendations are collapsed", async () => {
+    const observe = vi.fn();
+    class IntersectionObserverMock {
+      readonly unobserve = vi.fn();
+      readonly disconnect = vi.fn();
+
+      constructor() {}
+
+      observe = observe;
+
+      takeRecords(): IntersectionObserverEntry[] {
+        return [];
+      }
+    }
+
+    const originalIntersectionObserver = global.IntersectionObserver;
+    global.IntersectionObserver =
+      IntersectionObserverMock as unknown as typeof IntersectionObserver;
+
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") return [];
+      if (op === "skills.health.scan") return { targets: [], mounts: [] };
+      if (op === "skills.recommend") {
+        return {
+          entries: [{ slug: "skill-1", displayName: "Skill 1", reason: "reason", sourceQuery: "React", score: 1, installed: false }],
+          hasMore: true,
+        };
+      }
+      return [];
+    });
+
+    renderPanel(sendCommand);
+    const toggle = await screen.findByRole("button", { name: "Collapse Recommendations" });
+    fireEvent.click(toggle);
+
+    await waitFor(() => expect(observe).not.toHaveBeenCalled());
+    global.IntersectionObserver = originalIntersectionObserver;
+  });
+```
+
+- [ ] **Step 2: Run the web test to verify it fails**
+
+Run: `pnpm --filter @coder-studio/web test -- packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+Expected: FAIL because the panel view has no sentinel, no observer wiring, and no footer loading state.
+
+- [ ] **Step 3: Add sentinel refs and observer effect to `skills-panel.tsx`**
+
+At the top of the component, extend the hook destructuring:
+
+```ts
+    loadingRecommendationPage,
+    loadMoreRecommendations,
+    recommendationsHasMore,
+```
+
+Add refs:
+
+```ts
+  const recommendationsLoadSentinelRef = useRef<HTMLDivElement | null>(null);
+  const recommendationsScrollRootRef = useRef<HTMLDivElement | null>(null);
+```
+
+Attach the scroll root ref to the existing sidebar body:
+
+```tsx
+        <div
+          ref={recommendationsScrollRootRef}
+          className="workspace-sidebar-panel__body workspace-sidebar-panel__body--stacked skills-panel__body"
+        >
+```
+
+Add an effect modeled after `git-panel.tsx`:
+
+```ts
+  useEffect(() => {
+    if (
+      panelState.recommendationsCollapsed ||
+      !recommendationsHasMore ||
+      typeof IntersectionObserver === "undefined"
+    ) {
+      return;
+    }
+
+    const root = recommendationsScrollRootRef.current;
+    const sentinel = recommendationsLoadSentinelRef.current;
+    if (!root || !sentinel) {
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          void loadMoreRecommendations();
+        }
+      },
+      {
+        root,
+        rootMargin: "120px 0px",
+        threshold: 0,
+      }
+    );
+
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, [
+    loadMoreRecommendations,
+    panelState.recommendationsCollapsed,
+    recommendationsHasMore,
+  ]);
+```
+
+- [ ] **Step 4: Render the sentinel and footer loading state**
+
+Inside the recommendations section render path, append after the mapped cards:
+
+```tsx
+                  <>
+                    {sortedRecommendations.map((item) => (
+                      <article
+                        key={item.slug}
+                        className="skills-panel__list-item skills-panel__list-item--recommendation workspace-sidebar-row"
+                      >
+                        ...
+                      </article>
+                    ))}
+                    {loadingRecommendationPage ? (
+                      <p className="workspace-search-panel__state">{t("common.loading")}</p>
+                    ) : null}
+                    {recommendationsHasMore ? (
+                      <div
+                        ref={recommendationsLoadSentinelRef}
+                        data-testid="skills-recommendations-sentinel"
+                        aria-hidden="true"
+                      />
+                    ) : null}
+                  </>
+```
+
+Keep the first-page empty/loading branches unchanged.
+
+- [ ] **Step 5: Run the web test to verify it passes**
+
+Run: `pnpm --filter @coder-studio/web test -- packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+Expected: PASS with observer-based next-page loading and collapsed-state guard behavior.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/web/src/features/workspace/views/shared/skills-panel.tsx packages/web/src/features/workspace/views/shared/skills-panel.test.tsx
+git commit -m "feat: load more skill recommendations on scroll"
+```
+
+### Task 6: Full Regression Verification
+
+**Files:**
+- Modify: none
+- Test: `packages/core/src/domain/skill-management.test.ts`
+- Test: `packages/server/src/__tests__/skills/commands.test.ts`
+- Test: `packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+- [ ] **Step 1: Run the focused core test suite**
+
+Run: `pnpm --filter @coder-studio/core test -- packages/core/src/domain/skill-management.test.ts`
+
+Expected: PASS.
+
+- [ ] **Step 2: Run the focused server test suite**
+
+Run: `pnpm --filter @coder-studio/server test -- packages/server/src/__tests__/skills/commands.test.ts`
+
+Expected: PASS.
+
+- [ ] **Step 3: Run the focused web test suite**
+
+Run: `pnpm --filter @coder-studio/web test -- packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`
+
+Expected: PASS.
+
+- [ ] **Step 4: Run repository verification if time and scope allow**
+
+Run: `pnpm ci:test`
+
+Expected: PASS, or document any unrelated failures precisely before handoff.
+
+- [ ] **Step 5: Commit verification-state updates only if needed**
+
+```bash
+git status --short
+```
+
+Expected: no uncommitted changes after verification. Do not create an extra commit if verification produced no file changes.
diff --git a/docs/superpowers/plans/2026-06-23-builtin-skill-automation-bridge.md b/docs/superpowers/plans/2026-06-23-builtin-skill-automation-bridge.md
new file mode 100644
index 000000000..dbba0bbc2
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-23-builtin-skill-automation-bridge.md
@@ -0,0 +1,1046 @@
+# Built-in Skill Automation Bridge Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace PATH-based built-in skill automation with mounted `cmd.mjs` bridges that execute against the exact session runtime through an injected internal automation entry.
+
+**Architecture:** Keep the existing websocket command bus and backend ops such as `memory.create`, `canvas.create`, and `uiAction.dispatch`. Add a dedicated internal CLI entry for dotted automation ops, ship a shared `cmd.mjs` bridge with built-in automation skills, force rendered copy mounts for those skills, and inject a resolved `CODER_STUDIO_AUTOMATION_ENTRY` into agent sessions so mounted skills never depend on global `coder-studio` resolution.
+
+**Tech Stack:** TypeScript, Node.js ESM, Vitest, existing `@spencer-kit/coder-studio` CLI package, existing `@coder-studio/server` skill/session managers, websocket automation client.
+
+**Spec reference:** `docs/superpowers/specs/2026-06-23-builtin-skill-automation-bridge-design.md`
+
+**Git hygiene:** The worktree already contains unrelated edits in `packages/cli`, `packages/core`, and `packages/server`. Read those files before patching, stage only the files for the current task, and never revert unrelated user changes.
+
+---
+
+## File Structure
+
+**New files:**
+- `packages/cli/src/automation-entry.ts` — internal session-scoped automation entry that accepts dotted ops like `memory.create` and forwards them through the existing websocket command client
+- `packages/cli/src/automation-entry.test.ts` — parser and dispatch coverage for the internal automation entry
+- `packages/server/src/skills/builtin/automation-bridge.ts` — shared `cmd.mjs` source, render helpers, and automation-mount constants
+- `packages/server/src/__tests__/skills/builtin-automation-bridge.test.ts` — verifies `cmd.mjs` env validation, delegation, and exit-code forwarding
+- `packages/server/src/session/automation-entry-path.ts` — resolves the absolute dev/dist path for the internal automation entry
+- `packages/server/src/__tests__/session-automation-entry-path.test.ts` — dev/dist resolution coverage for the injected automation entry path
+
+**Modified files:**
+- `packages/cli/src/automation-command-client.ts` — add a strict session-scoped resolution mode that refuses global server discovery
+- `packages/cli/src/automation-command-client.test.ts` — cover strict session mode and existing bearer-header behavior
+- `packages/server/src/skills/builtin/definitions/types.ts` — allow built-in skills to declare extra managed files and mount rendering behavior
+- `packages/server/src/skills/builtin/materialize.ts` — materialize `SKILL.md` plus managed files such as `cmd.mjs`
+- `packages/server/src/skills/mount-manager.ts` — support forced-copy mounts plus mounted file overrides for rendered skills
+- `packages/server/src/skills/builtin/sync-manager.ts` — detect automation built-ins and pass render/copy options into the mount manager
+- `packages/server/src/skills/builtin/definitions/coder-studio-memory.ts` — switch examples to `node "<absolute...>/cmd.mjs" memory.*`
+- `packages/server/src/skills/builtin/definitions/coder-studio-open.ts` — switch examples to `node "<absolute...>/cmd.mjs" ui.*`
+- `packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts` — switch examples to `node "<absolute...>/cmd.mjs" canvas.*`
+- `packages/server/src/session/manager.ts` — inject `CODER_STUDIO_AUTOMATION_ENTRY` into agent sessions
+- `packages/server/src/__tests__/skills/builtin-registry.test.ts` — cover managed files and generic library skill content
+- `packages/server/src/__tests__/skills/mount-manager.test.ts` — cover forced-copy rendered mounts
+- `packages/server/src/__tests__/skills/builtin-sync-manager.test.ts` — cover rendered auto-mount behavior
+- `packages/server/src/__tests__/server-builtin-skills-wiring.test.ts` — cover builtin library files, mounted `cmd.mjs`, and target-specific `SKILL.md`
+- `packages/server/src/__tests__/session-integration.test.ts` — cover `CODER_STUDIO_AUTOMATION_ENTRY` session env injection
+
+**Testing commands used in this plan:**
+- `pnpm --filter @spencer-kit/coder-studio exec vitest run src/automation-command-client.test.ts src/automation-entry.test.ts`
+- `pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/builtin-registry.test.ts src/__tests__/skills/builtin-automation-bridge.test.ts`
+- `pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/mount-manager.test.ts src/__tests__/skills/builtin-sync-manager.test.ts src/__tests__/server-builtin-skills-wiring.test.ts`
+- `pnpm --filter @coder-studio/server exec vitest run src/__tests__/session-automation-entry-path.test.ts src/__tests__/session-integration.test.ts`
+- `pnpm ci:verify`
+
+---
+
+### Task 1: Add The Internal Session-Scoped Automation Entry
+
+**Files:**
+- Create: `packages/cli/src/automation-entry.ts`
+- Create: `packages/cli/src/automation-entry.test.ts`
+- Modify: `packages/cli/src/automation-command-client.ts`
+- Modify: `packages/cli/src/automation-command-client.test.ts`
+
+- [ ] **Step 1: Write the failing CLI tests**
+
+Add `packages/cli/src/automation-entry.test.ts` with focused parser/dispatch coverage:
+
+```ts
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { callCoderStudioCommand } = vi.hoisted(() => ({
+  callCoderStudioCommand: vi.fn(),
+}));
+
+vi.mock("./automation-command-client.js", () => ({
+  callCoderStudioCommand,
+}));
+
+import { runAutomationEntry } from "./automation-entry.js";
+
+describe("automation entry", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it("maps memory.create to the existing websocket op shape", async () => {
+    vi.stubEnv("CODER_STUDIO_API_URL", "http://127.0.0.1:4173");
+    vi.stubEnv("CODER_STUDIO_WORKSPACE_ID", "ws-1");
+    callCoderStudioCommand.mockResolvedValueOnce({ id: "mem-1" });
+
+    await runAutomationEntry([
+      "memory.create",
+      "--type",
+      "issue",
+      "--content",
+      "Investigate canvas mount",
+      "--status",
+      "not_started",
+      "--skill",
+      "coder-studio-memory",
+      "--json",
+    ]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: "http://127.0.0.1:4173",
+      op: "memory.create",
+      args: {
+        workspaceId: "ws-1",
+        type: "issue",
+        content: "Investigate canvas mount",
+        status: "not_started",
+        sourceHint: { skillSlug: "coder-studio-memory" },
+      },
+      resolveStrategy: "session",
+    });
+  });
+
+  it("maps ui.open-file to uiAction.dispatch", async () => {
+    vi.stubEnv("CODER_STUDIO_API_URL", "http://127.0.0.1:4173");
+    vi.stubEnv("CODER_STUDIO_WORKSPACE_ID", "ws-1");
+    callCoderStudioCommand.mockResolvedValueOnce({ accepted: true });
+
+    await runAutomationEntry([
+      "ui.open-file",
+      "--path",
+      "packages/server/src/session/manager.ts",
+      "--line",
+      "12",
+      "--column",
+      "3",
+      "--json",
+    ]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: "http://127.0.0.1:4173",
+      op: "uiAction.dispatch",
+      args: {
+        workspaceId: "ws-1",
+        intent: {
+          type: "editor.openFile",
+          path: "packages/server/src/session/manager.ts",
+          line: 12,
+          column: 3,
+        },
+        source: { kind: "agent" },
+      },
+      resolveStrategy: "session",
+    });
+  });
+});
+```
+
+Extend `packages/cli/src/automation-command-client.test.ts` with a failure case:
+
+```ts
+  it("rejects session-scoped calls when api url is unavailable", async () => {
+    vi.stubEnv("CODER_STUDIO_API_URL", "");
+    getServerStatus.mockResolvedValue(null);
+    getBrowserUrl.mockReturnValue(undefined);
+
+    await expect(
+      callCoderStudioCommand({
+        op: "memory.list",
+        args: { workspaceId: "ws-1" },
+        resolveStrategy: "session",
+      })
+    ).rejects.toThrow("CODER_STUDIO_API_URL");
+  });
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio exec vitest run src/automation-command-client.test.ts src/automation-entry.test.ts
+```
+
+Expected: FAIL because `automation-entry.ts` does not exist and the command client still falls back to managed-server discovery.
+
+- [ ] **Step 3: Implement the internal automation entry and strict client mode**
+
+Create `packages/cli/src/automation-entry.ts` with a dedicated entrypoint instead of reusing the public `coder-studio` parser:
+
+```ts
+import { callCoderStudioCommand } from "./automation-command-client.js";
+
+type AutomationOp =
+  | "memory.list"
+  | "memory.search"
+  | "memory.get"
+  | "memory.create"
+  | "memory.update"
+  | "memory.delete"
+  | "canvas.list"
+  | "canvas.create"
+  | "canvas.update"
+  | "canvas.render"
+  | "ui.open-file"
+  | "ui.close-file"
+  | "ui.open-url"
+  | "ui.close-url"
+  | "ui.open-canvas";
+
+function readRequiredEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) {
+    throw new Error(`Coder Studio automation is not available in this session. Missing ${name}.`);
+  }
+  return value;
+}
+
+function parseFlags(argv: string[]): Record<string, string | boolean> {
+  const flags: Record<string, string | boolean> = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token?.startsWith("--")) {
+      throw new Error(`Unknown argument: ${token}`);
+    }
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = next;
+    index += 1;
+  }
+  return flags;
+}
+
+function buildArgs(op: AutomationOp, flags: Record<string, string | boolean>) {
+  const workspaceId = readRequiredEnv("CODER_STUDIO_WORKSPACE_ID");
+  switch (op) {
+    case "memory.create":
+      return {
+        workspaceId,
+        type: String(flags.type),
+        content: String(flags.content),
+        ...(typeof flags.status === "string" ? { status: flags.status } : {}),
+        ...(typeof flags.skill === "string"
+          ? { sourceHint: { skillSlug: flags.skill } }
+          : {}),
+      };
+    case "memory.list":
+      return {
+        workspaceId,
+        ...(typeof flags.type === "string" ? { type: flags.type } : {}),
+        ...(typeof flags.query === "string" ? { query: flags.query } : {}),
+      };
+    case "memory.search":
+      return {
+        workspaceId,
+        query: String(flags.query),
+        ...(typeof flags.type === "string" ? { type: flags.type } : {}),
+      };
+    case "memory.get":
+    case "memory.delete":
+      return { workspaceId, id: String(flags.id) };
+    case "memory.update":
+      return {
+        workspaceId,
+        id: String(flags.id),
+        ...(typeof flags.type === "string" ? { type: flags.type } : {}),
+        ...(typeof flags.content === "string" ? { content: flags.content } : {}),
+        ...(typeof flags.status === "string" ? { status: flags.status } : {}),
+      };
+    case "canvas.list":
+      return { workspaceId };
+    case "canvas.create":
+      return {
+        workspaceId,
+        kind: String(flags.kind),
+        title: String(flags.title),
+        documentJson: String(flags["document-json"]),
+        ...(flags.open === true ? { open: true } : {}),
+      };
+    case "canvas.update":
+      return {
+        workspaceId,
+        canvasId: String(flags.canvas),
+        documentJson: String(flags["document-json"]),
+      };
+    case "canvas.render":
+      return {
+        workspaceId,
+        canvasId: String(flags.canvas),
+      };
+    case "ui.open-file":
+      return {
+        workspaceId,
+        intent: {
+          type: "editor.openFile",
+          path: String(flags.path),
+          ...(typeof flags.line === "string" ? { line: Number(flags.line) } : {}),
+          ...(typeof flags.column === "string" ? { column: Number(flags.column) } : {}),
+        },
+        source: { kind: "agent" as const },
+      };
+    case "ui.close-file":
+      return {
+        workspaceId,
+        intent: {
+          type: "editor.closeFile",
+          path: String(flags.path),
+        },
+        source: { kind: "agent" as const },
+      };
+    case "ui.open-url":
+      return {
+        workspaceId,
+        intent: {
+          type: "browser.openUrl",
+          url: String(flags.url),
+        },
+        source: { kind: "agent" as const },
+      };
+    case "ui.close-url":
+      return {
+        workspaceId,
+        intent: {
+          type: "browser.closeUrl",
+          url: String(flags.url),
+        },
+        source: { kind: "agent" as const },
+      };
+    case "ui.open-canvas":
+      return {
+        workspaceId,
+        intent: {
+          type: "canvas.open",
+          canvasId: String(flags.canvas),
+        },
+        source: { kind: "agent" as const },
+      };
+  }
+}
+
+export async function runAutomationEntry(argv = process.argv.slice(2)): Promise<void> {
+  const [opToken, ...flagTokens] = argv;
+  if (!opToken) {
+    throw new Error("Missing automation op. Expected values like memory.create or ui.open-file.");
+  }
+
+  const op = opToken as AutomationOp;
+  const apiUrl = readRequiredEnv("CODER_STUDIO_API_URL");
+  const flags = parseFlags(flagTokens);
+  const result = await callCoderStudioCommand({
+    apiUrl,
+    op: op.startsWith("ui.") ? "uiAction.dispatch" : op,
+    args: buildArgs(op, flags),
+    resolveStrategy: "session",
+  });
+
+  if (flags.json === true) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(JSON.stringify(result));
+}
+
+if (process.argv[1]?.endsWith("automation-entry.ts") || process.argv[1]?.endsWith("automation-entry.js")) {
+  void runAutomationEntry().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}
+```
+
+Update `packages/cli/src/automation-command-client.ts` to make session-scoped behavior explicit:
+
+```ts
+export interface CoderStudioCommandInput {
+  apiUrl?: string;
+  op: string;
+  args: unknown;
+  timeoutMs?: number;
+  resolveStrategy?: "auto" | "session";
+}
+
+async function resolveApiUrl(
+  explicitApiUrl: string | undefined,
+  resolveStrategy: "auto" | "session" = "auto"
+): Promise<string> {
+  if (explicitApiUrl) {
+    return explicitApiUrl;
+  }
+
+  if (process.env.CODER_STUDIO_API_URL) {
+    return process.env.CODER_STUDIO_API_URL;
+  }
+
+  if (resolveStrategy === "session") {
+    throw new Error(
+      "Coder Studio automation is not available in this session. Missing CODER_STUDIO_API_URL."
+    );
+  }
+
+  const status = await getServerStatus();
+  const browserUrl = getBrowserUrl(status);
+  if (browserUrl) {
+    return browserUrl;
+  }
+
+  throw new Error(
+    "Unable to find a running Coder Studio server. Start it first or pass --api-url."
+  );
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @spencer-kit/coder-studio exec vitest run src/automation-command-client.test.ts src/automation-entry.test.ts
+```
+
+Expected: PASS. The new entry should use only `CODER_STUDIO_API_URL` and should never attempt managed-server discovery in session mode.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/cli/src/automation-entry.ts packages/cli/src/automation-entry.test.ts packages/cli/src/automation-command-client.ts packages/cli/src/automation-command-client.test.ts
+git commit -m "feat(cli): add session-scoped automation entry"
+```
+
+---
+
+### Task 2: Materialize Shared Automation Bridge Files For Built-in Skills
+
+**Files:**
+- Create: `packages/server/src/skills/builtin/automation-bridge.ts`
+- Create: `packages/server/src/__tests__/skills/builtin-automation-bridge.test.ts`
+- Modify: `packages/server/src/skills/builtin/definitions/types.ts`
+- Modify: `packages/server/src/skills/builtin/materialize.ts`
+- Modify: `packages/server/src/__tests__/skills/builtin-registry.test.ts`
+
+- [ ] **Step 1: Write the failing server tests**
+
+Add `packages/server/src/__tests__/skills/builtin-automation-bridge.test.ts`:
+
+```ts
+import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  AUTOMATION_CMD_FILE_NAME,
+  BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+} from "../../skills/builtin/automation-bridge.js";
+
+describe("builtin automation bridge", () => {
+  let tempDir: string | undefined;
+
+  afterEach(async () => {
+    if (tempDir) {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("fails clearly when required session env is missing", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "builtin-automation-bridge-"));
+    const cmdPath = join(tempDir, AUTOMATION_CMD_FILE_NAME);
+    await writeFile(cmdPath, BUILTIN_AUTOMATION_BRIDGE_SOURCE, "utf8");
+
+    const result = spawnSync(process.execPath, [cmdPath, "memory.list"], {
+      env: {},
+      encoding: "utf8",
+    });
+
+    expect(result.status).not.toBe(0);
+    expect(result.stderr).toContain("CODER_STUDIO_API_URL");
+  });
+
+  it("delegates to the injected automation entry and preserves exit code", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "builtin-automation-bridge-"));
+    const cmdPath = join(tempDir, AUTOMATION_CMD_FILE_NAME);
+    const entryPath = join(tempDir, "fake-automation-entry.mjs");
+    await writeFile(cmdPath, BUILTIN_AUTOMATION_BRIDGE_SOURCE, "utf8");
+    await writeFile(
+      entryPath,
+      'console.log(JSON.stringify(process.argv.slice(2))); process.exit(7);',
+      "utf8"
+    );
+    await chmod(entryPath, 0o755);
+
+    const result = spawnSync(process.execPath, [cmdPath, "memory.list", "--json"], {
+      env: {
+        ...process.env,
+        CODER_STUDIO_API_URL: "http://127.0.0.1:4173",
+        CODER_STUDIO_WORKSPACE_ID: "ws-1",
+        CODER_STUDIO_SESSION_TOKEN: "token-1",
+        CODER_STUDIO_AUTOMATION_ENTRY: entryPath,
+      },
+      encoding: "utf8",
+    });
+
+    expect(result.status).toBe(7);
+    expect(result.stdout).toContain('"memory.list"');
+  });
+});
+```
+
+Extend `packages/server/src/__tests__/skills/builtin-registry.test.ts` with expectations like:
+
+```ts
+    expect(memoryEntry).toMatchObject({
+      slug: "coder-studio-memory",
+      builtin: { autoMount: true },
+    });
+    await expect(readFile(join(memoryEntry!.libraryPath, "cmd.mjs"), "utf8")).resolves.toContain(
+      "CODER_STUDIO_AUTOMATION_ENTRY"
+    );
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/builtin-registry.test.ts src/__tests__/skills/builtin-automation-bridge.test.ts
+```
+
+Expected: FAIL because built-in skills do not ship `cmd.mjs`, and the bridge module does not exist.
+
+- [ ] **Step 3: Implement shared bridge source and managed-file materialization**
+
+Create `packages/server/src/skills/builtin/automation-bridge.ts`:
+
+```ts
+import { join } from "node:path";
+
+export const AUTOMATION_CMD_FILE_NAME = "cmd.mjs";
+export const AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN = "<absolute-mounted-skill-path>/cmd.mjs";
+
+export const BUILTIN_AUTOMATION_BRIDGE_SOURCE = `import { spawn } from "node:child_process";
+
+const REQUIRED_ENV = [
+  "CODER_STUDIO_API_URL",
+  "CODER_STUDIO_WORKSPACE_ID",
+  "CODER_STUDIO_SESSION_TOKEN",
+  "CODER_STUDIO_AUTOMATION_ENTRY",
+];
+
+function readRequiredEnv(name) {
+  const value = process.env[name]?.trim();
+  if (!value) {
+    throw new Error(
+      \`Coder Studio automation is not available in this session. Missing \${name}.\`
+    );
+  }
+  return value;
+}
+
+for (const key of REQUIRED_ENV) {
+  readRequiredEnv(key);
+}
+
+const entry = process.env.CODER_STUDIO_AUTOMATION_ENTRY;
+const child = spawn(process.execPath, [entry, ...process.argv.slice(2)], {
+  env: process.env,
+  stdio: "inherit",
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});
+
+child.on("error", (error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+`;
+
+export interface MountedSkillOverride {
+  relativePath: string;
+  content: string;
+}
+
+export function renderMountedAutomationCommand(targetPath: string): string {
+  return `node "${join(targetPath, AUTOMATION_CMD_FILE_NAME)}"`;
+}
+
+export function renderMountedSkillContent(content: string, targetPath: string): string {
+  return content.replaceAll(
+    AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN,
+    join(targetPath, AUTOMATION_CMD_FILE_NAME)
+  );
+}
+```
+
+Extend `packages/server/src/skills/builtin/definitions/types.ts`:
+
+```ts
+export interface BuiltinSkillManagedFile {
+  relativePath: string;
+  content: string;
+}
+
+export interface BuiltinSkillDefinition {
+  slug: string;
+  displayName: string;
+  description: string;
+  version: string;
+  defaultEnabled: boolean;
+  autoMountInMvp: boolean;
+  content: string;
+  files?: readonly BuiltinSkillManagedFile[];
+  mountRendering?: "none" | "automation_bridge";
+}
+```
+
+Update `packages/server/src/skills/builtin/materialize.ts` to write declared files after `SKILL.md`:
+
+```ts
+    await writeFile(join(libraryPath, "SKILL.md"), `${skill.content.trimEnd()}\n`, "utf8");
+    for (const file of skill.files ?? []) {
+      const targetPath = join(libraryPath, file.relativePath);
+      await mkdir(dirname(targetPath), { recursive: true });
+      await writeFile(targetPath, file.content, "utf8");
+    }
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/builtin-registry.test.ts src/__tests__/skills/builtin-automation-bridge.test.ts
+```
+
+Expected: PASS. Built-in library entries should now include `cmd.mjs`, and the shared bridge should validate env plus delegate exit status.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/skills/builtin/automation-bridge.ts packages/server/src/__tests__/skills/builtin-automation-bridge.test.ts packages/server/src/skills/builtin/definitions/types.ts packages/server/src/skills/builtin/materialize.ts packages/server/src/__tests__/skills/builtin-registry.test.ts
+git commit -m "feat(server): materialize builtin automation bridges"
+```
+
+---
+
+### Task 3: Render Automation Skills As Forced-Copy Mounts
+
+**Files:**
+- Modify: `packages/server/src/skills/mount-manager.ts`
+- Modify: `packages/server/src/skills/builtin/sync-manager.ts`
+- Modify: `packages/server/src/__tests__/skills/mount-manager.test.ts`
+- Modify: `packages/server/src/__tests__/skills/builtin-sync-manager.test.ts`
+
+- [ ] **Step 1: Write the failing mount tests**
+
+Add one `mount-manager` test that forces rendered overrides:
+
+```ts
+  it("uses copy mode and writes mounted overrides when requested", async () => {
+    const relation = await manager.mount({
+      providerId: "codex",
+      skillSlug: "my-review-skill",
+      enabled: true,
+      preferredMode: "copy",
+      mountedOverrides: [
+        {
+          relativePath: "SKILL.md",
+          content: 'node "/tmp/codex-skills/my-review-skill/cmd.mjs" memory.list --json\n',
+        },
+      ],
+    });
+
+    expect(relation.mountModeResolved).toBe("copy");
+    await expect(readFile(join(skillDir, "my-review-skill", "SKILL.md"), "utf8")).resolves.toContain(
+      'node "/tmp/codex-skills/my-review-skill/cmd.mjs"'
+    );
+  });
+```
+
+Add one `builtin-sync-manager` test that proves automation skills are mounted as rendered copies:
+
+```ts
+    expect(result.mounted).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          providerId: "codex",
+          skillSlug: "coder-studio-memory",
+          mountModeResolved: "copy",
+        }),
+      ])
+    );
+    await expect(
+      readFile(join(skillDir, "coder-studio-memory", "SKILL.md"), "utf8")
+    ).resolves.toContain(`node "${join(skillDir, "coder-studio-memory", "cmd.mjs")}"`);
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/mount-manager.test.ts src/__tests__/skills/builtin-sync-manager.test.ts
+```
+
+Expected: FAIL because mount plans cannot force `copy`, and mounted `SKILL.md` content is not rewritten with target-specific paths.
+
+- [ ] **Step 3: Implement forced-copy mount plans and mounted overrides**
+
+Extend `packages/server/src/skills/mount-manager.ts`:
+
+```ts
+export interface SkillMountPlan {
+  providerId: string;
+  skillSlug: string;
+  enabled: boolean;
+  preferredMode?: "auto" | "copy";
+  mountedOverrides?: Array<{
+    relativePath: string;
+    content: string;
+  }>;
+}
+```
+
+Change the mount flow so `preferredMode: "copy"` skips symlink attempts and writes overrides after copy:
+
+```ts
+    const preferredMode = input.preferredMode ?? "auto";
+    let mountModeResolved: SkillMountRelation["mountModeResolved"] =
+      preferredMode === "copy" ? "copy" : "symlink";
+
+    await rm(targetPath, { recursive: true, force: true });
+    if (preferredMode === "copy") {
+      await copyRecursively(libraryEntry.libraryPath, targetPath);
+    } else {
+      try {
+        await symlink(libraryEntry.libraryPath, targetPath);
+      } catch {
+        mountModeResolved = "copy";
+        await copyRecursively(libraryEntry.libraryPath, targetPath);
+      }
+    }
+
+    for (const override of input.mountedOverrides ?? []) {
+      const overridePath = join(targetPath, override.relativePath);
+      await mkdir(dirname(overridePath), { recursive: true });
+      await writeFile(overridePath, override.content, "utf8");
+    }
+```
+
+Update `packages/server/src/skills/builtin/sync-manager.ts` to build automation mount overrides from definitions:
+
+```ts
+import {
+  AUTOMATION_CMD_FILE_NAME,
+  renderMountedSkillContent,
+} from "./automation-bridge.js";
+
+const definitionBySlug = new Map((this.deps.skills ?? BUILTIN_SKILLS).map((skill) => [skill.slug, skill]));
+
+        const definition = definitionBySlug.get(entry.slug);
+        const targetPath = join(provider.skillMountDirectories![0], entry.slug);
+        const mountedOverrides =
+          definition?.mountRendering === "automation_bridge"
+            ? [
+                {
+                  relativePath: "SKILL.md",
+                  content: `${renderMountedSkillContent(definition.content, targetPath).trimEnd()}\n`,
+                },
+              ]
+            : undefined;
+
+        const relation = await this.deps.skillMountMgr.mount({
+          providerId: provider.id,
+          skillSlug: entry.slug,
+          enabled: true,
+          preferredMode:
+            definition?.mountRendering === "automation_bridge" ? "copy" : "auto",
+          mountedOverrides,
+        });
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/mount-manager.test.ts src/__tests__/skills/builtin-sync-manager.test.ts
+```
+
+Expected: PASS. Automation skills should mount as `copy`, and their mounted `SKILL.md` should contain the actual provider target path.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/skills/mount-manager.ts packages/server/src/skills/builtin/sync-manager.ts packages/server/src/__tests__/skills/mount-manager.test.ts packages/server/src/__tests__/skills/builtin-sync-manager.test.ts
+git commit -m "feat(server): render builtin automation mounts"
+```
+
+---
+
+### Task 4: Inject The Resolved Automation Entry Into Agent Sessions
+
+**Files:**
+- Create: `packages/server/src/session/automation-entry-path.ts`
+- Create: `packages/server/src/__tests__/session-automation-entry-path.test.ts`
+- Modify: `packages/server/src/session/manager.ts`
+- Modify: `packages/server/src/__tests__/session-integration.test.ts`
+
+- [ ] **Step 1: Write the failing session tests**
+
+Create `packages/server/src/__tests__/session-automation-entry-path.test.ts`:
+
+```ts
+import { describe, expect, it } from "vitest";
+import { resolveAutomationEntryPath } from "../session/automation-entry-path.js";
+
+describe("resolveAutomationEntryPath", () => {
+  it("prefers the repo source entry in development worktrees", () => {
+    const path = resolveAutomationEntryPath();
+    expect(path).toContain("packages/cli/src/automation-entry");
+  });
+});
+```
+
+Extend `packages/server/src/__tests__/session-integration.test.ts` with an env assertion:
+
+```ts
+    expect(spawnCalls[0]?.options).toMatchObject({
+      env: expect.objectContaining({
+        CODER_STUDIO_API_URL: expect.stringContaining("127.0.0.1"),
+        CODER_STUDIO_SESSION_TOKEN: expect.any(String),
+        CODER_STUDIO_WORKSPACE_ID: expect.any(String),
+        CODER_STUDIO_AUTOMATION_ENTRY: expect.stringContaining("automation-entry"),
+      }),
+    });
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/session-automation-entry-path.test.ts src/__tests__/session-integration.test.ts
+```
+
+Expected: FAIL because the resolver helper does not exist and sessions do not inject `CODER_STUDIO_AUTOMATION_ENTRY`.
+
+- [ ] **Step 3: Implement entry-path resolution and session env wiring**
+
+Create `packages/server/src/session/automation-entry-path.ts`:
+
+```ts
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_CANDIDATES = [
+  new URL("../../../cli/src/automation-entry.ts", import.meta.url),
+  new URL("../../../cli/dist/automation-entry.js", import.meta.url),
+];
+
+export function resolveAutomationEntryPath(candidates = DEFAULT_CANDIDATES): string {
+  const match = candidates.find((candidate) => existsSync(candidate));
+  if (!match) {
+    throw new Error("Unable to locate the Coder Studio automation entry.");
+  }
+  return fileURLToPath(match);
+}
+```
+
+Update `packages/server/src/session/manager.ts`:
+
+```ts
+import { resolveAutomationEntryPath } from "./automation-entry-path.js";
+
+const automationEntryPath = resolveAutomationEntryPath();
+
+      const terminalSpec: TerminalSpec = {
+        workspaceId: req.workspaceId,
+        kind: "agent",
+        argv: cmd.argv,
+        cwd: cmd.cwd,
+        env: {
+          ...cmd.env,
+          CODER_STUDIO: "1",
+          CODER_STUDIO_WORKSPACE_ID: req.workspaceId,
+          CODER_STUDIO_SESSION_ID: sessionId,
+          CODER_STUDIO_PROVIDER_ID: req.providerId,
+          CODER_STUDIO_SESSION_TOKEN: tokenRecord.token,
+          CODER_STUDIO_AUTOMATION_ENTRY: automationEntryPath,
+          [AUTOMATION_PERMISSIONS_ENV]: permissions.join(","),
+          ...(this.hostBridge.getHostApiUrl()
+            ? { CODER_STUDIO_API_URL: this.hostBridge.getHostApiUrl() }
+            : {}),
+        },
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/session-automation-entry-path.test.ts src/__tests__/session-integration.test.ts
+```
+
+Expected: PASS. New agent sessions should carry an absolute `CODER_STUDIO_AUTOMATION_ENTRY`, and the resolver should pick the repo source entry in development.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/session/automation-entry-path.ts packages/server/src/__tests__/session-automation-entry-path.test.ts packages/server/src/session/manager.ts packages/server/src/__tests__/session-integration.test.ts
+git commit -m "feat(server): inject automation entry into sessions"
+```
+
+---
+
+### Task 5: Rewrite Built-in Skill Content And Wiring Expectations
+
+**Files:**
+- Modify: `packages/server/src/skills/builtin/definitions/coder-studio-memory.ts`
+- Modify: `packages/server/src/skills/builtin/definitions/coder-studio-open.ts`
+- Modify: `packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts`
+- Modify: `packages/server/src/__tests__/skills/builtin-registry.test.ts`
+- Modify: `packages/server/src/__tests__/server-builtin-skills-wiring.test.ts`
+
+- [ ] **Step 1: Write the failing content and wiring tests**
+
+Update `packages/server/src/__tests__/skills/builtin-registry.test.ts` expectations:
+
+```ts
+    expect(CODER_STUDIO_MEMORY_SKILL.content).toContain(
+      'node "<absolute-mounted-skill-path>/cmd.mjs" memory.create --type wiki'
+    );
+    expect(CODER_STUDIO_MEMORY_SKILL.content).not.toContain("coder-studio memory add");
+    expect(CODER_STUDIO_OPEN_SKILL.content).toContain(
+      'node "<absolute-mounted-skill-path>/cmd.mjs" ui.open-file --path <workspace-relative-path> --json'
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      'node "<absolute-mounted-skill-path>/cmd.mjs" canvas.create --kind architecture_canvas'
+    );
+```
+
+Update `packages/server/src/__tests__/server-builtin-skills-wiring.test.ts`:
+
+```ts
+    expect(readFileSync(builtinMemorySkillPath, "utf8")).toContain(
+      'node "<absolute-mounted-skill-path>/cmd.mjs" memory.create'
+    );
+    expect(existsSync(join(builtinRoot, "coder-studio-memory", "cmd.mjs"))).toBe(true);
+
+    expect(readFileSync(homeMemorySkillPath, "utf8")).toContain(
+      `node "${join(tempDir, "home", ".agents", "skills", "coder-studio-memory", "cmd.mjs")}"`
+    );
+    expect(readFileSync(homeMemorySkillPath, "utf8")).not.toContain("coder-studio memory add");
+    expect(existsSync(join(tempDir, "home", ".agents", "skills", "coder-studio-memory", "cmd.mjs"))).toBe(true);
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/builtin-registry.test.ts src/__tests__/server-builtin-skills-wiring.test.ts
+```
+
+Expected: FAIL because built-in skill content still references `coder-studio ...` commands and mounted skills do not contain absolute `cmd.mjs` references.
+
+- [ ] **Step 3: Rewrite the three built-in automation skills**
+
+For all three skill definition files, attach the bridge file and mark them as automation-rendered:
+
+```ts
+import {
+  AUTOMATION_CMD_FILE_NAME,
+  BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+} from "../automation-bridge.js";
+
+export const CODER_STUDIO_MEMORY_SKILL: BuiltinSkillDefinition = {
+  slug: "coder-studio-memory",
+  displayName: "Coder Studio Memory",
+  description: "Read and write durable Coder Studio workspace memory on demand.",
+  version: "1.0.0",
+  defaultEnabled: true,
+  autoMountInMvp: true,
+  mountRendering: "automation_bridge",
+  files: [
+    {
+      relativePath: AUTOMATION_CMD_FILE_NAME,
+      content: BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+    },
+  ],
+  content: [
+    "---",
+    "name: coder-studio-memory",
+    "description: Read and write durable Coder Studio workspace memory on demand.",
+    "---",
+    "",
+    "# Coder Studio Memory",
+    "",
+    "Use this skill when you need durable project context or want to leave stable follow-up context for future sessions.",
+    "",
+    "```bash",
+    'node "<absolute-mounted-skill-path>/cmd.mjs" memory.search --query architecture --json',
+    'node "<absolute-mounted-skill-path>/cmd.mjs" memory.create --type issue --content "Verify release notes before publishing." --status pending_verification --skill coder-studio-memory --json',
+    "```",
+    "",
+  ].join("\\n"),
+};
+```
+
+Apply the same shape to `coder-studio-open.ts` and `coder-studio-canvas.ts`, using dotted ops like `ui.open-file`, `ui.close-file`, `ui.open-url`, `ui.close-url`, `ui.open-canvas`, `canvas.create`, `canvas.update`, and `canvas.render`.
+
+- [ ] **Step 4: Run targeted tests and the final repo verification**
+
+Run:
+
+```bash
+pnpm --filter @coder-studio/server exec vitest run src/__tests__/skills/builtin-registry.test.ts src/__tests__/server-builtin-skills-wiring.test.ts src/__tests__/skills/builtin-sync-manager.test.ts
+pnpm ci:verify
+```
+
+Expected: PASS. The library copy should contain generic `node "<absolute-mounted-skill-path>/cmd.mjs"` examples, and mounted skills should contain absolute target paths plus `cmd.mjs`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/skills/builtin/definitions/coder-studio-memory.ts packages/server/src/skills/builtin/definitions/coder-studio-open.ts packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts packages/server/src/__tests__/skills/builtin-registry.test.ts packages/server/src/__tests__/server-builtin-skills-wiring.test.ts
+git commit -m "feat(server): move builtin automation skills to mounted bridges"
+```
+
+---
+
+## Self-Review Checklist
+
+- Spec coverage:
+  - built-in skill files gain `cmd.mjs` and managed-file materialization in Task 2
+  - rendered copy mounts and target-specific `SKILL.md` happen in Task 3
+  - runtime env injection of `CODER_STUDIO_AUTOMATION_ENTRY` happens in Task 4
+  - dotted internal automation ops and strict session-only websocket usage happen in Task 1
+  - memory/canvas/open skill content migration happens in Task 5
+- Placeholder scan:
+  - no `TODO`, `TBD`, or “similar to previous task” placeholders remain
+  - each task has explicit files, concrete commands, and expected results
+- Type consistency:
+  - `mountRendering`, `files`, `preferredMode`, `mountedOverrides`, and `resolveStrategy` are used consistently across tasks
diff --git a/docs/superpowers/plans/2026-06-23-canvas-file-first-implementation.md b/docs/superpowers/plans/2026-06-23-canvas-file-first-implementation.md
new file mode 100644
index 000000000..07faf369b
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-23-canvas-file-first-implementation.md
@@ -0,0 +1,1549 @@
+# Canvas File-First Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Migrate canvas from an artifact-first `canvasId` render model to a file-first `.csc` document model where normal file opens render the canvas by `sourcePath`.
+
+**Architecture:** Keep the existing canvas repo and `canvasId` command compatibility shims only where they are still useful for `canvas.list`, `canvas.update`, and `ui open-canvas`, but move steady-state rendering, tab identity, route addressing, and default open behavior to `workspaceId + sourcePath`. The server will create readable `.csc` files from meaningful titles, the web editor will treat `.csc` as a renderable document type with a path-addressed canvas tab, and rename/delete flows will rewrite or close those tabs the same way normal file state already does.
+
+**Tech Stack:** TypeScript, Zod, Fastify, React 19, Jotai, Vitest, Testing Library
+
+---
+
+## File Map
+
+- `packages/server/src/canvas/source-path.ts`
+  Creates readable `.csc` source paths from canvas titles and handles collision suffixes locally inside the canvas subsystem.
+- `packages/server/src/canvas/service.ts`
+  Owns canvas create, update, render, repo sync, and source-file reads. This becomes the main file-first server entry.
+- `packages/server/src/storage/repositories/canvas-repo.ts`
+  Keeps compatibility metadata for list/update/open-canvas and gains path rewrite/delete helpers for generic file rename/delete.
+- `packages/server/src/commands/canvas.ts`
+  Keeps command compatibility, but makes `canvas.render` resolve to `sourcePath` first and emits canonical path-based `canvas.open`.
+- `packages/server/src/commands/ui-actions.ts`
+  Resolves legacy `canvas.open` requests by `canvasId` and rebroadcasts canonical file-first metadata.
+- `packages/server/src/routes/canvas.ts`
+  Switches the canvas API from `/:canvasId/data` to `/data?sourcePath=...`.
+- `packages/server/src/commands/file.ts`
+  Calls canvas repo sync hooks after generic file rename/delete so compatibility records do not drift.
+- `packages/core/src/domain/canvas.ts`
+  Shared render response contract; this must stop requiring `canvasId` for runtime rendering and must carry `sourcePath`.
+- `packages/core/src/domain/types.ts`
+  Shared workspace tab contract; the canvas editor tab becomes path-addressed.
+- `packages/core/src/domain/ui-actions.ts`
+  Shared UI action contract; `canvas.open` becomes canonicalized around `sourcePath`.
+- `packages/web/src/features/workspace/atoms/files.ts`
+  Adds `.csc` classification, path-based canvas tab construction, normalization, and refresh-token keys.
+- `packages/web/src/features/workspace/actions/use-open-workspace-file.ts`
+  Intercepts `.csc` from ordinary file-open flows and opens a render tab instead of a text file tab.
+- `packages/web/src/features/ui-actions/use-ui-action-subscription.ts`
+  Opens or replaces canvas tabs by `sourcePath`, not `canvasId`.
+- `packages/web/src/features/code-editor/views/shared/canvas-surface.tsx`
+  Refreshes and embeds canvases by `sourcePath`.
+- `packages/web/src/features/canvas/api.ts`
+  Fetches canvas data by query `sourcePath`.
+- `packages/web/src/features/canvas/routes/embedded-canvas-route.tsx`
+  Reads `sourcePath` from search params and renders the embedded canvas.
+- `packages/web/src/features/workspace/actions/open-editor-state.ts`
+  Normalizes persisted canvas tabs by `sourcePath`.
+- `packages/web/src/features/workspace/actions/use-file-actions.ts`
+  Rewrites or closes canvas tabs during file rename/delete.
+- `packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts`
+  Updates builtin skill guidance to require meaningful titles and to open existing canvases through normal `.csc` file flows.
+
+## Final Verification
+
+Run these after all tasks are complete:
+
+```bash
+pnpm --dir packages/core exec vitest run src/domain/canvas.test.ts src/domain/ui-actions.test.ts src/domain/types.test.ts
+pnpm --dir packages/server exec vitest run src/canvas/source-path.test.ts src/canvas/service.test.ts src/commands/canvas.test.ts src/routes/canvas.test.ts src/__tests__/ui-actions-commands.test.ts src/__tests__/file-commands.test.ts src/storage/repositories/canvas-repo.test.ts src/__tests__/skills/builtin-registry.test.ts src/__tests__/server-builtin-skills-wiring.test.ts
+pnpm --dir packages/web exec vitest run src/features/workspace/atoms/files.test.ts src/features/workspace/actions/open-editor-state.test.ts src/features/workspace/actions/use-open-workspace-file.test.tsx src/features/workspace/actions/use-file-actions.test.tsx src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx src/features/ui-actions/use-ui-action-subscription.test.tsx src/features/code-editor/views/shared/canvas-surface.test.tsx src/features/canvas/routes/embedded-canvas-route.test.tsx src/app.test.tsx src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx
+pnpm ci:verify
+```
+
+Expected: all targeted tests pass, then `pnpm ci:verify` exits `0`.
+
+### Task 1: Create Readable `.csc` Source Paths From Canvas Titles
+
+**Files:**
+- Create: `packages/server/src/canvas/source-path.ts`
+- Create: `packages/server/src/canvas/source-path.test.ts`
+- Modify: `packages/server/src/canvas/service.ts`
+- Modify: `packages/server/src/canvas/service.test.ts`
+- Test: `packages/server/src/canvas/source-path.test.ts`
+- Test: `packages/server/src/canvas/service.test.ts`
+
+- [ ] **Step 1: Write the failing slug and create-path tests**
+
+Add a focused helper test file:
+
+```ts
+import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createCanvasSourcePath, slugifyCanvasTitle } from "./source-path.js";
+
+describe("canvas source paths", () => {
+  let tempDir: string | undefined;
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+      tempDir = undefined;
+    }
+  });
+
+  it("slugifies meaningful canvas titles into readable file names", () => {
+    expect(slugifyCanvasTitle("Runtime Request Flow")).toBe("runtime-request-flow");
+    expect(slugifyCanvasTitle(" Workspace Audit Summary ")).toBe("workspace-audit-summary");
+  });
+
+  it("allocates .csc file names and appends numeric suffixes on collision", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-source-path-"));
+    mkdirSync(join(tempDir, ".coder-studio", "canvases"), { recursive: true });
+    writeFileSync(
+      join(tempDir, ".coder-studio", "canvases", "runtime-request-flow.csc"),
+      "{}\n"
+    );
+
+    expect(
+      createCanvasSourcePath({
+        workspaceRootPath: tempDir,
+        title: "Runtime Request Flow",
+      })
+    ).toBe(".coder-studio/canvases/runtime-request-flow-2.csc");
+  });
+});
+```
+
+Extend `packages/server/src/canvas/service.test.ts` so create now expects a readable `.csc` path:
+
+```ts
+    expect(result.record.title).toBe("Runtime Flow");
+    expect(result.record.sourcePath).toBe(".coder-studio/canvases/runtime-flow.csc");
+```
+
+- [ ] **Step 2: Run the server tests to verify they fail**
+
+Run: `pnpm --dir packages/server exec vitest run src/canvas/source-path.test.ts src/canvas/service.test.ts`
+
+Expected: FAIL because `source-path.ts` does not exist and `CanvasService.create()` still writes `<canvas-id>.canvas.json`.
+
+- [ ] **Step 3: Add the source-path helper and switch create to `.csc`**
+
+Create `packages/server/src/canvas/source-path.ts`:
+
+```ts
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export function slugifyCanvasTitle(title: string): string {
+  return title
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+export function createCanvasSourcePath(input: {
+  workspaceRootPath: string;
+  title: string;
+}): string {
+  const slug = slugifyCanvasTitle(input.title);
+  if (!slug) {
+    throw { code: "invalid_canvas_title", message: "Canvas title must produce a valid file name" };
+  }
+
+  let suffix = 0;
+  while (true) {
+    const fileName = suffix === 0 ? `${slug}.csc` : `${slug}-${suffix + 1}.csc`;
+    const sourcePath = `.coder-studio/canvases/${fileName}`;
+    if (!existsSync(join(input.workspaceRootPath, sourcePath))) {
+      return sourcePath;
+    }
+    suffix += 1;
+  }
+}
+```
+
+Update the create path in `packages/server/src/canvas/service.ts`:
+
+```ts
+import { createCanvasSourcePath } from "./source-path.js";
+
+// inside CanvasService.create()
+    const timestamp = this.now();
+    const canvasId = createCanvasId(timestamp);
+    const sourcePath = createCanvasSourcePath({
+      workspaceRootPath: input.workspaceRootPath,
+      title: input.title,
+    });
+```
+
+Do not change the internal `canvasId` record generation in this task; it remains a compatibility identifier.
+
+- [ ] **Step 4: Run the server tests to verify they pass**
+
+Run: `pnpm --dir packages/server exec vitest run src/canvas/source-path.test.ts src/canvas/service.test.ts`
+
+Expected: PASS with `.coder-studio/canvases/<slug>.csc` paths.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/canvas/source-path.ts packages/server/src/canvas/source-path.test.ts packages/server/src/canvas/service.ts packages/server/src/canvas/service.test.ts
+git commit -m "feat: create canvases as readable csc files"
+```
+
+### Task 2: Move Shared Contracts to Source-Path-First Canvas Identity
+
+**Files:**
+- Modify: `packages/core/src/domain/canvas.ts`
+- Modify: `packages/core/src/domain/types.ts`
+- Modify: `packages/core/src/domain/ui-actions.ts`
+- Modify: `packages/core/src/domain/canvas.test.ts`
+- Modify: `packages/core/src/domain/types.test.ts`
+- Modify: `packages/core/src/domain/ui-actions.test.ts`
+- Test: `packages/core/src/domain/canvas.test.ts`
+- Test: `packages/core/src/domain/types.test.ts`
+- Test: `packages/core/src/domain/ui-actions.test.ts`
+
+- [ ] **Step 1: Write the failing shared-contract tests**
+
+Add a response-shape assertion in `packages/core/src/domain/canvas.test.ts`:
+
+```ts
+  it("requires sourcePath for canvas render responses", () => {
+    expect(() =>
+      CanvasDataResponseSchema.parse({
+        workspaceId: "ws-1",
+        title: "Runtime Flow",
+        kind: "architecture_canvas",
+        renderStatus: "ready",
+        lastError: null,
+        compiledDocument: {
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [],
+        },
+      })
+    ).toThrow();
+
+    expect(
+      CanvasDataResponseSchema.parse({
+        workspaceId: "ws-1",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+        title: "Runtime Flow",
+        kind: "architecture_canvas",
+        renderStatus: "ready",
+        lastError: null,
+        compiledDocument: {
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [],
+        },
+      })
+    ).toMatchObject({
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+  });
+```
+
+Add a type assertion in `packages/core/src/domain/types.test.ts`:
+
+```ts
+import type { WorkspaceCanvasEditorTab } from "./types";
+
+describe("WorkspaceCanvasEditorTab", () => {
+  it("is keyed by sourcePath instead of requiring canvasId", () => {
+    expectTypeOf<WorkspaceCanvasEditorTab>().toEqualTypeOf<{
+      kind: "canvas";
+      id: string;
+      title: string;
+      sourcePath: string;
+      artifactType?: "architecture_canvas" | "report_canvas";
+      canvasId?: string;
+    }>();
+  });
+});
+```
+
+Update `packages/core/src/domain/ui-actions.test.ts` with a canonical file-first `canvas.open` case:
+
+```ts
+    expect(
+      validateUiActionIntent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        title: " Runtime Flow ",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      })
+    ).toEqual({
+      type: "canvas.open",
+      workspaceId: "ws-1",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+```
+
+Keep one compatibility case with `canvasId` only in the same test file.
+
+- [ ] **Step 2: Run the core tests to verify they fail**
+
+Run: `pnpm --dir packages/core exec vitest run src/domain/canvas.test.ts src/domain/types.test.ts src/domain/ui-actions.test.ts`
+
+Expected: FAIL because `CanvasDataResponseSchema` does not require `sourcePath`, `WorkspaceCanvasEditorTab` still requires `canvasId`, and `canvas.open` still rejects the canonical path-based payload.
+
+- [ ] **Step 3: Update the shared contracts**
+
+In `packages/core/src/domain/canvas.ts`, change the response shape:
+
+```ts
+export const CanvasDataResponseSchema = z
+  .object({
+    workspaceId: z.string().trim().min(1),
+    sourcePath: z.string().trim().min(1),
+    canvasId: z.string().trim().min(1).optional(),
+    title: z.string().trim().min(1),
+    kind: CanvasArtifactKind,
+    renderStatus: z.enum(["ready", "error"]),
+    lastError: CanvasRenderErrorSchema.nullable().optional(),
+    compiledDocument: CompiledCanvasSchema.optional(),
+  })
+```
+
+In `packages/core/src/domain/types.ts`, change the tab contract:
+
+```ts
+export interface WorkspaceCanvasEditorTab {
+  kind: "canvas";
+  id: string;
+  title: string;
+  sourcePath: string;
+  artifactType?: "architecture_canvas" | "report_canvas";
+  canvasId?: string;
+}
+```
+
+In `packages/core/src/domain/ui-actions.ts`, make canonical `canvas.open` path-first while preserving `canvasId` as an optional compatibility field:
+
+```ts
+export type CanvasOpenUiActionIntent = {
+  type: "canvas.open";
+  workspaceId?: string;
+  title: string;
+  artifactType: CanvasArtifactKind;
+  sourcePath: string;
+  canvasId?: string;
+};
+
+export type CanvasOpenUiActionDispatchIntent = {
+  type: "canvas.open";
+  workspaceId?: string;
+  canvasId?: string;
+  title?: string;
+  artifactType?: CanvasArtifactKind;
+  sourcePath?: string;
+};
+```
+
+Update `validateUiActionIntent()` so it accepts either:
+
+```ts
+      const hasCanvasId = typeof intent.canvasId === "string" && intent.canvasId.trim().length > 0;
+      const hasMetadata =
+        intent.title !== undefined &&
+        intent.artifactType !== undefined &&
+        intent.sourcePath !== undefined;
+
+      if (!hasCanvasId && !hasMetadata) {
+        throw new Error("canvas.open requires canvasId or sourcePath metadata");
+      }
+```
+
+- [ ] **Step 4: Run the core tests to verify they pass**
+
+Run: `pnpm --dir packages/core exec vitest run src/domain/canvas.test.ts src/domain/types.test.ts src/domain/ui-actions.test.ts`
+
+Expected: PASS with source-path-first contracts.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/core/src/domain/canvas.ts packages/core/src/domain/types.ts packages/core/src/domain/ui-actions.ts packages/core/src/domain/canvas.test.ts packages/core/src/domain/types.test.ts packages/core/src/domain/ui-actions.test.ts
+git commit -m "feat: make shared canvas contracts source-path first"
+```
+
+### Task 3: Make Server Render, Routes, and Canonical `canvas.open` File-First
+
+**Files:**
+- Modify: `packages/server/src/canvas/service.ts`
+- Modify: `packages/server/src/commands/canvas.ts`
+- Modify: `packages/server/src/commands/ui-actions.ts`
+- Modify: `packages/server/src/routes/canvas.ts`
+- Modify: `packages/server/src/commands/canvas.test.ts`
+- Modify: `packages/server/src/routes/canvas.test.ts`
+- Modify: `packages/server/src/__tests__/ui-actions-commands.test.ts`
+- Test: `packages/server/src/commands/canvas.test.ts`
+- Test: `packages/server/src/routes/canvas.test.ts`
+- Test: `packages/server/src/__tests__/ui-actions-commands.test.ts`
+
+- [ ] **Step 1: Write the failing server path-first tests**
+
+Update `packages/server/src/routes/canvas.test.ts` to use query `sourcePath`:
+
+```ts
+    const response = await app.inject({
+      method: "GET",
+      url: "/api/canvas/ws-1/data?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc",
+    });
+
+    expect(getCanvasData).toHaveBeenCalledWith({
+      workspaceId: "ws-1",
+      workspaceRootPath: "/workspace",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+```
+
+Update `packages/server/src/commands/canvas.test.ts` so `canvas.render` asserts a file-first response:
+
+```ts
+    const renderResult = await dispatch(
+      command("canvas.render", {
+        workspaceId: "ws-1",
+        sourcePath: created.record.sourcePath,
+      }),
+      ctx
+    );
+
+    expect(renderResult.ok).toBe(true);
+    expect(renderResult.data).toEqual({
+      sourcePath: created.record.sourcePath,
+      canvasId: created.record.id,
+      renderStatus: "ready",
+      lastError: null,
+    });
+```
+
+Update `packages/server/src/__tests__/ui-actions-commands.test.ts` so canonical `canvas.open` expectations assert `sourcePath` and do not require the caller to supply metadata.
+
+- [ ] **Step 2: Run the server tests to verify they fail**
+
+Run: `pnpm --dir packages/server exec vitest run src/commands/canvas.test.ts src/routes/canvas.test.ts src/__tests__/ui-actions-commands.test.ts`
+
+Expected: FAIL because the route still expects `:canvasId`, `canvas.render` still returns `canvasId`-only output, and canonical UI action handling is still id-first.
+
+- [ ] **Step 3: Update the service, command, and route flow**
+
+In `packages/server/src/canvas/service.ts`, render directly from the source file instead of requiring a repo hit:
+
+```ts
+  async getCanvasData(input: {
+    workspaceId: string;
+    workspaceRootPath: string;
+    sourcePath: string;
+  }): Promise<CanvasDataResponse> {
+    const sourceRead = await readFile(input.workspaceId, input.workspaceRootPath, input.sourcePath);
+    if (sourceRead.kind !== "text") {
+      throw { code: "canvas_source_invalid", message: "Canvas source must be a text file" };
+    }
+
+    const validated = validateCanvasSource(sourceRead.content);
+    const fallbackTitle = input.sourcePath.split("/").pop() ?? input.sourcePath;
+    if (!validated.ok) {
+      return {
+        workspaceId: input.workspaceId,
+        sourcePath: input.sourcePath,
+        title: fallbackTitle,
+        kind: "architecture_canvas",
+        renderStatus: "error",
+        lastError: validated.error,
+      };
+    }
+
+    const record = this.getRecordBySourcePath(input.workspaceId, input.sourcePath);
+    const compiledDocument = compileCanvasDocument(validated.document);
+
+    return {
+      workspaceId: input.workspaceId,
+      sourcePath: input.sourcePath,
+      ...(record ? { canvasId: record.id } : {}),
+      title: validated.document.title,
+      kind: validated.document.kind,
+      renderStatus: "ready",
+      lastError: null,
+      compiledDocument,
+    };
+  }
+```
+
+In `packages/server/src/commands/canvas.ts`, keep `canvasId` as a compatibility input but resolve to `sourcePath` before rendering:
+
+```ts
+    const sourcePath =
+      args.sourcePath ?? canvasService.getRecord(args.workspaceId, args.canvasId ?? "")?.sourcePath;
+
+    if (!sourcePath) {
+      throw {
+        code: "canvas_not_found",
+        message: `Canvas not found: ${args.canvasId ?? args.sourcePath ?? "unknown"}`,
+      };
+    }
+
+    const result = await canvasService.getCanvasData({
+      workspaceId: args.workspaceId,
+      workspaceRootPath: workspace.path,
+      sourcePath,
+    });
+
+    return {
+      sourcePath: result.sourcePath,
+      ...(result.canvasId ? { canvasId: result.canvasId } : {}),
+      renderStatus: result.renderStatus,
+      lastError: result.lastError ?? null,
+    };
+```
+
+In `packages/server/src/routes/canvas.ts`, switch to query-based addressing:
+
+```ts
+  app.get("/api/canvas/:workspaceId/data", async (request, reply) => {
+    const { workspaceId } = request.params as { workspaceId: string };
+    const { sourcePath } = request.query as { sourcePath?: string };
+
+    if (!sourcePath) {
+      return reply.status(400).send({ error: "source_path_required" });
+    }
+
+    const data = await deps.canvasService.getCanvasData({
+      workspaceId,
+      workspaceRootPath: workspace.path,
+      sourcePath,
+    });
+
+    return reply.send(data);
+  });
+```
+
+In `packages/server/src/commands/ui-actions.ts`, first relax the server dispatch schema so `canvasId` is optional for path-first callers:
+
+```ts
+  z.object({
+    type: z.literal("canvas.open"),
+    workspaceId: z.string().optional(),
+    canvasId: z.string().optional(),
+    title: z.string().optional(),
+    artifactType: z.enum(["architecture_canvas", "report_canvas"]).optional(),
+    sourcePath: z.string().optional(),
+  }),
+```
+
+Then canonicalize `canvas.open` to file metadata:
+
+```ts
+          const sourcePath =
+            request.intent.sourcePath ??
+            ctx.canvasService?.getRecord(workspaceId, request.intent.canvasId ?? "")?.sourcePath;
+          if (!sourcePath) {
+            throw {
+              code: "canvas_not_found",
+              message: `Canvas not found: ${request.intent.canvasId ?? "unknown"}`,
+            };
+          }
+
+          const data = await ctx.canvasService.getCanvasData({
+            workspaceId,
+            workspaceRootPath: workspace.path,
+            sourcePath,
+          });
+
+          return {
+            ...request,
+            intent: {
+              type: "canvas.open" as const,
+              workspaceId,
+              sourcePath: data.sourcePath,
+              title: data.title,
+              artifactType: data.kind,
+              ...(data.canvasId ? { canvasId: data.canvasId } : {}),
+            },
+          };
+```
+
+- [ ] **Step 4: Run the server tests to verify they pass**
+
+Run: `pnpm --dir packages/server exec vitest run src/commands/canvas.test.ts src/routes/canvas.test.ts src/__tests__/ui-actions-commands.test.ts`
+
+Expected: PASS with query-based render routes and canonical path-first `canvas.open`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/canvas/service.ts packages/server/src/commands/canvas.ts packages/server/src/commands/ui-actions.ts packages/server/src/routes/canvas.ts packages/server/src/commands/canvas.test.ts packages/server/src/routes/canvas.test.ts packages/server/src/__tests__/ui-actions-commands.test.ts
+git commit -m "feat: render canvases by source path"
+```
+
+### Task 4: Make Web Canvas Tabs, Fetching, and Embedded Routes Path-Based
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/atoms/files.ts`
+- Modify: `packages/web/src/features/workspace/actions/open-editor-state.ts`
+- Modify: `packages/web/src/features/code-editor/views/shared/canvas-surface.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx`
+- Modify: `packages/web/src/features/canvas/api.ts`
+- Modify: `packages/web/src/features/canvas/routes/embedded-canvas-route.tsx`
+- Modify: `packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx`
+- Modify: `packages/web/src/app.tsx`
+- Modify: `packages/web/src/app.test.tsx`
+- Modify: `packages/web/src/features/workspace/atoms/files.test.ts`
+- Modify: `packages/web/src/features/workspace/actions/open-editor-state.test.ts`
+- Test: `packages/web/src/features/workspace/atoms/files.test.ts`
+- Test: `packages/web/src/features/workspace/actions/open-editor-state.test.ts`
+- Test: `packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx`
+- Test: `packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx`
+- Test: `packages/web/src/app.test.tsx`
+
+- [ ] **Step 1: Write the failing web path-based tests**
+
+Update `packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx` to render a path-keyed canvas tab without `canvasId`:
+
+```ts
+        <CanvasSurface
+          workspaceId="ws-1"
+          tab={{
+            kind: "canvas",
+            id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+            title: "Runtime Flow",
+            sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+          }}
+        />
+```
+
+Then assert:
+
+```ts
+    expect(frame).toHaveAttribute(
+      "src",
+      "/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc&refresh=0"
+    );
+```
+
+Update the refresh assertion:
+
+```ts
+      expect(dispatch).toHaveBeenCalledWith(
+        "canvas.render",
+        {
+          workspaceId: "ws-1",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+        },
+        undefined
+      );
+```
+
+Update the refresh-token assertion in the same test:
+
+```ts
+      expect(
+        store.get(
+          canvasRefreshTokenAtomFamily({
+            workspaceId: "ws-1",
+            sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+          })
+        )
+      ).toBe(1);
+```
+
+Update `packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx` to mount:
+
+```tsx
+      <MemoryRouter
+        initialEntries={[
+          "/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc",
+        ]}
+      >
+        <Routes>
+          <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+        </Routes>
+      </MemoryRouter>
+```
+
+and assert:
+
+```ts
+    expect(fetchCanvasDataMock).toHaveBeenCalledWith(
+      "ws-1",
+      ".coder-studio/canvases/runtime-flow.csc"
+    );
+```
+
+Update `packages/web/src/app.test.tsx` so the embedded canvas route test uses `/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc`.
+
+Add a new normalization test in `packages/web/src/features/workspace/atoms/files.test.ts`:
+
+```ts
+  it("deduplicates canvas tabs by sourcePath", () => {
+    expect(
+      normalizeWorkspaceEditorTabs([
+        {
+          kind: "canvas",
+          id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+          title: "Runtime Flow",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+        },
+        {
+          kind: "canvas",
+          id: "canvas:legacy-id",
+          title: "Runtime Flow",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+          canvasId: "canvas-1",
+        },
+      ])
+    ).toHaveLength(1);
+  });
+```
+
+- [ ] **Step 2: Run the web tests to verify they fail**
+
+Run: `pnpm --dir packages/web exec vitest run src/features/workspace/atoms/files.test.ts src/features/workspace/actions/open-editor-state.test.ts src/features/code-editor/views/shared/canvas-surface.test.tsx src/features/canvas/routes/embedded-canvas-route.test.tsx src/app.test.tsx`
+
+Expected: FAIL because the web still keys tabs and fetch URLs by `canvasId`.
+
+- [ ] **Step 3: Add path-based canvas helpers and route/query handling**
+
+In `packages/web/src/features/workspace/atoms/files.ts`, add file-type helpers and a tab factory:
+
+```ts
+const CANVAS_SOURCE_EXTENSION_PATTERN = /\.csc$/i;
+
+export function isCanvasSourcePath(path: string): boolean {
+  return CANVAS_SOURCE_EXTENSION_PATTERN.test(path);
+}
+
+function deriveCanvasTabTitle(sourcePath: string): string {
+  const fileName = sourcePath.split("/").pop() ?? sourcePath;
+  return fileName.replace(/\.csc$/i, "");
+}
+
+export function createWorkspaceCanvasEditorTab(input: {
+  sourcePath: string;
+  title?: string;
+  artifactType?: "architecture_canvas" | "report_canvas";
+  canvasId?: string;
+}): WorkspaceCanvasEditorTab {
+  const sourcePath = input.sourcePath.trim();
+  return {
+    kind: "canvas",
+    id: `canvas:${sourcePath}`,
+    title: input.title?.trim() || deriveCanvasTabTitle(sourcePath),
+    sourcePath,
+    ...(input.artifactType ? { artifactType: input.artifactType } : {}),
+    ...(input.canvasId ? { canvasId: input.canvasId } : {}),
+  };
+}
+```
+
+Also switch canvas normalization and dedupe to `sourcePath`, and change the refresh token key:
+
+```ts
+export interface CanvasRefreshTokenKey {
+  workspaceId: string;
+  sourcePath: string;
+}
+
+export const canvasRefreshTokenAtomFamily = atomFamily(
+  (_key: CanvasRefreshTokenKey) => atom<number>(0),
+  (left, right) => left.workspaceId === right.workspaceId && left.sourcePath === right.sourcePath
+);
+```
+
+In `packages/web/src/features/canvas/api.ts`, fetch by query:
+
+```ts
+export async function fetchCanvasData(
+  workspaceId: string,
+  sourcePath: string
+): Promise<CanvasDataResponse> {
+  const query = new URLSearchParams({ sourcePath });
+  const response = await fetch(`/api/canvas/${encodeURIComponent(workspaceId)}/data?${query}`, {
+    credentials: "include",
+  });
+
+  return readJson(response);
+}
+```
+
+In `packages/web/src/features/canvas/routes/embedded-canvas-route.tsx`, read `sourcePath` from `useSearchParams()` and update the missing-param error string:
+
+```ts
+  const { workspaceId } = useParams<{ workspaceId: string }>();
+  const [searchParams] = useSearchParams();
+  const sourcePath = searchParams.get("sourcePath");
+
+  if (!workspaceId || !sourcePath) {
+    setData(null);
+    setError("Canvas route is missing workspace or source path.");
+    setLoading(false);
+    return;
+  }
+```
+
+In `packages/web/src/features/code-editor/views/shared/canvas-surface.tsx`, key everything by `sourcePath`:
+
+```ts
+  const refreshToken = useAtomValue(
+    canvasRefreshTokenAtomFamily({ workspaceId, sourcePath: tab.sourcePath })
+  );
+  const setRefreshToken = useSetAtom(
+    canvasRefreshTokenAtomFamily({ workspaceId, sourcePath: tab.sourcePath })
+  );
+
+  if (!tab.sourcePath.trim()) {
+    return (
+      <EmptyState
+        className="git-diff-empty"
+        title={<p className="git-diff-empty-title">{t("code_editor.preview_unavailable")}</p>}
+      />
+    );
+  }
+
+  const handleRefresh = () => {
+    void dispatch<{ renderStatus: string; lastError: unknown | null }>("canvas.render", {
+      workspaceId,
+      sourcePath: tab.sourcePath,
+    }).then((result) => {
+      if (!result.ok) {
+        return;
+      }
+      setRefreshToken((current) => current + 1);
+    });
+  };
+
+  const src = `/embedded/canvas/${encodeURIComponent(workspaceId)}?sourcePath=${encodeURIComponent(tab.sourcePath)}&refresh=${encodeURIComponent(String(refreshToken))}`;
+```
+
+In `packages/web/src/app.tsx`, change the route:
+
+```tsx
+        <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+```
+
+- [ ] **Step 4: Run the web tests to verify they pass**
+
+Run: `pnpm --dir packages/web exec vitest run src/features/workspace/atoms/files.test.ts src/features/workspace/actions/open-editor-state.test.ts src/features/code-editor/views/shared/canvas-surface.test.tsx src/features/canvas/routes/embedded-canvas-route.test.tsx src/app.test.tsx`
+
+Expected: PASS with source-path-based embedded canvas routes.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/web/src/features/workspace/atoms/files.ts packages/web/src/features/workspace/actions/open-editor-state.ts packages/web/src/features/code-editor/views/shared/canvas-surface.tsx packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx packages/web/src/features/canvas/api.ts packages/web/src/features/canvas/routes/embedded-canvas-route.tsx packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx packages/web/src/app.tsx packages/web/src/app.test.tsx packages/web/src/features/workspace/atoms/files.test.ts packages/web/src/features/workspace/actions/open-editor-state.test.ts
+git commit -m "feat: key canvas tabs and embedded routes by source path"
+```
+
+### Task 5: Open `.csc` Files Into Render Tabs by Default
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/actions/use-open-workspace-file.ts`
+- Modify: `packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/canvas-surface.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx`
+- Modify: `packages/web/src/features/ui-actions/use-ui-action-subscription.ts`
+- Modify: `packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx`
+- Modify: `packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx`
+- Test: `packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx`
+- Test: `packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx`
+- Test: `packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx`
+- Test: `packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx`
+
+- [ ] **Step 1: Write the failing `.csc` open tests**
+
+Add a new test in `packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx`:
+
+```ts
+  it("opens csc files as canvas tabs instead of text file tabs", async () => {
+    const sendCommand = vi.fn().mockResolvedValue({
+      id: "ws-test",
+      path: "/workspace",
+      targetRuntime: "native",
+      openedAt: 1,
+      lastActiveAt: 1,
+      uiState: {
+        leftPanelWidth: 280,
+        bottomPanelHeight: 200,
+        focusMode: false,
+      },
+    });
+
+    const store = createStore();
+    seedWorkspace(store);
+    store.set(wsClientAtom, { sendCommand } as never);
+
+    const { result } = renderHook(() => useOpenWorkspaceFile("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.openWorkspaceFile({
+        workspaceId: "ws-test",
+        path: ".coder-studio/canvases/runtime-flow.csc",
+        source: "manual",
+      });
+    });
+
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBeNull();
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([]);
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+        title: "runtime-flow",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      },
+    ]);
+  });
+```
+
+Add a source-view override test in the same file:
+
+```ts
+  it("opens csc files as text when source view is explicitly requested", async () => {
+    const store = createStore();
+    seedWorkspace(store);
+
+    const { result } = renderHook(() => useOpenWorkspaceFile("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.openWorkspaceFile(
+        {
+          workspaceId: "ws-test",
+          path: ".coder-studio/canvases/runtime-flow.csc",
+          source: "manual",
+        },
+        { preferCanvasRender: false }
+      );
+    });
+
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe(
+      ".coder-studio/canvases/runtime-flow.csc"
+    );
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([
+      ".coder-studio/canvases/runtime-flow.csc",
+    ]);
+  });
+```
+
+Update `packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx` so `canvas.open` expectations key by `sourcePath`:
+
+```ts
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+        canvasId: "canvas-1",
+      },
+```
+
+Update `packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx` so the shared `canvasTab` fixture uses `id: "canvas:.coder-studio/canvases/runtime-flow.csc"` and no assertion depends on `canvasId`.
+
+Update `packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx` so `Open Source` explicitly requests source view:
+
+```ts
+    expect(openWorkspaceFileMock).toHaveBeenCalledWith(
+      {
+        workspaceId: "ws-1",
+        path: ".coder-studio/canvases/runtime-flow.csc",
+        source: "manual",
+      },
+      { preferCanvasRender: false }
+    );
+```
+
+- [ ] **Step 2: Run the web tests to verify they fail**
+
+Run: `pnpm --dir packages/web exec vitest run src/features/workspace/actions/use-open-workspace-file.test.tsx src/features/code-editor/views/shared/canvas-surface.test.tsx src/features/ui-actions/use-ui-action-subscription.test.tsx src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx`
+
+Expected: FAIL because `.csc` still opens as a normal file and canvas tabs are still replaced by `canvasId`.
+
+- [ ] **Step 3: Intercept `.csc` opens by default, but preserve explicit source opens**
+
+In `packages/web/src/features/workspace/actions/use-open-workspace-file.ts`, intercept before the regular `openLocation()` flow:
+
+```ts
+interface OpenWorkspaceFileOptions {
+  targetDraftPaneId?: string;
+  preferCanvasRender?: boolean;
+}
+
+import {
+  activeEditorTabAtomFamily,
+  activeFilePathAtomFamily,
+  createWorkspaceCanvasEditorTab,
+  editorViewVisibleAtomFamily,
+  isCanvasSourcePath,
+  openEditorTabsAtomFamily,
+} from "../atoms";
+
+// inside the standalone editor branch, before setEditorMode/openLocation
+      if (options.preferCanvasRender !== false && isCanvasSourcePath(input.path)) {
+        setFocusedEditorPaneId(null);
+        if (activeEditorPaneId && !paneLayoutHasEditorPaneId(paneLayout, activeEditorPaneId)) {
+          setActiveEditorPaneId(null);
+        }
+
+        const nextCanvasTab = createWorkspaceCanvasEditorTab({ sourcePath: input.path });
+        const currentTabs = store.get(openEditorTabsAtomFamily(workspaceId));
+        const nextTabs = [
+          ...currentTabs.filter(
+            (tab) => tab.kind !== "canvas" || tab.sourcePath !== nextCanvasTab.sourcePath
+          ),
+          nextCanvasTab,
+        ];
+
+        store.set(activeFilePathAtomFamily(workspaceId), null);
+        store.set(editorViewVisibleAtomFamily(workspaceId), true);
+        store.set(openEditorTabsAtomFamily(workspaceId), nextTabs);
+        store.set(activeEditorTabAtomFamily(workspaceId), nextCanvasTab);
+        await persistUiState({
+          editorViewVisible: true,
+          openEditorTabs: nextTabs,
+          activeEditorTab: nextCanvasTab,
+          activeEditorPath: null,
+        });
+        return;
+      }
+```
+
+In `packages/web/src/features/code-editor/views/shared/canvas-surface.tsx`, keep `Open Source` on the same `.csc` file but bypass the default renderer:
+
+```ts
+  const handleOpenSource = () => {
+    void openWorkspaceFile(
+      {
+        workspaceId,
+        path: tab.sourcePath,
+        source: "manual",
+      },
+      { preferCanvasRender: false }
+    );
+  };
+```
+
+In `packages/web/src/features/ui-actions/use-ui-action-subscription.ts`, replace the inline tab object with the shared helper and dedupe by `sourcePath`:
+
+```ts
+      const nextCanvasTab = createWorkspaceCanvasEditorTab({
+        sourcePath: event.intent.sourcePath,
+        title: event.intent.title,
+        artifactType: event.intent.artifactType,
+        canvasId: event.intent.canvasId,
+      });
+
+      const existingIndex = currentTabs.findIndex(
+        (tab) => tab.kind === "canvas" && tab.sourcePath === nextCanvasTab.sourcePath
+      );
+```
+
+- [ ] **Step 4: Run the web tests to verify they pass**
+
+Run: `pnpm --dir packages/web exec vitest run src/features/workspace/actions/use-open-workspace-file.test.tsx src/features/code-editor/views/shared/canvas-surface.test.tsx src/features/ui-actions/use-ui-action-subscription.test.tsx src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx`
+
+Expected: PASS with `.csc` opening directly into render tabs.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/web/src/features/workspace/actions/use-open-workspace-file.ts packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx packages/web/src/features/code-editor/views/shared/canvas-surface.tsx packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx packages/web/src/features/ui-actions/use-ui-action-subscription.ts packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx
+git commit -m "feat: open csc files as canvas render tabs"
+```
+
+### Task 6: Align Rename/Delete Semantics and Compatibility Metadata With Normal Files
+
+**Files:**
+- Modify: `packages/server/src/storage/repositories/canvas-repo.ts`
+- Modify: `packages/server/src/storage/repositories/canvas-repo.test.ts`
+- Modify: `packages/server/src/canvas/service.ts`
+- Modify: `packages/server/src/commands/file.ts`
+- Modify: `packages/server/src/__tests__/file-commands.test.ts`
+- Modify: `packages/web/src/features/workspace/actions/use-file-actions.ts`
+- Modify: `packages/web/src/features/workspace/actions/use-file-actions.test.tsx`
+- Modify: `packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx`
+- Test: `packages/server/src/storage/repositories/canvas-repo.test.ts`
+- Test: `packages/server/src/__tests__/file-commands.test.ts`
+- Test: `packages/web/src/features/workspace/actions/use-file-actions.test.tsx`
+- Test: `packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx`
+
+- [ ] **Step 1: Write the failing rename/delete tests**
+
+Add a repo rewrite test in `packages/server/src/storage/repositories/canvas-repo.test.ts`:
+
+```ts
+  it("rewrites and removes records by source path", () => {
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      artifactType: "architecture_canvas",
+      title: "Runtime Flow",
+      updatedAt: 100,
+      renderStatus: "ready",
+      lastError: null,
+    });
+
+    repo.rewriteSourcePaths("ws-1", ".coder-studio/canvases/runtime-flow.csc", ".coder-studio/canvases/runtime-overview.csc");
+    expect(repo.get("ws-1", "canvas-1")?.sourcePath).toBe(
+      ".coder-studio/canvases/runtime-overview.csc"
+    );
+
+    repo.deleteBySourcePath("ws-1", ".coder-studio/canvases/runtime-overview.csc");
+    expect(repo.get("ws-1", "canvas-1")).toBeUndefined();
+  });
+```
+
+In `packages/server/src/__tests__/file-commands.test.ts`, add the canvas imports:
+
+```ts
+import { CanvasService } from "../canvas/service.js";
+import { CanvasRepo } from "../storage/repositories/canvas-repo.js";
+```
+
+Then extend `beforeEach()` after `workspaceId = workspace.id;`:
+
+```ts
+    const canvasRepo = new CanvasRepo({ rootDir: join(testDir, ".state", "canvases") });
+    const canvasService = new CanvasService({ canvasRepo, now: () => 1000 });
+    ctx = {
+      ...ctx,
+      canvasService,
+    } as CommandContext;
+```
+
+Then add a file-command repo-sync test after the existing rename assertions:
+
+```ts
+
+  it("rewrites canvas compatibility records when csc files are renamed", async () => {
+    const created = await ctx.canvasService!.create({
+      workspaceId,
+      workspaceRootPath: testDir,
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      document: {
+        summary: "How requests move.",
+        diagram: {
+          dsl: "mermaid",
+          source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+        },
+        annotations: [],
+      },
+    });
+
+    await dispatch(
+      {
+        kind: "command",
+        id: "file-rename-canvas-1",
+        op: "file.rename",
+        args: {
+          workspaceId,
+          fromPath: created.record.sourcePath,
+          toPath: ".coder-studio/canvases/runtime-overview.csc",
+        },
+      },
+      ctx
+    );
+
+    expect(ctx.canvasService?.getRecord(workspaceId, created.record.id)?.sourcePath).toBe(
+      ".coder-studio/canvases/runtime-overview.csc"
+    );
+  });
+```
+
+Add a rename test in `packages/web/src/features/workspace/actions/use-file-actions.test.tsx`:
+
+```ts
+  it("rewrites open canvas tabs when a csc file is renamed", async () => {
+    const store = createStore();
+    const sendCommand = vi.fn(
+      async (op: string, args?: { workspaceId?: string; uiState?: Record<string, unknown> }) => {
+        if (op === "file.rename") {
+          return undefined;
+        }
+
+        if (op === "workspace.uiState.set") {
+          const workspaceId = args?.workspaceId ?? "ws-test";
+          const workspace = store.get(workspacesAtom)[workspaceId];
+          return {
+            id: workspaceId,
+            path: workspace?.path ?? "/workspace",
+            targetRuntime: workspace?.targetRuntime ?? "native",
+            openedAt: workspace?.openedAt ?? 1,
+            lastActiveAt: workspace?.lastActiveAt ?? 1,
+            uiState: args?.uiState,
+          };
+        }
+
+        if (op === "file.readTree") {
+          return { path: "/workspace", children: [] };
+        }
+
+        throw new Error(`Unexpected command: ${op}`);
+      }
+    );
+
+    seedWorkspace(store);
+    store.set(wsClientAtom, { sendCommand } as never);
+    store.set(fileTreeAtomFamily("ws-test"), new Map([[".", []]]));
+    store.set(openEditorTabsAtomFamily("ws-test"), [
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+        title: "Runtime Flow",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-test"), {
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+      title: "Runtime Flow",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+
+    const { result } = renderHook(() => useFileActions({ workspaceId: "ws-test" }), {
+      wrapper: wrapperFor(store),
+    });
+
+    act(() => {
+      result.current.openRenameDialog({
+        path: ".coder-studio/canvases/runtime-flow.csc",
+        name: "runtime-flow.csc",
+        kind: "file",
+      });
+      result.current.updateRenameDraft("runtime-overview.csc");
+    });
+
+    await act(async () => {
+      await result.current.submitRenameDialog();
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/runtime-overview.csc",
+        title: "Runtime Flow",
+        sourcePath: ".coder-studio/canvases/runtime-overview.csc",
+      },
+    ]);
+    expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual({
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/runtime-overview.csc",
+      title: "Runtime Flow",
+      sourcePath: ".coder-studio/canvases/runtime-overview.csc",
+    });
+  });
+```
+
+Add a delete test in the same file that closes the render tab when the `.csc` file is deleted:
+
+```ts
+  it("closes open canvas tabs when a csc file is deleted", async () => {
+    const store = createStore();
+    const sendCommand = vi.fn(
+      async (op: string, args?: { workspaceId?: string; uiState?: Record<string, unknown> }) => {
+        if (op === "file.delete") {
+          return undefined;
+        }
+
+        if (op === "workspace.uiState.set") {
+          const workspaceId = args?.workspaceId ?? "ws-test";
+          const workspace = store.get(workspacesAtom)[workspaceId];
+          return {
+            id: workspaceId,
+            path: workspace?.path ?? "/workspace",
+            targetRuntime: workspace?.targetRuntime ?? "native",
+            openedAt: workspace?.openedAt ?? 1,
+            lastActiveAt: workspace?.lastActiveAt ?? 1,
+            uiState: args?.uiState,
+          };
+        }
+
+        if (op === "file.readTree") {
+          return { path: "/workspace", children: [] };
+        }
+
+        throw new Error(`Unexpected command: ${op}`);
+      }
+    );
+
+    seedWorkspace(store);
+    store.set(wsClientAtom, { sendCommand } as never);
+    store.set(fileTreeAtomFamily("ws-test"), new Map([[".", []]]));
+    store.set(openEditorTabsAtomFamily("ws-test"), [
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+        title: "Runtime Flow",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-test"), {
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+      title: "Runtime Flow",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+
+    const { result } = renderHook(() => useFileActions({ workspaceId: "ws-test" }), {
+      wrapper: wrapperFor(store),
+    });
+
+    act(() => {
+      result.current.requestDelete({
+        path: ".coder-studio/canvases/runtime-flow.csc",
+        name: "runtime-flow.csc",
+        error: null,
+      });
+    });
+
+    await act(async () => {
+      await result.current.confirmDelete();
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([]);
+    expect(store.get(activeEditorTabAtomFamily("ws-test"))).toBeNull();
+  });
+```
+
+Update `packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx` so its canvas helper and expectations use source-path identity:
+
+```ts
+function canvasTab(sourcePath: string, title: string) {
+  return {
+    kind: "canvas" as const,
+    id: `canvas:${sourcePath}`,
+    title,
+    sourcePath,
+  };
+}
+
+// then use:
+canvasTab(".coder-studio/canvases/runtime-flow.csc", "Runtime Flow")
+```
+
+- [ ] **Step 2: Run the rename/delete tests to verify they fail**
+
+Run: `pnpm --dir packages/server exec vitest run src/storage/repositories/canvas-repo.test.ts src/__tests__/file-commands.test.ts`
+Run: `pnpm --dir packages/web exec vitest run src/features/workspace/actions/use-file-actions.test.tsx src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx`
+
+Expected: FAIL because neither the server repo nor the web tab state currently rewrites canvas paths.
+
+- [ ] **Step 3: Add repo sync hooks and path-based tab rewrite/remove helpers**
+
+In `packages/server/src/storage/repositories/canvas-repo.ts`, add path rewrite/delete helpers:
+
+```ts
+  rewriteSourcePaths(workspaceId: string, fromPath: string, toPath: string): void {
+    const file = this.readWorkspaceFile(workspaceId);
+    let changed = false;
+
+    for (const [id, record] of Object.entries(file.canvases)) {
+      if (record.sourcePath === fromPath) {
+        file.canvases[id] = { ...record, sourcePath: toPath };
+        changed = true;
+        continue;
+      }
+
+      if (record.sourcePath.startsWith(`${fromPath}/`)) {
+        file.canvases[id] = {
+          ...record,
+          sourcePath: `${toPath}${record.sourcePath.slice(fromPath.length)}`,
+        };
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      this.writeWorkspaceFile(file);
+    }
+  }
+
+  deleteBySourcePath(workspaceId: string, deletedPath: string): void {
+    const file = this.readWorkspaceFile(workspaceId);
+    const nextEntries = Object.entries(file.canvases).filter(([, record]) => {
+      return (
+        record.sourcePath !== deletedPath &&
+        !record.sourcePath.startsWith(`${deletedPath}/`)
+      );
+    });
+
+    file.canvases = Object.fromEntries(nextEntries);
+    this.writeWorkspaceFile(file);
+  }
+```
+
+Expose minimal rename/delete sync hooks from `packages/server/src/canvas/service.ts`:
+
+```ts
+  handleWorkspaceRename(workspaceId: string, fromPath: string, toPath: string): void {
+    this.options.canvasRepo.rewriteSourcePaths(workspaceId, fromPath, toPath);
+  }
+
+  handleWorkspaceDelete(workspaceId: string, deletedPath: string): void {
+    this.options.canvasRepo.deleteBySourcePath(workspaceId, deletedPath);
+  }
+```
+
+Call those hooks in `packages/server/src/commands/file.ts`:
+
+```ts
+      await deleteEntry(workspace.path, args.path);
+      ctx.canvasService?.handleWorkspaceDelete(args.workspaceId, args.path);
+```
+
+```ts
+      await renameEntry(workspace.path, args.fromPath, args.toPath);
+      ctx.canvasService?.handleWorkspaceRename(args.workspaceId, args.fromPath, args.toPath);
+```
+
+In `packages/web/src/features/workspace/actions/use-file-actions.ts`, rewrite or remove canvas tabs alongside file paths:
+
+```ts
+function rewriteCanvasTabs(
+  tabs: WorkspaceEditorTab[],
+  fromPath: string,
+  toPath: string
+): WorkspaceEditorTab[] {
+  return tabs.map((tab) =>
+    tab.kind === "canvas" && isSameOrDescendantPath(tab.sourcePath, fromPath)
+      ? {
+          ...tab,
+          sourcePath: rewriteDescendantPath(tab.sourcePath, fromPath, toPath),
+          id: `canvas:${rewriteDescendantPath(tab.sourcePath, fromPath, toPath)}`,
+        }
+      : tab
+  );
+}
+
+function removeDeletedCanvasTabs(
+  tabs: WorkspaceEditorTab[],
+  deletedPath: string
+): WorkspaceEditorTab[] {
+  return tabs.filter(
+    (tab) => tab.kind !== "canvas" || !isSameOrDescendantPath(tab.sourcePath, deletedPath)
+  );
+}
+```
+
+Apply those helpers in both rename and delete paths and persist `openEditorTabs` plus `activeEditorTab` with the rewritten state.
+
+- [ ] **Step 4: Run the rename/delete tests to verify they pass**
+
+Run: `pnpm --dir packages/server exec vitest run src/storage/repositories/canvas-repo.test.ts src/__tests__/file-commands.test.ts`
+Run: `pnpm --dir packages/web exec vitest run src/features/workspace/actions/use-file-actions.test.tsx src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx`
+
+Expected: PASS with both compatibility metadata and open canvas tabs tracking file renames/deletes.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/storage/repositories/canvas-repo.ts packages/server/src/storage/repositories/canvas-repo.test.ts packages/server/src/canvas/service.ts packages/server/src/commands/file.ts packages/server/src/__tests__/file-commands.test.ts packages/web/src/features/workspace/actions/use-file-actions.ts packages/web/src/features/workspace/actions/use-file-actions.test.tsx packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx
+git commit -m "feat: align canvas rename and delete semantics with files"
+```
+
+### Task 7: Update Builtin Canvas Skill Guidance and `.csc` Examples
+
+**Files:**
+- Modify: `packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts`
+- Modify: `packages/server/src/__tests__/skills/builtin-registry.test.ts`
+- Modify: `packages/server/src/__tests__/server-builtin-skills-wiring.test.ts`
+- Modify: `packages/cli/src/bin.test.ts`
+- Test: `packages/server/src/__tests__/skills/builtin-registry.test.ts`
+- Test: `packages/server/src/__tests__/server-builtin-skills-wiring.test.ts`
+- Test: `packages/cli/src/bin.test.ts`
+
+- [ ] **Step 1: Write the failing skill and example tests**
+
+Update `packages/server/src/__tests__/skills/builtin-registry.test.ts`:
+
+```ts
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      'Always use a meaningful title such as "Runtime Request Flow" or "Workspace Audit Summary".'
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      "coder-studio ui open-file --path .coder-studio/canvases/runtime-flow.csc --json"
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(".coder-studio/canvases/<slug>.csc");
+```
+
+Update `packages/server/src/__tests__/server-builtin-skills-wiring.test.ts` with the same expectations against the materialized `SKILL.md`.
+
+Update the example strings in `packages/cli/src/bin.test.ts` so the `--source-path` examples use `.csc`:
+
+```ts
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+```
+
+- [ ] **Step 2: Run the skill and CLI tests to verify they fail**
+
+Run: `pnpm --dir packages/server exec vitest run src/__tests__/skills/builtin-registry.test.ts src/__tests__/server-builtin-skills-wiring.test.ts`
+Run: `pnpm --dir packages/cli exec vitest run src/bin.test.ts`
+
+Expected: FAIL because the builtin skill still documents `.canvas.json`, `ui open-canvas`, and has no meaningful-title guidance.
+
+- [ ] **Step 3: Rewrite the builtin skill content for file-first usage**
+
+In `packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts`, update the content strings so create guidance explicitly requires meaningful titles:
+
+```ts
+  "Always use a meaningful title that tells the user what the canvas is for. Good examples: `Runtime Request Flow`, `Agent Tooling Overview`, `Workspace Audit Summary`.",
+  "Do not use generic names such as `Canvas`, `Diagram`, `Architecture`, or `Untitled`.",
+```
+
+Replace the “Open An Existing Canvas” guidance with a file-first flow:
+
+```ts
+  "List canvases first when you need the saved file path:",
+  "",
+  "```bash",
+  "coder-studio canvas list --workspace <workspace-id> --json",
+  "```",
+  "",
+  "Then open the `.csc` file through the normal file-open path:",
+  "",
+  "```bash",
+  "coder-studio ui open-file --workspace <workspace-id> --path .coder-studio/canvases/runtime-flow.csc --json",
+  "```",
+```
+
+Update the notes block to mention `.csc`:
+
+```ts
+  "- canvas source is stored as `.coder-studio/canvases/<slug>.csc` in the workspace",
+```
+
+Do not remove `ui open-canvas` support from the product in this task; only stop teaching it as the primary path.
+
+- [ ] **Step 4: Run the skill and CLI tests to verify they pass**
+
+Run: `pnpm --dir packages/server exec vitest run src/__tests__/skills/builtin-registry.test.ts src/__tests__/server-builtin-skills-wiring.test.ts`
+Run: `pnpm --dir packages/cli exec vitest run src/bin.test.ts`
+
+Expected: PASS with file-first `.csc` skill guidance and updated example strings.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts packages/server/src/__tests__/skills/builtin-registry.test.ts packages/server/src/__tests__/server-builtin-skills-wiring.test.ts packages/cli/src/bin.test.ts
+git commit -m "docs: teach the canvas skill to use meaningful csc titles"
+```
diff --git a/docs/superpowers/plans/2026-06-24-terminal-profiles.md b/docs/superpowers/plans/2026-06-24-terminal-profiles.md
new file mode 100644
index 000000000..c8f578af0
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-24-terminal-profiles.md
@@ -0,0 +1,1398 @@
+# Terminal Profiles Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build server-owned terminal profiles with a configurable default profile, explicit per-launch profile selection, WSL-aware Windows behavior, and VS Code-style terminal creation UI in both the toolbar and settings.
+
+**Architecture:** Keep profile detection, default resolution, custom profile merging, and launch-spec construction on the server. Expose a host-level `terminal.profiles.list` command plus a host-level `terminal.create` wrapper that resolves `profileId` and delegates to a narrow runtime spawn command. On the web side, reuse that DTO in a desktop split button, a mobile chooser sheet, and settings controls for default/custom profiles.
+
+**Tech Stack:** TypeScript, Zod, pnpm workspace, Vitest, React 19, Jotai, existing websocket host/runtime command registries.
+
+---
+
+## File Map
+
+- Create: `packages/core/src/domain/terminal-profiles.ts` — shared terminal profile DTOs and persisted custom profile shape.
+- Modify: `packages/core/src/index.ts` — export the new DTO module.
+- Create: `packages/server/src/terminal-profiles/detect.ts` — detect built-in native shells and WSL distros.
+- Create: `packages/server/src/terminal-profiles/registry.ts` — merge detected + custom profiles, resolve defaults, and build launch specs.
+- Create: `packages/server/src/terminal-profiles/wsl.ts` — WSL distro parsing and Windows-path-to-WSL-path conversion.
+- Create: `packages/server/src/terminal-profiles/__tests__/registry.test.ts` — unit coverage for detection-independent resolution logic.
+- Modify: `packages/server/src/commands/terminal.ts` — add host `terminal.profiles.list`, move client-facing `terminal.create` to host orchestration, add runtime `terminal.spawn`.
+- Modify: `packages/server/src/commands/settings.ts` — add `terminal.defaultProfileId` and `terminal.profiles` schema + validation.
+- Modify: `packages/server/src/commands/settings.test.ts` — cover terminal settings persistence and validation.
+- Modify: `packages/server/src/__tests__/terminal-commands.test.ts` — cover profile listing, explicit-profile create, unavailable-profile failures, and default fallback behavior.
+- Create: `packages/web/src/features/terminal-panel/actions/use-terminal-profiles.ts` — fetch/cache terminal profiles for terminal UI.
+- Modify: `packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts` — accept optional `profileId`.
+- Modify: `packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx` — assert `profileId` dispatch behavior.
+- Modify: `packages/web/src/features/terminal-panel/actions/use-terminal-actions.ts` — expose profile data and create handlers to the panel.
+- Create: `packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx` — desktop split button + mobile chooser.
+- Modify: `packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx` — replace the single create action with the profile-aware launcher.
+- Modify: `packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx` — cover desktop default launch and alternate-profile selection.
+- Create: `packages/web/src/features/settings/components/terminal-profile-settings.tsx` — default-profile picker and custom-profile editor.
+- Modify: `packages/web/src/features/settings/components/settings-page.tsx` — load terminal settings/profile list state and render the new terminal profile settings block inside `GeneralSettings`.
+- Modify: `packages/web/src/features/settings/components/settings-page.test.tsx` — cover settings hydration and saving for terminal profiles.
+- Modify: `packages/web/src/locales/en.json` — add terminal profile labels and validation copy.
+- Modify: `packages/web/src/locales/zh.json` — add matching Chinese strings.
+
+## Task 1: Shared DTOs and Server Terminal Profile Registry
+
+**Files:**
+- Create: `packages/core/src/domain/terminal-profiles.ts`
+- Modify: `packages/core/src/index.ts`
+- Create: `packages/server/src/terminal-profiles/detect.ts`
+- Create: `packages/server/src/terminal-profiles/registry.ts`
+- Create: `packages/server/src/terminal-profiles/wsl.ts`
+- Create: `packages/server/src/terminal-profiles/__tests__/registry.test.ts`
+- Test: `packages/server/src/terminal-profiles/__tests__/registry.test.ts`
+
+- [ ] **Step 1: Write the failing registry tests first**
+
+```ts
+import { describe, expect, it } from "vitest";
+import type { CustomTerminalProfile } from "@coder-studio/core";
+import { listTerminalProfiles, resolveTerminalLaunch } from "../registry.js";
+
+const customProfiles: CustomTerminalProfile[] = [
+  {
+    id: "custom:node-shell",
+    label: "Node Shell",
+    command: "node",
+    args: ["--interactive"],
+    icon: "terminal",
+  },
+];
+
+describe("terminal profile registry", () => {
+  it("keeps the configured default id while resolving a fallback available profile", async () => {
+    const result = await listTerminalProfiles({
+      platform: "linux",
+      shellPath: "/bin/zsh",
+      configuredDefaultProfileId: "detected:win:powershell",
+      customProfiles,
+      detectProfiles: async () => [
+        {
+          id: "detected:posix:zsh",
+          label: "zsh",
+          source: "detected",
+          runtime: "native",
+          icon: "terminal",
+          argv: ["/bin/zsh", "-i"],
+          cwdRuntime: "native",
+        },
+      ],
+    });
+
+    expect(result.configuredDefaultProfileId).toBe("detected:win:powershell");
+    expect(result.resolvedDefaultProfileId).toBe("detected:posix:zsh");
+    expect(result.profiles.map((profile) => profile.id)).toEqual([
+      "detected:posix:zsh",
+      "custom:node-shell",
+    ]);
+  });
+
+  it("throws for an explicitly requested unavailable profile instead of silently falling back", async () => {
+    await expect(
+      resolveTerminalLaunch({
+        platform: "linux",
+        shellPath: "/bin/zsh",
+        configuredDefaultProfileId: "detected:posix:zsh",
+        requestedProfileId: "detected:win:pwsh",
+        customProfiles: [],
+        workspacePath: "/repo/app",
+        detectProfiles: async () => [
+          {
+            id: "detected:posix:zsh",
+            label: "zsh",
+            source: "detected",
+            runtime: "native",
+            icon: "terminal",
+            argv: ["/bin/zsh", "-i"],
+            cwdRuntime: "native",
+          },
+        ],
+      })
+    ).rejects.toMatchObject({
+      code: "terminal_profile_unavailable",
+      message: "Terminal profile unavailable: detected:win:pwsh",
+    });
+  });
+
+  it("builds a WSL launch spec with mapped cwd when the workspace is on a Windows drive", async () => {
+    const launch = await resolveTerminalLaunch({
+      platform: "win32",
+      configuredDefaultProfileId: "detected:win:wsl:Ubuntu-24.04",
+      workspacePath: "C:\\repo\\app",
+      customProfiles: [],
+      detectProfiles: async () => [
+        {
+          id: "detected:win:wsl:Ubuntu-24.04",
+          label: "Ubuntu-24.04",
+          source: "detected",
+          runtime: "wsl",
+          icon: "terminal",
+          argv: ["wsl.exe", "-d", "Ubuntu-24.04"],
+          cwdRuntime: "wsl",
+          wslDistro: "Ubuntu-24.04",
+        },
+      ],
+    });
+
+    expect(launch.argv).toEqual([
+      "wsl.exe",
+      "-d",
+      "Ubuntu-24.04",
+      "--cd",
+      "/mnt/c/repo/app",
+    ]);
+    expect(launch.cwd).toBe("C:\\repo\\app");
+    expect(launch.profileId).toBe("detected:win:wsl:Ubuntu-24.04");
+  });
+
+  it("falls back to the distro home when a WSL cwd cannot be mapped", async () => {
+    const launch = await resolveTerminalLaunch({
+      platform: "win32",
+      configuredDefaultProfileId: "detected:win:wsl:Ubuntu-24.04",
+      workspacePath: "\\\\wsl$\\Ubuntu-24.04\\repo\\app",
+      customProfiles: [],
+      detectProfiles: async () => [
+        {
+          id: "detected:win:wsl:Ubuntu-24.04",
+          label: "Ubuntu-24.04",
+          source: "detected",
+          runtime: "wsl",
+          icon: "terminal",
+          argv: ["wsl.exe", "-d", "Ubuntu-24.04"],
+          cwdRuntime: "wsl",
+          wslDistro: "Ubuntu-24.04",
+        },
+      ],
+    });
+
+    expect(launch.argv).toEqual(["wsl.exe", "-d", "Ubuntu-24.04"]);
+    expect(launch.cwd).toBe("\\\\wsl$\\Ubuntu-24.04\\repo\\app");
+  });
+});
+```
+
+- [ ] **Step 2: Run the new registry test and verify it fails for the missing module/functionality**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/terminal-profiles/__tests__/registry.test.ts`
+
+Expected: FAIL with a module-resolution or missing-export error for `../registry.js`, plus `0 passed`.
+
+- [ ] **Step 3: Add the shared DTOs and registry implementation**
+
+```ts
+// packages/core/src/domain/terminal-profiles.ts
+export type TerminalProfileSource = "detected" | "custom";
+export type TerminalProfileRuntime = "native" | "wsl";
+
+export interface TerminalProfile {
+  id: string;
+  label: string;
+  source: TerminalProfileSource;
+  runtime: TerminalProfileRuntime;
+  icon: string;
+}
+
+export interface CustomTerminalProfile {
+  id: `custom:${string}`;
+  label: string;
+  command: string;
+  args?: string[];
+  icon?: string;
+}
+
+export interface TerminalProfilesListResult {
+  profiles: TerminalProfile[];
+  configuredDefaultProfileId?: string;
+  resolvedDefaultProfileId: string | null;
+}
+```
+
+```ts
+// packages/server/src/terminal-profiles/wsl.ts
+import path from "node:path";
+
+export function toWslPath(windowsPath: string): string | null {
+  const parsed = path.win32.parse(windowsPath);
+  if (!parsed.root || !/^[A-Za-z]:\\$/.test(parsed.root)) {
+    return null;
+  }
+
+  const drive = parsed.root[0]!.toLowerCase();
+  const relative = windowsPath.slice(parsed.root.length).replace(/\\/g, "/");
+  return `/mnt/${drive}${relative ? `/${relative}` : ""}`;
+}
+
+export function appendWslCwd(argv: string[], mappedCwd: string | null): string[] {
+  if (!mappedCwd) {
+    return argv;
+  }
+  return [...argv, "--cd", mappedCwd];
+}
+```
+
+```ts
+// packages/server/src/terminal-profiles/registry.ts
+import type {
+  CustomTerminalProfile,
+  TerminalProfile,
+  TerminalProfilesListResult,
+} from "@coder-studio/core";
+import { detectTerminalProfiles, type DetectedTerminalProfile } from "./detect.js";
+import { appendWslCwd, toWslPath } from "./wsl.js";
+
+export interface ResolvedTerminalLaunch {
+  profileId: string;
+  title: string;
+  argv: string[];
+  cwd: string;
+}
+
+interface RegistryInput {
+  platform?: NodeJS.Platform;
+  shellPath?: string;
+  configuredDefaultProfileId?: string;
+  customProfiles: CustomTerminalProfile[];
+  workspacePath?: string;
+  detectProfiles?: () => Promise<DetectedTerminalProfile[]>;
+}
+
+export async function listTerminalProfiles(
+  input: RegistryInput
+): Promise<TerminalProfilesListResult> {
+  const detected = await (input.detectProfiles
+    ? input.detectProfiles()
+    : detectTerminalProfiles({
+        platform: input.platform,
+        shellPath: input.shellPath,
+      }));
+
+  const profiles: TerminalProfile[] = [
+    ...detected.map(toDto),
+    ...input.customProfiles.map((profile) => ({
+      id: profile.id,
+      label: profile.label,
+      source: "custom",
+      runtime: "native",
+      icon: profile.icon ?? "terminal",
+    })),
+  ];
+
+  const configuredDefaultProfileId = input.configuredDefaultProfileId;
+  const resolvedDefaultProfileId =
+    profiles.find((profile) => profile.id === configuredDefaultProfileId)?.id ??
+    profiles[0]?.id ??
+    null;
+
+  return {
+    profiles,
+    configuredDefaultProfileId,
+    resolvedDefaultProfileId,
+  };
+}
+
+export async function resolveTerminalLaunch(input: RegistryInput & { requestedProfileId?: string }) {
+  if (!input.workspacePath) {
+    throw new Error("workspacePath is required for resolveTerminalLaunch");
+  }
+
+  const detected = await (input.detectProfiles
+    ? input.detectProfiles()
+    : detectTerminalProfiles({
+        platform: input.platform,
+        shellPath: input.shellPath,
+      }));
+
+  const definitions = new Map<string, DetectedTerminalProfile | CustomTerminalProfile>(
+    detected.map((profile) => [profile.id, profile]).concat(input.customProfiles.map((profile) => [profile.id, profile]))
+  );
+
+  const summary = await listTerminalProfiles(input);
+  const targetId = input.requestedProfileId ?? summary.resolvedDefaultProfileId;
+
+  if (!targetId) {
+    throw {
+      code: "terminal_profile_unavailable",
+      message: "No terminal profiles are available on this machine",
+    };
+  }
+
+  const profile = definitions.get(targetId);
+  if (!profile) {
+    throw {
+      code: "terminal_profile_unavailable",
+      message: `Terminal profile unavailable: ${targetId}`,
+    };
+  }
+
+  if ("command" in profile) {
+    return {
+      profileId: profile.id,
+      title: profile.label,
+      argv: [profile.command, ...(profile.args ?? [])],
+      cwd: input.workspacePath,
+    } satisfies ResolvedTerminalLaunch;
+  }
+
+  if (profile.cwdRuntime === "wsl") {
+    return {
+      profileId: profile.id,
+      title: profile.label,
+      argv: appendWslCwd(profile.argv, toWslPath(input.workspacePath)),
+      cwd: input.workspacePath,
+    } satisfies ResolvedTerminalLaunch;
+  }
+
+  return {
+    profileId: profile.id,
+    title: profile.label,
+    argv: profile.argv,
+    cwd: input.workspacePath,
+  } satisfies ResolvedTerminalLaunch;
+}
+
+function toDto(profile: DetectedTerminalProfile): TerminalProfile {
+  return {
+    id: profile.id,
+    label: profile.label,
+    source: profile.source,
+    runtime: profile.runtime,
+    icon: profile.icon,
+  };
+}
+```
+
+- [ ] **Step 4: Run the registry test again and verify it passes**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/terminal-profiles/__tests__/registry.test.ts`
+
+Expected: PASS with `4 passed` and exit code `0`.
+
+- [ ] **Step 5: Commit only the Task 1 files**
+
+```bash
+git add packages/core/src/domain/terminal-profiles.ts packages/core/src/index.ts packages/server/src/terminal-profiles/detect.ts packages/server/src/terminal-profiles/registry.ts packages/server/src/terminal-profiles/wsl.ts packages/server/src/terminal-profiles/__tests__/registry.test.ts
+git commit -m "feat: add terminal profile registry"
+```
+
+## Task 2: Host Commands, Runtime Spawn Command, and Terminal Settings Schema
+
+**Files:**
+- Modify: `packages/server/src/commands/terminal.ts`
+- Modify: `packages/server/src/commands/settings.ts`
+- Modify: `packages/server/src/commands/settings.test.ts`
+- Modify: `packages/server/src/__tests__/terminal-commands.test.ts`
+- Test: `packages/server/src/commands/settings.test.ts`
+- Test: `packages/server/src/__tests__/terminal-commands.test.ts`
+
+- [ ] **Step 1: Write the failing command/settings tests**
+
+```ts
+it("returns terminal profiles with configured and resolved default ids", async () => {
+  const settingsRepo = new SettingsRepo({ filePath: join(tempDir, "settings.json") });
+  settingsRepo.set("terminal.defaultProfileId", "detected:win:powershell");
+  settingsRepo.set("terminal.profiles", [
+    {
+      id: "custom:node-shell",
+      label: "Node Shell",
+      command: "node",
+      args: ["--interactive"],
+      icon: "terminal",
+    },
+  ]);
+
+  const result = await dispatch(
+    {
+      kind: "command",
+      id: "terminal-profiles-list-1",
+      op: "terminal.profiles.list",
+      args: {},
+    },
+    createContext({ settingsRepo })
+  );
+
+  expect(result.ok).toBe(true);
+  expect(result.data).toMatchObject({
+    configuredDefaultProfileId: "detected:win:powershell",
+    resolvedDefaultProfileId: expect.any(String),
+  });
+});
+
+it("passes the requested profileId through terminal.create and errors when that profile is missing", async () => {
+  const settingsRepo = {
+    get: vi.fn((key: string) => {
+      if (key === "terminal.defaultProfileId") return "detected:posix:zsh";
+      if (key === "terminal.profiles") return [];
+      return undefined;
+    }),
+  } as never;
+
+  const missingResult = await dispatch(
+    {
+      kind: "command",
+      id: "terminal-create-missing-profile",
+      op: "terminal.create",
+      args: {
+        workspaceId: "ws-1",
+        profileId: "detected:win:pwsh",
+      },
+    },
+    createContext({ settingsRepo })
+  );
+
+  expect(missingResult.ok).toBe(false);
+  expect(missingResult.error).toMatchObject({
+    code: "terminal_profile_unavailable",
+  });
+});
+
+it("settings.update persists terminal.defaultProfileId and terminal.profiles", async () => {
+  const result = await dispatch(
+    {
+      kind: "command",
+      id: "settings-update-terminal-profiles",
+      op: "settings.update",
+      args: {
+        settings: {
+          terminal: {
+            defaultProfileId: "custom:node-shell",
+            profiles: [
+              {
+                id: "custom:node-shell",
+                label: "Node Shell",
+                command: "node",
+                args: ["--interactive"],
+                icon: "terminal",
+              },
+            ],
+          },
+        },
+      },
+    },
+    ctx
+  );
+
+  expect(result.ok).toBe(true);
+  expect(settingsRepo.get("terminal.defaultProfileId")).toBe("custom:node-shell");
+  expect(settingsRepo.get("terminal.profiles")).toEqual([
+    {
+      id: "custom:node-shell",
+      label: "Node Shell",
+      command: "node",
+      args: ["--interactive"],
+      icon: "terminal",
+    },
+  ]);
+});
+```
+
+- [ ] **Step 2: Run the command/settings tests and verify they fail for the new behavior**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/commands/settings.test.ts src/__tests__/terminal-commands.test.ts`
+
+Expected: FAIL with `unknown_op` for `terminal.profiles.list`, schema validation failures for `terminal.profiles`, and at least one assertion mismatch around `profileId`.
+
+- [ ] **Step 3: Implement the host commands and settings schema**
+
+```ts
+// packages/server/src/commands/settings.ts
+import type { CustomTerminalProfile } from "@coder-studio/core";
+
+const CustomTerminalProfileSchema = z.object({
+  id: z.string().regex(/^custom:/),
+  label: z.string().trim().min(1),
+  command: z.string().trim().min(1),
+  args: z.array(z.string()).optional(),
+  icon: z.string().trim().min(1).optional(),
+});
+
+const TerminalSettingsSchema = z
+  .object({
+    defaultProfileId: z.string().optional(),
+    profiles: z.array(CustomTerminalProfileSchema).optional(),
+  })
+  .superRefine((value, ctx) => {
+    const ids = new Set<string>();
+    for (const profile of value.profiles ?? []) {
+      if (ids.has(profile.id)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Duplicate terminal profile id: ${profile.id}`,
+          path: ["profiles"],
+        });
+      }
+      ids.add(profile.id);
+    }
+  });
+
+```diff
+ const SettingsSchema = z.object({
++  terminal: TerminalSettingsSchema.optional(),
+ });
+```
+
+```ts
+// packages/server/src/commands/terminal.ts
+registerCommand("terminal.profiles.list", z.object({}).default({}), async (_args, ctx) => {
+  return await listTerminalProfiles({
+    platform: process.platform,
+    shellPath: process.env.SHELL,
+    configuredDefaultProfileId: ctx.settingsRepo.get("terminal.defaultProfileId"),
+    customProfiles: (ctx.settingsRepo.get("terminal.profiles") as CustomTerminalProfile[]) ?? [],
+  });
+});
+
+registerRuntimeCommand(
+  "terminal.spawn",
+  z.object({
+    workspaceId: z.string(),
+    argv: z.array(z.string()).min(1),
+    title: z.string().min(1),
+    cwd: z.string().min(1),
+    cols: z.number().int().positive().optional(),
+    rows: z.number().int().positive().optional(),
+    themeBackground: z.string().regex(/^#[0-9a-fA-F]{3,8}$/).optional(),
+  }),
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      return ctx.terminalMgr.create({
+        workspaceId: args.workspaceId,
+        kind: "shell",
+        argv: args.argv,
+        title: args.title,
+        cwd: args.cwd,
+        cols: args.cols ?? 120,
+        rows: args.rows ?? 30,
+        themeBackground: args.themeBackground,
+      });
+    },
+  }
+);
+
+registerHostCommand(
+  "terminal.create",
+  z.object({
+    workspaceId: z.string(),
+    profileId: z.string().optional(),
+    cols: z.number().int().positive().optional(),
+    rows: z.number().int().positive().optional(),
+    cwdPath: z.string().optional(),
+    themeBackground: z.string().regex(/^#[0-9a-fA-F]{3,8}$/).optional(),
+  }),
+  async (args, ctx, meta) => {
+    const workspace = ctx.workspaceMgr.get(args.workspaceId);
+    if (!workspace) {
+      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+    }
+
+    const cwd = await resolveWorkspaceCwd(workspace.path, args.cwdPath);
+    const launch = await resolveTerminalLaunch({
+      platform: process.platform,
+      shellPath: process.env.SHELL,
+      configuredDefaultProfileId: ctx.settingsRepo.get("terminal.defaultProfileId"),
+      requestedProfileId: args.profileId,
+      customProfiles: (ctx.settingsRepo.get("terminal.profiles") as CustomTerminalProfile[]) ?? [],
+      workspacePath: cwd,
+    });
+
+    return await executeRuntimeCommandOnTarget(
+      "terminal.spawn",
+      {
+        workspaceId: args.workspaceId,
+        argv: launch.argv,
+        title: launch.title,
+        cwd: launch.cwd,
+        cols: args.cols,
+        rows: args.rows,
+        themeBackground: args.themeBackground,
+      },
+      ctx,
+      meta,
+      { kind: "workspace", workspaceId: args.workspaceId }
+    );
+  }
+);
+```
+
+- [ ] **Step 4: Run the server terminal/settings tests again and verify they pass**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/commands/settings.test.ts src/__tests__/terminal-commands.test.ts`
+
+Expected: PASS with all assertions green and exit code `0`.
+
+- [ ] **Step 5: Commit only the Task 2 files**
+
+```bash
+git add packages/server/src/commands/terminal.ts packages/server/src/commands/settings.ts packages/server/src/commands/settings.test.ts packages/server/src/__tests__/terminal-commands.test.ts
+git commit -m "feat: wire terminal profile commands"
+```
+
+## Task 3: Terminal Toolbar Profiles UX
+
+**Files:**
+- Create: `packages/web/src/features/terminal-panel/actions/use-terminal-profiles.ts`
+- Modify: `packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts`
+- Modify: `packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx`
+- Modify: `packages/web/src/features/terminal-panel/actions/use-terminal-actions.ts`
+- Create: `packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx`
+- Modify: `packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx`
+- Modify: `packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx`
+- Test: `packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx`
+- Test: `packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx`
+
+- [ ] **Step 1: Write the failing web tests first**
+
+```ts
+it("passes profileId to terminal.create when a non-default terminal profile is selected", async () => {
+  const sendCommand = vi.fn().mockResolvedValue({
+    id: "term_2",
+    workspaceId: "ws-test",
+    kind: "shell",
+    title: "Git Bash",
+    cwd: "/tmp/ws-test",
+    argv: ["bash"],
+    cols: 120,
+    rows: 30,
+    alive: true,
+    createdAt: 1,
+  });
+
+  const store = createStore();
+  store.set(localeAtom, "en");
+  store.set(wsClientAtom, { sendCommand } as never);
+
+  const { result } = renderHook(() => useCreateShellTerminal("ws-test"), {
+    wrapper: wrapperFor(store),
+  });
+
+  await act(async () => {
+    await result.current.createShellTerminal({ profileId: "detected:win:git-bash" });
+  });
+
+  expect(sendCommand).toHaveBeenCalledWith(
+    "terminal.create",
+    expect.objectContaining({
+      workspaceId: "ws-test",
+      profileId: "detected:win:git-bash",
+    }),
+    undefined
+  );
+});
+
+it("uses the resolved default profile from the primary toolbar button and opens the profile picker from the chevron", async () => {
+  const sendCommand = vi.fn().mockImplementation((op: string) => {
+    if (op === "terminal.list") return Promise.resolve([]);
+    if (op === "terminal.profiles.list") {
+      return Promise.resolve({
+        configuredDefaultProfileId: "detected:win:pwsh",
+        resolvedDefaultProfileId: "detected:win:pwsh",
+        profiles: [
+          { id: "detected:win:pwsh", label: "PowerShell", source: "detected", runtime: "native", icon: "terminal" },
+          { id: "detected:win:git-bash", label: "Git Bash", source: "detected", runtime: "native", icon: "terminal" },
+        ],
+      });
+    }
+    if (op === "terminal.create") {
+      return Promise.resolve({
+        id: "term_2",
+        workspaceId: "ws-test",
+        kind: "shell",
+        title: "PowerShell",
+        cwd: "/tmp/ws-test",
+        argv: ["pwsh"],
+        cols: 120,
+        rows: 30,
+        alive: true,
+        createdAt: 1,
+      });
+    }
+    return Promise.resolve(undefined);
+  });
+
+  render(
+    <Provider store={store}>
+      <TerminalPanel />
+    </Provider>
+  );
+
+  await user.click(screen.getByRole("button", { name: "New Terminal" }));
+  expect(sendCommand).toHaveBeenCalledWith(
+    "terminal.create",
+    expect.objectContaining({ profileId: "detected:win:pwsh" }),
+    undefined
+  );
+
+  await user.click(screen.getByRole("button", { name: "Choose Terminal Profile" }));
+  expect(await screen.findByText("Git Bash")).toBeInTheDocument();
+});
+```
+
+- [ ] **Step 2: Run the web terminal tests and verify they fail**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx src/features/terminal-panel/__tests__/terminal-panel.test.tsx`
+
+Expected: FAIL because `profileId` is absent from the create hook dispatch, `terminal.profiles.list` is never requested, and the chooser button does not exist yet.
+
+- [ ] **Step 3: Implement the terminal profile hook and split-button UI**
+
+```ts
+// packages/web/src/features/terminal-panel/actions/use-terminal-profiles.ts
+import type { TerminalProfile, TerminalProfilesListResult } from "@coder-studio/core";
+import { useAtomValue } from "jotai";
+import { useEffect, useState } from "react";
+import { dispatchCommandAtom } from "../../../atoms/connection";
+
+export function useTerminalProfiles() {
+  const dispatch = useAtomValue(dispatchCommandAtom);
+  const [data, setData] = useState<TerminalProfilesListResult>({
+    profiles: [],
+    resolvedDefaultProfileId: null,
+  });
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+
+    void dispatch<TerminalProfilesListResult>("terminal.profiles.list", {})
+      .then((result) => {
+        if (!cancelled && result.ok && result.data) {
+          setData(result.data);
+        }
+      })
+      .finally(() => {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [dispatch]);
+
+  const defaultProfile =
+    data.profiles.find((profile) => profile.id === data.resolvedDefaultProfileId) ?? null;
+
+  return {
+    profiles: data.profiles,
+    configuredDefaultProfileId: data.configuredDefaultProfileId,
+    resolvedDefaultProfileId: data.resolvedDefaultProfileId,
+    defaultProfile,
+    loading,
+  };
+}
+```
+
+```ts
+// packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts
+async createShellTerminal(args: { cwdPath?: string; profileId?: string } = {}) {
+  if (!workspaceId) {
+    pushToast({
+      kind: "warning",
+      title: t("terminal.create_unavailable_title"),
+      body: t("terminal.create_unavailable_body"),
+    });
+    return null;
+  }
+
+  try {
+    const result = await dispatch<TerminalDto>("terminal.create", {
+      workspaceId,
+      cwdPath: args.cwdPath,
+      profileId: args.profileId,
+      themeBackground,
+    });
+
+    if (!result.ok || !result.data) {
+      pushToast({
+        kind: "error",
+        title: t("terminal.create_failed_title"),
+        body: result.error?.message ?? t("terminal.create_failed_body"),
+      });
+      return null;
+    }
+
+    const terminal = result.data;
+    store.set(terminalMetaAtomFamily(terminal.id), toTerminalMeta(terminal));
+    store.set(terminalIdsAtomFamily(workspaceId), (current) =>
+      current.includes(terminal.id) ? current : [...current, terminal.id]
+    );
+    store.set(terminalActiveIdAtomFamily(workspaceId), terminal.id);
+    return terminal;
+  } catch (error) {
+    pushToast({
+      kind: "error",
+      title: t("terminal.create_failed_title"),
+      body: error instanceof Error ? error.message : t("terminal.create_failed_body"),
+    });
+    return null;
+  }
+}
+```
+
+```tsx
+// packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx
+import type { TerminalProfile } from "@coder-studio/core";
+import { ChevronDown } from "lucide-react";
+import { Button, IconButton, Popover, ThemedIcon, Tooltip } from "../../../../components/ui";
+import { MobileSelectSheet } from "../../../mobile-select";
+
+export function TerminalProfileCreateButton(props: {
+  mobile: boolean;
+  loading: boolean;
+  profiles: TerminalProfile[];
+  defaultProfile: TerminalProfile | null;
+  onCreate: (profileId?: string) => Promise<void>;
+}) {
+  if (props.mobile) {
+    return (
+      <>
+        <IconButton
+          aria-label="New Terminal"
+          icon={<ThemedIcon semantic="terminal.action.new" size={14} />}
+          onClick={() => void props.onCreate(props.defaultProfile?.id)}
+          size="sm"
+        />
+        <MobileSelectSheet
+          title="Terminal Profiles"
+          sections={[
+            {
+              kind: "actions",
+              id: "default-profile",
+              items: props.defaultProfile
+                ? [
+                    {
+                      id: "open-default-profile",
+                      label: `Open Default: ${props.defaultProfile.label}`,
+                      onAction: () => props.onCreate(props.defaultProfile?.id),
+                    },
+                  ]
+                : [],
+            },
+            {
+              kind: "options",
+              id: "other-profiles",
+              title: "Other Profiles",
+              items: props.profiles.map((profile) => ({
+                id: profile.id,
+                label: profile.label,
+                meta: profile.id === props.defaultProfile?.id ? "Default" : undefined,
+              })),
+            },
+          ]}
+          onSelect={(profileId) => props.onCreate(profileId)}
+          onClose={() => {}}
+        />
+      </>
+    );
+  }
+
+  return (
+    <div className="terminal-create-split">
+      <Tooltip content={props.defaultProfile ? `Open ${props.defaultProfile.label}` : "New Terminal"}>
+        <Button onClick={() => void props.onCreate(props.defaultProfile?.id)}>
+          <ThemedIcon semantic="terminal.action.new" size={14} />
+          <span>New Terminal</span>
+        </Button>
+      </Tooltip>
+      <Popover
+        title="Terminal Profiles"
+        content={
+          <>
+            {props.profiles.map((profile) => (
+              <button key={profile.id} type="button" onClick={() => void props.onCreate(profile.id)}>
+                {profile.label}
+              </button>
+            ))}
+          </>
+        }
+      >
+        <IconButton aria-label="Choose Terminal Profile" icon={<ChevronDown size={14} />} size="sm" />
+      </Popover>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 4: Run the web terminal tests again and verify they pass**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx src/features/terminal-panel/__tests__/terminal-panel.test.tsx`
+
+Expected: PASS with the hook and terminal panel assertions green.
+
+- [ ] **Step 5: Commit only the Task 3 files**
+
+```bash
+git add packages/web/src/features/terminal-panel/actions/use-terminal-profiles.ts packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx packages/web/src/features/terminal-panel/actions/use-terminal-actions.ts packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx
+git commit -m "feat: add terminal profile launcher ui"
+```
+
+## Task 4: Settings UI for Default and Custom Terminal Profiles
+
+**Files:**
+- Create: `packages/web/src/features/settings/components/terminal-profile-settings.tsx`
+- Modify: `packages/web/src/features/settings/components/settings-page.tsx`
+- Modify: `packages/web/src/features/settings/components/settings-page.test.tsx`
+- Modify: `packages/web/src/locales/en.json`
+- Modify: `packages/web/src/locales/zh.json`
+- Test: `packages/web/src/features/settings/components/settings-page.test.tsx`
+
+- [ ] **Step 1: Write the failing settings-page tests**
+
+```ts
+it("hydrates the terminal profile settings from settings.get and terminal.profiles.list", async () => {
+  const sendCommand = createDefaultCommandHandler({
+    settings: {
+      "terminal.defaultProfileId": "custom:node-shell",
+      "terminal.profiles": [
+        {
+          id: "custom:node-shell",
+          label: "Node Shell",
+          command: "node",
+          args: ["--interactive"],
+          icon: "terminal",
+        },
+      ],
+    },
+  }).mockImplementation(async (op: string) => {
+    if (op === "settings.get") {
+      return {
+        "terminal.defaultProfileId": "custom:node-shell",
+        "terminal.profiles": [
+          {
+            id: "custom:node-shell",
+            label: "Node Shell",
+            command: "node",
+            args: ["--interactive"],
+            icon: "terminal",
+          },
+        ],
+      };
+    }
+    if (op === "terminal.profiles.list") {
+      return {
+        configuredDefaultProfileId: "custom:node-shell",
+        resolvedDefaultProfileId: "custom:node-shell",
+        profiles: [
+          { id: "detected:posix:zsh", label: "zsh", source: "detected", runtime: "native", icon: "terminal" },
+          { id: "custom:node-shell", label: "Node Shell", source: "custom", runtime: "native", icon: "terminal" },
+        ],
+      };
+    }
+    return {};
+  });
+
+  renderSettingsPage(sendCommand);
+
+  expect(await screen.findByLabelText("Default Terminal Profile")).toHaveValue("custom:node-shell");
+  expect(screen.getByDisplayValue("Node Shell")).toBeInTheDocument();
+  expect(screen.getByDisplayValue("node")).toBeInTheDocument();
+});
+
+it("saves a new custom profile and updates terminal.defaultProfileId", async () => {
+  const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+    if (op === "settings.get") return {};
+    if (op === "provider.list") return DEFAULT_PROVIDER_LIST;
+    if (op === "terminal.profiles.list") {
+      return {
+        configuredDefaultProfileId: undefined,
+        resolvedDefaultProfileId: "detected:posix:zsh",
+        profiles: [
+          { id: "detected:posix:zsh", label: "zsh", source: "detected", runtime: "native", icon: "terminal" },
+        ],
+      };
+    }
+    return { updated: ["terminal.defaultProfileId", "terminal.profiles"] };
+  });
+
+  renderSettingsPage(sendCommand);
+
+  await user.click(await screen.findByRole("button", { name: "Add Terminal Profile" }));
+  await user.type(screen.getByLabelText("Profile Label"), "Node Shell");
+  await user.type(screen.getByLabelText("Command"), "node");
+  await user.type(screen.getByLabelText("Arguments"), "--interactive");
+  await user.selectOptions(screen.getByLabelText("Default Terminal Profile"), "custom:node-shell");
+
+  await waitFor(() => {
+    expect(sendCommand).toHaveBeenCalledWith(
+      "settings.update",
+      {
+        settings: {
+          terminal: {
+            defaultProfileId: "custom:node-shell",
+            profiles: [
+              {
+                id: "custom:node-shell",
+                label: "Node Shell",
+                command: "node",
+                args: ["--interactive"],
+                icon: "terminal",
+              },
+            ],
+          },
+        },
+      },
+      undefined
+    );
+  });
+});
+
+it("edits and deletes an existing custom profile without changing other settings", async () => {
+  const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+    if (op === "settings.get") {
+      return {
+        "terminal.defaultProfileId": "custom:node-shell",
+        "terminal.profiles": [
+          {
+            id: "custom:node-shell",
+            label: "Node Shell",
+            command: "node",
+            args: ["--interactive"],
+            icon: "terminal",
+          },
+        ],
+      };
+    }
+    if (op === "provider.list") return DEFAULT_PROVIDER_LIST;
+    if (op === "terminal.profiles.list") {
+      return {
+        configuredDefaultProfileId: "custom:node-shell",
+        resolvedDefaultProfileId: "custom:node-shell",
+        profiles: [
+          { id: "detected:posix:zsh", label: "zsh", source: "detected", runtime: "native", icon: "terminal" },
+          { id: "custom:node-shell", label: "Node Shell", source: "custom", runtime: "native", icon: "terminal" },
+        ],
+      };
+    }
+    return { updated: ["terminal.defaultProfileId", "terminal.profiles"] };
+  });
+
+  renderSettingsPage(sendCommand);
+
+  const labelInput = await screen.findByDisplayValue("Node Shell");
+  await user.clear(labelInput);
+  await user.type(labelInput, "Node REPL");
+
+  await waitFor(() => {
+    expect(sendCommand).toHaveBeenCalledWith(
+      "settings.update",
+      {
+        settings: {
+          terminal: {
+            defaultProfileId: "custom:node-shell",
+            profiles: [
+              {
+                id: "custom:node-shell",
+                label: "Node REPL",
+                command: "node",
+                args: ["--interactive"],
+                icon: "terminal",
+              },
+            ],
+          },
+        },
+      },
+      undefined
+    );
+  });
+
+  await user.click(screen.getByRole("button", { name: "Remove Profile" }));
+
+  await waitFor(() => {
+    expect(sendCommand).toHaveBeenCalledWith(
+      "settings.update",
+      {
+        settings: {
+          terminal: {
+            defaultProfileId: undefined,
+            profiles: [],
+          },
+        },
+      },
+      undefined
+    );
+  });
+});
+```
+
+- [ ] **Step 2: Run the settings-page test and verify it fails**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/settings/components/settings-page.test.tsx`
+
+Expected: FAIL because the settings page never requests `terminal.profiles.list`, has no terminal profile controls, and never posts `terminal.defaultProfileId` or `terminal.profiles`.
+
+- [ ] **Step 3: Implement the settings component and localization**
+
+```tsx
+// packages/web/src/features/settings/components/terminal-profile-settings.tsx
+import type { CustomTerminalProfile, TerminalProfile } from "@coder-studio/core";
+import { Button, Input, Select } from "../../../components/ui";
+import { useTranslation } from "../../../lib/i18n";
+
+function nextCustomProfileId(label: string): `custom:${string}` {
+  const normalized = label.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return `custom:${normalized || crypto.randomUUID()}`;
+}
+
+function newDraftProfileId(): `custom:${string}` {
+  return `custom:draft-${crypto.randomUUID()}`;
+}
+
+function resolvePersistedProfileId(profile: CustomTerminalProfile): `custom:${string}` {
+  if (!profile.id.startsWith("custom:draft-") || !profile.label.trim()) {
+    return profile.id;
+  }
+  return nextCustomProfileId(profile.label);
+}
+
+export function TerminalProfileSettings(props: {
+  profiles: TerminalProfile[];
+  defaultProfileId?: string;
+  customProfiles: CustomTerminalProfile[];
+  onSave: (settings: { defaultProfileId?: string; profiles: CustomTerminalProfile[] }) => Promise<void>;
+}) {
+  const t = useTranslation();
+
+  const persist = async (
+    nextProfiles: CustomTerminalProfile[],
+    nextDefaultProfileId = props.defaultProfileId
+  ) => {
+    const safeDefaultProfileId =
+      nextDefaultProfileId && nextProfiles.some((profile) => profile.id === nextDefaultProfileId)
+        ? nextDefaultProfileId
+        : props.profiles.some((profile) => profile.id === nextDefaultProfileId)
+          ? nextDefaultProfileId
+          : undefined;
+
+    await props.onSave({
+      defaultProfileId: safeDefaultProfileId,
+      profiles: nextProfiles,
+    });
+  };
+
+  const updateProfile = (
+    profileId: string,
+    patch: Partial<Pick<CustomTerminalProfile, "label" | "command" | "args" | "icon">>
+  ) => {
+    const nextProfiles = props.customProfiles.map((profile) => {
+      if (profile.id !== profileId) {
+        return profile;
+      }
+
+      const merged = { ...profile, ...patch };
+      return {
+        ...merged,
+        id: resolvePersistedProfileId(merged),
+      };
+    });
+    void persist(nextProfiles);
+  };
+
+  const removeProfile = (profileId: string) => {
+    const nextProfiles = props.customProfiles.filter((profile) => profile.id !== profileId);
+    const nextDefaultProfileId =
+      props.defaultProfileId === profileId ? undefined : props.defaultProfileId;
+    void persist(nextProfiles, nextDefaultProfileId);
+  };
+
+  const addProfile = () => {
+    const profileId = newDraftProfileId();
+    const nextProfiles = [
+      ...props.customProfiles,
+      {
+        id: profileId,
+        label: "Custom Profile",
+        command: "",
+        args: [],
+        icon: "terminal",
+      },
+    ];
+    void persist(nextProfiles);
+  };
+
+  return (
+    <div className="settings-group">
+      <h3 className="settings-group-title">{t("settings.terminal_profiles.title")}</h3>
+      <p className="settings-group-desc">{t("settings.terminal_profiles.hint")}</p>
+
+      <label className="settings-config-label" htmlFor="terminal-default-profile">
+        {t("settings.terminal_profiles.default_label")}
+      </label>
+      <Select
+        aria-label={t("settings.terminal_profiles.default_label")}
+        id="terminal-default-profile"
+        options={props.profiles.map((profile) => ({
+          value: profile.id,
+          label: profile.label,
+        }))}
+        value={props.defaultProfileId ?? ""}
+        onChange={(event) => {
+          void persist(props.customProfiles, event.target.value || undefined);
+        }}
+      />
+
+      {props.customProfiles.map((profile) => (
+        <div key={profile.id} className="settings-profile-card">
+          <Input
+            aria-label={t("settings.terminal_profiles.profile_label")}
+            value={profile.label}
+            onChange={(event) => {
+              updateProfile(profile.id, { label: event.target.value });
+            }}
+          />
+          <Input
+            aria-label={t("settings.terminal_profiles.command")}
+            value={profile.command}
+            onChange={(event) => {
+              updateProfile(profile.id, { command: event.target.value });
+            }}
+          />
+          <Input
+            aria-label={t("settings.terminal_profiles.arguments")}
+            value={(profile.args ?? []).join(" ")}
+            onChange={(event) => {
+              updateProfile(profile.id, {
+                args: event.target.value
+                  .split(/\s+/)
+                  .map((token) => token.trim())
+                  .filter(Boolean),
+              });
+            }}
+          />
+          <Button tone="danger" onClick={() => removeProfile(profile.id)}>
+            {t("settings.terminal_profiles.remove")}
+          </Button>
+        </div>
+      ))}
+
+      <Button onClick={addProfile}>{t("settings.terminal_profiles.add")}</Button>
+    </div>
+  );
+}
+```
+
+```json
+// packages/web/src/locales/en.json
+{
+  "settings": {
+    "terminal_profiles": {
+      "title": "Terminal Profiles",
+      "hint": "Choose the default profile and manage custom launch commands.",
+      "default_label": "Default Terminal Profile",
+      "profile_label": "Profile Label",
+      "command": "Command",
+      "arguments": "Arguments",
+      "arguments_hint": "Separate arguments with spaces. Use one field for the full command token.",
+      "add": "Add Terminal Profile",
+      "remove": "Remove Profile"
+    }
+  }
+}
+```
+
+- [ ] **Step 4: Run the settings-page test again and verify it passes**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/settings/components/settings-page.test.tsx`
+
+Expected: PASS with the new terminal profile settings assertions green.
+
+- [ ] **Step 5: Commit only the Task 4 files**
+
+```bash
+git add packages/web/src/features/settings/components/terminal-profile-settings.tsx packages/web/src/features/settings/components/settings-page.tsx packages/web/src/features/settings/components/settings-page.test.tsx packages/web/src/locales/en.json packages/web/src/locales/zh.json
+git commit -m "feat: add terminal profile settings"
+```
+
+## Task 5: Full Verification, Review, and Final Cleanup
+
+**Files:**
+- Modify: `packages/core/src/domain/terminal-profiles.ts`
+- Modify: `packages/server/src/terminal-profiles/detect.ts`
+- Modify: `packages/server/src/terminal-profiles/registry.ts`
+- Modify: `packages/server/src/terminal-profiles/wsl.ts`
+- Modify: `packages/server/src/commands/terminal.ts`
+- Modify: `packages/server/src/commands/settings.ts`
+- Modify: `packages/server/src/commands/settings.test.ts`
+- Modify: `packages/server/src/__tests__/terminal-commands.test.ts`
+- Modify: `packages/web/src/features/terminal-panel/actions/use-terminal-profiles.ts`
+- Modify: `packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts`
+- Modify: `packages/web/src/features/terminal-panel/actions/use-terminal-actions.ts`
+- Modify: `packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx`
+- Modify: `packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx`
+- Modify: `packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx`
+- Modify: `packages/web/src/features/settings/components/terminal-profile-settings.tsx`
+- Modify: `packages/web/src/features/settings/components/settings-page.tsx`
+- Modify: `packages/web/src/features/settings/components/settings-page.test.tsx`
+- Modify: `packages/web/src/locales/en.json`
+- Modify: `packages/web/src/locales/zh.json`
+- Test: `packages/server/src/terminal-profiles/__tests__/registry.test.ts`
+- Test: `packages/server/src/commands/settings.test.ts`
+- Test: `packages/server/src/__tests__/terminal-commands.test.ts`
+- Test: `packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx`
+- Test: `packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx`
+- Test: `packages/web/src/features/settings/components/settings-page.test.tsx`
+
+- [ ] **Step 1: Run the focused feature test suite**
+
+Run: `pnpm --filter @coder-studio/server exec vitest run src/terminal-profiles/__tests__/registry.test.ts src/commands/settings.test.ts src/__tests__/terminal-commands.test.ts && pnpm --filter @coder-studio/web exec vitest run src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx src/features/terminal-panel/__tests__/terminal-panel.test.tsx src/features/settings/components/settings-page.test.tsx`
+
+Expected: PASS for all targeted terminal profile tests, exit code `0`.
+
+- [ ] **Step 2: Run package builds/type checks that prove the touched packages still compile**
+
+Run: `pnpm --filter @coder-studio/core build && pnpm --filter @coder-studio/server build && pnpm --filter @coder-studio/web build`
+
+Expected: PASS for all three packages, exit code `0`.
+
+- [ ] **Step 3: Run repository-level verification before claiming completion**
+
+Run: `pnpm ci:verify`
+
+Expected: PASS with lint, tests, and builds green across the repository.
+
+- [ ] **Step 4: Review the diff against the spec and fix anything missing before the final handoff**
+
+```bash
+git status --short
+git diff --stat 58c39d4d..HEAD
+```
+
+Expected: only the planned terminal profile files are included in the feature commits, plus any deliberate follow-up fixes from verification.
+
+- [ ] **Step 5: Commit any verification/review fixes if needed**
+
+```bash
+git add packages/core/src/domain/terminal-profiles.ts packages/server/src/terminal-profiles packages/server/src/commands/terminal.ts packages/server/src/commands/settings.ts packages/server/src/commands/settings.test.ts packages/server/src/__tests__/terminal-commands.test.ts packages/web/src/features/terminal-panel packages/web/src/features/settings/components/terminal-profile-settings.tsx packages/web/src/features/settings/components/settings-page.tsx packages/web/src/features/settings/components/settings-page.test.tsx packages/web/src/locales/en.json packages/web/src/locales/zh.json
+git commit -m "fix: address terminal profile verification feedback"
+```
+
+## Self-Review
+
+### Spec Coverage Check
+
+- Unified cross-platform terminal profile DTOs: Task 1.
+- Server-owned detection, merge, default resolution, and WSL handling: Tasks 1-2.
+- `terminal.create(profileId?)` plus `terminal.profiles.list`: Task 2.
+- No silent fallback for an explicitly selected unavailable profile: Tasks 1-2 tests.
+- Preserve `configuredDefaultProfileId` while computing `resolvedDefaultProfileId`: Tasks 1-2 tests.
+- Desktop split button and mobile chooser: Task 3.
+- Settings support for default profile and custom profile CRUD: Task 4.
+- Locales and user-facing copy for the new settings/UI flows: Task 4.
+- Full verification before handoff: Task 5.
+
+### Placeholder Scan
+
+- No `TODO`, `TBD`, or “similar to Task N” placeholders remain.
+- Every task includes concrete files, commands, commit messages, and code snippets.
+
+### Type Consistency Check
+
+- Shared persisted custom profile type is `CustomTerminalProfile`.
+- Server list command returns `TerminalProfilesListResult`.
+- Client create flow sends `profileId?: string` to `terminal.create`.
+- Unavailable explicit selection always throws `terminal_profile_unavailable`.
diff --git a/docs/superpowers/plans/2026-06-25-terminal-settings-route-implementation.md b/docs/superpowers/plans/2026-06-25-terminal-settings-route-implementation.md
new file mode 100644
index 000000000..21371b505
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-25-terminal-settings-route-implementation.md
@@ -0,0 +1,526 @@
+# Terminal Settings Route Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Move all terminal-related settings into a dedicated `Terminal` section, remove the legacy `/settings` route, and update every affected entry point to the canonical `/more/settings/...` routes.
+
+**Architecture:** Keep `MoreFeaturesPage` as the only public settings router, add `terminal` to the shared settings-section registry, and extract terminal-only UI into its own settings section component so `General` and `Appearance` can shed terminal responsibilities cleanly. Reuse the existing settings persistence APIs and terminal-profile data flow rather than introducing new commands.
+
+**Tech Stack:** TypeScript, React 19, Jotai, React Router, Vitest, existing settings and more-route infrastructure in `packages/web`.
+
+---
+
+## File Map
+
+- Create: `packages/web/src/features/settings/components/terminal-settings-section.tsx` — dedicated terminal settings UI section with renderer, copy-on-select, profiles, and font-size controls.
+- Modify: `packages/web/src/features/settings/components/settings-sections.tsx` — add `terminal` to the visible settings registry and section order.
+- Modify: `packages/web/src/features/settings/components/settings-page.tsx` — render the terminal section, remove terminal UI from general/appearance, and update mobile grouping.
+- Modify: `packages/web/src/features/more/routes.ts` — add `/more/settings/terminal` metadata.
+- Modify: `packages/web/src/features/more/page.tsx` — allow embedded terminal settings rendering.
+- Modify: `packages/web/src/shells/desktop-shell.tsx` — remove `/settings` route and legacy auth-bypass path handling.
+- Modify: `packages/web/src/shells/mobile-shell/index.tsx` — remove `/settings` route and legacy auth-bypass path handling.
+- Modify: `packages/web/src/theme/icon-theme.ts` — add `nav.settings.terminal`.
+- Modify: `packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx` — point terminal profile config link at `/more/settings/terminal#terminal-profiles`.
+- Modify: `packages/web/src/features/workspace/views/shared/footer-update-rail.tsx` — point update details at `/more/about/update-status`.
+- Modify: `packages/web/src/features/command-palette/components/command-palette.tsx` — open `/more/settings/general`.
+- Modify: `packages/web/src/ui-preview/scenes/page-scenes.tsx` — replace old settings preview routes.
+- Modify: `packages/web/src/ui-preview/scenes/showcase-scenes.tsx` — replace old settings preview routes.
+- Modify: `packages/web/src/ui-preview/scenes/desktop-review-scenes.tsx` — replace old settings preview routes.
+- Modify: `packages/web/src/locales/en.json` — add terminal section labels/hints and clearer terminal-profile copy.
+- Modify: `packages/web/src/locales/zh.json` — add matching Chinese strings and clearer terminal-profile copy.
+- Modify: `packages/web/src/features/settings/components/settings-page.test.tsx` — cover section order and terminal-control relocation.
+- Modify: `packages/web/src/features/more/page.test.tsx` — cover `/more/settings/terminal`.
+- Modify: `packages/web/src/shells/desktop-shell.test.tsx` — assert auth bypass works for `/more/settings/...` instead of `/settings`.
+- Modify: `packages/web/src/shells/mobile-shell/index.test.tsx` — assert auth bypass works for `/more/settings/...` instead of `/settings`.
+- Modify: `packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx` — assert canonical terminal profile settings link.
+- Modify: `packages/web/src/features/workspace/views/shared/footer-update-rail.test.tsx` — assert canonical about route.
+- Modify: `packages/web/src/features/command-palette/components/command-palette.test.tsx` — assert command-palette settings navigation uses `/more/settings/general`.
+- Modify: `packages/web/src/theme/icon-theme.test.ts` — assert the new `nav.settings.terminal` semantic resolves.
+- Modify: `packages/web/src/ui-preview/catalog.test.tsx` — update preview-route expectations if they still hardcode `/settings`.
+
+## Task 1: Add `Terminal` To the Shared Settings Route And Section Maps
+
+**Files:**
+- Modify: `packages/web/src/features/settings/components/settings-sections.tsx`
+- Modify: `packages/web/src/features/settings/components/settings-page.tsx`
+- Modify: `packages/web/src/features/more/routes.ts`
+- Modify: `packages/web/src/features/more/page.tsx`
+- Modify: `packages/web/src/shells/desktop-shell.tsx`
+- Modify: `packages/web/src/shells/mobile-shell/index.tsx`
+- Modify: `packages/web/src/theme/icon-theme.ts`
+- Modify: `packages/web/src/features/settings/components/settings-page.test.tsx`
+- Modify: `packages/web/src/features/more/page.test.tsx`
+- Modify: `packages/web/src/shells/desktop-shell.test.tsx`
+- Modify: `packages/web/src/shells/mobile-shell/index.test.tsx`
+- Modify: `packages/web/src/theme/icon-theme.test.ts`
+
+- [ ] **Step 1: Write the failing route/section tests first**
+
+```ts
+// packages/web/src/features/settings/components/settings-page.test.tsx
+it("renders terminal between agents and appearance in the visible settings navigation", async () => {
+  const store = createConnectedStore(vi.fn().mockResolvedValue({}));
+
+  renderSettingsPage(store);
+
+  await waitFor(() => {
+    expect(screen.getByRole("button", { name: "终端" })).toBeInTheDocument();
+  });
+
+  const labels = Array.from(document.querySelectorAll(".settings-nav-item")).map((item) =>
+    item.textContent?.trim()
+  );
+
+  expect(labels).toEqual(["通用", "Agents", "终端", "外观", "快捷键"]);
+});
+```
+
+```ts
+// packages/web/src/features/more/page.test.tsx
+it("parses the terminal settings route", () => {
+  expect(parseMoreRoute("/more/settings/terminal")).toEqual({
+    isValid: true,
+    category: "settings",
+    section: "terminal",
+  });
+});
+```
+
+```ts
+// packages/web/src/shells/desktop-shell.test.tsx
+it("renders MoreFeaturesPage on /more/settings/terminal while auth status is still unknown", async () => {
+  window.history.replaceState({}, "", "/more/settings/terminal");
+
+  const store = createStore();
+  store.set(connectionStatusAtom, "connected");
+  store.set(authEnabledAtom, null);
+  store.set(authenticatedAtom, false);
+
+  renderShell(store);
+
+  expect(await screen.findByTestId("more-features-page")).toBeInTheDocument();
+  expect(screen.queryByText("Page not found")).toBeNull();
+});
+```
+
+```ts
+// packages/web/src/theme/icon-theme.test.ts
+expect(getIconPresentation(themeId, "nav.settings.terminal")).toEqual({
+  semantic: "nav.settings.terminal",
+  Icon: Terminal,
+  tone: "secondary",
+  surface: "none",
+});
+```
+
+- [ ] **Step 2: Run the focused tests and verify they fail for the missing section/route**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/settings/components/settings-page.test.tsx src/features/more/page.test.tsx src/shells/desktop-shell.test.tsx src/shells/mobile-shell/index.test.tsx src/theme/icon-theme.test.ts`
+
+Expected: FAIL with at least one missing `终端`/`Terminal` navigation assertion, `parseMoreRoute("/more/settings/terminal")` mismatch, or missing `nav.settings.terminal` semantic.
+
+- [ ] **Step 3: Add the new section and remove the legacy `/settings` shell route**
+
+```ts
+// packages/web/src/features/settings/components/settings-sections.tsx
+export type SettingsSection =
+  | "general"
+  | "providers"
+  | "terminal"
+  | "appearance"
+  | "shortcuts"
+  | "monitoring"
+  | "analysis"
+  | "diagnostics"
+  | "about";
+
+const VISIBLE_SETTINGS_SECTIONS = [
+  { id: "general", labelKey: "settings.general", iconSemantic: "nav.settings.general" },
+  { id: "providers", labelKey: "settings.providers", iconSemantic: "nav.settings.providers" },
+  { id: "terminal", labelKey: "settings.terminal.title", iconSemantic: "nav.settings.terminal" },
+  { id: "appearance", labelKey: "settings.appearance", iconSemantic: "nav.settings.appearance" },
+  { id: "shortcuts", labelKey: "settings.shortcuts.title", iconSemantic: "nav.settings.shortcuts" },
+] as const satisfies readonly SettingsSectionMeta[];
+```
+
+```ts
+// packages/web/src/features/more/routes.ts
+sections: [
+  {
+    id: "general",
+    labelKey: "settings.general",
+    hintKey: "more.section.settings.general_hint",
+    iconSemantic: "nav.settings.general",
+  },
+  {
+    id: "providers",
+    labelKey: "more.section.settings.agents",
+    hintKey: "more.section.settings.agents_hint",
+    iconSemantic: "nav.settings.providers",
+  },
+  {
+    id: "terminal",
+    labelKey: "settings.terminal.title",
+    hintKey: "more.section.settings.terminal_hint",
+    iconSemantic: "nav.settings.terminal",
+  },
+  {
+    id: "appearance",
+    labelKey: "settings.appearance",
+    hintKey: "more.section.settings.appearance_hint",
+    iconSemantic: "nav.settings.appearance",
+  },
+]
+```
+
+```ts
+// packages/web/src/shells/desktop-shell.tsx
+const shouldBypassAuthLoading =
+  location.pathname.startsWith("/analytics") ||
+  location.pathname.startsWith("/monitoring") ||
+  location.pathname.startsWith("/diagnostics") ||
+  location.pathname.startsWith("/more") ||
+  location.pathname === "/session-gate";
+
+<Routes>
+  <Route path="/more/*" element={<MoreFeaturesPage />} />
+  <Route path="/workspace" element={...} />
+  <Route path="*" element={<NotFoundPage />} />
+</Routes>
+```
+
+```ts
+// packages/web/src/theme/icon-theme.ts
+"nav.settings.terminal",
+
+"nav.settings.terminal": { glyph: Terminal, tone: "secondary" },
+```
+
+- [ ] **Step 4: Re-run the focused tests and verify they pass**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/settings/components/settings-page.test.tsx src/features/more/page.test.tsx src/shells/desktop-shell.test.tsx src/shells/mobile-shell/index.test.tsx src/theme/icon-theme.test.ts`
+
+Expected: PASS with `0 failed`.
+
+- [ ] **Step 5: Commit the route/section scaffold**
+
+```bash
+git add \
+  packages/web/src/features/settings/components/settings-sections.tsx \
+  packages/web/src/features/settings/components/settings-page.tsx \
+  packages/web/src/features/more/routes.ts \
+  packages/web/src/features/more/page.tsx \
+  packages/web/src/shells/desktop-shell.tsx \
+  packages/web/src/shells/mobile-shell/index.tsx \
+  packages/web/src/theme/icon-theme.ts \
+  packages/web/src/features/settings/components/settings-page.test.tsx \
+  packages/web/src/features/more/page.test.tsx \
+  packages/web/src/shells/desktop-shell.test.tsx \
+  packages/web/src/shells/mobile-shell/index.test.tsx \
+  packages/web/src/theme/icon-theme.test.ts
+git commit -m "feat: add dedicated terminal settings route"
+```
+
+## Task 2: Move Terminal Controls Into a Dedicated `TerminalSettingsSection`
+
+**Files:**
+- Create: `packages/web/src/features/settings/components/terminal-settings-section.tsx`
+- Modify: `packages/web/src/features/settings/components/settings-page.tsx`
+- Modify: `packages/web/src/features/settings/components/terminal-profile-settings.tsx`
+- Modify: `packages/web/src/features/settings/components/settings-page.test.tsx`
+
+- [ ] **Step 1: Write the failing terminal-relocation tests first**
+
+```ts
+// packages/web/src/features/settings/components/settings-page.test.tsx
+it("renders terminal controls under the terminal section instead of general", async () => {
+  const store = createConnectedStore(vi.fn().mockResolvedValue({}));
+
+  renderSettingsPage(store);
+
+  fireEvent.click(screen.getByRole("button", { name: "终端" }));
+
+  expect(await screen.findByRole("heading", { name: "终端渲染器" })).toBeInTheDocument();
+  expect(screen.getByRole("switch", { name: "选中自动复制" })).toBeInTheDocument();
+  expect(screen.getByRole("spinbutton", { name: "桌面端终端字号" })).toBeInTheDocument();
+  expect(screen.getByRole("spinbutton", { name: "移动端终端字号" })).toBeInTheDocument();
+
+  fireEvent.click(screen.getByRole("button", { name: "通用" }));
+  expect(screen.queryByRole("heading", { name: "终端渲染器" })).not.toBeInTheDocument();
+
+  fireEvent.click(screen.getByRole("button", { name: "外观" }));
+  expect(screen.queryByRole("spinbutton", { name: "桌面端终端字号" })).not.toBeInTheDocument();
+});
+```
+
+```ts
+// packages/web/src/features/settings/components/settings-page.test.tsx
+it("exposes the terminal profiles anchor from the terminal section route", async () => {
+  const store = createConnectedStore(createDefaultCommandHandler());
+
+  renderSettingsPage(store, {
+    initialEntry: "/settings?section=terminal#terminal-profiles",
+  });
+
+  const terminalProfilesHeading = await screen.findByRole("heading", { name: "终端配置" });
+  expect(document.getElementById("terminal-profiles")).toContainElement(terminalProfilesHeading);
+});
+```
+
+- [ ] **Step 2: Run the focused settings-page tests and verify they fail before the extraction**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/settings/components/settings-page.test.tsx`
+
+Expected: FAIL because the `终端` section does not yet render terminal controls, or the controls still appear in `通用` / `外观`.
+
+- [ ] **Step 3: Extract the terminal UI into a dedicated section component**
+
+```ts
+// packages/web/src/features/settings/components/settings-page.tsx
+import {
+  TerminalSettingsSection,
+  type TerminalSettingsSectionProps,
+} from "./terminal-settings-section";
+
+const MOBILE_SETTINGS_GROUPS = [
+  {
+    titleKey: "settings.mobile_groups.workspace_runtime",
+    sections: ["general", "providers", "terminal"],
+  },
+  {
+    titleKey: "settings.mobile_groups.interface_interaction",
+    sections: ["appearance", "shortcuts"],
+  },
+] as const;
+
+const renderContent = (section: SettingsSection, currentAboutView: AboutSettingsView) => {
+  switch (section) {
+    case "general":
+      return <GeneralSettings ... />;
+    case "terminal":
+      return (
+        <TerminalSettingsSection
+          terminalRenderer={terminalRenderer}
+          setTerminalRenderer={handleTerminalRendererSelection}
+          terminalCopyOnSelect={terminalPreferences.copyOnSelect}
+          setTerminalCopyOnSelect={handleTerminalCopyOnSelectSelection}
+          terminalProfiles={terminalProfiles}
+          customTerminalProfiles={customTerminalProfiles}
+          configuredTerminalDefaultProfileId={configuredTerminalDefaultProfileId}
+          resolvedTerminalDefaultProfileId={resolvedTerminalDefaultProfileId}
+          onTerminalProfileSettingsChange={handleTerminalProfileSettingsChange}
+          desktopTerminalFontSize={getTerminalFontSizePreference(terminalPreferences, "desktop")}
+          mobileTerminalFontSize={getTerminalFontSizePreference(terminalPreferences, "mobile")}
+          setDesktopTerminalFontSize={handleDesktopTerminalFontSizeSelection}
+          setMobileTerminalFontSize={handleMobileTerminalFontSizeSelection}
+        />
+      );
+```
+
+```ts
+// packages/web/src/features/settings/components/terminal-settings-section.tsx
+export function TerminalSettingsSection({
+  terminalRenderer,
+  setTerminalRenderer,
+  terminalCopyOnSelect,
+  setTerminalCopyOnSelect,
+  terminalProfiles,
+  customTerminalProfiles,
+  configuredTerminalDefaultProfileId,
+  resolvedTerminalDefaultProfileId,
+  onTerminalProfileSettingsChange,
+  desktopTerminalFontSize,
+  mobileTerminalFontSize,
+  setDesktopTerminalFontSize,
+  setMobileTerminalFontSize,
+}: TerminalSettingsSectionProps) {
+  // keep the existing renderer, copy-on-select, terminal profile, and font-size UI here
+}
+```
+
+```ts
+// packages/web/src/features/settings/components/terminal-profile-settings.tsx
+<div className="settings-config-control">
+  <div style={{ width: "220px", maxWidth: "100%" }}>
+    <Select ... />
+  </div>
+</div>
+```
+
+- [ ] **Step 4: Re-run the settings-page tests and verify they pass**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/settings/components/settings-page.test.tsx`
+
+Expected: PASS with the terminal controls only appearing in the `Terminal` section.
+
+- [ ] **Step 5: Commit the terminal section extraction**
+
+```bash
+git add \
+  packages/web/src/features/settings/components/terminal-settings-section.tsx \
+  packages/web/src/features/settings/components/settings-page.tsx \
+  packages/web/src/features/settings/components/terminal-profile-settings.tsx \
+  packages/web/src/features/settings/components/settings-page.test.tsx
+git commit -m "refactor: move terminal controls into terminal settings"
+```
+
+## Task 3: Update Links, Locale Copy, And Preview/Test Consumers
+
+**Files:**
+- Modify: `packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx`
+- Modify: `packages/web/src/features/workspace/views/shared/footer-update-rail.tsx`
+- Modify: `packages/web/src/features/command-palette/components/command-palette.tsx`
+- Modify: `packages/web/src/ui-preview/scenes/page-scenes.tsx`
+- Modify: `packages/web/src/ui-preview/scenes/showcase-scenes.tsx`
+- Modify: `packages/web/src/ui-preview/scenes/desktop-review-scenes.tsx`
+- Modify: `packages/web/src/locales/en.json`
+- Modify: `packages/web/src/locales/zh.json`
+- Modify: `packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx`
+- Modify: `packages/web/src/features/workspace/views/shared/footer-update-rail.test.tsx`
+- Modify: `packages/web/src/features/command-palette/components/command-palette.test.tsx`
+- Modify: `packages/web/src/ui-preview/catalog.test.tsx`
+
+- [ ] **Step 1: Write the failing link/copy tests first**
+
+```ts
+// packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx
+expect(
+  within(chooser).getByRole("link", { name: "Configure Terminal Profiles..." })
+).toHaveAttribute("href", "/more/settings/terminal#terminal-profiles");
+```
+
+```ts
+// packages/web/src/features/workspace/views/shared/footer-update-rail.test.tsx
+fireEvent.click(screen.getByRole("button", { name: testCase.action }));
+expect(navigateMock).toHaveBeenLastCalledWith("/more/about/update-status");
+```
+
+```ts
+// packages/web/src/features/command-palette/components/command-palette.test.tsx
+fireEvent.keyDown(palette!, { key: "Enter" });
+expect(routerMocks.navigate).toHaveBeenCalledWith("/more/settings/general");
+```
+
+- [ ] **Step 2: Run the focused link tests and verify they fail before the updates**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/terminal-panel/__tests__/terminal-panel.test.tsx src/features/workspace/views/shared/footer-update-rail.test.tsx src/features/command-palette/components/command-palette.test.tsx src/ui-preview/catalog.test.tsx`
+
+Expected: FAIL with `/settings?...` or `/settings` still showing up in one or more assertions.
+
+- [ ] **Step 3: Update navigation helpers, preview routes, and locale copy**
+
+```ts
+// packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx
+import { buildMorePath } from "../../../more/routes";
+
+href={`${buildMorePath("settings", "terminal")}#terminal-profiles`}
+```
+
+```ts
+// packages/web/src/features/workspace/views/shared/footer-update-rail.tsx
+const openDetails = () => {
+  navigate("/more/about/update-status");
+};
+```
+
+```ts
+// packages/web/src/features/command-palette/components/command-palette.tsx
+{
+  id: "settings",
+  label: t("more.category.settings"),
+  description: t("more.category.settings_hint"),
+  action: () => navigate("/more/settings/general"),
+}
+```
+
+```json
+// packages/web/src/locales/en.json
+"terminal": {
+  "title": "Terminal"
+},
+"more": {
+  "section": {
+    "settings": {
+      "general_hint": "Core workspace, notification, language, and runtime preferences.",
+      "terminal_hint": "Renderer, copy-on-select, launch profiles, and terminal font sizes."
+    }
+  }
+},
+"terminal_profiles": {
+  "hint": "Choose the default shell and manage reusable custom terminal launch presets. Detected profiles are read-only."
+}
+```
+
+```json
+// packages/web/src/locales/zh.json
+"terminal": {
+  "title": "终端"
+},
+"more": {
+  "section": {
+    "settings": {
+      "general_hint": "工作区、通知、语言和运行时等基础偏好。",
+      "terminal_hint": "终端渲染、选中复制、启动配置和终端字号。"
+    }
+  }
+},
+"terminal_profiles": {
+  "hint": "选择默认 shell，并管理可复用的自定义终端启动配置。检测到的配置为只读。"
+}
+```
+
+- [ ] **Step 4: Re-run the focused link/copy tests and verify they pass**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/terminal-panel/__tests__/terminal-panel.test.tsx src/features/workspace/views/shared/footer-update-rail.test.tsx src/features/command-palette/components/command-palette.test.tsx src/ui-preview/catalog.test.tsx`
+
+Expected: PASS with no remaining `/settings` route expectations in these areas.
+
+- [ ] **Step 5: Commit the navigation and copy cleanup**
+
+```bash
+git add \
+  packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx \
+  packages/web/src/features/workspace/views/shared/footer-update-rail.tsx \
+  packages/web/src/features/command-palette/components/command-palette.tsx \
+  packages/web/src/ui-preview/scenes/page-scenes.tsx \
+  packages/web/src/ui-preview/scenes/showcase-scenes.tsx \
+  packages/web/src/ui-preview/scenes/desktop-review-scenes.tsx \
+  packages/web/src/locales/en.json \
+  packages/web/src/locales/zh.json \
+  packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx \
+  packages/web/src/features/workspace/views/shared/footer-update-rail.test.tsx \
+  packages/web/src/features/command-palette/components/command-palette.test.tsx \
+  packages/web/src/ui-preview/catalog.test.tsx
+git commit -m "fix: align terminal settings links and copy"
+```
+
+## Task 4: Run Final Verification And Ship A Single Reviewable Branch State
+
+**Files:**
+- Modify: any files from Tasks 1-3 if final review finds issues
+
+- [ ] **Step 1: Run the full targeted verification sweep**
+
+Run: `pnpm --filter @coder-studio/web exec vitest run src/features/settings/components/settings-page.test.tsx src/features/more/page.test.tsx src/shells/desktop-shell.test.tsx src/shells/mobile-shell/index.test.tsx src/features/terminal-panel/__tests__/terminal-panel.test.tsx src/features/workspace/views/shared/footer-update-rail.test.tsx src/features/command-palette/components/command-palette.test.tsx src/theme/icon-theme.test.ts src/ui-preview/catalog.test.tsx`
+
+Expected: PASS with `0 failed`.
+
+- [ ] **Step 2: Run repository-level web lint for the touched package**
+
+Run: `pnpm --filter @coder-studio/web lint`
+
+Expected: exit code `0`.
+
+- [ ] **Step 3: Run the repo verification command required by the workspace instructions**
+
+Run: `pnpm ci:verify`
+
+Expected: exit code `0`.
+
+- [ ] **Step 4: Commit any final fixes after review**
+
+```bash
+git add packages/web/src
+git add docs/superpowers/plans/2026-06-25-terminal-settings-route-implementation.md
+git commit -m "fix: split terminal settings into dedicated section"
+```
diff --git a/docs/superpowers/plans/2026-06-25-vscode-preview-tabs.md b/docs/superpowers/plans/2026-06-25-vscode-preview-tabs.md
new file mode 100644
index 000000000..d12f381ef
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-25-vscode-preview-tabs.md
@@ -0,0 +1,731 @@
+# VSCode Preview Tabs Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add VSCode-style preview file tabs, fixed tabs, and editor-tab context menu close actions to the workspace editor.
+
+**Architecture:** Keep preview behavior inside the existing web editor state layer. File tabs gain a `pinned` flag in `WorkspaceFileEditorTab`; `openEditorTabs` becomes the canonical ordered tab list while `openEditorPaths` remains a compatibility/persisted pinned-file list. File tree clicks pass an explicit open disposition, editor actions own pin/replace/close logic, and the tab header owns the visual/context-menu surface.
+
+**Tech Stack:** TypeScript, React 19, Jotai, Vitest, Testing Library, lucide-react
+
+---
+
+## File Map
+
+- `packages/web/src/features/workspace/atoms/files.ts`
+  Adds file-tab `pinned`, helper constructors, and tab identity helpers.
+- `packages/web/src/features/workspace/actions/open-editor-state.ts`
+  Normalizes old file tabs as pinned and adds ordered tab list helpers.
+- `packages/web/src/features/workspace/actions/open-editor-state.test.ts`
+  Covers legacy normalization and preview tab preservation.
+- `packages/web/src/features/workspace/actions/use-open-workspace-file.ts`
+  Accepts `openDisposition: "preview" | "pinned" | "preserve"` and applies file preview replacement.
+- `packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx`
+  Covers single-click preview replacement and double-click pinning.
+- `packages/web/src/features/workspace/actions/use-file-actions.ts`
+  Routes file tree selection as preview.
+- `packages/web/src/features/workspace/views/shared/file-tree-panel.tsx`
+  Adds file double-click pin entry.
+- `packages/web/src/features/workspace/actions/use-open-editors-actions.ts`
+  Keeps close behavior compatible with preview tabs and exposes close helpers for batch operations if needed.
+- `packages/web/src/features/code-editor/actions/use-code-editor-actions.ts`
+  Pins preview tabs on edit and exposes tab-level close/pin/batch actions.
+- `packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx`
+  Extends non-file tab tests to ensure browser/canvas tabs still work with mixed file tab states.
+- `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx`
+  Renders preview tab style and opens the editor tab context menu.
+- `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx`
+  Covers preview visual state and context menu actions.
+- `packages/web/src/features/workspace/views/shared/file-context-menu.tsx`
+  Either remains as-is or is generalized only if necessary for editor tab context menus.
+
+## Final Verification
+
+Run after implementation:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/workspace/actions/open-editor-state.test.ts src/features/workspace/actions/use-open-workspace-file.test.tsx src/features/workspace/actions/open-editors-close.test.ts src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx src/features/workspace/views/shared/file-tree-panel.test.tsx
+pnpm lint
+```
+
+Expected: targeted web tests pass, then repository lint exits `0`.
+
+### Task 1: Add Preview/Pinned File Tab State Helpers
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/atoms/files.ts`
+- Modify: `packages/web/src/features/workspace/actions/open-editor-state.ts`
+- Test: `packages/web/src/features/workspace/actions/open-editor-state.test.ts`
+
+- [ ] **Step 1: Write failing normalization tests**
+
+Add tests to `open-editor-state.test.ts`:
+
+```ts
+it("normalizes legacy file editor tabs as pinned", () => {
+  expect(
+    normalizeWorkspaceEditorUiStatePatch({
+      openEditorTabs: [{ kind: "file", path: "src/app.ts" }],
+      activeEditorTab: { kind: "file", path: "src/app.ts" },
+    })
+  ).toEqual({
+    openEditorTabs: [{ kind: "file", path: "src/app.ts", pinned: true }],
+    activeEditorTab: { kind: "file", path: "src/app.ts", pinned: true },
+  });
+});
+
+it("preserves preview file editor tabs", () => {
+  expect(
+    normalizeWorkspaceEditorUiStatePatch({
+      openEditorTabs: [{ kind: "file", path: "src/preview.ts", pinned: false }],
+      activeEditorTab: { kind: "file", path: "src/preview.ts", pinned: false },
+    })
+  ).toEqual({
+    openEditorTabs: [{ kind: "file", path: "src/preview.ts", pinned: false }],
+    activeEditorTab: { kind: "file", path: "src/preview.ts", pinned: false },
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to verify failure**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/workspace/actions/open-editor-state.test.ts
+```
+
+Expected: FAIL because file tabs do not carry `pinned`.
+
+- [ ] **Step 3: Implement minimal state helpers**
+
+Change `WorkspaceFileEditorTab`:
+
+```ts
+export interface WorkspaceFileEditorTab {
+  kind: "file";
+  path: string;
+  pinned?: boolean;
+}
+```
+
+Add helpers near the tab types:
+
+```ts
+export function createWorkspaceFileEditorTab(
+  path: string,
+  options: { pinned?: boolean } = {}
+): WorkspaceFileEditorTab {
+  return {
+    kind: "file",
+    path,
+    pinned: options.pinned ?? true,
+  };
+}
+
+export function isPreviewFileEditorTab(tab: WorkspaceEditorTab | null | undefined): boolean {
+  return tab?.kind === "file" && tab.pinned === false;
+}
+```
+
+Update `normalizeWorkspaceFileEditorTab` to trim path and set `pinned`:
+
+```ts
+return {
+  kind: "file",
+  path: candidate.path.trim(),
+  pinned: typeof candidate.pinned === "boolean" ? candidate.pinned : true,
+};
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/workspace/actions/open-editor-state.test.ts
+```
+
+Expected: PASS.
+
+### Task 2: Add Preview Replacement and Pin Open Semantics
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/actions/use-open-workspace-file.ts`
+- Modify: `packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx`
+- Modify: `packages/web/src/features/workspace/actions/use-file-actions.ts`
+
+- [ ] **Step 1: Write failing open behavior tests**
+
+Add tests to `use-open-workspace-file.test.tsx`:
+
+```ts
+it("replaces the existing preview file tab when opening another preview file", async () => {
+  const store = createStore();
+  seedWorkspace(store);
+  store.set(openEditorTabsAtomFamily("ws-test"), [
+    { kind: "file", path: "src/a.ts", pinned: false },
+  ]);
+  store.set(activeEditorTabAtomFamily("ws-test"), {
+    kind: "file",
+    path: "src/a.ts",
+    pinned: false,
+  });
+  store.set(activeFilePathAtomFamily("ws-test"), "src/a.ts");
+
+  const { result } = renderHook(() => useOpenWorkspaceFile("ws-test"), {
+    wrapper: wrapperFor(store),
+  });
+
+  await act(async () => {
+    await result.current.openWorkspaceFile(
+      { workspaceId: "ws-test", path: "src/b.ts", source: "file-tree" },
+      { openTarget: "navigate", openDisposition: "preview" }
+    );
+  });
+
+  expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+    { kind: "file", path: "src/b.ts", pinned: false },
+  ]);
+  expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual({
+    kind: "file",
+    path: "src/b.ts",
+    pinned: false,
+  });
+  expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe("src/b.ts");
+});
+
+it("pins the current preview tab when opening the same file as pinned", async () => {
+  const store = createStore();
+  seedWorkspace(store);
+  store.set(openEditorTabsAtomFamily("ws-test"), [
+    { kind: "file", path: "src/a.ts", pinned: false },
+  ]);
+  store.set(activeEditorTabAtomFamily("ws-test"), {
+    kind: "file",
+    path: "src/a.ts",
+    pinned: false,
+  });
+  store.set(activeFilePathAtomFamily("ws-test"), "src/a.ts");
+
+  const { result } = renderHook(() => useOpenWorkspaceFile("ws-test"), {
+    wrapper: wrapperFor(store),
+  });
+
+  await act(async () => {
+    await result.current.openWorkspaceFile(
+      { workspaceId: "ws-test", path: "src/a.ts", source: "file-tree" },
+      { openTarget: "navigate", openDisposition: "pinned" }
+    );
+  });
+
+  expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+    { kind: "file", path: "src/a.ts", pinned: true },
+  ]);
+  expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual(["src/a.ts"]);
+});
+```
+
+- [ ] **Step 2: Run tests to verify failure**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/workspace/actions/use-open-workspace-file.test.tsx
+```
+
+Expected: FAIL because `openDisposition` is not supported.
+
+- [ ] **Step 3: Implement open disposition**
+
+Extend `OpenWorkspaceFileOptions`:
+
+```ts
+openDisposition?: "preview" | "pinned" | "preserve";
+```
+
+In the standalone source-file branch, before persisting, compute next tabs:
+
+```ts
+const openDisposition = options.openDisposition ?? "pinned";
+const currentOpenEditorTabs = store.get(openEditorTabsAtomFamily(workspaceId));
+const existingFileTab = currentOpenEditorTabs.find(
+  (tab) => tab.kind === "file" && tab.path === input.path
+);
+const existingPreviewTab = currentOpenEditorTabs.find(
+  (tab) => tab.kind === "file" && tab.pinned === false
+);
+const nextFileTab = {
+  kind: "file" as const,
+  path: input.path,
+  pinned: openDisposition !== "preview",
+};
+const nextOpenEditorTabs = existingFileTab
+  ? currentOpenEditorTabs.map((tab) =>
+      tab === existingFileTab ? { ...existingFileTab, pinned: nextFileTab.pinned } : tab
+    )
+  : openDisposition === "preview" && existingPreviewTab
+    ? currentOpenEditorTabs.map((tab) => (tab === existingPreviewTab ? nextFileTab : tab))
+    : [...currentOpenEditorTabs, nextFileTab];
+```
+
+Then set:
+
+```ts
+setOpenEditorTabs(nextOpenEditorTabs);
+setActiveEditorTab(nextFileTab);
+```
+
+Only append to `openEditorPaths` when the resolved tab is pinned:
+
+```ts
+const nextOpenEditorPaths =
+  nextFileTab.pinned === true
+    ? appendOpenEditorPath(store.get(openEditorPathsAtomFamily(workspaceId)), input.path)
+    : store.get(openEditorPathsAtomFamily(workspaceId));
+```
+
+Persist `openEditorTabs`, `activeEditorTab`, `activeEditorPath`, and the possibly unchanged `openEditorPaths`.
+
+- [ ] **Step 4: Route file tree single-clicks to preview**
+
+In `use-file-actions.ts`, change `handleSelectFile`:
+
+```ts
+void openWorkspaceFile(
+  {
+    workspaceId,
+    path,
+    source: "file-tree",
+  },
+  { openTarget: "navigate", openDisposition: "preview" }
+);
+```
+
+- [ ] **Step 5: Run tests to verify pass**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/workspace/actions/use-open-workspace-file.test.tsx src/features/workspace/actions/open-editor-state.test.ts
+```
+
+Expected: PASS.
+
+### Task 3: Add File Tree Double-Click Pinning
+
+**Files:**
+- Modify: `packages/web/src/features/workspace/views/shared/file-tree-panel.tsx`
+- Modify: `packages/web/src/features/workspace/actions/use-file-actions.ts`
+- Test: `packages/web/src/features/workspace/views/shared/file-tree-panel.test.tsx`
+
+- [ ] **Step 1: Add failing double-click test**
+
+In `file-tree-panel.test.tsx`, add a test that renders a file row and double-clicks it. Mock `useFileActions` or assert through existing integration setup that `openWorkspaceFile` receives `{ openDisposition: "pinned" }`.
+
+Use this assertion shape:
+
+```ts
+expect(openWorkspaceFile).toHaveBeenCalledWith(
+  { workspaceId: "ws-test", path: "src/app.ts", source: "file-tree" },
+  { openTarget: "navigate", openDisposition: "pinned" }
+);
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/workspace/views/shared/file-tree-panel.test.tsx
+```
+
+Expected: FAIL because rows do not have a pinning double-click path.
+
+- [ ] **Step 3: Add a pin handler**
+
+In `use-file-actions.ts`, add:
+
+```ts
+const handlePinFile = useCallback(
+  (path: string) => {
+    void openWorkspaceFile(
+      {
+        workspaceId,
+        path,
+        source: "file-tree",
+      },
+      { openTarget: "navigate", openDisposition: "pinned" }
+    );
+    onSelectFile?.(path);
+  },
+  [onSelectFile, openWorkspaceFile, workspaceId]
+);
+```
+
+Return `handlePinFile`.
+
+In `file-tree-panel.tsx`, thread `onPinFile` to file rows and attach:
+
+```tsx
+onDoubleClick={
+  node.kind === "file"
+    ? (event) => {
+        event.preventDefault();
+        onPinFile(node.path);
+      }
+    : undefined
+}
+```
+
+- [ ] **Step 4: Run test to verify pass**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/workspace/views/shared/file-tree-panel.test.tsx
+```
+
+Expected: PASS.
+
+### Task 4: Pin Preview Tabs on Editing and Preserve Mixed Tab Behavior
+
+**Files:**
+- Modify: `packages/web/src/features/code-editor/actions/use-code-editor-actions.ts`
+- Test: `packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx`
+
+- [ ] **Step 1: Add failing edit-to-pin test**
+
+Add to `use-code-editor-actions.browser-tabs.test.tsx`:
+
+```ts
+it("pins an active preview file tab when the user edits it", async () => {
+  const { store } = setupStore();
+  store.set(openEditorTabsAtomFamily("ws-1"), [
+    { kind: "file", path: "src/app.ts", pinned: false },
+  ]);
+  store.set(activeEditorTabAtomFamily("ws-1"), {
+    kind: "file",
+    path: "src/app.ts",
+    pinned: false,
+  });
+
+  const { result } = renderHook(() => useCodeEditorActions(), {
+    wrapper: createWrapper(store),
+  });
+
+  await act(async () => {
+    result.current.handleContentChange("export const app = 2;\n");
+  });
+
+  expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+    { kind: "file", path: "src/app.ts", pinned: true },
+  ]);
+  expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+    kind: "file",
+    path: "src/app.ts",
+    pinned: true,
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx
+```
+
+Expected: FAIL because editing does not pin preview tabs.
+
+- [ ] **Step 3: Pin active preview in `handleContentChange`**
+
+Inside `handleContentChange`, after dirty state update, add:
+
+```ts
+if (currentActiveEditorTab?.kind === "file" && currentActiveEditorTab.path === currentFile.path) {
+  const pinnedTab = { kind: "file" as const, path: currentFile.path, pinned: true };
+  if (isGlobalEditorState) {
+    setOpenEditorTabs((current) =>
+      current.map((tab) =>
+        tab.kind === "file" && tab.path === currentFile.path ? pinnedTab : tab
+      )
+    );
+    setActiveEditorTab(pinnedTab);
+  } else {
+    setLocalOpenEditorTabs((current) =>
+      current.map((tab) =>
+        tab.kind === "file" && tab.path === currentFile.path ? pinnedTab : tab
+      )
+    );
+    setLocalActiveEditorTab(pinnedTab);
+  }
+}
+```
+
+Persist the updated `openEditorTabs`, `activeEditorTab`, and append the path to `openEditorPaths` for global state.
+
+- [ ] **Step 4: Run test to verify pass**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx
+```
+
+Expected: PASS.
+
+### Task 5: Render Preview Tab Styling and Context Menu Actions
+
+**Files:**
+- Modify: `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx`
+- Modify: `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx`
+
+- [ ] **Step 1: Add failing tab header tests**
+
+Add tests:
+
+```ts
+it("marks preview file tabs with a preview class", () => {
+  render(
+    <CodeEditorTabsHeader
+      activeFilePath="src/preview.ts"
+      activeFullPath="/workspace/src/preview.ts"
+      activeEditorTab={{ kind: "file", path: "src/preview.ts", pinned: false }}
+      openEditorTabs={[{ kind: "file", path: "src/preview.ts", pinned: false }]}
+      openEditorPaths={[]}
+      openFiles={{}}
+      showPathRow={false}
+      onActivateOpenFile={vi.fn()}
+    />,
+    { wrapper: wrapperFor() }
+  );
+
+  expect(screen.getByRole("tab")).toHaveClass("code-editor-tab--preview");
+});
+
+it("opens a tab context menu with keep open for preview tabs", async () => {
+  const keepOpen = vi.fn();
+  render(
+    <CodeEditorTabsHeader
+      activeFilePath="src/preview.ts"
+      activeFullPath="/workspace/src/preview.ts"
+      activeEditorTab={{ kind: "file", path: "src/preview.ts", pinned: false }}
+      openEditorTabs={[{ kind: "file", path: "src/preview.ts", pinned: false }]}
+      openEditorPaths={[]}
+      openFiles={{}}
+      showPathRow={false}
+      onActivateOpenFile={vi.fn()}
+      onKeepOpenEditorTab={keepOpen}
+    />,
+    { wrapper: wrapperFor() }
+  );
+
+  fireEvent.contextMenu(screen.getByRole("tab"));
+  fireEvent.click(screen.getByRole("menuitem", { name: "Keep Open" }));
+
+  expect(keepOpen).toHaveBeenCalledWith({ kind: "file", path: "src/preview.ts", pinned: false });
+});
+```
+
+- [ ] **Step 2: Run tests to verify failure**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx
+```
+
+Expected: FAIL because preview class and context menu are missing.
+
+- [ ] **Step 3: Add header props and menu**
+
+Add optional props:
+
+```ts
+onCloseOtherEditorTabs?: (tab: WorkspaceEditorTab) => void;
+onCloseSavedEditorTabs?: () => void;
+onCloseEditorTabsToRight?: (tab: WorkspaceEditorTab) => void;
+onCloseAllEditorTabs?: () => void;
+onKeepOpenEditorTab?: (tab: WorkspaceEditorTab) => void;
+```
+
+Track context menu state:
+
+```ts
+const [contextMenu, setContextMenu] = useState<{
+  tab: WorkspaceEditorTab;
+  x: number;
+  y: number;
+} | null>(null);
+```
+
+Render a small `role="menu"` portal or inline fixed layer with menuitem buttons. Include `Keep Open` only when `tab.kind === "file" && tab.pinned === false`.
+
+Add `code-editor-tab--preview` and `code-editor-tab-item--preview` classes when `tab.kind === "file" && tab.pinned === false`.
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx
+```
+
+Expected: PASS.
+
+### Task 6: Implement Batch Tab Actions in Editor Actions
+
+**Files:**
+- Modify: `packages/web/src/features/code-editor/actions/use-code-editor-actions.ts`
+- Modify: `packages/web/src/features/code-editor/views/shared/code-editor-host.tsx`
+- Test: `packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx`
+
+- [ ] **Step 1: Add failing batch close tests**
+
+Add tests for:
+
+```ts
+it("closes saved file tabs while keeping dirty file tabs", async () => {
+  const { store } = setupStore();
+  store.set(openEditorTabsAtomFamily("ws-1"), [
+    { kind: "file", path: "src/app.ts", pinned: true },
+    { kind: "file", path: "src/dirty.ts", pinned: true },
+  ]);
+  store.set(openEditorPathsAtomFamily("ws-1"), ["src/app.ts", "src/dirty.ts"]);
+  store.set(openFilesAtomFamily("ws-1"), {
+    "src/app.ts": {
+      kind: "text",
+      path: "src/app.ts",
+      content: "a",
+      savedContent: "a",
+      baseHash: "hash-app",
+      isDirty: false,
+    },
+    "src/dirty.ts": {
+      kind: "text",
+      path: "src/dirty.ts",
+      content: "changed",
+      savedContent: "saved",
+      baseHash: "hash-dirty",
+      isDirty: true,
+    },
+  });
+
+  const { result } = renderHook(() => useCodeEditorActions(), {
+    wrapper: createWrapper(store),
+  });
+
+  await act(async () => {
+    result.current.closeSavedEditorTabs();
+  });
+
+  expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+    { kind: "file", path: "src/dirty.ts", pinned: true },
+  ]);
+});
+```
+
+Add a second test for `closeEditorTabsToRight`.
+
+- [ ] **Step 2: Run tests to verify failure**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx
+```
+
+Expected: FAIL because batch action methods are missing.
+
+- [ ] **Step 3: Implement batch action methods**
+
+Return these from `useCodeEditorActions`:
+
+```ts
+keepOpenEditorTab(tab: WorkspaceEditorTab): void
+closeOtherEditorTabs(tab: WorkspaceEditorTab): void
+closeEditorTabsToRight(tab: WorkspaceEditorTab): void
+closeSavedEditorTabs(): void
+closeAllEditorTabs(): void
+```
+
+Use the current ordered `openEditorTabsRef.current`. For file tabs, also update:
+
+- `openFiles`
+- `openEditorPaths`
+- `activeFilePath`
+- pending loads
+- persisted UI state
+
+For non-file tabs, use existing `closeEditorTab` identity behavior.
+
+- [ ] **Step 4: Wire header props**
+
+Where `CodeEditorTabsHeader` is rendered in `code-editor-host.tsx` and editor pane surfaces, pass the new methods:
+
+```tsx
+onKeepOpenEditorTab={state.keepOpenEditorTab}
+onCloseOtherEditorTabs={state.closeOtherEditorTabs}
+onCloseEditorTabsToRight={state.closeEditorTabsToRight}
+onCloseSavedEditorTabs={state.closeSavedEditorTabs}
+onCloseAllEditorTabs={state.closeAllEditorTabs}
+```
+
+- [ ] **Step 5: Run tests to verify pass**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx
+```
+
+Expected: PASS.
+
+### Task 7: Final Verification and Commit
+
+**Files:**
+- All files modified above
+
+- [ ] **Step 1: Run targeted tests**
+
+Run:
+
+```bash
+pnpm --dir packages/web exec vitest run src/features/workspace/actions/open-editor-state.test.ts src/features/workspace/actions/use-open-workspace-file.test.tsx src/features/workspace/actions/open-editors-close.test.ts src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx src/features/workspace/views/shared/file-tree-panel.test.tsx
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: Run repository lint**
+
+Run:
+
+```bash
+pnpm lint
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Review diff**
+
+Run:
+
+```bash
+git diff --stat
+git diff -- packages/web/src/features/workspace packages/web/src/features/code-editor
+```
+
+Expected: only files related to preview tabs and editor tab menu changed.
+
+- [ ] **Step 4: Commit**
+
+Run:
+
+```bash
+git add packages/web/src/features/workspace packages/web/src/features/code-editor docs/superpowers/plans/2026-06-25-vscode-preview-tabs.md
+git commit -m "feat: add preview editor tabs"
+```
+
+Expected: commit succeeds.
diff --git a/docs/superpowers/specs/2026-06-15-session-token-automation-design.md b/docs/superpowers/specs/2026-06-15-session-token-automation-design.md
new file mode 100644
index 000000000..462af5b91
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-15-session-token-automation-design.md
@@ -0,0 +1,161 @@
+# Session Token Automation Design
+
+> **Status:** Draft for user review  
+> **Date:** 2026-06-15  
+> **Scope:** `packages/server`, `packages/cli`, `packages/core`, tests
+
+## Goal
+
+Replace password-based re-login for agent automation with a per-session bearer token. The token should authorize local CLI/WebSocket automation for one active agent session without exposing the browser cookie auth path or broadening `/ws` access.
+
+## Decisions
+
+- Keep browser/UI auth unchanged. Existing cookie auth remains the only path for normal web sessions.
+- Add a separate session token for agent automation.
+- Bind each token to one `sessionId`, `workspaceId`, and `providerId`.
+- Accept the token only on loopback `/ws` requests.
+- Send the token as `Authorization: Bearer <token>` from CLI automation clients.
+- Use the token to derive a reduced automation permission set, not a full admin identity.
+- Do not add blanket `/ws` bypass or password re-login for automation.
+
+## Non-Goals
+
+- Do not replace browser login/session cookies.
+- Do not add a general-purpose personal access token system.
+- Do not introduce local IPC in this iteration.
+- Do not widen the auth model beyond local agent automation.
+
+## Existing Context
+
+- `packages/server/src/auth/plugin.ts` currently only validates cookie auth.
+- `packages/server/src/ws/dispatch.ts` currently enforces activation gating for websocket commands.
+- `packages/server/src/session/manager.ts` already injects `CODER_STUDIO_SESSION_ID`, `CODER_STUDIO_WORKSPACE_ID`, `CODER_STUDIO_PROVIDER_ID`, and `CODER_STUDIO_API_URL`.
+- `packages/cli/src/automation-command-client.ts` currently opens `/ws` without auth headers.
+- `packages/core/src/domain/automation.ts` defines automation identify/capability data and permission filtering.
+- `packages/server/src/commands/memory.ts` now rejects legacy `tag/tags` args and only accepts the current memory type set.
+
+## Architecture
+
+The change is a narrow automation auth layer:
+
+1. Session creation issues a high-entropy token and injects it into the agent environment.
+2. The CLI reads that token and sends it in the websocket `Authorization` header.
+3. The server accepts bearer auth for `/ws` only when the request is local.
+4. Websocket dispatch checks a token-scoped authorization context before running commands.
+5. Automation capability discovery reflects the scoped permissions for that token.
+
+The token is not a replacement for user auth; it is a session-bound credential for the agent process that already owns the session.
+
+## Token Model
+
+Create a server-side session-token store with entries shaped like:
+
+```ts
+{
+  token: string;
+  sessionId: string;
+  workspaceId: string;
+  providerId: string;
+  createdAt: number;
+  revokedAt?: number;
+}
+```
+
+Rules:
+
+- Token value must be high entropy and unguessable.
+- Token is valid only while the linked session exists and is not revoked.
+- Token is not reusable across sessions.
+- Token scope is the linked session's workspace and provider only.
+- Token never becomes a browser login cookie.
+
+## Auth Flow
+
+### Session creation
+
+When `SessionManager.create()` launches the agent terminal, it also generates a session token and injects it into the child environment as `CODER_STUDIO_SESSION_TOKEN`.
+
+### CLI transport
+
+`packages/cli/src/automation-command-client.ts` reads `CODER_STUDIO_SESSION_TOKEN` and adds:
+
+```ts
+headers: {
+  Authorization: `Bearer ${token}`,
+}
+```
+
+to the websocket connection.
+
+### Server validation
+
+`packages/server/src/auth/plugin.ts` accepts bearer auth for `/ws` only when:
+
+- auth is enabled,
+- the request is loopback/local,
+- the bearer token matches a live session token.
+
+Browser requests continue to rely on cookie auth.
+
+## Command Authorization
+
+Token auth must not imply unrestricted websocket command access.
+
+Allowed automation commands should remain small and session-scoped, including:
+
+- `automation.identify`
+- `automation.capabilities`
+- `session.list`
+- `terminal.read`
+- `git.status`
+- `git.diff`
+- `memory.list`
+- `memory.search`
+- `memory.get`
+- `memory.add`
+- `memory.update`
+- `memory.delete`
+- `uiAction.capabilities`
+- `uiAction.dispatch`
+
+Denied by default:
+
+- `workspace.list`
+- `session.create`
+- workspace admin / settings / install / destructive maintenance commands
+
+The token should also narrow the `automation.identify` and `automation.capabilities` responses so they only advertise commands the token can actually use.
+
+## CLI Memory Cleanup
+
+The `memory` CLI transport should be cleaned up as part of the same change:
+
+- stop sending legacy `tag/tags` arguments
+- align CLI memory type examples with the current server schema
+- keep `memory add/update/search/list/get/delete` wired to the current command names only
+
+This is a compatibility fix, not a new memory feature.
+
+## Tests
+
+Add coverage for:
+
+- valid session token can open `/ws`
+- invalid or missing token is rejected
+- non-loopback bearer auth is rejected
+- token-scoped commands allow `memory`, `git`, `ui`, and `session.list`
+- token-scoped commands deny `workspace.list` and `session.create`
+- CLI websocket client sends `Authorization`
+- `memory` CLI no longer emits legacy `tag/tags`
+
+## Risks
+
+- If token scope is too broad, the bearer token becomes a hidden admin credential.
+- If token scope is too narrow, automation will keep failing on common read paths.
+- If token revocation is not tied to session lifecycle, stale sessions may keep working after restart.
+
+## Open Questions
+
+- Should revoked session tokens be persisted or kept in memory only?
+- Should token invalidation happen on session end, workspace close, or both?
+- Should `automation.capabilities` expose only explicitly allowed commands or also return denied metadata for diagnostics?
diff --git a/docs/superpowers/specs/2026-06-16-dev-browser-query-sw-https-design.md b/docs/superpowers/specs/2026-06-16-dev-browser-query-sw-https-design.md
new file mode 100644
index 000000000..0d5b6e892
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-16-dev-browser-query-sw-https-design.md
@@ -0,0 +1,321 @@
+# Dev Browser Query + SW + HTTPS Design
+
+> Status: Draft for user review
+> Date: 2026-06-16
+> Scope: `packages/web` dev-browser UI and service worker, `packages/server` dev-browser routes and startup TLS support, related tests and docs
+
+## Goal
+
+Redesign the built-in browser so it can preview a local development server while
+preserving the browser-visible pathname of the target page.
+
+The design keeps the original `path` visible to the app and to SPA routers, while
+still routing requests through Coder Studio for loopback fetches. The design does
+not attempt to make the browser report the target's real `host` or `origin`.
+
+## User Problem
+
+The current dev browser uses a path-based proxy URL such as
+`/dev-browser/session/:id/proxy/...`. That creates two classes of failures:
+
+1. iframe navigations that redirect to a different path can land on the wrong
+   route because the proxy prefix leaks into the browser-visible URL
+2. SPA apps receive the proxy path instead of their real route, so they render the
+   wrong page or compute the wrong client-side route state
+
+## Design Summary
+
+The v1 redesign uses four pieces:
+
+1. A browser-visible URL that keeps the original pathname, plus a hidden session
+   token in query string form for the first load
+2. A root-scope service worker that binds a browser client to a dev-browser
+   session and routes later requests for that client
+3. A hidden server-side proxy base that the service worker forwards to
+4. Automatic HTTPS bootstrap for non-loopback IP access, backed by generated local
+   certificates when needed
+
+## In Scope
+
+- browser-visible URLs that preserve the target pathname
+- hidden session propagation through query parameters on the first load
+- a root-scope service worker that routes requests by client/session binding
+- server-side proxy routes that remain hidden from browser-visible navigation
+- automatic HTTPS for non-loopback IP access
+- automatic local certificate generation for development
+- clear fallback when the browser refuses the certificate
+- session cleanup and expiry
+- tests for routing, query handling, secure-context handling, and HTTPS fallback
+
+## Out Of Scope
+
+- preserving the target's true `host` or `origin`
+- browser automation or remote desktop rendering
+- WebSocket proxying in v1
+- HMR support in v1
+- user-managed certificate configuration in v1
+- changing file preview behavior
+
+## Existing State
+
+The current implementation lives in:
+
+- `packages/server/src/routes/dev-browser.ts`
+- `packages/web/public/dev-browser-sw.js`
+- `packages/web/src/features/dev-browser/dev-browser-surface.tsx`
+
+Today the iframe navigates through `/dev-browser/session/:id/proxy/...`, and the
+service worker is scoped only to `/dev-browser/`. That arrangement exposes the
+proxy path to the page and makes SPA route handling brittle.
+
+The server startup path currently has no TLS configuration. HTTPS support for
+non-loopback IP access must therefore be added as a new startup capability.
+
+## UX Flow
+
+1. The user opens the built-in browser tab.
+2. The user enters a loopback URL.
+3. The client creates a dev-browser session on the server.
+4. The iframe loads the target pathname with a hidden session query token.
+5. A root-scope service worker claims the page and binds that client to the session.
+6. Subsequent navigations and resource requests are routed to the hidden proxy base.
+7. The first document removes the session query from the visible URL after binding.
+
+## URL Model
+
+Given a target such as:
+
+```text
+http://localhost:8000/app/
+```
+
+The browser-visible URL should be the original path, not the proxy path. A first
+load can use a query token, for example:
+
+```text
+/app/?__cs_sid=dev_abc
+```
+
+The hidden proxy base remains server-internal:
+
+```text
+/dev-browser/session/dev_abc/proxy
+```
+
+The service worker uses the session binding to map requests like:
+
+```text
+GET /app/?__cs_sid=dev_abc
+GET /assets/main.js
+GET /api/data
+```
+
+to the hidden proxy base and then to the real loopback target.
+
+## Service Worker Model
+
+The service worker should be registered at a root scope when the current browser
+context supports it.
+
+The worker responsibilities are:
+
+- parse the session token from the initial request when present
+- bind `clientId` to `sessionId`
+- route same-client navigations and subresource requests to the hidden proxy base
+- preserve browser-visible `pathname`, `search`, and `hash` semantics
+- avoid rewriting the page into a proxy-prefixed path
+- only intercept loopback requests such as `localhost`, `127.0.0.1`, and `::1`
+- pass through non-loopback requests unchanged so the iframe can render them
+  normally
+
+The worker should not try to emulate a full browser. It should route requests at
+fetch time and only perform a small bootstrap-level URL cleanup in the first
+document.
+
+## Server API
+
+Session creation:
+
+```text
+POST /api/dev-proxy/session
+body: { "url": "http://localhost:8000" }
+response:
+{
+  "id": "dev_abc",
+  "browserUrl": "/app/?__cs_sid=dev_abc",
+  "browserProxyBase": "/dev-browser/session/dev_abc/proxy",
+  "targetOrigin": "http://127.0.0.1:8000"
+}
+```
+
+Session lookup and deletion remain authenticated API routes.
+
+Proxy requests remain on the hidden server path:
+
+```text
+ANY /dev-browser/session/:id/proxy/*
+```
+
+The public browser should not rely on that proxy path for normal navigation.
+
+## Target Validation
+
+Allowed preview targets:
+
+- `http://localhost:<port>`
+- `http://127.0.0.1:<port>`
+- `http://[::1]:<port>`
+
+Rejected targets:
+
+- non-HTTP/HTTPS protocols
+- loopback-free HTTP hosts
+- loopback-free HTTPS hosts
+- credentials in the URL
+- missing or invalid ports
+
+The server should canonicalize loopback connection targets for upstream access, but
+the browser-visible pathname must remain the original pathname.
+
+## HTTPS Strategy
+
+The dev browser needs a secure context when the browser is not already on HTTPS or
+loopback.
+
+Rules:
+
+- if the Coder Studio UI is already on HTTPS, enable the new service worker flow
+- if the UI is on `localhost`, `127.0.0.1`, `::1`, or `*.localhost`, enable the
+  new flow without additional certificates
+- if the UI is accessed through a non-loopback IP over HTTP, the server should
+  automatically switch to HTTPS
+- if HTTPS is required, the server should auto-generate local certificates on
+  startup or first use
+- if the certificate is not trusted by the browser, show a clear warning and allow
+  the user to continue manually or fall back to the legacy proxy path
+
+The first version should use automatic certificate generation only. User-managed
+certificate inputs are out of scope.
+
+## Certificate Handling
+
+The certificate mechanism should be development-friendly rather than production
+grade.
+
+Recommended behavior:
+
+- generate and reuse a local CA under the Coder Studio state directory
+- issue a leaf certificate for the current server host or IP
+- include SAN entries for the current access host and common loopback names where
+  practical
+- prefer HTTPS when the server is started on a non-loopback IP
+
+The design does not require perfect automatic trust installation. When trust is
+missing, the browser may present its normal TLS warning and the UI should explain
+what to do.
+
+## Browser Bootstrap
+
+The first document loaded by the iframe should:
+
+- read the hidden session token from query parameters
+- register or update the root-scope service worker when available
+- bind the client to the active dev-browser session
+- call `history.replaceState` to remove the session query from the visible URL
+- avoid broad `fetch`, `XMLHttpRequest`, or `WebSocket` monkey-patching unless a
+  test proves the worker cannot cover a required case
+
+## Hidden Proxy
+
+The server-side proxy continues to own actual loopback fetching.
+
+Responsibilities:
+
+- forward HTTP methods and request bodies to the target origin
+- filter hop-by-hop and sensitive headers
+- rewrite redirect locations only into browser-visible paths, not proxy paths
+- preserve response types for HTML, CSS, JavaScript, images, JSON, and other
+  ordinary assets
+
+WebSocket proxying remains out of scope for v1.
+
+## Error Handling
+
+The browser should show explicit states for:
+
+- invalid URL input
+- unsupported non-loopback HTTP URL
+- HTTPS required for IP access
+- TLS trust failure
+- expired or missing session token
+- service worker unsupported in this browser context
+
+When the certificate is blocked, the UI should present a direct explanation and a
+manual proceed option before falling back.
+
+Requests that do not match the local loopback interception rules should not be
+treated as dev-browser errors.
+
+## Security
+
+This remains a local proxy feature, not a general proxy.
+
+Required protections:
+
+- inherit existing Coder Studio authentication
+- require a valid dev-browser session for all proxy traffic
+- validate upstream targets server-side
+- keep proxy routes hidden from normal browser navigation
+- expire sessions after inactivity
+- delete sessions when the browser tab closes when possible
+- do not expose the hidden proxy base as the browser-visible route model
+
+## Testing
+
+Server tests:
+
+- accept loopback HTTP URLs
+- accept HTTPS URLs for secure-context flows
+- reject unsupported HTTP IP access until HTTPS is available
+- create browser URLs that preserve the target path and carry a hidden session token
+- proxy requests from the hidden base to the loopback target
+- rewrite redirects to browser-visible paths
+- generate or select TLS material for non-loopback IP access
+
+Web tests:
+
+- browser tab opens with a visible path, not a proxy path
+- initial session query is removed after binding
+- root-scope service worker receives the session binding
+- SPA-style navigation keeps the visible pathname correct
+- certificate-blocked states surface the expected UI
+
+## Risks
+
+- Root-scope service worker behavior differs across browsers and security contexts.
+- Certificate generation and trust behavior varies by platform.
+- Session binding must survive reloads and navigation without leaking into the
+  visible route.
+- The legacy proxy path should remain as a fallback until the new flow is stable.
+
+## Rollout Plan
+
+1. Add the new query-based URL model behind the dev browser entry path.
+2. Add root-scope service worker routing and session binding.
+3. Add HTTPS startup support for non-loopback IP access.
+4. Keep the legacy proxy flow as fallback until the new flow is verified.
+5. Remove or de-emphasize the old proxy-prefixed browser-visible path once the new
+   flow is stable.
+
+## Implementation Notes
+
+This work should stay focused on the built-in browser feature.
+
+Recommended file boundaries:
+
+- session and URL model in `packages/server/src/routes/dev-browser.ts`
+- service worker routing in `packages/web/public/dev-browser-sw.js`
+- browser tab UI and bootstrap handling in
+  `packages/web/src/features/dev-browser/dev-browser-surface.tsx`
+- TLS bootstrap in the server startup path
+- tests next to the touched modules
diff --git a/docs/superpowers/specs/2026-06-18-workspace-memory-taxonomy-status-design.md b/docs/superpowers/specs/2026-06-18-workspace-memory-taxonomy-status-design.md
new file mode 100644
index 000000000..0fd1b3eec
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-18-workspace-memory-taxonomy-status-design.md
@@ -0,0 +1,289 @@
+# Workspace Memory Taxonomy And Status Design
+
+> Date: 2026-06-18
+> Status: Draft for user review
+> Owner: Codex
+
+## Problem
+
+Workspace memory currently uses five string literal types:
+
+```ts
+feature | todo | bugfix | project | note
+```
+
+Those values have become ambiguous:
+
+- `project` sounds narrower than the actual use case, which includes reusable
+  project knowledge, commands, conventions, architecture notes, and stable
+  operating context.
+- `bugfix` describes an implementation action, while users need a category for
+  the underlying problem.
+- `feature` can mean either an already existing capability or a future request.
+  The product direction is to avoid that split for now.
+- A single progress/status field should not apply to informational memory such
+  as wiki notes.
+
+There are also two nearby UI issues in the active memory todo set:
+
+- On desktop, selecting a type in the create-memory dropdown does not close the
+  dropdown.
+- The draggable split line can sit above the editor and should not remain
+  visually prominent.
+
+## Goal
+
+Simplify memory taxonomy to four durable categories and add progress only where
+progress has clear meaning:
+
+```ts
+wiki | issue | todo | note
+```
+
+The final user-facing order is:
+
+1. Wiki
+2. Issue / 问题
+3. Todo / 待办
+4. Note / 备注
+
+Only `issue` and `todo` entries can carry progress. `wiki` and `note` are
+informational and do not expose or persist progress.
+
+## Non-Goals
+
+- Do not add separate `capability`, `feature`, `request`, or `improvement`
+  categories in this iteration.
+- Do not build a dedicated migration command or startup migration pass.
+- Do not introduce tags, title, hierarchy, assignees, due dates, or priority.
+- Do not change memory storage from workspace-scoped JSON files.
+- Do not redesign the whole memory panel layout.
+- Do not add mobile-specific memory UI beyond keeping shared behavior valid.
+
+## Decisions
+
+Use a constant object plus ordered arrays instead of a TypeScript `enum`.
+
+```ts
+export const WorkspaceMemoryType = {
+  Wiki: "wiki",
+  Issue: "issue",
+  Todo: "todo",
+  Note: "note",
+} as const;
+
+export const WORKSPACE_MEMORY_TYPES = [
+  WorkspaceMemoryType.Wiki,
+  WorkspaceMemoryType.Issue,
+  WorkspaceMemoryType.Todo,
+  WorkspaceMemoryType.Note,
+] as const;
+```
+
+This keeps centralized named values, preserves ordering, works with existing
+`z.enum(WORKSPACE_MEMORY_TYPES)`, and makes legacy alias handling explicit.
+
+Add a status field for actionable entries:
+
+```ts
+export const WorkspaceMemoryStatus = {
+  NotStarted: "not_started",
+  InProgress: "in_progress",
+  PendingVerification: "pending_verification",
+  Completed: "completed",
+} as const;
+```
+
+Status applies only to `issue` and `todo`.
+
+## Legacy Type Compatibility
+
+Old stored values and temporary API/CLI inputs map to the new taxonomy:
+
+```text
+project -> wiki
+bugfix  -> issue
+feature -> wiki
+todo    -> todo
+note    -> note
+```
+
+The `feature -> wiki` mapping is intentional. The existing workspace memory
+entries using `feature` are mostly stable facts about existing product behavior.
+Since the product is not keeping a separate capability/improvement split in this
+iteration, `wiki` is the least ambiguous destination.
+
+Compatibility behavior:
+
+- Reading old JSON normalizes legacy types before returning runtime entries.
+- API and CLI may accept legacy type aliases during this transition.
+- New command responses and new writes return only `wiki`, `issue`, `todo`, or
+  `note`.
+- The next create, update, or delete for a workspace rewrites the whole memory
+  file in normalized form through the existing repository write path.
+- Invalid unknown types still fail validation or are skipped during legacy file
+  normalization, matching the current repository tolerance.
+
+## Status Semantics
+
+Valid statuses:
+
+```text
+not_started
+in_progress
+pending_verification
+completed
+```
+
+Rules:
+
+- New `issue` and `todo` entries default to `not_started` when no status is
+  provided.
+- New `wiki` and `note` entries have no `status`.
+- Updating an entry from `issue` or `todo` to `wiki` or `note` clears `status`.
+- Updating an entry from `wiki` or `note` to `issue` or `todo` defaults status
+  to `not_started` unless a valid status is provided.
+- Search remains content/type-based. Status does not need search matching in
+  this iteration.
+
+The intended workflow is:
+
+- Agents or users mark work as `in_progress` when actively handling it.
+- Agents may mark finished work as `pending_verification` so the user can
+  verify it.
+- Users can mark verified work as `completed`.
+
+## Core Contract
+
+`packages/core/src/domain/memory.ts` should expose:
+
+- `WorkspaceMemoryType` constant object
+- `WORKSPACE_MEMORY_TYPES` ordered array
+- `WorkspaceMemoryStatus` constant object
+- `WORKSPACE_MEMORY_STATUSES` ordered array
+- `WorkspaceMemoryEntry.status?: WorkspaceMemoryStatus`
+- validation helpers that normalize legacy type aliases and enforce status
+  applicability
+
+The validated create/update result should never contain legacy types. It should
+also omit status for non-actionable types.
+
+## Server Behavior
+
+`packages/server/src/commands/memory.ts` should:
+
+- validate `memory.create`, `memory.update`, `memory.list`, and `memory.search`
+  against the new canonical type set plus accepted legacy aliases
+- accept optional `status` for create/update
+- reject invalid statuses
+- normalize legacy types before reaching storage
+
+`packages/server/src/storage/repositories/memory-repo.ts` should:
+
+- normalize legacy stored types while reading files
+- normalize or clear status according to type during create/update
+- write only canonical types and valid statuses
+- keep sorting, soft delete, workspace file naming, and missing-file behavior
+  unchanged
+
+## CLI And Automation Metadata
+
+Automation capability descriptions and CLI help/examples should list only:
+
+```text
+wiki | issue | todo | note
+```
+
+During the compatibility window, callers using `project`, `bugfix`, or
+`feature` should still work, but docs and examples should not encourage those
+values.
+
+## Web UI
+
+`MemoryPanel` should:
+
+- show type options in the order Wiki, Issue, Todo, Note
+- use localized labels:
+  - English: Wiki, Issue, Todo, Note
+  - Chinese: Wiki, 问题, 待办, 备注
+- show status controls only for `issue` and `todo`
+- hide status controls for `wiki` and `note`
+- clear local draft status when the selected type becomes `wiki` or `note`
+- default local draft status to `not_started` when the selected type becomes
+  `issue` or `todo`
+- render status badges or metadata for actionable entries only
+
+The existing content-only memory shape remains unchanged otherwise.
+
+## Adjacent UI Fixes
+
+### Desktop Select Close
+
+The desktop select/listbox behavior should close after selecting an option. The
+fix should live in the shared select component if the broken behavior is generic;
+otherwise it can be scoped to the memory type select. Tests should prove that a
+desktop option click updates the value and closes the listbox.
+
+### Split Handle Layering
+
+The draggable split handle should remain usable but not visually cover the
+editor:
+
+- lower the handle overlay z-index relative to editor content where possible
+- make the visible divider transparent or effectively invisible
+- preserve the pointer target size so resizing remains ergonomic
+- avoid broad layout refactors in pane or editor rendering
+
+## Testing
+
+Focused tests should cover:
+
+- core memory type/status constants and validation
+- legacy type normalization:
+  - `project -> wiki`
+  - `bugfix -> issue`
+  - `feature -> wiki`
+- status applicability:
+  - `issue`/`todo` keep or default status
+  - `wiki`/`note` omit status
+  - changing to a non-actionable type clears status
+- server command schemas accept canonical types and temporary legacy aliases
+- repository reads old files without dropping valid entries
+- memory panel renders the four type options in order
+- memory panel only shows status controls for actionable types
+- desktop select closes after an option selection
+
+For handoff, run the relevant package tests first, then repository verification
+if time permits:
+
+```bash
+pnpm --filter @coder-studio/core test
+pnpm --filter @coder-studio/server test
+pnpm --filter @coder-studio/web test
+pnpm ci:verify
+```
+
+## Risks
+
+- Existing user data with old type strings must not disappear. This is addressed
+  by read-time normalization.
+- Agents or scripts may still send `project`, `bugfix`, or `feature`. Temporary
+  command-level aliases reduce breakage while docs move to canonical names.
+- Status can become misleading if exposed on informational entries. The schema
+  and UI both avoid status for `wiki` and `note`.
+- Changing shared select behavior may affect other desktop selects. The test
+  should check the shared expectation and implementation should preserve current
+  mobile sheet behavior.
+
+## Validation
+
+The feature is complete when:
+
+- `memory.list` returns only `wiki`, `issue`, `todo`, or `note` types.
+- Old memory files containing `project`, `bugfix`, or `feature` still load.
+- New writes persist only canonical types.
+- `issue` and `todo` can display and update status.
+- `wiki` and `note` do not display or persist status.
+- The desktop memory type dropdown closes on selection.
+- The split drag handle no longer visibly covers editor content while remaining
+  draggable.
diff --git a/docs/superpowers/specs/2026-06-20-external-browser-proxy-grants-design.md b/docs/superpowers/specs/2026-06-20-external-browser-proxy-grants-design.md
new file mode 100644
index 000000000..09f7389fc
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-20-external-browser-proxy-grants-design.md
@@ -0,0 +1,471 @@
+# External Browser Proxy Grants Design
+
+> Status: Draft for user review
+> Date: 2026-06-20
+> Scope: `packages/server` proxy grant APIs and dedicated proxy listener, `packages/web` proxy management panel, related tests and docs
+
+## Goal
+
+Allow users to open an internal or otherwise browser-inaccessible HTTP service in a
+normal browser tab by routing traffic through Coder Studio, while keeping Coder
+Studio's own UI origin isolated from the proxied application origin.
+
+The feature must support:
+
+- ordinary HTTP page loads and static assets
+- same-origin `fetch` and `XMLHttpRequest`
+- browser WebSocket connections
+- short-lived, revocable authorization grants
+- browser-extension-based request header injection such as ModHeader or Requestly
+
+## Decisions
+
+- Keep the proxy entry outside the built-in dev browser. This is for normal browser
+  tabs, not iframe-based workspace previews.
+- Require two request headers on proxy traffic:
+  - `X-CS-Proxy-Target`
+  - `X-CS-Proxy-Grant`
+- Bind every grant to exactly one normalized target origin.
+- Run the proxy on a dedicated origin, not on the main Coder Studio UI origin.
+- Require both normal Coder Studio browser auth and a valid proxy grant.
+- Return the raw grant token only at create time and rotate time.
+- Add a lightweight `Proxy Access` management panel in the Coder Studio UI.
+- Support WebSocket tunneling on the dedicated proxy origin.
+
+## Non-Goals
+
+- Do not proxy through the main UI origin such as `http://localhost:4444/...`.
+- Do not support unauthenticated or open-proxy behavior.
+- Do not add plugin-specific browser extension installation flows in v1.
+- Do not rewrite arbitrary HTML or JavaScript response bodies to fix hard-coded
+  absolute upstream URLs.
+- Do not support non-HTTP targets such as `file:`, unix sockets, or raw TCP.
+- Do not add per-grant insecure TLS bypass toggles in v1.
+
+## Why a Dedicated Origin Is Required
+
+If proxied content is served from the same origin as Coder Studio itself, the
+proxied page becomes same-origin with Coder Studio APIs, websocket transport, and
+cookie-backed session state. That breaks the application's security boundary.
+
+The proxy must therefore live on a separate origin, for example:
+
+- main UI: `http://localhost:4444`
+- proxy: `http://localhost:4445`
+
+The safest v1 shape is the same hostname plus a different port. Same host plus
+different port is a different browser origin and still allows the browser to send
+the existing host-scoped auth cookie to both listeners.
+
+Using a different hostname is a possible future option, but it is out of scope for
+v1 unless the auth cookie model is extended to support an explicit shared cookie
+domain. The current browser auth model should be assumed to be host-scoped.
+
+## Existing Context
+
+Coder Studio already has:
+
+- cookie-backed browser auth enforced by a global Fastify auth guard
+- a built-in dev browser proxy path family under `/dev-browser/`
+- existing route reservations for `/api`, `/auth`, `/internal`, `/assets`, and
+  `/dev-browser`
+
+Those existing dev-browser routes are not the right foundation here. They were
+designed for iframe-hosted preview behavior, not for a first-class external browser
+entry protected by extension-injected headers.
+
+## User Flow
+
+1. The user signs in to Coder Studio on the main UI origin.
+2. The user opens `Settings > Proxy Access`.
+3. The user creates a grant by entering:
+   - a label
+   - a target origin such as `http://10.20.0.15:8080` or `https://git.corp.local`
+   - whether WebSocket proxying is allowed
+   - a TTL preset such as `1 hour`, `24 hours`, or `7 days`
+4. The server validates the target against proxy target policy and creates the
+   grant.
+5. The UI shows a one-time setup modal containing:
+   - the dedicated proxy origin
+   - the exact `X-CS-Proxy-Target` header value
+   - the exact `X-CS-Proxy-Grant` token
+   - example browser-extension match rules for both HTTP and WebSocket traffic
+6. The user configures a browser extension to inject those headers for the proxy
+   origin.
+7. The user opens the proxy origin in a normal browser tab, for example
+   `http://localhost:4445/`.
+8. Requests reaching the proxy origin include the extension headers, so the server
+   authenticates and forwards them to the bound upstream target.
+9. The `Proxy Access` panel later lets the user inspect, extend, rotate, or revoke
+   grants.
+
+## Interaction Design
+
+## Panel Placement
+
+Add a lightweight `Proxy Access` panel under Settings. This is a global account or
+server-session feature, not a workspace tab feature.
+
+The panel has two areas:
+
+- `Create Grant`
+- `Active and Recent Grants`
+
+## Create Grant Form
+
+Fields:
+
+- `Label`
+- `Target Origin`
+- `Allow WebSocket`
+- `TTL`
+
+Validation:
+
+- require an absolute `http://` or `https://` origin
+- normalize host casing, default ports, and trailing slash
+- reject paths, hashes, usernames, and passwords in the target field
+- reject targets outside configured allow policy
+
+## Post-Create Modal
+
+After create and after rotate, the UI opens a modal with:
+
+- `Proxy Origin`
+- `Header 1: X-CS-Proxy-Target`
+- `Header 2: X-CS-Proxy-Grant`
+- copy buttons for each value
+- copyable extension match patterns for:
+  - `http://<proxy-host>:<proxy-port>/*`
+  - `https://<proxy-host>:<proxy-port>/*`
+  - `ws://<proxy-host>:<proxy-port>/*`
+  - `wss://<proxy-host>:<proxy-port>/*`
+
+The modal must explicitly say that the raw grant token is shown only once. If the
+user loses it, the recovery path is `Rotate`, not `Reveal`.
+
+## Grant List
+
+Each row shows:
+
+- label
+- target origin
+- websocket enabled state
+- created at
+- expires at
+- last used at
+- status: `active`, `expired`, or `revoked`
+
+Row actions:
+
+- `Extend`
+- `Rotate`
+- `Revoke`
+
+`Extend` keeps the existing token and lengthens validity.  
+`Rotate` returns a new raw token and invalidates the old token immediately.  
+`Revoke` permanently disables the grant and clears proxy session state tied to it.
+
+## Architecture
+
+The feature has three layers:
+
+1. Main UI app on the existing Coder Studio origin
+2. Dedicated proxy app on a separate origin
+3. Shared grant and cookie-jar state inside the same server process
+
+The main UI app handles grant management APIs and panel rendering.
+
+The dedicated proxy app handles:
+
+- authenticated HTTP proxying
+- authenticated WebSocket upgrades
+- upstream cookie-jar management
+- top-level proxy error pages
+
+The server process starts both listeners together and stops them together.
+
+## Server Configuration
+
+Extend server config with a proxy section similar to:
+
+```ts
+proxy: {
+  enabled: boolean;
+  host: string;
+  port: number;
+  publicOrigin?: string;
+  maxGrantTtlMs: number;
+  allowedHosts: string[];
+  allowedCidrs: string[];
+  allowLoopback: boolean;
+}
+```
+
+Defaults:
+
+- proxy disabled unless explicitly enabled
+- proxy host defaults to main server host
+- proxy port defaults to `mainPort + 1`
+- loopback allowed when proxy is enabled
+- non-loopback intranet targets require explicit allow policy
+
+`publicOrigin` is needed when Coder Studio sits behind a reverse proxy and the
+externally visible proxy URL differs from the internal listener address.
+
+For v1, `publicOrigin` should preserve the same hostname as the main UI origin and
+only vary by port or outer reverse-proxy port mapping, so existing browser auth
+cookies continue to apply.
+
+## Grant Model
+
+Persist grants in a new server-side repository, for example `proxy-grants.json`.
+
+```ts
+type ProxyGrantRecord = {
+  id: string;
+  label: string;
+  targetOrigin: string;
+  allowWebSocket: boolean;
+  tokenHash: string;
+  createdAt: number;
+  expiresAt: number;
+  revokedAt: number | null;
+  lastUsedAt: number | null;
+  lastUsedIp: string | null;
+};
+```
+
+Rules:
+
+- store only a hash of the token, never the raw token
+- token must be high entropy and unguessable
+- one grant maps to one exact target origin
+- a revoked grant never becomes active again
+- an expired grant may be extended or rotated
+- rotate clears the previous token and generates a new token
+
+## Target Policy
+
+Proxying internal services is SSRF-sensitive. Target validation must happen both at
+grant creation time and at connection time.
+
+Rules:
+
+- allow only `http` and `https`
+- require an explicit origin, not an arbitrary URL with path
+- deny `file:`, `ftp:`, `ws:`, `wss:`, unix sockets, and raw hostless forms
+- deny targets that fall outside configured host and CIDR policy
+- re-resolve hostname targets on each new upstream connection and re-check the
+  resolved IPs against policy to avoid DNS rebinding
+
+Recommended default:
+
+- allow loopback
+- deny all non-loopback private network targets unless the admin explicitly
+  configured allow rules
+
+## Cookie and Session Handling
+
+The proxy must not blindly expose upstream cookies to the browser because all proxy
+targets would otherwise share one browser cookie namespace on the proxy origin.
+
+Instead, the server keeps a per-grant upstream cookie jar in memory:
+
+- inbound browser `Cookie` headers are not forwarded upstream except for cookies the
+  proxy itself owns
+- upstream `Set-Cookie` headers are captured into the per-grant jar
+- later HTTP requests and WebSocket handshakes for the same grant replay those
+  upstream cookies
+- revoking, rotating, or expiring a grant clears its cookie jar
+- proxy cookie jars do not need to survive server restart in v1
+
+This preserves most cookie-based upstream sessions without leaking one target's
+cookies into another target's requests.
+
+## Authentication Model
+
+Every proxy request must pass two checks:
+
+1. existing browser auth cookie validation
+2. proxy grant validation
+
+The proxy app reuses the same auth-session repository as the main UI app, so a user
+must still be logged in through the normal Coder Studio auth flow.
+
+Then the proxy app validates:
+
+- `X-CS-Proxy-Grant` exists
+- `X-CS-Proxy-Target` exists
+- the token hash matches a live, unrevoked grant
+- the header target exactly matches the grant's normalized `targetOrigin`
+- the target still satisfies current target policy
+
+This keeps grant leakage from becoming a complete bypass when the user is no longer
+authenticated in the browser.
+
+## Main UI APIs
+
+Add management endpoints on the main UI origin:
+
+- `GET /api/proxy/config`
+- `POST /api/proxy/grants`
+- `GET /api/proxy/grants`
+- `POST /api/proxy/grants/:id/extend`
+- `POST /api/proxy/grants/:id/rotate`
+- `DELETE /api/proxy/grants/:id`
+
+Create response shape:
+
+```json
+{
+  "id": "pgr_123",
+  "label": "grafana staging",
+  "targetOrigin": "http://10.20.0.15:8080",
+  "allowWebSocket": true,
+  "expiresAt": 1780000000000,
+  "proxyOrigin": "http://localhost:4445",
+  "grantToken": "pgt_..."
+}
+```
+
+`grantToken` is returned only by `create` and `rotate`.
+
+List responses must omit the raw token.
+
+## Dedicated Proxy Routing
+
+The dedicated proxy origin proxies requests from `/` downward:
+
+- `GET /`
+- `GET /assets/app.js`
+- `POST /api/login`
+- `WS /ws`
+
+All of those use the bound target origin from the headers and grant lookup.
+
+A request like:
+
+```text
+GET http://localhost:4445/app?tab=1
+X-CS-Proxy-Target: http://10.20.0.15:8080
+X-CS-Proxy-Grant: pgt_...
+```
+
+becomes:
+
+```text
+GET http://10.20.0.15:8080/app?tab=1
+```
+
+This root-level proxy model preserves compatibility with applications that use
+absolute root paths such as `/assets/main.js` or `/ws`.
+
+## HTTP Forwarding Rules
+
+For each proxied HTTP request:
+
+1. validate auth cookie and grant headers
+2. build upstream URL from:
+   - grant target origin
+   - incoming pathname
+   - incoming query string
+3. stream the request body upstream
+4. strip proxy-only and hop-by-hop headers
+5. rewrite request metadata where needed:
+   - `Host` becomes upstream host
+   - `Origin` becomes upstream origin when present
+   - `Referer` is rewritten when it points at the proxy origin
+6. attach cookies from the server-side cookie jar
+7. stream the upstream response back to the browser
+8. capture upstream `Set-Cookie` into the jar instead of forwarding it directly
+9. rewrite redirect `Location` headers that point at the target origin so the
+   browser stays on the proxy origin
+
+Response body rewriting is out of scope in v1. Applications that hard-code absolute
+upstream URLs inside HTML or JavaScript may still fail.
+
+## WebSocket Forwarding Rules
+
+For each WebSocket upgrade:
+
+1. validate auth cookie and grant headers
+2. verify the grant allows WebSocket traffic
+3. convert target protocol:
+   - `http` -> `ws`
+   - `https` -> `wss`
+4. preserve incoming pathname and query string
+5. open one upstream WebSocket connection for one browser WebSocket connection
+6. rewrite `Origin` to the upstream origin
+7. attach cookies from the server-side cookie jar
+8. tunnel frames transparently in both directions
+9. propagate close codes and errors
+
+No multiplexing, message inspection, or protocol-aware rewriting is needed.
+
+## Error Handling
+
+Expected error codes:
+
+- `400 proxy_headers_required`
+- `400 invalid_proxy_target`
+- `401 auth_required`
+- `403 proxy_grant_invalid`
+- `403 proxy_grant_expired`
+- `403 proxy_grant_revoked`
+- `403 proxy_target_not_allowed`
+- `403 proxy_websocket_not_allowed`
+- `409 proxy_target_mismatch`
+- `502 upstream_unreachable`
+- `504 upstream_timeout`
+
+For top-level HTML navigations on the proxy origin, return a simple HTML error page
+with:
+
+- a short human-readable message
+- the failing target
+- a link back to the main Coder Studio UI
+
+For subresources, XHR, and WebSocket failures, return protocol-appropriate status
+codes only.
+
+## Limitations
+
+The v1 proxy is intended for applications that primarily use:
+
+- relative asset URLs
+- same-origin API calls
+- same-origin WebSocket URLs
+
+Applications that hard-code absolute URLs to their original upstream origin may
+bypass the proxy model and fail in the browser. That limitation should be called out
+in the panel help text and user-facing docs.
+
+Simultaneous multi-target browsing from one browser profile is also intentionally
+simple in v1. Because the browser extension injects one header rule set per proxy
+origin, users will typically enable one grant configuration at a time unless their
+extension supports multiple toggled profiles.
+
+## Testing
+
+Add coverage for:
+
+- grant create, list, extend, rotate, revoke lifecycle
+- raw token returned only on create and rotate
+- token hash persistence and invalid token rejection
+- target normalization and policy enforcement
+- DNS rebinding protection checks
+- proxy app auth cookie plus grant enforcement
+- HTTP forwarding, redirect rewrite, and cookie-jar capture
+- WebSocket upgrade success, close propagation, and websocket-disabled rejection
+- panel create flow, one-time token modal, and grant row actions
+
+## Risks
+
+- If target allow policy is too broad, the proxy becomes an internal SSRF tool.
+- If cookie handling is too permissive, one upstream service can leak state into
+  another target's requests.
+- If the proxy origin accidentally collapses back onto the main UI origin, the
+  design becomes unsafe even if grant validation is correct.
+- If grant rotation does not invalidate the old token immediately, leaked tokens
+  remain useful longer than expected.
diff --git a/docs/superpowers/specs/2026-06-20-global-custom-skills-design.md b/docs/superpowers/specs/2026-06-20-global-custom-skills-design.md
new file mode 100644
index 000000000..a1b99e04a
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-20-global-custom-skills-design.md
@@ -0,0 +1,648 @@
+# Global Custom Skills Design
+
+Date: 2026-06-20
+Status: Draft
+Owner: codex
+
+## Problem
+
+当前产品已经有一套 `Skills` 管理链路：
+
+- 可以展示公共 skill 库
+- 可以区分 `skillhub / local / builtin`
+- 可以对 skill 执行挂载、卸载、修复、更新
+- 可以在右侧 `Skills` 面板中查看已安装和 built-in skill
+
+但它还缺少“产品内创建和维护自定义 skill”的完整体验。当前用户如果想做一个自定义 skill，需要在产品外手工：
+
+- 在 `~/.agents/skills/<slug>/` 下新建目录
+- 手写 `SKILL.md`
+- 自己管理目录内的其他文件
+- 回到产品里等待本地扫描把它显示出来
+
+这条链路的问题不是“少一个创建按钮”这么简单，而是产品对 `local` skill 只做了“扫描并展示”的被动支持，还没有给用户提供一条主动的、闭环的创作路径：
+
+- 缺少 `Custom Skills` 入口，用户无法区分“我自己创建的 skill”和“安装来的 skill”
+- 缺少创建流程，用户不能直接在产品里生成 `SKILL.md`
+- 缺少目录树，用户看不到一个 skill 目录下的全部文件
+- 缺少文件级管理动作，用户不能新建、重命名、删除 skill 内文件
+- 缺少和现有 editor 的联动，skill 文件不能像 workspace 文件一样直接进入编辑器
+- 缺少把 skill 目录拖到 agent 的直接交互
+
+用户要的不是“把 skill 面板做成第二个重量级文件管理器”，而是一条更轻的创作流：
+
+- 在产品里创建全局自定义 skill
+- 默认先不启用
+- 能看到该 skill 对应的目录和全部文件
+- 点文件后直接用现有 editor 编辑
+- 必要时把整个 skill 目录路径拖给 agent，让 agent 去改
+
+## Goals
+
+- 在 `Skills` 面板中新增明确的 `Custom Skills` section。
+- 支持在产品内创建全局自定义 skill，目标目录为 `~/.agents/skills/<slug>/`。
+- 创建时只要求输入 skill 名称，自动生成 slug 和 `SKILL.md`。
+- 创建后的自定义 skill 默认不启用。
+- 在产品内浏览单个 skill 目录的完整树结构。
+- 支持对 skill 目录执行轻量文件管理：新建文件、新建文件夹、重命名、删除。
+- 点击 skill 文件后，复用现有 editor 打开和编辑，而不是在 `Skills` 面板中重造一套编辑器。
+- 支持把 skill 根目录或单个文件拖到 agent，会话中只插入路径文本，不引入特殊附件语义。
+- 自定义 skill 与现有挂载体系兼容，仍沿用已有启用/禁用逻辑。
+
+## Non-Goals
+
+- 这次不做 workspace 级自定义 skill；自定义 skill 是应用级全局资源。
+- 这次不做“导入一个现有本地目录并自动变成 skill”的流程。
+- 这次不做“复制 skill”“skill 模板市场”“版本历史”“撤销恢复”等进阶能力。
+- 这次不在 `Skills` 面板内内嵌代码编辑器。
+- 这次不把自定义 skill 伪装成某个 workspace 的文件树节点。
+- 这次不支持重命名 skill slug 本身，也不支持移动 skill 根目录。
+- 这次不改变现有 mounted skill、built-in skill、skills-hub 搜索安装的基础行为。
+
+## Current Context
+
+### Existing Local Skill Model
+
+服务端已经会扫描本地全局 skill 根目录：
+
+- [`packages/server/src/skills/local-skill-scanner.ts`](../../../packages/server/src/skills/local-skill-scanner.ts)
+
+默认路径已经固定为：
+
+- `~/.agents/skills`
+
+扫描规则也已经与目标模型一致：
+
+- 一个目录即一个 skill
+- 目录下存在 `SKILL.md` 就会被识别
+- `slug` 直接取目录名
+- `source` 为 `local`
+
+这意味着“全局自定义 skill”不需要再发明新的领域模型；它天然就是现有 `local` source 的一部分，缺的只是创建、浏览和编辑入口。
+
+### Existing Skills Panel
+
+前端现有 `Skills` 面板已经具备：
+
+- 公共 skill 列表
+- built-in 分组
+- 搜索与推荐
+- enable/disable
+- uninstall/update
+- skill 详情页
+
+参考：
+
+- [`packages/web/src/features/workspace/views/shared/skills-panel.tsx`](../../../packages/web/src/features/workspace/views/shared/skills-panel.tsx)
+- [`packages/web/src/features/workspace/actions/use-skills-panel.ts`](../../../packages/web/src/features/workspace/actions/use-skills-panel.ts)
+
+但当前 skill 详情页只有元信息和 target 信息，还不能展示 skill 目录内文件。
+
+### Existing Editor Constraint
+
+当前 editor 及文件命令几乎全部绑定在 `workspaceId + workspace relative path` 上：
+
+- [`packages/web/src/features/workspace/actions/use-open-workspace-file.ts`](../../../packages/web/src/features/workspace/actions/use-open-workspace-file.ts)
+- [`packages/web/src/features/workspace/actions/use-file-actions.ts`](../../../packages/web/src/features/workspace/actions/use-file-actions.ts)
+- [`packages/server/src/commands/file.ts`](../../../packages/server/src/commands/file.ts)
+
+这意味着不能把全局 skill 目录简单塞进 workspace 文件模型里，否则会混淆：
+
+- 文件来源
+- 路径拖拽含义
+- terminal 路径插入
+- 外部变更同步
+- editor tab 的身份
+
+因此复用 editor UI 是对的，但要通过“新增 skill 文件来源”来复用，而不是通过“伪装成 workspace 文件”来复用。
+
+### Existing Drag-and-Drop Semantics
+
+当前路径拖拽语义已经存在：
+
+- [`packages/web/src/lib/workspace-path-drag.ts`](../../../packages/web/src/lib/workspace-path-drag.ts)
+
+并且 agent / terminal 已经能消费“拖入路径字符串”的行为。这证明产品已经接受“路径即操作对象”的交互模型。自定义 skill 只需要扩展一套与之平行的 `skill path drag` 语义，不需要引入新的附件领域。
+
+## User Decisions Captured
+
+- 自定义 skill 是全局共享资源，而不是某个 workspace 私有资源。
+- 创建自定义 skill 后默认不启用。
+- 把 skill 目录拖到 agent 时，只插入目录路径，让 agent 自己读取和修改文件。
+- skill 目录中的文件需要可编辑，但不希望在 `Skills` 面板内再做一套重型编辑器。
+- 目录树需要支持基础文件管理：查看、打开、创建、重命名、删除。
+- 产品应优先复用现有 editor 体验，而不是重复建设编辑能力。
+
+## Approaches Considered
+
+### Option A: 把全局 skill 目录伪装成 workspace 文件
+
+核心思路：
+
+- 把 `~/.agents/skills/<slug>` 作为某个 workspace 下的“特殊目录”
+- 所有读写和打开动作仍走 `file.*` 命令
+
+优点：
+
+- 短期内复用现有文件树与 editor 命令最多
+
+缺点：
+
+- 语义错误；全局资源被绑定到单个 workspace
+- 拖拽和 terminal 路径插入会带上错误的 workspace 身份
+- 多 workspace 打开同一 skill 时状态会变得难以解释
+- 后续外部变更、持久化 tab、冲突检测都会被污染
+
+### Option B: 在 Skills 面板里内嵌一套轻编辑器
+
+核心思路：
+
+- `Skills` 面板自己展示目录树和文本编辑区
+- 不触达现有 editor 主链路
+
+优点：
+
+- 不需要扩展 editor 的文件来源模型
+
+缺点：
+
+- 会产生第二套编辑体验
+- dirty 状态、保存、冲突、快捷键、预览行为都会重复建设
+- 很快会变成一个半成品 editor
+
+### Option C: 复用现有 editor UI，但增加 `skill` 文件来源（推荐）
+
+核心思路：
+
+- `Skills` 面板负责列表、详情、目录树和管理动作
+- 技术上为 editor 增加一种新的文件来源：`skill`
+- skill 文件读写走 `skills.files.*` 命令
+- 打开 skill 文件时进入现有 editor tab
+
+优点：
+
+- 交互最干净
+- skill 仍是全局资源，不会污染 workspace 文件模型
+- editor 能力可以复用到位
+- 后续如果还有别的全局资源，也有统一扩展方向
+
+缺点：
+
+- 需要扩展 editor 的 tab 身份、打开逻辑和读写命令
+
+## Final Choice
+
+采用 Option C。
+
+产品新增一条“全局自定义 skill 创作流”，但不新增第二套编辑器：
+
+- `Skills` 面板新增 `Custom Skills` section
+- 自定义 skill 仍然作为 `source=local` 的 skill 进入公共 skill 库
+- 点击 skill 文件后复用现有 editor UI 打开
+- editor 底层新增 `skill` 文件来源，而不是复用 workspace 文件来源
+- 拖到 agent 时仍保持“插入路径”的轻语义
+
+## Scope
+
+### Included In This Design
+
+- `Custom Skills` section
+- 创建全局自定义 skill
+- skill 详情页中的目录树
+- skill 文件与目录的基础管理
+- 与现有 editor 的联动
+- skill 根目录与单文件拖到 agent
+- 必要的服务端命令与前端状态扩展
+
+### Excluded From This Design
+
+- 现有 `Installed / Built-in / Discover` 主流程重做
+- skill slug 重命名
+- 批量文件操作
+- 拖到 terminal 的专门优化
+- 移动端完整编辑体验优化
+
+## Final UX
+
+### 1. Skills Panel Structure
+
+`Skills` 面板从上到下分为四个 section：
+
+1. `Custom Skills`
+2. `Installed`
+3. `Built-in`
+4. `Discover`
+
+`Custom Skills` 放在最上面，因为它是用户主动创作的入口，而不是被动扫描结果。
+
+section header 结构：
+
+- 标题：`Custom Skills`
+- 计数
+- `Create` 按钮
+- 折叠/展开按钮
+
+可选辅助文案：
+
+- `Global skills stored in ~/.agents/skills`
+
+### 2. Custom Skills List
+
+每个 custom skill 使用与现有 skill 卡片一致的紧凑 row/card 风格，但只展示自定义 skill 关心的信息：
+
+- display name
+- slug
+- description 摘要
+- 启用状态摘要
+
+每项操作：
+
+- 点击主体：进入详情页
+- `Enable/Disable` switch
+- `Delete` button
+
+不在列表态直接显示目录树或文件操作，避免首层过重。
+
+### 3. Create Skill Flow
+
+点击 `Create` 后打开轻量 dialog。
+
+字段：
+
+- `Skill name` 输入框
+- `Slug` 只读预览
+
+说明文案：
+
+- 创建目录：`~/.agents/skills/<slug>/`
+- 自动生成文件：`SKILL.md`
+- 创建后默认不启用
+
+交互规则：
+
+- 名称变化时实时生成 slug
+- 如果 slug 冲突，显示错误并禁止提交
+- 点击 `Create` 后：
+  - 创建目录
+  - 写入默认 `SKILL.md`
+  - 刷新 skill 库
+  - 自动进入新 skill 详情页
+  - 自动打开 `SKILL.md`
+
+默认模板：
+
+```md
+---
+name: my-skill
+description: Custom skill
+---
+
+# My Skill
+```
+
+### 4. Skill Detail View
+
+详情页继续沿用当前 “从列表进入 detail view” 的结构，但增加文件层能力。
+
+顶部展示：
+
+- 返回按钮
+- skill 名称
+- slug
+- source
+- 全局路径
+- 启用状态摘要
+
+顶部动作：
+
+- `Enable/Disable`
+- `New File`
+- `New Folder`
+- `Delete`
+
+主体区域分两部分：
+
+- `Overview`
+  - 描述
+  - library path
+  - target summaries
+- `Files`
+  - 展示该 skill 根目录的目录树
+
+### 5. Files Tree
+
+文件树的目标不是做成完整的资源管理器，而是提供“skill 内文件的最小闭环管理”。
+
+树结构规则：
+
+- 根节点固定为 skill 根目录
+- 默认加载根目录一级内容
+- `SKILL.md` 排在最前
+- 目录可展开/收起
+- 文件点击后直接用现有 editor 打开
+
+每个节点支持：
+
+- 文件
+  - `Open`
+  - `Rename`
+  - `Delete`
+  - `Drag path to agent`
+- 目录
+  - `Expand/Collapse`
+  - `New File`
+  - `New Folder`
+  - `Rename`
+  - `Delete`
+  - 根目录额外支持 `Drag skill path to agent`
+
+不做：
+
+- 多选
+- 复制/粘贴
+- 拖拽重排文件
+
+### 6. Editing Flow
+
+skill 文件编辑完全复用现有 editor：
+
+- 从 `Files` 树点击文件
+- 文件进入现有 editor tab
+- 保存、dirty、冲突检测都沿用 editor 现有行为
+
+`Skills` 面板本身不内嵌文本编辑区。这样用户获得的是一套统一编辑体验，而不是两套相似但不一致的编辑器。
+
+### 7. Drag to Agent
+
+自定义 skill 的拖拽继续使用“路径语义”：
+
+- 拖 skill 根目录到 agent：插入 skill 目录路径
+- 拖单个文件到 agent：插入文件路径
+
+这不是“附加一个 skill 对象”，只是把路径给 agent。agent 后续如何读取或修改文件，仍由会话内行为决定。
+
+推荐文案：
+
+- 根目录：`Drag to agent as path`
+- 文件：`Drag file path to agent`
+
+### 8. Delete Flow
+
+`Delete` 始终是删除整个 skill 文件夹，而不是只删库索引。
+
+删除确认：
+
+- 若未启用：
+  - `Delete this custom skill and all files in its folder?`
+- 若仍有 enabled mounts：
+  - `This skill is enabled for some agents. Deleting it will disable it first, then remove its folder and files.`
+
+执行顺序：
+
+1. unmount enabled targets
+2. 删除 skill 目录
+3. 删除库索引项
+4. 广播 `skillLibraryChanged`
+5. 前端返回列表并刷新
+
+## Interaction Details
+
+### List Page Principles
+
+- 列表只负责“选 skill”和“做轻管理动作”
+- 不在列表页直接暴露文件树
+- 自定义 skill 与其他来源 skill 视觉上保持同一系统，但分组明确
+
+### Detail Page Principles
+
+- 详情页负责“理解一个 skill”
+- 目录树负责“浏览和组织文件”
+- editor 负责“实际编辑”
+
+### Status Language
+
+自定义 skill 继续沿用现有挂载状态体系，不重新发明第二套状态词。
+
+但在列表层面对用户暴露的是简化摘要：
+
+- `Disabled`
+- `Enabled`
+- `Partial`
+- `Error`
+
+## Architecture
+
+### 1. Domain Model
+
+不新增新的 skill 类型。自定义 skill 仍然是现有：
+
+- `SkillLibraryEntry`
+- `source = "local"`
+
+新增的是“这是产品创建的 local skill”的创作链路，而不是新的库模型。
+
+### 2. Server Command Surface
+
+需要新增一组 `skills.custom.*` 命令：
+
+- `skills.custom.create`
+- `skills.custom.delete`
+
+以及一组 skill 文件命令：
+
+- `skills.files.readTree`
+- `skills.files.read`
+- `skills.files.write`
+- `skills.files.create`
+- `skills.files.mkdir`
+- `skills.files.rename`
+- `skills.files.delete`
+
+这些命令都通过 `skillSlug` 定位到 `libraryPath`，而不是通过 `workspaceId` 定位。
+
+### 3. Path Safety
+
+所有 skill 文件操作都必须：
+
+- 以 `skill.libraryPath` 为根目录
+- 禁止路径逃逸
+- 禁止删除或写出 skill 根目录之外的内容
+
+安全模型应与现有 `file-io` 一致，但根目录从 workspace root 换成 skill root。
+
+### 4. Editor Source Model
+
+需要把当前“只支持 workspace 文件”的 editor 打开模型扩展为“支持多来源文件”。
+
+最低要求：
+
+- editor tab 能区分 `workspace file` 与 `skill file`
+- 打开、读取、保存时分发到不同命令
+- tab 标题可显示文件名，副标题或 displayPath 显示 skill 路径
+
+不要求这次把整个 editor 域做成完全通用的资源系统，但不能继续假设“所有文件都属于 workspace”。
+
+### 5. Drag Payload Model
+
+需要新增与 workspace 平行的 drag payload：
+
+- `skillSlug`
+- `path`
+- `kind`
+
+agent 端消费时只读取文本路径，不要求理解 skill 领域对象。
+
+### 6. Refresh Model
+
+skill 文件修改成功后，需要：
+
+- 刷新当前 skill 目录树
+- 保持详情页展开状态
+- 如有必要刷新 `skills.library.list`
+
+skill 创建、删除、启用、禁用继续依赖现有：
+
+- `skills.library.changed` topic
+
+## Data Flow
+
+### Create
+
+1. 用户点击 `Create`
+2. 前端提交 `skills.custom.create`
+3. 服务端生成 slug、校验冲突、创建目录、写入 `SKILL.md`
+4. 服务端写入或刷新库索引
+5. 服务端广播 `skills.library.changed`
+6. 前端刷新列表并进入详情
+7. 前端调用 `skills.files.readTree`
+8. 前端自动打开 `SKILL.md`
+
+### Open Skill File
+
+1. 用户在 skill 文件树点击文件
+2. 前端以 `skill` 来源打开 editor tab
+3. editor 调用 `skills.files.read`
+4. 返回文本或图片内容
+5. editor 进入正常展示与编辑状态
+
+### Save Skill File
+
+1. 用户在 editor 中修改并保存
+2. editor 根据文件来源调用 `skills.files.write`
+3. 服务端做冲突检测并写入
+4. 前端更新 buffer hash
+5. 需要时刷新 skill 树相关节点
+
+### Drag Skill Path to Agent
+
+1. 用户拖根目录或单文件
+2. 前端写入 skill path drag payload 和 `text/plain`
+3. agent drop zone 接收
+4. 会话中插入对应路径文本
+
+## Error Handling
+
+### Create Errors
+
+- 名称为空
+- slug 冲突
+- 无法写入 `~/.agents/skills`
+- 默认模板写入失败
+
+前端在 create dialog 中就地展示错误，不跳页。
+
+### File Operation Errors
+
+- 路径逃逸
+- 文件不存在
+- 目标已存在
+- 冲突写入
+- 非法重命名
+
+错误处理原则：
+
+- 文件树操作错误在当前上下文展示
+- editor 写入冲突继续沿用现有 editor 行为
+- 删除失败不做静默吞掉
+
+### External Mutation
+
+用户可能直接在磁盘上改 `~/.agents/skills/<slug>`。
+
+v1 不要求做实时 watch，但要求：
+
+- 面板 refresh 后能看到外部变化
+- 如果打开中的 skill 文件保存时发现内容已变，给出冲突反馈
+
+## Testing Strategy
+
+### Server
+
+- `skills.custom.create`
+  - 创建成功
+  - slug 冲突
+  - 非法名称归一化
+  - 模板文件生成
+- `skills.files.*`
+  - readTree/read/write/create/mkdir/rename/delete
+  - 路径逃逸保护
+  - 冲突写入
+  - 根目录约束
+
+### Web
+
+- `Custom Skills` section 渲染与空状态
+- create dialog 流程
+- 创建后自动进入详情并打开 `SKILL.md`
+- 文件树展开、打开、创建、重命名、删除
+- skill 文件以 `skill` 来源进入 editor
+- enable/disable 与 delete 的交互不回归
+- skill path drag payload 正确生成并可被 agent drop 消费
+
+### Integration
+
+- 创建 custom skill 后立刻出现在 `skills.library.list`
+- 打开并保存 `SKILL.md` 后文件内容落盘
+- 删除 skill 后目录和索引都消失
+
+## Risks
+
+### Editor Assumptions Are Workspace-Centric
+
+当前 editor、tab、open file state 和保存路径都假设文件来自 workspace。这个假设如果只改一半，会导致：
+
+- tab 身份冲突
+- 保存分发错误
+- display path 混乱
+
+因此实现时不能只加一两个 `if`；至少要把“文件来源”作为 editor 一等概念引入。
+
+### Deleting Mounted Local Skills Must Stay Coherent
+
+当前 `skills.uninstall` 已经会删除 `libraryPath`。新增 custom skill 创作链路后，删除动作必须继续与 mount/unmount 关系保持一致，不能出现：
+
+- 目录删了但 mount relation 还在
+- 索引删了但详情页还保留旧状态
+
+### Drag Model Drift
+
+如果 skill 路径拖拽和 workspace 路径拖拽最终行为不同，用户会困惑。因此两者必须都坚持“拖入即插入路径文本”的一致心智。
+
+## Open Questions Resolved
+
+- 自定义 skill 是否全局共享：是。
+- 创建后是否默认启用：否。
+- 拖到 agent 是否作为特殊 skill 附件：否，只插入路径。
+- 是否在技能面板内重做编辑器：否，复用现有 editor。
+- 文件树是否需要基础文件管理：是，但只做轻量操作。
+
+## Summary
+
+这次设计不是给 `Skills` 面板再拼一个“迷你 IDE”，也不是把全局 skill 强行塞进 workspace 文件模型，而是补上一条完整、轻量、语义正确的自定义 skill 创作流：
+
+- 在 `Skills` 面板里创建全局 custom skill
+- 在详情页里管理它的目录和文件
+- 在现有 editor 里编辑文件
+- 在 agent 中通过拖拽路径把它交给会话处理
+
+这样既能满足“可编辑”的诉求，又不会让 `Skills` 面板变成第二套沉重的工作台。
diff --git a/docs/superpowers/specs/2026-06-20-mobile-agent-provider-compact-design.md b/docs/superpowers/specs/2026-06-20-mobile-agent-provider-compact-design.md
new file mode 100644
index 000000000..15d0e92ed
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-20-mobile-agent-provider-compact-design.md
@@ -0,0 +1,36 @@
+# Mobile Agent Provider Compact Design
+
+## Goal
+
+Make the mobile `Select Agent` provider list more compact by removing the redundant middle description line for launch-ready providers while preserving install and error guidance when it is needed.
+
+## Scope
+
+- Mobile provider list in `MobileAgentSheet` create mode only
+- Do not change desktop behavior
+- Do not change the session-switching mode layout
+
+## Behavior
+
+### Launch-ready providers
+
+- Keep the provider name as the primary label
+- Keep the status/meta line such as `Start new session` or `Starting`
+- Remove the redundant default description line such as `Start Codex session`
+
+### Providers needing guidance
+
+- Keep manual install or error guidance in the description slot
+- Keep the diagnostics trailing action when guidance is present
+
+## Styling
+
+- Scope density changes to the mobile agent sheet only
+- Tighten row padding and copy spacing slightly so the provider list reads denser without affecting other mobile command sheets
+- Keep the monogram icon treatment and provider theme colors unchanged
+
+## Testing
+
+- Component test: launch-ready providers no longer render the default `Start {provider} session` description
+- Component test: guidance text still appears when a provider needs help
+- Theme test: agent-sheet-specific compact spacing tokens are present
diff --git a/docs/superpowers/specs/2026-06-20-mobile-agent-provider-monogram-design.md b/docs/superpowers/specs/2026-06-20-mobile-agent-provider-monogram-design.md
new file mode 100644
index 000000000..4eb07053c
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-20-mobile-agent-provider-monogram-design.md
@@ -0,0 +1,260 @@
+# Mobile Agent Provider Monogram Design
+
+Date: 2026-06-20
+Status: Draft
+Owner: codex
+
+## Problem
+
+移动端 `Select Agent` 页面里的 provider 图标样式现在不统一：
+
+- `Claude` 和 `Codex` 使用语义图形图标
+- `Gemini`、`Cursor`、`OpenCode` 使用两位大写字母 monogram
+
+这会让同一列表里的视觉语言不一致。用户希望这个页面统一为：
+
+- 所有 provider 都使用“前两个字母大写”作为 icon
+- icon 颜色保持各自 provider 的主题色
+- 只调整移动端页面，不改 PC 端现有表现
+
+## Goals
+
+- 统一移动端 `Select Agent` 页面中全部 provider 的 icon 形式。
+- 所有 provider 使用两位大写字母 monogram。
+- monogram 的颜色和背景保持 provider 主题色风格。
+- 仅修改移动端入口，不影响桌面端或其他 Agent 入口。
+- 保持现有列表文案、启动逻辑、禁用态、诊断入口不变。
+
+## Non-Goals
+
+- 不修改桌面端 draft launcher 或其他 PC 端 provider 选择 UI。
+- 不引入新的 provider 图形图标。
+- 不重做 provider 卡片布局、间距或交互逻辑。
+- 不扩展全局 theme semantic 体系到所有 provider。
+
+## Current Context
+
+移动端 provider 选择页位于：
+
+- [`packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.tsx`](../../../packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.tsx)
+
+当前逻辑分为两类：
+
+- `claude` / `codex` 命中 `PROVIDER_ICON_SEMANTICS`，渲染 `ThemedIcon`
+- 其他 provider 回退为 `.agent-provider-card-monogram` 文本样式
+
+这意味着当前列表同时混用了“图形 icon”和“文字 monogram”两套表现。
+
+移动端列表项公共结构来自：
+
+- [`packages/web/src/features/mobile-select/components/mobile-select-sheet.tsx`](../../../packages/web/src/features/mobile-select/components/mobile-select-sheet.tsx)
+- [`packages/web/src/styles/components.css`](../../../packages/web/src/styles/components.css)
+
+其中 `.mobile-select-sheet__item-icon` 只负责图标容器排版，不区分 provider 身份。因此如果要给 provider monogram 加主题色，最稳妥的方式是在 `mobile-agent-sheet.tsx` 中输出带 provider 修饰类的专用节点，而不是改动整个移动端选择器的通用 icon 行为。
+
+## User Decisions Captured
+
+- 仅处理移动端页面。
+- PC 端当前效果正常，不应改动。
+- 所有 provider 统一使用前两个字母大写。
+- icon 使用各自 provider 的主题色。
+
+## Approaches Considered
+
+### Option A: 仅在移动端统一为 provider monogram，并按 provider id 加主题色（推荐）
+
+核心思路：
+
+- 去掉移动端 `claude` / `codex` 的语义图形 icon 分支
+- 所有 provider 都走统一的 monogram 渲染
+- 在移动端 provider icon 节点上附加 `provider id` 修饰类，提供主题色
+
+优点：
+
+- 改动范围最小
+- 完全符合用户要求
+- 只影响移动端页面，不会波及 PC 端
+- 不需要扩展全局 icon semantic
+
+缺点：
+
+- provider 主题色映射需要在移动端页或其配套样式中维护一份轻量定义
+
+### Option B: 提取共享 provider monogram 组件，移动端和桌面端共用
+
+优点：
+
+- 后续复用性更强
+
+缺点：
+
+- 会触碰桌面端共享逻辑
+- 即使桌面端 UI 最终不变，也会扩大这次改动范围
+- 不符合“不要动 PC 端”的边界
+
+### Option C: 扩展全局 icon semantic，让所有 provider 继续走 `ThemedIcon`
+
+优点：
+
+- 主题系统更完整
+
+缺点：
+
+- 需求目标是“统一为前两个字母大写”，不是增加更多图形 icon
+- 需要修改 theme semantic 和 registry，范围偏大
+- 对当前问题来说属于过度设计
+
+## Final Choice
+
+采用 Option A。
+
+这次改动将把移动端 `Select Agent` 页面中的所有 provider icon 统一为两位大写 monogram，并通过 provider-specific 样式让颜色保持主题化。PC 端和其他入口不做任何行为或样式调整。
+
+## Final UX
+
+在移动端 `Select Agent` 页面中：
+
+- `Claude` 显示 `CL`
+- `Codex` 显示 `CO`
+- `Gemini` 显示 `GE`
+- `Cursor` 显示 `CU`
+- `OpenCode` 显示 `OP`
+
+icon 视觉规则：
+
+- 使用一致的字母 icon 尺寸、圆角、字重和对齐方式
+- 每个 provider 通过主题色区分前景色、背景色和必要的边框混色
+- 列表中的文本、描述、meta、诊断按钮、点击行为保持现状
+
+## Implementation Design
+
+### Rendering
+
+`mobile-agent-sheet.tsx` 中的 provider icon 渲染将改为单一路径：
+
+- 删除 `PROVIDER_ICON_SEMANTICS`
+- 新增 provider monogram 计算函数
+- 新增 provider icon class 计算函数
+- 对所有 provider 输出统一的 monogram 节点
+
+建议渲染结构：
+
+```tsx
+<span
+  aria-hidden="true"
+  className={`mobile-agent-provider-icon mobile-agent-provider-icon--${provider.id}`}
+>
+  <span className="mobile-agent-provider-icon__label">CL</span>
+</span>
+```
+
+这个结构只在移动端 agent sheet 中使用，不进入通用 `MobileSelectSheet`。
+
+### Monogram Rules
+
+monogram 文案取 provider label 的前两个可见字符并转大写。对当前已知 provider，结果应为：
+
+- `Claude` -> `CL`
+- `Codex` -> `CO`
+- `Gemini` -> `GE`
+- `Cursor` -> `CU`
+- `OpenCode` -> `OP`
+
+这里应基于当前显示 label 生成，而不是对 provider id 写死文案映射；这样后续 provider 扩展仍可自动回退为“两位字母”。
+
+### Styling
+
+在 [`packages/web/src/styles/components.css`](../../../packages/web/src/styles/components.css) 中增加仅供移动端页面使用的专用类：
+
+- `.mobile-agent-provider-icon`
+- `.mobile-agent-provider-icon__label`
+- `.mobile-agent-provider-icon--claude`
+- `.mobile-agent-provider-icon--codex`
+- `.mobile-agent-provider-icon--gemini`
+- `.mobile-agent-provider-icon--cursor`
+- `.mobile-agent-provider-icon--opencode`
+
+基础样式负责：
+
+- 固定宽高
+- 居中
+- 圆角
+- monospace / semibold 视觉
+- 字号与现有移动端行高匹配
+
+provider 修饰类负责：
+
+- `color`
+- `background`
+- 需要时的 `border`
+
+这些颜色不应通过修改 `.mobile-select-sheet__item-icon` 全局规则实现，以免影响其他移动端选择器。
+
+### Data Flow
+
+现有 provider 列表、runtime state、busy 状态、诊断入口都保持不变。改动只发生在 `providerSections` 中的 `icon` 生成逻辑。
+
+不会改变：
+
+- `useProviderLauncher` 返回的数据
+- `launch(id)` 调用
+- `guideMessage` 文案
+- `busy` / `disabled` 判定
+
+### Error Handling
+
+这个变更没有新增异步流程。主要需要保证：
+
+- provider label 为空时仍能回退到 provider id
+- monogram 生成函数不会输出空字符串
+
+回退策略：
+
+- 先取 `badge`
+- 再取 `displayName`
+- 再取 `id`
+- 取值后裁剪前两个字符并转大写
+
+## Testing
+
+需要更新和补充的验证重点：
+
+### Unit / Component Tests
+
+更新：
+
+- [`packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx`](../../../packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx)
+
+覆盖点：
+
+- `Claude` 和 `Codex` 不再渲染 `data-icon-semantic="agent.provider.*"`
+- 所有 provider 都渲染两位大写字母
+- `Gemini` 点击仍然触发 `launch("gemini")`
+- provider 缺失 runtime state 时仍然跳过，不影响渲染稳定性
+
+如样式测试已覆盖移动端 command 列表 icon 表现，可按需补充：
+
+- 仅验证新类存在，不对具体颜色值做过度脆弱断言
+
+### Manual Verification
+
+手工检查移动端 `Select Agent` 页面：
+
+- 所有 provider icon 形式一致
+- `Claude` / `Codex` 颜色仍有清晰区分
+- `Gemini` / `Cursor` / `OpenCode` 颜色符合主题化预期
+- 长文案、禁用态、诊断按钮未发生布局回归
+
+## Risks
+
+- provider 主题色如果直接硬编码在样式中，后续新增 provider 需要补对应修饰类。
+- 不同 theme 下如果某个 provider 色对比度不足，可能需要轻调背景混色比例。
+- 基于显示 label 截取前两个字符时，若未来某个 provider 使用非拉丁前缀，monogram 规则可能需要单独定义。
+
+## Acceptance Criteria
+
+- 移动端 `Select Agent` 页中所有 provider 都显示两位大写字母 icon。
+- 每个 provider 的 icon 都有各自主题色，而不是统一颜色。
+- `Claude` 和 `Codex` 不再显示图形 icon。
+- 仅移动端页面发生变化，PC 端 UI 不变。
+- 现有 provider 启动和诊断行为保持不变。
diff --git a/docs/superpowers/specs/2026-06-20-mobile-workspace-drawer-design.md b/docs/superpowers/specs/2026-06-20-mobile-workspace-drawer-design.md
new file mode 100644
index 000000000..23b6045c4
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-20-mobile-workspace-drawer-design.md
@@ -0,0 +1,201 @@
+# Mobile Workspace Drawer Design
+
+> Status: Draft
+> Date: 2026-06-20
+> Scope: `packages/web` mobile workspace shell, mobile topbar, mobile workspace drawer, mobile empty-state entry flow
+
+## Goal
+
+Rework the mobile workspace shell so the bottom `Agent / 文件 / 终端` dock is removed, file and terminal entry points move into the topbar, and agent switching is folded into the workspace drawer as a flat tree rooted at the active workspace.
+
+The goal is not to redesign the mobile file sheet, terminal sheet, or active agent surface. The goal is to simplify mobile navigation and make the workspace-to-agent hierarchy explicit.
+
+## Final Direction
+
+Use a flatter mobile shell with three navigation regions:
+
+1. a lighter topbar with left-aligned title
+2. a workspace drawer that owns workspace and agent switching
+3. the main content area showing only the active agent session
+
+Key decisions:
+
+- remove the bottom mobile dock entirely
+- keep the top-left workspace/drawer affordance
+- move `文件` and `终端` entry points to the top-right of the mobile topbar
+- keep files and terminal on their existing sheet flows rather than redesigning those surfaces
+- change the mobile workspace drawer into a flat tree where only the active workspace expands
+- render agent rows under the active workspace using the existing mobile agent information density, including provider and runtime state
+- use a flatter visual language with weaker card treatment, tighter type, and lower roundness
+
+## In Scope
+
+- mobile topbar layout and action placement
+- removal of the bottom mobile dock from the workspace shell
+- mobile workspace drawer information architecture and interaction model
+- agent switching from the drawer
+- placing `+ 新建 Agent` inside the active workspace subtree
+- mobile empty-state entry changes so agent creation is consistent with the new drawer model
+- mobile tests covering the new navigation model
+
+## Out Of Scope
+
+- redesigning the internal file explorer, file detail, or terminal sheet content
+- redesigning the active `SessionCard` content for the current agent
+- changing desktop workspace behavior
+- changing provider launch logic beyond where the entry point lives
+- redesigning global `/more` navigation
+
+## Existing Context
+
+The current mobile workspace shell is organized around:
+
+- a topbar with workspace switcher, `/more`, and fullscreen actions
+- a main area that shows the active agent session or an empty state
+- a bottom dock with `Agent`, `文件`, and `终端`
+- a separate mobile agent sheet used for session switching and session creation
+- a workspace drawer used only for workspace switching
+
+This structure creates a split navigation model:
+
+- workspace switching lives in one place
+- agent switching lives in another place
+- files and terminal live in a third place
+
+The approved redesign collapses those concerns into a clearer hierarchy: workspace and agent switching share the drawer, while files and terminal become topbar actions.
+
+## Navigation Model
+
+### Topbar
+
+The mobile topbar keeps the left-side workspace trigger but changes its visual hierarchy:
+
+- title is left-aligned
+- title sizing and weight should be lighter than the approved mockup's first pass and closer to existing product UI density
+- the right side shows two lighter action triggers for `文件` and `终端`
+
+Topbar behavior rules:
+
+- tapping the left workspace area opens or closes the workspace drawer
+- tapping `文件` opens the existing mobile files sheet flow
+- tapping `终端` opens the existing mobile terminal sheet flow
+- opening files or terminal should close the drawer and any agent-selection overlay state
+
+The previous `/more` action is not part of the approved topbar layout for this screen. Fullscreen behavior is also not part of the approved topbar action set for this flow.
+
+### Main Content Area
+
+The main area continues to render only the active mobile agent session.
+
+Rules:
+
+- do not introduce an inline agent list into the main content area
+- do not turn the main area into a split workspace-and-agent layout
+- keep the current active session presentation path centered on the existing `SessionCard`
+
+If there is an active session, the shell should behave as it does today aside from the navigation changes around it.
+
+### Workspace Drawer
+
+The drawer becomes the primary mobile navigation surface for workspaces and agents.
+
+Drawer hierarchy rules:
+
+- show all workspaces in a single list
+- only the active workspace expands
+- inactive workspaces remain collapsed to a single row
+- the active workspace row expands inline to show child agent rows
+- child agent rows appear visually subordinate through indentation, smaller type, and lighter separators rather than through heavy nested cards
+
+Agent row behavior rules:
+
+- each row shows the agent title as the primary line
+- each row shows provider and session state as the secondary line
+- the secondary line should follow the existing mobile agent panel pattern, such as `CODEX · IDLE`
+- selected agent state should be visible but restrained; avoid heavy card fills or oversized pills
+- tapping an agent row immediately switches the active agent session
+- after switching, the drawer closes and the main content updates to that session
+
+Workspace row behavior rules:
+
+- the active workspace row acts as the expanded section header and should not trigger a workspace switch or close the drawer when tapped
+- tapping an inactive workspace switches to that workspace and closes the drawer
+- after switching workspace, the newly active workspace becomes the only expanded node
+
+### New Agent Entry
+
+`+ 新建 Agent` moves into the active workspace subtree.
+
+Rules:
+
+- render it after the active workspace's agent rows
+- it should read as part of that workspace's hierarchy, not as a global floating action
+- tapping it should enter the existing mobile agent creation flow
+- the creation flow continues to use the current provider-selection sheet implementation
+
+## Empty State
+
+The mobile no-session state should stop teaching users to use a separate agent dock entry, because that entry no longer exists.
+
+Approved empty-state rules:
+
+- keep the main area empty state lightweight
+- remove copy that depends on a bottom `Agent` entry
+- the primary action should still let the user create a session quickly
+- that action should conceptually align with the new drawer tree model rather than teaching an obsolete navigation pattern
+
+It is acceptable for the empty state CTA to open the existing create-agent flow directly, as long as the copy no longer describes a removed bottom dock.
+
+## Visual Direction
+
+The approved visual direction is flatter and more product-like than the first mockup draft.
+
+Required styling characteristics:
+
+- reduce headline size and weight in the mobile topbar and drawer rows
+- weaken card treatment or remove it where plain rows and separators are sufficient
+- reduce roundness compared with the current mockup direction
+- prefer borders, dividers, indentation, and subtle fills over stacked rounded cards
+- keep selected-agent emphasis visible but restrained
+- keep agent metadata legible without making the drawer visually noisy
+
+This change should preserve the product's current mobile IDE feel rather than drifting into a marketing-style visual hierarchy.
+
+## Implementation Constraints
+
+The approved implementation should reuse existing mobile workspace state where possible.
+
+Preferred reuse points:
+
+- `useWorkspaceScreenModel` for workspace list, mobile agent sessions, current mobile session selection, and mobile sheet opening
+- existing `MobileFilesSheet` and terminal-sheet presentation
+- existing session selection and session creation behavior
+
+Avoid introducing a parallel cross-feature data model just for the drawer tree. The drawer should derive its hierarchy from the current active workspace plus existing session data.
+
+A local expanded-workspace rule is sufficient because the approved interaction only allows the active workspace to expand.
+
+## Testing
+
+The implementation should add or update tests for the following behaviors:
+
+- mobile workspace topbar renders `文件` and `终端` actions instead of the removed bottom dock model
+- the bottom mobile dock is no longer rendered in the workspace shell
+- the workspace drawer shows all workspaces but expands only the active workspace
+- expanded active workspace rows include agent items
+- agent items render both title and `provider · state` metadata
+- selecting an agent item switches the active session and closes the drawer
+- selecting an inactive workspace switches workspace and preserves the rule that only the active workspace expands
+- the empty state no longer references the removed bottom `Agent` entry
+- the empty state still provides a working path to create a session
+
+## Risks
+
+The main risk is replacing a three-entry bottom navigation model with a drawer-plus-topbar model without preserving fast access or clear orientation.
+
+The design addresses that risk by:
+
+- keeping files and terminal as single-tap topbar actions
+- limiting drawer expansion to one workspace at a time
+- preserving current session information density in agent rows
+- keeping the active agent surface unchanged so the navigation refactor does not also rewrite the work surface
diff --git a/docs/superpowers/specs/2026-06-20-skill-source-unification-design.md b/docs/superpowers/specs/2026-06-20-skill-source-unification-design.md
new file mode 100644
index 000000000..fa0ec75f0
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-20-skill-source-unification-design.md
@@ -0,0 +1,572 @@
+Date: 2026-06-20
+Status: Draft
+Owner: codex
+
+## Problem
+
+当前 skill library 的主分类字段是 `source`，取值为：
+
+- `builtin`
+- `skillhub`
+- `local`
+
+这个模型已经不足以表达产品当前的实际需求。
+
+现状里有三类用户可见 skill：
+
+1. Coder Studio 内置 skill
+2. 通过 Skill Hub 或第三方方式安装的 skill
+3. 由 Coder Studio 在产品内创建并管理的自定义 skill
+
+但当前模型把第 2 类和第 3 类都可能落到“本地目录 + `local`”这一类里，导致：
+
+- 第三方安装或手工放入 `~/.agents/skills` 的 skill 会被误认为 `Custom Skills`
+- custom 专属能力，例如文件树、文件编辑、删除确认，也会错误暴露给第三方本地 skill
+- custom skill 启用后会被 mount 到 agent skill 目录中，如果扫描器再次扫描该目录，会把 mirror 再次统计成一条已安装 skill
+- builtin skill 也有同样的问题：builtin canonical 本体在 Coder Studio 自己的目录里，但 mount 后的 mirror 如果出现在扫描目录中，也可能被重新扫成一条本地 skill
+
+当前代码已经暴露出这个问题：
+
+- 本地扫描把 `~/.agents/skills` 下所有 skill 都标成 `source: "local"`
+- 前端把 `source === "local"` 直接归入 `Custom Skills`
+- builtin stale cleanup 已经包含一段“识别 local symlink 实际指向 builtin canonical”的补救逻辑，说明 mirror 被误扫的问题已经真实存在
+
+问题的根源不是某一个判断条件写错，而是 skill 分类语义本身不清晰，并且 canonical skill 与 mounted mirror 缺少统一边界。
+
+## Goals
+
+- 用一个统一的主字段表达 skill 的产品分类，避免“来源”和“管理方式”混用。
+- 给 custom skill 一个独立 canonical 根目录，不与第三方本地 skill 混放。
+- 明确 builtin 和 custom 的 canonical 本体与 mounted mirror 的区别。
+- 确保 mounted mirror 不会被再次扫描成新的 library entry。
+- 让 custom 专属能力只对 custom 生效。
+- 保持 builtin、installed、custom 在 UI 中的分组和行为一致、可预测。
+
+## Non-Goals
+
+- 这次不重做整个 Skills 面板视觉结构。
+- 这次不引入 workspace 级 custom skill。
+- 这次不做旧 custom skill 自动迁移；用户已确认当前没有需要迁移的数据。
+- 这次不改变 provider 的挂载目录策略；只改变 library 分类和扫描逻辑。
+- 这次不把 external local skill 变成可编辑资源。
+
+## Current Context
+
+### Current Library Classification
+
+当前核心类型定义：
+
+- `packages/core/src/domain/skill-management.ts`
+
+其中 `SkillLibraryEntry.source` 只有三种：
+
+- `builtin`
+- `skillhub`
+- `local`
+
+当前 `local` 被同时用于：
+
+- 扫描 `~/.agents/skills` 得到的第三方或手工 skill
+- 由 `skills.custom.create` 创建的 custom skill
+
+因此前端和服务端一旦使用 `source === "local"` 作为“custom”的代理条件，就必然产生误判。
+
+### Current Canonical Roots
+
+当前 builtin canonical 目录已经独立存在：
+
+- `join(stateRoot, "state", "skills", "builtin", <slug>)`
+
+当前 Skill Hub 安装目录也独立存在：
+
+- `join(stateRoot, "state", "skills", "library", <slug>)`
+
+当前 custom skill 没有自己的 canonical 根目录，仍然创建在：
+
+- `~/.agents/skills/<slug>`
+
+这使得 custom 与 external local skill 在物理上混放。
+
+### Current Mount Behavior
+
+skill mount 逻辑统一通过 `SkillMountManager` 执行：
+
+- canonical library entry 提供 `libraryPath`
+- mount 目标使用 provider 的 `skillMountDirectories[0]`
+- 默认优先创建 symlink
+- symlink 失败时回退到 copy
+
+这意味着：
+
+- builtin/custom canonical 本体和 mounted mirror 是两个不同概念
+- mirror 可能是 symlink，也可能是 copy
+- 不能只通过“是否为 symlink”判断一个条目是不是 mirror
+
+### Current Builtin Cleanup
+
+builtin stale cleanup 已包含识别“扫描出来的 local entry 实际是指向 builtin canonical 的 symlink artifact”的逻辑。
+
+这说明：
+
+- builtin mirror 被扫描为本地 skill 的情况已经出现
+- 当前方案主要靠事后清理解决，而不是从扫描阶段排除 mirror
+
+## User Decisions Captured
+
+- custom skill 使用独立目录，不与其他 skill 混放。
+- custom skill 根目录使用 Coder Studio 的 state root 派生目录。
+- 当前没有历史 custom skill 需要迁移，可以不处理自动搬迁。
+- 主分类应统一成一个字段，不希望用多个交叉字段决定主行为。
+- custom skill 启用后同步到 agent skill 目录，但不能因此在 installed 列表里再显示一遍。
+- builtin 也必须避免同类 mirror 重复统计问题。
+
+## Approaches Considered
+
+### Option A: 保持现有 `source`，只增加 `isCustom`
+
+优点：
+
+- 改动面看似较小
+
+缺点：
+
+- 主分类仍然分裂为多个字段
+- `source` 继续承担不完整语义
+- 后续代码仍容易继续把 `source === "local"` 当作 custom 代理
+- builtin/custom mirror 去重语义仍不统一
+
+### Option B: 保持目录不变，只重命名 `source`
+
+优点：
+
+- 可减少部分 UI 误判
+
+缺点：
+
+- custom 仍与 external local skill 混放
+- mirror 问题依旧存在
+- 物理模型和逻辑模型不一致
+
+### Option C: 统一主字段 + custom 独立 canonical 目录 + mirror 扫描排除
+
+优点：
+
+- 主分类语义清晰
+- custom、installed、builtin 三类边界明确
+- builtin 和 custom 的 mirror 问题能用同一套机制解决
+- UI、命令、文件权限都可以收口到统一判断
+
+缺点：
+
+- 需要修改 core 类型、扫描逻辑、repo merge、部分前端分组和命令判定
+
+## Final Choice
+
+采用 Option C。
+
+## Final Model
+
+### Unified Classification Field
+
+`SkillLibraryEntry.source` 改为以下统一主分类：
+
+- `builtin`
+- `installed`
+- `custom`
+
+含义定义如下：
+
+- `builtin`
+  - 由 Coder Studio 内置并 materialize 的 canonical skill
+- `installed`
+  - 非 builtin、非 custom 的所有已安装 skill
+  - 包含 Skill Hub 安装项
+  - 包含扫描到的 external local skill
+- `custom`
+  - 由 Coder Studio 在产品内创建和管理的 custom skill
+
+这个字段是产品主分类字段，以下行为只依赖它：
+
+- Skills 面板分组
+- 是否显示 custom 文件树和文件管理动作
+- 删除/卸载语义
+- 自定义 skill API 与命令访问权限
+
+### Optional Origin Metadata
+
+如果需要保留 installed skill 的细分来源，可增加可选元数据：
+
+- `origin?: "builtin" | "skillhub" | "filesystem"`
+
+使用规则：
+
+- `source` 决定主分组和主行为
+- `origin` 只用于辅助展示或能力判断
+
+例如：
+
+- `source === "installed" && origin === "skillhub"` 才允许版本检查与更新
+- `source === "installed" && origin === "filesystem"` 只显示为本地已安装 skill，不显示更新
+
+`origin` 不是主分类字段，不参与 `Custom Skills / Installed / Built-in` 分组。
+
+## Canonical Directories
+
+### Builtin Canonical Root
+
+保持现有路径：
+
+- `join(stateRoot, "state", "skills", "builtin")`
+
+每个 builtin skill 的 canonical 路径为：
+
+- `join(builtinRoot, slug)`
+
+### Installed Canonical Root
+
+Skill Hub 安装项保持现有 managed library 根目录：
+
+- `join(stateRoot, "state", "skills", "library")`
+
+这类条目写入：
+
+- `source: "installed"`
+- `origin: "skillhub"`
+
+### Custom Canonical Root
+
+新增 custom canonical 根目录：
+
+- `join(stateRoot, "state", "skills", "custom")`
+
+每个 custom skill 的 canonical 路径为：
+
+- `join(customRoot, slug)`
+
+`skills.custom.create` 只能在这里创建 custom skill，不再写入 `~/.agents/skills`。
+
+### External Local Scan Roots
+
+外部本地 skill 继续扫描 agent 生态目录，例如：
+
+- `~/.agents/skills`
+
+扫描得到的条目写入：
+
+- `source: "installed"`
+- `origin: "filesystem"`
+
+## Mounted Mirror Model
+
+### Canonical vs Mirror
+
+对 builtin 和 custom，必须明确区分：
+
+- canonical skill
+  - library 中唯一真实条目
+  - 拥有自己的 canonical 根目录
+- mounted mirror
+  - 为了让 provider/agent 读取 skill 而同步到 provider skill 目录中的镜像
+  - 可能是 symlink，也可能是 copy
+  - 不是新的 library entry
+
+mirror 绝不能被再次统计为 installed skill。
+
+### Managed Mirror Marker
+
+为所有 Coder Studio 管理的 canonical skill 写一个隐藏 marker 文件：
+
+- `.coder-studio-skill.json`
+
+marker 最少包含：
+
+- `version: 1`
+- `managedBy: "coder-studio"`
+- `source: "builtin" | "custom"`
+- `slug: string`
+
+要求：
+
+- builtin canonical 写入 marker
+- custom canonical 写入 marker
+- mount 为 symlink 时，marker 会自然透出
+- mount 为 copy 时，marker 也必须被复制过去
+
+### Mirror Exclusion Rule
+
+扫描 external local roots 时，如果发现 skill 目录包含 marker 且：
+
+- `managedBy === "coder-studio"`
+
+则该目录被视为 mounted mirror，必须直接跳过，不生成 library entry。
+
+这个排除规则统一适用于：
+
+- builtin mirror
+- custom mirror
+
+不能只对 custom 生效。
+
+### Slug Fallback Guard
+
+除 marker 外，再增加 slug 级兜底：
+
+- 如果某个 slug 已在 builtin canonical 或 custom canonical 中存在
+- 扫描 external local roots 时发现同 slug 目录
+- 且该目录是从 Coder Studio canonical mount 出来的 mirror
+
+则必须跳过
+
+marker 是主判定方式，slug 兜底是为兼容 copy/symlink 异常或历史状态。
+
+## Server Behavior Changes
+
+### Local Scanner
+
+本地扫描器需要拆分语义：
+
+- 扫描 custom canonical root
+- 扫描 external installed roots
+
+不再使用单一“所有本地目录统一映射为 `local`”的模型。
+
+扫描输出：
+
+- custom canonical -> `source: "custom"`, `origin: "filesystem"`
+- external local -> `source: "installed"`, `origin: "filesystem"`
+
+扫描 external local roots 时必须先执行 mirror exclusion。
+
+### Custom Skill Creation
+
+`skills.custom.create`：
+
+- 根目录改为 custom canonical root
+- 写入 `SKILL.md`
+- 写入 `.coder-studio-skill.json`
+- 返回 library entry：
+  - `source: "custom"`
+  - `origin: "filesystem"`
+
+创建前必须做 slug 全局冲突检查。
+
+### Skill Hub Install
+
+Skill Hub 安装完成后写入 library entry：
+
+- `source: "installed"`
+- `origin: "skillhub"`
+
+### Builtin Materialization
+
+builtin materialize 输出 entry：
+
+- `source: "builtin"`
+- `origin: "builtin"`
+
+同时 builtin canonical 目录也应写入 marker。
+
+### Skill Library Repo Merge
+
+repo merge 规则需要显式化，不能再依赖“`source === local` 就覆盖”的旧逻辑。
+
+推荐优先级：
+
+1. builtin canonical
+2. custom canonical
+3. managed installed entries
+4. external local scanned installed entries
+
+规则：
+
+- builtin 不被 external scan 覆盖
+- custom 不被 external scan 覆盖
+- managed installed 不被 external filesystem scan 覆盖
+- external local scanned item 只在 slug 不冲突时补充进入库
+- 已存在的 persisted entry 若拥有更高优先级，扫描结果只能刷新有限的派生字段，不能整体降级覆盖
+
+### File Management Commands
+
+以下命令只允许 `source === "custom"`：
+
+- `skills.files.readTree`
+- `skills.files.read`
+- `skills.files.write`
+- `skills.files.create`
+- `skills.files.mkdir`
+- `skills.files.rename`
+- `skills.files.delete`
+- `/api/skill-file`
+
+如果是 `installed` 或 `builtin`，应返回明确错误。
+
+### Delete / Uninstall Semantics
+
+- `builtin`
+  - 不可卸载
+- `installed`
+  - 执行 uninstall 语义
+- `custom`
+  - 执行 delete 语义
+
+`custom` delete 流程：
+
+1. 找到所有 mount relations
+2. unmount 所有 enabled mirror
+3. 删除 mount repo relations
+4. 删除 custom canonical 目录
+5. 删除 library entry
+6. 广播 library changed
+
+对于 `installed + origin: "filesystem"` 的 external local skill：
+
+- 不应从 Coder Studio 内直接删除第三方目录
+- 推荐只支持 unmount，不支持删除底层目录
+
+如果保留 “uninstall” 按钮，应明确它只解除 Coder Studio 管理关系，不删除源目录。更保守的做法是不展示删除/卸载目录动作。
+
+## Frontend Behavior Changes
+
+### Section Grouping
+
+Skills panel 分组统一改为：
+
+1. `Custom Skills`
+   - `source === "custom"`
+2. `Installed`
+   - `source === "installed"`
+3. `Built-in`
+   - `source === "builtin"`
+4. `Discover`
+
+### Detail View
+
+detail view 行为：
+
+- `custom`
+  - 显示文件树
+  - 显示新建文件/文件夹
+  - 支持重命名、删除、拖拽路径
+- `installed`
+  - 不显示 custom 文件管理动作
+- `builtin`
+  - 不显示 custom 文件管理动作
+
+### Labels
+
+若存在 `origin`：
+
+- `installed + skillhub` 可显示 `Skill Hub`
+- `installed + filesystem` 可显示 `Local`
+
+这只是说明性标签，不改变主分组。
+
+### Update Button
+
+只有以下条件才显示更新：
+
+- `source === "installed"`
+- `origin === "skillhub"`
+
+## Conflict Rules
+
+skill slug 在 library 视角必须唯一。
+
+创建 custom 时必须检查：
+
+- builtin canonical 中是否已有该 slug
+- persisted installed entries 中是否已有该 slug
+- custom canonical 中是否已有该 slug
+- external local 扫描结果中是否已有该 slug
+
+冲突时返回明确错误，例如：
+
+- `skill_slug_conflict`
+
+这样可以避免 custom 与 installed/builtin 之间的展示和 mount 歧义。
+
+## Testing Plan
+
+### Core and Domain
+
+- `SkillLibrarySource` 新枚举值测试
+- `SkillLibraryEntry` 新可选 `origin` 测试
+
+### Scanner
+
+- custom canonical 扫描返回 `source: "custom"`
+- external local 扫描返回 `source: "installed"`
+- external local 中带 managed mirror marker 的 custom 目录被跳过
+- external local 中带 managed mirror marker 的 builtin 目录被跳过
+
+### Builtin
+
+- builtin canonical materialize 输出 `source: "builtin"`
+- builtin mount 到 provider skill 目录后不会再以 installed 形式进入 library
+- 历史 stale cleanup 测试继续保留，作为遗留垃圾回收保障
+
+### Custom
+
+- `skills.custom.create` 在 custom canonical root 下创建目录
+- 创建时写 marker
+- custom mount 到 `.agents/skills` 后不会新增 installed entry
+
+### Installed
+
+- Skill Hub 安装写入 `source: "installed", origin: "skillhub"`
+- external filesystem skill 写入 `source: "installed", origin: "filesystem"`
+- external filesystem installed 不显示 update
+
+### Repo Merge
+
+- external scanned entry 不覆盖 builtin/custom/managed installed
+- 同 slug custom 存在时，external scanned item 被跳过
+
+### Commands and Routes
+
+- `skills.files.*` 仅 custom 可用
+- `/api/skill-file` 仅 custom 可用
+- custom delete 会先 unmount 再删 canonical
+- builtin uninstall 被拒绝
+
+### Frontend
+
+- `custom` 只在 `Custom Skills` section 中显示
+- `installed` 只在 `Installed` section 中显示
+- `builtin` 只在 `Built-in` section 中显示
+- enabled custom 不会在 Installed 再出现
+- enabled builtin 不会在 Installed 再出现
+- 只有 custom 有文件树与文件操作
+- 只有 skillhub installed 有 update
+
+## Risks
+
+- `source` 枚举变更会影响 server/web tests 和任何持久化快照，需要一次性修全。
+- 若历史 `library-index.json` 中保留旧枚举值，需要在读取时做兼容映射。
+- copy fallback 挂载场景下，如果 marker 没有被完整复制，会导致 mirror exclusion 失效，因此 marker 必须作为 mount copy 的一部分受测试保护。
+
+## Compatibility
+
+历史数据兼容策略：
+
+- 读取旧 entry 时：
+  - `builtin` -> `builtin`
+  - `skillhub` -> `installed` + `origin: "skillhub"`
+  - `local`
+    - 若路径位于 custom canonical root -> `custom` + `origin: "filesystem"`
+    - 否则 -> `installed` + `origin: "filesystem"`
+
+用户已确认当前没有需要迁移的老 custom skill，因此不需要自动文件迁移流程。
+
+## Implementation Outline
+
+1. 更新 core domain 类型与兼容映射
+2. 为 builtin/custom canonical 写 marker
+3. 重构本地扫描器，拆分 custom root 与 external local roots
+4. 在 external 扫描中加入 managed mirror exclusion
+5. 更新 SkillLibraryRepo merge 优先级
+6. 更新 `skills.custom.create`
+7. 更新 Skill Hub install entry 写入模型
+8. 更新 `skills.files.*` 与 `/api/skill-file` 的访问判定
+9. 更新 Skills panel 分组、detail view、按钮显示
+10. 补齐 server/web 回归测试
diff --git a/docs/superpowers/specs/2026-06-21-canvas-restore-design.md b/docs/superpowers/specs/2026-06-21-canvas-restore-design.md
new file mode 100644
index 000000000..46f1b26c9
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-21-canvas-restore-design.md
@@ -0,0 +1,571 @@
+# Canvas Restore Design
+
+> Status: Draft for user review
+> Date: 2026-06-21
+> Scope: `packages/core`, `packages/server`, `packages/web`, `packages/cli`
+
+## Problem
+
+Coder Studio previously shipped a first-class `canvas` artifact flow that let
+agents or CLI users create structured workspace artifacts and open them as
+editor tabs. That capability was introduced on 2026-06-14 and then removed on
+2026-06-14 by the `Refactor skills runtime and remove canvas surfaces` change.
+
+On current `develop`, the following are all gone:
+
+- canvas core contracts
+- canvas server commands and service
+- canvas API route
+- canvas editor-tab type and UI action
+- embedded canvas route and renderers
+- canvas CLI entrypoints
+
+The goal of this design is to restore the removed canvas feature on top of the
+current `develop` architecture without trying to replay the entire pre-removal
+branch state.
+
+## Goals
+
+- Restore a minimal but usable canvas feature on current `develop`.
+- Restore first-class canvas artifacts as editor tabs inside the existing
+  editor surface.
+- Restore two v1 artifact kinds:
+  - `architecture_canvas`
+  - `report_canvas`
+- Persist canvas source as real workspace files under
+  `.coder-studio/canvases/*.canvas.json`.
+- Restore explicit server commands to create, update, render, and list
+  canvases.
+- Restore a product-owned render path through an embedded route plus a server
+  data API.
+- Preserve the ability to open the backing source file from the canvas tab.
+- Keep the restored scope compatible with the current skills/runtime work on
+  `develop`.
+
+## Non-Goals
+
+- Do not restore freeform whiteboard editing.
+- Do not restore arbitrary agent-authored HTML.
+- Do not restore export, sharing, publishing, or permissions.
+- Do not restore advanced background rerender automation in the first pass.
+- Do not replay unrelated pre-removal refactors just because they existed in
+  the old branch.
+- Do not broaden the artifact surface beyond
+  `architecture_canvas` and `report_canvas`.
+
+## Current Context
+
+Relevant current files:
+
+- `packages/core/src/domain/types.ts`
+- `packages/core/src/domain/ui-actions.ts`
+- `packages/server/src/server.ts`
+- `packages/server/src/app.ts`
+- `packages/server/src/commands/index.ts`
+- `packages/server/src/ws/dispatch.ts`
+- `packages/web/src/app.tsx`
+- `packages/web/src/features/workspace/atoms/files.ts`
+- `packages/web/src/features/ui-actions/use-ui-action-subscription.ts`
+- `packages/web/src/features/code-editor/views/shared/editor-surface.tsx`
+- `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx`
+- `packages/cli/src/cli.ts`
+- `packages/cli/src/parse-args.ts`
+
+The current editor surface already supports mixed tab kinds through
+`WorkspaceEditorTab`, but only `file` and `browser` remain on `develop`. The
+UI action system also remains intact, so `canvas.open` can be restored without
+inventing a new transport.
+
+## User Decisions Captured
+
+- The current branch should restore canvas instead of leaving it removed.
+- The restore should target the minimal usable chain, not a full replay of the
+  old branch.
+- The restored feature should include the previously implemented artifact types:
+  `architecture_canvas` and `report_canvas`.
+- The restored feature should keep file-backed source and a product-owned
+  renderer.
+- The restored feature should keep the canvas tab, embedded route, data API,
+  and source-file workflow.
+
+## Approaches Considered
+
+### Option A: Minimal restore on top of current `develop`
+
+Restore only the canvas-specific contracts, server flow, editor-tab support,
+embedded route, renderers, and CLI commands. Adapt them where necessary to fit
+the current codebase.
+
+Pros:
+
+- Lowest risk to the current skills/runtime work.
+- Smallest restore surface that still returns visible user value.
+- Lets us verify the old canvas model still fits the current editor shell.
+
+Cons:
+
+- Requires some selective adaptation instead of a blind revert.
+
+Decision: accept.
+
+### Option B: Replay the pre-removal canvas implementation wholesale
+
+Try to reapply the removed canvas implementation nearly verbatim.
+
+Pros:
+
+- Conceptually simple.
+- Preserves old file structure and behavior.
+
+Cons:
+
+- High conflict risk with post-removal `develop`.
+- Risks reintroducing stale assumptions from the old branch.
+- Pulls in more incidental surface area than needed.
+
+Decision: reject.
+
+### Option C: Restore only the read-only embedded route first
+
+Bring back just the render route and API, leaving out create/update/list and
+editor-tab integration.
+
+Pros:
+
+- Lowest implementation risk.
+
+Cons:
+
+- Incomplete user-facing feature.
+- Does not actually restore the original canvas workflow.
+
+Decision: reject.
+
+## Final Design
+
+## 1. Scope Summary
+
+The restore target is the smallest version that feels like the former canvas
+feature to an end user:
+
+- a canvas can be created, updated, rendered, and listed through server
+  commands
+- a canvas source file exists in the workspace
+- a canvas can open as an editor tab through a UI action
+- the tab shows an embedded canvas page rendered by product-owned UI
+- the user can open the source file and manually refresh the render
+
+This pass intentionally excludes automatic rerender orchestration beyond
+explicit `canvas.render` and manual refresh.
+
+## 2. High-Level Architecture
+
+The restored flow is:
+
+`agent or CLI -> canvas.create/update/render/list -> server validate/persist/compile -> canvas.open UI action -> editor tab -> embedded route -> /api/canvas/.../data -> renderer`
+
+The important boundary remains:
+
+- source is typed JSON stored in the workspace
+- server owns validation and compilation
+- frontend owns presentation only
+- the canvas tab is a viewer plus control surface, not the source editor
+
+## 3. Data Model
+
+### 3.1 Core schema restoration
+
+Restore `packages/core/src/domain/canvas.ts` with the previously implemented
+contracts:
+
+- `CanvasArtifactKind`
+- `CanvasRecord`
+- `CanvasDocumentEnvelope`
+- `CompiledCanvas`
+- `CanvasDataResponse`
+- render status and render error types
+
+The restore keeps the existing v1 envelope shape:
+
+```json
+{
+  "version": 1,
+  "kind": "architecture_canvas",
+  "title": "Runtime Flow",
+  "document": {}
+}
+```
+
+### 3.2 Workspace UI state restoration
+
+Restore `WorkspaceCanvasEditorTab` to `packages/core/src/domain/types.ts` and
+re-add it to `WorkspaceEditorTab`.
+
+Expected shape:
+
+```ts
+interface WorkspaceCanvasEditorTab {
+  kind: "canvas";
+  id: string;
+  canvasId: string;
+  title: string;
+  artifactType: "architecture_canvas" | "report_canvas";
+  sourcePath: string;
+}
+```
+
+This allows canvas tabs to participate in:
+
+- open tab persistence
+- active tab restoration
+- existing mixed-tab editor UI
+
+### 3.3 UI action restoration
+
+Restore `canvas.open` in `packages/core/src/domain/ui-actions.ts` so the server
+can tell the frontend to open a persisted canvas.
+
+The action payload should include:
+
+- `workspaceId`
+- `canvasId`
+- `title`
+- `artifactType`
+- `sourcePath`
+
+## 4. Server Design
+
+### 4.1 Repository
+
+Restore `packages/server/src/storage/repositories/canvas-repo.ts`.
+
+Responsibilities:
+
+- store workspace-local canvas metadata
+- list canvases by workspace
+- get by `workspaceId + canvasId`
+- upsert records
+
+The repo remains metadata-only. It does not store the source document body.
+
+### 4.2 Source of truth
+
+Canvas content continues to live in real workspace files:
+
+- `.coder-studio/canvases/<canvas-id>.canvas.json`
+
+The repo stores only index/runtime state:
+
+- id
+- workspaceId
+- sessionId when available
+- sourcePath
+- artifactType
+- title
+- updatedAt
+- renderStatus
+- lastError
+
+### 4.3 Validation and compilation
+
+Restore `packages/server/src/canvas/*`:
+
+- `validation.ts`
+- `compiler.ts`
+- `service.ts`
+- supporting graph/mermaid helpers needed by `architecture_canvas`
+
+Responsibilities:
+
+- parse and validate source JSON
+- compile source to frontend render data
+- normalize validation and compile failures into structured canvas errors
+
+The restore keeps the previous rendering model:
+
+- `architecture_canvas`
+  - diagram section
+  - annotations section
+- `report_canvas`
+  - stats
+  - markdown
+  - list
+  - table
+  - callout
+  - section
+
+### 4.4 Commands
+
+Restore `packages/server/src/commands/canvas.ts` and register it from
+`packages/server/src/commands/index.ts`.
+
+Commands to restore:
+
+- `canvas.list`
+- `canvas.create`
+- `canvas.update`
+- `canvas.render`
+
+Behavior:
+
+- `canvas.create`
+  - validate input
+  - create a new canvas id
+  - write source file
+  - persist metadata
+  - compile once
+  - optionally broadcast `canvas.open`
+- `canvas.update`
+  - load existing record
+  - rewrite source file with optimistic base hash protection
+  - compile once
+- `canvas.render`
+  - rerender an existing canvas by id or source path
+- `canvas.list`
+  - return workspace canvas records
+
+### 4.5 Route
+
+Restore `packages/server/src/routes/canvas.ts` and register it from
+`packages/server/src/app.ts`.
+
+Route:
+
+- `GET /api/canvas/:workspaceId/:canvasId/data`
+
+Behavior:
+
+- resolve workspace
+- fetch current compiled data from `CanvasService`
+- return `404` for missing workspace or canvas
+- return structured error payloads only for expected canvas-not-found cases
+
+### 4.6 Server assembly
+
+Update `packages/server/src/server.ts` and `packages/server/src/ws/dispatch.ts`
+to wire `CanvasRepo` and `CanvasService` into `CommandContext`.
+
+This is the only new server dependency added in the restore. No unrelated
+server subsystems should change.
+
+## 5. Frontend Design
+
+### 5.1 Router restoration
+
+Restore the embedded canvas route in `packages/web/src/app.tsx`:
+
+- `/embedded/canvas/:workspaceId/:canvasId`
+
+This route should be handled before the normal shell catch-all.
+
+### 5.2 Canvas feature module
+
+Restore `packages/web/src/features/canvas/*`:
+
+- `api.ts`
+- `routes/embedded-canvas-route.tsx`
+- `components/canvas-route-frame.tsx`
+- `components/architecture-canvas-renderer.tsx`
+- `components/report-canvas-renderer.tsx`
+
+Responsibilities:
+
+- fetch compiled data from the server
+- render loading/error/ready states
+- display architecture and report artifacts using product-owned UI
+
+### 5.3 Editor tab support
+
+Update `packages/web/src/features/workspace/atoms/files.ts` to restore:
+
+- `WorkspaceCanvasEditorTab`
+- normalization support for persisted canvas tabs
+- `canvasRefreshTokenAtomFamily`
+
+The refresh token stays local to the frontend and only exists to force the
+embedded iframe URL to reload after a manual rerender.
+
+### 5.4 UI action subscription
+
+Update `packages/web/src/features/ui-actions/use-ui-action-subscription.ts`
+to handle `canvas.open`.
+
+Behavior:
+
+- create or replace a canvas tab keyed by `canvasId`
+- mark the editor view visible
+- set the canvas tab as active
+
+This mirrors the existing browser-tab flow instead of introducing a new UI
+action subsystem.
+
+### 5.5 Editor surface integration
+
+Update `packages/web/src/features/code-editor/views/shared/editor-surface.tsx`
+to recognize `canvas` tabs and render a restored `CanvasSurface`.
+
+`CanvasSurface` responsibilities:
+
+- show toolbar actions
+- render the embedded route in an iframe
+- provide:
+  - `Open source`
+  - `Refresh`
+
+`Open source` opens the backing `.canvas.json` file in the standard editor.
+
+`Refresh` dispatches `canvas.render` and increments the refresh token for the
+iframe when the command succeeds.
+
+### 5.6 Tab chrome integration
+
+Update `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx`
+to support:
+
+- canvas tab title display
+- activation
+- close behavior
+- canvas-specific iconography
+
+The tab should behave like a first-class mixed tab beside file and browser
+tabs, not like a special overlay.
+
+## 6. CLI Design
+
+Restore the `canvas` automation surface in:
+
+- `packages/cli/src/parse-args.ts`
+- `packages/cli/src/cli.ts`
+
+Commands to restore:
+
+- `coder-studio canvas list`
+- `coder-studio canvas create`
+- `coder-studio canvas update`
+- `coder-studio canvas render`
+
+The CLI should remain a thin wrapper over the restored server commands. No
+special client-side compilation logic should be introduced.
+
+## 7. Error Handling
+
+### 7.1 Validation failures
+
+If `canvas.create` or `canvas.update` receives invalid source content:
+
+- reject the request with a structured validation error
+- do not persist invalid source
+- do not silently coerce to another shape
+
+### 7.2 Compile failures
+
+If source validation passes but compilation fails:
+
+- persist the source
+- mark the record `renderStatus: "error"`
+- return `lastError`
+- let the frontend render a canvas error state
+
+This preserves user-editable source while surfacing a broken render.
+
+### 7.3 Frontend states
+
+The embedded route must explicitly handle:
+
+- loading
+- no data
+- error
+- ready
+
+The canvas tab itself should not collapse or disappear on render failure. The
+failure needs to remain inspectable and refreshable.
+
+## 8. Testing Strategy
+
+### 8.1 Core
+
+Restore or add tests covering:
+
+- source envelope validation
+- compiled document contracts
+- `CanvasDataResponse` invariants
+
+### 8.2 Server
+
+Restore or add tests covering:
+
+- `CanvasService.create`
+- `CanvasService.update`
+- `CanvasService.renderFromSourcePath`
+- `CanvasService.getCanvasData`
+- `canvas` command handlers
+- canvas API route responses
+- server wiring for route and command context
+
+### 8.3 Frontend
+
+Restore or add tests covering:
+
+- `App` route selection for `/embedded/canvas/...`
+- `useUiActionSubscription` handling of `canvas.open`
+- `editor-surface` canvas rendering path
+- tab header activation and close behavior for canvas tabs
+- embedded route loading/error/ready states
+- both canvas renderer variants
+
+### 8.4 CLI
+
+Restore or add tests for:
+
+- `parse-args` support for the `canvas` command family
+- CLI command dispatch wiring
+
+## 9. Restore Order
+
+Implementation should proceed in this order:
+
+1. restore core contracts
+2. restore server repo/service/commands/route
+3. restore frontend router, tab model, surface, and renderers
+4. restore CLI support
+5. run focused tests
+6. run repository verification relevant to the touched packages
+
+This ordering keeps the contract and backend ready before the UI starts
+consuming them.
+
+## 10. Risks and Constraints
+
+- Current `develop` has moved on in skills/runtime areas, so blind revert
+  strategies are unsafe.
+- The old canvas implementation used large UI components; restore work should
+  avoid incidental UI refactors while still fitting current imports and tests.
+- Automatic rerender-on-file-change existed as a design goal before removal,
+  but this restore does not depend on reintroducing that behavior.
+
+## 11. Acceptance Criteria
+
+The restore is complete when all of the following are true:
+
+- a canvas can be created through the restored server command path
+- source is written under `.coder-studio/canvases/`
+- a canvas can be opened as an editor tab through `canvas.open`
+- the tab loads `/embedded/canvas/:workspaceId/:canvasId`
+- the embedded route fetches `/api/canvas/:workspaceId/:canvasId/data`
+- `architecture_canvas` and `report_canvas` both render
+- the user can open the backing source file from the canvas tab
+- the user can manually refresh the render from the canvas tab
+- restored focused tests pass
+
+## 12. Design Summary
+
+This restore intentionally brings back the old canvas user experience without
+bringing back the whole old branch. The product shape remains:
+
+- typed source in workspace files
+- server-owned validation and compilation
+- first-class canvas tabs in the editor
+- embedded product renderers for architecture and report artifacts
+
+That is enough to make the previous canvas feature visible and usable again on
+today's `develop` while keeping the implementation surface constrained.
diff --git a/docs/superpowers/specs/2026-06-21-skill-recommendations-pagination-design.md b/docs/superpowers/specs/2026-06-21-skill-recommendations-pagination-design.md
new file mode 100644
index 000000000..34dbf11fe
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-21-skill-recommendations-pagination-design.md
@@ -0,0 +1,479 @@
+# Skill Recommendations Pagination Design
+
+Date: 2026-06-21
+Status: Draft
+Owner: codex
+
+## Problem
+
+当前 `Skills` 面板里的推荐区使用 `skills.recommend` 一次性返回固定数量的结果，前端直接整块渲染：
+
+- 默认不传 `limit`
+- 服务端默认只返回 5 条推荐
+- 接口参数把 `limit` 上限限制在 10
+- 推荐区没有分页能力
+- 推荐区也没有“滚动到底部继续加载”的交互
+
+这会带来两个问题：
+
+- 推荐区默认可见内容太少，用户很容易看不到后续推荐
+- 如果简单把默认数量调大，推荐区会继续走“一次性全量加载”的模型，后续扩展性和滚动体验都不理想
+
+用户这次要的不是单纯把数字从 5 改成 20，而是把推荐区改成真正的分页模型：
+
+- 首屏默认展示 20 条
+- 用户继续滚动整个侧边栏时，推荐区底部进入视口后自动加载下一页
+- 推荐区本身不变成独立滚动容器
+
+## Goals
+
+- 把推荐区首屏默认数量提升到 20 条。
+- 为 `skills.recommend` 增加稳定的分页能力。
+- 在推荐区底部进入当前侧边栏滚动视口时，自动加载下一页。
+- 保持当前侧边栏“单滚动容器”的交互，不引入推荐区内部二次滚动。
+- 在推荐结果刷新后重置分页，避免旧结果和新结果混杂。
+- 复用仓库内现有分页与触底加载模式，尽量减少新交互语义。
+
+## Non-Goals
+
+- 这次不改 `Discover` 搜索结果的分页模型。
+- 这次不改推荐算法本身，不调整 query seed、权重或排序规则。
+- 这次不为推荐结果引入游标型分页。
+- 这次不把推荐区改成独立滚动列表。
+- 这次不新增“手动加载更多”按钮作为主路径。
+- 这次不尝试缓存跨页推荐快照或做服务端增量推荐计算。
+
+## Current Context
+
+### Existing Recommend API
+
+服务端命令注册位于：
+
+- [`packages/server/src/commands/skills/query.ts`](../../../packages/server/src/commands/skills/query.ts)
+
+当前 `skills.recommend` 的特点：
+
+- 请求参数只包含 `workspaceId` 和可选 `limit`
+- `limit` 上限被限制为 10
+- 返回值是 `SkillRecommendationEntry[]`
+- 调用 `inspectWorkspaceIntelligence()` 生成工作区摘要
+- 再调用 `buildSkillRecommendations()` 生成推荐列表
+
+### Existing Recommendation Builder
+
+推荐构建逻辑位于：
+
+- [`packages/server/src/skills/recommendation.ts`](../../../packages/server/src/skills/recommendation.ts)
+
+当前行为：
+
+- 基于 workspace intelligence 构建若干 query seed
+- 并行调用 skills hub 搜索
+- 合并多组 query 的结果并累积分数
+- 过滤已安装 skill
+- 按 `score -> displayName -> slug` 排序
+- 最后做一次 `slice(0, limit)`
+
+这意味着推荐列表本质上已经先形成一个完整排序结果，再截断返回。因此它天然更适合使用 `offset + limit` 切片，而不是强行引入 cursor。
+
+### Existing Frontend Recommendations Flow
+
+前端推荐区的主要逻辑位于：
+
+- [`packages/web/src/features/workspace/actions/use-skills-panel.ts`](../../../packages/web/src/features/workspace/actions/use-skills-panel.ts)
+- [`packages/web/src/features/workspace/views/shared/skills-panel.tsx`](../../../packages/web/src/features/workspace/views/shared/skills-panel.tsx)
+
+当前行为：
+
+- `refreshRecommendations()` 调用 `skills.recommend`
+- 返回值直接写入 `recommendations` state
+- 视图层对 `recommendations` 做本地排序后整块渲染
+- 没有 `hasMore`
+- 没有分页 loading 状态
+- 没有触底加载逻辑
+
+### Existing Scroll Root
+
+当前侧边栏内容区的滚动容器不是推荐区本身，而是整个侧边栏 body：
+
+- [`packages/web/src/styles/components.css`](../../../packages/web/src/styles/components.css)
+
+关键规则：
+
+- `.workspace-sidebar-panel__content > .workspace-sidebar-view > .workspace-sidebar-panel__body { overflow-y: auto; }`
+
+这意味着推荐区要实现触底加载，observer 的 `root` 应该绑定到侧边栏 body，而不是推荐区列表本身。
+
+### Existing Infinite Scroll Pattern
+
+仓库里已经有稳定的“滚动到底部自动加载下一页”模式：
+
+- [`packages/web/src/features/workspace/views/shared/git-panel.tsx`](../../../packages/web/src/features/workspace/views/shared/git-panel.tsx)
+- [`packages/web/src/features/workspace/actions/use-git-actions.ts`](../../../packages/web/src/features/workspace/actions/use-git-actions.ts)
+
+该模式使用：
+
+- `IntersectionObserver`
+- 底部 sentinel 元素
+- `hasMore` 状态
+- 单独的分页 loading 状态
+- 请求并发保护
+
+推荐区应复用这一思路，而不是新造另一套触底加载模型。
+
+## User Decisions Captured
+
+- 推荐区默认首屏展示 20 条。
+- “加载更多”必须是真分页，而不是前端一次性拿全量后再逐步展开。
+- 触发下一页的动作来自滚动整个侧边栏，不是推荐区内部滚动。
+- 推荐区不新增独立滚动容器。
+- 实现方案采用 `offset + limit`，不采用 cursor 分页。
+
+## Approaches Considered
+
+### Option A: Offset + Limit Pagination（推荐）
+
+核心思路：
+
+- 服务端每次按当前逻辑生成完整有序推荐列表
+- 返回前按 `offset + limit` 切片
+- 同时返回 `hasMore`
+- 前端首屏请求 `offset=0, limit=20`
+- 后续页用 `offset=recommendations.length, limit=20`
+
+优点：
+
+- 最贴近当前实现
+- 服务端改动边界清晰
+- 易于复用现有前端 infinite scroll 模式
+- 不需要保存复杂的推荐游标状态
+
+缺点：
+
+- 每次翻页都要重新构建完整推荐列表
+- 推荐结果如果在刷新期间发生变化，前端需要做去重保护
+
+### Option B: Cursor Pagination
+
+核心思路：
+
+- 服务端在第一页返回分页 cursor
+- 前端用 cursor 请求下一页
+
+优点：
+
+- 接口语义更像传统分页 API
+
+缺点：
+
+- 当前推荐结果并没有天然 cursor 来源
+- 仍然需要先构建完整推荐列表再导出 cursor
+- 复杂度高于收益
+- 不符合当前推荐源的真实数据形态
+
+## Final Choice
+
+采用 Option A。
+
+本次把 `skills.recommend` 改成基于 `offset + limit` 的分页接口，并让前端推荐区在现有侧边栏滚动容器里通过底部 sentinel 自动加载下一页。
+
+## API Design
+
+### Request Shape
+
+`skills.recommend` 请求参数调整为：
+
+- `workspaceId: string`
+- `limit?: number`
+- `offset?: number`
+
+规则：
+
+- `limit` 默认值为 `20`
+- `limit` 上限调整为 `20`
+- `offset` 默认值为 `0`
+- `offset` 最小值为 `0`
+
+这里把上限直接收敛到 20，是为了和当前明确确认的 UI 分页粒度保持一致，避免本次改动引入未使用的更大页尺寸。
+
+### Response Shape
+
+`skills.recommend` 返回值从：
+
+- `SkillRecommendationEntry[]`
+
+改为：
+
+- `{ entries: SkillRecommendationEntry[]; hasMore: boolean }`
+
+`hasMore` 的含义与 `git.log` 保持一致：
+
+- 当前页后仍有更多推荐结果时为 `true`
+- 当前页已经到达末尾时为 `false`
+
+### Server Pagination Rules
+
+服务端分页规则：
+
+1. 先按当前逻辑生成完整排序后的推荐列表。
+2. 用 `offset` 和 `limit` 对完整列表做切片。
+3. `hasMore = offset + entries.length < totalEntries`
+
+这保证：
+
+- 排序稳定
+- 不会因为前端分页导致跨页顺序变化
+- 分页语义可以和当前推荐算法解耦
+
+## Server Design
+
+### Command Layer
+
+修改：
+
+- [`packages/server/src/commands/skills/query.ts`](../../../packages/server/src/commands/skills/query.ts)
+
+变更内容：
+
+- 放宽 `skills.recommend` 参数 schema，支持 `offset`
+- `limit` 默认值改为 20，最大值改为 20
+- 返回值改为分页对象，而不是数组
+
+### Recommendation Builder
+
+修改：
+
+- [`packages/server/src/skills/recommendation.ts`](../../../packages/server/src/skills/recommendation.ts)
+
+建议把当前“生成完整推荐列表”和“应用分页切片”显式分层：
+
+- 保留现有推荐构建和排序逻辑
+- 新增分页包装逻辑，负责 `offset/limit` 和 `hasMore`
+
+目标不是重写推荐算法，而是把当前隐式的 `slice(0, limit)` 提升成显式分页输出。
+
+### Shared Domain Types
+
+修改：
+
+- [`packages/core/src/domain/skill-management.ts`](../../../packages/core/src/domain/skill-management.ts)
+
+新增稳定的分页返回类型，例如：
+
+- `SkillRecommendationPage`
+
+它至少包含：
+
+- `entries: SkillRecommendationEntry[]`
+- `hasMore: boolean`
+
+这样前后端、UI preview 和测试都能共享同一个返回契约。
+
+## Frontend Design
+
+### State Model
+
+修改：
+
+- [`packages/web/src/features/workspace/actions/use-skills-panel.ts`](../../../packages/web/src/features/workspace/actions/use-skills-panel.ts)
+
+推荐状态从“单数组”扩展为分页状态：
+
+- `recommendations`
+- `recommendationsHasMore`
+- `loadingRecommendations`
+- `loadingRecommendationPage`
+
+并增加一个分页请求锁，防止 observer 连续触发造成重复请求。
+
+### Data Flow
+
+前端需要两个清晰动作：
+
+1. `refreshRecommendations()`
+
+行为：
+
+- 清空当前推荐分页状态
+- 请求第一页：`offset=0, limit=20`
+- 替换 `recommendations`
+- 更新 `recommendationsHasMore`
+
+2. `loadMoreRecommendations()`
+
+行为：
+
+- 如果首屏仍在加载、正在翻页、`hasMore=false`、推荐区折叠，则直接返回
+- 请求下一页：`offset=recommendations.length, limit=20`
+- 结果按 `slug` 去重后追加到列表末尾
+- 更新 `recommendationsHasMore`
+
+这里必须做 `slug` 去重，因为服务端每次翻页都会重新计算完整推荐集。如果在刷新、安装或外部状态变化的边界时推荐结果略有漂移，前端仍应避免重复卡片。
+
+### Refresh Triggers
+
+以下场景统一触发“重置并加载第一页”：
+
+- 面板初次加载
+- `refreshToken` 变化
+- skill 安装成功
+- skill 卸载成功
+- skill 更新成功
+
+目标是保证推荐区始终反映当前 skill 安装状态和工作区分析结果，而不是在旧分页基础上继续叠加新结果。
+
+### View Integration
+
+修改：
+
+- [`packages/web/src/features/workspace/views/shared/skills-panel.tsx`](../../../packages/web/src/features/workspace/views/shared/skills-panel.tsx)
+
+视图层变更：
+
+- 推荐区底部新增 sentinel 元素
+- 当推荐区展开、`hasMore=true`、浏览器支持 `IntersectionObserver` 时，注册 observer
+- observer 的 `root` 指向当前侧边栏滚动容器 `.workspace-sidebar-panel__body`
+- sentinel 进入视口后触发 `loadMoreRecommendations()`
+
+### Loading UX
+
+推荐区加载态分成两种：
+
+1. 首屏加载
+
+- 沿用当前整块推荐区的 loading 文案
+
+2. 后续分页加载
+
+- 不覆盖已加载卡片
+- 只在推荐列表底部显示一条轻量 loading 行
+- sentinel 保持在列表尾部
+
+这样能避免用户滚动到一半时，整个推荐区闪回到首屏 loading 状态。
+
+## Interaction Design
+
+### Default Behavior
+
+- 用户打开 `Skills` 面板
+- 推荐区首屏加载 20 条
+- 用户继续滚动整个侧边栏
+- 当推荐区底部进入当前侧边栏滚动视口时，自动加载下一页 20 条
+
+### Collapsed State
+
+- 推荐区折叠时不注册 observer
+- 折叠期间不触发分页请求
+- 重新展开后保留已加载的推荐结果和 `hasMore` 状态
+
+这保证折叠动作只影响可见性，不意外重置用户已加载的内容。
+
+### Empty State
+
+- 第一页返回空结果时，继续显示现有“无推荐”文案
+- 后续页如果返回空列表，只更新 `hasMore=false`，不显示额外空态
+
+### Failure State
+
+- 第一页请求失败：保持现有错误提示语义
+- 后续页请求失败：不清空当前已加载推荐，只停止本次追加并保留现有列表
+
+这样失败不会破坏用户已经看到的推荐内容。
+
+## Edge Cases
+
+### Recommendation Set Changes Between Pages
+
+由于服务端每次翻页都会重新计算完整推荐集，理论上可能出现：
+
+- 某个 skill 在第一页请求后被安装
+- 工作区状态变化导致推荐排序略变
+
+本次设计的处理方式是：
+
+- 显式刷新场景一律重置分页
+- 非刷新场景下，前端追加时按 `slug` 去重
+
+本次不尝试跨请求锁定服务端推荐快照，因为这会引入额外状态管理，而当前需求不需要。
+
+### Observer Availability
+
+如果浏览器环境没有 `IntersectionObserver`：
+
+- 推荐区仍正常显示第一页 20 条
+- 不启用自动加载下一页
+
+本次不为这一降级路径补做新的按钮型交互，因为当前运行环境以现代浏览器为主，且仓库已有多个 observer 依赖点。
+
+### Duplicate Fetch Prevention
+
+触底 observer 在快速滚动时可能多次触发，因此前端必须使用单独的分页请求锁，保证：
+
+- 同一时间最多只有一个“下一页”请求在飞行
+- 首屏加载和分页加载不会并发执行
+
+## Testing
+
+### Server Tests
+
+修改或新增：
+
+- [`packages/server/src/__tests__/skills/commands.test.ts`](../../../packages/server/src/__tests__/skills/commands.test.ts)
+- [`packages/core/src/domain/skill-management.test.ts`](../../../packages/core/src/domain/skill-management.test.ts)
+
+至少覆盖：
+
+- `skills.recommend` 默认返回分页对象
+- 默认分页大小为 20
+- `offset + limit` 切片正确
+- `hasMore` 在中间页和末页上的行为正确
+
+### Frontend Action Tests
+
+修改或新增：
+
+- [`packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`](../../../packages/web/src/features/workspace/views/shared/skills-panel.test.tsx)
+- [`packages/web/src/features/workspace/actions/use-skills-panel.ts`](../../../packages/web/src/features/workspace/actions/use-skills-panel.ts)
+
+至少覆盖：
+
+- 首屏请求会发送 `limit=20, offset=0`
+- 触发分页时会发送下一页 `offset`
+- 分页结果会追加而不是覆盖
+- 重复 slug 会被去重
+- `refreshToken` 或安装成功后会重置并重新从第一页开始
+
+### View Tests
+
+至少覆盖：
+
+- 推荐区展开且 `hasMore=true` 时注册 observer
+- sentinel 进入视口会触发 `loadMoreRecommendations()`
+- 推荐区折叠时不触发分页
+- 分页 loading 只显示在列表底部，不覆盖已有结果
+
+## Files Expected To Change
+
+- [`packages/core/src/domain/skill-management.ts`](../../../packages/core/src/domain/skill-management.ts)
+- [`packages/core/src/domain/skill-management.test.ts`](../../../packages/core/src/domain/skill-management.test.ts)
+- [`packages/server/src/commands/skills/query.ts`](../../../packages/server/src/commands/skills/query.ts)
+- [`packages/server/src/skills/recommendation.ts`](../../../packages/server/src/skills/recommendation.ts)
+- [`packages/server/src/__tests__/skills/commands.test.ts`](../../../packages/server/src/__tests__/skills/commands.test.ts)
+- [`packages/web/src/features/workspace/actions/use-skills-panel.ts`](../../../packages/web/src/features/workspace/actions/use-skills-panel.ts)
+- [`packages/web/src/features/workspace/views/shared/skills-panel.tsx`](../../../packages/web/src/features/workspace/views/shared/skills-panel.tsx)
+- [`packages/web/src/features/workspace/views/shared/skills-panel.test.tsx`](../../../packages/web/src/features/workspace/views/shared/skills-panel.test.tsx)
+- [`packages/web/src/ui-preview/preview-store.ts`](../../../packages/web/src/ui-preview/preview-store.ts)
+
+## Verification Strategy
+
+实现阶段至少需要运行：
+
+- `pnpm --filter @coder-studio/core test -- skill-management`
+- `pnpm --filter @coder-studio/server test -- skills`
+- `pnpm --filter @coder-studio/web test -- skills-panel`
+
+如果包级命令与仓库当前脚本组织不完全匹配，则应回退到仓库实际可用的等价测试命令，但验证范围必须覆盖：
+
+- 共享类型
+- 服务端推荐分页
+- 前端推荐分页与触底加载
diff --git a/docs/superpowers/specs/2026-06-23-builtin-skill-automation-bridge-design.md b/docs/superpowers/specs/2026-06-23-builtin-skill-automation-bridge-design.md
new file mode 100644
index 000000000..273d29f87
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-23-builtin-skill-automation-bridge-design.md
@@ -0,0 +1,413 @@
+# Built-in Skill Automation Bridge Design
+
+> Status: Draft for user review
+> Date: 2026-06-23
+> Scope: `packages/server`, `packages/cli`, builtin skill assets, tests
+
+## Problem
+
+Coder Studio's built-in automation skills currently describe user-facing CLI commands such as:
+
+```bash
+coder-studio memory add ...
+```
+
+That contract is too weak for agent automation.
+
+In the current dev and Windows workflow, the failure mode is not that the backend command is missing. The real failure is that the agent process can resolve a different `coder-studio` binary than the developer expects:
+
+- the user terminal may hit a local dev shim
+- the agent session may hit a global install
+- PATH injection is not a strong enough contract for mounted skills
+- shell-specific entry syntax (`$env:...`, `"$VAR"`, `%VAR%`) leaks compatibility concerns into the skill itself
+
+This creates three product problems:
+
+1. built-in skills are versioned separately from the real automation entry they need
+2. skill docs rely on PATH/global command discovery
+3. Windows/dev behavior can drift from the workspace runtime the session actually belongs to
+
+The user wants a more stable agent-facing contract:
+
+- the skill should ship its own stable Node entry
+- that entry should read session/runtime context from environment
+- the skill should not call `coder-studio` directly
+- the skill should not require PATH or shell-specific environment expansion
+
+## Goals
+
+- Keep the existing backend command bus and websocket automation transport.
+- Remove PATH and global `coder-studio` resolution from the built-in skill contract.
+- Make the skill-facing command shell-stable by invoking `node <absolute-skill-cmd-path> ...`.
+- Version the skill instructions and the skill launcher together.
+- Bind provider-specific mounted paths at skill mount time.
+- Bind runtime session context at session creation time.
+- Allow all Coder Studio built-in automation skills to share the same launcher implementation.
+
+## Non-Goals
+
+- Do not add a new public human-facing CLI command such as `coder-studio-automation`.
+- Do not move automation to MCP for this phase.
+- Do not replace the current websocket command bus with a REST-only transport.
+- Do not teach third-party or arbitrary local skills to use this launcher automatically.
+- Do not redesign the full skill management system beyond what is needed for built-in automation skills.
+
+## Current Context
+
+Relevant current behavior:
+
+- Built-in skills currently materialize only `SKILL.md`.
+- Built-in skill definitions do not support extra files.
+- Skill mount currently symlinks or copies the canonical skill directory into the provider's mounted skill directory.
+- Agent sessions already inject:
+  - `CODER_STUDIO_SESSION_TOKEN`
+  - `CODER_STUDIO_API_URL`
+  - `CODER_STUDIO_WORKSPACE_ID`
+  - session/provider metadata
+- The existing CLI already maps automation commands to backend websocket ops such as `memory.create`.
+
+Relevant files:
+
+- `packages/server/src/skills/builtin/definitions/types.ts`
+- `packages/server/src/skills/builtin/materialize.ts`
+- `packages/server/src/skills/mount-manager.ts`
+- `packages/server/src/session/manager.ts`
+- `packages/cli/src/automation-command-client.ts`
+- `packages/server/src/skills/builtin/definitions/coder-studio-memory.ts`
+- `packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts`
+- `packages/server/src/skills/builtin/definitions/coder-studio-open.ts`
+
+## User Decisions Captured
+
+- Do not keep a second public command name just for human use.
+- The agent-facing contract should not depend on PATH.
+- The most stable skill contract is a mounted `cmd.mjs` shipped with the skill.
+- All Coder Studio built-in automation skills can use the same `cmd.mjs` content.
+- The mount step should generate the final skill-facing command path for the current provider/environment.
+- Session startup should inject runtime context such as API URL, workspace id, and session token.
+- The launcher should be a thin bridge, not a second independent automation stack.
+
+## Approaches Considered
+
+### Option A: Keep using `coder-studio ...`
+
+Pros:
+
+- Minimal immediate code change
+
+Cons:
+
+- still depends on PATH/global resolution
+- still reproduces the Windows/dev mismatch
+- skill and runtime entry stay version-decoupled
+
+Decision: reject.
+
+### Option B: Expose a session env entry directly in the skill
+
+Example:
+
+```bash
+"$CODER_STUDIO_AUTOMATION_ENTRY" memory create ...
+```
+
+Pros:
+
+- removes PATH dependency
+- reuses one real automation entry
+
+Cons:
+
+- pushes shell syntax differences into `SKILL.md`
+- still leaves PowerShell / POSIX / cmd.exe compatibility as a skill concern
+- makes the skill contract less portable to different providers
+
+Decision: reject as the skill-facing contract.
+
+### Option C: Mount-rendered `cmd.mjs` bridge inside the skill, with session-injected runtime context
+
+Pros:
+
+- skill-facing command becomes stable and shell-simple
+- `SKILL.md` and `cmd.mjs` version together
+- mounted absolute path can be rendered for the actual provider target directory
+- runtime context stays in env, not in the skill files
+- the same bridge file can be reused by memory, canvas, and open skills
+
+Cons:
+
+- requires built-in skill materialization to support extra files
+- requires mount-time rendering instead of a pure symlink/copy flow for these skills
+
+Decision: accept.
+
+## Final Design
+
+## 1. Contract Split
+
+The final contract is intentionally split into two phases:
+
+### Mount-time contract
+
+At mount time, Coder Studio determines the provider's real mounted skill directory and writes a provider-specific `SKILL.md` that references the mounted launch script by absolute path.
+
+This solves the path problem.
+
+### Session-time contract
+
+At session startup, Coder Studio injects runtime context into the agent process environment.
+
+This solves the runtime binding problem.
+
+The skill files must never embed secrets or session-specific tokens.
+
+## 2. Skill-Facing Command Shape
+
+Built-in automation skills will stop documenting `coder-studio ...` commands.
+
+They will instead document commands in this shape:
+
+```bash
+node "<absolute-mounted-skill-path>/cmd.mjs" memory.create --type issue --content "..." --status not_started --json
+```
+
+Properties of this contract:
+
+- no PATH lookup
+- no `npx`
+- no global install requirement
+- no shell-specific env expansion syntax in the skill itself
+- `node` remains the only required executable
+
+The initial phase should use backend-op-aligned names such as:
+
+- `memory.list`
+- `memory.search`
+- `memory.get`
+- `memory.create`
+- `memory.update`
+- `memory.delete`
+- `canvas.list`
+- `canvas.create`
+- `canvas.update`
+- `canvas.render`
+- `ui.open-file`
+- `ui.open-url`
+- `ui.open-canvas`
+
+Friendly aliases may be added later, but they are not required for this phase.
+
+## 3. Built-in Skill Packaging Model
+
+Extend built-in skill definitions so they can materialize more than `SKILL.md`.
+
+The built-in model should support:
+
+- primary instruction content
+- additional managed files
+
+Recommended definition shape:
+
+- keep `content` as the canonical library `SKILL.md`
+- add a managed-files field such as `files[]` with relative path plus file content
+
+For built-in automation skills, each canonical skill directory should contain at least:
+
+- `SKILL.md`
+- `cmd.mjs`
+
+`cmd.mjs` content should be identical across Coder Studio's built-in automation skills.
+
+This bridge is not a per-skill implementation file. It is a shared launcher that ships with each built-in automation skill so the skill remains self-contained when mounted.
+
+Recommended source-of-truth structure:
+
+- one shared runner template in the repository
+- built-in definitions reference that template when materializing
+
+This avoids hand-maintaining duplicate launcher code in multiple definition files.
+
+## 4. Mount-Time Rendering
+
+The mounted skill directory must be treated as the place where final skill-facing instructions are rendered.
+
+This is required because the final command path is provider-specific:
+
+- Codex may mount to `~/.agents/skills/...`
+- Claude may mount to `~/.claude/skills/...`
+- other providers may use different mounted skill roots
+
+The absolute path embedded in `SKILL.md` must therefore be derived from:
+
+```ts
+join(mountRelation.targetPath, "cmd.mjs")
+```
+
+Not from:
+
+- the workspace root
+- the skill source path
+- a PATH command name
+
+### Rendering behavior
+
+For built-in automation skills:
+
+1. resolve the real provider target path
+2. mount using `copy`, not `symlink`
+3. ensure the target directory exists
+4. copy managed files, including `cmd.mjs`, into the target directory
+5. rewrite mounted `SKILL.md` using the final absolute `cmd.mjs` path
+6. mark the mount as managed and synced
+
+The canonical library copy may keep generic command text, but the mounted `SKILL.md` must be target-specific output.
+
+This means built-in automation skills should not rely on a pure symlink mount. Their final mounted `SKILL.md` is target-specific output.
+
+Other non-automation skills can keep the current symlink/copy behavior.
+
+No new mount-mode enum is required for this phase. Existing `mountModeResolved: "copy"` is sufficient for rendered automation mounts.
+
+## 5. Session-Time Environment Contract
+
+Session startup continues to inject runtime context.
+
+Required runtime env:
+
+- `CODER_STUDIO_SESSION_TOKEN`
+- `CODER_STUDIO_API_URL`
+- `CODER_STUDIO_WORKSPACE_ID`
+
+Built-in automation sessions should also inject an internal launcher path, but it is not part of the skill-facing shell contract:
+
+- `CODER_STUDIO_AUTOMATION_ENTRY`
+
+`CODER_STUDIO_AUTOMATION_ENTRY` must be an absolute filesystem path resolved by the server for the current runtime:
+
+- in dev, it can point at the repo source or dev-built entry
+- in packaged/runtime builds, it can point at the shipped dist entry
+- skills never need to know which one they received
+
+This internal env points to the real automation launcher that already resolves dev vs prod and any required repo/dist path differences.
+
+The important boundary is:
+
+- `SKILL.md` does not use `CODER_STUDIO_AUTOMATION_ENTRY` directly
+- `cmd.mjs` may use it internally
+
+## 6. `cmd.mjs` Responsibilities
+
+`cmd.mjs` is a thin launcher with shared behavior across built-in automation skills.
+
+It must:
+
+- read required runtime env
+- fail clearly if the required env is missing
+- require `CODER_STUDIO_AUTOMATION_ENTRY` for built-in automation sessions
+- delegate to the real automation backend entry by invoking `process.execPath` with the resolved entry path and the original argv payload
+- forward stdout/stderr and exit code
+- avoid any fallback to PATH-based `coder-studio`
+
+It must not:
+
+- guess the current server from PM2/runtime config
+- call a global `coder-studio` command
+- require shell-specific setup in `SKILL.md`
+- parse backend-specific schemas itself
+
+## 7. Internal Automation Backend Entry
+
+The skill bridge is not the real automation client.
+
+The real execution path remains an internal Coder Studio automation entry that reuses the existing websocket command infrastructure.
+
+Recommended internal layering:
+
+1. `SKILL.md` invokes mounted `cmd.mjs`
+2. `cmd.mjs` reads runtime env and delegates
+3. the delegated entry parses dotted op syntax such as `memory.create` and reuses the existing automation websocket client
+4. backend continues to receive the same `memory.create`, `canvas.create`, and related ops
+
+This preserves the existing transport and permission model.
+
+No new public CLI name is required.
+
+The delegated entry must operate in session-scoped mode only:
+
+- it uses injected `CODER_STUDIO_API_URL`
+- it uses injected `CODER_STUDIO_SESSION_TOKEN`
+- it must not fall back to managed-server discovery, global status files, or PATH resolution
+
+This keeps agent automation bound to the exact workspace session that mounted the skill.
+
+## 8. Built-in Skill Content Changes
+
+The following built-in skills should be migrated in this phase:
+
+- `coder-studio-memory`
+- `coder-studio-canvas`
+- `coder-studio-open`
+
+Required content changes:
+
+- remove `coder-studio ...` command examples
+- remove PATH-based fallback guidance
+- remove shell-specific env-expansion examples as the primary contract
+- switch to `node "<absolute-cmd-path>/cmd.mjs" ...`
+- align command examples with current backend operation names
+
+For memory specifically:
+
+- stop teaching `memory add`
+- teach `memory.create`
+- keep source attribution explicit in examples, for example `--skill coder-studio-memory`, rather than adding skill-specific logic into the shared launcher
+
+## 9. Failure Behavior
+
+The mounted bridge should fail fast and clearly in these cases:
+
+- `node` is unavailable
+- `CODER_STUDIO_SESSION_TOKEN` is missing
+- `CODER_STUDIO_API_URL` is missing
+- `CODER_STUDIO_WORKSPACE_ID` is missing
+- `CODER_STUDIO_AUTOMATION_ENTRY` is missing
+- the delegated internal automation entry is unavailable
+
+Example error direction:
+
+`Coder Studio automation is not available in this session. Missing CODER_STUDIO_API_URL or session token.`
+
+The bridge must not silently fall back to:
+
+- `coder-studio`
+- `npx coder-studio`
+- local server discovery
+
+## 10. Testing
+
+Add coverage for:
+
+- built-in skill definitions can materialize extra files
+- built-in automation skills include `cmd.mjs`
+- mount renders `SKILL.md` with the final provider target path
+- rendered `SKILL.md` references `join(targetPath, "cmd.mjs")`
+- session env includes required runtime context
+- `cmd.mjs` fails clearly when runtime env is missing
+- `cmd.mjs` delegates to the internal automation entry and preserves exit status
+- Windows dev sessions no longer depend on resolving a global `coder-studio` binary
+- built-in memory skill content no longer references `memory add`
+- rendered automation mounts are recorded as `copy`
+
+## Risks
+
+- Mount-rendered skills cannot use a pure symlink flow, which increases mount implementation complexity.
+- Absolute paths embedded in `SKILL.md` become stale if a mounted target moves without a re-sync.
+- The bridge depends on `node` being present in the agent environment.
+- If session secrets leak into mounted skill files, the design fails its security boundary.
+- Dotted op syntax is less human-friendly than the public CLI shape, but that is acceptable because this contract is for mounted agent automation, not end users.
+
+## Phase-One Decisions
+
+- Built-in automation mounts use existing `mountModeResolved: "copy"`; no new mount enum is added.
+- Phase one supports dotted op syntax only, such as `memory.create` and `ui.open-file`.
+- The shared `cmd.mjs` stays transport-only; it does not inject skill-specific memory metadata automatically.
diff --git a/docs/superpowers/specs/2026-06-23-canvas-file-first-design.md b/docs/superpowers/specs/2026-06-23-canvas-file-first-design.md
new file mode 100644
index 000000000..7f8e5e055
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-23-canvas-file-first-design.md
@@ -0,0 +1,332 @@
+# Canvas File-First Design
+
+> Status: Draft for user review
+> Date: 2026-06-23
+> Scope: `packages/core`, `packages/server`, `packages/web`, `packages/cli`
+
+## Problem
+
+The current canvas model is still artifact-first:
+
+- canvas source is stored as `.coder-studio/canvases/<canvas-id>.canvas.json`
+- render flow is keyed by `canvasId`
+- the editor opens a dedicated `canvas` tab that points back to a source file
+- source editing and rendered viewing are related, but they are not modeled as the same file-first resource
+
+This causes three problems:
+
+- canvas does not behave like a normal workspace file
+- manual open flows need canvas-specific entry points or commands
+- future editing features risk splitting into two identities: a source file and a separate rendered artifact
+
+The user wants to move canvas to a file-first model:
+
+- the real source of truth is a workspace file
+- opening that file should default to rendered canvas view
+- source editing should operate on the same file
+- rename and delete semantics should match normal file behavior
+- this phase should not implement future drawing or exported image features yet
+
+## Goals
+
+- Make canvas a file-first document type backed by `.csc` files.
+- Treat `.csc` as the single source of truth for canvas content.
+- Open `.csc` files into a rendered canvas view by default.
+- Keep source editing available for the same `.csc` file.
+- Remove `canvasId` as a required user-facing or render-time identity.
+- Align rename and delete behavior with current normal file handling.
+- Require meaningful human-readable canvas names at creation time so users can tell what a canvas is for from the tab title, list view, and file name.
+- Preserve future compatibility with richer direct canvas editing.
+
+## Non-Goals
+
+- Do not add drawing, brush, selection, masking, or image annotation tools in this phase.
+- Do not implement automatic exported PNG generation for agent consumption in this phase.
+- Do not generalize the editor into a reusable framework for every future rendered document type yet.
+- Do not keep a separate artifact identity model just for backward familiarity.
+- Do not add a new dedicated “manual open canvas” button or panel in this phase.
+
+## Current Context
+
+Relevant current behavior:
+
+- Canvas files are created under `.coder-studio/canvases/<canvas-id>.canvas.json`.
+- `canvas.open` opens a non-file editor tab carrying `canvasId`, `artifactType`, and `sourcePath`.
+- The canvas surface renders through `/embedded/canvas/:workspaceId/:canvasId`.
+- The canvas surface already exposes `Open Source` and `Refresh`, but source editing opens a separate file tab.
+- Standard file rename behavior in the workspace rewrites active/open editor paths instead of treating rename as delete-plus-create.
+
+Relevant files:
+
+- `packages/core/src/domain/canvas.ts`
+- `packages/core/src/domain/types.ts`
+- `packages/core/src/domain/ui-actions.ts`
+- `packages/server/src/canvas/service.ts`
+- `packages/server/src/commands/canvas.ts`
+- `packages/server/src/commands/ui-actions.ts`
+- `packages/server/src/routes/canvas.ts`
+- `packages/web/src/features/code-editor/views/shared/canvas-surface.tsx`
+- `packages/web/src/features/code-editor/views/shared/editor-surface.tsx`
+- `packages/web/src/features/ui-actions/use-ui-action-subscription.ts`
+- `packages/web/src/features/workspace/actions/use-file-actions.ts`
+- `packages/web/src/features/workspace/actions/use-open-workspace-file.ts`
+
+## User Decisions Captured
+
+- Canvas should move to a file-first model now rather than keep the current id-first model.
+- `.csc` should be the real canvas source file, not a pointer file that only stores an id.
+- Opening a `.csc` file should default to rendered canvas view.
+- Source editing and rendered viewing should refer to the same file.
+- Rename semantics should follow the existing normal editor/file rename behavior.
+- Canvas creation should use meaningful user-visible names rather than generic placeholders so users can find the right canvas later.
+- Future direct canvas editing should remain compatible with this model.
+- Future agent reading can rely on an automatically updated final image, but that is explicitly out of scope for this phase.
+
+## Approaches Considered
+
+### Option A: Keep the current artifact-first model and add more manual entry points
+
+Pros:
+
+- Lowest short-term implementation cost
+- Reuses current `canvasId` infrastructure
+
+Cons:
+
+- Canvas still does not behave like a normal file
+- Source and render remain split identities
+- Future editing features would need another migration
+
+Decision: reject.
+
+### Option B: File-first `.csc`, but keep `canvasId` as the primary render identity
+
+Pros:
+
+- Smaller migration than fully removing id-based render paths
+- Preserves more current behavior
+
+Cons:
+
+- Still models the same canvas as both a file and a separate artifact
+- Keeps unnecessary metadata synchronization
+- Rename and file-open flows stay more complex than needed
+
+Decision: reject.
+
+### Option C: Fully file-first `.csc`, render by `sourcePath`, remove required `canvasId`
+
+Pros:
+
+- Cleanest user and system model
+- Canvas becomes a normal workspace file with a custom renderer
+- Source and render are two views of one resource
+- Best base for future direct canvas editing
+
+Cons:
+
+- Requires broader changes across server, web, and command surfaces
+
+Decision: accept.
+
+## Final Design
+
+## 1. File Model
+
+Canvas source files become real workspace files with the `.csc` extension.
+
+The `.csc` file remains the only source of truth. It stores the full canvas document envelope, not a pointer to another artifact.
+
+Example path:
+
+- `.coder-studio/canvases/runtime-flow.csc`
+
+The current JSON-based envelope shape can remain in v1, but the file extension changes and the model is explicitly file-first.
+
+Creation naming rules:
+
+- Every canvas create flow must provide a meaningful title that describes the canvas content, such as `Runtime Request Flow` or `Workspace Audit Summary`.
+- Generic titles such as `Canvas`, `Diagram`, `Architecture`, `Untitled`, or id-like placeholder names should not be used by agent-driven create flows.
+- The initial `.csc` file path should be derived from that title by slugifying it, for example `Runtime Request Flow` -> `.coder-studio/canvases/runtime-request-flow.csc`.
+- If the slug already exists, the create flow should keep the readable base name and append a numeric suffix, for example `runtime-request-flow-2.csc`.
+- Editing the title inside the `.csc` document does not automatically rename the file path. File rename remains an explicit workspace file operation, matching normal file behavior.
+
+## 2. Identity Model
+
+Render identity moves from `canvasId` to `sourcePath`.
+
+The system should treat a canvas as:
+
+- workspace id
+- source path
+
+This pair is sufficient for:
+
+- opening render view
+- refreshing render
+- restoring editor state
+- rename propagation
+- delete handling
+
+`canvasId` is removed from the primary runtime model for this feature. If compatibility shims are temporarily needed during migration, they stay internal and should not remain part of the intended steady-state API.
+
+## 3. Opening Behavior
+
+Opening a `.csc` file through normal file flows should default to rendered canvas view rather than plain text source view.
+
+This includes:
+
+- explorer click
+- quick open / open file flows
+- drag-and-drop open flows that resolve to a workspace file path
+
+The rendered view should still expose source access for the same file.
+
+Initial phase behavior:
+
+- default open target for `.csc`: render view
+- explicit source access: `Open Source` from the canvas surface
+
+Future work may replace `Open Source` with a stronger `Render / Source` toggle, but that is not required now.
+
+## 4. Editor Tab Model
+
+Canvas tabs remain a non-file editor tab in the current editor architecture, but they become file-addressed rather than artifact-addressed.
+
+Expected tab shape after migration:
+
+```ts
+interface WorkspaceCanvasEditorTab {
+  kind: "canvas";
+  id: `canvas:${sourcePath}`;
+  sourcePath: string;
+  title: string;
+}
+```
+
+The tab should not require `canvasId` or artifact metadata to render.
+
+The path row and persistence model should treat the canvas tab as belonging to the `.csc` file it represents.
+
+## 5. Render Flow
+
+Render requests and embedded routes should take `sourcePath` instead of `canvasId`.
+
+Target flow:
+
+- open `.csc`
+- construct canvas editor tab keyed by `sourcePath`
+- render through a route and command surface addressed by `workspaceId + sourcePath`
+- read and validate the `.csc` file
+- compile and display the rendered canvas
+
+Expected route direction:
+
+- current: `/embedded/canvas/:workspaceId/:canvasId`
+- target: `/embedded/canvas/:workspaceId?sourcePath=<percent-encoded-workspace-relative-path>`
+
+The same query-based addressing should be used for the data route:
+
+- target: `/api/canvas/:workspaceId/data?sourcePath=<percent-encoded-workspace-relative-path>`
+
+## 6. Server Responsibilities
+
+Server canvas handling changes from record-first to source-file-first:
+
+- create canvas writes a `.csc` file
+- render reads by `sourcePath`
+- open-canvas style APIs become compatibility shims or are removed
+- file-backed validation remains server-owned
+- compile remains server-owned
+
+This phase should prefer these command shapes:
+
+- `canvas.render` requires `workspaceId + sourcePath`
+- file open flows trigger render view for `.csc`
+
+Any remaining repo or record layer should be treated as optional cache/compatibility infrastructure, not the canonical model.
+
+## 7. Rename and Delete Semantics
+
+Canvas files should follow the same semantics as ordinary file rename/delete handling.
+
+Rename:
+
+- rename of a `.csc` file is treated as the same file moving to a new path
+- open render tabs follow the new path
+- source tabs follow the new path
+- active state and persisted UI state are rewritten to the new path
+
+Delete:
+
+- delete of a `.csc` file closes any render tab for that path
+- delete of a `.csc` file closes any source tab for that path
+
+This avoids special-case “delete then recreate” semantics and keeps behavior aligned with the rest of the editor.
+
+## 8. Compatibility With Future Direct Canvas Editing
+
+This model is intentionally compatible with future in-canvas editing.
+
+Future direct manipulation features such as brush strokes, selections, or annotations should update the `.csc` source document rather than a separate artifact identity.
+
+That keeps:
+
+- rendered view
+- source view
+- future export or derived image generation
+
+all anchored to one file.
+
+This phase does not implement those features, but it must not block them.
+
+## 9. CLI and UI Action Direction
+
+The long-term preferred open path becomes normal file open behavior for `.csc`.
+
+Implications:
+
+- `ui open-canvas` no longer needs to be the primary user-facing or agent-facing path
+- `ui open-file --path <file>.csc` can become sufficient once `.csc` opens into render view by default
+
+Short-term compatibility is acceptable, but the target state is that canvas behaves like a file type, not like a separate workspace artifact class.
+
+## 10. Builtin Skill Guidance
+
+The builtin canvas skill and any related agent instructions should explicitly require meaningful names when creating canvases.
+
+Required guidance:
+
+- When calling `coder-studio canvas create`, always pass a specific `--title` that tells the user what the canvas represents.
+- Prefer concise descriptive names such as `Runtime Request Flow`, `Agent Tooling Overview`, or `Workspace Audit Summary`.
+- Do not create canvases with placeholder names such as `Canvas`, `Diagram`, `Architecture`, `New Canvas`, or timestamp-only labels.
+- The reason for this rule is user-facing discoverability: the canvas title and derived file name should make it obvious what the canvas is for in tabs, lists, and file explorers.
+
+## Testing
+
+Required verification coverage:
+
+- canvas creation with a meaningful title produces a readable `.csc` path and preserves the intended title
+- `.csc` files open into render view from normal file-open flows
+- `Open Source` opens the same `.csc` file in text mode
+- render refresh reads by `sourcePath`
+- editor tab persistence restores canvas tabs by `sourcePath`
+- rename of `.csc` rewrites render/source tab state like ordinary files
+- delete of `.csc` closes render/source tab state
+- server render route rejects invalid or missing `.csc` files with clear errors
+
+## Risks
+
+- Current canvas code assumes `canvasId` in multiple places; migration needs careful end-to-end updates.
+- Existing persisted canvas tabs may need normalization if older state still contains `canvasId`-based entries.
+- Drag-and-drop behavior needs care if some flows bypass normal open-file routing.
+
+## Rollout Recommendation
+
+Implement this as a focused migration in one pass:
+
+1. Move server render/read paths to `sourcePath`.
+2. Change canvas source file extension and creation/update behavior to `.csc`.
+3. Make `.csc` open through render view in the editor.
+4. Update canvas tab persistence and rename/delete handling to be path-based.
+5. Leave future exported image generation and direct drawing features for a later phase.
diff --git a/docs/superpowers/specs/2026-06-24-terminal-profiles-design.md b/docs/superpowers/specs/2026-06-24-terminal-profiles-design.md
new file mode 100644
index 000000000..49fe2eae4
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-24-terminal-profiles-design.md
@@ -0,0 +1,514 @@
+# Terminal Profiles — Design
+
+> Status: Draft for user review
+> Date: 2026-06-24
+> Scope: `packages/core`, `packages/server`, `packages/web`, terminal settings/tests
+
+## Problem
+
+Coder Studio's shell terminal flow currently has no terminal profile model.
+
+The current behavior is hardcoded in the server:
+
+- shell terminal creation resolves a single default shell in [`packages/server/src/commands/terminal.ts`](../../../packages/server/src/commands/terminal.ts)
+- on Windows that default is `ComSpec` / `cmd.exe`
+- the web terminal toolbar only exposes a single "new terminal" action in [`packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx`](../../../packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx)
+- the terminal create action does not accept a profile identifier in [`packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts`](../../../packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts)
+
+That leaves three product gaps:
+
+1. Windows users are pushed into `cmd.exe` even when they prefer PowerShell, Git Bash, or WSL.
+2. There is no VS Code style split between "open default terminal quickly" and "pick a different terminal when needed".
+3. There is no stable settings model for a default terminal profile or user-defined profiles.
+
+The user wants VS Code style behavior:
+
+- one configured default profile
+- one-click open for the default profile
+- a chooser for opening another profile each time
+- auto-detected profiles plus user-defined custom profiles
+- one cross-platform model, with Windows and WSL handled well in v1
+
+## Goals
+
+- Introduce a unified terminal profile model for Windows, macOS, and Linux.
+- Make the server the single source of truth for detected, custom, and resolved default profiles.
+- Add a VS Code style split-button entry for new terminals on desktop.
+- Add a mobile-friendly chooser flow that preserves the same default-plus-picker mental model.
+- Allow users to configure a global default terminal profile.
+- Allow users to create, edit, and delete custom profiles.
+- Support detected WSL distro profiles on Windows.
+- Keep terminal creation server-validated instead of letting the client construct arbitrary shell invocations.
+
+## Non-Goals
+
+- Do not redesign the full workspace runtime model in this phase.
+- Do not make terminal profiles workspace-specific in v1.
+- Do not implement split terminal, debug terminal, or task-profile integrations in v1.
+- Do not import or mirror the user's local VS Code terminal settings automatically.
+- Do not expose profile-level environment variable editing in v1.
+- Do not rebuild the settings navigation structure around a new top-level terminal section.
+- Do not silently substitute a different shell when the user explicitly selected an unavailable profile.
+
+## Current Context
+
+Relevant current behavior:
+
+- `terminal.create` resolves one shell directly on the server and does not accept profile selection.
+- the terminal toolbar has one create action but no profile dropdown.
+- terminal settings today cover renderer, copy-on-select, and font size, but no profile settings.
+- the settings command schema already supports nested top-level groups, so a new `terminal.*` namespace is feasible in [`packages/server/src/commands/settings.ts`](../../../packages/server/src/commands/settings.ts)
+- workspace metadata already includes `targetRuntime` and `wslDistro` in [`packages/core/src/domain/types.ts`](../../../packages/core/src/domain/types.ts), but the current workspace open flow still defaults to native runtime in [`packages/server/src/commands/workspace.ts`](../../../packages/server/src/commands/workspace.ts)
+- runtime binding also does not currently distinguish WSL in [`packages/server/src/server.ts`](../../../packages/server/src/server.ts)
+
+Relevant files:
+
+- `packages/core/src/domain/types.ts`
+- `packages/server/src/commands/terminal.ts`
+- `packages/server/src/commands/settings.ts`
+- `packages/server/src/provider-runtime/command-check.ts`
+- `packages/server/src/workspace/runtime-check.ts`
+- `packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx`
+- `packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts`
+- `packages/web/src/features/terminal-panel/actions/use-terminal-actions.ts`
+- `packages/web/src/features/settings/components/settings-page.tsx`
+
+## User Decisions Captured
+
+- Match the VS Code model: keep a default profile and also let the user choose another profile when opening a terminal.
+- Build one cross-platform terminal profile model instead of a Windows-only one.
+- Prioritize Windows behavior first.
+- Use auto-detected profiles plus user-defined custom profiles.
+- Treat WSL as part of the terminal profile system for this phase.
+- Prefer the server-owned architecture over a client-owned shell-command model.
+- Keep the current settings page structure and add terminal profile controls into the existing general terminal settings area.
+
+## Approaches Considered
+
+### Option A: Client-owned profiles and shell command construction
+
+The web client would detect profiles, store profile metadata, and send raw shell commands to the server when creating a terminal.
+
+Pros:
+
+- quick to prototype
+- minimal server-side surface expansion
+
+Cons:
+
+- duplicates platform-specific detection logic in the client
+- pushes Windows, Git Bash, and WSL path handling into the browser layer
+- weakens server-side validation
+- makes tests and future desktop/mobile parity harder
+
+Decision: reject.
+
+### Option B: Server-owned terminal profile registry with client chooser support
+
+The server detects built-in profiles, merges them with custom profiles, resolves a default profile, and creates terminals from a `profileId`. The client renders the picker and settings UI.
+
+Pros:
+
+- one authority for profile detection and resolution
+- preserves server-side validation and platform-specific logic
+- keeps the client thin
+- fits the existing `settings.get/settings.update` pattern
+- makes WSL and Windows path handling testable on the server
+
+Cons:
+
+- requires new command surfaces and DTOs
+- requires a small amount of settings model expansion
+
+Decision: accept.
+
+### Option C: Full VS Code parity in one phase
+
+This would include split terminal, debug terminal, task terminal profile routing, per-workspace defaults, profile icons and ordering semantics, and deep runtime integration.
+
+Pros:
+
+- most complete long-term model
+
+Cons:
+
+- much larger than the user request
+- entangles terminal profile work with unrelated terminal subsystems
+- increases regression risk significantly
+
+Decision: reject for this phase.
+
+## Final Choice
+
+Adopt Option B.
+
+This phase introduces a server-owned terminal profile registry and resolution flow, with the web client consuming that model for terminal creation and settings management. The product outcome matches the requested VS Code behavior without coupling the work to a wider runtime redesign.
+
+## Final Design
+
+### 1. Core DTOs
+
+Add a new terminal profile DTO to `@coder-studio/core`.
+
+Recommended shape:
+
+```ts
+export type TerminalProfileSource = "detected" | "custom";
+export type TerminalProfileRuntime = "native" | "wsl";
+
+export interface TerminalProfile {
+  id: string;
+  label: string;
+  source: TerminalProfileSource;
+  runtime: TerminalProfileRuntime;
+  icon: string;
+}
+
+export interface TerminalProfilesListResult {
+  profiles: TerminalProfile[];
+  configuredDefaultProfileId?: string;
+  resolvedDefaultProfileId: string | null;
+}
+```
+
+Notes:
+
+- `id` must be stable and opaque to the client.
+- `icon` is a semantic token or small identifier, not a raw asset path.
+- the DTO intentionally excludes launch-time internals such as `command`, `args`, or `env`.
+
+### 2. Settings Model
+
+Introduce a new top-level `terminal` settings namespace instead of putting profile selection under `appearance`.
+
+Recommended persisted shape:
+
+```ts
+terminal: {
+  defaultProfileId?: string;
+  profiles?: Array<{
+    id: string;
+    label: string;
+    command: string;
+    args?: string[];
+    icon?: string;
+  }>;
+}
+```
+
+Rules:
+
+- `terminal.defaultProfileId` stores the user's preferred profile id.
+- `terminal.profiles` stores only custom profiles.
+- detected profiles are not persisted into settings.
+- custom profile ids are generated once and stay stable across label edits.
+
+Validation rules:
+
+- `label` is required and non-empty.
+- `command` is required and non-empty.
+- `args`, if present, must be a string array.
+- duplicate custom ids are rejected.
+
+Why top-level `terminal`:
+
+- profile selection is a runtime launch concern, not a visual appearance preference
+- keeping it out of `appearance.*` avoids semantic drift as the feature grows
+
+### 3. Stable Profile Id Rules
+
+Detected profiles should use stable generated ids:
+
+- `detected:win:pwsh`
+- `detected:win:powershell`
+- `detected:win:cmd`
+- `detected:win:git-bash`
+- `detected:win:wsl:Ubuntu-24.04`
+- `detected:posix:zsh`
+- `detected:posix:bash`
+
+Custom profiles should use:
+
+- `custom:<generated-id>`
+
+This keeps `defaultProfileId` stable even when labels are renamed for display.
+
+### 4. Server Profile Registry
+
+Add a dedicated server module for terminal profiles, for example:
+
+- `packages/server/src/terminal-profiles/index.ts`
+- `packages/server/src/terminal-profiles/detect.ts`
+- `packages/server/src/terminal-profiles/resolve.ts`
+
+Responsibilities:
+
+- detect built-in and system-available profiles for the current host platform
+- read custom profiles from settings
+- merge detected and custom profiles
+- resolve the active default profile
+- translate `profileId` into a concrete terminal spawn spec
+
+The registry should be the only place that knows:
+
+- how a profile is detected
+- how a profile is launched
+- how Windows and WSL cwd mapping works
+
+### 5. Detection Strategy
+
+Detection uses the existing command availability infrastructure in [`packages/server/src/provider-runtime/command-check.ts`](../../../packages/server/src/provider-runtime/command-check.ts).
+
+#### Windows
+
+Detect in this order:
+
+- `pwsh`
+- `powershell`
+- `cmd` / `ComSpec`
+- Git Bash via `bash` or known Git install paths
+- `wsl`
+
+If `wsl` is available:
+
+- run `wsl -l -q`
+- trim empty lines
+- emit one detected profile per distro, such as `Ubuntu-24.04 (WSL)`
+
+Recommended default resolution order on Windows:
+
+1. `pwsh`
+2. `powershell`
+3. `cmd`
+4. first detected Git Bash
+5. first detected WSL distro
+
+#### macOS and Linux
+
+Detect:
+
+- current `$SHELL`
+- `zsh`
+- `bash`
+- `fish`
+- `pwsh`
+
+Then de-duplicate by launch identity and keep the current shell first if available.
+
+Recommended default resolution order on POSIX:
+
+1. current `$SHELL`
+2. `zsh`
+3. `bash`
+4. `fish`
+5. `pwsh`
+
+### 6. New and Updated Commands
+
+#### `terminal.profiles.list`
+
+Add a new runtime command:
+
+```ts
+terminal.profiles.list({ workspaceId })
+```
+
+Response:
+
+- `profiles`
+- `configuredDefaultProfileId`
+- `resolvedDefaultProfileId`
+
+Behavior:
+
+- profile availability is computed at request time
+- if a configured default is unavailable, keep reporting it in `configuredDefaultProfileId`
+- `resolvedDefaultProfileId` must point to a real available profile or `null`
+
+#### `terminal.create`
+
+Extend the existing `terminal.create` input with:
+
+```ts
+profileId?: string
+```
+
+Behavior:
+
+- if `profileId` is omitted, create using `resolvedDefaultProfileId`
+- if `profileId` is present but unavailable, return an explicit error
+- do not silently fall back when the user explicitly selected a profile
+- preserve the current `cwdPath`, `cols`, `rows`, and `themeBackground` handling
+
+### 7. Launch Resolution
+
+The profile registry resolves `profileId` into a launch spec used by the terminal manager.
+
+Examples:
+
+- `PowerShell`: `["pwsh"]` or `["powershell.exe"]`
+- `Command Prompt`: `[resolvedComSpec]`
+- `Git Bash`: `[resolvedPathToBash]`
+- `WSL distro`: `["wsl.exe", "-d", "<distro>", "--cd", "<mapped-cwd>"]`
+- custom profile: `[command, ...args]`
+
+The terminal title should prefer the profile label rather than a basename-derived shell name. This lets tabs show `PowerShell`, `Git Bash`, or `Ubuntu-24.04 (WSL)` clearly.
+
+### 8. WSL Behavior
+
+For this phase, WSL is treated as a terminal profile family, not as a full workspace runtime integration.
+
+#### CWD mapping
+
+When opening a WSL profile from a Windows-hosted workspace path:
+
+- map `C:\repo\app` to `/mnt/c/repo/app`
+- map drive letters case-insensitively
+- normalize backslashes to slashes
+
+If mapping fails safely:
+
+- fall back to the distro default home directory
+- do not fail terminal creation solely because cwd mapping was impossible
+
+#### Why not bind this to workspace runtime now
+
+The current workspace runtime path is not consistently WSL-aware yet:
+
+- workspace open still defaults to native runtime
+- runtime bindings do not select a distinct WSL runtime id
+
+Bundling that redesign into terminal profiles would make the phase too large. The profile system should therefore stand on its own in v1.
+
+### 9. Client UI
+
+#### Desktop terminal toolbar
+
+Replace the single new-terminal trigger with a VS Code style split button:
+
+- primary button: open the resolved default profile
+- chevron button: open the terminal profile chooser
+
+Chooser content:
+
+- highlighted default item at the top
+- grouped `Detected` and `Custom` sections
+- item click creates a terminal with the selected profile
+- footer action: `Configure Terminal Profiles…`
+
+#### Mobile terminal toolbar
+
+Do not force a desktop-style split button into the constrained mobile header.
+
+Instead:
+
+- the existing create trigger opens a mobile sheet
+- the first item is `Open Default: <profile>`
+- remaining items list the other available profiles
+
+This keeps the same model without overloading the mobile header layout.
+
+### 10. Settings UI
+
+Do not add a new top-level settings section.
+
+Place terminal profile controls into the existing terminal-related area of `GeneralSettings` in [`packages/web/src/features/settings/components/settings-page.tsx`](../../../packages/web/src/features/settings/components/settings-page.tsx).
+
+Add:
+
+- `Default Profile` select
+- `Detected Profiles` read-only list
+- `Custom Profiles` editable list
+- `Add Profile` action
+
+Custom profile editor fields in v1:
+
+- `label`
+- `command`
+- `args`
+
+Do not expose:
+
+- environment variables
+- workspace-scoped overrides
+- icon editing
+
+### 11. Default Resolution and Failure Modes
+
+#### Default resolution
+
+If the configured default profile exists and is available:
+
+- use it
+
+If the configured default profile is missing:
+
+- keep reporting it as `configuredDefaultProfileId`
+- compute a fallback `resolvedDefaultProfileId`
+- let the UI surface a soft warning that the configured default is unavailable
+
+#### Explicit profile creation failure
+
+If the user explicitly chose a profile and it is unavailable or spawn fails:
+
+- return an error
+- show a toast in the UI
+- do not silently switch to another profile
+
+This preserves predictability.
+
+### 12. Architecture
+
+```text
+settings.get / settings.update
+          |
+          v
+server terminal profile registry
+  |- detect built-in/system profiles
+  |- load custom profiles
+  |- resolve default profile
+  |- map profileId -> launch spec
+          |
+          +--> terminal.profiles.list
+          |
+          +--> terminal.create(profileId?)
+                      |
+                      v
+                 TerminalManager.create()
+```
+
+### 13. Testing
+
+#### Server tests
+
+- detected Windows profile list generation
+- `wsl -l -q` parsing
+- default profile resolution when configured default is missing
+- `terminal.create` profile selection and explicit error behavior
+- WSL cwd mapping from Windows paths
+- custom profile settings validation
+
+#### Web tests
+
+- desktop split button primary action opens the resolved default profile
+- desktop chooser renders detected and custom groups
+- mobile create flow shows default-first sheet
+- settings page updates `terminal.defaultProfileId`
+- custom profile create/edit/delete flows
+- explicit profile launch failure shows toast
+
+### 14. Rollout Notes
+
+- adding the new command and DTO surface is backward-compatible with existing terminals as long as `terminal.create` keeps `profileId` optional
+- the toolbar UI can ship once `terminal.profiles.list` is available
+- existing users with no terminal settings should continue to get a resolved default automatically
+- users on Windows should immediately stop being forced into `cmd.exe` when a better default exists
+
+### 15. Future Work
+
+- per-workspace default terminal profiles
+- custom profile environment variables
+- task terminal profile routing
+- split terminal and debug terminal integration
+- deeper workspace runtime and WSL alignment
+- optional import or compatibility mapping from VS Code terminal profile settings
diff --git a/docs/superpowers/specs/2026-06-25-terminal-settings-route-design.md b/docs/superpowers/specs/2026-06-25-terminal-settings-route-design.md
new file mode 100644
index 000000000..5f1406d8c
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-25-terminal-settings-route-design.md
@@ -0,0 +1,151 @@
+# Terminal Settings Route Design
+
+> Status: Draft for review
+
+## Goal
+
+Move all terminal-related settings into a dedicated `Terminal` section under `More > Settings`, remove the legacy `/settings` route, and update terminal entry points to use the canonical `/more/settings/...` paths.
+
+## Scope
+
+This design covers:
+
+- a new `Terminal` settings section placed below `Agents`
+- moving terminal renderer, copy-on-select, terminal profiles, and desktop/mobile terminal font sizes into that section
+- removing the old `/settings` route and any `/settings?...` navigation
+- updating terminal profile entry links and update-details links to canonical `/more/...` routes
+- clarifying terminal profile copy so it reads like a reusable launch preset
+- keeping the settings and more-route tests aligned with the new route map
+
+This design does not cover:
+
+- unrelated settings refactors
+- changes to terminal runtime behavior outside the settings UI
+- new terminal profile features beyond wording and layout cleanup
+
+## Current Architecture
+
+Settings are split across `packages/web/src/features/settings/components/settings-page.tsx`, `settings-sections.tsx`, and `packages/web/src/features/more/*`.
+
+Today, terminal controls are spread across two sections:
+
+- `General` owns terminal renderer, copy-on-select, and terminal profiles
+- `Appearance` owns desktop and mobile terminal font sizes
+
+Route handling is also split:
+
+- `/more/settings/...` is the newer canonical settings surface
+- `/settings` still exists in the shells and a few in-app links
+
+## Requirements
+
+### Functional
+
+1. `Terminal` appears in the settings sidebar after `Agents` and before `Appearance`.
+2. `Terminal` contains terminal renderer, copy-on-select, terminal profiles, and desktop/mobile terminal font sizes.
+3. `General` no longer shows terminal-specific controls.
+4. `/more/settings/terminal` is a valid canonical route.
+5. `/settings` is removed from the shells and no longer used for navigation.
+6. The terminal profile configuration link opens the terminal settings section and anchors to the profile editor.
+7. The update-details footer link opens the canonical about route under `/more`.
+8. The terminal profile default selector stays single-line by using a fixed-width control.
+9. The terminal profile help text explains that custom configs are reusable terminal launch presets.
+
+### Non-functional
+
+1. Route behavior must stay consistent on desktop and mobile.
+2. Existing tests should fail loudly if `/settings` is reintroduced.
+3. The section order must remain stable across the desktop sidebar and mobile section list.
+
+## Proposed Design
+
+### 1. Route model
+
+Make `/more/settings/general`, `/more/settings/terminal`, `/more/settings/appearance`, and `/more/settings/shortcuts` the only public settings routes.
+
+Remove `/settings` from:
+
+- `packages/web/src/shells/desktop-shell.tsx`
+- `packages/web/src/shells/mobile-shell/index.tsx`
+- any in-app links that still point at `/settings`
+
+No redirect alias is retained. A direct `/settings` visit should no longer be treated as a valid settings entrypoint.
+
+### 2. Settings section map
+
+Add `terminal` to the `SettingsSection` union and visible settings registry.
+
+Final visible order:
+
+1. `general`
+2. `providers`
+3. `terminal`
+4. `appearance`
+5. `shortcuts`
+
+`SettingsPage` should render a dedicated `TerminalSettings` section component that owns:
+
+- terminal renderer pills
+- copy-on-select switch
+- terminal profile editor
+- desktop terminal font size input
+- mobile terminal font size input
+
+`GeneralSettings` should keep only general runtime items such as notifications, supervisor controls, language, and LSP mode.
+
+`AppearanceSettings` should keep theme and personalization controls, but no terminal sizing fields.
+
+### 3. More route integration
+
+Add `terminal` to `packages/web/src/features/more/routes.ts` and `page.tsx` so the settings category can resolve `/more/settings/terminal`.
+
+The settings category should keep the same default section behavior:
+
+- `/more/settings` canonicalizes to `/more/settings/general`
+- invalid settings sections canonicalize back to `/more/settings/general`
+
+Update the embedded settings section allow-list so `terminal` can render inside the `More` shell.
+
+### 4. Terminal profile UX
+
+Keep the profile editor anchored at `#terminal-profiles`, but make the entrypoint link point to `/more/settings/terminal#terminal-profiles`.
+
+Update the terminal profile help text so it explicitly explains that custom profiles are reusable terminal launch presets.
+
+Keep the default-profile selector constrained to a fixed width so long labels do not wrap and compress the row layout.
+
+### 5. Related navigation
+
+Update the update rail action that currently opens about details to the canonical `/more/about/update-status` route.
+
+Any other stale `/settings?section=...` links should be converted to `/more/settings/...`.
+
+## Data Flow
+
+1. User opens `More > Settings > Terminal`.
+2. `MoreFeaturesPage` resolves the canonical `/more/settings/terminal` route.
+3. `SettingsPage` renders the terminal section instead of general or appearance terminal controls.
+4. Terminal profile edits persist through the existing settings update flow.
+5. The terminal profile entry link jumps directly to the terminal profile anchor.
+6. Footer update details open the canonical about route under `/more`.
+
+## Error Handling
+
+- If an invalid settings section is requested, route canonicalization should fall back to `/more/settings/general`.
+- If the terminal settings section is missing from the visible registry, the mobile and desktop section-order checks should fail in tests.
+- If the legacy `/settings` route is accidentally reintroduced, shell tests should catch it.
+
+## Testing Strategy
+
+- update `settings-sections` tests to cover the new terminal section order
+- update `settings-page` tests to verify terminal controls live under `Terminal`, not `General` or `Appearance`
+- update `more/page` tests to cover `/more/settings/terminal`
+- update shell tests to assert `/settings` is gone
+- update terminal profile link tests to assert `/more/settings/terminal#terminal-profiles`
+- update footer update rail tests to assert `/more/about/update-status`
+
+## Risks
+
+1. The settings page is large, so moving controls between section components can introduce prop churn if the split is done mechanically.
+2. Removing `/settings` outright may surface stale links in less frequently used flows.
+3. The terminal profile selector width fix can regress if the control is later reused in a narrower container without the fixed-width wrapper.
diff --git a/docs/superpowers/specs/2026-06-25-vscode-preview-tabs-design.md b/docs/superpowers/specs/2026-06-25-vscode-preview-tabs-design.md
new file mode 100644
index 000000000..e7e6251b5
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-25-vscode-preview-tabs-design.md
@@ -0,0 +1,236 @@
+# VSCode Preview Tabs - Design
+
+Date: 2026-06-25
+Status: Draft
+Owner: Codex
+
+## Problem
+
+当前编辑器的文件打开行为更接近“每次打开都追加一条记录”的模式，和 VSCode 的 tab 交互不一致。
+
+用户希望的是：
+
+- 单击文件时，先以 preview 方式打开，复用当前 preview tab
+- 再单击别的文件时，当前 preview tab 的内容被替换
+- 双击文件时，把该文件固定成独立 tab
+- 右键 tab 时，提供和 VSCode 接近的关闭动作
+
+现在的实现里，文件打开会直接落到持久化 open 列表中，`openEditorPaths` 和 `openEditorTabs` 的语义也混在一起，导致无法区分 preview tab 和 pinned tab。
+
+## Goals
+
+- 文件树单击行为改成 VSCode 风格 preview 打开
+- 文件树双击行为改成固定 tab
+- preview tab 在首次编辑时自动固定
+- tab 右键提供：
+  - Close
+  - Close Others
+  - Close to the Right
+  - Close Saved
+  - Close All
+  - Keep Open
+- 兼容现有 browser tab 和 canvas tab 行为，不破坏它们的独立语义
+
+## Non-Goals
+
+- 不改 browser tab 的打开模型
+- 不改 canvas tab 的打开模型
+- 不做全局 IDE 命令中心
+- 不新增用户设置项来关闭 preview 模式
+- 不做 inline rename 或拖拽分组
+
+## VSCode Baseline
+
+VSCode 的公开文档说明：
+
+- Explorer 单击文件会进入 preview mode，并复用 preview tab
+- 双击或开始编辑会把文件变成 dedicated tab
+- preview tab 会以斜体标识
+
+官方 tab 右键菜单还包含：
+
+- Close
+- Close Others
+- Close to the Right
+- Close Saved
+- Close All
+- Keep Open / Pin / Unpin
+
+## Proposed Model
+
+给文件 tab 增加固定态字段：
+
+```ts
+interface WorkspaceFileEditorTab {
+  kind: "file";
+  path: string;
+  pinned?: boolean;
+}
+```
+
+约定：
+
+- `pinned: true` 表示固定 tab
+- `pinned` 缺省或 `false` 表示 preview tab
+- 旧数据默认按 pinned 处理，避免历史 workspace 丢状态
+
+## Interaction Rules
+
+### Single Click
+
+文件树单击时：
+
+- 如果当前存在未固定 preview tab，则用新文件替换它
+- 如果目标文件已经以 pinned tab 打开，则只激活该 tab
+- 如果没有 preview tab，也没有 pinned 命中，则创建一个 preview tab
+
+### Double Click
+
+文件树双击时：
+
+- 如果目标文件当前是 preview tab，则直接 pin 它
+- 如果目标文件已经打开，则确保它是 pinned
+- 如果没打开，则新建 pinned tab
+
+### Start Editing
+
+如果用户在 preview tab 中直接修改内容，系统应自动把该 tab 标记为 pinned。
+
+这和 VSCode 的“开始编辑即固定”一致。
+
+### Close
+
+- Close 只关闭当前 tab
+- Close Others 关闭除当前 tab 外的其他 tab
+- Close to the Right 关闭当前 tab 右侧的 tab
+- Close Saved 关闭所有未 dirty 的文件 tab
+- Close All 关闭全部 tab
+- Keep Open 只对 preview tab 显示，点击后把当前 tab 固定
+
+### Dirty Handling
+
+保持现有未保存确认逻辑：
+
+- dirty 文件关闭时仍然弹确认
+- Close Saved 不会关 dirty 文件
+- Close All 会走现有批量关闭确认
+
+## Implementation Shape
+
+### 1. State and Normalization
+
+修改 `packages/web/src/features/workspace/atoms/files.ts` 和
+`packages/web/src/features/workspace/actions/open-editor-state.ts`：
+
+- 为 file tab 增加 `pinned`
+- hydrate / normalize 时兼容旧状态
+- 让 preview tab 和 pinned tab 在持久化里能被区分
+
+### 2. Open Entry Point
+
+修改 `packages/web/src/features/workspace/actions/use-open-workspace-file.ts`：
+
+- 增加打开意图参数，例如 `openDisposition: "preview" | "pinned"`
+- 文件树单击传 preview
+- 文件树双击传 pinned
+- 现有代码里显式调用打开文件的地方，按语义选 preview 或 pinned
+
+### 3. Editor Actions
+
+修改 `packages/web/src/features/code-editor/actions/use-code-editor-actions.ts`：
+
+- 实现 preview tab 替换
+- 实现 pin / unpin
+- 实现点击 tab 的激活逻辑
+- 实现右键菜单所需的批量关闭逻辑
+- 在内容变更时自动 pin preview tab
+
+### 4. UI Surface
+
+修改 `packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx`：
+
+- preview tab 用斜体或等价视觉样式标识
+- tab 上增加右键菜单入口
+- 右键菜单复用文件树已有的菜单交互能力，但命令集合换成 editor tab 语义
+
+修改 `packages/web/src/features/workspace/views/shared/file-tree-panel.tsx`：
+
+- 文件行支持双击
+- 单击保持 preview open
+- 双击执行 pin open
+
+### 5. Menu Layer
+
+建议把当前 `file-context-menu` 的定位和键盘导航能力抽成可复用层，然后 editor tab 菜单和 file tree 菜单共用。
+
+原因是：
+
+- 右键菜单都是坐标锚定
+- 需要一致的键盘/escape/focus 行为
+- 以后如果再扩 editor 级动作，不想再做一套菜单壳
+
+## Approaches Considered
+
+### Option A: 只改文件打开逻辑，tab 右键先不做
+
+优点：
+
+- 改动最小
+- 风险最低
+
+缺点：
+
+- 只解决一半问题
+- 和 VSCode 差异仍然明显
+
+### Option B: Preview / pinned + editor tab 右键菜单同步落地
+
+优点：
+
+- 最接近 VSCode
+- 行为闭环完整
+- 一次把用户感知最强的两个点一起修正
+
+缺点：
+
+- 需要同时动 state、open flow、tab UI、menu
+
+### Option C: 再加设置项和更复杂的 tab 分组策略
+
+优点：
+
+- 可配置性最好
+
+缺点：
+
+- 明显超出当前需求
+- 容易把问题拖成一个更大的 editor 系统改造
+
+## Final Choice
+
+采用 Option B。
+
+原因很直接：这次需求本质上是把编辑器行为对齐到 VSCode，单做 preview 不够，单做右键菜单也不够。两个部分一起做，用户感知才是完整的。
+
+## Testing
+
+重点测试：
+
+- 单击 A 再单击 B，只保留一个 preview tab
+- 双击 B 后，B 变成 pinned
+- preview tab 编辑后自动 pin
+- Close Saved 不关闭 dirty 文件
+- Close to the Right 按顺序关闭右侧 tab
+- 旧 workspace state hydrate 后仍然能正确识别 pinned 文件 tab
+- browser / canvas tab 的行为不被这次改动影响
+
+## Risks
+
+- `openEditorPaths` 和 `openEditorTabs` 当前有一定重叠，改造时要避免两套状态继续互相覆盖
+- 单击和双击的点击序列要处理好，避免双击时先闪出 preview 再被错误持久化
+- 右键菜单如果只做文件 tab 版本，后续可能还会有人想把 browser / canvas tab 一并统一
+
+## References
+
+- VSCode docs preview mode: https://code.visualstudio.com/docs/getstarted/userinterface#_preview-mode
+- VSCode editor title context menu source: https://github.com/microsoft/vscode/blob/main/src/vs/workbench/browser/parts/editor/editor.contribution.ts
diff --git a/e2e-ui/specs/custom-skills-review.spec.ts b/e2e-ui/specs/custom-skills-review.spec.ts
new file mode 100644
index 000000000..a90b4e50f
--- /dev/null
+++ b/e2e-ui/specs/custom-skills-review.spec.ts
@@ -0,0 +1,97 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { expect, type Page, test } from "@playwright/test";
+import { waitForStableScene } from "../fixtures/capture";
+import { openPreviewScene } from "../fixtures/prefs";
+
+const outputDir = path.resolve(process.cwd(), "output/screenshots/custom-skills-review");
+
+async function ensureOutputDir() {
+  await fs.mkdir(outputDir, { recursive: true });
+}
+
+function shot(name: string) {
+  return path.join(outputDir, name);
+}
+
+async function captureSkillsSidebar(page: Page, filename: string) {
+  const panel = page.locator(".left-panel .workspace-sidebar-panel").first();
+  await panel.waitFor({ state: "visible" });
+  await panel.screenshot({
+    path: shot(filename),
+    animations: "disabled",
+    scale: "device",
+  });
+}
+
+async function openSkillsPanel(page: Page) {
+  await page.getByRole("button", { name: "Skills" }).click();
+  await expect(page.getByRole("heading", { level: 2, name: "Custom Skills" })).toBeVisible();
+}
+
+async function openCustomSkillsScene(page: Page) {
+  await ensureOutputDir();
+  await openPreviewScene(page, {
+    sceneId: "workspace-custom-skills-review",
+    device: "desktop",
+    theme: "mint-dark",
+    locale: "en",
+  });
+  await waitForStableScene(page);
+  await openSkillsPanel(page);
+}
+
+test.describe("custom skills review captures", () => {
+  test.beforeEach(async ({ page }, testInfo) => {
+    test.skip(testInfo.project.name !== "desktop", "desktop review only");
+    testInfo.setTimeout(120_000);
+    await openCustomSkillsScene(page);
+  });
+
+  test("capture custom skills list", async ({ page }) => {
+    await expect(page.getByText("Review Ops Skill")).toBeVisible();
+    await expect(page.getByText("Session Audit Helper")).toBeVisible();
+    await captureSkillsSidebar(page, "01-list.png");
+  });
+
+  test("capture custom skill detail", async ({ page }) => {
+    await page.getByText("Review Ops Skill").click();
+    await expect(page.getByRole("heading", { level: 2, name: "Review Ops Skill" })).toBeVisible();
+    await expect(page.getByText("refs")).toBeVisible();
+    await captureSkillsSidebar(page, "02-detail.png");
+  });
+
+  test("capture custom skill create state", async ({ page }) => {
+    await page.getByRole("button", { name: "New Skill" }).click();
+    await page.locator("#custom-skill-name").fill("Launch Check Runner");
+    await page.getByRole("button", { name: "Create" }).last().click();
+    await expect(
+      page.getByRole("heading", { level: 2, name: "Launch Check Runner" })
+    ).toBeVisible();
+    await expect(
+      page.locator(".skills-panel__card-slug").filter({ hasText: "launch-check-runner" })
+    ).toBeVisible();
+    await captureSkillsSidebar(page, "03-created.png");
+  });
+
+  test("capture custom skill edit state", async ({ page }) => {
+    await page.getByText("Review Ops Skill").click();
+    await expect(page.getByRole("heading", { level: 2, name: "Review Ops Skill" })).toBeVisible();
+
+    const filesSection = page
+      .locator(".workspace-sidebar-section")
+      .filter({ has: page.getByRole("heading", { level: 3, name: "Files" }) });
+
+    await filesSection.getByRole("button", { name: "New Folder", exact: true }).click();
+    await page.locator("#custom-skill-path").fill("refs/checklists");
+    await page.getByRole("button", { name: "Create" }).last().click();
+    await page.getByRole("button", { name: "refs", exact: true }).click();
+    await expect(page.getByText("checklists")).toBeVisible();
+
+    await page.getByRole("button", { name: "action.edit refs" }).click();
+    await page.locator("#custom-skill-rename").fill("reference");
+    await page.getByRole("button", { name: "Confirm" }).click();
+    await expect(page.getByText("reference")).toBeVisible();
+    await captureSkillsSidebar(page, "04-edited.png");
+  });
+});
diff --git a/package.json b/package.json
index 8aa716c22..c34144252 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,7 @@
     "publish:cli": "tsx scripts/publish-cli.ts",
     "publish:wiki": "tsx scripts/publish-wiki.ts",
     "ci:lint": "pnpm exec biome check --diagnostic-level=error --max-diagnostics=none .",
-    "ci:test:scripts": "pnpm exec vitest run --config scripts/vitest.config.ts scripts/publish-cli.test.ts scripts/build-cli.test.ts scripts/validate-changesets.test.ts scripts/husky-pre-commit.test.ts --environment node",
+    "ci:test:scripts": "pnpm exec vitest run --config scripts/vitest.config.ts --environment node",
     "ci:test:workspace": "pnpm -r --filter './packages/**' --filter '!@coder-studio/web' --if-present run test && pnpm --filter @coder-studio/web test",
     "ci:test": "pnpm ci:test:scripts && pnpm ci:test:workspace",
     "ci:typecheck": "pnpm --filter @spencer-kit/coder-studio exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/utils exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/core exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/providers exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/server exec tsc -p tsconfig.json --noEmit && pnpm --filter @coder-studio/web exec tsc -p tsconfig.json --noEmit",
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 55896469d..6e6bad386 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -44,6 +44,7 @@
     "fastify": "^5.8.5",
     "ignore": "^7.0.5",
     "markdown-it": "^14.1.0",
+    "mermaid": "^11.15.0",
     "mime-types": "^2.1.35",
     "node-pty": "^1.1.0",
     "pino-pretty": "^13.1.3",
diff --git a/packages/cli/src/automation-client.ts b/packages/cli/src/automation-client.ts
index ada3a683b..1bc23cbcc 100644
--- a/packages/cli/src/automation-client.ts
+++ b/packages/cli/src/automation-client.ts
@@ -1,7 +1,9 @@
 import {
+  AUTOMATION_PERMISSIONS_ENV,
   buildIdentifyResult,
   DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
   listAutomationCapabilities,
+  parseAutomationPermissionsEnv,
 } from "@coder-studio/core";
 
 interface PrintOptions {
@@ -20,10 +22,15 @@ export function printIdentify(options: PrintOptions = {}): void {
 }
 
 export function printCapabilities(options: PrintOptions = {}): void {
+  const scopedPermissionsEnv = process.env[AUTOMATION_PERMISSIONS_ENV];
+  const scopedPermissions = parseAutomationPermissionsEnv(scopedPermissionsEnv);
   const result = {
     version: 1,
     commands: listAutomationCapabilities({
-      permissions: DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
+      permissions:
+        scopedPermissionsEnv === undefined
+          ? DEFAULT_AGENT_AUTOMATION_PERMISSIONS
+          : scopedPermissions,
     }),
   };
 
diff --git a/packages/cli/src/automation-command-client.test.ts b/packages/cli/src/automation-command-client.test.ts
new file mode 100644
index 000000000..4e7d78095
--- /dev/null
+++ b/packages/cli/src/automation-command-client.test.ts
@@ -0,0 +1,179 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { getServerStatus, getBrowserUrl } = vi.hoisted(() => ({
+  getServerStatus: vi.fn(),
+  getBrowserUrl: vi.fn(),
+}));
+
+const { MockWebSocket, socketInstances } = vi.hoisted(() => {
+  const socketInstances: Array<{
+    url: string;
+    options?: { headers?: Record<string, string> };
+    handlers: Map<string, Array<(...args: any[]) => void>>;
+    send: ReturnType<typeof vi.fn>;
+    close: ReturnType<typeof vi.fn>;
+    emit: (event: string, ...args: any[]) => void;
+  }> = [];
+
+  class MockWebSocket {
+    static readonly OPEN = 1;
+
+    readonly handlers = new Map<string, Array<(...args: any[]) => void>>();
+    readonly send = vi.fn();
+    readonly close = vi.fn();
+
+    constructor(
+      public readonly url: string,
+      public readonly options?: { headers?: Record<string, string> }
+    ) {
+      socketInstances.push(this);
+      queueMicrotask(() => this.emit("open"));
+    }
+
+    on(event: string, handler: (...args: any[]) => void): void {
+      const handlers = this.handlers.get(event) ?? [];
+      handlers.push(handler);
+      this.handlers.set(event, handlers);
+    }
+
+    emit(event: string, ...args: any[]): void {
+      for (const handler of this.handlers.get(event) ?? []) {
+        handler(...args);
+      }
+    }
+  }
+
+  return { MockWebSocket, socketInstances };
+});
+
+vi.mock("./server-control.js", () => ({
+  getServerStatus,
+}));
+
+vi.mock("./server-url.js", () => ({
+  getBrowserUrl,
+}));
+
+vi.mock("ws", () => ({
+  default: MockWebSocket,
+}));
+
+import { callCoderStudioCommand } from "./automation-command-client.js";
+
+describe("automation command client", () => {
+  beforeEach(() => {
+    socketInstances.length = 0;
+    vi.stubEnv("CODER_STUDIO_API_URL", "");
+    getServerStatus.mockResolvedValue({
+      status: "running",
+      pid: 1,
+      host: "127.0.0.1",
+      port: 4173,
+      restartCount: 0,
+      outFile: "/tmp/server.out.log",
+      errFile: "/tmp/server.err.log",
+      startedAt: 1,
+    });
+    getBrowserUrl.mockReturnValue("http://127.0.0.1:4173");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  it("sends a bearer authorization header when a session token is present", async () => {
+    vi.stubEnv("CODER_STUDIO_SESSION_TOKEN", "session-token-123");
+
+    const pending = callCoderStudioCommand({
+      op: "git.status",
+      args: { workspaceId: "ws-1" },
+    });
+
+    await vi.waitFor(() => {
+      expect(socketInstances).toHaveLength(1);
+    });
+
+    const socket = socketInstances[0]!;
+    expect(socket?.url).toBe("ws://127.0.0.1:4173/ws");
+    expect(socket?.options).toEqual({
+      headers: {
+        Authorization: "Bearer session-token-123",
+      },
+    });
+
+    await vi.waitFor(() => {
+      expect(socket.send).toHaveBeenCalledTimes(1);
+    });
+
+    const sentPayload = JSON.parse(socket.send.mock.calls[0]?.[0] as string) as {
+      id: string;
+    };
+    socket.emit(
+      "message",
+      Buffer.from(
+        JSON.stringify({
+          kind: "result",
+          id: sentPayload.id,
+          ok: true,
+          data: { branch: "main" },
+        })
+      )
+    );
+
+    await expect(pending).resolves.toEqual({ branch: "main" });
+  });
+
+  it("opens the websocket without authorization headers when no session token is present", async () => {
+    const pending = callCoderStudioCommand({
+      op: "workspace.list",
+      args: {},
+    });
+
+    await vi.waitFor(() => {
+      expect(socketInstances).toHaveLength(1);
+    });
+
+    const socket = socketInstances[0]!;
+    expect(socket?.options).toBeUndefined();
+
+    await vi.waitFor(() => {
+      expect(socket.send).toHaveBeenCalledTimes(1);
+    });
+
+    const sentPayload = JSON.parse(socket.send.mock.calls[0]?.[0] as string) as {
+      id: string;
+    };
+    socket.emit(
+      "message",
+      Buffer.from(
+        JSON.stringify({
+          kind: "result",
+          id: sentPayload.id,
+          ok: true,
+          data: [],
+        })
+      )
+    );
+
+    await expect(pending).resolves.toEqual([]);
+  });
+
+  it("rejects session-scoped calls when CODER_STUDIO_API_URL is unavailable without falling back to managed-server discovery", async () => {
+    vi.stubEnv("CODER_STUDIO_API_URL", "");
+    getServerStatus.mockClear();
+    getBrowserUrl.mockClear();
+
+    await expect(
+      callCoderStudioCommand({
+        op: "workspace.list",
+        args: {},
+        resolveStrategy: "session",
+      })
+    ).rejects.toThrow(/CODER_STUDIO_API_URL/);
+
+    expect(getServerStatus).not.toHaveBeenCalled();
+    expect(getBrowserUrl).not.toHaveBeenCalled();
+    expect(socketInstances).toHaveLength(0);
+  });
+});
diff --git a/packages/cli/src/automation-command-client.ts b/packages/cli/src/automation-command-client.ts
index 9191363c8..6ef4fd479 100644
--- a/packages/cli/src/automation-command-client.ts
+++ b/packages/cli/src/automation-command-client.ts
@@ -8,6 +8,7 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
 
 export interface CoderStudioCommandInput {
   apiUrl?: string;
+  resolveStrategy?: "auto" | "session";
   op: string;
   args: unknown;
   timeoutMs?: number;
@@ -33,13 +34,23 @@ function toWebSocketUrl(apiUrl: string): string {
   return url.toString();
 }
 
-async function resolveApiUrl(explicitApiUrl: string | undefined): Promise<string> {
+async function resolveApiUrl(
+  explicitApiUrl: string | undefined,
+  resolveStrategy: "auto" | "session" = "auto"
+): Promise<string> {
   if (explicitApiUrl) {
     return explicitApiUrl;
   }
 
-  if (process.env.CODER_STUDIO_API_URL) {
-    return process.env.CODER_STUDIO_API_URL;
+  const envApiUrl = process.env.CODER_STUDIO_API_URL?.trim();
+  if (envApiUrl) {
+    return envApiUrl;
+  }
+
+  if (resolveStrategy === "session") {
+    throw new Error(
+      "Session-scoped automation requires CODER_STUDIO_API_URL to be set or passed explicitly."
+    );
   }
 
   const status = await getServerStatus();
@@ -73,13 +84,22 @@ function parseResultMessage(data: WebSocket.RawData): Result | null {
 export async function callCoderStudioCommand<T = unknown>(
   input: CoderStudioCommandInput
 ): Promise<T> {
-  const apiUrl = await resolveApiUrl(input.apiUrl);
+  const apiUrl = await resolveApiUrl(input.apiUrl, input.resolveStrategy);
   const wsUrl = toWebSocketUrl(apiUrl);
   const id = randomUUID();
   const timeoutMs = input.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+  const sessionToken = process.env.CODER_STUDIO_SESSION_TOKEN?.trim();
+  const socketOptions =
+    sessionToken && sessionToken.length > 0
+      ? {
+          headers: {
+            Authorization: `Bearer ${sessionToken}`,
+          },
+        }
+      : undefined;
 
   return new Promise<T>((resolve, reject) => {
-    const socket = new WebSocket(wsUrl);
+    const socket = new WebSocket(wsUrl, socketOptions);
     let settled = false;
     const timer = setTimeout(() => {
       finish(() => reject(new Error(`Timed out waiting for ${input.op} result`)));
diff --git a/packages/cli/src/automation-entry.test.ts b/packages/cli/src/automation-entry.test.ts
new file mode 100644
index 000000000..7eae1da27
--- /dev/null
+++ b/packages/cli/src/automation-entry.test.ts
@@ -0,0 +1,178 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { callCoderStudioCommand } = vi.hoisted(() => ({
+  callCoderStudioCommand: vi.fn(),
+}));
+
+vi.mock("./automation-command-client.js", () => ({
+  callCoderStudioCommand,
+}));
+
+import { main } from "./automation-entry.js";
+
+describe("automation entry", () => {
+  beforeEach(() => {
+    vi.stubEnv("CODER_STUDIO_API_URL", "http://127.0.0.1:4173");
+    vi.stubEnv("CODER_STUDIO_WORKSPACE_ID", "ws-1");
+    callCoderStudioCommand.mockResolvedValue({ ok: true });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+    vi.clearAllMocks();
+  });
+
+  it("maps memory.create to the existing websocket command shape in session mode", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main([
+      "memory.create",
+      "--type",
+      "issue",
+      "--content",
+      "Verify memory status forwarding.",
+      "--status",
+      "pending_verification",
+      "--skill",
+      "coder-studio-memory",
+      "--json",
+    ]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: "http://127.0.0.1:4173",
+      resolveStrategy: "session",
+      op: "memory.create",
+      args: {
+        workspaceId: "ws-1",
+        type: "issue",
+        content: "Verify memory status forwarding.",
+        status: "pending_verification",
+        sourceHint: { skillSlug: "coder-studio-memory" },
+      },
+    });
+  });
+
+  it("maps ui.open-file to uiAction.dispatch in session mode", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main([
+      "ui.open-file",
+      "--path",
+      "src/index.ts",
+      "--line",
+      "12",
+      "--column",
+      "3",
+      "--json",
+    ]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: "http://127.0.0.1:4173",
+      resolveStrategy: "session",
+      op: "uiAction.dispatch",
+      args: {
+        workspaceId: "ws-1",
+        intent: {
+          type: "editor.openFile",
+          workspaceId: "ws-1",
+          path: "src/index.ts",
+          line: 12,
+          column: 3,
+        },
+        source: { kind: "agent" },
+      },
+    });
+  });
+
+  it("maps ui.open-canvas to a minimal uiAction.dispatch payload in session mode", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main(["ui.open-canvas", "--canvas", "canvas_123", "--json"]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: "http://127.0.0.1:4173",
+      resolveStrategy: "session",
+      op: "uiAction.dispatch",
+      args: {
+        workspaceId: "ws-1",
+        intent: {
+          type: "canvas.open",
+          workspaceId: "ws-1",
+          canvasId: "canvas_123",
+        },
+        source: { kind: "agent" },
+      },
+    });
+  });
+
+  it("rejects missing ui.open-file path values when the next token is another flag", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await expect(main(["ui.open-file", "--path", "--json"])).rejects.toThrow("Missing path value");
+    expect(callCoderStudioCommand).not.toHaveBeenCalled();
+  });
+
+  it("allows option values that begin with a single dash", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main(["memory.create", "--type", "note", "--content", "- starts with dash", "--json"]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: "http://127.0.0.1:4173",
+      resolveStrategy: "session",
+      op: "memory.create",
+      args: {
+        workspaceId: "ws-1",
+        type: "note",
+        content: "- starts with dash",
+      },
+    });
+  });
+
+  it("maps ui.close-url to uiAction.dispatch in session mode", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main(["ui.close-url", "--url", "https://example.com", "--json"]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: "http://127.0.0.1:4173",
+      resolveStrategy: "session",
+      op: "uiAction.dispatch",
+      args: {
+        workspaceId: "ws-1",
+        intent: {
+          type: "browser.closeUrl",
+          workspaceId: "ws-1",
+          url: "https://example.com",
+        },
+        source: { kind: "agent" },
+      },
+    });
+  });
+
+  it("maps canvas.render with source-path in session mode", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main(["canvas.render", "--source-path", "docs/report.md", "--json"]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: "http://127.0.0.1:4173",
+      resolveStrategy: "session",
+      op: "canvas.render",
+      args: {
+        workspaceId: "ws-1",
+        sourcePath: "docs/report.md",
+      },
+    });
+  });
+
+  it("rejects unsupported automation ops", async () => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await expect(main(["ui.launch-rocket", "--json"])).rejects.toThrow(
+      "Unsupported automation op: ui.launch-rocket"
+    );
+    expect(callCoderStudioCommand).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/cli/src/automation-entry.ts b/packages/cli/src/automation-entry.ts
new file mode 100644
index 000000000..a3b47c626
--- /dev/null
+++ b/packages/cli/src/automation-entry.ts
@@ -0,0 +1,608 @@
+import { pathToFileURL } from "node:url";
+import { callCoderStudioCommand } from "./automation-command-client.js";
+
+type SupportedOp =
+  | "memory.list"
+  | "memory.search"
+  | "memory.get"
+  | "memory.create"
+  | "memory.update"
+  | "memory.delete"
+  | "canvas.list"
+  | "canvas.create"
+  | "canvas.update"
+  | "canvas.render"
+  | "ui.open-file"
+  | "ui.close-file"
+  | "ui.open-url"
+  | "ui.close-url"
+  | "ui.open-canvas";
+
+type CanvasArtifactType = "architecture_canvas" | "report_canvas";
+
+interface SessionEnv {
+  apiUrl: string;
+  workspaceId: string;
+}
+
+interface ParsedEntryCommand {
+  op: string;
+  args: Record<string, unknown>;
+  json: boolean;
+}
+
+function readRequiredEnv(name: "CODER_STUDIO_API_URL" | "CODER_STUDIO_WORKSPACE_ID"): string {
+  const value = process.env[name]?.trim();
+  if (!value) {
+    throw new Error(`Coder Studio automation is not available in this session. Missing ${name}.`);
+  }
+
+  return value;
+}
+
+function readSessionEnv(): SessionEnv {
+  return {
+    apiUrl: readRequiredEnv("CODER_STUDIO_API_URL"),
+    workspaceId: readRequiredEnv("CODER_STUDIO_WORKSPACE_ID"),
+  };
+}
+
+function readOptionValue(argv: string[], index: number, label: string): string {
+  const value = argv[index];
+  if (value === undefined || value.startsWith("--")) {
+    throw new Error(`Missing ${label} value`);
+  }
+
+  return value;
+}
+
+function readPositiveIntegerOption(argv: string[], index: number, label: string): number {
+  const value = readOptionValue(argv, index, label);
+  if (!/^[1-9]\d*$/u.test(value)) {
+    throw new Error(`Invalid ${label} number`);
+  }
+
+  return Number(value);
+}
+
+function parseJsonOption(label: string, value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new Error(
+      `Invalid ${label} JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+function normalizeCanvasArtifactType(value: string): CanvasArtifactType {
+  if (value !== "architecture_canvas" && value !== "report_canvas") {
+    throw new Error("Invalid artifact-type value");
+  }
+
+  return value;
+}
+
+function ensureNoExtraPositionals(positionals: string[]): void {
+  if (positionals.length > 0) {
+    throw new Error(`Unknown argument: ${positionals[0]}`);
+  }
+}
+
+function parseMemoryCommand(
+  op: SupportedOp,
+  argv: string[],
+  workspaceId: string
+): ParsedEntryCommand {
+  let json = false;
+  let query: string | undefined;
+  let memoryId: string | undefined;
+  let memoryType: string | undefined;
+  let content: string | undefined;
+  let status: string | undefined;
+  let skillSlug: string | undefined;
+  const positionals: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === undefined) {
+      continue;
+    }
+
+    switch (arg) {
+      case "--json":
+        json = true;
+        break;
+      case "--type":
+        memoryType = readOptionValue(argv, i + 1, "type");
+        i += 1;
+        break;
+      case "--content":
+        content = readOptionValue(argv, i + 1, "content");
+        i += 1;
+        break;
+      case "--status":
+        status = readOptionValue(argv, i + 1, "status");
+        i += 1;
+        break;
+      case "--skill":
+        skillSlug = readOptionValue(argv, i + 1, "skill");
+        i += 1;
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        positionals.push(arg);
+        break;
+    }
+  }
+
+  if (op === "memory.list") {
+    ensureNoExtraPositionals(positionals);
+    return {
+      op,
+      json,
+      args: {
+        workspaceId,
+        ...(memoryType !== undefined ? { type: memoryType } : {}),
+      },
+    };
+  }
+
+  if (op === "memory.search") {
+    query = positionals[0];
+    if (!query) {
+      throw new Error("Missing query value");
+    }
+    ensureNoExtraPositionals(positionals.slice(1));
+    return {
+      op,
+      json,
+      args: {
+        workspaceId,
+        query,
+        ...(memoryType !== undefined ? { type: memoryType } : {}),
+      },
+    };
+  }
+
+  if (op === "memory.get") {
+    memoryId = positionals[0];
+    if (!memoryId) {
+      throw new Error("Missing memory id value");
+    }
+    ensureNoExtraPositionals(positionals.slice(1));
+    return {
+      op,
+      json,
+      args: { workspaceId, id: memoryId },
+    };
+  }
+
+  if (op === "memory.create") {
+    ensureNoExtraPositionals(positionals);
+    if (!memoryType) {
+      throw new Error("Missing type value");
+    }
+    if (!content) {
+      throw new Error("Missing content value");
+    }
+
+    return {
+      op,
+      json,
+      args: {
+        workspaceId,
+        type: memoryType,
+        content,
+        ...(status !== undefined ? { status } : {}),
+        ...(skillSlug !== undefined ? { sourceHint: { skillSlug } } : {}),
+      },
+    };
+  }
+
+  if (op === "memory.update") {
+    memoryId = positionals[0];
+    if (!memoryId) {
+      throw new Error("Missing memory id value");
+    }
+    ensureNoExtraPositionals(positionals.slice(1));
+    return {
+      op,
+      json,
+      args: {
+        workspaceId,
+        id: memoryId,
+        ...(memoryType !== undefined ? { type: memoryType } : {}),
+        ...(content !== undefined ? { content } : {}),
+        ...(status !== undefined ? { status } : {}),
+      },
+    };
+  }
+
+  memoryId = positionals[0];
+  if (!memoryId) {
+    throw new Error("Missing memory id value");
+  }
+  ensureNoExtraPositionals(positionals.slice(1));
+  return {
+    op,
+    json,
+    args: { workspaceId, id: memoryId },
+  };
+}
+
+function parseCanvasCommand(
+  op: SupportedOp,
+  argv: string[],
+  workspaceId: string
+): ParsedEntryCommand {
+  let json = false;
+  let canvasId: string | undefined;
+  let sourcePath: string | undefined;
+  let kind: CanvasArtifactType | undefined;
+  let title: string | undefined;
+  let documentJson: string | undefined;
+  let openInEditor = false;
+  const positionals: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === undefined) {
+      continue;
+    }
+
+    switch (arg) {
+      case "--json":
+        json = true;
+        break;
+      case "--canvas":
+      case "--canvas-id":
+        canvasId = readOptionValue(argv, i + 1, "canvas");
+        i += 1;
+        break;
+      case "--source-path":
+        sourcePath = readOptionValue(argv, i + 1, "source-path");
+        i += 1;
+        break;
+      case "--kind":
+        kind = normalizeCanvasArtifactType(readOptionValue(argv, i + 1, "kind"));
+        i += 1;
+        break;
+      case "--title":
+        title = readOptionValue(argv, i + 1, "title");
+        i += 1;
+        break;
+      case "--document-json":
+        documentJson = readOptionValue(argv, i + 1, "document-json");
+        i += 1;
+        break;
+      case "--open":
+        openInEditor = true;
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        positionals.push(arg);
+        break;
+    }
+  }
+
+  ensureNoExtraPositionals(positionals);
+
+  if (op === "canvas.list") {
+    return {
+      op,
+      json,
+      args: { workspaceId },
+    };
+  }
+
+  if (op === "canvas.create") {
+    if (!kind) {
+      throw new Error("Missing kind value");
+    }
+    if (!title) {
+      throw new Error("Missing title value");
+    }
+    if (!documentJson) {
+      throw new Error("Missing document-json value");
+    }
+
+    return {
+      op,
+      json,
+      args: {
+        workspaceId,
+        kind,
+        title,
+        document: parseJsonOption("document-json", documentJson),
+        ...(openInEditor ? { openInEditor: true } : {}),
+      },
+    };
+  }
+
+  if (op === "canvas.update") {
+    if (!canvasId) {
+      throw new Error("Missing canvas value");
+    }
+    if (!documentJson) {
+      throw new Error("Missing document-json value");
+    }
+
+    return {
+      op,
+      json,
+      args: {
+        workspaceId,
+        canvasId,
+        ...(title !== undefined ? { title } : {}),
+        document: parseJsonOption("document-json", documentJson),
+      },
+    };
+  }
+
+  if (!canvasId && !sourcePath) {
+    throw new Error("Missing canvas or source-path value");
+  }
+
+  return {
+    op,
+    json,
+    args: {
+      workspaceId,
+      ...(canvasId !== undefined ? { canvasId } : {}),
+      ...(sourcePath !== undefined ? { sourcePath } : {}),
+    },
+  };
+}
+
+function parseUiCommand(op: SupportedOp, argv: string[], workspaceId: string): ParsedEntryCommand {
+  let json = false;
+  let path: string | undefined;
+  let url: string | undefined;
+  let line: number | undefined;
+  let column: number | undefined;
+  let canvasId: string | undefined;
+  let title: string | undefined;
+  let artifactType: CanvasArtifactType | undefined;
+  let sourcePath: string | undefined;
+  const positionals: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === undefined) {
+      continue;
+    }
+
+    switch (arg) {
+      case "--json":
+        json = true;
+        break;
+      case "--path":
+        path = readOptionValue(argv, i + 1, "path");
+        i += 1;
+        break;
+      case "--url":
+        url = readOptionValue(argv, i + 1, "url");
+        i += 1;
+        break;
+      case "--line":
+        line = readPositiveIntegerOption(argv, i + 1, "line");
+        i += 1;
+        break;
+      case "--column":
+        column = readPositiveIntegerOption(argv, i + 1, "column");
+        i += 1;
+        break;
+      case "--canvas":
+      case "--canvas-id":
+        canvasId = readOptionValue(argv, i + 1, "canvas");
+        i += 1;
+        break;
+      case "--title":
+        title = readOptionValue(argv, i + 1, "title");
+        i += 1;
+        break;
+      case "--artifact-type":
+        artifactType = normalizeCanvasArtifactType(readOptionValue(argv, i + 1, "artifact-type"));
+        i += 1;
+        break;
+      case "--source-path":
+        sourcePath = readOptionValue(argv, i + 1, "source-path");
+        i += 1;
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        positionals.push(arg);
+        break;
+    }
+  }
+
+  ensureNoExtraPositionals(positionals);
+
+  if (op === "ui.open-file") {
+    if (!path) {
+      throw new Error("Missing path value");
+    }
+    return {
+      op: "uiAction.dispatch",
+      json,
+      args: {
+        workspaceId,
+        intent: {
+          type: "editor.openFile",
+          workspaceId,
+          path,
+          ...(line !== undefined ? { line } : {}),
+          ...(column !== undefined ? { column } : {}),
+        },
+        source: { kind: "agent" },
+      },
+    };
+  }
+
+  if (op === "ui.close-file") {
+    if (!path) {
+      throw new Error("Missing path value");
+    }
+    return {
+      op: "uiAction.dispatch",
+      json,
+      args: {
+        workspaceId,
+        intent: {
+          type: "editor.closeFile",
+          workspaceId,
+          path,
+        },
+        source: { kind: "agent" },
+      },
+    };
+  }
+
+  if (op === "ui.open-url") {
+    if (!url) {
+      throw new Error("Missing url value");
+    }
+    return {
+      op: "uiAction.dispatch",
+      json,
+      args: {
+        workspaceId,
+        intent: {
+          type: "browser.openUrl",
+          workspaceId,
+          url,
+        },
+        source: { kind: "agent" },
+      },
+    };
+  }
+
+  if (op === "ui.close-url") {
+    if (!url) {
+      throw new Error("Missing url value");
+    }
+    return {
+      op: "uiAction.dispatch",
+      json,
+      args: {
+        workspaceId,
+        intent: {
+          type: "browser.closeUrl",
+          workspaceId,
+          url,
+        },
+        source: { kind: "agent" },
+      },
+    };
+  }
+
+  if (!canvasId) {
+    throw new Error("Missing canvas value");
+  }
+
+  return {
+    op: "uiAction.dispatch",
+    json,
+    args: {
+      workspaceId,
+      intent: {
+        type: "canvas.open",
+        workspaceId,
+        canvasId,
+        ...(title !== undefined ? { title } : {}),
+        ...(artifactType !== undefined ? { artifactType } : {}),
+        ...(sourcePath !== undefined ? { sourcePath } : {}),
+      },
+      source: { kind: "agent" },
+    },
+  };
+}
+
+function parseCommand(
+  opValue: string | undefined,
+  argv: string[],
+  env: SessionEnv
+): ParsedEntryCommand {
+  if (!opValue) {
+    throw new Error("Missing automation op");
+  }
+
+  const op = opValue as SupportedOp;
+  switch (op) {
+    case "memory.list":
+    case "memory.search":
+    case "memory.get":
+    case "memory.create":
+    case "memory.update":
+    case "memory.delete":
+      return parseMemoryCommand(op, argv, env.workspaceId);
+    case "canvas.list":
+    case "canvas.create":
+    case "canvas.update":
+    case "canvas.render":
+      return parseCanvasCommand(op, argv, env.workspaceId);
+    case "ui.open-file":
+    case "ui.close-file":
+    case "ui.open-url":
+    case "ui.close-url":
+    case "ui.open-canvas":
+      return parseUiCommand(op, argv, env.workspaceId);
+    default:
+      throw new Error(`Unsupported automation op: ${opValue}`);
+  }
+}
+
+function printCommandResult(result: unknown, json: boolean): void {
+  if (
+    !json &&
+    typeof result === "object" &&
+    result !== null &&
+    "text" in result &&
+    typeof (result as { text?: unknown }).text === "string"
+  ) {
+    console.log((result as { text: string }).text);
+    return;
+  }
+
+  if (
+    !json &&
+    typeof result === "object" &&
+    result !== null &&
+    "diff" in result &&
+    typeof (result as { diff?: unknown }).diff === "string"
+  ) {
+    console.log((result as { diff: string }).diff);
+    return;
+  }
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+export async function main(argv = process.argv.slice(2)): Promise<void> {
+  const env = readSessionEnv();
+  const [op, ...rest] = argv;
+  const parsed = parseCommand(op, rest, env);
+  const result = await callCoderStudioCommand({
+    apiUrl: env.apiUrl,
+    resolveStrategy: "session",
+    op: parsed.op,
+    args: parsed.args,
+  });
+
+  printCommandResult(result, parsed.json);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  void main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error("CLI error:", message);
+    process.exit(1);
+  });
+}
diff --git a/packages/cli/src/bin.test.ts b/packages/cli/src/bin.test.ts
index d93ad5dac..fb35a4ed6 100644
--- a/packages/cli/src/bin.test.ts
+++ b/packages/cli/src/bin.test.ts
@@ -73,6 +73,9 @@ vi.mock("./automation-command-client.js", () => ({
 import { main } from "./cli";
 import { parseArgs, RUNTIME_CONFIG_ERROR } from "./parse-args";
 
+const MINIMAL_ARCHITECTURE_CANVAS_DOCUMENT_JSON =
+  '{"summary":"Runtime flow","diagram":{"dsl":"mermaid","source":"flowchart LR\\nWebUI[Web UI] --> Server[Runtime Server]"},"annotations":[]}';
+
 beforeEach(() => {
   readCliConfig.mockReturnValue(null);
   writeCliConfig.mockImplementation(() => undefined);
@@ -167,7 +170,7 @@ describe("main", () => {
     expect(startManagedServer).toHaveBeenCalledWith({
       script: expect.stringMatching(/server-runner\.(ts|js|mjs)$/),
       cwd: process.cwd(),
-      waitMs: 5000,
+      waitMs: 15000,
     });
     expect(logSpy).toHaveBeenCalledWith("Coder Studio server started in background.");
     expect(logSpy).toHaveBeenCalledWith("Run `coder-studio status` to inspect the server.");
@@ -315,7 +318,7 @@ describe("main", () => {
     expect(startManagedServer).toHaveBeenCalledWith({
       script: expect.stringMatching(/server-runner\.(ts|js|mjs)$/),
       cwd: process.cwd(),
-      waitMs: 5000,
+      waitMs: 15000,
     });
     expect(logSpy).toHaveBeenCalledWith("Coder Studio server started in background.");
   });
@@ -592,6 +595,20 @@ describe("main", () => {
     );
   });
 
+  it("prints canvas help examples with escaped newlines in document-json", async () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main(["help"]);
+
+    const output = logSpy.mock.calls[0]?.[0] as string;
+    expect(output).toContain(
+      `coder-studio canvas create --workspace ws_123 --kind architecture_canvas --title "Runtime Flow" --document-json '{"summary":"Runtime flow","diagram":{"dsl":"mermaid","source":"flowchart LR\\nWebUI[Web UI] --> Server[Runtime Server]"},"annotations":[]}' --open --json`
+    );
+    expect(output).toContain(
+      `coder-studio canvas update --workspace ws_123 --canvas canvas_123 --document-json '{"summary":"Runtime flow","diagram":{"dsl":"mermaid","source":"flowchart LR\\nWebUI[Web UI] --> Server[Runtime Server]"},"annotations":[]}' --json`
+    );
+  });
+
   it("prints workspace list output through the Coder Studio command API", async () => {
     callCoderStudioCommand.mockResolvedValueOnce([{ id: "ws-1", path: "/repo" }]);
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
@@ -824,22 +841,238 @@ describe("main", () => {
     });
   });
 
+  it("prints UI open-canvas dispatch output through the Coder Studio command API", async () => {
+    callCoderStudioCommand.mockResolvedValueOnce({
+      accepted: true,
+      requestId: "req-open-canvas",
+      topic: "workspace.ws-1.ui.action",
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main(["ui", "open-canvas", "--workspace", "ws-1", "--canvas", "canvas-1", "--json"]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: undefined,
+      op: "uiAction.dispatch",
+      args: {
+        workspaceId: "ws-1",
+        intent: {
+          type: "canvas.open",
+          workspaceId: "ws-1",
+          canvasId: "canvas-1",
+        },
+        source: { kind: "agent" },
+      },
+    });
+    expect(JSON.parse(logSpy.mock.calls[0]?.[0] as string)).toEqual({
+      accepted: true,
+      requestId: "req-open-canvas",
+      topic: "workspace.ws-1.ui.action",
+    });
+  });
+
   it("prints memory list output through the Coder Studio command API", async () => {
     callCoderStudioCommand.mockResolvedValueOnce([{ id: "mem-1", workspaceId: "ws-1" }]);
     const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
 
-    await main(["memory", "list", "--workspace", "ws-1", "--type", "decision", "--json"]);
+    await main(["memory", "list", "--workspace", "ws-1", "--type", "wiki", "--json"]);
 
     expect(callCoderStudioCommand).toHaveBeenCalledWith({
       apiUrl: undefined,
       op: "memory.list",
-      args: { workspaceId: "ws-1", type: "decision" },
+      args: { workspaceId: "ws-1", type: "wiki" },
     });
     expect(JSON.parse(logSpy.mock.calls[0]?.[0] as string)).toEqual([
       { id: "mem-1", workspaceId: "ws-1" },
     ]);
   });
 
+  it("prints canvas list output through the Coder Studio command API", async () => {
+    callCoderStudioCommand.mockResolvedValueOnce([{ id: "canvas-1", workspaceId: "ws-1" }]);
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main(["canvas", "list", "--workspace", "ws-1", "--json"]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: undefined,
+      op: "canvas.list",
+      args: { workspaceId: "ws-1" },
+    });
+    expect(JSON.parse(logSpy.mock.calls[0]?.[0] as string)).toEqual([
+      { id: "canvas-1", workspaceId: "ws-1" },
+    ]);
+  });
+
+  it("maps canvas create options to canvas.create", async () => {
+    callCoderStudioCommand.mockResolvedValueOnce({ id: "canvas-1", workspaceId: "ws-1" });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const document = MINIMAL_ARCHITECTURE_CANVAS_DOCUMENT_JSON;
+
+    await main([
+      "canvas",
+      "create",
+      "--workspace",
+      "ws-1",
+      "--kind",
+      "architecture_canvas",
+      "--title",
+      "Runtime Flow",
+      "--document-json",
+      document,
+      "--open",
+      "--json",
+    ]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: undefined,
+      op: "canvas.create",
+      args: {
+        workspaceId: "ws-1",
+        kind: "architecture_canvas",
+        title: "Runtime Flow",
+        document: {
+          summary: "Runtime flow",
+          diagram: {
+            dsl: "mermaid",
+            source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+          },
+          annotations: [],
+        },
+        openInEditor: true,
+      },
+    });
+    expect(JSON.parse(logSpy.mock.calls[0]?.[0] as string)).toEqual({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+    });
+  });
+
+  it("maps canvas update options to canvas.update", async () => {
+    callCoderStudioCommand.mockResolvedValueOnce({ id: "canvas-1", workspaceId: "ws-1" });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const document = MINIMAL_ARCHITECTURE_CANVAS_DOCUMENT_JSON;
+
+    await main([
+      "canvas",
+      "update",
+      "--workspace",
+      "ws-1",
+      "--canvas-id",
+      "canvas-1",
+      "--document-json",
+      document,
+      "--json",
+    ]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: undefined,
+      op: "canvas.update",
+      args: {
+        workspaceId: "ws-1",
+        canvasId: "canvas-1",
+        document: {
+          summary: "Runtime flow",
+          diagram: {
+            dsl: "mermaid",
+            source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+          },
+          annotations: [],
+        },
+      },
+    });
+    expect(JSON.parse(logSpy.mock.calls[0]?.[0] as string)).toEqual({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+    });
+  });
+
+  it("prints canvas render output through the Coder Studio command API", async () => {
+    callCoderStudioCommand.mockResolvedValueOnce({ id: "canvas-1", format: "svg" });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main(["canvas", "render", "--workspace", "ws-1", "--canvas", "canvas-1", "--json"]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: undefined,
+      op: "canvas.render",
+      args: {
+        workspaceId: "ws-1",
+        canvasId: "canvas-1",
+      },
+    });
+    expect(JSON.parse(logSpy.mock.calls[0]?.[0] as string)).toEqual({
+      id: "canvas-1",
+      format: "svg",
+    });
+  });
+
+  it("maps canvas render source paths to canvas.render", async () => {
+    callCoderStudioCommand.mockResolvedValueOnce({
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      format: "svg",
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main([
+      "canvas",
+      "render",
+      "--workspace",
+      "ws-1",
+      "--source-path",
+      ".coder-studio/canvases/canvas-1.canvas.json",
+      "--json",
+    ]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: undefined,
+      op: "canvas.render",
+      args: {
+        workspaceId: "ws-1",
+        sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      },
+    });
+    expect(JSON.parse(logSpy.mock.calls[0]?.[0] as string)).toEqual({
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      format: "svg",
+    });
+  });
+
+  it("maps canvas render canvas ids and source paths together to canvas.render", async () => {
+    callCoderStudioCommand.mockResolvedValueOnce({
+      canvasId: "canvas-1",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      format: "svg",
+    });
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main([
+      "canvas",
+      "render",
+      "--workspace",
+      "ws-1",
+      "--canvas",
+      "canvas-1",
+      "--source-path",
+      ".coder-studio/canvases/canvas-1.canvas.json",
+      "--json",
+    ]);
+
+    expect(callCoderStudioCommand).toHaveBeenCalledWith({
+      apiUrl: undefined,
+      op: "canvas.render",
+      args: {
+        workspaceId: "ws-1",
+        canvasId: "canvas-1",
+        sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      },
+    });
+    expect(JSON.parse(logSpy.mock.calls[0]?.[0] as string)).toEqual({
+      canvasId: "canvas-1",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      format: "svg",
+    });
+  });
+
   it("uses CODER_STUDIO_WORKSPACE_ID for memory commands when workspace is omitted", async () => {
     vi.stubEnv("CODER_STUDIO_WORKSPACE_ID", "ws-env");
     callCoderStudioCommand.mockResolvedValueOnce([{ id: "mem-1", workspaceId: "ws-env" }]);
@@ -877,9 +1110,11 @@ describe("main", () => {
       "--workspace",
       "ws-1",
       "--type",
-      "decision",
+      "issue",
       "--content",
-      "Persist decisions outside the repo.",
+      "Verify memory status forwarding.",
+      "--status",
+      "pending_verification",
       "--tag",
       "Architecture",
       "--tag",
@@ -894,9 +1129,9 @@ describe("main", () => {
       op: "memory.create",
       args: {
         workspaceId: "ws-1",
-        type: "decision",
-        content: "Persist decisions outside the repo.",
-        tags: ["Architecture", "Testing"],
+        type: "issue",
+        content: "Verify memory status forwarding.",
+        status: "pending_verification",
         sourceHint: { skillSlug: "coder-studio-memory" },
       },
     });
@@ -914,6 +1149,8 @@ describe("main", () => {
       "ws-1",
       "--content",
       "Updated content",
+      "--status",
+      "completed",
       "--tag",
       "storage",
       "--json",
@@ -927,7 +1164,7 @@ describe("main", () => {
         workspaceId: "ws-1",
         id: "mem-1",
         content: "Updated content",
-        tags: ["storage"],
+        status: "completed",
       },
     });
     expect(callCoderStudioCommand).toHaveBeenNthCalledWith(2, {
@@ -1124,7 +1361,7 @@ describe("parseArgs", () => {
         "--workspace",
         "ws-1",
         "--type",
-        "decision",
+        "wiki",
         "--tag",
         "Architecture",
         "--json",
@@ -1133,7 +1370,7 @@ describe("parseArgs", () => {
       command: "memory",
       memoryCommand: "list",
       workspaceId: "ws-1",
-      memoryType: "decision",
+      memoryType: "wiki",
       tags: ["Architecture"],
       json: true,
     });
@@ -1171,6 +1408,18 @@ describe("parseArgs", () => {
     });
   });
 
+  it("parses UI open-canvas command", () => {
+    expect(
+      parseArgs(["ui", "open-canvas", "--workspace", "ws-1", "--canvas", "canvas-1", "--json"])
+    ).toEqual({
+      command: "ui",
+      uiCommand: "open-canvas",
+      workspaceId: "ws-1",
+      canvasId: "canvas-1",
+      json: true,
+    });
+  });
+
   it("parses memory search command with query text", () => {
     expect(parseArgs(["memory", "search", "testing", "--workspace", "ws-1"])).toEqual({
       command: "memory",
@@ -1189,7 +1438,7 @@ describe("parseArgs", () => {
     });
   });
 
-  it("parses memory add command with content fields, tags, and skill source", () => {
+  it("parses memory add command with content fields, status, tags, and skill source", () => {
     expect(
       parseArgs([
         "memory",
@@ -1197,9 +1446,11 @@ describe("parseArgs", () => {
         "--workspace",
         "ws-1",
         "--type",
-        "decision",
+        "issue",
         "--content",
-        "Persist decisions.",
+        "Verify memory status forwarding.",
+        "--status",
+        "pending_verification",
         "--tag",
         "Architecture",
         "--tag",
@@ -1212,8 +1463,9 @@ describe("parseArgs", () => {
       command: "memory",
       memoryCommand: "add",
       workspaceId: "ws-1",
-      memoryType: "decision",
-      content: "Persist decisions.",
+      memoryType: "issue",
+      content: "Verify memory status forwarding.",
+      memoryStatus: "pending_verification",
       tags: ["Architecture", "Testing"],
       skillSlug: "coder-studio-memory",
       json: true,
@@ -1244,6 +1496,8 @@ describe("parseArgs", () => {
         "ws-1",
         "--content",
         "Updated content",
+        "--status",
+        "completed",
         "--tag",
         "storage",
       ])
@@ -1253,6 +1507,7 @@ describe("parseArgs", () => {
       memoryId: "mem-1",
       workspaceId: "ws-1",
       content: "Updated content",
+      memoryStatus: "completed",
       tags: ["storage"],
     });
     expect(parseArgs(["memory", "delete", "mem-1", "--workspace", "ws-1"])).toEqual({
@@ -1263,6 +1518,368 @@ describe("parseArgs", () => {
     });
   });
 
+  it("parses canvas create command with required options", () => {
+    expect(
+      parseArgs([
+        "canvas",
+        "create",
+        "--workspace",
+        "ws-1",
+        "--kind",
+        "architecture_canvas",
+        "--title",
+        "Runtime Flow",
+        "--document-json",
+        MINIMAL_ARCHITECTURE_CANVAS_DOCUMENT_JSON,
+        "--open",
+        "--json",
+      ])
+    ).toEqual({
+      command: "canvas",
+      canvasCommand: "create",
+      workspaceId: "ws-1",
+      kind: "architecture_canvas",
+      title: "Runtime Flow",
+      documentJson: MINIMAL_ARCHITECTURE_CANVAS_DOCUMENT_JSON,
+      openInEditor: true,
+      json: true,
+    });
+  });
+
+  it("parses canvas list command with workspace id", () => {
+    expect(parseArgs(["canvas", "list", "--workspace", "ws-1", "--json"])).toEqual({
+      command: "canvas",
+      canvasCommand: "list",
+      workspaceId: "ws-1",
+      json: true,
+    });
+  });
+
+  it("parses canvas update command with workspace, canvas id, and document", () => {
+    expect(
+      parseArgs([
+        "canvas",
+        "update",
+        "--workspace",
+        "ws-1",
+        "--canvas-id",
+        "canvas-1",
+        "--title",
+        "Updated Runtime Flow",
+        "--document-json",
+        MINIMAL_ARCHITECTURE_CANVAS_DOCUMENT_JSON,
+        "--json",
+      ])
+    ).toEqual({
+      command: "canvas",
+      canvasCommand: "update",
+      workspaceId: "ws-1",
+      canvasId: "canvas-1",
+      title: "Updated Runtime Flow",
+      documentJson: MINIMAL_ARCHITECTURE_CANVAS_DOCUMENT_JSON,
+      json: true,
+    });
+  });
+
+  it("parses canvas render command with workspace and canvas-id alias", () => {
+    expect(
+      parseArgs(["canvas", "render", "--workspace", "ws-1", "--canvas-id", "canvas-1", "--json"])
+    ).toEqual({
+      command: "canvas",
+      canvasCommand: "render",
+      workspaceId: "ws-1",
+      canvasId: "canvas-1",
+      json: true,
+    });
+  });
+
+  it("parses canvas render command with workspace and canvas id", () => {
+    expect(
+      parseArgs(["canvas", "render", "--workspace", "ws-1", "--canvas", "canvas-1", "--json"])
+    ).toEqual({
+      command: "canvas",
+      canvasCommand: "render",
+      workspaceId: "ws-1",
+      canvasId: "canvas-1",
+      json: true,
+    });
+  });
+
+  it("parses canvas render command with workspace and source path", () => {
+    expect(
+      parseArgs([
+        "canvas",
+        "render",
+        "--workspace",
+        "ws-1",
+        "--source-path",
+        ".coder-studio/canvases/canvas-1.canvas.json",
+        "--json",
+      ])
+    ).toEqual({
+      command: "canvas",
+      canvasCommand: "render",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      json: true,
+    });
+  });
+
+  it("clears canvas args when switching from update to render", () => {
+    expect(() =>
+      parseArgs([
+        "canvas",
+        "update",
+        "--workspace",
+        "ws-1",
+        "--canvas",
+        "c1",
+        "--document-json",
+        "{}",
+        "render",
+      ])
+    ).toThrow("Missing canvas or source-path value");
+  });
+
+  it("clears canvas args when switching from create to update", () => {
+    expect(() =>
+      parseArgs([
+        "canvas",
+        "create",
+        "--workspace",
+        "ws-1",
+        "--kind",
+        "architecture_canvas",
+        "--title",
+        "T",
+        "--document-json",
+        "{}",
+        "update",
+      ])
+    ).toThrow("Missing canvas value");
+  });
+
+  it("clears update-only canvas args when switching to list", () => {
+    expect(
+      parseArgs([
+        "canvas",
+        "update",
+        "--workspace",
+        "ws-1",
+        "--canvas",
+        "c1",
+        "--document-json",
+        "{}",
+        "list",
+      ])
+    ).toEqual({
+      command: "canvas",
+      canvasCommand: "list",
+      workspaceId: "ws-1",
+    });
+  });
+
+  it("retains pre-subcommand memory options for parse compatibility", () => {
+    expect(parseArgs(["memory", "--type", "wiki", "list", "--json"])).toEqual({
+      command: "memory",
+      memoryCommand: "list",
+      memoryType: "wiki",
+      json: true,
+    });
+    expect(parseArgs(["memory", "--tag", "Architecture", "list", "--workspace", "ws-1"])).toEqual({
+      command: "memory",
+      memoryCommand: "list",
+      workspaceId: "ws-1",
+      tags: ["Architecture"],
+    });
+    expect(parseArgs(["memory", "--type", "issue", "--content", "x", "add"])).toEqual({
+      command: "memory",
+      memoryCommand: "add",
+      memoryType: "issue",
+      content: "x",
+    });
+  });
+
+  it("retains pre-subcommand memory status for update", () => {
+    expect(
+      parseArgs([
+        "memory",
+        "--status",
+        "completed",
+        "update",
+        "mem-1",
+        "--workspace",
+        "ws-1",
+        "--content",
+        "x",
+      ])
+    ).toEqual({
+      command: "memory",
+      memoryCommand: "update",
+      memoryId: "mem-1",
+      workspaceId: "ws-1",
+      content: "x",
+      memoryStatus: "completed",
+    });
+  });
+
+  it("rejects memory status on subcommands that do not write status", () => {
+    expect(() => parseArgs(["memory", "list", "--status", "completed"])).toThrow(
+      "Unknown option: --status"
+    );
+    expect(() => parseArgs(["memory", "--status", "completed", "list"])).toThrow(
+      "Unknown option: --status"
+    );
+    expect(() =>
+      parseArgs(["memory", "search", "testing", "--workspace", "ws-1", "--status", "completed"])
+    ).toThrow("Unknown option: --status");
+    expect(() =>
+      parseArgs(["memory", "delete", "mem-1", "--workspace", "ws-1", "--status", "completed"])
+    ).toThrow("Unknown option: --status");
+  });
+
+  it("clears memory status when switching memory subcommands", () => {
+    expect(
+      parseArgs([
+        "memory",
+        "add",
+        "--workspace",
+        "ws-1",
+        "--type",
+        "issue",
+        "--content",
+        "Verify memory status forwarding.",
+        "--status",
+        "completed",
+        "memory",
+        "update",
+        "mem-1",
+        "--workspace",
+        "ws-1",
+        "--content",
+        "x",
+      ])
+    ).toEqual({
+      command: "memory",
+      memoryCommand: "update",
+      memoryId: "mem-1",
+      workspaceId: "ws-1",
+      content: "x",
+    });
+  });
+
+  it("clears memory-only args when switching from memory to another automation command", () => {
+    const cases: Array<{ argv: string[]; expected: ReturnType<typeof parseArgs> }> = [
+      {
+        argv: ["memory", "--status", "completed", "workspace", "list", "--json"],
+        expected: {
+          command: "workspace",
+          workspaceCommand: "list",
+          json: true,
+        },
+      },
+      {
+        argv: [
+          "memory",
+          "add",
+          "--workspace",
+          "ws-memory",
+          "--type",
+          "issue",
+          "--content",
+          "x",
+          "--status",
+          "completed",
+          "workspace",
+          "list",
+          "--json",
+        ],
+        expected: {
+          command: "workspace",
+          workspaceCommand: "list",
+          json: true,
+        },
+      },
+      {
+        argv: [
+          "memory",
+          "add",
+          "--workspace",
+          "ws-memory",
+          "--type",
+          "issue",
+          "--content",
+          "x",
+          "--status",
+          "completed",
+          "git",
+          "status",
+          "--workspace",
+          "ws-git",
+          "--json",
+        ],
+        expected: {
+          command: "git",
+          gitCommand: "status",
+          workspaceId: "ws-git",
+          json: true,
+        },
+      },
+      {
+        argv: [
+          "memory",
+          "--status",
+          "completed",
+          "--type",
+          "issue",
+          "--content",
+          "x",
+          "--tag",
+          "Architecture",
+          "git",
+          "status",
+          "--workspace",
+          "ws-1",
+          "--json",
+        ],
+        expected: {
+          command: "git",
+          gitCommand: "status",
+          workspaceId: "ws-1",
+          json: true,
+        },
+      },
+      {
+        argv: [
+          "memory",
+          "--status",
+          "completed",
+          "--type",
+          "issue",
+          "--content",
+          "x",
+          "--tag",
+          "Architecture",
+          "ui",
+          "show-panel",
+          "--panel",
+          "terminal",
+          "--json",
+        ],
+        expected: {
+          command: "ui",
+          uiCommand: "show-panel",
+          panel: "terminal",
+          json: true,
+        },
+      },
+    ];
+
+    for (const { argv, expected } of cases) {
+      expect(parseArgs(argv)).toEqual(expected);
+    }
+  });
+
   it("parses server alias as serve", () => {
     expect(parseArgs(["server"])).toEqual({
       command: "serve",
@@ -1475,17 +2092,41 @@ describe("parseArgs", () => {
       "Missing memory id value"
     );
     expect(() => parseArgs(["memory", "add", "--workspace", "ws-1"])).toThrow("Missing type value");
-    expect(() => parseArgs(["memory", "add", "--type", "decision"])).toThrow(
-      "Missing content value"
-    );
+    expect(() => parseArgs(["memory", "add", "--type", "issue"])).toThrow("Missing content value");
     expect(() => parseArgs(["memory", "search", "--workspace", "ws-1"])).toThrow(
       "Missing query value"
     );
   });
 
+  it("requires canvas command arguments", () => {
+    expect(() => parseArgs(["canvas"])).toThrow("Missing canvas subcommand");
+    expect(() => parseArgs(["canvas", "list"])).toThrow("Missing workspace value");
+    expect(() =>
+      parseArgs(["canvas", "create", "--workspace", "ws-1", "--kind", "architecture_canvas"])
+    ).toThrow("Missing title value");
+    expect(() =>
+      parseArgs([
+        "canvas",
+        "create",
+        "--workspace",
+        "ws-1",
+        "--kind",
+        "architecture_canvas",
+        "--title",
+        "Runtime Flow",
+      ])
+    ).toThrow("Missing document-json value");
+    expect(() =>
+      parseArgs(["canvas", "update", "--workspace", "ws-1", "--document-json", "{}"])
+    ).toThrow("Missing canvas value");
+    expect(() => parseArgs(["canvas", "render", "--workspace", "ws-1"])).toThrow(
+      "Missing canvas or source-path value"
+    );
+  });
+
   it("rejects legacy title flags on memory commands", () => {
     expect(() =>
-      parseArgs(["memory", "add", "--workspace", "ws-1", "--type", "decision", "--title", "t"])
+      parseArgs(["memory", "add", "--workspace", "ws-1", "--type", "issue", "--title", "t"])
     ).toThrow("Unknown option: --title");
     expect(() =>
       parseArgs(["memory", "update", "mem-1", "--workspace", "ws-1", "--title", "t"])
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 98a3d5854..f93961b5f 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -16,7 +16,7 @@ import { getServerStatus, type ServerStatus, stopRunningServer } from "./server-
 import { prepareLocalStateStorage, startServer } from "./server-runner.js";
 import { getBrowserUrl, getListenIp, getListenUrl } from "./server-url.js";
 
-const MANAGED_SERVER_WAIT_MS = 5000;
+const MANAGED_SERVER_WAIT_MS = 15000;
 const DEFAULT_LOG_TAIL_LINES = 40;
 
 function formatConfig(config: CliConfig | null): string {
@@ -85,6 +85,7 @@ COMMANDS:
   terminal      Read terminal automation data
   git           Read git automation data
   ui            Dispatch UI actions to the active Coder Studio workspace
+  canvas        Create, update, render, and list workspace canvases
   memory        Read and write workspace memory
   version  Show version
 
@@ -121,9 +122,14 @@ EXAMPLES:
   coder-studio ui open-url --workspace ws_123 --url http://127.0.0.1:5173 --json
   coder-studio ui close-url --workspace ws_123 --url http://127.0.0.1:5173 --json
   coder-studio ui show-panel --workspace ws_123 --panel terminal --json
+  coder-studio canvas list --workspace ws_123 --json
+  coder-studio canvas create --workspace ws_123 --kind architecture_canvas --title "Runtime Flow" --document-json '{"summary":"Runtime flow","diagram":{"dsl":"mermaid","source":"flowchart LR\\nWebUI[Web UI] --> Server[Runtime Server]"},"annotations":[]}' --open --json
+  coder-studio canvas update --workspace ws_123 --canvas canvas_123 --document-json '{"summary":"Runtime flow","diagram":{"dsl":"mermaid","source":"flowchart LR\\nWebUI[Web UI] --> Server[Runtime Server]"},"annotations":[]}' --json
+  coder-studio canvas render --workspace ws_123 --canvas canvas_123 --json
   coder-studio memory list --workspace ws_123 --json
   coder-studio memory search architecture --workspace ws_123 --json
-  coder-studio memory add --workspace ws_123 --type decision --content "This repo uses pnpm." --tag tooling --json
+  coder-studio memory add --workspace ws_123 --type wiki --content "This repo uses pnpm." --json
+  coder-studio memory add --workspace ws_123 --type issue --content "Verify release notes." --status pending_verification --json
   coder-studio stop
   coder-studio config --host 0.0.0.0 --port 8080
 `);
@@ -191,6 +197,16 @@ function printCommandResult(result: unknown, options: { json?: boolean } = {}):
   console.log(JSON.stringify(result, null, 2));
 }
 
+function parseJsonOption(label: string, value: string): unknown {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    throw new Error(
+      `Invalid ${label} JSON: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
 function buildUiActionIntent(args: CliArgs): Record<string, unknown> {
   const workspace = args.workspaceId !== undefined ? { workspaceId: args.workspaceId } : {};
 
@@ -221,6 +237,12 @@ function buildUiActionIntent(args: CliArgs): Record<string, unknown> {
         ...workspace,
         url: args.url!,
       };
+    case "open-canvas":
+      return {
+        type: "canvas.open",
+        ...workspace,
+        canvasId: args.canvasId!,
+      };
     case "show-panel":
       return {
         type: "panel.show",
@@ -504,6 +526,71 @@ export async function main(argv = process.argv.slice(2)): Promise<void> {
     return;
   }
 
+  if (args.command === "canvas") {
+    if (args.canvasCommand === "list") {
+      printCommandResult(
+        await callCoderStudioCommand({
+          apiUrl: args.apiUrl,
+          op: "canvas.list",
+          args: { workspaceId: args.workspaceId! },
+        }),
+        { json: args.json }
+      );
+      return;
+    }
+
+    if (args.canvasCommand === "create") {
+      printCommandResult(
+        await callCoderStudioCommand({
+          apiUrl: args.apiUrl,
+          op: "canvas.create",
+          args: {
+            workspaceId: args.workspaceId!,
+            kind: args.kind!,
+            title: args.title!,
+            document: parseJsonOption("document-json", args.documentJson!),
+            ...(args.openInEditor === true ? { openInEditor: true } : {}),
+          },
+        }),
+        { json: args.json }
+      );
+      return;
+    }
+
+    if (args.canvasCommand === "update") {
+      printCommandResult(
+        await callCoderStudioCommand({
+          apiUrl: args.apiUrl,
+          op: "canvas.update",
+          args: {
+            workspaceId: args.workspaceId!,
+            canvasId: args.canvasId!,
+            ...(args.title !== undefined ? { title: args.title } : {}),
+            document: parseJsonOption("document-json", args.documentJson!),
+          },
+        }),
+        { json: args.json }
+      );
+      return;
+    }
+
+    if (args.canvasCommand === "render") {
+      printCommandResult(
+        await callCoderStudioCommand({
+          apiUrl: args.apiUrl,
+          op: "canvas.render",
+          args: {
+            workspaceId: args.workspaceId!,
+            ...(args.canvasId !== undefined ? { canvasId: args.canvasId } : {}),
+            ...(args.sourcePath !== undefined ? { sourcePath: args.sourcePath } : {}),
+          },
+        }),
+        { json: args.json }
+      );
+      return;
+    }
+  }
+
   if (args.command === "memory") {
     const workspaceId = resolveMemoryWorkspaceId(args);
 
@@ -516,7 +603,6 @@ export async function main(argv = process.argv.slice(2)): Promise<void> {
             workspaceId,
             ...(args.query !== undefined ? { query: args.query } : {}),
             ...(args.memoryType !== undefined ? { type: args.memoryType } : {}),
-            ...(args.tags?.[0] !== undefined ? { tag: args.tags[0] } : {}),
           },
         }),
         { json: args.json }
@@ -533,7 +619,6 @@ export async function main(argv = process.argv.slice(2)): Promise<void> {
             workspaceId,
             query: args.query!,
             ...(args.memoryType !== undefined ? { type: args.memoryType } : {}),
-            ...(args.tags?.[0] !== undefined ? { tag: args.tags[0] } : {}),
           },
         }),
         { json: args.json }
@@ -562,7 +647,7 @@ export async function main(argv = process.argv.slice(2)): Promise<void> {
             workspaceId,
             type: args.memoryType!,
             content: args.content!,
-            ...(args.tags !== undefined ? { tags: args.tags } : {}),
+            ...(args.memoryStatus !== undefined ? { status: args.memoryStatus } : {}),
             ...(args.skillSlug !== undefined ? { sourceHint: { skillSlug: args.skillSlug } } : {}),
           },
         }),
@@ -581,7 +666,7 @@ export async function main(argv = process.argv.slice(2)): Promise<void> {
             id: args.memoryId!,
             ...(args.memoryType !== undefined ? { type: args.memoryType } : {}),
             ...(args.content !== undefined ? { content: args.content } : {}),
-            ...(args.tags !== undefined ? { tags: args.tags } : {}),
+            ...(args.memoryStatus !== undefined ? { status: args.memoryStatus } : {}),
           },
         }),
         { json: args.json }
diff --git a/packages/cli/src/parse-args.ts b/packages/cli/src/parse-args.ts
index 52df7e2ba..7d1324146 100644
--- a/packages/cli/src/parse-args.ts
+++ b/packages/cli/src/parse-args.ts
@@ -15,17 +15,20 @@ type CliCommand =
   | "terminal"
   | "git"
   | "ui"
-  | "memory";
+  | "memory"
+  | "canvas";
 type AuthCommand = "ban-list" | "unblock";
 type WorkspaceCommand = "list";
 type SessionCommand = "list";
 type TerminalCommand = "read";
 type GitCommand = "status" | "diff";
+type CanvasCommand = "list" | "create" | "update" | "render";
 type UiCommand =
   | "open-file"
   | "close-file"
   | "open-url"
   | "close-url"
+  | "open-canvas"
   | "show-panel"
   | "focus-workspace"
   | "run-command";
@@ -34,6 +37,16 @@ type MemoryCommand = "list" | "get" | "search" | "add" | "update" | "delete";
 export const RUNTIME_CONFIG_ERROR =
   "Host, port, state-dir, password, and auth settings must be configured via the config command";
 
+const AUTOMATION_COMMANDS = [
+  "workspace",
+  "session",
+  "terminal",
+  "git",
+  "ui",
+  "memory",
+  "canvas",
+] as const;
+
 export interface CliArgs {
   foreground?: boolean;
   restart?: boolean;
@@ -47,6 +60,7 @@ export interface CliArgs {
   gitCommand?: GitCommand;
   uiCommand?: UiCommand;
   memoryCommand?: MemoryCommand;
+  canvasCommand?: CanvasCommand;
   configHelp?: boolean;
   port?: number;
   host?: string;
@@ -56,9 +70,11 @@ export interface CliArgs {
   ip?: string;
   json?: boolean;
   workspaceId?: string;
+  canvasId?: string;
   terminalId?: string;
   bytes?: number;
   path?: string;
+  sourcePath?: string;
   url?: string;
   panel?: string;
   uiCommandId?: string;
@@ -68,16 +84,25 @@ export interface CliArgs {
   apiUrl?: string;
   memoryId?: string;
   memoryType?: string;
+  memoryStatus?: string;
   query?: string;
   content?: string;
   tags?: string[];
   skillSlug?: string;
+  kind?: "architecture_canvas" | "report_canvas";
+  title?: string;
+  documentJson?: string;
+  openInEditor?: boolean;
 }
 
 function getActiveCommand(args: CliArgs): CliCommand {
   return args.command ?? "serve";
 }
 
+function isAutomationCommand(command: CliCommand): boolean {
+  return (AUTOMATION_COMMANDS as readonly string[]).includes(command);
+}
+
 function clearConfigArgs(args: CliArgs): void {
   delete args.configHelp;
   delete args.port;
@@ -92,6 +117,25 @@ function clearAuthArgs(args: CliArgs): void {
   delete args.ip;
 }
 
+function clearMemoryArgs(args: CliArgs): void {
+  delete args.memoryId;
+  delete args.memoryType;
+  delete args.memoryStatus;
+  delete args.query;
+  delete args.content;
+  delete args.tags;
+  delete args.skillSlug;
+}
+
+function clearCanvasArgs(args: CliArgs): void {
+  delete args.canvasId;
+  delete args.sourcePath;
+  delete args.kind;
+  delete args.title;
+  delete args.documentJson;
+  delete args.openInEditor;
+}
+
 function clearAutomationArgs(args: CliArgs): void {
   delete args.workspaceCommand;
   delete args.sessionCommand;
@@ -99,10 +143,13 @@ function clearAutomationArgs(args: CliArgs): void {
   delete args.gitCommand;
   delete args.uiCommand;
   delete args.memoryCommand;
+  delete args.canvasCommand;
   delete args.workspaceId;
+  delete args.canvasId;
   delete args.terminalId;
   delete args.bytes;
   delete args.path;
+  delete args.sourcePath;
   delete args.url;
   delete args.panel;
   delete args.uiCommandId;
@@ -110,12 +157,11 @@ function clearAutomationArgs(args: CliArgs): void {
   delete args.column;
   delete args.staged;
   delete args.apiUrl;
-  delete args.memoryId;
-  delete args.memoryType;
-  delete args.query;
-  delete args.content;
-  delete args.tags;
-  delete args.skillSlug;
+  delete args.kind;
+  delete args.title;
+  delete args.documentJson;
+  delete args.openInEditor;
+  clearMemoryArgs(args);
 }
 
 function clearLogsArgs(args: CliArgs): void {
@@ -124,6 +170,10 @@ function clearLogsArgs(args: CliArgs): void {
 }
 
 function setCommand(args: CliArgs, command: CliCommand): void {
+  const previousCommand = args.command;
+  const isAutomation = isAutomationCommand(command);
+  const wasAutomation = previousCommand !== undefined && isAutomationCommand(previousCommand);
+
   if (command !== "config") {
     clearConfigArgs(args);
   }
@@ -136,15 +186,13 @@ function setCommand(args: CliArgs, command: CliCommand): void {
     clearLogsArgs(args);
   }
 
-  if (!["workspace", "session", "terminal", "git", "ui", "memory"].includes(command)) {
+  if (!isAutomation || (wasAutomation && previousCommand !== command)) {
     clearAutomationArgs(args);
+  } else if (command !== "memory") {
+    clearMemoryArgs(args);
   }
 
-  if (
-    command !== "identify" &&
-    command !== "capabilities" &&
-    !["workspace", "session", "terminal", "git", "ui", "memory"].includes(command)
-  ) {
+  if (command !== "identify" && command !== "capabilities" && !isAutomation) {
     delete args.json;
   }
 
@@ -205,6 +253,32 @@ function readPositiveIntegerOption(argv: string[], index: number, label: string)
   return parsed;
 }
 
+function memoryCommandSupportsStatus(command: MemoryCommand): boolean {
+  return command === "add" || command === "update";
+}
+
+function setMemoryCommand(args: CliArgs, command: MemoryCommand): void {
+  const isSwitchingSubcommands = args.memoryCommand !== undefined;
+  if (isSwitchingSubcommands) {
+    clearMemoryArgs(args);
+  }
+
+  args.memoryCommand = command;
+
+  if (args.memoryStatus !== undefined && !memoryCommandSupportsStatus(command)) {
+    throwUnknownOption("--status");
+  }
+}
+
+function setCanvasCommand(args: CliArgs, command: CanvasCommand): void {
+  const isSwitchingSubcommands = args.canvasCommand !== undefined;
+  if (isSwitchingSubcommands) {
+    clearCanvasArgs(args);
+  }
+
+  args.canvasCommand = command;
+}
+
 export function parseArgs(argv: string[]): CliArgs {
   const args: CliArgs = {};
 
@@ -230,6 +304,7 @@ export function parseArgs(argv: string[]): CliArgs {
       case "git":
       case "ui":
       case "memory":
+      case "canvas":
         setCommand(args, arg);
         break;
 
@@ -312,11 +387,7 @@ export function parseArgs(argv: string[]): CliArgs {
       case "--json": {
         const command = getActiveCommand(args);
 
-        if (
-          command !== "identify" &&
-          command !== "capabilities" &&
-          !["workspace", "session", "terminal", "git", "ui", "memory"].includes(command)
-        ) {
+        if (command !== "identify" && command !== "capabilities" && !isAutomationCommand(command)) {
           throwUnknownOption(arg);
         }
 
@@ -331,7 +402,8 @@ export function parseArgs(argv: string[]): CliArgs {
           command !== "session" &&
           command !== "git" &&
           command !== "ui" &&
-          command !== "memory"
+          command !== "memory" &&
+          command !== "canvas"
         ) {
           throwUnknownOption(arg);
         }
@@ -440,7 +512,7 @@ export function parseArgs(argv: string[]): CliArgs {
 
       case "--api-url": {
         const command = getActiveCommand(args);
-        if (!["workspace", "session", "terminal", "git", "ui", "memory"].includes(command)) {
+        if (!isAutomationCommand(command)) {
           throwUnknownOption(arg);
         }
 
@@ -458,6 +530,18 @@ export function parseArgs(argv: string[]): CliArgs {
         i += 1;
         break;
 
+      case "--status":
+        if (
+          getActiveCommand(args) !== "memory" ||
+          (args.memoryCommand !== undefined && !memoryCommandSupportsStatus(args.memoryCommand))
+        ) {
+          throwUnknownOption(arg);
+        }
+
+        args.memoryStatus = readOptionValue(argv, i + 1, "status");
+        i += 1;
+        break;
+
       case "--content":
         if (getActiveCommand(args) !== "memory") {
           throwUnknownOption(arg);
@@ -485,6 +569,81 @@ export function parseArgs(argv: string[]): CliArgs {
         i += 1;
         break;
 
+      case "--kind":
+        if (getActiveCommand(args) !== "canvas" || args.canvasCommand !== "create") {
+          throwUnknownOption(arg);
+        }
+
+        {
+          const value = readOptionValue(argv, i + 1, "kind");
+          if (value !== "architecture_canvas" && value !== "report_canvas") {
+            throw new Error("Invalid kind value");
+          }
+          args.kind = value;
+        }
+        i += 1;
+        break;
+
+      case "--title":
+        if (
+          getActiveCommand(args) !== "canvas" ||
+          (args.canvasCommand !== "create" && args.canvasCommand !== "update")
+        ) {
+          throwUnknownOption(arg);
+        }
+
+        args.title = readOptionValue(argv, i + 1, "title");
+        i += 1;
+        break;
+
+      case "--document-json":
+        if (
+          getActiveCommand(args) !== "canvas" ||
+          (args.canvasCommand !== "create" && args.canvasCommand !== "update")
+        ) {
+          throwUnknownOption(arg);
+        }
+
+        args.documentJson = readOptionValue(argv, i + 1, "document-json");
+        i += 1;
+        break;
+
+      case "--canvas":
+      case "--canvas-id":
+        if (getActiveCommand(args) === "ui" && args.uiCommand === "open-canvas") {
+          args.canvasId = readOptionValue(argv, i + 1, "canvas");
+          i += 1;
+          break;
+        }
+
+        if (
+          getActiveCommand(args) !== "canvas" ||
+          (args.canvasCommand !== "update" && args.canvasCommand !== "render")
+        ) {
+          throwUnknownOption(arg);
+        }
+
+        args.canvasId = readOptionValue(argv, i + 1, "canvas");
+        i += 1;
+        break;
+
+      case "--source-path":
+        if (getActiveCommand(args) !== "canvas" || args.canvasCommand !== "render") {
+          throwUnknownOption(arg);
+        }
+
+        args.sourcePath = readOptionValue(argv, i + 1, "source-path");
+        i += 1;
+        break;
+
+      case "--open":
+        if (getActiveCommand(args) !== "canvas" || args.canvasCommand !== "create") {
+          throwUnknownOption(arg);
+        }
+
+        args.openInEditor = true;
+        break;
+
       case "--port":
       case "-p": {
         ensureConfigContext(args, arg);
@@ -547,23 +706,41 @@ export function parseArgs(argv: string[]): CliArgs {
           break;
         }
         if (command === "memory") {
-          args.memoryCommand = arg;
+          setMemoryCommand(args, arg);
+          break;
+        }
+        if (command === "canvas") {
+          setCanvasCommand(args, arg);
           break;
         }
 
         throwUnknownArgument(arg);
       }
 
+      case "create":
+      case "render":
+        if (getActiveCommand(args) !== "canvas") {
+          throwUnknownArgument(arg);
+        }
+
+        setCanvasCommand(args, arg);
+        break;
+
       case "get":
       case "search":
       case "add":
       case "update":
       case "delete":
+        if (getActiveCommand(args) === "canvas" && arg === "update") {
+          setCanvasCommand(args, arg);
+          break;
+        }
+
         if (getActiveCommand(args) !== "memory") {
           throwUnknownArgument(arg);
         }
 
-        args.memoryCommand = arg;
+        setMemoryCommand(args, arg);
         break;
 
       case "read":
@@ -587,6 +764,7 @@ export function parseArgs(argv: string[]): CliArgs {
       case "close-file":
       case "open-url":
       case "close-url":
+      case "open-canvas":
       case "show-panel":
       case "focus-workspace":
       case "run-command":
@@ -705,6 +883,10 @@ export function parseArgs(argv: string[]): CliArgs {
       throw new Error("Missing url value");
     }
 
+    if (args.uiCommand === "open-canvas" && args.canvasId === undefined) {
+      throw new Error("Missing canvas value");
+    }
+
     if (args.uiCommand === "show-panel" && args.panel === undefined) {
       throw new Error("Missing panel value");
     }
@@ -723,6 +905,10 @@ export function parseArgs(argv: string[]): CliArgs {
       throw new Error("Missing memory subcommand");
     }
 
+    if (args.memoryStatus !== undefined && !memoryCommandSupportsStatus(args.memoryCommand)) {
+      throwUnknownOption("--status");
+    }
+
     if (
       (args.memoryCommand === "get" ||
         args.memoryCommand === "update" ||
@@ -747,5 +933,47 @@ export function parseArgs(argv: string[]): CliArgs {
     }
   }
 
+  if (args.command === "canvas") {
+    if (args.canvasCommand === undefined) {
+      throw new Error("Missing canvas subcommand");
+    }
+
+    if (args.workspaceId === undefined) {
+      throw new Error("Missing workspace value");
+    }
+
+    if (args.canvasCommand === "create") {
+      if (args.kind === undefined) {
+        throw new Error("Missing kind value");
+      }
+
+      if (args.title === undefined) {
+        throw new Error("Missing title value");
+      }
+
+      if (args.documentJson === undefined) {
+        throw new Error("Missing document-json value");
+      }
+    }
+
+    if (args.canvasCommand === "update") {
+      if (args.canvasId === undefined) {
+        throw new Error("Missing canvas value");
+      }
+
+      if (args.documentJson === undefined) {
+        throw new Error("Missing document-json value");
+      }
+    }
+
+    if (
+      args.canvasCommand === "render" &&
+      args.canvasId === undefined &&
+      args.sourcePath === undefined
+    ) {
+      throw new Error("Missing canvas or source-path value");
+    }
+  }
+
   return args;
 }
diff --git a/packages/cli/src/pm2-control.test.ts b/packages/cli/src/pm2-control.test.ts
index a0129f1fe..a81127910 100644
--- a/packages/cli/src/pm2-control.test.ts
+++ b/packages/cli/src/pm2-control.test.ts
@@ -326,6 +326,73 @@ describe("pm2-control", () => {
     );
   });
 
+  it("keeps waiting while the managed process is still launching", async () => {
+    start.mockImplementationOnce(
+      (_config: unknown, callback: (error: Error | null, apps: unknown[]) => void) => {
+        callback(null, [{ pm_id: 1 }]);
+      }
+    );
+
+    describeProcess
+      .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [])
+      )
+      .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [{ pid: 424242, pm2_env: { status: "launching", restart_time: 0 } }])
+      )
+      .mockImplementation(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [{ pid: 424242, pm2_env: { status: "online", restart_time: 0 } }])
+      );
+
+    const pendingStart = startManagedServer({
+      script: "/cli/dist/esm/server-runner.js",
+      cwd: "/repo",
+      waitMs: 120,
+    });
+
+    setTimeout(() => {
+      writeRuntimeConfig({
+        host: "127.0.0.1",
+        port: 4187,
+        pid: 424242,
+        token: "test-token",
+        serverInstanceId: "server-1",
+        startedAt: Date.now(),
+      });
+    }, 10);
+
+    await expect(pendingStart).resolves.toBeUndefined();
+  });
+
+  it("times out when the managed process stays online but never writes runtime.json", async () => {
+    start.mockImplementationOnce(
+      (_config: unknown, callback: (error: Error | null, apps: unknown[]) => void) => {
+        callback(null, [{ pm_id: 1 }]);
+      }
+    );
+
+    describeProcess
+      .mockImplementationOnce(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [])
+      )
+      .mockImplementation(
+        (_name: string, callback: (error: Error | null, result: unknown[]) => void) =>
+          callback(null, [{ pid: 424242, pm2_env: { status: "online", restart_time: 0 } }])
+      );
+
+    await expect(
+      startManagedServer({
+        script: "/cli/dist/esm/server-runner.js",
+        cwd: "/repo",
+        waitMs: 50,
+      })
+    ).rejects.toThrow("runtime readiness timed out after 50ms");
+  });
+
   it("includes only the current startup error log excerpt when background startup fails", async () => {
     const { errFile } = getLogPaths();
     mkdirSync(dirname(errFile), { recursive: true });
diff --git a/packages/cli/src/pm2-control.ts b/packages/cli/src/pm2-control.ts
index 373fefea0..0e64f70ff 100644
--- a/packages/cli/src/pm2-control.ts
+++ b/packages/cli/src/pm2-control.ts
@@ -40,6 +40,11 @@ interface StartupLogOffsets {
   errOffset: number;
 }
 
+interface RuntimeReadinessState {
+  kind: "ready" | "pending" | "failed";
+  reason?: string;
+}
+
 const isMissingManagedServerError = (error: unknown): boolean => {
   if (!(error instanceof Error)) {
     return false;
@@ -208,6 +213,31 @@ const withPm2Connection = async <T>(operation: (pm2: Pm2Module) => Promise<T>):
   }
 };
 
+const readRuntimeReadiness = async (pm2: Pm2Module): Promise<RuntimeReadinessState> => {
+  if (readRuntimeConfig()) {
+    return { kind: "ready" };
+  }
+
+  const processes = await describeManagedServer(pm2);
+  const process = processes[0];
+  if (!process) {
+    return {
+      kind: "failed",
+      reason: "the managed process exited before runtime data was written",
+    };
+  }
+
+  const status = process.pm2_env?.status;
+  if (status === "errored" || status === "stopped") {
+    return {
+      kind: "failed",
+      reason: `the managed process entered the ${status} state`,
+    };
+  }
+
+  return { kind: "pending" };
+};
+
 const waitForRuntimeReady = async (
   pm2: Pm2Module,
   waitMs: number,
@@ -216,22 +246,13 @@ const waitForRuntimeReady = async (
   const deadline = Date.now() + waitMs;
 
   while (Date.now() <= deadline) {
-    if (readRuntimeConfig()) {
+    const readiness = await readRuntimeReadiness(pm2);
+    if (readiness.kind === "ready") {
       return;
     }
 
-    const processes = await describeManagedServer(pm2);
-    const process = processes[0];
-    if (!process) {
-      throw createStartupError(
-        "the managed process exited before runtime data was written",
-        logOffsets
-      );
-    }
-
-    const status = process.pm2_env?.status;
-    if (status === "errored" || status === "stopped") {
-      throw createStartupError(`the managed process entered the ${status} state`, logOffsets);
+    if (readiness.kind === "failed") {
+      throw createStartupError(readiness.reason ?? "runtime readiness failed", logOffsets);
     }
 
     const remainingMs = deadline - Date.now();
diff --git a/packages/core/src/domain/automation.test.ts b/packages/core/src/domain/automation.test.ts
index 781cdfeca..cda8102f1 100644
--- a/packages/core/src/domain/automation.test.ts
+++ b/packages/core/src/domain/automation.test.ts
@@ -1,11 +1,17 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   buildIdentifyResult,
   DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
   listAutomationCapabilities,
+  SCOPED_SESSION_AUTOMATION_PERMISSIONS,
 } from "./automation.js";
 
 describe("automation domain", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    delete process.env.CODER_STUDIO_AUTOMATION_PERMISSIONS;
+  });
+
   it("returns outside-Coder-Studio when env marker is absent", () => {
     expect(buildIdentifyResult({ env: {} })).toEqual({ insideCoderStudio: false });
   });
@@ -35,6 +41,93 @@ describe("automation domain", () => {
     });
   });
 
+  it("reads scoped automation permissions from env when present", () => {
+    expect(
+      buildIdentifyResult({
+        env: {
+          CODER_STUDIO: "1",
+          CODER_STUDIO_AUTOMATION_PERMISSIONS: SCOPED_SESSION_AUTOMATION_PERMISSIONS.join(", "),
+        },
+      }).permissions
+    ).toEqual(SCOPED_SESSION_AUTOMATION_PERMISSIONS);
+  });
+
+  it("treats an explicitly empty scoped permission env as authoritative and returns no permissions", () => {
+    expect(
+      buildIdentifyResult({
+        env: {
+          CODER_STUDIO: "1",
+          CODER_STUDIO_AUTOMATION_PERMISSIONS: "",
+        },
+      }).permissions
+    ).toEqual([]);
+  });
+
+  it("treats an invalid scoped permission env as authoritative and returns no permissions", () => {
+    expect(
+      buildIdentifyResult({
+        env: {
+          CODER_STUDIO: "1",
+          CODER_STUDIO_AUTOMATION_PERMISSIONS: "invalid:permission, nope",
+        },
+      }).permissions
+    ).toEqual([]);
+  });
+
+  it("treats mixed valid and invalid scoped permission env tokens as invalid", () => {
+    expect(
+      buildIdentifyResult({
+        env: {
+          CODER_STUDIO: "1",
+          CODER_STUDIO_AUTOMATION_PERMISSIONS: "session:read,invalid:permission",
+        },
+      }).permissions
+    ).toEqual([]);
+    expect(
+      buildIdentifyResult({
+        env: {
+          CODER_STUDIO: "1",
+          CODER_STUDIO_AUTOMATION_PERMISSIONS: "invalid:permission,session:read",
+        },
+      }).permissions
+    ).toEqual([]);
+  });
+
+  it("treats blank scoped permission env tokens as invalid", () => {
+    expect(
+      buildIdentifyResult({
+        env: {
+          CODER_STUDIO: "1",
+          CODER_STUDIO_AUTOMATION_PERMISSIONS: "session:read,",
+        },
+      }).permissions
+    ).toEqual([]);
+    expect(
+      buildIdentifyResult({
+        env: {
+          CODER_STUDIO: "1",
+          CODER_STUDIO_AUTOMATION_PERMISSIONS: ",session:read",
+        },
+      }).permissions
+    ).toEqual([]);
+    expect(
+      buildIdentifyResult({
+        env: {
+          CODER_STUDIO: "1",
+          CODER_STUDIO_AUTOMATION_PERMISSIONS: "session:read,,git:read",
+        },
+      }).permissions
+    ).toEqual([]);
+    expect(
+      buildIdentifyResult({
+        env: {
+          CODER_STUDIO: "1",
+          CODER_STUDIO_AUTOMATION_PERMISSIONS: "session:read, ,git:read",
+        },
+      }).permissions
+    ).toEqual([]);
+  });
+
   it("lists capabilities allowed by caller permissions", () => {
     const capabilities = listAutomationCapabilities({
       permissions: DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
@@ -79,24 +172,24 @@ describe("automation domain", () => {
     expect(memoryAdd).toMatchObject({
       permissions: ["memory:write"],
       riskLevel: "write",
-      examples: [
-        'coder-studio memory add --workspace ws_123 --type project --content "..." --json',
-      ],
+      examples: ['coder-studio memory add --workspace ws_123 --type wiki --content "..." --json'],
     });
     expect(memoryAdd?.examples).toEqual([
-      'coder-studio memory add --workspace ws_123 --type project --content "..." --json',
+      'coder-studio memory add --workspace ws_123 --type wiki --content "..." --json',
     ]);
     expect(memoryAdd?.inputSchema).toEqual({
       workspaceId: "string",
-      type: "feature | todo | bugfix | project | note",
+      type: "wiki | issue | todo | note",
       content: "string",
+      status: "not_started | in_progress | pending_verification | completed optional",
     });
     expect(memoryAdd?.inputSchema).not.toHaveProperty("tags");
     expect(memoryUpdate?.inputSchema).toEqual({
       workspaceId: "string",
       id: "string",
-      type: "feature | todo | bugfix | project | note optional",
+      type: "wiki | issue | todo | note optional",
       content: "string optional",
+      status: "not_started | in_progress | pending_verification | completed optional",
     });
     expect(memoryUpdate?.inputSchema).not.toHaveProperty("tags");
     expect(memoryUpdate).toMatchObject({
@@ -108,11 +201,18 @@ describe("automation domain", () => {
     expect(memoryExamples).toSatisfy((examples) =>
       examples.every((example) => !example.includes("--tag"))
     );
+    expect(memoryExamples).toSatisfy((examples) =>
+      examples.every((example) => !example.includes("--type project"))
+    );
     expect(memoryAdd?.inputSchema.type).not.toContain("project_fact");
     expect(memoryUpdate?.inputSchema.type).not.toContain("project_fact");
     expect(memoryExamples).toSatisfy((examples) =>
       examples.every((example) => !example.includes("project_fact"))
     );
+    expect(JSON.stringify(memoryCapabilities)).not.toContain("bugfix");
+    expect(JSON.stringify(memoryCapabilities)).not.toContain(
+      "feature | todo | bugfix | project | note"
+    );
   });
 
   it("includes low-risk UI action permissions in the default agent permissions", () => {
@@ -171,4 +271,119 @@ describe("automation domain", () => {
       )
     ).toEqual(["memory.add", "memory.update", "memory.delete"]);
   });
+
+  it("lists scoped capabilities without workspace.list while preserving session, terminal, git, memory, and ui actions", () => {
+    const capabilities = listAutomationCapabilities({
+      permissions: SCOPED_SESSION_AUTOMATION_PERMISSIONS,
+    });
+    const capabilityNames = capabilities.map((capability) => capability.name);
+
+    expect(capabilityNames).not.toContain("workspace.list");
+    expect(capabilityNames).toEqual(
+      expect.arrayContaining([
+        "session.list",
+        "terminal.read",
+        "git.status",
+        "git.diff",
+        "memory.list",
+        "memory.search",
+        "memory.get",
+        "memory.add",
+        "memory.update",
+        "memory.delete",
+        "ui.editor.openFile",
+        "ui.editor.closeFile",
+        "ui.browser.openUrl",
+        "ui.browser.closeUrl",
+        "ui.workspace.focus",
+        "ui.panel.show",
+        "ui.command.run",
+      ])
+    );
+  });
+
+  it("prints scoped capabilities in the cli without workspace.list", async () => {
+    process.env.CODER_STUDIO_AUTOMATION_PERMISSIONS =
+      SCOPED_SESSION_AUTOMATION_PERMISSIONS.join(", ");
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const { printCapabilities } = await import("../../../cli/src/automation-client.ts");
+
+    printCapabilities({ json: true });
+
+    const payload = JSON.parse(logSpy.mock.calls[0]?.[0] as string) as {
+      version: number;
+      commands: Array<{ name: string }>;
+    };
+
+    expect(payload.version).toBe(1);
+    expect(payload.commands.map((command) => command.name)).not.toContain("workspace.list");
+    expect(payload.commands.map((command) => command.name)).toEqual(
+      expect.arrayContaining([
+        "session.list",
+        "terminal.read",
+        "git.status",
+        "git.diff",
+        "memory.list",
+        "memory.search",
+        "memory.get",
+        "memory.add",
+        "memory.update",
+        "memory.delete",
+        "ui.editor.openFile",
+        "ui.command.run",
+      ])
+    );
+  });
+
+  it("prints no cli capabilities when the scoped permission env is present but invalid", async () => {
+    process.env.CODER_STUDIO_AUTOMATION_PERMISSIONS = "invalid:permission, nope";
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const { printCapabilities } = await import("../../../cli/src/automation-client.ts");
+
+    printCapabilities({ json: true });
+
+    const payload = JSON.parse(logSpy.mock.calls[0]?.[0] as string) as {
+      version: number;
+      commands: Array<{ name: string }>;
+    };
+
+    expect(payload.version).toBe(1);
+    expect(payload.commands).toEqual([]);
+  });
+
+  it("prints no cli capabilities when the scoped permission env mixes valid and invalid tokens", async () => {
+    process.env.CODER_STUDIO_AUTOMATION_PERMISSIONS = "session:read,invalid:permission";
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const { printCapabilities } = await import("../../../cli/src/automation-client.ts");
+
+    printCapabilities({ json: true });
+
+    const payload = JSON.parse(logSpy.mock.calls[0]?.[0] as string) as {
+      version: number;
+      commands: Array<{ name: string }>;
+    };
+
+    expect(payload.version).toBe(1);
+    expect(payload.commands).toEqual([]);
+  });
+
+  it("prints no cli capabilities when the scoped permission env includes blank tokens", async () => {
+    process.env.CODER_STUDIO_AUTOMATION_PERMISSIONS = "session:read, ";
+
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const { printCapabilities } = await import("../../../cli/src/automation-client.ts");
+
+    printCapabilities({ json: true });
+
+    const payload = JSON.parse(logSpy.mock.calls[0]?.[0] as string) as {
+      version: number;
+      commands: Array<{ name: string }>;
+    };
+
+    expect(payload.version).toBe(1);
+    expect(payload.commands).toEqual([]);
+  });
 });
diff --git a/packages/core/src/domain/automation.ts b/packages/core/src/domain/automation.ts
index 6125c7bb7..902e018a2 100644
--- a/packages/core/src/domain/automation.ts
+++ b/packages/core/src/domain/automation.ts
@@ -1,5 +1,7 @@
 import { listUiActionCapabilities } from "./ui-actions.js";
 
+export const AUTOMATION_PERMISSIONS_ENV = "CODER_STUDIO_AUTOMATION_PERMISSIONS";
+
 export const DEFAULT_AGENT_AUTOMATION_PERMISSIONS = [
   "workspace:read",
   "session:read",
@@ -15,6 +17,16 @@ export const DEFAULT_AGENT_AUTOMATION_PERMISSIONS = [
 export type AutomationPermission = (typeof DEFAULT_AGENT_AUTOMATION_PERMISSIONS)[number];
 export type AutomationRiskLevel = "read" | "write" | "dangerous";
 
+export const SCOPED_SESSION_AUTOMATION_PERMISSIONS = [
+  "session:read",
+  "terminal:read",
+  "git:read",
+  "memory:read",
+  "memory:write",
+  "ui:navigate",
+  "ui:command",
+] as const satisfies readonly AutomationPermission[];
+
 export interface IdentifyInput {
   env?: Record<string, string | undefined>;
   cwd?: string;
@@ -138,13 +150,14 @@ const MVP_CAPABILITIES: AutomationCapability[] = [
     description: "Create a workspace memory entry.",
     inputSchema: {
       workspaceId: "string",
-      type: "feature | todo | bugfix | project | note",
+      type: "wiki | issue | todo | note",
       content: "string",
+      status: "not_started | in_progress | pending_verification | completed optional",
     },
     output: "Created workspace memory entry as JSON.",
     permissions: ["memory:write"],
     riskLevel: "write",
-    examples: ['coder-studio memory add --workspace ws_123 --type project --content "..." --json'],
+    examples: ['coder-studio memory add --workspace ws_123 --type wiki --content "..." --json'],
     available: true,
   },
   {
@@ -154,8 +167,9 @@ const MVP_CAPABILITIES: AutomationCapability[] = [
     inputSchema: {
       workspaceId: "string",
       id: "string",
-      type: "feature | todo | bugfix | project | note optional",
+      type: "wiki | issue | todo | note optional",
       content: "string optional",
+      status: "not_started | in_progress | pending_verification | completed optional",
     },
     output: "Updated workspace memory entry as JSON.",
     permissions: ["memory:write"],
@@ -176,12 +190,49 @@ const MVP_CAPABILITIES: AutomationCapability[] = [
   },
 ];
 
+const AUTOMATION_PERMISSION_SET = new Set<AutomationPermission>(
+  DEFAULT_AGENT_AUTOMATION_PERMISSIONS
+);
+
+export function parseAutomationPermissionsEnv(value?: string): AutomationPermission[] {
+  if (!value) {
+    return [];
+  }
+
+  const permissions: AutomationPermission[] = [];
+  const seen = new Set<AutomationPermission>();
+
+  for (const token of value.split(",")) {
+    const normalized = token.trim();
+    if (!normalized) {
+      return [];
+    }
+
+    if (!AUTOMATION_PERMISSION_SET.has(normalized as AutomationPermission)) {
+      return [];
+    }
+
+    const permission = normalized as AutomationPermission;
+    if (seen.has(permission)) {
+      continue;
+    }
+
+    seen.add(permission);
+    permissions.push(permission);
+  }
+
+  return permissions;
+}
+
 export function buildIdentifyResult(input: IdentifyInput = {}): IdentifyResult {
   const env = input.env ?? process.env;
   if (env.CODER_STUDIO !== "1") {
     return { insideCoderStudio: false };
   }
 
+  const scopedPermissionsEnv = env[AUTOMATION_PERMISSIONS_ENV];
+  const scopedPermissions = parseAutomationPermissionsEnv(scopedPermissionsEnv);
+
   return {
     insideCoderStudio: true,
     workspaceId: env.CODER_STUDIO_WORKSPACE_ID,
@@ -190,7 +241,8 @@ export function buildIdentifyResult(input: IdentifyInput = {}): IdentifyResult {
     providerId: env.CODER_STUDIO_PROVIDER_ID,
     cwd: input.cwd ?? process.cwd(),
     apiUrl: env.CODER_STUDIO_API_URL,
-    permissions: DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
+    permissions:
+      scopedPermissionsEnv === undefined ? DEFAULT_AGENT_AUTOMATION_PERMISSIONS : scopedPermissions,
   };
 }
 
diff --git a/packages/core/src/domain/canvas.test.ts b/packages/core/src/domain/canvas.test.ts
new file mode 100644
index 000000000..157666bb8
--- /dev/null
+++ b/packages/core/src/domain/canvas.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { CanvasDataResponseSchema, parseCanvasDocumentEnvelope } from "./canvas.js";
+
+describe("canvas domain", () => {
+  it("parses an architecture canvas envelope", () => {
+    const parsed = parseCanvasDocumentEnvelope({
+      version: 1,
+      kind: "architecture_canvas",
+      title: "Runtime Flow",
+      document: {
+        summary: "How requests move.",
+        diagram: {
+          dsl: "mermaid",
+          source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+        },
+        annotations: [{ title: "Boundary", body: "Server owns execution." }],
+      },
+    });
+
+    expect(parsed.kind).toBe("architecture_canvas");
+    expect(parsed.document.diagram.dsl).toBe("mermaid");
+  });
+
+  it("rejects ready responses without a compiled document", () => {
+    const result = CanvasDataResponseSchema.safeParse({
+      canvasId: "canvas-1",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      workspaceId: "ws-1",
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      renderStatus: "ready",
+      lastError: null,
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  it("requires sourcePath for canvas render responses", () => {
+    expect(() =>
+      CanvasDataResponseSchema.parse({
+        workspaceId: "ws-1",
+        title: "Runtime Flow",
+        kind: "architecture_canvas",
+        renderStatus: "ready",
+        lastError: null,
+        compiledDocument: {
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [],
+        },
+      })
+    ).toThrow();
+
+    expect(
+      CanvasDataResponseSchema.parse({
+        workspaceId: "ws-1",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+        title: "Runtime Flow",
+        kind: "architecture_canvas",
+        renderStatus: "ready",
+        lastError: null,
+        compiledDocument: {
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [],
+        },
+      })
+    ).toMatchObject({
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+  });
+});
diff --git a/packages/core/src/domain/canvas.ts b/packages/core/src/domain/canvas.ts
new file mode 100644
index 000000000..38ab3d927
--- /dev/null
+++ b/packages/core/src/domain/canvas.ts
@@ -0,0 +1,288 @@
+import { z } from "zod";
+
+export const CanvasArtifactKind = z.enum(["architecture_canvas", "report_canvas"]);
+export type CanvasArtifactKind = z.infer<typeof CanvasArtifactKind>;
+
+export const CANVAS_DOCUMENT_VERSION = 1;
+
+export const CanvasRenderStatus = z.enum(["ready", "error", "rendering"]);
+export type CanvasRenderStatus = z.infer<typeof CanvasRenderStatus>;
+
+export const CanvasErrorCategory = z.enum(["validation_error", "compile_error", "render_error"]);
+export type CanvasErrorCategory = z.infer<typeof CanvasErrorCategory>;
+
+export const CanvasRenderErrorSchema = z.object({
+  category: CanvasErrorCategory,
+  message: z.string(),
+  fieldPath: z.string().optional(),
+});
+export type CanvasRenderError = z.infer<typeof CanvasRenderErrorSchema>;
+
+const GraphDiagramSchema = z.object({
+  dsl: z.literal("mermaid"),
+  source: z.string().trim().min(1),
+});
+
+const ArchitectureCanvasAnnotationSchema = z.object({
+  title: z.string().trim().min(1),
+  body: z.string().trim().min(1),
+});
+
+const ArchitectureCanvasDocumentSchema = z.object({
+  summary: z.string().trim().min(1),
+  diagram: GraphDiagramSchema,
+  annotations: z.array(ArchitectureCanvasAnnotationSchema),
+});
+export type ArchitectureCanvasDocument = z.infer<typeof ArchitectureCanvasDocumentSchema>;
+
+const ReportStatSchema = z.object({
+  label: z.string().trim().min(1),
+  value: z.union([z.string(), z.number()]),
+  tone: z.enum(["neutral", "info", "success", "warning", "danger"]).optional(),
+});
+
+const ReportBlockSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("stats"),
+    items: z.array(ReportStatSchema).min(1),
+  }),
+  z.object({
+    type: z.literal("markdown"),
+    markdown: z.string().trim().min(1),
+  }),
+  z.object({
+    type: z.literal("list"),
+    items: z.array(z.string().trim().min(1)).min(1),
+  }),
+  z.object({
+    type: z.literal("table"),
+    columns: z.array(z.string().trim().min(1)).min(1),
+    rows: z.array(z.array(z.string())).min(1),
+  }),
+  z.object({
+    type: z.literal("callout"),
+    tone: z.enum(["info", "success", "warning", "danger"]),
+    title: z.string().trim().min(1),
+    body: z.string().trim().min(1),
+  }),
+]);
+
+const ReportCanvasDocumentSchema = z.object({
+  summary: z.string().trim().min(1),
+  stats: z.array(ReportStatSchema),
+  sections: z
+    .array(
+      z.object({
+        title: z.string().trim().min(1),
+        blocks: z.array(ReportBlockSchema).min(1),
+      })
+    )
+    .min(1),
+});
+export type ReportCanvasDocument = z.infer<typeof ReportCanvasDocumentSchema>;
+
+export const CanvasDocumentEnvelopeSchema = z.discriminatedUnion("kind", [
+  z.object({
+    version: z.literal(CANVAS_DOCUMENT_VERSION),
+    kind: z.literal("architecture_canvas"),
+    title: z.string().trim().min(1),
+    document: ArchitectureCanvasDocumentSchema,
+  }),
+  z.object({
+    version: z.literal(CANVAS_DOCUMENT_VERSION),
+    kind: z.literal("report_canvas"),
+    title: z.string().trim().min(1),
+    document: ReportCanvasDocumentSchema,
+  }),
+]);
+export type CanvasDocumentEnvelope = z.infer<typeof CanvasDocumentEnvelopeSchema>;
+
+const CompiledArchitectureCanvasSchema = z.object({
+  kind: z.literal("architecture_canvas"),
+  title: z.string().trim().min(1),
+  summary: z.string().trim().min(1),
+  sections: z.array(
+    z.discriminatedUnion("type", [
+      z.object({
+        type: z.literal("diagram"),
+        mermaidSource: z.string().trim().min(1).optional(),
+        direction: z.enum(["TB", "TD", "BT", "LR", "RL"]).optional(),
+        groups: z
+          .array(
+            z.object({
+              id: z.string().trim().min(1),
+              label: z.string().trim().min(1),
+              nodeIds: z.array(z.string().trim().min(1)).min(1),
+            })
+          )
+          .optional(),
+        nodes: z.array(
+          z.object({
+            id: z.string().trim().min(1),
+            label: z.string().trim().min(1).optional(),
+          })
+        ),
+        edges: z.array(
+          z.object({
+            from: z.string().trim().min(1),
+            to: z.string().trim().min(1),
+            label: z.string().trim().min(1).optional(),
+          })
+        ),
+      }),
+      z.object({
+        type: z.literal("annotations"),
+        items: z.array(ArchitectureCanvasAnnotationSchema),
+      }),
+    ])
+  ),
+});
+
+const CompiledReportBlockSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("markdown"),
+    markdown: z.string().trim().min(1),
+  }),
+  z.object({
+    type: z.literal("list"),
+    items: z.array(z.string().trim().min(1)).min(1),
+  }),
+  z.object({
+    type: z.literal("table"),
+    columns: z.array(z.string().trim().min(1)).min(1),
+    rows: z.array(z.array(z.string())).min(1),
+  }),
+  z.object({
+    type: z.literal("callout"),
+    tone: z.enum(["info", "success", "warning", "danger"]),
+    title: z.string().trim().min(1),
+    body: z.string().trim().min(1),
+  }),
+  z.object({
+    type: z.literal("stats"),
+    items: z.array(
+      z.object({
+        label: z.string().trim().min(1),
+        value: z.string(),
+        tone: z.enum(["neutral", "info", "success", "warning", "danger"]).optional(),
+      })
+    ),
+  }),
+]);
+
+const CompiledReportCanvasSchema = z.object({
+  kind: z.literal("report_canvas"),
+  title: z.string().trim().min(1),
+  sections: z.array(
+    z.discriminatedUnion("type", [
+      z.object({
+        type: z.literal("stats"),
+        items: z.array(
+          z.object({
+            label: z.string().trim().min(1),
+            value: z.string(),
+            tone: z.enum(["neutral", "info", "success", "warning", "danger"]).optional(),
+          })
+        ),
+      }),
+      z.object({
+        type: z.literal("section"),
+        title: z.string().trim().min(1),
+        blocks: z.array(CompiledReportBlockSchema),
+      }),
+    ])
+  ),
+});
+
+export const CompiledCanvasSchema = z.discriminatedUnion("kind", [
+  CompiledArchitectureCanvasSchema,
+  CompiledReportCanvasSchema,
+]);
+export type CompiledCanvas = z.infer<typeof CompiledCanvasSchema>;
+
+export const CanvasDataResponseSchema = z
+  .object({
+    canvasId: z.string().trim().min(1).optional(),
+    workspaceId: z.string().trim().min(1),
+    sourcePath: z.string().trim().min(1),
+    title: z.string().trim().min(1),
+    kind: CanvasArtifactKind,
+    renderStatus: z.enum(["ready", "error"]),
+    lastError: CanvasRenderErrorSchema.nullable().optional(),
+    compiledDocument: CompiledCanvasSchema.optional(),
+  })
+  .superRefine((value, ctx) => {
+    if (value.renderStatus === "ready") {
+      if (!value.compiledDocument) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["compiledDocument"],
+          message: "compiledDocument is required when renderStatus is ready",
+        });
+      }
+
+      if (value.compiledDocument && value.compiledDocument.kind !== value.kind) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["compiledDocument", "kind"],
+          message: "compiledDocument.kind must match kind",
+        });
+      }
+
+      if (value.lastError !== null && value.lastError !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["lastError"],
+          message: "lastError must be null or undefined when renderStatus is ready",
+        });
+      }
+    }
+
+    if (value.renderStatus === "error") {
+      if (value.compiledDocument) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["compiledDocument"],
+          message: "compiledDocument must be absent when renderStatus is error",
+        });
+      }
+
+      if (value.lastError == null) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["lastError"],
+          message: "lastError is required when renderStatus is error",
+        });
+      }
+    }
+  });
+export type CanvasDataResponse = z.infer<typeof CanvasDataResponseSchema>;
+
+export interface CanvasRecord {
+  id: string;
+  workspaceId: string;
+  sessionId?: string;
+  sourcePath: string;
+  artifactType: CanvasArtifactKind;
+  title: string;
+  updatedAt: number;
+  renderStatus: CanvasRenderStatus;
+  lastError?: CanvasRenderError | null;
+}
+
+export function parseCanvasDocumentEnvelope(value: unknown): CanvasDocumentEnvelope {
+  const result = CanvasDocumentEnvelopeSchema.safeParse(value);
+  if (result.success) {
+    return result.data;
+  }
+
+  const firstIssue = result.error.issues[0];
+  if (!firstIssue) {
+    throw new Error("Invalid canvas");
+  }
+
+  const path = firstIssue?.path?.length ? firstIssue.path.join(".") : undefined;
+  const message = path ? `${path}: ${firstIssue.message}` : firstIssue.message;
+
+  throw new Error(message);
+}
diff --git a/packages/core/src/domain/memory.test.ts b/packages/core/src/domain/memory.test.ts
index 371b37dfa..8d1d6bd25 100644
--- a/packages/core/src/domain/memory.test.ts
+++ b/packages/core/src/domain/memory.test.ts
@@ -1,17 +1,46 @@
 import { describe, expect, it } from "vitest";
 import {
+  isActionableWorkspaceMemoryType,
+  normalizeWorkspaceMemoryStatus,
+  normalizeWorkspaceMemoryType,
   resolveWorkspaceMemorySource,
   validateWorkspaceMemoryInput,
   WORKSPACE_MEMORY_SOURCE_KINDS,
+  WORKSPACE_MEMORY_STATUSES,
   WORKSPACE_MEMORY_TYPES,
 } from "./memory.js";
 
 describe("workspace memory domain", () => {
-  it("exports stable memory types and source kinds", () => {
-    expect(WORKSPACE_MEMORY_TYPES).toEqual(["feature", "todo", "bugfix", "project", "note"]);
+  it("exports stable memory types, statuses, and source kinds", () => {
+    expect(WORKSPACE_MEMORY_TYPES).toEqual(["wiki", "issue", "todo", "note"]);
+    expect(WORKSPACE_MEMORY_STATUSES).toEqual([
+      "not_started",
+      "in_progress",
+      "pending_verification",
+      "completed",
+    ]);
     expect(WORKSPACE_MEMORY_SOURCE_KINDS).toEqual(["user", "agent", "skill"]);
   });
 
+  it("normalizes legacy memory types into the canonical taxonomy", () => {
+    expect(normalizeWorkspaceMemoryType("project")).toBe("wiki");
+    expect(normalizeWorkspaceMemoryType("bugfix")).toBe("issue");
+    expect(normalizeWorkspaceMemoryType("feature")).toBe("wiki");
+    expect(normalizeWorkspaceMemoryType("todo")).toBe("todo");
+    expect(normalizeWorkspaceMemoryType("unknown")).toBeUndefined();
+    expect(normalizeWorkspaceMemoryType("toString")).toBeUndefined();
+  });
+
+  it("detects actionable memory types", () => {
+    expect(isActionableWorkspaceMemoryType("wiki")).toBe(false);
+    expect(isActionableWorkspaceMemoryType("issue")).toBe(true);
+  });
+
+  it("normalizes canonical memory statuses", () => {
+    expect(normalizeWorkspaceMemoryStatus("in_progress")).toBe("in_progress");
+    expect(normalizeWorkspaceMemoryStatus("unknown")).toBeUndefined();
+  });
+
   it("normalizes trimmed content", () => {
     expect(
       validateWorkspaceMemoryInput({
@@ -19,11 +48,71 @@ describe("workspace memory domain", () => {
         content: "  Use pnpm for package scripts.  ",
       })
     ).toEqual({
-      type: "project",
+      type: "wiki",
       content: "Use pnpm for package scripts.",
     });
   });
 
+  it("validates canonical and legacy memory inputs with actionable statuses", () => {
+    expect(
+      validateWorkspaceMemoryInput({
+        type: "issue",
+        content: "Broken",
+        status: "in_progress",
+      })
+    ).toEqual({
+      type: "issue",
+      content: "Broken",
+      status: "in_progress",
+    });
+    expect(
+      validateWorkspaceMemoryInput({
+        type: "todo",
+        content: "Ship",
+        status: undefined,
+      })
+    ).toEqual({
+      type: "todo",
+      content: "Ship",
+      status: "not_started",
+    });
+    expect(
+      validateWorkspaceMemoryInput({
+        type: "wiki",
+        content: "Use pnpm",
+        status: "completed",
+      })
+    ).toEqual({
+      type: "wiki",
+      content: "Use pnpm",
+    });
+    expect(
+      validateWorkspaceMemoryInput({
+        type: "bugfix",
+        content: "Old",
+        status: "completed",
+      })
+    ).toEqual({
+      type: "issue",
+      content: "Old",
+      status: "completed",
+    });
+    expect(() =>
+      validateWorkspaceMemoryInput({
+        type: "issue",
+        content: "Broken",
+        status: "unknown",
+      })
+    ).toThrow("Invalid memory status");
+    expect(() =>
+      validateWorkspaceMemoryInput({
+        type: "wiki",
+        content: "Use pnpm",
+        status: "unknown",
+      })
+    ).toThrow("Invalid memory status");
+  });
+
   it("ignores stale tags payloads and returns a tag-free validated result", () => {
     const validated = validateWorkspaceMemoryInput({
       type: "project",
@@ -32,7 +121,7 @@ describe("workspace memory domain", () => {
     } as Parameters<typeof validateWorkspaceMemoryInput>[0] & { tags: string[] });
 
     expect(validated).toEqual({
-      type: "project",
+      type: "wiki",
       content: "Keep pnpm scripts centralized.",
     });
     expect(validated).not.toHaveProperty("tags");
@@ -45,6 +134,12 @@ describe("workspace memory domain", () => {
         content: "Content",
       })
     ).toThrow("Invalid memory type");
+    expect(() =>
+      validateWorkspaceMemoryInput({
+        type: "toString",
+        content: "x",
+      })
+    ).toThrow("Invalid memory type");
     expect(() =>
       validateWorkspaceMemoryInput({
         type: "note",
diff --git a/packages/core/src/domain/memory.ts b/packages/core/src/domain/memory.ts
index 56267a3fb..fe10da3b7 100644
--- a/packages/core/src/domain/memory.ts
+++ b/packages/core/src/domain/memory.ts
@@ -1,7 +1,35 @@
-export const WORKSPACE_MEMORY_TYPES = ["feature", "todo", "bugfix", "project", "note"] as const;
+export const WorkspaceMemoryType = {
+  Wiki: "wiki",
+  Issue: "issue",
+  Todo: "todo",
+  Note: "note",
+} as const;
+
+export const WORKSPACE_MEMORY_TYPES = [
+  WorkspaceMemoryType.Wiki,
+  WorkspaceMemoryType.Issue,
+  WorkspaceMemoryType.Todo,
+  WorkspaceMemoryType.Note,
+] as const;
 
 export type WorkspaceMemoryType = (typeof WORKSPACE_MEMORY_TYPES)[number];
 
+export const WorkspaceMemoryStatus = {
+  NotStarted: "not_started",
+  InProgress: "in_progress",
+  PendingVerification: "pending_verification",
+  Completed: "completed",
+} as const;
+
+export const WORKSPACE_MEMORY_STATUSES = [
+  WorkspaceMemoryStatus.NotStarted,
+  WorkspaceMemoryStatus.InProgress,
+  WorkspaceMemoryStatus.PendingVerification,
+  WorkspaceMemoryStatus.Completed,
+] as const;
+
+export type WorkspaceMemoryStatus = (typeof WORKSPACE_MEMORY_STATUSES)[number];
+
 export const WORKSPACE_MEMORY_SOURCE_KINDS = ["user", "agent", "skill"] as const;
 
 export type WorkspaceMemorySourceKind = (typeof WORKSPACE_MEMORY_SOURCE_KINDS)[number];
@@ -18,6 +46,7 @@ export interface WorkspaceMemoryEntry {
   workspaceId: string;
   type: WorkspaceMemoryType;
   content: string;
+  status?: WorkspaceMemoryStatus;
   source: WorkspaceMemorySource;
   createdAt: number;
   updatedAt: number;
@@ -34,11 +63,13 @@ export interface WorkspaceMemoryListFilter {
 export interface WorkspaceMemoryInput {
   type: unknown;
   content: unknown;
+  status?: unknown;
 }
 
 export interface WorkspaceMemoryValidatedInput {
   type: WorkspaceMemoryType;
   content: string;
+  status?: WorkspaceMemoryStatus;
 }
 
 export interface WorkspaceMemorySourceInput {
@@ -50,10 +81,14 @@ export interface WorkspaceMemorySourceInput {
 }
 
 const WORKSPACE_MEMORY_TYPE_SET = new Set<string>(WORKSPACE_MEMORY_TYPES);
+const WORKSPACE_MEMORY_STATUS_SET = new Set<string>(WORKSPACE_MEMORY_STATUSES);
 const WORKSPACE_MEMORY_SOURCE_KIND_SET = new Set<string>(WORKSPACE_MEMORY_SOURCE_KINDS);
-function isWorkspaceMemoryType(value: unknown): value is WorkspaceMemoryType {
-  return typeof value === "string" && WORKSPACE_MEMORY_TYPE_SET.has(value);
-}
+
+const LEGACY_WORKSPACE_MEMORY_TYPE_ALIASES = new Map<string, WorkspaceMemoryType>([
+  ["project", WorkspaceMemoryType.Wiki],
+  ["bugfix", WorkspaceMemoryType.Issue],
+  ["feature", WorkspaceMemoryType.Wiki],
+]);
 
 function isWorkspaceMemorySourceKind(value: unknown): value is WorkspaceMemorySourceKind {
   return typeof value === "string" && WORKSPACE_MEMORY_SOURCE_KIND_SET.has(value);
@@ -68,10 +103,33 @@ function normalizeSourceText(value: unknown): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined;
 }
 
+export function normalizeWorkspaceMemoryType(value: unknown): WorkspaceMemoryType | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  if (WORKSPACE_MEMORY_TYPE_SET.has(value)) {
+    return value as WorkspaceMemoryType;
+  }
+
+  return LEGACY_WORKSPACE_MEMORY_TYPE_ALIASES.get(value);
+}
+
+export function isActionableWorkspaceMemoryType(type: WorkspaceMemoryType): boolean {
+  return type === WorkspaceMemoryType.Issue || type === WorkspaceMemoryType.Todo;
+}
+
+export function normalizeWorkspaceMemoryStatus(value: unknown): WorkspaceMemoryStatus | undefined {
+  return typeof value === "string" && WORKSPACE_MEMORY_STATUS_SET.has(value)
+    ? (value as WorkspaceMemoryStatus)
+    : undefined;
+}
+
 export function validateWorkspaceMemoryInput(
   input: WorkspaceMemoryInput
 ): WorkspaceMemoryValidatedInput {
-  if (!isWorkspaceMemoryType(input.type)) {
+  const type = normalizeWorkspaceMemoryType(input.type);
+  if (!type) {
     throw new Error("Invalid memory type");
   }
 
@@ -84,9 +142,23 @@ export function validateWorkspaceMemoryInput(
     throw new Error("Memory content is required");
   }
 
+  const status =
+    input.status === undefined ? undefined : normalizeWorkspaceMemoryStatus(input.status);
+  if (input.status !== undefined && !status) {
+    throw new Error("Invalid memory status");
+  }
+
+  if (!isActionableWorkspaceMemoryType(type)) {
+    return {
+      type,
+      content,
+    };
+  }
+
   return {
-    type: input.type,
+    type,
     content,
+    status: status ?? WorkspaceMemoryStatus.NotStarted,
   };
 }
 
diff --git a/packages/core/src/domain/skill-management.test.ts b/packages/core/src/domain/skill-management.test.ts
index 9b149cddf..d7cac645c 100644
--- a/packages/core/src/domain/skill-management.test.ts
+++ b/packages/core/src/domain/skill-management.test.ts
@@ -1,8 +1,13 @@
-import type { SkillRecommendationEntry } from "./skill-management.js";
+import type {
+  SkillLibraryEntry,
+  SkillRecommendationEntry,
+  SkillRecommendationPage,
+} from "./skill-management.js";
 import {
   isSkillMountStatus,
   SKILL_INSTALL_STATES,
   SKILL_LIBRARY_ITEM_STATES,
+  SKILL_LIBRARY_ORIGINS,
   SKILL_LIBRARY_SOURCES,
   SKILL_MOUNT_STATUSES,
   SKILL_TARGET_HEALTH_STATES,
@@ -24,7 +29,11 @@ describe("skill management domain", () => {
   });
 
   it("exports stable skill library sources", () => {
-    expect(SKILL_LIBRARY_SOURCES).toEqual(["skillhub", "local", "builtin"]);
+    expect(SKILL_LIBRARY_SOURCES).toEqual(["builtin", "installed", "custom"]);
+  });
+
+  it("exports stable skill library origins", () => {
+    expect(SKILL_LIBRARY_ORIGINS).toEqual(["builtin", "skillhub", "filesystem"]);
   });
 
   it("exports stable mount statuses", () => {
@@ -69,4 +78,42 @@ describe("skill management domain", () => {
 
     expect(entry.slug).toBe("code-review");
   });
+
+  it("exports a stable skill recommendation page shape", () => {
+    const page: SkillRecommendationPage = {
+      entries: [
+        {
+          slug: "code-review",
+          displayName: "Code Review",
+          description: "Reviews code changes",
+          reason: "Matches the workspace test workflow",
+          sourceQuery: "test workflow",
+          score: 42,
+          installed: false,
+        },
+      ],
+      hasMore: true,
+    };
+
+    expect(page.entries[0]?.slug).toBe("code-review");
+    expect(page.hasMore).toBe(true);
+  });
+
+  it("exports a stable skill library entry shape with optional origin", () => {
+    const entry: SkillLibraryEntry = {
+      slug: "code-review",
+      displayName: "Code Review",
+      description: "Reviews code changes",
+      version: "1.0.0",
+      source: "installed",
+      origin: "skillhub",
+      libraryPath: "/skills/code-review",
+      installState: "installed",
+      installedAt: 1,
+      updatedAt: 2,
+    };
+
+    expect(entry.source).toBe("installed");
+    expect(entry.origin).toBe("skillhub");
+  });
 });
diff --git a/packages/core/src/domain/skill-management.ts b/packages/core/src/domain/skill-management.ts
index 55335ea1a..5658374cb 100644
--- a/packages/core/src/domain/skill-management.ts
+++ b/packages/core/src/domain/skill-management.ts
@@ -1,5 +1,6 @@
 export const SKILL_INSTALL_STATES = ["installed", "installing", "failed"] as const;
-export const SKILL_LIBRARY_SOURCES = ["skillhub", "local", "builtin"] as const;
+export const SKILL_LIBRARY_SOURCES = ["builtin", "installed", "custom"] as const;
+export const SKILL_LIBRARY_ORIGINS = ["builtin", "skillhub", "filesystem"] as const;
 export const SKILL_LIBRARY_ITEM_STATES = [
   "unmounted",
   "partially_mounted",
@@ -23,6 +24,7 @@ export const SKILL_TARGET_HEALTH_STATES = ["healthy", "warning", "error", "uncon
 
 type SkillInstallState = (typeof SKILL_INSTALL_STATES)[number];
 export type SkillLibrarySource = (typeof SKILL_LIBRARY_SOURCES)[number];
+export type SkillLibraryOrigin = (typeof SKILL_LIBRARY_ORIGINS)[number];
 type SkillMountStatus = (typeof SKILL_MOUNT_STATUSES)[number];
 export type SkillVersionCheckStatus = (typeof SKILL_VERSION_CHECK_STATUSES)[number];
 type SkillTargetHealthState = (typeof SKILL_TARGET_HEALTH_STATES)[number];
@@ -37,6 +39,7 @@ export interface SkillLibraryEntry {
   description?: string;
   version: string;
   source: SkillLibrarySource;
+  origin?: SkillLibraryOrigin;
   libraryPath: string;
   installState: SkillInstallState;
   installedAt: number;
@@ -58,6 +61,11 @@ export interface SkillRecommendationEntry {
   installed: boolean;
 }
 
+export interface SkillRecommendationPage {
+  entries: SkillRecommendationEntry[];
+  hasMore: boolean;
+}
+
 export interface SkillVersionCheckEntry {
   slug: string;
   currentVersion: string;
diff --git a/packages/core/src/domain/terminal-profiles.ts b/packages/core/src/domain/terminal-profiles.ts
new file mode 100644
index 000000000..c715ec42e
--- /dev/null
+++ b/packages/core/src/domain/terminal-profiles.ts
@@ -0,0 +1,24 @@
+export type TerminalProfileSource = "detected" | "custom";
+export type TerminalProfileRuntime = "native" | "wsl";
+
+export interface TerminalProfile {
+  id: string;
+  label: string;
+  source: TerminalProfileSource;
+  runtime: TerminalProfileRuntime;
+  icon: string;
+}
+
+export interface CustomTerminalProfile {
+  id: `custom:${string}`;
+  label: string;
+  command: string;
+  args?: string[];
+  icon?: string;
+}
+
+export interface TerminalProfilesListResult {
+  profiles: TerminalProfile[];
+  configuredDefaultProfileId?: string;
+  resolvedDefaultProfileId: string | null;
+}
diff --git a/packages/core/src/domain/types.test.ts b/packages/core/src/domain/types.test.ts
index da36c027e..a440f3635 100644
--- a/packages/core/src/domain/types.test.ts
+++ b/packages/core/src/domain/types.test.ts
@@ -15,6 +15,7 @@ import type {
   TaskRun,
   Terminal,
   TerminalKind,
+  WorkspaceCanvasEditorTab,
   WorkspaceHistoryEntry,
 } from "./types";
 import { deriveSessionTitle, normalizeSessionTitleInput, SESSION_TITLE_MAX_LENGTH } from "./types";
@@ -62,6 +63,12 @@ describe("normalizeSessionTitleInput", () => {
   it("returns undefined for whitespace-only input", () => {
     expect(normalizeSessionTitleInput("\n\t  ")).toBeUndefined();
   });
+
+  it("strips terminal escape sequences including SGR mouse reports", () => {
+    expect(normalizeSessionTitleInput("\x1b[<35;17;18M")).toBeUndefined();
+    expect(normalizeSessionTitleInput("<35;17;18M")).toBeUndefined();
+    expect(normalizeSessionTitleInput("\x1b[<35;17;18Mfix the build")).toBe("fix the build");
+  });
 });
 
 describe("SessionState", () => {
@@ -88,6 +95,19 @@ describe("WorkspaceHistoryEntry", () => {
   });
 });
 
+describe("WorkspaceCanvasEditorTab", () => {
+  it("is keyed by sourcePath with optional canvas compatibility metadata", () => {
+    expectTypeOf<WorkspaceCanvasEditorTab>().toEqualTypeOf<{
+      kind: "canvas";
+      id: string;
+      title: string;
+      sourcePath: string;
+      artifactType?: "architecture_canvas" | "report_canvas";
+      canvasId?: string;
+    }>();
+  });
+});
+
 describe("AgentContextKind", () => {
   it("covers the backend context package variants", () => {
     expectTypeOf<AgentContextKind>().toEqualTypeOf<
diff --git a/packages/core/src/domain/types.ts b/packages/core/src/domain/types.ts
index d79b7bc9c..b187d334e 100644
--- a/packages/core/src/domain/types.ts
+++ b/packages/core/src/domain/types.ts
@@ -68,6 +68,7 @@ export type WorkspacePaneNode = WorkspacePaneLeaf | WorkspacePaneSplit;
 export interface WorkspaceFileEditorTab {
   kind: "file";
   path: string;
+  pinned?: boolean;
 }
 
 export type DevBrowserDevicePreset = "desktop" | "iphone-14" | "pixel-7" | "custom";
@@ -85,13 +86,26 @@ export interface WorkspaceBrowserEditorTab {
   userAgentMode: DevBrowserUserAgentMode;
 }
 
-export type WorkspaceEditorTab = WorkspaceFileEditorTab | WorkspaceBrowserEditorTab;
+export interface WorkspaceCanvasEditorTab {
+  kind: "canvas";
+  id: string;
+  title: string;
+  sourcePath: string;
+  artifactType?: "architecture_canvas" | "report_canvas";
+  canvasId?: string;
+}
+
+export type WorkspaceEditorTab =
+  | WorkspaceFileEditorTab
+  | WorkspaceBrowserEditorTab
+  | WorkspaceCanvasEditorTab;
 
 export interface UiState {
   leftPanelWidth: number;
   bottomPanelHeight: number;
   focusMode: boolean;
   editorViewVisible?: boolean;
+  editorPinned?: boolean;
   activeSessionId?: string;
   paneLayout?: WorkspacePaneNode;
   fileTreeExpandedDirs?: string[];
@@ -720,12 +734,20 @@ export interface ProviderConfig {
   [key: string]: unknown;
 }
 
+const TERMINAL_CONTROL_SEQUENCE_FOR_SESSION_TITLE_PATTERN =
+  /\x1b\[[0-9;?<>]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1bP[\s\S]*?\x1b\\|\x1b[@-_]|<\d+(?:;\d+)*[Mm]/g;
+
+function stripTerminalControlSequences(raw: string): string {
+  return raw.replace(TERMINAL_CONTROL_SEQUENCE_FOR_SESSION_TITLE_PATTERN, "").replace(/\x1b/g, "");
+}
+
 /**
  * Derive a compact session title from a raw input buffer (the bytes a user
  * just submitted to the agent terminal). Returns undefined when the buffer
  * contains nothing meaningful after trimming.
  *
  * Rules:
+ *   - Strip terminal control/escape sequences (including SGR mouse reports).
  *   - Collapse all whitespace (including newlines) into single spaces.
  *   - Trim leading/trailing whitespace.
  *   - Truncate to SESSION_TITLE_MAX_LENGTH; if clipped, the final character is
@@ -733,7 +755,7 @@ export interface ProviderConfig {
  *     SESSION_TITLE_MAX_LENGTH.
  */
 export function normalizeSessionTitleInput(raw: string): string | undefined {
-  const normalized = raw.replace(/\s+/g, " ").trim();
+  const normalized = stripTerminalControlSequences(raw).replace(/\s+/g, " ").trim();
   return normalized || undefined;
 }
 
diff --git a/packages/core/src/domain/ui-actions.test.ts b/packages/core/src/domain/ui-actions.test.ts
index cee1e940e..68f046923 100644
--- a/packages/core/src/domain/ui-actions.test.ts
+++ b/packages/core/src/domain/ui-actions.test.ts
@@ -16,6 +16,7 @@ describe("ui action domain", () => {
       "editor.closeFile",
       "browser.openUrl",
       "browser.closeUrl",
+      "canvas.open",
       "workspace.focus",
       "panel.show",
       "command.run",
@@ -42,6 +43,26 @@ describe("ui action domain", () => {
         available: true,
       }
     );
+    expect(capabilities.find((capability) => capability.type === "canvas.open")).toMatchObject({
+      cli: "coder-studio ui open-canvas --canvas <canvas-id>",
+      description:
+        "Open a persisted canvas artifact in the built-in editor. Canonical dispatch payloads are sourcePath-first; canvasId remains a compatibility identifier and CLI path.",
+      inputSchema: {
+        workspaceId: "string optional",
+        title: "string required for canonical sourcePath payloads",
+        artifactType:
+          "architecture_canvas | report_canvas required for canonical sourcePath payloads",
+        sourcePath: "workspace-relative string required for canonical sourcePath payloads",
+        canvasId: "string optional compatibility identifier",
+      },
+      permissions: ["ui:navigate"],
+      riskLevel: "read",
+      available: true,
+    });
+    expect(capabilities.find((capability) => capability.type === "canvas.open")?.examples).toEqual([
+      '{"type":"canvas.open","workspaceId":"ws_123","title":"Runtime Flow","artifactType":"architecture_canvas","sourcePath":".coder-studio/canvases/runtime-flow.csc"}',
+      "coder-studio ui open-canvas --workspace ws_123 --canvas canvas_123 --json",
+    ]);
   });
 
   it("filters UI action capabilities by permissions", () => {
@@ -54,6 +75,7 @@ describe("ui action domain", () => {
       "editor.closeFile",
       "browser.openUrl",
       "browser.closeUrl",
+      "canvas.open",
       "workspace.focus",
       "panel.show",
     ]);
@@ -96,6 +118,10 @@ describe("ui action domain", () => {
       type: "browser.closeUrl",
       url: "http://127.0.0.1:5173/",
     });
+    expect(validateUiActionIntent({ type: "browser.openUrl", url: "http://[::1]:5173" })).toEqual({
+      type: "browser.openUrl",
+      url: "http://[::1]:5173/",
+    });
 
     expect(() =>
       validateUiActionIntent({ type: "browser.openUrl", url: "https://example.com" })
@@ -105,6 +131,94 @@ describe("ui action domain", () => {
     ).toThrow("localhost URLs");
   });
 
+  it("validates and normalizes canvas.open intents", () => {
+    expect(
+      validateUiActionIntent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        title: " Runtime Flow ",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      })
+    ).toEqual({
+      type: "canvas.open",
+      workspaceId: "ws-1",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+
+    expect(
+      validateUiActionIntent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: "   ",
+        title: " Runtime Flow ",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      })
+    ).toEqual({
+      type: "canvas.open",
+      workspaceId: "ws-1",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+
+    expect(
+      validateUiActionIntent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: " canvas-1 ",
+      })
+    ).toEqual({
+      type: "canvas.open",
+      workspaceId: "ws-1",
+      canvasId: "canvas-1",
+    });
+
+    expect(() =>
+      validateUiActionIntent({
+        type: "canvas.open",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+      })
+    ).toThrow("canvas.open requires title, artifactType, and sourcePath when metadata is provided");
+
+    expect(() =>
+      validateUiActionIntent({
+        type: "canvas.open",
+      })
+    ).toThrow("canvas.open requires canvasId or sourcePath metadata");
+
+    expect(() =>
+      validateUiActionIntent({
+        type: "canvas.open",
+        title: "   ",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      })
+    ).toThrow("canvas.open title must not be empty");
+
+    expect(() =>
+      validateUiActionIntent({
+        type: "canvas.open",
+        title: "Runtime Flow",
+        artifactType: "bogus" as never,
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      })
+    ).toThrow("canvas.open artifactType must be architecture_canvas or report_canvas");
+
+    expect(() =>
+      validateUiActionIntent({
+        type: "canvas.open",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: "../runtime.canvas.json",
+      })
+    ).toThrow("workspace-relative");
+  });
+
   it("rejects non-allowlisted command.run ids", () => {
     expect(validateUiActionIntent({ type: "command.run", commandId: "quickOpen.open" })).toEqual({
       type: "command.run",
diff --git a/packages/core/src/domain/ui-actions.ts b/packages/core/src/domain/ui-actions.ts
index 69921cfa1..f09703d6d 100644
--- a/packages/core/src/domain/ui-actions.ts
+++ b/packages/core/src/domain/ui-actions.ts
@@ -1,49 +1,93 @@
 import { Topics } from "../protocol/topics.js";
 import type { AutomationPermission } from "./automation.js";
+import { CanvasArtifactKind } from "./canvas.js";
 
 export type UiActionRiskLevel = "read" | "write" | "dangerous";
 export type UiPanelId = "terminal" | "explorer" | "search" | "git" | "skills" | "agentInstructions";
 export type UiCommandId = "quickOpen.open" | "commandPalette.open";
 
+type EditorOpenFileUiActionIntent = {
+  type: "editor.openFile";
+  workspaceId?: string;
+  path: string;
+  line?: number;
+  column?: number;
+  target?: "active" | "newPane" | { paneId: string };
+};
+
+type EditorCloseFileUiActionIntent = {
+  type: "editor.closeFile";
+  workspaceId?: string;
+  path: string;
+};
+
+type BrowserOpenUrlUiActionIntent = {
+  type: "browser.openUrl";
+  workspaceId?: string;
+  url: string;
+  target?: "preview" | "external";
+};
+
+type BrowserCloseUrlUiActionIntent = {
+  type: "browser.closeUrl";
+  workspaceId?: string;
+  url: string;
+};
+
+export type CanvasOpenUiActionIntent = {
+  type: "canvas.open";
+  workspaceId?: string;
+  title: string;
+  artifactType: CanvasArtifactKind;
+  sourcePath: string;
+  canvasId?: string;
+};
+
+export type CanvasOpenUiActionDispatchIntent = {
+  type: "canvas.open";
+  workspaceId?: string;
+  canvasId?: string;
+  title?: string;
+  artifactType?: CanvasArtifactKind;
+  sourcePath?: string;
+};
+
+type WorkspaceFocusUiActionIntent = {
+  type: "workspace.focus";
+  workspaceId: string;
+};
+
+type PanelShowUiActionIntent = {
+  type: "panel.show";
+  workspaceId?: string;
+  panel: UiPanelId;
+};
+
+type CommandRunUiActionIntent = {
+  type: "command.run";
+  commandId: UiCommandId;
+  args?: Record<string, unknown>;
+};
+
 export type UiActionIntent =
-  | {
-      type: "editor.openFile";
-      workspaceId?: string;
-      path: string;
-      line?: number;
-      column?: number;
-      target?: "active" | "newPane" | { paneId: string };
-    }
-  | {
-      type: "editor.closeFile";
-      workspaceId?: string;
-      path: string;
-    }
-  | {
-      type: "browser.openUrl";
-      workspaceId?: string;
-      url: string;
-      target?: "preview" | "external";
-    }
-  | {
-      type: "browser.closeUrl";
-      workspaceId?: string;
-      url: string;
-    }
-  | {
-      type: "workspace.focus";
-      workspaceId: string;
-    }
-  | {
-      type: "panel.show";
-      workspaceId?: string;
-      panel: UiPanelId;
-    }
-  | {
-      type: "command.run";
-      commandId: UiCommandId;
-      args?: Record<string, unknown>;
-    };
+  | EditorOpenFileUiActionIntent
+  | EditorCloseFileUiActionIntent
+  | BrowserOpenUrlUiActionIntent
+  | BrowserCloseUrlUiActionIntent
+  | CanvasOpenUiActionIntent
+  | WorkspaceFocusUiActionIntent
+  | PanelShowUiActionIntent
+  | CommandRunUiActionIntent;
+
+export type UiActionDispatchIntent =
+  | EditorOpenFileUiActionIntent
+  | EditorCloseFileUiActionIntent
+  | BrowserOpenUrlUiActionIntent
+  | BrowserCloseUrlUiActionIntent
+  | CanvasOpenUiActionDispatchIntent
+  | WorkspaceFocusUiActionIntent
+  | PanelShowUiActionIntent
+  | CommandRunUiActionIntent;
 
 export interface UiActionDescriptor {
   type: UiActionIntent["type"];
@@ -57,7 +101,7 @@ export interface UiActionDescriptor {
 }
 
 export interface UiActionDispatchRequest {
-  intent: UiActionIntent;
+  intent: UiActionDispatchIntent;
   source?: {
     kind: "agent" | "user" | "system";
     sessionId?: string;
@@ -80,6 +124,10 @@ export interface UiActionEvent {
   dispatchedAt: number;
 }
 
+export interface UiActionEventRequest extends Omit<UiActionDispatchRequest, "intent"> {
+  intent: UiActionIntent;
+}
+
 export const ALLOWED_UI_COMMAND_IDS: readonly UiCommandId[] = [
   "quickOpen.open",
   "commandPalette.open",
@@ -142,6 +190,27 @@ const UI_ACTION_CAPABILITIES: UiActionDescriptor[] = [
     available: true,
     examples: ["coder-studio ui close-url --url http://127.0.0.1:5173 --json"],
   },
+  {
+    type: "canvas.open",
+    cli: "coder-studio ui open-canvas --canvas <canvas-id>",
+    description:
+      "Open a persisted canvas artifact in the built-in editor. Canonical dispatch payloads are sourcePath-first; canvasId remains a compatibility identifier and CLI path.",
+    inputSchema: {
+      workspaceId: "string optional",
+      title: "string required for canonical sourcePath payloads",
+      artifactType:
+        "architecture_canvas | report_canvas required for canonical sourcePath payloads",
+      sourcePath: "workspace-relative string required for canonical sourcePath payloads",
+      canvasId: "string optional compatibility identifier",
+    },
+    permissions: ["ui:navigate"],
+    riskLevel: "read",
+    available: true,
+    examples: [
+      '{"type":"canvas.open","workspaceId":"ws_123","title":"Runtime Flow","artifactType":"architecture_canvas","sourcePath":".coder-studio/canvases/runtime-flow.csc"}',
+      "coder-studio ui open-canvas --workspace ws_123 --canvas canvas_123 --json",
+    ],
+  },
   {
     type: "workspace.focus",
     cli: "coder-studio ui focus-workspace --workspace <workspace-id>",
@@ -225,6 +294,7 @@ export function normalizeLocalhostUrl(url: string): string {
     hostname === "localhost" ||
     hostname === "127.0.0.1" ||
     hostname === "::1" ||
+    hostname === "[::1]" ||
     hostname.endsWith(".localhost");
   if (!isLocalhost) {
     throw new Error("browser.openUrl only supports localhost URLs");
@@ -233,7 +303,7 @@ export function normalizeLocalhostUrl(url: string): string {
   return parsed.toString();
 }
 
-export function validateUiActionIntent(intent: UiActionIntent): UiActionIntent {
+export function validateUiActionIntent(intent: UiActionDispatchIntent): UiActionDispatchIntent {
   switch (intent.type) {
     case "editor.openFile": {
       if (!isSafeWorkspaceRelativePath(intent.path)) {
@@ -253,6 +323,66 @@ export function validateUiActionIntent(intent: UiActionIntent): UiActionIntent {
       return { ...intent, url: normalizeLocalhostUrl(intent.url) };
     case "browser.closeUrl":
       return { ...intent, url: normalizeLocalhostUrl(intent.url) };
+    case "canvas.open": {
+      const { canvasId: _rawCanvasId, ...restIntent } = intent;
+      const canvasId = intent.canvasId?.trim() || undefined;
+
+      const hasAnyMetadata =
+        intent.title !== undefined ||
+        intent.artifactType !== undefined ||
+        intent.sourcePath !== undefined;
+      const hasAllMetadata =
+        intent.title !== undefined &&
+        intent.artifactType !== undefined &&
+        intent.sourcePath !== undefined;
+      if (hasAnyMetadata && !hasAllMetadata) {
+        throw new Error(
+          "canvas.open requires title, artifactType, and sourcePath when metadata is provided"
+        );
+      }
+
+      if (!canvasId && !hasAllMetadata) {
+        throw new Error("canvas.open requires canvasId or sourcePath metadata");
+      }
+
+      if (!hasAllMetadata) {
+        return {
+          ...restIntent,
+          ...(canvasId ? { canvasId } : {}),
+        };
+      }
+
+      const sourcePathInput = intent.sourcePath;
+      const titleInput = intent.title;
+      const artifactType = intent.artifactType;
+      if (sourcePathInput === undefined || titleInput === undefined || artifactType === undefined) {
+        throw new Error(
+          "canvas.open requires title, artifactType, and sourcePath when metadata is provided"
+        );
+      }
+
+      const sourcePath = sourcePathInput.trim();
+      if (!isSafeWorkspaceRelativePath(sourcePath)) {
+        throw new Error("canvas.open sourcePath must be workspace-relative");
+      }
+
+      const title = titleInput.trim();
+      if (!title) {
+        throw new Error("canvas.open title must not be empty");
+      }
+
+      if (!CanvasArtifactKind.safeParse(artifactType).success) {
+        throw new Error("canvas.open artifactType must be architecture_canvas or report_canvas");
+      }
+
+      return {
+        ...restIntent,
+        ...(canvasId ? { canvasId } : {}),
+        artifactType,
+        title,
+        sourcePath,
+      };
+    }
     case "workspace.focus":
       if (!intent.workspaceId) {
         throw new Error("workspace.focus requires workspaceId");
@@ -268,13 +398,11 @@ export function validateUiActionIntent(intent: UiActionIntent): UiActionIntent {
   }
 }
 
-export function normalizeUiActionDispatchRequest(
-  request: UiActionDispatchRequest
-): UiActionDispatchRequest {
+export function normalizeUiActionDispatchRequest<T extends UiActionDispatchRequest>(request: T): T {
   return {
     ...request,
     intent: validateUiActionIntent(request.intent),
-  };
+  } as T;
 }
 
 export function resolveUiActionWorkspaceId(
@@ -298,7 +426,7 @@ function createRequestId(): string {
 }
 
 export function createUiActionEvent(input: {
-  request: UiActionDispatchRequest;
+  request: UiActionEventRequest;
   workspaceId: string;
   dispatchedAt: number;
 }): UiActionEvent {
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index cc6faaa93..2992a18c5 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1,6 +1,7 @@
 // Protocol
 
 export * from "./domain/automation";
+export * from "./domain/canvas";
 export * from "./domain/diagnostics";
 export * from "./domain/events";
 export * from "./domain/lsp";
@@ -11,6 +12,7 @@ export * from "./domain/provider-install";
 export * from "./domain/skill-management";
 export * from "./domain/supervisor";
 export * from "./domain/system-dependency-install";
+export * from "./domain/terminal-profiles";
 // Domain
 export * from "./domain/types";
 export * from "./domain/ui-actions";
diff --git a/packages/providers/src/cursor/definition.test.ts b/packages/providers/src/cursor/definition.test.ts
index 598ff9569..8d1ad44c4 100644
--- a/packages/providers/src/cursor/definition.test.ts
+++ b/packages/providers/src/cursor/definition.test.ts
@@ -49,12 +49,9 @@ describe("cursorDefinition", () => {
     expect(cursorDefinition.idleHeuristics?.idleDebounceMs).toBe(4000);
   });
 
-  it("supports skills mount through Cursor and shared skill directories", () => {
+  it("supports skills mount only through the Cursor-native skills directory", () => {
     expect(cursorDefinition.supportsSkillsMount).toBe(true);
-    expect(cursorDefinition.skillMountDirectories).toEqual([
-      join(homedir(), ".agents", "skills"),
-      join(homedir(), ".cursor", "skills"),
-    ]);
+    expect(cursorDefinition.skillMountDirectories).toEqual([join(homedir(), ".cursor", "skills")]);
   });
 
   it("supports agent_instructions_generate in headless mode", () => {
diff --git a/packages/providers/src/cursor/definition.ts b/packages/providers/src/cursor/definition.ts
index efea3f317..b8feeee3d 100644
--- a/packages/providers/src/cursor/definition.ts
+++ b/packages/providers/src/cursor/definition.ts
@@ -1,6 +1,7 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 import type { ProviderConfig, ProviderDefinition } from "@coder-studio/core";
 import { debounceIdleHeuristics } from "../debounce-idle-heuristics.js";
-import { sharedFirstSkillMountDirectories } from "../skills/directories.js";
 import { type CursorConfig, cursorConfigSchema } from "./config-schema.js";
 import { buildCursorSupervisorEvalCommand } from "./supervisor-eval.js";
 
@@ -43,7 +44,7 @@ export const cursorDefinition: ProviderDefinition = {
   stability: "stable",
   supportsAgentInstructions: true,
   supportsSkillsMount: true,
-  skillMountDirectories: sharedFirstSkillMountDirectories(".cursor"),
+  skillMountDirectories: [join(homedir(), ".cursor", "skills")],
   capability: "full",
   capabilities: [
     { key: "interactive_session", supported: true, label: "Interactive session" },
diff --git a/packages/server/package.json b/packages/server/package.json
index 54bb2f600..2bb43c478 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -43,6 +43,7 @@
     "fastify": "^5.8.5",
     "ignore": "^7.0.0",
     "markdown-it": "^14.1.0",
+    "mermaid": "^11.15.0",
     "mime-types": "^2.1.35",
     "node-pty": "^1.1.0",
     "pino-pretty": "^13.1.3",
diff --git a/packages/server/src/__tests__/activation-commands.test.ts b/packages/server/src/__tests__/activation-commands.test.ts
index e073e3f7b..995d258b9 100644
--- a/packages/server/src/__tests__/activation-commands.test.ts
+++ b/packages/server/src/__tests__/activation-commands.test.ts
@@ -1,15 +1,21 @@
 import type { FastifyRequest } from "fastify";
 import { describe, expect, it, vi } from "vitest";
+import type { RequestAuthContext } from "../auth/plugin.js";
 import { ActivationManager } from "../ws/activation.js";
 import { type CommandContext, dispatch } from "../ws/dispatch.js";
 import type { Broadcaster } from "../ws/hub.js";
 import "../commands/activation.js";
+import "../commands/automation.js";
+import "../commands/canvas.js";
+import "../commands/memory.js";
 import "../commands/workspace.js";
+import "../commands/ui-actions.js";
 
-function createMockRequest(): FastifyRequest {
+function createMockRequest(authContext?: RequestAuthContext): FastifyRequest {
   return {
     ip: "127.0.0.1",
     headers: { "user-agent": "test-agent" },
+    ...(authContext ? { coderStudioAuthContext: authContext } : {}),
   } as unknown as FastifyRequest;
 }
 
@@ -22,7 +28,9 @@ function createBaseContext(overrides?: {
       list: vi.fn(() => [{ id: "workspace-1" }]),
     } as unknown as CommandContext["workspaceMgr"],
     sessionMgr: {} as never,
-    terminalMgr: {} as never,
+    terminalMgr: {
+      getRingBufferTail: vi.fn(() => Buffer.from("tail")),
+    } as unknown as CommandContext["terminalMgr"],
     eventBus: {} as never,
     broadcaster:
       overrides?.broadcaster ??
@@ -36,6 +44,59 @@ function createBaseContext(overrides?: {
     supervisorMgr: {} as never,
     autoFetch: {} as never,
     activationMgr: overrides?.activationMgr ?? new ActivationManager(),
+    memoryRepo: {
+      list: vi.fn(() => []),
+      get: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+    } as never,
+    canvasService: {
+      list: vi.fn(async (workspaceId: string) =>
+        workspaceId === "workspace-1" ? [{ id: "canvas-1", workspaceId }] : []
+      ),
+    } as never,
+    workspaceMgr: {
+      list: vi.fn(() => [{ id: "workspace-1" }]),
+      get: vi.fn((workspaceId: string) =>
+        workspaceId === "workspace-1" ? { id: "workspace-1", path: "/repo" } : undefined
+      ),
+    } as unknown as CommandContext["workspaceMgr"],
+    sessionMgr: {
+      getForWorkspace: vi.fn((workspaceId: string) =>
+        workspaceId === "workspace-1"
+          ? [
+              {
+                id: "sess-1",
+                workspaceId: "workspace-1",
+                terminalId: "term-1",
+                providerId: "codex",
+                state: "running",
+                capability: "full",
+                startedAt: 1,
+                lastActiveAt: 1,
+              },
+            ]
+          : []
+      ),
+      get: vi.fn((sessionId: string) =>
+        sessionId === "sess-1"
+          ? {
+              id: "sess-1",
+              workspaceId: "workspace-1",
+              terminalId: "term-1",
+              providerId: "codex",
+              state: "running",
+              capability: "full",
+              startedAt: 1,
+              lastActiveAt: 1,
+            }
+          : undefined
+      ),
+      findSessionIdByTerminal: vi.fn((terminalId: string) =>
+        terminalId === "term-1" ? "sess-1" : undefined
+      ),
+    } as unknown as CommandContext["sessionMgr"],
   };
 }
 
@@ -264,4 +325,236 @@ describe("activation commands", () => {
     expect(result.ok).toBe(true);
     expect(result.data).toEqual([{ id: "workspace-1" }]);
   });
+
+  it("allows token-auth websocket commands within the scoped permission set without an active lease", async () => {
+    const request = createMockRequest({
+      mode: "session_token",
+      token: "tok-1",
+      sessionId: "sess-1",
+      workspaceId: "workspace-1",
+      providerId: "codex",
+      permissions: ["session:read", "memory:read", "ui:command"],
+      createdAt: 1,
+    });
+    const broadcaster = {
+      broadcast: vi.fn(),
+      sendToClient: vi.fn(() => true),
+      sendBinaryToClient: vi.fn(() => true),
+      getRequestMetadata: vi.fn(() => request),
+    } satisfies Broadcaster;
+    const ctx = createBaseContext({ broadcaster });
+
+    const memoryList = await dispatch(
+      {
+        kind: "command",
+        id: "token-memory-list",
+        op: "memory.list",
+        args: { workspaceId: "workspace-1" },
+      },
+      ctx,
+      "ws-token"
+    );
+
+    const uiDispatch = await dispatch(
+      {
+        kind: "command",
+        id: "token-ui-dispatch",
+        op: "uiAction.dispatch",
+        args: {
+          workspaceId: "workspace-1",
+          intent: { type: "command.run", commandId: "quickOpen.open" },
+        },
+      },
+      ctx,
+      "ws-token"
+    );
+
+    expect(memoryList.ok).toBe(true);
+    expect(uiDispatch.ok).toBe(true);
+  });
+
+  it("rejects token-auth websocket commands outside the scoped permission set", async () => {
+    const request = createMockRequest({
+      mode: "session_token",
+      token: "tok-2",
+      sessionId: "sess-1",
+      workspaceId: "workspace-1",
+      providerId: "codex",
+      permissions: ["session:read"],
+      createdAt: 1,
+    });
+    const broadcaster = {
+      broadcast: vi.fn(),
+      sendToClient: vi.fn(() => true),
+      sendBinaryToClient: vi.fn(() => true),
+      getRequestMetadata: vi.fn(() => request),
+    } satisfies Broadcaster;
+    const ctx = createBaseContext({ broadcaster });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "token-workspace-list",
+        op: "workspace.list",
+        args: {},
+      },
+      ctx,
+      "ws-token"
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toEqual({
+      code: "permission_denied",
+      message: "Token is not authorized for this command",
+    });
+  });
+
+  it("allows token-auth websocket canvas commands within the scoped permission set", async () => {
+    const request = createMockRequest({
+      mode: "session_token",
+      token: "tok-canvas-1",
+      sessionId: "sess-1",
+      workspaceId: "workspace-1",
+      providerId: "codex",
+      permissions: ["memory:read"],
+      createdAt: 1,
+    });
+    const broadcaster = {
+      broadcast: vi.fn(),
+      sendToClient: vi.fn(() => true),
+      sendBinaryToClient: vi.fn(() => true),
+      getRequestMetadata: vi.fn(() => request),
+    } satisfies Broadcaster;
+    const ctx = createBaseContext({ broadcaster });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "token-canvas-list",
+        op: "canvas.list",
+        args: { workspaceId: "workspace-1" },
+      },
+      ctx,
+      "ws-token"
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual([{ id: "canvas-1", workspaceId: "workspace-1" }]);
+  });
+
+  it("rejects token-auth websocket commands that target another workspace", async () => {
+    const request = createMockRequest({
+      mode: "session_token",
+      token: "tok-3",
+      sessionId: "sess-1",
+      workspaceId: "workspace-1",
+      providerId: "codex",
+      permissions: ["memory:read"],
+      createdAt: 1,
+    });
+    const broadcaster = {
+      broadcast: vi.fn(),
+      sendToClient: vi.fn(() => true),
+      sendBinaryToClient: vi.fn(() => true),
+      getRequestMetadata: vi.fn(() => request),
+    } satisfies Broadcaster;
+    const ctx = createBaseContext({ broadcaster });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "token-memory-cross-workspace",
+        op: "memory.list",
+        args: { workspaceId: "workspace-2" },
+      },
+      ctx,
+      "ws-token"
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toEqual({
+      code: "permission_denied",
+      message: "Token is not authorized for the requested workspace",
+    });
+  });
+
+  it("rejects token-auth uiAction.dispatch when payload workspace ids conflict", async () => {
+    const request = createMockRequest({
+      mode: "session_token",
+      token: "tok-ui-cross-workspace",
+      sessionId: "sess-1",
+      workspaceId: "workspace-1",
+      providerId: "codex",
+      permissions: ["ui:navigate"],
+      createdAt: 1,
+    });
+    const broadcaster = {
+      broadcast: vi.fn(),
+      sendToClient: vi.fn(() => true),
+      sendBinaryToClient: vi.fn(() => true),
+      getRequestMetadata: vi.fn(() => request),
+    } satisfies Broadcaster;
+    const ctx = createBaseContext({ broadcaster });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "token-ui-cross-workspace",
+        op: "uiAction.dispatch",
+        args: {
+          workspaceId: "workspace-1",
+          intent: {
+            type: "editor.openFile",
+            workspaceId: "workspace-2",
+            path: "src/index.ts",
+          },
+        },
+      },
+      ctx,
+      "ws-token"
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toEqual({
+      code: "permission_denied",
+      message: "Token is not authorized for the requested workspace",
+    });
+  });
+
+  it("rejects token-auth websocket terminal reads for another session", async () => {
+    const request = createMockRequest({
+      mode: "session_token",
+      token: "tok-4",
+      sessionId: "sess-1",
+      workspaceId: "workspace-1",
+      providerId: "codex",
+      permissions: ["terminal:read"],
+      createdAt: 1,
+    });
+    const broadcaster = {
+      broadcast: vi.fn(),
+      sendToClient: vi.fn(() => true),
+      sendBinaryToClient: vi.fn(() => true),
+      getRequestMetadata: vi.fn(() => request),
+    } satisfies Broadcaster;
+    const ctx = createBaseContext({ broadcaster });
+    ctx.sessionMgr.findSessionIdByTerminal = vi.fn(() => "sess-other");
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "token-terminal-cross-session",
+        op: "terminal.read",
+        args: { terminalId: "term-2" },
+      },
+      ctx,
+      "ws-token"
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toEqual({
+      code: "permission_denied",
+      message: "Token is not authorized for the requested session",
+    });
+  });
 });
diff --git a/packages/server/src/__tests__/automation/commands.test.ts b/packages/server/src/__tests__/automation/commands.test.ts
index 4fa1cc234..c6c02ce67 100644
--- a/packages/server/src/__tests__/automation/commands.test.ts
+++ b/packages/server/src/__tests__/automation/commands.test.ts
@@ -1,6 +1,7 @@
 import {
   type AutomationPermission,
   DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
+  SCOPED_SESSION_AUTOMATION_PERMISSIONS,
 } from "@coder-studio/core";
 import { describe, expect, it } from "vitest";
 import type { CommandContext } from "../../ws/dispatch.js";
@@ -93,4 +94,41 @@ describe("automation commands", () => {
     );
     expect(DEFAULT_AGENT_AUTOMATION_PERMISSIONS).toContain("git:read");
   });
+
+  it("uses scoped token permissions from websocket auth context when no permissions are supplied", async () => {
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "automation-capabilities-token-default-1",
+        op: "automation.capabilities",
+        args: {},
+      },
+      createBaseContext({
+        broadcaster: {
+          getRequestMetadata: () =>
+            ({
+              coderStudioAuthContext: {
+                mode: "session_token",
+                token: "tok-1",
+                sessionId: "sess-1",
+                workspaceId: "ws-1",
+                providerId: "codex",
+                permissions: SCOPED_SESSION_AUTOMATION_PERMISSIONS,
+                createdAt: 1,
+              },
+            }) as never,
+        } as never,
+      }),
+      "ws-token"
+    );
+
+    expect(result.ok).toBe(true);
+    const commands = (result.data as { commands: Array<{ name: string }> }).commands;
+    expect(commands).toEqual(
+      expect.arrayContaining([expect.objectContaining({ name: "git.status" })])
+    );
+    expect(commands).not.toEqual(
+      expect.arrayContaining([expect.objectContaining({ name: "workspace.list" })])
+    );
+  });
 });
diff --git a/packages/server/src/__tests__/dispatch.test.ts b/packages/server/src/__tests__/dispatch.test.ts
index 0d5719d1d..6c70cadb1 100644
--- a/packages/server/src/__tests__/dispatch.test.ts
+++ b/packages/server/src/__tests__/dispatch.test.ts
@@ -4,7 +4,13 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { z } from "zod";
+import { WorkspaceRuntimeBindingStore } from "../host/workspace-runtime-binding.js";
 import type { CommandContext } from "../ws/dispatch.js";
+import {
+  clearHostCommandsForTest,
+  clearRuntimeCommandsForTest,
+  registerRuntimeCommand,
+} from "../ws/index.js";
 import "../commands/workspace-activity.js";
 import "../commands/ui-actions.js";
 import { dispatch, getRegisteredCommands, registerCommand } from "../ws/dispatch.js";
@@ -13,6 +19,7 @@ describe("Command Dispatch", () => {
   let ctx: CommandContext;
 
   beforeEach(() => {
+    const runtimeBindings = new WorkspaceRuntimeBindingStore();
     ctx = {
       workspaceMgr: {},
       sessionMgr: {},
@@ -23,11 +30,24 @@ describe("Command Dispatch", () => {
         registerViewer: vi.fn(),
         unregisterViewer: vi.fn(),
       },
+      activationMgr: {
+        getLease: vi.fn(),
+      },
+      runtimeRouter: {
+        executeOnTarget: vi.fn(),
+      },
+      runtimeBindings,
+      settingsRepo: {},
+      providerRegistry: [],
     } as CommandContext;
+    clearHostCommandsForTest();
+    clearRuntimeCommandsForTest();
   });
 
   afterEach(() => {
     vi.useRealTimers();
+    clearHostCommandsForTest();
+    clearRuntimeCommandsForTest();
   });
 
   describe("registerCommand", () => {
@@ -233,5 +253,120 @@ describe("Command Dispatch", () => {
       expect(result.ok).toBe(true);
       expect(broadcast).toHaveBeenCalled();
     });
+
+    it("routes explicit runtime commands through the runtime router", async () => {
+      registerRuntimeCommand(
+        "runtime.echo",
+        z.object({
+          workspaceId: z.string(),
+          value: z.number(),
+        }),
+        {
+          resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+          handler: async () => ({ echoed: true }),
+        }
+      );
+      const executeOnTarget = vi.fn().mockResolvedValue({ echoed: 42 });
+      ctx = {
+        ...ctx,
+        runtimeRouter: {
+          executeOnTarget,
+        },
+      } as CommandContext;
+
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "runtime-echo-1",
+          op: "runtime.echo",
+          args: {
+            workspaceId: "ws-1",
+            value: 42,
+          },
+        },
+        ctx,
+        "runtime-client"
+      );
+
+      expect(result).toEqual({
+        kind: "result",
+        id: "runtime-echo-1",
+        ok: true,
+        data: { echoed: 42 },
+      });
+      expect(executeOnTarget).toHaveBeenCalledWith(
+        { kind: "workspace", workspaceId: "ws-1" },
+        "runtime.echo",
+        { workspaceId: "ws-1", value: 42 },
+        { authContext: undefined, clientId: "runtime-client" }
+      );
+    });
+
+    it("authorizes terminal.read session tokens via runtime binding projections", async () => {
+      registerCommand(
+        "terminal.read",
+        z.object({
+          terminalId: z.string(),
+        }),
+        async (args) => ({
+          terminalId: args.terminalId,
+        })
+      );
+      const runtimeBindings = new WorkspaceRuntimeBindingStore();
+      runtimeBindings.bindSession({
+        id: "sess-other",
+        workspaceId: "ws-1",
+        terminalId: "term-1",
+        providerId: "codex",
+        state: "running",
+        capability: "full",
+        startedAt: 1,
+        lastActiveAt: 1,
+      });
+      const findSessionIdByTerminal = vi.fn(() => {
+        throw new Error("dispatch should use runtime binding projections for terminal scope");
+      });
+      ctx = {
+        ...ctx,
+        broadcaster: {
+          getRequestMetadata: () =>
+            ({
+              coderStudioAuthContext: {
+                mode: "session_token",
+                token: "token-1",
+                sessionId: "sess-allowed",
+                workspaceId: "ws-1",
+                providerId: "codex",
+                permissions: ["terminal:read"],
+                createdAt: 1,
+              },
+            }) as never,
+        } as never,
+        runtimeBindings,
+        sessionMgr: {
+          findSessionIdByTerminal,
+        },
+      } as CommandContext;
+
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "terminal-read-auth-1",
+          op: "terminal.read",
+          args: {
+            terminalId: "term-1",
+          },
+        },
+        ctx,
+        "session-token-client"
+      );
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toEqual({
+        code: "permission_denied",
+        message: "Token is not authorized for the requested session",
+      });
+      expect(findSessionIdByTerminal).not.toHaveBeenCalled();
+    });
   });
 });
diff --git a/packages/server/src/__tests__/host-command-registry.test.ts b/packages/server/src/__tests__/host-command-registry.test.ts
new file mode 100644
index 000000000..885acb214
--- /dev/null
+++ b/packages/server/src/__tests__/host-command-registry.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import {
+  clearHostCommandsForTest,
+  getHostCommandDefinition,
+  registerHostCommand,
+} from "../host/command-registry.js";
+
+describe("host command registry", () => {
+  it("stores host command definitions by op", () => {
+    clearHostCommandsForTest();
+    registerHostCommand("host.test", z.object({ value: z.number() }), async (args) => ({
+      doubled: args.value * 2,
+    }));
+
+    const definition = getHostCommandDefinition("host.test");
+    expect(definition?.schema.parse({ value: 2 })).toEqual({ value: 2 });
+  });
+});
diff --git a/packages/server/src/__tests__/runtime-command-registry.test.ts b/packages/server/src/__tests__/runtime-command-registry.test.ts
new file mode 100644
index 000000000..03712741c
--- /dev/null
+++ b/packages/server/src/__tests__/runtime-command-registry.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import {
+  clearRuntimeCommandsForTest,
+  getRegisteredRuntimeCommands,
+  getRuntimeCommandDefinition,
+  registerRuntimeCommand,
+} from "../runtime/command-registry.js";
+
+describe("runtime command registry", () => {
+  it("keeps route resolution metadata next to the runtime handler", () => {
+    clearRuntimeCommandsForTest();
+    registerRuntimeCommand("runtime.test", z.object({ workspaceId: z.string() }), {
+      resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+      handler: async () => ({ ok: true }),
+    });
+
+    const definition = getRuntimeCommandDefinition("runtime.test");
+    expect(definition?.resolveTarget({ workspaceId: "ws-1" })).toEqual({
+      kind: "workspace",
+      workspaceId: "ws-1",
+    });
+  });
+
+  it("keeps internal runtime commands registered while hiding them from public listings", () => {
+    clearRuntimeCommandsForTest();
+    registerRuntimeCommand("runtime.internal", z.object({ workspaceId: z.string() }), {
+      visibility: "internal",
+      resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+      handler: async () => ({ ok: true }),
+    });
+
+    expect(getRuntimeCommandDefinition("runtime.internal")).toBeDefined();
+    expect(
+      getRuntimeCommandDefinition("runtime.internal", { includeInternal: false })
+    ).toBeUndefined();
+    expect(getRegisteredRuntimeCommands()).not.toContain("runtime.internal");
+  });
+});
diff --git a/packages/server/src/__tests__/runtime-router.test.ts b/packages/server/src/__tests__/runtime-router.test.ts
new file mode 100644
index 000000000..9c8d35a5f
--- /dev/null
+++ b/packages/server/src/__tests__/runtime-router.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from "vitest";
+import { RuntimeRegistry } from "../host/runtime-registry.js";
+import { RuntimeRouter } from "../host/runtime-router.js";
+import { WorkspaceRuntimeBindingStore } from "../host/workspace-runtime-binding.js";
+
+describe("RuntimeRouter", () => {
+  it("resolves workspace, session, terminal, and default targets", async () => {
+    const bindings = new WorkspaceRuntimeBindingStore();
+    bindings.bindWorkspace("ws-1", "native-default");
+    bindings.bindSession({
+      id: "sess-1",
+      workspaceId: "ws-1",
+      terminalId: "term-1",
+      providerId: "codex",
+      state: "running",
+      capability: "full",
+      startedAt: 1,
+      lastActiveAt: 1,
+    });
+    bindings.bindTerminal({
+      id: "term-1",
+      workspaceId: "ws-1",
+      kind: "agent",
+      title: "agent",
+      cwd: "/repo",
+      argv: [],
+      cols: 120,
+      rows: 30,
+      alive: true,
+      createdAt: 1,
+    });
+
+    const execute = vi.fn(async () => ({ ok: true }));
+    const registry = new RuntimeRegistry();
+    registry.register({
+      id: "native-default",
+      kind: "native",
+      execute,
+      disposeWorkspace: vi.fn(),
+      health: async () => ({ ok: true }),
+    });
+
+    const router = new RuntimeRouter({
+      runtimeRegistry: registry,
+      bindings,
+      defaultRuntimeId: "native-default",
+    });
+
+    await router.executeOnTarget({ kind: "workspace", workspaceId: "ws-1" }, "file.read", {});
+    await router.executeOnTarget({ kind: "session", sessionId: "sess-1" }, "session.stop", {});
+    await router.executeOnTarget({ kind: "terminal", terminalId: "term-1" }, "terminal.read", {});
+    await router.executeOnTarget({ kind: "default" }, "skills.library.list", {});
+
+    expect(execute).toHaveBeenCalledTimes(4);
+  });
+});
diff --git a/packages/server/src/__tests__/runtime/native-runtime.test.ts b/packages/server/src/__tests__/runtime/native-runtime.test.ts
new file mode 100644
index 000000000..deca63b33
--- /dev/null
+++ b/packages/server/src/__tests__/runtime/native-runtime.test.ts
@@ -0,0 +1,41 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createNativeRuntime } from "../../runtime/native-runtime.js";
+
+describe("NativeRuntimeHandle", () => {
+  let stateDir: string;
+
+  afterEach(() => {
+    if (stateDir) {
+      rmSync(stateDir, { recursive: true, force: true });
+    }
+  });
+
+  it("stores runtime-owned state under state/runtimes/native-default", async () => {
+    stateDir = mkdtempSync(join(tmpdir(), "native-runtime-state-"));
+    const runtime = await createNativeRuntime({
+      runtimeId: "native-default",
+      stateRoot: stateDir,
+      hostBridge: {
+        issueSessionToken: vi.fn(() => ({ token: "token" })),
+        revokeSessionTokensBySessionId: vi.fn(),
+        getHostApiUrl: () => "http://127.0.0.1:4173",
+        emitDomainEvent: vi.fn(),
+        broadcast: vi.fn(),
+        recordWorkspaceFetch: vi.fn(),
+        sendToClient: vi.fn(() => true),
+        sendBinaryToClient: vi.fn(() => true),
+      },
+      providerRegistry: [],
+      workspaceLookup: {
+        get: () => undefined,
+        list: () => [],
+      },
+      providerConfigRepoFactory: undefined,
+    });
+
+    expect(runtime.id).toBe("native-default");
+  });
+});
diff --git a/packages/server/src/__tests__/server-builtin-skills-wiring.test.ts b/packages/server/src/__tests__/server-builtin-skills-wiring.test.ts
index 41c4ea0a2..ff03019fb 100644
--- a/packages/server/src/__tests__/server-builtin-skills-wiring.test.ts
+++ b/packages/server/src/__tests__/server-builtin-skills-wiring.test.ts
@@ -3,6 +3,10 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { Server } from "../server.js";
+import {
+  AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN,
+  AUTOMATION_CMD_FILE_NAME,
+} from "../skills/builtin/automation-bridge.js";
 
 describe("server built-in skills wiring", () => {
   const originalHome = process.env.HOME;
@@ -50,6 +54,8 @@ describe("server built-in skills wiring", () => {
     });
 
     const ctx = server.__test__!.commandContext;
+    expect(server.__test__?.hostContext.runtimeRouter).toBeDefined();
+    expect(server.__test__?.nativeRuntime).toBeDefined();
 
     expect(ctx.builtinSkillSyncMgr).toBeDefined();
     expect(ctx.automationAuditLog).toBeDefined();
@@ -68,25 +74,72 @@ describe("server built-in skills wiring", () => {
           installState: "installed",
           builtin: { defaultEnabled: true, autoMount: true },
         }),
+        expect.objectContaining({
+          slug: "coder-studio-canvas",
+          source: "builtin",
+          installState: "installed",
+          builtin: { defaultEnabled: true, autoMount: true },
+        }),
       ])
     );
     expect(ctx.skillLibraryRepo?.list().filter((entry) => entry.source === "builtin")).toHaveLength(
-      2
+      3
+    );
+    expect(ctx.skillLibraryRepo?.getCustomSkillRoot()).toBe(
+      join(tempDir, "state-root", "state", "skills", "custom")
     );
 
     const builtinRoot = join(tempDir, "state-root", "state", "skills", "builtin");
     const builtinOpenSkillPath = join(builtinRoot, "coder-studio-open", "SKILL.md");
     expect(existsSync(builtinOpenSkillPath)).toBe(true);
-    expect(readFileSync(builtinOpenSkillPath, "utf8")).toContain("coder-studio ui open-file");
-    expect(readFileSync(builtinOpenSkillPath, "utf8")).toContain("coder-studio ui open-url");
-    expect(readFileSync(builtinOpenSkillPath, "utf8")).toContain("coder-studio ui close-file");
-    expect(readFileSync(builtinOpenSkillPath, "utf8")).toContain("coder-studio ui close-url");
+    expect(readFileSync(builtinOpenSkillPath, "utf8")).toContain(
+      AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN
+    );
+    expect(readFileSync(builtinOpenSkillPath, "utf8")).toContain("ui.open-file");
+    expect(readFileSync(builtinOpenSkillPath, "utf8")).toContain("ui.open-url");
+    expect(readFileSync(builtinOpenSkillPath, "utf8")).toContain("ui.close-file");
+    expect(readFileSync(builtinOpenSkillPath, "utf8")).toContain("ui.close-url");
+    expect(existsSync(join(builtinRoot, "coder-studio-open", AUTOMATION_CMD_FILE_NAME))).toBe(true);
 
     const builtinMemorySkillPath = join(builtinRoot, "coder-studio-memory", "SKILL.md");
     expect(existsSync(builtinMemorySkillPath)).toBe(true);
-    expect(readFileSync(builtinMemorySkillPath, "utf8")).toContain("coder-studio memory list");
-    expect(readFileSync(builtinMemorySkillPath, "utf8")).toContain("coder-studio memory search");
-    expect(readFileSync(builtinMemorySkillPath, "utf8")).toContain("coder-studio memory add");
+    expect(readFileSync(builtinMemorySkillPath, "utf8")).toContain(
+      AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN
+    );
+    expect(readFileSync(builtinMemorySkillPath, "utf8")).toContain("memory.list");
+    expect(readFileSync(builtinMemorySkillPath, "utf8")).toContain("memory.search");
+    expect(readFileSync(builtinMemorySkillPath, "utf8")).toContain("memory.create");
+    expect(readFileSync(builtinMemorySkillPath, "utf8")).not.toContain("memory add");
+    expect(existsSync(join(builtinRoot, "coder-studio-memory", AUTOMATION_CMD_FILE_NAME))).toBe(
+      true
+    );
+
+    const builtinCanvasSkillPath = join(builtinRoot, "coder-studio-canvas", "SKILL.md");
+    expect(existsSync(builtinCanvasSkillPath)).toBe(true);
+    expect(readFileSync(builtinCanvasSkillPath, "utf8")).toContain(
+      AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN
+    );
+    expect(readFileSync(builtinCanvasSkillPath, "utf8")).toContain("canvas.create");
+    expect(readFileSync(builtinCanvasSkillPath, "utf8")).toContain("canvas.update");
+    expect(readFileSync(builtinCanvasSkillPath, "utf8")).toContain("canvas.render");
+    expect(readFileSync(builtinCanvasSkillPath, "utf8")).toContain(
+      "ui.open-file --path .coder-studio/canvases/<title-slug>.csc"
+    );
+    expect(readFileSync(builtinCanvasSkillPath, "utf8")).toContain(
+      "canvas.render --source-path .coder-studio/canvases/<title-slug>.csc"
+    );
+    expect(readFileSync(builtinCanvasSkillPath, "utf8")).toContain(
+      "ui.open-canvas --canvas <canvas-id>"
+    );
+    expect(readFileSync(builtinCanvasSkillPath, "utf8")).toContain(
+      "readable `.coder-studio/canvases/<title-slug>.csc` paths"
+    );
+    expect(readFileSync(builtinCanvasSkillPath, "utf8")).not.toContain(
+      ".coder-studio/canvases/<canvas-id>.canvas.json"
+    );
+    expect(existsSync(join(builtinRoot, "coder-studio-canvas", AUTOMATION_CMD_FILE_NAME))).toBe(
+      true
+    );
 
     const homeOpenSkillPath = join(
       tempDir,
@@ -97,10 +150,21 @@ describe("server built-in skills wiring", () => {
       "SKILL.md"
     );
     expect(existsSync(homeOpenSkillPath)).toBe(true);
-    expect(readFileSync(homeOpenSkillPath, "utf8")).toContain("coder-studio ui open-file");
-    expect(readFileSync(homeOpenSkillPath, "utf8")).toContain("coder-studio ui open-url");
-    expect(readFileSync(homeOpenSkillPath, "utf8")).toContain("coder-studio ui close-file");
-    expect(readFileSync(homeOpenSkillPath, "utf8")).toContain("coder-studio ui close-url");
+    expect(readFileSync(homeOpenSkillPath, "utf8")).not.toContain(
+      AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN
+    );
+    expect(readFileSync(homeOpenSkillPath, "utf8")).toContain(
+      join(tempDir, "home", ".agents", "skills", "coder-studio-open", AUTOMATION_CMD_FILE_NAME)
+    );
+    expect(readFileSync(homeOpenSkillPath, "utf8")).toContain("ui.open-file");
+    expect(readFileSync(homeOpenSkillPath, "utf8")).toContain("ui.open-url");
+    expect(readFileSync(homeOpenSkillPath, "utf8")).toContain("ui.close-file");
+    expect(readFileSync(homeOpenSkillPath, "utf8")).toContain("ui.close-url");
+    expect(
+      existsSync(
+        join(tempDir, "home", ".agents", "skills", "coder-studio-open", AUTOMATION_CMD_FILE_NAME)
+      )
+    ).toBe(true);
 
     const homeMemorySkillPath = join(
       tempDir,
@@ -111,8 +175,59 @@ describe("server built-in skills wiring", () => {
       "SKILL.md"
     );
     expect(existsSync(homeMemorySkillPath)).toBe(true);
-    expect(readFileSync(homeMemorySkillPath, "utf8")).toContain("coder-studio memory list");
-    expect(readFileSync(homeMemorySkillPath, "utf8")).toContain("coder-studio memory search");
-    expect(readFileSync(homeMemorySkillPath, "utf8")).toContain("coder-studio memory add");
-  }, 20_000);
+    expect(readFileSync(homeMemorySkillPath, "utf8")).not.toContain(
+      AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN
+    );
+    expect(readFileSync(homeMemorySkillPath, "utf8")).toContain(
+      join(tempDir, "home", ".agents", "skills", "coder-studio-memory", AUTOMATION_CMD_FILE_NAME)
+    );
+    expect(readFileSync(homeMemorySkillPath, "utf8")).toContain("memory.list");
+    expect(readFileSync(homeMemorySkillPath, "utf8")).toContain("memory.search");
+    expect(readFileSync(homeMemorySkillPath, "utf8")).toContain("memory.create");
+    expect(readFileSync(homeMemorySkillPath, "utf8")).not.toContain("memory add");
+    expect(
+      existsSync(
+        join(tempDir, "home", ".agents", "skills", "coder-studio-memory", AUTOMATION_CMD_FILE_NAME)
+      )
+    ).toBe(true);
+
+    const homeCanvasSkillPath = join(
+      tempDir,
+      "home",
+      ".agents",
+      "skills",
+      "coder-studio-canvas",
+      "SKILL.md"
+    );
+    expect(existsSync(homeCanvasSkillPath)).toBe(true);
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).not.toContain(
+      AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN
+    );
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).toContain(
+      join(tempDir, "home", ".agents", "skills", "coder-studio-canvas", AUTOMATION_CMD_FILE_NAME)
+    );
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).toContain("canvas.create");
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).toContain("canvas.update");
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).toContain("canvas.render");
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).toContain(
+      "ui.open-file --path .coder-studio/canvases/<title-slug>.csc"
+    );
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).toContain(
+      "canvas.render --source-path .coder-studio/canvases/<title-slug>.csc"
+    );
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).toContain(
+      "ui.open-canvas --canvas <canvas-id>"
+    );
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).toContain(
+      "readable `.coder-studio/canvases/<title-slug>.csc` paths"
+    );
+    expect(readFileSync(homeCanvasSkillPath, "utf8")).not.toContain(
+      ".coder-studio/canvases/<canvas-id>.canvas.json"
+    );
+    expect(
+      existsSync(
+        join(tempDir, "home", ".agents", "skills", "coder-studio-canvas", AUTOMATION_CMD_FILE_NAME)
+      )
+    ).toBe(true);
+  }, 30_000);
 });
diff --git a/packages/server/src/__tests__/server-lsp-runtime-mode-hydration.test.ts b/packages/server/src/__tests__/server-lsp-runtime-mode-hydration.test.ts
index 7e264c4dc..c3dde7d17 100644
--- a/packages/server/src/__tests__/server-lsp-runtime-mode-hydration.test.ts
+++ b/packages/server/src/__tests__/server-lsp-runtime-mode-hydration.test.ts
@@ -33,6 +33,7 @@ describe("server lsp runtime mode hydration", () => {
       port: 0,
     });
 
+    expect(server.__test__?.nativeRuntime).toBeDefined();
     expect(server.__test__?.commandContext.lspMgr.getRuntimeMode()).toBe("off");
   });
 });
diff --git a/packages/server/src/__tests__/server-memory-wiring.test.ts b/packages/server/src/__tests__/server-memory-wiring.test.ts
index f21b8d5cd..cbc067f0d 100644
--- a/packages/server/src/__tests__/server-memory-wiring.test.ts
+++ b/packages/server/src/__tests__/server-memory-wiring.test.ts
@@ -51,7 +51,7 @@ describe("createServer memory wiring", () => {
     expect(result.ok).toBe(true);
     expect(result.data).toMatchObject({
       workspaceId: workspace.id,
-      type: "project",
+      type: "wiki",
       content: "Memory commands use the server-assembled MemoryRepo.",
     } satisfies Partial<WorkspaceMemoryEntry>);
     expect(ctx.memoryRepo?.list({ workspaceId: workspace.id })).toHaveLength(1);
diff --git a/packages/server/src/__tests__/server-monitoring-hydration.test.ts b/packages/server/src/__tests__/server-monitoring-hydration.test.ts
index c97d3d18b..e475284df 100644
--- a/packages/server/src/__tests__/server-monitoring-hydration.test.ts
+++ b/packages/server/src/__tests__/server-monitoring-hydration.test.ts
@@ -1,7 +1,7 @@
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createServer, type Server } from "../server.js";
 import { SettingsRepo } from "../storage/index.js";
 
@@ -34,11 +34,13 @@ describe("server monitoring hydration", () => {
       port: 0,
     });
 
-    expect(server.__test__?.commandContext.monitoringService?.getResponse().settings).toEqual(
-      expect.objectContaining({
-        enabled: true,
-        sampleIntervalMs: 5000,
-      })
-    );
+    await vi.waitFor(() => {
+      expect(server.__test__?.commandContext.monitoringService?.getResponse().settings).toEqual(
+        expect.objectContaining({
+          enabled: true,
+          sampleIntervalMs: 5000,
+        })
+      );
+    });
   });
 });
diff --git a/packages/server/src/__tests__/server-runtime-config.test.ts b/packages/server/src/__tests__/server-runtime-config.test.ts
index f5bf5e3fa..436e897c0 100644
--- a/packages/server/src/__tests__/server-runtime-config.test.ts
+++ b/packages/server/src/__tests__/server-runtime-config.test.ts
@@ -2,7 +2,7 @@ import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { getRuntimePath, readRuntimeConfig } from "@coder-studio/core/runtime";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { ServerConfig } from "../config.js";
 import { createServer, type Server, type ServerRuntimeOptions } from "../server.js";
 
@@ -34,6 +34,9 @@ describe("server runtime config", () => {
       server = undefined;
     }
 
+    vi.doUnmock("../agent-instructions/publisher.js");
+    vi.resetModules();
+
     if (existsSync(runtimePath)) {
       rmSync(runtimePath);
     }
@@ -86,4 +89,46 @@ describe("server runtime config", () => {
 
     expect(readRuntimeConfig()).toBeNull();
   });
+
+  it("writes runtime config before post-listen workspace sync completes", async () => {
+    const syncGate = Promise.withResolvers<void>();
+    vi.resetModules();
+    vi.doMock("../agent-instructions/publisher.js", async () => {
+      const actual = await vi.importActual<typeof import("../agent-instructions/publisher.js")>(
+        "../agent-instructions/publisher.js"
+      );
+
+      class DeferredPublisher extends actual.AgentInstructionsPublisher {
+        override async syncAllOpenWorkspaces() {
+          await syncGate.promise;
+          return [];
+        }
+      }
+
+      return {
+        ...actual,
+        AgentInstructionsPublisher: DeferredPublisher,
+      };
+    });
+
+    const { createServer: createDeferredServer } = await import("../server.js");
+
+    const pendingServer = createDeferredServer({
+      stateDir: join(testHomeDir, "server-state-deferred"),
+      host: "127.0.0.1",
+      port: 0,
+      writeRuntimeConfig: true,
+    });
+
+    await expect
+      .poll(() => readRuntimeConfig(), {
+        timeout: 5_000,
+      })
+      .not.toBeNull();
+
+    syncGate.resolve();
+    server = await pendingServer;
+    const { createServer: restoredCreateServer } = await import("../server.js");
+    expect(restoredCreateServer).toBeDefined();
+  });
 });
diff --git a/packages/server/src/__tests__/session-automation-entry-path.test.ts b/packages/server/src/__tests__/session-automation-entry-path.test.ts
new file mode 100644
index 000000000..1e23cb2dc
--- /dev/null
+++ b/packages/server/src/__tests__/session-automation-entry-path.test.ts
@@ -0,0 +1,43 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, normalize } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveAutomationEntryPath } from "../session/automation-entry-path.js";
+
+describe("resolveAutomationEntryPath", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // Ignore cleanup errors in test temp dirs.
+      }
+    }
+  });
+
+  it("prefers the repo source automation entry during development", () => {
+    const resolvedPath = resolveAutomationEntryPath();
+
+    expect(isAbsolute(resolvedPath)).toBe(true);
+    expect(normalize(resolvedPath)).toContain(normalize("packages/cli/src/automation-entry.ts"));
+  });
+
+  it("resolves a same-directory automation entry artifact for packaged dist runtimes", () => {
+    const packageRoot = mkdtempSync(join(tmpdir(), "coder-studio-cli-dist-"));
+    tempDirs.push(packageRoot);
+
+    const distDir = join(packageRoot, "dist", "esm");
+    mkdirSync(distDir, { recursive: true });
+    writeFileSync(join(distDir, "server-runner.mjs"), "export {};\n");
+    writeFileSync(join(distDir, "automation-entry.mjs"), "export {};\n");
+
+    const resolvedPath = resolveAutomationEntryPath(
+      pathToFileURL(join(distDir, "server-runner.mjs")).href
+    );
+
+    expect(resolvedPath).toBe(join(distDir, "automation-entry.mjs"));
+  });
+});
diff --git a/packages/server/src/__tests__/session-commands.test.ts b/packages/server/src/__tests__/session-commands.test.ts
index 3ef91dc58..336f30db8 100644
--- a/packages/server/src/__tests__/session-commands.test.ts
+++ b/packages/server/src/__tests__/session-commands.test.ts
@@ -5,7 +5,11 @@ import type { ProviderDefinition } from "@coder-studio/core";
 import { providerRegistry } from "@coder-studio/providers";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { EventBus } from "../bus/event-bus.js";
+import { RuntimeRegistry } from "../host/runtime-registry.js";
+import { RuntimeRouter } from "../host/runtime-router.js";
+import { WorkspaceRuntimeBindingStore } from "../host/workspace-runtime-binding.js";
 import { buildCustomProviderDefinition } from "../provider-runtime/custom-provider.js";
+import { createNativeRuntime } from "../runtime/native-runtime.js";
 import { SessionManager } from "../session/manager.js";
 import type { SessionDatabase } from "../session/types.js";
 import { ProviderConfigRepo } from "../storage/repositories/provider-config-repo.js";
@@ -36,6 +40,9 @@ describe("Session Commands", () => {
   let workspaceRepo: WorkspaceRepo;
   let terminalMgrStub: TerminalManager;
   let sessionDbStub: SessionDatabase;
+  let runtimeBindings: WorkspaceRuntimeBindingStore;
+  let runtimeRegistry: RuntimeRegistry;
+  let runtimeRouter: RuntimeRouter;
 
   beforeEach(() => {
     eventBus = new EventBus();
@@ -76,11 +83,54 @@ describe("Session Commands", () => {
       providerRegistry: [],
       providerConfigRepo,
     });
+    runtimeBindings = new WorkspaceRuntimeBindingStore();
+    runtimeRegistry = new RuntimeRegistry();
+    runtimeRouter = new RuntimeRouter({
+      runtimeRegistry,
+      bindings: runtimeBindings,
+      defaultRuntimeId: "native-default",
+    });
+    eventBus.on("workspace.meta.changed", (event) => {
+      const workspace = workspaceMgr.get(event.workspaceId);
+      if (!workspace) {
+        runtimeBindings.unbindWorkspace(event.workspaceId);
+        return;
+      }
+
+      runtimeBindings.bindWorkspace(workspace.id, "native-default");
+    });
+    eventBus.on("session.state.changed", (event) => {
+      if (event.session) {
+        runtimeBindings.bindSession(event.session);
+      }
+    });
+    eventBus.on("session.lifecycle", (event) => {
+      if (event.event === "removed") {
+        runtimeBindings.removeSession(event.sessionId);
+      }
+    });
+    eventBus.on("terminal.created", (event) => {
+      runtimeBindings.bindTerminal({
+        id: event.terminalId,
+        workspaceId: event.workspaceId,
+        kind: event.kind,
+        title: event.title,
+        cwd: event.cwd,
+        argv: [],
+        cols: 120,
+        rows: 30,
+        alive: true,
+        createdAt: Date.now(),
+      });
+    });
+    eventBus.on("terminal.exited", (event) => {
+      runtimeBindings.removeTerminal(event.terminalId);
+    });
 
     ctx = {
       workspaceMgr,
       sessionMgr,
-      terminalMgr: {} as never,
+      terminalMgr: terminalMgrStub,
       eventBus,
       broadcaster,
       settingsRepo,
@@ -89,6 +139,11 @@ describe("Session Commands", () => {
       supervisorMgr: {} as never,
       providerConfigRepo,
       sessionMetadataRepo,
+      runtimeBindings,
+      runtimeRouter,
+      activationMgr: { getLease: vi.fn(() => ({ wsClientId: "client-1" })) } as never,
+      autoFetch: {} as never,
+      lspMgr: {} as never,
     } as unknown as CommandContext;
     tempDirs = [];
   });
@@ -129,6 +184,40 @@ describe("Session Commands", () => {
       };
 
       try {
+        runtimeRegistry.register(
+          await createNativeRuntime({
+            runtimeId: "native-default",
+            stateRoot: stateDir,
+            hostBridge: {
+              issueSessionToken: vi.fn(() => ({ token: "token" })),
+              revokeSessionTokensBySessionId: vi.fn(),
+              getHostApiUrl: () => "http://127.0.0.1:4173",
+              emitDomainEvent: (event) => eventBus.emit(event),
+              broadcast: vi.fn(),
+              recordWorkspaceFetch: vi.fn(),
+              sendToClient: vi.fn(() => true),
+              sendBinaryToClient: vi.fn(() => true),
+            },
+            providerRegistry: ctx.providerRegistry,
+            workspaceLookup: {
+              get: (workspaceId: string) => workspaceMgr.get(workspaceId),
+              list: () => workspaceMgr.list(),
+            },
+            providerRuntimeDeps: ctx.providerRuntimeDeps,
+            contextOverrides: {
+              eventBus,
+              providerConfigRepo: ctx.providerConfigRepo,
+              sessionMgr,
+              terminalMgr: ctx.terminalMgr,
+              taskMgr: ctx.taskMgr,
+              lspMgr: ctx.lspMgr,
+              supervisorMgr: ctx.supervisorMgr,
+              sessionMetadataRepo,
+              agentInstructionPublisher: ctx.agentInstructionPublisher,
+            },
+          })
+        );
+
         const openResult = await dispatch(
           {
             kind: "command",
@@ -140,6 +229,7 @@ describe("Session Commands", () => {
         );
 
         expect(openResult.ok).toBe(true);
+        expect(ctx.runtimeBindings.findWorkspaceIdBySessionId(openResult.data!.id)).toBeUndefined();
 
         const result = await dispatch(
           {
@@ -186,21 +276,47 @@ describe("Session Commands", () => {
         syncAllOpenWorkspaces: vi.fn(),
       } as never;
 
-      const createSpy = vi.spyOn(sessionMgr, "create").mockImplementation(async () => {
+      const realCreate = sessionMgr.create.bind(sessionMgr);
+      const createSpy = vi.spyOn(sessionMgr, "create").mockImplementation(async (request) => {
         calls.push("create");
-        return {
-          id: "sess-1",
-          workspaceId: "ws-1",
-          providerId: "claude",
-          terminalId: "term-1",
-          capability: "full",
-          state: "starting",
-          startedAt: Date.now(),
-          lastActiveAt: Date.now(),
-        };
+        return realCreate(request);
       });
 
       try {
+        runtimeRegistry.register(
+          await createNativeRuntime({
+            runtimeId: "native-default",
+            stateRoot: stateDir,
+            hostBridge: {
+              issueSessionToken: vi.fn(() => ({ token: "token" })),
+              revokeSessionTokensBySessionId: vi.fn(),
+              getHostApiUrl: () => "http://127.0.0.1:4173",
+              emitDomainEvent: (event) => eventBus.emit(event),
+              broadcast: vi.fn(),
+              recordWorkspaceFetch: vi.fn(),
+              sendToClient: vi.fn(() => true),
+              sendBinaryToClient: vi.fn(() => true),
+            },
+            providerRegistry: ctx.providerRegistry,
+            workspaceLookup: {
+              get: (workspaceId: string) => workspaceMgr.get(workspaceId),
+              list: () => workspaceMgr.list(),
+            },
+            providerRuntimeDeps: ctx.providerRuntimeDeps,
+            contextOverrides: {
+              eventBus,
+              providerConfigRepo: ctx.providerConfigRepo,
+              sessionMgr,
+              terminalMgr: ctx.terminalMgr,
+              taskMgr: ctx.taskMgr,
+              lspMgr: ctx.lspMgr,
+              supervisorMgr: ctx.supervisorMgr,
+              sessionMetadataRepo,
+              agentInstructionPublisher: ctx.agentInstructionPublisher,
+            },
+          })
+        );
+
         const openResult = await dispatch(
           {
             kind: "command",
@@ -229,6 +345,9 @@ describe("Session Commands", () => {
 
         expect(result.ok).toBe(true);
         expect(calls).toEqual(["publish", "create"]);
+        expect(ctx.runtimeBindings.findWorkspaceIdBySessionId(result.data!.id)).toBe(
+          openResult.data!.id
+        );
       } finally {
         createSpy.mockRestore();
         rmSync(testDir, { recursive: true, force: true });
@@ -300,6 +419,7 @@ describe("Session Commands", () => {
           CODER_STUDIO_PROVIDER_ID: "claude",
           CODER_STUDIO_API_URL: "http://127.0.0.1:4173",
         });
+        expect(createdSpecs[0]?.env?.CODER_STUDIO_SESSION_TOKEN).toMatch(/^[a-f0-9]{64}$/);
       } finally {
         rmSync(testDir, { recursive: true, force: true });
       }
diff --git a/packages/server/src/__tests__/session-hydrate-restart.test.ts b/packages/server/src/__tests__/session-hydrate-restart.test.ts
index 5c4cc6122..9b9653090 100644
--- a/packages/server/src/__tests__/session-hydrate-restart.test.ts
+++ b/packages/server/src/__tests__/session-hydrate-restart.test.ts
@@ -120,5 +120,6 @@ describe("session hydrate restart", () => {
         state: "ended",
       }),
     ]);
+    expect(server.__test__?.sessionTokenRepo.listBySessionId("sess-hydrated")).toEqual([]);
   });
 });
diff --git a/packages/server/src/__tests__/session-integration.test.ts b/packages/server/src/__tests__/session-integration.test.ts
index 9a85b1cee..87029a4ff 100644
--- a/packages/server/src/__tests__/session-integration.test.ts
+++ b/packages/server/src/__tests__/session-integration.test.ts
@@ -12,9 +12,15 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { DomainEvent, Session } from "@coder-studio/core";
+import {
+  AUTOMATION_PERMISSIONS_ENV,
+  type DomainEvent,
+  SCOPED_SESSION_AUTOMATION_PERMISSIONS,
+  type Session,
+} from "@coder-studio/core";
 import { providerRegistry } from "@coder-studio/providers";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SessionTokenRepo } from "../auth/session-token-repo.js";
 import { EventBus } from "../bus/event-bus.js";
 import { ProviderInstallManager } from "../provider-runtime/install-manager.js";
 import { SessionManager } from "../session/manager.js";
@@ -138,6 +144,7 @@ describe("Session Integration", () => {
   let testDir: string;
   let stateDir: string;
   let providerConfigRepo: ProviderConfigRepo;
+  let sessionTokenRepo: SessionTokenRepo;
 
   beforeEach(() => {
     // Create event bus
@@ -195,6 +202,7 @@ describe("Session Integration", () => {
     providerConfigRepo = new ProviderConfigRepo({
       filePath: join(stateDir, "provider-configs.json"),
     });
+    sessionTokenRepo = new SessionTokenRepo();
     const settingsRepo = new SettingsRepo({
       filePath: join(stateDir, "settings.json"),
     });
@@ -205,6 +213,10 @@ describe("Session Integration", () => {
       broadcaster: mockBroadcaster,
       providerRegistry,
       providerConfigRepo,
+      sessionTokenRepo,
+      runtimeContext: {
+        apiUrl: "http://127.0.0.1:4321",
+      },
     });
 
     // Create context
@@ -529,6 +541,105 @@ describe("Session Integration", () => {
         })
       );
     });
+
+    it("injects session token and scoped automation permissions into the launched agent env", async () => {
+      const openResult = await dispatch(
+        {
+          kind: "command",
+          id: "test-session-token-open",
+          op: "workspace.open",
+          args: { path: testDir },
+        },
+        ctx
+      );
+
+      expect(openResult.ok).toBe(true);
+      const workspaceId = openResult.data!.id;
+
+      const sessionResult = await dispatch(
+        {
+          kind: "command",
+          id: "test-session-token-create",
+          op: "session.create",
+          args: {
+            workspaceId,
+            providerId: "claude",
+          },
+        },
+        ctx
+      );
+
+      expect(sessionResult.ok).toBe(true);
+
+      const env = (spawnCalls.at(-1)?.options as { env?: Record<string, string> } | undefined)?.env;
+      expect(env?.CODER_STUDIO_API_URL).toBe("http://127.0.0.1:4321");
+      expect(env?.CODER_STUDIO_SESSION_TOKEN).toMatch(/^[a-f0-9]{64}$/);
+      expect(env?.CODER_STUDIO_WORKSPACE_ID).toBe(workspaceId);
+      expect(env?.CODER_STUDIO_AUTOMATION_ENTRY).toContain("automation-entry");
+      expect(env?.[AUTOMATION_PERMISSIONS_ENV]).toBe(
+        SCOPED_SESSION_AUTOMATION_PERMISSIONS.join(",")
+      );
+
+      const tokenRecord = sessionTokenRepo.get(env?.CODER_STUDIO_SESSION_TOKEN ?? "");
+      expect(tokenRecord).toEqual(
+        expect.objectContaining({
+          sessionId: sessionResult.data!.id,
+          workspaceId,
+          providerId: "claude",
+          permissions: [...SCOPED_SESSION_AUTOMATION_PERMISSIONS],
+        })
+      );
+    });
+
+    it("revokes the issued session token when automation entry resolution fails", async () => {
+      const resolverError = new Error("automation entry resolution failed");
+      const issuedSessionIds: string[] = [];
+      const revokedSessionIds: string[] = [];
+      const claudeProvider = providerRegistry.find((provider) => provider.id === "claude");
+
+      expect(claudeProvider).toBeDefined();
+
+      const failingSessionMgr = new SessionManager({
+        terminalMgr,
+        eventBus,
+        db: sessionDb,
+        broadcaster: ctx.broadcaster,
+        providerRegistry,
+        providerConfigRepo,
+        hostBridge: {
+          issueSessionToken: (input) => {
+            issuedSessionIds.push(input.sessionId);
+            const record = sessionTokenRepo.issue(input);
+            return { token: record.token };
+          },
+          revokeSessionTokensBySessionId: (sessionId) => {
+            revokedSessionIds.push(sessionId);
+            sessionTokenRepo.revokeBySessionId(sessionId);
+          },
+          getHostApiUrl: () => "http://127.0.0.1:4321",
+          emitDomainEvent: () => {},
+          broadcast: () => {},
+          sendToClient: () => false,
+          sendBinaryToClient: () => false,
+        },
+        resolveAutomationEntryPath: () => {
+          throw resolverError;
+        },
+      } as never);
+
+      await expect(
+        failingSessionMgr.create({
+          workspaceId: "workspace-resolution-failure",
+          workspacePath: testDir,
+          providerId: "claude",
+          provider: claudeProvider!,
+        })
+      ).rejects.toThrow(resolverError);
+
+      expect(issuedSessionIds).toHaveLength(1);
+      expect(revokedSessionIds).toEqual(issuedSessionIds);
+      expect(sessionTokenRepo.listBySessionId(issuedSessionIds[0]!)).toEqual([]);
+    });
   });
 
   describe("Session state transitions", () => {
@@ -699,6 +810,11 @@ describe("Session Integration", () => {
     });
 
     it("should stop session successfully", async () => {
+      const sessionToken = (
+        spawnCalls.at(-1)?.options as { env?: Record<string, string> } | undefined
+      )?.env?.CODER_STUDIO_SESSION_TOKEN;
+      expect(sessionToken).toBeDefined();
+
       const result = await dispatch(
         {
           kind: "command",
@@ -714,6 +830,40 @@ describe("Session Integration", () => {
       // Verify session state changed to ended
       const session = sessionMgr.get(sessionId);
       expect(session?.state).toBe("ended");
+      expect(sessionTokenRepo.get(sessionToken ?? "")).toBeUndefined();
+    });
+
+    it("revokes tokens when ended sessions are deleted during workspace teardown cleanup", async () => {
+      const sessionToken = (
+        spawnCalls.at(-1)?.options as { env?: Record<string, string> } | undefined
+      )?.env?.CODER_STUDIO_SESSION_TOKEN;
+      expect(sessionToken).toBeDefined();
+
+      await dispatch(
+        {
+          kind: "command",
+          id: "test-stop-for-delete-ended",
+          op: "session.stop",
+          args: { sessionId },
+        },
+        ctx
+      );
+
+      expect(sessionMgr.get(sessionId)?.state).toBe("ended");
+      expect(sessionTokenRepo.get(sessionToken ?? "")).toBeUndefined();
+
+      const replacementToken = sessionTokenRepo.issue({
+        sessionId,
+        workspaceId: workspaceId!,
+        providerId: "claude",
+        permissions: SCOPED_SESSION_AUTOMATION_PERMISSIONS,
+      }).token;
+
+      expect(sessionTokenRepo.get(replacementToken)).toBeDefined();
+
+      sessionMgr.deleteEndedForWorkspace(workspaceId!);
+
+      expect(sessionTokenRepo.get(replacementToken)).toBeUndefined();
     });
 
     it("should fail session.stop for non-existent session", async () => {
@@ -1049,6 +1199,27 @@ describe("Session Integration", () => {
         })
       );
     });
+
+    it("does not recreate a live automation token while hydrating a stale session", async () => {
+      sessionDb.listHydratable = vi.fn().mockReturnValue([
+        {
+          id: "sess-hydrate-4",
+          workspaceId: "ws-1",
+          terminalId: "term-dead",
+          providerId: "claude",
+          state: "running",
+          capability: "full",
+          startedAt: 100,
+          lastActiveAt: 200,
+        },
+      ]);
+
+      await sessionMgr.hydrate();
+
+      const tokens = sessionTokenRepo.listBySessionId("sess-hydrate-4");
+      expect(tokens).toEqual([]);
+      expect(sessionMgr.get("sess-hydrate-4")?.state).toBe("ended");
+    });
   });
 
   describe("Multiple sessions", () => {
diff --git a/packages/server/src/__tests__/session-manager-api.test.ts b/packages/server/src/__tests__/session-manager-api.test.ts
index 0a04bcd3f..c39e00109 100644
--- a/packages/server/src/__tests__/session-manager-api.test.ts
+++ b/packages/server/src/__tests__/session-manager-api.test.ts
@@ -1,5 +1,6 @@
 import type { DomainEvent, ProviderDefinition, Session } from "@coder-studio/core";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SessionTokenRepo } from "../auth/session-token-repo.js";
 import { EventBus } from "../bus/event-bus.js";
 import { SessionManager } from "../session/manager.js";
 import type { SessionDatabase } from "../session/types.js";
@@ -18,6 +19,10 @@ type EventBusWithHandlers = EventBus & {
   handlers: Map<string, Set<(...args: unknown[]) => void>>;
 };
 
+type SessionTokenRepoInternals = SessionTokenRepo & {
+  recordsByToken: Map<string, unknown>;
+};
+
 const providerConfigRepoStub = {
   get: vi.fn(() => undefined),
 } as unknown as ProviderConfigRepo;
@@ -30,6 +35,7 @@ describe("SessionManager session-level API", () => {
   let ptyResizes: Array<[number, number]>;
   let mockPty: PtyProcess;
   let provider: ProviderDefinition;
+  let sessionTokenRepo: SessionTokenRepo;
 
   beforeEach(() => {
     ptyWrites = [];
@@ -83,6 +89,7 @@ describe("SessionManager session-level API", () => {
     } as ProviderDefinition;
 
     eventBus = new EventBus();
+    sessionTokenRepo = new SessionTokenRepo();
     terminalMgr = new TerminalManager({ ptyHost, eventBus, db: terminalDb });
     sessionMgr = new SessionManager({
       terminalMgr,
@@ -91,6 +98,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
   });
 
@@ -196,6 +204,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -234,6 +243,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
     const lifecycleEvents: string[] = [];
     eventBus.on("session.lifecycle", (event) => lifecycleEvents.push(event.event));
@@ -274,6 +284,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -313,6 +324,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -358,6 +370,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -400,6 +413,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -442,6 +456,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -487,6 +502,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -532,6 +548,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -571,6 +588,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -611,6 +629,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
     const lifecycleEvents: string[] = [];
     eventBus.on("session.lifecycle", (event) => lifecycleEvents.push(event.event));
@@ -655,6 +674,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
     const lifecycleEvents: string[] = [];
     eventBus.on("session.lifecycle", (event) => lifecycleEvents.push(event.event));
@@ -702,6 +722,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
     const lifecycleEvents: string[] = [];
     eventBus.on("session.lifecycle", (event) => lifecycleEvents.push(event.event));
@@ -749,6 +770,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
     const lifecycleEvents: string[] = [];
     eventBus.on("session.lifecycle", (event) => lifecycleEvents.push(event.event));
@@ -793,6 +815,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
     const lifecycleEvents: string[] = [];
     eventBus.on("session.lifecycle", (event) => lifecycleEvents.push(event.event));
@@ -836,6 +859,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -871,6 +895,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     const session = await createSession();
@@ -909,6 +934,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
     const lifecycleEvents: string[] = [];
     eventBus.on("session.lifecycle", (event) => lifecycleEvents.push(event.event));
@@ -957,6 +983,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [provider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
     const lifecycleEvents: string[] = [];
     eventBus.on("session.lifecycle", (event) => lifecycleEvents.push(event.event));
@@ -1096,6 +1123,25 @@ describe("SessionManager session-level API", () => {
     );
   });
 
+  it("revokes the session token when deleting an ended session", async () => {
+    const session = await createSession();
+    sessionMgr.onTerminalExit(session.terminalId, 0);
+    expect(sessionMgr.get(session.id)?.state).toBe("ended");
+
+    const replacementToken = sessionTokenRepo.issue({
+      sessionId: session.id,
+      workspaceId: session.workspaceId,
+      providerId: session.providerId,
+      permissions: ["session:read"],
+    }).token;
+
+    expect(replacementToken).toMatch(/^[a-f0-9]{64}$/);
+    expect((sessionTokenRepo as SessionTokenRepoInternals).recordsByToken.size).toBe(1);
+
+    expect(() => sessionMgr.delete(session.id)).not.toThrow();
+    expect((sessionTokenRepo as SessionTokenRepoInternals).recordsByToken.size).toBe(0);
+  });
+
   it("does not retain a half-created session when terminal creation throws", async () => {
     const failingProvider = {
       ...provider,
@@ -1122,6 +1168,7 @@ describe("SessionManager session-level API", () => {
       broadcaster: { broadcast: vi.fn() } as Broadcaster,
       providerRegistry: [failingProvider],
       providerConfigRepo: providerConfigRepoStub,
+      sessionTokenRepo,
     });
 
     await expect(
@@ -1134,5 +1181,6 @@ describe("SessionManager session-level API", () => {
     ).rejects.toThrow("spawn failed");
 
     expect(failingSessionMgr.getForWorkspace("ws-1")).toEqual([]);
+    expect((sessionTokenRepo as SessionTokenRepoInternals).recordsByToken.size).toBe(0);
   });
 });
diff --git a/packages/server/src/__tests__/session-manager-title.test.ts b/packages/server/src/__tests__/session-manager-title.test.ts
index 09a617c87..c8f6de800 100644
--- a/packages/server/src/__tests__/session-manager-title.test.ts
+++ b/packages/server/src/__tests__/session-manager-title.test.ts
@@ -194,6 +194,21 @@ describe("SessionManager title derivation", () => {
     }
   });
 
+  it("ignores SGR mouse tracking sequences when deriving the title", async () => {
+    const session = await createSession();
+
+    sessionMgr.onTerminalInput("terminal-1", "submit", "\x1b[<35;17;18M");
+    expect(sessionMgr.get(session.id)?.title).toBeUndefined();
+
+    mockDb.update.mockClear();
+    sessionMgr.onTerminalInput("terminal-1", "submit", "\x1b[<35;17;18Mfix the build");
+
+    expect(mockDb.update).toHaveBeenCalledWith(session.id, {
+      title: "fix the b…",
+      firstSubmittedUserInput: "fix the build",
+    });
+  });
+
   it("derives the title from submitted text instead of terminal buffer state", async () => {
     const session = await createSession();
 
diff --git a/packages/server/src/__tests__/session-token-repo.test.ts b/packages/server/src/__tests__/session-token-repo.test.ts
new file mode 100644
index 000000000..0c192d43c
--- /dev/null
+++ b/packages/server/src/__tests__/session-token-repo.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { type SessionAutomationTokenRecord, SessionTokenRepo } from "../auth/session-token-repo.js";
+
+function expectTokenRecordShape(record: SessionAutomationTokenRecord | undefined): asserts record {
+  expect(record).toBeDefined();
+  expect(record?.token).toMatch(/^[a-f0-9]{64}$/);
+  expect(record?.createdAt).toBeTypeOf("number");
+}
+
+describe("SessionTokenRepo", () => {
+  it("issues high-entropy session automation tokens and looks them up", () => {
+    const repo = new SessionTokenRepo();
+
+    const record = repo.issue({
+      sessionId: "sess-1",
+      workspaceId: "ws-1",
+      providerId: "claude",
+      permissions: ["session:read", "git:read"],
+    });
+
+    expectTokenRecordShape(record);
+    expect(record.sessionId).toBe("sess-1");
+    expect(record.workspaceId).toBe("ws-1");
+    expect(record.providerId).toBe("claude");
+    expect(record.permissions).toEqual(["session:read", "git:read"]);
+    expect(repo.get(record.token)).toEqual(record);
+  });
+
+  it("revokes individual tokens", () => {
+    const repo = new SessionTokenRepo();
+    const record = repo.issue({
+      sessionId: "sess-2",
+      workspaceId: "ws-1",
+      providerId: "codex",
+      permissions: ["session:read"],
+    });
+
+    expect(repo.revoke(record.token)).toBe(true);
+    expect(repo.get(record.token)).toBeUndefined();
+    expect(repo.revoke(record.token)).toBe(false);
+  });
+
+  it("revokes the active token when a session ends", () => {
+    const repo = new SessionTokenRepo();
+    const first = repo.issue({
+      sessionId: "sess-3",
+      workspaceId: "ws-1",
+      providerId: "claude",
+      permissions: ["session:read"],
+    });
+    const second = repo.issue({
+      sessionId: "sess-3",
+      workspaceId: "ws-1",
+      providerId: "claude",
+      permissions: ["session:read", "git:read"],
+    });
+
+    expect(repo.get(first.token)).toEqual(first);
+    expect(repo.get(second.token)).toEqual(second);
+
+    repo.revokeBySessionId("sess-3");
+
+    expect(repo.get(first.token)).toBeUndefined();
+    expect(repo.get(second.token)).toBeUndefined();
+  });
+});
diff --git a/packages/server/src/__tests__/skills-command.test.ts b/packages/server/src/__tests__/skills-command.test.ts
index 7040f0eb9..8278ebcb5 100644
--- a/packages/server/src/__tests__/skills-command.test.ts
+++ b/packages/server/src/__tests__/skills-command.test.ts
@@ -26,7 +26,8 @@ describe("skills commands", () => {
       displayName: "Code Review",
       description: "Review code changes before merge",
       version: "1.2.3",
-      source: "skillhub",
+      source: "installed",
+      origin: "skillhub",
       libraryPath: "/skills/library/code-review",
       installState: "installed",
       installedAt: 1,
diff --git a/packages/server/src/__tests__/skills/builtin-automation-bridge.test.ts b/packages/server/src/__tests__/skills/builtin-automation-bridge.test.ts
new file mode 100644
index 000000000..b9f8658ef
--- /dev/null
+++ b/packages/server/src/__tests__/skills/builtin-automation-bridge.test.ts
@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  AUTOMATION_CMD_FILE_NAME,
+  BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+} from "../../skills/builtin/automation-bridge.js";
+
+function runNodeScript(
+  entryPath: string,
+  options: {
+    args?: string[];
+    env?: NodeJS.ProcessEnv;
+  } = {}
+): Promise<{ code: number | null; signal: NodeJS.Signals | null; stderr: string; stdout: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [entryPath, ...(options.args ?? [])], {
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on("close", (code, signal) => {
+      resolve({ code, signal, stderr, stdout });
+    });
+  });
+}
+
+describe("builtin automation bridge", () => {
+  let tempDir: string | undefined;
+
+  afterEach(async () => {
+    if (tempDir) {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("fails clearly when required environment is missing", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "coder-studio-automation-bridge-"));
+    const bridgePath = join(tempDir, AUTOMATION_CMD_FILE_NAME);
+    await writeFile(bridgePath, BUILTIN_AUTOMATION_BRIDGE_SOURCE, "utf8");
+
+    const result = await runNodeScript(bridgePath, {
+      env: {
+        PATH: process.env.PATH,
+      },
+    });
+
+    expect(result.code).toBe(1);
+    expect(result.signal).toBeNull();
+    expect(result.stderr).toContain("CODER_STUDIO_API_URL");
+  });
+
+  it("delegates to the injected automation entry and preserves exit code", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "coder-studio-automation-bridge-"));
+    const bridgePath = join(tempDir, AUTOMATION_CMD_FILE_NAME);
+    const automationEntryPath = join(tempDir, "automation-entry.mjs");
+    await writeFile(bridgePath, BUILTIN_AUTOMATION_BRIDGE_SOURCE, "utf8");
+    await writeFile(
+      automationEntryPath,
+      [
+        "import { writeFileSync } from 'node:fs';",
+        "const outputPath = process.argv[2];",
+        "writeFileSync(outputPath, JSON.stringify(process.argv.slice(3)));",
+        "process.exit(17);",
+      ].join("\n"),
+      "utf8"
+    );
+
+    const argvCapturePath = join(tempDir, "argv.json");
+    const result = await runNodeScript(bridgePath, {
+      args: [argvCapturePath, "alpha", "beta"],
+      env: {
+        ...process.env,
+        CODER_STUDIO_API_URL: "http://127.0.0.1:3000",
+        CODER_STUDIO_WORKSPACE_ID: "workspace-123",
+        CODER_STUDIO_SESSION_TOKEN: "session-token",
+        CODER_STUDIO_AUTOMATION_ENTRY: automationEntryPath,
+      },
+    });
+
+    expect(result.code).toBe(17);
+    expect(result.signal).toBeNull();
+    expect(JSON.parse(await readFile(argvCapturePath, "utf8"))).toEqual(["alpha", "beta"]);
+  });
+
+  it("runs TypeScript automation entries through tsx when the injected entry is a source file", async () => {
+    tempDir = await mkdtemp(join(process.cwd(), ".coder-studio-automation-bridge-"));
+    const bridgePath = join(tempDir, AUTOMATION_CMD_FILE_NAME);
+    const automationEntryPath = join(tempDir, "automation-entry.ts");
+    const argvCapturePath = join(tempDir, "argv.json");
+    await writeFile(bridgePath, BUILTIN_AUTOMATION_BRIDGE_SOURCE, "utf8");
+    await writeFile(
+      join(tempDir, "message.ts"),
+      "export const message = 'from-ts-helper';\n",
+      "utf8"
+    );
+    await writeFile(
+      automationEntryPath,
+      [
+        "import { writeFileSync } from 'node:fs';",
+        "import { message } from './message.js';",
+        "const outputPath = process.argv[2];",
+        "writeFileSync(outputPath, JSON.stringify({ message, args: process.argv.slice(3) }));",
+        "process.exit(23);",
+      ].join("\n"),
+      "utf8"
+    );
+
+    const result = await runNodeScript(bridgePath, {
+      args: [argvCapturePath, "alpha", "beta"],
+      env: {
+        ...process.env,
+        CODER_STUDIO_API_URL: "http://127.0.0.1:3000",
+        CODER_STUDIO_WORKSPACE_ID: "workspace-123",
+        CODER_STUDIO_SESSION_TOKEN: "session-token",
+        CODER_STUDIO_AUTOMATION_ENTRY: automationEntryPath,
+      },
+    });
+
+    expect(result.code).toBe(23);
+    expect(result.signal).toBeNull();
+    expect(JSON.parse(await readFile(argvCapturePath, "utf8"))).toEqual({
+      message: "from-ts-helper",
+      args: ["alpha", "beta"],
+    });
+  });
+});
diff --git a/packages/server/src/__tests__/skills/builtin-registry.test.ts b/packages/server/src/__tests__/skills/builtin-registry.test.ts
index 23dbc7981..398f69875 100644
--- a/packages/server/src/__tests__/skills/builtin-registry.test.ts
+++ b/packages/server/src/__tests__/skills/builtin-registry.test.ts
@@ -2,6 +2,12 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
+import {
+  AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN,
+  AUTOMATION_CMD_FILE_NAME,
+  BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+} from "../../skills/builtin/automation-bridge.js";
+import { CODER_STUDIO_CANVAS_SKILL } from "../../skills/builtin/definitions/coder-studio-canvas.js";
 import { CODER_STUDIO_MEMORY_SKILL } from "../../skills/builtin/definitions/coder-studio-memory.js";
 import { CODER_STUDIO_OPEN_SKILL } from "../../skills/builtin/definitions/coder-studio-open.js";
 import { BUILTIN_SKILLS } from "../../skills/builtin/definitions/index.js";
@@ -28,6 +34,47 @@ const TEST_BUILTIN_SKILL: BuiltinSkillDefinition = {
   ].join("\n"),
 };
 
+const TEST_AUTOMATION_BUILTIN_SKILL = {
+  slug: "coder-studio-automation-builtin",
+  displayName: "Coder Studio Automation Builtin",
+  description: "Test fixture for built-in automation bridge materialization.",
+  version: "1.0.0",
+  defaultEnabled: true,
+  autoMountInMvp: false,
+  mountRendering: "automation_bridge",
+  content: [
+    "---",
+    "name: coder-studio-automation-builtin",
+    "description: Uses a shared automation bridge.",
+    "---",
+    "",
+    `Run \`node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}"\` after mount.`,
+    "",
+  ].join("\n"),
+  files: [
+    {
+      relativePath: AUTOMATION_CMD_FILE_NAME,
+      content: BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+    },
+  ],
+} satisfies BuiltinSkillDefinition;
+
+function extractFrontmatterDescription(content: string): string | null {
+  const frontmatterMatch = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/);
+  if (!frontmatterMatch?.[1]) {
+    return null;
+  }
+
+  for (const line of frontmatterMatch[1].split(/\r?\n/)) {
+    const descriptionMatch = line.match(/^description:\s*(.+)$/);
+    if (descriptionMatch?.[1]) {
+      return descriptionMatch[1].trim();
+    }
+  }
+
+  return null;
+}
+
 describe("builtin skills", () => {
   let tempDir: string | undefined;
 
@@ -41,31 +88,78 @@ describe("builtin skills", () => {
     expect(CODER_STUDIO_OPEN_SKILL).toMatchObject({
       slug: "coder-studio-open",
       displayName: "Coder Studio Open",
-      description: "Open workspace files and localhost URLs in Coder Studio.",
+      description:
+        "Use when an agent running inside Coder Studio needs to open or close a workspace file, open or close a localhost URL, or open a canvas for the user.",
       version: "1.0.0",
       defaultEnabled: true,
       autoMountInMvp: true,
+      mountRendering: "automation_bridge",
+      files: [{ relativePath: AUTOMATION_CMD_FILE_NAME }],
     });
     expect(CODER_STUDIO_OPEN_SKILL.content).toContain("name: coder-studio-open");
-    expect(CODER_STUDIO_OPEN_SKILL.content).toContain("coder-studio ui open-file");
-    expect(CODER_STUDIO_OPEN_SKILL.content).toContain("coder-studio ui open-url");
-    expect(CODER_STUDIO_OPEN_SKILL.content).toContain("coder-studio ui close-file");
-    expect(CODER_STUDIO_OPEN_SKILL.content).toContain("coder-studio ui close-url");
+    expect(CODER_STUDIO_OPEN_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-file`
+    );
+    expect(CODER_STUDIO_OPEN_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-url`
+    );
+    expect(CODER_STUDIO_OPEN_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.close-file`
+    );
+    expect(CODER_STUDIO_OPEN_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.close-url`
+    );
+    expect(CODER_STUDIO_OPEN_SKILL.content).not.toContain("coder-studio ui open-file");
+    expect(CODER_STUDIO_OPEN_SKILL.content).not.toContain("coder-studio ui open-url");
     expect(CODER_STUDIO_OPEN_SKILL.content).not.toContain("coder-studio ui show-panel");
     expect(CODER_STUDIO_OPEN_SKILL.content).not.toContain("coder-studio ui run-command");
+    expect(CODER_STUDIO_OPEN_SKILL.files).toEqual([
+      {
+        relativePath: AUTOMATION_CMD_FILE_NAME,
+        content: BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+      },
+    ]);
     expect(BUILTIN_SKILLS).toContain(CODER_STUDIO_OPEN_SKILL);
   });
 
+  it("keeps built-in skill metadata descriptions in sync with SKILL.md frontmatter", () => {
+    for (const skill of BUILTIN_SKILLS) {
+      expect(extractFrontmatterDescription(skill.content)).toBe(skill.description);
+    }
+  });
+
+  it("limits the open skill canvas surface to ui.open-canvas only", () => {
+    expect(CODER_STUDIO_OPEN_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-canvas`
+    );
+    expect(CODER_STUDIO_OPEN_SKILL.content).toContain(
+      "open or close a workspace file, open or close a localhost URL, or open a canvas tab"
+    );
+    expect(CODER_STUDIO_OPEN_SKILL.content).not.toContain("ui.close-canvas");
+    expect(CODER_STUDIO_OPEN_SKILL.content).not.toContain("close a canvas");
+    expect(CODER_STUDIO_OPEN_SKILL.content).not.toContain(
+      "close a workspace file, localhost URL, or canvas tab"
+    );
+  });
+
   it("declares the workspace memory skill as default enabled and auto-mounted", () => {
     expect(CODER_STUDIO_MEMORY_SKILL).toMatchObject({
       slug: "coder-studio-memory",
       displayName: "Coder Studio Memory",
       defaultEnabled: true,
       autoMountInMvp: true,
+      mountRendering: "automation_bridge",
+      files: [{ relativePath: AUTOMATION_CMD_FILE_NAME }],
     });
-    expect(CODER_STUDIO_MEMORY_SKILL.content).toContain("coder-studio memory list");
-    expect(CODER_STUDIO_MEMORY_SKILL.content).toContain("coder-studio memory search");
-    expect(CODER_STUDIO_MEMORY_SKILL.content).toContain("coder-studio memory add");
+    expect(CODER_STUDIO_MEMORY_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.list`
+    );
+    expect(CODER_STUDIO_MEMORY_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.search`
+    );
+    expect(CODER_STUDIO_MEMORY_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.create`
+    );
     expect(CODER_STUDIO_MEMORY_SKILL.content).toContain(
       "Read workspace memory when you need to understand the project or context better, recover debugging information, verify commands or conventions, or review durable notes before making changes."
     );
@@ -73,18 +167,83 @@ describe("builtin skills", () => {
       "Write memory when you learn something durable that should help a future session, such as a confirmed project rule, a stable debugging conclusion, a reusable command, a repository convention, a technical constraint, a real follow-up todo, or an important feature constraint."
     );
     expect(CODER_STUDIO_MEMORY_SKILL.content).toContain(
-      "Use `feature` for product behavior, `todo` for pending work, `bugfix` for defects, `project` for repository-operating knowledge, and `note` only as a fallback."
+      "Use `wiki` for durable project knowledge, `issue` for defects or verification items, `todo` for concrete follow-up work, and `note` only as a fallback."
+    );
+    expect(CODER_STUDIO_MEMORY_SKILL.content).toContain(
+      "Status applies only to `issue` and `todo` memories. Use `not_started`, `in_progress`, `pending_verification`, or `completed` when the memory tracks work state."
     );
     expect(CODER_STUDIO_MEMORY_SKILL.content).toContain(
-      'coder-studio memory add --workspace <workspace-id> --type project --content "This workspace uses pnpm for package scripts." --skill coder-studio-memory --json'
+      'memory.create --type wiki --content "This workspace uses pnpm for package scripts." --skill coder-studio-memory --json'
     );
+    expect(CODER_STUDIO_MEMORY_SKILL.content).toContain(
+      'memory.create --type issue --content "Verify release notes before publishing." --status pending_verification --skill coder-studio-memory --json'
+    );
+    expect(CODER_STUDIO_MEMORY_SKILL.content).not.toContain("memory add");
+    expect(CODER_STUDIO_MEMORY_SKILL.content).not.toContain("coder-studio memory");
     expect(CODER_STUDIO_MEMORY_SKILL.content).not.toContain("--tag");
     expect(CODER_STUDIO_MEMORY_SKILL.content).not.toContain("--type decision");
+    expect(CODER_STUDIO_MEMORY_SKILL.content).not.toContain("--type project");
+    expect(CODER_STUDIO_MEMORY_SKILL.content).not.toContain("Use `feature`");
     expect(CODER_STUDIO_MEMORY_SKILL.content).not.toContain("--title");
     expect(CODER_STUDIO_MEMORY_SKILL.content).not.toContain("mem_");
+    expect(CODER_STUDIO_MEMORY_SKILL.files).toEqual([
+      {
+        relativePath: AUTOMATION_CMD_FILE_NAME,
+        content: BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+      },
+    ]);
     expect(BUILTIN_SKILLS).toContain(CODER_STUDIO_MEMORY_SKILL);
   });
 
+  it("declares the Coder Studio canvas skill as an auto-mounted built-in", () => {
+    expect(CODER_STUDIO_CANVAS_SKILL).toMatchObject({
+      slug: "coder-studio-canvas",
+      displayName: "Coder Studio Canvas",
+      version: "1.0.0",
+      defaultEnabled: true,
+      autoMountInMvp: true,
+      mountRendering: "automation_bridge",
+      files: [{ relativePath: AUTOMATION_CMD_FILE_NAME }],
+    });
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.create`
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.update`
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.render`
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-file --path .coder-studio/canvases/<title-slug>.csc --json`
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.render --source-path .coder-studio/canvases/<title-slug>.csc --json`
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-canvas --canvas <canvas-id> --json`
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain('"version": 1');
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      "raw HTML like `<div>` or `<span>` is invalid in canvas source"
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).toContain(
+      "readable `.coder-studio/canvases/<title-slug>.csc` paths"
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.content).not.toContain("coder-studio canvas create");
+    expect(CODER_STUDIO_CANVAS_SKILL.content).not.toContain("coder-studio ui open-file");
+    expect(CODER_STUDIO_CANVAS_SKILL.content).not.toContain(
+      ".coder-studio/canvases/<canvas-id>.canvas.json"
+    );
+    expect(CODER_STUDIO_CANVAS_SKILL.files).toEqual([
+      {
+        relativePath: AUTOMATION_CMD_FILE_NAME,
+        content: BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+      },
+    ]);
+    expect(BUILTIN_SKILLS).toContain(CODER_STUDIO_CANVAS_SKILL);
+  });
+
   it("materializes built-in SKILL.md files", async () => {
     tempDir = await mkdtemp(join(tmpdir(), "coder-studio-builtin-memory-"));
 
@@ -93,6 +252,8 @@ describe("builtin skills", () => {
       now: () => 1234,
     });
 
+    expect(entries).toHaveLength(3);
+
     const openEntry = entries.find((entry) => entry.slug === "coder-studio-open");
     expect(openEntry).toMatchObject({
       slug: "coder-studio-open",
@@ -103,8 +264,12 @@ describe("builtin skills", () => {
 
     const openContent = await readFile(join(openEntry!.libraryPath, "SKILL.md"), "utf8");
     expect(openContent).toContain("name: coder-studio-open");
-    expect(openContent).toContain("coder-studio ui open-file");
-    expect(openContent).toContain("coder-studio ui open-url");
+    expect(openContent).toContain(AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN);
+    expect(openContent).toContain("ui.open-file");
+    expect(openContent).toContain("ui.open-url");
+    expect(await readFile(join(openEntry!.libraryPath, AUTOMATION_CMD_FILE_NAME), "utf8")).toBe(
+      `${BUILTIN_AUTOMATION_BRIDGE_SOURCE.trimEnd()}\n`
+    );
 
     const memoryEntry = entries.find((entry) => entry.slug === "coder-studio-memory");
     expect(memoryEntry).toMatchObject({
@@ -116,10 +281,34 @@ describe("builtin skills", () => {
 
     const content = await readFile(join(memoryEntry!.libraryPath, "SKILL.md"), "utf8");
     expect(content).toContain("name: coder-studio-memory");
-    expect(content).toContain(
-      "Read workspace memory when you need to understand the project or context better"
-    );
+    expect(content).toContain(AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN);
+    expect(content).toContain("memory.search");
     expect(content).not.toContain("Actual workspace memory");
+    expect(await readFile(join(memoryEntry!.libraryPath, AUTOMATION_CMD_FILE_NAME), "utf8")).toBe(
+      `${BUILTIN_AUTOMATION_BRIDGE_SOURCE.trimEnd()}\n`
+    );
+
+    const canvasEntry = entries.find((entry) => entry.slug === "coder-studio-canvas");
+    expect(canvasEntry).toMatchObject({
+      slug: "coder-studio-canvas",
+      source: "builtin",
+      installState: "installed",
+      builtin: { defaultEnabled: true, autoMount: true },
+    });
+
+    const canvasContent = await readFile(join(canvasEntry!.libraryPath, "SKILL.md"), "utf8");
+    expect(canvasContent).toContain(AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN);
+    expect(canvasContent).toContain("canvas.create");
+    expect(canvasContent).toContain("ui.open-file --path .coder-studio/canvases/<title-slug>.csc");
+    expect(canvasContent).toContain(
+      "canvas.render --source-path .coder-studio/canvases/<title-slug>.csc"
+    );
+    expect(canvasContent).toContain("ui.open-canvas --canvas <canvas-id>");
+    expect(canvasContent).toContain("readable `.coder-studio/canvases/<title-slug>.csc` paths");
+    expect(canvasContent).not.toContain(".coder-studio/canvases/<canvas-id>.canvas.json");
+    expect(await readFile(join(canvasEntry!.libraryPath, AUTOMATION_CMD_FILE_NAME), "utf8")).toBe(
+      `${BUILTIN_AUTOMATION_BRIDGE_SOURCE.trimEnd()}\n`
+    );
   });
 
   it("materializes provided built-in SKILL.md files into the state directory", async () => {
@@ -145,4 +334,27 @@ describe("builtin skills", () => {
     expect(content).toContain("coder-studio-example-builtin");
     expect(content).toContain("Use this fixture only in tests.");
   });
+
+  it("materializes declared managed files alongside SKILL.md without rewriting placeholders", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "coder-studio-builtin-automation-"));
+
+    const entries = await materializeBuiltinSkills({
+      builtinRoot: tempDir,
+      now: () => 1234,
+      skills: [TEST_AUTOMATION_BUILTIN_SKILL],
+    });
+
+    expect(entries).toHaveLength(1);
+
+    const skillEntry = entries[0];
+    const skillContent = await readFile(join(skillEntry.libraryPath, "SKILL.md"), "utf8");
+    const cmdContent = await readFile(
+      join(skillEntry.libraryPath, AUTOMATION_CMD_FILE_NAME),
+      "utf8"
+    );
+
+    expect(skillContent).toContain(AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN);
+    expect(skillContent).not.toContain(skillEntry.libraryPath);
+    expect(cmdContent).toBe(`${BUILTIN_AUTOMATION_BRIDGE_SOURCE.trimEnd()}\n`);
+  });
 });
diff --git a/packages/server/src/__tests__/skills/builtin-sync-manager.test.ts b/packages/server/src/__tests__/skills/builtin-sync-manager.test.ts
index 5831513d1..a4f7b73c9 100644
--- a/packages/server/src/__tests__/skills/builtin-sync-manager.test.ts
+++ b/packages/server/src/__tests__/skills/builtin-sync-manager.test.ts
@@ -1,11 +1,16 @@
-import { lstat, mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { ProviderDefinition } from "@coder-studio/core";
 import { afterEach, describe, expect, it } from "vitest";
+import {
+  AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN,
+  AUTOMATION_CMD_FILE_NAME,
+} from "../../skills/builtin/automation-bridge.js";
 import type { BuiltinSkillDefinition } from "../../skills/builtin/registry.js";
 import { BUILTIN_SKILLS } from "../../skills/builtin/registry.js";
 import { BuiltinSkillSyncManager } from "../../skills/builtin/sync-manager.js";
+import { readManagedSkillMarker } from "../../skills/managed-skill-metadata.js";
 import { SkillMountManager } from "../../skills/mount-manager.js";
 import { SettingsRepo } from "../../storage/repositories/settings-repo.js";
 import { SkillLibraryRepo } from "../../storage/repositories/skill-library-repo.js";
@@ -29,6 +34,31 @@ const TEST_BUILTIN_SKILL: BuiltinSkillDefinition = {
   ].join("\n"),
 };
 
+const TEST_AUTOMATION_BRIDGE_SKILL: BuiltinSkillDefinition = {
+  slug: "coder-studio-automation-bridge-test",
+  displayName: "Coder Studio Automation Bridge Test",
+  description: "Test fixture for automation bridge mount rewriting.",
+  version: "1.0.0",
+  defaultEnabled: true,
+  autoMountInMvp: true,
+  mountRendering: "automation_bridge",
+  content: [
+    "---",
+    "name: coder-studio-automation-bridge-test",
+    "description: Automation bridge test fixture.",
+    "---",
+    "",
+    `Run \`node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}"\` to bridge.`,
+    "",
+  ].join("\n"),
+  files: [
+    {
+      relativePath: AUTOMATION_CMD_FILE_NAME,
+      content: 'console.log("bridge");',
+    },
+  ],
+};
+
 function provider(id: string, skillDir?: string): ProviderDefinition {
   return {
     id,
@@ -97,6 +127,20 @@ describe("BuiltinSkillSyncManager", () => {
     expect(result.libraryEntries.map((entry) => entry.slug)).toEqual(
       expect.arrayContaining(["coder-studio-open", "coder-studio-memory"])
     );
+    expect(result.libraryEntries).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          slug: "coder-studio-open",
+          source: "builtin",
+          origin: "builtin",
+        }),
+        expect.objectContaining({
+          slug: "coder-studio-memory",
+          source: "builtin",
+          origin: "builtin",
+        }),
+      ])
+    );
     expect(result.mounted).toEqual(
       expect.arrayContaining([
         expect.objectContaining({
@@ -109,10 +153,21 @@ describe("BuiltinSkillSyncManager", () => {
           skillSlug: "coder-studio-memory",
           status: "mounted",
         }),
+        expect.objectContaining({
+          providerId: "codex",
+          skillSlug: "coder-studio-canvas",
+          status: "mounted",
+        }),
       ])
     );
-    expect(result.mounted).toHaveLength(2);
+    expect(result.mounted).toHaveLength(3);
     expect(result.skipped).toEqual([]);
+    expect(readManagedSkillMarker(join(skillDir, "coder-studio-open"))).toEqual({
+      version: 1,
+      managedBy: "coder-studio",
+      source: "builtin",
+      slug: "coder-studio-open",
+    });
     expect(mountRepo.get("codex", "coder-studio-open")).toEqual(
       expect.objectContaining({
         providerId: "codex",
@@ -125,8 +180,15 @@ describe("BuiltinSkillSyncManager", () => {
         skillSlug: "coder-studio-memory",
       })
     );
+    expect(mountRepo.get("codex", "coder-studio-canvas")).toEqual(
+      expect.objectContaining({
+        providerId: "codex",
+        skillSlug: "coder-studio-canvas",
+      })
+    );
     await expect(lstat(join(skillDir, "coder-studio-open", "SKILL.md"))).resolves.toBeTruthy();
     await expect(lstat(join(skillDir, "coder-studio-memory", "SKILL.md"))).resolves.toBeTruthy();
+    await expect(lstat(join(skillDir, "coder-studio-canvas", "SKILL.md"))).resolves.toBeTruthy();
   });
 
   it("syncs provided built-ins into the library without auto-mounting by default", async () => {
@@ -216,6 +278,59 @@ describe("BuiltinSkillSyncManager", () => {
     });
   });
 
+  it("mounts automation-rendered builtins in copy mode with rewritten SKILL.md content", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "coder-studio-builtin-automation-"));
+    const builtinRoot = join(tempDir, "builtin");
+    const skillDir = join(tempDir, "codex-skills");
+    const providers = [provider("codex", skillDir)];
+    const libraryRepo = new SkillLibraryRepo({
+      filePath: join(tempDir, "library-index.json"),
+    });
+    const mountRepo = new SkillMountRepo({
+      filePath: join(tempDir, "mounts.json"),
+    });
+    const settingsRepo = new SettingsRepo({
+      filePath: join(tempDir, "settings.json"),
+    });
+    const mountManager = new SkillMountManager({
+      getProviderRegistry: () => providers,
+      skillLibraryRepo: libraryRepo,
+      skillMountRepo: mountRepo,
+    });
+
+    const manager = new BuiltinSkillSyncManager({
+      builtinRoot,
+      getProviderRegistry: () => providers,
+      skillLibraryRepo: libraryRepo,
+      skillMountRepo: mountRepo,
+      skillMountMgr: mountManager,
+      settingsRepo,
+      now: () => 1000,
+      skills: [TEST_AUTOMATION_BRIDGE_SKILL],
+    });
+
+    const result = await manager.sync();
+    const mountedPath = join(skillDir, TEST_AUTOMATION_BRIDGE_SKILL.slug);
+    const mountedSkillPath = join(mountedPath, "SKILL.md");
+    const expectedCmdPath = join(mountedPath, AUTOMATION_CMD_FILE_NAME);
+
+    expect(result.mounted).toEqual([
+      expect.objectContaining({
+        providerId: "codex",
+        skillSlug: TEST_AUTOMATION_BRIDGE_SKILL.slug,
+        mountModeResolved: "copy",
+      }),
+    ]);
+    expect((await lstat(mountedPath)).isSymbolicLink()).toBe(false);
+    await expect(readFile(mountedSkillPath, "utf8")).resolves.toContain(expectedCmdPath);
+    await expect(readFile(mountedSkillPath, "utf8")).resolves.not.toContain(
+      AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN
+    );
+    await expect(
+      readFile(join(builtinRoot, TEST_AUTOMATION_BRIDGE_SKILL.slug, "SKILL.md"), "utf8")
+    ).resolves.toContain(AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN);
+  });
+
   it("removes stale built-in skills without touching other installed skills", async () => {
     tempDir = await mkdtemp(join(tmpdir(), "coder-studio-builtin-stale-"));
     const builtinRoot = join(tempDir, "builtin");
@@ -258,7 +373,8 @@ describe("BuiltinSkillSyncManager", () => {
       displayName: "Frontend Design",
       description: "Installed from Skill Hub",
       version: "1.0.0",
-      source: "skillhub",
+      source: "installed",
+      origin: "skillhub",
       libraryPath: skillHubLibraryPath,
       installState: "installed",
       installedAt: 1,
@@ -303,7 +419,11 @@ describe("BuiltinSkillSyncManager", () => {
 
     expect(libraryRepo.get("old-builtin-skill")).toBeUndefined();
     expect(libraryRepo.get("frontend-design")).toEqual(
-      expect.objectContaining({ slug: "frontend-design", source: "skillhub" })
+      expect.objectContaining({
+        slug: "frontend-design",
+        source: "installed",
+        origin: "skillhub",
+      })
     );
     await expect(lstat(staleLibraryPath)).rejects.toThrow();
     await expect(lstat(staleTargetPath)).rejects.toThrow();
@@ -347,7 +467,11 @@ describe("BuiltinSkillSyncManager", () => {
     await symlink(staleLibraryPath, staleTargetPath);
 
     expect(libraryRepo.get("old-builtin-skill")).toEqual(
-      expect.objectContaining({ slug: "old-builtin-skill", source: "local" })
+      expect.objectContaining({
+        slug: "old-builtin-skill",
+        source: "installed",
+        origin: "filesystem",
+      })
     );
 
     const mountManager = new SkillMountManager({
@@ -408,7 +532,11 @@ describe("BuiltinSkillSyncManager", () => {
     await symlink(staleLibraryPath, providerTargetPath);
 
     expect(libraryRepo.get("old-builtin-skill")).toEqual(
-      expect.objectContaining({ slug: "old-builtin-skill", source: "local" })
+      expect.objectContaining({
+        slug: "old-builtin-skill",
+        source: "installed",
+        origin: "filesystem",
+      })
     );
 
     const mountManager = new SkillMountManager({
@@ -441,6 +569,66 @@ describe("BuiltinSkillSyncManager", () => {
     ]);
   });
 
+  it("removes copied stale built-in artifacts under a symlinked parent skill directory", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "coder-studio-builtin-stale-symlink-parent-copy-"));
+    const builtinRoot = join(tempDir, "dev", "state", "skills", "builtin");
+    const externalBuiltinRoot = join(tempDir, "prod", "state", "skills", "builtin");
+    const symlinkedSkillDir = join(tempDir, "agent-skills");
+    const staleLibraryPath = join(externalBuiltinRoot, "old-builtin-skill");
+    const staleTargetPath = join(symlinkedSkillDir, "old-builtin-skill");
+    const providers = [provider("codex", symlinkedSkillDir)];
+    const libraryRepo = new SkillLibraryRepo({
+      filePath: join(tempDir, "library-index.json"),
+      localSkillRoots: [symlinkedSkillDir],
+    });
+    const mountRepo = new SkillMountRepo({
+      filePath: join(tempDir, "mounts.json"),
+    });
+    const settingsRepo = new SettingsRepo({
+      filePath: join(tempDir, "settings.json"),
+    });
+
+    await mkdir(staleLibraryPath, { recursive: true });
+    await writeFile(join(staleLibraryPath, "SKILL.md"), "# Old Builtin\n", "utf8");
+    await symlink(externalBuiltinRoot, symlinkedSkillDir);
+
+    expect(libraryRepo.get("old-builtin-skill")).toEqual(
+      expect.objectContaining({
+        slug: "old-builtin-skill",
+        source: "installed",
+        origin: "filesystem",
+      })
+    );
+
+    const mountManager = new SkillMountManager({
+      getProviderRegistry: () => providers,
+      skillLibraryRepo: libraryRepo,
+      skillMountRepo: mountRepo,
+    });
+
+    const manager = new BuiltinSkillSyncManager({
+      builtinRoot,
+      getProviderRegistry: () => providers,
+      skillLibraryRepo: libraryRepo,
+      skillMountRepo: mountRepo,
+      skillMountMgr: mountManager,
+      settingsRepo,
+      now: () => 1000,
+    });
+
+    const result = await manager.sync();
+
+    expect(libraryRepo.get("old-builtin-skill")).toBeUndefined();
+    await expect(lstat(staleTargetPath)).rejects.toThrow();
+    await expect(lstat(staleLibraryPath)).rejects.toThrow();
+    expect(result.removed).toEqual([
+      {
+        skillSlug: "old-builtin-skill",
+        unmountedProviderIds: ["codex"],
+      },
+    ]);
+  });
+
   it("does not remove a real local skill that reuses a stale built-in slug", async () => {
     tempDir = await mkdtemp(join(tmpdir(), "coder-studio-builtin-stale-real-local-"));
     const builtinRoot = join(tempDir, "builtin");
@@ -485,7 +673,8 @@ describe("BuiltinSkillSyncManager", () => {
     expect(libraryRepo.get("old-builtin-skill")).toEqual(
       expect.objectContaining({
         slug: "old-builtin-skill",
-        source: "local",
+        source: "installed",
+        origin: "filesystem",
         libraryPath: localSkillPath,
       })
     );
diff --git a/packages/server/src/__tests__/skills/commands.test.ts b/packages/server/src/__tests__/skills/commands.test.ts
index 8610ba452..7f00ad4b2 100644
--- a/packages/server/src/__tests__/skills/commands.test.ts
+++ b/packages/server/src/__tests__/skills/commands.test.ts
@@ -1,10 +1,19 @@
-import { lstat, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import {
+  readFile as fsReadFile,
+  lstat,
+  mkdir,
+  mkdtemp,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Topics } from "@coder-studio/core";
 import { describe, expect, it, vi } from "vitest";
 import { registerSkillsCommands } from "../../commands/skills/index.js";
 import { SkillHealthManager } from "../../skills/health-manager.js";
+import { readManagedSkillMarker } from "../../skills/managed-skill-metadata.js";
 import { SkillMountManager } from "../../skills/mount-manager.js";
 import { SkillLibraryRepo } from "../../storage/repositories/skill-library-repo.js";
 import { SkillMountRepo } from "../../storage/repositories/skill-mount-repo.js";
@@ -13,6 +22,13 @@ import { dispatch } from "../../ws/dispatch.js";
 
 registerSkillsCommands();
 
+const PNG_BYTES = Buffer.from(
+  "89504E470D0A1A0A0000000D4948445200000001000000010806000000" +
+    "1F15C4890000000A49444154789C63000100000005000157CFC4A30000" +
+    "0000049454E44AE426082",
+  "hex"
+);
+
 function createBaseContext(overrides: Partial<CommandContext> = {}): CommandContext {
   return {
     workspaceMgr: {} as never,
@@ -62,7 +78,8 @@ describe("skills commands", () => {
           displayName: "Code Review",
           description: "Review code changes before merge",
           version: "1.2.3",
-          source: "skillhub",
+          source: "installed",
+          origin: "skillhub",
           libraryPath: "/library/code-review",
           installState: "installed",
           installedAt: 1,
@@ -155,7 +172,8 @@ describe("skills commands", () => {
                   displayName: "React Review",
                   description: "Review React code",
                   version: "1.0.0",
-                  source: "skillhub",
+                  source: "installed",
+                  origin: "skillhub",
                   libraryPath: "/library/react-review",
                   installState: "installed",
                   installedAt: 1,
@@ -200,22 +218,84 @@ describe("skills commands", () => {
       );
 
       expect(result.ok).toBe(true);
-      expect(result.data).toEqual([
-        expect.objectContaining({
-          slug: "vite-testing",
-          installed: false,
-          reason: expect.any(String),
-          sourceQuery: expect.any(String),
-        }),
-      ]);
+      expect(result.data).toEqual({
+        entries: [
+          expect.objectContaining({
+            slug: "vite-testing",
+            installed: false,
+            reason: expect.any(String),
+            sourceQuery: expect.any(String),
+          }),
+        ],
+        hasMore: false,
+      });
       expect(
-        (result.data as Array<{ slug: string }>).some((item) => item.slug === "react-review")
+        (result.data as { entries: Array<{ slug: string }> }).entries.some(
+          (item) => item.slug === "react-review"
+        )
       ).toBe(false);
     } finally {
       await rm(workspaceRoot, { recursive: true, force: true });
     }
   });
 
+  it("returns paginated recommendations with hasMore", async () => {
+    const workspaceRoot = await mkdtemp(join(tmpdir(), "skills-recommend-page-"));
+    try {
+      await writeFile(
+        join(workspaceRoot, "package.json"),
+        JSON.stringify(
+          {
+            dependencies: { react: "^19.0.0" },
+            scripts: { test: "vitest run" },
+          },
+          null,
+          2
+        )
+      );
+
+      const ctx = createBaseContext({
+        workspaceMgr: {
+          get: vi.fn(() => ({ id: "ws-1", path: workspaceRoot })),
+        } as never,
+        skillLibraryRepo: { get: vi.fn(() => undefined) } as never,
+        skillMountRepo: { listBySkillSlug: vi.fn(() => []) } as never,
+        skillsHubClient: {
+          search: vi.fn(async (query: string) =>
+            query.includes("React")
+              ? [
+                  { slug: "skill-a", displayName: "Skill A", description: "A" },
+                  { slug: "skill-b", displayName: "Skill B", description: "B" },
+                  { slug: "skill-c", displayName: "Skill C", description: "C" },
+                ]
+              : []
+          ),
+        } as never,
+      });
+
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "skills-recommend-page-1",
+          op: "skills.recommend",
+          args: { workspaceId: "ws-1", limit: 2, offset: 1 },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual({
+        entries: [
+          expect.objectContaining({ slug: "skill-b" }),
+          expect.objectContaining({ slug: "skill-c" }),
+        ],
+        hasMore: false,
+      });
+    } finally {
+      await rm(workspaceRoot, { recursive: true, force: true });
+    }
+  });
+
   it("returns merged remote and local info for a skill", async () => {
     const ctx = createBaseContext({
       skillLibraryRepo: {
@@ -224,7 +304,8 @@ describe("skills commands", () => {
           displayName: "Code Review",
           description: "Review code changes before merge",
           version: "1.2.3",
-          source: "skillhub",
+          source: "installed",
+          origin: "skillhub",
           libraryPath: "/library/code-review",
           installState: "installed",
           installedAt: 1,
@@ -285,7 +366,8 @@ describe("skills commands", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -360,7 +442,8 @@ describe("skills commands", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -371,7 +454,8 @@ describe("skills commands", () => {
             displayName: "Security Review",
             description: "Review security issues",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/library/security-review",
             installState: "installed",
             installedAt: 1,
@@ -381,7 +465,8 @@ describe("skills commands", () => {
             slug: "local-helper",
             displayName: "Local Helper",
             version: "local",
-            source: "local",
+            source: "custom",
+            origin: "filesystem",
             libraryPath: "/library/local-helper",
             installState: "installed",
             installedAt: 1,
@@ -451,7 +536,8 @@ describe("skills commands", () => {
             slug: "missing-version",
             displayName: "Missing Version",
             version: "1.0.0",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/library/missing-version",
             installState: "installed",
             installedAt: 1,
@@ -461,7 +547,8 @@ describe("skills commands", () => {
             slug: "lookup-failed",
             displayName: "Lookup Failed",
             version: "1.0.0",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/library/lookup-failed",
             installState: "installed",
             installedAt: 1,
@@ -545,6 +632,396 @@ describe("skills commands", () => {
     ]);
   });
 
+  it("creates a custom skill in the canonical custom root", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skills-custom-create-"));
+    const libraryFile = join(tempDir, "skill-library.json");
+    const customSkillRoot = join(tempDir, "state", "skills", "custom");
+    const externalSkillRoot = join(tempDir, "external-skills");
+    await mkdir(customSkillRoot, { recursive: true });
+    await mkdir(externalSkillRoot, { recursive: true });
+    const broadcast = vi.fn();
+    const skillLibraryRepo = new SkillLibraryRepo({
+      filePath: libraryFile,
+      customSkillRoot,
+      externalSkillRoots: [externalSkillRoot],
+    });
+    const ctx = createBaseContext({
+      broadcaster: { broadcast } as never,
+      skillsHubClient: {} as never,
+      skillLibraryRepo,
+      skillMountRepo: {
+        listBySkillSlug: vi.fn(() => []),
+      } as never,
+    });
+
+    try {
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "skills-custom-create-1",
+          op: "skills.custom.create",
+          args: { name: "My Review Skill" },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual(
+        expect.objectContaining({
+          slug: "my-review-skill",
+          source: "custom",
+          origin: "filesystem",
+          installState: "installed",
+          libraryPath: join(customSkillRoot, "my-review-skill"),
+        })
+      );
+      expect(skillLibraryRepo.get("my-review-skill")).toEqual(
+        expect.objectContaining({
+          slug: "my-review-skill",
+          source: "custom",
+          origin: "filesystem",
+        })
+      );
+      expect(readManagedSkillMarker(join(customSkillRoot, "my-review-skill"))).toEqual({
+        version: 1,
+        managedBy: "coder-studio",
+        source: "custom",
+        slug: "my-review-skill",
+      });
+      expect(broadcast).toHaveBeenCalledWith(
+        Topics.skillLibraryChanged,
+        expect.objectContaining({
+          reason: "custom_created",
+          slug: "my-review-skill",
+        })
+      );
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects custom skill creation when another source already owns the slug", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skills-custom-create-conflict-"));
+    const customSkillRoot = join(tempDir, "state", "skills", "custom");
+    const managedLibraryRoot = join(tempDir, "state", "skills", "library");
+    const existingLibraryPath = join(managedLibraryRoot, "my-review-skill");
+    await mkdir(existingLibraryPath, { recursive: true });
+    await writeFile(join(existingLibraryPath, "SKILL.md"), "# Existing\n");
+
+    const skillLibraryRepo = new SkillLibraryRepo({
+      filePath: join(tempDir, "skill-library.json"),
+      managedLibraryRoot,
+      customSkillRoot,
+    });
+    skillLibraryRepo.set({
+      slug: "my-review-skill",
+      displayName: "My Review Skill",
+      description: "Installed variant",
+      version: "1.0.0",
+      source: "installed",
+      origin: "skillhub",
+      libraryPath: existingLibraryPath,
+      installState: "installed",
+      installedAt: 1,
+      updatedAt: 1,
+    });
+    const ctx = createBaseContext({
+      broadcaster: { broadcast: vi.fn() } as never,
+      skillsHubClient: {} as never,
+      skillLibraryRepo,
+      skillMountRepo: {
+        listBySkillSlug: vi.fn(() => []),
+      } as never,
+    });
+
+    try {
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "skills-custom-create-conflict-1",
+          op: "skills.custom.create",
+          args: { name: "My Review Skill" },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(false);
+      expect(result.error).toMatchObject({
+        code: "skill_slug_conflict",
+        message: "A skill with slug my-review-skill already exists",
+      });
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("reads the file tree and files for local skills", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skills-files-read-"));
+    const customSkillRoot = join(tempDir, "state", "skills", "custom");
+    const skillRoot = join(customSkillRoot, "my-review-skill");
+    await mkdir(join(skillRoot, "refs"), { recursive: true });
+    await writeFile(join(skillRoot, "SKILL.md"), "# My Review Skill\n");
+    await writeFile(join(skillRoot, "refs", "guide.md"), "guide\n");
+    await writeFile(join(skillRoot, "pixel.png"), PNG_BYTES);
+    const skillLibraryRepo = new SkillLibraryRepo({
+      filePath: join(tempDir, "skill-library.json"),
+      customSkillRoot,
+    });
+    const ctx = createBaseContext({
+      skillsHubClient: {} as never,
+      skillLibraryRepo,
+      skillMountRepo: {
+        listBySkillSlug: vi.fn(() => []),
+      } as never,
+    });
+
+    try {
+      const treeResult = await dispatch(
+        {
+          kind: "command",
+          id: "skills-files-tree-1",
+          op: "skills.files.readTree",
+          args: { skillSlug: "my-review-skill" },
+        },
+        ctx
+      );
+      const textReadResult = await dispatch(
+        {
+          kind: "command",
+          id: "skills-files-read-1",
+          op: "skills.files.read",
+          args: { skillSlug: "my-review-skill", path: "refs/guide.md" },
+        },
+        ctx
+      );
+      const imageReadResult = await dispatch(
+        {
+          kind: "command",
+          id: "skills-files-read-2",
+          op: "skills.files.read",
+          args: { skillSlug: "my-review-skill", path: "pixel.png" },
+        },
+        ctx
+      );
+
+      expect(treeResult.ok).toBe(true);
+      expect((treeResult.data as { path: string }).path).toBe(".");
+      expect(
+        (treeResult.data as { children: Array<{ path: string; kind: string }> }).children
+      ).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ path: "refs", kind: "dir" }),
+          expect.objectContaining({ path: "SKILL.md", kind: "file" }),
+        ])
+      );
+      expect(textReadResult.ok).toBe(true);
+      expect(textReadResult.data).toMatchObject({
+        kind: "text",
+        content: "guide\n",
+        displayPath: join(skillRoot, "refs", "guide.md"),
+        baseHash: expect.any(String),
+      });
+      expect(imageReadResult.ok).toBe(true);
+      expect(imageReadResult.data).toMatchObject({
+        kind: "image",
+        mime: "image/png",
+        url: "/api/skill-file?skillSlug=my-review-skill&path=pixel.png",
+        size: PNG_BYTES.length,
+      });
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("writes and mutates local skill files through skill file commands", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skills-files-write-"));
+    const customSkillRoot = join(tempDir, "state", "skills", "custom");
+    const skillRoot = join(customSkillRoot, "my-review-skill");
+    await mkdir(skillRoot, { recursive: true });
+    await writeFile(join(skillRoot, "SKILL.md"), "# My Review Skill\n");
+    await writeFile(join(skillRoot, "draft.md"), "draft\n");
+    const broadcast = vi.fn();
+    const skillLibraryRepo = new SkillLibraryRepo({
+      filePath: join(tempDir, "skill-library.json"),
+      customSkillRoot,
+    });
+    const ctx = createBaseContext({
+      broadcaster: { broadcast } as never,
+      skillsHubClient: {} as never,
+      skillLibraryRepo,
+      skillMountRepo: {
+        listBySkillSlug: vi.fn(() => []),
+      } as never,
+    });
+
+    try {
+      const writeResult = await dispatch(
+        {
+          kind: "command",
+          id: "skills-files-write-1",
+          op: "skills.files.write",
+          args: { skillSlug: "my-review-skill", path: "draft.md", content: "updated\n" },
+        },
+        ctx
+      );
+      expect(writeResult.ok).toBe(true);
+      expect(writeResult.data).toMatchObject({ newHash: expect.any(String) });
+      expect(await fsReadFile(join(skillRoot, "draft.md"), "utf8")).toBe("updated\n");
+
+      const createResult = await dispatch(
+        {
+          kind: "command",
+          id: "skills-files-create-1",
+          op: "skills.files.create",
+          args: { skillSlug: "my-review-skill", path: "notes/today.md" },
+        },
+        ctx
+      );
+      const mkdirResult = await dispatch(
+        {
+          kind: "command",
+          id: "skills-files-mkdir-1",
+          op: "skills.files.mkdir",
+          args: { skillSlug: "my-review-skill", path: "archive" },
+        },
+        ctx
+      );
+      const renameResult = await dispatch(
+        {
+          kind: "command",
+          id: "skills-files-rename-1",
+          op: "skills.files.rename",
+          args: {
+            skillSlug: "my-review-skill",
+            fromPath: "draft.md",
+            toPath: "final.md",
+          },
+        },
+        ctx
+      );
+      expect(createResult.ok).toBe(true);
+      expect(await fsReadFile(join(skillRoot, "notes", "today.md"), "utf8")).toBe("");
+      expect(mkdirResult.ok).toBe(true);
+      expect((await stat(join(skillRoot, "archive"))).isDirectory()).toBe(true);
+      expect(renameResult.ok).toBe(true);
+      expect(await fsReadFile(join(skillRoot, "final.md"), "utf8")).toBe("updated\n");
+      const deleteResult = await dispatch(
+        {
+          kind: "command",
+          id: "skills-files-delete-1",
+          op: "skills.files.delete",
+          args: { skillSlug: "my-review-skill", path: "notes/today.md" },
+        },
+        ctx
+      );
+      expect(deleteResult.ok).toBe(true);
+      await expect(stat(join(skillRoot, "notes", "today.md"))).rejects.toThrow();
+      expect(broadcast).toHaveBeenCalledTimes(5);
+      expect(broadcast).toHaveBeenCalledWith(
+        Topics.skillLibraryChanged,
+        expect.objectContaining({
+          reason: "skill_files_changed",
+          skillSlug: "my-review-skill",
+        })
+      );
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects skill file commands for non-custom skills", async () => {
+    const ctx = createBaseContext({
+      skillsHubClient: {} as never,
+      skillLibraryRepo: {
+        get: vi.fn(() => ({
+          slug: "code-review",
+          displayName: "Code Review",
+          version: "1.0.0",
+          source: "installed",
+          origin: "skillhub",
+          libraryPath: "/library/code-review",
+          installState: "installed",
+          installedAt: 1,
+          updatedAt: 1,
+        })),
+      } as never,
+      skillMountRepo: {
+        listBySkillSlug: vi.fn(() => []),
+      } as never,
+    });
+
+    const results = await Promise.all([
+      dispatch(
+        {
+          kind: "command",
+          id: "skills-files-nonlocal-tree-1",
+          op: "skills.files.readTree",
+          args: { skillSlug: "code-review" },
+        },
+        ctx
+      ),
+      dispatch(
+        {
+          kind: "command",
+          id: "skills-files-nonlocal-read-1",
+          op: "skills.files.read",
+          args: { skillSlug: "code-review", path: "SKILL.md" },
+        },
+        ctx
+      ),
+      dispatch(
+        {
+          kind: "command",
+          id: "skills-files-nonlocal-write-1",
+          op: "skills.files.write",
+          args: { skillSlug: "code-review", path: "SKILL.md", content: "updated\n" },
+        },
+        ctx
+      ),
+      dispatch(
+        {
+          kind: "command",
+          id: "skills-files-nonlocal-create-1",
+          op: "skills.files.create",
+          args: { skillSlug: "code-review", path: "new.md" },
+        },
+        ctx
+      ),
+      dispatch(
+        {
+          kind: "command",
+          id: "skills-files-nonlocal-mkdir-1",
+          op: "skills.files.mkdir",
+          args: { skillSlug: "code-review", path: "refs" },
+        },
+        ctx
+      ),
+      dispatch(
+        {
+          kind: "command",
+          id: "skills-files-nonlocal-rename-1",
+          op: "skills.files.rename",
+          args: { skillSlug: "code-review", fromPath: "a.md", toPath: "b.md" },
+        },
+        ctx
+      ),
+      dispatch(
+        {
+          kind: "command",
+          id: "skills-files-nonlocal-delete-1",
+          op: "skills.files.delete",
+          args: { skillSlug: "code-review", path: "SKILL.md" },
+        },
+        ctx
+      ),
+    ]);
+
+    expect(results.every((result) => result.ok === false)).toBe(true);
+    for (const result of results) {
+      expect(result.error?.code).toBe("skill_not_found");
+    }
+  });
+
   it("syncs builtin skills through command dispatch", async () => {
     const sync = vi.fn(async () => ({
       libraryEntries: [],
@@ -690,7 +1167,8 @@ describe("skills commands", () => {
           displayName: "Code Review",
           description: "Review code changes before merge",
           version: "1.2.3",
-          source: "skillhub",
+          source: "installed",
+          origin: "skillhub",
           libraryPath: "/library/code-review",
           installState: "installed",
           installedAt: 1,
@@ -722,7 +1200,8 @@ describe("skills commands", () => {
           slug: "local-helper",
           displayName: "Local Helper",
           version: "local",
-          source: "local",
+          source: "custom",
+          origin: "filesystem",
           libraryPath: "/library/local-helper",
           installState: "installed",
           installedAt: 1,
@@ -749,6 +1228,43 @@ describe("skills commands", () => {
     expect(start).not.toHaveBeenCalled();
   });
 
+  it("rejects update requests for filesystem-installed skills", async () => {
+    const start = vi.fn();
+    const ctx = createBaseContext({
+      skillInstallMgr: { start } as never,
+      skillLibraryRepo: {
+        get: vi.fn(() => ({
+          slug: "code-review",
+          displayName: "Code Review",
+          version: "1.0.0",
+          source: "installed",
+          origin: "filesystem",
+          libraryPath: "/library/code-review",
+          installState: "installed",
+          installedAt: 1,
+          updatedAt: 2,
+        })),
+      } as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "skills-update-start-filesystem-1",
+        op: "skills.update.start",
+        args: { slug: "code-review" },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatchObject({
+      code: "skill_update_unavailable",
+      message: "Only installed Skill Hub skills can be updated: code-review",
+    });
+    expect(start).not.toHaveBeenCalled();
+  });
+
   it("rejects update requests for Skill Hub skills that are not installed", async () => {
     const start = vi.fn();
     const ctx = createBaseContext({
@@ -759,7 +1275,8 @@ describe("skills commands", () => {
           displayName: "Code Review",
           description: "Review code changes before merge",
           version: "1.2.3",
-          source: "skillhub",
+          source: "installed",
+          origin: "skillhub",
           libraryPath: "/library/code-review",
           installState: "failed",
           installedAt: 1,
@@ -844,7 +1361,8 @@ describe("skills commands", () => {
         displayName: "Code Review",
         description: "Review code changes before merge",
         version: "1.0.0",
-        source: "skillhub",
+        source: "installed",
+        origin: "skillhub",
         libraryPath,
         installState: "installed",
         installedAt: 1,
@@ -927,7 +1445,8 @@ describe("skills commands", () => {
         displayName: "Code Review",
         description: "Review code changes before merge",
         version: "local",
-        source: "local",
+        source: "custom",
+        origin: "filesystem",
         libraryPath: localSkillPath,
         installState: "installed",
         installedAt: 1,
@@ -1013,7 +1532,8 @@ describe("skills commands", () => {
         displayName: "Code Review",
         description: "Review code changes before merge",
         version: "local",
-        source: "local",
+        source: "custom",
+        origin: "filesystem",
         libraryPath: localSkillPath,
         installState: "installed",
         installedAt: 1,
@@ -1107,7 +1627,8 @@ describe("skills commands", () => {
         displayName: "Code Review",
         description: "Review code changes before merge",
         version: "1.0.0",
-        source: "skillhub",
+        source: "installed",
+        origin: "skillhub",
         libraryPath,
         installState: "installed",
         installedAt: 1,
@@ -1211,7 +1732,7 @@ describe("skills commands", () => {
     ]);
   });
 
-  it("uninstalls a skill by removing repo state and library directory", async () => {
+  it("uninstalls a Skill Hub skill by removing repo state without deleting third-party filesystem directories", async () => {
     const tempDir = join(tmpdir(), `skill-uninstall-${Date.now()}`);
     const libraryPath = join(tempDir, "code-review");
     await mkdir(libraryPath, { recursive: true });
@@ -1226,7 +1747,8 @@ describe("skills commands", () => {
           slug: "code-review",
           displayName: "Code Review",
           version: "1.0.0",
-          source: "skillhub",
+          source: "installed",
+          origin: "skillhub",
           libraryPath,
           installState: "installed",
           installedAt: 1,
@@ -1261,7 +1783,7 @@ describe("skills commands", () => {
         slug: "code-review",
       })
     );
-    await expect(rm(libraryPath, { recursive: true, force: false })).rejects.toBeTruthy();
+    await expect(lstat(libraryPath)).resolves.toBeTruthy();
   });
 
   it("rejects uninstalling built-in skills", async () => {
@@ -1313,6 +1835,288 @@ describe("skills commands", () => {
     await rm(tempDir, { recursive: true, force: true });
   });
 
+  it("rejects uninstalling custom skills without force", async () => {
+    const tempDir = join(tmpdir(), `skill-uninstall-custom-${Date.now()}`);
+    const libraryPath = join(tempDir, "my-review-skill");
+    await mkdir(libraryPath, { recursive: true });
+    const deleteBySkillSlug = vi.fn();
+    const deleteEntry = vi.fn();
+    const ctx = createBaseContext({
+      skillsHubClient: {} as never,
+      skillLibraryRepo: {
+        get: vi.fn(() => ({
+          slug: "my-review-skill",
+          displayName: "My Review Skill",
+          version: "local",
+          source: "custom",
+          origin: "filesystem",
+          libraryPath,
+          installState: "installed",
+          installedAt: 1,
+          updatedAt: 1,
+        })),
+        delete: deleteEntry,
+      } as never,
+      skillMountRepo: {
+        listBySkillSlug: vi.fn(() => []),
+        deleteBySkillSlug,
+      } as never,
+      skillMountMgr: {} as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "skills-uninstall-custom-1",
+        op: "skills.uninstall",
+        args: { slug: "my-review-skill" },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe("skill_uninstall_confirmation_required");
+    expect(deleteBySkillSlug).not.toHaveBeenCalled();
+    expect(deleteEntry).not.toHaveBeenCalled();
+    expect((await lstat(libraryPath)).isDirectory()).toBe(true);
+
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("rejects uninstalling filesystem-installed skills", async () => {
+    const tempDir = join(tmpdir(), `skill-uninstall-filesystem-${Date.now()}`);
+    const libraryPath = join(tempDir, "code-review");
+    await mkdir(libraryPath, { recursive: true });
+    const deleteBySkillSlug = vi.fn();
+    const deleteEntry = vi.fn();
+    const ctx = createBaseContext({
+      skillsHubClient: {} as never,
+      skillLibraryRepo: {
+        get: vi.fn(() => ({
+          slug: "code-review",
+          displayName: "Code Review",
+          version: "1.0.0",
+          source: "installed",
+          origin: "filesystem",
+          libraryPath,
+          installState: "installed",
+          installedAt: 1,
+          updatedAt: 1,
+        })),
+        delete: deleteEntry,
+      } as never,
+      skillMountRepo: {
+        listBySkillSlug: vi.fn(() => []),
+        deleteBySkillSlug,
+      } as never,
+      skillMountMgr: {} as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "skills-uninstall-filesystem-1",
+        op: "skills.uninstall",
+        args: { slug: "code-review", force: true },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe("skill_uninstall_unavailable");
+    expect(deleteBySkillSlug).not.toHaveBeenCalled();
+    expect(deleteEntry).not.toHaveBeenCalled();
+    expect((await lstat(libraryPath)).isDirectory()).toBe(true);
+
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("force deletes custom skills and unmounts their relations", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skill-uninstall-custom-force-"));
+    const libraryPath = join(tempDir, "state", "skills", "custom", "my-review-skill");
+    await mkdir(libraryPath, { recursive: true });
+    await writeFile(join(libraryPath, "SKILL.md"), "# My Review Skill\n");
+    await writeFile(
+      join(libraryPath, ".coder-studio-skill.json"),
+      JSON.stringify({
+        version: 1,
+        managedBy: "coder-studio",
+        source: "custom",
+        slug: "my-review-skill",
+      }),
+      "utf8"
+    );
+    const deleteBySkillSlug = vi.fn();
+    const deleteEntry = vi.fn();
+    const unmount = vi.fn(async () => undefined);
+    const broadcast = vi.fn();
+    const ctx = createBaseContext({
+      broadcaster: { broadcast } as never,
+      skillsHubClient: {} as never,
+      skillLibraryRepo: {
+        get: vi.fn(() => ({
+          slug: "my-review-skill",
+          displayName: "My Review Skill",
+          version: "local",
+          source: "custom",
+          origin: "filesystem",
+          libraryPath,
+          installState: "installed",
+          installedAt: 1,
+          updatedAt: 1,
+        })),
+        getCustomSkillRoot: vi.fn(() => join(tempDir, "state", "skills", "custom")),
+        delete: deleteEntry,
+      } as never,
+      skillMountRepo: {
+        listBySkillSlug: vi.fn(() => [
+          {
+            providerId: "codex",
+            skillSlug: "my-review-skill",
+            enabled: true,
+            sourcePath: libraryPath,
+            targetPath: join(tempDir, ".agents", "skills", "my-review-skill"),
+            mountModeResolved: "symlink",
+            status: "mounted",
+          },
+          {
+            providerId: "claude",
+            skillSlug: "my-review-skill",
+            enabled: false,
+            sourcePath: libraryPath,
+            targetPath: join(tempDir, ".claude", "skills", "my-review-skill"),
+            mountModeResolved: "copy",
+            status: "mounted",
+          },
+        ]),
+        deleteBySkillSlug,
+      } as never,
+      skillMountMgr: { unmount } as never,
+    });
+
+    try {
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "skills-uninstall-custom-force-1",
+          op: "skills.uninstall",
+          args: { slug: "my-review-skill", force: true },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      expect(unmount).toHaveBeenCalledTimes(2);
+      expect(deleteBySkillSlug).toHaveBeenCalledWith("my-review-skill");
+      expect(deleteEntry).toHaveBeenCalledWith("my-review-skill");
+      await expect(lstat(libraryPath)).rejects.toThrow();
+      expect(broadcast).toHaveBeenCalledWith(
+        Topics.skillLibraryChanged,
+        expect.objectContaining({
+          reason: "uninstalled",
+          slug: "my-review-skill",
+        })
+      );
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not delete a custom skill path outside the configured custom root", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skill-uninstall-custom-guard-"));
+    const customSkillRoot = join(tempDir, "state", "skills", "custom");
+    const unrelatedPath = join(tempDir, "external", "my-review-skill");
+    await mkdir(customSkillRoot, { recursive: true });
+    await mkdir(unrelatedPath, { recursive: true });
+    await writeFile(join(unrelatedPath, "SKILL.md"), "# My Review Skill\n");
+    const deleteBySkillSlug = vi.fn();
+    const deleteEntry = vi.fn();
+    const ctx = createBaseContext({
+      skillsHubClient: {} as never,
+      skillLibraryRepo: {
+        get: vi.fn(() => ({
+          slug: "my-review-skill",
+          displayName: "My Review Skill",
+          version: "local",
+          source: "custom",
+          origin: "filesystem",
+          libraryPath: unrelatedPath,
+          installState: "installed",
+          installedAt: 1,
+          updatedAt: 1,
+        })),
+        getCustomSkillRoot: vi.fn(() => customSkillRoot),
+        delete: deleteEntry,
+      } as never,
+      skillMountRepo: {
+        listBySkillSlug: vi.fn(() => []),
+        deleteBySkillSlug,
+      } as never,
+      skillMountMgr: { unmount: vi.fn(async () => undefined) } as never,
+    });
+
+    try {
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "skills-uninstall-custom-guard-1",
+          op: "skills.uninstall",
+          args: { slug: "my-review-skill", force: true },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      await expect(lstat(unrelatedPath)).resolves.toBeTruthy();
+      expect(deleteBySkillSlug).toHaveBeenCalledWith("my-review-skill");
+      expect(deleteEntry).toHaveBeenCalledWith("my-review-skill");
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects Skill Hub installs when another source already owns the slug", async () => {
+    const start = vi.fn(async () => ({
+      jobId: "job-install-conflict-1",
+      slug: "code-review",
+      status: "queued",
+      steps: [],
+    }));
+    const ctx = createBaseContext({
+      skillInstallMgr: { start } as never,
+      skillLibraryRepo: {
+        get: vi.fn(() => ({
+          slug: "code-review",
+          displayName: "Code Review",
+          version: "local",
+          source: "custom",
+          origin: "filesystem",
+          libraryPath: "/skills/custom/code-review",
+          installState: "installed",
+          installedAt: 1,
+          updatedAt: 1,
+        })),
+      } as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "skills-install-start-conflict-1",
+        op: "skills.install.start",
+        args: { slug: "code-review" },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatchObject({
+      code: "skill_slug_conflict",
+      message: "A skill with slug code-review already exists",
+    });
+    expect(start).not.toHaveBeenCalled();
+  });
+
   it("scans and persists mount health state", async () => {
     const upsert = vi.fn();
     const ctx = createBaseContext({
@@ -1374,7 +2178,8 @@ describe("skills commands", () => {
         displayName: "Code Review",
         description: "Review code changes before merge",
         version: "1.0.0",
-        source: "skillhub",
+        source: "installed",
+        origin: "skillhub",
         libraryPath,
         installState: "installed",
         installedAt: 1,
@@ -1459,7 +2264,8 @@ describe("skills commands", () => {
         displayName: "Code Review",
         description: "Review code changes before merge",
         version: "1.0.0",
-        source: "skillhub",
+        source: "installed",
+        origin: "skillhub",
         libraryPath,
         installState: "installed",
         installedAt: 1,
diff --git a/packages/server/src/__tests__/skills/custom-skill.test.ts b/packages/server/src/__tests__/skills/custom-skill.test.ts
new file mode 100644
index 000000000..0a55e9027
--- /dev/null
+++ b/packages/server/src/__tests__/skills/custom-skill.test.ts
@@ -0,0 +1,44 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createCustomSkill, slugifySkillName } from "../../skills/custom-skill.js";
+import { readManagedSkillMarker } from "../../skills/managed-skill-metadata.js";
+
+const tempDirs: string[] = [];
+
+async function createTempRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "custom-skill-"));
+  tempDirs.push(root);
+  return root;
+}
+
+describe("custom skill helpers", () => {
+  afterEach(async () => {
+    await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  it("slugifies a display name into a stable directory slug", () => {
+    expect(slugifySkillName("My Review Skill")).toBe("my-review-skill");
+  });
+
+  it("creates <root>/<slug>/SKILL.md with a default template", async () => {
+    const rootDir = await createTempRoot();
+
+    const entry = await createCustomSkill({ rootDir, name: "My Review Skill" });
+
+    expect(entry.slug).toBe("my-review-skill");
+    expect(entry.source).toBe("custom");
+    expect(entry.origin).toBe("filesystem");
+    expect(entry.installState).toBe("installed");
+    expect(await readFile(join(rootDir, "my-review-skill", "SKILL.md"), "utf8")).toContain(
+      "# My Review Skill"
+    );
+    expect(readManagedSkillMarker(join(rootDir, "my-review-skill"))).toEqual({
+      version: 1,
+      managedBy: "coder-studio",
+      source: "custom",
+      slug: "my-review-skill",
+    });
+  });
+});
diff --git a/packages/server/src/__tests__/skills/file-io.test.ts b/packages/server/src/__tests__/skills/file-io.test.ts
new file mode 100644
index 000000000..1afb114c7
--- /dev/null
+++ b/packages/server/src/__tests__/skills/file-io.test.ts
@@ -0,0 +1,68 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { readSkillFile, readSkillTree } from "../../commands/skills/files.js";
+
+const PNG_BYTES = Buffer.from(
+  "89504E470D0A1A0A0000000D4948445200000001000000010806000000" +
+    "1F15C4890000000A49444154789C63000100000005000157CFC4A30000" +
+    "0000049454E44AE426082",
+  "hex"
+);
+
+const tempDirs: string[] = [];
+
+async function createSkillRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "skill-file-io-"));
+  tempDirs.push(root);
+  await mkdir(join(root, "refs"), { recursive: true });
+  await writeFile(join(root, "SKILL.md"), "# My Review Skill\n");
+  await writeFile(join(root, "refs", "guide.md"), "guide\n");
+  await writeFile(join(root, "pixel.png"), PNG_BYTES);
+  return root;
+}
+
+describe("skill file helpers", () => {
+  afterEach(async () => {
+    await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  it("reads a skill tree with root-relative paths", async () => {
+    const skillRoot = await createSkillRoot();
+
+    const result = await readSkillTree(skillRoot);
+
+    expect(result.path).toBe(".");
+    expect(result.children).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: "refs", kind: "dir" }),
+        expect.objectContaining({ path: "SKILL.md", kind: "file" }),
+      ])
+    );
+  });
+
+  it("rejects path escape attempts when reading skill files", async () => {
+    const skillRoot = await createSkillRoot();
+
+    await expect(
+      readSkillFile("my-review-skill", skillRoot, "../outside.md")
+    ).rejects.toMatchObject({
+      code: "path_escape",
+    });
+  });
+
+  it("returns skill image reads with the skill asset URL shape", async () => {
+    const skillRoot = await createSkillRoot();
+
+    const result = await readSkillFile("my-review-skill", skillRoot, "pixel.png");
+
+    expect(result).toMatchObject({
+      kind: "image",
+      mime: "image/png",
+      url: "/api/skill-file?skillSlug=my-review-skill&path=pixel.png",
+      size: PNG_BYTES.length,
+      isTextBacked: false,
+    });
+  });
+});
diff --git a/packages/server/src/__tests__/skills/install-manager.test.ts b/packages/server/src/__tests__/skills/install-manager.test.ts
index 5ca788515..860ef09b8 100644
--- a/packages/server/src/__tests__/skills/install-manager.test.ts
+++ b/packages/server/src/__tests__/skills/install-manager.test.ts
@@ -110,6 +110,77 @@ describe("SkillInstallManager", () => {
       await expect(lstat(join(uninstalledSkillDir, "code-review"))).rejects.toBeTruthy();
       expect(skillMountRepo.get("uninstalled-agent", "code-review")).toBeUndefined();
       expect(skillMountRepo.get("unconfigured-agent", "code-review")).toBeUndefined();
+      expect(skillLibraryRepo.get("code-review")).toEqual(
+        expect.objectContaining({
+          slug: "code-review",
+          source: "installed",
+          origin: "skillhub",
+        })
+      );
+    } finally {
+      await rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("rejects Skill Hub installs when a custom skill already owns the slug", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skill-install-conflict-custom-"));
+    try {
+      const libraryRoot = join(tempDir, "library");
+      const customSkillPath = join(tempDir, "state", "skills", "custom", "code-review");
+      await mkdir(customSkillPath, { recursive: true });
+      await writeFile(join(customSkillPath, "SKILL.md"), "# Custom Code Review\n");
+
+      const skillLibraryRepo = new SkillLibraryRepo({
+        filePath: join(tempDir, "library-index.json"),
+        customSkillRoot: join(tempDir, "state", "skills", "custom"),
+      });
+      skillLibraryRepo.set({
+        slug: "code-review",
+        displayName: "Code Review",
+        description: "Custom version",
+        version: "local",
+        source: "custom",
+        origin: "filesystem",
+        libraryPath: customSkillPath,
+        installState: "installed",
+        installedAt: 1,
+        updatedAt: 1,
+      });
+
+      const manager = new SkillInstallManager({
+        skillsHubClient: {
+          info: vi.fn(async () => ({
+            slug: "code-review",
+            name: "Code Review",
+            description: "Review code changes before merge",
+            version: "1.2.3",
+          })),
+          stageInstall: vi.fn(async () => {
+            throw new Error("stageInstall should not run");
+          }),
+          readStagedSkill: vi.fn(async () => "skill body"),
+          cleanupStage: vi.fn(async () => undefined),
+        } as never,
+        skillLibraryRepo,
+        libraryRoot,
+      });
+
+      const started = await manager.start("code-review");
+      const finished = await waitForJob(manager, started.jobId);
+
+      expect(finished?.status).toBe("failed");
+      expect(finished?.failure).toMatchObject({
+        code: "unknown_failure",
+        message: "A skill with slug code-review already exists",
+      });
+      expect(skillLibraryRepo.get("code-review")).toEqual(
+        expect.objectContaining({
+          source: "custom",
+          origin: "filesystem",
+          libraryPath: customSkillPath,
+        })
+      );
+      await expect(lstat(customSkillPath)).resolves.toBeTruthy();
     } finally {
       await rm(tempDir, { recursive: true, force: true });
     }
diff --git a/packages/server/src/__tests__/skills/local-skill-scanner.test.ts b/packages/server/src/__tests__/skills/local-skill-scanner.test.ts
new file mode 100644
index 000000000..2c9492947
--- /dev/null
+++ b/packages/server/src/__tests__/skills/local-skill-scanner.test.ts
@@ -0,0 +1,143 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  scanDiscoveredSkillEntries,
+  scanLocalSkillEntries,
+} from "../../skills/local-skill-scanner.js";
+
+describe("local skill scanner", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "local-skill-scanner-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("treats the canonical custom root as custom filesystem skills", async () => {
+    const externalRoot = join(tempDir, "external");
+    const customRoot = join(tempDir, "custom");
+    const slug = "code-review";
+    const externalSkillDir = join(externalRoot, slug);
+    const customSkillDir = join(customRoot, slug);
+
+    await mkdir(externalSkillDir, { recursive: true });
+    await mkdir(customSkillDir, { recursive: true });
+    await writeFile(
+      join(externalSkillDir, "SKILL.md"),
+      ["---", "name: code-review", "description: External copy", "---", "", "# External", ""].join(
+        "\n"
+      ),
+      "utf8"
+    );
+    await writeFile(
+      join(customSkillDir, "SKILL.md"),
+      ["---", "name: code-review", "description: Custom copy", "---", "", "# Custom", ""].join(
+        "\n"
+      ),
+      "utf8"
+    );
+
+    expect(
+      scanDiscoveredSkillEntries({
+        customRoot,
+        externalRoots: [externalRoot],
+      })
+    ).toEqual([
+      expect.objectContaining({
+        slug,
+        description: "Custom copy",
+        source: "custom",
+        origin: "filesystem",
+        libraryPath: customSkillDir,
+      }),
+    ]);
+  });
+
+  it("marks filesystem skills outside the custom root as installed", async () => {
+    const externalRoot = join(tempDir, "external");
+    const skillDir = join(externalRoot, "code-review");
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(
+      join(skillDir, "SKILL.md"),
+      ["---", "name: code-review", "description: External copy", "---", "", "# External", ""].join(
+        "\n"
+      ),
+      "utf8"
+    );
+
+    expect(scanLocalSkillEntries([externalRoot])).toEqual([
+      expect.objectContaining({
+        slug: "code-review",
+        source: "installed",
+        origin: "filesystem",
+      }),
+    ]);
+  });
+
+  it("skips managed mirrors discovered under external roots", async () => {
+    const externalRoot = join(tempDir, "external");
+    const skillDir = join(externalRoot, "coder-studio-open");
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(
+      join(skillDir, "SKILL.md"),
+      [
+        "---",
+        "name: coder-studio-open",
+        "description: Mirror copy",
+        "---",
+        "",
+        "# Mirror",
+        "",
+      ].join("\n"),
+      "utf8"
+    );
+    await writeFile(
+      join(skillDir, ".coder-studio-skill.json"),
+      JSON.stringify({
+        version: 1,
+        managedBy: "coder-studio",
+        source: "builtin",
+        slug: "coder-studio-open",
+      }),
+      "utf8"
+    );
+
+    expect(scanLocalSkillEntries([externalRoot])).toEqual([]);
+  });
+
+  it("skips managed custom mirrors discovered under external roots", async () => {
+    const externalRoot = join(tempDir, "external");
+    const skillDir = join(externalRoot, "coder-studio-open");
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(
+      join(skillDir, "SKILL.md"),
+      [
+        "---",
+        "name: coder-studio-open",
+        "description: Mirror copy",
+        "---",
+        "",
+        "# Mirror",
+        "",
+      ].join("\n"),
+      "utf8"
+    );
+    await writeFile(
+      join(skillDir, ".coder-studio-skill.json"),
+      JSON.stringify({
+        version: 1,
+        managedBy: "coder-studio",
+        source: "custom",
+        slug: "coder-studio-open",
+      }),
+      "utf8"
+    );
+
+    expect(scanLocalSkillEntries([externalRoot])).toEqual([]);
+  });
+});
diff --git a/packages/server/src/__tests__/skills/mount-manager.test.ts b/packages/server/src/__tests__/skills/mount-manager.test.ts
new file mode 100644
index 000000000..4a7887e4f
--- /dev/null
+++ b/packages/server/src/__tests__/skills/mount-manager.test.ts
@@ -0,0 +1,301 @@
+import { lstat, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ProviderDefinition } from "@coder-studio/core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { CODER_STUDIO_SKILL_MARKER } from "../../skills/managed-skill-metadata.js";
+import { SkillLibraryRepo } from "../../storage/repositories/skill-library-repo.js";
+import { SkillMountRepo } from "../../storage/repositories/skill-mount-repo.js";
+
+function provider(id: string, skillDir?: string): ProviderDefinition {
+  return {
+    id,
+    displayName: id,
+    badge: id,
+    kind: "built_in",
+    supportsSkillsMount: true,
+    capability: "full",
+    capabilities: [],
+    install: {
+      prerequisites: [],
+      manualGuideKeys: [],
+      docUrls: { provider: "", prerequisites: {} },
+      strategies: {},
+    },
+    buildCommand: () => ({ argv: [id], env: {}, cwd: "/tmp" }),
+    configSchema: { parse: (value: unknown) => value } as never,
+    defaultConfig: {},
+    requiredCommands: [id],
+    skillMountDirectories: skillDir ? [skillDir] : undefined,
+  };
+}
+
+describe("SkillMountManager", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(async () => {
+    vi.restoreAllMocks();
+    await Promise.all(tempDirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  it("preserves the managed marker when symlink mount falls back to copy", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skill-mount-manager-"));
+    tempDirs.push(tempDir);
+    const libraryPath = join(tempDir, "state", "skills", "custom", "my-review-skill");
+    const skillDir = join(tempDir, ".agents", "skills");
+    await mkdir(libraryPath, { recursive: true });
+    await writeFile(join(libraryPath, "SKILL.md"), "# My Review Skill\n", "utf8");
+    await writeFile(
+      join(libraryPath, CODER_STUDIO_SKILL_MARKER),
+      JSON.stringify({
+        version: 1,
+        managedBy: "coder-studio",
+        source: "custom",
+        slug: "my-review-skill",
+      }),
+      "utf8"
+    );
+
+    const skillLibraryRepo = new SkillLibraryRepo({
+      filePath: join(tempDir, "library-index.json"),
+    });
+    const skillMountRepo = new SkillMountRepo({
+      filePath: join(tempDir, "mounts.json"),
+    });
+    skillLibraryRepo.set({
+      slug: "my-review-skill",
+      displayName: "My Review Skill",
+      version: "local",
+      source: "custom",
+      origin: "filesystem",
+      libraryPath,
+      installState: "installed",
+      installedAt: 1,
+      updatedAt: 1,
+    });
+
+    vi.resetModules();
+    vi.doMock("node:fs/promises", async (importOriginal) => {
+      const actual = await importOriginal<typeof import("node:fs/promises")>();
+      return {
+        ...actual,
+        symlink: vi.fn(async () => {
+          throw Object.assign(new Error("symlink not permitted"), { code: "EPERM" });
+        }),
+      };
+    });
+
+    const { SkillMountManager } = await import("../../skills/mount-manager.js");
+
+    const manager = new SkillMountManager({
+      getProviderRegistry: () => [provider("codex", skillDir)],
+      skillLibraryRepo,
+      skillMountRepo,
+    });
+
+    const relation = await manager.mount({
+      providerId: "codex",
+      skillSlug: "my-review-skill",
+      enabled: true,
+    });
+
+    expect(relation.mountModeResolved).toBe("copy");
+    await expect(
+      lstat(join(skillDir, "my-review-skill", CODER_STUDIO_SKILL_MARKER))
+    ).resolves.toBeTruthy();
+    expect(
+      JSON.parse(
+        await readFile(join(skillDir, "my-review-skill", CODER_STUDIO_SKILL_MARKER), "utf8")
+      )
+    ).toMatchObject({
+      managedBy: "coder-studio",
+      source: "custom",
+      slug: "my-review-skill",
+    });
+  });
+
+  it("can force copy mode and apply mounted overrides", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skill-mount-manager-"));
+    tempDirs.push(tempDir);
+    const libraryPath = join(tempDir, "state", "skills", "custom", "automation-skill");
+    const skillDir = join(tempDir, ".agents", "skills");
+    await mkdir(libraryPath, { recursive: true });
+    await writeFile(join(libraryPath, "SKILL.md"), "# Placeholder\noriginal\n", "utf8");
+    await writeFile(join(libraryPath, "notes.txt"), "library copy\n", "utf8");
+
+    const skillLibraryRepo = new SkillLibraryRepo({
+      filePath: join(tempDir, "library-index.json"),
+    });
+    const skillMountRepo = new SkillMountRepo({
+      filePath: join(tempDir, "mounts.json"),
+    });
+    skillLibraryRepo.set({
+      slug: "automation-skill",
+      displayName: "Automation Skill",
+      version: "local",
+      source: "custom",
+      origin: "filesystem",
+      libraryPath,
+      installState: "installed",
+      installedAt: 1,
+      updatedAt: 1,
+    });
+
+    const { SkillMountManager } = await import("../../skills/mount-manager.js");
+
+    const manager = new SkillMountManager({
+      getProviderRegistry: () => [provider("codex", skillDir)],
+      skillLibraryRepo,
+      skillMountRepo,
+    });
+
+    const relation = await manager.mount({
+      providerId: "codex",
+      skillSlug: "automation-skill",
+      enabled: true,
+      preferredMode: "copy",
+      mountedOverrides: [
+        {
+          relativePath: "SKILL.md",
+          content: "# Rewritten\nmounted\n",
+        },
+      ],
+    });
+
+    expect(relation.mountModeResolved).toBe("copy");
+    expect((await lstat(join(skillDir, "automation-skill"))).isSymbolicLink()).toBe(false);
+    await expect(readFile(join(skillDir, "automation-skill", "notes.txt"), "utf8")).resolves.toBe(
+      "library copy\n"
+    );
+    await expect(readFile(join(skillDir, "automation-skill", "SKILL.md"), "utf8")).resolves.toBe(
+      "# Rewritten\nmounted\n"
+    );
+  });
+
+  it("treats mounted overrides as copy-only behavior", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skill-mount-manager-"));
+    tempDirs.push(tempDir);
+    const libraryPath = join(tempDir, "state", "skills", "custom", "override-skill");
+    const skillDir = join(tempDir, ".agents", "skills");
+    await mkdir(libraryPath, { recursive: true });
+    await writeFile(join(libraryPath, "SKILL.md"), "# Source\noriginal\n", "utf8");
+
+    const skillLibraryRepo = new SkillLibraryRepo({
+      filePath: join(tempDir, "library-index.json"),
+    });
+    const skillMountRepo = new SkillMountRepo({
+      filePath: join(tempDir, "mounts.json"),
+    });
+    skillLibraryRepo.set({
+      slug: "override-skill",
+      displayName: "Override Skill",
+      version: "local",
+      source: "custom",
+      origin: "filesystem",
+      libraryPath,
+      installState: "installed",
+      installedAt: 1,
+      updatedAt: 1,
+    });
+
+    vi.resetModules();
+    const symlinkMock = vi.fn(async () => undefined);
+    vi.doMock("node:fs/promises", async (importOriginal) => {
+      const actual = await importOriginal<typeof import("node:fs/promises")>();
+      return {
+        ...actual,
+        symlink: symlinkMock,
+      };
+    });
+
+    const { SkillMountManager } = await import("../../skills/mount-manager.js");
+
+    const manager = new SkillMountManager({
+      getProviderRegistry: () => [provider("codex", skillDir)],
+      skillLibraryRepo,
+      skillMountRepo,
+    });
+
+    const relation = await manager.mount({
+      providerId: "codex",
+      skillSlug: "override-skill",
+      enabled: true,
+      mountedOverrides: [
+        {
+          relativePath: "SKILL.md",
+          content: "# Mounted\nrewritten\n",
+        },
+      ],
+    });
+
+    expect(relation.mountModeResolved).toBe("copy");
+    expect(symlinkMock).not.toHaveBeenCalled();
+    expect((await lstat(join(skillDir, "override-skill"))).isSymbolicLink()).toBe(false);
+    await expect(readFile(join(skillDir, "override-skill", "SKILL.md"), "utf8")).resolves.toBe(
+      "# Mounted\nrewritten\n"
+    );
+    await expect(readFile(join(libraryPath, "SKILL.md"), "utf8")).resolves.toBe(
+      "# Source\noriginal\n"
+    );
+  });
+
+  it("replaces copied symlinked override files before writing mounted overrides", async () => {
+    const tempDir = await mkdtemp(join(tmpdir(), "skill-mount-manager-"));
+    tempDirs.push(tempDir);
+    const libraryPath = join(tempDir, "state", "skills", "custom", "symlinked-override-skill");
+    const skillDir = join(tempDir, ".agents", "skills");
+    const sharedPath = join(tempDir, "shared-skill-template.md");
+    await mkdir(libraryPath, { recursive: true });
+    await writeFile(sharedPath, "# Shared\nsource\n", "utf8");
+    await symlink(sharedPath, join(libraryPath, "SKILL.md"));
+
+    const skillLibraryRepo = new SkillLibraryRepo({
+      filePath: join(tempDir, "library-index.json"),
+    });
+    const skillMountRepo = new SkillMountRepo({
+      filePath: join(tempDir, "mounts.json"),
+    });
+    skillLibraryRepo.set({
+      slug: "symlinked-override-skill",
+      displayName: "Symlinked Override Skill",
+      version: "local",
+      source: "custom",
+      origin: "filesystem",
+      libraryPath,
+      installState: "installed",
+      installedAt: 1,
+      updatedAt: 1,
+    });
+
+    vi.resetModules();
+    vi.doUnmock("node:fs/promises");
+    const { SkillMountManager } = await import("../../skills/mount-manager.js");
+
+    const manager = new SkillMountManager({
+      getProviderRegistry: () => [provider("codex", skillDir)],
+      skillLibraryRepo,
+      skillMountRepo,
+    });
+
+    const relation = await manager.mount({
+      providerId: "codex",
+      skillSlug: "symlinked-override-skill",
+      enabled: true,
+      mountedOverrides: [
+        {
+          relativePath: "SKILL.md",
+          content: "# Mounted\noverride\n",
+        },
+      ],
+    });
+
+    expect(relation.mountModeResolved).toBe("copy");
+    expect(
+      (await lstat(join(skillDir, "symlinked-override-skill", "SKILL.md"))).isSymbolicLink()
+    ).toBe(false);
+    await expect(
+      readFile(join(skillDir, "symlinked-override-skill", "SKILL.md"), "utf8")
+    ).resolves.toBe("# Mounted\noverride\n");
+    await expect(readFile(sharedPath, "utf8")).resolves.toBe("# Shared\nsource\n");
+  });
+});
diff --git a/packages/server/src/__tests__/storage/skill-library-repo.test.ts b/packages/server/src/__tests__/storage/skill-library-repo.test.ts
index 12f75732f..860625ec9 100644
--- a/packages/server/src/__tests__/storage/skill-library-repo.test.ts
+++ b/packages/server/src/__tests__/storage/skill-library-repo.test.ts
@@ -10,7 +10,13 @@ describe("SkillLibraryRepo", () => {
 
   beforeEach(async () => {
     tempDir = await mkdtemp(join(tmpdir(), "skill-library-repo-"));
-    repo = new SkillLibraryRepo({ filePath: join(tempDir, "library.json") });
+    repo = new SkillLibraryRepo({
+      filePath: join(tempDir, "library.json"),
+      builtinRoot: join(tempDir, "state", "skills", "builtin"),
+      managedLibraryRoot: join(tempDir, "state", "skills", "library"),
+      customSkillRoot: join(tempDir, "state", "skills", "custom"),
+      externalSkillRoots: [],
+    });
   });
 
   afterEach(async () => {
@@ -30,7 +36,13 @@ describe("SkillLibraryRepo", () => {
       updatedAt: 2,
     });
 
-    const reloaded = new SkillLibraryRepo({ filePath: join(tempDir, "library.json") });
+    const reloaded = new SkillLibraryRepo({
+      filePath: join(tempDir, "library.json"),
+      builtinRoot: join(tempDir, "state", "skills", "builtin"),
+      managedLibraryRoot: join(tempDir, "state", "skills", "library"),
+      customSkillRoot: join(tempDir, "state", "skills", "custom"),
+      externalSkillRoots: [],
+    });
     expect(reloaded.get("code-review")).toMatchObject({
       slug: "code-review",
       displayName: "Code Review",
@@ -59,14 +71,18 @@ describe("SkillLibraryRepo", () => {
 
     const scannedRepo = new SkillLibraryRepo({
       filePath: join(tempDir, "library.json"),
-      localSkillRoots: [skillsRoot],
+      builtinRoot: join(tempDir, "state", "skills", "builtin"),
+      managedLibraryRoot: join(tempDir, "state", "skills", "library"),
+      customSkillRoot: join(tempDir, "state", "skills", "custom"),
+      externalSkillRoots: [skillsRoot],
     });
 
     expect(scannedRepo.get("code-review")).toMatchObject({
       slug: "code-review",
       displayName: "Code Review",
       description: "Review code changes before merge",
-      source: "local",
+      source: "installed",
+      origin: "filesystem",
       version: "local",
       installState: "installed",
       libraryPath: localSkillDir,
@@ -76,53 +92,170 @@ describe("SkillLibraryRepo", () => {
       expect.objectContaining({
         slug: "code-review",
         displayName: "Code Review",
-        source: "local",
+        source: "installed",
       }),
     ]);
   });
 
-  it("does not let scanned local skills override persisted built-in entries", async () => {
-    const skillsRoot = join(tempDir, "agents-skills");
-    const localSkillDir = join(skillsRoot, "coder-studio-example-builtin");
-    await mkdir(localSkillDir, { recursive: true });
+  it("normalizes persisted entries inside the custom root to custom filesystem skills", async () => {
+    const customRoot = join(tempDir, "state", "skills", "custom");
+    const customSkillDir = join(customRoot, "code-review");
+    await mkdir(customSkillDir, { recursive: true });
     await writeFile(
-      join(localSkillDir, "SKILL.md"),
-      [
-        "---",
-        "name: coder-studio-example-builtin",
-        "description: Local shadow copy",
-        "---",
-        "",
-        "# Local Shadow Copy",
-        "",
-      ].join("\n"),
+      join(customSkillDir, "SKILL.md"),
+      ["---", "name: code-review", "description: Custom copy", "---", "", "# Custom", ""].join(
+        "\n"
+      ),
+      "utf8"
+    );
+
+    await writeFile(
+      join(tempDir, "library.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          "code-review": {
+            slug: "code-review",
+            displayName: "Code Review",
+            description: "Custom copy",
+            version: "1",
+            source: "local",
+            libraryPath: customSkillDir,
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 2,
+          },
+        },
+      }),
+      "utf8"
+    );
+
+    const reloaded = new SkillLibraryRepo({
+      filePath: join(tempDir, "library.json"),
+      builtinRoot: join(tempDir, "state", "skills", "builtin"),
+      managedLibraryRoot: join(tempDir, "state", "skills", "library"),
+      customSkillRoot: customRoot,
+      externalSkillRoots: [],
+    });
+
+    expect(reloaded.get("code-review")).toMatchObject({
+      source: "custom",
+      origin: "filesystem",
+      libraryPath: customSkillDir,
+    });
+  });
+
+  it("keeps managed installed entries ahead of matching external filesystem scans", async () => {
+    const externalRoot = join(tempDir, "external");
+    const skillDir = join(externalRoot, "code-review");
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(
+      join(skillDir, "SKILL.md"),
+      ["---", "name: code-review", "description: External copy", "---", "", "# External", ""].join(
+        "\n"
+      ),
       "utf8"
     );
 
     repo.set({
-      slug: "coder-studio-example-builtin",
-      displayName: "Coder Studio Example Builtin",
-      description: "Built-in test fixture",
-      version: "1.0.0",
-      source: "builtin",
-      libraryPath: join(tempDir, "state", "skills", "builtin", "coder-studio-example-builtin"),
+      slug: "code-review",
+      displayName: "Code Review",
+      description: "Managed copy",
+      version: "2.0.0",
+      source: "skillhub",
+      libraryPath: join(tempDir, "state", "skills", "library", "code-review"),
       installState: "installed",
       installedAt: 1,
       updatedAt: 2,
-      builtin: { defaultEnabled: true, autoMount: false },
     });
 
     const scannedRepo = new SkillLibraryRepo({
       filePath: join(tempDir, "library.json"),
-      localSkillRoots: [skillsRoot],
+      builtinRoot: join(tempDir, "state", "skills", "builtin"),
+      managedLibraryRoot: join(tempDir, "state", "skills", "library"),
+      customSkillRoot: join(tempDir, "state", "skills", "custom"),
+      externalSkillRoots: [externalRoot],
+    });
+
+    expect(scannedRepo.get("code-review")).toMatchObject({
+      source: "installed",
+      origin: "skillhub",
+      description: "Managed copy",
+    });
+  });
+
+  it("normalizes legacy local entries to installed filesystem when no custom root is configured", async () => {
+    const legacyRoot = join(tempDir, "legacy-skills");
+    const legacySkillDir = join(legacyRoot, "code-review");
+    await mkdir(legacySkillDir, { recursive: true });
+    await writeFile(
+      join(tempDir, "library.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          "code-review": {
+            slug: "code-review",
+            displayName: "Code Review",
+            description: "Legacy local copy",
+            version: "1",
+            source: "local",
+            libraryPath: legacySkillDir,
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 2,
+          },
+        },
+      }),
+      "utf8"
+    );
+
+    const repoWithoutCustomRoot = new SkillLibraryRepo({
+      filePath: join(tempDir, "library.json"),
+      localSkillRoots: [legacyRoot],
+    });
+
+    expect(repoWithoutCustomRoot.get("code-review")).toMatchObject({
+      source: "installed",
+      origin: "filesystem",
+      libraryPath: legacySkillDir,
+    });
+  });
+
+  it("treats sibling paths that merely share the custom prefix as installed filesystem skills", async () => {
+    const customRoot = join(tempDir, "state", "skills", "custom");
+    const siblingRoot = join(tempDir, "state", "skills", "custom-shadow");
+    const siblingSkillDir = join(siblingRoot, "code-review");
+    await mkdir(siblingSkillDir, { recursive: true });
+    await writeFile(
+      join(tempDir, "library.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          "code-review": {
+            slug: "code-review",
+            displayName: "Code Review",
+            description: "Sibling copy",
+            version: "1",
+            source: "local",
+            libraryPath: siblingSkillDir,
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 2,
+          },
+        },
+      }),
+      "utf8"
+    );
+
+    const repoWithCustomRoot = new SkillLibraryRepo({
+      filePath: join(tempDir, "library.json"),
+      customSkillRoot: customRoot,
     });
 
-    expect(scannedRepo.get("coder-studio-example-builtin")).toMatchObject({
-      slug: "coder-studio-example-builtin",
-      description: "Built-in test fixture",
-      source: "builtin",
-      libraryPath: join(tempDir, "state", "skills", "builtin", "coder-studio-example-builtin"),
-      builtin: { defaultEnabled: true, autoMount: false },
+    expect(repoWithCustomRoot.get("code-review")).toMatchObject({
+      source: "installed",
+      origin: "filesystem",
+      libraryPath: siblingSkillDir,
     });
   });
 });
diff --git a/packages/server/src/__tests__/terminal-commands.test.ts b/packages/server/src/__tests__/terminal-commands.test.ts
index 115add71c..e695fab0f 100644
--- a/packages/server/src/__tests__/terminal-commands.test.ts
+++ b/packages/server/src/__tests__/terminal-commands.test.ts
@@ -8,14 +8,27 @@ import {
 } from "@coder-studio/core";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { CommandContext } from "../ws/dispatch.js";
-import { dispatch } from "../ws/dispatch.js";
+import { dispatch, executeRuntimeCommand } from "../ws/dispatch.js";
 
 import "../commands/recovery.js";
 import "../commands/terminal.js";
 import { clearPendingTerminalInput, registerPendingTerminalInput } from "../commands/terminal.js";
 
-function createContext(overrides: Partial<CommandContext> = {}): CommandContext {
+function createSettingsRepoStub(settings: Record<string, unknown> = {}) {
   return {
+    get: vi.fn((key: string) => settings[key]),
+    getAll: vi.fn(() => ({ ...settings })),
+    set: vi.fn(),
+    delete: vi.fn(),
+    listKeys: vi.fn(() => Object.keys(settings)),
+  };
+}
+
+function createContext(overrides: Partial<CommandContext> = {}): CommandContext {
+  const sendCommand = vi.fn();
+  let runtimeCtxRef: CommandContext;
+
+  const ctx = {
     db: {} as never,
     workspaceMgr: {
       get: vi.fn().mockReturnValue({
@@ -60,11 +73,87 @@ function createContext(overrides: Partial<CommandContext> = {}): CommandContext
       sendToClient: vi.fn(),
       sendBinaryToClient: vi.fn(),
     } as never,
+    runtimeBindings: {
+      findWorkspaceIdByTerminalId: vi.fn(() => "ws-1"),
+      findSessionIdByTerminalId: vi.fn(() => "sess-1"),
+      findWorkspaceIdBySessionId: vi.fn(() => "ws-1"),
+      getRuntimeIdForWorkspace: vi.fn(() => "native-default"),
+    } as never,
+    runtimeRouter: {
+      executeOnTarget: vi.fn(async (target, op, args, meta) => {
+        sendCommand(op, args, meta?.clientId);
+        return executeRuntimeCommand(
+          op,
+          args,
+          {
+            runtimeId: "native-default",
+            workspaceLookup: {
+              get: (workspaceId: string) => runtimeCtxRef.workspaceMgr.get(workspaceId) as never,
+              list: () =>
+                typeof runtimeCtxRef.workspaceMgr.list === "function"
+                  ? (runtimeCtxRef.workspaceMgr.list() as never)
+                  : [],
+            },
+            hostBridge: {
+              issueSessionToken: () => ({ token: "" }),
+              revokeSessionTokensBySessionId: () => {},
+              getHostApiUrl: () => undefined,
+              emitDomainEvent: (event) => runtimeCtxRef.eventBus.emit(event),
+              broadcast: (topic, payload) => runtimeCtxRef.broadcaster.broadcast(topic, payload),
+              recordWorkspaceFetch: (workspaceId) =>
+                runtimeCtxRef.workspaceMgr.recordFetch?.(workspaceId),
+              sendToClient: (clientId, payload) =>
+                typeof runtimeCtxRef.broadcaster.sendToClient === "function"
+                  ? runtimeCtxRef.broadcaster.sendToClient(clientId as never, payload as never)
+                  : false,
+              sendBinaryToClient: (clientId, payload) =>
+                typeof runtimeCtxRef.broadcaster.sendBinaryToClient === "function"
+                  ? runtimeCtxRef.broadcaster.sendBinaryToClient(clientId as never, payload)
+                  : false,
+            },
+            eventBus: runtimeCtxRef.eventBus,
+            providerConfigRepo: runtimeCtxRef.providerConfigRepo,
+            providerRegistry: runtimeCtxRef.providerRegistry,
+            sessionMgr: runtimeCtxRef.sessionMgr,
+            terminalMgr: runtimeCtxRef.terminalMgr,
+            taskMgr: runtimeCtxRef.taskMgr as never,
+            lspMgr: runtimeCtxRef.lspMgr,
+            lspToolMgr: runtimeCtxRef.lspToolMgr,
+            lspToolInstallMgr: runtimeCtxRef.lspToolInstallMgr,
+            supervisorMgr: runtimeCtxRef.supervisorMgr,
+            providerRuntimeDeps: runtimeCtxRef.providerRuntimeDeps,
+            providerInstallMgr: runtimeCtxRef.providerInstallMgr,
+            systemDependencyInstallMgr: runtimeCtxRef.systemDependencyInstallMgr,
+            skillsHubClient: runtimeCtxRef.skillsHubClient,
+            skillInstallMgr: runtimeCtxRef.skillInstallMgr,
+            skillMountMgr: runtimeCtxRef.skillMountMgr,
+            skillHealthMgr: runtimeCtxRef.skillHealthMgr,
+            skillLibraryRepo: runtimeCtxRef.skillLibraryRepo,
+            skillTargetRepo: runtimeCtxRef.skillTargetRepo,
+            skillMountRepo: runtimeCtxRef.skillMountRepo,
+            builtinSkillSyncMgr: runtimeCtxRef.builtinSkillSyncMgr,
+            sessionMetadataRepo: runtimeCtxRef.sessionMetadataRepo,
+            sessionAnalysisService: runtimeCtxRef.sessionAnalysisService,
+            workAnalysisService: runtimeCtxRef.workAnalysisService,
+            agentInstructionPublisher: runtimeCtxRef.agentInstructionPublisher,
+          } as never,
+          meta
+        );
+      }),
+    } as never,
     fencingMgr: {} as never,
     supervisorMgr: {} as never,
     providerRegistry: [],
+    activationMgr: { getLease: vi.fn(() => ({ wsClientId: "client-1" })) } as never,
+    autoFetch: {} as never,
+    settingsRepo: createSettingsRepoStub() as never,
+    providerConfigRepo: {} as never,
+    lspMgr: {} as never,
+    __sendCommand: sendCommand,
     ...overrides,
   };
+  runtimeCtxRef = ctx as CommandContext;
+  return runtimeCtxRef;
 }
 
 describe("terminal commands", () => {
@@ -157,6 +246,9 @@ describe("terminal commands", () => {
       text: "ready\n",
     });
     expect(ctx.terminalMgr.getRingBufferTail).toHaveBeenCalledWith("term-1", 4096);
+    expect(
+      (ctx as CommandContext & { __sendCommand: ReturnType<typeof vi.fn> }).__sendCommand
+    ).toHaveBeenCalledWith("terminal.read", { terminalId: "term-1" }, undefined);
   });
 
   it("returns binary metadata and sends replay payload to requesting client", async () => {
@@ -310,6 +402,94 @@ describe("terminal commands", () => {
     }
   });
 
+  it("returns configured and resolved defaults from terminal.profiles.list", async () => {
+    vi.stubEnv("SHELL", "/bin/zsh");
+    const ctx = createContext({
+      settingsRepo: createSettingsRepoStub({
+        "terminal.defaultProfileId": "custom:ops",
+        "terminal.profiles": [
+          {
+            id: "custom:ops",
+            label: "Ops Shell",
+            command: "/usr/bin/env",
+            args: ["bash"],
+            icon: "rocket",
+          },
+        ],
+      }) as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "terminal-profiles-list-1",
+        op: "terminal.profiles.list",
+        args: {},
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.data).toMatchObject({
+      configuredDefaultProfileId: "custom:ops",
+      resolvedDefaultProfileId: "custom:ops",
+    });
+    expect(result.data).toMatchObject({
+      profiles: expect.arrayContaining([
+        expect.objectContaining({
+          id: "custom:ops",
+          label: "Ops Shell",
+          source: "custom",
+          runtime: "native",
+          icon: "rocket",
+        }),
+      ]),
+    });
+  });
+
+  it("accepts omitted args for terminal.profiles.list and trims persisted custom profiles", async () => {
+    vi.stubEnv("SHELL", "/bin/zsh");
+    const ctx = createContext({
+      settingsRepo: createSettingsRepoStub({
+        "terminal.defaultProfileId": "custom:ops",
+        "terminal.profiles": [
+          {
+            id: "custom:ops",
+            label: "  Ops Shell  ",
+            command: "  /usr/bin/env  ",
+            args: ["bash"],
+            icon: "rocket",
+          },
+        ],
+      }) as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "terminal-profiles-list-no-args-1",
+        op: "terminal.profiles.list",
+        args: undefined,
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.data).toMatchObject({
+      configuredDefaultProfileId: "custom:ops",
+      resolvedDefaultProfileId: "custom:ops",
+      profiles: expect.arrayContaining([
+        expect.objectContaining({
+          id: "custom:ops",
+          label: "Ops Shell",
+          source: "custom",
+          runtime: "native",
+          icon: "rocket",
+        }),
+      ]),
+    });
+  });
+
   it("uses the current user shell when creating shell terminals", async () => {
     vi.stubEnv("SHELL", "/bin/zsh");
     const ctx = createContext();
@@ -333,6 +513,120 @@ describe("terminal commands", () => {
         title: "zsh",
       })
     );
+    expect(
+      (ctx as CommandContext & { __sendCommand: ReturnType<typeof vi.fn> }).__sendCommand
+    ).toHaveBeenCalledWith(
+      "terminal.spawn",
+      expect.objectContaining({
+        workspaceId: "ws-1",
+        argv: ["/bin/zsh", "-i"],
+        title: "zsh",
+      }),
+      undefined
+    );
+  });
+
+  it("passes the requested terminal profile through terminal.create", async () => {
+    const ctx = createContext({
+      settingsRepo: createSettingsRepoStub({
+        "terminal.profiles": [
+          {
+            id: "custom:tooling",
+            label: "Tooling",
+            command: "npm",
+            args: ["run", "dev"],
+          },
+        ],
+      }) as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "terminal-create-profile-1",
+        op: "terminal.create",
+        args: {
+          workspaceId: "ws-1",
+          profileId: "custom:tooling",
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(true);
+    expect(ctx.terminalMgr.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        workspaceId: "ws-1",
+        kind: "shell",
+        argv: ["npm", "run", "dev"],
+        title: "Tooling",
+        cwd: "/tmp/workspace",
+      })
+    );
+    expect(
+      (ctx as CommandContext & { __sendCommand: ReturnType<typeof vi.fn> }).__sendCommand
+    ).toHaveBeenCalledWith(
+      "terminal.spawn",
+      expect.objectContaining({
+        workspaceId: "ws-1",
+        argv: ["npm", "run", "dev"],
+        title: "Tooling",
+      }),
+      undefined
+    );
+  });
+
+  it("returns terminal_profile_unavailable for an explicit missing profile", async () => {
+    vi.stubEnv("SHELL", "/bin/zsh");
+    const ctx = createContext();
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "terminal-create-profile-missing-1",
+        op: "terminal.create",
+        args: {
+          workspaceId: "ws-1",
+          profileId: "custom:missing",
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatchObject({
+      code: "terminal_profile_unavailable",
+      message: "Terminal profile unavailable: custom:missing",
+    });
+    expect(ctx.terminalMgr.create).not.toHaveBeenCalled();
+  });
+
+  it("returns unknown_op when terminal.spawn is dispatched directly", async () => {
+    const ctx = createContext();
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "terminal-spawn-direct-dispatch-1",
+        op: "terminal.spawn",
+        args: {
+          workspaceId: "ws-1",
+          argv: ["/bin/zsh", "-i"],
+          title: "zsh",
+          cwd: "/tmp/workspace",
+          cols: 120,
+          rows: 30,
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatchObject({
+      code: "unknown_op",
+      message: "Unknown operation: terminal.spawn",
+    });
+    expect(ctx.terminalMgr.create).not.toHaveBeenCalled();
   });
 
   it("returns terminal_spawn_failed when shell terminal creation throws a terminal spawn error", async () => {
diff --git a/packages/server/src/__tests__/ui-actions-commands.test.ts b/packages/server/src/__tests__/ui-actions-commands.test.ts
index 874013c61..cfa2942fd 100644
--- a/packages/server/src/__tests__/ui-actions-commands.test.ts
+++ b/packages/server/src/__tests__/ui-actions-commands.test.ts
@@ -175,6 +175,266 @@ describe("ui action commands", () => {
     expect(result.data).toMatchObject({ topic: Topics.workspaceUiAction("ws-fallback") });
   });
 
+  it("hydrates and broadcasts canvas.open intents from a source path without caller metadata", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(4234);
+    const ctx = createContext({
+      workspaceMgr: {
+        get: vi.fn((workspaceId: string) =>
+          workspaceId === "ws-1" ? { id: "ws-1", path: "/workspace" } : undefined
+        ),
+      } as never,
+      canvasService: {
+        getCanvasData: vi.fn(async () => ({
+          canvasId: "canvas-1",
+          workspaceId: "ws-1",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+          title: "Runtime Flow",
+          kind: "architecture_canvas",
+          renderStatus: "ready",
+          lastError: null,
+          compiledDocument: {
+            kind: "architecture_canvas",
+            title: "Runtime Flow",
+            summary: "How requests move.",
+            sections: [],
+          },
+        })),
+      } as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "ui-dispatch-open-canvas-1",
+        op: "uiAction.dispatch",
+        args: {
+          workspaceId: "ws-1",
+          intent: {
+            type: "canvas.open",
+            sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+          },
+          requestId: "req-open-canvas-1",
+          source: { kind: "agent", sessionId: "sess-1", providerId: "codex" },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual({
+      accepted: true,
+      requestId: "req-open-canvas-1",
+      topic: Topics.workspaceUiAction("ws-1"),
+    });
+    expect(ctx.broadcaster.broadcast).toHaveBeenCalledWith(Topics.workspaceUiAction("ws-1"), {
+      requestId: "req-open-canvas-1",
+      workspaceId: "ws-1",
+      intent: {
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      },
+      source: { kind: "agent", sessionId: "sess-1", providerId: "codex" },
+      dispatchedAt: 4234,
+    });
+
+    vi.useRealTimers();
+  });
+
+  it("resolves canvas.open metadata from canvasId compatibility input before broadcasting", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(4734);
+    const ctx = createContext({
+      workspaceMgr: {
+        get: vi.fn((workspaceId: string) =>
+          workspaceId === "ws-1" ? { id: "ws-1", path: "/workspace" } : undefined
+        ),
+      } as never,
+      canvasService: {
+        getRecord: vi.fn((workspaceId: string, canvasId: string) =>
+          workspaceId === "ws-1" && canvasId === "canvas_123"
+            ? {
+                id: "canvas_123",
+                workspaceId: "ws-1",
+                title: "Runtime Flow",
+                artifactType: "architecture_canvas",
+                sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+              }
+            : undefined
+        ),
+        getCanvasData: vi.fn(async () => ({
+          canvasId: "canvas_123",
+          workspaceId: "ws-1",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+          title: "Runtime Flow",
+          kind: "architecture_canvas",
+          renderStatus: "ready",
+          lastError: null,
+          compiledDocument: {
+            kind: "architecture_canvas",
+            title: "Runtime Flow",
+            summary: "How requests move.",
+            sections: [],
+          },
+        })),
+      } as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "ui-dispatch-open-canvas-compat-1",
+        op: "uiAction.dispatch",
+        args: {
+          workspaceId: "ws-1",
+          intent: { type: "canvas.open", canvasId: "canvas_123" },
+          requestId: "req-open-canvas-compat-1",
+          source: { kind: "agent", sessionId: "sess-1", providerId: "codex" },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual({
+      accepted: true,
+      requestId: "req-open-canvas-compat-1",
+      topic: Topics.workspaceUiAction("ws-1"),
+    });
+    expect(ctx.broadcaster.broadcast).toHaveBeenCalledWith(Topics.workspaceUiAction("ws-1"), {
+      requestId: "req-open-canvas-compat-1",
+      workspaceId: "ws-1",
+      intent: {
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: "canvas_123",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      },
+      source: { kind: "agent", sessionId: "sess-1", providerId: "codex" },
+      dispatchedAt: 4734,
+    });
+
+    vi.useRealTimers();
+  });
+
+  it("prefers canonical canvas metadata over client-supplied canvas.open metadata", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(5234);
+    const ctx = createContext({
+      workspaceMgr: {
+        get: vi.fn((workspaceId: string) =>
+          workspaceId === "ws-1" ? { id: "ws-1", path: "/workspace" } : undefined
+        ),
+      } as never,
+      canvasService: {
+        getRecord: vi.fn((workspaceId: string, canvasId: string) =>
+          workspaceId === "ws-1" && canvasId === "canvas-1"
+            ? {
+                id: "canvas-1",
+                workspaceId: "ws-1",
+                title: "Runtime Flow",
+                artifactType: "architecture_canvas",
+                sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+              }
+            : undefined
+        ),
+        getCanvasData: vi.fn(async () => ({
+          canvasId: "canvas-1",
+          workspaceId: "ws-1",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+          title: "Runtime Flow",
+          kind: "architecture_canvas",
+          renderStatus: "ready",
+          lastError: null,
+          compiledDocument: {
+            kind: "architecture_canvas",
+            title: "Runtime Flow",
+            summary: "How requests move.",
+            sections: [],
+          },
+        })),
+      } as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "ui-dispatch-open-canvas-2",
+        op: "uiAction.dispatch",
+        args: {
+          workspaceId: "ws-1",
+          intent: {
+            type: "canvas.open",
+            canvasId: "canvas-1",
+            title: "Wrong Title",
+            artifactType: "report_canvas",
+            sourcePath: "docs/wrong.csc",
+          },
+          requestId: "req-open-canvas-2",
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(true);
+    expect(ctx.broadcaster.broadcast).toHaveBeenCalledWith(Topics.workspaceUiAction("ws-1"), {
+      requestId: "req-open-canvas-2",
+      workspaceId: "ws-1",
+      intent: {
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      },
+      source: undefined,
+      dispatchedAt: 5234,
+    });
+
+    vi.useRealTimers();
+  });
+
+  it("rejects canvas.open when the canvas metadata cannot be resolved", async () => {
+    const ctx = createContext({
+      workspaceMgr: {
+        get: vi.fn((workspaceId: string) =>
+          workspaceId === "ws-1" ? { id: "ws-1", path: "/workspace" } : undefined
+        ),
+      } as never,
+      canvasService: {
+        getRecord: vi.fn(() => undefined),
+        getCanvasData: vi.fn(async () => {
+          throw { code: "canvas_not_found", message: "Canvas not found: missing-canvas" };
+        }),
+      } as never,
+    });
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "ui-dispatch-open-canvas-missing-1",
+        op: "uiAction.dispatch",
+        args: {
+          workspaceId: "ws-1",
+          intent: { type: "canvas.open", canvasId: "missing-canvas" },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatchObject({
+      code: "canvas_not_found",
+    });
+    expect(ctx.broadcaster.broadcast).not.toHaveBeenCalled();
+  });
   it("rejects unsafe UI action intents before broadcasting", async () => {
     const ctx = createContext();
 
diff --git a/packages/server/src/__tests__/workspace-commands.test.ts b/packages/server/src/__tests__/workspace-commands.test.ts
index 95b66147b..171059ab8 100644
--- a/packages/server/src/__tests__/workspace-commands.test.ts
+++ b/packages/server/src/__tests__/workspace-commands.test.ts
@@ -271,6 +271,67 @@ describe("Workspace Commands", () => {
         },
       ]);
     });
+
+    it("removes a recent workspace by path and returns the updated list", async () => {
+      settingsRepo.set(WORKSPACE_HISTORY_KEY, [
+        {
+          path: "/repo/alpha",
+          name: "alpha",
+          lastOpenedAt: 3,
+        },
+        {
+          path: "/repo/beta",
+          name: "beta",
+          lastOpenedAt: 2,
+        },
+      ]);
+
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "workspace-history-remove-entry",
+          op: "workspace.history.remove",
+          args: {
+            path: "/repo/alpha",
+          },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual([
+        {
+          path: "/repo/beta",
+          name: "beta",
+          lastOpenedAt: 2,
+        },
+      ]);
+      expect(settingsRepo.get(WORKSPACE_HISTORY_KEY)).toEqual(result.data);
+    });
+
+    it("clears the recent workspace list and removes the stored key", async () => {
+      settingsRepo.set(WORKSPACE_HISTORY_KEY, [
+        {
+          path: "/repo/alpha",
+          name: "alpha",
+          lastOpenedAt: 3,
+        },
+      ]);
+
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "workspace-history-clear",
+          op: "workspace.history.clear",
+          args: {},
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.data).toEqual([]);
+      expect(settingsRepo.get(WORKSPACE_HISTORY_KEY)).toBeUndefined();
+    });
   });
 
   describe("workspace.open", () => {
@@ -290,6 +351,24 @@ describe("Workspace Commands", () => {
       expect(result.ok).toBe(false);
     });
 
+    it("workspace.open still records a native workspace through the command layer", async () => {
+      const workspaceDir = join(tmpdir(), `workspace-open-native-${Date.now()}`);
+      await mkdir(workspaceDir, { recursive: true });
+
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "workspace-open-native",
+          op: "workspace.open",
+          args: { path: workspaceDir },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      expect(result.data).toMatchObject({ targetRuntime: "native" });
+    });
+
     it("triggers open-time auto fetch after workspace.open succeeds", async () => {
       const dir = join(tmpdir(), `workspace-open-test-${Date.now()}`);
       await mkdir(dir);
@@ -535,7 +614,7 @@ describe("Workspace Commands", () => {
       );
 
       expect(result.ok).toBe(false);
-      expect(result.error?.code).toBe("internal_error");
+      expect(result.error?.code).toBe("workspace_not_found");
     });
   });
 
@@ -597,6 +676,53 @@ describe("Workspace Commands", () => {
       });
     });
 
+    it("preserves preview file tab metadata in workspace ui state", async () => {
+      const dir = join(tmpdir(), `workspace-command-preview-tab-test-${Date.now()}`);
+      await mkdir(dir);
+
+      const openResult = await dispatch(
+        {
+          kind: "command",
+          id: "open-workspace-preview-tab",
+          op: "workspace.open",
+          args: {
+            path: dir,
+          },
+        },
+        ctx
+      );
+
+      expect(openResult.ok).toBe(true);
+
+      const workspaceId = (openResult.data as { id: string }).id;
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "set-ui-state-preview-tab",
+          op: "workspace.uiState.set",
+          args: {
+            workspaceId,
+            uiState: {
+              leftPanelWidth: 320,
+              bottomPanelHeight: 210,
+              focusMode: false,
+              openEditorTabs: [{ kind: "file", path: "src/preview.ts", pinned: false }],
+              activeEditorTab: { kind: "file", path: "src/preview.ts", pinned: false },
+            },
+          },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      expect(
+        (result.data as { uiState: { openEditorTabs: unknown } }).uiState.openEditorTabs
+      ).toEqual([{ kind: "file", path: "src/preview.ts", pinned: false }]);
+      expect(
+        (result.data as { uiState: { activeEditorTab: unknown } }).uiState.activeEditorTab
+      ).toEqual({ kind: "file", path: "src/preview.ts", pinned: false });
+    });
+
     it("persists typed pane leaves with draft and editor kinds", async () => {
       const dir = join(tmpdir(), `workspace-command-typed-pane-test-${Date.now()}`);
       await mkdir(dir);
@@ -832,6 +958,47 @@ describe("Workspace Commands", () => {
       ).toBe("src/app.tsx");
     });
 
+    it("persists editor pinned state into workspace ui state", async () => {
+      const dir = join(tmpdir(), `workspace-editor-pinned-test-${Date.now()}`);
+      await mkdir(dir);
+
+      const openResult = await dispatch(
+        {
+          kind: "command",
+          id: "open-workspace-editor-pinned",
+          op: "workspace.open",
+          args: { path: dir },
+        },
+        ctx
+      );
+
+      expect(openResult.ok).toBe(true);
+      const workspaceId = (openResult.data as { id: string }).id;
+
+      const result = await dispatch(
+        {
+          kind: "command",
+          id: "set-ui-state-editor-pinned",
+          op: "workspace.uiState.set",
+          args: {
+            workspaceId,
+            uiState: {
+              leftPanelWidth: 320,
+              bottomPanelHeight: 210,
+              focusMode: false,
+              editorPinned: false,
+            },
+          },
+        },
+        ctx
+      );
+
+      expect(result.ok).toBe(true);
+      expect((result.data as { uiState: { editorPinned?: boolean } }).uiState.editorPinned).toBe(
+        false
+      );
+    });
+
     it("persists multiple browser editor tabs with duplicate urls", async () => {
       const dir = join(tmpdir(), `workspace-browser-editors-test-${Date.now()}`);
       await mkdir(dir);
diff --git a/packages/server/src/__tests__/workspace-runtime-binding.test.ts b/packages/server/src/__tests__/workspace-runtime-binding.test.ts
new file mode 100644
index 000000000..672b950ab
--- /dev/null
+++ b/packages/server/src/__tests__/workspace-runtime-binding.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { WorkspaceRuntimeBindingStore } from "../host/workspace-runtime-binding.js";
+
+describe("WorkspaceRuntimeBindingStore", () => {
+  it("tracks workspace, session, and terminal bindings together", () => {
+    const store = new WorkspaceRuntimeBindingStore();
+    store.bindWorkspace("ws-1", "native-default");
+    store.bindSession({
+      id: "sess-1",
+      workspaceId: "ws-1",
+      terminalId: "term-1",
+      providerId: "codex",
+      state: "running",
+      capability: "full",
+      startedAt: 1,
+      lastActiveAt: 1,
+    });
+    store.bindTerminal({
+      id: "term-1",
+      workspaceId: "ws-1",
+      kind: "agent",
+      title: "Claude",
+      cwd: "/repo",
+      argv: [],
+      cols: 120,
+      rows: 30,
+      alive: true,
+      createdAt: 1,
+    });
+
+    expect(store.getRuntimeIdForWorkspace("ws-1")).toBe("native-default");
+    expect(store.findWorkspaceIdBySessionId("sess-1")).toBe("ws-1");
+    expect(store.findWorkspaceIdByTerminalId("term-1")).toBe("ws-1");
+    expect(store.findSessionIdByTerminalId("term-1")).toBe("sess-1");
+    expect(store.listSessionsForWorkspace("ws-1")).toHaveLength(1);
+    expect(store.listTerminalsForWorkspace("ws-1")).toHaveLength(1);
+  });
+});
diff --git a/packages/server/src/__tests__/workspace-watcher-hydrate-restart.test.ts b/packages/server/src/__tests__/workspace-watcher-hydrate-restart.test.ts
index 0de9316fb..645a78e0d 100644
--- a/packages/server/src/__tests__/workspace-watcher-hydrate-restart.test.ts
+++ b/packages/server/src/__tests__/workspace-watcher-hydrate-restart.test.ts
@@ -148,12 +148,14 @@ describe("workspace watcher hydrate restart", () => {
     );
 
     expect(openResult.ok).toBe(true);
-    expect(await readFile(join(workspaceDir, "AGENTS.md"), "utf8")).toContain(
-      "# Agent Instructions"
-    );
-    expect(await readFile(join(workspaceDir, ".claude", "CLAUDE.md"), "utf8")).toContain(
-      "# Agent Instructions"
-    );
+    await vi.waitFor(async () => {
+      expect(await readFile(join(workspaceDir, "AGENTS.md"), "utf8")).toContain(
+        "# Agent Instructions"
+      );
+      expect(await readFile(join(workspaceDir, ".claude", "CLAUDE.md"), "utf8")).toContain(
+        "# Agent Instructions"
+      );
+    });
 
     await server.stop();
     server = undefined;
@@ -168,11 +170,13 @@ describe("workspace watcher hydrate restart", () => {
       port: 0,
     });
 
-    expect(await readFile(join(workspaceDir, "AGENTS.md"), "utf8")).toContain(
-      "# Agent Instructions"
-    );
-    expect(await readFile(join(workspaceDir, ".claude", "CLAUDE.md"), "utf8")).toContain(
-      "# Agent Instructions"
-    );
+    await vi.waitFor(async () => {
+      expect(await readFile(join(workspaceDir, "AGENTS.md"), "utf8")).toContain(
+        "# Agent Instructions"
+      );
+      expect(await readFile(join(workspaceDir, ".claude", "CLAUDE.md"), "utf8")).toContain(
+        "# Agent Instructions"
+      );
+    });
   });
 });
diff --git a/packages/server/src/__tests__/workspace/manager.test.ts b/packages/server/src/__tests__/workspace/manager.test.ts
index 48cd5a38f..5b29072d8 100644
--- a/packages/server/src/__tests__/workspace/manager.test.ts
+++ b/packages/server/src/__tests__/workspace/manager.test.ts
@@ -69,6 +69,17 @@ describe("WorkspaceManager", () => {
       expect(workspace.uiState).toBeDefined();
     });
 
+    it("persists explicit targetRuntime and wslDistro on new workspaces", async () => {
+      const workspace = await manager.open({
+        path: testDir,
+        targetRuntime: "wsl",
+        wslDistro: "Ubuntu-24.04",
+      });
+
+      expect(workspace.targetRuntime).toBe("wsl");
+      expect(workspace.wslDistro).toBe("Ubuntu-24.04");
+    });
+
     it("triggers open-time auto fetch for new workspaces", async () => {
       const autoFetch = {
         triggerOpenTimeFetch: vi.fn(),
diff --git a/packages/server/src/app-routing.test.ts b/packages/server/src/app-routing.test.ts
index 699c64419..abc814143 100644
--- a/packages/server/src/app-routing.test.ts
+++ b/packages/server/src/app-routing.test.ts
@@ -7,6 +7,7 @@ import { buildFastifyApp } from "./app.js";
 import { EventBus } from "./bus/event-bus.js";
 import { AuthLoginBlockRepo } from "./storage/repositories/auth-login-block-repo.js";
 import { AuthSessionRepo } from "./storage/repositories/auth-session-repo.js";
+import { SkillLibraryRepo } from "./storage/repositories/skill-library-repo.js";
 import { WorkspaceRepo } from "./storage/repositories/workspace-repo.js";
 import { WorkspaceManager } from "./workspace/manager.js";
 import { FencingManager } from "./ws/fencing.js";
@@ -79,12 +80,35 @@ describe("app routing", () => {
         broadcaster: wsHub,
       }),
       config,
+      skillLibraryRepo: new SkillLibraryRepo({
+        filePath: join(tempDir, "state", "skills", "library-index.json"),
+        builtinRoot: join(tempDir, "state", "skills", "builtin"),
+        managedLibraryRoot: join(tempDir, "state", "skills", "library"),
+        customSkillRoot: join(tempDir, "state", "skills", "custom"),
+        externalSkillRoots: [],
+      }),
       authSessionRepo: new AuthSessionRepo({
         filePath: join(tempDir, "state", "auth-sessions.json"),
       }),
       authLoginBlockRepo: new AuthLoginBlockRepo({
         filePath: join(tempDir, "state", "auth-login-blocks.json"),
       }),
+      canvasService: {
+        getCanvasData: async () => ({
+          canvasId: "canvas-1",
+          workspaceId: "ws-1",
+          title: "Runtime Flow",
+          kind: "architecture_canvas",
+          renderStatus: "ready",
+          lastError: null,
+          compiledDocument: {
+            kind: "architecture_canvas",
+            title: "Runtime Flow",
+            summary: "How requests move.",
+            sections: [],
+          },
+        }),
+      } as never,
       logger: false,
     });
 
@@ -241,7 +265,25 @@ describe("app routing", () => {
     expect(response.body).not.toContain("<!doctype html>");
   });
 
-  it("registers dev browser session API routes", async () => {
+  it("does not fall back to index.html for canvas api routes", async () => {
+    const instance = await createApp();
+
+    const response = await instance.inject({
+      method: "GET",
+      url: "/api/canvas/ws-1/data?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc",
+      headers: {
+        accept: "text/html",
+      },
+    });
+
+    expect(response.statusCode).toBe(404);
+    expect(response.headers["content-type"]).toContain("application/json");
+    expect(response.json()).toMatchObject({
+      error: "workspace_not_found",
+    });
+  });
+
+  it("does not register the removed dev browser session API routes", async () => {
     const instance = await createApp();
 
     const response = await instance.inject({
@@ -250,8 +292,8 @@ describe("app routing", () => {
       payload: { url: "http://example.com:8000" },
     });
 
-    expect(response.statusCode).toBe(400);
-    expect(response.json()).toMatchObject({ error: "invalid_dev_browser_target" });
+    expect(response.statusCode).toBe(404);
+    expect(response.body).not.toContain("<!doctype html>");
   });
 
   it("does not serve index.html for dev browser proxy paths", async () => {
@@ -269,74 +311,74 @@ describe("app routing", () => {
     expect(response.body).not.toContain("<!doctype html>");
   });
 
-  it("treats root static files as public even when auth is enabled", async () => {
-    const instance = await createApp(true);
+  it("does not serve index.html for old dev browser HTML navigation paths", async () => {
+    const instance = await createApp();
 
     const response = await instance.inject({
       method: "GET",
-      url: "/task-complete.wav",
+      url: "/dev-browser/session/missing/proxy/app",
+      headers: {
+        accept: "text/html",
+      },
     });
 
-    expect(response.statusCode).toBe(200);
-    expect(response.body).toBe("fake-wave");
+    expect(response.statusCode).toBe(404);
+    expect(response.body).not.toContain("<!doctype html>");
   });
 
-  it("serves the dev browser service worker when a web root is configured", async () => {
-    const instance = await createApp();
+  it("treats root static files as public even when auth is enabled", async () => {
+    const instance = await createApp(true);
 
     const response = await instance.inject({
       method: "GET",
-      url: "/dev-browser-sw.js",
+      url: "/task-complete.wav",
     });
 
     expect(response.statusCode).toBe(200);
-    expect(response.headers["content-type"]).toContain("javascript");
-    expect(response.body).toContain("coder-studio-dev-browser-session");
+    expect(response.body).toBe("fake-wave");
   });
 
-  it("does not double-register dev-browser-sw.js when it exists in the web root", async () => {
-    writeFileSync(join(webRoot, "dev-browser-sw.js"), 'const MARKER = "bundled-dev-browser-sw";\n');
-
+  it("does not serve the removed dev browser service worker", async () => {
     const instance = await createApp();
 
-    const getResponse = await instance.inject({
+    const response = await instance.inject({
       method: "GET",
       url: "/dev-browser-sw.js",
     });
-    expect(getResponse.statusCode).toBe(200);
-    expect(getResponse.headers["cache-control"]).toBe("no-cache, no-store, must-revalidate");
-    expect(getResponse.body).toContain("bundled-dev-browser-sw");
 
-    const headResponse = await instance.inject({
-      method: "HEAD",
-      url: "/dev-browser-sw.js",
-    });
-    expect(headResponse.statusCode).toBe(200);
+    expect(response.statusCode).toBe(404);
+    expect(response.body).not.toContain("<!doctype html>");
   });
 
-  it("serves the dev browser service worker without a configured web root", async () => {
-    const instance = await createApp(false, {}, { webRoot: null });
+  it("does not serve a stale dev browser service worker from the web root", async () => {
+    writeFileSync(join(webRoot, "dev-browser-sw.js"), "self.skipWaiting();\n");
+    const instance = await createApp();
 
     const response = await instance.inject({
       method: "GET",
       url: "/dev-browser-sw.js",
     });
 
-    expect(response.statusCode).toBe(200);
-    expect(response.headers["content-type"]).toContain("javascript");
-    expect(response.body).toContain("coder-studio-dev-browser-session");
+    expect(response.statusCode).toBe(404);
+    expect(response.body).not.toContain("skipWaiting");
   });
 
-  it("treats the dev browser service worker as public when auth is enabled", async () => {
-    const instance = await createApp(true, {}, { webRoot: null });
+  it("serves ordinary root static files from the web root", async () => {
+    writeFileSync(join(webRoot, "robots.txt"), "User-agent: *\n");
 
-    const response = await instance.inject({
+    const instance = await createApp();
+
+    const getResponse = await instance.inject({
       method: "GET",
-      url: "/dev-browser-sw.js",
+      url: "/robots.txt",
     });
+    expect(getResponse.statusCode).toBe(200);
+    expect(getResponse.body).toContain("User-agent: *");
 
-    expect(response.statusCode).toBe(200);
-    expect(response.headers["content-type"]).toContain("javascript");
-    expect(response.body).toContain("coder-studio-dev-browser-session");
+    const headResponse = await instance.inject({
+      method: "HEAD",
+      url: "/robots.txt",
+    });
+    expect(headResponse.statusCode).toBe(200);
   });
 });
diff --git a/packages/server/src/app.ts b/packages/server/src/app.ts
index 8fc0c66df..1f458be6e 100644
--- a/packages/server/src/app.ts
+++ b/packages/server/src/app.ts
@@ -4,9 +4,7 @@
  * Builds the Fastify application with all routes and middleware
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join, resolve } from "node:path";
 import { IN_MEMORY_STATE_DIR } from "@coder-studio/core/state-paths";
 import compress from "@fastify/compress";
 import cors from "@fastify/cors";
@@ -21,12 +19,15 @@ import {
   registerAuthRoutes,
   registerAuthStatusRoute,
 } from "./auth/index.js";
+import type { SessionTokenRepo } from "./auth/session-token-repo.js";
+import type { CanvasService } from "./canvas/service.js";
 import type { ServerConfig } from "./config.js";
 import { PreviewSessionStore } from "./preview/session-store.js";
 import { registerAppearanceAssetsRoutes } from "./routes/appearance-assets.js";
-import { registerDevBrowserRoutes } from "./routes/dev-browser.js";
+import { registerCanvasRoutes } from "./routes/canvas.js";
 import { registerFileAssetRoutes } from "./routes/file-asset.js";
 import { registerPreviewRoutes } from "./routes/preview.js";
+import { registerSkillFileAssetRoutes } from "./routes/skill-file-asset.js";
 import { registerUploadsRoute } from "./routes/uploads.js";
 import {
   AppearanceAssetRepo,
@@ -34,6 +35,7 @@ import {
 } from "./storage/repositories/appearance-asset-repo.js";
 import type { AuthLoginBlockRepo } from "./storage/repositories/auth-login-block-repo.js";
 import type { AuthSessionRepo } from "./storage/repositories/auth-session-repo.js";
+import type { SkillLibraryRepo } from "./storage/repositories/skill-library-repo.js";
 import { MAX_FILE_BYTES, MAX_FILES_PER_BATCH } from "./uploads/constants.js";
 import { isFrontendNavigationRequest } from "./web-ui-routing.js";
 import type { WorkspaceManager } from "./workspace/manager.js";
@@ -43,29 +45,16 @@ interface AppDeps {
   wsHub: WsHub;
   webRoot?: string;
   workspaceMgr: WorkspaceManager;
+  skillLibraryRepo: SkillLibraryRepo;
   config: ServerConfig;
   authSessionRepo: AuthSessionRepo;
   authLoginBlockRepo: AuthLoginBlockRepo;
+  sessionTokenRepo?: SessionTokenRepo;
   appearanceAssetRepo?: AppearanceAssetRepoType;
+  canvasService?: CanvasService;
   logger?: FastifyServerOptions["logger"];
 }
 
-const SERVER_SRC_DIR = dirname(fileURLToPath(import.meta.url));
-const DEV_BROWSER_SW_FALLBACK_PATH = resolve(SERVER_SRC_DIR, "../../web/public/dev-browser-sw.js");
-
-function resolveDevBrowserServiceWorkerPath(webRoot?: string): string | null {
-  const webRootPath = webRoot ? join(webRoot, "dev-browser-sw.js") : null;
-  if (webRootPath && existsSync(webRootPath)) {
-    return webRootPath;
-  }
-
-  if (existsSync(DEV_BROWSER_SW_FALLBACK_PATH)) {
-    return DEV_BROWSER_SW_FALLBACK_PATH;
-  }
-
-  return null;
-}
-
 /**
  * Build Fastify application
  */
@@ -113,11 +102,12 @@ export async function buildFastifyApp(deps: AppDeps): Promise<FastifyInstance> {
 
   // Phase 2: Configurable auth middleware
   app.addHook(
-    "onRequest",
+    "preValidation",
     createAuthGuard({
       config: deps.config,
       authSessionRepo: deps.authSessionRepo,
       authLoginBlockRepo: deps.authLoginBlockRepo,
+      sessionTokenRepo: deps.sessionTokenRepo,
     })
   );
 
@@ -177,42 +167,40 @@ export async function buildFastifyApp(deps: AppDeps): Promise<FastifyInstance> {
   registerFileAssetRoutes(app, {
     workspaceMgr: deps.workspaceMgr,
   });
+  registerSkillFileAssetRoutes(app, {
+    skillLibraryRepo: deps.skillLibraryRepo,
+  });
 
   registerAppearanceAssetsRoutes(app, {
     uploadsDir: deps.config.uploadsDir,
     repo: appearanceAssetRepo,
   });
 
-  registerDevBrowserRoutes(app);
-
   const previewSessions = new PreviewSessionStore();
   registerPreviewRoutes(app, {
     workspaceMgr: deps.workspaceMgr,
     previewSessions,
   });
 
+  if (deps.canvasService) {
+    registerCanvasRoutes(app, {
+      workspaceMgr: deps.workspaceMgr,
+      canvasService: deps.canvasService,
+    });
+  }
+
   registerUploadsRoute(app, {
     uploadsDir: deps.config.uploadsDir,
     workspaceMgr: deps.workspaceMgr,
   });
 
-  app.get("/dev-browser-sw.js", async (_request, reply) => {
-    const scriptPath = resolveDevBrowserServiceWorkerPath(deps.webRoot);
-    if (!scriptPath) {
-      return reply.callNotFound();
-    }
-
-    const script = readFileSync(scriptPath, "utf8");
-    reply.header("Cache-Control", "no-cache, no-store, must-revalidate");
-    return reply.type("application/javascript; charset=utf-8").send(script);
-  });
-
   // Static file serving (for web UI)
   if (deps.webRoot) {
     app.register(staticPlugin, {
       root: deps.webRoot,
       prefix: "/",
       wildcard: false,
+      // Keep the retired dev browser service worker unavailable so older registrations cannot refresh themselves.
       globIgnore: ["index.html", "assets/**", "dev-browser-sw.js"],
       maxAge: "1y",
       immutable: true,
diff --git a/packages/server/src/auth/index.ts b/packages/server/src/auth/index.ts
index 18ce1bbcb..f5f52fb85 100644
--- a/packages/server/src/auth/index.ts
+++ b/packages/server/src/auth/index.ts
@@ -1,3 +1,4 @@
+export type { RequestAuthContext } from "./plugin.js";
 export {
   createAuthGuard,
   registerAuthLogoutRoute,
diff --git a/packages/server/src/auth/plugin.test.ts b/packages/server/src/auth/plugin.test.ts
index 4e203af45..b4a121b52 100644
--- a/packages/server/src/auth/plugin.test.ts
+++ b/packages/server/src/auth/plugin.test.ts
@@ -1,14 +1,19 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import type { Result } from "@coder-studio/core";
 import type { FastifyInstance } from "fastify";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { buildFastifyApp } from "../app.js";
+import { SessionTokenRepo } from "../auth/session-token-repo.js";
 import { EventBus } from "../bus/event-bus.js";
+import "../commands/memory.js";
 import { AuthLoginBlockRepo } from "../storage/repositories/auth-login-block-repo.js";
 import { AuthSessionRepo } from "../storage/repositories/auth-session-repo.js";
 import { WorkspaceRepo } from "../storage/repositories/workspace-repo.js";
 import { WorkspaceManager } from "../workspace/manager.js";
+import { ActivationManager } from "../ws/activation.js";
+import type { CommandContext } from "../ws/dispatch.js";
 import { FencingManager } from "../ws/fencing.js";
 import { WsHub } from "../ws/hub.js";
 
@@ -19,17 +24,10 @@ describe("auth login protection", () => {
   let stateDir: string;
   let app: FastifyInstance;
   let webRoot: string;
+  let sessionTokenRepo: SessionTokenRepo;
+  let wsHub: WsHub;
 
-  beforeEach(async () => {
-    tempDir = mkdtempSync(join(tmpdir(), "coder-studio-auth-"));
-    stateDir = join(tempDir, "state-root");
-    webRoot = join(tempDir, "web");
-    mkdirSync(join(webRoot, "assets"), { recursive: true });
-    writeFileSync(
-      join(webRoot, "index.html"),
-      '<!doctype html><html><body><div id="root">shell</div></body></html>'
-    );
-
+  async function createApp(options: { authEnabled: boolean; password?: string }) {
     const eventBus = new EventBus();
     const fencingMgr = new FencingManager();
     const config = {
@@ -40,27 +38,28 @@ describe("auth login protection", () => {
       logLevel: "info" as const,
       webRoot,
       auth: {
-        enabled: true,
-        password: "sekrit",
+        enabled: options.authEnabled,
+        password: options.password,
       },
     };
-    const wsHub = new WsHub({
+    const nextWsHub = new WsHub({
       eventBus,
-      commandContext: null as never,
+      commandContext: null,
       config,
       fencingMgr,
     });
+    const workspaceMgr = new WorkspaceManager({
+      workspaceRepo: new WorkspaceRepo({
+        filePath: join(tempDir, "state", "workspaces.json"),
+      }),
+      eventBus,
+      broadcaster: nextWsHub,
+    });
 
-    app = await buildFastifyApp({
-      wsHub,
+    const nextApp = await buildFastifyApp({
+      wsHub: nextWsHub,
       webRoot,
-      workspaceMgr: new WorkspaceManager({
-        workspaceRepo: new WorkspaceRepo({
-          filePath: join(tempDir, "state", "workspaces.json"),
-        }),
-        eventBus,
-        broadcaster: wsHub,
-      }),
+      workspaceMgr,
       config,
       authSessionRepo: new AuthSessionRepo({
         filePath: join(tempDir, "state", "auth-sessions.json"),
@@ -68,14 +67,73 @@ describe("auth login protection", () => {
       authLoginBlockRepo: new AuthLoginBlockRepo({
         filePath: join(tempDir, "state", "auth-login-blocks.json"),
       }),
+      sessionTokenRepo,
       logger: false,
     });
+
+    nextWsHub.setCommandContext({
+      workspaceMgr: {
+        get: (workspaceId: string) =>
+          workspaceId === "ws-1" ? { id: "ws-1", path: "/workspace" } : undefined,
+      },
+      sessionMgr: {},
+      terminalMgr: {},
+      taskMgr: {},
+      eventBus,
+      broadcaster: nextWsHub,
+      settingsRepo: {},
+      providerConfigRepo: {},
+      providerRegistry: [],
+      fencingMgr,
+      supervisorMgr: {},
+      autoFetch: {
+        unregisterViewer: () => undefined,
+      },
+      activationMgr: new ActivationManager(),
+      lspMgr: {},
+      memoryRepo: {
+        list: () => [],
+        get: () => undefined,
+        create: () => {
+          throw new Error("Unexpected memory.create");
+        },
+        update: () => {
+          throw new Error("Unexpected memory.update");
+        },
+        delete: () => {
+          throw new Error("Unexpected memory.delete");
+        },
+      },
+    } as unknown as CommandContext);
+
+    await nextApp.ready();
+    return {
+      app: nextApp,
+      wsHub: nextWsHub,
+    };
+  }
+
+  beforeEach(async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "coder-studio-auth-"));
+    stateDir = join(tempDir, "state-root");
+    webRoot = join(tempDir, "web");
+    mkdirSync(join(webRoot, "assets"), { recursive: true });
+    writeFileSync(
+      join(webRoot, "index.html"),
+      '<!doctype html><html><body><div id="root">shell</div></body></html>'
+    );
+
+    sessionTokenRepo = new SessionTokenRepo();
+    const created = await createApp({ authEnabled: true, password: "sekrit" });
+    app = created.app;
+    wsHub = created.wsHub;
   });
 
   afterEach(async () => {
     if (app) {
       await app.close();
     }
+    wsHub?.destroy();
     rmSync(tempDir, { recursive: true, force: true });
   });
 
@@ -269,6 +327,127 @@ describe("auth login protection", () => {
     });
   });
 
+  it("rejects websocket upgrades without cookie or bearer auth", async () => {
+    await expect(app.injectWS("/ws")).rejects.toThrow("Unexpected server response: 401");
+  });
+
+  it("accepts websocket upgrades with a valid loopback bearer token", async () => {
+    const tokenRecord = sessionTokenRepo.issue({
+      sessionId: "sess-1",
+      workspaceId: "ws-1",
+      providerId: "codex",
+      permissions: ["session:read"],
+    });
+
+    const socket = await app.injectWS("/ws", {
+      headers: {
+        authorization: `Bearer ${tokenRecord.token}`,
+        "x-forwarded-for": "127.0.0.1",
+      },
+    });
+
+    socket.terminate();
+  });
+
+  it("decorates auth-disabled websocket requests with a valid session token context", async () => {
+    await app.close();
+    wsHub.destroy();
+    const created = await createApp({ authEnabled: false });
+    app = created.app;
+    wsHub = created.wsHub;
+    const tokenRecord = sessionTokenRepo.issue({
+      sessionId: "sess-1",
+      workspaceId: "ws-1",
+      providerId: "codex",
+      permissions: ["memory:read"],
+    });
+
+    const socket = await app.injectWS("/ws", {
+      headers: {
+        authorization: `Bearer ${tokenRecord.token}`,
+        "x-forwarded-for": "127.0.0.1",
+      },
+    });
+    const resultPromise = new Promise<Result>((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error("Timed out waiting for result")), 2_000);
+      socket.on("message", (data) => {
+        const message = JSON.parse(data.toString()) as Result;
+        if (message.kind === "result" && message.id === "memory-list-1") {
+          clearTimeout(timeout);
+          resolve(message);
+        }
+      });
+    });
+
+    socket.send(
+      JSON.stringify({
+        kind: "command",
+        id: "memory-list-1",
+        op: "memory.list",
+        args: { workspaceId: "ws-1" },
+      })
+    );
+
+    await expect(resultPromise).resolves.toMatchObject({
+      ok: true,
+      data: [],
+    });
+    socket.terminate();
+  });
+
+  it("rejects websocket upgrades with an invalid bearer token", async () => {
+    await expect(
+      app.injectWS("/ws", {
+        headers: {
+          authorization: "Bearer invalid-token",
+          "x-forwarded-for": "127.0.0.1",
+        },
+      })
+    ).rejects.toThrow("Unexpected server response: 401");
+  });
+
+  it("does not allow non-websocket routes to use bearer auth as a cookie substitute", async () => {
+    const tokenRecord = sessionTokenRepo.issue({
+      sessionId: "sess-1",
+      workspaceId: "ws-1",
+      providerId: "codex",
+      permissions: ["session:read"],
+    });
+
+    const response = await app.inject({
+      method: "GET",
+      url: "/internal/openapi.json",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${tokenRecord.token}`,
+      },
+    });
+
+    expect(response.statusCode).toBe(401);
+    expect(response.json()).toMatchObject({
+      ok: false,
+      error: "Authentication required",
+    });
+  });
+
+  it("rejects bearer-auth websocket upgrades from non-loopback requests", async () => {
+    const tokenRecord = sessionTokenRepo.issue({
+      sessionId: "sess-1",
+      workspaceId: "ws-1",
+      providerId: "codex",
+      permissions: ["session:read"],
+    });
+
+    await expect(
+      app.injectWS("/ws", {
+        headers: {
+          authorization: `Bearer ${tokenRecord.token}`,
+          "x-forwarded-for": "198.51.100.24",
+        },
+      })
+    ).rejects.toThrow("Unexpected server response: 401");
+  });
+
   it("does not redirect bare reserved backend namespaces to the auth page", async () => {
     const apiResponse = await app.inject({
       method: "GET",
diff --git a/packages/server/src/auth/plugin.ts b/packages/server/src/auth/plugin.ts
index 49d6e1c36..a72dc2c9a 100644
--- a/packages/server/src/auth/plugin.ts
+++ b/packages/server/src/auth/plugin.ts
@@ -9,6 +9,7 @@ import {
   isPublicStaticPath,
 } from "../web-ui-routing.js";
 import { AuthLoginProtection, resolveClientIp } from "./login-protection.js";
+import type { SessionAutomationTokenRecord, SessionTokenRepo } from "./session-token-repo.js";
 
 const AUTH_COOKIE_NAME = "coder_studio_auth";
 
@@ -60,6 +61,17 @@ interface AuthDeps {
   config: ServerConfig;
   authSessionRepo: AuthSessionRepo;
   authLoginBlockRepo: AuthLoginBlockRepo;
+  sessionTokenRepo?: SessionTokenRepo;
+}
+
+export type RequestAuthContext =
+  | { mode: "browser" }
+  | ({ mode: "session_token" } & SessionAutomationTokenRecord);
+
+declare module "fastify" {
+  interface FastifyRequest {
+    coderStudioAuthContext?: RequestAuthContext;
+  }
 }
 
 const isFrontendNavigationRequest = (request: FastifyRequest, deps: AuthDeps): boolean => {
@@ -69,7 +81,79 @@ const isFrontendNavigationRequest = (request: FastifyRequest, deps: AuthDeps): b
   return isFrontendNavigationRequestForWebUi(request);
 };
 
+const LOOPBACK_IPS = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+
+function getBearerToken(request: FastifyRequest): string | null {
+  const header = request.headers.authorization;
+  if (!header) {
+    return null;
+  }
+
+  const match = header.match(/^Bearer\s+(.+)$/i);
+  if (!match) {
+    return null;
+  }
+
+  const token = match[1]?.trim();
+  return token ? token : null;
+}
+
+function getTrustedClientIp(request: FastifyRequest): string | null {
+  const ip = resolveClientIp({
+    headers: request.headers,
+    ip: request.ip ?? "",
+  }).trim();
+
+  return ip ? ip.toLowerCase() : null;
+}
+
+function isLoopbackRequest(request: FastifyRequest): boolean {
+  const ip = getTrustedClientIp(request);
+  if (!ip) {
+    return false;
+  }
+
+  return LOOPBACK_IPS.has(ip);
+}
+
+function authenticateSessionToken(
+  request: FastifyRequest,
+  deps: AuthDeps
+): SessionAutomationTokenRecord | null {
+  if (getRequestPathname(request.url) !== "/ws") {
+    return null;
+  }
+
+  const token = getBearerToken(request);
+  if (!token) {
+    return null;
+  }
+
+  if (!isLoopbackRequest(request)) {
+    return null;
+  }
+
+  return deps.sessionTokenRepo?.get(token) ?? null;
+}
+
+function decorateSessionTokenAuth(request: FastifyRequest, deps: AuthDeps): boolean {
+  const tokenRecord = authenticateSessionToken(request, deps);
+  if (tokenRecord) {
+    request.coderStudioAuthContext = {
+      mode: "session_token",
+      ...tokenRecord,
+    };
+    return true;
+  }
+
+  return false;
+}
+
 const isAuthenticatedRequest = (request: FastifyRequest, deps: AuthDeps): boolean => {
+  if (decorateSessionTokenAuth(request, deps)) {
+    return true;
+  }
+
   if (!deps.config.auth.enabled) {
     return true;
   }
@@ -81,11 +165,19 @@ const isAuthenticatedRequest = (request: FastifyRequest, deps: AuthDeps): boolea
   }
 
   const token = decodeAuthCookieValue(authCookie);
-  return deps.authSessionRepo.touch(token, Date.now());
+  const authenticated = deps.authSessionRepo.touch(token, Date.now());
+  if (authenticated) {
+    request.coderStudioAuthContext = { mode: "browser" };
+  }
+  return authenticated;
 };
 
 export const createAuthGuard = (deps: AuthDeps) => {
   return async (request: FastifyRequest, reply: FastifyReply) => {
+    if (decorateSessionTokenAuth(request, deps)) {
+      return;
+    }
+
     if (
       !deps.config.auth.enabled ||
       isPublicPath(request.url) ||
diff --git a/packages/server/src/auth/session-token-repo.ts b/packages/server/src/auth/session-token-repo.ts
new file mode 100644
index 000000000..88cf1102d
--- /dev/null
+++ b/packages/server/src/auth/session-token-repo.ts
@@ -0,0 +1,86 @@
+import { randomBytes } from "node:crypto";
+import type { AutomationPermission } from "@coder-studio/core";
+
+export interface SessionAutomationTokenRecord {
+  token: string;
+  sessionId: string;
+  workspaceId: string;
+  providerId: string;
+  permissions: readonly AutomationPermission[];
+  createdAt: number;
+}
+
+export interface IssueSessionAutomationTokenInput {
+  sessionId: string;
+  workspaceId: string;
+  providerId: string;
+  permissions: readonly AutomationPermission[];
+}
+
+export class SessionTokenRepo {
+  private readonly recordsByToken = new Map<string, SessionAutomationTokenRecord>();
+  private readonly tokensBySessionId = new Map<string, Set<string>>();
+
+  issue(input: IssueSessionAutomationTokenInput): SessionAutomationTokenRecord {
+    const record: SessionAutomationTokenRecord = {
+      token: randomBytes(32).toString("hex"),
+      sessionId: input.sessionId,
+      workspaceId: input.workspaceId,
+      providerId: input.providerId,
+      permissions: [...input.permissions],
+      createdAt: Date.now(),
+    };
+
+    this.recordsByToken.set(record.token, record);
+    const tokens = this.tokensBySessionId.get(record.sessionId) ?? new Set<string>();
+    tokens.add(record.token);
+    this.tokensBySessionId.set(record.sessionId, tokens);
+    return record;
+  }
+
+  get(token: string): SessionAutomationTokenRecord | undefined {
+    return this.recordsByToken.get(token);
+  }
+
+  listBySessionId(sessionId: string): SessionAutomationTokenRecord[] {
+    const tokens = this.tokensBySessionId.get(sessionId);
+    if (!tokens) {
+      return [];
+    }
+
+    return Array.from(tokens)
+      .map((token) => this.recordsByToken.get(token))
+      .filter((record): record is SessionAutomationTokenRecord => record !== undefined);
+  }
+
+  revoke(token: string): boolean {
+    const record = this.recordsByToken.get(token);
+    if (!record) {
+      return false;
+    }
+
+    this.recordsByToken.delete(token);
+    const tokens = this.tokensBySessionId.get(record.sessionId);
+    if (!tokens) {
+      return true;
+    }
+
+    tokens.delete(token);
+    if (tokens.size === 0) {
+      this.tokensBySessionId.delete(record.sessionId);
+    }
+    return true;
+  }
+
+  revokeBySessionId(sessionId: string): void {
+    const tokens = this.tokensBySessionId.get(sessionId);
+    if (!tokens) {
+      return;
+    }
+
+    for (const token of tokens) {
+      this.recordsByToken.delete(token);
+    }
+    this.tokensBySessionId.delete(sessionId);
+  }
+}
diff --git a/packages/server/src/canvas/compiler.test.ts b/packages/server/src/canvas/compiler.test.ts
new file mode 100644
index 000000000..a0bb014de
--- /dev/null
+++ b/packages/server/src/canvas/compiler.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import { compileCanvasDocument } from "./compiler.js";
+
+describe("compileCanvasDocument", () => {
+  it("produces an architecture_canvas render model", () => {
+    const compiled = compileCanvasDocument({
+      version: 1,
+      kind: "architecture_canvas",
+      title: "Runtime Flow",
+      document: {
+        summary: "How requests move.",
+        diagram: {
+          dsl: "mermaid",
+          source: ["WebUI[Web UI]", "Server[Runtime Server]", "WebUI -->|dispatch| Server"].join(
+            "\n"
+          ),
+        },
+        annotations: [{ title: "Boundary", body: "Server owns execution." }],
+      },
+    });
+
+    expect(compiled).toEqual({
+      kind: "architecture_canvas",
+      title: "Runtime Flow",
+      summary: "How requests move.",
+      sections: [
+        {
+          type: "diagram",
+          mermaidSource: [
+            "WebUI[Web UI]",
+            "Server[Runtime Server]",
+            "WebUI -->|dispatch| Server",
+          ].join("\n"),
+          direction: undefined,
+          groups: [],
+          nodes: [
+            { id: "WebUI", label: "Web UI" },
+            { id: "Server", label: "Runtime Server" },
+          ],
+          edges: [{ from: "WebUI", to: "Server", label: "dispatch" }],
+        },
+        {
+          type: "annotations",
+          items: [{ title: "Boundary", body: "Server owns execution." }],
+        },
+      ],
+    });
+  });
+
+  it("produces a report_canvas render model", () => {
+    const compiled = compileCanvasDocument({
+      version: 1,
+      kind: "report_canvas",
+      title: "Audit",
+      document: {
+        summary: "Workspace audit.",
+        stats: [{ label: "Packages", value: 6, tone: "info" }],
+        sections: [
+          {
+            title: "Findings",
+            blocks: [
+              { type: "markdown", markdown: "Server owns rendering." },
+              {
+                type: "stats",
+                items: [{ label: "Packages", value: 6 }],
+              },
+            ],
+          },
+        ],
+      },
+    });
+
+    expect(compiled).toEqual({
+      kind: "report_canvas",
+      title: "Audit",
+      sections: [
+        {
+          type: "stats",
+          items: [{ label: "Packages", value: "6", tone: "info" }],
+        },
+        {
+          type: "section",
+          title: "Findings",
+          blocks: [
+            { type: "markdown", markdown: "Server owns rendering." },
+            {
+              type: "stats",
+              items: [{ label: "Packages", value: "6", tone: undefined }],
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it("uses Mermaid flowchart compilation for Mermaid architecture canvases", () => {
+    const compiled = compileCanvasDocument({
+      version: 1,
+      kind: "architecture_canvas",
+      title: "Runtime Flow",
+      document: {
+        summary: "How requests move.",
+        diagram: {
+          dsl: "mermaid",
+          source: "flowchart LR\nWebUI[Web UI] -->|dispatch| Server[Runtime Server]",
+        },
+        annotations: [],
+      },
+    });
+
+    expect(compiled).toEqual({
+      kind: "architecture_canvas",
+      title: "Runtime Flow",
+      summary: "How requests move.",
+      sections: [
+        {
+          type: "diagram",
+          mermaidSource: "flowchart LR\nWebUI[Web UI] -->|dispatch| Server[Runtime Server]",
+          direction: "LR",
+          groups: [],
+          nodes: [
+            { id: "WebUI", label: "Web UI" },
+            { id: "Server", label: "Runtime Server" },
+          ],
+          edges: [{ from: "WebUI", to: "Server", label: "dispatch" }],
+        },
+        {
+          type: "annotations",
+          items: [],
+        },
+      ],
+    });
+  });
+});
diff --git a/packages/server/src/canvas/compiler.ts b/packages/server/src/canvas/compiler.ts
new file mode 100644
index 000000000..b49750967
--- /dev/null
+++ b/packages/server/src/canvas/compiler.ts
@@ -0,0 +1,59 @@
+import type { CanvasDocumentEnvelope, CompiledCanvas } from "@coder-studio/core";
+import { parseMermaidFlowchart } from "./mermaid-flowchart.js";
+
+export function compileCanvasDocument(document: CanvasDocumentEnvelope): CompiledCanvas {
+  if (document.kind === "architecture_canvas") {
+    const graph = parseMermaidFlowchart(document.document.diagram.source);
+
+    return {
+      kind: "architecture_canvas",
+      title: document.title,
+      summary: document.document.summary,
+      sections: [
+        {
+          type: "diagram",
+          mermaidSource: document.document.diagram.source,
+          direction: graph.direction,
+          groups: graph.groups,
+          nodes: graph.nodes,
+          edges: graph.edges,
+        },
+        {
+          type: "annotations",
+          items: document.document.annotations,
+        },
+      ],
+    };
+  }
+
+  return {
+    kind: "report_canvas",
+    title: document.title,
+    sections: [
+      {
+        type: "stats",
+        items: document.document.stats.map((stat) => ({
+          label: stat.label,
+          value: String(stat.value),
+          tone: stat.tone,
+        })),
+      },
+      ...document.document.sections.map((section) => ({
+        type: "section" as const,
+        title: section.title,
+        blocks: section.blocks.map((block) =>
+          block.type === "stats"
+            ? {
+                ...block,
+                items: block.items.map((item) => ({
+                  label: item.label,
+                  value: String(item.value),
+                  tone: item.tone,
+                })),
+              }
+            : block
+        ),
+      })),
+    ],
+  };
+}
diff --git a/packages/server/src/canvas/mermaid-flowchart.test.ts b/packages/server/src/canvas/mermaid-flowchart.test.ts
new file mode 100644
index 000000000..fe33de2b0
--- /dev/null
+++ b/packages/server/src/canvas/mermaid-flowchart.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { parseMermaidFlowchart } from "./mermaid-flowchart.js";
+
+describe("parseMermaidFlowchart", () => {
+  it("produces labeled nodes and labeled edges", () => {
+    const graph = parseMermaidFlowchart(
+      "flowchart LR\nWebUI[Web UI] -->|dispatch| Server[Runtime Server]"
+    );
+
+    expect(graph).toEqual({
+      direction: "LR",
+      groups: [],
+      nodes: [
+        { id: "WebUI", label: "Web UI" },
+        { id: "Server", label: "Runtime Server" },
+      ],
+      edges: [{ from: "WebUI", to: "Server", label: "dispatch" }],
+    });
+  });
+
+  it("tracks simple subgraphs as groups", () => {
+    const graph = parseMermaidFlowchart(
+      [
+        "flowchart TD",
+        "subgraph Client Layer",
+        "  WebUI[Web UI]",
+        "end",
+        "Server[Runtime Server]",
+        "WebUI --> Server",
+      ].join("\n")
+    );
+
+    expect(graph.groups).toEqual([
+      {
+        id: "client-layer",
+        label: "Client Layer",
+        nodeIds: ["WebUI"],
+      },
+    ]);
+    expect(graph.direction).toBe("TD");
+  });
+
+  it("rejects unsupported flowchart statements", () => {
+    expect(() => parseMermaidFlowchart("flowchart LR\nclassDef hot fill:#f00")).toThrow(
+      "Unsupported Mermaid flowchart statement"
+    );
+  });
+});
diff --git a/packages/server/src/canvas/mermaid-flowchart.ts b/packages/server/src/canvas/mermaid-flowchart.ts
new file mode 100644
index 000000000..ce12409fd
--- /dev/null
+++ b/packages/server/src/canvas/mermaid-flowchart.ts
@@ -0,0 +1,182 @@
+export interface MermaidFlowchartNode {
+  id: string;
+  label?: string;
+}
+
+export interface MermaidFlowchartEdge {
+  from: string;
+  to: string;
+  label?: string;
+}
+
+export interface MermaidFlowchartGroup {
+  id: string;
+  label: string;
+  nodeIds: string[];
+}
+
+export interface MermaidFlowchartGraph {
+  direction?: "TB" | "TD" | "BT" | "LR" | "RL";
+  groups: MermaidFlowchartGroup[];
+  nodes: MermaidFlowchartNode[];
+  edges: MermaidFlowchartEdge[];
+}
+
+function normalizeGroupId(label: string): string {
+  return (
+    label
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/gu, "-")
+      .replace(/^-+|-+$/gu, "") || "group"
+  );
+}
+
+function parseNodeToken(token: string): MermaidFlowchartNode {
+  const trimmed = token.trim();
+  const labeled = trimmed.match(/^([A-Za-z0-9_-]+)\[(.+)\]$/u);
+  if (labeled) {
+    return {
+      id: labeled[1]!,
+      label: labeled[2]!.trim(),
+    };
+  }
+
+  const bare = trimmed.match(/^([A-Za-z0-9_-]+)$/u);
+  if (bare) {
+    return { id: bare[1]! };
+  }
+
+  throw new Error(`Unsupported Mermaid node token: ${trimmed}`);
+}
+
+function upsertNode(
+  nodes: Map<string, MermaidFlowchartNode>,
+  node: MermaidFlowchartNode
+): MermaidFlowchartNode {
+  const existing = nodes.get(node.id);
+  const next = {
+    id: node.id,
+    label: node.label ?? existing?.label,
+  };
+  nodes.set(node.id, next);
+  return next;
+}
+
+function parseEdgeLine(line: string): MermaidFlowchartEdge & {
+  fromNode: MermaidFlowchartNode;
+  toNode: MermaidFlowchartNode;
+} {
+  const labeled = line.match(/^(.*?)\s*-->\|(.*?)\|\s*(.*?)$/u);
+  if (labeled) {
+    const fromNode = parseNodeToken(labeled[1]!);
+    const toNode = parseNodeToken(labeled[3]!);
+    return {
+      from: fromNode.id,
+      to: toNode.id,
+      label: labeled[2]!.trim() || undefined,
+      fromNode,
+      toNode,
+    };
+  }
+
+  const plain = line.match(/^(.*?)\s*-->\s*(.*?)$/u);
+  if (plain) {
+    const fromNode = parseNodeToken(plain[1]!);
+    const toNode = parseNodeToken(plain[2]!);
+    return {
+      from: fromNode.id,
+      to: toNode.id,
+      fromNode,
+      toNode,
+    };
+  }
+
+  throw new Error(`Unsupported Mermaid flowchart statement: ${line}`);
+}
+
+function trackNodeInGroups(groups: MermaidFlowchartGroup[], nodeId: string): void {
+  for (const group of groups) {
+    if (!group.nodeIds.includes(nodeId)) {
+      group.nodeIds.push(nodeId);
+    }
+  }
+}
+
+export function parseMermaidFlowchart(source: string): MermaidFlowchartGraph {
+  const nodes = new Map<string, MermaidFlowchartNode>();
+  const edges: MermaidFlowchartEdge[] = [];
+  const groups: MermaidFlowchartGroup[] = [];
+  const groupStack: MermaidFlowchartGroup[] = [];
+  let direction: MermaidFlowchartGraph["direction"];
+
+  for (const rawLine of source.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (!line) {
+      continue;
+    }
+
+    const header = line.match(/^(flowchart|graph)\s+(TB|TD|BT|LR|RL)$/u);
+    if (header) {
+      direction = header[2] as MermaidFlowchartGraph["direction"];
+      continue;
+    }
+
+    if (line.startsWith("subgraph ")) {
+      const label = line.slice("subgraph ".length).trim();
+      if (!label) {
+        throw new Error("Mermaid subgraph label is required");
+      }
+
+      const group: MermaidFlowchartGroup = {
+        id: normalizeGroupId(label),
+        label,
+        nodeIds: [],
+      };
+      groups.push(group);
+      groupStack.push(group);
+      continue;
+    }
+
+    if (line === "end") {
+      if (groupStack.length === 0) {
+        throw new Error("Unexpected Mermaid subgraph terminator");
+      }
+      groupStack.pop();
+      continue;
+    }
+
+    if (line.includes("-->")) {
+      const edge = parseEdgeLine(line);
+      const fromNode = upsertNode(nodes, edge.fromNode);
+      const toNode = upsertNode(nodes, edge.toNode);
+      trackNodeInGroups(groupStack, fromNode.id);
+      trackNodeInGroups(groupStack, toNode.id);
+      edges.push({
+        from: edge.from,
+        to: edge.to,
+        label: edge.label,
+      });
+      continue;
+    }
+
+    try {
+      const node = upsertNode(nodes, parseNodeToken(line));
+      trackNodeInGroups(groupStack, node.id);
+      continue;
+    } catch {
+      throw new Error(`Unsupported Mermaid flowchart statement: ${line}`);
+    }
+  }
+
+  if (groupStack.length > 0) {
+    throw new Error("Unterminated Mermaid subgraph");
+  }
+
+  return {
+    direction,
+    groups: groups.filter((group) => group.nodeIds.length > 0),
+    nodes: [...nodes.values()],
+    edges,
+  };
+}
diff --git a/packages/server/src/canvas/service.test.ts b/packages/server/src/canvas/service.test.ts
new file mode 100644
index 000000000..9071347cb
--- /dev/null
+++ b/packages/server/src/canvas/service.test.ts
@@ -0,0 +1,531 @@
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { CanvasRepo } from "../storage/repositories/canvas-repo.js";
+import { CanvasService } from "./service.js";
+
+describe("CanvasService", () => {
+  let tempDir: string | undefined;
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+      tempDir = undefined;
+    }
+  });
+
+  it("creates a canvas source file, stores metadata, and lists it", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(workspaceRoot, { recursive: true });
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    const result = await service.create({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      document: {
+        summary: "How requests move.",
+        diagram: {
+          dsl: "mermaid",
+          source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+        },
+        annotations: [],
+      },
+    });
+
+    expect(result.record.title).toBe("Runtime Flow");
+    expect(result.record.sourcePath).toBe(".coder-studio/canvases/runtime-flow.csc");
+    expect(result.renderStatus).toBe("ready");
+    expect(result.lastError).toBeNull();
+    expect(readFileSync(join(workspaceRoot, result.record.sourcePath), "utf8")).toContain(
+      '"kind": "architecture_canvas"'
+    );
+    expect(await service.list("ws-1")).toEqual([result.record]);
+  });
+
+  it("returns compiled canvas data for a persisted source file", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(workspaceRoot, { recursive: true });
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    const created = await service.create({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      document: {
+        summary: "How requests move.",
+        diagram: {
+          dsl: "mermaid",
+          source: "flowchart LR\nWebUI[Web UI] -->|dispatch| Server[Server]",
+        },
+        annotations: [{ title: "Boundary", body: "Server owns execution." }],
+      },
+    });
+
+    const result = await service.getCanvasData({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      canvasId: created.record.id,
+    });
+
+    expect(result).toMatchObject({
+      canvasId: created.record.id,
+      workspaceId: "ws-1",
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      renderStatus: "ready",
+      lastError: null,
+      compiledDocument: {
+        kind: "architecture_canvas",
+        title: "Runtime Flow",
+        summary: "How requests move.",
+      },
+    });
+    expect(result.compiledDocument?.sections[0]).toMatchObject({
+      type: "diagram",
+      direction: "LR",
+      nodes: [
+        { id: "WebUI", label: "Web UI" },
+        { id: "Server", label: "Server" },
+      ],
+      edges: [{ from: "WebUI", to: "Server", label: "dispatch" }],
+    });
+  });
+
+  it("prefers sourcePath identity over a mismatched canvasId when rendering", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(join(workspaceRoot, ".coder-studio", "canvases"), { recursive: true });
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/other-flow.csc",
+      artifactType: "report_canvas",
+      title: "Other Canvas",
+      updatedAt: 999,
+      renderStatus: "ready",
+      lastError: null,
+    });
+
+    writeFileSync(
+      join(workspaceRoot, ".coder-studio/canvases/runtime-flow.csc"),
+      JSON.stringify(
+        {
+          version: 1,
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          document: {
+            summary: "How requests move.",
+            diagram: {
+              dsl: "mermaid",
+              source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+            },
+            annotations: [],
+          },
+        },
+        null,
+        2
+      ) + "\n"
+    );
+
+    const result = await service.getCanvasData({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      canvasId: "canvas-1",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+
+    expect(result).toMatchObject({
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      renderStatus: "ready",
+      lastError: null,
+    });
+    expect(result.canvasId).toBeUndefined();
+    expect(repo.get("ws-1", "canvas-1")).toMatchObject({
+      id: "canvas-1",
+      sourcePath: ".coder-studio/canvases/other-flow.csc",
+      title: "Other Canvas",
+      artifactType: "report_canvas",
+    });
+  });
+
+  it("creates unique readable source files for concurrent canvases with the same title", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(workspaceRoot, { recursive: true });
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    const [first, second] = await Promise.all([
+      service.create({
+        workspaceId: "ws-1",
+        workspaceRootPath: workspaceRoot,
+        title: "Runtime Flow",
+        kind: "architecture_canvas",
+        document: {
+          summary: "First flow.",
+          diagram: {
+            dsl: "mermaid",
+            source: "flowchart LR\nClient[Client] --> Server[Server]",
+          },
+          annotations: [],
+        },
+      }),
+      service.create({
+        workspaceId: "ws-1",
+        workspaceRootPath: workspaceRoot,
+        title: "Runtime Flow",
+        kind: "architecture_canvas",
+        document: {
+          summary: "Second flow.",
+          diagram: {
+            dsl: "mermaid",
+            source: "flowchart LR\nWorker[Worker] --> Queue[Queue]",
+          },
+          annotations: [],
+        },
+      }),
+    ]);
+
+    const sourcePaths = [first.record.sourcePath, second.record.sourcePath].sort();
+    expect(sourcePaths).toEqual([
+      ".coder-studio/canvases/runtime-flow-2.csc",
+      ".coder-studio/canvases/runtime-flow.csc",
+    ]);
+    expect(new Set(sourcePaths).size).toBe(2);
+
+    const sourceContents = [
+      readFileSync(join(workspaceRoot, first.record.sourcePath), "utf8"),
+      readFileSync(join(workspaceRoot, second.record.sourcePath), "utf8"),
+    ].join("\n");
+    expect(sourceContents).toContain('"summary": "First flow."');
+    expect(sourceContents).toContain('"summary": "Second flow."');
+    expect(await service.list("ws-1")).toHaveLength(2);
+  });
+
+  it("rejects canvas creation when the canvas directory escapes through a symlink", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    const outsideRoot = join(tempDir, "outside-canvases");
+    mkdirSync(join(workspaceRoot, ".coder-studio"), { recursive: true });
+    mkdirSync(outsideRoot, { recursive: true });
+    symlinkSync(
+      outsideRoot,
+      join(workspaceRoot, ".coder-studio", "canvases"),
+      process.platform === "win32" ? "junction" : "dir"
+    );
+
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    await expect(
+      service.create({
+        workspaceId: "ws-1",
+        workspaceRootPath: workspaceRoot,
+        title: "Runtime Flow",
+        kind: "architecture_canvas",
+        document: {
+          summary: "How requests move.",
+          diagram: {
+            dsl: "mermaid",
+            source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+          },
+          annotations: [],
+        },
+      })
+    ).rejects.toMatchObject({
+      code: "path_escape",
+    });
+
+    expect(existsSync(join(outsideRoot, "runtime-flow.csc"))).toBe(false);
+    expect(repo.list("ws-1")).toEqual([]);
+  });
+
+  it("returns an error response for invalid source content", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(join(workspaceRoot, ".coder-studio", "canvases"), { recursive: true });
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      artifactType: "architecture_canvas",
+      title: "Broken Canvas",
+      updatedAt: 999,
+      renderStatus: "ready",
+      lastError: null,
+    });
+
+    writeFileSync(
+      join(workspaceRoot, ".coder-studio/canvases/canvas-1.canvas.json"),
+      JSON.stringify({
+        version: 1,
+        kind: "architecture_canvas",
+        title: "Broken Canvas",
+        document: {
+          summary: "Missing diagram payload.",
+          annotations: [],
+        },
+      })
+    );
+
+    const result = await service.getCanvasData({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      canvasId: "canvas-1",
+    });
+
+    expect(result.canvasId).toBe("canvas-1");
+    expect(result.renderStatus).toBe("error");
+    expect(result.compiledDocument).toBeUndefined();
+    expect(result.lastError).toMatchObject({
+      category: "validation_error",
+    });
+    expect(repo.get("ws-1", "canvas-1")).toMatchObject({
+      renderStatus: "error",
+    });
+  });
+
+  it("returns a compile error response when graph compilation fails", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(join(workspaceRoot, ".coder-studio", "canvases"), { recursive: true });
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      artifactType: "architecture_canvas",
+      title: "Broken Canvas",
+      updatedAt: 999,
+      renderStatus: "rendering",
+      lastError: null,
+    });
+
+    writeFileSync(
+      join(workspaceRoot, ".coder-studio/canvases/canvas-1.canvas.json"),
+      JSON.stringify({
+        version: 1,
+        kind: "architecture_canvas",
+        title: "Broken Canvas",
+        document: {
+          summary: "Broken graph.",
+          diagram: {
+            dsl: "mermaid",
+            source: "flowchart LR\ninvalid syntax here!!!",
+          },
+          annotations: [],
+        },
+      })
+    );
+
+    const result = await service.getCanvasData({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      canvasId: "canvas-1",
+    });
+
+    expect(result.renderStatus).toBe("error");
+    expect(result.compiledDocument).toBeUndefined();
+    expect(result.lastError).toMatchObject({
+      category: "compile_error",
+    });
+    expect(repo.get("ws-1", "canvas-1")).toMatchObject({
+      renderStatus: "error",
+    });
+  });
+
+  it("updates an existing canvas source file and record", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(workspaceRoot, { recursive: true });
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    const created = await service.create({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      document: {
+        summary: "How requests move.",
+        diagram: {
+          dsl: "mermaid",
+          source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+        },
+        annotations: [],
+      },
+    });
+
+    const result = await service.update({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      canvasId: created.record.id,
+      title: "Recovered Canvas",
+      document: {
+        summary: "Recovered",
+        diagram: {
+          dsl: "mermaid",
+          source: "flowchart LR\nWebUI[Web UI] --> Server[Server]",
+        },
+        annotations: [],
+      },
+    });
+
+    expect(result.record).toMatchObject({
+      id: created.record.id,
+      title: "Recovered Canvas",
+      artifactType: "architecture_canvas",
+      renderStatus: "ready",
+      lastError: null,
+    });
+    expect(result.renderStatus).toBe("ready");
+    expect(readFileSync(join(workspaceRoot, created.record.sourcePath), "utf8")).toContain(
+      '"title": "Recovered Canvas"'
+    );
+  });
+
+  it("allows updating an invalid source file with a valid document", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(join(workspaceRoot, ".coder-studio", "canvases"), { recursive: true });
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      artifactType: "architecture_canvas",
+      title: "Broken Canvas",
+      updatedAt: 999,
+      renderStatus: "error",
+      lastError: {
+        category: "validation_error",
+        message: "Invalid canvas source",
+      },
+    });
+
+    writeFileSync(
+      join(workspaceRoot, ".coder-studio/canvases/canvas-1.canvas.json"),
+      JSON.stringify({
+        version: 1,
+        kind: "architecture_canvas",
+        title: "Broken Canvas",
+        document: {
+          summary: "Missing diagram payload.",
+          annotations: [],
+        },
+      })
+    );
+
+    const result = await service.update({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      canvasId: "canvas-1",
+      title: "Recovered Canvas",
+      document: {
+        summary: "Recovered",
+        diagram: {
+          dsl: "mermaid",
+          source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+        },
+        annotations: [],
+      },
+    });
+
+    expect(result.record).toMatchObject({
+      id: "canvas-1",
+      title: "Recovered Canvas",
+      renderStatus: "ready",
+      lastError: null,
+    });
+    expect(result.renderStatus).toBe("ready");
+    expect(result.lastError).toBeNull();
+  });
+
+  it("renders canvas data from a persisted source path", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-service-"));
+    const workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(join(workspaceRoot, ".coder-studio", "canvases"), { recursive: true });
+    const repo = new CanvasRepo({ rootDir: join(tempDir, "state", "canvases") });
+    const service = new CanvasService({ canvasRepo: repo, now: () => 1000 });
+
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      artifactType: "architecture_canvas",
+      title: "Runtime Flow",
+      updatedAt: 999,
+      renderStatus: "rendering",
+      lastError: null,
+    });
+
+    writeFileSync(
+      join(workspaceRoot, ".coder-studio/canvases/canvas-1.canvas.json"),
+      JSON.stringify(
+        {
+          version: 1,
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          document: {
+            summary: "How requests move.",
+            diagram: {
+              dsl: "mermaid",
+              source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+            },
+            annotations: [],
+          },
+        },
+        null,
+        2
+      ) + "\n"
+    );
+
+    const result = await service.renderFromSourcePath({
+      workspaceId: "ws-1",
+      workspaceRootPath: workspaceRoot,
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+    });
+
+    expect(result).toMatchObject({
+      canvasId: "canvas-1",
+      workspaceId: "ws-1",
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      renderStatus: "ready",
+      lastError: null,
+      compiledDocument: {
+        kind: "architecture_canvas",
+        title: "Runtime Flow",
+      },
+    });
+  });
+});
diff --git a/packages/server/src/canvas/service.ts b/packages/server/src/canvas/service.ts
new file mode 100644
index 000000000..4299dab28
--- /dev/null
+++ b/packages/server/src/canvas/service.ts
@@ -0,0 +1,398 @@
+import { randomBytes } from "node:crypto";
+import { basename } from "node:path";
+import {
+  CANVAS_DOCUMENT_VERSION,
+  type CanvasArtifactKind,
+  type CanvasDataResponse,
+  type CanvasDocumentEnvelope,
+  type CanvasRecord,
+  type CanvasRenderError,
+} from "@coder-studio/core";
+import { deleteEntry, readFile, writeFile } from "../fs/file-io.js";
+import { CanvasRepo } from "../storage/repositories/canvas-repo.js";
+import { compileCanvasDocument } from "./compiler.js";
+import { writeNewCanvasSource } from "./source-path.js";
+import { validateCanvasSource } from "./validation.js";
+
+interface CanvasServiceOptions {
+  canvasRepo: CanvasRepo;
+  now?: () => number;
+}
+
+function createCanvasId(now: number): string {
+  return `canvas_${now}_${randomBytes(4).toString("hex")}`;
+}
+
+function throwValidationError(error: CanvasRenderError): never {
+  throw {
+    code: "canvas_validation_error",
+    message: error.message,
+    details: error,
+  };
+}
+
+function normalizeCompileError(error: unknown): CanvasRenderError {
+  return {
+    category: "compile_error",
+    message: error instanceof Error ? error.message : "Failed to compile canvas",
+  };
+}
+
+export class CanvasService {
+  private readonly now: () => number;
+
+  constructor(private readonly options: CanvasServiceOptions) {
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  async create(input: {
+    workspaceId: string;
+    workspaceRootPath: string;
+    sessionId?: string;
+    title: string;
+    kind: CanvasArtifactKind;
+    document: unknown;
+  }): Promise<{
+    record: CanvasRecord;
+    source: CanvasDocumentEnvelope;
+    renderStatus: CanvasDataResponse["renderStatus"];
+    lastError: CanvasRenderError | null;
+  }> {
+    const timestamp = this.now();
+    const canvasId = createCanvasId(timestamp);
+    const envelope = {
+      version: CANVAS_DOCUMENT_VERSION,
+      kind: input.kind,
+      title: input.title,
+      document: input.document,
+    };
+    const parsed = validateCanvasSource(JSON.stringify(envelope));
+    if (!parsed.ok) {
+      throwValidationError(parsed.error);
+    }
+
+    const sourcePath = await writeNewCanvasSource({
+      workspaceRootPath: input.workspaceRootPath,
+      title: input.title,
+      content: JSON.stringify(parsed.document, null, 2) + "\n",
+    });
+
+    let record: CanvasRecord | undefined;
+
+    try {
+      record = this.options.canvasRepo.upsert({
+        id: canvasId,
+        workspaceId: input.workspaceId,
+        sessionId: input.sessionId,
+        sourcePath,
+        artifactType: parsed.document.kind,
+        title: parsed.document.title,
+        updatedAt: timestamp,
+        renderStatus: "rendering",
+        lastError: null,
+      });
+
+      const data = await this.readCanvasData({
+        workspaceId: input.workspaceId,
+        workspaceRootPath: input.workspaceRootPath,
+        sourcePath,
+        record,
+      });
+
+      return {
+        record: this.options.canvasRepo.get(input.workspaceId, canvasId) ?? record,
+        source: parsed.document,
+        renderStatus: data.renderStatus,
+        lastError: data.lastError ?? null,
+      };
+    } catch (error) {
+      if (record) {
+        this.options.canvasRepo.delete(input.workspaceId, canvasId);
+      }
+
+      try {
+        await deleteEntry(input.workspaceRootPath, sourcePath);
+      } catch (cleanupError) {
+        if ((cleanupError as { code?: string }).code !== "not_found") {
+          throw cleanupError;
+        }
+      }
+
+      throw error;
+    }
+  }
+
+  async update(input: {
+    workspaceId: string;
+    workspaceRootPath: string;
+    canvasId: string;
+    title?: string;
+    document: unknown;
+  }): Promise<{
+    record: CanvasRecord;
+    source: CanvasDocumentEnvelope;
+    renderStatus: CanvasDataResponse["renderStatus"];
+    lastError: CanvasRenderError | null;
+  }> {
+    const existing = this.options.canvasRepo.get(input.workspaceId, input.canvasId);
+    if (!existing) {
+      throw { code: "canvas_not_found", message: `Canvas not found: ${input.canvasId}` };
+    }
+
+    const currentRead = await readFile(
+      input.workspaceId,
+      input.workspaceRootPath,
+      existing.sourcePath
+    );
+    if (currentRead.kind !== "text") {
+      throw { code: "canvas_source_invalid", message: "Canvas source must be a text file" };
+    }
+
+    const nextEnvelope = {
+      version: CANVAS_DOCUMENT_VERSION,
+      kind: existing.artifactType,
+      title: input.title ?? existing.title,
+      document: input.document,
+    };
+    const nextParsed = validateCanvasSource(JSON.stringify(nextEnvelope));
+    if (!nextParsed.ok) {
+      throwValidationError(nextParsed.error);
+    }
+
+    if (nextParsed.document.kind !== existing.artifactType) {
+      throw {
+        code: "canvas_kind_mismatch",
+        message: "Canvas kind cannot change in v1",
+      };
+    }
+
+    await writeFile(
+      input.workspaceRootPath,
+      existing.sourcePath,
+      JSON.stringify(nextParsed.document, null, 2) + "\n",
+      currentRead.baseHash
+    );
+
+    const record = this.options.canvasRepo.upsert({
+      ...existing,
+      title: nextParsed.document.title,
+      updatedAt: this.now(),
+      renderStatus: "rendering",
+      lastError: null,
+    });
+
+    const data = await this.readCanvasData({
+      workspaceId: input.workspaceId,
+      workspaceRootPath: input.workspaceRootPath,
+      sourcePath: existing.sourcePath,
+      record,
+    });
+
+    return {
+      record: this.options.canvasRepo.get(input.workspaceId, input.canvasId) ?? record,
+      source: nextParsed.document,
+      renderStatus: data.renderStatus,
+      lastError: data.lastError ?? null,
+    };
+  }
+
+  async list(workspaceId: string): Promise<CanvasRecord[]> {
+    return this.options.canvasRepo.list(workspaceId);
+  }
+
+  getRecord(workspaceId: string, canvasId: string): CanvasRecord | undefined {
+    return this.options.canvasRepo.get(workspaceId, canvasId);
+  }
+
+  getRecordBySourcePath(workspaceId: string, sourcePath: string): CanvasRecord | undefined {
+    return this.options.canvasRepo
+      .list(workspaceId)
+      .find((record) => record.sourcePath === sourcePath);
+  }
+
+  async getCanvasData(input: {
+    workspaceId: string;
+    workspaceRootPath: string;
+    canvasId?: string;
+    sourcePath?: string;
+  }): Promise<CanvasDataResponse> {
+    const recordFromCanvasId = input.canvasId
+      ? this.options.canvasRepo.get(input.workspaceId, input.canvasId)
+      : undefined;
+    const sourcePath = input.sourcePath ?? recordFromCanvasId?.sourcePath;
+
+    if (!sourcePath) {
+      throw {
+        code: "canvas_not_found",
+        message: `Canvas not found: ${input.canvasId ?? input.sourcePath ?? "unknown"}`,
+      };
+    }
+
+    return this.readCanvasData({
+      workspaceId: input.workspaceId,
+      workspaceRootPath: input.workspaceRootPath,
+      sourcePath,
+      record:
+        input.sourcePath !== undefined
+          ? this.getRecordBySourcePath(input.workspaceId, sourcePath)
+          : (recordFromCanvasId ?? this.getRecordBySourcePath(input.workspaceId, sourcePath)),
+    });
+  }
+
+  async renderFromSourcePath(input: {
+    workspaceId: string;
+    workspaceRootPath: string;
+    sourcePath: string;
+  }): Promise<CanvasDataResponse> {
+    return this.getCanvasData(input);
+  }
+
+  private async readCanvasData(input: {
+    workspaceId: string;
+    workspaceRootPath: string;
+    sourcePath: string;
+    record?: CanvasRecord;
+  }): Promise<CanvasDataResponse> {
+    let sourceRead;
+    try {
+      sourceRead = await readFile(input.workspaceId, input.workspaceRootPath, input.sourcePath);
+    } catch (error) {
+      if (
+        (error as { code?: string }).code === "not_found" ||
+        (error as NodeJS.ErrnoException).code === "ENOENT"
+      ) {
+        throw {
+          code: "canvas_not_found",
+          message: `Canvas not found: ${input.sourcePath}`,
+        };
+      }
+      throw error;
+    }
+
+    if (sourceRead.kind !== "text") {
+      throw { code: "canvas_source_invalid", message: "Canvas source must be a text file" };
+    }
+
+    const validated = validateCanvasSource(sourceRead.content);
+    if (!validated.ok) {
+      const metadata = getCanvasErrorMetadata({
+        sourcePath: input.sourcePath,
+        sourceContent: sourceRead.content,
+        record: input.record,
+      });
+      const record = input.record
+        ? this.options.canvasRepo.upsert({
+            ...input.record,
+            title: metadata.title,
+            artifactType: metadata.kind,
+            updatedAt: this.now(),
+            renderStatus: "error",
+            lastError: validated.error,
+          })
+        : undefined;
+
+      return {
+        ...(record ? { canvasId: record.id } : {}),
+        workspaceId: input.workspaceId,
+        sourcePath: input.sourcePath,
+        title: record?.title ?? metadata.title,
+        kind: record?.artifactType ?? metadata.kind,
+        renderStatus: "error",
+        lastError: validated.error,
+      };
+    }
+
+    try {
+      const compiledDocument = compileCanvasDocument(validated.document);
+      const record = input.record
+        ? this.options.canvasRepo.upsert({
+            ...input.record,
+            title: validated.document.title,
+            artifactType: validated.document.kind,
+            updatedAt: this.now(),
+            renderStatus: "ready",
+            lastError: null,
+          })
+        : undefined;
+
+      return {
+        ...(record ? { canvasId: record.id } : {}),
+        workspaceId: input.workspaceId,
+        sourcePath: input.sourcePath,
+        title: record?.title ?? validated.document.title,
+        kind: record?.artifactType ?? validated.document.kind,
+        renderStatus: "ready",
+        lastError: null,
+        compiledDocument,
+      };
+    } catch (error) {
+      const lastError = normalizeCompileError(error);
+      const record = input.record
+        ? this.options.canvasRepo.upsert({
+            ...input.record,
+            title: validated.document.title,
+            artifactType: validated.document.kind,
+            updatedAt: this.now(),
+            renderStatus: "error",
+            lastError,
+          })
+        : undefined;
+
+      return {
+        ...(record ? { canvasId: record.id } : {}),
+        workspaceId: input.workspaceId,
+        sourcePath: input.sourcePath,
+        title: record?.title ?? validated.document.title,
+        kind: record?.artifactType ?? validated.document.kind,
+        renderStatus: "error",
+        lastError,
+      };
+    }
+  }
+}
+
+function getCanvasErrorMetadata(input: {
+  sourcePath: string;
+  sourceContent: string;
+  record?: CanvasRecord;
+}): {
+  title: string;
+  kind: CanvasArtifactKind;
+} {
+  if (input.record) {
+    return {
+      title: input.record.title,
+      kind: input.record.artifactType,
+    };
+  }
+
+  const parsed = tryParseCanvasMetadata(input.sourceContent);
+  return {
+    title: parsed?.title ?? deriveCanvasTitleFromSourcePath(input.sourcePath),
+    kind: parsed?.kind ?? "architecture_canvas",
+  };
+}
+
+function tryParseCanvasMetadata(sourceContent: string): {
+  title?: string;
+  kind?: CanvasArtifactKind;
+} | null {
+  try {
+    const parsed = JSON.parse(sourceContent) as Record<string, unknown>;
+    const title =
+      typeof parsed.title === "string" && parsed.title.trim() ? parsed.title.trim() : undefined;
+    const kind =
+      parsed.kind === "architecture_canvas" || parsed.kind === "report_canvas"
+        ? parsed.kind
+        : undefined;
+    return { title, kind };
+  } catch {
+    return null;
+  }
+}
+
+function deriveCanvasTitleFromSourcePath(sourcePath: string): string {
+  const fileName = basename(sourcePath).replace(/\.csc$/i, "");
+  const normalized = fileName.replace(/[-_]+/g, " ").trim();
+  return normalized || sourcePath;
+}
diff --git a/packages/server/src/canvas/source-path.test.ts b/packages/server/src/canvas/source-path.test.ts
new file mode 100644
index 000000000..bcc0cf77e
--- /dev/null
+++ b/packages/server/src/canvas/source-path.test.ts
@@ -0,0 +1,60 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createCanvasSourcePath, slugifyCanvasTitle } from "./source-path.js";
+
+describe("canvas source paths", () => {
+  let tempDir: string | undefined;
+
+  afterEach(() => {
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+      tempDir = undefined;
+    }
+  });
+
+  it("slugifies meaningful canvas titles into readable file names", () => {
+    expect(slugifyCanvasTitle("Runtime Request Flow")).toBe("runtime-request-flow");
+    expect(slugifyCanvasTitle(" Workspace Audit Summary ")).toBe("workspace-audit-summary");
+  });
+
+  it("avoids Windows-reserved file names", () => {
+    expect(slugifyCanvasTitle("CON")).toBe("con-canvas");
+    expect(slugifyCanvasTitle("LPT1")).toBe("lpt1-canvas");
+  });
+
+  it("truncates slugs to 80 characters and trims trailing hyphens after truncation", () => {
+    expect(slugifyCanvasTitle("a".repeat(81))).toBe("a".repeat(80));
+    expect(slugifyCanvasTitle(`${"a".repeat(79)} !!!`)).toBe("a".repeat(79));
+  });
+
+  it("allocates .csc file names and appends numeric suffixes on collision", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-source-path-"));
+    mkdirSync(join(tempDir, ".coder-studio", "canvases"), { recursive: true });
+    writeFileSync(join(tempDir, ".coder-studio", "canvases", "runtime-request-flow.csc"), "{}\n");
+
+    expect(
+      createCanvasSourcePath({
+        workspaceRootPath: tempDir,
+        title: "Runtime Request Flow",
+      })
+    ).toBe(".coder-studio/canvases/runtime-request-flow-2.csc");
+  });
+
+  it("throws when the title does not produce a valid slug", () => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-source-path-"));
+
+    expect(() =>
+      createCanvasSourcePath({
+        workspaceRootPath: tempDir,
+        title: "!!!",
+      })
+    ).toThrowErrorMatchingInlineSnapshot(`
+      {
+        "code": "invalid_canvas_title",
+        "message": "Canvas title must produce a valid file name",
+      }
+    `);
+  });
+});
diff --git a/packages/server/src/canvas/source-path.ts b/packages/server/src/canvas/source-path.ts
new file mode 100644
index 000000000..5b674d2e6
--- /dev/null
+++ b/packages/server/src/canvas/source-path.ts
@@ -0,0 +1,112 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileIfMissing } from "../fs/file-io.js";
+
+const CANVAS_SOURCE_DIR = ".coder-studio/canvases";
+const MAX_SLUG_LENGTH = 80;
+const WINDOWS_RESERVED_BASENAMES = new Set([
+  "con",
+  "prn",
+  "aux",
+  "nul",
+  "com1",
+  "com2",
+  "com3",
+  "com4",
+  "com5",
+  "com6",
+  "com7",
+  "com8",
+  "com9",
+  "lpt1",
+  "lpt2",
+  "lpt3",
+  "lpt4",
+  "lpt5",
+  "lpt6",
+  "lpt7",
+  "lpt8",
+  "lpt9",
+]);
+
+function trimEdgeHyphens(value: string): string {
+  return value.replace(/^-+|-+$/g, "");
+}
+
+function normalizeCanvasSlug(slug: string): string {
+  if (!slug) {
+    return slug;
+  }
+
+  if (WINDOWS_RESERVED_BASENAMES.has(slug)) {
+    return `${slug}-canvas`;
+  }
+
+  return slug;
+}
+
+function buildCanvasSourcePath(slug: string, attempt: number): string {
+  const fileName = attempt === 1 ? `${slug}.csc` : `${slug}-${attempt}.csc`;
+  return `${CANVAS_SOURCE_DIR}/${fileName}`;
+}
+
+export function slugifyCanvasTitle(title: string): string {
+  return normalizeCanvasSlug(
+    trimEdgeHyphens(
+      title
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .slice(0, MAX_SLUG_LENGTH)
+    )
+  );
+}
+
+function getValidatedCanvasSlug(title: string): string {
+  const slug = slugifyCanvasTitle(title);
+  if (!slug) {
+    throw {
+      code: "invalid_canvas_title",
+      message: "Canvas title must produce a valid file name",
+    };
+  }
+
+  return slug;
+}
+
+export function createCanvasSourcePath(input: {
+  workspaceRootPath: string;
+  title: string;
+}): string {
+  const slug = getValidatedCanvasSlug(input.title);
+
+  for (let attempt = 1; ; attempt += 1) {
+    const sourcePath = buildCanvasSourcePath(slug, attempt);
+    if (!existsSync(join(input.workspaceRootPath, sourcePath))) {
+      return sourcePath;
+    }
+  }
+}
+
+export async function writeNewCanvasSource(input: {
+  workspaceRootPath: string;
+  title: string;
+  content: string;
+}): Promise<string> {
+  const slug = getValidatedCanvasSlug(input.title);
+
+  for (let attempt = 1; ; attempt += 1) {
+    const sourcePath = buildCanvasSourcePath(slug, attempt);
+
+    try {
+      await writeFileIfMissing(input.workspaceRootPath, sourcePath, input.content);
+      return sourcePath;
+    } catch (error) {
+      if ((error as { code?: string }).code === "already_exists") {
+        continue;
+      }
+
+      throw error;
+    }
+  }
+}
diff --git a/packages/server/src/canvas/validation.test.ts b/packages/server/src/canvas/validation.test.ts
new file mode 100644
index 000000000..144deddc6
--- /dev/null
+++ b/packages/server/src/canvas/validation.test.ts
@@ -0,0 +1,175 @@
+import { describe, expect, it } from "vitest";
+import { validateCanvasSource } from "./validation.js";
+
+describe("validateCanvasSource", () => {
+  it("accepts a valid architecture canvas envelope", () => {
+    const result = validateCanvasSource(
+      JSON.stringify({
+        version: 1,
+        kind: "architecture_canvas",
+        title: "Runtime Flow",
+        document: {
+          summary: "How requests move.",
+          diagram: {
+            dsl: "mermaid",
+            source: ["WebUI[Web UI]", "Server[Runtime Server]", "WebUI -->|dispatch| Server"].join(
+              "\n"
+            ),
+          },
+          annotations: [{ title: "Boundary", body: "Server owns execution." }],
+        },
+      })
+    );
+
+    expect(result).toEqual({
+      ok: true,
+      document: expect.objectContaining({
+        kind: "architecture_canvas",
+        title: "Runtime Flow",
+      }),
+    });
+  });
+
+  it("accepts a valid report canvas envelope", () => {
+    const result = validateCanvasSource(
+      JSON.stringify({
+        version: 1,
+        kind: "report_canvas",
+        title: "Audit",
+        document: {
+          summary: "Workspace audit.",
+          stats: [{ label: "Packages", value: 6 }],
+          sections: [
+            {
+              title: "Findings",
+              blocks: [{ type: "markdown", markdown: "Server owns rendering." }],
+            },
+          ],
+        },
+      })
+    );
+
+    expect(result).toEqual({
+      ok: true,
+      document: expect.objectContaining({
+        kind: "report_canvas",
+        title: "Audit",
+      }),
+    });
+  });
+
+  it("reports a zod field path for invalid envelopes", () => {
+    const result = validateCanvasSource(
+      JSON.stringify({
+        version: 1,
+        kind: "architecture_canvas",
+        title: "Broken",
+        document: {
+          summary: "How requests move.",
+          diagram: {
+            dsl: "mermaid",
+            source: "",
+          },
+          annotations: [],
+        },
+      })
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        category: "validation_error",
+        message: expect.any(String),
+        fieldPath: "document.diagram.source",
+      },
+    });
+  });
+
+  it("blocks raw html-like strings in source fields", () => {
+    const result = validateCanvasSource(
+      JSON.stringify({
+        version: 1,
+        kind: "architecture_canvas",
+        title: "Broken",
+        document: {
+          summary: "How requests move.",
+          diagram: {
+            dsl: "mermaid",
+            source: "<div>WebUI[Web]</div>",
+          },
+          annotations: [],
+        },
+      })
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        category: "validation_error",
+        message: "Canvas source must not contain raw HTML",
+        fieldPath: "document.diagram.source",
+      },
+    });
+  });
+
+  it("rejects raw html-like strings in architecture summary fields", () => {
+    const result = validateCanvasSource(
+      JSON.stringify({
+        version: 1,
+        kind: "architecture_canvas",
+        title: "Broken",
+        document: {
+          summary: "<section>How requests move.</section>",
+          diagram: {
+            dsl: "mermaid",
+            source: "WebUI",
+          },
+          annotations: [],
+        },
+      })
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        category: "validation_error",
+        message: "Canvas source must not contain raw HTML",
+        fieldPath: "document.summary",
+      },
+    });
+  });
+
+  it("rejects raw html-like strings in report markdown blocks", () => {
+    const result = validateCanvasSource(
+      JSON.stringify({
+        version: 1,
+        kind: "report_canvas",
+        title: "Broken",
+        document: {
+          summary: "Workspace audit.",
+          stats: [],
+          sections: [
+            {
+              title: "Findings",
+              blocks: [
+                {
+                  type: "markdown",
+                  markdown: "<div>Server owns rendering.</div>",
+                },
+              ],
+            },
+          ],
+        },
+      })
+    );
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        category: "validation_error",
+        message: "Canvas source must not contain raw HTML",
+        fieldPath: "document.sections.0.blocks.0.markdown",
+      },
+    });
+  });
+});
diff --git a/packages/server/src/canvas/validation.ts b/packages/server/src/canvas/validation.ts
new file mode 100644
index 000000000..48c04bf36
--- /dev/null
+++ b/packages/server/src/canvas/validation.ts
@@ -0,0 +1,92 @@
+import {
+  type CanvasDocumentEnvelope,
+  CanvasDocumentEnvelopeSchema,
+  type CanvasRenderError,
+} from "@coder-studio/core";
+import { ZodError } from "zod";
+
+const HTML_LIKE_PATTERN = /<[a-z!/][^>]*>/iu;
+
+function findHtmlLikeStringField(value: unknown, path: string[] = []): string | null {
+  if (typeof value === "string") {
+    return HTML_LIKE_PATTERN.test(value) ? path.join(".") : null;
+  }
+
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) {
+      const result = findHtmlLikeStringField(item, [...path, String(index)]);
+      if (result) {
+        return result;
+      }
+    }
+    return null;
+  }
+
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = [...path, key];
+    const result = findHtmlLikeStringField(child, childPath);
+    if (result) {
+      return result;
+    }
+  }
+
+  return null;
+}
+
+export function validateCanvasSource(
+  source: string
+): { ok: true; document: CanvasDocumentEnvelope } | { ok: false; error: CanvasRenderError } {
+  try {
+    const parsedJson = JSON.parse(source) as unknown;
+    const htmlLikeFieldPath = findHtmlLikeStringField(parsedJson);
+    if (htmlLikeFieldPath) {
+      return {
+        ok: false,
+        error: {
+          category: "validation_error",
+          message: "Canvas source must not contain raw HTML",
+          fieldPath: htmlLikeFieldPath,
+        },
+      };
+    }
+
+    return {
+      ok: true,
+      document: CanvasDocumentEnvelopeSchema.parse(parsedJson),
+    };
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      return {
+        ok: false,
+        error: {
+          category: "validation_error",
+          message: error.message,
+        },
+      };
+    }
+
+    if (error instanceof ZodError) {
+      const issue = error.issues[0];
+      return {
+        ok: false,
+        error: {
+          category: "validation_error",
+          message: issue?.message ?? "Invalid canvas source",
+          fieldPath: issue?.path.join("."),
+        },
+      };
+    }
+
+    return {
+      ok: false,
+      error: {
+        category: "validation_error",
+        message: (error as Error).message || "Invalid canvas source",
+      },
+    };
+  }
+}
diff --git a/packages/server/src/commands/automation.ts b/packages/server/src/commands/automation.ts
index 4ed57ab20..45d3f4ee2 100644
--- a/packages/server/src/commands/automation.ts
+++ b/packages/server/src/commands/automation.ts
@@ -1,10 +1,37 @@
 import {
+  type AutomationPermission,
   buildIdentifyResult,
   DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
   listAutomationCapabilities,
 } from "@coder-studio/core";
 import { z } from "zod";
-import { registerCommand } from "../ws/dispatch.js";
+import { getSessionTokenRequestAuthContext, registerCommand } from "../ws/dispatch.js";
+
+function getEffectivePermissions(
+  requestedPermissions: readonly string[] | undefined,
+  ctx: Parameters<typeof registerCommand>[2] extends (
+    args: unknown,
+    ctx: infer T,
+    clientId?: string
+  ) => Promise<unknown>
+    ? T
+    : never,
+  clientId?: string
+): readonly string[] {
+  const authContext = getSessionTokenRequestAuthContext(ctx, clientId);
+  if (!authContext) {
+    return requestedPermissions ?? DEFAULT_AGENT_AUTOMATION_PERMISSIONS;
+  }
+
+  if (!requestedPermissions) {
+    return authContext.permissions;
+  }
+
+  const allowed = new Set<AutomationPermission>(authContext.permissions);
+  return requestedPermissions.filter((permission) =>
+    allowed.has(permission as AutomationPermission)
+  );
+}
 
 registerCommand(
   "automation.identify",
@@ -22,11 +49,11 @@ registerCommand(
   z.object({
     permissions: z.array(z.string()).optional(),
   }),
-  async (args) => {
+  async (args, ctx, clientId) => {
     return {
       version: 1,
       commands: listAutomationCapabilities({
-        permissions: args.permissions ?? DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
+        permissions: getEffectivePermissions(args.permissions, ctx, clientId),
       }),
     };
   }
diff --git a/packages/server/src/commands/canvas.test.ts b/packages/server/src/commands/canvas.test.ts
new file mode 100644
index 000000000..033cd50bd
--- /dev/null
+++ b/packages/server/src/commands/canvas.test.ts
@@ -0,0 +1,210 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Topics } from "@coder-studio/core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { CanvasService } from "../canvas/service.js";
+import { CanvasRepo } from "../storage/repositories/canvas-repo.js";
+import type { CommandContext } from "../ws/dispatch.js";
+import { dispatch } from "../ws/dispatch.js";
+import "./index.js";
+
+function command(op: string, args: unknown) {
+  return {
+    kind: "command" as const,
+    id: `${op}-test`,
+    op,
+    args,
+  };
+}
+
+describe("canvas commands", () => {
+  let tempDir: string;
+  let workspaceRoot: string;
+  let broadcast: ReturnType<typeof vi.fn>;
+  let ctx: CommandContext;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-command-"));
+    workspaceRoot = join(tempDir, "workspace");
+    mkdirSync(workspaceRoot, { recursive: true });
+    broadcast = vi.fn();
+
+    const canvasRepo = new CanvasRepo({
+      rootDir: join(tempDir, "state", "canvases"),
+    });
+    const canvasService = new CanvasService({
+      canvasRepo,
+      now: () => 1000,
+    });
+
+    ctx = {
+      workspaceMgr: {
+        get: vi.fn((workspaceId: string) =>
+          workspaceId === "ws-1" ? { id: "ws-1", path: workspaceRoot } : undefined
+        ),
+      },
+      sessionMgr: {} as never,
+      terminalMgr: {} as never,
+      taskMgr: {} as never,
+      eventBus: {} as never,
+      broadcaster: { broadcast } as never,
+      settingsRepo: {} as never,
+      providerConfigRepo: {} as never,
+      providerRegistry: [],
+      fencingMgr: {} as never,
+      supervisorMgr: {} as never,
+      autoFetch: {} as never,
+      activationMgr: {} as never,
+      lspMgr: {} as never,
+      canvasService,
+    };
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("creates, lists, updates, and renders canvases through the command layer", async () => {
+    const createResult = await dispatch(
+      command("canvas.create", {
+        workspaceId: "ws-1",
+        kind: "architecture_canvas",
+        title: "Runtime Flow",
+        openInEditor: true,
+        document: {
+          summary: "How requests move.",
+          diagram: {
+            dsl: "mermaid",
+            source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+          },
+          annotations: [],
+        },
+      }),
+      ctx
+    );
+
+    expect(createResult.ok).toBe(true);
+    const created = createResult.data as Awaited<ReturnType<CanvasService["create"]>>;
+    expect(created.record.title).toBe("Runtime Flow");
+    expect(created.renderStatus).toBe("ready");
+    expect(broadcast).toHaveBeenCalledWith(
+      Topics.workspaceUiAction("ws-1"),
+      expect.objectContaining({
+        workspaceId: "ws-1",
+        intent: expect.objectContaining({
+          type: "canvas.open",
+          workspaceId: "ws-1",
+          canvasId: created.record.id,
+          title: "Runtime Flow",
+          artifactType: "architecture_canvas",
+          sourcePath: created.record.sourcePath,
+        }),
+      })
+    );
+
+    const listResult = await dispatch(command("canvas.list", { workspaceId: "ws-1" }), ctx);
+    expect(listResult.ok).toBe(true);
+    expect(listResult.data).toEqual([created.record]);
+
+    const updateResult = await dispatch(
+      command("canvas.update", {
+        workspaceId: "ws-1",
+        canvasId: created.record.id,
+        title: "Recovered Canvas",
+        document: {
+          summary: "Recovered",
+          diagram: {
+            dsl: "mermaid",
+            source: "flowchart LR\nWebUI[Web UI] --> Server[Server]",
+          },
+          annotations: [],
+        },
+      }),
+      ctx
+    );
+
+    expect(updateResult.ok).toBe(true);
+    expect(updateResult.data).toMatchObject({
+      record: expect.objectContaining({
+        id: created.record.id,
+        title: "Recovered Canvas",
+        renderStatus: "ready",
+      }),
+      renderStatus: "ready",
+      lastError: null,
+    });
+
+    const renderResult = await dispatch(
+      command("canvas.render", {
+        workspaceId: "ws-1",
+        canvasId: created.record.id,
+      }),
+      ctx
+    );
+
+    expect(renderResult.ok).toBe(true);
+    expect(renderResult.data).toEqual({
+      canvasId: created.record.id,
+      sourcePath: created.record.sourcePath,
+      renderStatus: "ready",
+      lastError: null,
+    });
+  });
+
+  it("renders a canvas directly from sourcePath without requiring a repo record", async () => {
+    mkdirSync(join(workspaceRoot, ".coder-studio", "canvases"), { recursive: true });
+    const sourcePath = ".coder-studio/canvases/runtime-flow.csc";
+    writeFileSync(
+      join(workspaceRoot, sourcePath),
+      JSON.stringify(
+        {
+          version: 1,
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          document: {
+            summary: "How requests move.",
+            diagram: {
+              dsl: "mermaid",
+              source: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+            },
+            annotations: [],
+          },
+        },
+        null,
+        2
+      ) + "\n"
+    );
+
+    const renderResult = await dispatch(
+      command("canvas.render", {
+        workspaceId: "ws-1",
+        sourcePath,
+      }),
+      ctx
+    );
+
+    expect(renderResult.ok).toBe(true);
+    expect(renderResult.data).toEqual({
+      sourcePath,
+      renderStatus: "ready",
+      lastError: null,
+    });
+    await expect(ctx.canvasService?.list("ws-1")).resolves.toEqual([]);
+  });
+
+  it("returns canvas_not_found when a sourcePath does not exist", async () => {
+    const renderResult = await dispatch(
+      command("canvas.render", {
+        workspaceId: "ws-1",
+        sourcePath: ".coder-studio/canvases/missing-flow.csc",
+      }),
+      ctx
+    );
+
+    expect(renderResult.ok).toBe(false);
+    expect(renderResult.error).toMatchObject({
+      code: "canvas_not_found",
+    });
+  });
+});
diff --git a/packages/server/src/commands/canvas.ts b/packages/server/src/commands/canvas.ts
new file mode 100644
index 000000000..4a29cb781
--- /dev/null
+++ b/packages/server/src/commands/canvas.ts
@@ -0,0 +1,152 @@
+import { createUiActionEvent, Topics } from "@coder-studio/core";
+import { z } from "zod";
+import { type CommandContext, registerCommand } from "../ws/dispatch.js";
+
+function getWorkspaceOrThrow(ctx: CommandContext, workspaceId: string) {
+  const workspace = ctx.workspaceMgr.get(workspaceId);
+  if (!workspace) {
+    throw { code: "workspace_not_found", message: `Workspace not found: ${workspaceId}` };
+  }
+
+  return workspace;
+}
+
+function getCanvasServiceOrThrow(ctx: CommandContext) {
+  if (!ctx.canvasService) {
+    throw { code: "canvas_unavailable", message: "Canvas service is not available" };
+  }
+
+  return ctx.canvasService;
+}
+
+function broadcastCanvasOpen(
+  ctx: CommandContext,
+  input: {
+    workspaceId: string;
+    canvasId: string;
+    title: string;
+    artifactType: "architecture_canvas" | "report_canvas";
+    sourcePath: string;
+  }
+): void {
+  const event = createUiActionEvent({
+    request: {
+      intent: {
+        type: "canvas.open",
+        workspaceId: input.workspaceId,
+        canvasId: input.canvasId,
+        title: input.title,
+        artifactType: input.artifactType,
+        sourcePath: input.sourcePath,
+      },
+    },
+    workspaceId: input.workspaceId,
+    dispatchedAt: Date.now(),
+  });
+
+  ctx.broadcaster.broadcast(Topics.workspaceUiAction(input.workspaceId), event);
+}
+
+const canvasKindSchema = z.enum(["architecture_canvas", "report_canvas"]);
+
+registerCommand("canvas.list", z.object({ workspaceId: z.string() }), async (args, ctx) => {
+  getWorkspaceOrThrow(ctx, args.workspaceId);
+  return getCanvasServiceOrThrow(ctx).list(args.workspaceId);
+});
+
+registerCommand(
+  "canvas.create",
+  z.object({
+    workspaceId: z.string(),
+    sessionId: z.string().optional(),
+    kind: canvasKindSchema,
+    title: z.string(),
+    document: z.unknown(),
+    openInEditor: z.boolean().optional(),
+  }),
+  async (args, ctx) => {
+    const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+    const result = await getCanvasServiceOrThrow(ctx).create({
+      workspaceId: args.workspaceId,
+      workspaceRootPath: workspace.path,
+      sessionId: args.sessionId,
+      title: args.title,
+      kind: args.kind,
+      document: args.document,
+    });
+
+    if (args.openInEditor) {
+      broadcastCanvasOpen(ctx, {
+        workspaceId: args.workspaceId,
+        canvasId: result.record.id,
+        title: result.record.title,
+        artifactType: result.record.artifactType,
+        sourcePath: result.record.sourcePath,
+      });
+    }
+
+    return result;
+  }
+);
+
+registerCommand(
+  "canvas.update",
+  z.object({
+    workspaceId: z.string(),
+    canvasId: z.string(),
+    title: z.string().optional(),
+    document: z.unknown(),
+  }),
+  async (args, ctx) => {
+    const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+    return getCanvasServiceOrThrow(ctx).update({
+      workspaceId: args.workspaceId,
+      workspaceRootPath: workspace.path,
+      canvasId: args.canvasId,
+      title: args.title,
+      document: args.document,
+    });
+  }
+);
+
+registerCommand(
+  "canvas.render",
+  z
+    .object({
+      workspaceId: z.string(),
+      canvasId: z.string().optional(),
+      sourcePath: z.string().optional(),
+    })
+    .refine((value) => Boolean(value.canvasId || value.sourcePath), {
+      message: "canvasId or sourcePath is required",
+    }),
+  async (args, ctx) => {
+    const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+    const canvasService = getCanvasServiceOrThrow(ctx);
+    const sourcePath =
+      args.sourcePath ??
+      (args.canvasId
+        ? canvasService.getRecord(args.workspaceId, args.canvasId)?.sourcePath
+        : undefined);
+
+    if (!sourcePath) {
+      throw {
+        code: "canvas_not_found",
+        message: `Canvas not found: ${args.canvasId ?? args.sourcePath ?? "unknown"}`,
+      };
+    }
+
+    const result = await canvasService.getCanvasData({
+      workspaceId: args.workspaceId,
+      workspaceRootPath: workspace.path,
+      sourcePath,
+    });
+
+    return {
+      ...(result.canvasId ? { canvasId: result.canvasId } : {}),
+      sourcePath: result.sourcePath,
+      renderStatus: result.renderStatus,
+      lastError: result.lastError ?? null,
+    };
+  }
+);
diff --git a/packages/server/src/commands/file.ts b/packages/server/src/commands/file.ts
index e95ccee93..74955ad73 100644
--- a/packages/server/src/commands/file.ts
+++ b/packages/server/src/commands/file.ts
@@ -18,45 +18,51 @@ import {
   previewSearchSessionFile,
 } from "../fs/search-replace.js";
 import { readTree, searchFiles } from "../fs/tree.js";
-import { registerCommand } from "../ws/dispatch.js";
+import { registerRuntimeCommand } from "../runtime/command-registry.js";
 
 // file.readTree
-registerCommand(
+registerRuntimeCommand(
   "file.readTree",
   z.object({
     workspaceId: z.string(),
     subPath: z.string().optional(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    return readTree(workspace.path, args.subPath);
+      return readTree(workspace.path, args.subPath);
+    },
   }
 );
 
 // file.search
-registerCommand(
+registerRuntimeCommand(
   "file.search",
   z.object({
     workspaceId: z.string(),
     query: z.string(),
     limit: z.number().int().positive().max(50).optional(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    return searchFiles(workspace.path, args.query, args.limit ?? 10);
+      return searchFiles(workspace.path, args.query, args.limit ?? 10);
+    },
   }
 );
 
 // file.searchContent
-registerCommand(
+registerRuntimeCommand(
   "file.searchContent",
   z.object({
     workspaceId: z.string(),
@@ -64,39 +70,45 @@ registerCommand(
     maxFiles: z.number().int().positive().max(100),
     maxMatchesPerFile: z.number().int().positive().max(100),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    return searchFileContents(workspace.path, {
-      query: args.query,
-      maxFiles: args.maxFiles,
-      maxMatchesPerFile: args.maxMatchesPerFile,
-    });
+      return searchFileContents(workspace.path, {
+        query: args.query,
+        maxFiles: args.maxFiles,
+        maxMatchesPerFile: args.maxMatchesPerFile,
+      });
+    },
   }
 );
 
 // file.read
-registerCommand(
+registerRuntimeCommand(
   "file.read",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    return readWorkspaceFile(args.workspaceId, workspace.path, args.path);
+      return readWorkspaceFile(args.workspaceId, workspace.path, args.path);
+    },
   }
 );
 
 // file.searchSession.start
-registerCommand(
+registerRuntimeCommand(
   "file.searchSession.start",
   z.object({
     workspaceId: z.string(),
@@ -115,58 +127,64 @@ registerCommand(
     maxFiles: z.number().int().positive().max(100),
     maxMatchesPerFile: z.number().int().positive().max(100),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    const result = await createSearchSession(workspace.path, {
-      query: args.query,
-      replace: args.replace,
-      isRegex: args.isRegex,
-      matchCase: args.matchCase,
-      matchWholeWord: args.matchWholeWord,
-      preserveCase: args.preserveCase,
-      includeGlobs: args.includeGlobs,
-      excludeGlobs: args.excludeGlobs,
-      useIgnoreFiles: args.useIgnoreFiles,
-      useExcludeSettings: args.useExcludeSettings,
-      onlyOpenEditors: args.onlyOpenEditors,
-      openEditorPaths: args.openEditorPaths,
-      maxFiles: args.maxFiles,
-      maxMatchesPerFile: args.maxMatchesPerFile,
-    });
+      const result = await createSearchSession(workspace.path, {
+        query: args.query,
+        replace: args.replace,
+        isRegex: args.isRegex,
+        matchCase: args.matchCase,
+        matchWholeWord: args.matchWholeWord,
+        preserveCase: args.preserveCase,
+        includeGlobs: args.includeGlobs,
+        excludeGlobs: args.excludeGlobs,
+        useIgnoreFiles: args.useIgnoreFiles,
+        useExcludeSettings: args.useExcludeSettings,
+        onlyOpenEditors: args.onlyOpenEditors,
+        openEditorPaths: args.openEditorPaths,
+        maxFiles: args.maxFiles,
+        maxMatchesPerFile: args.maxMatchesPerFile,
+      });
 
-    return result.result;
+      return result.result;
+    },
   }
 );
 
 // file.searchSession.previewFile
-registerCommand(
+registerRuntimeCommand(
   "file.searchSession.previewFile",
   z.object({
     workspaceId: z.string(),
     sessionId: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    const result = await previewSearchSessionFile(workspace.path, args.sessionId, args.path);
-    if (!result) {
-      throw { code: "stale_session", message: "Search session is stale or missing" };
-    }
+      const result = await previewSearchSessionFile(workspace.path, args.sessionId, args.path);
+      if (!result) {
+        throw { code: "stale_session", message: "Search session is stale or missing" };
+      }
 
-    return result;
+      return result;
+    },
   }
 );
 
 // file.searchSession.apply
-registerCommand(
+registerRuntimeCommand(
   "file.searchSession.apply",
   z.object({
     workspaceId: z.string(),
@@ -177,120 +195,135 @@ registerCommand(
       z.object({ kind: z.literal("match"), path: z.string(), matchId: z.string() }),
     ]),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    const result = await applySearchSession(workspace.path, args.sessionId, args.scope);
-    if (result.status === "ok" || result.status === "partial") {
-      ctx.eventBus.emit({
-        type: "fs.dirty",
-        workspaceId: args.workspaceId,
-        reason: "file_content",
-      });
-    }
+      const result = await applySearchSession(workspace.path, args.sessionId, args.scope);
+      if (result.status === "ok" || result.status === "partial") {
+        ctx.eventBus.emit({
+          type: "fs.dirty",
+          workspaceId: args.workspaceId,
+          reason: "file_content",
+        });
+      }
 
-    return result;
+      return result;
+    },
   }
 );
 
 // file.create
-registerCommand(
+registerRuntimeCommand(
   "file.create",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    await createFile(workspace.path, args.path);
-    ctx.eventBus.emit({
-      type: "fs.dirty",
-      workspaceId: args.workspaceId,
-      reason: "fs_change",
-    });
-    return { ok: true };
+      await createFile(workspace.path, args.path);
+      ctx.eventBus.emit({
+        type: "fs.dirty",
+        workspaceId: args.workspaceId,
+        reason: "fs_change",
+      });
+      return { ok: true };
+    },
   }
 );
 
 // file.mkdir
-registerCommand(
+registerRuntimeCommand(
   "file.mkdir",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    await createDirectory(workspace.path, args.path);
-    ctx.eventBus.emit({
-      type: "fs.dirty",
-      workspaceId: args.workspaceId,
-      reason: "fs_change",
-    });
-    return { ok: true };
+      await createDirectory(workspace.path, args.path);
+      ctx.eventBus.emit({
+        type: "fs.dirty",
+        workspaceId: args.workspaceId,
+        reason: "fs_change",
+      });
+      return { ok: true };
+    },
   }
 );
 
 // file.delete
-registerCommand(
+registerRuntimeCommand(
   "file.delete",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    await deleteEntry(workspace.path, args.path);
-    ctx.eventBus.emit({
-      type: "fs.dirty",
-      workspaceId: args.workspaceId,
-      reason: "fs_change",
-    });
-    return { ok: true };
+      await deleteEntry(workspace.path, args.path);
+      ctx.eventBus.emit({
+        type: "fs.dirty",
+        workspaceId: args.workspaceId,
+        reason: "fs_change",
+      });
+      return { ok: true };
+    },
   }
 );
 
 // file.rename
-registerCommand(
+registerRuntimeCommand(
   "file.rename",
   z.object({
     workspaceId: z.string(),
     fromPath: z.string(),
     toPath: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    await renameEntry(workspace.path, args.fromPath, args.toPath);
-    ctx.eventBus.emit({
-      type: "fs.dirty",
-      workspaceId: args.workspaceId,
-      reason: "fs_change",
-    });
-    return { ok: true };
+      await renameEntry(workspace.path, args.fromPath, args.toPath);
+      ctx.eventBus.emit({
+        type: "fs.dirty",
+        workspaceId: args.workspaceId,
+        reason: "fs_change",
+      });
+      return { ok: true };
+    },
   }
 );
 
 // file.write
-registerCommand(
+registerRuntimeCommand(
   "file.write",
   z.object({
     workspaceId: z.string(),
@@ -298,18 +331,26 @@ registerCommand(
     content: z.string(),
     baseHash: z.string().optional(), // For conflict detection
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    const result = await writeWorkspaceFile(workspace.path, args.path, args.content, args.baseHash);
-    ctx.eventBus.emit({
-      type: "fs.dirty",
-      workspaceId: args.workspaceId,
-      reason: "file_content",
-    });
-    return result;
+      const result = await writeWorkspaceFile(
+        workspace.path,
+        args.path,
+        args.content,
+        args.baseHash
+      );
+      ctx.eventBus.emit({
+        type: "fs.dirty",
+        workspaceId: args.workspaceId,
+        reason: "file_content",
+      });
+      return result;
+    },
   }
 );
diff --git a/packages/server/src/commands/git.ts b/packages/server/src/commands/git.ts
index eb48eff41..54eb4e280 100644
--- a/packages/server/src/commands/git.ts
+++ b/packages/server/src/commands/git.ts
@@ -22,8 +22,8 @@ import {
 import { getFileDiff } from "../git/diff.js";
 import { getGitCommitDetail, getGitCommitFileDiff } from "../git/history.js";
 import { applyGitHunkOperation } from "../git/hunk-operations.js";
-import type { CommandContext } from "../ws/dispatch.js";
-import { registerCommand } from "../ws/dispatch.js";
+import { registerRuntimeCommand } from "../runtime/command-registry.js";
+import type { RuntimeCommandContext } from "../runtime/context.js";
 import { emitGitStateChanged } from "./git-events.js";
 
 const gitHttpAuthSchema = z.object({
@@ -44,73 +44,83 @@ function debugGitHistoryCommand(message: string, details?: Record<string, unknow
   console.log("[git-history]", message, details);
 }
 
+function getWorkspaceOrThrow(ctx: RuntimeCommandContext, workspaceId: string) {
+  const workspace = ctx.workspaceLookup.get(workspaceId);
+  if (!workspace) {
+    throw { code: "workspace_not_found", message: `Workspace not found: ${workspaceId}` };
+  }
+  return workspace;
+}
+
 async function runGitNetworkOperation<T>(
-  ctx: CommandContext,
+  ctx: RuntimeCommandContext,
   workspaceId: string,
   op: () => Promise<T>
 ): Promise<T> {
-  if (!ctx.autoFetch?.runExclusive) {
+  const autoFetch = (
+    ctx as unknown as {
+      autoFetch?: { runExclusive?<R>(workspaceId: string, op: () => Promise<R>): Promise<R> };
+    }
+  ).autoFetch;
+  if (!autoFetch?.runExclusive) {
     return op();
   }
 
-  return ctx.autoFetch.runExclusive(workspaceId, op);
+  return autoFetch.runExclusive(workspaceId, op);
+}
+
+function workspaceTarget(workspaceId: string) {
+  return { kind: "workspace" as const, workspaceId };
 }
 
-// git.status
-registerCommand(
+registerRuntimeCommand(
   "git.status",
   z.object({
     workspaceId: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    return getGitStatus(workspace.path);
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      return getGitStatus(workspace.path);
+    },
   }
 );
 
-// git.stage
-registerCommand(
+registerRuntimeCommand(
   "git.stage",
   z.object({
     workspaceId: z.string(),
     paths: z.array(z.string()),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    await stageFiles(workspace.path, args.paths);
-    emitGitStateChanged(ctx, args.workspaceId);
-    return {};
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      await stageFiles(workspace.path, args.paths);
+      emitGitStateChanged(ctx as never, args.workspaceId);
+      return {};
+    },
   }
 );
 
-// git.diff
-registerCommand(
+registerRuntimeCommand(
   "git.diff",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
     staged: z.boolean().optional(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    return getFileDiff(workspace.path, args.path, args.staged ?? false);
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      return getFileDiff(workspace.path, args.path, args.staged ?? false);
+    },
   }
 );
 
-// git.hunk
-registerCommand(
+registerRuntimeCommand(
   "git.hunk",
   z.object({
     workspaceId: z.string(),
@@ -119,96 +129,89 @@ registerCommand(
     hunkId: z.string(),
     operation: z.enum(["stage", "unstage", "discard"]),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    await applyGitHunkOperation(workspace.path, args);
-    emitGitStateChanged(ctx, args.workspaceId, {
-      worktreeChanged: true,
-    });
-    return {};
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      await applyGitHunkOperation(workspace.path, args);
+      emitGitStateChanged(ctx as never, args.workspaceId, {
+        worktreeChanged: true,
+      });
+      return {};
+    },
   }
 );
 
-// git.log
-registerCommand(
+registerRuntimeCommand(
   "git.log",
   z.object({
     workspaceId: z.string(),
     limit: z.number().int().min(1).max(50).optional(),
     afterSha: gitCommitRevisionSchema.optional(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    debugGitHistoryCommand("command git.log request", {
-      workspaceId: args.workspaceId,
-      workspacePath: workspace.path,
-      limit: args.limit ?? 5,
-      afterSha: args.afterSha,
-    });
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+
+      debugGitHistoryCommand("command git.log request", {
+        workspaceId: args.workspaceId,
+        workspacePath: workspace.path,
+        limit: args.limit ?? 5,
+        afterSha: args.afterSha,
+      });
 
-    const history = await getGitHistory(workspace.path, {
-      limit: args.limit ?? 5,
-      afterSha: args.afterSha,
-    });
+      const history = await getGitHistory(workspace.path, {
+        limit: args.limit ?? 5,
+        afterSha: args.afterSha,
+      });
 
-    debugGitHistoryCommand("command git.log response", {
-      workspaceId: args.workspaceId,
-      entryCount: history.entries.length,
-      hasMore: history.hasMore,
-      firstSha: history.entries[0]?.sha,
-      lastSha: history.entries.at(-1)?.sha,
-    });
+      debugGitHistoryCommand("command git.log response", {
+        workspaceId: args.workspaceId,
+        entryCount: history.entries.length,
+        hasMore: history.hasMore,
+        firstSha: history.entries[0]?.sha,
+        lastSha: history.entries.at(-1)?.sha,
+      });
 
-    return history;
+      return history;
+    },
   }
 );
 
-// git.show
-registerCommand(
+registerRuntimeCommand(
   "git.show",
   z.object({
     workspaceId: z.string(),
     sha: gitCommitRevisionSchema,
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    return {
-      diff: await getGitCommitDiff(workspace.path, args.sha),
-    };
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      return {
+        diff: await getGitCommitDiff(workspace.path, args.sha),
+      };
+    },
   }
 );
 
-// git.commitDetail
-registerCommand(
+registerRuntimeCommand(
   "git.commitDetail",
   z.object({
     workspaceId: z.string(),
     sha: gitCommitRevisionSchema,
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    return getGitCommitDetail(workspace.path, args.sha);
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      return getGitCommitDetail(workspace.path, args.sha);
+    },
   }
 );
 
-// git.commitFileDiff
-registerCommand(
+registerRuntimeCommand(
   "git.commitFileDiff",
   z.object({
     workspaceId: z.string(),
@@ -216,80 +219,72 @@ registerCommand(
     path: z.string(),
     oldPath: z.string().optional(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    return getGitCommitFileDiff(workspace.path, args);
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      return getGitCommitFileDiff(workspace.path, args);
+    },
   }
 );
 
-// git.unstage
-registerCommand(
+registerRuntimeCommand(
   "git.unstage",
   z.object({
     workspaceId: z.string(),
     paths: z.array(z.string()),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    await unstageFiles(workspace.path, args.paths);
-    emitGitStateChanged(ctx, args.workspaceId);
-    return {};
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      await unstageFiles(workspace.path, args.paths);
+      emitGitStateChanged(ctx as never, args.workspaceId);
+      return {};
+    },
   }
 );
 
-// git.discard
-registerCommand(
+registerRuntimeCommand(
   "git.discard",
   z.object({
     workspaceId: z.string(),
     paths: z.array(z.string()),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    await discardChanges(workspace.path, args.paths);
-    emitGitStateChanged(ctx, args.workspaceId, {
-      treeChanged: true,
-    });
-    return {};
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      await discardChanges(workspace.path, args.paths);
+      emitGitStateChanged(ctx as never, args.workspaceId, {
+        treeChanged: true,
+      });
+      return {};
+    },
   }
 );
 
-// git.commit
-registerCommand(
+registerRuntimeCommand(
   "git.commit",
   z.object({
     workspaceId: z.string(),
     message: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    const result = await commitChanges(workspace.path, args.message);
-    emitGitStateChanged(ctx, args.workspaceId, {
-      branchChanged: true,
-      worktreeChanged: true,
-    });
-    return result;
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      const result = await commitChanges(workspace.path, args.message);
+      emitGitStateChanged(ctx as never, args.workspaceId, {
+        branchChanged: true,
+        worktreeChanged: true,
+      });
+      return result;
+    },
   }
 );
 
-// git.push
-registerCommand(
+registerRuntimeCommand(
   "git.push",
   z.object({
     workspaceId: z.string(),
@@ -298,30 +293,28 @@ registerCommand(
     force: z.boolean().optional(),
     auth: gitHttpAuthSchema.optional(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    const result = await runGitNetworkOperation(ctx, args.workspaceId, () =>
-      runGitPush(workspace.path, {
-        remote: args.remote,
-        branch: args.branch,
-        force: args.force,
-        auth: args.auth,
-      })
-    );
-    emitGitStateChanged(ctx, args.workspaceId, {
-      branchChanged: true,
-      worktreeChanged: true,
-    });
-    return result;
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      const result = await runGitNetworkOperation(ctx, args.workspaceId, () =>
+        runGitPush(workspace.path, {
+          remote: args.remote,
+          branch: args.branch,
+          force: args.force,
+          auth: args.auth,
+        })
+      );
+      emitGitStateChanged(ctx as never, args.workspaceId, {
+        branchChanged: true,
+        worktreeChanged: true,
+      });
+      return result;
+    },
   }
 );
 
-// git.pull
-registerCommand(
+registerRuntimeCommand(
   "git.pull",
   z.object({
     workspaceId: z.string(),
@@ -329,31 +322,29 @@ registerCommand(
     branch: z.string().optional(),
     auth: gitHttpAuthSchema.optional(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    const result = await runGitNetworkOperation(ctx, args.workspaceId, () =>
-      runGitPull(workspace.path, {
-        remote: args.remote,
-        branch: args.branch,
-        auth: args.auth,
-      })
-    );
-    ctx.workspaceMgr.recordFetch(args.workspaceId);
-    emitGitStateChanged(ctx, args.workspaceId, {
-      treeChanged: true,
-      branchChanged: true,
-      worktreeChanged: true,
-    });
-    return result;
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      const result = await runGitNetworkOperation(ctx, args.workspaceId, () =>
+        runGitPull(workspace.path, {
+          remote: args.remote,
+          branch: args.branch,
+          auth: args.auth,
+        })
+      );
+      ctx.hostBridge.recordWorkspaceFetch?.(args.workspaceId);
+      emitGitStateChanged(ctx as never, args.workspaceId, {
+        treeChanged: true,
+        branchChanged: true,
+        worktreeChanged: true,
+      });
+      return result;
+    },
   }
 );
 
-// git.fetch
-registerCommand(
+registerRuntimeCommand(
   "git.fetch",
   z.object({
     workspaceId: z.string(),
@@ -362,104 +353,95 @@ registerCommand(
     auth: gitHttpAuthSchema.optional(),
     background: z.boolean().optional(),
   }),
-  async (args, ctx, clientId) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    try {
-      // AutoFetchScheduler already holds the per-workspace lock before it
-      // dispatches an internal background fetch. Client-originated requests
-      // must still serialize through the shared network-operation gate.
-      const isInternalBackgroundFetch = args.background === true && !clientId;
-      const runFetch = () =>
-        runGitFetch(workspace.path, {
-          remote: args.remote,
-          prune: args.prune,
-          auth: args.auth,
-          timeoutMs: args.background ? GIT_BACKGROUND_FETCH_TIMEOUT_MS : undefined,
-        });
-      const result = isInternalBackgroundFetch
-        ? await runFetch()
-        : await runGitNetworkOperation(ctx, args.workspaceId, runFetch);
-      ctx.workspaceMgr.recordFetch(args.workspaceId);
-      emitGitStateChanged(ctx, args.workspaceId, { branchChanged: true });
-      return result;
-    } catch (err) {
-      if (args.background && err instanceof GitAuthError) {
-        return { success: false, message: err.message, updatedRefs: [] };
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx, meta) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+
+      try {
+        const isInternalBackgroundFetch = args.background === true && !meta?.clientId;
+        const runFetch = () =>
+          runGitFetch(workspace.path, {
+            remote: args.remote,
+            prune: args.prune,
+            auth: args.auth,
+            timeoutMs: args.background ? GIT_BACKGROUND_FETCH_TIMEOUT_MS : undefined,
+          });
+        const result = isInternalBackgroundFetch
+          ? await runFetch()
+          : await runGitNetworkOperation(ctx, args.workspaceId, runFetch);
+        ctx.hostBridge.recordWorkspaceFetch?.(args.workspaceId);
+        emitGitStateChanged(ctx as never, args.workspaceId, { branchChanged: true });
+        return result;
+      } catch (err) {
+        if (args.background && err instanceof GitAuthError) {
+          return { success: false, message: err.message, updatedRefs: [] };
+        }
+        throw err;
       }
-      throw err;
-    }
+    },
   }
 );
 
-// git.checkout
-registerCommand(
+registerRuntimeCommand(
   "git.checkout",
   z.object({
     workspaceId: z.string(),
     ref: z.string(),
     createBranch: z.boolean().optional(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    const result = await runGitCheckout(workspace.path, args.ref, {
-      createBranch: args.createBranch,
-    });
-    if (result.success) {
-      emitGitStateChanged(ctx, args.workspaceId, {
-        treeChanged: true,
-        branchChanged: true,
-        worktreeChanged: true,
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      const result = await runGitCheckout(workspace.path, args.ref, {
+        createBranch: args.createBranch,
       });
-    }
-    return result;
+      if (result.success) {
+        emitGitStateChanged(ctx as never, args.workspaceId, {
+          treeChanged: true,
+          branchChanged: true,
+          worktreeChanged: true,
+        });
+      }
+      return result;
+    },
   }
 );
 
-// git.branch
-registerCommand(
+registerRuntimeCommand(
   "git.branch",
   z.object({
     workspaceId: z.string(),
     name: z.string(),
     startPoint: z.string().optional(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    const result = await runGitCreateBranch(workspace.path, args.name, {
-      startPoint: args.startPoint,
-    });
-    emitGitStateChanged(ctx, args.workspaceId, {
-      branchChanged: true,
-      worktreeChanged: true,
-    });
-    return result;
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      const result = await runGitCreateBranch(workspace.path, args.name, {
+        startPoint: args.startPoint,
+      });
+      emitGitStateChanged(ctx as never, args.workspaceId, {
+        branchChanged: true,
+        worktreeChanged: true,
+      });
+      return result;
+    },
   }
 );
 
-// git.branches
-registerCommand(
+registerRuntimeCommand(
   "git.branches",
   z.object({
     workspaceId: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    return runGitListBranches(workspace.path);
+  {
+    resolveTarget: (args) => workspaceTarget(args.workspaceId),
+    handler: async (args, ctx) => {
+      const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+      return runGitListBranches(workspace.path);
+    },
   }
 );
diff --git a/packages/server/src/commands/index.ts b/packages/server/src/commands/index.ts
index e7eb49481..1e93f8942 100644
--- a/packages/server/src/commands/index.ts
+++ b/packages/server/src/commands/index.ts
@@ -1,13 +1,16 @@
 /**
  * Command handlers
  *
- * This file imports all command handlers to register them with the dispatch system.
+ * Imported for side effects so handlers register with the dispatch registry.
+ * The explicit registration functions are phase-1 bootstrap affordances that
+ * currently preserve this static behavior.
  */
 
 import "./workspace.js";
 import "./workspace-activity.js";
 import "./automation.js";
 import "./ui-actions.js";
+import "./canvas.js";
 import "./activation.js";
 import "./connection.js";
 import "./recovery.js";
@@ -34,3 +37,12 @@ import "./updates.js";
 import "./monitoring.js";
 import "./work-analysis.js";
 import "./memory.js";
+
+export async function registerHostCommands(): Promise<void> {}
+
+export async function registerRuntimeCommands(): Promise<void> {}
+
+export async function registerAllCommands(): Promise<void> {
+  await registerHostCommands();
+  await registerRuntimeCommands();
+}
diff --git a/packages/server/src/commands/lsp.ts b/packages/server/src/commands/lsp.ts
index c6184c15e..53b34d11f 100644
--- a/packages/server/src/commands/lsp.ts
+++ b/packages/server/src/commands/lsp.ts
@@ -1,110 +1,125 @@
 import { z } from "zod";
 import { buildLspRuntimeStatus } from "../lsp-tools/runtime-status.js";
-import { registerCommand } from "../ws/dispatch.js";
+import { registerRuntimeCommand } from "../runtime/command-registry.js";
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.ensureSession",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => ctx.lspMgr.ensureSession(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.ensureSession(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.setMode",
   z.object({
     mode: z.enum(["auto", "off"]),
   }),
-  async (args, ctx) => {
-    await ctx.lspMgr.setRuntimeMode(args.mode);
-    return { mode: ctx.lspMgr.getRuntimeMode() };
+  {
+    resolveTarget: () => ({ kind: "default" }),
+    handler: async (args, ctx) => {
+      await ctx.lspMgr.setRuntimeMode(args.mode);
+      return { mode: ctx.lspMgr.getRuntimeMode() };
+    },
   }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.runtimeStatus",
   z.object({
     workspaceId: z.string(),
   }),
-  async (args, ctx) => {
-    if (!ctx.lspToolMgr) {
-      throw {
-        code: "lsp_tool_manager_unavailable",
-        message: "LSP tool manager not configured",
-      };
-    }
-
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw {
-        code: "workspace_not_found",
-        message: `Workspace not found: ${args.workspaceId}`,
-      };
-    }
-
-    return buildLspRuntimeStatus({
-      workspace,
-      lspToolMgr: ctx.lspToolMgr,
-    });
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      if (!ctx.lspToolMgr) {
+        throw {
+          code: "lsp_tool_manager_unavailable",
+          message: "LSP tool manager not configured",
+        };
+      }
+
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw {
+          code: "workspace_not_found",
+          message: `Workspace not found: ${args.workspaceId}`,
+        };
+      }
+
+      return buildLspRuntimeStatus({
+        workspace: workspace as never,
+        lspToolMgr: ctx.lspToolMgr,
+      });
+    },
   }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.install.start",
   z.object({
     workspaceId: z.string(),
     serverKind: z.enum(["typescript", "python", "go", "rust", "vue"]),
   }),
-  async (args, ctx) => {
-    if (!ctx.lspToolInstallMgr) {
-      throw {
-        code: "lsp_install_unavailable",
-        message: "LSP install manager not configured",
-      };
-    }
-
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw {
-        code: "workspace_not_found",
-        message: `Workspace not found: ${args.workspaceId}`,
-      };
-    }
-
-    return ctx.lspToolInstallMgr.start({
-      workspace,
-      serverKind: args.serverKind,
-    });
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      if (!ctx.lspToolInstallMgr) {
+        throw {
+          code: "lsp_install_unavailable",
+          message: "LSP install manager not configured",
+        };
+      }
+
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw {
+          code: "workspace_not_found",
+          message: `Workspace not found: ${args.workspaceId}`,
+        };
+      }
+
+      return ctx.lspToolInstallMgr.start({
+        workspace: workspace as never,
+        serverKind: args.serverKind,
+      });
+    },
   }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.install.get",
   z.object({
     jobId: z.string(),
   }),
-  async (args, ctx) => {
-    if (!ctx.lspToolInstallMgr) {
-      throw {
-        code: "lsp_install_unavailable",
-        message: "LSP install manager not configured",
-      };
-    }
-
-    const job = ctx.lspToolInstallMgr.get(args.jobId);
-    if (!job) {
-      throw {
-        code: "lsp_install_job_not_found",
-        message: `Install job not found: ${args.jobId}`,
-      };
-    }
-
-    return job;
+  {
+    resolveTarget: () => ({ kind: "default" }),
+    handler: async (args, ctx) => {
+      if (!ctx.lspToolInstallMgr) {
+        throw {
+          code: "lsp_install_unavailable",
+          message: "LSP install manager not configured",
+        };
+      }
+
+      const job = ctx.lspToolInstallMgr.get(args.jobId);
+      if (!job) {
+        throw {
+          code: "lsp_install_job_not_found",
+          message: `Install job not found: ${args.jobId}`,
+        };
+      }
+
+      return job;
+    },
   }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.openDocument",
   z.object({
     workspaceId: z.string(),
@@ -112,29 +127,38 @@ registerCommand(
     languageId: z.string(),
     text: z.string(),
   }),
-  async (args, ctx) => ctx.lspMgr.openDocument(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.openDocument(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.changeDocument",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
     text: z.string(),
   }),
-  async (args, ctx) => ctx.lspMgr.changeDocument(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.changeDocument(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.closeDocument",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => ctx.lspMgr.closeDocument(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.closeDocument(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.definition",
   z.object({
     workspaceId: z.string(),
@@ -142,10 +166,13 @@ registerCommand(
     line: z.number().int().positive(),
     column: z.number().int().positive(),
   }),
-  async (args, ctx) => ctx.lspMgr.definition(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.definition(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.declaration",
   z.object({
     workspaceId: z.string(),
@@ -153,10 +180,13 @@ registerCommand(
     line: z.number().int().positive(),
     column: z.number().int().positive(),
   }),
-  async (args, ctx) => ctx.lspMgr.declaration(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.declaration(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.typeDefinition",
   z.object({
     workspaceId: z.string(),
@@ -164,10 +194,13 @@ registerCommand(
     line: z.number().int().positive(),
     column: z.number().int().positive(),
   }),
-  async (args, ctx) => ctx.lspMgr.typeDefinition(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.typeDefinition(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.references",
   z.object({
     workspaceId: z.string(),
@@ -175,10 +208,13 @@ registerCommand(
     line: z.number().int().positive(),
     column: z.number().int().positive(),
   }),
-  async (args, ctx) => ctx.lspMgr.references(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.references(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.hover",
   z.object({
     workspaceId: z.string(),
@@ -186,23 +222,32 @@ registerCommand(
     line: z.number().int().positive(),
     column: z.number().int().positive(),
   }),
-  async (args, ctx) => ctx.lspMgr.hover(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.hover(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.documentSymbols",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => ctx.lspMgr.documentSymbols(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.documentSymbols(args),
+  }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "lsp.semanticTokens",
   z.object({
     workspaceId: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => ctx.lspMgr.semanticTokens(args)
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => ctx.lspMgr.semanticTokens(args),
+  }
 );
diff --git a/packages/server/src/commands/memory.test.ts b/packages/server/src/commands/memory.test.ts
index f2f9246aa..b75a903d0 100644
--- a/packages/server/src/commands/memory.test.ts
+++ b/packages/server/src/commands/memory.test.ts
@@ -63,7 +63,7 @@ describe("memory commands", () => {
     const createdResult = await dispatch(
       command("memory.create", {
         workspaceId: "ws-1",
-        type: "project",
+        type: "wiki",
         content: "Keep durable context outside the Git workspace.",
         sourceHint: {
           kind: "skill",
@@ -79,7 +79,7 @@ describe("memory commands", () => {
     expect(created).toEqual({
       id: "mem_1779120000000_r1",
       workspaceId: "ws-1",
-      type: "project",
+      type: "wiki",
       content: "Keep durable context outside the Git workspace.",
       source: {
         kind: "skill",
@@ -101,12 +101,19 @@ describe("memory commands", () => {
     });
     expect(persistedRepo.get("ws-1", created.id)).toEqual(created);
 
+    const legacyTypeListResult = await dispatch(
+      command("memory.list", { workspaceId: "ws-1", type: "project" }),
+      ctx
+    );
+    expect(legacyTypeListResult.ok).toBe(true);
+    expect(legacyTypeListResult.data).toEqual([created]);
+
     const listResult = await dispatch(command("memory.list", { workspaceId: "ws-1" }), ctx);
     expect(listResult.ok).toBe(true);
     expect(listResult.data).toEqual([created]);
 
     const typeSearchResult = await dispatch(
-      command("memory.search", { workspaceId: "ws-1", query: "PROJECT" }),
+      command("memory.search", { workspaceId: "ws-1", query: "wiki" }),
       ctx
     );
     expect(typeSearchResult.ok).toBe(true);
@@ -223,7 +230,7 @@ describe("memory commands", () => {
     expect(searchResult.data).toEqual([]);
 
     now += 1000;
-    const createResult = await dispatch(
+    const projectCreateResult = await dispatch(
       command("memory.create", {
         workspaceId,
         type: "project",
@@ -231,35 +238,197 @@ describe("memory commands", () => {
       }),
       ctx
     );
-    expect(createResult.ok).toBe(true);
-    const created = createResult.data as WorkspaceMemoryEntry;
-    expect(created).toEqual({
+    expect(projectCreateResult.ok).toBe(true);
+    const projectCreated = projectCreateResult.data as WorkspaceMemoryEntry;
+    expect(projectCreated).toEqual({
       id: "mem_1779120001000_r1",
       workspaceId,
-      type: "project",
+      type: "wiki",
       content: "Persist only project-shaped memory records.",
       source: { kind: "user" },
       createdAt: now,
       updatedAt: now,
     });
 
+    now += 1000;
+    const bugfixCreateResult = await dispatch(
+      command("memory.create", {
+        workspaceId,
+        type: "bugfix",
+        status: "pending_verification",
+        content: "Persist only bugfix-shaped memory records.",
+      }),
+      ctx
+    );
+    expect(bugfixCreateResult.ok).toBe(true);
+    const bugfixCreated = bugfixCreateResult.data as WorkspaceMemoryEntry;
+    expect(bugfixCreated).toEqual({
+      id: "mem_1779120002000_r2",
+      workspaceId,
+      type: "issue",
+      status: "pending_verification",
+      content: "Persist only bugfix-shaped memory records.",
+      source: { kind: "user" },
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    now += 1000;
+    const featureCreateResult = await dispatch(
+      command("memory.create", {
+        workspaceId,
+        type: "feature",
+        content: "Persist only feature-shaped memory records.",
+      }),
+      ctx
+    );
+    expect(featureCreateResult.ok).toBe(true);
+    const featureCreated = featureCreateResult.data as WorkspaceMemoryEntry;
+    expect(featureCreated).toEqual({
+      id: "mem_1779120003000_r3",
+      workspaceId,
+      type: "wiki",
+      content: "Persist only feature-shaped memory records.",
+      source: { kind: "user" },
+      createdAt: now,
+      updatedAt: now,
+    });
+
     expect(JSON.parse(readFileSync(filePath, "utf-8"))).toEqual({
       version: 1,
       workspaceId,
       entries: {
-        [created.id]: {
-          id: created.id,
+        [projectCreated.id]: {
+          id: projectCreated.id,
           workspaceId,
-          type: "project",
+          type: "wiki",
           content: "Persist only project-shaped memory records.",
           source: { kind: "user" },
-          createdAt: now,
-          updatedAt: now,
+          createdAt: projectCreated.createdAt,
+          updatedAt: projectCreated.updatedAt,
+        },
+        [bugfixCreated.id]: {
+          id: bugfixCreated.id,
+          workspaceId,
+          type: "issue",
+          status: "pending_verification",
+          content: "Persist only bugfix-shaped memory records.",
+          source: { kind: "user" },
+          createdAt: bugfixCreated.createdAt,
+          updatedAt: bugfixCreated.updatedAt,
+        },
+        [featureCreated.id]: {
+          id: featureCreated.id,
+          workspaceId,
+          type: "wiki",
+          content: "Persist only feature-shaped memory records.",
+          source: { kind: "user" },
+          createdAt: featureCreated.createdAt,
+          updatedAt: featureCreated.updatedAt,
         },
       },
     });
   });
 
+  it("tracks memory statuses through create and update commands", async () => {
+    const issueCreateResult = await dispatch(
+      command("memory.create", {
+        workspaceId: "ws-1",
+        type: "issue",
+        content: "Fix broken command routing.",
+      }),
+      ctx
+    );
+
+    expect(issueCreateResult.ok).toBe(true);
+    const issue = issueCreateResult.data as WorkspaceMemoryEntry;
+    expect(issue).toMatchObject({
+      workspaceId: "ws-1",
+      type: "issue",
+      status: "not_started",
+      content: "Fix broken command routing.",
+    });
+
+    const wikiCreateResult = await dispatch(
+      command("memory.create", {
+        workspaceId: "ws-1",
+        type: "wiki",
+        status: "completed",
+        content: "Track command behavior in durable memory.",
+      }),
+      ctx
+    );
+
+    expect(wikiCreateResult.ok).toBe(true);
+    expect(wikiCreateResult.data).not.toHaveProperty("status");
+
+    now += 1000;
+    const completedUpdateResult = await dispatch(
+      command("memory.update", {
+        workspaceId: "ws-1",
+        id: issue.id,
+        status: "completed",
+      }),
+      ctx
+    );
+
+    expect(completedUpdateResult.ok).toBe(true);
+    expect(completedUpdateResult.data).toMatchObject({
+      id: issue.id,
+      type: "issue",
+      status: "completed",
+    });
+
+    now += 1000;
+    const noteUpdateResult = await dispatch(
+      command("memory.update", {
+        workspaceId: "ws-1",
+        id: issue.id,
+        type: "note",
+      }),
+      ctx
+    );
+
+    expect(noteUpdateResult.ok).toBe(true);
+    expect(noteUpdateResult.data).toMatchObject({
+      id: issue.id,
+      type: "note",
+    });
+    expect(noteUpdateResult.data).not.toHaveProperty("status");
+
+    now += 1000;
+    const issueResetResult = await dispatch(
+      command("memory.update", {
+        workspaceId: "ws-1",
+        id: issue.id,
+        type: "issue",
+      }),
+      ctx
+    );
+
+    expect(issueResetResult.ok).toBe(true);
+    expect(issueResetResult.data).toMatchObject({
+      id: issue.id,
+      type: "issue",
+      status: "not_started",
+    });
+  });
+
+  it("rejects invalid memory statuses during create validation", async () => {
+    const result = await dispatch(
+      command("memory.create", {
+        workspaceId: "ws-1",
+        type: "issue",
+        status: "open",
+        content: "Invalid status should not be accepted.",
+      }),
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe("validation_error");
+  });
+
   it("returns workspace_not_found before touching memory storage", async () => {
     const result = await dispatch(command("memory.list", { workspaceId: "missing" }), ctx);
 
@@ -376,7 +545,7 @@ describe("memory commands", () => {
     const created = createdResult.data as WorkspaceMemoryEntry;
     expect(created).toMatchObject({
       workspaceId: "ws-1",
-      type: "project",
+      type: "wiki",
       content: "Keep project rules durable.",
     });
 
diff --git a/packages/server/src/commands/memory.ts b/packages/server/src/commands/memory.ts
index 0816fd72c..53cd4c488 100644
--- a/packages/server/src/commands/memory.ts
+++ b/packages/server/src/commands/memory.ts
@@ -1,8 +1,20 @@
-import { WORKSPACE_MEMORY_SOURCE_KINDS, WORKSPACE_MEMORY_TYPES } from "@coder-studio/core";
+import {
+  normalizeWorkspaceMemoryType,
+  WORKSPACE_MEMORY_SOURCE_KINDS,
+  WORKSPACE_MEMORY_STATUSES,
+} from "@coder-studio/core";
 import { z } from "zod";
 import { type CommandContext, registerCommand } from "../ws/dispatch.js";
 
-const memoryTypeSchema = z.enum(WORKSPACE_MEMORY_TYPES);
+const memoryTypeArgSchema = z
+  .string()
+  .trim()
+  .min(1, { message: "Invalid memory type" })
+  .refine((value) => normalizeWorkspaceMemoryType(value) !== undefined, {
+    message: "Invalid memory type",
+  })
+  .transform((value) => normalizeWorkspaceMemoryType(value)!);
+const memoryStatusSchema = z.enum(WORKSPACE_MEMORY_STATUSES);
 const memorySourceKindSchema = z.enum(WORKSPACE_MEMORY_SOURCE_KINDS);
 
 const workspaceSchema = z.object({
@@ -29,7 +41,7 @@ function rejectLegacyTagArgs<T extends z.ZodTypeAny>(schema: T) {
 
 const memoryListBaseSchema = workspaceSchema.extend({
   query: z.string().optional(),
-  type: memoryTypeSchema.optional(),
+  type: memoryTypeArgSchema.optional(),
   includeArchived: z.boolean().optional(),
 });
 const memoryListSchema = rejectLegacyTagArgs(memoryListBaseSchema);
@@ -50,7 +62,8 @@ const sourceHintSchema = z
 
 const memoryCreateSchema = rejectLegacyTagArgs(
   workspaceSchema.extend({
-    type: memoryTypeSchema,
+    type: memoryTypeArgSchema,
+    status: memoryStatusSchema.optional(),
     content: z.string().trim().min(1).max(20_000),
     sourceHint: sourceHintSchema.optional(),
   })
@@ -58,7 +71,8 @@ const memoryCreateSchema = rejectLegacyTagArgs(
 
 const memoryUpdateSchema = rejectLegacyTagArgs(
   memoryIdSchema.extend({
-    type: memoryTypeSchema.optional(),
+    type: memoryTypeArgSchema.optional(),
+    status: memoryStatusSchema.optional(),
     content: z.string().trim().min(1).max(20_000).optional(),
   })
 );
@@ -141,6 +155,7 @@ registerCommand("memory.create", memoryCreateSchema, async (args, ctx) => {
   const entry = memoryRepo.create({
     workspaceId: args.workspaceId,
     type: args.type,
+    status: args.status,
     content: args.content,
     source: {
       defaultKind: defaultSourceKind(args.sourceHint),
@@ -159,6 +174,7 @@ registerCommand("memory.update", memoryUpdateSchema, async (args, ctx) => {
     workspaceId: args.workspaceId,
     id: args.id,
     type: args.type,
+    status: args.status,
     content: args.content,
   });
 
diff --git a/packages/server/src/commands/recovery.ts b/packages/server/src/commands/recovery.ts
index f80ea594e..733f6e302 100644
--- a/packages/server/src/commands/recovery.ts
+++ b/packages/server/src/commands/recovery.ts
@@ -4,11 +4,11 @@ import {
   type RecoveryReconcileResult,
 } from "@coder-studio/core";
 import { z } from "zod";
-import { registerCommand } from "../ws/dispatch.js";
+import { registerRuntimeCommand } from "../runtime/command-registry.js";
 
 const RecoveryReasonSchema = z.enum(RECOVERY_REASONS);
 
-registerCommand(
+registerRuntimeCommand(
   "recovery.reconcile",
   z.object({
     reason: RecoveryReasonSchema,
@@ -19,78 +19,81 @@ registerCommand(
       })
     ),
   }),
-  async (args, ctx): Promise<RecoveryReconcileResult> => {
-    const terminals: RecoveryReconcileDecision[] = args.terminals.map((entry) => {
-      const inspection = ctx.terminalMgr.inspectRecovery(entry.terminalId, entry.renderedSeq);
+  {
+    resolveTarget: (args) => ({ kind: "terminal", terminalId: args.terminals[0]!.terminalId }),
+    handler: async (args, ctx): Promise<RecoveryReconcileResult> => {
+      const terminals: RecoveryReconcileDecision[] = args.terminals.map((entry) => {
+        const inspection = ctx.terminalMgr.inspectRecovery(entry.terminalId, entry.renderedSeq);
 
-      if (inspection.status === "unknown") {
-        return {
-          terminalId: entry.terminalId,
-          action: "unrecoverable",
-          reason: "unknown_terminal",
-        };
-      }
+        if (inspection.status === "unknown") {
+          return {
+            terminalId: entry.terminalId,
+            action: "unrecoverable",
+            reason: "unknown_terminal",
+          };
+        }
 
-      if (!inspection.alive && entry.renderedSeq >= inspection.headSeq) {
-        return {
-          terminalId: entry.terminalId,
-          action: "closed",
-          headSeq: inspection.headSeq,
-          exitCode: inspection.exitCode,
-        };
-      }
+        if (!inspection.alive && entry.renderedSeq >= inspection.headSeq) {
+          return {
+            terminalId: entry.terminalId,
+            action: "closed",
+            headSeq: inspection.headSeq,
+            exitCode: inspection.exitCode,
+          };
+        }
 
-      if (entry.renderedSeq === inspection.headSeq) {
-        return {
-          terminalId: entry.terminalId,
-          action: "noop",
-          headSeq: inspection.headSeq,
-        };
-      }
+        if (entry.renderedSeq === inspection.headSeq) {
+          return {
+            terminalId: entry.terminalId,
+            action: "noop",
+            headSeq: inspection.headSeq,
+          };
+        }
 
-      if (args.reason === "initial_mount" && inspection.snapshot.kind === "available") {
-        return {
-          terminalId: entry.terminalId,
-          action: "snapshot",
-          headSeq: inspection.headSeq,
-        };
-      }
+        if (args.reason === "initial_mount" && inspection.snapshot.kind === "available") {
+          return {
+            terminalId: entry.terminalId,
+            action: "snapshot",
+            headSeq: inspection.headSeq,
+          };
+        }
 
-      if (inspection.replay.kind === "available") {
-        return {
-          terminalId: entry.terminalId,
-          action: "replay",
-          fromSeq: entry.renderedSeq,
-          headSeq: inspection.headSeq,
-          closed: inspection.alive ? undefined : { exitCode: inspection.exitCode },
-        };
-      }
+        if (inspection.replay.kind === "available") {
+          return {
+            terminalId: entry.terminalId,
+            action: "replay",
+            fromSeq: entry.renderedSeq,
+            headSeq: inspection.headSeq,
+            closed: inspection.alive ? undefined : { exitCode: inspection.exitCode },
+          };
+        }
 
-      if (inspection.snapshot.kind === "available") {
-        return {
-          terminalId: entry.terminalId,
-          action: "snapshot",
-          headSeq: inspection.headSeq,
-          closed: inspection.alive ? undefined : { exitCode: inspection.exitCode },
-        };
-      }
+        if (inspection.snapshot.kind === "available") {
+          return {
+            terminalId: entry.terminalId,
+            action: "snapshot",
+            headSeq: inspection.headSeq,
+            closed: inspection.alive ? undefined : { exitCode: inspection.exitCode },
+          };
+        }
+
+        if (!inspection.alive) {
+          return {
+            terminalId: entry.terminalId,
+            action: "closed",
+            headSeq: inspection.headSeq,
+            exitCode: inspection.exitCode,
+          };
+        }
 
-      if (!inspection.alive) {
         return {
           terminalId: entry.terminalId,
-          action: "closed",
-          headSeq: inspection.headSeq,
-          exitCode: inspection.exitCode,
+          action: "unrecoverable",
+          reason: "too_old_no_snapshot",
         };
-      }
-
-      return {
-        terminalId: entry.terminalId,
-        action: "unrecoverable",
-        reason: "too_old_no_snapshot",
-      };
-    });
+      });
 
-    return { terminals };
+      return { terminals };
+    },
   }
 );
diff --git a/packages/server/src/commands/session.ts b/packages/server/src/commands/session.ts
index 3327a3478..3d029cd28 100644
--- a/packages/server/src/commands/session.ts
+++ b/packages/server/src/commands/session.ts
@@ -6,18 +6,11 @@ import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import type { ProviderDefinition } from "@coder-studio/core";
 import { z } from "zod";
+import { registerHostCommand } from "../host/command-registry.js";
 import { buildProviderRuntimeStatus } from "../provider-runtime/runtime-status.js";
+import { registerRuntimeCommand } from "../runtime/command-registry.js";
 import { applyPaneDisposition } from "../workspace/pane-layout.js";
-import { registerCommand } from "../ws/dispatch.js";
-
-const SESSION_CLOSE_POLL_INTERVAL_MS = 100;
-const SESSION_CLOSE_TIMEOUT_MS = 5_000;
-
-function delay(ms: number) {
-  return new Promise<void>((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
+import { executeRuntimeCommandOnTarget, registerCommand } from "../ws/dispatch.js";
 
 function getProviderFromRegistry(
   providerId: string,
@@ -46,18 +39,21 @@ async function tryReadGitHead(workspacePath: string): Promise<string | undefined
 }
 
 // session.list
-registerCommand(
+registerRuntimeCommand(
   "session.list",
   z.object({
     workspaceId: z.string(),
   }),
-  async (args, ctx) => {
-    return ctx.sessionMgr.getForWorkspace(args.workspaceId);
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      return ctx.sessionMgr.getForWorkspace(args.workspaceId);
+    },
   }
 );
 
 // session.create
-registerCommand(
+registerRuntimeCommand(
   "session.create",
   z.object({
     workspaceId: z.string(),
@@ -68,142 +64,130 @@ registerCommand(
       .regex(/^#[0-9a-fA-F]{3,8}$/)
       .optional(),
   }),
-  async (args, ctx) => {
-    // Get workspace
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    const provider = getProviderFromRegistry(args.providerId, ctx.providerRegistry);
-    if (!provider) {
-      throw { code: "unknown_provider", message: `Provider not found: ${args.providerId}` };
-    }
-
-    const runtimeStatus = await buildProviderRuntimeStatus([provider], ctx.providerRuntimeDeps);
-    const providerStatus = runtimeStatus.providers[provider.id];
-
-    if (!providerStatus?.available) {
-      throw {
-        code: "provider_cli_missing",
-        message: "Provider CLI is not installed",
-        details: {
-          providerId: provider.id,
-          missingCommands: providerStatus?.missingCommands ?? provider.requiredCommands,
-        },
-      };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    await ctx.agentInstructionPublisher?.syncWorkspace(args.workspaceId);
+      const provider = getProviderFromRegistry(args.providerId, ctx.providerRegistry);
+      if (!provider) {
+        throw { code: "unknown_provider", message: `Provider not found: ${args.providerId}` };
+      }
 
-    const session = await ctx.sessionMgr.create({
-      workspaceId: args.workspaceId,
-      workspacePath: workspace.path,
-      providerId: args.providerId,
-      provider,
-      draft: args.draft,
-      themeBackground: args.themeBackground,
-    });
+      const runtimeStatus = await buildProviderRuntimeStatus([provider], ctx.providerRuntimeDeps);
+      const providerStatus = runtimeStatus.providers[provider.id];
 
-    ctx.sessionMetadataRepo?.upsert({
-      sessionId: session.id,
-      workspaceId: args.workspaceId,
-      providerId: args.providerId,
-      objective: args.draft?.trim() || undefined,
-      baselineGitHead: await tryReadGitHead(workspace.path),
-      baselineCapturedAt: Date.now(),
-      verificationRuns: [],
-    });
+      if (!providerStatus?.available) {
+        throw {
+          code: "provider_cli_missing",
+          message: "Provider CLI is not installed",
+          details: {
+            providerId: provider.id,
+            missingCommands: providerStatus?.missingCommands ?? provider.requiredCommands,
+          },
+        };
+      }
 
-    return session;
+      await ctx.agentInstructionPublisher?.syncWorkspace(args.workspaceId);
+
+      const session = await ctx.sessionMgr.create({
+        workspaceId: args.workspaceId,
+        workspacePath: workspace.path,
+        providerId: args.providerId,
+        provider,
+        draft: args.draft,
+        themeBackground: args.themeBackground,
+      });
+
+      ctx.sessionMetadataRepo?.upsert({
+        sessionId: session.id,
+        workspaceId: args.workspaceId,
+        providerId: args.providerId,
+        objective: args.draft?.trim() || undefined,
+        baselineGitHead: await tryReadGitHead(workspace.path),
+        baselineCapturedAt: Date.now(),
+        verificationRuns: [],
+      });
+
+      return session;
+    },
   }
 );
 
 // session.stop
-registerCommand(
+registerRuntimeCommand(
   "session.stop",
   z.object({
     sessionId: z.string(),
   }),
-  async (args, ctx) => {
-    await ctx.sessionMgr.stop(args.sessionId);
+  {
+    resolveTarget: (args) => ({ kind: "session", sessionId: args.sessionId }),
+    handler: async (args, ctx) => {
+      await ctx.sessionMgr.stop(args.sessionId);
+    },
   }
 );
 
 // session.remove
-registerCommand(
+registerRuntimeCommand(
   "session.remove",
   z.object({
     sessionId: z.string(),
   }),
-  async (args, ctx) => {
-    const session = ctx.sessionMgr.get(args.sessionId);
-    if (!session) {
-      throw { code: "session_not_found", message: `Session not found: ${args.sessionId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "session", sessionId: args.sessionId }),
+    handler: async (args, ctx) => {
+      const session = ctx.sessionMgr.get(args.sessionId);
+      if (!session) {
+        throw { code: "session_not_found", message: `Session not found: ${args.sessionId}` };
+      }
 
-    if (session.state !== "ended") {
-      throw { code: "invalid_state", message: `Cannot remove session in state: ${session.state}` };
-    }
+      if (session.state !== "ended") {
+        throw {
+          code: "invalid_state",
+          message: `Cannot remove session in state: ${session.state}`,
+        };
+      }
 
-    ctx.sessionMgr.delete(args.sessionId);
-    ctx.sessionMetadataRepo?.delete(args.sessionId);
+      ctx.sessionMgr.delete(args.sessionId);
+      ctx.sessionMetadataRepo?.delete(args.sessionId);
+    },
   }
 );
 
-registerCommand(
+registerHostCommand(
   "session.close",
   z.object({
     sessionId: z.string(),
     paneDisposition: z.enum(["draft", "remove"]).default("draft"),
   }),
   async (args, ctx) => {
-    let session = ctx.sessionMgr.get(args.sessionId);
-    if (!session) {
-      throw { code: "session_not_found", message: `Session not found: ${args.sessionId}` };
+    const session = ctx.sessionMgr?.get?.(args.sessionId);
+    const workspaceId =
+      ctx.runtimeBindings.findWorkspaceIdBySessionId(args.sessionId) ?? session?.workspaceId;
+    if (!workspaceId) {
+      throw {
+        code: "workspace_not_found",
+        message: `Workspace not found for session: ${args.sessionId}`,
+      };
     }
 
-    if (session.state !== "ended") {
-      try {
-        await ctx.sessionMgr.stop(args.sessionId);
-      } catch (error) {
-        const candidate = error as { message?: string };
-        throw {
-          code: "session_close_failed",
-          message: candidate.message ?? `Failed to stop session: ${args.sessionId}`,
-        };
-      }
-
-      const deadline = Date.now() + SESSION_CLOSE_TIMEOUT_MS;
-      while (Date.now() < deadline) {
-        session = ctx.sessionMgr.get(args.sessionId);
-        if (!session) {
-          return;
-        }
-        if (session.state === "ended") {
-          break;
-        }
-        await delay(SESSION_CLOSE_POLL_INTERVAL_MS);
-      }
-
-      session = ctx.sessionMgr.get(args.sessionId);
-      if (!session) {
-        return;
-      }
-      if (session.state !== "ended") {
-        throw {
-          code: "session_close_timeout",
-          message: `Timed out waiting for session to end before closing: ${args.sessionId}`,
-        };
-      }
+    if (session?.state !== "ended") {
+      await executeRuntimeCommandOnTarget(
+        "session.stop",
+        { sessionId: args.sessionId },
+        ctx,
+        undefined,
+        { kind: "session", sessionId: args.sessionId }
+      );
     }
 
-    const workspace = ctx.workspaceMgr.get(session.workspaceId);
+    const workspace = ctx.workspaceMgr.get(workspaceId);
     if (!workspace) {
-      throw {
-        code: "workspace_not_found",
-        message: `Workspace not found: ${session.workspaceId}`,
-      };
+      throw { code: "workspace_not_found", message: `Workspace not found: ${workspaceId}` };
     }
 
     const nextUiState = {
@@ -215,9 +199,15 @@ registerCommand(
       ),
     };
 
-    ctx.workspaceMgr.updateUiState(session.workspaceId, nextUiState);
-    ctx.sessionMgr.delete(args.sessionId);
-    ctx.sessionMetadataRepo?.delete(args.sessionId);
+    ctx.workspaceMgr.updateUiState(workspaceId, nextUiState);
+    await executeRuntimeCommandOnTarget(
+      "session.remove",
+      { sessionId: args.sessionId },
+      ctx,
+      undefined,
+      { kind: "session", sessionId: args.sessionId }
+    );
+    ctx.runtimeBindings.removeSession(args.sessionId);
   }
 );
 
diff --git a/packages/server/src/commands/settings.test.ts b/packages/server/src/commands/settings.test.ts
index c77be5b3d..ae90cb53d 100644
--- a/packages/server/src/commands/settings.test.ts
+++ b/packages/server/src/commands/settings.test.ts
@@ -170,6 +170,224 @@ describe("settings commands", () => {
     expect(settingsRepo.get("appearance.mobileTerminalFontSize")).toBe(15);
   });
 
+  it("settings.update persists terminal profile settings into the file-backed settings store", async () => {
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "settings-update-terminal-profiles",
+        op: "settings.update",
+        args: {
+          settings: {
+            terminal: {
+              defaultProfileId: "custom:ops",
+              profiles: [
+                {
+                  id: "custom:ops",
+                  label: "Ops Shell",
+                  command: "/usr/bin/env",
+                  args: ["bash"],
+                  icon: "rocket",
+                },
+              ],
+            },
+          },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(true);
+    expect(settingsRepo.get("terminal.defaultProfileId")).toBe("custom:ops");
+    expect(settingsRepo.get("terminal.profiles")).toEqual([
+      {
+        id: "custom:ops",
+        label: "Ops Shell",
+        command: "/usr/bin/env",
+        args: ["bash"],
+        icon: "rocket",
+      },
+    ]);
+  });
+
+  it("settings.update clears terminal.defaultProfileId when it receives null", async () => {
+    settingsRepo.set("terminal.defaultProfileId", "custom:ops");
+
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "settings-update-terminal-default-clear",
+        op: "settings.update",
+        args: {
+          settings: {
+            terminal: {
+              defaultProfileId: null,
+            },
+          },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(true);
+    expect(settingsRepo.get("terminal.defaultProfileId")).toBeUndefined();
+  });
+
+  it("settings.update trims terminal profile labels and commands before persisting", async () => {
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "settings-update-terminal-profiles-trimmed",
+        op: "settings.update",
+        args: {
+          settings: {
+            terminal: {
+              profiles: [
+                {
+                  id: "custom:ops",
+                  label: "  Ops Shell  ",
+                  command: "  /usr/bin/env  ",
+                  args: ["bash"],
+                },
+              ],
+            },
+          },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(true);
+    expect(settingsRepo.get("terminal.profiles")).toEqual([
+      {
+        id: "custom:ops",
+        label: "Ops Shell",
+        command: "/usr/bin/env",
+        args: ["bash"],
+      },
+    ]);
+  });
+
+  it("settings.update rejects terminal profiles with invalid ids", async () => {
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "settings-update-terminal-profiles-invalid-id",
+        op: "settings.update",
+        args: {
+          settings: {
+            terminal: {
+              profiles: [
+                {
+                  id: "ops",
+                  label: "Ops Shell",
+                  command: "/usr/bin/env",
+                  args: ["bash"],
+                },
+              ],
+            },
+          },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe("validation_error");
+    expect(settingsRepo.get("terminal.profiles")).toBeUndefined();
+  });
+
+  it("settings.update rejects duplicate terminal profile ids", async () => {
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "settings-update-terminal-profiles-duplicate-ids",
+        op: "settings.update",
+        args: {
+          settings: {
+            terminal: {
+              profiles: [
+                {
+                  id: "custom:ops",
+                  label: "Ops Shell",
+                  command: "/usr/bin/env",
+                  args: ["bash"],
+                },
+                {
+                  id: "custom:ops",
+                  label: "Ops Shell Copy",
+                  command: "/bin/sh",
+                },
+              ],
+            },
+          },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe("validation_error");
+    expect(settingsRepo.get("terminal.profiles")).toBeUndefined();
+  });
+
+  it("settings.update rejects terminal profiles with whitespace-only labels", async () => {
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "settings-update-terminal-profiles-blank-label",
+        op: "settings.update",
+        args: {
+          settings: {
+            terminal: {
+              profiles: [
+                {
+                  id: "custom:ops",
+                  label: "   ",
+                  command: "/usr/bin/env",
+                  args: ["bash"],
+                },
+              ],
+            },
+          },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe("validation_error");
+    expect(settingsRepo.get("terminal.profiles")).toBeUndefined();
+  });
+
+  it("settings.update rejects terminal profiles with whitespace-only commands", async () => {
+    const result = await dispatch(
+      {
+        kind: "command",
+        id: "settings-update-terminal-profiles-blank-command",
+        op: "settings.update",
+        args: {
+          settings: {
+            terminal: {
+              profiles: [
+                {
+                  id: "custom:ops",
+                  label: "Ops Shell",
+                  command: "   ",
+                  args: ["bash"],
+                },
+              ],
+            },
+          },
+        },
+      },
+      ctx
+    );
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.code).toBe("validation_error");
+    expect(settingsRepo.get("terminal.profiles")).toBeUndefined();
+  });
+
   it("settings.update persists lsp.mode into the file-backed settings store", async () => {
     const result = await dispatch(
       {
diff --git a/packages/server/src/commands/settings.ts b/packages/server/src/commands/settings.ts
index b95bf3a17..081c461c9 100644
--- a/packages/server/src/commands/settings.ts
+++ b/packages/server/src/commands/settings.ts
@@ -3,6 +3,7 @@
  */
 
 import {
+  type CustomTerminalProfile,
   DEFAULT_SUPERVISOR_EVALUATION_TIMEOUT_SEC,
   isMonitoringSampleIntervalMs,
   isUpdateCheckIntervalSec,
@@ -49,6 +50,40 @@ const PERSONALIZATION_OVERRIDE_FIELDS = [
   "surfaceOpacity",
 ] as const;
 
+const TrimmedNonEmptyStringSchema = z.string().trim().min(1);
+const CustomTerminalProfileIdSchema = z.custom<CustomTerminalProfile["id"]>(
+  (value) => typeof value === "string" && value.startsWith("custom:"),
+  {
+    message: "Custom terminal profile ids must start with custom:",
+  }
+);
+const CustomTerminalProfileSchema: z.ZodType<CustomTerminalProfile> = z.object({
+  id: CustomTerminalProfileIdSchema,
+  label: TrimmedNonEmptyStringSchema,
+  command: TrimmedNonEmptyStringSchema,
+  args: z.array(z.string()).optional(),
+  icon: z.string().optional(),
+});
+
+const CustomTerminalProfilesSchema: z.ZodType<CustomTerminalProfile[]> = z
+  .array(CustomTerminalProfileSchema)
+  .superRefine((profiles, issueCtx) => {
+    const seen = new Set<string>();
+
+    for (const [index, profile] of profiles.entries()) {
+      if (!seen.has(profile.id)) {
+        seen.add(profile.id);
+        continue;
+      }
+
+      issueCtx.addIssue({
+        code: "custom",
+        message: `Duplicate terminal profile id: ${profile.id}`,
+        path: [index, "id"],
+      });
+    }
+  });
+
 // Settings schema
 const SettingsSchema = z.object({
   defaultProviderId: z.string().optional(),
@@ -130,6 +165,12 @@ const SettingsSchema = z.object({
       sampleIntervalMs: z.number().int().refine(isMonitoringSampleIntervalMs).optional(),
     })
     .optional(),
+  terminal: z
+    .object({
+      defaultProfileId: z.string().nullable().optional(),
+      profiles: CustomTerminalProfilesSchema.optional(),
+    })
+    .optional(),
   providers: z.record(z.string(), z.unknown()).optional(),
 });
 
@@ -212,9 +253,11 @@ registerCommand(
 
     // Flatten settings to key-value pairs
     const flatSettings = flattenSettings(nonProviderSettings);
+    const nullDeleteKeys = resolveNullSettingsKeysToDelete(flatSettings);
 
-    for (const key of overrideKeysToDelete) {
+    for (const key of [...overrideKeysToDelete, ...nullDeleteKeys]) {
       ctx.settingsRepo.delete(key);
+      delete flatSettings[key];
     }
 
     for (const [key, value] of Object.entries(flatSettings)) {
@@ -378,6 +421,10 @@ function compactProviderConfig(config: Record<string, unknown>): Record<string,
   );
 }
 
+function resolveNullSettingsKeysToDelete(settings: Record<string, unknown>): string[] {
+  return settings["terminal.defaultProfileId"] === null ? ["terminal.defaultProfileId"] : [];
+}
+
 function resolveAppearancePersonalizationOverrideKeysToDelete(
   settings: Record<string, unknown>
 ): string[] {
diff --git a/packages/server/src/commands/skills/custom.ts b/packages/server/src/commands/skills/custom.ts
new file mode 100644
index 000000000..ae915800c
--- /dev/null
+++ b/packages/server/src/commands/skills/custom.ts
@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { createCustomSkill, slugifySkillName } from "../../skills/custom-skill.js";
+import { registerCommand } from "../../ws/dispatch.js";
+import { broadcastSkillLibraryChanged, requireSkillsQuerySupport } from "./shared.js";
+
+export function registerCustomSkillCommands(): void {
+  registerCommand(
+    "skills.custom.create",
+    z.object({
+      name: z.string().trim().min(1),
+    }),
+    async (args, ctx) => {
+      requireSkillsQuerySupport(ctx);
+
+      const rootDir = ctx.skillLibraryRepo.getCustomSkillRoot();
+      if (!rootDir) {
+        throw {
+          code: "skill_create_unavailable",
+          message: "No custom skill root is configured",
+        };
+      }
+
+      const existing = ctx.skillLibraryRepo.get(slugifySkillName(args.name));
+      if (existing) {
+        throw {
+          code: "skill_slug_conflict",
+          message: `A skill with slug ${existing.slug} already exists`,
+        };
+      }
+
+      const slug = slugifySkillName(args.name);
+      for (const entry of ctx.skillLibraryRepo.list()) {
+        if (entry.slug === slug) {
+          throw {
+            code: "skill_slug_conflict",
+            message: `A skill with slug ${entry.slug} already exists`,
+          };
+        }
+      }
+
+      const entry = await createCustomSkill({
+        rootDir,
+        name: args.name,
+      });
+
+      ctx.skillLibraryRepo.set(entry);
+      broadcastSkillLibraryChanged(ctx, {
+        reason: "custom_created",
+        slug: entry.slug,
+      });
+      return entry;
+    }
+  );
+}
diff --git a/packages/server/src/commands/skills/files.ts b/packages/server/src/commands/skills/files.ts
new file mode 100644
index 000000000..e0b65b244
--- /dev/null
+++ b/packages/server/src/commands/skills/files.ts
@@ -0,0 +1,209 @@
+import { realpath, stat } from "node:fs/promises";
+import { z } from "zod";
+import {
+  createDirectory,
+  createFile,
+  deleteEntry,
+  readFile as readWorkspaceFile,
+  renameEntry,
+  resolveSafe,
+  writeFile as writeWorkspaceFile,
+} from "../../fs/file-io.js";
+import { getImageTypeInfo } from "../../fs/image.js";
+import { isPathInsideRoot } from "../../fs/path-safety.js";
+import { readTree } from "../../fs/tree.js";
+import type { CommandContext } from "../../ws/dispatch.js";
+import { registerCommand } from "../../ws/dispatch.js";
+import { broadcastSkillLibraryChanged, requireSkillsQuerySupport } from "./shared.js";
+
+function getLocalSkillEntry(ctx: CommandContext, skillSlug: string) {
+  requireSkillsQuerySupport(ctx);
+  const entry = ctx.skillLibraryRepo.get(skillSlug);
+  if (!entry || entry.source !== "custom") {
+    throw { code: "skill_not_found", message: `Custom skill not found: ${skillSlug}` };
+  }
+  return entry;
+}
+
+async function toDisplayPath(skillRoot: string, relPath: string): Promise<string> {
+  const absPath = resolveSafe(skillRoot, relPath);
+  const [realRootPath, realTargetPath] = await Promise.all([
+    realpath(skillRoot).catch(() => null),
+    realpath(absPath).catch(() => null),
+  ]);
+
+  if (realRootPath && realTargetPath && !isPathInsideRoot(realRootPath, realTargetPath)) {
+    throw { code: "path_escape", message: "Path escapes skill root" };
+  }
+
+  return absPath;
+}
+
+function broadcastSkillFilesChanged(ctx: CommandContext, skillSlug: string): void {
+  broadcastSkillLibraryChanged(ctx, {
+    reason: "skill_files_changed",
+    skillSlug,
+  });
+}
+
+export async function readSkillTree(skillRoot: string, subPath?: string) {
+  return readTree(skillRoot, subPath);
+}
+
+export async function readSkillFile(skillSlug: string, skillRoot: string, relPath: string) {
+  const result = await readWorkspaceFile(skillSlug, skillRoot, relPath);
+  const displayPath = await toDisplayPath(skillRoot, relPath);
+
+  if (result.kind === "image") {
+    const params = new URLSearchParams({
+      skillSlug,
+      path: relPath,
+    });
+    return {
+      ...result,
+      url: `/api/skill-file?${params.toString()}`,
+      displayPath,
+    };
+  }
+
+  return {
+    ...result,
+    displayPath,
+  };
+}
+
+export async function resolveSkillImageAsset(skillRoot: string, relPath: string) {
+  const typeInfo = getImageTypeInfo(relPath);
+  if (!typeInfo) {
+    throw { code: "not_an_image", message: "Only image files are supported" };
+  }
+
+  const absPath = resolveSafe(skillRoot, relPath);
+  const [realRootPath, realAssetPath] = await Promise.all([
+    realpath(skillRoot).catch(() => null),
+    realpath(absPath).catch(() => null),
+  ]);
+
+  if (!realRootPath || !realAssetPath) {
+    throw { code: "not_found", message: "File not found" };
+  }
+
+  if (!isPathInsideRoot(realRootPath, realAssetPath)) {
+    throw { code: "path_escape", message: "Path escapes skill root" };
+  }
+
+  const fileStats = await stat(absPath).catch(() => null);
+  if (!fileStats?.isFile()) {
+    throw { code: "not_found", message: "File not found" };
+  }
+
+  return {
+    absPath,
+    mime: typeInfo.mime,
+    size: fileStats.size,
+  };
+}
+
+export function registerSkillFileCommands(): void {
+  registerCommand(
+    "skills.files.readTree",
+    z.object({
+      skillSlug: z.string().trim().min(1),
+      path: z.string().optional(),
+    }),
+    async (args, ctx) => {
+      const entry = getLocalSkillEntry(ctx, args.skillSlug);
+      return readSkillTree(entry.libraryPath, args.path);
+    }
+  );
+
+  registerCommand(
+    "skills.files.read",
+    z.object({
+      skillSlug: z.string().trim().min(1),
+      path: z.string().trim().min(1),
+    }),
+    async (args, ctx) => {
+      const entry = getLocalSkillEntry(ctx, args.skillSlug);
+      return readSkillFile(args.skillSlug, entry.libraryPath, args.path);
+    }
+  );
+
+  registerCommand(
+    "skills.files.write",
+    z.object({
+      skillSlug: z.string().trim().min(1),
+      path: z.string().trim().min(1),
+      content: z.string(),
+      baseHash: z.string().optional(),
+    }),
+    async (args, ctx) => {
+      const entry = getLocalSkillEntry(ctx, args.skillSlug);
+      const result = await writeWorkspaceFile(
+        entry.libraryPath,
+        args.path,
+        args.content,
+        args.baseHash
+      );
+      broadcastSkillFilesChanged(ctx, args.skillSlug);
+      return result;
+    }
+  );
+
+  registerCommand(
+    "skills.files.create",
+    z.object({
+      skillSlug: z.string().trim().min(1),
+      path: z.string().trim().min(1),
+    }),
+    async (args, ctx) => {
+      const entry = getLocalSkillEntry(ctx, args.skillSlug);
+      await createFile(entry.libraryPath, args.path);
+      broadcastSkillFilesChanged(ctx, args.skillSlug);
+      return { ok: true };
+    }
+  );
+
+  registerCommand(
+    "skills.files.mkdir",
+    z.object({
+      skillSlug: z.string().trim().min(1),
+      path: z.string().trim().min(1),
+    }),
+    async (args, ctx) => {
+      const entry = getLocalSkillEntry(ctx, args.skillSlug);
+      await createDirectory(entry.libraryPath, args.path);
+      broadcastSkillFilesChanged(ctx, args.skillSlug);
+      return { ok: true };
+    }
+  );
+
+  registerCommand(
+    "skills.files.rename",
+    z.object({
+      skillSlug: z.string().trim().min(1),
+      fromPath: z.string().trim().min(1),
+      toPath: z.string().trim().min(1),
+    }),
+    async (args, ctx) => {
+      const entry = getLocalSkillEntry(ctx, args.skillSlug);
+      await renameEntry(entry.libraryPath, args.fromPath, args.toPath);
+      broadcastSkillFilesChanged(ctx, args.skillSlug);
+      return { ok: true };
+    }
+  );
+
+  registerCommand(
+    "skills.files.delete",
+    z.object({
+      skillSlug: z.string().trim().min(1),
+      path: z.string().trim().min(1),
+    }),
+    async (args, ctx) => {
+      const entry = getLocalSkillEntry(ctx, args.skillSlug);
+      await deleteEntry(entry.libraryPath, args.path);
+      broadcastSkillFilesChanged(ctx, args.skillSlug);
+      return { ok: true };
+    }
+  );
+}
diff --git a/packages/server/src/commands/skills/index.ts b/packages/server/src/commands/skills/index.ts
index 68c4658e5..95210ecee 100644
--- a/packages/server/src/commands/skills/index.ts
+++ b/packages/server/src/commands/skills/index.ts
@@ -1,4 +1,6 @@
 import { registerBuiltinSkillCommands } from "./builtin.js";
+import { registerCustomSkillCommands } from "./custom.js";
+import { registerSkillFileCommands } from "./files.js";
 import { registerSkillHealthCommands } from "./health.js";
 import { registerSkillInstallCommands } from "./install.js";
 import { registerSkillLibraryCommands } from "./library.js";
@@ -14,6 +16,8 @@ export function registerSkillsCommands(): void {
 
   registered = true;
   registerSkillQueryCommands();
+  registerCustomSkillCommands();
+  registerSkillFileCommands();
   registerSkillLibraryCommands();
   registerSkillInstallCommands();
   registerSkillMountCommands();
diff --git a/packages/server/src/commands/skills/install.ts b/packages/server/src/commands/skills/install.ts
index 83bdff4f5..18cdf19cb 100644
--- a/packages/server/src/commands/skills/install.ts
+++ b/packages/server/src/commands/skills/install.ts
@@ -2,12 +2,31 @@ import { z } from "zod";
 import { registerCommand } from "../../ws/dispatch.js";
 import { requireSkillInstallSupport } from "./shared.js";
 
+function canInstallFromSkillHub(
+  entry:
+    | {
+        slug: string;
+        source: "builtin" | "installed" | "custom";
+        origin?: "builtin" | "skillhub" | "filesystem";
+      }
+    | undefined
+): boolean {
+  return !entry || (entry.source === "installed" && entry.origin === "skillhub");
+}
+
 export function registerSkillInstallCommands(): void {
   registerCommand(
     "skills.install.start",
     z.object({ slug: z.string().trim().min(1) }),
     async (args, ctx) => {
       requireSkillInstallSupport(ctx);
+      const existing = ctx.skillLibraryRepo?.get(args.slug);
+      if (!canInstallFromSkillHub(existing)) {
+        throw {
+          code: "skill_slug_conflict",
+          message: `A skill with slug ${args.slug} already exists`,
+        };
+      }
       return ctx.skillInstallMgr.start(args.slug);
     }
   );
@@ -22,7 +41,12 @@ export function registerSkillInstallCommands(): void {
       }
 
       const entry = ctx.skillLibraryRepo.get(args.slug);
-      if (!entry || entry.source !== "skillhub" || entry.installState !== "installed") {
+      if (
+        !entry ||
+        entry.source !== "installed" ||
+        entry.origin !== "skillhub" ||
+        entry.installState !== "installed"
+      ) {
         throw {
           code: "skill_update_unavailable",
           message: `Only installed Skill Hub skills can be updated: ${args.slug}`,
diff --git a/packages/server/src/commands/skills/library.ts b/packages/server/src/commands/skills/library.ts
index 8375039c9..4a65339be 100644
--- a/packages/server/src/commands/skills/library.ts
+++ b/packages/server/src/commands/skills/library.ts
@@ -38,7 +38,12 @@ export function registerSkillLibraryCommands(): void {
 
     const skillHubEntries = ctx.skillLibraryRepo
       .list()
-      .filter((entry) => entry.source === "skillhub" && entry.installState === "installed");
+      .filter(
+        (entry) =>
+          entry.source === "installed" &&
+          entry.origin === "skillhub" &&
+          entry.installState === "installed"
+      );
 
     return Promise.all(skillHubEntries.map((entry) => checkSkillHubVersion(entry, ctx)));
   });
diff --git a/packages/server/src/commands/skills/mount.ts b/packages/server/src/commands/skills/mount.ts
index d19a71044..1b3c3bf44 100644
--- a/packages/server/src/commands/skills/mount.ts
+++ b/packages/server/src/commands/skills/mount.ts
@@ -1,5 +1,7 @@
 import { rm } from "node:fs/promises";
 import { z } from "zod";
+import { isPathInsideRoot } from "../../fs/path-safety.js";
+import { readManagedSkillMarker } from "../../skills/managed-skill-metadata.js";
 import { registerCommand } from "../../ws/dispatch.js";
 import {
   broadcastSkillLibraryChanged,
@@ -9,6 +11,15 @@ import {
   requireSkillTargetSupport,
 } from "./shared.js";
 
+function canDeleteCustomSkillPath(customRoot: string, libraryPath: string, slug: string): boolean {
+  if (!customRoot || !libraryPath || !isPathInsideRoot(customRoot, libraryPath)) {
+    return false;
+  }
+
+  const marker = readManagedSkillMarker(libraryPath);
+  return marker?.source === "custom" && marker.slug === slug;
+}
+
 export function registerSkillMountCommands(): void {
   registerCommand(
     "skills.mount",
@@ -70,6 +81,20 @@ export function registerSkillMountCommands(): void {
         };
       }
 
+      if (libraryEntry?.source === "installed" && libraryEntry.origin === "filesystem") {
+        throw {
+          code: "skill_uninstall_unavailable",
+          message: `Filesystem-installed skills cannot be uninstalled by Coder Studio: ${args.slug}`,
+        };
+      }
+
+      if (libraryEntry?.source === "custom" && !args.force) {
+        throw {
+          code: "skill_uninstall_confirmation_required",
+          message: `Custom skill deletion requires confirmation: ${args.slug}`,
+        };
+      }
+
       const mounts = ctx.skillMountRepo.listBySkillSlug(args.slug);
       const enabledMounts = mounts.filter((entry) => entry.enabled);
       if (enabledMounts.length > 0 && !args.force) {
@@ -88,8 +113,13 @@ export function registerSkillMountCommands(): void {
 
       ctx.skillMountRepo.deleteBySkillSlug(args.slug);
       ctx.skillLibraryRepo.delete(args.slug);
-      if (libraryEntry?.libraryPath) {
-        await rm(libraryEntry.libraryPath, { recursive: true, force: true }).catch(() => undefined);
+      if (libraryEntry?.source === "custom" && libraryEntry.libraryPath) {
+        const customRoot = ctx.skillLibraryRepo.getCustomSkillRoot();
+        if (canDeleteCustomSkillPath(customRoot, libraryEntry.libraryPath, args.slug)) {
+          await rm(libraryEntry.libraryPath, { recursive: true, force: true }).catch(
+            () => undefined
+          );
+        }
       }
       broadcastSkillLibraryChanged(ctx, {
         reason: "uninstalled",
diff --git a/packages/server/src/commands/skills/query.ts b/packages/server/src/commands/skills/query.ts
index db8762e32..6f9c908f0 100644
--- a/packages/server/src/commands/skills/query.ts
+++ b/packages/server/src/commands/skills/query.ts
@@ -35,7 +35,8 @@ export function registerSkillQueryCommands(): void {
     "skills.recommend",
     z.object({
       workspaceId: z.string().trim().min(1),
-      limit: z.number().int().positive().max(10).optional(),
+      limit: z.number().int().positive().max(20).optional(),
+      offset: z.number().int().min(0).optional(),
     }),
     async (args, ctx) => {
       requireSkillsQuerySupport(ctx);
@@ -58,6 +59,7 @@ export function registerSkillQueryCommands(): void {
         search: (query) => ctx.skillsHubClient.search(query),
         isInstalled: (slug) => Boolean(ctx.skillLibraryRepo.get(slug)),
         limit: args.limit,
+        offset: args.offset,
       });
     }
   );
diff --git a/packages/server/src/commands/task.ts b/packages/server/src/commands/task.ts
index 92c3d3c92..ca9f5fd55 100644
--- a/packages/server/src/commands/task.ts
+++ b/packages/server/src/commands/task.ts
@@ -1,6 +1,7 @@
 import { z } from "zod";
+import { registerRuntimeCommand } from "../runtime/command-registry.js";
+import type { RuntimeCommandContext } from "../runtime/context.js";
 import { discoverTasks } from "../tasks/discovery.js";
-import { type CommandContext, registerCommand } from "../ws/dispatch.js";
 
 const workspaceSchema = z.object({
   workspaceId: z.string(),
@@ -15,71 +16,92 @@ const taskRunSchema = z.object({
     .optional(),
 });
 
-function getWorkspaceOrThrow(ctx: CommandContext, workspaceId: string) {
-  const workspace = ctx.workspaceMgr.get(workspaceId);
+function getWorkspaceOrThrow(ctx: RuntimeCommandContext, workspaceId: string) {
+  const workspace = ctx.workspaceLookup.get(workspaceId);
   if (!workspace) {
     throw { code: "workspace_not_found", message: `Workspace not found: ${workspaceId}` };
   }
   return workspace;
 }
 
-registerCommand("task.discover", workspaceSchema, async (args, ctx) => {
-  const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
-  const result = await discoverTasks({ workspaceId: args.workspaceId, rootPath: workspace.path });
-  const tasks = ctx.taskMgr.setDiscoveredTasks(args.workspaceId, result.tasks);
-  return { tasks, warnings: result.warnings };
+registerRuntimeCommand("task.discover", workspaceSchema, {
+  resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+  handler: async (args, ctx) => {
+    const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+    const result = await discoverTasks({ workspaceId: args.workspaceId, rootPath: workspace.path });
+    const tasks = ctx.taskMgr.setDiscoveredTasks(args.workspaceId, result.tasks);
+    return { tasks, warnings: result.warnings };
+  },
 });
 
-registerCommand("task.list", workspaceSchema, async (args, ctx) => {
-  getWorkspaceOrThrow(ctx, args.workspaceId);
-  const existing = ctx.taskMgr.list(args.workspaceId);
-  if (existing.length > 0) {
-    return existing;
-  }
+registerRuntimeCommand("task.list", workspaceSchema, {
+  resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+  handler: async (args, ctx) => {
+    getWorkspaceOrThrow(ctx, args.workspaceId);
+    const existing = ctx.taskMgr.list(args.workspaceId);
+    if (existing.length > 0) {
+      return existing;
+    }
 
-  const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
-  const result = await discoverTasks({ workspaceId: args.workspaceId, rootPath: workspace.path });
-  return ctx.taskMgr.setDiscoveredTasks(args.workspaceId, result.tasks);
+    const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+    const result = await discoverTasks({ workspaceId: args.workspaceId, rootPath: workspace.path });
+    return ctx.taskMgr.setDiscoveredTasks(args.workspaceId, result.tasks);
+  },
 });
 
-registerCommand("task.run", taskRunSchema, async (args, ctx) => {
-  const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
-  if (ctx.taskMgr.list(args.workspaceId).length === 0) {
-    const result = await discoverTasks({ workspaceId: args.workspaceId, rootPath: workspace.path });
-    ctx.taskMgr.setDiscoveredTasks(args.workspaceId, result.tasks);
-  }
+registerRuntimeCommand("task.run", taskRunSchema, {
+  resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+  handler: async (args, ctx) => {
+    const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+    if (ctx.taskMgr.list(args.workspaceId).length === 0) {
+      const result = await discoverTasks({
+        workspaceId: args.workspaceId,
+        rootPath: workspace.path,
+      });
+      ctx.taskMgr.setDiscoveredTasks(args.workspaceId, result.tasks);
+    }
 
-  return ctx.taskMgr.run({
-    workspaceId: args.workspaceId,
-    workspacePath: workspace.path,
-    taskId: args.taskId,
-    themeBackground: args.themeBackground,
-  });
+    return ctx.taskMgr.run({
+      workspaceId: args.workspaceId,
+      workspacePath: workspace.path,
+      taskId: args.taskId,
+      themeBackground: args.themeBackground,
+    });
+  },
 });
 
-registerCommand("task.rerun", taskRunSchema, async (args, ctx) => {
-  const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
-  return ctx.taskMgr.rerun({
-    workspaceId: args.workspaceId,
-    workspacePath: workspace.path,
-    taskId: args.taskId,
-    themeBackground: args.themeBackground,
-  });
+registerRuntimeCommand("task.rerun", taskRunSchema, {
+  resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+  handler: async (args, ctx) => {
+    const workspace = getWorkspaceOrThrow(ctx, args.workspaceId);
+    return ctx.taskMgr.rerun({
+      workspaceId: args.workspaceId,
+      workspacePath: workspace.path,
+      taskId: args.taskId,
+      themeBackground: args.themeBackground,
+    });
+  },
 });
 
-registerCommand(
+registerRuntimeCommand(
   "task.stop",
   z.object({
     workspaceId: z.string(),
     runId: z.string(),
   }),
-  async (args, ctx) => {
-    getWorkspaceOrThrow(ctx, args.workspaceId);
-    return ctx.taskMgr.stop({ workspaceId: args.workspaceId, runId: args.runId });
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      getWorkspaceOrThrow(ctx, args.workspaceId);
+      return ctx.taskMgr.stop({ workspaceId: args.workspaceId, runId: args.runId });
+    },
   }
 );
 
-registerCommand("task.history", workspaceSchema, async (args, ctx) => {
-  getWorkspaceOrThrow(ctx, args.workspaceId);
-  return ctx.taskMgr.history(args.workspaceId);
+registerRuntimeCommand("task.history", workspaceSchema, {
+  resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+  handler: async (args, ctx) => {
+    getWorkspaceOrThrow(ctx, args.workspaceId);
+    return ctx.taskMgr.history(args.workspaceId);
+  },
 });
diff --git a/packages/server/src/commands/terminal.ts b/packages/server/src/commands/terminal.ts
index d00f303ab..56ef5dc97 100644
--- a/packages/server/src/commands/terminal.ts
+++ b/packages/server/src/commands/terminal.ts
@@ -3,8 +3,9 @@
  */
 
 import { stat } from "node:fs/promises";
-import { basename, isAbsolute } from "node:path";
+import { isAbsolute } from "node:path";
 import {
+  type CustomTerminalProfile,
   encodeTerminalBinaryFrame,
   TERMINAL_BINARY_PROTOCOL_VERSION,
   TERMINAL_INPUT_ACTIVITIES,
@@ -16,9 +17,49 @@ import {
 } from "@coder-studio/core";
 import { z } from "zod";
 import { resolveSafe } from "../fs/file-io.js";
-import { registerCommand } from "../ws/dispatch.js";
+import { registerHostCommand } from "../host/command-registry.js";
+import { registerRuntimeCommand } from "../runtime/command-registry.js";
+import type { RuntimeCommandContext } from "../runtime/context.js";
+import { listTerminalProfiles, resolveTerminalLaunch } from "../terminal-profiles/registry.js";
+import { executeRuntimeCommandOnTarget } from "../ws/dispatch.js";
 
 const TerminalInputActivitySchema = z.enum(TERMINAL_INPUT_ACTIVITIES).optional();
+const TerminalThemeBackgroundSchema = z
+  .string()
+  .regex(/^#[0-9a-fA-F]{3,8}$/)
+  .optional();
+const TrimmedNonEmptyStringSchema = z.string().trim().min(1);
+const CustomTerminalProfileIdSchema = z.custom<CustomTerminalProfile["id"]>(
+  (value) => typeof value === "string" && value.startsWith("custom:"),
+  {
+    message: "Custom terminal profile ids must start with custom:",
+  }
+);
+const CustomTerminalProfileSchema: z.ZodType<CustomTerminalProfile> = z.object({
+  id: CustomTerminalProfileIdSchema,
+  label: TrimmedNonEmptyStringSchema,
+  command: TrimmedNonEmptyStringSchema,
+  args: z.array(z.string()).optional(),
+  icon: z.string().optional(),
+});
+const CustomTerminalProfilesSchema: z.ZodType<CustomTerminalProfile[]> = z
+  .array(CustomTerminalProfileSchema)
+  .superRefine((profiles, issueCtx) => {
+    const seen = new Set<string>();
+
+    for (const [index, profile] of profiles.entries()) {
+      if (!seen.has(profile.id)) {
+        seen.add(profile.id);
+        continue;
+      }
+
+      issueCtx.addIssue({
+        code: "custom",
+        message: `Duplicate terminal profile id: ${profile.id}`,
+        path: [index, "id"],
+      });
+    }
+  });
 
 const TerminalInputSchema = z.union([
   z.object({
@@ -80,13 +121,7 @@ function allocateOutboundBinaryStreamId(): number {
 
 function sendTerminalBinaryFrame(
   clientId: string | undefined,
-  ctx: Parameters<typeof registerCommand>[2] extends (
-    args: unknown,
-    ctx: infer T,
-    clientId?: string
-  ) => Promise<unknown>
-    ? T
-    : never,
+  ctx: Pick<RuntimeCommandContext, "hostBridge">,
   frame: {
     type: (typeof TerminalBinaryFrameType)[keyof typeof TerminalBinaryFrameType];
     meta: number;
@@ -98,7 +133,7 @@ function sendTerminalBinaryFrame(
     return;
   }
 
-  ctx.broadcaster.sendBinaryToClient(
+  ctx.hostBridge.sendBinaryToClient(
     clientId,
     Buffer.from(
       encodeTerminalBinaryFrame(
@@ -116,242 +151,310 @@ function sendTerminalBinaryFrame(
   );
 }
 
-function resolveShellCommand(): { argv: string[]; title: string } {
-  if (process.platform === "win32") {
-    const shellPath = process.env.ComSpec || process.env.COMSPEC || "cmd.exe";
-    return {
-      argv: [shellPath],
-      title: basename(shellPath) || shellPath,
-    };
-  }
-
-  const shellPath = process.env.SHELL || "/bin/bash";
-  const shellName = basename(shellPath);
-  const argv = shellName === "cmd.exe" ? [shellPath] : [shellPath, "-i"];
+function getTerminalSettings(settingsRepo: { get: <T = unknown>(key: string) => T | undefined }): {
+  configuredDefaultProfileId?: string;
+  customProfiles: CustomTerminalProfile[];
+} {
+  const configuredDefaultProfileId = settingsRepo.get<string>("terminal.defaultProfileId");
+  const customProfiles = CustomTerminalProfilesSchema.catch([]).parse(
+    settingsRepo.get("terminal.profiles")
+  );
 
   return {
-    argv,
-    title: shellName || shellPath,
+    configuredDefaultProfileId,
+    customProfiles,
   };
 }
 
+async function resolveWorkspaceCwd(workspacePath: string, cwdPath?: string): Promise<string> {
+  if (!cwdPath || cwdPath === ".") {
+    return workspacePath;
+  }
+
+  if (isAbsolute(cwdPath)) {
+    throw { code: "invalid_cwd_path", message: "cwdPath must be workspace-relative" };
+  }
+
+  let resolvedCwd: string;
+  try {
+    resolvedCwd = resolveSafe(workspacePath, cwdPath);
+  } catch (error) {
+    if (
+      typeof error === "object" &&
+      error !== null &&
+      "code" in error &&
+      error.code === "path_escape"
+    ) {
+      throw { code: "invalid_cwd_path", message: "cwdPath must be workspace-relative" };
+    }
+    throw error;
+  }
+
+  const cwdStats = await stat(resolvedCwd).catch(() => null);
+  if (!cwdStats) {
+    throw { code: "cwd_not_found", message: `Directory not found: ${cwdPath}` };
+  }
+  if (!cwdStats.isDirectory()) {
+    throw { code: "cwd_not_directory", message: `Not a directory: ${cwdPath}` };
+  }
+
+  return resolvedCwd;
+}
+
 // terminal.list
-registerCommand(
+registerRuntimeCommand(
   "terminal.list",
   z.object({
     workspaceId: z.string(),
   }),
-  async (args, ctx) => {
-    return ctx.terminalMgr
-      .getAll()
-      .map((terminal) => terminal.toDTO())
-      .filter((terminal) => terminal.workspaceId === args.workspaceId);
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      return ctx.terminalMgr
+        .getAll()
+        .map((terminal) => terminal.toDTO())
+        .filter((terminal) => terminal.workspaceId === args.workspaceId);
+    },
   }
 );
 
 // terminal.read
-registerCommand(
+registerRuntimeCommand(
   "terminal.read",
   z.object({
     terminalId: z.string(),
     bytes: z.number().int().positive().max(MAX_TERMINAL_READ_BYTES).optional(),
   }),
-  async (args, ctx) => {
-    const bytes = args.bytes ?? DEFAULT_TERMINAL_READ_BYTES;
-    const tail = ctx.terminalMgr.getRingBufferTail(args.terminalId, bytes);
-
-    return {
-      terminalId: args.terminalId,
-      bytes,
-      text: tail.toString("utf8"),
-    };
+  {
+    resolveTarget: (args) => ({ kind: "terminal", terminalId: args.terminalId }),
+    handler: async (args, ctx) => {
+      const bytes = args.bytes ?? DEFAULT_TERMINAL_READ_BYTES;
+      const tail = ctx.terminalMgr.getRingBufferTail(args.terminalId, bytes);
+
+      return {
+        terminalId: args.terminalId,
+        bytes,
+        text: tail.toString("utf8"),
+      };
+    },
   }
 );
 
+registerHostCommand("terminal.profiles.list", z.object({}).default({}), async (_args, ctx) => {
+  const terminalSettings = getTerminalSettings(ctx.settingsRepo);
+  return listTerminalProfiles({
+    configuredDefaultProfileId: terminalSettings.configuredDefaultProfileId,
+    customProfiles: terminalSettings.customProfiles,
+  });
+});
+
 // terminal.create
-registerCommand(
+registerHostCommand(
   "terminal.create",
   z.object({
     workspaceId: z.string(),
+    profileId: z.string().optional(),
     cols: z.number().int().positive().optional(),
     rows: z.number().int().positive().optional(),
     cwdPath: z.string().optional(),
-    themeBackground: z
-      .string()
-      .regex(/^#[0-9a-fA-F]{3,8}$/)
-      .optional(),
+    themeBackground: TerminalThemeBackgroundSchema,
   }),
-  async (args, ctx) => {
+  async (args, ctx, meta) => {
     const workspace = ctx.workspaceMgr.get(args.workspaceId);
     if (!workspace) {
       throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
     }
 
-    let cwd = workspace.path;
-    if (args.cwdPath && args.cwdPath !== ".") {
-      if (isAbsolute(args.cwdPath)) {
-        throw { code: "invalid_cwd_path", message: "cwdPath must be workspace-relative" };
-      }
+    const cwd = await resolveWorkspaceCwd(workspace.path, args.cwdPath);
+    const terminalSettings = getTerminalSettings(ctx.settingsRepo);
+    const launch = await resolveTerminalLaunch({
+      configuredDefaultProfileId: terminalSettings.configuredDefaultProfileId,
+      customProfiles: terminalSettings.customProfiles,
+      requestedProfileId: args.profileId,
+      workspacePath: cwd,
+    });
 
-      let resolvedCwd: string;
-      try {
-        resolvedCwd = resolveSafe(workspace.path, args.cwdPath);
-      } catch (error) {
-        if (
-          typeof error === "object" &&
-          error !== null &&
-          "code" in error &&
-          error.code === "path_escape"
-        ) {
-          throw { code: "invalid_cwd_path", message: "cwdPath must be workspace-relative" };
-        }
-        throw error;
-      }
+    return executeRuntimeCommandOnTarget(
+      "terminal.spawn",
+      {
+        workspaceId: args.workspaceId,
+        argv: launch.argv,
+        title: launch.title,
+        cwd: launch.cwd,
+        cols: args.cols ?? 120,
+        rows: args.rows ?? 30,
+        themeBackground: args.themeBackground,
+      },
+      ctx,
+      meta,
+      { kind: "workspace", workspaceId: args.workspaceId }
+    );
+  }
+);
 
-      const cwdStats = await stat(resolvedCwd).catch(() => null);
-      if (!cwdStats) {
-        throw { code: "cwd_not_found", message: `Directory not found: ${args.cwdPath}` };
-      }
-      if (!cwdStats.isDirectory()) {
-        throw { code: "cwd_not_directory", message: `Not a directory: ${args.cwdPath}` };
+// terminal.spawn
+registerRuntimeCommand(
+  "terminal.spawn",
+  z.object({
+    workspaceId: z.string(),
+    argv: z.array(z.string()).min(1),
+    title: z.string().min(1),
+    cwd: z.string().min(1),
+    cols: z.number().int().positive(),
+    rows: z.number().int().positive(),
+    themeBackground: TerminalThemeBackgroundSchema,
+  }),
+  {
+    visibility: "internal",
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
       }
 
-      cwd = resolvedCwd;
-    }
-
-    const shell = resolveShellCommand();
-
-    // Create shell terminal
-    const terminal = ctx.terminalMgr.create({
-      workspaceId: args.workspaceId,
-      kind: "shell",
-      argv: shell.argv,
-      title: shell.title,
-      cwd,
-      cols: args.cols ?? 120,
-      rows: args.rows ?? 30,
-      themeBackground: args.themeBackground,
-    });
-
-    return terminal;
+      return ctx.terminalMgr.create({
+        workspaceId: args.workspaceId,
+        kind: "shell",
+        argv: args.argv,
+        title: args.title,
+        cwd: args.cwd,
+        cols: args.cols,
+        rows: args.rows,
+        themeBackground: args.themeBackground,
+      });
+    },
   }
 );
 
 // terminal.replay
-registerCommand(
+registerRuntimeCommand(
   "terminal.replay",
   z.object({
     terminalId: z.string(),
     lastSeq: z.number().int().nonnegative().optional(),
   }),
-  async (args, ctx, clientId) => {
-    const replay = ctx.terminalMgr.replay(args.terminalId, args.lastSeq ?? 0);
-
-    if (replay.status !== "ok") {
-      return replay;
-    }
-
-    const streamId = allocateOutboundBinaryStreamId();
-    sendTerminalBinaryFrame(clientId, ctx, {
-      type: TerminalBinaryFrameType.Replay,
-      meta: replay.seq,
-      streamId,
-      payload: replay.data,
-    });
+  {
+    resolveTarget: (args) => ({ kind: "terminal", terminalId: args.terminalId }),
+    handler: async (args, ctx, meta) => {
+      const replay = ctx.terminalMgr.replay(args.terminalId, args.lastSeq ?? 0);
+      if (replay.status !== "ok") {
+        return replay;
+      }
 
-    return {
-      status: "ok" as const,
-      transport: "binary" as const,
-      streamId,
-      size: replay.data.length,
-      seq: replay.seq,
-    };
+      const streamId = allocateOutboundBinaryStreamId();
+      sendTerminalBinaryFrame(meta?.clientId, ctx, {
+        type: TerminalBinaryFrameType.Replay,
+        meta: replay.seq,
+        streamId,
+        payload: replay.data,
+      });
+
+      return {
+        status: "ok" as const,
+        transport: "binary" as const,
+        streamId,
+        size: replay.data.length,
+        seq: replay.seq,
+      };
+    },
   }
 );
 
 // terminal.snapshot
-registerCommand(
+registerRuntimeCommand(
   "terminal.snapshot",
   z.object({
     terminalId: z.string(),
   }),
-  async (args, ctx, clientId) => {
-    const snapshot = await ctx.terminalMgr.snapshot(args.terminalId);
-
-    if (snapshot.status !== "ok") {
-      return snapshot;
-    }
-
-    const streamId = allocateOutboundBinaryStreamId();
-    sendTerminalBinaryFrame(clientId, ctx, {
-      type: TerminalBinaryFrameType.Snapshot,
-      meta: snapshot.seq,
-      streamId,
-      payload: snapshot.data,
-    });
+  {
+    resolveTarget: (args) => ({ kind: "terminal", terminalId: args.terminalId }),
+    handler: async (args, ctx, meta) => {
+      const snapshot = await ctx.terminalMgr.snapshot(args.terminalId);
+      if (snapshot.status !== "ok") {
+        return snapshot;
+      }
 
-    return {
-      status: "ok" as const,
-      transport: "binary" as const,
-      streamId,
-      size: snapshot.data.length,
-      seq: snapshot.seq,
-      rows: snapshot.rows,
-      cols: snapshot.cols,
-      source: "headless" as const,
-    } satisfies TerminalSnapshotBinaryResult;
+      const streamId = allocateOutboundBinaryStreamId();
+      sendTerminalBinaryFrame(meta?.clientId, ctx, {
+        type: TerminalBinaryFrameType.Snapshot,
+        meta: snapshot.seq,
+        streamId,
+        payload: snapshot.data,
+      });
+
+      return {
+        status: "ok" as const,
+        transport: "binary" as const,
+        streamId,
+        size: snapshot.data.length,
+        seq: snapshot.seq,
+        rows: snapshot.rows,
+        cols: snapshot.cols,
+        source: "headless" as const,
+      } satisfies TerminalSnapshotBinaryResult;
+    },
   }
 );
 
 // terminal.close
-registerCommand(
+registerRuntimeCommand(
   "terminal.close",
   z.object({
     terminalId: z.string(),
   }),
-  async (args, ctx) => {
-    await ctx.terminalMgr.close(args.terminalId);
+  {
+    resolveTarget: (args) => ({ kind: "terminal", terminalId: args.terminalId }),
+    handler: async (args, ctx) => {
+      await ctx.terminalMgr.close(args.terminalId);
+    },
   }
 );
 
 // terminal.input
-registerCommand("terminal.input", TerminalInputSchema, async (args, ctx) => {
-  const buffer = decodeTerminalInput(args);
-  const sessionId = ctx.sessionMgr.findSessionIdByTerminal(args.terminalId);
-  if (sessionId) {
-    ctx.sessionMgr.sendInput(
-      sessionId,
-      buffer,
-      normalizeTerminalInputActivity(args.activity),
-      args.submittedText
-    );
-    return;
-  }
+registerRuntimeCommand("terminal.input", TerminalInputSchema, {
+  resolveTarget: (args) => ({ kind: "terminal", terminalId: args.terminalId }),
+  handler: async (args, ctx) => {
+    const buffer = decodeTerminalInput(args);
+    const sessionId = ctx.sessionMgr.findSessionIdByTerminal(args.terminalId);
+    if (sessionId) {
+      ctx.sessionMgr.sendInput(
+        sessionId,
+        buffer,
+        normalizeTerminalInputActivity(args.activity),
+        args.submittedText
+      );
+      return;
+    }
 
-  ctx.terminalMgr.write(args.terminalId, buffer);
+    ctx.terminalMgr.write(args.terminalId, buffer);
+  },
 });
 
 // terminal.resize
-registerCommand(
+registerRuntimeCommand(
   "terminal.resize",
   z.object({
     terminalId: z.string(),
     cols: z.number().int().positive(),
     rows: z.number().int().positive(),
   }),
-  async (args, ctx) => {
-    const sessionId = ctx.sessionMgr.findSessionIdByTerminal(args.terminalId);
-    if (sessionId) {
-      ctx.sessionMgr.resize(sessionId, args.cols, args.rows);
-      return;
-    }
+  {
+    resolveTarget: (args) => ({ kind: "terminal", terminalId: args.terminalId }),
+    handler: async (args, ctx) => {
+      const sessionId = ctx.sessionMgr.findSessionIdByTerminal(args.terminalId);
+      if (sessionId) {
+        ctx.sessionMgr.resize(sessionId, args.cols, args.rows);
+        return;
+      }
 
-    ctx.terminalMgr.resize(args.terminalId, args.cols, args.rows);
+      ctx.terminalMgr.resize(args.terminalId, args.cols, args.rows);
+    },
   }
 );
 
 // terminal.syncThemeBackground
-registerCommand(
+registerRuntimeCommand(
   "terminal.syncThemeBackground",
   z.object({
     workspaceId: z.string(),
@@ -360,7 +463,10 @@ registerCommand(
       .regex(/^#[0-9a-fA-F]{3,8}$/)
       .optional(),
   }),
-  async (args, ctx) => {
-    ctx.terminalMgr.syncThemeBackgroundForWorkspace(args.workspaceId, args.themeBackground);
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      ctx.terminalMgr.syncThemeBackgroundForWorkspace(args.workspaceId, args.themeBackground);
+    },
   }
 );
diff --git a/packages/server/src/commands/ui-actions.ts b/packages/server/src/commands/ui-actions.ts
index 81149b457..a08f26a23 100644
--- a/packages/server/src/commands/ui-actions.ts
+++ b/packages/server/src/commands/ui-actions.ts
@@ -1,4 +1,5 @@
 import {
+  type AutomationPermission,
   createUiActionDispatchResult,
   createUiActionEvent,
   DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
@@ -8,7 +9,7 @@ import {
   Topics,
 } from "@coder-studio/core";
 import { z } from "zod";
-import { registerCommand } from "../ws/dispatch.js";
+import { getSessionTokenRequestAuthContext, registerCommand } from "../ws/dispatch.js";
 
 const uiActionIntentSchema = z.discriminatedUnion("type", [
   z.object({
@@ -37,6 +38,18 @@ const uiActionIntentSchema = z.discriminatedUnion("type", [
     workspaceId: z.string().optional(),
     url: z.string(),
   }),
+  z
+    .object({
+      type: z.literal("canvas.open"),
+      workspaceId: z.string().optional(),
+      canvasId: z.string().optional(),
+      title: z.string().optional(),
+      artifactType: z.enum(["architecture_canvas", "report_canvas"]).optional(),
+      sourcePath: z.string().optional(),
+    })
+    .refine((value) => Boolean(value.canvasId?.trim() || value.sourcePath?.trim()), {
+      message: "canvas.open requires canvasId or sourcePath",
+    }),
   z.object({
     type: z.literal("workspace.focus"),
     workspaceId: z.string(),
@@ -71,21 +84,92 @@ registerCommand(
   z.object({
     permissions: z.array(z.string()).optional(),
   }),
-  async (args) => ({
-    version: 1,
-    actions: listUiActionCapabilities({
-      permissions: args.permissions ?? DEFAULT_AGENT_AUTOMATION_PERMISSIONS,
-    }),
-  })
+  async (args, ctx, clientId) => {
+    const authContext = getSessionTokenRequestAuthContext(ctx, clientId);
+    const permissions = !authContext
+      ? (args.permissions ?? DEFAULT_AGENT_AUTOMATION_PERMISSIONS)
+      : !args.permissions
+        ? authContext.permissions
+        : args.permissions.filter((permission) =>
+            new Set<AutomationPermission>(authContext.permissions).has(
+              permission as AutomationPermission
+            )
+          );
+
+    return {
+      version: 1,
+      actions: listUiActionCapabilities({
+        permissions,
+      }),
+    };
+  }
 );
 
-registerCommand("uiAction.dispatch", uiActionDispatchSchema, async (args, ctx) => {
-  const request = normalizeUiActionDispatchRequest({
-    intent: args.intent,
-    requestId: args.requestId,
-    source: args.source,
-  });
-  const workspaceId = resolveUiActionWorkspaceId(request, args.workspaceId);
+registerCommand("uiAction.dispatch", uiActionDispatchSchema, async (args, ctx, clientId) => {
+  const authContext = getSessionTokenRequestAuthContext(ctx, clientId);
+  const fallbackWorkspaceId = args.workspaceId ?? authContext?.workspaceId;
+  const { intent } = args;
+  const request =
+    intent.type === "canvas.open"
+      ? await (async () => {
+          if (!ctx.canvasService) {
+            throw {
+              code: "canvas_unavailable",
+              message: "Canvas service is not available",
+            };
+          }
+
+          const workspaceId = intent.workspaceId?.trim() || fallbackWorkspaceId;
+          if (!workspaceId) {
+            throw new Error("workspaceId is required for this UI action");
+          }
+
+          const workspace = ctx.workspaceMgr.get(workspaceId);
+          if (!workspace) {
+            throw {
+              code: "workspace_not_found",
+              message: `Workspace not found: ${workspaceId}`,
+            };
+          }
+
+          const compatibilityCanvasId = intent.canvasId?.trim();
+          const compatibilityRecord = compatibilityCanvasId
+            ? ctx.canvasService.getRecord(workspaceId, compatibilityCanvasId)
+            : undefined;
+          const sourcePath = compatibilityRecord?.sourcePath ?? intent.sourcePath?.trim();
+
+          if (!sourcePath) {
+            throw {
+              code: "canvas_not_found",
+              message: `Canvas not found: ${intent.canvasId ?? "unknown"}`,
+            };
+          }
+
+          const canvasData = await ctx.canvasService.getCanvasData({
+            workspaceId,
+            workspaceRootPath: workspace.path,
+            sourcePath,
+          });
+
+          return normalizeUiActionDispatchRequest({
+            intent: {
+              type: "canvas.open" as const,
+              workspaceId,
+              ...(canvasData.canvasId ? { canvasId: canvasData.canvasId } : {}),
+              title: canvasData.title,
+              artifactType: canvasData.kind,
+              sourcePath: canvasData.sourcePath,
+            },
+            requestId: args.requestId,
+            source: args.source,
+          });
+        })()
+      : normalizeUiActionDispatchRequest({
+          intent,
+          requestId: args.requestId,
+          source: args.source,
+        });
+  const workspaceId = resolveUiActionWorkspaceId(request, fallbackWorkspaceId);
   const event = createUiActionEvent({
     request,
     workspaceId,
diff --git a/packages/server/src/commands/workspace-activity.ts b/packages/server/src/commands/workspace-activity.ts
index 88a4ae82b..04c84a542 100644
--- a/packages/server/src/commands/workspace-activity.ts
+++ b/packages/server/src/commands/workspace-activity.ts
@@ -57,6 +57,20 @@ registerCommand("workspace.history.list", z.object({}), async (_args, ctx) => {
   return new WorkspaceHistoryStore(ctx.settingsRepo).list();
 });
 
+registerCommand(
+  "workspace.history.remove",
+  z.object({
+    path: z.string(),
+  }),
+  async (args, ctx) => {
+    return new WorkspaceHistoryStore(ctx.settingsRepo).remove(args.path);
+  }
+);
+
+registerCommand("workspace.history.clear", z.object({}), async (_args, ctx) => {
+  return new WorkspaceHistoryStore(ctx.settingsRepo).clear();
+});
+
 registerCommand(
   "workspace.lastViewedTarget.set",
   z.object({
diff --git a/packages/server/src/commands/workspace.ts b/packages/server/src/commands/workspace.ts
index 55a3b7529..ca03c6bdf 100644
--- a/packages/server/src/commands/workspace.ts
+++ b/packages/server/src/commands/workspace.ts
@@ -8,6 +8,8 @@ import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import type { WorkspacePaneNode } from "@coder-studio/core";
 import { z } from "zod";
 import { createDirectory } from "../fs/file-io.js";
+import { registerHostCommand } from "../host/command-registry.js";
+import { registerRuntimeCommand } from "../runtime/command-registry.js";
 import { WorkspaceHistoryStore } from "../workspace/history-store.js";
 import { inspectWorkspaceIntelligence } from "../workspace/intelligence.js";
 import { registerCommand } from "../ws/dispatch.js";
@@ -98,6 +100,7 @@ const workspaceEditorTabSchema = z.union([
     .object({
       kind: z.literal("file"),
       path: z.string(),
+      pinned: z.boolean().optional(),
     })
     .strict(),
   z
@@ -194,47 +197,64 @@ registerCommand(
 );
 
 // workspace.open
-registerCommand(
+registerHostCommand(
   "workspace.open",
   z.object({
     path: z.string(),
   }),
   async (args, ctx) => {
+    const targetRuntime = "native";
     const workspace = await ctx.workspaceMgr.open({
       path: args.path,
+      targetRuntime,
     });
 
-    new WorkspaceHistoryStore(ctx.settingsRepo).recordOpen(workspace.path);
-    await ctx.agentInstructionPublisher?.syncWorkspace(workspace.id);
+    ctx.runtimeBindings?.bindWorkspace(workspace.id, "native-default");
+    ctx.settingsRepo && new WorkspaceHistoryStore(ctx.settingsRepo).recordOpen(workspace.path);
+    await (
+      ctx as {
+        agentInstructionPublisher?: {
+          syncWorkspace(workspaceId: string): Promise<void>;
+        };
+      }
+    ).agentInstructionPublisher?.syncWorkspace(workspace.id);
     return workspace;
   }
 );
 
-registerCommand(
+registerRuntimeCommand(
   "workspace.intelligence",
   z.object({
     workspaceId: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
-
-    return inspectWorkspaceIntelligence({
-      workspaceId: workspace.id,
-      rootPath: workspace.path,
-    });
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
+
+      return inspectWorkspaceIntelligence({
+        workspaceId: workspace.id,
+        rootPath: workspace.path,
+      });
+    },
   }
 );
 
 // workspace.close
-registerCommand(
+registerHostCommand(
   "workspace.close",
   z.object({
     id: z.string(),
   }),
   async (args, ctx) => {
+    const workspace = ctx.workspaceMgr.get(args.id);
+    if (!workspace) {
+      throw { code: "workspace_not_found", message: `Workspace not found: ${args.id}` };
+    }
+
     await ctx.workspaceMgr.close(args.id);
   }
 );
@@ -247,6 +267,7 @@ registerCommand(
       leftPanelWidth: z.number(),
       bottomPanelHeight: z.number(),
       focusMode: z.boolean(),
+      editorPinned: z.boolean().optional(),
       editorViewVisible: z.boolean().optional(),
       activeSessionId: z.string().optional(),
       agentInstructionsExpanded: z.boolean().optional(),
diff --git a/packages/server/src/commands/worktree.ts b/packages/server/src/commands/worktree.ts
index befc1476e..e3b26e5b8 100644
--- a/packages/server/src/commands/worktree.ts
+++ b/packages/server/src/commands/worktree.ts
@@ -14,17 +14,17 @@ import {
   removeWorktree,
   resolveWorktreePath,
 } from "../git/worktree.js";
-import type { CommandContext } from "../ws/dispatch.js";
-import { registerCommand } from "../ws/dispatch.js";
+import { registerRuntimeCommand } from "../runtime/command-registry.js";
+import type { RuntimeCommandContext } from "../runtime/context.js";
 import { emitGitStateChanged } from "./git-events.js";
 
 async function findRelatedWorkspaceIds(
-  ctx: CommandContext,
+  ctx: RuntimeCommandContext,
   workspacePath: string
 ): Promise<string[]> {
   const targetCommonDir = await getGitCommonDirPath(workspacePath);
   const relatedWorkspaceIds = await Promise.all(
-    ctx.workspaceMgr.list().map(async (workspace) => {
+    ctx.workspaceLookup.list().map(async (workspace) => {
       try {
         const commonDir = await getGitCommonDirPath(workspace.path);
         return commonDir === targetCommonDir ? workspace.id : null;
@@ -37,126 +37,144 @@ async function findRelatedWorkspaceIds(
   return relatedWorkspaceIds.filter((workspaceId): workspaceId is string => Boolean(workspaceId));
 }
 
-function emitWorktreeChangedForWorkspaceIds(ctx: CommandContext, workspaceIds: string[]) {
+function emitWorktreeChangedForWorkspaceIds(ctx: RuntimeCommandContext, workspaceIds: string[]) {
   for (const workspaceId of workspaceIds) {
-    if (!ctx.workspaceMgr.get(workspaceId)) {
+    if (!ctx.workspaceLookup.get(workspaceId)) {
       continue;
     }
-    emitGitStateChanged(ctx, workspaceId, { worktreeChanged: true });
+    emitGitStateChanged(ctx as never, workspaceId, { worktreeChanged: true });
   }
 }
 
-function isWorkspaceOpenForPath(ctx: CommandContext, workspacePath: string): boolean {
+function isWorkspaceOpenForPath(ctx: RuntimeCommandContext, workspacePath: string): boolean {
   const targetPath = path.resolve(workspacePath);
-  return ctx.workspaceMgr
+  return ctx.workspaceLookup
     .list()
     .some((openWorkspace) => path.resolve(openWorkspace.path) === targetPath);
 }
 
 // worktree.list
-registerCommand("worktree.list", z.object({ workspaceId: z.string() }), async (args, ctx) => {
-  const workspace = ctx.workspaceMgr.get(args.workspaceId);
-  if (!workspace) {
-    throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-  }
-  return { worktrees: await listWorktrees(workspace.path) };
+registerRuntimeCommand("worktree.list", z.object({ workspaceId: z.string() }), {
+  resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+  handler: async (args, ctx) => {
+    const workspace = ctx.workspaceLookup.get(args.workspaceId);
+    if (!workspace) {
+      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+    }
+    return { worktrees: await listWorktrees(workspace.path) };
+  },
 });
 
 // worktree.status
-registerCommand(
+registerRuntimeCommand(
   "worktree.status",
   z.object({ workspaceId: z.string(), worktreePath: z.string() }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    const worktreePath = await resolveWorktreePath(workspace.path, args.worktreePath);
-    return { status: await getWorktreeStatus(worktreePath) };
+      const worktreePath = await resolveWorktreePath(workspace.path, args.worktreePath);
+      return { status: await getWorktreeStatus(worktreePath) };
+    },
   }
 );
 
 // worktree.diff
-registerCommand(
+registerRuntimeCommand(
   "worktree.diff",
   z.object({
     workspaceId: z.string(),
     worktreePath: z.string(),
     staged: z.boolean().optional().default(false),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    const worktreePath = await resolveWorktreePath(workspace.path, args.worktreePath);
-    return { diff: await getWorktreeDiff(worktreePath, args.staged) };
+      const worktreePath = await resolveWorktreePath(workspace.path, args.worktreePath);
+      return { diff: await getWorktreeDiff(worktreePath, args.staged) };
+    },
   }
 );
 
 // worktree.tree
-registerCommand(
+registerRuntimeCommand(
   "worktree.tree",
   z.object({ workspaceId: z.string(), worktreePath: z.string() }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    const worktreePath = await resolveWorktreePath(workspace.path, args.worktreePath);
-    return { tree: await getWorktreeTree(worktreePath) };
+      const worktreePath = await resolveWorktreePath(workspace.path, args.worktreePath);
+      return { tree: await getWorktreeTree(worktreePath) };
+    },
   }
 );
 
 // worktree.create
-registerCommand(
+registerRuntimeCommand(
   "worktree.create",
   z.object({
     workspaceId: z.string(),
     branch: z.string(),
     path: z.string(),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    const relatedWorkspaceIds = await findRelatedWorkspaceIds(ctx, workspace.path);
-    const worktree = await createWorktree(workspace.path, args.branch, args.path);
-    emitWorktreeChangedForWorkspaceIds(ctx, relatedWorkspaceIds);
-    return { worktree };
+      const relatedWorkspaceIds = await findRelatedWorkspaceIds(ctx, workspace.path);
+      const worktree = await createWorktree(workspace.path, args.branch, args.path);
+      emitWorktreeChangedForWorkspaceIds(ctx, relatedWorkspaceIds);
+      return { worktree };
+    },
   }
 );
 
 // worktree.remove
-registerCommand(
+registerRuntimeCommand(
   "worktree.remove",
   z.object({
     workspaceId: z.string(),
     worktreePath: z.string(),
     force: z.boolean().optional().default(false),
   }),
-  async (args, ctx) => {
-    const workspace = ctx.workspaceMgr.get(args.workspaceId);
-    if (!workspace) {
-      throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
-    }
+  {
+    resolveTarget: (args) => ({ kind: "workspace", workspaceId: args.workspaceId }),
+    handler: async (args, ctx) => {
+      const workspace = ctx.workspaceLookup.get(args.workspaceId);
+      if (!workspace) {
+        throw { code: "workspace_not_found", message: `Workspace not found: ${args.workspaceId}` };
+      }
 
-    const relatedWorkspaceIds = await findRelatedWorkspaceIds(ctx, workspace.path);
-    const worktreePath = await resolveWorktreePath(workspace.path, args.worktreePath);
-    if (isWorkspaceOpenForPath(ctx, worktreePath)) {
-      throw {
-        code: "worktree_in_use",
-        message: `Cannot remove an open worktree workspace: ${worktreePath}`,
-      };
-    }
+      const relatedWorkspaceIds = await findRelatedWorkspaceIds(ctx, workspace.path);
+      const worktreePath = await resolveWorktreePath(workspace.path, args.worktreePath);
+      if (isWorkspaceOpenForPath(ctx, worktreePath)) {
+        throw {
+          code: "worktree_in_use",
+          message: `Cannot remove an open worktree workspace: ${worktreePath}`,
+        };
+      }
 
-    await removeWorktree(workspace.path, worktreePath, args.force);
-    emitWorktreeChangedForWorkspaceIds(ctx, relatedWorkspaceIds);
-    return {};
+      await removeWorktree(workspace.path, worktreePath, args.force);
+      emitWorktreeChangedForWorkspaceIds(ctx, relatedWorkspaceIds);
+      return {};
+    },
   }
 );
diff --git a/packages/server/src/config.test.ts b/packages/server/src/config.test.ts
index 65491a3a4..a71e80451 100644
--- a/packages/server/src/config.test.ts
+++ b/packages/server/src/config.test.ts
@@ -199,4 +199,73 @@ describe("parseServerConfig", () => {
 
     expect(config.uploadsDir).toBe("/explicit");
   });
+
+  it("builds proxy config from defaults when unset", () => {
+    delete process.env.PROXY_ENABLED;
+    delete process.env.PROXY_HOST;
+    delete process.env.PROXY_PORT;
+    delete process.env.PROXY_PUBLIC_ORIGIN;
+    delete process.env.PROXY_MAX_GRANT_TTL_MS;
+    delete process.env.PROXY_ALLOWED_HOSTS;
+    delete process.env.PROXY_ALLOWED_CIDRS;
+    delete process.env.PROXY_ALLOW_LOOPBACK;
+    delete process.env.HOST;
+    delete process.env.PORT;
+
+    const config = parseServerConfig();
+
+    expect(config.proxy).toEqual({
+      enabled: false,
+      host: "localhost",
+      port: 4174,
+      publicOrigin: undefined,
+      maxGrantTtlMs: 7 * 24 * 60 * 60 * 1000,
+      allowedHosts: [],
+      allowedCidrs: [],
+      allowLoopback: true,
+    });
+  });
+
+  it("prefers proxy host override and increments the main port by default", () => {
+    process.env.HOST = "env-host";
+    process.env.PORT = "9000";
+
+    const config = parseServerConfig({ host: "app-host", proxy: { host: "proxy-host" } });
+
+    expect(config.proxy.host).toBe("proxy-host");
+    expect(config.proxy.port).toBe(9001);
+  });
+
+  it("preserves explicit zero-valued ports for the app and proxy", () => {
+    process.env.PROXY_PORT = "8124";
+
+    const config = parseServerConfig({ port: 0, proxy: { port: 0 } });
+
+    expect(config.port).toBe(0);
+    expect(config.proxy.port).toBe(0);
+  });
+
+  it("reads proxy env settings and trims allowlists", () => {
+    process.env.PROXY_ENABLED = "true";
+    process.env.PROXY_HOST = "proxy.internal";
+    process.env.PROXY_PORT = "8123";
+    process.env.PROXY_PUBLIC_ORIGIN = "https://proxy.example.test";
+    process.env.PROXY_MAX_GRANT_TTL_MS = "60000";
+    process.env.PROXY_ALLOWED_HOSTS = " localhost, example.test ,, 127.0.0.1 ";
+    process.env.PROXY_ALLOWED_CIDRS = " 10.0.0.0/8,192.168.0.0/16 ,, ";
+    process.env.PROXY_ALLOW_LOOPBACK = "false";
+
+    const config = parseServerConfig();
+
+    expect(config.proxy).toEqual({
+      enabled: true,
+      host: "proxy.internal",
+      port: 8123,
+      publicOrigin: "https://proxy.example.test",
+      maxGrantTtlMs: 60000,
+      allowedHosts: ["localhost", "example.test", "127.0.0.1"],
+      allowedCidrs: ["10.0.0.0/8", "192.168.0.0/16"],
+      allowLoopback: false,
+    });
+  });
 });
diff --git a/packages/server/src/config.ts b/packages/server/src/config.ts
index 801c363d0..dcc1376e6 100644
--- a/packages/server/src/config.ts
+++ b/packages/server/src/config.ts
@@ -29,6 +29,16 @@ export interface ServerConfig {
     enabled: boolean;
     password?: string;
   };
+  proxy: {
+    enabled: boolean;
+    host: string;
+    port: number;
+    publicOrigin?: string;
+    maxGrantTtlMs: number;
+    allowedHosts: string[];
+    allowedCidrs: string[];
+    allowLoopback: boolean;
+  };
   update: {
     supported: boolean;
     installKind: "global_npm" | "unsupported";
@@ -158,6 +168,17 @@ function resolveUploadsDir(explicit?: string): string {
   return path.join(os.homedir(), ".coder-studio", "uploads");
 }
 
+function parseCsvEnv(value: string | undefined): string[] {
+  if (!value) {
+    return [];
+  }
+
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
 /**
  * Parse server configuration from environment and CLI args
  */
@@ -171,12 +192,14 @@ export function parseServerConfig(overrides?: ServerConfigInput): ServerConfig {
     envDataDir: process.env.DATA_DIR,
   });
   const uploadsDir = resolveUploadsDir(overrides?.uploadsDir || process.env.UPLOADS_DIR);
+  const port = overrides?.port ?? parseInt(process.env.PORT || "4173", 10);
+  const proxyPort = overrides?.proxy?.port ?? process.env.PROXY_PORT;
 
   // NOTE: use `??` on port so callers can pass 0 to request an
   // OS-assigned port. `||` would silently fall through to 4173 for port=0.
   return {
     host: overrides?.host || process.env.HOST || "localhost",
-    port: overrides?.port ?? parseInt(process.env.PORT || "4173", 10),
+    port,
     stateDir,
     uploadsDir,
     logLevel: overrides?.logLevel ?? parseLogLevel(process.env.LOG_LEVEL) ?? "info",
@@ -187,6 +210,16 @@ export function parseServerConfig(overrides?: ServerConfigInput): ServerConfig {
       enabled: !noAuth && !!password,
       password,
     },
+    proxy: {
+      enabled: process.env.PROXY_ENABLED === "true",
+      host: process.env.PROXY_HOST || overrides?.proxy?.host || process.env.HOST || "localhost",
+      port: proxyPort !== undefined ? Number(proxyPort) : port + 1,
+      publicOrigin: process.env.PROXY_PUBLIC_ORIGIN,
+      maxGrantTtlMs: Number(process.env.PROXY_MAX_GRANT_TTL_MS || 7 * 24 * 60 * 60 * 1000),
+      allowedHosts: parseCsvEnv(process.env.PROXY_ALLOWED_HOSTS),
+      allowedCidrs: parseCsvEnv(process.env.PROXY_ALLOWED_CIDRS),
+      allowLoopback: process.env.PROXY_ALLOW_LOOPBACK !== "false",
+    },
     update: overrides?.update ?? {
       supported: false,
       installKind: "unsupported",
diff --git a/packages/server/src/dev-browser/proxy-headers.test.ts b/packages/server/src/dev-browser/proxy-headers.test.ts
deleted file mode 100644
index c591c2abf..000000000
--- a/packages/server/src/dev-browser/proxy-headers.test.ts
+++ /dev/null
@@ -1,156 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  buildProxyWebSocketRequestOptions,
-  filterProxyRequestHeaders,
-  filterProxyResponseHeaders,
-  rewriteProxyLocationHeader,
-  rewriteProxyUrlReference,
-} from "./proxy-headers.js";
-
-describe("dev browser proxy headers", () => {
-  it("strips hop-by-hop request headers and sets the target host", () => {
-    expect(
-      Object.fromEntries(
-        filterProxyRequestHeaders(
-          {
-            connection: "upgrade",
-            host: "coder.example",
-            upgrade: "websocket",
-            cookie: "coder_studio_auth=secret",
-            accept: "text/html",
-          },
-          "127.0.0.1:8000"
-        )
-      )
-    ).toEqual({
-      accept: "text/html",
-      host: "127.0.0.1:8000",
-    });
-  });
-
-  it("strips unsafe response headers", () => {
-    const headers = new Headers({
-      "content-type": "text/html",
-      "content-length": "200",
-      "content-encoding": "gzip",
-      connection: "keep-alive",
-      "set-cookie": "sid=abc",
-    });
-
-    expect(Object.fromEntries(filterProxyResponseHeaders(headers))).toEqual({
-      "content-type": "text/html",
-    });
-  });
-
-  it("strips websocket transport headers and preserves subprotocols", () => {
-    expect(
-      buildProxyWebSocketRequestOptions({
-        connection: "Upgrade",
-        upgrade: "websocket",
-        host: "coder.example",
-        "sec-websocket-key": "secret",
-        "sec-websocket-version": "13",
-        "sec-websocket-extensions": "permessage-deflate",
-        "sec-websocket-protocol": "json, superjson",
-        cookie: "coder_studio_auth=secret",
-        authorization: "Bearer secret",
-        origin: "https://coder.example",
-        "x-trace-id": "trace-1",
-      })
-    ).toEqual({
-      headers: {
-        "x-trace-id": "trace-1",
-      },
-      protocols: ["json", "superjson"],
-    });
-  });
-
-  it("overrides websocket user-agent when provided", () => {
-    expect(
-      buildProxyWebSocketRequestOptions(
-        {
-          "user-agent": "Coder Studio Browser",
-          "x-trace-id": "trace-1",
-        },
-        {
-          userAgent: "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 Chrome/125.0.0.0 Mobile",
-        }
-      )
-    ).toEqual({
-      headers: {
-        "user-agent": "Mozilla/5.0 (Linux; Android 14) AppleWebKit/537.36 Chrome/125.0.0.0 Mobile",
-        "x-trace-id": "trace-1",
-      },
-    });
-  });
-
-  it("rewrites loopback redirect locations into browser proxy paths", () => {
-    expect(
-      rewriteProxyLocationHeader("http://localhost:8000/dashboard?tab=1", {
-        browserProxyBase: "/dev-browser/session/dev_1/proxy",
-        targetOrigin: "http://127.0.0.1:8000",
-        port: 8000,
-      })
-    ).toBe("/dev-browser/session/dev_1/proxy/dashboard?tab=1");
-
-    expect(
-      rewriteProxyLocationHeader("/login", {
-        browserProxyBase: "/dev-browser/session/dev_1/proxy",
-        targetOrigin: "http://127.0.0.1:8000",
-        port: 8000,
-      })
-    ).toBe("/dev-browser/session/dev_1/proxy/login");
-
-    expect(
-      rewriteProxyLocationHeader("//localhost:8000/dashboard?tab=1", {
-        browserProxyBase: "/dev-browser/session/dev_1/proxy",
-        targetOrigin: "http://127.0.0.1:8000",
-        port: 8000,
-      })
-    ).toBe("/dev-browser/session/dev_1/proxy/dashboard?tab=1");
-  });
-
-  it("does not rewrite external protocol-relative redirect locations", () => {
-    expect(
-      rewriteProxyLocationHeader("//example.com/dashboard", {
-        browserProxyBase: "/dev-browser/session/dev_1/proxy",
-        targetOrigin: "http://127.0.0.1:8000",
-        port: 8000,
-      })
-    ).toBe("//example.com/dashboard");
-  });
-
-  it("rewrites root-relative and matching loopback URL references", () => {
-    expect(
-      rewriteProxyUrlReference("/assets/app.css", {
-        browserProxyBase: "/dev-browser/session/dev_1/proxy",
-        targetOrigin: "http://127.0.0.1:8000",
-        port: 8000,
-      })
-    ).toBe("/dev-browser/session/dev_1/proxy/assets/app.css");
-
-    expect(
-      rewriteProxyUrlReference("http://localhost:8000/images/logo.png", {
-        browserProxyBase: "/dev-browser/session/dev_1/proxy",
-        targetOrigin: "http://127.0.0.1:8000",
-        port: 8000,
-      })
-    ).toBe("/dev-browser/session/dev_1/proxy/images/logo.png");
-
-    expect(
-      rewriteProxyUrlReference("./relative.svg", {
-        browserProxyBase: "/dev-browser/session/dev_1/proxy",
-        targetOrigin: "http://127.0.0.1:8000",
-        port: 8000,
-      })
-    ).toBe("./relative.svg");
-
-    expect(
-      rewriteProxyUrlReference("http://localhost:3000/images/logo.png", {
-        browserProxyBase: "/dev-browser/session/dev_1/proxy",
-        targetOrigin: "http://127.0.0.1:8000",
-        port: 8000,
-      })
-    ).toBe("http://localhost:3000/images/logo.png");
-  });
-});
diff --git a/packages/server/src/dev-browser/proxy-headers.ts b/packages/server/src/dev-browser/proxy-headers.ts
deleted file mode 100644
index 732d78c06..000000000
--- a/packages/server/src/dev-browser/proxy-headers.ts
+++ /dev/null
@@ -1,218 +0,0 @@
-import type { IncomingHttpHeaders } from "node:http";
-
-const HOP_BY_HOP_HEADERS = new Set([
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailer",
-  "transfer-encoding",
-  "upgrade",
-]);
-
-const BLOCKED_REQUEST_HEADERS = new Set(["cookie", "authorization", "origin"]);
-const BLOCKED_RESPONSE_HEADERS = new Set(["content-length", "content-encoding", "set-cookie"]);
-const BLOCKED_WEBSOCKET_REQUEST_HEADERS = new Set([
-  ...BLOCKED_REQUEST_HEADERS,
-  "connection",
-  "upgrade",
-  "host",
-  "sec-websocket-key",
-  "sec-websocket-version",
-  "sec-websocket-extensions",
-]);
-
-function normalizeHeaderValue(value: string | string[] | undefined): string | undefined {
-  if (value === undefined) {
-    return undefined;
-  }
-
-  return Array.isArray(value) ? value.join(", ") : value;
-}
-
-function appendHeader(target: Headers, key: string, value: string | string[] | undefined): void {
-  if (value === undefined) {
-    return;
-  }
-
-  if (Array.isArray(value)) {
-    for (const entry of value) {
-      target.append(key, entry);
-    }
-    return;
-  }
-
-  target.set(key, value);
-}
-
-export function filterProxyRequestHeaders(
-  headers: IncomingHttpHeaders,
-  targetHost: string,
-  options: { userAgent?: string } = {}
-): Headers {
-  const filtered = new Headers();
-
-  for (const [rawKey, value] of Object.entries(headers)) {
-    const key = rawKey.toLowerCase();
-    if (HOP_BY_HOP_HEADERS.has(key) || BLOCKED_REQUEST_HEADERS.has(key) || key === "host") {
-      continue;
-    }
-
-    appendHeader(filtered, key, value);
-  }
-
-  filtered.set("host", targetHost);
-  if (options.userAgent) {
-    filtered.set("user-agent", options.userAgent);
-  }
-  return filtered;
-}
-
-export function buildProxyWebSocketRequestOptions(headers: IncomingHttpHeaders): {
-  headers: Record<string, string>;
-  protocols?: string[];
-};
-export function buildProxyWebSocketRequestOptions(
-  headers: IncomingHttpHeaders,
-  options: { userAgent?: string }
-): {
-  headers: Record<string, string>;
-  protocols?: string[];
-};
-export function buildProxyWebSocketRequestOptions(
-  headers: IncomingHttpHeaders,
-  options: { userAgent?: string } = {}
-): {
-  headers: Record<string, string>;
-  protocols?: string[];
-} {
-  const filteredHeaders: Record<string, string> = {};
-  let protocols: string[] | undefined;
-
-  for (const [rawKey, value] of Object.entries(headers)) {
-    const key = rawKey.toLowerCase();
-
-    if (key === "sec-websocket-protocol") {
-      const normalized = normalizeHeaderValue(value);
-      if (normalized) {
-        const parsedProtocols = normalized
-          .split(",")
-          .map((protocol) => protocol.trim())
-          .filter(Boolean);
-
-        if (parsedProtocols.length > 0) {
-          protocols = parsedProtocols;
-        }
-      }
-      continue;
-    }
-
-    if (BLOCKED_WEBSOCKET_REQUEST_HEADERS.has(key)) {
-      continue;
-    }
-
-    const normalized = normalizeHeaderValue(value);
-    if (normalized !== undefined) {
-      filteredHeaders[key] = normalized;
-    }
-  }
-
-  if (options.userAgent) {
-    filteredHeaders["user-agent"] = options.userAgent;
-  }
-
-  return protocols ? { headers: filteredHeaders, protocols } : { headers: filteredHeaders };
-}
-
-export function filterProxyResponseHeaders(headers: Headers): Headers {
-  const filtered = new Headers();
-
-  headers.forEach((value, rawKey) => {
-    const key = rawKey.toLowerCase();
-    if (HOP_BY_HOP_HEADERS.has(key) || BLOCKED_RESPONSE_HEADERS.has(key)) {
-      return;
-    }
-
-    filtered.set(key, value);
-  });
-
-  return filtered;
-}
-
-function isLoopbackHostname(hostname: string): boolean {
-  return (
-    hostname === "localhost" ||
-    hostname === "127.0.0.1" ||
-    hostname === "::1" ||
-    hostname === "[::1]"
-  );
-}
-
-function effectivePort(url: URL): number {
-  if (url.port) {
-    return Number(url.port);
-  }
-  return url.protocol === "http:" ? 80 : 443;
-}
-
-function toProxiedLoopbackUrl(
-  parsed: URL,
-  input: { browserProxyBase: string; port: number; targetOrigin: string }
-): string | null {
-  const isLoopback =
-    parsed.protocol === "http:" &&
-    effectivePort(parsed) === input.port &&
-    isLoopbackHostname(parsed.hostname);
-
-  if (!isLoopback) {
-    return null;
-  }
-
-  return `${input.browserProxyBase}${parsed.pathname}${parsed.search}${parsed.hash}`;
-}
-
-export function rewriteProxyUrlReference(
-  value: string,
-  input: { browserProxyBase: string; port: number; targetOrigin: string }
-): string {
-  const trimmed = value.trim();
-  if (!trimmed || trimmed.startsWith("#")) {
-    return value;
-  }
-
-  if (trimmed.startsWith("/") && !trimmed.startsWith("//")) {
-    return `${input.browserProxyBase}${trimmed}`;
-  }
-
-  if (!/^(?:[a-zA-Z][a-zA-Z\d+.-]*:|\/\/)/.test(trimmed)) {
-    return value;
-  }
-
-  let parsed: URL;
-  try {
-    parsed = new URL(trimmed, input.targetOrigin);
-  } catch {
-    return value;
-  }
-
-  return toProxiedLoopbackUrl(parsed, input) ?? value;
-}
-
-export function rewriteProxyLocationHeader(
-  location: string,
-  input: { browserProxyBase: string; port: number; targetOrigin: string }
-): string {
-  if (location.startsWith("/") && !location.startsWith("//")) {
-    return `${input.browserProxyBase}${location}`;
-  }
-
-  let parsed: URL;
-  try {
-    parsed = new URL(location, input.targetOrigin);
-  } catch {
-    return location;
-  }
-
-  return toProxiedLoopbackUrl(parsed, input) ?? location;
-}
diff --git a/packages/server/src/dev-browser/session-store.test.ts b/packages/server/src/dev-browser/session-store.test.ts
deleted file mode 100644
index 4ec0f67a2..000000000
--- a/packages/server/src/dev-browser/session-store.test.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { DevBrowserSessionStore } from "./session-store.js";
-import type { DevBrowserTarget } from "./target-url.js";
-
-function target(overrides: Partial<DevBrowserTarget> = {}): DevBrowserTarget {
-  return {
-    connectHost: "127.0.0.1",
-    displayUrl: "http://localhost:8000/app",
-    originalHost: "localhost",
-    port: 8000,
-    targetHash: "",
-    targetOrigin: "http://127.0.0.1:8000",
-    targetPath: "/app",
-    ...overrides,
-  };
-}
-
-describe("DevBrowserSessionStore", () => {
-  it("creates and reads short-lived sessions", () => {
-    let now = 1_000;
-    const store = new DevBrowserSessionStore({ now: () => now, ttlMs: 10_000 });
-    const session = store.create(target());
-
-    expect(session.id).toMatch(/^dev_/);
-    expect(session.createdAt).toBe(1_000);
-    expect(session.expiresAt).toBe(11_000);
-    expect(store.get(session.id)).toMatchObject({
-      id: session.id,
-      targetOrigin: "http://127.0.0.1:8000",
-      targetPath: "/app",
-    });
-
-    now = 2_000;
-    expect(store.get(session.id)?.lastAccessedAt).toBe(2_000);
-  });
-
-  it("expires inactive sessions", () => {
-    let now = 1_000;
-    const store = new DevBrowserSessionStore({ now: () => now, ttlMs: 500 });
-    const session = store.create(target());
-
-    now = 1_501;
-
-    expect(store.get(session.id)).toBeNull();
-  });
-
-  it("deletes sessions explicitly", () => {
-    const store = new DevBrowserSessionStore({ now: () => 1_000, ttlMs: 10_000 });
-    const session = store.create(target());
-
-    expect(store.delete(session.id)).toBe(true);
-    expect(store.get(session.id)).toBeNull();
-  });
-});
diff --git a/packages/server/src/dev-browser/session-store.ts b/packages/server/src/dev-browser/session-store.ts
deleted file mode 100644
index 536c4a4bb..000000000
--- a/packages/server/src/dev-browser/session-store.ts
+++ /dev/null
@@ -1,75 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type { DevBrowserTarget } from "./target-url.js";
-
-export interface DevBrowserSession extends DevBrowserTarget {
-  createdAt: number;
-  expiresAt: number;
-  id: string;
-  lastAccessedAt: number;
-  preserveStudioPlatformPaths?: boolean;
-  userAgent?: string;
-}
-
-export interface DevBrowserSessionStoreOptions {
-  now?: () => number;
-  ttlMs?: number;
-}
-
-export interface CreateDevBrowserSessionInput extends DevBrowserTarget {
-  userAgent?: string;
-}
-
-const DEFAULT_TTL_MS = 30 * 60 * 1_000;
-
-function cloneSession(session: DevBrowserSession): DevBrowserSession {
-  return { ...session };
-}
-
-export class DevBrowserSessionStore {
-  readonly #now: () => number;
-  readonly #ttlMs: number;
-  readonly #sessions = new Map<string, DevBrowserSession>();
-
-  constructor(options: DevBrowserSessionStoreOptions = {}) {
-    this.#now = options.now ?? (() => Date.now());
-    this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
-  }
-
-  create(target: CreateDevBrowserSessionInput): DevBrowserSession {
-    const now = this.#now();
-    const session: DevBrowserSession = {
-      ...target,
-      id: `dev_${randomUUID()}`,
-      createdAt: now,
-      lastAccessedAt: now,
-      expiresAt: now + this.#ttlMs,
-    };
-    this.#sessions.set(session.id, session);
-    return cloneSession(session);
-  }
-
-  get(id: string): DevBrowserSession | null {
-    const session = this.#sessions.get(id);
-    if (!session) {
-      return null;
-    }
-
-    const now = this.#now();
-    if (session.expiresAt <= now) {
-      this.#sessions.delete(id);
-      return null;
-    }
-
-    const nextSession: DevBrowserSession = {
-      ...session,
-      lastAccessedAt: now,
-      expiresAt: now + this.#ttlMs,
-    };
-    this.#sessions.set(id, nextSession);
-    return cloneSession(nextSession);
-  }
-
-  delete(id: string): boolean {
-    return this.#sessions.delete(id);
-  }
-}
diff --git a/packages/server/src/dev-browser/target-url.test.ts b/packages/server/src/dev-browser/target-url.test.ts
deleted file mode 100644
index eb75c38b6..000000000
--- a/packages/server/src/dev-browser/target-url.test.ts
+++ /dev/null
@@ -1,68 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { DevBrowserTargetUrlError, parseDevBrowserTargetUrl } from "./target-url.js";
-
-describe("parseDevBrowserTargetUrl", () => {
-  it("accepts loopback HTTP URLs with explicit ports", () => {
-    expect(parseDevBrowserTargetUrl("http://localhost:8000/app?draft=1#top")).toMatchObject({
-      targetOrigin: "http://127.0.0.1:8000",
-      targetPath: "/app?draft=1",
-      targetHash: "#top",
-      connectHost: "127.0.0.1",
-      port: 8000,
-    });
-
-    expect(parseDevBrowserTargetUrl("http://127.0.0.1:5173/")).toMatchObject({
-      targetOrigin: "http://127.0.0.1:5173",
-      targetPath: "/",
-      targetHash: "",
-      connectHost: "127.0.0.1",
-      port: 5173,
-    });
-
-    expect(parseDevBrowserTargetUrl("http://[::1]:3000/docs")).toMatchObject({
-      targetOrigin: "http://[::1]:3000",
-      targetPath: "/docs",
-      targetHash: "",
-      connectHost: "::1",
-      port: 3000,
-    });
-
-    expect(parseDevBrowserTargetUrl("http://localhost:80/")).toMatchObject({
-      targetOrigin: "http://127.0.0.1:80",
-      targetPath: "/",
-      targetHash: "",
-      connectHost: "127.0.0.1",
-      port: 80,
-    });
-  });
-
-  it("normalizes manual input without an explicit protocol to HTTP", () => {
-    expect(parseDevBrowserTargetUrl("localhost:8000")).toMatchObject({
-      displayUrl: "http://localhost:8000/",
-      targetOrigin: "http://127.0.0.1:8000",
-      targetPath: "/",
-    });
-  });
-
-  it("rejects non-loopback and unsafe targets", () => {
-    const invalidInputs = [
-      "https://localhost:8000",
-      "http://localhost",
-      "http://localhost:0",
-      "http://localhost:8000@evil.test",
-      "http://user:pass@localhost:8000",
-      "http://192.168.1.20:8000",
-      "http://example.com:8000",
-      "http://127.1:8000",
-      "http://2130706433:8000",
-      "http://0x7f000001:8000",
-      "http://[0:0:0:0:0:0:0:1]:8000",
-      "file:///tmp/index.html",
-      "",
-    ];
-
-    for (const input of invalidInputs) {
-      expect(() => parseDevBrowserTargetUrl(input), input).toThrow(DevBrowserTargetUrlError);
-    }
-  });
-});
diff --git a/packages/server/src/dev-browser/target-url.ts b/packages/server/src/dev-browser/target-url.ts
deleted file mode 100644
index 834f1b6e9..000000000
--- a/packages/server/src/dev-browser/target-url.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-export class DevBrowserTargetUrlError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "DevBrowserTargetUrlError";
-  }
-}
-
-export interface DevBrowserTarget {
-  connectHost: "127.0.0.1" | "::1";
-  displayUrl: string;
-  originalHost: "localhost" | "127.0.0.1" | "[::1]";
-  port: number;
-  targetHash: string;
-  targetOrigin: string;
-  targetPath: string;
-}
-
-const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
-
-interface RawTargetAuthority {
-  host: "localhost" | "127.0.0.1" | "[::1]";
-  port: number;
-}
-
-function withDefaultProtocol(input: string): string {
-  const trimmed = input.trim();
-  if (!trimmed) {
-    throw new DevBrowserTargetUrlError("empty_url");
-  }
-  return /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(trimmed) ? trimmed : `http://${trimmed}`;
-}
-
-function parsePort(portText: string): number {
-  if (!portText) {
-    throw new DevBrowserTargetUrlError("missing_port");
-  }
-
-  const port = Number(portText);
-  if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new DevBrowserTargetUrlError("invalid_port");
-  }
-
-  return port;
-}
-
-function parseRawAuthority(input: string): RawTargetAuthority {
-  const authority = input.slice("http://".length).split(/[/?#]/, 1)[0] ?? "";
-
-  if (authority.includes("@")) {
-    throw new DevBrowserTargetUrlError("credentials_not_allowed");
-  }
-
-  let match: RegExpExecArray | null;
-  if (authority.startsWith("[")) {
-    match = /^(\[[^\]]+\]):(\d+)$/.exec(authority);
-  } else {
-    match = /^([^:]+):(\d+)$/.exec(authority);
-  }
-
-  if (!match) {
-    throw new DevBrowserTargetUrlError("missing_port");
-  }
-
-  const host = match[1];
-  const portText = match[2];
-  if (host === undefined || portText === undefined) {
-    throw new DevBrowserTargetUrlError("invalid_url");
-  }
-
-  if (!LOOPBACK_HOSTS.has(host)) {
-    throw new DevBrowserTargetUrlError("host_not_allowed");
-  }
-
-  return {
-    host: host as "localhost" | "127.0.0.1" | "[::1]",
-    port: parsePort(portText),
-  };
-}
-
-export function parseDevBrowserTargetUrl(input: string): DevBrowserTarget {
-  const normalizedInput = withDefaultProtocol(input);
-
-  let url: URL;
-  try {
-    url = new URL(normalizedInput);
-  } catch {
-    throw new DevBrowserTargetUrlError("invalid_url");
-  }
-
-  if (url.protocol !== "http:") {
-    throw new DevBrowserTargetUrlError("unsupported_protocol");
-  }
-
-  const { host, port } = parseRawAuthority(normalizedInput);
-  const connectHost = host === "[::1]" ? "::1" : "127.0.0.1";
-  const targetOrigin = connectHost === "::1" ? `http://[::1]:${port}` : `http://127.0.0.1:${port}`;
-  const targetPath = `${url.pathname || "/"}${url.search}`;
-
-  return {
-    connectHost,
-    displayUrl: url.href,
-    originalHost: host,
-    port,
-    targetHash: url.hash,
-    targetOrigin,
-    targetPath,
-  };
-}
diff --git a/packages/server/src/fs/file-io.ts b/packages/server/src/fs/file-io.ts
index a6416daba..aba2d5d47 100644
--- a/packages/server/src/fs/file-io.ts
+++ b/packages/server/src/fs/file-io.ts
@@ -272,3 +272,30 @@ export async function writeFile(
 
   return { newHash };
 }
+
+export async function writeFileIfMissing(
+  rootPath: string,
+  relPath: string,
+  content: string
+): Promise<FileWriteResult> {
+  const abs = resolveSafe(rootPath, relPath);
+  await assertResolvesInsideWorkspace(rootPath, abs);
+
+  await mkdir(path.dirname(abs), { recursive: true });
+
+  try {
+    await fsWriteFile(abs, content, {
+      encoding: "utf-8",
+      flag: "wx",
+    });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      throw { code: "already_exists", message: "File already exists" };
+    }
+
+    throw error;
+  }
+
+  const newHash = createHash("sha256").update(content).digest("hex");
+  return { newHash };
+}
diff --git a/packages/server/src/host/command-registry.ts b/packages/server/src/host/command-registry.ts
new file mode 100644
index 000000000..81f7d217e
--- /dev/null
+++ b/packages/server/src/host/command-registry.ts
@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { HostCommandContext, HostDispatchMeta } from "./context.js";
+
+export interface HostCommandDefinition<S extends z.ZodTypeAny = z.ZodTypeAny, R = unknown> {
+  schema: S;
+  handler: (args: z.output<S>, ctx: HostCommandContext, meta?: HostDispatchMeta) => Promise<R>;
+}
+
+const hostCommands = new Map<string, HostCommandDefinition<any, any>>();
+
+export function registerHostCommand<S extends z.ZodTypeAny, R>(
+  op: string,
+  schema: S,
+  handler: HostCommandDefinition<S, R>["handler"]
+): void {
+  hostCommands.set(op, { schema, handler });
+}
+
+export function getHostCommandDefinition(op: string): HostCommandDefinition | undefined {
+  return hostCommands.get(op);
+}
+
+export function getRegisteredHostCommands(): string[] {
+  return Array.from(hostCommands.keys());
+}
+
+export function clearHostCommandsForTest(): void {
+  hostCommands.clear();
+}
diff --git a/packages/server/src/host/context.ts b/packages/server/src/host/context.ts
new file mode 100644
index 000000000..b56636cab
--- /dev/null
+++ b/packages/server/src/host/context.ts
@@ -0,0 +1,44 @@
+import type { ProviderDefinition } from "@coder-studio/core";
+import type { RequestAuthContext } from "../auth/index.js";
+import type { AutomationAuditLog } from "../automation/audit-log.js";
+import type { ServerConfig } from "../config.js";
+import type { AutoFetchRuntime } from "../git/auto-fetch.js";
+import type { MonitoringService } from "../monitoring/service.js";
+import type { SessionManager } from "../session/manager.js";
+import type { CustomProviderRepo } from "../storage/repositories/custom-provider-repo.js";
+import type { MemoryRepo } from "../storage/repositories/memory-repo.js";
+import type { SettingsRepo } from "../storage/repositories/settings-repo.js";
+import type { TerminalManager } from "../terminal/manager.js";
+import type { UpdateService } from "../update/update-service.js";
+import type { WorkspaceManager } from "../workspace/manager.js";
+import type { ActivationManager } from "../ws/activation.js";
+import type { FencingManager } from "../ws/fencing.js";
+import type { Broadcaster } from "../ws/hub.js";
+import type { RuntimeRouter } from "./runtime-router.js";
+import type { WorkspaceRuntimeBindingStore } from "./workspace-runtime-binding.js";
+
+export interface HostCommandContext {
+  workspaceMgr: WorkspaceManager;
+  sessionMgr?: SessionManager;
+  terminalMgr?: TerminalManager;
+  settingsRepo: SettingsRepo;
+  memoryRepo?: MemoryRepo;
+  activationMgr: ActivationManager;
+  automationAuditLog?: AutomationAuditLog;
+  broadcaster: Broadcaster;
+  autoFetch?: AutoFetchRuntime;
+  runtimeRouter: RuntimeRouter;
+  runtimeBindings: WorkspaceRuntimeBindingStore;
+  fencingMgr?: FencingManager;
+  config?: Pick<ServerConfig, "auth" | "host">;
+  updateService?: UpdateService;
+  monitoringService?: MonitoringService;
+  customProviderRepo?: CustomProviderRepo;
+  providerRegistry: ProviderDefinition[];
+  setProviderRegistry?: (providers: ProviderDefinition[]) => void;
+}
+
+export interface HostDispatchMeta {
+  clientId?: string;
+  authContext?: RequestAuthContext;
+}
diff --git a/packages/server/src/host/runtime-registry.ts b/packages/server/src/host/runtime-registry.ts
new file mode 100644
index 000000000..74c1c5bcc
--- /dev/null
+++ b/packages/server/src/host/runtime-registry.ts
@@ -0,0 +1,24 @@
+import type { ProviderDefinition } from "@coder-studio/core";
+import type { RuntimeHandle } from "../runtime/contract.js";
+
+export class RuntimeRegistry {
+  private readonly runtimes = new Map<string, RuntimeHandle>();
+
+  register(runtime: RuntimeHandle): void {
+    this.runtimes.set(runtime.id, runtime);
+  }
+
+  get(runtimeId: string): RuntimeHandle | undefined {
+    return this.runtimes.get(runtimeId);
+  }
+
+  list(): RuntimeHandle[] {
+    return Array.from(this.runtimes.values());
+  }
+
+  setProviderRegistry(providers: ProviderDefinition[]): void {
+    for (const runtime of this.runtimes.values()) {
+      runtime.setProviderRegistry?.(providers);
+    }
+  }
+}
diff --git a/packages/server/src/host/runtime-router.ts b/packages/server/src/host/runtime-router.ts
new file mode 100644
index 000000000..e2ddfc6c3
--- /dev/null
+++ b/packages/server/src/host/runtime-router.ts
@@ -0,0 +1,60 @@
+import type { RequestAuthContext } from "../auth/index.js";
+import type { RuntimeExecuteMeta, RuntimeRouteTarget } from "../runtime/contract.js";
+import type { RuntimeRegistry } from "./runtime-registry.js";
+import type { WorkspaceRuntimeBindingStore } from "./workspace-runtime-binding.js";
+
+export class RuntimeRouter {
+  constructor(
+    private readonly deps: {
+      runtimeRegistry: RuntimeRegistry;
+      bindings: WorkspaceRuntimeBindingStore;
+      defaultRuntimeId: string;
+    }
+  ) {}
+
+  private resolveRuntimeId(target: RuntimeRouteTarget): string {
+    if (target.kind === "default") {
+      return this.deps.defaultRuntimeId;
+    }
+
+    const workspaceId =
+      target.kind === "workspace"
+        ? target.workspaceId
+        : target.kind === "session"
+          ? this.deps.bindings.findWorkspaceIdBySessionId(target.sessionId)
+          : this.deps.bindings.findWorkspaceIdByTerminalId(target.terminalId);
+
+    if (!workspaceId) {
+      throw { code: "workspace_not_found", message: "Unable to resolve runtime target" };
+    }
+
+    const runtimeId = this.deps.bindings.getRuntimeIdForWorkspace(workspaceId);
+    if (!runtimeId) {
+      throw {
+        code: "runtime_not_bound",
+        message: `No runtime bound for workspace: ${workspaceId}`,
+      };
+    }
+
+    return runtimeId;
+  }
+
+  async executeOnTarget(
+    target: RuntimeRouteTarget,
+    op: string,
+    args: unknown,
+    meta?: RuntimeExecuteMeta
+  ): Promise<unknown> {
+    const runtimeId = this.resolveRuntimeId(target);
+    const runtime = this.deps.runtimeRegistry.get(runtimeId);
+    if (!runtime) {
+      throw { code: "runtime_not_found", message: `Runtime not found: ${runtimeId}` };
+    }
+
+    return runtime.execute(op, args, meta);
+  }
+
+  getAuthContextForClient(_clientId?: string): RequestAuthContext | undefined {
+    return undefined;
+  }
+}
diff --git a/packages/server/src/host/workspace-runtime-binding.ts b/packages/server/src/host/workspace-runtime-binding.ts
new file mode 100644
index 000000000..219a73e98
--- /dev/null
+++ b/packages/server/src/host/workspace-runtime-binding.ts
@@ -0,0 +1,121 @@
+import type { Session, Terminal } from "@coder-studio/core";
+
+function upsertByWorkspaceId<T extends { id: string; workspaceId: string }>(
+  outer: Map<string, Map<string, T>>,
+  index: Map<string, string>,
+  value: T
+): void {
+  const previousWorkspaceId = index.get(value.id);
+  if (previousWorkspaceId && previousWorkspaceId !== value.workspaceId) {
+    outer.get(previousWorkspaceId)?.delete(value.id);
+  }
+
+  index.set(value.id, value.workspaceId);
+  const bucket = outer.get(value.workspaceId) ?? new Map<string, T>();
+  bucket.set(value.id, value);
+  outer.set(value.workspaceId, bucket);
+}
+
+export class WorkspaceRuntimeBindingStore {
+  private readonly runtimeIdByWorkspaceId = new Map<string, string>();
+  private readonly workspaceIdBySessionId = new Map<string, string>();
+  private readonly workspaceIdByTerminalId = new Map<string, string>();
+  private readonly sessionIdByTerminalId = new Map<string, string>();
+  private readonly sessionsByWorkspaceId = new Map<string, Map<string, Session>>();
+  private readonly terminalsByWorkspaceId = new Map<string, Map<string, Terminal>>();
+
+  bindWorkspace(workspaceId: string, runtimeId: string): void {
+    this.runtimeIdByWorkspaceId.set(workspaceId, runtimeId);
+  }
+
+  unbindWorkspace(workspaceId: string): void {
+    this.runtimeIdByWorkspaceId.delete(workspaceId);
+
+    const sessions = this.sessionsByWorkspaceId.get(workspaceId);
+    for (const session of sessions?.values() ?? []) {
+      this.workspaceIdBySessionId.delete(session.id);
+      if (this.sessionIdByTerminalId.get(session.terminalId) === session.id) {
+        this.sessionIdByTerminalId.delete(session.terminalId);
+      }
+    }
+
+    const terminals = this.terminalsByWorkspaceId.get(workspaceId);
+    for (const terminalId of terminals?.keys() ?? []) {
+      this.workspaceIdByTerminalId.delete(terminalId);
+    }
+
+    this.sessionsByWorkspaceId.delete(workspaceId);
+    this.terminalsByWorkspaceId.delete(workspaceId);
+  }
+
+  getRuntimeIdForWorkspace(workspaceId: string): string | undefined {
+    return this.runtimeIdByWorkspaceId.get(workspaceId);
+  }
+
+  bindSession(session: Session): void {
+    const previousWorkspaceId = this.workspaceIdBySessionId.get(session.id);
+    const previousSession = previousWorkspaceId
+      ? this.sessionsByWorkspaceId.get(previousWorkspaceId)?.get(session.id)
+      : undefined;
+
+    if (
+      previousSession &&
+      previousSession.terminalId !== session.terminalId &&
+      this.sessionIdByTerminalId.get(previousSession.terminalId) === session.id
+    ) {
+      this.sessionIdByTerminalId.delete(previousSession.terminalId);
+    }
+
+    upsertByWorkspaceId(this.sessionsByWorkspaceId, this.workspaceIdBySessionId, session);
+    this.sessionIdByTerminalId.set(session.terminalId, session.id);
+  }
+
+  removeSession(sessionId: string): void {
+    const workspaceId = this.workspaceIdBySessionId.get(sessionId);
+    if (!workspaceId) {
+      return;
+    }
+
+    const session = this.sessionsByWorkspaceId.get(workspaceId)?.get(sessionId);
+    if (session && this.sessionIdByTerminalId.get(session.terminalId) === sessionId) {
+      this.sessionIdByTerminalId.delete(session.terminalId);
+    }
+
+    this.workspaceIdBySessionId.delete(sessionId);
+    this.sessionsByWorkspaceId.get(workspaceId)?.delete(sessionId);
+  }
+
+  findWorkspaceIdBySessionId(sessionId: string): string | undefined {
+    return this.workspaceIdBySessionId.get(sessionId);
+  }
+
+  listSessionsForWorkspace(workspaceId: string): Session[] {
+    return Array.from(this.sessionsByWorkspaceId.get(workspaceId)?.values() ?? []);
+  }
+
+  findSessionIdByTerminalId(terminalId: string): string | undefined {
+    return this.sessionIdByTerminalId.get(terminalId);
+  }
+
+  bindTerminal(terminal: Terminal): void {
+    upsertByWorkspaceId(this.terminalsByWorkspaceId, this.workspaceIdByTerminalId, terminal);
+  }
+
+  removeTerminal(terminalId: string): void {
+    const workspaceId = this.workspaceIdByTerminalId.get(terminalId);
+    if (!workspaceId) {
+      return;
+    }
+
+    this.workspaceIdByTerminalId.delete(terminalId);
+    this.terminalsByWorkspaceId.get(workspaceId)?.delete(terminalId);
+  }
+
+  findWorkspaceIdByTerminalId(terminalId: string): string | undefined {
+    return this.workspaceIdByTerminalId.get(terminalId);
+  }
+
+  listTerminalsForWorkspace(workspaceId: string): Terminal[] {
+    return Array.from(this.terminalsByWorkspaceId.get(workspaceId)?.values() ?? []);
+  }
+}
diff --git a/packages/server/src/preview/html-resource-rewriter.ts b/packages/server/src/preview/html-resource-rewriter.ts
index 9a619737b..7b2549231 100644
--- a/packages/server/src/preview/html-resource-rewriter.ts
+++ b/packages/server/src/preview/html-resource-rewriter.ts
@@ -28,6 +28,7 @@ interface PreviewRewriteInput {
   sessionId: string;
   workspaceRootPath: string;
   baseWorkspacePath?: string;
+  preserveRootRelativePrefixes?: string[];
 }
 
 export function encodePathSegments(inputPath: string): string {
@@ -39,12 +40,18 @@ export function encodePathSegments(inputPath: string): string {
 
 export function rewritePreviewHtmlResourceUrls(
   html: string,
-  input: { sessionId: string; workspaceRootPath: string; entryPath: string }
+  input: {
+    sessionId: string;
+    workspaceRootPath: string;
+    entryPath: string;
+    preserveRootRelativePrefixes?: string[];
+  }
 ): string {
   const rewriteInput = {
     sessionId: input.sessionId,
     workspaceRootPath: input.workspaceRootPath,
     baseWorkspacePath: input.entryPath,
+    preserveRootRelativePrefixes: input.preserveRootRelativePrefixes,
   };
   const htmlWithStyleBlocks = html.replace(
     STYLE_BLOCK_PATTERN,
@@ -234,6 +241,10 @@ function rewritePreviewResourceUrl(rawValue: string, input: PreviewRewriteInput)
   const decodedPath = decodePathSegments(trimmedValue.replaceAll("\\", "/"));
 
   if (decodedPath.startsWith("/")) {
+    if (input.preserveRootRelativePrefixes?.some((prefix) => decodedPath.startsWith(prefix))) {
+      return rawValue;
+    }
+
     const workspaceRelativePath =
       resolveWorkspaceRelativePath(input.workspaceRootPath, decodedPath) ??
       normalizeWorkspaceRelativePath(decodedPath.slice(1));
diff --git a/packages/server/src/preview/render-markdown.test.ts b/packages/server/src/preview/render-markdown.test.ts
index d90f307f9..3f627d110 100644
--- a/packages/server/src/preview/render-markdown.test.ts
+++ b/packages/server/src/preview/render-markdown.test.ts
@@ -32,4 +32,15 @@ describe("renderMarkdownDocument", () => {
 
     expect(html).toContain("&lt;script&gt;alert(&quot;x&quot;)&lt;/script&gt;");
   });
+
+  it("injects mermaid runtime assets for mermaid fenced code blocks", () => {
+    const html = renderMarkdownDocument({
+      markdown: "```mermaid\ngraph TD\nA[README] --> B[Preview]\n```",
+      title: "README.md",
+    });
+
+    expect(html).toContain('<pre class="mermaid">');
+    expect(html).toContain("/api/preview/assets/mermaid.min.js");
+    expect(html).toContain("/api/preview/assets/markdown-mermaid-init.js");
+  });
 });
diff --git a/packages/server/src/preview/render-markdown.ts b/packages/server/src/preview/render-markdown.ts
index 63be1b6a0..187e97b53 100644
--- a/packages/server/src/preview/render-markdown.ts
+++ b/packages/server/src/preview/render-markdown.ts
@@ -1,11 +1,35 @@
+import { markdownUsesMermaid } from "@coder-studio/utils";
 import MarkdownIt from "markdown-it";
 
+const MERMAID_RUNTIME_SRC = "/api/preview/assets/mermaid.min.js";
+const MERMAID_INIT_SRC = "/api/preview/assets/markdown-mermaid-init.js";
+
 const md = new MarkdownIt({
   html: false,
   linkify: true,
   typographer: false,
 });
 
+const defaultFenceRenderer = md.renderer.rules.fence?.bind(md.renderer.rules);
+
+md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+  const token = tokens[idx];
+  if (!token) {
+    return "";
+  }
+
+  const language = token.info.trim().split(/\s+/, 1)[0];
+  if (language === "mermaid") {
+    return `<pre class="mermaid">${md.utils.escapeHtml(token.content)}</pre>\n`;
+  }
+
+  if (defaultFenceRenderer) {
+    return defaultFenceRenderer(tokens, idx, options, env, self);
+  }
+
+  return self.renderToken(tokens, idx, options);
+};
+
 const PREVIEW_CSS = `
   :root { color-scheme: light; }
   body {
@@ -43,6 +67,9 @@ function escapeHtml(value: string): string {
 
 export function renderMarkdownDocument(input: { markdown: string; title: string }): string {
   const body = md.render(input.markdown);
+  const scripts = markdownUsesMermaid(input.markdown)
+    ? `\n    <script src="${MERMAID_RUNTIME_SRC}"></script>\n    <script src="${MERMAID_INIT_SRC}"></script>`
+    : "";
   return `<!doctype html>
 <html lang="en">
   <head>
@@ -51,6 +78,6 @@ export function renderMarkdownDocument(input: { markdown: string; title: string
     <title>${escapeHtml(input.title)}</title>
     <style>${PREVIEW_CSS}</style>
   </head>
-  <body>${body}</body>
+  <body>${body}${scripts}</body>
 </html>`;
 }
diff --git a/packages/server/src/routes/canvas.test.ts b/packages/server/src/routes/canvas.test.ts
new file mode 100644
index 000000000..172229989
--- /dev/null
+++ b/packages/server/src/routes/canvas.test.ts
@@ -0,0 +1,164 @@
+import Fastify from "fastify";
+import { describe, expect, it, vi } from "vitest";
+import { registerCanvasRoutes } from "./canvas.js";
+
+describe("/api/canvas", () => {
+  it("returns compiled canvas data by source path as json", async () => {
+    const getCanvasData = vi.fn(async () => ({
+      canvasId: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      renderStatus: "ready",
+      lastError: null,
+      compiledDocument: {
+        kind: "architecture_canvas",
+        title: "Runtime Flow",
+        summary: "How requests move.",
+        sections: [],
+      },
+    }));
+
+    const app = Fastify({ logger: false });
+    registerCanvasRoutes(app, {
+      workspaceMgr: {
+        get: () => ({ path: "/workspace" }),
+      },
+      canvasService: {
+        getCanvasData,
+      },
+    });
+    await app.ready();
+
+    const response = await app.inject({
+      method: "GET",
+      url: "/api/canvas/ws-1/data?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc",
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.headers["content-type"]).toContain("application/json");
+    expect(response.json()).toMatchObject({
+      canvasId: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      title: "Runtime Flow",
+      renderStatus: "ready",
+    });
+    expect(getCanvasData).toHaveBeenCalledWith({
+      workspaceId: "ws-1",
+      workspaceRootPath: "/workspace",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    });
+
+    await app.close();
+  });
+
+  it("returns not found when the workspace is missing", async () => {
+    const getCanvasData = vi.fn();
+    const app = Fastify({ logger: false });
+    registerCanvasRoutes(app, {
+      workspaceMgr: {
+        get: () => null,
+      },
+      canvasService: {
+        getCanvasData,
+      },
+    });
+    await app.ready();
+
+    const response = await app.inject({
+      method: "GET",
+      url: "/api/canvas/ws-1/data?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc",
+    });
+
+    expect(response.statusCode).toBe(404);
+    expect(response.json()).toMatchObject({
+      error: "workspace_not_found",
+    });
+    expect(getCanvasData).not.toHaveBeenCalled();
+
+    await app.close();
+  });
+
+  it("returns bad request when sourcePath is missing", async () => {
+    const getCanvasData = vi.fn();
+    const app = Fastify({ logger: false });
+    registerCanvasRoutes(app, {
+      workspaceMgr: {
+        get: () => ({ path: "/workspace" }),
+      },
+      canvasService: {
+        getCanvasData,
+      },
+    });
+    await app.ready();
+
+    const response = await app.inject({
+      method: "GET",
+      url: "/api/canvas/ws-1/data",
+    });
+
+    expect(response.statusCode).toBe(400);
+    expect(response.json()).toMatchObject({
+      error: "source_path_required",
+    });
+    expect(getCanvasData).not.toHaveBeenCalled();
+
+    await app.close();
+  });
+
+  it("returns not found when the canvas is missing", async () => {
+    const app = Fastify({ logger: false });
+    registerCanvasRoutes(app, {
+      workspaceMgr: {
+        get: () => ({ path: "/workspace" }),
+      },
+      canvasService: {
+        getCanvasData: async () => {
+          throw { code: "canvas_not_found", message: "Canvas not found: canvas-1" };
+        },
+      },
+    });
+    await app.ready();
+
+    const response = await app.inject({
+      method: "GET",
+      url: "/api/canvas/ws-1/data?sourcePath=.coder-studio%2Fcanvases%2Fmissing-flow.csc",
+    });
+
+    expect(response.statusCode).toBe(404);
+    expect(response.json()).toMatchObject({
+      error: "canvas_not_found",
+    });
+
+    await app.close();
+  });
+
+  it("returns bad request when sourcePath escapes the workspace", async () => {
+    const app = Fastify({ logger: false });
+    registerCanvasRoutes(app, {
+      workspaceMgr: {
+        get: () => ({ path: "/workspace" }),
+      },
+      canvasService: {
+        getCanvasData: async () => {
+          throw { code: "path_escape", message: "Path escapes workspace root" };
+        },
+      },
+    });
+    await app.ready();
+
+    const response = await app.inject({
+      method: "GET",
+      url: "/api/canvas/ws-1/data?sourcePath=..%2Fsecret",
+    });
+
+    expect(response.statusCode).toBe(400);
+    expect(response.json()).toMatchObject({
+      error: "path_escape",
+    });
+
+    await app.close();
+  });
+});
diff --git a/packages/server/src/routes/canvas.ts b/packages/server/src/routes/canvas.ts
new file mode 100644
index 000000000..4d4a4c3b0
--- /dev/null
+++ b/packages/server/src/routes/canvas.ts
@@ -0,0 +1,54 @@
+import type { FastifyInstance } from "fastify";
+
+export function registerCanvasRoutes(
+  app: FastifyInstance,
+  deps: {
+    workspaceMgr: {
+      get(id: string): { path: string } | null | undefined;
+    };
+    canvasService: {
+      getCanvasData(input: {
+        workspaceId: string;
+        workspaceRootPath: string;
+        sourcePath?: string;
+        canvasId?: string;
+      }): Promise<unknown>;
+    };
+  }
+): void {
+  app.get("/api/canvas/:workspaceId/data", async (request, reply) => {
+    const { workspaceId } = request.params as {
+      workspaceId: string;
+    };
+    const { sourcePath } = request.query as {
+      sourcePath?: string;
+    };
+    const workspace = deps.workspaceMgr.get(workspaceId);
+    if (!workspace) {
+      return reply.status(404).send({ error: "workspace_not_found" });
+    }
+
+    if (!sourcePath) {
+      return reply.status(400).send({ error: "source_path_required" });
+    }
+
+    try {
+      const data = await deps.canvasService.getCanvasData({
+        workspaceId,
+        workspaceRootPath: workspace.path,
+        sourcePath,
+      });
+      return reply.send(data);
+    } catch (error) {
+      if ((error as { code?: string })?.code === "path_escape") {
+        return reply.status(400).send({ error: "path_escape" });
+      }
+
+      if ((error as { code?: string })?.code === "canvas_not_found") {
+        return reply.status(404).send({ error: "canvas_not_found" });
+      }
+
+      throw error;
+    }
+  });
+}
diff --git a/packages/server/src/routes/dev-browser.test.ts b/packages/server/src/routes/dev-browser.test.ts
deleted file mode 100644
index b8d4cd114..000000000
--- a/packages/server/src/routes/dev-browser.test.ts
+++ /dev/null
@@ -1,729 +0,0 @@
-import {
-  type AddressInfo,
-  createServer as createNetServer,
-  type Socket as NetSocket,
-} from "node:net";
-import websocket from "@fastify/websocket";
-import Fastify from "fastify";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { WebSocket as ClientWebSocket, type RawData, type WebSocket as WsWebSocket } from "ws";
-import { DevBrowserSessionStore } from "../dev-browser/session-store.js";
-import { registerDevBrowserRoutes } from "./dev-browser.js";
-
-function waitForMessage(socket: WsWebSocket): Promise<{ data: RawData; isBinary: boolean }> {
-  return new Promise((resolve, reject) => {
-    const handleMessage = (data: RawData, isBinary: boolean) => {
-      cleanup();
-      resolve({ data, isBinary });
-    };
-    const handleError = (error: Error) => {
-      cleanup();
-      reject(error);
-    };
-    const handleClose = (code: number, reason: Buffer) => {
-      cleanup();
-      reject(new Error(`socket closed before message: ${code} ${reason.toString()}`));
-    };
-    const cleanup = () => {
-      socket.off("message", handleMessage);
-      socket.off("error", handleError);
-      socket.off("close", handleClose);
-    };
-
-    socket.on("message", handleMessage);
-    socket.on("error", handleError);
-    socket.on("close", handleClose);
-  });
-}
-
-function waitForClose(socket: WsWebSocket): Promise<{ code: number; reason: string }> {
-  return new Promise((resolve, reject) => {
-    const handleClose = (code: number, reason: Buffer) => {
-      cleanup();
-      resolve({ code, reason: reason.toString() });
-    };
-    const handleError = (error: Error) => {
-      cleanup();
-      reject(error);
-    };
-    const cleanup = () => {
-      socket.off("close", handleClose);
-      socket.off("error", handleError);
-    };
-
-    socket.on("close", handleClose);
-    socket.on("error", handleError);
-  });
-}
-
-async function waitForExpectation(
-  check: () => void,
-  timeoutMs = 1000,
-  intervalMs = 20
-): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-
-  while (Date.now() < deadline) {
-    try {
-      check();
-      return;
-    } catch {
-      await new Promise((resolve) => setTimeout(resolve, intervalMs));
-    }
-  }
-
-  check();
-}
-
-describe("dev browser routes", () => {
-  let target: ReturnType<typeof Fastify>;
-  let app: ReturnType<typeof Fastify>;
-  let targetOrigin: string;
-  let targetPort: number;
-  let observedUpstreamClose: { code: number; reason: string } | null;
-  let observedHttpUserAgent: string | undefined;
-  let observedWsUserAgent: string | undefined;
-
-  beforeEach(async () => {
-    observedUpstreamClose = null;
-    observedHttpUserAgent = undefined;
-    observedWsUserAgent = undefined;
-    target = Fastify({ logger: false });
-    await target.register(websocket, {
-      options: {
-        handleProtocols: (protocols, request) => {
-          if (request.url?.startsWith("/ws-protocol")) {
-            return protocols.has("superjson") ? "superjson" : protocols.values().next().value;
-          }
-          return protocols.values().next().value;
-        },
-      },
-    });
-    target.addContentTypeParser(
-      "application/x-www-form-urlencoded",
-      { parseAs: "buffer" },
-      (_request, body, done) => {
-        done(null, body);
-      }
-    );
-    target.get("/app/", async (_request, reply) =>
-      reply
-        .type("text/html")
-        .send(
-          '<!doctype html><html><head><link rel="stylesheet" href="/assets/app.css"></head><body><img src="/images/logo.png"><a href="/docs">docs</a><form action="/submit" method="post"></form><script src="/assets/app.js"></script></body></html>'
-        )
-    );
-    target.get("/vite/", async (_request, reply) =>
-      reply.type("text/html").send(`<!DOCTYPE html>
-<html lang="zh-CN">
-  <head>
-    <script type="module">import { injectIntoGlobalHook } from "/@react-refresh";
-injectIntoGlobalHook(window);</script>
-    <script type="module" src="/@vite/client"></script>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>`)
-    );
-    target.get("/studio/", async (_request, reply) =>
-      reply.type("text/html").send(`<!DOCTYPE html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="description" content="Coder Studio - Agent-First Development Environment" />
-    <title>Coder Studio</title>
-    <script type="module" src="/src/main.tsx"></script>
-  </head>
-  <body>
-    <div id="root"></div>
-  </body>
-</html>`)
-    );
-    target.get("/assets/app.css", async (_request, reply) =>
-      reply
-        .type("text/css")
-        .send(
-          `body{background-image:url("/images/bg.png")} .logo{background-image:url("http://localhost:${targetPort}/images/abs.png")} .icon{background-image:url(./icon.svg)}`
-        )
-    );
-    target.get("/@vite/client", async (_request, reply) =>
-      reply
-        .type("application/javascript")
-        .send('import "/src/vite-setup.ts"; export const base = "/";')
-    );
-    target.get("/assets/app.js", async (_request, reply) =>
-      reply.type("application/javascript").send("window.loaded = true;")
-    );
-    target.get("/observe-user-agent", async (request) => {
-      observedHttpUserAgent = request.headers["user-agent"];
-      return { userAgent: observedHttpUserAgent ?? null };
-    });
-    target.get("/ws", { websocket: true }, (socket) => {
-      socket.on("message", (message, isBinary) => {
-        socket.send(message, { binary: isBinary });
-      });
-    });
-    target.get("/ws-observe-user-agent", { websocket: true }, (socket, request) => {
-      observedWsUserAgent = request.headers["user-agent"];
-      socket.send(`user-agent:${observedWsUserAgent ?? ""}`);
-    });
-    target.get("/ws-protocol", { websocket: true }, (socket) => {
-      socket.send(`protocol:${socket.protocol}`);
-      socket.on("message", (message, isBinary) => {
-        socket.send(message, { binary: isBinary });
-      });
-    });
-    target.get("/ws-close", { websocket: true }, (socket) => {
-      socket.close(4001, "upstream_done");
-    });
-    target.get("/ws-observe-close", { websocket: true }, (socket) => {
-      socket.send("ready");
-      socket.on("close", (code, reason) => {
-        observedUpstreamClose = {
-          code,
-          reason: reason.toString(),
-        };
-      });
-    });
-    target.get("/src/main.tsx", async (_request, reply) =>
-      reply
-        .type("application/javascript")
-        .send(`import React from "/node_modules/.vite/deps/react.js?v=1";
-import App from "/src/App.tsx";
-const lazy = () => import("/src/lazy.tsx");
-console.log(React, App, lazy);`)
-    );
-    target.post("/api/echo", async (request) => request.body);
-    target.post("/api/form", async (request) => ({
-      body: Buffer.isBuffer(request.body)
-        ? request.body.toString("utf-8")
-        : String(request.body ?? ""),
-      contentType: request.headers["content-type"],
-    }));
-    target.get("/redirect", async (_request, reply) => reply.redirect("/app/"));
-    target.get("/*", async (request) => ({ url: request.url }));
-    await target.listen({ host: "127.0.0.1", port: 0 });
-
-    const address = target.server.address();
-    if (!address || typeof address === "string") {
-      throw new Error("target listen failed");
-    }
-    targetPort = address.port;
-    targetOrigin = `http://127.0.0.1:${address.port}`;
-
-    app = Fastify({ logger: false });
-    await app.register(websocket);
-    registerDevBrowserRoutes(app, {
-      sessions: new DevBrowserSessionStore(),
-    });
-    await app.ready();
-  });
-
-  afterEach(async () => {
-    await app.close();
-    await target.close();
-  });
-
-  async function createSession(
-    path = "/app/",
-    options: {
-      userAgent?: string;
-    } = {}
-  ) {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/dev-proxy/session",
-      payload: { url: `${targetOrigin}${path}`, ...options },
-    });
-    expect(response.statusCode).toBe(200);
-    return response.json() as {
-      browserProxyBase: string;
-      browserUrl: string;
-      id: string;
-      targetOrigin: string;
-    };
-  }
-
-  it("creates sessions for loopback targets", async () => {
-    const created = await createSession();
-
-    expect(created.id).toMatch(/^dev_/);
-    expect(created.browserUrl).toBe(`/dev-browser/session/${created.id}/`);
-    expect(created.browserProxyBase).toBe(`/dev-browser/session/${created.id}/proxy`);
-    expect(created.targetOrigin).toBe(targetOrigin);
-  });
-
-  it("rejects invalid session targets", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/dev-proxy/session",
-      payload: { url: "http://example.com:8000" },
-    });
-
-    expect(response.statusCode).toBe(400);
-    expect(response.json()).toMatchObject({ error: "invalid_dev_browser_target" });
-  });
-
-  it("serves shell HTML that registers the service worker", async () => {
-    const created = await createSession();
-    const response = await app.inject({
-      method: "GET",
-      url: created.browserUrl,
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.headers["content-type"]).toContain("text/html");
-    expect(response.body).toContain("/dev-browser-sw.js");
-    expect(response.body).toContain(created.browserProxyBase);
-    expect(response.body).toContain(
-      "window.location.replace(session.browserProxyBase + session.targetPath + session.targetHash)"
-    );
-    expect(response.body).toContain(
-      "window.location.replace(session.browserProxyBase + session.targetPath + session.targetHash)"
-    );
-  });
-
-  it("proxies HTML and injects a websocket failure warning bootstrap without blocking page load", async () => {
-    const userAgent =
-      "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 Version/17.5 Mobile/15E148 Safari/604.1";
-    const created = await createSession("/app/", { userAgent });
-    const response = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}/app/`,
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.headers["content-type"]).toContain("text/html");
-    expect(response.body).toContain("Coder Studio dev browser could not connect to a WebSocket");
-    expect(response.body).toContain("coder-studio-dev-browser-websocket-warning");
-    expect(response.body).toContain("function toProxyWebSocketUrl(value, base)");
-    expect(response.body).toContain(
-      "const proxyUrl = resolvedUrl ?? toProxyWebSocketUrl(value, window.location.href);"
-    );
-    expect(response.body).toContain("function isCoderStudioPlatformPath(pathname) {");
-    expect(response.body).toContain('pathname === "/healthz"');
-    expect(response.body).toContain('pathname === "/ws"');
-    expect(response.body).toContain('pathname.startsWith("/auth/")');
-    expect(response.body).toContain('pathname.startsWith("/api/")');
-    expect(response.body).toContain("const currentPort =");
-    expect(response.body).toContain("const samePortAsStudio = currentPort === targetPort;");
-    const httpProxyStart = response.body.indexOf("function shouldProxyUrl(url) {");
-    const httpProxyEnd = response.body.indexOf("function shouldProxyWebSocketUrl(url) {");
-    const httpProxyBody = response.body.slice(httpProxyStart, httpProxyEnd);
-    expect(httpProxyBody).toContain(
-      "if ((samePortAsStudio || preserveStudioPlatformPaths) && isCoderStudioPlatformPath(url.pathname)) {"
-    );
-    const webSocketProxyStart = response.body.indexOf("function shouldProxyWebSocketUrl(url) {");
-    const webSocketProxyEnd = response.body.indexOf("function toProxyUrl(value, base) {");
-    const webSocketProxyBody = response.body.slice(webSocketProxyStart, webSocketProxyEnd);
-    expect(webSocketProxyBody).toContain("if (url.host === window.location.host) {");
-    expect(webSocketProxyBody).toContain('return !url.pathname.startsWith("/dev-browser/");');
-    expect(response.body).toContain('window.location.protocol === "https:" ? "wss:" : "ws:"');
-    expect(response.body).toContain("const navigatorOverrides = {");
-    expect(response.body).toContain("userAgent: navigatorUserAgent");
-    expect(response.body).toContain(userAgent);
-    expect(response.body).toContain("platform: /iPhone|iPad|iPod/.test(navigatorUserAgent)");
-    expect(response.body).toContain("maxTouchPoints: /Mobile|Android|iPhone|iPad|iPod/.test(");
-    expect(response.body).toContain("Object.defineProperty(window.navigator, key, {");
-    expect(response.body).not.toContain("throw new Error");
-    expect(response.body).toContain(
-      `<script src="${created.browserProxyBase}/assets/app.js"></script>`
-    );
-    expect(response.body).toContain(
-      `<link rel="stylesheet" href="${created.browserProxyBase}/assets/app.css">`
-    );
-    expect(response.body).toContain(`<img src="${created.browserProxyBase}/images/logo.png">`);
-    expect(response.body).toContain(`<a href="${created.browserProxyBase}/docs">docs</a>`);
-    expect(response.body).toContain(
-      `<form action="${created.browserProxyBase}/submit" method="post"></form>`
-    );
-  });
-
-  it("rewrites css url references for root-relative and loopback absolute assets", async () => {
-    const created = await createSession();
-    const response = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}/assets/app.css`,
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.headers["content-type"]).toContain("text/css");
-    expect(response.body).toContain(`url("${created.browserProxyBase}/images/bg.png")`);
-    expect(response.body).toContain(`url("${created.browserProxyBase}/images/abs.png")`);
-    expect(response.body).toContain("url(./icon.svg)");
-  });
-
-  it("rewrites inline module imports in html for fallback mode", async () => {
-    const created = await createSession("/vite/");
-    const response = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}/vite/`,
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.headers["content-type"]).toContain("text/html");
-    expect(response.body).toContain(
-      `import { injectIntoGlobalHook } from "${created.browserProxyBase}/@react-refresh";`
-    );
-    expect(response.body).toContain(
-      `<script type="module" src="${created.browserProxyBase}/@vite/client"></script>`
-    );
-    expect(response.body).toContain(
-      `<script type="module" src="${created.browserProxyBase}/src/main.tsx"></script>`
-    );
-    expect(response.body.indexOf("function toProxyWebSocketUrl(value, base)")).toBeGreaterThan(-1);
-    expect(response.body.indexOf("function toProxyWebSocketUrl(value, base)")).toBeLessThan(
-      response.body.indexOf(
-        `<script type="module" src="${created.browserProxyBase}/@vite/client"></script>`
-      )
-    );
-  });
-
-  it("preserves coder studio platform paths in fallback mode for cross-port studio previews", async () => {
-    const created = await createSession("/studio/");
-    const response = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}/studio/`,
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.headers["content-type"]).toContain("text/html");
-    expect(response.body).toContain("preserveStudioPlatformPaths");
-    expect(response.body).toContain(
-      "if ((samePortAsStudio || preserveStudioPlatformPaths) && isCoderStudioPlatformPath(url.pathname)) {"
-    );
-    expect(response.body).toContain("function toPreservedStudioWebSocketUrl(value, base) {");
-    expect(response.body).toContain(
-      'if (!preserveStudioPlatformPaths || !loopbackHosts.has(parsed.hostname) || parsed.pathname !== "/ws") {'
-    );
-    expect(response.body).toContain(
-      "const resolvedUrl = toPreservedStudioWebSocketUrl(value, window.location.href);"
-    );
-    expect(response.body).toContain(
-      "const proxyUrl = resolvedUrl ?? toProxyWebSocketUrl(value, window.location.href);"
-    );
-  });
-
-  it("keeps the visible history path on the target route in fallback mode", async () => {
-    const created = await createSession("/vite/");
-    const response = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}/vite/`,
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.body).toContain('const visiblePath = session.targetPath || "/";');
-    expect(response.body).toContain(
-      'nativeReplaceState(window.history.state, "", visiblePath + window.location.hash);'
-    );
-    expect(response.body).not.toContain("coderStudioDevBrowserPushState");
-    expect(response.body).not.toContain("coderStudioDevBrowserReplaceState");
-  });
-
-  it("rewrites absolute esm imports inside javascript module responses", async () => {
-    const created = await createSession("/vite/");
-    const response = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}/src/main.tsx`,
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.headers["content-type"]).toContain("javascript");
-    expect(response.body).toContain(
-      `import React from "${created.browserProxyBase}/node_modules/.vite/deps/react.js?v=1";`
-    );
-    expect(response.body).toContain(`import App from "${created.browserProxyBase}/src/App.tsx";`);
-    expect(response.body).toContain(`import("${created.browserProxyBase}/src/lazy.tsx")`);
-  });
-
-  it("proxies static assets and JSON posts", async () => {
-    const created = await createSession();
-    const asset = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}/assets/app.js`,
-    });
-    const post = await app.inject({
-      method: "POST",
-      url: `${created.browserProxyBase}/api/echo`,
-      headers: { "content-type": "application/json" },
-      payload: { ok: true },
-    });
-
-    expect(asset.statusCode).toBe(200);
-    expect(asset.headers["content-type"]).toContain("javascript");
-    expect(asset.body).toContain("window.loaded");
-    expect(post.statusCode).toBe(200);
-    expect(post.json()).toEqual({ ok: true });
-  });
-
-  it("proxies non-JSON request bodies without rewriting them", async () => {
-    const created = await createSession();
-    const response = await app.inject({
-      method: "POST",
-      url: `${created.browserProxyBase}/api/form`,
-      headers: { "content-type": "application/x-www-form-urlencoded" },
-      payload: "name=a%2Bb&ok=1",
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.json()).toEqual({
-      body: "name=a%2Bb&ok=1",
-      contentType: "application/x-www-form-urlencoded",
-    });
-  });
-
-  it("forwards the session user-agent on proxied http requests", async () => {
-    const userAgent =
-      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/125.0.0.0 Safari/537.36";
-    const created = await createSession("/observe-user-agent", { userAgent });
-    const response = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}/observe-user-agent`,
-      headers: {
-        "user-agent": "Coder Studio Test Browser",
-      },
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.json()).toEqual({ userAgent });
-    expect(observedHttpUserAgent).toBe(userAgent);
-  });
-
-  it("keeps protocol-relative-looking proxy paths on the session target", async () => {
-    const created = await createSession();
-    const response = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}//127.0.0.1:1/escape`,
-    });
-
-    expect(response.statusCode).toBe(200);
-    expect(response.json()).toEqual({ url: "//127.0.0.1:1/escape" });
-  });
-
-  it("rewrites loopback redirects to browser proxy paths", async () => {
-    const created = await createSession("/redirect");
-    const response = await app.inject({
-      method: "GET",
-      url: `${created.browserProxyBase}/redirect`,
-    });
-
-    expect(response.statusCode).toBeGreaterThanOrEqual(300);
-    expect(response.statusCode).toBeLessThan(400);
-    expect(response.headers.location).toBe(`${created.browserProxyBase}/app/`);
-  });
-
-  it("proxies websocket text and binary frames", async () => {
-    const created = await createSession();
-    const socket = await app.injectWS(`${created.browserProxyBase}/ws`);
-    const textResponsePromise = waitForMessage(socket);
-    socket.send("hello over proxy");
-    const textResponse = await textResponsePromise;
-
-    expect(textResponse.isBinary).toBe(false);
-    expect(textResponse.data.toString()).toBe("hello over proxy");
-
-    const binaryPayload = Buffer.from([0x00, 0x01, 0x02, 0x03]);
-    const binaryResponsePromise = waitForMessage(socket);
-    socket.send(binaryPayload, { binary: true });
-    const binaryResponse = await binaryResponsePromise;
-
-    expect(binaryResponse.isBinary).toBe(true);
-    expect(Buffer.from(binaryResponse.data)).toEqual(binaryPayload);
-
-    socket.close();
-    await waitForClose(socket);
-  });
-
-  it("forwards the session user-agent on proxied websocket upgrades", async () => {
-    const userAgent =
-      "Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36 Chrome/125.0.0.0 Mobile Safari/537.36";
-    const created = await createSession("/app/", { userAgent });
-    const socket = await app.injectWS(`${created.browserProxyBase}/ws-observe-user-agent`);
-
-    await expect(waitForMessage(socket)).resolves.toEqual({
-      data: Buffer.from(`user-agent:${userAgent}`),
-      isBinary: false,
-    });
-    expect(observedWsUserAgent).toBe(userAgent);
-
-    socket.close();
-    await waitForClose(socket);
-  });
-
-  it("propagates upstream websocket closes", async () => {
-    const created = await createSession();
-    const socket = await app.injectWS(`${created.browserProxyBase}/ws-close`);
-
-    await expect(waitForClose(socket)).resolves.toEqual({
-      code: 4001,
-      reason: "upstream_done",
-    });
-  });
-
-  it("closes the browser websocket when the upstream websocket is unavailable", async () => {
-    const created = await createSession();
-    const socket = await app.injectWS(`${created.browserProxyBase}/missing-ws`);
-
-    await expect(waitForClose(socket)).resolves.toEqual({
-      code: 1014,
-      reason: "dev_browser_target_unavailable",
-    });
-  });
-
-  it("proxies the websocket subprotocol selected by the upstream target", async () => {
-    const created = await createSession();
-    await app.listen({ host: "127.0.0.1", port: 0 });
-    const address = app.server.address();
-    if (!address || typeof address === "string") {
-      throw new Error("proxy app listen failed");
-    }
-
-    const socket = await new Promise<WsWebSocket>((resolve, reject) => {
-      const ws = new ClientWebSocket(
-        `ws://127.0.0.1:${address.port}${created.browserProxyBase}/ws-protocol`,
-        ["json", "superjson"]
-      );
-      const firstMessagePromise = waitForMessage(ws);
-
-      ws.once("open", async () => {
-        try {
-          expect(ws.protocol).toBe("superjson");
-          await expect(firstMessagePromise).resolves.toEqual({
-            data: Buffer.from("protocol:superjson"),
-            isBinary: false,
-          });
-          resolve(ws);
-        } catch (error) {
-          reject(error);
-        }
-      });
-      ws.once("error", reject);
-      ws.once("close", (code, reason) =>
-        reject(new Error(`socket closed before open: ${code} ${reason.toString()}`))
-      );
-      ws.once("unexpected-response", (_request, response) =>
-        reject(new Error(`unexpected response: ${response.statusCode}`))
-      );
-    });
-    socket.close();
-    await waitForClose(socket);
-  });
-
-  it("falls back to the first browser websocket protocol when the upstream target does not override it", async () => {
-    const created = await createSession();
-    await app.listen({ host: "127.0.0.1", port: 0 });
-    const address = app.server.address();
-    if (!address || typeof address === "string") {
-      throw new Error("proxy app listen failed");
-    }
-
-    const socket = await new Promise<WsWebSocket>((resolve, reject) => {
-      const ws = new ClientWebSocket(
-        `ws://127.0.0.1:${address.port}${created.browserProxyBase}/ws`,
-        ["json", "superjson"]
-      );
-
-      ws.once("open", () => {
-        try {
-          expect(ws.protocol).toBe("json");
-          resolve(ws);
-        } catch (error) {
-          reject(error);
-        }
-      });
-      ws.once("error", reject);
-      ws.once("close", (code, reason) =>
-        reject(new Error(`socket closed before open: ${code} ${reason.toString()}`))
-      );
-      ws.once("unexpected-response", (_request, response) =>
-        reject(new Error(`unexpected response: ${response.statusCode}`))
-      );
-    });
-
-    const messagePromise = waitForMessage(socket);
-    socket.send("hello over first-protocol proxy");
-    await expect(messagePromise).resolves.toEqual({
-      data: Buffer.from("hello over first-protocol proxy"),
-      isBinary: false,
-    });
-
-    socket.close();
-    await waitForClose(socket);
-  });
-
-  it("bounds buffered browser frames while the upstream websocket is still connecting", async () => {
-    const pendingSockets = new Set<NetSocket>();
-    const stalledServer = createNetServer((socket) => {
-      pendingSockets.add(socket);
-      socket.on("close", () => {
-        pendingSockets.delete(socket);
-      });
-    });
-    await new Promise<void>((resolve, reject) => {
-      stalledServer.once("error", reject);
-      stalledServer.listen(0, "127.0.0.1", () => resolve());
-    });
-
-    try {
-      const address = stalledServer.address();
-      if (!address || typeof address === "string") {
-        throw new Error("stalled websocket server failed to bind");
-      }
-
-      const response = await app.inject({
-        method: "POST",
-        url: "/api/dev-proxy/session",
-        payload: { url: `http://127.0.0.1:${(address as AddressInfo).port}/ws-stall` },
-      });
-      expect(response.statusCode).toBe(200);
-
-      const created = response.json() as {
-        browserProxyBase: string;
-      };
-      const socket = await app.injectWS(`${created.browserProxyBase}/ws-stall`);
-
-      socket.send(Buffer.alloc(70 * 1024, 1), { binary: true });
-
-      await expect(waitForClose(socket)).resolves.toEqual({
-        code: 1009,
-        reason: "dev_browser_websocket_buffer_overflow",
-      });
-    } finally {
-      for (const pendingSocket of pendingSockets) {
-        pendingSocket.destroy();
-      }
-      await new Promise<void>((resolve, reject) => {
-        stalledServer.close((error) => {
-          if (error) {
-            reject(error);
-            return;
-          }
-          resolve();
-        });
-      });
-    }
-  });
-
-  it("closes the upstream websocket cleanly when the browser socket terminates abnormally", async () => {
-    const created = await createSession();
-    const socket = await app.injectWS(`${created.browserProxyBase}/ws-observe-close`);
-    const readyMessage = await waitForMessage(socket);
-
-    expect(readyMessage.isBinary).toBe(false);
-    expect(readyMessage.data.toString()).toBe("ready");
-
-    socket.terminate();
-
-    await waitForExpectation(() => {
-      expect(observedUpstreamClose).not.toBeNull();
-    });
-  });
-
-  it("rejects websocket upgrades for missing dev-browser sessions", async () => {
-    await expect(app.injectWS("/dev-browser/session/missing/proxy/ws")).rejects.toThrow(
-      "Unexpected server response: 404"
-    );
-  });
-});
diff --git a/packages/server/src/routes/dev-browser.ts b/packages/server/src/routes/dev-browser.ts
deleted file mode 100644
index 77038df20..000000000
--- a/packages/server/src/routes/dev-browser.ts
+++ /dev/null
@@ -1,925 +0,0 @@
-import type { IncomingMessage } from "node:http";
-import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
-import { type RawData, WebSocket as WsWebSocket } from "ws";
-import { z } from "zod";
-import {
-  buildProxyWebSocketRequestOptions,
-  filterProxyRequestHeaders,
-  filterProxyResponseHeaders,
-  rewriteProxyLocationHeader,
-  rewriteProxyUrlReference,
-} from "../dev-browser/proxy-headers.js";
-import type { DevBrowserSession } from "../dev-browser/session-store.js";
-import { DevBrowserSessionStore } from "../dev-browser/session-store.js";
-import { DevBrowserTargetUrlError, parseDevBrowserTargetUrl } from "../dev-browser/target-url.js";
-
-const createSessionSchema = z.object({
-  url: z.string().min(1),
-  userAgent: z.string().min(1).optional(),
-});
-const MAX_PENDING_WEBSOCKET_BYTES = 64 * 1024;
-const preparedProxyWebSockets = new WeakMap<IncomingMessage, PreparedProxyWebSocket>();
-
-interface PreparedProxyWebSocket {
-  upstream: WsWebSocket;
-  selectedProtocol: string;
-  browserSocket: WsWebSocket | null;
-  closeBrowser: ((code: number, reason: string) => void) | null;
-  bufferedMessages: Array<{ data: RawData; isBinary: boolean }>;
-  bufferedClose: { code: number; reason: Buffer } | null;
-  bufferedError: boolean;
-  upstreamClosed: boolean;
-  upstreamReceivedMessage: boolean;
-}
-
-function browserProxyBase(id: string): string {
-  return `/dev-browser/session/${id}/proxy`;
-}
-
-function browserUrl(id: string): string {
-  return `/dev-browser/session/${id}/`;
-}
-
-function serializeSession(session: DevBrowserSession) {
-  return {
-    id: session.id,
-    browserUrl: browserUrl(session.id),
-    browserProxyBase: browserProxyBase(session.id),
-    displayUrl: session.displayUrl,
-    targetOrigin: session.targetOrigin,
-    targetPath: session.targetPath,
-    targetHash: session.targetHash,
-    expiresAt: session.expiresAt,
-    ...(session.preserveStudioPlatformPaths ? { preserveStudioPlatformPaths: true } : {}),
-  };
-}
-
-function isCoderStudioHtml(html: string): boolean {
-  return (
-    html.includes("<title>Coder Studio</title>") ||
-    html.includes('content="Coder Studio - Agent-First Development Environment"')
-  );
-}
-
-function escapeJsonForScript(value: unknown): string {
-  return JSON.stringify(value).replaceAll("<", "\\u003c");
-}
-
-function renderDevBrowserShell(session: DevBrowserSession): string {
-  const payload = serializeSession(session);
-  return `<!doctype html>
-<html>
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>Coder Studio Dev Browser</title>
-</head>
-<body>
-  <p>Opening local preview...</p>
-  <script>
-    const session = ${escapeJsonForScript(payload)};
-    function fallbackToProxyMode() {
-      window.location.replace(session.browserProxyBase + session.targetPath + session.targetHash);
-    }
-    async function openDevBrowserSession() {
-      if (!("serviceWorker" in navigator) || !window.isSecureContext) {
-        fallbackToProxyMode();
-        return;
-      }
-      const registration = await navigator.serviceWorker.register("/dev-browser-sw.js", { scope: "/dev-browser/" });
-      await navigator.serviceWorker.ready;
-      const worker = registration.active || registration.waiting || registration.installing;
-      worker?.postMessage({ type: "coder-studio-dev-browser-session", session });
-      fallbackToProxyMode();
-    }
-    openDevBrowserSession().catch((error) => {
-      console.error(error);
-      fallbackToProxyMode();
-    });
-  </script>
-</body>
-</html>`;
-}
-
-function createHtmlBootstrap(session: DevBrowserSession): string {
-  const payload = serializeSession(session);
-  return `<script>
-(function () {
-  const session = ${escapeJsonForScript(payload)};
-  const browserProxyBase = session.browserProxyBase;
-  const targetOrigin = session.targetOrigin;
-  const visiblePath = session.targetPath || "/";
-  const targetPort = new URL(targetOrigin).port || "80";
-  const currentPort =
-    window.location.port || (window.location.protocol === "https:" ? "443" : "80");
-  const samePortAsStudio = currentPort === targetPort;
-  const preserveStudioPlatformPaths = session.preserveStudioPlatformPaths === true;
-  const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
-  function isCoderStudioPlatformPath(pathname) {
-    return (
-      pathname === "/api" ||
-      pathname.startsWith("/api/") ||
-      pathname === "/auth" ||
-      pathname.startsWith("/auth/") ||
-      pathname === "/healthz" ||
-      pathname === "/internal" ||
-      pathname.startsWith("/internal/") ||
-      pathname === "/ws"
-    );
-  }
-  function shouldProxyUrl(url) {
-    if (!url) {
-      return false;
-    }
-    if (url.host === window.location.host) {
-      if (url.pathname.startsWith("/dev-browser/")) {
-        return false;
-      }
-      if ((samePortAsStudio || preserveStudioPlatformPaths) && isCoderStudioPlatformPath(url.pathname)) {
-        return false;
-      }
-      return true;
-    }
-    return url.protocol === "http:" && loopbackHosts.has(url.hostname) && (url.port || "80") === targetPort;
-  }
-  function shouldProxyWebSocketUrl(url) {
-    if (!url) {
-      return false;
-    }
-    if (url.protocol !== "ws:" && url.protocol !== "wss:") {
-      return false;
-    }
-    if (url.host === window.location.host) {
-      if (url.pathname === "/ws") {
-        return true;
-      }
-      return !url.pathname.startsWith("/dev-browser/");
-    }
-    const port = url.port || (url.protocol === "wss:" ? "443" : "80");
-    return loopbackHosts.has(url.hostname) && port === targetPort;
-  }
-  function toProxyUrl(value, base) {
-    if (typeof value !== "string" || value.length === 0) {
-      return null;
-    }
-    let parsed;
-    try {
-      parsed = new URL(value, base || window.location.href);
-    } catch {
-      return null;
-    }
-    if (!shouldProxyUrl(parsed)) {
-      return null;
-    }
-    return window.location.origin + browserProxyBase + parsed.pathname + parsed.search + parsed.hash;
-  }
-  function toProxyWebSocketUrl(value, base) {
-    if (typeof value !== "string" || value.length === 0) {
-      return null;
-    }
-    let parsed;
-    try {
-      parsed = new URL(value, base || window.location.href);
-    } catch {
-      return null;
-    }
-    if (!shouldProxyWebSocketUrl(parsed)) {
-      return null;
-    }
-    const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-    return protocol + "//" + window.location.host + browserProxyBase + parsed.pathname + parsed.search + parsed.hash;
-  }
-  function toPreservedStudioWebSocketUrl(value, base) {
-    if (typeof value !== "string" || value.length === 0) {
-      return null;
-    }
-    let parsed;
-    try {
-      parsed = new URL(value, base || window.location.href);
-    } catch {
-      return null;
-    }
-    if (!preserveStudioPlatformPaths || !loopbackHosts.has(parsed.hostname) || parsed.pathname !== "/ws") {
-      return null;
-    }
-    const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-    return protocol + "//" + window.location.host + "/ws";
-  }
-  if (navigator.serviceWorker && navigator.serviceWorker.controller) {
-    navigator.serviceWorker.controller.postMessage({ type: "coder-studio-dev-browser-session", session });
-  }
-  const navigatorUserAgent = ${escapeJsonForScript(session.userAgent ?? null)};
-  if (navigatorUserAgent) {
-    const navigatorOverrides = {
-      userAgent: navigatorUserAgent,
-      platform: /iPhone|iPad|iPod/.test(navigatorUserAgent)
-        ? "iPhone"
-        : /Android/.test(navigatorUserAgent)
-          ? "Linux armv8l"
-          : /Macintosh|Mac OS X/.test(navigatorUserAgent)
-            ? "MacIntel"
-            : /Windows/.test(navigatorUserAgent)
-              ? "Win32"
-              : navigator.platform,
-      maxTouchPoints: /Mobile|Android|iPhone|iPad|iPod/.test(navigatorUserAgent)
-        ? Math.max(navigator.maxTouchPoints || 0, 5)
-        : navigator.maxTouchPoints,
-    };
-    for (const [key, value] of Object.entries(navigatorOverrides)) {
-      try {
-        Object.defineProperty(window.navigator, key, {
-          configurable: true,
-          value,
-        });
-      } catch {}
-    }
-  }
-  const warningId = "coder-studio-dev-browser-websocket-warning";
-  const warningText =
-    "Coder Studio dev browser could not connect to a WebSocket. The preview may load, but live updates can fail.";
-  let pendingWarningMessage = null;
-  function mountWebSocketWarning() {
-    if (!pendingWarningMessage || !document.body || document.getElementById(warningId)) {
-      return;
-    }
-    const warning = document.createElement("div");
-    warning.id = warningId;
-    warning.setAttribute("role", "alert");
-    warning.style.cssText =
-      "position:sticky;top:0;z-index:2147483647;padding:10px 14px;border-bottom:1px solid rgba(245,158,11,0.45);background:#2b2111;color:#fbbf24;font:12px/1.4 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif;";
-    warning.textContent = pendingWarningMessage;
-    document.body.prepend(warning);
-  }
-  function showWebSocketWarning(message) {
-    pendingWarningMessage = message;
-    if (document.body) {
-      mountWebSocketWarning();
-      return;
-    }
-    window.addEventListener("DOMContentLoaded", mountWebSocketWarning, { once: true });
-  }
-  const NativeWebSocket = window.WebSocket;
-  const nativeFetch = window.fetch.bind(window);
-  window.fetch = function coderStudioDevBrowserFetch(input, init) {
-    const request = input instanceof Request ? input : null;
-    const proxyUrl = toProxyUrl(request ? request.url : String(input), request ? undefined : window.location.href);
-    if (!proxyUrl) {
-      return nativeFetch(input, init);
-    }
-    if (request) {
-      return nativeFetch(new Request(proxyUrl, request), init);
-    }
-    return nativeFetch(proxyUrl, init);
-  };
-  const NativeXMLHttpRequestOpen = XMLHttpRequest.prototype.open;
-  XMLHttpRequest.prototype.open = function coderStudioDevBrowserOpen(method, url) {
-    const proxyUrl = toProxyUrl(String(url), window.location.href);
-    return NativeXMLHttpRequestOpen.call(
-      this,
-      method,
-      proxyUrl ?? url,
-      ...Array.prototype.slice.call(arguments, 2)
-    );
-  };
-  if (window.EventSource) {
-    const NativeEventSource = window.EventSource;
-    window.EventSource = function CoderStudioDevBrowserEventSource(url, configuration) {
-      const proxyUrl = toProxyUrl(String(url), window.location.href);
-      return new NativeEventSource(proxyUrl ?? url, configuration);
-    };
-    window.EventSource.prototype = NativeEventSource.prototype;
-    Object.setPrototypeOf(window.EventSource, NativeEventSource);
-  }
-  const nativeReplaceState = window.history.replaceState.bind(window.history);
-  try {
-    nativeReplaceState(window.history.state, "", visiblePath + window.location.hash);
-  } catch {}
-  const nativeOpen = window.open.bind(window);
-  window.open = function coderStudioDevBrowserOpenWindow(url, target, features) {
-    const proxyUrl = typeof url === "string" ? toProxyUrl(url, window.location.href) : null;
-    return nativeOpen(proxyUrl ?? url, target, features);
-  };
-  window.WebSocket = function CoderStudioDevBrowserWebSocket(url, protocols) {
-    const value = String(url);
-    const resolvedUrl = toPreservedStudioWebSocketUrl(value, window.location.href);
-    const proxyUrl = resolvedUrl ?? toProxyWebSocketUrl(value, window.location.href);
-    const socket = proxyUrl
-      ? arguments.length > 1
-        ? new NativeWebSocket(proxyUrl, protocols)
-        : new NativeWebSocket(proxyUrl)
-      : arguments.length > 1
-        ? new NativeWebSocket(url, protocols)
-        : new NativeWebSocket(url);
-    if (proxyUrl || /^wss?:\\/\\/(localhost|127\\.0\\.0\\.1|\\[::1\\])(?::\\d+)?\\b/.test(value)) {
-      let opened = false;
-      let warned = false;
-      const warn = function () {
-        if (warned) {
-          return;
-        }
-        warned = true;
-        console.warn("Coder Studio dev browser could not connect to a WebSocket.");
-        showWebSocketWarning(warningText);
-      };
-      socket.addEventListener("open", function () {
-        opened = true;
-      }, { once: true });
-      socket.addEventListener("error", function () {
-        warn();
-      }, { once: true });
-      socket.addEventListener("close", function (event) {
-        if (!opened || event.code !== 1000) {
-          warn();
-        }
-      }, { once: true });
-    }
-    return socket;
-  };
-  window.WebSocket.prototype = NativeWebSocket.prototype;
-  Object.setPrototypeOf(window.WebSocket, NativeWebSocket);
-})();
-</script>`;
-}
-
-function rewriteHtmlAttributes(html: string, session: DevBrowserSession): string {
-  const rewrite = (value: string) =>
-    rewriteProxyUrlReference(value, {
-      browserProxyBase: browserProxyBase(session.id),
-      port: session.port,
-      targetOrigin: session.targetOrigin,
-    });
-
-  return html.replace(
-    /\b(?:src|href|action)=("([^"]*)"|'([^']*)')/gi,
-    (match, quoted, doubleQuoted, singleQuoted) => {
-      const quote = quoted[0];
-      const value = doubleQuoted ?? singleQuoted ?? "";
-      const nextValue = rewrite(value);
-      return `${match.slice(0, match.indexOf(quoted))}${quote}${nextValue}${quote}`;
-    }
-  );
-}
-
-function rewriteJavaScriptModuleSpecifiers(source: string, session: DevBrowserSession): string {
-  const rewrite = (value: string) =>
-    rewriteProxyUrlReference(value, {
-      browserProxyBase: browserProxyBase(session.id),
-      port: session.port,
-      targetOrigin: session.targetOrigin,
-    });
-
-  const rewriteSpecifier = (quote: string, value: string) => `${quote}${rewrite(value)}${quote}`;
-
-  return source
-    .replace(
-      /\bimport\s*\(\s*(['"])([^'"]+)\1\s*\)/g,
-      (_match, quote: string, value: string) => `import(${rewriteSpecifier(quote, value)})`
-    )
-    .replace(
-      /\b(?:import|export)\s+(?:[^'"]*?\sfrom\s*)?(['"])([^'"]+)\1/g,
-      (match, quote: string, value: string) =>
-        match.replace(`${quote}${value}${quote}`, rewriteSpecifier(quote, value))
-    )
-    .replace(
-      /\bnew\s+URL\s*\(\s*(['"])([^'"]+)\1(\s*,\s*import\.meta\.url\s*\))/g,
-      (_match, quote: string, value: string, suffix: string) =>
-        `new URL(${rewriteSpecifier(quote, value)}${suffix}`
-    );
-}
-
-function rewriteInlineModuleScripts(html: string, session: DevBrowserSession): string {
-  return html.replace(
-    /<script\b([^>]*)>([\s\S]*?)<\/script>/gi,
-    (match, attrs: string, body: string) => {
-      if (!/\btype\s*=\s*["']module["']/i.test(attrs) || /\bsrc\s*=/i.test(attrs)) {
-        return match;
-      }
-
-      return `<script${attrs}>${rewriteJavaScriptModuleSpecifiers(body, session)}</script>`;
-    }
-  );
-}
-
-function injectHtmlBootstrap(html: string, session: DevBrowserSession): string {
-  const bootstrap = createHtmlBootstrap(session);
-  const rewrittenHtml = rewriteInlineModuleScripts(rewriteHtmlAttributes(html, session), session);
-  const headMatch = rewrittenHtml.match(/<head\b[^>]*>/i);
-  if (headMatch) {
-    const insertAt = headMatch.index! + headMatch[0].length;
-    return `${rewrittenHtml.slice(0, insertAt)}${bootstrap}${rewrittenHtml.slice(insertAt)}`;
-  }
-
-  const bodyMatch = rewrittenHtml.match(/<body\b[^>]*>/i);
-  if (bodyMatch) {
-    const insertAt = bodyMatch.index! + bodyMatch[0].length;
-    return `${rewrittenHtml.slice(0, insertAt)}${bootstrap}${rewrittenHtml.slice(insertAt)}`;
-  }
-
-  return `${bootstrap}${rewrittenHtml}`;
-}
-
-function rewriteCssUrls(css: string, session: DevBrowserSession): string {
-  return css.replace(
-    /url\(\s*(['"]?)([^)'"]+)\1\s*\)/gi,
-    (_match, quote: string, value: string) => {
-      const nextValue = rewriteProxyUrlReference(value, {
-        browserProxyBase: browserProxyBase(session.id),
-        port: session.port,
-        targetOrigin: session.targetOrigin,
-      });
-      return `url(${quote}${nextValue}${quote})`;
-    }
-  );
-}
-
-function bufferToBodyInit(buffer: Buffer): BodyInit {
-  const bytes = new Uint8Array(buffer.byteLength);
-  bytes.set(buffer);
-  return bytes;
-}
-
-function resolveProxyTargetUrl(session: DevBrowserSession, request: FastifyRequest): URL {
-  const incoming = new URL(request.url, "http://coder-studio.local");
-  const prefix = `/dev-browser/session/${session.id}/proxy`;
-  const path = incoming.pathname.startsWith(prefix)
-    ? incoming.pathname.slice(prefix.length) || "/"
-    : "/";
-  const targetUrl = new URL(session.targetOrigin);
-  targetUrl.pathname = path.startsWith("/") ? path : `/${path}`;
-  targetUrl.search = incoming.search;
-  return targetUrl;
-}
-
-function toWebSocketTargetUrl(targetUrl: URL): URL {
-  const upstreamUrl = new URL(targetUrl);
-  upstreamUrl.protocol = upstreamUrl.protocol === "https:" ? "wss:" : "ws:";
-  return upstreamUrl;
-}
-
-function getSessionFromRequest(
-  sessions: DevBrowserSessionStore,
-  request: FastifyRequest
-): DevBrowserSession | null {
-  const { id } = request.params as { id: string };
-  return sessions.get(id) ?? null;
-}
-
-function isValidCloseCode(code: number): boolean {
-  return (
-    code === 1000 ||
-    (code >= 3000 && code <= 4999) ||
-    (code >= 1001 && code <= 1014 && code !== 1004 && code !== 1005 && code !== 1006)
-  );
-}
-
-function rawDataByteLength(data: RawData): number {
-  if (Array.isArray(data)) {
-    return data.reduce((total, chunk) => total + chunk.byteLength, 0);
-  }
-
-  return data.byteLength;
-}
-
-function closeBrowserForUpstreamResult(
-  closeBrowser: (code: number, reason: string) => void,
-  result: { code: number; reason: Buffer },
-  upstreamReceivedMessage: boolean
-): void {
-  if (!upstreamReceivedMessage && result.code === 1005 && result.reason.length === 0) {
-    closeBrowser(1014, "dev_browser_target_unavailable");
-    return;
-  }
-
-  closeBrowser(result.code, result.reason.toString());
-}
-
-async function prepareProxyWebSocket(
-  request: FastifyRequest,
-  session: DevBrowserSession
-): Promise<PreparedProxyWebSocket | null> {
-  const targetUrl = toWebSocketTargetUrl(resolveProxyTargetUrl(session, request));
-  const { protocols, ...requestOptions } = buildProxyWebSocketRequestOptions(request.headers, {
-    userAgent: session.userAgent,
-  });
-  if (!protocols || protocols.length === 0) {
-    return null;
-  }
-
-  return await new Promise<PreparedProxyWebSocket>((resolve, reject) => {
-    const upstream = new WsWebSocket(targetUrl, protocols, requestOptions);
-    const prepared: PreparedProxyWebSocket = {
-      upstream,
-      selectedProtocol: "",
-      browserSocket: null,
-      closeBrowser: null,
-      bufferedMessages: [],
-      bufferedClose: null,
-      bufferedError: false,
-      upstreamClosed: false,
-      upstreamReceivedMessage: false,
-    };
-    let upstreamOpened = false;
-    let settled = false;
-
-    const rejectUnavailable = () => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      reject(new Error("dev_browser_target_unavailable"));
-    };
-
-    upstream.on("message", (data, isBinary) => {
-      prepared.upstreamReceivedMessage = true;
-      if (prepared.browserSocket?.readyState === WsWebSocket.OPEN) {
-        prepared.browserSocket.send(data, { binary: isBinary });
-        return;
-      }
-      prepared.bufferedMessages.push({ data, isBinary });
-    });
-
-    upstream.on("close", (code, reason) => {
-      prepared.upstreamClosed = true;
-      if (!upstreamOpened) {
-        rejectUnavailable();
-        return;
-      }
-      if (!prepared.closeBrowser) {
-        prepared.bufferedClose = { code, reason };
-        return;
-      }
-      closeBrowserForUpstreamResult(
-        prepared.closeBrowser,
-        { code, reason },
-        prepared.upstreamReceivedMessage
-      );
-    });
-
-    upstream.on("error", () => {
-      if (!upstreamOpened) {
-        rejectUnavailable();
-        return;
-      }
-      if (!prepared.closeBrowser) {
-        prepared.bufferedError = true;
-        return;
-      }
-      if (!prepared.upstreamClosed) {
-        prepared.closeBrowser(1011, "dev_browser_websocket_error");
-      }
-    });
-
-    upstream.once("open", () => {
-      upstreamOpened = true;
-      if (settled) {
-        return;
-      }
-      settled = true;
-      prepared.selectedProtocol = upstream.protocol;
-      resolve(prepared);
-    });
-  });
-}
-
-function bindPreparedProxyWebSocket(
-  prepared: PreparedProxyWebSocket,
-  browserSocket: WsWebSocket,
-  closeBrowser: (code: number, reason: string) => void,
-  closeUpstream: () => void
-): void {
-  prepared.browserSocket = browserSocket;
-  prepared.closeBrowser = closeBrowser;
-
-  for (const message of prepared.bufferedMessages.splice(0)) {
-    if (browserSocket.readyState !== WsWebSocket.OPEN) {
-      break;
-    }
-    browserSocket.send(message.data, { binary: message.isBinary });
-  }
-
-  if (prepared.bufferedClose) {
-    closeBrowserForUpstreamResult(
-      closeBrowser,
-      prepared.bufferedClose,
-      prepared.upstreamReceivedMessage
-    );
-    return;
-  }
-
-  if (prepared.bufferedError && !prepared.upstreamClosed) {
-    closeBrowser(1011, "dev_browser_websocket_error");
-    closeUpstream();
-  }
-}
-
-async function proxyRequest(
-  request: FastifyRequest,
-  reply: FastifyReply,
-  session: DevBrowserSession
-) {
-  const targetUrl = resolveProxyTargetUrl(session, request);
-  const targetHeaders = filterProxyRequestHeaders(request.headers, targetUrl.host, {
-    userAgent: session.userAgent,
-  });
-  const method = request.method.toUpperCase();
-  const init: RequestInit = {
-    method,
-    headers: targetHeaders,
-    redirect: "manual",
-  };
-
-  if (method !== "GET" && method !== "HEAD" && request.body !== undefined) {
-    if (Buffer.isBuffer(request.body)) {
-      init.body = bufferToBodyInit(request.body);
-    } else if (typeof request.body === "string") {
-      init.body = request.body;
-    } else {
-      init.body = JSON.stringify(request.body);
-      targetHeaders.set("content-type", "application/json");
-    }
-  }
-
-  let upstream: Response;
-  try {
-    upstream = await fetch(targetUrl, init);
-  } catch {
-    return reply.status(502).send({ error: "dev_browser_target_unavailable" });
-  }
-
-  const responseHeaders = filterProxyResponseHeaders(upstream.headers);
-  const location = upstream.headers.get("location");
-  if (location) {
-    responseHeaders.set(
-      "location",
-      rewriteProxyLocationHeader(location, {
-        browserProxyBase: browserProxyBase(session.id),
-        port: session.port,
-        targetOrigin: session.targetOrigin,
-      })
-    );
-  }
-
-  responseHeaders.forEach((value, key) => reply.header(key, value));
-  reply.status(upstream.status);
-
-  const contentType = upstream.headers.get("content-type") ?? "";
-  if (contentType.includes("text/html")) {
-    const html = await upstream.text();
-    const effectiveSession =
-      isCoderStudioHtml(html) && !session.preserveStudioPlatformPaths
-        ? { ...session, preserveStudioPlatformPaths: true }
-        : session;
-    return reply.type("text/html; charset=utf-8").send(injectHtmlBootstrap(html, effectiveSession));
-  }
-
-  if (contentType.includes("text/css")) {
-    const css = rewriteCssUrls(await upstream.text(), session);
-    return reply.type("text/css; charset=utf-8").send(css);
-  }
-
-  if (contentType.includes("javascript")) {
-    const script = rewriteJavaScriptModuleSpecifiers(await upstream.text(), session);
-    return reply.type("application/javascript; charset=utf-8").send(script);
-  }
-
-  return reply.send(Buffer.from(await upstream.arrayBuffer()));
-}
-
-function proxyWebSocket(
-  request: FastifyRequest,
-  browserSocket: WsWebSocket,
-  session: DevBrowserSession,
-  prepared: PreparedProxyWebSocket | null = null
-) {
-  const targetUrl = prepared ? null : toWebSocketTargetUrl(resolveProxyTargetUrl(session, request));
-  const { protocols, ...requestOptions } = prepared
-    ? { headers: {} }
-    : buildProxyWebSocketRequestOptions(request.headers, { userAgent: session.userAgent });
-  const upstream = prepared
-    ? prepared.upstream
-    : new WsWebSocket(targetUrl!, protocols, requestOptions);
-
-  let upstreamOpened = prepared !== null;
-  let browserClosed = false;
-  let upstreamClosed = prepared?.upstreamClosed ?? false;
-  let upstreamReceivedMessage = prepared?.upstreamReceivedMessage ?? false;
-  let pendingBytes = 0;
-  const pendingMessages: Array<{ data: RawData; isBinary: boolean }> = [];
-
-  const closeBrowser = (code: number, reason: string) => {
-    if (browserClosed) {
-      return;
-    }
-    browserClosed = true;
-    if (isValidCloseCode(code)) {
-      browserSocket.close(code, reason);
-      return;
-    }
-    browserSocket.close();
-  };
-
-  const closeUpstream = (code?: number, reason?: Buffer) => {
-    if (prepared ? prepared.upstreamClosed : upstreamClosed) {
-      return;
-    }
-    if (prepared) {
-      prepared.upstreamClosed = true;
-    } else {
-      upstreamClosed = true;
-    }
-    if (code === undefined || !isValidCloseCode(code)) {
-      upstream.close();
-      return;
-    }
-    upstream.close(code, reason?.toString());
-  };
-
-  browserSocket.on("message", (data, isBinary) => {
-    if (upstream.readyState === WsWebSocket.OPEN) {
-      upstream.send(data, { binary: isBinary });
-      return;
-    }
-    if (upstream.readyState === WsWebSocket.CONNECTING) {
-      pendingBytes += rawDataByteLength(data);
-      if (pendingBytes > MAX_PENDING_WEBSOCKET_BYTES) {
-        pendingMessages.length = 0;
-        closeBrowser(1009, "dev_browser_websocket_buffer_overflow");
-        closeUpstream();
-        return;
-      }
-      pendingMessages.push({ data, isBinary });
-    }
-  });
-
-  browserSocket.on("close", (code, reason) => {
-    closeUpstream(code, reason);
-  });
-
-  browserSocket.on("error", () => {
-    closeUpstream();
-  });
-
-  if (prepared) {
-    bindPreparedProxyWebSocket(prepared, browserSocket, closeBrowser, () => closeUpstream());
-    return;
-  }
-
-  upstream.on("open", () => {
-    upstreamOpened = true;
-    for (const message of pendingMessages.splice(0)) {
-      upstream.send(message.data, { binary: message.isBinary });
-    }
-    pendingBytes = 0;
-  });
-
-  upstream.on("message", (data, isBinary) => {
-    upstreamReceivedMessage = true;
-    if (browserSocket.readyState === WsWebSocket.OPEN) {
-      browserSocket.send(data, { binary: isBinary });
-    }
-  });
-
-  upstream.on("close", (code, reason) => {
-    upstreamClosed = true;
-    if (!upstreamOpened) {
-      closeBrowser(1014, "dev_browser_target_unavailable");
-      return;
-    }
-    closeBrowserForUpstreamResult(closeBrowser, { code, reason }, upstreamReceivedMessage);
-  });
-
-  upstream.on("error", () => {
-    if (!upstreamOpened) {
-      closeBrowser(1014, "dev_browser_target_unavailable");
-      return;
-    }
-    closeBrowser(1011, "dev_browser_websocket_error");
-  });
-}
-
-export function registerDevBrowserRoutes(
-  app: FastifyInstance,
-  deps: { sessions?: DevBrowserSessionStore } = {}
-): void {
-  const sessions = deps.sessions ?? new DevBrowserSessionStore();
-  const existingHandleProtocols = app.websocketServer.options.handleProtocols;
-  app.websocketServer.options.handleProtocols = (protocols, rawRequest) => {
-    const prepared = preparedProxyWebSockets.get(rawRequest);
-    if (prepared) {
-      return prepared.selectedProtocol;
-    }
-    return existingHandleProtocols
-      ? existingHandleProtocols(protocols, rawRequest)
-      : (protocols.values().next().value ?? false);
-  };
-
-  app.post("/api/dev-proxy/session", async (request, reply) => {
-    const parsed = createSessionSchema.safeParse(request.body);
-    if (!parsed.success) {
-      return reply.status(400).send({ error: "invalid_dev_browser_payload" });
-    }
-
-    try {
-      const session = sessions.create({
-        ...parseDevBrowserTargetUrl(parsed.data.url),
-        ...(parsed.data.userAgent ? { userAgent: parsed.data.userAgent } : {}),
-      });
-      return reply.send(serializeSession(session));
-    } catch (error) {
-      if (error instanceof DevBrowserTargetUrlError) {
-        return reply.status(400).send({ error: "invalid_dev_browser_target" });
-      }
-      throw error;
-    }
-  });
-
-  app.get("/api/dev-proxy/session/:id", async (request, reply) => {
-    const { id } = request.params as { id: string };
-    const session = sessions.get(id);
-    return session
-      ? reply.send(serializeSession(session))
-      : reply.status(404).send({ error: "dev_browser_session_not_found" });
-  });
-
-  app.delete("/api/dev-proxy/session/:id", async (request, reply) => {
-    const { id } = request.params as { id: string };
-    sessions.delete(id);
-    return reply.send({ ok: true });
-  });
-
-  app.get("/dev-browser/session/:id", async (request, reply) => {
-    const { id } = request.params as { id: string };
-    return reply.redirect(`/dev-browser/session/${id}/`);
-  });
-
-  app.get("/dev-browser/session/:id/", async (request, reply) => {
-    const { id } = request.params as { id: string };
-    const session = sessions.get(id);
-    if (!session) {
-      return reply.status(404).send({ error: "dev_browser_session_not_found" });
-    }
-    return reply.type("text/html; charset=utf-8").send(renderDevBrowserShell(session));
-  });
-
-  app.register(async (proxyApp) => {
-    proxyApp.removeAllContentTypeParsers();
-    proxyApp.addContentTypeParser("*", { parseAs: "buffer" }, (_request, body, done) => {
-      done(null, body);
-    });
-
-    proxyApp.route({
-      method: "GET",
-      url: "/dev-browser/session/:id/proxy/*",
-      preHandler: async (request, reply) => {
-        preparedProxyWebSockets.delete(request.raw);
-
-        const session = getSessionFromRequest(sessions, request);
-        if (!session) {
-          return reply.status(404).send({ error: "dev_browser_session_not_found" });
-        }
-
-        if (request.ws) {
-          try {
-            const prepared = await prepareProxyWebSocket(request, session);
-            if (prepared) {
-              preparedProxyWebSockets.set(request.raw, prepared);
-            }
-          } catch {
-            return reply.status(502).send({
-              error: "dev_browser_target_unavailable",
-            });
-          }
-        }
-      },
-      handler: async (request, reply) => {
-        const session = getSessionFromRequest(sessions, request);
-        if (!session) {
-          return reply.status(404).send({ error: "dev_browser_session_not_found" });
-        }
-        return proxyRequest(request, reply, session);
-      },
-      wsHandler: (socket, request) => {
-        const session = getSessionFromRequest(sessions, request);
-        if (!session) {
-          socket.close(1008, "dev_browser_session_not_found");
-          return;
-        }
-        const prepared = preparedProxyWebSockets.get(request.raw) ?? null;
-        preparedProxyWebSockets.delete(request.raw);
-        proxyWebSocket(request, socket, session, prepared);
-      },
-    });
-
-    proxyApp.route({
-      method: ["DELETE", "OPTIONS", "PATCH", "POST", "PUT"],
-      url: "/dev-browser/session/:id/proxy/*",
-      handler: async (request, reply) => {
-        const session = getSessionFromRequest(sessions, request);
-        if (!session) {
-          return reply.status(404).send({ error: "dev_browser_session_not_found" });
-        }
-        return proxyRequest(request, reply, session);
-      },
-    });
-  });
-}
diff --git a/packages/server/src/routes/preview.test.ts b/packages/server/src/routes/preview.test.ts
index b98dc40f5..c14e1256c 100644
--- a/packages/server/src/routes/preview.test.ts
+++ b/packages/server/src/routes/preview.test.ts
@@ -307,6 +307,53 @@ describe("/api/preview/session", () => {
     expect(entryRes.headers["content-security-policy"]).toContain("script-src 'none'");
   });
 
+  it("allows markdown preview scripts only when the document contains mermaid diagrams", async () => {
+    const createRes = await app.inject({
+      method: "POST",
+      url: "/api/preview/session",
+      payload: {
+        workspaceId: "ws-1",
+        entryPath: "README.md",
+        kind: "markdown",
+        content: "```mermaid\ngraph TD\nA[README] --> B[Preview]\n```",
+      },
+    });
+
+    const { id, previewUrl } = createRes.json();
+    const entryRes = await app.inject({
+      method: "GET",
+      url: previewUrl,
+    });
+    const runtimeRes = await app.inject({
+      method: "GET",
+      url: "/api/preview/assets/mermaid.min.js",
+    });
+    const initRes = await app.inject({
+      method: "GET",
+      url: "/api/preview/assets/markdown-mermaid-init.js",
+    });
+
+    expect(entryRes.statusCode).toBe(200);
+    expect(entryRes.headers["x-preview-allow-scripts"]).toBe("true");
+    expect(entryRes.headers["content-security-policy"]).toContain("script-src 'self'");
+    expect(entryRes.headers["content-security-policy"]).not.toContain(
+      "script-src 'self' 'unsafe-inline'"
+    );
+    expect(entryRes.headers["content-security-policy"]).not.toContain("script-src-attr");
+    expect(entryRes.body).toContain('src="/api/preview/assets/mermaid.min.js"');
+    expect(entryRes.body).toContain('src="/api/preview/assets/markdown-mermaid-init.js"');
+    expect(entryRes.body).not.toContain(
+      `/api/preview/session/${id}/api/preview/assets/mermaid.min.js`
+    );
+    expect(entryRes.body).not.toContain(
+      `/api/preview/session/${id}/api/preview/assets/markdown-mermaid-init.js`
+    );
+    expect(runtimeRes.statusCode).toBe(200);
+    expect(runtimeRes.headers["content-type"]).toContain("javascript");
+    expect(initRes.statusCode).toBe(200);
+    expect(initRes.body).toContain("mermaid.initialize");
+  });
+
   it("returns 404 when a relative asset is missing", async () => {
     const createRes = await app.inject({
       method: "POST",
diff --git a/packages/server/src/routes/preview.ts b/packages/server/src/routes/preview.ts
index 65b724538..ae9113f1d 100644
--- a/packages/server/src/routes/preview.ts
+++ b/packages/server/src/routes/preview.ts
@@ -1,4 +1,7 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { posix } from "node:path";
+import { markdownUsesMermaid } from "@coder-studio/utils";
 import type { FastifyInstance } from "fastify";
 import { z } from "zod";
 import {
@@ -11,6 +14,7 @@ import { loadPreviewResource, resolvePreviewResourcePath } from "../preview/reso
 import { PreviewSessionStore } from "../preview/session-store.js";
 
 type PreviewKind = "markdown" | "html";
+type PreviewScriptPolicy = "none" | "self" | "relaxed";
 
 interface PreviewSessionBody {
   workspaceId: string;
@@ -27,19 +31,36 @@ interface PreviewSessionUpdateBody {
 
 type WorkspaceLookup = { path: string } | null | undefined;
 
-function getPreviewContentSecurityPolicy(allowScripts: boolean): string {
-  const scriptPolicy = allowScripts
-    ? "script-src 'self' 'unsafe-inline'; script-src-attr 'unsafe-inline'"
-    : "script-src 'none'";
-
-  return `default-src 'none'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; font-src 'self' data:; ${scriptPolicy}; base-uri 'none'; form-action 'none'`;
+const require = createRequire(import.meta.url);
+const MERMAID_RUNTIME_PATH = require.resolve("mermaid/dist/mermaid.min.js");
+const MARKDOWN_MERMAID_INIT_SCRIPT = [
+  "if (typeof window.mermaid !== 'undefined') {",
+  "  window.mermaid.initialize({ startOnLoad: true, securityLevel: 'strict' });",
+  "}",
+].join("\n");
+let mermaidRuntimePromise: Promise<Buffer> | null = null;
+
+function getPreviewContentSecurityPolicy(scriptPolicy: PreviewScriptPolicy): string {
+  const resolvedScriptPolicy =
+    scriptPolicy === "relaxed"
+      ? "script-src 'self' 'unsafe-inline'; script-src-attr 'unsafe-inline'"
+      : scriptPolicy === "self"
+        ? "script-src 'self'"
+        : "script-src 'none'";
+
+  return `default-src 'none'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; font-src 'self' data:; ${resolvedScriptPolicy}; base-uri 'none'; form-action 'none'`;
 }
 
-function getEffectivePreviewAllowScripts(session: {
+function getSessionPreviewScriptPolicy(session: {
   kind: PreviewKind;
   allowScripts: boolean;
-}): boolean {
-  return session.kind === "html" && session.allowScripts;
+  content: string;
+}): PreviewScriptPolicy {
+  if (session.kind === "html") {
+    return session.allowScripts ? "relaxed" : "none";
+  }
+
+  return markdownUsesMermaid(session.content) ? "self" : "none";
 }
 
 function resolvePreviewAssetWorkspacePath(entryPath: string, rawPath: string): string {
@@ -48,6 +69,11 @@ function resolvePreviewAssetWorkspacePath(entryPath: string, rawPath: string): s
   return resolvePreviewResourcePath(entryPath, relativeAssetPath);
 }
 
+async function loadMermaidRuntime(): Promise<Buffer> {
+  mermaidRuntimePromise ??= readFile(MERMAID_RUNTIME_PATH);
+  return mermaidRuntimePromise;
+}
+
 const previewSessionCreateSchema = z.object({
   workspaceId: z.string().min(1),
   entryPath: z.string().min(1),
@@ -68,6 +94,23 @@ export function registerPreviewRoutes(
     previewSessions: PreviewSessionStore;
   }
 ): void {
+  app.get("/api/preview/assets/mermaid.min.js", async (_request, reply) => {
+    const script = await loadMermaidRuntime();
+    return reply
+      .header("Content-Type", "application/javascript; charset=utf-8")
+      .header("Cache-Control", "no-store")
+      .header("X-Content-Type-Options", "nosniff")
+      .send(script);
+  });
+
+  app.get("/api/preview/assets/markdown-mermaid-init.js", async (_request, reply) => {
+    return reply
+      .header("Content-Type", "application/javascript; charset=utf-8")
+      .header("Cache-Control", "no-store")
+      .header("X-Content-Type-Options", "nosniff")
+      .send(MARKDOWN_MERMAID_INIT_SCRIPT);
+  });
+
   app.post("/api/preview/session", async (request, reply) => {
     const parsed = previewSessionCreateSchema.safeParse(request.body);
     if (!parsed.success) {
@@ -143,9 +186,12 @@ export function registerPreviewRoutes(
         entryPath: session.entryPath,
         sessionId: session.id,
         workspaceRootPath: workspace.path,
+        preserveRootRelativePrefixes:
+          session.kind === "markdown" ? ["/api/preview/assets/"] : undefined,
       });
-      const allowScripts = getEffectivePreviewAllowScripts(session);
-      const contentSecurityPolicy = getPreviewContentSecurityPolicy(allowScripts);
+      const scriptPolicy = getSessionPreviewScriptPolicy(session);
+      const allowScripts = scriptPolicy !== "none";
+      const contentSecurityPolicy = getPreviewContentSecurityPolicy(scriptPolicy);
 
       const response = reply
         .header("Content-Type", "text/html; charset=utf-8")
diff --git a/packages/server/src/routes/skill-file-asset.test.ts b/packages/server/src/routes/skill-file-asset.test.ts
new file mode 100644
index 000000000..7fbb56090
--- /dev/null
+++ b/packages/server/src/routes/skill-file-asset.test.ts
@@ -0,0 +1,132 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Fastify, { type FastifyInstance } from "fastify";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { registerSkillFileAssetRoutes } from "./skill-file-asset.js";
+
+const PNG_BYTES = Buffer.from(
+  "89504E470D0A1A0A0000000D4948445200000001000000010806000000" +
+    "1F15C4890000000A49444154789C63000100000005000157CFC4A30000" +
+    "0000049454E44AE426082",
+  "hex"
+);
+
+async function buildApp(
+  skillPath: string | null,
+  source: "custom" | "installed" = "custom",
+  origin: "filesystem" | "skillhub" = "filesystem"
+) {
+  const app = Fastify({ logger: false });
+  registerSkillFileAssetRoutes(app, {
+    skillLibraryRepo: {
+      get: (slug: string) =>
+        slug === "my-review-skill" && skillPath
+          ? {
+              slug,
+              displayName: "My Review Skill",
+              version: "local",
+              source,
+              origin,
+              libraryPath: skillPath,
+              installState: "installed",
+              installedAt: 1,
+              updatedAt: 1,
+            }
+          : undefined,
+    } as never,
+  });
+  await app.ready();
+  return app;
+}
+
+describe("/api/skill-file", () => {
+  let testDir: string;
+  let app: FastifyInstance;
+
+  beforeEach(async () => {
+    testDir = join(
+      tmpdir(),
+      `skill-file-asset-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+    }
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  it("streams a skill image with the correct mime type and size", async () => {
+    await writeFile(join(testDir, "pixel.png"), PNG_BYTES);
+    app = await buildApp(testDir);
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/api/skill-file?skillSlug=my-review-skill&path=pixel.png",
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.headers["content-type"]).toBe("image/png");
+    expect(res.headers["content-length"]).toBe(String(PNG_BYTES.length));
+    expect(res.headers["cache-control"]).toBe("no-store");
+    expect(res.rawPayload.equals(PNG_BYTES)).toBe(true);
+  });
+
+  it("returns 400 when skillSlug or path is missing", async () => {
+    app = await buildApp(testDir);
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/api/skill-file?skillSlug=my-review-skill",
+    });
+
+    expect(res.statusCode).toBe(400);
+  });
+
+  it("returns 404 for unknown skills or non-image files", async () => {
+    await writeFile(join(testDir, "note.txt"), "secret");
+    app = await buildApp(testDir);
+
+    const unknownRes = await app.inject({
+      method: "GET",
+      url: "/api/skill-file?skillSlug=ghost&path=pixel.png",
+    });
+    const nonImageRes = await app.inject({
+      method: "GET",
+      url: "/api/skill-file?skillSlug=my-review-skill&path=note.txt",
+    });
+
+    expect(unknownRes.statusCode).toBe(404);
+    expect(unknownRes.json()).toMatchObject({ error: "skill_not_found" });
+    expect(nonImageRes.statusCode).toBe(404);
+    expect(nonImageRes.json()).toMatchObject({ error: "not_an_image" });
+  });
+
+  it("rejects path escape attempts", async () => {
+    app = await buildApp(testDir);
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/api/skill-file?skillSlug=my-review-skill&path=../outside.png",
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(res.json()).toMatchObject({ error: "path_escape" });
+  });
+
+  it("returns 404 for non-local skills", async () => {
+    await writeFile(join(testDir, "pixel.png"), PNG_BYTES);
+    app = await buildApp(testDir, "installed", "skillhub");
+
+    const res = await app.inject({
+      method: "GET",
+      url: "/api/skill-file?skillSlug=my-review-skill&path=pixel.png",
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json()).toMatchObject({ error: "skill_not_found" });
+  });
+});
diff --git a/packages/server/src/routes/skill-file-asset.ts b/packages/server/src/routes/skill-file-asset.ts
new file mode 100644
index 000000000..7a0cdf5f8
--- /dev/null
+++ b/packages/server/src/routes/skill-file-asset.ts
@@ -0,0 +1,56 @@
+import { createReadStream } from "node:fs";
+import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
+import { resolveSkillImageAsset } from "../commands/skills/files.js";
+import type { SkillLibraryRepo } from "../storage/repositories/skill-library-repo.js";
+
+interface SkillFileAssetQuery {
+  skillSlug?: string;
+  path?: string;
+}
+
+export function registerSkillFileAssetRoutes(
+  app: FastifyInstance,
+  deps: { skillLibraryRepo: SkillLibraryRepo }
+): void {
+  app.get(
+    "/api/skill-file",
+    async (request: FastifyRequest<{ Querystring: SkillFileAssetQuery }>, reply: FastifyReply) => {
+      const { skillSlug, path } = request.query;
+
+      if (!skillSlug || !path) {
+        return reply.status(400).send({ ok: false, error: "skillSlug and path are required" });
+      }
+
+      const entry = deps.skillLibraryRepo.get(skillSlug);
+      if (!entry || entry.source !== "custom") {
+        return reply.status(404).send({ ok: false, error: "skill_not_found" });
+      }
+
+      try {
+        const asset = await resolveSkillImageAsset(entry.libraryPath, path);
+        reply
+          .header("Content-Type", asset.mime)
+          .header("Content-Length", String(asset.size))
+          .header("Cache-Control", "no-store")
+          .header("X-Content-Type-Options", "nosniff");
+
+        return reply.send(createReadStream(asset.absPath));
+      } catch (error) {
+        const code =
+          typeof error === "object" && error !== null && "code" in error
+            ? (error as { code?: string }).code
+            : undefined;
+
+        if (code === "path_escape") {
+          return reply.status(400).send({ ok: false, error: "path_escape" });
+        }
+
+        if (code === "not_an_image") {
+          return reply.status(404).send({ ok: false, error: "not_an_image" });
+        }
+
+        return reply.status(404).send({ ok: false, error: "not_found" });
+      }
+    }
+  );
+}
diff --git a/packages/server/src/runtime/assembly.ts b/packages/server/src/runtime/assembly.ts
new file mode 100644
index 000000000..23db4ce29
--- /dev/null
+++ b/packages/server/src/runtime/assembly.ts
@@ -0,0 +1,71 @@
+import { ProviderConfigRepo } from "../storage/repositories/provider-config-repo.js";
+import type { RuntimeCommandContext } from "./context.js";
+import type { RuntimeHostBridge } from "./contract.js";
+import { getRuntimeStateFile } from "./runtime-state.js";
+
+export interface RuntimeAssembly {
+  context: RuntimeCommandContext;
+  stop(): Promise<void>;
+}
+
+export async function assembleRuntime(input: {
+  runtimeId: string;
+  stateRoot: string;
+  hostBridge: RuntimeHostBridge;
+  providerRegistry: RuntimeCommandContext["providerRegistry"];
+  workspaceLookup: RuntimeCommandContext["workspaceLookup"];
+  providerRuntimeDeps?: RuntimeCommandContext["providerRuntimeDeps"];
+  contextOverrides?: Partial<RuntimeCommandContext>;
+  providerConfigRepoFactory?:
+    | ((filePath: string) => RuntimeCommandContext["providerConfigRepo"])
+    | undefined;
+}): Promise<RuntimeAssembly> {
+  const providerConfigPath = getRuntimeStateFile(
+    input.stateRoot,
+    input.runtimeId,
+    "provider-configs.json"
+  );
+  const providerConfigRepo = input.providerConfigRepoFactory
+    ? input.providerConfigRepoFactory(providerConfigPath)
+    : new ProviderConfigRepo({
+        filePath: providerConfigPath,
+      });
+
+  const context = {
+    runtimeId: input.runtimeId,
+    workspaceLookup: input.workspaceLookup,
+    hostBridge: input.hostBridge,
+    eventBus: {
+      emit() {},
+      on() {
+        return () => {};
+      },
+    },
+    providerConfigRepo,
+    providerRegistry: input.providerRegistry,
+    sessionMgr: {
+      setProviderRegistry() {},
+      async stopForWorkspace() {},
+      deleteEndedForWorkspace() {},
+    },
+    terminalMgr: {
+      async closeForWorkspace() {},
+    },
+    taskMgr: {
+      clearWorkspace() {},
+    },
+    lspMgr: {
+      async disposeWorkspace() {},
+    },
+    supervisorMgr: {
+      setProviderRegistry() {},
+    },
+    providerRuntimeDeps: input.providerRuntimeDeps,
+    ...input.contextOverrides,
+  } as unknown as RuntimeCommandContext;
+
+  return {
+    context,
+    async stop() {},
+  };
+}
diff --git a/packages/server/src/runtime/command-registry.ts b/packages/server/src/runtime/command-registry.ts
new file mode 100644
index 000000000..43076f7a6
--- /dev/null
+++ b/packages/server/src/runtime/command-registry.ts
@@ -0,0 +1,56 @@
+import { z } from "zod";
+import type { RuntimeCommandContext } from "./context.js";
+import type { RuntimeExecuteMeta, RuntimeRouteTarget } from "./contract.js";
+
+export type RuntimeCommandVisibility = "public" | "internal";
+
+export interface RuntimeCommandDefinition<S extends z.ZodTypeAny = z.ZodTypeAny, R = unknown> {
+  schema: S;
+  visibility: RuntimeCommandVisibility;
+  resolveTarget: (args: z.output<S>) => RuntimeRouteTarget;
+  handler: (args: z.output<S>, ctx: RuntimeCommandContext, meta?: RuntimeExecuteMeta) => Promise<R>;
+}
+
+const runtimeCommands = new Map<string, RuntimeCommandDefinition<any, any>>();
+
+export function registerRuntimeCommand<S extends z.ZodTypeAny, R>(
+  op: string,
+  schema: S,
+  definition: Omit<RuntimeCommandDefinition<S, R>, "schema" | "visibility"> & {
+    visibility?: RuntimeCommandVisibility;
+  }
+): void {
+  runtimeCommands.set(op, {
+    schema,
+    visibility: definition.visibility ?? "public",
+    ...definition,
+  });
+}
+
+export function getRuntimeCommandDefinition(
+  op: string,
+  options?: { includeInternal?: boolean }
+): RuntimeCommandDefinition | undefined {
+  const definition = runtimeCommands.get(op);
+  if (!definition) {
+    return undefined;
+  }
+
+  if (definition.visibility === "internal" && options?.includeInternal === false) {
+    return undefined;
+  }
+
+  return definition;
+}
+
+export function getRegisteredRuntimeCommands(options?: { includeInternal?: boolean }): string[] {
+  const includeInternal = options?.includeInternal ?? false;
+
+  return Array.from(runtimeCommands.entries())
+    .filter(([, definition]) => includeInternal || definition.visibility !== "internal")
+    .map(([op]) => op);
+}
+
+export function clearRuntimeCommandsForTest(): void {
+  runtimeCommands.clear();
+}
diff --git a/packages/server/src/runtime/context.ts b/packages/server/src/runtime/context.ts
new file mode 100644
index 000000000..d0d6977f9
--- /dev/null
+++ b/packages/server/src/runtime/context.ts
@@ -0,0 +1,62 @@
+import type { ProviderDefinition, Workspace } from "@coder-studio/core";
+import type { AgentInstructionsPublisher } from "../agent-instructions/publisher.js";
+import type { EventBus } from "../bus/event-bus.js";
+import type { LspManager } from "../lsp/manager.js";
+import type { LspToolInstallManager } from "../lsp-tools/install-manager.js";
+import type { LspToolManager } from "../lsp-tools/manager.js";
+import type { ProviderInstallManager } from "../provider-runtime/install-manager.js";
+import type { RuntimeStatusDeps } from "../provider-runtime/runtime-status.js";
+import type { SessionManager } from "../session/manager.js";
+import type { SessionAnalysisService } from "../session-analysis/service.js";
+import type { BuiltinSkillSyncManager } from "../skills/builtin/sync-manager.js";
+import type { SkillHealthManager } from "../skills/health-manager.js";
+import type { SkillInstallManager } from "../skills/install-manager.js";
+import type { SkillMountManager } from "../skills/mount-manager.js";
+import type { SkillsHubClient } from "../skills/skills-hub-client.js";
+import type { ProviderConfigRepo } from "../storage/repositories/provider-config-repo.js";
+import type { SessionMetadataRepo } from "../storage/repositories/session-metadata-repo.js";
+import type { SkillLibraryRepo } from "../storage/repositories/skill-library-repo.js";
+import type { SkillMountRepo } from "../storage/repositories/skill-mount-repo.js";
+import type { SkillTargetRepo } from "../storage/repositories/skill-target-repo.js";
+import type { SupervisorManager } from "../supervisor/manager.js";
+import type { SystemDependencyInstallManager } from "../system-deps/install-manager.js";
+import type { TaskManager } from "../tasks/manager.js";
+import type { TerminalManager } from "../terminal/manager.js";
+import type { WorkAnalysisService } from "../work-analysis/service.js";
+import type { RuntimeHostBridge } from "./contract.js";
+
+type RuntimeWorkspaceLookup = Pick<Workspace, "id" | "path" | "targetRuntime">;
+
+export interface RuntimeCommandContext {
+  runtimeId: string;
+  workspaceLookup: {
+    get(workspaceId: string): RuntimeWorkspaceLookup | undefined;
+    list(): RuntimeWorkspaceLookup[];
+  };
+  hostBridge: RuntimeHostBridge;
+  eventBus: EventBus;
+  providerConfigRepo: ProviderConfigRepo;
+  providerRegistry: ProviderDefinition[];
+  sessionMgr: SessionManager;
+  terminalMgr: TerminalManager;
+  taskMgr: TaskManager;
+  lspMgr: LspManager;
+  lspToolMgr?: LspToolManager;
+  lspToolInstallMgr?: LspToolInstallManager;
+  supervisorMgr: SupervisorManager;
+  providerRuntimeDeps?: RuntimeStatusDeps;
+  providerInstallMgr?: ProviderInstallManager;
+  systemDependencyInstallMgr?: SystemDependencyInstallManager;
+  skillsHubClient?: SkillsHubClient;
+  skillInstallMgr?: SkillInstallManager;
+  skillMountMgr?: SkillMountManager;
+  skillHealthMgr?: SkillHealthManager;
+  skillLibraryRepo?: SkillLibraryRepo;
+  skillTargetRepo?: SkillTargetRepo;
+  skillMountRepo?: SkillMountRepo;
+  builtinSkillSyncMgr?: BuiltinSkillSyncManager;
+  sessionMetadataRepo?: SessionMetadataRepo;
+  sessionAnalysisService?: SessionAnalysisService;
+  workAnalysisService?: WorkAnalysisService;
+  agentInstructionPublisher?: AgentInstructionsPublisher;
+}
diff --git a/packages/server/src/runtime/contract.ts b/packages/server/src/runtime/contract.ts
new file mode 100644
index 000000000..25105b628
--- /dev/null
+++ b/packages/server/src/runtime/contract.ts
@@ -0,0 +1,38 @@
+import type { AutomationPermission, DomainEvent, ProviderDefinition } from "@coder-studio/core";
+import type { RequestAuthContext } from "../auth/index.js";
+
+export type RuntimeRouteTarget =
+  | { kind: "workspace"; workspaceId: string }
+  | { kind: "session"; sessionId: string }
+  | { kind: "terminal"; terminalId: string }
+  | { kind: "default" };
+
+export interface RuntimeExecuteMeta {
+  clientId?: string;
+  authContext?: RequestAuthContext;
+}
+
+export interface RuntimeHostBridge {
+  issueSessionToken(input: {
+    sessionId: string;
+    workspaceId: string;
+    providerId: string;
+    permissions: readonly AutomationPermission[];
+  }): { token: string };
+  revokeSessionTokensBySessionId(sessionId: string): void;
+  getHostApiUrl(): string | undefined;
+  emitDomainEvent(event: DomainEvent): void;
+  broadcast(topic: string, payload: unknown): void;
+  recordWorkspaceFetch?(workspaceId: string): void;
+  sendToClient(clientId: string, payload: unknown): boolean;
+  sendBinaryToClient(clientId: string, payload: Buffer): boolean;
+}
+
+export interface RuntimeHandle {
+  id: string;
+  kind: "native" | "wsl";
+  execute(op: string, args: unknown, meta?: RuntimeExecuteMeta): Promise<unknown>;
+  disposeWorkspace(workspaceId: string): Promise<void>;
+  setProviderRegistry?(providers: ProviderDefinition[]): void;
+  health(): Promise<{ ok: true }>;
+}
diff --git a/packages/server/src/runtime/events.ts b/packages/server/src/runtime/events.ts
new file mode 100644
index 000000000..4fe0f8fe8
--- /dev/null
+++ b/packages/server/src/runtime/events.ts
@@ -0,0 +1,14 @@
+import type { DomainEvent } from "@coder-studio/core";
+import type { RuntimeHostBridge } from "./contract.js";
+
+export function emitRuntimeEvent(hostBridge: RuntimeHostBridge, event: DomainEvent): void {
+  hostBridge.emitDomainEvent(event);
+}
+
+export function broadcastRuntimeTopic(
+  hostBridge: RuntimeHostBridge,
+  topic: string,
+  payload: unknown
+): void {
+  hostBridge.broadcast(topic, payload);
+}
diff --git a/packages/server/src/runtime/native-runtime.ts b/packages/server/src/runtime/native-runtime.ts
new file mode 100644
index 000000000..423d88be9
--- /dev/null
+++ b/packages/server/src/runtime/native-runtime.ts
@@ -0,0 +1,53 @@
+import { assembleRuntime } from "./assembly.js";
+import { getRuntimeCommandDefinition } from "./command-registry.js";
+import type { RuntimeCommandContext } from "./context.js";
+import type { RuntimeHandle, RuntimeHostBridge } from "./contract.js";
+
+async function executeRuntimeCommand(
+  op: string,
+  args: unknown,
+  ctx: RuntimeCommandContext,
+  meta?: Parameters<RuntimeHandle["execute"]>[2]
+): Promise<unknown> {
+  const definition = getRuntimeCommandDefinition(op);
+  if (!definition) {
+    throw { code: "unknown_op", message: `Unknown operation: ${op}` };
+  }
+
+  const parsedArgs = definition.schema.parse(args);
+  return definition.handler(parsedArgs, ctx, meta);
+}
+
+export async function createNativeRuntime(input: {
+  runtimeId: string;
+  stateRoot: string;
+  hostBridge: RuntimeHostBridge;
+  providerRegistry: RuntimeCommandContext["providerRegistry"];
+  workspaceLookup: RuntimeCommandContext["workspaceLookup"];
+  providerRuntimeDeps?: RuntimeCommandContext["providerRuntimeDeps"];
+  contextOverrides?: Partial<RuntimeCommandContext>;
+  providerConfigRepoFactory?:
+    | ((filePath: string) => RuntimeCommandContext["providerConfigRepo"])
+    | undefined;
+}): Promise<RuntimeHandle> {
+  const assembly = await assembleRuntime(input);
+
+  return {
+    id: input.runtimeId,
+    kind: "native",
+    execute: (op, args, meta) => executeRuntimeCommand(op, args, assembly.context, meta),
+    disposeWorkspace: async (workspaceId) => {
+      await assembly.context.lspMgr.disposeWorkspace(workspaceId);
+      await assembly.context.sessionMgr.stopForWorkspace(workspaceId);
+      assembly.context.sessionMgr.deleteEndedForWorkspace(workspaceId);
+      assembly.context.taskMgr.clearWorkspace(workspaceId);
+      await assembly.context.terminalMgr.closeForWorkspace(workspaceId);
+    },
+    setProviderRegistry: (providers) => {
+      assembly.context.providerRegistry = providers;
+      assembly.context.sessionMgr.setProviderRegistry(providers);
+      assembly.context.supervisorMgr.setProviderRegistry(providers);
+    },
+    health: async () => ({ ok: true }),
+  };
+}
diff --git a/packages/server/src/runtime/runtime-state.ts b/packages/server/src/runtime/runtime-state.ts
new file mode 100644
index 000000000..1d1f80d74
--- /dev/null
+++ b/packages/server/src/runtime/runtime-state.ts
@@ -0,0 +1,13 @@
+import { join } from "node:path";
+
+export function getRuntimeStateRoot(stateRoot: string, runtimeId: string): string {
+  return join(stateRoot, "state", "runtimes", runtimeId);
+}
+
+export function getRuntimeStateFile(
+  stateRoot: string,
+  runtimeId: string,
+  ...parts: string[]
+): string {
+  return join(getRuntimeStateRoot(stateRoot, runtimeId), ...parts);
+}
diff --git a/packages/server/src/server.ts b/packages/server/src/server.ts
index 9c8cd861e..2d6b2fdf3 100644
--- a/packages/server/src/server.ts
+++ b/packages/server/src/server.ts
@@ -6,7 +6,7 @@
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { DomainEvent } from "@coder-studio/core";
+import type { AutomationPermission, DomainEvent } from "@coder-studio/core";
 import {
   deleteRuntimeConfig,
   getRuntimePath,
@@ -19,8 +19,11 @@ import { isDirectExecution } from "@coder-studio/utils";
 import type { FastifyInstance } from "fastify";
 import { AgentInstructionsPublisher } from "./agent-instructions/publisher.js";
 import { buildFastifyApp } from "./app.js";
+import { SessionTokenRepo } from "./auth/session-token-repo.js";
 import { AutomationAuditLog } from "./automation/audit-log.js";
 import { EventBus } from "./bus/event-bus.js";
+import { CanvasService } from "./canvas/service.js";
+import { registerAllCommands } from "./commands/index.js";
 import {
   ensureStateDir,
   parseServerConfig,
@@ -28,6 +31,10 @@ import {
   type ServerConfigInput,
 } from "./config.js";
 import { AutoFetchScheduler } from "./git/auto-fetch.js";
+import type { HostCommandContext } from "./host/context.js";
+import { RuntimeRegistry } from "./host/runtime-registry.js";
+import { RuntimeRouter } from "./host/runtime-router.js";
+import { WorkspaceRuntimeBindingStore } from "./host/workspace-runtime-binding.js";
 import { LspManager } from "./lsp/manager.js";
 import { LspToolInstallManager } from "./lsp-tools/install-manager.js";
 import { LspToolManager } from "./lsp-tools/manager.js";
@@ -45,6 +52,8 @@ import {
   buildProviderRuntimeStatus,
   type RuntimeStatusDeps,
 } from "./provider-runtime/runtime-status.js";
+import type { RuntimeHandle } from "./runtime/contract.js";
+import { createNativeRuntime } from "./runtime/native-runtime.js";
 import { SessionManager } from "./session/manager.js";
 import { SessionAnalysisRunner } from "./session-analysis/runner.js";
 import { SessionAnalysisService } from "./session-analysis/service.js";
@@ -57,6 +66,7 @@ import { SkillsHubClient } from "./skills/skills-hub-client.js";
 import { AppearanceAssetRepo } from "./storage/repositories/appearance-asset-repo.js";
 import { AuthLoginBlockRepo } from "./storage/repositories/auth-login-block-repo.js";
 import { AuthSessionRepo } from "./storage/repositories/auth-session-repo.js";
+import { CanvasRepo } from "./storage/repositories/canvas-repo.js";
 import { CustomProviderRepo } from "./storage/repositories/custom-provider-repo.js";
 import { MemoryRepo } from "./storage/repositories/memory-repo.js";
 import { ProviderConfigRepo } from "./storage/repositories/provider-config-repo.js";
@@ -96,14 +106,29 @@ import { dispatch } from "./ws/dispatch.js";
 import { FencingManager } from "./ws/fencing.js";
 import { WsHub } from "./ws/hub.js";
 
-import "./commands/index.js";
-
 const WS_KEEPALIVE_INTERVAL_MS = 15_000;
 
+function logStartupPhase(app: FastifyInstance | null, label: string, startedAt: number): void {
+  const elapsedMs = Date.now() - startedAt;
+  const message = `[startup] ${label}=${elapsedMs}ms`;
+  if (app) {
+    app.log.info(message);
+    return;
+  }
+
+  console.log(message);
+}
+
 export interface Server {
   app: FastifyInstance;
   stop: () => Promise<void>;
-  __test__?: { sessionMgr: SessionManager; commandContext: CommandContext };
+  __test__?: {
+    sessionMgr: SessionManager;
+    commandContext: CommandContext;
+    hostContext: HostCommandContext;
+    nativeRuntime: RuntimeHandle;
+    sessionTokenRepo: SessionTokenRepo;
+  };
 }
 
 export interface ServerRuntimeOptions {
@@ -113,6 +138,7 @@ export interface ServerRuntimeOptions {
 export async function createServer(
   configOverrides?: ServerConfigInput & ServerRuntimeOptions
 ): Promise<Server> {
+  const startupAt = Date.now();
   const config = parseServerConfig(configOverrides);
   const configuredStateDir = resolveConfiguredStateDir(config);
   const shouldCleanupStateRoot = configuredStateDir === IN_MEMORY_STATE_DIR;
@@ -126,8 +152,16 @@ export async function createServer(
   const activationMgr = new ActivationManager();
   const fencingMgr = new FencingManager();
   const wsHub = new WsHub({ eventBus, commandContext: null, config, fencingMgr });
+  const runtimeBindings = new WorkspaceRuntimeBindingStore();
+  const runtimeRegistry = new RuntimeRegistry();
+  const runtimeRouter = new RuntimeRouter({
+    runtimeRegistry,
+    bindings: runtimeBindings,
+    defaultRuntimeId: "native-default",
+  });
   let workspaceMgr: WorkspaceManager;
   let commandContext: CommandContext;
+  let hostContext: HostCommandContext;
   let agentInstructionPublisher: AgentInstructionsPublisher | undefined;
   let lspMgr: LspManager | null = null;
   const managedProcessRegistry = new ManagedProcessRegistry({
@@ -140,6 +174,7 @@ export async function createServer(
   const sessionRepo = new SessionRepo({
     filePath: join(stateRoot, "state", "sessions.json"),
   });
+  const sessionTokenRepo = new SessionTokenRepo();
 
   const terminalMgr = new TerminalManager({
     ptyHost: createPtyHost(),
@@ -210,7 +245,10 @@ export async function createServer(
     : {};
   const skillLibraryRepo = new SkillLibraryRepo({
     filePath: join(stateRoot, "state", "skills", "library-index.json"),
-    localSkillRoots: resolveDefaultLocalSkillRoots(),
+    builtinRoot: join(stateRoot, "state", "skills", "builtin"),
+    managedLibraryRoot: join(stateRoot, "state", "skills", "library"),
+    customSkillRoot: join(stateRoot, "state", "skills", "custom"),
+    externalSkillRoots: resolveDefaultLocalSkillRoots(),
   });
   const skillTargetRepo = new SkillTargetRepo({
     filePath: join(stateRoot, "state", "skills", "targets.json"),
@@ -248,7 +286,10 @@ export async function createServer(
     filePath: join(stateRoot, "state", "workspaces.json"),
   });
   const sessionMetadataRepo = new SessionMetadataRepo({
-    workspaceRepo,
+    workspaceLookup: {
+      list: () => workspaceMgr.list(),
+      get: (workspaceId) => workspaceMgr.get(workspaceId),
+    },
   });
   const sessionAnalysisRepo = new SessionAnalysisRepo({
     filePath: join(stateRoot, "state", "session-analysis.json"),
@@ -263,6 +304,13 @@ export async function createServer(
   const memoryRepo = new MemoryRepo({
     rootDir: join(stateRoot, "state", "memory", "workspaces"),
   });
+  const canvasRepo = new CanvasRepo({
+    rootDir: join(stateRoot, "state", "canvases", "workspaces"),
+  });
+  const canvasService = new CanvasService({
+    canvasRepo,
+    now: () => Date.now(),
+  });
   const builtinSkillSyncMgr = new BuiltinSkillSyncManager({
     builtinRoot: join(stateRoot, "state", "skills", "builtin"),
     getProviderRegistry: () => activeProviderRegistry,
@@ -272,6 +320,36 @@ export async function createServer(
     settingsRepo,
   });
   await builtinSkillSyncMgr.sync();
+  logStartupPhase(null, "builtinSkillSync", startupAt);
+
+  const hostBridge = {
+    issueSessionToken: (input: {
+      sessionId: string;
+      workspaceId: string;
+      providerId: string;
+      permissions: readonly AutomationPermission[];
+    }) => sessionTokenRepo.issue(input),
+    revokeSessionTokensBySessionId: (sessionId: string) => {
+      sessionTokenRepo.revokeBySessionId(sessionId);
+    },
+    getHostApiUrl: () =>
+      `http://${config.host === "0.0.0.0" ? "127.0.0.1" : config.host}:${config.port}`,
+    emitDomainEvent: (event: DomainEvent) => {
+      eventBus.emit(event);
+    },
+    broadcast: (topic: string, payload: unknown) => {
+      wsHub.broadcast(topic, payload);
+    },
+    recordWorkspaceFetch: (workspaceId: string) => {
+      workspaceMgr.recordFetch(workspaceId);
+    },
+    sendToClient: (clientId: string, payload: unknown) => {
+      return wsHub.sendToClient(clientId as never, payload as never);
+    },
+    sendBinaryToClient: (clientId: string, payload: Buffer) => {
+      return wsHub.sendBinaryToClient(clientId as never, payload);
+    },
+  };
 
   const sessionMgr = new SessionManager({
     terminalMgr,
@@ -280,9 +358,7 @@ export async function createServer(
     broadcaster: wsHub,
     providerRegistry: activeProviderRegistry,
     providerConfigRepo,
-    runtimeContext: {
-      apiUrl: `http://${config.host === "0.0.0.0" ? "127.0.0.1" : config.host}:${config.port}`,
-    },
+    hostBridge,
   });
 
   let supervisorMgr: SupervisorManager | undefined;
@@ -341,6 +417,7 @@ export async function createServer(
       await terminalMgr.closeForWorkspace(workspaceId);
       sessionMgr.deleteEndedForWorkspace(workspaceId);
       memoryRepo.removeWorkspace(workspaceId);
+      canvasRepo.removeWorkspace(workspaceId);
 
       for (const session of persistedSessions) {
         sessionRepo.delete(session.id);
@@ -370,11 +447,14 @@ export async function createServer(
   const app = await buildFastifyApp({
     wsHub,
     workspaceMgr,
+    skillLibraryRepo,
     webRoot: config.webRoot,
     config,
     authSessionRepo,
     authLoginBlockRepo,
+    sessionTokenRepo,
     appearanceAssetRepo,
+    canvasService,
     logger: {
       level: "info",
       transport: {
@@ -386,6 +466,7 @@ export async function createServer(
       },
     },
   });
+  logStartupPhase(app, "buildFastifyApp", startupAt);
 
   wsHub.setLogger(app.log);
   workspaceMgr.setLogger(app.log);
@@ -401,9 +482,6 @@ export async function createServer(
     }
     agentInstructionPublisher?.scheduleWorkspaceSync(workspaceId);
   });
-  workspaceMgr.hydrateWatchers();
-  await agentInstructionPublisher.syncAllOpenWorkspaces();
-
   const lspManifestStore = new FileManifestStore(resolveLspToolRoot(stateRoot));
   const lspToolMgr = new LspToolManager({
     manifestStore: lspManifestStore,
@@ -450,8 +528,63 @@ export async function createServer(
     logger: app.log,
   });
   await sessionMgr.hydrate();
+  logStartupPhase(app, "sessionHydrate", startupAt);
   supervisorMgr.start();
 
+  for (const workspace of workspaceMgr.list()) {
+    runtimeBindings.bindWorkspace(workspace.id, "native-default");
+  }
+  for (const session of sessionMgr.getAll()) {
+    runtimeBindings.bindSession(session);
+  }
+  for (const terminal of terminalMgr.getAll()) {
+    runtimeBindings.bindTerminal(terminal.toDTO());
+  }
+
+  eventBus.on<Extract<DomainEvent, { type: "workspace.meta.changed" }>>(
+    "workspace.meta.changed",
+    (event) => {
+      const workspace = workspaceMgr.get(event.workspaceId);
+      if (!workspace) {
+        runtimeBindings.unbindWorkspace(event.workspaceId);
+        return;
+      }
+
+      const runtimeId = workspace.targetRuntime === "native" ? "native-default" : "native-default";
+      runtimeBindings.bindWorkspace(workspace.id, runtimeId);
+    }
+  );
+  eventBus.on<Extract<DomainEvent, { type: "session.state.changed" }>>(
+    "session.state.changed",
+    (event) => {
+      if (event.session) {
+        runtimeBindings.bindSession(event.session);
+      }
+    }
+  );
+  eventBus.on<Extract<DomainEvent, { type: "session.lifecycle" }>>("session.lifecycle", (event) => {
+    if (event.event === "removed") {
+      runtimeBindings.removeSession(event.sessionId);
+    }
+  });
+  eventBus.on<Extract<DomainEvent, { type: "terminal.created" }>>("terminal.created", (event) => {
+    runtimeBindings.bindTerminal({
+      id: event.terminalId,
+      workspaceId: event.workspaceId,
+      kind: event.kind,
+      title: event.title,
+      cwd: event.cwd,
+      argv: [],
+      cols: 120,
+      rows: 30,
+      alive: true,
+      createdAt: Date.now(),
+    });
+  });
+  eventBus.on<Extract<DomainEvent, { type: "terminal.exited" }>>("terminal.exited", (event) => {
+    runtimeBindings.removeTerminal(event.terminalId);
+  });
+
   const providerInstallMgr = new ProviderInstallManager(activeProviderRegistry, {
     ...providerRuntimeDeps,
     runCommand: providerMockOverrides?.runCommand ?? runCommandAsString,
@@ -460,7 +593,7 @@ export async function createServer(
     ...providerRuntimeDeps,
     runCommand: providerMockOverrides?.runCommand ?? runCommandAsString,
     ptyHost: createPtyHost(),
-    broadcaster: wsHub,
+    hostBridge,
   });
 
   updateService = new UpdateService({
@@ -479,8 +612,6 @@ export async function createServer(
         .filter((session) => session.state === "starting" || session.state === "running").length,
     countActiveSupervisors: () => supervisorMgr?.countActive() ?? 0,
   });
-  updateService.start();
-
   monitoringService = new MonitoringService({
     broadcaster: wsHub,
     settingsRepo,
@@ -492,6 +623,75 @@ export async function createServer(
     processCollector: createProcessTableCollector(),
   });
 
+  hostContext = {
+    workspaceMgr,
+    sessionMgr,
+    terminalMgr,
+    settingsRepo,
+    memoryRepo,
+    activationMgr,
+    automationAuditLog,
+    broadcaster: wsHub,
+    autoFetch,
+    runtimeRouter,
+    runtimeBindings,
+    fencingMgr,
+    config,
+    updateService,
+    monitoringService,
+    customProviderRepo,
+    providerRegistry: activeProviderRegistry,
+    setProviderRegistry: (providers) => {
+      activeProviderRegistry = providers;
+      hostContext.providerRegistry = providers;
+      commandContext.providerRegistry = providers;
+      runtimeRegistry.setProviderRegistry(providers);
+      providerInstallMgr.setProviders(providers);
+    },
+  };
+
+  await registerAllCommands();
+
+  const nativeRuntime = await createNativeRuntime({
+    runtimeId: "native-default",
+    stateRoot,
+    hostBridge,
+    providerRegistry: activeProviderRegistry,
+    workspaceLookup: {
+      get: (workspaceId) => workspaceMgr.get(workspaceId),
+      list: () => workspaceMgr.list(),
+    },
+    providerRuntimeDeps,
+    contextOverrides: {
+      eventBus,
+      providerConfigRepo,
+      providerRegistry: activeProviderRegistry,
+      sessionMgr,
+      terminalMgr,
+      taskMgr,
+      lspMgr,
+      lspToolMgr,
+      lspToolInstallMgr,
+      supervisorMgr,
+      providerRuntimeDeps,
+      providerInstallMgr,
+      systemDependencyInstallMgr,
+      skillsHubClient,
+      skillInstallMgr,
+      skillMountMgr,
+      skillHealthMgr,
+      skillLibraryRepo,
+      skillTargetRepo,
+      skillMountRepo,
+      builtinSkillSyncMgr,
+      sessionMetadataRepo,
+      sessionAnalysisService,
+      workAnalysisService,
+      agentInstructionPublisher,
+    },
+  });
+  runtimeRegistry.register(nativeRuntime);
+
   commandContext = {
     workspaceMgr,
     sessionMgr,
@@ -505,10 +705,13 @@ export async function createServer(
     fencingMgr,
     supervisorMgr,
     autoFetch,
+    runtimeRouter,
+    runtimeBindings,
     providerRuntimeDeps,
     providerInstallMgr,
     systemDependencyInstallMgr,
     activationMgr,
+    canvasService,
     config,
     lspMgr,
     lspToolMgr,
@@ -520,7 +723,9 @@ export async function createServer(
     workAnalysisService,
     setProviderRegistry: (providers) => {
       activeProviderRegistry = providers;
+      hostContext.providerRegistry = providers;
       commandContext.providerRegistry = providers;
+      runtimeRegistry.setProviderRegistry(providers);
       providerInstallMgr.setProviders(providers);
       sessionMgr.setProviderRegistry(providers);
       supervisorMgr?.setProviderRegistry(providers);
@@ -541,7 +746,6 @@ export async function createServer(
   };
 
   wsHub.setCommandContext(commandContext);
-  monitoringService.start();
 
   eventBus.on(
     "session.state.changed",
@@ -566,6 +770,7 @@ export async function createServer(
     host: config.host,
     port: config.port,
   });
+  logStartupPhase(app, "listen", startupAt);
 
   if (configOverrides?.writeRuntimeConfig ?? process.env.NODE_ENV === "production") {
     const runtime: RuntimeConfig = {
@@ -579,6 +784,20 @@ export async function createServer(
     process.env.CODER_STUDIO_RUNTIME_JSON_PATH = getRuntimePath();
     writeRuntimeConfig(runtime);
   }
+  logStartupPhase(app, "runtimeConfigWritten", startupAt);
+
+  const runPostListenWarmup = async (): Promise<void> => {
+    workAnalysisService.startAutoScan();
+    workspaceMgr.hydrateWatchers();
+    await agentInstructionPublisher.syncAllOpenWorkspaces();
+    updateService.start();
+    monitoringService.start();
+  };
+
+  void runPostListenWarmup().catch((error) => {
+    app.log.warn({ err: error }, "post-listen warmup failed");
+  });
+  logStartupPhase(app, "postListenWarmupScheduled", startupAt);
 
   const gcTimer = setTimeout(() => {
     runStartupGc(config.uploadsDir, app.log).catch((err) =>
@@ -622,7 +841,13 @@ export async function createServer(
   return {
     app,
     stop: stopServer,
-    __test__: { sessionMgr, commandContext },
+    __test__: {
+      sessionMgr,
+      commandContext,
+      hostContext,
+      nativeRuntime,
+      sessionTokenRepo,
+    },
   };
 }
 
diff --git a/packages/server/src/session/automation-entry-path.ts b/packages/server/src/session/automation-entry-path.ts
new file mode 100644
index 000000000..4faeaef7b
--- /dev/null
+++ b/packages/server/src/session/automation-entry-path.ts
@@ -0,0 +1,28 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function isPackagedDistRuntime(modulePath: string): boolean {
+  return modulePath.includes(`${sep}dist${sep}esm${sep}`);
+}
+
+export function resolveAutomationEntryPath(runtimeModuleUrl: string = import.meta.url): string {
+  const modulePath = fileURLToPath(runtimeModuleUrl);
+  const moduleDir = dirname(modulePath);
+  const sourceEntryPath = resolve(moduleDir, "../../../cli/src/automation-entry.ts");
+  const repoDistEntryPath = resolve(moduleDir, "../../../cli/dist/esm/automation-entry.mjs");
+  const packagedDistEntryPath = resolve(moduleDir, "automation-entry.mjs");
+  const candidates = isPackagedDistRuntime(modulePath)
+    ? [packagedDistEntryPath, sourceEntryPath, repoDistEntryPath]
+    : [sourceEntryPath, repoDistEntryPath, packagedDistEntryPath];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    `Unable to resolve Coder Studio automation entry. Tried ${candidates.join(", ")}.`
+  );
+}
diff --git a/packages/server/src/session/manager.ts b/packages/server/src/session/manager.ts
index a326fb852..b624a4249 100644
--- a/packages/server/src/session/manager.ts
+++ b/packages/server/src/session/manager.ts
@@ -6,21 +6,30 @@
  */
 
 import type {
+  AutomationPermission,
   DomainEvent,
   ProviderDefinition,
   Session,
   SessionState,
   TerminalInputActivity,
 } from "@coder-studio/core";
-import { deriveSessionTitle, normalizeSessionTitleInput } from "@coder-studio/core";
+import {
+  AUTOMATION_PERMISSIONS_ENV,
+  deriveSessionTitle,
+  normalizeSessionTitleInput,
+  SCOPED_SESSION_AUTOMATION_PERMISSIONS,
+} from "@coder-studio/core";
+import { SessionTokenRepo } from "../auth/session-token-repo.js";
 import type { EventBus, Unsubscribe } from "../bus/event-bus.js";
 import { mergeProviderLaunchConfig } from "../provider-config.js";
+import type { RuntimeHostBridge } from "../runtime/contract.js";
 import type { ProviderConfigRepo } from "../storage/repositories/provider-config-repo.js";
 import { type SessionRow, sessionToRow } from "../storage/repositories/session-repo.js";
 import type { TerminalManager } from "../terminal/manager.js";
 import type { RenderOptions } from "../terminal/snapshot-render.js";
 import type { TerminalSpec } from "../terminal/types.js";
 import type { Broadcaster } from "../ws/hub.js";
+import { resolveAutomationEntryPath as defaultResolveAutomationEntryPath } from "./automation-entry-path.js";
 import { PtyStateDetector } from "./pty-state-detector.js";
 import { createShadowComparator, type ShadowComparator } from "./state-shadow-comparator.js";
 import type { SessionDatabase } from "./types.js";
@@ -54,7 +63,10 @@ export interface SessionManagerDeps {
   broadcaster: Broadcaster;
   providerRegistry: ProviderDefinition[];
   providerConfigRepo: ProviderConfigRepo;
+  hostBridge?: RuntimeHostBridge;
+  sessionTokenRepo?: SessionTokenRepo;
   runtimeContext?: SessionRuntimeContext;
+  resolveAutomationEntryPath?: () => string;
   logger?: SessionLogger;
 }
 
@@ -261,9 +273,19 @@ export class SessionManager {
   private comparators = new Map<string, ShadowComparator>();
   private detectorUnsubscribes = new Map<string, Unsubscribe>();
   private readonly logger: SessionLogger;
+  private readonly hostBridge: RuntimeHostBridge;
+  private readonly automationEntryPathResolver: () => string;
 
   constructor(private readonly deps: SessionManagerDeps) {
     this.logger = deps.logger ?? NOOP_SESSION_LOGGER;
+    this.hostBridge =
+      deps.hostBridge ??
+      createCompatHostBridge({
+        sessionTokenRepo: deps.sessionTokenRepo ?? new SessionTokenRepo(),
+        apiUrl: deps.runtimeContext?.apiUrl,
+      });
+    this.automationEntryPathResolver =
+      deps.resolveAutomationEntryPath ?? defaultResolveAutomationEntryPath;
 
     this.deps.eventBus.on("terminal.exited", (event: TerminalExitedEvent) => {
       this.onTerminalExit(event.terminalId, event.exitCode);
@@ -280,62 +302,80 @@ export class SessionManager {
   async create(req: CreateSessionRequest): Promise<Session> {
     const sessionId = generateSessionId();
     const launchConfig = this.getLaunchConfig(req.providerId, req.provider);
-
-    // Build command from provider (pass config and context)
-    const cmd = req.provider.buildCommand(launchConfig, {
-      workspacePath: req.workspacePath,
+    const permissions = [
+      ...SCOPED_SESSION_AUTOMATION_PERMISSIONS,
+    ] as readonly AutomationPermission[];
+    const tokenRecord = this.hostBridge.issueSessionToken({
       sessionId,
+      workspaceId: req.workspaceId,
+      providerId: req.providerId,
+      permissions,
     });
+    try {
+      const automationEntryPath = this.automationEntryPathResolver();
 
-    // Create terminal spec
-    const terminalSpec: TerminalSpec = {
-      workspaceId: req.workspaceId,
-      kind: "agent",
-      argv: cmd.argv,
-      cwd: cmd.cwd,
-      env: {
-        ...cmd.env,
-        CODER_STUDIO: "1",
-        CODER_STUDIO_WORKSPACE_ID: req.workspaceId,
-        CODER_STUDIO_SESSION_ID: sessionId,
-        CODER_STUDIO_PROVIDER_ID: req.providerId,
-        ...(this.deps.runtimeContext?.apiUrl
-          ? { CODER_STUDIO_API_URL: this.deps.runtimeContext.apiUrl }
-          : {}),
-      },
-      title: req.provider.displayName,
-      themeBackground: req.themeBackground,
-    };
+      // Build command from provider (pass config and context)
+      const cmd = req.provider.buildCommand(launchConfig, {
+        workspacePath: req.workspacePath,
+        sessionId,
+      });
 
-    // Create terminal (delegates to TerminalManager)
-    const terminal = this.deps.terminalMgr.create(terminalSpec);
+      // Create terminal spec
+      const terminalSpec: TerminalSpec = {
+        workspaceId: req.workspaceId,
+        kind: "agent",
+        argv: cmd.argv,
+        cwd: cmd.cwd,
+        env: {
+          ...cmd.env,
+          CODER_STUDIO: "1",
+          CODER_STUDIO_WORKSPACE_ID: req.workspaceId,
+          CODER_STUDIO_SESSION_ID: sessionId,
+          CODER_STUDIO_PROVIDER_ID: req.providerId,
+          CODER_STUDIO_SESSION_TOKEN: tokenRecord.token,
+          CODER_STUDIO_AUTOMATION_ENTRY: automationEntryPath,
+          [AUTOMATION_PERMISSIONS_ENV]: permissions.join(","),
+          ...(this.hostBridge.getHostApiUrl()
+            ? { CODER_STUDIO_API_URL: this.hostBridge.getHostApiUrl() }
+            : {}),
+        },
+        title: req.provider.displayName,
+        themeBackground: req.themeBackground,
+      };
 
-    // Register session only after terminal creation succeeds so failed creates
-    // do not leak half-created sessions into memory or hydration state.
-    const active = new ActiveSession({
-      id: sessionId,
-      workspaceId: req.workspaceId,
-      providerId: req.providerId,
-      terminalId: terminal.id,
-      capability: req.provider.capability,
-      state: "starting",
-      draft: req.draft,
-    });
+      // Create terminal (delegates to TerminalManager)
+      const terminal = this.deps.terminalMgr.create(terminalSpec);
+
+      // Register session only after terminal creation succeeds so failed creates
+      // do not leak half-created sessions into memory or hydration state.
+      const active = new ActiveSession({
+        id: sessionId,
+        workspaceId: req.workspaceId,
+        providerId: req.providerId,
+        terminalId: terminal.id,
+        capability: req.provider.capability,
+        state: "starting",
+        draft: req.draft,
+      });
 
-    this.sessions.set(sessionId, active);
-    this.terminalToSession.set(terminal.id, sessionId);
-    this.attachShadowDetector(active, req.provider);
+      this.sessions.set(sessionId, active);
+      this.terminalToSession.set(terminal.id, sessionId);
+      this.attachShadowDetector(active, req.provider);
 
-    // Persist initial (`starting`) row so subsequent update() calls have a
-    // target to UPDATE and so a crash between here and the optimistic idle
-    // promotion below still leaves a sane DB state.
-    this.deps.db.insert(active.toRow());
+      // Persist initial (`starting`) row so subsequent update() calls have a
+      // target to UPDATE and so a crash between here and the optimistic idle
+      // promotion below still leaves a sane DB state.
+      this.deps.db.insert(active.toRow());
 
-    // Emit the initial `starting` snapshot so clients can latch session
-    // creation before any optimistic transition fires.
-    this.emitStateChanged(active, null, "starting");
+      // Emit the initial `starting` snapshot so clients can latch session
+      // creation before any optimistic transition fires.
+      this.emitStateChanged(active, null, "starting");
 
-    return active.toDTO();
+      return active.toDTO();
+    } catch (error) {
+      this.hostBridge.revokeSessionTokensBySessionId(sessionId);
+      throw error;
+    }
   }
 
   /**
@@ -467,6 +507,7 @@ export class SessionManager {
       this.sessions.delete(session.id);
       this.terminalToSession.delete(session.terminalId);
       this.cleanupDetector(session.id);
+      this.hostBridge.revokeSessionTokensBySessionId(session.id);
     }
   }
 
@@ -731,6 +772,7 @@ export class SessionManager {
     this.sessions.delete(sessionId);
     this.terminalToSession.delete(session.terminalId);
     this.cleanupDetector(sessionId);
+    this.hostBridge.revokeSessionTokensBySessionId(sessionId);
 
     // Delete from database
     this.deps.db.delete(sessionId);
@@ -1210,6 +1252,7 @@ export class SessionManager {
     session.exitCode = exitCode;
     this.terminalToSession.delete(session.terminalId);
     this.cleanupDetector(session.id);
+    this.hostBridge.revokeSessionTokensBySessionId(session.id);
 
     this.deps.db.update(session.id, {
       state: "ended",
@@ -1302,3 +1345,29 @@ class ActiveSession {
     });
   }
 }
+
+function createCompatHostBridge(input: {
+  sessionTokenRepo: SessionTokenRepo;
+  apiUrl?: string;
+}): RuntimeHostBridge {
+  return {
+    issueSessionToken(args) {
+      const record = input.sessionTokenRepo.issue(args);
+      return { token: record.token };
+    },
+    revokeSessionTokensBySessionId(sessionId) {
+      input.sessionTokenRepo.revokeBySessionId(sessionId);
+    },
+    getHostApiUrl() {
+      return input.apiUrl;
+    },
+    emitDomainEvent() {},
+    broadcast() {},
+    sendToClient() {
+      return false;
+    },
+    sendBinaryToClient() {
+      return false;
+    },
+  };
+}
diff --git a/packages/server/src/skills/builtin/automation-bridge.ts b/packages/server/src/skills/builtin/automation-bridge.ts
new file mode 100644
index 000000000..86b2d0648
--- /dev/null
+++ b/packages/server/src/skills/builtin/automation-bridge.ts
@@ -0,0 +1,77 @@
+import { join } from "node:path";
+
+export const AUTOMATION_CMD_FILE_NAME = "cmd.mjs";
+export const AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN = "<absolute-mounted-skill-path>/cmd.mjs";
+
+export function renderMountedAutomationCommand(targetPath: string): string {
+  return `node "${join(targetPath, AUTOMATION_CMD_FILE_NAME)}"`;
+}
+
+export function renderMountedSkillContent(content: string, targetPath: string): string {
+  return content.replaceAll(
+    AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN,
+    join(targetPath, AUTOMATION_CMD_FILE_NAME)
+  );
+}
+
+export const BUILTIN_AUTOMATION_BRIDGE_SOURCE = `
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+const requiredEnv = [
+  "CODER_STUDIO_API_URL",
+  "CODER_STUDIO_WORKSPACE_ID",
+  "CODER_STUDIO_SESSION_TOKEN",
+  "CODER_STUDIO_AUTOMATION_ENTRY",
+];
+
+for (const key of requiredEnv) {
+  if (!process.env[key] || process.env[key].trim().length === 0) {
+    console.error(\`Coder Studio automation is not available in this session. Missing \${key}.\`);
+    process.exit(1);
+  }
+}
+
+function resolveChildArgv() {
+  const entryPath = process.env.CODER_STUDIO_AUTOMATION_ENTRY;
+  if (!entryPath) {
+    throw new Error("Missing CODER_STUDIO_AUTOMATION_ENTRY.");
+  }
+
+  if (!entryPath.endsWith(".ts")) {
+    return [entryPath, ...process.argv.slice(2)];
+  }
+
+  const requireFromEntry = createRequire(pathToFileURL(entryPath));
+  const tsxLoaderPath = requireFromEntry.resolve("tsx");
+  return ["--import", tsxLoaderPath, entryPath, ...process.argv.slice(2)];
+}
+
+let childArgv;
+try {
+  childArgv = resolveChildArgv();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+const child = spawn(process.execPath, childArgv, {
+  stdio: "inherit",
+  env: process.env,
+});
+
+child.on("error", (error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code ?? 1);
+});
+`.trim();
diff --git a/packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts b/packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts
new file mode 100644
index 000000000..de645fbc5
--- /dev/null
+++ b/packages/server/src/skills/builtin/definitions/coder-studio-canvas.ts
@@ -0,0 +1,191 @@
+import {
+  AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN,
+  AUTOMATION_CMD_FILE_NAME,
+  BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+} from "../automation-bridge.js";
+import type { BuiltinSkillDefinition } from "./types.js";
+
+const DESCRIPTION =
+  "Create visual architecture diagrams and structured report canvases inside Coder Studio when the user asks for a diagram, architecture overview, or when a visual would better explain a concept.";
+
+const CONTENT = [
+  "---",
+  "name: coder-studio-canvas",
+  `description: ${DESCRIPTION}`,
+  "---",
+  "",
+  "# Coder Studio Canvas",
+  "",
+  "Use this skill when the user asks you to draw an architecture diagram, create a visual overview, or when a diagram or structured report would communicate something more clearly than plain text alone.",
+  "",
+  "Typical triggers:",
+  "",
+  '- "画一个架构图"',
+  '- "draw an architecture diagram"',
+  '- "show me how the system is structured"',
+  '- "用图说明一下这个流程"',
+  "- any request where boxes-and-arrows or a structured visual summary would help",
+  "",
+  "## Canvas Kinds",
+  "",
+  "There are two canvas kinds:",
+  "",
+  "- `architecture_canvas`: boxes, edges, annotations — best for system diagrams, data flow, module relationships",
+  "- `report_canvas`: stats, markdown blocks, lists, tables, callouts — best for structured summaries, audits, status reports",
+  "",
+  "Choose the kind that fits the content. Default to `architecture_canvas` for diagrams.",
+  "",
+  "## Create And Open An Architecture Canvas",
+  "",
+  "Always use `--open` so the canvas appears as an editor tab immediately after creation.",
+  "",
+  "```bash",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.create --kind architecture_canvas --title "<title>" --document-json '<json>' --open --json`,
+  "```",
+  "",
+  "Document shape for `architecture_canvas` — uses Mermaid flowchart syntax in the `source` field:",
+  "",
+  "```json",
+  "{",
+  '  "summary": "One-line description of what this diagram shows.",',
+  '  "diagram": {',
+  '    "dsl": "mermaid",',
+  '    "source": "flowchart LR\\nWebUI[Web UI] --> Server[API Server]\\nServer --> DB[Database]"',
+  "  },",
+  '  "annotations": [',
+  '    { "title": "Boundary", "body": "Server owns all business logic." }',
+  "  ]",
+  "}",
+  "```",
+  "",
+  "Mermaid flowchart rules:",
+  "",
+  "- First line: `flowchart LR` (left-to-right) or `flowchart TB` (top-to-bottom)",
+  "- Node with label: `NodeID[Display Label]`",
+  "- Directed edge: `A --> B` or with label: `A -->|label| B`",
+  "- Subgraph: `subgraph GroupName` ... `end`",
+  "- One statement per line, separated by `\\n` in the JSON string",
+  "",
+  "Keep diagrams focused. 3-10 nodes is usually right. Use annotations to explain boundaries, ownership, or important constraints.",
+  "",
+  "## Create And Open A Report Canvas",
+  "",
+  "```bash",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.create --kind report_canvas --title "<title>" --document-json '<json>' --open --json`,
+  "```",
+  "",
+  "Document shape for `report_canvas`:",
+  "",
+  "```json",
+  "{",
+  '  "summary": "Workspace audit summary.",',
+  '  "stats": [',
+  '    { "label": "Packages", "value": 6, "tone": "info" }',
+  "  ],",
+  '  "sections": [',
+  "    {",
+  '      "title": "Findings",',
+  '      "blocks": [',
+  '        { "type": "markdown", "markdown": "Key finding goes here." },',
+  '        { "type": "callout", "tone": "warning", "title": "Risk", "body": "Explain the risk." }',
+  "      ]",
+  "    }",
+  "  ]",
+  "}",
+  "```",
+  "",
+  "Block types: `markdown`, `stats`, `list`, `table`, `callout`. Each section needs at least one block.",
+  "",
+  "## Canvas Source Files",
+  "",
+  "Every created canvas writes a readable `.coder-studio/canvases/<title-slug>.csc` file in the workspace. Treat that file path as the primary steady-state handle for opening and rendering canvases.",
+  "",
+  "Full source envelope example:",
+  "",
+  "```json",
+  "{",
+  '  "version": 1,',
+  '  "kind": "architecture_canvas",',
+  '  "title": "System Overview",',
+  '  "document": {',
+  '    "summary": "How the web UI, server, and database connect.",',
+  '    "diagram": {',
+  '      "dsl": "mermaid",',
+  '      "source": "flowchart LR\\nWebUI[Web UI] --> Server[API Server]\\nServer --> DB[Database]"',
+  "    },",
+  '    "annotations": [',
+  '      { "title": "Boundary", "body": "Server owns all business logic." }',
+  "    ]",
+  "  }",
+  "}",
+  "```",
+  "",
+  "## Open An Existing Canvas",
+  "",
+  "Prefer opening the `.csc` file path directly:",
+  "",
+  "```bash",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-file --path .coder-studio/canvases/<title-slug>.csc --json`,
+  "```",
+  "",
+  "If you only know the canvas id, `ui.open-canvas` remains available as a compatibility path:",
+  "",
+  "```bash",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-canvas --canvas <canvas-id> --json`,
+  "```",
+  "",
+  "Or list canvases first to find the id and source path you need:",
+  "",
+  "```bash",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.list --json`,
+  "```",
+  "",
+  "## Update A Canvas",
+  "",
+  "Update when the content changes but the canvas identity should stay the same:",
+  "",
+  "```bash",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.update --canvas <canvas-id> --document-json '<json>' --json`,
+  "```",
+  "",
+  "## Render",
+  "",
+  "Prefer rendering from the `.csc` source path:",
+  "",
+  "```bash",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.render --source-path .coder-studio/canvases/<title-slug>.csc --json`,
+  "```",
+  "",
+  "If you only have the canvas id, this also works:",
+  "",
+  "```bash",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" canvas.render --canvas <canvas-id> --json`,
+  "```",
+  "",
+  "## Notes",
+  "",
+  "- always use `--open` when creating a canvas so the user sees it immediately",
+  "- new canvas source files are stored as readable `.coder-studio/canvases/<title-slug>.csc` paths in the workspace",
+  "- title should be meaningful because it becomes the readable `.csc` slug",
+  "- raw HTML like `<div>` or `<span>` is invalid in canvas source",
+  "- keep diagrams small and focused; prefer multiple canvases over one overloaded diagram",
+  "- always include `--json` for machine-readable output",
+  "",
+].join("\n");
+
+export const CODER_STUDIO_CANVAS_SKILL: BuiltinSkillDefinition = {
+  slug: "coder-studio-canvas",
+  displayName: "Coder Studio Canvas",
+  description: DESCRIPTION,
+  version: "1.0.0",
+  defaultEnabled: true,
+  autoMountInMvp: true,
+  files: [
+    {
+      relativePath: AUTOMATION_CMD_FILE_NAME,
+      content: BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+    },
+  ],
+  mountRendering: "automation_bridge",
+  content: CONTENT,
+};
diff --git a/packages/server/src/skills/builtin/definitions/coder-studio-memory.ts b/packages/server/src/skills/builtin/definitions/coder-studio-memory.ts
index 4dd3edb4e..005b0ba13 100644
--- a/packages/server/src/skills/builtin/definitions/coder-studio-memory.ts
+++ b/packages/server/src/skills/builtin/definitions/coder-studio-memory.ts
@@ -1,9 +1,16 @@
+import {
+  AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN,
+  AUTOMATION_CMD_FILE_NAME,
+  BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+} from "../automation-bridge.js";
 import type { BuiltinSkillDefinition } from "./types.js";
 
+const DESCRIPTION = "Read and write durable Coder Studio workspace memory on demand.";
+
 const CONTENT = [
   "---",
   "name: coder-studio-memory",
-  "description: Read and write durable Coder Studio workspace memory on demand.",
+  `description: ${DESCRIPTION}`,
   "---",
   "",
   "# Coder Studio Memory",
@@ -17,15 +24,9 @@ const CONTENT = [
   "Prefer targeted reads before broad reads:",
   "",
   "```bash",
-  "coder-studio memory search architecture --workspace <workspace-id> --json",
-  "coder-studio memory list --workspace <workspace-id> --type project --json",
-  "coder-studio memory get <memory-id> --workspace <workspace-id> --json",
-  "```",
-  "",
-  "If `CODER_STUDIO_WORKSPACE_ID` is set, you can omit `--workspace`:",
-  "",
-  "```bash",
-  "coder-studio memory search testing --json",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.search architecture --json`,
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.list --type wiki --json`,
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.get <memory-id> --json`,
   "```",
   "",
   "## Write Stable Context",
@@ -34,27 +35,29 @@ const CONTENT = [
   "",
   "Avoid transient scratch notes, temporary debugging observations, secrets, credentials, or anything the user would not expect to persist.",
   "",
-  "Use `feature` for product behavior, `todo` for pending work, `bugfix` for defects, `project` for repository-operating knowledge, and `note` only as a fallback.",
+  "Use `wiki` for durable project knowledge, `issue` for defects or verification items, `todo` for concrete follow-up work, and `note` only as a fallback.",
   "",
   "Choose the narrowest type that matches the memory:",
   "",
-  "- `feature`: stable facts about what the product does or should do.",
-  "- `todo`: durable follow-up work that should remain visible later.",
-  "- `bugfix`: confirmed defects, causes, or fixes that matter beyond the current turn.",
-  "- `project`: repository-operating knowledge such as commands, conventions, directory expectations, or technical constraints.",
-  "- `note`: only when the memory is durable but does not fit the other four types cleanly.",
+  "- `wiki`: repository-operating knowledge such as commands, conventions, architecture, directory expectations, or technical constraints.",
+  "- `issue`: confirmed defects, investigation findings, or verification items that should remain visible later.",
+  "- `todo`: durable follow-up work with a concrete next action.",
+  "- `note`: durable context that does not fit the other three types cleanly.",
+  "",
+  "Status applies only to `issue` and `todo` memories. Use `not_started`, `in_progress`, `pending_verification`, or `completed` when the memory tracks work state.",
   "",
   "Write direct, searchable content that will still make sense in a later session.",
   "",
   "```bash",
-  'coder-studio memory add --workspace <workspace-id> --type project --content "This workspace uses pnpm for package scripts." --skill coder-studio-memory --json',
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.create --type wiki --content "This workspace uses pnpm for package scripts." --skill coder-studio-memory --json`,
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.create --type issue --content "Verify release notes before publishing." --status pending_verification --skill coder-studio-memory --json`,
   "```",
   "",
   "Update or delete memory when it becomes stale:",
   "",
   "```bash",
-  'coder-studio memory update <memory-id> --workspace <workspace-id> --content "Updated durable project context." --json',
-  "coder-studio memory delete <memory-id> --workspace <workspace-id> --json",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.update <memory-id> --content "Updated durable project context." --json`,
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" memory.delete <memory-id> --json`,
   "```",
   "",
   "Users can inspect, edit, and delete workspace memory from the Memory side panel.",
@@ -64,9 +67,16 @@ const CONTENT = [
 export const CODER_STUDIO_MEMORY_SKILL: BuiltinSkillDefinition = {
   slug: "coder-studio-memory",
   displayName: "Coder Studio Memory",
-  description: "Read and write durable Coder Studio workspace memory on demand.",
+  description: DESCRIPTION,
   version: "1.0.0",
   defaultEnabled: true,
   autoMountInMvp: true,
+  files: [
+    {
+      relativePath: AUTOMATION_CMD_FILE_NAME,
+      content: BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+    },
+  ],
+  mountRendering: "automation_bridge",
   content: CONTENT,
 };
diff --git a/packages/server/src/skills/builtin/definitions/coder-studio-open.ts b/packages/server/src/skills/builtin/definitions/coder-studio-open.ts
index 868a90e6e..558df42f5 100644
--- a/packages/server/src/skills/builtin/definitions/coder-studio-open.ts
+++ b/packages/server/src/skills/builtin/definitions/coder-studio-open.ts
@@ -1,34 +1,50 @@
+import {
+  AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN,
+  AUTOMATION_CMD_FILE_NAME,
+  BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+} from "../automation-bridge.js";
 import type { BuiltinSkillDefinition } from "./types.js";
 
+const DESCRIPTION =
+  "Use when an agent running inside Coder Studio needs to open or close a workspace file, open or close a localhost URL, or open a canvas for the user.";
+
 const CONTENT = [
   "---",
   "name: coder-studio-open",
-  "description: Use when an agent running inside Coder Studio needs to open or close a workspace file or localhost URL for the user.",
+  `description: ${DESCRIPTION}`,
   "---",
   "",
   "# Coder Studio Open",
   "",
-  "Use this only to open or close a workspace file in Coder Studio's editor or a localhost URL in Coder Studio's browser for the user.",
-  "",
-  "Run one of:",
+  "Use this only to open or close a workspace file, open or close a localhost URL, or open a canvas tab for the user inside Coder Studio.",
   "",
-  "coder-studio ui open-file --path <workspace-relative-path> [--line N] [--column N] [--workspace <workspace-id>] --json",
-  "coder-studio ui close-file --path <workspace-relative-path> [--workspace <workspace-id>] --json",
-  "coder-studio ui open-url --url http://127.0.0.1:5173 [--workspace <workspace-id>] --json",
-  "coder-studio ui close-url --url http://127.0.0.1:5173 [--workspace <workspace-id>] --json",
+  "Run the mounted bridge command directly:",
   "",
-  "If the CLI cannot find the running Coder Studio server, pass `--api-url <url>` or set `CODER_STUDIO_API_URL`.",
+  "```bash",
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-file --path src/index.ts --line 12 --json`,
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.close-file --path src/index.ts --json`,
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-url --url http://127.0.0.1:5173 --json`,
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.close-url --url http://127.0.0.1:5173 --json`,
+  `node "${AUTOMATION_CMD_ABSOLUTE_PATH_TOKEN}" ui.open-canvas --canvas canvas_123 --json`,
+  "```",
   "",
-  "Use workspace-relative file paths only; do not use absolute paths or `..` segments. URLs must be localhost `http` or `https` URLs. Close commands only close a matching file path or current browser URL. `accepted: true` means the request was dispatched, not that the frontend has finished rendering it.",
+  "Use workspace-relative file paths only; do not use absolute paths or `..` segments. URLs must stay on localhost `http` or `https`. Close commands only close a matching file path or the current browser URL. `accepted: true` means the request was dispatched, not that the frontend has finished rendering it.",
   "",
 ].join("\n");
 
 export const CODER_STUDIO_OPEN_SKILL: BuiltinSkillDefinition = {
   slug: "coder-studio-open",
   displayName: "Coder Studio Open",
-  description: "Open workspace files and localhost URLs in Coder Studio.",
+  description: DESCRIPTION,
   version: "1.0.0",
   defaultEnabled: true,
   autoMountInMvp: true,
+  files: [
+    {
+      relativePath: AUTOMATION_CMD_FILE_NAME,
+      content: BUILTIN_AUTOMATION_BRIDGE_SOURCE,
+    },
+  ],
+  mountRendering: "automation_bridge",
   content: CONTENT,
 };
diff --git a/packages/server/src/skills/builtin/definitions/index.ts b/packages/server/src/skills/builtin/definitions/index.ts
index 8aeb71453..4bc45c19c 100644
--- a/packages/server/src/skills/builtin/definitions/index.ts
+++ b/packages/server/src/skills/builtin/definitions/index.ts
@@ -1,8 +1,14 @@
+import { CODER_STUDIO_CANVAS_SKILL } from "./coder-studio-canvas.js";
 import { CODER_STUDIO_MEMORY_SKILL } from "./coder-studio-memory.js";
 import { CODER_STUDIO_OPEN_SKILL } from "./coder-studio-open.js";
 
+export { CODER_STUDIO_CANVAS_SKILL } from "./coder-studio-canvas.js";
 export { CODER_STUDIO_MEMORY_SKILL } from "./coder-studio-memory.js";
 export { CODER_STUDIO_OPEN_SKILL } from "./coder-studio-open.js";
 export type { BuiltinSkillDefinition } from "./types.js";
 
-export const BUILTIN_SKILLS = [CODER_STUDIO_OPEN_SKILL, CODER_STUDIO_MEMORY_SKILL];
+export const BUILTIN_SKILLS = [
+  CODER_STUDIO_OPEN_SKILL,
+  CODER_STUDIO_MEMORY_SKILL,
+  CODER_STUDIO_CANVAS_SKILL,
+];
diff --git a/packages/server/src/skills/builtin/definitions/types.ts b/packages/server/src/skills/builtin/definitions/types.ts
index 6518189a1..0d38b2dee 100644
--- a/packages/server/src/skills/builtin/definitions/types.ts
+++ b/packages/server/src/skills/builtin/definitions/types.ts
@@ -1,3 +1,8 @@
+export interface BuiltinSkillManagedFile {
+  relativePath: string;
+  content: string;
+}
+
 export interface BuiltinSkillDefinition {
   slug: string;
   displayName: string;
@@ -6,4 +11,6 @@ export interface BuiltinSkillDefinition {
   defaultEnabled: boolean;
   autoMountInMvp: boolean;
   content: string;
+  files?: readonly BuiltinSkillManagedFile[];
+  mountRendering?: "none" | "automation_bridge";
 }
diff --git a/packages/server/src/skills/builtin/materialize.ts b/packages/server/src/skills/builtin/materialize.ts
index bd0e99ba4..799f5c062 100644
--- a/packages/server/src/skills/builtin/materialize.ts
+++ b/packages/server/src/skills/builtin/materialize.ts
@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { SkillLibraryEntry } from "@coder-studio/core";
+import { writeManagedSkillMarker } from "../managed-skill-metadata.js";
 import { BUILTIN_SKILLS, type BuiltinSkillDefinition } from "./definitions/index.js";
 
 export interface MaterializeBuiltinSkillsInput {
@@ -20,12 +21,24 @@ export async function materializeBuiltinSkills(
     const libraryPath = join(input.builtinRoot, skill.slug);
     await mkdir(libraryPath, { recursive: true });
     await writeFile(join(libraryPath, "SKILL.md"), `${skill.content.trimEnd()}\n`, "utf8");
+    for (const managedFile of skill.files ?? []) {
+      const managedFilePath = join(libraryPath, managedFile.relativePath);
+      await mkdir(dirname(managedFilePath), { recursive: true });
+      await writeFile(managedFilePath, `${managedFile.content.trimEnd()}\n`, "utf8");
+    }
+    writeManagedSkillMarker(libraryPath, {
+      version: 1,
+      managedBy: "coder-studio",
+      source: "builtin",
+      slug: skill.slug,
+    });
     entries.push({
       slug: skill.slug,
       displayName: skill.displayName,
       description: skill.description,
       version: skill.version,
       source: "builtin",
+      origin: "builtin",
       libraryPath,
       installState: "installed",
       installedAt: now,
diff --git a/packages/server/src/skills/builtin/registry.ts b/packages/server/src/skills/builtin/registry.ts
index 49e69a7d3..b9c8781e8 100644
--- a/packages/server/src/skills/builtin/registry.ts
+++ b/packages/server/src/skills/builtin/registry.ts
@@ -1,5 +1,6 @@
 export {
   BUILTIN_SKILLS,
+  CODER_STUDIO_CANVAS_SKILL,
   CODER_STUDIO_MEMORY_SKILL,
   CODER_STUDIO_OPEN_SKILL,
 } from "./definitions/index.js";
diff --git a/packages/server/src/skills/builtin/stale-cleanup.ts b/packages/server/src/skills/builtin/stale-cleanup.ts
index 9ec055b33..944a78fc6 100644
--- a/packages/server/src/skills/builtin/stale-cleanup.ts
+++ b/packages/server/src/skills/builtin/stale-cleanup.ts
@@ -167,7 +167,11 @@ async function listStaleLocalBuiltinArtifacts(
 ): Promise<Map<string, StaleLocalBuiltinArtifact>> {
   const artifacts = new Map<string, StaleLocalBuiltinArtifact>();
   for (const entry of libraryEntries) {
-    if (entry.source !== "local" || currentSlugs.has(entry.slug)) {
+    if (
+      entry.source !== "installed" ||
+      entry.origin !== "filesystem" ||
+      currentSlugs.has(entry.slug)
+    ) {
       continue;
     }
 
@@ -184,26 +188,51 @@ async function listStaleLocalBuiltinArtifacts(
 }
 
 async function resolveLocalBuiltinArtifactPath(
-  targetPath: string,
+  discoveredPath: string,
   skillSlug: string
 ): Promise<string | undefined> {
   let stat: Awaited<ReturnType<typeof lstat>>;
   try {
-    stat = await lstat(targetPath);
+    stat = await lstat(discoveredPath);
+  } catch {
+    return undefined;
+  }
+
+  if (stat.isSymbolicLink()) {
+    const linkTarget = await readlink(discoveredPath).catch(() => undefined);
+    if (!linkTarget) {
+      return undefined;
+    }
+
+    const resolvedTarget = resolve(dirname(discoveredPath), linkTarget);
+    if (
+      !isCoderStudioBuiltinArtifactPath(resolvedTarget, skillSlug) ||
+      !(await hasSkillMarkdown(resolvedTarget))
+    ) {
+      return undefined;
+    }
+
+    return resolvedTarget;
+  }
+
+  const parentPath = dirname(discoveredPath);
+  let parentStat: Awaited<ReturnType<typeof lstat>>;
+  try {
+    parentStat = await lstat(parentPath);
   } catch {
     return undefined;
   }
 
-  if (!stat.isSymbolicLink()) {
+  if (!parentStat.isSymbolicLink()) {
     return undefined;
   }
 
-  const linkTarget = await readlink(targetPath).catch(() => undefined);
-  if (!linkTarget) {
+  const parentLinkTarget = await readlink(parentPath).catch(() => undefined);
+  if (!parentLinkTarget) {
     return undefined;
   }
 
-  const resolvedTarget = resolve(dirname(targetPath), linkTarget);
+  const resolvedTarget = join(resolve(dirname(parentPath), parentLinkTarget), skillSlug);
   if (
     !isCoderStudioBuiltinArtifactPath(resolvedTarget, skillSlug) ||
     !(await hasSkillMarkdown(resolvedTarget))
diff --git a/packages/server/src/skills/builtin/sync-manager.ts b/packages/server/src/skills/builtin/sync-manager.ts
index 9cae6d874..69e26c7c8 100644
--- a/packages/server/src/skills/builtin/sync-manager.ts
+++ b/packages/server/src/skills/builtin/sync-manager.ts
@@ -1,11 +1,13 @@
+import { join } from "node:path";
 import type { ProviderDefinition, SkillLibraryEntry, SkillMountRelation } from "@coder-studio/core";
 import type { SettingsRepo } from "../../storage/repositories/settings-repo.js";
 import type { SkillLibraryRepo } from "../../storage/repositories/skill-library-repo.js";
 import type { SkillMountRepo } from "../../storage/repositories/skill-mount-repo.js";
 import type { SkillMountManager } from "../mount-manager.js";
+import { renderMountedSkillContent } from "./automation-bridge.js";
 import { materializeBuiltinSkills } from "./materialize.js";
 import { BuiltinSkillMountPreferences } from "./mount-preferences.js";
-import type { BuiltinSkillDefinition } from "./registry.js";
+import { BUILTIN_SKILLS, type BuiltinSkillDefinition } from "./registry.js";
 import { removeStaleBuiltinSkills } from "./stale-cleanup.js";
 
 export interface BuiltinSkillSyncManagerDeps {
@@ -32,10 +34,11 @@ export class BuiltinSkillSyncManager {
   constructor(private readonly deps: BuiltinSkillSyncManagerDeps) {}
 
   async sync(): Promise<BuiltinSkillSyncResult> {
+    const builtinDefinitions = this.getBuiltinDefinitions();
     const entries = await materializeBuiltinSkills({
       builtinRoot: this.deps.builtinRoot,
       now: this.deps.now,
-      skills: this.deps.skills,
+      skills: builtinDefinitions,
     });
     for (const entry of entries) {
       this.deps.skillLibraryRepo.set(entry);
@@ -80,6 +83,7 @@ export class BuiltinSkillSyncManager {
           providerId: provider.id,
           skillSlug: entry.slug,
           enabled: true,
+          ...this.getMountRenderingPlan(provider, entry.slug, builtinDefinitions),
         });
         this.deps.skillMountRepo.upsert(relation);
         mounted.push(relation);
@@ -113,4 +117,35 @@ export class BuiltinSkillSyncManager {
     this.preferences = new BuiltinSkillMountPreferences(this.deps.settingsRepo);
     return this.preferences;
   }
+
+  private getBuiltinDefinitions(): readonly BuiltinSkillDefinition[] {
+    return this.deps.skills ?? BUILTIN_SKILLS;
+  }
+
+  private getMountRenderingPlan(
+    provider: ProviderDefinition,
+    skillSlug: string,
+    definitions: readonly BuiltinSkillDefinition[]
+  ): Pick<Parameters<SkillMountManager["mount"]>[0], "preferredMode" | "mountedOverrides"> {
+    const definition = definitions.find((item) => item.slug === skillSlug);
+    if (definition?.mountRendering !== "automation_bridge") {
+      return {};
+    }
+
+    const providerSkillDir = provider?.skillMountDirectories?.[0];
+    if (!providerSkillDir) {
+      return { preferredMode: "copy" };
+    }
+
+    const targetPath = join(providerSkillDir, skillSlug);
+    return {
+      preferredMode: "copy",
+      mountedOverrides: [
+        {
+          relativePath: "SKILL.md",
+          content: `${renderMountedSkillContent(definition.content, targetPath).trimEnd()}\n`,
+        },
+      ],
+    };
+  }
 }
diff --git a/packages/server/src/skills/custom-skill.ts b/packages/server/src/skills/custom-skill.ts
new file mode 100644
index 000000000..9670c2471
--- /dev/null
+++ b/packages/server/src/skills/custom-skill.ts
@@ -0,0 +1,61 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { SkillLibraryEntry } from "@coder-studio/core";
+import { writeManagedSkillMarker } from "./managed-skill-metadata.js";
+
+export function slugifySkillName(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+export async function createCustomSkill(input: {
+  rootDir: string;
+  name: string;
+}): Promise<SkillLibraryEntry> {
+  const displayName = input.name.trim();
+  const slug = slugifySkillName(displayName);
+
+  if (!slug) {
+    throw { code: "invalid_skill_name", message: "Skill name must produce a valid slug" };
+  }
+
+  const libraryPath = join(input.rootDir, slug);
+  await mkdir(input.rootDir, { recursive: true });
+  await mkdir(libraryPath, { recursive: false });
+
+  const markdown = [
+    "---",
+    `name: ${slug}`,
+    "description: Custom skill",
+    "---",
+    "",
+    `# ${displayName}`,
+    "",
+  ].join("\n");
+
+  await writeFile(join(libraryPath, "SKILL.md"), markdown, "utf8");
+  writeManagedSkillMarker(libraryPath, {
+    version: 1,
+    managedBy: "coder-studio",
+    source: "custom",
+    slug,
+  });
+
+  const now = Date.now();
+  return {
+    slug,
+    displayName,
+    description: "Custom skill",
+    version: "local",
+    source: "custom",
+    origin: "filesystem",
+    libraryPath,
+    installState: "installed",
+    installedAt: now,
+    updatedAt: now,
+  };
+}
diff --git a/packages/server/src/skills/install-manager.ts b/packages/server/src/skills/install-manager.ts
index 733a68b3f..b20be299b 100644
--- a/packages/server/src/skills/install-manager.ts
+++ b/packages/server/src/skills/install-manager.ts
@@ -29,6 +29,10 @@ interface SkillInfoLike {
   version?: string;
 }
 
+function canOverwriteWithSkillHubInstall(existing: SkillLibraryEntry | undefined): boolean {
+  return !existing || (existing.source === "installed" && existing.origin === "skillhub");
+}
+
 export class SkillInstallManager {
   private readonly jobs = new Map<string, SkillInstallJobSnapshot>();
   private readonly activeJobIdsBySlug = new Map<string, string>();
@@ -88,6 +92,11 @@ export class SkillInstallManager {
       markStep(job, "stage-install", "running");
       this.jobs.set(job.jobId, job);
 
+      const existing = this.deps.skillLibraryRepo.get(job.slug);
+      if (!canOverwriteWithSkillHubInstall(existing)) {
+        throw new Error(`A skill with slug ${job.slug} already exists`);
+      }
+
       const info = (await this.deps.skillsHubClient.info(job.slug).catch(() => undefined)) as
         | SkillInfoLike
         | undefined;
@@ -145,7 +154,8 @@ export class SkillInstallManager {
       displayName: info?.name?.trim() || slug,
       description: info?.description?.trim() || undefined,
       version: info?.version?.trim() || "1",
-      source: "skillhub",
+      source: "installed",
+      origin: "skillhub",
       libraryPath,
       installState: "installed",
       installedAt: existing?.installedAt ?? now,
diff --git a/packages/server/src/skills/local-skill-scanner.ts b/packages/server/src/skills/local-skill-scanner.ts
index bc024162e..9a48a2e71 100644
--- a/packages/server/src/skills/local-skill-scanner.ts
+++ b/packages/server/src/skills/local-skill-scanner.ts
@@ -3,12 +3,20 @@ import { accessSync, constants, readdirSync, readFileSync, statSync } from "node
 import { homedir } from "node:os";
 import { join } from "node:path";
 import type { SkillLibraryEntry } from "@coder-studio/core";
+import { readManagedSkillMarker } from "./managed-skill-metadata.js";
 
 interface SkillMarkdownMetadata {
   description?: string;
   version?: string;
 }
 
+export interface ScanDiscoveredSkillEntriesInput {
+  customRoot?: string;
+  externalRoots: string[];
+  builtinRoot?: string;
+  managedLibraryRoot?: string;
+}
+
 export function resolveDefaultLocalSkillRoots(): string[] {
   if (process.env.NODE_ENV === "test") {
     return [];
@@ -18,20 +26,95 @@ export function resolveDefaultLocalSkillRoots(): string[] {
 }
 
 export function scanLocalSkillEntries(roots: string[]): SkillLibraryEntry[] {
+  return scanDiscoveredSkillEntries({ externalRoots: roots });
+}
+
+export function scanDiscoveredSkillEntries(
+  input: ScanDiscoveredSkillEntriesInput
+): SkillLibraryEntry[] {
   const discovered = new Map<string, SkillLibraryEntry>();
+  const reserved = new Set<string>();
+
+  reserveSkillSlugs(input.builtinRoot, reserved);
+
+  for (const entry of scanLocalSkillRoot(input.customRoot, {
+    source: "custom",
+    origin: "filesystem",
+    reserved,
+  })) {
+    discovered.set(entry.slug, entry);
+    reserved.add(entry.slug);
+  }
+
+  reserveSkillSlugs(input.managedLibraryRoot, reserved);
 
-  for (const root of roots) {
-    for (const entry of scanLocalSkillRoot(root)) {
+  for (const root of input.externalRoots) {
+    for (const entry of scanLocalSkillRoot(root, {
+      source: "installed",
+      origin: "filesystem",
+      reserved,
+      skipManagedMirrors: true,
+    })) {
       if (!discovered.has(entry.slug)) {
         discovered.set(entry.slug, entry);
       }
+      reserved.add(entry.slug);
     }
   }
 
   return [...discovered.values()];
 }
 
-function scanLocalSkillRoot(root: string): SkillLibraryEntry[] {
+function reserveSkillSlugs(root: string | undefined, reserved: Set<string>): void {
+  for (const slug of scanSkillSlugs(root)) {
+    reserved.add(slug);
+  }
+}
+
+function scanSkillSlugs(root: string | undefined): string[] {
+  if (!root) {
+    return [];
+  }
+
+  let dirents: Dirent[];
+  try {
+    dirents = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const slugs: string[] = [];
+  for (const dirent of dirents) {
+    if (!dirent.isDirectory() && !dirent.isSymbolicLink()) {
+      continue;
+    }
+
+    const skillDir = join(root, dirent.name);
+    const skillMdPath = join(skillDir, "SKILL.md");
+    try {
+      accessSync(skillMdPath, constants.F_OK);
+      slugs.push(dirent.name);
+    } catch {
+      continue;
+    }
+  }
+
+  return slugs;
+}
+
+function scanLocalSkillRoot(
+  root: string | undefined,
+  options: {
+    source: SkillLibraryEntry["source"];
+    origin: NonNullable<SkillLibraryEntry["origin"]>;
+    reserved: Set<string>;
+    skipManagedMirrors?: boolean;
+  }
+): SkillLibraryEntry[] {
+  if (!root) {
+    return [];
+  }
+
   let dirents: Dirent[];
   try {
     dirents = readdirSync(root, { withFileTypes: true });
@@ -48,6 +131,17 @@ function scanLocalSkillRoot(root: string): SkillLibraryEntry[] {
     const skillDir = join(root, dirent.name);
     const skillMdPath = join(skillDir, "SKILL.md");
 
+    if (options.reserved.has(dirent.name)) {
+      continue;
+    }
+
+    if (options.skipManagedMirrors) {
+      const marker = readManagedSkillMarker(skillDir);
+      if (marker && marker.managedBy === "coder-studio") {
+        continue;
+      }
+    }
+
     try {
       accessSync(skillMdPath, constants.F_OK);
       const markdown = readFileSync(skillMdPath, "utf8");
@@ -61,7 +155,8 @@ function scanLocalSkillRoot(root: string): SkillLibraryEntry[] {
         displayName: toDisplayName(dirent.name),
         description: metadata.description,
         version: metadata.version ?? "local",
-        source: "local",
+        source: options.source,
+        origin: options.origin,
         libraryPath: skillDir,
         installState: "installed",
         installedAt,
diff --git a/packages/server/src/skills/managed-skill-metadata.ts b/packages/server/src/skills/managed-skill-metadata.ts
new file mode 100644
index 000000000..dac2d7c8d
--- /dev/null
+++ b/packages/server/src/skills/managed-skill-metadata.ts
@@ -0,0 +1,45 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const CODER_STUDIO_SKILL_MARKER = ".coder-studio-skill.json";
+
+export interface ManagedSkillMarker {
+  version: 1;
+  managedBy: "coder-studio";
+  source: "builtin" | "custom";
+  slug: string;
+}
+
+function isManagedSkillMarker(value: unknown): value is ManagedSkillMarker {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+
+  const candidate = value as Partial<ManagedSkillMarker>;
+  return (
+    candidate.version === 1 &&
+    candidate.managedBy === "coder-studio" &&
+    (candidate.source === "builtin" || candidate.source === "custom") &&
+    typeof candidate.slug === "string" &&
+    candidate.slug.trim().length > 0
+  );
+}
+
+export function readManagedSkillMarker(skillDir: string): ManagedSkillMarker | undefined {
+  try {
+    const raw = readFileSync(join(skillDir, CODER_STUDIO_SKILL_MARKER), "utf8");
+    const parsed = JSON.parse(raw);
+    return isManagedSkillMarker(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeManagedSkillMarker(skillDir: string, marker: ManagedSkillMarker): void {
+  mkdirSync(skillDir, { recursive: true });
+  writeFileSync(
+    join(skillDir, CODER_STUDIO_SKILL_MARKER),
+    `${JSON.stringify(marker, null, 2)}\n`,
+    "utf8"
+  );
+}
diff --git a/packages/server/src/skills/mount-manager.ts b/packages/server/src/skills/mount-manager.ts
index bc54048b2..cefcac0cf 100644
--- a/packages/server/src/skills/mount-manager.ts
+++ b/packages/server/src/skills/mount-manager.ts
@@ -1,4 +1,14 @@
-import { copyFile, lstat, mkdir, readdir, readlink, rm, symlink, unlink } from "node:fs/promises";
+import {
+  copyFile,
+  lstat,
+  mkdir,
+  readdir,
+  readlink,
+  rm,
+  symlink,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import type { ProviderDefinition, SkillMountRelation } from "@coder-studio/core";
 import type { SkillLibraryRepo } from "../storage/repositories/skill-library-repo.js";
@@ -14,6 +24,8 @@ export interface SkillMountPlan {
   providerId: string;
   skillSlug: string;
   enabled: boolean;
+  preferredMode?: "auto" | "copy";
+  mountedOverrides?: Array<{ relativePath: string; content: string }>;
 }
 
 export class SkillMountManager {
@@ -74,14 +86,30 @@ export class SkillMountManager {
       await unlinkSafe(existing.targetPath);
     }
 
+    const shouldCopyMount =
+      input.preferredMode === "copy" || (input.mountedOverrides?.length ?? 0) > 0;
+
     let mountModeResolved: SkillMountRelation["mountModeResolved"] = "symlink";
-    try {
-      await rm(targetPath, { recursive: true, force: true });
-      await symlink(libraryEntry.libraryPath, targetPath);
-    } catch {
+    if (shouldCopyMount) {
       mountModeResolved = "copy";
       await rm(targetPath, { recursive: true, force: true });
       await copyRecursively(libraryEntry.libraryPath, targetPath);
+    } else {
+      try {
+        await rm(targetPath, { recursive: true, force: true });
+        await symlink(libraryEntry.libraryPath, targetPath);
+      } catch {
+        mountModeResolved = "copy";
+        await rm(targetPath, { recursive: true, force: true });
+        await copyRecursively(libraryEntry.libraryPath, targetPath);
+      }
+    }
+
+    for (const override of input.mountedOverrides ?? []) {
+      const overridePath = join(targetPath, override.relativePath);
+      await mkdir(dirname(overridePath), { recursive: true });
+      await unlinkIfSymlink(overridePath);
+      await writeFile(overridePath, override.content, "utf8");
     }
 
     const relation: SkillMountRelation = {
@@ -134,6 +162,17 @@ async function unlinkSafe(path: string): Promise<void> {
   }
 }
 
+async function unlinkIfSymlink(path: string): Promise<void> {
+  try {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink()) {
+      await unlink(path);
+    }
+  } catch {
+    return;
+  }
+}
+
 async function copyRecursively(source: string, target: string): Promise<void> {
   await mkdir(target, { recursive: true });
   const entries = await readdir(source, { withFileTypes: true });
diff --git a/packages/server/src/skills/recommendation.ts b/packages/server/src/skills/recommendation.ts
index 42f7f62d9..b5de78577 100644
--- a/packages/server/src/skills/recommendation.ts
+++ b/packages/server/src/skills/recommendation.ts
@@ -1,4 +1,8 @@
-import type { SkillRecommendationEntry, WorkspaceIntelligenceSummary } from "@coder-studio/core";
+import type {
+  SkillRecommendationEntry,
+  SkillRecommendationPage,
+  WorkspaceIntelligenceSummary,
+} from "@coder-studio/core";
 
 export interface SkillRecommendationSearchResult {
   slug: string;
@@ -22,13 +26,12 @@ interface RecommendationAccumulator {
   sourceQueryScore: number;
 }
 
-const DEFAULT_RECOMMENDATION_LIMIT = 5;
+const DEFAULT_RECOMMENDATION_LIMIT = 20;
 
-export async function buildSkillRecommendations(input: {
+export async function buildSkillRecommendationEntries(input: {
   intelligence: WorkspaceIntelligenceSummary;
   search: (query: string) => Promise<SkillRecommendationSearchResult[]>;
   isInstalled: (slug: string) => boolean;
-  limit?: number;
 }): Promise<SkillRecommendationEntry[]> {
   const seeds = buildRecommendationQueries(input.intelligence);
   if (seeds.length === 0) {
@@ -88,7 +91,6 @@ export async function buildSkillRecommendations(input: {
         left.slug.localeCompare(right.slug, undefined, { sensitivity: "base" })
       );
     })
-    .slice(0, input.limit ?? DEFAULT_RECOMMENDATION_LIMIT)
     .map((entry) => ({
       slug: entry.slug,
       displayName: entry.displayName,
@@ -100,6 +102,24 @@ export async function buildSkillRecommendations(input: {
     }));
 }
 
+export async function buildSkillRecommendations(input: {
+  intelligence: WorkspaceIntelligenceSummary;
+  search: (query: string) => Promise<SkillRecommendationSearchResult[]>;
+  isInstalled: (slug: string) => boolean;
+  limit?: number;
+  offset?: number;
+}): Promise<SkillRecommendationPage> {
+  const entries = await buildSkillRecommendationEntries(input);
+  const offset = input.offset ?? 0;
+  const limit = input.limit ?? DEFAULT_RECOMMENDATION_LIMIT;
+  const pageEntries = entries.slice(offset, offset + limit);
+
+  return {
+    entries: pageEntries,
+    hasMore: offset + pageEntries.length < entries.length,
+  };
+}
+
 function buildRecommendationQueries(
   summary: WorkspaceIntelligenceSummary
 ): RecommendationQuerySeed[] {
diff --git a/packages/server/src/storage/repositories/canvas-repo.test.ts b/packages/server/src/storage/repositories/canvas-repo.test.ts
new file mode 100644
index 000000000..884c45dd8
--- /dev/null
+++ b/packages/server/src/storage/repositories/canvas-repo.test.ts
@@ -0,0 +1,120 @@
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { CanvasRepo } from "./canvas-repo.js";
+
+describe("CanvasRepo", () => {
+  let tempDir: string;
+  let repo: CanvasRepo;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "canvas-repo-"));
+    repo = new CanvasRepo({ rootDir: join(tempDir, "canvases") });
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("lists and gets records ordered by updatedAt descending", () => {
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "workspace/one",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      artifactType: "architecture_canvas",
+      title: "Runtime Flow",
+      updatedAt: 100,
+      renderStatus: "ready",
+      lastError: null,
+    });
+
+    repo.upsert({
+      id: "canvas-2",
+      workspaceId: "workspace/one",
+      sourcePath: ".coder-studio/canvases/canvas-2.canvas.json",
+      artifactType: "report_canvas",
+      title: "Audit",
+      updatedAt: 200,
+      renderStatus: "error",
+      lastError: {
+        category: "compile_error",
+        message: "compile failed",
+      },
+    });
+
+    expect(repo.get("workspace/one", "canvas-1")).toMatchObject({
+      id: "canvas-1",
+      title: "Runtime Flow",
+    });
+    expect(repo.list("workspace/one").map((record) => record.id)).toEqual(["canvas-2", "canvas-1"]);
+  });
+
+  it("upserts and deletes a single record without affecting the workspace file", () => {
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      artifactType: "architecture_canvas",
+      title: "Original",
+      updatedAt: 100,
+      renderStatus: "ready",
+      lastError: null,
+    });
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      artifactType: "architecture_canvas",
+      title: "Updated",
+      updatedAt: 300,
+      renderStatus: "ready",
+      lastError: null,
+    });
+    repo.upsert({
+      id: "canvas-2",
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/canvas-2.canvas.json",
+      artifactType: "report_canvas",
+      title: "Keep",
+      updatedAt: 200,
+      renderStatus: "ready",
+      lastError: null,
+    });
+
+    repo.delete("ws-1", "canvas-1");
+
+    expect(repo.get("ws-1", "canvas-1")).toBeUndefined();
+    expect(repo.list("ws-1")).toEqual([
+      expect.objectContaining({
+        id: "canvas-2",
+        title: "Keep",
+      }),
+    ]);
+  });
+
+  it("removes the workspace metadata file", () => {
+    repo.upsert({
+      id: "canvas-1",
+      workspaceId: "workspace/with spaces",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      artifactType: "architecture_canvas",
+      title: "Runtime Flow",
+      updatedAt: 100,
+      renderStatus: "ready",
+      lastError: null,
+    });
+
+    const filePath = join(
+      tempDir,
+      "canvases",
+      `${encodeURIComponent("workspace/with spaces")}.json`
+    );
+    expect(existsSync(filePath)).toBe(true);
+
+    repo.removeWorkspace("workspace/with spaces");
+
+    expect(existsSync(filePath)).toBe(false);
+    expect(repo.list("workspace/with spaces")).toEqual([]);
+  });
+});
diff --git a/packages/server/src/storage/repositories/canvas-repo.ts b/packages/server/src/storage/repositories/canvas-repo.ts
new file mode 100644
index 000000000..26345215f
--- /dev/null
+++ b/packages/server/src/storage/repositories/canvas-repo.ts
@@ -0,0 +1,68 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import type { CanvasRecord } from "@coder-studio/core";
+import { readJsonFile, writeJsonFileAtomic } from "./json-file-store.js";
+
+interface CanvasRepoOptions {
+  rootDir: string;
+}
+
+interface CanvasWorkspaceFile {
+  version: 1;
+  workspaceId: string;
+  canvases: Record<string, CanvasRecord>;
+}
+
+function emptyWorkspaceFile(workspaceId: string): CanvasWorkspaceFile {
+  return {
+    version: 1,
+    workspaceId,
+    canvases: {},
+  };
+}
+
+export class CanvasRepo {
+  constructor(private readonly options: CanvasRepoOptions) {}
+
+  list(workspaceId: string): CanvasRecord[] {
+    return Object.values(this.readWorkspaceFile(workspaceId).canvases).sort(
+      (left, right) => right.updatedAt - left.updatedAt
+    );
+  }
+
+  get(workspaceId: string, canvasId: string): CanvasRecord | undefined {
+    return this.readWorkspaceFile(workspaceId).canvases[canvasId];
+  }
+
+  upsert(record: CanvasRecord): CanvasRecord {
+    const file = this.readWorkspaceFile(record.workspaceId);
+    file.canvases[record.id] = record;
+    this.writeWorkspaceFile(file);
+    return record;
+  }
+
+  delete(workspaceId: string, canvasId: string): void {
+    const file = this.readWorkspaceFile(workspaceId);
+    delete file.canvases[canvasId];
+    this.writeWorkspaceFile(file);
+  }
+
+  removeWorkspace(workspaceId: string): void {
+    rmSync(this.filePath(workspaceId), { force: true });
+  }
+
+  private readWorkspaceFile(workspaceId: string): CanvasWorkspaceFile {
+    return (
+      readJsonFile<CanvasWorkspaceFile>(this.filePath(workspaceId)) ??
+      emptyWorkspaceFile(workspaceId)
+    );
+  }
+
+  private writeWorkspaceFile(file: CanvasWorkspaceFile): void {
+    writeJsonFileAtomic(this.filePath(file.workspaceId), file);
+  }
+
+  private filePath(workspaceId: string): string {
+    return join(this.options.rootDir, `${encodeURIComponent(workspaceId)}.json`);
+  }
+}
diff --git a/packages/server/src/storage/repositories/memory-repo.test.ts b/packages/server/src/storage/repositories/memory-repo.test.ts
index acf0c2983..4f34845a4 100644
--- a/packages/server/src/storage/repositories/memory-repo.test.ts
+++ b/packages/server/src/storage/repositories/memory-repo.test.ts
@@ -32,7 +32,7 @@ describe("MemoryRepo", () => {
   it("stores each workspace in an encoded workspace file", () => {
     const entry = repo.create({
       workspaceId: "workspace/with spaces",
-      type: "project",
+      type: "wiki",
       content: "Keep memory outside the Git workspace.",
       source: { kind: "user" },
     });
@@ -50,7 +50,7 @@ describe("MemoryRepo", () => {
       entries: {
         [entry.id]: {
           workspaceId: "workspace/with spaces",
-          type: "project",
+          type: "wiki",
           content: "Keep memory outside the Git workspace.",
         },
       },
@@ -66,7 +66,7 @@ describe("MemoryRepo", () => {
   it("creates and reloads entries sorted by updated time descending", () => {
     const first = repo.create({
       workspaceId: "ws-1",
-      type: "project",
+      type: "wiki",
       content: "This was learned first.",
       source: { kind: "user" },
     });
@@ -107,14 +107,15 @@ describe("MemoryRepo", () => {
       repo.update({
         workspaceId: "ws-1",
         id: entry.id,
-        type: "bugfix",
+        type: "issue",
         content: "Updated content",
       })
     ).toEqual({
       id: entry.id,
       workspaceId: "ws-1",
-      type: "bugfix",
+      type: "issue",
       content: "Updated content",
+      status: "not_started",
       source: { kind: "user" },
       createdAt: entry.createdAt,
       updatedAt: now,
@@ -138,9 +139,9 @@ describe("MemoryRepo", () => {
   });
 
   it("filters and searches only content and type case-insensitively", () => {
-    const projectEntry = repo.create({
+    const wikiEntry = repo.create({
       workspaceId: "ws-1",
-      type: "project",
+      type: "wiki",
       content: "Do not dirty the Git workspace.",
       source: { kind: "user" },
     });
@@ -151,7 +152,7 @@ describe("MemoryRepo", () => {
       source: { kind: "agent" },
     });
 
-    expect(repo.list({ workspaceId: "ws-1", query: "dirty" })).toEqual([projectEntry]);
+    expect(repo.list({ workspaceId: "ws-1", query: "dirty" })).toEqual([wikiEntry]);
     expect(repo.list({ workspaceId: "ws-1", query: "todo" })).toHaveLength(1);
     expect(repo.list({ workspaceId: "ws-1", query: "agent" })).toEqual([]);
     expect(repo.list({ workspaceId: "ws-1", type: "todo" })).toHaveLength(1);
@@ -212,7 +213,7 @@ describe("MemoryRepo", () => {
     now += 1000;
     const created = repo.create({
       workspaceId,
-      type: "project",
+      type: "wiki",
       content: "Only the new taxonomy persists.",
       source: { kind: "user" },
     });
@@ -224,7 +225,7 @@ describe("MemoryRepo", () => {
         [created.id]: {
           id: created.id,
           workspaceId,
-          type: "project",
+          type: "wiki",
           content: "Only the new taxonomy persists.",
           source: { kind: "user" },
           createdAt: now,
@@ -277,6 +278,270 @@ describe("MemoryRepo", () => {
     expect(repo.list({ workspaceId })).toEqual([]);
   });
 
+  it("normalizes legacy stored aliases and returns entries sorted by updated time descending", () => {
+    const workspaceId = "ws-legacy-aliases";
+    const filePath = join(tempDir, "memory", "workspaces", `${workspaceId}.json`);
+    mkdirSync(join(tempDir, "memory", "workspaces"), { recursive: true });
+    writeFileSync(
+      filePath,
+      JSON.stringify(
+        {
+          version: 1,
+          workspaceId,
+          entries: {
+            project: {
+              id: "project",
+              workspaceId,
+              type: "project",
+              content: "Legacy project memory.",
+              source: { kind: "user" },
+              createdAt: 1,
+              updatedAt: 1,
+            },
+            bugfix: {
+              id: "bugfix",
+              workspaceId,
+              type: "bugfix",
+              content: "Legacy bugfix memory.",
+              source: { kind: "agent" },
+              createdAt: 2,
+              updatedAt: 3,
+            },
+            feature: {
+              id: "feature",
+              workspaceId,
+              type: "feature",
+              content: "Legacy feature memory.",
+              source: { kind: "skill" },
+              createdAt: 3,
+              updatedAt: 2,
+            },
+          },
+        },
+        null,
+        2
+      ) + "\n"
+    );
+
+    expect(
+      repo.list({ workspaceId }).map((entry) => ({
+        id: entry.id,
+        type: entry.type,
+        status: entry.status,
+      }))
+    ).toEqual([
+      { id: "bugfix", type: "issue", status: "not_started" },
+      { id: "feature", type: "wiki", status: undefined },
+      { id: "project", type: "wiki", status: undefined },
+    ]);
+  });
+
+  it("keeps entries with invalid stored statuses during normalization", () => {
+    const workspaceId = "ws-invalid-stored-statuses";
+    const filePath = join(tempDir, "memory", "workspaces", `${workspaceId}.json`);
+    mkdirSync(join(tempDir, "memory", "workspaces"), { recursive: true });
+    writeFileSync(
+      filePath,
+      JSON.stringify(
+        {
+          version: 1,
+          workspaceId,
+          entries: {
+            issue: {
+              id: "issue",
+              workspaceId,
+              type: "issue",
+              status: "open",
+              content: "Discard the invalid actionable status.",
+              source: { kind: "user" },
+              createdAt: 1,
+              updatedAt: 2,
+            },
+            project: {
+              id: "project",
+              workspaceId,
+              type: "project",
+              status: "open",
+              content: "Discard the invalid alias status.",
+              source: { kind: "user" },
+              createdAt: 1,
+              updatedAt: 1,
+            },
+          },
+        },
+        null,
+        2
+      ) + "\n"
+    );
+
+    expect(
+      repo.list({ workspaceId }).map((entry) => ({
+        id: entry.id,
+        type: entry.type,
+        status: entry.status,
+      }))
+    ).toEqual([
+      { id: "issue", type: "issue", status: "not_started" },
+      { id: "project", type: "wiki", status: undefined },
+    ]);
+  });
+
+  it("persists supplied status for actionable entries", () => {
+    const entry = repo.create({
+      workspaceId: "ws-1",
+      type: "issue",
+      status: "in_progress",
+      content: "Fix broken command routing.",
+      source: { kind: "user" },
+    });
+    const filePath = join(tempDir, "memory", "workspaces", "ws-1.json");
+
+    expect(entry.status).toBe("in_progress");
+    expect(JSON.parse(readFileSync(filePath, "utf-8")).entries[entry.id]).toMatchObject({
+      type: "issue",
+      status: "in_progress",
+    });
+  });
+
+  it("defaults missing status for actionable entries", () => {
+    const entry = repo.create({
+      workspaceId: "ws-1",
+      type: "todo",
+      content: "Run focused verification.",
+      source: { kind: "user" },
+    });
+
+    expect(entry.status).toBe("not_started");
+  });
+
+  it("omits status for non-actionable entries even when supplied", () => {
+    const entry = repo.create({
+      workspaceId: "ws-1",
+      type: "wiki",
+      status: "completed",
+      content: "Use pnpm for project scripts.",
+      source: { kind: "user" },
+    });
+
+    expect(entry).not.toHaveProperty("status");
+  });
+
+  it("removes stale status when updating an actionable entry to a non-actionable type", () => {
+    const entry = repo.create({
+      workspaceId: "ws-1",
+      type: "issue",
+      status: "in_progress",
+      content: "Fix stale status.",
+      source: { kind: "user" },
+    });
+    now += 1000;
+
+    const updated = repo.update({
+      workspaceId: "ws-1",
+      id: entry.id,
+      type: "note",
+    });
+
+    expect(updated).toMatchObject({
+      id: entry.id,
+      type: "note",
+      content: "Fix stale status.",
+    });
+    expect(updated).not.toHaveProperty("status");
+  });
+
+  it("defaults or uses supplied status when updating a non-actionable entry to an actionable type", () => {
+    const defaulted = repo.create({
+      workspaceId: "ws-1",
+      type: "note",
+      content: "Track without explicit status.",
+      source: { kind: "user" },
+    });
+    const supplied = repo.create({
+      workspaceId: "ws-1",
+      type: "wiki",
+      content: "Track with explicit status.",
+      source: { kind: "user" },
+    });
+    now += 1000;
+
+    expect(
+      repo.update({
+        workspaceId: "ws-1",
+        id: defaulted.id,
+        type: "issue",
+      }).status
+    ).toBe("not_started");
+    expect(
+      repo.update({
+        workspaceId: "ws-1",
+        id: supplied.id,
+        type: "todo",
+        status: "pending_verification",
+      }).status
+    ).toBe("pending_verification");
+  });
+
+  it("normalizes stored statuses while reading legacy entries", () => {
+    const workspaceId = "ws-legacy-statuses";
+    const filePath = join(tempDir, "memory", "workspaces", `${workspaceId}.json`);
+    mkdirSync(join(tempDir, "memory", "workspaces"), { recursive: true });
+    writeFileSync(
+      filePath,
+      JSON.stringify(
+        {
+          version: 1,
+          workspaceId,
+          entries: {
+            valid: {
+              id: "valid",
+              workspaceId,
+              type: "issue",
+              status: "in_progress",
+              content: "Preserve this status.",
+              source: { kind: "user" },
+              createdAt: 1,
+              updatedAt: 4,
+            },
+            missing: {
+              id: "missing",
+              workspaceId,
+              type: "todo",
+              content: "Default this status.",
+              source: { kind: "user" },
+              createdAt: 1,
+              updatedAt: 3,
+            },
+            stale: {
+              id: "stale",
+              workspaceId,
+              type: "note",
+              status: "completed",
+              content: "Clear this stale status.",
+              source: { kind: "user" },
+              createdAt: 1,
+              updatedAt: 2,
+            },
+          },
+        },
+        null,
+        2
+      ) + "\n"
+    );
+
+    expect(
+      repo.list({ workspaceId }).map((entry) => ({
+        id: entry.id,
+        type: entry.type,
+        status: entry.status,
+      }))
+    ).toEqual([
+      { id: "valid", type: "issue", status: "in_progress" },
+      { id: "missing", type: "todo", status: "not_started" },
+      { id: "stale", type: "note", status: undefined },
+    ]);
+  });
+
   it("removes a workspace memory file", () => {
     repo.create({
       workspaceId: "ws-1",
diff --git a/packages/server/src/storage/repositories/memory-repo.ts b/packages/server/src/storage/repositories/memory-repo.ts
index c3f0b2ef4..df4d714ff 100644
--- a/packages/server/src/storage/repositories/memory-repo.ts
+++ b/packages/server/src/storage/repositories/memory-repo.ts
@@ -5,9 +5,14 @@ import type {
   WorkspaceMemoryEntry,
   WorkspaceMemoryListFilter,
   WorkspaceMemorySourceInput,
+  WorkspaceMemoryStatus,
   WorkspaceMemoryType,
 } from "@coder-studio/core";
-import { resolveWorkspaceMemorySource, validateWorkspaceMemoryInput } from "@coder-studio/core";
+import {
+  normalizeWorkspaceMemoryStatus,
+  resolveWorkspaceMemorySource,
+  validateWorkspaceMemoryInput,
+} from "@coder-studio/core";
 import { readJsonFile, writeJsonFileAtomic } from "./json-file-store.js";
 
 interface MemoryRepoOptions {
@@ -26,6 +31,7 @@ interface MemoryCreateInput {
   workspaceId: string;
   type: WorkspaceMemoryType;
   content: string;
+  status?: WorkspaceMemoryStatus;
   source?: WorkspaceMemorySourceInput;
 }
 
@@ -34,6 +40,7 @@ interface MemoryUpdateInput {
   id: string;
   type?: WorkspaceMemoryType;
   content?: string;
+  status?: WorkspaceMemoryStatus;
   archivedAt?: number;
 }
 
@@ -84,6 +91,7 @@ function normalizeEntry(
   const validated = validateWorkspaceMemoryInput({
     type: entry.type,
     content: entry.content,
+    status: normalizeWorkspaceMemoryStatus(entry.status),
   });
 
   return {
@@ -94,6 +102,7 @@ function normalizeEntry(
         : fallbackWorkspaceId,
     type: validated.type,
     content: validated.content,
+    ...(validated.status ? { status: validated.status } : {}),
     source: resolveWorkspaceMemorySource(isRecord(entry.source) ? entry.source : {}),
     createdAt:
       typeof entry.createdAt === "number" && Number.isFinite(entry.createdAt) ? entry.createdAt : 0,
@@ -160,6 +169,7 @@ export class MemoryRepo {
     const validated = validateWorkspaceMemoryInput({
       type: input.type,
       content: input.content,
+      status: input.status,
     });
     const file = this.readWorkspaceFile(input.workspaceId);
     const timestamp = this.now();
@@ -168,6 +178,7 @@ export class MemoryRepo {
       workspaceId: input.workspaceId,
       type: validated.type,
       content: validated.content,
+      ...(validated.status ? { status: validated.status } : {}),
       source: resolveWorkspaceMemorySource(input.source ?? {}),
       createdAt: timestamp,
       updatedAt: timestamp,
@@ -188,11 +199,14 @@ export class MemoryRepo {
     const validated = validateWorkspaceMemoryInput({
       type: input.type ?? existing.type,
       content: input.content ?? existing.content,
+      status: input.status ?? existing.status,
     });
+    const { status: _status, ...existingWithoutStatus } = existing;
     const updated: WorkspaceMemoryEntry = {
-      ...existing,
+      ...existingWithoutStatus,
       type: validated.type,
       content: validated.content,
+      ...(validated.status ? { status: validated.status } : {}),
       updatedAt: this.now(),
       ...(input.archivedAt !== undefined ? { archivedAt: input.archivedAt } : {}),
     };
diff --git a/packages/server/src/storage/repositories/session-metadata-repo.ts b/packages/server/src/storage/repositories/session-metadata-repo.ts
index 565896cb2..fb0841c99 100644
--- a/packages/server/src/storage/repositories/session-metadata-repo.ts
+++ b/packages/server/src/storage/repositories/session-metadata-repo.ts
@@ -15,13 +15,17 @@ interface SessionMetadataWorkspace {
   path: string;
 }
 
-interface SessionMetadataWorkspaceRepo {
+interface SessionMetadataWorkspaceLookup {
   list(): SessionMetadataWorkspace[];
-  findById(id: string): SessionMetadataWorkspace | undefined;
+  get(workspaceId: string): SessionMetadataWorkspace | undefined;
 }
 
 export interface SessionMetadataRepoOptions {
-  workspaceRepo: SessionMetadataWorkspaceRepo;
+  workspaceLookup?: SessionMetadataWorkspaceLookup;
+  workspaceRepo?: {
+    list(): SessionMetadataWorkspace[];
+    findById(id: string): SessionMetadataWorkspace | undefined;
+  };
 }
 
 interface SessionMetadataLocation {
@@ -81,15 +85,28 @@ function normalizeFileMetadata(value: unknown): Record<string, AgentSessionMetad
 }
 
 export class SessionMetadataRepo {
-  private readonly workspaceRepo: SessionMetadataWorkspaceRepo;
+  private readonly workspaceLookup: SessionMetadataWorkspaceLookup;
 
   constructor(input: SessionMetadataRepoOptions) {
-    this.workspaceRepo = input.workspaceRepo;
+    if (input.workspaceLookup) {
+      this.workspaceLookup = input.workspaceLookup;
+      return;
+    }
+
+    if (input.workspaceRepo) {
+      this.workspaceLookup = {
+        list: () => input.workspaceRepo!.list(),
+        get: (workspaceId: string) => input.workspaceRepo!.findById(workspaceId),
+      };
+      return;
+    }
+
+    throw new Error("SessionMetadataRepo requires workspaceLookup or workspaceRepo");
   }
 
   upsert(metadata: AgentSessionMetadata): AgentSessionMetadata {
     const normalized = normalizeMetadata(metadata);
-    const workspace = this.workspaceRepo.findById(normalized.workspaceId);
+    const workspace = this.workspaceLookup.get(normalized.workspaceId);
     if (!workspace) {
       throw new Error(`Workspace not found for session metadata: ${normalized.workspaceId}`);
     }
@@ -132,7 +149,7 @@ export class SessionMetadataRepo {
   }
 
   private findSessionLocation(sessionId: string): SessionMetadataLocation | undefined {
-    for (const workspace of this.workspaceRepo.list()) {
+    for (const workspace of this.workspaceLookup.list()) {
       const fileMetadata = this.loadWorkspaceFileMetadata(workspace.path);
       if (Object.prototype.hasOwnProperty.call(fileMetadata, sessionId)) {
         return {
diff --git a/packages/server/src/storage/repositories/skill-library-repo.ts b/packages/server/src/storage/repositories/skill-library-repo.ts
index 3fd3a1a7e..158f14202 100644
--- a/packages/server/src/storage/repositories/skill-library-repo.ts
+++ b/packages/server/src/storage/repositories/skill-library-repo.ts
@@ -1,10 +1,24 @@
+import { relative } from "node:path";
 import type { SkillLibraryEntry } from "@coder-studio/core";
-import { scanLocalSkillEntries } from "../../skills/local-skill-scanner.js";
+import { scanDiscoveredSkillEntries } from "../../skills/local-skill-scanner.js";
 import { readJsonFile, writeJsonFileAtomic } from "./json-file-store.js";
 
+type LegacySkillLibrarySource = SkillLibraryEntry["source"] | "local" | "skillhub";
+type LegacySkillLibraryOrigin = SkillLibraryEntry["origin"] | "local" | "skillhub";
+
+type PersistedSkillLibraryEntry = Omit<SkillLibraryEntry, "source" | "origin"> & {
+  source: LegacySkillLibrarySource;
+  origin?: LegacySkillLibraryOrigin;
+};
+
+type ModernPersistedSkillLibraryEntry = Omit<PersistedSkillLibraryEntry, "source" | "origin"> & {
+  source: SkillLibraryEntry["source"];
+  origin?: SkillLibraryEntry["origin"];
+};
+
 interface SkillLibraryFileRecord {
   version: 1;
-  entries?: Record<string, SkillLibraryEntry>;
+  entries?: Record<string, PersistedSkillLibraryEntry>;
 }
 
 function isSkillLibraryFileRecord(value: unknown): value is SkillLibraryFileRecord {
@@ -19,7 +33,28 @@ function isSkillLibraryFileRecord(value: unknown): value is SkillLibraryFileReco
 type SkillLibraryRecord = Record<string, SkillLibraryEntry>;
 
 export class SkillLibraryRepo {
-  constructor(private readonly input: { filePath: string; localSkillRoots?: string[] }) {}
+  constructor(
+    private readonly input: {
+      filePath: string;
+      builtinRoot?: string;
+      managedLibraryRoot?: string;
+      customSkillRoot?: string;
+      externalSkillRoots?: string[];
+      localSkillRoots?: string[];
+    }
+  ) {}
+
+  getCustomSkillRoot(): string {
+    return this.input.customSkillRoot ?? "";
+  }
+
+  getLocalRoots(): string[] {
+    if (this.input.customSkillRoot) {
+      return [this.input.customSkillRoot, ...(this.input.externalSkillRoots ?? [])];
+    }
+
+    return [...(this.input.localSkillRoots ?? [])];
+  }
 
   list(): SkillLibraryEntry[] {
     return Object.values(this.load()).sort(
@@ -33,7 +68,7 @@ export class SkillLibraryRepo {
 
   set(entry: SkillLibraryEntry): SkillLibraryEntry {
     const next = this.loadPersisted();
-    next[entry.slug] = { ...entry };
+    next[entry.slug] = normalizePersistedEntry(entry, this.getCustomSkillRoot());
     this.save(next);
     return next[entry.slug]!;
   }
@@ -46,11 +81,16 @@ export class SkillLibraryRepo {
 
   private load(): SkillLibraryRecord {
     const persisted = this.loadPersisted();
-    const discovered = scanLocalSkillEntries(this.input.localSkillRoots ?? []);
+    const discovered = scanDiscoveredSkillEntries({
+      builtinRoot: this.input.builtinRoot,
+      managedLibraryRoot: this.input.managedLibraryRoot,
+      customRoot: this.input.customSkillRoot,
+      externalRoots: this.input.externalSkillRoots ?? this.input.localSkillRoots ?? [],
+    });
 
     for (const entry of discovered) {
       const existing = persisted[entry.slug];
-      if (!existing || existing.source === "local") {
+      if (!existing || compareEntryPriority(entry, existing) > 0) {
         persisted[entry.slug] = entry;
       }
     }
@@ -59,14 +99,79 @@ export class SkillLibraryRepo {
   }
 
   private loadPersisted(): SkillLibraryRecord {
-    const parsed = readJsonFile<SkillLibraryFileRecord | SkillLibraryRecord>(this.input.filePath);
-    if (isSkillLibraryFileRecord(parsed)) {
-      return { ...(parsed.entries ?? {}) };
+    const parsed = readJsonFile<
+      SkillLibraryFileRecord | Record<string, PersistedSkillLibraryEntry>
+    >(this.input.filePath);
+    const records = isSkillLibraryFileRecord(parsed) ? (parsed.entries ?? {}) : (parsed ?? {});
+    const normalized: SkillLibraryRecord = {};
+
+    for (const [slug, entry] of Object.entries(records)) {
+      normalized[slug] = normalizePersistedEntry(entry, this.getCustomSkillRoot());
     }
-    return parsed ? { ...parsed } : {};
+
+    return normalized;
   }
 
   private save(entries: Record<string, SkillLibraryEntry>): void {
     writeJsonFileAtomic(this.input.filePath, { version: 1, entries });
   }
 }
+
+function normalizePersistedEntry(
+  entry: PersistedSkillLibraryEntry,
+  customRoot: string
+): SkillLibraryEntry {
+  if (entry.source === "skillhub" || entry.origin === "skillhub") {
+    return {
+      ...entry,
+      source: "installed",
+      origin: "skillhub",
+    };
+  }
+
+  const isUnderCustomRoot = isPathInsideRoot(entry.libraryPath, customRoot);
+  const isLegacyLocal = entry.source === "local";
+
+  if (isLegacyLocal || isUnderCustomRoot) {
+    return {
+      ...entry,
+      source: isUnderCustomRoot ? "custom" : "installed",
+      origin: "filesystem",
+    };
+  }
+
+  const modernEntry = entry as ModernPersistedSkillLibraryEntry;
+
+  return modernEntry.source === "installed" && !modernEntry.origin
+    ? {
+        ...modernEntry,
+        origin: "filesystem",
+      }
+    : modernEntry;
+}
+
+function isPathInsideRoot(candidatePath: string, rootPath: string): boolean {
+  if (!rootPath) {
+    return false;
+  }
+
+  const relativePath = relative(rootPath, candidatePath);
+  return relativePath !== "" && !relativePath.startsWith("..") && !relativePath.includes(":/");
+}
+
+function compareEntryPriority(left: SkillLibraryEntry, right: SkillLibraryEntry): number {
+  return priorityOf(left) - priorityOf(right);
+}
+
+function priorityOf(entry: SkillLibraryEntry): number {
+  if (entry.source === "builtin") {
+    return 4;
+  }
+  if (entry.source === "custom") {
+    return 3;
+  }
+  if (entry.source === "installed" && entry.origin === "skillhub") {
+    return 2;
+  }
+  return 1;
+}
diff --git a/packages/server/src/system-deps/install-manager.ts b/packages/server/src/system-deps/install-manager.ts
index ddfbe5702..35251e9a3 100644
--- a/packages/server/src/system-deps/install-manager.ts
+++ b/packages/server/src/system-deps/install-manager.ts
@@ -9,8 +9,8 @@ import type {
 } from "@coder-studio/core";
 import { Topics } from "@coder-studio/core";
 import type { RuntimeStatusDeps } from "../provider-runtime/runtime-status.js";
+import type { RuntimeHostBridge } from "../runtime/contract.js";
 import type { PtyHost, PtyProcess } from "../terminal/types.js";
-import type { Broadcaster } from "../ws/hub.js";
 import { SYSTEM_DEPENDENCY_DEFINITIONS } from "./definitions.js";
 import { detectSystemDependencyInteraction } from "./interaction-detector.js";
 import { buildSystemDependencyRuntimeStatus } from "./runtime-status.js";
@@ -25,7 +25,8 @@ interface InstallSession {
 
 export interface SystemDependencyInstallManagerDeps extends RuntimeStatusDeps {
   ptyHost: PtyHost;
-  broadcaster: Pick<Broadcaster, "sendToClient">;
+  hostBridge?: Pick<RuntimeHostBridge, "sendToClient">;
+  broadcaster?: { sendToClient(clientId: string, payload: unknown): boolean };
 }
 
 interface InFlightStart {
@@ -380,7 +381,7 @@ export class SystemDependencyInstallManager {
 
     session.seq += 1;
     if (session.routeClientId) {
-      this.deps.broadcaster.sendToClient(session.routeClientId, {
+      this.getSendToClient()(session.routeClientId, {
         kind: "event",
         topic: Topics.systemDependencyInstallOutput(jobId),
         seq: session.seq,
@@ -405,6 +406,12 @@ export class SystemDependencyInstallManager {
     }
   }
 
+  private getSendToClient(): (clientId: string, payload: unknown) => boolean {
+    return (
+      this.deps.hostBridge?.sendToClient ?? this.deps.broadcaster?.sendToClient ?? (() => false)
+    );
+  }
+
   private async handleExit(jobId: string, event: PtyExitEvent): Promise<void> {
     const job = this.jobs.get(jobId);
     if (!job) {
diff --git a/packages/server/src/terminal-profiles/__tests__/registry.test.ts b/packages/server/src/terminal-profiles/__tests__/registry.test.ts
new file mode 100644
index 000000000..fccc512e7
--- /dev/null
+++ b/packages/server/src/terminal-profiles/__tests__/registry.test.ts
@@ -0,0 +1,305 @@
+import type { CustomTerminalProfile } from "@coder-studio/core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { detectTerminalProfiles } from "../detect.js";
+import { listTerminalProfiles, resolveTerminalLaunch } from "../registry.js";
+
+const customProfiles: CustomTerminalProfile[] = [
+  {
+    id: "custom:node-shell",
+    label: "Node Shell",
+    command: "node",
+    args: ["--interactive"],
+    icon: "terminal",
+  },
+];
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("detectTerminalProfiles", () => {
+  it("uses ComSpec for cmd detection instead of shellPath on Windows", async () => {
+    vi.stubEnv("ComSpec", "C:\\Windows\\System32\\cmd.exe");
+
+    const profiles = await detectTerminalProfiles({
+      platform: "win32",
+      shellPath: "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
+      commandExists: async (command) => command === "C:\\Windows\\System32\\cmd.exe",
+    });
+
+    expect(profiles).toContainEqual(
+      expect.objectContaining({
+        id: "detected:win:cmd",
+        argv: ["C:\\Windows\\System32\\cmd.exe"],
+      })
+    );
+  });
+
+  it("uses the resolved Git Bash path from PATH on Windows", async () => {
+    vi.stubEnv("ComSpec", "");
+    vi.stubEnv("COMSPEC", "");
+
+    const runCommand = vi.fn(
+      async (file: string, args: string[], _options?: { windowsHide: boolean }) => {
+        if (file === "where" && args[0] === "bash") {
+          return {
+            stdout: "C:\\Program Files\\Git\\bin\\bash.exe\r\n",
+            stderr: "",
+          };
+        }
+
+        throw new Error(`missing: ${file} ${args.join(" ")}`);
+      }
+    );
+
+    const profiles = await detectTerminalProfiles({
+      platform: "win32",
+      runCommand,
+    });
+
+    expect(profiles).toContainEqual(
+      expect.objectContaining({
+        id: "detected:win:git-bash",
+        argv: ["C:\\Program Files\\Git\\bin\\bash.exe"],
+      })
+    );
+  });
+
+  it("does not treat the WSL bash shim as Git Bash on Windows", async () => {
+    vi.stubEnv("ComSpec", "");
+    vi.stubEnv("COMSPEC", "");
+
+    const runCommand = vi.fn(
+      async (file: string, args: string[], _options?: { windowsHide: boolean }) => {
+        if (file === "where" && args[0] === "bash") {
+          return {
+            stdout: "C:\\Windows\\System32\\bash.exe\r\n",
+            stderr: "",
+          };
+        }
+
+        throw new Error(`missing: ${file} ${args.join(" ")}`);
+      }
+    );
+
+    const profiles = await detectTerminalProfiles({
+      platform: "win32",
+      runCommand,
+    });
+
+    expect(profiles.find((profile) => profile.id === "detected:win:git-bash")).toBeUndefined();
+  });
+
+  it("does not treat non-Git bash implementations as Git Bash on Windows", async () => {
+    vi.stubEnv("ComSpec", "");
+    vi.stubEnv("COMSPEC", "");
+
+    const runCommand = vi.fn(
+      async (file: string, args: string[], _options?: { windowsHide: boolean }) => {
+        if (file === "where" && args[0] === "bash") {
+          return {
+            stdout: "C:\\msys64\\usr\\bin\\bash.exe\r\n",
+            stderr: "",
+          };
+        }
+
+        throw new Error(`missing: ${file} ${args.join(" ")}`);
+      }
+    );
+
+    const profiles = await detectTerminalProfiles({
+      platform: "win32",
+      runCommand,
+    });
+
+    expect(profiles.find((profile) => profile.id === "detected:win:git-bash")).toBeUndefined();
+  });
+
+  it("detects Git Bash from known Git for Windows install paths when bash is not on PATH", async () => {
+    vi.stubEnv("ComSpec", "");
+    vi.stubEnv("COMSPEC", "");
+    vi.stubEnv("ProgramFiles", "C:\\Program Files");
+    vi.stubEnv("ProgramFiles(x86)", "C:\\Program Files (x86)");
+    vi.stubEnv("LOCALAPPDATA", "C:\\Users\\spencer\\AppData\\Local");
+
+    const profiles = await detectTerminalProfiles({
+      platform: "win32",
+      commandExists: async () => false,
+      existsSync: (file) => file === "C:\\Program Files\\Git\\bin\\bash.exe",
+    });
+
+    expect(profiles).toContainEqual(
+      expect.objectContaining({
+        id: "detected:win:git-bash",
+        argv: ["C:\\Program Files\\Git\\bin\\bash.exe"],
+      })
+    );
+  });
+
+  it("labels detected WSL distros with a WSL suffix", async () => {
+    vi.stubEnv("ComSpec", "");
+    vi.stubEnv("COMSPEC", "");
+
+    const runCommand = vi.fn(
+      async (file: string, args: string[], _options?: { windowsHide: boolean }) => {
+        if (file === "where" && args[0] === "wsl") {
+          return {
+            stdout: "C:\\Windows\\System32\\wsl.exe\r\n",
+            stderr: "",
+          };
+        }
+
+        if (file === "wsl.exe" && args[0] === "-l" && args[1] === "-q") {
+          return {
+            stdout: "Ubuntu-24.04\r\n",
+            stderr: "",
+          };
+        }
+
+        throw new Error(`missing: ${file} ${args.join(" ")}`);
+      }
+    );
+
+    const profiles = await detectTerminalProfiles({
+      platform: "win32",
+      runCommand,
+    });
+
+    expect(profiles).toContainEqual(
+      expect.objectContaining({
+        id: "detected:win:wsl:Ubuntu-24.04",
+        label: "Ubuntu-24.04 (WSL)",
+        argv: ["wsl.exe", "-d", "Ubuntu-24.04"],
+      })
+    );
+  });
+});
+
+describe("terminal profile registry", () => {
+  it("keeps the configured default id while resolving a fallback available profile", async () => {
+    const result = await listTerminalProfiles({
+      platform: "linux",
+      shellPath: "/bin/zsh",
+      configuredDefaultProfileId: "detected:win:powershell",
+      customProfiles,
+      detectProfiles: async () => [
+        {
+          id: "detected:posix:zsh",
+          label: "zsh",
+          source: "detected",
+          runtime: "native",
+          icon: "terminal",
+          argv: ["/bin/zsh", "-i"],
+          cwdRuntime: "native",
+        },
+      ],
+    });
+
+    expect(result.configuredDefaultProfileId).toBe("detected:win:powershell");
+    expect(result.resolvedDefaultProfileId).toBe("detected:posix:zsh");
+    expect(result.profiles.map((profile) => profile.id)).toEqual([
+      "detected:posix:zsh",
+      "custom:node-shell",
+    ]);
+  });
+
+  it("throws for an explicitly requested unavailable profile instead of silently falling back", async () => {
+    await expect(
+      resolveTerminalLaunch({
+        platform: "linux",
+        shellPath: "/bin/zsh",
+        configuredDefaultProfileId: "detected:posix:zsh",
+        requestedProfileId: "detected:win:pwsh",
+        customProfiles: [],
+        workspacePath: "/repo/app",
+        detectProfiles: async () => [
+          {
+            id: "detected:posix:zsh",
+            label: "zsh",
+            source: "detected",
+            runtime: "native",
+            icon: "terminal",
+            argv: ["/bin/zsh", "-i"],
+            cwdRuntime: "native",
+          },
+        ],
+      })
+    ).rejects.toMatchObject({
+      code: "terminal_profile_unavailable",
+      message: "Terminal profile unavailable: detected:win:pwsh",
+    });
+  });
+
+  it("builds a WSL launch spec with mapped cwd when the workspace is on a Windows drive", async () => {
+    const launch = await resolveTerminalLaunch({
+      platform: "win32",
+      configuredDefaultProfileId: "detected:win:wsl:Ubuntu-24.04",
+      workspacePath: "C:\\repo\\app",
+      customProfiles: [],
+      detectProfiles: async () => [
+        {
+          id: "detected:win:wsl:Ubuntu-24.04",
+          label: "Ubuntu-24.04",
+          source: "detected",
+          runtime: "wsl",
+          icon: "terminal",
+          argv: ["wsl.exe", "-d", "Ubuntu-24.04"],
+          cwdRuntime: "wsl",
+          wslDistro: "Ubuntu-24.04",
+        },
+      ],
+    });
+
+    expect(launch.title).toBe("Ubuntu-24.04 (WSL)");
+    expect(launch.argv).toEqual(["wsl.exe", "-d", "Ubuntu-24.04", "--cd", "/mnt/c/repo/app"]);
+    expect(launch.cwd).toBe("C:\\repo\\app");
+    expect(launch.profileId).toBe("detected:win:wsl:Ubuntu-24.04");
+  });
+
+  it("normalizes WSL profile labels in list results", async () => {
+    const result = await listTerminalProfiles({
+      platform: "win32",
+      configuredDefaultProfileId: "detected:win:wsl:Ubuntu-24.04",
+      customProfiles: [],
+      detectProfiles: async () => [
+        {
+          id: "detected:win:wsl:Ubuntu-24.04",
+          label: "Ubuntu-24.04",
+          source: "detected",
+          runtime: "wsl",
+          icon: "terminal",
+          argv: ["wsl.exe", "-d", "Ubuntu-24.04"],
+          cwdRuntime: "wsl",
+          wslDistro: "Ubuntu-24.04",
+        },
+      ],
+    });
+
+    expect(result.profiles[0]?.label).toBe("Ubuntu-24.04 (WSL)");
+  });
+
+  it("falls back to the distro home when a WSL cwd cannot be mapped", async () => {
+    const launch = await resolveTerminalLaunch({
+      platform: "win32",
+      configuredDefaultProfileId: "detected:win:wsl:Ubuntu-24.04",
+      workspacePath: "\\\\wsl$\\Ubuntu-24.04\\repo\\app",
+      customProfiles: [],
+      detectProfiles: async () => [
+        {
+          id: "detected:win:wsl:Ubuntu-24.04",
+          label: "Ubuntu-24.04",
+          source: "detected",
+          runtime: "wsl",
+          icon: "terminal",
+          argv: ["wsl.exe", "-d", "Ubuntu-24.04"],
+          cwdRuntime: "wsl",
+          wslDistro: "Ubuntu-24.04",
+        },
+      ],
+    });
+
+    expect(launch.title).toBe("Ubuntu-24.04 (WSL)");
+    expect(launch.argv).toEqual(["wsl.exe", "-d", "Ubuntu-24.04"]);
+    expect(launch.cwd).toBe("\\\\wsl$\\Ubuntu-24.04\\repo\\app");
+  });
+});
diff --git a/packages/server/src/terminal-profiles/detect.ts b/packages/server/src/terminal-profiles/detect.ts
new file mode 100644
index 000000000..4a972b5df
--- /dev/null
+++ b/packages/server/src/terminal-profiles/detect.ts
@@ -0,0 +1,272 @@
+import { existsSync as fsExistsSync } from "node:fs";
+import path from "node:path";
+import type { TerminalProfile } from "@coder-studio/core";
+import {
+  type CommandAvailabilityCheck,
+  checkCommandAvailable,
+  getCommandLookupExecutable,
+} from "../provider-runtime/command-check.js";
+import { type CommandRunner, runCommandAsString } from "../provider-runtime/command-runner.js";
+import { formatWslLabel } from "./wsl.js";
+
+export interface DetectedTerminalProfile extends TerminalProfile {
+  source: "detected";
+  argv: string[];
+  cwdRuntime: "native" | "wsl";
+  wslDistro?: string;
+}
+
+export interface DetectTerminalProfilesInput {
+  platform?: NodeJS.Platform;
+  shellPath?: string;
+  commandExists?: CommandAvailabilityCheck;
+  runCommand?: CommandRunner;
+  existsSync?: (file: string) => boolean;
+}
+
+export async function detectTerminalProfiles(
+  input: DetectTerminalProfilesInput = {}
+): Promise<DetectedTerminalProfile[]> {
+  const platform = input.platform ?? process.platform;
+  const commandExists =
+    input.commandExists ??
+    ((command: string) =>
+      checkCommandAvailable(command, {
+        platform,
+        runCommand: input.runCommand,
+        existsSync: input.existsSync,
+      }));
+
+  if (platform === "win32") {
+    return detectWindowsProfiles({ ...input, platform, commandExists });
+  }
+
+  return detectPosixProfiles({ ...input, platform, commandExists });
+}
+
+async function detectWindowsProfiles(
+  input: Required<Pick<DetectTerminalProfilesInput, "platform">> &
+    Pick<DetectTerminalProfilesInput, "runCommand" | "existsSync"> & {
+      commandExists: CommandAvailabilityCheck;
+    }
+): Promise<DetectedTerminalProfile[]> {
+  const profiles: DetectedTerminalProfile[] = [];
+
+  if (await input.commandExists("pwsh")) {
+    profiles.push({
+      id: "detected:win:pwsh",
+      label: "PowerShell",
+      source: "detected",
+      runtime: "native",
+      icon: "terminal",
+      argv: ["pwsh"],
+      cwdRuntime: "native",
+    });
+  }
+
+  if (await input.commandExists("powershell")) {
+    profiles.push({
+      id: "detected:win:powershell",
+      label: "Windows PowerShell",
+      source: "detected",
+      runtime: "native",
+      icon: "terminal",
+      argv: ["powershell"],
+      cwdRuntime: "native",
+    });
+  }
+
+  const cmdPath = firstNonEmpty(process.env.ComSpec, process.env.COMSPEC) ?? "cmd.exe";
+  if (await input.commandExists(cmdPath)) {
+    profiles.push({
+      id: "detected:win:cmd",
+      label: "Command Prompt",
+      source: "detected",
+      runtime: "native",
+      icon: "terminal",
+      argv: [cmdPath],
+      cwdRuntime: "native",
+    });
+  }
+
+  const gitBashPath = await resolveGitBashPath(input);
+  if (gitBashPath) {
+    profiles.push({
+      id: "detected:win:git-bash",
+      label: "Git Bash",
+      source: "detected",
+      runtime: "native",
+      icon: "terminal",
+      argv: [gitBashPath],
+      cwdRuntime: "native",
+    });
+  }
+
+  if (await input.commandExists("wsl")) {
+    const distros = await listWslDistros(input.runCommand);
+    for (const distro of distros) {
+      profiles.push({
+        id: `detected:win:wsl:${distro}`,
+        label: formatWslLabel(distro),
+        source: "detected",
+        runtime: "wsl",
+        icon: "terminal",
+        argv: ["wsl.exe", "-d", distro],
+        cwdRuntime: "wsl",
+        wslDistro: distro,
+      });
+    }
+  }
+
+  return profiles;
+}
+
+async function resolveGitBashPath(
+  input: Pick<DetectTerminalProfilesInput, "platform" | "runCommand" | "existsSync"> & {
+    commandExists: CommandAvailabilityCheck;
+  }
+): Promise<string | null> {
+  const resolvedPath = await resolveWindowsCommandPath("bash", input.runCommand);
+  if (resolvedPath && isGitForWindowsBashPath(resolvedPath)) {
+    return resolvedPath;
+  }
+
+  const installPath = resolveGitBashInstallPath(input.existsSync);
+  if (installPath) {
+    return installPath;
+  }
+
+  return null;
+}
+
+async function detectPosixProfiles(
+  input: Required<Pick<DetectTerminalProfilesInput, "platform">> &
+    Pick<DetectTerminalProfilesInput, "shellPath"> & {
+      commandExists: CommandAvailabilityCheck;
+    }
+): Promise<DetectedTerminalProfile[]> {
+  const profiles: DetectedTerminalProfile[] = [];
+  const seenIds = new Set<string>();
+  const shellPath = input.shellPath ?? process.env.SHELL;
+
+  if (shellPath) {
+    const shellName = basenameForPlatform(shellPath, input.platform);
+    const currentProfile = buildPosixProfile(shellName, shellPath);
+    pushIfUnique(profiles, seenIds, currentProfile);
+  }
+
+  for (const command of ["zsh", "bash", "fish", "pwsh"] as const) {
+    if (!(await input.commandExists(command))) {
+      continue;
+    }
+
+    pushIfUnique(profiles, seenIds, buildPosixProfile(command, command));
+  }
+
+  return profiles;
+}
+
+function buildPosixProfile(shellName: string, command: string): DetectedTerminalProfile {
+  return {
+    id: `detected:posix:${shellName}`,
+    label: shellName,
+    source: "detected",
+    runtime: "native",
+    icon: "terminal",
+    argv: requiresInteractiveFlag(shellName) ? [command, "-i"] : [command],
+    cwdRuntime: "native",
+  };
+}
+
+function basenameForPlatform(filePath: string, platform: NodeJS.Platform): string {
+  return platform === "win32" ? path.win32.basename(filePath) : path.posix.basename(filePath);
+}
+
+function requiresInteractiveFlag(shellName: string): boolean {
+  return shellName !== "pwsh" && shellName !== "powershell" && shellName !== "cmd.exe";
+}
+
+function pushIfUnique(
+  profiles: DetectedTerminalProfile[],
+  seenIds: Set<string>,
+  profile: DetectedTerminalProfile
+): void {
+  if (seenIds.has(profile.id)) {
+    return;
+  }
+
+  seenIds.add(profile.id);
+  profiles.push(profile);
+}
+
+async function listWslDistros(runCommand?: CommandRunner): Promise<string[]> {
+  const runner = runCommand ?? runCommandAsString;
+
+  try {
+    const { stdout } = await runner("wsl.exe", ["-l", "-q"], { windowsHide: true });
+    return stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+async function resolveWindowsCommandPath(
+  command: string,
+  runCommand?: CommandRunner
+): Promise<string | null> {
+  const runner = runCommand ?? runCommandAsString;
+
+  try {
+    const { stdout } = await runner(getCommandLookupExecutable("win32"), [command], {
+      windowsHide: true,
+    });
+    return (
+      stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0) ?? null
+    );
+  } catch {
+    return null;
+  }
+}
+
+function resolveGitBashInstallPath(existsSync?: (file: string) => boolean): string | null {
+  const fileExists = existsSync ?? fsExistsSync;
+  const programFiles = firstNonEmpty(process.env.ProgramFiles);
+  const programFilesX86 = firstNonEmpty(process.env["ProgramFiles(x86)"]);
+  const localAppData = firstNonEmpty(process.env.LOCALAPPDATA);
+  const candidates = [
+    programFiles && path.win32.join(programFiles, "Git", "bin", "bash.exe"),
+    programFiles && path.win32.join(programFiles, "Git", "usr", "bin", "bash.exe"),
+    programFilesX86 && path.win32.join(programFilesX86, "Git", "bin", "bash.exe"),
+    programFilesX86 && path.win32.join(programFilesX86, "Git", "usr", "bin", "bash.exe"),
+    localAppData && path.win32.join(localAppData, "Programs", "Git", "bin", "bash.exe"),
+    localAppData && path.win32.join(localAppData, "Programs", "Git", "usr", "bin", "bash.exe"),
+  ].filter((value): value is string => Boolean(value));
+
+  for (const candidate of candidates) {
+    if (fileExists(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function isGitForWindowsBashPath(filePath: string): boolean {
+  const normalized = path.win32.normalize(filePath).replace(/\//g, "\\").toLowerCase();
+  return (
+    normalized.endsWith("\\git\\bin\\bash.exe") ||
+    normalized.endsWith("\\git\\usr\\bin\\bash.exe") ||
+    normalized.endsWith("\\portablegit\\bin\\bash.exe") ||
+    normalized.endsWith("\\portablegit\\usr\\bin\\bash.exe")
+  );
+}
+
+function firstNonEmpty(...values: Array<string | undefined>): string | null {
+  return values.find((value) => typeof value === "string" && value.length > 0) ?? null;
+}
diff --git a/packages/server/src/terminal-profiles/registry.ts b/packages/server/src/terminal-profiles/registry.ts
new file mode 100644
index 000000000..aa13fa549
--- /dev/null
+++ b/packages/server/src/terminal-profiles/registry.ts
@@ -0,0 +1,164 @@
+import type {
+  CustomTerminalProfile,
+  TerminalProfile,
+  TerminalProfilesListResult,
+} from "@coder-studio/core";
+import { type DetectedTerminalProfile, detectTerminalProfiles } from "./detect.js";
+import { appendWslCwd, formatWslLabel, toWslPath } from "./wsl.js";
+
+export interface ResolvedTerminalLaunch {
+  profileId: string;
+  title: string;
+  argv: string[];
+  cwd: string;
+}
+
+export interface RegistryInput {
+  platform?: NodeJS.Platform;
+  shellPath?: string;
+  configuredDefaultProfileId?: string;
+  customProfiles: CustomTerminalProfile[];
+  workspacePath?: string;
+  detectProfiles?: () => Promise<DetectedTerminalProfile[]>;
+}
+
+export async function listTerminalProfiles(
+  input: RegistryInput
+): Promise<TerminalProfilesListResult> {
+  const state = await loadRegistryState(input);
+
+  return {
+    profiles: state.profiles,
+    configuredDefaultProfileId: input.configuredDefaultProfileId,
+    resolvedDefaultProfileId: state.resolvedDefaultProfileId,
+  };
+}
+
+export async function resolveTerminalLaunch(
+  input: RegistryInput & { requestedProfileId?: string }
+): Promise<ResolvedTerminalLaunch> {
+  if (!input.workspacePath) {
+    throw new Error("workspacePath is required for resolveTerminalLaunch");
+  }
+
+  const state = await loadRegistryState(input);
+  const targetId = input.requestedProfileId ?? state.resolvedDefaultProfileId;
+
+  if (!targetId) {
+    throw {
+      code: "terminal_profile_unavailable",
+      message: "No terminal profiles are available on this machine",
+    };
+  }
+
+  const profile = state.definitions.get(targetId);
+  if (!profile) {
+    throw {
+      code: "terminal_profile_unavailable",
+      message: `Terminal profile unavailable: ${targetId}`,
+    };
+  }
+
+  if (isCustomProfile(profile)) {
+    return {
+      profileId: profile.id,
+      title: profile.label,
+      argv: [profile.command, ...(profile.args ?? [])],
+      cwd: input.workspacePath,
+    };
+  }
+
+  if (profile.cwdRuntime === "wsl") {
+    return {
+      profileId: profile.id,
+      title: getDetectedProfileLabel(profile),
+      argv: appendWslCwd(profile.argv, toWslPath(input.workspacePath)),
+      cwd: input.workspacePath,
+    };
+  }
+
+  return {
+    profileId: profile.id,
+    title: getDetectedProfileLabel(profile),
+    argv: [...profile.argv],
+    cwd: input.workspacePath,
+  };
+}
+
+interface RegistryState {
+  profiles: TerminalProfile[];
+  definitions: Map<string, DetectedTerminalProfile | CustomTerminalProfile>;
+  resolvedDefaultProfileId: string | null;
+}
+
+async function loadRegistryState(input: RegistryInput): Promise<RegistryState> {
+  const detected = await loadDetectedProfiles(input);
+  const profiles: TerminalProfile[] = [
+    ...detected.map(toDto),
+    ...input.customProfiles.map(toCustomDto),
+  ];
+
+  const definitions = new Map<string, DetectedTerminalProfile | CustomTerminalProfile>();
+  for (const profile of detected) {
+    definitions.set(profile.id, profile);
+  }
+  for (const profile of input.customProfiles) {
+    definitions.set(profile.id, profile);
+  }
+
+  const resolvedDefaultProfileId =
+    profiles.find((profile) => profile.id === input.configuredDefaultProfileId)?.id ??
+    profiles[0]?.id ??
+    null;
+
+  return {
+    profiles,
+    definitions,
+    resolvedDefaultProfileId,
+  };
+}
+
+async function loadDetectedProfiles(input: RegistryInput): Promise<DetectedTerminalProfile[]> {
+  if (input.detectProfiles) {
+    return input.detectProfiles();
+  }
+
+  return detectTerminalProfiles({
+    platform: input.platform,
+    shellPath: input.shellPath,
+  });
+}
+
+function toDto(profile: DetectedTerminalProfile): TerminalProfile {
+  return {
+    id: profile.id,
+    label: getDetectedProfileLabel(profile),
+    source: profile.source,
+    runtime: profile.runtime,
+    icon: profile.icon,
+  };
+}
+
+function toCustomDto(profile: CustomTerminalProfile): TerminalProfile {
+  return {
+    id: profile.id,
+    label: profile.label,
+    source: "custom",
+    runtime: "native",
+    icon: profile.icon ?? "terminal",
+  };
+}
+
+function isCustomProfile(
+  profile: DetectedTerminalProfile | CustomTerminalProfile
+): profile is CustomTerminalProfile {
+  return "command" in profile;
+}
+
+function getDetectedProfileLabel(profile: DetectedTerminalProfile): string {
+  if (profile.runtime !== "wsl") {
+    return profile.label;
+  }
+
+  return formatWslLabel(profile.wslDistro ?? profile.label);
+}
diff --git a/packages/server/src/terminal-profiles/wsl.ts b/packages/server/src/terminal-profiles/wsl.ts
new file mode 100644
index 000000000..09537d568
--- /dev/null
+++ b/packages/server/src/terminal-profiles/wsl.ts
@@ -0,0 +1,24 @@
+import path from "node:path";
+
+export function toWslPath(windowsPath: string): string | null {
+  const parsed = path.win32.parse(windowsPath);
+  if (!parsed.root || !/^[A-Za-z]:\\$/.test(parsed.root)) {
+    return null;
+  }
+
+  const drive = parsed.root[0]!.toLowerCase();
+  const relative = windowsPath.slice(parsed.root.length).replace(/\\/g, "/");
+  return `/mnt/${drive}${relative ? `/${relative}` : ""}`;
+}
+
+export function appendWslCwd(argv: string[], mappedCwd: string | null): string[] {
+  if (!mappedCwd) {
+    return [...argv];
+  }
+
+  return [...argv, "--cd", mappedCwd];
+}
+
+export function formatWslLabel(distro: string): string {
+  return distro.endsWith(" (WSL)") ? distro : `${distro} (WSL)`;
+}
diff --git a/packages/server/src/web-ui-routing.ts b/packages/server/src/web-ui-routing.ts
index 0bf2990af..93bbf1aad 100644
--- a/packages/server/src/web-ui-routing.ts
+++ b/packages/server/src/web-ui-routing.ts
@@ -1,13 +1,8 @@
 import type { FastifyRequest } from "fastify";
 
-const RESERVED_PREFIXES = ["/api/", "/auth/", "/internal/", "/assets/"];
+const RESERVED_PREFIXES = ["/api/", "/auth/", "/internal/", "/assets/", "/dev-browser/"];
 const RESERVED_EXACT_PATHS = new Set(["/api", "/auth", "/assets", "/healthz", "/internal", "/ws"]);
-const ROOT_PUBLIC_FILE_PATHS = new Set([
-  "/dev-browser-sw.js",
-  "/favicon.ico",
-  "/index.html",
-  "/task-complete.wav",
-]);
+const ROOT_PUBLIC_FILE_PATHS = new Set(["/favicon.ico", "/index.html", "/task-complete.wav"]);
 
 export function getRequestPathname(url: string): string {
   return url.split("?", 1)[0] || "/";
diff --git a/packages/server/src/workspace/history-store.test.ts b/packages/server/src/workspace/history-store.test.ts
index e28bf0e3d..aca4c4a09 100644
--- a/packages/server/src/workspace/history-store.test.ts
+++ b/packages/server/src/workspace/history-store.test.ts
@@ -75,4 +75,52 @@ describe("WorkspaceHistoryStore", () => {
     });
     expect(history.find((entry) => entry.path === "/repo/kept")).toBeUndefined();
   });
+
+  it("removes a stored history entry by path while preserving the remaining order", () => {
+    store.recordOpen("/repo/alpha", 100);
+    store.recordOpen("/repo/beta", 200);
+    store.recordOpen("/repo/gamma", 300);
+
+    const nextHistory = store.remove("/repo/beta");
+
+    expect(nextHistory).toEqual([
+      {
+        path: "/repo/gamma",
+        name: "gamma",
+        lastOpenedAt: 300,
+      },
+      {
+        path: "/repo/alpha",
+        name: "alpha",
+        lastOpenedAt: 100,
+      },
+    ]);
+    expect(store.list()).toEqual(nextHistory);
+  });
+
+  it("returns the current history unchanged when removing a path that is not present", () => {
+    store.recordOpen("/repo/alpha", 100);
+
+    const nextHistory = store.remove("/repo/missing");
+
+    expect(nextHistory).toEqual([
+      {
+        path: "/repo/alpha",
+        name: "alpha",
+        lastOpenedAt: 100,
+      },
+    ]);
+    expect(store.list()).toEqual(nextHistory);
+  });
+
+  it("clears the stored history and removes the persisted key", () => {
+    store.recordOpen("/repo/alpha", 100);
+    store.recordOpen("/repo/beta", 200);
+
+    const nextHistory = store.clear();
+
+    expect(nextHistory).toEqual([]);
+    expect(store.list()).toEqual([]);
+    expect(settingsRepo.get(WORKSPACE_HISTORY_KEY)).toBeUndefined();
+  });
 });
diff --git a/packages/server/src/workspace/history-store.ts b/packages/server/src/workspace/history-store.ts
index e42e9588b..5a08c323b 100644
--- a/packages/server/src/workspace/history-store.ts
+++ b/packages/server/src/workspace/history-store.ts
@@ -37,6 +37,19 @@ function buildEntry(path: string, lastOpenedAt: number): WorkspaceHistoryEntry {
   };
 }
 
+function persistHistory(
+  settingsRepo: SettingsRepo,
+  history: WorkspaceHistoryEntry[]
+): WorkspaceHistoryEntry[] {
+  if (history.length === 0) {
+    settingsRepo.delete(WORKSPACE_HISTORY_KEY);
+    return [];
+  }
+
+  settingsRepo.set(WORKSPACE_HISTORY_KEY, history);
+  return history;
+}
+
 export class WorkspaceHistoryStore {
   private readonly settingsRepo: SettingsRepo;
 
@@ -54,6 +67,16 @@ export class WorkspaceHistoryStore {
       .sort((left, right) => right.lastOpenedAt - left.lastOpenedAt)
       .slice(0, WORKSPACE_HISTORY_LIMIT);
 
-    this.settingsRepo.set(WORKSPACE_HISTORY_KEY, nextHistory);
+    persistHistory(this.settingsRepo, nextHistory);
+  }
+
+  remove(path: string): WorkspaceHistoryEntry[] {
+    const trimmedPath = path.trim();
+    const nextHistory = this.list().filter((entry) => entry.path !== trimmedPath);
+    return persistHistory(this.settingsRepo, nextHistory);
+  }
+
+  clear(): WorkspaceHistoryEntry[] {
+    return persistHistory(this.settingsRepo, []);
   }
 }
diff --git a/packages/server/src/workspace/manager.ts b/packages/server/src/workspace/manager.ts
index 730ca9f4f..0d0d89f9c 100644
--- a/packages/server/src/workspace/manager.ts
+++ b/packages/server/src/workspace/manager.ts
@@ -9,6 +9,7 @@ import { WorkspaceValidator } from "./validator.js";
 
 export interface OpenWorkspaceRequest {
   path: string;
+  targetRuntime?: Workspace["targetRuntime"];
   wslDistro?: string;
 }
 
@@ -117,6 +118,8 @@ export class WorkspaceManager {
    * @returns Created or existing workspace
    */
   async open(req: OpenWorkspaceRequest): Promise<Workspace> {
+    const targetRuntime = req.targetRuntime ?? "native";
+
     // 1. Validate path
     await this.validator.validate(req.path);
 
@@ -143,8 +146,8 @@ export class WorkspaceManager {
     const workspace: Workspace = {
       id: generateWorkspaceId(),
       path: req.path,
-      targetRuntime: "native",
-      wslDistro: req.wslDistro,
+      targetRuntime,
+      wslDistro: targetRuntime === "wsl" ? req.wslDistro : undefined,
       openedAt: Date.now(),
       lastActiveAt: Date.now(),
       uiState: {
diff --git a/packages/server/src/ws/dispatch.ts b/packages/server/src/ws/dispatch.ts
index 4e41d0ba3..8cad6adc9 100644
--- a/packages/server/src/ws/dispatch.ts
+++ b/packages/server/src/ws/dispatch.ts
@@ -1,22 +1,35 @@
 /**
  * Command Dispatch
  *
- * Routes commands to handlers and validates input
+ * Routes commands to host handlers, runtime handlers, or compatibility
+ * handlers while preserving the existing websocket protocol behavior.
  */
 
-import type { Command, ProviderDefinition, Result } from "@coder-studio/core";
+import type { AutomationPermission, Command, ProviderDefinition, Result } from "@coder-studio/core";
 import { z } from "zod";
 import type { AgentInstructionsPublisher } from "../agent-instructions/publisher.js";
+import type { RequestAuthContext } from "../auth/index.js";
 import type { AutomationAuditLog } from "../automation/audit-log.js";
 import type { EventBus } from "../bus/event-bus.js";
+import type { CanvasService } from "../canvas/service.js";
 import type { ServerConfig } from "../config.js";
 import type { AutoFetchRuntime } from "../git/auto-fetch.js";
+import { getHostCommandDefinition, getRegisteredHostCommands } from "../host/command-registry.js";
+import type { HostCommandContext, HostDispatchMeta } from "../host/context.js";
+import type { RuntimeRouter } from "../host/runtime-router.js";
+import type { WorkspaceRuntimeBindingStore } from "../host/workspace-runtime-binding.js";
 import type { LspManager } from "../lsp/manager.js";
 import type { LspToolInstallManager } from "../lsp-tools/install-manager.js";
 import type { LspToolManager } from "../lsp-tools/manager.js";
 import type { MonitoringService } from "../monitoring/service.js";
 import type { ProviderInstallManager } from "../provider-runtime/install-manager.js";
 import type { RuntimeStatusDeps } from "../provider-runtime/runtime-status.js";
+import {
+  getRegisteredRuntimeCommands,
+  getRuntimeCommandDefinition,
+} from "../runtime/command-registry.js";
+import type { RuntimeCommandContext } from "../runtime/context.js";
+import type { RuntimeExecuteMeta, RuntimeRouteTarget } from "../runtime/contract.js";
 import type { SessionManager } from "../session/manager.js";
 import type { SessionAnalysisService } from "../session-analysis/service.js";
 import type { BuiltinSkillSyncManager } from "../skills/builtin/sync-manager.js";
@@ -44,9 +57,9 @@ import type { FencingManager } from "./fencing.js";
 import type { Broadcaster } from "./hub.js";
 
 /**
- * Command context - injected dependencies for handlers
+ * Command context - injected dependencies for compatibility handlers
  */
-export interface CommandContext {
+export interface CommandContext extends HostCommandContext {
   workspaceMgr: WorkspaceManager;
   sessionMgr: SessionManager;
   terminalMgr: TerminalManager;
@@ -59,10 +72,13 @@ export interface CommandContext {
   fencingMgr: FencingManager;
   supervisorMgr: SupervisorManager;
   autoFetch: AutoFetchRuntime;
+  runtimeRouter: RuntimeRouter;
+  runtimeBindings: WorkspaceRuntimeBindingStore;
   providerRuntimeDeps?: RuntimeStatusDeps;
   providerInstallMgr?: ProviderInstallManager;
   systemDependencyInstallMgr?: SystemDependencyInstallManager;
   agentInstructionPublisher?: AgentInstructionsPublisher;
+  canvasService?: CanvasService;
   activationMgr: ActivationManager;
   config?: Pick<ServerConfig, "auth" | "host">;
   lspMgr: LspManager;
@@ -89,7 +105,7 @@ export interface CommandContext {
 }
 
 /**
- * Command handler type
+ * Command handler type for compatibility-registered handlers.
  */
 export type CommandHandler<A = unknown, R = unknown> = (
   args: A,
@@ -99,15 +115,141 @@ export type CommandHandler<A = unknown, R = unknown> = (
 
 type CommandSchema = z.ZodTypeAny;
 
-/**
- * Registry of all command handlers
- */
-const handlers = new Map<string, CommandHandler>();
+const compatibilityHandlers = new Map<string, CommandHandler>();
+const compatibilitySchemas = new Map<string, CommandSchema>();
+
+const NOOP_EVENT_BUS: Pick<EventBus, "emit" | "on"> = {
+  emit: () => {},
+  on: () => () => {},
+};
+
+const NOOP_PROVIDER_CONFIG_REPO: Pick<
+  ProviderConfigRepo,
+  "get" | "set" | "delete" | "listProviderIds" | "getAll"
+> = {
+  get: () => undefined,
+  set: () => {},
+  delete: () => {},
+  listProviderIds: () => [],
+  getAll: () => ({}),
+};
+
+export function createInlineRuntimeContext(ctx: HostCommandContext): RuntimeCommandContext {
+  const candidate = ctx as Partial<CommandContext>;
+  const eventBus = candidate.eventBus ?? NOOP_EVENT_BUS;
+  const broadcaster = candidate.broadcaster;
+
+  return {
+    runtimeId: "native-default",
+    workspaceLookup: {
+      get: (workspaceId: string) => candidate.workspaceMgr?.get?.(workspaceId) as never,
+      list: () => candidate.workspaceMgr?.list?.().slice() ?? [],
+    },
+    hostBridge: {
+      issueSessionToken: () => ({ token: "" }),
+      revokeSessionTokensBySessionId: () => {},
+      getHostApiUrl: () => undefined,
+      emitDomainEvent: (event) => eventBus.emit(event),
+      broadcast: (topic, payload) => {
+        if (typeof broadcaster?.broadcast === "function") {
+          broadcaster.broadcast(topic, payload);
+        }
+      },
+      recordWorkspaceFetch: (workspaceId) => candidate.workspaceMgr?.recordFetch?.(workspaceId),
+      sendToClient: (clientId, payload) =>
+        typeof broadcaster?.sendToClient === "function"
+          ? broadcaster.sendToClient(clientId as never, payload as never)
+          : false,
+      sendBinaryToClient: (clientId, payload) =>
+        typeof broadcaster?.sendBinaryToClient === "function"
+          ? broadcaster.sendBinaryToClient(clientId as never, payload)
+          : false,
+    },
+    eventBus: eventBus as EventBus,
+    providerConfigRepo: (candidate.providerConfigRepo ??
+      NOOP_PROVIDER_CONFIG_REPO) as ProviderConfigRepo,
+    providerRegistry: candidate.providerRegistry ?? [],
+    sessionMgr: candidate.sessionMgr as SessionManager,
+    terminalMgr: candidate.terminalMgr as TerminalManager,
+    taskMgr: candidate.taskMgr as TaskManager,
+    lspMgr: candidate.lspMgr as LspManager,
+    lspToolMgr: candidate.lspToolMgr,
+    lspToolInstallMgr: candidate.lspToolInstallMgr,
+    supervisorMgr: candidate.supervisorMgr as SupervisorManager,
+    providerRuntimeDeps: candidate.providerRuntimeDeps,
+    providerInstallMgr: candidate.providerInstallMgr,
+    systemDependencyInstallMgr: candidate.systemDependencyInstallMgr,
+    skillsHubClient: candidate.skillsHubClient,
+    skillInstallMgr: candidate.skillInstallMgr,
+    skillMountMgr: candidate.skillMountMgr,
+    skillHealthMgr: candidate.skillHealthMgr,
+    skillLibraryRepo: candidate.skillLibraryRepo,
+    skillTargetRepo: candidate.skillTargetRepo,
+    skillMountRepo: candidate.skillMountRepo,
+    builtinSkillSyncMgr: candidate.builtinSkillSyncMgr,
+    sessionMetadataRepo: candidate.sessionMetadataRepo,
+    sessionAnalysisService: candidate.sessionAnalysisService,
+    workAnalysisService: candidate.workAnalysisService,
+    agentInstructionPublisher: candidate.agentInstructionPublisher,
+  };
+}
+
+function shouldFallbackRuntimeRouting(error: unknown, target: RuntimeRouteTarget): boolean {
+  const code =
+    typeof error === "object" && error !== null && "code" in error
+      ? (error as { code?: unknown }).code
+      : undefined;
+
+  return (
+    code === "runtime_not_bound" ||
+    code === "runtime_not_found" ||
+    (code === "workspace_not_found" && target.kind !== "workspace")
+  );
+}
+
+export async function executeRuntimeCommandOnTarget(
+  op: string,
+  args: unknown,
+  ctx: HostCommandContext,
+  meta?: RuntimeExecuteMeta,
+  targetOverride?: RuntimeRouteTarget
+): Promise<unknown> {
+  const definition = getRuntimeCommandDefinition(op);
+  if (!definition) {
+    throw {
+      code: "unknown_op",
+      message: `Unknown operation: ${op}`,
+    };
+  }
+
+  const parsedArgs = definition.schema.parse(args);
+  const target = targetOverride ?? definition.resolveTarget(parsedArgs);
+  const inlineRuntimeContext = createInlineRuntimeContext(ctx);
+
+  if (typeof ctx.runtimeRouter?.executeOnTarget === "function") {
+    try {
+      return await ctx.runtimeRouter.executeOnTarget(target, op, parsedArgs, meta);
+    } catch (error) {
+      if (!shouldFallbackRuntimeRouting(error, target)) {
+        throw error;
+      }
+    }
+  }
+
+  if (inlineRuntimeContext) {
+    return definition.handler(parsedArgs, inlineRuntimeContext, meta);
+  }
+
+  if (compatibilityHandlers.has(op)) {
+    return executeCompatibilityCommand(op, parsedArgs, ctx as CommandContext, meta?.clientId);
+  }
+
+  throw {
+    code: "runtime_router_unavailable",
+    message: `Runtime router is unavailable for operation: ${op}`,
+  };
+}
 
-/**
- * Registry of all command schemas
- */
-const schemas = new Map<string, CommandSchema>();
 const ACTIVATION_ALLOWLIST = new Set([
   "activation.claim",
   "activation.release",
@@ -123,30 +265,303 @@ const ACTIVATION_ALLOWLIST = new Set([
   "workspace.list",
 ]);
 
+const SESSION_TOKEN_ALLOWLIST = new Set([
+  "automation.capabilities",
+  "automation.identify",
+  "canvas.create",
+  "canvas.list",
+  "canvas.render",
+  "canvas.update",
+  "connection.probe",
+  "git.diff",
+  "git.status",
+  "memory.create",
+  "memory.delete",
+  "memory.get",
+  "memory.list",
+  "memory.search",
+  "memory.update",
+  "session.list",
+  "terminal.read",
+  "uiAction.capabilities",
+  "uiAction.dispatch",
+]);
+
+type SessionTokenAuthContext = Extract<RequestAuthContext, { mode: "session_token" }>;
+
+function createPermissionDeniedError(message: string): Result["error"] {
+  return {
+    code: "permission_denied",
+    message,
+  };
+}
+
+export function getRequestAuthContext(
+  ctx: Pick<HostCommandContext, "broadcaster">,
+  clientId?: string
+): RequestAuthContext | undefined {
+  if (!clientId || typeof ctx.broadcaster.getRequestMetadata !== "function") {
+    return undefined;
+  }
+
+  return ctx.broadcaster.getRequestMetadata(clientId)?.coderStudioAuthContext;
+}
+
+export function getSessionTokenRequestAuthContext(
+  ctx: Pick<HostCommandContext, "broadcaster">,
+  clientId?: string
+): SessionTokenAuthContext | undefined {
+  const authContext = getRequestAuthContext(ctx, clientId);
+  return authContext?.mode === "session_token" ? authContext : undefined;
+}
+
+function getUiActionPermission(args: unknown): AutomationPermission | undefined {
+  if (!args || typeof args !== "object" || !("intent" in args)) {
+    return undefined;
+  }
+
+  const intent = (args as { intent?: { type?: unknown } }).intent;
+  if (!intent || typeof intent !== "object") {
+    return undefined;
+  }
+
+  return intent.type === "command.run" ? "ui:command" : "ui:navigate";
+}
+
+function getSessionTokenPermission(msg: Command): AutomationPermission | null | undefined {
+  switch (msg.op) {
+    case "automation.capabilities":
+    case "automation.identify":
+    case "connection.probe":
+    case "uiAction.capabilities":
+      return null;
+    case "session.list":
+      return "session:read";
+    case "terminal.read":
+      return "terminal:read";
+    case "git.status":
+    case "git.diff":
+      return "git:read";
+    case "memory.list":
+    case "memory.search":
+    case "memory.get":
+      return "memory:read";
+    case "memory.create":
+    case "memory.update":
+    case "memory.delete":
+      return "memory:write";
+    case "canvas.list":
+    case "canvas.render":
+      return "memory:read";
+    case "canvas.create":
+    case "canvas.update":
+      return "memory:write";
+    case "uiAction.dispatch":
+      return getUiActionPermission(msg.args);
+    default:
+      return undefined;
+  }
+}
+
+function getWorkspaceIdArg(args: unknown): string | undefined {
+  if (!args || typeof args !== "object") {
+    return undefined;
+  }
+
+  return typeof (args as { workspaceId?: unknown }).workspaceId === "string"
+    ? (args as { workspaceId: string }).workspaceId
+    : undefined;
+}
+
+function getUiIntentWorkspaceId(args: unknown): string | undefined {
+  if (!args || typeof args !== "object") {
+    return undefined;
+  }
+
+  const intent = (args as { intent?: { workspaceId?: unknown } }).intent;
+  return typeof intent?.workspaceId === "string" ? intent.workspaceId : undefined;
+}
+
+function getReferencedWorkspaceIds(args: unknown): string[] {
+  const workspaceIds = [getWorkspaceIdArg(args), getUiIntentWorkspaceId(args)].filter(
+    (workspaceId): workspaceId is string => typeof workspaceId === "string"
+  );
+
+  return [...new Set(workspaceIds)];
+}
+
+function validateSessionTokenScope(
+  msg: Command,
+  authContext: SessionTokenAuthContext,
+  ctx: Pick<HostCommandContext, "runtimeBindings">
+): Result["error"] | null {
+  switch (msg.op) {
+    case "session.list":
+    case "git.status":
+    case "git.diff":
+    case "memory.list":
+    case "memory.search":
+    case "memory.get":
+    case "memory.create":
+    case "memory.update":
+    case "memory.delete":
+    case "canvas.list":
+    case "canvas.create":
+    case "canvas.update":
+    case "canvas.render": {
+      const workspaceId = getWorkspaceIdArg(msg.args);
+      if (workspaceId && workspaceId !== authContext.workspaceId) {
+        return createPermissionDeniedError("Token is not authorized for the requested workspace");
+      }
+      return null;
+    }
+    case "terminal.read": {
+      if (!msg.args || typeof msg.args !== "object") {
+        return null;
+      }
+
+      const terminalId = (msg.args as { terminalId?: unknown }).terminalId;
+      if (typeof terminalId !== "string") {
+        return null;
+      }
+
+      const sessionId =
+        ctx.runtimeBindings?.findSessionIdByTerminalId(terminalId) ??
+        (ctx as Partial<CommandContext>).sessionMgr?.findSessionIdByTerminal?.(terminalId);
+      if (sessionId && sessionId !== authContext.sessionId) {
+        return createPermissionDeniedError("Token is not authorized for the requested session");
+      }
+      return null;
+    }
+    case "uiAction.dispatch": {
+      const workspaceIds = getReferencedWorkspaceIds(msg.args);
+      if (workspaceIds.some((workspaceId) => workspaceId !== authContext.workspaceId)) {
+        return createPermissionDeniedError("Token is not authorized for the requested workspace");
+      }
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+function authorizeSessionTokenCommand(
+  msg: Command,
+  authContext: SessionTokenAuthContext,
+  ctx: Pick<HostCommandContext, "runtimeBindings">
+): Result["error"] | null {
+  if (!SESSION_TOKEN_ALLOWLIST.has(msg.op)) {
+    return createPermissionDeniedError("Token is not authorized for this command");
+  }
+
+  const requiredPermission = getSessionTokenPermission(msg);
+  if (requiredPermission === undefined) {
+    return createPermissionDeniedError("Token is not authorized for this command");
+  }
+
+  if (requiredPermission !== null && !authContext.permissions.includes(requiredPermission)) {
+    return createPermissionDeniedError("Token is not authorized for this command");
+  }
+
+  return validateSessionTokenScope(msg, authContext, ctx);
+}
+
+async function executeCompatibilityCommand(
+  op: string,
+  args: unknown,
+  ctx: CommandContext,
+  clientId?: string
+): Promise<unknown> {
+  const handler = compatibilityHandlers.get(op);
+  if (!handler) {
+    throw {
+      code: "unknown_op",
+      message: `Unknown operation: ${op}`,
+    };
+  }
+
+  const schema = compatibilitySchemas.get(op);
+  const parsedArgs = schema ? schema.parse(args) : args;
+  return handler(parsedArgs, ctx, clientId);
+}
+
 /**
- * Register a command handler
+ * Register a compatibility command handler.
  */
 export function registerCommand<S extends CommandSchema, R>(
   op: string,
   schema: S,
   handler: CommandHandler<z.output<S>, R>
 ): void {
-  handlers.set(op, handler as CommandHandler);
-  schemas.set(op, schema);
+  compatibilityHandlers.set(op, handler as CommandHandler);
+  compatibilitySchemas.set(op, schema);
+}
+
+export async function executeHostCommand(
+  op: string,
+  args: unknown,
+  ctx: HostCommandContext,
+  meta?: HostDispatchMeta
+): Promise<unknown> {
+  const definition = getHostCommandDefinition(op);
+  if (definition) {
+    const parsedArgs = definition.schema.parse(args);
+    return definition.handler(parsedArgs, ctx, meta);
+  }
+
+  if (compatibilityHandlers.has(op)) {
+    return executeCompatibilityCommand(op, args, ctx as CommandContext, meta?.clientId);
+  }
+
+  throw {
+    code: "unknown_op",
+    message: `Unknown operation: ${op}`,
+  };
+}
+
+export async function executeRuntimeCommand(
+  op: string,
+  args: unknown,
+  ctx: RuntimeCommandContext,
+  meta?: RuntimeExecuteMeta
+): Promise<unknown> {
+  const definition = getRuntimeCommandDefinition(op);
+  if (!definition) {
+    throw {
+      code: "unknown_op",
+      message: `Unknown operation: ${op}`,
+    };
+  }
+
+  const parsedArgs = definition.schema.parse(args);
+  return definition.handler(parsedArgs, ctx, meta);
 }
 
 /**
- * Dispatch a command to its handler
+ * Dispatch a command to its host or runtime target.
  */
 export async function dispatch(
   msg: Command,
-  ctx: CommandContext,
+  ctx: HostCommandContext,
   clientId?: string
 ): Promise<Result> {
   const isWsDispatch =
     clientId !== undefined && typeof ctx.broadcaster.getRequestMetadata === "function";
+  const authContext = isWsDispatch ? getSessionTokenRequestAuthContext(ctx, clientId) : undefined;
 
-  if (isWsDispatch && !ACTIVATION_ALLOWLIST.has(msg.op)) {
+  if (authContext) {
+    const authorizationError = authorizeSessionTokenCommand(msg, authContext, ctx);
+    if (authorizationError) {
+      return {
+        kind: "result",
+        id: msg.id,
+        ok: false,
+        error: authorizationError,
+      };
+    }
+  }
+
+  if (isWsDispatch && !authContext && !ACTIVATION_ALLOWLIST.has(msg.op)) {
     const active = ctx.activationMgr.getLease();
     if (!active || active.wsClientId !== clientId) {
       return {
@@ -161,29 +576,33 @@ export async function dispatch(
     }
   }
 
-  const handler = handlers.get(msg.op);
-
-  if (!handler) {
-    return {
-      kind: "result",
-      id: msg.id,
-      ok: false,
-      error: {
-        code: "unknown_op",
-        message: `Unknown operation: ${msg.op}`,
-      },
-    };
-  }
-
   try {
-    const schema = schemas.get(msg.op);
-    let args = msg.args;
+    const runtimeDefinition = getRuntimeCommandDefinition(msg.op, { includeInternal: false });
+    if (runtimeDefinition) {
+      const parsedArgs = runtimeDefinition.schema.parse(msg.args);
+      const data = await executeRuntimeCommandOnTarget(
+        msg.op,
+        parsedArgs,
+        ctx,
+        {
+          clientId,
+          authContext,
+        },
+        runtimeDefinition.resolveTarget(parsedArgs)
+      );
 
-    if (schema) {
-      args = schema.parse(msg.args);
+      return {
+        kind: "result",
+        id: msg.id,
+        ok: true,
+        data,
+      };
     }
 
-    const data = await handler(args, ctx, clientId);
+    const data = await executeHostCommand(msg.op, msg.args, ctx, {
+      clientId,
+      authContext,
+    });
 
     return {
       kind: "result",
@@ -192,19 +611,17 @@ export async function dispatch(
       data,
     };
   } catch (error: unknown) {
-    const normalizedError = normalizeError(error);
-
     return {
       kind: "result",
       id: msg.id,
       ok: false,
-      error: normalizedError,
+      error: normalizeError(error),
     };
   }
 }
 
 /**
- * Normalize error to protocol format
+ * Normalize error to protocol format.
  */
 function normalizeError(error: unknown): Result["error"] {
   const candidate = error as {
@@ -238,8 +655,15 @@ function normalizeError(error: unknown): Result["error"] {
 }
 
 /**
- * Get all registered commands
+ * Get all registered commands, including compatibility and explicit host/runtime
+ * registrations.
  */
 export function getRegisteredCommands(): string[] {
-  return Array.from(handlers.keys());
+  return Array.from(
+    new Set([
+      ...compatibilityHandlers.keys(),
+      ...getRegisteredHostCommands(),
+      ...getRegisteredRuntimeCommands(),
+    ])
+  );
 }
diff --git a/packages/server/src/ws/hub.ts b/packages/server/src/ws/hub.ts
index c2c652d5f..aed65638d 100644
--- a/packages/server/src/ws/hub.ts
+++ b/packages/server/src/ws/hub.ts
@@ -22,14 +22,15 @@ import type WebSocket from "ws";
 import { EventBus } from "../bus/event-bus.js";
 import { clearPendingTerminalInput, registerPendingTerminalInput } from "../commands/terminal.js";
 import type { ServerConfig } from "../config.js";
+import type { HostCommandContext } from "../host/context.js";
 import { ClientId, WsClient } from "./client.js";
-import { type CommandContext, dispatch } from "./dispatch.js";
+import { dispatch } from "./dispatch.js";
 import type { FencingManager } from "./fencing.js";
 import { isStreamTopic } from "./topic-class.js";
 
 interface WsHubDeps {
   eventBus: EventBus;
-  commandContext: CommandContext | null;
+  commandContext: HostCommandContext | null;
   config: ServerConfig;
   fencingMgr: FencingManager;
   logger?: FastifyBaseLogger;
@@ -84,7 +85,7 @@ export class WsHub implements Broadcaster {
     this.deps.logger = logger;
   }
 
-  setCommandContext(commandContext: CommandContext): void {
+  setCommandContext(commandContext: HostCommandContext): void {
     this.deps.commandContext = commandContext;
   }
 
@@ -250,7 +251,7 @@ export class WsHub implements Broadcaster {
         client.sendEvent(workspaceTopic, workspace);
       }
 
-      const sessions = commandContext.sessionMgr.getForWorkspace(workspace.id);
+      const sessions = commandContext.sessionMgr?.getForWorkspace(workspace.id) ?? [];
       for (const session of sessions) {
         const sessionTopic = Topics.sessionState(workspace.id, session.id);
         if (!client.subscribesTo(sessionTopic)) {
@@ -273,7 +274,7 @@ export class WsHub implements Broadcaster {
     this.clients.delete(client.id);
     this.clientRequests.delete(client.id);
     this.discardPendingBinaryWaiters(client.id);
-    this.deps.commandContext?.autoFetch.unregisterViewer(client.id);
+    this.deps.commandContext?.autoFetch?.unregisterViewer(client.id);
     this.deps.commandContext?.activationMgr.onSocketClosed(client.id);
 
     // Release fencing tokens held by this client
@@ -555,7 +556,7 @@ export class WsHub implements Broadcaster {
     return id;
   }
 
-  private getCommandContext(): CommandContext {
+  private getCommandContext(): HostCommandContext {
     if (!this.deps.commandContext) {
       throw new Error("WebSocket command context has not been initialized");
     }
diff --git a/packages/server/src/ws/index.ts b/packages/server/src/ws/index.ts
index 47124431e..122172252 100644
--- a/packages/server/src/ws/index.ts
+++ b/packages/server/src/ws/index.ts
@@ -2,6 +2,28 @@
  * WebSocket module exports
  */
 
+export {
+  clearHostCommandsForTest,
+  getHostCommandDefinition,
+  getRegisteredHostCommands,
+  registerHostCommand,
+} from "../host/command-registry.js";
+export {
+  clearRuntimeCommandsForTest,
+  getRegisteredRuntimeCommands,
+  getRuntimeCommandDefinition,
+  registerRuntimeCommand,
+} from "../runtime/command-registry.js";
 export { type ClientId, type CloseHandler, type MessageHandler, WsClient } from "./client.js";
-export { type CommandContext, type CommandHandler, dispatch, registerCommand } from "./dispatch.js";
+export {
+  type CommandContext,
+  type CommandHandler,
+  dispatch,
+  executeHostCommand,
+  executeRuntimeCommand,
+  getRegisteredCommands,
+  getRequestAuthContext,
+  getSessionTokenRequestAuthContext,
+  registerCommand,
+} from "./dispatch.js";
 export { type Broadcaster, WsHub } from "./hub.js";
diff --git a/packages/utils/package.json b/packages/utils/package.json
index 9e07ce8dd..f8298415b 100644
--- a/packages/utils/package.json
+++ b/packages/utils/package.json
@@ -9,6 +9,10 @@
       "types": "./src/index.ts",
       "default": "./src/index.ts"
     },
+    "./markdown-mermaid": {
+      "types": "./src/markdown-mermaid.ts",
+      "default": "./src/markdown-mermaid.ts"
+    },
     "./token-metric": {
       "types": "./src/token-metric.ts",
       "default": "./src/token-metric.ts"
@@ -22,6 +26,10 @@
         "types": "./dist/index.d.ts",
         "import": "./dist/index.js"
       },
+      "./markdown-mermaid": {
+        "types": "./dist/markdown-mermaid.d.ts",
+        "import": "./dist/markdown-mermaid.js"
+      },
       "./token-metric": {
         "types": "./dist/token-metric.d.ts",
         "import": "./dist/token-metric.js"
diff --git a/packages/utils/src/index.ts b/packages/utils/src/index.ts
index fb35ee86c..27a5b2a3f 100644
--- a/packages/utils/src/index.ts
+++ b/packages/utils/src/index.ts
@@ -6,6 +6,7 @@ export {
   shouldDeliverPromptViaStdin,
   WINDOWS_COMMAND_LINE_LIMIT,
 } from "./headless-prompt-delivery.js";
+export { markdownUsesMermaid } from "./markdown-mermaid.js";
 export { formatTokenMetric } from "./token-metric.js";
 export { shouldUseShellForCommand } from "./windows-shim.js";
 export type {
diff --git a/packages/utils/src/markdown-mermaid.test.ts b/packages/utils/src/markdown-mermaid.test.ts
new file mode 100644
index 000000000..d5fb9fa81
--- /dev/null
+++ b/packages/utils/src/markdown-mermaid.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+
+import * as utils from "./index.js";
+
+describe("markdownUsesMermaid", () => {
+  it("detects mermaid fenced code blocks and ignores other markdown", () => {
+    const markdownUsesMermaid = (utils as Record<string, unknown>).markdownUsesMermaid;
+
+    expect(typeof markdownUsesMermaid).toBe("function");
+    if (typeof markdownUsesMermaid !== "function") {
+      return;
+    }
+
+    expect(markdownUsesMermaid("```mermaid\ngraph TD\nA --> B\n```")).toBe(true);
+    expect(markdownUsesMermaid("~~~mermaid\ngraph TD\nA --> B\n~~~")).toBe(true);
+    expect(markdownUsesMermaid("```ts\nconst diagram = 'mermaid';\n```")).toBe(false);
+    expect(markdownUsesMermaid("# README\n\nNo diagrams here.")).toBe(false);
+  });
+});
diff --git a/packages/utils/src/markdown-mermaid.ts b/packages/utils/src/markdown-mermaid.ts
new file mode 100644
index 000000000..a81724486
--- /dev/null
+++ b/packages/utils/src/markdown-mermaid.ts
@@ -0,0 +1,5 @@
+const MERMAID_FENCE_PATTERN = /^[ \t]{0,3}(?:`{3,}|~{3,})[ \t]*mermaid(?:[ \t].*)?$/m;
+
+export function markdownUsesMermaid(markdown: string): boolean {
+  return MERMAID_FENCE_PATTERN.test(markdown);
+}
diff --git a/packages/web/package.json b/packages/web/package.json
index 0f68e77d2..da0add261 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -24,6 +24,7 @@
     "jotai": "^2.19.1",
     "jotai-family": "^1.0.1",
     "lucide-react": "^1.14.0",
+    "markdown-it": "^14.1.0",
     "monaco-editor": "^0.55.1",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
@@ -38,6 +39,7 @@
     "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@types/markdown-it": "^14.1.2",
     "@vitejs/plugin-react": "^6.0.1",
     "jsdom": "^29.1.1",
     "typescript": "^6.0.3",
diff --git a/packages/web/public/dev-browser-sw.js b/packages/web/public/dev-browser-sw.js
deleted file mode 100644
index d49f2d350..000000000
--- a/packages/web/public/dev-browser-sw.js
+++ /dev/null
@@ -1,141 +0,0 @@
-const SESSION_MESSAGE_TYPE = "coder-studio-dev-browser-session";
-const sessions = new Map();
-const clientSessions = new Map();
-
-function getSessionIdFromProxyPath(pathname) {
-  const match = /^\/dev-browser\/session\/([^/]+)\/proxy(?:\/|$)/.exec(pathname);
-  return match ? decodeURIComponent(match[1]) : null;
-}
-
-function getSessionForRequest(input) {
-  if (input.clientSessionId && input.sessions[input.clientSessionId]) {
-    return input.sessions[input.clientSessionId];
-  }
-
-  const requestUrl = new URL(input.requestUrl);
-  const fromRequest = getSessionIdFromProxyPath(requestUrl.pathname);
-  if (fromRequest && input.sessions[fromRequest]) {
-    return input.sessions[fromRequest];
-  }
-
-  if (input.referrer) {
-    const referrerUrl = new URL(input.referrer);
-    const fromReferrer = getSessionIdFromProxyPath(referrerUrl.pathname);
-    if (fromReferrer && input.sessions[fromReferrer]) {
-      return input.sessions[fromReferrer];
-    }
-  }
-
-  return null;
-}
-
-function isLoopbackUrlForSession(url, session) {
-  if (url.protocol !== "http:") {
-    return false;
-  }
-
-  const target = new URL(session.targetOrigin);
-  return (
-    url.port === target.port &&
-    (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]")
-  );
-}
-
-function getPortForUrl(url) {
-  if (url.port) {
-    return url.port;
-  }
-  return url.protocol === "https:" ? "443" : "80";
-}
-
-function isCoderStudioPlatformPath(pathname) {
-  return (
-    pathname === "/api" ||
-    pathname.startsWith("/api/") ||
-    pathname === "/auth" ||
-    pathname.startsWith("/auth/") ||
-    pathname === "/healthz" ||
-    pathname === "/internal" ||
-    pathname.startsWith("/internal/") ||
-    pathname === "/ws"
-  );
-}
-
-function mapRequestToProxy(input) {
-  const requestUrl = new URL(input.requestUrl);
-  const session = getSessionForRequest(input);
-  if (!session) {
-    return null;
-  }
-
-  if (requestUrl.pathname.startsWith(session.browserProxyBase)) {
-    return null;
-  }
-
-  if (requestUrl.origin === self.location.origin) {
-    const currentPort = getPortForUrl(new URL(self.location.origin));
-    const targetPort = getPortForUrl(new URL(session.targetOrigin));
-    if (requestUrl.pathname.startsWith("/dev-browser/")) {
-      return null;
-    }
-    if (
-      requestUrl.pathname !== "/ws" &&
-      (currentPort === targetPort || session.preserveStudioPlatformPaths === true) &&
-      isCoderStudioPlatformPath(requestUrl.pathname)
-    ) {
-      return null;
-    }
-    return `${self.location.origin}${session.browserProxyBase}${requestUrl.pathname}${requestUrl.search}`;
-  }
-
-  if (isLoopbackUrlForSession(requestUrl, session)) {
-    return `${self.location.origin}${session.browserProxyBase}${requestUrl.pathname}${requestUrl.search}`;
-  }
-
-  return null;
-}
-
-self.addEventListener("install", () => {
-  self.skipWaiting();
-});
-
-self.addEventListener("activate", (event) => {
-  event.waitUntil(self.clients.claim());
-});
-
-self.addEventListener("message", (event) => {
-  if (event.data?.type !== SESSION_MESSAGE_TYPE || !event.data.session?.id) {
-    return;
-  }
-
-  sessions.set(event.data.session.id, event.data.session);
-  if (event.source?.id) {
-    clientSessions.set(event.source.id, event.data.session.id);
-  }
-});
-
-self.addEventListener("fetch", (event) => {
-  const clientSessionId = event.clientId ? clientSessions.get(event.clientId) : undefined;
-  const mappedUrl = mapRequestToProxy({
-    requestUrl: event.request.url,
-    referrer: event.request.referrer,
-    clientSessionId,
-    sessions: Object.fromEntries(sessions.entries()),
-  });
-
-  if (!mappedUrl) {
-    return;
-  }
-
-  if (event.request.mode === "navigate") {
-    event.respondWith(Response.redirect(mappedUrl, 302));
-    return;
-  }
-
-  const proxiedRequest = new Request(mappedUrl, event.request);
-  event.respondWith(fetch(proxiedRequest));
-});
-
-self.__coderStudioDevBrowserSwTest = {
-  mapRequest: mapRequestToProxy,
-};
diff --git a/packages/web/src/app.test.tsx b/packages/web/src/app.test.tsx
index 162e29a08..583fb2ca2 100644
--- a/packages/web/src/app.test.tsx
+++ b/packages/web/src/app.test.tsx
@@ -13,6 +13,10 @@ vi.mock("./shells/mobile-shell", () => ({
   MobileShell: () => <div data-testid="mobile-shell">MobileShell</div>,
 }));
 
+vi.mock("./features/canvas/routes/embedded-canvas-route", () => ({
+  EmbeddedCanvasRoute: () => <div data-testid="embedded-canvas-route">EmbeddedCanvasRoute</div>,
+}));
+
 function setMatchMediaMock(predicate: (query: string) => boolean) {
   const matchMedia = vi.fn((query: string) => ({
     addEventListener: vi.fn(),
@@ -85,4 +89,27 @@ describe("App shell selection", () => {
     expect(screen.getByTestId("mobile-shell")).toBeInTheDocument();
     expect(screen.queryByTestId("desktop-shell")).not.toBeInTheDocument();
   });
+
+  it("renders the embedded canvas route outside the app shells", () => {
+    setMatchMediaMock(() => false);
+    window.history.replaceState(
+      {},
+      "",
+      "/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc"
+    );
+    const store = createStore();
+    store.set(connectionStatusAtom, "connected");
+    store.set(authEnabledAtom, false);
+    store.set(authenticatedAtom, true);
+
+    render(
+      <Provider store={store}>
+        <App />
+      </Provider>
+    );
+
+    expect(screen.getByTestId("embedded-canvas-route")).toBeInTheDocument();
+    expect(screen.queryByTestId("desktop-shell")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("mobile-shell")).not.toBeInTheDocument();
+  });
 });
diff --git a/packages/web/src/app.tsx b/packages/web/src/app.tsx
index 88f326842..e74fef502 100644
--- a/packages/web/src/app.tsx
+++ b/packages/web/src/app.tsx
@@ -6,7 +6,8 @@
  * - desktop -> DesktopShell
  */
 
-import { BrowserRouter } from "react-router-dom";
+import { BrowserRouter, Route, Routes } from "react-router-dom";
+import { EmbeddedCanvasRoute } from "./features/canvas/routes/embedded-canvas-route";
 import { useViewport } from "./hooks/use-viewport";
 import { DesktopShell } from "./shells/desktop-shell";
 import { MobileShell } from "./shells/mobile-shell";
@@ -20,7 +21,10 @@ function ShellSwitch() {
 function App() {
   return (
     <BrowserRouter>
-      <ShellSwitch />
+      <Routes>
+        <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+        <Route path="*" element={<ShellSwitch />} />
+      </Routes>
     </BrowserRouter>
   );
 }
diff --git a/packages/web/src/app/providers.lifecycle.test.tsx b/packages/web/src/app/providers.lifecycle.test.tsx
index 1940b9141..fe10ba238 100644
--- a/packages/web/src/app/providers.lifecycle.test.tsx
+++ b/packages/web/src/app/providers.lifecycle.test.tsx
@@ -938,6 +938,20 @@ describe("AppProviders lifecycle recovery", () => {
     });
   });
 
+  it("falls back to auth disabled when /auth/status cannot be reached", async () => {
+    globalThis.fetch = vi
+      .fn()
+      .mockRejectedValue(new Error("ECONNREFUSED")) as unknown as typeof fetch;
+
+    const store = createStore();
+    renderProviders(store);
+
+    await vi.waitFor(() => {
+      expect(store.get(authEnabledAtom)).toBe(false);
+      expect(store.get(authenticatedAtom)).toBe(false);
+    });
+  });
+
   it("does not connect or recover the websocket before login when auth is required", async () => {
     globalThis.fetch = vi.fn().mockResolvedValue({
       json: async () => ({ authEnabled: true, authenticated: false }),
diff --git a/packages/web/src/app/providers.test.tsx b/packages/web/src/app/providers.test.tsx
index de2d44dff..ecdeb47eb 100644
--- a/packages/web/src/app/providers.test.tsx
+++ b/packages/web/src/app/providers.test.tsx
@@ -1,7 +1,7 @@
 import type { Supervisor, UpdateStateView } from "@coder-studio/core";
 import { createStore } from "jotai";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { isWriterAtom, serverInfoAtom, sessionsAtom } from "../atoms";
+import { isWriterAtom, serverInfoAtom, sessionsAtom, workspacesAtom } from "../atoms";
 import {
   activeWorkspaceAtom,
   activeWorkspaceIdAtom,
@@ -242,6 +242,39 @@ describe("routeEventToAtom", () => {
     expect(store.get(activeFilePathAtomFamily("ws-1"))).toBe("src/current.ts");
   });
 
+  it("preserves editor pinned state when a workspace meta patch only updates part of ui state", () => {
+    const store = createStore();
+
+    routeEventToAtom(
+      "workspace.ws-1.meta",
+      {
+        path: "/tmp/ws-1",
+        targetRuntime: "native",
+        uiState: {
+          leftPanelWidth: 280,
+          bottomPanelHeight: 200,
+          focusMode: false,
+          editorPinned: false,
+          activeEditorPath: "src/initial.ts",
+        },
+      },
+      store
+    );
+
+    routeEventToAtom(
+      "workspace.ws-1.meta",
+      {
+        uiState: {
+          activeEditorPath: "src/next.ts",
+        },
+      },
+      store
+    );
+
+    expect(store.get(activeFilePathAtomFamily("ws-1"))).toBe("src/next.ts");
+    expect(store.get(workspacesAtom)["ws-1"]?.uiState.editorPinned).toBe(false);
+  });
+
   it("marks the file tree stale when an fs.dirty event arrives", () => {
     const store = createStore();
 
diff --git a/packages/web/src/app/providers.tsx b/packages/web/src/app/providers.tsx
index 3076358ab..70d3f09e1 100644
--- a/packages/web/src/app/providers.tsx
+++ b/packages/web/src/app/providers.tsx
@@ -663,6 +663,7 @@ export function AppProviders({ children }: AppProvidersProps) {
         setAuthEnabled(Boolean(data.authEnabled));
         store.set(authenticatedAtom, Boolean(data.authenticated) || data.authEnabled === false);
       } catch {
+        setAuthEnabled(false);
         store.set(authenticatedAtom, false);
       }
     };
@@ -1314,10 +1315,16 @@ export function routeEventToAtom(topic: string, payload: unknown, store: Store):
         return;
       }
 
+      const normalizedUiState = patch.uiState
+        ? normalizeWorkspaceEditorUiState({
+            ...(existing?.uiState ?? {}),
+            ...patch.uiState,
+          } as Workspace["uiState"])
+        : undefined;
       const normalizedPatch: Partial<Workspace> = patch.uiState
         ? {
             ...patch,
-            uiState: normalizeWorkspaceEditorUiState(patch.uiState),
+            uiState: normalizedUiState,
           }
         : patch;
 
diff --git a/packages/web/src/features/agent-panes/views/shared/draft-launcher.test.tsx b/packages/web/src/features/agent-panes/views/shared/draft-launcher.test.tsx
index ede312059..399c053c0 100644
--- a/packages/web/src/features/agent-panes/views/shared/draft-launcher.test.tsx
+++ b/packages/web/src/features/agent-panes/views/shared/draft-launcher.test.tsx
@@ -4,6 +4,7 @@ import { createStore, Provider } from "jotai";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { localeAtom } from "../../../../atoms/app-ui";
 import { wsClientAtom } from "../../../../atoms/connection";
+import { SKILL_PATH_DRAG_MIME } from "../../../../lib/skill-path-drag";
 import { WORKSPACE_PATH_DRAG_MIME } from "../../../../lib/workspace-path-drag";
 import { DraftLauncher } from "./draft-launcher";
 
@@ -207,12 +208,73 @@ describe("DraftLauncher", () => {
     expect(within(geminiCard as HTMLElement).getByText("GE")).toBeInTheDocument();
     expect(within(cursorCard as HTMLElement).getByText("CU")).toBeInTheDocument();
     expect(within(opencodeCard as HTMLElement).getByText("OP")).toBeInTheDocument();
+    expect(
+      within(claudeCard as HTMLElement)
+        .getByText("CL")
+        .closest(".agent-provider-card-monogram--claude")
+    ).not.toBeNull();
+    expect(
+      within(codexCard as HTMLElement)
+        .getByText("CO")
+        .closest(".agent-provider-card-monogram--codex")
+    ).not.toBeNull();
+    expect(
+      within(geminiCard as HTMLElement)
+        .getByText("GE")
+        .closest(".agent-provider-card-monogram--gemini")
+    ).not.toBeNull();
+    expect(
+      within(cursorCard as HTMLElement)
+        .getByText("CU")
+        .closest(".agent-provider-card-monogram--cursor")
+    ).not.toBeNull();
+    expect(
+      within(opencodeCard as HTMLElement)
+        .getByText("OP")
+        .closest(".agent-provider-card-monogram--opencode")
+    ).not.toBeNull();
     expect(screen.queryByText("Limited Support")).not.toBeInTheDocument();
     expect(screen.queryByText("Experimental")).not.toBeInTheDocument();
     expect(screen.queryByText("Supervisor evaluation")).not.toBeInTheDocument();
     expect(screen.queryByText("Interactive session")).not.toBeInTheDocument();
   });
 
+  it("uses fallback tone classes for unknown provider monograms", () => {
+    const store = createDraftLauncherStore();
+
+    mockUseProviderLauncher.mockReturnValue({
+      providers: [
+        ...createProviderLauncherValue().providers,
+        createProvider({ id: "mistral", displayName: "Mistral Agent", badge: "Mistral" }),
+      ],
+      states: {
+        ...createProviderLauncherValue().states,
+        mistral: createRuntimeState("mistral"),
+      },
+      launch: vi.fn(),
+    });
+
+    const { container } = render(
+      <Provider store={store}>
+        <DraftLauncher workspaceId="ws-123" />
+      </Provider>
+    );
+
+    const mistralCard = container.querySelector(".agent-provider-card-mistral");
+
+    expect(mistralCard).not.toBeNull();
+    expect(within(mistralCard as HTMLElement).getByText("MI")).toBeInTheDocument();
+
+    const mistralMonogram = within(mistralCard as HTMLElement)
+      .getByText("MI")
+      .closest(".agent-provider-card-monogram--mistral");
+
+    expect(mistralMonogram).not.toBeNull();
+    expect(mistralMonogram?.className).toMatch(
+      /agent-provider-card-monogram--tone-(accent|info|success|warning)/
+    );
+  });
+
   it("renders provider rows as single-line labels with a dedicated CTA column", () => {
     const store = createDraftLauncherStore();
     const { container } = render(
@@ -485,4 +547,116 @@ describe("DraftLauncher", () => {
     expect(dragOver.defaultPrevented).toBe(true);
     expect(await screen.findByText("Open in editor")).toBeInTheDocument();
   });
+
+  it("opens dropped skill files in an editor pane target", async () => {
+    const store = createDraftLauncherStore();
+    const onOpenFile = vi.fn();
+
+    const { container } = render(
+      <Provider store={store}>
+        <DraftLauncher workspaceId="ws-123" paneId="pane-1" onOpenFile={onOpenFile} />
+      </Provider>
+    );
+
+    const root = container.querySelector('[data-pane-id="pane-1"]') as HTMLElement;
+    const payload = {
+      skillSlug: "my-review-skill",
+      path: "refs/guide.md",
+      absolutePath: "/root/.agents/skills/my-review-skill/refs/guide.md",
+      kind: "file" as const,
+    };
+
+    const dataTransfer = {
+      files: [],
+      types: [SKILL_PATH_DRAG_MIME, "text/plain"],
+      items: [],
+      getData: (type: string) =>
+        type === SKILL_PATH_DRAG_MIME ? JSON.stringify(payload) : payload.absolutePath,
+    };
+    const dragOver = createEvent.dragOver(root, { dataTransfer });
+    fireEvent(root, dragOver);
+
+    expect(dragOver.defaultPrevented).toBe(true);
+    expect(await screen.findByText("Open in editor")).toBeInTheDocument();
+
+    const drop = createEvent.drop(root, { dataTransfer });
+    fireEvent(root, drop);
+
+    expect(drop.defaultPrevented).toBe(true);
+    expect(onOpenFile).toHaveBeenCalledWith("pane-1", "skill:my-review-skill/refs/guide.md");
+  });
+
+  it("allows drag-over for skill file drags even when payload data is not readable until drop", async () => {
+    const store = createDraftLauncherStore();
+
+    const { container } = render(
+      <Provider store={store}>
+        <DraftLauncher workspaceId="ws-123" paneId="pane-1" onOpenFile={vi.fn()} />
+      </Provider>
+    );
+
+    const root = container.querySelector('[data-pane-id="pane-1"]') as HTMLElement;
+
+    fireEvent(
+      window,
+      new CustomEvent("coder-studio:skill-path-drag-start", {
+        detail: {
+          skillSlug: "my-review-skill",
+          path: "refs/guide.md",
+          absolutePath: "/root/.agents/skills/my-review-skill/refs/guide.md",
+          kind: "file",
+        },
+      })
+    );
+
+    const dataTransfer = {
+      files: [],
+      types: [SKILL_PATH_DRAG_MIME, "text/plain"],
+      items: [],
+      getData: () => "",
+    };
+    const dragOver = createEvent.dragOver(root, { dataTransfer });
+    fireEvent(root, dragOver);
+
+    expect(dragOver.defaultPrevented).toBe(true);
+    expect(await screen.findByText("Open in editor")).toBeInTheDocument();
+  });
+
+  it("ignores dropped skill directories for editor pane targets", async () => {
+    const store = createDraftLauncherStore();
+    const onOpenFile = vi.fn();
+
+    const { container } = render(
+      <Provider store={store}>
+        <DraftLauncher workspaceId="ws-123" paneId="pane-1" onOpenFile={onOpenFile} />
+      </Provider>
+    );
+
+    const root = container.querySelector('[data-pane-id="pane-1"]') as HTMLElement;
+    const payload = {
+      skillSlug: "my-review-skill",
+      path: "refs",
+      absolutePath: "/root/.agents/skills/my-review-skill/refs",
+      kind: "dir" as const,
+    };
+
+    const dataTransfer = {
+      files: [],
+      types: [SKILL_PATH_DRAG_MIME, "text/plain"],
+      items: [],
+      getData: (type: string) =>
+        type === SKILL_PATH_DRAG_MIME ? JSON.stringify(payload) : payload.absolutePath,
+    };
+    const dragOver = createEvent.dragOver(root, { dataTransfer });
+    fireEvent(root, dragOver);
+
+    expect(dragOver.defaultPrevented).toBe(true);
+    expect(screen.queryByText("Open in editor")).toBeNull();
+
+    const drop = createEvent.drop(root, { dataTransfer });
+    fireEvent(root, drop);
+
+    expect(drop.defaultPrevented).toBe(true);
+    expect(onOpenFile).not.toHaveBeenCalled();
+  });
 });
diff --git a/packages/web/src/features/agent-panes/views/shared/draft-launcher.tsx b/packages/web/src/features/agent-panes/views/shared/draft-launcher.tsx
index 60335c7d6..1e296b2dc 100644
--- a/packages/web/src/features/agent-panes/views/shared/draft-launcher.tsx
+++ b/packages/web/src/features/agent-panes/views/shared/draft-launcher.tsx
@@ -1,11 +1,20 @@
 import type { Session } from "@coder-studio/core";
 import { useAtomValue, useSetAtom } from "jotai";
 import { FlipHorizontal, FlipVertical, GripVertical, X } from "lucide-react";
-import { type DragEvent, type FC, useRef, useState } from "react";
+import { type DragEvent, type FC, useEffect, useRef, useState } from "react";
 import { dispatchCommandAtom } from "../../../../atoms/connection";
 import { sessionsAtom } from "../../../../atoms/sessions";
 import { Button, IconButton, StatusDot, Tag, Tooltip } from "../../../../components/ui";
 import { useTranslation } from "../../../../lib/i18n";
+import {
+  getSkillPathDragPayload,
+  hasSkillPathDragType,
+  isSkillPathDragPayload,
+  SKILL_PATH_DRAG_END_EVENT,
+  SKILL_PATH_DRAG_START_EVENT,
+  type SkillPathDragPayload,
+  toSkillDragEditorPath,
+} from "../../../../lib/skill-path-drag";
 import {
   getWorkspacePathDragPayload,
   hasWorkspacePathDragType,
@@ -35,6 +44,9 @@ interface DraftLauncherProps {
   onSplitPane?: (paneId: string, direction: "horizontal" | "vertical") => void;
 }
 
+const knownProviderMonogramClasses = new Set(["claude", "codex", "gemini", "cursor", "opencode"]);
+const fallbackProviderTones = ["accent", "info", "success", "warning"] as const;
+
 export const DraftLauncher: FC<DraftLauncherProps> = ({
   dragState,
   workspaceId,
@@ -51,6 +63,9 @@ export const DraftLauncher: FC<DraftLauncherProps> = ({
   const dispatch = useAtomValue(dispatchCommandAtom);
   const setSessions = useSetAtom(sessionsAtom);
   const [isFileDropTarget, setIsFileDropTarget] = useState(false);
+  const [skillPathDragPayload, setSkillPathDragPayload] = useState<SkillPathDragPayload | null>(
+    null
+  );
   const draftLauncherRef = useRef<HTMLDivElement | null>(null);
   const supportsPaneDrag = usePaneDragEnabled();
   const canDragPane = supportsPaneDrag && Boolean(paneId && onPaneDragStart);
@@ -76,9 +91,26 @@ export const DraftLauncher: FC<DraftLauncherProps> = ({
     }
   );
 
-  const renderProviderIcon = (title: string) => {
+  const getProviderFallbackToneClass = (providerId: string) => {
+    if (knownProviderMonogramClasses.has(providerId)) {
+      return "";
+    }
+
+    const toneIndex =
+      Array.from(providerId).reduce((sum, char) => sum + char.charCodeAt(0), 0) %
+      fallbackProviderTones.length;
+
+    return `agent-provider-card-monogram--tone-${fallbackProviderTones[toneIndex]}`;
+  };
+
+  const renderProviderIcon = (title: string, providerId: string) => {
+    const fallbackToneClass = getProviderFallbackToneClass(providerId);
+
     return (
-      <span aria-hidden="true" className="agent-provider-card-monogram">
+      <span
+        aria-hidden="true"
+        className={`agent-provider-card-monogram agent-provider-card-monogram--${providerId}${fallbackToneClass ? ` ${fallbackToneClass}` : ""}`}
+      >
         {title.slice(0, 2).toUpperCase()}
       </span>
     );
@@ -187,21 +219,61 @@ export const DraftLauncher: FC<DraftLauncherProps> = ({
       return null;
     }
 
-    const payload = getWorkspacePathDragPayload(event.dataTransfer);
-    if (!payload || payload.workspaceId !== workspaceId || payload.kind !== "file") {
-      return null;
+    const workspacePayload = getWorkspacePathDragPayload(event.dataTransfer);
+    if (workspacePayload) {
+      if (workspacePayload.workspaceId !== workspaceId || workspacePayload.kind !== "file") {
+        return null;
+      }
+
+      return workspacePayload.path;
     }
 
-    return payload.path;
+    const skillPayload = getSkillPathDragPayload(event.dataTransfer) ?? skillPathDragPayload;
+    return skillPayload?.kind === "file" ? toSkillDragEditorPath(skillPayload) : null;
   };
 
+  useEffect(() => {
+    const handleSkillPathDragStart = (event: Event) => {
+      const payload = event instanceof CustomEvent ? event.detail : null;
+      setSkillPathDragPayload(isSkillPathDragPayload(payload) ? payload : null);
+    };
+    const handleSkillPathDragEnd = () => {
+      setSkillPathDragPayload(null);
+      setIsFileDropTarget(false);
+    };
+
+    window.addEventListener(SKILL_PATH_DRAG_START_EVENT, handleSkillPathDragStart);
+    window.addEventListener(SKILL_PATH_DRAG_END_EVENT, handleSkillPathDragEnd);
+    return () => {
+      window.removeEventListener(SKILL_PATH_DRAG_START_EVENT, handleSkillPathDragStart);
+      window.removeEventListener(SKILL_PATH_DRAG_END_EVENT, handleSkillPathDragEnd);
+    };
+  }, []);
+
   const handleDragOver = (event: DragEvent<HTMLDivElement>) => {
-    if (!paneId || !hasWorkspacePathDragType(event.dataTransfer)) {
+    if (!paneId) {
+      return;
+    }
+
+    const hasWorkspacePath = hasWorkspacePathDragType(event.dataTransfer);
+    const hasSkillPath = hasSkillPathDragType(event.dataTransfer);
+    if (!hasWorkspacePath && !hasSkillPath) {
       return;
     }
 
     event.preventDefault();
-    setIsFileDropTarget(true);
+
+    if (hasWorkspacePath) {
+      setIsFileDropTarget(true);
+      return;
+    }
+
+    if (resolveDroppedFilePath(event)) {
+      setIsFileDropTarget(true);
+      return;
+    }
+
+    setIsFileDropTarget(false);
   };
 
   const handleDragLeave = () => {
@@ -210,12 +282,12 @@ export const DraftLauncher: FC<DraftLauncherProps> = ({
 
   const handleDrop = (event: DragEvent<HTMLDivElement>) => {
     const path = resolveDroppedFilePath(event);
+    event.preventDefault();
     setIsFileDropTarget(false);
     if (!path || !paneId) {
       return;
     }
 
-    event.preventDefault();
     onOpenFile?.(paneId, path);
   };
 
@@ -348,7 +420,7 @@ export const DraftLauncher: FC<DraftLauncherProps> = ({
                         disabled={isAnyProviderBusy}
                         leadingIcon={
                           <span className="agent-provider-card-icon">
-                            {renderProviderIcon(title)}
+                            {renderProviderIcon(title, provider.id)}
                           </span>
                         }
                         onClick={() => {
diff --git a/packages/web/src/features/agent-panes/views/shared/editor-pane-card.test.tsx b/packages/web/src/features/agent-panes/views/shared/editor-pane-card.test.tsx
index 6c3840d77..764af90d4 100644
--- a/packages/web/src/features/agent-panes/views/shared/editor-pane-card.test.tsx
+++ b/packages/web/src/features/agent-panes/views/shared/editor-pane-card.test.tsx
@@ -2,6 +2,7 @@ import { act, fireEvent, render, screen, within } from "@testing-library/react";
 import { createStore, Provider } from "jotai";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { localeAtom } from "../../../../atoms/app-ui";
+import { setSkillPathDragData } from "../../../../lib/skill-path-drag";
 import { setWorkspacePathDragData } from "../../../../lib/workspace-path-drag";
 import { type OpenFile, openFilesAtomFamily } from "../../../workspace/atoms";
 import {
@@ -64,6 +65,80 @@ function createWorkspaceFileDataTransfer(workspaceId: string, path: string) {
   return dataTransfer;
 }
 
+function createWorkspaceDirDataTransfer(workspaceId: string, path: string) {
+  const values = new Map<string, string>();
+  const types: string[] = [];
+  const dataTransfer: Pick<DataTransfer, "effectAllowed" | "getData" | "setData" | "types"> = {
+    types,
+    effectAllowed: "uninitialized" as DataTransfer["effectAllowed"],
+    setData: vi.fn((type: string, value: string) => {
+      if (!types.includes(type)) {
+        types.push(type);
+      }
+      values.set(type, value);
+    }),
+    getData: vi.fn((type: string) => values.get(type) ?? ""),
+  };
+
+  setWorkspacePathDragData(dataTransfer, {
+    workspaceId,
+    path,
+    kind: "dir",
+  });
+
+  return dataTransfer;
+}
+
+function createSkillFileDataTransfer(skillSlug: string, path: string, absolutePath: string) {
+  const values = new Map<string, string>();
+  const types: string[] = [];
+  const dataTransfer: Pick<DataTransfer, "effectAllowed" | "getData" | "setData" | "types"> = {
+    types,
+    effectAllowed: "uninitialized" as DataTransfer["effectAllowed"],
+    setData: vi.fn((type: string, value: string) => {
+      if (!types.includes(type)) {
+        types.push(type);
+      }
+      values.set(type, value);
+    }),
+    getData: vi.fn((type: string) => values.get(type) ?? ""),
+  };
+
+  setSkillPathDragData(dataTransfer, {
+    skillSlug,
+    path,
+    absolutePath,
+    kind: "file",
+  });
+
+  return dataTransfer;
+}
+
+function createSkillDirDataTransfer(skillSlug: string, path: string, absolutePath: string) {
+  const values = new Map<string, string>();
+  const types: string[] = [];
+  const dataTransfer: Pick<DataTransfer, "effectAllowed" | "getData" | "setData" | "types"> = {
+    types,
+    effectAllowed: "uninitialized" as DataTransfer["effectAllowed"],
+    setData: vi.fn((type: string, value: string) => {
+      if (!types.includes(type)) {
+        types.push(type);
+      }
+      values.set(type, value);
+    }),
+    getData: vi.fn((type: string) => values.get(type) ?? ""),
+  };
+
+  setSkillPathDragData(dataTransfer, {
+    skillSlug,
+    path,
+    absolutePath,
+    kind: "dir",
+  });
+
+  return dataTransfer;
+}
+
 describe("EditorPaneCard", () => {
   afterEach(() => {
     vi.clearAllMocks();
@@ -222,6 +297,245 @@ describe("EditorPaneCard", () => {
     expect(document.querySelector(".editor-pane-card__file-drop-overlay")).toBeNull();
   });
 
+  it("opens dropped skill files in the editor pane", () => {
+    const store = createStore();
+    const onClosePane = vi.fn();
+    const onSplitPane = vi.fn();
+    const onOpenFile = vi.fn();
+
+    mocks.mockUseCodeEditorActions.mockReturnValue(mocks.editorState);
+    store.set(localeAtom, "en");
+    store.set(
+      editorPaneActiveFilePathAtomFamily(getEditorPaneStateKey("ws-123", "pane-1")),
+      "src/app.tsx"
+    );
+
+    render(
+      <Provider store={store}>
+        <EditorPaneCard
+          workspaceId="ws-123"
+          paneId="pane-1"
+          onClosePane={onClosePane}
+          onOpenFile={onOpenFile}
+          onSplitPane={onSplitPane}
+        />
+      </Provider>
+    );
+
+    const editorPane = screen.getByTestId("editor-pane-pane-1");
+    const dragOver = new Event("dragover", { bubbles: true, cancelable: true });
+    Object.defineProperty(dragOver, "dataTransfer", {
+      value: createSkillFileDataTransfer(
+        "my-review-skill",
+        "refs/guide.md",
+        "/root/.agents/skills/my-review-skill/refs/guide.md"
+      ),
+    });
+
+    fireEvent(editorPane, dragOver);
+
+    expect(dragOver.defaultPrevented).toBe(true);
+    expect(screen.getByText("Open in editor")).toBeInTheDocument();
+
+    const drop = new Event("drop", { bubbles: true, cancelable: true });
+    Object.defineProperty(drop, "dataTransfer", {
+      value: createSkillFileDataTransfer(
+        "my-review-skill",
+        "refs/guide.md",
+        "/root/.agents/skills/my-review-skill/refs/guide.md"
+      ),
+    });
+
+    fireEvent(editorPane, drop);
+
+    expect(drop.defaultPrevented).toBe(true);
+    expect(onOpenFile).toHaveBeenCalledWith("pane-1", "skill:my-review-skill/refs/guide.md");
+  });
+
+  it("swallows dropped workspace directories without leaking text into the editor", () => {
+    const store = createStore();
+    const onClosePane = vi.fn();
+    const onSplitPane = vi.fn();
+    const onOpenFile = vi.fn();
+    const parentDrop = vi.fn();
+
+    mocks.mockUseCodeEditorActions.mockReturnValue(mocks.editorState);
+    store.set(localeAtom, "en");
+    store.set(
+      editorPaneActiveFilePathAtomFamily(getEditorPaneStateKey("ws-123", "pane-1")),
+      "src/app.tsx"
+    );
+
+    render(
+      <Provider store={store}>
+        <div onDrop={parentDrop}>
+          <EditorPaneCard
+            workspaceId="ws-123"
+            paneId="pane-1"
+            onClosePane={onClosePane}
+            onOpenFile={onOpenFile}
+            onSplitPane={onSplitPane}
+          />
+        </div>
+      </Provider>
+    );
+
+    const editorPane = screen.getByTestId("editor-pane-pane-1");
+    const dragOver = new Event("dragover", { bubbles: true, cancelable: true });
+    Object.defineProperty(dragOver, "dataTransfer", {
+      value: createWorkspaceDirDataTransfer("ws-123", "src"),
+    });
+
+    fireEvent(editorPane, dragOver);
+
+    expect(dragOver.defaultPrevented).toBe(true);
+    expect(screen.queryByText("Open in editor")).toBeNull();
+
+    const drop = new Event("drop", { bubbles: true, cancelable: true });
+    Object.defineProperty(drop, "dataTransfer", {
+      value: createWorkspaceDirDataTransfer("ws-123", "src"),
+    });
+
+    fireEvent(editorPane, drop);
+
+    expect(drop.defaultPrevented).toBe(true);
+    expect(parentDrop).not.toHaveBeenCalled();
+    expect(onOpenFile).not.toHaveBeenCalled();
+  });
+
+  it("swallows dropped skill directories without leaking text into the editor", () => {
+    const store = createStore();
+    const onClosePane = vi.fn();
+    const onSplitPane = vi.fn();
+    const onOpenFile = vi.fn();
+    const parentDrop = vi.fn();
+
+    mocks.mockUseCodeEditorActions.mockReturnValue(mocks.editorState);
+    store.set(localeAtom, "en");
+    store.set(
+      editorPaneActiveFilePathAtomFamily(getEditorPaneStateKey("ws-123", "pane-1")),
+      "src/app.tsx"
+    );
+
+    render(
+      <Provider store={store}>
+        <div onDrop={parentDrop}>
+          <EditorPaneCard
+            workspaceId="ws-123"
+            paneId="pane-1"
+            onClosePane={onClosePane}
+            onOpenFile={onOpenFile}
+            onSplitPane={onSplitPane}
+          />
+        </div>
+      </Provider>
+    );
+
+    const editorPane = screen.getByTestId("editor-pane-pane-1");
+    const dragOver = new Event("dragover", { bubbles: true, cancelable: true });
+    Object.defineProperty(dragOver, "dataTransfer", {
+      value: createSkillDirDataTransfer(
+        "my-review-skill",
+        "refs",
+        "/root/.agents/skills/my-review-skill/refs"
+      ),
+    });
+
+    fireEvent(editorPane, dragOver);
+
+    expect(dragOver.defaultPrevented).toBe(true);
+    expect(screen.queryByText("Open in editor")).toBeNull();
+
+    const drop = new Event("drop", { bubbles: true, cancelable: true });
+    Object.defineProperty(drop, "dataTransfer", {
+      value: createSkillDirDataTransfer(
+        "my-review-skill",
+        "refs",
+        "/root/.agents/skills/my-review-skill/refs"
+      ),
+    });
+
+    fireEvent(editorPane, drop);
+
+    expect(drop.defaultPrevented).toBe(true);
+    expect(parentDrop).not.toHaveBeenCalled();
+    expect(onOpenFile).not.toHaveBeenCalled();
+  });
+
+  it("prepares a hidden file drop shield while a skill file drag is active", () => {
+    const store = createStore();
+    const onClosePane = vi.fn();
+    const onSplitPane = vi.fn();
+    const onOpenFile = vi.fn();
+
+    mocks.mockUseCodeEditorActions.mockReturnValue(mocks.editorState);
+    store.set(localeAtom, "en");
+    store.set(
+      editorPaneActiveFilePathAtomFamily(getEditorPaneStateKey("ws-123", "pane-1")),
+      "docs/preview.md"
+    );
+
+    render(
+      <Provider store={store}>
+        <EditorPaneCard
+          workspaceId="ws-123"
+          paneId="pane-1"
+          onClosePane={onClosePane}
+          onOpenFile={onOpenFile}
+          onSplitPane={onSplitPane}
+        />
+      </Provider>
+    );
+
+    act(() => {
+      window.dispatchEvent(
+        new CustomEvent("coder-studio:skill-path-drag-start", {
+          detail: {
+            skillSlug: "my-review-skill",
+            path: "refs/guide.md",
+            absolutePath: "/root/.agents/skills/my-review-skill/refs/guide.md",
+            kind: "file",
+          },
+        })
+      );
+    });
+
+    const hiddenDropShield = document.querySelector(".editor-pane-card__file-drop-overlay");
+    expect(hiddenDropShield).toHaveClass("editor-pane-card__file-drop-overlay--hidden");
+
+    const dragOver = new Event("dragover", { bubbles: true, cancelable: true });
+    Object.defineProperty(dragOver, "dataTransfer", {
+      value: createSkillFileDataTransfer(
+        "my-review-skill",
+        "refs/guide.md",
+        "/root/.agents/skills/my-review-skill/refs/guide.md"
+      ),
+    });
+
+    fireEvent(hiddenDropShield!, dragOver);
+
+    expect(dragOver.defaultPrevented).toBe(true);
+    expect(screen.getByText("Open in editor")).toBeInTheDocument();
+
+    const drop = new Event("drop", { bubbles: true, cancelable: true });
+    Object.defineProperty(drop, "dataTransfer", {
+      value: createSkillFileDataTransfer(
+        "my-review-skill",
+        "refs/guide.md",
+        "/root/.agents/skills/my-review-skill/refs/guide.md"
+      ),
+    });
+
+    fireEvent(hiddenDropShield!, drop);
+
+    expect(onOpenFile).toHaveBeenCalledWith("pane-1", "skill:my-review-skill/refs/guide.md");
+
+    act(() => {
+      window.dispatchEvent(new Event("coder-studio:skill-path-drag-end"));
+    });
+    expect(document.querySelector(".editor-pane-card__file-drop-overlay")).toBeNull();
+  });
+
   it("keeps header actions right aligned when the editor pane has no open files", () => {
     const store = createStore();
     const onClosePane = vi.fn();
diff --git a/packages/web/src/features/agent-panes/views/shared/editor-pane-card.tsx b/packages/web/src/features/agent-panes/views/shared/editor-pane-card.tsx
index 04b3fcaa4..63513b741 100644
--- a/packages/web/src/features/agent-panes/views/shared/editor-pane-card.tsx
+++ b/packages/web/src/features/agent-panes/views/shared/editor-pane-card.tsx
@@ -4,6 +4,15 @@ import type { DragEvent, FC } from "react";
 import { useEffect, useState } from "react";
 import { ConfirmDialog, IconButton, Tooltip } from "../../../../components/ui";
 import { useTranslation } from "../../../../lib/i18n";
+import {
+  getSkillPathDragPayload,
+  hasSkillPathDragType,
+  isSkillPathDragPayload,
+  SKILL_PATH_DRAG_END_EVENT,
+  SKILL_PATH_DRAG_START_EVENT,
+  type SkillPathDragPayload,
+  toSkillDragEditorPath,
+} from "../../../../lib/skill-path-drag";
 import {
   getWorkspacePathDragPayload,
   hasWorkspacePathDragType,
@@ -43,6 +52,42 @@ function getEditorPaneTitle(path: string | null, fallbackTitle: string): string
   return getFileName(path);
 }
 
+function resolveDroppedEditorPath(
+  dataTransfer: DataTransfer | null | undefined,
+  workspaceId: string
+): string | null {
+  const workspacePayload = getWorkspacePathDragPayload(dataTransfer);
+  if (workspacePayload) {
+    if (workspacePayload.workspaceId !== workspaceId || workspacePayload.kind !== "file") {
+      return null;
+    }
+
+    return workspacePayload.path;
+  }
+
+  const skillPayload = getSkillPathDragPayload(dataTransfer);
+  return skillPayload?.kind === "file" ? toSkillDragEditorPath(skillPayload) : null;
+}
+
+function isHandledNonFileDrop(
+  dataTransfer: DataTransfer | null | undefined,
+  workspaceId: string,
+  workspacePathDragPayload: WorkspacePathDragPayload | null,
+  skillPathDragPayload: SkillPathDragPayload | null
+): boolean {
+  if (hasWorkspacePathDragType(dataTransfer)) {
+    const payload = getWorkspacePathDragPayload(dataTransfer) ?? workspacePathDragPayload;
+    return payload?.workspaceId === workspaceId && payload.kind === "dir";
+  }
+
+  if (hasSkillPathDragType(dataTransfer)) {
+    const payload = getSkillPathDragPayload(dataTransfer) ?? skillPathDragPayload;
+    return payload?.kind === "dir";
+  }
+
+  return false;
+}
+
 interface EditorPaneCardProps {
   dragState?: {
     isDragging: boolean;
@@ -71,6 +116,9 @@ export const EditorPaneCard: FC<EditorPaneCardProps> = ({
   const [isFileDropTarget, setIsFileDropTarget] = useState(false);
   const [workspacePathDragPayload, setWorkspacePathDragPayload] =
     useState<WorkspacePathDragPayload | null>(null);
+  const [skillPathDragPayload, setSkillPathDragPayload] = useState<SkillPathDragPayload | null>(
+    null
+  );
   const editorPaneStateKey = getEditorPaneStateKey(workspaceId, paneId);
   const activeFilePathAtom = editorPaneActiveFilePathAtomFamily(editorPaneStateKey);
   const editorModeAtom = editorPaneModeAtomFamily(editorPaneStateKey);
@@ -112,7 +160,8 @@ export const EditorPaneCard: FC<EditorPaneCardProps> = ({
   const shouldRenderFileDropOverlay =
     isFileDropTarget ||
     (workspacePathDragPayload?.workspaceId === workspaceId &&
-      workspacePathDragPayload.kind === "file");
+      workspacePathDragPayload.kind === "file") ||
+    skillPathDragPayload?.kind === "file";
 
   useEffect(() => {
     const handleWorkspacePathDragStart = (event: Event) => {
@@ -132,6 +181,24 @@ export const EditorPaneCard: FC<EditorPaneCardProps> = ({
     };
   }, []);
 
+  useEffect(() => {
+    const handleSkillPathDragStart = (event: Event) => {
+      const payload = event instanceof CustomEvent ? event.detail : null;
+      setSkillPathDragPayload(isSkillPathDragPayload(payload) ? payload : null);
+    };
+    const handleSkillPathDragEnd = () => {
+      setSkillPathDragPayload(null);
+      setIsFileDropTarget(false);
+    };
+
+    window.addEventListener(SKILL_PATH_DRAG_START_EVENT, handleSkillPathDragStart);
+    window.addEventListener(SKILL_PATH_DRAG_END_EVENT, handleSkillPathDragEnd);
+    return () => {
+      window.removeEventListener(SKILL_PATH_DRAG_START_EVENT, handleSkillPathDragStart);
+      window.removeEventListener(SKILL_PATH_DRAG_END_EVENT, handleSkillPathDragEnd);
+    };
+  }, []);
+
   const requestClosePane = () => {
     if (isDirtyTextFile) {
       setCloseConfirmOpen(true);
@@ -145,14 +212,37 @@ export const EditorPaneCard: FC<EditorPaneCardProps> = ({
     onClosePane(paneId);
   };
   const handleWorkspaceFileDragEnter = (event: DragEvent<HTMLDivElement>) => {
-    if (!onOpenFile || !hasWorkspacePathDragType(event.dataTransfer)) {
+    if (!onOpenFile) {
+      return;
+    }
+
+    const hasWorkspacePath = hasWorkspacePathDragType(event.dataTransfer);
+    const hasSkillPath = hasSkillPathDragType(event.dataTransfer);
+    if (!hasWorkspacePath && !hasSkillPath) {
+      return;
+    }
+
+    if (resolveDroppedEditorPath(event.dataTransfer, workspaceId)) {
+      event.preventDefault();
+      event.stopPropagation();
+      event.dataTransfer.dropEffect = "copy";
+      setIsFileDropTarget(true);
       return;
     }
 
-    event.preventDefault();
-    event.stopPropagation();
-    event.dataTransfer.dropEffect = "copy";
-    setIsFileDropTarget(true);
+    if (
+      isHandledNonFileDrop(
+        event.dataTransfer,
+        workspaceId,
+        workspacePathDragPayload,
+        skillPathDragPayload
+      )
+    ) {
+      event.preventDefault();
+      event.stopPropagation();
+      event.dataTransfer.dropEffect = "none";
+      setIsFileDropTarget(false);
+    }
   };
   const handleWorkspaceFileDragLeave = (event: DragEvent<HTMLDivElement>) => {
     const nextTarget = event.relatedTarget;
@@ -163,20 +253,31 @@ export const EditorPaneCard: FC<EditorPaneCardProps> = ({
     setIsFileDropTarget(false);
   };
   const handleWorkspaceFileDrop = (event: DragEvent<HTMLDivElement>) => {
-    if (!onOpenFile || !hasWorkspacePathDragType(event.dataTransfer)) {
+    if (!onOpenFile) {
       return;
     }
 
-    event.preventDefault();
-    event.stopPropagation();
-    setIsFileDropTarget(false);
-
-    const payload = getWorkspacePathDragPayload(event.dataTransfer);
-    if (!payload || payload.workspaceId !== workspaceId || payload.kind !== "file") {
+    const path = resolveDroppedEditorPath(event.dataTransfer, workspaceId);
+    if (path) {
+      setIsFileDropTarget(false);
+      event.preventDefault();
+      event.stopPropagation();
+      onOpenFile(paneId, path);
       return;
     }
 
-    onOpenFile(paneId, payload.path);
+    if (
+      isHandledNonFileDrop(
+        event.dataTransfer,
+        workspaceId,
+        workspacePathDragPayload,
+        skillPathDragPayload
+      )
+    ) {
+      setIsFileDropTarget(false);
+      event.preventDefault();
+      event.stopPropagation();
+    }
   };
 
   return (
diff --git a/packages/web/src/features/canvas/api.test.ts b/packages/web/src/features/canvas/api.test.ts
new file mode 100644
index 000000000..5415cac2e
--- /dev/null
+++ b/packages/web/src/features/canvas/api.test.ts
@@ -0,0 +1,107 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fetchCanvasData } from "./api";
+
+describe("fetchCanvasData", () => {
+  const originalFetch = globalThis.fetch;
+  const sourcePath = ".coder-studio/canvases/runtime-flow.csc";
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it("parses a valid canvas payload", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: vi.fn().mockResolvedValue({
+        workspaceId: "ws-1",
+        sourcePath,
+        title: "Runtime Flow",
+        kind: "architecture_canvas",
+        renderStatus: "ready",
+        lastError: null,
+        compiledDocument: {
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [
+            {
+              type: "diagram",
+              nodes: [{ id: "web", label: "Web UI" }],
+              edges: [],
+            },
+            {
+              type: "annotations",
+              items: [],
+            },
+          ],
+        },
+      }),
+    });
+    globalThis.fetch = fetchMock as typeof fetch;
+
+    const result = await fetchCanvasData("ws-1", sourcePath);
+
+    expect(result.sourcePath).toBe(sourcePath);
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/canvas/ws-1/data?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc",
+      {
+        credentials: "include",
+      }
+    );
+  });
+
+  it("rejects malformed canvas payloads", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: vi.fn().mockResolvedValue({
+        canvasId: "canvas-1",
+        renderStatus: "ready",
+      }),
+    });
+    globalThis.fetch = fetchMock as typeof fetch;
+
+    await expect(fetchCanvasData("ws-1", sourcePath)).rejects.toThrow("canvas_response_invalid");
+  });
+
+  it("rejects invalid json payloads", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: vi.fn().mockRejectedValue(new SyntaxError("Unexpected token <")),
+    });
+    globalThis.fetch = fetchMock as typeof fetch;
+
+    await expect(fetchCanvasData("ws-1", sourcePath)).rejects.toThrow("canvas_response_invalid");
+  });
+
+  it("rejects architecture payloads without a diagram section", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: vi.fn().mockResolvedValue({
+        workspaceId: "ws-1",
+        sourcePath,
+        title: "Runtime Flow",
+        kind: "architecture_canvas",
+        renderStatus: "ready",
+        lastError: null,
+        compiledDocument: {
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [
+            {
+              type: "annotations",
+              items: [{ title: "Boundary", body: "Server owns execution." }],
+            },
+          ],
+        },
+      }),
+    });
+    globalThis.fetch = fetchMock as typeof fetch;
+
+    await expect(fetchCanvasData("ws-1", sourcePath)).rejects.toThrow("canvas_response_invalid");
+  });
+});
diff --git a/packages/web/src/features/canvas/api.ts b/packages/web/src/features/canvas/api.ts
new file mode 100644
index 000000000..e652d66e9
--- /dev/null
+++ b/packages/web/src/features/canvas/api.ts
@@ -0,0 +1,49 @@
+import { type CanvasDataResponse, CanvasDataResponseSchema } from "@coder-studio/core";
+
+function isRenderableCanvasResponse(data: CanvasDataResponse): boolean {
+  if (data.renderStatus !== "ready") {
+    return true;
+  }
+
+  if (data.compiledDocument.kind !== "architecture_canvas") {
+    return true;
+  }
+
+  return data.compiledDocument.sections.some((section) => section.type === "diagram");
+}
+
+async function readJson(response: Response): Promise<CanvasDataResponse> {
+  if (!response.ok) {
+    throw new Error(`canvas_request_failed:${response.status}`);
+  }
+
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new Error("canvas_response_invalid");
+  }
+
+  const parsed = CanvasDataResponseSchema.safeParse(payload);
+
+  if (!parsed.success || !isRenderableCanvasResponse(parsed.data)) {
+    throw new Error("canvas_response_invalid");
+  }
+
+  return parsed.data;
+}
+
+export async function fetchCanvasData(
+  workspaceId: string,
+  sourcePath: string
+): Promise<CanvasDataResponse> {
+  const query = new URLSearchParams({ sourcePath });
+  const response = await fetch(
+    `/api/canvas/${encodeURIComponent(workspaceId)}/data?${query.toString()}`,
+    {
+      credentials: "include",
+    }
+  );
+
+  return readJson(response);
+}
diff --git a/packages/web/src/features/canvas/components/architecture-canvas-renderer.test.tsx b/packages/web/src/features/canvas/components/architecture-canvas-renderer.test.tsx
new file mode 100644
index 000000000..2d38e4e6a
--- /dev/null
+++ b/packages/web/src/features/canvas/components/architecture-canvas-renderer.test.tsx
@@ -0,0 +1,144 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { ArchitectureCanvasRenderer } from "./architecture-canvas-renderer";
+
+vi.mock("./mermaid-diagram", () => ({
+  MermaidDiagram: ({ source }: { source: string }) => <div data-testid="mermaid-svg">{source}</div>,
+}));
+
+describe("ArchitectureCanvasRenderer", () => {
+  it("renders a fallback when no diagram section is present", () => {
+    render(
+      <ArchitectureCanvasRenderer
+        canvas={{
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [
+            {
+              type: "annotations",
+              items: [{ title: "Boundary", body: "Server owns execution." }],
+            },
+          ],
+        }}
+      />
+    );
+
+    expect(screen.getByText("Canvas diagram unavailable.")).toBeInTheDocument();
+  });
+
+  it("renders a mermaid diagram when mermaidSource is available", async () => {
+    render(
+      <ArchitectureCanvasRenderer
+        canvas={{
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [
+            {
+              type: "diagram",
+              mermaidSource: "flowchart LR\nWebUI[Web UI] --> Server[Runtime Server]",
+              direction: "LR",
+              nodes: [
+                { id: "WebUI", label: "Web UI" },
+                { id: "Server", label: "Runtime Server" },
+              ],
+              edges: [{ from: "WebUI", to: "Server" }],
+            },
+            {
+              type: "annotations",
+              items: [{ title: "Boundary", body: "Server owns execution." }],
+            },
+          ],
+        }}
+      />
+    );
+
+    expect(screen.getByTestId("mermaid-svg")).toBeInTheDocument();
+    expect(screen.getByTestId("mermaid-svg")).toHaveTextContent(/flowchart LR/);
+    expect(screen.queryByText("System Diagram")).not.toBeInTheDocument();
+    expect(screen.getByText("Boundary")).toBeInTheDocument();
+  });
+
+  it("renders compiled groups instead of inferred role layers when mermaidSource is absent", () => {
+    render(
+      <ArchitectureCanvasRenderer
+        canvas={{
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [
+            {
+              type: "diagram",
+              direction: "LR",
+              groups: [
+                {
+                  id: "execution-cluster",
+                  label: "Execution Cluster",
+                  nodeIds: ["alpha", "beta"],
+                },
+              ],
+              nodes: [
+                { id: "alpha", label: "Alpha Node" },
+                { id: "beta", label: "Beta Node" },
+              ],
+              edges: [{ from: "alpha", to: "beta", label: "dispatch" }],
+            },
+            {
+              type: "annotations",
+              items: [{ title: "Boundary", body: "Server owns execution." }],
+            },
+          ],
+        }}
+      />
+    );
+
+    expect(screen.getByText("Execution Cluster")).toBeInTheDocument();
+    expect(screen.getByText("Contains 2 nodes")).toBeInTheDocument();
+    expect(screen.queryByText("Data layer")).not.toBeInTheDocument();
+  });
+
+  it("renders diagram nodes, edges, and annotations when mermaidSource is absent", () => {
+    render(
+      <ArchitectureCanvasRenderer
+        canvas={{
+          kind: "architecture_canvas",
+          title: "Runtime Flow",
+          summary: "How requests move.",
+          sections: [
+            {
+              type: "diagram",
+              direction: "LR",
+              nodes: [
+                { id: "web", label: "Web UI" },
+                { id: "server", label: "Server Runtime" },
+                { id: "provider", label: "Model Provider" },
+              ],
+              edges: [
+                { from: "web", to: "server", label: "dispatch" },
+                { from: "server", to: "provider", label: "run command" },
+              ],
+            },
+            {
+              type: "annotations",
+              items: [{ title: "Boundary", body: "Server owns execution." }],
+            },
+          ],
+        }}
+      />
+    );
+
+    expect(screen.getByText("System Diagram")).toBeInTheDocument();
+    expect(screen.getByText("Left to right flow")).toBeInTheDocument();
+    expect(screen.getByText("Nodes")).toBeInTheDocument();
+    expect(screen.getByText("Web UI")).toBeInTheDocument();
+    expect(screen.getByText("Server Runtime")).toBeInTheDocument();
+    expect(screen.getByText("Model Provider")).toBeInTheDocument();
+    expect(screen.getByText("dispatch")).toBeInTheDocument();
+    expect(screen.getByText("run command")).toBeInTheDocument();
+    expect(screen.getByText("Boundary")).toBeInTheDocument();
+    expect(screen.getByText("Server owns execution.")).toBeInTheDocument();
+  });
+});
diff --git a/packages/web/src/features/canvas/components/architecture-canvas-renderer.tsx b/packages/web/src/features/canvas/components/architecture-canvas-renderer.tsx
new file mode 100644
index 000000000..54c11990d
--- /dev/null
+++ b/packages/web/src/features/canvas/components/architecture-canvas-renderer.tsx
@@ -0,0 +1,184 @@
+import type { CompiledCanvas } from "@coder-studio/core";
+import { MermaidDiagram } from "./mermaid-diagram";
+
+interface ArchitectureCanvasRendererProps {
+  canvas: Extract<CompiledCanvas, { kind: "architecture_canvas" }>;
+}
+
+type ArchitectureDiagramSection = Extract<
+  Extract<CompiledCanvas, { kind: "architecture_canvas" }>["sections"][number],
+  { type: "diagram" }
+>;
+
+function formatDirection(direction: ArchitectureDiagramSection["direction"] | undefined): string {
+  switch (direction) {
+    case "RL":
+      return "Right to left flow";
+    case "TB":
+    case "TD":
+      return "Top to bottom flow";
+    case "BT":
+      return "Bottom to top flow";
+    case "LR":
+    default:
+      return "Left to right flow";
+  }
+}
+
+function renderNodeCard(node: { id: string; label?: string }, key: string) {
+  return (
+    <article
+      key={key}
+      style={{
+        border: "1px solid rgba(31,41,51,0.12)",
+        borderRadius: "18px",
+        padding: "14px 16px",
+        background: "rgba(255,255,255,0.92)",
+      }}
+    >
+      <strong>{node.label ?? node.id}</strong>
+      {node.label && node.label !== node.id ? (
+        <div style={{ color: "#52606d", fontSize: "0.9rem", marginTop: "4px" }}>{node.id}</div>
+      ) : null}
+    </article>
+  );
+}
+
+function renderDiagramDetails(diagram: ArchitectureDiagramSection) {
+  const nodeMap = new Map(diagram.nodes.map((node) => [node.id, node] as const));
+  const groupedNodeIds = new Set((diagram.groups ?? []).flatMap((group) => group.nodeIds));
+  const ungroupedNodes = diagram.nodes.filter((node) => !groupedNodeIds.has(node.id));
+
+  return (
+    <>
+      <div style={{ display: "grid", gap: "6px" }}>
+        <h2 style={{ margin: 0 }}>System Diagram</h2>
+        <p style={{ margin: 0, color: "#52606d" }}>{formatDirection(diagram.direction)}</p>
+      </div>
+
+      {diagram.groups?.map((group) => (
+        <section key={group.id} style={{ display: "grid", gap: "10px" }}>
+          <div style={{ display: "grid", gap: "4px" }}>
+            <h3 style={{ margin: 0 }}>{group.label}</h3>
+            <p style={{ margin: 0, color: "#52606d", fontSize: "0.9rem" }}>
+              Contains {group.nodeIds.length} node{group.nodeIds.length === 1 ? "" : "s"}
+            </p>
+          </div>
+          <div
+            style={{
+              display: "grid",
+              gap: "12px",
+              gridTemplateColumns: "repeat(auto-fit, minmax(180px, 1fr))",
+            }}
+          >
+            {group.nodeIds.map((nodeId, index) =>
+              renderNodeCard(nodeMap.get(nodeId) ?? { id: nodeId }, `${group.id}-${index}`)
+            )}
+          </div>
+        </section>
+      ))}
+
+      {ungroupedNodes.length > 0 ? (
+        <section style={{ display: "grid", gap: "10px" }}>
+          <h3 style={{ margin: 0 }}>Nodes</h3>
+          <div
+            style={{
+              display: "grid",
+              gap: "12px",
+              gridTemplateColumns: "repeat(auto-fit, minmax(180px, 1fr))",
+            }}
+          >
+            {ungroupedNodes.map((node) => renderNodeCard(node, node.id))}
+          </div>
+        </section>
+      ) : null}
+
+      <section style={{ display: "grid", gap: "8px" }}>
+        <h3 style={{ margin: 0 }}>Connections</h3>
+        <div style={{ display: "grid", gap: "8px" }}>
+          {diagram.edges.map((edge, index) => (
+            <div
+              key={`${edge.from}-${edge.to}-${index}`}
+              style={{
+                borderLeft: "3px solid #0f766e",
+                paddingLeft: "12px",
+                color: "#334155",
+              }}
+            >
+              <strong>{edge.label ?? `${edge.from} -> ${edge.to}`}</strong>
+              <div style={{ color: "#64748b", fontSize: "0.9rem" }}>
+                {edge.from}
+                {" -> "}
+                {edge.to}
+              </div>
+            </div>
+          ))}
+        </div>
+      </section>
+    </>
+  );
+}
+
+export function ArchitectureCanvasRenderer({ canvas }: ArchitectureCanvasRendererProps) {
+  const diagram = canvas.sections.find((section) => section.type === "diagram");
+  const annotations = canvas.sections.find((section) => section.type === "annotations");
+
+  if (!diagram) {
+    return (
+      <section
+        style={{
+          border: "1px solid rgba(185,28,28,0.2)",
+          borderRadius: "20px",
+          padding: "18px",
+          background: "rgba(255,255,255,0.84)",
+          color: "#7f1d1d",
+        }}
+      >
+        Canvas diagram unavailable.
+      </section>
+    );
+  }
+
+  return (
+    <div style={{ display: "grid", gap: "18px" }}>
+      <section
+        style={{
+          border: "1px solid rgba(15,23,42,0.08)",
+          borderRadius: "24px",
+          padding: "20px",
+          background:
+            "linear-gradient(180deg, rgba(252,253,252,0.96) 0%, rgba(244,248,247,0.98) 100%)",
+          boxShadow: "0 24px 50px rgba(15, 23, 42, 0.08)",
+          display: "grid",
+          gap: "16px",
+        }}
+      >
+        {diagram.mermaidSource ? (
+          <MermaidDiagram source={diagram.mermaidSource} />
+        ) : (
+          renderDiagramDetails(diagram)
+        )}
+      </section>
+
+      {annotations && annotations.items.length > 0 ? (
+        <section
+          style={{
+            border: "1px solid rgba(31,41,51,0.12)",
+            borderRadius: "20px",
+            padding: "18px",
+            background: "rgba(255,255,255,0.84)",
+            display: "grid",
+            gap: "12px",
+          }}
+        >
+          {annotations.items.map((item, index) => (
+            <article key={`${item.title}-${index}`}>
+              <h3 style={{ margin: "0 0 6px" }}>{item.title}</h3>
+              <p style={{ margin: 0, color: "#52606d", lineHeight: 1.6 }}>{item.body}</p>
+            </article>
+          ))}
+        </section>
+      ) : null}
+    </div>
+  );
+}
diff --git a/packages/web/src/features/canvas/components/canvas-content.tsx b/packages/web/src/features/canvas/components/canvas-content.tsx
new file mode 100644
index 000000000..6f25335aa
--- /dev/null
+++ b/packages/web/src/features/canvas/components/canvas-content.tsx
@@ -0,0 +1,121 @@
+import type { CanvasDataResponse } from "@coder-studio/core";
+import { useEffect, useState } from "react";
+import { fetchCanvasData } from "../api";
+import { ArchitectureCanvasRenderer } from "./architecture-canvas-renderer";
+import { type CanvasContentLayout, CanvasRouteFrame } from "./canvas-route-frame";
+import { ReportCanvasRenderer } from "./report-canvas-renderer";
+
+export type { CanvasContentLayout } from "./canvas-route-frame";
+
+interface CanvasContentProps {
+  workspaceId: string;
+  sourcePath: string;
+  refreshToken?: number;
+  layout?: CanvasContentLayout;
+}
+
+export function CanvasContent({
+  workspaceId,
+  sourcePath,
+  refreshToken = 0,
+  layout = "page",
+}: CanvasContentProps) {
+  const [data, setData] = useState<CanvasDataResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const normalizedSourcePath = sourcePath.trim();
+    if (!workspaceId || !normalizedSourcePath) {
+      setData(null);
+      setError("Canvas route is missing workspace or source path.");
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    setData(null);
+    setLoading(true);
+    setError(null);
+
+    void fetchCanvasData(workspaceId, normalizedSourcePath)
+      .then((response) => {
+        if (cancelled) {
+          return;
+        }
+        setData(response);
+        setLoading(false);
+      })
+      .catch((nextError) => {
+        if (cancelled) {
+          return;
+        }
+        setError(nextError instanceof Error ? nextError.message : "Failed to load canvas.");
+        setLoading(false);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [refreshToken, sourcePath, workspaceId]);
+
+  if (loading) {
+    return <CanvasRouteFrame layout={layout} loading />;
+  }
+
+  if (error) {
+    return <CanvasRouteFrame layout={layout} error={<p style={{ margin: 0 }}>{error}</p>} />;
+  }
+
+  if (!data) {
+    return (
+      <CanvasRouteFrame
+        layout={layout}
+        error={<p style={{ margin: 0 }}>Canvas data is unavailable.</p>}
+      />
+    );
+  }
+
+  if (data.renderStatus === "error") {
+    return (
+      <CanvasRouteFrame
+        layout={layout}
+        title={data.title}
+        error={
+          <div>
+            <h2 style={{ marginTop: 0 }}>Render failed</h2>
+            <p style={{ marginBottom: 0 }}>{data.lastError?.message ?? "Unknown canvas error."}</p>
+          </div>
+        }
+      />
+    );
+  }
+
+  if (!data.compiledDocument) {
+    return (
+      <CanvasRouteFrame
+        layout={layout}
+        error={<p style={{ margin: 0 }}>Canvas data is unavailable.</p>}
+      />
+    );
+  }
+
+  if (data.compiledDocument.kind === "architecture_canvas") {
+    return (
+      <CanvasRouteFrame
+        layout={layout}
+        title={data.compiledDocument.title}
+        summary={data.compiledDocument.summary}
+        variant="architecture"
+      >
+        <ArchitectureCanvasRenderer canvas={data.compiledDocument} />
+      </CanvasRouteFrame>
+    );
+  }
+
+  return (
+    <CanvasRouteFrame layout={layout} title={data.compiledDocument.title}>
+      <ReportCanvasRenderer canvas={data.compiledDocument} />
+    </CanvasRouteFrame>
+  );
+}
diff --git a/packages/web/src/features/canvas/components/canvas-route-frame.tsx b/packages/web/src/features/canvas/components/canvas-route-frame.tsx
new file mode 100644
index 000000000..696e3de0a
--- /dev/null
+++ b/packages/web/src/features/canvas/components/canvas-route-frame.tsx
@@ -0,0 +1,120 @@
+import type { PropsWithChildren, ReactNode } from "react";
+
+export type CanvasContentLayout = "page" | "inline";
+
+interface CanvasRouteFrameProps extends PropsWithChildren {
+  title?: string;
+  summary?: string;
+  error?: ReactNode;
+  loading?: boolean;
+  variant?: "report" | "architecture";
+  layout?: CanvasContentLayout;
+}
+
+export function CanvasRouteFrame({
+  children,
+  title,
+  summary,
+  error,
+  loading = false,
+  variant = "report",
+  layout = "page",
+}: CanvasRouteFrameProps) {
+  const isArchitecture = variant === "architecture";
+  const isInline = layout === "inline";
+
+  return (
+    <main
+      className={isInline ? "canvas-route-frame canvas-route-frame--inline" : "canvas-route-frame"}
+      style={{
+        minHeight: isInline ? "auto" : "100vh",
+        padding: isInline ? "16px" : "24px",
+        background: isArchitecture
+          ? "linear-gradient(180deg, rgba(244,249,248,1) 0%, rgba(235,242,241,1) 100%)"
+          : "linear-gradient(180deg, rgba(248,245,238,1) 0%, rgba(240,234,223,1) 100%)",
+        color: "#1f2933",
+        fontFamily: isArchitecture
+          ? '"Instrument Sans", "Avenir Next", "Segoe UI", sans-serif'
+          : '"Iowan Old Style", "Palatino Linotype", "Book Antiqua", serif',
+      }}
+    >
+      <section
+        style={{
+          maxWidth: "1100px",
+          margin: "0 auto",
+          display: "grid",
+          gap: "18px",
+        }}
+      >
+        {title ? (
+          <header style={{ display: "grid", gap: isArchitecture ? "12px" : "10px" }}>
+            {isArchitecture ? (
+              <p
+                style={{
+                  margin: 0,
+                  fontSize: "0.82rem",
+                  fontWeight: 700,
+                  letterSpacing: "0.1em",
+                  textTransform: "uppercase",
+                  color: "#0f766e",
+                }}
+              >
+                Canvas Renderer
+              </p>
+            ) : null}
+            <h1
+              style={{
+                margin: 0,
+                fontSize: "clamp(2rem, 4vw, 3rem)",
+                lineHeight: isArchitecture ? 0.98 : 1.05,
+                color: isArchitecture ? "#0f172a" : "#1f2933",
+                letterSpacing: isArchitecture ? "-0.03em" : undefined,
+              }}
+            >
+              {title}
+            </h1>
+            {summary ? (
+              <p
+                style={{
+                  margin: 0,
+                  color: "#52606d",
+                  fontSize: isArchitecture ? "1.02rem" : "1rem",
+                  lineHeight: 1.6,
+                  maxWidth: isArchitecture ? "72ch" : undefined,
+                }}
+              >
+                {summary}
+              </p>
+            ) : null}
+          </header>
+        ) : null}
+        {loading ? (
+          <section
+            style={{
+              border: "1px solid rgba(31,41,51,0.12)",
+              borderRadius: "20px",
+              padding: "18px",
+              background: "rgba(255,255,255,0.84)",
+            }}
+          >
+            Loading canvas...
+          </section>
+        ) : null}
+        {error ? (
+          <section
+            style={{
+              border: "1px solid rgba(185,28,28,0.2)",
+              borderRadius: "20px",
+              padding: "18px",
+              background: "rgba(255,255,255,0.84)",
+              color: "#7f1d1d",
+            }}
+          >
+            {error}
+          </section>
+        ) : null}
+        {!loading && !error ? children : null}
+      </section>
+    </main>
+  );
+}
diff --git a/packages/web/src/features/canvas/components/mermaid-diagram.tsx b/packages/web/src/features/canvas/components/mermaid-diagram.tsx
new file mode 100644
index 000000000..12d433f41
--- /dev/null
+++ b/packages/web/src/features/canvas/components/mermaid-diagram.tsx
@@ -0,0 +1,122 @@
+import { useEffect, useId, useRef, useState } from "react";
+
+const MERMAID_SCRIPT_SRC = "/api/preview/assets/mermaid.min.js";
+
+type MermaidRuntime = {
+  initialize: (config: Record<string, unknown>) => void;
+  render: (
+    id: string,
+    source: string
+  ) => Promise<{ svg: string; bindFunctions?: (element: Element) => void }>;
+};
+
+declare global {
+  interface Window {
+    mermaid?: MermaidRuntime;
+  }
+}
+
+let mermaidLoader: Promise<MermaidRuntime> | null = null;
+
+export function loadMermaidRuntime(): Promise<MermaidRuntime> {
+  if (mermaidLoader) {
+    return mermaidLoader;
+  }
+
+  mermaidLoader = new Promise((resolve, reject) => {
+    if (window.mermaid) {
+      window.mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: "strict",
+        theme: "neutral",
+      });
+      resolve(window.mermaid);
+      return;
+    }
+
+    const script = document.createElement("script");
+    script.src = MERMAID_SCRIPT_SRC;
+    script.async = true;
+    script.onload = () => {
+      if (!window.mermaid) {
+        mermaidLoader = null;
+        reject(new Error("Mermaid runtime failed to initialize."));
+        return;
+      }
+
+      window.mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: "strict",
+        theme: "neutral",
+      });
+      resolve(window.mermaid);
+    };
+    script.onerror = () => {
+      mermaidLoader = null;
+      reject(new Error("Failed to load Mermaid runtime."));
+    };
+    document.head.appendChild(script);
+  });
+
+  return mermaidLoader;
+}
+
+export function resetMermaidRuntimeForTests(): void {
+  mermaidLoader = null;
+  delete window.mermaid;
+}
+
+interface MermaidDiagramProps {
+  source: string;
+}
+
+export function MermaidDiagram({ source }: MermaidDiagramProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const renderId = useId().replace(/:/g, "");
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) {
+      return;
+    }
+
+    let cancelled = false;
+    container.replaceChildren();
+    setError(null);
+
+    void loadMermaidRuntime()
+      .then(async (mermaid) => {
+        const id = `mermaid-${renderId}`;
+        const { svg, bindFunctions } = await mermaid.render(id, source);
+        if (cancelled) {
+          return;
+        }
+
+        container.innerHTML = svg;
+        bindFunctions?.(container);
+      })
+      .catch((nextError) => {
+        if (cancelled) {
+          return;
+        }
+
+        container.replaceChildren();
+        setError(nextError instanceof Error ? nextError.message : "Failed to render diagram.");
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [renderId, source]);
+
+  if (error) {
+    return (
+      <p style={{ margin: 0, color: "#7f1d1d", lineHeight: 1.6 }}>
+        Mermaid diagram failed to render: {error}
+      </p>
+    );
+  }
+
+  return <div ref={containerRef} className="architecture-canvas-mermaid" />;
+}
diff --git a/packages/web/src/features/canvas/components/report-canvas-renderer.test.tsx b/packages/web/src/features/canvas/components/report-canvas-renderer.test.tsx
new file mode 100644
index 000000000..cacc0a6e0
--- /dev/null
+++ b/packages/web/src/features/canvas/components/report-canvas-renderer.test.tsx
@@ -0,0 +1,41 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { ReportCanvasRenderer } from "./report-canvas-renderer";
+
+describe("ReportCanvasRenderer", () => {
+  it("renders markdown blocks as formatted markdown content", () => {
+    render(
+      <ReportCanvasRenderer
+        canvas={{
+          kind: "report_canvas",
+          title: "Audit",
+          sections: [
+            {
+              type: "section",
+              title: "Key Findings",
+              blocks: [
+                {
+                  type: "markdown",
+                  markdown:
+                    "This **matters**. Review the [docs](https://example.com/docs).\n\n- First item\n- Second item\n\n```ts\nconst score = 1;\n```",
+                },
+              ],
+            },
+          ],
+        }}
+      />
+    );
+
+    expect(screen.getByText("Key Findings")).toBeInTheDocument();
+    expect(screen.getByText("matters").closest("strong")).not.toBeNull();
+    expect(screen.getByRole("link", { name: "docs" })).toHaveAttribute(
+      "href",
+      "https://example.com/docs"
+    );
+    expect(screen.getByText("First item").closest("li")).not.toBeNull();
+    expect(screen.getByText("Second item").closest("li")).not.toBeNull();
+    expect(screen.getByText("const score = 1;").closest("code")).not.toBeNull();
+  });
+});
diff --git a/packages/web/src/features/canvas/components/report-canvas-renderer.tsx b/packages/web/src/features/canvas/components/report-canvas-renderer.tsx
new file mode 100644
index 000000000..8fdf9eced
--- /dev/null
+++ b/packages/web/src/features/canvas/components/report-canvas-renderer.tsx
@@ -0,0 +1,174 @@
+import type { CompiledCanvas } from "@coder-studio/core";
+import MarkdownIt from "markdown-it";
+
+interface ReportCanvasRendererProps {
+  canvas: Extract<CompiledCanvas, { kind: "report_canvas" }>;
+}
+
+const panelStyle = {
+  border: "1px solid rgba(31,41,51,0.12)",
+  borderRadius: "20px",
+  padding: "18px",
+  background: "rgba(255,255,255,0.84)",
+};
+
+const markdownStyle = {
+  color: "#52606d",
+  lineHeight: 1.6,
+};
+
+const markdown = new MarkdownIt({
+  html: false,
+  linkify: true,
+  typographer: false,
+});
+
+function renderBlock(
+  block: Extract<
+    Extract<CompiledCanvas, { kind: "report_canvas" }>["sections"][number],
+    { type: "section" }
+  >["blocks"][number],
+  key: string
+) {
+  switch (block.type) {
+    case "markdown":
+      return (
+        <div
+          key={key}
+          style={markdownStyle}
+          dangerouslySetInnerHTML={{ __html: markdown.render(block.markdown) }}
+        />
+      );
+    case "list":
+      return (
+        <ul key={key} style={{ margin: 0, color: "#52606d", lineHeight: 1.6 }}>
+          {block.items.map((item, index) => (
+            <li key={`${key}-${index}`}>{item}</li>
+          ))}
+        </ul>
+      );
+    case "table":
+      return (
+        <table key={key} style={{ width: "100%", borderCollapse: "collapse" }}>
+          <thead>
+            <tr>
+              {block.columns.map((column) => (
+                <th
+                  key={`${key}-${column}`}
+                  style={{
+                    textAlign: "left",
+                    padding: "10px 12px",
+                    borderBottom: "1px solid rgba(31,41,51,0.12)",
+                  }}
+                >
+                  {column}
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {block.rows.map((row, rowIndex) => (
+              <tr key={`${key}-${rowIndex}`}>
+                {row.map((cell, cellIndex) => (
+                  <td
+                    key={`${key}-${rowIndex}-${cellIndex}`}
+                    style={{ padding: "10px 12px", borderBottom: "1px solid rgba(31,41,51,0.12)" }}
+                  >
+                    {cell}
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      );
+    case "callout":
+      return (
+        <aside
+          key={key}
+          style={{
+            borderRadius: "16px",
+            padding: "14px 16px",
+            background: "rgba(15,118,110,0.08)",
+          }}
+        >
+          <h3 style={{ margin: "0 0 8px" }}>{block.title}</h3>
+          <p style={{ margin: 0, color: "#52606d", lineHeight: 1.6 }}>{block.body}</p>
+        </aside>
+      );
+    case "stats":
+      return (
+        <div
+          key={key}
+          style={{
+            display: "grid",
+            gap: "12px",
+            gridTemplateColumns: "repeat(auto-fit, minmax(140px, 1fr))",
+          }}
+        >
+          {block.items.map((item, index) => (
+            <article
+              key={`${key}-${index}`}
+              style={{
+                border: "1px solid rgba(31,41,51,0.12)",
+                borderRadius: "14px",
+                padding: "14px",
+                background: "rgba(255,255,255,0.9)",
+              }}
+            >
+              <span style={{ display: "block", color: "#52606d" }}>{item.label}</span>
+              <strong>{item.value}</strong>
+            </article>
+          ))}
+        </div>
+      );
+  }
+}
+
+export function ReportCanvasRenderer({ canvas }: ReportCanvasRendererProps) {
+  return (
+    <div style={{ display: "grid", gap: "18px" }}>
+      {canvas.sections.map((section, sectionIndex) => {
+        if (section.type === "stats") {
+          return (
+            <section key={`stats-${sectionIndex}`} style={panelStyle}>
+              <div
+                style={{
+                  display: "grid",
+                  gap: "12px",
+                  gridTemplateColumns: "repeat(auto-fit, minmax(140px, 1fr))",
+                }}
+              >
+                {section.items.map((item, itemIndex) => (
+                  <article
+                    key={`stats-${sectionIndex}-${itemIndex}`}
+                    style={{
+                      border: "1px solid rgba(31,41,51,0.12)",
+                      borderRadius: "14px",
+                      padding: "14px",
+                      background: "rgba(255,255,255,0.9)",
+                    }}
+                  >
+                    <span style={{ display: "block", color: "#52606d" }}>{item.label}</span>
+                    <strong>{item.value}</strong>
+                  </article>
+                ))}
+              </div>
+            </section>
+          );
+        }
+
+        return (
+          <section key={`section-${sectionIndex}`} style={panelStyle}>
+            <h2 style={{ marginTop: 0 }}>{section.title}</h2>
+            <div style={{ display: "grid", gap: "14px" }}>
+              {section.blocks.map((block, blockIndex) =>
+                renderBlock(block, `section-${sectionIndex}-block-${blockIndex}`)
+              )}
+            </div>
+          </section>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx b/packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx
new file mode 100644
index 000000000..3326591e7
--- /dev/null
+++ b/packages/web/src/features/canvas/routes/embedded-canvas-route.test.tsx
@@ -0,0 +1,210 @@
+// @vitest-environment jsdom
+
+import { render, screen, waitFor } from "@testing-library/react";
+import { MemoryRouter, Route, Routes } from "react-router-dom";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { EmbeddedCanvasRoute } from "./embedded-canvas-route";
+
+const fetchCanvasDataMock = vi.fn();
+
+vi.mock("../api", () => ({
+  fetchCanvasData: (...args: unknown[]) => fetchCanvasDataMock(...args),
+}));
+
+describe("EmbeddedCanvasRoute", () => {
+  beforeEach(() => {
+    fetchCanvasDataMock.mockReset();
+  });
+
+  it("renders a loading state while the request is in flight", async () => {
+    fetchCanvasDataMock.mockImplementationOnce(
+      () => new Promise(() => undefined) as Promise<unknown>
+    );
+
+    render(
+      <MemoryRouter
+        initialEntries={[
+          "/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc",
+        ]}
+      >
+        <Routes>
+          <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+        </Routes>
+      </MemoryRouter>
+    );
+
+    expect(screen.getByText("Loading canvas...")).toBeInTheDocument();
+  });
+
+  it("renders architecture canvas data", async () => {
+    fetchCanvasDataMock.mockResolvedValueOnce({
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      title: "Runtime Flow",
+      kind: "architecture_canvas",
+      renderStatus: "ready",
+      lastError: null,
+      compiledDocument: {
+        kind: "architecture_canvas",
+        title: "Runtime Flow",
+        summary: "How requests move.",
+        sections: [
+          {
+            type: "diagram",
+            nodes: [{ id: "WebUI", label: "WebUI" }],
+            edges: [{ from: "WebUI", to: "Server" }],
+          },
+          {
+            type: "annotations",
+            items: [{ title: "Boundary", body: "Server owns execution." }],
+          },
+        ],
+      },
+    });
+
+    render(
+      <MemoryRouter
+        initialEntries={[
+          "/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Fruntime-flow.csc",
+        ]}
+      >
+        <Routes>
+          <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+        </Routes>
+      </MemoryRouter>
+    );
+
+    expect(await screen.findByText("Runtime Flow")).toBeInTheDocument();
+    expect(screen.getByText("Canvas Renderer")).toBeInTheDocument();
+    expect(screen.getByText("WebUI")).toBeInTheDocument();
+    expect(screen.getByText("Boundary")).toBeInTheDocument();
+    expect(fetchCanvasDataMock).toHaveBeenCalledWith(
+      "ws-1",
+      ".coder-studio/canvases/runtime-flow.csc"
+    );
+  });
+
+  it("renders report canvas data", async () => {
+    fetchCanvasDataMock.mockResolvedValueOnce({
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/audit.csc",
+      title: "Audit",
+      kind: "report_canvas",
+      renderStatus: "ready",
+      lastError: null,
+      compiledDocument: {
+        kind: "report_canvas",
+        title: "Audit",
+        sections: [
+          {
+            type: "stats",
+            items: [{ label: "Packages", value: "6", tone: "neutral" }],
+          },
+          {
+            type: "section",
+            title: "Key Findings",
+            blocks: [{ type: "list", items: ["Server owns rendering."] }],
+          },
+        ],
+      },
+    });
+
+    render(
+      <MemoryRouter
+        initialEntries={["/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Faudit.csc"]}
+      >
+        <Routes>
+          <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+        </Routes>
+      </MemoryRouter>
+    );
+
+    expect(await screen.findByText("Key Findings")).toBeInTheDocument();
+    expect(screen.getByText("Packages")).toBeInTheDocument();
+    expect(screen.getByText("Server owns rendering.")).toBeInTheDocument();
+  });
+
+  it("renders canvas error state when renderStatus is error", async () => {
+    fetchCanvasDataMock.mockResolvedValueOnce({
+      workspaceId: "ws-1",
+      sourcePath: ".coder-studio/canvases/broken-canvas.csc",
+      title: "Broken Canvas",
+      kind: "architecture_canvas",
+      renderStatus: "error",
+      lastError: {
+        category: "compile_error",
+        message: "Missing node referenced by edge: Missing",
+      },
+    });
+
+    render(
+      <MemoryRouter
+        initialEntries={[
+          "/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Fbroken-canvas.csc",
+        ]}
+      >
+        <Routes>
+          <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+        </Routes>
+      </MemoryRouter>
+    );
+
+    expect(await screen.findByText("Render failed")).toBeInTheDocument();
+    expect(screen.getByText("Missing node referenced by edge: Missing")).toBeInTheDocument();
+  });
+
+  it("renders request errors", async () => {
+    fetchCanvasDataMock.mockRejectedValueOnce(new Error("canvas_request_failed:404"));
+
+    render(
+      <MemoryRouter
+        initialEntries={[
+          "/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Fmissing-flow.csc",
+        ]}
+      >
+        <Routes>
+          <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+        </Routes>
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("canvas_request_failed:404")).toBeInTheDocument();
+    });
+  });
+
+  it("renders invalid payload errors", async () => {
+    fetchCanvasDataMock.mockRejectedValueOnce(new Error("canvas_response_invalid"));
+
+    render(
+      <MemoryRouter
+        initialEntries={[
+          "/embedded/canvas/ws-1?sourcePath=.coder-studio%2Fcanvases%2Finvalid-flow.csc",
+        ]}
+      >
+        <Routes>
+          <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+        </Routes>
+      </MemoryRouter>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("canvas_response_invalid")).toBeInTheDocument();
+    });
+  });
+
+  it("renders a missing-param error when sourcePath is absent", async () => {
+    render(
+      <MemoryRouter initialEntries={["/embedded/canvas/ws-1"]}>
+        <Routes>
+          <Route path="/embedded/canvas/:workspaceId" element={<EmbeddedCanvasRoute />} />
+        </Routes>
+      </MemoryRouter>
+    );
+
+    expect(
+      await screen.findByText("Canvas route is missing workspace or source path.")
+    ).toBeInTheDocument();
+    expect(fetchCanvasDataMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/web/src/features/canvas/routes/embedded-canvas-route.tsx b/packages/web/src/features/canvas/routes/embedded-canvas-route.tsx
new file mode 100644
index 000000000..1f7390943
--- /dev/null
+++ b/packages/web/src/features/canvas/routes/embedded-canvas-route.tsx
@@ -0,0 +1,22 @@
+import { useParams, useSearchParams } from "react-router-dom";
+import { CanvasContent } from "../components/canvas-content";
+
+export function EmbeddedCanvasRoute() {
+  const { workspaceId } = useParams<{ workspaceId: string }>();
+  const [searchParams] = useSearchParams();
+  const sourcePath = searchParams.get("sourcePath") ?? "";
+  const refreshToken = Number.parseInt(searchParams.get("refresh") ?? "0", 10);
+
+  if (!workspaceId || !sourcePath) {
+    return <CanvasContent workspaceId={workspaceId ?? ""} sourcePath={sourcePath} layout="page" />;
+  }
+
+  return (
+    <CanvasContent
+      workspaceId={workspaceId}
+      sourcePath={sourcePath}
+      refreshToken={Number.isFinite(refreshToken) ? refreshToken : 0}
+      layout="page"
+    />
+  );
+}
diff --git a/packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx b/packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx
index 66a383f52..c38debb5d 100644
--- a/packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx
+++ b/packages/web/src/features/code-editor/actions/use-code-editor-actions.browser-tabs.test.tsx
@@ -1,4 +1,4 @@
-import { act, renderHook } from "@testing-library/react";
+import { act, renderHook, waitFor } from "@testing-library/react";
 import { createStore, Provider } from "jotai";
 import type { PropsWithChildren } from "react";
 import { describe, expect, it, vi } from "vitest";
@@ -88,7 +88,16 @@ function setupStore() {
   return { store, sendCommand };
 }
 
-describe("useCodeEditorActions browser tabs", () => {
+describe("useCodeEditorActions non-file tabs", () => {
+  const canvasTab = {
+    kind: "canvas" as const,
+    id: "canvas:canvas-1",
+    canvasId: "canvas-1",
+    title: "Runtime Flow",
+    artifactType: "architecture_canvas" as const,
+    sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+  };
+
   it("openBrowserTab uses the latest tab state across back-to-back calls before rerender", async () => {
     const { store } = setupStore();
     const { result } = renderHook(() => useCodeEditorActions(), {
@@ -115,6 +124,375 @@ describe("useCodeEditorActions browser tabs", () => {
     expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual(browserTabs[1]);
   });
 
+  it("pins an active preview file tab when the user edits it", async () => {
+    const { store } = setupStore();
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/app.ts", pinned: false },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-1"), {
+      kind: "file",
+      path: "src/app.ts",
+      pinned: false,
+    });
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.handleContentChange("export const app = 2;\n");
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      { kind: "file", path: "src/app.ts", pinned: true },
+    ]);
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+      kind: "file",
+      path: "src/app.ts",
+      pinned: true,
+    });
+    expect(store.get(openEditorPathsAtomFamily("ws-1"))).toEqual(["src/app.ts"]);
+  });
+
+  it("returns preview file tab metadata to the editor header", () => {
+    const { store } = setupStore();
+    store.set(openEditorPathsAtomFamily("ws-1"), []);
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/app.ts", pinned: false },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-1"), {
+      kind: "file",
+      path: "src/app.ts",
+      pinned: false,
+    });
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.openEditorTabs).toEqual([
+      { kind: "file", path: "src/app.ts", pinned: false },
+    ]);
+  });
+
+  it("syncs the active file tab from open preview tab metadata", async () => {
+    const { store } = setupStore();
+    store.set(openEditorPathsAtomFamily("ws-1"), []);
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/app.ts", pinned: false },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-1"), {
+      kind: "file",
+      path: "src/app.ts",
+      pinned: true,
+    });
+
+    renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await waitFor(() => {
+      expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+        kind: "file",
+        path: "src/app.ts",
+        pinned: false,
+      });
+    });
+  });
+
+  it("does not pin an active file tab when it is not in persistent open editor paths", async () => {
+    const { store } = setupStore();
+    store.set(openEditorPathsAtomFamily("ws-1"), []);
+    store.set(openEditorTabsAtomFamily("ws-1"), []);
+    store.set(activeEditorTabAtomFamily("ws-1"), null);
+
+    renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await waitFor(() => {
+      expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+        kind: "file",
+        path: "src/app.ts",
+        pinned: false,
+      });
+    });
+  });
+
+  it("returns an active preview fallback tab as unpinned when it is not persisted open", () => {
+    const { store } = setupStore();
+    store.set(openEditorPathsAtomFamily("ws-1"), []);
+    store.set(openEditorTabsAtomFamily("ws-1"), []);
+    store.set(activeEditorTabAtomFamily("ws-1"), {
+      kind: "file",
+      path: "src/app.ts",
+      pinned: false,
+    });
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.openEditorTabs).toEqual([
+      { kind: "file", path: "src/app.ts", pinned: false },
+    ]);
+  });
+
+  it("keeps a preview file tab open when requested from the tab menu", async () => {
+    const { store } = setupStore();
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/app.ts", pinned: false },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-1"), {
+      kind: "file",
+      path: "src/app.ts",
+      pinned: false,
+    });
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.keepOpenEditorTab({ kind: "file", path: "src/app.ts", pinned: false });
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      { kind: "file", path: "src/app.ts", pinned: true },
+    ]);
+    expect(store.get(openEditorPathsAtomFamily("ws-1"))).toEqual(["src/app.ts"]);
+  });
+
+  it("closes saved file tabs while keeping dirty file tabs", async () => {
+    const { store } = setupStore();
+    store.set(activeFilePathAtomFamily("ws-1"), "src/dirty.ts");
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/app.ts", pinned: true },
+      { kind: "file", path: "src/dirty.ts", pinned: true },
+    ]);
+    store.set(openEditorPathsAtomFamily("ws-1"), ["src/app.ts", "src/dirty.ts"]);
+    store.set(openFilesAtomFamily("ws-1"), {
+      "src/app.ts": {
+        kind: "text",
+        path: "src/app.ts",
+        content: "a",
+        savedContent: "a",
+        baseHash: "hash-app",
+        isDirty: false,
+      },
+      "src/dirty.ts": {
+        kind: "text",
+        path: "src/dirty.ts",
+        content: "changed",
+        savedContent: "saved",
+        baseHash: "hash-dirty",
+        isDirty: true,
+      },
+    });
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.closeSavedEditorTabs();
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      { kind: "file", path: "src/dirty.ts", pinned: true },
+    ]);
+    expect(store.get(openEditorPathsAtomFamily("ws-1"))).toEqual(["src/dirty.ts"]);
+    expect(store.get(openFilesAtomFamily("ws-1"))).toHaveProperty("src/dirty.ts");
+    expect(store.get(openFilesAtomFamily("ws-1"))).not.toHaveProperty("src/app.ts");
+  });
+
+  it("keeps dirty file tabs when closing all editor tabs", async () => {
+    const { store } = setupStore();
+    const browser = {
+      kind: "browser" as const,
+      id: "browser-1",
+      url: null,
+      devicePreset: "desktop" as const,
+      viewportWidth: null,
+      viewportHeight: null,
+      orientation: "portrait" as const,
+      userAgentMode: "desktop" as const,
+    };
+    store.set(activeFilePathAtomFamily("ws-1"), "src/dirty.ts");
+    store.set(activeEditorTabAtomFamily("ws-1"), {
+      kind: "file",
+      path: "src/dirty.ts",
+      pinned: true,
+    });
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/app.ts", pinned: true },
+      { kind: "file", path: "src/dirty.ts", pinned: true },
+      browser,
+    ]);
+    store.set(openEditorPathsAtomFamily("ws-1"), ["src/app.ts", "src/dirty.ts"]);
+    store.set(openFilesAtomFamily("ws-1"), {
+      "src/app.ts": {
+        kind: "text",
+        path: "src/app.ts",
+        content: "app",
+        savedContent: "app",
+        baseHash: "hash-app",
+        isDirty: false,
+      },
+      "src/dirty.ts": {
+        kind: "text",
+        path: "src/dirty.ts",
+        content: "changed",
+        savedContent: "saved",
+        baseHash: "hash-dirty",
+        isDirty: true,
+      },
+    });
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.closeAllEditorTabs();
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      { kind: "file", path: "src/dirty.ts", pinned: true },
+    ]);
+    expect(store.get(openEditorPathsAtomFamily("ws-1"))).toEqual(["src/dirty.ts"]);
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+      kind: "file",
+      path: "src/dirty.ts",
+      pinned: true,
+    });
+    expect(store.get(openFilesAtomFamily("ws-1"))).toEqual({
+      "src/dirty.ts": {
+        kind: "text",
+        path: "src/dirty.ts",
+        content: "changed",
+        savedContent: "saved",
+        baseHash: "hash-dirty",
+        isDirty: true,
+      },
+    });
+  });
+
+  it("closes editor tabs to the right of the target tab", async () => {
+    const { store } = setupStore();
+    const browser = {
+      kind: "browser" as const,
+      id: "browser-right",
+      url: null,
+      devicePreset: "desktop" as const,
+      viewportWidth: null,
+      viewportHeight: null,
+      orientation: "portrait" as const,
+      userAgentMode: "desktop" as const,
+    };
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/app.ts", pinned: true },
+      { kind: "file", path: "src/right.ts", pinned: true },
+      browser,
+    ]);
+    store.set(openEditorPathsAtomFamily("ws-1"), ["src/app.ts", "src/right.ts"]);
+    store.set(openFilesAtomFamily("ws-1"), {
+      "src/app.ts": {
+        kind: "text",
+        path: "src/app.ts",
+        content: "app",
+        savedContent: "app",
+        baseHash: "hash-app",
+        isDirty: false,
+      },
+      "src/right.ts": {
+        kind: "text",
+        path: "src/right.ts",
+        content: "right",
+        savedContent: "right",
+        baseHash: "hash-right",
+        isDirty: false,
+      },
+    });
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.closeEditorTabsToRight({ kind: "file", path: "src/app.ts", pinned: true });
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      { kind: "file", path: "src/app.ts", pinned: true },
+    ]);
+    expect(store.get(openEditorPathsAtomFamily("ws-1"))).toEqual(["src/app.ts"]);
+  });
+
+  it("keeps dirty file tabs when closing editor tabs to the right", async () => {
+    const { store } = setupStore();
+    const browser = {
+      kind: "browser" as const,
+      id: "browser-right",
+      url: null,
+      devicePreset: "desktop" as const,
+      viewportWidth: null,
+      viewportHeight: null,
+      orientation: "portrait" as const,
+      userAgentMode: "desktop" as const,
+    };
+    store.set(activeFilePathAtomFamily("ws-1"), "src/app.ts");
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/app.ts", pinned: true },
+      { kind: "file", path: "src/dirty.ts", pinned: true },
+      { kind: "file", path: "src/right.ts", pinned: true },
+      browser,
+    ]);
+    store.set(openEditorPathsAtomFamily("ws-1"), ["src/app.ts", "src/dirty.ts", "src/right.ts"]);
+    store.set(openFilesAtomFamily("ws-1"), {
+      "src/app.ts": {
+        kind: "text",
+        path: "src/app.ts",
+        content: "app",
+        savedContent: "app",
+        baseHash: "hash-app",
+        isDirty: false,
+      },
+      "src/dirty.ts": {
+        kind: "text",
+        path: "src/dirty.ts",
+        content: "changed",
+        savedContent: "saved",
+        baseHash: "hash-dirty",
+        isDirty: true,
+      },
+      "src/right.ts": {
+        kind: "text",
+        path: "src/right.ts",
+        content: "right",
+        savedContent: "right",
+        baseHash: "hash-right",
+        isDirty: false,
+      },
+    });
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.closeEditorTabsToRight({ kind: "file", path: "src/app.ts", pinned: true });
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      { kind: "file", path: "src/app.ts", pinned: true },
+      { kind: "file", path: "src/dirty.ts", pinned: true },
+    ]);
+    expect(store.get(openEditorPathsAtomFamily("ws-1"))).toEqual(["src/app.ts", "src/dirty.ts"]);
+    expect(store.get(openFilesAtomFamily("ws-1"))).toHaveProperty("src/dirty.ts");
+    expect(store.get(openFilesAtomFamily("ws-1"))).not.toHaveProperty("src/right.ts");
+  });
+
   it("openBrowserTab opens a new browser tab every time with unique ids and activates the latest tab", async () => {
     const { store } = setupStore();
     const { result } = renderHook(() => useCodeEditorActions(), {
@@ -199,6 +577,262 @@ describe("useCodeEditorActions browser tabs", () => {
     });
   });
 
+  it("returns canvas tabs and allows activating and closing them like other non-file tabs", async () => {
+    const { store } = setupStore();
+    const browser = {
+      kind: "browser" as const,
+      id: "browser-1",
+      url: "localhost:8001",
+      devicePreset: "desktop" as const,
+      viewportWidth: null,
+      viewportHeight: null,
+      orientation: "portrait" as const,
+      userAgentMode: "desktop" as const,
+    };
+
+    store.set(openEditorTabsAtomFamily("ws-1"), [canvasTab, browser]);
+    store.set(activeEditorTabAtomFamily("ws-1"), browser);
+    store.set(editorViewVisibleAtomFamily("ws-1"), true);
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    expect(result.current.openEditorTabs).toEqual([
+      { kind: "file", path: "src/app.ts", pinned: true },
+      canvasTab,
+      browser,
+    ]);
+
+    await act(async () => {
+      result.current.activateEditorTab(canvasTab);
+    });
+
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual(canvasTab);
+
+    await act(async () => {
+      result.current.closeEditorTab(canvasTab);
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([browser]);
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual(browser);
+  });
+
+  it("closes only the matching source-path-first canvas tab when canvasId is absent", async () => {
+    const { store } = setupStore();
+    const firstCanvas = {
+      kind: "canvas" as const,
+      id: "canvas:.coder-studio/canvases/auth-gate.csc",
+      title: "auth-gate",
+      sourcePath: ".coder-studio/canvases/auth-gate.csc",
+    };
+    const secondCanvas = {
+      kind: "canvas" as const,
+      id: "canvas:.coder-studio/canvases/billing.csc",
+      title: "billing",
+      sourcePath: ".coder-studio/canvases/billing.csc",
+    };
+
+    store.set(openEditorTabsAtomFamily("ws-1"), [firstCanvas, secondCanvas]);
+    store.set(activeEditorTabAtomFamily("ws-1"), secondCanvas);
+    store.set(editorViewVisibleAtomFamily("ws-1"), true);
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.closeEditorTab(firstCanvas);
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([secondCanvas]);
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual(secondCanvas);
+  });
+
+  it("switches a .csc source file into a canvas tab when preview mode is requested", async () => {
+    const { store } = setupStore();
+    store.set(activeFilePathAtomFamily("ws-1"), ".coder-studio/canvases/auth-gate.csc");
+    store.set(openEditorPathsAtomFamily("ws-1"), [".coder-studio/canvases/auth-gate.csc"]);
+    store.set(openFilesAtomFamily("ws-1"), {
+      ".coder-studio/canvases/auth-gate.csc": {
+        kind: "text",
+        path: ".coder-studio/canvases/auth-gate.csc",
+        content: '{"kind":"architecture_canvas"}',
+        savedContent: '{"kind":"architecture_canvas"}',
+        baseHash: "hash-canvas",
+        isDirty: false,
+      },
+    });
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.setMode("preview");
+    });
+
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/auth-gate.csc",
+      title: "auth-gate",
+      sourcePath: ".coder-studio/canvases/auth-gate.csc",
+      artifactType: "architecture_canvas",
+      canvasId: ".coder-studio/canvases/auth-gate.csc",
+    });
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/auth-gate.csc",
+        title: "auth-gate",
+        sourcePath: ".coder-studio/canvases/auth-gate.csc",
+        artifactType: "architecture_canvas",
+        canvasId: ".coder-studio/canvases/auth-gate.csc",
+      },
+    ]);
+    expect(result.current.mode).toBe("preview");
+  });
+
+  it("refreshes legacy .csc canvas tab metadata when preview mode is requested again", async () => {
+    const { store } = setupStore();
+    store.set(activeFilePathAtomFamily("ws-1"), ".coder-studio/canvases/auth-gate.csc");
+    store.set(openEditorPathsAtomFamily("ws-1"), [".coder-studio/canvases/auth-gate.csc"]);
+    store.set(openFilesAtomFamily("ws-1"), {
+      ".coder-studio/canvases/auth-gate.csc": {
+        kind: "text",
+        path: ".coder-studio/canvases/auth-gate.csc",
+        content: '{"kind":"report_canvas"}',
+        savedContent: '{"kind":"report_canvas"}',
+        baseHash: "hash-canvas",
+        isDirty: false,
+      },
+    });
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/auth-gate.csc",
+        title: "auth-gate",
+        sourcePath: ".coder-studio/canvases/auth-gate.csc",
+        artifactType: "architecture_canvas",
+      },
+    ]);
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.setMode("preview");
+    });
+
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toMatchObject({
+      kind: "canvas",
+      sourcePath: ".coder-studio/canvases/auth-gate.csc",
+      artifactType: "report_canvas",
+      canvasId: ".coder-studio/canvases/auth-gate.csc",
+    });
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      expect.objectContaining({
+        kind: "canvas",
+        sourcePath: ".coder-studio/canvases/auth-gate.csc",
+        artifactType: "report_canvas",
+        canvasId: ".coder-studio/canvases/auth-gate.csc",
+      }),
+    ]);
+  });
+
+  it("switches an active canvas tab back to its source file when edit mode is requested", async () => {
+    const { store } = setupStore();
+    store.set(activeFilePathAtomFamily("ws-1"), null);
+    store.set(openEditorPathsAtomFamily("ws-1"), []);
+    store.set(openFilesAtomFamily("ws-1"), {
+      ".coder-studio/canvases/auth-gate.csc": {
+        kind: "text",
+        path: ".coder-studio/canvases/auth-gate.csc",
+        content: '{"kind":"architecture_canvas"}',
+        savedContent: '{"kind":"architecture_canvas"}',
+        baseHash: "hash-canvas",
+        isDirty: false,
+      },
+    });
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/auth-gate.csc",
+        title: "auth-gate",
+        sourcePath: ".coder-studio/canvases/auth-gate.csc",
+      },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-1"), {
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/auth-gate.csc",
+      title: "auth-gate",
+      sourcePath: ".coder-studio/canvases/auth-gate.csc",
+    });
+    store.set(editorViewVisibleAtomFamily("ws-1"), true);
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      result.current.setMode("edit");
+    });
+
+    expect(store.get(activeFilePathAtomFamily("ws-1"))).toBe(
+      ".coder-studio/canvases/auth-gate.csc"
+    );
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+      kind: "file",
+      path: ".coder-studio/canvases/auth-gate.csc",
+      pinned: true,
+    });
+    expect(result.current.mode).toBe("edit");
+  });
+
+  it("hideEditorView persists a hidden global editor when the active tab is a browser tab", async () => {
+    const { store, sendCommand } = setupStore();
+    store.set(activeFilePathAtomFamily("ws-1"), null);
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "browser", id: "browser-1", url: "localhost:8001" },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-1"), {
+      kind: "browser",
+      id: "browser-1",
+      url: "localhost:8001",
+    });
+    store.set(editorViewVisibleAtomFamily("ws-1"), true);
+
+    const { result } = renderHook(() => useCodeEditorActions(), {
+      wrapper: createWrapper(store),
+    });
+
+    await act(async () => {
+      await result.current.hideEditorView();
+    });
+
+    expect(store.get(editorViewVisibleAtomFamily("ws-1"))).toBe(false);
+    expect(store.get(activeFilePathAtomFamily("ws-1"))).toBeNull();
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledTimes(1);
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "workspace.uiState.set",
+      expect.objectContaining({
+        workspaceId: "ws-1",
+        uiState: expect.objectContaining({
+          editorViewVisible: false,
+          activeEditorPath: null,
+          openEditorTabs: [{ kind: "browser", id: "browser-1", url: "localhost:8001" }],
+          activeEditorTab: { kind: "browser", id: "browser-1", url: "localhost:8001" },
+        }),
+      }),
+      undefined
+    );
+  });
+
   it("keeps editor pane state on the pane file even when the global editor is on a browser tab", () => {
     const { store } = setupStore();
     const paneStateKey = getEditorPaneStateKey("ws-1", "pane-1");
@@ -231,7 +865,83 @@ describe("useCodeEditorActions browser tabs", () => {
     expect(result.current.activeEditorTab).toEqual({
       kind: "file",
       path: "src/app.ts",
+      pinned: true,
+    });
+    expect(result.current.openEditorTabs).toEqual([
+      { kind: "file", path: "src/app.ts", pinned: true },
+    ]);
+  });
+
+  it("switches a pane-local .csc file between source edit and canvas preview", async () => {
+    const { store } = setupStore();
+    const paneStateKey = getEditorPaneStateKey("ws-1", "pane-1");
+
+    store.set(
+      editorPaneActiveFilePathAtomFamily(paneStateKey),
+      ".coder-studio/canvases/auth-gate.csc"
+    );
+    store.set(editorPaneOpenEditorPathsAtomFamily(paneStateKey), [
+      ".coder-studio/canvases/auth-gate.csc",
+    ]);
+    store.set(openFilesAtomFamily("ws-1"), {
+      ".coder-studio/canvases/auth-gate.csc": {
+        kind: "text",
+        path: ".coder-studio/canvases/auth-gate.csc",
+        content: '{"kind":"architecture_canvas"}',
+        savedContent: '{"kind":"architecture_canvas"}',
+        baseHash: "hash-canvas",
+        isDirty: false,
+      },
+    });
+
+    const { result } = renderHook(
+      () =>
+        useCodeEditorActions({
+          activeFilePathAtom: editorPaneActiveFilePathAtomFamily(paneStateKey),
+          editorModeAtom: editorPaneModeAtomFamily(paneStateKey),
+          openEditorPathsAtom: editorPaneOpenEditorPathsAtomFamily(paneStateKey),
+          pendingNavigationAtom: editorPanePendingNavigationAtomFamily(paneStateKey),
+          persistEditorUiState: false,
+        }),
+      {
+        wrapper: createWrapper(store),
+      }
+    );
+
+    await act(async () => {
+      result.current.setMode("preview");
+    });
+
+    expect(result.current.activeEditorTab).toEqual({
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/auth-gate.csc",
+      title: "auth-gate",
+      sourcePath: ".coder-studio/canvases/auth-gate.csc",
+      artifactType: "architecture_canvas",
+      canvasId: ".coder-studio/canvases/auth-gate.csc",
+    });
+    expect(result.current.openEditorTabs).toEqual([
+      { kind: "file", path: ".coder-studio/canvases/auth-gate.csc", pinned: true },
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/auth-gate.csc",
+        title: "auth-gate",
+        sourcePath: ".coder-studio/canvases/auth-gate.csc",
+        artifactType: "architecture_canvas",
+        canvasId: ".coder-studio/canvases/auth-gate.csc",
+      },
+    ]);
+    expect(result.current.mode).toBe("preview");
+
+    await act(async () => {
+      result.current.setMode("edit");
+    });
+
+    expect(result.current.activeEditorTab).toEqual({
+      kind: "file",
+      path: ".coder-studio/canvases/auth-gate.csc",
+      pinned: true,
     });
-    expect(result.current.openEditorTabs).toEqual([{ kind: "file", path: "src/app.ts" }]);
+    expect(result.current.mode).toBe("edit");
   });
 });
diff --git a/packages/web/src/features/code-editor/actions/use-code-editor-actions.ts b/packages/web/src/features/code-editor/actions/use-code-editor-actions.ts
index 480726e4f..41bfb481a 100644
--- a/packages/web/src/features/code-editor/actions/use-code-editor-actions.ts
+++ b/packages/web/src/features/code-editor/actions/use-code-editor-actions.ts
@@ -15,6 +15,7 @@ import {
   activeEditorTabAtomFamily,
   activeFilePathAtomFamily,
   createWorkspaceBrowserEditorTab,
+  createWorkspaceCanvasEditorTabFromSourcePath,
   deriveDocumentPreviewKind,
   deriveEditorModeForOpenFile,
   deriveEditorModeForPath,
@@ -25,6 +26,7 @@ import {
   gitDiffPreviewAtomFamily,
   gitDiffPreviewDismissedAtomFamily,
   gitStateAtomFamily,
+  isCanvasSourcePath,
   type OpenFile,
   openEditorPathsAtomFamily,
   openEditorTabsAtomFamily,
@@ -34,6 +36,7 @@ import {
 } from "../../workspace/atoms";
 import { type PendingEditorNavigation, pendingEditorNavigationAtomFamily } from "../atoms";
 import { monacoModelRegistry } from "../monaco/model-registry";
+import { parseSkillEditorPath } from "../skill-editor-path";
 import { parseSystemAgentInstructionsEditorPath } from "../system-agent-instructions-path";
 import {
   beginPendingEditorLoad,
@@ -86,12 +89,30 @@ function toSystemFileReadPayload(document: AgentInstructionsSystemDocument): Edi
   };
 }
 
+function isSkillNotFoundError(error: { code?: string } | undefined): boolean {
+  return error?.code === "skill_not_found" || error?.code === "not_found";
+}
+
+function deriveEditorModeForResource(path: string, file?: OpenFile): WorkspaceEditorMode {
+  if (parseSkillEditorPath(path)) {
+    return "edit";
+  }
+
+  return file ? deriveEditorModeForOpenFile(file) : deriveEditorModeForPath(path);
+}
+
 function isBrowserEditorTab(
   tab: WorkspaceEditorTab
 ): tab is Extract<WorkspaceEditorTab, { kind: "browser" }> {
   return tab.kind === "browser";
 }
 
+function isCanvasEditorTab(
+  tab: WorkspaceEditorTab
+): tab is Extract<WorkspaceEditorTab, { kind: "canvas" }> {
+  return tab.kind === "canvas";
+}
+
 function isSameEditorTab(
   left: WorkspaceEditorTab | null | undefined,
   right: WorkspaceEditorTab
@@ -104,7 +125,44 @@ function isSameEditorTab(
     return left.id === right.id;
   }
 
-  return left.path === right.path;
+  if (left.kind === "canvas" && right.kind === "canvas") {
+    if (left.canvasId && right.canvasId) {
+      return left.canvasId === right.canvasId;
+    }
+
+    return left.sourcePath === right.sourcePath;
+  }
+
+  if (left.kind === "file" && right.kind === "file") {
+    return left.path === right.path;
+  }
+
+  return false;
+}
+
+type WorkspaceFileEditorTab = Extract<WorkspaceEditorTab, { kind: "file" }>;
+
+function findOpenFileEditorTab(
+  tabs: WorkspaceEditorTab[],
+  path: string
+): WorkspaceFileEditorTab | null {
+  return (
+    (tabs.find((tab) => tab.kind === "file" && tab.path === path) as
+      | WorkspaceFileEditorTab
+      | undefined) ?? null
+  );
+}
+
+function resolveFileEditorTab(
+  tabs: WorkspaceEditorTab[],
+  path: string,
+  fallbackPinned = false
+): WorkspaceFileEditorTab {
+  return findOpenFileEditorTab(tabs, path) ?? { kind: "file", path, pinned: fallbackPinned };
+}
+
+function isDirtyOpenFile(file: OpenFile | undefined): boolean {
+  return file?.kind === "text" && file.isDirty === true;
 }
 
 export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
@@ -149,6 +207,8 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
   const [globalActiveEditorTab, setActiveEditorTab] = useAtom(
     activeEditorTabAtomFamily(workspaceId ?? "")
   );
+  const [localOpenEditorTabs, setLocalOpenEditorTabs] = useState<WorkspaceEditorTab[]>([]);
+  const [localActiveEditorTab, setLocalActiveEditorTab] = useState<WorkspaceEditorTab | null>(null);
   const [mode, setMode] = useAtom(editorModeAtom);
   const setEditorViewVisible = useSetAtom(editorViewVisibleAtomFamily(workspaceId ?? ""));
   const editorRefreshToken = useAtomValue(editorRefreshTokenAtomFamily(workspaceId ?? ""));
@@ -187,25 +247,60 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
   const currentFile: OpenFile | undefined = workspaceId
     ? openFiles[activeFilePath ?? ""]
     : undefined;
+  const currentOpenEditorTabs = isGlobalEditorState ? openEditorTabs : localOpenEditorTabs;
+  const currentActiveEditorTab = isGlobalEditorState ? globalActiveEditorTab : localActiveEditorTab;
+  const activeCanvasEditorTab =
+    currentActiveEditorTab?.kind === "canvas" ? currentActiveEditorTab : null;
 
   useEffect(() => {
     if (!activeFilePath) {
+      if (!isGlobalEditorState && currentActiveEditorTab?.kind === "file") {
+        setLocalActiveEditorTab(null);
+      }
       return;
     }
 
     recordActivationPath(activeFilePath);
-    if (isGlobalEditorState) {
-      setActiveEditorTab({ kind: "file", path: activeFilePath });
+    const matchingOpenFileTab = findOpenFileEditorTab(currentOpenEditorTabs, activeFilePath);
+    const nextFileTab =
+      matchingOpenFileTab ??
+      ({
+        kind: "file",
+        path: activeFilePath,
+        pinned: openEditorPaths.includes(activeFilePath),
+      } as const);
+    const shouldSyncPaneActiveTabToFile =
+      !currentActiveEditorTab ||
+      (currentActiveEditorTab.kind === "file" && currentActiveEditorTab.path !== activeFilePath) ||
+      (currentActiveEditorTab.kind === "file" &&
+        matchingOpenFileTab !== null &&
+        currentActiveEditorTab.pinned !== matchingOpenFileTab.pinned) ||
+      (currentActiveEditorTab.kind === "canvas" &&
+        currentActiveEditorTab.sourcePath !== activeFilePath);
+    const shouldSyncGlobalActiveTabToFile =
+      !currentActiveEditorTab ||
+      (currentActiveEditorTab.kind === "file" && currentActiveEditorTab.path !== activeFilePath) ||
+      (currentActiveEditorTab.kind === "file" &&
+        matchingOpenFileTab !== null &&
+        currentActiveEditorTab.pinned !== matchingOpenFileTab.pinned);
+    if (isGlobalEditorState && shouldSyncGlobalActiveTabToFile) {
+      setActiveEditorTab(nextFileTab);
+    } else if (!isGlobalEditorState && shouldSyncPaneActiveTabToFile) {
+      setLocalActiveEditorTab(nextFileTab);
     }
     if (isGlobalEditorState && workspaceId) {
       setEditorViewVisible(true);
     }
   }, [
     activeFilePath,
+    currentActiveEditorTab,
+    currentOpenEditorTabs,
     isGlobalEditorState,
+    openEditorPaths,
     recordActivationPath,
     setActiveEditorTab,
     setEditorViewVisible,
+    setLocalActiveEditorTab,
     workspaceId,
   ]);
 
@@ -225,7 +320,9 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
       (diffPreview?.kind === "worktree-file-diff" ||
         diffPreview?.kind === "search-replace-file-diff") &&
       diffPreview.path === activeFilePath;
-    const nextMode = shouldPreserveDiffMode ? "diff" : deriveEditorModeForOpenFile(currentFile);
+    const nextMode = shouldPreserveDiffMode
+      ? "diff"
+      : deriveEditorModeForResource(activeFilePath, currentFile);
     if (nextMode !== mode) {
       setMode(nextMode);
     }
@@ -238,12 +335,12 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
   }, [activeFilePath]);
 
   useEffect(() => {
-    openEditorTabsRef.current = openEditorTabs;
-  }, [openEditorTabs]);
+    openEditorTabsRef.current = currentOpenEditorTabs;
+  }, [currentOpenEditorTabs]);
 
   useEffect(() => {
-    activeEditorTabRef.current = globalActiveEditorTab;
-  }, [globalActiveEditorTab]);
+    activeEditorTabRef.current = currentActiveEditorTab;
+  }, [currentActiveEditorTab]);
 
   const invalidateSaveStateForPaths = useCallback((paths: string[]) => {
     if (paths.length === 0) {
@@ -308,15 +405,21 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
       const requestId = beginPendingEditorLoad(workspaceId, path);
       setFileLoadError((current) => (current?.path === path ? null : current));
       const systemProviderId = parseSystemAgentInstructionsEditorPath(path);
+      const skillPath = parseSkillEditorPath(path);
       const result = systemProviderId
         ? await dispatch<AgentInstructionsSystemDocument>("agentInstructions.system.read", {
             workspaceId,
             providerId: systemProviderId,
           })
-        : await dispatch<FileReadPayload>("file.read", {
-            workspaceId,
-            path,
-          });
+        : skillPath
+          ? await dispatch<EditorReadPayload>("skills.files.read", {
+              skillSlug: skillPath.skillSlug,
+              path: skillPath.relativePath,
+            })
+          : await dispatch<FileReadPayload>("file.read", {
+              workspaceId,
+              path,
+            });
 
       if (shouldIgnorePendingEditorLoadResult(workspaceId, path, requestId)) {
         return;
@@ -366,7 +469,7 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
 
           finishPendingEditorLoad(workspaceId, path, requestId);
           setOpenFiles((prev) => ({ ...prev, [path]: newFile }));
-          if (workspaceRootPath && !systemProviderId) {
+          if (workspaceRootPath && !systemProviderId && !skillPath) {
             monacoModelRegistry.updateFromDisk({
               workspaceRootPath,
               path,
@@ -410,7 +513,7 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
 
       finishPendingEditorLoad(workspaceId, path, requestId);
       setOpenFiles((prev) => ({ ...prev, [path]: newFile }));
-      if (workspaceRootPath && data.kind === "text" && !systemProviderId) {
+      if (workspaceRootPath && data.kind === "text" && !systemProviderId && !skillPath) {
         monacoModelRegistry.updateFromDisk({
           workspaceRootPath,
           path,
@@ -435,6 +538,53 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
     [t]
   );
 
+  const pinFileEditorTab = useCallback(
+    (path: string) => {
+      const pinnedTab = { kind: "file" as const, path, pinned: true };
+      const currentOpenEditorTabs = openEditorTabsRef.current;
+      const nextOpenEditorTabs = currentOpenEditorTabs.some(
+        (tab) => tab.kind === "file" && tab.path === path
+      )
+        ? currentOpenEditorTabs.map((tab) =>
+            tab.kind === "file" && tab.path === path ? pinnedTab : tab
+          )
+        : [...currentOpenEditorTabs, pinnedTab];
+
+      openEditorTabsRef.current = nextOpenEditorTabs;
+      activeEditorTabRef.current = pinnedTab;
+
+      if (isGlobalEditorState) {
+        setOpenEditorTabs(nextOpenEditorTabs);
+        setActiveEditorTab(pinnedTab);
+        const nextOpenEditorPaths = mergeOpenEditorPaths(openEditorPaths, [path]);
+        setOpenEditorPaths(nextOpenEditorPaths);
+        if (shouldPersistEditorUiState) {
+          void persistUiState({
+            openEditorPaths: nextOpenEditorPaths,
+            openEditorTabs: nextOpenEditorTabs,
+            activeEditorTab: pinnedTab,
+            activeEditorPath: path,
+          });
+        }
+        return;
+      }
+
+      setLocalOpenEditorTabs(nextOpenEditorTabs);
+      setLocalActiveEditorTab(pinnedTab);
+    },
+    [
+      isGlobalEditorState,
+      openEditorPaths,
+      persistUiState,
+      setActiveEditorTab,
+      setLocalActiveEditorTab,
+      setLocalOpenEditorTabs,
+      setOpenEditorPaths,
+      setOpenEditorTabs,
+      shouldPersistEditorUiState,
+    ]
+  );
+
   const handleSave = useCallback(async () => {
     if (!workspaceId || !currentFile || currentFile.kind !== "text") {
       return;
@@ -454,6 +604,7 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
     setSaveError((current) => (current?.path === path ? null : current));
 
     const systemProviderId = parseSystemAgentInstructionsEditorPath(path);
+    const skillPath = parseSkillEditorPath(path);
     const result = systemProviderId
       ? await dispatch<AgentInstructionsSystemDocument>("agentInstructions.system.write", {
           workspaceId,
@@ -461,12 +612,19 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
           content,
           baseHash: baseHash || undefined,
         })
-      : await dispatch<{ newHash: string }>("file.write", {
-          workspaceId,
-          path,
-          content,
-          baseHash: baseHash || undefined,
-        });
+      : skillPath
+        ? await dispatch<{ newHash: string }>("skills.files.write", {
+            skillSlug: skillPath.skillSlug,
+            path: skillPath.relativePath,
+            content,
+            baseHash: baseHash || undefined,
+          })
+        : await dispatch<{ newHash: string }>("file.write", {
+            workspaceId,
+            path,
+            content,
+            baseHash: baseHash || undefined,
+          });
 
     if (activeSaveRequestIdByPathRef.current.get(path) !== requestId) {
       return;
@@ -531,8 +689,13 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
           },
         };
       });
+
+      const activeTab = activeEditorTabRef.current;
+      if (activeTab?.kind === "file" && activeTab.path === currentFile.path) {
+        pinFileEditorTab(currentFile.path);
+      }
     },
-    [currentFile, setOpenFiles, workspaceId]
+    [currentFile, pinFileEditorTab, setOpenFiles, workspaceId]
   );
 
   useEffect(() => {
@@ -566,15 +729,21 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
     const reconcileOpenFiles = async () => {
       for (const [path, file] of entries) {
         const systemProviderId = parseSystemAgentInstructionsEditorPath(path);
+        const skillPath = parseSkillEditorPath(path);
         const result = systemProviderId
           ? await dispatch<AgentInstructionsSystemDocument>("agentInstructions.system.read", {
               workspaceId,
               providerId: systemProviderId,
             })
-          : await dispatch<FileReadPayload>("file.read", {
-              workspaceId,
-              path,
-            });
+          : skillPath
+            ? await dispatch<EditorReadPayload>("skills.files.read", {
+                skillSlug: skillPath.skillSlug,
+                path: skillPath.relativePath,
+              })
+            : await dispatch<FileReadPayload>("file.read", {
+                workspaceId,
+                path,
+              });
 
         if (cancelled) {
           return;
@@ -584,7 +753,11 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
           ? (result.data as AgentInstructionsSystemDocument | undefined)
           : undefined;
         if (!result.ok || !result.data || (systemDocument && !systemDocument.exists)) {
-          const isMissing = systemDocument ? true : result.error?.code === "not_found";
+          const isMissing = systemDocument
+            ? true
+            : skillPath
+              ? isSkillNotFoundError(result.error)
+              : result.error?.code === "not_found";
           setOpenFiles((prev) => {
             const existing = prev[path];
             if (!existing) {
@@ -648,7 +821,7 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
               viewingTextBackedImageAsText: file.viewingTextBackedImageAsText,
             },
           }));
-          if (workspaceRootPath && !systemProviderId) {
+          if (workspaceRootPath && !systemProviderId && !skillPath) {
             monacoModelRegistry.updateFromDisk({
               workspaceRootPath,
               path,
@@ -852,6 +1025,10 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
         setActiveEditorTab((current) =>
           current?.kind === "file" && current.path === path ? null : current
         );
+      } else {
+        setLocalActiveEditorTab((current) =>
+          current?.kind === "file" && current.path === path ? null : current
+        );
       }
       setSaveError((current) => (current?.path === path ? null : current));
     },
@@ -860,6 +1037,7 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
       isGlobalEditorState,
       setActiveEditorTab,
       setEditorViewVisible,
+      setLocalActiveEditorTab,
       setOpenEditorTabs,
       setSaveError,
       workspaceId,
@@ -876,6 +1054,12 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
       setActiveFilePath(null);
       setMode("edit");
       setSaveError(null);
+      if (shouldPersistEditorUiState) {
+        void persistUiState({
+          activeEditorPath: null,
+          editorViewVisible: false,
+        });
+      }
       return;
     }
 
@@ -893,6 +1077,7 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
       void persistUiState({
         openEditorPaths: nextOpenEditorPaths,
         activeEditorPath: null,
+        editorViewVisible: false,
       });
     }
   }, [
@@ -1039,25 +1224,34 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
   );
 
   const activateOpenFile = useCallback(
-    (path: string) => {
+    (path: string, options: { pinned?: boolean } = {}) => {
       if (!workspaceId) {
         return;
       }
 
       recordActivationPath(path);
+      const nextFileTab = resolveFileEditorTab(
+        openEditorTabsRef.current,
+        path,
+        options.pinned ?? openEditorPaths.includes(path)
+      );
       if (isGlobalEditorState) {
         setEditorViewVisible(true);
-        setActiveEditorTab({ kind: "file", path });
+        setActiveEditorTab(nextFileTab);
+      } else {
+        setLocalActiveEditorTab(nextFileTab);
       }
 
+      const nextFile = openFiles[path];
+      const nextMode = deriveEditorModeForResource(path, nextFile);
+
       if (path === activeFilePath) {
+        if (nextMode !== mode) {
+          setMode(nextMode);
+        }
         return;
       }
 
-      const nextFile = openFiles[path];
-      const nextMode = nextFile
-        ? deriveEditorModeForOpenFile(nextFile)
-        : deriveEditorModeForPath(path);
       setActiveFilePath(path);
       if (nextMode !== mode) {
         setMode(nextMode);
@@ -1072,12 +1266,14 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
       activeFilePath,
       isGlobalEditorState,
       mode,
+      openEditorPaths,
       openFiles,
       persistUiState,
       recordActivationPath,
       setActiveFilePath,
       setActiveEditorTab,
       setEditorViewVisible,
+      setLocalActiveEditorTab,
       setMode,
       shouldPersistEditorUiState,
       workspaceId,
@@ -1113,6 +1309,61 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
     workspaceId,
   ]);
 
+  const activateCanvasPreviewForSourcePath = useCallback(
+    (sourcePath: string) => {
+      if (!workspaceId || !isCanvasSourcePath(sourcePath)) {
+        return false;
+      }
+
+      const currentOpenEditorTabs = openEditorTabsRef.current;
+      const existingCanvasTab = currentOpenEditorTabs.find(
+        (tab): tab is Extract<WorkspaceEditorTab, { kind: "canvas" }> =>
+          tab.kind === "canvas" && tab.sourcePath === sourcePath
+      );
+      const nextCanvasTab = createWorkspaceCanvasEditorTabFromSourcePath({
+        sourcePath,
+        file: openFiles[sourcePath],
+        existingTab: existingCanvasTab,
+      });
+      const nextOpenEditorTabs = existingCanvasTab
+        ? currentOpenEditorTabs.map((tab) => (tab === existingCanvasTab ? nextCanvasTab : tab))
+        : [...currentOpenEditorTabs, nextCanvasTab];
+
+      openEditorTabsRef.current = nextOpenEditorTabs;
+      activeEditorTabRef.current = nextCanvasTab;
+      if (isGlobalEditorState) {
+        setEditorViewVisible(true);
+        setOpenEditorTabs(nextOpenEditorTabs);
+        setActiveEditorTab(nextCanvasTab);
+      } else {
+        setLocalOpenEditorTabs(nextOpenEditorTabs);
+        setLocalActiveEditorTab(nextCanvasTab);
+      }
+      setMode("preview");
+      if (isGlobalEditorState && shouldPersistEditorUiState) {
+        void persistUiState({
+          editorViewVisible: true,
+          openEditorTabs: nextOpenEditorTabs,
+          activeEditorTab: nextCanvasTab,
+        });
+      }
+      return true;
+    },
+    [
+      isGlobalEditorState,
+      persistUiState,
+      setActiveEditorTab,
+      setEditorViewVisible,
+      setLocalActiveEditorTab,
+      setLocalOpenEditorTabs,
+      setMode,
+      setOpenEditorTabs,
+      openFiles,
+      shouldPersistEditorUiState,
+      workspaceId,
+    ]
+  );
+
   const activateEditorTab = useCallback(
     (tab: WorkspaceEditorTab) => {
       if (tab.kind === "browser") {
@@ -1133,6 +1384,30 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
         return;
       }
 
+      if (tab.kind === "canvas") {
+        if (!workspaceId) {
+          return;
+        }
+
+        if (isGlobalEditorState) {
+          const currentOpenEditorTabs = openEditorTabsRef.current;
+          activeEditorTabRef.current = tab;
+          setEditorViewVisible(true);
+          setActiveEditorTab(tab);
+          if (shouldPersistEditorUiState) {
+            void persistUiState({
+              openEditorTabs: currentOpenEditorTabs,
+              activeEditorTab: tab,
+            });
+          }
+          return;
+        }
+
+        activeEditorTabRef.current = tab;
+        setLocalActiveEditorTab(tab);
+        return;
+      }
+
       activateOpenFile(tab.path);
     },
     [
@@ -1141,6 +1416,7 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
       persistUiState,
       setActiveEditorTab,
       setEditorViewVisible,
+      setLocalActiveEditorTab,
       shouldPersistEditorUiState,
       workspaceId,
     ]
@@ -1153,23 +1429,29 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
         return;
       }
 
-      if (!isGlobalEditorState) {
+      if (tab.kind === "browser" && !isGlobalEditorState) {
         return;
       }
 
       const currentOpenEditorTabs = openEditorTabsRef.current;
       const currentActiveEditorTab = activeEditorTabRef.current;
-      const currentBrowserTabs = currentOpenEditorTabs.filter(isBrowserEditorTab);
-      const closedBrowserIndex = currentBrowserTabs.findIndex((entry) => entry.id === tab.id);
+      const currentNonFileTabs = currentOpenEditorTabs.filter(
+        (entry): entry is Extract<WorkspaceEditorTab, { kind: "browser" | "canvas" }> =>
+          entry.kind === "browser" || entry.kind === "canvas"
+      );
+      const closedTabIndex = currentNonFileTabs.findIndex((entry) => isSameEditorTab(entry, tab));
       const nextOpenEditorTabs = currentOpenEditorTabs.filter(
-        (entry) => entry.kind !== "browser" || entry.id !== tab.id
+        (entry) => !isSameEditorTab(entry, tab)
       );
 
       if (nextOpenEditorTabs.length === currentOpenEditorTabs.length) {
         return;
       }
 
-      const nextBrowserTabs = nextOpenEditorTabs.filter(isBrowserEditorTab);
+      const nextNonFileTabs = nextOpenEditorTabs.filter(
+        (entry): entry is Extract<WorkspaceEditorTab, { kind: "browser" | "canvas" }> =>
+          entry.kind === "browser" || entry.kind === "canvas"
+      );
       const mergedOpenFilePaths = mergeOpenEditorPaths(
         openEditorPaths,
         activeFilePath ? [activeFilePath] : undefined
@@ -1179,31 +1461,204 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
           ? activeFilePath
           : (mergedOpenFilePaths[0] ?? null);
       const nextActiveEditorTab = isSameEditorTab(currentActiveEditorTab, tab)
-        ? (nextBrowserTabs[closedBrowserIndex] ??
-          nextBrowserTabs[closedBrowserIndex - 1] ??
+        ? (nextNonFileTabs[closedTabIndex] ??
+          nextNonFileTabs[closedTabIndex - 1] ??
           (fallbackFilePath ? ({ kind: "file", path: fallbackFilePath } as const) : null))
         : currentActiveEditorTab;
 
+      openEditorTabsRef.current = nextOpenEditorTabs;
+      activeEditorTabRef.current = nextActiveEditorTab;
+      if (isGlobalEditorState) {
+        setOpenEditorTabs(nextOpenEditorTabs);
+        setActiveEditorTab(nextActiveEditorTab);
+      } else {
+        setLocalOpenEditorTabs(nextOpenEditorTabs);
+        setLocalActiveEditorTab(nextActiveEditorTab);
+      }
+      if (isGlobalEditorState && shouldPersistEditorUiState) {
+        void persistUiState({
+          openEditorTabs: nextOpenEditorTabs,
+          activeEditorTab: nextActiveEditorTab,
+        });
+      }
+    },
+    [
+      activeFilePath,
+      closeOpenFilePath,
+      isGlobalEditorState,
+      openEditorPaths,
+      persistUiState,
+      setActiveEditorTab,
+      setLocalActiveEditorTab,
+      setLocalOpenEditorTabs,
+      setOpenEditorTabs,
+      shouldPersistEditorUiState,
+    ]
+  );
+
+  const removeEditorTabs = useCallback(
+    (tabsToRemove: WorkspaceEditorTab[]) => {
+      if (tabsToRemove.length === 0) {
+        return;
+      }
+
+      const currentOpenEditorTabs = openEditorTabsRef.current;
+      const removedFilePaths = tabsToRemove.flatMap((tab) =>
+        tab.kind === "file" ? [tab.path] : []
+      );
+      const removedFilePathSet = new Set(removedFilePaths);
+      const nextOpenEditorTabs = currentOpenEditorTabs.filter(
+        (tab) => !tabsToRemove.some((removed) => isSameEditorTab(tab, removed))
+      );
+      const currentActiveEditorTab = activeEditorTabRef.current;
+      const currentActiveRemoved =
+        currentActiveEditorTab !== null &&
+        tabsToRemove.some((removed) => isSameEditorTab(currentActiveEditorTab, removed));
+      const nextActiveEditorTab =
+        currentActiveRemoved || !currentActiveEditorTab
+          ? (nextOpenEditorTabs[0] ?? null)
+          : currentActiveEditorTab;
+      const nextActiveFilePath =
+        nextActiveEditorTab?.kind === "file"
+          ? nextActiveEditorTab.path
+          : activeFilePath && !removedFilePathSet.has(activeFilePath)
+            ? activeFilePath
+            : null;
+      const nextOpenEditorPaths = openEditorPaths.filter((path) => !removedFilePathSet.has(path));
+
+      for (const path of removedFilePaths) {
+        cancelPendingEditorLoad(workspaceId ?? "", path);
+      }
+
+      setOpenFiles((prev) => {
+        let changed = false;
+        const next = { ...prev };
+        for (const path of removedFilePaths) {
+          if (path in next) {
+            delete next[path];
+            changed = true;
+          }
+        }
+        return changed ? next : prev;
+      });
+
       openEditorTabsRef.current = nextOpenEditorTabs;
       activeEditorTabRef.current = nextActiveEditorTab;
       setOpenEditorTabs(nextOpenEditorTabs);
       setActiveEditorTab(nextActiveEditorTab);
+      setOpenEditorPaths(nextOpenEditorPaths);
+      setActiveFilePath(nextActiveFilePath);
+      if (nextActiveFilePath !== activeFilePath) {
+        setMode("edit");
+      }
       if (shouldPersistEditorUiState) {
         void persistUiState({
           openEditorTabs: nextOpenEditorTabs,
           activeEditorTab: nextActiveEditorTab,
+          openEditorPaths: nextOpenEditorPaths,
+          activeEditorPath: nextActiveFilePath,
         });
       }
     },
     [
       activeFilePath,
-      closeOpenFilePath,
-      isGlobalEditorState,
       openEditorPaths,
       persistUiState,
       setActiveEditorTab,
+      setActiveFilePath,
+      setMode,
+      setOpenEditorPaths,
       setOpenEditorTabs,
+      setOpenFiles,
       shouldPersistEditorUiState,
+      workspaceId,
+    ]
+  );
+
+  const keepOpenEditorTab = useCallback(
+    (tab: WorkspaceEditorTab) => {
+      if (tab.kind !== "file") {
+        return;
+      }
+
+      pinFileEditorTab(tab.path);
+    },
+    [pinFileEditorTab]
+  );
+
+  const closeOtherEditorTabs = useCallback(
+    (tab: WorkspaceEditorTab) => {
+      const tabsToRemove = openEditorTabsRef.current.filter((entry) => {
+        if (isSameEditorTab(entry, tab)) {
+          return false;
+        }
+
+        return entry.kind !== "file" || !isDirtyOpenFile(openFiles[entry.path]);
+      });
+      removeEditorTabs(tabsToRemove);
+    },
+    [openFiles, removeEditorTabs]
+  );
+
+  const closeEditorTabsToRight = useCallback(
+    (tab: WorkspaceEditorTab) => {
+      const currentOpenEditorTabs = openEditorTabsRef.current;
+      const index = currentOpenEditorTabs.findIndex((entry) => isSameEditorTab(entry, tab));
+      if (index < 0) {
+        return;
+      }
+
+      removeEditorTabs(
+        currentOpenEditorTabs
+          .slice(index + 1)
+          .filter((entry) => entry.kind !== "file" || !isDirtyOpenFile(openFiles[entry.path]))
+      );
+    },
+    [openFiles, removeEditorTabs]
+  );
+
+  const closeSavedEditorTabs = useCallback(() => {
+    const tabsToRemove = openEditorTabsRef.current.filter((tab) => {
+      if (tab.kind !== "file") {
+        return false;
+      }
+
+      return !isDirtyOpenFile(openFiles[tab.path]);
+    });
+
+    removeEditorTabs(tabsToRemove);
+  }, [openFiles, removeEditorTabs]);
+
+  const closeAllEditorTabs = useCallback(() => {
+    removeEditorTabs(
+      openEditorTabsRef.current.filter(
+        (tab) => tab.kind !== "file" || !isDirtyOpenFile(openFiles[tab.path])
+      )
+    );
+  }, [openFiles, removeEditorTabs]);
+
+  const handleSetMode = useCallback(
+    (nextMode: WorkspaceEditorMode) => {
+      if (nextMode === "preview") {
+        const previewSourcePath = activeFilePath ?? activeCanvasEditorTab?.sourcePath;
+        if (previewSourcePath && activateCanvasPreviewForSourcePath(previewSourcePath)) {
+          return;
+        }
+      }
+
+      if (nextMode === "edit" && activeCanvasEditorTab) {
+        activateOpenFile(activeCanvasEditorTab.sourcePath, { pinned: true });
+        return;
+      }
+
+      setMode(nextMode);
+    },
+    [
+      activeCanvasEditorTab,
+      activeFilePath,
+      activateCanvasPreviewForSourcePath,
+      activateOpenFile,
+      setMode,
     ]
   );
 
@@ -1212,10 +1667,12 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
   const isSvgTextBacked =
     (isImageFile && currentFile.isTextBacked) ||
     (isTextFile && currentFile.viewingTextBackedImageAsText === true);
-  const canPreview = Boolean(currentFile);
+  const canPreview = Boolean(currentFile) || activeCanvasEditorTab !== null;
   const canEdit =
-    Boolean(currentFile) &&
-    (currentFile?.kind === "text" || (currentFile?.kind === "image" && currentFile.isTextBacked));
+    activeCanvasEditorTab !== null ||
+    (Boolean(currentFile) &&
+      (currentFile?.kind === "text" ||
+        (currentFile?.kind === "image" && currentFile.isTextBacked)));
   const activeFileHasDiffPreview = Boolean(
     activeFilePath &&
       diffPreview &&
@@ -1275,8 +1732,12 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
     activeFilePath && externalStatus?.path === activeFilePath ? externalStatus.status : null;
   const activeSaveError =
     activeFilePath && saveError?.path === activeFilePath ? saveError.message : null;
+  const activeSkillPath =
+    currentFile?.kind === "text" ? parseSkillEditorPath(currentFile.path) : null;
   const documentPreviewKind =
-    currentFile?.kind === "text" ? deriveDocumentPreviewKind(currentFile.path) : null;
+    currentFile?.kind === "text" && !activeSkillPath
+      ? deriveDocumentPreviewKind(currentFile.path)
+      : null;
   const documentPreview = usePreviewSession({
     enabled: mode === "preview" && Boolean(documentPreviewKind),
     workspaceId,
@@ -1287,17 +1748,25 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
 
   return {
     activeFilePath,
-    activeEditorTab: isGlobalEditorState
-      ? (globalActiveEditorTab ?? (activeFilePath ? { kind: "file", path: activeFilePath } : null))
-      : activeFilePath
-        ? { kind: "file", path: activeFilePath }
-        : null,
+    activeEditorTab:
+      currentActiveEditorTab ??
+      (activeFilePath
+        ? resolveFileEditorTab(
+            currentOpenEditorTabs,
+            activeFilePath,
+            openEditorPaths.includes(activeFilePath)
+          )
+        : null),
     activeDiffChange,
     activeExternalStatus,
     activeLoadError,
     activateOpenFile,
     activateEditorTab,
     closeEditorTab,
+    closeAllEditorTabs,
+    closeEditorTabsToRight,
+    closeOtherEditorTabs,
+    closeSavedEditorTabs,
     closeOpenFilePath,
     canSave,
     canDiff,
@@ -1308,30 +1777,44 @@ export function useCodeEditorActions(options: CodeEditorActionsOptions = {}) {
     handleClose,
     hideEditorView,
     handleContentChange,
+    keepOpenEditorTab,
     handleSave,
     hasUnsavedChangesOutsideDiff,
     isImageFile,
     isSaving,
     isSvgTextBacked,
     isTextFile,
-    mode,
+    mode: activeCanvasEditorTab ? "preview" : mode,
     openBrowserTab,
-    openEditorTabs: isGlobalEditorState
-      ? mergeOpenEditorPaths(openEditorPaths, activeFilePath ? [activeFilePath] : undefined)
-          .map((path): WorkspaceEditorTab => ({ kind: "file", path }))
-          .concat(openEditorTabs.filter((tab) => tab.kind === "browser"))
-      : mergeOpenEditorPaths(openEditorPaths, activeFilePath ? [activeFilePath] : undefined).map(
-          (path): WorkspaceEditorTab => ({ kind: "file", path })
-        ),
+    openEditorTabs: (() => {
+      const existingFileTabs = currentOpenEditorTabs.filter(
+        (tab): tab is Extract<WorkspaceEditorTab, { kind: "file" }> => tab.kind === "file"
+      );
+      const existingFileTabPaths = new Set(existingFileTabs.map((tab) => tab.path));
+      const mergedFileTabs = [
+        ...existingFileTabs,
+        ...mergeOpenEditorPaths(openEditorPaths, activeFilePath ? [activeFilePath] : undefined)
+          .filter((path) => !existingFileTabPaths.has(path))
+          .map(
+            (path): WorkspaceEditorTab => ({
+              kind: "file",
+              path,
+              pinned: openEditorPaths.includes(path),
+            })
+          ),
+      ];
+
+      return mergedFileTabs.concat(
+        currentOpenEditorTabs.filter((tab) => isBrowserEditorTab(tab) || isCanvasEditorTab(tab))
+      );
+    })(),
     openEditorPaths,
     openFiles,
     openCommitFileDiff,
     openInDiffMode,
     pendingNavigationAtom,
     saveError: activeSaveError,
-    setMode: (nextMode: WorkspaceEditorMode) => {
-      setMode(nextMode);
-    },
+    setMode: handleSetMode,
     toggleSvgTextMode,
     workspace,
     workspaceId,
diff --git a/packages/web/src/features/code-editor/actions/use-open-location.test.tsx b/packages/web/src/features/code-editor/actions/use-open-location.test.tsx
index a439d8e40..34c9e8128 100644
--- a/packages/web/src/features/code-editor/actions/use-open-location.test.tsx
+++ b/packages/web/src/features/code-editor/actions/use-open-location.test.tsx
@@ -5,6 +5,7 @@ import { describe, expect, it } from "vitest";
 import {
   activeEditorTabAtomFamily,
   activeFilePathAtomFamily,
+  openEditorTabsAtomFamily,
   openFilesAtomFamily,
 } from "../../workspace/atoms";
 import { pendingEditorNavigationAtomFamily } from "../atoms";
@@ -47,7 +48,7 @@ describe("useOpenLocation", () => {
     });
   });
 
-  it("switches back to the file editor tab when opening a file while browser is active", async () => {
+  it("switches back to a preview file editor tab when opening a file without existing metadata", async () => {
     const store = createStore();
     store.set(activeFilePathAtomFamily("ws-1"), "src/utils/math.ts");
     store.set(activeEditorTabAtomFamily("ws-1"), browserTab("browser-1", "localhost:8001"));
@@ -65,6 +66,32 @@ describe("useOpenLocation", () => {
     expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
       kind: "file",
       path: "src/utils/math.ts",
+      pinned: false,
+    });
+  });
+
+  it("preserves existing preview file tab metadata when opening a location", async () => {
+    const store = createStore();
+    store.set(activeFilePathAtomFamily("ws-1"), "src/utils/math.ts");
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/utils/math.ts", pinned: false },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-1"), browserTab("browser-1", "localhost:8001"));
+    const wrapper = createWrapper(store);
+    const { result } = renderHook(() => useOpenLocation("ws-1"), { wrapper });
+
+    await act(async () => {
+      await result.current.openLocation({
+        workspaceId: "ws-1",
+        path: "src/utils/math.ts",
+        source: "manual",
+      });
+    });
+
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+      kind: "file",
+      path: "src/utils/math.ts",
+      pinned: false,
     });
   });
 
diff --git a/packages/web/src/features/code-editor/actions/use-open-location.ts b/packages/web/src/features/code-editor/actions/use-open-location.ts
index 9a9981393..8982235ae 100644
--- a/packages/web/src/features/code-editor/actions/use-open-location.ts
+++ b/packages/web/src/features/code-editor/actions/use-open-location.ts
@@ -7,6 +7,7 @@ import {
   deriveEditorModeForPath,
   editorModeAtomFamily,
   gitDiffPreviewAtomFamily,
+  openEditorTabsAtomFamily,
   openFilesAtomFamily,
 } from "../../workspace/atoms";
 import { type PendingEditorNavigation, pendingEditorNavigationAtomFamily } from "../atoms";
@@ -16,6 +17,7 @@ export function useOpenLocation(workspaceId: string): {
   clearPendingNavigation(path: string): void;
 } {
   const diffPreview = useAtomValue(gitDiffPreviewAtomFamily(workspaceId));
+  const openEditorTabs = useAtomValue(openEditorTabsAtomFamily(workspaceId));
   const openFiles = useAtomValue(openFilesAtomFamily(workspaceId));
   const setActiveFilePath = useSetAtom(activeFilePathAtomFamily(workspaceId));
   const setActiveEditorTab = useSetAtom(activeEditorTabAtomFamily(workspaceId));
@@ -39,7 +41,13 @@ export function useOpenLocation(workspaceId: string): {
       }
 
       setActiveFilePath(input.path);
-      setActiveEditorTab({ kind: "file", path: input.path });
+      setActiveEditorTab(
+        openEditorTabs.find((tab) => tab.kind === "file" && tab.path === input.path) ?? {
+          kind: "file",
+          path: input.path,
+          pinned: false,
+        }
+      );
 
       if (!openFiles[input.path]) {
         // Existing editor load flow is keyed off activeFilePath. Setting it is
@@ -54,6 +62,7 @@ export function useOpenLocation(workspaceId: string): {
     [
       diffPreview,
       openFiles,
+      openEditorTabs,
       setActiveEditorTab,
       setActiveFilePath,
       setDiffPreview,
diff --git a/packages/web/src/features/code-editor/actions/use-preview-session.test.tsx b/packages/web/src/features/code-editor/actions/use-preview-session.test.tsx
index e5a61abae..3dd16d2a7 100644
--- a/packages/web/src/features/code-editor/actions/use-preview-session.test.tsx
+++ b/packages/web/src/features/code-editor/actions/use-preview-session.test.tsx
@@ -213,4 +213,36 @@ describe("usePreviewSession", () => {
 
     unmount();
   });
+
+  it("allows scripts for markdown previews when the content contains mermaid fences", async () => {
+    const fetchMock = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        id: "session-1",
+        previewUrl: "/api/preview/session/session-1/README.md",
+        revision: 1,
+      }),
+    });
+
+    vi.stubGlobal("fetch", fetchMock);
+
+    const { result, unmount } = renderHook(() =>
+      usePreviewSession({
+        enabled: true,
+        workspaceId: "ws-1",
+        filePath: "README.md",
+        content: "```mermaid\ngraph TD\nA[README] --> B[Preview]\n```",
+        kind: "markdown",
+      })
+    );
+
+    await waitFor(() => expect(result.current.iframeSrc).toContain("rev=1"));
+    expect(result.current.allowScripts).toBe(true);
+    expect(JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body))).toMatchObject({
+      allowScripts: true,
+      kind: "markdown",
+    });
+
+    unmount();
+  });
 });
diff --git a/packages/web/src/features/code-editor/actions/use-preview-session.ts b/packages/web/src/features/code-editor/actions/use-preview-session.ts
index b24933765..508b27221 100644
--- a/packages/web/src/features/code-editor/actions/use-preview-session.ts
+++ b/packages/web/src/features/code-editor/actions/use-preview-session.ts
@@ -1,3 +1,4 @@
+import { markdownUsesMermaid } from "@coder-studio/utils/markdown-mermaid";
 import { useEffect, useRef, useState } from "react";
 import {
   createPreviewSession,
@@ -22,15 +23,17 @@ export function usePreviewSession(input: {
   const [isSyncing, setIsSyncing] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [retryNonce, setRetryNonce] = useState(0);
-  const latestContentRef = useRef(input.content ?? "");
-  const lastSyncedContentRef = useRef(input.content ?? "");
-  const allowScripts = input.kind === "html";
+  const content = input.content ?? "";
+  const latestContentRef = useRef(content);
+  const lastSyncedContentRef = useRef(content);
+  const allowScripts =
+    input.kind === "html" || (input.kind === "markdown" && markdownUsesMermaid(content));
   const targetKey =
     input.enabled && input.workspaceId && input.filePath && input.kind
       ? `${input.workspaceId}:${input.kind}:${input.filePath}`
       : null;
 
-  latestContentRef.current = input.content ?? "";
+  latestContentRef.current = content;
 
   useEffect(() => {
     if (!targetKey || !input.workspaceId || !input.filePath || !input.kind) {
diff --git a/packages/web/src/features/code-editor/index.test.tsx b/packages/web/src/features/code-editor/index.test.tsx
index 14ed23a10..81f3fe203 100644
--- a/packages/web/src/features/code-editor/index.test.tsx
+++ b/packages/web/src/features/code-editor/index.test.tsx
@@ -16,6 +16,14 @@ import { activeWorkspaceIdAtom } from "../../atoms/workspaces";
 import { seedReadyWorkspaceState } from "../../test-utils/workspace-state";
 import { CommandResultError } from "../../ws/client";
 import {
+  editorPaneActiveFilePathAtomFamily,
+  editorPaneModeAtomFamily,
+  editorPaneOpenEditorPathsAtomFamily,
+  editorPanePendingNavigationAtomFamily,
+  getEditorPaneStateKey,
+} from "../agent-panes/atoms/editor-panes";
+import {
+  activeEditorTabAtomFamily,
   activeFilePathAtomFamily,
   editorModeAtomFamily,
   editorRefreshTokenAtomFamily,
@@ -25,6 +33,7 @@ import {
   gitStateAtomFamily,
   type OpenFile,
   openEditorPathsAtomFamily,
+  openEditorTabsAtomFamily,
   openFilesAtomFamily,
 } from "../workspace/atoms";
 import { OpenEditorsSection } from "../workspace/views/shared/open-editors-section";
@@ -268,6 +277,60 @@ describe("CodeEditorHost", () => {
     expect(mockRegistryUpdateFromDisk).not.toHaveBeenCalled();
   });
 
+  it("opens skill files through the skill file read command", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "skills.files.read") {
+        return {
+          kind: "text",
+          content: "# My Review Skill\n",
+          baseHash: "skill-hash-1",
+          encoding: "utf-8",
+          displayPath: "/root/.agents/skills/my-review-skill/SKILL.md",
+        };
+      }
+
+      if (op === "file.read") {
+        throw new Error("skill files must not use file.read");
+      }
+
+      return null;
+    });
+    const { store } = setupStore({ activePath: "skill:my-review-skill/SKILL.md", sendCommand });
+
+    render(
+      <Provider store={store}>
+        <CodeEditorHost />
+      </Provider>
+    );
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.files.read",
+        {
+          skillSlug: "my-review-skill",
+          path: "SKILL.md",
+        },
+        undefined
+      );
+    });
+
+    expect(sendCommand.mock.calls.some(([op]) => op === "file.read")).toBe(false);
+    await waitFor(() => {
+      expect(screen.getByTestId("monaco-host")).toHaveTextContent("# My Review Skill");
+    });
+    expectCurrentFilePathTitle("/root/.agents/skills/my-review-skill/SKILL.md");
+    expect(store.get(openFilesAtomFamily("ws-1"))["skill:my-review-skill/SKILL.md"]).toMatchObject({
+      kind: "text",
+      path: "skill:my-review-skill/SKILL.md",
+      displayPath: "/root/.agents/skills/my-review-skill/SKILL.md",
+      content: "# My Review Skill\n",
+      savedContent: "# My Review Skill\n",
+      baseHash: "skill-hash-1",
+      isDirty: false,
+    });
+    expect(mockRegistryUpdateFromDisk).not.toHaveBeenCalled();
+  });
+
   it("saves system agent instructions through the provider-specific write command", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "agentInstructions.system.read") {
@@ -342,6 +405,79 @@ describe("CodeEditorHost", () => {
     });
   });
 
+  it("saves skill files through the skill file write command", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "skills.files.read") {
+        return {
+          kind: "text",
+          content: "# My Review Skill\n",
+          baseHash: "skill-hash-1",
+          encoding: "utf-8",
+          displayPath: "/root/.agents/skills/my-review-skill/SKILL.md",
+        };
+      }
+
+      if (op === "skills.files.write") {
+        return {
+          newHash: "skill-hash-2",
+        };
+      }
+
+      if (op === "file.write") {
+        throw new Error("skill files must not use file.write");
+      }
+
+      return null;
+    });
+    const { store } = setupStore({ activePath: "skill:my-review-skill/SKILL.md", sendCommand });
+
+    render(
+      <Provider store={store}>
+        <CodeEditorHost />
+      </Provider>
+    );
+
+    const editor = await screen.findByRole("textbox", { name: "Editor content" });
+    fireEvent.change(editor, {
+      target: { value: "# My Review Skill\n\n- Prefer focused answers.\n" },
+    });
+
+    await waitFor(() => {
+      expect(
+        store.get(openFilesAtomFamily("ws-1"))["skill:my-review-skill/SKILL.md"]
+      ).toMatchObject({
+        isDirty: true,
+      });
+    });
+
+    pressSaveShortcut();
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.files.write",
+        {
+          skillSlug: "my-review-skill",
+          path: "SKILL.md",
+          content: "# My Review Skill\n\n- Prefer focused answers.\n",
+          baseHash: "skill-hash-1",
+        },
+        undefined
+      );
+    });
+
+    expect(sendCommand.mock.calls.some(([op]) => op === "file.write")).toBe(false);
+    await waitFor(() => {
+      expect(
+        store.get(openFilesAtomFamily("ws-1"))["skill:my-review-skill/SKILL.md"]
+      ).toMatchObject({
+        savedContent: "# My Review Skill\n\n- Prefer focused answers.\n",
+        baseHash: "skill-hash-2",
+        displayPath: "/root/.agents/skills/my-review-skill/SKILL.md",
+        isDirty: false,
+      });
+    });
+  });
+
   it("keeps a seeded missing project agent draft in memory until save creates the file", async () => {
     const draftContent = "# Agent Instructions\n\n- Add project context here.\n";
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
@@ -539,6 +675,57 @@ describe("CodeEditorHost", () => {
     expect(mockRegistryUpdateFromDisk).not.toHaveBeenCalled();
   });
 
+  it("refreshes a clean skill buffer through the virtual path and keeps the display path", async () => {
+    let readCount = 0;
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "skills.files.read") {
+        readCount += 1;
+        return {
+          kind: "text",
+          content:
+            readCount === 1 ? "# My Review Skill\n" : "# My Review Skill\n\nUpdated on disk\n",
+          baseHash: readCount === 1 ? "skill-hash-1" : "skill-hash-2",
+          encoding: "utf-8",
+          displayPath: "/root/.agents/skills/my-review-skill/SKILL.md",
+        };
+      }
+
+      if (op === "file.read") {
+        throw new Error("skill files must not use file.read");
+      }
+
+      return null;
+    });
+    const { store } = setupStore({ activePath: "skill:my-review-skill/SKILL.md", sendCommand });
+
+    render(
+      <Provider store={store}>
+        <CodeEditorHost />
+      </Provider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("monaco-host")).toHaveTextContent("# My Review Skill");
+    });
+
+    act(() => {
+      store.set(editorRefreshTokenAtomFamily("ws-1"), 1);
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("monaco-host")).toHaveTextContent("Updated on disk");
+    });
+    expectCurrentFilePathTitle("/root/.agents/skills/my-review-skill/SKILL.md");
+    expect(store.get(openFilesAtomFamily("ws-1"))["skill:my-review-skill/SKILL.md"]).toMatchObject({
+      path: "skill:my-review-skill/SKILL.md",
+      displayPath: "/root/.agents/skills/my-review-skill/SKILL.md",
+      savedContent: "# My Review Skill\n\nUpdated on disk\n",
+      baseHash: "skill-hash-2",
+      isDirty: false,
+    });
+    expect(mockRegistryUpdateFromDisk).not.toHaveBeenCalled();
+  });
+
   it("shows an error instead of staying in loading when file.read fails", async () => {
     const sendCommand = vi.fn().mockRejectedValue(new Error("File not found"));
     const { store } = setupStore({ activePath: "src/missing.ts", sendCommand });
@@ -1391,6 +1578,137 @@ describe("CodeEditorHost", () => {
     });
   });
 
+  it("switches .csc files between source edit and canvas preview from the mode buttons", async () => {
+    const { store } = setupStore({
+      activePath: ".coder-studio/canvases/auth-gate.csc",
+      openEditorPaths: [".coder-studio/canvases/auth-gate.csc"],
+      openFiles: {
+        ".coder-studio/canvases/auth-gate.csc": {
+          kind: "text",
+          path: ".coder-studio/canvases/auth-gate.csc",
+          content: '{"kind":"architecture_canvas"}',
+          savedContent: '{"kind":"architecture_canvas"}',
+          baseHash: "canvas-hash",
+          isDirty: false,
+        },
+      },
+    });
+
+    render(
+      <Provider store={store}>
+        <CodeEditorHost />
+      </Provider>
+    );
+
+    expect(screen.getByTestId("monaco-host")).toHaveTextContent("architecture_canvas");
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview" }));
+
+    await waitFor(() => {
+      const previewTab = screen.getByRole("tab", { selected: true });
+      expect(previewTab).toHaveAttribute("title", ".coder-studio/canvases/auth-gate.csc");
+      expect(within(previewTab).getByText("auth-gate")).toBeInTheDocument();
+      expect(within(previewTab).getByText("ARCH")).toBeInTheDocument();
+    });
+
+    expect(store.get(editorModeAtomFamily("ws-1"))).toBe("preview");
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/auth-gate.csc",
+      title: "auth-gate",
+      sourcePath: ".coder-studio/canvases/auth-gate.csc",
+      artifactType: "architecture_canvas",
+      canvasId: ".coder-studio/canvases/auth-gate.csc",
+    });
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/auth-gate.csc",
+        title: "auth-gate",
+        sourcePath: ".coder-studio/canvases/auth-gate.csc",
+        artifactType: "architecture_canvas",
+        canvasId: ".coder-studio/canvases/auth-gate.csc",
+      },
+    ]);
+
+    fireEvent.click(screen.getByRole("button", { name: "Edit" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("monaco-host")).toHaveTextContent("architecture_canvas");
+    });
+
+    expect(store.get(editorModeAtomFamily("ws-1"))).toBe("edit");
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+      kind: "file",
+      path: ".coder-studio/canvases/auth-gate.csc",
+      pinned: true,
+    });
+  });
+
+  it("switches pane-local .csc files between source edit and canvas preview from the mode buttons", async () => {
+    const { store } = setupStore({
+      activePath: null,
+      openEditorPaths: [],
+      openFiles: {
+        ".coder-studio/canvases/auth-gate.csc": {
+          kind: "text",
+          path: ".coder-studio/canvases/auth-gate.csc",
+          content: '{"kind":"architecture_canvas"}',
+          savedContent: '{"kind":"architecture_canvas"}',
+          baseHash: "canvas-hash",
+          isDirty: false,
+        },
+      },
+    });
+    const paneStateKey = getEditorPaneStateKey("ws-1", "pane-1");
+    store.set(
+      editorPaneActiveFilePathAtomFamily(paneStateKey),
+      ".coder-studio/canvases/auth-gate.csc"
+    );
+    store.set(editorPaneOpenEditorPathsAtomFamily(paneStateKey), [
+      ".coder-studio/canvases/auth-gate.csc",
+    ]);
+
+    function PaneCodeEditorHost() {
+      const editorState = useCodeEditorActions({
+        activeFilePathAtom: editorPaneActiveFilePathAtomFamily(paneStateKey),
+        editorModeAtom: editorPaneModeAtomFamily(paneStateKey),
+        openEditorPathsAtom: editorPaneOpenEditorPathsAtomFamily(paneStateKey),
+        pendingNavigationAtom: editorPanePendingNavigationAtomFamily(paneStateKey),
+        persistEditorUiState: false,
+      });
+
+      return <CodeEditorHost editorState={editorState} />;
+    }
+
+    render(
+      <Provider store={store}>
+        <PaneCodeEditorHost />
+      </Provider>
+    );
+
+    expect(screen.getByTestId("monaco-host")).toHaveTextContent("architecture_canvas");
+
+    fireEvent.click(screen.getByRole("button", { name: "Preview" }));
+
+    await waitFor(() => {
+      const previewTab = screen.getByRole("tab", { selected: true });
+      expect(previewTab).toHaveAttribute("title", ".coder-studio/canvases/auth-gate.csc");
+      expect(within(previewTab).getByText("auth-gate")).toBeInTheDocument();
+      expect(within(previewTab).getByText("ARCH")).toBeInTheDocument();
+    });
+
+    expect(store.get(editorPaneModeAtomFamily(paneStateKey))).toBe("preview");
+
+    fireEvent.click(screen.getByRole("button", { name: "Edit" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("monaco-host")).toHaveTextContent("architecture_canvas");
+    });
+
+    expect(store.get(editorPaneModeAtomFamily(paneStateKey))).toBe("edit");
+  });
+
   it("defaults markdown files into preview mode after load", async () => {
     const { store } = setupStore({
       activePath: "README.md",
diff --git a/packages/web/src/features/code-editor/skill-editor-path.test.ts b/packages/web/src/features/code-editor/skill-editor-path.test.ts
new file mode 100644
index 000000000..fad600e84
--- /dev/null
+++ b/packages/web/src/features/code-editor/skill-editor-path.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import {
+  isSkillEditorPath,
+  parseSkillEditorPath,
+  SKILL_EDITOR_PATH_PREFIX,
+  toSkillEditorPath,
+} from "./skill-editor-path";
+
+describe("skill editor paths", () => {
+  it("builds a stable virtual path from slug and relative path", () => {
+    expect(toSkillEditorPath("my-review-skill", "refs/checklist.md")).toBe(
+      "skill:my-review-skill/refs/checklist.md"
+    );
+  });
+
+  it("parses skill virtual paths into slug and relative path", () => {
+    expect(parseSkillEditorPath("skill:my-review-skill/SKILL.md")).toEqual({
+      skillSlug: "my-review-skill",
+      relativePath: "SKILL.md",
+    });
+    expect(parseSkillEditorPath("skill:my-review-skill/refs/checklist.md")).toEqual({
+      skillSlug: "my-review-skill",
+      relativePath: "refs/checklist.md",
+    });
+  });
+
+  it("rejects malformed skill editor paths", () => {
+    expect(parseSkillEditorPath("src/app.ts")).toBeNull();
+    expect(parseSkillEditorPath(SKILL_EDITOR_PATH_PREFIX)).toBeNull();
+    expect(parseSkillEditorPath("skill:missing-relative-path")).toBeNull();
+    expect(parseSkillEditorPath("skill:/SKILL.md")).toBeNull();
+    expect(parseSkillEditorPath("skill:my-review-skill/")).toBeNull();
+  });
+
+  it("detects skill virtual paths", () => {
+    expect(isSkillEditorPath("skill:my-review-skill/SKILL.md")).toBe(true);
+    expect(isSkillEditorPath("src/app.ts")).toBe(false);
+  });
+});
diff --git a/packages/web/src/features/code-editor/skill-editor-path.ts b/packages/web/src/features/code-editor/skill-editor-path.ts
new file mode 100644
index 000000000..54a2031c7
--- /dev/null
+++ b/packages/web/src/features/code-editor/skill-editor-path.ts
@@ -0,0 +1,37 @@
+export const SKILL_EDITOR_PATH_PREFIX = "skill:";
+
+export interface ParsedSkillEditorPath {
+  skillSlug: string;
+  relativePath: string;
+}
+
+export function toSkillEditorPath(skillSlug: string, relativePath: string): string {
+  return `${SKILL_EDITOR_PATH_PREFIX}${skillSlug}/${relativePath}`;
+}
+
+export function parseSkillEditorPath(path: string): ParsedSkillEditorPath | null {
+  if (!path.startsWith(SKILL_EDITOR_PATH_PREFIX)) {
+    return null;
+  }
+
+  const rawTarget = path.slice(SKILL_EDITOR_PATH_PREFIX.length);
+  const separatorIndex = rawTarget.indexOf("/");
+  if (separatorIndex <= 0 || separatorIndex === rawTarget.length - 1) {
+    return null;
+  }
+
+  const skillSlug = rawTarget.slice(0, separatorIndex).trim();
+  const relativePath = rawTarget.slice(separatorIndex + 1).trim();
+  if (!skillSlug || !relativePath) {
+    return null;
+  }
+
+  return {
+    skillSlug,
+    relativePath,
+  };
+}
+
+export function isSkillEditorPath(path: string): boolean {
+  return parseSkillEditorPath(path) !== null;
+}
diff --git a/packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx b/packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx
new file mode 100644
index 000000000..16363dadf
--- /dev/null
+++ b/packages/web/src/features/code-editor/views/shared/canvas-surface.test.tsx
@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { describe, expect, it, vi } from "vitest";
+import { fetchCanvasData } from "../../../canvas/api";
+import { CanvasSurface } from "./canvas-surface";
+
+vi.mock("../../../../lib/i18n", () => ({
+  useTranslation: () => (key: string) => {
+    const dictionary: Record<string, string> = {
+      "code_editor.preview_unavailable": "Preview unavailable",
+      "code_editor.canvas_zoom_controls": "Canvas zoom controls",
+      "code_editor.canvas_zoom_reset": "Reset zoom",
+      "code_editor.image_zoom_out": "Zoom out",
+      "code_editor.image_zoom_in": "Zoom in",
+      "code_editor.image_zoom_level": "Zoom level",
+    };
+    return dictionary[key] ?? key;
+  },
+}));
+
+vi.mock("../../../canvas/api", () => ({
+  fetchCanvasData: vi.fn(),
+}));
+
+const runtimeFlowPayload = {
+  workspaceId: "ws-1",
+  sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+  title: "Runtime Flow",
+  kind: "architecture_canvas" as const,
+  renderStatus: "ready" as const,
+  lastError: null,
+  compiledDocument: {
+    kind: "architecture_canvas" as const,
+    title: "Runtime Flow",
+    summary: "How requests move.",
+    sections: [
+      {
+        type: "diagram" as const,
+        nodes: [{ id: "web", label: "Web UI" }],
+        edges: [],
+      },
+      {
+        type: "annotations" as const,
+        items: [],
+      },
+    ],
+  },
+};
+
+function renderCanvasSurface() {
+  const store = createStore();
+
+  const view = render(
+    <Provider store={store}>
+      <CanvasSurface
+        workspaceId="ws-1"
+        tab={{
+          kind: "canvas",
+          id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+          title: "Runtime Flow",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+        }}
+      />
+    </Provider>
+  );
+
+  return { store, ...view };
+}
+
+describe("CanvasSurface", () => {
+  it("renders canvas inline with zoom controls", async () => {
+    const fetchCanvasDataMock = vi.mocked(fetchCanvasData);
+    fetchCanvasDataMock.mockResolvedValue(runtimeFlowPayload);
+
+    const { container } = renderCanvasSurface();
+
+    expect(container.querySelector("iframe")).toBeNull();
+    expect(container.querySelector(".canvas-surface__viewport")).toBeTruthy();
+    expect(screen.getByRole("toolbar", { name: "Canvas zoom controls" })).toBeInTheDocument();
+
+    await waitFor(() => {
+      expect(fetchCanvasDataMock).toHaveBeenCalledWith(
+        "ws-1",
+        ".coder-studio/canvases/runtime-flow.csc"
+      );
+    });
+    expect(screen.getByRole("heading", { name: "Runtime Flow" })).toBeInTheDocument();
+  });
+
+  it("updates zoom level from the zoom buttons and ctrl+wheel", async () => {
+    vi.mocked(fetchCanvasData).mockResolvedValue(runtimeFlowPayload);
+    const { container } = renderCanvasSurface();
+
+    await waitFor(() => {
+      expect(screen.getByRole("heading", { name: "Runtime Flow" })).toBeInTheDocument();
+    });
+
+    expect(screen.getByLabelText("Zoom level")).toHaveTextContent("100%");
+
+    fireEvent.click(screen.getByRole("button", { name: "Zoom in" }));
+    expect(screen.getByLabelText("Zoom level")).toHaveTextContent("110%");
+
+    fireEvent.click(screen.getByRole("button", { name: "Zoom out" }));
+    expect(screen.getByLabelText("Zoom level")).toHaveTextContent("100%");
+
+    const viewport = container.querySelector(".canvas-surface__viewport");
+    expect(viewport).toBeTruthy();
+    fireEvent.wheel(viewport as HTMLElement, { deltaY: -1, ctrlKey: true });
+    expect(screen.getByLabelText("Zoom level")).toHaveTextContent("110%");
+
+    fireEvent.click(screen.getByRole("button", { name: "Reset zoom" }));
+    expect(screen.getByLabelText("Zoom level")).toHaveTextContent("100%");
+  });
+});
diff --git a/packages/web/src/features/code-editor/views/shared/canvas-surface.tsx b/packages/web/src/features/code-editor/views/shared/canvas-surface.tsx
new file mode 100644
index 000000000..10864bbc7
--- /dev/null
+++ b/packages/web/src/features/code-editor/views/shared/canvas-surface.tsx
@@ -0,0 +1,126 @@
+import { useAtomValue } from "jotai";
+import { RotateCcw, ZoomIn, ZoomOut } from "lucide-react";
+import type { FC, WheelEvent } from "react";
+import { useEffect, useState } from "react";
+import { EmptyState, IconButton, Tooltip } from "../../../../components/ui";
+import { useTranslation } from "../../../../lib/i18n";
+import { CanvasContent } from "../../../canvas/components/canvas-content";
+import {
+  canvasRefreshTokenAtomFamily,
+  type WorkspaceCanvasEditorTab,
+} from "../../../workspace/atoms";
+
+const MIN_ZOOM = 0.5;
+const MAX_ZOOM = 2.5;
+const ZOOM_STEP = 0.1;
+
+function clampZoom(value: number): number {
+  return Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, Number(value.toFixed(2))));
+}
+
+function formatZoom(value: number): string {
+  return `${Math.round(value * 100)}%`;
+}
+
+interface CanvasSurfaceProps {
+  workspaceId: string;
+  tab: WorkspaceCanvasEditorTab;
+}
+
+export const CanvasSurface: FC<CanvasSurfaceProps> = ({ workspaceId, tab }) => {
+  const t = useTranslation();
+  const sourcePath = tab.sourcePath.trim();
+  const refreshToken = useAtomValue(canvasRefreshTokenAtomFamily({ workspaceId, sourcePath }));
+  const [zoom, setZoom] = useState(1);
+
+  useEffect(() => {
+    setZoom(1);
+  }, [refreshToken, sourcePath]);
+
+  if (!sourcePath) {
+    return (
+      <EmptyState
+        className="git-diff-empty"
+        title={<p className="git-diff-empty-title">{t("code_editor.preview_unavailable")}</p>}
+      />
+    );
+  }
+
+  const changeZoom = (delta: number) => {
+    setZoom((current) => clampZoom(current + delta));
+  };
+
+  const handleWheel = (event: WheelEvent<HTMLDivElement>) => {
+    if (!event.ctrlKey && !event.metaKey) {
+      return;
+    }
+
+    event.preventDefault();
+    changeZoom(event.deltaY > 0 ? -ZOOM_STEP : ZOOM_STEP);
+  };
+
+  const zoomOutDisabled = zoom <= MIN_ZOOM;
+  const zoomInDisabled = zoom >= MAX_ZOOM;
+  const resetDisabled = zoom === 1;
+
+  return (
+    <div className="document-preview canvas-surface">
+      <div className="canvas-surface__viewport" onWheel={handleWheel}>
+        <div
+          className="canvas-surface__scaled-content"
+          style={{
+            transform: `scale(${zoom})`,
+            transformOrigin: "top left",
+            width: `${100 / zoom}%`,
+          }}
+        >
+          <CanvasContent
+            workspaceId={workspaceId}
+            sourcePath={sourcePath}
+            refreshToken={refreshToken}
+            layout="inline"
+          />
+        </div>
+      </div>
+      <div
+        className="canvas-surface__zoom-bar"
+        role="toolbar"
+        aria-label={t("code_editor.canvas_zoom_controls")}
+      >
+        <Tooltip content={t("code_editor.image_zoom_out")}>
+          <IconButton
+            aria-label={t("code_editor.image_zoom_out")}
+            className="canvas-surface__zoom-btn"
+            disabled={zoomOutDisabled}
+            icon={<ZoomOut size={14} />}
+            onClick={() => changeZoom(-ZOOM_STEP)}
+            size="sm"
+          />
+        </Tooltip>
+        <span className="canvas-surface__zoom-level" aria-label={t("code_editor.image_zoom_level")}>
+          {formatZoom(zoom)}
+        </span>
+        <Tooltip content={t("code_editor.image_zoom_in")}>
+          <IconButton
+            aria-label={t("code_editor.image_zoom_in")}
+            className="canvas-surface__zoom-btn"
+            disabled={zoomInDisabled}
+            icon={<ZoomIn size={14} />}
+            onClick={() => changeZoom(ZOOM_STEP)}
+            size="sm"
+          />
+        </Tooltip>
+        <Tooltip content={t("code_editor.canvas_zoom_reset")}>
+          <IconButton
+            aria-label={t("code_editor.canvas_zoom_reset")}
+            className="canvas-surface__zoom-btn"
+            disabled={resetDisabled}
+            icon={<RotateCcw size={14} />}
+            onClick={() => setZoom(1)}
+            size="sm"
+          />
+        </Tooltip>
+      </div>
+    </div>
+  );
+};
diff --git a/packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx b/packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx
new file mode 100644
index 000000000..b2997c336
--- /dev/null
+++ b/packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.test.tsx
@@ -0,0 +1,175 @@
+// @vitest-environment jsdom
+
+import { fireEvent, render, screen, within } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { localeAtom } from "../../../../atoms/app-ui";
+import { CodeEditorTabsHeader } from "./code-editor-tabs-header";
+
+function wrapperFor(locale: "en" | "zh" = "en") {
+  const store = createStore();
+  store.set(localeAtom, locale);
+
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <Provider store={store}>{children}</Provider>;
+  };
+}
+
+describe("CodeEditorTabsHeader", () => {
+  it("marks preview file tabs with a preview class", () => {
+    render(
+      <CodeEditorTabsHeader
+        activeFilePath="src/preview.ts"
+        activeFullPath="/workspace/src/preview.ts"
+        activeEditorTab={{ kind: "file", path: "src/preview.ts", pinned: false }}
+        openEditorTabs={[{ kind: "file", path: "src/preview.ts", pinned: false }]}
+        openEditorPaths={[]}
+        openFiles={{}}
+        showPathRow={false}
+        onActivateOpenFile={vi.fn()}
+      />,
+      {
+        wrapper: wrapperFor(),
+      }
+    );
+
+    expect(screen.getByRole("tab")).toHaveClass("code-editor-tab--preview");
+  });
+
+  it("opens a tab context menu with keep open for preview tabs", () => {
+    const keepOpen = vi.fn();
+    render(
+      <CodeEditorTabsHeader
+        activeFilePath="src/preview.ts"
+        activeFullPath="/workspace/src/preview.ts"
+        activeEditorTab={{ kind: "file", path: "src/preview.ts", pinned: false }}
+        openEditorTabs={[{ kind: "file", path: "src/preview.ts", pinned: false }]}
+        openEditorPaths={[]}
+        openFiles={{}}
+        showPathRow={false}
+        onActivateOpenFile={vi.fn()}
+        onKeepOpenEditorTab={keepOpen}
+      />,
+      {
+        wrapper: wrapperFor(),
+      }
+    );
+
+    fireEvent.contextMenu(screen.getByRole("tab"));
+    fireEvent.click(screen.getByRole("menuitem", { name: "Keep Open" }));
+
+    expect(keepOpen).toHaveBeenCalledWith({
+      kind: "file",
+      path: "src/preview.ts",
+      pinned: false,
+    });
+  });
+
+  it("keeps a preview tab open when the tab is double-clicked", () => {
+    const keepOpen = vi.fn();
+    render(
+      <CodeEditorTabsHeader
+        activeFilePath="src/preview.ts"
+        activeFullPath="/workspace/src/preview.ts"
+        activeEditorTab={{ kind: "file", path: "src/preview.ts", pinned: false }}
+        openEditorTabs={[{ kind: "file", path: "src/preview.ts", pinned: false }]}
+        openEditorPaths={[]}
+        openFiles={{}}
+        showPathRow={false}
+        onActivateOpenFile={vi.fn()}
+        onKeepOpenEditorTab={keepOpen}
+      />,
+      {
+        wrapper: wrapperFor(),
+      }
+    );
+
+    fireEvent.doubleClick(screen.getByRole("tab"));
+
+    expect(keepOpen).toHaveBeenCalledWith({
+      kind: "file",
+      path: "src/preview.ts",
+      pinned: false,
+    });
+  });
+
+  it("does not mislabel canvas tabs without an artifact type as report canvases", () => {
+    render(
+      <CodeEditorTabsHeader
+        activeFilePath={null}
+        activeFullPath=".coder-studio/canvases/auth-gate.csc"
+        activeEditorTab={{
+          kind: "canvas",
+          id: "canvas:.coder-studio/canvases/auth-gate.csc",
+          title: "auth-gate",
+          sourcePath: ".coder-studio/canvases/auth-gate.csc",
+          canvasId: ".coder-studio/canvases/auth-gate.csc",
+        }}
+        openEditorTabs={[
+          {
+            kind: "canvas",
+            id: "canvas:.coder-studio/canvases/auth-gate.csc",
+            title: "auth-gate",
+            sourcePath: ".coder-studio/canvases/auth-gate.csc",
+            canvasId: ".coder-studio/canvases/auth-gate.csc",
+          },
+        ]}
+        openEditorPaths={[]}
+        openFiles={{}}
+        showPathRow={false}
+        onActivateOpenFile={vi.fn()}
+      />,
+      {
+        wrapper: wrapperFor(),
+      }
+    );
+
+    const tab = screen.getByRole("tab", { selected: true });
+    expect(within(tab).getByText("auth-gate")).toBeInTheDocument();
+    expect(within(tab).queryByText("REPORT")).not.toBeInTheDocument();
+  });
+
+  it("keeps source-path-first canvas tabs distinct when canvasId is absent", () => {
+    render(
+      <CodeEditorTabsHeader
+        activeFilePath={null}
+        activeFullPath=".coder-studio/canvases/auth-gate.csc"
+        activeEditorTab={{
+          kind: "canvas",
+          id: "canvas:.coder-studio/canvases/auth-gate.csc",
+          title: "auth-gate",
+          sourcePath: ".coder-studio/canvases/auth-gate.csc",
+        }}
+        openEditorTabs={[
+          {
+            kind: "canvas",
+            id: "canvas:.coder-studio/canvases/auth-gate.csc",
+            title: "auth-gate",
+            sourcePath: ".coder-studio/canvases/auth-gate.csc",
+          },
+          {
+            kind: "canvas",
+            id: "canvas:.coder-studio/canvases/billing.csc",
+            title: "billing",
+            sourcePath: ".coder-studio/canvases/billing.csc",
+          },
+        ]}
+        openEditorPaths={[]}
+        openFiles={{}}
+        showPathRow={false}
+        onActivateOpenFile={vi.fn()}
+      />,
+      {
+        wrapper: wrapperFor(),
+      }
+    );
+
+    const tabs = screen.getAllByRole("tab");
+    expect(tabs).toHaveLength(2);
+    expect(tabs[0]).toHaveAttribute("aria-selected", "true");
+    expect(within(tabs[0]).getByText("auth-gate")).toBeInTheDocument();
+    expect(within(tabs[1]).getByText("billing")).toBeInTheDocument();
+    expect(tabs[1]).toHaveAttribute("aria-selected", "false");
+  });
+});
diff --git a/packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx b/packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx
index 56a30688f..545f62616 100644
--- a/packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx
+++ b/packages/web/src/features/code-editor/views/shared/code-editor-tabs-header.tsx
@@ -1,5 +1,6 @@
-import { FileCode2, Globe, X } from "lucide-react";
+import { FileCode2, Globe, PanelsTopLeft, X } from "lucide-react";
 import type { MouseEvent, ReactNode } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { useTranslation } from "../../../../lib/i18n";
 import type { OpenFile, WorkspaceEditorTab } from "../../../workspace/atoms";
 
@@ -12,8 +13,13 @@ interface CodeEditorTabsHeaderProps {
   emptyLabel?: string;
   onActivateEditorTab?: (tab: WorkspaceEditorTab) => void;
   onActivateOpenFile: (path: string) => void;
+  onCloseAllEditorTabs?: () => void;
   onCloseEditorTab?: (tab: WorkspaceEditorTab) => void;
+  onCloseEditorTabsToRight?: (tab: WorkspaceEditorTab) => void;
   onCloseOpenFilePath?: (path: string) => void;
+  onCloseOtherEditorTabs?: (tab: WorkspaceEditorTab) => void;
+  onCloseSavedEditorTabs?: () => void;
+  onKeepOpenEditorTab?: (tab: WorkspaceEditorTab) => void;
   openEditorTabs?: WorkspaceEditorTab[];
   openEditorPaths: string[];
   openFiles: Record<string, OpenFile>;
@@ -90,9 +96,30 @@ function isSameEditorTab(left: WorkspaceEditorTab | null | undefined, right: Wor
     return left.path === right.path;
   }
 
+  if (left.kind === "canvas" && right.kind === "canvas") {
+    if (left.canvasId && right.canvasId) {
+      return left.canvasId === right.canvasId;
+    }
+
+    return left.sourcePath === right.sourcePath;
+  }
+
   return false;
 }
 
+interface TabContextMenuState {
+  tab: WorkspaceEditorTab;
+  x: number;
+  y: number;
+}
+
+interface TabContextMenuItem {
+  id: string;
+  label: string;
+  disabled?: boolean;
+  onSelect: () => void;
+}
+
 export function CodeEditorTabsHeader({
   activeFilePath,
   activeFullPath,
@@ -102,8 +129,13 @@ export function CodeEditorTabsHeader({
   emptyLabel,
   onActivateEditorTab,
   onActivateOpenFile,
+  onCloseAllEditorTabs,
   onCloseEditorTab,
+  onCloseEditorTabsToRight,
   onCloseOpenFilePath,
+  onCloseOtherEditorTabs,
+  onCloseSavedEditorTabs,
+  onKeepOpenEditorTab,
   openEditorTabs,
   openEditorPaths,
   openFiles,
@@ -113,6 +145,8 @@ export function CodeEditorTabsHeader({
   workspaceRootPath,
 }: CodeEditorTabsHeaderProps) {
   const t = useTranslation();
+  const menuRef = useRef<HTMLDivElement | null>(null);
+  const [contextMenu, setContextMenu] = useState<TabContextMenuState | null>(null);
   const visibleEditorTabs =
     openEditorTabs ?? openEditorPaths.map((path): WorkspaceEditorTab => ({ kind: "file", path }));
   const fileTabPaths = visibleEditorTabs.flatMap((tab) => (tab.kind === "file" ? [tab.path] : []));
@@ -130,6 +164,128 @@ export function CodeEditorTabsHeader({
   ]
     .filter(Boolean)
     .join(" ");
+  const openContextMenu = useCallback((event: MouseEvent<HTMLElement>, tab: WorkspaceEditorTab) => {
+    event.preventDefault();
+    setContextMenu({ tab, x: event.clientX, y: event.clientY });
+  }, []);
+  const closeContextMenu = useCallback(() => setContextMenu(null), []);
+  const contextMenuItems = useMemo<TabContextMenuItem[]>(() => {
+    if (!contextMenu) {
+      return [];
+    }
+
+    const tab = contextMenu.tab;
+    const items: TabContextMenuItem[] = [];
+    if (tab.kind === "file" && tab.pinned === false && onKeepOpenEditorTab) {
+      items.push({
+        id: "keep-open",
+        label: t("code_editor.keep_tab_open"),
+        onSelect: () => onKeepOpenEditorTab(tab),
+      });
+    }
+
+    items.push(
+      {
+        id: "close",
+        label: t("action.close"),
+        disabled: !onCloseEditorTab && !(tab.kind === "file" && onCloseOpenFilePath),
+        onSelect: () => {
+          if (onCloseEditorTab) {
+            onCloseEditorTab(tab);
+          } else if (tab.kind === "file") {
+            onCloseOpenFilePath?.(tab.path);
+          }
+        },
+      },
+      {
+        id: "close-others",
+        label: t("code_editor.close_other_tabs"),
+        disabled: !onCloseOtherEditorTabs,
+        onSelect: () => onCloseOtherEditorTabs?.(tab),
+      },
+      {
+        id: "close-to-right",
+        label: t("code_editor.close_tabs_to_right"),
+        disabled: !onCloseEditorTabsToRight,
+        onSelect: () => onCloseEditorTabsToRight?.(tab),
+      },
+      {
+        id: "close-saved",
+        label: t("code_editor.close_saved_tabs"),
+        disabled: !onCloseSavedEditorTabs,
+        onSelect: () => onCloseSavedEditorTabs?.(),
+      },
+      {
+        id: "close-all",
+        label: t("action.close_all"),
+        disabled: !onCloseAllEditorTabs,
+        onSelect: () => onCloseAllEditorTabs?.(),
+      }
+    );
+
+    return items;
+  }, [
+    contextMenu,
+    onCloseAllEditorTabs,
+    onCloseEditorTab,
+    onCloseEditorTabsToRight,
+    onCloseOpenFilePath,
+    onCloseOtherEditorTabs,
+    onCloseSavedEditorTabs,
+    onKeepOpenEditorTab,
+    t,
+  ]);
+
+  useLayoutEffect(() => {
+    if (!contextMenu || !menuRef.current) {
+      return;
+    }
+
+    const rect = menuRef.current.getBoundingClientRect();
+    const left = Math.min(
+      Math.max(8, contextMenu.x),
+      Math.max(8, window.innerWidth - rect.width - 8)
+    );
+    const top = Math.min(
+      Math.max(8, contextMenu.y),
+      Math.max(8, window.innerHeight - rect.height - 8)
+    );
+    menuRef.current.style.left = `${left}px`;
+    menuRef.current.style.top = `${top}px`;
+    menuRef.current.focus();
+  }, [contextMenu, contextMenuItems]);
+
+  useEffect(() => {
+    if (!contextMenu) {
+      return;
+    }
+
+    const handlePointerDown = (event: globalThis.PointerEvent) => {
+      if (!(event.target instanceof Node)) {
+        return;
+      }
+
+      if (menuRef.current?.contains(event.target)) {
+        return;
+      }
+
+      closeContextMenu();
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        closeContextMenu();
+      }
+    };
+
+    document.addEventListener("pointerdown", handlePointerDown);
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("pointerdown", handlePointerDown);
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [closeContextMenu, contextMenu]);
 
   return (
     <header className={headerClassName}>
@@ -172,6 +328,7 @@ export function CodeEditorTabsHeader({
                       className={tabClassName}
                       title={tab.url ?? t("dev_browser.title")}
                       onClick={() => onActivateEditorTab?.(tab)}
+                      onContextMenu={(event) => openContextMenu(event, tab)}
                     >
                       <span className="code-editor-tab__icon" aria-hidden="true">
                         <Globe size={14} />
@@ -197,6 +354,66 @@ export function CodeEditorTabsHeader({
                 );
               }
 
+              if (tab.kind === "canvas") {
+                const isActive = isSameEditorTab(activeEditorTab, tab);
+                const tabItemClassName = [
+                  "code-editor-tab-item",
+                  "code-editor-tab-item--canvas",
+                  isActive ? "code-editor-tab-item--active" : "",
+                ]
+                  .filter(Boolean)
+                  .join(" ");
+                const tabClassName = [
+                  "code-editor-tab",
+                  "code-editor-tab--canvas",
+                  isActive ? "code-editor-tab--active" : "",
+                ]
+                  .filter(Boolean)
+                  .join(" ");
+                const closeLabel = t("code_editor.close_editor_tab", { name: tab.title });
+                const handleCloseTab = (event: MouseEvent<HTMLButtonElement>) => {
+                  event.stopPropagation();
+                  onCloseEditorTab?.(tab);
+                };
+
+                return (
+                  <div key={tab.id} className={tabItemClassName}>
+                    <button
+                      type="button"
+                      role="tab"
+                      aria-selected={isActive}
+                      className={tabClassName}
+                      title={tab.sourcePath}
+                      onClick={() => onActivateEditorTab?.(tab)}
+                      onContextMenu={(event) => openContextMenu(event, tab)}
+                    >
+                      <span className="code-editor-tab__icon" aria-hidden="true">
+                        <PanelsTopLeft size={14} />
+                      </span>
+                      <span className="code-editor-tab__copy">
+                        <span className="code-editor-tab__name">{tab.title}</span>
+                        {tab.artifactType ? (
+                          <span className="code-editor-tab__folder">
+                            {tab.artifactType === "architecture_canvas" ? "ARCH" : "REPORT"}
+                          </span>
+                        ) : null}
+                      </span>
+                    </button>
+                    {onCloseEditorTab ? (
+                      <button
+                        type="button"
+                        className="code-editor-tab__close"
+                        aria-label={closeLabel}
+                        title={closeLabel}
+                        onClick={handleCloseTab}
+                      >
+                        <X size={13} aria-hidden="true" />
+                      </button>
+                    ) : null}
+                  </div>
+                );
+              }
+
               const path = tab.path;
               const fileName = getFileName(path);
               const openFile = openFiles[path];
@@ -206,12 +423,14 @@ export function CodeEditorTabsHeader({
                 ? isSameEditorTab(activeEditorTab, tab)
                 : path === activeFilePath;
               const isDirty = isDirtyFile(openFile);
+              const isPreview = tab.pinned === false;
               const parentFolder =
                 (fileNameCounts[fileName] ?? 0) > 1 ? getParentFolderName(path) : null;
               const tabItemClassName = [
                 "code-editor-tab-item",
                 isActive ? "code-editor-tab-item--active" : "",
                 isDirty ? "code-editor-tab-item--dirty" : "",
+                isPreview ? "code-editor-tab-item--preview" : "",
               ]
                 .filter(Boolean)
                 .join(" ");
@@ -219,6 +438,7 @@ export function CodeEditorTabsHeader({
                 "code-editor-tab",
                 isActive ? "code-editor-tab--active" : "",
                 isDirty ? "code-editor-tab--dirty" : "",
+                isPreview ? "code-editor-tab--preview" : "",
               ]
                 .filter(Boolean)
                 .join(" ");
@@ -232,6 +452,14 @@ export function CodeEditorTabsHeader({
 
                 onCloseOpenFilePath?.(path);
               };
+              const handleDoubleClickTab = (event: MouseEvent<HTMLButtonElement>) => {
+                if (!isPreview || !onKeepOpenEditorTab) {
+                  return;
+                }
+
+                event.preventDefault();
+                onKeepOpenEditorTab(tab);
+              };
 
               return (
                 <div key={path} className={tabItemClassName}>
@@ -241,9 +469,11 @@ export function CodeEditorTabsHeader({
                     aria-selected={isActive}
                     className={tabClassName}
                     title={fullPath}
+                    onContextMenu={(event) => openContextMenu(event, tab)}
                     onClick={() =>
                       onActivateEditorTab ? onActivateEditorTab(tab) : onActivateOpenFile(path)
                     }
+                    onDoubleClick={handleDoubleClickTab}
                   >
                     <span className="code-editor-tab__icon" aria-hidden="true">
                       {getFileTypeLabel(path)}
@@ -320,6 +550,42 @@ export function CodeEditorTabsHeader({
           ) : null}
         </nav>
       ) : null}
+      {contextMenu ? (
+        <div className="file-context-menu-layer">
+          <div
+            ref={menuRef}
+            role="menu"
+            tabIndex={-1}
+            aria-label={t("code_editor.editor_tab_actions")}
+            className="file-context-menu code-editor-tab-context-menu"
+            style={{ position: "fixed", left: contextMenu.x, top: contextMenu.y }}
+          >
+            <div className="file-context-menu__section">
+              <div className="file-context-menu__section-items">
+                {contextMenuItems.map((item) => (
+                  <button
+                    key={item.id}
+                    type="button"
+                    role="menuitem"
+                    className="file-context-menu__item"
+                    disabled={item.disabled}
+                    onClick={() => {
+                      if (item.disabled) {
+                        return;
+                      }
+
+                      item.onSelect();
+                      closeContextMenu();
+                    }}
+                  >
+                    <span>{item.label}</span>
+                  </button>
+                ))}
+              </div>
+            </div>
+          </div>
+        </div>
+      ) : null}
     </header>
   );
 }
diff --git a/packages/web/src/features/code-editor/views/shared/editor-surface.test.tsx b/packages/web/src/features/code-editor/views/shared/editor-surface.test.tsx
index dc73dfdc9..3b0c4b40b 100644
--- a/packages/web/src/features/code-editor/views/shared/editor-surface.test.tsx
+++ b/packages/web/src/features/code-editor/views/shared/editor-surface.test.tsx
@@ -36,8 +36,21 @@ vi.mock("../../../../lib/i18n", () => ({
 }));
 
 vi.mock("../../components/monaco-host", () => ({
-  MonacoHost: ({ readOnly }: { readOnly?: boolean }) => (
-    <div data-testid="monaco-host" data-read-only={String(Boolean(readOnly))} />
+  MonacoHost: ({
+    readOnly,
+    standalone,
+    workspaceRootPath,
+  }: {
+    readOnly?: boolean;
+    standalone?: boolean;
+    workspaceRootPath?: string;
+  }) => (
+    <div
+      data-testid="monaco-host"
+      data-read-only={String(Boolean(readOnly))}
+      data-standalone={String(Boolean(standalone))}
+      data-workspace-root-path={workspaceRootPath ?? ""}
+    />
   ),
 }));
 
@@ -125,6 +138,23 @@ vi.mock("../../../dev-browser/dev-browser-surface", () => ({
   ),
 }));
 
+vi.mock("./canvas-surface", () => ({
+  CanvasSurface: ({
+    workspaceId,
+    tab,
+  }: {
+    workspaceId: string;
+    tab: { canvasId: string; title: string };
+  }) => (
+    <div
+      data-testid="canvas-surface"
+      data-workspace-id={workspaceId}
+      data-canvas-id={tab.canvasId}
+      data-title={tab.title}
+    />
+  ),
+}));
+
 function createState(overrides: Partial<CodeEditorState> = {}): CodeEditorState {
   return {
     activeFilePath: "src/app.ts",
@@ -235,6 +265,73 @@ describe("EditorSurface", () => {
     expect(screen.getByTestId("monaco-host")).toHaveAttribute("data-read-only", "false");
   });
 
+  it("preserves preview file tab styling from open editor tab metadata", () => {
+    const state = createState({
+      activeFilePath: "package.json",
+      activeEditorTab: { kind: "file", path: "package.json", pinned: false },
+      currentFile: {
+        kind: "text",
+        path: "package.json",
+        content: "{}\n",
+        savedContent: "{}\n",
+        baseHash: "hash-package",
+        isDirty: false,
+      },
+      openEditorPaths: [],
+      openEditorTabs: [{ kind: "file", path: "package.json", pinned: false }],
+      openFiles: {
+        "package.json": {
+          kind: "text",
+          path: "package.json",
+          content: "{}\n",
+          savedContent: "{}\n",
+          baseHash: "hash-package",
+          isDirty: false,
+        },
+      },
+    });
+
+    render(<EditorSurface state={state} />);
+
+    expect(screen.getByRole("tab", { name: /package\.json/ })).toHaveClass(
+      "code-editor-tab--preview"
+    );
+  });
+
+  it("renders skill text files in standalone Monaco mode without a workspace root", () => {
+    const state = createState({
+      activeFilePath: "skill:my-review-skill/SKILL.md",
+      activeEditorTab: { kind: "file", path: "skill:my-review-skill/SKILL.md" },
+      currentFile: {
+        kind: "text",
+        path: "skill:my-review-skill/SKILL.md",
+        displayPath: "/root/.agents/skills/my-review-skill/SKILL.md",
+        content: "# My Review Skill\n",
+        savedContent: "# My Review Skill\n",
+        baseHash: "skill-hash-1",
+        isDirty: false,
+      },
+      openEditorTabs: [{ kind: "file", path: "skill:my-review-skill/SKILL.md" }],
+      openEditorPaths: ["skill:my-review-skill/SKILL.md"],
+      openFiles: {
+        "skill:my-review-skill/SKILL.md": {
+          kind: "text",
+          path: "skill:my-review-skill/SKILL.md",
+          displayPath: "/root/.agents/skills/my-review-skill/SKILL.md",
+          content: "# My Review Skill\n",
+          savedContent: "# My Review Skill\n",
+          baseHash: "skill-hash-1",
+          isDirty: false,
+        },
+      },
+    });
+
+    render(<EditorSurface state={state} />);
+
+    expect(screen.getByTestId("monaco-host")).toHaveAttribute("data-standalone", "true");
+    expect(screen.getByTestId("monaco-host")).toHaveAttribute("data-workspace-root-path", "");
+  });
+
   it("renders document preview for markdown files in preview mode", () => {
     const state = createState({
       mode: "preview",
@@ -291,6 +388,42 @@ describe("EditorSurface", () => {
     expect(screen.getByTestId("document-preview")).toHaveAttribute("data-allow-scripts", "true");
   });
 
+  it("renders the canvas surface when the active editor tab is a canvas", () => {
+    const state = createState({
+      activeFilePath: null,
+      activeEditorTab: {
+        kind: "canvas",
+        id: "canvas:canvas-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      },
+      openEditorTabs: [
+        {
+          kind: "canvas",
+          id: "canvas:canvas-1",
+          canvasId: "canvas-1",
+          title: "Runtime Flow",
+          artifactType: "architecture_canvas",
+          sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+        },
+      ],
+      openEditorPaths: [],
+      currentFile: undefined,
+      isTextFile: false,
+      isImageFile: false,
+      canPreview: false,
+      canEdit: false,
+      canDiff: false,
+    });
+
+    render(<EditorSurface state={state} />);
+
+    expect(screen.getByTestId("canvas-surface")).toHaveAttribute("data-workspace-id", "ws-1");
+    expect(screen.getByTestId("canvas-surface")).toHaveAttribute("data-canvas-id", "canvas-1");
+  });
+
   it("renders Monaco diff when diff kind is text", () => {
     const state = createState({
       mode: "diff",
diff --git a/packages/web/src/features/code-editor/views/shared/editor-surface.tsx b/packages/web/src/features/code-editor/views/shared/editor-surface.tsx
index 82816c889..b8371d644 100644
--- a/packages/web/src/features/code-editor/views/shared/editor-surface.tsx
+++ b/packages/web/src/features/code-editor/views/shared/editor-surface.tsx
@@ -12,7 +12,9 @@ import { ImageDiffPreview } from "../../components/image-diff-preview";
 import { ImagePreview } from "../../components/image-preview";
 import { MonacoDiffHost } from "../../components/monaco-diff-host";
 import { MonacoHost } from "../../components/monaco-host";
+import { isSkillEditorPath } from "../../skill-editor-path";
 import { isSystemAgentInstructionsEditorPath } from "../../system-agent-instructions-path";
+import { CanvasSurface } from "./canvas-surface";
 import type { CodeEditorChrome, CodeEditorState } from "./code-editor-host";
 import { CodeEditorDesktopHeaderActions } from "./code-editor-host";
 import {
@@ -105,14 +107,25 @@ export const EditorSurface: FC<EditorSurfaceProps> = ({
     );
   }
 
+  const resolveFileEditorTab = (path: string): Extract<WorkspaceEditorTab, { kind: "file" }> =>
+    openEditorTabs.find((tab) => tab.kind === "file" && tab.path === path) ?? {
+      kind: "file",
+      path,
+      pinned: openEditorPaths.includes(path),
+    };
   const activePreviewKind = activeDiffChange?.kind;
   const resolvedActiveEditorTab =
     activeEditorTab?.kind === "browser"
       ? activeEditorTab
-      : activeFilePath
-        ? { kind: "file" as const, path: activeFilePath }
-        : activeEditorTab;
+      : activeEditorTab?.kind === "canvas"
+        ? activeEditorTab
+        : activeEditorTab?.kind === "file" && activeEditorTab.path === activeFilePath
+          ? activeEditorTab
+          : activeFilePath
+            ? resolveFileEditorTab(activeFilePath)
+            : activeEditorTab;
   const isBrowserEditorTabActive = resolvedActiveEditorTab?.kind === "browser";
+  const isCanvasEditorTabActive = resolvedActiveEditorTab?.kind === "canvas";
   const currentTextFile = currentFile?.kind === "text" ? currentFile : null;
   const currentImageFile = currentFile?.kind === "image" ? currentFile : null;
   const showHeader = chrome === "full";
@@ -146,9 +159,11 @@ export const EditorSurface: FC<EditorSurfaceProps> = ({
   const isSystemTextFile = Boolean(
     currentTextFile && isSystemAgentInstructionsEditorPath(currentTextFile.path)
   );
+  const isSkillTextFile = Boolean(currentTextFile && isSkillEditorPath(currentTextFile.path));
   const shouldRenderDocumentPreview =
     mode === "preview" &&
     currentTextFile !== null &&
+    !isSkillTextFile &&
     deriveDocumentPreviewKind(currentTextFile.path) !== null;
   const titleText = commitPreview
     ? (commitPreview.title ?? commitPreview.path)
@@ -161,15 +176,17 @@ export const EditorSurface: FC<EditorSurfaceProps> = ({
   const visibleEditorTabs = isCommitPreview
     ? []
     : [
-        ...visibleEditorPaths.map((path) => ({ kind: "file" as const, path })),
-        ...openEditorTabs.filter((tab) => tab.kind === "browser"),
+        ...visibleEditorPaths.map(resolveFileEditorTab),
+        ...openEditorTabs.filter((tab) => tab.kind === "browser" || tab.kind === "canvas"),
       ];
   const activeFullPath =
-    currentFile?.displayPath ??
-    (activeFilePath ? getFullWorkspaceFilePath(workspace.path, activeFilePath) : titleText);
+    resolvedActiveEditorTab?.kind === "canvas"
+      ? resolvedActiveEditorTab.sourcePath
+      : (currentFile?.displayPath ??
+        (activeFilePath ? getFullWorkspaceFilePath(workspace.path, activeFilePath) : titleText));
   const dirtyStatusLabel = isDirtyTextFile ? t("code_editor.modified_unsaved_changes") : null;
   const handleActivateEditorTab = (tab: WorkspaceEditorTab) => {
-    if (tab.kind === "browser" || isBrowserEditorTabActive) {
+    if (tab.kind === "browser" || tab.kind === "canvas" || isBrowserEditorTabActive) {
       activateEditorTab(tab);
       return;
     }
@@ -177,7 +194,7 @@ export const EditorSurface: FC<EditorSurfaceProps> = ({
     activateOpenFile(tab.path);
   };
   const handleCloseEditorTab = (tab: WorkspaceEditorTab) => {
-    if (tab.kind === "browser" || isBrowserEditorTabActive) {
+    if (tab.kind === "browser" || tab.kind === "canvas" || isBrowserEditorTabActive) {
       closeEditorTab(tab);
       return;
     }
@@ -263,8 +280,13 @@ export const EditorSurface: FC<EditorSurfaceProps> = ({
               dirtyStatusLabel={dirtyStatusLabel}
               onActivateOpenFile={activateOpenFile}
               onActivateEditorTab={handleActivateEditorTab}
+              onCloseAllEditorTabs={state.closeAllEditorTabs}
               onCloseEditorTab={handleCloseEditorTab}
+              onCloseEditorTabsToRight={state.closeEditorTabsToRight}
               onCloseOpenFilePath={closeOpenFilePath}
+              onCloseOtherEditorTabs={state.closeOtherEditorTabs}
+              onCloseSavedEditorTabs={state.closeSavedEditorTabs}
+              onKeepOpenEditorTab={state.keepOpenEditorTab}
               openEditorPaths={visibleEditorPaths}
               openEditorTabs={visibleEditorTabs}
               openFiles={openFiles}
@@ -300,14 +322,17 @@ export const EditorSurface: FC<EditorSurfaceProps> = ({
           )
         ) : null}
 
-        {!isCommitPreview && !isBrowserEditorTabActive && saveError ? (
+        {!isCommitPreview && !isBrowserEditorTabActive && !isCanvasEditorTabActive && saveError ? (
           <div className="code-editor-error" role="alert">
             <ThemedIcon semantic="state.error" size={14} />
             <span>{saveError}</span>
           </div>
         ) : null}
 
-        {!isCommitPreview && !isBrowserEditorTabActive && activeExternalStatus ? (
+        {!isCommitPreview &&
+        !isBrowserEditorTabActive &&
+        !isCanvasEditorTabActive &&
+        activeExternalStatus ? (
           <div className="code-editor-error" role="alert">
             <ThemedIcon
               semantic={
@@ -323,7 +348,10 @@ export const EditorSurface: FC<EditorSurfaceProps> = ({
           </div>
         ) : null}
 
-        {!isCommitPreview && !isBrowserEditorTabActive && hasUnsavedChangesOutsideDiff ? (
+        {!isCommitPreview &&
+        !isBrowserEditorTabActive &&
+        !isCanvasEditorTabActive &&
+        hasUnsavedChangesOutsideDiff ? (
           <div className="code-editor-error" role="alert">
             <ThemedIcon semantic="state.warning" size={14} />
             <span>{t("code_editor.diff_saved_only")}</span>
@@ -337,6 +365,8 @@ export const EditorSurface: FC<EditorSurfaceProps> = ({
               workspaceId={workspace.id}
               browserTab={resolvedActiveEditorTab}
             />
+          ) : isCanvasEditorTabActive ? (
+            <CanvasSurface workspaceId={workspace.id} tab={resolvedActiveEditorTab} />
           ) : isCommitFileListPreview ? (
             <CommitFileListPreview
               preview={commitFileListPreview}
@@ -368,11 +398,11 @@ export const EditorSurface: FC<EditorSurfaceProps> = ({
           ) : currentTextFile ? (
             <MonacoHost
               workspaceId={workspace.id}
-              workspaceRootPath={isSystemTextFile ? undefined : workspace.path}
+              workspaceRootPath={isSystemTextFile || isSkillTextFile ? undefined : workspace.path}
               filePath={currentTextFile.displayPath ?? currentTextFile.path}
               content={currentTextFile.content}
               pendingNavigationAtom={pendingNavigationAtom}
-              standalone={isSystemTextFile}
+              standalone={isSystemTextFile || isSkillTextFile}
               onContentChange={handleContentChange}
               onSave={handleSave}
               readOnly={mode === "preview"}
diff --git a/packages/web/src/features/command-palette/components/command-palette.test.tsx b/packages/web/src/features/command-palette/components/command-palette.test.tsx
index c7b2a9925..9b62a3719 100644
--- a/packages/web/src/features/command-palette/components/command-palette.test.tsx
+++ b/packages/web/src/features/command-palette/components/command-palette.test.tsx
@@ -23,7 +23,7 @@ vi.mock("../../../hooks/use-viewport", () => ({
 
 const routerMocks = vi.hoisted(() => ({
   navigate: vi.fn(),
-  location: { pathname: "/settings" },
+  location: { pathname: "/more/settings/general" },
 }));
 
 vi.mock("react-router-dom", async () => {
@@ -64,7 +64,7 @@ describe("CommandPalette", () => {
   beforeEach(() => {
     viewportMocks.viewport = "desktop";
     routerMocks.navigate.mockReset();
-    routerMocks.location.pathname = "/settings";
+    routerMocks.location.pathname = "/more/settings/general";
   });
 
   it("switches workspaces by setting the active id in memory and navigating to /workspace", () => {
@@ -371,7 +371,7 @@ describe("CommandPalette", () => {
 
     fireEvent.keyDown(palette!, { key: "Enter" });
 
-    expect(routerMocks.navigate).toHaveBeenCalledWith("/settings");
+    expect(routerMocks.navigate).toHaveBeenCalledWith("/more/settings/general");
     expect(store.get(commandPaletteOpenAtom)).toBe(false);
   });
 
diff --git a/packages/web/src/features/command-palette/components/command-palette.tsx b/packages/web/src/features/command-palette/components/command-palette.tsx
index a3ffe2709..06ea95054 100644
--- a/packages/web/src/features/command-palette/components/command-palette.tsx
+++ b/packages/web/src/features/command-palette/components/command-palette.tsx
@@ -345,7 +345,7 @@ function buildCommands(context: {
       description: t("settings.title"),
       shortcut: "Ctrl+,",
       action: () => {
-        navigate("/settings");
+        navigate("/more/settings/general");
       },
     },
     {
diff --git a/packages/web/src/features/dev-browser/api.test.ts b/packages/web/src/features/dev-browser/api.test.ts
deleted file mode 100644
index 8ce3f79f0..000000000
--- a/packages/web/src/features/dev-browser/api.test.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { createDevBrowserSession, deleteDevBrowserSession } from "./api";
-
-describe("dev browser api", () => {
-  afterEach(() => {
-    vi.unstubAllGlobals();
-  });
-
-  it("creates and deletes sessions with credentialed fetch", async () => {
-    const fetchMock = vi.fn(async (url: string, init?: RequestInit) => {
-      if (url === "/api/dev-proxy/session" && init?.method === "POST") {
-        return new Response(
-          JSON.stringify({
-            id: "dev_1",
-            browserUrl: "/dev-browser/session/dev_1/",
-            browserProxyBase: "/dev-browser/session/dev_1/proxy",
-            targetOrigin: "http://127.0.0.1:8000",
-          }),
-          { status: 200, headers: { "content-type": "application/json" } }
-        );
-      }
-
-      if (url === "/api/dev-proxy/session/dev_1" && init?.method === "DELETE") {
-        return new Response(JSON.stringify({ ok: true }), { status: 200 });
-      }
-
-      return new Response("missing", { status: 404 });
-    });
-    vi.stubGlobal("fetch", fetchMock);
-
-    const created = await createDevBrowserSession("localhost:8000");
-    await deleteDevBrowserSession("dev_1");
-
-    expect(created.browserUrl).toBe("/dev-browser/session/dev_1/");
-    expect(fetchMock).toHaveBeenCalledWith(
-      "/api/dev-proxy/session",
-      expect.objectContaining({
-        method: "POST",
-        credentials: "include",
-        body: JSON.stringify({ url: "localhost:8000" }),
-      })
-    );
-    expect(fetchMock).toHaveBeenCalledWith(
-      "/api/dev-proxy/session/dev_1",
-      expect.objectContaining({ method: "DELETE", credentials: "include" })
-    );
-  });
-
-  it("sends userAgent in the create session request body when provided", async () => {
-    const fetchMock = vi.fn(
-      async () =>
-        new Response(
-          JSON.stringify({
-            id: "dev_1",
-            browserUrl: "/dev-browser/session/dev_1/",
-            browserProxyBase: "/dev-browser/session/dev_1/proxy",
-            targetOrigin: "http://127.0.0.1:8000",
-          }),
-          { status: 200, headers: { "content-type": "application/json" } }
-        )
-    );
-    vi.stubGlobal("fetch", fetchMock);
-
-    await createDevBrowserSession("localhost:8000", {
-      userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15",
-    });
-
-    expect(fetchMock).toHaveBeenCalledWith(
-      "/api/dev-proxy/session",
-      expect.objectContaining({
-        method: "POST",
-        credentials: "include",
-        body: JSON.stringify({
-          url: "localhost:8000",
-          userAgent: "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15",
-        }),
-      })
-    );
-  });
-});
diff --git a/packages/web/src/features/dev-browser/api.ts b/packages/web/src/features/dev-browser/api.ts
deleted file mode 100644
index 99c045474..000000000
--- a/packages/web/src/features/dev-browser/api.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-export interface DevBrowserSessionResponse {
-  browserProxyBase: string;
-  browserUrl: string;
-  displayUrl?: string;
-  expiresAt?: number;
-  id: string;
-  targetOrigin: string;
-}
-
-async function readJson<T>(response: Response): Promise<T> {
-  if (!response.ok) {
-    throw new Error(`dev_browser_request_failed:${response.status}`);
-  }
-  return response.json() as Promise<T>;
-}
-
-export interface CreateDevBrowserSessionOptions {
-  userAgent?: string;
-}
-
-export async function createDevBrowserSession(
-  url: string,
-  options: CreateDevBrowserSessionOptions = {}
-): Promise<DevBrowserSessionResponse> {
-  const response = await fetch("/api/dev-proxy/session", {
-    method: "POST",
-    credentials: "include",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ url, ...(options.userAgent ? { userAgent: options.userAgent } : {}) }),
-  });
-
-  return readJson<DevBrowserSessionResponse>(response);
-}
-
-export async function deleteDevBrowserSession(sessionId: string): Promise<void> {
-  const response = await fetch(`/api/dev-proxy/session/${sessionId}`, {
-    method: "DELETE",
-    credentials: "include",
-  });
-
-  await readJson<{ ok: true }>(response);
-}
diff --git a/packages/web/src/features/dev-browser/dev-browser-surface.test.tsx b/packages/web/src/features/dev-browser/dev-browser-surface.test.tsx
index 8c4745fa6..4b3bc55af 100644
--- a/packages/web/src/features/dev-browser/dev-browser-surface.test.tsx
+++ b/packages/web/src/features/dev-browser/dev-browser-surface.test.tsx
@@ -26,34 +26,17 @@ vi.mock("../../lib/i18n", () => ({
       "dev_browser.viewport_width_label": "Viewport width",
       "dev_browser.viewport_height_label": "Viewport height",
       "dev_browser.rotate": "Rotate",
-      "dev_browser.apply_device": "Apply device",
       "dev_browser.viewport_preview_label": "Viewport preview",
-      "dev_browser.invalid_viewport": "Enter a width and height between 1 and 4096.",
-      "dev_browser.open": "Open",
-      "dev_browser.loading": "Opening local preview",
-      "dev_browser.unsupported": "Service workers are unavailable",
       "dev_browser.error": "Could not open local preview",
+      "dev_browser.invalid_viewport": "Enter a width and height between 1 and 4096.",
+      "dev_browser.embed_limitations":
+        "Some local apps block iframe previews. If the page stays blank, open the URL in your browser or relax frame restrictions for local development.",
       dev_browser_invalid_viewport: "Enter a width and height between 1 and 4096.",
     };
     return translations[key] ?? key;
   },
 }));
 
-vi.mock("./api", () => ({
-  createDevBrowserSession: vi.fn(async (url: string) => {
-    const displayUrl = new URL(/^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(url) ? url : `http://${url}`)
-      .href;
-    return {
-      id: "dev_1",
-      browserUrl: "/dev-browser/session/dev_1/",
-      browserProxyBase: "/dev-browser/session/dev_1/proxy",
-      displayUrl,
-      targetOrigin: new URL(displayUrl).origin,
-    };
-  }),
-  deleteDevBrowserSession: vi.fn(async () => undefined),
-}));
-
 function wrapperFor(store: ReturnType<typeof createStore>) {
   return function Wrapper({ children }: { children: ReactNode }) {
     return <Provider store={store}>{children}</Provider>;
@@ -103,44 +86,55 @@ function createWorkspaceStore(
   return store;
 }
 
+async function selectDevicePreset(user: ReturnType<typeof userEvent.setup>, label: string) {
+  await user.click(screen.getByRole("button", { name: /^Device\b/ }));
+  await user.click(screen.getByRole("option", { name: label }));
+}
+
+async function submitLocalUrl(value: string) {
+  const input = screen.getByLabelText("Local URL");
+  fireEvent.change(input, {
+    target: { value },
+  });
+  fireEvent.keyDown(input, {
+    key: "Enter",
+    code: "Enter",
+    charCode: 13,
+  });
+}
+
+function getBrowserFrame() {
+  return screen.getByTitle("Browser");
+}
+
 describe("DevBrowserSurface", () => {
+  const originalServiceWorker = navigator.serviceWorker;
+
   afterEach(() => {
+    Object.defineProperty(navigator, "serviceWorker", {
+      configurable: true,
+      value: originalServiceWorker,
+    });
     vi.clearAllMocks();
     vi.restoreAllMocks();
   });
 
-  function enableServiceWorkerSupport() {
-    Object.defineProperty(window, "isSecureContext", { configurable: true, value: true });
-    Object.defineProperty(window.navigator, "serviceWorker", {
-      configurable: true,
-      value: {},
-    });
-  }
-
-  async function selectDevicePreset(user: ReturnType<typeof userEvent.setup>, label: string) {
-    await user.click(screen.getByRole("button", { name: /^Device\b/ }));
-    await user.click(screen.getByRole("option", { name: label }));
-  }
+  it("opens a direct iframe preview without creating a proxy session", async () => {
+    const activeTab = browserTab("browser-1", null);
+    const store = createWorkspaceStore([activeTab], activeTab);
 
-  async function submitLocalUrl(_user: ReturnType<typeof userEvent.setup>, value: string) {
-    const input = screen.getByLabelText("Local URL");
-    fireEvent.change(input, {
-      target: { value },
-    });
-    fireEvent.keyDown(input, {
-      key: "Enter",
-      code: "Enter",
-      charCode: 13,
+    render(<DevBrowserSurface workspaceId="ws-test" browserTab={activeTab} />, {
+      wrapper: wrapperFor(store),
     });
-  }
 
-  function getBrowserFrame() {
-    return screen.getByTitle("Browser");
-  }
+    await submitLocalUrl("localhost:8000");
 
-  it("creates a session and renders the iframe", async () => {
-    enableServiceWorkerSupport();
-    const user = userEvent.setup();
+    await screen.findByLabelText("Viewport preview");
+    expect(getBrowserFrame()).toHaveAttribute("src", "http://localhost:8000/");
+    expect(store.get(currentDevBrowserUrlAtomFamily("ws-test"))).toBe("http://localhost:8000/");
+  });
+
+  it("shows an embed limitation notice for direct iframe previews", () => {
     const activeTab = browserTab("browser-1", null);
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -148,16 +142,14 @@ describe("DevBrowserSurface", () => {
       wrapper: wrapperFor(store),
     });
 
-    await submitLocalUrl(user, "localhost:8000");
-
-    await screen.findByLabelText("Viewport preview");
-    const frame = getBrowserFrame();
-    expect(frame).toHaveAttribute("src", "/dev-browser/session/dev_1/");
+    expect(
+      screen.getByText(
+        "Some local apps block iframe previews. If the page stays blank, open the URL in your browser or relax frame restrictions for local development."
+      )
+    ).toBeVisible();
   });
 
-  it("opens and clears pending workspace URLs", async () => {
-    enableServiceWorkerSupport();
-    const api = await import("./api");
+  it("opens and clears pending workspace URLs directly", async () => {
     const activeTab = browserTab("browser-1", null);
     const store = createWorkspaceStore([activeTab], activeTab, "ws-1");
     store.set(pendingDevBrowserUrlAtomFamily("ws-1"), "http://127.0.0.1:5173/");
@@ -169,60 +161,44 @@ describe("DevBrowserSurface", () => {
     );
 
     await waitFor(() =>
-      expect(api.createDevBrowserSession).toHaveBeenCalledWith("http://127.0.0.1:5173/", {
-        userAgent: undefined,
-      })
+      expect(store.get(currentDevBrowserUrlAtomFamily("ws-1"))).toBe("http://127.0.0.1:5173/")
     );
     expect(screen.getByLabelText("Local URL")).toHaveValue("http://127.0.0.1:5173/");
     expect(store.get(pendingDevBrowserUrlAtomFamily("ws-1"))).toBeNull();
-    expect(store.get(currentDevBrowserUrlAtomFamily("ws-1"))).toBe("http://127.0.0.1:5173/");
+    expect(getBrowserFrame()).toHaveAttribute("src", "http://127.0.0.1:5173/");
   });
 
-  it("tracks the current workspace URL after a manual open and clears it on unmount", async () => {
-    enableServiceWorkerSupport();
-    const user = userEvent.setup();
+  it("keeps invalid pending workspace URLs pending when they cannot be opened", async () => {
     const activeTab = browserTab("browser-1", null);
     const store = createWorkspaceStore([activeTab], activeTab, "ws-1");
+    store.set(pendingDevBrowserUrlAtomFamily("ws-1"), "https://example.com/app");
 
-    const { unmount } = render(
+    render(
       <Provider store={store}>
         <DevBrowserSurface workspaceId="ws-1" browserTab={activeTab} />
       </Provider>
     );
 
-    await submitLocalUrl(user, "localhost:8000");
-
-    await screen.findByLabelText("Viewport preview");
-    expect(store.get(currentDevBrowserUrlAtomFamily("ws-1"))).toBe("http://localhost:8000/");
-
-    unmount();
-
-    expect(store.get(currentDevBrowserUrlAtomFamily("ws-1"))).toBeNull();
-  });
-
-  it("shows unsupported state when service workers are unavailable", () => {
-    Object.defineProperty(window, "isSecureContext", { configurable: true, value: false });
-    Object.defineProperty(window.navigator, "serviceWorker", {
-      configurable: true,
-      value: undefined,
-    });
-    const activeTab = browserTab("browser-1", null);
-    const store = createWorkspaceStore([activeTab], activeTab);
-
-    render(<DevBrowserSurface workspaceId="ws-test" browserTab={activeTab} />, {
-      wrapper: wrapperFor(store),
-    });
-
-    expect(screen.getByText("Service workers are unavailable")).toBeInTheDocument();
+    expect(await screen.findByText("Could not open local preview")).toBeVisible();
+    expect(store.get(pendingDevBrowserUrlAtomFamily("ws-1"))).toBe("https://example.com/app");
+    expect(screen.queryByTitle("Browser")).not.toBeInTheDocument();
   });
 
-  it("falls back to proxy mode when service workers are unavailable", async () => {
-    Object.defineProperty(window, "isSecureContext", { configurable: true, value: false });
-    Object.defineProperty(window.navigator, "serviceWorker", {
+  it("unregisters legacy dev-browser service workers on mount", async () => {
+    const legacyRegistration = {
+      scope: "http://localhost/dev-browser/",
+      unregister: vi.fn(async () => true),
+    };
+    const unrelatedRegistration = {
+      scope: "http://localhost/preview/",
+      unregister: vi.fn(async () => true),
+    };
+    Object.defineProperty(navigator, "serviceWorker", {
       configurable: true,
-      value: undefined,
+      value: {
+        getRegistrations: vi.fn(async () => [legacyRegistration, unrelatedRegistration]),
+      },
     });
-    const api = await import("./api");
     const activeTab = browserTab("browser-1", null);
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -230,24 +206,11 @@ describe("DevBrowserSurface", () => {
       wrapper: wrapperFor(store),
     });
 
-    const user = userEvent.setup();
-    await submitLocalUrl(user, "localhost:8000");
-
-    await waitFor(() =>
-      expect(api.createDevBrowserSession).toHaveBeenCalledWith("localhost:8000", {
-        userAgent: undefined,
-      })
-    );
-    await screen.findByLabelText("Viewport preview");
-    expect(getBrowserFrame()).toHaveAttribute("src", "/dev-browser/session/dev_1/");
+    await waitFor(() => expect(legacyRegistration.unregister).toHaveBeenCalled());
+    expect(unrelatedRegistration.unregister).not.toHaveBeenCalled();
   });
 
-  it("recreates the dev browser session from the active browser tab url without service workers", async () => {
-    Object.defineProperty(window, "isSecureContext", { configurable: true, value: false });
-    Object.defineProperty(window.navigator, "serviceWorker", {
-      configurable: true,
-      value: undefined,
-    });
+  it("reopens directly from the active browser tab url on mount", async () => {
     const activeTab = browserTab("browser-1", "localhost:8001");
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -256,59 +219,22 @@ describe("DevBrowserSurface", () => {
     });
 
     await screen.findByLabelText("Viewport preview");
-    const frame = getBrowserFrame();
-    expect(frame).toHaveAttribute("src", "/dev-browser/session/dev_1/");
-
-    const api = await import("./api");
-    await waitFor(() =>
-      expect(api.createDevBrowserSession).toHaveBeenCalledWith("localhost:8001", {
-        userAgent: undefined,
-      })
-    );
+    expect(getBrowserFrame()).toHaveAttribute("src", "http://localhost:8001/");
   });
 
-  it("deletes the active session on unmount", async () => {
-    enableServiceWorkerSupport();
-    const api = await import("./api");
-    const user = userEvent.setup();
-    const activeTab = browserTab("browser-1", null);
-    const store = createWorkspaceStore([activeTab], activeTab);
-
-    const { unmount } = render(<DevBrowserSurface workspaceId="ws-test" browserTab={activeTab} />, {
-      wrapper: wrapperFor(store),
-    });
-    await submitLocalUrl(user, "localhost:8000");
-    await screen.findByLabelText("Viewport preview");
-
-    unmount();
-
-    await waitFor(() => expect(api.deleteDevBrowserSession).toHaveBeenCalledWith("dev_1"));
-  });
-
-  it("recreates the dev browser session from the active browser tab url on mount", async () => {
-    enableServiceWorkerSupport();
-    const activeTab = browserTab("browser-1", "localhost:8001");
+  it("does not render invalid persisted browser tab URLs", () => {
+    const activeTab = browserTab("browser-1", "https://example.com/app");
     const store = createWorkspaceStore([activeTab], activeTab);
 
     render(<DevBrowserSurface workspaceId="ws-test" browserTab={activeTab} />, {
       wrapper: wrapperFor(store),
     });
 
-    await screen.findByLabelText("Viewport preview");
-    const frame = getBrowserFrame();
-    expect(frame).toHaveAttribute("src", "/dev-browser/session/dev_1/");
-
-    const api = await import("./api");
-    await waitFor(() =>
-      expect(api.createDevBrowserSession).toHaveBeenCalledWith("localhost:8001", {
-        userAgent: undefined,
-      })
-    );
+    expect(screen.queryByTitle("Browser")).not.toBeInTheDocument();
+    expect(store.get(currentDevBrowserUrlAtomFamily("ws-test"))).toBeNull();
   });
 
   it("replaces the current browser tab url instead of writing devBrowserTargetUrl", async () => {
-    enableServiceWorkerSupport();
-
     const activeTab = browserTab("browser-1", null);
     const otherTab = browserTab("browser-2", "localhost:8002");
     const store = createWorkspaceStore([activeTab, otherTab], activeTab);
@@ -317,56 +243,60 @@ describe("DevBrowserSurface", () => {
       wrapper: wrapperFor(store),
     });
 
-    const user = userEvent.setup();
-    await submitLocalUrl(user, "localhost:8000");
+    await submitLocalUrl("localhost:8000");
 
     await screen.findByLabelText("Viewport preview");
 
     expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
-      browserTab("browser-1", "localhost:8000"),
+      browserTab("browser-1", "http://localhost:8000/"),
       browserTab("browser-2", "localhost:8002"),
     ]);
     expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual(
-      browserTab("browser-1", "localhost:8000")
+      browserTab("browser-1", "http://localhost:8000/")
     );
     expect(store.get(workspacesAtom)["ws-test"]?.uiState).toMatchObject({
       openEditorTabs: [
-        browserTab("browser-1", "localhost:8000"),
+        browserTab("browser-1", "http://localhost:8000/"),
         browserTab("browser-2", "localhost:8002"),
       ],
-      activeEditorTab: browserTab("browser-1", "localhost:8000"),
+      activeEditorTab: browserTab("browser-1", "http://localhost:8000/"),
     });
     expect(store.get(workspacesAtom)["ws-test"]?.uiState).not.toHaveProperty("devBrowserTargetUrl");
   });
 
   it("stays idle for browser tabs with no url until user opens one", async () => {
-    enableServiceWorkerSupport();
-
     const activeTab = browserTab("browser-1", null);
     const store = createWorkspaceStore([activeTab], activeTab);
-    const api = await import("./api");
 
     render(<DevBrowserSurface workspaceId="ws-test" browserTab={activeTab} />, {
       wrapper: wrapperFor(store),
     });
 
-    expect(api.createDevBrowserSession).not.toHaveBeenCalled();
     expect(screen.queryByTitle("Browser")).not.toBeInTheDocument();
 
-    const user = userEvent.setup();
-    await submitLocalUrl(user, "localhost:8003");
+    await submitLocalUrl("localhost:8003");
 
-    await waitFor(() =>
-      expect(api.createDevBrowserSession).toHaveBeenCalledWith("localhost:8003", {
-        userAgent: undefined,
-      })
-    );
     await screen.findByLabelText("Viewport preview");
-    expect(getBrowserFrame()).toHaveAttribute("src", "/dev-browser/session/dev_1/");
+    expect(getBrowserFrame()).toHaveAttribute("src", "http://localhost:8003/");
+  });
+
+  it("rejects non-local manual URLs", async () => {
+    const activeTab = browserTab("browser-1", null);
+    const store = createWorkspaceStore([activeTab], activeTab);
+
+    render(<DevBrowserSurface workspaceId="ws-test" browserTab={activeTab} />, {
+      wrapper: wrapperFor(store),
+    });
+
+    await submitLocalUrl("https://example.com/app");
+
+    expect(await screen.findByText("Could not open local preview")).toBeVisible();
+    expect(screen.queryByTitle("Browser")).not.toBeInTheDocument();
+    expect(store.get(currentDevBrowserUrlAtomFamily("ws-test"))).toBeNull();
+    expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual(activeTab);
   });
 
   it("uses fill mode for desktop sessions and hides device-only controls", async () => {
-    enableServiceWorkerSupport();
     const activeTab = browserTab("browser-1", "http://127.0.0.1:5173/");
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -377,8 +307,6 @@ describe("DevBrowserSurface", () => {
     const viewport = await screen.findByLabelText("Viewport preview");
     const frame = getBrowserFrame();
 
-    expect(screen.queryByText("Local URL")).not.toBeInTheDocument();
-    expect(screen.queryByText("Device")).not.toBeInTheDocument();
     expect(screen.queryByLabelText("Viewport width")).not.toBeInTheDocument();
     expect(screen.queryByLabelText("Viewport height")).not.toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Rotate" })).not.toBeInTheDocument();
@@ -387,10 +315,8 @@ describe("DevBrowserSurface", () => {
     expect(frame).not.toHaveAttribute("style");
   });
 
-  it("reopens the session immediately when selecting a non-custom mobile preset", async () => {
-    enableServiceWorkerSupport();
+  it("applies a non-custom mobile preset without reopening through a proxy", async () => {
     const user = userEvent.setup();
-    const api = await import("./api");
     const activeTab = browserTab("browser-1", "http://127.0.0.1:5173/");
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -399,37 +325,31 @@ describe("DevBrowserSurface", () => {
     });
 
     await screen.findByLabelText("Viewport preview");
-    expect(api.createDevBrowserSession).toHaveBeenCalledTimes(1);
-    expect(api.createDevBrowserSession).toHaveBeenLastCalledWith("http://127.0.0.1:5173/", {
-      userAgent: undefined,
-    });
 
     await selectDevicePreset(user, "iPhone 14");
-    await waitFor(() => expect(api.createDevBrowserSession).toHaveBeenCalledTimes(2));
-    expect(api.createDevBrowserSession).toHaveBeenLastCalledWith("http://127.0.0.1:5173/", {
-      userAgent: expect.stringContaining("iPhone"),
-    });
-    expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual(
-      browserTab("browser-1", "http://127.0.0.1:5173/", {
-        devicePreset: "iphone-14",
-        viewportWidth: 390,
-        viewportHeight: 844,
-        orientation: "portrait",
-        userAgentMode: "mobile",
-      })
+
+    await waitFor(() =>
+      expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual(
+        browserTab("browser-1", "http://127.0.0.1:5173/", {
+          devicePreset: "iphone-14",
+          viewportWidth: 390,
+          viewportHeight: 844,
+          orientation: "portrait",
+          userAgentMode: "desktop",
+        })
+      )
     );
+    expect(getBrowserFrame()).toHaveAttribute("src", "http://127.0.0.1:5173/");
   });
 
   it("returns to desktop fill mode immediately when selecting desktop", async () => {
-    enableServiceWorkerSupport();
     const user = userEvent.setup();
-    const api = await import("./api");
     const activeTab = browserTab("browser-1", "http://127.0.0.1:5173/", {
       devicePreset: "pixel-7",
       viewportWidth: 412,
       viewportHeight: 915,
       orientation: "portrait",
-      userAgentMode: "mobile",
+      userAgentMode: "desktop",
     });
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -441,10 +361,6 @@ describe("DevBrowserSurface", () => {
 
     await selectDevicePreset(user, "Desktop");
 
-    await waitFor(() => expect(api.createDevBrowserSession).toHaveBeenCalledTimes(2));
-    expect(api.createDevBrowserSession).toHaveBeenLastCalledWith("http://127.0.0.1:5173/", {
-      userAgent: undefined,
-    });
     await waitFor(() =>
       expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual(
         browserTab("browser-1", "http://127.0.0.1:5173/", {
@@ -463,15 +379,10 @@ describe("DevBrowserSurface", () => {
     expect(screen.queryByLabelText("Viewport height")).not.toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Rotate" })).not.toBeInTheDocument();
     expect(viewport).not.toHaveClass("dev-browser-frame-viewport--device");
-    expect(viewport.style.width).toBe("");
-    expect(viewport.style.height).toBe("");
-    expect(frame.style.width).toBe("");
-    expect(frame.style.height).toBe("");
+    expect(frame).toHaveAttribute("src", "http://127.0.0.1:5173/");
   });
 
   it("applies rotation immediately for fixed device presets", async () => {
-    enableServiceWorkerSupport();
-    const api = await import("./api");
     const activeTab = browserTab("browser-1", "http://127.0.0.1:5173/", {
       devicePreset: "iphone-14",
       viewportWidth: 390,
@@ -489,7 +400,6 @@ describe("DevBrowserSurface", () => {
 
     fireEvent.click(screen.getByRole("button", { name: "Rotate" }));
 
-    await waitFor(() => expect(api.createDevBrowserSession).toHaveBeenCalledTimes(2));
     await waitFor(() =>
       expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual(
         browserTab("browser-1", "http://127.0.0.1:5173/", {
@@ -497,20 +407,19 @@ describe("DevBrowserSurface", () => {
           viewportWidth: 844,
           viewportHeight: 390,
           orientation: "landscape",
-          userAgentMode: "mobile",
+          userAgentMode: "desktop",
         })
       )
     );
   });
 
   it("renders device sessions inside a fixed logical viewport", async () => {
-    enableServiceWorkerSupport();
     const activeTab = browserTab("browser-1", "http://127.0.0.1:5173/", {
       devicePreset: "pixel-7",
       viewportWidth: 412,
       viewportHeight: 915,
       orientation: "portrait",
-      userAgentMode: "mobile",
+      userAgentMode: "desktop",
     });
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -525,13 +434,12 @@ describe("DevBrowserSurface", () => {
   });
 
   it("scales the logical viewport down to fit the shell", async () => {
-    enableServiceWorkerSupport();
     const activeTab = browserTab("browser-1", "http://127.0.0.1:5173/", {
       devicePreset: "iphone-14",
       viewportWidth: 390,
       viewportHeight: 844,
       orientation: "portrait",
-      userAgentMode: "mobile",
+      userAgentMode: "desktop",
     });
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -563,15 +471,13 @@ describe("DevBrowserSurface", () => {
   });
 
   it("keeps custom viewport edits local until open is submitted", async () => {
-    enableServiceWorkerSupport();
     const user = userEvent.setup();
-    const api = await import("./api");
     const activeTab = browserTab("browser-1", "http://127.0.0.1:5173/", {
       devicePreset: "pixel-7",
       viewportWidth: 412,
       viewportHeight: 915,
       orientation: "portrait",
-      userAgentMode: "mobile",
+      userAgentMode: "desktop",
     });
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -591,7 +497,6 @@ describe("DevBrowserSurface", () => {
       target: { value: "700" },
     });
 
-    expect(api.createDevBrowserSession).toHaveBeenCalledTimes(1);
     expect(screen.getByLabelText("Viewport preview")).toHaveStyle({
       width: "412px",
       height: "915px",
@@ -603,10 +508,6 @@ describe("DevBrowserSurface", () => {
       charCode: 13,
     });
 
-    await waitFor(() => expect(api.createDevBrowserSession).toHaveBeenCalledTimes(2));
-    expect(api.createDevBrowserSession).toHaveBeenLastCalledWith("http://127.0.0.1:5173/", {
-      userAgent: expect.stringContaining("iPhone"),
-    });
     await waitFor(() =>
       expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual(
         browserTab("browser-1", "http://127.0.0.1:5173/", {
@@ -614,7 +515,7 @@ describe("DevBrowserSurface", () => {
           viewportWidth: 500,
           viewportHeight: 700,
           orientation: "portrait",
-          userAgentMode: "mobile",
+          userAgentMode: "desktop",
         })
       )
     );
@@ -625,9 +526,7 @@ describe("DevBrowserSurface", () => {
   });
 
   it("blocks open and shows an error when custom viewport dimensions are invalid", async () => {
-    enableServiceWorkerSupport();
     const user = userEvent.setup();
-    const api = await import("./api");
     const activeTab = browserTab("browser-1", "http://127.0.0.1:5173/");
     const store = createWorkspaceStore([activeTab], activeTab);
 
@@ -636,7 +535,6 @@ describe("DevBrowserSurface", () => {
     });
 
     await screen.findByLabelText("Viewport preview");
-    expect(api.createDevBrowserSession).toHaveBeenCalledTimes(1);
 
     await selectDevicePreset(user, "Custom");
     fireEvent.change(screen.getByLabelText("Viewport width"), {
@@ -645,10 +543,9 @@ describe("DevBrowserSurface", () => {
     fireEvent.change(screen.getByLabelText("Viewport height"), {
       target: { value: "99999" },
     });
-    await submitLocalUrl(user, "http://127.0.0.1:5173/");
+    await submitLocalUrl("http://127.0.0.1:5173/");
 
     expect(await screen.findByText("Enter a width and height between 1 and 4096.")).toBeVisible();
-    expect(api.createDevBrowserSession).toHaveBeenCalledTimes(1);
     expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual(activeTab);
   });
 });
diff --git a/packages/web/src/features/dev-browser/dev-browser-surface.tsx b/packages/web/src/features/dev-browser/dev-browser-surface.tsx
index bf3032e4e..3f9ab528b 100644
--- a/packages/web/src/features/dev-browser/dev-browser-surface.tsx
+++ b/packages/web/src/features/dev-browser/dev-browser-surface.tsx
@@ -1,3 +1,4 @@
+import { normalizeLocalhostUrl } from "@coder-studio/core";
 import { useAtom, useStore } from "jotai";
 import { RotateCw } from "lucide-react";
 import {
@@ -23,22 +24,8 @@ import {
   type WorkspaceBrowserEditorTab,
   type WorkspaceEditorTab,
 } from "../workspace/atoms";
-import {
-  createDevBrowserSession,
-  type DevBrowserSessionResponse,
-  deleteDevBrowserSession,
-} from "./api";
 import { currentDevBrowserUrlAtomFamily, pendingDevBrowserUrlAtomFamily } from "./atoms";
 
-function supportsDevBrowserServiceWorker(): boolean {
-  return (
-    typeof window !== "undefined" &&
-    window.isSecureContext &&
-    typeof navigator !== "undefined" &&
-    navigator.serviceWorker !== undefined
-  );
-}
-
 interface DevBrowserSurfaceProps {
   browserTab: WorkspaceBrowserEditorTab;
   workspaceId: string;
@@ -66,11 +53,9 @@ const DEVICE_PRESETS: Record<
   { height: number | null; width: number | null; userAgentMode: DevBrowserUserAgentMode }
 > = {
   desktop: { width: null, height: null, userAgentMode: "desktop" },
-  "iphone-14": { width: 390, height: 844, userAgentMode: "mobile" },
-  "pixel-7": { width: 412, height: 915, userAgentMode: "mobile" },
+  "iphone-14": { width: 390, height: 844, userAgentMode: "desktop" },
+  "pixel-7": { width: 412, height: 915, userAgentMode: "desktop" },
 };
-const MOBILE_USER_AGENT =
-  "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1";
 
 interface DeviceSettingsDraft {
   devicePreset: DevBrowserDevicePreset;
@@ -200,12 +185,34 @@ function resolveDeviceSettings(draft: DeviceSettingsDraft): ResolvedDeviceSettin
   };
 }
 
-function deriveUserAgent(userAgentMode: DevBrowserUserAgentMode): string | undefined {
-  if (userAgentMode === "mobile") {
-    return MOBILE_USER_AGENT;
+function normalizeBrowserUrl(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "";
   }
 
-  return undefined;
+  const candidate = /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(trimmed) ? trimmed : `http://${trimmed}`;
+
+  return normalizeLocalhostUrl(candidate);
+}
+
+function createAppliedBrowserTab(browserTab: WorkspaceBrowserEditorTab): WorkspaceBrowserEditorTab {
+  if (!browserTab.url) {
+    return browserTab;
+  }
+
+  try {
+    const normalizedUrl = normalizeBrowserUrl(browserTab.url);
+    return {
+      ...browserTab,
+      url: normalizedUrl || null,
+    };
+  } catch {
+    return {
+      ...browserTab,
+      url: null,
+    };
+  }
 }
 
 export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurfaceProps) {
@@ -217,16 +224,15 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
   const [draft, setDraft] = useState<DeviceSettingsDraft>(() =>
     createDraftFromBrowserTab(browserTab)
   );
-  const [appliedBrowserTab, setAppliedBrowserTab] = useState<WorkspaceBrowserEditorTab>(browserTab);
-  const [session, setSession] = useState<DevBrowserSessionResponse | null>(null);
-  const [loading, setLoading] = useState(false);
+  const [appliedBrowserTab, setAppliedBrowserTab] = useState<WorkspaceBrowserEditorTab>(() =>
+    createAppliedBrowserTab(browserTab)
+  );
   const [error, setError] = useState<string | null>(null);
   const [pendingUrl, setPendingUrl] = useAtom(pendingDevBrowserUrlAtomFamily(workspaceId));
   const [, setCurrentUrl] = useAtom(currentDevBrowserUrlAtomFamily(workspaceId));
-  const sessionRef = useRef<DevBrowserSessionResponse | null>(null);
   const autoOpenedUrlRef = useRef<string | null>(null);
+  const pendingOpenUrlRef = useRef<string | null>(null);
   const frameShellRef = useRef<HTMLDivElement | null>(null);
-  const serviceWorkerSupported = supportsDevBrowserServiceWorker();
   const [frameScale, setFrameScale] = useState(1);
 
   const resolvedDraft = useMemo(() => resolveDeviceSettings(draft), [draft]);
@@ -247,8 +253,19 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
   );
 
   useEffect(() => {
-    sessionRef.current = session;
-  }, [session]);
+    const serviceWorker = navigator.serviceWorker;
+    if (!serviceWorker?.getRegistrations) {
+      return;
+    }
+
+    void serviceWorker.getRegistrations().then((registrations) => {
+      for (const registration of registrations) {
+        if (registration.scope.includes("/dev-browser/")) {
+          void registration.unregister();
+        }
+      }
+    });
+  }, []);
 
   useEffect(() => {
     if (!persistedTargetUrl || url.trim().length > 0) {
@@ -270,7 +287,7 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
   ]);
 
   useEffect(() => {
-    setAppliedBrowserTab(browserTab);
+    setAppliedBrowserTab(createAppliedBrowserTab(browserTab));
   }, [
     browserTab.devicePreset,
     browserTab.id,
@@ -283,19 +300,22 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
 
   useEffect(() => {
     return () => {
-      const activeSession = sessionRef.current;
       setCurrentUrl(null);
-      if (activeSession) {
-        void deleteDevBrowserSession(activeSession.id).catch(() => undefined);
-      }
     };
   }, [setCurrentUrl]);
 
   const openTargetUrl = useCallback(
     async (targetUrl: string, nextDeviceSettings: ResolvedDeviceSettings) => {
-      const nextUrl = targetUrl.trim();
-      if (loading || !nextUrl) {
-        return;
+      let nextUrl: string;
+      try {
+        nextUrl = normalizeBrowserUrl(targetUrl);
+      } catch {
+        setError("dev_browser_open_failed");
+        return false;
+      }
+
+      if (!nextUrl) {
+        return false;
       }
 
       const nextBrowserTab: WorkspaceBrowserEditorTab = {
@@ -313,32 +333,18 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
       );
       setUrl(nextUrl);
       autoOpenedUrlRef.current = nextUrl;
-      setLoading(true);
       setError(null);
-      const previousSession = sessionRef.current;
-      try {
-        const created = await createDevBrowserSession(nextUrl, {
-          userAgent: deriveUserAgent(nextDeviceSettings.userAgentMode),
-        });
-        setSession(created);
-        setCurrentUrl(created.displayUrl ?? `${created.targetOrigin}/`);
-        if (previousSession) {
-          void deleteDevBrowserSession(previousSession.id).catch(() => undefined);
-        }
-        setAppliedBrowserTab(nextBrowserTab);
-        store.set(openEditorTabsAtomFamily(workspaceId), nextOpenEditorTabs);
-        store.set(activeEditorTabAtomFamily(workspaceId), nextBrowserTab);
-        await persistUiState({
-          openEditorTabs: nextOpenEditorTabs,
-          activeEditorTab: nextBrowserTab,
-        });
-      } catch (err) {
-        setError(err instanceof Error ? err.message : "dev_browser_open_failed");
-      } finally {
-        setLoading(false);
-      }
+      setCurrentUrl(nextUrl);
+      setAppliedBrowserTab(nextBrowserTab);
+      store.set(openEditorTabsAtomFamily(workspaceId), nextOpenEditorTabs);
+      store.set(activeEditorTabAtomFamily(workspaceId), nextBrowserTab);
+      const persisted = await persistUiState({
+        openEditorTabs: nextOpenEditorTabs,
+        activeEditorTab: nextBrowserTab,
+      });
+      return persisted;
     },
-    [appliedBrowserTab, loading, persistUiState, setCurrentUrl, store, workspaceId]
+    [appliedBrowserTab, persistUiState, setCurrentUrl, store, workspaceId]
   );
 
   const persistDeviceSettings = useCallback(
@@ -391,7 +397,14 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
       return;
     }
 
-    if (loading || session !== null || autoOpenedUrlRef.current === persistedTargetUrl) {
+    let normalizedPersistedTargetUrl: string;
+    try {
+      normalizedPersistedTargetUrl = normalizeBrowserUrl(persistedTargetUrl);
+    } catch {
+      return;
+    }
+
+    if (autoOpenedUrlRef.current === normalizedPersistedTargetUrl) {
       return;
     }
 
@@ -400,23 +413,38 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
       return;
     }
 
-    void openTargetUrl(persistedTargetUrl, persistedDeviceSettings);
-  }, [browserTab, loading, openTargetUrl, persistedTargetUrl, session]);
+    void openTargetUrl(normalizedPersistedTargetUrl, persistedDeviceSettings);
+  }, [browserTab, openTargetUrl, persistedTargetUrl]);
 
   useEffect(() => {
-    if (!pendingUrl || loading) {
+    if (!pendingUrl) {
+      pendingOpenUrlRef.current = null;
+      return;
+    }
+
+    if (pendingOpenUrlRef.current === pendingUrl) {
       return;
     }
 
-    setPendingUrl(null);
     if (!browserTab.url) {
       const persistedDeviceSettings = resolveDeviceSettings(createDraftFromBrowserTab(browserTab));
       if (!persistedDeviceSettings) {
         return;
       }
-      void openTargetUrl(pendingUrl, persistedDeviceSettings);
+      pendingOpenUrlRef.current = pendingUrl;
+      void openTargetUrl(pendingUrl, persistedDeviceSettings).then((opened) => {
+        if (opened) {
+          pendingOpenUrlRef.current = null;
+          setPendingUrl(null);
+          return;
+        }
+
+        if (pendingOpenUrlRef.current === pendingUrl) {
+          pendingOpenUrlRef.current = null;
+        }
+      });
     }
-  }, [browserTab, browserTab.url, loading, openTargetUrl, pendingUrl, setPendingUrl]);
+  }, [browserTab, browserTab.url, openTargetUrl, pendingUrl, setPendingUrl]);
 
   useEffect(() => {
     if (!hasFixedViewport || !frameShellRef.current) {
@@ -436,7 +464,7 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
     );
     const clampedScale = Number(Math.max(0, nextScale).toFixed(3));
     setFrameScale(clampedScale);
-  }, [hasFixedViewport, session, viewportHeight, viewportWidth]);
+  }, [hasFixedViewport, viewportHeight, viewportWidth]);
 
   const submitCurrentUrl = useCallback(
     async (targetUrl: string) => {
@@ -568,18 +596,16 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
         </div>
       </form>
 
-      {!serviceWorkerSupported ? (
-        <Notice tone="warning" message={t("dev_browser.unsupported")} />
-      ) : null}
       {error ? (
         <Notice
           tone="error"
           message={error === "dev_browser_invalid_viewport" ? t(error) : t("dev_browser.error")}
         />
       ) : null}
+      <Notice tone="info" message={t("dev_browser.embed_limitations")} />
 
       <div className="dev-browser-frame-shell" ref={frameShellRef}>
-        {session ? (
+        {appliedBrowserTab.url ? (
           hasFixedViewport ? (
             <div
               className="dev-browser-frame-viewport dev-browser-frame-viewport--device"
@@ -593,7 +619,7 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
               <iframe
                 className="dev-browser-frame"
                 title={t("dev_browser.title")}
-                src={session.browserUrl}
+                src={appliedBrowserTab.url}
                 sandbox="allow-scripts allow-forms allow-same-origin allow-popups"
                 style={{
                   width: `${viewportWidth}px`,
@@ -609,7 +635,7 @@ export function DevBrowserSurface({ browserTab, workspaceId }: DevBrowserSurface
               <iframe
                 className="dev-browser-frame"
                 title={t("dev_browser.title")}
-                src={session.browserUrl}
+                src={appliedBrowserTab.url}
                 sandbox="allow-scripts allow-forms allow-same-origin allow-popups"
               />
             </div>
diff --git a/packages/web/src/features/dev-browser/dev-browser-sw.test.ts b/packages/web/src/features/dev-browser/dev-browser-sw.test.ts
deleted file mode 100644
index f0d8931e0..000000000
--- a/packages/web/src/features/dev-browser/dev-browser-sw.test.ts
+++ /dev/null
@@ -1,141 +0,0 @@
-// @vitest-environment node
-
-import { readFileSync } from "node:fs";
-import { resolve } from "node:path";
-import vm from "node:vm";
-import { describe, expect, it } from "vitest";
-
-interface SwHarness {
-  mapRequest(input: {
-    clientSessionId?: string;
-    referrer?: string;
-    requestUrl: string;
-    sessions: Record<string, unknown>;
-  }): string | null;
-}
-
-function loadHarness(origin = "https://studio.example"): SwHarness {
-  const script = readFileSync(resolve(process.cwd(), "public/dev-browser-sw.js"), "utf8");
-  const listeners: Record<string, unknown> = {};
-  const context = {
-    URL,
-    console,
-    clients: { get: async () => null },
-    fetch: async () => new Response("ok"),
-    self: {
-      __coderStudioDevBrowserSwTest: undefined as SwHarness | undefined,
-      addEventListener: (name: string, handler: unknown) => {
-        listeners[name] = handler;
-      },
-      location: {
-        origin,
-      },
-      skipWaiting: () => undefined,
-    },
-  };
-
-  vm.runInNewContext(script, context);
-  const harness = context.self.__coderStudioDevBrowserSwTest;
-  if (!harness) {
-    throw new Error("service worker test harness missing");
-  }
-  return harness;
-}
-
-describe("dev browser service worker mapper", () => {
-  const session = {
-    id: "dev_1",
-    browserProxyBase: "/dev-browser/session/dev_1/proxy",
-    targetOrigin: "http://127.0.0.1:8000",
-    targetPath: "/app/",
-  };
-
-  it("maps root-relative resource URLs using the proxied referrer", () => {
-    const harness = loadHarness();
-
-    expect(
-      harness.mapRequest({
-        requestUrl: "https://studio.example/assets/app.js",
-        referrer: "https://studio.example/dev-browser/session/dev_1/proxy/app/",
-        sessions: { dev_1: session },
-      })
-    ).toBe("https://studio.example/dev-browser/session/dev_1/proxy/assets/app.js");
-  });
-
-  it("maps hardcoded localhost URLs to the active proxy base", () => {
-    const harness = loadHarness();
-
-    expect(
-      harness.mapRequest({
-        requestUrl: "http://localhost:8000/chunk.js?x=1",
-        referrer: "https://studio.example/dev-browser/session/dev_1/proxy/app/",
-        sessions: { dev_1: session },
-      })
-    ).toBe("https://studio.example/dev-browser/session/dev_1/proxy/chunk.js?x=1");
-  });
-
-  it("does not rewrite unrelated Coder Studio requests", () => {
-    const harness = loadHarness();
-
-    expect(
-      harness.mapRequest({
-        requestUrl: "https://studio.example/assets/main-app.js",
-        referrer: "https://studio.example/workspace",
-        sessions: { dev_1: session },
-      })
-    ).toBeNull();
-  });
-
-  it("does not rewrite Coder Studio platform auth requests when previewing the studio vite app", () => {
-    const harness = loadHarness("http://studio.example:5173");
-
-    expect(
-      harness.mapRequest({
-        requestUrl: "http://studio.example:5173/auth/status",
-        referrer: "http://studio.example:5173/dev-browser/session/dev_1/proxy/",
-        sessions: {
-          dev_1: {
-            ...session,
-            targetOrigin: "http://127.0.0.1:5173",
-          },
-        },
-      })
-    ).toBeNull();
-  });
-
-  it("does not rewrite Coder Studio platform auth requests for cross-port studio previews", () => {
-    const harness = loadHarness("http://studio.example:4173");
-
-    expect(
-      harness.mapRequest({
-        requestUrl: "http://studio.example:4173/auth/status",
-        referrer: "http://studio.example:4173/dev-browser/session/dev_1/proxy/",
-        sessions: {
-          dev_1: {
-            ...session,
-            targetOrigin: "http://127.0.0.1:5175",
-            preserveStudioPlatformPaths: true,
-          },
-        },
-      })
-    ).toBeNull();
-  });
-
-  it("continues rewriting cross-port Coder Studio websocket requests through the proxy", () => {
-    const harness = loadHarness("http://studio.example:4173");
-
-    expect(
-      harness.mapRequest({
-        requestUrl: "http://127.0.0.1:5175/ws",
-        referrer: "http://studio.example:4173/dev-browser/session/dev_1/proxy/",
-        sessions: {
-          dev_1: {
-            ...session,
-            targetOrigin: "http://127.0.0.1:5175",
-            preserveStudioPlatformPaths: true,
-          },
-        },
-      })
-    ).toBe("http://studio.example:4173/dev-browser/session/dev_1/proxy/ws");
-  });
-});
diff --git a/packages/web/src/features/dev-browser/dev-browser-vite-proxy.test.ts b/packages/web/src/features/dev-browser/dev-browser-vite-proxy.test.ts
deleted file mode 100644
index bea8b93da..000000000
--- a/packages/web/src/features/dev-browser/dev-browser-vite-proxy.test.ts
+++ /dev/null
@@ -1,172 +0,0 @@
-// @vitest-environment node
-
-import {
-  createServer as createHttpServer,
-  type IncomingMessage,
-  type ServerResponse,
-} from "node:http";
-import { createRequire } from "node:module";
-import type { AddressInfo } from "node:net";
-import { createServer, type ViteDevServer } from "vite";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-
-const require = createRequire(new URL("../../../../server/package.json", import.meta.url));
-const { WebSocket, WebSocketServer } = require("ws") as typeof import("ws");
-
-function createBackendServer(handler: (req: IncomingMessage, res: ServerResponse) => void) {
-  return new Promise<{ server: ReturnType<typeof createHttpServer>; url: string }>(
-    (resolve, reject) => {
-      const server = createHttpServer(handler);
-      server.once("error", reject);
-      server.listen(0, "127.0.0.1", () => {
-        const address = server.address();
-        if (!address || typeof address === "string") {
-          reject(new Error("backend test server failed to bind"));
-          return;
-        }
-        resolve({ server, url: `http://127.0.0.1:${address.port}` });
-      });
-    }
-  );
-}
-
-describe("dev browser vite proxy", () => {
-  const originalBackendHttpUrl = process.env.VITE_BACKEND_HTTP_URL;
-  const originalBackendWsUrl = process.env.VITE_BACKEND_WS_URL;
-  let backendServer: ReturnType<typeof createHttpServer> | null = null;
-  let backendWsServer: WebSocketServer | null = null;
-  let viteServer: ViteDevServer | null = null;
-  let vitePort = 0;
-
-  beforeAll(async () => {
-    const backend = await createBackendServer((req, res) => {
-      if (req.url === "/dev-browser/session/test/") {
-        res.statusCode = 200;
-        res.setHeader("content-type", "text/html; charset=utf-8");
-        res.end("<!doctype html><html><body>proxied dev browser session</body></html>");
-        return;
-      }
-
-      res.statusCode = 404;
-      res.setHeader("content-type", "text/plain; charset=utf-8");
-      res.end("backend fallback");
-    });
-    backendServer = backend.server;
-    backendWsServer = new WebSocketServer({ noServer: true });
-    backendWsServer.on("connection", (socket) => {
-      socket.send(`protocol:${socket.protocol || "none"}`);
-      socket.on("message", (data) => {
-        socket.send(`backend:${data.toString()}`);
-      });
-    });
-    backendServer.on("upgrade", (req, socket, head) => {
-      if (req.url !== "/dev-browser/session/test/proxy/ws") {
-        socket.destroy();
-        return;
-      }
-
-      backendWsServer?.handleUpgrade(req, socket, head, (ws) => {
-        backendWsServer?.emit("connection", ws, req);
-      });
-    });
-
-    process.env.VITE_BACKEND_HTTP_URL = backend.url;
-    process.env.VITE_BACKEND_WS_URL = backend.url.replace("http://", "ws://");
-
-    viteServer = await createServer({
-      configFile: "./vite.config.ts",
-      logLevel: "silent",
-      optimizeDeps: {
-        noDiscovery: true,
-      },
-      server: {
-        host: "127.0.0.1",
-        port: 0,
-      },
-    });
-
-    await viteServer.listen();
-    const address = viteServer.httpServer?.address() as AddressInfo | null;
-    if (!address) {
-      throw new Error("vite test server failed to bind");
-    }
-    vitePort = address.port;
-  });
-
-  afterAll(async () => {
-    process.env.VITE_BACKEND_HTTP_URL = originalBackendHttpUrl;
-    process.env.VITE_BACKEND_WS_URL = originalBackendWsUrl;
-    await viteServer?.close();
-    await new Promise<void>((resolve, reject) => {
-      if (!backendServer) {
-        resolve();
-        return;
-      }
-      backendServer.close((error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve();
-      });
-    });
-  });
-
-  it("serves the dev browser service worker from public assets instead of proxying it", async () => {
-    const response = await fetch(`http://127.0.0.1:${vitePort}/dev-browser-sw.js`);
-    const body = await response.text();
-
-    expect(response.status).toBe(200);
-    expect(response.headers.get("content-type")).toContain("javascript");
-    expect(body).toContain("coder-studio-dev-browser-session");
-    expect(body).not.toContain("backend fallback");
-  });
-
-  it("continues proxying dev browser session routes to the backend", async () => {
-    const response = await fetch(`http://127.0.0.1:${vitePort}/dev-browser/session/test/`);
-
-    expect(response.status).toBe(200);
-    expect(response.headers.get("content-type")).toContain("text/html");
-    expect(await response.text()).toContain("proxied dev browser session");
-  });
-
-  it("proxies dev browser websocket upgrades to the backend", async () => {
-    const ws = new WebSocket(`ws://127.0.0.1:${vitePort}/dev-browser/session/test/proxy/ws`);
-    const ready = new Promise<string>((resolve) => {
-      ws.once("message", (data) => resolve(data.toString()));
-    });
-
-    await new Promise<void>((resolve) => {
-      ws.once("open", () => resolve());
-    });
-
-    expect(await ready).toBe("protocol:none");
-
-    const echoed = new Promise<string>((resolve) => {
-      ws.once("message", (data) => resolve(data.toString()));
-    });
-
-    ws.send("hello");
-    expect(await echoed).toBe("backend:hello");
-    ws.terminate();
-  });
-
-  it("proxies websocket subprotocol negotiation through the vite dev proxy", async () => {
-    const ws = new WebSocket(
-      `ws://127.0.0.1:${vitePort}/dev-browser/session/test/proxy/ws`,
-      "vite-hmr"
-    );
-    const ready = new Promise<string>((resolve) => {
-      ws.once("message", (data) => resolve(data.toString()));
-    });
-
-    await new Promise<void>((resolve) => {
-      ws.once("open", () => resolve());
-    });
-
-    expect(ws.protocol).toBe("vite-hmr");
-
-    expect(await ready).toBe("protocol:vite-hmr");
-    ws.terminate();
-  });
-});
diff --git a/packages/web/src/features/diagnostics/page.tsx b/packages/web/src/features/diagnostics/page.tsx
index 67ef3cdc8..acc4da441 100644
--- a/packages/web/src/features/diagnostics/page.tsx
+++ b/packages/web/src/features/diagnostics/page.tsx
@@ -578,7 +578,7 @@ export function DiagnosticsPage({
           ) : (
             <PageHeader
               title={t("diagnostics.title")}
-              titleAs="h1"
+              titleAs="h3"
               level="secondary"
               onBack={handleBack}
               backLabel={t("action.back")}
diff --git a/packages/web/src/features/monitoring/page.test.tsx b/packages/web/src/features/monitoring/page.test.tsx
index 4c0404d23..7187b8f6f 100644
--- a/packages/web/src/features/monitoring/page.test.tsx
+++ b/packages/web/src/features/monitoring/page.test.tsx
@@ -125,7 +125,7 @@ describe("MonitoringContent", () => {
 
     expect(await screen.findByText("Host overview")).toBeInTheDocument();
     expect(
-      screen.queryByRole("heading", { level: 1, name: "Performance monitoring" })
+      screen.queryByRole("heading", { level: 3, name: "Performance monitoring" })
     ).not.toBeInTheDocument();
   });
 
@@ -195,7 +195,7 @@ describe("MonitoringContent", () => {
 
     expect(await screen.findByTestId("monitoring-page")).toBeInTheDocument();
     expect(
-      screen.getByRole("heading", { level: 1, name: "Performance monitoring" })
+      screen.getByRole("heading", { level: 3, name: "Performance monitoring" })
     ).toBeInTheDocument();
   });
 
diff --git a/packages/web/src/features/monitoring/page.tsx b/packages/web/src/features/monitoring/page.tsx
index 380bd3946..184049711 100644
--- a/packages/web/src/features/monitoring/page.tsx
+++ b/packages/web/src/features/monitoring/page.tsx
@@ -915,7 +915,7 @@ export function MonitoringPage() {
         ) : (
           <PageHeader
             title={t("monitoring.title")}
-            titleAs="h1"
+            titleAs="h3"
             level="secondary"
             onBack={() => window.history.back()}
             backLabel={t("action.back")}
diff --git a/packages/web/src/features/more/page.test.tsx b/packages/web/src/features/more/page.test.tsx
index bb0192d9e..376de82b7 100644
--- a/packages/web/src/features/more/page.test.tsx
+++ b/packages/web/src/features/more/page.test.tsx
@@ -87,6 +87,21 @@ function renderMorePage(
           return [];
         }
 
+        if (op === "terminal.profiles.list") {
+          return {
+            profiles: [
+              {
+                id: "detected:bash",
+                label: "Bash",
+                source: "detected",
+                runtime: "native",
+                icon: "terminal",
+              },
+            ],
+            resolvedDefaultProfileId: "detected:bash",
+          };
+        }
+
         if (op === "monitoring.get") {
           return {
             settings: {
@@ -269,6 +284,7 @@ describe("more routes", () => {
   it("builds canonical more paths", () => {
     expect(buildMorePath()).toBe("/more");
     expect(buildMorePath("settings")).toBe("/more/settings");
+    expect(buildMorePath("settings", "terminal")).toBe("/more/settings/terminal");
     expect(buildMorePath("analysis", "monitoring")).toBe("/more/analysis/monitoring");
   });
 
@@ -404,6 +420,14 @@ describe("MoreFeaturesPage", () => {
     ).toBeTruthy();
   });
 
+  it("does not render desktop category tab descriptions for the active category", () => {
+    renderMorePage(["/more/settings/general"], { locale: "zh" });
+
+    expect(screen.getByRole("tab", { name: "设置" })).toHaveAttribute("aria-selected", "true");
+    expect(screen.queryByText("调整工作区行为、provider、外观和快捷键。")).not.toBeInTheDocument();
+    expect(document.querySelector(".more-features-tab__copy")).toBeNull();
+  });
+
   it("canonicalizes the desktop root route to the default settings section", async () => {
     renderMorePage(["/more"]);
 
@@ -498,7 +522,7 @@ describe("MoreFeaturesPage", () => {
   it("returns to /workspace from the desktop back button even when prior history exists", async () => {
     const user = userEvent.setup();
 
-    renderMorePage(["/settings", "/more/analysis/monitoring"]);
+    renderMorePage(["/more/settings/general", "/more/analysis/monitoring"]);
 
     await user.click(screen.getByRole("button", { name: "Back" }));
 
@@ -507,12 +531,36 @@ describe("MoreFeaturesPage", () => {
     });
   });
 
-  it("renders embedded settings content for /more/settings/general", async () => {
-    renderMorePage(["/more/settings/general"]);
+  it("renders embedded settings content for /more/settings/terminal", async () => {
+    renderMorePage(["/more/settings/terminal"]);
 
-    expect(await screen.findByText("Notifications")).toBeInTheDocument();
+    expect(await screen.findByTestId("location-display")).toHaveTextContent(
+      "/more/settings/terminal"
+    );
+    expect(await screen.findByRole("heading", { name: /Terminal renderer/i })).toBeInTheDocument();
+    expect(
+      screen.getByRole("spinbutton", { name: /Desktop terminal font size/i })
+    ).toBeInTheDocument();
+    expect(screen.queryByText("Notifications")).not.toBeInTheDocument();
     expect(screen.queryByText("Section placeholder")).not.toBeInTheDocument();
-    expect(screen.queryByRole("heading", { level: 1, name: "Settings" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("heading", { level: 3, name: "Settings" })).not.toBeInTheDocument();
+  });
+
+  it("exposes the terminal profiles anchor from the canonical terminal settings route", async () => {
+    renderMorePage(["/more/settings/terminal#terminal-profiles"]);
+
+    const terminalProfilesHeading = await screen.findByRole("heading", {
+      name: "Terminal Profiles",
+    });
+    const terminalProfilesSection = document.getElementById("terminal-profiles");
+
+    expect(screen.getByRole("button", { name: "Terminal" })).toHaveAttribute(
+      "aria-current",
+      "page"
+    );
+    expect(terminalProfilesSection).not.toBeNull();
+    expect(terminalProfilesSection).toContainElement(terminalProfilesHeading);
+    expect(terminalProfilesSection).toHaveClass("settings-group");
   });
 
   it("renders only the product subview for /more/about/product", async () => {
@@ -547,7 +595,7 @@ describe("MoreFeaturesPage", () => {
       )
     ).toBeInTheDocument();
     expect(
-      screen.queryByRole("heading", { level: 1, name: "Performance monitoring" })
+      screen.queryByRole("heading", { level: 3, name: "Performance monitoring" })
     ).not.toBeInTheDocument();
   });
 
diff --git a/packages/web/src/features/more/page.tsx b/packages/web/src/features/more/page.tsx
index 312977a34..1d1f9359a 100644
--- a/packages/web/src/features/more/page.tsx
+++ b/packages/web/src/features/more/page.tsx
@@ -25,6 +25,7 @@ const FALLBACK_CATEGORY = MORE_CATEGORIES.settings;
 type EmbeddedMoreSettingsSection =
   | "general"
   | "providers"
+  | "terminal"
   | "appearance"
   | "shortcuts"
   | "monitoring";
@@ -141,6 +142,7 @@ function isEmbeddedSettingsSection(sectionId: string): sectionId is EmbeddedMore
   return (
     sectionId === "general" ||
     sectionId === "providers" ||
+    sectionId === "terminal" ||
     sectionId === "appearance" ||
     sectionId === "shortcuts" ||
     sectionId === "monitoring"
@@ -212,7 +214,7 @@ function MoreMobileCategoryList({
   return (
     <div className="more-features-page more-features-page--mobile" data-testid="more-features-page">
       <header className="more-features-mobile-detail__header">
-        <MobilePageHeader title={title} titleAs="h1" onBack={onBack} backLabel={backLabel} />
+        <MobilePageHeader title={title} titleAs="h3" onBack={onBack} backLabel={backLabel} />
       </header>
       <main className="more-features-mobile-list" role="list">
         {items.map((item) => (
@@ -380,14 +382,18 @@ export function MoreFeaturesPage() {
         <header className="more-features-page__header">
           <PageHeader
             title={t("more.title")}
-            titleAs="h1"
+            titleAs="h3"
             level="secondary"
             onBack={handleBack}
             backLabel={t("action.back")}
             className="more-features-page__page-header"
           />
         </header>
+      </div>
+
+      <div className="more-features-page__divider" aria-hidden="true" />
 
+      <div className="more-features-page__frame more-features-page__frame--tight-top more-features-page__frame--tight-bottom">
         <div role="tablist" aria-label={t("more.category_tabs")} className="more-features-tabs">
           {MORE_CATEGORY_LIST.map((category, categoryIndex) => {
             const isActive = category.id === activeCategory.id;
@@ -407,9 +413,6 @@ export function MoreFeaturesPage() {
                 }
               >
                 <span className="more-features-tab__label">{t(category.labelKey)}</span>
-                {isActive ? (
-                  <span className="more-features-tab__copy">{t(category.descriptionKey)}</span>
-                ) : null}
               </button>
             );
           })}
diff --git a/packages/web/src/features/more/routes.ts b/packages/web/src/features/more/routes.ts
index 1f25368af..8257de408 100644
--- a/packages/web/src/features/more/routes.ts
+++ b/packages/web/src/features/more/routes.ts
@@ -36,6 +36,12 @@ export const MORE_CATEGORIES = {
         hintKey: "more.section.settings.agents_hint",
         iconSemantic: "nav.settings.providers",
       },
+      {
+        id: "terminal",
+        labelKey: "label.terminal",
+        hintKey: "more.section.settings.terminal_hint",
+        iconSemantic: "nav.settings.terminal",
+      },
       {
         id: "appearance",
         labelKey: "settings.appearance",
diff --git a/packages/web/src/features/quick-open/components/quick-open.test.tsx b/packages/web/src/features/quick-open/components/quick-open.test.tsx
index 0c7810852..f94e60ce0 100644
--- a/packages/web/src/features/quick-open/components/quick-open.test.tsx
+++ b/packages/web/src/features/quick-open/components/quick-open.test.tsx
@@ -16,7 +16,11 @@ import {
   focusedEditorPaneIdAtomFamily,
 } from "../../agent-panes/atoms/editor-panes";
 import { paneLayoutAtomFamily } from "../../agent-panes/atoms/pane-layout";
-import { activeFilePathAtomFamily } from "../../workspace/atoms/files";
+import {
+  activeEditorTabAtomFamily,
+  activeFilePathAtomFamily,
+  openEditorTabsAtomFamily,
+} from "../../workspace/atoms/files";
 import { QuickOpen } from "./quick-open";
 
 function seedWorkspace(store: ReturnType<typeof createStore>) {
@@ -170,4 +174,55 @@ describe("QuickOpen", () => {
     expect(store.get(focusedEditorPaneIdAtomFamily("ws-test"))).toBeNull();
     expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe("src/app.tsx");
   });
+
+  it("opens .csc quick open selections as canvas tabs", async () => {
+    const sendCommand = vi.fn().mockResolvedValue({
+      files: [
+        {
+          path: ".coder-studio/canvases/auth-gate.csc",
+          name: "auth-gate.csc",
+          kind: "file",
+        },
+      ],
+    });
+    const store = createStore();
+    store.set(wsClientAtom, { sendCommand } as never);
+    seedWorkspace(store);
+    store.set(quickOpenOpenAtom, true);
+
+    render(
+      <Provider store={store}>
+        <QuickOpen />
+      </Provider>
+    );
+
+    fireEvent.change(screen.getByRole("textbox", { name: /Go to File|跳转到文件/i }), {
+      target: { value: "auth" },
+    });
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(150);
+    });
+
+    fireEvent.click(screen.getByRole("option", { name: /auth-gate\.csc/i }));
+
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBeNull();
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/auth-gate.csc",
+        title: "auth-gate",
+        sourcePath: ".coder-studio/canvases/auth-gate.csc",
+        canvasId: ".coder-studio/canvases/auth-gate.csc",
+      },
+    ]);
+    expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual({
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/auth-gate.csc",
+      title: "auth-gate",
+      sourcePath: ".coder-studio/canvases/auth-gate.csc",
+      canvasId: ".coder-studio/canvases/auth-gate.csc",
+    });
+    expect(store.get(quickOpenOpenAtom)).toBe(false);
+  });
 });
diff --git a/packages/web/src/features/quick-open/components/quick-open.tsx b/packages/web/src/features/quick-open/components/quick-open.tsx
index 840aedc70..2a50d053b 100644
--- a/packages/web/src/features/quick-open/components/quick-open.tsx
+++ b/packages/web/src/features/quick-open/components/quick-open.tsx
@@ -148,11 +148,14 @@ export function QuickOpen() {
 
           if (event.key === "Enter" && activeResult && workspaceId) {
             event.preventDefault();
-            void openWorkspaceFile({
-              workspaceId,
-              path: activeResult.path,
-              source: "manual",
-            });
+            void openWorkspaceFile(
+              {
+                workspaceId,
+                path: activeResult.path,
+                source: "manual",
+              },
+              { openTarget: "navigate" }
+            );
             setOpen(false);
           }
         }}
@@ -201,11 +204,14 @@ export function QuickOpen() {
                       return;
                     }
 
-                    void openWorkspaceFile({
-                      workspaceId,
-                      path: file.path,
-                      source: "manual",
-                    });
+                    void openWorkspaceFile(
+                      {
+                        workspaceId,
+                        path: file.path,
+                        source: "manual",
+                      },
+                      { openTarget: "navigate" }
+                    );
                     setOpen(false);
                   }}
                 >
diff --git a/packages/web/src/features/settings/components/config-editor.test.tsx b/packages/web/src/features/settings/components/config-editor.test.tsx
index cf44edf92..de6d73b95 100644
--- a/packages/web/src/features/settings/components/config-editor.test.tsx
+++ b/packages/web/src/features/settings/components/config-editor.test.tsx
@@ -181,6 +181,22 @@ describe("ConfigEditor", () => {
     );
   });
 
+  it("wraps the editor in a dedicated fill-height viewport container", async () => {
+    const { container } = renderConfigEditor();
+
+    await waitFor(() => {
+      expect(screen.getByTestId("monaco-host")).toBeInTheDocument();
+    });
+
+    const editorViewport = container.querySelector(".config-card-editor-slot--fill-height");
+
+    expect(editorViewport).not.toBeNull();
+    expect(editorViewport).toContainElement(screen.getByTestId("monaco-host"));
+    expect(editorViewport).toContainElement(
+      screen.getByRole("textbox", { name: "Config editor content" })
+    );
+  });
+
   it("renders the shared spinner primitive while a save is in flight", async () => {
     const user = userEvent.setup();
     let resolveSave: ((value: { success: boolean; backupPath: string | null }) => void) | undefined;
diff --git a/packages/web/src/features/settings/components/config-editor.tsx b/packages/web/src/features/settings/components/config-editor.tsx
index a16948040..fcdd573f3 100644
--- a/packages/web/src/features/settings/components/config-editor.tsx
+++ b/packages/web/src/features/settings/components/config-editor.tsx
@@ -322,13 +322,17 @@ export function ConfigEditor({
             />
           )}
 
-          <MonacoHost
-            filePath={configPath}
-            content={content}
-            onContentChange={handleContentChange}
-            standalone
-            visible={visible}
-          />
+          <div
+            className={`config-card-editor-slot ${fillHeight ? "config-card-editor-slot--fill-height" : ""}`}
+          >
+            <MonacoHost
+              filePath={configPath}
+              content={content}
+              onContentChange={handleContentChange}
+              standalone
+              visible={visible}
+            />
+          </div>
 
           {/* Actions */}
           <div className="config-card-actions">
diff --git a/packages/web/src/features/settings/components/settings-page.test.tsx b/packages/web/src/features/settings/components/settings-page.test.tsx
index b4866d246..5ac0fda45 100644
--- a/packages/web/src/features/settings/components/settings-page.test.tsx
+++ b/packages/web/src/features/settings/components/settings-page.test.tsx
@@ -1,4 +1,8 @@
-import type { MonitoringResponse, MonitoringSettings } from "@coder-studio/core";
+import type {
+  MonitoringResponse,
+  MonitoringSettings,
+  TerminalProfilesListResult,
+} from "@coder-studio/core";
 import { act, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import { createStore, Provider } from "jotai";
 import { BrowserRouter, MemoryRouter } from "react-router-dom";
@@ -138,6 +142,19 @@ const DEFAULT_PROVIDER_LIST = [
   },
 ] as const;
 
+const DEFAULT_TERMINAL_PROFILES: TerminalProfilesListResult = {
+  profiles: [
+    {
+      id: "detected:bash",
+      label: "Bash",
+      source: "detected",
+      runtime: "native",
+      icon: "terminal",
+    },
+  ],
+  resolvedDefaultProfileId: "detected:bash",
+};
+
 function buildSettingsDashboard(
   overrides: {
     errorMessage?: string;
@@ -259,6 +276,10 @@ function createDefaultCommandHandler(overrides?: {
       return overrides?.providers ?? DEFAULT_PROVIDER_LIST;
     }
 
+    if (op === "terminal.profiles.list") {
+      return DEFAULT_TERMINAL_PROFILES;
+    }
+
     if (op === "settings.previewCommand") {
       return overrides?.preview?.(args) ?? { preview: "preview" };
     }
@@ -343,7 +364,7 @@ function renderSettingsPage(
 }
 
 function renderEmbeddedSettingsPage(
-  section: "general" | "providers" | "appearance" | "shortcuts" | "about",
+  section: "general" | "providers" | "terminal" | "appearance" | "shortcuts" | "about",
   options: {
     aboutView?: "all" | "product" | "update-status" | "auto-update";
     store?: ReturnType<typeof createConnectedStore>;
@@ -616,6 +637,9 @@ describe("SettingsPage", () => {
     expect(
       desktopView.container.querySelector('[data-icon-semantic="nav.settings.providers"]')
     ).toBeTruthy();
+    expect(
+      desktopView.container.querySelector('[data-icon-semantic="nav.settings.terminal"]')
+    ).toBeTruthy();
     expect(
       desktopView.container.querySelector('[data-icon-semantic="nav.settings.appearance"]')
     ).toBeTruthy();
@@ -653,6 +677,9 @@ describe("SettingsPage", () => {
     expect(
       mobileView.container.querySelector('[data-icon-semantic="nav.settings.providers"]')
     ).toBeTruthy();
+    expect(
+      mobileView.container.querySelector('[data-icon-semantic="nav.settings.terminal"]')
+    ).toBeTruthy();
     expect(
       mobileView.container.querySelector('[data-icon-semantic="nav.settings.appearance"]')
     ).toBeTruthy();
@@ -978,7 +1005,41 @@ describe("SettingsPage", () => {
       .getAllByRole("button")
       .map((button) => button.textContent?.trim() ?? "");
 
-    expect(labels).toEqual(["通用", "Agents", "外观", "快捷键"]);
+    expect(labels).toEqual(["通用", "Agents", "终端", "外观", "快捷键"]);
+  });
+
+  it("groups terminal with workspace/runtime settings on mobile", async () => {
+    viewportMocks.viewport = "mobile";
+    const store = createConnectedStore(vi.fn().mockResolvedValue({}));
+
+    const view = renderSettingsPage(store);
+
+    const root = await waitFor(() => {
+      const element = view.container.querySelector(".settings-mobile-root");
+      if (!(element instanceof HTMLElement)) {
+        throw new Error("Settings mobile root did not render");
+      }
+      return element;
+    });
+    const groups = root.querySelectorAll(".settings-mobile-group");
+
+    expect(groups).toHaveLength(2);
+    expect(
+      within(groups[0] as HTMLElement)
+        .getAllByRole("button")
+        .map(
+          (button) =>
+            button.querySelector(".settings-mobile-item__label")?.textContent?.trim() ?? ""
+        )
+    ).toEqual(["通用", "Agents", "终端"]);
+    expect(
+      within(groups[1] as HTMLElement)
+        .getAllByRole("button")
+        .map(
+          (button) =>
+            button.querySelector(".settings-mobile-item__label")?.textContent?.trim() ?? ""
+        )
+    ).toEqual(["外观", "快捷键"]);
   });
 
   it("does not expose diagnostics in the visible settings navigation", async () => {
@@ -2897,10 +2958,10 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     await waitFor(() => {
-      expect(screen.getByText("通知")).toBeInTheDocument();
+      expect(screen.getByText("终端渲染器")).toBeInTheDocument();
     });
 
     const detailBody = document.querySelector(".settings-body--mobile");
@@ -2998,16 +3059,19 @@ describe("SettingsPage", () => {
     renderSettingsPage(store);
     fireEvent.click(screen.getByRole("button", { name: "外观" }));
 
-    const appearanceGroupTitles = (await screen.findAllByRole("heading", { level: 3 })).map(
-      (heading) => heading.textContent
-    );
     const themePicker = await screen.findByRole("button", { name: "主题 Mint 深色" });
+    const appearanceSurface = themePicker.closest(".settings-content-surface");
+    const appearanceGroupTitles = within(appearanceSurface as HTMLElement)
+      .getAllByRole("heading", { level: 3 })
+      .map((heading) => heading.textContent);
 
     expect(appearanceGroupTitles[0]).toBe("主题");
     expect(themePicker).toHaveAccessibleDescription("选择应用主题");
     expect(screen.queryByRole("group", { name: "语言" })).not.toBeInTheDocument();
     expect(screen.queryByRole("group", { name: "终端渲染器" })).not.toBeInTheDocument();
     expect(screen.queryByRole("switch", { name: "选中自动复制" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("spinbutton", { name: "桌面端终端字号" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("spinbutton", { name: "移动端终端字号" })).not.toBeInTheDocument();
     expect(themePicker).toHaveAttribute("aria-haspopup", "listbox");
 
     fireEvent.click(screen.getByRole("button", { name: "通用" }));
@@ -3016,6 +3080,9 @@ describe("SettingsPage", () => {
 
     expect(screen.getByRole("group", { name: "语言" })).toHaveAccessibleDescription("选择界面语言");
     expect(chineseLanguagePill).toHaveAttribute("aria-pressed", "true");
+    expect(screen.queryByRole("group", { name: "终端渲染器" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("switch", { name: "选中自动复制" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("heading", { name: "终端配置" })).not.toBeInTheDocument();
   });
 
   it("hydrates appearance personalization controls from settings.get and syncs the global atom", async () => {
@@ -3307,7 +3374,7 @@ describe("SettingsPage", () => {
     expect(store.get(appearancePersonalizationAtom).common.backgroundAssetId).toBeNull();
   });
 
-  it("renders terminal option groups through shared pills in general settings", async () => {
+  it("renders terminal option groups in the terminal settings section", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {
@@ -3319,7 +3386,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     const standardRendererPill = await screen.findByRole("button", { name: "标准" });
 
@@ -3331,6 +3398,362 @@ describe("SettingsPage", () => {
     expect(standardRendererPill).toHaveAttribute("aria-pressed", "true");
   });
 
+  it("hydrates terminal profile settings from settings.get and terminal.profiles.list", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "settings.get") {
+        return {
+          "terminal.defaultProfileId": "custom:ops",
+          "terminal.profiles": [
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              command: "/usr/bin/env",
+              args: ["bash", "-l"],
+            },
+          ],
+        };
+      }
+      if (op === "terminal.profiles.list") {
+        return {
+          profiles: [
+            ...DEFAULT_TERMINAL_PROFILES.profiles,
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              source: "custom",
+              runtime: "native",
+              icon: "terminal",
+            },
+          ],
+          configuredDefaultProfileId: "custom:ops",
+          resolvedDefaultProfileId: "custom:ops",
+        } satisfies TerminalProfilesListResult;
+      }
+      return {};
+    });
+    const store = createConnectedStore(sendCommand);
+
+    renderSettingsPage(store);
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
+
+    expect(await screen.findByRole("heading", { name: "终端配置" })).toBeInTheDocument();
+    expect(sendCommand).toHaveBeenCalledWith("settings.get", {}, undefined);
+    expect(sendCommand).toHaveBeenCalledWith("terminal.profiles.list", {}, undefined);
+    const defaultProfileTrigger = screen.getByRole("button", { name: /默认终端配置/ });
+    expect(defaultProfileTrigger).toHaveAttribute("aria-haspopup", "listbox");
+    expect(defaultProfileTrigger).toHaveTextContent("Ops Shell");
+    const currentDefaultRow = screen.getByText("当前默认").closest(".settings-info-row");
+    expect(currentDefaultRow).not.toBeNull();
+    expect(within(currentDefaultRow as HTMLElement).getByText("Ops Shell")).toBeInTheDocument();
+    expect(screen.getAllByText("Bash").length).toBeGreaterThan(0);
+    expect(screen.getByText("检测到")).toBeInTheDocument();
+    expect(screen.getAllByText("Ops Shell").length).toBeGreaterThan(0);
+    expect(screen.getByText("/usr/bin/env bash -l")).toBeInTheDocument();
+  });
+
+  it("exposes a terminal profiles anchor from the embedded terminal section", async () => {
+    const store = createConnectedStore(createDefaultCommandHandler());
+
+    renderEmbeddedSettingsPage("terminal", { store });
+
+    const terminalProfilesHeading = await screen.findByRole("heading", { name: "终端配置" });
+    const terminalProfilesSection = document.getElementById("terminal-profiles");
+
+    expect(terminalProfilesSection).not.toBeNull();
+    expect(terminalProfilesSection).toContainElement(terminalProfilesHeading);
+    expect(terminalProfilesSection).toHaveClass("settings-group");
+  });
+
+  it("shows the resolved terminal default when no explicit terminal default is configured", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "settings.get") {
+        return {};
+      }
+      if (op === "terminal.profiles.list") {
+        return DEFAULT_TERMINAL_PROFILES;
+      }
+      return {};
+    });
+    const store = createConnectedStore(sendCommand);
+
+    renderSettingsPage(store);
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
+
+    expect(await screen.findByRole("button", { name: /默认终端配置/ })).toHaveTextContent(
+      "系统默认"
+    );
+    const currentDefaultRow = screen.getByText("当前默认").closest(".settings-info-row");
+    expect(currentDefaultRow).not.toBeNull();
+    expect(within(currentDefaultRow as HTMLElement).getByText("Bash")).toBeInTheDocument();
+  });
+
+  it("saves a new custom terminal profile and sets it as default", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "settings.get") {
+        return {};
+      }
+      if (op === "terminal.profiles.list") {
+        return DEFAULT_TERMINAL_PROFILES;
+      }
+      return {};
+    });
+    const store = createConnectedStore(sendCommand);
+
+    renderSettingsPage(store);
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
+
+    fireEvent.change(await screen.findByRole("textbox", { name: "配置名称" }), {
+      target: { value: "Ops Shell" },
+    });
+    fireEvent.change(screen.getByRole("textbox", { name: "命令" }), {
+      target: { value: "/usr/bin/env" },
+    });
+    fireEvent.change(screen.getByRole("textbox", { name: "参数" }), {
+      target: { value: "bash\n-l" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "保存自定义配置" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "settings.update",
+        {
+          settings: {
+            terminal: {
+              defaultProfileId: "custom:ops-shell",
+              profiles: [
+                {
+                  id: "custom:ops-shell",
+                  label: "Ops Shell",
+                  command: "/usr/bin/env",
+                  args: ["bash", "-l"],
+                },
+              ],
+            },
+          },
+        },
+        undefined
+      );
+    });
+  });
+
+  it("edits and deletes an existing custom terminal profile, clearing it when it was default", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "settings.get") {
+        return {
+          "terminal.defaultProfileId": "custom:ops",
+          "terminal.profiles": [
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              command: "/bin/bash",
+              args: ["-l"],
+              icon: "rocket",
+            },
+          ],
+        };
+      }
+      if (op === "terminal.profiles.list") {
+        return {
+          profiles: [
+            ...DEFAULT_TERMINAL_PROFILES.profiles,
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              source: "custom",
+              runtime: "native",
+              icon: "terminal",
+            },
+          ],
+          configuredDefaultProfileId: "custom:ops",
+          resolvedDefaultProfileId: "custom:ops",
+        } satisfies TerminalProfilesListResult;
+      }
+      return {};
+    });
+    const store = createConnectedStore(sendCommand);
+
+    renderSettingsPage(store);
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
+
+    fireEvent.click(await screen.findByRole("button", { name: "编辑 Ops Shell" }));
+    fireEvent.change(screen.getByRole("textbox", { name: "命令" }), {
+      target: { value: "/bin/zsh" },
+    });
+    fireEvent.change(screen.getByRole("textbox", { name: "参数" }), {
+      target: { value: "" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "保存自定义配置" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "settings.update",
+        {
+          settings: {
+            terminal: {
+              defaultProfileId: "custom:ops",
+              profiles: [
+                {
+                  id: "custom:ops",
+                  label: "Ops Shell",
+                  command: "/bin/zsh",
+                  args: [],
+                  icon: "rocket",
+                },
+              ],
+            },
+          },
+        },
+        undefined
+      );
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "删除 Ops Shell" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "settings.update",
+        {
+          settings: {
+            terminal: {
+              defaultProfileId: null,
+              profiles: [],
+            },
+          },
+        },
+        undefined
+      );
+    });
+  });
+
+  it("clears the configured terminal default when the system-default option is selected", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "settings.get") {
+        return {
+          "terminal.defaultProfileId": "custom:ops",
+          "terminal.profiles": [
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              command: "/usr/bin/env",
+              args: ["bash"],
+            },
+          ],
+        };
+      }
+      if (op === "terminal.profiles.list") {
+        return {
+          profiles: [
+            ...DEFAULT_TERMINAL_PROFILES.profiles,
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              source: "custom",
+              runtime: "native",
+              icon: "terminal",
+            },
+          ],
+          configuredDefaultProfileId: "custom:ops",
+          resolvedDefaultProfileId: "custom:ops",
+        } satisfies TerminalProfilesListResult;
+      }
+      return {};
+    });
+    const store = createConnectedStore(sendCommand);
+
+    renderSettingsPage(store);
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
+
+    fireEvent.click(await screen.findByRole("button", { name: /默认终端配置/ }));
+    fireEvent.click(await screen.findByRole("option", { name: "系统默认" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "settings.update",
+        {
+          settings: {
+            terminal: {
+              defaultProfileId: null,
+              profiles: [
+                {
+                  id: "custom:ops",
+                  label: "Ops Shell",
+                  command: "/usr/bin/env",
+                  args: ["bash"],
+                },
+              ],
+            },
+          },
+        },
+        undefined
+      );
+    });
+  });
+
+  it("preserves custom profile icons when only the default terminal profile selection changes", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "settings.get") {
+        return {
+          "terminal.defaultProfileId": "custom:ops",
+          "terminal.profiles": [
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              command: "/usr/bin/env",
+              args: ["bash"],
+              icon: "rocket",
+            },
+          ],
+        };
+      }
+      if (op === "terminal.profiles.list") {
+        return {
+          profiles: [
+            ...DEFAULT_TERMINAL_PROFILES.profiles,
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              source: "custom",
+              runtime: "native",
+              icon: "rocket",
+            },
+          ],
+          configuredDefaultProfileId: "custom:ops",
+          resolvedDefaultProfileId: "custom:ops",
+        } satisfies TerminalProfilesListResult;
+      }
+      return {};
+    });
+    const store = createConnectedStore(sendCommand);
+
+    renderSettingsPage(store);
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
+    fireEvent.click(await screen.findByRole("button", { name: /默认终端配置/ }));
+    fireEvent.click(await screen.findByRole("option", { name: "Bash" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "settings.update",
+        {
+          settings: {
+            terminal: {
+              defaultProfileId: "detected:bash",
+              profiles: [
+                {
+                  id: "custom:ops",
+                  label: "Ops Shell",
+                  command: "/usr/bin/env",
+                  args: ["bash"],
+                  icon: "rocket",
+                },
+              ],
+            },
+          },
+        },
+        undefined
+      );
+    });
+  });
+
   it("hydrates lsp runtime mode from settings.get", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
@@ -3447,7 +3870,7 @@ describe("SettingsPage", () => {
     expect(screen.getByRole("button", { name: "Off" })).toHaveAttribute("aria-pressed", "false");
   });
 
-  it("keeps copy-on-select visible on desktop general settings", async () => {
+  it("keeps copy-on-select visible on desktop terminal settings", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {
@@ -3459,12 +3882,12 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     expect(await screen.findByRole("switch", { name: "选中自动复制" })).toBeInTheDocument();
   });
 
-  it("shows copy-on-select on mobile general settings with mobile-specific hint", async () => {
+  it("shows copy-on-select on mobile terminal settings with mobile-specific hint", async () => {
     viewportMocks.viewport = "mobile";
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
@@ -3477,7 +3900,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     expect(await screen.findByRole("switch", { name: "选中自动复制" })).toBeInTheDocument();
     expect(screen.getByText("选中文本后自动复制到系统剪贴板")).toBeInTheDocument();
@@ -3738,7 +4161,7 @@ describe("SettingsPage", () => {
     expect(document.documentElement).toHaveAttribute("data-theme", "graphite-dark");
   });
 
-  it("updates terminal renderer selection through the shared general pills", async () => {
+  it("updates terminal renderer selection through the terminal section pills", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {
@@ -3750,7 +4173,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
     fireEvent.click(await screen.findByRole("button", { name: "兼容模式" }));
 
     await waitFor(() => {
@@ -3778,7 +4201,7 @@ describe("SettingsPage", () => {
     expect(screen.getByRole("button", { name: "标准" })).toHaveAttribute("aria-pressed", "false");
   });
 
-  it("preserves terminal renderer selection when a stale settings load resolves afterward in general settings", async () => {
+  it("preserves terminal renderer selection when a stale settings load resolves afterward in terminal settings", async () => {
     let resolveSettingsGet: ((value: Record<string, unknown>) => void) | undefined;
     const settingsGetPromise = new Promise<Record<string, unknown>>((resolve) => {
       resolveSettingsGet = resolve;
@@ -3792,7 +4215,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
     fireEvent.click(await screen.findByRole("button", { name: "兼容模式" }));
 
     await waitFor(() => {
@@ -3824,7 +4247,7 @@ describe("SettingsPage", () => {
     expect(screen.getByRole("button", { name: "标准" })).toHaveAttribute("aria-pressed", "false");
   });
 
-  it("renders the copy-on-select switch from loaded general settings", async () => {
+  it("renders the copy-on-select switch from loaded terminal settings", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {
@@ -3836,7 +4259,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     await waitFor(() => {
       expect(screen.getByRole("switch", { name: "选中自动复制" })).toHaveAttribute(
@@ -3852,7 +4275,7 @@ describe("SettingsPage", () => {
     });
   });
 
-  it("updates copy-on-select through the general switch and syncs the global atom", async () => {
+  it("updates copy-on-select through the terminal switch and syncs the global atom", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {
@@ -3864,7 +4287,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
     fireEvent.click(await screen.findByRole("switch", { name: "选中自动复制" }));
 
     await waitFor(() => {
@@ -3889,7 +4312,7 @@ describe("SettingsPage", () => {
     });
   });
 
-  it("renders copy-on-select from the terminal preferences atom before general settings load resolves", async () => {
+  it("renders copy-on-select from the terminal preferences atom before terminal settings load resolves", async () => {
     let resolveSettingsGet: ((value: Record<string, unknown>) => void) | undefined;
     const settingsGetPromise = new Promise<Record<string, unknown>>((resolve) => {
       resolveSettingsGet = resolve;
@@ -3909,7 +4332,7 @@ describe("SettingsPage", () => {
     });
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     expect(await screen.findByRole("switch", { name: "选中自动复制" })).toHaveAttribute(
       "aria-checked",
@@ -3922,7 +4345,7 @@ describe("SettingsPage", () => {
     });
   });
 
-  it("preserves copy-on-select when a stale general settings load resolves afterward", async () => {
+  it("preserves copy-on-select when a stale terminal settings load resolves afterward", async () => {
     let resolveSettingsGet: ((value: Record<string, unknown>) => void) | undefined;
     const settingsGetPromise = new Promise<Record<string, unknown>>((resolve) => {
       resolveSettingsGet = resolve;
@@ -3936,7 +4359,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
     fireEvent.click(await screen.findByRole("switch", { name: "选中自动复制" }));
 
     await waitFor(() => {
@@ -3970,7 +4393,7 @@ describe("SettingsPage", () => {
     });
   });
 
-  it("defaults copy-on-select to enabled when general settings do not provide a value", async () => {
+  it("defaults copy-on-select to enabled when terminal settings do not provide a value", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {};
@@ -3980,7 +4403,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "通用" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     await waitFor(() => {
       expect(screen.getByRole("switch", { name: "选中自动复制" })).toHaveAttribute(
@@ -4009,7 +4432,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "外观" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     const desktopInput = await screen.findByRole("spinbutton", { name: "桌面端终端字号" });
     const mobileInput = await screen.findByRole("spinbutton", { name: "移动端终端字号" });
@@ -4025,7 +4448,7 @@ describe("SettingsPage", () => {
     });
   });
 
-  it("falls back to the legacy shared terminal font size when split settings are absent", async () => {
+  it("falls back to the legacy shared terminal font size when split settings are absent in terminal settings", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {
@@ -4037,7 +4460,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "外观" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     const desktopInput = await screen.findByRole("spinbutton", { name: "桌面端终端字号" });
     const mobileInput = await screen.findByRole("spinbutton", { name: "移动端终端字号" });
@@ -4054,7 +4477,7 @@ describe("SettingsPage", () => {
     });
   });
 
-  it("updates desktop terminal font size through the appearance input and syncs the global atom", async () => {
+  it("updates desktop terminal font size through the terminal input and syncs the global atom", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {
@@ -4067,7 +4490,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "外观" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     const input = await screen.findByRole("spinbutton", { name: "桌面端终端字号" });
 
@@ -4109,7 +4532,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "外观" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     const input = await screen.findByRole("spinbutton", { name: "桌面端终端字号" });
 
@@ -4142,7 +4565,7 @@ describe("SettingsPage", () => {
     ).toHaveLength(1);
   });
 
-  it("updates mobile terminal font size through the appearance input without changing desktop size", async () => {
+  it("updates mobile terminal font size through the terminal input without changing desktop size", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {
@@ -4155,7 +4578,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "外观" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     const input = await screen.findByRole("spinbutton", { name: "移动端终端字号" });
 
@@ -4184,7 +4607,7 @@ describe("SettingsPage", () => {
     });
   });
 
-  it("shows a validation error and restores the current desktop terminal font size for out-of-range values", async () => {
+  it("shows a validation error and restores the current desktop terminal font size for out-of-range values in terminal settings", async () => {
     const sendCommand = vi.fn().mockImplementation(async (op: string) => {
       if (op === "settings.get") {
         return {
@@ -4197,7 +4620,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "外观" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     const input = await screen.findByRole("spinbutton", { name: "桌面端终端字号" });
     await waitFor(() => {
@@ -4231,7 +4654,7 @@ describe("SettingsPage", () => {
     });
   });
 
-  it("preserves desktop terminal font size when a stale appearance settings load resolves afterward", async () => {
+  it("preserves desktop terminal font size when a stale terminal settings load resolves afterward", async () => {
     let resolveSettingsGet: ((value: Record<string, unknown>) => void) | undefined;
     const settingsGetPromise = new Promise<Record<string, unknown>>((resolve) => {
       resolveSettingsGet = resolve;
@@ -4245,7 +4668,7 @@ describe("SettingsPage", () => {
     const store = createConnectedStore(sendCommand);
 
     renderSettingsPage(store);
-    fireEvent.click(screen.getByRole("button", { name: "外观" }));
+    fireEvent.click(screen.getByRole("button", { name: "终端" }));
 
     const input = await screen.findByRole("spinbutton", { name: "桌面端终端字号" });
     fireEvent.change(input, { target: { value: "17" } });
@@ -4524,7 +4947,7 @@ describe("SettingsPage", () => {
   it("renders embedded settings content without standalone page chrome", async () => {
     renderEmbeddedSettingsPage("general");
 
-    expect(screen.queryByRole("heading", { level: 1, name: "设置" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("heading", { level: 3, name: "设置" })).not.toBeInTheDocument();
     expect(screen.queryByTestId("settings-mobile-root")).toBeNull();
     expect(await screen.findByText("通知")).toBeInTheDocument();
     expect(document.querySelector(".settings-sidebar")).toBeNull();
diff --git a/packages/web/src/features/settings/components/settings-page.tsx b/packages/web/src/features/settings/components/settings-page.tsx
index 0b0a153b9..17b976ce4 100644
--- a/packages/web/src/features/settings/components/settings-page.tsx
+++ b/packages/web/src/features/settings/components/settings-page.tsx
@@ -5,6 +5,7 @@
  */
 
 import {
+  type CustomTerminalProfile,
   createDefaultMonitoringSettings,
   createDefaultUpdateSettings,
   DEFAULT_SUPERVISOR_EVALUATION_TIMEOUT_SEC,
@@ -30,6 +31,7 @@ import {
   resolveSupervisorRetryOnTimeout,
   resolveUpdateAutoCheckEnabled,
   resolveUpdateCheckIntervalSec,
+  type TerminalProfilesListResult,
 } from "@coder-studio/core";
 import { useAtom, useAtomValue, useSetAtom, useStore } from "jotai";
 import { Check, ChevronRight } from "lucide-react";
@@ -58,12 +60,11 @@ import { useMonitoringData } from "../../monitoring";
 import { notificationPreferencesAtom } from "../../notifications/atoms";
 import { MobilePageHeader } from "../../shared/components/mobile-page-header";
 import { PageHeader } from "../../shared/components/page-header";
+import { resetTerminalProfilesAtom } from "../../terminal-panel/actions/use-terminal-profiles";
 import {
   getTerminalFontSizePreference,
   hasExplicitTerminalFontSizeSetting,
   hasLegacyTerminalFontSizeSetting,
-  MAX_TERMINAL_FONT_SIZE,
-  MIN_TERMINAL_FONT_SIZE,
   resolveTerminalCopyOnSelectSetting,
   resolveTerminalFontSizeSetting,
   terminalPreferencesAtom,
@@ -80,6 +81,8 @@ import {
   type SettingsSection,
 } from "./settings-sections";
 import { ShortcutsSettings } from "./shortcuts-settings";
+import { type TerminalProfileSettingsChange } from "./terminal-profile-settings";
+import { TerminalSettingsSection } from "./terminal-settings-section";
 import { useSessionGateDispatch } from "./use-session-gate-dispatch";
 
 type NotificationCapabilityStatus = "available" | "limited" | "unsupported";
@@ -100,7 +103,7 @@ type AppearanceAssetScope = "common" | "desktop" | "mobile";
 type AppearanceOverrideTarget = Exclude<AppearanceAssetScope, "common">;
 type EmbeddedSettingsSection = Extract<
   SettingsSection,
-  "general" | "providers" | "appearance" | "shortcuts" | "about" | "monitoring"
+  "general" | "providers" | "terminal" | "appearance" | "shortcuts" | "about" | "monitoring"
 >;
 
 const CORE_THEME_IDS = [
@@ -126,7 +129,6 @@ const SEASONAL_THEME_IDS = [
 ] as const;
 
 const DEFAULT_SETTINGS_SECTION: SettingsSection = SETTINGS_SECTIONS[0].id;
-const TERMINAL_FONT_SIZE_SAVE_THROTTLE_MS = 500;
 const PERSONALIZATION_OVERRIDE_FIELDS = [
   "backgroundAssetId",
   "backgroundDimness",
@@ -196,6 +198,54 @@ function loadProviderAdditionalArgs(
   );
 }
 
+function isCustomTerminalProfileId(value: unknown): value is CustomTerminalProfile["id"] {
+  return typeof value === "string" && value.startsWith("custom:");
+}
+
+function loadCustomTerminalProfiles(settings: Record<string, unknown>): CustomTerminalProfile[] {
+  const value = settings["terminal.profiles"];
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const seen = new Set<string>();
+  const profiles: CustomTerminalProfile[] = [];
+  for (const item of value) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      continue;
+    }
+
+    const record = item as Record<string, unknown>;
+    if (
+      !isCustomTerminalProfileId(record.id) ||
+      typeof record.label !== "string" ||
+      typeof record.command !== "string" ||
+      seen.has(record.id)
+    ) {
+      continue;
+    }
+
+    const label = record.label.trim();
+    const command = record.command.trim();
+    if (!label || !command) {
+      continue;
+    }
+
+    seen.add(record.id);
+    profiles.push({
+      id: record.id,
+      label,
+      command,
+      args: Array.isArray(record.args)
+        ? record.args.filter((arg): arg is string => typeof arg === "string")
+        : [],
+      icon: typeof record.icon === "string" ? record.icon : undefined,
+    });
+  }
+
+  return profiles;
+}
+
 const DEFAULT_PROVIDERS: ProviderInfo[] = [
   { id: "claude", displayName: "Claude" },
   { id: "codex", displayName: "Codex" },
@@ -219,6 +269,8 @@ function getMobileSectionHintKey(section: SettingsSection) {
       return "settings.notifications_channel_hint";
     case "providers":
       return "settings.provider.command_preview_hint";
+    case "terminal":
+      return "settings.terminal_renderer_hint";
     case "analysis":
       return "settings.analysis.hint";
     case "appearance":
@@ -237,7 +289,7 @@ function getMobileSectionHintKey(section: SettingsSection) {
 const MOBILE_SETTINGS_GROUPS = [
   {
     titleKey: "settings.mobile_groups.workspace_runtime",
-    sections: ["general", "providers"],
+    sections: ["general", "providers", "terminal"],
   },
   {
     titleKey: "settings.mobile_groups.interface_interaction",
@@ -407,6 +459,14 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
   const [terminalRenderer, setTerminalRendererState] = useState<"standard" | "compatibility">(
     "standard"
   );
+  const [terminalProfiles, setTerminalProfiles] = useState<TerminalProfile[]>([]);
+  const [customTerminalProfiles, setCustomTerminalProfiles] = useState<CustomTerminalProfile[]>([]);
+  const [configuredTerminalDefaultProfileId, setConfiguredTerminalDefaultProfileId] = useState<
+    string | undefined
+  >(undefined);
+  const [resolvedTerminalDefaultProfileId, setResolvedTerminalDefaultProfileId] = useState<
+    string | null
+  >(null);
   const [providerAdditionalArgsById, setProviderAdditionalArgsById] = useState<
     Record<string, string>
   >({});
@@ -430,6 +490,7 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
   const terminalPreferences = useAtomValue(terminalPreferencesAtom);
   const setNotificationPreferences = useSetAtom(notificationPreferencesAtom);
   const setTerminalPreferences = useSetAtom(terminalPreferencesAtom);
+  const resetTerminalProfiles = useSetAtom(resetTerminalProfilesAtom);
   const setHydratedLspRuntimeMode = useSetAtom(lspRuntimeModeAtom);
   const store = useStore();
   const settingsLoadFailedUnknownRef = useRef(settingsLoadFailedUnknown);
@@ -449,6 +510,7 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
     checkIntervalSec: 0,
   });
   const monitoringSelectionVersionRef = useRef(0);
+  const terminalProfileSelectionVersionRef = useRef(0);
   const detailSection =
     navigationState.kind === "detail" ? navigationState.section : navigationState.lastSection;
   const effectiveSection = embeddedSection ?? detailSection;
@@ -525,11 +587,14 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
         ...updateSelectionVersionRef.current,
       };
       const monitoringSelectionVersionAtRequestStart = monitoringSelectionVersionRef.current;
-      const [settingsResult, providersResult] = await Promise.all([
+      const terminalProfileSelectionVersionAtRequestStart =
+        terminalProfileSelectionVersionRef.current;
+      const [settingsResult, providersResult, terminalProfilesResult] = await Promise.all([
         dispatch<Record<string, unknown>>("settings.get", {}),
         dispatch<ProviderListItem[]>("provider.list", {}),
+        dispatch<TerminalProfilesListResult>("terminal.profiles.list", {}),
       ]);
-      if (settingsResult === null || providersResult === null) {
+      if (settingsResult === null || providersResult === null || terminalProfilesResult === null) {
         return;
       }
 
@@ -554,6 +619,28 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
       const settings = settingsResult.data;
       if (cancelled) return;
       setSettingsLoadError(null);
+      if (
+        terminalProfileSelectionVersionRef.current === terminalProfileSelectionVersionAtRequestStart
+      ) {
+        setCustomTerminalProfiles(loadCustomTerminalProfiles(settings));
+        setConfiguredTerminalDefaultProfileId(
+          typeof terminalProfilesResult.data?.configuredDefaultProfileId === "string"
+            ? terminalProfilesResult.data.configuredDefaultProfileId
+            : typeof settings["terminal.defaultProfileId"] === "string"
+              ? settings["terminal.defaultProfileId"]
+              : undefined
+        );
+        setResolvedTerminalDefaultProfileId(
+          typeof terminalProfilesResult.data?.resolvedDefaultProfileId === "string"
+            ? terminalProfilesResult.data.resolvedDefaultProfileId
+            : null
+        );
+        setTerminalProfiles(
+          terminalProfilesResult.ok && Array.isArray(terminalProfilesResult.data?.profiles)
+            ? terminalProfilesResult.data.profiles
+            : []
+        );
+      }
       if (typeof settings["notifications.enabled"] === "boolean") {
         setNotificationsEnabled(settings["notifications.enabled"]);
       }
@@ -813,6 +900,71 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
     });
   };
 
+  const handleTerminalProfileSettingsChange = async (next: TerminalProfileSettingsChange) => {
+    const previousCustomProfiles = customTerminalProfiles;
+    const previousDefaultProfileId = configuredTerminalDefaultProfileId;
+    const previousResolvedDefaultProfileId = resolvedTerminalDefaultProfileId;
+    terminalProfileSelectionVersionRef.current += 1;
+    const requestVersion = terminalProfileSelectionVersionRef.current;
+    setCustomTerminalProfiles(next.customProfiles);
+    if ("defaultProfileId" in next) {
+      setConfiguredTerminalDefaultProfileId(next.defaultProfileId ?? undefined);
+    }
+
+    const terminalSettings: {
+      profiles: CustomTerminalProfile[];
+      defaultProfileId?: string | null;
+    } = {
+      profiles: next.customProfiles,
+    };
+    if ("defaultProfileId" in next) {
+      terminalSettings.defaultProfileId = next.defaultProfileId ?? null;
+    }
+
+    const result = await dispatch("settings.update", {
+      settings: {
+        terminal: terminalSettings,
+      },
+    });
+
+    if (result === null || !result.ok) {
+      if (terminalProfileSelectionVersionRef.current === requestVersion) {
+        setCustomTerminalProfiles(previousCustomProfiles);
+        setConfiguredTerminalDefaultProfileId(previousDefaultProfileId);
+        setResolvedTerminalDefaultProfileId(previousResolvedDefaultProfileId);
+      }
+      if (result !== null && !result.ok) {
+        setSettingsLoadError(result.error?.message ?? settingsLoadFailedUnknownRef.current);
+      }
+      return false;
+    }
+
+    const refreshedProfilesResult = await dispatch<TerminalProfilesListResult>(
+      "terminal.profiles.list",
+      {}
+    );
+    if (
+      refreshedProfilesResult?.ok &&
+      Array.isArray(refreshedProfilesResult.data?.profiles) &&
+      terminalProfileSelectionVersionRef.current === requestVersion
+    ) {
+      setTerminalProfiles(refreshedProfilesResult.data.profiles);
+      setConfiguredTerminalDefaultProfileId(
+        typeof refreshedProfilesResult.data.configuredDefaultProfileId === "string"
+          ? refreshedProfilesResult.data.configuredDefaultProfileId
+          : undefined
+      );
+      setResolvedTerminalDefaultProfileId(
+        typeof refreshedProfilesResult.data.resolvedDefaultProfileId === "string"
+          ? refreshedProfilesResult.data.resolvedDefaultProfileId
+          : null
+      );
+    }
+
+    resetTerminalProfiles();
+    return true;
+  };
+
   const handleUpdateAutoCheckChange = async (value: boolean) => {
     updateSelectionVersionRef.current.autoCheckEnabled += 1;
     setUpdateAutoCheckEnabled(value);
@@ -929,10 +1081,6 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
             setSupervisorRetryOnEvaluatorError={setSupervisorRetryOnEvaluatorError}
             lspRuntimeMode={lspRuntimeMode}
             onLspRuntimeModeSelect={handleLspRuntimeModeSelection}
-            terminalRenderer={terminalRenderer}
-            setTerminalRenderer={handleTerminalRendererSelection}
-            terminalCopyOnSelect={terminalPreferences.copyOnSelect}
-            setTerminalCopyOnSelect={handleTerminalCopyOnSelectSelection}
             locale={locale}
             setLocale={handleLocaleSelection}
           />
@@ -950,11 +1098,7 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
       case "appearance":
         return (
           <AppearanceSettings
-            desktopTerminalFontSize={getTerminalFontSizePreference(terminalPreferences, "desktop")}
-            mobileTerminalFontSize={getTerminalFontSizePreference(terminalPreferences, "mobile")}
             personalization={personalization}
-            setDesktopTerminalFontSize={handleDesktopTerminalFontSizeSelection}
-            setMobileTerminalFontSize={handleMobileTerminalFontSizeSelection}
             savePersonalization={saveAppearancePersonalization}
             theme={theme}
             setTheme={handleThemeSelection}
@@ -985,6 +1129,24 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
             onLayoutModeChange={setContentLayoutMode}
           />
         );
+      case "terminal":
+        return (
+          <TerminalSettingsSection
+            terminalRenderer={terminalRenderer}
+            setTerminalRenderer={handleTerminalRendererSelection}
+            terminalCopyOnSelect={terminalPreferences.copyOnSelect}
+            setTerminalCopyOnSelect={handleTerminalCopyOnSelectSelection}
+            terminalProfiles={terminalProfiles}
+            customTerminalProfiles={customTerminalProfiles}
+            configuredTerminalDefaultProfileId={configuredTerminalDefaultProfileId}
+            resolvedTerminalDefaultProfileId={resolvedTerminalDefaultProfileId}
+            onTerminalProfileSettingsChange={handleTerminalProfileSettingsChange}
+            desktopTerminalFontSize={getTerminalFontSizePreference(terminalPreferences, "desktop")}
+            mobileTerminalFontSize={getTerminalFontSizePreference(terminalPreferences, "mobile")}
+            setDesktopTerminalFontSize={handleDesktopTerminalFontSizeSelection}
+            setMobileTerminalFontSize={handleMobileTerminalFontSizeSelection}
+          />
+        );
       case "shortcuts":
         return <ShortcutsSettings />;
       case "about":
@@ -1100,7 +1262,7 @@ export function SettingsPage({ embeddedSection, aboutView = "all" }: SettingsPag
         ) : (
           <PageHeader
             title={t("settings.title")}
-            titleAs="h1"
+            titleAs="h3"
             level="secondary"
             onBack={handleBack}
             backLabel={t("action.back")}
@@ -1218,10 +1380,6 @@ interface GeneralSettingsProps {
   setSupervisorRetryOnEvaluatorError: (value: boolean) => void;
   lspRuntimeMode: LspRuntimeMode;
   onLspRuntimeModeSelect: (value: LspRuntimeMode) => Promise<void>;
-  terminalRenderer: "standard" | "compatibility";
-  setTerminalRenderer: (value: "standard" | "compatibility") => void;
-  terminalCopyOnSelect: boolean;
-  setTerminalCopyOnSelect: (value: boolean) => void;
   locale: string;
   setLocale: (value: "zh" | "en") => void;
 }
@@ -1272,24 +1430,6 @@ function parseSupervisorRetryDelayInput(value: string): number | null {
   return parsed;
 }
 
-function parseTerminalFontSizeInput(value: string): number | null {
-  const trimmed = value.trim();
-  if (!/^\d+$/.test(trimmed)) {
-    return null;
-  }
-
-  const parsed = Number(trimmed);
-  if (
-    !Number.isSafeInteger(parsed) ||
-    parsed < MIN_TERMINAL_FONT_SIZE ||
-    parsed > MAX_TERMINAL_FONT_SIZE
-  ) {
-    return null;
-  }
-
-  return parsed;
-}
-
 function parseBoundedInteger(value: string, min: number, max: number): number | null {
   const trimmed = value.trim();
   if (!/^\d+$/.test(trimmed)) {
@@ -1340,10 +1480,6 @@ function GeneralSettings({
   setSupervisorRetryOnEvaluatorError,
   lspRuntimeMode,
   onLspRuntimeModeSelect,
-  terminalRenderer,
-  setTerminalRenderer,
-  terminalCopyOnSelect,
-  setTerminalCopyOnSelect,
   locale,
   setLocale,
 }: GeneralSettingsProps) {
@@ -1352,12 +1488,8 @@ function GeneralSettings({
   const notificationsDescId = useId();
   const soundLabelId = useId();
   const soundDescId = useId();
-  const terminalRendererTitleId = useId();
-  const terminalRendererDescId = useId();
   const lspRuntimeModeTitleId = useId();
   const lspRuntimeModeDescId = useId();
-  const copyOnSelectLabelId = useId();
-  const copyOnSelectDescId = useId();
   const languageTitleId = useId();
   const languageDescId = useId();
   const dispatch = useSessionGateDispatch();
@@ -1700,64 +1832,6 @@ function GeneralSettings({
         </div>
       </div>
 
-      <div className="settings-group">
-        <h3 className="settings-group-title" id={terminalRendererTitleId}>
-          {t("settings.terminal_renderer")}
-        </h3>
-        <p className="settings-group-desc" id={terminalRendererDescId}>
-          {t("settings.terminal_renderer_hint")}
-        </p>
-
-        <div
-          aria-describedby={terminalRendererDescId}
-          aria-labelledby={terminalRendererTitleId}
-          className="settings-pills"
-          role="group"
-        >
-          <Pill
-            leadingIcon={terminalRenderer === "standard" ? <Check size={12} /> : undefined}
-            onClick={() => {
-              setTerminalRenderer("standard");
-              void saveSettings({ appearance: { terminalRenderer: "standard" } });
-            }}
-            active={terminalRenderer === "standard"}
-          >
-            {t("settings.terminal_standard")}
-          </Pill>
-          <Pill
-            leadingIcon={terminalRenderer === "compatibility" ? <Check size={12} /> : undefined}
-            onClick={() => {
-              setTerminalRenderer("compatibility");
-              void saveSettings({ appearance: { terminalRenderer: "compatibility" } });
-            }}
-            active={terminalRenderer === "compatibility"}
-          >
-            {t("settings.terminal_compatibility")}
-          </Pill>
-        </div>
-
-        <div className="settings-toggle-row">
-          <div className="settings-toggle-info">
-            <span className="settings-toggle-label" id={copyOnSelectLabelId}>
-              {t("settings.copy_on_select")}
-            </span>
-            <span className="settings-toggle-desc" id={copyOnSelectDescId}>
-              {t("settings.copy_on_select_hint")}
-            </span>
-          </div>
-          <Switch
-            aria-describedby={copyOnSelectDescId}
-            aria-labelledby={copyOnSelectLabelId}
-            checked={terminalCopyOnSelect}
-            className="settings-toggle"
-            onCheckedChange={(nextValue) => {
-              setTerminalCopyOnSelect(nextValue);
-              void saveSettings({ appearance: { terminalCopyOnSelect: nextValue } });
-            }}
-          />
-        </div>
-      </div>
-
       <div className="settings-group">
         <h3 className="settings-group-title">{t("settings.supervisor.title")}</h3>
         <p className="settings-group-desc">{t("settings.supervisor.hint")}</p>
@@ -1984,22 +2058,14 @@ function GeneralSettings({
 }
 
 interface AppearanceSettingsProps {
-  desktopTerminalFontSize: number;
-  mobileTerminalFontSize: number;
   personalization: AppearancePersonalization;
-  setDesktopTerminalFontSize: (value: number) => void;
-  setMobileTerminalFontSize: (value: number) => void;
   savePersonalization: (value: AppearancePersonalization) => Promise<boolean>;
   theme: string;
   setTheme: (value: string) => void;
 }
 
 function AppearanceSettings({
-  desktopTerminalFontSize,
-  mobileTerminalFontSize,
   personalization,
-  setDesktopTerminalFontSize,
-  setMobileTerminalFontSize,
   savePersonalization,
   theme,
   setTheme,
@@ -2008,10 +2074,6 @@ function AppearanceSettings({
   const themeTitleId = useId();
   const themeDescId = useId();
   const themeSelectId = useId();
-  const desktopTerminalFontSizeLabelId = useId();
-  const desktopTerminalFontSizeDescId = useId();
-  const mobileTerminalFontSizeLabelId = useId();
-  const mobileTerminalFontSizeDescId = useId();
   const backgroundFileInputId = useId();
   const commonGlassLabelId = useId();
   const commonGlassDescId = useId();
@@ -2062,18 +2124,6 @@ function AppearanceSettings({
       };
     }),
   ];
-  const [desktopTerminalFontSizeDraft, setDesktopTerminalFontSizeDraft] = useState(
-    String(desktopTerminalFontSize)
-  );
-  const [desktopTerminalFontSizeError, setDesktopTerminalFontSizeError] = useState<string | null>(
-    null
-  );
-  const [mobileTerminalFontSizeDraft, setMobileTerminalFontSizeDraft] = useState(
-    String(mobileTerminalFontSize)
-  );
-  const [mobileTerminalFontSizeError, setMobileTerminalFontSizeError] = useState<string | null>(
-    null
-  );
   const [assetActionError, setAssetActionError] = useState<string | null>(null);
   const [backgroundDimnessDraft, setBackgroundDimnessDraft] = useState(
     String(personalization.common.backgroundDimness)
@@ -2104,33 +2154,10 @@ function AppearanceSettings({
   const [desktopSurfaceOpacityError, setDesktopSurfaceOpacityError] = useState<string | null>(null);
   const [mobileSurfaceOpacityError, setMobileSurfaceOpacityError] = useState<string | null>(null);
   const fileInputRef = useRef<HTMLInputElement | null>(null);
-  const lastTerminalFontSizeCommitAtRef = useRef<
-    Record<"desktopTerminalFontSize" | "mobileTerminalFontSize", number>
-  >({
-    desktopTerminalFontSize: 0,
-    mobileTerminalFontSize: 0,
-  });
-
   const saveSettings = async (settings: Record<string, unknown>) => {
     return await dispatch("settings.update", { settings });
   };
 
-  useEffect(() => {
-    setDesktopTerminalFontSizeDraft(String(desktopTerminalFontSize));
-  }, [desktopTerminalFontSize]);
-
-  useEffect(() => {
-    setMobileTerminalFontSizeDraft(String(mobileTerminalFontSize));
-  }, [mobileTerminalFontSize]);
-
-  useEffect(() => {
-    setDesktopTerminalFontSizeError(null);
-  }, [desktopTerminalFontSize]);
-
-  useEffect(() => {
-    setMobileTerminalFontSizeError(null);
-  }, [mobileTerminalFontSize]);
-
   useEffect(() => {
     setBackgroundDimnessDraft(String(personalization.common.backgroundDimness));
     setBackgroundBlurDraft(String(personalization.common.backgroundBlur));
@@ -2412,64 +2439,6 @@ function AppearanceSettings({
     </div>
   );
 
-  const commitTerminalFontSize = async (
-    draft: string,
-    currentValue: number,
-    settingKey: "desktopTerminalFontSize" | "mobileTerminalFontSize",
-    setValue: (value: number) => void,
-    setDraft: (value: string) => void,
-    setError: (value: string | null) => void
-  ) => {
-    const parsed = parseTerminalFontSizeInput(draft);
-    if (parsed === null) {
-      setDraft(String(currentValue));
-      setError(
-        t("settings.terminal_font_size_validation_error", {
-          min: MIN_TERMINAL_FONT_SIZE,
-          max: MAX_TERMINAL_FONT_SIZE,
-        })
-      );
-      return;
-    }
-
-    if (parsed === currentValue) {
-      setDraft(String(parsed));
-      setError(null);
-      return;
-    }
-
-    const now = Date.now();
-    if (
-      now - lastTerminalFontSizeCommitAtRef.current[settingKey] <
-      TERMINAL_FONT_SIZE_SAVE_THROTTLE_MS
-    ) {
-      return;
-    }
-    lastTerminalFontSizeCommitAtRef.current[settingKey] = now;
-
-    const result = await dispatch("settings.update", {
-      settings: {
-        appearance: {
-          [settingKey]: parsed,
-        },
-      },
-    });
-
-    if (result === null) {
-      return;
-    }
-
-    if (!result.ok) {
-      setDraft(String(currentValue));
-      setError(result.error?.message || t("settings.config_files.save_failed"));
-      return;
-    }
-
-    setValue(parsed);
-    setDraft(String(parsed));
-    setError(null);
-  };
-
   return (
     <div className="settings-section">
       <input
@@ -2984,135 +2953,6 @@ function AppearanceSettings({
           </span>
         ) : null}
       </div>
-
-      <div className="settings-group">
-        <h3 className="settings-group-title">{t("settings.terminal_appearance")}</h3>
-        <p className="settings-group-desc">{t("settings.terminal_font_size_hint")}</p>
-
-        <div className="settings-config-field settings-config-field--inline">
-          <label
-            className="settings-config-label"
-            htmlFor="desktop-terminal-font-size"
-            id={desktopTerminalFontSizeLabelId}
-          >
-            {t("settings.desktop_terminal_font_size")}
-          </label>
-          <div className="settings-config-control">
-            <Input
-              id="desktop-terminal-font-size"
-              aria-describedby={desktopTerminalFontSizeDescId}
-              aria-labelledby={desktopTerminalFontSizeLabelId}
-              className="settings-input-compact"
-              type="number"
-              min={MIN_TERMINAL_FONT_SIZE}
-              max={MAX_TERMINAL_FONT_SIZE}
-              step={1}
-              inputMode="numeric"
-              invalid={Boolean(desktopTerminalFontSizeError)}
-              value={desktopTerminalFontSizeDraft}
-              onChange={(event) => {
-                setDesktopTerminalFontSizeDraft(event.target.value);
-                if (desktopTerminalFontSizeError) {
-                  setDesktopTerminalFontSizeError(null);
-                }
-              }}
-              onBlur={() => {
-                void commitTerminalFontSize(
-                  desktopTerminalFontSizeDraft,
-                  desktopTerminalFontSize,
-                  "desktopTerminalFontSize",
-                  setDesktopTerminalFontSize,
-                  setDesktopTerminalFontSizeDraft,
-                  setDesktopTerminalFontSizeError
-                );
-              }}
-              onKeyDown={(event) => {
-                if (event.key === "Enter") {
-                  event.preventDefault();
-                  void commitTerminalFontSize(
-                    desktopTerminalFontSizeDraft,
-                    desktopTerminalFontSize,
-                    "desktopTerminalFontSize",
-                    setDesktopTerminalFontSize,
-                    setDesktopTerminalFontSizeDraft,
-                    setDesktopTerminalFontSizeError
-                  );
-                }
-              }}
-            />
-          </div>
-          <span className="settings-toggle-desc" id={desktopTerminalFontSizeDescId}>
-            {t("settings.desktop_terminal_font_size_hint")}
-          </span>
-          {desktopTerminalFontSizeError ? (
-            <span className="form-error" role="alert">
-              {desktopTerminalFontSizeError}
-            </span>
-          ) : null}
-        </div>
-
-        <div className="settings-config-field settings-config-field--inline">
-          <label
-            className="settings-config-label"
-            htmlFor="mobile-terminal-font-size"
-            id={mobileTerminalFontSizeLabelId}
-          >
-            {t("settings.mobile_terminal_font_size")}
-          </label>
-          <div className="settings-config-control">
-            <Input
-              id="mobile-terminal-font-size"
-              aria-describedby={mobileTerminalFontSizeDescId}
-              aria-labelledby={mobileTerminalFontSizeLabelId}
-              className="settings-input-compact"
-              type="number"
-              min={MIN_TERMINAL_FONT_SIZE}
-              max={MAX_TERMINAL_FONT_SIZE}
-              step={1}
-              inputMode="numeric"
-              invalid={Boolean(mobileTerminalFontSizeError)}
-              value={mobileTerminalFontSizeDraft}
-              onChange={(event) => {
-                setMobileTerminalFontSizeDraft(event.target.value);
-                if (mobileTerminalFontSizeError) {
-                  setMobileTerminalFontSizeError(null);
-                }
-              }}
-              onBlur={() => {
-                void commitTerminalFontSize(
-                  mobileTerminalFontSizeDraft,
-                  mobileTerminalFontSize,
-                  "mobileTerminalFontSize",
-                  setMobileTerminalFontSize,
-                  setMobileTerminalFontSizeDraft,
-                  setMobileTerminalFontSizeError
-                );
-              }}
-              onKeyDown={(event) => {
-                if (event.key === "Enter") {
-                  event.preventDefault();
-                  void commitTerminalFontSize(
-                    mobileTerminalFontSizeDraft,
-                    mobileTerminalFontSize,
-                    "mobileTerminalFontSize",
-                    setMobileTerminalFontSize,
-                    setMobileTerminalFontSizeDraft,
-                    setMobileTerminalFontSizeError
-                  );
-                }
-              }}
-            />
-          </div>
-          <span className="settings-toggle-desc" id={mobileTerminalFontSizeDescId}>
-            {t("settings.mobile_terminal_font_size_hint")}
-          </span>
-          {mobileTerminalFontSizeError ? (
-            <span className="form-error" role="alert">
-              {mobileTerminalFontSizeError}
-            </span>
-          ) : null}
-        </div>
-      </div>
     </div>
   );
 }
diff --git a/packages/web/src/features/settings/components/settings-sections.tsx b/packages/web/src/features/settings/components/settings-sections.tsx
index 30a77f979..a71e2f5a6 100644
--- a/packages/web/src/features/settings/components/settings-sections.tsx
+++ b/packages/web/src/features/settings/components/settings-sections.tsx
@@ -3,6 +3,7 @@ import type { IconSemantic } from "../../../theme";
 export type SettingsSection =
   | "general"
   | "providers"
+  | "terminal"
   | "appearance"
   | "shortcuts"
   | "monitoring"
@@ -19,6 +20,7 @@ export interface SettingsSectionMeta {
 const VISIBLE_SETTINGS_SECTIONS = [
   { id: "general", labelKey: "settings.general", iconSemantic: "nav.settings.general" },
   { id: "providers", labelKey: "settings.providers", iconSemantic: "nav.settings.providers" },
+  { id: "terminal", labelKey: "label.terminal", iconSemantic: "nav.settings.terminal" },
   { id: "appearance", labelKey: "settings.appearance", iconSemantic: "nav.settings.appearance" },
   { id: "shortcuts", labelKey: "settings.shortcuts.title", iconSemantic: "nav.settings.shortcuts" },
 ] as const satisfies readonly SettingsSectionMeta[];
diff --git a/packages/web/src/features/settings/components/terminal-profile-settings.tsx b/packages/web/src/features/settings/components/terminal-profile-settings.tsx
new file mode 100644
index 000000000..c02954098
--- /dev/null
+++ b/packages/web/src/features/settings/components/terminal-profile-settings.tsx
@@ -0,0 +1,369 @@
+import type { CustomTerminalProfile, TerminalProfile } from "@coder-studio/core";
+import { useState } from "react";
+import { Button, Input, Select } from "../../../components/ui";
+import { useTranslation } from "../../../lib/i18n";
+
+const SYSTEM_DEFAULT_PROFILE_VALUE = "__system__";
+
+export interface TerminalProfileSettingsChange {
+  customProfiles: CustomTerminalProfile[];
+  defaultProfileId?: string | null;
+}
+
+interface TerminalProfileSettingsProps {
+  readonly configuredDefaultProfileId?: string;
+  readonly customProfiles: CustomTerminalProfile[];
+  readonly profiles: TerminalProfile[];
+  readonly resolvedDefaultProfileId: string | null;
+  readonly onChange: (next: TerminalProfileSettingsChange) => Promise<boolean>;
+}
+
+interface DraftState {
+  label: string;
+  command: string;
+  args: string;
+}
+
+const EMPTY_DRAFT: DraftState = {
+  label: "",
+  command: "",
+  args: "",
+};
+
+function parseArgs(value: string): string[] {
+  return value
+    .split(/\r?\n/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function formatArgs(args: readonly string[] | undefined): string {
+  return args?.join("\n") ?? "";
+}
+
+function formatCommand(profile: CustomTerminalProfile): string {
+  return [profile.command, ...(profile.args ?? [])].filter(Boolean).join(" ");
+}
+
+function slugifyProfileLabel(label: string): string {
+  const slug = label
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+
+  return slug || "profile";
+}
+
+function createCustomProfileId(
+  label: string,
+  existingProfiles: readonly CustomTerminalProfile[]
+): CustomTerminalProfile["id"] {
+  const base = `custom:${slugifyProfileLabel(label)}` as CustomTerminalProfile["id"];
+  const existingIds = new Set(existingProfiles.map((profile) => profile.id));
+  if (!existingIds.has(base)) {
+    return base;
+  }
+
+  let suffix = 2;
+  while (existingIds.has(`custom:${slugifyProfileLabel(label)}-${suffix}`)) {
+    suffix += 1;
+  }
+
+  return `custom:${slugifyProfileLabel(label)}-${suffix}` as CustomTerminalProfile["id"];
+}
+
+function normalizeCustomProfiles(profiles: readonly CustomTerminalProfile[]) {
+  return profiles.map((profile) => ({
+    id: profile.id,
+    label: profile.label.trim(),
+    command: profile.command.trim(),
+    args: profile.args ?? [],
+    icon: profile.icon,
+  }));
+}
+
+export function TerminalProfileSettings({
+  configuredDefaultProfileId,
+  customProfiles,
+  profiles,
+  resolvedDefaultProfileId,
+  onChange,
+}: TerminalProfileSettingsProps) {
+  const t = useTranslation();
+  const [editingProfileId, setEditingProfileId] = useState<string | null>(null);
+  const [draft, setDraft] = useState<DraftState>(EMPTY_DRAFT);
+  const detectedProfiles = profiles.filter((profile) => profile.source === "detected");
+  const customProfileIds = new Set(customProfiles.map((profile) => profile.id));
+  const listedCustomProfileIds = new Set(
+    profiles.filter((profile) => profile.source === "custom").map((profile) => profile.id)
+  );
+  const customProfilesForDefault = [
+    ...customProfiles,
+    ...profiles
+      .filter((profile) => profile.source === "custom" && !customProfileIds.has(profile.id))
+      .map(
+        (profile): CustomTerminalProfile => ({
+          id: profile.id as CustomTerminalProfile["id"],
+          label: profile.label,
+          command: "",
+          args: [],
+        })
+      ),
+  ];
+  const normalizedCustomProfiles = normalizeCustomProfiles(customProfiles);
+  const defaultProfileOptions = [
+    {
+      value: SYSTEM_DEFAULT_PROFILE_VALUE,
+      label: t("settings.terminal_profiles.system_default"),
+    },
+    ...detectedProfiles.map((profile) => ({
+      value: profile.id,
+      label: profile.label,
+    })),
+    ...customProfilesForDefault.map((profile) => ({
+      value: profile.id,
+      label: profile.label,
+    })),
+  ];
+  const defaultProfileValue = configuredDefaultProfileId ?? SYSTEM_DEFAULT_PROFILE_VALUE;
+  const isDraftValid = draft.label.trim().length > 0 && draft.command.trim().length > 0;
+  const effectiveDefaultProfileLabel =
+    [
+      ...profiles,
+      ...customProfiles.map(
+        (profile): TerminalProfile => ({
+          id: profile.id,
+          label: profile.label,
+          source: "custom",
+          runtime: "native",
+          icon: profile.icon ?? "terminal",
+        })
+      ),
+    ].find((profile) => profile.id === resolvedDefaultProfileId)?.label ??
+    t("settings.terminal_profiles.none_detected");
+
+  const resetDraft = () => {
+    setEditingProfileId(null);
+    setDraft(EMPTY_DRAFT);
+  };
+
+  const handleDefaultChange = async (value: string) => {
+    const nextDefaultProfileId = value === SYSTEM_DEFAULT_PROFILE_VALUE ? null : value;
+    await onChange({
+      customProfiles: normalizedCustomProfiles,
+      defaultProfileId: nextDefaultProfileId,
+    });
+  };
+
+  const handleSaveDraft = async () => {
+    if (!isDraftValid) {
+      return;
+    }
+
+    const existingProfile = editingProfileId
+      ? customProfiles.find((profile) => profile.id === editingProfileId)
+      : undefined;
+    const nextProfile: CustomTerminalProfile = {
+      id:
+        existingProfile?.id ??
+        createCustomProfileId(
+          draft.label,
+          customProfiles.filter(() => !editingProfileId)
+        ),
+      label: draft.label.trim(),
+      command: draft.command.trim(),
+      args: parseArgs(draft.args),
+      icon: existingProfile?.icon,
+    };
+    const nextCustomProfiles = existingProfile
+      ? customProfiles.map((profile) => (profile.id === existingProfile.id ? nextProfile : profile))
+      : [...customProfiles, nextProfile];
+    const nextDefaultProfileId = existingProfile ? configuredDefaultProfileId : nextProfile.id;
+    const saved = await onChange({
+      customProfiles: normalizeCustomProfiles(nextCustomProfiles),
+      defaultProfileId: nextDefaultProfileId,
+    });
+
+    if (saved) {
+      resetDraft();
+    }
+  };
+
+  const handleEdit = (profile: CustomTerminalProfile) => {
+    setEditingProfileId(profile.id);
+    setDraft({
+      label: profile.label,
+      command: profile.command,
+      args: formatArgs(profile.args),
+    });
+  };
+
+  const handleDelete = async (profile: CustomTerminalProfile) => {
+    const nextCustomProfiles = customProfiles.filter((item) => item.id !== profile.id);
+    const saved = await onChange({
+      customProfiles: normalizeCustomProfiles(nextCustomProfiles),
+      defaultProfileId:
+        configuredDefaultProfileId === profile.id ? null : configuredDefaultProfileId,
+    });
+
+    if (saved && editingProfileId === profile.id) {
+      resetDraft();
+    }
+  };
+
+  return (
+    <div
+      className="settings-group"
+      id="terminal-profiles"
+      style={{ scrollMarginTop: "var(--space-lg)" }}
+    >
+      <h3 className="settings-group-title">{t("settings.terminal_profiles.title")}</h3>
+      <p className="settings-group-desc">{t("settings.terminal_profiles.hint")}</p>
+
+      <div className="settings-config-field settings-config-field--inline">
+        <label className="settings-config-label" htmlFor="terminal-default-profile">
+          {t("settings.terminal_profiles.default_label")}
+        </label>
+        <div className="settings-config-control">
+          <div style={{ width: "220px", maxWidth: "100%" }}>
+            <Select
+              desktopMode="listbox"
+              id="terminal-default-profile"
+              aria-label={t("settings.terminal_profiles.default_label")}
+              mobileSheetTitle={t("settings.terminal_profiles.default_label")}
+              options={defaultProfileOptions}
+              value={defaultProfileValue}
+              onValueChange={(value) => {
+                void handleDefaultChange(value);
+              }}
+            />
+          </div>
+        </div>
+      </div>
+
+      <div className="settings-info-row">
+        <span className="settings-info-label">
+          {t("settings.terminal_profiles.current_default")}
+        </span>
+        <span className="settings-info-value">{effectiveDefaultProfileLabel}</span>
+      </div>
+
+      <div className="settings-info-row">
+        <span className="settings-info-label">
+          {t("settings.terminal_profiles.detected_profiles")}
+        </span>
+        <span className="settings-info-value">
+          {detectedProfiles.length > 0
+            ? detectedProfiles.map((profile) => profile.label).join(", ")
+            : t("settings.terminal_profiles.none_detected")}
+          {detectedProfiles.length > 0 ? (
+            <span className="settings-status-hint">
+              {t("settings.terminal_profiles.detected_badge")}
+            </span>
+          ) : null}
+        </span>
+      </div>
+
+      {customProfiles.length > 0 ? (
+        customProfiles.map((profile) => (
+          <div className="settings-toggle-row settings-toggle-row--action" key={profile.id}>
+            <div className="settings-toggle-info">
+              <span className="settings-toggle-label">{profile.label}</span>
+              <span className="settings-toggle-desc">{formatCommand(profile)}</span>
+              {!listedCustomProfileIds.has(profile.id) ? (
+                <span className="settings-toggle-desc">
+                  {t("settings.terminal_profiles.pending_refresh")}
+                </span>
+              ) : null}
+            </div>
+            <div className="settings-pills">
+              <Button
+                size="sm"
+                variant="secondary"
+                aria-label={t("settings.terminal_profiles.edit_profile", {
+                  label: profile.label,
+                })}
+                onClick={() => handleEdit(profile)}
+              >
+                {t("common.edit")}
+              </Button>
+              <Button
+                size="sm"
+                variant="ghost"
+                aria-label={t("settings.terminal_profiles.delete_profile", {
+                  label: profile.label,
+                })}
+                onClick={() => {
+                  void handleDelete(profile);
+                }}
+              >
+                {t("common.delete")}
+              </Button>
+            </div>
+          </div>
+        ))
+      ) : (
+        <div className="settings-info-row">
+          <span className="settings-info-label">
+            {t("settings.terminal_profiles.custom_profiles")}
+          </span>
+          <span className="settings-info-value">
+            {t("settings.terminal_profiles.no_custom_profiles")}
+          </span>
+        </div>
+      )}
+
+      <div className="settings-config-field">
+        <label className="settings-config-label" htmlFor="terminal-profile-label">
+          {t("settings.terminal_profiles.profile_label")}
+        </label>
+        <Input
+          id="terminal-profile-label"
+          value={draft.label}
+          onChange={(event) => setDraft((current) => ({ ...current, label: event.target.value }))}
+        />
+      </div>
+      <div className="settings-config-field">
+        <label className="settings-config-label" htmlFor="terminal-profile-command">
+          {t("settings.terminal_profiles.command")}
+        </label>
+        <Input
+          id="terminal-profile-command"
+          value={draft.command}
+          onChange={(event) => setDraft((current) => ({ ...current, command: event.target.value }))}
+        />
+      </div>
+      <div className="settings-config-field">
+        <label className="settings-config-label" htmlFor="terminal-profile-args">
+          {t("settings.terminal_profiles.args")}
+        </label>
+        <textarea
+          id="terminal-profile-args"
+          className="input"
+          rows={3}
+          value={draft.args}
+          onChange={(event) => setDraft((current) => ({ ...current, args: event.target.value }))}
+        />
+        <span className="settings-toggle-desc">{t("settings.terminal_profiles.args_hint")}</span>
+      </div>
+      <div className="settings-pills">
+        <Button
+          size="sm"
+          variant="primary"
+          disabled={!isDraftValid}
+          onClick={() => {
+            void handleSaveDraft();
+          }}
+        >
+          {t("settings.terminal_profiles.save_custom")}
+        </Button>
+        {editingProfileId ? (
+          <Button size="sm" variant="ghost" onClick={resetDraft}>
+            {t("common.cancel")}
+          </Button>
+        ) : null}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/web/src/features/settings/components/terminal-settings-section.tsx b/packages/web/src/features/settings/components/terminal-settings-section.tsx
new file mode 100644
index 000000000..68e650049
--- /dev/null
+++ b/packages/web/src/features/settings/components/terminal-settings-section.tsx
@@ -0,0 +1,383 @@
+import type { CustomTerminalProfile, TerminalProfile } from "@coder-studio/core";
+import { Check } from "lucide-react";
+import { useEffect, useId, useRef, useState } from "react";
+import { Input, Pill, Switch } from "../../../components/ui";
+import { useTranslation } from "../../../lib/i18n";
+import { MAX_TERMINAL_FONT_SIZE, MIN_TERMINAL_FONT_SIZE } from "../../terminal-panel/preferences";
+import {
+  TerminalProfileSettings,
+  type TerminalProfileSettingsChange,
+} from "./terminal-profile-settings";
+import { useSessionGateDispatch } from "./use-session-gate-dispatch";
+
+const TERMINAL_FONT_SIZE_SAVE_THROTTLE_MS = 500;
+
+interface TerminalSettingsSectionProps {
+  terminalRenderer: "standard" | "compatibility";
+  setTerminalRenderer: (value: "standard" | "compatibility") => void;
+  terminalCopyOnSelect: boolean;
+  setTerminalCopyOnSelect: (value: boolean) => void;
+  terminalProfiles: TerminalProfile[];
+  customTerminalProfiles: CustomTerminalProfile[];
+  configuredTerminalDefaultProfileId?: string;
+  resolvedTerminalDefaultProfileId: string | null;
+  onTerminalProfileSettingsChange: (change: TerminalProfileSettingsChange) => Promise<boolean>;
+  desktopTerminalFontSize: number;
+  mobileTerminalFontSize: number;
+  setDesktopTerminalFontSize: (value: number) => void;
+  setMobileTerminalFontSize: (value: number) => void;
+}
+
+function parseTerminalFontSizeInput(value: string): number | null {
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return null;
+  }
+
+  const parsed = Number(trimmed);
+  if (
+    !Number.isSafeInteger(parsed) ||
+    parsed < MIN_TERMINAL_FONT_SIZE ||
+    parsed > MAX_TERMINAL_FONT_SIZE
+  ) {
+    return null;
+  }
+
+  return parsed;
+}
+
+export function TerminalSettingsSection({
+  terminalRenderer,
+  setTerminalRenderer,
+  terminalCopyOnSelect,
+  setTerminalCopyOnSelect,
+  terminalProfiles,
+  customTerminalProfiles,
+  configuredTerminalDefaultProfileId,
+  resolvedTerminalDefaultProfileId,
+  onTerminalProfileSettingsChange,
+  desktopTerminalFontSize,
+  mobileTerminalFontSize,
+  setDesktopTerminalFontSize,
+  setMobileTerminalFontSize,
+}: TerminalSettingsSectionProps) {
+  const t = useTranslation();
+  const dispatch = useSessionGateDispatch();
+  const terminalRendererTitleId = useId();
+  const terminalRendererDescId = useId();
+  const copyOnSelectLabelId = useId();
+  const copyOnSelectDescId = useId();
+  const desktopTerminalFontSizeLabelId = useId();
+  const desktopTerminalFontSizeDescId = useId();
+  const mobileTerminalFontSizeLabelId = useId();
+  const mobileTerminalFontSizeDescId = useId();
+  const [desktopTerminalFontSizeDraft, setDesktopTerminalFontSizeDraft] = useState(
+    String(desktopTerminalFontSize)
+  );
+  const [desktopTerminalFontSizeError, setDesktopTerminalFontSizeError] = useState<string | null>(
+    null
+  );
+  const [mobileTerminalFontSizeDraft, setMobileTerminalFontSizeDraft] = useState(
+    String(mobileTerminalFontSize)
+  );
+  const [mobileTerminalFontSizeError, setMobileTerminalFontSizeError] = useState<string | null>(
+    null
+  );
+  const lastTerminalFontSizeCommitAtRef = useRef<
+    Record<"desktopTerminalFontSize" | "mobileTerminalFontSize", number>
+  >({
+    desktopTerminalFontSize: 0,
+    mobileTerminalFontSize: 0,
+  });
+
+  useEffect(() => {
+    setDesktopTerminalFontSizeDraft(String(desktopTerminalFontSize));
+  }, [desktopTerminalFontSize]);
+
+  useEffect(() => {
+    setMobileTerminalFontSizeDraft(String(mobileTerminalFontSize));
+  }, [mobileTerminalFontSize]);
+
+  useEffect(() => {
+    setDesktopTerminalFontSizeError(null);
+  }, [desktopTerminalFontSize]);
+
+  useEffect(() => {
+    setMobileTerminalFontSizeError(null);
+  }, [mobileTerminalFontSize]);
+
+  const commitTerminalFontSize = async (
+    draft: string,
+    currentValue: number,
+    settingKey: "desktopTerminalFontSize" | "mobileTerminalFontSize",
+    setValue: (value: number) => void,
+    setDraft: (value: string) => void,
+    setError: (value: string | null) => void
+  ) => {
+    const parsed = parseTerminalFontSizeInput(draft);
+    if (parsed === null) {
+      setDraft(String(currentValue));
+      setError(
+        t("settings.terminal_font_size_validation_error", {
+          min: MIN_TERMINAL_FONT_SIZE,
+          max: MAX_TERMINAL_FONT_SIZE,
+        })
+      );
+      return;
+    }
+
+    if (parsed === currentValue) {
+      setDraft(String(parsed));
+      setError(null);
+      return;
+    }
+
+    const now = Date.now();
+    if (
+      now - lastTerminalFontSizeCommitAtRef.current[settingKey] <
+      TERMINAL_FONT_SIZE_SAVE_THROTTLE_MS
+    ) {
+      return;
+    }
+    lastTerminalFontSizeCommitAtRef.current[settingKey] = now;
+
+    const result = await dispatch("settings.update", {
+      settings: {
+        appearance: {
+          [settingKey]: parsed,
+        },
+      },
+    });
+
+    if (result === null) {
+      return;
+    }
+
+    if (!result.ok) {
+      setDraft(String(currentValue));
+      setError(result.error?.message || t("settings.config_files.save_failed"));
+      return;
+    }
+
+    setValue(parsed);
+    setDraft(String(parsed));
+    setError(null);
+  };
+
+  return (
+    <div className="settings-section">
+      <div className="settings-group">
+        <h3 className="settings-group-title" id={terminalRendererTitleId}>
+          {t("settings.terminal_renderer")}
+        </h3>
+        <p className="settings-group-desc" id={terminalRendererDescId}>
+          {t("settings.terminal_renderer_hint")}
+        </p>
+
+        <div
+          aria-describedby={terminalRendererDescId}
+          aria-labelledby={terminalRendererTitleId}
+          className="settings-pills"
+          role="group"
+        >
+          <Pill
+            leadingIcon={terminalRenderer === "standard" ? <Check size={12} /> : undefined}
+            onClick={() => {
+              setTerminalRenderer("standard");
+              void dispatch("settings.update", {
+                settings: {
+                  appearance: {
+                    terminalRenderer: "standard",
+                  },
+                },
+              });
+            }}
+            active={terminalRenderer === "standard"}
+          >
+            {t("settings.terminal_standard")}
+          </Pill>
+          <Pill
+            leadingIcon={terminalRenderer === "compatibility" ? <Check size={12} /> : undefined}
+            onClick={() => {
+              setTerminalRenderer("compatibility");
+              void dispatch("settings.update", {
+                settings: {
+                  appearance: {
+                    terminalRenderer: "compatibility",
+                  },
+                },
+              });
+            }}
+            active={terminalRenderer === "compatibility"}
+          >
+            {t("settings.terminal_compatibility")}
+          </Pill>
+        </div>
+
+        <div className="settings-toggle-row">
+          <div className="settings-toggle-info">
+            <span className="settings-toggle-label" id={copyOnSelectLabelId}>
+              {t("settings.copy_on_select")}
+            </span>
+            <span className="settings-toggle-desc" id={copyOnSelectDescId}>
+              {t("settings.copy_on_select_hint")}
+            </span>
+          </div>
+          <Switch
+            aria-describedby={copyOnSelectDescId}
+            aria-labelledby={copyOnSelectLabelId}
+            checked={terminalCopyOnSelect}
+            className="settings-toggle"
+            onCheckedChange={(nextValue) => {
+              setTerminalCopyOnSelect(nextValue);
+              void dispatch("settings.update", {
+                settings: {
+                  appearance: {
+                    terminalCopyOnSelect: nextValue,
+                  },
+                },
+              });
+            }}
+          />
+        </div>
+      </div>
+
+      <TerminalProfileSettings
+        configuredDefaultProfileId={configuredTerminalDefaultProfileId}
+        customProfiles={customTerminalProfiles}
+        profiles={terminalProfiles}
+        resolvedDefaultProfileId={resolvedTerminalDefaultProfileId}
+        onChange={onTerminalProfileSettingsChange}
+      />
+
+      <div className="settings-group">
+        <h3 className="settings-group-title">{t("settings.terminal_appearance")}</h3>
+        <p className="settings-group-desc">{t("settings.terminal_font_size_hint")}</p>
+
+        <div className="settings-config-field settings-config-field--inline">
+          <label
+            className="settings-config-label"
+            htmlFor="desktop-terminal-font-size"
+            id={desktopTerminalFontSizeLabelId}
+          >
+            {t("settings.desktop_terminal_font_size")}
+          </label>
+          <div className="settings-config-control">
+            <Input
+              id="desktop-terminal-font-size"
+              aria-describedby={desktopTerminalFontSizeDescId}
+              aria-labelledby={desktopTerminalFontSizeLabelId}
+              className="settings-input-compact"
+              type="number"
+              min={MIN_TERMINAL_FONT_SIZE}
+              max={MAX_TERMINAL_FONT_SIZE}
+              step={1}
+              inputMode="numeric"
+              invalid={Boolean(desktopTerminalFontSizeError)}
+              value={desktopTerminalFontSizeDraft}
+              onChange={(event) => {
+                setDesktopTerminalFontSizeDraft(event.target.value);
+                if (desktopTerminalFontSizeError) {
+                  setDesktopTerminalFontSizeError(null);
+                }
+              }}
+              onBlur={() => {
+                void commitTerminalFontSize(
+                  desktopTerminalFontSizeDraft,
+                  desktopTerminalFontSize,
+                  "desktopTerminalFontSize",
+                  setDesktopTerminalFontSize,
+                  setDesktopTerminalFontSizeDraft,
+                  setDesktopTerminalFontSizeError
+                );
+              }}
+              onKeyDown={(event) => {
+                if (event.key === "Enter") {
+                  event.preventDefault();
+                  void commitTerminalFontSize(
+                    desktopTerminalFontSizeDraft,
+                    desktopTerminalFontSize,
+                    "desktopTerminalFontSize",
+                    setDesktopTerminalFontSize,
+                    setDesktopTerminalFontSizeDraft,
+                    setDesktopTerminalFontSizeError
+                  );
+                }
+              }}
+            />
+          </div>
+          <span className="settings-toggle-desc" id={desktopTerminalFontSizeDescId}>
+            {t("settings.desktop_terminal_font_size_hint")}
+          </span>
+          {desktopTerminalFontSizeError ? (
+            <span className="form-error" role="alert">
+              {desktopTerminalFontSizeError}
+            </span>
+          ) : null}
+        </div>
+
+        <div className="settings-config-field settings-config-field--inline">
+          <label
+            className="settings-config-label"
+            htmlFor="mobile-terminal-font-size"
+            id={mobileTerminalFontSizeLabelId}
+          >
+            {t("settings.mobile_terminal_font_size")}
+          </label>
+          <div className="settings-config-control">
+            <Input
+              id="mobile-terminal-font-size"
+              aria-describedby={mobileTerminalFontSizeDescId}
+              aria-labelledby={mobileTerminalFontSizeLabelId}
+              className="settings-input-compact"
+              type="number"
+              min={MIN_TERMINAL_FONT_SIZE}
+              max={MAX_TERMINAL_FONT_SIZE}
+              step={1}
+              inputMode="numeric"
+              invalid={Boolean(mobileTerminalFontSizeError)}
+              value={mobileTerminalFontSizeDraft}
+              onChange={(event) => {
+                setMobileTerminalFontSizeDraft(event.target.value);
+                if (mobileTerminalFontSizeError) {
+                  setMobileTerminalFontSizeError(null);
+                }
+              }}
+              onBlur={() => {
+                void commitTerminalFontSize(
+                  mobileTerminalFontSizeDraft,
+                  mobileTerminalFontSize,
+                  "mobileTerminalFontSize",
+                  setMobileTerminalFontSize,
+                  setMobileTerminalFontSizeDraft,
+                  setMobileTerminalFontSizeError
+                );
+              }}
+              onKeyDown={(event) => {
+                if (event.key === "Enter") {
+                  event.preventDefault();
+                  void commitTerminalFontSize(
+                    mobileTerminalFontSizeDraft,
+                    mobileTerminalFontSize,
+                    "mobileTerminalFontSize",
+                    setMobileTerminalFontSize,
+                    setMobileTerminalFontSizeDraft,
+                    setMobileTerminalFontSizeError
+                  );
+                }
+              }}
+            />
+          </div>
+          <span className="settings-toggle-desc" id={mobileTerminalFontSizeDescId}>
+            {t("settings.mobile_terminal_font_size_hint")}
+          </span>
+          {mobileTerminalFontSizeError ? (
+            <span className="form-error" role="alert">
+              {mobileTerminalFontSizeError}
+            </span>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/packages/web/src/features/shared/components/mobile-page-header.test.tsx b/packages/web/src/features/shared/components/mobile-page-header.test.tsx
index 3ac73ceaf..35f051ced 100644
--- a/packages/web/src/features/shared/components/mobile-page-header.test.tsx
+++ b/packages/web/src/features/shared/components/mobile-page-header.test.tsx
@@ -20,6 +20,9 @@ describe("MobilePageHeader", () => {
     expect(header).toHaveClass("page-header--secondary");
     expect(header).toHaveAttribute("data-level", "secondary");
     expect(leading).not.toBeNull();
+    const backButton = within(leading as HTMLElement).getByRole("button", { name: "Back" });
+    expect(backButton).toBeInTheDocument();
+    expect(within(backButton).queryByText("Back")).toBeNull();
     expect(within(leading as HTMLElement).getByText("Open Workspace")).toBeInTheDocument();
     expect(screen.queryByText("WORKSPACE")).not.toBeInTheDocument();
   });
diff --git a/packages/web/src/features/shared/components/page-header.test.tsx b/packages/web/src/features/shared/components/page-header.test.tsx
index d3744c876..6266c171b 100644
--- a/packages/web/src/features/shared/components/page-header.test.tsx
+++ b/packages/web/src/features/shared/components/page-header.test.tsx
@@ -21,9 +21,9 @@ describe("PageHeader", () => {
     expect(header).toHaveAttribute("data-level", "secondary");
     expect(leading).not.toBeNull();
     expect(actions).not.toBeNull();
-    expect(
-      within(leading as HTMLElement).getByRole("button", { name: "Back" })
-    ).toBeInTheDocument();
+    const backButton = within(leading as HTMLElement).getByRole("button", { name: "Back" });
+    expect(backButton).toBeInTheDocument();
+    expect(within(backButton).queryByText("Back")).toBeNull();
     expect(within(leading as HTMLElement).getByText("Agent Sessions")).toBeInTheDocument();
     expect(
       within(actions as HTMLElement).getByRole("button", { name: "Edit" })
@@ -38,6 +38,7 @@ describe("PageHeader", () => {
     expect(copy).not.toBeNull();
     expect(within(copy as HTMLElement).getByText("Workspace")).toBeInTheDocument();
     expect(within(copy as HTMLElement).getByText("Config")).toBeInTheDocument();
+    expect(screen.queryByText("Back")).toBeNull();
     expect(screen.queryByRole("button", { name: "Edit" })).not.toBeInTheDocument();
   });
 
diff --git a/packages/web/src/features/shared/components/page-header.tsx b/packages/web/src/features/shared/components/page-header.tsx
index 8ece9136f..b1bc2dd57 100644
--- a/packages/web/src/features/shared/components/page-header.tsx
+++ b/packages/web/src/features/shared/components/page-header.tsx
@@ -40,8 +40,7 @@ export function PageHeader({
             onClick={onBack}
             aria-label={backAriaLabel ?? backLabel}
           >
-            <ArrowLeft size={16} />
-            <span>{backLabel}</span>
+            <ArrowLeft size={16} aria-hidden="true" />
           </button>
         ) : null}
         <div className="page-header__copy">
diff --git a/packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx b/packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx
index 89f3c12f3..7b1552055 100644
--- a/packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx
+++ b/packages/web/src/features/terminal-panel/__tests__/terminal-panel.test.tsx
@@ -180,6 +180,29 @@ describe("TerminalPanel", () => {
         return Promise.resolve([]);
       }
 
+      if (op === "terminal.profiles.list") {
+        return Promise.resolve({
+          profiles: [
+            {
+              id: "detected:zsh",
+              label: "zsh",
+              source: "detected",
+              runtime: "native",
+              icon: "terminal",
+            },
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              source: "custom",
+              runtime: "native",
+              icon: "rocket",
+            },
+          ],
+          configuredDefaultProfileId: "custom:ops",
+          resolvedDefaultProfileId: "custom:ops",
+        });
+      }
+
       if (op === "terminal.create") {
         return Promise.resolve({
           id: "term_2",
@@ -228,6 +251,17 @@ describe("TerminalPanel", () => {
       screen.getAllByRole("button", { name: "New Terminal" })[0]?.click();
     });
 
+    expect(sendCommand).toHaveBeenCalledWith("terminal.profiles.list", {}, undefined);
+    expect(sendCommand).toHaveBeenCalledWith(
+      "terminal.create",
+      expect.objectContaining({
+        workspaceId: "ws-test",
+        profileId: "custom:ops",
+        themeBackground: expect.any(String),
+      }),
+      undefined
+    );
+
     await waitFor(() => {
       expect(screen.getByTestId("xterm-host")).toHaveTextContent("term_2");
     });
@@ -243,6 +277,369 @@ describe("TerminalPanel", () => {
     expect(consoleSpy).not.toHaveBeenCalled();
   });
 
+  it("launches the resolved default profile from the desktop toolbar primary create action", async () => {
+    const user = userEvent.setup();
+    const store = createStore();
+    const subscribe = vi.fn((_topics: string[], handler: EventHandler) => {
+      handlers.push(handler);
+      return () => {
+        handlers = handlers.filter((candidate) => candidate !== handler);
+      };
+    });
+    const sendCommand = vi.fn().mockImplementation((op: string) => {
+      if (op === "terminal.list") {
+        return Promise.resolve([
+          {
+            id: "term_1",
+            workspaceId: "ws-test",
+            kind: "shell",
+            title: "Workspace Shell",
+            cwd: "/tmp/ws-test",
+            argv: ["/bin/bash"],
+            cols: 120,
+            rows: 30,
+            alive: true,
+            createdAt: 1,
+          },
+        ]);
+      }
+
+      if (op === "terminal.profiles.list") {
+        return Promise.resolve({
+          profiles: [
+            {
+              id: "detected:win:powershell",
+              label: "PowerShell",
+              source: "detected",
+              runtime: "native",
+              icon: "terminal",
+            },
+            {
+              id: "detected:win:git-bash",
+              label: "Git Bash",
+              source: "detected",
+              runtime: "native",
+              icon: "terminal",
+            },
+          ],
+          configuredDefaultProfileId: "detected:win:git-bash",
+          resolvedDefaultProfileId: "detected:win:git-bash",
+        });
+      }
+
+      if (op === "terminal.create") {
+        return Promise.resolve({
+          id: "term_git_bash",
+          workspaceId: "ws-test",
+          kind: "shell",
+          title: "Git Bash",
+          cwd: "/tmp/ws-test",
+          argv: ["C:/Program Files/Git/bin/bash.exe"],
+          cols: 120,
+          rows: 30,
+          alive: true,
+          createdAt: 2,
+        });
+      }
+
+      return Promise.resolve(undefined);
+    });
+
+    seedReadyWorkspaceState(store, {
+      "ws-test": {
+        id: "ws-test",
+        path: "/tmp/ws-test",
+        targetRuntime: "native",
+        openedAt: 1,
+        lastActiveAt: 1,
+        uiState: {
+          leftPanelWidth: 280,
+          bottomPanelHeight: 200,
+          focusMode: false,
+        },
+      },
+    });
+    store.set(bottomPanelHeightAtom, 240);
+    setEnglishLocale(store);
+    store.set(wsClientAtom, { subscribe, sendCommand } as never);
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter>
+          <TerminalPanel />
+        </MemoryRouter>
+      </Provider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("xterm-host")).toHaveTextContent("term_1");
+    });
+
+    const toolbarRight = document.querySelector(".terminal-toolbar-right");
+    expect(toolbarRight).not.toBeNull();
+
+    await user.click(
+      within(toolbarRight as HTMLElement).getByRole("button", { name: "New Terminal" })
+    );
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "terminal.create",
+        expect.objectContaining({
+          workspaceId: "ws-test",
+          profileId: "detected:win:git-bash",
+          themeBackground: expect.any(String),
+        }),
+        undefined
+      );
+    });
+  });
+
+  it("exposes alternate profiles from the desktop profile chooser", async () => {
+    const user = userEvent.setup();
+    const store = createStore();
+    const subscribe = vi.fn((_topics: string[], handler: EventHandler) => {
+      handlers.push(handler);
+      return () => {
+        handlers = handlers.filter((candidate) => candidate !== handler);
+      };
+    });
+    const sendCommand = vi.fn().mockImplementation((op: string) => {
+      if (op === "terminal.list") {
+        return Promise.resolve([
+          {
+            id: "term_1",
+            workspaceId: "ws-test",
+            kind: "shell",
+            title: "Workspace Shell",
+            cwd: "/tmp/ws-test",
+            argv: ["/bin/bash"],
+            cols: 120,
+            rows: 30,
+            alive: true,
+            createdAt: 1,
+          },
+        ]);
+      }
+
+      if (op === "terminal.profiles.list") {
+        return Promise.resolve({
+          profiles: [
+            {
+              id: "detected:win:powershell",
+              label: "PowerShell",
+              source: "detected",
+              runtime: "native",
+              icon: "terminal",
+            },
+            {
+              id: "detected:win:git-bash",
+              label: "Git Bash",
+              source: "detected",
+              runtime: "native",
+              icon: "terminal",
+            },
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              source: "custom",
+              runtime: "native",
+              icon: "rocket",
+            },
+          ],
+          configuredDefaultProfileId: "detected:win:powershell",
+          resolvedDefaultProfileId: "detected:win:powershell",
+        });
+      }
+
+      if (op === "terminal.create") {
+        return Promise.resolve({
+          id: "term_git_bash",
+          workspaceId: "ws-test",
+          kind: "shell",
+          title: "Git Bash",
+          cwd: "/tmp/ws-test",
+          argv: ["C:/Program Files/Git/bin/bash.exe"],
+          cols: 120,
+          rows: 30,
+          alive: true,
+          createdAt: 2,
+        });
+      }
+
+      return Promise.resolve(undefined);
+    });
+
+    seedReadyWorkspaceState(store, {
+      "ws-test": {
+        id: "ws-test",
+        path: "/tmp/ws-test",
+        targetRuntime: "native",
+        openedAt: 1,
+        lastActiveAt: 1,
+        uiState: {
+          leftPanelWidth: 280,
+          bottomPanelHeight: 200,
+          focusMode: false,
+        },
+      },
+    });
+    store.set(bottomPanelHeightAtom, 240);
+    setEnglishLocale(store);
+    store.set(wsClientAtom, { subscribe, sendCommand } as never);
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter>
+          <TerminalPanel />
+        </MemoryRouter>
+      </Provider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("xterm-host")).toHaveTextContent("term_1");
+    });
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith("terminal.profiles.list", {}, undefined);
+    });
+
+    const toolbarRight = document.querySelector(".terminal-toolbar-right");
+    expect(toolbarRight).not.toBeNull();
+    const createButtonGroup = (toolbarRight as HTMLElement).querySelector(
+      ".terminal-profile-create-button"
+    );
+    expect(createButtonGroup).not.toBeNull();
+    expect(createButtonGroup).toHaveStyle({ gap: "2px" });
+
+    await user.click(
+      within(toolbarRight as HTMLElement).getByRole("button", {
+        name: "Choose Terminal Profile",
+      })
+    );
+
+    const chooser = screen.getByRole("dialog", { name: "New Terminal" });
+    expect(within(chooser).getByText("Detected")).toBeInTheDocument();
+    expect(within(chooser).getByText("Custom")).toBeInTheDocument();
+    expect(within(chooser).getByRole("button", { name: /Git Bash/ })).toBeInTheDocument();
+    expect(within(chooser).getByRole("button", { name: /Ops Shell/ })).toBeInTheDocument();
+    expect(
+      within(chooser).getByRole("link", { name: "Configure Terminal Profiles..." })
+    ).toHaveAttribute("href", "/more/settings/terminal#terminal-profiles");
+    expect(within(chooser).queryByRole("link", { name: "Settings" })).not.toBeInTheDocument();
+
+    await user.click(within(chooser).getByRole("button", { name: /Git Bash/ }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "terminal.create",
+        expect.objectContaining({
+          workspaceId: "ws-test",
+          profileId: "detected:win:git-bash",
+          themeBackground: expect.any(String),
+        }),
+        undefined
+      );
+    });
+  });
+
+  it("opens a mobile profile chooser with an explicit default action before other profiles", async () => {
+    const user = userEvent.setup();
+    const store = createStore();
+    const subscribe = vi.fn((_topics: string[], handler: EventHandler) => {
+      handlers.push(handler);
+      return () => {
+        handlers = handlers.filter((candidate) => candidate !== handler);
+      };
+    });
+    const sendCommand = vi.fn().mockImplementation((op: string) => {
+      if (op === "terminal.list") {
+        return Promise.resolve([]);
+      }
+
+      if (op === "terminal.profiles.list") {
+        return Promise.resolve({
+          profiles: [
+            {
+              id: "detected:zsh",
+              label: "zsh",
+              source: "detected",
+              runtime: "native",
+              icon: "terminal",
+            },
+            {
+              id: "custom:ops",
+              label: "Ops Shell",
+              source: "custom",
+              runtime: "native",
+              icon: "rocket",
+            },
+            {
+              id: "custom:python",
+              label: "Python Env",
+              source: "custom",
+              runtime: "native",
+              icon: "code",
+            },
+          ],
+          configuredDefaultProfileId: "custom:ops",
+          resolvedDefaultProfileId: "custom:ops",
+        });
+      }
+
+      return Promise.resolve(undefined);
+    });
+
+    seedReadyWorkspaceState(store, {
+      "ws-test": {
+        id: "ws-test",
+        path: "/tmp/ws-test",
+        targetRuntime: "native",
+        openedAt: 1,
+        lastActiveAt: 1,
+        uiState: {
+          leftPanelWidth: 280,
+          bottomPanelHeight: 200,
+          focusMode: false,
+        },
+      },
+    });
+    store.set(bottomPanelHeightAtom, 240);
+    setEnglishLocale(store);
+    store.set(wsClientAtom, { subscribe, sendCommand } as never);
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter>
+          <div className="mobile-terminal-sheet mobile-terminal-sheet--fullscreen">
+            <TerminalPanel chrome="mobile-fullscreen" />
+          </div>
+        </MemoryRouter>
+      </Provider>
+    );
+
+    await user.click(screen.getAllByRole("button", { name: "New Terminal" })[0]!);
+
+    const chooser = screen.getByRole("region", { name: "New Terminal sheet" });
+    const profileButtons = ["Open Default: Ops Shell", "zsh", "Python Env"].map((name) =>
+      within(chooser).getByRole("button", { name })
+    );
+
+    expect(profileButtons[0]).toHaveTextContent("Open Default: Ops Shell");
+    expect(profileButtons[1]).toHaveTextContent("zsh");
+    expect(profileButtons[2]).toHaveTextContent("Python Env");
+    expect(within(chooser).queryByRole("button", { name: "Ops Shell" })).not.toBeInTheDocument();
+
+    act(() => {
+      store.set(localeAtom, "zh");
+    });
+
+    await waitFor(() => {
+      expect(
+        within(chooser).getByRole("button", { name: "打开默认配置：Ops Shell" })
+      ).toBeInTheDocument();
+    });
+  });
+
   it("opens package commands from the toolbar button next to new terminal", async () => {
     const user = userEvent.setup();
     const store = createStore();
@@ -329,10 +726,14 @@ describe("TerminalPanel", () => {
     const newTerminalIndex = toolbarButtons.findIndex(
       (button) => button.getAttribute("aria-label") === "New Terminal"
     );
+    const profileChooserIndex = toolbarButtons.findIndex(
+      (button) => button.getAttribute("aria-label") === "Choose Terminal Profile"
+    );
     const commandButtonIndex = toolbarButtons.findIndex(
       (button) => button.getAttribute("aria-label") === "Open Commands"
     );
-    expect(commandButtonIndex).toBe(newTerminalIndex + 1);
+    expect(profileChooserIndex).toBe(newTerminalIndex + 1);
+    expect(commandButtonIndex).toBe(profileChooserIndex + 1);
     const commandButton = toolbarButtons[commandButtonIndex]!;
 
     await user.click(commandButton);
@@ -557,6 +958,86 @@ describe("TerminalPanel", () => {
     expect(screen.queryByRole("dialog", { name: "Terminal Sessions" })).toBeNull();
   });
 
+  it("renders a static desktop terminal title when only one terminal exists", async () => {
+    const user = userEvent.setup();
+    const store = createStore();
+    const subscribe = vi.fn((_topics: string[], handler: EventHandler) => {
+      handlers.push(handler);
+      return () => {
+        handlers = handlers.filter((candidate) => candidate !== handler);
+      };
+    });
+    const sendCommand = vi.fn().mockImplementation((op: string) => {
+      if (op === "terminal.list") {
+        return Promise.resolve([
+          {
+            id: "term_1",
+            workspaceId: "ws-test",
+            kind: "shell",
+            title: "/bin/zsh",
+            cwd: "/tmp/ws-test",
+            argv: ["/bin/zsh"],
+            cols: 120,
+            rows: 30,
+            alive: true,
+            createdAt: 1,
+          },
+        ]);
+      }
+
+      return Promise.resolve([]);
+    });
+
+    seedReadyWorkspaceState(store, {
+      "ws-test": {
+        id: "ws-test",
+        path: "/tmp/ws-test",
+        targetRuntime: "native",
+        openedAt: 1,
+        lastActiveAt: 1,
+        uiState: {
+          leftPanelWidth: 280,
+          bottomPanelHeight: 200,
+          focusMode: false,
+        },
+      },
+    });
+    store.set(bottomPanelHeightAtom, 240);
+    setEnglishLocale(store);
+    store.set(wsClientAtom, { subscribe, sendCommand } as never);
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter>
+          <TerminalPanel />
+        </MemoryRouter>
+      </Provider>
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("xterm-host")).toHaveTextContent("term_1");
+    });
+
+    expect(document.querySelector(".terminal-selector-btn--static")).toHaveTextContent("zsh — 1");
+    expect(
+      document.querySelector(
+        ".terminal-selector-btn--static svg, .terminal-selector-btn--static .lucide"
+      )
+    ).toBeNull();
+    expect(screen.queryByRole("button", { name: "zsh — 1" })).toBeNull();
+
+    await user.click(screen.getByRole("button", { name: "New Terminal" }));
+    expect(sendCommand).toHaveBeenCalledWith(
+      "terminal.create",
+      expect.objectContaining({
+        workspaceId: "ws-test",
+        cwdPath: undefined,
+        themeBackground: expect.any(String),
+      }),
+      undefined
+    );
+  });
+
   it("shows an error toast when terminal creation fails", async () => {
     const store = createStore();
     const subscribe = vi.fn((_topics: string[], handler: EventHandler) => {
diff --git a/packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx b/packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx
index 19f2cce97..d77c8c945 100644
--- a/packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx
+++ b/packages/web/src/features/terminal-panel/__tests__/xterm-host.test.tsx
@@ -517,15 +517,17 @@ describe("XtermHost", () => {
         }
       | undefined;
 
-    let links:
+    const links = await new Promise<
       | Array<{
           text: string;
           range: { start: { x: number; y: number }; end: { x: number; y: number } };
           activate(event: MouseEvent, text: string): void;
         }>
-      | undefined;
-    provider?.provideLinks(1, (nextLinks) => {
-      links = nextLinks;
+      | undefined
+    >((resolve) => {
+      provider?.provideLinks(1, (nextLinks) => {
+        resolve(nextLinks);
+      });
     });
 
     expect(links).toHaveLength(1);
@@ -552,7 +554,7 @@ describe("XtermHost", () => {
     expect(store.get(openEditorPathsAtomFamily("test-workspace"))).toEqual(["src/app.tsx"]);
   });
 
-  it("opens http links from terminal output in a new page", () => {
+  it("opens http links from terminal output in a new page", async () => {
     const openSpy = vi.spyOn(window, "open").mockImplementation(() => null);
     setMockBufferLines([[0, "Visit https://example.com/docs?x=1."]]);
 
@@ -580,15 +582,17 @@ describe("XtermHost", () => {
         }
       | undefined;
 
-    let links:
+    const links = await new Promise<
       | Array<{
           text: string;
           range: { start: { x: number; y: number }; end: { x: number; y: number } };
           activate(event: MouseEvent, text: string): void;
         }>
-      | undefined;
-    provider?.provideLinks(1, (nextLinks) => {
-      links = nextLinks;
+      | undefined
+    >((resolve) => {
+      provider?.provideLinks(1, (nextLinks) => {
+        resolve(nextLinks);
+      });
     });
 
     expect(links).toHaveLength(1);
@@ -609,6 +613,106 @@ describe("XtermHost", () => {
     );
   });
 
+  it("rejoins wrapped workspace paths from terminal output in the editor", async () => {
+    const store = createStore();
+    store.set(workspacesAtom, {
+      "test-workspace": {
+        id: "test-workspace",
+        path: "/repo",
+        targetRuntime: "native",
+        openedAt: 1,
+        lastActiveAt: 1,
+        uiState: {
+          leftPanelWidth: 280,
+          bottomPanelHeight: 240,
+          focusMode: false,
+        },
+      },
+    });
+    store.set(workspaceOrderAtom, ["test-workspace"]);
+    store.set(workspacesLoadStateAtom, "ready");
+    setMockBufferLines([
+      [0, "/repo/src/features/terminal-        ", false],
+      [1, "panel/links/terminal-link-provider.ts", true],
+    ]);
+
+    render(
+      <Provider store={store}>
+        <XtermHost terminalId="wrapped-link-terminal" workspaceId="test-workspace" />
+      </Provider>
+    );
+
+    expect(mockTerminal.registerLinkProvider).toHaveBeenCalledTimes(1);
+    const provider = mockTerminal.registerLinkProvider.mock.calls[0]?.[0] as
+      | {
+          provideLinks(
+            bufferLineNumber: number,
+            callback: (
+              links:
+                | Array<{
+                    text: string;
+                    range: { start: { x: number; y: number }; end: { x: number; y: number } };
+                    activate(event: MouseEvent, text: string): void;
+                  }>
+                | undefined
+            ) => void
+          ): void;
+        }
+      | undefined;
+
+    const firstRowLinks = await new Promise<
+      | Array<{
+          text: string;
+          range: { start: { x: number; y: number }; end: { x: number; y: number } };
+          activate(event: MouseEvent, text: string): void;
+        }>
+      | undefined
+    >((resolve) => {
+      provider?.provideLinks(1, (nextLinks) => {
+        resolve(nextLinks);
+      });
+    });
+
+    const secondRowLinks = await new Promise<
+      | Array<{
+          text: string;
+          range: { start: { x: number; y: number }; end: { x: number; y: number } };
+          activate(event: MouseEvent, text: string): void;
+        }>
+      | undefined
+    >((resolve) => {
+      provider?.provideLinks(2, (nextLinks) => {
+        resolve(nextLinks);
+      });
+    });
+
+    expect(firstRowLinks).toHaveLength(1);
+    expect(firstRowLinks?.[0]).toMatchObject({
+      text: "/repo/src/features/terminal-panel/links/terminal-link-provider.ts",
+      range: {
+        start: { x: 1, y: 1 },
+        end: { x: 37, y: 2 },
+      },
+    });
+    expect(secondRowLinks).toHaveLength(1);
+    expect(secondRowLinks?.[0]?.text).toBe(
+      "/repo/src/features/terminal-panel/links/terminal-link-provider.ts"
+    );
+
+    await act(async () => {
+      secondRowLinks?.[0]?.activate(new MouseEvent("click"), secondRowLinks[0].text);
+      await Promise.resolve();
+    });
+
+    expect(store.get(pendingEditorNavigationAtomFamily("test-workspace"))).toMatchObject({
+      workspaceId: "test-workspace",
+      path: "src/features/terminal-panel/links/terminal-link-provider.ts",
+      line: undefined,
+      column: undefined,
+      source: "manual",
+    });
+  });
+
   it("copies the terminal selection on desktop pointerup when copy-on-select is enabled", async () => {
     const store = createStore();
     const writeText = vi.fn().mockResolvedValue(undefined);
@@ -3789,6 +3893,64 @@ describe("XtermHost", () => {
     );
   });
 
+  it("does not treat SGR mouse tracking sequences as submitted text", async () => {
+    const store = createStore();
+    const sendTerminalInput = vi.fn().mockResolvedValue(undefined);
+
+    store.set(wsClientAtom, {
+      sendTerminalInput,
+      subscribe: vi.fn(() => () => {}),
+    } as never);
+
+    render(
+      <Provider store={store}>
+        <XtermHost terminalId="mouse-submit-terminal" workspaceId="test-workspace" />
+      </Provider>
+    );
+
+    const onDataCallback = mockTerminal.onData.mock.calls[0]?.[0];
+    expect(onDataCallback).toBeTypeOf("function");
+
+    await onDataCallback?.("\x1b[<35;17;18M");
+    await onDataCallback?.("\r");
+
+    expect(sendTerminalInput).toHaveBeenLastCalledWith(
+      "mouse-submit-terminal",
+      new TextEncoder().encode("\r"),
+      "submit",
+      undefined
+    );
+  });
+
+  it("preserves user text submitted after SGR mouse tracking sequences", async () => {
+    const store = createStore();
+    const sendTerminalInput = vi.fn().mockResolvedValue(undefined);
+
+    store.set(wsClientAtom, {
+      sendTerminalInput,
+      subscribe: vi.fn(() => () => {}),
+    } as never);
+
+    render(
+      <Provider store={store}>
+        <XtermHost terminalId="mouse-text-submit-terminal" workspaceId="test-workspace" />
+      </Provider>
+    );
+
+    const onDataCallback = mockTerminal.onData.mock.calls[0]?.[0];
+    expect(onDataCallback).toBeTypeOf("function");
+
+    await onDataCallback?.("\x1b[<35;17;18M");
+    await onDataCallback?.("fix the build\r");
+
+    expect(sendTerminalInput).toHaveBeenLastCalledWith(
+      "mouse-text-submit-terminal",
+      new TextEncoder().encode("fix the build\r"),
+      "submit",
+      "fix the build"
+    );
+  });
+
   it("renders pending image previews and shows overflow count in the third slot", () => {
     uploadHookMocks.pendingImages = [
       { id: "img-1", name: "first.png", previewUrl: "blob:first" },
@@ -5126,6 +5288,231 @@ describe("XtermHost", () => {
     expect(consoleSpy).toHaveBeenCalledWith("Failed to send terminal input:", expect.any(Error));
   });
 
+  it("rebuilds terminal history when switching back to a previously rendered terminal", async () => {
+    const store = createStore();
+    const termABytes = new TextEncoder().encode("term a snapshot\n");
+    const termBBytes = new TextEncoder().encode("term b snapshot\n");
+    const rafCallbacks: FrameRequestCallback[] = [];
+    const originalRequestAnimationFrame = global.requestAnimationFrame;
+    const originalCancelAnimationFrame = global.cancelAnimationFrame;
+
+    mockTerminal.cols = 132;
+    mockTerminal.rows = 36;
+
+    const sendCommand = vi.fn().mockImplementation((op: string, args: unknown) => {
+      if (op === "recovery.reconcile") {
+        const request = args as {
+          reason: string;
+          terminals: Array<{ terminalId: string; renderedSeq: number }>;
+        };
+        const terminal = request.terminals[0];
+
+        if (terminal?.terminalId === "term-a" && terminal.renderedSeq === 0) {
+          return Promise.resolve({
+            terminals: [
+              { terminalId: "term-a", action: "snapshot", headSeq: termABytes.byteLength },
+            ],
+          });
+        }
+
+        if (terminal?.terminalId === "term-a" && terminal.renderedSeq === termABytes.byteLength) {
+          return Promise.resolve({
+            terminals: [{ terminalId: "term-a", action: "noop", headSeq: termABytes.byteLength }],
+          });
+        }
+
+        if (terminal?.terminalId === "term-b" && terminal.renderedSeq === 0) {
+          return Promise.resolve({
+            terminals: [
+              { terminalId: "term-b", action: "snapshot", headSeq: termBBytes.byteLength },
+            ],
+          });
+        }
+
+        throw new Error(`Unexpected reconcile request: ${JSON.stringify(request)}`);
+      }
+
+      if (op === "terminal.snapshot") {
+        const request = args as { terminalId: string };
+        if (request.terminalId === "term-a") {
+          return Promise.resolve({
+            status: "ok",
+            transport: "binary",
+            streamId: 101,
+            size: termABytes.byteLength,
+            seq: termABytes.byteLength,
+            rows: 24,
+            cols: 80,
+            source: "headless",
+            bytes: termABytes,
+          } satisfies TerminalSnapshotPayload);
+        }
+
+        if (request.terminalId === "term-b") {
+          return Promise.resolve({
+            status: "ok",
+            transport: "binary",
+            streamId: 102,
+            size: termBBytes.byteLength,
+            seq: termBBytes.byteLength,
+            rows: 24,
+            cols: 80,
+            source: "headless",
+            bytes: termBBytes,
+          } satisfies TerminalSnapshotPayload);
+        }
+      }
+
+      return Promise.resolve({ status: "ok" });
+    });
+    const probeConnection = vi.fn().mockResolvedValue({ ok: true });
+
+    global.requestAnimationFrame = vi.fn((callback: FrameRequestCallback) => {
+      rafCallbacks.push(callback);
+      return rafCallbacks.length;
+    }) as typeof requestAnimationFrame;
+    global.cancelAnimationFrame = vi.fn() as typeof cancelAnimationFrame;
+
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, {
+      sendCommand,
+      subscribe: vi.fn(() => () => {}),
+      getStatus: vi.fn(() => "connected"),
+      probeConnection,
+      onStatus: vi.fn(() => () => {}),
+    } as never);
+
+    setGlobalRecoveryCoordinator(
+      createRecoveryCoordinator({
+        wsClient: {
+          getStatus: vi.fn(() => "connected"),
+          probeConnection,
+          onStatus: vi.fn(() => () => {}),
+          subscribe: vi.fn(() => () => {}),
+        } as never,
+        sendCommand: async (op, innerArgs, options) => {
+          try {
+            const data = await sendCommand(op, innerArgs as never, options);
+            return { ok: true, data };
+          } catch (error) {
+            return {
+              ok: false,
+              error: {
+                code: "command_error",
+                message: error instanceof Error ? error.message : String(error),
+              },
+            };
+          }
+        },
+        applyReplay: vi.fn(),
+        applySnapshot: vi.fn(),
+      })
+    );
+
+    const { rerender } = render(
+      <Provider store={store}>
+        <XtermHost terminalId="term-a" workspaceId="test-workspace" />
+      </Provider>
+    );
+
+    await act(async () => {
+      const callback = rafCallbacks.shift();
+      callback?.(16);
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    await waitFor(() => {
+      expectTerminalWriteData(termABytes);
+    });
+
+    rerender(
+      <Provider store={store}>
+        <XtermHost terminalId="term-b" workspaceId="test-workspace" />
+      </Provider>
+    );
+
+    await act(async () => {
+      const callback = rafCallbacks.shift();
+      callback?.(32);
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    await waitFor(() => {
+      expectTerminalWriteData(termBBytes);
+    });
+
+    rerender(
+      <Provider store={store}>
+        <XtermHost terminalId="term-a" workspaceId="test-workspace" />
+      </Provider>
+    );
+
+    await act(async () => {
+      const callback = rafCallbacks.shift();
+      callback?.(48);
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    await waitFor(() => {
+      expect(
+        sendCommand.mock.calls.filter(
+          ([op, args]) =>
+            op === "recovery.reconcile" &&
+            (args as { terminals: Array<{ terminalId: string }> }).terminals[0]?.terminalId ===
+              "term-a"
+        )
+      ).toHaveLength(2);
+    });
+
+    const termAReconcileCalls = sendCommand.mock.calls
+      .filter(
+        ([op, args]) =>
+          op === "recovery.reconcile" &&
+          (
+            args as {
+              terminals: Array<{ terminalId: string; renderedSeq: number }>;
+            }
+          ).terminals[0]?.terminalId === "term-a"
+      )
+      .map(([op, args]) => [op, args]);
+
+    expect(termAReconcileCalls).toHaveLength(2);
+    expect(termAReconcileCalls[0]).toEqual([
+      "recovery.reconcile",
+      {
+        reason: "initial_mount",
+        terminals: [{ terminalId: "term-a", renderedSeq: 0 }],
+      },
+    ]);
+    expect(termAReconcileCalls[1]).toEqual([
+      "recovery.reconcile",
+      {
+        reason: "initial_mount",
+        terminals: [{ terminalId: "term-a", renderedSeq: 0 }],
+      },
+    ]);
+
+    expect(
+      sendCommand.mock.calls.filter(
+        ([op, args]) =>
+          op === "terminal.snapshot" && (args as { terminalId: string }).terminalId === "term-a"
+      )
+    ).toHaveLength(2);
+
+    expect(
+      mockTerminal.write.mock.calls.filter(([written]) => written === termABytes)
+    ).toHaveLength(2);
+
+    global.requestAnimationFrame = originalRequestAnimationFrame;
+    global.cancelAnimationFrame = originalCancelAnimationFrame;
+  });
+
   it("buffers live output until replay finishes and drops overlapping bytes", async () => {
     const store = createStore();
     const replayChunk = new TextEncoder().encode("replay snapshot\n");
diff --git a/packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx b/packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx
index d205f4b70..a59cd0ec3 100644
--- a/packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx
+++ b/packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.test.tsx
@@ -67,6 +67,82 @@ describe("useCreateShellTerminal", () => {
     });
   });
 
+  it("passes profileId through to terminal.create when launching a non-default profile", async () => {
+    const sendCommand = vi.fn().mockResolvedValue({
+      id: "term_3",
+      workspaceId: "ws-test",
+      kind: "shell",
+      title: "Ops Shell",
+      cwd: "/tmp/ws-test",
+      argv: ["/usr/bin/env", "bash"],
+      cols: 120,
+      rows: 30,
+      alive: true,
+      createdAt: 1,
+    });
+
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+
+    const { result } = renderHook(() => useCreateShellTerminal("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.createShellTerminal({ cwdPath: "src", profileId: "custom:ops" });
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "terminal.create",
+      expect.objectContaining({
+        workspaceId: "ws-test",
+        cwdPath: "src",
+        profileId: "custom:ops",
+        themeBackground: expect.stringMatching(/^#[0-9a-fA-F]{6,8}$/),
+      }),
+      undefined
+    );
+  });
+
+  it("passes a detected Git Bash profileId through to terminal.create", async () => {
+    const sendCommand = vi.fn().mockResolvedValue({
+      id: "term_git_bash",
+      workspaceId: "ws-test",
+      kind: "shell",
+      title: "Git Bash",
+      cwd: "/tmp/ws-test",
+      argv: ["C:/Program Files/Git/bin/bash.exe"],
+      cols: 120,
+      rows: 30,
+      alive: true,
+      createdAt: 1,
+    });
+
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+
+    const { result } = renderHook(() => useCreateShellTerminal("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.createShellTerminal({ profileId: "detected:win:git-bash" });
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "terminal.create",
+      expect.objectContaining({
+        workspaceId: "ws-test",
+        cwdPath: undefined,
+        profileId: "detected:win:git-bash",
+        themeBackground: expect.stringMatching(/^#[0-9a-fA-F]{6,8}$/),
+      }),
+      undefined
+    );
+  });
+
   it("shows a warning toast and returns null when no workspace is selected", async () => {
     const sendCommand = vi.fn();
     const store = createStore();
diff --git a/packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts b/packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts
index 94749d0ee..42d4279bc 100644
--- a/packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts
+++ b/packages/web/src/features/terminal-panel/actions/use-create-shell-terminal.ts
@@ -29,7 +29,7 @@ export function useCreateShellTerminal(workspaceId: string | null) {
   const themeBackground = useTerminalThemeBackground();
 
   return {
-    async createShellTerminal(args: { cwdPath?: string } = {}) {
+    async createShellTerminal(args: { cwdPath?: string; profileId?: string } = {}) {
       if (!workspaceId) {
         pushToast({
           kind: "warning",
@@ -43,6 +43,7 @@ export function useCreateShellTerminal(workspaceId: string | null) {
         const result = await dispatch<TerminalDto>("terminal.create", {
           workspaceId,
           cwdPath: args.cwdPath,
+          profileId: args.profileId,
           themeBackground,
         });
 
diff --git a/packages/web/src/features/terminal-panel/actions/use-terminal-actions.ts b/packages/web/src/features/terminal-panel/actions/use-terminal-actions.ts
index 880d5e95f..392849928 100644
--- a/packages/web/src/features/terminal-panel/actions/use-terminal-actions.ts
+++ b/packages/web/src/features/terminal-panel/actions/use-terminal-actions.ts
@@ -13,6 +13,7 @@ import {
   terminalOutputAtomFamily,
 } from "../atoms";
 import { useCreateShellTerminal } from "./use-create-shell-terminal";
+import { useTerminalProfiles } from "./use-terminal-profiles";
 
 const EMPTY_TERMINAL_ID = "__terminal_panel_empty__";
 const EMPTY_WORKSPACE_ID = "__terminal_panel_empty_workspace__";
@@ -55,6 +56,14 @@ export function useTerminalActions() {
     terminalActiveIdAtomFamily(workspaceAtomKey)
   );
   const { createShellTerminal } = useCreateShellTerminal(activeWorkspaceId);
+  const {
+    profiles,
+    configuredDefaultProfileId,
+    resolvedDefaultProfileId,
+    defaultProfile,
+    loading: terminalProfilesLoading,
+    ensureProfilesLoaded,
+  } = useTerminalProfiles();
   const unsubscribeRef = useRef<(() => void) | null>(null);
 
   const activeTerminalMetaState = useAtomValue(
@@ -192,9 +201,18 @@ export function useTerminalActions() {
     };
   }, [activeWorkspaceId, store, wsClient]);
 
-  const handleCreateTerminal = useCallback(async () => {
-    await createShellTerminal();
-  }, [createShellTerminal]);
+  const handleCreateTerminal = useCallback(
+    async (profileId?: string) => {
+      const resolvedProfileId =
+        profileId ??
+        resolvedDefaultProfileId ??
+        (await ensureProfilesLoaded()).resolvedDefaultProfileId ??
+        undefined;
+
+      await createShellTerminal({ profileId: resolvedProfileId });
+    },
+    [createShellTerminal, ensureProfilesLoaded, resolvedDefaultProfileId]
+  );
 
   const handleCloseTerminal = useCallback(
     async (terminalId: string) => {
@@ -228,10 +246,15 @@ export function useTerminalActions() {
     activeTerminalId,
     activeTerminalMeta,
     activeWorkspaceId,
+    configuredDefaultProfileId,
+    defaultProfile,
     handleCloseTerminal,
     handleCreateTerminal,
     handleSwitchTerminal,
     hasTerminals: terminalIds.length > 0,
+    resolvedDefaultProfileId,
     terminalIds,
+    terminalProfiles: profiles,
+    terminalProfilesLoading,
   };
 }
diff --git a/packages/web/src/features/terminal-panel/actions/use-terminal-profiles.ts b/packages/web/src/features/terminal-panel/actions/use-terminal-profiles.ts
new file mode 100644
index 000000000..5dea3722c
--- /dev/null
+++ b/packages/web/src/features/terminal-panel/actions/use-terminal-profiles.ts
@@ -0,0 +1,134 @@
+import type { TerminalProfile, TerminalProfilesListResult } from "@coder-studio/core";
+import { atom, useAtomValue, useSetAtom, useStore } from "jotai";
+import { useCallback, useEffect, useMemo } from "react";
+import { type CommandResult, dispatchCommandAtom } from "../../../atoms/connection";
+
+interface TerminalProfilesState {
+  profiles: TerminalProfile[];
+  configuredDefaultProfileId?: string;
+  resolvedDefaultProfileId: string | null;
+  loading: boolean;
+  loaded: boolean;
+}
+
+const EMPTY_STATE: TerminalProfilesState = {
+  profiles: [],
+  configuredDefaultProfileId: undefined,
+  resolvedDefaultProfileId: null,
+  loading: false,
+  loaded: false,
+};
+
+const terminalProfilesStateAtom = atom<TerminalProfilesState>(EMPTY_STATE);
+export const resetTerminalProfilesAtom = atom(null, (_get, set) => {
+  set(terminalProfilesStateAtom, EMPTY_STATE);
+});
+const inflightByStore = new WeakMap<object, Promise<TerminalProfilesState>>();
+
+function normalizeProfilesResult(
+  result: CommandResult<TerminalProfilesListResult>
+): TerminalProfilesState {
+  if (!result.ok || !result.data) {
+    return {
+      ...EMPTY_STATE,
+      loaded: true,
+    };
+  }
+
+  const profiles = Array.isArray(result.data.profiles) ? result.data.profiles : [];
+  const configuredDefaultProfileId =
+    typeof result.data.configuredDefaultProfileId === "string"
+      ? result.data.configuredDefaultProfileId
+      : undefined;
+  const resolvedDefaultProfileId =
+    typeof result.data.resolvedDefaultProfileId === "string"
+      ? result.data.resolvedDefaultProfileId
+      : null;
+
+  return {
+    profiles,
+    configuredDefaultProfileId,
+    resolvedDefaultProfileId,
+    loading: false,
+    loaded: true,
+  };
+}
+
+export function useTerminalProfiles() {
+  const store = useStore();
+  const dispatch = useAtomValue(dispatchCommandAtom);
+  const state = useAtomValue(terminalProfilesStateAtom);
+  const setState = useSetAtom(terminalProfilesStateAtom);
+
+  const loadProfiles = useCallback(async () => {
+    const existingRequest = inflightByStore.get(store);
+    if (existingRequest) {
+      return existingRequest;
+    }
+
+    setState((current) =>
+      current.loading
+        ? current
+        : {
+            ...current,
+            loading: true,
+          }
+    );
+
+    const request = dispatch<TerminalProfilesListResult>("terminal.profiles.list", {})
+      .then((result) => {
+        const nextState = normalizeProfilesResult(result);
+        store.set(terminalProfilesStateAtom, nextState);
+        return nextState;
+      })
+      .catch(() => {
+        const nextState = {
+          ...EMPTY_STATE,
+          loaded: true,
+        };
+        store.set(terminalProfilesStateAtom, nextState);
+        return nextState;
+      })
+      .finally(() => {
+        inflightByStore.delete(store);
+      });
+
+    inflightByStore.set(store, request);
+    return request;
+  }, [dispatch, setState, store]);
+
+  useEffect(() => {
+    if (state.loaded || state.loading) {
+      return;
+    }
+
+    void loadProfiles();
+  }, [loadProfiles, state.loaded, state.loading]);
+
+  const defaultProfile = useMemo(() => {
+    if (!state.profiles.length) {
+      return null;
+    }
+
+    return (
+      state.profiles.find((profile) => profile.id === state.resolvedDefaultProfileId) ??
+      state.profiles[0] ??
+      null
+    );
+  }, [state.profiles, state.resolvedDefaultProfileId]);
+
+  return {
+    profiles: state.profiles,
+    configuredDefaultProfileId: state.configuredDefaultProfileId,
+    resolvedDefaultProfileId: state.resolvedDefaultProfileId,
+    defaultProfile,
+    loading: state.loading,
+    async ensureProfilesLoaded() {
+      if (state.loaded) {
+        return state;
+      }
+
+      return loadProfiles();
+    },
+  };
+}
diff --git a/packages/web/src/features/terminal-panel/links/terminal-link-provider.test.ts b/packages/web/src/features/terminal-panel/links/terminal-link-provider.test.ts
index bc62ff21c..9a14fd0fc 100644
--- a/packages/web/src/features/terminal-panel/links/terminal-link-provider.test.ts
+++ b/packages/web/src/features/terminal-panel/links/terminal-link-provider.test.ts
@@ -46,24 +46,37 @@ function createProvider(
   return { provider, openWorkspaceFile };
 }
 
-function provideLinks(
+async function provideLinks(
   provider: ReturnType<typeof createTerminalWorkspaceLinkProvider>,
   row: number
 ) {
-  let links: CapturedLink[] | undefined;
-  provider.provideLinks(row, (nextLinks) => {
-    links = nextLinks as CapturedLink[] | undefined;
+  const links = await new Promise<CapturedLink[] | undefined>((resolve) => {
+    provider.provideLinks(row, (nextLinks) => {
+      resolve(nextLinks as CapturedLink[] | undefined);
+    });
   });
+
   return links;
 }
 
 describe("createTerminalWorkspaceLinkProvider", () => {
-  it("starts a workspace path link at the path instead of adjacent label text", () => {
+  it("invokes the callback synchronously for immediate links", () => {
+    const { provider } = createProvider([[0, createBufferLine("Visit https://example.com/docs")]]);
+    let synchronouslyResolved = false;
+
+    provider.provideLinks(1, () => {
+      synchronouslyResolved = true;
+    });
+
+    expect(synchronouslyResolved).toBe(true);
+  });
+
+  it("starts a workspace path link at the path instead of adjacent label text", async () => {
     const { provider, openWorkspaceFile } = createProvider([
       [0, createBufferLine("更新文件:.stitch/designs/overlay-editor-header-scope.html")],
     ]);
 
-    const links = provideLinks(provider, 1);
+    const links = await provideLinks(provider, 1);
 
     expect(links).toHaveLength(1);
     expect(links?.[0]).toMatchObject({
@@ -84,7 +97,7 @@ describe("createTerminalWorkspaceLinkProvider", () => {
     });
   });
 
-  it("opens absolute workspace paths that wrap across terminal rows", () => {
+  it("opens absolute workspace paths that wrap across terminal rows", async () => {
     const { provider, openWorkspaceFile } = createProvider(
       [
         [0, createBufferLine("'/root/.coder-studio/uploads/ws_1779420655702_45iqdg5vv/", false)],
@@ -93,8 +106,8 @@ describe("createTerminalWorkspaceLinkProvider", () => {
       "/root/.coder-studio/uploads/ws_1779420655702_45iqdg5vv"
     );
 
-    const firstRowLinks = provideLinks(provider, 1);
-    const secondRowLinks = provideLinks(provider, 2);
+    const firstRowLinks = await provideLinks(provider, 1);
+    const secondRowLinks = await provideLinks(provider, 2);
 
     expect(firstRowLinks).toHaveLength(1);
     expect(firstRowLinks?.[0]).toMatchObject({
@@ -123,23 +136,60 @@ describe("createTerminalWorkspaceLinkProvider", () => {
     });
   });
 
-  it("does not open the wrapped tail of an absolute path outside the workspace", () => {
+  it("does not open the wrapped tail of an absolute path outside the workspace", async () => {
     const { provider, openWorkspaceFile } = createProvider([
       [0, createBufferLine("'/root/.coder-studio/uploads/ws_1779420655702_45iqdg5vv/", false)],
       [1, createBufferLine("2026-06-09/7e4ffb70-image.png' ", true)],
     ]);
 
-    expect(provideLinks(provider, 1)).toBeUndefined();
-    expect(provideLinks(provider, 2)).toBeUndefined();
+    await expect(provideLinks(provider, 1)).resolves.toBeUndefined();
+    await expect(provideLinks(provider, 2)).resolves.toBeUndefined();
     expect(openWorkspaceFile).not.toHaveBeenCalled();
   });
 
-  it("keeps line and column suffixes out of the workspace file path", () => {
+  it("rejoins wrapped workspace paths across padded terminal rows", async () => {
+    const { provider, openWorkspaceFile } = createProvider(
+      [
+        [
+          0,
+          createBufferLine(
+            "/home/spencer/workspace/coder-studio/packages/web/src/features/terminal-        ",
+            false
+          ),
+        ],
+        [1, createBufferLine("panel/links/terminal-link-provider.ts", true)],
+      ],
+      "/home/spencer/workspace/coder-studio"
+    );
+
+    const firstRowLinks = await provideLinks(provider, 1);
+    const secondRowLinks = await provideLinks(provider, 2);
+
+    expect(firstRowLinks).toHaveLength(1);
+    expect(firstRowLinks?.[0]?.text).toBe(
+      "/home/spencer/workspace/coder-studio/packages/web/src/features/terminal-panel/links/terminal-link-provider.ts"
+    );
+    expect(secondRowLinks).toHaveLength(1);
+    expect(secondRowLinks?.[0]?.text).toBe(
+      "/home/spencer/workspace/coder-studio/packages/web/src/features/terminal-panel/links/terminal-link-provider.ts"
+    );
+
+    secondRowLinks?.[0]?.activate(new MouseEvent("click"), secondRowLinks[0].text);
+    expect(openWorkspaceFile).toHaveBeenCalledWith({
+      workspaceId: "ws-1",
+      path: "packages/web/src/features/terminal-panel/links/terminal-link-provider.ts",
+      line: undefined,
+      column: undefined,
+      source: "manual",
+    });
+  });
+
+  it("keeps line and column suffixes out of the workspace file path", async () => {
     const { provider, openWorkspaceFile } = createProvider([
       [0, createBufferLine("at /root/workspace/coder-studio/packages/web/src/main.tsx:12:3")],
     ]);
 
-    const links = provideLinks(provider, 1);
+    const links = await provideLinks(provider, 1);
 
     expect(links).toHaveLength(1);
     expect(links?.[0]?.text).toBe("/root/workspace/coder-studio/packages/web/src/main.tsx:12:3");
@@ -153,4 +203,79 @@ describe("createTerminalWorkspaceLinkProvider", () => {
       source: "manual",
     });
   });
+
+  it("does not link truncated workspace paths on their own", async () => {
+    const { provider, openWorkspaceFile } = createProvider(
+      [
+        [
+          0,
+          createBufferLine(
+            "/home/spencer/workspace/coder-studio/packages/web/src/features/terminal-"
+          ),
+        ],
+      ],
+      "/home/spencer/workspace/coder-studio"
+    );
+
+    await expect(provideLinks(provider, 1)).resolves.toBeUndefined();
+    expect(openWorkspaceFile).not.toHaveBeenCalled();
+  });
+
+  it("rejoins workspace paths split across adjacent non-wrapped rows", async () => {
+    const { provider, openWorkspaceFile } = createProvider(
+      [
+        [
+          0,
+          createBufferLine(
+            "/home/spencer/workspace/coder-studio/packages/web/src/features/terminal-"
+          ),
+        ],
+        [1, createBufferLine("panel/links/terminal-link-provider.ts")],
+      ],
+      "/home/spencer/workspace/coder-studio"
+    );
+
+    const firstRowLinks = await provideLinks(provider, 1);
+    const secondRowLinks = await provideLinks(provider, 2);
+
+    expect(firstRowLinks).toHaveLength(1);
+    expect(firstRowLinks?.[0]?.text).toBe(
+      "/home/spencer/workspace/coder-studio/packages/web/src/features/terminal-panel/links/terminal-link-provider.ts"
+    );
+
+    expect(secondRowLinks).toHaveLength(1);
+    expect(secondRowLinks?.[0]?.text).toBe(
+      "/home/spencer/workspace/coder-studio/packages/web/src/features/terminal-panel/links/terminal-link-provider.ts"
+    );
+
+    secondRowLinks?.[0]?.activate(new MouseEvent("click"), secondRowLinks[0].text);
+    expect(openWorkspaceFile).toHaveBeenCalledWith({
+      workspaceId: "ws-1",
+      path: "packages/web/src/features/terminal-panel/links/terminal-link-provider.ts",
+      line: undefined,
+      column: undefined,
+      source: "manual",
+    });
+  });
+
+  it("rejoins workspace paths across padded adjacent rows", async () => {
+    const { provider } = createProvider(
+      [
+        [
+          0,
+          createBufferLine(
+            "/home/spencer/workspace/coder-studio/packages/web/src/features/terminal-        "
+          ),
+        ],
+        [1, createBufferLine("panel/links/terminal-link-provider.ts")],
+      ],
+      "/home/spencer/workspace/coder-studio"
+    );
+
+    const firstRowLinks = await provideLinks(provider, 1);
+    expect(firstRowLinks).toHaveLength(1);
+    expect(firstRowLinks?.[0]?.text).toBe(
+      "/home/spencer/workspace/coder-studio/packages/web/src/features/terminal-panel/links/terminal-link-provider.ts"
+    );
+  });
 });
diff --git a/packages/web/src/features/terminal-panel/links/terminal-link-provider.ts b/packages/web/src/features/terminal-panel/links/terminal-link-provider.ts
index 4e562ae8d..18eb9673c 100644
--- a/packages/web/src/features/terminal-panel/links/terminal-link-provider.ts
+++ b/packages/web/src/features/terminal-panel/links/terminal-link-provider.ts
@@ -43,6 +43,12 @@ interface TerminalLinkCandidate {
   startIndex: number;
 }
 
+interface LogicalLineTextSegment {
+  row: number;
+  line: TerminalBufferLineLike;
+  text: string;
+}
+
 interface LogicalLineSegment {
   row: number;
   line: TerminalBufferLineLike;
@@ -65,6 +71,8 @@ interface TerminalWorkspaceLinkProviderOptions {
 const LINK_CANDIDATE_PATTERN =
   /https?:\/\/[^\s<>"'`]+|[a-z]:[\\/][^\s<>"'`]+|\/[^\s<>"'`]+|(?:[a-z0-9_.@+-]+\/)+[^\s<>"'`]+/giu;
 const TRAILING_PUNCTUATION_PATTERN = /[),.;\]}]+$/;
+const PATH_CONTINUATION_CHARACTER_PATTERN = /[a-z0-9_./@+-]/iu;
+const TRUNCATED_PATH_TRAILING_PATTERN = /[-./]$/u;
 const HTTP_URL_PATTERN = /^https?:\/\//iu;
 
 function normalizePathSeparators(path: string): string {
@@ -154,6 +162,73 @@ function resolveWorkspaceFileTarget(
   };
 }
 
+function shouldCollapsePathBoundary(leftText: string, rightText: string): boolean {
+  const leftVisibleText = leftText.replace(/\s+$/u, "");
+  const rightVisibleText = rightText.replace(/^\s+/u, "");
+  if (!leftVisibleText || !rightVisibleText) {
+    return false;
+  }
+
+  const leftLastChar = leftVisibleText[leftVisibleText.length - 1];
+  const rightFirstChar = rightVisibleText[0];
+  if (!leftLastChar || !rightFirstChar) {
+    return false;
+  }
+
+  return (
+    PATH_CONTINUATION_CHARACTER_PATTERN.test(leftLastChar) &&
+    PATH_CONTINUATION_CHARACTER_PATTERN.test(rightFirstChar) &&
+    (/[-./]$/u.test(leftVisibleText) ||
+      rightVisibleText.includes("/") ||
+      rightVisibleText.startsWith("."))
+  );
+}
+
+function buildLogicalTerminalLine(segments: LogicalLineTextSegment[]): LogicalTerminalLine {
+  const normalizedSegments: LogicalLineTextSegment[] = [];
+
+  for (const segment of segments) {
+    let text = segment.text;
+    const previousSegment = normalizedSegments[normalizedSegments.length - 1];
+    if (previousSegment && shouldCollapsePathBoundary(previousSegment.text, text)) {
+      previousSegment.text = previousSegment.text.replace(/\s+$/u, "");
+      text = text.replace(/^\s+/u, "");
+    }
+
+    normalizedSegments.push({
+      row: segment.row,
+      line: segment.line,
+      text,
+    });
+  }
+
+  let text = "";
+  const logicalSegments = normalizedSegments.map((segment) => {
+    const startIndex = text.length;
+    text += segment.text;
+
+    return {
+      row: segment.row,
+      line: segment.line,
+      startIndex,
+      endIndex: text.length,
+    };
+  });
+
+  return {
+    text,
+    segments: logicalSegments,
+  };
+}
+
+function logicalLineToTextSegments(logicalLine: LogicalTerminalLine): LogicalLineTextSegment[] {
+  return logicalLine.segments.map((segment) => ({
+    row: segment.row,
+    line: segment.line,
+    text: logicalLine.text.slice(segment.startIndex, segment.endIndex),
+  }));
+}
+
 function getLogicalTerminalLine(
   terminal: TerminalLike,
   bufferLineNumber: number
@@ -192,21 +267,83 @@ function getLogicalTerminalLine(
     lines.push({ row: scanRow, line: nextLine });
   }
 
-  let text = "";
-  const segments = lines.map((segment, index) => {
-    const segmentText = segment.line.translateToString(index === lines.length - 1);
-    const startIndex = text.length;
-    text += segmentText;
-
-    return {
+  return buildLogicalTerminalLine(
+    lines.map((segment, index) => ({
       row: segment.row,
       line: segment.line,
-      startIndex,
-      endIndex: text.length,
-    };
-  });
+      text: segment.line.translateToString(index === lines.length - 1),
+    }))
+  );
+}
+
+function getAdjacentLogicalTerminalLine(
+  terminal: TerminalLike,
+  logicalLine: LogicalTerminalLine,
+  direction: "previous" | "next"
+): LogicalTerminalLine | null {
+  const edgeSegment =
+    direction === "previous"
+      ? logicalLine.segments[0]
+      : logicalLine.segments[logicalLine.segments.length - 1];
+  if (!edgeSegment) {
+    return null;
+  }
 
-  return { text, segments };
+  const adjacentRow = direction === "previous" ? edgeSegment.row - 1 : edgeSegment.row + 1;
+  if (adjacentRow < 0) {
+    return null;
+  }
+
+  return getLogicalTerminalLine(terminal, adjacentRow + 1);
+}
+
+function canJoinAdjacentLogicalLines(
+  left: LogicalTerminalLine,
+  right: LogicalTerminalLine
+): boolean {
+  return shouldCollapsePathBoundary(left.text, right.text);
+}
+
+function mergeLogicalTerminalLines(lines: LogicalTerminalLine[]): LogicalTerminalLine {
+  return buildLogicalTerminalLine(lines.flatMap(logicalLineToTextSegments));
+}
+
+function getLinkCandidateContexts(
+  terminal: TerminalLike,
+  bufferLineNumber: number
+): LogicalTerminalLine[] {
+  const current = getLogicalTerminalLine(terminal, bufferLineNumber);
+  if (!current) {
+    return [];
+  }
+
+  const contexts = new Map<string, LogicalTerminalLine>();
+  const addContext = (logicalLine: LogicalTerminalLine) => {
+    const firstRow = logicalLine.segments[0]?.row ?? -1;
+    const lastRow = logicalLine.segments[logicalLine.segments.length - 1]?.row ?? -1;
+    contexts.set(`${firstRow}:${lastRow}:${logicalLine.text}`, logicalLine);
+  };
+
+  addContext(current);
+
+  const previous = getAdjacentLogicalTerminalLine(terminal, current, "previous");
+  const next = getAdjacentLogicalTerminalLine(terminal, current, "next");
+  const canJoinPrevious = previous ? canJoinAdjacentLogicalLines(previous, current) : false;
+  const canJoinNext = next ? canJoinAdjacentLogicalLines(current, next) : false;
+
+  if (previous && canJoinPrevious) {
+    addContext(mergeLogicalTerminalLines([previous, current]));
+  }
+
+  if (next && canJoinNext) {
+    addContext(mergeLogicalTerminalLines([current, next]));
+  }
+
+  if (previous && next && canJoinPrevious && canJoinNext) {
+    addContext(mergeLogicalTerminalLines([previous, current, next]));
+  }
+
+  return [...contexts.values()];
 }
 
 function findSegmentForStringIndex(
@@ -282,41 +419,72 @@ function rangeIntersectsBufferLine(range: TerminalLinkRange, bufferLineNumber: n
   return range.start.y <= bufferLineNumber && range.end.y >= bufferLineNumber;
 }
 
-function buildWorkspaceFileLinks(
+function compareBufferPosition(
+  left: { x: number; y: number },
+  right: { x: number; y: number }
+): number {
+  if (left.y !== right.y) {
+    return left.y - right.y;
+  }
+
+  return left.x - right.x;
+}
+
+function rangeContainsRange(outer: TerminalLinkRange, inner: TerminalLinkRange): boolean {
+  return (
+    compareBufferPosition(outer.start, inner.start) <= 0 &&
+    compareBufferPosition(inner.end, outer.end) <= 0
+  );
+}
+
+function isProbablyTruncatedWorkspacePathCandidate(
   logicalLine: LogicalTerminalLine,
+  candidate: TerminalLinkCandidate
+): boolean {
+  if (!TRUNCATED_PATH_TRAILING_PATTERN.test(candidate.text)) {
+    return false;
+  }
+
+  const visibleLogicalTextLength = logicalLine.text.replace(/\s+$/u, "").length;
+  return candidate.startIndex + candidate.text.length === visibleLogicalTextLength;
+}
+
+function buildWorkspaceFileLinks(
+  logicalLines: LogicalTerminalLine[],
   bufferLineNumber: number,
   workspacePath: string | undefined,
   openWorkspaceFile: TerminalWorkspaceLinkProviderOptions["openWorkspaceFile"],
   workspaceId: string
 ): TerminalLink[] {
-  const links: TerminalLink[] = [];
+  const links = logicalLines.flatMap((logicalLine) =>
+    findLinkCandidates(logicalLine.text).map((candidate) => {
+      const range = buildCandidateRange(logicalLine, candidate);
+      if (!range || !rangeIntersectsBufferLine(range, bufferLineNumber)) {
+        return null;
+      }
 
-  for (const candidate of findLinkCandidates(logicalLine.text)) {
-    const range = buildCandidateRange(logicalLine, candidate);
-    if (!range || !rangeIntersectsBufferLine(range, bufferLineNumber)) {
-      continue;
-    }
+      const text = candidate.text;
 
-    const text = candidate.text;
+      if (HTTP_URL_PATTERN.test(text)) {
+        return {
+          text,
+          range,
+          activate: () => {
+            window.open(text, "_blank", "noopener,noreferrer");
+          },
+        } satisfies TerminalLink;
+      }
 
-    if (HTTP_URL_PATTERN.test(text)) {
-      links.push({
-        text,
-        range,
-        activate: () => {
-          window.open(text, "_blank", "noopener,noreferrer");
-        },
-      });
-      continue;
-    }
+      if (!workspacePath) {
+        return null;
+      }
 
-    if (workspacePath) {
       const target = resolveWorkspaceFileTarget(text, workspacePath);
-      if (!target) {
-        continue;
+      if (!target || isProbablyTruncatedWorkspacePathCandidate(logicalLine, candidate)) {
+        return null;
       }
 
-      links.push({
+      return {
         text,
         range,
         activate: () => {
@@ -328,25 +496,52 @@ function buildWorkspaceFileLinks(
             source: "manual",
           });
         },
-      });
+      } satisfies TerminalLink;
+    })
+  );
+
+  const resolvedLinks = links.filter((link): link is TerminalLink => link !== null);
+
+  const accepted: TerminalLink[] = [];
+  for (const link of [...resolvedLinks].sort(
+    (left, right) => right.text.length - left.text.length
+  )) {
+    const duplicate = accepted.some(
+      (existing) =>
+        existing.text === link.text &&
+        compareBufferPosition(existing.range.start, link.range.start) === 0 &&
+        compareBufferPosition(existing.range.end, link.range.end) === 0
+    );
+    if (duplicate) {
+      continue;
+    }
+
+    if (accepted.some((existing) => rangeContainsRange(existing.range, link.range))) {
+      continue;
     }
+
+    accepted.push(link);
   }
 
-  return links;
+  return accepted.sort(
+    (left, right) =>
+      compareBufferPosition(left.range.start, right.range.start) ||
+      compareBufferPosition(left.range.end, right.range.end)
+  );
 }
 
 export function createTerminalWorkspaceLinkProvider(options: TerminalWorkspaceLinkProviderOptions) {
   return {
     provideLinks(bufferLineNumber: number, callback: (links: TerminalLink[] | undefined) => void) {
       const workspacePath = options.getWorkspacePath();
-      const logicalLine = getLogicalTerminalLine(options.terminal, bufferLineNumber);
-      if (!logicalLine) {
+      const logicalLines = getLinkCandidateContexts(options.terminal, bufferLineNumber);
+      if (logicalLines.length === 0) {
         callback(undefined);
         return;
       }
 
       const links = buildWorkspaceFileLinks(
-        logicalLine,
+        logicalLines,
         bufferLineNumber,
         workspacePath,
         options.openWorkspaceFile,
diff --git a/packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx b/packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx
index fa02511e3..21f435368 100644
--- a/packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx
+++ b/packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.test.tsx
@@ -2,6 +2,7 @@ import { act, renderHook } from "@testing-library/react";
 import { createStore, Provider } from "jotai";
 import React from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SKILL_PATH_DRAG_MIME } from "../../../lib/skill-path-drag";
 import { WORKSPACE_PATH_DRAG_MIME } from "../../../lib/workspace-path-drag";
 import { toastsAtom } from "../../notifications/atoms";
 import { usePasteDropUpload } from "./use-paste-drop-upload.js";
@@ -85,6 +86,52 @@ function fireWorkspacePathDrop(
   return event;
 }
 
+function fireSkillPathDragOver(
+  target: HTMLElement,
+  payload: {
+    skillSlug: string;
+    path: string;
+    absolutePath: string;
+    kind: "file" | "dir";
+  }
+) {
+  const event = new Event("dragover", { bubbles: true, cancelable: true });
+  Object.defineProperty(event, "dataTransfer", {
+    value: {
+      files: [],
+      types: [SKILL_PATH_DRAG_MIME, "text/plain"],
+      items: [],
+      getData: (type: string) =>
+        type === SKILL_PATH_DRAG_MIME ? JSON.stringify(payload) : payload.absolutePath,
+    },
+  });
+  target.dispatchEvent(event);
+  return event;
+}
+
+function fireSkillPathDrop(
+  target: HTMLElement,
+  payload: {
+    skillSlug: string;
+    path: string;
+    absolutePath: string;
+    kind: "file" | "dir";
+  }
+) {
+  const event = new Event("drop", { bubbles: true, cancelable: true });
+  Object.defineProperty(event, "dataTransfer", {
+    value: {
+      files: [],
+      types: [SKILL_PATH_DRAG_MIME, "text/plain"],
+      items: [],
+      getData: (type: string) =>
+        type === SKILL_PATH_DRAG_MIME ? JSON.stringify(payload) : payload.absolutePath,
+    },
+  });
+  target.dispatchEvent(event);
+  return event;
+}
+
 function fireTextDrop(target: HTMLElement) {
   const event = new Event("drop", { bubbles: true, cancelable: true });
   Object.defineProperty(event, "dataTransfer", {
@@ -752,6 +799,41 @@ describe("usePasteDropUpload", () => {
     expect(result.current.busy).toBe(false);
   });
 
+  it("prevents default for internal skill drags and inserts a quoted absolute path", async () => {
+    const store = createStore();
+    const { result } = renderHook(
+      () =>
+        usePasteDropUpload({
+          containerRef: { current: container },
+          workspaceId: "ws-1",
+          terminalId: "terminal-1",
+          sendTextToTerminal: sendInput,
+          enabled: true,
+        }),
+      { wrapper: makeWrapper(store) }
+    );
+
+    const payload = {
+      skillSlug: "my-review-skill",
+      path: "refs/guide.md",
+      absolutePath: "/root/.agents/skills/my-review-skill/refs/guide.md",
+      kind: "file" as const,
+    };
+
+    const dragOver = fireSkillPathDragOver(container, payload);
+    expect(dragOver.defaultPrevented).toBe(true);
+
+    await act(async () => {
+      const drop = fireSkillPathDrop(container, payload);
+      expect(drop.defaultPrevented).toBe(true);
+      await flushAsyncWork();
+    });
+
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+    expect(sendInput).toHaveBeenCalledWith("'/root/.agents/skills/my-review-skill/refs/guide.md' ");
+    expect(result.current.busy).toBe(false);
+  });
+
   it("keeps internal path insertion ordered behind earlier uploads", async () => {
     const store = createStore();
     let resolveUpload: ((value: Response) => void) | undefined;
diff --git a/packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.ts b/packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.ts
index 2d04a9a3c..50e53e4c0 100644
--- a/packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.ts
+++ b/packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.ts
@@ -2,6 +2,7 @@ import { atom, useAtom, useSetAtom, useStore } from "jotai";
 import { atomFamily } from "jotai-family";
 import { type RefObject, useCallback, useEffect, useRef, useState } from "react";
 import { useTranslation } from "../../../lib/i18n";
+import { getSkillPathDragPayload, hasSkillPathDragType } from "../../../lib/skill-path-drag";
 import {
   getWorkspacePathDragPayload,
   hasWorkspacePathDragType,
@@ -332,6 +333,35 @@ export function usePasteDropUpload(opts: Options): PasteDropUploadActions {
     [pushToast, runSequence, t, workspaceId]
   );
 
+  const handleSkillPathDrop = useCallback(
+    async (dataTransfer: DataTransfer | null | undefined) => {
+      const payload = getSkillPathDragPayload(dataTransfer);
+      if (!payload) {
+        pushToast({
+          kind: "error",
+          title: t("terminal.upload.drop_failed"),
+          body: t("terminal.upload.drop_read_failed"),
+          duration: 3_000,
+        });
+        return;
+      }
+
+      await runSequence(async () => `${quoteShellSingle(payload.absolutePath)} `, {
+        trackBusy: false,
+        onError: (error) => {
+          console.debug("Skill path drop failed:", error);
+          pushToast({
+            kind: "error",
+            title: t("terminal.upload.drop_failed"),
+            body: t("terminal.upload.drop_insert_failed"),
+            duration: 3_000,
+          });
+        },
+      });
+    },
+    [pushToast, runSequence, t]
+  );
+
   const handleClipboardPaste = useCallback(async () => {
     if (!enabled) {
       return;
@@ -437,17 +467,28 @@ export function usePasteDropUpload(opts: Options): PasteDropUploadActions {
         return;
       }
 
-      if (!hasWorkspacePathDragType(event.dataTransfer)) {
+      if (
+        !hasWorkspacePathDragType(event.dataTransfer) &&
+        !hasSkillPathDragType(event.dataTransfer)
+      ) {
         return;
       }
 
       event.preventDefault();
       event.stopPropagation();
-      void handleWorkspacePathDrop(event.dataTransfer);
+      if (hasWorkspacePathDragType(event.dataTransfer)) {
+        void handleWorkspacePathDrop(event.dataTransfer);
+        return;
+      }
+
+      void handleSkillPathDrop(event.dataTransfer);
     };
 
     const onDragOver = (event: DragEvent) => {
-      if (hasWorkspacePathDragType(event.dataTransfer)) {
+      if (
+        hasWorkspacePathDragType(event.dataTransfer) ||
+        hasSkillPathDragType(event.dataTransfer)
+      ) {
         event.preventDefault();
         return;
       }
@@ -467,7 +508,14 @@ export function usePasteDropUpload(opts: Options): PasteDropUploadActions {
       element.removeEventListener("drop", onDrop, { capture: true });
       element.removeEventListener("dragover", onDragOver, { capture: true });
     };
-  }, [collectPendingFiles, containerRef, enabled, handleFiles, handleWorkspacePathDrop]);
+  }, [
+    collectPendingFiles,
+    containerRef,
+    enabled,
+    handleFiles,
+    handleSkillPathDrop,
+    handleWorkspacePathDrop,
+  ]);
 
   return {
     busy,
diff --git a/packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx b/packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx
index d060cf65e..b9aba176f 100644
--- a/packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx
+++ b/packages/web/src/features/terminal-panel/views/shared/terminal-panel.tsx
@@ -2,7 +2,6 @@ import { useAtom, useStore } from "jotai";
 import { ChevronDown, Command, X } from "lucide-react";
 import { type ReactNode, useEffect, useState } from "react";
 import {
-  Button,
   EmptyState,
   IconButton,
   Popover,
@@ -16,6 +15,7 @@ import { TaskCommandSidePanel } from "../../../tasks";
 import { useTerminalActions } from "../../actions/use-terminal-actions";
 import { terminalCommandSidePanelOpenAtomFamily, terminalMetaAtomFamily } from "../../atoms";
 import { formatTerminalTitle } from "../../components/title-format";
+import { TerminalProfileCreateButton } from "./terminal-profile-create-button";
 import { TerminalSelectorItem } from "./terminal-selector-item";
 import { XtermHost } from "./xterm-host";
 
@@ -46,11 +46,14 @@ export function TerminalPanel({
     activeTerminalId,
     activeTerminalMeta,
     activeWorkspaceId,
+    defaultProfile,
     handleCloseTerminal,
     handleCreateTerminal,
     handleSwitchTerminal,
     hasTerminals,
     terminalIds,
+    terminalProfiles,
+    terminalProfilesLoading,
   } = useTerminalActions();
   const activeTerminalIndex = activeTerminalId ? terminalIds.indexOf(activeTerminalId) : 0;
   const activeTerminalTitle = formatTerminalTitle(
@@ -187,15 +190,14 @@ export function TerminalPanel({
 
             {isMobileFullscreen ? (
               <div className="terminal-toolbar-actions">
-                <Tooltip content={t("action.open")}>
-                  <IconButton
-                    className="panel-toolbar-btn"
-                    aria-label={t("terminal.new_terminal")}
-                    icon={<ThemedIcon semantic="terminal.action.new" size={14} />}
-                    onClick={handleCreateTerminal}
-                    size="sm"
-                  />
-                </Tooltip>
+                <TerminalProfileCreateButton
+                  defaultProfile={defaultProfile}
+                  loading={terminalProfilesLoading}
+                  mobile
+                  profiles={terminalProfiles}
+                  variant="toolbar"
+                  onCreateTerminal={handleCreateTerminal}
+                />
               </div>
             ) : null}
           </div>
@@ -254,14 +256,12 @@ export function TerminalPanel({
                           </button>
                         </Popover>
                       ) : (
-                        <button
-                          type="button"
-                          className="terminal-selector-btn"
+                        <div
+                          className="terminal-selector-btn terminal-selector-btn--static"
                           aria-label={activeTerminalTitle}
                         >
                           <span>{activeTerminalTitle}</span>
-                          <ChevronDown size={12} />
-                        </button>
+                        </div>
                       )}
                     </div>
                   ) : null}
@@ -289,15 +289,13 @@ export function TerminalPanel({
               )}
 
               <div className="terminal-toolbar-actions">
-                <Tooltip content={t("action.open")}>
-                  <IconButton
-                    className="panel-toolbar-btn"
-                    aria-label={t("terminal.new_terminal")}
-                    icon={<ThemedIcon semantic="terminal.action.new" size={14} />}
-                    onClick={handleCreateTerminal}
-                    size="sm"
-                  />
-                </Tooltip>
+                <TerminalProfileCreateButton
+                  defaultProfile={defaultProfile}
+                  loading={terminalProfilesLoading}
+                  profiles={terminalProfiles}
+                  variant="toolbar"
+                  onCreateTerminal={handleCreateTerminal}
+                />
                 {!isMobileFullscreen ? (
                   <Tooltip
                     content={
@@ -332,14 +330,14 @@ export function TerminalPanel({
           {!hasTerminals ? (
             <EmptyState
               action={
-                <Button
-                  variant="primary"
-                  size="sm"
-                  onClick={handleCreateTerminal}
-                  leadingIcon={<ThemedIcon semantic="terminal.action.new" size={14} />}
-                >
-                  {t("terminal.new_terminal")}
-                </Button>
+                <TerminalProfileCreateButton
+                  defaultProfile={defaultProfile}
+                  loading={terminalProfilesLoading}
+                  mobile={isMobileFullscreen}
+                  profiles={terminalProfiles}
+                  variant="empty-state"
+                  onCreateTerminal={handleCreateTerminal}
+                />
               }
               className="bottom-terminal-empty"
               description={<p className="bottom-terminal-empty-hint">{t("terminal.empty_hint")}</p>}
diff --git a/packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx b/packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx
new file mode 100644
index 000000000..98af5e380
--- /dev/null
+++ b/packages/web/src/features/terminal-panel/views/shared/terminal-profile-create-button.tsx
@@ -0,0 +1,257 @@
+import type { TerminalProfile } from "@coder-studio/core";
+import { ChevronDown } from "lucide-react";
+import { useMemo, useState } from "react";
+import { Button, IconButton, Popover, ThemedIcon, Tooltip } from "../../../../components/ui";
+import { useTranslation } from "../../../../lib/i18n";
+import { MobileSelectSheet } from "../../../mobile-select";
+
+interface TerminalProfileCreateButtonProps {
+  profiles: TerminalProfile[];
+  defaultProfile: TerminalProfile | null;
+  loading: boolean;
+  mobile?: boolean;
+  variant?: "toolbar" | "empty-state";
+  onCreateTerminal: (profileId?: string) => Promise<void> | void;
+}
+
+function getOrderedProfiles(
+  profiles: TerminalProfile[],
+  defaultProfileId: string | null | undefined
+): TerminalProfile[] {
+  if (!defaultProfileId) {
+    return profiles;
+  }
+
+  const defaultProfile = profiles.find((profile) => profile.id === defaultProfileId);
+  if (!defaultProfile) {
+    return profiles;
+  }
+
+  return [defaultProfile, ...profiles.filter((profile) => profile.id !== defaultProfileId)];
+}
+
+export function TerminalProfileCreateButton({
+  profiles,
+  defaultProfile,
+  loading,
+  mobile = false,
+  variant = "toolbar",
+  onCreateTerminal,
+}: TerminalProfileCreateButtonProps) {
+  const t = useTranslation();
+  const [desktopChooserOpen, setDesktopChooserOpen] = useState(false);
+  const [mobileChooserOpen, setMobileChooserOpen] = useState(false);
+  const chooserLabel = t("terminal.profile_chooser_label");
+  const configureProfilesLabel = t("terminal.profile_configure");
+  const orderedProfiles = useMemo(
+    () => getOrderedProfiles(profiles, defaultProfile?.id),
+    [defaultProfile?.id, profiles]
+  );
+  const mobileProfiles = useMemo(() => {
+    if (!defaultProfile) {
+      return orderedProfiles.map((profile) => ({
+        id: profile.id,
+        label: profile.label,
+      }));
+    }
+
+    return [
+      {
+        id: defaultProfile.id,
+        label: t("terminal.open_default_profile", { label: defaultProfile.label }),
+      },
+      ...profiles
+        .filter((profile) => profile.id !== defaultProfile.id)
+        .map((profile) => ({
+          id: profile.id,
+          label: profile.label,
+        })),
+    ];
+  }, [defaultProfile, orderedProfiles, profiles, t]);
+
+  const profileSections = useMemo(() => {
+    const customProfiles = orderedProfiles.filter((profile) => profile.source === "custom");
+    const detectedProfiles = orderedProfiles.filter((profile) => profile.source === "detected");
+    const orderedSources =
+      defaultProfile?.source === "custom"
+        ? [
+            ["custom", customProfiles],
+            ["detected", detectedProfiles],
+          ]
+        : [
+            ["detected", detectedProfiles],
+            ["custom", customProfiles],
+          ];
+
+    return orderedSources
+      .filter(([, items]) => items.length > 0)
+      .map(([source, items]) => ({
+        source,
+        items,
+      }));
+  }, [defaultProfile?.source, orderedProfiles]);
+
+  const runCreate = async (profileId?: string) => {
+    await onCreateTerminal(profileId);
+    setDesktopChooserOpen(false);
+    setMobileChooserOpen(false);
+  };
+
+  if (mobile) {
+    return (
+      <>
+        {variant === "toolbar" ? (
+          <Tooltip content={t("action.open")}>
+            <IconButton
+              className="panel-toolbar-btn"
+              aria-label={t("terminal.new_terminal")}
+              icon={<ThemedIcon semantic="terminal.action.new" size={14} />}
+              onClick={() => setMobileChooserOpen(true)}
+              size="sm"
+            />
+          </Tooltip>
+        ) : (
+          <Button
+            variant="primary"
+            size="sm"
+            onClick={() => setMobileChooserOpen(true)}
+            leadingIcon={<ThemedIcon semantic="terminal.action.new" size={14} />}
+          >
+            {t("terminal.new_terminal")}
+          </Button>
+        )}
+        {mobileChooserOpen ? (
+          <MobileSelectSheet
+            title={t("terminal.new_terminal")}
+            loading={loading}
+            sections={[
+              {
+                kind: "options",
+                id: "terminal-profiles",
+                items: mobileProfiles,
+              },
+            ]}
+            onClose={() => setMobileChooserOpen(false)}
+            onSelect={(profileId) => runCreate(profileId)}
+          />
+        ) : null}
+      </>
+    );
+  }
+
+  const primaryButton =
+    variant === "empty-state" ? (
+      <Button
+        variant="primary"
+        size="sm"
+        onClick={() => void runCreate(defaultProfile?.id)}
+        leadingIcon={<ThemedIcon semantic="terminal.action.new" size={14} />}
+      >
+        {t("terminal.new_terminal")}
+      </Button>
+    ) : (
+      <Tooltip content={t("action.open")}>
+        <IconButton
+          className="panel-toolbar-btn"
+          aria-label={t("terminal.new_terminal")}
+          icon={<ThemedIcon semantic="terminal.action.new" size={14} />}
+          onClick={() => void runCreate(defaultProfile?.id)}
+          size="sm"
+        />
+      </Tooltip>
+    );
+
+  return (
+    <div
+      className={`terminal-profile-create-button terminal-profile-create-button--${variant}`}
+      style={{ display: "flex", alignItems: "center", gap: "2px" }}
+    >
+      {primaryButton}
+      <Popover
+        content={
+          <div className="terminal-profile-create-button__menu">
+            {profileSections.map((section) => (
+              <div
+                key={section.source}
+                className="terminal-profile-create-button__group"
+                style={{ display: "grid", gap: "0.375rem", paddingBottom: "0.75rem" }}
+              >
+                <p
+                  className="terminal-profile-create-button__group-label"
+                  style={{
+                    margin: 0,
+                    color: "var(--text-tertiary)",
+                    fontSize: "0.75rem",
+                    textTransform: "uppercase",
+                  }}
+                >
+                  {t(
+                    section.source === "custom"
+                      ? "terminal.profile_source_custom"
+                      : "terminal.profile_source_detected"
+                  )}
+                </p>
+                {section.items.map((profile) => (
+                  <button
+                    key={profile.id}
+                    type="button"
+                    className="terminal-profile-create-button__item"
+                    onClick={() => void runCreate(profile.id)}
+                    style={{
+                      border: "none",
+                      background: "transparent",
+                      color: "inherit",
+                      cursor: "pointer",
+                      display: "flex",
+                      justifyContent: "space-between",
+                      padding: 0,
+                      textAlign: "left",
+                    }}
+                  >
+                    <span>{profile.label}</span>
+                    {profile.id === defaultProfile?.id ? (
+                      <span style={{ color: "var(--text-tertiary)", fontSize: "0.75rem" }}>
+                        {t("terminal.default_badge")}
+                      </span>
+                    ) : null}
+                  </button>
+                ))}
+              </div>
+            ))}
+            <div
+              className="terminal-profile-create-button__footer"
+              style={{
+                borderTop: "1px solid var(--border-subtle)",
+                display: "flex",
+                justifyContent: "flex-end",
+                paddingTop: "0.75rem",
+              }}
+            >
+              <Button
+                as="a"
+                href="/more/settings/terminal#terminal-profiles"
+                variant="ghost"
+                size="sm"
+              >
+                {configureProfilesLabel}
+              </Button>
+            </div>
+          </div>
+        }
+        contentClassName="terminal-profile-create-button__popover"
+        forceMode="desktop"
+        open={desktopChooserOpen}
+        placement="bottom-end"
+        title={t("terminal.new_terminal")}
+        onOpenChange={setDesktopChooserOpen}
+      >
+        <IconButton
+          aria-label={chooserLabel}
+          className="panel-toolbar-btn terminal-profile-create-button__toggle"
+          icon={<ChevronDown size={14} />}
+          size="sm"
+        />
+      </Popover>
+    </div>
+  );
+}
diff --git a/packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx b/packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx
index 50d991024..508d3d6c8 100644
--- a/packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx
+++ b/packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx
@@ -83,6 +83,8 @@ const MOBILE_TOUCH_MOMENTUM_FRAME_MS = 16;
 const MOBILE_COPY_MODE_LONG_PRESS_MS = 500;
 const MOBILE_COPY_MODE_MOVE_TOLERANCE_PX = 10;
 const TERMINAL_FOCUS_REPORTING_BYTES = new Set(["\x1b[I", "\x1b[O"]);
+const TERMINAL_ESCAPE_SEQUENCE_PATTERN =
+  /^\x1b(?:\[[0-9;?<>]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|P[\s\S]*?\x1b\\|[@-_])/;
 const TERMINAL_COPY_ON_SELECT_ERROR_THROTTLE_MS = 3_000;
 const TERMINAL_RECOVERY_LOADING_OVERLAY_DELAY_MS = 1_200;
 
@@ -247,9 +249,7 @@ function consumeTerminalInputDraft(
 
     if (char === "\x1b") {
       const remaining = data.slice(index);
-      const escapeMatch = remaining.match(
-        /^\x1b(?:\[[0-9;?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|P[\s\S]*?\x1b\\|[@-_])/
-      );
+      const escapeMatch = remaining.match(TERMINAL_ESCAPE_SEQUENCE_PATTERN);
       if (escapeMatch) {
         index += escapeMatch[0].length - 1;
         continue;
@@ -1702,6 +1702,20 @@ export function XtermHost({
     updateShiftArmed(false);
     inputDraftRef.current = "";
     inputRevisionRef.current += 1;
+    // XtermHost is reused across terminal tab switches, so per-terminal
+    // recovery cursors must be reset before the next terminal registers with
+    // the global recovery coordinator. Otherwise the new terminal can inherit
+    // the previous tab's rendered seq and incorrectly reconcile to `noop`,
+    // leaving a freshly-created xterm instance blank after switching back.
+    replayedSeqRef.current = 0;
+    latestRenderedSeqRef.current = 0;
+    recoveryReplayAnchorSeqRef.current = null;
+    pendingReplayChunksRef.current = [];
+    replayCompletedRef.current = false;
+    coldStartStateRef.current = "idle";
+    activeHistoricalRecoveryModeRef.current = null;
+    pendingRecoveryModeRef.current = null;
+    reconnectRecoveryTriggerRef.current = null;
     clearPendingImagesRef.current?.();
   }, [terminalId, updateCtrlMode, updateShiftArmed, workspaceId]);
 
diff --git a/packages/web/src/features/topbar/components/tab.test.tsx b/packages/web/src/features/topbar/components/tab.test.tsx
index 1ea615da3..3288419d9 100644
--- a/packages/web/src/features/topbar/components/tab.test.tsx
+++ b/packages/web/src/features/topbar/components/tab.test.tsx
@@ -296,7 +296,7 @@ describe("WorkspaceTab", () => {
     expect(routerMocks.navigate).not.toHaveBeenCalled();
   });
 
-  it("renders unread counts through the shared badge primitive and truncates above max", () => {
+  it("does not render an unread badge even when unread counts exist", () => {
     const workspace = {
       ...createWorkspace("ws-2", "/tmp/two"),
       unreadCount: 12,
@@ -306,19 +306,6 @@ describe("WorkspaceTab", () => {
 
     renderWorkspaceTab(store, workspace);
 
-    expect(screen.getByText("9+")).toHaveClass("topbar-unread");
-  });
-
-  it("does not render an unread badge when the count is zero", () => {
-    const workspace = {
-      ...createWorkspace("ws-2", "/tmp/two"),
-      unreadCount: 0,
-    };
-    const store = createStore();
-    store.set(localeAtom, "en");
-
-    renderWorkspaceTab(store, workspace);
-
     expect(document.querySelector(".topbar-unread")).toBeNull();
   });
 
diff --git a/packages/web/src/features/topbar/components/tab.tsx b/packages/web/src/features/topbar/components/tab.tsx
index 287f26d40..b8d1ca089 100644
--- a/packages/web/src/features/topbar/components/tab.tsx
+++ b/packages/web/src/features/topbar/components/tab.tsx
@@ -2,13 +2,13 @@
  * Workspace Tab Component
  *
  * Individual workspace tab in the topbar.
- * Shows workspace name, status indicator, unread badge, and close button.
+ * Shows workspace name, session status mini map, and close button.
  */
 
 import type { Workspace } from "@coder-studio/core";
 import { X } from "lucide-react";
 import type { FC } from "react";
-import { Badge, IconButton, Tab, Tooltip } from "../../../components/ui";
+import { IconButton, Tab, Tooltip } from "../../../components/ui";
 import { useTranslation } from "../../../lib/i18n";
 import { useWorkspaceSessions } from "../../agent-panes/actions/use-workspace-sessions";
 import { formatWorkspaceLabel } from "../../notifications/format";
@@ -31,7 +31,6 @@ interface WorkspaceTabProps {
  * PRD §5.1.2:
  *   - Session mini map (one cell per pane, status-coded)
  *   - Tab text (truncated)
- *   - Unread badge (conditional, count display)
  *   - Close button (visible on hover)
  */
 export const WorkspaceTab: FC<WorkspaceTabProps> = ({ workspace, isActive }) => {
@@ -67,13 +66,12 @@ export const WorkspaceTab: FC<WorkspaceTabProps> = ({ workspace, isActive }) =>
             <span className="topbar-tab-name">{displayName}</span>
           </Tooltip>
           <WorkspaceSessionMiniMap cells={miniMapCells} columns={miniMapColumns} />
-          <Badge count={workspace.unreadCount ?? 0} max={9} />
         </span>
       </Tab>
       <IconButton
         className="topbar-close"
         aria-label={t("action.close_workspace")}
-        icon={<X size={14} />}
+        icon={<X size={12} />}
         onClick={handleClose}
         size="sm"
       />
diff --git a/packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx b/packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx
index dc9dc4129..3c79145ba 100644
--- a/packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx
+++ b/packages/web/src/features/ui-actions/use-ui-action-subscription.test.tsx
@@ -3,7 +3,7 @@
 import { Topics, type UiActionEvent } from "@coder-studio/core";
 import { act, render, waitFor } from "@testing-library/react";
 import { createStore, Provider } from "jotai";
-import { describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { commandPaletteOpenAtom, quickOpenOpenAtom } from "../../atoms/app-ui";
 import { wsClientAtom } from "../../atoms/connection";
 import { workspacesAtom } from "../../atoms/workspaces";
@@ -27,6 +27,32 @@ import {
 } from "../workspace/atoms/layout";
 import { useUiActionSubscription } from "./use-ui-action-subscription";
 
+const { persistUiStateSpy } = vi.hoisted(() => ({
+  persistUiStateSpy: vi.fn(),
+}));
+
+vi.mock("../workspace/actions/use-workspace-ui-state-persistence", async (importOriginal) => {
+  const actual =
+    await importOriginal<
+      typeof import("../workspace/actions/use-workspace-ui-state-persistence")
+    >();
+
+  return {
+    ...actual,
+    useWorkspaceUiStatePersistence: (workspaceId: string) => {
+      const result = actual.useWorkspaceUiStatePersistence(workspaceId);
+
+      return {
+        ...result,
+        persistUiState: async (patch: Parameters<typeof result.persistUiState>[0]) => {
+          persistUiStateSpy(patch);
+          return result.persistUiState(patch);
+        },
+      };
+    },
+  };
+});
+
 function Harness({ workspaceId }: { workspaceId: string }) {
   useUiActionSubscription(workspaceId);
   return null;
@@ -48,16 +74,52 @@ function createWorkspace(id: string) {
   };
 }
 
-function setupHarness() {
+function createWsClientMocks() {
   let handler: ((topic: string, payload: unknown, seq: number) => void) | null = null;
   const unsubscribe = vi.fn();
   const subscribe = vi.fn((_topics: string[], nextHandler: typeof handler) => {
     handler = nextHandler;
     return unsubscribe;
   });
+  const sendCommand = vi.fn(async (op: string, args: unknown) => {
+    if (op === "workspace.uiState.set") {
+      const { workspaceId, uiState } = args as {
+        workspaceId: string;
+        uiState: (ReturnType<typeof createWorkspace> & { uiState: unknown })["uiState"];
+      };
+
+      return {
+        ...createWorkspace(workspaceId),
+        uiState,
+      };
+    }
+
+    return null;
+  });
+
+  return {
+    get handler() {
+      return handler;
+    },
+    subscribe,
+    unsubscribe,
+    sendCommand,
+  };
+}
+
+function setupHarness(options?: { initialWsClient?: unknown }) {
+  const wsClientMocks = createWsClientMocks();
   const store = createStore();
   store.set(workspacesAtom, { "ws-1": createWorkspace("ws-1") } as never);
-  store.set(wsClientAtom, { subscribe } as never);
+  store.set(
+    wsClientAtom,
+    (options && "initialWsClient" in options
+      ? options.initialWsClient
+      : {
+          subscribe: wsClientMocks.subscribe,
+          sendCommand: wsClientMocks.sendCommand,
+        }) as never
+  );
 
   const view = render(
     <Provider store={store}>
@@ -67,11 +129,19 @@ function setupHarness() {
 
   const emit = async (payload: unknown) => {
     await act(async () => {
-      handler?.(Topics.workspaceUiAction("ws-1"), payload, 1);
+      wsClientMocks.handler?.(Topics.workspaceUiAction("ws-1"), payload, 1);
     });
   };
 
-  return { emit, store, subscribe, unsubscribe, ...view };
+  return {
+    emit,
+    store,
+    subscribe: wsClientMocks.subscribe,
+    unsubscribe: wsClientMocks.unsubscribe,
+    sendCommand: wsClientMocks.sendCommand,
+    wsClient: { subscribe: wsClientMocks.subscribe, sendCommand: wsClientMocks.sendCommand },
+    ...view,
+  };
 }
 
 function createEvent(intent: UiActionEvent["intent"]): UiActionEvent {
@@ -88,6 +158,10 @@ function browserTab(id: string, url: string | null): WorkspaceBrowserEditorTab {
 }
 
 describe("useUiActionSubscription", () => {
+  beforeEach(() => {
+    persistUiStateSpy.mockClear();
+  });
+
   it("skips subscription when the ws client mock does not implement subscribe", () => {
     const store = createStore();
     store.set(workspacesAtom, { "ws-1": createWorkspace("ws-1") } as never);
@@ -187,6 +261,296 @@ describe("useUiActionSubscription", () => {
     expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual(openEditorTabs[0]);
   });
 
+  it("opens and activates a canvas tab from canvas.open events", async () => {
+    const { emit, store } = setupHarness();
+
+    await emit(
+      createEvent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      })
+    );
+
+    expect(store.get(editorViewVisibleAtomFamily("ws-1"))).toBe(true);
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      {
+        kind: "canvas",
+        id: "canvas:canvas-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      },
+    ]);
+    expect(store.get(activeEditorTabAtomFamily("ws-1"))).toEqual({
+      kind: "canvas",
+      id: "canvas:canvas-1",
+      canvasId: "canvas-1",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas",
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+    });
+  });
+
+  it("persists canvas tabs opened from canvas.open events via workspace.uiState.set", async () => {
+    const { emit, sendCommand } = setupHarness();
+
+    await emit(
+      createEvent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      })
+    );
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalled();
+    });
+
+    expect(sendCommand.mock.calls[0]?.[0]).toBe("workspace.uiState.set");
+    expect(sendCommand.mock.calls[0]?.[1]).toEqual(
+      expect.objectContaining({
+        workspaceId: "ws-1",
+        uiState: expect.objectContaining({
+          editorViewVisible: true,
+          openEditorTabs: [
+            {
+              kind: "canvas",
+              id: "canvas:canvas-1",
+              canvasId: "canvas-1",
+              title: "Runtime Flow",
+              artifactType: "architecture_canvas",
+              sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+            },
+          ],
+          activeEditorTab: {
+            kind: "canvas",
+            id: "canvas:canvas-1",
+            canvasId: "canvas-1",
+            title: "Runtime Flow",
+            artifactType: "architecture_canvas",
+            sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+          },
+        }),
+      })
+    );
+  });
+
+  it("persists mixed tabs while replacing an existing canvas tab with the same canvasId", async () => {
+    const { emit, sendCommand, store } = setupHarness();
+    const existingBrowserTab = browserTab("browser-1", "http://127.0.0.1:5173/");
+    const replacedCanvasTab = {
+      kind: "canvas" as const,
+      id: "canvas:canvas-1",
+      canvasId: "canvas-1",
+      title: "Old Runtime Flow",
+      artifactType: "architecture_canvas" as const,
+      sourcePath: ".coder-studio/canvases/canvas-1-old.canvas.json",
+    };
+    const expectedCanvasTab = {
+      kind: "canvas" as const,
+      id: "canvas:canvas-1",
+      canvasId: "canvas-1",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas" as const,
+      sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+    };
+    const expectedTabs = [
+      { kind: "file" as const, path: "src/index.ts" },
+      existingBrowserTab,
+      expectedCanvasTab,
+    ];
+
+    store.set(editorViewVisibleAtomFamily("ws-1"), false);
+    store.set(openEditorPathsAtomFamily("ws-1"), ["src/index.ts"]);
+    store.set(openEditorTabsAtomFamily("ws-1"), [
+      { kind: "file", path: "src/index.ts" },
+      existingBrowserTab,
+      replacedCanvasTab,
+    ]);
+    store.set(activeFilePathAtomFamily("ws-1"), "src/index.ts");
+    store.set(activeEditorTabAtomFamily("ws-1"), existingBrowserTab);
+
+    await emit(
+      createEvent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/canvas-1.canvas.json",
+      })
+    );
+
+    expect(persistUiStateSpy).toHaveBeenCalledWith({
+      editorViewVisible: true,
+      openEditorTabs: expectedTabs,
+      activeEditorTab: expectedCanvasTab,
+    });
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalled();
+    });
+
+    expect(sendCommand.mock.calls[0]?.[0]).toBe("workspace.uiState.set");
+    expect(sendCommand.mock.calls[0]?.[1]).toEqual(
+      expect.objectContaining({
+        workspaceId: "ws-1",
+        uiState: expect.objectContaining({
+          editorViewVisible: true,
+          openEditorTabs: expectedTabs,
+          activeEditorTab: expectedCanvasTab,
+        }),
+      })
+    );
+  });
+
+  it("reuses a source-path-first canvas tab when a later canvas.open event resolves a canvasId", async () => {
+    const { emit, store } = setupHarness();
+    const existingCanvasTab = {
+      kind: "canvas" as const,
+      id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas" as const,
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    };
+
+    store.set(openEditorTabsAtomFamily("ws-1"), [existingCanvasTab]);
+    store.set(activeEditorTabAtomFamily("ws-1"), existingCanvasTab);
+
+    await emit(
+      createEvent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      })
+    );
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      {
+        kind: "canvas",
+        id: "canvas:canvas-1",
+        canvasId: "canvas-1",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      },
+    ]);
+  });
+
+  it("matches source-path-first canvas tabs by sourcePath when canvasId is absent", async () => {
+    const { emit, store } = setupHarness();
+    const runtimeFlowTab = {
+      kind: "canvas" as const,
+      id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+      title: "Runtime Flow",
+      artifactType: "architecture_canvas" as const,
+      sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+    };
+    const auditTab = {
+      kind: "canvas" as const,
+      id: "canvas:.coder-studio/canvases/audit.csc",
+      title: "Old Audit",
+      artifactType: "report_canvas" as const,
+      sourcePath: ".coder-studio/canvases/audit.csc",
+    };
+
+    store.set(openEditorTabsAtomFamily("ws-1"), [runtimeFlowTab, auditTab]);
+    store.set(activeEditorTabAtomFamily("ws-1"), runtimeFlowTab);
+
+    await emit(
+      createEvent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        title: "Audit",
+        artifactType: "report_canvas",
+        sourcePath: ".coder-studio/canvases/audit.csc",
+      })
+    );
+
+    expect(store.get(openEditorTabsAtomFamily("ws-1"))).toEqual([
+      runtimeFlowTab,
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/audit.csc",
+        title: "Audit",
+        artifactType: "report_canvas",
+        sourcePath: ".coder-studio/canvases/audit.csc",
+      },
+    ]);
+  });
+
+  it("persists canvas tabs after ws client becomes available post-mount", async () => {
+    const { emit, store, sendCommand, subscribe, wsClient } = setupHarness({
+      initialWsClient: null,
+    });
+
+    expect(subscribe).not.toHaveBeenCalled();
+
+    act(() => {
+      store.set(wsClientAtom, wsClient as never);
+    });
+
+    await waitFor(() => {
+      expect(subscribe).toHaveBeenCalledWith(
+        [Topics.workspaceUiAction("ws-1")],
+        expect.any(Function)
+      );
+    });
+
+    await emit(
+      createEvent({
+        type: "canvas.open",
+        workspaceId: "ws-1",
+        canvasId: "canvas-late",
+        title: "Late Client Canvas",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/canvas-late.canvas.json",
+      })
+    );
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalled();
+    });
+
+    expect(sendCommand.mock.calls[0]?.[0]).toBe("workspace.uiState.set");
+    expect(sendCommand.mock.calls[0]?.[1]).toEqual(
+      expect.objectContaining({
+        workspaceId: "ws-1",
+        uiState: expect.objectContaining({
+          openEditorTabs: [
+            {
+              kind: "canvas",
+              id: "canvas:canvas-late",
+              canvasId: "canvas-late",
+              title: "Late Client Canvas",
+              artifactType: "architecture_canvas",
+              sourcePath: ".coder-studio/canvases/canvas-late.canvas.json",
+            },
+          ],
+          activeEditorTab: {
+            kind: "canvas",
+            id: "canvas:canvas-late",
+            canvasId: "canvas-late",
+            title: "Late Client Canvas",
+            artifactType: "architecture_canvas",
+            sourcePath: ".coder-studio/canvases/canvas-late.canvas.json",
+          },
+        }),
+      })
+    );
+  });
+
   it("closes a matching file tab from editor.closeFile events", async () => {
     const { emit, store } = setupHarness();
     store.set(editorViewVisibleAtomFamily("ws-1"), true);
diff --git a/packages/web/src/features/ui-actions/use-ui-action-subscription.ts b/packages/web/src/features/ui-actions/use-ui-action-subscription.ts
index 5769a2649..3dd4447f7 100644
--- a/packages/web/src/features/ui-actions/use-ui-action-subscription.ts
+++ b/packages/web/src/features/ui-actions/use-ui-action-subscription.ts
@@ -10,10 +10,12 @@ import {
 import { pushToastAtom } from "../notifications/atoms";
 import { useOpenWorkspaceFile } from "../workspace/actions/use-open-workspace-file";
 import { useSelectWorkspaceTarget } from "../workspace/actions/use-select-workspace-target";
+import { useWorkspaceUiStatePersistence } from "../workspace/actions/use-workspace-ui-state-persistence";
 import {
   activeEditorTabAtomFamily,
   activeFilePathAtomFamily,
   createWorkspaceBrowserEditorTab,
+  createWorkspaceCanvasEditorTab,
   editorViewVisibleAtomFamily,
   openEditorPathsAtomFamily,
   openEditorTabsAtomFamily,
@@ -57,6 +59,7 @@ export function useUiActionSubscription(workspaceId: string): void {
   const store = useStore();
   const selectWorkspaceTarget = useSelectWorkspaceTarget();
   const { openWorkspaceFile } = useOpenWorkspaceFile(workspaceId);
+  const { persistUiState } = useWorkspaceUiStatePersistence(workspaceId);
 
   const registry = useMemo(() => {
     const nextRegistry = createUiActionRegistry();
@@ -106,7 +109,10 @@ export function useUiActionSubscription(workspaceId: string): void {
           .map((tab) => tab.path),
         ...(currentActivePath && currentActivePath !== targetPath ? [currentActivePath] : []),
       ].filter((path, index, paths) => paths.indexOf(path) === index);
-      const browserTab = nextTabs.find((tab) => tab.kind === "browser") ?? null;
+      const fallbackNonFileTab =
+        nextTabs.find((tab): tab is Exclude<WorkspaceEditorTab, { kind: "file" }> => {
+          return tab.kind === "browser" || tab.kind === "canvas";
+        }) ?? null;
       const nextActiveFilePath =
         currentActivePath === targetPath ? (remainingFilePaths[0] ?? null) : currentActivePath;
       const shouldReplaceActiveTab =
@@ -114,14 +120,14 @@ export function useUiActionSubscription(workspaceId: string): void {
       const nextActiveTab: WorkspaceEditorTab | null = shouldReplaceActiveTab
         ? remainingFilePaths[0]
           ? { kind: "file", path: remainingFilePaths[0] }
-          : browserTab
+          : fallbackNonFileTab
         : currentActiveTab;
 
       setOpenEditorPaths(nextOpenPaths);
       setOpenEditorTabs(nextTabs);
       setActiveFilePath(nextActiveFilePath);
       setActiveEditorTab(nextActiveTab);
-      setEditorViewVisible(remainingFilePaths.length > 0 || browserTab !== null);
+      setEditorViewVisible(remainingFilePaths.length > 0 || fallbackNonFileTab !== null);
     });
 
     nextRegistry.register("browser.openUrl", (event) => {
@@ -136,6 +142,46 @@ export function useUiActionSubscription(workspaceId: string): void {
       setActiveEditorTab(nextBrowserTab);
     });
 
+    nextRegistry.register("canvas.open", (event) => {
+      if (event.intent.type !== "canvas.open") {
+        return;
+      }
+
+      const nextCanvasTab: WorkspaceEditorTab = createWorkspaceCanvasEditorTab({
+        sourcePath: event.intent.sourcePath,
+        title: event.intent.title,
+        artifactType: event.intent.artifactType,
+        ...(event.intent.canvasId
+          ? {
+              canvasId: event.intent.canvasId,
+              id: `canvas:${event.intent.canvasId}`,
+            }
+          : {}),
+      });
+
+      const currentTabs = store.get(openEditorTabsAtomFamily(workspaceId));
+      const existingIndex = currentTabs.findIndex(
+        (tab) =>
+          tab.kind === "canvas" &&
+          (tab.sourcePath === nextCanvasTab.sourcePath ||
+            (nextCanvasTab.canvasId !== undefined && tab.canvasId === nextCanvasTab.canvasId))
+      );
+      const nextTabs =
+        existingIndex === -1
+          ? [...currentTabs, nextCanvasTab]
+          : currentTabs.map((tab, index) => (index === existingIndex ? nextCanvasTab : tab));
+      const nextEditorState = {
+        editorViewVisible: true,
+        openEditorTabs: nextTabs,
+        activeEditorTab: nextCanvasTab,
+      };
+
+      setEditorViewVisible(nextEditorState.editorViewVisible);
+      setOpenEditorTabs(nextEditorState.openEditorTabs);
+      setActiveEditorTab(nextEditorState.activeEditorTab);
+      void persistUiState(nextEditorState);
+    });
+
     nextRegistry.register("browser.closeUrl", (event) => {
       if (event.intent.type !== "browser.closeUrl") {
         return;
@@ -170,10 +216,14 @@ export function useUiActionSubscription(workspaceId: string): void {
       const nextBrowserTabs = nextTabs.filter(
         (tab): tab is Extract<WorkspaceEditorTab, { kind: "browser" }> => tab.kind === "browser"
       );
+      const nextCanvasTabs = nextTabs.filter(
+        (tab): tab is Extract<WorkspaceEditorTab, { kind: "canvas" }> => tab.kind === "canvas"
+      );
       const fallbackFilePath = currentActivePath ?? currentOpenPaths[0] ?? null;
       const nextActiveTab =
         nextBrowserTabs[closedBrowserIndex] ??
         nextBrowserTabs[closedBrowserIndex - 1] ??
+        nextCanvasTabs[0] ??
         (fallbackFilePath ? ({ kind: "file", path: fallbackFilePath } as const) : null);
 
       setPendingDevBrowserUrl((current) => (current === targetUrl ? null : current));
@@ -234,6 +284,7 @@ export function useUiActionSubscription(workspaceId: string): void {
     return nextRegistry;
   }, [
     openWorkspaceFile,
+    persistUiState,
     selectWorkspaceTarget,
     setActiveEditorTab,
     setActiveFilePath,
diff --git a/packages/web/src/features/workspace/actions/open-editor-state.test.ts b/packages/web/src/features/workspace/actions/open-editor-state.test.ts
index 74939196b..62fd21799 100644
--- a/packages/web/src/features/workspace/actions/open-editor-state.test.ts
+++ b/packages/web/src/features/workspace/actions/open-editor-state.test.ts
@@ -5,6 +5,46 @@ import {
 } from "./open-editor-state";
 
 describe("open editor state browser tab normalization", () => {
+  it("normalizes legacy file editor tabs as pinned", () => {
+    expect(
+      normalizeWorkspaceEditorUiStatePatch({
+        openEditorTabs: [{ kind: "file", path: "src/app.ts" }],
+        activeEditorTab: { kind: "file", path: "src/app.ts" },
+      })
+    ).toEqual({
+      openEditorTabs: [{ kind: "file", path: "src/app.ts", pinned: true }],
+      activeEditorTab: { kind: "file", path: "src/app.ts", pinned: true },
+    });
+  });
+
+  it("preserves preview file editor tabs", () => {
+    expect(
+      normalizeWorkspaceEditorUiStatePatch({
+        openEditorTabs: [{ kind: "file", path: "src/preview.ts", pinned: false }],
+        activeEditorTab: { kind: "file", path: "src/preview.ts", pinned: false },
+      })
+    ).toEqual({
+      openEditorTabs: [{ kind: "file", path: "src/preview.ts", pinned: false }],
+      activeEditorTab: { kind: "file", path: "src/preview.ts", pinned: false },
+    });
+  });
+
+  it("does not add an active preview file to persistent open editor paths", () => {
+    expect(
+      normalizeWorkspaceEditorUiStatePatch({
+        openEditorPaths: ["src/pinned.ts"],
+        activeEditorPath: "src/preview.ts",
+        openEditorTabs: [{ kind: "file", path: "src/preview.ts", pinned: false }],
+        activeEditorTab: { kind: "file", path: "src/preview.ts", pinned: false },
+      })
+    ).toEqual({
+      openEditorPaths: ["src/pinned.ts"],
+      activeEditorPath: "src/preview.ts",
+      openEditorTabs: [{ kind: "file", path: "src/preview.ts", pinned: false }],
+      activeEditorTab: { kind: "file", path: "src/preview.ts", pinned: false },
+    });
+  });
+
   it("preserves device settings when migrating a legacy dev browser tab", () => {
     expect(
       normalizeWorkspaceEditorUiStatePatch({
@@ -80,4 +120,49 @@ describe("open editor state browser tab normalization", () => {
       userAgentMode: "mobile",
     });
   });
+
+  it("preserves sourcePath-first canvas tabs and appends an active canvas tab when it is missing from open tabs", () => {
+    expect(
+      normalizeWorkspaceEditorUiStatePatch({
+        openEditorTabs: [
+          {
+            kind: "canvas",
+            id: "canvas:.coder-studio/canvases/report.csc",
+            title: "Report",
+            sourcePath: " .coder-studio/canvases/report.csc ",
+          },
+        ],
+        activeEditorTab: {
+          kind: "canvas",
+          id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+          title: "Runtime Flow",
+          artifactType: "architecture_canvas",
+          sourcePath: " .coder-studio/canvases/runtime-flow.csc ",
+        },
+      })
+    ).toEqual({
+      openEditorTabs: [
+        {
+          kind: "canvas",
+          id: "canvas:.coder-studio/canvases/report.csc",
+          title: "Report",
+          sourcePath: ".coder-studio/canvases/report.csc",
+        },
+        {
+          kind: "canvas",
+          id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+          title: "Runtime Flow",
+          artifactType: "architecture_canvas",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+        },
+      ],
+      activeEditorTab: {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+        title: "Runtime Flow",
+        artifactType: "architecture_canvas",
+        sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+      },
+    });
+  });
 });
diff --git a/packages/web/src/features/workspace/actions/open-editor-state.ts b/packages/web/src/features/workspace/actions/open-editor-state.ts
index c10804f12..e7b806dfc 100644
--- a/packages/web/src/features/workspace/actions/open-editor-state.ts
+++ b/packages/web/src/features/workspace/actions/open-editor-state.ts
@@ -3,10 +3,12 @@ import type { Store } from "jotai/vanilla/store";
 import {
   activeEditorTabAtomFamily,
   activeFilePathAtomFamily,
+  createWorkspaceCanvasEditorTab,
   editorViewVisibleAtomFamily,
   openEditorPathsAtomFamily,
   openEditorTabsAtomFamily,
   type WorkspaceBrowserEditorTab,
+  type WorkspaceCanvasEditorTab,
   type WorkspaceEditorTab,
   type WorkspaceFileEditorTab,
 } from "../atoms";
@@ -111,15 +113,53 @@ function normalizeWorkspaceFileEditorTab(entry: unknown): WorkspaceFileEditorTab
   return {
     kind: "file",
     path: candidate.path.trim(),
+    pinned: typeof candidate.pinned === "boolean" ? candidate.pinned : true,
   };
 }
 
+function normalizeWorkspaceCanvasEditorTab(entry: unknown): WorkspaceCanvasEditorTab | null {
+  if (!entry || typeof entry !== "object") {
+    return null;
+  }
+
+  const candidate = entry as Partial<WorkspaceCanvasEditorTab>;
+  if (candidate.kind !== "canvas") {
+    return null;
+  }
+
+  if (typeof candidate.sourcePath !== "string" || candidate.sourcePath.trim().length === 0) {
+    return null;
+  }
+
+  if (typeof candidate.title !== "string" || candidate.title.trim().length === 0) {
+    return null;
+  }
+
+  if (
+    candidate.artifactType !== undefined &&
+    candidate.artifactType !== "architecture_canvas" &&
+    candidate.artifactType !== "report_canvas"
+  ) {
+    return null;
+  }
+
+  return createWorkspaceCanvasEditorTab({
+    id: typeof candidate.id === "string" ? candidate.id : undefined,
+    title: candidate.title,
+    artifactType: candidate.artifactType,
+    sourcePath: candidate.sourcePath,
+    canvasId: typeof candidate.canvasId === "string" ? candidate.canvasId : undefined,
+  });
+}
+
 function normalizeWorkspaceEditorTab(
   entry: unknown,
   legacyUrl: string | null
 ): WorkspaceEditorTab | null {
   return (
-    normalizeWorkspaceBrowserEditorTab(entry, legacyUrl) ?? normalizeWorkspaceFileEditorTab(entry)
+    normalizeWorkspaceBrowserEditorTab(entry, legacyUrl) ??
+    normalizeWorkspaceCanvasEditorTab(entry) ??
+    normalizeWorkspaceFileEditorTab(entry)
   );
 }
 
@@ -133,6 +173,7 @@ function normalizeWorkspaceEditorTabs(
 
   const seenFilePaths = new Set<string>();
   const seenBrowserIds = new Set<string>();
+  const seenCanvasSourcePaths = new Set<string>();
   const next: WorkspaceEditorTab[] = [];
 
   for (const entry of value) {
@@ -151,6 +192,16 @@ function normalizeWorkspaceEditorTabs(
       continue;
     }
 
+    if (normalizedTab.kind === "canvas") {
+      if (seenCanvasSourcePaths.has(normalizedTab.sourcePath)) {
+        continue;
+      }
+
+      seenCanvasSourcePaths.add(normalizedTab.sourcePath);
+      next.push(normalizedTab);
+      continue;
+    }
+
     if (seenFilePaths.has(normalizedTab.path)) {
       continue;
     }
@@ -162,19 +213,35 @@ function normalizeWorkspaceEditorTabs(
   return next;
 }
 
-function appendMissingActiveBrowserTab(
+function appendMissingActiveNonFileTab(
   openEditorTabs: WorkspaceEditorTab[],
   activeEditorTab: WorkspaceEditorTab | null
 ): WorkspaceEditorTab[] {
-  if (activeEditorTab?.kind !== "browser") {
-    return openEditorTabs;
+  if (activeEditorTab?.kind === "browser") {
+    if (openEditorTabs.some((tab) => tab.kind === "browser" && tab.id === activeEditorTab.id)) {
+      return openEditorTabs;
+    }
+
+    return [...openEditorTabs, activeEditorTab];
+  }
+
+  if (activeEditorTab?.kind === "canvas") {
+    if (
+      openEditorTabs.some(
+        (tab) => tab.kind === "canvas" && tab.sourcePath === activeEditorTab.sourcePath
+      )
+    ) {
+      return openEditorTabs;
+    }
+
+    return [...openEditorTabs, activeEditorTab];
   }
 
-  if (openEditorTabs.some((tab) => tab.kind === "browser" && tab.id === activeEditorTab.id)) {
+  if (activeEditorTab?.kind !== "browser") {
     return openEditorTabs;
   }
 
-  return [...openEditorTabs, activeEditorTab];
+  return openEditorTabs;
 }
 
 function hasOwnProperty<T extends object>(value: T, key: PropertyKey): boolean {
@@ -280,6 +347,9 @@ export function normalizeWorkspaceEditorUiStatePatch(
   const hasOpenEditorTabs = hasOwnProperty(uiState, "openEditorTabs");
   const hasActiveEditorTab = hasOwnProperty(uiState, "activeEditorTab");
   const legacyBrowserTargetUrl = readLegacyDevBrowserTargetUrl(uiState);
+  const normalizedActiveEditorTab = hasActiveEditorTab
+    ? normalizeWorkspaceEditorTab(uiState.activeEditorTab, legacyBrowserTargetUrl)
+    : null;
 
   if (
     !hasOpenEditorPaths &&
@@ -307,7 +377,15 @@ export function normalizeWorkspaceEditorUiStatePatch(
       const activeEditorPath = normalizeActiveEditorPath(uiState.activeEditorPath);
       next.activeEditorPath = activeEditorPath;
 
-      if (activeEditorPath && !openEditorPaths.includes(activeEditorPath)) {
+      const isActivePreviewFileTab =
+        normalizedActiveEditorTab?.kind === "file" &&
+        normalizedActiveEditorTab.path === activeEditorPath &&
+        normalizedActiveEditorTab.pinned === false;
+      if (
+        activeEditorPath &&
+        !openEditorPaths.includes(activeEditorPath) &&
+        !isActivePreviewFileTab
+      ) {
         next.openEditorPaths = [...openEditorPaths, activeEditorPath];
       }
     }
@@ -327,23 +405,17 @@ export function normalizeWorkspaceEditorUiStatePatch(
     next.openEditorTabs = openEditorTabs;
 
     if (hasActiveEditorTab) {
-      const activeEditorTab = normalizeWorkspaceEditorTab(
-        uiState.activeEditorTab,
-        legacyBrowserTargetUrl
-      );
+      const activeEditorTab = normalizedActiveEditorTab;
       next.activeEditorTab = activeEditorTab;
-      if (activeEditorTab?.kind === "browser") {
-        next.openEditorTabs = appendMissingActiveBrowserTab(openEditorTabs, activeEditorTab);
+      if (activeEditorTab?.kind === "browser" || activeEditorTab?.kind === "canvas") {
+        next.openEditorTabs = appendMissingActiveNonFileTab(openEditorTabs, activeEditorTab);
       }
     }
   } else if (hasActiveEditorTab) {
-    const activeEditorTab = normalizeWorkspaceEditorTab(
-      uiState.activeEditorTab,
-      legacyBrowserTargetUrl
-    );
+    const activeEditorTab = normalizedActiveEditorTab;
     next.activeEditorTab = activeEditorTab;
-    if (activeEditorTab?.kind === "browser") {
-      next.openEditorTabs = appendMissingActiveBrowserTab([], activeEditorTab);
+    if (activeEditorTab?.kind === "browser" || activeEditorTab?.kind === "canvas") {
+      next.openEditorTabs = appendMissingActiveNonFileTab([], activeEditorTab);
     }
   }
 
diff --git a/packages/web/src/features/workspace/actions/use-file-actions.test.tsx b/packages/web/src/features/workspace/actions/use-file-actions.test.tsx
index 949e12d7b..3301cc4e9 100644
--- a/packages/web/src/features/workspace/actions/use-file-actions.test.tsx
+++ b/packages/web/src/features/workspace/actions/use-file-actions.test.tsx
@@ -14,11 +14,13 @@ import {
 import { paneLayoutAtomFamily } from "../../agent-panes/atoms/pane-layout";
 import { pendingEditorNavigationAtomFamily } from "../../code-editor/atoms";
 import {
+  activeEditorTabAtomFamily,
   activeFilePathAtomFamily,
   expandedDirsAtomFamily,
   fileTreeAtomFamily,
   loadedDirsAtomFamily,
   openEditorPathsAtomFamily,
+  openEditorTabsAtomFamily,
   openFilesAtomFamily,
 } from "../atoms";
 import { useFileActions } from "./use-file-actions";
@@ -399,6 +401,41 @@ describe("useFileActions rename behavior", () => {
     expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe("src/standalone.ts");
   });
 
+  it("opens .csc explorer files as canvas tabs", async () => {
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand: vi.fn() } as never);
+    store.set(fileTreeAtomFamily("ws-test"), new Map([[".", []]]));
+
+    const { result } = renderHook(() => useFileActions({ workspaceId: "ws-test" }), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      result.current.handleSelectFile(".coder-studio/canvases/auth-gate.csc");
+      await Promise.resolve();
+    });
+
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBeNull();
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([]);
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/auth-gate.csc",
+        title: "auth-gate",
+        sourcePath: ".coder-studio/canvases/auth-gate.csc",
+        canvasId: ".coder-studio/canvases/auth-gate.csc",
+      },
+    ]);
+    expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual({
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/auth-gate.csc",
+      title: "auth-gate",
+      sourcePath: ".coder-studio/canvases/auth-gate.csc",
+      canvasId: ".coder-studio/canvases/auth-gate.csc",
+    });
+  });
+
   it("preserves loaded expanded descendants while refreshing the root tree", async () => {
     const sendCommand = vi
       .fn()
diff --git a/packages/web/src/features/workspace/actions/use-file-actions.ts b/packages/web/src/features/workspace/actions/use-file-actions.ts
index 02a934a15..861621b1d 100644
--- a/packages/web/src/features/workspace/actions/use-file-actions.ts
+++ b/packages/web/src/features/workspace/actions/use-file-actions.ts
@@ -711,11 +711,29 @@ export function useFileActions({
 
   const handleSelectFile = useCallback(
     (path: string) => {
-      void openWorkspaceFile({
-        workspaceId,
-        path,
-        source: "file-tree",
-      });
+      void openWorkspaceFile(
+        {
+          workspaceId,
+          path,
+          source: "file-tree",
+        },
+        { openTarget: "navigate", openDisposition: "preview" }
+      );
+      onSelectFile?.(path);
+    },
+    [onSelectFile, openWorkspaceFile, workspaceId]
+  );
+
+  const handlePinFile = useCallback(
+    (path: string) => {
+      void openWorkspaceFile(
+        {
+          workspaceId,
+          path,
+          source: "file-tree",
+        },
+        { openTarget: "navigate", openDisposition: "pinned" }
+      );
       onSelectFile?.(path);
     },
     [onSelectFile, openWorkspaceFile, workspaceId]
@@ -733,6 +751,7 @@ export function useFileActions({
     cancelDelete,
     confirmDelete,
     handleSelectFile,
+    handlePinFile,
     loadFileTree,
     loadChildren,
     loadSearchResults,
diff --git a/packages/web/src/features/workspace/actions/use-memory-panel.ts b/packages/web/src/features/workspace/actions/use-memory-panel.ts
index 7a2e970be..991085eb3 100644
--- a/packages/web/src/features/workspace/actions/use-memory-panel.ts
+++ b/packages/web/src/features/workspace/actions/use-memory-panel.ts
@@ -1,4 +1,8 @@
-import type { WorkspaceMemoryEntry, WorkspaceMemoryType } from "@coder-studio/core";
+import type {
+  WorkspaceMemoryEntry,
+  WorkspaceMemoryStatus,
+  WorkspaceMemoryType,
+} from "@coder-studio/core";
 import { useAtomValue } from "jotai";
 import { useCallback, useEffect, useState } from "react";
 import { dispatchCommandAtom, wsClientAtom } from "../../../atoms/connection";
@@ -7,6 +11,7 @@ import { workspaceTopic } from "../../../ws";
 interface MemoryCreateInput {
   content: string;
   type: WorkspaceMemoryType;
+  status?: WorkspaceMemoryStatus;
 }
 
 interface MemoryUpdateInput extends MemoryCreateInput {
diff --git a/packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx b/packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx
index 0df98135c..99db9a5bf 100644
--- a/packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx
+++ b/packages/web/src/features/workspace/actions/use-open-workspace-file.test.tsx
@@ -15,7 +15,13 @@ import {
 } from "../../agent-panes/atoms/editor-panes";
 import { paneLayoutAtomFamily } from "../../agent-panes/atoms/pane-layout";
 import { pendingEditorNavigationAtomFamily } from "../../code-editor/atoms";
-import { activeFilePathAtomFamily, openEditorPathsAtomFamily } from "../atoms";
+import {
+  activeEditorTabAtomFamily,
+  activeFilePathAtomFamily,
+  openEditorPathsAtomFamily,
+  openEditorTabsAtomFamily,
+  openFilesAtomFamily,
+} from "../atoms";
 import { useOpenWorkspaceFile } from "./use-open-workspace-file";
 
 function editorPaneStateKey(workspaceId: string, paneId: string): string {
@@ -46,6 +52,82 @@ function seedWorkspace(store: ReturnType<typeof createStore>) {
 }
 
 describe("useOpenWorkspaceFile", () => {
+  it("replaces the existing preview file tab when opening another preview file", async () => {
+    const store = createStore();
+    seedWorkspace(store);
+    store.set(openEditorTabsAtomFamily("ws-test"), [
+      { kind: "file", path: "src/a.ts", pinned: false },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-test"), {
+      kind: "file",
+      path: "src/a.ts",
+      pinned: false,
+    });
+    store.set(activeFilePathAtomFamily("ws-test"), "src/a.ts");
+
+    const { result } = renderHook(() => useOpenWorkspaceFile("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.openWorkspaceFile(
+        { workspaceId: "ws-test", path: "src/b.ts", source: "file-tree" },
+        { openTarget: "navigate", openDisposition: "preview" }
+      );
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+      { kind: "file", path: "src/b.ts", pinned: false },
+    ]);
+    expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual({
+      kind: "file",
+      path: "src/b.ts",
+      pinned: false,
+    });
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe("src/b.ts");
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([]);
+    expect(store.get(pendingEditorNavigationAtomFamily("ws-test"))).toMatchObject({
+      workspaceId: "ws-test",
+      path: "src/b.ts",
+      source: "file-tree",
+    });
+  });
+
+  it("pins the current preview tab when opening the same file as pinned", async () => {
+    const store = createStore();
+    seedWorkspace(store);
+    store.set(openEditorTabsAtomFamily("ws-test"), [
+      { kind: "file", path: "src/a.ts", pinned: false },
+    ]);
+    store.set(activeEditorTabAtomFamily("ws-test"), {
+      kind: "file",
+      path: "src/a.ts",
+      pinned: false,
+    });
+    store.set(activeFilePathAtomFamily("ws-test"), "src/a.ts");
+
+    const { result } = renderHook(() => useOpenWorkspaceFile("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.openWorkspaceFile(
+        { workspaceId: "ws-test", path: "src/a.ts", source: "file-tree" },
+        { openTarget: "navigate", openDisposition: "pinned" }
+      );
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+      { kind: "file", path: "src/a.ts", pinned: true },
+    ]);
+    expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual({
+      kind: "file",
+      path: "src/a.ts",
+      pinned: true,
+    });
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual(["src/a.ts"]);
+  });
+
   it("opens regular files in the standalone editor without clearing the focused editor pane", async () => {
     const store = createStore();
     seedWorkspace(store);
@@ -343,4 +425,96 @@ describe("useOpenWorkspaceFile", () => {
       undefined
     );
   });
+
+  it("opens .csc files as canvas tabs for navigation-style opens", async () => {
+    const sendCommand = vi.fn().mockResolvedValue({
+      id: "ws-test",
+      path: "/workspace",
+      targetRuntime: "native",
+      openedAt: 1,
+      lastActiveAt: 1,
+      uiState: {
+        leftPanelWidth: 280,
+        bottomPanelHeight: 200,
+        focusMode: false,
+      },
+    });
+
+    const store = createStore();
+    seedWorkspace(store);
+    store.set(wsClientAtom, { sendCommand } as never);
+    store.set(openFilesAtomFamily("ws-test"), {
+      ".coder-studio/canvases/auth-gate.csc": {
+        kind: "text",
+        path: ".coder-studio/canvases/auth-gate.csc",
+        content: '{"kind":"architecture_canvas"}',
+        savedContent: '{"kind":"architecture_canvas"}',
+        baseHash: "canvas-hash",
+        isDirty: false,
+      },
+    });
+
+    const { result } = renderHook(() => useOpenWorkspaceFile("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.openWorkspaceFile(
+        {
+          workspaceId: "ws-test",
+          path: ".coder-studio/canvases/auth-gate.csc",
+          source: "manual",
+        },
+        { openTarget: "navigate" }
+      );
+    });
+
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBeNull();
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([]);
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+      {
+        kind: "canvas",
+        id: "canvas:.coder-studio/canvases/auth-gate.csc",
+        title: "auth-gate",
+        sourcePath: ".coder-studio/canvases/auth-gate.csc",
+        artifactType: "architecture_canvas",
+        canvasId: ".coder-studio/canvases/auth-gate.csc",
+      },
+    ]);
+    expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual({
+      kind: "canvas",
+      id: "canvas:.coder-studio/canvases/auth-gate.csc",
+      title: "auth-gate",
+      sourcePath: ".coder-studio/canvases/auth-gate.csc",
+      artifactType: "architecture_canvas",
+      canvasId: ".coder-studio/canvases/auth-gate.csc",
+    });
+    expect(sendCommand).toHaveBeenCalledWith(
+      "workspace.uiState.set",
+      expect.objectContaining({
+        workspaceId: "ws-test",
+        uiState: expect.objectContaining({
+          openEditorTabs: [
+            {
+              kind: "canvas",
+              id: "canvas:.coder-studio/canvases/auth-gate.csc",
+              title: "auth-gate",
+              sourcePath: ".coder-studio/canvases/auth-gate.csc",
+              artifactType: "architecture_canvas",
+              canvasId: ".coder-studio/canvases/auth-gate.csc",
+            },
+          ],
+          activeEditorTab: {
+            kind: "canvas",
+            id: "canvas:.coder-studio/canvases/auth-gate.csc",
+            title: "auth-gate",
+            sourcePath: ".coder-studio/canvases/auth-gate.csc",
+            artifactType: "architecture_canvas",
+            canvasId: ".coder-studio/canvases/auth-gate.csc",
+          },
+        }),
+      }),
+      undefined
+    );
+  });
 });
diff --git a/packages/web/src/features/workspace/actions/use-open-workspace-file.ts b/packages/web/src/features/workspace/actions/use-open-workspace-file.ts
index 6bc0bf022..939ce56c2 100644
--- a/packages/web/src/features/workspace/actions/use-open-workspace-file.ts
+++ b/packages/web/src/features/workspace/actions/use-open-workspace-file.ts
@@ -17,21 +17,60 @@ import {
 } from "../../agent-panes/pane-layout-tree";
 import { useOpenLocation } from "../../code-editor/actions/use-open-location";
 import { type PendingEditorNavigation } from "../../code-editor/atoms";
-import { deriveEditorModeForPath, editorModeAtomFamily, openEditorPathsAtomFamily } from "../atoms";
+import {
+  activeEditorTabAtomFamily,
+  createWorkspaceCanvasEditorTabFromSourcePath,
+  deriveEditorModeForPath,
+  editorModeAtomFamily,
+  editorViewVisibleAtomFamily,
+  isCanvasSourcePath,
+  openEditorPathsAtomFamily,
+  openEditorTabsAtomFamily,
+  openFilesAtomFamily,
+} from "../atoms";
 import { appendOpenEditorPath } from "./open-editor-state";
 import { useWorkspaceUiStatePersistence } from "./use-workspace-ui-state-persistence";
 
 interface OpenWorkspaceFileOptions {
   targetDraftPaneId?: string;
+  openTarget?: "source" | "navigate";
+  openDisposition?: "preview" | "pinned" | "preserve";
+}
+
+function resolveOpenWorkspaceTarget(
+  input: PendingEditorNavigation,
+  options: OpenWorkspaceFileOptions
+): "source" | "canvas" {
+  if (options.openTarget !== "navigate") {
+    return "source";
+  }
+
+  if (options.targetDraftPaneId) {
+    return "source";
+  }
+
+  if (
+    input.line !== undefined ||
+    input.column !== undefined ||
+    input.endLine !== undefined ||
+    input.endColumn !== undefined
+  ) {
+    return "source";
+  }
+
+  return isCanvasSourcePath(input.path) ? "canvas" : "source";
 }
 
 export function useOpenWorkspaceFile(workspaceId: string) {
   const paneLayout = useAtomValue(paneLayoutAtomFamily(workspaceId));
   const activeEditorPaneId = useAtomValue(activeEditorPaneIdAtomFamily(workspaceId));
   const setActiveEditorPaneId = useSetAtom(activeEditorPaneIdAtomFamily(workspaceId));
+  const setActiveEditorTab = useSetAtom(activeEditorTabAtomFamily(workspaceId));
   const setFocusedEditorPaneId = useSetAtom(focusedEditorPaneIdAtomFamily(workspaceId));
   const setEditorMode = useSetAtom(editorModeAtomFamily(workspaceId));
+  const setEditorViewVisible = useSetAtom(editorViewVisibleAtomFamily(workspaceId));
   const setOpenEditorPaths = useSetAtom(openEditorPathsAtomFamily(workspaceId));
+  const setOpenEditorTabs = useSetAtom(openEditorTabsAtomFamily(workspaceId));
   const store = useStore();
   const { openLocation } = useOpenLocation(workspaceId);
   const { convertDraftPane } = usePaneActions(workspaceId);
@@ -40,9 +79,10 @@ export function useOpenWorkspaceFile(workspaceId: string) {
 
   const openWorkspaceFile = useCallback(
     async (input: PendingEditorNavigation, options: OpenWorkspaceFileOptions = {}) => {
+      const resolvedOpenTarget = resolveOpenWorkspaceTarget(input, options);
       let targetEditorPaneId: string | null = null;
 
-      if (options.targetDraftPaneId) {
+      if (resolvedOpenTarget === "source" && options.targetDraftPaneId) {
         if (paneLayoutHasDraftPaneId(paneLayout, options.targetDraftPaneId)) {
           convertDraftPane(options.targetDraftPaneId);
           targetEditorPaneId = options.targetDraftPaneId;
@@ -77,15 +117,67 @@ export function useOpenWorkspaceFile(workspaceId: string) {
         setActiveEditorPaneId(null);
       }
 
+      if (resolvedOpenTarget === "canvas") {
+        const currentOpenEditorTabs = store.get(openEditorTabsAtomFamily(workspaceId));
+        const openFiles = store.get(openFilesAtomFamily(workspaceId));
+        const existingCanvasTab = currentOpenEditorTabs.find(
+          (tab) => tab.kind === "canvas" && tab.sourcePath === input.path
+        );
+        const nextCanvasTab = createWorkspaceCanvasEditorTabFromSourcePath({
+          sourcePath: input.path,
+          file: openFiles[input.path],
+          existingTab: existingCanvasTab,
+        });
+        const nextOpenEditorTabs = existingCanvasTab
+          ? currentOpenEditorTabs.map((tab) => (tab === existingCanvasTab ? nextCanvasTab : tab))
+          : [...currentOpenEditorTabs, nextCanvasTab];
+
+        setEditorViewVisible(true);
+        setOpenEditorTabs(nextOpenEditorTabs);
+        setActiveEditorTab(nextCanvasTab);
+        void persistUiState({
+          editorViewVisible: true,
+          openEditorTabs: nextOpenEditorTabs,
+          activeEditorTab: nextCanvasTab,
+        });
+        return;
+      }
+
       setEditorMode(deriveEditorModeForPath(input.path));
       await openLocation(input);
-      const nextOpenEditorPaths = appendOpenEditorPath(
-        store.get(openEditorPathsAtomFamily(workspaceId)),
-        input.path
+      const openDisposition = options.openDisposition ?? "pinned";
+      const currentOpenEditorTabs = store.get(openEditorTabsAtomFamily(workspaceId));
+      const existingFileTab = currentOpenEditorTabs.find(
+        (tab) => tab.kind === "file" && tab.path === input.path
+      );
+      const existingPreviewTab = currentOpenEditorTabs.find(
+        (tab) => tab.kind === "file" && tab.pinned === false
       );
+      const shouldPinFileTab =
+        openDisposition === "pinned" ||
+        openDisposition === "preserve" ||
+        (openDisposition === "preview" && existingFileTab?.pinned === true);
+      const nextFileTab = {
+        kind: "file" as const,
+        path: input.path,
+        pinned: shouldPinFileTab,
+      };
+      const nextOpenEditorTabs = existingFileTab
+        ? currentOpenEditorTabs.map((tab) => (tab === existingFileTab ? nextFileTab : tab))
+        : openDisposition === "preview" && existingPreviewTab
+          ? currentOpenEditorTabs.map((tab) => (tab === existingPreviewTab ? nextFileTab : tab))
+          : [...currentOpenEditorTabs, nextFileTab];
+      const currentOpenEditorPaths = store.get(openEditorPathsAtomFamily(workspaceId));
+      const nextOpenEditorPaths = shouldPinFileTab
+        ? appendOpenEditorPath(currentOpenEditorPaths, input.path)
+        : currentOpenEditorPaths;
       setOpenEditorPaths(nextOpenEditorPaths);
+      setOpenEditorTabs(nextOpenEditorTabs);
+      setActiveEditorTab(nextFileTab);
       void persistUiState({
         openEditorPaths: nextOpenEditorPaths,
+        openEditorTabs: nextOpenEditorTabs,
+        activeEditorTab: nextFileTab,
         activeEditorPath: input.path,
       });
     },
@@ -96,9 +188,12 @@ export function useOpenWorkspaceFile(workspaceId: string) {
       paneLayout,
       persistUiState,
       setActiveEditorPaneId,
+      setActiveEditorTab,
       setEditorMode,
+      setEditorViewVisible,
       setFocusedEditorPaneId,
       setOpenEditorPaths,
+      setOpenEditorTabs,
       store,
       workspaceId,
     ]
diff --git a/packages/web/src/features/workspace/actions/use-skill-file-actions.test.tsx b/packages/web/src/features/workspace/actions/use-skill-file-actions.test.tsx
new file mode 100644
index 000000000..d123facbd
--- /dev/null
+++ b/packages/web/src/features/workspace/actions/use-skill-file-actions.test.tsx
@@ -0,0 +1,407 @@
+// @vitest-environment jsdom
+
+import { act, renderHook } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { localeAtom } from "../../../atoms/app-ui";
+import { wsClientAtom } from "../../../atoms/connection";
+import { workspacesAtom } from "../../../atoms/workspaces";
+import { pendingEditorNavigationAtomFamily } from "../../code-editor/atoms";
+import { toSkillEditorPath } from "../../code-editor/skill-editor-path";
+import { activeFilePathAtomFamily, openEditorPathsAtomFamily, openFilesAtomFamily } from "../atoms";
+import { useSkillFileActions } from "./use-skill-file-actions";
+
+function wrapperFor(store: ReturnType<typeof createStore>) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <Provider store={store}>{children}</Provider>;
+  };
+}
+
+function seedWorkspace(store: ReturnType<typeof createStore>) {
+  store.set(workspacesAtom, {
+    "ws-test": {
+      id: "ws-test",
+      path: "/workspace",
+      targetRuntime: "native",
+      openedAt: 1,
+      lastActiveAt: 1,
+      uiState: {
+        leftPanelWidth: 280,
+        bottomPanelHeight: 200,
+        focusMode: false,
+      },
+    },
+  } as never);
+}
+
+function createSendCommand(store: ReturnType<typeof createStore>) {
+  return vi.fn(
+    async (op: string, args?: { workspaceId?: string; uiState?: Record<string, unknown> }) => {
+      if (op === "skills.files.readTree") {
+        const path = (args as { path?: string } | undefined)?.path;
+        if (path === "refs") {
+          return {
+            path: "refs",
+            children: [
+              {
+                name: "guide.md",
+                path: "refs/guide.md",
+                kind: "file",
+                size: 12,
+                mtime: 2,
+              },
+            ],
+          };
+        }
+
+        return {
+          path: ".",
+          children: [
+            {
+              name: "refs",
+              path: "refs",
+              kind: "dir",
+            },
+            {
+              name: "SKILL.md",
+              path: "SKILL.md",
+              kind: "file",
+              size: 10,
+              mtime: 1,
+            },
+          ],
+        };
+      }
+
+      if (
+        op === "skills.files.create" ||
+        op === "skills.files.rename" ||
+        op === "skills.files.delete"
+      ) {
+        return { ok: true };
+      }
+
+      if (op === "workspace.uiState.set") {
+        const workspaceId = args?.workspaceId ?? "ws-test";
+        const workspace = store.get(workspacesAtom)[workspaceId];
+        return {
+          id: workspaceId,
+          path: workspace?.path ?? "/workspace",
+          targetRuntime: workspace?.targetRuntime ?? "native",
+          openedAt: workspace?.openedAt ?? 1,
+          lastActiveAt: workspace?.lastActiveAt ?? 1,
+          uiState: args?.uiState,
+        };
+      }
+
+      throw new Error(`Unexpected command: ${op}`);
+    }
+  );
+}
+
+describe("useSkillFileActions", () => {
+  it("loads the root tree and opens a skill file in the existing editor flow", async () => {
+    const store = createStore();
+    const sendCommand = createSendCommand(store);
+
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+    seedWorkspace(store);
+
+    const { result } = renderHook(
+      () => useSkillFileActions({ workspaceId: "ws-test", skillSlug: "my-review-skill" }),
+      {
+        wrapper: wrapperFor(store),
+      }
+    );
+
+    await act(async () => {
+      await result.current.loadFileTree();
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "skills.files.readTree",
+      {
+        skillSlug: "my-review-skill",
+      },
+      undefined
+    );
+    expect(result.current.fileTree?.get(".")).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ path: "refs", kind: "dir" }),
+        expect.objectContaining({ path: "SKILL.md", kind: "file" }),
+      ])
+    );
+
+    await act(async () => {
+      await result.current.openSkillFile("SKILL.md");
+    });
+
+    const skillEditorPath = toSkillEditorPath("my-review-skill", "SKILL.md");
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe(skillEditorPath);
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([skillEditorPath]);
+    expect(store.get(pendingEditorNavigationAtomFamily("ws-test"))).toMatchObject({
+      workspaceId: "ws-test",
+      path: skillEditorPath,
+      source: "manual",
+      requestId: expect.any(Number),
+    });
+    expect(store.get(workspacesAtom)["ws-test"]?.uiState.openEditorPaths).toEqual([
+      skillEditorPath,
+    ]);
+  });
+
+  it("loads child directories on demand", async () => {
+    const store = createStore();
+    const sendCommand = createSendCommand(store);
+
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+    seedWorkspace(store);
+
+    const { result } = renderHook(
+      () => useSkillFileActions({ workspaceId: "ws-test", skillSlug: "my-review-skill" }),
+      {
+        wrapper: wrapperFor(store),
+      }
+    );
+
+    await act(async () => {
+      await result.current.loadFileTree();
+      await result.current.loadChildren("refs");
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "skills.files.readTree",
+      {
+        skillSlug: "my-review-skill",
+        path: "refs",
+      },
+      undefined
+    );
+    expect(result.current.fileTree?.get("refs")).toEqual([
+      expect.objectContaining({
+        path: "refs/guide.md",
+        kind: "file",
+      }),
+    ]);
+  });
+
+  it("creates a skill file and opens it in the editor", async () => {
+    const store = createStore();
+    const sendCommand = createSendCommand(store);
+
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+    seedWorkspace(store);
+
+    const { result } = renderHook(
+      () => useSkillFileActions({ workspaceId: "ws-test", skillSlug: "my-review-skill" }),
+      {
+        wrapper: wrapperFor(store),
+      }
+    );
+
+    await act(async () => {
+      await result.current.loadFileTree();
+    });
+
+    act(() => {
+      result.current.openCreateDialog("file", "refs");
+      result.current.updateDraftPath("refs/checklist.md");
+    });
+
+    await act(async () => {
+      await result.current.submitCreateDialog();
+    });
+
+    const skillEditorPath = toSkillEditorPath("my-review-skill", "refs/checklist.md");
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "skills.files.create",
+      {
+        skillSlug: "my-review-skill",
+        path: "refs/checklist.md",
+      },
+      undefined
+    );
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe(skillEditorPath);
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([skillEditorPath]);
+  });
+
+  it("renames open skill editor paths when a skill file is renamed", async () => {
+    const store = createStore();
+    const sendCommand = createSendCommand(store);
+    const oldEditorPath = toSkillEditorPath("my-review-skill", "refs/guide.md");
+    const nextEditorPath = toSkillEditorPath("my-review-skill", "refs/checklist.md");
+
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+    seedWorkspace(store);
+    store.set(activeFilePathAtomFamily("ws-test"), oldEditorPath);
+    store.set(openEditorPathsAtomFamily("ws-test"), [oldEditorPath, "README.md"]);
+    store.set(openFilesAtomFamily("ws-test"), {
+      [oldEditorPath]: {
+        kind: "text",
+        path: oldEditorPath,
+        content: "guide",
+        savedContent: "guide",
+        baseHash: "hash-1",
+        isDirty: false,
+      },
+    });
+
+    const { result } = renderHook(
+      () => useSkillFileActions({ workspaceId: "ws-test", skillSlug: "my-review-skill" }),
+      {
+        wrapper: wrapperFor(store),
+      }
+    );
+
+    act(() => {
+      result.current.openRenameDialog({
+        path: "refs/guide.md",
+        name: "guide.md",
+        kind: "file",
+      });
+      result.current.updateRenameDraft("checklist.md");
+    });
+
+    await act(async () => {
+      await result.current.submitRenameDialog();
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "skills.files.rename",
+      {
+        skillSlug: "my-review-skill",
+        fromPath: "refs/guide.md",
+        toPath: "refs/checklist.md",
+      },
+      undefined
+    );
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe(nextEditorPath);
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([nextEditorPath, "README.md"]);
+    expect(store.get(openFilesAtomFamily("ws-test"))).toEqual({
+      [nextEditorPath]: expect.objectContaining({
+        path: nextEditorPath,
+      }),
+    });
+  });
+
+  it("renames open descendant skill editor paths when a skill directory is renamed", async () => {
+    const store = createStore();
+    const sendCommand = createSendCommand(store);
+    const oldEditorPath = toSkillEditorPath("my-review-skill", "refs/guide.md");
+    const nextEditorPath = toSkillEditorPath("my-review-skill", "references/guide.md");
+
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+    seedWorkspace(store);
+    store.set(activeFilePathAtomFamily("ws-test"), oldEditorPath);
+    store.set(openEditorPathsAtomFamily("ws-test"), [oldEditorPath, "README.md"]);
+    store.set(openFilesAtomFamily("ws-test"), {
+      [oldEditorPath]: {
+        kind: "text",
+        path: oldEditorPath,
+        content: "guide",
+        savedContent: "guide",
+        baseHash: "hash-1",
+        isDirty: false,
+      },
+    });
+
+    const { result } = renderHook(
+      () => useSkillFileActions({ workspaceId: "ws-test", skillSlug: "my-review-skill" }),
+      {
+        wrapper: wrapperFor(store),
+      }
+    );
+
+    act(() => {
+      result.current.openRenameDialog({
+        path: "refs",
+        name: "refs",
+        kind: "dir",
+      });
+      result.current.updateRenameDraft("references");
+    });
+
+    await act(async () => {
+      await result.current.submitRenameDialog();
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "skills.files.rename",
+      {
+        skillSlug: "my-review-skill",
+        fromPath: "refs",
+        toPath: "references",
+      },
+      undefined
+    );
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe(nextEditorPath);
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([nextEditorPath, "README.md"]);
+    expect(store.get(openFilesAtomFamily("ws-test"))).toEqual({
+      [nextEditorPath]: expect.objectContaining({
+        path: nextEditorPath,
+      }),
+    });
+  });
+
+  it("removes open skill editor paths when a skill file is deleted", async () => {
+    const store = createStore();
+    const sendCommand = createSendCommand(store);
+    const editorPath = toSkillEditorPath("my-review-skill", "refs/guide.md");
+
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+    seedWorkspace(store);
+    store.set(activeFilePathAtomFamily("ws-test"), editorPath);
+    store.set(openEditorPathsAtomFamily("ws-test"), [editorPath, "README.md"]);
+    store.set(openFilesAtomFamily("ws-test"), {
+      [editorPath]: {
+        kind: "text",
+        path: editorPath,
+        content: "guide",
+        savedContent: "guide",
+        baseHash: "hash-1",
+        isDirty: false,
+      },
+    });
+
+    const { result } = renderHook(
+      () => useSkillFileActions({ workspaceId: "ws-test", skillSlug: "my-review-skill" }),
+      {
+        wrapper: wrapperFor(store),
+      }
+    );
+
+    act(() => {
+      result.current.requestDelete({
+        path: "refs/guide.md",
+        name: "guide.md",
+        error: null,
+      });
+    });
+
+    await act(async () => {
+      await result.current.confirmDelete();
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "skills.files.delete",
+      {
+        skillSlug: "my-review-skill",
+        path: "refs/guide.md",
+      },
+      {
+        timeoutMs: 180000,
+      }
+    );
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBeNull();
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual(["README.md"]);
+    expect(store.get(openFilesAtomFamily("ws-test"))).toEqual({});
+  });
+});
diff --git a/packages/web/src/features/workspace/actions/use-skill-file-actions.ts b/packages/web/src/features/workspace/actions/use-skill-file-actions.ts
new file mode 100644
index 000000000..eb779b3c6
--- /dev/null
+++ b/packages/web/src/features/workspace/actions/use-skill-file-actions.ts
@@ -0,0 +1,658 @@
+import type { FileNode } from "@coder-studio/core";
+import { useAtomValue, useSetAtom } from "jotai";
+import { useCallback, useRef, useState } from "react";
+import { dispatchCommandAtom } from "../../../atoms/connection";
+import { useTranslation } from "../../../lib/i18n";
+import { useOpenLocation } from "../../code-editor/actions/use-open-location";
+import { toSkillEditorPath } from "../../code-editor/skill-editor-path";
+import {
+  activeFilePathAtomFamily,
+  type OpenFile,
+  openEditorPathsAtomFamily,
+  openFilesAtomFamily,
+} from "../atoms";
+import {
+  customSkillCreateDialogAtomFamily,
+  customSkillExpandedDirsAtomFamily,
+  customSkillFileTreeAtomFamily,
+  customSkillLoadedDirsAtomFamily,
+  customSkillPendingDeleteAtomFamily,
+  customSkillRenameDialogAtomFamily,
+} from "../atoms/skills";
+import {
+  applyDirectoryRefresh,
+  applyRootTreeRefresh,
+  collectRefreshTargets,
+} from "./file-tree-refresh";
+import {
+  appendOpenEditorPath,
+  normalizeOpenEditorPaths,
+  rewriteDescendantEditorPath,
+  rewriteOpenEditorPaths,
+} from "./open-editor-state";
+import type { CreateDialogState, PendingDeleteState, RenameDialogState } from "./use-file-actions";
+import { useWorkspaceUiStatePersistence } from "./use-workspace-ui-state-persistence";
+
+interface ReadTreeResult {
+  path: string;
+  children: FileNode[];
+}
+
+interface UseSkillFileActionsArgs {
+  workspaceId: string;
+  skillSlug: string;
+}
+
+const FILE_DELETE_TIMEOUT_MS = 180_000;
+
+function isReadTreeResult(value: unknown): value is ReadTreeResult {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  return Array.isArray((value as ReadTreeResult).children);
+}
+
+function toSkillFilePath(skillSlug: string, relativePath: string): string {
+  return toSkillEditorPath(skillSlug, relativePath);
+}
+
+function rewriteDescendantPath(path: string, fromPath: string, toPath: string): string {
+  return rewriteDescendantEditorPath(path, fromPath, toPath);
+}
+
+function isSameOrDescendantPath(path: string, targetPath: string): boolean {
+  return path === targetPath || path.startsWith(`${targetPath}/`);
+}
+
+function removeDeletedEditorPaths(paths: Iterable<string>, deletedPath: string): string[] {
+  return normalizeOpenEditorPaths(Array.from(paths)).filter(
+    (path) => !isSameOrDescendantPath(path, deletedPath)
+  );
+}
+
+function removeDeletedOpenFiles(
+  openFiles: Record<string, OpenFile>,
+  deletedPath: string
+): Record<string, OpenFile> {
+  let changed = false;
+  const nextEntries = Object.entries(openFiles).filter(([path]) => {
+    const shouldKeep = !isSameOrDescendantPath(path, deletedPath);
+    changed = changed || !shouldKeep;
+    return shouldKeep;
+  });
+
+  return changed ? Object.fromEntries(nextEntries) : openFiles;
+}
+
+function removeDeletedTreeEntries(
+  previousTree: Map<string, FileNode[]> | null,
+  deletedPath: string
+): Map<string, FileNode[]> | null {
+  if (!previousTree) {
+    return previousTree;
+  }
+
+  const lastSlashIndex = deletedPath.lastIndexOf("/");
+  const parentPath = lastSlashIndex === -1 ? "." : deletedPath.slice(0, lastSlashIndex);
+  const nextTree = new Map<string, FileNode[]>();
+
+  for (const [path, nodes] of previousTree) {
+    if (isSameOrDescendantPath(path, deletedPath)) {
+      continue;
+    }
+
+    if (path === parentPath) {
+      nextTree.set(
+        path,
+        nodes.filter((node) => node.path !== deletedPath)
+      );
+      continue;
+    }
+
+    nextTree.set(path, nodes);
+  }
+
+  return nextTree;
+}
+
+function removeDeletedDirPaths(paths: Set<string>, deletedPath: string): Set<string> {
+  return new Set([...paths].filter((path) => !isSameOrDescendantPath(path, deletedPath)));
+}
+
+function rewriteOpenFiles(
+  openFiles: Record<string, OpenFile>,
+  fromPath: string,
+  toPath: string
+): Record<string, OpenFile> {
+  const nextEntries = Object.entries(openFiles).map(([path, file]) => {
+    const rewrittenPath = rewriteDescendantPath(path, fromPath, toPath);
+
+    if (rewrittenPath === path) {
+      return [path, file] as const;
+    }
+
+    return [
+      rewrittenPath,
+      {
+        ...file,
+        path: rewrittenPath,
+      },
+    ] as const;
+  });
+
+  return Object.fromEntries(nextEntries);
+}
+
+export function useSkillFileActions({ workspaceId, skillSlug }: UseSkillFileActionsArgs) {
+  const t = useTranslation();
+  const dispatch = useAtomValue(dispatchCommandAtom);
+  const fileTree = useAtomValue(customSkillFileTreeAtomFamily(workspaceId)(skillSlug));
+  const loadedDirs = useAtomValue(customSkillLoadedDirsAtomFamily(workspaceId)(skillSlug));
+  const expandedDirs = useAtomValue(customSkillExpandedDirsAtomFamily(workspaceId)(skillSlug));
+  const createDialog = useAtomValue(customSkillCreateDialogAtomFamily(workspaceId)(skillSlug));
+  const renameDialog = useAtomValue(customSkillRenameDialogAtomFamily(workspaceId)(skillSlug));
+  const pendingDelete = useAtomValue(customSkillPendingDeleteAtomFamily(workspaceId)(skillSlug));
+  const activeFilePath = useAtomValue(activeFilePathAtomFamily(workspaceId));
+  const openEditorPaths = useAtomValue(openEditorPathsAtomFamily(workspaceId));
+  const openFiles = useAtomValue(openFilesAtomFamily(workspaceId));
+  const setFileTree = useSetAtom(customSkillFileTreeAtomFamily(workspaceId)(skillSlug));
+  const setLoadedDirs = useSetAtom(customSkillLoadedDirsAtomFamily(workspaceId)(skillSlug));
+  const setExpandedDirs = useSetAtom(customSkillExpandedDirsAtomFamily(workspaceId)(skillSlug));
+  const setCreateDialog = useSetAtom(customSkillCreateDialogAtomFamily(workspaceId)(skillSlug));
+  const setRenameDialog = useSetAtom(customSkillRenameDialogAtomFamily(workspaceId)(skillSlug));
+  const setPendingDelete = useSetAtom(customSkillPendingDeleteAtomFamily(workspaceId)(skillSlug));
+  const setActiveFilePath = useSetAtom(activeFilePathAtomFamily(workspaceId));
+  const setOpenEditorPaths = useSetAtom(openEditorPathsAtomFamily(workspaceId));
+  const setOpenFiles = useSetAtom(openFilesAtomFamily(workspaceId));
+  const { openLocation } = useOpenLocation(workspaceId);
+  const { persistUiState } = useWorkspaceUiStatePersistence(workspaceId);
+  const [isLoading, setIsLoading] = useState(false);
+  const [isLoadingDir, setIsLoadingDir] = useState<string | null>(null);
+  const [isDeleting, setIsDeleting] = useState(false);
+  const deleteInFlightRef = useRef(false);
+
+  const loadFileTree = useCallback(async () => {
+    if (!workspaceId || !skillSlug || isLoading) {
+      return false;
+    }
+
+    setIsLoading(true);
+    try {
+      const result = await dispatch<ReadTreeResult>("skills.files.readTree", {
+        skillSlug,
+      });
+
+      if (!result.ok || !isReadTreeResult(result.data)) {
+        return false;
+      }
+
+      const reconciled = applyRootTreeRefresh({
+        previousTree: fileTree,
+        previousLoadedDirs: loadedDirs,
+        previousExpandedDirs: expandedDirs,
+        rootChildren: result.data.children,
+      });
+
+      let currentTree = reconciled.tree;
+      let currentLoadedDirs = reconciled.loadedDirs;
+
+      setFileTree(currentTree);
+      setLoadedDirs(currentLoadedDirs);
+      setExpandedDirs(reconciled.prunedExpandedDirs);
+
+      for (const dirPath of collectRefreshTargets(reconciled.prunedExpandedDirs)) {
+        const childResult = await dispatch<ReadTreeResult>("skills.files.readTree", {
+          skillSlug,
+          path: dirPath,
+        });
+
+        if (!childResult.ok || !isReadTreeResult(childResult.data)) {
+          continue;
+        }
+
+        const refreshed = applyDirectoryRefresh({
+          previousTree: currentTree,
+          previousLoadedDirs: currentLoadedDirs,
+          previousExpandedDirs: reconciled.prunedExpandedDirs,
+          dirPath,
+          children: childResult.data.children,
+        });
+
+        currentTree = refreshed.tree;
+        currentLoadedDirs = new Set(refreshed.loadedDirs).add(dirPath);
+        setFileTree(currentTree);
+        setLoadedDirs(currentLoadedDirs);
+      }
+
+      return true;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [
+    dispatch,
+    expandedDirs,
+    fileTree,
+    isLoading,
+    loadedDirs,
+    setExpandedDirs,
+    setFileTree,
+    setLoadedDirs,
+    skillSlug,
+    workspaceId,
+  ]);
+
+  const loadChildren = useCallback(
+    async (dirPath: string) => {
+      if (!workspaceId || !skillSlug || isLoadingDir === dirPath) {
+        return false;
+      }
+
+      if (expandedDirs.has(dirPath)) {
+        setExpandedDirs((current) => {
+          const next = new Set(current);
+          next.delete(dirPath);
+          return next;
+        });
+        return true;
+      }
+
+      setIsLoadingDir(dirPath);
+      try {
+        const result = await dispatch<ReadTreeResult>("skills.files.readTree", {
+          skillSlug,
+          path: dirPath,
+        });
+
+        if (!result.ok || !isReadTreeResult(result.data)) {
+          return false;
+        }
+
+        const refreshed = applyDirectoryRefresh({
+          previousTree: fileTree,
+          previousLoadedDirs: loadedDirs,
+          previousExpandedDirs: expandedDirs,
+          dirPath,
+          children: result.data.children,
+        });
+
+        setFileTree(refreshed.tree);
+        setLoadedDirs(new Set(refreshed.loadedDirs).add(dirPath));
+        setExpandedDirs((current) => new Set(current).add(dirPath));
+        return true;
+      } finally {
+        setIsLoadingDir(null);
+      }
+    },
+    [
+      dispatch,
+      expandedDirs,
+      fileTree,
+      isLoadingDir,
+      loadedDirs,
+      setExpandedDirs,
+      setFileTree,
+      setLoadedDirs,
+      skillSlug,
+      workspaceId,
+    ]
+  );
+
+  const openSkillFile = useCallback(
+    async (relativePath: string, source: "manual" | "file-tree" = "manual") => {
+      const path = toSkillFilePath(skillSlug, relativePath);
+      await openLocation({
+        workspaceId,
+        path,
+        source,
+      });
+      const nextOpenEditorPaths = appendOpenEditorPath(openEditorPaths, path);
+      setOpenEditorPaths(nextOpenEditorPaths);
+      void persistUiState({
+        openEditorPaths: nextOpenEditorPaths,
+        activeEditorPath: path,
+      });
+    },
+    [openEditorPaths, openLocation, persistUiState, setOpenEditorPaths, skillSlug, workspaceId]
+  );
+
+  const openCreateDialog = useCallback(
+    (mode: "file" | "folder", baseDir: string | null) => {
+      const normalizedBaseDir = baseDir ? `${baseDir.replace(/\/+$/, "")}/` : "";
+      setCreateDialog({
+        mode,
+        draftPath: normalizedBaseDir,
+        error: null,
+      });
+    },
+    [setCreateDialog]
+  );
+
+  const closeCreateDialog = useCallback(() => {
+    setCreateDialog(null);
+  }, [setCreateDialog]);
+
+  const updateDraftPath = useCallback(
+    (draftPath: string) => {
+      setCreateDialog((current) => {
+        if (!current) {
+          return current;
+        }
+
+        return {
+          ...current,
+          draftPath,
+          error: null,
+        };
+      });
+    },
+    [setCreateDialog]
+  );
+
+  const openRenameDialog = useCallback(
+    ({ path, name, kind }: { path: string; name: string; kind: "file" | "dir" }) => {
+      setRenameDialog({
+        fromPath: path,
+        currentName: name,
+        nextName: name,
+        kind,
+        error: null,
+      });
+    },
+    [setRenameDialog]
+  );
+
+  const closeRenameDialog = useCallback(() => {
+    setRenameDialog(null);
+  }, [setRenameDialog]);
+
+  const updateRenameDraft = useCallback(
+    (nextName: string) => {
+      setRenameDialog((current) =>
+        current
+          ? {
+              ...current,
+              nextName,
+              error: null,
+            }
+          : current
+      );
+    },
+    [setRenameDialog]
+  );
+
+  const submitCreateDialog = useCallback(async () => {
+    if (!createDialog) {
+      return;
+    }
+
+    const path = createDialog.draftPath.trim();
+    if (!path) {
+      setCreateDialog((current) =>
+        current
+          ? {
+              ...current,
+              error: t("file.path_required"),
+            }
+          : current
+      );
+      return;
+    }
+
+    if (createDialog.mode === "file" && path.endsWith("/")) {
+      setCreateDialog((current) =>
+        current
+          ? {
+              ...current,
+              error: t("file.invalid_file_path"),
+            }
+          : current
+      );
+      return;
+    }
+
+    const op = createDialog.mode === "file" ? "skills.files.create" : "skills.files.mkdir";
+    const result = await dispatch(op, {
+      skillSlug,
+      path,
+    });
+
+    if (!result.ok) {
+      setCreateDialog((current) =>
+        current
+          ? {
+              ...current,
+              error: result.error?.message ?? t("file.create_failed"),
+            }
+          : current
+      );
+      return;
+    }
+
+    await loadFileTree();
+    closeCreateDialog();
+
+    if (createDialog.mode === "file") {
+      await openSkillFile(path);
+    }
+  }, [
+    closeCreateDialog,
+    createDialog,
+    dispatch,
+    loadFileTree,
+    openSkillFile,
+    setCreateDialog,
+    skillSlug,
+    t,
+  ]);
+
+  const submitRenameDialog = useCallback(async () => {
+    if (!renameDialog) {
+      return;
+    }
+
+    const nextName = renameDialog.nextName.trim();
+    if (!nextName) {
+      setRenameDialog((current) =>
+        current
+          ? {
+              ...current,
+              error: t("file.rename_required"),
+            }
+          : current
+      );
+      return;
+    }
+
+    if (nextName.includes("/") || nextName.includes("\\")) {
+      setRenameDialog((current) =>
+        current
+          ? {
+              ...current,
+              error: t("file.rename_invalid_name"),
+            }
+          : current
+      );
+      return;
+    }
+
+    if (nextName === renameDialog.currentName) {
+      setRenameDialog(null);
+      return;
+    }
+
+    const lastSlashIndex = renameDialog.fromPath.lastIndexOf("/");
+    const parentDir = lastSlashIndex === -1 ? "" : renameDialog.fromPath.slice(0, lastSlashIndex);
+    const toPath = parentDir ? `${parentDir}/${nextName}` : nextName;
+
+    const result = await dispatch("skills.files.rename", {
+      skillSlug,
+      fromPath: renameDialog.fromPath,
+      toPath,
+    });
+
+    if (!result.ok) {
+      setRenameDialog((current) =>
+        current
+          ? {
+              ...current,
+              error: result.error?.message ?? t("file.rename_failed"),
+            }
+          : current
+      );
+      return;
+    }
+
+    const fromEditorPath = toSkillFilePath(skillSlug, renameDialog.fromPath);
+    const toEditorPath = toSkillFilePath(skillSlug, toPath);
+
+    const nextActiveFilePath = activeFilePath
+      ? rewriteDescendantPath(activeFilePath, fromEditorPath, toEditorPath)
+      : activeFilePath;
+    const nextOpenEditorPaths = rewriteOpenEditorPaths(
+      openEditorPaths,
+      fromEditorPath,
+      toEditorPath
+    );
+
+    setActiveFilePath(nextActiveFilePath);
+    setOpenEditorPaths(nextOpenEditorPaths);
+    setOpenFiles((current) => rewriteOpenFiles(current, fromEditorPath, toEditorPath));
+    void persistUiState({
+      openEditorPaths: nextOpenEditorPaths,
+      activeEditorPath: nextActiveFilePath,
+    });
+    await loadFileTree();
+    setRenameDialog(null);
+  }, [
+    activeFilePath,
+    dispatch,
+    loadFileTree,
+    openEditorPaths,
+    persistUiState,
+    renameDialog,
+    setActiveFilePath,
+    setOpenEditorPaths,
+    setOpenFiles,
+    setRenameDialog,
+    skillSlug,
+    t,
+  ]);
+
+  const cancelDelete = useCallback(() => {
+    if (deleteInFlightRef.current) {
+      return;
+    }
+
+    setPendingDelete(null);
+  }, [setPendingDelete]);
+
+  const confirmDelete = useCallback(async () => {
+    if (!pendingDelete || deleteInFlightRef.current) {
+      return;
+    }
+
+    deleteInFlightRef.current = true;
+    setIsDeleting(true);
+    try {
+      const result = await dispatch(
+        "skills.files.delete",
+        {
+          skillSlug,
+          path: pendingDelete.path,
+        },
+        {
+          timeoutMs: FILE_DELETE_TIMEOUT_MS,
+        }
+      );
+
+      if (!result.ok) {
+        setPendingDelete((current) =>
+          current
+            ? {
+                ...current,
+                error: result.error?.message ?? t("file.delete_failed"),
+              }
+            : current
+        );
+        return;
+      }
+
+      const targetEditorPath = toSkillFilePath(skillSlug, pendingDelete.path);
+      const nextActiveFilePath =
+        activeFilePath && isSameOrDescendantPath(activeFilePath, targetEditorPath)
+          ? null
+          : activeFilePath;
+      const nextOpenEditorPaths = removeDeletedEditorPaths(openEditorPaths, targetEditorPath);
+      const nextOpenFiles = removeDeletedOpenFiles(openFiles, targetEditorPath);
+      const nextTree = removeDeletedTreeEntries(fileTree, pendingDelete.path);
+      const nextLoadedDirs = removeDeletedDirPaths(loadedDirs, pendingDelete.path);
+      const nextExpandedDirs = removeDeletedDirPaths(expandedDirs, pendingDelete.path);
+
+      if (activeFilePath !== nextActiveFilePath) {
+        setActiveFilePath(nextActiveFilePath);
+      }
+
+      setOpenEditorPaths(nextOpenEditorPaths);
+      setOpenFiles(nextOpenFiles);
+      setFileTree(nextTree);
+      setLoadedDirs(nextLoadedDirs);
+      setExpandedDirs(nextExpandedDirs);
+      void persistUiState({
+        openEditorPaths: nextOpenEditorPaths,
+        activeEditorPath: nextActiveFilePath,
+      });
+      setPendingDelete(null);
+      void loadFileTree();
+    } finally {
+      deleteInFlightRef.current = false;
+      setIsDeleting(false);
+    }
+  }, [
+    activeFilePath,
+    dispatch,
+    expandedDirs,
+    fileTree,
+    loadFileTree,
+    loadedDirs,
+    openEditorPaths,
+    openFiles,
+    pendingDelete,
+    persistUiState,
+    setActiveFilePath,
+    setExpandedDirs,
+    setFileTree,
+    setLoadedDirs,
+    setOpenEditorPaths,
+    setOpenFiles,
+    setPendingDelete,
+    skillSlug,
+    t,
+  ]);
+
+  return {
+    activeFilePath,
+    createDialog,
+    expandedDirs,
+    fileTree,
+    isDeleting,
+    isLoading,
+    isLoadingDir,
+    pendingDelete,
+    renameDialog,
+    cancelDelete,
+    closeCreateDialog,
+    closeRenameDialog,
+    confirmDelete,
+    loadChildren,
+    loadFileTree,
+    openCreateDialog,
+    openRenameDialog,
+    openSkillFile,
+    requestDelete: setPendingDelete,
+    submitCreateDialog,
+    submitRenameDialog,
+    updateDraftPath,
+    updateRenameDraft,
+  };
+}
diff --git a/packages/web/src/features/workspace/actions/use-skills-panel.ts b/packages/web/src/features/workspace/actions/use-skills-panel.ts
index 55573daea..38a5606dd 100644
--- a/packages/web/src/features/workspace/actions/use-skills-panel.ts
+++ b/packages/web/src/features/workspace/actions/use-skills-panel.ts
@@ -4,14 +4,17 @@ import {
   type SkillLibraryEntry,
   type SkillMountRelation,
   type SkillRecommendationEntry,
+  type SkillRecommendationPage,
   type SkillVersionCheckEntry,
   Topics,
 } from "@coder-studio/core";
 import { useAtom, useAtomValue } from "jotai";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { dispatchCommandAtom, wsClientAtom } from "../../../atoms/connection";
 import { skillsPanelStateAtomFamily } from "../atoms/skills";
 
+const RECOMMENDATIONS_PAGE_SIZE = 20;
+
 export interface SkillSearchResultItem {
   slug: string;
   displayName: string;
@@ -43,6 +46,15 @@ interface SkillsHealthScanResult {
   mounts: SkillMountRelation[];
 }
 
+function appendUniqueRecommendations(
+  current: SkillRecommendationEntry[],
+  incoming: SkillRecommendationEntry[]
+) {
+  const seen = new Set(current.map((entry) => entry.slug));
+  const appended = incoming.filter((entry) => !seen.has(entry.slug));
+  return appended.length > 0 ? [...current, ...appended] : current;
+}
+
 export function useSkillsPanel(workspaceId: string) {
   const dispatch = useAtomValue(dispatchCommandAtom);
   const wsClient = useAtomValue(wsClientAtom);
@@ -62,9 +74,13 @@ export function useSkillsPanel(workspaceId: string) {
   );
   const [loadingSearch, setLoadingSearch] = useState(false);
   const [loadingRecommendations, setLoadingRecommendations] = useState(false);
+  const [recommendationsHasMore, setRecommendationsHasMore] = useState(false);
+  const [loadingRecommendationPage, setLoadingRecommendationPage] = useState(false);
   const [loadingLibrary, setLoadingLibrary] = useState(false);
   const [checkingVersions, setCheckingVersions] = useState(false);
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const recommendationCycleRef = useRef(0);
+  const recommendationPageLoadingRef = useRef(false);
 
   const refreshLibrary = useCallback(async () => {
     setLoadingLibrary(true);
@@ -100,18 +116,71 @@ export function useSkillsPanel(workspaceId: string) {
   );
 
   const refreshRecommendations = useCallback(async () => {
+    const cycle = recommendationCycleRef.current + 1;
+    recommendationCycleRef.current = cycle;
+    recommendationPageLoadingRef.current = false;
+    setLoadingRecommendationPage(false);
     setLoadingRecommendations(true);
-    const result = await dispatch<SkillRecommendationEntry[]>("skills.recommend", { workspaceId });
+    const result = await dispatch<SkillRecommendationPage>("skills.recommend", {
+      workspaceId,
+      limit: RECOMMENDATIONS_PAGE_SIZE,
+      offset: 0,
+    });
+    if (recommendationCycleRef.current !== cycle) {
+      return;
+    }
     setLoadingRecommendations(false);
     if (!result.ok || !result.data) {
       setErrorMessage(result.error?.message ?? "Failed to load skill recommendations");
       return;
     }
 
-    setRecommendations(result.data);
+    setRecommendations(result.data.entries);
+    setRecommendationsHasMore(result.data.hasMore);
     setErrorMessage(null);
   }, [dispatch, workspaceId]);
 
+  const loadMoreRecommendations = useCallback(async () => {
+    if (
+      loadingRecommendations ||
+      recommendationPageLoadingRef.current ||
+      panelState.recommendationsCollapsed ||
+      !recommendationsHasMore
+    ) {
+      return;
+    }
+
+    const cycle = recommendationCycleRef.current;
+    recommendationPageLoadingRef.current = true;
+    setLoadingRecommendationPage(true);
+    const result = await dispatch<SkillRecommendationPage>("skills.recommend", {
+      workspaceId,
+      limit: RECOMMENDATIONS_PAGE_SIZE,
+      offset: recommendations.length,
+    });
+    if (recommendationCycleRef.current !== cycle) {
+      return;
+    }
+    recommendationPageLoadingRef.current = false;
+    setLoadingRecommendationPage(false);
+
+    if (!result.ok || !result.data) {
+      setErrorMessage(result.error?.message ?? "Failed to load skill recommendations");
+      return;
+    }
+
+    setRecommendations((current) => appendUniqueRecommendations(current, result.data!.entries));
+    setRecommendationsHasMore(result.data.hasMore);
+    setErrorMessage(null);
+  }, [
+    dispatch,
+    loadingRecommendations,
+    panelState.recommendationsCollapsed,
+    recommendations.length,
+    recommendationsHasMore,
+    workspaceId,
+  ]);
+
   const checkSkillVersions = useCallback(async () => {
     setCheckingVersions(true);
     const result = await dispatch<SkillVersionCheckEntry[]>("skills.versions.check", {});
@@ -254,6 +323,29 @@ export function useSkillsPanel(workspaceId: string) {
     [dispatch, setPanelState]
   );
 
+  const createCustomSkill = useCallback(
+    async (name: string) => {
+      const trimmed = name.trim();
+      if (!trimmed) {
+        return null;
+      }
+
+      const result = await dispatch<SkillLibraryEntry>("skills.custom.create", {
+        name: trimmed,
+      });
+      if (!result.ok || !result.data) {
+        setErrorMessage(result.error?.message ?? "Failed to create custom skill");
+        return null;
+      }
+
+      setErrorMessage(null);
+      await refreshLibrary();
+      await refreshHealth();
+      return result.data;
+    },
+    [dispatch, refreshHealth, refreshLibrary]
+  );
+
   const setSkillMountEnabled = useCallback(
     async (skillSlug: string, providerIds: string[], enabled: boolean) => {
       if (providerIds.length === 0) {
@@ -396,13 +488,16 @@ export function useSkillsPanel(workspaceId: string) {
     errorMessage,
     checkSkillVersions,
     checkingVersions,
+    createCustomSkill,
     installSkill,
     installingSkillSlugs,
     library,
     loadSkillInfo,
     loadingLibrary,
+    loadingRecommendationPage,
     loadingRecommendations,
     loadingSearch,
+    loadMoreRecommendations,
     mountsBySkillSlug,
     panelState,
     refreshHealth,
@@ -410,6 +505,7 @@ export function useSkillsPanel(workspaceId: string) {
     setSkillMountEnabled,
     setBuiltinMountEnabled,
     recommendations,
+    recommendationsHasMore,
     runSearch,
     searchResults,
     setPanelState,
diff --git a/packages/web/src/features/workspace/actions/use-workspace-launch-actions.test.tsx b/packages/web/src/features/workspace/actions/use-workspace-launch-actions.test.tsx
index e4e9f269a..5b40c49a8 100644
--- a/packages/web/src/features/workspace/actions/use-workspace-launch-actions.test.tsx
+++ b/packages/web/src/features/workspace/actions/use-workspace-launch-actions.test.tsx
@@ -35,6 +35,12 @@ function Harness({ onClose }: { onClose: () => void }) {
       <button type="button" onClick={() => void actions.openWorkspaceByPath("/repo/history-app")}>
         open-history
       </button>
+      <button type="button" onClick={() => void actions.removeRecentWorkspace("/repo/history-app")}>
+        remove-history
+      </button>
+      <button type="button" onClick={() => void actions.clearRecentWorkspaces()}>
+        clear-history
+      </button>
     </div>
   );
 }
@@ -154,4 +160,114 @@ describe("useWorkspaceLaunchActions", () => {
     expect(store.get(workspacesAtom)).toHaveProperty("ws-history");
     expect(onClose).toHaveBeenCalledTimes(1);
   });
+
+  it("removes one recent workspace entry using the server-returned history snapshot", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string, args?: { path?: string }) => {
+      if (op === "workspace.browse") {
+        return {
+          currentPath: "/home/spencer",
+          parentPath: "/home",
+          directories: [],
+        };
+      }
+
+      if (op === "workspace.history.list") {
+        return [
+          {
+            path: "/repo/history-app",
+            name: "history-app",
+            lastOpenedAt: 100,
+          },
+          {
+            path: "/repo/keep-app",
+            name: "keep-app",
+            lastOpenedAt: 90,
+          },
+        ];
+      }
+
+      if (op === "workspace.history.remove") {
+        expect(args).toEqual({ path: "/repo/history-app" });
+        return [
+          {
+            path: "/repo/keep-app",
+            name: "keep-app",
+            lastOpenedAt: 90,
+          },
+        ];
+      }
+
+      return {};
+    });
+
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter>
+          <Harness onClose={vi.fn()} />
+        </MemoryRouter>
+      </Provider>
+    );
+
+    expect(await screen.findByTestId("recent-workspaces")).toHaveTextContent(
+      "/repo/history-app|/repo/keep-app"
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "remove-history" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("recent-workspaces")).toHaveTextContent("/repo/keep-app");
+    });
+  });
+
+  it("clears all recent workspaces using the server-returned empty history snapshot", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "workspace.browse") {
+        return {
+          currentPath: "/home/spencer",
+          parentPath: "/home",
+          directories: [],
+        };
+      }
+
+      if (op === "workspace.history.list") {
+        return [
+          {
+            path: "/repo/history-app",
+            name: "history-app",
+            lastOpenedAt: 100,
+          },
+        ];
+      }
+
+      if (op === "workspace.history.clear") {
+        return [];
+      }
+
+      return {};
+    });
+
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter>
+          <Harness onClose={vi.fn()} />
+        </MemoryRouter>
+      </Provider>
+    );
+
+    expect(await screen.findByTestId("recent-workspaces")).toHaveTextContent("/repo/history-app");
+
+    fireEvent.click(screen.getByRole("button", { name: "clear-history" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("recent-workspaces")).toHaveTextContent("");
+    });
+  });
 });
diff --git a/packages/web/src/features/workspace/actions/use-workspace-launch-actions.ts b/packages/web/src/features/workspace/actions/use-workspace-launch-actions.ts
index b4e416583..53886eff7 100644
--- a/packages/web/src/features/workspace/actions/use-workspace-launch-actions.ts
+++ b/packages/web/src/features/workspace/actions/use-workspace-launch-actions.ts
@@ -119,6 +119,49 @@ export function useWorkspaceLaunchActions(onClose: () => void) {
     }
   }, [dispatch]);
 
+  const removeRecentWorkspace = useCallback(
+    async (path: string) => {
+      if (!path) {
+        return false;
+      }
+
+      try {
+        const result = await dispatch<WorkspaceHistoryEntry[]>("workspace.history.remove", {
+          path,
+        });
+
+        if (!result.ok) {
+          setError(result.error?.message || t("workspace.launch.open_failed"));
+          return false;
+        }
+
+        setRecentWorkspaces(Array.isArray(result.data) ? result.data : []);
+        return true;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : String(err));
+        return false;
+      }
+    },
+    [dispatch, t]
+  );
+
+  const clearRecentWorkspaces = useCallback(async () => {
+    try {
+      const result = await dispatch<WorkspaceHistoryEntry[]>("workspace.history.clear", {});
+
+      if (!result.ok) {
+        setError(result.error?.message || t("workspace.launch.open_failed"));
+        return false;
+      }
+
+      setRecentWorkspaces(Array.isArray(result.data) ? result.data : []);
+      return true;
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+      return false;
+    }
+  }, [dispatch, t]);
+
   useEffect(() => {
     void loadDirectory();
     void loadWorkspaceHistory();
@@ -349,7 +392,9 @@ export function useWorkspaceLaunchActions(onClose: () => void) {
     recentWorkspaces,
     rootPaths,
     closeCreateFolder,
+    clearRecentWorkspaces,
     selectedPath,
+    removeRecentWorkspace,
     submitCreateFolder,
     updateNewFolderName,
   };
diff --git a/packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx b/packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx
index fd7509faf..68b2a942c 100644
--- a/packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx
+++ b/packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.test.tsx
@@ -23,6 +23,21 @@ function wrapperFor(store: ReturnType<typeof createStore>) {
   };
 }
 
+function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((nextResolve, nextReject) => {
+    resolve = nextResolve;
+    reject = nextReject;
+  });
+
+  return {
+    promise,
+    reject,
+    resolve,
+  };
+}
+
 function browserTab(id: string, url: string | null) {
   return {
     kind: "browser" as const,
@@ -36,6 +51,17 @@ function browserTab(id: string, url: string | null) {
   };
 }
 
+function canvasTab(id: string, canvasId: string, title: string) {
+  return {
+    kind: "canvas" as const,
+    id,
+    canvasId,
+    title,
+    artifactType: "architecture_canvas" as const,
+    sourcePath: `.coder-studio/canvases/${canvasId}.canvas.json`,
+  };
+}
+
 describe("useWorkspaceUiStatePersistence", () => {
   it("persists ui state when the workspace record is missing uiState", async () => {
     const sendCommand = vi.fn().mockImplementation(async (_op: string, payload: unknown) => {
@@ -342,4 +368,246 @@ describe("useWorkspaceUiStatePersistence", () => {
       undefined
     );
   });
+
+  it("persists canvas tabs through workspace.uiState.set", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (_op: string, payload: unknown) => {
+      const { workspaceId, uiState } = payload as {
+        workspaceId: string;
+        uiState: Record<string, unknown>;
+      };
+
+      return {
+        ...store.get(workspacesAtom)[workspaceId],
+        uiState,
+      };
+    });
+
+    const store = createStore();
+    store.set(wsClientAtom, { sendCommand } as never);
+    store.set(workspacesAtom, {
+      "ws-test": {
+        id: "ws-test",
+        path: "/workspace",
+        targetRuntime: "native",
+        openedAt: 1,
+        lastActiveAt: 1,
+        uiState: {
+          leftPanelWidth: 240,
+          bottomPanelHeight: 180,
+          focusMode: false,
+        },
+      },
+    } as never);
+    store.set(leftPanelWidthAtomFamily("ws-test"), 280);
+    store.set(bottomPanelHeightAtomFamily("ws-test"), 220);
+    store.set(focusModeAtomFamily("ws-test"), true);
+    store.set(editorViewVisibleAtomFamily("ws-test"), true);
+    store.set(paneLayoutAtomFamily("ws-test"), {
+      id: "root",
+      type: "leaf",
+      leafKind: "editor",
+    });
+    store.set(openEditorTabsAtomFamily("ws-test"), [
+      canvasTab("canvas:canvas-1", "canvas-1", "Runtime Flow"),
+    ]);
+    store.set(
+      activeEditorTabAtomFamily("ws-test"),
+      canvasTab("canvas:canvas-1", "canvas-1", "Runtime Flow")
+    );
+
+    const { result } = renderHook(() => useWorkspaceUiStatePersistence("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.persistUiState({});
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "workspace.uiState.set",
+      {
+        workspaceId: "ws-test",
+        uiState: expect.objectContaining({
+          openEditorTabs: [canvasTab("canvas:canvas-1", "canvas-1", "Runtime Flow")],
+          activeEditorTab: canvasTab("canvas:canvas-1", "canvas-1", "Runtime Flow"),
+        }),
+      },
+      undefined
+    );
+  });
+
+  it("persists editor pinned state through workspace.uiState.set", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (_op: string, payload: unknown) => {
+      const { workspaceId, uiState } = payload as {
+        workspaceId: string;
+        uiState: Record<string, unknown>;
+      };
+
+      return {
+        ...store.get(workspacesAtom)[workspaceId],
+        uiState,
+      };
+    });
+
+    const store = createStore();
+    store.set(wsClientAtom, { sendCommand } as never);
+    store.set(workspacesAtom, {
+      "ws-test": {
+        id: "ws-test",
+        path: "/workspace",
+        targetRuntime: "native",
+        openedAt: 1,
+        lastActiveAt: 1,
+        uiState: {
+          leftPanelWidth: 240,
+          bottomPanelHeight: 180,
+          focusMode: false,
+        },
+      },
+    } as never);
+    store.set(leftPanelWidthAtomFamily("ws-test"), 280);
+    store.set(bottomPanelHeightAtomFamily("ws-test"), 220);
+    store.set(focusModeAtomFamily("ws-test"), true);
+    store.set(editorViewVisibleAtomFamily("ws-test"), true);
+    store.set(paneLayoutAtomFamily("ws-test"), {
+      id: "root",
+      type: "leaf",
+      leafKind: "editor",
+    });
+
+    const { result } = renderHook(() => useWorkspaceUiStatePersistence("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.persistUiState({ editorPinned: false });
+    });
+
+    expect(sendCommand).toHaveBeenCalledWith(
+      "workspace.uiState.set",
+      {
+        workspaceId: "ws-test",
+        uiState: expect.objectContaining({
+          leftPanelWidth: 280,
+          bottomPanelHeight: 220,
+          focusMode: true,
+          editorViewVisible: true,
+          editorPinned: false,
+          paneLayout: {
+            id: "root",
+            type: "leaf",
+            leafKind: "editor",
+          },
+        }),
+      },
+      undefined
+    );
+  });
+
+  it("does not let an older ui state response overwrite a newer editor pinned change", async () => {
+    const firstWrite = createDeferred<{
+      id: string;
+      path: string;
+      targetRuntime: "native";
+      openedAt: number;
+      lastActiveAt: number;
+      uiState: Record<string, unknown>;
+    }>();
+    const secondWrite = createDeferred<{
+      id: string;
+      path: string;
+      targetRuntime: "native";
+      openedAt: number;
+      lastActiveAt: number;
+      uiState: Record<string, unknown>;
+    }>();
+    const sendCommand = vi
+      .fn()
+      .mockImplementationOnce(() => firstWrite.promise)
+      .mockImplementationOnce(() => secondWrite.promise);
+
+    const store = createStore();
+    store.set(wsClientAtom, { sendCommand } as never);
+    store.set(workspacesAtom, {
+      "ws-test": {
+        id: "ws-test",
+        path: "/workspace",
+        targetRuntime: "native",
+        openedAt: 1,
+        lastActiveAt: 1,
+        uiState: {
+          leftPanelWidth: 240,
+          bottomPanelHeight: 180,
+          focusMode: false,
+          editorViewVisible: true,
+        },
+      },
+    } as never);
+    store.set(leftPanelWidthAtomFamily("ws-test"), 280);
+    store.set(bottomPanelHeightAtomFamily("ws-test"), 220);
+    store.set(focusModeAtomFamily("ws-test"), true);
+    store.set(editorViewVisibleAtomFamily("ws-test"), true);
+    store.set(paneLayoutAtomFamily("ws-test"), {
+      id: "root",
+      type: "leaf",
+      leafKind: "editor",
+    });
+
+    const { result } = renderHook(() => useWorkspaceUiStatePersistence("ws-test"), {
+      wrapper: wrapperFor(store),
+    });
+
+    let firstRequest!: Promise<boolean>;
+    let secondRequest!: Promise<boolean>;
+
+    act(() => {
+      firstRequest = result.current.persistUiState({ activeSessionId: "sess-1" });
+      secondRequest = result.current.persistUiState({ editorPinned: false });
+    });
+
+    expect(store.get(workspacesAtom)["ws-test"]?.uiState.editorPinned).toBe(false);
+
+    await act(async () => {
+      secondWrite.resolve({
+        ...store.get(workspacesAtom)["ws-test"],
+        uiState: {
+          leftPanelWidth: 280,
+          bottomPanelHeight: 220,
+          focusMode: true,
+          editorViewVisible: true,
+          paneLayout: {
+            id: "root",
+            type: "leaf",
+            leafKind: "editor",
+          },
+          activeSessionId: "sess-1",
+          editorPinned: false,
+        },
+      });
+      await secondRequest;
+    });
+
+    expect(store.get(workspacesAtom)["ws-test"]?.uiState.editorPinned).toBe(false);
+
+    await act(async () => {
+      firstWrite.resolve({
+        ...store.get(workspacesAtom)["ws-test"],
+        uiState: {
+          leftPanelWidth: 280,
+          bottomPanelHeight: 220,
+          focusMode: true,
+          editorViewVisible: true,
+          paneLayout: {
+            id: "root",
+            type: "leaf",
+            leafKind: "editor",
+          },
+          activeSessionId: "sess-1",
+        },
+      });
+      await firstRequest;
+    });
+
+    expect(store.get(workspacesAtom)["ws-test"]?.uiState.editorPinned).toBe(false);
+  });
 });
diff --git a/packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.ts b/packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.ts
index 9db7d330d..a5e292bb9 100644
--- a/packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.ts
+++ b/packages/web/src/features/workspace/actions/use-workspace-ui-state-persistence.ts
@@ -1,5 +1,5 @@
 import type { Workspace } from "@coder-studio/core";
-import { useAtomValue, useSetAtom, useStore } from "jotai";
+import { type Store, useAtomValue, useSetAtom, useStore } from "jotai";
 import { useCallback } from "react";
 import { dispatchCommandAtom, wsClientAtom } from "../../../atoms/connection";
 import { workspacesAtom } from "../../../atoms/workspaces";
@@ -48,6 +48,25 @@ function stripLegacyDevBrowserTargetUrl(
   return restUiState;
 }
 
+const workspaceUiWriteSeqByStore = new WeakMap<Store, Map<string, number>>();
+
+function nextWorkspaceUiWriteSeq(store: Store, workspaceId: string): number {
+  const existing = workspaceUiWriteSeqByStore.get(store);
+  const sequences = existing ?? new Map<string, number>();
+
+  if (!existing) {
+    workspaceUiWriteSeqByStore.set(store, sequences);
+  }
+
+  const nextSeq = (sequences.get(workspaceId) ?? 0) + 1;
+  sequences.set(workspaceId, nextSeq);
+  return nextSeq;
+}
+
+function getLatestWorkspaceUiWriteSeq(store: Store, workspaceId: string): number {
+  return workspaceUiWriteSeqByStore.get(store)?.get(workspaceId) ?? 0;
+}
+
 export function useWorkspaceUiStatePersistence(workspaceId: string) {
   const dispatch = useAtomValue(dispatchCommandAtom);
   const wsClient = useAtomValue(wsClientAtom);
@@ -64,6 +83,7 @@ export function useWorkspaceUiStatePersistence(workspaceId: string) {
       if (!workspace) {
         return false;
       }
+      const writeSeq = nextWorkspaceUiWriteSeq(store, workspaceId);
 
       const currentOpenEditorPaths = store.get(openEditorPathsAtomFamily(workspaceId));
       const currentActiveEditorPath = store.get(activeFilePathAtomFamily(workspaceId));
@@ -79,11 +99,12 @@ export function useWorkspaceUiStatePersistence(workspaceId: string) {
         workspace.uiState?.activeEditorPath !== undefined ||
         currentOpenEditorPaths.length > 0 ||
         currentActiveEditorPath !== null;
-      const shouldIncludeBrowserEditorState =
+      const shouldIncludeEditorTabState =
         workspace.uiState?.openEditorTabs !== undefined ||
         workspace.uiState?.activeEditorTab !== undefined ||
-        currentOpenEditorTabs.some((tab) => tab.kind === "browser") ||
-        currentActiveEditorTab?.kind === "browser";
+        currentOpenEditorTabs.some((tab) => tab.kind !== "file") ||
+        currentActiveEditorTab?.kind === "browser" ||
+        currentActiveEditorTab?.kind === "canvas";
 
       const nextUiState: Workspace["uiState"] = {
         ...baseUiState,
@@ -98,7 +119,7 @@ export function useWorkspaceUiStatePersistence(workspaceId: string) {
               activeEditorPath: currentActiveEditorPath,
             }
           : {}),
-        ...(shouldIncludeBrowserEditorState
+        ...(shouldIncludeEditorTabState
           ? {
               openEditorTabs: currentOpenEditorTabs,
               activeEditorTab: currentActiveEditorTab,
@@ -138,7 +159,10 @@ export function useWorkspaceUiStatePersistence(workspaceId: string) {
         }
 
         const persistedWorkspace = result.data;
-        if (isWorkspace(persistedWorkspace)) {
+        if (
+          isWorkspace(persistedWorkspace) &&
+          getLatestWorkspaceUiWriteSeq(store, workspaceId) === writeSeq
+        ) {
           setWorkspaces((previous) => ({
             ...previous,
             [workspaceId]: persistedWorkspace,
diff --git a/packages/web/src/features/workspace/atoms/files.test.ts b/packages/web/src/features/workspace/atoms/files.test.ts
index 9eda57a36..196e69bd4 100644
--- a/packages/web/src/features/workspace/atoms/files.test.ts
+++ b/packages/web/src/features/workspace/atoms/files.test.ts
@@ -36,13 +36,13 @@ describe("workspace editor tabs", () => {
       normalizeWorkspaceEditorTabs([
         { kind: "file", path: "src/app.tsx" },
         { kind: "browser", id: "dev-browser", url: null },
-        { kind: "file", path: "src/app.tsx" },
+        { kind: "file", path: "src/app.tsx", pinned: false },
         { kind: "browser", id: "dev-browser", url: null },
         { kind: "file", path: "" },
         { kind: "browser", id: "   " },
       ])
     ).toEqual([
-      { kind: "file", path: "src/app.tsx" },
+      { kind: "file", path: "src/app.tsx", pinned: true },
       {
         kind: "browser",
         id: "dev-browser",
@@ -56,6 +56,12 @@ describe("workspace editor tabs", () => {
     ]);
   });
 
+  it("preserves preview file tabs when they are already marked unpinned", () => {
+    expect(
+      normalizeWorkspaceEditorTabs([{ kind: "file", path: "src/preview.ts", pinned: false }])
+    ).toEqual([{ kind: "file", path: "src/preview.ts", pinned: false }]);
+  });
+
   it("keeps duplicate same-url browser tabs when ids differ", () => {
     expect(
       normalizeWorkspaceEditorTabs([
@@ -132,6 +138,26 @@ describe("workspace editor tabs", () => {
     ]);
   });
 
+  it("deduplicates canvas tabs by sourcePath", () => {
+    expect(
+      normalizeWorkspaceEditorTabs([
+        {
+          kind: "canvas",
+          id: "canvas:.coder-studio/canvases/runtime-flow.csc",
+          title: "Runtime Flow",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+        },
+        {
+          kind: "canvas",
+          id: "canvas:legacy-id",
+          title: "Runtime Flow",
+          sourcePath: ".coder-studio/canvases/runtime-flow.csc",
+          canvasId: "canvas-1",
+        },
+      ])
+    ).toHaveLength(1);
+  });
+
   it("creates browser editor tabs with normalized urls", () => {
     const tab = createWorkspaceBrowserEditorTab(" localhost:8000 ");
 
diff --git a/packages/web/src/features/workspace/atoms/files.ts b/packages/web/src/features/workspace/atoms/files.ts
index 3d8f00b36..96d50cc0d 100644
--- a/packages/web/src/features/workspace/atoms/files.ts
+++ b/packages/web/src/features/workspace/atoms/files.ts
@@ -81,6 +81,7 @@ export type WorkspaceEditorMode = "preview" | "edit" | "diff";
 export interface WorkspaceFileEditorTab {
   kind: "file";
   path: string;
+  pinned?: boolean;
 }
 
 export type DevBrowserDevicePreset = "desktop" | "iphone-14" | "pixel-7" | "custom";
@@ -98,12 +99,39 @@ export interface WorkspaceBrowserEditorTab {
   userAgentMode: DevBrowserUserAgentMode;
 }
 
-export type WorkspaceEditorTab = WorkspaceFileEditorTab | WorkspaceBrowserEditorTab;
+export interface WorkspaceCanvasEditorTab {
+  kind: "canvas";
+  id: string;
+  title: string;
+  sourcePath: string;
+  artifactType?: "architecture_canvas" | "report_canvas";
+  canvasId?: string;
+}
+
+export type WorkspaceEditorTab =
+  | WorkspaceFileEditorTab
+  | WorkspaceBrowserEditorTab
+  | WorkspaceCanvasEditorTab;
 
 let browserTabIdCounter = 0;
 
 export const MAX_BROWSER_VIEWPORT_DIMENSION = 4096;
 
+export function createWorkspaceFileEditorTab(
+  path: string,
+  options: { pinned?: boolean } = {}
+): WorkspaceFileEditorTab {
+  return {
+    kind: "file",
+    path,
+    pinned: options.pinned ?? true,
+  };
+}
+
+export function isPreviewFileEditorTab(tab: WorkspaceEditorTab | null | undefined): boolean {
+  return tab?.kind === "file" && tab.pinned === false;
+}
+
 function normalizeViewportDimension(value: unknown): number | null {
   return typeof value === "number" &&
     Number.isInteger(value) &&
@@ -148,11 +176,16 @@ export function createWorkspaceBrowserEditorTab(
 
 const IMAGE_FILE_EXTENSION_PATTERN = /\.(avif|bmp|gif|ico|jpe?g|png|svg|tiff?|webp)$/i;
 const DOCUMENT_PREVIEW_EXTENSION_PATTERN = /\.(md|markdown|html?)$/i;
+const CANVAS_SOURCE_EXTENSION_PATTERN = /\.csc$/i;
 
 export function isDocumentPreviewPath(path: string): boolean {
   return DOCUMENT_PREVIEW_EXTENSION_PATTERN.test(path);
 }
 
+export function isCanvasSourcePath(path: string): boolean {
+  return CANVAS_SOURCE_EXTENSION_PATTERN.test(path);
+}
+
 export function deriveDocumentPreviewKind(path: string): "markdown" | "html" | null {
   if (/\.(md|markdown)$/i.test(path)) {
     return "markdown";
@@ -189,6 +222,66 @@ export function deriveEditorModeForPath(path: string): WorkspaceEditorMode {
   return isPreviewByDefaultPath(path) ? "preview" : "edit";
 }
 
+function deriveCanvasTabTitle(sourcePath: string): string {
+  const fileName = sourcePath.split("/").pop() ?? sourcePath;
+  return fileName.replace(/\.csc$/i, "");
+}
+
+export function createWorkspaceCanvasEditorTab(input: {
+  sourcePath: string;
+  title?: string;
+  artifactType?: "architecture_canvas" | "report_canvas";
+  canvasId?: string;
+  id?: string;
+}): WorkspaceCanvasEditorTab {
+  const sourcePath = input.sourcePath.trim();
+
+  return {
+    kind: "canvas",
+    id: input.id?.trim() || `canvas:${sourcePath}`,
+    title: input.title?.trim() || deriveCanvasTabTitle(sourcePath),
+    sourcePath,
+    ...(input.artifactType ? { artifactType: input.artifactType } : {}),
+    ...(input.canvasId?.trim() ? { canvasId: input.canvasId.trim() } : {}),
+  };
+}
+
+export function deriveCanvasArtifactTypeFromOpenFile(
+  file?: OpenFile
+): WorkspaceCanvasEditorTab["artifactType"] {
+  if (file?.kind !== "text") {
+    return undefined;
+  }
+
+  try {
+    const candidate = JSON.parse(file.content) as { kind?: unknown };
+    if (candidate.kind === "architecture_canvas" || candidate.kind === "report_canvas") {
+      return candidate.kind;
+    }
+  } catch {
+    return undefined;
+  }
+
+  return undefined;
+}
+
+export function createWorkspaceCanvasEditorTabFromSourcePath(input: {
+  sourcePath: string;
+  file?: OpenFile;
+  existingTab?: WorkspaceCanvasEditorTab;
+}): WorkspaceCanvasEditorTab {
+  const artifactType =
+    deriveCanvasArtifactTypeFromOpenFile(input.file) ?? input.existingTab?.artifactType;
+
+  return createWorkspaceCanvasEditorTab({
+    sourcePath: input.sourcePath,
+    id: input.existingTab?.id,
+    title: input.existingTab?.title,
+    artifactType,
+    canvasId: input.existingTab?.canvasId?.trim() || input.sourcePath,
+  });
+}
+
 function normalizeBrowserTab(entry: unknown): WorkspaceBrowserEditorTab | null {
   if (!entry || typeof entry !== "object") {
     return null;
@@ -218,6 +311,41 @@ function normalizeBrowserTab(entry: unknown): WorkspaceBrowserEditorTab | null {
   };
 }
 
+function normalizeCanvasTab(entry: unknown): WorkspaceCanvasEditorTab | null {
+  if (!entry || typeof entry !== "object") {
+    return null;
+  }
+
+  const candidate = entry as Partial<WorkspaceCanvasEditorTab>;
+  if (candidate.kind !== "canvas") {
+    return null;
+  }
+
+  if (typeof candidate.sourcePath !== "string" || candidate.sourcePath.trim().length === 0) {
+    return null;
+  }
+
+  if (
+    candidate.artifactType !== undefined &&
+    candidate.artifactType !== "architecture_canvas" &&
+    candidate.artifactType !== "report_canvas"
+  ) {
+    return null;
+  }
+
+  if (typeof candidate.title !== "string" || candidate.title.trim().length === 0) {
+    return null;
+  }
+
+  return createWorkspaceCanvasEditorTab({
+    id: typeof candidate.id === "string" ? candidate.id : undefined,
+    title: candidate.title,
+    artifactType: candidate.artifactType,
+    sourcePath: candidate.sourcePath,
+    canvasId: typeof candidate.canvasId === "string" ? candidate.canvasId : undefined,
+  });
+}
+
 export function normalizeWorkspaceEditorTabs(value: unknown): WorkspaceEditorTab[] {
   if (!Array.isArray(value)) {
     return [];
@@ -225,6 +353,7 @@ export function normalizeWorkspaceEditorTabs(value: unknown): WorkspaceEditorTab
 
   const seenFilePaths = new Set<string>();
   const seenBrowserIds = new Set<string>();
+  const seenCanvasSourcePaths = new Set<string>();
   const next: WorkspaceEditorTab[] = [];
 
   for (const entry of value) {
@@ -239,6 +368,17 @@ export function normalizeWorkspaceEditorTabs(value: unknown): WorkspaceEditorTab
       continue;
     }
 
+    const normalizedCanvasTab = normalizeCanvasTab(entry);
+    if (normalizedCanvasTab) {
+      if (seenCanvasSourcePaths.has(normalizedCanvasTab.sourcePath)) {
+        continue;
+      }
+
+      seenCanvasSourcePaths.add(normalizedCanvasTab.sourcePath);
+      next.push(normalizedCanvasTab);
+      continue;
+    }
+
     if (!entry || typeof entry !== "object") {
       continue;
     }
@@ -258,7 +398,11 @@ export function normalizeWorkspaceEditorTabs(value: unknown): WorkspaceEditorTab
     }
 
     seenFilePaths.add(path);
-    next.push({ kind: "file", path });
+    next.push({
+      kind: "file",
+      path,
+      pinned: candidate.pinned === false ? false : true,
+    });
   }
 
   return next;
@@ -306,6 +450,16 @@ export const editorModeAtomFamily = atomFamily((_workspaceId: string) =>
  */
 export const editorRefreshTokenAtomFamily = atomFamily((_workspaceId: string) => atom<number>(0));
 
+export interface CanvasRefreshTokenKey {
+  workspaceId: string;
+  sourcePath: string;
+}
+
+export const canvasRefreshTokenAtomFamily = atomFamily(
+  (_key: CanvasRefreshTokenKey) => atom<number>(0),
+  (left, right) => left.workspaceId === right.workspaceId && left.sourcePath === right.sourcePath
+);
+
 /**
  * Active file (derived)
  */
diff --git a/packages/web/src/features/workspace/atoms/skills.ts b/packages/web/src/features/workspace/atoms/skills.ts
index b9731f97f..8a554940e 100644
--- a/packages/web/src/features/workspace/atoms/skills.ts
+++ b/packages/web/src/features/workspace/atoms/skills.ts
@@ -1,10 +1,17 @@
+import type { FileNode } from "@coder-studio/core";
 import { atom } from "jotai";
 import { atomFamily } from "jotai-family";
+import type {
+  CreateDialogState,
+  PendingDeleteState,
+  RenameDialogState,
+} from "../actions/use-file-actions";
 
 export interface SkillsPanelState {
   query: string;
   resolvedQuery: string;
   installJobIdBySlug: Record<string, string>;
+  customCollapsed: boolean;
   installedCollapsed: boolean;
   builtinCollapsed: boolean;
   discoverCollapsed: boolean;
@@ -16,6 +23,7 @@ function createInitialSkillsPanelState(): SkillsPanelState {
     query: "",
     resolvedQuery: "",
     installJobIdBySlug: {},
+    customCollapsed: false,
     installedCollapsed: true,
     builtinCollapsed: true,
     discoverCollapsed: false,
@@ -26,3 +34,27 @@ function createInitialSkillsPanelState(): SkillsPanelState {
 export const skillsPanelStateAtomFamily = atomFamily((_workspaceId: string) =>
   atom<SkillsPanelState>(createInitialSkillsPanelState())
 );
+
+export const customSkillFileTreeAtomFamily = atomFamily((_workspaceId: string) =>
+  atomFamily((_skillSlug: string) => atom<Map<string, FileNode[]> | null>(null))
+);
+
+export const customSkillLoadedDirsAtomFamily = atomFamily((_workspaceId: string) =>
+  atomFamily((_skillSlug: string) => atom<Set<string>>(new Set<string>()))
+);
+
+export const customSkillExpandedDirsAtomFamily = atomFamily((_workspaceId: string) =>
+  atomFamily((_skillSlug: string) => atom<Set<string>>(new Set<string>()))
+);
+
+export const customSkillCreateDialogAtomFamily = atomFamily((_workspaceId: string) =>
+  atomFamily((_skillSlug: string) => atom<CreateDialogState | null>(null))
+);
+
+export const customSkillRenameDialogAtomFamily = atomFamily((_workspaceId: string) =>
+  atomFamily((_skillSlug: string) => atom<RenameDialogState | null>(null))
+);
+
+export const customSkillPendingDeleteAtomFamily = atomFamily((_workspaceId: string) =>
+  atomFamily((_skillSlug: string) => atom<PendingDeleteState | null>(null))
+);
diff --git a/packages/web/src/features/workspace/views/desktop/workspace-desktop-view.test.tsx b/packages/web/src/features/workspace/views/desktop/workspace-desktop-view.test.tsx
index 32bfe77a4..084e04998 100644
--- a/packages/web/src/features/workspace/views/desktop/workspace-desktop-view.test.tsx
+++ b/packages/web/src/features/workspace/views/desktop/workspace-desktop-view.test.tsx
@@ -7,13 +7,14 @@ import type { PointerEvent as ReactPointerEvent } from "react";
 import { MemoryRouter } from "react-router-dom";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { connectionStatusAtom, wsClientAtom } from "../../../../atoms/connection";
-import { activeWorkspaceIdAtom } from "../../../../atoms/workspaces";
+import { activeWorkspaceIdAtom, workspacesAtom } from "../../../../atoms/workspaces";
 import { seedReadyWorkspaceState } from "../../../../test-utils/workspace-state";
 import {
   activeEditorTabAtomFamily,
   activeFilePathAtomFamily,
   editorViewVisibleAtomFamily,
   openEditorPathsAtomFamily,
+  openEditorTabsAtomFamily,
   openFilesAtomFamily,
 } from "../../atoms";
 import { type DesktopSidebarView, desktopSidebarViewAtomFamily } from "../../atoms/layout";
@@ -21,6 +22,19 @@ import { WorkspaceDesktopView } from "./workspace-desktop-view";
 
 let lastWsSubscribeSpy: ReturnType<typeof vi.fn> | null = null;
 
+function browserTab(id: string, url: string | null) {
+  return {
+    kind: "browser" as const,
+    id,
+    url,
+    devicePreset: "desktop" as const,
+    viewportWidth: null,
+    viewportHeight: null,
+    orientation: "portrait" as const,
+    userAgentMode: "desktop" as const,
+  };
+}
+
 vi.mock("../../../../lib/i18n", () => ({
   useTranslation: () => (key: string) => {
     const translations: Record<string, string> = {
@@ -388,6 +402,42 @@ describe("WorkspaceDesktopView", () => {
     );
   });
 
+  it("restores the desktop editor as floating after refresh when persisted as unpinned with an active browser tab", () => {
+    const store = renderDesktopView("explorer");
+    const persistedBrowserTab = browserTab("browser-1", "http://127.0.0.1:5173/");
+
+    act(() => {
+      const currentWorkspaces = store.get(workspacesAtom);
+      const currentWorkspace = currentWorkspaces["ws-test"];
+      if (!currentWorkspace) {
+        throw new Error("Expected test workspace to exist");
+      }
+
+      store.set(workspacesAtom, {
+        ...currentWorkspaces,
+        "ws-test": {
+          ...currentWorkspace,
+          uiState: {
+            ...currentWorkspace.uiState,
+            editorPinned: false,
+          } as never,
+        },
+      });
+      store.set(editorViewVisibleAtomFamily("ws-test"), true);
+      store.set(openEditorTabsAtomFamily("ws-test"), [persistedBrowserTab]);
+      store.set(activeEditorTabAtomFamily("ws-test"), persistedBrowserTab);
+      store.set(activeFilePathAtomFamily("ws-test"), null);
+    });
+
+    const editorHost = screen.getByTestId("code-editor-host");
+    const overlay = editorHost.closest(".workspace-main-stage__editor-overlay");
+    const agentPanes = screen.getByTestId("agent-panes").closest(".agent-panes");
+
+    expect(editorHost).toHaveAttribute("data-editor-pinned", "false");
+    expect(overlay).toHaveClass("workspace-main-stage__editor-overlay--floating");
+    expect(agentPanes).not.toHaveAttribute("aria-hidden");
+  });
+
   it("toggles the desktop editor between pinned and floating overlay modes", () => {
     const store = renderDesktopView("explorer");
     act(() => {
diff --git a/packages/web/src/features/workspace/views/desktop/workspace-desktop-view.tsx b/packages/web/src/features/workspace/views/desktop/workspace-desktop-view.tsx
index 11bd0e828..3c9a9973e 100644
--- a/packages/web/src/features/workspace/views/desktop/workspace-desktop-view.tsx
+++ b/packages/web/src/features/workspace/views/desktop/workspace-desktop-view.tsx
@@ -357,7 +357,7 @@ const WorkspaceDesktopScene: FC = () => {
     null
   );
   const [editorRestoreOpening, setEditorRestoreOpening] = useState(false);
-  const [editorPinned, setEditorPinned] = useState(true);
+  const [editorPinned, setEditorPinned] = useState(workspace?.uiState.editorPinned ?? true);
   const [floatingEditorGeometry, setFloatingEditorGeometry] =
     useState<FloatingEditorGeometry | null>(null);
   const [floatingEditorInteractionKind, setFloatingEditorInteractionKind] = useState<
@@ -368,6 +368,7 @@ const WorkspaceDesktopScene: FC = () => {
   const floatingEditorRef = useRef<HTMLDivElement>(null);
   const floatingEditorInteractionRef = useRef<FloatingEditorInteraction | null>(null);
   const floatingEditorInteractionCleanupRef = useRef<(() => void) | null>(null);
+  const { persistUiState } = useWorkspaceUiStatePersistence(workspaceId);
   const editorRestoreStyle = useMemo<CSSProperties | undefined>(() => {
     if (!editorRestorePosition) {
       return undefined;
@@ -392,6 +393,10 @@ const WorkspaceDesktopScene: FC = () => {
     }
   }, [activeFilePath]);
 
+  useEffect(() => {
+    setEditorPinned(workspace?.uiState.editorPinned ?? true);
+  }, [workspace?.id, workspace?.uiState.editorPinned]);
+
   const handleEditorRestoreStart = () => {
     if (editorRestoreOpeningTimerRef.current !== null) {
       window.clearTimeout(editorRestoreOpeningTimerRef.current);
@@ -633,6 +638,11 @@ const WorkspaceDesktopScene: FC = () => {
     };
   };
 
+  const handleToggleEditorPinned = (nextPinned: boolean) => {
+    setEditorPinned(nextPinned);
+    void persistUiState({ editorPinned: nextPinned });
+  };
+
   useEffect(() => {
     const handleKeyDown = (event: KeyboardEvent) => {
       if (event.defaultPrevented || isEditableTarget(event.target)) {
@@ -814,7 +824,7 @@ const WorkspaceDesktopScene: FC = () => {
                   onBeginFloatingEditorMove={(event) =>
                     beginFloatingEditorInteraction("move", event)
                   }
-                  onToggleEditorPinned={setEditorPinned}
+                  onToggleEditorPinned={handleToggleEditorPinned}
                 />
               </div>
             ) : null}
diff --git a/packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx b/packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx
index d44f316b3..a1d8c657c 100644
--- a/packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx
+++ b/packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.test.tsx
@@ -1,4 +1,4 @@
-import { fireEvent, render, screen } from "@testing-library/react";
+import { fireEvent, render, screen, within } from "@testing-library/react";
 import { createStore, Provider } from "jotai";
 import { describe, expect, it, vi } from "vitest";
 import { localeAtom } from "../../../../atoms/app-ui";
@@ -30,7 +30,7 @@ function createDefaultProviders() {
 }
 
 describe("MobileAgentSheet", () => {
-  it("renders semantic icons for create-session and provider launch actions", () => {
+  it("renders a create-session semantic icon and monogram provider launch icons", () => {
     const store = createStore();
     store.set(localeAtom, "en");
     store.set(wsClientAtom, { sendCommand: vi.fn() } as never);
@@ -79,7 +79,6 @@ describe("MobileAgentSheet", () => {
     expect(
       firstView.container.querySelector('[data-icon-semantic="agent.action.newSession"]')
     ).toBeTruthy();
-    expect(screen.getByRole("button", { name: "Create Session" })).toBeInTheDocument();
 
     firstView.unmount();
 
@@ -100,12 +99,17 @@ describe("MobileAgentSheet", () => {
 
     expect(
       providerView.container.querySelector('[data-icon-semantic="agent.provider.claude"]')
-    ).toBeTruthy();
+    ).toBeNull();
     expect(
       providerView.container.querySelector('[data-icon-semantic="agent.provider.codex"]')
-    ).toBeTruthy();
-    expect(screen.getByRole("button", { name: "Claude" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "Codex" })).toBeInTheDocument();
+    ).toBeNull();
+
+    expect(
+      providerView.container.querySelector(".mobile-agent-provider-icon--claude")
+    ).toHaveTextContent("CL");
+    expect(
+      providerView.container.querySelector(".mobile-agent-provider-icon--codex")
+    ).toHaveTextContent("CO");
   });
 
   it("renders every provider returned by the launcher in create mode", () => {
@@ -121,6 +125,7 @@ describe("MobileAgentSheet", () => {
         createProvider("gemini", "Gemini CLI", "Gemini"),
         createProvider("cursor", "Cursor Agent", "Cursor"),
         createProvider("opencode", "OpenCode"),
+        createProvider("mistral", "Mistral Agent", "Mistral"),
       ],
       states: {
         claude: {
@@ -173,6 +178,16 @@ describe("MobileAgentSheet", () => {
           loading: false,
           installJob: null,
         },
+        mistral: {
+          runtime: {
+            available: true,
+            autoInstallSupported: true,
+            installReadiness: "ready",
+            manualGuideKeys: [],
+          },
+          loading: false,
+          installJob: null,
+        },
       },
       launch,
     });
@@ -197,6 +212,21 @@ describe("MobileAgentSheet", () => {
     expect(screen.getByRole("button", { name: "Gemini" })).toBeInTheDocument();
     expect(screen.getByRole("button", { name: "Cursor" })).toBeInTheDocument();
     expect(screen.getByRole("button", { name: "OpenCode" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Mistral" })).toBeInTheDocument();
+    expect(screen.getByText("CL")).toBeInTheDocument();
+    expect(screen.getByText("CO")).toBeInTheDocument();
+    expect(screen.getByText("GE")).toBeInTheDocument();
+    expect(screen.getByText("CU")).toBeInTheDocument();
+    expect(screen.getByText("OP")).toBeInTheDocument();
+    expect(screen.getByText("MI")).toBeInTheDocument();
+    expect(screen.getByText("GE").closest(".mobile-agent-provider-icon--gemini")).not.toBeNull();
+    expect(screen.getByText("CU").closest(".mobile-agent-provider-icon--cursor")).not.toBeNull();
+    expect(screen.getByText("OP").closest(".mobile-agent-provider-icon--opencode")).not.toBeNull();
+    const mistralIcon = screen.getByText("MI").closest(".mobile-agent-provider-icon--mistral");
+    expect(mistralIcon).not.toBeNull();
+    expect(mistralIcon?.className).toMatch(
+      /mobile-agent-provider-icon--tone-(accent|info|success|warning)/
+    );
 
     fireEvent.click(screen.getByRole("button", { name: "Gemini" }));
 
@@ -420,7 +450,10 @@ describe("MobileAgentSheet", () => {
 
     expect(screen.queryByText("Then run npm install -g @openai/codex.")).toBeNull();
     expect(screen.queryByRole("button", { name: "Open Diagnostics" })).toBeNull();
-    expect(screen.getByText("Start Codex session")).toBeInTheDocument();
+    expect(screen.queryByText("Start Codex session")).toBeNull();
+    expect(
+      within(screen.getByRole("button", { name: "Codex" })).getByText("Start new session")
+    ).toBeInTheDocument();
   });
 
   it("renders session state in the mobile agent list", () => {
diff --git a/packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.tsx b/packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.tsx
index ae33ba8b9..4e47f82a6 100644
--- a/packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.tsx
+++ b/packages/web/src/features/workspace/views/mobile/mobile-agent-sheet.tsx
@@ -27,11 +27,6 @@ interface MobileAgentSheetProps {
 
 type AgentSheetMode = "sessions" | "providers";
 
-const PROVIDER_ICON_SEMANTICS = {
-  claude: "agent.provider.claude",
-  codex: "agent.provider.codex",
-} as const;
-
 function formatSessionLabel(session: Session) {
   if (session.title?.trim()) {
     return session.title.trim();
@@ -68,15 +63,35 @@ function formatProviderLabel(provider: Pick<ProviderListItem, "badge" | "display
   return provider.badge || provider.displayName || provider.id;
 }
 
-function renderProviderIcon(provider: ProviderListItem) {
-  const semantic = PROVIDER_ICON_SEMANTICS[provider.id as keyof typeof PROVIDER_ICON_SEMANTICS];
-  if (semantic) {
-    return <ThemedIcon semantic={semantic} size={16} />;
+function formatProviderMonogram(provider: Pick<ProviderListItem, "badge" | "displayName" | "id">) {
+  const label = formatProviderLabel(provider).trim();
+  const monogramSource = label || provider.id;
+  return monogramSource.slice(0, 2).toUpperCase();
+}
+
+const knownProviderIconClasses = new Set(["claude", "codex", "gemini", "cursor", "opencode"]);
+const fallbackProviderTones = ["accent", "info", "success", "warning"] as const;
+
+function getProviderFallbackToneClass(providerId: string) {
+  if (knownProviderIconClasses.has(providerId)) {
+    return "";
   }
 
+  const toneIndex =
+    Array.from(providerId).reduce((sum, char) => sum + char.charCodeAt(0), 0) %
+    fallbackProviderTones.length;
+
+  return `mobile-agent-provider-icon--tone-${fallbackProviderTones[toneIndex]}`;
+}
+
+function renderProviderIcon(provider: ProviderListItem) {
+  const fallbackToneClass = getProviderFallbackToneClass(provider.id);
   return (
-    <span aria-hidden="true" className="agent-provider-card-monogram">
-      {formatProviderLabel(provider).slice(0, 2).toUpperCase()}
+    <span
+      aria-hidden="true"
+      className={`mobile-agent-provider-icon mobile-agent-provider-icon--${provider.id}${fallbackToneClass ? ` ${fallbackToneClass}` : ""}`}
+    >
+      <span className="mobile-agent-provider-icon__label">{formatProviderMonogram(provider)}</span>
     </span>
   );
 }
@@ -191,7 +206,7 @@ export function MobileAgentSheet({
           {
             id: provider.id,
             label,
-            description: guideMessage || t("mobile.agent.start_session", { provider: label }),
+            description: guideMessage || undefined,
             meta: busy ? t("mobile.agent.starting") : t("mobile.agent.start_new_session"),
             icon: renderProviderIcon(provider),
             disabled: !canLaunchSession || busy,
@@ -220,7 +235,7 @@ export function MobileAgentSheet({
 
   return (
     <MobileSelectSheet
-      className="mobile-select-sheet--command"
+      className="mobile-select-sheet--command mobile-agent-sheet--providers"
       title={mode === "sessions" ? t("mobile.agent.title") : t("session.provider_select")}
       sections={mode === "sessions" ? sessionSections : providerSections}
       selectedId={mode === "sessions" ? (activeSession?.id ?? null) : null}
diff --git a/packages/web/src/features/workspace/views/mobile/mobile-explorer-panel.test.tsx b/packages/web/src/features/workspace/views/mobile/mobile-explorer-panel.test.tsx
index 6769a4fc8..95f02c5b4 100644
--- a/packages/web/src/features/workspace/views/mobile/mobile-explorer-panel.test.tsx
+++ b/packages/web/src/features/workspace/views/mobile/mobile-explorer-panel.test.tsx
@@ -16,6 +16,8 @@ vi.mock("../../../../lib/i18n", () => ({
       "workspace.quick_jump.placeholder": "Type a filename or path",
       "workspace.quick_jump.no_results": "No results",
       "workspace.quick_jump.failed": "Search failed",
+      "workspace.quick_jump.expand_label": "Expand Quick Jump",
+      "workspace.quick_jump.collapse_label": "Collapse Quick Jump",
       "workspace.sidebar.workspace": "Workspace",
       "workspace.sidebar.workspace_expand_label": "Expand Workspace",
       "workspace.sidebar.workspace_collapse_label": "Collapse Workspace",
@@ -218,6 +220,38 @@ describe("MobileExplorerPanel", () => {
     expect(onSelectFile).not.toHaveBeenCalled();
   });
 
+  it("allows the Quick Jump section to collapse and expand", () => {
+    const store = createStore();
+    store.set(fileTreeAtomFamily("ws-test"), new Map([[".", []]]));
+    store.set(openFilesAtomFamily("ws-test"), {});
+
+    render(
+      <Provider store={store}>
+        <MobileExplorerPanel workspaceId="ws-test" routeToDetail={vi.fn()} collapseVersion={0} />
+      </Provider>
+    );
+
+    const quickJumpSection = screen
+      .getByRole("heading", { level: 2, name: /Quick Jump|快速跳转/i })
+      .closest("section") as HTMLElement;
+
+    expect(
+      within(quickJumpSection).getByPlaceholderText(/Type a filename or path|输入文件名或路径/i)
+    ).toBeInTheDocument();
+
+    fireEvent.click(within(quickJumpSection).getByRole("button", { name: "Collapse Quick Jump" }));
+
+    expect(
+      within(quickJumpSection).queryByPlaceholderText(/Type a filename or path|输入文件名或路径/i)
+    ).toBeNull();
+
+    fireEvent.click(within(quickJumpSection).getByRole("button", { name: "Expand Quick Jump" }));
+
+    expect(
+      within(quickJumpSection).getByPlaceholderText(/Type a filename or path|输入文件名或路径/i)
+    ).toBeInTheDocument();
+  });
+
   it("renders workspace actions inside the Workspace section and wires mobile callbacks", () => {
     const onOpenFileCreate = vi.fn();
     const onOpenFolderCreate = vi.fn();
diff --git a/packages/web/src/features/workspace/views/mobile/mobile-topbar.tsx b/packages/web/src/features/workspace/views/mobile/mobile-topbar.tsx
index d9ab43e15..7d335d5b5 100644
--- a/packages/web/src/features/workspace/views/mobile/mobile-topbar.tsx
+++ b/packages/web/src/features/workspace/views/mobile/mobile-topbar.tsx
@@ -11,6 +11,8 @@ interface MobileTopBarProps {
   activeWorkspace: Workspace | null;
   drawerOpen: boolean;
   fullscreenController?: WorkspaceFullscreenController;
+  onOpenFiles: () => void;
+  onOpenTerminal: () => void;
   onToggleDrawer: () => void;
 }
 
@@ -18,6 +20,8 @@ export function MobileTopBar({
   activeWorkspace,
   drawerOpen,
   fullscreenController,
+  onOpenFiles,
+  onOpenTerminal,
   onToggleDrawer,
 }: MobileTopBarProps) {
   const t = useTranslation();
@@ -43,6 +47,18 @@ export function MobileTopBar({
       </button>
 
       <div className="mobile-topbar__actions">
+        <IconButton
+          onClick={onOpenFiles}
+          aria-label={t("mobile.dock.open_files")}
+          className="mobile-topbar__icon-button"
+          icon={<ThemedIcon semantic="mobile.dock.files" size={18} />}
+        />
+        <IconButton
+          onClick={onOpenTerminal}
+          aria-label={t("mobile.dock.open_terminal")}
+          className="mobile-topbar__icon-button"
+          icon={<ThemedIcon semantic="mobile.dock.terminal" size={18} />}
+        />
         <IconButton
           aria-label={t("more.title")}
           className="mobile-topbar__icon-button"
diff --git a/packages/web/src/features/workspace/views/mobile/mobile-workspace-drawer.test.tsx b/packages/web/src/features/workspace/views/mobile/mobile-workspace-drawer.test.tsx
index 85f9667e4..85ab7d480 100644
--- a/packages/web/src/features/workspace/views/mobile/mobile-workspace-drawer.test.tsx
+++ b/packages/web/src/features/workspace/views/mobile/mobile-workspace-drawer.test.tsx
@@ -1,22 +1,14 @@
-import { render, screen, waitFor } from "@testing-library/react";
+import { render, screen, waitFor, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { createStore, Provider } from "jotai";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { lastViewedTargetAtom, localeAtom } from "../../../../atoms/app-ui";
 import { wsClientAtom } from "../../../../atoms/connection";
+import { activeWorkspaceIdAtom } from "../../../../atoms/workspaces";
 import { MobileWorkspaceDrawer } from "./mobile-workspace-drawer";
 
-const navigateMock = vi.fn();
 const closeWorkspaceMock = vi.fn();
 
-vi.mock("react-router-dom", async () => {
-  const actual = await vi.importActual<typeof import("react-router-dom")>("react-router-dom");
-  return {
-    ...actual,
-    useNavigate: () => navigateMock,
-  };
-});
-
 vi.mock("../../actions/use-workspace-close-action", () => ({
   useWorkspaceCloseAction: () => closeWorkspaceMock,
 }));
@@ -32,14 +24,38 @@ vi.mock("../../../../lib/i18n", () => ({
         return "Workspace";
       case "mobile.workspace_drawer.select_title":
         return "Select Workspace";
+      case "mobile.workspace_drawer.expand_workspace":
+        return `Expand ${params?.name ?? ""}`;
+      case "mobile.workspace_drawer.collapse_workspace":
+        return `Collapse ${params?.name ?? ""}`;
       case "mobile.workspace_drawer.switch_to_workspace":
         return `Switch to ${params?.name ?? ""}`;
       case "mobile.workspace_drawer.close_workspace":
         return `Close ${params?.name ?? ""}`;
+      case "mobile.workspace_drawer.current_workspace":
+        return `Translated current workspace ${params?.name ?? ""}`;
+      case "mobile.workspace_drawer.create_session_in_workspace":
+        return `Translated create session in ${params?.name ?? ""}`;
       case "worktree.current":
         return "Current";
       case "action.close":
         return "Close";
+      case "action.create_session":
+        return "Create session";
+      case "mobile.agent.switch_to_agent":
+        return `Switch to agent ${params?.name ?? ""}`;
+      case "mobile.agent.empty":
+        return "No active sessions";
+      case "mobile.agent.close_current_session":
+        return "Close Current Session";
+      case "status.starting":
+        return "Starting";
+      case "status.running":
+        return "Running";
+      case "status.idle":
+        return "Idle";
+      case "status.ended":
+        return "Ended";
       case "tooltip.new_workspace":
         return "New Workspace";
       default:
@@ -63,9 +79,13 @@ describe("MobileWorkspaceDrawer", () => {
       <Provider store={store}>
         <MobileWorkspaceDrawer
           activeWorkspaceId="ws-1"
+          activeSessionId={null}
           isOpen
           onClose={onClose}
+          onCreateSession={vi.fn()}
           onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{}}
           workspaces={[
             {
               id: "ws-1",
@@ -89,7 +109,7 @@ describe("MobileWorkspaceDrawer", () => {
     expect(closeButton).toHaveClass(
       "btn",
       "btn-ghost",
-      "btn-lg",
+      "btn-sm",
       "mobile-workspace-drawer__item-close"
     );
 
@@ -110,9 +130,13 @@ describe("MobileWorkspaceDrawer", () => {
       <Provider store={store}>
         <MobileWorkspaceDrawer
           activeWorkspaceId="ws-1"
+          activeSessionId={null}
           isOpen
           onClose={onClose}
+          onCreateSession={vi.fn()}
           onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{}}
           workspaces={[
             {
               id: "ws-1",
@@ -134,6 +158,8 @@ describe("MobileWorkspaceDrawer", () => {
     const dismissButton = screen.getByRole("button", { name: "Close" });
 
     expect(dismissButton).toHaveClass("mobile-workspace-drawer__dismiss");
+    expect(screen.queryByText("Select Workspace")).not.toBeInTheDocument();
+    expect(screen.getByText("Workspace")).toHaveClass("mobile-workspace-drawer__kicker");
 
     await user.click(dismissButton);
 
@@ -147,9 +173,13 @@ describe("MobileWorkspaceDrawer", () => {
       <Provider store={store}>
         <MobileWorkspaceDrawer
           activeWorkspaceId="ws-1"
+          activeSessionId={null}
           isOpen
           onClose={vi.fn()}
+          onCreateSession={vi.fn()}
           onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{}}
           workspaces={[
             {
               id: "ws-1",
@@ -180,23 +210,19 @@ describe("MobileWorkspaceDrawer", () => {
       </Provider>
     );
 
-    expect(screen.getByRole("button", { name: "Switch to demo" })).toHaveAttribute(
+    expect(screen.getByRole("button", { name: "Collapse demo" })).toHaveAttribute(
       "aria-current",
       "page"
     );
-    expect(screen.getByText("Current")).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "Switch to other" })).not.toHaveAttribute(
+    expect(screen.getByRole("button", { name: "Expand other" })).not.toHaveAttribute(
       "aria-current"
     );
   });
 
-  it("persists a workspace-only target when the mobile drawer switches workspace", async () => {
+  it("toggles a non-active workspace subtree without collapsing other expanded workspaces", async () => {
     const user = userEvent.setup();
     const onClose = vi.fn();
-    const sendCommand = vi.fn().mockResolvedValue({
-      workspaceId: "ws-2",
-      updatedAt: 10,
-    });
+    const sendCommand = vi.fn();
     const store = createStore();
     store.set(localeAtom, "en");
     store.set(wsClientAtom, { sendCommand } as never);
@@ -209,9 +235,32 @@ describe("MobileWorkspaceDrawer", () => {
       <Provider store={store}>
         <MobileWorkspaceDrawer
           activeWorkspaceId="ws-1"
+          activeSessionId={null}
           isOpen
           onClose={onClose}
+          onCreateSession={vi.fn()}
           onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{
+            "ws-1": [
+              {
+                id: "sess-1",
+                workspaceId: "ws-1",
+                providerId: "claude",
+                title: "Claude Repair CI",
+                state: "running",
+              },
+            ],
+            "ws-2": [
+              {
+                id: "sess-9",
+                workspaceId: "ws-2",
+                providerId: "gemini",
+                title: "Gemini Sandbox",
+                state: "running",
+              },
+            ],
+          }}
           workspaces={[
             {
               id: "ws-1",
@@ -242,15 +291,24 @@ describe("MobileWorkspaceDrawer", () => {
       </Provider>
     );
 
-    await user.click(screen.getByRole("button", { name: "Switch to other" }));
+    expect(screen.getByText("Claude Repair CI")).toBeInTheDocument();
 
-    await waitFor(() => {
-      expect(sendCommand).toHaveBeenCalledWith(
-        "workspace.lastViewedTarget.set",
-        { workspaceId: "ws-2", sessionId: undefined },
-        undefined
-      );
-    });
+    await user.click(screen.getByRole("button", { name: "Expand other" }));
+
+    expect(sendCommand).not.toHaveBeenCalledWith(
+      "workspace.lastViewedTarget.set",
+      expect.anything(),
+      undefined
+    );
+    expect(onClose).not.toHaveBeenCalled();
+    expect(screen.getByRole("button", { name: "Collapse demo" })).toBeInTheDocument();
+    expect(screen.getByText("Claude Repair CI")).toBeInTheDocument();
+    expect(screen.getByText("Gemini Sandbox")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Collapse other" }));
+
+    expect(screen.getByText("Claude Repair CI")).toBeInTheDocument();
+    expect(screen.queryByText("Gemini Sandbox")).not.toBeInTheDocument();
   });
 
   it("does not persist again when the mobile drawer clicks the active workspace", async () => {
@@ -265,9 +323,13 @@ describe("MobileWorkspaceDrawer", () => {
       <Provider store={store}>
         <MobileWorkspaceDrawer
           activeWorkspaceId="ws-1"
+          activeSessionId={null}
           isOpen
           onClose={onClose}
+          onCreateSession={vi.fn()}
           onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{}}
           workspaces={[
             {
               id: "ws-1",
@@ -286,7 +348,7 @@ describe("MobileWorkspaceDrawer", () => {
       </Provider>
     );
 
-    await user.click(screen.getByRole("button", { name: "Switch to demo" }));
+    await user.click(screen.getByRole("button", { name: "Collapse demo" }));
 
     expect(sendCommand).not.toHaveBeenCalledWith(
       "workspace.lastViewedTarget.set",
@@ -295,6 +357,512 @@ describe("MobileWorkspaceDrawer", () => {
     );
   });
 
+  it("renders the active workspace as expanded by default and shows its agent rows with provider state meta", () => {
+    const store = createStore();
+
+    render(
+      <Provider store={store}>
+        <MobileWorkspaceDrawer
+          activeWorkspaceId="ws-1"
+          activeSessionId="sess-2"
+          isOpen
+          onClose={vi.fn()}
+          onCreateSession={vi.fn()}
+          onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{
+            "ws-1": [
+              {
+                id: "sess-1",
+                workspaceId: "ws-1",
+                providerId: "claude",
+                title: "Claude Repair CI",
+                state: "running",
+              },
+              {
+                id: "sess-2",
+                workspaceId: "ws-1",
+                providerId: "codex",
+                title: "Codex Mobile Layout",
+                state: "idle",
+              },
+            ],
+            "ws-2": [
+              {
+                id: "sess-9",
+                workspaceId: "ws-2",
+                providerId: "gemini",
+                title: "Gemini Sandbox",
+                state: "running",
+              },
+            ],
+          }}
+          workspaces={[
+            {
+              id: "ws-1",
+              path: "/tmp/demo",
+              targetRuntime: "native",
+              openedAt: 1,
+              lastActiveAt: 1,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+            {
+              id: "ws-2",
+              path: "/tmp/other",
+              targetRuntime: "native",
+              openedAt: 2,
+              lastActiveAt: 2,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+          ]}
+        />
+      </Provider>
+    );
+
+    expect(screen.getByText("Codex Mobile Layout")).toBeInTheDocument();
+    expect(screen.getByText("CODEX · Idle")).toBeInTheDocument();
+    expect(screen.queryByText("Gemini Sandbox")).not.toBeInTheDocument();
+  });
+
+  it("switches workspace only when a session row is pressed", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    const onSelectSession = vi.fn();
+    const sendCommand = vi.fn().mockResolvedValue({
+      workspaceId: "ws-2",
+      sessionId: "sess-9",
+      updatedAt: 10,
+    });
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+    store.set(activeWorkspaceIdAtom, "ws-1");
+
+    render(
+      <Provider store={store}>
+        <MobileWorkspaceDrawer
+          activeWorkspaceId="ws-1"
+          activeSessionId="sess-1"
+          isOpen
+          onClose={onClose}
+          onCreateSession={vi.fn()}
+          onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={onSelectSession}
+          sessionsByWorkspaceId={{
+            "ws-1": [
+              {
+                id: "sess-1",
+                workspaceId: "ws-1",
+                providerId: "claude",
+                title: "Claude Repair CI",
+                state: "running",
+              },
+              {
+                id: "sess-2",
+                workspaceId: "ws-1",
+                providerId: "codex",
+                title: "Codex Mobile Layout",
+                state: "idle",
+              },
+            ],
+            "ws-2": [
+              {
+                id: "sess-9",
+                workspaceId: "ws-2",
+                providerId: "gemini",
+                title: "Gemini Sandbox",
+                state: "running",
+              },
+            ],
+          }}
+          workspaces={[
+            {
+              id: "ws-1",
+              path: "/tmp/demo",
+              targetRuntime: "native",
+              openedAt: 1,
+              lastActiveAt: 1,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+            {
+              id: "ws-2",
+              path: "/tmp/other",
+              targetRuntime: "native",
+              openedAt: 2,
+              lastActiveAt: 2,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+          ]}
+        />
+      </Provider>
+    );
+
+    await user.click(screen.getByRole("button", { name: "Expand other" }));
+    await user.click(screen.getByRole("button", { name: "Switch to agent Gemini Sandbox" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "workspace.lastViewedTarget.set",
+        { workspaceId: "ws-2", sessionId: "sess-9" },
+        undefined
+      );
+    });
+    expect(store.get(activeWorkspaceIdAtom)).toBe("ws-2");
+    expect(onSelectSession).not.toHaveBeenCalled();
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("toggles the active workspace subtree when its header is pressed", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+
+    render(
+      <Provider store={createStore()}>
+        <MobileWorkspaceDrawer
+          activeWorkspaceId="ws-1"
+          activeSessionId={null}
+          isOpen
+          onClose={onClose}
+          onCreateSession={vi.fn()}
+          onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{
+            "ws-1": [
+              {
+                id: "sess-1",
+                workspaceId: "ws-1",
+                providerId: "claude",
+                title: "Claude Repair CI",
+                state: "running",
+              },
+            ],
+          }}
+          workspaces={[
+            {
+              id: "ws-1",
+              path: "/tmp/demo",
+              targetRuntime: "native",
+              openedAt: 1,
+              lastActiveAt: 1,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+          ]}
+        />
+      </Provider>
+    );
+
+    expect(screen.getByText("Claude Repair CI")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Collapse demo" }));
+
+    expect(screen.queryByText("Claude Repair CI")).not.toBeInTheDocument();
+    expect(onClose).not.toHaveBeenCalled();
+
+    await user.click(screen.getByRole("button", { name: "Expand demo" }));
+
+    expect(screen.getByText("Claude Repair CI")).toBeInTheDocument();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("renders the create-session button beside the workspace close button for the active workspace", async () => {
+    const user = userEvent.setup();
+    const onCreateSession = vi.fn();
+
+    render(
+      <Provider store={createStore()}>
+        <MobileWorkspaceDrawer
+          activeWorkspaceId="ws-1"
+          activeSessionId={null}
+          isOpen
+          onClose={vi.fn()}
+          onCreateSession={onCreateSession}
+          onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{
+            "ws-1": [
+              {
+                id: "sess-1",
+                workspaceId: "ws-1",
+                providerId: "claude",
+                title: "Claude Repair CI",
+                state: "running",
+              },
+              {
+                id: "sess-2",
+                workspaceId: "ws-1",
+                providerId: "codex",
+                title: "Codex Mobile Layout",
+                state: "idle",
+              },
+            ],
+          }}
+          workspaces={[
+            {
+              id: "ws-1",
+              path: "/tmp/demo",
+              targetRuntime: "native",
+              openedAt: 1,
+              lastActiveAt: 1,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+          ]}
+        />
+      </Provider>
+    );
+
+    const activeWorkspaceItem = screen
+      .getByRole("button", { name: "Collapse demo" })
+      .closest(".mobile-workspace-drawer__item");
+
+    expect(activeWorkspaceItem).not.toBeNull();
+    expect(
+      within(activeWorkspaceItem as HTMLElement).getByRole("button", {
+        name: "Translated create session in demo",
+      })
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Switch to agent Claude Repair CI" })
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Switch to agent Codex Mobile Layout" })
+    ).toBeInTheDocument();
+    expect(screen.getAllByRole("button", { name: "Close Current Session" })).toHaveLength(2);
+
+    await user.click(screen.getByRole("button", { name: "Translated create session in demo" }));
+
+    expect(onCreateSession).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not render a create-session button for a non-active workspace", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Provider store={createStore()}>
+        <MobileWorkspaceDrawer
+          activeWorkspaceId="ws-1"
+          activeSessionId={null}
+          isOpen
+          onClose={vi.fn()}
+          onCreateSession={vi.fn()}
+          onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{
+            "ws-1": [],
+            "ws-2": [
+              {
+                id: "sess-9",
+                workspaceId: "ws-2",
+                providerId: "gemini",
+                title: "Gemini Sandbox",
+                state: "running",
+              },
+            ],
+          }}
+          workspaces={[
+            {
+              id: "ws-1",
+              path: "/tmp/demo",
+              targetRuntime: "native",
+              openedAt: 1,
+              lastActiveAt: 1,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+            {
+              id: "ws-2",
+              path: "/tmp/other",
+              targetRuntime: "native",
+              openedAt: 2,
+              lastActiveAt: 2,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+          ]}
+        />
+      </Provider>
+    );
+
+    await user.click(screen.getByRole("button", { name: "Expand other" }));
+
+    expect(
+      screen.queryByRole("button", { name: "Translated create session in other" })
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders an empty-state action for an expanded workspace with no sessions and switches on click", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    const sendCommand = vi.fn().mockResolvedValue({
+      workspaceId: "ws-2",
+      updatedAt: 10,
+    });
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+    store.set(activeWorkspaceIdAtom, "ws-1");
+
+    render(
+      <Provider store={store}>
+        <MobileWorkspaceDrawer
+          activeWorkspaceId="ws-1"
+          activeSessionId={null}
+          isOpen
+          onClose={onClose}
+          onCreateSession={vi.fn()}
+          onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{
+            "ws-1": [
+              {
+                id: "sess-1",
+                workspaceId: "ws-1",
+                providerId: "claude",
+                title: "Claude Repair CI",
+                state: "running",
+              },
+            ],
+            "ws-2": [],
+          }}
+          workspaces={[
+            {
+              id: "ws-1",
+              path: "/tmp/demo",
+              targetRuntime: "native",
+              openedAt: 1,
+              lastActiveAt: 1,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+            {
+              id: "ws-2",
+              path: "/tmp/other",
+              targetRuntime: "native",
+              openedAt: 2,
+              lastActiveAt: 2,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+          ]}
+        />
+      </Provider>
+    );
+
+    await user.click(screen.getByRole("button", { name: "Expand other" }));
+
+    expect(screen.getByText("No active sessions")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Switch to other" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "workspace.lastViewedTarget.set",
+        { workspaceId: "ws-2", sessionId: undefined },
+        undefined
+      );
+    });
+    expect(store.get(activeWorkspaceIdAtom)).toBe("ws-2");
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders the empty-state action for the active workspace without switching again", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    const sendCommand = vi.fn();
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+
+    render(
+      <Provider store={store}>
+        <MobileWorkspaceDrawer
+          activeWorkspaceId="ws-1"
+          activeSessionId={null}
+          isOpen
+          onClose={onClose}
+          onCreateSession={vi.fn()}
+          onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{ "ws-1": [] }}
+          workspaces={[
+            {
+              id: "ws-1",
+              path: "/tmp/demo",
+              targetRuntime: "native",
+              openedAt: 1,
+              lastActiveAt: 1,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+          ]}
+        />
+      </Provider>
+    );
+
+    expect(screen.getByText("No active sessions")).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: "Switch to demo" }));
+
+    expect(sendCommand).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("closes a session from the active workspace subtree and dismisses the drawer", async () => {
+    const user = userEvent.setup();
+    const onClose = vi.fn();
+    const onCloseSession = vi.fn().mockResolvedValue(undefined);
+
+    render(
+      <Provider store={createStore()}>
+        <MobileWorkspaceDrawer
+          activeWorkspaceId="ws-1"
+          activeSessionId="sess-2"
+          isOpen
+          onClose={onClose}
+          onCloseSession={onCloseSession}
+          onCreateSession={vi.fn()}
+          onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{
+            "ws-1": [
+              {
+                id: "sess-1",
+                workspaceId: "ws-1",
+                providerId: "claude",
+                title: "Claude Repair CI",
+                state: "running",
+              },
+              {
+                id: "sess-2",
+                workspaceId: "ws-1",
+                providerId: "codex",
+                title: "Codex Mobile Layout",
+                state: "idle",
+              },
+            ],
+          }}
+          workspaces={[
+            {
+              id: "ws-1",
+              path: "/tmp/demo",
+              targetRuntime: "native",
+              openedAt: 1,
+              lastActiveAt: 1,
+              uiState: { leftPanelWidth: 320, bottomPanelHeight: 240, focusMode: false },
+            },
+          ]}
+        />
+      </Provider>
+    );
+
+    const activeRow = screen
+      .getByRole("button", { name: "Switch to agent Codex Mobile Layout" })
+      .closest(".mobile-workspace-drawer__child-session-row");
+
+    expect(activeRow).not.toBeNull();
+
+    await user.click(
+      within(activeRow as HTMLElement).getByRole("button", { name: "Close Current Session" })
+    );
+
+    expect(onCloseSession).toHaveBeenCalledWith("sess-2");
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
   it("renders the footer launch action with the new workspace semantic icon", () => {
     const store = createStore();
 
@@ -302,9 +870,13 @@ describe("MobileWorkspaceDrawer", () => {
       <Provider store={store}>
         <MobileWorkspaceDrawer
           activeWorkspaceId="ws-1"
+          activeSessionId={null}
           isOpen
           onClose={vi.fn()}
+          onCreateSession={vi.fn()}
           onOpenWorkspaceLauncher={vi.fn()}
+          onSelectSession={vi.fn()}
+          sessionsByWorkspaceId={{}}
           workspaces={[
             {
               id: "ws-1",
diff --git a/packages/web/src/features/workspace/views/mobile/mobile-workspace-drawer.tsx b/packages/web/src/features/workspace/views/mobile/mobile-workspace-drawer.tsx
index 6be734e70..386d4988b 100644
--- a/packages/web/src/features/workspace/views/mobile/mobile-workspace-drawer.tsx
+++ b/packages/web/src/features/workspace/views/mobile/mobile-workspace-drawer.tsx
@@ -1,7 +1,7 @@
-import type { Workspace } from "@coder-studio/core";
+import type { Session, Workspace } from "@coder-studio/core";
 import { useSetAtom } from "jotai";
-import { Check, X } from "lucide-react";
-import { useNavigate } from "react-router-dom";
+import { X } from "lucide-react";
+import { useEffect, useState } from "react";
 import { activeWorkspaceIdAtom } from "../../../../atoms/workspaces";
 import { IconButton, ThemedIcon } from "../../../../components/ui";
 import { useTranslation } from "../../../../lib/i18n";
@@ -9,26 +9,97 @@ import { formatWorkspaceLabel } from "../../../notifications/format";
 import { usePersistWorkspaceLastViewedTarget } from "../../actions/use-persist-workspace-last-viewed-target";
 import { useWorkspaceCloseAction } from "../../actions/use-workspace-close-action";
 
+interface MobileWorkspaceDrawerSessionItem {
+  id: string;
+  workspaceId: string;
+  providerId: string;
+  title?: string;
+  state: Session["state"];
+}
+
 interface MobileWorkspaceDrawerProps {
   activeWorkspaceId: string | null;
+  activeSessionId?: string | null;
   isOpen: boolean;
+  sessionsByWorkspaceId?: Record<string, MobileWorkspaceDrawerSessionItem[]>;
   workspaces: Workspace[];
   onClose: () => void;
+  onCloseSession?: (sessionId: string) => Promise<void>;
+  onCreateSession?: () => void;
   onOpenWorkspaceLauncher: () => void;
+  onSelectSession?: (sessionId: string) => void;
+}
+
+function formatDrawerSessionLabel(session: MobileWorkspaceDrawerSessionItem) {
+  if (session.title?.trim()) {
+    return session.title.trim();
+  }
+
+  if (session.providerId) {
+    return session.providerId.replace(/\b\w/g, (char) => char.toUpperCase());
+  }
+
+  const numericId = session.id.match(/(\d+)/)?.[1];
+  if (numericId) {
+    return `SESSION-${numericId.slice(-2).padStart(2, "0")}`;
+  }
+
+  return session.id.replace(/[_-]/g, " ").toUpperCase();
+}
+
+function formatDrawerSessionStateLabel(
+  state: Session["state"],
+  t: ReturnType<typeof useTranslation>
+) {
+  switch (state) {
+    case "starting":
+      return t("status.starting");
+    case "running":
+      return t("status.running");
+    case "idle":
+      return t("status.idle");
+    case "ended":
+      return t("status.ended");
+    default:
+      return state;
+  }
 }
 
 export function MobileWorkspaceDrawer({
   activeWorkspaceId,
+  activeSessionId,
   isOpen,
+  sessionsByWorkspaceId = {},
   workspaces,
   onClose,
+  onCloseSession = async () => {},
+  onCreateSession = () => {},
   onOpenWorkspaceLauncher,
+  onSelectSession = () => {},
 }: MobileWorkspaceDrawerProps) {
-  const navigate = useNavigate();
   const setActiveWorkspaceId = useSetAtom(activeWorkspaceIdAtom);
   const t = useTranslation();
   const closeWorkspace = useWorkspaceCloseAction();
   const persistLastViewedTarget = usePersistWorkspaceLastViewedTarget();
+  const [expandedWorkspaceIds, setExpandedWorkspaceIds] = useState<Set<string>>(
+    () => new Set(activeWorkspaceId ? [activeWorkspaceId] : [])
+  );
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    setExpandedWorkspaceIds((currentExpandedWorkspaceIds) => {
+      if (!activeWorkspaceId || currentExpandedWorkspaceIds.has(activeWorkspaceId)) {
+        return currentExpandedWorkspaceIds;
+      }
+
+      const nextExpandedWorkspaceIds = new Set(currentExpandedWorkspaceIds);
+      nextExpandedWorkspaceIds.add(activeWorkspaceId);
+      return nextExpandedWorkspaceIds;
+    });
+  }, [activeWorkspaceId, isOpen]);
 
   if (!isOpen) {
     return null;
@@ -49,9 +120,6 @@ export function MobileWorkspaceDrawer({
         <div className="mobile-workspace-drawer__header">
           <div className="mobile-workspace-drawer__header-copy">
             <div className="mobile-workspace-drawer__kicker">{t("label.workspace")}</div>
-            <h2 className="mobile-workspace-drawer__title">
-              {t("mobile.workspace_drawer.select_title")}
-            </h2>
           </div>
           <IconButton
             aria-label={t("action.close")}
@@ -66,6 +134,8 @@ export function MobileWorkspaceDrawer({
           {workspaces.map((workspace) => {
             const displayName = formatWorkspaceLabel(workspace) || workspace.id;
             const isActive = workspace.id === activeWorkspaceId;
+            const isExpanded = expandedWorkspaceIds.has(workspace.id);
+            const workspaceSessions = sessionsByWorkspaceId[workspace.id] ?? [];
 
             return (
               <div
@@ -78,48 +148,153 @@ export function MobileWorkspaceDrawer({
                   type="button"
                   className="mobile-workspace-drawer__item-main"
                   aria-current={isActive ? "page" : undefined}
-                  aria-label={t("mobile.workspace_drawer.switch_to_workspace", {
-                    name: displayName,
-                  })}
-                  onClick={() => {
-                    if (isActive) {
-                      navigate("/workspace");
-                      onClose();
-                      return;
-                    }
-
-                    void persistLastViewedTarget({ workspaceId: workspace.id });
-                    setActiveWorkspaceId(workspace.id);
-                    navigate("/workspace");
-                    onClose();
-                  }}
+                  aria-expanded={isExpanded}
+                  aria-label={
+                    isExpanded
+                      ? t("mobile.workspace_drawer.collapse_workspace", {
+                          name: displayName,
+                        })
+                      : t("mobile.workspace_drawer.expand_workspace", {
+                          name: displayName,
+                        })
+                  }
+                  onClick={() =>
+                    setExpandedWorkspaceIds((currentExpandedWorkspaceIds) => {
+                      const nextExpandedWorkspaceIds = new Set(currentExpandedWorkspaceIds);
+
+                      if (nextExpandedWorkspaceIds.has(workspace.id)) {
+                        nextExpandedWorkspaceIds.delete(workspace.id);
+                      } else {
+                        nextExpandedWorkspaceIds.add(workspace.id);
+                      }
+
+                      return nextExpandedWorkspaceIds;
+                    })
+                  }
                 >
                   <span className="mobile-workspace-drawer__item-name-row">
                     <span className="mobile-workspace-drawer__item-name">{displayName}</span>
-                    {isActive ? (
-                      <span className="mobile-workspace-drawer__item-state">
-                        <Check size={12} />
-                        <span>{t("worktree.current")}</span>
-                      </span>
-                    ) : null}
                   </span>
                   <span className="mobile-workspace-drawer__item-path">{workspace.path}</span>
                 </button>
-                <IconButton
-                  aria-label={t("mobile.workspace_drawer.close_workspace", { name: displayName })}
-                  className="mobile-workspace-drawer__item-close"
-                  icon={<X size={16} />}
-                  onClick={() => {
-                    void closeWorkspace(workspace.id, { navigateHomeWhenEmpty: true }).then(
-                      (closed) => {
-                        if (closed) {
-                          onClose();
+                <div className="mobile-workspace-drawer__item-actions">
+                  {isActive ? (
+                    <IconButton
+                      aria-label={t("mobile.workspace_drawer.create_session_in_workspace", {
+                        name: displayName,
+                      })}
+                      className="mobile-workspace-drawer__item-create"
+                      icon={<ThemedIcon semantic="agent.action.newSession" size={12} />}
+                      onClick={onCreateSession}
+                      size="sm"
+                    />
+                  ) : null}
+                  <IconButton
+                    aria-label={t("mobile.workspace_drawer.close_workspace", { name: displayName })}
+                    className="mobile-workspace-drawer__item-close"
+                    icon={<X size={14} />}
+                    onClick={() => {
+                      void closeWorkspace(workspace.id, { navigateHomeWhenEmpty: true }).then(
+                        (closed) => {
+                          if (closed) {
+                            onClose();
+                          }
                         }
-                      }
-                    );
-                  }}
-                  size="lg"
-                />
+                      );
+                    }}
+                    size="sm"
+                  />
+                </div>
+                {isExpanded ? (
+                  <div className="mobile-workspace-drawer__item-children">
+                    {workspaceSessions.length === 0 ? (
+                      <button
+                        type="button"
+                        className="mobile-workspace-drawer__child-empty"
+                        aria-label={t("mobile.workspace_drawer.switch_to_workspace", {
+                          name: displayName,
+                        })}
+                        onClick={() => {
+                          if (workspace.id === activeWorkspaceId) {
+                            return;
+                          }
+
+                          void persistLastViewedTarget({ workspaceId: workspace.id });
+                          setActiveWorkspaceId(workspace.id);
+                          onClose();
+                        }}
+                      >
+                        <span className="mobile-workspace-drawer__child-empty-title">
+                          {t("mobile.agent.empty")}
+                        </span>
+                        <span className="mobile-workspace-drawer__child-empty-hint">
+                          {t("mobile.workspace_drawer.switch_to_workspace", {
+                            name: displayName,
+                          })}
+                        </span>
+                      </button>
+                    ) : (
+                      workspaceSessions.map((session) => {
+                        const sessionLabel = formatDrawerSessionLabel(session);
+                        const isActiveSession = session.id === activeSessionId;
+
+                        return (
+                          <div
+                            key={session.id}
+                            className={`mobile-workspace-drawer__child-session-row ${
+                              isActiveSession
+                                ? "mobile-workspace-drawer__child-session-row--active"
+                                : ""
+                            }`}
+                          >
+                            <button
+                              type="button"
+                              className={`mobile-workspace-drawer__child-session ${
+                                isActiveSession
+                                  ? "mobile-workspace-drawer__child-session--active"
+                                  : ""
+                              }`}
+                              aria-current={isActiveSession ? "page" : undefined}
+                              aria-label={t("mobile.agent.switch_to_agent", { name: sessionLabel })}
+                              onClick={() => {
+                                void persistLastViewedTarget({
+                                  workspaceId: workspace.id,
+                                  sessionId: session.id,
+                                });
+                                if (workspace.id !== activeWorkspaceId) {
+                                  setActiveWorkspaceId(workspace.id);
+                                } else {
+                                  onSelectSession(session.id);
+                                }
+                                onClose();
+                              }}
+                            >
+                              <span className="mobile-workspace-drawer__child-session-label">
+                                {sessionLabel}
+                              </span>
+                              <span className="mobile-workspace-drawer__child-session-meta">
+                                {`${session.providerId.toUpperCase()} · ${formatDrawerSessionStateLabel(
+                                  session.state,
+                                  t
+                                )}`}
+                              </span>
+                            </button>
+                            <IconButton
+                              aria-label={t("mobile.agent.close_current_session")}
+                              className="mobile-workspace-drawer__child-session-close"
+                              icon={<X size={12} />}
+                              onClick={async () => {
+                                await onCloseSession(session.id);
+                                onClose();
+                              }}
+                              size="sm"
+                            />
+                          </div>
+                        );
+                      })
+                    )}
+                  </div>
+                ) : null}
               </div>
             );
           })}
diff --git a/packages/web/src/features/workspace/views/mobile/workspace-mobile-view.test.tsx b/packages/web/src/features/workspace/views/mobile/workspace-mobile-view.test.tsx
index 4a3be16a0..0c24563e7 100644
--- a/packages/web/src/features/workspace/views/mobile/workspace-mobile-view.test.tsx
+++ b/packages/web/src/features/workspace/views/mobile/workspace-mobile-view.test.tsx
@@ -1,12 +1,15 @@
 // @vitest-environment jsdom
 
+import type { Session } from "@coder-studio/core";
 import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { createStore, Provider } from "jotai";
 import { MemoryRouter } from "react-router-dom";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { connectionStatusAtom, wsClientAtom } from "../../../../atoms/connection";
+import { sessionsAtom } from "../../../../atoms/sessions";
 import { activeWorkspaceIdAtom } from "../../../../atoms/workspaces";
 import { seedReadyWorkspaceState } from "../../../../test-utils/workspace-state";
+import { paneLayoutAtomFamily } from "../../../agent-panes/atoms/pane-layout";
 import {
   activeFilePathAtomFamily,
   type GitDiffPreview,
@@ -199,7 +202,9 @@ vi.mock("../../../code-editor/actions/use-code-editor-actions", () => ({
 }));
 
 vi.mock("./mobile-agent-sheet", () => ({
-  MobileAgentSheet: () => <div data-testid="mobile-agent-sheet" />,
+  MobileAgentSheet: ({ defaultMode }: { defaultMode?: "create" | "list" }) => (
+    <div data-testid="mobile-agent-sheet" data-default-mode={defaultMode ?? ""} />
+  ),
 }));
 
 vi.mock("./mobile-dock", () => ({
@@ -261,13 +266,85 @@ vi.mock("./mobile-files-sheet", () => ({
 }));
 
 vi.mock("./mobile-topbar", () => ({
-  MobileTopBar: () => <div data-testid="mobile-topbar" />,
+  MobileTopBar: ({
+    onToggleDrawer,
+    onOpenFiles,
+    onOpenTerminal,
+  }: {
+    onToggleDrawer: () => void;
+    onOpenFiles?: () => void;
+    onOpenTerminal?: () => void;
+  }) => (
+    <div data-testid="mobile-topbar">
+      <button type="button" onClick={onToggleDrawer}>
+        Toggle drawer
+      </button>
+      <button type="button" onClick={onOpenFiles}>
+        Topbar files
+      </button>
+      <button type="button" onClick={onOpenTerminal}>
+        Topbar terminal
+      </button>
+    </div>
+  ),
 }));
 
 vi.mock("./mobile-workspace-drawer", () => ({
-  MobileWorkspaceDrawer: () => null,
+  MobileWorkspaceDrawer: ({
+    isOpen,
+    activeSessionId,
+    sessionsByWorkspaceId,
+    onCreateSession,
+    onSelectSession,
+  }: {
+    isOpen: boolean;
+    activeSessionId?: string | null;
+    sessionsByWorkspaceId?: Record<
+      string,
+      Array<{
+        id: string;
+        workspaceId: string;
+        providerId: string;
+        title?: string;
+        state: string;
+      }>
+    >;
+    onCreateSession?: () => void;
+    onSelectSession?: (sessionId: string) => void;
+  }) =>
+    isOpen ? (
+      <div data-testid="mobile-workspace-drawer">
+        <div data-testid="drawer-active-session">{activeSessionId ?? ""}</div>
+        <pre data-testid="drawer-sessions">{JSON.stringify(sessionsByWorkspaceId ?? {})}</pre>
+        <button type="button" onClick={onCreateSession}>
+          Drawer create session
+        </button>
+        <button type="button" onClick={() => onSelectSession?.("sess-2")}>
+          Drawer select sess-2
+        </button>
+      </div>
+    ) : null,
 }));
 
+function createSession(
+  partial: Partial<Session> & Pick<Session, "id" | "terminalId" | "providerId">
+): Session {
+  return {
+    id: partial.id,
+    workspaceId: partial.workspaceId ?? "ws-test",
+    terminalId: partial.terminalId,
+    providerId: partial.providerId,
+    state: partial.state ?? "idle",
+    capability: partial.capability ?? "full",
+    startedAt: partial.startedAt ?? Date.now() - 10_000,
+    lastActiveAt: partial.lastActiveAt ?? Date.now() - 1_000,
+    title: partial.title,
+    endedAt: partial.endedAt,
+    completionPercent: partial.completionPercent,
+    errorReason: partial.errorReason,
+  };
+}
+
 function createSendCommandMock() {
   return vi.fn().mockImplementation(async (op: string) => {
     if (op === "git.status") {
@@ -295,12 +372,33 @@ function renderMobileView(
     activePath: string | null;
     openFiles: Record<string, OpenFile>;
     diffPreview?: GitDiffPreview | null;
+    sessions?: Session[];
+    mobileActiveSessionId?: string | null;
   } = { activePath: null, openFiles: {} }
 ) {
   const store = createStore();
   currentStore = store;
   store.set(connectionStatusAtom, "connected");
-  store.set(wsClientAtom, { sendCommand: createSendCommandMock() } as never);
+  const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+    if (op === "git.status") {
+      return {
+        branch: "main",
+        ahead: 0,
+        behind: 0,
+        staged: [],
+        modified: [],
+        deleted: [],
+        untracked: [],
+      };
+    }
+
+    if (op === "session.list") {
+      return options.sessions ?? [];
+    }
+
+    return null;
+  });
+  store.set(wsClientAtom, { sendCommand } as never);
   seedReadyWorkspaceState(store, {
     "ws-test": {
       id: "ws-test",
@@ -312,6 +410,7 @@ function renderMobileView(
         leftPanelWidth: 280,
         bottomPanelHeight: 200,
         focusMode: false,
+        activeSessionId: options.mobileActiveSessionId ?? undefined,
       },
     },
   });
@@ -321,6 +420,18 @@ function renderMobileView(
   if (options.diffPreview !== undefined) {
     store.set(gitDiffPreviewAtomFamily("ws-test"), options.diffPreview as never);
   }
+  if (options.sessions) {
+    store.set(
+      sessionsAtom,
+      Object.fromEntries(options.sessions.map((session) => [session.id, session])) as never
+    );
+    store.set(paneLayoutAtomFamily("ws-test"), {
+      id: "mobile-root",
+      type: "leaf",
+      leafKind: "session",
+      sessionId: options.sessions[0]?.id,
+    } as never);
+  }
 
   render(
     <Provider store={store}>
@@ -366,7 +477,7 @@ describe("WorkspaceMobileView", () => {
       },
     });
 
-    fireEvent.click(screen.getByRole("button", { name: "Files" }));
+    fireEvent.click(screen.getByRole("button", { name: "Topbar files" }));
     fireEvent.click(screen.getByRole("button", { name: "Open a.ts" }));
 
     expect(screen.getByRole("heading", { level: 2, name: "a.ts" })).toBeInTheDocument();
@@ -395,7 +506,7 @@ describe("WorkspaceMobileView", () => {
       },
     });
 
-    fireEvent.click(screen.getByRole("button", { name: "Files" }));
+    fireEvent.click(screen.getByRole("button", { name: "Topbar files" }));
     fireEvent.click(screen.getByRole("button", { name: "Open a.ts" }));
 
     expect(screen.getByRole("heading", { level: 2, name: "a.ts" })).toBeInTheDocument();
@@ -443,7 +554,7 @@ describe("WorkspaceMobileView", () => {
       },
     });
 
-    fireEvent.click(screen.getByRole("button", { name: "Files" }));
+    fireEvent.click(screen.getByRole("button", { name: "Topbar files" }));
     fireEvent.click(screen.getByRole("button", { name: "Open commit preview" }));
 
     await waitFor(() => {
@@ -502,7 +613,7 @@ describe("WorkspaceMobileView", () => {
       diffPreview,
     });
 
-    fireEvent.click(screen.getByRole("button", { name: "Files" }));
+    fireEvent.click(screen.getByRole("button", { name: "Topbar files" }));
     expect(screen.queryByRole("heading", { level: 2, name: /Open Files|打开的文件/i })).toBeNull();
 
     act(() => {
@@ -540,13 +651,261 @@ describe("WorkspaceMobileView", () => {
       },
     });
 
-    fireEvent.click(screen.getByRole("button", { name: "Files" }));
+    fireEvent.click(screen.getByRole("button", { name: "Topbar files" }));
 
     expect(screen.getByTestId("mobile-files-sheet-root")).toBeInTheDocument();
     expect(screen.getByRole("region", { name: "Sheet Explorer" })).toBeInTheDocument();
     expect(screen.getByRole("heading", { level: 2, name: "Explorer" })).toBeInTheDocument();
   });
 
+  it("opens the files sheet from the mobile topbar", async () => {
+    renderMobileView();
+
+    fireEvent.click(screen.getByRole("button", { name: "Topbar files" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("mobile-files-sheet-root")).toBeInTheDocument();
+      expect(screen.getByRole("heading", { level: 2, name: "Explorer" })).toBeInTheDocument();
+    });
+  });
+
+  it("opens the terminal sheet from the mobile topbar", async () => {
+    renderMobileView();
+
+    fireEvent.click(screen.getByRole("button", { name: "Topbar terminal" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("terminal-panel")).toBeInTheDocument();
+      expect(screen.getByRole("heading", { level: 2, name: "label.terminal" })).toBeInTheDocument();
+    });
+  });
+
+  it("removes the mobile dock row and keeps the status bar inside the bottom stack", () => {
+    renderMobileView();
+
+    expect(screen.queryByTestId("mobile-dock")).not.toBeInTheDocument();
+    expect(screen.getByTestId("mobile-bottom-stack")).toBeInTheDocument();
+    expect(screen.getByTestId("workspace-status-bar")).toBeInTheDocument();
+  });
+
+  it("keeps the empty-state guidance aligned with topbar access instead of the removed bottom bar", () => {
+    renderMobileView({
+      activePath: null,
+      openFiles: {},
+      sessions: [],
+    });
+
+    expect(screen.getByText("Start session")).toBeInTheDocument();
+    expect(screen.getByText("Use files or terminal to get started.")).toBeInTheDocument();
+    expect(screen.queryByText(/bottom bar/i)).not.toBeInTheDocument();
+  });
+
+  it("passes the current mobile sessions and screen-model actions into the drawer", async () => {
+    renderMobileView({
+      activePath: null,
+      openFiles: {},
+      mobileActiveSessionId: "sess-1",
+      sessions: [
+        createSession({
+          id: "sess-1",
+          workspaceId: "ws-test",
+          terminalId: "term-1",
+          providerId: "claude",
+          title: "Claude Repair CI",
+          state: "running",
+          lastActiveAt: 2,
+        }),
+        createSession({
+          id: "sess-2",
+          workspaceId: "ws-test",
+          terminalId: "term-2",
+          providerId: "codex",
+          title: "Codex Mobile Layout",
+          state: "idle",
+          lastActiveAt: 1,
+        }),
+      ],
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Toggle drawer" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("mobile-workspace-drawer")).toBeInTheDocument();
+    });
+
+    expect(screen.getByTestId("drawer-active-session")).toHaveTextContent("sess-1");
+    expect(screen.getByTestId("drawer-sessions")).toHaveTextContent("sess-1");
+    expect(screen.getByTestId("drawer-sessions")).toHaveTextContent("sess-2");
+    expect(screen.getByTestId("drawer-sessions")).toHaveTextContent('"ws-test"');
+  });
+
+  it("passes loaded sessions for every workspace into the drawer grouping", async () => {
+    const store = renderMobileView({
+      activePath: null,
+      openFiles: {},
+      mobileActiveSessionId: "sess-1",
+      sessions: [
+        createSession({
+          id: "sess-1",
+          workspaceId: "ws-test",
+          terminalId: "term-1",
+          providerId: "claude",
+          title: "Claude Repair CI",
+          state: "running",
+          lastActiveAt: 2,
+        }),
+        createSession({
+          id: "sess-9",
+          workspaceId: "ws-2",
+          terminalId: "term-9",
+          providerId: "gemini",
+          title: "Gemini Sandbox",
+          state: "idle",
+          lastActiveAt: 1,
+        }),
+      ],
+    });
+
+    act(() => {
+      seedReadyWorkspaceState(store, {
+        "ws-test": {
+          id: "ws-test",
+          path: "/tmp/ws-test",
+          targetRuntime: "native",
+          openedAt: 1,
+          lastActiveAt: 1,
+          uiState: {
+            leftPanelWidth: 280,
+            bottomPanelHeight: 200,
+            focusMode: false,
+            activeSessionId: "sess-1",
+          },
+        },
+        "ws-2": {
+          id: "ws-2",
+          path: "/tmp/ws-2",
+          targetRuntime: "native",
+          openedAt: 2,
+          lastActiveAt: 2,
+          uiState: {
+            leftPanelWidth: 280,
+            bottomPanelHeight: 200,
+            focusMode: false,
+          },
+        },
+      });
+      store.set(activeWorkspaceIdAtom, "ws-test");
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Toggle drawer" }));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("mobile-workspace-drawer")).toBeInTheDocument();
+    });
+
+    expect(screen.getByTestId("drawer-sessions")).toHaveTextContent('"ws-test"');
+    expect(screen.getByTestId("drawer-sessions")).toHaveTextContent('"ws-2"');
+    expect(screen.getByTestId("drawer-sessions")).toHaveTextContent("sess-9");
+  });
+
+  it("closes the drawer and opens the existing create-session flow from the drawer action", async () => {
+    renderMobileView();
+
+    fireEvent.click(screen.getByRole("button", { name: "Toggle drawer" }));
+    await waitFor(() => {
+      expect(screen.getByTestId("mobile-workspace-drawer")).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Drawer create session" }));
+
+    await waitFor(() => {
+      expect(screen.queryByTestId("mobile-workspace-drawer")).not.toBeInTheDocument();
+      expect(screen.getByTestId("mobile-agent-sheet")).toBeInTheDocument();
+    });
+  });
+
+  it("opens the agent sheet in create mode from drawer create even when sessions already exist", async () => {
+    renderMobileView({
+      activePath: null,
+      openFiles: {},
+      mobileActiveSessionId: "sess-1",
+      sessions: [
+        createSession({
+          id: "sess-1",
+          workspaceId: "ws-test",
+          terminalId: "term-1",
+          providerId: "claude",
+          title: "Claude Repair CI",
+          state: "running",
+          lastActiveAt: 2,
+        }),
+        createSession({
+          id: "sess-2",
+          workspaceId: "ws-test",
+          terminalId: "term-2",
+          providerId: "codex",
+          title: "Codex Mobile Layout",
+          state: "idle",
+          lastActiveAt: 1,
+        }),
+      ],
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Toggle drawer" }));
+    await waitFor(() => {
+      expect(screen.getByTestId("mobile-workspace-drawer")).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Drawer create session" }));
+
+    await waitFor(() => {
+      expect(screen.queryByTestId("mobile-workspace-drawer")).not.toBeInTheDocument();
+      expect(screen.getByTestId("mobile-agent-sheet")).toHaveAttribute(
+        "data-default-mode",
+        "create"
+      );
+    });
+  });
+
+  it("selects a session from the drawer and closes it", async () => {
+    renderMobileView({
+      activePath: null,
+      openFiles: {},
+      mobileActiveSessionId: "sess-1",
+      sessions: [
+        createSession({
+          id: "sess-1",
+          workspaceId: "ws-test",
+          terminalId: "term-1",
+          providerId: "claude",
+          title: "Claude Repair CI",
+          state: "running",
+          lastActiveAt: 2,
+        }),
+        createSession({
+          id: "sess-2",
+          workspaceId: "ws-test",
+          terminalId: "term-2",
+          providerId: "codex",
+          title: "Codex Mobile Layout",
+          state: "idle",
+          lastActiveAt: 1,
+        }),
+      ],
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Toggle drawer" }));
+    await waitFor(() => {
+      expect(screen.getByTestId("mobile-workspace-drawer")).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Drawer select sess-2" }));
+
+    await waitFor(() => {
+      expect(screen.queryByTestId("mobile-workspace-drawer")).not.toBeInTheDocument();
+    });
+  });
+
   it("does not expose the dev browser sheet from the mobile dock", async () => {
     renderMobileView();
 
diff --git a/packages/web/src/features/workspace/views/mobile/workspace-mobile-view.tsx b/packages/web/src/features/workspace/views/mobile/workspace-mobile-view.tsx
index 07c509e28..9d0892c39 100644
--- a/packages/web/src/features/workspace/views/mobile/workspace-mobile-view.tsx
+++ b/packages/web/src/features/workspace/views/mobile/workspace-mobile-view.tsx
@@ -1,10 +1,13 @@
+import type { Session } from "@coder-studio/core";
 import { useAtomValue, useSetAtom } from "jotai";
-import { type CSSProperties, type ReactNode, useEffect, useRef, useState } from "react";
+import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from "react";
 import {
   lastViewedTargetAtom,
   pendingFocusSessionAtom,
   visibleMobileSessionIdAtom,
 } from "../../../../atoms/app-ui";
+import { connectionStatusAtom, dispatchCommandAtom } from "../../../../atoms/connection";
+import { sessionsAtom } from "../../../../atoms/sessions";
 import { Sheet } from "../../../../components/ui";
 import { useTranslation } from "../../../../lib/i18n";
 import { SessionCard } from "../../../agent-panes/views/shared/session-card";
@@ -26,7 +29,6 @@ import { useMobileLayoutMode } from "./hooks/use-mobile-layout-mode";
 import { useMobileMotionMode } from "./hooks/use-mobile-motion-mode";
 import { useVisualViewportInset } from "./hooks/use-visual-viewport-inset";
 import { MobileAgentSheet } from "./mobile-agent-sheet";
-import { MobileDock } from "./mobile-dock";
 import { MobileFilesSheet } from "./mobile-files-sheet";
 import { MobileTopBar } from "./mobile-topbar";
 import { MobileWorkspaceDrawer } from "./mobile-workspace-drawer";
@@ -70,10 +72,16 @@ export function WorkspaceMobileView() {
   const fullscreenRootRef = useRef<HTMLDivElement>(null);
   const restoredWorkspaceIdRef = useRef<string | null>(null);
   const lastPersistedSessionIdRef = useRef<string | null>(null);
+  const drawerHydratedWorkspaceIdsRef = useRef<Set<string>>(new Set());
+  const drawerPendingWorkspaceIdsRef = useRef<Set<string>>(new Set());
   const fullscreenController = useWorkspaceFullscreen(fullscreenRootRef);
   const t = useTranslation();
+  const connectionStatus = useAtomValue(connectionStatusAtom);
+  const dispatch = useAtomValue(dispatchCommandAtom);
   const pendingFocusSessionId = useAtomValue(pendingFocusSessionAtom);
   const lastViewedTarget = useAtomValue(lastViewedTargetAtom);
+  const allSessions = useAtomValue(sessionsAtom);
+  const setSessions = useSetAtom(sessionsAtom);
   const setVisibleMobileSessionId = useSetAtom(visibleMobileSessionIdAtom);
   const supervisorDetails = useAtomValue(supervisorDetailsAtom);
   const supervisorDialog = useAtomValue(supervisorDialogAtom);
@@ -103,6 +111,7 @@ export function WorkspaceMobileView() {
   );
   const [drawerOpen, setDrawerOpen] = useState(false);
   const [agentSheetOpen, setAgentSheetOpen] = useState(false);
+  const [agentSheetMode, setAgentSheetMode] = useState<"create" | "list">("create");
   const [mobileFilesView, setMobileFilesView] = useState<MobileWorkspaceSidebarView>("explorer");
   const [mobileFileCreateRequest, setMobileFileCreateRequest] = useState<CreateRequest | null>(
     null
@@ -312,6 +321,119 @@ export function WorkspaceMobileView() {
         ? t("workspace.sidebar.search")
         : t("workspace.sidebar.source_control");
 
+  useEffect(() => {
+    if (!drawerOpen || connectionStatus !== "connected") {
+      return;
+    }
+
+    let cancelled = false;
+    const workspaceIdsToHydrate = workspaces
+      .map((candidate) => candidate.id)
+      .filter(
+        (workspaceId) =>
+          workspaceId !== activeWorkspaceId &&
+          !drawerHydratedWorkspaceIdsRef.current.has(workspaceId) &&
+          !drawerPendingWorkspaceIdsRef.current.has(workspaceId)
+      );
+
+    for (const workspaceId of workspaceIdsToHydrate) {
+      drawerPendingWorkspaceIdsRef.current.add(workspaceId);
+      const workspaceSessionIdsAtRequestStart = new Set(
+        Object.values(allSessions)
+          .filter((session) => session.workspaceId === workspaceId)
+          .map((session) => session.id)
+      );
+
+      dispatch<Session[]>("session.list", { workspaceId })
+        .then((result) => {
+          drawerPendingWorkspaceIdsRef.current.delete(workspaceId);
+
+          if (cancelled || !result.ok || !result.data) {
+            console.error("Failed to fetch sessions:", result.error?.message);
+            return;
+          }
+
+          const nextSessions = result.data;
+          drawerHydratedWorkspaceIdsRef.current.add(workspaceId);
+
+          setSessions((previous) => {
+            const currentWorkspaceSessions = Object.values(previous).filter(
+              (session) => session.workspaceId === workspaceId
+            );
+            const preservedLateSessions = currentWorkspaceSessions.filter(
+              (session) =>
+                !workspaceSessionIdsAtRequestStart.has(session.id) &&
+                !nextSessions.some((nextSession) => nextSession.id === session.id)
+            );
+            const mergedSessions = [...nextSessions, ...preservedLateSessions];
+            const next = Object.fromEntries(
+              Object.entries(previous).filter(([, session]) => session.workspaceId !== workspaceId)
+            );
+
+            for (const session of mergedSessions) {
+              next[session.id] = session;
+            }
+
+            return next;
+          });
+        })
+        .catch((error) => {
+          drawerPendingWorkspaceIdsRef.current.delete(workspaceId);
+
+          if (!cancelled) {
+            console.error("Failed to fetch sessions:", error);
+          }
+        });
+    }
+
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    activeWorkspaceId,
+    allSessions,
+    connectionStatus,
+    dispatch,
+    drawerOpen,
+    setSessions,
+    workspaces,
+  ]);
+
+  const sessionsByWorkspaceId = useMemo(() => {
+    const grouped = Object.fromEntries(
+      workspaces.map((workspaceItem) => [workspaceItem.id, [] as typeof mobileAgentSessions])
+    ) as Record<string, typeof mobileAgentSessions>;
+
+    if (activeWorkspaceId) {
+      grouped[activeWorkspaceId] = mobileAgentSessions;
+    }
+
+    for (const session of Object.values(allSessions)) {
+      if (session.state === "draft" || session.workspaceId === activeWorkspaceId) {
+        continue;
+      }
+
+      if (!grouped[session.workspaceId]) {
+        grouped[session.workspaceId] = [];
+      }
+
+      grouped[session.workspaceId].push(session);
+    }
+
+    return Object.fromEntries(
+      Object.entries(grouped).map(([workspaceId, workspaceSessions]) => [
+        workspaceId,
+        workspaceSessions.map((session) => ({
+          id: session.id,
+          workspaceId: session.workspaceId,
+          providerId: session.providerId,
+          title: session.title,
+          state: session.state,
+        })),
+      ])
+    );
+  }, [activeWorkspaceId, allSessions, mobileAgentSessions, workspaces]);
+
   const sheetBody =
     mobileSheet === "files"
       ? {
@@ -377,21 +499,23 @@ export function WorkspaceMobileView() {
           }
         : null;
 
-  const handleDockSelect = (item: "agent" | "files" | "terminal") => {
-    if (item === "agent") {
-      setAgentSheetOpen((value) => !value);
-      return;
-    }
+  const handleOpenFiles = () => {
+    setDrawerOpen(false);
+    setAgentSheetOpen(false);
+    openMobileSheet("files");
+  };
 
+  const handleOpenTerminal = () => {
+    setDrawerOpen(false);
     setAgentSheetOpen(false);
-    openMobileSheet(item);
+    openMobileSheet("terminal");
   };
 
-  const activeDockItem = agentSheetOpen
-    ? "agent"
-    : mobileSheet === "files" || mobileSheet === "terminal"
-      ? mobileSheet
-      : null;
+  const handleOpenAgentSheet = (mode: "create" | "list") => {
+    setDrawerOpen(false);
+    setAgentSheetMode(mode);
+    setAgentSheetOpen(true);
+  };
 
   return (
     <div
@@ -409,6 +533,8 @@ export function WorkspaceMobileView() {
           setAgentSheetOpen(false);
           setDrawerOpen((value) => !value);
         }}
+        onOpenFiles={handleOpenFiles}
+        onOpenTerminal={handleOpenTerminal}
       />
 
       <main className="mobile-shell__viewport">
@@ -443,7 +569,7 @@ export function WorkspaceMobileView() {
                     <button
                       type="button"
                       className="mobile-shell__empty-cta"
-                      onClick={() => setAgentSheetOpen(true)}
+                      onClick={() => handleOpenAgentSheet("create")}
                     >
                       {t("action.create_session")}
                     </button>
@@ -460,9 +586,6 @@ export function WorkspaceMobileView() {
         data-testid="mobile-bottom-stack"
         style={{ "--mobile-keyboard-inset": `${keyboardInset}px` } as CSSProperties}
       >
-        <div className="mobile-dock-shell">
-          <MobileDock activeItem={activeDockItem} onSelectItem={handleDockSelect} />
-        </div>
         {activeWorkspaceId ? (
           <WorkspaceStatusBar
             workspaceId={activeWorkspaceId}
@@ -476,7 +599,7 @@ export function WorkspaceMobileView() {
         <MobileAgentSheet
           activeSessionId={mobileActiveSessionId}
           activeWorkspaceId={activeWorkspaceId}
-          defaultMode={mobileAgentSessions.length === 0 ? "create" : "list"}
+          defaultMode={agentSheetMode}
           sessions={mobileAgentSessions}
           onClose={() => setAgentSheetOpen(false)}
           onCloseSession={closeMobileSession}
@@ -517,13 +640,21 @@ export function WorkspaceMobileView() {
 
       <MobileWorkspaceDrawer
         activeWorkspaceId={activeWorkspaceId}
+        activeSessionId={mobileActiveSessionId}
         isOpen={drawerOpen}
+        sessionsByWorkspaceId={sessionsByWorkspaceId}
         workspaces={workspaces}
         onClose={() => setDrawerOpen(false)}
+        onCloseSession={closeMobileSession}
+        onCreateSession={() => handleOpenAgentSheet("create")}
         onOpenWorkspaceLauncher={() => {
           setAgentSheetOpen(false);
           setWorkspaceLaunchOpen(true);
         }}
+        onSelectSession={(sessionId) => {
+          selectMobileSession(sessionId);
+          setDrawerOpen(false);
+        }}
       />
 
       {workspaceLaunchOpen ? (
diff --git a/packages/web/src/features/workspace/views/shared/file-tree-panel.test.tsx b/packages/web/src/features/workspace/views/shared/file-tree-panel.test.tsx
index c100ba819..ea0f9b130 100644
--- a/packages/web/src/features/workspace/views/shared/file-tree-panel.test.tsx
+++ b/packages/web/src/features/workspace/views/shared/file-tree-panel.test.tsx
@@ -11,6 +11,8 @@ import {
   fileTreeAtomFamily,
   fileTreeStaleAtomFamily,
   loadedDirsAtomFamily,
+  openEditorPathsAtomFamily,
+  openEditorTabsAtomFamily,
   openFilesAtomFamily,
 } from "../../atoms";
 import { FileTreePanel } from "./file-tree-panel";
@@ -1957,6 +1959,47 @@ describe("FileTreePanel", () => {
       source: "file-tree",
       requestId: expect.any(Number),
     });
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+      { kind: "file", path: "src/app.tsx", pinned: false },
+    ]);
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual([]);
+  });
+
+  it("pins a file tab when a file-tree row is double-clicked", async () => {
+    const store = createStore();
+    store.set(wsClientAtom, { sendCommand: vi.fn().mockResolvedValue({}) } as never);
+    store.set(
+      fileTreeAtomFamily("ws-test"),
+      new Map([
+        [
+          ".",
+          [
+            {
+              path: "src/app.tsx",
+              name: "app.tsx",
+              kind: "file",
+            },
+          ],
+        ],
+      ])
+    );
+
+    render(
+      <Provider store={store}>
+        <FileTreePanel workspaceId="ws-test" />
+      </Provider>
+    );
+
+    fireEvent.doubleClick(await screen.findByText("app.tsx"));
+
+    await waitFor(() => {
+      expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe("src/app.tsx");
+    });
+
+    expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+      { kind: "file", path: "src/app.tsx", pinned: true },
+    ]);
+    expect(store.get(openEditorPathsAtomFamily("ws-test"))).toEqual(["src/app.tsx"]);
   });
 
   it("keeps expanded directories populated after refreshing the file tree", async () => {
diff --git a/packages/web/src/features/workspace/views/shared/file-tree-panel.tsx b/packages/web/src/features/workspace/views/shared/file-tree-panel.tsx
index 0948ec3a4..d0ad4bedc 100644
--- a/packages/web/src/features/workspace/views/shared/file-tree-panel.tsx
+++ b/packages/web/src/features/workspace/views/shared/file-tree-panel.tsx
@@ -198,6 +198,7 @@ export const FileTreePanel: FC<FileTreePanelProps> = ({
     cancelDelete,
     confirmDelete,
     handleSelectFile,
+    handlePinFile,
     loadChildren,
     loadSearchResults,
     openCreateDialog,
@@ -454,6 +455,7 @@ export const FileTreePanel: FC<FileTreePanelProps> = ({
                   selectedPath={activeFilePath}
                   isContextTarget={contextTargetPath === node.path}
                   onSelectFile={handleSelectFile}
+                  onPinFile={handlePinFile}
                   onOpenContextMenu={openRowContextMenu}
                   onBeginLongPress={beginRowLongPress}
                   onUpdateLongPress={updateLongPress}
@@ -478,6 +480,7 @@ export const FileTreePanel: FC<FileTreePanelProps> = ({
                 contextTargetPath={contextTargetPath}
                 onRequestCreate={openCreateDialog}
                 onSelectFile={handleSelectFile}
+                onPinFile={handlePinFile}
                 onLoadChildren={loadChildren}
                 onToggleDirs={applyExpandedDirs}
                 isLoadingDir={isLoadingDir}
@@ -535,6 +538,7 @@ interface FileSearchResultRowProps {
   selectedPath: string | null;
   isContextTarget: boolean;
   onSelectFile: (path: string) => void;
+  onPinFile: (path: string) => void;
   onOpenContextMenu: (
     event: ReactMouseEvent<HTMLElement>,
     node: FileNode,
@@ -557,6 +561,7 @@ const FileSearchResultRow: FC<FileSearchResultRowProps> = ({
   selectedPath,
   isContextTarget,
   onSelectFile,
+  onPinFile,
   onOpenContextMenu,
   onBeginLongPress,
   onUpdateLongPress,
@@ -591,6 +596,10 @@ const FileSearchResultRow: FC<FileSearchResultRowProps> = ({
 
         onSelectFile(node.path);
       }}
+      onDoubleClick={(event) => {
+        event.preventDefault();
+        onPinFile(node.path);
+      }}
       onContextMenu={
         variant === "desktop" ? (event) => onOpenContextMenu(event, node, surface) : undefined
       }
@@ -628,6 +637,7 @@ interface FileTreeNodeProps {
   contextTargetPath: string | null;
   onRequestCreate: (mode: "file" | "folder", baseDir: string | null) => void;
   onSelectFile: (path: string) => void;
+  onPinFile: (path: string) => void;
   onLoadChildren: (dirPath: string) => void;
   onToggleDirs: (nextPaths: Iterable<string>) => void;
   isLoadingDir: string | null;
@@ -658,6 +668,7 @@ const FileTreeNode: FC<FileTreeNodeProps> = ({
   contextTargetPath,
   onRequestCreate,
   onSelectFile,
+  onPinFile,
   onLoadChildren,
   onToggleDirs,
   isLoadingDir,
@@ -737,6 +748,14 @@ const FileTreeNode: FC<FileTreeNodeProps> = ({
         draggable={variant === "desktop" ? true : undefined}
         onDragStart={variant === "desktop" ? handleDragStart : undefined}
         onClick={handleClick}
+        onDoubleClick={
+          !isFolder
+            ? (event) => {
+                event.preventDefault();
+                onPinFile(node.path);
+              }
+            : undefined
+        }
         onContextMenu={
           variant === "desktop" ? (event) => onOpenContextMenu(event, node, "tree") : undefined
         }
@@ -826,6 +845,7 @@ const FileTreeNode: FC<FileTreeNodeProps> = ({
               contextTargetPath={contextTargetPath}
               onRequestCreate={onRequestCreate}
               onSelectFile={onSelectFile}
+              onPinFile={onPinFile}
               onLoadChildren={onLoadChildren}
               onToggleDirs={onToggleDirs}
               defaultExpandedRootPaths={defaultExpandedRootPaths}
diff --git a/packages/web/src/features/workspace/views/shared/footer-update-rail.test.tsx b/packages/web/src/features/workspace/views/shared/footer-update-rail.test.tsx
index d48629f73..b73de3dc5 100644
--- a/packages/web/src/features/workspace/views/shared/footer-update-rail.test.tsx
+++ b/packages/web/src/features/workspace/views/shared/footer-update-rail.test.tsx
@@ -249,7 +249,7 @@ describe("FooterUpdateRail", () => {
 
       if (testCase.action) {
         fireEvent.click(screen.getByRole("button", { name: testCase.action }));
-        expect(navigateMock).toHaveBeenLastCalledWith("/settings?section=about");
+        expect(navigateMock).toHaveBeenLastCalledWith("/more/about/update-status");
       }
 
       unmount();
diff --git a/packages/web/src/features/workspace/views/shared/footer-update-rail.tsx b/packages/web/src/features/workspace/views/shared/footer-update-rail.tsx
index 3fd27f8e7..1b8cf6c8c 100644
--- a/packages/web/src/features/workspace/views/shared/footer-update-rail.tsx
+++ b/packages/web/src/features/workspace/views/shared/footer-update-rail.tsx
@@ -86,7 +86,7 @@ export function FooterUpdateRail() {
   };
 
   const openDetails = () => {
-    navigate("/settings?section=about");
+    navigate("/more/about/update-status");
   };
 
   if (!updateState) {
diff --git a/packages/web/src/features/workspace/views/shared/git-panel.test.tsx b/packages/web/src/features/workspace/views/shared/git-panel.test.tsx
index 3f6c50bb0..3f7ea632f 100644
--- a/packages/web/src/features/workspace/views/shared/git-panel.test.tsx
+++ b/packages/web/src/features/workspace/views/shared/git-panel.test.tsx
@@ -2991,7 +2991,7 @@ describe("GitPanel", () => {
     expect(changesSection).not.toBeNull();
 
     fireEvent.click(
-      within(changesSection as HTMLElement).getByRole("button", { name: "放弃全部" })
+      within(changesSection as HTMLElement).getByRole("button", { name: "撤销全部" })
     );
 
     expect(screen.getByText("放弃所有更改")).toBeInTheDocument();
@@ -3146,7 +3146,7 @@ describe("GitPanel", () => {
     expect(changesSection).not.toBeNull();
 
     fireEvent.click(
-      within(changesSection as HTMLElement).getByRole("button", { name: "放弃全部" })
+      within(changesSection as HTMLElement).getByRole("button", { name: "撤销全部" })
     );
 
     expect(screen.getByRole("dialog")).toBeInTheDocument();
@@ -3357,15 +3357,35 @@ describe("GitPanel", () => {
     expect(screen.queryByText("未跟踪")).toBeNull();
     expect(screen.getByPlaceholderText("输入提交信息...")).toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "刷新" })).not.toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "放弃全部" })).toBeInTheDocument();
-    expect(screen.getAllByRole("button", { name: "暂存全部" })).toHaveLength(1);
+    expect(screen.getByRole("button", { name: "撤销全部" })).toBeInTheDocument();
+    expect(screen.getAllByRole("button", { name: "添加全部" })).toHaveLength(1);
     expect(screen.getByRole("button", { name: "取消暂存全部" })).toBeInTheDocument();
 
+    const stagedSection = screen.getByText("已暂存").closest(".git-panel-section");
+    expect(stagedSection).not.toBeNull();
+    expect(
+      within(stagedSection as HTMLElement).getByRole("button", { name: "取消暂存全部" })
+    ).toBeInTheDocument();
+    expect(
+      within(stagedSection as HTMLElement).queryByText("取消暂存全部")
+    ).not.toBeInTheDocument();
+
+    const changesSection = screen.getByText("更改").closest(".git-panel-section");
+    expect(changesSection).not.toBeNull();
+    expect(
+      within(changesSection as HTMLElement).getByRole("button", { name: "添加全部" })
+    ).toBeInTheDocument();
+    expect(
+      within(changesSection as HTMLElement).getByRole("button", { name: "撤销全部" })
+    ).toBeInTheDocument();
+    expect(within(changesSection as HTMLElement).queryByText("添加全部")).not.toBeInTheDocument();
+    expect(within(changesSection as HTMLElement).queryByText("撤销全部")).not.toBeInTheDocument();
+
     const commitBlock = screen.getByPlaceholderText("输入提交信息...").closest(".git-commit-block");
     expect(commitBlock).not.toBeNull();
     expect(within(commitBlock as HTMLElement).queryByRole("button", { name: "放弃" })).toBeNull();
     expect(
-      within(commitBlock as HTMLElement).queryByRole("button", { name: "暂存全部" })
+      within(commitBlock as HTMLElement).queryByRole("button", { name: "添加全部" })
     ).toBeNull();
     expect(
       within(commitBlock as HTMLElement).getByRole("button", { name: "提交" })
diff --git a/packages/web/src/features/workspace/views/shared/git-panel.tsx b/packages/web/src/features/workspace/views/shared/git-panel.tsx
index 15e40b445..24126cbe5 100644
--- a/packages/web/src/features/workspace/views/shared/git-panel.tsx
+++ b/packages/web/src/features/workspace/views/shared/git-panel.tsx
@@ -745,13 +745,14 @@ export const GitPanel: FC<GitPanelProps> = ({
             actions={
               stagedCount > 0 ? (
                 <Tooltip content={t("git.unstage_all")}>
-                  <button
-                    type="button"
-                    className="git-panel-section-link"
+                  <IconButton
+                    aria-label={t("git.unstage_all")}
+                    className="git-panel-section-action-icon"
+                    icon={<Minus size={12} />}
                     onClick={() => void handleUnstageAll()}
-                  >
-                    {t("git.unstage_all")}
-                  </button>
+                    size="sm"
+                    variant="ghost"
+                  />
                 </Tooltip>
               ) : null
             }
@@ -803,24 +804,26 @@ export const GitPanel: FC<GitPanelProps> = ({
               <>
                 {unstagedCount > 0 ? (
                   <Tooltip content={t("git.stage_all")}>
-                    <button
-                      type="button"
-                      className="git-panel-section-link"
+                    <IconButton
+                      aria-label={t("git.stage_all")}
+                      className="git-panel-section-action-icon"
+                      icon={<Plus size={12} />}
                       onClick={() => void handleStageAll()}
-                    >
-                      {t("git.stage_all")}
-                    </button>
+                      size="sm"
+                      variant="ghost"
+                    />
                   </Tooltip>
                 ) : null}
                 {unstagedCount > 0 ? (
                   <Tooltip content={t("git.discard_all")}>
-                    <button
-                      type="button"
-                      className="git-panel-section-link"
+                    <IconButton
+                      aria-label={t("git.discard_all")}
+                      className="git-panel-section-action-icon"
+                      icon={<RotateCcw size={12} />}
                       onClick={handleDiscardAll}
-                    >
-                      {t("git.discard_all")}
-                    </button>
+                      size="sm"
+                      variant="ghost"
+                    />
                   </Tooltip>
                 ) : null}
               </>
diff --git a/packages/web/src/features/workspace/views/shared/memory-panel.test.tsx b/packages/web/src/features/workspace/views/shared/memory-panel.test.tsx
index 06b760c8d..d1e001f42 100644
--- a/packages/web/src/features/workspace/views/shared/memory-panel.test.tsx
+++ b/packages/web/src/features/workspace/views/shared/memory-panel.test.tsx
@@ -1,5 +1,6 @@
 import type { WorkspaceMemoryEntry } from "@coder-studio/core";
 import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { createStore, Provider } from "jotai";
 import { describe, expect, it, vi } from "vitest";
 import { localeAtom } from "../../../../atoms/app-ui";
@@ -9,13 +10,21 @@ import { MemoryPanel } from "./memory-panel";
 const baseMemoryEntry: WorkspaceMemoryEntry = {
   id: "mem-1",
   workspaceId: "ws-1",
-  type: "project",
+  type: "wiki",
   content: "Package scripts should run through pnpm.",
   source: { kind: "user" },
   createdAt: 1000,
   updatedAt: 2000,
 };
 
+const issueMemoryEntry: WorkspaceMemoryEntry = {
+  ...baseMemoryEntry,
+  id: "mem-2",
+  type: "issue",
+  content: "Dropdown stays open.",
+  status: "pending_verification",
+};
+
 function renderMemoryPanel(
   sendCommand: ReturnType<typeof vi.fn>,
   options: { refreshToken?: number } = {}
@@ -37,9 +46,10 @@ describe("MemoryPanel", () => {
       if (op === "memory.list") {
         return [
           baseMemoryEntry,
+          issueMemoryEntry,
           {
             ...baseMemoryEntry,
-            id: "mem-2",
+            id: "mem-3",
             type: "note",
             content: "Run targeted tests before handoff.",
           },
@@ -53,15 +63,21 @@ describe("MemoryPanel", () => {
 
     expect(await screen.findByText("Project Memory")).toBeInTheDocument();
     expect(screen.getByRole("heading", { name: "Memory" })).toBeInTheDocument();
-    expect(screen.getByText("2 active entries")).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "All" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "Project" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "Note" })).toBeInTheDocument();
-    await screen.findByRole("button", { name: "Package scripts should run through pnpm. Project" });
+    expect(screen.getByText("3 active entries")).toBeInTheDocument();
+    expect(
+      within(screen.getByRole("group", { name: "Memory type" }))
+        .getAllByRole("button")
+        .map((button) => button.textContent)
+    ).toEqual(["All", "Wiki", "Issue", "Todo", "Note"]);
+    await screen.findByRole("button", { name: "Package scripts should run through pnpm. Wiki" });
     expect(sendCommand).toHaveBeenCalledWith("memory.list", { workspaceId: "ws-1" }, undefined);
     expect(screen.getByText("Package scripts should run through pnpm.")).toBeInTheDocument();
-    expect(screen.getByText("project")).toBeInTheDocument();
+    expect(screen.getByText("Dropdown stays open.")).toBeInTheDocument();
+    expect(screen.getByText("wiki")).toBeInTheDocument();
+    expect(screen.getByText("issue")).toBeInTheDocument();
     expect(screen.getByText("note")).toBeInTheDocument();
+    expect(screen.getByText("pending verification")).toBeInTheDocument();
+    expect(screen.queryByText("not started")).toBeNull();
     expect(screen.queryByText("Selected Memory")).toBeNull();
     expect(screen.queryByRole("button", { name: "Save memory" })).toBeNull();
 
@@ -73,11 +89,38 @@ describe("MemoryPanel", () => {
       screen.getByRole("button", { name: "Run targeted tests before handoff. Note" })
     ).toBeInTheDocument();
     expect(
-      screen.queryByRole("button", { name: "Package scripts should run through pnpm. Project" })
+      screen.queryByRole("button", { name: "Package scripts should run through pnpm. Wiki" })
     ).toBeNull();
     expect(sendCommand.mock.calls.filter(([op]) => op === "memory.list")).toHaveLength(1);
   });
 
+  it("renders actionable memory statuses as separate status badges", async () => {
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "memory.list") {
+        return [issueMemoryEntry];
+      }
+
+      return null;
+    });
+
+    const { container } = renderMemoryPanel(sendCommand);
+
+    await screen.findByRole("button", { name: "Dropdown stays open. Issue" });
+
+    const badges = container.querySelector(".memory-panel__item-badges");
+    expect(badges).not.toBeNull();
+
+    const typeBadge = screen.getByText("issue");
+    const statusBadge = screen.getByText("pending verification");
+
+    expect(typeBadge).toHaveClass("memory-panel__badge", "memory-panel__badge--issue");
+    expect(statusBadge).toHaveClass(
+      "memory-panel__badge",
+      "memory-panel__badge--status",
+      "memory-panel__badge--status-pending_verification"
+    );
+  });
+
   it("creates and deletes memory entries without issuing inline update commands", async () => {
     let entries: WorkspaceMemoryEntry[] = [baseMemoryEntry];
     const sendCommand = vi.fn(async (op: string, args: unknown) => {
@@ -112,7 +155,7 @@ describe("MemoryPanel", () => {
 
     renderMemoryPanel(sendCommand);
 
-    await screen.findByRole("button", { name: "Package scripts should run through pnpm. Project" });
+    await screen.findByRole("button", { name: "Package scripts should run through pnpm. Wiki" });
     expect(screen.queryByRole("button", { name: "Save memory" })).toBeNull();
     expect(screen.queryByText("Selected Memory")).toBeNull();
 
@@ -120,8 +163,14 @@ describe("MemoryPanel", () => {
 
     const createDialog = await screen.findByRole("dialog", { name: "Create memory" });
     fireEvent.change(within(createDialog).getByLabelText("Content"), {
-      target: { value: "Workspace memory is stored per workspace." },
+      target: { value: "Dropdown stays open." },
     });
+    fireEvent.click(within(createDialog).getByRole("button", { name: "Type Wiki" }));
+    fireEvent.click(
+      within(within(createDialog).getByRole("listbox", { name: "Type" })).getByRole("option", {
+        name: "Issue",
+      })
+    );
     fireEvent.click(within(createDialog).getByRole("button", { name: "Save memory" }));
 
     await waitFor(() => {
@@ -129,8 +178,9 @@ describe("MemoryPanel", () => {
         "memory.create",
         {
           workspaceId: "ws-1",
-          type: "project",
-          content: "Workspace memory is stored per workspace.",
+          type: "issue",
+          content: "Dropdown stays open.",
+          status: "not_started",
         },
         undefined
       );
@@ -142,14 +192,14 @@ describe("MemoryPanel", () => {
 
     expect(
       await screen.findByRole("button", {
-        name: "Workspace memory is stored per workspace. Project",
+        name: "Dropdown stays open. Issue",
       })
     ).toBeInTheDocument();
     expect(sendCommand.mock.calls.some(([op]) => op === "memory.update")).toBe(false);
 
     fireEvent.click(
       screen.getByRole("button", {
-        name: /Delete memory Workspace memory is stored per workspace\./i,
+        name: /Delete memory Dropdown stays open\./i,
       })
     );
 
@@ -165,6 +215,111 @@ describe("MemoryPanel", () => {
     });
   });
 
+  it("closes the create-memory type dropdown after selecting a category", async () => {
+    const user = userEvent.setup();
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "memory.list") {
+        return [baseMemoryEntry];
+      }
+
+      return null;
+    });
+
+    renderMemoryPanel(sendCommand);
+
+    await screen.findByRole("button", { name: "Package scripts should run through pnpm. Wiki" });
+
+    await user.click(screen.getByRole("button", { name: "New memory" }));
+
+    const createDialog = await screen.findByRole("dialog", { name: "Create memory" });
+    const typeTrigger = within(createDialog).getByRole("button", { name: "Type Wiki" });
+    expect(within(createDialog).queryByRole("button", { name: /Status/i })).toBeNull();
+
+    await user.click(typeTrigger);
+
+    const listbox = within(createDialog).getByRole("listbox", { name: "Type" });
+    await user.click(within(listbox).getByRole("option", { name: "Issue" }));
+
+    expect(within(createDialog).queryByRole("listbox", { name: "Type" })).toBeNull();
+    expect(within(createDialog).getByRole("button", { name: "Type Issue" })).toBeInTheDocument();
+    expect(
+      within(createDialog).getByRole("button", { name: "Status Not started" })
+    ).toBeInTheDocument();
+
+    await user.click(within(createDialog).getByRole("button", { name: "Type Issue" }));
+    await user.click(
+      within(within(createDialog).getByRole("listbox", { name: "Type" })).getByRole("option", {
+        name: "Note",
+      })
+    );
+
+    expect(within(createDialog).getByRole("button", { name: "Type Note" })).toBeInTheDocument();
+    expect(within(createDialog).queryByRole("button", { name: /Status/i })).toBeNull();
+
+    await user.click(within(createDialog).getByRole("button", { name: "Type Note" }));
+    await user.click(
+      within(within(createDialog).getByRole("listbox", { name: "Type" })).getByRole("option", {
+        name: "Wiki",
+      })
+    );
+
+    expect(within(createDialog).getByRole("button", { name: "Type Wiki" })).toBeInTheDocument();
+    expect(within(createDialog).queryByRole("button", { name: /Status/i })).toBeNull();
+  });
+
+  it("edits issue memory status", async () => {
+    let entries: WorkspaceMemoryEntry[] = [issueMemoryEntry];
+    const sendCommand = vi.fn(async (op: string, args: unknown) => {
+      if (op === "memory.list") {
+        return entries;
+      }
+
+      if (op === "memory.update") {
+        const { id, ...updates } = args as Partial<WorkspaceMemoryEntry> & { id: string };
+        entries = entries.map((entry) =>
+          entry.id === id ? { ...entry, ...updates, updatedAt: 4000 } : entry
+        );
+        return entries.find((entry) => entry.id === id);
+      }
+
+      return null;
+    });
+
+    renderMemoryPanel(sendCommand);
+
+    await screen.findByRole("button", { name: "Dropdown stays open. Issue" });
+    fireEvent.click(screen.getByRole("button", { name: /Edit memory Dropdown stays open\./i }));
+
+    const editDialog = await screen.findByRole("dialog", { name: "Edit memory" });
+    expect(
+      within(editDialog).getByRole("button", { name: "Status Pending verification" })
+    ).toBeInTheDocument();
+
+    fireEvent.click(
+      within(editDialog).getByRole("button", { name: "Status Pending verification" })
+    );
+    fireEvent.click(
+      within(within(editDialog).getByRole("listbox", { name: "Status" })).getByRole("option", {
+        name: "Completed",
+      })
+    );
+    fireEvent.click(within(editDialog).getByRole("button", { name: "Save memory" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "memory.update",
+        {
+          workspaceId: "ws-1",
+          id: "mem-2",
+          type: "issue",
+          content: "Dropdown stays open.",
+          status: "completed",
+        },
+        undefined
+      );
+    });
+  });
+
   it("keeps the list visible while showing the correct delete dialog title", async () => {
     const sendCommand = vi.fn(async (op: string) => {
       if (op === "memory.list") {
@@ -178,7 +333,7 @@ describe("MemoryPanel", () => {
 
     expect(
       await screen.findByRole("button", {
-        name: "Package scripts should run through pnpm. Project",
+        name: "Package scripts should run through pnpm. Wiki",
       })
     ).toBeInTheDocument();
     expect(screen.queryByText("Selected Memory")).toBeNull();
diff --git a/packages/web/src/features/workspace/views/shared/memory-panel.tsx b/packages/web/src/features/workspace/views/shared/memory-panel.tsx
index 019c177fb..aa41eb2a7 100644
--- a/packages/web/src/features/workspace/views/shared/memory-panel.tsx
+++ b/packages/web/src/features/workspace/views/shared/memory-panel.tsx
@@ -1,11 +1,16 @@
 import {
+  isActionableWorkspaceMemoryType,
+  WORKSPACE_MEMORY_STATUSES,
   WORKSPACE_MEMORY_TYPES,
   type WorkspaceMemoryEntry,
-  type WorkspaceMemoryType,
+  WorkspaceMemoryStatus,
+  type WorkspaceMemoryStatus as WorkspaceMemoryStatusType,
+  WorkspaceMemoryType,
+  type WorkspaceMemoryType as WorkspaceMemoryTypeType,
 } from "@coder-studio/core";
 import { useAtomValue } from "jotai";
 import { Pencil, Trash2, X } from "lucide-react";
-import { type FC, useEffect, useMemo, useState } from "react";
+import { type FC, useEffect, useId, useMemo, useState } from "react";
 import { localeAtom } from "../../../../atoms/app-ui";
 import { Button } from "../../../../components/ui/button";
 import { ConfirmDialog } from "../../../../components/ui/confirm-dialog";
@@ -28,10 +33,11 @@ interface MemoryPanelProps {
 
 interface MemoryDraft {
   content: string;
-  type: WorkspaceMemoryType;
+  type: WorkspaceMemoryTypeType;
+  status?: WorkspaceMemoryStatusType;
 }
 
-const DEFAULT_MEMORY_TYPE: WorkspaceMemoryType = "project";
+const DEFAULT_MEMORY_TYPE: WorkspaceMemoryTypeType = WorkspaceMemoryType.Wiki;
 
 const EMPTY_DRAFT: MemoryDraft = {
   content: "",
@@ -39,7 +45,7 @@ const EMPTY_DRAFT: MemoryDraft = {
 };
 
 function formatMemoryType(
-  type: WorkspaceMemoryType,
+  type: WorkspaceMemoryTypeType,
   t: (key: string, params?: Record<string, string | number>) => string
 ): string {
   return t(`workspace.memory.types.${type}`);
@@ -64,19 +70,45 @@ function memoryLabel(entry: WorkspaceMemoryEntry): string {
 }
 
 function formatMemoryTypeBadge(
-  type: WorkspaceMemoryType,
+  type: WorkspaceMemoryTypeType,
   t: (key: string, params?: Record<string, string | number>) => string
 ): string {
   return formatMemoryType(type, t).toLowerCase();
 }
 
+function formatMemoryStatus(
+  status: WorkspaceMemoryStatusType,
+  t: (key: string, params?: Record<string, string | number>) => string
+): string {
+  return t(`workspace.memory.statuses.${status}`);
+}
+
 function draftFromEntry(entry: WorkspaceMemoryEntry): MemoryDraft {
+  const status = normalizeDraftStatus(entry.type, entry.status);
+
   return {
     content: entry.content,
     type: entry.type,
+    ...(status ? { status } : {}),
   };
 }
 
+function createDefaultDraft(type: WorkspaceMemoryTypeType = DEFAULT_MEMORY_TYPE): MemoryDraft {
+  return {
+    content: "",
+    type,
+    ...(isActionableWorkspaceMemoryType(type) ? { status: WorkspaceMemoryStatus.NotStarted } : {}),
+  };
+}
+
+function normalizeDraftStatus(type: WorkspaceMemoryTypeType, status?: WorkspaceMemoryStatusType) {
+  if (!isActionableWorkspaceMemoryType(type)) {
+    return undefined;
+  }
+
+  return status ?? WorkspaceMemoryStatus.NotStarted;
+}
+
 function formatActiveCount(
   count: number,
   t: (key: string, params?: Record<string, string | number>) => string
@@ -88,12 +120,18 @@ function formatActiveCount(
 
 export const MemoryPanel: FC<MemoryPanelProps> = ({ workspaceId, refreshToken = 0 }) => {
   const t = useTranslation();
+  const memoryTypeLabelId = useId();
   const locale = useAtomValue(localeAtom) === "zh" ? "zh" : "en";
-  const memoryTypeOptions: ReadonlyArray<SelectOption<WorkspaceMemoryType>> =
+  const memoryTypeOptions: ReadonlyArray<SelectOption<WorkspaceMemoryTypeType>> =
     WORKSPACE_MEMORY_TYPES.map((type) => ({
       value: type,
       label: formatMemoryType(type, t),
     }));
+  const statusOptions: ReadonlyArray<SelectOption<WorkspaceMemoryStatusType>> =
+    WORKSPACE_MEMORY_STATUSES.map((status) => ({
+      value: status,
+      label: formatMemoryStatus(status, t),
+    }));
   const {
     createMemory,
     deleteMemory,
@@ -105,7 +143,7 @@ export const MemoryPanel: FC<MemoryPanelProps> = ({ workspaceId, refreshToken =
     updateMemory,
   } = useMemoryPanel(workspaceId);
   const [query, setQuery] = useState("");
-  const [typeFilter, setTypeFilter] = useState<WorkspaceMemoryType | "all">("all");
+  const [typeFilter, setTypeFilter] = useState<WorkspaceMemoryTypeType | "all">("all");
   const [createDialogOpen, setCreateDialogOpen] = useState(false);
   const [editingEntry, setEditingEntry] = useState<WorkspaceMemoryEntry | null>(null);
   const [pendingDelete, setPendingDelete] = useState<(typeof entries)[number] | null>(null);
@@ -139,7 +177,7 @@ export const MemoryPanel: FC<MemoryPanelProps> = ({ workspaceId, refreshToken =
 
   const startNewMemory = () => {
     setEditingEntry(null);
-    setCreateDraft(EMPTY_DRAFT);
+    setCreateDraft(createDefaultDraft());
     setCreateDialogOpen(true);
   };
 
@@ -159,6 +197,7 @@ export const MemoryPanel: FC<MemoryPanelProps> = ({ workspaceId, refreshToken =
     const payload = {
       content: createDraft.content,
       type: createDraft.type,
+      ...(createDraft.status ? { status: createDraft.status } : {}),
     };
     const saved = editingEntry
       ? await updateMemory({
@@ -189,10 +228,14 @@ export const MemoryPanel: FC<MemoryPanelProps> = ({ workspaceId, refreshToken =
     formDraft: MemoryDraft,
     setFormDraft: (updater: (current: MemoryDraft) => MemoryDraft) => void
   ) => {
+    const actionableType = isActionableWorkspaceMemoryType(formDraft.type);
+
     return (
       <div className="memory-panel__form">
-        <label className="memory-panel__field">
-          <span className="memory-panel__label">{t("workspace.memory.type_label")}</span>
+        <div className="memory-panel__field">
+          <span id={memoryTypeLabelId} className="memory-panel__label">
+            {t("workspace.memory.type_label")}
+          </span>
           <Select
             desktopMode="listbox"
             className="workspace-sidebar-control memory-panel__select"
@@ -200,15 +243,37 @@ export const MemoryPanel: FC<MemoryPanelProps> = ({ workspaceId, refreshToken =
             mobileSheetTitle={t("workspace.memory.type_label")}
             options={memoryTypeOptions}
             value={formDraft.type}
-            aria-label={t("workspace.memory.type_label")}
+            aria-labelledby={memoryTypeLabelId}
             onValueChange={(value) =>
               setFormDraft((current) => ({
                 ...current,
                 type: value,
+                status: normalizeDraftStatus(value, current.status),
               }))
             }
           />
-        </label>
+        </div>
+
+        {actionableType ? (
+          <div className="memory-panel__field">
+            <span className="memory-panel__label">{t("workspace.memory.status_label")}</span>
+            <Select
+              desktopMode="listbox"
+              className="workspace-sidebar-control memory-panel__select"
+              mobileSheetPresentation="inline"
+              mobileSheetTitle={t("workspace.memory.status_label")}
+              options={statusOptions}
+              value={formDraft.status ?? WorkspaceMemoryStatus.NotStarted}
+              aria-label={t("workspace.memory.status_label")}
+              onValueChange={(value) =>
+                setFormDraft((current) => ({
+                  ...current,
+                  status: value,
+                }))
+              }
+            />
+          </div>
+        ) : null}
 
         <label className="memory-panel__field">
           <span className="memory-panel__label">{t("workspace.memory.content_label")}</span>
@@ -322,10 +387,19 @@ export const MemoryPanel: FC<MemoryPanelProps> = ({ workspaceId, refreshToken =
                       </button>
                       <div className="memory-panel__item-meta">
                         <span className="memory-panel__item-meta-main">
-                          <span
-                            className={`memory-panel__badge memory-panel__badge--${entry.type}`}
-                          >
-                            {formatMemoryTypeBadge(entry.type, t)}
+                          <span className="memory-panel__item-badges">
+                            <span
+                              className={`memory-panel__badge memory-panel__badge--${entry.type}`}
+                            >
+                              {formatMemoryTypeBadge(entry.type, t)}
+                            </span>
+                            {entry.status ? (
+                              <span
+                                className={`memory-panel__badge memory-panel__badge--status memory-panel__badge--status-${entry.status}`}
+                              >
+                                {formatMemoryStatus(entry.status, t).toLowerCase()}
+                              </span>
+                            ) : null}
                           </span>
                           <span>{formatRelativeTime(entry.updatedAt, locale)}</span>
                         </span>
diff --git a/packages/web/src/features/workspace/views/shared/open-editors-section.test.tsx b/packages/web/src/features/workspace/views/shared/open-editors-section.test.tsx
index d321e1f7c..10746f768 100644
--- a/packages/web/src/features/workspace/views/shared/open-editors-section.test.tsx
+++ b/packages/web/src/features/workspace/views/shared/open-editors-section.test.tsx
@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 
-import { fireEvent, render, screen, within } from "@testing-library/react";
+import { act, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
 import { createStore, Provider } from "jotai";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { workspacesAtom } from "../../../../atoms/workspaces";
@@ -15,10 +15,12 @@ import {
   beginPendingEditorLoad,
 } from "../../../code-editor/actions/pending-editor-loads";
 import {
+  activeEditorTabAtomFamily,
   activeFilePathAtomFamily,
   type OpenFile,
   type OpenTextFile,
   openEditorPathsAtomFamily,
+  openEditorTabsAtomFamily,
   openFilesAtomFamily,
 } from "../../atoms";
 import { OpenEditorsSection } from "./open-editors-section";
@@ -345,6 +347,39 @@ describe("OpenEditorsSection", () => {
     expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe("README.md");
   });
 
+  it("opens .csc open-editor clicks as source instead of canvas", async () => {
+    const { store } = renderSection(
+      {
+        ".coder-studio/canvases/auth-gate.csc": createFile(".coder-studio/canvases/auth-gate.csc"),
+        "README.md": createFile("README.md"),
+      },
+      "README.md"
+    );
+
+    act(() => {
+      fireEvent.click(screen.getByRole("button", { name: ".coder-studio/canvases/auth-gate.csc" }));
+    });
+
+    expect(store.get(activeFilePathAtomFamily("ws-test"))).toBe(
+      ".coder-studio/canvases/auth-gate.csc"
+    );
+
+    await waitFor(() => {
+      expect(store.get(openEditorTabsAtomFamily("ws-test"))).toEqual([
+        {
+          kind: "file",
+          path: ".coder-studio/canvases/auth-gate.csc",
+          pinned: true,
+        },
+      ]);
+      expect(store.get(activeEditorTabAtomFamily("ws-test"))).toEqual({
+        kind: "file",
+        path: ".coder-studio/canvases/auth-gate.csc",
+        pinned: true,
+      });
+    });
+  });
+
   it("writes workspace drag data for open editor rows", () => {
     renderSection();
 
diff --git a/packages/web/src/features/workspace/views/shared/open-editors-section.tsx b/packages/web/src/features/workspace/views/shared/open-editors-section.tsx
index 956e1e035..45f445fd3 100644
--- a/packages/web/src/features/workspace/views/shared/open-editors-section.tsx
+++ b/packages/web/src/features/workspace/views/shared/open-editors-section.tsx
@@ -185,11 +185,14 @@ export function OpenEditorsSection({ workspaceId, onSelectFile, title }: OpenEdi
                   draggable
                   onDragStart={(event) => handleDragStart(path, event)}
                   onClick={() => {
-                    void openWorkspaceFile({
-                      workspaceId,
-                      path,
-                      source: "manual",
-                    });
+                    void openWorkspaceFile(
+                      {
+                        workspaceId,
+                        path,
+                        source: "manual",
+                      },
+                      { openTarget: "source" }
+                    );
                     onSelectFile?.(path);
                   }}
                 >
diff --git a/packages/web/src/features/workspace/views/shared/quick-jump-section.tsx b/packages/web/src/features/workspace/views/shared/quick-jump-section.tsx
index d901ad4b5..748cc1d7b 100644
--- a/packages/web/src/features/workspace/views/shared/quick-jump-section.tsx
+++ b/packages/web/src/features/workspace/views/shared/quick-jump-section.tsx
@@ -1,8 +1,9 @@
 import type { FileNode } from "@coder-studio/core";
 import { useAtomValue } from "jotai";
+import { ChevronDown, ChevronRight } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import { dispatchCommandAtom } from "../../../../atoms/connection";
-import { ThemedIcon } from "../../../../components/ui";
+import { IconButton, ThemedIcon, Tooltip } from "../../../../components/ui";
 import { useTranslation } from "../../../../lib/i18n";
 import { useOpenWorkspaceFile } from "../../actions/use-open-workspace-file";
 
@@ -23,8 +24,13 @@ export function QuickJumpSection({ workspaceId, onSelectFile }: QuickJumpSection
   const [results, setResults] = useState<FileNode[]>([]);
   const [loading, setLoading] = useState(false);
   const [failed, setFailed] = useState(false);
+  const [collapsed, setCollapsed] = useState(false);
   const requestIdRef = useRef(0);
   const hasQuery = query.trim().length > 0;
+  const isExpanded = !collapsed;
+  const toggleLabel = isExpanded
+    ? t("workspace.quick_jump.collapse_label")
+    : t("workspace.quick_jump.expand_label");
 
   useEffect(() => {
     const trimmed = query.trim();
@@ -82,58 +88,74 @@ export function QuickJumpSection({ workspaceId, onSelectFile }: QuickJumpSection
     <section className="workspace-sidebar-section workspace-quick-jump">
       <div className="workspace-sidebar-section__header">
         <div className="workspace-sidebar-section__header-main">
-          <span className="workspace-sidebar-section__chevron" aria-hidden="true">
-            ▾
-          </span>
+          <Tooltip content={toggleLabel}>
+            <IconButton
+              aria-expanded={isExpanded}
+              aria-label={toggleLabel}
+              className="workspace-sidebar-section__chevron"
+              icon={isExpanded ? <ChevronDown size={14} /> : <ChevronRight size={14} />}
+              size="sm"
+              onClick={() => setCollapsed((value) => !value)}
+            />
+          </Tooltip>
           <h2 className="workspace-sidebar-section__title">{t("workspace.quick_jump.title")}</h2>
         </div>
       </div>
-      <label
-        className="workspace-quick-jump__search workspace-sidebar-control"
-        htmlFor={`quick-jump-${workspaceId}`}
-      >
-        <ThemedIcon semantic="nav.search" size={14} aria-hidden="true" />
-        <input
-          id={`quick-jump-${workspaceId}`}
-          type="search"
-          className="workspace-quick-jump__input"
-          aria-label={t("workspace.quick_jump.title")}
-          placeholder={t("workspace.quick_jump.placeholder")}
-          value={query}
-          onChange={(event) => setQuery(event.target.value)}
-        />
-      </label>
+      {isExpanded ? (
+        <>
+          <label
+            className="workspace-quick-jump__search workspace-sidebar-control"
+            htmlFor={`quick-jump-${workspaceId}`}
+          >
+            <ThemedIcon semantic="nav.search" size={14} aria-hidden="true" />
+            <input
+              id={`quick-jump-${workspaceId}`}
+              type="search"
+              className="workspace-quick-jump__input"
+              aria-label={t("workspace.quick_jump.title")}
+              placeholder={t("workspace.quick_jump.placeholder")}
+              value={query}
+              onChange={(event) => setQuery(event.target.value)}
+            />
+          </label>
 
-      {hasQuery ? (
-        <div className="workspace-quick-jump__results">
-          {loading ? (
-            <p className="workspace-quick-jump__state">{t("common.loading")}</p>
-          ) : failed ? (
-            <p className="workspace-quick-jump__state">{t("workspace.quick_jump.failed")}</p>
-          ) : results.length === 0 ? (
-            <p className="workspace-quick-jump__state">{t("workspace.quick_jump.no_results")}</p>
-          ) : (
-            results.map((file) => (
-              <button
-                key={file.path}
-                type="button"
-                className="workspace-quick-jump__item workspace-sidebar-row"
-                aria-label={file.path}
-                onClick={() => {
-                  void openWorkspaceFile({
-                    workspaceId,
-                    path: file.path,
-                    source: "manual",
-                  });
-                  onSelectFile?.(file.path);
-                }}
-              >
-                <span className="workspace-quick-jump__primary">{file.name}</span>
-                <span className="workspace-quick-jump__secondary">{file.path}</span>
-              </button>
-            ))
-          )}
-        </div>
+          {hasQuery ? (
+            <div className="workspace-quick-jump__results">
+              {loading ? (
+                <p className="workspace-quick-jump__state">{t("common.loading")}</p>
+              ) : failed ? (
+                <p className="workspace-quick-jump__state">{t("workspace.quick_jump.failed")}</p>
+              ) : results.length === 0 ? (
+                <p className="workspace-quick-jump__state">
+                  {t("workspace.quick_jump.no_results")}
+                </p>
+              ) : (
+                results.map((file) => (
+                  <button
+                    key={file.path}
+                    type="button"
+                    className="workspace-quick-jump__item workspace-sidebar-row"
+                    aria-label={file.path}
+                    onClick={() => {
+                      void openWorkspaceFile(
+                        {
+                          workspaceId,
+                          path: file.path,
+                          source: "manual",
+                        },
+                        { openTarget: "navigate" }
+                      );
+                      onSelectFile?.(file.path);
+                    }}
+                  >
+                    <span className="workspace-quick-jump__primary">{file.name}</span>
+                    <span className="workspace-quick-jump__secondary">{file.path}</span>
+                  </button>
+                ))
+              )}
+            </div>
+          ) : null}
+        </>
       ) : null}
     </section>
   );
diff --git a/packages/web/src/features/workspace/views/shared/skills-panel.test.tsx b/packages/web/src/features/workspace/views/shared/skills-panel.test.tsx
index 0db64d1a9..6be1a57d0 100644
--- a/packages/web/src/features/workspace/views/shared/skills-panel.test.tsx
+++ b/packages/web/src/features/workspace/views/shared/skills-panel.test.tsx
@@ -1,16 +1,50 @@
 // @vitest-environment jsdom
 
 import { Topics } from "@coder-studio/core";
-import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import {
+  act,
+  fireEvent,
+  render,
+  renderHook,
+  screen,
+  waitFor,
+  within,
+} from "@testing-library/react";
 import { createStore, Provider } from "jotai";
+import type { ReactNode } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { wsClientAtom } from "../../../../atoms/connection";
+import { SKILL_PATH_DRAG_MIME } from "../../../../lib/skill-path-drag";
+import { useSkillsPanel } from "../../actions/use-skills-panel";
+import { activeFilePathAtomFamily } from "../../atoms";
 import { SkillsPanel } from "./skills-panel";
 
+const originalIntersectionObserver = global.IntersectionObserver;
+
 const translations: Record<string, string> = {
   "common.loading": "Loading...",
   "common.cancel": "Cancel",
+  "common.create": "Create",
+  "action.edit": "Edit",
+  "action.confirm": "Confirm",
+  "action.close": "Close",
   "skills.title": "Skill Library",
+  "skills.custom_title": "Custom Skills",
+  "skills.custom_expand_label": "Expand Custom Skills",
+  "skills.custom_collapse_label": "Collapse Custom Skills",
+  "skills.custom_new": "New Skill",
+  "skills.custom_empty": "No custom skills yet.",
+  "skills.custom_create_title": "Create Custom Skill",
+  "skills.custom_create_name": "Skill Name",
+  "skills.custom_create_name_required": "Enter a skill name",
+  "skills.custom_create_placeholder": "My Review Skill",
+  "skills.custom_create_helper":
+    "We will create a folder with SKILL.md under your global skills directory.",
+  "skills.custom_files_title": "Files",
+  "skills.custom_open": "Open",
+  "skills.custom_new_file": "New File",
+  "skills.custom_new_folder": "New Folder",
+  "skills.custom_delete": "Delete",
   "skills.discover_title": "Discover",
   "skills.recommendations_title": "Recommended",
   "skills.recommendations_expand_label": "Expand Recommendations",
@@ -44,8 +78,17 @@ const translations: Record<string, string> = {
   "skills.version_unknown": "Unknown",
   "skills.version_check_failed": "Check failed",
   "skills.uninstall": "Uninstall",
+  "skills.delete": "Delete",
   "skills.uninstall_tooltip":
     "Disable this skill first, then remove it from the shared skill library.",
+  "skills.custom_remove_tooltip":
+    "Delete this custom skill folder from your global skills directory.",
+  "skills.custom_remove_confirm_title": "Delete {{name}}?",
+  "skills.custom_remove_confirm_description":
+    "This permanently deletes the custom skill folder and all files under it from your global skills directory.",
+  "skills.custom_remove_confirm_mounted_description":
+    "This custom skill is enabled on {{count}} target(s). Deleting it will disable it first, then permanently delete the skill folder and all files under it from your global skills directory.",
+  "skills.custom_remove_confirm_confirm": "Delete Skill",
   "skills.uninstall_confirm_title": "Remove {{name}}?",
   "skills.uninstall_confirm_description":
     "This skill is enabled on {{count}} target(s). Removing it will disable it first, then delete it from the skill library.",
@@ -84,13 +127,23 @@ const translations: Record<string, string> = {
   "workspace.skills.status.installed": "Installed",
   "workspace.skills.status.installing": "Installing",
   "workspace.skills.status.failed": "Failed",
-  "workspace.skills.source.skillhub": "skills-hub",
-  "workspace.skills.source.local": "Local",
+  "workspace.skills.source.installed": "Installed",
+  "workspace.skills.source.custom": "Custom",
   "workspace.skills.source.builtin": "Built-in",
+  "workspace.skills.origin.skillhub": "skills-hub",
+  "workspace.skills.origin.filesystem": "Local",
   "skills.mount_state.unmounted": "Disabled",
   "skills.mount_state.partially_mounted": "Enabled",
   "skills.mount_state.fully_mounted": "Enabled",
   "skills.mount_state.error": "Error",
+  "file.path": "Path",
+  "file.path_required": "Path is required",
+  "file.invalid_file_path": "Invalid file path",
+  "file.create_failed": "Create failed",
+  "file.rename_required": "Name is required",
+  "file.rename_invalid_name": "Invalid name",
+  "file.rename_failed": "Rename failed",
+  "file.delete_failed": "Delete failed",
 };
 
 const translate = (key: string, params?: Record<string, unknown>) => {
@@ -118,6 +171,8 @@ function createSubscribeMock(): SubscribeMock {
   return vi.fn((_topics: string[], _handler: SkillLibraryEventHandler) => () => {});
 }
 
+const emptySkillRecommendationPage = { entries: [], hasMore: false };
+
 function renderPanel(sendCommand: ReturnType<typeof vi.fn>, subscribe = createSubscribeMock()) {
   const store = createStore();
   store.set(wsClientAtom, { sendCommand, subscribe } as never);
@@ -146,6 +201,40 @@ function renderPanelWithProps(
   return { ...view, store };
 }
 
+function wrapperFor(store: ReturnType<typeof createStore>) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <Provider store={store}>{children}</Provider>;
+  };
+}
+
+function createDragDataTransfer() {
+  const values = new Map<string, string>();
+  const types: string[] = [];
+  const dataTransfer: Pick<DataTransfer, "effectAllowed" | "getData" | "setData" | "types"> = {
+    types,
+    effectAllowed: "uninitialized" as DataTransfer["effectAllowed"],
+    setData: vi.fn((type: string, value: string) => {
+      if (!types.includes(type)) {
+        types.push(type);
+      }
+      values.set(type, value);
+    }),
+    getData: vi.fn((type: string) => values.get(type) ?? ""),
+  };
+
+  return { dataTransfer, values };
+}
+
+function createDeferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
 async function expandInstalledSection() {
   const installedHeading = await screen.findByRole("heading", {
     level: 2,
@@ -189,8 +278,19 @@ async function expandBuiltinSection() {
 }
 
 describe("SkillsPanel", () => {
+  let intersectionObserverInstances: Array<{
+    callback: IntersectionObserverCallback;
+    observe: ReturnType<typeof vi.fn>;
+    unobserve: ReturnType<typeof vi.fn>;
+    disconnect: ReturnType<typeof vi.fn>;
+    root: Element | Document | null;
+    rootMargin: string;
+    thresholds: readonly number[];
+  }>;
+
   beforeEach(() => {
     activeElementState.current = document.body;
+    intersectionObserverInstances = [];
 
     Object.defineProperty(document, "activeElement", {
       configurable: true,
@@ -208,6 +308,7 @@ describe("SkillsPanel", () => {
 
   afterEach(() => {
     vi.restoreAllMocks();
+    global.IntersectionObserver = originalIntersectionObserver;
 
     Object.defineProperty(HTMLElement.prototype, "focus", {
       configurable: true,
@@ -226,7 +327,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -246,10 +348,10 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
-    renderPanel(sendCommand);
+    renderPanelWithProps(sendCommand);
 
     expect(
       await screen.findByRole("heading", { level: 2, name: "Installed Skills" })
@@ -267,7 +369,7 @@ describe("SkillsPanel", () => {
     expect(screen.queryByText("Enabled")).not.toBeInTheDocument();
     expect(screen.getByText("Review code changes before merge")).toBeInTheDocument();
     expect(sendCommand).toHaveBeenCalledWith("skills.library.list", {}, undefined);
-  });
+  }, 10_000);
 
   it("refreshes skill state when the server broadcasts a library change", async () => {
     let eventHandler: SkillLibraryEventHandler | undefined;
@@ -285,7 +387,7 @@ describe("SkillsPanel", () => {
         return { targets: [], mounts: [] };
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand, subscribe);
@@ -322,7 +424,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -363,10 +466,10 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
-    renderPanel(sendCommand);
+    renderPanelWithProps(sendCommand);
 
     const installedSection = await expandInstalledSection();
 
@@ -396,7 +499,8 @@ describe("SkillsPanel", () => {
             displayName: "Dev Containers",
             description,
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/dev-containers",
             installState: "installed",
             installedAt: 1,
@@ -416,10 +520,10 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
-    renderPanel(sendCommand);
+    renderPanelWithProps(sendCommand);
 
     await expandInstalledSection();
     const descriptionNode = await screen.findByText(description);
@@ -441,7 +545,8 @@ describe("SkillsPanel", () => {
             displayName: "Command Control",
             description: "Coordinate command workflows",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/command-control",
             installState: "installed",
             installedAt: 1,
@@ -485,206 +590,1565 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      if (op === "skills.uninstall") {
-        return { deleted: true, slug: "command-control" };
+      if (op === "skills.uninstall") {
+        return { deleted: true, slug: "command-control" };
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    renderPanelWithProps(sendCommand);
+
+    await expandInstalledSection();
+    const skillCard = (await screen.findByText("Command Control")).closest("article");
+    if (!skillCard) {
+      throw new Error("Skill card not found");
+    }
+
+    fireEvent.click(within(skillCard).getByRole("button", { name: "Uninstall" }));
+
+    expect(screen.getByRole("dialog")).toHaveTextContent("Remove Command Control?");
+    expect(
+      sendCommand.mock.calls.some(
+        ([op, args]) =>
+          op === "skills.uninstall" &&
+          (args as { slug?: string; force?: boolean }).slug === "command-control"
+      )
+    ).toBe(false);
+
+    fireEvent.click(screen.getByRole("button", { name: "Remove Skill" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.uninstall",
+        { slug: "command-control", force: true },
+        undefined
+      );
+    });
+  });
+
+  it("renders installed, built-in, recommendations, and discover sections", async () => {
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") {
+        return [];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.targets.list") {
+        return [];
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    renderPanelWithProps(sendCommand);
+
+    expect(
+      await screen.findByRole("heading", { level: 2, name: "Installed Skills" })
+    ).toBeInTheDocument();
+    expect(screen.getByRole("heading", { level: 2, name: "Built-in Skills" })).toBeInTheDocument();
+    expect(screen.getByRole("heading", { level: 2, name: "Recommended" })).toBeInTheDocument();
+    expect(screen.getByRole("heading", { level: 2, name: "Discover" })).toBeInTheDocument();
+  });
+
+  it("renders recommended uninstalled skills", async () => {
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") {
+        return [];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.recommend") {
+        return {
+          entries: [
+            {
+              slug: "vite-testing",
+              displayName: "Vite Testing",
+              description:
+                "Testing Vite apps with a description long enough that it should be constrained to a single visible line.",
+              reason:
+                "Matches Vite and test scripts with a reason long enough that it should use the same one-line presentation.",
+              sourceQuery: "Vite",
+              score: 10,
+              installed: false,
+            },
+          ],
+          hasMore: false,
+        };
+      }
+
+      if (op === "skills.targets.list") {
+        return [];
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    renderPanel(sendCommand);
+
+    expect(
+      await screen.findByRole("heading", {
+        level: 2,
+        name: "Recommended",
+      })
+    ).toBeInTheDocument();
+    expect(await screen.findByText("Vite Testing")).toBeInTheDocument();
+    expect(
+      screen.queryByText(
+        "Testing Vite apps with a description long enough that it should be constrained to a single visible line."
+      )
+    ).toBeNull();
+    expect(
+      screen.getByText(
+        "Matches Vite and test scripts with a reason long enough that it should use the same one-line presentation."
+      )
+    ).toHaveClass("skills-panel__card-description--truncated");
+    const recommendationCard = screen.getByText("Vite Testing").closest("article");
+    if (!recommendationCard) {
+      throw new Error("Recommendation card not found");
+    }
+    const recommendationInstallButton = within(recommendationCard).getByRole("button", {
+      name: "Install",
+    });
+    const recommendationActions = recommendationInstallButton.closest(
+      ".skills-panel__card-head-actions"
+    );
+    expect(recommendationActions).not.toBeNull();
+    expect(recommendationActions).toContainElement(
+      within(recommendationCard).getByText("Available")
+    );
+    expect(sendCommand).toHaveBeenCalledWith(
+      "skills.recommend",
+      { workspaceId: "ws-1", limit: 20, offset: 0 },
+      undefined
+    );
+  });
+
+  it("appends the next recommendation page without duplicating slugs", async () => {
+    const sendCommand = vi.fn(async (op: string, args?: { offset?: number }) => {
+      if (op === "skills.library.list") {
+        return [];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.recommend" && args?.offset === 20) {
+        return {
+          entries: [
+            {
+              slug: "skill-20",
+              displayName: "Skill 20",
+              reason: "reason",
+              sourceQuery: "React",
+              score: 80,
+              installed: false,
+            },
+            {
+              slug: "skill-21",
+              displayName: "Skill 21",
+              reason: "reason",
+              sourceQuery: "React",
+              score: 79,
+              installed: false,
+            },
+          ],
+          hasMore: false,
+        };
+      }
+
+      if (op === "skills.recommend") {
+        return {
+          entries: Array.from({ length: 20 }, (_, index) => ({
+            slug: `skill-${index + 1}`,
+            displayName: `Skill ${index + 1}`,
+            reason: "reason",
+            sourceQuery: "React",
+            score: 100 - index,
+            installed: false,
+          })),
+          hasMore: true,
+        };
+      }
+
+      return [];
+    });
+
+    const store = createStore();
+    store.set(wsClientAtom, { sendCommand, subscribe: createSubscribeMock() } as never);
+
+    const { result } = renderHook(() => useSkillsPanel("ws-1"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.refreshRecommendations();
+    });
+
+    await waitFor(() => {
+      expect(result.current.recommendations).toHaveLength(20);
+      expect(result.current.recommendationsHasMore).toBe(true);
+    });
+
+    await act(async () => {
+      await result.current.loadMoreRecommendations();
+    });
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.recommend",
+        { workspaceId: "ws-1", limit: 20, offset: 20 },
+        undefined
+      );
+      expect(
+        result.current.recommendations.filter((entry) => entry.slug === "skill-20")
+      ).toHaveLength(1);
+      expect(result.current.recommendations.some((entry) => entry.slug === "skill-21")).toBe(true);
+      expect(result.current.recommendationsHasMore).toBe(false);
+    });
+  });
+
+  it("ignores stale recommendation pages after recommendations refresh", async () => {
+    const staleSecondPage = createDeferred<{
+      entries: Array<{
+        slug: string;
+        displayName: string;
+        reason: string;
+        sourceQuery: string;
+        score: number;
+        installed: boolean;
+      }>;
+      hasMore: boolean;
+    }>();
+    const initialFirstPage = Array.from({ length: 20 }, (_, index) => ({
+      slug: `initial-skill-${index + 1}`,
+      displayName: `Initial Skill ${index + 1}`,
+      reason: "initial reason",
+      sourceQuery: "React",
+      score: 100 - index,
+      installed: false,
+    }));
+    const refreshedFirstPage = Array.from({ length: 20 }, (_, index) => ({
+      slug: `refreshed-skill-${index + 1}`,
+      displayName: `Refreshed Skill ${index + 1}`,
+      reason: "refreshed reason",
+      sourceQuery: "TypeScript",
+      score: 200 - index,
+      installed: false,
+    }));
+    let firstPageCallCount = 0;
+
+    const sendCommand = vi.fn(async (op: string, args?: { offset?: number }) => {
+      if (op === "skills.library.list") {
+        return [];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.recommend" && args?.offset === 20) {
+        return staleSecondPage.promise;
+      }
+
+      if (op === "skills.recommend" && args?.offset === 0) {
+        firstPageCallCount += 1;
+        return firstPageCallCount === 1
+          ? { entries: initialFirstPage, hasMore: true }
+          : { entries: refreshedFirstPage, hasMore: false };
+      }
+
+      return [];
+    });
+
+    const store = createStore();
+    store.set(wsClientAtom, { sendCommand, subscribe: createSubscribeMock() } as never);
+
+    const { result } = renderHook(() => useSkillsPanel("ws-1"), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await result.current.refreshRecommendations();
+    });
+
+    await waitFor(() => {
+      expect(result.current.recommendations).toEqual(initialFirstPage);
+      expect(result.current.recommendationsHasMore).toBe(true);
+    });
+
+    let loadMorePromise: Promise<void> | undefined;
+    await act(async () => {
+      loadMorePromise = result.current.loadMoreRecommendations();
+    });
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.recommend",
+        { workspaceId: "ws-1", limit: 20, offset: 20 },
+        undefined
+      );
+      expect(result.current.loadingRecommendationPage).toBe(true);
+    });
+
+    await act(async () => {
+      await result.current.refreshRecommendations();
+    });
+
+    await waitFor(() => {
+      expect(result.current.recommendations).toEqual(refreshedFirstPage);
+      expect(result.current.recommendationsHasMore).toBe(false);
+      expect(result.current.loadingRecommendationPage).toBe(false);
+    });
+
+    await act(async () => {
+      staleSecondPage.resolve({
+        entries: [
+          {
+            slug: "stale-skill-21",
+            displayName: "Stale Skill 21",
+            reason: "stale reason",
+            sourceQuery: "React",
+            score: 80,
+            installed: false,
+          },
+        ],
+        hasMore: true,
+      });
+      await loadMorePromise;
+    });
+
+    await waitFor(() => {
+      expect(result.current.recommendations).toEqual(refreshedFirstPage);
+      expect(result.current.recommendations.some((entry) => entry.slug === "stale-skill-21")).toBe(
+        false
+      );
+      expect(result.current.recommendationsHasMore).toBe(false);
+    });
+  });
+
+  it("does not use an observer while recommendations are collapsed", async () => {
+    class IntersectionObserverMock {
+      readonly observe = vi.fn();
+      readonly unobserve = vi.fn();
+      readonly disconnect = vi.fn();
+      readonly root: Element | Document | null;
+      readonly rootMargin: string;
+      readonly thresholds: readonly number[];
+
+      constructor(callback: IntersectionObserverCallback, options?: IntersectionObserverInit) {
+        this.root = options?.root ?? null;
+        this.rootMargin = options?.rootMargin ?? "";
+        this.thresholds = Array.isArray(options?.threshold)
+          ? options.threshold
+          : [options?.threshold ?? 0];
+        intersectionObserverInstances.push({
+          callback,
+          observe: this.observe,
+          unobserve: this.unobserve,
+          disconnect: this.disconnect,
+          root: this.root,
+          rootMargin: this.rootMargin,
+          thresholds: this.thresholds,
+        });
+      }
+
+      takeRecords(): IntersectionObserverEntry[] {
+        return [];
+      }
+    }
+    global.IntersectionObserver =
+      IntersectionObserverMock as unknown as typeof IntersectionObserver;
+
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") {
+        return [];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.recommend") {
+        return {
+          entries: [
+            {
+              slug: "vite-testing",
+              displayName: "Vite Testing",
+              reason: "reason",
+              sourceQuery: "Vite",
+              score: 10,
+              installed: false,
+            },
+          ],
+          hasMore: true,
+        };
+      }
+
+      if (op === "skills.targets.list") {
+        return [];
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    renderPanel(sendCommand);
+
+    const recommendationsHeading = await screen.findByRole("heading", {
+      level: 2,
+      name: "Recommended",
+    });
+    const recommendationsSection = recommendationsHeading.closest("section");
+    if (!recommendationsSection) {
+      throw new Error("Recommendations section not found");
+    }
+
+    const toggle = within(recommendationsSection).getByRole("button", {
+      name: "Collapse Recommendations",
+    });
+
+    await waitFor(() => {
+      expect(intersectionObserverInstances).toHaveLength(1);
+    });
+    expect(intersectionObserverInstances[0]?.observe).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(toggle);
+
+    await waitFor(() => {
+      expect(toggle).toHaveAttribute("aria-expanded", "false");
+    });
+    expect(screen.queryByTestId("skills-recommendations-sentinel")).toBeNull();
+    expect(intersectionObserverInstances).toHaveLength(1);
+    expect(intersectionObserverInstances[0]?.disconnect).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(toggle);
+
+    await waitFor(() => {
+      expect(screen.getByText("Vite Testing")).toBeInTheDocument();
+    });
+    expect(screen.getByTestId("skills-recommendations-sentinel")).toBeInTheDocument();
+    expect(intersectionObserverInstances).toHaveLength(2);
+    expect(intersectionObserverInstances[1]?.observe).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-observes recommendations after returning from skill details", async () => {
+    class IntersectionObserverMock {
+      readonly observe = vi.fn();
+      readonly unobserve = vi.fn();
+      readonly disconnect = vi.fn();
+      readonly root: Element | Document | null;
+      readonly rootMargin: string;
+      readonly thresholds: readonly number[];
+
+      constructor(callback: IntersectionObserverCallback, options?: IntersectionObserverInit) {
+        this.root = options?.root ?? null;
+        this.rootMargin = options?.rootMargin ?? "";
+        this.thresholds = Array.isArray(options?.threshold)
+          ? options.threshold
+          : [options?.threshold ?? 0];
+        intersectionObserverInstances.push({
+          callback,
+          observe: this.observe,
+          unobserve: this.unobserve,
+          disconnect: this.disconnect,
+          root: this.root,
+          rootMargin: this.rootMargin,
+          thresholds: this.thresholds,
+        });
+      }
+
+      takeRecords(): IntersectionObserverEntry[] {
+        return [];
+      }
+    }
+    global.IntersectionObserver =
+      IntersectionObserverMock as unknown as typeof IntersectionObserver;
+
+    const sendCommand = vi.fn(async (op: string, args?: { offset?: number; slug?: string }) => {
+      if (op === "skills.library.list") {
+        return [];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.recommend" && args?.offset === 20) {
+        return {
+          entries: [
+            {
+              slug: "skill-21",
+              displayName: "Skill 21",
+              reason: "reason",
+              sourceQuery: "React",
+              score: 79,
+              installed: false,
+            },
+          ],
+          hasMore: false,
+        };
+      }
+
+      if (op === "skills.recommend") {
+        return {
+          entries: Array.from({ length: 20 }, (_, index) => ({
+            slug: `skill-${index + 1}`,
+            displayName: `Skill ${index + 1}`,
+            reason: "reason",
+            sourceQuery: "React",
+            score: 100 - index,
+            installed: false,
+          })),
+          hasMore: true,
+        };
+      }
+
+      if (op === "skills.info" && args?.slug === "skill-1") {
+        return {
+          slug: "skill-1",
+          displayName: "Skill 1",
+          description: "Skill 1 details",
+          installed: false,
+          mounts: [],
+        };
+      }
+
+      if (op === "skills.targets.list") {
+        return [];
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    renderPanel(sendCommand);
+
+    await waitFor(() => {
+      expect(screen.getByText("Skill 1")).toBeInTheDocument();
+      expect(intersectionObserverInstances).toHaveLength(1);
+    });
+
+    const firstSentinel = screen.getByTestId("skills-recommendations-sentinel");
+    expect(intersectionObserverInstances[0]?.observe).toHaveBeenCalledWith(firstSentinel);
+
+    fireEvent.click(screen.getByRole("button", { name: "Open Skill 1 details" }));
+
+    expect(await screen.findByRole("heading", { level: 2, name: "Skill 1" })).toBeInTheDocument();
+    expect(intersectionObserverInstances[0]?.disconnect).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(screen.getByRole("button", { name: "Back to skills" }));
+
+    await waitFor(() => {
+      expect(screen.getByText("Skill 1")).toBeInTheDocument();
+      expect(intersectionObserverInstances).toHaveLength(2);
+    });
+
+    const remountedSentinel = screen.getByTestId("skills-recommendations-sentinel");
+    expect(intersectionObserverInstances[1]?.observe).toHaveBeenCalledWith(remountedSentinel);
+
+    await act(async () => {
+      intersectionObserverInstances[1]?.callback(
+        [{ isIntersecting: true, target: remountedSentinel } as IntersectionObserverEntry],
+        {} as IntersectionObserver
+      );
+    });
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.recommend",
+        { workspaceId: "ws-1", limit: 20, offset: 20 },
+        undefined
+      );
+      expect(screen.getByText("Skill 21")).toBeInTheDocument();
+    });
+  });
+
+  it("renders next-page loading text only at the recommendations footer", async () => {
+    class IntersectionObserverMock {
+      readonly observe = vi.fn();
+      readonly unobserve = vi.fn();
+      readonly disconnect = vi.fn();
+      readonly root: Element | Document | null;
+      readonly rootMargin: string;
+      readonly thresholds: readonly number[];
+
+      constructor(callback: IntersectionObserverCallback, options?: IntersectionObserverInit) {
+        this.root = options?.root ?? null;
+        this.rootMargin = options?.rootMargin ?? "";
+        this.thresholds = Array.isArray(options?.threshold)
+          ? options.threshold
+          : [options?.threshold ?? 0];
+        intersectionObserverInstances.push({
+          callback,
+          observe: this.observe,
+          unobserve: this.unobserve,
+          disconnect: this.disconnect,
+          root: this.root,
+          rootMargin: this.rootMargin,
+          thresholds: this.thresholds,
+        });
+      }
+
+      takeRecords(): IntersectionObserverEntry[] {
+        return [];
+      }
+    }
+    global.IntersectionObserver =
+      IntersectionObserverMock as unknown as typeof IntersectionObserver;
+
+    const secondPage = createDeferred<{
+      entries: Array<{
+        slug: string;
+        displayName: string;
+        reason: string;
+        sourceQuery: string;
+        score: number;
+        installed: boolean;
+      }>;
+      hasMore: boolean;
+    }>();
+
+    const sendCommand = vi.fn(async (op: string, args?: { offset?: number }) => {
+      if (op === "skills.library.list") {
+        return [];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.recommend" && args?.offset === 20) {
+        return secondPage.promise;
+      }
+
+      if (op === "skills.recommend") {
+        return {
+          entries: Array.from({ length: 20 }, (_, index) => ({
+            slug: `skill-${index + 1}`,
+            displayName: `Skill ${index + 1}`,
+            reason: "reason",
+            sourceQuery: "React",
+            score: 100 - index,
+            installed: false,
+          })),
+          hasMore: true,
+        };
+      }
+
+      if (op === "skills.targets.list") {
+        return [];
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    const { container } = renderPanel(sendCommand);
+
+    await waitFor(() => {
+      expect(screen.getByText("Skill 1")).toBeInTheDocument();
+    });
+    await waitFor(() => {
+      expect(intersectionObserverInstances).toHaveLength(1);
+    });
+
+    const sentinel = screen.getByTestId("skills-recommendations-sentinel");
+    await act(async () => {
+      intersectionObserverInstances[0]?.callback(
+        [{ isIntersecting: true, target: sentinel } as IntersectionObserverEntry],
+        {} as IntersectionObserver
+      );
+    });
+
+    const loadingStates = await screen.findAllByText("Loading...");
+    expect(loadingStates).toHaveLength(1);
+
+    const recommendationsList = sentinel.closest(".skills-panel__recommendations-list");
+    expect(recommendationsList).not.toBeNull();
+    expect(recommendationsList).toContainElement(loadingStates[0] ?? null);
+    expect(
+      container.querySelector(
+        ".skills-panel__recommendations-list > p.workspace-search-panel__state"
+      )
+    ).not.toBeNull();
+    expect(screen.getByText("Skill 1")).toBeInTheDocument();
+
+    secondPage.resolve({
+      entries: [
+        {
+          slug: "skill-21",
+          displayName: "Skill 21",
+          reason: "reason",
+          sourceQuery: "React",
+          score: 79,
+          installed: false,
+        },
+      ],
+      hasMore: false,
+    });
+
+    await waitFor(() => {
+      expect(screen.getByText("Skill 21")).toBeInTheDocument();
+    });
+  });
+
+  it("reloads recommendations from the first page when the panel refresh token changes", async () => {
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") {
+        return [];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.recommend") {
+        return {
+          entries: [],
+          hasMore: false,
+        };
+      }
+
+      if (op === "skills.targets.list") {
+        return [];
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    const { rerender, store } = renderPanelWithProps(sendCommand, 0);
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.recommend",
+        { workspaceId: "ws-1", limit: 20, offset: 0 },
+        undefined
+      );
+    });
+
+    const recommendationCallsBeforeRefresh = sendCommand.mock.calls.filter(
+      ([op]) => op === "skills.recommend"
+    ).length;
+
+    rerender(
+      <Provider store={store}>
+        <SkillsPanel workspaceId="ws-1" refreshToken={1} />
+      </Provider>
+    );
+
+    await waitFor(() => {
+      expect(
+        sendCommand.mock.calls.filter(
+          ([op, args]) =>
+            op === "skills.recommend" &&
+            args?.workspaceId === "ws-1" &&
+            args?.limit === 20 &&
+            args?.offset === 0
+        ).length
+      ).toBeGreaterThan(recommendationCallsBeforeRefresh);
+    });
+  });
+
+  it("shows local skill versions without source labels in installed skill cards", async () => {
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") {
+        return [
+          {
+            slug: "code-review",
+            displayName: "Code Review",
+            description: "Review code changes before merge",
+            version: "local",
+            source: "custom",
+            origin: "filesystem",
+            libraryPath: "/users/spencer/.agents/skills/code-review",
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 2,
+            mountedProviderIds: [],
+            mountStatus: "unmounted",
+            errorCount: 0,
+          },
+        ];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.targets.list") {
+        return [];
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    renderPanel(sendCommand);
+
+    await expandInstalledSection();
+    const skillCard = (await screen.findByText("Code Review")).closest("article");
+    if (!skillCard) {
+      throw new Error("Skill card not found");
+    }
+
+    expect(within(skillCard).getByText("code-review")).toBeInTheDocument();
+    expect(within(skillCard).getByText("local")).toBeInTheDocument();
+    expect(within(skillCard).queryByText("Local")).toBeNull();
+  });
+
+  it("groups unified sources and limits labels and actions by origin", async () => {
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") {
+        return [
+          {
+            slug: "review-ops-skill",
+            displayName: "Review Ops Skill",
+            description: "Run structured acceptance checks.",
+            version: "local",
+            source: "custom",
+            origin: "filesystem",
+            libraryPath: "/Users/spencer/.coder-studio/state/skills/custom/review-ops-skill",
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 2,
+            mountedProviderIds: ["codex"],
+            mountStatus: "partially_mounted",
+            errorCount: 0,
+          },
+          {
+            slug: "external-review",
+            displayName: "External Review",
+            description: "External filesystem skill.",
+            version: "local",
+            source: "installed",
+            origin: "filesystem",
+            libraryPath: "/Users/spencer/.agents/skills/external-review",
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 2,
+            mountedProviderIds: ["codex"],
+            mountStatus: "fully_mounted",
+            errorCount: 0,
+          },
+          {
+            slug: "code-review",
+            displayName: "Code Review",
+            description: "Review code changes before merge.",
+            version: "1.2.3",
+            source: "installed",
+            origin: "skillhub",
+            libraryPath: "/skills/library/code-review",
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 2,
+            mountedProviderIds: [],
+            mountStatus: "unmounted",
+            errorCount: 0,
+          },
+          {
+            slug: "coder-studio-open",
+            displayName: "Coder Studio Open",
+            description: "Open files for the user.",
+            version: "1.0.0",
+            source: "builtin",
+            origin: "builtin",
+            libraryPath: "/skills/builtin/coder-studio-open",
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 2,
+            mountedProviderIds: ["codex"],
+            mountStatus: "fully_mounted",
+            errorCount: 0,
+            builtin: { defaultEnabled: true, autoMount: true },
+          },
+        ];
+      }
+
+      if (op === "skills.health.scan") {
+        return {
+          targets: [
+            {
+              providerId: "codex",
+              displayName: "Codex",
+              kind: "built_in",
+              skillDir: "/Users/test/.codex/skills",
+              mountPreference: "auto",
+              lastHealthState: "healthy",
+              lastHealthError: null,
+              mountedSkillCount: 3,
+            },
+          ],
+          mounts: [
+            {
+              providerId: "codex",
+              skillSlug: "review-ops-skill",
+              enabled: true,
+              sourcePath: "/Users/spencer/.coder-studio/state/skills/custom/review-ops-skill",
+              targetPath: "/Users/test/.codex/skills/review-ops-skill",
+              mountModeResolved: "symlink",
+              status: "mounted",
+            },
+            {
+              providerId: "codex",
+              skillSlug: "external-review",
+              enabled: true,
+              sourcePath: "/Users/spencer/.agents/skills/external-review",
+              targetPath: "/Users/test/.codex/skills/external-review",
+              mountModeResolved: "symlink",
+              status: "mounted",
+            },
+            {
+              providerId: "codex",
+              skillSlug: "coder-studio-open",
+              enabled: true,
+              sourcePath: "/skills/builtin/coder-studio-open",
+              targetPath: "/Users/test/.codex/skills/coder-studio-open",
+              mountModeResolved: "symlink",
+              status: "mounted",
+            },
+          ],
+        };
+      }
+
+      if (op === "skills.targets.list") {
+        return [];
+      }
+
+      if (op === "skills.versions.check") {
+        return [
+          {
+            slug: "code-review",
+            currentVersion: "1.2.3",
+            latestVersion: "1.3.0",
+            status: "update_available",
+          },
+        ];
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    renderPanel(sendCommand);
+
+    const customHeading = await screen.findByRole("heading", { level: 2, name: "Custom Skills" });
+    const customSection = customHeading.closest("section");
+    if (!customSection) {
+      throw new Error("Custom section not found");
+    }
+
+    const installedSection = await expandInstalledSection();
+    const builtinSection = await expandBuiltinSection();
+
+    expect(within(customSection).getByText("Review Ops Skill")).toBeInTheDocument();
+    expect(within(installedSection).getByText("External Review")).toBeInTheDocument();
+    expect(within(installedSection).getByText("Code Review")).toBeInTheDocument();
+    expect(within(builtinSection).getByText("Coder Studio Open")).toBeInTheDocument();
+    expect(screen.queryAllByText("Review Ops Skill")).toHaveLength(1);
+
+    const filesystemCard = (await within(installedSection).findByText("External Review")).closest(
+      "article"
+    );
+    const skillHubCard = (await within(installedSection).findByText("Code Review")).closest(
+      "article"
+    );
+    if (!filesystemCard || !skillHubCard) {
+      throw new Error("Installed skill cards not found");
+    }
+
+    expect(within(filesystemCard).getByText("Local")).toBeInTheDocument();
+    expect(within(filesystemCard).queryByRole("button", { name: "Update" })).toBeNull();
+    expect(within(filesystemCard).queryByRole("button", { name: "Uninstall" })).toBeNull();
+
+    fireEvent.click(within(installedSection).getByRole("button", { name: "Check versions" }));
+    expect(await within(skillHubCard).findByRole("button", { name: "Update" })).toBeVisible();
+
+    fireEvent.click(await within(customSection).findByText("Review Ops Skill"));
+    expect(
+      await screen.findByRole("heading", { level: 2, name: "Review Ops Skill" })
+    ).toBeVisible();
+    expect(screen.getByRole("button", { name: "New File" })).toBeVisible();
+
+    fireEvent.click(screen.getByRole("button", { name: "Back to skills" }));
+    const refreshedInstalledSection = await expandInstalledSection();
+    fireEvent.click(await within(refreshedInstalledSection).findByText("External Review"));
+    expect(await screen.findByRole("heading", { level: 2, name: "External Review" })).toBeVisible();
+    expect(screen.queryByRole("button", { name: "New File" })).toBeNull();
+  });
+
+  it("renders custom skills in a dedicated section and creates a new custom skill", async () => {
+    let libraryEntries: Array<Record<string, unknown>> = [];
+
+    const sendCommand = vi.fn(async (op: string, args?: Record<string, unknown>) => {
+      if (op === "skills.library.list") {
+        return libraryEntries;
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.custom.create") {
+        const entry = {
+          slug: "my-review-skill",
+          displayName: "My Review Skill",
+          description: undefined,
+          version: "local",
+          source: "custom",
+          origin: "filesystem",
+          libraryPath: "/root/.agents/skills/my-review-skill",
+          installState: "installed",
+          installedAt: 1,
+          updatedAt: 1,
+        };
+        libraryEntries = [entry];
+        return entry;
+      }
+
+      if (op === "skills.files.readTree") {
+        return {
+          path: ".",
+          children: [
+            {
+              name: "SKILL.md",
+              path: "SKILL.md",
+              kind: "file",
+            },
+          ],
+        };
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    const { store } = renderPanelWithProps(sendCommand);
+
+    const heading = await screen.findByRole("heading", { level: 2, name: "Custom Skills" });
+    const section = heading.closest("section");
+    if (!section) {
+      throw new Error("Custom skills section not found");
+    }
+
+    expect(within(section).getByRole("button", { name: "Collapse Custom Skills" })).toHaveAttribute(
+      "aria-expanded",
+      "true"
+    );
+    expect(await within(section).findByText("No custom skills yet.")).toBeInTheDocument();
+
+    fireEvent.click(within(section).getByRole("button", { name: "New Skill" }));
+
+    const nameInput = await screen.findByLabelText("Skill Name");
+    fireEvent.change(nameInput, { target: { value: "My Review Skill" } });
+    fireEvent.click(screen.getByRole("button", { name: "Create" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.custom.create",
+        {
+          name: "My Review Skill",
+        },
+        undefined
+      );
+    });
+
+    expect(
+      await screen.findByRole("heading", { level: 2, name: "My Review Skill" })
+    ).toBeInTheDocument();
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.files.readTree",
+        {
+          skillSlug: "my-review-skill",
+        },
+        undefined
+      );
+    });
+    await waitFor(() => {
+      expect(store.get(activeFilePathAtomFamily("ws-1"))).toBe("skill:my-review-skill/SKILL.md");
+    });
+  });
+
+  it("shows a real validation error when the custom skill name is empty", async () => {
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") {
+        return [];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    renderPanel(sendCommand);
+
+    const heading = await screen.findByRole("heading", { level: 2, name: "Custom Skills" });
+    const section = heading.closest("section");
+    if (!section) {
+      throw new Error("Custom skills section not found");
+    }
+
+    fireEvent.click(within(section).getByRole("button", { name: "New Skill" }));
+    fireEvent.click(await screen.findByRole("button", { name: "Create" }));
+
+    expect(await screen.findByText("Enter a skill name")).toBeInTheDocument();
+    expect(sendCommand).not.toHaveBeenCalledWith(
+      "skills.custom.create",
+      expect.anything(),
+      undefined
+    );
+  });
+
+  it("requires confirmation before deleting a custom skill that is not mounted", async () => {
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "skills.library.list") {
+        return [
+          {
+            slug: "my-review-skill",
+            displayName: "My Review Skill",
+            description: "Local review helper",
+            version: "local",
+            source: "custom",
+            origin: "filesystem",
+            libraryPath: "/root/.agents/skills/my-review-skill",
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 1,
+            mountedProviderIds: [],
+            mountStatus: "unmounted",
+            errorCount: 0,
+          },
+        ];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.targets.list") {
+        return [];
+      }
+
+      if (op === "skills.uninstall") {
+        return { deleted: true, slug: "my-review-skill" };
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
+    });
+
+    renderPanelWithProps(sendCommand);
+
+    const customHeading = await screen.findByRole("heading", { level: 2, name: "Custom Skills" });
+    const customSection = customHeading.closest("section");
+    if (!customSection) {
+      throw new Error("Custom skills section not found");
+    }
+
+    const skillCard = (await within(customSection).findByText("My Review Skill")).closest(
+      "article"
+    );
+    if (!skillCard) {
+      throw new Error("Custom skill card not found");
+    }
+
+    fireEvent.click(within(skillCard).getByRole("button", { name: "Delete" }));
+
+    expect(screen.getByRole("dialog")).toHaveTextContent("Delete My Review Skill?");
+    expect(
+      sendCommand.mock.calls.some(
+        ([op, args]) =>
+          op === "skills.uninstall" &&
+          (args as { slug?: string; force?: boolean }).slug === "my-review-skill"
+      )
+    ).toBe(false);
+
+    fireEvent.click(screen.getByRole("button", { name: "Delete Skill" }));
+
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.uninstall",
+        { slug: "my-review-skill", force: true },
+        undefined
+      );
+    });
+  });
+
+  it("shows local skill files in detail view and opens files through the existing editor path flow", async () => {
+    const sendCommand = vi.fn(async (op: string, args?: Record<string, unknown>) => {
+      if (op === "skills.library.list") {
+        return [
+          {
+            slug: "my-review-skill",
+            displayName: "My Review Skill",
+            description: "Custom review workflow",
+            version: "local",
+            source: "custom",
+            origin: "filesystem",
+            libraryPath: "/root/.agents/skills/my-review-skill",
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 1,
+            mountedProviderIds: [],
+            mountStatus: "unmounted",
+            errorCount: 0,
+          },
+        ];
+      }
+
+      if (op === "skills.health.scan") {
+        return { targets: [], mounts: [] };
+      }
+
+      if (op === "skills.files.readTree") {
+        const path = args?.path;
+        if (path === "refs") {
+          return {
+            path: "refs",
+            children: [
+              {
+                name: "guide.md",
+                path: "refs/guide.md",
+                kind: "file",
+              },
+            ],
+          };
+        }
+
+        return {
+          path: ".",
+          children: [
+            {
+              name: "refs",
+              path: "refs",
+              kind: "dir",
+            },
+            {
+              name: "SKILL.md",
+              path: "SKILL.md",
+              kind: "file",
+            },
+          ],
+        };
+      }
+
+      if (op === "workspace.uiState.set") {
+        return {
+          id: "ws-1",
+          path: "/workspace",
+          targetRuntime: "native",
+          openedAt: 1,
+          lastActiveAt: 1,
+          uiState: args?.uiState,
+        };
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
-    renderPanel(sendCommand);
+    const { store } = renderPanelWithProps(sendCommand);
 
-    await expandInstalledSection();
-    const skillCard = (await screen.findByText("Command Control")).closest("article");
-    if (!skillCard) {
-      throw new Error("Skill card not found");
+    const customHeading = await screen.findByRole("heading", { level: 2, name: "Custom Skills" });
+    const customSection = customHeading.closest("section");
+    if (!customSection) {
+      throw new Error("Custom skills section not found");
     }
 
-    fireEvent.click(within(skillCard).getByRole("button", { name: "Uninstall" }));
-
-    expect(screen.getByRole("dialog")).toHaveTextContent("Remove Command Control?");
     expect(
-      sendCommand.mock.calls.some(
-        ([op, args]) =>
-          op === "skills.uninstall" &&
-          (args as { slug?: string; force?: boolean }).slug === "command-control"
-      )
-    ).toBe(false);
+      within(customSection).getByRole("button", { name: "Collapse Custom Skills" })
+    ).toHaveAttribute("aria-expanded", "true");
+    fireEvent.click(await within(customSection).findByText("My Review Skill"));
 
-    fireEvent.click(screen.getByRole("button", { name: "Remove Skill" }));
+    expect(await screen.findByText("Custom review workflow")).toBeInTheDocument();
+    expect(await screen.findByRole("heading", { level: 3, name: "Files" })).toBeInTheDocument();
+    expect(await screen.findByText("SKILL.md")).toBeInTheDocument();
+    expect(await screen.findByText("refs")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByText("refs"));
 
     await waitFor(() => {
       expect(sendCommand).toHaveBeenCalledWith(
-        "skills.uninstall",
-        { slug: "command-control", force: true },
+        "skills.files.readTree",
+        {
+          skillSlug: "my-review-skill",
+          path: "refs",
+        },
         undefined
       );
     });
+    expect(await screen.findByText("guide.md")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByText("guide.md"));
+
+    expect(store.get(activeFilePathAtomFamily("ws-1"))).toBe("skill:my-review-skill/refs/guide.md");
   });
 
-  it("renders installed, built-in, recommendations, and discover sections", async () => {
-    const sendCommand = vi.fn(async (op: string) => {
+  it("collapses an expanded local skill directory without reloading it", async () => {
+    const sendCommand = vi.fn(async (op: string, args?: Record<string, unknown>) => {
       if (op === "skills.library.list") {
-        return [];
+        return [
+          {
+            slug: "my-review-skill",
+            displayName: "My Review Skill",
+            description: "Custom review workflow",
+            version: "local",
+            source: "custom",
+            origin: "filesystem",
+            libraryPath: "/root/.agents/skills/my-review-skill",
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 1,
+            mountedProviderIds: [],
+            mountStatus: "unmounted",
+            errorCount: 0,
+          },
+        ];
       }
 
       if (op === "skills.health.scan") {
         return { targets: [], mounts: [] };
       }
 
-      if (op === "skills.targets.list") {
-        return [];
+      if (op === "skills.files.readTree") {
+        const path = args?.path;
+        if (path === "refs") {
+          return {
+            path: "refs",
+            children: [
+              {
+                name: "guide.md",
+                path: "refs/guide.md",
+                kind: "file",
+              },
+            ],
+          };
+        }
+
+        return {
+          path: ".",
+          children: [
+            {
+              name: "refs",
+              path: "refs",
+              kind: "dir",
+            },
+            {
+              name: "SKILL.md",
+              path: "SKILL.md",
+              kind: "file",
+            },
+          ],
+        };
       }
 
-      return [];
+      if (op === "workspace.uiState.set") {
+        return {
+          id: "ws-1",
+          path: "/workspace",
+          targetRuntime: "native",
+          openedAt: 1,
+          lastActiveAt: 1,
+          uiState: args?.uiState,
+        };
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
 
-    expect(
-      await screen.findByRole("heading", { level: 2, name: "Installed Skills" })
-    ).toBeInTheDocument();
-    expect(screen.getByRole("heading", { level: 2, name: "Built-in Skills" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { level: 2, name: "Recommended" })).toBeInTheDocument();
-    expect(screen.getByRole("heading", { level: 2, name: "Discover" })).toBeInTheDocument();
-  });
+    const customHeading = await screen.findByRole("heading", { level: 2, name: "Custom Skills" });
+    const customSection = customHeading.closest("section");
+    if (!customSection) {
+      throw new Error("Custom skills section not found");
+    }
 
-  it("renders recommended uninstalled skills", async () => {
-    const sendCommand = vi.fn(async (op: string) => {
-      if (op === "skills.library.list") {
-        return [];
-      }
+    fireEvent.click(await within(customSection).findByText("My Review Skill"));
 
-      if (op === "skills.health.scan") {
-        return { targets: [], mounts: [] };
-      }
+    const refsButton = await screen.findByRole("button", { name: "refs" });
+    fireEvent.click(refsButton);
 
-      if (op === "skills.recommend") {
-        return [
-          {
-            slug: "vite-testing",
-            displayName: "Vite Testing",
-            description:
-              "Testing Vite apps with a description long enough that it should be constrained to a single visible line.",
-            reason:
-              "Matches Vite and test scripts with a reason long enough that it should use the same one-line presentation.",
-            sourceQuery: "Vite",
-            score: 10,
-            installed: false,
-          },
-        ];
-      }
+    expect(await screen.findByText("guide.md")).toBeInTheDocument();
 
-      if (op === "skills.targets.list") {
-        return [];
-      }
+    fireEvent.click(refsButton);
 
-      return [];
+    await waitFor(() => {
+      expect(screen.queryByText("guide.md")).toBeNull();
     });
 
-    renderPanel(sendCommand);
-
-    expect(
-      await screen.findByRole("heading", {
-        level: 2,
-        name: "Recommended",
-      })
-    ).toBeInTheDocument();
-    expect(await screen.findByText("Vite Testing")).toBeInTheDocument();
-    expect(
-      screen.queryByText(
-        "Testing Vite apps with a description long enough that it should be constrained to a single visible line."
-      )
-    ).toBeNull();
     expect(
-      screen.getByText(
-        "Matches Vite and test scripts with a reason long enough that it should use the same one-line presentation."
+      sendCommand.mock.calls.filter(
+        ([op, args]) => op === "skills.files.readTree" && args?.path === "refs"
       )
-    ).toHaveClass("skills-panel__card-description--truncated");
-    const recommendationCard = screen.getByText("Vite Testing").closest("article");
-    if (!recommendationCard) {
-      throw new Error("Recommendation card not found");
-    }
-    const recommendationInstallButton = within(recommendationCard).getByRole("button", {
-      name: "Install",
-    });
-    const recommendationActions = recommendationInstallButton.closest(
-      ".skills-panel__card-head-actions"
-    );
-    expect(recommendationActions).not.toBeNull();
-    expect(recommendationActions).toContainElement(
-      within(recommendationCard).getByText("Available")
-    );
-    expect(sendCommand).toHaveBeenCalledWith(
-      "skills.recommend",
-      { workspaceId: "ws-1" },
-      undefined
-    );
-  });
+    ).toHaveLength(1);
+  }, 10_000);
 
-  it("refreshes recommendations when the panel refresh token changes", async () => {
-    const sendCommand = vi.fn(async (op: string) => {
+  it("supports lightweight create, rename, and delete actions for local skill files", async () => {
+    const sendCommand = vi.fn(async (op: string, args?: Record<string, unknown>) => {
       if (op === "skills.library.list") {
-        return [];
+        return [
+          {
+            slug: "my-review-skill",
+            displayName: "My Review Skill",
+            description: "Custom review workflow",
+            version: "local",
+            source: "custom",
+            origin: "filesystem",
+            libraryPath: "/root/.agents/skills/my-review-skill",
+            installState: "installed",
+            installedAt: 1,
+            updatedAt: 1,
+            mountedProviderIds: [],
+            mountStatus: "unmounted",
+            errorCount: 0,
+          },
+        ];
       }
 
       if (op === "skills.health.scan") {
         return { targets: [], mounts: [] };
       }
 
-      if (op === "skills.recommend") {
-        return [];
+      if (op === "skills.files.readTree") {
+        const path = args?.path;
+        if (path === "refs") {
+          return {
+            path: "refs",
+            children: [
+              {
+                name: "guide.md",
+                path: "refs/guide.md",
+                kind: "file",
+              },
+            ],
+          };
+        }
+
+        return {
+          path: ".",
+          children: [
+            {
+              name: "refs",
+              path: "refs",
+              kind: "dir",
+            },
+            {
+              name: "SKILL.md",
+              path: "SKILL.md",
+              kind: "file",
+            },
+          ],
+        };
       }
 
-      if (op === "skills.targets.list") {
-        return [];
+      if (op === "skills.files.mkdir") {
+        return { ok: true };
       }
 
-      return [];
+      if (op === "skills.files.rename") {
+        return { ok: true };
+      }
+
+      if (op === "skills.files.delete") {
+        return { ok: true };
+      }
+
+      if (op === "workspace.uiState.set") {
+        return {
+          id: "ws-1",
+          path: "/workspace",
+          targetRuntime: "native",
+          openedAt: 1,
+          lastActiveAt: 1,
+          uiState: args?.uiState,
+        };
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
-    const { rerender, store } = renderPanelWithProps(sendCommand, 0);
+    renderPanel(sendCommand);
+
+    const customHeading = await screen.findByRole("heading", { level: 2, name: "Custom Skills" });
+    const customSection = customHeading.closest("section");
+    if (!customSection) {
+      throw new Error("Custom skills section not found");
+    }
+
+    fireEvent.click(await within(customSection).findByText("My Review Skill"));
+    fireEvent.click(await screen.findByText("refs"));
+    expect(await screen.findByText("guide.md")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "New Folder" }));
+    fireEvent.change(await screen.findByLabelText("Path"), {
+      target: { value: "refs/checklists" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Create" }));
 
     await waitFor(() => {
       expect(sendCommand).toHaveBeenCalledWith(
-        "skills.recommend",
-        { workspaceId: "ws-1" },
+        "skills.files.mkdir",
+        {
+          skillSlug: "my-review-skill",
+          path: "refs/checklists",
+        },
         undefined
       );
     });
 
-    const recommendationCallsBeforeRefresh = sendCommand.mock.calls.filter(
-      ([op]) => op === "skills.recommend"
-    ).length;
+    fireEvent.click(screen.getByRole("button", { name: "Edit refs" }));
+    fireEvent.change(document.getElementById("custom-skill-rename") as HTMLInputElement, {
+      target: { value: "references" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Confirm" }));
 
-    rerender(
-      <Provider store={store}>
-        <SkillsPanel workspaceId="ws-1" refreshToken={1} />
-      </Provider>
-    );
+    await waitFor(() => {
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.files.rename",
+        {
+          skillSlug: "my-review-skill",
+          fromPath: "refs",
+          toPath: "references",
+        },
+        undefined
+      );
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Delete guide.md" }));
+    fireEvent.click(screen.getByRole("button", { name: "Confirm" }));
 
     await waitFor(() => {
-      const recommendationCallsAfterRefresh = sendCommand.mock.calls.filter(
-        ([op]) => op === "skills.recommend"
-      ).length;
-      expect(recommendationCallsAfterRefresh).toBeGreaterThan(recommendationCallsBeforeRefresh);
+      expect(sendCommand).toHaveBeenCalledWith(
+        "skills.files.delete",
+        {
+          skillSlug: "my-review-skill",
+          path: "refs/guide.md",
+        },
+        {
+          timeoutMs: 180000,
+        }
+      );
     });
-  });
+  }, 10_000);
 
-  it("shows local skill versions without source labels in installed skill cards", async () => {
-    const sendCommand = vi.fn(async (op: string) => {
+  it("marks local skill root and file rows draggable with skill path payloads", async () => {
+    const sendCommand = vi.fn(async (op: string, args?: Record<string, unknown>) => {
       if (op === "skills.library.list") {
         return [
           {
-            slug: "code-review",
-            displayName: "Code Review",
-            description: "Review code changes before merge",
+            slug: "my-review-skill",
+            displayName: "My Review Skill",
+            description: "Custom review workflow",
             version: "local",
-            source: "local",
-            libraryPath: "/users/spencer/.agents/skills/code-review",
+            source: "custom",
+            origin: "filesystem",
+            libraryPath: "/root/.agents/skills/my-review-skill",
             installState: "installed",
             installedAt: 1,
-            updatedAt: 2,
+            updatedAt: 1,
             mountedProviderIds: [],
             mountStatus: "unmounted",
             errorCount: 0,
@@ -696,24 +2160,94 @@ describe("SkillsPanel", () => {
         return { targets: [], mounts: [] };
       }
 
-      if (op === "skills.targets.list") {
-        return [];
+      if (op === "skills.files.readTree") {
+        const path = args?.path;
+        if (path === "refs") {
+          return {
+            path: "refs",
+            children: [
+              {
+                name: "guide.md",
+                path: "refs/guide.md",
+                kind: "file",
+              },
+            ],
+          };
+        }
+
+        return {
+          path: ".",
+          children: [
+            {
+              name: "refs",
+              path: "refs",
+              kind: "dir",
+            },
+            {
+              name: "SKILL.md",
+              path: "SKILL.md",
+              kind: "file",
+            },
+          ],
+        };
       }
 
-      return [];
+      if (op === "workspace.uiState.set") {
+        return {
+          id: "ws-1",
+          path: "/workspace",
+          targetRuntime: "native",
+          openedAt: 1,
+          lastActiveAt: 1,
+          uiState: args?.uiState,
+        };
+      }
+
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
 
-    await expandInstalledSection();
-    const skillCard = (await screen.findByText("Code Review")).closest("article");
-    if (!skillCard) {
-      throw new Error("Skill card not found");
+    const customHeading = await screen.findByRole("heading", { level: 2, name: "Custom Skills" });
+    const customSection = customHeading.closest("section");
+    if (!customSection) {
+      throw new Error("Custom skills section not found");
     }
 
-    expect(within(skillCard).getByText("code-review")).toBeInTheDocument();
-    expect(within(skillCard).getByText("local")).toBeInTheDocument();
-    expect(within(skillCard).queryByText("Local")).toBeNull();
+    fireEvent.click(await within(customSection).findByText("My Review Skill"));
+
+    expect(await screen.findByText("my-review-skill/")).toBeInTheDocument();
+    const rootRow = screen.getByText("my-review-skill/").closest(".skills-panel__files-node");
+    const skillFileButton = screen.getByRole("button", { name: "SKILL.md" });
+    const skillFileRow = skillFileButton.closest(".skills-panel__files-node");
+    expect(rootRow).toHaveAttribute("draggable", "true");
+    expect(skillFileRow).toHaveAttribute("draggable", "true");
+
+    const rootDrag = createDragDataTransfer();
+    fireEvent.dragStart(rootRow!, { dataTransfer: rootDrag.dataTransfer });
+
+    expect(rootDrag.values.get(SKILL_PATH_DRAG_MIME)).toBe(
+      JSON.stringify({
+        skillSlug: "my-review-skill",
+        path: ".",
+        absolutePath: "/root/.agents/skills/my-review-skill",
+        kind: "dir",
+      })
+    );
+    expect(rootDrag.values.get("text/plain")).toBe("/root/.agents/skills/my-review-skill");
+
+    const fileDrag = createDragDataTransfer();
+    fireEvent.dragStart(skillFileRow!, { dataTransfer: fileDrag.dataTransfer });
+
+    expect(fileDrag.values.get(SKILL_PATH_DRAG_MIME)).toBe(
+      JSON.stringify({
+        skillSlug: "my-review-skill",
+        path: "SKILL.md",
+        absolutePath: "/root/.agents/skills/my-review-skill/SKILL.md",
+        kind: "file",
+      })
+    );
+    expect(fileDrag.values.get("text/plain")).toBe("/root/.agents/skills/my-review-skill/SKILL.md");
   });
 
   it("separates built-in skills into their own section", async () => {
@@ -725,7 +2259,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -760,7 +2295,7 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -799,7 +2334,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -834,7 +2370,7 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -869,7 +2405,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -912,7 +2449,7 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -921,7 +2458,9 @@ describe("SkillsPanel", () => {
     fireEvent.click(await screen.findByText("Review code changes before merge"));
 
     expect(screen.getByRole("heading", { level: 2, name: "Code Review" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "Back to skills" })).toBeVisible();
+    const backButton = screen.getByRole("button", { name: "Back to skills" });
+    expect(backButton).toBeVisible();
+    expect(within(backButton).queryByText("Back to skills")).toBeNull();
     expect(screen.getByText("code-review")).toBeInTheDocument();
     expect(screen.getByText("Review code changes before merge")).toBeInTheDocument();
     expect(screen.getByText("/skills/library/code-review")).toBeInTheDocument();
@@ -947,7 +2486,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -1008,7 +2548,7 @@ describe("SkillsPanel", () => {
         return { libraryEntries: [], mounted: [], skipped: [], removed: [] };
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -1149,7 +2689,7 @@ describe("SkillsPanel", () => {
         return { ok: true };
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -1259,7 +2799,7 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -1287,7 +2827,7 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -1296,6 +2836,7 @@ describe("SkillsPanel", () => {
     const headings = screen.getAllByRole("heading", { level: 2 });
 
     expect(headings.map((heading) => heading.textContent)).toEqual([
+      "Custom Skills",
       "Installed Skills",
       "Built-in Skills",
       "Discover",
@@ -1345,7 +2886,7 @@ describe("SkillsPanel", () => {
         ];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     const { container } = renderPanel(sendCommand);
@@ -1425,7 +2966,7 @@ describe("SkillsPanel", () => {
         };
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -1470,7 +3011,7 @@ describe("SkillsPanel", () => {
     });
   });
 
-  it("collapses and expands installed, built-in, recommendations, and discover sections independently", async () => {
+  it("collapses and expands custom, installed, built-in, recommendations, and discover sections independently", async () => {
     const sendCommand = vi.fn(async (op: string) => {
       if (op === "skills.library.list") {
         return [
@@ -1479,7 +3020,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -1514,11 +3056,36 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
 
+    const customHeading = await screen.findByRole("heading", {
+      level: 2,
+      name: "Custom Skills",
+    });
+    const customSection = customHeading.closest("section");
+    if (!customSection) {
+      throw new Error("Custom section not found");
+    }
+
+    expect(
+      within(customSection).getByRole("button", { name: "Collapse Custom Skills" })
+    ).toHaveAttribute("aria-expanded", "true");
+    expect(within(customSection).getByText("No custom skills yet.")).toBeInTheDocument();
+
+    fireEvent.click(within(customSection).getByRole("button", { name: "Collapse Custom Skills" }));
+
+    expect(
+      within(customSection).getByRole("button", { name: "Expand Custom Skills" })
+    ).toHaveAttribute("aria-expanded", "false");
+    expect(within(customSection).queryByText("No custom skills yet.")).toBeNull();
+
+    fireEvent.click(within(customSection).getByRole("button", { name: "Expand Custom Skills" }));
+
+    expect(await within(customSection).findByText("No custom skills yet.")).toBeInTheDocument();
+
     const installedHeading = await screen.findByRole("heading", {
       level: 2,
       name: "Installed Skills",
@@ -1593,7 +3160,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -1666,7 +3234,7 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -1791,7 +3359,7 @@ describe("SkillsPanel", () => {
         };
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -1836,7 +3404,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -1908,7 +3477,7 @@ describe("SkillsPanel", () => {
         };
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -1958,7 +3527,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -2020,7 +3590,7 @@ describe("SkillsPanel", () => {
         };
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -2067,7 +3637,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -2120,7 +3691,7 @@ describe("SkillsPanel", () => {
         return { ok: true };
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
@@ -2165,7 +3736,8 @@ describe("SkillsPanel", () => {
             displayName: "Code Review",
             description: "Review code changes before merge",
             version: "1.2.3",
-            source: "skillhub",
+            source: "installed",
+            origin: "skillhub",
             libraryPath: "/skills/library/code-review",
             installState: "installed",
             installedAt: 1,
@@ -2209,7 +3781,7 @@ describe("SkillsPanel", () => {
         return [];
       }
 
-      return [];
+      return op === "skills.recommend" ? emptySkillRecommendationPage : [];
     });
 
     renderPanel(sendCommand);
diff --git a/packages/web/src/features/workspace/views/shared/skills-panel.tsx b/packages/web/src/features/workspace/views/shared/skills-panel.tsx
index 92bedb1aa..12ba6b6e8 100644
--- a/packages/web/src/features/workspace/views/shared/skills-panel.tsx
+++ b/packages/web/src/features/workspace/views/shared/skills-panel.tsx
@@ -1,15 +1,32 @@
 import type {
   AgentSkillTargetEntry,
+  FileNode,
+  SkillLibraryEntry,
   SkillMountRelation,
   SkillRecommendationEntry,
   SkillVersionCheckEntry,
 } from "@coder-studio/core";
-import { ArrowLeft, ChevronDown, ChevronRight } from "lucide-react";
-import { type FC, type KeyboardEvent, type ReactNode, useEffect, useMemo, useState } from "react";
+import { ArrowLeft, ChevronDown, ChevronRight, Pencil, Trash2, X } from "lucide-react";
+import {
+  type FC,
+  type KeyboardEvent,
+  type DragEvent as ReactDragEvent,
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import {
   Button,
   ConfirmDialog,
   IconButton,
+  Input,
+  Modal,
+  ModalBody,
+  ModalFooter,
+  ModalHeader,
+  ModalTitle,
   Notice,
   Switch,
   Tag,
@@ -17,6 +34,8 @@ import {
   Tooltip,
 } from "../../../../components/ui";
 import { useTranslation } from "../../../../lib/i18n";
+import { setSkillPathDragData } from "../../../../lib/skill-path-drag";
+import { useSkillFileActions } from "../../actions/use-skill-file-actions";
 import type {
   SkillInfoItem,
   SkillLibraryListItem,
@@ -51,6 +70,7 @@ interface SkillDetailItem {
   description?: string;
   version?: string;
   source?: SkillLibraryListItem["source"];
+  origin?: SkillLibraryListItem["origin"];
   libraryPath?: string;
   installed: boolean;
 }
@@ -102,6 +122,22 @@ function detailHeaderMeta(skill: SkillDetailItem, t: Translate) {
   return null;
 }
 
+function sourceLabel(skill: Pick<SkillDetailItem, "source" | "origin">, t: Translate) {
+  if (skill.origin === "filesystem") {
+    return t("workspace.skills.origin.filesystem");
+  }
+
+  if (skill.origin === "skillhub") {
+    return t("workspace.skills.origin.skillhub");
+  }
+
+  if (skill.source) {
+    return t(`workspace.skills.source.${skill.source}`);
+  }
+
+  return t("skills.available");
+}
+
 function formatSkillVersion(version: string | undefined) {
   const trimmed = version?.trim() ?? "";
   if (!trimmed) {
@@ -164,7 +200,11 @@ function isBuiltinSkill(skill: SkillLibraryListItem) {
 }
 
 function sourceForSkillInfo(info: SkillInfoItem): SkillDetailItem["source"] {
-  return info.libraryEntry?.source ?? "skillhub";
+  return info.libraryEntry?.source ?? "installed";
+}
+
+function originForSkillInfo(info: SkillInfoItem): SkillDetailItem["origin"] {
+  return info.libraryEntry?.origin ?? "skillhub";
 }
 
 function detailFromLibraryItem(skill: SkillLibraryListItem): SkillDetailItem {
@@ -174,6 +214,20 @@ function detailFromLibraryItem(skill: SkillLibraryListItem): SkillDetailItem {
     description: skill.description,
     version: skill.version,
     source: skill.source,
+    origin: skill.origin,
+    libraryPath: skill.libraryPath,
+    installed: skill.installState === "installed",
+  };
+}
+
+function detailFromLibraryEntry(skill: SkillLibraryEntry): SkillDetailItem {
+  return {
+    slug: skill.slug,
+    displayName: skill.displayName,
+    description: skill.description,
+    version: skill.version,
+    source: skill.source,
+    origin: skill.origin,
     libraryPath: skill.libraryPath,
     installed: skill.installState === "installed",
   };
@@ -186,6 +240,7 @@ function detailFromSkillInfo(info: SkillInfoItem): SkillDetailItem {
     description: info.description,
     version: info.version,
     source: sourceForSkillInfo(info),
+    origin: originForSkillInfo(info),
     libraryPath: info.libraryEntry?.libraryPath,
     installed: info.installed,
   };
@@ -197,7 +252,8 @@ function detailFromSearchResult(item: SkillSearchResultItem): SkillDetailItem {
     displayName: item.displayName,
     description: item.description,
     version: item.installedVersion ?? item.version,
-    source: "skillhub",
+    source: "installed",
+    origin: "skillhub",
     installed: item.installed,
   };
 }
@@ -207,7 +263,8 @@ function detailFromRecommendation(item: SkillRecommendationEntry): SkillDetailIt
     slug: item.slug,
     displayName: item.displayName,
     description: item.description,
-    source: "skillhub",
+    source: "installed",
+    origin: "skillhub",
     installed: item.installed,
   };
 }
@@ -219,24 +276,28 @@ function skillDetailMatches(left: SkillDetailItem, right: SkillDetailItem) {
     left.description === right.description &&
     left.version === right.version &&
     left.source === right.source &&
+    left.origin === right.origin &&
     left.libraryPath === right.libraryPath &&
     left.installed === right.installed
   );
 }
 
 function groupLibraryItems(items: SkillLibraryListItem[]) {
+  const custom: SkillLibraryListItem[] = [];
   const installed: SkillLibraryListItem[] = [];
   const builtin: SkillLibraryListItem[] = [];
 
   for (const item of items) {
     if (isBuiltinSkill(item)) {
       builtin.push(item);
+    } else if (item.source === "custom") {
+      custom.push(item);
     } else {
       installed.push(item);
     }
   }
 
-  return { builtin, installed };
+  return { builtin, custom, installed };
 }
 
 function sortSearchItems(items: SkillSearchResultItem[]) {
@@ -355,6 +416,421 @@ function buildTargetSummaries(
   });
 }
 
+function buildNestedTree(treeMap: Map<string, FileNode[]>, expandedDirs: Set<string>): FileNode[] {
+  const attachChildren = (nodes: FileNode[]): FileNode[] =>
+    nodes.map((node) => {
+      if (node.kind === "dir" && expandedDirs.has(node.path) && treeMap.has(node.path)) {
+        return {
+          ...node,
+          children: attachChildren(treeMap.get(node.path)!),
+        };
+      }
+
+      return node;
+    });
+
+  return attachChildren(treeMap.get(".") ?? []);
+}
+
+function sortNodes(nodes: FileNode[]): FileNode[] {
+  return [...nodes].sort((left, right) => {
+    if (left.kind !== right.kind) {
+      return left.kind === "dir" ? -1 : 1;
+    }
+
+    return left.name.localeCompare(right.name);
+  });
+}
+
+interface SkillFilesTreeProps {
+  nodes: FileNode[];
+  isLoadingDir: string | null;
+  onLoadChildren: (path: string) => Promise<boolean>;
+  onOpenFile: (path: string) => Promise<void>;
+  onRequestCreate: (mode: "file" | "folder", baseDir: string | null) => void;
+  onRequestRename: (node: { path: string; name: string; kind: "file" | "dir" }) => void;
+  onRequestDelete: (node: { path: string; name: string }) => void;
+  skillLibraryPath: string;
+  skillSlug: string;
+}
+
+function toSkillAbsolutePath(skillLibraryPath: string, relativePath: string) {
+  if (relativePath === ".") {
+    return skillLibraryPath;
+  }
+
+  return `${skillLibraryPath}/${relativePath}`;
+}
+
+function SkillFilesTree({
+  nodes,
+  isLoadingDir,
+  onLoadChildren,
+  onOpenFile,
+  onRequestCreate,
+  onRequestRename,
+  onRequestDelete,
+  skillLibraryPath,
+  skillSlug,
+}: SkillFilesTreeProps) {
+  return (
+    <div className="skills-panel__files-tree" role="tree">
+      {sortNodes(nodes).map((node) => (
+        <SkillFilesTreeNode
+          key={node.path}
+          isLoadingDir={isLoadingDir}
+          node={node}
+          onLoadChildren={onLoadChildren}
+          onOpenFile={onOpenFile}
+          onRequestCreate={onRequestCreate}
+          onRequestRename={onRequestRename}
+          onRequestDelete={onRequestDelete}
+          skillLibraryPath={skillLibraryPath}
+          skillSlug={skillSlug}
+        />
+      ))}
+    </div>
+  );
+}
+
+interface SkillFilesTreeNodeProps {
+  node: FileNode;
+  isLoadingDir: string | null;
+  onLoadChildren: (path: string) => Promise<boolean>;
+  onOpenFile: (path: string) => Promise<void>;
+  onRequestCreate: (mode: "file" | "folder", baseDir: string | null) => void;
+  onRequestRename: (node: { path: string; name: string; kind: "file" | "dir" }) => void;
+  onRequestDelete: (node: { path: string; name: string }) => void;
+  skillLibraryPath: string;
+  skillSlug: string;
+}
+
+function SkillFilesTreeNode({
+  node,
+  isLoadingDir,
+  onLoadChildren,
+  onOpenFile,
+  onRequestCreate,
+  onRequestRename,
+  onRequestDelete,
+  skillLibraryPath,
+  skillSlug,
+}: SkillFilesTreeNodeProps) {
+  const t = useTranslation();
+  const handleClick = () => {
+    if (node.path === ".") {
+      return;
+    }
+
+    if (node.kind === "file") {
+      void onOpenFile(node.path);
+      return;
+    }
+
+    void onLoadChildren(node.path);
+  };
+
+  const handleDragStart = (event: ReactDragEvent<HTMLDivElement>) => {
+    if (!event.dataTransfer) {
+      return;
+    }
+
+    event.stopPropagation();
+    setSkillPathDragData(event.dataTransfer, {
+      skillSlug,
+      path: node.path,
+      absolutePath: toSkillAbsolutePath(skillLibraryPath, node.path),
+      kind: node.kind,
+    });
+  };
+
+  return (
+    <div
+      className="skills-panel__files-node"
+      role="treeitem"
+      aria-expanded={node.kind === "dir" ? Boolean(node.children) : undefined}
+      draggable
+      onDragStart={handleDragStart}
+    >
+      <div className="skills-panel__files-row">
+        <button type="button" className="skills-panel__files-button" onClick={handleClick}>
+          {node.kind === "dir" ? (
+            <span aria-hidden="true">{node.children ? "▾" : "▸"}</span>
+          ) : (
+            <span aria-hidden="true">•</span>
+          )}
+          <span>{node.name}</span>
+          {isLoadingDir === node.path ? <span>{` ${"..."}`}</span> : null}
+        </button>
+        {node.path !== "." ? (
+          <div className="skills-panel__files-actions">
+            {node.kind === "dir" ? (
+              <button
+                type="button"
+                className="workspace-sidebar-section__action"
+                aria-label={`${t("skills.custom_new_folder")} ${node.path}`}
+                onClick={(event) => {
+                  event.stopPropagation();
+                  onRequestCreate("folder", node.path);
+                }}
+              >
+                {t("skills.custom_new_folder")}
+              </button>
+            ) : null}
+            <IconButton
+              aria-label={`${t("action.edit")} ${node.name}`}
+              icon={<Pencil size={12} />}
+              onClick={(event) => {
+                event.stopPropagation();
+                onRequestRename({
+                  path: node.path,
+                  name: node.name,
+                  kind: node.kind,
+                });
+              }}
+              size="sm"
+              variant="ghost"
+            />
+            <IconButton
+              aria-label={`${t("skills.custom_delete")} ${node.name}`}
+              icon={<Trash2 size={12} />}
+              onClick={(event) => {
+                event.stopPropagation();
+                onRequestDelete({
+                  path: node.path,
+                  name: node.name,
+                });
+              }}
+              size="sm"
+              variant="ghost"
+            />
+          </div>
+        ) : null}
+      </div>
+      {node.kind === "dir" && node.children?.length ? (
+        <div className="skills-panel__files-children">
+          <SkillFilesTree
+            skillLibraryPath={skillLibraryPath}
+            skillSlug={skillSlug}
+            nodes={node.children}
+            isLoadingDir={isLoadingDir}
+            onLoadChildren={onLoadChildren}
+            onOpenFile={onOpenFile}
+            onRequestCreate={onRequestCreate}
+            onRequestRename={onRequestRename}
+            onRequestDelete={onRequestDelete}
+          />
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function CreateCustomSkillFileDialogs({
+  skillFileActions,
+}: {
+  skillFileActions: ReturnType<typeof useSkillFileActions>;
+}) {
+  const t = useTranslation();
+  const createInputRef = useRef<HTMLInputElement | null>(null);
+  const renameInputRef = useRef<HTMLInputElement | null>(null);
+
+  return (
+    <>
+      {skillFileActions.createDialog ? (
+        <Modal
+          initialFocus={() => createInputRef.current}
+          onOpenChange={skillFileActions.closeCreateDialog}
+          open
+        >
+          <ModalHeader>
+            <ModalTitle>
+              <span>
+                {skillFileActions.createDialog.mode === "file"
+                  ? t("skills.custom_new_file")
+                  : t("skills.custom_new_folder")}
+              </span>
+            </ModalTitle>
+            <IconButton
+              aria-label={t("action.close")}
+              icon={<X size={14} />}
+              onClick={skillFileActions.closeCreateDialog}
+              size="sm"
+            />
+          </ModalHeader>
+          <ModalBody>
+            <div className="form-group">
+              <label htmlFor="custom-skill-path">{t("file.path")}</label>
+              <Input
+                id="custom-skill-path"
+                ref={createInputRef}
+                value={skillFileActions.createDialog.draftPath}
+                onChange={(event) => skillFileActions.updateDraftPath(event.target.value)}
+                invalid={Boolean(skillFileActions.createDialog.error)}
+                autoFocus
+              />
+              {skillFileActions.createDialog.error ? (
+                <span className="form-error" role="alert">
+                  {skillFileActions.createDialog.error}
+                </span>
+              ) : null}
+            </div>
+          </ModalBody>
+          <ModalFooter>
+            <Button onClick={skillFileActions.closeCreateDialog}>{t("common.cancel")}</Button>
+            <Button
+              variant="primary"
+              onClick={() => {
+                void skillFileActions.submitCreateDialog();
+              }}
+            >
+              {t("common.create")}
+            </Button>
+          </ModalFooter>
+        </Modal>
+      ) : null}
+
+      {skillFileActions.renameDialog ? (
+        <Modal
+          initialFocus={() => renameInputRef.current}
+          onOpenChange={skillFileActions.closeRenameDialog}
+          open
+        >
+          <ModalHeader>
+            <ModalTitle>
+              <span>{t("action.edit")}</span>
+            </ModalTitle>
+            <IconButton
+              aria-label={t("action.close")}
+              icon={<X size={14} />}
+              onClick={skillFileActions.closeRenameDialog}
+              size="sm"
+            />
+          </ModalHeader>
+          <ModalBody>
+            <div className="form-group">
+              <label htmlFor="custom-skill-rename">{t("action.edit")}</label>
+              <Input
+                id="custom-skill-rename"
+                ref={renameInputRef}
+                value={skillFileActions.renameDialog.nextName}
+                onChange={(event) => skillFileActions.updateRenameDraft(event.target.value)}
+                invalid={Boolean(skillFileActions.renameDialog.error)}
+                autoFocus
+              />
+              {skillFileActions.renameDialog.error ? (
+                <span className="form-error" role="alert">
+                  {skillFileActions.renameDialog.error}
+                </span>
+              ) : null}
+            </div>
+          </ModalBody>
+          <ModalFooter>
+            <Button onClick={skillFileActions.closeRenameDialog}>{t("common.cancel")}</Button>
+            <Button
+              variant="primary"
+              onClick={() => {
+                void skillFileActions.submitRenameDialog();
+              }}
+            >
+              {t("action.confirm")}
+            </Button>
+          </ModalFooter>
+        </Modal>
+      ) : null}
+
+      <ConfirmDialog
+        open={Boolean(skillFileActions.pendingDelete)}
+        title={t("skills.custom_delete")}
+        description={skillFileActions.pendingDelete?.name ?? ""}
+        cancelText={t("common.cancel")}
+        confirmText={t("action.confirm")}
+        tone="danger"
+        onOpenChange={(open) => {
+          if (!open) {
+            skillFileActions.cancelDelete();
+          }
+        }}
+        onConfirm={() => {
+          void skillFileActions.confirmDelete();
+        }}
+      />
+    </>
+  );
+}
+
+interface CreateCustomSkillModalProps {
+  open: boolean;
+  draftName: string;
+  error: string | null;
+  onDraftChange: (value: string) => void;
+  onClose: () => void;
+  onConfirm: () => Promise<void>;
+}
+
+function CreateCustomSkillModal({
+  open,
+  draftName,
+  error,
+  onDraftChange,
+  onClose,
+  onConfirm,
+}: CreateCustomSkillModalProps) {
+  const t = useTranslation();
+  const inputRef = useRef<HTMLInputElement | null>(null);
+
+  if (!open) {
+    return null;
+  }
+
+  return (
+    <Modal initialFocus={() => inputRef.current} onOpenChange={onClose} open>
+      <ModalHeader>
+        <ModalTitle>
+          <span>{t("skills.custom_create_title")}</span>
+        </ModalTitle>
+        <IconButton
+          aria-label={t("action.close")}
+          icon={<X size={14} />}
+          onClick={onClose}
+          size="sm"
+        />
+      </ModalHeader>
+      <ModalBody>
+        <div className="form-group">
+          <label htmlFor="custom-skill-name">{t("skills.custom_create_name")}</label>
+          <Input
+            id="custom-skill-name"
+            ref={inputRef}
+            value={draftName}
+            onChange={(event) => onDraftChange(event.target.value)}
+            placeholder={t("skills.custom_create_placeholder")}
+            invalid={Boolean(error)}
+            autoFocus
+          />
+          <span className="dialog-helper">{t("skills.custom_create_helper")}</span>
+          {error ? (
+            <span className="form-error" role="alert">
+              {error}
+            </span>
+          ) : null}
+        </div>
+      </ModalBody>
+      <ModalFooter>
+        <Button onClick={onClose}>{t("common.cancel")}</Button>
+        <Button
+          variant="primary"
+          onClick={() => {
+            void onConfirm();
+          }}
+        >
+          {t("common.create")}
+        </Button>
+      </ModalFooter>
+    </Modal>
+  );
+}
+
 interface SkillsSectionHeaderProps {
   actions?: ReactNode;
   count?: number;
@@ -476,6 +952,7 @@ interface SkillDetailViewProps {
   installSkill: ReturnType<typeof useSkillsPanel>["installSkill"];
   installingSkillSlugs: ReturnType<typeof useSkillsPanel>["installingSkillSlugs"];
   onBack: () => void;
+  workspaceId: string;
 }
 
 function SkillDetailView({
@@ -486,9 +963,54 @@ function SkillDetailView({
   installSkill,
   installingSkillSlugs,
   onBack,
+  workspaceId,
 }: SkillDetailViewProps) {
   const targetSummaries = buildTargetSummaries(t, targets, mounts);
   const headerMeta = detailHeaderMeta(skill, t);
+  const skillFileActions = useSkillFileActions({
+    workspaceId,
+    skillSlug: skill.slug,
+  });
+  const didAutoOpenSkillRef = useRef<string | null>(null);
+  const loadFileTreeRef = useRef(skillFileActions.loadFileTree);
+  const treeNodes = useMemo(
+    () =>
+      skillFileActions.fileTree
+        ? buildNestedTree(skillFileActions.fileTree, skillFileActions.expandedDirs)
+        : [],
+    [skillFileActions.expandedDirs, skillFileActions.fileTree]
+  );
+
+  useEffect(() => {
+    loadFileTreeRef.current = skillFileActions.loadFileTree;
+  }, [skillFileActions.loadFileTree]);
+
+  useEffect(() => {
+    if (skill.source !== "custom") {
+      return;
+    }
+
+    void loadFileTreeRef.current();
+  }, [skill.slug, skill.source]);
+
+  useEffect(() => {
+    if (skill.source !== "custom") {
+      didAutoOpenSkillRef.current = null;
+      return;
+    }
+
+    if (didAutoOpenSkillRef.current === skill.slug) {
+      return;
+    }
+
+    if (skillFileActions.activeFilePath?.startsWith(`skill:${skill.slug}/`)) {
+      didAutoOpenSkillRef.current = skill.slug;
+      return;
+    }
+
+    didAutoOpenSkillRef.current = skill.slug;
+    void skillFileActions.openSkillFile("SKILL.md", "file-tree");
+  }, [skill.slug, skill.source, skillFileActions.activeFilePath, skillFileActions.openSkillFile]);
 
   return (
     <div className="workspace-sidebar-view skills-panel skills-panel--detail">
@@ -502,7 +1024,6 @@ function SkillDetailView({
               onClick={onBack}
             >
               <ArrowLeft size={14} aria-hidden="true" />
-              <span>{t("skills.detail_back")}</span>
             </button>
             <div className="skills-panel__detail-title-row">
               <h2 className="skills-panel__detail-title">{skill.displayName}</h2>
@@ -533,11 +1054,7 @@ function SkillDetailView({
           <dl className="skills-panel__detail-fields">
             <div className="skills-panel__detail-field">
               <dt>{t("skills.detail_source")}</dt>
-              <dd>
-                {skill.source
-                  ? t(`workspace.skills.source.${skill.source}`)
-                  : t("skills.available")}
-              </dd>
+              <dd>{sourceLabel(skill, t)}</dd>
             </div>
             {skill.libraryPath ? (
               <div className="skills-panel__detail-field">
@@ -548,7 +1065,61 @@ function SkillDetailView({
           </dl>
         </section>
 
-        {skill.installed ? (
+        {skill.source === "custom" ? (
+          <section className="workspace-sidebar-section skills-panel__detail-targets">
+            <div className="workspace-sidebar-section__header">
+              <div className="workspace-sidebar-section__header-main">
+                <h3 className="workspace-sidebar-section__title">
+                  {t("skills.custom_files_title")}
+                </h3>
+              </div>
+              <div className="workspace-sidebar-panel__actions workspace-sidebar-section__actions">
+                <button
+                  type="button"
+                  className="workspace-sidebar-section__action"
+                  onClick={() => skillFileActions.openCreateDialog("file", null)}
+                >
+                  {t("skills.custom_new_file")}
+                </button>
+                <button
+                  type="button"
+                  className="workspace-sidebar-section__action"
+                  onClick={() => skillFileActions.openCreateDialog("folder", null)}
+                >
+                  {t("skills.custom_new_folder")}
+                </button>
+              </div>
+            </div>
+            <div className="skills-panel__target-details skills-panel__target-details--detail">
+              <div className="skills-panel__files-tree" role="tree">
+                <SkillFilesTreeNode
+                  isLoadingDir={skillFileActions.isLoadingDir}
+                  node={{
+                    kind: "dir",
+                    name: `${skill.slug}/`,
+                    path: ".",
+                    children: treeNodes,
+                  }}
+                  onLoadChildren={skillFileActions.loadChildren}
+                  onOpenFile={skillFileActions.openSkillFile}
+                  onRequestCreate={skillFileActions.openCreateDialog}
+                  onRequestRename={skillFileActions.openRenameDialog}
+                  onRequestDelete={(node) =>
+                    skillFileActions.requestDelete({
+                      path: node.path,
+                      name: node.name,
+                      error: null,
+                    })
+                  }
+                  skillLibraryPath={skill.libraryPath}
+                  skillSlug={skill.slug}
+                />
+              </div>
+            </div>
+          </section>
+        ) : null}
+
+        {skill.installed && skill.source !== "custom" ? (
           <section className="workspace-sidebar-section skills-panel__detail-targets">
             <div className="workspace-sidebar-section__header">
               <div className="workspace-sidebar-section__header-main">
@@ -561,6 +1132,10 @@ function SkillDetailView({
             </div>
           </section>
         ) : null}
+
+        {skill.source === "custom" ? (
+          <CreateCustomSkillFileDialogs skillFileActions={skillFileActions} />
+        ) : null}
       </div>
     </div>
   );
@@ -575,6 +1150,7 @@ interface SkillsLibrarySectionProps {
   emptyLabel: string;
   actions?: ReactNode;
   allowUninstall: boolean;
+  requireUninstallConfirm?: boolean;
   isExpanded: boolean;
   toggleLabel: string;
   mountsBySkillSlug: Record<string, SkillMountRelation[]>;
@@ -672,6 +1248,7 @@ function SkillsLibrarySection({
   emptyLabel,
   actions,
   allowUninstall,
+  requireUninstallConfirm = false,
   isExpanded,
   toggleLabel,
   mountsBySkillSlug,
@@ -701,7 +1278,7 @@ function SkillsLibrarySection({
       }
     }
 
-    if (mountedProviderIds.size > 0) {
+    if (mountedProviderIds.size > 0 || requireUninstallConfirm) {
       setPendingUninstall({ mountCount: mountedProviderIds.size, skill });
       return;
     }
@@ -734,7 +1311,10 @@ function SkillsLibrarySection({
                 const targetSummaries = buildTargetSummaries(t, targets, mounts);
                 const versionCheck = versionChecksBySlug[skill.slug];
                 const versionStatus = versionCheckTag(t, versionCheck);
-                const canUpdate = versionCheck?.status === "update_available";
+                const canUpdate =
+                  skill.source === "installed" &&
+                  skill.origin === "skillhub" &&
+                  versionCheck?.status === "update_available";
                 const configuredProviderIds = targetSummaries
                   .filter((summary) => summary.configured)
                   .map((summary) => summary.providerId);
@@ -783,6 +1363,10 @@ function SkillsLibrarySection({
                   : t("skills.builtin_enable_skill", {
                       name: skill.displayName,
                     });
+                const isManagedInstalledSkill =
+                  skill.source === "installed" && skill.origin === "skillhub";
+                const isFilesystemInstalledSkill =
+                  skill.source === "installed" && skill.origin === "filesystem";
 
                 return (
                   <article
@@ -858,14 +1442,24 @@ function SkillsLibrarySection({
                                     size="sm"
                                   />
                                 </Tooltip>
-                                <Tooltip content={t("skills.uninstall_tooltip")}>
-                                  <Button
-                                    size="sm"
-                                    onClick={() => requestUninstallSkill(skill, mounts)}
+                                {isManagedInstalledSkill || skill.source === "custom" ? (
+                                  <Tooltip
+                                    content={
+                                      skill.source === "custom"
+                                        ? t("skills.custom_remove_tooltip")
+                                        : t("skills.uninstall_tooltip")
+                                    }
                                   >
-                                    {t("skills.uninstall")}
-                                  </Button>
-                                </Tooltip>
+                                    <Button
+                                      size="sm"
+                                      onClick={() => requestUninstallSkill(skill, mounts)}
+                                    >
+                                      {skill.source === "custom"
+                                        ? t("skills.delete")
+                                        : t("skills.uninstall")}
+                                    </Button>
+                                  </Tooltip>
+                                ) : null}
                               </>
                             ) : null}
                           </>
@@ -873,6 +1467,11 @@ function SkillsLibrarySection({
                         onOpenSkill={onOpenSkill}
                         badges={
                           <>
+                            {isFilesystemInstalledSkill ? (
+                              <Tag color="neutral" caps={false}>
+                                {sourceLabel(detailFromLibraryItem(skill), t)}
+                              </Tag>
+                            ) : null}
                             {shouldShowSkillVersion(skill) ? (
                               <Tag color="neutral" caps={false}>
                                 {formatSkillVersion(skill.version)}
@@ -901,12 +1500,22 @@ function SkillsLibrarySection({
 
       <ConfirmDialog
         cancelText={t("common.cancel")}
-        confirmText={t("skills.uninstall_confirm_confirm")}
+        confirmText={
+          pendingUninstall?.skill.source === "custom"
+            ? t("skills.custom_remove_confirm_confirm")
+            : t("skills.uninstall_confirm_confirm")
+        }
         description={
           pendingUninstall
-            ? t("skills.uninstall_confirm_description", {
-                count: pendingUninstall.mountCount,
-              })
+            ? pendingUninstall.skill.source === "custom"
+              ? pendingUninstall.mountCount > 0
+                ? t("skills.custom_remove_confirm_mounted_description", {
+                    count: pendingUninstall.mountCount,
+                  })
+                : t("skills.custom_remove_confirm_description")
+              : t("skills.uninstall_confirm_description", {
+                  count: pendingUninstall.mountCount,
+                })
             : null
         }
         onConfirm={() => {
@@ -925,7 +1534,11 @@ function SkillsLibrarySection({
         open={Boolean(pendingUninstall)}
         title={
           pendingUninstall
-            ? t("skills.uninstall_confirm_title", { name: pendingUninstall.skill.displayName })
+            ? pendingUninstall.skill.source === "custom"
+              ? t("skills.custom_remove_confirm_title", {
+                  name: pendingUninstall.skill.displayName,
+                })
+              : t("skills.uninstall_confirm_title", { name: pendingUninstall.skill.displayName })
             : ""
         }
         tone="danger"
@@ -939,19 +1552,23 @@ export const SkillsPanel: FC<SkillsPanelProps> = ({ workspaceId, refreshToken })
   const {
     checkSkillVersions,
     checkingVersions,
+    createCustomSkill,
     errorMessage,
     installSkill,
     installingSkillSlugs,
     library,
     loadSkillInfo,
     loadingLibrary,
+    loadingRecommendationPage,
     loadingRecommendations,
     loadingSearch,
+    loadMoreRecommendations,
     mountsBySkillSlug,
     panelState,
     refreshHealth,
     refreshRecommendations,
     recommendations,
+    recommendationsHasMore,
     runSearch,
     searchResults,
     setBuiltinMountEnabled,
@@ -964,20 +1581,30 @@ export const SkillsPanel: FC<SkillsPanelProps> = ({ workspaceId, refreshToken })
     versionChecksBySlug,
   } = useSkillsPanel(workspaceId);
   const sortedLibrary = useMemo(() => sortLibraryItems(library), [library]);
-  const { builtin: builtinLibrary, installed: installedLibrary } = useMemo(
-    () => groupLibraryItems(sortedLibrary),
-    [sortedLibrary]
-  );
+  const {
+    builtin: builtinLibrary,
+    custom: customLibrary,
+    installed: installedLibrary,
+  } = useMemo(() => groupLibraryItems(sortedLibrary), [sortedLibrary]);
   const sortedSearchResults = useMemo(() => sortSearchItems(searchResults), [searchResults]);
   const sortedRecommendations = useMemo(
     () => sortRecommendationItems(recommendations),
     [recommendations]
   );
   const [selectedSkillDetail, setSelectedSkillDetail] = useState<SkillDetailItem | null>(null);
+  const [createCustomOpen, setCreateCustomOpen] = useState(false);
+  const [createCustomDraft, setCreateCustomDraft] = useState("");
+  const [createCustomError, setCreateCustomError] = useState<string | null>(null);
+  const customPanelId = `skills-custom-${workspaceId}`;
   const installedPanelId = `skills-installed-${workspaceId}`;
   const builtinPanelId = `skills-builtin-${workspaceId}`;
   const recommendationsPanelId = `skills-recommendations-${workspaceId}`;
   const discoverPanelId = `skills-discover-${workspaceId}`;
+  const recommendationsLoadSentinelRef = useRef<HTMLDivElement | null>(null);
+  const recommendationsScrollRootRef = useRef<HTMLDivElement | null>(null);
+  const customToggleLabel = panelState.customCollapsed
+    ? t("skills.custom_expand_label")
+    : t("skills.custom_collapse_label");
   const installedToggleLabel = panelState.installedCollapsed
     ? t("skills.installed_expand_label")
     : t("skills.installed_collapse_label");
@@ -992,6 +1619,7 @@ export const SkillsPanel: FC<SkillsPanelProps> = ({ workspaceId, refreshToken })
     : t("skills.recommendations_collapse_label");
   const discoverCount =
     panelState.resolvedQuery && !loadingSearch ? sortedSearchResults.length : undefined;
+  const customCount = loadingLibrary ? undefined : customLibrary.length;
   const installedCount = loadingLibrary ? undefined : installedLibrary.length;
   const builtinCount = loadingLibrary ? undefined : builtinLibrary.length;
   const recommendationsCount = loadingRecommendations ? undefined : sortedRecommendations.length;
@@ -1026,6 +1654,46 @@ export const SkillsPanel: FC<SkillsPanelProps> = ({ workspaceId, refreshToken })
     void refreshRecommendations();
   }, [refreshHealth, refreshRecommendations, refreshToken]);
 
+  useEffect(() => {
+    if (
+      selectedSkillDetail ||
+      panelState.recommendationsCollapsed ||
+      !recommendationsHasMore ||
+      typeof IntersectionObserver === "undefined"
+    ) {
+      return;
+    }
+
+    const root = recommendationsScrollRootRef.current;
+    const sentinel = recommendationsLoadSentinelRef.current;
+    if (!root || !sentinel) {
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          void loadMoreRecommendations();
+        }
+      },
+      {
+        root,
+        rootMargin: "120px 0px",
+        threshold: 0,
+      }
+    );
+
+    observer.observe(sentinel);
+    return () => {
+      observer.disconnect();
+    };
+  }, [
+    loadMoreRecommendations,
+    panelState.recommendationsCollapsed,
+    recommendationsHasMore,
+    selectedSkillDetail,
+  ]);
+
   useEffect(() => {
     if (!selectedSkillDetail) {
       return;
@@ -1063,6 +1731,7 @@ export const SkillsPanel: FC<SkillsPanelProps> = ({ workspaceId, refreshToken })
         skill={selectedSkillDetail}
         t={t}
         targets={targets}
+        workspaceId={workspaceId}
       />
     );
   }
@@ -1070,7 +1739,51 @@ export const SkillsPanel: FC<SkillsPanelProps> = ({ workspaceId, refreshToken })
   return (
     <>
       <div className="workspace-sidebar-view skills-panel">
-        <div className="workspace-sidebar-panel__body workspace-sidebar-panel__body--stacked skills-panel__body">
+        <div
+          ref={recommendationsScrollRootRef}
+          className="workspace-sidebar-panel__body workspace-sidebar-panel__body--stacked skills-panel__body"
+        >
+          <SkillsLibrarySection
+            actions={
+              <button
+                type="button"
+                className="workspace-sidebar-section__action"
+                onClick={() => {
+                  setCreateCustomDraft("");
+                  setCreateCustomError(null);
+                  setCreateCustomOpen(true);
+                }}
+              >
+                {t("skills.custom_new")}
+              </button>
+            }
+            allowUninstall={true}
+            requireUninstallConfirm={true}
+            emptyLabel={loadingLibrary ? t("common.loading") : t("skills.custom_empty")}
+            count={customCount}
+            isExpanded={!panelState.customCollapsed}
+            items={loadingLibrary ? [] : customLibrary}
+            mountsBySkillSlug={mountsBySkillSlug}
+            panelId={customPanelId}
+            panelState={panelState}
+            setBuiltinMountEnabled={setBuiltinMountEnabled}
+            setSkillMountEnabled={setSkillMountEnabled}
+            t={t}
+            targets={targets}
+            title={t("skills.custom_title")}
+            toggleLabel={customToggleLabel}
+            uninstallSkill={uninstallSkill}
+            updateSkill={updateSkill}
+            versionChecksBySlug={versionChecksBySlug}
+            onOpenSkill={openSkillDetail}
+            onToggleExpanded={() =>
+              setPanelState((current) => ({
+                ...current,
+                customCollapsed: !current.customCollapsed,
+              }))
+            }
+          />
+
           <SkillsLibrarySection
             actions={
               <>
@@ -1276,43 +1989,84 @@ export const SkillsPanel: FC<SkillsPanelProps> = ({ workspaceId, refreshToken })
                 ) : sortedRecommendations.length === 0 ? (
                   <p className="workspace-search-panel__state">{t("skills.no_recommendations")}</p>
                 ) : (
-                  sortedRecommendations.map((item) => (
-                    <article
-                      key={item.slug}
-                      className="skills-panel__list-item skills-panel__list-item--recommendation workspace-sidebar-row"
-                    >
-                      <div className="skills-panel__row-head">
-                        <SkillCardOpen
-                          detail={detailFromRecommendation(item)}
-                          t={t}
-                          onOpenSkill={openSkillDetail}
-                          badges={
-                            <Tag color="neutral" caps={false}>
-                              {item.installed ? t("skills.installed") : t("skills.available")}
-                            </Tag>
-                          }
-                          actions={
-                            <Button
-                              size="sm"
-                              loading={installingSkillSlugs.has(item.slug)}
-                              disabled={item.installed}
-                              onClick={() => void installSkill(item.slug)}
-                            >
-                              {item.installed ? t("skills.installed") : t("skills.install")}
-                            </Button>
-                          }
-                        >
-                          <SkillCardDescription>{item.reason}</SkillCardDescription>
-                        </SkillCardOpen>
-                      </div>
-                    </article>
-                  ))
+                  <>
+                    {sortedRecommendations.map((item) => (
+                      <article
+                        key={item.slug}
+                        className="skills-panel__list-item skills-panel__list-item--recommendation workspace-sidebar-row"
+                      >
+                        <div className="skills-panel__row-head">
+                          <SkillCardOpen
+                            detail={detailFromRecommendation(item)}
+                            t={t}
+                            onOpenSkill={openSkillDetail}
+                            badges={
+                              <Tag color="neutral" caps={false}>
+                                {item.installed ? t("skills.installed") : t("skills.available")}
+                              </Tag>
+                            }
+                            actions={
+                              <Button
+                                size="sm"
+                                loading={installingSkillSlugs.has(item.slug)}
+                                disabled={item.installed}
+                                onClick={() => void installSkill(item.slug)}
+                              >
+                                {item.installed ? t("skills.installed") : t("skills.install")}
+                              </Button>
+                            }
+                          >
+                            <SkillCardDescription>{item.reason}</SkillCardDescription>
+                          </SkillCardOpen>
+                        </div>
+                      </article>
+                    ))}
+                    {loadingRecommendationPage ? (
+                      <p className="workspace-search-panel__state">{t("common.loading")}</p>
+                    ) : null}
+                    {recommendationsHasMore ? (
+                      <div
+                        ref={recommendationsLoadSentinelRef}
+                        data-testid="skills-recommendations-sentinel"
+                        aria-hidden="true"
+                      />
+                    ) : null}
+                  </>
                 )}
               </div>
             ) : null}
           </section>
         </div>
       </div>
+
+      <CreateCustomSkillModal
+        draftName={createCustomDraft}
+        error={createCustomError}
+        open={createCustomOpen}
+        onClose={() => {
+          setCreateCustomOpen(false);
+          setCreateCustomError(null);
+        }}
+        onDraftChange={setCreateCustomDraft}
+        onConfirm={async () => {
+          const trimmed = createCustomDraft.trim();
+          if (!trimmed) {
+            setCreateCustomError(t("skills.custom_create_name_required"));
+            return;
+          }
+
+          const created = await createCustomSkill(trimmed);
+          if (!created) {
+            setCreateCustomError(errorMessage ?? "Failed to create custom skill");
+            return;
+          }
+
+          setCreateCustomOpen(false);
+          setCreateCustomError(null);
+          setCreateCustomDraft("");
+          setSelectedSkillDetail(detailFromLibraryEntry(created));
+        }}
+      />
     </>
   );
 };
diff --git a/packages/web/src/features/workspace/views/shared/workspace-launch-modal.test.tsx b/packages/web/src/features/workspace/views/shared/workspace-launch-modal.test.tsx
index 425f815a9..ae088f44b 100644
--- a/packages/web/src/features/workspace/views/shared/workspace-launch-modal.test.tsx
+++ b/packages/web/src/features/workspace/views/shared/workspace-launch-modal.test.tsx
@@ -531,6 +531,132 @@ describe("WorkspaceLaunchModal", () => {
     expect(onClose).toHaveBeenCalledTimes(1);
   });
 
+  it("removes a recent workspace row without opening it", async () => {
+    const onClose = vi.fn();
+    const sendCommand = vi.fn().mockImplementation(async (op: string, args?: { path?: string }) => {
+      if (op === "workspace.browse") {
+        return {
+          currentPath: "/home/spencer",
+          parentPath: "/home",
+          directories: [{ name: "workspace", path: "/home/spencer/workspace" }],
+        };
+      }
+
+      if (op === "workspace.history.list") {
+        return [
+          {
+            path: "/repo/coder-studio",
+            name: "coder-studio",
+            lastOpenedAt: 100,
+          },
+          {
+            path: "/repo/keep-me",
+            name: "keep-me",
+            lastOpenedAt: 90,
+          },
+        ];
+      }
+
+      if (op === "workspace.history.remove") {
+        expect(args).toEqual({ path: "/repo/coder-studio" });
+        return [
+          {
+            path: "/repo/keep-me",
+            name: "keep-me",
+            lastOpenedAt: 90,
+          },
+        ];
+      }
+
+      return {};
+    });
+
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter>
+          <WorkspaceLaunchModal onClose={onClose} />
+        </MemoryRouter>
+      </Provider>
+    );
+
+    expect(await screen.findByText("coder-studio")).toBeInTheDocument();
+
+    fireEvent.click(
+      screen.getByRole("button", { name: "Remove coder-studio from recent workspaces" })
+    );
+
+    await waitFor(() => {
+      expect(screen.queryByText("/repo/coder-studio")).not.toBeInTheDocument();
+    });
+    expect(sendCommand).not.toHaveBeenCalledWith(
+      "workspace.open",
+      { path: "/repo/coder-studio" },
+      undefined
+    );
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it("confirms before clearing all recent workspaces", async () => {
+    const sendCommand = vi.fn().mockImplementation(async (op: string) => {
+      if (op === "workspace.browse") {
+        return {
+          currentPath: "/home/spencer",
+          parentPath: "/home",
+          directories: [{ name: "workspace", path: "/home/spencer/workspace" }],
+        };
+      }
+
+      if (op === "workspace.history.list") {
+        return [
+          {
+            path: "/repo/coder-studio",
+            name: "coder-studio",
+            lastOpenedAt: 100,
+          },
+        ];
+      }
+
+      if (op === "workspace.history.clear") {
+        return [];
+      }
+
+      return {};
+    });
+
+    const store = createStore();
+    store.set(localeAtom, "en");
+    store.set(wsClientAtom, { sendCommand } as never);
+
+    render(
+      <Provider store={store}>
+        <MemoryRouter>
+          <WorkspaceLaunchModal onClose={vi.fn()} />
+        </MemoryRouter>
+      </Provider>
+    );
+
+    expect(await screen.findByText("Recent Workspaces")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Clear all recent workspaces" }));
+
+    expect(screen.getByText("Clear recent workspaces?")).toBeInTheDocument();
+    expect(
+      screen.getByText(
+        "This only clears the recent workspace list. It does not delete any project directories from disk."
+      )
+    ).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: "Clear all" }));
+
+    await waitFor(() => {
+      expect(screen.queryByText("Recent Workspaces")).not.toBeInTheDocument();
+    });
+  });
+
   it("renders recent workspace rows inside the mobile launch sheet", async () => {
     viewportMocks.viewport = "mobile";
 
diff --git a/packages/web/src/features/workspace/views/shared/workspace-launch-modal.tsx b/packages/web/src/features/workspace/views/shared/workspace-launch-modal.tsx
index 71db9edc0..afcd07a4a 100644
--- a/packages/web/src/features/workspace/views/shared/workspace-launch-modal.tsx
+++ b/packages/web/src/features/workspace/views/shared/workspace-launch-modal.tsx
@@ -1,8 +1,9 @@
 import { useAtomValue } from "jotai";
 import { ArrowUp, X } from "lucide-react";
-import { useLayoutEffect, useRef } from "react";
+import { useLayoutEffect, useRef, useState } from "react";
 import { localeAtom } from "../../../../atoms/app-ui";
 import {
+  ConfirmDialog,
   EmptyState,
   IconButton,
   Input,
@@ -53,8 +54,10 @@ export function WorkspaceLaunchModal({ onClose }: WorkspaceLaunchModalProps) {
   const locale = useAtomValue(localeAtom) as LocaleCode;
   const t = useTranslation();
   const createFolderInputRef = useRef<HTMLInputElement | null>(null);
+  const [showClearRecentConfirm, setShowClearRecentConfirm] = useState(false);
   const {
     browsing,
+    clearRecentWorkspaces,
     closeCreateFolder,
     currentPath,
     createFolderError,
@@ -76,6 +79,7 @@ export function WorkspaceLaunchModal({ onClose }: WorkspaceLaunchModalProps) {
     parentPath,
     recentWorkspaces,
     rootPaths,
+    removeRecentWorkspace,
     selectedPath,
     submitCreateFolder,
     updateNewFolderName,
@@ -108,27 +112,49 @@ export function WorkspaceLaunchModal({ onClose }: WorkspaceLaunchModalProps) {
   const recentSection =
     !historyLoading && recentWorkspaces.length > 0 ? (
       <section className="launch-recent" aria-labelledby="launch-recent-title">
-        <div className="launch-section-title" id="launch-recent-title">
-          {t("workspace.launch.recent_title")}
+        <div className="launch-section-header">
+          <div className="launch-section-title" id="launch-recent-title">
+            {t("workspace.launch.recent_title")}
+          </div>
+          <button
+            type="button"
+            className="launch-section-action"
+            onClick={() => setShowClearRecentConfirm(true)}
+            disabled={loading}
+            aria-label={t("workspace.launch.clear_recent_workspaces")}
+          >
+            {t("workspace.launch.clear_all")}
+          </button>
         </div>
         <div className="launch-recent-list">
           {recentWorkspaces.map((entry) => (
-            <button
-              key={entry.path}
-              className="launch-recent-row"
-              type="button"
-              aria-label={t("workspace.launch.open_recent", { name: entry.name })}
-              disabled={loading}
-              onClick={() => void openWorkspaceByPath(entry.path)}
-            >
-              <span className="launch-recent-row__header">
-                <span className="launch-recent-row__name">{entry.name}</span>
-                <span className="launch-recent-row__time">
-                  {formatDate(entry.lastOpenedAt, locale)}
+            <div key={entry.path} className="launch-recent-item">
+              <IconButton
+                aria-label={t("workspace.launch.remove_recent", { name: entry.name })}
+                className="launch-recent-remove"
+                disabled={loading}
+                icon={<X size={14} />}
+                size="sm"
+                onClick={() => {
+                  void removeRecentWorkspace(entry.path);
+                }}
+              />
+              <button
+                className="launch-recent-row"
+                type="button"
+                aria-label={t("workspace.launch.open_recent", { name: entry.name })}
+                disabled={loading}
+                onClick={() => void openWorkspaceByPath(entry.path)}
+              >
+                <span className="launch-recent-row__header">
+                  <span className="launch-recent-row__name">{entry.name}</span>
+                  <span className="launch-recent-row__time">
+                    {formatDate(entry.lastOpenedAt, locale)}
+                  </span>
                 </span>
-              </span>
-              <span className="launch-recent-row__path">{entry.path}</span>
-            </button>
+                <span className="launch-recent-row__path">{entry.path}</span>
+              </button>
+            </div>
           ))}
         </div>
       </section>
@@ -292,58 +318,94 @@ export function WorkspaceLaunchModal({ onClose }: WorkspaceLaunchModalProps) {
 
   if (isMobile) {
     return (
-      <Sheet
-        title={launchTitle}
-        body={launchBody}
-        footer={launchFooter}
-        fullscreen
-        bodyClassName="mobile-sheet__body--flush mobile-sheet__body--fullscreen mobile-launch-sheet"
-        contentClassName="mobile-sheet--launch"
-        onClose={onClose}
-      />
+      <>
+        <Sheet
+          title={launchTitle}
+          body={launchBody}
+          footer={launchFooter}
+          fullscreen
+          bodyClassName="mobile-sheet__body--flush mobile-sheet__body--fullscreen mobile-launch-sheet"
+          contentClassName="mobile-sheet--launch"
+          onClose={onClose}
+        />
+
+        {showClearRecentConfirm ? (
+          <ConfirmDialog
+            open
+            onOpenChange={setShowClearRecentConfirm}
+            title={t("workspace.launch.clear_recent_confirm_title")}
+            description={t("workspace.launch.clear_recent_confirm_description")}
+            cancelText={t("action.cancel")}
+            confirmText={t("workspace.launch.clear_all")}
+            tone="danger"
+            onConfirm={() => {
+              void clearRecentWorkspaces();
+              setShowClearRecentConfirm(false);
+            }}
+          />
+        ) : null}
+      </>
     );
   }
 
   return (
-    <WorkbenchLayer
-      ariaLabel={launchTitle}
-      onOpenChange={(open) => {
-        if (!open) {
-          onClose();
-        }
-      }}
-      open
-    >
-      <div className="launch-modal">
-        <div className="launch-header">
-          <div className="launch-header-left">
-            <div className="launch-title">{launchTitle}</div>
-            <div className="launch-hint">{launchHint}</div>
-          </div>
-          <div className="launch-header-right">
-            <IconButton
-              aria-label={t("action.close")}
-              className="launch-close-btn"
-              icon={<X size={16} />}
-              onClick={onClose}
-              size="sm"
-            />
+    <>
+      <WorkbenchLayer
+        ariaLabel={launchTitle}
+        onOpenChange={(open) => {
+          if (!open) {
+            onClose();
+          }
+        }}
+        open
+      >
+        <div className="launch-modal">
+          <div className="launch-header">
+            <div className="launch-header-left">
+              <div className="launch-title">{launchTitle}</div>
+              <div className="launch-hint">{launchHint}</div>
+            </div>
+            <div className="launch-header-right">
+              <IconButton
+                aria-label={t("action.close")}
+                className="launch-close-btn"
+                icon={<X size={16} />}
+                onClick={onClose}
+                size="sm"
+              />
+            </div>
           </div>
-        </div>
 
-        {launchBody}
+          {launchBody}
 
-        <div className="launch-footer">
-          <button
-            className="launch-start-btn launch-start-btn--desktop"
-            onClick={() => void handleOpen()}
-            disabled={loading || !selectedPath}
-          >
-            {loading ? t("workspace.launch.starting") : t("workspace.launch.start")}
-          </button>
+          <div className="launch-footer">
+            <button
+              className="launch-start-btn launch-start-btn--desktop"
+              onClick={() => void handleOpen()}
+              disabled={loading || !selectedPath}
+            >
+              {loading ? t("workspace.launch.starting") : t("workspace.launch.start")}
+            </button>
+          </div>
         </div>
-      </div>
-    </WorkbenchLayer>
+      </WorkbenchLayer>
+
+      {showClearRecentConfirm ? (
+        <ConfirmDialog
+          open
+          onOpenChange={setShowClearRecentConfirm}
+          title={t("workspace.launch.clear_recent_confirm_title")}
+          description={t("workspace.launch.clear_recent_confirm_description")}
+          cancelText={t("action.cancel")}
+          confirmText={t("workspace.launch.clear_all")}
+          tone="danger"
+          onConfirm={() => {
+            void clearRecentWorkspaces();
+            setShowClearRecentConfirm(false);
+          }}
+        />
+      ) : null}
+    </>
   );
 }
 
diff --git a/packages/web/src/hooks/use-bootstrap.test.tsx b/packages/web/src/hooks/use-bootstrap.test.tsx
index 3b842b2b0..bcfe21a55 100644
--- a/packages/web/src/hooks/use-bootstrap.test.tsx
+++ b/packages/web/src/hooks/use-bootstrap.test.tsx
@@ -9,6 +9,7 @@ import { activationStatusAtom } from "../atoms/activation";
 import { authenticatedAtom, lastViewedTargetAtom, localeAtom } from "../atoms/app-ui";
 import { authEnabledAtom, connectionStatusAtom, wsClientAtom } from "../atoms/connection";
 import { workspacesAtom, workspacesLoadStateAtom } from "../atoms/workspaces";
+import { paneLayoutAtomFamily } from "../features/agent-panes/atoms/pane-layout";
 import {
   activeEditorTabAtomFamily,
   activeFilePathAtomFamily,
@@ -225,4 +226,88 @@ describe("useBootstrap", () => {
     );
     expect(store.get(workspacesAtom)["ws-1"]?.uiState).not.toHaveProperty("devBrowserTargetUrl");
   });
+
+  it("hydrates the persisted pane layout from the workspace list response", async () => {
+    const store = createStore();
+    const sendCommand = vi.fn(async (op: string) => {
+      if (op === "workspace.list") {
+        return [
+          {
+            id: "ws-1",
+            path: "/workspace",
+            targetRuntime: "native",
+            openedAt: 1,
+            lastActiveAt: 1,
+            uiState: {
+              leftPanelWidth: 280,
+              bottomPanelHeight: 200,
+              focusMode: false,
+              paneLayout: {
+                id: "root",
+                type: "split",
+                direction: "horizontal",
+                ratio: 0.6,
+                children: [
+                  {
+                    id: "session-pane",
+                    type: "leaf",
+                    leafKind: "session",
+                    sessionId: "sess-1",
+                  },
+                  {
+                    id: "editor-pane",
+                    type: "leaf",
+                    leafKind: "editor",
+                  },
+                ],
+              },
+            },
+          },
+        ];
+      }
+
+      if (op === "workspace.lastViewedTarget.get") {
+        return null;
+      }
+
+      throw new Error(`Unexpected command: ${op}`);
+    });
+
+    store.set(wsClientAtom, { sendCommand } as never);
+    store.set(connectionStatusAtom, "connected");
+    store.set(authEnabledAtom, false);
+    store.set(activationStatusAtom, "active");
+    store.set(authenticatedAtom, true);
+    store.set(localeAtom, "en");
+
+    renderHook(() => useBootstrap(), {
+      wrapper: wrapperFor(store),
+    });
+
+    await act(async () => {
+      await waitFor(() => {
+        expect(store.get(workspacesLoadStateAtom)).toBe("ready");
+      });
+    });
+
+    expect(store.get(paneLayoutAtomFamily("ws-1"))).toEqual({
+      id: "root",
+      type: "split",
+      direction: "horizontal",
+      ratio: 0.6,
+      children: [
+        {
+          id: "session-pane",
+          type: "leaf",
+          leafKind: "session",
+          sessionId: "sess-1",
+        },
+        {
+          id: "editor-pane",
+          type: "leaf",
+          leafKind: "editor",
+        },
+      ],
+    });
+  });
 });
diff --git a/packages/web/src/hooks/use-bootstrap.ts b/packages/web/src/hooks/use-bootstrap.ts
index a9810193a..fd82244a4 100644
--- a/packages/web/src/hooks/use-bootstrap.ts
+++ b/packages/web/src/hooks/use-bootstrap.ts
@@ -13,6 +13,10 @@ import {
   workspacesLoadErrorAtom,
   workspacesLoadStateAtom,
 } from "../atoms/workspaces";
+import {
+  normalizePaneLayout,
+  paneLayoutAtomFamily,
+} from "../features/agent-panes/atoms/pane-layout";
 import {
   hydrateWorkspaceEditorState,
   normalizeWorkspaceEditorUiState,
@@ -120,6 +124,10 @@ export function useBootstrap() {
           for (const workspace of nextWorkspaces) {
             wsMap[workspace.id] = workspace;
             hydrateWorkspaceEditorState(store, workspace.id, workspace.uiState);
+            const paneLayout = normalizePaneLayout(workspace.uiState?.paneLayout);
+            if (paneLayout) {
+              store.set(paneLayoutAtomFamily(workspace.id), paneLayout);
+            }
           }
 
           setWorkspaces(wsMap);
diff --git a/packages/web/src/lib/i18n.test.ts b/packages/web/src/lib/i18n.test.ts
index 038c4114c..ac393a038 100644
--- a/packages/web/src/lib/i18n.test.ts
+++ b/packages/web/src/lib/i18n.test.ts
@@ -74,6 +74,13 @@ describe("i18n coverage", () => {
     expect(en.skills.targets.summary).toBe("{count} enabled");
   });
 
+  it("describes mobile empty-state file and terminal access from the top bar", () => {
+    expect(zh.mobile.empty.files_terminal_hint).toBe("文件和终端可继续通过顶部栏访问。");
+    expect(en.mobile.empty.files_terminal_hint).toBe(
+      "Files and Terminal stay available from the top bar."
+    );
+  });
+
   it("resolves every static translation key used in source files", () => {
     const localeKeys = new Set(flattenKeys(zh));
     const sourceRoot = path.resolve(__dirname, "..");
diff --git a/packages/web/src/lib/skill-path-drag.test.ts b/packages/web/src/lib/skill-path-drag.test.ts
new file mode 100644
index 000000000..6331afcbb
--- /dev/null
+++ b/packages/web/src/lib/skill-path-drag.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  getSkillPathDragPayload,
+  hasSkillPathDragType,
+  SKILL_PATH_DRAG_MIME,
+  setSkillPathDragData,
+  toSkillDragEditorPath,
+} from "./skill-path-drag";
+
+describe("skill-path-drag", () => {
+  it("writes the custom mime payload and plain text absolute path", () => {
+    const setData = vi.fn();
+    const dataTransfer = {
+      effectAllowed: "none",
+      setData,
+    } as unknown as DataTransfer;
+
+    setSkillPathDragData(dataTransfer, {
+      skillSlug: "my-review-skill",
+      path: "refs/guide.md",
+      absolutePath: "/root/.agents/skills/my-review-skill/refs/guide.md",
+      kind: "file",
+    });
+
+    expect(dataTransfer.effectAllowed).toBe("copy");
+    expect(setData).toHaveBeenNthCalledWith(
+      1,
+      SKILL_PATH_DRAG_MIME,
+      JSON.stringify({
+        skillSlug: "my-review-skill",
+        path: "refs/guide.md",
+        absolutePath: "/root/.agents/skills/my-review-skill/refs/guide.md",
+        kind: "file",
+      })
+    );
+    expect(setData).toHaveBeenNthCalledWith(
+      2,
+      "text/plain",
+      "/root/.agents/skills/my-review-skill/refs/guide.md"
+    );
+  });
+
+  it("reads a valid payload only when the custom mime type is present", () => {
+    const dataTransfer = {
+      types: [SKILL_PATH_DRAG_MIME, "text/plain"],
+      getData: vi.fn((type: string) =>
+        type === SKILL_PATH_DRAG_MIME
+          ? JSON.stringify({
+              skillSlug: "my-review-skill",
+              path: "SKILL.md",
+              absolutePath: "/root/.agents/skills/my-review-skill/SKILL.md",
+              kind: "file",
+            })
+          : "/root/.agents/skills/my-review-skill/SKILL.md"
+      ),
+    } as unknown as DataTransfer;
+
+    expect(hasSkillPathDragType(dataTransfer)).toBe(true);
+    expect(getSkillPathDragPayload(dataTransfer)).toEqual({
+      skillSlug: "my-review-skill",
+      path: "SKILL.md",
+      absolutePath: "/root/.agents/skills/my-review-skill/SKILL.md",
+      kind: "file",
+    });
+  });
+
+  it("returns null for invalid payloads", () => {
+    expect(
+      getSkillPathDragPayload({
+        types: [SKILL_PATH_DRAG_MIME],
+        getData: () => "{bad json",
+      } as unknown as DataTransfer)
+    ).toBeNull();
+
+    expect(
+      getSkillPathDragPayload({
+        types: [SKILL_PATH_DRAG_MIME],
+        getData: () =>
+          JSON.stringify({
+            skillSlug: "my-review-skill",
+            path: "",
+            absolutePath: "/root/.agents/skills/my-review-skill",
+            kind: "dir",
+          }),
+      } as unknown as DataTransfer)
+    ).toBeNull();
+  });
+
+  it("derives a skill editor path only for file payloads", () => {
+    expect(
+      toSkillDragEditorPath({
+        skillSlug: "my-review-skill",
+        path: "refs/guide.md",
+        absolutePath: "/root/.agents/skills/my-review-skill/refs/guide.md",
+        kind: "file",
+      })
+    ).toBe("skill:my-review-skill/refs/guide.md");
+
+    expect(
+      toSkillDragEditorPath({
+        skillSlug: "my-review-skill",
+        path: ".",
+        absolutePath: "/root/.agents/skills/my-review-skill",
+        kind: "dir",
+      })
+    ).toBeNull();
+  });
+});
diff --git a/packages/web/src/lib/skill-path-drag.ts b/packages/web/src/lib/skill-path-drag.ts
new file mode 100644
index 000000000..9e7d32fe0
--- /dev/null
+++ b/packages/web/src/lib/skill-path-drag.ts
@@ -0,0 +1,99 @@
+import { toSkillEditorPath } from "../features/code-editor/skill-editor-path";
+
+export const SKILL_PATH_DRAG_MIME = "application/x-coder-studio-skill-path";
+export const SKILL_PATH_DRAG_START_EVENT = "coder-studio:skill-path-drag-start";
+export const SKILL_PATH_DRAG_END_EVENT = "coder-studio:skill-path-drag-end";
+
+export interface SkillPathDragPayload {
+  skillSlug: string;
+  path: string;
+  absolutePath: string;
+  kind: "file" | "dir";
+}
+
+let clearSkillPathDragEndListeners: (() => void) | null = null;
+
+export function isSkillPathDragPayload(value: unknown): value is SkillPathDragPayload {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+
+  const payload = value as Record<string, unknown>;
+
+  return (
+    typeof payload.skillSlug === "string" &&
+    payload.skillSlug.length > 0 &&
+    typeof payload.path === "string" &&
+    payload.path.length > 0 &&
+    typeof payload.absolutePath === "string" &&
+    payload.absolutePath.length > 0 &&
+    (payload.kind === "file" || payload.kind === "dir")
+  );
+}
+
+export function hasSkillPathDragType(
+  dataTransfer: Pick<DataTransfer, "types"> | null | undefined
+): boolean {
+  return Array.from(dataTransfer?.types ?? []).includes(SKILL_PATH_DRAG_MIME);
+}
+
+export function setSkillPathDragData(
+  dataTransfer: Pick<DataTransfer, "setData" | "effectAllowed">,
+  payload: SkillPathDragPayload
+): void {
+  dataTransfer.effectAllowed = "copy";
+  dataTransfer.setData(SKILL_PATH_DRAG_MIME, JSON.stringify(payload));
+  dataTransfer.setData("text/plain", payload.absolutePath);
+  announceSkillPathDragStart(payload);
+}
+
+export function getSkillPathDragPayload(
+  dataTransfer: Pick<DataTransfer, "types" | "getData"> | null | undefined
+): SkillPathDragPayload | null {
+  if (!hasSkillPathDragType(dataTransfer)) {
+    return null;
+  }
+
+  try {
+    const raw = dataTransfer?.getData(SKILL_PATH_DRAG_MIME) ?? "";
+    const parsed: unknown = JSON.parse(raw);
+    return isSkillPathDragPayload(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function toSkillDragEditorPath(payload: SkillPathDragPayload): string | null {
+  if (payload.kind !== "file") {
+    return null;
+  }
+
+  return toSkillEditorPath(payload.skillSlug, payload.path);
+}
+
+export function announceSkillPathDragStart(payload: SkillPathDragPayload): void {
+  if (typeof window === "undefined" || typeof CustomEvent === "undefined") {
+    return;
+  }
+
+  clearSkillPathDragEndListeners?.();
+  window.dispatchEvent(new CustomEvent(SKILL_PATH_DRAG_START_EVENT, { detail: payload }));
+
+  const finishDrag = () => announceSkillPathDragEnd();
+  window.addEventListener("dragend", finishDrag, { once: true });
+  window.addEventListener("drop", finishDrag, { once: true });
+  clearSkillPathDragEndListeners = () => {
+    window.removeEventListener("dragend", finishDrag);
+    window.removeEventListener("drop", finishDrag);
+  };
+}
+
+export function announceSkillPathDragEnd(): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  clearSkillPathDragEndListeners?.();
+  clearSkillPathDragEndListeners = null;
+  window.dispatchEvent(new Event(SKILL_PATH_DRAG_END_EVENT));
+}
diff --git a/packages/web/src/locales/en.json b/packages/web/src/locales/en.json
index fba02ddad..ab2efef53 100644
--- a/packages/web/src/locales/en.json
+++ b/packages/web/src/locales/en.json
@@ -54,7 +54,8 @@
     "no": "No",
     "ok": "OK",
     "all": "All",
-    "active": "Active"
+    "active": "Active",
+    "create": "Create"
   },
   "action": {
     "open": "Open",
@@ -70,11 +71,13 @@
     "commit": "Commit",
     "push": "Push",
     "pull": "Pull",
+    "open_source": "Open Source File",
     "refresh": "Refresh",
     "settings": "Settings",
     "cancel": "Cancel",
     "confirm": "Confirm",
     "close": "Close",
+    "edit": "Edit",
     "apply": "Apply",
     "reset": "Reset",
     "search": "Search",
@@ -209,12 +212,18 @@
       "type_filter": "Memory type",
       "all_types": "All types",
       "types": {
-        "feature": "Feature",
+        "wiki": "Wiki",
+        "issue": "Issue",
         "todo": "Todo",
-        "bugfix": "Bugfix",
-        "project": "Project",
         "note": "Note"
       },
+      "status_label": "Status",
+      "statuses": {
+        "not_started": "Not started",
+        "in_progress": "In progress",
+        "pending_verification": "Pending verification",
+        "completed": "Completed"
+      },
       "active_count": "{count} active entries",
       "active_count_one": "{count} active entry",
       "entries": "Memory entries",
@@ -238,7 +247,9 @@
       "title": "Quick Jump",
       "placeholder": "Type a filename or path",
       "no_results": "No matching files found.",
-      "failed": "File search failed. Try again."
+      "failed": "File search failed. Try again.",
+      "expand_label": "Expand Quick Jump",
+      "collapse_label": "Collapse Quick Jump"
     },
     "open_editors": {
       "title_with_count": "{title} ({count})",
@@ -333,9 +344,13 @@
         "failed": "Failed"
       },
       "source": {
-        "skillhub": "skills-hub",
-        "local": "Local",
+        "installed": "Installed",
+        "custom": "Custom",
         "builtin": "Built-in"
+      },
+      "origin": {
+        "skillhub": "skills-hub",
+        "filesystem": "Local"
       }
     },
     "search": {
@@ -372,6 +387,11 @@
       "title": "Start Workspace",
       "recent_title": "Recent Workspaces",
       "open_recent": "Open recent workspace {name}",
+      "remove_recent": "Remove {name} from recent workspaces",
+      "clear_recent_workspaces": "Clear all recent workspaces",
+      "clear_recent_confirm_title": "Clear recent workspaces?",
+      "clear_recent_confirm_description": "This only clears the recent workspace list. It does not delete any project directories from disk.",
+      "clear_all": "Clear all",
       "home_directory": "Home Directory",
       "go_up": "Go Up",
       "new_folder": "New Folder",
@@ -407,6 +427,20 @@
   },
   "skills": {
     "title": "Skills",
+    "custom_title": "Custom Skills",
+    "custom_expand_label": "Expand Custom Skills",
+    "custom_collapse_label": "Collapse Custom Skills",
+    "custom_new": "New Skill",
+    "custom_empty": "No custom skills yet.",
+    "custom_create_title": "Create Custom Skill",
+    "custom_create_name": "Skill Name",
+    "custom_create_name_required": "Enter a skill name",
+    "custom_create_placeholder": "My Review Skill",
+    "custom_create_helper": "We will create a folder with SKILL.md under your global skills directory.",
+    "custom_files_title": "Files",
+    "custom_new_file": "New File",
+    "custom_new_folder": "New Folder",
+    "custom_delete": "Delete",
     "discover_title": "Discover",
     "recommendations_title": "Recommended",
     "recommendations_expand_label": "Expand Recommendations",
@@ -455,8 +489,14 @@
     "detail_source": "Source",
     "detail_library_path": "Library path",
     "detail_targets": "Agent Status",
+    "delete": "Delete",
     "uninstall": "Uninstall",
     "uninstall_tooltip": "Disable this skill first, then remove it from the shared skill library.",
+    "custom_remove_tooltip": "Delete this custom skill folder from your global skills directory.",
+    "custom_remove_confirm_title": "Delete {name}?",
+    "custom_remove_confirm_description": "This permanently deletes the custom skill folder and all files under it from your global skills directory.",
+    "custom_remove_confirm_mounted_description": "This custom skill is enabled on {count} target(s). Deleting it will disable it first, then permanently delete the skill folder and all files under it from your global skills directory.",
+    "custom_remove_confirm_confirm": "Delete Skill",
     "uninstall_confirm_title": "Remove {name}?",
     "uninstall_confirm_description": "This skill is enabled on {count} target(s). Removing it will disable it first, then delete it from the skill library.",
     "uninstall_confirm_confirm": "Remove Skill",
@@ -550,12 +590,16 @@
       "aria_label": "Workspace drawer",
       "close": "Close workspace drawer",
       "select_title": "Select workspace",
+      "current_workspace": "Current workspace {name}",
+      "expand_workspace": "Expand workspace {name}",
+      "collapse_workspace": "Collapse workspace {name}",
       "switch_to_workspace": "Switch to workspace {name}",
+      "create_session_in_workspace": "Create session in {name}",
       "close_workspace": "Close workspace {name}"
     },
     "empty": {
       "start_session": "Start a new agent session for this workspace.",
-      "files_terminal_hint": "Files and Terminal stay available from the bottom bar."
+      "files_terminal_hint": "Files and Terminal stay available from the top bar."
     }
   },
   "dev_browser": {
@@ -577,6 +621,7 @@
     "loading": "Opening...",
     "unsupported": "Service workers are unavailable in this browser or connection. Coder Studio will fall back to compatibility mode, but live updates may be limited.",
     "error": "Could not open the local preview.",
+    "embed_limitations": "Some local apps block iframe previews. If the page stays blank, open the URL in your browser or relax frame restrictions for local development.",
     "invalid_viewport": "Enter a width and height between 1 and 4096.",
     "empty_description": "Enter a loopback URL from a local dev server, such as localhost:8000."
   },
@@ -700,6 +745,12 @@
     "paste_dialog_submit": "Send",
     "hide": "Hide Terminal",
     "show": "Show Terminal",
+    "profile_chooser_label": "Choose Terminal Profile",
+    "profile_configure": "Configure Terminal Profiles...",
+    "open_default_profile": "Open Default: {label}",
+    "profile_source_custom": "Custom",
+    "profile_source_detected": "Detected",
+    "default_badge": "Default",
     "selector": {
       "switch": "Switch terminal",
       "title": "Terminal Sessions",
@@ -857,6 +908,11 @@
     "close_browser_tab": "Close Browser tab",
     "open_editor_view": "Open editor view",
     "open_editor_tabs": "Open editor tabs",
+    "editor_tab_actions": "Editor tab actions",
+    "keep_tab_open": "Keep Open",
+    "close_other_tabs": "Close Others",
+    "close_tabs_to_right": "Close to the Right",
+    "close_saved_tabs": "Close Saved",
     "current_file_path": "Current file path",
     "modified_unsaved_changes": "modified · Unsaved changes",
     "image_load_failed_body": "The image could not be loaded. The file may have been moved or is larger than the browser allows.",
@@ -867,6 +923,8 @@
     "image_zoom_actual": "Actual size",
     "image_zoom_level": "Zoom level",
     "image_zoom_fit_level": "Fit",
+    "canvas_zoom_controls": "Canvas zoom controls",
+    "canvas_zoom_reset": "Reset zoom",
     "image_diff_base": "Base",
     "image_diff_current": "Current",
     "image_diff_no_base": "No base image",
@@ -1335,6 +1393,26 @@
     "copy_on_select_failed_body": "Use Ctrl/Cmd+C to copy manually",
     "terminal_standard": "Standard",
     "terminal_compatibility": "Compatibility Mode",
+    "terminal_profiles": {
+      "title": "Terminal Profiles",
+      "hint": "Choose the default shell and manage reusable custom terminal launch presets. Detected profiles are read-only.",
+      "default_label": "Default terminal profile",
+      "current_default": "Current default",
+      "system_default": "System default",
+      "detected_profiles": "Detected profiles",
+      "detected_badge": "Detected",
+      "none_detected": "No detected profiles",
+      "custom_profiles": "Custom profiles",
+      "no_custom_profiles": "No custom profiles yet",
+      "profile_label": "Profile label",
+      "command": "Command",
+      "args": "Arguments",
+      "args_hint": "Enter one argument per line.",
+      "save_custom": "Save custom profile",
+      "edit_profile": "Edit {label}",
+      "delete_profile": "Delete {label}",
+      "pending_refresh": "Available after profile refresh"
+    },
     "provider": {
       "title": "Agent Settings",
       "status": "Status",
@@ -1457,7 +1535,7 @@
     "placeholder_description": "This task only builds the desktop shell. Route-aware section content will be wired in a later task.",
     "category": {
       "settings": "Settings",
-      "settings_hint": "Adjust workspace behavior, providers, appearance, and shortcuts.",
+      "settings_hint": "Adjust workspace, agent, terminal, appearance, and shortcut behavior.",
       "analysis": "Analysis & Diagnostics",
       "analysis_hint": "Review analytics, monitoring, and diagnostics surfaces.",
       "about": "About & Updates",
@@ -1465,9 +1543,10 @@
     },
     "section": {
       "settings": {
-        "general_hint": "Core workspace, notification, terminal, and language preferences.",
+        "general_hint": "Core workspace, notification, language, and runtime preferences.",
         "agents": "Agents",
         "agents_hint": "Provider selection, commands, and agent-specific configuration.",
+        "terminal_hint": "Renderer, copy-on-select, launch profiles, and terminal font sizes.",
         "appearance_hint": "Theme, background, and material preferences.",
         "shortcuts_hint": "Keyboard bindings and common interaction shortcuts."
       },
diff --git a/packages/web/src/locales/zh.json b/packages/web/src/locales/zh.json
index 739688c5d..6dbf84fd2 100644
--- a/packages/web/src/locales/zh.json
+++ b/packages/web/src/locales/zh.json
@@ -54,7 +54,8 @@
     "no": "否",
     "ok": "确定",
     "all": "全部",
-    "active": "当前"
+    "active": "当前",
+    "create": "创建"
   },
   "action": {
     "open": "打开",
@@ -70,11 +71,13 @@
     "commit": "提交",
     "push": "推送",
     "pull": "拉取",
+    "open_source": "打开源文件",
     "refresh": "刷新",
     "settings": "设置",
     "cancel": "取消",
     "confirm": "确认",
     "close": "关闭",
+    "edit": "编辑",
     "apply": "应用",
     "reset": "重置",
     "search": "搜索",
@@ -210,12 +213,18 @@
       "type_filter": "记忆类型",
       "all_types": "全部类型",
       "types": {
-        "feature": "功能",
+        "wiki": "Wiki",
+        "issue": "问题",
         "todo": "待办",
-        "bugfix": "修复",
-        "project": "项目",
         "note": "备注"
       },
+      "status_label": "状态",
+      "statuses": {
+        "not_started": "待开始",
+        "in_progress": "进行中",
+        "pending_verification": "待验证",
+        "completed": "已完成"
+      },
       "active_count": "{count} 条当前记忆",
       "active_count_one": "{count} 条当前记忆",
       "entries": "记忆条目",
@@ -239,7 +248,9 @@
       "title": "快速跳转",
       "placeholder": "输入文件名或路径",
       "no_results": "未找到匹配文件。",
-      "failed": "文件搜索失败，请重试。"
+      "failed": "文件搜索失败，请重试。",
+      "expand_label": "展开快速跳转",
+      "collapse_label": "收起快速跳转"
     },
     "open_editors": {
       "title_with_count": "{title} ({count})",
@@ -334,9 +345,13 @@
         "failed": "失败"
       },
       "source": {
-        "skillhub": "skills-hub",
-        "local": "本地",
+        "installed": "已安装",
+        "custom": "自定义",
         "builtin": "内置"
+      },
+      "origin": {
+        "skillhub": "skills-hub",
+        "filesystem": "本地"
       }
     },
     "extensions": {
@@ -384,6 +399,11 @@
       "title": "启动工作区",
       "recent_title": "最近工作区",
       "open_recent": "打开最近工作区 {name}",
+      "remove_recent": "从最近工作区中移除 {name}",
+      "clear_recent_workspaces": "清空全部最近工作区",
+      "clear_recent_confirm_title": "清空最近工作区？",
+      "clear_recent_confirm_description": "这只会清空最近工作区列表，不会删除磁盘上的任何项目目录。",
+      "clear_all": "全部清空",
       "home_directory": "主目录",
       "go_up": "返回上一级",
       "new_folder": "新建文件夹",
@@ -419,6 +439,20 @@
   },
   "skills": {
     "title": "Skills",
+    "custom_title": "自定义 Skill",
+    "custom_expand_label": "展开自定义 Skill",
+    "custom_collapse_label": "收起自定义 Skill",
+    "custom_new": "新建 Skill",
+    "custom_empty": "还没有自定义 Skill。",
+    "custom_create_title": "创建自定义 Skill",
+    "custom_create_name": "Skill 名称",
+    "custom_create_name_required": "请输入 Skill 名称",
+    "custom_create_placeholder": "我的评审 Skill",
+    "custom_create_helper": "我们会在你的全局 skills 目录下创建一个包含 SKILL.md 的文件夹。",
+    "custom_files_title": "文件",
+    "custom_new_file": "新建文件",
+    "custom_new_folder": "新建文件夹",
+    "custom_delete": "删除",
     "discover_title": "发现技能",
     "recommendations_title": "推荐",
     "recommendations_expand_label": "展开推荐 Skill",
@@ -467,8 +501,14 @@
     "detail_source": "来源",
     "detail_library_path": "库路径",
     "detail_targets": "启用状态",
+    "delete": "删除",
     "uninstall": "卸载",
     "uninstall_tooltip": "先停用，再从共享 Skill 库中移除。",
+    "custom_remove_tooltip": "从你的全局 skills 目录中删除这个自定义 Skill 文件夹。",
+    "custom_remove_confirm_title": "删除 {name}？",
+    "custom_remove_confirm_description": "这会从你的全局 skills 目录中永久删除这个自定义 Skill 文件夹及其所有文件。",
+    "custom_remove_confirm_mounted_description": "这个自定义 Skill 已在 {count} 个目标中启用。删除时会先停用，再从你的全局 skills 目录中永久删除这个 Skill 文件夹及其所有文件。",
+    "custom_remove_confirm_confirm": "删除 Skill",
     "uninstall_confirm_title": "卸载 {name}？",
     "uninstall_confirm_description": "这个 Skill 已在 {count} 个目标中启用。卸载时会先停用，再从 Skill 库中移除。",
     "uninstall_confirm_confirm": "卸载 Skill",
@@ -562,12 +602,16 @@
       "aria_label": "工作区抽屉",
       "close": "关闭工作区抽屉",
       "select_title": "选择工作区",
+      "current_workspace": "当前工作区 {name}",
+      "expand_workspace": "展开工作区 {name}",
+      "collapse_workspace": "收起工作区 {name}",
       "switch_to_workspace": "切换到工作区 {name}",
+      "create_session_in_workspace": "在 {name} 中创建会话",
       "close_workspace": "关闭工作区 {name}"
     },
     "empty": {
       "start_session": "为当前工作区启动一个新的 Agent 会话。",
-      "files_terminal_hint": "文件和终端可继续通过底部栏访问。"
+      "files_terminal_hint": "文件和终端可继续通过顶部栏访问。"
     }
   },
   "dev_browser": {
@@ -589,6 +633,7 @@
     "loading": "正在打开...",
     "unsupported": "当前浏览器或连接不支持 Service Worker。Coder Studio 将降级为兼容模式打开页面，但实时更新能力可能受限。",
     "error": "无法打开本地预览。",
+    "embed_limitations": "部分本地应用会阻止 iframe 预览。如果页面保持空白，请直接在浏览器中打开该 URL，或在本地开发时放宽嵌入限制。",
     "invalid_viewport": "请输入 1 到 4096 之间的宽度和高度。",
     "empty_description": "输入本地开发服务的 loopback 地址，例如 localhost:8000。"
   },
@@ -712,6 +757,12 @@
     "paste_dialog_submit": "发送",
     "hide": "隐藏终端",
     "show": "显示终端",
+    "profile_chooser_label": "选择终端配置",
+    "profile_configure": "管理终端配置...",
+    "open_default_profile": "打开默认配置：{label}",
+    "profile_source_custom": "自定义",
+    "profile_source_detected": "检测到",
+    "default_badge": "默认",
     "selector": {
       "switch": "切换终端",
       "title": "终端会话",
@@ -869,6 +920,11 @@
     "close_browser_tab": "关闭浏览器标签",
     "open_editor_view": "打开编辑器视图",
     "open_editor_tabs": "打开的编辑器标签",
+    "editor_tab_actions": "编辑器标签操作",
+    "keep_tab_open": "保持打开",
+    "close_other_tabs": "关闭其他标签",
+    "close_tabs_to_right": "关闭右侧标签",
+    "close_saved_tabs": "关闭已保存标签",
     "current_file_path": "当前文件路径",
     "modified_unsaved_changes": "已修改 · 未保存的更改",
     "image_load_failed_body": "图片无法加载。文件可能已被移动，或大小超出浏览器限制。",
@@ -879,6 +935,8 @@
     "image_zoom_actual": "原始大小",
     "image_zoom_level": "缩放比例",
     "image_zoom_fit_level": "适应",
+    "canvas_zoom_controls": "Canvas 缩放控制",
+    "canvas_zoom_reset": "重置缩放",
     "image_diff_base": "基准",
     "image_diff_current": "当前",
     "image_diff_no_base": "没有基准图片",
@@ -928,12 +986,12 @@
     "no_commits": "暂无提交",
     "stage": "暂存",
     "unstage": "取消暂存",
-    "stage_all": "暂存全部",
+    "stage_all": "添加全部",
     "unstage_all": "取消暂存全部",
     "stage_failed_title": "暂存失败",
     "unstage_failed_title": "取消暂存失败",
     "discard": "放弃",
-    "discard_all": "放弃全部",
+    "discard_all": "撤销全部",
     "discard_failed_title": "放弃失败",
     "stage_file": "暂存文件",
     "unstage_file": "取消暂存文件",
@@ -1347,6 +1405,26 @@
     "copy_on_select_failed_body": "请使用 Ctrl/Cmd+C 手动复制",
     "terminal_standard": "标准",
     "terminal_compatibility": "兼容模式",
+    "terminal_profiles": {
+      "title": "终端配置",
+      "hint": "选择默认 shell，并管理可复用的自定义终端启动配置。检测到的配置为只读。",
+      "default_label": "默认终端配置",
+      "current_default": "当前默认",
+      "system_default": "系统默认",
+      "detected_profiles": "检测到的配置",
+      "detected_badge": "检测到",
+      "none_detected": "未检测到配置",
+      "custom_profiles": "自定义配置",
+      "no_custom_profiles": "暂无自定义配置",
+      "profile_label": "配置名称",
+      "command": "命令",
+      "args": "参数",
+      "args_hint": "每行输入一个参数。",
+      "save_custom": "保存自定义配置",
+      "edit_profile": "编辑 {label}",
+      "delete_profile": "删除 {label}",
+      "pending_refresh": "配置刷新后可用"
+    },
     "provider": {
       "title": "Agent 设置",
       "status": "状态",
@@ -1469,7 +1547,7 @@
     "placeholder_description": "这个任务只搭建桌面端外壳，具体分区内容会在后续任务里接入。",
     "category": {
       "settings": "设置",
-      "settings_hint": "调整工作区行为、provider、外观和快捷键。",
+      "settings_hint": "调整工作区、agent、终端、外观和快捷键行为。",
       "analysis": "分析与诊断",
       "analysis_hint": "查看工作分析、性能监控和环境诊断页面。",
       "about": "关于与更新",
@@ -1477,9 +1555,10 @@
     },
     "section": {
       "settings": {
-        "general_hint": "工作区、通知、终端和语言等基础偏好。",
+        "general_hint": "工作区、通知、语言和运行时等基础偏好。",
         "agents": "Agents",
         "agents_hint": "Provider 选择、命令参数和 agent 相关配置。",
+        "terminal_hint": "终端渲染、选中复制、启动配置和终端字号。",
         "appearance_hint": "主题、背景和材质偏好。",
         "shortcuts_hint": "键盘绑定和常用交互快捷键。"
       },
diff --git a/packages/web/src/shells/desktop-shell.test.tsx b/packages/web/src/shells/desktop-shell.test.tsx
index 6077d041b..0fac535b7 100644
--- a/packages/web/src/shells/desktop-shell.test.tsx
+++ b/packages/web/src/shells/desktop-shell.test.tsx
@@ -107,7 +107,7 @@ describe("DesktopShell auth gating", () => {
     expect(screen.queryByText("LoginPage")).not.toBeInTheDocument();
   });
 
-  it("renders SettingsPage on /settings while auth status is still unknown", () => {
+  it("shows the loading shell on /settings while auth status is still unknown", () => {
     window.history.replaceState({}, "", "/settings");
 
     const store = createStore();
@@ -117,8 +117,9 @@ describe("DesktopShell auth gating", () => {
 
     renderShell(store);
 
-    expect(screen.getByText("SettingsPage")).toBeInTheDocument();
-    expect(screen.queryByText("正在连接工作区...")).not.toBeInTheDocument();
+    expect(screen.getByText("正在连接工作区...")).toBeInTheDocument();
+    expect(document.querySelector(".app-loading-shell")).toBeTruthy();
+    expect(screen.queryByText("SettingsPage")).not.toBeInTheDocument();
   });
 
   it("renders DiagnosticsPage on /diagnostics while auth status is still unknown", () => {
@@ -149,8 +150,8 @@ describe("DesktopShell auth gating", () => {
     expect(screen.queryByText("正在连接工作区...")).not.toBeInTheDocument();
   });
 
-  it("renders MoreFeaturesPage on /more/settings/general while auth status is still unknown", async () => {
-    window.history.replaceState({}, "", "/more/settings/general");
+  it("renders MoreFeaturesPage on /more/settings/terminal while auth status is still unknown", async () => {
+    window.history.replaceState({}, "", "/more/settings/terminal");
 
     const store = createStore();
     store.set(connectionStatusAtom, "connected");
diff --git a/packages/web/src/shells/desktop-shell.tsx b/packages/web/src/shells/desktop-shell.tsx
index 993178be3..a2ab8805e 100644
--- a/packages/web/src/shells/desktop-shell.tsx
+++ b/packages/web/src/shells/desktop-shell.tsx
@@ -18,7 +18,6 @@ import { MoreFeaturesPage } from "../features/more";
 import { NotFoundPage } from "../features/not-found";
 import { ToastContainer } from "../features/notifications";
 import { QuickOpen } from "../features/quick-open";
-import { SettingsPage } from "../features/settings";
 import { WelcomePage } from "../features/welcome";
 import { WorkAnalyticsPage } from "../features/work-analysis";
 import { WorkspaceDesktopView } from "../features/workspace/views/desktop/workspace-desktop-view";
@@ -43,7 +42,6 @@ export function DesktopShell() {
   const location = useLocation();
   const authUnknown = authEnabled === null;
   const shouldBypassAuthLoading =
-    location.pathname.startsWith("/settings") ||
     location.pathname.startsWith("/analytics") ||
     location.pathname.startsWith("/monitoring") ||
     location.pathname.startsWith("/diagnostics") ||
@@ -87,7 +85,6 @@ export function DesktopShell() {
                 </WorkspaceRouteGate>
               }
             />
-            <Route path="/settings" element={<SettingsPage />} />
             <Route path="*" element={<NotFoundPage />} />
           </Routes>
         )}
diff --git a/packages/web/src/shells/mobile-shell/index.test.tsx b/packages/web/src/shells/mobile-shell/index.test.tsx
index 57ef2677c..d015c37fe 100644
--- a/packages/web/src/shells/mobile-shell/index.test.tsx
+++ b/packages/web/src/shells/mobile-shell/index.test.tsx
@@ -628,6 +628,23 @@ function renderMobileShell({
   return { store, sendCommand, sendTerminalInput, ...view };
 }
 
+async function openWorkspaceDrawer(user: ReturnType<typeof userEvent.setup>) {
+  await user.click(screen.getByRole("button", { name: "Switch workspace" }));
+  return screen.findByRole("complementary", { name: "Workspace drawer" });
+}
+
+async function openWorkspaceDrawerCreateFlow(user: ReturnType<typeof userEvent.setup>) {
+  await openWorkspaceDrawer(user);
+  await user.click(screen.getByRole("button", { name: "Create session in Alpha" }));
+  return screen.findByRole("region", { name: "Select Agent sheet" });
+}
+
+function getWorkspaceDrawerSessionRow(sessionName: string) {
+  return screen
+    .getByRole("button", { name: `Switch to agent ${sessionName}` })
+    .closest(".mobile-workspace-drawer__child-session-row");
+}
+
 beforeEach(() => {
   window.matchMedia = vi.fn((query: string) => ({
     matches: query === "(max-width: 899px), (pointer: coarse)",
@@ -654,24 +671,30 @@ afterEach(() => {
 });
 
 describe("MobileShell Phase 2 workspace", () => {
-  it("renders mobile workspace chrome on /workspace", async () => {
+  it("renders the workspace topbar actions on /workspace and opens the connected sheets", async () => {
+    const user = userEvent.setup();
     renderMobileShell({ initialEntry: "/workspace" });
 
     expect(screen.getByRole("button", { name: "Switch workspace" })).toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Switch active agent" })).not.toBeInTheDocument();
-    const agentButton = screen.getByRole("button", { name: "Open Agent sheet" });
     const filesButton = screen.getByRole("button", { name: "Open Files sheet" });
     const terminalButton = screen.getByRole("button", { name: "Open Terminal sheet" });
-    expect(agentButton).toBeInTheDocument();
+    const moreFeaturesButton = screen.getByRole("button", { name: "More Features" });
+    const fullscreenButton = screen.getByRole("button", { name: "Enter Fullscreen" });
     expect(filesButton).toBeInTheDocument();
     expect(terminalButton).toBeInTheDocument();
-    expect(agentButton.querySelector('[data-icon-semantic="mobile.dock.agent"]')).toBeTruthy();
+    expect(moreFeaturesButton).toBeInTheDocument();
+    expect(fullscreenButton).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Open Agent sheet" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("tablist", { name: "Mobile agents" })).not.toBeInTheDocument();
+    expect(screen.queryByText("已连接")).not.toBeInTheDocument();
     expect(filesButton.querySelector('[data-icon-semantic="mobile.dock.files"]')).toBeTruthy();
     expect(
       terminalButton.querySelector('[data-icon-semantic="mobile.dock.terminal"]')
     ).toBeTruthy();
-    expect(screen.queryByRole("tablist", { name: "Mobile agents" })).not.toBeInTheDocument();
-    expect(screen.queryByText("已连接")).not.toBeInTheDocument();
+    expect(
+      moreFeaturesButton.querySelector('[data-icon-semantic="nav.workspaceMenu"]')
+    ).toBeTruthy();
     expect(screen.getByTestId("mobile-session-card")).toHaveTextContent("sess_2");
     expect(screen.getByTestId("mobile-session-card")).not.toHaveAttribute("data-readonly", "true");
     expect(document.querySelector(".mobile-shell__agent-stage .supervisor-card")).not.toBeNull();
@@ -686,6 +709,21 @@ describe("MobileShell Phase 2 workspace", () => {
       "mobile-shell__agent-stage"
     );
     expect(screen.queryByRole("textbox", { name: "Agent composer" })).not.toBeInTheDocument();
+
+    await user.click(filesButton);
+
+    expect(screen.getByRole("tablist", { name: "Files sheet tabs" })).toBeInTheDocument();
+
+    await user.click(screen.getByRole("button", { name: /back|返回/i }));
+
+    expect(screen.queryByRole("tablist", { name: "Files sheet tabs" })).not.toBeInTheDocument();
+
+    await user.click(terminalButton);
+
+    expect(screen.getByTestId("mobile-terminal-panel")).toBeInTheDocument();
+    expect(screen.getByRole("region", { name: "Terminal sheet" })).toHaveClass(
+      "mobile-sheet--fullscreen"
+    );
   });
 
   it("opens the mobile supervisor sheet when the shared strip-row details action is tapped", async () => {
@@ -893,9 +931,9 @@ describe("MobileShell Phase 2 workspace", () => {
     ).toBeInTheDocument();
   });
 
-  it("opens the workspace drawer and switches active workspace", async () => {
+  it("expands a non-active workspace from the mobile drawer without switching it", async () => {
     const user = userEvent.setup();
-    const sendCommand = vi.fn(async (op: string) => {
+    const sendCommand = vi.fn(async (op: string, args?: { workspaceId?: string }) => {
       if (op === "workspace.lastViewedTarget.set") {
         return {
           workspaceId: "ws-2",
@@ -903,21 +941,34 @@ describe("MobileShell Phase 2 workspace", () => {
         };
       }
 
+      if (op === "session.list" && args?.workspaceId === "ws-2") {
+        return [
+          createSession({
+            id: "sess_beta_1",
+            workspaceId: "ws-2",
+            terminalId: "term-beta-1",
+            providerId: "gemini",
+            state: "idle",
+            title: "Beta Gemini",
+          }),
+        ];
+      }
+
       return undefined;
     });
     const { store } = renderMobileShell({ initialEntry: "/workspace", sendCommand });
 
     await user.click(screen.getByRole("button", { name: "Switch workspace" }));
-    await user.click(screen.getByRole("button", { name: "Switch to workspace Beta" }));
+    await user.click(screen.getByRole("button", { name: "Expand workspace Beta" }));
 
     await waitFor(() => {
-      expect(sendCommand).toHaveBeenCalledWith(
-        "workspace.lastViewedTarget.set",
-        { workspaceId: "ws-2", sessionId: undefined },
-        undefined
-      );
+      expect(sendCommand).toHaveBeenCalledWith("session.list", { workspaceId: "ws-2" }, undefined);
     });
-    expect(store.get(activeWorkspaceIdAtom)).toBe("ws-2");
+    expect(store.get(activeWorkspaceIdAtom)).toBe("ws-1");
+    expect(
+      screen.queryByRole("button", { name: "Create session in Beta" })
+    ).not.toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Switch to agent Beta Gemini" })).toBeInTheDocument();
   });
 
   it("closes the active workspace from the mobile workspace drawer and falls back to the next workspace", async () => {
@@ -1007,19 +1058,33 @@ describe("MobileShell Phase 2 workspace", () => {
     });
   });
 
-  it("shows a more-features trigger instead of the workspace menu trigger", async () => {
+  it("keeps workspace-only topbar actions and removes the legacy agent trigger", async () => {
     renderMobileShell({ initialEntry: "/workspace" });
 
+    expect(screen.getByRole("button", { name: "Open Files sheet" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Open Terminal sheet" })).toBeInTheDocument();
     expect(screen.getByRole("button", { name: "More Features" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Enter Fullscreen" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Open Agent sheet" })).not.toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Workspace Menu" })).not.toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Open more actions" })).not.toBeInTheDocument();
     expect(screen.queryByRole("button", { name: "Quick Actions" })).not.toBeInTheDocument();
   });
 
-  it("preserves shared IconButton compatibility classes on mobile topbar icon-only triggers", async () => {
+  it("preserves shared button compatibility classes on mobile topbar icon actions", async () => {
     removeFullscreenApiForMobileShell();
     renderMobileShell({ initialEntry: "/workspace" });
 
+    expect(screen.getByRole("button", { name: "Open Files sheet" })).toHaveClass(
+      "btn",
+      "btn-ghost",
+      "mobile-topbar__icon-button"
+    );
+    expect(screen.getByRole("button", { name: "Open Terminal sheet" })).toHaveClass(
+      "btn",
+      "btn-ghost",
+      "mobile-topbar__icon-button"
+    );
     expect(screen.getByRole("button", { name: "More Features" })).toHaveClass(
       "btn",
       "btn-ghost",
@@ -1045,19 +1110,22 @@ describe("MobileShell Phase 2 workspace", () => {
     expect(screen.getByRole("button", { name: /^About & Updates/ })).toBeInTheDocument();
   });
 
-  it("shows a fullscreen toggle to the right of the more-features trigger when the browser supports fullscreen", async () => {
+  it("shows topbar action order as files, terminal, more features, fullscreen", async () => {
     installFullscreenApiForMobileShell();
     renderMobileShell({ initialEntry: "/workspace" });
 
+    const filesButton = screen.getByRole("button", { name: "Open Files sheet" });
+    const terminalButton = screen.getByRole("button", { name: "Open Terminal sheet" });
     const moreFeaturesButton = screen.getByRole("button", { name: "More Features" });
     const fullscreenButton = await screen.findByRole("button", { name: "Enter Fullscreen" });
     const actionButtons = Array.from(
       document.querySelector(".mobile-topbar__actions")?.children ?? []
     );
 
-    expect(actionButtons[0]).toBe(moreFeaturesButton);
-    expect(moreFeaturesButton.nextElementSibling).toBe(fullscreenButton);
-    expect(actionButtons[1]).toBe(fullscreenButton);
+    expect(actionButtons[0]).toBe(filesButton);
+    expect(actionButtons[1]).toBe(terminalButton);
+    expect(actionButtons[2]).toBe(moreFeaturesButton);
+    expect(actionButtons[3]).toBe(fullscreenButton);
   });
 
   it("keeps the fullscreen toggle visible on mobile when the browser does not support fullscreen", async () => {
@@ -1126,7 +1194,7 @@ describe("MobileShell Phase 2 workspace", () => {
     expect(screen.queryByText("LoginPage")).not.toBeInTheDocument();
   });
 
-  it("renders SettingsPage on mobile /settings while auth status is still unknown", () => {
+  it("shows the loading shell on mobile /settings while auth status is still unknown", () => {
     const store = createStore();
     store.set(connectionStatusAtom, "connected");
     store.set(authEnabledAtom, null);
@@ -1141,9 +1209,10 @@ describe("MobileShell Phase 2 workspace", () => {
       </Provider>
     );
 
-    expect(screen.getByText("SettingsPage")).toBeInTheDocument();
+    expect(screen.getByText("正在连接工作区...")).toBeInTheDocument();
+    expect(document.querySelector(".app-loading-shell")).toBeTruthy();
+    expect(screen.queryByText("SettingsPage")).not.toBeInTheDocument();
     expect(screen.getByTestId("location-display")).toHaveTextContent("/settings");
-    expect(screen.queryByText("正在连接工作区...")).not.toBeInTheDocument();
   });
 
   it("renders DiagnosticsPage on mobile /diagnostics while auth status is still unknown", () => {
@@ -1451,7 +1520,7 @@ describe("MobileShell Phase 2 workspace", () => {
 
   it("shows the global reconnecting banner on non-workspace mobile routes", () => {
     renderMobileShell({
-      initialEntry: "/settings",
+      initialEntry: "/more/settings/terminal",
       locale: "zh",
       connectionStatus: "reconnecting",
       withWorkspaces: false,
@@ -1469,65 +1538,59 @@ describe("MobileShell Phase 2 workspace", () => {
     expect(screen.getByText("Page not found")).toBeInTheDocument();
   });
 
-  it("switches the active session from the dock selector", async () => {
+  it("switches the active session from the workspace drawer", async () => {
     const user = userEvent.setup();
     renderMobileShell();
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    expect(screen.getByRole("region", { name: "Agent Sessions sheet" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "Create Session" })).toBeInTheDocument();
-    const activeRow = screen
-      .getByRole("button", {
-        name: "Codex",
-        description: /Switch to agent Codex CODEX/,
-      })
-      .closest(".mobile-select-sheet__item-row");
-    const inactiveRow = screen
-      .getByRole("button", {
-        name: "Claude",
-        description: /Switch to agent Claude CLAUDE/,
-      })
-      .closest(".mobile-select-sheet__item-row");
-    expect(activeRow).not.toBeNull();
-    expect(inactiveRow).not.toBeNull();
+    await user.click(screen.getByRole("button", { name: "Switch workspace" }));
+    expect(screen.getByRole("complementary", { name: "Workspace drawer" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Create session in Alpha" })).toBeInTheDocument();
     expect(
-      within(activeRow as HTMLElement).getByRole("button", { name: "Close Current Session" })
-    ).toBeInTheDocument();
+      screen.queryByRole("button", { name: "Create session in Beta" })
+    ).not.toBeInTheDocument();
     expect(
-      within(inactiveRow as HTMLElement).getByRole("button", { name: "Close Current Session" })
-    ).toBeInTheDocument();
+      screen.getByRole("button", {
+        name: "Switch to agent Codex",
+      })
+    ).toHaveAttribute("aria-current", "page");
+
     await user.click(
       screen.getByRole("button", {
-        name: "Claude",
-        description: /Switch to agent Claude CLAUDE/,
+        name: "Switch to agent Claude",
       })
     );
 
     expect(screen.getByTestId("mobile-session-card")).toHaveTextContent("sess_1");
   });
 
-  it("renders the agent sheet as a fullscreen mobile sheet on mobile", async () => {
+  it("opens the create-only agent sheet from the workspace drawer", async () => {
     const user = userEvent.setup();
     renderMobileShell();
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
+    await user.click(screen.getByRole("button", { name: "Switch workspace" }));
+    await user.click(screen.getByRole("button", { name: "Create session in Alpha" }));
 
-    expect(screen.getByRole("region", { name: "Agent Sessions sheet" })).toBeInTheDocument();
+    expect(screen.getByRole("region", { name: "Select Agent sheet" })).toBeInTheDocument();
     expect(document.querySelectorAll(".mobile-sheet-layer")).toHaveLength(1);
     expect(document.querySelector(".mobile-shell__bottom-stack .mobile-sheet-layer")).toBeNull();
+    expect(screen.queryByRole("region", { name: "Agent Sessions sheet" })).not.toBeInTheDocument();
   });
 
   it("dismisses the agent sheet when tapping the backdrop", async () => {
     const user = userEvent.setup();
-    renderMobileShell();
+    renderMobileShell({
+      sessions: [],
+      paneLayout: {
+        id: "root",
+        type: "leaf",
+      },
+    });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
+    await user.click(screen.getByRole("button", { name: "Create Session" }));
     await user.click(screen.getByRole("button", { name: "Dismiss current sheet" }));
 
     await waitFor(() => {
-      expect(
-        screen.queryByRole("region", { name: "Agent Sessions sheet" })
-      ).not.toBeInTheDocument();
+      expect(screen.queryByRole("region", { name: "Select Agent sheet" })).not.toBeInTheDocument();
     });
   });
 
@@ -1587,8 +1650,7 @@ describe("MobileShell Phase 2 workspace", () => {
       },
     });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    await user.click(screen.getByRole("button", { name: "Create Session" }));
+    await openWorkspaceDrawerCreateFlow(user);
 
     await user.click(screen.getByRole("button", { name: /Codex/ }));
 
@@ -1667,8 +1729,7 @@ describe("MobileShell Phase 2 workspace", () => {
       },
     });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    await user.click(screen.getByRole("button", { name: "Create Session" }));
+    await openWorkspaceDrawerCreateFlow(user);
 
     expect(screen.getByRole("region", { name: "Select Agent sheet" })).toBeInTheDocument();
 
@@ -1694,27 +1755,13 @@ describe("MobileShell Phase 2 workspace", () => {
     expect(screen.getByRole("button", { name: "Open Diagnostics" })).toBeInTheDocument();
   }, 15_000);
 
-  it("switches from session mode to provider mode inside a single mobile select sheet", async () => {
-    const user = userEvent.setup();
-    renderMobileShell();
-
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-
-    expect(screen.getByRole("region", { name: "Agent Sessions sheet" })).toBeInTheDocument();
-    expect(document.querySelectorAll(".mobile-sheet-layer")).toHaveLength(1);
-
-    await user.click(screen.getByRole("button", { name: "Create Session" }));
-
-    expect(screen.getByRole("region", { name: "Select Agent sheet" })).toBeInTheDocument();
-    expect(document.querySelectorAll(".mobile-sheet-layer")).toHaveLength(1);
-
-    await user.click(screen.getByRole("button", { name: "Back" }));
+  it("does not expose the legacy /agent route after moving session switching into the workspace drawer", () => {
+    renderMobileShell({ initialEntry: "/agent" });
 
-    expect(screen.getByRole("region", { name: "Agent Sessions sheet" })).toBeInTheDocument();
-    expect(document.querySelectorAll(".mobile-sheet-layer")).toHaveLength(1);
+    expect(screen.getByText("Page not found")).toBeInTheDocument();
   });
 
-  it("creates a new agent from the mobile session sheet", async () => {
+  it("creates a new agent from the workspace drawer create flow", async () => {
     const user = userEvent.setup();
     const hydratedSessions = [
       createSession({
@@ -1792,14 +1839,8 @@ describe("MobileShell Phase 2 workspace", () => {
       },
     });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    await user.click(screen.getByRole("button", { name: "Create Session" }));
-    await user.click(
-      screen.getByRole("button", {
-        name: "Codex",
-        description: "Start Codex session Start new session",
-      })
-    );
+    await openWorkspaceDrawerCreateFlow(user);
+    await user.click(screen.getByRole("button", { name: "Codex" }));
 
     await waitFor(() => {
       expect(screen.getByTestId("mobile-session-card")).toHaveTextContent("sess_3");
@@ -1835,25 +1876,24 @@ describe("MobileShell Phase 2 workspace", () => {
     });
   });
 
-  it("closes the agent sheet once when selecting an existing session", async () => {
+  it("closes the workspace drawer once when selecting an existing session", async () => {
     const user = userEvent.setup();
     renderMobileShell();
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
+    await user.click(screen.getByRole("button", { name: "Switch workspace" }));
     await user.click(
       screen.getByRole("button", {
-        name: "Claude",
-        description: /Switch to agent Claude CLAUDE/,
+        name: "Switch to agent Claude",
       })
     );
 
     await waitFor(() => {
       expect(
-        screen.queryByRole("region", { name: "Agent Sessions sheet" })
+        screen.queryByRole("complementary", { name: "Workspace drawer" })
       ).not.toBeInTheDocument();
     });
 
-    expect(document.querySelectorAll(".mobile-sheet-layer")).toHaveLength(0);
+    expect(document.querySelectorAll(".mobile-drawer-layer")).toHaveLength(0);
   });
 
   it("closes the active agent from the current session row action", async () => {
@@ -1883,13 +1923,8 @@ describe("MobileShell Phase 2 workspace", () => {
 
     renderMobileShell({ sendCommand });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    const activeRow = screen
-      .getByRole("button", {
-        name: "Codex",
-        description: /Switch to agent Codex CODEX/,
-      })
-      .closest(".mobile-select-sheet__item-row");
+    await openWorkspaceDrawer(user);
+    const activeRow = getWorkspaceDrawerSessionRow("Codex");
     expect(activeRow).not.toBeNull();
 
     await user.click(
@@ -2031,14 +2066,8 @@ describe("MobileShell Phase 2 workspace", () => {
     });
     closeStore = store;
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    await user.click(screen.getByRole("button", { name: "Create Session" }));
-    await user.click(
-      screen.getByRole("button", {
-        name: "Codex",
-        description: "Start Codex session Start new session",
-      })
-    );
+    await openWorkspaceDrawerCreateFlow(user);
+    await user.click(screen.getByRole("button", { name: "Codex" }));
 
     await waitFor(() => {
       expect(screen.getByTestId("mobile-session-card")).toHaveTextContent("sess_3");
@@ -2056,13 +2085,8 @@ describe("MobileShell Phase 2 workspace", () => {
     );
     expect(createdLayout.children?.[1]).not.toHaveProperty("closeBehavior");
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    const createdRow = screen
-      .getByRole("button", {
-        name: "Codex 2",
-        description: /Switch to agent Codex 2 CODEX/,
-      })
-      .closest(".mobile-select-sheet__item-row");
+    await openWorkspaceDrawer(user);
+    const createdRow = getWorkspaceDrawerSessionRow("Codex 2");
     expect(createdRow).not.toBeNull();
 
     await user.click(
@@ -2170,26 +2194,15 @@ describe("MobileShell Phase 2 workspace", () => {
       },
     });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    await user.click(screen.getByRole("button", { name: "Create Session" }));
-    await user.click(
-      screen.getByRole("button", {
-        name: "Codex",
-        description: "Start Codex session Start new session",
-      })
-    );
+    await openWorkspaceDrawerCreateFlow(user);
+    await user.click(screen.getByRole("button", { name: "Codex" }));
 
     await waitFor(() => {
       expect(screen.getByTestId("mobile-session-card")).toHaveTextContent("sess_3");
     });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    const createdRow = screen
-      .getByRole("button", {
-        name: "Codex 2",
-        description: /Switch to agent Codex 2 CODEX/,
-      })
-      .closest(".mobile-select-sheet__item-row");
+    await openWorkspaceDrawer(user);
+    const createdRow = getWorkspaceDrawerSessionRow("Codex 2");
     expect(createdRow).not.toBeNull();
 
     await user.click(
@@ -2350,13 +2363,8 @@ describe("MobileShell Phase 2 workspace", () => {
       expect(screen.getByTestId("mobile-session-card")).toHaveTextContent("sess_3");
     });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    const geminiRow = screen
-      .getByRole("button", {
-        name: "Gemini",
-        description: /Switch to agent Gemini GEMINI/,
-      })
-      .closest(".mobile-select-sheet__item-row");
+    await openWorkspaceDrawer(user);
+    const geminiRow = getWorkspaceDrawerSessionRow("Gemini");
     expect(geminiRow).not.toBeNull();
 
     await user.click(
@@ -2371,12 +2379,7 @@ describe("MobileShell Phase 2 workspace", () => {
       );
     });
 
-    await user.click(
-      screen.getByRole("button", {
-        name: "Codex",
-        description: /Switch to agent Codex CODEX/,
-      })
-    );
+    await user.click(screen.getByRole("button", { name: "Switch to agent Codex" }));
 
     await waitFor(() => {
       expect(screen.getByTestId("mobile-session-card")).toHaveTextContent("sess_2");
@@ -2427,13 +2430,8 @@ describe("MobileShell Phase 2 workspace", () => {
 
     renderMobileShell({ sendCommand });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    const inactiveRow = screen
-      .getByRole("button", {
-        name: "Claude",
-        description: /Switch to agent Claude CLAUDE/,
-      })
-      .closest(".mobile-select-sheet__item-row");
+    await openWorkspaceDrawer(user);
+    const inactiveRow = getWorkspaceDrawerSessionRow("Claude");
     expect(inactiveRow).not.toBeNull();
 
     await user.click(
@@ -2497,14 +2495,9 @@ describe("MobileShell Phase 2 workspace", () => {
       });
     });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
+    await openWorkspaceDrawer(user);
 
-    const hiddenRow = screen
-      .getByRole("button", {
-        name: "Remote Codex",
-        description: /Switch to agent Remote Codex CODEX/,
-      })
-      .closest(".mobile-select-sheet__item-row");
+    const hiddenRow = getWorkspaceDrawerSessionRow("Remote Codex");
     expect(hiddenRow).not.toBeNull();
 
     await user.click(
@@ -2534,18 +2527,18 @@ describe("MobileShell Phase 2 workspace", () => {
     });
   });
 
-  it("persists the global target when a mobile session is selected from the agent sheet", async () => {
+  it("switches to a non-active workspace only when its session is selected from the drawer", async () => {
     const user = userEvent.setup();
-    const sendCommand = vi.fn(async (op: string) => {
+    const sendCommand = vi.fn(async (op: string, args?: { workspaceId?: string }) => {
       if (op === "workspace.lastViewedTarget.set") {
         return {
-          workspaceId: "ws-1",
-          sessionId: "sess_1",
+          workspaceId: "ws-2",
+          sessionId: "sess_beta_1",
           updatedAt: 10,
         };
       }
 
-      if (op === "session.list") {
+      if (op === "session.list" && args?.workspaceId === "ws-1") {
         return [
           createSession({
             id: "sess_1",
@@ -2564,16 +2557,29 @@ describe("MobileShell Phase 2 workspace", () => {
         ];
       }
 
+      if (op === "session.list" && args?.workspaceId === "ws-2") {
+        return [
+          createSession({
+            id: "sess_beta_1",
+            workspaceId: "ws-2",
+            terminalId: "term-beta-1",
+            providerId: "gemini",
+            state: "idle",
+            title: "Beta Gemini",
+          }),
+        ];
+      }
+
       return undefined;
     });
 
-    renderMobileShell({ sendCommand });
+    const { store } = renderMobileShell({ sendCommand });
 
-    await user.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
+    await user.click(screen.getByRole("button", { name: "Switch workspace" }));
+    await user.click(screen.getByRole("button", { name: "Expand workspace Beta" }));
     await user.click(
       screen.getByRole("button", {
-        name: "Claude",
-        description: /Switch to agent Claude CLAUDE/,
+        name: "Switch to agent Beta Gemini",
       })
     );
 
@@ -2581,12 +2587,17 @@ describe("MobileShell Phase 2 workspace", () => {
       expect(sendCommand).toHaveBeenCalledWith(
         "workspace.lastViewedTarget.set",
         {
-          workspaceId: "ws-1",
-          sessionId: "sess_1",
+          workspaceId: "ws-2",
+          sessionId: "sess_beta_1",
         },
         undefined
       );
     });
+
+    await waitFor(() => {
+      expect(store.get(activeWorkspaceIdAtom)).toBe("ws-2");
+      expect(screen.getByTestId("mobile-session-card")).toHaveTextContent("sess_beta_1");
+    });
   });
 
   it("tracks the currently visible mobile session in app UI state and clears it on unmount", async () => {
@@ -2895,13 +2906,8 @@ describe("MobileShell Phase 2 workspace", () => {
       "closeBehavior"
     );
 
-    await userEvent.click(await screen.findByRole("button", { name: "Open Agent sheet" }));
-    const restoredRow = screen
-      .getByRole("button", {
-        name: "New Mobile Codex",
-        description: /Switch to agent New Mobile Codex CODEX/,
-      })
-      .closest(".mobile-select-sheet__item-row");
+    await userEvent.click(screen.getByRole("button", { name: "Switch workspace" }));
+    const restoredRow = getWorkspaceDrawerSessionRow("New Mobile Codex");
     expect(restoredRow).not.toBeNull();
 
     await userEvent.click(
@@ -3152,17 +3158,13 @@ describe("MobileShell Phase 2 workspace", () => {
     await user.click(screen.getByRole("button", { name: "Create Session" }));
 
     expect(screen.getByRole("region", { name: "Select Agent sheet" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Claude" })).toBeInTheDocument();
     expect(
-      screen.getByRole("button", {
-        name: "Claude",
-        description: "Start Claude session Start new session",
-      })
+      within(screen.getByRole("button", { name: "Claude" })).getByText("Start new session")
     ).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Codex" })).toBeInTheDocument();
     expect(
-      screen.getByRole("button", {
-        name: "Codex",
-        description: "Start Codex session Start new session",
-      })
+      within(screen.getByRole("button", { name: "Codex" })).getByText("Start new session")
     ).toBeInTheDocument();
   });
 
@@ -3179,18 +3181,17 @@ describe("MobileShell Phase 2 workspace", () => {
     });
 
     expect(screen.getByRole("button", { name: "切换工作区" })).toBeInTheDocument();
-    expect(screen.getByRole("button", { name: "打开 Agent 面板" })).toBeInTheDocument();
     expect(screen.getByRole("button", { name: "打开文件面板" })).toBeInTheDocument();
     expect(screen.getByRole("button", { name: "打开终端面板" })).toBeInTheDocument();
     expect(screen.getByText("为当前工作区启动一个新的 Agent 会话。")).toBeInTheDocument();
-    expect(screen.getByText("文件和终端可继续通过底部栏访问。")).toBeInTheDocument();
+    expect(screen.getByText("文件和终端可继续通过顶部栏访问。")).toBeInTheDocument();
     expect(document.querySelector(".mobile-shell__empty-kicker")).toBeNull();
 
     await user.click(screen.getByRole("button", { name: "切换工作区" }));
 
     expect(screen.getByRole("complementary", { name: "工作区抽屉" })).toBeInTheDocument();
     expect(screen.getByRole("button", { name: "关闭工作区抽屉" })).toBeInTheDocument();
-    expect(screen.getByText("选择工作区")).toBeInTheDocument();
+    expect(screen.queryByText("选择工作区")).not.toBeInTheDocument();
     expect(screen.getByRole("button", { name: "新建工作区" })).toBeInTheDocument();
 
     await user.click(screen.getByRole("button", { name: "打开文件面板" }));
@@ -3395,9 +3396,9 @@ describe("MobileShell Phase 2 workspace", () => {
     expect(screen.queryByTestId("mobile-code-editor")).not.toBeInTheDocument();
   });
 
-  it("opens the terminal sheet from the dock", async () => {
+  it("opens the terminal sheet from the workspace topbar", async () => {
     const user = userEvent.setup();
-    renderMobileShell();
+    renderMobileShell({ initialEntry: "/workspace" });
 
     await user.click(screen.getByRole("button", { name: "Open Terminal sheet" }));
 
diff --git a/packages/web/src/shells/mobile-shell/index.tsx b/packages/web/src/shells/mobile-shell/index.tsx
index 4cef9d504..54ba92c91 100644
--- a/packages/web/src/shells/mobile-shell/index.tsx
+++ b/packages/web/src/shells/mobile-shell/index.tsx
@@ -10,7 +10,6 @@ import { MonitoringPage } from "../../features/monitoring";
 import { MoreFeaturesPage } from "../../features/more";
 import { NotFoundPage } from "../../features/not-found";
 import { ToastContainer } from "../../features/notifications";
-import { SettingsPage } from "../../features/settings";
 import { WelcomePage } from "../../features/welcome";
 import { WorkAnalyticsPage } from "../../features/work-analysis";
 import { WorkspaceMobileView } from "../../features/workspace/views/mobile/workspace-mobile-view";
@@ -36,7 +35,6 @@ export function MobileShell() {
   const location = useLocation();
   const authUnknown = authEnabled === null;
   const shouldBypassAuthLoading =
-    location.pathname.startsWith("/settings") ||
     location.pathname.startsWith("/analytics") ||
     location.pathname.startsWith("/monitoring") ||
     location.pathname.startsWith("/diagnostics") ||
@@ -80,7 +78,6 @@ export function MobileShell() {
                 </WorkspaceRouteGate>
               }
             />
-            <Route path="/settings" element={<SettingsPage />} />
             <Route path="*" element={<NotFoundPage />} />
           </Routes>
         )}
diff --git a/packages/web/src/styles/base.theme.test.ts b/packages/web/src/styles/base.theme.test.ts
index 82f0062df..3f5e361c0 100644
--- a/packages/web/src/styles/base.theme.test.ts
+++ b/packages/web/src/styles/base.theme.test.ts
@@ -29,6 +29,18 @@ function getRuleBlock(selector: string) {
   return blocks.at(-1) ?? "";
 }
 
+function getCustomProperty(block: string, name: string): string | null {
+  const matcher = new RegExp(`${name}:\\s*([^;]+);`, "g");
+  let value: string | null = null;
+  let match: RegExpExecArray | null = null;
+
+  while ((match = matcher.exec(block)) !== null) {
+    value = match[1]?.trim() ?? null;
+  }
+
+  return value;
+}
+
 describe("base.css theme-sensitive shells", () => {
   it("keeps the app loading shell on semantic material tokens", () => {
     const shell = getRuleBlock(".app-loading-shell");
@@ -175,6 +187,11 @@ describe("base.css desktop typography foundation", () => {
     expect(tokensStylesheet).toContain("--z-popover:");
     expect(tokensStylesheet).toContain("--z-tooltip:");
     expect(tokensStylesheet).toContain("--z-toast:");
+
+    expect(getCustomProperty(tokensStylesheet, "--z-modal-backdrop")).toBe("380");
+    expect(getCustomProperty(tokensStylesheet, "--z-modal")).toBe("390");
+    expect(getCustomProperty(tokensStylesheet, "--z-workbench-backdrop")).toBe("360");
+    expect(getCustomProperty(tokensStylesheet, "--z-workbench")).toBe("370");
   });
 
   it("maps base text elements onto semantic typography tokens", () => {
diff --git a/packages/web/src/styles/components.css b/packages/web/src/styles/components.css
index c5215daed..a369d0ce8 100644
--- a/packages/web/src/styles/components.css
+++ b/packages/web/src/styles/components.css
@@ -671,6 +671,71 @@
   color: var(--text-tertiary);
 }
 
+.mobile-agent-provider-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  border: 1px solid transparent;
+  border-radius: var(--radius-md);
+  flex-shrink: 0;
+}
+
+.mobile-agent-provider-icon__label {
+  font-family: var(--font-mono);
+  font-size: var(--type-body-6-size);
+  line-height: 1;
+  font-weight: var(--type-heading-5-weight);
+  letter-spacing: 0.02em;
+}
+
+.mobile-agent-provider-icon--claude {
+  color: var(--icon-accent);
+  background: var(--icon-surface-accent);
+}
+
+.mobile-agent-provider-icon--codex {
+  color: var(--icon-secondary);
+  background: var(--icon-surface-subtle);
+  border-color: var(--component-mix-border-default-64pct-transparent);
+}
+
+.mobile-agent-provider-icon--gemini {
+  color: var(--icon-info);
+  background: var(--icon-surface-info);
+}
+
+.mobile-agent-provider-icon--cursor {
+  color: var(--icon-success);
+  background: var(--icon-surface-success);
+}
+
+.mobile-agent-provider-icon--opencode {
+  color: var(--icon-warning);
+  background: var(--icon-surface-warning);
+}
+
+.mobile-agent-provider-icon--tone-accent {
+  color: var(--icon-accent);
+  background: var(--icon-surface-accent);
+}
+
+.mobile-agent-provider-icon--tone-info {
+  color: var(--icon-info);
+  background: var(--icon-surface-info);
+}
+
+.mobile-agent-provider-icon--tone-success {
+  color: var(--icon-success);
+  background: var(--icon-surface-success);
+}
+
+.mobile-agent-provider-icon--tone-warning {
+  color: var(--icon-warning);
+  background: var(--icon-surface-warning);
+}
+
 .mobile-select-sheet--command
   .mobile-select-sheet__list
   > [data-selected="true"]
@@ -739,6 +804,21 @@
   background: transparent;
 }
 
+.mobile-agent-sheet--providers.mobile-select-sheet--command .mobile-select-sheet__item {
+  min-height: 38px;
+  padding: 8px 16px;
+}
+
+.mobile-agent-sheet--providers.mobile-select-sheet--command
+  .mobile-select-sheet__item-row
+  > .mobile-select-sheet__item {
+  min-height: 38px;
+}
+
+.mobile-agent-sheet--providers.mobile-select-sheet--command .mobile-select-sheet__item-copy {
+  gap: 1px;
+}
+
 .mobile-select-sheet--command .mobile-select-sheet__item-side-action--danger {
   color: var(--component-mix-status-danger-fg-76pct-text-primary);
 }
@@ -833,25 +913,25 @@
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  font-size: var(--type-heading-5-size);
-  line-height: var(--type-heading-5-line-height);
-  font-weight: var(--type-heading-5-weight);
+  font-size: var(--type-heading-6-size);
+  line-height: var(--type-heading-6-line-height);
+  font-weight: var(--type-heading-6-weight);
   color: var(--text-primary);
   text-align: left;
 }
 
 .page-header--primary .page-header__title {
-  font-size: var(--type-heading-4-size);
-  line-height: var(--type-heading-4-line-height);
-  font-weight: var(--type-heading-4-weight);
-}
-
-.page-header--secondary .page-header__title {
   font-size: var(--type-heading-5-size);
   line-height: var(--type-heading-5-line-height);
   font-weight: var(--type-heading-5-weight);
 }
 
+.page-header--secondary .page-header__title {
+  font-size: var(--type-heading-6-size);
+  line-height: var(--type-heading-6-line-height);
+  font-weight: var(--type-heading-6-weight);
+}
+
 .page-header__back {
   display: inline-flex;
   align-items: center;
@@ -2247,6 +2327,24 @@
   text-align: right;
 }
 
+.terminal-profile-settings {
+  scroll-margin-top: var(--sp-6);
+}
+
+.terminal-profile-settings__default-select {
+  width: min(280px, 100%);
+}
+
+.terminal-profile-settings__default-select .mobile-select-trigger {
+  width: 100%;
+}
+
+.terminal-profile-settings__default-select .mobile-select-trigger__value {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 .settings-appearance-file-input {
   position: absolute;
   width: 1px;
@@ -2451,17 +2549,26 @@
 }
 
 .more-features-page__frame--compact-top {
-  padding-top: var(--sp-2);
+  padding-top: 0;
 }
 
 .more-features-page__frame--tight-bottom {
   padding-bottom: 0;
 }
 
+.more-features-page__frame--tight-top {
+  padding-top: 0;
+}
+
 .more-features-page__header {
   min-width: 0;
 }
 
+.more-features-page__divider {
+  border-bottom: 1px solid var(--border-default);
+  margin-bottom: var(--sp-2);
+}
+
 .more-features-page__copy,
 .more-features-content__copy {
   display: grid;
@@ -2523,7 +2630,6 @@
   display: grid;
   align-content: start;
   gap: var(--gap-compact);
-  min-width: 144px;
   padding: 0 0 var(--sp-2);
   border: none;
   border-bottom: 2px solid transparent;
@@ -2676,6 +2782,11 @@
   gap: var(--sp-2);
 }
 
+.more-features-mobile-detail__header {
+  padding: 0 calc(var(--mobile-safe-right) + var(--sp-4)) 0
+    calc(var(--mobile-safe-left) + var(--sp-4));
+}
+
 .more-features-page--mobile {
   display: flex;
   flex-direction: column;
@@ -2685,11 +2796,13 @@
 }
 
 .more-features-mobile-list {
-  display: grid;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
   flex: 1;
   min-height: 0;
   gap: 0;
-  padding: var(--sp-3) 0 calc(var(--sp-6) + var(--mobile-safe-bottom));
+  padding: 0 0 calc(var(--sp-6) + var(--mobile-safe-bottom));
   overflow-y: auto;
 }
 
@@ -2697,9 +2810,9 @@
   display: grid;
   gap: var(--gap-hairline);
   width: 100%;
-  padding: calc(var(--sp-4) - var(--gap-compact)) var(--sp-4);
+  padding: var(--sp-2) var(--sp-4);
   border: none;
-  border-top: 1px solid var(--border-default);
+  border-bottom: 1px solid var(--border-default);
   background: transparent;
   text-align: left;
 }
@@ -2821,23 +2934,6 @@
   font-size: var(--text-sm);
 }
 
-.terminal-selector-dropdown {
-  display: none;
-  position: absolute;
-  top: 100%;
-  right: 0;
-  min-width: 200px;
-  background: var(--surface-panel);
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-md);
-  box-shadow: var(--shadow-lg);
-  z-index: var(--z-dropdown);
-}
-
-.terminal-selector:hover .terminal-selector-dropdown {
-  display: block;
-}
-
 .terminal-selector-item {
   display: flex;
   align-items: center;
@@ -3213,6 +3309,10 @@
   text-align: center;
 }
 
+.xterm-replay-overlay {
+  z-index: var(--z-inline);
+}
+
 .xterm-replay-overlay--degraded .xterm-replay-overlay__card {
   border-color: var(--component-mix-border-default-68pct-status-warning-fg-32pct);
 }
@@ -3434,7 +3534,7 @@ body.focus-mode-active .split-divider-h {
   align-items: center;
   justify-content: center;
   position: relative;
-  z-index: var(--z-inline-raised);
+  z-index: var(--z-inline);
 }
 
 .split-divider-v:hover {
@@ -3449,7 +3549,7 @@ body.focus-mode-active .split-divider-h {
   cursor: row-resize;
   flex-shrink: 0;
   position: relative;
-  z-index: var(--z-inline-raised);
+  z-index: var(--z-inline);
 }
 
 .split-divider-h:hover {
@@ -4717,15 +4817,15 @@ body.is-dragging-pane {
 }
 
 .pane-layout-divider {
-  background: var(--border-default);
+  background: transparent;
   transition: background var(--duration-fast) var(--ease-out);
   flex-shrink: 0;
   position: relative;
-  z-index: var(--z-inline-raised);
+  z-index: var(--z-inline);
 }
 
 .pane-layout-divider:hover {
-  background: var(--border-focus);
+  background: transparent;
 }
 
 .pane-layout-horizontal-divider {
@@ -4734,6 +4834,7 @@ body.is-dragging-pane {
   margin-left: -5px;
   margin-right: -5px;
   justify-self: center;
+  background: transparent;
 }
 
 .pane-layout-vertical-divider {
@@ -4743,6 +4844,7 @@ body.is-dragging-pane {
   margin-top: -5px;
   margin-bottom: -5px;
   align-self: center;
+  background: transparent;
 }
 
 /* ========== Draft Launcher ========== */
@@ -7987,20 +8089,77 @@ body.is-dragging-pane {
   margin-bottom: var(--sp-4);
 }
 
-.launch-section-title {
+.launch-section-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--sp-3);
   margin-bottom: var(--sp-2);
+}
+
+.launch-section-title {
   font-size: var(--type-body-5-size);
   line-height: var(--type-body-5-line-height);
   font-weight: var(--font-medium);
   color: var(--text-secondary);
 }
 
+.launch-section-action {
+  border: none;
+  background: transparent;
+  color: var(--state-info-text);
+  font-size: var(--type-body-6-size);
+  line-height: var(--type-body-6-line-height);
+  font-weight: var(--type-body-6-weight);
+  cursor: pointer;
+  transition:
+    color var(--duration-fast) var(--ease-out),
+    opacity var(--duration-fast) var(--ease-out);
+}
+
+.launch-section-action:hover {
+  color: var(--text-primary);
+}
+
+.launch-section-action:focus-visible {
+  outline: none;
+  border-radius: var(--radius-sm);
+  box-shadow: 0 0 0 var(--state-focus-ring-width) var(--state-focus-ring-color);
+}
+
+.launch-section-action:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
 .launch-recent-list {
   display: flex;
   flex-direction: column;
   gap: var(--sp-2);
 }
 
+.launch-recent-item {
+  position: relative;
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-md);
+  background: var(--surface-panel);
+  transition:
+    background var(--duration-fast) var(--ease-out),
+    border-color var(--duration-fast) var(--ease-out),
+    box-shadow var(--duration-fast) var(--ease-out),
+    opacity var(--duration-fast) var(--ease-out);
+}
+
+.launch-recent-item:hover {
+  background: var(--surface-hover);
+  border-color: var(--state-info-border);
+  box-shadow: var(--shadow-sm);
+}
+
+.launch-recent-item:focus-within {
+  box-shadow: 0 0 0 var(--state-focus-ring-width) var(--state-focus-ring-color);
+}
+
 .launch-recent-row {
   display: flex;
   width: 100%;
@@ -8009,26 +8168,25 @@ body.is-dragging-pane {
   align-items: flex-start;
   gap: var(--sp-1);
   padding: var(--sp-3);
-  border: 1px solid var(--border-default);
-  border-radius: var(--radius-md);
-  background: var(--surface-panel);
+  padding-right: calc(var(--sp-3) + 28px + var(--sp-2));
+  border: none;
+  border-radius: inherit;
+  background: transparent;
   text-align: left;
   cursor: pointer;
   transition:
     background var(--duration-fast) var(--ease-out),
-    border-color var(--duration-fast) var(--ease-out),
     box-shadow var(--duration-fast) var(--ease-out),
     opacity var(--duration-fast) var(--ease-out);
 }
 
 .launch-recent-row:hover {
-  background: var(--surface-hover);
-  border-color: var(--state-info-border);
+  background: transparent;
 }
 
 .launch-recent-row:focus-visible {
   outline: none;
-  box-shadow: 0 0 0 var(--state-focus-ring-width) var(--state-focus-ring-color);
+  box-shadow: none;
 }
 
 .launch-recent-row:disabled {
@@ -8059,7 +8217,7 @@ body.is-dragging-pane {
   font-size: var(--type-body-6-size);
   line-height: var(--type-body-6-line-height);
   font-weight: var(--type-body-6-weight);
-  color: var(--text-secondary);
+  color: var(--text-tertiary);
   white-space: nowrap;
 }
 
@@ -8073,6 +8231,32 @@ body.is-dragging-pane {
   word-break: break-all;
 }
 
+.launch-recent-remove {
+  position: absolute;
+  top: var(--sp-2);
+  right: var(--sp-2);
+  width: 28px;
+  height: 28px;
+  border-radius: var(--radius-full);
+  color: var(--text-tertiary);
+  opacity: 0.56;
+}
+
+.launch-recent-item:hover .launch-recent-remove,
+.launch-recent-item:focus-within .launch-recent-remove {
+  opacity: 1;
+}
+
+.launch-recent-remove:hover {
+  background: var(--surface-elevated);
+  color: var(--text-primary);
+}
+
+.launch-recent-remove:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 var(--state-focus-ring-width) var(--state-focus-ring-color);
+}
+
 .launch-intro {
   margin-bottom: var(--sp-4);
 }
@@ -9140,12 +9324,60 @@ textarea.input {
   justify-content: center;
   min-width: 1.75rem;
   min-height: 1.75rem;
+  border: 1px solid transparent;
+  border-radius: var(--radius-md);
   font-family: var(--font-mono);
   font-size: var(--type-body-6-size);
   line-height: 1;
   font-weight: var(--type-heading-5-weight);
 }
 
+.agent-provider-card-monogram--claude {
+  color: var(--icon-accent);
+  background: var(--icon-surface-accent);
+}
+
+.agent-provider-card-monogram--codex {
+  color: var(--icon-secondary);
+  background: var(--icon-surface-subtle);
+  border-color: var(--component-mix-border-default-64pct-transparent);
+}
+
+.agent-provider-card-monogram--gemini {
+  color: var(--icon-info);
+  background: var(--icon-surface-info);
+}
+
+.agent-provider-card-monogram--cursor {
+  color: var(--icon-success);
+  background: var(--icon-surface-success);
+}
+
+.agent-provider-card-monogram--opencode {
+  color: var(--icon-warning);
+  background: var(--icon-surface-warning);
+}
+
+.agent-provider-card-monogram--tone-accent {
+  color: var(--icon-accent);
+  background: var(--icon-surface-accent);
+}
+
+.agent-provider-card-monogram--tone-info {
+  color: var(--icon-info);
+  background: var(--icon-surface-info);
+}
+
+.agent-provider-card-monogram--tone-success {
+  color: var(--icon-success);
+  background: var(--icon-surface-success);
+}
+
+.agent-provider-card-monogram--tone-warning {
+  color: var(--icon-warning);
+  background: var(--icon-surface-warning);
+}
+
 .agent-provider-card-body {
   display: grid;
   grid-template-columns: minmax(0, 1fr) auto;
@@ -10042,9 +10274,78 @@ textarea.input {
   font-variant-numeric: tabular-nums;
 }
 
-.document-preview {
-  display: flex;
-  min-height: 100%;
+.document-preview.canvas-surface {
+  height: 100%;
+  min-height: 0;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.canvas-surface {
+  flex-direction: column;
+}
+
+.canvas-surface__content {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+.canvas-surface__viewport {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+.canvas-surface__scaled-content {
+  transform-origin: top left;
+}
+
+.canvas-surface__zoom-bar {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--gap-compact);
+  flex-shrink: 0;
+  padding: var(--sp-2) var(--sp-3);
+  border-top: 1px solid var(--border-subtle);
+  background: var(--surface-panel-bg);
+}
+
+.canvas-surface__zoom-btn {
+  width: 26px;
+  height: 26px;
+}
+
+.canvas-surface__zoom-level {
+  min-width: 44px;
+  color: var(--text-secondary);
+  text-align: center;
+  font-size: var(--type-body-6-size);
+  line-height: var(--type-body-6-line-height);
+  font-variant-numeric: tabular-nums;
+}
+
+.canvas-surface__content :where(h1, h2, h3, h4, h5, h6, p, ul, ol, table) {
+  margin: 0;
+  font: inherit;
+  color: inherit;
+}
+
+.architecture-canvas-mermaid {
+  overflow-x: auto;
+  padding: var(--sp-1) 0;
+}
+
+.architecture-canvas-mermaid svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+.document-preview {
+  display: flex;
+  min-height: 100%;
   background: var(--surface-page);
 }
 
@@ -10697,16 +10998,11 @@ body.is-resizing-floating-editor--nesw * {
 
 .pane-layout-divider {
   position: relative;
-  background: linear-gradient(180deg, transparent, var(--state-info-bg), transparent);
+  background: transparent;
 }
 
 .pane-layout-vertical-divider {
-  background: linear-gradient(
-    180deg,
-    transparent,
-    var(--component-mix-status-info-fg-24pct-transparent),
-    transparent
-  );
+  background: transparent;
 }
 
 .pane-layout-divider::after {
@@ -10714,7 +11010,7 @@ body.is-resizing-floating-editor--nesw * {
   position: absolute;
   pointer-events: none;
   border-radius: var(--radius-pill);
-  background: var(--component-mix-border-default-62pct-transparent);
+  background: transparent;
 }
 
 .pane-layout-horizontal-divider::after {
@@ -10730,16 +11026,16 @@ body.is-resizing-floating-editor--nesw * {
   right: 0;
   top: 50%;
   height: 1px;
-  background: var(--component-mix-border-default-78pct-status-info-fg-22pct);
+  background: transparent;
   transform: translateY(-50%);
 }
 
 .pane-layout-divider:hover::after {
-  background: var(--component-mix-border-focus-58pct-transparent);
+  background: transparent;
 }
 
 .pane-layout-divider:hover {
-  background: var(--component-mix-border-focus-44pct-transparent-56pct);
+  background: transparent;
 }
 
 .session-card {
@@ -12067,6 +12363,13 @@ body.is-dragging-pane .session-action-btn-drag {
   font-size: 11px;
 }
 
+.terminal-selector-btn--static {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  cursor: default;
+}
+
 .bottom-terminal-content {
   flex-direction: row;
   align-items: stretch;
@@ -12233,18 +12536,29 @@ body.is-dragging-pane .session-action-btn-drag {
   gap: var(--gap-tight);
   justify-content: flex-start;
   padding: 0 var(--control-height-md) 0 var(--inset-control-inline);
-  border-radius: 7px;
+  border: 1px solid transparent;
+  border-bottom: 1px solid transparent;
+  border-radius: 4px 4px 0 0;
   overflow: hidden;
   isolation: isolate;
+  background: transparent;
+  color: var(--text-secondary);
+  transition:
+    background-color var(--duration-fast) var(--ease-out),
+    border-color var(--duration-fast) var(--ease-out),
+    color var(--duration-fast) var(--ease-out);
+}
+
+.topbar-tab:hover {
+  color: var(--text-primary);
+  background: var(--component-mix-surface-panel-66pct-transparent);
 }
 
 .topbar-tab.active {
-  background: linear-gradient(
-    180deg,
-    var(--component-rgba-43-60-75-0-94),
-    var(--component-rgba-30-44-56-0-98)
-  );
-  border-color: var(--component-mix-border-subtle-72pct-status-info-fg-28pct);
+  background: var(--component-mix-surface-active-94pct-surface-panel-6pct);
+  border-color: var(--component-mix-border-default-84pct-transparent);
+  border-bottom-color: var(--status-info-fg);
+  color: var(--text-primary);
 }
 
 .topbar-tab-content {
@@ -12329,22 +12643,30 @@ body.is-dragging-pane .session-action-btn-drag {
 }
 
 .topbar-close {
-  width: 18px;
-  height: 18px;
+  width: 16px;
+  height: 16px;
   position: absolute;
   top: 50%;
-  right: 6px;
+  right: 5px;
   margin-left: 0;
   border-radius: 4px;
   opacity: 0;
   pointer-events: none;
   transform: translateY(-50%);
   z-index: var(--z-inline);
+  color: var(--component-mix-text-tertiary-82pct-status-info-fg-18pct);
+  background: transparent;
+  transition:
+    opacity var(--duration-fast) var(--ease-out),
+    color var(--duration-fast) var(--ease-out),
+    background-color var(--duration-fast) var(--ease-out);
 }
 
 .topbar-close:hover:not(:disabled),
 .topbar-close:active:not(:disabled) {
   transform: translateY(-50%);
+  color: var(--text-primary);
+  background: var(--component-mix-status-info-fg-8pct-transparent);
 }
 
 .topbar-tab-shell.active .topbar-close,
@@ -12629,13 +12951,10 @@ body.is-dragging-pane .session-action-btn-drag {
 }
 
 .topbar-tab.active {
-  background: linear-gradient(
-    180deg,
-    var(--component-mix-surface-active-86pct-white-14pct),
-    var(--component-mix-surface-active-94pct-surface-panel-6pct)
-  );
-  border-color: var(--component-mix-border-subtle-72pct-status-info-fg-28pct);
-  box-shadow: inset 0 1px 0 var(--component-mix-white-22pct-transparent);
+  background: var(--component-mix-surface-active-94pct-surface-panel-6pct);
+  border-color: var(--component-mix-border-default-84pct-transparent);
+  border-bottom-color: var(--status-info-fg);
+  box-shadow: none;
 }
 
 .connection-status {
@@ -12945,8 +13264,8 @@ body.is-dragging-pane .session-action-btn-drag {
 
 .config-card--fill-height {
   display: flex;
-  flex: 1;
-  min-height: 0;
+  flex: 1 0 auto;
+  min-height: 320px;
   flex-direction: column;
 }
 
@@ -13047,7 +13366,7 @@ body.is-dragging-pane .session-action-btn-drag {
 }
 
 .config-card-body--fill-height > .monaco-host {
-  flex: 1;
+  flex: 1 1 auto;
   min-height: 0;
 }
 
@@ -13056,15 +13375,22 @@ body.is-dragging-pane .session-action-btn-drag {
 }
 
 /* Monaco Editor */
-.config-card-body .monaco-host {
+.config-card-editor-slot {
+  display: flex;
+  flex-direction: column;
   min-height: 200px;
   max-height: 600px;
   border-bottom: 1px solid var(--border-default);
 }
 
-.config-card-body--fill-height .monaco-host {
-  flex: 1;
+.config-card-editor-slot > .monaco-host {
+  flex: 1 1 auto;
   min-height: 0;
+}
+
+.config-card-editor-slot--fill-height {
+  flex: 1 0 192px;
+  min-height: 192px;
   max-height: none;
 }
 
@@ -13353,9 +13679,9 @@ body.is-dragging-pane .session-action-btn-drag {
     display: grid;
     grid-template-columns: minmax(0, 1fr) auto;
     align-items: center;
-    gap: var(--sp-3);
-    padding: calc(var(--mobile-safe-top) + var(--sp-1)) calc(var(--mobile-safe-right) + var(--sp-4))
-      var(--sp-1) calc(var(--mobile-safe-left) + var(--sp-4));
+    gap: var(--sp-2);
+    padding: calc(var(--mobile-safe-top) + var(--sp-1)) calc(var(--mobile-safe-right) + var(--sp-3))
+      var(--sp-1) calc(var(--mobile-safe-left) + var(--sp-3));
     background: var(--material-shell-topbar);
     border-bottom: 1px solid var(--component-mix-border-default-84pct-transparent);
     backdrop-filter: var(--material-backdrop-filter);
@@ -13374,12 +13700,13 @@ body.is-dragging-pane .session-action-btn-drag {
   .mobile-topbar__workspace-button {
     display: flex;
     align-items: center;
+    justify-content: flex-start;
     gap: var(--sp-2);
     min-width: 0;
     width: 100%;
     min-height: 36px;
     height: 36px;
-    padding: 0 var(--sp-3);
+    padding: 0 var(--sp-2) 0 var(--sp-1);
     border: none;
     border-bottom: none;
     border-radius: 0;
@@ -13388,14 +13715,19 @@ body.is-dragging-pane .session-action-btn-drag {
   }
 
   .mobile-topbar__workspace-leading {
+    display: inline-flex;
+    align-items: center;
+    align-self: center;
     flex-shrink: 0;
     color: var(--component-mix-text-secondary-88pct-status-info-fg-12pct);
   }
 
   .mobile-topbar__workspace-name {
-    display: block;
-    flex: 1 1 auto;
+    display: flex;
+    align-items: center;
+    align-self: center;
     min-width: 0;
+    max-width: 100%;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
@@ -13486,7 +13818,8 @@ body.is-dragging-pane .session-action-btn-drag {
     position: relative;
     display: inline-flex;
     align-items: center;
-    gap: var(--sp-2);
+    flex-shrink: 0;
+    gap: 4px;
   }
 
   .mobile-shell__recovery-strip {
@@ -13528,8 +13861,8 @@ body.is-dragging-pane .session-action-btn-drag {
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    width: 36px;
-    min-width: 36px;
+    width: 30px;
+    min-width: 30px;
     min-height: 36px;
     height: 36px;
     padding: 0;
@@ -13545,6 +13878,10 @@ body.is-dragging-pane .session-action-btn-drag {
       box-shadow var(--mobile-shell-motion-surface-duration) var(--ease-out);
   }
 
+  .mobile-topbar__icon-button .themed-icon {
+    color: currentColor;
+  }
+
   .mobile-inline-sheet {
     position: absolute;
     top: calc(100% + var(--sp-2));
@@ -14222,9 +14559,9 @@ body.is-dragging-pane .session-action-btn-drag {
   }
 
   .mobile-page-header .page-header__title {
-    font-size: var(--type-heading-5-size);
-    line-height: var(--type-heading-5-line-height);
-    font-weight: var(--type-heading-5-weight);
+    font-size: var(--type-heading-6-size);
+    line-height: var(--type-heading-6-line-height);
+    font-weight: var(--type-heading-6-weight);
     letter-spacing: 0.01em;
   }
 
@@ -14311,6 +14648,18 @@ body.is-dragging-pane .session-action-btn-drag {
     margin-bottom: var(--sp-3);
   }
 
+  .mobile-launch-sheet .launch-section-header {
+    align-items: flex-start;
+  }
+
+  .mobile-launch-sheet .launch-recent-item {
+    min-height: 72px;
+  }
+
+  .mobile-launch-sheet .launch-recent-remove {
+    min-width: 40px;
+  }
+
   .mobile-launch-sheet .folder-picker {
     display: flex;
     flex: 1;
@@ -15124,11 +15473,7 @@ body.is-dragging-pane .session-action-btn-drag {
     padding: calc(var(--mobile-safe-top) + var(--sp-3)) calc(var(--mobile-safe-right) + var(--sp-3))
       calc(var(--sp-3) + var(--mobile-safe-bottom)) calc(var(--mobile-safe-left) + var(--sp-3));
     border-right: 1px solid var(--component-mix-border-default-82pct-transparent);
-    background: linear-gradient(
-      180deg,
-      var(--component-mix-surface-panel-96pct-transparent) 0%,
-      var(--component-mix-surface-page-94pct-surface-panel-6pct) 100%
-    );
+    background: var(--surface-page);
     box-shadow: none;
     transform: translateX(-12px);
     opacity: 0;
@@ -15139,8 +15484,8 @@ body.is-dragging-pane .session-action-btn-drag {
     display: flex;
     align-items: center;
     justify-content: space-between;
-    gap: var(--sp-3);
-    padding: 0 0 var(--sp-3);
+    gap: var(--sp-2);
+    padding: 0 0 var(--sp-2);
     border-bottom: 1px solid var(--component-mix-border-default-82pct-transparent);
   }
 
@@ -15149,53 +15494,43 @@ body.is-dragging-pane .session-action-btn-drag {
     min-width: 0;
     flex: 1;
     flex-direction: column;
-    gap: 4px;
+    gap: 0;
+    justify-content: center;
+    padding: 0;
   }
 
   .mobile-workspace-drawer__kicker {
     display: inline-flex;
     align-items: center;
-    gap: 6px;
-    font-family: var(--font-mono);
+    gap: 4px;
+    min-height: 28px;
+    font-family: var(--font-sans);
     font-size: var(--type-body-6-size);
     line-height: var(--type-body-6-line-height);
-    font-weight: var(--type-body-6-weight);
-    letter-spacing: 0.08em;
-    text-transform: uppercase;
-    color: var(--text-tertiary);
+    font-weight: var(--font-medium);
+    letter-spacing: 0.02em;
+    text-transform: none;
+    color: var(--text-secondary);
   }
 
   .mobile-workspace-drawer__kicker::before {
-    content: "";
-    width: 6px;
-    height: 6px;
-    border-radius: 999px;
-    background: var(--component-mix-status-info-fg-76pct-transparent);
-    box-shadow: 0 0 0 3px var(--component-mix-status-info-fg-14pct-transparent);
-  }
-
-  .mobile-workspace-drawer__title {
-    margin: 0;
-    font-size: var(--type-heading-4-size);
-    line-height: var(--type-heading-4-line-height);
-    font-weight: var(--type-heading-4-weight);
-    color: var(--text-primary);
+    display: none;
   }
 
   .mobile-workspace-drawer__dismiss {
-    width: 34px;
-    min-width: 34px;
-    height: 34px;
-    min-height: 34px;
-    border: 1px solid var(--component-mix-border-default-66pct-transparent);
-    border-radius: 999px;
-    background: var(--component-mix-surface-panel-78pct-surface-page);
-    color: var(--text-secondary);
+    width: 28px;
+    min-width: 28px;
+    height: 28px;
+    min-height: 28px;
+    border: none;
+    border-radius: var(--radius-md);
+    background: transparent;
+    color: var(--text-tertiary);
     box-shadow: none;
   }
 
   .mobile-workspace-drawer__dismiss:hover {
-    background: var(--component-mix-surface-hover-84pct-transparent);
+    background: var(--surface-hover);
     color: var(--text-primary);
   }
 
@@ -15203,32 +15538,28 @@ body.is-dragging-pane .session-action-btn-drag {
     display: flex;
     flex: 0 1 auto;
     flex-direction: column;
-    gap: var(--sp-2);
+    gap: 0;
     min-height: 0;
     max-height: 100%;
     overflow-y: auto;
-    margin: var(--sp-3) 0;
-    padding-right: 2px;
+    margin: 0;
+    padding-right: 0;
     border: none;
     background: transparent;
     box-shadow: none;
   }
 
   .mobile-workspace-drawer__item {
-    display: flex;
-    align-items: stretch;
-    gap: var(--sp-2);
-    padding: var(--sp-2);
-    border: 1px solid var(--component-mix-border-default-78pct-transparent);
-    border-radius: var(--radius-xl);
-    background: linear-gradient(
-      180deg,
-      var(--component-mix-surface-panel-88pct-transparent) 0%,
-      var(--component-mix-surface-page-92pct-surface-panel-8pct) 100%
-    );
-    box-shadow:
-      inset 0 1px 0 var(--component-mix-fg-white-5pct-transparent),
-      0 12px 30px var(--component-mix-surface-page-16pct-transparent);
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: flex-start;
+    gap: 0;
+    padding: 0;
+    border: none;
+    border-bottom: 1px solid var(--component-mix-border-default-72pct-transparent);
+    border-radius: 0;
+    background: transparent;
+    box-shadow: none;
     text-align: left;
     transition:
       background-color var(--mobile-shell-motion-surface-duration) var(--ease-out),
@@ -15239,29 +15570,18 @@ body.is-dragging-pane .session-action-btn-drag {
   }
 
   .mobile-workspace-drawer__item--active {
-    background:
-      linear-gradient(
-        180deg,
-        var(--component-mix-status-info-fg-12pct-surface-panel) 0%,
-        var(--component-mix-status-info-fg-10pct-surface-page) 100%
-      ),
-      var(--component-mix-surface-panel-92pct-surface-elevated);
-    box-shadow:
-      inset 0 1px 0 var(--component-mix-status-info-fg-12pct-transparent),
-      0 14px 32px var(--component-mix-status-info-fg-8pct-transparent);
-    border-color: var(--component-mix-status-info-fg-28pct-border-default);
+    background: transparent;
+    box-shadow: none;
   }
 
   .mobile-workspace-drawer__item-main {
     display: flex;
-    flex: 1;
     min-width: 0;
     flex-direction: column;
     align-items: flex-start;
-    justify-content: center;
-    gap: 3px;
-    padding: var(--sp-2);
-    padding-right: 0;
+    justify-content: flex-start;
+    gap: 1px;
+    padding: 6px 0 4px 0;
     text-align: left;
   }
 
@@ -15269,28 +15589,55 @@ body.is-dragging-pane .session-action-btn-drag {
     display: flex;
     width: 100%;
     min-width: 0;
+    min-height: 20px;
     align-items: center;
     gap: var(--sp-2);
   }
 
+  .mobile-workspace-drawer__item-actions {
+    display: inline-flex;
+    min-height: 20px;
+    align-items: center;
+    gap: 0;
+    align-self: flex-start;
+    padding-top: 6px;
+  }
+
+  .mobile-workspace-drawer__item-create,
   .mobile-workspace-drawer__item-close {
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    width: 32px;
-    min-width: 32px;
-    min-height: 32px;
-    margin: auto 0;
+    width: 20px;
+    min-width: 20px;
+    min-height: 20px;
+    margin: 0;
     align-self: auto;
-    border: 1px solid var(--component-mix-border-default-56pct-transparent);
-    border-radius: 999px;
-    color: var(--component-mix-status-danger-fg-82pct-text-primary);
-    background: var(--component-mix-surface-panel-76pct-transparent);
+    border: none;
+    border-radius: var(--radius-sm);
+    background: transparent;
     transition:
       background-color var(--mobile-shell-motion-surface-duration) var(--ease-out),
       color var(--mobile-shell-motion-surface-duration) var(--ease-out);
   }
 
+  .mobile-workspace-drawer__item-create {
+    color: var(--text-secondary);
+  }
+
+  .mobile-workspace-drawer__item-close {
+    color: var(--component-mix-status-danger-fg-82pct-text-primary);
+  }
+
+  .mobile-workspace-drawer__item-create .themed-icon {
+    color: currentColor;
+  }
+
+  .mobile-workspace-drawer__item-create:hover {
+    background: var(--component-mix-surface-hover-84pct-transparent);
+    color: var(--text-primary);
+  }
+
   .mobile-workspace-drawer__item-close:hover {
     background: var(--component-mix-status-danger-fg-8pct-transparent);
   }
@@ -15304,32 +15651,130 @@ body.is-dragging-pane .session-action-btn-drag {
     font-weight: var(--type-body-3-weight);
   }
 
-  .mobile-workspace-drawer__item-state {
-    display: inline-flex;
-    align-items: center;
-    gap: 4px;
-    padding: 1px 6px;
-    border: 1px solid var(--component-mix-status-info-fg-26pct-transparent);
-    border-radius: 999px;
-    background: var(--component-mix-status-info-fg-12pct-transparent);
-    color: var(--component-mix-status-info-fg-74pct-text-primary);
+  .mobile-workspace-drawer__item-path {
+    max-width: 100%;
+    overflow: hidden;
+    color: var(--text-tertiary);
+    font-family: var(--font-mono);
     font-size: var(--type-body-6-size);
     line-height: var(--type-body-6-line-height);
     font-weight: var(--type-body-6-weight);
-    letter-spacing: 0.08em;
+    text-overflow: ellipsis;
     white-space: nowrap;
   }
 
-  .mobile-workspace-drawer__item-path {
-    max-width: 100%;
-    overflow: hidden;
+  .mobile-workspace-drawer__item-children {
+    display: flex;
+    grid-column: 1 / -1;
+    flex-direction: column;
+    gap: 0;
+    padding: 4px 0 6px;
+    border-top: 1px solid var(--component-mix-border-default-62pct-transparent);
+  }
+
+  .mobile-workspace-drawer__child-session-row {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    gap: 0;
+    align-items: stretch;
+  }
+
+  .mobile-workspace-drawer__child-session-row + .mobile-workspace-drawer__child-session-row {
+    border-top: 1px solid var(--component-mix-border-default-62pct-transparent);
+  }
+
+  .mobile-workspace-drawer__child-empty {
+    display: flex;
+    width: 100%;
+    min-width: 0;
+    flex-direction: column;
+    align-items: flex-start;
+    justify-content: flex-start;
+    gap: 2px;
+    padding: 4px 0 4px 14px;
+    border: 0;
+    border-radius: 0;
+    background: transparent;
+    text-align: left;
+    color: var(--text-secondary);
+  }
+
+  .mobile-workspace-drawer__child-empty-title {
+    min-width: 0;
+    color: var(--text-secondary);
+    font-size: var(--type-body-6-size);
+    line-height: var(--type-body-6-line-height);
+    font-weight: var(--type-body-6-weight);
+  }
+
+  .mobile-workspace-drawer__child-empty-hint {
+    min-width: 0;
     color: var(--text-tertiary);
     font-family: var(--font-mono);
-    font-size: var(--type-body-5-size);
-    line-height: var(--type-body-5-line-height);
-    font-weight: var(--type-body-5-weight);
-    text-overflow: ellipsis;
-    white-space: nowrap;
+    font-size: var(--type-body-6-size);
+    line-height: var(--type-body-6-line-height);
+    font-weight: var(--type-body-6-weight);
+  }
+
+  .mobile-workspace-drawer__child-session {
+    display: flex;
+    width: 100%;
+    min-width: 0;
+    align-items: flex-start;
+    justify-content: flex-start;
+    gap: 2px;
+    padding: 1px 0 1px 14px;
+    border: 0;
+    border-radius: 0;
+    background: transparent;
+    text-align: left;
+  }
+
+  .mobile-workspace-drawer__child-session {
+    flex-direction: column;
+  }
+
+  .mobile-workspace-drawer__child-session-close {
+    align-self: center;
+    width: 20px;
+    min-width: 20px;
+    min-height: 20px;
+    margin: 0;
+    border: none;
+    border-radius: var(--radius-sm);
+    background: transparent;
+    color: var(--component-mix-status-danger-fg-82pct-text-primary);
+    box-shadow: none;
+  }
+
+  .mobile-workspace-drawer__child-session-close:hover {
+    background: var(--component-mix-status-danger-fg-8pct-transparent);
+  }
+
+  .mobile-workspace-drawer__child-session-row--active {
+    background: var(--state-selected-bg);
+  }
+
+  .mobile-workspace-drawer__child-session--active {
+    border-color: transparent;
+    background: transparent;
+  }
+
+  .mobile-workspace-drawer__child-session-label {
+    min-width: 0;
+    color: var(--text-primary);
+    font-size: var(--type-body-6-size);
+    line-height: var(--type-body-6-line-height);
+    font-weight: var(--type-body-6-weight);
+  }
+
+  .mobile-workspace-drawer__child-session-meta {
+    min-width: 0;
+    color: var(--text-tertiary);
+    font-family: var(--font-mono);
+    font-size: var(--type-body-6-size);
+    line-height: var(--type-body-6-line-height);
+    font-weight: var(--type-body-6-weight);
   }
 
   .mobile-workspace-drawer__footer {
@@ -15347,11 +15792,11 @@ body.is-dragging-pane .session-action-btn-drag {
     justify-content: flex-start;
     gap: var(--sp-2);
     width: 100%;
-    min-height: 46px;
-    padding: 0 var(--sp-3);
-    border: 1px solid var(--component-mix-border-default-78pct-transparent);
-    border-radius: var(--radius-md);
-    background: var(--component-mix-surface-panel-80pct-transparent);
+    min-height: 40px;
+    padding: 0;
+    border: 0;
+    border-radius: 0;
+    background: transparent;
     color: var(--text-primary);
     font-size: var(--type-body-3-size);
     line-height: var(--type-body-3-line-height);
@@ -15867,6 +16312,10 @@ body.is-dragging-pane .session-action-btn-drag {
     background: var(--component-mix-surface-panel-92pct-surface-page);
   }
 
+  .settings-mobile-root > .settings-mobile-group:first-child .settings-mobile-group__list {
+    border-top: none;
+  }
+
   .settings-mobile-item {
     display: flex;
     align-items: center;
@@ -15997,6 +16446,7 @@ body.is-dragging-pane .session-action-btn-drag {
     padding: calc(var(--mobile-safe-top) + var(--sp-1)) calc(var(--mobile-safe-right) + var(--sp-4))
       var(--sp-1) calc(var(--mobile-safe-left) + var(--sp-4));
     background: var(--settings-header-surface);
+    border-bottom: none;
     backdrop-filter: var(--material-backdrop-filter);
   }
 
@@ -16357,7 +16807,13 @@ body.is-dragging-pane .session-action-btn-drag {
 
 .workspace-activity-bar__button--active {
   border-color: var(--component-mix-border-default-72pct-transparent);
-  background: var(--component-mix-status-info-fg-14pct-transparent);
+  background: var(--state-selected-bg);
+  color: var(--text-primary);
+}
+
+.workspace-activity-bar__button--active:hover {
+  border-color: var(--component-mix-border-default-72pct-transparent);
+  background: var(--state-selected-bg);
   color: var(--text-primary);
 }
 
@@ -17057,7 +17513,8 @@ body.is-dragging-pane .session-action-btn-drag {
   min-width: 0;
   flex: 1 1 auto;
   align-items: center;
-  gap: 6px;
+  justify-content: space-between;
+  gap: 8px;
 }
 
 .memory-panel__item-meta-main > span {
@@ -17066,9 +17523,13 @@ body.is-dragging-pane .session-action-btn-drag {
   white-space: nowrap;
 }
 
-.memory-panel__item-meta-main > span:nth-child(2) {
+.memory-panel__item-badges {
+  display: inline-flex;
   min-width: 0;
   flex: 1 1 auto;
+  align-items: center;
+  gap: 6px;
+  overflow: hidden;
 }
 
 .memory-panel__item-meta-main > span:last-child {
@@ -17089,7 +17550,7 @@ body.is-dragging-pane .session-action-btn-drag {
 
 .memory-panel__badge {
   display: inline-flex;
-  max-width: 42%;
+  max-width: 100%;
   min-height: 20px;
   flex: 0 0 auto;
   align-items: center;
@@ -17106,29 +17567,53 @@ body.is-dragging-pane .session-action-btn-drag {
   font-weight: var(--type-body-6-weight);
 }
 
-.memory-panel__badge--feature {
+.memory-panel__badge--wiki {
   border-color: var(--component-mix-status-success-fg-60pct-border-default-40pct);
   color: var(--status-success-fg);
 }
 
+.memory-panel__badge--issue {
+  border-color: var(--component-mix-status-danger-fg-34pct-border-default);
+  color: var(--component-mix-status-danger-fg-84pct-text-primary);
+}
+
 .memory-panel__badge--todo {
   border-color: var(--component-mix-border-default-68pct-status-warning-fg-32pct);
   color: var(--status-warning-fg);
 }
 
-.memory-panel__badge--bugfix {
-  border-color: var(--component-mix-status-danger-fg-34pct-border-default);
-  color: var(--component-mix-status-danger-fg-84pct-text-primary);
+.memory-panel__badge--note {
+  border-color: var(--component-mix-border-default-84pct-transparent);
+  color: var(--text-tertiary);
 }
 
-.memory-panel__badge--project {
-  border-color: var(--component-mix-status-info-fg-42pct-border-default);
-  color: var(--status-info-fg);
+.memory-panel__badge--status {
+  background: var(--component-mix-surface-page-68pct-surface-panel-32pct);
+  color: var(--text-secondary);
 }
 
-.memory-panel__badge--note {
+.memory-panel__badge--status-not_started {
   border-color: var(--component-mix-border-default-84pct-transparent);
-  color: var(--text-tertiary);
+  background: var(--component-mix-surface-page-68pct-surface-panel-32pct);
+  color: var(--text-secondary);
+}
+
+.memory-panel__badge--status-in_progress {
+  border-color: var(--component-mix-status-info-fg-28pct-border-default);
+  background: var(--component-mix-status-info-fg-8pct-surface-panel);
+  color: var(--status-info-fg);
+}
+
+.memory-panel__badge--status-pending_verification {
+  border-color: var(--component-mix-border-default-68pct-status-warning-fg-32pct);
+  background: var(--component-mix-status-warning-fg-15pct-transparent);
+  color: var(--status-warning-fg);
+}
+
+.memory-panel__badge--status-completed {
+  border-color: var(--component-mix-status-success-fg-60pct-border-default-40pct);
+  background: var(--component-mix-status-success-fg-15pct-transparent);
+  color: var(--status-success-fg);
 }
 
 .memory-panel__empty {
@@ -18557,6 +19042,44 @@ body.is-dragging-pane .session-action-btn-drag {
   padding-top: 0;
 }
 
+.skills-panel__files-row {
+  display: flex;
+  min-width: 0;
+  align-items: center;
+  gap: var(--gap-compact);
+}
+
+.skills-panel__files-button {
+  display: inline-flex;
+  min-width: 0;
+  flex: 1 1 auto;
+  align-items: center;
+  gap: var(--gap-compact);
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: var(--text-secondary);
+  font-size: var(--type-body-6-size);
+  line-height: var(--type-body-6-line-height);
+  text-align: left;
+  cursor: pointer;
+}
+
+.skills-panel__files-button:hover {
+  color: var(--text-primary);
+}
+
+.skills-panel__files-actions {
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: var(--gap-hairline);
+}
+
+.skills-panel__files-children {
+  margin-left: var(--sp-3);
+}
+
 @media (max-width: 960px) {
   .workspace-agent-instructions__status {
     gap: var(--gap-tight);
@@ -18917,6 +19440,18 @@ body.is-dragging-pane .session-action-btn-drag {
   color: var(--text-primary);
 }
 
+.git-panel-section-action-icon {
+  width: 24px;
+  height: 24px;
+  border-color: var(--component-mix-border-default-84pct-transparent);
+  border-radius: var(--radius-md);
+}
+
+.git-panel-section-action-icon:hover:not(:disabled):not([aria-disabled="true"]) {
+  border-color: var(--component-mix-border-default-72pct-transparent);
+  background: var(--surface-hover);
+}
+
 .git-panel-section-actions {
   display: inline-flex;
   align-items: center;
@@ -20031,6 +20566,23 @@ body.is-dragging-pane .session-action-btn-drag {
   color: var(--text-primary);
 }
 
+.code-editor-tab--preview .code-editor-tab__name {
+  display: inline-block;
+  max-width: 100%;
+  font-style: oblique 12deg;
+  transform: skewX(-8deg);
+  transform-origin: left center;
+}
+
+.code-editor-tab-item--preview:not(.code-editor-tab-item--active) {
+  color: var(--text-tertiary);
+}
+
+.code-editor-tab-item--preview:hover,
+.code-editor-tab-item--preview.code-editor-tab-item--active {
+  color: var(--text-primary);
+}
+
 .code-editor-tab__icon {
   display: inline-flex;
   align-items: center;
@@ -20481,7 +21033,7 @@ body.is-dragging-pane .session-action-btn-drag {
 
 .workspace-activity-bar__button--active {
   border-color: var(--component-mix-border-default-72pct-transparent);
-  background: var(--component-mix-status-info-fg-14pct-transparent);
+  background: var(--state-selected-bg);
   color: var(--text-primary);
 }
 
@@ -20494,6 +21046,10 @@ body.is-dragging-pane .session-action-btn-drag {
   line-height: 1;
 }
 
+.workspace-activity-bar__glyph > .themed-icon {
+  color: currentColor;
+}
+
 .workspace-sidebar-panel__content > .workspace-sidebar-view > .workspace-sidebar-panel__body {
   overflow-y: auto;
 }
@@ -21221,8 +21777,7 @@ body.is-dragging-pane .session-action-btn-drag {
   gap: var(--sp-2);
 }
 
-.git-panel-section-actions .git-panel-section-link:not(:last-child),
-.git-panel-section-changes .git-panel-section-actions .git-panel-section-link:not(:first-child) {
+.git-panel-section-actions .git-panel-section-link:not(:last-child) {
   display: none;
 }
 
@@ -21391,6 +21946,11 @@ body.is-dragging-pane .session-action-btn-drag {
   min-height: 0;
 }
 
+.mobile-sheet--files .mobile-explorer-panel {
+  gap: 16px;
+  overflow: hidden;
+}
+
 .mobile-sheet--files .workspace-sidebar-panel__body--stacked,
 .mobile-sheet--files .workspace-search-panel .workspace-sidebar-panel__body--stacked,
 .mobile-sheet--files .git-panel-scroll {
@@ -21398,11 +21958,17 @@ body.is-dragging-pane .session-action-btn-drag {
   grid-template-rows: none;
   gap: 16px;
   padding: 0;
-  overflow: visible;
 }
 
 .mobile-sheet--files .workspace-sidebar-panel__body--stacked {
   align-content: start;
+  min-height: 0;
+  grid-template-rows: auto minmax(0, 1fr);
+}
+
+.mobile-sheet--files .workspace-search-panel .workspace-sidebar-panel__body--stacked {
+  min-height: 0;
+  grid-template-rows: auto minmax(0, 1fr);
 }
 
 .mobile-sheet--files .workspace-sidebar-section,
@@ -21417,7 +21983,8 @@ body.is-dragging-pane .session-action-btn-drag {
 }
 
 .mobile-sheet--files .workspace-sidebar-section--fill {
-  flex: 0 0 auto;
+  flex: 1 1 auto;
+  min-height: 0;
   padding-bottom: 0;
 }
 
@@ -21488,6 +22055,7 @@ body.is-dragging-pane .session-action-btn-drag {
 }
 
 .mobile-sheet--files .workspace-quick-jump {
+  flex: 0 0 auto;
   padding-bottom: 0;
 }
 
@@ -21521,6 +22089,11 @@ body.is-dragging-pane .session-action-btn-drag {
   padding-top: 0;
 }
 
+.mobile-sheet--files .workspace-search-panel__results {
+  min-height: 0;
+  overflow-y: auto;
+}
+
 .mobile-sheet--files .workspace-quick-jump__item,
 .mobile-sheet--files .workspace-open-editors__item,
 .mobile-sheet--files .file-tree-shell--mobile .tree-item,
@@ -21604,6 +22177,8 @@ body.is-dragging-pane .session-action-btn-drag {
 
 .mobile-sheet--files .git-panel-scroll {
   grid-template-columns: minmax(0, 1fr);
+  min-height: 0;
+  overflow-y: auto;
 }
 
 .mobile-sheet--files .git-commit-block {
diff --git a/packages/web/src/styles/components.theme.test.ts b/packages/web/src/styles/components.theme.test.ts
index 57503d61f..85c142628 100644
--- a/packages/web/src/styles/components.theme.test.ts
+++ b/packages/web/src/styles/components.theme.test.ts
@@ -325,6 +325,18 @@ describe("components.css theme-sensitive surfaces", () => {
     ).toBe(true);
   });
 
+  it("does not hide the desktop terminal selector popover with legacy dropdown rules", () => {
+    const terminalSelectorDropdownRules = getRuleBlocksFrom(
+      stylesheet,
+      ".terminal-selector-dropdown"
+    );
+
+    expect(terminalSelectorDropdownRules.some((block) => block.includes("display: none"))).toBe(
+      false
+    );
+    expect(hasRuleBlock(".terminal-selector:hover .terminal-selector-dropdown")).toBe(false);
+  });
+
   it("routes semantic icon classes through icon tokens", () => {
     expect(getLastRuleBlock(".settings-mobile-item__icon")).toContain("var(--icon-secondary)");
     expect(getLastRuleBlock(".settings-nav-icon")).toContain("var(--icon-secondary)");
@@ -729,6 +741,14 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(getLastRuleBlockFrom(tabsStyles, ":global(.worktree-tab.active)")).toContain(
       "border-bottom: 2px solid var(--state-selected-border)"
     );
+    expect(getLastRuleBlock(".more-features-page__frame--compact-top")).toContain("padding-top: 0");
+    expect(getLastRuleBlock(".more-features-page__divider")).toContain(
+      "border-bottom: 1px solid var(--border-default)"
+    );
+    expect(getLastRuleBlock(".more-features-page__divider")).toContain(
+      "margin-bottom: var(--sp-2)"
+    );
+    expect(getLastRuleBlock(".more-features-tab")).not.toContain("min-width:");
     expect(getLastRuleBlockFrom(selectStylesheet, ".listbox")).toContain(
       "background: var(--surface-overlay-bg)"
     );
@@ -1214,6 +1234,12 @@ describe("components.css theme-sensitive surfaces", () => {
     const launchButtonFocus = getLastRuleBlock(".launch-start-btn:focus-visible");
     const launchButtonHover = getLastRuleBlock(".launch-start-btn:hover");
     const mobileLaunchButton = getLastRuleBlock(".launch-start-btn--mobile");
+    const recentItem = getLastRuleBlock(".launch-recent-item");
+    const recentItemHover = getLastRuleBlock(".launch-recent-item:hover");
+    const recentRow = getLastRuleBlock(".launch-recent-row");
+    const recentTime = getLastRuleBlock(".launch-recent-row__time");
+    const recentRemove = getLastRuleBlock(".launch-recent-remove");
+    const recentRemoveHover = getLastRuleBlock(".launch-recent-remove:hover");
 
     expect(modal).not.toContain("var(--component-rgba-17-24-31-0-98)");
     expect(modal).toContain("var(--component-mix-surface-panel-97pct-white-3pct)");
@@ -1225,6 +1251,19 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(launchButtonHover).toContain("box-shadow: var(--shadow-lg)");
     expect(mobileLaunchButton).toContain("border-radius: var(--radius-xl)");
     expect(mobileLaunchButton).toContain("box-shadow: var(--shadow-lg)");
+    expect(recentItem).toContain("position: relative");
+    expect(recentItem).toContain("border: 1px solid var(--border-default)");
+    expect(recentItem).toContain("border-radius: var(--radius-md)");
+    expect(recentItemHover).toContain("box-shadow: var(--shadow-sm)");
+    expect(recentRow).toContain("padding-right: calc(var(--sp-3) + 28px + var(--sp-2))");
+    expect(recentRow).not.toContain("border: 1px solid var(--border-default)");
+    expect(recentTime).toContain("color: var(--text-tertiary)");
+    expect(recentRemove).toContain("position: absolute");
+    expect(recentRemove).toContain("top: var(--sp-2)");
+    expect(recentRemove).toContain("right: var(--sp-2)");
+    expect(recentRemove).toContain("opacity: 0.56");
+    expect(recentRemove).not.toContain("min-height: 100%");
+    expect(recentRemoveHover).toContain("background: var(--surface-elevated)");
   });
 
   it("keeps workspace chrome on tokens instead of hardcoded dark fills", () => {
@@ -1271,6 +1310,10 @@ describe("components.css theme-sensitive surfaces", () => {
     const activityBarButton = getLastRuleBlock(".workspace-activity-bar__button");
     const activityBarButtonHover = getLastRuleBlock(".workspace-activity-bar__button:hover");
     const activityBarButtonActive = getLastRuleBlock(".workspace-activity-bar__button--active");
+    const activityBarButtonActiveHover = getLastRuleBlock(
+      ".workspace-activity-bar__button--active:hover"
+    );
+    const activityBarGlyphIcon = getLastRuleBlock(".workspace-activity-bar__glyph > .themed-icon");
     const sidebarActions = getLastRuleBlock(".workspace-sidebar-panel__actions");
     const verticalDividerRules = getRuleBlocksFrom(stylesheet, ".split-divider-v").join("\n");
     const horizontalDividerRules = getRuleBlocksFrom(stylesheet, ".split-divider-h").join("\n");
@@ -1321,9 +1364,18 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(topbarTabContent).toContain("gap: var(--gap-tight)");
     expect(topbarTabContent).toContain("background: transparent");
     expect(topbarTabContent).toContain("box-shadow: none");
-    expect(activeTab).toContain("var(--component-mix-surface-active-86pct-white-14pct)");
-    expect(activeTab).toContain("var(--component-mix-surface-active-94pct-surface-panel-6pct)");
-    expect(activeTab).not.toContain("rgba(45, 63, 79, 0.92)");
+    expect(topbarTab).toContain("border-radius: 4px 4px 0 0");
+    expect(topbarTab).toContain("background: transparent");
+    expect(activeTab).toContain(
+      "border-color: var(--component-mix-border-default-84pct-transparent)"
+    );
+    expect(activeTab).toContain("border-bottom-color: var(--status-info-fg)");
+    expect(activeTab).not.toContain("linear-gradient(");
+    expect(getLastRuleBlock(".topbar-close")).toContain("width: 16px");
+    expect(getLastRuleBlock(".topbar-close")).toContain("right: 5px");
+    expect(getLastRuleBlock(".topbar-close")).toContain(
+      "color: var(--component-mix-text-tertiary-82pct-status-info-fg-18pct)"
+    );
     expect(topbarTab).toContain("position: relative");
     expect(topbarTab).toContain("overflow: hidden");
     expect(miniMap).toContain("position: relative");
@@ -1404,14 +1456,16 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(activityBarButton).toContain("border-radius: var(--radius-md)");
     expect(activityBarButton).toContain("background: transparent");
     expect(activityBarButtonHover).toContain("background: var(--surface-hover)");
-    expect(activityBarButtonActive).toContain(
-      "background: var(--component-mix-status-info-fg-14pct-transparent)"
-    );
+    expect(activityBarButtonActive).toContain("background: var(--state-selected-bg)");
+    expect(activityBarButtonActiveHover).toContain("background: var(--state-selected-bg)");
+    expect(activityBarGlyphIcon).toContain("color: currentColor");
     expect(sidebarActions).toContain("gap: var(--gap-control)");
     expect(verticalDividerRules).toContain("width: 10px");
     expect(verticalDividerRules).not.toContain("width: 8px");
     expect(verticalDividerRules).toContain("margin-left: -5px");
     expect(verticalDividerRules).toContain("margin-right: -5px");
+    expect(verticalDividerRules).toContain("z-index: var(--z-inline)");
+    expect(verticalDividerRules).not.toContain("z-index: var(--z-inline-raised)");
     expect(verticalDividerLineRules).toContain(
       "background: var(--component-mix-border-default-62pct-transparent)"
     );
@@ -1419,30 +1473,27 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(horizontalDividerRules).not.toContain("height: 8px");
     expect(horizontalDividerRules).toContain("margin-top: -5px");
     expect(horizontalDividerRules).toContain("margin-bottom: -5px");
+    expect(horizontalDividerRules).toContain("z-index: var(--z-inline)");
+    expect(horizontalDividerRules).not.toContain("z-index: var(--z-inline-raised)");
     expect(horizontalDividerLineRules).toContain(
       "background: var(--component-mix-border-default-62pct-transparent)"
     );
     expect(paneDividerBaseRules).toContain("position: relative");
-    expect(paneDividerBaseRules).toContain("z-index: var(--z-inline-raised)");
-    expect(paneDividerBaseRules).toContain(
-      "background: linear-gradient(180deg, transparent, var(--state-info-bg), transparent)"
-    );
-    expect(paneDividerLineRules).toContain(
-      "background: var(--component-mix-border-default-62pct-transparent)"
-    );
+    expect(paneDividerBaseRules).toContain("z-index: var(--z-inline)");
+    expect(paneDividerBaseRules).not.toContain("z-index: var(--z-inline-raised)");
+    expect(paneDividerBaseRules).toContain("background: transparent");
+    expect(paneDividerLineRules).toContain("background: transparent");
     expect(paneDividerLineRules).toContain("border-radius: var(--radius-pill)");
-    expect(paneDividerHoverRules).toContain(
-      "background: var(--component-mix-border-focus-44pct-transparent-56pct)"
-    );
+    expect(paneDividerHoverRules).toContain("background: transparent");
     expect(paneDividerHorizontalRules).toContain("width: 10px");
     expect(paneDividerHorizontalRules).toContain("margin-left: -5px");
     expect(paneDividerHorizontalRules).toContain("margin-right: -5px");
-    expect(paneDividerHorizontalRules).not.toContain("background: transparent");
+    expect(paneDividerHorizontalRules).toContain("background: transparent");
     expect(paneDividerVerticalRules).toContain("width: 100%");
     expect(paneDividerVerticalRules).toContain("height: 10px");
     expect(paneDividerVerticalRules).toContain("margin-top: -5px");
     expect(paneDividerVerticalRules).toContain("margin-bottom: -5px");
-    expect(paneDividerVerticalRules).not.toContain("background: transparent");
+    expect(paneDividerVerticalRules).toContain("background: transparent");
     expect(hasLegacyPaneDividerHorizontalRule).toBe(false);
     expect(hasLegacyPaneDividerVerticalRule).toBe(false);
     expect(bottomPanel).toContain("padding: 0");
@@ -1769,6 +1820,15 @@ describe("components.css theme-sensitive surfaces", () => {
     const editorTabbarActions = getLastRuleBlock(".code-editor-tabbar__actions");
     const editorTabFrame = getLastRuleBlock(".code-editor-tab-item");
     const editorTabClose = getLastRuleBlock(".code-editor-tab__close");
+    const editorPreviewTabName = getLastRuleBlock(
+      ".code-editor-tab--preview .code-editor-tab__name"
+    );
+    const inactivePreviewTabFrame = getLastRuleBlock(
+      ".code-editor-tab-item--preview:not(.code-editor-tab-item--active)"
+    );
+    const previewTabInteractiveFrame = getLastGroupedRuleBlock(
+      /\.code-editor-tab-item--preview:hover,\s*\.code-editor-tab-item--preview\.code-editor-tab-item--active\s*\{([^}]*)\}/g
+    );
     const editorOverlayOpening =
       getRuleBlocksFrom(stylesheet, ".workspace-main-stage__editor-overlay--opening")[0] ?? "";
     const editorRestore = getRuleBlocksFrom(stylesheet, ".workspace-editor-restore")[0] ?? "";
@@ -1847,6 +1907,10 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(editorTabClose).toContain("width: 24px");
     expect(editorTabClose).toContain("border: none");
     expect(editorTabClose).not.toContain("border: 1px solid transparent");
+    expect(editorPreviewTabName).toContain("font-style: oblique 12deg");
+    expect(editorPreviewTabName).toContain("transform: skewX(-8deg)");
+    expect(inactivePreviewTabFrame).toContain("color: var(--text-tertiary)");
+    expect(previewTabInteractiveFrame).toContain("color: var(--text-primary)");
     expect(imageCanvasRules).toContain("overflow: hidden");
     expect(imageCanvasRules).not.toContain("overflow: auto");
     expect(editorOverlayOpening).toContain(
@@ -1934,6 +1998,7 @@ describe("components.css theme-sensitive surfaces", () => {
     const gitView = getLastRuleBlock(".workspace-git-view");
     const editorHeader = getLastRuleBlock(".code-editor-header");
     const editorBody = getLastRuleBlock(".code-editor-body");
+    const xtermReplayOverlay = getLastRuleBlock(".xterm-replay-overlay");
     const addedLine = getLastRuleBlock(".git-diff-line-added");
     const removedLine = getLastRuleBlock(".git-diff-line-removed");
     const diffEmpty = getLastRuleBlock(".git-diff-empty");
@@ -1984,6 +2049,7 @@ describe("components.css theme-sensitive surfaces", () => {
       "border-bottom: 1px solid var(--workspace-editor-toolbar-border)"
     );
     expect(editorBody).toContain("background: var(--surface-panel-bg)");
+    expect(xtermReplayOverlay).toContain("z-index: var(--z-inline)");
     expect(addedLine).toContain("background: var(--diff-added-bg)");
     expect(addedLine).toContain("color: var(--diff-added-fg)");
     expect(removedLine).toContain("background: var(--diff-deleted-bg)");
@@ -2136,6 +2202,16 @@ describe("components.css theme-sensitive surfaces", () => {
     const providerBody = getLastRuleBlock(".agent-provider-card-body");
     const providerCopy = getLastRuleBlock(".agent-provider-card-copy");
     const providerIcon = getLastRuleBlock(".agent-provider-card-icon");
+    const providerMonogram = getLastRuleBlock(".agent-provider-card-monogram");
+    const monogramClaude = getLastRuleBlock(".agent-provider-card-monogram--claude");
+    const monogramCodex = getLastRuleBlock(".agent-provider-card-monogram--codex");
+    const monogramGemini = getLastRuleBlock(".agent-provider-card-monogram--gemini");
+    const monogramCursor = getLastRuleBlock(".agent-provider-card-monogram--cursor");
+    const monogramOpencode = getLastRuleBlock(".agent-provider-card-monogram--opencode");
+    const monogramToneAccent = getLastRuleBlock(".agent-provider-card-monogram--tone-accent");
+    const monogramToneInfo = getLastRuleBlock(".agent-provider-card-monogram--tone-info");
+    const monogramToneSuccess = getLastRuleBlock(".agent-provider-card-monogram--tone-success");
+    const monogramToneWarning = getLastRuleBlock(".agent-provider-card-monogram--tone-warning");
     const dropZone = getLastRuleBlock(".agent-draft-drop-zone");
     const dropZoneIcon = getLastRuleBlock(".agent-draft-drop-zone-icon");
 
@@ -2178,17 +2254,42 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(providerCopy).toContain("gap: var(--gap-compact)");
     expect(providerIcon).toContain("width: 22px");
     expect(providerIcon).toContain("height: 22px");
+    expect(providerMonogram).toContain("min-width: 1.75rem");
+    expect(providerMonogram).toContain("min-height: 1.75rem");
+    expect(providerMonogram).toContain("font-family: var(--font-mono)");
+    expect(providerMonogram).toContain("font-weight: var(--type-heading-5-weight)");
+    expect(monogramClaude).toContain("color: var(--icon-accent)");
+    expect(monogramClaude).toContain("background: var(--icon-surface-accent)");
+    expect(monogramCodex).toContain("color: var(--icon-secondary)");
+    expect(monogramCodex).toContain("background: var(--icon-surface-subtle)");
+    expect(monogramCodex).toContain(
+      "border-color: var(--component-mix-border-default-64pct-transparent)"
+    );
+    expect(monogramGemini).toContain("color: var(--icon-info)");
+    expect(monogramGemini).toContain("background: var(--icon-surface-info)");
+    expect(monogramCursor).toContain("color: var(--icon-success)");
+    expect(monogramCursor).toContain("background: var(--icon-surface-success)");
+    expect(monogramOpencode).toContain("color: var(--icon-warning)");
+    expect(monogramOpencode).toContain("background: var(--icon-surface-warning)");
+    expect(monogramToneAccent).toContain("color: var(--icon-accent)");
+    expect(monogramToneAccent).toContain("background: var(--icon-surface-accent)");
+    expect(monogramToneInfo).toContain("color: var(--icon-info)");
+    expect(monogramToneInfo).toContain("background: var(--icon-surface-info)");
+    expect(monogramToneSuccess).toContain("color: var(--icon-success)");
+    expect(monogramToneSuccess).toContain("background: var(--icon-surface-success)");
+    expect(monogramToneWarning).toContain("color: var(--icon-warning)");
+    expect(monogramToneWarning).toContain("background: var(--icon-surface-warning)");
     expect(dropZone).toContain("border: 1px dashed var(--border-subtle)");
     expect(dropZone).toContain("min-height: 72px");
     expect(dropZone).toContain("width: 100%");
     expect(dropZone).toContain("box-sizing: border-box");
     expect(dropZoneIcon).toContain("width: 24px");
     expect(hasRuleBlock(".agent-draft-footer")).toBe(false);
-    expect(hasRuleBlock(".agent-provider-card-claude")).toBe(false);
-    expect(hasRuleBlock(".agent-provider-card-codex")).toBe(false);
-    expect(hasRuleBlock(".agent-provider-card-gemini")).toBe(false);
-    expect(hasRuleBlock(".agent-provider-card-cursor")).toBe(false);
-    expect(hasRuleBlock(".agent-provider-card-opencode")).toBe(false);
+    expect(hasRuleBlock(".agent-provider-card-monogram--claude")).toBe(true);
+    expect(hasRuleBlock(".agent-provider-card-monogram--codex")).toBe(true);
+    expect(hasRuleBlock(".agent-provider-card-monogram--gemini")).toBe(true);
+    expect(hasRuleBlock(".agent-provider-card-monogram--cursor")).toBe(true);
+    expect(hasRuleBlock(".agent-provider-card-monogram--opencode")).toBe(true);
     expect(hasRuleBlock(".agent-provider-card--experimental")).toBe(false);
   });
 
@@ -2272,9 +2373,9 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(pageHeader).toContain("width: 100%");
     expect(mobilePageHeader).toContain("min-height: 44px");
     expect(mobilePageHeaderLeading).toContain("gap: 8px");
-    expect(mobilePageHeaderTitle).toContain("font-size: var(--type-heading-5-size)");
-    expect(mobilePageHeaderTitle).toContain("line-height: var(--type-heading-5-line-height)");
-    expect(mobilePageHeaderTitle).toContain("font-weight: var(--type-heading-5-weight)");
+    expect(mobilePageHeaderTitle).toContain("font-size: var(--type-heading-6-size)");
+    expect(mobilePageHeaderTitle).toContain("line-height: var(--type-heading-6-line-height)");
+    expect(mobilePageHeaderTitle).toContain("font-weight: var(--type-heading-6-weight)");
     expect(mobilePageHeaderBack).toContain("min-height: var(--control-height-sm)");
     expect(mobilePageHeaderBack).toContain("gap: var(--gap-tight)");
     expect(mobilePageHeaderBack).toContain("font-family: var(--font-mono)");
@@ -2293,16 +2394,16 @@ describe("components.css theme-sensitive surfaces", () => {
     const primaryTitle = getLastRuleBlock(".page-header--primary .page-header__title");
     const secondaryTitle = getLastRuleBlock(".page-header--secondary .page-header__title");
 
-    expect(baseTitle).toContain("font-weight: var(--type-heading-5-weight)");
+    expect(baseTitle).toContain("font-weight: var(--type-heading-6-weight)");
     expect(copy).toContain("gap: var(--gap-compact)");
     expect(primaryHeader).toContain("min-height: 56px");
     expect(secondaryHeader).toContain("min-height: 48px");
-    expect(primaryTitle).toContain("font-size: var(--type-heading-4-size)");
-    expect(primaryTitle).toContain("line-height: var(--type-heading-4-line-height)");
-    expect(primaryTitle).toContain("font-weight: var(--type-heading-4-weight)");
-    expect(secondaryTitle).toContain("font-size: var(--type-heading-5-size)");
-    expect(secondaryTitle).toContain("line-height: var(--type-heading-5-line-height)");
-    expect(secondaryTitle).toContain("font-weight: var(--type-heading-5-weight)");
+    expect(primaryTitle).toContain("font-size: var(--type-heading-5-size)");
+    expect(primaryTitle).toContain("line-height: var(--type-heading-5-line-height)");
+    expect(primaryTitle).toContain("font-weight: var(--type-heading-5-weight)");
+    expect(secondaryTitle).toContain("font-size: var(--type-heading-6-size)");
+    expect(secondaryTitle).toContain("line-height: var(--type-heading-6-line-height)");
+    expect(secondaryTitle).toContain("font-weight: var(--type-heading-6-weight)");
   });
 
   it("keeps diagnostics mobile summary titles on the typography token contract", () => {
@@ -2662,6 +2763,63 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(stylesheet).not.toContain(".mobile-select-sheet__item-check {");
   });
 
+  it("styles mobile agent provider monograms with provider-specific token surfaces", () => {
+    const providerIcon = getLastRuleBlock(".mobile-agent-provider-icon");
+    const providerLabel = getLastRuleBlock(".mobile-agent-provider-icon__label");
+    const claude = getLastRuleBlock(".mobile-agent-provider-icon--claude");
+    const codex = getLastRuleBlock(".mobile-agent-provider-icon--codex");
+    const gemini = getLastRuleBlock(".mobile-agent-provider-icon--gemini");
+    const cursor = getLastRuleBlock(".mobile-agent-provider-icon--cursor");
+    const opencode = getLastRuleBlock(".mobile-agent-provider-icon--opencode");
+    const toneAccent = getLastRuleBlock(".mobile-agent-provider-icon--tone-accent");
+    const toneInfo = getLastRuleBlock(".mobile-agent-provider-icon--tone-info");
+    const toneSuccess = getLastRuleBlock(".mobile-agent-provider-icon--tone-success");
+    const toneWarning = getLastRuleBlock(".mobile-agent-provider-icon--tone-warning");
+
+    expect(providerIcon).toContain("width: 1.75rem");
+    expect(providerIcon).toContain("height: 1.75rem");
+    expect(providerIcon).toContain("border-radius: var(--radius-md)");
+    expect(providerIcon).toContain("border: 1px solid transparent");
+    expect(providerLabel).toContain("font-family: var(--font-mono)");
+    expect(providerLabel).toContain("font-weight: var(--type-heading-5-weight)");
+    expect(claude).toContain("color: var(--icon-accent)");
+    expect(claude).toContain("background: var(--icon-surface-accent)");
+    expect(codex).toContain("color: var(--icon-secondary)");
+    expect(codex).toContain("background: var(--icon-surface-subtle)");
+    expect(codex).toContain("border-color: var(--component-mix-border-default-64pct-transparent)");
+    expect(gemini).toContain("color: var(--icon-info)");
+    expect(gemini).toContain("background: var(--icon-surface-info)");
+    expect(cursor).toContain("color: var(--icon-success)");
+    expect(cursor).toContain("background: var(--icon-surface-success)");
+    expect(opencode).toContain("color: var(--icon-warning)");
+    expect(opencode).toContain("background: var(--icon-surface-warning)");
+    expect(toneAccent).toContain("color: var(--icon-accent)");
+    expect(toneAccent).toContain("background: var(--icon-surface-accent)");
+    expect(toneInfo).toContain("color: var(--icon-info)");
+    expect(toneInfo).toContain("background: var(--icon-surface-info)");
+    expect(toneSuccess).toContain("color: var(--icon-success)");
+    expect(toneSuccess).toContain("background: var(--icon-surface-success)");
+    expect(toneWarning).toContain("color: var(--icon-warning)");
+    expect(toneWarning).toContain("background: var(--icon-surface-warning)");
+  });
+
+  it("keeps the mobile agent provider sheet compact without affecting other command sheets", () => {
+    const agentItem = getLastRuleBlock(
+      ".mobile-agent-sheet--providers.mobile-select-sheet--command .mobile-select-sheet__item"
+    );
+    const agentCopy = getLastRuleBlock(
+      ".mobile-agent-sheet--providers.mobile-select-sheet--command .mobile-select-sheet__item-copy"
+    );
+    const agentRowItem = getLastRuleBlock(
+      ".mobile-agent-sheet--providers.mobile-select-sheet--command .mobile-select-sheet__item-row > .mobile-select-sheet__item"
+    );
+
+    expect(agentItem).toContain("min-height: 38px");
+    expect(agentItem).toContain("padding: 8px 16px");
+    expect(agentCopy).toContain("gap: 1px");
+    expect(agentRowItem).toContain("min-height: 38px");
+  });
+
   it("keeps the mobile dock as a three-entry bottom rail for agent, files, and terminal", () => {
     const mobileDock = getLastRuleBlock(".mobile-dock");
     const mobileDockItem = getRuleBlocksFrom(stylesheet, ".mobile-dock__item").find((block) =>
@@ -2828,6 +2986,9 @@ describe("components.css theme-sensitive surfaces", () => {
     const mobileSettingsHeaderPage = getLastRuleBlock(
       ".settings-page--mobile > .settings-header"
     ).replace(/\s+/g, " ");
+    const firstMobileSettingsGroupList = getLastRuleBlock(
+      ".settings-mobile-root > .settings-mobile-group:first-child .settings-mobile-group__list"
+    ).replace(/\s+/g, " ");
     const mobileSettingsHeaderPageHeader = getLastRuleBlock(".settings-header .mobile-page-header");
     const mobileSettingsHeaderLeading = getLastRuleBlock(
       ".settings-header .mobile-page-header .page-header__leading"
@@ -2850,6 +3011,8 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(mobileSettingsHeaderPage).toContain(
       "padding: calc(var(--mobile-safe-top) + var(--sp-1)) calc(var(--mobile-safe-right) + var(--sp-4)) var(--sp-1) calc(var(--mobile-safe-left) + var(--sp-4))"
     );
+    expect(mobileSettingsHeaderPage).toContain("border-bottom: none");
+    expect(firstMobileSettingsGroupList).toContain("border-top: none");
     expect(mobileSettingsHeaderPageHeader).toContain("gap: var(--sp-2)");
     expect(mobileSettingsHeaderLeading).toContain("gap: var(--sp-2)");
     expect(mobileSettingsHeaderBack).toContain("min-height: 32px");
@@ -2883,7 +3046,9 @@ describe("components.css theme-sensitive surfaces", () => {
     );
     const moreFeaturesMobilePage = getLastRuleBlock(".more-features-page--mobile");
     const moreFeaturesMobileList = getLastRuleBlock(".more-features-mobile-list");
+    const moreFeaturesMobileItem = getLastRuleBlock(".more-features-mobile-item");
     const moreFeaturesMobileDetail = getLastRuleBlock(".more-features-mobile-detail");
+    const moreFeaturesMobileDetailHeader = getLastRuleBlock(".more-features-mobile-detail__header");
     const moreFeaturesMobileDetailContent = getLastRuleBlock(
       ".more-features-mobile-detail__content"
     );
@@ -2915,14 +3080,24 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(moreFeaturesMobilePage).toContain("height: 100dvh");
     expect(moreFeaturesMobileList).toContain("flex: 1");
     expect(moreFeaturesMobileList).toContain("min-height: 0");
+    expect(moreFeaturesMobileList).not.toContain("display: grid");
+    expect(moreFeaturesMobileList).toContain("display: flex");
+    expect(moreFeaturesMobileList).toContain("flex-direction: column");
+    expect(moreFeaturesMobileList).toContain("align-items: stretch");
     expect(moreFeaturesMobileList).toContain(
-      "padding: var(--sp-3) 0 calc(var(--sp-6) + var(--mobile-safe-bottom))"
+      "padding: 0 0 calc(var(--sp-6) + var(--mobile-safe-bottom))"
     );
     expect(moreFeaturesMobileList).toContain("overflow-y: auto");
+    expect(moreFeaturesMobileItem).toContain("padding: var(--sp-2) var(--sp-4)");
+    expect(moreFeaturesMobileItem).toContain("border-bottom: 1px solid var(--border-default)");
+    expect(moreFeaturesMobileItem).not.toContain("border-top:");
     expect(moreFeaturesMobileDetail).toContain("display: flex");
     expect(moreFeaturesMobileDetail).toContain("flex-direction: column");
     expect(moreFeaturesMobileDetail).toContain("min-height: 100dvh");
     expect(moreFeaturesMobileDetail).toContain("height: 100dvh");
+    expect(moreFeaturesMobileDetailHeader.replace(/\s+/g, " ")).toContain(
+      "padding: 0 calc(var(--mobile-safe-right) + var(--sp-4)) 0 calc(var(--mobile-safe-left) + var(--sp-4))"
+    );
     expect(moreFeaturesMobileDetailContent).toContain("flex: 1");
     expect(moreFeaturesMobileDetailContent).toContain("min-height: 0");
     expect(moreFeaturesMobileDetailContent).toContain(
@@ -3093,16 +3268,34 @@ describe("components.css theme-sensitive surfaces", () => {
     const topbarWorkspaceButton = getLastGroupedRuleBlock(
       /\.mobile-topbar__workspace-button\s*\{([^}]*)\}/g
     );
+    const topbarActions = getLastRuleBlock(".mobile-topbar__actions");
     const topbarIconButton = getLastRuleBlock(".mobile-topbar__icon-button");
+    const topbarWorkspaceLeading = getLastRuleBlock(".mobile-topbar__workspace-leading");
+    const topbarWorkspaceName = getLastRuleBlock(".mobile-topbar__workspace-name");
+    const topbarIconThemedIcon = getLastRuleBlock(".mobile-topbar__icon-button .themed-icon");
 
     expect(topbar).toContain(
-      "padding: calc(var(--mobile-safe-top) + var(--sp-1)) calc(var(--mobile-safe-right) + var(--sp-4)) var(--sp-1) calc(var(--mobile-safe-left) + var(--sp-4))"
+      "padding: calc(var(--mobile-safe-top) + var(--sp-1)) calc(var(--mobile-safe-right) + var(--sp-3)) var(--sp-1) calc(var(--mobile-safe-left) + var(--sp-3))"
     );
+    expect(topbar).toContain("gap: var(--sp-2)");
     expect(topbarWorkspaceButton).toContain("border-bottom: none");
     expect(topbarWorkspaceButton).toContain("border-radius: 0");
+    expect(topbarWorkspaceButton).toContain("justify-content: flex-start");
+    expect(topbarWorkspaceButton).toContain("padding: 0 var(--sp-2) 0 var(--sp-1)");
+    expect(topbarWorkspaceLeading).toContain("display: inline-flex");
+    expect(topbarWorkspaceLeading).toContain("align-items: center");
+    expect(topbarWorkspaceLeading).toContain("align-self: center");
+    expect(topbarWorkspaceName).toContain("display: flex");
+    expect(topbarWorkspaceName).toContain("align-items: center");
+    expect(topbarWorkspaceName).toContain("align-self: center");
+    expect(topbarWorkspaceName).not.toContain("flex: 1 1 auto");
+    expect(topbarActions).toContain("gap: 4px");
     expect(topbarIconButton).toContain("border: none");
+    expect(topbarIconButton).toContain("width: 30px");
+    expect(topbarIconButton).toContain("min-width: 30px");
     expect(topbarIconButton).toContain("border-radius: 10px");
     expect(topbarIconButton).toContain("background: transparent");
+    expect(topbarIconThemedIcon).toContain("color: currentColor");
     expect(emptyStage).toContain("padding: clamp(34px, 9vh, 72px) var(--sp-4) var(--sp-3)");
     expect(bottomStack).toContain("background: var(--material-overlay)");
     expect(bottomStack).toContain(
@@ -3203,15 +3396,26 @@ describe("components.css theme-sensitive surfaces", () => {
       ".workspace-sidebar-section__actions .panel-toolbar-btn"
     );
     const mobileExplorerPanel = getLastRuleBlock(".mobile-explorer-panel");
+    const mobileFilesFillSection = getLastRuleBlock(
+      ".mobile-sheet--files .workspace-sidebar-section--fill"
+    );
+    const mobileQuickJumpSection = getLastRuleBlock(".mobile-sheet--files .workspace-quick-jump");
     const mobileQuickJumpSearch = getLastRuleBlock(
       ".mobile-sheet--files .workspace-quick-jump__search"
     );
     const mobileQuickJumpItem = getLastRuleBlock(".workspace-quick-jump__item");
     const mobileSearchPanel = getLastRuleBlock(".workspace-search-panel--mobile");
+    const mobileFilesSearchBody = getLastRuleBlock(
+      ".mobile-sheet--files .workspace-search-panel .workspace-sidebar-panel__body--stacked"
+    );
+    const mobileFilesSearchResults = getLastRuleBlock(
+      ".mobile-sheet--files .workspace-search-panel__results"
+    );
     const mobileFilesSearchSurfaceBlocks = getRuleBlocksFrom(
       stylesheet,
       ".mobile-sheet--files .workspace-search-panel--mobile"
     );
+    const mobileFilesGitScroll = getLastRuleBlock(".mobile-sheet--files .git-panel-scroll");
     const mobileFileSearch = getLastRuleBlock(
       ".mobile-sheet--files .file-tree-shell--mobile .file-tree-search"
     );
@@ -3222,7 +3426,34 @@ describe("components.css theme-sensitive surfaces", () => {
     const mobileFileRowSelected = getLastRuleBlock(
       ".mobile-sheet--files .file-tree-shell--mobile .tree-item.selected"
     );
+    const drawerRoot = getLastRuleBlock(".mobile-workspace-drawer");
+    const drawerHeaderCopy = getLastRuleBlock(".mobile-workspace-drawer__header-copy");
+    const drawerKicker = getLastRuleBlock(".mobile-workspace-drawer__kicker");
+    const drawerKickerBefore = getLastRuleBlock(".mobile-workspace-drawer__kicker::before");
+    const drawerDismiss = getLastRuleBlock(".mobile-workspace-drawer__dismiss");
+    const drawerList = getLastRuleBlock(".mobile-workspace-drawer__list");
     const drawerItem = getLastRuleBlock(".mobile-workspace-drawer__item");
+    const drawerActiveItemBlocks = getRuleBlocksFrom(
+      stylesheet,
+      ".mobile-workspace-drawer__item--active"
+    );
+    const drawerItemMain = getLastRuleBlock(".mobile-workspace-drawer__item-main");
+    const drawerItemNameRow = getLastRuleBlock(".mobile-workspace-drawer__item-name-row");
+    const drawerItemActions = getLastRuleBlock(".mobile-workspace-drawer__item-actions");
+    const drawerItemCreateBlocks = getRuleBlocksFrom(
+      stylesheet,
+      ".mobile-workspace-drawer__item-create"
+    );
+    const drawerItemCloseBlocks = getRuleBlocksFrom(
+      stylesheet,
+      ".mobile-workspace-drawer__item-close"
+    );
+    const drawerItemChildren = getLastRuleBlock(".mobile-workspace-drawer__item-children");
+    const drawerChildEmpty = getLastRuleBlock(".mobile-workspace-drawer__child-empty");
+    const drawerChildSessionBlocks = getRuleBlocksFrom(
+      stylesheet,
+      ".mobile-workspace-drawer__child-session"
+    );
     const drawerFooterButton = getLastRuleBlock(".mobile-workspace-drawer__footer-button");
     const welcomeCard = getLastRuleBlock(".welcome-card--mobile");
     const welcomeFeature = getLastRuleBlock(".welcome-card--mobile .welcome-feature");
@@ -3251,6 +3482,9 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(mobileFilesSegmented).not.toContain("linear-gradient(");
     expect(mobileExplorerPanel).toContain("display: flex");
     expect(mobileExplorerPanel).toContain("flex-direction: column");
+    expect(mobileFilesFillSection).toContain("flex: 1 1 auto");
+    expect(mobileFilesFillSection).toContain("min-height: 0");
+    expect(mobileQuickJumpSection).toContain("flex: 0 0 auto");
     expect(mobileFilesSegment).toContain("padding: 0");
     expect(mobileFilesSegment).toContain("justify-content: center");
     expect(mobileFilesSegment).toContain("min-width: 38px");
@@ -3273,6 +3507,10 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(mobileQuickJumpSearch).toContain("border-radius: 4px");
     expect(mobileQuickJumpItem).toContain("grid-template-columns: minmax(0, 1fr)");
     expect(mobileSearchPanel).toContain("background: transparent");
+    expect(mobileFilesSearchBody).toContain("grid-template-rows: auto minmax(0, 1fr)");
+    expect(mobileFilesSearchBody).toContain("min-height: 0");
+    expect(mobileFilesSearchResults).toContain("overflow-y: auto");
+    expect(mobileFilesSearchResults).toContain("min-height: 0");
     expect(
       mobileFilesSearchSurfaceBlocks.some(
         (block) =>
@@ -3281,6 +3519,8 @@ describe("components.css theme-sensitive surfaces", () => {
           block.includes("box-shadow: none")
       )
     ).toBe(true);
+    expect(mobileFilesGitScroll).toContain("overflow-y: auto");
+    expect(mobileFilesGitScroll).toContain("min-height: 0");
     expect(
       mobileFilesSurfaceBlocks.some(
         (block) =>
@@ -3310,8 +3550,76 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(mobileFileRowSelected).not.toContain("border-left:");
     expect(mobileFileRowSelected).toContain("border: 1px solid var(--state-selected-border)");
     expect(mobileFileRowSelected).toContain("background: var(--state-selected-bg)");
-    expect(drawerItem).toContain("border-radius: var(--radius-xl)");
-    expect(drawerFooterButton).toContain("border-radius: var(--radius-md)");
+    expect(drawerItem).toContain("display: grid");
+    expect(drawerItem).toContain("grid-template-columns: minmax(0, 1fr) auto");
+    expect(drawerItem).toContain("align-items: flex-start");
+    expect(drawerList).toContain("margin: 0");
+    expect(drawerItemMain).toContain("justify-content: flex-start");
+    expect(drawerItemMain).toContain("padding: 6px 0 4px 0");
+    expect(drawerItemNameRow).toContain("min-height: 20px");
+    expect(drawerItemChildren).toContain("display: flex");
+    expect(drawerItemChildren).toContain("grid-column: 1 / -1");
+    expect(drawerItemChildren).toContain("flex-direction: column");
+    expect(drawerItemChildren).toContain(
+      "border-top: 1px solid var(--component-mix-border-default-62pct-transparent)"
+    );
+    expect(drawerChildEmpty).toContain("display: flex");
+    expect(drawerChildEmpty).toContain("flex-direction: column");
+    expect(drawerChildEmpty).toContain("padding: 4px 0 4px 14px");
+    expect(drawerChildSessionBlocks.some((block) => block.includes("display: flex"))).toBe(true);
+    expect(drawerChildSessionBlocks.some((block) => block.includes("width: 100%"))).toBe(true);
+    expect(drawerChildSessionBlocks.some((block) => block.includes("gap: 2px"))).toBe(true);
+    expect(
+      drawerChildSessionBlocks.some((block) => block.includes("padding: 1px 0 1px 14px"))
+    ).toBe(true);
+    expect(drawerRoot).not.toContain("linear-gradient(");
+    expect(drawerHeaderCopy).toContain("justify-content: center");
+    expect(drawerHeaderCopy).toContain("padding: 0");
+    expect(drawerKicker).toContain("gap: 4px");
+    expect(drawerKicker).toContain("font-family: var(--font-sans)");
+    expect(drawerKicker).toContain("font-size: var(--type-body-6-size)");
+    expect(drawerKicker).toContain("font-weight: var(--font-medium)");
+    expect(drawerKicker).toContain("letter-spacing: 0.02em");
+    expect(drawerKickerBefore).toContain("display: none");
+    expect(drawerDismiss).toContain("border-radius: var(--radius-md)");
+    expect(drawerDismiss).toContain("width: 28px");
+    expect(drawerDismiss).toContain("height: 28px");
+    expect(drawerDismiss).toContain("border: none");
+    expect(drawerDismiss).not.toContain("border-radius: 999px");
+    expect(drawerItem).toContain("border-radius: 0");
+    expect(drawerItem).toContain("background: transparent");
+    expect(drawerItem).not.toContain("linear-gradient(");
+    expect(drawerItem).not.toContain("border-top:");
+    expect(drawerItem).toContain("box-shadow: none");
+    expect(drawerActiveItemBlocks.some((block) => block.includes("linear-gradient("))).toBe(false);
+    expect(drawerItemActions).toContain("display: inline-flex");
+    expect(drawerItemActions).toContain("min-height: 20px");
+    expect(drawerItemActions).toContain("align-self: flex-start");
+    expect(drawerItemActions).toContain("padding-top: 6px");
+    expect(
+      drawerItemCreateBlocks.some(
+        (block) =>
+          block.includes("border-radius: var(--radius-sm)") &&
+          block.includes("background: transparent")
+      )
+    ).toBe(true);
+    expect(
+      drawerItemCloseBlocks.some((block) => block.includes("border-radius: var(--radius-sm)"))
+    ).toBe(true);
+    expect(drawerItemCloseBlocks.some((block) => block.includes("border-radius: 999px"))).toBe(
+      false
+    );
+    expect(drawerChildSessionBlocks.some((block) => block.includes("border-radius: 0"))).toBe(true);
+    expect(drawerChildSessionBlocks.some((block) => block.includes("border: 0"))).toBe(true);
+    expect(
+      drawerChildSessionBlocks.some((block) => block.includes("background: transparent"))
+    ).toBe(true);
+    expect(drawerChildSessionBlocks.some((block) => block.includes("linear-gradient("))).toBe(
+      false
+    );
+    expect(drawerFooterButton).toContain("border-radius: 0");
+    expect(drawerFooterButton).toContain("background: transparent");
+    expect(drawerFooterButton).not.toContain("linear-gradient(");
     expect(welcomeCard).toContain("border-radius: var(--radius-lg)");
     expect(welcomeFeature).toContain("border-radius: var(--radius-lg)");
     expect(welcomeButton).toContain("border-radius: var(--radius-md)");
@@ -3757,6 +4065,10 @@ describe("components.css theme-sensitive surfaces", () => {
     );
     const toggle = getRuleBlocksFrom(stylesheet, ".git-panel-section-toggle").join("\n");
     const sectionCount = getLastRuleBlock(".git-panel-section-count");
+    const sectionActionIcon = getLastRuleBlock(".git-panel-section-action-icon");
+    const hiddenSectionLinkRule = getLastRuleBlock(
+      ".git-panel-section-actions .git-panel-section-link:not(:last-child)"
+    );
     const desktopPanel = getLastRuleBlock(".git-panel--desktop");
 
     expect(section).toContain("min-width: 0");
@@ -3771,6 +4083,10 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(sectionCount).toContain("font-size: var(--type-body-6-size)");
     expect(sectionCount).toContain("line-height: var(--type-body-6-line-height)");
     expect(sectionCount).toContain("font-weight: var(--type-body-6-weight)");
+    expect(sectionActionIcon).toContain("width: 24px");
+    expect(sectionActionIcon).toContain("height: 24px");
+    expect(sectionActionIcon).toContain("border-radius: var(--radius-md)");
+    expect(hiddenSectionLinkRule).toContain("display: none");
     expect(desktopPanel).toContain("min-height: 0");
     expect(desktopPanel).toContain("height: 100%");
   });
diff --git a/packages/web/src/styles/memory-panel.guard.test.ts b/packages/web/src/styles/memory-panel.guard.test.ts
index 959182541..fc30eba8b 100644
--- a/packages/web/src/styles/memory-panel.guard.test.ts
+++ b/packages/web/src/styles/memory-panel.guard.test.ts
@@ -45,15 +45,27 @@ describe("memory panel styles", () => {
       (match) => match[0]
     ).join("\n");
 
-    expect(badgeVariants).toContain(".memory-panel__badge--feature");
+    expect(badgeVariants).toContain(".memory-panel__badge--wiki");
+    expect(badgeVariants).toContain(".memory-panel__badge--issue");
     expect(badgeVariants).toContain(".memory-panel__badge--todo");
-    expect(badgeVariants).toContain(".memory-panel__badge--bugfix");
-    expect(badgeVariants).toContain(".memory-panel__badge--project");
     expect(badgeVariants).toContain(".memory-panel__badge--note");
+    expect(badgeVariants).not.toContain(".memory-panel__badge--feature");
+    expect(badgeVariants).not.toContain(".memory-panel__badge--bugfix");
+    expect(badgeVariants).not.toContain(".memory-panel__badge--project");
     expect(badgeVariants).not.toContain("workflow");
     expect(badgeVariants).not.toContain("decision");
     expect(badgeVariants).not.toContain("project_fact");
     expect(badgeVariants).not.toContain("task_context");
     expect(badgeVariants).not.toContain("preference");
   });
+
+  it("defines dedicated status badge variants for actionable memory states", () => {
+    const css = readFileSync(`${process.cwd()}/src/styles/components.css`, "utf8");
+
+    expect(css).toContain(".memory-panel__badge--status {");
+    expect(css).toContain(".memory-panel__badge--status-not_started {");
+    expect(css).toContain(".memory-panel__badge--status-in_progress {");
+    expect(css).toContain(".memory-panel__badge--status-pending_verification {");
+    expect(css).toContain(".memory-panel__badge--status-completed {");
+  });
 });
diff --git a/packages/web/src/styles/pane-layout-divider.theme.test.ts b/packages/web/src/styles/pane-layout-divider.theme.test.ts
index 86810e77f..e1900cfb4 100644
--- a/packages/web/src/styles/pane-layout-divider.theme.test.ts
+++ b/packages/web/src/styles/pane-layout-divider.theme.test.ts
@@ -29,16 +29,24 @@ function getRuleBlocks(selector: string) {
 }
 
 describe("pane-layout vertical divider styles", () => {
-  it("keeps stacked pane dividers visible on shared workspace surfaces", () => {
+  it("keeps stacked pane divider hit areas transparent and below editor overlays", () => {
+    const baseDivider = getRuleBlocks(".pane-layout-divider").join("\n");
     const divider = getRuleBlocks(".pane-layout-vertical-divider").join("\n");
     const dividerLine = getRuleBlocks(".pane-layout-vertical-divider::after").join("\n");
-
+    const hoverDividerLine = getRuleBlocks(".pane-layout-divider:hover::after").join("\n");
+
+    expect(baseDivider).toContain("z-index: var(--z-inline)");
+    expect(baseDivider).not.toContain("z-index: var(--z-inline-raised)");
+    expect(baseDivider).not.toContain("z-index: var(--z-modal");
+    expect(baseDivider).not.toContain("z-index: var(--z-popover");
+    expect(baseDivider).not.toContain("z-index: var(--z-tooltip");
+    expect(baseDivider).toContain("background: transparent");
     expect(divider).toContain("width: 100%");
     expect(divider).toContain("height: 10px");
     expect(divider).toContain("margin-top: -5px");
     expect(divider).toContain("margin-bottom: -5px");
-    expect(divider).toContain("background: linear-gradient(");
-    expect(divider).toContain("var(--component-mix-status-info-fg-24pct-transparent)");
-    expect(dividerLine).toContain("var(--component-mix-border-default-78pct-status-info-fg-22pct)");
+    expect(divider).toContain("background: transparent");
+    expect(dividerLine).toContain("background: transparent");
+    expect(hoverDividerLine).toContain("background: transparent");
   });
 });
diff --git a/packages/web/src/styles/tokens.css b/packages/web/src/styles/tokens.css
index 381d5059f..a4db3af7d 100644
--- a/packages/web/src/styles/tokens.css
+++ b/packages/web/src/styles/tokens.css
@@ -288,15 +288,15 @@
   --z-local-overlay: 240;
   --z-sheet-backdrop: 300;
   --z-sheet: 310;
-  --z-modal-backdrop: 320;
-  --z-modal: 330;
+  --z-modal-backdrop: 380;
+  --z-modal: 390;
   --z-drawer-backdrop: 340;
   --z-drawer: 350;
   --z-workbench-backdrop: 360;
   --z-workbench: 370;
-  --z-popover: 380;
-  --z-tooltip: 390;
-  --z-toast: 400;
+  --z-popover: 400;
+  --z-tooltip: 410;
+  --z-toast: 420;
 
   /* ========== Visual稿别名 (short aliases) ========== */
   --text: var(--text-primary);
diff --git a/packages/web/src/theme/icon-theme.test.ts b/packages/web/src/theme/icon-theme.test.ts
index c36ea4555..99d1f34b0 100644
--- a/packages/web/src/theme/icon-theme.test.ts
+++ b/packages/web/src/theme/icon-theme.test.ts
@@ -1,4 +1,4 @@
-import { AlertTriangle, Info } from "lucide-react";
+import { AlertTriangle, Info, Terminal } from "lucide-react";
 import { describe, expect, it } from "vitest";
 import { BASE_ICON_THEME, getIconPresentation, ICON_SEMANTICS, THEME_IDS } from "./index";
 
@@ -117,6 +117,7 @@ describe("theme icon resolver", () => {
       const tones = new Set([
         getIconPresentation(themeId, "nav.settings.general").tone,
         getIconPresentation(themeId, "nav.settings.providers").tone,
+        getIconPresentation(themeId, "nav.settings.terminal").tone,
         getIconPresentation(themeId, "nav.settings.appearance").tone,
         getIconPresentation(themeId, "nav.settings.shortcuts").tone,
         getIconPresentation(themeId, "nav.settings.monitoring").tone,
@@ -148,6 +149,13 @@ describe("theme icon resolver", () => {
     }
   });
 
+  it("uses the terminal glyph for the terminal settings nav semantic", () => {
+    expect(BASE_ICON_THEME.icons["nav.settings.terminal"]).toEqual({
+      glyph: Terminal,
+      tone: "secondary",
+    });
+  });
+
   it("applies the approved seasonal icon hierarchy without retheming semantic status icons", () => {
     for (const themeId of ["spring-dark", "spring-light"] as const) {
       expect(getIconPresentation(themeId, "mobile.dock.agent")).toEqual(
diff --git a/packages/web/src/theme/icon-theme.ts b/packages/web/src/theme/icon-theme.ts
index 27afd6a29..30ad87641 100644
--- a/packages/web/src/theme/icon-theme.ts
+++ b/packages/web/src/theme/icon-theme.ts
@@ -87,6 +87,7 @@ export const ICON_SEMANTICS = [
   "mobile.dock.terminal",
   "nav.settings.general",
   "nav.settings.providers",
+  "nav.settings.terminal",
   "nav.settings.appearance",
   "nav.settings.shortcuts",
   "nav.settings.monitoring",
@@ -213,6 +214,7 @@ export const BASE_ICON_THEME: IconThemeDefinition = {
     "mobile.dock.terminal": { glyph: PanelBottom, tone: "current" },
     "nav.settings.general": { glyph: Settings, tone: "secondary" },
     "nav.settings.providers": { glyph: Globe, tone: "secondary" },
+    "nav.settings.terminal": { glyph: Terminal, tone: "secondary" },
     "nav.settings.appearance": { glyph: Palette, tone: "secondary" },
     "nav.settings.shortcuts": { glyph: Keyboard, tone: "secondary" },
     "nav.settings.monitoring": { glyph: Eye, tone: "secondary" },
diff --git a/packages/web/src/ui-preview/catalog.test.tsx b/packages/web/src/ui-preview/catalog.test.tsx
index 4045db9cd..fae097337 100644
--- a/packages/web/src/ui-preview/catalog.test.tsx
+++ b/packages/web/src/ui-preview/catalog.test.tsx
@@ -172,6 +172,7 @@ describe("UI preview catalog", () => {
         "app-loading-shell",
         "workspace-load-error",
         "workspace-desktop",
+        "workspace-custom-skills-review",
         "workspace-mobile",
         "workspace-draft-pane-editor-review",
         "auth-preview",
@@ -185,10 +186,29 @@ describe("UI preview catalog", () => {
     const scene = getUiPreviewScene("settings-appearance");
     expect(
       scene?.router({ theme: "mint-dark", locale: "en", device: "desktop" }).initialEntries
-    ).toEqual(["/settings"]);
+    ).toEqual(["/more/settings/appearance"]);
     expect(scene?.capture?.settingsSection).toBe("appearance");
   });
 
+  it("renders settings section scenes through the canonical More route", async () => {
+    const appearanceScene = renderScene("settings-appearance");
+
+    expect(await screen.findByTestId("more-features-page")).toBeInTheDocument();
+    expect(screen.getByRole("tab", { name: "Settings" })).toHaveAttribute("aria-selected", "true");
+    expect(screen.getByRole("button", { name: "Appearance" })).toHaveAttribute(
+      "aria-current",
+      "page"
+    );
+    expect(await screen.findByRole("heading", { name: "Theme" })).toBeInTheDocument();
+    expect(screen.getByRole("heading", { name: "Background & Material" })).toBeInTheDocument();
+
+    appearanceScene.unmount();
+    renderScene("settings-providers");
+
+    expect(await screen.findByTestId("more-features-page")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Agents" })).toHaveAttribute("aria-current", "page");
+  });
+
   it("marks the shortcuts settings scene for capture-time navigation", () => {
     const scene = getUiPreviewScene("settings-shortcuts");
     expect(scene?.capture?.settingsSection).toBe("shortcuts");
@@ -198,10 +218,20 @@ describe("UI preview catalog", () => {
     const scene = getUiPreviewScene("settings-monitoring");
     expect(
       scene?.router({ theme: "mint-dark", locale: "en", device: "desktop" }).initialEntries
-    ).toEqual(["/settings?section=monitoring"]);
+    ).toEqual(["/more/analysis/monitoring"]);
     expect(scene?.capture?.selector).toBe(".settings-monitoring-shell");
   });
 
+  it("renders the monitoring settings scene directly into monitoring content", async () => {
+    renderScene("settings-monitoring");
+
+    expect(await screen.findByTestId("more-features-page")).toBeInTheDocument();
+    expect(
+      await screen.findByRole("heading", { name: "Performance monitoring" })
+    ).toBeInTheDocument();
+    expect(document.querySelector(".settings-monitoring-shell")).toBeTruthy();
+  });
+
   it("seeds the monitoring review scene with attribution, detail, and subprocess content", () => {
     const scene = getUiPreviewScene("settings-monitoring");
     const seed = scene?.seed({ theme: "mint-light", locale: "en", device: "desktop" });
@@ -341,8 +371,11 @@ describe("UI preview catalog", () => {
   it("renders the shortcuts settings scene with the shortcuts list", async () => {
     renderScene("settings-shortcuts");
 
-    fireEvent.click(await screen.findByRole("button", { name: /keyboard shortcuts/i }));
-    expect(await screen.findByLabelText(/keyboard shortcuts/i)).toBeInTheDocument();
+    expect(await screen.findByTestId("more-features-page")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /keyboard shortcuts/i })).toHaveAttribute(
+      "aria-current",
+      "page"
+    );
     expect(document.querySelector(".shortcuts-list")).toBeTruthy();
   });
 
@@ -454,6 +487,22 @@ describe("UI preview catalog", () => {
     expect(screen.getAllByText("Draft")).toHaveLength(2);
   });
 
+  it("renders the custom skills workspace review scene and opens the skills sidebar", async () => {
+    renderScene("workspace-custom-skills-review");
+
+    expect(
+      await screen.findByRole("navigation", { name: /Workspace activity bar|工作区活动栏/i })
+    ).toBeInTheDocument();
+
+    fireEvent.click(screen.getByRole("button", { name: /Skills|技能/i }));
+
+    expect(
+      await screen.findByRole("heading", { level: 2, name: "Custom Skills" })
+    ).toBeInTheDocument();
+    expect(screen.getByText("Review Ops Skill")).toBeInTheDocument();
+    expect(screen.getByText("Session Audit Helper")).toBeInTheDocument();
+  });
+
   it("renders the editor-pane review scene with pane-local editor toolbar chrome", async () => {
     renderScene("workspace-editor-pane-review");
 
@@ -575,16 +624,25 @@ describe("UI preview catalog", () => {
   it("renders the settings density review scene", async () => {
     renderScene("settings-density-review");
 
-    expect(await screen.findByRole("heading", { name: /settings|设置/i })).toBeInTheDocument();
-    expect(document.querySelector(".settings-header .page-header")).toBeTruthy();
-    expect(document.querySelector(".settings-sidebar")).toBeTruthy();
+    expect(
+      await screen.findByRole("heading", { name: /more features|更多功能/i })
+    ).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "General" })).toHaveAttribute("aria-current", "page");
+    expect(document.querySelector(".more-features-page__page-header")).toBeTruthy();
+    expect(document.querySelector(".more-features-shell__nav")).toBeTruthy();
   });
 
   it("renders the settings light theme review scene", async () => {
     renderScene("settings-light-theme-review", "desktop", "mint-light");
 
-    expect(await screen.findByRole("heading", { name: /settings|设置/i })).toBeInTheDocument();
-    expect(document.querySelector(".settings-page")).toBeTruthy();
+    expect(
+      await screen.findByRole("heading", { name: /more features|更多功能/i })
+    ).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Appearance" })).toHaveAttribute(
+      "aria-current",
+      "page"
+    );
+    expect(document.querySelector(".settings-content")).toBeTruthy();
     expect(document.querySelector(".settings-nav-item")).toBeTruthy();
     expect(document.documentElement).toHaveAttribute("data-theme", "mint-light");
   });
diff --git a/packages/web/src/ui-preview/preview-store.ts b/packages/web/src/ui-preview/preview-store.ts
index 7aeacf01e..83265e360 100644
--- a/packages/web/src/ui-preview/preview-store.ts
+++ b/packages/web/src/ui-preview/preview-store.ts
@@ -16,7 +16,7 @@ import type {
   SkillInstallJobSnapshot,
   SkillLibraryEntry,
   SkillMountRelation,
-  SkillRecommendationEntry,
+  SkillRecommendationPage,
   SkillVersionCheckEntry,
   Supervisor,
   UpdateStateView,
@@ -132,7 +132,7 @@ export interface UiPreviewCommands {
     targets: Array<AgentSkillTargetEntry & { mountedSkillCount: number }>;
     mounts: SkillMountRelation[];
   };
-  skillsRecommendations?: SkillRecommendationEntry[];
+  skillsRecommendations?: SkillRecommendationPage;
   skillsSearchResultsByQuery?: Record<
     string,
     Array<{
@@ -157,6 +157,14 @@ export interface UiPreviewCommands {
       mounts: SkillMountRelation[];
     }
   >;
+  skillsLocalFileEntriesBySlug?: Record<
+    string,
+    Array<{
+      path: string;
+      kind: "file" | "dir";
+      content?: string;
+    }>
+  >;
   skillsVersionChecks?: SkillVersionCheckEntry[];
   terminalListByWorkspaceId?: Record<
     string,
@@ -259,6 +267,454 @@ function getTerminalPreviewSeq(seed: UiPreviewSeed, terminalId: string): number
   return getTerminalPreviewBytes(seed, terminalId).byteLength;
 }
 
+type PreviewSkillLibraryItem = NonNullable<UiPreviewCommands["skillsLibraryList"]>[number];
+type PreviewSkillInfoMap = NonNullable<UiPreviewCommands["skillsInfoBySlug"]>;
+type PreviewSkillTarget = NonNullable<UiPreviewCommands["skillsHealthScan"]>["targets"][number];
+
+interface PreviewSkillFsFileEntry {
+  kind: "file";
+  content: string;
+}
+
+interface PreviewSkillFsDirEntry {
+  kind: "dir";
+}
+
+type PreviewSkillFsEntry = PreviewSkillFsFileEntry | PreviewSkillFsDirEntry;
+
+interface PreviewSkillsState {
+  library: PreviewSkillLibraryItem[];
+  healthScan: {
+    targets: PreviewSkillTarget[];
+    mounts: SkillMountRelation[];
+  };
+  localFilesBySlug: Map<string, Map<string, PreviewSkillFsEntry>>;
+  infoBySlug: PreviewSkillInfoMap;
+  localSkillRoot: string;
+}
+
+function cloneSkillLibraryItem(item: PreviewSkillLibraryItem): PreviewSkillLibraryItem {
+  return {
+    ...item,
+    mountedProviderIds: [...item.mountedProviderIds],
+  };
+}
+
+function cloneSkillMountRelation(relation: SkillMountRelation): SkillMountRelation {
+  return {
+    ...relation,
+  };
+}
+
+function cloneSkillTarget(target: PreviewSkillTarget): PreviewSkillTarget {
+  return {
+    ...target,
+  };
+}
+
+function cloneSkillInfoMap(input: UiPreviewCommands["skillsInfoBySlug"]): PreviewSkillInfoMap {
+  return Object.fromEntries(
+    Object.entries(input ?? {}).map(([slug, info]) => [
+      slug,
+      {
+        ...info,
+        libraryEntry: info.libraryEntry ? { ...info.libraryEntry } : undefined,
+        mounts: info.mounts.map((mount) => ({ ...mount })),
+      },
+    ])
+  );
+}
+
+function previewHash(content: string): string {
+  let hash = 0;
+  for (let index = 0; index < content.length; index += 1) {
+    hash = (hash * 31 + content.charCodeAt(index)) >>> 0;
+  }
+  return `preview:${content.length}:${hash.toString(16)}`;
+}
+
+function slugifyPreviewSkillName(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+function buildDefaultCustomSkillMarkdown(displayName: string, slug: string): string {
+  return [
+    "---",
+    `name: ${slug}`,
+    "description: Custom skill",
+    "---",
+    "",
+    `# ${displayName}`,
+    "",
+  ].join("\n");
+}
+
+function normalizeSkillPath(input?: string, rootFallback = "."): string {
+  const trimmed = (input ?? "").trim();
+  if (!trimmed || trimmed === "." || trimmed === "./") {
+    return rootFallback;
+  }
+
+  const sanitized = trimmed
+    .replace(/\\/g, "/")
+    .replace(/^\.\/+/, "")
+    .replace(/\/+/g, "/")
+    .replace(/\/+$/g, "");
+
+  if (!sanitized || sanitized === ".") {
+    return rootFallback;
+  }
+
+  const segments = sanitized.split("/");
+  if (segments.some((segment) => !segment || segment === "." || segment === "..")) {
+    throw { code: "path_escape", message: "Path escapes skill root" };
+  }
+
+  return segments.join("/");
+}
+
+function parentSkillPath(path: string): string {
+  if (path === ".") {
+    return ".";
+  }
+
+  const slashIndex = path.lastIndexOf("/");
+  return slashIndex === -1 ? "." : path.slice(0, slashIndex);
+}
+
+function basenameSkillPath(path: string): string {
+  if (path === ".") {
+    return ".";
+  }
+
+  const slashIndex = path.lastIndexOf("/");
+  return slashIndex === -1 ? path : path.slice(slashIndex + 1);
+}
+
+function ensurePreviewDirEntries(tree: Map<string, PreviewSkillFsEntry>, targetPath: string): void {
+  let current = ".";
+  for (const segment of targetPath.split("/")) {
+    current = current === "." ? segment : `${current}/${segment}`;
+    const existing = tree.get(current);
+    if (existing?.kind === "file") {
+      throw { code: "already_exists", message: "File already exists" };
+    }
+    if (!existing) {
+      tree.set(current, { kind: "dir" });
+    }
+  }
+}
+
+function listPreviewSkillChildren(
+  tree: Map<string, PreviewSkillFsEntry>,
+  dirPath: string
+): FileNode[] {
+  const dirEntry = tree.get(dirPath);
+  if (!dirEntry || dirEntry.kind !== "dir") {
+    throw { code: "not_found", message: "Directory not found" };
+  }
+
+  const children: FileNode[] = [];
+  for (const [path, entry] of tree.entries()) {
+    if (path === "." || parentSkillPath(path) !== dirPath) {
+      continue;
+    }
+
+    children.push({
+      name: basenameSkillPath(path),
+      path,
+      kind: entry.kind,
+    });
+  }
+
+  return children.sort((left, right) => {
+    if (left.kind !== right.kind) {
+      return left.kind === "dir" ? -1 : 1;
+    }
+    return left.name.localeCompare(right.name);
+  });
+}
+
+function getPreviewLocalSkillTree(state: PreviewSkillsState, skillSlug: string) {
+  const tree = state.localFilesBySlug.get(skillSlug);
+  if (!tree) {
+    throw { code: "skill_not_found", message: `Custom skill not found: ${skillSlug}` };
+  }
+  return tree;
+}
+
+function getPreviewSkillLibraryEntry(state: PreviewSkillsState, skillSlug: string) {
+  const entry = state.library.find((skill) => skill.slug === skillSlug);
+  if (!entry || entry.source !== "custom") {
+    throw { code: "skill_not_found", message: `Custom skill not found: ${skillSlug}` };
+  }
+  return entry;
+}
+
+function touchPreviewSkill(state: PreviewSkillsState, skillSlug: string): void {
+  const entry = getPreviewSkillLibraryEntry(state, skillSlug);
+  entry.updatedAt = Date.now();
+}
+
+function readPreviewSkillFile(
+  state: PreviewSkillsState,
+  skillSlug: string,
+  relPath: string
+): {
+  kind: "text";
+  content: string;
+  baseHash: string;
+  encoding: "utf-8";
+  displayPath: string;
+} {
+  const entry = getPreviewSkillLibraryEntry(state, skillSlug);
+  const tree = getPreviewLocalSkillTree(state, skillSlug);
+  const normalizedPath = normalizeSkillPath(relPath, ".");
+  const node = tree.get(normalizedPath);
+
+  if (!node || node.kind !== "file") {
+    throw { code: "not_found", message: "File not found" };
+  }
+
+  return {
+    kind: "text",
+    content: node.content,
+    baseHash: previewHash(node.content),
+    encoding: "utf-8",
+    displayPath: `${entry.libraryPath}/${normalizedPath}`,
+  };
+}
+
+function createPreviewSkillFile(
+  state: PreviewSkillsState,
+  skillSlug: string,
+  relPath: string
+): void {
+  const tree = getPreviewLocalSkillTree(state, skillSlug);
+  const normalizedPath = normalizeSkillPath(relPath, ".");
+  const existing = tree.get(normalizedPath);
+  if (existing) {
+    throw { code: "already_exists", message: "File already exists" };
+  }
+
+  ensurePreviewDirEntries(tree, parentSkillPath(normalizedPath));
+  tree.set(normalizedPath, { kind: "file", content: "" });
+  touchPreviewSkill(state, skillSlug);
+}
+
+function createPreviewSkillDirectory(
+  state: PreviewSkillsState,
+  skillSlug: string,
+  relPath: string
+): void {
+  const tree = getPreviewLocalSkillTree(state, skillSlug);
+  const normalizedPath = normalizeSkillPath(relPath, ".");
+  const existing = tree.get(normalizedPath);
+  if (existing) {
+    throw {
+      code: "already_exists",
+      message: existing.kind === "dir" ? "Directory already exists" : "File already exists",
+    };
+  }
+
+  ensurePreviewDirEntries(tree, normalizedPath);
+  touchPreviewSkill(state, skillSlug);
+}
+
+function renamePreviewSkillEntry(
+  state: PreviewSkillsState,
+  skillSlug: string,
+  fromRelPath: string,
+  toRelPath: string
+): void {
+  const tree = getPreviewLocalSkillTree(state, skillSlug);
+  const fromPath = normalizeSkillPath(fromRelPath, ".");
+  const toPath = normalizeSkillPath(toRelPath, ".");
+  const source = tree.get(fromPath);
+
+  if (!source) {
+    throw { code: "not_found", message: "Source not found" };
+  }
+
+  if (parentSkillPath(fromPath) !== parentSkillPath(toPath)) {
+    throw {
+      code: "rename_across_directories_not_supported",
+      message: "Rename must stay within the current directory",
+    };
+  }
+
+  if (tree.has(toPath)) {
+    throw { code: "already_exists", message: "Target already exists" };
+  }
+
+  const renamedEntries = [...tree.entries()].filter(
+    ([path]) => path === fromPath || path.startsWith(`${fromPath}/`)
+  );
+  const renamedPaths = new Set(renamedEntries.map(([path]) => path));
+
+  for (const [path] of renamedEntries) {
+    const nextPath = path === fromPath ? toPath : `${toPath}${path.slice(fromPath.length)}`;
+    const conflict = tree.get(nextPath);
+    if (conflict && !renamedPaths.has(nextPath)) {
+      throw { code: "already_exists", message: "Target already exists" };
+    }
+  }
+
+  for (const [path] of renamedEntries) {
+    tree.delete(path);
+  }
+
+  for (const [path, entry] of renamedEntries) {
+    const nextPath = path === fromPath ? toPath : `${toPath}${path.slice(fromPath.length)}`;
+    tree.set(
+      nextPath,
+      entry.kind === "dir" ? { kind: "dir" } : { kind: "file", content: entry.content }
+    );
+  }
+
+  touchPreviewSkill(state, skillSlug);
+}
+
+function deletePreviewSkillEntry(
+  state: PreviewSkillsState,
+  skillSlug: string,
+  relPath: string
+): void {
+  const tree = getPreviewLocalSkillTree(state, skillSlug);
+  const normalizedPath = normalizeSkillPath(relPath, ".");
+  if (!tree.has(normalizedPath)) {
+    throw { code: "not_found", message: "Target not found" };
+  }
+
+  for (const path of [...tree.keys()]) {
+    if (path === normalizedPath || path.startsWith(`${normalizedPath}/`)) {
+      tree.delete(path);
+    }
+  }
+
+  touchPreviewSkill(state, skillSlug);
+}
+
+function writePreviewSkillFile(
+  state: PreviewSkillsState,
+  skillSlug: string,
+  relPath: string,
+  content: string,
+  baseHash?: string
+): { newHash: string } {
+  const tree = getPreviewLocalSkillTree(state, skillSlug);
+  const normalizedPath = normalizeSkillPath(relPath, ".");
+  const node = tree.get(normalizedPath);
+  if (!node || node.kind !== "file") {
+    throw { code: "not_found", message: "File not found" };
+  }
+
+  const currentHash = previewHash(node.content);
+  if (baseHash && baseHash !== currentHash) {
+    throw {
+      code: "conflict",
+      message: "File has been modified externally",
+      details: {
+        expectedHash: baseHash,
+        actualHash: currentHash,
+      },
+    };
+  }
+
+  tree.set(normalizedPath, { kind: "file", content });
+  touchPreviewSkill(state, skillSlug);
+  return { newHash: previewHash(content) };
+}
+
+function buildPreviewLocalFileTree(
+  displayName: string,
+  slug: string,
+  entries?: Array<{ path: string; kind: "file" | "dir"; content?: string }>
+): Map<string, PreviewSkillFsEntry> {
+  const tree = new Map<string, PreviewSkillFsEntry>();
+  tree.set(".", { kind: "dir" });
+
+  for (const entry of entries ?? []) {
+    const normalizedPath = normalizeSkillPath(entry.path, ".");
+    if (normalizedPath === ".") {
+      continue;
+    }
+
+    if (entry.kind === "dir") {
+      ensurePreviewDirEntries(tree, normalizedPath);
+      continue;
+    }
+
+    ensurePreviewDirEntries(tree, parentSkillPath(normalizedPath));
+    tree.set(normalizedPath, { kind: "file", content: entry.content ?? "" });
+  }
+
+  if (!tree.has("SKILL.md")) {
+    tree.set("SKILL.md", {
+      kind: "file",
+      content: buildDefaultCustomSkillMarkdown(displayName, slug),
+    });
+  }
+
+  return tree;
+}
+
+function resolvePreviewLocalSkillRoot(
+  library: PreviewSkillLibraryItem[],
+  commands: UiPreviewCommands
+): string {
+  const localEntry = library.find((entry) => entry.source === "custom");
+  if (localEntry?.libraryPath) {
+    return parentSkillPath(localEntry.libraryPath.replace(/\\/g, "/"));
+  }
+
+  const seededPath = Object.keys(commands.skillsLocalFileEntriesBySlug ?? {})[0];
+  if (seededPath) {
+    return "/Users/spencer/.coder-studio/state/skills/custom";
+  }
+
+  return "/Users/spencer/.coder-studio/state/skills/custom";
+}
+
+function createPreviewSkillsState(commands: UiPreviewCommands = {}): PreviewSkillsState {
+  const library = (commands.skillsLibraryList ?? []).map(cloneSkillLibraryItem);
+  const healthScan = {
+    targets: (commands.skillsHealthScan?.targets ?? []).map(cloneSkillTarget),
+    mounts: (commands.skillsHealthScan?.mounts ?? []).map(cloneSkillMountRelation),
+  };
+  const infoBySlug = cloneSkillInfoMap(commands.skillsInfoBySlug);
+  const localSkillRoot = resolvePreviewLocalSkillRoot(library, commands);
+  const localFilesBySlug = new Map<string, Map<string, PreviewSkillFsEntry>>();
+
+  for (const entry of library) {
+    if (entry.source !== "custom") {
+      continue;
+    }
+
+    localFilesBySlug.set(
+      entry.slug,
+      buildPreviewLocalFileTree(
+        entry.displayName,
+        entry.slug,
+        commands.skillsLocalFileEntriesBySlug?.[entry.slug]
+      )
+    );
+  }
+
+  return {
+    library,
+    healthScan,
+    localFilesBySlug,
+    infoBySlug,
+    localSkillRoot,
+  };
+}
+
 function err(message: string) {
   return {
     ok: false as const,
@@ -267,6 +723,8 @@ function err(message: string) {
 }
 
 function createPreviewDispatcher(seed: UiPreviewSeed, store: Store): DispatchCommand {
+  const previewSkillsState = createPreviewSkillsState(seed.commands);
+
   return async <T>(op: string, args: unknown) => {
     const commands = seed.commands ?? {};
 
@@ -342,9 +800,20 @@ function createPreviewDispatcher(seed: UiPreviewSeed, store: Store): DispatchCom
       if (workspaceId && uiState?.paneLayout) {
         store.set(paneLayoutAtomFamily(workspaceId), uiState.paneLayout as PaneNode);
       }
-      return ok(
-        (commands.workspaceUiStateSet ?? commands.workspaceOpen ?? seed.workspaces?.[0]) as T
-      );
+      const fallbackWorkspace =
+        seed.workspaces?.find((workspace) => workspace.id === workspaceId) ?? seed.workspaces?.[0];
+      if (workspaceId && fallbackWorkspace && uiState) {
+        const nextWorkspace = {
+          ...fallbackWorkspace,
+          uiState,
+        };
+        store.set(workspacesAtom, {
+          ...store.get(workspacesAtom),
+          [workspaceId]: nextWorkspace,
+        });
+        return ok((commands.workspaceUiStateSet ?? nextWorkspace) as T);
+      }
+      return ok((commands.workspaceUiStateSet ?? commands.workspaceOpen ?? fallbackWorkspace) as T);
     }
 
     if (op === "session.list") {
@@ -514,19 +983,24 @@ function createPreviewDispatcher(seed: UiPreviewSeed, store: Store): DispatchCom
     }
 
     if (op === "skills.library.list") {
-      return ok((commands.skillsLibraryList ?? []) as unknown as T);
+      return ok(previewSkillsState.library.map(cloneSkillLibraryItem) as unknown as T);
     }
 
     if (op === "skills.health.scan") {
-      return ok((commands.skillsHealthScan ?? { targets: [], mounts: [] }) as unknown as T);
+      return ok({
+        targets: previewSkillsState.healthScan.targets.map(cloneSkillTarget),
+        mounts: previewSkillsState.healthScan.mounts.map(cloneSkillMountRelation),
+      } as unknown as T);
     }
 
     if (op === "skills.targets.list") {
-      return ok((commands.skillsHealthScan?.targets ?? []) as unknown as T);
+      return ok(previewSkillsState.healthScan.targets.map(cloneSkillTarget) as unknown as T);
     }
 
     if (op === "skills.recommend") {
-      return ok((commands.skillsRecommendations ?? []) as unknown as T);
+      return ok(
+        (commands.skillsRecommendations ?? { entries: [], hasMore: false }) as unknown as T
+      );
     }
 
     if (op === "skills.search") {
@@ -536,12 +1010,16 @@ function createPreviewDispatcher(seed: UiPreviewSeed, store: Store): DispatchCom
 
     if (op === "skills.info") {
       const slug = (args as { slug?: string })?.slug ?? "";
-      const configured = commands.skillsInfoBySlug?.[slug];
+      const configured = previewSkillsState.infoBySlug[slug];
       if (configured) {
-        return ok(configured as unknown as T);
+        return ok({
+          ...configured,
+          libraryEntry: configured.libraryEntry ? { ...configured.libraryEntry } : undefined,
+          mounts: configured.mounts.map(cloneSkillMountRelation),
+        } as unknown as T);
       }
 
-      const libraryEntry = commands.skillsLibraryList?.find((skill) => skill.slug === slug);
+      const libraryEntry = previewSkillsState.library.find((skill) => skill.slug === slug);
       if (libraryEntry) {
         return ok({
           slug: libraryEntry.slug,
@@ -549,15 +1027,122 @@ function createPreviewDispatcher(seed: UiPreviewSeed, store: Store): DispatchCom
           description: libraryEntry.description,
           version: libraryEntry.version,
           installed: libraryEntry.installState === "installed",
-          libraryEntry,
+          libraryEntry: { ...libraryEntry },
           mounts:
-            commands.skillsHealthScan?.mounts.filter((mount) => mount.skillSlug === slug) ?? [],
+            previewSkillsState.healthScan.mounts
+              .filter((mount) => mount.skillSlug === slug)
+              .map(cloneSkillMountRelation) ?? [],
         } as unknown as T);
       }
 
       return err(`Missing preview skill info for ${slug}`);
     }
 
+    if (op === "skills.custom.create") {
+      const displayName = (args as { name?: string })?.name?.trim() ?? "";
+      const slug = slugifyPreviewSkillName(displayName);
+
+      if (!slug) {
+        throw { code: "invalid_skill_name", message: "Skill name must produce a valid slug" };
+      }
+
+      if (previewSkillsState.library.some((entry) => entry.slug === slug)) {
+        throw { code: "already_exists", message: "Skill already exists" };
+      }
+
+      const now = Date.now();
+      const entry: PreviewSkillLibraryItem = {
+        slug,
+        displayName,
+        description: "Custom skill",
+        version: "local",
+        source: "custom",
+        origin: "filesystem",
+        libraryPath: `${previewSkillsState.localSkillRoot}/${slug}`,
+        installState: "installed",
+        installedAt: now,
+        updatedAt: now,
+        mountedProviderIds: [],
+        mountStatus: "unmounted",
+        errorCount: 0,
+      };
+
+      previewSkillsState.library.push(entry);
+      previewSkillsState.localFilesBySlug.set(
+        slug,
+        buildPreviewLocalFileTree(displayName, slug, [
+          {
+            path: "SKILL.md",
+            kind: "file",
+            content: buildDefaultCustomSkillMarkdown(displayName, slug),
+          },
+        ])
+      );
+
+      return ok({ ...entry } as unknown as T);
+    }
+
+    if (op === "skills.files.readTree") {
+      const skillSlug = (args as { skillSlug?: string })?.skillSlug ?? "";
+      const path = normalizeSkillPath((args as { path?: string })?.path, ".");
+      const tree = getPreviewLocalSkillTree(previewSkillsState, skillSlug);
+      return ok({
+        path,
+        children: listPreviewSkillChildren(tree, path),
+      } as unknown as T);
+    }
+
+    if (op === "skills.files.read") {
+      const skillSlug = (args as { skillSlug?: string })?.skillSlug ?? "";
+      const path = (args as { path?: string })?.path ?? "";
+      return ok(readPreviewSkillFile(previewSkillsState, skillSlug, path) as unknown as T);
+    }
+
+    if (op === "skills.files.write") {
+      const skillSlug = (args as { skillSlug?: string })?.skillSlug ?? "";
+      const path = (args as { path?: string })?.path ?? "";
+      const content = (args as { content?: string })?.content ?? "";
+      const baseHash = (args as { baseHash?: string })?.baseHash;
+      return ok(
+        writePreviewSkillFile(
+          previewSkillsState,
+          skillSlug,
+          path,
+          content,
+          baseHash
+        ) as unknown as T
+      );
+    }
+
+    if (op === "skills.files.create") {
+      const skillSlug = (args as { skillSlug?: string })?.skillSlug ?? "";
+      const path = (args as { path?: string })?.path ?? "";
+      createPreviewSkillFile(previewSkillsState, skillSlug, path);
+      return ok({ ok: true } as unknown as T);
+    }
+
+    if (op === "skills.files.mkdir") {
+      const skillSlug = (args as { skillSlug?: string })?.skillSlug ?? "";
+      const path = (args as { path?: string })?.path ?? "";
+      createPreviewSkillDirectory(previewSkillsState, skillSlug, path);
+      return ok({ ok: true } as unknown as T);
+    }
+
+    if (op === "skills.files.rename") {
+      const skillSlug = (args as { skillSlug?: string })?.skillSlug ?? "";
+      const fromPath = (args as { fromPath?: string })?.fromPath ?? "";
+      const toPath = (args as { toPath?: string })?.toPath ?? "";
+      renamePreviewSkillEntry(previewSkillsState, skillSlug, fromPath, toPath);
+      return ok({ ok: true } as unknown as T);
+    }
+
+    if (op === "skills.files.delete") {
+      const skillSlug = (args as { skillSlug?: string })?.skillSlug ?? "";
+      const path = (args as { path?: string })?.path ?? "";
+      deletePreviewSkillEntry(previewSkillsState, skillSlug, path);
+      return ok({ ok: true } as unknown as T);
+    }
+
     if (op === "skills.versions.check") {
       return ok((commands.skillsVersionChecks ?? []) as unknown as T);
     }
diff --git a/packages/web/src/ui-preview/scene-metadata.test.ts b/packages/web/src/ui-preview/scene-metadata.test.ts
index a8e5731ff..4d21559e0 100644
--- a/packages/web/src/ui-preview/scene-metadata.test.ts
+++ b/packages/web/src/ui-preview/scene-metadata.test.ts
@@ -18,6 +18,7 @@ describe("ui preview scene metadata", () => {
   it("registers the desktop review scene ids", () => {
     expect(UI_PREVIEW_SCENE_METADATA.map((scene) => scene.id)).toEqual(
       expect.arrayContaining([
+        "workspace-custom-skills-review",
         "readme-desktop-hero",
         "readme-desktop-review",
         "readme-mobile-progress",
@@ -127,4 +128,18 @@ describe("ui preview scene metadata", () => {
     expect(mobileWorkspaceScene?.source).toBe("real-route");
     expect(mobileWorkspaceScene?.description.toLowerCase()).toContain("appearance");
   });
+
+  it("registers a dedicated custom skills workspace review scene", () => {
+    const scene = UI_PREVIEW_SCENE_METADATA.find(
+      (entry) => entry.id === "workspace-custom-skills-review"
+    );
+
+    expect(scene?.devices).toEqual(["desktop"]);
+    expect(scene?.themes).toEqual(["mint-dark"]);
+    expect(scene?.locales).toEqual(["en"]);
+    expect(scene?.capture?.selector).toBe(".workspace-page");
+    expect(scene?.description.toLowerCase()).toContain("custom skills");
+    expect(scene?.description.toLowerCase()).toContain("create");
+    expect(scene?.description.toLowerCase()).toContain("edit");
+  });
 });
diff --git a/packages/web/src/ui-preview/scene-metadata.ts b/packages/web/src/ui-preview/scene-metadata.ts
index 29cbc5af9..1bfdd7489 100644
--- a/packages/web/src/ui-preview/scene-metadata.ts
+++ b/packages/web/src/ui-preview/scene-metadata.ts
@@ -141,6 +141,18 @@ export const UI_PREVIEW_SCENE_METADATA: UiPreviewSceneMetadata[] = [
     locales: ["zh", "en"],
     capture: { selector: ".workspace-page" },
   },
+  {
+    id: "workspace-custom-skills-review",
+    title: "Workspace / Custom Skills Review",
+    category: "page",
+    source: "real-route",
+    description:
+      "Desktop workspace scene seeded with custom skills so the skills sidebar can be reviewed with real list, detail, create, and edit interactions.",
+    devices: ["desktop"],
+    themes: ["mint-dark"],
+    locales: ["en"],
+    capture: { selector: ".workspace-page" },
+  },
   {
     id: "workspace-mobile",
     title: "Workspace / Mobile",
diff --git a/packages/web/src/ui-preview/scenes/desktop-review-scenes.tsx b/packages/web/src/ui-preview/scenes/desktop-review-scenes.tsx
index 0d1bbc6a7..1aa5561e9 100644
--- a/packages/web/src/ui-preview/scenes/desktop-review-scenes.tsx
+++ b/packages/web/src/ui-preview/scenes/desktop-review-scenes.tsx
@@ -6,7 +6,7 @@ import type {
   WorktreeInfo,
 } from "@coder-studio/core";
 import { CommandPalette } from "../../features/command-palette";
-import { SettingsPage } from "../../features/settings";
+import { MoreFeaturesPage } from "../../features/more";
 import { TerminalPanel } from "../../features/terminal-panel";
 import { TopBar } from "../../features/topbar";
 import { FileTreePanel } from "../../features/workspace/views/shared/file-tree-panel";
@@ -392,7 +392,10 @@ export function createDesktopReviewScenes(): UiPreviewSceneDefinition[] {
       ),
     }),
     scene("settings-density-review", {
-      router: () => ({ initialEntries: ["/settings"], path: "/settings" }),
+      router: () => ({
+        initialEntries: ["/more/settings/general"],
+        path: "/more/settings/general",
+      }),
       seed: (context) => ({
         ...buildWorkspaceSeed(context),
         commands: {
@@ -414,10 +417,13 @@ export function createDesktopReviewScenes(): UiPreviewSceneDefinition[] {
           },
         },
       }),
-      render: () => <SettingsPage />,
+      render: () => <MoreFeaturesPage />,
     }),
     scene("settings-light-theme-review", {
-      router: () => ({ initialEntries: ["/settings"], path: "/settings" }),
+      router: () => ({
+        initialEntries: ["/more/settings/appearance"],
+        path: "/more/settings/appearance",
+      }),
       seed: (context) => ({
         ...buildWorkspaceSeed(context),
         commands: {
@@ -439,7 +445,7 @@ export function createDesktopReviewScenes(): UiPreviewSceneDefinition[] {
           },
         },
       }),
-      render: () => <SettingsPage />,
+      render: () => <MoreFeaturesPage />,
     }),
     scene("desktop-overlay-review", {
       router: () => ({ initialEntries: ["/workspace"], path: "/workspace" }),
diff --git a/packages/web/src/ui-preview/scenes/page-scenes.tsx b/packages/web/src/ui-preview/scenes/page-scenes.tsx
index 074f95c78..97006fda7 100644
--- a/packages/web/src/ui-preview/scenes/page-scenes.tsx
+++ b/packages/web/src/ui-preview/scenes/page-scenes.tsx
@@ -11,6 +11,7 @@ import {
 } from "@coder-studio/core";
 import { LoginPage } from "../../features/auth";
 import { SessionGatePage } from "../../features/auth/session-gate";
+import { MoreFeaturesPage } from "../../features/more";
 import { NotFoundPage } from "../../features/not-found";
 import { SettingsPage } from "../../features/settings";
 import { WelcomePage } from "../../features/welcome";
@@ -256,8 +257,9 @@ const previewSkillsLibrary = [
     displayName: "Frontend Design",
     description: "Design and verify production frontend UI changes in the workspace.",
     version: "1.4.0",
-    source: "skillhub" as const,
-    libraryPath: "/Users/spencer/.coder-studio/skills/frontend-design",
+    source: "installed" as const,
+    origin: "skillhub" as const,
+    libraryPath: "/Users/spencer/.coder-studio/state/skills/library/frontend-design",
     installState: "installed" as const,
     installedAt: 1715731200000,
     updatedAt: 1715731200000,
@@ -267,6 +269,138 @@ const previewSkillsLibrary = [
   },
 ];
 
+const previewCustomSkillsLibrary = [
+  {
+    slug: "review-ops-skill",
+    displayName: "Review Ops Skill",
+    description: "Run structured acceptance and rollout checks before shipping a change.",
+    version: "local",
+    source: "custom" as const,
+    origin: "filesystem" as const,
+    libraryPath: "/Users/spencer/.coder-studio/state/skills/custom/review-ops-skill",
+    installState: "installed" as const,
+    installedAt: 1715731200000,
+    updatedAt: 1715731200000,
+    mountedProviderIds: ["codex", "claude"],
+    mountStatus: "fully_mounted" as const,
+    errorCount: 0,
+  },
+  {
+    slug: "session-audit-helper",
+    displayName: "Session Audit Helper",
+    description: "Inspect long-running sessions and summarize follow-up actions for handoff.",
+    version: "local",
+    source: "custom" as const,
+    origin: "filesystem" as const,
+    libraryPath: "/Users/spencer/.coder-studio/state/skills/custom/session-audit-helper",
+    installState: "installed" as const,
+    installedAt: 1715731200000,
+    updatedAt: 1715731200000,
+    mountedProviderIds: ["codex"],
+    mountStatus: "partially_mounted" as const,
+    errorCount: 0,
+  },
+];
+
+const previewCustomSkillMounts = [
+  {
+    providerId: "codex",
+    skillSlug: "review-ops-skill",
+    enabled: true,
+    sourcePath: "/Users/spencer/.coder-studio/state/skills/custom/review-ops-skill",
+    targetPath: "/Users/spencer/.codex/skills/review-ops-skill",
+    mountModeResolved: "symlink" as const,
+    status: "mounted" as const,
+    lastSyncedAt: 1715731200000,
+  },
+  {
+    providerId: "claude",
+    skillSlug: "review-ops-skill",
+    enabled: true,
+    sourcePath: "/Users/spencer/.coder-studio/state/skills/custom/review-ops-skill",
+    targetPath: "/Users/spencer/.claude/skills/review-ops-skill",
+    mountModeResolved: "symlink" as const,
+    status: "mounted" as const,
+    lastSyncedAt: 1715731200000,
+  },
+  {
+    providerId: "codex",
+    skillSlug: "session-audit-helper",
+    enabled: true,
+    sourcePath: "/Users/spencer/.coder-studio/state/skills/custom/session-audit-helper",
+    targetPath: "/Users/spencer/.codex/skills/session-audit-helper",
+    mountModeResolved: "symlink" as const,
+    status: "mounted" as const,
+    lastSyncedAt: 1715731200000,
+  },
+];
+
+const previewCustomSkillFiles = {
+  "review-ops-skill": [
+    {
+      path: "SKILL.md",
+      kind: "file" as const,
+      content: [
+        "---",
+        "name: review-ops-skill",
+        "description: Acceptance and rollout reviewer",
+        "---",
+        "",
+        "# Review Ops Skill",
+        "",
+        "Use this skill to verify acceptance, rollout safety, and release readiness.",
+        "",
+        "- Review the changed files",
+        "- Verify tests and screenshots",
+        "- Summarize launch risks",
+        "",
+      ].join("\n"),
+    },
+    { path: "refs", kind: "dir" as const },
+    {
+      path: "refs/checklist.md",
+      kind: "file" as const,
+      content: [
+        "# Acceptance Checklist",
+        "",
+        "- Confirm core flow",
+        "- Capture screenshots",
+        "- Note residual risk",
+        "",
+      ].join("\n"),
+    },
+    { path: "templates", kind: "dir" as const },
+    {
+      path: "templates/report.md",
+      kind: "file" as const,
+      content: ["# Release Report", "", "## Summary", "", "- Pending", ""].join("\n"),
+    },
+  ],
+  "session-audit-helper": [
+    {
+      path: "SKILL.md",
+      kind: "file" as const,
+      content: [
+        "---",
+        "name: session-audit-helper",
+        "description: Session audit helper",
+        "---",
+        "",
+        "# Session Audit Helper",
+        "",
+        "Audit recent sessions and capture next steps.",
+        "",
+      ].join("\n"),
+    },
+    { path: "refs", kind: "dir" as const },
+    {
+      path: "refs/summary.md",
+      kind: "file" as const,
+      content: "# Summary\n",
+    },
+  ],
+};
+
 const fileTreeMap = new Map<string, FileNode[]>();
 fileTreeMap.set(".", [
   { name: "packages", path: "packages", kind: "dir" },
@@ -963,17 +1097,20 @@ function buildWorkspaceSeed(context: UiPreviewSceneContext, sessions: Session[]
         targets: previewSkillTargets,
         mounts: previewSkillMounts,
       },
-      skillsRecommendations: [
-        {
-          slug: "test-automation",
-          displayName: "Test Automation",
-          description: "Detect and run the most relevant project checks.",
-          reason: "This workspace has pnpm scripts for test, build, and lint.",
-          sourceQuery: "workspace scripts",
-          score: 0.88,
-          installed: false,
-        },
-      ],
+      skillsRecommendations: {
+        entries: [
+          {
+            slug: "test-automation",
+            displayName: "Test Automation",
+            description: "Detect and run the most relevant project checks.",
+            reason: "This workspace has pnpm scripts for test, build, and lint.",
+            sourceQuery: "workspace scripts",
+            score: 0.88,
+            installed: false,
+          },
+        ],
+        hasMore: false,
+      },
       skillsVersionChecks: [
         {
           slug: "frontend-design",
@@ -986,6 +1123,25 @@ function buildWorkspaceSeed(context: UiPreviewSceneContext, sessions: Session[]
   };
 }
 
+function buildWorkspaceCustomSkillsReviewSeed(context: UiPreviewSceneContext) {
+  const base = buildWorkspaceSeed(context);
+
+  return {
+    ...base,
+    commands: {
+      ...base.commands,
+      skillsLibraryList: [...previewCustomSkillsLibrary, ...previewSkillsLibrary],
+      skillsHealthScan: {
+        targets: previewSkillTargets,
+        mounts: [...previewCustomSkillMounts, ...previewSkillMounts],
+      },
+      skillsRecommendations: { entries: [], hasMore: false },
+      skillsLocalFileEntriesBySlug: previewCustomSkillFiles,
+      skillsVersionChecks: [],
+    },
+  };
+}
+
 function buildDraftPaneEditorReviewSeed(context: UiPreviewSceneContext) {
   const reviewWorkspace: Workspace = {
     ...workspace,
@@ -1308,32 +1464,47 @@ export function createPageScenes(): UiPreviewSceneDefinition[] {
       render: () => <WelcomePage />,
     }),
     scene("settings-general", {
-      router: () => ({ initialEntries: ["/settings"], path: "/settings" }),
+      router: () => ({
+        initialEntries: ["/more/settings/general"],
+        path: "/more/settings/general",
+      }),
       seed: (context) => buildSettingsSeed(context),
-      render: () => <SettingsPage />,
+      render: () => <MoreFeaturesPage />,
     }),
     scene("settings-appearance", {
-      router: () => ({ initialEntries: ["/settings"], path: "/settings" }),
+      router: () => ({
+        initialEntries: ["/more/settings/appearance"],
+        path: "/more/settings/appearance",
+      }),
       seed: (context) => buildSettingsSeed(context),
-      render: () => <SettingsPage />,
+      render: () => <MoreFeaturesPage />,
     }),
     scene("settings-providers", {
-      router: () => ({ initialEntries: ["/settings"], path: "/settings" }),
+      router: () => ({
+        initialEntries: ["/more/settings/providers"],
+        path: "/more/settings/providers",
+      }),
       seed: (context) => buildSettingsSeed(context),
-      render: () => <SettingsPage />,
+      render: () => <MoreFeaturesPage />,
     }),
     scene("settings-shortcuts", {
-      router: () => ({ initialEntries: ["/settings"], path: "/settings" }),
+      router: () => ({
+        initialEntries: ["/more/settings/shortcuts"],
+        path: "/more/settings/shortcuts",
+      }),
       seed: (context) => buildSettingsSeed(context),
-      render: () => <SettingsPage />,
+      render: () => <MoreFeaturesPage />,
     }),
     scene("settings-monitoring", {
-      router: () => ({ initialEntries: ["/settings?section=monitoring"], path: "/settings" }),
+      router: () => ({
+        initialEntries: ["/more/analysis/monitoring"],
+        path: "/more/analysis/monitoring",
+      }),
       seed: (context) => buildSettingsSeed(context),
-      render: () => <SettingsPage />,
+      render: () => <MoreFeaturesPage />,
     }),
     scene("settings-mobile-root", {
-      router: () => ({ initialEntries: ["/settings"], path: "/settings" }),
+      router: () => ({ initialEntries: ["/more/settings"], path: "/more/settings" }),
       seed: (context) => buildSettingsSeed({ ...context, device: "mobile" }),
       render: () => <SettingsPage />,
     }),
@@ -1359,6 +1530,15 @@ export function createPageScenes(): UiPreviewSceneDefinition[] {
         </WorkspaceRouteGate>
       ),
     }),
+    scene("workspace-custom-skills-review", {
+      router: () => ({ initialEntries: ["/workspace"], path: "/workspace" }),
+      seed: (context) => buildWorkspaceCustomSkillsReviewSeed(context),
+      render: () => (
+        <WorkspaceRouteGate>
+          <WorkspaceDesktopView />
+        </WorkspaceRouteGate>
+      ),
+    }),
     scene("workspace-mobile", {
       router: () => ({ initialEntries: ["/workspace"], path: "/workspace" }),
       seed: (context) => buildWorkspaceSeed(context),
diff --git a/packages/web/src/ui-preview/scenes/showcase-scenes.tsx b/packages/web/src/ui-preview/scenes/showcase-scenes.tsx
index 564bd3782..cc9b0e18b 100644
--- a/packages/web/src/ui-preview/scenes/showcase-scenes.tsx
+++ b/packages/web/src/ui-preview/scenes/showcase-scenes.tsx
@@ -937,9 +937,15 @@ function ReadmeMobileProgressWorkspace() {
       className="mobile-shell mobile-shell--stacked mobile-shell--motion-reduced"
       data-testid="mobile-shell"
     >
-      <MobileTopBar activeWorkspace={workspace} drawerOpen={false} onToggleDrawer={() => {}} />
+      <MobileTopBar
+        activeWorkspace={workspace}
+        drawerOpen={false}
+        onToggleDrawer={() => {}}
+        onOpenFiles={() => {}}
+        onOpenTerminal={() => {}}
+      />
       <main className="mobile-shell__viewport">
-        <div className="mobile-shell__content" style={{ gap: "12px", paddingBottom: "144px" }}>
+        <div className="mobile-shell__content" style={{ gap: "12px", paddingBottom: "88px" }}>
           <section className="mobile-shell__agent-stage" style={{ flex: "0 0 420px" }}>
             <SessionCard
               sessionId="session-readme-mobile"
@@ -960,9 +966,6 @@ function ReadmeMobileProgressWorkspace() {
         data-testid="mobile-bottom-stack"
         style={{ "--mobile-keyboard-inset": "0px" } as CSSProperties}
       >
-        <div className="mobile-dock-shell">
-          <MobileDock activeItem="agent" onSelectItem={() => {}} />
-        </div>
         <WorkspaceStatusBar workspaceId={workspace.id} gitState={readmeMobileGitState} />
       </div>
     </div>
@@ -1108,18 +1111,21 @@ function FooterUpdateRailPreviewShell({
       className={`${className} mobile-shell mobile-shell--stacked mobile-shell--motion-reduced`}
       data-testid="mobile-shell"
     >
-      <MobileTopBar activeWorkspace={workspace} drawerOpen={false} onToggleDrawer={() => {}} />
+      <MobileTopBar
+        activeWorkspace={workspace}
+        drawerOpen={false}
+        onToggleDrawer={() => {}}
+        onOpenFiles={() => {}}
+        onOpenTerminal={() => {}}
+      />
       <main className="mobile-shell__viewport">
-        <div className="mobile-shell__content" style={{ paddingBottom: "144px" }} />
+        <div className="mobile-shell__content" style={{ paddingBottom: "88px" }} />
       </main>
       <div
         className="mobile-shell__bottom-stack"
         data-testid="mobile-bottom-stack"
         style={{ "--mobile-keyboard-inset": "0px" } as CSSProperties}
       >
-        <div className="mobile-dock-shell">
-          <MobileDock activeItem="agent" onSelectItem={() => {}} />
-        </div>
         <WorkspaceStatusBar workspaceId={workspace.id} gitState={readmeDesktopGitStatus} />
       </div>
     </div>
@@ -1803,7 +1809,10 @@ export function createShowcaseScenes(): UiPreviewSceneDefinition[] {
       ),
     }),
     scene("provider-error-state", {
-      router: () => ({ initialEntries: ["/settings"], path: "/settings" }),
+      router: () => ({
+        initialEntries: ["/more/settings/providers"],
+        path: "/more/settings/providers",
+      }),
       seed: (context) => ({ ...context }),
       render: () => (
         <div className="settings-page">
diff --git a/packages/web/vite.config.ts b/packages/web/vite.config.ts
index e78b9755e..97c21f43e 100644
--- a/packages/web/vite.config.ts
+++ b/packages/web/vite.config.ts
@@ -31,7 +31,7 @@ export default defineConfig(({ command, isPreview }) => {
             proxy.on("error", (err) => {
               console.log("WS proxy error:", err);
             });
-            proxy.on("proxyReqWs", (proxyReq, req, socket) => {
+            proxy.on("proxyReqWs", (_proxyReq, req, _socket) => {
               console.log("WS proxy upgrade:", req.url);
             });
           },
@@ -45,14 +45,6 @@ export default defineConfig(({ command, isPreview }) => {
         "/api": {
           target: backendHttpTarget,
         },
-        "/api/dev-proxy": {
-          target: backendHttpTarget,
-        },
-        "/dev-browser/session": {
-          target: backendHttpTarget,
-          ws: true,
-          changeOrigin: true,
-        },
       },
     },
     build: {
@@ -79,6 +71,8 @@ export default defineConfig(({ command, isPreview }) => {
             ) {
               return "xterm";
             }
+
+            return undefined;
           },
         },
       },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a213f9774..d06e32c37 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -98,6 +98,9 @@ importers:
       markdown-it:
         specifier: ^14.1.0
         version: 14.1.1
+      mermaid:
+        specifier: ^11.15.0
+        version: 11.15.0
       mime-types:
         specifier: ^2.1.35
         version: 2.1.35
@@ -228,6 +231,9 @@ importers:
       markdown-it:
         specifier: ^14.1.0
         version: 14.1.1
+      mermaid:
+        specifier: ^11.15.0
+        version: 11.15.0
       mime-types:
         specifier: ^2.1.35
         version: 2.1.35
@@ -331,6 +337,9 @@ importers:
       lucide-react:
         specifier: ^1.14.0
         version: 1.14.0(react@19.2.5)
+      markdown-it:
+        specifier: ^14.1.0
+        version: 14.1.1
       monaco-editor:
         specifier: ^0.55.1
         version: 0.55.1
@@ -362,6 +371,9 @@ importers:
       '@testing-library/user-event':
         specifier: ^14.6.1
         version: 14.6.1(@testing-library/dom@10.4.1)
+      '@types/markdown-it':
+        specifier: ^14.1.2
+        version: 14.1.2
       '@types/react':
         specifier: ^19.2.14
         version: 19.2.14
@@ -389,6 +401,9 @@ packages:
   '@adobe/css-tools@4.4.4':
     resolution: {integrity: sha512-Elp+iwUx5rN5+Y8xLt5/GRoG20WGoDCQ/1Fb+1LiGtvwbDavuSk0jhD/eZdckHAuzcDzccnkv+rEjyWfRx18gg==}
 
+  '@antfu/install-pkg@1.1.0':
+    resolution: {integrity: sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==}
+
   '@asamuzakjp/css-color@5.1.11':
     resolution: {integrity: sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==}
     engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
@@ -473,6 +488,9 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@braintree/sanitize-url@7.1.2':
+    resolution: {integrity: sha512-jigsZK+sMF/cuiB7sERuo9V7N9jx+dhmHHnQyDSVdpZwVutaBu7WvNYqMDLSgFgfB30n452TP3vjDAvFC973mA==}
+
   '@bramus/specificity@2.4.2':
     resolution: {integrity: sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==}
     hasBin: true
@@ -538,6 +556,9 @@ packages:
   '@changesets/write@0.4.0':
     resolution: {integrity: sha512-CdTLvIOPiCNuH71pyDu3rA+Q0n65cmAbXnwWH84rKGiFumFzkmHNT8KHTMEchcxN+Kl8I54xGUhJ7l3E7X396Q==}
 
+  '@chevrotain/types@11.1.2':
+    resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
+
   '@csstools/color-helpers@6.0.2':
     resolution: {integrity: sha512-LMGQLS9EuADloEFkcTBR3BwV/CGHV7zyDxVRtVDTwdI2Ca4it0CCVTT9wCkxSgokjE5Ho41hEPgb8OEUwoXr6Q==}
     engines: {node: '>=20.19.0'}
@@ -958,6 +979,12 @@ packages:
   '@fontsource/noto-sans-sc@5.2.9':
     resolution: {integrity: sha512-bTUIWGBgJDpwi5qAr+x0/lcgv80IHTB9vl6s2f6EymZEa7qYV99yNRBZuKFT+SYDKVunZrjCEhWtpxqmbXWl5Q==}
 
+  '@iconify/types@2.0.0':
+    resolution: {integrity: sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==}
+
+  '@iconify/utils@3.1.3':
+    resolution: {integrity: sha512-LPKOXPn/zV+zis1oOfGWogaXVpqUybF3ZS6SCZIsz8vg0ivVp9+fVqyYB7xq0aiST/VhUQYGO1qo6uoYSiEJqw==}
+
   '@inquirer/external-editor@1.0.3':
     resolution: {integrity: sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==}
     engines: {node: '>=18'}
@@ -980,6 +1007,9 @@ packages:
   '@manypkg/get-packages@1.1.3':
     resolution: {integrity: sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==}
 
+  '@mermaid-js/parser@1.1.1':
+    resolution: {integrity: sha512-VuHdsYMK1bT6X2JbcAaWAhugTRvRBRyuZgd+c22swUeI9g/ntaxF7CY7dYarhZovofCbUNO0G7JesfmNtjYOCw==}
+
   '@napi-rs/wasm-runtime@1.1.4':
     resolution: {integrity: sha512-3NQNNgA1YSlJb/kMH1ildASP9HW7/7kYnRI2szWJaofaS1hWmbGI4H+d3+22aGzXXN9IJ+n+GiFVcGipJP18ow==}
     peerDependencies:
@@ -1191,30 +1221,108 @@ packages:
   '@types/chai@5.2.3':
     resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
 
+  '@types/d3-array@3.2.2':
+    resolution: {integrity: sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==}
+
+  '@types/d3-axis@3.0.6':
+    resolution: {integrity: sha512-pYeijfZuBd87T0hGn0FO1vQ/cgLk6E1ALJjfkC0oJ8cbwkZl3TpgS8bVBLZN+2jjGgg38epgxb2zmoGtSfvgMw==}
+
+  '@types/d3-brush@3.0.6':
+    resolution: {integrity: sha512-nH60IZNNxEcrh6L1ZSMNA28rj27ut/2ZmI3r96Zd+1jrZD++zD3LsMIjWlvg4AYrHn/Pqz4CF3veCxGjtbqt7A==}
+
+  '@types/d3-chord@3.0.6':
+    resolution: {integrity: sha512-LFYWWd8nwfwEmTZG9PfQxd17HbNPksHBiJHaKuY1XeqscXacsS2tyoo6OdRsjf+NQYeB6XrNL3a25E3gH69lcg==}
+
   '@types/d3-color@3.1.3':
     resolution: {integrity: sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A==}
 
+  '@types/d3-contour@3.0.6':
+    resolution: {integrity: sha512-BjzLgXGnCWjUSYGfH1cpdo41/hgdWETu4YxpezoztawmqsvCeep+8QGfiY6YbDvfgHz/DkjeIkkZVJavB4a3rg==}
+
+  '@types/d3-delaunay@6.0.4':
+    resolution: {integrity: sha512-ZMaSKu4THYCU6sV64Lhg6qjf1orxBthaC161plr5KuPHo3CNm8DTHiLw/5Eq2b6TsNP0W0iJrUOFscY6Q450Hw==}
+
+  '@types/d3-dispatch@3.0.7':
+    resolution: {integrity: sha512-5o9OIAdKkhN1QItV2oqaE5KMIiXAvDWBDPrD85e58Qlz1c1kI/J0NcqbEG88CoTwJrYe7ntUCVfeUl2UJKbWgA==}
+
   '@types/d3-drag@3.0.7':
     resolution: {integrity: sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ==}
 
+  '@types/d3-dsv@3.0.7':
+    resolution: {integrity: sha512-n6QBF9/+XASqcKK6waudgL0pf/S5XHPPI8APyMLLUHd8NqouBGLsU8MgtO7NINGtPBtk9Kko/W4ea0oAspwh9g==}
+
+  '@types/d3-ease@3.0.2':
+    resolution: {integrity: sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA==}
+
+  '@types/d3-fetch@3.0.7':
+    resolution: {integrity: sha512-fTAfNmxSb9SOWNB9IoG5c8Hg6R+AzUHDRlsXsDZsNp6sxAEOP0tkP3gKkNSO/qmHPoBFTxNrjDprVHDQDvo5aA==}
+
+  '@types/d3-force@3.0.10':
+    resolution: {integrity: sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw==}
+
+  '@types/d3-format@3.0.4':
+    resolution: {integrity: sha512-fALi2aI6shfg7vM5KiR1wNJnZ7r6UuggVqtDA+xiEdPZQwy/trcQaHnwShLuLdta2rTymCNpxYTiMZX/e09F4g==}
+
+  '@types/d3-geo@3.1.0':
+    resolution: {integrity: sha512-856sckF0oP/diXtS4jNsiQw/UuK5fQG8l/a9VVLeSouf1/PPbBE1i1W852zVwKwYCBkFJJB7nCFTbk6UMEXBOQ==}
+
+  '@types/d3-hierarchy@3.1.7':
+    resolution: {integrity: sha512-tJFtNoYBtRtkNysX1Xq4sxtjK8YgoWUNpIiUee0/jHGRwqvzYxkq0hGVbbOGSz+JgFxxRu4K8nb3YpG3CMARtg==}
+
   '@types/d3-interpolate@3.0.4':
     resolution: {integrity: sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA==}
 
+  '@types/d3-path@3.1.1':
+    resolution: {integrity: sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg==}
+
+  '@types/d3-polygon@3.0.2':
+    resolution: {integrity: sha512-ZuWOtMaHCkN9xoeEMr1ubW2nGWsp4nIql+OPQRstu4ypeZ+zk3YKqQT0CXVe/PYqrKpZAi+J9mTs05TKwjXSRA==}
+
+  '@types/d3-quadtree@3.0.6':
+    resolution: {integrity: sha512-oUzyO1/Zm6rsxKRHA1vH0NEDG58HrT5icx/azi9MF1TWdtttWl0UIUsjEQBBh+SIkrpd21ZjEv7ptxWys1ncsg==}
+
+  '@types/d3-random@3.0.3':
+    resolution: {integrity: sha512-Imagg1vJ3y76Y2ea0871wpabqp613+8/r0mCLEBfdtqC7xMSfj9idOnmBYyMoULfHePJyxMAw3nWhJxzc+LFwQ==}
+
+  '@types/d3-scale-chromatic@3.1.0':
+    resolution: {integrity: sha512-iWMJgwkK7yTRmWqRB5plb1kadXyQ5Sj8V/zYlFGMUBbIPKQScw+Dku9cAAMgJG+z5GYDoMjWGLVOvjghDEFnKQ==}
+
+  '@types/d3-scale@4.0.9':
+    resolution: {integrity: sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==}
+
   '@types/d3-selection@3.0.11':
     resolution: {integrity: sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w==}
 
+  '@types/d3-shape@3.1.8':
+    resolution: {integrity: sha512-lae0iWfcDeR7qt7rA88BNiqdvPS5pFVPpo5OfjElwNaT2yyekbM0C9vK+yqBqEmHr6lDkRnYNoTBYlAgJa7a4w==}
+
+  '@types/d3-time-format@4.0.3':
+    resolution: {integrity: sha512-5xg9rC+wWL8kdDj153qZcsJ0FWiFt0J5RB6LYUNZjwSnesfblqrI/bJ1wBdJ8OQfncgbJG5+2F+qfqnqyzYxyg==}
+
+  '@types/d3-time@3.0.4':
+    resolution: {integrity: sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==}
+
+  '@types/d3-timer@3.0.2':
+    resolution: {integrity: sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw==}
+
   '@types/d3-transition@3.0.9':
     resolution: {integrity: sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg==}
 
   '@types/d3-zoom@3.0.8':
     resolution: {integrity: sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw==}
 
+  '@types/d3@7.4.3':
+    resolution: {integrity: sha512-lZXZ9ckh5R8uiFVt8ogUNf+pIrK4EsWrx2Np75WvF/eTpJ0FMHNhjXk8CKEx/+gpHbNQyJWehbFaTvqmHWB3ww==}
+
   '@types/deep-eql@4.0.2':
     resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
 
   '@types/estree@1.0.8':
     resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
 
+  '@types/geojson@7946.0.16':
+    resolution: {integrity: sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg==}
+
   '@types/linkify-it@5.0.0':
     resolution: {integrity: sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q==}
 
@@ -1247,6 +1355,9 @@ packages:
   '@types/ws@8.18.1':
     resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
 
+  '@upsetjs/venn.js@2.0.0':
+    resolution: {integrity: sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw==}
+
   '@vitejs/plugin-react@6.0.1':
     resolution: {integrity: sha512-l9X/E3cDb+xY3SWzlG1MOGt2usfEHGMNIaegaUGFsLkb3RCn/k8/TOXBcab+OndDI4TBtktT8/9BwwW8Vi9KUQ==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -1503,6 +1614,14 @@ packages:
   commander@2.15.1:
     resolution: {integrity: sha512-VlfT9F3V0v+jr4yxPc5gg9s62/fIVWsd2Bk2iD435um1NlGMYdVCq+MjcXnhYq2icNOizHr1kK+5TI6H0Hy0ag==}
 
+  commander@7.2.0:
+    resolution: {integrity: sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==}
+    engines: {node: '>= 10'}
+
+  commander@8.3.0:
+    resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==}
+    engines: {node: '>= 12'}
+
   content-disposition@1.1.0:
     resolution: {integrity: sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==}
     engines: {node: '>=18'}
@@ -1520,6 +1639,12 @@ packages:
   core-util-is@1.0.3:
     resolution: {integrity: sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==}
 
+  cose-base@1.0.3:
+    resolution: {integrity: sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==}
+
+  cose-base@2.2.0:
+    resolution: {integrity: sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==}
+
   croner@4.1.97:
     resolution: {integrity: sha512-/f6gpQuxDaqXu+1kwQYSckUglPaOrHdbIlBAu0YuW8/Cdb45XwXYNUBXg3r/9Mo6n540Kn/smKcZWko5x99KrQ==}
 
@@ -1540,10 +1665,51 @@ packages:
   culvert@0.1.2:
     resolution: {integrity: sha512-yi1x3EAWKjQTreYWeSd98431AV+IEE0qoDyOoaHJ7KJ21gv6HtBXHVLX74opVSGqcR8/AbjJBHAHpcOy2bj5Gg==}
 
+  cytoscape-cose-bilkent@4.1.0:
+    resolution: {integrity: sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape-fcose@2.2.0:
+    resolution: {integrity: sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape@3.34.0:
+    resolution: {integrity: sha512-62rNSrioXw93uliKFBwjukeQyeWwH2PqDrTac31r2P6464u3AUvTk0xS4LVvT251g7IgkFunrI48ZEZGjywSOg==}
+    engines: {node: '>=0.10'}
+
+  d3-array@2.12.1:
+    resolution: {integrity: sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ==}
+
+  d3-array@3.2.4:
+    resolution: {integrity: sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==}
+    engines: {node: '>=12'}
+
+  d3-axis@3.0.0:
+    resolution: {integrity: sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==}
+    engines: {node: '>=12'}
+
+  d3-brush@3.0.0:
+    resolution: {integrity: sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==}
+    engines: {node: '>=12'}
+
+  d3-chord@3.0.1:
+    resolution: {integrity: sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==}
+    engines: {node: '>=12'}
+
   d3-color@3.1.0:
     resolution: {integrity: sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==}
     engines: {node: '>=12'}
 
+  d3-contour@4.0.2:
+    resolution: {integrity: sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==}
+    engines: {node: '>=12'}
+
+  d3-delaunay@6.0.4:
+    resolution: {integrity: sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==}
+    engines: {node: '>=12'}
+
   d3-dispatch@3.0.1:
     resolution: {integrity: sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==}
     engines: {node: '>=12'}
@@ -1552,18 +1718,88 @@ packages:
     resolution: {integrity: sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==}
     engines: {node: '>=12'}
 
+  d3-dsv@3.0.1:
+    resolution: {integrity: sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==}
+    engines: {node: '>=12'}
+    hasBin: true
+
   d3-ease@3.0.1:
     resolution: {integrity: sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==}
     engines: {node: '>=12'}
 
+  d3-fetch@3.0.1:
+    resolution: {integrity: sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==}
+    engines: {node: '>=12'}
+
+  d3-force@3.0.0:
+    resolution: {integrity: sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==}
+    engines: {node: '>=12'}
+
+  d3-format@3.1.2:
+    resolution: {integrity: sha512-AJDdYOdnyRDV5b6ArilzCPPwc1ejkHcoyFarqlPqT7zRYjhavcT3uSrqcMvsgh2CgoPbK3RCwyHaVyxYcP2Arg==}
+    engines: {node: '>=12'}
+
+  d3-geo@3.1.1:
+    resolution: {integrity: sha512-637ln3gXKXOwhalDzinUgY83KzNWZRKbYubaG+fGVuc/dxO64RRljtCTnf5ecMyE1RIdtqpkVcq0IbtU2S8j2Q==}
+    engines: {node: '>=12'}
+
+  d3-hierarchy@3.1.2:
+    resolution: {integrity: sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==}
+    engines: {node: '>=12'}
+
   d3-interpolate@3.0.1:
     resolution: {integrity: sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==}
     engines: {node: '>=12'}
 
+  d3-path@1.0.9:
+    resolution: {integrity: sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==}
+
+  d3-path@3.1.0:
+    resolution: {integrity: sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==}
+    engines: {node: '>=12'}
+
+  d3-polygon@3.0.1:
+    resolution: {integrity: sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==}
+    engines: {node: '>=12'}
+
+  d3-quadtree@3.0.1:
+    resolution: {integrity: sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==}
+    engines: {node: '>=12'}
+
+  d3-random@3.0.1:
+    resolution: {integrity: sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==}
+    engines: {node: '>=12'}
+
+  d3-sankey@0.12.3:
+    resolution: {integrity: sha512-nQhsBRmM19Ax5xEIPLMY9ZmJ/cDvd1BG3UVvt5h3WRxKg5zGRbvnteTyWAbzeSvlh3tW7ZEmq4VwR5mB3tutmQ==}
+
+  d3-scale-chromatic@3.1.0:
+    resolution: {integrity: sha512-A3s5PWiZ9YCXFye1o246KoscMWqf8BsD9eRiJ3He7C9OBaxKhAd5TFCdEx/7VbKtxxTsu//1mMJFrEt572cEyQ==}
+    engines: {node: '>=12'}
+
+  d3-scale@4.0.2:
+    resolution: {integrity: sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==}
+    engines: {node: '>=12'}
+
   d3-selection@3.0.0:
     resolution: {integrity: sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==}
     engines: {node: '>=12'}
 
+  d3-shape@1.3.7:
+    resolution: {integrity: sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw==}
+
+  d3-shape@3.2.0:
+    resolution: {integrity: sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==}
+    engines: {node: '>=12'}
+
+  d3-time-format@4.1.0:
+    resolution: {integrity: sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==}
+    engines: {node: '>=12'}
+
+  d3-time@3.1.0:
+    resolution: {integrity: sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==}
+    engines: {node: '>=12'}
+
   d3-timer@3.0.1:
     resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
     engines: {node: '>=12'}
@@ -1578,6 +1814,13 @@ packages:
     resolution: {integrity: sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==}
     engines: {node: '>=12'}
 
+  d3@7.9.0:
+    resolution: {integrity: sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA==}
+    engines: {node: '>=12'}
+
+  dagre-d3-es@7.0.14:
+    resolution: {integrity: sha512-P4rFMVq9ESWqmOgK+dlXvOtLwYg0i7u0HBGJER0LZDJT2VHIPAMZ/riPxqJceWMStH5+E61QxFra9kIS3AqdMg==}
+
   data-uri-to-buffer@6.0.2:
     resolution: {integrity: sha512-7hvf7/GW8e86rW0ptuwS3OcBGDjIi6SZva7hCyWC0yYry2cOPmLIjXAUHI6DK2HsnwJd9ifmt57i8eV2n4YNpw==}
     engines: {node: '>= 14'}
@@ -1595,6 +1838,9 @@ packages:
   dayjs@1.11.15:
     resolution: {integrity: sha512-MC+DfnSWiM9APs7fpiurHGCoeIx0Gdl6QZBy+5lu8MbYKN5FZEXqOgrundfibdfhGZ15o9hzmZ2xJjZnbvgKXQ==}
 
+  dayjs@1.11.21:
+    resolution: {integrity: sha512-98IT+HOahAisibz/yjKbzuOBwYcjJ7BCLPzARyHiyEBmRz4fatF+KPJszEHXsGYjUG234aH/cOjW1wwTbKUZlA==}
+
   debug@4.3.7:
     resolution: {integrity: sha512-Er2nc/H7RrMXZBFCEim6TCmMk02Z8vLC2Rbi1KEBggpo0fS6l0S1nnapwmIi3yW/+GOJap1Krg4w0Hg80oCqgQ==}
     engines: {node: '>=6.0'}
@@ -1620,6 +1866,9 @@ packages:
     resolution: {integrity: sha512-TllpMR/t0M5sqCXfj85i4XaAzxmS5tVA16dqvdkMwGmzI+dXLXnw3J+3Vdv7VKw+ThlTMboK6i9rnZ6Nntj5CQ==}
     engines: {node: '>= 14'}
 
+  delaunator@5.1.0:
+    resolution: {integrity: sha512-AGrQ4QSgssa1NGmWmLPqN5NY2KajF5MqxetNEO+o0n3ZwZZeTmt7bBnvzHWrmkZFxGgr4HdyFgelzgi06otLuQ==}
+
   delayed-stream@1.0.0:
     resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
     engines: {node: '>=0.4.0'}
@@ -1653,6 +1902,9 @@ packages:
   dompurify@3.2.7:
     resolution: {integrity: sha512-WhL/YuveyGXJaerVlMYGWhvQswa7myDG17P7Vu65EWC05o8vfeNbvNf4d/BOvH99+ZW+LlQsc1GDKMa1vNK6dw==}
 
+  dompurify@3.4.11:
+    resolution: {integrity: sha512-zhlUV12GsaRzMsf9q5M254YhA4+VuF0fG+QFqu6aYpoGlKtz+w8//jBcGVYBgQkR5GHjUomejY84AV+/uPbWdw==}
+
   dotenv@8.6.0:
     resolution: {integrity: sha512-IrPdXQsk2BbzvCBGBOTmmSH5SodmqZNt4ERAZDmW4CT+tL8VtvinqywuANaFu4bOMWki16nqf0e4oC0QIaDr/g==}
     engines: {node: '>=10'}
@@ -1707,6 +1959,9 @@ packages:
     resolution: {integrity: sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==}
     engines: {node: '>= 0.4'}
 
+  es-toolkit@1.48.1:
+    resolution: {integrity: sha512-wfnXlwd5I75eXRtdD2vuEs50xHHESECDsGD7yiQnfFVNoa5522NwXEbmgo98LfiukSQHs+mBM7/YG3qKJB9/mQ==}
+
   esbuild@0.27.7:
     resolution: {integrity: sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==}
     engines: {node: '>=18'}
@@ -1899,6 +2154,9 @@ packages:
   graceful-fs@4.2.11:
     resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
 
+  hachure-fill@0.5.2:
+    resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
+
   has-flag@4.0.0:
     resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
     engines: {node: '>=8'}
@@ -1943,6 +2201,10 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  iconv-lite@0.6.3:
+    resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
+    engines: {node: '>=0.10.0'}
+
   iconv-lite@0.7.2:
     resolution: {integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==}
     engines: {node: '>=0.10.0'}
@@ -1958,6 +2220,9 @@ packages:
     resolution: {integrity: sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==}
     engines: {node: '>= 4'}
 
+  import-meta-resolve@4.2.0:
+    resolution: {integrity: sha512-Iqv2fzaTQN28s/FwZAoFq0ZSs/7hMAHJVX+w8PZl3cY19Pxk6jFFalxQoIfW2826i/fDLXv8IiEZRIT0lDuWcg==}
+
   indent-string@4.0.0:
     resolution: {integrity: sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==}
     engines: {node: '>=8'}
@@ -1968,6 +2233,13 @@ packages:
   ini@1.3.8:
     resolution: {integrity: sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==}
 
+  internmap@1.0.1:
+    resolution: {integrity: sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==}
+
+  internmap@2.0.3:
+    resolution: {integrity: sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==}
+    engines: {node: '>=12'}
+
   ip-address@10.2.0:
     resolution: {integrity: sha512-/+S6j4E9AHvW9SWMSEY9Xfy66O5PWvVEJ08O0y5JGyEKQpojb0K0GKpz/v5HJ/G0vi3D2sjGK78119oXZeE0qA==}
     engines: {node: '>= 12'}
@@ -2076,6 +2348,19 @@ packages:
   jsonfile@4.0.0:
     resolution: {integrity: sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==}
 
+  katex@0.16.47:
+    resolution: {integrity: sha512-Eeo8Ys1doU1z+x8AZsPpQu+p/QcZBI5PeOo7QGQdy2x2m0MU/hYagBbGOmXwr5KVbEfVuWv9LpnQWeehogurjg==}
+    hasBin: true
+
+  khroma@2.1.0:
+    resolution: {integrity: sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw==}
+
+  layout-base@1.0.2:
+    resolution: {integrity: sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==}
+
+  layout-base@2.0.1:
+    resolution: {integrity: sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==}
+
   light-my-request@6.6.0:
     resolution: {integrity: sha512-CHYbu8RtboSIoVsHZ6Ye4cj4Aw/yg2oAFimlF7mNvfDV192LR7nDiKtSIfCuLT7KokPSTn/9kfVLm5OGN0A28A==}
 
@@ -2160,6 +2445,9 @@ packages:
     resolution: {integrity: sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==}
     engines: {node: '>=8'}
 
+  lodash-es@4.18.1:
+    resolution: {integrity: sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==}
+
   lodash.startcase@4.4.0:
     resolution: {integrity: sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==}
 
@@ -2195,6 +2483,11 @@ packages:
     engines: {node: '>= 18'}
     hasBin: true
 
+  marked@16.4.2:
+    resolution: {integrity: sha512-TI3V8YYWvkVf3KJe1dRkpnjs68JUPyEa5vjKrp1XEEJUAOaQc+Qj+L1qWbPd0SJuAdQkFU0h73sXXqwDYxsiDA==}
+    engines: {node: '>= 20'}
+    hasBin: true
+
   math-intrinsics@1.1.0:
     resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
     engines: {node: '>= 0.4'}
@@ -2209,6 +2502,9 @@ packages:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
 
+  mermaid@11.15.0:
+    resolution: {integrity: sha512-pTMbcf3rWdtLiYGpmoTjHEpeY8seiy6sR+9nD7LOs8KfUbHE4lOUAprTRqRAcWSQ6MQpdX+YEsxShtGsINtPtw==}
+
   micromatch@4.0.8:
     resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
     engines: {node: '>=8.6'}
@@ -2327,12 +2623,18 @@ packages:
   package-manager-detector@0.2.11:
     resolution: {integrity: sha512-BEnLolu+yuz22S56CU1SUKq3XC3PkwD5wv4ikR4MfGvnRVcmzXR9DwSlW2fEamyTPyXHomBJRzgapeuBvRNzJQ==}
 
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
+
   pako@0.2.9:
     resolution: {integrity: sha512-NUcwaKxUxWrZLpDG+z/xZaCgQITkA/Dv4V/T6bw7VON6l1Xz/VnrBqrYjZQ12TamKHzITTfOEIYUj48y2KXImA==}
 
   parse5@8.0.1:
     resolution: {integrity: sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==}
 
+  path-data-parser@0.1.0:
+    resolution: {integrity: sha512-NOnmBpt5Y2RWbuv0LMzsayp3lVylAHLPUTut412ZA3l+C4uw4ZVkQbjShYCQ8TCpUMdPapr4YjUqLYD6v68j+w==}
+
   path-exists@4.0.0:
     resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
     engines: {node: '>=8'}
@@ -2414,6 +2716,12 @@ packages:
     engines: {node: '>=18.0.0'}
     hasBin: true
 
+  points-on-curve@0.2.0:
+    resolution: {integrity: sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==}
+
+  points-on-path@0.2.1:
+    resolution: {integrity: sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==}
+
   postcss@8.5.13:
     resolution: {integrity: sha512-qif0+jGGZoLWdHey3UFHHWP0H7Gbmsk8T5VEqyYFbWqPr1XqvLGBbk/sl8V5exGmcYJklJOhOQq1pV9IcsiFag==}
     engines: {node: ^10 || ^12 || >=14}
@@ -2552,17 +2860,26 @@ packages:
   rfdc@1.4.1:
     resolution: {integrity: sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==}
 
+  robust-predicates@3.0.3:
+    resolution: {integrity: sha512-NS3levdsRIUOmiJ8FZWCP7LG3QpJyrs/TE0Zpf1yvZu8cAJJ6QMW92H1c7kWpdIHo8RvmLxN/o2JXTKHp74lUA==}
+
   rolldown@1.0.0-rc.17:
     resolution: {integrity: sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA==}
     engines: {node: ^20.19.0 || >=22.12.0}
     hasBin: true
 
+  roughjs@4.6.6:
+    resolution: {integrity: sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==}
+
   run-parallel@1.2.0:
     resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
 
   run-series@1.1.9:
     resolution: {integrity: sha512-Arc4hUN896vjkqCYrUXquBFtRZdv1PfLbTYP71efP6butxyQ0kWpiNJyAgsxscmQg1cqvHY32/UCBzXedTpU2g==}
 
+  rw@1.3.3:
+    resolution: {integrity: sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==}
+
   safe-buffer@5.1.2:
     resolution: {integrity: sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==}
 
@@ -2703,6 +3020,9 @@ packages:
     resolution: {integrity: sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw==}
     engines: {node: '>=14.16'}
 
+  stylis@4.4.0:
+    resolution: {integrity: sha512-5Z9ZpRzfuH6l/UAvCPAPUo3665Nk2wLaZU3x+TLHKVzIz33+sbJqbtrYoC3KD4/uVOr2Zp+L0LySezP9OHV9yA==}
+
   supports-color@7.2.0:
     resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
     engines: {node: '>=8'}
@@ -2772,6 +3092,10 @@ packages:
     resolution: {integrity: sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==}
     engines: {node: '>=20'}
 
+  ts-dedent@2.3.0:
+    resolution: {integrity: sha512-JfJeIHke7y2egdGGgRAvpCwYFUsHlM2gPcrVOxFkznt/4uzQ7HFmvE63iFHVLBJNDuyDOQgijDK/tXH/f6Msjg==}
+    engines: {node: '>=6.10'}
+
   tslib@2.3.0:
     resolution: {integrity: sha512-N82ooyxVNm6h1riLCoyS9e3fuJ3AMG2zIZs2Gd1ATcSFjSA23Q0fzjjZeh0jbJvWVDZ0cJT8yaNNaaXHzueNjg==}
 
@@ -3027,6 +3351,11 @@ snapshots:
 
   '@adobe/css-tools@4.4.4': {}
 
+  '@antfu/install-pkg@1.1.0':
+    dependencies:
+      package-manager-detector: 1.6.0
+      tinyexec: 1.1.2
+
   '@asamuzakjp/css-color@5.1.11':
     dependencies:
       '@asamuzakjp/generational-cache': 1.0.1
@@ -3092,6 +3421,8 @@ snapshots:
   '@biomejs/cli-win32-x64@2.4.14':
     optional: true
 
+  '@braintree/sanitize-url@7.1.2': {}
+
   '@bramus/specificity@2.4.2':
     dependencies:
       css-tree: 3.2.1
@@ -3254,6 +3585,8 @@ snapshots:
       human-id: 4.1.3
       prettier: 2.8.8
 
+  '@chevrotain/types@11.1.2': {}
+
   '@csstools/color-helpers@6.0.2': {}
 
   '@csstools/css-calc@3.2.0(@csstools/css-parser-algorithms@4.0.0(@csstools/css-tokenizer@4.0.0))(@csstools/css-tokenizer@4.0.0)':
@@ -3537,6 +3870,14 @@ snapshots:
 
   '@fontsource/noto-sans-sc@5.2.9': {}
 
+  '@iconify/types@2.0.0': {}
+
+  '@iconify/utils@3.1.3':
+    dependencies:
+      '@antfu/install-pkg': 1.1.0
+      '@iconify/types': 2.0.0
+      import-meta-resolve: 4.2.0
+
   '@inquirer/external-editor@1.0.3(@types/node@25.6.0)':
     dependencies:
       chardet: 2.1.1
@@ -3564,6 +3905,10 @@ snapshots:
       globby: 11.1.0
       read-yaml-file: 1.1.0
 
+  '@mermaid-js/parser@1.1.1':
+    dependencies:
+      '@chevrotain/types': 11.1.2
+
   '@napi-rs/wasm-runtime@1.1.4(@emnapi/core@1.10.0)(@emnapi/runtime@1.10.0)':
     dependencies:
       '@emnapi/core': 1.10.0
@@ -3741,18 +4086,81 @@ snapshots:
       '@types/deep-eql': 4.0.2
       assertion-error: 2.0.1
 
+  '@types/d3-array@3.2.2': {}
+
+  '@types/d3-axis@3.0.6':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-brush@3.0.6':
+    dependencies:
+      '@types/d3-selection': 3.0.11
+
+  '@types/d3-chord@3.0.6': {}
+
   '@types/d3-color@3.1.3': {}
 
+  '@types/d3-contour@3.0.6':
+    dependencies:
+      '@types/d3-array': 3.2.2
+      '@types/geojson': 7946.0.16
+
+  '@types/d3-delaunay@6.0.4': {}
+
+  '@types/d3-dispatch@3.0.7': {}
+
   '@types/d3-drag@3.0.7':
     dependencies:
       '@types/d3-selection': 3.0.11
 
+  '@types/d3-dsv@3.0.7': {}
+
+  '@types/d3-ease@3.0.2': {}
+
+  '@types/d3-fetch@3.0.7':
+    dependencies:
+      '@types/d3-dsv': 3.0.7
+
+  '@types/d3-force@3.0.10': {}
+
+  '@types/d3-format@3.0.4': {}
+
+  '@types/d3-geo@3.1.0':
+    dependencies:
+      '@types/geojson': 7946.0.16
+
+  '@types/d3-hierarchy@3.1.7': {}
+
   '@types/d3-interpolate@3.0.4':
     dependencies:
       '@types/d3-color': 3.1.3
 
+  '@types/d3-path@3.1.1': {}
+
+  '@types/d3-polygon@3.0.2': {}
+
+  '@types/d3-quadtree@3.0.6': {}
+
+  '@types/d3-random@3.0.3': {}
+
+  '@types/d3-scale-chromatic@3.1.0': {}
+
+  '@types/d3-scale@4.0.9':
+    dependencies:
+      '@types/d3-time': 3.0.4
+
   '@types/d3-selection@3.0.11': {}
 
+  '@types/d3-shape@3.1.8':
+    dependencies:
+      '@types/d3-path': 3.1.1
+
+  '@types/d3-time-format@4.0.3': {}
+
+  '@types/d3-time@3.0.4': {}
+
+  '@types/d3-timer@3.0.2': {}
+
   '@types/d3-transition@3.0.9':
     dependencies:
       '@types/d3-selection': 3.0.11
@@ -3762,10 +4170,45 @@ snapshots:
       '@types/d3-interpolate': 3.0.4
       '@types/d3-selection': 3.0.11
 
+  '@types/d3@7.4.3':
+    dependencies:
+      '@types/d3-array': 3.2.2
+      '@types/d3-axis': 3.0.6
+      '@types/d3-brush': 3.0.6
+      '@types/d3-chord': 3.0.6
+      '@types/d3-color': 3.1.3
+      '@types/d3-contour': 3.0.6
+      '@types/d3-delaunay': 6.0.4
+      '@types/d3-dispatch': 3.0.7
+      '@types/d3-drag': 3.0.7
+      '@types/d3-dsv': 3.0.7
+      '@types/d3-ease': 3.0.2
+      '@types/d3-fetch': 3.0.7
+      '@types/d3-force': 3.0.10
+      '@types/d3-format': 3.0.4
+      '@types/d3-geo': 3.1.0
+      '@types/d3-hierarchy': 3.1.7
+      '@types/d3-interpolate': 3.0.4
+      '@types/d3-path': 3.1.1
+      '@types/d3-polygon': 3.0.2
+      '@types/d3-quadtree': 3.0.6
+      '@types/d3-random': 3.0.3
+      '@types/d3-scale': 4.0.9
+      '@types/d3-scale-chromatic': 3.1.0
+      '@types/d3-selection': 3.0.11
+      '@types/d3-shape': 3.1.8
+      '@types/d3-time': 3.0.4
+      '@types/d3-time-format': 4.0.3
+      '@types/d3-timer': 3.0.2
+      '@types/d3-transition': 3.0.9
+      '@types/d3-zoom': 3.0.8
+
   '@types/deep-eql@4.0.2': {}
 
   '@types/estree@1.0.8': {}
 
+  '@types/geojson@7946.0.16': {}
+
   '@types/linkify-it@5.0.0': {}
 
   '@types/markdown-it@14.1.2':
@@ -3798,6 +4241,11 @@ snapshots:
     dependencies:
       '@types/node': 25.6.0
 
+  '@upsetjs/venn.js@2.0.0':
+    optionalDependencies:
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
   '@vitejs/plugin-react@6.0.1(vite@8.0.10(@types/node@25.6.0)(esbuild@0.28.0)(tsx@4.21.0))':
     dependencies:
       '@rolldown/pluginutils': 1.0.0-rc.7
@@ -4041,6 +4489,10 @@ snapshots:
 
   commander@2.15.1: {}
 
+  commander@7.2.0: {}
+
+  commander@8.3.0: {}
+
   content-disposition@1.1.0: {}
 
   convert-source-map@2.0.0: {}
@@ -4051,6 +4503,14 @@ snapshots:
 
   core-util-is@1.0.3: {}
 
+  cose-base@1.0.3:
+    dependencies:
+      layout-base: 1.0.2
+
+  cose-base@2.2.0:
+    dependencies:
+      layout-base: 2.0.1
+
   croner@4.1.97: {}
 
   cross-spawn@7.0.6:
@@ -4070,8 +4530,50 @@ snapshots:
 
   culvert@0.1.2: {}
 
+  cytoscape-cose-bilkent@4.1.0(cytoscape@3.34.0):
+    dependencies:
+      cose-base: 1.0.3
+      cytoscape: 3.34.0
+
+  cytoscape-fcose@2.2.0(cytoscape@3.34.0):
+    dependencies:
+      cose-base: 2.2.0
+      cytoscape: 3.34.0
+
+  cytoscape@3.34.0: {}
+
+  d3-array@2.12.1:
+    dependencies:
+      internmap: 1.0.1
+
+  d3-array@3.2.4:
+    dependencies:
+      internmap: 2.0.3
+
+  d3-axis@3.0.0: {}
+
+  d3-brush@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  d3-chord@3.0.1:
+    dependencies:
+      d3-path: 3.1.0
+
   d3-color@3.1.0: {}
 
+  d3-contour@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-delaunay@6.0.4:
+    dependencies:
+      delaunator: 5.1.0
+
   d3-dispatch@3.0.1: {}
 
   d3-drag@3.0.0:
@@ -4079,14 +4581,82 @@ snapshots:
       d3-dispatch: 3.0.1
       d3-selection: 3.0.0
 
+  d3-dsv@3.0.1:
+    dependencies:
+      commander: 7.2.0
+      iconv-lite: 0.6.3
+      rw: 1.3.3
+
   d3-ease@3.0.1: {}
 
+  d3-fetch@3.0.1:
+    dependencies:
+      d3-dsv: 3.0.1
+
+  d3-force@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-timer: 3.0.1
+
+  d3-format@3.1.2: {}
+
+  d3-geo@3.1.1:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-hierarchy@3.1.2: {}
+
   d3-interpolate@3.0.1:
     dependencies:
       d3-color: 3.1.0
 
+  d3-path@1.0.9: {}
+
+  d3-path@3.1.0: {}
+
+  d3-polygon@3.0.1: {}
+
+  d3-quadtree@3.0.1: {}
+
+  d3-random@3.0.1: {}
+
+  d3-sankey@0.12.3:
+    dependencies:
+      d3-array: 2.12.1
+      d3-shape: 1.3.7
+
+  d3-scale-chromatic@3.1.0:
+    dependencies:
+      d3-color: 3.1.0
+      d3-interpolate: 3.0.1
+
+  d3-scale@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+      d3-format: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+
   d3-selection@3.0.0: {}
 
+  d3-shape@1.3.7:
+    dependencies:
+      d3-path: 1.0.9
+
+  d3-shape@3.2.0:
+    dependencies:
+      d3-path: 3.1.0
+
+  d3-time-format@4.1.0:
+    dependencies:
+      d3-time: 3.1.0
+
+  d3-time@3.1.0:
+    dependencies:
+      d3-array: 3.2.4
+
   d3-timer@3.0.1: {}
 
   d3-transition@3.0.1(d3-selection@3.0.0):
@@ -4106,6 +4676,44 @@ snapshots:
       d3-selection: 3.0.0
       d3-transition: 3.0.1(d3-selection@3.0.0)
 
+  d3@7.9.0:
+    dependencies:
+      d3-array: 3.2.4
+      d3-axis: 3.0.0
+      d3-brush: 3.0.0
+      d3-chord: 3.0.1
+      d3-color: 3.1.0
+      d3-contour: 4.0.2
+      d3-delaunay: 6.0.4
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-dsv: 3.0.1
+      d3-ease: 3.0.1
+      d3-fetch: 3.0.1
+      d3-force: 3.0.0
+      d3-format: 3.1.2
+      d3-geo: 3.1.1
+      d3-hierarchy: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-path: 3.1.0
+      d3-polygon: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-random: 3.0.1
+      d3-scale: 4.0.2
+      d3-scale-chromatic: 3.1.0
+      d3-selection: 3.0.0
+      d3-shape: 3.2.0
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+      d3-timer: 3.0.1
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+      d3-zoom: 3.0.0
+
+  dagre-d3-es@7.0.14:
+    dependencies:
+      d3: 7.9.0
+      lodash-es: 4.18.1
+
   data-uri-to-buffer@6.0.2: {}
 
   data-urls@7.0.0:
@@ -4121,6 +4729,8 @@ snapshots:
 
   dayjs@1.11.15: {}
 
+  dayjs@1.11.21: {}
+
   debug@4.3.7:
     dependencies:
       ms: 2.1.3
@@ -4137,6 +4747,10 @@ snapshots:
       escodegen: 2.1.0
       esprima: 4.0.1
 
+  delaunator@5.1.0:
+    dependencies:
+      robust-predicates: 3.0.3
+
   delayed-stream@1.0.0: {}
 
   depd@2.0.0: {}
@@ -4159,6 +4773,10 @@ snapshots:
     optionalDependencies:
       '@types/trusted-types': 2.0.7
 
+  dompurify@3.4.11:
+    optionalDependencies:
+      '@types/trusted-types': 2.0.7
+
   dotenv@8.6.0: {}
 
   dunder-proto@1.0.1:
@@ -4218,6 +4836,8 @@ snapshots:
       has-tostringtag: 1.0.2
       hasown: 2.0.3
 
+  es-toolkit@1.48.1: {}
+
   esbuild@0.27.7:
     optionalDependencies:
       '@esbuild/aix-ppc64': 0.27.7
@@ -4479,6 +5099,8 @@ snapshots:
 
   graceful-fs@4.2.11: {}
 
+  hachure-fill@0.5.2: {}
+
   has-flag@4.0.0: {}
 
   has-symbols@1.1.0: {}
@@ -4525,6 +5147,10 @@ snapshots:
 
   husky@9.1.7: {}
 
+  iconv-lite@0.6.3:
+    dependencies:
+      safer-buffer: 2.1.2
+
   iconv-lite@0.7.2:
     dependencies:
       safer-buffer: 2.1.2
@@ -4535,12 +5161,18 @@ snapshots:
 
   ignore@7.0.5: {}
 
+  import-meta-resolve@4.2.0: {}
+
   indent-string@4.0.0: {}
 
   inherits@2.0.4: {}
 
   ini@1.3.8: {}
 
+  internmap@1.0.1: {}
+
+  internmap@2.0.3: {}
+
   ip-address@10.2.0: {}
 
   ipaddr.js@2.4.0: {}
@@ -4639,6 +5271,16 @@ snapshots:
     optionalDependencies:
       graceful-fs: 4.2.11
 
+  katex@0.16.47:
+    dependencies:
+      commander: 8.3.0
+
+  khroma@2.1.0: {}
+
+  layout-base@1.0.2: {}
+
+  layout-base@2.0.1: {}
+
   light-my-request@6.6.0:
     dependencies:
       cookie: 1.1.1
@@ -4702,6 +5344,8 @@ snapshots:
     dependencies:
       p-locate: 4.1.0
 
+  lodash-es@4.18.1: {}
+
   lodash.startcase@4.4.0: {}
 
   lodash@4.18.1: {}
@@ -4731,6 +5375,8 @@ snapshots:
 
   marked@14.0.0: {}
 
+  marked@16.4.2: {}
+
   math-intrinsics@1.1.0: {}
 
   mdn-data@2.27.1: {}
@@ -4739,6 +5385,30 @@ snapshots:
 
   merge2@1.4.1: {}
 
+  mermaid@11.15.0:
+    dependencies:
+      '@braintree/sanitize-url': 7.1.2
+      '@iconify/utils': 3.1.3
+      '@mermaid-js/parser': 1.1.1
+      '@types/d3': 7.4.3
+      '@upsetjs/venn.js': 2.0.0
+      cytoscape: 3.34.0
+      cytoscape-cose-bilkent: 4.1.0(cytoscape@3.34.0)
+      cytoscape-fcose: 2.2.0(cytoscape@3.34.0)
+      d3: 7.9.0
+      d3-sankey: 0.12.3
+      dagre-d3-es: 7.0.14
+      dayjs: 1.11.21
+      dompurify: 3.4.11
+      es-toolkit: 1.48.1
+      katex: 0.16.47
+      khroma: 2.1.0
+      marked: 16.4.2
+      roughjs: 4.6.6
+      stylis: 4.4.0
+      ts-dedent: 2.3.0
+      uuid: 14.0.0
+
   micromatch@4.0.8:
     dependencies:
       braces: 3.0.3
@@ -4837,12 +5507,16 @@ snapshots:
     dependencies:
       quansync: 0.2.11
 
+  package-manager-detector@1.6.0: {}
+
   pako@0.2.9: {}
 
   parse5@8.0.1:
     dependencies:
       entities: 8.0.0
 
+  path-data-parser@0.1.0: {}
+
   path-exists@4.0.0: {}
 
   path-key@3.1.1: {}
@@ -4970,6 +5644,13 @@ snapshots:
       - supports-color
       - utf-8-validate
 
+  points-on-curve@0.2.0: {}
+
+  points-on-path@0.2.1:
+    dependencies:
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+
   postcss@8.5.13:
     dependencies:
       nanoid: 3.3.12
@@ -5107,6 +5788,8 @@ snapshots:
 
   rfdc@1.4.1: {}
 
+  robust-predicates@3.0.3: {}
+
   rolldown@1.0.0-rc.17:
     dependencies:
       '@oxc-project/types': 0.127.0
@@ -5128,12 +5811,21 @@ snapshots:
       '@rolldown/binding-win32-arm64-msvc': 1.0.0-rc.17
       '@rolldown/binding-win32-x64-msvc': 1.0.0-rc.17
 
+  roughjs@4.6.6:
+    dependencies:
+      hachure-fill: 0.5.2
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+      points-on-path: 0.2.1
+
   run-parallel@1.2.0:
     dependencies:
       queue-microtask: 1.2.3
 
   run-series@1.1.9: {}
 
+  rw@1.3.3: {}
+
   safe-buffer@5.1.2: {}
 
   safe-buffer@5.2.1: {}
@@ -5241,6 +5933,8 @@ snapshots:
 
   strip-json-comments@5.0.3: {}
 
+  stylis@4.4.0: {}
+
   supports-color@7.2.0:
     dependencies:
       has-flag: 4.0.0
@@ -5296,6 +5990,8 @@ snapshots:
     dependencies:
       punycode: 2.3.1
 
+  ts-dedent@2.3.0: {}
+
   tslib@2.3.0: {}
 
   tslib@2.8.1: {}
diff --git a/scripts/build-cli.test.ts b/scripts/build-cli.test.ts
index 033199fe8..fc16a8df0 100644
--- a/scripts/build-cli.test.ts
+++ b/scripts/build-cli.test.ts
@@ -54,4 +54,10 @@ describe("build-cli", () => {
       "@coder-studio/core/state-paths": resolve(CORE_DIR, "src/state-paths.ts"),
     });
   });
+
+  it("emits the automation entry as an ESM build output", async () => {
+    const buildOptions = await createCliBuildOptions("esm");
+
+    expect(buildOptions.entryPoints).toContain(resolve(CLI_DIR, "src/automation-entry.ts"));
+  });
 });
diff --git a/scripts/dev-server.test.ts b/scripts/dev-server.test.ts
new file mode 100644
index 000000000..c3141d1b7
--- /dev/null
+++ b/scripts/dev-server.test.ts
@@ -0,0 +1,68 @@
+import type { ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const buildDevServerEnv = vi.fn(() => ({ PATH: "/tmp/dev-bin" }));
+const runBackground = vi.fn();
+
+vi.mock("./shared/index.js", () => ({
+  buildDevServerEnv,
+  CLI_DIR: "/repo/packages/cli",
+  error: vi.fn(),
+  info: vi.fn(),
+  log: vi.fn(),
+  ROOT_DIR: "/repo",
+  SERVER_DIR: "/repo/packages/server",
+  success: vi.fn(),
+}));
+
+vi.mock("./shared/process.js", () => ({
+  isDirectExecution: vi.fn(() => false),
+  runBackground,
+}));
+
+function createChildProcess() {
+  const child = new EventEmitter() as ChildProcess;
+  child.kill = vi.fn(() => true) as unknown as ChildProcess["kill"];
+  return child;
+}
+
+describe("dev-server", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.resetModules();
+    runBackground.mockReset();
+  });
+
+  it("exits with the backend watch child status when it closes", async () => {
+    const child = createChildProcess();
+    runBackground.mockReturnValue(child);
+    const exit = vi.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit called");
+    }) as never);
+    const { devServer } = await import("./dev-server.js");
+
+    await devServer();
+    expect(() => child.emit("close", 7, null)).toThrow("process.exit called");
+
+    expect(exit).toHaveBeenCalledWith(7);
+  });
+
+  it("forces development NODE_ENV for the backend watch child", async () => {
+    const child = createChildProcess();
+    runBackground.mockReturnValue(child);
+    const { devServer } = await import("./dev-server.js");
+
+    await devServer();
+
+    expect(buildDevServerEnv).toHaveBeenCalledWith({
+      rootDir: "/repo",
+      cliDir: "/repo/packages/cli",
+      env: expect.objectContaining({
+        NODE_ENV: "development",
+        HOST: "127.0.0.1",
+        PORT: "4173",
+      }),
+    });
+  });
+});
diff --git a/scripts/dev-server.ts b/scripts/dev-server.ts
index faa923d0e..04a5552f9 100644
--- a/scripts/dev-server.ts
+++ b/scripts/dev-server.ts
@@ -3,7 +3,16 @@
  * Starts tsx watch for backend
  */
 
-import { error, info, log, SERVER_DIR, success } from "./shared/index.js";
+import {
+  buildDevServerEnv,
+  CLI_DIR,
+  error,
+  info,
+  log,
+  ROOT_DIR,
+  SERVER_DIR,
+  success,
+} from "./shared/index.js";
 import { isDirectExecution, runBackground } from "./shared/process.js";
 
 const SERVER_PORT = 4173;
@@ -12,21 +21,38 @@ const SERVER_HOST = "127.0.0.1";
 async function devServer(): Promise<void> {
   info("Starting tsx watch for backend...");
 
-  const serverProcess = runBackground("pnpm", ["tsx", "watch", "src/server.ts"], {
-    cwd: SERVER_DIR,
-    stdio: "inherit",
+  const serverEnv = buildDevServerEnv({
+    rootDir: ROOT_DIR,
+    cliDir: CLI_DIR,
     env: {
       ...process.env,
+      NODE_ENV: "development",
       HOST: SERVER_HOST,
       PORT: String(SERVER_PORT),
     },
   });
 
+  const serverProcess = runBackground("pnpm", ["tsx", "watch", "src/server.ts"], {
+    cwd: SERVER_DIR,
+    stdio: "inherit",
+    env: serverEnv,
+  });
+
   serverProcess.on("error", (err) => {
     error(`Server process failed: ${err.message}`);
     process.exit(1);
   });
 
+  serverProcess.on("close", (code, signal) => {
+    const exitCode = typeof code === "number" ? code : signal ? 1 : 0;
+    if (exitCode !== 0) {
+      error(
+        `Server process exited with ${typeof code === "number" ? `code ${code}` : `signal ${signal}`}`
+      );
+    }
+    process.exit(exitCode);
+  });
+
   success(`Backend dev server running at http://${SERVER_HOST}:${SERVER_PORT}`);
 
   // Handle process termination
diff --git a/scripts/dev.test.ts b/scripts/dev.test.ts
new file mode 100644
index 000000000..101d6a426
--- /dev/null
+++ b/scripts/dev.test.ts
@@ -0,0 +1,61 @@
+import type { ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const buildDevServerEnv = vi.fn(() => ({ PATH: "/tmp/dev-bin" }));
+const runBackground = vi.fn();
+const waitForProcesses = vi.fn(() => Promise.resolve());
+
+vi.mock("./shared/index.js", () => ({
+  buildDevServerEnv,
+  CLI_DIR: "/repo/packages/cli",
+  error: vi.fn(),
+  info: vi.fn(),
+  log: vi.fn(),
+  ROOT_DIR: "/repo",
+  SERVER_DIR: "/repo/packages/server",
+  step: vi.fn(),
+  success: vi.fn(),
+  WEB_DIR: "/repo/packages/web",
+}));
+
+vi.mock("./shared/process.js", () => ({
+  isDirectExecution: vi.fn(() => false),
+  runBackground,
+  waitForProcesses,
+}));
+
+function createChildProcess() {
+  const child = new EventEmitter() as ChildProcess;
+  child.kill = vi.fn(() => true) as unknown as ChildProcess["kill"];
+  return child;
+}
+
+describe("dev", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.resetModules();
+    buildDevServerEnv.mockClear();
+    runBackground.mockReset();
+    waitForProcesses.mockClear();
+  });
+
+  it("forces development NODE_ENV for the backend watch child", async () => {
+    const viteChild = createChildProcess();
+    const serverChild = createChildProcess();
+    runBackground.mockReturnValueOnce(viteChild).mockReturnValueOnce(serverChild);
+    const { dev } = await import("./dev.js");
+
+    await dev();
+
+    expect(buildDevServerEnv).toHaveBeenCalledWith({
+      rootDir: "/repo",
+      cliDir: "/repo/packages/cli",
+      env: expect.objectContaining({
+        NODE_ENV: "development",
+        HOST: "127.0.0.1",
+        PORT: "4173",
+      }),
+    });
+  });
+});
diff --git a/scripts/dev.ts b/scripts/dev.ts
index 27cc89daa..981997deb 100644
--- a/scripts/dev.ts
+++ b/scripts/dev.ts
@@ -3,7 +3,18 @@
  * Runs both frontend and backend dev servers concurrently
  */
 
-import { error, info, log, SERVER_DIR, step, success, WEB_DIR } from "./shared/index.js";
+import {
+  buildDevServerEnv,
+  CLI_DIR,
+  error,
+  info,
+  log,
+  ROOT_DIR,
+  SERVER_DIR,
+  step,
+  success,
+  WEB_DIR,
+} from "./shared/index.js";
 import { isDirectExecution, runBackground, waitForProcesses } from "./shared/process.js";
 
 const VITE_PORT = 5173;
@@ -24,11 +35,16 @@ async function dev(): Promise<void> {
   const serverProcess = runBackground("pnpm", ["tsx", "watch", "src/server.ts"], {
     cwd: SERVER_DIR,
     stdio: "inherit",
-    env: {
-      ...process.env,
-      HOST: SERVER_HOST,
-      PORT: String(SERVER_PORT),
-    },
+    env: buildDevServerEnv({
+      rootDir: ROOT_DIR,
+      cliDir: CLI_DIR,
+      env: {
+        ...process.env,
+        NODE_ENV: "development",
+        HOST: SERVER_HOST,
+        PORT: String(SERVER_PORT),
+      },
+    }),
   });
 
   const processes = [viteProcess, serverProcess];
diff --git a/scripts/publish-cli.test.ts b/scripts/publish-cli.test.ts
index fd010f848..9b6d8d9ef 100644
--- a/scripts/publish-cli.test.ts
+++ b/scripts/publish-cli.test.ts
@@ -93,7 +93,6 @@ describe("publish-cli", () => {
     await writeFile(join(cliDir, "dist", "esm", "index.mjs"), "export {};\n");
     await writeFile(join(cliDir, "dist", "esm", "server-runner.mjs"), "export {};\n");
     await writeFile(join(cliDir, "dist", "web", "index.html"), "<!doctype html>\n");
-    await writeFile(join(cliDir, "dist", "web", "dev-browser-sw.js"), "self.skipWaiting();\n");
     await writeFile(
       join(cliDir, "package.json"),
       JSON.stringify({
@@ -140,7 +139,6 @@ describe("publish-cli", () => {
     await writeFile(join(cliDir, "dist", "esm", "index.mjs"), "export {};\n");
     await writeFile(join(cliDir, "dist", "esm", "server-runner.mjs"), "export {};\n");
     await writeFile(join(cliDir, "dist", "web", "index.html"), "<!doctype html>\n");
-    await writeFile(join(cliDir, "dist", "web", "dev-browser-sw.js"), "self.skipWaiting();\n");
     await writeFile(
       join(cliDir, "package.json"),
       JSON.stringify({
@@ -179,7 +177,6 @@ describe("publish-cli", () => {
     await writeFile(join(cliDir, "dist", "esm", "index.mjs"), "export {};\n");
     await writeFile(join(cliDir, "dist", "esm", "server-runner.mjs"), "export {};\n");
     await writeFile(join(cliDir, "dist", "web", "index.html"), "<!doctype html>\n");
-    await writeFile(join(cliDir, "dist", "web", "dev-browser-sw.js"), "self.skipWaiting();\n");
     await writeFile(
       join(cliDir, "package.json"),
       JSON.stringify({
@@ -212,46 +209,6 @@ describe("publish-cli", () => {
     );
   });
 
-  it("requires the dev browser service worker in the published web assets", async () => {
-    const dir = await mkdtemp(join(tmpdir(), "coder-studio-publish-"));
-    const cliDir = join(dir, "packages", "cli");
-
-    await mkdir(join(cliDir, "dist", "esm"), { recursive: true });
-    await mkdir(join(cliDir, "dist", "web"), { recursive: true });
-    await writeFile(join(cliDir, "dist", "bin.js"), "#!/usr/bin/env node\n");
-    await writeFile(join(cliDir, "dist", "esm", "bin.mjs"), "export {};\n");
-    await writeFile(join(cliDir, "dist", "esm", "index.mjs"), "export {};\n");
-    await writeFile(join(cliDir, "dist", "esm", "server-runner.mjs"), "export {};\n");
-    await writeFile(join(cliDir, "dist", "web", "index.html"), "<!doctype html>\n");
-    await writeFile(
-      join(cliDir, "package.json"),
-      JSON.stringify({
-        name: "@spencer-kit/coder-studio",
-        version: "1.2.3",
-        bin: { "coder-studio": "./src/bin.ts" },
-        files: ["dist"],
-        publishConfig: {
-          bin: { "coder-studio": "./dist/bin.js" },
-          exports: {
-            ".": {
-              import: "./dist/esm/index.mjs",
-            },
-          },
-        },
-        exports: {
-          ".": {
-            import: "./src/index.ts",
-          },
-        },
-        dependencies: {
-          "@xterm/addon-serialize": "^0.14.0",
-        },
-      })
-    );
-
-    await expect(assertCliPublishArtifacts(cliDir)).rejects.toThrow("dist/web/dev-browser-sw.js");
-  });
-
   it("rejects a real publish from a dirty worktree unless explicitly allowed", async () => {
     const exec = vi.fn(async () => ({ stdout: " M package.json\n" }));
 
diff --git a/scripts/publish-cli.ts b/scripts/publish-cli.ts
index 846051bff..988f17457 100644
--- a/scripts/publish-cli.ts
+++ b/scripts/publish-cli.ts
@@ -162,7 +162,6 @@ export async function assertCliPublishArtifacts(
   await assertFile(resolve(cliDir, "dist/esm/index.mjs"));
   await assertFile(resolve(cliDir, "dist/esm/server-runner.mjs"));
   await assertFile(resolve(cliDir, "dist/web/index.html"));
-  await assertFile(resolve(cliDir, "dist/web/dev-browser-sw.js"));
   assertBundleRuntimeDependenciesDeclared(
     pkg.dependencies,
     await collectBareImports(resolve(cliDir, "dist/esm"), [
diff --git a/scripts/shared/dev-cli-shim.test.ts b/scripts/shared/dev-cli-shim.test.ts
new file mode 100644
index 000000000..380f0890e
--- /dev/null
+++ b/scripts/shared/dev-cli-shim.test.ts
@@ -0,0 +1,163 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import { buildDevServerEnv, ensureDevCliShim, prependPathEntry } from "./dev-cli-shim.js";
+
+const tempDirs: string[] = [];
+const REPO_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+const requireFromHere = createRequire(import.meta.url);
+const NODE_EXEC = process.execPath;
+const TSX_LOADER = requireFromHere.resolve("tsx");
+
+function quotePosixShellArg(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function quoteWindowsCmdArg(value: string): string {
+  return `"${value.replaceAll("%", "%%").replaceAll('"', '""')}"`;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    rmSync(tempDirs.pop()!, { recursive: true, force: true });
+  }
+});
+
+describe("dev cli shim", () => {
+  it("writes unix and windows coder-studio shims that forward to the workspace cli", () => {
+    const rootDir = mkdtempSync(join(tmpdir(), "coder-studio-dev-shim-root-"));
+    tempDirs.push(rootDir);
+    const cliDir = join(rootDir, "packages", "cli");
+
+    const result = ensureDevCliShim({ rootDir, cliDir });
+
+    expect(result.binDir).toBe(join(rootDir, ".tmp", "dev-bin"));
+    expect(readFileSync(result.unixShimPath, "utf8")).toContain(
+      `exec ${quotePosixShellArg(NODE_EXEC)} --import ${quotePosixShellArg(TSX_LOADER)} ${quotePosixShellArg(join(cliDir, "src", "bin.ts"))} "$@"`
+    );
+    expect(readFileSync(result.windowsShimPath, "utf8")).toContain(
+      `${quoteWindowsCmdArg(NODE_EXEC)} --import ${quoteWindowsCmdArg(TSX_LOADER)} ${quoteWindowsCmdArg(join(cliDir, "src", "bin.ts"))} %*`
+    );
+    expect(statSync(result.unixShimPath).mode & 0o111).not.toBe(0);
+  });
+
+  it("quotes shim root directories for unix shells and cmd files", () => {
+    const rootDir = join(tmpdir(), "coder studio root $HOME \"quoted\" 'single'");
+    tempDirs.push(rootDir);
+    const cliDir = join(rootDir, "packages", "cli");
+
+    const result = ensureDevCliShim({ rootDir, cliDir });
+
+    expect(readFileSync(result.unixShimPath, "utf8")).toContain(
+      `exec ${quotePosixShellArg(NODE_EXEC)} --import ${quotePosixShellArg(TSX_LOADER)} ${quotePosixShellArg(join(cliDir, "src", "bin.ts"))} "$@"`
+    );
+    expect(readFileSync(result.windowsShimPath, "utf8")).toContain(
+      `${quoteWindowsCmdArg(NODE_EXEC)} --import ${quoteWindowsCmdArg(TSX_LOADER)} ${quoteWindowsCmdArg(join(cliDir, "src", "bin.ts"))} %*`
+    );
+  });
+
+  it("escapes percent signs in windows cmd shims", () => {
+    const rootDir = join(tmpdir(), "coder-studio-%USERPROFILE%-root");
+    tempDirs.push(rootDir);
+    const cliDir = join(rootDir, "packages", "cli");
+
+    const result = ensureDevCliShim({ rootDir, cliDir });
+
+    expect(readFileSync(result.windowsShimPath, "utf8")).toContain(
+      `${quoteWindowsCmdArg(NODE_EXEC)} --import ${quoteWindowsCmdArg(TSX_LOADER)} ${quoteWindowsCmdArg(join(cliDir, "src", "bin.ts"))} %*`
+    );
+  });
+
+  it("prepends the shim directory using the existing PATH key casing", () => {
+    const env = prependPathEntry(
+      {
+        Path: "/usr/bin",
+        HOME: "/tmp/dev-home",
+      },
+      "/tmp/dev-bin",
+      { delimiter: ":" }
+    );
+
+    expect(env).toEqual({
+      Path: "/tmp/dev-bin:/usr/bin",
+      HOME: "/tmp/dev-home",
+    });
+  });
+
+  it("creates a PATH entry when the base env does not define one", () => {
+    const env = prependPathEntry({ HOME: "/tmp/dev-home" }, "/tmp/dev-bin", {
+      delimiter: ":",
+    });
+
+    expect(env).toEqual({
+      HOME: "/tmp/dev-home",
+      PATH: "/tmp/dev-bin",
+    });
+  });
+
+  it("normalizes duplicate PATH-like keys before prepending the shim directory", () => {
+    const env = prependPathEntry(
+      {
+        Path: "C:\\Windows",
+        PATH: "/usr/bin",
+        PaTh: "/custom/bin",
+        HOME: "/tmp/dev-home",
+      },
+      "/tmp/dev-bin",
+      { delimiter: ":" }
+    );
+
+    expect(env).toEqual({
+      Path: "/tmp/dev-bin:C:\\Windows:/usr/bin:/custom/bin",
+      HOME: "/tmp/dev-home",
+    });
+  });
+
+  it("builds the dev server env by generating the shim and prepending it to PATH", () => {
+    const rootDir = mkdtempSync(join(tmpdir(), "coder-studio-dev-env-root-"));
+    tempDirs.push(rootDir);
+    const cliDir = join(rootDir, "packages", "cli");
+
+    const env = buildDevServerEnv({
+      rootDir,
+      cliDir,
+      env: {
+        Path: "/usr/bin",
+        HOME: "/tmp/dev-home",
+      },
+    });
+
+    expect(env).toEqual({
+      Path: `${join(rootDir, ".tmp", "dev-bin")}:/usr/bin`,
+      HOME: "/tmp/dev-home",
+    });
+    expect(statSync(join(rootDir, ".tmp", "dev-bin", "coder-studio")).mode & 0o111).not.toBe(0);
+  });
+
+  it.runIf(process.platform !== "win32")(
+    "executes the generated coder-studio shim without depending on a preinstalled coder-studio command",
+    () => {
+      const result = ensureDevCliShim({
+        rootDir: REPO_ROOT,
+        cliDir: join(REPO_ROOT, "packages", "cli"),
+      });
+      const command = spawnSync(result.unixShimPath, ["help"], {
+        encoding: "utf8",
+        timeout: 40_000,
+        env: {
+          HOME: process.env.HOME ?? tmpdir(),
+          PATH: "/usr/bin:/bin",
+        },
+      });
+
+      expect(command.status).toBe(0);
+      expect(command.error).toBeUndefined();
+      expect(command.stdout).toContain("Coder Studio CLI");
+    },
+    40_000
+  );
+});
diff --git a/scripts/shared/dev-cli-shim.ts b/scripts/shared/dev-cli-shim.ts
new file mode 100644
index 000000000..85a5dacdc
--- /dev/null
+++ b/scripts/shared/dev-cli-shim.ts
@@ -0,0 +1,105 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter as defaultPathDelimiter, join } from "node:path";
+
+export interface DevCliShimInput {
+  rootDir: string;
+  cliDir: string;
+}
+
+export interface DevCliShimResult {
+  binDir: string;
+  unixShimPath: string;
+  windowsShimPath: string;
+}
+
+export interface DevServerEnvInput extends DevCliShimInput {
+  env: NodeJS.ProcessEnv;
+}
+
+function quotePosixShellArg(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function quoteWindowsCmdArg(value: string): string {
+  return `"${value.replaceAll("%", "%%").replaceAll('"', '""')}"`;
+}
+
+const requireFromHere = createRequire(import.meta.url);
+
+function resolveDevCliRuntime() {
+  return {
+    nodeExecPath: process.execPath,
+    tsxLoaderPath: requireFromHere.resolve("tsx"),
+  };
+}
+
+export function ensureDevCliShim(input: DevCliShimInput): DevCliShimResult {
+  const binDir = join(input.rootDir, ".tmp", "dev-bin");
+  const unixShimPath = join(binDir, "coder-studio");
+  const windowsShimPath = join(binDir, "coder-studio.cmd");
+  const repoCliEntry = join(input.cliDir, "src", "bin.ts");
+  const { nodeExecPath, tsxLoaderPath } = resolveDevCliRuntime();
+  const unixNodeExec = quotePosixShellArg(nodeExecPath);
+  const unixTsxLoader = quotePosixShellArg(tsxLoaderPath);
+  const unixRepoCliEntry = quotePosixShellArg(repoCliEntry);
+  const windowsNodeExec = quoteWindowsCmdArg(nodeExecPath);
+  const windowsTsxLoader = quoteWindowsCmdArg(tsxLoaderPath);
+  const windowsRepoCliEntry = quoteWindowsCmdArg(repoCliEntry);
+
+  mkdirSync(binDir, { recursive: true });
+
+  writeFileSync(
+    unixShimPath,
+    [
+      "#!/usr/bin/env sh",
+      `exec ${unixNodeExec} --import ${unixTsxLoader} ${unixRepoCliEntry} "$@"`,
+      "",
+    ].join("\n"),
+    { encoding: "utf8", mode: 0o755 }
+  );
+  writeFileSync(
+    windowsShimPath,
+    [
+      "@echo off",
+      `${windowsNodeExec} --import ${windowsTsxLoader} ${windowsRepoCliEntry} %*`,
+      "",
+    ].join("\r\n"),
+    "utf8"
+  );
+
+  return {
+    binDir,
+    unixShimPath,
+    windowsShimPath,
+  };
+}
+
+export function prependPathEntry(
+  env: NodeJS.ProcessEnv,
+  entry: string,
+  options: { delimiter?: string } = {}
+): NodeJS.ProcessEnv {
+  const pathKeys = Object.keys(env).filter((key) => key.toUpperCase() === "PATH");
+  const pathKey =
+    pathKeys.find((key) => key === "Path") ?? pathKeys.find((key) => key === "PATH") ?? "PATH";
+  const currentPath = pathKeys
+    .map((key) => env[key])
+    .filter((value): value is string => typeof value === "string" && value.length > 0)
+    .join(options.delimiter ?? defaultPathDelimiter);
+  const delimiter = options.delimiter ?? defaultPathDelimiter;
+  const nextEnv = { ...env };
+  for (const key of pathKeys) {
+    delete nextEnv[key];
+  }
+
+  return {
+    ...nextEnv,
+    [pathKey]: currentPath.length > 0 ? `${entry}${delimiter}${currentPath}` : entry,
+  };
+}
+
+export function buildDevServerEnv(input: DevServerEnvInput): NodeJS.ProcessEnv {
+  const { binDir } = ensureDevCliShim(input);
+  return prependPathEntry(input.env, binDir);
+}
diff --git a/scripts/shared/esbuild.ts b/scripts/shared/esbuild.ts
index 4faa95ad9..6a1a2cc05 100644
--- a/scripts/shared/esbuild.ts
+++ b/scripts/shared/esbuild.ts
@@ -56,6 +56,7 @@ export async function createCliBuildOptions(format: "esm" | "cjs"): Promise<Buil
 
   return {
     entryPoints: [
+      resolve(CLI_DIR, "src/automation-entry.ts"),
       resolve(CLI_DIR, "src/bin.ts"),
       resolve(CLI_DIR, "src/index.ts"),
       resolve(CLI_DIR, "src/server-runner.ts"),
diff --git a/scripts/shared/index.ts b/scripts/shared/index.ts
index 5f9cf602a..e33dd5509 100644
--- a/scripts/shared/index.ts
+++ b/scripts/shared/index.ts
@@ -3,6 +3,7 @@
  */
 
 export * from "./copy.js";
+export * from "./dev-cli-shim.js";
 export * from "./esbuild.js";
 export * from "./logger.js";
 export * from "./paths.js";
diff --git a/scripts/shared/process.test.ts b/scripts/shared/process.test.ts
new file mode 100644
index 000000000..226923670
--- /dev/null
+++ b/scripts/shared/process.test.ts
@@ -0,0 +1,35 @@
+import type { ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { describe, expect, it, vi } from "vitest";
+import { waitForProcesses } from "./process.js";
+
+function createChildProcess() {
+  const child = new EventEmitter() as ChildProcess;
+  child.kill = vi.fn(() => true) as unknown as ChildProcess["kill"];
+  return child;
+}
+
+describe("process utilities", () => {
+  it("rejects and terminates sibling processes when one child exits non-zero", async () => {
+    const failingProcess = createChildProcess();
+    const siblingProcess = createChildProcess();
+    const wait = waitForProcesses([failingProcess, siblingProcess]);
+
+    failingProcess.emit("close", 1, null);
+
+    await expect(wait).rejects.toThrow("Process exited with code 1");
+    expect(siblingProcess.kill).toHaveBeenCalledWith("SIGTERM");
+    expect(failingProcess.kill).not.toHaveBeenCalled();
+  });
+
+  it("resolves when all child processes exit successfully", async () => {
+    const firstProcess = createChildProcess();
+    const secondProcess = createChildProcess();
+    const wait = waitForProcesses([firstProcess, secondProcess]);
+
+    firstProcess.emit("close", 0, null);
+    secondProcess.emit("close", 0, null);
+
+    await expect(wait).resolves.toBeUndefined();
+  });
+});
diff --git a/scripts/shared/process.ts b/scripts/shared/process.ts
index c3242bdab..a702fd395 100644
--- a/scripts/shared/process.ts
+++ b/scripts/shared/process.ts
@@ -75,12 +75,48 @@ export function runBackground(
  * Wait for all child processes to exit
  */
 export async function waitForProcesses(processes: ChildProcess[]): Promise<void> {
-  await Promise.all(
-    processes.map(
-      (p) =>
-        new Promise<void>((resolve) => {
-          p.on("close", () => resolve());
-        })
-    )
-  );
+  const settled = new Set<ChildProcess>();
+
+  await new Promise<void>((resolve, reject) => {
+    if (processes.length === 0) {
+      resolve();
+      return;
+    }
+
+    let rejected = false;
+
+    const rejectOnce = (processToSkip: ChildProcess, error: Error) => {
+      if (rejected) {
+        return;
+      }
+      rejected = true;
+      for (const processToKill of processes) {
+        if (processToKill !== processToSkip && !settled.has(processToKill)) {
+          processToKill.kill("SIGTERM");
+        }
+      }
+      reject(error);
+    };
+
+    for (const child of processes) {
+      child.on("close", (code, signal) => {
+        settled.add(child);
+        if (code !== 0) {
+          const suffix =
+            typeof code === "number" ? `code ${code}` : `signal ${signal ?? "unknown"}`;
+          rejectOnce(child, new Error(`Process exited with ${suffix}`));
+          return;
+        }
+
+        if (!rejected && settled.size === processes.length) {
+          resolve();
+        }
+      });
+
+      child.on("error", (err) => {
+        settled.add(child);
+        rejectOnce(child, err);
+      });
+    }
+  });
 }