diff --git a/.github/workflows/assemble-local.yml b/.github/workflows/assemble-local.yml
deleted file mode 100644
index 90f6de42..00000000
--- a/.github/workflows/assemble-local.yml
+++ /dev/null
@@ -1,193 +0,0 @@
-name: Assemble local branch
-
-# Triggers on every master push (i.e. after syncing upstream) and on demand.
-# Builds the `local` branch: master + fork overlay + cherry-picked pending upstream PRs.
-# Syncs build-dev.yml to the `dev` branch so every dev push triggers a build.
-#
-# PR entries support an optional "exclude:BRANCH" suffix to handle cases where
-# one PR branch was rebased onto another. The exclude branch's commits are subtracted
-# from the cherry-pick range so they aren't double-applied.
-#
-# When upstream merges a PR, remove its entry from PR_CHERRY_PICK or PR_SQUASH below.
-
-on:
-  push:
-    branches: [master]
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  actions: write
-
-jobs:
-  assemble:
-    runs-on: runners-farhoodlabs
-    timeout-minutes: 15
-    steps:
-      - name: Checkout master
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Configure git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-
-      - name: Fetch all remotes
-        run: |
-          git remote add upstream https://github.com/paperclipai/paperclip.git 2>/dev/null || true
-          git fetch --all --quiet
-
-      - name: Assemble local branch
-        run: |
-          set -euo pipefail
-
-          # Start local from master (which mirrors upstream)
-          git checkout -B local origin/master
-
-          # Apply fork overlay: Dockerfile, build workflows, CLAUDE.md
-          cp .farhoodlabs/Dockerfile Dockerfile
-          cp .farhoodlabs/CLAUDE.md CLAUDE.md
-          mkdir -p .github/workflows
-          cp .farhoodlabs/.github/workflows/build-prod.yml .github/workflows/build-prod.yml
-          cp .farhoodlabs/.github/workflows/build-dev.yml .github/workflows/build-dev.yml
-          git add Dockerfile CLAUDE.md .github/workflows/build-prod.yml .github/workflows/build-dev.yml
-          git commit -m "chore: apply fork overlay from .farhoodlabs"
-
-          # --- PRs to cherry-pick commit-by-commit (clean, no merge commits) ---
-          # Format: "PR-number branch-name [exclude:base-branch]"
-          # Use exclude: when a branch was rebased onto another PR branch to avoid double-applying commits.
-          # Remove an entry here when upstream merges the PR.
-          PR_CHERRY_PICK=(
-            "3237 skill-pat-feature"
-            "3351 skill-scan-refresh exclude:skill-pat-feature"
-            "4162 fix/far-108-k8s-adapter-reaper-liveness"
-          )
-
-          for entry in "${PR_CHERRY_PICK[@]}"; do
-            # Parse: pr_num, branch, optional exclude branch
-            pr_num=$(echo "$entry" | awk '{print $1}')
-            branch=$(echo "$entry" | awk '{print $2}')
-            exclude_branch=$(echo "$entry" | grep -oP '(?<=exclude:)\S+' || true)
-            remote_branch="origin/$branch"
-            exclude_arg=""
-            if [ -n "$exclude_branch" ]; then
-              exclude_arg="--not origin/$exclude_branch"
-            fi
-
-            if ! git rev-parse "$remote_branch" &>/dev/null; then
-              echo "WARNING: $remote_branch not found, skipping PR #$pr_num"
-              continue
-            fi
-
-            # Exclude commits already on origin/master (fork-overlay/CI infra
-            # that landed on master via the .farhoodlabs/ overlay path). PR
-            # branches sometimes pull these in via `git merge origin/master`,
-            # but cherry-picking them onto `local` (which is already master)
-            # is redundant and produces conflicts on the assemble-local file.
-            mapfile -t commits < <(git log --no-merges --reverse --format="%H" upstream/master.."$remote_branch" ^origin/master $exclude_arg)
-
-            if [ ${#commits[@]} -eq 0 ]; then
-              echo "PR #$pr_num ($branch): no unique commits — likely merged upstream, skipping"
-              continue
-            fi
-
-            echo "PR #$pr_num ($branch): cherry-picking ${#commits[@]} commit(s)"
-            for sha in "${commits[@]}"; do
-              git cherry-pick "$sha" || {
-                # If the cherry-pick produced an empty result (commit's content
-                # is already in HEAD via auto-merge), skip it instead of failing.
-                # State signature: CHERRY_PICK_HEAD set, no unmerged paths,
-                # nothing staged.
-                if [ -f .git/CHERRY_PICK_HEAD ] \
-                  && [ -z "$(git diff --name-only --diff-filter=U)" ] \
-                  && git diff --staged --quiet; then
-                  echo "PR #$pr_num: $sha became empty after merge, skipping"
-                  git cherry-pick --skip
-                  continue
-                fi
-                echo "::error::Cherry-pick conflict at $sha from PR #$pr_num ($branch)"
-                echo "::error::Resolve the conflict, force-push the branch, then re-run this workflow"
-                git cherry-pick --abort
-                exit 1
-              }
-            done
-          done
-
-          # --- PRs to apply as a single squash (complex history with merge commits) ---
-          # git merge --squash applies the net final diff of the branch, bypassing
-          # intra-PR commit ordering issues. CI commits that cancel out are ignored.
-          # Remove an entry here when upstream merges the PR.
-          PR_SQUASH=(
-            "3987 feat/company-portability-complete"
-          )
-
-          for entry in "${PR_SQUASH[@]}"; do
-            pr_num="${entry%% *}"
-            branch="${entry#* }"
-            remote_branch="origin/$branch"
-
-            if ! git rev-parse "$remote_branch" &>/dev/null; then
-              echo "WARNING: $remote_branch not found, skipping PR #$pr_num"
-              continue
-            fi
-
-            # Check if the branch has any unique non-merge commits
-            unique=$(git log --no-merges --oneline upstream/master.."$remote_branch" | wc -l)
-            if [ "$unique" -eq 0 ]; then
-              echo "PR #$pr_num ($branch): no unique commits — likely merged upstream, skipping"
-              continue
-            fi
-
-            echo "PR #$pr_num ($branch): applying as squash ($unique non-merge commits)"
-            git merge --squash "$remote_branch" || {
-              echo "::error::Squash conflict for PR #$pr_num ($branch)"
-              git merge --abort 2>/dev/null || git reset --hard HEAD
-              exit 1
-            }
-            # Only commit if there are staged changes
-            git diff --staged --quiet || git commit -m "feat: apply PR #$pr_num ($branch)"
-          done
-
-          git push origin local --force
-          echo "local branch assembled and pushed"
-
-      - name: Trigger prod build
-        run: |
-          curl -sS -X POST \
-            -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
-            -H "Accept: application/vnd.github.v3+json" \
-            https://api.github.com/repos/${{ github.repository }}/actions/workflows/build-prod.yml/dispatches \
-            -d '{"ref":"local"}'
-
-      - name: Sync build-dev.yml to dev branch
-        run: |
-          set -euo pipefail
-
-          if ! git rev-parse origin/dev &>/dev/null; then
-            echo "dev branch not found on origin, skipping"
-            exit 0
-          fi
-
-          canonical=".farhoodlabs/.github/workflows/build-dev.yml"
-          target=".github/workflows/build-dev.yml"
-
-          if git show origin/dev:"$target" 2>/dev/null | diff --brief - "$canonical" &>/dev/null; then
-            echo "build-dev.yml on dev is up to date, skipping"
-            exit 0
-          fi
-
-          echo "Syncing build-dev.yml to dev branch..."
-          # Save canonical content before switching branches (.farhoodlabs/ only exists on master)
-          tmp=$(mktemp)
-          cp "$canonical" "$tmp"
-          git checkout -B dev-wf-sync origin/dev
-          mkdir -p "$(dirname "$target")"
-          cp "$tmp" "$target"
-          rm "$tmp"
-          git add "$target"
-          git commit -m "chore(ci): sync build-dev.yml from .farhoodlabs"
-          git push origin dev-wf-sync:dev
-          echo "build-dev.yml synced to dev"
diff --git a/Dockerfile b/Dockerfile
index 95c452c9..e367910e 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -34,6 +34,7 @@ COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/
 COPY packages/plugins/sdk/package.json packages/plugins/sdk/
 COPY --parents packages/plugins/sandbox-providers/./*/package.json packages/plugins/sandbox-providers/
 COPY packages/plugins/paperclip-plugin-fake-sandbox/package.json packages/plugins/paperclip-plugin-fake-sandbox/
+COPY packages/plugins/plugin-llm-wiki/package.json packages/plugins/plugin-llm-wiki/
 COPY patches/ patches/
 
 RUN pnpm install --frozen-lockfile
diff --git a/cli/src/__tests__/plugin-init.test.ts b/cli/src/__tests__/plugin-init.test.ts
new file mode 100644
index 00000000..8faeb459
--- /dev/null
+++ b/cli/src/__tests__/plugin-init.test.ts
@@ -0,0 +1,164 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  scaffoldPluginProject: vi.fn((options: { outputDir: string }) => options.outputDir),
+}));
+
+vi.mock("../../../packages/plugins/create-paperclip-plugin/src/index.js", async () => {
+  const actual =
+    await vi.importActual<typeof import("../../../packages/plugins/create-paperclip-plugin/src/index.js")>(
+      "../../../packages/plugins/create-paperclip-plugin/src/index.js",
+    );
+  return {
+    ...actual,
+    scaffoldPluginProject: mocks.scaffoldPluginProject,
+  };
+});
+
+import {
+  buildPluginInstallRequest,
+  buildPluginInitNextCommands,
+  buildPluginInitScaffoldOptions,
+  registerPluginCommands,
+} from "../commands/client/plugin.js";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cli-plugin-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("plugin init", () => {
+  beforeEach(() => {
+    mocks.scaffoldPluginProject.mockClear();
+  });
+
+  it("maps package name and flags to scaffolder options", () => {
+    const cwd = path.resolve("/tmp/paperclip-cli-test");
+    const options = buildPluginInitScaffoldOptions(
+      "@acme/plugin-linear",
+      {
+        output: "plugins",
+        template: "connector",
+        category: "automation",
+        displayName: "Linear Bridge",
+        description: "Syncs Linear issues",
+        author: "Acme",
+        sdkPath: "../paperclip/packages/plugins/sdk",
+      },
+      cwd,
+    );
+
+    expect(options).toEqual({
+      pluginName: "@acme/plugin-linear",
+      outputDir: path.resolve(cwd, "plugins", "plugin-linear"),
+      template: "connector",
+      category: "automation",
+      displayName: "Linear Bridge",
+      description: "Syncs Linear issues",
+      author: "Acme",
+      sdkPath: "../paperclip/packages/plugins/sdk",
+    });
+  });
+
+  it("builds exact next commands using the scaffold path", () => {
+    expect(buildPluginInitNextCommands("/tmp/acme plugin")).toEqual([
+      "cd '/tmp/acme plugin'",
+      "pnpm install",
+      "pnpm dev",
+      "paperclipai plugin install '/tmp/acme plugin'",
+    ]);
+  });
+
+  it("registers the CLI wrapper and invokes the existing scaffolder", async () => {
+    const program = new Command();
+    program.exitOverride();
+    program.configureOutput({ writeOut: () => {}, writeErr: () => {} });
+    registerPluginCommands(program);
+
+    await program.parseAsync(
+      [
+        "plugin",
+        "init",
+        "demo-plugin",
+        "--output",
+        "/tmp/paperclip-init-output",
+        "--template",
+        "workspace",
+        "--category",
+        "workspace",
+        "--display-name",
+        "Demo Plugin",
+        "--description",
+        "Demo description",
+        "--author",
+        "Paperclip",
+        "--sdk-path",
+        "/repo/packages/plugins/sdk",
+      ],
+      { from: "user" },
+    );
+
+    expect(mocks.scaffoldPluginProject).toHaveBeenCalledTimes(1);
+    expect(mocks.scaffoldPluginProject).toHaveBeenCalledWith({
+      pluginName: "demo-plugin",
+      outputDir: path.resolve("/tmp/paperclip-init-output", "demo-plugin"),
+      template: "workspace",
+      category: "workspace",
+      displayName: "Demo Plugin",
+      description: "Demo description",
+      author: "Paperclip",
+      sdkPath: "/repo/packages/plugins/sdk",
+    });
+  });
+});
+
+describe("plugin install", () => {
+  it("resolves an existing relative local path to an absolute local install request", () => {
+    const cwd = makeTempDir();
+    const pluginDir = path.join(cwd, "demo-plugin");
+    fs.mkdirSync(pluginDir);
+
+    expect(buildPluginInstallRequest("demo-plugin", {}, { cwd })).toEqual({
+      packageName: pluginDir,
+      version: undefined,
+      isLocalPath: true,
+    });
+  });
+
+  it("keeps an absolute local path absolute and marks it as local", () => {
+    const pluginDir = path.join(makeTempDir(), "demo-plugin");
+    fs.mkdirSync(pluginDir);
+
+    expect(buildPluginInstallRequest(pluginDir, {}, { cwd: "/" })).toEqual({
+      packageName: pluginDir,
+      version: undefined,
+      isLocalPath: true,
+    });
+  });
+
+  it("preserves npm package installs when no local path exists", () => {
+    expect(
+      buildPluginInstallRequest("@acme/plugin-linear", { version: "1.2.3" }, {
+        cwd: makeTempDir(),
+      }),
+    ).toEqual({
+      packageName: "@acme/plugin-linear",
+      version: "1.2.3",
+      isLocalPath: false,
+    });
+  });
+});
diff --git a/cli/src/commands/client/plugin.ts b/cli/src/commands/client/plugin.ts
index 9031d696..933671e3 100644
--- a/cli/src/commands/client/plugin.ts
+++ b/cli/src/commands/client/plugin.ts
@@ -1,5 +1,11 @@
 import path from "node:path";
-import { Command } from "commander";
+import { existsSync } from "node:fs";
+import { Command, Option } from "commander";
+import {
+  scaffoldPluginProject,
+  shellQuote,
+  type ScaffoldPluginOptions,
+} from "../../../../packages/plugins/create-paperclip-plugin/src/index.js";
 import pc from "picocolors";
 import {
   addCommonClientOptions,
@@ -39,28 +45,101 @@ interface PluginInstallOptions extends BaseClientOptions {
   version?: string;
 }
 
+interface PluginInstallRequest {
+  packageName: string;
+  version?: string;
+  isLocalPath: boolean;
+}
+
 interface PluginUninstallOptions extends BaseClientOptions {
   force?: boolean;
 }
 
+interface PluginInitOptions extends BaseClientOptions {
+  output?: string;
+  template?: ScaffoldPluginOptions["template"];
+  category?: ScaffoldPluginOptions["category"];
+  displayName?: string;
+  description?: string;
+  author?: string;
+  sdkPath?: string;
+}
+
+interface PluginInitResult {
+  outputDir: string;
+  nextCommands: string[];
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+function expandHomePath(packageArg: string): string {
+  if (!packageArg.startsWith("~")) return packageArg;
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  return path.resolve(home, packageArg.slice(1).replace(/^[\\/]/, ""));
+}
+
+function hasLocalPathSyntax(packageArg: string): boolean {
+  return (
+    path.isAbsolute(packageArg) ||
+    packageArg.startsWith("./") ||
+    packageArg.startsWith("../") ||
+    packageArg.startsWith("~") ||
+    packageArg.startsWith(".\\") ||
+    packageArg.startsWith("..\\")
+  );
+}
+
+function isExistingRelativePath(
+  packageArg: string,
+  cwd: string,
+  pathExists: (targetPath: string) => boolean,
+): boolean {
+  if (packageArg.trim() === "") return false;
+  if (hasLocalPathSyntax(packageArg)) return false;
+  return pathExists(path.resolve(cwd, packageArg));
+}
+
 /**
  * Resolve a local path argument to an absolute path so the server can find the
  * plugin on disk regardless of where the user ran the CLI.
  */
-function resolvePackageArg(packageArg: string, isLocal: boolean): string {
+function resolvePackageArg(packageArg: string, isLocal: boolean, cwd = process.cwd()): string {
   if (!isLocal) return packageArg;
-  // Already absolute
   if (path.isAbsolute(packageArg)) return packageArg;
-  // Expand leading ~ to home directory
-  if (packageArg.startsWith("~")) {
-    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-    return path.resolve(home, packageArg.slice(1).replace(/^[\\/]/, ""));
+  if (packageArg.startsWith("~")) return expandHomePath(packageArg);
+  return path.resolve(cwd, packageArg);
+}
+
+export function buildPluginInstallRequest(
+  packageArg: string,
+  opts: Pick<PluginInstallOptions, "local" | "version"> = {},
+  deps: { cwd?: string; existsSync?: (targetPath: string) => boolean } = {},
+): PluginInstallRequest {
+  const cwd = deps.cwd ?? process.cwd();
+  const pathExists = deps.existsSync ?? existsSync;
+  const isLocal =
+    opts.local ||
+    hasLocalPathSyntax(packageArg) ||
+    (opts.version ? false : isExistingRelativePath(packageArg, cwd, pathExists));
+
+  if (isLocal && opts.version) {
+    throw new Error("--version is only supported for npm package installs, not local plugin paths.");
   }
-  return path.resolve(process.cwd(), packageArg);
+
+  return {
+    packageName: resolvePackageArg(packageArg, Boolean(isLocal), cwd),
+    version: opts.version,
+    isLocalPath: Boolean(isLocal),
+  };
+}
+
+export function renderLocalPluginInstallHint(packagePath: string): string {
+  return [
+    pc.dim("Local plugin installs run trusted local code from your machine."),
+    pc.dim(`Keep ${pc.cyan("pnpm dev")} running in ${packagePath}; Paperclip watches rebuilt dist output and reloads the plugin worker.`),
+  ].join("\n");
 }
 
 function formatPlugin(p: PluginRecord): string {
@@ -87,6 +166,58 @@ function formatPlugin(p: PluginRecord): string {
   return parts.join("  ");
 }
 
+function packageToDirName(pluginName: string): string {
+  return pluginName.replace(/^@[^/]+\//, "");
+}
+
+export function buildPluginInitScaffoldOptions(
+  packageName: string,
+  opts: PluginInitOptions,
+  cwd = process.cwd(),
+): ScaffoldPluginOptions {
+  const outputRoot = path.resolve(cwd, opts.output ?? ".");
+  const outputDir = path.resolve(outputRoot, packageToDirName(packageName));
+
+  return {
+    pluginName: packageName,
+    outputDir,
+    template: opts.template,
+    category: opts.category,
+    displayName: opts.displayName,
+    description: opts.description,
+    author: opts.author,
+    sdkPath: opts.sdkPath,
+  };
+}
+
+export function buildPluginInitNextCommands(outputDir: string): string[] {
+  const quotedOutputDir = shellQuote(outputDir);
+  return [
+    `cd ${quotedOutputDir}`,
+    "pnpm install",
+    "pnpm dev",
+    `paperclipai plugin install ${quotedOutputDir}`,
+  ];
+}
+
+export function renderPluginInitSuccess(result: PluginInitResult): string {
+  return [
+    pc.green(`✓ Created plugin scaffold at ${result.outputDir}`),
+    "",
+    "Next commands:",
+    ...result.nextCommands.map((command) => `  ${pc.cyan(command)}`),
+  ].join("\n");
+}
+
+export function runPluginInitCommand(packageName: string, opts: PluginInitOptions): PluginInitResult {
+  const scaffoldOptions = buildPluginInitScaffoldOptions(packageName, opts);
+  const outputDir = scaffoldPluginProject(scaffoldOptions);
+  return {
+    outputDir,
+    nextCommands: buildPluginInitNextCommands(outputDir),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -94,6 +225,43 @@ function formatPlugin(p: PluginRecord): string {
 export function registerPluginCommands(program: Command): void {
   const plugin = program.command("plugin").description("Plugin lifecycle management");
 
+  // -------------------------------------------------------------------------
+  // plugin init <package-name>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("init <packageName>")
+      .description("Scaffold a local Paperclip plugin project")
+      .option("--output <dir>", "Directory to create the plugin folder in")
+      .addOption(
+        new Option("--template <template>", "Starter template")
+          .choices(["default", "connector", "workspace", "environment"])
+          .default("default"),
+      )
+      .addOption(
+        new Option("--category <category>", "Manifest category")
+          .choices(["connector", "workspace", "automation", "ui", "environment"]),
+      )
+      .option("--display-name <name>", "Manifest display name")
+      .option("--description <description>", "Manifest description")
+      .option("--author <author>", "Manifest author")
+      .option("--sdk-path <path>", "Local @paperclipai/plugin-sdk package path")
+      .action((packageName: string, opts: PluginInitOptions) => {
+        try {
+          const result = runPluginInitCommand(packageName, opts);
+
+          if (opts.json) {
+            printOutput(result, { json: true });
+            return;
+          }
+
+          console.log(renderPluginInitSuccess(result));
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
   // -------------------------------------------------------------------------
   // plugin list
   // -------------------------------------------------------------------------
@@ -147,31 +315,19 @@ export function registerPluginCommands(program: Command): void {
         try {
           const ctx = resolveCommandContext(opts);
 
-          // Auto-detect local paths: starts with . or / or ~ or is an absolute path
-          const isLocal =
-            opts.local ||
-            packageArg.startsWith("./") ||
-            packageArg.startsWith("../") ||
-            packageArg.startsWith("/") ||
-            packageArg.startsWith("~");
-
-          const resolvedPackage = resolvePackageArg(packageArg, isLocal);
+          const installRequest = buildPluginInstallRequest(packageArg, opts);
 
           if (!ctx.json) {
             console.log(
               pc.dim(
-                isLocal
-                  ? `Installing plugin from local path: ${resolvedPackage}`
-                  : `Installing plugin: ${resolvedPackage}${opts.version ? `@${opts.version}` : ""}`,
+                installRequest.isLocalPath
+                  ? `Installing plugin from local path: ${installRequest.packageName}`
+                  : `Installing plugin: ${installRequest.packageName}${opts.version ? `@${opts.version}` : ""}`,
               ),
             );
           }
 
-          const installedPlugin = await ctx.api.post<PluginRecord>("/api/plugins/install", {
-            packageName: resolvedPackage,
-            version: opts.version,
-            isLocalPath: isLocal,
-          });
+          const installedPlugin = await ctx.api.post<PluginRecord>("/api/plugins/install", installRequest);
 
           if (ctx.json) {
             printOutput(installedPlugin, { json: true });
@@ -192,6 +348,10 @@ export function registerPluginCommands(program: Command): void {
           if (installedPlugin.lastError) {
             console.log(pc.red(`  Warning: ${installedPlugin.lastError}`));
           }
+
+          if (installRequest.isLocalPath) {
+            console.log(renderLocalPluginInstallHint(installRequest.packageName));
+          }
         } catch (err) {
           handleCommandError(err);
         }
diff --git a/cli/tsconfig.json b/cli/tsconfig.json
index 3af05f51..3b42fe77 100644
--- a/cli/tsconfig.json
+++ b/cli/tsconfig.json
@@ -4,5 +4,5 @@
     "outDir": "dist",
     "rootDir": ".."
   },
-  "include": ["src", "../packages/shared/src"]
+  "include": ["src", "../packages/shared/src", "../packages/plugins/create-paperclip-plugin/src"]
 }
diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md
index 22075e04..45f2e15b 100644
--- a/doc/SPEC-implementation.md
+++ b/doc/SPEC-implementation.md
@@ -37,7 +37,7 @@ These decisions close open questions from `SPEC.md` for V1.
 | Visibility | Full visibility to board and all agents in same company |
 | Communication | Tasks + comments only (no separate chat system) |
 | Task ownership | Single assignee; atomic checkout required for `in_progress` transition |
-| Recovery | Liveness/watchdog recovery preserves explicit ownership: retry lost execution continuity where safe, otherwise create visible recovery issues or require human escalation (see `doc/execution-semantics.md`) |
+| Recovery | Liveness/watchdog recovery preserves explicit ownership: retry lost execution continuity where safe, otherwise open visible source-scoped recovery actions by default, use issue-backed recovery only for independent repair work, or require human escalation (see `doc/execution-semantics.md`) |
 | Agent adapters | Built-in `process`, `http`, local CLI/session adapters, and OpenClaw gateway support; external adapters can also be loaded through the adapter plugin flow |
 | Plugin framework | Local/self-hosted early plugin runtime is in scope; cloud marketplace and packaged public distribution remain out of scope |
 | Auth | Mode-dependent human auth (`local_trusted` implicit board in current code; authenticated mode uses sessions), API keys for agents |
@@ -434,9 +434,10 @@ Side effects:
 V1 non-terminal liveness rule:
 
 - agent-owned `todo`, `in_progress`, `in_review`, and `blocked` issues must have a live execution path, an explicit waiting path, or an explicit recovery path
-- `in_review` is healthy only when a typed execution participant, pending issue-thread interaction or approval, user owner, active run, queued wake, or explicit recovery issue owns the next action
+- `in_review` is healthy only when a typed execution participant, pending issue-thread interaction or approval, user owner, active run, queued wake, or explicit recovery action owns the next action
 - a blocked chain is covered only when each unresolved leaf issue is live or explicitly waiting
 - when Paperclip cannot safely infer the next action, it surfaces the problem through visible blocked/recovery work instead of silently completing or reassigning work
+- explicit recovery actions are the liveness primitive; source-scoped actions are the default form, issue-backed recovery is a fallback for independent repair work or safety boundaries, and comments alone are evidence rather than a healthy liveness path
 
 Detailed ownership, execution, blocker, active-run watchdog, crash-recovery, and non-terminal liveness semantics are documented in `doc/execution-semantics.md`.
 
diff --git a/doc/execution-semantics.md b/doc/execution-semantics.md
index b6d2d542..735c88a6 100644
--- a/doc/execution-semantics.md
+++ b/doc/execution-semantics.md
@@ -156,7 +156,7 @@ If a parent is truly waiting on a child, model that with blockers. Do not rely o
 
 For agent-owned, non-terminal issues, Paperclip should never leave work in a state where nobody is responsible for the next move and nothing will wake or surface it.
 
-This is a visibility contract, not an auto-completion contract. If Paperclip cannot safely infer the next action, it should surface the ambiguity with a blocked state, a visible comment, or an explicit recovery issue. It must not silently mark work done from prose comments or guess that a dependency is complete.
+This is a visibility contract, not an auto-completion contract. If Paperclip cannot safely infer the next action, it should surface the ambiguity with a blocked state, a visible notice, or an explicit recovery action. It must not silently mark work done from prose comments or guess that a dependency is complete.
 
 An issue is healthy when the product can answer "what moves this forward next?" without requiring a human to reconstruct intent from the whole thread. An issue is stalled when it is non-terminal but has no live execution path, no explicit waiting path, and no recovery path.
 
@@ -169,7 +169,32 @@ The valid action-path primitives are:
 - a one-shot issue monitor (`executionPolicy.monitor.nextCheckAt`) that will wake the assignee for a future check
 - a human owner via `assigneeUserId`
 - a first-class blocker chain whose unresolved leaf issues are themselves healthy
-- an open explicit recovery issue that names the owner and action needed to restore liveness
+- an open explicit recovery action that names the owner and action needed to restore liveness
+
+### Explicit recovery actions
+
+An explicit recovery action is a typed liveness repair path for a source issue. It is the recovery primitive; the action can be rendered directly on the source issue or backed by a separate recovery issue when the repair needs its own work item.
+
+A valid recovery action must name:
+
+- the source issue and company
+- the recovery kind and idempotency fingerprint
+- the recovery owner, plus previous or return owner when ownership may temporarily shift
+- the cause, bounded evidence, and next action
+- the wake, monitor, timeout, retry, or escalation policy that will move the action forward
+- the resolution outcome when closed, such as restored, delegated, false positive, blocked, escalated, or cancelled
+
+A source-scoped recovery action is the default form. Use it when the next safe move is to repair the source issue's liveness directly: restore a wake path, clarify disposition, re-establish a monitor, record a false positive, or delegate real follow-up work from the source issue.
+
+Use an issue-backed recovery action only when the recovery is genuinely independent work or when source-scoped handling would be unsafe or unclear. Examples include:
+
+- long or cross-agent repair work with its own assignee, subtasks, or blockers
+- real delegated follow-up that should block the source issue as a first-class dependency
+- active-run watchdog work that must observe a still-running source process without interfering with it
+- recovery that needs separate review, approval, security handling, or escalation ownership
+- cases where source issue ownership cannot be changed or restored safely
+
+A comment or system notice can be evidence for a recovery action, but it is not a recovery action by itself. Comment-only recovery is not a healthy liveness path because it does not define a typed owner, wake or monitor policy, retry bound, timeout, escalation path, or resolution outcome.
 
 ### Agent-assigned `todo`
 
@@ -191,7 +216,7 @@ Assigning an issue normally implies executable intent. When create APIs receive
 
 An explicit assigned `backlog` issue remains valid when the creator is deliberately parking the work. It must not wake the assignee just because it has an assignee. Paperclip should make that choice visible in activity and UI so operators can distinguish intentional parking from a missed handoff.
 
-An assigned `backlog` issue becomes a liveness problem when another issue is blocked on it and there is no explicit waiting path such as a human owner, active run, queued wake, pending interaction or approval, monitor, or open recovery issue. In that case the blocked parent should surface "blocked by parked work" rather than treating the dependency chain as healthy.
+An assigned `backlog` issue becomes a liveness problem when another issue is blocked on it and there is no explicit waiting path such as a human owner, active run, queued wake, pending interaction or approval, monitor, or open recovery action. In that case the blocked parent should surface "blocked by parked work" rather than treating the dependency chain as healthy.
 
 ### Agent-assigned `in_progress`
 
@@ -202,7 +227,7 @@ A healthy active-work state means at least one of these is true:
 - there is an active run for the issue
 - there is already a queued continuation wake
 - there is an active one-shot monitor that will wake the assignee for a future check
-- there is an open explicit recovery issue for the lost execution path
+- there is an open explicit recovery action for the lost execution path
 
 An agent-owned `in_progress` issue is stalled when it has no active run, no queued continuation, and no explicit recovery surface. A still-running but silent process is not automatically stalled; it is handled by the active-run watchdog contract.
 
@@ -217,11 +242,11 @@ A healthy `in_review` issue has at least one valid action path:
 - a human owner via `assigneeUserId`
 - an active run or queued wake that is expected to process the review state
 - an active one-shot monitor for an external service or async review loop that the assignee owns
-- an open explicit recovery issue for an ambiguous review handoff
+- an open explicit recovery action for an ambiguous review handoff
 
 Agent-assigned `in_review` with no typed participant is only healthy when one of the other paths exists. Assignment to the same agent that produced the handoff is not, by itself, a review path.
 
-An `in_review` issue is stalled when it has no typed participant, no pending interaction or approval, no user owner, no active monitor, no active run, no queued wake, and no explicit recovery issue. Paperclip should surface that state as recovery work rather than silently completing the issue or leaving blocker chains parked indefinitely.
+An `in_review` issue is stalled when it has no typed participant, no pending interaction or approval, no user owner, no active monitor, no active run, no queued wake, and no explicit recovery action. Paperclip should surface that state as recovery work rather than silently completing the issue or leaving blocker chains parked indefinitely.
 
 ### Issue monitors
 
@@ -241,7 +266,7 @@ Monitors are not recurring intervals. When a monitor fires, Paperclip clears the
 
 Because `serviceName` and `notes` remain visible in issue activity and wake context, operators should keep them short and non-secret. Put enough context for the assignee to know what to inspect, but do not include signed URLs, bearer tokens, customer secrets, tenant-private identifiers, or provider links with embedded credentials.
 
-Monitor bounds are enforced. Paperclip rejects attempts to re-arm a monitor whose `timeoutAt` or `maxAttempts` is already exhausted. When a scheduled monitor reaches an exhausted bound at trigger time, Paperclip clears it and follows `recoveryPolicy`: `wake_owner` queues a bounded recovery wake for the assignee, `create_recovery_issue` opens visible recovery work, and `escalate_to_board` records a board-visible escalation comment/activity.
+Monitor bounds are enforced. Paperclip rejects attempts to re-arm a monitor whose `timeoutAt` or `maxAttempts` is already exhausted. When a scheduled monitor reaches an exhausted bound at trigger time, Paperclip clears it and follows `recoveryPolicy`: `wake_owner` queues a bounded recovery wake for the assignee, `create_recovery_issue` opens visible issue-backed recovery work, and `escalate_to_board` records a board-visible escalation comment/activity.
 
 Use `blocked` instead of a monitor when no Paperclip assignee owns a responsible polling path. In that case, name the external owner/action or create first-class recovery/blocker work.
 
@@ -252,12 +277,12 @@ This is explicit waiting state.
 A healthy `blocked` issue has an explicit waiting path:
 
 - first-class blockers exist, and each unresolved leaf has a valid action path under this contract
-- the issue is blocked on an explicit recovery issue that itself has a live or waiting path
+- the issue has an explicit recovery action that itself has a live or waiting path
 - the issue is waiting on a pending interaction, linked approval, human owner, or clearly named external owner/action
 
 A blocker chain is covered only when its unresolved leaf is live or explicitly waiting. An intermediate `blocked` issue does not make the chain healthy by itself.
 
-A `blocked` issue is stalled when the unresolved blocker leaf has no active run, queued wake, typed participant, pending interaction or approval, user owner, external owner/action, or recovery issue. In that case the parent should show the first stalled leaf instead of presenting the dependency as calmly covered.
+A `blocked` issue is stalled when the unresolved blocker leaf has no active run, queued wake, typed participant, pending interaction or approval, user owner, external owner/action, or recovery action. In that case the parent should show the first stalled leaf instead of presenting the dependency as calmly covered.
 
 ## 8. Crash and Restart Recovery
 
@@ -277,7 +302,7 @@ Example:
 Recovery rule:
 
 - if the latest issue-linked run failed/timed out/cancelled and no live execution path remains, Paperclip queues one automatic assignment recovery wake
-- if that recovery wake also finishes and the issue is still stranded, Paperclip moves the issue to `blocked` and posts a visible comment
+- if that recovery wake also finishes and the issue is still stranded, Paperclip moves the issue to `blocked` and opens or updates an explicit recovery action when a bounded owner/action is known; the visible comment is evidence, not the recovery path by itself
 
 This is a dispatch recovery, not a continuation recovery.
 
@@ -293,7 +318,7 @@ Example:
 Recovery rule:
 
 - Paperclip queues one automatic continuation wake
-- if that continuation wake also finishes and the issue is still stranded, Paperclip moves the issue to `blocked` and posts a visible comment
+- if that continuation wake also finishes and the issue is still stranded, Paperclip moves the issue to `blocked` and opens or updates an explicit recovery action when a bounded owner/action is known; the visible comment is evidence, not the recovery path by itself
 
 This is an active-work continuity recovery.
 
@@ -306,7 +331,7 @@ On startup and on the periodic recovery loop, Paperclip now does four things in
 1. reap orphaned `running` runs
 2. resume persisted `queued` runs
 3. reconcile stranded assigned work
-4. scan silent active runs and create or update explicit watchdog review issues
+4. scan silent active runs and create or update explicit watchdog recovery actions
 
 The stranded-work pass closes the gap where issue state survives a crash but the wake/run path does not. The silent-run scan covers the separate case where a live process exists but has stopped producing observable output.
 
@@ -319,11 +344,11 @@ The recovery service owns this contract:
 - classify active-run output silence as `ok`, `suspicious`, `critical`, `snoozed`, or `not_applicable`
 - collect bounded evidence from run logs, recent run events, child issues, and blockers
 - preserve redaction and truncation before evidence is written to issue descriptions
-- create at most one open `stale_active_run_evaluation` issue per run
+- create at most one open watchdog recovery action per run; issue-backed implementations use `stale_active_run_evaluation` issues
 - honor active snooze decisions before creating more review work
 - build the `outputSilence` summary shown by live-run and active-run API responses
 
-Suspicious silence creates a medium-priority review issue for the selected recovery owner. Critical silence raises that review issue to high priority and blocks the source issue on the explicit evaluation task without cancelling the active process.
+Suspicious silence creates a medium-priority watchdog recovery action for the selected recovery owner. Critical silence raises that recovery action to high priority and, when issue-backed evaluation is needed for correctness, blocks the source issue on the explicit evaluation task without cancelling the active process.
 
 Watchdog decisions are explicit operator/recovery-owner decisions:
 
@@ -333,7 +358,7 @@ Watchdog decisions are explicit operator/recovery-owner decisions:
 
 Operators should prefer `snooze` for known time-bounded quiet periods. `continue` is only a short acknowledgement of the current evidence; if the run remains silent after the re-arm window, the periodic watchdog scan can create or update review work again.
 
-The board can record watchdog decisions. The assigned owner of the watchdog evaluation issue can also record them. Other agents cannot.
+The board can record watchdog decisions. The assigned owner of an issue-backed watchdog evaluation can also record them. Other agents cannot.
 
 ## 11. Auto-Recover vs Explicit Recovery vs Human Escalation
 
@@ -351,9 +376,9 @@ Examples:
 
 Auto-recovery preserves the existing owner. It does not choose a replacement agent.
 
-### Explicit Recovery Issue
+### Explicit Recovery Action
 
-Paperclip creates an explicit recovery issue when the system can identify a problem but cannot safely complete the work itself.
+Paperclip opens an explicit recovery action when the system can identify a problem but cannot safely complete the work itself.
 
 Examples:
 
@@ -361,9 +386,11 @@ Examples:
 - a dependency graph has an invalid/uninvokable owner, unassigned blocker, or invalid review participant
 - an active run is silent past the watchdog threshold
 
-The source issue remains visible and blocked on the recovery issue when blocking is necessary for correctness. The recovery owner must restore a live path, resolve the source issue manually, or record the reason it is a false positive.
+The recovery action stays source-scoped by default. The source issue should show the recovery owner, cause, evidence, next action, and wake or monitor policy in its own thread/detail surface.
 
-Instance-level issue-graph liveness auto-recovery is disabled by default. When enabled, its lookback window means "dependency paths updated within the last N hours"; older findings remain advisory and are counted as outside the configured lookback instead of creating recovery issues automatically. This is an operator noise control, not the older staleness delay for determining whether a chain is old enough to surface.
+Create an issue-backed recovery action only when a separate issue is the right execution object. In that fallback form, the source issue remains visible and is blocked on the recovery issue when blocking is necessary for correctness. The recovery owner must restore a live path, resolve the source issue manually, delegate real follow-up work, or record the reason the signal is a false positive.
+
+Instance-level issue-graph liveness auto-recovery is disabled by default. When enabled, its lookback window means "dependency paths updated within the last N hours"; older findings remain advisory and are counted as outside the configured lookback instead of creating recovery actions automatically. This is an operator noise control, not the older staleness delay for determining whether a chain is old enough to surface.
 
 ### Human Escalation
 
@@ -391,7 +418,7 @@ The recovery model is intentionally conservative:
 
 - preserve ownership
 - retry once when the control plane lost execution continuity
-- create explicit recovery work when the system can identify a bounded recovery owner/action
+- open an explicit recovery action when the system can identify a bounded recovery owner/action
 - escalate visibly when the system cannot safely keep going
 
 ## 13. Practical Interpretation
diff --git a/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md b/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md
new file mode 100644
index 00000000..18b033e3
--- /dev/null
+++ b/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md
@@ -0,0 +1,136 @@
+# Local Plugin Development
+
+This is the short happy-path guide for developing a Paperclip plugin from a folder on your machine. You will scaffold a plugin, run it in watch mode, install it into a running Paperclip instance from an absolute local path, and edit code with the plugin worker reloading after each rebuild.
+
+For the full alpha surface — manifest fields, capabilities, managed agents/projects/routines, UI slots, scoped API routes — see [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md).
+
+## Prerequisites
+
+- Node.js 22+ and `pnpm`.
+- A local Paperclip checkout you can run from source. Local plugin installs read source from disk, so the running server must be able to see the path you give it.
+
+## The five steps
+
+```bash
+# 1. Start Paperclip locally
+pnpm paperclipai run
+
+# 2. Scaffold a plugin outside the Paperclip repo
+paperclipai plugin init @acme/hello-plugin --output ~/dev/paperclip-plugins
+
+# 3. Install dependencies and start the watch build
+cd ~/dev/paperclip-plugins/hello-plugin
+pnpm install
+pnpm dev
+
+# 4. In another terminal, install the plugin from its absolute path
+paperclipai plugin install ~/dev/paperclip-plugins/hello-plugin
+
+# 5. Confirm it loaded
+paperclipai plugin list
+paperclipai plugin inspect acme.hello-plugin
+```
+
+That's the loop. The rest of this page explains what each step does and what to expect when you edit code.
+
+### 1. Start Paperclip
+
+```bash
+pnpm paperclipai run
+```
+
+Paperclip listens on `http://127.0.0.1:3100` by default. The CLI talks to that server, so leave it running.
+
+### 2. Scaffold the plugin
+
+```bash
+paperclipai plugin init @acme/hello-plugin --output ~/dev/paperclip-plugins
+```
+
+This creates `~/dev/paperclip-plugins/hello-plugin/` with `src/manifest.ts`, `src/worker.ts`, `src/ui/index.tsx`, an esbuild watch config, a Vitest config, and a snapshot of `@paperclipai/plugin-sdk` from your local Paperclip checkout. You can run the package and tests without publishing anything to npm.
+
+Useful flags:
+
+- `--template <default|connector|workspace|environment>` — starter shape.
+- `--category <connector|workspace|automation|ui|environment>` — manifest category.
+- `--display-name`, `--description`, `--author` — manifest metadata.
+- `--sdk-path <absolute-path>` — point at a specific `packages/plugins/sdk` checkout if you have more than one.
+
+When `plugin init` finishes, it prints the next four commands literally. You can copy them.
+
+### 3. Install dependencies and run the watch build
+
+```bash
+cd ~/dev/paperclip-plugins/hello-plugin
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` runs `esbuild --watch` against the plugin source and emits `dist/manifest.js`, `dist/worker.js`, and `dist/ui/`. Leave it running. Every time you save, esbuild rebuilds the affected output file.
+
+If your plugin has UI and you want a browser-side dev server with hot module replacement during local UI iteration, run `pnpm dev:ui` in a second terminal. It serves `dist/ui/` on `http://127.0.0.1:4177`. This is optional; Paperclip can load the built UI directly from `dist/ui/` without it.
+
+### 4. Install from the absolute path
+
+```bash
+paperclipai plugin install ~/dev/paperclip-plugins/hello-plugin
+```
+
+The CLI auto-detects local paths (anything that looks absolute, starts with `./`, `../`, or `~`, or resolves to an existing folder relative to the current directory) and sends `{ isLocalPath: true }` to `POST /api/plugins/install` with the resolved absolute path. If you want to be explicit, pass `--local`.
+
+You will see a confirmation like:
+
+```
+Installing plugin from local path: /Users/you/dev/paperclip-plugins/hello-plugin
+✓ Installed acme.hello-plugin v0.1.0 (ready)
+Local plugin installs run trusted local code from your machine.
+Keep `pnpm dev` running in /Users/you/dev/paperclip-plugins/hello-plugin;
+Paperclip watches rebuilt dist output and reloads the plugin worker.
+```
+
+Relative paths are resolved against the current working directory, so `paperclipai plugin install .` from inside the plugin folder works too.
+
+### 5. Inspect
+
+```bash
+paperclipai plugin list
+paperclipai plugin inspect acme.hello-plugin
+```
+
+`list` shows plugin key, status, version, and short error. `inspect` prints the same record with the full last error if there is one. Both accept `--json` if you want to script against them.
+
+## Reload semantics, honestly
+
+Paperclip watches the on-disk plugin package after a local install. The watcher targets the runtime entrypoints declared in the package's `paperclipPlugin` field (`dist/manifest.js`, `dist/worker.js`, `dist/ui/`).
+
+What that means in practice:
+
+- **Worker code:** save a `.ts` file → esbuild rewrites `dist/worker.js` → Paperclip debounces ~500ms and restarts the plugin worker. The next worker call uses the new code. There is no in-process hot module replacement for worker code; it is a worker restart.
+- **Manifest:** save `src/manifest.ts` → `dist/manifest.js` rewrites → the worker restarts and the host re-reads the manifest.
+- **Plugin UI:** save a `.tsx` file → esbuild rewrites `dist/ui/` → Paperclip reloads the UI bundle on its next mount. To get HMR during UI iteration, run `pnpm dev:ui` and point at the dev server with `devUiUrl` in your manifest while developing.
+- **Without `pnpm dev`:** the watcher only fires on `dist/*` changes. If you stop the watch build, source edits do not reach Paperclip. Restart `pnpm dev` (or run `pnpm build` once) before expecting changes.
+- **`node_modules`, `.git`, `.paperclip-sdk`, and other dotfolders are ignored.** Adding a dependency requires the new code to actually be imported and rebuilt before the worker sees it.
+
+The server never compiles plugin source for you. The package's own build scripts own that step.
+
+## Local path plugins vs npm packages
+
+Both go through the same install endpoint, but they mean different things:
+
+- **Local path plugins are trusted local code.** Paperclip executes worker code from disk under the same trust boundary as the rest of the running instance. This is meant for developing or operating a plugin against a checkout you control. There is no signature check, no sandboxing of worker code, and no provenance metadata beyond the path. Do not install local-path plugins you did not write.
+- **npm packages are the deployable artifact.** `paperclipai plugin install @acme/plugin-foo` (optionally `--version 1.2.3`) installs from your configured npm registry, version-pins, and produces an install record that other operators can reproduce. Ship plugins this way.
+
+When you are done iterating locally, publish the package and reinstall the npm-package form so the install reflects what you will ship.
+
+## Common things to do next
+
+- **Restart cleanly:** `paperclipai plugin disable <key>` pauses the plugin without removing it. `paperclipai plugin enable <key>` brings it back. `paperclipai plugin uninstall <key>` removes the install record; add `--force` to also purge plugin state and settings.
+- **Browse examples:** `paperclipai plugin examples` lists the bundled example plugins that ship with the repo, each with a ready-to-run `paperclipai plugin install <path>` line.
+- **Go deeper:** [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md) covers worker capabilities, managed agents/projects/routines, plugin database namespaces, scoped API routes, and the shared UI components in `@paperclipai/plugin-sdk/ui`. [`PLUGIN_SPEC.md`](./PLUGIN_SPEC.md) is the longer-form specification, including future ideas that are not yet implemented.
+
+## Troubleshooting
+
+- **`Plugin install returned no plugin record` or `error` status.** Run `paperclipai plugin inspect <key>` for the last error. The most common causes are (1) the plugin has not built yet — run `pnpm dev` or `pnpm build` first, (2) the `paperclipPlugin` entries in `package.json` point at files that do not exist on disk, or (3) the manifest failed validation. The Paperclip server log has the full validation error.
+- **Edits do not seem to reload.** Confirm `pnpm dev` is still running and writing to `dist/`. If you renamed entry files, update the `paperclipPlugin.manifest` / `paperclipPlugin.worker` / `paperclipPlugin.ui` fields in `package.json` so the watcher targets them.
+- **Worker restarts but UI is stale.** Hard-reload the page. If you want HMR, run `pnpm dev:ui` and set `devUiUrl` in your manifest to `http://127.0.0.1:4177` during development.
+- **Path arguments fail on Windows.** Quote paths that contain spaces, and prefer absolute paths over `~`-prefixed paths in non-bash shells.
diff --git a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md b/doc/plugins/PLUGIN_AUTHORING_GUIDE.md
index fc43ae7b..eb20163b 100644
--- a/doc/plugins/PLUGIN_AUTHORING_GUIDE.md
+++ b/doc/plugins/PLUGIN_AUTHORING_GUIDE.md
@@ -4,6 +4,8 @@ This guide describes the current, implemented way to create a Paperclip plugin i
 
 It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec includes future ideas; this guide only covers the alpha surface that exists now.
 
+> **New to plugins?** Start with the short [Local Plugin Development guide](./LOCAL_PLUGIN_DEVELOPMENT.md) — it walks the CLI happy path (`plugin init` → `pnpm dev` → `plugin install <path>`) end to end. Come back here for the full manifest surface, worker capabilities, and UI components.
+
 ## Current reality
 
 - Treat plugin workers and plugin UI as trusted code.
@@ -20,23 +22,13 @@ It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec i
 
 ## Scaffold a plugin
 
-Use the scaffold package:
+Use the CLI scaffold command:
 
 ```bash
-pnpm --filter @paperclipai/create-paperclip-plugin build
-node packages/plugins/create-paperclip-plugin/dist/index.js @yourscope/plugin-name --output ./packages/plugins/examples
+paperclipai plugin init @yourscope/plugin-name --output /absolute/path/to/plugin-repos
 ```
 
-For a plugin that lives outside the Paperclip repo:
-
-```bash
-pnpm --filter @paperclipai/create-paperclip-plugin build
-node packages/plugins/create-paperclip-plugin/dist/index.js @yourscope/plugin-name \
-  --output /absolute/path/to/plugin-repos \
-  --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
-```
-
-That creates a package with:
+That creates `<output>/plugin-name/` with:
 
 - `src/manifest.ts`
 - `src/worker.ts`
@@ -47,11 +39,13 @@ That creates a package with:
 
 Inside this monorepo, the scaffold uses `workspace:*` for `@paperclipai/plugin-sdk`.
 
-Outside this monorepo, the scaffold snapshots `@paperclipai/plugin-sdk` from the local Paperclip checkout into a `.paperclip-sdk/` tarball so you can build and test a plugin without publishing anything to npm first.
+Outside this monorepo, the scaffold snapshots `@paperclipai/plugin-sdk` from the local Paperclip checkout into a `.paperclip-sdk/` tarball so you can build and test a plugin without publishing anything to npm first. Pass `--sdk-path /absolute/path/to/paperclip/packages/plugins/sdk` if you have more than one Paperclip checkout.
 
-## Recommended local workflow
+## Local development workflow
 
-From the generated plugin folder:
+See the short [Local Plugin Development guide](./LOCAL_PLUGIN_DEVELOPMENT.md) for the full happy path (`pnpm dev` → `paperclipai plugin install <absolute-path>` → `paperclipai plugin list`) and reload semantics.
+
+Minimum verification from the generated plugin folder:
 
 ```bash
 pnpm install
@@ -60,16 +54,6 @@ pnpm test
 pnpm build
 ```
 
-For local development, install it into Paperclip from an absolute local path through the plugin manager or API. The server supports local filesystem installs and watches local-path plugins for file changes so worker restarts happen automatically after rebuilds.
-
-Example:
-
-```bash
-curl -X POST http://127.0.0.1:3100/api/plugins/install \
-  -H "Content-Type: application/json" \
-  -d '{"packageName":"/absolute/path/to/your-plugin","isLocalPath":true}'
-```
-
 ## Supported alpha surface
 
 Worker:
diff --git a/packages/adapter-utils/src/sandbox-install-command.test.ts b/packages/adapter-utils/src/sandbox-install-command.test.ts
index 454d227e..01c32936 100644
--- a/packages/adapter-utils/src/sandbox-install-command.test.ts
+++ b/packages/adapter-utils/src/sandbox-install-command.test.ts
@@ -3,9 +3,17 @@ import { buildSandboxNpmInstallCommand } from "./sandbox-install-command.js";
 
 describe("buildSandboxNpmInstallCommand", () => {
   it("installs globally as root, via sudo when available, and under ~/.local otherwise", () => {
-    expect(buildSandboxNpmInstallCommand("@google/gemini-cli")).toBe(
-      'if [ "$(id -u)" -eq 0 ]; then npm install -g \'@google/gemini-cli\'; elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then sudo -E npm install -g \'@google/gemini-cli\'; else mkdir -p "$HOME/.local" && npm install -g --prefix "$HOME/.local" \'@google/gemini-cli\'; fi',
-    );
+    const command = buildSandboxNpmInstallCommand("@google/gemini-cli");
+    expect(command).toContain("if [ \"$(id -u)\" -eq 0 ]; then npm install -g '@google/gemini-cli';");
+    expect(command).toContain("sudo -E npm install -g '@google/gemini-cli'");
+    expect(command).toContain("npm install -g --prefix \"$HOME/.local\" '@google/gemini-cli'");
+  });
+
+  it("bootstraps npm from a portable Node tarball when missing", () => {
+    const command = buildSandboxNpmInstallCommand("@google/gemini-cli");
+    expect(command).toContain("if ! command -v npm >/dev/null 2>&1; then");
+    expect(command).toContain("https://nodejs.org/dist/");
+    expect(command).toContain('export PATH="$HOME/.local/bin:$PATH"');
   });
 
   it("shell-quotes package names", () => {
diff --git a/packages/adapter-utils/src/sandbox-install-command.ts b/packages/adapter-utils/src/sandbox-install-command.ts
index ceede21d..d8ef0767 100644
--- a/packages/adapter-utils/src/sandbox-install-command.ts
+++ b/packages/adapter-utils/src/sandbox-install-command.ts
@@ -2,10 +2,40 @@ function shellSingleQuote(value: string): string {
   return `'${value.replaceAll("'", `'\"'\"'`)}'`;
 }
 
+// Bootstrap a usable npm when the sandbox image ships without one (e.g. the
+// default exe.dev VM image has sshd + a normal user homedir but no Node
+// toolchain). We install a portable Node tarball into $HOME/.local rather
+// than using apt-get because the distro-packaged Node is often old enough to
+// reject modern JS syntax (regex /v flag, etc.) used by adapter CLIs like
+// @google/gemini-cli. The bootstrap also sets PAPERCLIP_NPM_BOOTSTRAPPED=1
+// so the install step knows to skip sudo — sudo would reset PATH via
+// secure_path and lose visibility of the freshly-installed npm in
+// $HOME/.local/bin.
+const ENSURE_NPM_PREAMBLE =
+  "PAPERCLIP_NPM_BOOTSTRAPPED=; " +
+  'if ! command -v npm >/dev/null 2>&1; then ' +
+  'NODE_ARCH="$(uname -m)"; ' +
+  'case "$NODE_ARCH" in ' +
+  "x86_64) NODE_ARCH=x64 ;; " +
+  "aarch64|arm64) NODE_ARCH=arm64 ;; " +
+  "esac; " +
+  'NODE_VERSION="v22.11.0"; ' +
+  'NODE_TARBALL="node-${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz"; ' +
+  'mkdir -p "$HOME/.local"; ' +
+  'curl -fsSL "https://nodejs.org/dist/${NODE_VERSION}/${NODE_TARBALL}" -o "/tmp/${NODE_TARBALL}" && ' +
+  'tar -xJf "/tmp/${NODE_TARBALL}" -C "$HOME/.local" --strip-components=1 && ' +
+  'rm -f "/tmp/${NODE_TARBALL}" && ' +
+  'export PATH="$HOME/.local/bin:$PATH" && ' +
+  "PAPERCLIP_NPM_BOOTSTRAPPED=1; " +
+  "fi;";
+
 export function buildSandboxNpmInstallCommand(packageName: string): string {
   const quotedPackageName = shellSingleQuote(packageName);
   return [
-    'if [ "$(id -u)" -eq 0 ]; then',
+    ENSURE_NPM_PREAMBLE,
+    'if [ -n "$PAPERCLIP_NPM_BOOTSTRAPPED" ]; then',
+    `npm install -g ${quotedPackageName};`,
+    'elif [ "$(id -u)" -eq 0 ]; then',
     `npm install -g ${quotedPackageName};`,
     'elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then',
     `sudo -E npm install -g ${quotedPackageName};`,
diff --git a/packages/adapter-utils/src/workspace-restore-merge.test.ts b/packages/adapter-utils/src/workspace-restore-merge.test.ts
index 32ad9582..ff0a5a12 100644
--- a/packages/adapter-utils/src/workspace-restore-merge.test.ts
+++ b/packages/adapter-utils/src/workspace-restore-merge.test.ts
@@ -1,4 +1,5 @@
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
@@ -58,4 +59,26 @@ describe("workspace restore merge", () => {
       readFile(path.join(targetDir, "manual-qa", "environment-matrix", "ssh", "codex_local.md"), "utf8"),
     ).resolves.toBe("ssh codex\n");
   });
+
+  it("ignores non-file entries when capturing snapshots", async () => {
+    if (process.platform === "win32") return;
+
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-restore-merge-"));
+    cleanupDirs.push(rootDir);
+    const socketPath = path.join(rootDir, "runtime.sock");
+    const server = net.createServer();
+
+    try {
+      await new Promise<void>((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(socketPath, resolve);
+      });
+
+      const snapshot = await captureDirectorySnapshot(rootDir, { exclude: [] });
+
+      expect(snapshot.entries.has("runtime.sock")).toBe(false);
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
 });
diff --git a/packages/adapter-utils/src/workspace-restore-merge.ts b/packages/adapter-utils/src/workspace-restore-merge.ts
index df75b236..e89023e2 100644
--- a/packages/adapter-utils/src/workspace-restore-merge.ts
+++ b/packages/adapter-utils/src/workspace-restore-merge.ts
@@ -47,6 +47,10 @@ async function walkDirectory(
 
     const fullPath = path.join(root, nextRelative);
     const stats = await fs.lstat(fullPath);
+    if (!stats.isDirectory() && !stats.isSymbolicLink() && !stats.isFile()) {
+      continue;
+    }
+
     if (stats.isDirectory()) {
       out.set(nextRelative, { kind: "dir" });
       await walkDirectory(root, exclude, nextRelative, out);
@@ -87,6 +91,8 @@ async function readSnapshotEntry(root: string, relative: string): Promise<Snapsh
       target: await fs.readlink(fullPath),
     };
   }
+  if (!stats.isFile()) return null;
+
   return {
     kind: "file",
     mode: stats.mode,
diff --git a/packages/adapters/claude-local/src/server/execute.ts b/packages/adapters/claude-local/src/server/execute.ts
index 828d686f..067f68cd 100644
--- a/packages/adapters/claude-local/src/server/execute.ts
+++ b/packages/adapters/claude-local/src/server/execute.ts
@@ -89,6 +89,15 @@ interface ClaudeRuntimeConfig {
   extraArgs: string[];
 }
 
+export function claudeSessionCwdMatchesExecutionTarget(input: {
+  runtimeSessionCwd: string;
+  effectiveExecutionCwd: string;
+  executionTargetIsRemote: boolean;
+}): boolean {
+  if (input.executionTargetIsRemote || input.runtimeSessionCwd.length === 0) return true;
+  return path.resolve(input.runtimeSessionCwd) === path.resolve(input.effectiveExecutionCwd);
+}
+
 function buildLoginResult(input: {
   proc: RunProcessResult;
   loginUrl: string | null;
@@ -591,7 +600,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const canResumeSession =
     runtimeSessionId.length > 0 &&
     hasMatchingPromptBundle &&
-    (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
+    claudeSessionCwdMatchesExecutionTarget({
+      runtimeSessionCwd,
+      effectiveExecutionCwd,
+      executionTargetIsRemote,
+    }) &&
     adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
   const sessionId = canResumeSession ? runtimeSessionId : null;
   if (
@@ -853,7 +866,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     const resolvedSessionParams = resolvedSessionId
       ? ({
         sessionId: resolvedSessionId,
-        cwd: effectiveExecutionCwd,
+        cwd,
         promptBundleKey: promptBundle.bundleKey,
         ...(executionTargetIsRemote
           ? {
diff --git a/packages/adapters/claude-local/src/server/index.ts b/packages/adapters/claude-local/src/server/index.ts
index 6c5c2782..7fcf0c11 100644
--- a/packages/adapters/claude-local/src/server/index.ts
+++ b/packages/adapters/claude-local/src/server/index.ts
@@ -1,4 +1,4 @@
-export { execute, runClaudeLogin } from "./execute.js";
+export { claudeSessionCwdMatchesExecutionTarget, execute, runClaudeLogin } from "./execute.js";
 export { listClaudeSkills, syncClaudeSkills } from "./skills.js";
 export { listClaudeModels } from "./models.js";
 export { testEnvironment } from "./test.js";
diff --git a/packages/adapters/gemini-local/src/index.ts b/packages/adapters/gemini-local/src/index.ts
index 68ca627d..626266b0 100644
--- a/packages/adapters/gemini-local/src/index.ts
+++ b/packages/adapters/gemini-local/src/index.ts
@@ -1,9 +1,12 @@
-import type { AdapterModelProfileDefinition } from "@paperclipai/adapter-utils";
+import {
+  buildSandboxNpmInstallCommand,
+  type AdapterModelProfileDefinition,
+} from "@paperclipai/adapter-utils";
 
 export const type = "gemini_local";
 export const label = "Gemini CLI (local)";
 
-export const SANDBOX_INSTALL_COMMAND = "npm install -g @google/gemini-cli";
+export const SANDBOX_INSTALL_COMMAND = buildSandboxNpmInstallCommand("@google/gemini-cli");
 
 export const DEFAULT_GEMINI_LOCAL_MODEL = "auto";
 
diff --git a/packages/adapters/opencode-local/src/index.ts b/packages/adapters/opencode-local/src/index.ts
index 3bd30518..6f36e378 100644
--- a/packages/adapters/opencode-local/src/index.ts
+++ b/packages/adapters/opencode-local/src/index.ts
@@ -8,9 +8,15 @@ export const label = "OpenCode (local)";
 // (linux-x64, linux-x64-musl, linux-x64-baseline, linux-x64-baseline-musl) in
 // parallel even though only one matches the sandbox; on bandwidth-constrained
 // sandboxes (e.g. Cloudflare) that exceeded the 240s install budget. The
-// official installer fetches a single arch-specific binary and adds
-// `$HOME/.opencode/bin` to PATH via `~/.bashrc`, which sandbox `sh -lc`
-// invocations source.
+// official installer fetches a single arch-specific binary into
+// `$HOME/.opencode/bin` and tries to add it to PATH via `~/.bashrc`. That
+// rc-file path is only sourced by interactive/login shells, so non-login
+// `sh -c` probe invocations (used by the runtime PATH check) cannot find the
+// binary. We fix that by symlinking the installed binary into a directory on
+// the non-login `sh -c` PATH: prefer `/usr/local/bin` (universally on the
+// default PATH on Linux distros) when root or passwordless sudo is available,
+// otherwise fall back to `$HOME/.local/bin` (which is on the default PATH on
+// the exe.dev sandbox image and most modern home-managed Linux images).
 //
 // Security tradeoff: this is `curl | bash` without a SHA-256 verification of
 // the install script. We accept this because:
@@ -25,7 +31,18 @@ export const label = "OpenCode (local)";
 // shell) and `curl -fsSL` give us fail-fast behavior on HTTP errors. If
 // OpenCode starts publishing a stable checksum/signature, switch to fetching
 // a versioned tarball + verifying the digest before exec.
-export const SANDBOX_INSTALL_COMMAND = "curl -fsSL https://opencode.ai/install | bash";
+export const SANDBOX_INSTALL_COMMAND =
+  'curl -fsSL https://opencode.ai/install | bash && ' +
+  'if [ -x "$HOME/.opencode/bin/opencode" ]; then ' +
+  'if [ "$(id -u)" -eq 0 ]; then ' +
+  'ln -sf "$HOME/.opencode/bin/opencode" /usr/local/bin/opencode; ' +
+  'elif command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then ' +
+  'sudo ln -sf "$HOME/.opencode/bin/opencode" /usr/local/bin/opencode; ' +
+  'else ' +
+  'mkdir -p "$HOME/.local/bin" && ' +
+  'ln -sf "$HOME/.opencode/bin/opencode" "$HOME/.local/bin/opencode"; ' +
+  'fi; ' +
+  'fi';
 
 export const DEFAULT_OPENCODE_LOCAL_MODEL = "openai/gpt-5.2-codex";
 
diff --git a/packages/db/src/migrations/0084_issue_recovery_actions.sql b/packages/db/src/migrations/0084_issue_recovery_actions.sql
new file mode 100644
index 00000000..6bce0bf5
--- /dev/null
+++ b/packages/db/src/migrations/0084_issue_recovery_actions.sql
@@ -0,0 +1,64 @@
+CREATE TABLE IF NOT EXISTS "issue_recovery_actions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"source_issue_id" uuid NOT NULL,
+	"recovery_issue_id" uuid,
+	"kind" text NOT NULL,
+	"status" text DEFAULT 'active' NOT NULL,
+	"owner_type" text DEFAULT 'agent' NOT NULL,
+	"owner_agent_id" uuid,
+	"owner_user_id" text,
+	"previous_owner_agent_id" uuid,
+	"return_owner_agent_id" uuid,
+	"cause" text NOT NULL,
+	"fingerprint" text NOT NULL,
+	"evidence" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"next_action" text NOT NULL,
+	"wake_policy" jsonb,
+	"monitor_policy" jsonb,
+	"attempt_count" integer DEFAULT 0 NOT NULL,
+	"max_attempts" integer,
+	"timeout_at" timestamp with time zone,
+	"last_attempt_at" timestamp with time zone,
+	"outcome" text,
+	"resolution_note" text,
+	"resolved_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_company_id_companies_id_fk') THEN
+		ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;
+	END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_source_issue_id_issues_id_fk') THEN
+		ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_recovery_issue_id_issues_id_fk') THEN
+		ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_recovery_issue_id_issues_id_fk" FOREIGN KEY ("recovery_issue_id") REFERENCES "public"."issues"("id") ON DELETE set null ON UPDATE no action;
+	END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_owner_agent_id_agents_id_fk') THEN
+		ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_owner_agent_id_agents_id_fk" FOREIGN KEY ("owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+	END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_previous_owner_agent_id_agents_id_fk') THEN
+		ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_previous_owner_agent_id_agents_id_fk" FOREIGN KEY ("previous_owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+	END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'issue_recovery_actions_return_owner_agent_id_agents_id_fk') THEN
+		ALTER TABLE "issue_recovery_actions" ADD CONSTRAINT "issue_recovery_actions_return_owner_agent_id_agents_id_fk" FOREIGN KEY ("return_owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+	END IF;
+END $$;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "issue_recovery_actions_company_source_status_idx" ON "issue_recovery_actions" USING btree ("company_id","source_issue_id","status");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "issue_recovery_actions_company_owner_status_idx" ON "issue_recovery_actions" USING btree ("company_id","owner_agent_id","status");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "issue_recovery_actions_company_recovery_issue_idx" ON "issue_recovery_actions" USING btree ("company_id","recovery_issue_id");--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "issue_recovery_actions_active_source_uq" ON "issue_recovery_actions" USING btree ("company_id","source_issue_id") WHERE "issue_recovery_actions"."status" in ('active', 'escalated');--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "issue_recovery_actions_active_fingerprint_uq" ON "issue_recovery_actions" USING btree ("company_id","source_issue_id","cause","fingerprint") WHERE "issue_recovery_actions"."status" in ('active', 'escalated');
diff --git a/packages/db/src/migrations/meta/_journal.json b/packages/db/src/migrations/meta/_journal.json
index 74214acd..9d124c7d 100644
--- a/packages/db/src/migrations/meta/_journal.json
+++ b/packages/db/src/migrations/meta/_journal.json
@@ -589,6 +589,13 @@
       "when": 1778074536410,
       "tag": "0083_company_secret_provider_configs",
       "breakpoints": true
+    },
+    {
+      "idx": 84,
+      "version": "7",
+      "when": 1778355326070,
+      "tag": "0084_issue_recovery_actions",
+      "breakpoints": true
     }
   ]
 }
diff --git a/packages/db/src/schema/index.ts b/packages/db/src/schema/index.ts
index 9099f904..fdf5f7cb 100644
--- a/packages/db/src/schema/index.ts
+++ b/packages/db/src/schema/index.ts
@@ -29,6 +29,7 @@ export { workspaceRuntimeServices } from "./workspace_runtime_services.js";
 export { projectGoals } from "./project_goals.js";
 export { goals } from "./goals.js";
 export { issues } from "./issues.js";
+export { issueRecoveryActions } from "./issue_recovery_actions.js";
 export { issueReferenceMentions } from "./issue_reference_mentions.js";
 export { issueRelations } from "./issue_relations.js";
 export { routines, routineRevisions, routineTriggers, routineRuns } from "./routines.js";
diff --git a/packages/db/src/schema/issue_recovery_actions.ts b/packages/db/src/schema/issue_recovery_actions.ts
new file mode 100644
index 00000000..9c65a648
--- /dev/null
+++ b/packages/db/src/schema/issue_recovery_actions.ts
@@ -0,0 +1,68 @@
+import { sql } from "drizzle-orm";
+import {
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+import { issues } from "./issues.js";
+
+export const issueRecoveryActions = pgTable(
+  "issue_recovery_actions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    sourceIssueId: uuid("source_issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
+    recoveryIssueId: uuid("recovery_issue_id").references(() => issues.id, { onDelete: "set null" }),
+    kind: text("kind").notNull(),
+    status: text("status").notNull().default("active"),
+    ownerType: text("owner_type").notNull().default("agent"),
+    ownerAgentId: uuid("owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    ownerUserId: text("owner_user_id"),
+    previousOwnerAgentId: uuid("previous_owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    returnOwnerAgentId: uuid("return_owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    cause: text("cause").notNull(),
+    fingerprint: text("fingerprint").notNull(),
+    evidence: jsonb("evidence").$type<Record<string, unknown>>().notNull().default({}),
+    nextAction: text("next_action").notNull(),
+    wakePolicy: jsonb("wake_policy").$type<Record<string, unknown>>(),
+    monitorPolicy: jsonb("monitor_policy").$type<Record<string, unknown>>(),
+    attemptCount: integer("attempt_count").notNull().default(0),
+    maxAttempts: integer("max_attempts"),
+    timeoutAt: timestamp("timeout_at", { withTimezone: true }),
+    lastAttemptAt: timestamp("last_attempt_at", { withTimezone: true }),
+    outcome: text("outcome"),
+    resolutionNote: text("resolution_note"),
+    resolvedAt: timestamp("resolved_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companySourceStatusIdx: index("issue_recovery_actions_company_source_status_idx").on(
+      table.companyId,
+      table.sourceIssueId,
+      table.status,
+    ),
+    companyOwnerStatusIdx: index("issue_recovery_actions_company_owner_status_idx").on(
+      table.companyId,
+      table.ownerAgentId,
+      table.status,
+    ),
+    companyRecoveryIssueIdx: index("issue_recovery_actions_company_recovery_issue_idx").on(
+      table.companyId,
+      table.recoveryIssueId,
+    ),
+    activeSourceIdx: uniqueIndex("issue_recovery_actions_active_source_uq")
+      .on(table.companyId, table.sourceIssueId)
+      .where(sql`${table.status} in ('active', 'escalated')`),
+    activeFingerprintIdx: uniqueIndex("issue_recovery_actions_active_fingerprint_uq")
+      .on(table.companyId, table.sourceIssueId, table.cause, table.fingerprint)
+      .where(sql`${table.status} in ('active', 'escalated')`),
+  }),
+);
diff --git a/packages/db/src/test-embedded-postgres.ts b/packages/db/src/test-embedded-postgres.ts
index 11ab9669..87db5cde 100644
--- a/packages/db/src/test-embedded-postgres.ts
+++ b/packages/db/src/test-embedded-postgres.ts
@@ -111,11 +111,15 @@ function formatEmbeddedPostgresError(error: unknown): string {
 }
 
 async function probeEmbeddedPostgresSupport(): Promise<EmbeddedPostgresTestSupport> {
-  const { dataDir, instance } = await createEmbeddedPostgresTestInstance(
-    "paperclip-embedded-postgres-probe-",
-  );
+  let dataDir: string | null = null;
+  let instance: EmbeddedPostgresInstance | null = null;
 
   try {
+    const created = await createEmbeddedPostgresTestInstance(
+      "paperclip-embedded-postgres-probe-",
+    );
+    dataDir = created.dataDir;
+    instance = created.instance;
     await instance.initialise();
     await instance.start();
     return { supported: true };
@@ -125,8 +129,8 @@ async function probeEmbeddedPostgresSupport(): Promise<EmbeddedPostgresTestSuppo
       reason: formatEmbeddedPostgresError(error),
     };
   } finally {
-    await instance.stop().catch(() => {});
-    cleanupEmbeddedPostgresTestDirs(dataDir);
+    await instance?.stop().catch(() => {});
+    if (dataDir) cleanupEmbeddedPostgresTestDirs(dataDir);
   }
 }
 
@@ -140,9 +144,14 @@ export async function getEmbeddedPostgresTestSupport(): Promise<EmbeddedPostgres
 export async function startEmbeddedPostgresTestDatabase(
   tempDirPrefix: string,
 ): Promise<EmbeddedPostgresTestDatabase> {
-  const { dataDir, port, instance } = await createEmbeddedPostgresTestInstance(tempDirPrefix);
+  let dataDir: string | null = null;
+  let instance: EmbeddedPostgresInstance | null = null;
 
   try {
+    const created = await createEmbeddedPostgresTestInstance(tempDirPrefix);
+    dataDir = created.dataDir;
+    instance = created.instance;
+    const { port } = created;
     await instance.initialise();
     await instance.start();
 
@@ -154,13 +163,13 @@ export async function startEmbeddedPostgresTestDatabase(
     return {
       connectionString,
       cleanup: async () => {
-        await instance.stop().catch(() => {});
-        cleanupEmbeddedPostgresTestDirs(dataDir);
+        await instance?.stop().catch(() => {});
+        if (dataDir) cleanupEmbeddedPostgresTestDirs(dataDir);
       },
     };
   } catch (error) {
-    await instance.stop().catch(() => {});
-    cleanupEmbeddedPostgresTestDirs(dataDir);
+    await instance?.stop().catch(() => {});
+    if (dataDir) cleanupEmbeddedPostgresTestDirs(dataDir);
     throw new Error(
       `Failed to start embedded PostgreSQL test database: ${formatEmbeddedPostgresError(error)}`,
     );
diff --git a/packages/plugins/create-paperclip-plugin/src/index.ts b/packages/plugins/create-paperclip-plugin/src/index.ts
index 5fc17b05..099cb57e 100644
--- a/packages/plugins/create-paperclip-plugin/src/index.ts
+++ b/packages/plugins/create-paperclip-plugin/src/index.ts
@@ -62,6 +62,11 @@ function toPosixPath(value: string): string {
   return value.split(path.sep).join("/");
 }
 
+export function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_/:=.,@%+-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, "'\"'\"'")}'`;
+}
+
 function formatFileDependency(absPath: string): string {
   return `file:${toPosixPath(path.resolve(absPath))}`;
 }
@@ -312,7 +317,8 @@ const manifest: PaperclipPluginManifestV1 = {
   capabilities: [
     "environment.drivers.register",
     "plugin.state.read",
-    "plugin.state.write"
+    "plugin.state.write",
+    "ui.dashboardWidget.register"
   ],
   entrypoints: {
     worker: "./dist/worker.js",
@@ -467,6 +473,11 @@ const BASE_PARAMS = {
 };
 
 describe("environment plugin scaffold", () => {
+  it("declares capabilities for its manifest features", () => {
+    expect(manifest.capabilities).toContain("environment.drivers.register");
+    expect(manifest.capabilities).toContain("ui.dashboardWidget.register");
+  });
+
   it("validates config", async () => {
     const driver = createFakeEnvironmentDriver({ driverKey: BASE_PARAMS.driverKey });
     const harness = createEnvironmentTestHarness({ manifest, environmentDriver: driver });
@@ -533,7 +544,8 @@ const manifest: PaperclipPluginManifestV1 = {
   capabilities: [
     "events.subscribe",
     "plugin.state.read",
-    "plugin.state.write"
+    "plugin.state.write",
+    "ui.dashboardWidget.register"
   ],
   entrypoints: {
     worker: "./dist/worker.js",
@@ -623,6 +635,11 @@ import manifest from "../src/manifest.js";
 import plugin from "../src/worker.js";
 
 describe("plugin scaffold", () => {
+  it("declares capabilities for its manifest features", () => {
+    expect(manifest.capabilities).toContain("events.subscribe");
+    expect(manifest.capabilities).toContain("ui.dashboardWidget.register");
+  });
+
   it("registers data + actions and handles events", async () => {
     const harness = createTestHarness({ manifest, capabilities: [...manifest.capabilities, "events.emit"] });
     await plugin.definition.setup(harness.ctx);
@@ -656,6 +673,11 @@ pnpm dev:ui         # local dev server with hot-reload events
 pnpm test
 \`\`\`
 
+\`pnpm dev\` rebuilds the worker, manifest, and UI bundles into \`dist/\`.
+When this package is installed from a local path, Paperclip watches that rebuilt
+output and reloads the plugin worker. Local installs run trusted code from this
+folder on your machine.
+
 ${sdkDependency.startsWith("file:")
   ? `This scaffold snapshots \`@paperclipai/plugin-sdk\` and \`@paperclipai/shared\` from a local Paperclip checkout at:\n\n\`${toPosixPath(localSdkPath)}\`\n\nThe packed tarballs live in \`.paperclip-sdk/\` for local development. Before publishing this plugin, switch those dependencies to published package versions once they are available on npm.\n\n`
   : ""}
@@ -663,9 +685,7 @@ ${sdkDependency.startsWith("file:")
 ## Install Into Paperclip
 
 \`\`\`bash
-curl -X POST http://127.0.0.1:3100/api/plugins/install \\
-  -H "Content-Type: application/json" \\
-  -d '{"packageName":"${toPosixPath(outputDir)}","isLocalPath":true}'
+paperclipai plugin install ${shellQuote(toPosixPath(outputDir))}
 \`\`\`
 
 ## Build Options
diff --git a/packages/plugins/examples/plugin-authoring-smoke-example/src/manifest.ts b/packages/plugins/examples/plugin-authoring-smoke-example/src/manifest.ts
index eb1c1efe..725c4dbf 100644
--- a/packages/plugins/examples/plugin-authoring-smoke-example/src/manifest.ts
+++ b/packages/plugins/examples/plugin-authoring-smoke-example/src/manifest.ts
@@ -11,7 +11,8 @@ const manifest: PaperclipPluginManifestV1 = {
   capabilities: [
     "events.subscribe",
     "plugin.state.read",
-    "plugin.state.write"
+    "plugin.state.write",
+    "ui.dashboardWidget.register"
   ],
   entrypoints: {
     worker: "./dist/worker.js",
diff --git a/packages/plugins/examples/plugin-authoring-smoke-example/tests/plugin.spec.ts b/packages/plugins/examples/plugin-authoring-smoke-example/tests/plugin.spec.ts
index 8dddda88..9f0451b0 100644
--- a/packages/plugins/examples/plugin-authoring-smoke-example/tests/plugin.spec.ts
+++ b/packages/plugins/examples/plugin-authoring-smoke-example/tests/plugin.spec.ts
@@ -4,6 +4,11 @@ import manifest from "../src/manifest.js";
 import plugin from "../src/worker.js";
 
 describe("plugin scaffold", () => {
+  it("declares capabilities for its manifest features", () => {
+    expect(manifest.capabilities).toContain("events.subscribe");
+    expect(manifest.capabilities).toContain("ui.dashboardWidget.register");
+  });
+
   it("registers data + actions and handles events", async () => {
     const harness = createTestHarness({ manifest, capabilities: [...manifest.capabilities, "events.emit"] });
     await plugin.definition.setup(harness.ctx);
diff --git a/packages/plugins/plugin-llm-wiki/.gitignore b/packages/plugins/plugin-llm-wiki/.gitignore
new file mode 100644
index 00000000..d9e2126a
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/.gitignore
@@ -0,0 +1,4 @@
+dist
+node_modules
+.paperclip-sdk
+screenshots
diff --git a/packages/plugins/plugin-llm-wiki/README.md b/packages/plugins/plugin-llm-wiki/README.md
new file mode 100644
index 00000000..6e0aabd4
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/README.md
@@ -0,0 +1,160 @@
+# LLM Wiki
+
+Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows.
+
+## Scope
+
+This package is the standalone home for LLM Wiki behavior. Wiki-specific routes,
+UI, prompts, tools, local-folder templates, migrations, fixtures, and tests live
+here rather than in Paperclip core.
+
+The alpha surface includes:
+
+- manifest-declared Wiki page, sidebar entry, and settings page
+- trusted local folder declaration for `raw/`, `wiki/`, `AGENTS.md`, `IDEA.md`, `wiki/index.md`, and `wiki/log.md`
+- plugin database namespace migration for wiki instances, sources, pages, operations, query sessions, and resource bindings
+- managed `Wiki Maintainer` agent, managed `LLM Wiki` project, and paused managed routines for wiki update processing, lint, and index refresh
+- plugin-operation issue creation using `surfaceVisibility: "plugin_operation"`
+- local source capture into `raw/` with metadata rows in the plugin DB namespace
+- opt-in company-scoped Paperclip event ingestion controls for issues, comments, and documents; event ingestion is disabled by default and routes captured raw provenance into the default space only
+- manual Paperclip project/root issue distillation and bounded backfill actions with explicit work items, operation issues, source caps, and estimated cost recording
+- Paperclip-derived distillation (cursor windows, manual `distill-now`, backfill) always writes into the default wiki space in Phase 1; non-default spaces remain on manual / raw-file ingest until per-space Paperclip ingestion profiles ship
+- Paperclip-derived distillation maintains `wiki/projects/<slug>/standup.md` as the executive current-state view for each represented project, alongside durable `wiki/projects/<slug>/index.md` knowledge pages
+- wiki page writes with plugin path validation, atomic local-folder writes, metadata/revision rows, backlink extraction, and optional stale-hash protection
+- wiki tools for search/read/write/propose patch/source/log/index/backlinks workflows
+
+## Phase 5 Security Gate
+
+Paperclip-derived text ingestion stays limited to issue titles/descriptions, issue comments, and issue documents.
+
+- Issue attachments/assets are **metadata-only** in Phase 5.
+- Issue work products are **metadata-only** in Phase 5.
+- The wiki must not fetch `/api/assets/:id/content`, dereference work-product `url` fields, or store those capability-bearing links in source bundles/snapshots.
+
+The accepted policy lives in [doc/plans/2026-05-06-llm-wiki-paperclip-asset-security-gate.md](../../../doc/plans/2026-05-06-llm-wiki-paperclip-asset-security-gate.md).
+
+## Development
+
+```bash
+pnpm install
+pnpm dev            # watch builds
+pnpm dev:ui         # local dev server with hot-reload events
+pnpm test
+```
+
+From the Paperclip repo root:
+
+```bash
+pnpm --filter @paperclipai/plugin-llm-wiki typecheck
+pnpm --filter @paperclipai/plugin-llm-wiki test
+pnpm --filter @paperclipai/plugin-llm-wiki build
+```
+
+## Alpha Verification
+
+Run these commands from the Paperclip repo root before handing off alpha plugin
+changes:
+
+```bash
+pnpm --filter @paperclipai/plugin-llm-wiki typecheck
+pnpm --filter @paperclipai/plugin-llm-wiki test
+pnpm --filter @paperclipai/plugin-llm-wiki build
+```
+
+The focused Vitest suite covers:
+
+- standalone package boundaries and package-local harness dependencies
+- required local folder bootstrap writes
+- raw source capture plus ingest metadata persistence
+- hidden plugin-operation issue creation for ingest/query/file-as-page workflows
+- disabled and enabled Paperclip event ingestion paths
+- managed routine declarations, manual distill/backfill work items, source cap handling, and backfill project/date scoping
+- atomic page writes, metadata/revision rows, backlinks, and stale-hash refusal
+- query session creation, run-id recording, stream event forwarding, and completion updates
+- filing a streamed query answer back into the wiki through a hidden operation
+
+Remaining alpha gaps:
+
+- Browser screenshot capture is maintained separately under `tests/screenshots`;
+  generated `screenshots/` outputs are local artifacts and are ignored by git.
+- Host-level plugin install and live agent invocation still need Paperclip
+  server/runtime smoke coverage when preparing a release candidate.
+
+
+
+## Install Into Paperclip
+
+```bash
+curl -X POST http://127.0.0.1:3100/api/plugins/install \
+  -H "Content-Type: application/json" \
+  -d '{"packageName":"/Users/dotta/paperclip/.paperclip/worktrees/PAP-3179-design-a-llm-wiki-plugin/packages/plugins/plugin-llm-wiki","isLocalPath":true}'
+```
+
+## Build Options
+
+- `pnpm build` uses esbuild presets from `@paperclipai/plugin-sdk/bundlers`.
+- `pnpm build:rollup` uses rollup presets from the same SDK.
+
+After changing manifest-loaded assets such as skills, agent instructions, or
+templates, recompile the local plugin before re-enabling it:
+
+```bash
+pnpm --filter @paperclipai/plugin-llm-wiki build
+```
+
+The package-local `dist/` directory is ignored by git, but local Paperclip
+installs load the compiled `dist/manifest.js` and `dist/worker.js` files at
+runtime. If activation failed before the rebuild, re-enable the plugin or
+restart the Paperclip dev server so the host imports the fresh bundle.
+
+## Local File Layout
+
+```text
+<configured-wiki-root>/
+  AGENTS.md
+  IDEA.md
+  .gitignore
+  raw/
+    .gitkeep
+  wiki/
+    index.md
+    log.md
+    sources/
+      .gitkeep
+    projects/
+      .gitkeep
+      <project-slug>/
+        index.md
+        standup.md
+        decisions.md
+        history.md
+    entities/
+      .gitkeep
+    concepts/
+      .gitkeep
+    synthesis/
+      .gitkeep
+```
+
+Use the settings page or `bootstrap-root` action to configure the folder and
+write the starter files. The plugin uses Paperclip's local folder API for path
+containment, symlink checks, read/write validation, and atomic writes.
+
+Bootstrap preserves existing files rather than overwriting operator edits. The
+default first-install skeleton is copied from the vanilla LLM Wiki layout, with
+`CLAUDE.md` renamed to `AGENTS.md` and Paperclip project overviews, standups,
+decisions, and history kept together under `wiki/projects/<slug>/`.
+
+## Managed Agent Instructions
+
+Plugin-managed agent instruction bundles live under:
+
+```text
+agents/<agent-key>/AGENTS.md
+```
+
+For this plugin the Wiki Maintainer source bundle is `agents/wiki-maintainer/AGENTS.md`.
+Any additional files in that folder are installed as sibling instruction files
+for the managed agent. The settings health check reports drift from these
+defaults, and resetting the managed agent asks for confirmation before replacing
+customized instructions.
diff --git a/packages/plugins/plugin-llm-wiki/agents/wiki-maintainer/AGENTS.md b/packages/plugins/plugin-llm-wiki/agents/wiki-maintainer/AGENTS.md
new file mode 100644
index 00000000..3c8b6e88
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/agents/wiki-maintainer/AGENTS.md
@@ -0,0 +1,65 @@
+# LLM Wiki Maintainer
+
+You are the maintainer of this personal wiki. The wiki is a persistent, interlinked knowledge base built from raw source documents. You read sources, extract knowledge, and integrate it into evolving wiki pages. The user curates sources, directs analysis, and asks questions; you handle the bookkeeping.
+
+## Wiki Root
+
+The wiki root folder is:
+
+`{{localFolders.wiki-root.path}}`
+
+The wiki's default operating schema is:
+
+`{{localFolders.wiki-root.agentsPath}}`
+
+Before ingest, query, lint, index, or maintenance work, read that wiki-root `AGENTS.md` file. It is the source of truth for page layout, citation style, log format, and wiki conventions. If the path above says `(not configured)`, stop and ask for the LLM Wiki root folder to be configured in plugin settings before doing file work.
+
+## Identity
+
+- You maintain the LLM Wiki, not the application codebase.
+- You keep raw source material in `raw/` immutable.
+- You keep Paperclip project operating summaries current in `wiki/projects/<project-slug>/standup.md`.
+- You create and update durable wiki pages under `wiki/`.
+- You keep `wiki/index.md` and `wiki/log.md` accurate after changes.
+- You cite wiki pages and raw sources in answers.
+
+## Operating Loop
+
+1. Resolve the configured wiki root folder and the target space named in the operation issue.
+2. Read the target space's `AGENTS.md`.
+3. Read the target space's `wiki/index.md` and recent `wiki/log.md` entries before choosing files.
+4. Pick the right operation skill (see below) and follow it.
+5. Use the LLM Wiki plugin tools for file reads, file writes, search, and logging. Always pass the operation issue's `wikiId` and `spaceSlug` arguments.
+6. Keep changes focused and append a concise log entry for durable updates.
+
+All operation paths are relative to the target space root. Paperclip-derived operations (`distill`, `backfill`, cursor-window distillation, event capture) always target the default space in Phase 1 — pass `spaceSlug: "default"` and reject any prompt that asks you to write Paperclip-derived pages into a non-default space. Manual ingest (`ingest`, `query`, `lint`, `index`, `file-as-page`) follows whatever space the operation issue names; do not cross into another space unless the operation issue explicitly requests a multi-space sweep.
+
+For Paperclip-derived project work, maintain two layers:
+
+- `wiki/projects/<project-slug>/standup.md` — the executive standup for live project status, recent work, blockers/risks, and next actions. Rewrite it to the current truth instead of appending dated diary sections.
+- `wiki/projects/<project-slug>/index.md` and optional `wiki/projects/<project-slug>/decisions.md` / `history.md` — durable knowledge pages for context, decisions, and meaningful history.
+
+Project pages and standups should read like human executive synthesis. Group work by concept, decision, blocker, and next action; use readable Paperclip issue links as evidence, but do not dump UUIDs, dates, statuses, or one-line issue inventories into the wiki narrative.
+
+## Skills
+
+Each operation has a dedicated LLM Wiki skill installed on this agent. Use the matching skill before improvising — they encode the page conventions, voice, and verification checklist for each operation.
+
+- `wiki-ingest` — a captured `raw/` source needs to become durable wiki pages.
+- `wiki-query` — answer a question from the wiki with citations; offer durable synthesis.
+- `wiki-lint` — read-only audit for contradictions, orphans, weak provenance, missing concept pages.
+- `paperclip-distill` — turn a Paperclip source bundle (cursor-window, distill, or backfill) into wiki-insightful project pages, decisions, and history. Replaces the stiff, datestamp-heavy templated output.
+- `index-refresh` — keep `wiki/index.md` accurate and scannable.
+
+The operation issue's `originKind` (`plugin:llm-wiki:operation:<type>`) tells you which skill to load:
+
+| `operationType`       | Skill                                          |
+| --------------------- | ---------------------------------------------- |
+| `ingest`              | `wiki-ingest`                                  |
+| `query`               | `wiki-query`                                   |
+| `lint`                | `wiki-lint`                                    |
+| `distill`, `backfill` | `paperclip-distill`                            |
+| `index`               | `index-refresh`                                |
+| `file-as-page`        | `wiki-query` (filing synthesis from an answer) |
+
+If a skill conflicts with this file, follow this file for identity. If a skill conflicts with the wiki-root `AGENTS.md`, follow that for page structure and voice.
diff --git a/packages/plugins/plugin-llm-wiki/esbuild.config.mjs b/packages/plugins/plugin-llm-wiki/esbuild.config.mjs
new file mode 100644
index 00000000..b5cfd36e
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import esbuild from "esbuild";
+import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
+
+const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
+const watch = process.argv.includes("--watch");
+
+const workerCtx = await esbuild.context(presets.esbuild.worker);
+const manifestCtx = await esbuild.context(presets.esbuild.manifest);
+const uiCtx = await esbuild.context(presets.esbuild.ui);
+
+if (watch) {
+  await Promise.all([workerCtx.watch(), manifestCtx.watch(), uiCtx.watch()]);
+  console.log("esbuild watch mode enabled for worker, manifest, and ui");
+} else {
+  await Promise.all([workerCtx.rebuild(), manifestCtx.rebuild(), uiCtx.rebuild()]);
+  await Promise.all([workerCtx.dispose(), manifestCtx.dispose(), uiCtx.dispose()]);
+}
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/.gitignore b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/.gitignore
new file mode 100644
index 00000000..ef42c26d
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/.gitignore
@@ -0,0 +1,3 @@
+.DS_Store
+.obsidian/workspace*
+.obsidian/cache
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/AGENTS.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/AGENTS.md
new file mode 100644
index 00000000..3c2aa273
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/AGENTS.md
@@ -0,0 +1,137 @@
+# AGENTS.md — LLM Wiki Schema
+
+You are the maintainer of this personal wiki. The wiki is a persistent, interlinked knowledge base built from raw source documents. You read sources, extract knowledge, and integrate it into evolving wiki pages. The user curates sources, directs analysis, and asks questions; you handle the bookkeeping.
+
+The underlying pattern is described in `IDEA.md` (Karpathy's "LLM Wiki" gist). Read it if you need the philosophy; this file is the operational schema.
+
+## Layout
+
+```
+.
+├── AGENTS.md         # this file — your operating instructions
+├── IDEA.md           # the pattern this wiki follows
+├── raw/              # immutable source documents (you read, never write)
+└── wiki/             # generated, owned by you
+    ├── index.md      # catalog of all pages
+    ├── log.md        # append-only timeline of operations
+    ├── sources/      # one summary page per source
+    ├── projects/     # Paperclip project overviews, standups, decisions, and history
+    │   └── <slug>/
+    │       ├── index.md
+    │       ├── standup.md
+    │       ├── decisions.md
+    │       └── history.md
+    ├── entities/     # people, organizations, products, places
+    ├── concepts/     # ideas, frameworks, definitions
+    └── synthesis/    # cross-cutting analysis, comparisons, theses
+```
+
+The subdirectories under `wiki/` are conventional, not enforced. Add new categories (e.g. `wiki/papers/`) as the domain demands — and update this file when you do.
+
+Paperclip project material lives only under `wiki/projects/<project-slug>/`. Do not create a top-level `projects/` directory.
+
+- `wiki/projects/<project-slug>/standup.md` is the executive-level project standup. It answers where the project stands today, what changed recently, current blockers/risks, and the next concrete actions.
+- `wiki/projects/<project-slug>/index.md` is the durable knowledge page. It explains what the project is, why it exists, decisions made, history, and long-lived context.
+- Keep the two linked. A standup should link to the durable project page, and the durable project page should point at the current standup for live status.
+- Update `standup.md` whenever Paperclip project, issue, plan, comment, blocker, approval, or status history materially changes the project's current state. Do not append endless dated sections; rewrite it as today's concise status.
+- Project writing should be editorial and concept-grouped. Do not dump issue queues, UUIDs, raw metadata, or date-heavy ledgers into project pages. Reference Paperclip tasks with human issue links where useful, but make headings and paragraphs explain the concepts, decisions, completed work, next work, and blockers in plain executive language.
+
+## Page conventions
+
+- **Filename:** kebab-case, `.md`. Treat filenames as stable; do not rename without updating backlinks.
+- **Frontmatter:** YAML at the top of every wiki page.
+  ```yaml
+  ---
+  title: Human-readable title
+  type: source | project | entity | concept | synthesis
+  tags: [tag-a, tag-b]
+  sources: [raw/doc.pdf]    # for source pages and synthesis pages
+  created: YYYY-MM-DD
+  updated: YYYY-MM-DD
+  ---
+  ```
+- **Cross-links:** Obsidian-style `[[wiki/entities/some-page]]` (or `[[some-page]]` when unambiguous). When you mention a concept or entity that has — or should have — its own page, link it.
+- **Citations:** cite the source inline whenever a claim comes from one: `(see [[wiki/sources/some-slug]])`.
+- **Voice:** terse, factual, neutral. The wiki is reference material, not narrative.
+
+## Operations
+
+### Ingest
+
+Triggered when the user drops a file in `raw/` and asks to process it (or just says "ingest").
+
+1. Read the source end to end.
+2. Briefly discuss key takeaways with the user before writing — confirm what to emphasize.
+3. Create `wiki/sources/<slug>.md`: a summary page (~300–800 words) covering the source's main claims, structure, and notable quotes or data.
+4. Update or create relevant pages in `entities/`, `concepts/`, `synthesis/`. A typical ingest touches 5–15 pages.
+5. Add any new pages to `wiki/index.md`.
+6. Append a log entry:
+   ```
+   ## [YYYY-MM-DD] ingest | <source title>
+   - source: raw/<filename>
+   - new pages: [[...]], [[...]]
+   - updated pages: [[...]], [[...]]
+   - notes: <one-line synthesis, contradiction flagged, or open question>
+   ```
+
+When new information contradicts an existing page, do **not** silently overwrite. Flag the contradiction on the page (a `> ⚠ contradicted by [[...]] (YYYY-MM-DD)` callout) and note it in the log.
+
+### Project updates
+
+Triggered when Paperclip project, issue, plan, comment, blocker, or status history is distilled into the wiki.
+
+1. Create or update `wiki/projects/<project-slug>/standup.md` first. Every Paperclip project represented in the wiki must have one. Keep stable sections for executive readout, what changed, decisions, blockers/risks, next actions, and links.
+2. Create or update `wiki/projects/<project-slug>/index.md` as the durable project overview. Keep stable sections for overview, current direction, workstreams, decisions, open risks/blockers, and references.
+3. Use `wiki/projects/<project-slug>/decisions.md` for accepted/rejected plans, architectural decisions, approval outcomes, and reversals when a project has enough decision history to warrant a separate page.
+4. Use `wiki/projects/<project-slug>/history.md` for compact narrative history of meaningful project movement. Group by phase or concept; do not mirror every issue comment.
+5. Always cite Paperclip source material with readable links to issue identifiers, document keys, issue documents, approvals, and raw/source pages. Do not put UUIDs in prose unless the UUID itself is the subject.
+6. Update `wiki/index.md` under Projects and append a `project` log entry to `wiki/log.md`.
+
+### Query
+
+The user asks a question. You:
+
+1. Read `wiki/index.md` to find candidate pages.
+2. Read those pages; follow links as needed.
+3. Answer with citations back to wiki pages, and ultimately to raw sources.
+4. If the answer is substantial (a comparison, analysis, new synthesis), offer to file it under `wiki/synthesis/` so the work compounds rather than disappearing into chat history.
+
+If the wiki lacks what the question needs, say so plainly and suggest sources to ingest or web searches to run.
+
+### Lint
+
+On request ("lint", "health check"), scan for:
+
+- contradictions across pages
+- claims a newer source has superseded
+- orphan pages (not linked from `index.md` or any other page)
+- concepts mentioned in multiple places but lacking a dedicated page
+- broken `[[wiki-links]]`
+- gaps where a web search or new source would help
+
+Report findings as a checklist and ask the user which to act on.
+
+## index.md format
+
+A catalog organized by category. Each line: `- [[path]] — one-line summary`. Keep it scannable; this is your primary navigation aid before opening pages.
+
+## log.md format
+
+Append new entries to the bottom. Every entry header follows:
+
+```
+## [YYYY-MM-DD] <op> | <subject>
+```
+
+so `grep "^## \[" wiki/log.md | tail -10` always returns recent activity. Operations: `ingest`, `query`, `lint`, `setup`, `refactor`.
+
+## Customization
+
+This schema is intentionally generic. As the wiki's domain becomes clear, evolve it:
+
+- add domain-specific page types and subdirectories
+- adjust frontmatter fields
+- specify preferred output formats for queries (Marp slides, charts, tables)
+- record workflow preferences (one-at-a-time vs batch ingest, level of human supervision)
+
+When you and the user agree on a convention, **write it into this file**. The schema is the wiki's source of truth for how the wiki is built.
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/IDEA.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/IDEA.md
new file mode 100644
index 00000000..35ef0712
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/IDEA.md
@@ -0,0 +1,75 @@
+# LLM Wiki
+
+A pattern for building personal knowledge bases using LLMs.
+
+This is an idea file, it is designed to be copy pasted to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, or etc.). Its goal is to communicate the high level idea, but your agent will build out the specifics in collaboration with you.
+
+## The core idea
+
+Most people's experience with LLMs and documents looks like RAG: you upload a collection of files, the LLM retrieves relevant chunks at query time, and generates an answer. This works, but the LLM is rediscovering knowledge from scratch on every question. There's no accumulation. Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up. NotebookLM, ChatGPT file uploads, and most RAG systems work this way.
+
+The idea here is different. Instead of just retrieving from raw documents at query time, the LLM **incrementally builds and maintains a persistent wiki** — a structured, interlinked collection of markdown files that sits between you and the raw sources. When you add a new source, the LLM doesn't just index it for later retrieval. It reads it, extracts the key information, and integrates it into the existing wiki — updating entity pages, revising topic summaries, noting where new data contradicts old claims, strengthening or challenging the evolving synthesis. The knowledge is compiled once and then *kept current*, not re-derived on every query.
+
+This is the key difference: **the wiki is a persistent, compounding artifact.** The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you've read. The wiki keeps getting richer with every source you add and every question you ask.
+
+You never (or rarely) write the wiki yourself — the LLM writes and maintains all of it. You're in charge of sourcing, exploration, and asking the right questions. The LLM does all the grunt work — the summarizing, cross-referencing, filing, and bookkeeping that makes a knowledge base actually useful over time. In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.
+
+This can apply to a lot of different contexts. A few examples:
+
+- **Personal**: tracking your own goals, health, psychology, self-improvement — filing journal entries, articles, podcast notes, and building up a structured picture of yourself over time.
+- **Research**: going deep on a topic over weeks or months — reading papers, articles, reports, and incrementally building a comprehensive wiki with an evolving thesis.
+- **Reading a book**: filing each chapter as you go, building out pages for characters, themes, plot threads, and how they connect. By the end you have a rich companion wiki. Think of fan wikis like [Tolkien Gateway](https://tolkiengateway.net/wiki/Main_Page) — thousands of interlinked pages covering characters, places, events, languages, built by a community of volunteers over years. You could build something like that personally as you read, with the LLM doing all the cross-referencing and maintenance.
+- **Business/team**: an internal wiki maintained by LLMs, fed by Slack threads, meeting transcripts, project documents, customer calls. Possibly with humans in the loop reviewing updates. The wiki stays current because the LLM does the maintenance that no one on the team wants to do.
+- **Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives** — anything where you're accumulating knowledge over time and want it organized rather than scattered.
+
+## Architecture
+
+There are three layers:
+
+**Raw sources** — your curated collection of source documents. Articles, papers, images, data files. These are immutable — the LLM reads from them but never modifies them. This is your source of truth.
+
+**The wiki** — a directory of LLM-generated markdown files. Summaries, entity pages, concept pages, comparisons, an overview, a synthesis. The LLM owns this layer entirely. It creates pages, updates them when new sources arrive, maintains cross-references, and keeps everything consistent. You read it; the LLM writes it.
+
+**The schema** — a document (e.g. AGENTS.md for Paperclip agents) that tells the LLM how the wiki is structured, what the conventions are, and what workflows to follow when ingesting sources, answering questions, or maintaining the wiki. This is the key configuration file — it's what makes the LLM a disciplined wiki maintainer rather than a generic chatbot. You and the LLM co-evolve this over time as you figure out what works for your domain.
+
+## Operations
+
+**Ingest.** You drop a new source into the raw collection and tell the LLM to process it. An example flow: the LLM reads the source, discusses key takeaways with you, writes a summary page in the wiki, updates the index, updates relevant entity and concept pages across the wiki, and appends an entry to the log. A single source might touch 10-15 wiki pages. Personally I prefer to ingest sources one at a time and stay involved — I read the summaries, check the updates, and guide the LLM on what to emphasize. But you could also batch-ingest many sources at once with less supervision. It's up to you to develop the workflow that fits your style and document it in the schema for future sessions.
+
+**Query.** You ask questions against the wiki. The LLM searches for relevant pages, reads them, and synthesizes an answer with citations. Answers can take different forms depending on the question — a markdown page, a comparison table, a slide deck (Marp), a chart (matplotlib), a canvas. The important insight: **good answers can be filed back into the wiki as new pages.** A comparison you asked for, an analysis, a connection you discovered — these are valuable and shouldn't disappear into chat history. This way your explorations compound in the knowledge base just like ingested sources do.
+
+**Lint.** Periodically, ask the LLM to health-check the wiki. Look for: contradictions between pages, stale claims that newer sources have superseded, orphan pages with no inbound links, important concepts mentioned but lacking their own page, missing cross-references, data gaps that could be filled with a web search. The LLM is good at suggesting new questions to investigate and new sources to look for. This keeps the wiki healthy as it grows.
+
+## Indexing and logging
+
+Two special files help the LLM (and you) navigate the wiki as it grows. They serve different purposes:
+
+**index.md** is content-oriented. It's a catalog of everything in the wiki — each page listed with a link, a one-line summary, and optionally metadata like date or source count. Organized by category (entities, concepts, sources, etc.). The LLM updates it on every ingest. When answering a query, the LLM reads the index first to find relevant pages, then drills into them. This works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure.
+
+**log.md** is chronological. It's an append-only record of what happened and when — ingests, queries, lint passes. A useful tip: if each entry starts with a consistent prefix (e.g. `## [2026-04-02] ingest | Article Title`), the log becomes parseable with simple unix tools — `grep "^## \[" log.md | tail -5` gives you the last 5 entries. The log gives you a timeline of the wiki's evolution and helps the LLM understand what's been done recently.
+
+## Optional: CLI tools
+
+At some point you may want to build small tools that help the LLM operate on the wiki more efficiently. A search engine over the wiki pages is the most obvious one — at small scale the index file is enough, but as the wiki grows you want proper search. [qmd](https://github.com/tobi/qmd) is a good option: it's a local search engine for markdown files with hybrid BM25/vector search and LLM re-ranking, all on-device. It has both a CLI (so the LLM can shell out to it) and an MCP server (so the LLM can use it as a native tool). You could also build something simpler yourself — the LLM can help you vibe-code a naive search script as the need arises.
+
+## Tips and tricks
+
+- **Obsidian Web Clipper** is a browser extension that converts web articles to markdown. Very useful for quickly getting sources into your raw collection.
+- **Download images locally.** In Obsidian Settings → Files and links, set "Attachment folder path" to a fixed directory (e.g. `raw/assets/`). Then in Settings → Hotkeys, search for "Download" to find "Download attachments for current file" and bind it to a hotkey (e.g. Ctrl+Shift+D). After clipping an article, hit the hotkey and all images get downloaded to local disk. This is optional but useful — it lets the LLM view and reference images directly instead of relying on URLs that may break. Note that LLMs can't natively read markdown with inline images in one pass — the workaround is to have the LLM read the text first, then view some or all of the referenced images separately to gain additional context. It's a bit clunky but works well enough.
+- **Obsidian's graph view** is the best way to see the shape of your wiki — what's connected to what, which pages are hubs, which are orphans.
+- **Marp** is a markdown-based slide deck format. Obsidian has a plugin for it. Useful for generating presentations directly from wiki content.
+- **Dataview** is an Obsidian plugin that runs queries over page frontmatter. If your LLM adds YAML frontmatter to wiki pages (tags, dates, source counts), Dataview can generate dynamic tables and lists.
+- The wiki is just a git repo of markdown files. You get version history, branching, and collaboration for free.
+
+## Why this works
+
+The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero.
+
+The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else.
+
+The idea is related in spirit to Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents. Bush's vision was closer to this than to what the web became: private, actively curated, with the connections between documents as valuable as the documents themselves. The part he couldn't solve was who does the maintenance. The LLM handles that.
+
+
+## Note
+
+This document is intentionally abstract. It describes the idea, not a specific implementation. The exact directory structure, the schema conventions, the page formats, the tooling — all of that will depend on your domain, your preferences, and your LLM of choice. Everything mentioned above is optional and modular — pick what's useful, ignore what isn't. For example: your sources might be text-only, so you don't need image handling at all. Your wiki might be small enough that the index file is all you need, no search engine required. You might not care about slide decks and just want markdown pages. You might want a completely different set of output formats. The right way to use this is to share it with your LLM agent and work together to instantiate a version that fits your needs. The document's only job is to communicate the pattern. Your LLM can figure out the rest.
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/plugin-boundaries.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/plugin-boundaries.md
new file mode 100644
index 00000000..89d8a8d9
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/raw/plugin-boundaries.md
@@ -0,0 +1,3 @@
+# Raw Source
+
+LLM Wiki code must live in the standalone plugin package.
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/areas/knowledge.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/areas/knowledge.md
new file mode 100644
index 00000000..46462345
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/areas/knowledge.md
@@ -0,0 +1,3 @@
+# Knowledge
+
+The wiki stores durable knowledge as local markdown files.
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/plugin-boundaries.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/plugin-boundaries.md
new file mode 100644
index 00000000..595ee78c
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/concepts/plugin-boundaries.md
@@ -0,0 +1,3 @@
+# Plugin Boundaries
+
+LLM Wiki routes, prompts, UI, tools, and migrations belong inside the plugin.
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/entities/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/entities/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/index.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/index.md
new file mode 100644
index 00000000..54f1f8a3
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/index.md
@@ -0,0 +1,23 @@
+# Index
+
+Catalog of durable wiki pages and linked project standups. Updated on every ingest or Paperclip distill.
+
+## Sources
+
+_(none yet)_
+
+## Projects
+
+_(none yet)_
+
+## Entities
+
+_(none yet)_
+
+## Concepts
+
+_(none yet)_
+
+## Synthesis
+
+_(none yet)_
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/log.md b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/log.md
new file mode 100644
index 00000000..6b101ab1
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/log.md
@@ -0,0 +1,10 @@
+# Log
+
+Append-only chronological record of wiki operations.
+
+## [2026-05-03] setup | wiki initialized
+- created `AGENTS.md` (schema)
+- created `raw/` for source documents
+- created `wiki/` skeleton: `index.md`, `log.md`, `sources/`, `projects/`, `entities/`, `concepts/`, `synthesis/`
+- created `wiki/projects/` for Paperclip project overviews and standups
+- pattern reference: `IDEA.md` (Karpathy "LLM Wiki" gist, https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/projects/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/projects/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/projects/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/sources/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/sources/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/synthesis/.gitkeep b/packages/plugins/plugin-llm-wiki/fixtures/basic-root/wiki/synthesis/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/migrations/001_llm_wiki.sql b/packages/plugins/plugin-llm-wiki/migrations/001_llm_wiki.sql
new file mode 100644
index 00000000..01d5067c
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/migrations/001_llm_wiki.sql
@@ -0,0 +1,101 @@
+CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_instances (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  root_folder_key text NOT NULL DEFAULT 'wiki-root',
+  configured_root_path text,
+  schema_version integer NOT NULL DEFAULT 1,
+  settings jsonb NOT NULL DEFAULT '{}'::jsonb,
+  managed_agent_key text,
+  managed_project_key text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (company_id, wiki_id)
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_sources (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  source_type text NOT NULL,
+  title text,
+  url text,
+  raw_path text NOT NULL,
+  content_hash text NOT NULL,
+  status text NOT NULL DEFAULT 'captured',
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_pages (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  path text NOT NULL,
+  title text,
+  page_type text,
+  frontmatter jsonb NOT NULL DEFAULT '{}'::jsonb,
+  source_refs jsonb NOT NULL DEFAULT '[]'::jsonb,
+  backlinks jsonb NOT NULL DEFAULT '[]'::jsonb,
+  content_hash text,
+  current_revision_id uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (company_id, wiki_id, path)
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  page_id uuid REFERENCES plugin_llm_wiki_8f50da974f.wiki_pages(id) ON DELETE CASCADE,
+  operation_id uuid,
+  path text NOT NULL,
+  content_hash text NOT NULL,
+  summary text,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_operations (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  operation_type text NOT NULL,
+  status text NOT NULL,
+  hidden_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
+  project_id uuid REFERENCES public.projects(id) ON DELETE SET NULL,
+  run_ids jsonb NOT NULL DEFAULT '[]'::jsonb,
+  cost_cents integer NOT NULL DEFAULT 0,
+  warnings jsonb NOT NULL DEFAULT '[]'::jsonb,
+  affected_pages jsonb NOT NULL DEFAULT '[]'::jsonb,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  hidden_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
+  agent_session_id text,
+  status text NOT NULL DEFAULT 'active',
+  filed_outputs jsonb NOT NULL DEFAULT '[]'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.wiki_resource_bindings (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  resource_kind text NOT NULL,
+  resource_key text NOT NULL,
+  resolved_id uuid,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (company_id, wiki_id, resource_kind, resource_key)
+);
diff --git a/packages/plugins/plugin-llm-wiki/migrations/002_paperclip_distillation.sql b/packages/plugins/plugin-llm-wiki/migrations/002_paperclip_distillation.sql
new file mode 100644
index 00000000..aa8c269b
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/migrations/002_paperclip_distillation.sql
@@ -0,0 +1,88 @@
+CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  source_scope text NOT NULL,
+  scope_key text NOT NULL,
+  project_id uuid REFERENCES public.projects(id) ON DELETE CASCADE,
+  root_issue_id uuid REFERENCES public.issues(id) ON DELETE CASCADE,
+  source_kind text NOT NULL DEFAULT 'paperclip_issue_history',
+  last_processed_at timestamptz,
+  last_observed_at timestamptz,
+  pending_event_count integer NOT NULL DEFAULT 0,
+  last_successful_run_id uuid,
+  last_source_hash text,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (company_id, wiki_id, source_scope, scope_key, source_kind)
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  work_item_kind text NOT NULL,
+  status text NOT NULL DEFAULT 'pending',
+  priority text NOT NULL DEFAULT 'medium',
+  project_id uuid REFERENCES public.projects(id) ON DELETE CASCADE,
+  root_issue_id uuid REFERENCES public.issues(id) ON DELETE CASCADE,
+  requested_by_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
+  idempotency_key text,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (company_id, wiki_id, idempotency_key)
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  cursor_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors(id) ON DELETE SET NULL,
+  work_item_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items(id) ON DELETE SET NULL,
+  project_id uuid REFERENCES public.projects(id) ON DELETE SET NULL,
+  root_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
+  source_window_start timestamptz,
+  source_window_end timestamptz,
+  source_hash text,
+  status text NOT NULL,
+  operation_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
+  retry_count integer NOT NULL DEFAULT 0,
+  cost_cents integer NOT NULL DEFAULT 0,
+  warnings jsonb NOT NULL DEFAULT '[]'::jsonb,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  distillation_run_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_runs(id) ON DELETE CASCADE,
+  project_id uuid REFERENCES public.projects(id) ON DELETE SET NULL,
+  root_issue_id uuid REFERENCES public.issues(id) ON DELETE SET NULL,
+  source_hash text NOT NULL,
+  max_characters integer NOT NULL,
+  clipped boolean NOT NULL DEFAULT false,
+  source_refs jsonb NOT NULL DEFAULT '[]'::jsonb,
+  bundle_markdown text NOT NULL,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL,
+  project_id uuid REFERENCES public.projects(id) ON DELETE CASCADE,
+  root_issue_id uuid REFERENCES public.issues(id) ON DELETE CASCADE,
+  page_path text NOT NULL,
+  last_applied_source_hash text,
+  last_distillation_run_id uuid REFERENCES plugin_llm_wiki_8f50da974f.paperclip_distillation_runs(id) ON DELETE SET NULL,
+  metadata jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (company_id, wiki_id, page_path)
+);
diff --git a/packages/plugins/plugin-llm-wiki/migrations/003_spaces.sql b/packages/plugins/plugin-llm-wiki/migrations/003_spaces.sql
new file mode 100644
index 00000000..e9c4a0fd
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/migrations/003_spaces.sql
@@ -0,0 +1,236 @@
+CREATE TABLE IF NOT EXISTS plugin_llm_wiki_8f50da974f.wiki_spaces (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL REFERENCES public.companies(id) ON DELETE CASCADE,
+  wiki_id text NOT NULL DEFAULT 'default',
+  slug text NOT NULL,
+  display_name text NOT NULL,
+  space_type text NOT NULL DEFAULT 'local_folder',
+  folder_mode text NOT NULL DEFAULT 'managed_subfolder',
+  root_folder_key text NOT NULL DEFAULT 'wiki-root',
+  path_prefix text,
+  configured_root_path text,
+  access_scope text NOT NULL DEFAULT 'shared',
+  owner_user_id text,
+  owner_agent_id uuid REFERENCES public.agents(id) ON DELETE SET NULL,
+  team_key text,
+  settings jsonb NOT NULL DEFAULT '{}'::jsonb,
+  status text NOT NULL DEFAULT 'active',
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (company_id, wiki_id, slug)
+);
+
+CREATE INDEX IF NOT EXISTS wiki_spaces_company_status_idx
+  ON plugin_llm_wiki_8f50da974f.wiki_spaces (company_id, wiki_id, status);
+
+WITH wiki_pairs AS (
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_instances
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_sources
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_pages
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_page_revisions
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_operations
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.wiki_query_sessions
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_distillation_runs
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_source_snapshots
+  UNION
+  SELECT company_id, wiki_id FROM plugin_llm_wiki_8f50da974f.paperclip_page_bindings
+)
+INSERT INTO plugin_llm_wiki_8f50da974f.wiki_spaces
+  (id, company_id, wiki_id, slug, display_name, space_type, folder_mode, root_folder_key, path_prefix, access_scope, status)
+SELECT (
+    substr(md5(company_id::text || ':' || wiki_id || ':default'), 1, 8) || '-' ||
+    substr(md5(company_id::text || ':' || wiki_id || ':default'), 9, 4) || '-' ||
+    '4' || substr(md5(company_id::text || ':' || wiki_id || ':default'), 14, 3) || '-' ||
+    '8' || substr(md5(company_id::text || ':' || wiki_id || ':default'), 18, 3) || '-' ||
+    substr(md5(company_id::text || ':' || wiki_id || ':default'), 21, 12)
+  )::uuid,
+  company_id,
+  wiki_id,
+  'default',
+  'default',
+  'local_folder',
+  'managed_subfolder',
+  'wiki-root',
+  NULL,
+  'shared',
+  'active'
+FROM wiki_pairs
+ON CONFLICT (company_id, wiki_id, slug) DO NOTHING;
+
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_sources ADD COLUMN IF NOT EXISTS space_id uuid;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages ADD COLUMN IF NOT EXISTS space_id uuid;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions ADD COLUMN IF NOT EXISTS space_id uuid;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_operations ADD COLUMN IF NOT EXISTS space_id uuid;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions ADD COLUMN IF NOT EXISTS space_id uuid;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors ADD COLUMN IF NOT EXISTS space_id uuid;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items ADD COLUMN IF NOT EXISTS space_id uuid;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs ADD COLUMN IF NOT EXISTS space_id uuid;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots ADD COLUMN IF NOT EXISTS space_id uuid;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings ADD COLUMN IF NOT EXISTS space_id uuid;
+
+UPDATE plugin_llm_wiki_8f50da974f.wiki_sources t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+UPDATE plugin_llm_wiki_8f50da974f.wiki_pages t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+UPDATE plugin_llm_wiki_8f50da974f.wiki_page_revisions t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+UPDATE plugin_llm_wiki_8f50da974f.wiki_operations t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+UPDATE plugin_llm_wiki_8f50da974f.wiki_query_sessions t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+UPDATE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+UPDATE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+UPDATE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+UPDATE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+UPDATE plugin_llm_wiki_8f50da974f.paperclip_page_bindings t
+SET space_id = s.id
+FROM plugin_llm_wiki_8f50da974f.wiki_spaces s
+WHERE t.company_id = s.company_id AND t.wiki_id = s.wiki_id AND s.slug = 'default' AND t.space_id IS NULL;
+
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_sources ALTER COLUMN space_id SET NOT NULL;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages ALTER COLUMN space_id SET NOT NULL;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions ALTER COLUMN space_id SET NOT NULL;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_operations ALTER COLUMN space_id SET NOT NULL;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions ALTER COLUMN space_id SET NOT NULL;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors ALTER COLUMN space_id SET NOT NULL;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items ALTER COLUMN space_id SET NOT NULL;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs ALTER COLUMN space_id SET NOT NULL;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots ALTER COLUMN space_id SET NOT NULL;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings ALTER COLUMN space_id SET NOT NULL;
+
+DO $$
+DECLARE
+  target record;
+  constraint_name text;
+BEGIN
+  FOR target IN
+    SELECT * FROM (VALUES
+      ('wiki_pages', ARRAY['company_id', 'wiki_id', 'path']::text[]),
+      ('paperclip_distillation_cursors', ARRAY['company_id', 'wiki_id', 'source_scope', 'scope_key', 'source_kind']::text[]),
+      ('paperclip_distillation_work_items', ARRAY['company_id', 'wiki_id', 'idempotency_key']::text[]),
+      ('paperclip_page_bindings', ARRAY['company_id', 'wiki_id', 'page_path']::text[])
+    ) AS targets(table_name, column_names)
+  LOOP
+    FOR constraint_name IN
+      SELECT c.conname
+      FROM pg_constraint c
+      JOIN pg_class t ON t.oid = c.conrelid
+      JOIN pg_namespace n ON n.oid = t.relnamespace
+      WHERE n.nspname = 'plugin_llm_wiki_8f50da974f'
+        AND t.relname = target.table_name
+        AND c.contype = 'u'
+        AND (
+          SELECT array_agg(a.attname ORDER BY constraint_columns.ordinality)::text[]
+          FROM unnest(c.conkey) WITH ORDINALITY AS constraint_columns(attnum, ordinality)
+          JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = constraint_columns.attnum
+        ) = target.column_names
+    LOOP
+      EXECUTE format('ALTER TABLE %I.%I DROP CONSTRAINT %I', 'plugin_llm_wiki_8f50da974f', target.table_name, constraint_name);
+    END LOOP;
+  END LOOP;
+END $$;
+
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
+  DROP CONSTRAINT IF EXISTS wiki_pages_company_wiki_space_path_key;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
+  ADD CONSTRAINT wiki_pages_company_wiki_space_path_key UNIQUE (company_id, wiki_id, space_id, path);
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
+  DROP CONSTRAINT IF EXISTS distillation_cursors_company_wiki_space_scope_key;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
+  ADD CONSTRAINT distillation_cursors_company_wiki_space_scope_key UNIQUE (company_id, wiki_id, space_id, source_scope, scope_key, source_kind);
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
+  DROP CONSTRAINT IF EXISTS distillation_work_items_company_wiki_space_idempotency_key;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
+  ADD CONSTRAINT distillation_work_items_company_wiki_space_idempotency_key UNIQUE (company_id, wiki_id, space_id, idempotency_key);
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings
+  DROP CONSTRAINT IF EXISTS page_bindings_company_wiki_space_page_path_key;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings
+  ADD CONSTRAINT page_bindings_company_wiki_space_page_path_key UNIQUE (company_id, wiki_id, space_id, page_path);
+
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_sources
+  DROP CONSTRAINT IF EXISTS wiki_sources_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_sources
+  ADD CONSTRAINT wiki_sources_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
+  DROP CONSTRAINT IF EXISTS wiki_pages_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
+  ADD CONSTRAINT wiki_pages_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions
+  DROP CONSTRAINT IF EXISTS wiki_page_revisions_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_page_revisions
+  ADD CONSTRAINT wiki_page_revisions_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_operations
+  DROP CONSTRAINT IF EXISTS wiki_operations_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_operations
+  ADD CONSTRAINT wiki_operations_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions
+  DROP CONSTRAINT IF EXISTS wiki_query_sessions_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_query_sessions
+  ADD CONSTRAINT wiki_query_sessions_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
+  DROP CONSTRAINT IF EXISTS paperclip_distillation_cursors_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
+  ADD CONSTRAINT paperclip_distillation_cursors_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
+  DROP CONSTRAINT IF EXISTS paperclip_distillation_work_items_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
+  ADD CONSTRAINT paperclip_distillation_work_items_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs
+  DROP CONSTRAINT IF EXISTS paperclip_distillation_runs_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs
+  ADD CONSTRAINT paperclip_distillation_runs_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots
+  DROP CONSTRAINT IF EXISTS paperclip_source_snapshots_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots
+  ADD CONSTRAINT paperclip_source_snapshots_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings
+  DROP CONSTRAINT IF EXISTS paperclip_page_bindings_space_id_fk;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings
+  ADD CONSTRAINT paperclip_page_bindings_space_id_fk FOREIGN KEY (space_id) REFERENCES plugin_llm_wiki_8f50da974f.wiki_spaces(id) ON DELETE CASCADE;
+
+CREATE INDEX IF NOT EXISTS wiki_sources_space_idx ON plugin_llm_wiki_8f50da974f.wiki_sources (company_id, wiki_id, space_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS wiki_operations_space_idx ON plugin_llm_wiki_8f50da974f.wiki_operations (company_id, wiki_id, space_id, created_at DESC);
+CREATE INDEX IF NOT EXISTS wiki_query_sessions_space_idx ON plugin_llm_wiki_8f50da974f.wiki_query_sessions (company_id, wiki_id, space_id, updated_at DESC);
+CREATE INDEX IF NOT EXISTS distillation_runs_space_idx ON plugin_llm_wiki_8f50da974f.paperclip_distillation_runs (company_id, wiki_id, space_id, created_at DESC);
diff --git a/packages/plugins/plugin-llm-wiki/package.json b/packages/plugins/plugin-llm-wiki/package.json
new file mode 100644
index 00000000..4461c845
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/package.json
@@ -0,0 +1,47 @@
+{
+  "name": "@paperclipai/plugin-llm-wiki",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "description": "Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows.",
+  "scripts": {
+    "prebuild": "pnpm --filter @paperclipai/plugin-sdk ensure-build-deps",
+    "build": "node ./esbuild.config.mjs",
+    "build:rollup": "rollup -c",
+    "dev": "node ./esbuild.config.mjs --watch",
+    "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
+    "test": "vitest run --config ./vitest.config.ts",
+    "typecheck": "pnpm --filter @paperclipai/plugin-sdk ensure-build-deps && tsc --noEmit"
+  },
+  "paperclipPlugin": {
+    "manifest": "./dist/manifest.js",
+    "worker": "./dist/worker.js",
+    "ui": "./dist/ui/"
+  },
+  "keywords": [
+    "paperclip",
+    "plugin",
+    "automation",
+    "wiki",
+    "knowledge"
+  ],
+  "author": "Paperclip",
+  "license": "MIT",
+  "devDependencies": {
+    "@paperclipai/plugin-sdk": "workspace:*",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "esbuild": "^0.27.3",
+    "react-dom": "^19.0.0",
+    "rollup": "^4.38.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}
diff --git a/packages/plugins/plugin-llm-wiki/rollup.config.mjs b/packages/plugins/plugin-llm-wiki/rollup.config.mjs
new file mode 100644
index 00000000..ccee40a7
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/rollup.config.mjs
@@ -0,0 +1,28 @@
+import { nodeResolve } from "@rollup/plugin-node-resolve";
+import typescript from "@rollup/plugin-typescript";
+import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
+
+const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
+
+function withPlugins(config) {
+  if (!config) return null;
+  return {
+    ...config,
+    plugins: [
+      nodeResolve({
+        extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs"],
+      }),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        declaration: false,
+        declarationMap: false,
+      }),
+    ],
+  };
+}
+
+export default [
+  withPlugins(presets.rollup.manifest),
+  withPlugins(presets.rollup.worker),
+  withPlugins(presets.rollup.ui),
+].filter(Boolean);
diff --git a/packages/plugins/plugin-llm-wiki/skills/README.md b/packages/plugins/plugin-llm-wiki/skills/README.md
new file mode 100644
index 00000000..cacfe3ca
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/skills/README.md
@@ -0,0 +1,34 @@
+# LLM Wiki Maintainer Skills
+
+This folder is the plugin-level source for LLM Wiki managed company skills. Paperclip installs these skills into the company skill library and syncs them onto the Wiki Maintainer agent. The Wiki Maintainer's identity and operating loop live in `agents/wiki-maintainer/AGENTS.md`; the wiki-root `AGENTS.md` remains the wiki schema for page layout, citation style, and log format.
+
+Each skill is an isolated SKILL.md describing one job — when to invoke it, the inputs that must be true before starting, the steps, and the durable output the operation must leave behind.
+
+## Skill registry
+
+| Skill | When to invoke |
+|---|---|
+| [`wiki-maintainer`](./wiki-maintainer/SKILL.md) | General LLM Wiki maintenance and tool-use guidance shared by the operation skills. |
+| [`wiki-ingest`](./wiki-ingest/SKILL.md) | A new file landed in `raw/` and the operation issue says "ingest" — turn the source into durable wiki pages. |
+| [`wiki-query`](./wiki-query/SKILL.md) | The user asked the wiki a question; answer with citations and offer to file durable synthesis back into `wiki/`. |
+| [`wiki-lint`](./wiki-lint/SKILL.md) | A lint or health-check operation — audit for contradictions, orphan pages, weak provenance, broken links, missing concept pages. |
+| [`paperclip-distill`](./paperclip-distill/SKILL.md) | Cursor-window, distill, or backfill operation on Paperclip activity — write a wiki-insightful project page, decisions log, and history note. |
+| [`index-refresh`](./index-refresh/SKILL.md) | Refresh `wiki/index.md` so each entry has a tight, scannable summary; flag drift between the index and recent log activity. |
+
+## Layering
+
+```
+AGENTS.md (wiki root)                              ← schema for the wiki itself: page conventions, frontmatter, voice
+  agents/wiki-maintainer/AGENTS.md                 ← agent identity and operating loop
+  skills/<skill>/SKILL.md                          ← plugin-managed company skills installed onto the maintainer
+```
+
+When a skill conflicts with the wiki-root `AGENTS.md`, the wiki schema wins for page format/voice and the skill wins for operation flow. When a skill conflicts with the agent's `AGENTS.md`, the agent file wins for identity and the skill wins for the operation procedure.
+
+## Skill conventions
+
+- Front matter has `name` (kebab-case) and `description` (one or two sentences with the trigger condition).
+- Each skill names the input it expects (e.g. an operation issue with `originKind` ending in `:ingest`, a captured `raw/` path, a Paperclip source bundle).
+- Each skill ends with a verification checklist — what must be true before the operation issue is closed `done`.
+- Skills cite the wiki-plugin tools they rely on (`wiki_search`, `wiki_read_page`, `wiki_write_page`, `wiki_read_source`, `wiki_list_sources`).
+- Skills do not duplicate the page conventions from the wiki root `AGENTS.md`. They reference it instead.
diff --git a/packages/plugins/plugin-llm-wiki/skills/index-refresh/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/index-refresh/SKILL.md
new file mode 100644
index 00000000..e0380e67
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/skills/index-refresh/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: index-refresh
+description: Use when an operation issue is an index refresh — typically the hourly index-refresh routine. Rebuild `wiki/index.md` so each entry has a tight, scannable one-line summary and the catalog tracks the actual contents of `wiki/`. Resolve drift between the index and recent log activity, but do not edit page content.
+---
+
+# Index Refresh
+
+Keep `wiki/index.md` accurate and scannable. The index is the maintainer's first stop for navigation — its quality determines how cheap every subsequent operation becomes.
+
+## Inputs
+
+- An operation issue with `operationType: "index"` (or the `index-refresh` routine title).
+- The operation issue's target `wikiId`, `spaceSlug`, and space root. Refresh only that space unless the issue explicitly says this is a multi-space sweep.
+
+## Workflow
+
+1. **Read the target space's `wiki/index.md`** as it currently stands.
+2. **Walk the target space's `wiki/`.** `wiki/projects/<slug>/standup.md` entries are current-state companions for durable `wiki/projects/<slug>/index.md` pages; index them only as links attached to the matching project entry. Walk `wiki/` by category (`sources/`, `projects/`, `entities/`, `concepts/`, `synthesis/`, plus any custom subdirectories the wiki schema added).
+3. **Read the target space's last ~50 entries of `wiki/log.md`** to spot pages that were created or substantially changed but never made it to the index.
+4. **Per category, produce sorted entries** of the form:
+   ```
+   - [[<path>]] — <one-line summary>
+   ```
+   The summary is one factual sentence pulled from the page's first paragraph or its title. **No status, no datestamps in the index** — those belong in the page itself or in the log.
+5. **Drop entries whose page no longer exists.** Note the deletion in the log:
+   ```
+   ## [YYYY-MM-DD] index-refresh | reconciled
+   - removed: [[wiki/old-page]] (page deleted)
+   - added: [[wiki/new-page]] — <summary>
+   ```
+6. **Add entries for pages that exist on disk but were missing from the index.** Skip `wiki/log.md` and `wiki/index.md` themselves. For standalone `wiki/projects/<slug>/standup.md` without a matching durable project page, add it under Projects and flag it for later durable-page distillation.
+7. **Write project entries editorially.** The Projects section should group work by the project's concept and purpose, not by issue ids, dates, statuses, UUIDs, or source metadata. Link task identifiers only as supporting evidence.
+8. **Preserve custom categories.** If the wiki has added e.g. `wiki/papers/` or `wiki/runbooks/`, keep its index section. Do not collapse to the default five categories.
+9. **Append a log entry** with counts:
+   ```
+   ## [YYYY-MM-DD] index-refresh | added=N removed=M
+   - operation issue: <issue identifier>
+   ```
+   If the index was already accurate, the log entry says `added=0 removed=0` — still write it so future audits can see the run happened.
+
+## What this skill does NOT do
+
+- Does not change page content.
+- Does not resolve contradictions, fix broken links, or fill concept gaps. Those go to the next `wiki-lint` run.
+- Does not write summaries that are not already supported by the page itself. If a page lacks a clear first paragraph to summarise, flag it for `wiki-lint`.
+
+## Voice
+
+- Index entries are one factual line per page, present tense.
+- No emojis, no statuses, no dates in `wiki/index.md`. Dates live in the log.
+
+## Verification
+
+Before closing the operation issue:
+
+- [ ] `wiki/index.md` matches the actual contents of `wiki/` — no missing pages, no dangling entries.
+- [ ] Project entries include current `wiki/projects/<slug>/standup.md` links when standups exist.
+- [ ] Each index line has the form `- [[path]] — <summary>`.
+- [ ] Custom category sections are preserved.
+- [ ] `wiki/log.md` has the index-refresh entry with counts (even if the counts are zero).
+- [ ] No page bodies were modified. No file under `raw/` was modified.
+
+## Tools
+
+`wiki_search`, `wiki_read_page`, `wiki_write_page` (for `wiki/index.md` and `wiki/log.md` only). Always include the operation issue's `wikiId` and `spaceSlug`.
diff --git a/packages/plugins/plugin-llm-wiki/skills/paperclip-distill/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/paperclip-distill/SKILL.md
new file mode 100644
index 00000000..fa7b8d60
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/skills/paperclip-distill/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: paperclip-distill
+description: Use when an operation issue is a Paperclip cursor-window, distill, or backfill — `operationType: "distill"` or `"backfill"` and the body references a Paperclip source bundle for a project or root issue. Turn raw Paperclip activity into a wiki-insightful project page, decisions log, and history note. This skill exists specifically to replace the stiff, datestamp-heavy templated output that the deterministic distiller produces.
+---
+
+# Paperclip Distill
+
+Distill Paperclip project, issue, comment, and document activity into durable wiki pages. The success criterion is **wiki-insightful, not procedural**: a reader who has never seen Paperclip should learn what the project is, what was decided, what is at risk, and what the current state is — without scanning a list of `## [YYYY-MM-DD]` headers.
+
+## When this skill is needed
+
+- Cursor-window distillation: the routine fed you a bounded source bundle of recent Paperclip activity for one project or root issue.
+- Backfill: the user asked to seed the wiki with the historical activity of a project or root issue. Source window may be wide.
+- Manual `distill-paperclip-now` request from the UI.
+
+If the operation issue is `operationType: "ingest"` (raw file) or `operationType: "query"`, this is the wrong skill — use `wiki-ingest` or `wiki-query`.
+
+## Destination space
+
+In Phase 1, every Paperclip distill, backfill, and cursor-window operation writes into the
+default wiki space. The operation issue should always carry `spaceSlug: "default"`. If an
+operation issue passes any other slug, stop and surface the mismatch in a comment — do not
+write Paperclip-derived pages into a non-default space.
+
+This rule is destination-only. The Paperclip source scope (which projects, root issues,
+comments, documents are read) is set elsewhere in the operation issue and is independent of
+the destination.
+
+## Inputs
+
+- A Paperclip source bundle (issue list, comment refs, document refs, source hash, cursor window).
+- An existing or planned `wiki/projects/<slug>/standup.md` page path.
+- An existing or planned `wiki/projects/<slug>/index.md` page path.
+- The operation issue's target `wikiId`, `spaceSlug`, space root, and the target space's `AGENTS.md` for page conventions.
+- The current `wiki/projects/<slug>/standup.md`, `wiki/projects/<slug>/index.md`, `decisions.md`, and `history.md` if they already exist (so you write a *patch*, not a rewrite).
+
+## Paperclip Asset Gate
+
+Do not treat Paperclip assets/attachments or issue work products as source text for this skill.
+
+- Allowed Paperclip body text: issue descriptions, comment bodies, document bodies.
+- Assets/attachments are metadata-only until a separate approved extraction policy exists.
+- Work products are metadata-only until a separate approved extraction policy exists.
+- Never fetch `/api/assets/:id/content`.
+- Never dereference a work-product `url`, preview URL, artifact URL, or other linked destination from this skill.
+- If an operator asks for attachment/work-product content distillation, stop and point them at the Phase 5 asset/work-product security gate policy instead of improvising.
+
+## Anti-patterns to avoid
+
+The deterministic templating this skill replaces produced these failure modes — do not reproduce them:
+
+1. **Datestamp-as-section-header.** Lines like `## [2026-04-15] paperclip-distill | proposed` belong in `wiki/log.md`, not in the project page. The project page is durable knowledge; the log is the audit trail.
+2. **Procedural status lists.** `Issue mix: 3 todo, 5 in_progress, 2 done` tells the reader nothing they could not read off Paperclip directly. State *what is happening and why it matters*, then cite the issues that constitute the evidence.
+3. **One-line-per-issue dumps.** A page that is mostly `- PAP-1234: title (in_progress, updated 2026-...)` is an issue list, not a wiki page. Group issues by what they are *about* (a decision, a risk, a workstream) and cite multiple issues per bullet when they share a story.
+4. **Mechanical "Current as of" timestamps everywhere.** One `current_as_of` in frontmatter is enough.
+5. **No interpretation.** "Active issues: PAP-A, PAP-B, PAP-C" is bookkeeping. "The team is concentrating on the schema migration ([PAP-A], [PAP-B]) and has parked the index work pending capacity ([PAP-C])." is wiki-insightful.
+6. **Opaque identifiers in prose.** UUIDs, cursor ids, source hashes, run ids, and raw metadata belong in logs or frontmatter when needed, not in executive-facing project narrative.
+
+## Workflow
+
+1. **Read the bundle in full.** Don't sample. Read every issue title, every comment, every document key the bundle includes. Note: which issues are decisions, which are risks/blockers, which are recently completed, which are inflight.
+2. **Read the existing project page** (if any) so you write a patch, not a rewrite. The "Decisions" section in particular accumulates over time — never wipe accepted decisions; supersede them with `> ⚠ reversed by ...` callouts when something later overrides them.
+3. **Read the target space's `AGENTS.md`** for page conventions: filename style, YAML frontmatter shape, link style, voice. Always pass the operation issue's `wikiId` and `spaceSlug` to LLM Wiki tools.
+4. **Write `wiki/projects/<slug>/standup.md` first.** Every Paperclip project represented in the wiki must have this file. It is the executive standup: where the project stands today, what changed recently, what is blocked or risky, and what happens next. Use stable sections, in this order:
+   - Frontmatter (`type: project-standup`, `project: <slug>`, `current_as_of: YYYY-MM-DD`, `sources`).
+   - **Executive Readout** — one short paragraph that explains the current project posture in plain language.
+   - **What Changed** — the meaningful work completed or advanced since the last window. Group by concept; cite issues/comments/documents only as evidence.
+   - **Decisions** — accepted/rejected/reversed decisions that changed the project direction. Omit when none exist.
+   - **Blockers / Risks** — current blockers and risks with named owner or next action when the source provides one.
+   - **Next Actions** — concrete next actions and owners inferred from Paperclip issues, not vague aspirations.
+   - **Links** — durable wiki project page and relevant Paperclip project/issues/documents.
+   Rewrite the standup to today's state. Do not append endless dated sections; the audit trail belongs in `wiki/log.md` and Paperclip comments.
+5. **Write `wiki/projects/<slug>/index.md`** with these stable sections, in this order:
+   - Frontmatter (`type: project`, `current_as_of: YYYY-MM-DD`, `tags`, `sources`).
+   - **Overview** — 2–4 sentences saying what the project is and why it exists. Use the project description if it exists; otherwise synthesise it from the root issue.
+   - **Current Direction** — narrative paragraph naming the active workstreams, the immediate next concrete deliverable, and the stance on risks. Cite 2–4 issues, do not list 20.
+   - **Workstreams** — a short, grouped list. Each line is a workstream or idea, not an issue.
+   - **Decisions** — accepted and reversed decisions with one paragraph each. Each decision cites the issue / approval / comment that ratified it. Format: `### Decision — short title` then a paragraph; never a bare bullet list.
+   - **Open Risks / Blockers** — what could derail the project, with the issue ref that surfaces it. Skip this section when the bundle has no risk signal — do not pad with `_(none)_`.
+   - **References** — readable links to the current standup and supporting Paperclip tasks/documents. Keep hashes and cursor ids out of the narrative.
+6. **Optionally write `wiki/projects/<slug>/decisions.md`** when the project has accumulated more decisions than the project page can carry without becoming a wall of text. Each decision is a `## ` section with: short title, accepted/reversed/superseded status, one-paragraph rationale, citing the source. *Do not* duplicate decisions already on the project page — link instead.
+7. **Optionally write `wiki/projects/<slug>/history.md`** for a compact narrative timeline of meaningful project changes. **Not** an issue dump — group by phase ("Discovery", "Architecture", "Build", "Stabilisation"), not by date. Each phase is a paragraph that cites the 2–4 issues that defined it.
+8. **Refresh `wiki/index.md`** under the `## Projects` section — one line per durable project page with a one-sentence summary of the project's purpose, plus a link to the current `wiki/projects/<slug>/standup.md` when present.
+9. **Append `wiki/log.md`** entry — this is where the datestamp belongs:
+   ```
+   ## [YYYY-MM-DD] paperclip-distill | <project name>
+   - standup: wiki/projects/<slug>/standup.md
+   - page: wiki/projects/<slug>/index.md
+   - source hash: `<hash>`
+   - cursor window: <start> → <end>
+   - notes: <one line on what changed in this distill, e.g. "decisions section grew with PAP-X reversal", "low-signal window, no page changes">
+   ```
+10. **Surface bundle warnings** (clipped sources, low signal, stale hash). Bundle warnings → `human_review_required: true` on the patch. Do not paper over them.
+
+## Voice
+
+- Past-tense for completed work, present-tense for current state, future-tense only with citation ("the team plans to … per [[…]]").
+- Cite Paperclip source refs inline using their issue identifier (e.g. `PAP-3179`), not opaque UUIDs.
+- Use issue links as evidence, not as the shape of the page. Headings and paragraphs should be organized by concepts, workstreams, decisions, and blockers.
+- Wiki voice: terse, factual, neutral. No "the team is excited to" or "this initiative aims to".
+- Headings are about *content*, not metadata. `## Schema migration` not `## Active Issues`.
+
+## When the bundle has no signal
+
+If the bundle has no durable signal — no decisions, no risk, no completed work, only routine status churn — do **not** write a project page. Instead:
+
+- Append a `paperclip-distill | low-signal skip` log entry naming the cursor window.
+- Close the operation issue with a one-line "no durable change in this window" comment.
+- Do not bump the source hash on a binding that has no proposed page.
+
+## Verification
+
+Before closing the operation issue:
+
+- [ ] The project page reads as wiki content, not as a Paperclip status report. A reader new to the company should understand what the project is.
+- [ ] `wiki/projects/<slug>/standup.md` exists for the represented project and reads as an executive current-state update, not a raw issue dump.
+- [ ] Decisions section names decisions, not issues — every decision has a one-paragraph rationale and a citation.
+- [ ] The page contains exactly one `current_as_of` (in frontmatter), zero `## [YYYY-MM-DD]` headings (those go to the log).
+- [ ] Bundle warnings (clipped, low signal, stale hash) are surfaced; the patch carries `human_review_required: true` when the deployment is authenticated/public.
+- [ ] `wiki/index.md` and `wiki/log.md` are updated.
+- [ ] No file under `raw/` was modified.
+
+## Tools
+
+`wiki_search`, `wiki_read_page`, `wiki_write_page`, `wiki_list_sources`, `wiki_read_source`. Always include the operation issue's `wikiId` and `spaceSlug`. The Paperclip source bundle arrives as part of the operation context — you do not need to assemble it.
diff --git a/packages/plugins/plugin-llm-wiki/skills/wiki-ingest/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/wiki-ingest/SKILL.md
new file mode 100644
index 00000000..3422af80
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/skills/wiki-ingest/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: wiki-ingest
+description: Use when an operation issue asks you to ingest a captured source from `raw/` into the LLM Wiki, or when the user explicitly says "ingest <slug>". The issue body will name a file under `raw/` (e.g. `raw/karpathy-llm-wiki.md`) and ask for durable wiki pages. Do not invoke this skill for Paperclip activity bundles — those use `paperclip-distill` instead.
+---
+
+# Wiki Ingest
+
+Turn one source document into durable, interlinked wiki knowledge.
+
+## Inputs
+
+- An operation issue with `operationType: "ingest"` assigned to you.
+- A `raw/` path mentioned in the issue body (always treat `raw/` as immutable).
+- The operation issue's target `wikiId`, `spaceSlug`, and space root (otherwise stop and surface the missing config to the requester).
+
+## Workflow
+
+1. **Read context first.**
+   - Read the target space's `AGENTS.md` for page conventions (filenames, frontmatter, voice, citation style).
+   - Read the target space's `wiki/index.md` to see what already exists.
+   - Read the target space's last ~20 entries of `wiki/log.md` to avoid re-ingesting a source or re-resolving a contradiction someone else already filed.
+2. **Read the source end to end** with `wiki_read_source`, passing the operation issue's `wikiId` and `spaceSlug`. Do not skim. Note the source's structure, claims, dates, and anything that contradicts existing pages.
+3. **Plan, then confirm — but only if the user is in the loop.** If the operation came from a routine (no live user), proceed. If a user is asking interactively, summarise the 3–5 takeaways you intend to file and ask which to emphasise before writing.
+4. **Write the source page** at `wiki/sources/<slug>.md` — ~300–800 words, frontmatter per the wiki schema, neutral voice, key claims with quoted excerpts where they carry weight. The source page is the canonical citation target for everything else this skill writes.
+5. **Update or create downstream pages** in `entities/`, `concepts/`, and `synthesis/`. A typical ingest touches 5–15 pages; resist creating pages for ideas that only appear once.
+6. **Wire the cross-links.** Every claim that comes from the source cites it as `(see [[wiki/sources/<slug>]])`. Every entity / concept mentioned by name on more than one page links to its dedicated page.
+7. **Flag contradictions; do not silently overwrite.** When new material disagrees with an existing page, append a `> ⚠ contradicted by [[wiki/sources/<slug>]] (YYYY-MM-DD)` callout to the older page and note the conflict in the log.
+8. **Refresh `wiki/index.md`** with one-line summaries for any new pages.
+9. **Append a log entry** in `wiki/log.md`:
+   ```
+   ## [YYYY-MM-DD] ingest | <source title>
+   - source: raw/<filename>
+   - new pages: [[...]], [[...]]
+   - updated pages: [[...]], [[...]]
+   - notes: <one-line synthesis or open question>
+   ```
+
+## Voice
+
+- Terse, factual, neutral. Reference material, not narrative.
+- No "Today I learned" or "This is interesting because" framing.
+- Quote the source verbatim when paraphrasing would lose precision.
+
+## Verification
+
+Before closing the operation issue:
+
+- [ ] Source page exists at `wiki/sources/<slug>.md` with valid frontmatter and a `sources:` field pointing to the raw path.
+- [ ] Every new or updated page links back to the source page or a downstream page that does.
+- [ ] `wiki/index.md` lists every new page under the right category with a one-line summary.
+- [ ] `wiki/log.md` has the ingest entry with the exact filename heading format (so `grep "^## \[" wiki/log.md` keeps working).
+- [ ] Any contradiction between the new source and an older page is annotated, not silently overwritten.
+- [ ] No file under `raw/` was modified.
+
+## Tools
+
+`wiki_list_sources`, `wiki_read_source`, `wiki_search`, `wiki_read_page`, `wiki_write_page`. Always include the operation issue's `wikiId` and `spaceSlug`.
diff --git a/packages/plugins/plugin-llm-wiki/skills/wiki-lint/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/wiki-lint/SKILL.md
new file mode 100644
index 00000000..acaa0255
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/skills/wiki-lint/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: wiki-lint
+description: Use when an operation issue is a lint or health-check (`operationType: "lint"`) — typically the nightly lint routine or a manual "Run lint" from the UI. Audit the wiki for contradictions, orphans, weak provenance, broken links, and missing concept pages, and return a triage list — do not auto-fix.
+---
+
+# Wiki Lint
+
+Audit, do not edit. Return findings the maintainer (human or agent) can triage.
+
+## Inputs
+
+- An operation issue with `operationType: "lint"`.
+- The operation issue's target `wikiId`, `spaceSlug`, and space root. Lint only that space unless the issue explicitly says this is a multi-space sweep.
+
+## Workflow
+
+1. **Walk the target space's `wiki/index.md` and wiki tree** with `wiki_search` and `wiki_read_page`, always passing the operation issue's `wikiId` and `spaceSlug`. Build a mental map of: pages that exist, pages referenced from `index.md`, pages referenced from other pages, and raw sources.
+2. **Check for the seven recurring issues**, in this order:
+   1. **Contradictions** — two pages making incompatible claims about the same entity, decision, or status. Flag both pages, name the conflicting claims, and quote evidence.
+   2. **Stale claims** — a page asserts X, but a newer source under `raw/` has superseded it. Flag the older page; never overwrite.
+   3. **Orphan pages** — a `wiki/` page is not linked from `index.md` and not referenced from any other wiki page. Either it should be linked, removed, or merged.
+   4. **Concept gaps** — a term appears on three or more pages but has no dedicated `wiki/concepts/<slug>.md`. Recommend creating one.
+   5. **Broken `[[wiki-links]]`** — a link target file does not exist.
+   6. **Weak provenance** — a non-trivial claim is uncited or cites only the wiki itself in a circle. The original source ref should be findable.
+   7. **Index / log drift** — pages exist that are not in `index.md`, or `index.md` lists pages that no longer exist. Recent operations in `wiki/log.md` that did not produce a corresponding page change.
+3. **Return a triage list**, grouped by severity:
+   - **critical**: contradictions, broken links to active pages, fabricated citations.
+   - **medium**: stale claims, weak provenance, large concept gaps.
+   - **low**: orphans, log drift, small index gaps.
+   Each item has: file path, evidence (a 1–2 line quote), suggested fix, and the operation that should follow up (`ingest`, `paperclip-distill`, `index-refresh`, manual review).
+4. **Do not write to `wiki/`.** Lint is read-only by design — the maintainer or the routine that follows decides which findings to act on.
+5. **Append a log entry** describing the run:
+   ```
+   ## [YYYY-MM-DD] lint | <N findings, M critical>
+   - operation issue: <issue identifier>
+   - critical: <count>
+   - medium: <count>
+   - low: <count>
+   ```
+
+## Voice
+
+- Lead with the count by severity.
+- Each finding is one bullet. Resist commentary.
+- When in doubt about severity, say so and surface it as medium with a "verify" note.
+
+## Verification
+
+Before closing the operation issue:
+
+- [ ] Findings are grouped by severity with file paths, evidence, and suggested fix per item.
+- [ ] No files under `raw/` were modified. No files under `wiki/` were modified except `wiki/log.md`.
+- [ ] If the run found nothing, the issue is closed with "no findings" and the log entry still exists so future audits can see this run happened.
+
+## Tools
+
+`wiki_search`, `wiki_read_page`, `wiki_list_sources`, `wiki_read_source`, `wiki_write_page` (only `wiki/log.md`). Always include the operation issue's `wikiId` and `spaceSlug`.
diff --git a/packages/plugins/plugin-llm-wiki/skills/wiki-maintainer/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/wiki-maintainer/SKILL.md
new file mode 100644
index 00000000..de701b76
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/skills/wiki-maintainer/SKILL.md
@@ -0,0 +1,12 @@
+---
+name: "LLM Wiki Maintainer"
+description: "Use the LLM Wiki plugin tools to maintain a cited local company wiki."
+---
+
+# LLM Wiki Maintainer
+
+Use this skill when maintaining the company LLM Wiki, answering questions from it, ingesting durable source material, refreshing the index, or linting wiki structure.
+
+Before changing wiki files, resolve the configured wiki root, read its AGENTS.md, inspect wiki/index.md and recent wiki/log.md entries, then use the LLM Wiki plugin tools for source reads, page writes, patch proposals, backlinks, and logging.
+
+Keep raw sources immutable, cite wiki pages and raw paths, update wiki/index.md when page navigation changes, and append a concise wiki/log.md entry for durable updates. For Paperclip project work, keep `wiki/projects/<project-slug>/standup.md` current as the executive status view and use `wiki/projects/<project-slug>/index.md` for durable project knowledge. Write project material as concept-grouped executive synthesis, not issue-id lists or metadata dumps.
diff --git a/packages/plugins/plugin-llm-wiki/skills/wiki-query/SKILL.md b/packages/plugins/plugin-llm-wiki/skills/wiki-query/SKILL.md
new file mode 100644
index 00000000..ccb2855a
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/skills/wiki-query/SKILL.md
@@ -0,0 +1,44 @@
+---
+name: wiki-query
+description: Use when an operation issue asks you to answer a question from the LLM Wiki — `operationType: "query"` and a question in the issue body. Answer with citations to wiki pages and raw sources, and offer to file durable synthesis back into `wiki/synthesis/` so the work compounds instead of disappearing into a chat thread.
+---
+
+# Wiki Query
+
+Answer a question from what the wiki actually contains, with citations.
+
+## Inputs
+
+- An operation issue with `operationType: "query"` and the question in the body.
+- The operation issue's target `wikiId`, `spaceSlug`, and space root.
+
+## Workflow
+
+1. **Open the target space's `wiki/index.md` first** — it is the navigation aid. Identify candidate pages.
+2. **Read the candidate pages** end to end with `wiki_read_page`, always passing the operation issue's `wikiId` and `spaceSlug`. Follow `[[wiki-links]]` to neighbouring pages when the question spans entities or concepts.
+3. **Inspect raw sources** when a wiki page's claim feels thin. The wiki points to `raw/` precisely so you can verify before answering. Use `wiki_read_source`.
+4. **Answer the question** in the operation issue thread. Structure:
+   - Direct answer first, in 1–4 sentences.
+   - Then the supporting facts as bullet points, each with an inline citation: `(see [[wiki/concepts/managed-resources]])` or `(see raw/<filename>)`.
+   - If you needed to read a raw source the wiki did not summarise, name that as a gap.
+5. **Decide whether the answer is durable.** If the question forced you to do real synthesis (a comparison, a tradeoff, a definition of something that isn't already a page), offer to file it under `wiki/synthesis/<slug>.md`. Do not write the synthesis page silently — it is opt-in. If the user accepts, write the page, link it from `wiki/index.md`, and append a `query | filed synthesis` log entry.
+6. **When the wiki cannot answer**, say so plainly. Suggest a source the user should ingest, a Paperclip project that would help if distilled, or a web lookup. Never bluff.
+
+## Voice
+
+- Lead with the answer.
+- Cite as you go, not in a footnote block at the end.
+- Use the wiki's terse, factual voice. The query response is itself a candidate for filing into `wiki/synthesis/`.
+
+## Verification
+
+Before closing the operation issue:
+
+- [ ] Every claim in the answer cites a wiki page or raw source.
+- [ ] If the wiki was insufficient, that is stated directly with a concrete next step (ingest source X, distill project Y, web search Z).
+- [ ] If you wrote a synthesis page, `wiki/index.md` lists it and `wiki/log.md` has a `query | filed synthesis` entry.
+- [ ] No file under `raw/` was modified.
+
+## Tools
+
+`wiki_search`, `wiki_read_page`, `wiki_list_sources`, `wiki_read_source`, `wiki_write_page` (only when filing synthesis). Always include the operation issue's `wikiId` and `spaceSlug`.
diff --git a/packages/plugins/plugin-llm-wiki/src/manifest.ts b/packages/plugins/plugin-llm-wiki/src/manifest.ts
new file mode 100644
index 00000000..de611ae6
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/src/manifest.ts
@@ -0,0 +1,601 @@
+import { readFileSync } from "node:fs";
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+import { DEFAULT_AGENT_INSTRUCTION_FILES, DEFAULT_AGENT_INSTRUCTIONS } from "./templates.js";
+
+export const PLUGIN_ID = "paperclipai.plugin-llm-wiki";
+export const WIKI_ROOT_FOLDER_KEY = "wiki-root";
+export const WIKI_MAINTAINER_AGENT_KEY = "wiki-maintainer";
+export const WIKI_MAINTAINER_SKILL_KEY = "wiki-maintainer";
+export const WIKI_INGEST_SKILL_KEY = "wiki-ingest";
+export const WIKI_QUERY_SKILL_KEY = "wiki-query";
+export const WIKI_LINT_SKILL_KEY = "wiki-lint";
+export const PAPERCLIP_DISTILL_SKILL_KEY = "paperclip-distill";
+export const INDEX_REFRESH_SKILL_KEY = "index-refresh";
+export const WIKI_PROJECT_KEY = "llm-wiki";
+export const CURSOR_WINDOW_ROUTINE_KEY = "cursor-window-processing";
+export const NIGHTLY_LINT_ROUTINE_KEY = "nightly-wiki-lint";
+export const INDEX_REFRESH_ROUTINE_KEY = "index-refresh";
+export const DEFAULT_MAX_SOURCE_BYTES = 250000;
+export const DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS = 12000;
+export const DEFAULT_MAX_PAPERCLIP_CURSOR_WINDOW_CHARS = 60000;
+export const DEFAULT_MAX_PAPERCLIP_ROUTINE_RUN_CHARS = 120000;
+export const DEFAULT_PAPERCLIP_COST_CENTS_PER_1K_CHARS = 1;
+export const WIKI_MAINTENANCE_ROUTINE_KEYS = [
+  CURSOR_WINDOW_ROUTINE_KEY,
+  NIGHTLY_LINT_ROUTINE_KEY,
+  INDEX_REFRESH_ROUTINE_KEY,
+] as const;
+export const WIKI_MANAGED_SKILL_KEYS = [
+  WIKI_MAINTAINER_SKILL_KEY,
+  WIKI_INGEST_SKILL_KEY,
+  WIKI_QUERY_SKILL_KEY,
+  WIKI_LINT_SKILL_KEY,
+  PAPERCLIP_DISTILL_SKILL_KEY,
+  INDEX_REFRESH_SKILL_KEY,
+] as const;
+
+function canonicalSkillKey(skillKey: string) {
+  return `plugin/paperclipai-plugin-llm-wiki/${skillKey}`;
+}
+
+function skillMarkdown(skillKey: (typeof WIKI_MANAGED_SKILL_KEYS)[number]) {
+  return readFileSync(new URL(`../skills/${skillKey}/SKILL.md`, import.meta.url), "utf8");
+}
+
+export const WIKI_MAINTAINER_SKILL_CANONICAL_KEY = canonicalSkillKey(WIKI_MAINTAINER_SKILL_KEY);
+export const WIKI_MANAGED_SKILL_CANONICAL_KEYS = WIKI_MANAGED_SKILL_KEYS.map(canonicalSkillKey);
+
+const CURSOR_WINDOW_ROUTINE_DESCRIPTION = `Process bounded Paperclip issue-history windows into the LLM Wiki.
+
+Run procedure:
+Target space: default (slug: default). Paperclip-derived indexing currently writes only into the default space, so this routine never sweeps other spaces. Per-space Paperclip ingestion profiles are a later phase; until they ship, treat any prompt to operate on a non-default space here as a bug and stop.
+1. Resolve the configured wiki root, then read the default space AGENTS.md, wiki/index.md, and the recent entries in wiki/log.md.
+2. Review recent Paperclip issue, comment, and document activity for non-plugin-operation work. Skip LLM Wiki operation issues so routine output does not feed back into itself.
+3. Synthesize Paperclip project state into wiki/projects/<slug>/standup.md for the executive current-state view, then durable project or root-issue knowledge into focused pages under wiki/projects/<slug>/index.md, wiki/concepts/, or wiki/synthesis/. Keep transient run logs out of durable pages unless they change the project's state or decisions.
+4. Write project material as concept-grouped executive synthesis. Link readable issue identifiers when useful, but do not turn project pages into issue-ID lists, UUID dumps, date ledgers, or metadata reports. Always pass wikiId \`default\` and spaceSlug \`default\` to LLM Wiki tools.
+5. Refresh wiki/index.md and append a short wiki/log.md entry listing the source window, affected pages, skipped windows, warnings, and any follow-up issue needed.
+6. If there is no new durable signal, record that in wiki/log.md and close the routine issue with a concise note.`;
+
+const NIGHTLY_LINT_ROUTINE_DESCRIPTION = `Lint the LLM Wiki for structure, provenance, and stale synthesis.
+
+Run procedure:
+Target space: default (slug: default). Paperclip-derived indexing currently writes only into the default space, so this routine never sweeps other spaces. Per-space Paperclip ingestion profiles are a later phase; until they ship, treat any prompt to operate on a non-default space here as a bug and stop.
+1. Resolve the configured wiki root, then read the default space AGENTS.md, wiki/index.md, wiki/log.md, and the current page list.
+2. Check for orphan pages, missing backlinks, stale source provenance, weak citations, duplicate concepts, contradictory claims, and index/log drift.
+3. Inspect the relevant wiki pages and raw sources before changing content. Do not invent missing provenance.
+4. Apply low-risk fixes directly: refresh backlinks, repair index entries, add missing source links, and append a wiki/log.md lint entry. Always pass wikiId \`default\` and spaceSlug \`default\` to LLM Wiki tools.
+5. For ambiguous contradictions or major rewrites, leave the pages unchanged and create or comment a follow-up Paperclip issue with the exact files and evidence.
+6. Close the routine issue with counts by severity, files changed, and unresolved findings.`;
+
+const INDEX_REFRESH_ROUTINE_DESCRIPTION = `Refresh the LLM Wiki navigation and change log.
+
+Run procedure:
+Target space: default (slug: default). Paperclip-derived indexing currently writes only into the default space, so this routine never sweeps other spaces. Per-space Paperclip ingestion profiles are a later phase; until they ship, treat any prompt to operate on a non-default space here as a bug and stop.
+1. Resolve the configured wiki root, then read the default space AGENTS.md, wiki/index.md, wiki/log.md, and the current page list.
+2. Rebuild wiki/index.md so it lists current wiki pages by category with concise summaries and valid wikilinks, and attaches wiki/projects/<slug>/standup.md links to matching project entries.
+3. Verify recently changed wiki pages and project standups are present in the index and that removed or renamed pages no longer appear.
+4. Do not rewrite content pages unless a broken title or link prevents the index from being accurate. Always pass wikiId \`default\` and spaceSlug \`default\` to LLM Wiki tools.
+5. Append a wiki/log.md entry with the index refresh time, page counts by category, and any unresolved indexing problems.
+6. Close the routine issue with the index changes and any follow-up needed.`;
+
+const manifest: PaperclipPluginManifestV1 = {
+  id: PLUGIN_ID,
+  apiVersion: 1,
+  version: "0.1.0",
+  displayName: "LLM Wiki",
+  description: "Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows.",
+  author: "Paperclip",
+  categories: ["automation", "ui"],
+  capabilities: [
+    "events.subscribe",
+    "api.routes.register",
+    "database.namespace.migrate",
+    "database.namespace.read",
+    "database.namespace.write",
+    "companies.read",
+    "projects.read",
+    "projects.managed",
+    "skills.managed",
+    "issues.read",
+    "issue.subtree.read",
+    "issues.create",
+    "issues.update",
+    "issues.wakeup",
+    "issues.orchestration.read",
+    "issue.comments.read",
+    "issue.comments.create",
+    "issue.documents.read",
+    "issue.documents.write",
+    "agents.read",
+    "agents.managed",
+    "agent.sessions.create",
+    "agent.sessions.list",
+    "agent.sessions.send",
+    "agent.sessions.close",
+    "routines.managed",
+    "local.folders",
+    "agent.tools.register",
+    "metrics.write",
+    "activity.log.write",
+    "plugin.state.read",
+    "plugin.state.write",
+    "ui.sidebar.register",
+    "ui.page.register"
+  ],
+  entrypoints: {
+    worker: "./dist/worker.js",
+    ui: "./dist/ui"
+  },
+  database: {
+    namespaceSlug: "llm_wiki",
+    migrationsDir: "migrations",
+    coreReadTables: ["companies", "issues", "projects", "agents"]
+  },
+  localFolders: [
+    {
+      folderKey: WIKI_ROOT_FOLDER_KEY,
+      displayName: "Wiki root",
+      description: "Company-scoped local folder that stores raw sources, wiki pages, Paperclip project standups under wiki/projects/, AGENTS.md, IDEA.md, wiki/index.md, and wiki/log.md.",
+      access: "readWrite",
+      requiredDirectories: [
+        "raw",
+        "wiki",
+        "wiki/sources",
+        "wiki/projects",
+        "wiki/entities",
+        "wiki/concepts",
+        "wiki/synthesis"
+      ],
+      requiredFiles: ["AGENTS.md", "IDEA.md", "wiki/index.md", "wiki/log.md"]
+    }
+  ],
+  agents: [
+    {
+      agentKey: WIKI_MAINTAINER_AGENT_KEY,
+      displayName: "Wiki Maintainer",
+      role: "knowledge-maintainer",
+      title: "LLM Wiki Maintainer",
+      icon: "book-open",
+      capabilities: "Ingests source material, maintains local wiki pages, answers cited questions, and runs wiki lint/maintenance through plugin tools.",
+      adapterType: "claude_local",
+      adapterPreference: ["claude_local", "codex_local", "gemini_local", "opencode_local", "cursor", "pi_local"],
+      adapterConfig: {
+        dangerouslySkipPermissions: false,
+        dangerouslyBypassApprovalsAndSandbox: false,
+        sandbox: true,
+        paperclipSkillSync: {
+          desiredSkills: WIKI_MANAGED_SKILL_CANONICAL_KEYS
+        }
+      },
+      runtimeConfig: {
+        modelProfiles: {
+          cheap: {
+            purpose: "classification, lint planning, index maintenance"
+          }
+        }
+      },
+      permissions: {
+        pluginTools: [PLUGIN_ID]
+      },
+      status: "paused",
+      budgetMonthlyCents: 0,
+      instructions: {
+        entryFile: "AGENTS.md",
+        content: DEFAULT_AGENT_INSTRUCTIONS,
+        files: DEFAULT_AGENT_INSTRUCTION_FILES,
+        assetPath: "agents/wiki-maintainer"
+      }
+    }
+  ],
+  projects: [
+    {
+      projectKey: WIKI_PROJECT_KEY,
+      displayName: "LLM Wiki",
+      description: "Plugin-managed inspection area for LLM Wiki ingest, query, lint, and maintenance operation issues.",
+      status: "in_progress",
+      color: "#2563eb"
+    }
+  ],
+  skills: [
+    {
+      skillKey: WIKI_MAINTAINER_SKILL_KEY,
+      displayName: "LLM Wiki Maintainer",
+      slug: "llm-wiki-maintainer",
+      description: "Use the LLM Wiki plugin tools to maintain a cited local company wiki.",
+      markdown: skillMarkdown(WIKI_MAINTAINER_SKILL_KEY)
+    },
+    {
+      skillKey: WIKI_INGEST_SKILL_KEY,
+      displayName: "Wiki Ingest",
+      slug: WIKI_INGEST_SKILL_KEY,
+      description: "Turn captured raw source material into cited durable LLM Wiki pages.",
+      markdown: skillMarkdown(WIKI_INGEST_SKILL_KEY)
+    },
+    {
+      skillKey: WIKI_QUERY_SKILL_KEY,
+      displayName: "Wiki Query",
+      slug: WIKI_QUERY_SKILL_KEY,
+      description: "Answer questions from the LLM Wiki with citations and optional durable synthesis.",
+      markdown: skillMarkdown(WIKI_QUERY_SKILL_KEY)
+    },
+    {
+      skillKey: WIKI_LINT_SKILL_KEY,
+      displayName: "Wiki Lint",
+      slug: WIKI_LINT_SKILL_KEY,
+      description: "Audit the LLM Wiki for contradictions, orphan pages, weak provenance, broken links, and missing concepts.",
+      markdown: skillMarkdown(WIKI_LINT_SKILL_KEY)
+    },
+    {
+      skillKey: PAPERCLIP_DISTILL_SKILL_KEY,
+      displayName: "Paperclip Distill",
+      slug: PAPERCLIP_DISTILL_SKILL_KEY,
+      description: "Turn Paperclip cursor-window, distill, or backfill source bundles into wiki-insightful project knowledge.",
+      markdown: skillMarkdown(PAPERCLIP_DISTILL_SKILL_KEY)
+    },
+    {
+      skillKey: INDEX_REFRESH_SKILL_KEY,
+      displayName: "Index Refresh",
+      slug: INDEX_REFRESH_SKILL_KEY,
+      description: "Refresh wiki/index.md so it accurately catalogs current wiki pages.",
+      markdown: skillMarkdown(INDEX_REFRESH_SKILL_KEY)
+    }
+  ],
+  routines: [
+    {
+      routineKey: CURSOR_WINDOW_ROUTINE_KEY,
+      title: "Process LLM Wiki updates",
+      description: CURSOR_WINDOW_ROUTINE_DESCRIPTION,
+      status: "paused",
+      priority: "low",
+      assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY },
+      projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY },
+      concurrencyPolicy: "skip_if_active",
+      catchUpPolicy: "skip_missed",
+      triggers: [
+        {
+          kind: "schedule",
+          label: "Every 6 hours",
+          enabled: false,
+          cronExpression: "0 */6 * * *",
+          timezone: "UTC",
+          signingMode: null,
+          replayWindowSec: null
+        }
+      ],
+      issueTemplate: {
+        surfaceVisibility: "plugin_operation",
+        originId: "routine:cursor-window-processing",
+        billingCode: "plugin-llm-wiki:distillation"
+      }
+    },
+    {
+      routineKey: NIGHTLY_LINT_ROUTINE_KEY,
+      title: "Run LLM Wiki lint",
+      description: NIGHTLY_LINT_ROUTINE_DESCRIPTION,
+      status: "paused",
+      priority: "low",
+      assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY },
+      projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY },
+      concurrencyPolicy: "skip_if_active",
+      catchUpPolicy: "skip_missed",
+      triggers: [
+        {
+          kind: "schedule",
+          label: "Nightly",
+          enabled: false,
+          cronExpression: "0 3 * * *",
+          timezone: "UTC",
+          signingMode: null,
+          replayWindowSec: null
+        }
+      ],
+      issueTemplate: {
+        surfaceVisibility: "plugin_operation",
+        originId: "routine:nightly-wiki-lint",
+        billingCode: "plugin-llm-wiki:maintenance"
+      }
+    },
+    {
+      routineKey: INDEX_REFRESH_ROUTINE_KEY,
+      title: "Refresh LLM Wiki index",
+      description: INDEX_REFRESH_ROUTINE_DESCRIPTION,
+      status: "paused",
+      priority: "low",
+      assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY },
+      projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY },
+      concurrencyPolicy: "skip_if_active",
+      catchUpPolicy: "skip_missed",
+      triggers: [
+        {
+          kind: "schedule",
+          label: "Hourly",
+          enabled: false,
+          cronExpression: "0 * * * *",
+          timezone: "UTC",
+          signingMode: null,
+          replayWindowSec: null
+        }
+      ],
+      issueTemplate: {
+        surfaceVisibility: "plugin_operation",
+        originId: "routine:index-refresh",
+        billingCode: "plugin-llm-wiki:maintenance"
+      }
+    }
+  ],
+  tools: [
+    {
+      name: "wiki_search",
+      displayName: "Search Wiki",
+      description: "Search indexed wiki page and source metadata for one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" },
+          query: { type: "string" },
+          limit: { type: "number" }
+        },
+        required: ["companyId", "wikiId", "query"]
+      }
+    },
+    {
+      name: "wiki_read_page",
+      displayName: "Read Wiki Page",
+      description: "Read a markdown wiki page from one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" },
+          path: { type: "string" }
+        },
+        required: ["companyId", "wikiId", "path"]
+      }
+    },
+    {
+      name: "wiki_write_page",
+      displayName: "Write Wiki Page",
+      description: "Atomically write a markdown wiki page in one wiki space after plugin path validation and optional hash conflict checks. Operation agents should pass the issue's spaceSlug; omitting it uses the default space. Protected control files such as AGENTS.md and IDEA.md are excluded from agent-tool writes.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" },
+          path: { type: "string" },
+          contents: { type: "string" },
+          expectedHash: { type: "string" },
+          summary: { type: "string" }
+        },
+        required: ["companyId", "wikiId", "path", "contents"]
+      }
+    },
+    {
+      name: "wiki_propose_patch",
+      displayName: "Propose Wiki Patch",
+      description: "Return a structured proposed page write for one wiki space without changing files. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" },
+          path: { type: "string" },
+          contents: { type: "string" },
+          summary: { type: "string" }
+        },
+        required: ["companyId", "wikiId", "path", "contents"]
+      }
+    },
+    {
+      name: "wiki_list_sources",
+      displayName: "List Wiki Sources",
+      description: "Return captured raw source metadata from one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" },
+          limit: { type: "number" }
+        },
+        required: ["companyId", "wikiId"]
+      }
+    },
+    {
+      name: "wiki_read_source",
+      displayName: "Read Wiki Source",
+      description: "Read a captured raw source from one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" },
+          rawPath: { type: "string" }
+        },
+        required: ["companyId", "wikiId", "rawPath"]
+      }
+    },
+    {
+      name: "wiki_append_log",
+      displayName: "Append Wiki Log",
+      description: "Append a maintenance note to one wiki space's wiki/log.md. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" },
+          entry: { type: "string" }
+        },
+        required: ["companyId", "wikiId", "entry"]
+      }
+    },
+    {
+      name: "wiki_update_index",
+      displayName: "Update Wiki Index",
+      description: "Atomically replace one wiki space's wiki/index.md with optional hash conflict checks. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" },
+          contents: { type: "string" },
+          expectedHash: { type: "string" }
+        },
+        required: ["companyId", "wikiId", "contents"]
+      }
+    },
+    {
+      name: "wiki_list_backlinks",
+      displayName: "List Wiki Backlinks",
+      description: "Return indexed backlinks for a wiki page in one wiki space. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" },
+          path: { type: "string" }
+        },
+        required: ["companyId", "wikiId", "path"]
+      }
+    },
+    {
+      name: "wiki_list_pages",
+      displayName: "List Wiki Pages",
+      description: "Return the known page index from one wiki space's plugin metadata. Operation agents should pass the issue's spaceSlug; omitting it uses the default space.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          companyId: { type: "string" },
+          wikiId: { type: "string" },
+          spaceSlug: { type: "string" }
+        },
+        required: ["companyId", "wikiId"]
+      }
+    }
+  ],
+  apiRoutes: [
+    {
+      routeKey: "overview",
+      method: "GET",
+      path: "/overview",
+      auth: "board-or-agent",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "bootstrap",
+      method: "POST",
+      path: "/bootstrap",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "capture-source",
+      method: "POST",
+      path: "/sources",
+      auth: "board-or-agent",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "spaces",
+      method: "GET",
+      path: "/spaces",
+      auth: "board-or-agent",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "create-space",
+      method: "POST",
+      path: "/spaces",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "update-space",
+      method: "PATCH",
+      path: "/spaces/:spaceSlug",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "bootstrap-space",
+      method: "POST",
+      path: "/spaces/:spaceSlug/bootstrap",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "archive-space",
+      method: "POST",
+      path: "/spaces/:spaceSlug/archive",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "operations",
+      method: "GET",
+      path: "/operations",
+      auth: "board-or-agent",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" }
+    },
+    {
+      routeKey: "start-query",
+      method: "POST",
+      path: "/query-sessions",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    },
+    {
+      routeKey: "file-as-page",
+      method: "POST",
+      path: "/file-as-page",
+      auth: "board",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" }
+    }
+  ],
+  ui: {
+    slots: [
+      {
+        type: "sidebar",
+        id: "wiki-sidebar",
+        displayName: "Wiki",
+        exportName: "SidebarLink",
+        order: 35
+      },
+      {
+        type: "page",
+        id: "wiki-page",
+        displayName: "Wiki",
+        exportName: "WikiPage",
+        routePath: "wiki"
+      },
+      {
+        type: "routeSidebar",
+        id: "wiki-route-sidebar",
+        displayName: "Wiki",
+        exportName: "WikiRouteSidebar",
+        routePath: "wiki"
+      }
+    ]
+  }
+};
+
+export default manifest;
diff --git a/packages/plugins/plugin-llm-wiki/src/templates.ts b/packages/plugins/plugin-llm-wiki/src/templates.ts
new file mode 100644
index 00000000..c07bf6f6
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/src/templates.ts
@@ -0,0 +1,73 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+
+export const REQUIRED_WIKI_DIRECTORIES = [
+  "raw",
+  "wiki",
+  "wiki/sources",
+  "wiki/projects",
+  "wiki/entities",
+  "wiki/concepts",
+  "wiki/synthesis",
+] as const;
+
+export const REQUIRED_WIKI_FILES = ["AGENTS.md", "IDEA.md", "wiki/index.md", "wiki/log.md"] as const;
+export const KARPATHY_LLM_WIKI_GIST_URL = "https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f";
+
+function templateFile(path: string): string {
+  return readFileSync(new URL(`../templates/${path}`, import.meta.url), "utf8");
+}
+
+function agentInstructionFiles(agentKey: string): Record<string, string> {
+  const root = new URL(`../agents/${agentKey}/`, import.meta.url);
+  const files: Record<string, string> = {};
+
+  function walk(relativeDir: string) {
+    const dirUrl = new URL(relativeDir ? `${relativeDir}/` : "./", root);
+    for (const entry of readdirSync(dirUrl)) {
+      if (entry === ".DS_Store") continue;
+      const relativePath = relativeDir ? `${relativeDir}/${entry}` : entry;
+      const entryUrl = new URL(relativePath, root);
+      const stat = statSync(entryUrl);
+      if (stat.isDirectory()) {
+        walk(relativePath);
+      } else if (stat.isFile()) {
+        files[relativePath] = readFileSync(entryUrl, "utf8");
+      }
+    }
+  }
+
+  walk("");
+  return Object.fromEntries(Object.entries(files).sort(([left], [right]) => left.localeCompare(right)));
+}
+
+export const DEFAULT_WIKI_SCHEMA = templateFile("AGENTS.md");
+export const DEFAULT_AGENT_INSTRUCTION_FILES = agentInstructionFiles("wiki-maintainer");
+export const DEFAULT_AGENT_INSTRUCTIONS = DEFAULT_AGENT_INSTRUCTION_FILES["AGENTS.md"] ?? "";
+export const DEFAULT_IDEA = templateFile("IDEA.md");
+export const DEFAULT_INDEX = templateFile("wiki/index.md");
+export const DEFAULT_LOG = templateFile("wiki/log.md");
+export const DEFAULT_GITIGNORE = templateFile(".gitignore");
+
+export const QUERY_PROMPT = `Answer from the LLM Wiki using the installed wiki-query skill.
+
+Read the target space's wiki/index.md first, inspect relevant pages and raw/source references in that same space, cite the wiki page paths and raw source paths used, and say when the wiki does not contain enough evidence. Useful durable synthesis should be filed back into wiki/synthesis/ inside that same space. Always pass the operation issue's wikiId and spaceSlug to LLM Wiki tools.
+`;
+
+export const LINT_PROMPT = `Lint the LLM Wiki using the installed wiki-lint skill.
+
+Audit the target space only for contradictions, stale claims, orphan pages, missing backlinks, weak provenance, and wiki/index.md / wiki/log.md drift. Also look for important concepts mentioned without pages and answers that should have been filed back into wiki/. Return findings grouped by severity with concrete file paths, evidence, and suggested fixes — do not auto-apply edits. Always pass the operation issue's wikiId and spaceSlug to LLM Wiki tools.
+`;
+
+export const BOOTSTRAP_FILES: ReadonlyArray<{ path: string; contents: string }> = [
+  { path: ".gitignore", contents: DEFAULT_GITIGNORE },
+  { path: "AGENTS.md", contents: DEFAULT_WIKI_SCHEMA },
+  { path: "IDEA.md", contents: DEFAULT_IDEA },
+  { path: "wiki/index.md", contents: DEFAULT_INDEX },
+  { path: "wiki/log.md", contents: DEFAULT_LOG },
+  { path: "raw/.gitkeep", contents: "" },
+  { path: "wiki/sources/.gitkeep", contents: "" },
+  { path: "wiki/projects/.gitkeep", contents: "" },
+  { path: "wiki/entities/.gitkeep", contents: "" },
+  { path: "wiki/concepts/.gitkeep", contents: "" },
+  { path: "wiki/synthesis/.gitkeep", contents: "" },
+];
diff --git a/packages/plugins/plugin-llm-wiki/src/ui/app.tsx b/packages/plugins/plugin-llm-wiki/src/ui/app.tsx
new file mode 100644
index 00000000..8110e827
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/src/ui/app.tsx
@@ -0,0 +1,7120 @@
+import {
+  AssigneePicker,
+  FileTree,
+  IssuesList as PluginIssuesList,
+  ManagedRoutinesList as PluginManagedRoutinesList,
+  MarkdownBlock,
+  MarkdownEditor,
+  ProjectPicker,
+  usePluginAction,
+  usePluginData,
+  usePluginStream,
+  usePluginToast,
+  useHostLocation,
+  useHostNavigation,
+  type FileTreeNode,
+  type ManagedRoutinesListItem,
+  type PluginPageProps,
+  type PluginRouteSidebarProps,
+  type PluginSettingsPageProps,
+  type PluginSidebarProps,
+} from "@paperclipai/plugin-sdk/ui";
+import { useCallback, useEffect, useMemo, useRef, useState, type AnchorHTMLAttributes, type CSSProperties, type ReactElement, type ReactNode } from "react";
+import { readIngestOperationIssueId, uploadIssueAttachmentFile } from "./issue-attachments.js";
+
+// ---------------------------------------------------------------------------
+// Shared design tokens — copied from the UX wireframe shared.css so the plugin
+// looks identical inside the host whether or not host theme tokens are
+// available at runtime.
+// ---------------------------------------------------------------------------
+
+const tokens = {
+  border: "var(--border, oklch(0.269 0 0))",
+  card: "var(--card, oklch(0.205 0 0))",
+  bg: "var(--background, oklch(0.145 0 0))",
+  fg: "var(--foreground, oklch(0.985 0 0))",
+  muted: "var(--muted-foreground, oklch(0.708 0 0))",
+  accent: "var(--accent, oklch(0.269 0 0))",
+  primary: "var(--primary, oklch(0.985 0 0))",
+  primaryFg: "var(--primary-foreground, oklch(0.205 0 0))",
+  destructive: "var(--destructive, oklch(0.637 0.237 25.331))",
+  pluginBg: "oklch(0.3 0.06 70)",
+  pluginFg: "oklch(0.92 0.08 80)",
+  pluginBorder: "oklch(0.55 0.15 70)",
+  hiddenOpBg: "oklch(0.27 0.04 280)",
+  hiddenOpFg: "oklch(0.85 0.08 280)",
+  hiddenOpBorder: "oklch(0.45 0.1 280)",
+  callout: { bg: "oklch(0.2 0.04 250)", fg: "oklch(0.85 0.08 250)", border: "oklch(0.4 0.1 250)" },
+  statusDone: "oklch(0.65 0.16 145)",
+  statusRunning: "oklch(0.7 0.13 200)",
+  statusBlocked: "oklch(0.6 0.21 25)",
+  statusInProgress: "oklch(0.58 0.18 280)",
+  statusTodo: "oklch(0.6 0.17 250)",
+  statusPaused: "oklch(0.72 0.15 70)",
+};
+
+type Tone = "todo" | "in_progress" | "in_review" | "done" | "blocked" | "running" | "paused" | "failed" | "queued" | "default";
+
+const toneStyles: Record<Tone, CSSProperties> = {
+  default: { background: "var(--secondary, oklch(0.269 0 0))", color: tokens.fg, border: `1px solid ${tokens.border}` },
+  todo: { background: "oklch(0.27 0.06 250)", color: "oklch(0.85 0.1 250)" },
+  in_progress: { background: "oklch(0.27 0.06 280)", color: "oklch(0.85 0.1 280)" },
+  in_review: { background: "oklch(0.27 0.07 305)", color: "oklch(0.85 0.1 305)" },
+  done: { background: "oklch(0.27 0.06 145)", color: "oklch(0.85 0.1 145)" },
+  blocked: { background: "oklch(0.27 0.08 25)", color: "oklch(0.82 0.13 25)" },
+  running: { background: "oklch(0.27 0.06 200)", color: "oklch(0.83 0.11 200)" },
+  paused: { background: "oklch(0.27 0.07 70)", color: "oklch(0.85 0.1 70)" },
+  failed: { background: "oklch(0.27 0.08 25)", color: "oklch(0.82 0.13 25)" },
+  queued: { background: "oklch(0.27 0.06 250)", color: "oklch(0.85 0.1 250)" },
+};
+
+const fontStack = `ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif`;
+const mobileMediaQuery = "(max-width: 767px)";
+const PLUGIN_ID = "paperclipai.plugin-llm-wiki";
+const WIKI_SIDEBAR_NAV_STATE_KEY = "paperclipWikiSidebarTreePath";
+const ROUTE_SIDEBAR_EXPANDED_STORAGE_PREFIX = `${PLUGIN_ID}:route-sidebar-expanded:v2`;
+const WIKI_TOC_STICKY_TOP = 88;
+const WIKI_SPACE_PREFETCH_LIMIT = 8;
+const DEFAULT_ROUTE_SIDEBAR_EXPANDED_PATHS = [
+  "wiki",
+  "wiki/sources",
+  "wiki/projects",
+  "wiki/entities",
+  "wiki/concepts",
+  "wiki/synthesis",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Shared types coming back from the worker.
+// ---------------------------------------------------------------------------
+
+type FolderStatus = {
+  configured: boolean;
+  path: string | null;
+  realPath: string | null;
+  access: "read" | "readWrite";
+  readable: boolean;
+  writable: boolean;
+  requiredDirectories: string[];
+  requiredFiles: string[];
+  missingDirectories: string[];
+  missingFiles: string[];
+  healthy: boolean;
+  problems: { code: string; message: string; path?: string }[];
+  checkedAt: string;
+};
+
+type ManagedAgent = {
+  status: string;
+  source?: "managed" | "selected";
+  agentId?: string | null;
+  resourceKey?: string | null;
+  details?: { name?: string; status?: string; adapterType?: string | null; icon?: string | null; urlKey?: string | null } | null;
+  defaultDrift?: { entryFile: string; changedFiles: string[] } | null;
+};
+
+type ManagedProject = {
+  status: string;
+  source?: "managed" | "selected";
+  projectId?: string | null;
+  resourceKey?: string | null;
+  details?: { name?: string; status?: string; color?: string | null } | null;
+};
+
+type ManagedRoutine = {
+  status: string;
+  routineId?: string | null;
+  resourceKey?: string | null;
+  missingRefs?: Array<{ pluginKey?: string; resourceKind: string; resourceKey: string }>;
+  defaultDrift?: {
+    changedFields: string[];
+    defaultTitle?: string | null;
+    defaultDescription?: string | null;
+  } | null;
+  routine?: {
+    id?: string;
+    title?: string;
+    status?: string;
+    assigneeAgentId?: string | null;
+    projectId?: string | null;
+    lastTriggeredAt?: string | null;
+    lastEnqueuedAt?: string | null;
+    managedByPlugin?: {
+      pluginDisplayName?: string;
+      resourceKey?: string;
+    } | null;
+  } | null;
+  details?: {
+    title?: string;
+    status?: string;
+    cronExpression?: string | null;
+    enabled?: boolean;
+    nextRunAt?: string | null;
+    lastRunAt?: string | null;
+    assigneeAgentId?: string | null;
+  } | null;
+};
+
+type ManagedSkill = {
+  status: string;
+  skillId?: string | null;
+  resourceKey?: string | null;
+  defaultDrift?: { changedFiles: string[] } | null;
+  skill?: {
+    id?: string;
+    name?: string;
+    key?: string;
+    description?: string | null;
+  } | null;
+  details?: {
+    name?: string;
+    key?: string;
+    description?: string | null;
+  } | null;
+};
+
+type OverviewData = {
+  status: "ok";
+  checkedAt: string;
+  wikiId: string;
+  folder: FolderStatus;
+  managedAgent: ManagedAgent;
+  managedProject: ManagedProject;
+  managedSkills: ManagedSkill[];
+  operationCount: number;
+  eventIngestion: EventIngestionSettings;
+  capabilities: string[];
+  prompts: { query: string; lint: string };
+};
+
+type EventIngestionSettings = {
+  enabled: boolean;
+  sources: {
+    issues: boolean;
+    comments: boolean;
+    documents: boolean;
+  };
+  wikiId: string;
+  maxCharacters: number;
+};
+
+type WikiEventIngestionSource = "issues" | "comments" | "documents";
+
+type PaperclipIngestionSourceScope =
+  | { kind: "active_projects"; limit: number; statuses?: Array<"in_progress" | "todo" | "done"> }
+  | { kind: "selected_projects"; projectIds: string[] }
+  | { kind: "root_issues"; issueIds: string[] }
+  | { kind: "company_all"; requiresBoardConfirmation: true };
+
+type PaperclipIngestionProfile = {
+  version: 1;
+  enabled: boolean;
+  sourceScopes: PaperclipIngestionSourceScope[];
+  sourceKinds: {
+    issues: boolean;
+    comments: boolean;
+    documents: boolean;
+    attachments: "off" | "metadata_only";
+    workProducts: "off" | "metadata_only";
+  };
+  cursor: {
+    maxWindowCharacters: number;
+    maxCharactersPerSource: number;
+    minSourceAgeMinutes: number;
+    maxWindowsPerRun: number;
+    staleAfterHours: number;
+  };
+  backfill: {
+    defaultStartAt?: string | null;
+    defaultEndAt?: string | null;
+    requireManualQueue: boolean;
+  };
+};
+
+type PaperclipIngestionProfileData = {
+  wikiId: string;
+  space: Pick<WikiSpace, "id" | "slug" | "displayName" | "accessScope" | "status">;
+  profile: PaperclipIngestionProfile;
+  effectiveState: "enabled" | "disabled" | "policy_blocked" | "pending_approval" | "enabled_no_scopes";
+  policyBlocks: string[];
+  historicalPageCount: number;
+  overlapCount: number;
+};
+
+type SettingsData = {
+  folder: FolderStatus;
+  managedAgent: ManagedAgent;
+  managedProject: ManagedProject;
+  managedRoutine?: ManagedRoutine;
+  managedRoutines?: ManagedRoutine[];
+  managedSkills?: ManagedSkill[];
+  distillationPolicy?: {
+    autoApplyAllowed: boolean;
+    autoApplyRestriction: string | null;
+    deploymentMode: "local_trusted" | "authenticated" | null;
+    deploymentExposure: "private" | "public" | null;
+  };
+  eventIngestion: EventIngestionSettings;
+  agentOptions: Array<{ id: string; name: string; status?: string | null; adapterType?: string | null; icon?: string | null; urlKey?: string | null }>;
+  projectOptions: Array<{ id: string; name: string; status?: string | null; color?: string | null }>;
+  capabilities: string[];
+};
+
+type WikiSpace = {
+  id: string;
+  companyId: string;
+  wikiId: string;
+  slug: string;
+  displayName: string;
+  spaceType: string;
+  folderMode: string;
+  rootFolderKey: string;
+  pathPrefix: string | null;
+  configuredRootPath: string | null;
+  accessScope: string;
+  ownerUserId: string | null;
+  ownerAgentId: string | null;
+  teamKey: string | null;
+  settings: Record<string, unknown>;
+  status: string;
+  createdAt: string | null;
+  updatedAt: string | null;
+};
+
+type WikiSpacesData = {
+  spaces: WikiSpace[];
+};
+
+type WikiSpaceWithFolderStatus = WikiSpace & {
+  relativeRoot: string;
+  folder: FolderStatus;
+};
+
+const DEFAULT_SPACE_SLUG = "default";
+
+type WikiPageRow = {
+  path: string;
+  title: string | null;
+  pageType: string | null;
+  backlinkCount: number;
+  sourceCount: number;
+  contentHash: string | null;
+  updatedAt: string;
+};
+
+type WikiSourceRow = {
+  rawPath: string;
+  title: string | null;
+  sourceType: string;
+  url: string | null;
+  status: string;
+  createdAt: string;
+};
+
+type PagesData = {
+  pages: WikiPageRow[];
+  sources: WikiSourceRow[];
+};
+
+type PageContentData = {
+  wikiId: string;
+  path: string;
+  contents: string;
+  title: string | null;
+  pageType: string | null;
+  backlinks: string[];
+  sourceRefs: Array<Record<string, unknown> | string>;
+  updatedAt: string | null;
+  hash: string;
+};
+
+type WikiOperationRow = {
+  id: string;
+  operationType: string;
+  status: string;
+  hiddenIssueId: string | null;
+  hiddenIssueIdentifier: string | null;
+  hiddenIssueTitle: string | null;
+  hiddenIssueStatus: string | null;
+  projectId: string | null;
+  runIds: unknown[];
+  costCents: number;
+  warnings: unknown[];
+  affectedPages: unknown[];
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type OperationsData = {
+  operations: WikiOperationRow[];
+};
+
+type TemplateData = {
+  path: string;
+  contents: string;
+  hash: string | null;
+  exists: boolean;
+};
+
+type WikiFrontmatterValue = string | string[];
+
+type WikiFrontmatterProperty = {
+  key: string;
+  value: WikiFrontmatterValue;
+};
+
+type ParsedWikiMarkdown = {
+  body: string;
+  frontmatter: WikiFrontmatterProperty[];
+};
+
+type WikiTocHeading = {
+  id: string;
+  text: string;
+  level: number;
+};
+
+// ---------------------------------------------------------------------------
+// Small presentational primitives.
+// ---------------------------------------------------------------------------
+
+function Badge({ children, tone = "default", style }: { children: ReactNode; tone?: Tone; style?: CSSProperties }) {
+  return (
+    <span style={{
+      display: "inline-flex",
+      alignItems: "center",
+      gap: 4,
+      padding: "2px 8px",
+      borderRadius: 999,
+      fontSize: 11,
+      fontWeight: 500,
+      whiteSpace: "nowrap",
+      ...toneStyles[tone],
+      ...style,
+    }}>{children}</span>
+  );
+}
+
+function HiddenOpBadge() {
+  return (
+    <span style={{
+      display: "inline-flex",
+      alignItems: "center",
+      gap: 4,
+      padding: "2px 8px",
+      borderRadius: 999,
+      fontSize: 11,
+      fontWeight: 500,
+      background: tokens.hiddenOpBg,
+      color: tokens.hiddenOpFg,
+      border: `1px solid ${tokens.hiddenOpBorder}`,
+    }}>📖 wiki task</span>
+  );
+}
+
+function StatusIcon({ status }: { status: string }) {
+  const map: Record<string, { color: string; filled?: boolean; pulse?: boolean }> = {
+    done: { color: tokens.statusDone, filled: true },
+    in_progress: { color: tokens.statusInProgress },
+    running: { color: tokens.statusRunning, pulse: true },
+    queued: { color: tokens.statusTodo },
+    todo: { color: tokens.statusTodo },
+    blocked: { color: tokens.statusBlocked },
+    failed: { color: tokens.statusBlocked },
+    paused: { color: tokens.statusPaused },
+  };
+  const tone = map[status] ?? { color: tokens.muted };
+  return (
+    <span style={{
+      width: 12,
+      height: 12,
+      flexShrink: 0,
+      borderRadius: "50%",
+      border: `2px solid ${tone.color}`,
+      background: tone.filled ? tone.color : "transparent",
+      animation: tone.pulse ? "pcWikiPulse 1.6s infinite" : undefined,
+    }} aria-hidden />
+  );
+}
+
+function Card({ children, style }: { children: ReactNode; style?: CSSProperties }) {
+  return (
+    <section style={{
+      background: tokens.card,
+      border: `1px solid ${tokens.border}`,
+      borderRadius: 8,
+      overflow: "hidden",
+      minWidth: 0,
+      ...style,
+    }}>{children}</section>
+  );
+}
+
+function CardHeader({ title, right, badges }: { title: ReactNode; right?: ReactNode; badges?: ReactNode }) {
+  return (
+    <div style={{
+      padding: "12px 16px",
+      borderBottom: `1px solid ${tokens.border}`,
+      display: "flex",
+      alignItems: "center",
+      flexWrap: "wrap",
+      gap: 12,
+      minWidth: 0,
+    }}>
+      <h3 style={{ margin: 0, fontSize: 14, fontWeight: 600, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis" }}>{title}</h3>
+      {badges}
+      {right ? <div style={{ marginLeft: "auto", minWidth: 0, maxWidth: "100%" }}>{right}</div> : null}
+    </div>
+  );
+}
+
+function CardBody({ children, padding = 16 }: { children: ReactNode; padding?: number | string }) {
+  return <div style={{ padding }}>{children}</div>;
+}
+
+const unfilledSurfaceStyle: CSSProperties = {
+  background: "transparent",
+};
+
+function PropRow({ label, value }: { label: ReactNode; value: ReactNode }) {
+  return (
+    <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", flexWrap: "wrap", padding: "4px 0", fontSize: 13, gap: 12, minWidth: 0 }}>
+      <span style={{ color: tokens.muted, fontSize: 12, flexShrink: 0 }}>{label}</span>
+      <span style={{ flex: "1 1 160px", minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "normal", overflowWrap: "anywhere", textAlign: "right" }}>{value}</span>
+    </div>
+  );
+}
+
+function Tiny({ children, style }: { children: ReactNode; style?: CSSProperties }) {
+  return <div style={{ fontSize: 11, color: tokens.muted, ...style }}>{children}</div>;
+}
+
+function Mono({ children, style }: { children: ReactNode; style?: CSSProperties }) {
+  return <span style={{ fontFamily: "ui-monospace, SFMono-Regular, monospace", fontSize: 12, overflowWrap: "anywhere", wordBreak: "break-word", ...style }}>{children}</span>;
+}
+
+type ButtonVariant = "primary" | "default" | "ghost" | "destructive";
+type ButtonSize = "sm" | "md";
+
+function Button({
+  variant = "default",
+  size = "md",
+  disabled,
+  loading,
+  onClick,
+  children,
+  type = "button",
+  style,
+  title,
+}: {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  disabled?: boolean;
+  loading?: boolean;
+  onClick?: () => void;
+  children: ReactNode;
+  type?: "button" | "submit";
+  style?: CSSProperties;
+  title?: string;
+}) {
+  const palette: Record<ButtonVariant, CSSProperties> = {
+    primary: {
+      background: tokens.primary,
+      color: tokens.primaryFg,
+      border: `1px solid transparent`,
+    },
+    default: {
+      background: tokens.card,
+      color: tokens.fg,
+      border: `1px solid ${tokens.border}`,
+    },
+    ghost: {
+      background: "transparent",
+      color: tokens.fg,
+      border: `1px solid transparent`,
+    },
+    destructive: {
+      background: "transparent",
+      color: "oklch(0.7 0.2 25)",
+      border: `1px solid oklch(0.5 0.18 25)`,
+    },
+  };
+  return (
+    <button
+      type={type}
+      title={title}
+      disabled={disabled || loading}
+      onClick={onClick}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 6,
+        padding: size === "sm" ? "3px 8px" : "6px 12px",
+        borderRadius: 6,
+        fontSize: size === "sm" ? 11 : 13,
+        fontWeight: 500,
+        cursor: disabled || loading ? "not-allowed" : "pointer",
+        opacity: disabled || loading ? 0.5 : 1,
+        fontFamily: fontStack,
+        minWidth: 0,
+        whiteSpace: "nowrap",
+        ...palette[variant],
+        ...style,
+      }}
+  >{children}</button>
+  );
+}
+
+function TextInput(props: React.InputHTMLAttributes<HTMLInputElement>) {
+  return (
+    <input
+      {...props}
+      style={{
+        background: "oklch(0.2 0 0)",
+        border: `1px solid ${tokens.border}`,
+        borderRadius: 6,
+        padding: "6px 10px",
+        fontSize: 13,
+        color: tokens.fg,
+        width: "100%",
+        boxSizing: "border-box",
+        minWidth: 0,
+        fontFamily: fontStack,
+        ...props.style,
+      }}
+    />
+  );
+}
+
+function TextArea(props: React.TextareaHTMLAttributes<HTMLTextAreaElement>) {
+  return (
+    <textarea
+      {...props}
+      style={{
+        background: "oklch(0.2 0 0)",
+        border: `1px solid ${tokens.border}`,
+        borderRadius: 6,
+        padding: "6px 10px",
+        fontSize: 13,
+        color: tokens.fg,
+        width: "100%",
+        boxSizing: "border-box",
+        minWidth: 0,
+        minHeight: 96,
+        fontFamily: fontStack,
+        resize: "vertical",
+        ...props.style,
+      }}
+    />
+  );
+}
+
+type AutosaveStatus = "idle" | "dirty" | "saving" | "saved" | "error";
+
+function AutosaveStatusLabel({ status, error }: { status: AutosaveStatus; error: string | null }) {
+  if (status === "saving") return <Tiny>Saving…</Tiny>;
+  if (status === "saved") return <Tiny>Saved</Tiny>;
+  if (status === "dirty") return <Tiny>Unsaved changes</Tiny>;
+  if (status === "error") return <Tiny style={{ color: "oklch(0.7 0.2 25)" }}>{error ?? "Autosave failed"}</Tiny>;
+  return <Tiny>Autosave on</Tiny>;
+}
+
+function AutosaveMarkdownEditor({
+  value,
+  placeholder,
+  minHeight,
+  resetKey,
+  onSave,
+  onStatusChange,
+}: {
+  value: string;
+  placeholder?: string;
+  minHeight?: number;
+  resetKey: string;
+  onSave: (value: string) => Promise<void>;
+  onStatusChange?: (status: AutosaveStatus) => void;
+}) {
+  const [draft, setDraft] = useState(value);
+  const [lastSaved, setLastSaved] = useState(value);
+  const [status, setStatus] = useState<AutosaveStatus>("idle");
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setDraft(value);
+    setLastSaved(value);
+    setStatus("idle");
+    setError(null);
+    onStatusChange?.("idle");
+  }, [onStatusChange, resetKey, value]);
+
+  useEffect(() => {
+    if (draft === lastSaved) return;
+    setStatus("dirty");
+    setError(null);
+    onStatusChange?.("dirty");
+    const timeout = window.setTimeout(async () => {
+      setStatus("saving");
+      onStatusChange?.("saving");
+      try {
+        await onSave(draft);
+        setLastSaved(draft);
+        setStatus("saved");
+        onStatusChange?.("saved");
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        setError(message);
+        setStatus("error");
+        onStatusChange?.("error");
+      }
+    }, 800);
+    return () => window.clearTimeout(timeout);
+  }, [draft, lastSaved, onSave, onStatusChange]);
+
+  return (
+    <div style={{ display: "grid", gap: 6, minWidth: 0 }}>
+      <MarkdownEditor
+        value={draft}
+        onChange={setDraft}
+        placeholder={placeholder}
+        bordered
+        contentClassName="min-h-[260px]"
+        className="pc-wiki-markdown-editor"
+      />
+      <style>{`
+        .pc-wiki-markdown-editor .mdxeditor-root-contenteditable {
+          min-height: ${minHeight ?? 260}px;
+        }
+      `}</style>
+      <AutosaveStatusLabel status={status} error={error} />
+    </div>
+  );
+}
+
+function Callout({ children, tone = "info" }: { children: ReactNode; tone?: "info" | "warn" | "danger" }) {
+  const palette = tone === "danger"
+    ? { bg: "oklch(0.22 0.06 25)", fg: "oklch(0.85 0.12 25)", border: "oklch(0.45 0.12 25)" }
+    : tone === "warn"
+      ? { bg: "oklch(0.22 0.06 70)", fg: "oklch(0.85 0.1 70)", border: "oklch(0.45 0.12 70)" }
+      : tokens.callout;
+  return (
+    <div style={{
+      background: palette.bg,
+      color: palette.fg,
+      border: `1px solid ${palette.border}`,
+      borderRadius: 8,
+      padding: "12px 14px",
+      fontSize: 13,
+      lineHeight: 1.55,
+    }}>{children}</div>
+  );
+}
+
+function Divider() {
+  return <div style={{ height: 1, background: tokens.border, margin: "16px 0" }} />;
+}
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+function useMediaQuery(query: string): boolean {
+  const getSnapshot = () => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+    return window.matchMedia(query).matches;
+  };
+  const [matches, setMatches] = useState(getSnapshot);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const mediaQuery = window.matchMedia(query);
+    const handleChange = (event: MediaQueryListEvent) => setMatches(event.matches);
+    setMatches(mediaQuery.matches);
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, [query]);
+
+  return matches;
+}
+
+function useIsMobileLayout(): boolean {
+  return useMediaQuery(mobileMediaQuery);
+}
+
+function useOverview(companyId: string | null) {
+  const params = useMemo(() => companyId ? { companyId } : undefined, [companyId]);
+  return usePluginData<OverviewData>("overview", params);
+}
+
+function useSettings(companyId: string | null) {
+  const params = useMemo(() => companyId ? { companyId } : undefined, [companyId]);
+  return usePluginData<SettingsData>("settings", params);
+}
+
+function usePages(companyId: string | null, opts: { includeRaw?: boolean; spaceSlug?: string | null } = {}) {
+  const params = useMemo(() => {
+    if (!companyId) return undefined;
+    const next: Record<string, unknown> = { companyId, includeRaw: opts.includeRaw ?? true };
+    if (opts.spaceSlug && opts.spaceSlug !== DEFAULT_SPACE_SLUG) next.spaceSlug = opts.spaceSlug;
+    else if (opts.spaceSlug === DEFAULT_SPACE_SLUG) next.spaceSlug = DEFAULT_SPACE_SLUG;
+    return next;
+  }, [companyId, opts.includeRaw, opts.spaceSlug]);
+  return usePluginData<PagesData>("pages", params);
+}
+
+function useSpaces(companyId: string | null) {
+  const params = useMemo(() => companyId ? { companyId } : undefined, [companyId]);
+  return usePluginData<WikiSpacesData>("spaces", params);
+}
+
+function useSpaceFolderStatus(companyId: string | null, spaceSlug: string | null) {
+  const params = useMemo(() => {
+    if (!companyId || !spaceSlug) return undefined;
+    return { companyId, spaceSlug };
+  }, [companyId, spaceSlug]);
+  return usePluginData<WikiSpaceWithFolderStatus>("space", params);
+}
+
+function usePaperclipIngestionProfile(companyId: string | null, spaceSlug: string | null) {
+  const params = useMemo(() => {
+    if (!companyId || !spaceSlug) return undefined;
+    return { companyId, spaceSlug };
+  }, [companyId, spaceSlug]);
+  return usePluginData<PaperclipIngestionProfileData>("paperclip-ingestion-profile", params);
+}
+
+function usePageContent(companyId: string | null, path: string | null, spaceSlug?: string | null) {
+  const params = useMemo(() => {
+    if (!companyId || !path) return undefined;
+    const next: Record<string, unknown> = { companyId, path };
+    if (spaceSlug) next.spaceSlug = spaceSlug;
+    return next;
+  }, [companyId, path, spaceSlug]);
+  return usePluginData<PageContentData>("page-content", params);
+}
+
+function useOperations(companyId: string | null, filter: { operationType?: string | null; status?: string | null; spaceSlug?: string | null } = {}) {
+  const params = useMemo(() => {
+    if (!companyId) return undefined;
+    return {
+      companyId,
+      operationType: filter.operationType ?? null,
+      status: filter.status ?? null,
+      spaceSlug: filter.spaceSlug ?? null,
+    };
+  }, [companyId, filter.operationType, filter.status, filter.spaceSlug]);
+  return usePluginData<OperationsData>("operations", params);
+}
+
+function useTemplate(companyId: string | null, path: string) {
+  const params = useMemo(() => {
+    if (!companyId) return undefined;
+    return { companyId, path };
+  }, [companyId, path]);
+  return usePluginData<TemplateData>("template", params);
+}
+
+type DistillationCursor = {
+  id: string;
+  sourceScope: string;
+  scopeKey: string;
+  projectId: string | null;
+  projectName: string | null;
+  projectColor: string | null;
+  rootIssueId: string | null;
+  rootIssueIdentifier: string | null;
+  rootIssueTitle: string | null;
+  lastProcessedAt: string | null;
+  lastObservedAt: string | null;
+  pendingEventCount: number;
+  lastSourceHash: string | null;
+  lastSuccessfulRunId: string | null;
+};
+
+type DistillationRun = {
+  id: string;
+  cursorId: string | null;
+  workItemId: string | null;
+  projectId: string | null;
+  projectName: string | null;
+  rootIssueId: string | null;
+  rootIssueIdentifier: string | null;
+  sourceWindowStart: string | null;
+  sourceWindowEnd: string | null;
+  sourceHash: string | null;
+  status: string;
+  costCents: number;
+  retryCount: number;
+  warnings: string[];
+  metadata: Record<string, unknown>;
+  operationIssueId: string | null;
+  operationIssueIdentifier: string | null;
+  operationIssueTitle: string | null;
+  affectedPagePaths: string[];
+  createdAt: string;
+  updatedAt: string;
+};
+
+type DistillationWorkItem = {
+  id: string;
+  workItemKind: string;
+  status: string;
+  priority: string;
+  projectId: string | null;
+  rootIssueId: string | null;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type DistillationPageBinding = {
+  id: string;
+  pagePath: string;
+  projectId: string | null;
+  projectName: string | null;
+  rootIssueId: string | null;
+  lastAppliedSourceHash: string | null;
+  lastDistillationRunId: string | null;
+  lastRunStatus: string | null;
+  lastRunCompletedAt: string | null;
+  lastRunSourceWindowEnd: string | null;
+  lastRunSourceHash: string | null;
+  metadata: Record<string, unknown>;
+  updatedAt: string;
+};
+
+type DistillationOverviewData = {
+  cursors: DistillationCursor[];
+  runs: DistillationRun[];
+  workItems: DistillationWorkItem[];
+  pageBindings: DistillationPageBinding[];
+  reviewWorkItems: DistillationWorkItem[];
+  counts: {
+    cursors: number;
+    runningRuns: number;
+    failedRuns24h: number;
+    reviewRequired: number;
+  };
+};
+
+function useDistillationOverview(companyId: string | null) {
+  const params = useMemo(() => (companyId ? { companyId } : undefined), [companyId]);
+  return usePluginData<DistillationOverviewData>("distillation-overview", params);
+}
+
+type DistillationProvenanceData = {
+  binding: DistillationPageBinding | null;
+  runs: DistillationRun[];
+  snapshot: {
+    id: string;
+    distillationRunId: string;
+    sourceHash: string;
+    maxCharacters: number;
+    clipped: boolean;
+    sourceRefs: Array<Record<string, unknown> | string>;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+  } | null;
+  cursor: DistillationCursor | null;
+};
+
+function useDistillationProvenance(companyId: string | null, pagePath: string | null) {
+  const params = useMemo(() => {
+    if (!companyId || !pagePath) return undefined;
+    return { companyId, pagePath };
+  }, [companyId, pagePath]);
+  return usePluginData<DistillationProvenanceData>("distillation-page-provenance", params);
+}
+
+function stripYamlInlineComment(value: string): string {
+  let quote: "'" | "\"" | null = null;
+  for (let i = 0; i < value.length; i++) {
+    const char = value[i];
+    const previous = value[i - 1];
+    if ((char === "'" || char === "\"") && previous !== "\\") {
+      quote = quote === char ? null : quote ?? char;
+    }
+    if (char === "#" && quote === null && (i === 0 || /\s/.test(previous ?? ""))) {
+      return value.slice(0, i).trimEnd();
+    }
+  }
+  return value.trim();
+}
+
+function unquoteYamlScalar(value: string): string {
+  const trimmed = stripYamlInlineComment(value).trim();
+  if (trimmed.length >= 2) {
+    const first = trimmed[0];
+    const last = trimmed[trimmed.length - 1];
+    if ((first === "\"" && last === "\"") || (first === "'" && last === "'")) {
+      return trimmed.slice(1, -1);
+    }
+  }
+  return trimmed;
+}
+
+function parseYamlInlineArray(value: string): string[] | null {
+  const trimmed = stripYamlInlineComment(value).trim();
+  if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return null;
+  const body = trimmed.slice(1, -1).trim();
+  if (!body) return [];
+
+  const items: string[] = [];
+  let current = "";
+  let quote: "'" | "\"" | null = null;
+  for (let i = 0; i < body.length; i++) {
+    const char = body[i];
+    const previous = body[i - 1];
+    if ((char === "'" || char === "\"") && previous !== "\\") {
+      quote = quote === char ? null : quote ?? char;
+      current += char;
+      continue;
+    }
+    if (char === "," && quote === null) {
+      const item = unquoteYamlScalar(current);
+      if (item) items.push(item);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+
+  const item = unquoteYamlScalar(current);
+  if (item) items.push(item);
+  return items;
+}
+
+function parseFrontmatterValue(rawValue: string, followingList: string[]): WikiFrontmatterValue {
+  const inlineArray = parseYamlInlineArray(rawValue);
+  if (inlineArray) return inlineArray;
+  if (!rawValue.trim() && followingList.length > 0) return followingList;
+  return unquoteYamlScalar(rawValue);
+}
+
+function parseWikiFrontmatterBlock(block: string): WikiFrontmatterProperty[] {
+  const lines = block.replace(/\r\n/g, "\n").split("\n");
+  const properties: WikiFrontmatterProperty[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || line.trimStart().startsWith("#")) continue;
+    if (/^\s+-\s+/.test(line)) continue;
+
+    const match = line.match(/^([A-Za-z0-9_-]+):(?:\s*(.*))?$/);
+    if (!match) continue;
+
+    const key = match[1];
+    const rawValue = match[2] ?? "";
+    const followingList: string[] = [];
+    let cursor = i + 1;
+    while (cursor < lines.length) {
+      const listMatch = lines[cursor]?.match(/^\s+-\s+(.+)$/);
+      if (!listMatch) break;
+      followingList.push(unquoteYamlScalar(listMatch[1] ?? ""));
+      cursor += 1;
+    }
+    if (!rawValue.trim() && followingList.length > 0) i = cursor - 1;
+
+    const value = parseFrontmatterValue(rawValue, followingList);
+    if (Array.isArray(value) ? value.length > 0 : value.length > 0) {
+      properties.push({ key, value });
+    }
+  }
+
+  return properties;
+}
+
+function parseWikiMarkdown(contents: string): ParsedWikiMarkdown {
+  const normalized = contents.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return { body: contents, frontmatter: [] };
+  }
+
+  const closingMatch = normalized.slice(4).match(/\n(?:---|\.\.\.)[ \t]*(?:\n|$)/);
+  if (!closingMatch || closingMatch.index == null) {
+    return { body: contents, frontmatter: [] };
+  }
+
+  const frontmatterBlock = normalized.slice(4, closingMatch.index + 4);
+  const bodyStart = 4 + closingMatch.index + closingMatch[0].length;
+  return {
+    body: normalized.slice(bodyStart).replace(/^\n+/, ""),
+    frontmatter: parseWikiFrontmatterBlock(frontmatterBlock),
+  };
+}
+
+function stripMarkdownHeadingSyntax(text: string): string {
+  return text
+    .replace(/\\([\\`*_{}\[\]()#+\-.!|>])/g, "$1")
+    .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    .replace(/\[\[([^\]|]+)\|([^\]]+)\]\]/g, "$2")
+    .replace(/\[\[([^\]]+)\]\]/g, "$1")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/[*_~]+/g, "")
+    .replace(/<[^>]+>/g, "")
+    .trim();
+}
+
+function slugifyWikiHeading(text: string): string {
+  const slug = stripMarkdownHeadingSyntax(text)
+    .toLowerCase()
+    .replace(/&[a-z0-9#]+;/g, "")
+    .replace(/[^a-z0-9\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-");
+  return slug || "section";
+}
+
+function extractWikiTocHeadings(markdownBody: string): WikiTocHeading[] {
+  const lines = markdownBody.replace(/\r\n/g, "\n").split("\n");
+  const headings: WikiTocHeading[] = [];
+  const usedIds = new Map<string, number>();
+  let fenced = false;
+
+  for (const line of lines) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      fenced = !fenced;
+      continue;
+    }
+    if (fenced) continue;
+
+    const match = line.match(/^\s{0,3}(#{2,4})\s+(.+?)\s*#*\s*$/);
+    if (!match) continue;
+
+    const text = stripMarkdownHeadingSyntax(match[2] ?? "");
+    if (!text) continue;
+
+    const baseId = slugifyWikiHeading(text);
+    const count = usedIds.get(baseId) ?? 0;
+    usedIds.set(baseId, count + 1);
+    headings.push({
+      id: count === 0 ? baseId : `${baseId}-${count + 1}`,
+      text,
+      level: match[1]?.length ?? 2,
+    });
+  }
+
+  return headings;
+}
+
+// ---------------------------------------------------------------------------
+// Sidebar entry and settings page.
+// ---------------------------------------------------------------------------
+
+// Stroke-2, 16×16 lucide-react icons inlined here because plugin bundles
+// cannot import `lucide-react` directly (host-only dep). Path data tracks the
+// upstream lucide source 1:1 — keep them in sync if upstream changes.
+
+type LucideIconProps = { size?: number };
+
+function makeLucideIcon(paths: ReactNode) {
+  return function LucideIcon({ size = 16 }: LucideIconProps) {
+    return (
+      <svg
+        aria-hidden="true"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        style={{ width: size, height: size, display: "block" }}
+      >
+        {paths}
+      </svg>
+    );
+  };
+}
+
+const BookOpenIcon = makeLucideIcon(
+  <>
+    <path d="M12 7v14" />
+    <path d="M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z" />
+  </>,
+);
+
+const DownloadCloudIcon = makeLucideIcon(
+  <>
+    <path d="M12 13v8l-4-4" />
+    <path d="m12 21 4-4" />
+    <path d="M4.393 15.269A7 7 0 1 1 15.71 8.071" />
+  </>,
+);
+
+const MessageSquareTextIcon = makeLucideIcon(
+  <>
+    <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+    <path d="M13 8H7" />
+    <path d="M17 12H7" />
+  </>,
+);
+
+const ListChecksIcon = makeLucideIcon(
+  <>
+    <path d="m3 17 2 2 4-4" />
+    <path d="m3 7 2 2 4-4" />
+    <path d="M13 6h8" />
+    <path d="M13 12h8" />
+    <path d="M13 18h8" />
+  </>,
+);
+
+const HistoryIcon = makeLucideIcon(
+  <>
+    <path d="M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8" />
+    <path d="M3 3v5h5" />
+    <path d="M12 7v5l4 2" />
+  </>,
+);
+
+const SlidersHorizontalIcon = makeLucideIcon(
+  <>
+    <line x1="21" x2="14" y1="4" y2="4" />
+    <line x1="10" x2="3" y1="4" y2="4" />
+    <line x1="21" x2="12" y1="12" y2="12" />
+    <line x1="8" x2="3" y1="12" y2="12" />
+    <line x1="21" x2="16" y1="20" y2="20" />
+    <line x1="12" x2="3" y1="20" y2="20" />
+    <line x1="14" x2="14" y1="2" y2="6" />
+    <line x1="8" x2="8" y1="10" y2="14" />
+    <line x1="16" x2="16" y1="18" y2="22" />
+  </>,
+);
+
+const FolderOpenIcon = makeLucideIcon(
+  <>
+    <path d="M6 14h.01" />
+    <path d="M3 6h5l2 2h11v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z" />
+  </>,
+);
+
+const ActivityIcon = makeLucideIcon(
+  <path d="M22 12h-2.48a2 2 0 0 0-1.93 1.46l-2.35 8.36a.5.5 0 0 1-.96 0L9.24 3.18a.5.5 0 0 0-.96 0l-2.35 8.36A2 2 0 0 1 4 13H2" />,
+);
+
+const InfoIcon = makeLucideIcon(
+  <>
+    <circle cx="12" cy="12" r="10" />
+    <path d="M12 16v-4" />
+    <path d="M12 8h.01" />
+  </>,
+);
+
+const SparklesIcon = makeLucideIcon(
+  <>
+    <path d="m12 3-1.9 5.8a2 2 0 0 1-1.3 1.3L3 12l5.8 1.9a2 2 0 0 1 1.3 1.3L12 21l1.9-5.8a2 2 0 0 1 1.3-1.3L21 12l-5.8-1.9a2 2 0 0 1-1.3-1.3z" />
+    <path d="M5 3v4" />
+    <path d="M19 17v4" />
+    <path d="M3 5h4" />
+    <path d="M17 19h4" />
+  </>,
+);
+
+const RefreshIcon = makeLucideIcon(
+  <>
+    <path d="M3 12a9 9 0 0 1 15-6.7L21 8" />
+    <path d="M21 3v5h-5" />
+    <path d="M21 12a9 9 0 0 1-15 6.7L3 16" />
+    <path d="M3 21v-5h5" />
+  </>,
+);
+
+const ExternalLinkIcon = makeLucideIcon(
+  <>
+    <path d="M15 3h6v6" />
+    <path d="M10 14 21 3" />
+    <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+  </>,
+);
+
+const ClockIcon = makeLucideIcon(
+  <>
+    <circle cx="12" cy="12" r="10" />
+    <path d="M12 6v6l4 2" />
+  </>,
+);
+
+const AlertTriangleIcon = makeLucideIcon(
+  <>
+    <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3z" />
+    <path d="M12 9v4" />
+    <path d="M12 17h.01" />
+  </>,
+);
+
+const XIcon = makeLucideIcon(
+  <>
+    <path d="M18 6 6 18" />
+    <path d="m6 6 12 12" />
+  </>,
+);
+
+const ChevronLeftIcon = makeLucideIcon(<path d="m15 18-6-6 6-6" />);
+
+const ChevronRightIcon = makeLucideIcon(<path d="m9 6 6 6-6 6" />);
+
+const ChevronDownIcon = makeLucideIcon(<path d="m6 9 6 6 6-6" />);
+
+const PlusIcon = makeLucideIcon(
+  <>
+    <path d="M12 5v14" />
+    <path d="M5 12h14" />
+  </>,
+);
+
+const PlusCircleIcon = makeLucideIcon(
+  <>
+    <circle cx="12" cy="12" r="9" />
+    <path d="M12 8v8" />
+    <path d="M8 12h8" />
+  </>,
+);
+
+const FolderIcon = makeLucideIcon(<path d="M3 7h6l2 2h10v10H3z" />);
+
+const MoreHorizontalIcon = makeLucideIcon(
+  <>
+    <circle cx="6" cy="12" r="1" />
+    <circle cx="12" cy="12" r="1" />
+    <circle cx="18" cy="12" r="1" />
+  </>,
+);
+
+const ArchiveIcon = makeLucideIcon(
+  <>
+    <path d="M3 6h18v4H3z" />
+    <path d="M5 10v10h14V10" />
+    <path d="M10 14h4" />
+  </>,
+);
+
+const PencilIcon = makeLucideIcon(
+  <>
+    <path d="M12 20h9" />
+    <path d="M16.5 3.5a2.121 2.121 0 1 1 3 3L7 19l-4 1 1-4z" />
+  </>,
+);
+
+export function SidebarLink({ context }: PluginSidebarProps) {
+  const hostNavigation = useHostNavigation();
+  return (
+    <a
+      {...hostNavigation.linkProps("/wiki")}
+      className="flex items-center gap-2.5 px-3 py-2 text-[13px] font-medium text-foreground/80 transition-colors hover:bg-accent/50 hover:text-foreground"
+      style={{ textDecoration: "none" }}
+    >
+      <span aria-hidden="true" className="shrink-0">
+        <BookOpenIcon />
+      </span>
+      <span className="flex-1 truncate">Wiki</span>
+    </a>
+  );
+}
+
+export function SettingsPage({ context }: PluginSettingsPageProps) {
+  const isMobile = useIsMobileLayout();
+  return (
+    <main style={{ padding: isMobile ? 16 : 24, maxWidth: isMobile ? "none" : 1040, minWidth: 0, fontFamily: fontStack, color: tokens.fg }}>
+      <SettingsBody context={context} />
+    </main>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main wiki page: section shell for Pages / Ask / Ingest / Lint / History /
+// Settings. Wiki navigation uses path segments so pages can be deep-linked as
+// `/:companyPrefix/wiki/page/path/to/file`. Legacy query-param links are still
+// accepted as a compatibility fallback.
+// ---------------------------------------------------------------------------
+
+type SectionKey = "browse" | "ingest" | "query" | "lint" | "history" | "settings";
+
+const SECTIONS: ReadonlyArray<{
+  key: SectionKey;
+  label: string;
+  Icon: (props: LucideIconProps) => ReactElement;
+  description: string;
+}> = [
+  { key: "browse", label: "Wiki", Icon: BookOpenIcon, description: "Open wiki pages and raw sources from the sidebar." },
+  { key: "query", label: "Ask", Icon: MessageSquareTextIcon, description: "Ask the Wiki Maintainer agent a cited question against the local wiki." },
+  { key: "ingest", label: "Add Content", Icon: PlusCircleIcon, description: "Capture a new source into the active space and queue an ingest operation." },
+  { key: "lint", label: "Lint", Icon: ListChecksIcon, description: "Run structural checks for orphan pages, missing backlinks, and stale provenance." },
+  { key: "history", label: "History", Icon: HistoryIcon, description: "Inspect recent LLM Wiki operation issues." },
+  { key: "settings", label: "Settings", Icon: SlidersHorizontalIcon, description: "Folder, agent, project, and routine configuration scoped to this company." },
+];
+
+const TOP_TOOL_KEYS: ReadonlySet<SectionKey> = new Set<SectionKey>(["query", "ingest"]);
+const BOTTOM_TOOL_KEYS: ReadonlySet<SectionKey> = new Set<SectionKey>(["history", "settings"]);
+const TOP_TOOL_SECTIONS = SECTIONS.filter((section) => TOP_TOOL_KEYS.has(section.key));
+const BOTTOM_TOOL_SECTIONS = SECTIONS.filter((section) => BOTTOM_TOOL_KEYS.has(section.key));
+const SECTION_KEYS: ReadonlySet<SectionKey> = new Set(SECTIONS.map((s) => s.key));
+const LEGACY_SECTION_ALIASES: Readonly<Partial<Record<string, SectionKey>>> = {
+  operations: "history",
+};
+
+function isSectionKey(value: string | null | undefined): value is SectionKey {
+  return typeof value === "string" && SECTION_KEYS.has(value as SectionKey);
+}
+
+function normalizeSectionKey(value: string | null | undefined): SectionKey | null {
+  if (typeof value !== "string") return null;
+  return LEGACY_SECTION_ALIASES[value] ?? (isSectionKey(value) ? value : null);
+}
+
+function readSectionFromSearch(search: string): SectionKey {
+  const params = new URLSearchParams(search);
+  const raw = params.get("section");
+  return normalizeSectionKey(raw) ?? "browse";
+}
+
+function decodeRouteSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+function readWikiRouteSegments(pathname: string): string[] {
+  const segments = pathname.split("/").filter(Boolean);
+  const wikiIndex = segments.findIndex((segment) => decodeRouteSegment(segment).toLowerCase() === "wiki");
+  if (wikiIndex === -1) return [];
+  return segments.slice(wikiIndex + 1).map(decodeRouteSegment);
+}
+
+// Strip an optional `spaces/<slug>` prefix from the wiki route segments.
+// Returns the active space slug (defaults to "default") and the remaining segments
+// after that prefix so existing section/page parsing keeps working unchanged.
+function readWikiSpaceContext(pathname: string): { spaceSlug: string; rest: string[] } {
+  const segments = readWikiRouteSegments(pathname);
+  if (segments[0] === "spaces" && typeof segments[1] === "string" && segments[1].length > 0) {
+    return { spaceSlug: segments[1], rest: segments.slice(2) };
+  }
+  return { spaceSlug: DEFAULT_SPACE_SLUG, rest: segments };
+}
+
+function readActiveSpaceSlugFromLocation(pathname: string): string {
+  return readWikiSpaceContext(pathname).spaceSlug;
+}
+
+function readSectionFromLocation(pathname: string, search: string): SectionKey {
+  const [firstSegment] = readWikiSpaceContext(pathname).rest;
+  if (firstSegment === "page") return "browse";
+  return normalizeSectionKey(firstSegment) ?? readSectionFromSearch(search);
+}
+
+function readSettingsSectionFromLocation(pathname: string): SettingsSectionKey {
+  const [firstSegment, secondSegment] = readWikiSpaceContext(pathname).rest;
+  if (firstSegment !== "settings") return "root";
+  if (secondSegment === "maintainer" || secondSegment === "project") return "root";
+  return SETTINGS_SECTIONS.some((section) => section.key === secondSegment)
+    ? secondSegment as SettingsSectionKey
+    : "root";
+}
+
+function readSettingsSpaceSlugFromLocation(pathname: string): string | null {
+  const segs = readWikiSpaceContext(pathname).rest;
+  if (segs[0] !== "settings" || segs[1] !== "spaces") return null;
+  const slug = segs[2];
+  return typeof slug === "string" && slug.length > 0 ? slug : null;
+}
+
+function buildSpacePrefix(spaceSlug: string): string {
+  return spaceSlug && spaceSlug !== DEFAULT_SPACE_SLUG
+    ? `/wiki/spaces/${encodeURIComponent(spaceSlug)}`
+    : `/wiki`;
+}
+
+function buildSectionHref(section: SectionKey, spaceSlug: string = DEFAULT_SPACE_SLUG): string {
+  const prefix = buildSpacePrefix(spaceSlug);
+  return section === "browse" ? prefix : `${prefix}/${section}`;
+}
+
+function buildSettingsSectionHref(settingsSection: SettingsSectionKey | "spaces", spaceSlug: string = DEFAULT_SPACE_SLUG, slug?: string): string {
+  const prefix = buildSpacePrefix(spaceSlug);
+  if (settingsSection === "spaces" && slug) {
+    return `${prefix}/settings/spaces/${encodeURIComponent(slug)}`;
+  }
+  if (settingsSection === "root") return `${prefix}/settings`;
+  return `${prefix}/settings/${settingsSection}`;
+}
+
+function readSelectedTreePathFromSearch(search: string): string | null {
+  const params = new URLSearchParams(search);
+  const raw = params.get("page")?.trim();
+  return raw || null;
+}
+
+function readSelectedTreePathFromLocation(pathname: string, search: string): string | null {
+  const [firstSegment, ...rest] = readWikiSpaceContext(pathname).rest;
+  if (firstSegment === "page") {
+    return treePathFromRouteSegments(rest);
+  }
+  return readSelectedTreePathFromSearch(search);
+}
+
+function buildPageHref(treePath: string, spaceSlug: string = DEFAULT_SPACE_SLUG): string {
+  const prefix = buildSpacePrefix(spaceSlug);
+  const encodedPath = routeSegmentsFromTreePath(treePath).map((segment) => encodeURIComponent(segment)).join("/");
+  return encodedPath ? `${prefix}/page/${encodedPath}` : prefix;
+}
+
+function wikiSidebarNavigationState(treePath: string): Record<typeof WIKI_SIDEBAR_NAV_STATE_KEY, string> {
+  return { [WIKI_SIDEBAR_NAV_STATE_KEY]: treePath };
+}
+
+function readSidebarSelectedPathFromNavigationState(state: unknown): string | null {
+  if (!state || typeof state !== "object") return null;
+  const value = (state as Record<string, unknown>)[WIKI_SIDEBAR_NAV_STATE_KEY];
+  return typeof value === "string" && value.trim() ? value : null;
+}
+
+function routeSidebarExpandedStorageKey(companyId: string | null | undefined): string {
+  return `${ROUTE_SIDEBAR_EXPANDED_STORAGE_PREFIX}:${companyId ?? "global"}`;
+}
+
+function readRouteSidebarExpandedPaths(storageKey: string): Set<string> {
+  if (typeof window === "undefined") return new Set(DEFAULT_ROUTE_SIDEBAR_EXPANDED_PATHS);
+
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    if (raw === null) return new Set(DEFAULT_ROUTE_SIDEBAR_EXPANDED_PATHS);
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return new Set(DEFAULT_ROUTE_SIDEBAR_EXPANDED_PATHS);
+    return new Set(parsed.filter((value): value is string => typeof value === "string" && value.trim().length > 0));
+  } catch {
+    return new Set(DEFAULT_ROUTE_SIDEBAR_EXPANDED_PATHS);
+  }
+}
+
+function writeRouteSidebarExpandedPaths(storageKey: string, paths: ReadonlySet<string>): void {
+  if (typeof window === "undefined") return;
+
+  try {
+    window.localStorage.setItem(storageKey, JSON.stringify([...paths].sort()));
+  } catch {
+    // Ignore storage failures; the tree still works for the current render.
+  }
+}
+
+const ROOT_WIKI_LINK_PAGES = new Set(["WIKI.md", "AGENTS.md", "IDEA.md", "index.md", "log.md"]);
+
+function splitWikiLinkTarget(target: string): { path: string; fragment: string | null } | null {
+  const trimmed = target.trim();
+  if (!trimmed || /^[a-z][a-z\d+.-]*:/i.test(trimmed) || trimmed.startsWith("//")) return null;
+
+  const hashIndex = trimmed.indexOf("#");
+  const rawPath = (hashIndex >= 0 ? trimmed.slice(0, hashIndex) : trimmed)
+    .trim()
+    .replace(/^\/+/, "");
+  if (
+    !rawPath ||
+    rawPath.includes("\\") ||
+    rawPath.split("/").some((segment) => !segment || segment === "." || segment === "..")
+  ) {
+    return null;
+  }
+
+  const fragment = hashIndex >= 0 ? trimmed.slice(hashIndex + 1).trim() || null : null;
+  return { path: rawPath, fragment };
+}
+
+function withMarkdownExtension(path: string): string {
+  return path.toLowerCase().endsWith(".md") ? path : `${path}.md`;
+}
+
+function normalizeWikiLinkPagePath(target: string): { path: string; fragment: string | null } | null {
+  const parsed = splitWikiLinkTarget(target);
+  if (!parsed) return null;
+
+  let path = withMarkdownExtension(parsed.path);
+  if (!path.startsWith("wiki/") && !path.startsWith("raw/") && !ROOT_WIKI_LINK_PAGES.has(path)) {
+    path = `wiki/${path}`;
+  }
+
+  return { path, fragment: parsed.fragment };
+}
+
+function buildWikiLinkHref(target: string, resolveHref: (to: string) => string): string | null {
+  const normalized = normalizeWikiLinkPagePath(target);
+  if (!normalized) return null;
+
+  const href = resolveHref(buildPageHref(normalized.path));
+  return normalized.fragment ? `${href}#${encodeURIComponent(normalized.fragment)}` : href;
+}
+
+function routeSegmentsFromTreePath(treePath: string): string[] {
+  return treePath.split("/").filter(Boolean);
+}
+
+function treePathFromRouteSegments(segments: string[]): string | null {
+  if (segments.length === 0) return null;
+  const [firstSegment, ...rest] = segments;
+  if (firstSegment === "templates") {
+    const templatePath = rest.join("/").trim();
+    return templatePath || null;
+  }
+  const routePath = segments.join("/").trim();
+  return routePath || null;
+}
+
+function firstSelectableTreePath(data: PagesData | null | undefined): string | null {
+  const firstPage = data?.pages.find((p) => p.path !== "wiki/index.md" && p.path !== "index.md") ?? data?.pages[0] ?? null;
+  if (firstPage) return firstPage.path;
+  const firstSource = data?.sources[0] ?? null;
+  if (firstSource) return firstSource.rawPath;
+  return TEMPLATE_PATHS[0] ?? null;
+}
+
+function contentPathFromTreePath(treePath: string | null): string | null {
+  return treePath;
+}
+
+function isEditableWikiPagePath(path: string): boolean {
+  return path === "WIKI.md"
+    || path === "AGENTS.md"
+    || path === "IDEA.md"
+    || path === "index.md"
+    || path === "log.md"
+    || path.startsWith("wiki/");
+}
+
+export function WikiPage({ context }: PluginPageProps) {
+  const { pathname, search } = useHostLocation();
+  const isMobile = useIsMobileLayout();
+  const section = useMemo(() => readSectionFromLocation(pathname, search), [pathname, search]);
+  const settingsSection = useMemo(() => readSettingsSectionFromLocation(pathname), [pathname]);
+  const activeSpaceSlug = useMemo(() => readActiveSpaceSlugFromLocation(pathname), [pathname]);
+  const settingsSpaceSlug = useMemo(() => readSettingsSpaceSlugFromLocation(pathname), [pathname]);
+  const overview = useOverview(context.companyId);
+  const [isDragActive, setIsDragActive] = useState(false);
+  const [stagedFiles, setStagedFiles] = useState<StagedIngestFile[]>([]);
+  const [isIngestModalOpen, setIsIngestModalOpen] = useState(false);
+
+  const resetDragState = useCallback(() => {
+    setIsDragActive(false);
+  }, []);
+
+  const stageFiles = useCallback((files: File[]) => {
+    if (files.length === 0) return;
+    const now = Date.now();
+    setStagedFiles((current) => [
+      ...current,
+      ...files.map((file, index) => ({
+        id: `${now}-${index}-${file.name}-${file.size}-${file.lastModified}`,
+        file,
+      })),
+    ]);
+    setIsIngestModalOpen(true);
+  }, []);
+
+  const handleDragEnter = useCallback((event: React.DragEvent<HTMLElement>) => {
+    if (!isFileDrag(event)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    setIsDragActive(true);
+  }, []);
+
+  const handleDragOver = useCallback((event: React.DragEvent<HTMLElement>) => {
+    if (!isFileDrag(event)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    event.dataTransfer.dropEffect = "copy";
+    setIsDragActive(true);
+  }, []);
+
+  const handleDragLeave = useCallback((event: React.DragEvent<HTMLElement>) => {
+    if (!isFileDrag(event)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    const relatedTarget = event.relatedTarget;
+    if (relatedTarget instanceof Node && event.currentTarget.contains(relatedTarget)) return;
+    resetDragState();
+  }, [resetDragState]);
+
+  const handleDrop = useCallback((event: React.DragEvent<HTMLElement>) => {
+    if (!isFileDrag(event)) return;
+    event.preventDefault();
+    event.stopPropagation();
+    resetDragState();
+    stageFiles(Array.from(event.dataTransfer.files ?? []));
+  }, [resetDragState, stageFiles]);
+
+  useEffect(() => {
+    if (!isDragActive) return;
+    const handleWindowDragLeave = (event: DragEvent) => {
+      const leftViewport =
+        event.clientX <= 0 ||
+        event.clientY <= 0 ||
+        event.clientX >= window.innerWidth ||
+        event.clientY >= window.innerHeight;
+      if (leftViewport) resetDragState();
+    };
+    const handleVisibilityChange = () => {
+      if (document.visibilityState !== "visible") resetDragState();
+    };
+    window.addEventListener("dragend", resetDragState);
+    window.addEventListener("drop", resetDragState);
+    window.addEventListener("blur", resetDragState);
+    window.addEventListener("dragleave", handleWindowDragLeave);
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    return () => {
+      window.removeEventListener("dragend", resetDragState);
+      window.removeEventListener("drop", resetDragState);
+      window.removeEventListener("blur", resetDragState);
+      window.removeEventListener("dragleave", handleWindowDragLeave);
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+    };
+  }, [isDragActive, resetDragState]);
+
+  if (!context.companyId) {
+    return <main style={{ ...shellStyle, height: isMobile ? "auto" : "100%", minHeight: isMobile ? "auto" : 600 }}>Choose a company to open the LLM Wiki.</main>;
+  }
+
+  return (
+    <main
+      style={{ ...shellStyle, position: "relative", height: isMobile ? "auto" : "100%", minHeight: isMobile ? "auto" : 600 }}
+      onDragEnter={handleDragEnter}
+      onDragOver={handleDragOver}
+      onDragLeave={handleDragLeave}
+      onDrop={handleDrop}
+    >
+      <style>{`@keyframes pcWikiPulse { 0%,100% { opacity:1 } 50% { opacity:0.45 } }`}</style>
+      <section style={{ flex: 1, minHeight: isMobile ? "auto" : 0, overflow: isMobile ? "visible" : "hidden", display: "flex" }}>
+        {overview.error ? (
+          <div style={{ padding: 24, flex: 1 }}>
+            <Callout tone="danger">LLM Wiki bridge error: {overview.error.message}</Callout>
+          </div>
+        ) : !overview.data ? (
+          <div style={{ padding: 24, flex: 1, color: tokens.muted, fontSize: 13 }}>Loading wiki…</div>
+        ) : !overview.data.folder.healthy ? (
+          <UnconfiguredFolder context={context} folder={overview.data.folder} refresh={overview.refresh} />
+        ) : section === "browse" ? (
+          <BrowseTab context={context} />
+        ) : section === "ingest" ? (
+          <IngestTab context={context} refreshOverview={overview.refresh} />
+        ) : section === "query" ? (
+          <QueryTab context={context} overview={overview.data} />
+        ) : section === "lint" ? (
+          <SettingsTab context={context} initialSection="lint" />
+        ) : section === "history" ? (
+          <HistoryTab context={context} overview={overview.data} />
+        ) : (
+          <SettingsTab context={context} initialSection={settingsSection} />
+        )}
+      </section>
+      {isDragActive ? <WikiPageDropOverlay onClose={resetDragState} /> : null}
+      {isIngestModalOpen ? (
+        <IngestFilesModal
+          companyId={context.companyId}
+          files={stagedFiles}
+          initialSpaceSlug={activeSpaceSlug}
+          onAddFiles={stageFiles}
+          onRemoveFile={(id) => setStagedFiles((current) => current.filter((item) => item.id !== id))}
+          onClose={() => {
+            setIsIngestModalOpen(false);
+            setStagedFiles([]);
+          }}
+          onIngested={() => {
+            overview.refresh();
+            if (typeof window !== "undefined") {
+              window.dispatchEvent(new CustomEvent("pc-wiki-ingest-queued"));
+            }
+          }}
+        />
+      ) : null}
+    </main>
+  );
+}
+
+type StagedIngestFile = {
+  id: string;
+  file: File;
+};
+
+function isFileDrag(event: React.DragEvent<HTMLElement>): boolean {
+  return Array.from(event.dataTransfer?.types ?? []).includes("Files");
+}
+
+function WikiPageDropOverlay({ onClose }: { onClose: () => void }) {
+  return (
+    <div
+      data-testid="llm-wiki-page-drop-overlay"
+      style={{
+        position: "fixed",
+        inset: 0,
+        zIndex: 1000,
+        pointerEvents: "auto",
+        display: "grid",
+        placeItems: "center",
+        padding: 24,
+        background: "color-mix(in oklab, var(--background, oklch(0.145 0 0)) 72%, transparent)",
+        backdropFilter: "blur(3px)",
+      }}
+    >
+      <button
+        type="button"
+        aria-label="Close ingest drop overlay"
+        title="Close"
+        onClick={(event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          onClose();
+        }}
+        style={{
+          position: "absolute",
+          top: 16,
+          right: 16,
+          width: 34,
+          height: 34,
+          borderRadius: 8,
+          border: `1px solid ${tokens.border}`,
+          background: "color-mix(in oklab, var(--card, oklch(0.205 0 0)) 90%, transparent)",
+          color: tokens.fg,
+          display: "inline-grid",
+          placeItems: "center",
+          cursor: "pointer",
+          boxShadow: "0 10px 30px rgba(0,0,0,0.28)",
+        }}
+      >
+        <XIcon size={16} />
+      </button>
+      <div style={{
+        width: "min(520px, 100%)",
+        borderRadius: 8,
+        border: `1.5px dashed ${tokens.pluginBorder}`,
+        background: "color-mix(in oklab, var(--card, oklch(0.205 0 0)) 92%, transparent)",
+        color: tokens.fg,
+        padding: "28px 24px",
+        textAlign: "center",
+        boxShadow: "0 20px 60px rgba(0,0,0,0.35)",
+      }}>
+        <div style={{ display: "inline-flex", alignItems: "center", justifyContent: "center", width: 44, height: 44, borderRadius: 8, background: tokens.pluginBg, color: tokens.pluginFg, marginBottom: 12 }}>
+          <DownloadCloudIcon size={24} />
+        </div>
+        <div style={{ fontSize: 18, fontWeight: 650, marginBottom: 6 }}>Drop to ingest into LLM Wiki</div>
+        <Tiny>Files will be staged for review before the wiki maintainer queues ingest operations.</Tiny>
+      </div>
+    </div>
+  );
+}
+
+function IngestFilesModal({
+  companyId,
+  files,
+  onAddFiles,
+  onRemoveFile,
+  onClose,
+  onIngested,
+  initialSpaceSlug,
+}: {
+  companyId: string;
+  files: StagedIngestFile[];
+  onAddFiles: (files: File[]) => void;
+  onRemoveFile: (id: string) => void;
+  onClose: () => void;
+  onIngested: () => void;
+  initialSpaceSlug: string;
+}) {
+  const ingest = usePluginAction("ingest-source");
+  const toast = usePluginToast();
+  const spacesQuery = useSpaces(companyId);
+  const spaces = useMemo(() => {
+    const list = spacesQuery.data?.spaces ?? [];
+    return [...list].sort(compareSpaces);
+  }, [spacesQuery.data]);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [errorMsg, setErrorMsg] = useState<string | null>(null);
+  const [targetSpaceSlug, setTargetSpaceSlug] = useState(initialSpaceSlug || DEFAULT_SPACE_SLUG);
+  const [pickerOpen, setPickerOpen] = useState(false);
+  const [createOpen, setCreateOpen] = useState(false);
+  const targetSpace = useMemo(() => spaces.find((s) => s.slug === targetSpaceSlug) ?? null, [spaces, targetSpaceSlug]);
+
+  const requestClose = useCallback(() => {
+    if (!busy) onClose();
+  }, [busy, onClose]);
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape" || busy) return;
+      event.preventDefault();
+      onClose();
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [busy, onClose]);
+
+  async function confirm() {
+    if (busy || files.length === 0) return;
+    setBusy(true);
+    setErrorMsg(null);
+    try {
+      for (const item of files) {
+        const contents = await item.file.text();
+        const result = await ingest({
+          companyId,
+          spaceSlug: targetSpaceSlug,
+          sourceType: "file",
+          title: item.file.name,
+          url: null,
+          contents,
+          metadata: {
+            fileName: item.file.name,
+            fileSize: item.file.size,
+            fileType: item.file.type || null,
+            lastModified: item.file.lastModified,
+          },
+        });
+        await uploadIssueAttachmentFile({
+          companyId,
+          issueId: readIngestOperationIssueId(result),
+          file: item.file,
+        });
+      }
+      const count = files.length;
+      const spaceLabel = targetSpace?.displayName ?? targetSpaceSlug;
+      toast({ tone: "success", title: `Files queued for ingest into ${spaceLabel}`, body: `${count} ${count === 1 ? "file" : "files"} captured into raw sources and attached to ingest tasks.` });
+      onIngested();
+      onClose();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setErrorMsg(message);
+      toast({ tone: "error", title: "File ingest failed", body: message });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="llm-wiki-ingest-modal-title"
+      data-testid="llm-wiki-ingest-modal"
+      onMouseDown={(event) => {
+        if (event.currentTarget === event.target) requestClose();
+      }}
+      style={{
+        position: "fixed",
+        inset: 0,
+        zIndex: 1010,
+        display: "grid",
+        placeItems: "center",
+        padding: 18,
+        background: "rgba(0,0,0,0.52)",
+      }}
+    >
+      <div style={{
+        width: "min(680px, 100%)",
+        maxHeight: "min(720px, calc(100vh - 36px))",
+        overflow: "auto",
+        background: tokens.card,
+        color: tokens.fg,
+        border: `1px solid ${tokens.border}`,
+        borderRadius: 8,
+        boxShadow: "0 24px 80px rgba(0,0,0,0.45)",
+      }}>
+        <div style={{ padding: "16px 18px", borderBottom: `1px solid ${tokens.border}`, display: "flex", gap: 12, alignItems: "flex-start" }}>
+          <div style={{ width: 34, height: 34, borderRadius: 8, background: tokens.pluginBg, color: tokens.pluginFg, display: "grid", placeItems: "center", flexShrink: 0 }}>
+            <DownloadCloudIcon size={18} />
+          </div>
+          <div style={{ flex: 1, minWidth: 0 }}>
+            <h2 id="llm-wiki-ingest-modal-title" style={{ margin: 0, fontSize: 16, fontWeight: 650 }}>Ingest files into {targetSpace?.displayName ?? targetSpaceSlug}</h2>
+            <Tiny style={{ marginTop: 4 }}>
+              Review the staged files, switch the destination space if needed, then queue them as LLM
+              Wiki ingest operations. This is manual file ingest - Paperclip-derived distillation always
+              routes to the default space regardless of the destination picked here.
+            </Tiny>
+          </div>
+          <Button size="sm" variant="ghost" onClick={requestClose} disabled={busy} title="Close ingest modal">Close</Button>
+        </div>
+        <div style={{ padding: 18, display: "grid", gap: 14 }}>
+          <SpacePicker
+            spaces={spaces}
+            activeSpaceSlug={targetSpaceSlug}
+            loading={spacesQuery.loading}
+            error={spacesQuery.error?.message ?? null}
+            isOpen={pickerOpen}
+            onToggle={() => setPickerOpen((v) => !v)}
+            onClose={() => setPickerOpen(false)}
+            onSelect={(slug) => {
+              setPickerOpen(false);
+              setTargetSpaceSlug(slug);
+            }}
+            onCreate={() => {
+              setPickerOpen(false);
+              setCreateOpen(true);
+            }}
+          />
+          <div style={{ display: "flex", gap: 8, flexWrap: "wrap", alignItems: "center" }}>
+            <Badge tone="running">{files.length} staged</Badge>
+            <Button size="sm" onClick={() => inputRef.current?.click()} disabled={busy}>Add files</Button>
+            <input
+              ref={inputRef}
+              type="file"
+              multiple
+              style={{ display: "none" }}
+              onChange={(event) => {
+                onAddFiles(Array.from(event.currentTarget.files ?? []));
+                event.currentTarget.value = "";
+              }}
+            />
+          </div>
+          <div style={{ border: `1px solid ${tokens.border}`, borderRadius: 8, overflow: "hidden" }}>
+            {files.length === 0 ? (
+              <div style={{ padding: 16 }}><Tiny>No files staged.</Tiny></div>
+            ) : files.map((item) => (
+              <div key={item.id} style={{ display: "flex", gap: 10, alignItems: "center", padding: "10px 12px", borderBottom: `1px solid ${tokens.border}`, minWidth: 0 }}>
+                <div style={{ flex: "1 1 auto", minWidth: 0 }}>
+                  <strong style={{ display: "block", fontSize: 13, overflowWrap: "anywhere" }}>{item.file.name}</strong>
+                  <Tiny>{formatFileSize(item.file.size)}{item.file.type ? ` · ${item.file.type}` : ""}</Tiny>
+                </div>
+                <Button size="sm" variant="ghost" onClick={() => onRemoveFile(item.id)} disabled={busy}>Remove</Button>
+              </div>
+            ))}
+          </div>
+          {errorMsg ? <Callout tone="danger">{errorMsg}</Callout> : null}
+          <Callout>
+            Confirming captures each file into <Mono>{targetSpaceSlug}/raw/</Mono>, attaches the original file to the ingest task, and initiates a task for the Wiki Maintainer to process.
+          </Callout>
+          <div style={{ display: "flex", gap: 8, justifyContent: "flex-end", flexWrap: "wrap" }}>
+            <Button variant="ghost" onClick={requestClose} disabled={busy}>Cancel</Button>
+            <Button variant="primary" onClick={confirm} disabled={files.length === 0} loading={busy}>Capture & ingest into {targetSpace?.displayName ?? targetSpaceSlug}</Button>
+          </div>
+        </div>
+      </div>
+      {createOpen ? (
+        <CreateSpaceModal
+          companyId={companyId}
+          existingSlugs={new Set(spaces.map((s) => s.slug))}
+          onClose={() => setCreateOpen(false)}
+          onCreated={(space) => {
+            setCreateOpen(false);
+            spacesQuery.refresh();
+            setTargetSpaceSlug(space.slug);
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function formatFileSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "Unknown size";
+  if (bytes < 1024) return `${bytes} B`;
+  const kib = bytes / 1024;
+  if (kib < 1024) return `${kib.toFixed(kib >= 10 ? 0 : 1)} KB`;
+  const mib = kib / 1024;
+  return `${mib.toFixed(mib >= 10 ? 0 : 1)} MB`;
+}
+
+// ---------------------------------------------------------------------------
+// Wiki route sidebar — replaces the company sidebar while the user is on a
+// `/wiki` route. Mirrors the shell of the host's CompanySettingsSidebar so
+// users see a familiar takeover.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Create-space modal — opened from the sidebar `+` icon and also reachable
+// from the edit-space settings sub-nav. Disables the "Cloud" type and the
+// "Existing absolute path" folder source per the PAP-3640 security review.
+// ---------------------------------------------------------------------------
+
+function slugify(input: string): string {
+  return input
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+}
+
+const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
+
+function CreateSpaceModal({
+  companyId,
+  existingSlugs,
+  onClose,
+  onCreated,
+}: {
+  companyId: string;
+  existingSlugs: ReadonlySet<string>;
+  onClose: () => void;
+  onCreated: (space: WikiSpace) => void;
+}) {
+  const create = usePluginAction("create-space");
+  const toast = usePluginToast();
+  const [displayName, setDisplayName] = useState("");
+  const [slug, setSlug] = useState("");
+  const [slugDirty, setSlugDirty] = useState(false);
+  const [folderMode, setFolderMode] = useState<"managed_subfolder" | "existing_local_folder">("managed_subfolder");
+  const [accessScope, setAccessScope] = useState<"shared" | "personal" | "team">("shared");
+  const [busy, setBusy] = useState(false);
+  const [errorMsg, setErrorMsg] = useState<string | null>(null);
+  const isMobile = useIsMobileLayout();
+
+  useEffect(() => {
+    const handler = (event: KeyboardEvent) => { if (event.key === "Escape" && !busy) onClose(); };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [busy, onClose]);
+
+  const effectiveSlug = slug.trim() || (slugDirty ? "" : slugify(displayName));
+
+  const slugError = (() => {
+    if (!effectiveSlug) return null;
+    if (effectiveSlug === DEFAULT_SPACE_SLUG) return "Slug 'default' is reserved.";
+    if (!SLUG_PATTERN.test(effectiveSlug)) return "Use 2-40 chars: lowercase letters, numbers, hyphens.";
+    if (existingSlugs.has(effectiveSlug)) return "A space with this slug already exists.";
+    return null;
+  })();
+
+  const canSubmit = displayName.trim().length > 0 && effectiveSlug.length > 0 && !slugError && !busy;
+
+  async function submit() {
+    if (!canSubmit) return;
+    setBusy(true);
+    setErrorMsg(null);
+    try {
+      const result = await create({
+        companyId,
+        slug: effectiveSlug,
+        displayName: displayName.trim(),
+        folderMode,
+        accessScope,
+      }) as { status: "created"; space: WikiSpace };
+      toast({ tone: "success", title: "Space created", body: `${result.space.displayName} is ready for ingest.` });
+      onCreated(result.space);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      setErrorMsg(msg);
+      toast({ tone: "error", title: "Could not create space", body: msg });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const previewName = displayName.trim() || "your-space";
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="create-space-modal-title"
+      style={{
+        position: "fixed",
+        inset: 0,
+        zIndex: 200,
+        display: "grid",
+        placeItems: isMobile ? "end" : "center",
+        padding: isMobile ? 0 : 18,
+        background: "rgba(0,0,0,0.52)",
+      }}
+      onClick={(event) => {
+        if (event.target === event.currentTarget && !busy) onClose();
+      }}
+    >
+      <div
+        style={{
+          width: isMobile ? "100%" : "min(560px, 100%)",
+          maxHeight: isMobile ? "92vh" : "min(760px, calc(100vh - 36px))",
+          overflow: "auto",
+          background: tokens.card,
+          color: tokens.fg,
+          border: `1px solid ${tokens.border}`,
+          borderRadius: isMobile ? "12px 12px 0 0" : 8,
+          boxShadow: "0 24px 80px rgba(0,0,0,0.45)",
+          fontFamily: fontStack,
+        }}
+      >
+        <div style={{ padding: "16px 20px", borderBottom: `1px solid ${tokens.border}`, display: "flex", alignItems: "flex-start", gap: 12 }}>
+          <div style={{ width: 34, height: 34, borderRadius: 8, background: tokens.pluginBg, color: tokens.pluginFg, display: "grid", placeItems: "center", flexShrink: 0 }}>
+            <FolderIcon size={18} />
+          </div>
+          <div style={{ flex: 1, minWidth: 0 }}>
+            <h2 id="create-space-modal-title" style={{ margin: 0, fontSize: 17, fontWeight: 650 }}>Create a shared space</h2>
+            <Tiny style={{ marginTop: 4 }}>
+              Spaces partition wiki pages, sources, and manual ingest into separate slug-prefixed folders
+              under the wiki root. Paperclip distillation and event capture always write into the
+              default space and skip new spaces created here - per-space Paperclip routing is a later
+              phase.
+            </Tiny>
+          </div>
+          <Button size="sm" variant="ghost" onClick={onClose} disabled={busy} title="Close">Close</Button>
+        </div>
+        <div style={{ padding: 20, display: "grid", gap: 16 }}>
+          <FormField label="Display name">
+            <TextInput
+              value={displayName}
+              autoFocus
+              onChange={(event) => {
+                setDisplayName(event.target.value);
+                if (!slugDirty) setSlug("");
+              }}
+              placeholder="Team research"
+              maxLength={120}
+            />
+          </FormField>
+          <FormField
+            label="Slug"
+            help={slugError ?? `Stored as the URL segment and the on-disk folder. Defaults to ${slugify(displayName) || "auto-derived from display name"}.`}
+            tone={slugError ? "danger" : "muted"}
+          >
+            <TextInput
+              value={slug || (slugDirty ? "" : slugify(displayName))}
+              onChange={(event) => {
+                setSlugDirty(true);
+                setSlug(event.target.value.toLowerCase().replace(/[^a-z0-9-]/g, ""));
+              }}
+              placeholder="team-research"
+              style={{ fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace" }}
+            />
+          </FormField>
+          <FormField label="Type">
+            <div style={{ display: "flex", gap: 6, flexWrap: "wrap" }}>
+              <SegmentedOption selected label="Folder" onClick={() => undefined} />
+              <SegmentedOption disabled label="Cloud" suffix="Coming soon" onClick={() => undefined} />
+            </div>
+          </FormField>
+          <FormField label="Folder source" help="New managed folders create a slug-scoped subfolder under your wiki root. Existing folders must already live under the same wiki root.">
+            <div style={{ display: "grid", gap: 8 }}>
+              <FolderModeRow
+                checked={folderMode === "managed_subfolder"}
+                onSelect={() => setFolderMode("managed_subfolder")}
+                label="New managed folder"
+                help={`Creates spaces/${previewName.replace(/\s+/g, "-").toLowerCase()}/ under the configured wiki root with the standard skeleton.`}
+              />
+              <FolderModeRow
+                checked={folderMode === "existing_local_folder"}
+                onSelect={() => setFolderMode("existing_local_folder")}
+                label="Existing folder under wiki root"
+                help="Re-use a sub-folder you've already created inside the wiki root. The folder path is stored in the space settings."
+              />
+              <FolderModeRow
+                disabled
+                checked={false}
+                onSelect={() => undefined}
+                label="Existing absolute path"
+                help="Pending host capability — security review (PAP-3640) gates this until host-managed dynamic local-folder bindings ship."
+                suffix="Disabled"
+              />
+            </div>
+          </FormField>
+          <FormField label="Access scope" help="Access scope is metadata only. It does not currently enforce who can read or write the space, and it does not change which Paperclip sources reach the space.">
+            <div style={{ display: "grid", gridTemplateColumns: isMobile ? "1fr" : "1fr 1fr 1fr", gap: 8 }}>
+              <ScopeTile
+                selected={accessScope === "shared"}
+                onSelect={() => setAccessScope("shared")}
+                label="Shared"
+                help="Visible to everyone in this company."
+              />
+              <ScopeTile
+                selected={accessScope === "personal"}
+                onSelect={() => setAccessScope("personal")}
+                label="Personal"
+                help="Future scope — stored only."
+                tag="Future"
+              />
+              <ScopeTile
+                selected={accessScope === "team"}
+                onSelect={() => setAccessScope("team")}
+                label="Team"
+                help="Future scope — stored only."
+                tag="Future"
+              />
+            </div>
+          </FormField>
+          {errorMsg ? <Callout tone="danger">{errorMsg}</Callout> : null}
+        </div>
+        <div style={{
+          padding: "12px 20px",
+          borderTop: `1px solid ${tokens.border}`,
+          display: "flex",
+          gap: 8,
+          justifyContent: isMobile ? "stretch" : "flex-end",
+          flexWrap: "wrap",
+          position: isMobile ? "sticky" : "static",
+          bottom: 0,
+          background: tokens.card,
+        }}>
+          <Button variant="ghost" onClick={onClose} disabled={busy} style={{ flex: isMobile ? 1 : undefined }}>Cancel</Button>
+          <Button variant="primary" onClick={submit} disabled={!canSubmit} loading={busy} style={{ flex: isMobile ? 1 : undefined }}>Create space</Button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function FormField({ label, help, tone = "muted", children }: { label: ReactNode; help?: ReactNode; tone?: "muted" | "danger"; children: ReactNode }) {
+  return (
+    <div style={{ display: "grid", gap: 6 }}>
+      <label style={{ fontSize: 12, fontWeight: 600, color: tokens.fg }}>{label}</label>
+      {children}
+      {help ? (
+        <span style={{ fontSize: 11, color: tone === "danger" ? "oklch(0.78 0.18 25)" : tokens.muted, lineHeight: 1.4 }}>{help}</span>
+      ) : null}
+    </div>
+  );
+}
+
+function SegmentedOption({ label, selected, disabled, suffix, onClick }: { label: string; selected?: boolean; disabled?: boolean; suffix?: string; onClick: () => void }) {
+  return (
+    <button
+      type="button"
+      onClick={disabled ? undefined : onClick}
+      disabled={disabled}
+      aria-pressed={selected}
+      aria-disabled={disabled}
+      style={{
+        padding: "8px 14px",
+        borderRadius: 6,
+        border: `1px solid ${selected ? tokens.border : tokens.border}`,
+        background: selected ? tokens.accent : "transparent",
+        color: disabled ? tokens.muted : tokens.fg,
+        fontSize: 13,
+        fontWeight: 600,
+        cursor: disabled ? "not-allowed" : "pointer",
+        opacity: disabled ? 0.6 : 1,
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 6,
+        fontFamily: fontStack,
+      }}
+    >
+      <span>{label}</span>
+      {suffix ? (
+        <span style={{
+          fontSize: 10,
+          fontWeight: 500,
+          padding: "1px 6px",
+          borderRadius: 3,
+          border: `1px dashed ${tokens.border}`,
+          color: tokens.muted,
+        }}>{suffix}</span>
+      ) : null}
+    </button>
+  );
+}
+
+function FolderModeRow({ checked, onSelect, label, help, disabled, suffix }: { checked: boolean; onSelect: () => void; label: string; help: string; disabled?: boolean; suffix?: string }) {
+  return (
+    <button
+      type="button"
+      onClick={disabled ? undefined : onSelect}
+      disabled={disabled}
+      style={{
+        display: "flex",
+        alignItems: "flex-start",
+        gap: 10,
+        padding: "10px 12px",
+        borderRadius: 8,
+        border: `1px solid ${checked ? tokens.fg : tokens.border}`,
+        background: "transparent",
+        color: tokens.fg,
+        textAlign: "left",
+        cursor: disabled ? "not-allowed" : "pointer",
+        opacity: disabled ? 0.55 : 1,
+        fontFamily: fontStack,
+      }}
+    >
+      <span
+        aria-hidden="true"
+        style={{
+          width: 14,
+          height: 14,
+          borderRadius: 7,
+          border: `2px solid ${checked ? tokens.fg : tokens.muted}`,
+          flexShrink: 0,
+          marginTop: 2,
+          background: checked ? tokens.fg : "transparent",
+        }}
+      />
+      <div style={{ display: "grid", gap: 2, flex: 1, minWidth: 0 }}>
+        <div style={{ display: "flex", alignItems: "center", gap: 6 }}>
+          <span style={{ fontSize: 13, fontWeight: 600 }}>{label}</span>
+          {suffix ? <Badge tone="default" style={{ fontSize: 10 }}>{suffix}</Badge> : null}
+        </div>
+        <span style={{ fontSize: 11, color: tokens.muted, lineHeight: 1.4 }}>{help}</span>
+      </div>
+    </button>
+  );
+}
+
+function ScopeTile({ selected, onSelect, label, help, tag }: { selected: boolean; onSelect: () => void; label: string; help: string; tag?: string }) {
+  return (
+    <button
+      type="button"
+      onClick={onSelect}
+      style={{
+        padding: "10px 12px",
+        borderRadius: 8,
+        border: `1px solid ${selected ? tokens.fg : tokens.border}`,
+        background: selected ? tokens.accent : "transparent",
+        color: tokens.fg,
+        textAlign: "left",
+        display: "grid",
+        gap: 4,
+        cursor: "pointer",
+        fontFamily: fontStack,
+      }}
+    >
+      <div style={{ display: "flex", alignItems: "center", gap: 6 }}>
+        <span style={{ fontSize: 13, fontWeight: 600 }}>{label}</span>
+        {tag ? <Badge tone="default" style={{ fontSize: 10 }}>{tag}</Badge> : null}
+      </div>
+      <span style={{ fontSize: 11, color: tokens.muted, lineHeight: 1.4 }}>{help}</span>
+    </button>
+  );
+}
+
+function compareSpaces(a: WikiSpace, b: WikiSpace): number {
+  if (a.slug === DEFAULT_SPACE_SLUG && b.slug !== DEFAULT_SPACE_SLUG) return -1;
+  if (b.slug === DEFAULT_SPACE_SLUG && a.slug !== DEFAULT_SPACE_SLUG) return 1;
+  return a.displayName.localeCompare(b.displayName, undefined, { sensitivity: "base" });
+}
+
+function activeWikiSpaces(spaces: WikiSpace[]): WikiSpace[] {
+  return spaces.filter((space) => space.status !== "archived");
+}
+
+function spaceTreeKey(spaceSlug: string, path: string): string {
+  return `${spaceSlug}::${path}`;
+}
+
+function SpacePageContentWarmup({ companyId, path, spaceSlug }: { companyId: string | null; path: string; spaceSlug: string }) {
+  usePageContent(companyId, path, spaceSlug);
+  return null;
+}
+
+function SpacePagesWarmup({ companyId, spaceSlug }: { companyId: string | null; spaceSlug: string }) {
+  const pages = usePages(companyId, { includeRaw: true, spaceSlug });
+  const selectedTreePath = firstSelectableTreePath(pages.data);
+  const selected = contentPathFromTreePath(selectedTreePath);
+  return selected ? <SpacePageContentWarmup companyId={companyId} path={selected} spaceSlug={spaceSlug} /> : null;
+}
+
+export function WikiRouteSidebar({ context }: PluginRouteSidebarProps) {
+  const hostNavigation = useHostNavigation();
+  const { pathname, search, state } = useHostLocation();
+  const activeSection = useMemo(() => readSectionFromLocation(pathname, search), [pathname, search]);
+  const activeSpaceSlug = useMemo(() => readActiveSpaceSlugFromLocation(pathname), [pathname]);
+  const companyName = context.companyPrefix ?? "Company";
+  const spacesQuery = useSpaces(context.companyId);
+  const spaces = useMemo(() => {
+    const list = spacesQuery.data?.spaces ?? [];
+    if (list.length === 0) return list;
+    return activeWikiSpaces(list).sort(compareSpaces);
+  }, [spacesQuery.data]);
+  const pages = usePages(context.companyId, { includeRaw: true, spaceSlug: activeSpaceSlug });
+  const activeSpaceNodes = useMemo(
+    () => buildBrowseTree(pages.data?.pages ?? [], pages.data?.sources ?? []),
+    [pages.data],
+  );
+  const warmupSpaces = useMemo(() => {
+    const active = spaces.find((space) => space.slug === activeSpaceSlug);
+    const rest = spaces.filter((space) => space.slug !== activeSpaceSlug);
+    return (active ? [active, ...rest] : rest).slice(0, WIKI_SPACE_PREFETCH_LIMIT);
+  }, [spaces, activeSpaceSlug]);
+  const storageKey = useMemo(() => routeSidebarExpandedStorageKey(context.companyId), [context.companyId]);
+  const [expandedRaw, setExpandedRaw] = useState<Set<string>>(() => readRouteSidebarExpandedPaths(storageKey));
+  const [selectedTreePath, setSelectedTreePath] = useState<string | null>(null);
+  const [spaceCollapse, setSpaceCollapse] = useState<Set<string>>(new Set());
+  const [createOpen, setCreateOpen] = useState(false);
+  const [openMenuFor, setOpenMenuFor] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (activeSection !== "browse") return;
+    const sidebarSelectedPath = readSidebarSelectedPathFromNavigationState(state);
+    if (sidebarSelectedPath === null) return;
+    setSelectedTreePath(sidebarSelectedPath);
+  }, [activeSection, state]);
+
+  useEffect(() => {
+    setExpandedRaw(readRouteSidebarExpandedPaths(storageKey));
+  }, [storageKey]);
+
+  useEffect(() => {
+    writeRouteSidebarExpandedPaths(storageKey, expandedRaw);
+  }, [expandedRaw, storageKey]);
+
+  useEffect(() => {
+    const ancestors = expandedAncestors(selectedTreePath);
+    if (ancestors.length === 0) return;
+    const slug = activeSpaceSlug;
+    setExpandedRaw((current) => {
+      const next = new Set(current);
+      let changed = false;
+      for (const ancestor of ancestors) {
+        const key = spaceTreeKey(slug, ancestor);
+        if (next.has(key)) continue;
+        next.add(key);
+        changed = true;
+      }
+      return changed ? next : current;
+    });
+  }, [selectedTreePath, activeSpaceSlug]);
+
+  // Project the per-space-prefixed expanded paths down to the active space's
+  // bare paths so FileTree (which is space-agnostic) can read them directly.
+  // Legacy entries written before this change have no `slug::` prefix and are
+  // treated as belonging to the default space.
+  const expandedForActiveSpace = useMemo(() => {
+    const next = new Set<string>();
+    const prefix = `${activeSpaceSlug}::`;
+    for (const entry of expandedRaw) {
+      if (entry.startsWith(prefix)) {
+        next.add(entry.slice(prefix.length));
+      } else if (!entry.includes("::") && activeSpaceSlug === DEFAULT_SPACE_SLUG) {
+        next.add(entry);
+      }
+    }
+    return next;
+  }, [expandedRaw, activeSpaceSlug]);
+
+  const handleToggleDir = (dirPath: string) => {
+    const key = spaceTreeKey(activeSpaceSlug, dirPath);
+    setExpandedRaw((current) => {
+      const next = new Set(current);
+      // For the default space, legacy un-prefixed entries also need to be
+      // removed so that the projection (which falls through legacy keys to
+      // default) does not leave a "ghost" expansion after a collapse click.
+      if (next.has(key)) {
+        next.delete(key);
+        if (activeSpaceSlug === DEFAULT_SPACE_SLUG) next.delete(dirPath);
+      } else if (activeSpaceSlug === DEFAULT_SPACE_SLUG && next.has(dirPath)) {
+        next.delete(dirPath);
+      } else {
+        next.add(key);
+      }
+      return next;
+    });
+  };
+
+  const toggleSpaceCollapse = (slug: string) => {
+    setSpaceCollapse((current) => {
+      const next = new Set(current);
+      if (next.has(slug)) next.delete(slug);
+      else next.add(slug);
+      return next;
+    });
+  };
+
+  const renderToolLink = ({ key, label, Icon }: (typeof SECTIONS)[number]) => {
+    const isLegacyLintSettingsActive = key === "settings" && activeSection === "lint";
+    const isActive = key === activeSection || isLegacyLintSettingsActive;
+    return (
+      <a
+        key={key}
+        {...hostNavigation.linkProps(buildSectionHref(key, activeSpaceSlug))}
+        aria-current={isActive ? "page" : undefined}
+        className={[
+          "flex items-center gap-2.5 rounded-md px-2 py-1.5 text-[13px] font-medium transition-colors",
+          isActive && !isLegacyLintSettingsActive
+            ? "bg-accent text-foreground"
+            : isActive
+              ? "text-foreground"
+            : "text-foreground/80 hover:bg-accent/50 hover:text-foreground",
+        ].join(" ")}
+        style={{ textDecoration: "none" }}
+      >
+        <span aria-hidden="true" className="shrink-0">
+          <Icon />
+        </span>
+        <span className="flex-1 truncate">{label}</span>
+      </a>
+    );
+  };
+
+  return (
+    <aside className="w-full h-full min-h-0 border-r border-border bg-background flex flex-col">
+      {warmupSpaces.map((space) => (
+        <SpacePagesWarmup key={space.slug} companyId={context.companyId} spaceSlug={space.slug} />
+      ))}
+      <div className="flex flex-col gap-1 px-3 py-3 shrink-0">
+        <a
+          {...hostNavigation.linkProps("/dashboard")}
+          className="flex items-center gap-1.5 rounded-md px-2 py-1 text-xs text-muted-foreground transition-colors hover:bg-accent/50 hover:text-foreground"
+          style={{ textDecoration: "none" }}
+        >
+          <span aria-hidden="true" className="shrink-0">
+            <ChevronLeftIcon size={14} />
+          </span>
+          <span className="truncate">{companyName}</span>
+        </a>
+      </div>
+      <div className="flex-1 min-h-0 overflow-y-auto border-t border-border px-3 py-3">
+        <nav aria-label="Wiki primary" className="mb-3">
+          <div className="flex flex-col gap-0.5">
+            {TOP_TOOL_SECTIONS.map(renderToolLink)}
+          </div>
+        </nav>
+        <div className="mb-1 flex items-center gap-1 px-2 text-[11px] font-semibold uppercase tracking-normal text-muted-foreground" style={{ height: 24 }}>
+          <span
+            className="flex-1 truncate"
+            title="Destination spaces. Browsing and manual ingest happen in the active space; Paperclip distillation always writes into the default space in Phase 1."
+          >
+            Shared Spaces
+          </span>
+          <button
+            type="button"
+            aria-label="Create space"
+            title="Create space"
+            onClick={() => setCreateOpen(true)}
+            style={{
+              width: 22,
+              height: 22,
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center",
+              border: "none",
+              background: "transparent",
+              color: tokens.muted,
+              borderRadius: 4,
+              cursor: "pointer",
+            }}
+          >
+            <PlusIcon size={14} />
+          </button>
+        </div>
+        {spacesQuery.error ? (
+          <div style={{ padding: "6px 8px", fontSize: 11, color: tokens.statusBlocked }}>
+            Failed to load spaces: {spacesQuery.error.message}
+          </div>
+        ) : null}
+        {spaces.length === 0 && spacesQuery.loading ? (
+          <Tiny style={{ padding: "6px 8px" }}>Loading spaces…</Tiny>
+        ) : null}
+        <div style={{ display: "flex", flexDirection: "column" }}>
+          {spaces.map((space) => {
+            const isActiveSpace = space.slug === activeSpaceSlug;
+            const collapsed = spaceCollapse.has(space.slug);
+            const showTree = isActiveSpace && !collapsed;
+            return (
+              <div key={space.slug} style={{ position: "relative" }}>
+                <SpaceRow
+                  space={space}
+                  active={isActiveSpace}
+                  expanded={showTree}
+                  hostNavigation={hostNavigation}
+                  onToggleCollapse={() => {
+                    if (!isActiveSpace) {
+                      setSpaceCollapse((current) => {
+                        if (!current.has(space.slug)) return current;
+                        const next = new Set(current);
+                        next.delete(space.slug);
+                        return next;
+                      });
+                      hostNavigation.navigate(buildSectionHref("browse", space.slug));
+                    } else {
+                      toggleSpaceCollapse(space.slug);
+                    }
+                  }}
+                  onMenuToggle={() => setOpenMenuFor((curr) => curr === space.slug ? null : space.slug)}
+                  menuOpen={openMenuFor === space.slug}
+                  onMenuClose={() => setOpenMenuFor(null)}
+                  onArchived={(slug) => {
+                    spacesQuery.refresh();
+                    setOpenMenuFor(null);
+                    setSpaceCollapse((current) => {
+                      if (!current.has(slug)) return current;
+                      const next = new Set(current);
+                      next.delete(slug);
+                      return next;
+                    });
+                    if (activeSpaceSlug === slug) {
+                      hostNavigation.navigate(buildSectionHref("browse", DEFAULT_SPACE_SLUG));
+                    }
+                  }}
+                  activeSpaceSlug={activeSpaceSlug}
+                  companyId={context.companyId}
+                />
+                {showTree ? (
+                  <div style={{ paddingLeft: 18, marginTop: 2, marginBottom: 6 }}>
+                    <FileTree
+                      nodes={activeSpaceNodes}
+                      selectedFile={selectedTreePath}
+                      expandedPaths={expandedForActiveSpace}
+                      onSelectFile={(path) => {
+                        setSelectedTreePath(path);
+                        hostNavigation.navigate(buildPageHref(path, space.slug), { state: wikiSidebarNavigationState(path) });
+                      }}
+                      onToggleDir={handleToggleDir}
+                      wrapLabels={false}
+                      loading={pages.loading}
+                      error={pages.error ? { message: pages.error.message } : null}
+                      empty={{ title: "No pages yet", description: "Add content to populate this space." }}
+                      ariaLabel={`Wiki pages in ${space.displayName}`}
+                    />
+                  </div>
+                ) : null}
+              </div>
+            );
+          })}
+        </div>
+      </div>
+      <nav
+        aria-label="Wiki secondary"
+        className="shrink-0 border-t border-border px-3 py-3"
+      >
+        <div className="flex flex-col gap-0.5">
+          {BOTTOM_TOOL_SECTIONS.map(renderToolLink)}
+        </div>
+      </nav>
+      {createOpen && context.companyId ? (
+        <CreateSpaceModal
+          companyId={context.companyId}
+          existingSlugs={new Set(spaces.map((s) => s.slug))}
+          onClose={() => setCreateOpen(false)}
+          onCreated={(space) => {
+            setCreateOpen(false);
+            spacesQuery.refresh();
+            hostNavigation.navigate(buildSectionHref("browse", space.slug));
+          }}
+        />
+      ) : null}
+    </aside>
+  );
+}
+
+function SpaceRow({
+  space,
+  active,
+  expanded,
+  hostNavigation,
+  onToggleCollapse,
+  onMenuToggle,
+  menuOpen,
+  onMenuClose,
+  onArchived,
+  activeSpaceSlug,
+  companyId,
+}: {
+  space: WikiSpace;
+  active: boolean;
+  expanded: boolean;
+  hostNavigation: ReturnType<typeof useHostNavigation>;
+  onToggleCollapse: () => void;
+  onMenuToggle: () => void;
+  menuOpen: boolean;
+  onMenuClose: () => void;
+  onArchived: (slug: string) => void;
+  activeSpaceSlug: string;
+  companyId: string | null;
+}) {
+  const [hover, setHover] = useState(false);
+  const isDefault = space.slug === DEFAULT_SPACE_SLUG;
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      aria-expanded={expanded}
+      aria-label={`${expanded ? "Collapse" : active ? "Expand" : "Open"} ${space.displayName} space`}
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => setHover(false)}
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: 6,
+        padding: "6px 8px",
+        borderRadius: 6,
+        cursor: "pointer",
+        background: active ? tokens.accent : "transparent",
+        position: "relative",
+      }}
+      onClick={onToggleCollapse}
+      onKeyDown={(event) => {
+        if (event.target !== event.currentTarget) return;
+        if (event.key !== "Enter" && event.key !== " ") return;
+        event.preventDefault();
+        onToggleCollapse();
+      }}
+    >
+      <span aria-hidden="true" style={{ color: tokens.muted, display: "flex", flexShrink: 0, transform: expanded ? "rotate(0)" : "rotate(0)" }}>
+        {expanded ? <ChevronDownIcon size={14} /> : <ChevronRightIcon size={14} />}
+      </span>
+      <span aria-hidden="true" style={{ color: tokens.muted, display: "flex", flexShrink: 0 }}>
+        <FolderIcon size={16} />
+      </span>
+      <span style={{ flex: 1, fontSize: 13, fontWeight: 600, color: tokens.fg, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
+        {space.displayName}
+      </span>
+      {space.accessScope === "personal" ? (
+        <Badge tone="default" style={{ height: 18, padding: "0 6px", fontSize: 10 }}>personal</Badge>
+      ) : space.accessScope === "team" ? (
+        <Badge tone="default" style={{ height: 18, padding: "0 6px", fontSize: 10 }}>team</Badge>
+      ) : null}
+      <button
+        type="button"
+        aria-label={`${space.displayName} space menu`}
+        title="Space menu"
+        onClick={(event) => {
+          event.stopPropagation();
+          onMenuToggle();
+        }}
+        style={{
+          opacity: hover || menuOpen ? 1 : 0,
+          transition: "opacity 80ms ease",
+          width: 22,
+          height: 22,
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          border: "none",
+          background: "transparent",
+          color: tokens.fg,
+          borderRadius: 4,
+          cursor: "pointer",
+        }}
+      >
+        <MoreHorizontalIcon size={14} />
+      </button>
+      {menuOpen ? (
+        <SpaceRowMenu
+          space={space}
+          isDefault={isDefault}
+          hostNavigation={hostNavigation}
+          activeSpaceSlug={activeSpaceSlug}
+          companyId={companyId}
+          onClose={onMenuClose}
+          onArchived={onArchived}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function SpaceRowMenu({
+  space,
+  isDefault,
+  hostNavigation,
+  activeSpaceSlug,
+  companyId,
+  onClose,
+  onArchived,
+}: {
+  space: WikiSpace;
+  isDefault: boolean;
+  hostNavigation: ReturnType<typeof useHostNavigation>;
+  activeSpaceSlug: string;
+  companyId: string | null;
+  onClose: () => void;
+  onArchived: (slug: string) => void;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const archive = usePluginAction("archive-space");
+  const bootstrap = usePluginAction("bootstrap-space");
+  const toast = usePluginToast();
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    const handler = (event: MouseEvent) => {
+      if (!ref.current) return;
+      if (event.target instanceof Node && ref.current.contains(event.target)) return;
+      onClose();
+    };
+    const keyHandler = (event: KeyboardEvent) => {
+      if (event.key === "Escape") onClose();
+    };
+    document.addEventListener("mousedown", handler);
+    document.addEventListener("keydown", keyHandler);
+    return () => {
+      document.removeEventListener("mousedown", handler);
+      document.removeEventListener("keydown", keyHandler);
+    };
+  }, [onClose]);
+
+  const handleArchive = async () => {
+    if (!companyId || isDefault || busy) return;
+    if (typeof window !== "undefined" && !window.confirm(`Archive ${space.displayName}? Pages remain on disk; you can restore later through the plugin API or by un-archiving from the database.`)) {
+      return;
+    }
+    setBusy(true);
+    try {
+      await archive({ companyId, spaceSlug: space.slug });
+      toast({ tone: "success", title: "Space archived", body: `${space.displayName} hidden from sidebar.` });
+      onArchived(space.slug);
+    } catch (err) {
+      toast({ tone: "error", title: "Archive failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const handleRefresh = async () => {
+    if (!companyId || busy) return;
+    setBusy(true);
+    try {
+      await bootstrap({ companyId, spaceSlug: space.slug });
+      toast({ tone: "success", title: "Space refreshed", body: `${space.displayName} index re-bootstrapped.` });
+      onClose();
+    } catch (err) {
+      toast({ tone: "error", title: "Refresh failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <div
+      ref={ref}
+      role="menu"
+      onClick={(event) => event.stopPropagation()}
+      style={{
+        position: "absolute",
+        top: "calc(100% + 4px)",
+        right: 0,
+        zIndex: 30,
+        minWidth: 220,
+        background: tokens.card,
+        border: `1px solid ${tokens.border}`,
+        borderRadius: 8,
+        boxShadow: "0 12px 36px rgba(0,0,0,0.45)",
+        padding: 4,
+      }}
+    >
+      <SpaceMenuItem
+        label="Edit space"
+        Icon={PencilIcon}
+        onClick={() => {
+          onClose();
+          hostNavigation.navigate(buildSettingsSectionHref("spaces", activeSpaceSlug, space.slug));
+        }}
+      />
+      <SpaceMenuItem
+        label="Refresh index"
+        Icon={RefreshIcon}
+        onClick={handleRefresh}
+        disabled={busy}
+      />
+      <SpaceMenuItem
+        label="Open ingest"
+        Icon={PlusCircleIcon}
+        onClick={() => {
+          onClose();
+          hostNavigation.navigate(buildSectionHref("ingest", space.slug));
+        }}
+      />
+      <SpaceMenuDivider />
+      <SpaceMenuItem
+        label={isDefault ? "Archive space (default cannot be archived)" : "Archive space…"}
+        Icon={ArchiveIcon}
+        onClick={handleArchive}
+        disabled={isDefault || busy}
+        destructive
+      />
+    </div>
+  );
+}
+
+function SpaceMenuItem({
+  label,
+  Icon,
+  onClick,
+  disabled,
+  destructive,
+}: {
+  label: string;
+  Icon: (props: LucideIconProps) => ReactElement;
+  onClick: () => void;
+  disabled?: boolean;
+  destructive?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      onClick={onClick}
+      disabled={disabled}
+      style={{
+        width: "100%",
+        display: "flex",
+        alignItems: "center",
+        gap: 10,
+        padding: "7px 10px",
+        background: "transparent",
+        border: "none",
+        cursor: disabled ? "not-allowed" : "pointer",
+        color: destructive ? "oklch(0.7 0.2 25)" : tokens.fg,
+        opacity: disabled ? 0.5 : 1,
+        fontSize: 13,
+        textAlign: "left",
+        borderRadius: 4,
+        fontFamily: fontStack,
+      }}
+      onMouseEnter={(event) => {
+        if (disabled) return;
+        event.currentTarget.style.background = tokens.accent;
+      }}
+      onMouseLeave={(event) => {
+        event.currentTarget.style.background = "transparent";
+      }}
+    >
+      <span aria-hidden="true" style={{ display: "flex", color: destructive ? "oklch(0.7 0.2 25)" : tokens.muted }}>
+        <Icon size={14} />
+      </span>
+      <span style={{ flex: 1 }}>{label}</span>
+    </button>
+  );
+}
+
+function SpaceMenuDivider() {
+  return <div style={{ height: 1, background: tokens.border, margin: "4px 0" }} />;
+}
+
+const shellStyle: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+  height: "100%",
+  minHeight: 600,
+  background: tokens.bg,
+  color: tokens.fg,
+  fontFamily: fontStack,
+  fontSize: 14,
+};
+
+// ---------------------------------------------------------------------------
+// Pre-flight: prompt for folder before any tab can be useful.
+// ---------------------------------------------------------------------------
+
+function UnconfiguredFolder({ context, folder, refresh }: { context: { companyId: string | null }; folder?: FolderStatus; refresh: () => void }) {
+  const bootstrap = usePluginAction("bootstrap-root");
+  const toast = usePluginToast();
+  const isMobile = useIsMobileLayout();
+  const [path, setPath] = useState(folder?.path ?? "");
+  const [busy, setBusy] = useState(false);
+  const [errorMsg, setErrorMsg] = useState<string | null>(null);
+  const configuredButUnhealthy = Boolean(folder?.configured);
+
+  useEffect(() => {
+    setPath(folder?.path ?? "");
+  }, [folder?.path]);
+
+  async function submit() {
+    if (!context.companyId || !path.trim()) return;
+    setBusy(true);
+    setErrorMsg(null);
+    try {
+      const result = await bootstrap({ companyId: context.companyId, path: path.trim() });
+      const written = (result as { writtenFiles?: string[] }).writtenFiles ?? [];
+      toast({ tone: "success", title: "Wiki root configured", body: written.length ? `Created ${written.length} bootstrap file(s).` : "Existing files preserved." });
+      refresh();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setErrorMsg(message);
+      toast({ tone: "error", title: "Could not configure wiki root", body: message });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <div style={{ flex: 1, padding: isMobile ? 16 : 28, display: "grid", placeItems: "start", overflow: isMobile ? "visible" : "auto", minWidth: 0 }}>
+      <Card style={{ maxWidth: 720, width: "100%" }}>
+        <CardHeader title={configuredButUnhealthy ? "Repair wiki root folder" : "Choose a wiki root folder"} />
+        <CardBody>
+          <Tiny style={{ marginBottom: 12 }}>
+            {configuredButUnhealthy
+              ? "The configured wiki root is not ready. Update the path or repair it to recreate required baseline files."
+              : "Pick an absolute path on this machine. The plugin creates "}
+            {!configuredButUnhealthy ? <><Mono>raw/</Mono>, <Mono>wiki/</Mono>, <Mono>AGENTS.md</Mono>, <Mono>IDEA.md</Mono>, <Mono>wiki/index.md</Mono>, and <Mono>wiki/log.md</Mono> if they don't already exist.</> : null}
+          </Tiny>
+          {folder?.problems?.length ? (
+            <Callout tone="danger">
+              <div style={{ display: "grid", gap: 6 }}>
+                {folder.problems.map((problem, index) => (
+                  <div key={`${problem.code}:${problem.path ?? index}`}>
+                    {problem.message}{problem.path ? <> <Mono>{problem.path}</Mono></> : null}
+                  </div>
+                ))}
+              </div>
+            </Callout>
+          ) : null}
+          <div style={{ display: "grid", gap: 12 }}>
+            {folder ? <FolderHealthChecklist folder={folder} /> : null}
+            <FolderPathPicker
+              value={path}
+              onChange={setPath}
+              onApply={submit}
+              applyLabel={configuredButUnhealthy ? "Repair & bootstrap" : "Configure & bootstrap"}
+              busy={busy}
+              disabled={!path.trim()}
+            />
+            <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
+              <Button variant="ghost" onClick={() => refresh()}>I already configured it</Button>
+            </div>
+            {errorMsg ? <Callout tone="danger">{errorMsg}</Callout> : null}
+          </div>
+        </CardBody>
+      </Card>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Browse tab: selected page detail. The route sidebar owns the file tree.
+// ---------------------------------------------------------------------------
+
+const TEMPLATE_PATHS = ["AGENTS.md", "IDEA.md"] as const;
+const BASELINE_DIRECTORIES = ["raw", "wiki", "wiki/sources", "wiki/projects", "wiki/entities", "wiki/concepts", "wiki/synthesis"] as const;
+const BASELINE_FILES = [...TEMPLATE_PATHS, "wiki/index.md", "wiki/log.md"] as const;
+const BASELINE_TREE_ORDER = new Map<string, number>([
+  ["AGENTS.md", 0],
+  ["IDEA.md", 1],
+  ["raw", 2],
+  ["wiki", 3],
+  ["wiki/index.md", 0],
+  ["wiki/log.md", 1],
+  ["wiki/sources", 2],
+  ["wiki/projects", 3],
+  ["wiki/entities", 4],
+  ["wiki/concepts", 5],
+  ["wiki/synthesis", 6],
+]);
+
+function basename(path: string): string {
+  return path.split("/").pop() ?? path;
+}
+
+function dirname(path: string): string {
+  const idx = path.lastIndexOf("/");
+  return idx === -1 ? "" : path.slice(0, idx);
+}
+
+function ensureDir(roots: FileTreeNode[], dirPath: string): FileTreeNode {
+  const segments = dirPath.split("/").filter(Boolean);
+  let parentChildren = roots;
+  let currentPath = "";
+  let currentNode: FileTreeNode | null = null;
+  for (const segment of segments) {
+    currentPath = currentPath ? `${currentPath}/${segment}` : segment;
+    let next = parentChildren.find((c) => c.kind === "dir" && c.path === currentPath);
+    if (!next) {
+      next = { name: segment, path: currentPath, kind: "dir", children: [] };
+      parentChildren.push(next);
+    }
+    parentChildren = next.children;
+    currentNode = next;
+  }
+  if (!currentNode) {
+    throw new Error(`ensureDir called with empty path`);
+  }
+  return currentNode;
+}
+
+function pageDisplayName(path: string, title: string | null): string {
+  const trimmed = title?.trim();
+  return trimmed ? trimmed : basename(path);
+}
+
+function treeDisplayName(path: string, title: string | null): string {
+  return (BASELINE_FILES as readonly string[]).includes(path) ? basename(path) : pageDisplayName(path, title);
+}
+
+function buildBrowseTree(
+  pages: WikiPageRow[],
+  sources: WikiSourceRow[],
+): FileTreeNode[] {
+  const roots: FileTreeNode[] = [];
+  const seenPaths = new Set<string>();
+
+  for (const dirPath of BASELINE_DIRECTORIES) {
+    ensureDir(roots, dirPath);
+  }
+
+  if (sources.length > 0) {
+    const rawDir = ensureDir(roots, "raw");
+    for (const source of sources) {
+      seenPaths.add(source.rawPath);
+      const node: FileTreeNode = {
+        name: pageDisplayName(source.rawPath, source.title),
+        path: source.rawPath,
+        kind: "file",
+        children: [],
+      };
+      rawDir.children.push(node);
+    }
+  }
+
+  for (const page of pages) {
+    seenPaths.add(page.path);
+    const parentDir = dirname(page.path);
+    const file: FileTreeNode = {
+      name: treeDisplayName(page.path, page.title),
+      path: page.path,
+      kind: "file",
+      children: [],
+    };
+    if (parentDir) {
+      ensureDir(roots, parentDir).children.push(file);
+    } else {
+      roots.push(file);
+    }
+  }
+
+  // Add the baseline files using their real wiki-root paths so the browser
+  // mirrors the on-disk default layout even before metadata has been indexed.
+  for (const path of BASELINE_FILES) {
+    if (seenPaths.has(path)) continue;
+    const parentDir = dirname(path);
+    const node = {
+      name: basename(path),
+      path,
+      kind: "file" as const,
+      children: [],
+      action: path,
+    };
+    seenPaths.add(path);
+    if (parentDir) {
+      ensureDir(roots, parentDir).children.push(node);
+      continue;
+    }
+    roots.push({
+      ...node,
+      name: path,
+    });
+  }
+
+  function sortNodes(nodes: FileTreeNode[]) {
+    nodes.sort((a, b) => {
+      const orderA = BASELINE_TREE_ORDER.get(a.path);
+      const orderB = BASELINE_TREE_ORDER.get(b.path);
+      if (orderA != null || orderB != null) return (orderA ?? Number.MAX_SAFE_INTEGER) - (orderB ?? Number.MAX_SAFE_INTEGER);
+      if (a.kind !== b.kind) return a.kind === "dir" ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+    for (const node of nodes) {
+      if (node.kind === "dir") sortNodes(node.children);
+    }
+  }
+  sortNodes(roots);
+
+  return roots;
+}
+
+function expandedAncestors(path: string | null): string[] {
+  if (!path) return [];
+  const out: string[] = [];
+  const segments = path.split("/").filter(Boolean);
+  let current = "";
+  for (let i = 0; i < segments.length - 1; i++) {
+    current = current ? `${current}/${segments[i]}` : segments[i];
+    out.push(current);
+  }
+  return out;
+}
+
+function BrowseTab({ context }: { context: { companyId: string | null } }) {
+  const { pathname, search } = useHostLocation();
+  const activeSpaceSlug = useMemo(() => readActiveSpaceSlugFromLocation(pathname), [pathname]);
+  const pages = usePages(context.companyId, { includeRaw: true, spaceSlug: activeSpaceSlug });
+  const isMobile = useIsMobileLayout();
+  const selectedTreePath = readSelectedTreePathFromLocation(pathname, search) ?? firstSelectableTreePath(pages.data);
+  const selected = contentPathFromTreePath(selectedTreePath);
+
+  return (
+    <div style={{ flex: 1, minWidth: 0, overflow: isMobile ? "visible" : "auto" }}>
+      {pages.loading && !selected ? (
+        <div style={{ padding: isMobile ? 16 : 28, color: tokens.muted, fontSize: 13 }}>Loading pages…</div>
+      ) : pages.error && !selected ? (
+        <div style={{ padding: isMobile ? 16 : 28 }}><Callout tone="danger">Failed to load pages: {pages.error.message}</Callout></div>
+      ) : (
+        <PageDetail context={context} path={selected} spaceSlug={activeSpaceSlug} />
+      )}
+    </div>
+  );
+}
+
+function PageDetail({ context, path, spaceSlug }: { context: { companyId: string | null }; path: string | null; spaceSlug?: string }) {
+  const content = usePageContent(context.companyId, path, spaceSlug ?? null);
+  const writePage = usePluginAction("write-page");
+  const toast = usePluginToast();
+  const hostNavigation = useHostNavigation();
+  const isMobile = useIsMobileLayout();
+  const markdownBodyRef = useRef<HTMLDivElement | null>(null);
+  const [editing, setEditing] = useState(false);
+  const [savedHash, setSavedHash] = useState<string | null>(null);
+  const [provenanceOpen, setProvenanceOpen] = useState(false);
+  const [tocOpen, setTocOpen] = useState(true);
+  const [activeTocId, setActiveTocId] = useState<string | null>(null);
+  const parsedMarkdown = useMemo(() => parseWikiMarkdown(content.data?.contents ?? ""), [content.data?.contents]);
+  const tocHeadings = useMemo(() => extractWikiTocHeadings(parsedMarkdown.body), [parsedMarkdown.body]);
+
+  useEffect(() => {
+    setEditing(false);
+    setSavedHash(null);
+    setTocOpen(true);
+    setActiveTocId(null);
+  }, [path]);
+
+  useEffect(() => {
+    if (!content.data || editing) return;
+    const root = markdownBodyRef.current;
+    if (!root) return;
+    const renderedHeadings = Array.from(root.querySelectorAll("h2, h3, h4"));
+    tocHeadings.forEach((heading, index) => {
+      const element = renderedHeadings[index];
+      if (element instanceof HTMLElement) {
+        element.id = heading.id;
+      }
+    });
+  }, [content.data, editing, tocHeadings]);
+
+  useEffect(() => {
+    if (!content.data || editing || tocHeadings.length === 0) return;
+    const root = markdownBodyRef.current;
+    if (!root) return;
+
+    const scrollParent = findScrollableAncestor(root);
+    const updateActiveHeading = () => {
+      const containerTop = scrollParent instanceof HTMLElement ? scrollParent.getBoundingClientRect().top : 0;
+      const activationY = containerTop + 96;
+      let activeId = tocHeadings[0]?.id ?? null;
+
+      for (const heading of tocHeadings) {
+        const element = root.ownerDocument.getElementById(heading.id);
+        if (!(element instanceof HTMLElement)) continue;
+        if (!root.contains(element)) continue;
+        if (element.getBoundingClientRect().top <= activationY) {
+          activeId = heading.id;
+        } else {
+          break;
+        }
+      }
+
+      setActiveTocId(activeId);
+    };
+
+    updateActiveHeading();
+    scrollParent.addEventListener("scroll", updateActiveHeading, { passive: true });
+    window.addEventListener("resize", updateActiveHeading);
+    return () => {
+      scrollParent.removeEventListener("scroll", updateActiveHeading);
+      window.removeEventListener("resize", updateActiveHeading);
+    };
+  }, [content.data, editing, tocHeadings]);
+
+  const editable = path ? isEditableWikiPagePath(path) : false;
+  const resolveWikiLinkHref = useCallback(
+    (target: string) => buildWikiLinkHref(target, hostNavigation.resolveHref),
+    [hostNavigation.resolveHref],
+  );
+  const handleTocClick = useCallback((event: React.MouseEvent<HTMLAnchorElement>, id: string) => {
+    const root = markdownBodyRef.current;
+    const target = root?.ownerDocument.getElementById(id);
+    if (!(target instanceof HTMLElement)) return;
+    if (root && !root.contains(target)) return;
+    event.preventDefault();
+    setActiveTocId(id);
+    target.scrollIntoView({ block: "start", behavior: "smooth" });
+    if (typeof window !== "undefined") {
+      window.history.replaceState(window.history.state, "", `${window.location.pathname}${window.location.search}#${id}`);
+    }
+  }, []);
+  const savePageContents = useCallback(async (nextContents: string) => {
+    if (!context.companyId || !content.data || !editable || !path) return;
+    const result = await writePage({
+        companyId: context.companyId,
+        wikiId: content.data.wikiId,
+        spaceSlug: spaceSlug ?? null,
+        path,
+        contents: nextContents,
+        expectedHash: savedHash ?? content.data.hash,
+        summary: `Edited ${path} from the LLM Wiki page`,
+    }) as { hash?: string };
+    if (typeof result.hash === "string") setSavedHash(result.hash);
+  }, [context.companyId, content.data, editable, path, savedHash, writePage, spaceSlug]);
+
+  if (!path) return <div style={{ padding: isMobile ? 16 : 28, color: tokens.muted, fontSize: 13 }}>Pick a page from the tree.</div>;
+  if (content.loading) return <div style={{ padding: isMobile ? 16 : 28, color: tokens.muted, fontSize: 13 }}>Loading {path}…</div>;
+  if (content.error && path.startsWith("raw/")) {
+    return (
+      <div style={{ padding: isMobile ? 16 : 28, display: "grid", gap: 12 }}>
+        <Callout tone="warn">
+          The captured source <Mono>{path}</Mono> is indexed but no longer exists in the configured wiki folder. Refresh the wiki or re-ingest the source to restore it.
+        </Callout>
+        <Tiny>{content.error.message}</Tiny>
+      </div>
+    );
+  }
+  if (content.error) return <div style={{ padding: isMobile ? 16 : 28 }}><Callout tone="danger">Failed to read {path}: {content.error.message}</Callout></div>;
+  if (!content.data) return <div style={{ padding: isMobile ? 16 : 28, color: tokens.muted, fontSize: 13 }}>No content for {path}.</div>;
+  const { contents, title, sourceRefs, updatedAt, hash } = content.data;
+  const visibleFrontmatter = parsedMarkdown.frontmatter.filter((property) => property.key.toLowerCase() !== "title");
+  const displayTitle = (BASELINE_FILES as readonly string[]).includes(path) ? basename(path) : title ?? basename(path);
+  const folderPath = dirname(path);
+
+  const isDistilledProjectPage = path.startsWith("wiki/projects/");
+  const showToc = !editing && tocHeadings.length > 0;
+  const displaySourceRefs = sourceRefs
+    .map((ref, index) => ({
+      id: sourceRefIdentity(ref, index),
+      label: formatSourceRef(ref, index),
+      hasDisplayText: typeof ref === "string" || readSourceRefField(ref, "title") !== null,
+    }))
+    .filter((ref) => ref.hasDisplayText);
+
+  return (
+    <article style={{ padding: isMobile ? "16px" : "24px 28px", display: "grid", gap: isMobile ? 12 : 14, minWidth: 0 }}>
+      <header style={{ display: "grid", gap: 8, minWidth: 0 }}>
+        <div style={{ display: "flex", alignItems: "flex-start", gap: 12, flexWrap: "wrap", minWidth: 0 }}>
+          <div style={{ flex: "1 1 260px", minWidth: 0 }}>
+            {folderPath ? <Tiny style={{ display: "block", marginBottom: 6 }}><Mono>{folderPath}</Mono></Tiny> : null}
+            <h1 style={{ margin: 0, fontSize: isMobile ? 20 : 22, overflowWrap: "anywhere" }}>{displayTitle}</h1>
+          </div>
+          <div style={{ display: "flex", gap: 6, alignItems: "center" }}>
+            {isDistilledProjectPage ? (
+              <Button size="sm" variant="ghost" onClick={() => setProvenanceOpen(true)} title="Show source provenance and freshness">
+                <InfoIcon size={12} /> Provenance
+              </Button>
+            ) : null}
+            {editable && !editing ? (
+              <Button size="sm" onClick={() => { setSavedHash(hash); setEditing(true); }}>Edit page</Button>
+            ) : editable ? (
+              <Button size="sm" variant="ghost" onClick={() => { setEditing(false); content.refresh(); }}>Done</Button>
+            ) : (
+              <Badge>read-only source</Badge>
+            )}
+          </div>
+        </div>
+        <Tiny>Updated {updatedAt ? formatTime(updatedAt) : "—"}</Tiny>
+      </header>
+      {isDistilledProjectPage && path ? (
+        <FreshnessChip companyId={context.companyId} pagePath={path} companyPrefix={(context as { companyPrefix?: string | null }).companyPrefix ?? null} />
+      ) : null}
+      {editing ? (
+        <>
+          <AutosaveMarkdownEditor
+            key={`${path}:${hash}`}
+            resetKey={`${path}:${hash}`}
+            value={contents}
+            placeholder={`Edit ${path}`}
+            minHeight={isMobile ? 260 : 420}
+            onSave={async (nextContents) => {
+              await savePageContents(nextContents);
+              toast({ tone: "success", title: `${path} saved` });
+            }}
+          />
+        </>
+      ) : (
+        <div
+          data-testid="llm-wiki-page-content-layout"
+          style={{
+            display: "grid",
+            gridTemplateColumns: showToc && !isMobile ? `minmax(0, 1fr) ${tocOpen ? "minmax(180px, 240px)" : "36px"}` : "minmax(0, 1fr)",
+            gap: showToc && !isMobile ? (tocOpen ? 24 : 10) : 0,
+            alignItems: "start",
+            minWidth: 0,
+          }}
+        >
+          <div style={{ display: "grid", gap: isMobile ? 12 : 14, minWidth: 0 }}>
+            <div ref={markdownBodyRef} style={{ minWidth: 0, fontSize: 13, lineHeight: 1.65 }}>
+              <FrontmatterProperties properties={visibleFrontmatter} />
+              <MarkdownBlock
+                content={parsedMarkdown.body}
+                enableWikiLinks
+                resolveWikiLinkHref={resolveWikiLinkHref}
+              />
+              {displaySourceRefs.length > 0 ? (
+                <section aria-label="Paperclip source refs" style={{ marginTop: 16, display: "grid", gap: 6 }}>
+                  <Tiny style={{ fontWeight: 650 }}>Paperclip source refs</Tiny>
+                  <ul style={{ margin: 0, paddingLeft: 18, color: tokens.muted, fontSize: 12, lineHeight: 1.5 }}>
+                    {displaySourceRefs.map((ref) => (
+                      <li key={ref.id}>{ref.label}</li>
+                    ))}
+                  </ul>
+                </section>
+              ) : null}
+            </div>
+          </div>
+          {showToc ? (
+            <OnThisPagePane
+              headings={tocHeadings}
+              activeHeadingId={activeTocId}
+              open={tocOpen}
+              onToggle={() => setTocOpen((current) => !current)}
+              onHeadingClick={handleTocClick}
+              mobile={isMobile}
+            />
+          ) : null}
+        </div>
+      )}
+      {provenanceOpen && path ? (
+        <ProvenanceDrawer
+          companyId={context.companyId}
+          pagePath={path}
+          onClose={() => setProvenanceOpen(false)}
+        />
+      ) : null}
+    </article>
+  );
+}
+
+function findScrollableAncestor(element: HTMLElement): HTMLElement | Window {
+  let current: HTMLElement | null = element.parentElement;
+  while (current && current !== document.body && current !== document.documentElement) {
+    const style = window.getComputedStyle(current);
+    const overflowY = style.overflowY;
+    if ((overflowY === "auto" || overflowY === "scroll") && current.scrollHeight > current.clientHeight) {
+      return current;
+    }
+    current = current.parentElement;
+  }
+  return window;
+}
+
+function OnThisPagePane({
+  headings,
+  activeHeadingId,
+  open,
+  onToggle,
+  onHeadingClick,
+  mobile,
+}: {
+  headings: WikiTocHeading[];
+  activeHeadingId: string | null;
+  open: boolean;
+  onToggle: () => void;
+  onHeadingClick: (event: React.MouseEvent<HTMLAnchorElement>, id: string) => void;
+  mobile: boolean;
+}) {
+  const contentId = "llm-wiki-on-this-page";
+  const currentHeadingId = activeHeadingId ?? headings[0]?.id ?? null;
+  const shellRef = useRef<HTMLElement | null>(null);
+  const [fixedFrame, setFixedFrame] = useState<{ left: number; top: number; width: number } | null>(null);
+
+  useEffect(() => {
+    if (mobile) {
+      setFixedFrame(null);
+      return;
+    }
+    const shell = shellRef.current;
+    if (!shell) return;
+
+    let animationFrame = 0;
+    const updateFrame = () => {
+      cancelAnimationFrame(animationFrame);
+      animationFrame = requestAnimationFrame(() => {
+        const rect = shell.getBoundingClientRect();
+        const top = Math.max(WIKI_TOC_STICKY_TOP, rect.top);
+        setFixedFrame((current) => {
+          if (
+            current &&
+            Math.abs(current.left - rect.left) < 0.5 &&
+            Math.abs(current.top - top) < 0.5 &&
+            Math.abs(current.width - rect.width) < 0.5
+          ) {
+            return current;
+          }
+          return { left: rect.left, top, width: rect.width };
+        });
+      });
+    };
+
+    updateFrame();
+    const resizeObserver = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(updateFrame);
+    resizeObserver?.observe(shell);
+    window.addEventListener("resize", updateFrame);
+    window.addEventListener("scroll", updateFrame, true);
+    return () => {
+      cancelAnimationFrame(animationFrame);
+      resizeObserver?.disconnect();
+      window.removeEventListener("resize", updateFrame);
+      window.removeEventListener("scroll", updateFrame, true);
+    };
+  }, [mobile, open]);
+
+  const paneStyle: CSSProperties = mobile ? {} : fixedFrame ? {
+    position: "fixed",
+    top: fixedFrame.top,
+    left: fixedFrame.left,
+    width: fixedFrame.width,
+    maxHeight: `calc(100vh - ${fixedFrame.top + 16}px)`,
+    overflowY: "auto",
+    zIndex: 2,
+  } : {
+    position: "sticky",
+    top: WIKI_TOC_STICKY_TOP,
+  };
+
+  return (
+    <aside
+      ref={shellRef}
+      aria-label="On this page"
+      style={{
+        order: mobile ? -1 : 0,
+        minWidth: 0,
+        minHeight: mobile ? undefined : open ? 120 : 24,
+        alignSelf: "start",
+      }}
+    >
+      <div style={{
+        ...paneStyle,
+        borderLeft: open ? `1px solid ${tokens.border}` : 0,
+        paddingLeft: open ? 10 : 0,
+      }}>
+        <button
+          type="button"
+          aria-label={open ? "Collapse on this page" : "Expand on this page"}
+          aria-expanded={open}
+          aria-controls={contentId}
+          onClick={onToggle}
+          style={{
+            display: "flex",
+            alignItems: "center",
+            justifyContent: open ? "space-between" : "center",
+            gap: 10,
+            width: "100%",
+            border: 0,
+            background: "transparent",
+            color: tokens.fg,
+            padding: open ? "0 0 8px" : "0",
+            fontFamily: fontStack,
+            fontSize: 12,
+            fontWeight: 650,
+            cursor: "pointer",
+            textAlign: "left",
+          }}
+        >
+          {open ? <span>On this page</span> : null}
+          <span aria-hidden="true" style={{ color: tokens.muted, transform: open ? "rotate(90deg)" : "rotate(0deg)", transition: "transform 120ms ease" }}>
+            <ChevronLeftIcon size={13} />
+          </span>
+        </button>
+        {open ? (
+          <nav id={contentId} style={{ display: "grid", gap: 2 }}>
+            {headings.map((heading) => {
+              const active = heading.id === currentHeadingId;
+              return (
+                <a
+                  key={heading.id}
+                  href={`#${heading.id}`}
+                  aria-current={active ? "location" : undefined}
+                  onClick={(event) => onHeadingClick(event, heading.id)}
+                  style={{
+                    display: "block",
+                    padding: `3px 0 3px ${Math.max(0, heading.level - 2) * 12}px`,
+                    color: active ? tokens.fg : tokens.muted,
+                    fontSize: 12,
+                    fontWeight: active ? 700 : 450,
+                    lineHeight: 1.35,
+                    textDecoration: "none",
+                    overflowWrap: "anywhere",
+                  }}
+                >
+                  {heading.text}
+                </a>
+              );
+            })}
+          </nav>
+        ) : null}
+      </div>
+    </aside>
+  );
+}
+
+function FreshnessChip({ companyId, pagePath, companyPrefix }: { companyId: string | null; pagePath: string; companyPrefix: string | null }) {
+  const provenance = useDistillationProvenance(companyId, pagePath);
+  const binding = provenance.data?.binding ?? null;
+  const cursor = provenance.data?.cursor ?? null;
+
+  if (provenance.loading && !provenance.data) {
+    return <FreshnessChipShell tone="info" icon={<ClockIcon size={14} />}>Checking distillation cursor…</FreshnessChipShell>;
+  }
+  if (!binding) return null;
+
+  const lastEnd = binding.lastRunSourceWindowEnd ?? binding.lastRunCompletedAt;
+  const status = binding.lastRunStatus ?? "unknown";
+  const sourceCount = (() => {
+    const meta = binding.metadata as Record<string, unknown>;
+    const refs = Array.isArray(meta.sourceRefs) ? meta.sourceRefs.length : null;
+    return refs;
+  })();
+  const isStale = (() => {
+    if (status === "failed" || status === "refused_cost_cap") return true;
+    if (!lastEnd) return true;
+    const diff = Date.now() - Date.parse(lastEnd);
+    return Number.isFinite(diff) ? diff > 72 * 60 * 60 * 1000 : true;
+  })();
+  const isFailed = status === "failed" || status === "refused_cost_cap";
+  const isRunning = status === "running";
+
+  const tone: "info" | "warn" | "danger" | "running" = isFailed ? "danger" : isStale ? "warn" : isRunning ? "running" : "info";
+  const projectLink = cursor && cursor.projectId && companyPrefix ? `/${companyPrefix}/projects/${cursor.projectId}` : null;
+
+  return (
+    <FreshnessChipShell
+      tone={tone}
+      icon={isFailed ? <AlertTriangleIcon size={14} /> : isRunning ? <ActivityIcon size={14} /> : <ClockIcon size={14} />}
+    >
+      <span><strong>Current as of {lastEnd ? formatTimestamp(lastEnd) : "—"}.</strong>
+        {sourceCount ? ` ${sourceCount} sources in this window. ` : " "}
+        Cursor at <Mono>{lastEnd ?? "—"}</Mono>.
+      </span>
+      {projectLink ? (
+        <a href={projectLink} style={{ marginLeft: 8, color: "inherit", textDecoration: "underline" }}>
+          Open Paperclip for live state →
+        </a>
+      ) : null}
+    </FreshnessChipShell>
+  );
+}
+
+function FreshnessChipShell({ tone, icon, children }: { tone: "info" | "warn" | "danger" | "running"; icon: ReactNode; children: ReactNode }) {
+  const palette = tone === "danger"
+    ? { bg: "oklch(0.22 0.06 25)", fg: "oklch(0.85 0.12 25)", border: "oklch(0.45 0.12 25)" }
+    : tone === "warn"
+      ? { bg: "oklch(0.22 0.06 70)", fg: "oklch(0.85 0.1 70)", border: "oklch(0.45 0.12 70)" }
+      : tone === "running"
+        ? { bg: "oklch(0.22 0.06 200)", fg: "oklch(0.85 0.11 200)", border: "oklch(0.45 0.12 200)" }
+        : tokens.callout;
+  return (
+    <div style={{
+      display: "inline-flex",
+      alignItems: "center",
+      gap: 8,
+      padding: "8px 12px",
+      borderRadius: 999,
+      background: palette.bg,
+      color: palette.fg,
+      border: `1px solid ${palette.border}`,
+      fontSize: 12.5,
+      lineHeight: 1.5,
+      flexWrap: "wrap",
+    }}>
+      {icon}
+      <div style={{ display: "flex", alignItems: "center", gap: 4, flexWrap: "wrap" }}>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+function readSourceRefField(ref: Record<string, unknown>, field: string): string | null {
+  const value = ref[field];
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function sourceRefIdentity(ref: Record<string, unknown> | string, fallbackIndex: number): string {
+  if (typeof ref === "string") return ref;
+  const issueIdentifier = readSourceRefField(ref, "issueIdentifier");
+  const issueId = readSourceRefField(ref, "issueId");
+  const commentId = readSourceRefField(ref, "commentId");
+  const documentKey = readSourceRefField(ref, "documentKey");
+  const documentId = readSourceRefField(ref, "documentId");
+  const kind = readSourceRefField(ref, "kind");
+  const parts = [kind, issueIdentifier ?? issueId, commentId, documentKey ?? documentId].filter(Boolean);
+  return parts.length > 0 ? parts.join(":") : `source-ref-${fallbackIndex}`;
+}
+
+function formatSourceRef(ref: Record<string, unknown> | string, fallbackIndex: number): string {
+  if (typeof ref === "string") return ref;
+
+  const kind = readSourceRefField(ref, "kind");
+  const issue = readSourceRefField(ref, "issueIdentifier") ?? readSourceRefField(ref, "issueId");
+  const title = readSourceRefField(ref, "title");
+  const commentId = readSourceRefField(ref, "commentId");
+  const documentKey = readSourceRefField(ref, "documentKey");
+  const documentId = readSourceRefField(ref, "documentId");
+
+  const primary = issue ?? sourceRefIdentity(ref, fallbackIndex);
+  const suffix = kind === "comment" && commentId
+    ? ` comment ${commentId.slice(0, 8)}`
+    : kind === "document" && (documentKey || documentId)
+      ? ` document ${documentKey ?? documentId?.slice(0, 8)}`
+      : kind ? ` ${kind}` : "";
+  return title ? `${primary}${suffix} - ${title}` : `${primary}${suffix}`;
+}
+
+function ProvenanceDrawer({ companyId, pagePath, onClose }: { companyId: string | null; pagePath: string; onClose: () => void }) {
+  const isMobile = useIsMobileLayout();
+  const provenance = useDistillationProvenance(companyId, pagePath);
+  const data = provenance.data;
+  const binding = data?.binding ?? null;
+  const cursor = data?.cursor ?? null;
+  const snapshot = data?.snapshot ?? null;
+  const runs = data?.runs ?? [];
+
+  return (
+    <div
+      onClick={onClose}
+      style={{
+        position: "fixed",
+        inset: 0,
+        background: "oklch(0 0 0 / 0.55)",
+        zIndex: 50,
+        display: "flex",
+        justifyContent: isMobile ? "stretch" : "flex-end",
+        alignItems: isMobile ? "flex-end" : "stretch",
+      }}
+    >
+      <div
+        onClick={(event) => event.stopPropagation()}
+        style={{
+          background: tokens.bg,
+          borderLeft: isMobile ? undefined : `1px solid ${tokens.border}`,
+          borderTop: isMobile ? `1px solid ${tokens.border}` : undefined,
+          width: isMobile ? "100%" : 420,
+          maxWidth: "100%",
+          maxHeight: isMobile ? "85vh" : "100vh",
+          display: "flex",
+          flexDirection: "column",
+        }}
+      >
+        <div style={{ padding: "14px 18px", borderBottom: `1px solid ${tokens.border}`, display: "flex", alignItems: "center", gap: 10 }}>
+          <InfoIcon size={16} />
+          <strong style={{ fontSize: 14, flex: 1 }}>Provenance</strong>
+          <Button variant="ghost" size="sm" onClick={onClose}>
+            <XIcon size={14} />
+          </Button>
+        </div>
+        <div style={{ overflow: "auto", flex: 1, padding: 18, display: "flex", flexDirection: "column", gap: 14 }}>
+          {provenance.loading && !data ? <Tiny>Loading provenance…</Tiny> : null}
+          {!binding && !provenance.loading ? <Callout>This page is not currently bound to a distillation cursor. It may be hand-authored or pre-distillation.</Callout> : null}
+          {binding ? (
+            <Card>
+              <CardBody padding={14}>
+                <PropRow label="Page path" value={<Mono>{binding.pagePath}</Mono>} />
+                <PropRow label="Source hash" value={<Mono>{binding.lastRunSourceHash?.slice(0, 16) ?? "—"}…</Mono>} />
+                <PropRow label="Cursor end" value={<Mono>{binding.lastRunSourceWindowEnd ? formatTimestamp(binding.lastRunSourceWindowEnd) : "—"}</Mono>} />
+                <PropRow label="Last run status" value={<Badge tone={runStatusTone(binding.lastRunStatus ?? "")}>{binding.lastRunStatus ?? "—"}</Badge>} />
+                <PropRow label="Project" value={binding.projectName ?? "—"} />
+                <PropRow label="Updated" value={formatTimestamp(binding.updatedAt)} />
+              </CardBody>
+            </Card>
+          ) : null}
+          {cursor ? (
+            <Card>
+              <CardHeader title="Cursor" />
+              <CardBody padding={14}>
+                <PropRow label="Scope" value={cursor.sourceScope} />
+                <PropRow label="Pending events" value={String(cursor.pendingEventCount)} />
+                <PropRow label="Last observed" value={formatTimestamp(cursor.lastObservedAt)} />
+                <PropRow label="Last processed" value={formatTimestamp(cursor.lastProcessedAt)} />
+              </CardBody>
+            </Card>
+          ) : null}
+          {snapshot ? (
+            <Card>
+              <CardHeader title="Sources in this window" />
+              <CardBody padding={14}>
+                <Tiny style={{ marginBottom: 8 }}>{snapshot.sourceRefs.length} ref{snapshot.sourceRefs.length === 1 ? "" : "s"}{snapshot.clipped ? " · clipped" : ""}</Tiny>
+                <ul style={{ margin: 0, paddingLeft: 18, fontSize: 12, color: tokens.muted, lineHeight: 1.5 }}>
+                  {snapshot.sourceRefs.slice(0, 8).map((ref, index) => {
+                    const obj = typeof ref === "object" && ref ? ref as Record<string, unknown> : null;
+                    const id = obj && typeof obj.id === "string" ? obj.id : typeof ref === "string" ? ref : `ref-${index}`;
+                    const kind = obj && typeof obj.kind === "string" ? obj.kind : null;
+                    const title = obj && typeof obj.title === "string" ? obj.title : null;
+                    return (
+                      <li key={`${id}-${index}`} style={{ marginBottom: 4 }}>
+                        <Mono>{id}</Mono>
+                        {kind ? ` · ${kind}` : ""}
+                        {title ? ` · ${title}` : ""}
+                      </li>
+                    );
+                  })}
+                </ul>
+                {snapshot.sourceRefs.length > 8 ? <Tiny style={{ marginTop: 6 }}>{`+${snapshot.sourceRefs.length - 8} more`}</Tiny> : null}
+              </CardBody>
+            </Card>
+          ) : null}
+          {runs.length > 0 ? (
+            <Card>
+              <CardHeader title="Operations affecting this page" />
+              <CardBody padding={0}>
+                <ul style={{ margin: 0, padding: 0, listStyle: "none" }}>
+                  {runs.slice(0, 8).map((run) => (
+                    <li key={run.id} style={{ padding: "10px 14px", borderBottom: `1px solid ${tokens.border}`, display: "flex", justifyContent: "space-between", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
+                      <Mono style={{ fontSize: 12 }}>{run.operationIssueIdentifier ?? `op-${run.id.slice(0, 6)}`}</Mono>
+                      <div style={{ display: "flex", gap: 8, alignItems: "center", flexWrap: "wrap" }}>
+                        <Tiny>{formatTimestamp(run.updatedAt)}</Tiny>
+                        <Mono style={{ fontSize: 11 }}>{formatCostCents(run.costCents)}</Mono>
+                        <Badge tone={runStatusTone(run.status)}>{runStatusLabel(run.status)}</Badge>
+                      </div>
+                    </li>
+                  ))}
+                </ul>
+              </CardBody>
+            </Card>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function FrontmatterProperties({ properties }: { properties: WikiFrontmatterProperty[] }) {
+  if (properties.length === 0) return null;
+
+  return (
+    <details
+      open
+      style={{
+        marginBottom: 20,
+        paddingBottom: 16,
+        borderBottom: `1px solid ${tokens.border}`,
+      }}
+    >
+      <summary
+        style={{
+          cursor: "pointer",
+          color: tokens.fg,
+          fontSize: 13,
+          fontWeight: 650,
+          listStylePosition: "outside",
+          marginBottom: 10,
+        }}
+      >
+        Properties
+      </summary>
+      <dl style={{ display: "grid", gap: 8, margin: 0, maxWidth: 720 }}>
+        {properties.map((property) => (
+          <div
+            key={property.key}
+            style={{
+              display: "grid",
+              gridTemplateColumns: "minmax(96px, 0.32fr) minmax(0, 1fr)",
+              gap: 12,
+              alignItems: "baseline",
+              minWidth: 0,
+            }}
+          >
+            <dt style={{ color: tokens.muted, fontSize: 12, minWidth: 0, overflowWrap: "anywhere" }}>{property.key}</dt>
+            <dd style={{ margin: 0, minWidth: 0 }}>
+              <FrontmatterValue value={property.value} />
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </details>
+  );
+}
+
+function FrontmatterValue({ value }: { value: WikiFrontmatterValue }) {
+  if (Array.isArray(value)) {
+    return (
+      <span style={{ display: "flex", flexWrap: "wrap", gap: 6, minWidth: 0 }}>
+        {value.map((item) => (
+          <span
+            key={item}
+            style={{
+              display: "inline-flex",
+              alignItems: "center",
+              minWidth: 0,
+              maxWidth: "100%",
+              padding: "1px 7px",
+              borderRadius: 999,
+              background: "var(--secondary, oklch(0.269 0 0))",
+              color: tokens.fg,
+              fontSize: 12,
+              lineHeight: 1.5,
+              overflowWrap: "anywhere",
+            }}
+          >
+            {item}
+          </span>
+        ))}
+      </span>
+    );
+  }
+
+  return (
+    <span style={{ color: tokens.fg, fontSize: 13, overflowWrap: "anywhere" }}>
+      {value}
+    </span>
+  );
+}
+
+function Row({ primary, secondary, right }: { primary: ReactNode; secondary?: ReactNode; right?: ReactNode }) {
+  return (
+    <div style={{
+      display: "flex",
+      alignItems: "center",
+      flexWrap: "wrap",
+      gap: 12,
+      padding: "8px 12px",
+      borderBottom: `1px solid ${tokens.border}`,
+      fontSize: 13,
+      minWidth: 0,
+    }}>
+      <div style={{ flex: "1 1 220px", minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "normal", overflowWrap: "anywhere" }}>{primary}</div>
+      {secondary ? <div style={{ flex: "0 1 auto", minWidth: 0, color: tokens.muted, fontSize: 12, overflowWrap: "anywhere" }}>{secondary}</div> : null}
+      {right ? <div style={{ marginLeft: "auto", minWidth: 0, display: "flex", gap: 6, alignItems: "center", justifyContent: "flex-end", flexWrap: "wrap" }}>{right}</div> : null}
+    </div>
+  );
+}
+
+function formatTime(iso: string | null | undefined): string {
+  if (!iso) return "—";
+  try {
+    const date = new Date(iso);
+    if (Number.isNaN(date.getTime())) return iso;
+    const diffMs = Date.now() - date.getTime();
+    const minutes = Math.floor(diffMs / 60000);
+    if (minutes < 1) return "just now";
+    if (minutes < 60) return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 30) return `${days}d ago`;
+    return date.toLocaleDateString();
+  } catch {
+    return iso;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Ingest tab.
+// ---------------------------------------------------------------------------
+
+function IngestTab({ context, refreshOverview }: { context: { companyId: string | null }; refreshOverview: () => void }) {
+  const { pathname } = useHostLocation();
+  const activeSpaceSlug = useMemo(() => readActiveSpaceSlugFromLocation(pathname), [pathname]);
+  const spacesQuery = useSpaces(context.companyId);
+  const spaces = useMemo(() => {
+    const list = spacesQuery.data?.spaces ?? [];
+    return activeWikiSpaces(list).sort(compareSpaces);
+  }, [spacesQuery.data]);
+  const ingest = usePluginAction("ingest-source");
+  const toast = usePluginToast();
+  const hostNavigation = useHostNavigation();
+  const isMobile = useIsMobileLayout();
+  const [url, setUrl] = useState("");
+  const [pasted, setPasted] = useState("");
+  const [title, setTitle] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [errorMsg, setErrorMsg] = useState<string | null>(null);
+  const [spaceMenuOpen, setSpaceMenuOpen] = useState(false);
+  const [createOpen, setCreateOpen] = useState(false);
+
+  const activeSpace = useMemo(() => {
+    return spaces.find((space) => space.slug === activeSpaceSlug)
+      ?? spaces.find((space) => space.slug === DEFAULT_SPACE_SLUG)
+      ?? null;
+  }, [spaces, activeSpaceSlug]);
+
+  const canSubmit = !!context.companyId && (pasted.trim().length > 0 || url.trim().length > 0) && !busy;
+
+  useEffect(() => {
+    const refresh = () => refreshOverview();
+    window.addEventListener("pc-wiki-ingest-queued", refresh);
+    return () => window.removeEventListener("pc-wiki-ingest-queued", refresh);
+  }, [refreshOverview]);
+
+  async function submit() {
+    if (!context.companyId) return;
+    setBusy(true);
+    setErrorMsg(null);
+    try {
+      let contents = pasted.trim();
+      let sourceType: "url" | "text" = "text";
+      let resolvedTitle = title.trim();
+      if (url.trim()) {
+        sourceType = "url";
+        contents = pasted.trim() || `Captured URL: ${url.trim()}\n\n_Plugin needs to fetch the URL — placeholder body for the alpha._`;
+        resolvedTitle = resolvedTitle || url.trim();
+      } else {
+        resolvedTitle = resolvedTitle || pasted.split("\n", 1)[0]?.slice(0, 80) || "Pasted source";
+      }
+      await ingest({
+        companyId: context.companyId,
+        spaceSlug: activeSpaceSlug,
+        sourceType,
+        url: url.trim() || null,
+        title: resolvedTitle,
+        contents,
+      });
+      const spaceLabel = activeSpace?.displayName ?? activeSpaceSlug;
+      toast({ tone: "success", title: `Source captured into ${spaceLabel}`, body: `Operation issue created. Check History to inspect.` });
+      setUrl("");
+      setPasted("");
+      setTitle("");
+      refreshOverview();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setErrorMsg(message);
+      toast({ tone: "error", title: "Ingest failed", body: message });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const spaceLabel = activeSpace?.displayName ?? activeSpaceSlug;
+
+  return (
+    <div style={{ flex: 1, minHeight: isMobile ? "auto" : 0, minWidth: 0, overflow: isMobile ? "visible" : "auto" }}>
+      <div style={{
+        padding: isMobile ? "16px" : "24px 28px",
+        maxWidth: 920,
+        minWidth: 0,
+      }}>
+        <div style={{ marginBottom: 4, fontSize: 11, fontWeight: 600, letterSpacing: "0.04em", textTransform: "uppercase", color: tokens.muted }}>Add Content</div>
+        <h2 style={{ margin: "0 0 6px", fontSize: 18, fontWeight: 650 }}>Capture into <span style={{ color: tokens.fg }}>{spaceLabel}</span></h2>
+        <Tiny style={{ marginBottom: 18 }}>
+          Each capture queues an ingest operation scoped to <Mono>{activeSpaceSlug}</Mono>. Files land in that space's <Mono>raw/</Mono> folder and the Wiki Maintainer proposes a patch.
+        </Tiny>
+        <div style={{ display: "grid", gap: 14, marginBottom: 18 }}>
+          <SpacePicker
+            spaces={spaces}
+            activeSpaceSlug={activeSpaceSlug}
+            loading={spacesQuery.loading}
+            error={spacesQuery.error?.message ?? null}
+            isOpen={spaceMenuOpen}
+            onToggle={() => setSpaceMenuOpen((v) => !v)}
+            onClose={() => setSpaceMenuOpen(false)}
+            onSelect={(slug) => {
+              setSpaceMenuOpen(false);
+              hostNavigation.navigate(buildSectionHref("ingest", slug));
+            }}
+            onCreate={() => {
+              setSpaceMenuOpen(false);
+              setCreateOpen(true);
+            }}
+          />
+          <div>
+            <label style={{ fontSize: 11, color: tokens.muted, display: "block", marginBottom: 6 }}>Drop files anywhere on this page</label>
+            <div style={{
+              minHeight: isMobile ? 180 : 230,
+              border: `1.5px dashed ${tokens.pluginBorder}`,
+              borderRadius: 8,
+              padding: isMobile ? 20 : 30,
+              display: "flex",
+              flexDirection: "column",
+              justifyContent: "center",
+              alignItems: "center",
+              gap: 10,
+              textAlign: "center",
+              color: tokens.muted,
+              background: tokens.pluginBg,
+            }}>
+              <div style={{ display: "inline-flex", alignItems: "center", justifyContent: "center", width: 46, height: 46, borderRadius: 8, background: tokens.card, color: tokens.pluginFg, border: `1px solid ${tokens.pluginBorder}` }}>
+                <DownloadCloudIcon size={24} />
+              </div>
+              <div style={{ fontSize: 16, fontWeight: 650, color: tokens.fg }}>Drop source files here</div>
+              <Tiny>Review staged files before queueing maintainer tasks.</Tiny>
+            </div>
+          </div>
+          <div data-testid="llm-wiki-ingest-manual-separator" aria-hidden="true" style={{ display: "flex", alignItems: "center", gap: 12, color: tokens.muted, fontSize: 11, fontWeight: 650, textTransform: "uppercase", letterSpacing: "0.04em" }}>
+            <span style={{ height: 1, flex: 1, background: tokens.border }} />
+            <span>or</span>
+            <span style={{ height: 1, flex: 1, background: tokens.border }} />
+          </div>
+          <div>
+            <label style={{ fontSize: 11, color: tokens.muted, display: "block", marginBottom: 4 }}>Source title (optional)</label>
+            <TextInput value={title} onChange={(e) => setTitle(e.target.value)} placeholder="e.g. Karpathy LLM Wiki gist" />
+          </div>
+          <div>
+            <label style={{ fontSize: 11, color: tokens.muted, display: "block", marginBottom: 4 }}>URL</label>
+            <TextInput value={url} onChange={(e) => setUrl(e.target.value)} placeholder="https://example.com/article" />
+          </div>
+          <div>
+            <label style={{ fontSize: 11, color: tokens.muted, display: "block", marginBottom: 4 }}>Paste markdown / text</label>
+            <TextArea value={pasted} onChange={(e) => setPasted(e.target.value)} placeholder="Paste source content…" rows={8} />
+          </div>
+        </div>
+        <div style={{ display: "flex", gap: 8, alignItems: "center", flexWrap: "wrap" }}>
+          <Button variant="primary" onClick={submit} disabled={!canSubmit} loading={busy}>+ Capture & ingest</Button>
+        </div>
+        {errorMsg ? <div style={{ marginTop: 14 }}><Callout tone="danger">{errorMsg}</Callout></div> : null}
+      </div>
+      {createOpen && context.companyId ? (
+        <CreateSpaceModal
+          companyId={context.companyId}
+          existingSlugs={new Set(spaces.map((s) => s.slug))}
+          onClose={() => setCreateOpen(false)}
+          onCreated={(space) => {
+            setCreateOpen(false);
+            spacesQuery.refresh();
+            hostNavigation.navigate(buildSectionHref("ingest", space.slug));
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function SpacePicker({
+  spaces,
+  activeSpaceSlug,
+  loading,
+  error,
+  isOpen,
+  onToggle,
+  onClose,
+  onSelect,
+  onCreate,
+}: {
+  spaces: WikiSpace[];
+  activeSpaceSlug: string;
+  loading: boolean;
+  error: string | null;
+  isOpen: boolean;
+  onToggle: () => void;
+  onClose: () => void;
+  onSelect: (slug: string) => void;
+  onCreate: () => void;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const active = spaces.find((s) => s.slug === activeSpaceSlug);
+  useEffect(() => {
+    if (!isOpen) return;
+    const handler = (event: MouseEvent) => {
+      if (!ref.current) return;
+      if (event.target instanceof Node && ref.current.contains(event.target)) return;
+      onClose();
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [isOpen, onClose]);
+  return (
+    <div ref={ref} style={{ position: "relative" }}>
+      <label style={{ fontSize: 11, color: tokens.muted, display: "block", marginBottom: 4 }}>Space</label>
+      <button
+        type="button"
+        onClick={onToggle}
+        aria-haspopup="listbox"
+        aria-expanded={isOpen}
+        style={{
+          width: "100%",
+          display: "flex",
+          alignItems: "center",
+          gap: 8,
+          background: "oklch(0.2 0 0)",
+          border: `1px solid ${tokens.border}`,
+          borderRadius: 6,
+          padding: "8px 10px",
+          color: tokens.fg,
+          fontFamily: fontStack,
+          fontSize: 13,
+          cursor: "pointer",
+          textAlign: "left",
+        }}
+      >
+        <FolderIcon size={14} />
+        <span style={{ flex: 1, fontWeight: 600 }}>{active?.displayName ?? activeSpaceSlug}</span>
+        {active ? (
+          <Badge tone="default" style={{ fontSize: 10, padding: "0 6px" }}>{active.accessScope}</Badge>
+        ) : null}
+        <ChevronDownIcon size={14} />
+      </button>
+      <div style={{ marginTop: 6, fontSize: 11, color: tokens.muted, lineHeight: 1.4 }}>
+        Defaults to the space you opened. Switching now re-routes the page so deep links carry the destination.
+      </div>
+      {isOpen ? (
+        <div
+          role="listbox"
+          style={{
+            position: "absolute",
+            top: "calc(100% + 4px)",
+            left: 0,
+            right: 0,
+            zIndex: 25,
+            background: tokens.card,
+            border: `1px solid ${tokens.border}`,
+            borderRadius: 8,
+            boxShadow: "0 16px 40px rgba(0,0,0,0.45)",
+            padding: 4,
+            maxHeight: 320,
+            overflowY: "auto",
+          }}
+        >
+          {error ? <div style={{ padding: 10, fontSize: 12, color: tokens.statusBlocked }}>{error}</div> : null}
+          {loading ? <div style={{ padding: 10 }}><Tiny>Loading spaces…</Tiny></div> : null}
+          {spaces.map((space) => (
+            <button
+              key={space.slug}
+              type="button"
+              role="option"
+              aria-selected={space.slug === activeSpaceSlug}
+              onClick={() => onSelect(space.slug)}
+              style={{
+                width: "100%",
+                display: "flex",
+                alignItems: "center",
+                gap: 8,
+                padding: "8px 10px",
+                background: space.slug === activeSpaceSlug ? tokens.accent : "transparent",
+                border: "none",
+                borderRadius: 6,
+                color: tokens.fg,
+                fontSize: 13,
+                fontFamily: fontStack,
+                cursor: "pointer",
+                textAlign: "left",
+              }}
+            >
+              <FolderIcon size={14} />
+              <span style={{ flex: 1, fontWeight: 600 }}>{space.displayName}</span>
+              <span style={{ fontSize: 10, color: tokens.muted, fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace" }}>{space.slug}</span>
+            </button>
+          ))}
+          <SpaceMenuDivider />
+          <button
+            type="button"
+            onClick={onCreate}
+            style={{
+              width: "100%",
+              display: "flex",
+              alignItems: "center",
+              gap: 8,
+              padding: "8px 10px",
+              background: "transparent",
+              border: "none",
+              borderRadius: 6,
+              color: "oklch(0.78 0.13 250)",
+              fontSize: 13,
+              fontFamily: fontStack,
+              cursor: "pointer",
+              textAlign: "left",
+              fontWeight: 600,
+            }}
+          >
+            <PlusIcon size={14} />
+            <span>New shared space…</span>
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function OperationCard({ op }: { op: WikiOperationRow }) {
+  return (
+    <Card>
+      <div style={{ padding: "12px 14px" }}>
+        <div style={{ display: "flex", gap: 8, alignItems: "center", flexWrap: "wrap", minWidth: 0 }}>
+          <StatusIcon status={op.status} />
+          <strong style={{ flex: "1 1 180px", minWidth: 0, fontSize: 13, overflowWrap: "anywhere" }}>{op.hiddenIssueTitle ?? `LLM Wiki ${op.operationType}`}</strong>
+          <Badge tone={statusTone(op.status)} style={{ marginLeft: "auto" }}>{op.status}</Badge>
+        </div>
+        <Tiny style={{ marginTop: 4 }}>
+          {op.operationType.toUpperCase()} · started {formatTime(op.createdAt)} · op-{op.id.slice(0, 6)}
+          {op.hiddenIssueIdentifier ? <> · <Mono>{op.hiddenIssueIdentifier}</Mono></> : null}
+        </Tiny>
+        {Array.isArray(op.warnings) && op.warnings.length > 0 ? (
+          <Tiny style={{ marginTop: 4, color: tokens.statusBlocked }}>
+            {op.warnings.length} warning{op.warnings.length === 1 ? "" : "s"}
+          </Tiny>
+        ) : null}
+      </div>
+    </Card>
+  );
+}
+
+function statusTone(status: string): Tone {
+  if (status === "done") return "done";
+  if (status === "running" || status === "in_progress") return "running";
+  if (status === "blocked" || status === "failed") return "failed";
+  if (status === "queued" || status === "todo") return "todo";
+  if (status === "paused") return "paused";
+  return "default";
+}
+
+// ---------------------------------------------------------------------------
+// Ask tab.
+// ---------------------------------------------------------------------------
+
+type QueryThreadEntry = {
+  id: string;
+  prompt: string;
+  operationId: string | null;
+  querySessionId: string | null;
+  hiddenIssueIdentifier: string | null;
+  channel: string | null;
+  status: "queued" | "running" | "done" | "error";
+  createdAt: string;
+  answer: string;
+  errorMessage?: string;
+};
+
+type QueryStreamEvent = {
+  type: string;
+  operationId?: string;
+  querySessionId?: string;
+  message?: string | null;
+  payload?: Record<string, unknown> | null;
+  eventType?: string;
+  stream?: string | null;
+  answer?: string;
+};
+
+function QueryTab({ context, overview }: { context: { companyId: string | null }; overview: OverviewData }) {
+  const startQuery = usePluginAction("start-query");
+  const fileAsPage = usePluginAction("file-as-page");
+  const toast = usePluginToast();
+  const { pathname } = useHostLocation();
+  const activeSpaceSlug = useMemo(() => readActiveSpaceSlugFromLocation(pathname), [pathname]);
+  const isMobile = useIsMobileLayout();
+  const [thread, setThread] = useState<QueryThreadEntry[]>([]);
+  const [prompt, setPrompt] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [filePath, setFilePath] = useState("wiki/concepts/new-page.md");
+  const [fileBody, setFileBody] = useState("");
+  const [filing, setFiling] = useState<string | null>(null);
+  const fileSource = useMemo(() => {
+    for (let i = thread.length - 1; i >= 0; i -= 1) {
+      const entry = thread[i];
+      if (entry.answer.trim()) return entry;
+    }
+    return null;
+  }, [thread]);
+
+  const activeEntry = useMemo(() => {
+    for (let i = thread.length - 1; i >= 0; i -= 1) {
+      const entry = thread[i];
+      if (entry.status === "running" || entry.status === "queued") return entry;
+    }
+    return null;
+  }, [thread]);
+
+  const stream = usePluginStream<QueryStreamEvent>(activeEntry?.channel ?? "llm-wiki:idle", {
+    companyId: context.companyId ?? undefined,
+  });
+
+  useEffect(() => {
+    if (!activeEntry || !stream.lastEvent) return;
+    const event = stream.lastEvent;
+    setThread((prev) => prev.map((entry) => {
+      if (entry.id !== activeEntry.id) return entry;
+      if (event.type === "agent.event" && event.eventType === "chunk" && event.message && event.stream !== "stderr") {
+        return { ...entry, answer: entry.answer + event.message, status: "running" };
+      }
+      if (event.type === "query.done") {
+        return { ...entry, status: "done", answer: event.answer ?? entry.answer };
+      }
+      if (event.type === "query.error") {
+        return { ...entry, status: "error", errorMessage: event.message ?? "agent session error" };
+      }
+      return entry;
+    }));
+    if (event.type === "query.done" && event.answer && !fileBody.trim()) {
+      setFileBody(event.answer);
+    }
+  }, [fileBody, stream.lastEvent, activeEntry?.id]);
+
+  async function send() {
+    if (!context.companyId || !prompt.trim()) return;
+    setBusy(true);
+    const entryId = `q-${Date.now()}`;
+    setThread((prev) => [...prev, {
+      id: entryId,
+      prompt: prompt.trim(),
+      operationId: null,
+      querySessionId: null,
+      hiddenIssueIdentifier: null,
+      channel: null,
+      status: "queued",
+      createdAt: new Date().toISOString(),
+      answer: "",
+    }]);
+    try {
+      const res = await startQuery({ companyId: context.companyId, spaceSlug: activeSpaceSlug, question: prompt.trim() });
+      const result = res as {
+        operationId: string;
+        querySessionId?: string;
+        channel?: string;
+        issue?: { identifier?: string | null };
+      };
+      setThread((prev) => prev.map((entry) =>
+        entry.id === entryId ? {
+          ...entry,
+          operationId: result.operationId,
+          querySessionId: result.querySessionId ?? result.operationId,
+          hiddenIssueIdentifier: result.issue?.identifier ?? null,
+          channel: result.channel ?? `llm-wiki:query:${result.operationId}`,
+          status: "running",
+        } : entry,
+      ));
+      setPrompt("");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setThread((prev) => prev.map((entry) =>
+        entry.id === entryId ? { ...entry, status: "error", errorMessage: message } : entry,
+      ));
+      toast({ tone: "error", title: "Ask failed", body: message });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function fileAnswer(entry?: QueryThreadEntry) {
+    const source = entry ?? fileSource;
+    const answer = fileBody.trim() || source?.answer.trim() || "";
+    if (!context.companyId || !filePath.trim() || !answer) return;
+    setFiling(source?.id ?? "manual");
+    try {
+      await fileAsPage({
+        companyId: context.companyId,
+        wikiId: overview.wikiId,
+        spaceSlug: activeSpaceSlug,
+        path: filePath.trim(),
+        question: source?.prompt,
+        answer,
+        querySessionId: source?.querySessionId,
+      });
+      toast({ tone: "success", title: "Answer filed", body: `Wrote ${filePath.trim()} and recorded a file-as-page task.` });
+      setFileBody("");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      toast({ tone: "error", title: "Could not file answer", body: message });
+    } finally {
+      setFiling(null);
+    }
+  }
+
+  return (
+    <div style={{ display: "flex", flexDirection: isMobile ? "column" : "row", flex: 1, minHeight: isMobile ? "auto" : 0, minWidth: 0 }}>
+      <div style={{ flex: 1, padding: isMobile ? "16px" : "24px 28px", overflow: isMobile ? "visible" : "auto", minWidth: 0 }}>
+        {thread.length === 0 ? (
+          <Callout>
+            Ask the wiki anything. Each question initiates a task assigned to the Wiki Maintainer. The answer streams below; you can promote useful answers into a wiki page.
+          </Callout>
+        ) : null}
+        <div style={{ display: "grid", gap: 22, marginTop: 18 }}>
+          {thread.map((entry) => (
+            <div key={entry.id}>
+              <Tiny style={{ marginBottom: 4 }}>You · {formatTime(entry.createdAt)}</Tiny>
+              <div style={{ background: tokens.card, border: `1px solid ${tokens.border}`, padding: "10px 12px", borderRadius: 8, fontSize: 13 }}>{entry.prompt}</div>
+              <Tiny style={{ marginTop: 8 }}>
+                Wiki Maintainer · {entry.status}
+                {entry.hiddenIssueIdentifier ? <> · <Mono>{entry.hiddenIssueIdentifier}</Mono></> : null}
+              </Tiny>
+              {entry.status === "error" ? (
+                <div style={{ marginTop: 6 }}><Callout tone="danger">{entry.errorMessage}</Callout></div>
+              ) : (
+                <pre style={{
+                  margin: "8px 0 0",
+                  whiteSpace: "pre-wrap",
+                  wordBreak: "break-word",
+                  fontFamily: "ui-sans-serif, system-ui, sans-serif",
+                  fontSize: 13,
+                  lineHeight: 1.65,
+                  color: tokens.fg,
+                }}>{entry.answer || (entry.status === "running" ? "Streaming…" : "")}</pre>
+              )}
+              {entry.answer.trim() && entry.status === "done" ? (
+                <div style={{ marginTop: 10, border: `1px dashed ${tokens.border}`, borderRadius: 8, padding: "10px 12px" }}>
+                  <div style={{ display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
+                    <strong style={{ fontSize: 13 }}>📑 File this answer as a wiki page?</strong>
+                    <Tiny style={{ marginLeft: isMobile ? 0 : "auto", width: isMobile ? "100%" : undefined }}>Path: <Mono>{filePath}</Mono></Tiny>
+                  </div>
+                  <div style={{ display: "flex", gap: 6, marginTop: 8, alignItems: "center", flexWrap: "wrap" }}>
+                    <TextInput value={filePath} onChange={(e) => setFilePath(e.target.value)} style={{ maxWidth: isMobile ? "none" : 360 }} />
+                    <Button size="sm" variant="primary" onClick={() => fileAnswer(entry)} disabled={!filePath.trim()} loading={filing === entry.id}>Accept &amp; file</Button>
+                  </div>
+                </div>
+              ) : null}
+            </div>
+          ))}
+        </div>
+        <div style={{ borderTop: `1px solid ${tokens.border}`, paddingTop: 14, marginTop: 22 }}>
+          <TextArea value={prompt} onChange={(e) => setPrompt(e.target.value)} placeholder="Ask the wiki…" rows={3} />
+          <div style={{ display: "flex", gap: 6, marginTop: 8, alignItems: "center", flexWrap: "wrap" }}>
+            <Button variant="primary" size="sm" onClick={send} disabled={!prompt.trim()} loading={busy}>Send (⌘↵)</Button>
+            <Badge>Cite: wiki + raw</Badge>
+            <Badge>Max steps: 6</Badge>
+            <Tiny style={{ marginLeft: "auto" }}>Streamed via agent session · maintainer task</Tiny>
+          </div>
+        </div>
+      </div>
+      <aside style={{
+        width: isMobile ? "auto" : 320,
+        borderLeft: isMobile ? "none" : `1px solid ${tokens.border}`,
+        borderTop: isMobile ? `1px solid ${tokens.border}` : "none",
+        padding: isMobile ? "16px" : "18px 20px",
+        overflow: isMobile ? "visible" : "auto",
+        minWidth: 0,
+      }}>
+        <Tiny style={{ marginBottom: 8 }}>SESSION</Tiny>
+        <PropRow label="Wiki" value={overview.wikiId} />
+        <PropRow label="Project" value={overview.managedProject.details?.name ?? overview.managedProject.status} />
+        <PropRow label="Agent" value={overview.managedAgent.details?.name ?? overview.managedAgent.status} />
+        <PropRow label="Operations" value={overview.operationCount} />
+        <PropRow label="Stream" value={stream.connected ? "live" : stream.connecting ? "connecting…" : "idle"} />
+        <Divider />
+        <Tiny style={{ marginBottom: 8 }}>ASK PROMPT</Tiny>
+        <pre style={{ margin: 0, whiteSpace: "pre-wrap", fontFamily: "ui-monospace, monospace", fontSize: 12, color: tokens.muted }}>{overview.prompts.query}</pre>
+      </aside>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Lint tab.
+// ---------------------------------------------------------------------------
+
+function LintTab({ context, overview, refreshOverview }: { context: { companyId: string | null }; overview: OverviewData; refreshOverview: () => void }) {
+  const isMobile = useIsMobileLayout();
+  return (
+    <div style={{ flex: 1, minHeight: isMobile ? "auto" : 0, overflow: isMobile ? "visible" : "auto", padding: isMobile ? "16px" : "24px 28px", display: "grid", gap: isMobile ? 14 : 18, minWidth: 0 }}>
+      <LintPanelContent context={context} overview={overview} refreshOverview={refreshOverview} />
+    </div>
+  );
+}
+
+function SettingsLintPanel({ context }: { context: { companyId: string | null } }) {
+  const overview = useOverview(context.companyId);
+
+  if (overview.error) {
+    return <SettingsPanel title="Lint" badge={<HiddenOpBadge />} description="Run structural checks for orphan pages, missing backlinks, and stale provenance.">
+      <Callout tone="danger">LLM Wiki bridge error: {overview.error.message}</Callout>
+    </SettingsPanel>;
+  }
+
+  if (!overview.data) {
+    return <SettingsPanel title="Lint" badge={<HiddenOpBadge />} description="Run structural checks for orphan pages, missing backlinks, and stale provenance.">
+      <Tiny>Loading lint controls…</Tiny>
+    </SettingsPanel>;
+  }
+
+  return (
+    <SettingsPanel
+      title="Lint"
+      badge={<HiddenOpBadge />}
+      description="Run structural checks for orphan pages, missing backlinks, and stale provenance."
+    >
+      <LintPanelContent context={context} overview={overview.data} refreshOverview={overview.refresh} showHeading={false} />
+    </SettingsPanel>
+  );
+}
+
+function LintPanelContent({
+  context,
+  overview,
+  refreshOverview,
+  showHeading = true,
+}: {
+  context: { companyId: string | null };
+  overview: OverviewData;
+  refreshOverview: () => void;
+  showHeading?: boolean;
+}) {
+  const create = usePluginAction("create-operation");
+  const { pathname } = useHostLocation();
+  const activeSpaceSlug = useMemo(() => readActiveSpaceSlugFromLocation(pathname), [pathname]);
+  const operations = useOperations(context.companyId, { operationType: "lint", spaceSlug: activeSpaceSlug });
+  const toast = usePluginToast();
+  const isMobile = useIsMobileLayout();
+  const [busy, setBusy] = useState(false);
+
+  async function runLint() {
+    if (!context.companyId) return;
+    setBusy(true);
+    try {
+      await create({
+        companyId: context.companyId,
+        spaceSlug: activeSpaceSlug,
+        operationType: "lint",
+        title: `Run LLM Wiki lint · ${activeSpaceSlug}`,
+        prompt: overview.prompts.lint,
+      });
+      toast({ tone: "success", title: "Lint queued", body: "Lint runs as a Wiki Maintainer task. Findings will appear here once the run completes." });
+      operations.refresh();
+      refreshOverview();
+    } catch (err) {
+      toast({ tone: "error", title: "Could not run lint", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const recent = operations.data?.operations ?? [];
+  const latestDone = recent.find((op) => op.status === "done");
+  const findings = Array.isArray(latestDone?.warnings) ? (latestDone!.warnings as Record<string, unknown>[]) : [];
+  const counts = aggregateLintFindings(findings);
+
+  return (
+    <div style={{ display: "grid", gap: isMobile ? 14 : 18, minWidth: 0 }}>
+      <div style={{ display: "flex", gap: 12, alignItems: "center", flexWrap: "wrap" }}>
+        {showHeading ? <h2 style={{ margin: 0, fontSize: 16, fontWeight: 600 }}>Lint</h2> : null}
+        <Badge style={unfilledSurfaceStyle}>{recent.length} run{recent.length === 1 ? "" : "s"}</Badge>
+        <Button variant="primary" size="sm" onClick={runLint} loading={busy} style={{ marginLeft: isMobile ? 0 : "auto" }}>▶ Run lint now</Button>
+      </div>
+      <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(140px, 1fr))", gap: 12 }}>
+        <StatCard label="Findings" value={String(counts.total)} hint={latestDone ? `last run ${formatTime(latestDone.createdAt)}` : "no runs yet"} />
+        <StatCard label="Critical" value={String(counts.critical)} hint="contradictions / conflict" tone={counts.critical > 0 ? "danger" : undefined} />
+        <StatCard label="Orphans" value={String(counts.orphan)} hint="no inbound backlinks" />
+        <StatCard label="Stale" value={String(counts.stale)} hint="provenance > 30d" />
+        <StatCard label="Index drift" value={String(counts.index)} hint="wiki/index.md / wiki/log.md" />
+      </div>
+      <Card style={unfilledSurfaceStyle}>
+        <CardHeader title="Findings" badges={<HiddenOpBadge />} right={<Tiny>Lint runs as a Wiki Maintainer task. Critical findings can optionally open visible follow-up issues — toggle in Settings → Lint policy.</Tiny>} />
+        <CardBody padding={0}>
+          {findings.length === 0 ? (
+            <div style={{ padding: 16, color: tokens.muted, fontSize: 13 }}>
+              {latestDone ? "Latest lint run reported no findings." : "No completed lint runs yet. Use ▶ Run lint now to start one."}
+            </div>
+          ) : findings.map((f, idx) => {
+            const severityTone: Tone = f.severity === "critical" ? "failed" : f.severity === "orphan" ? "paused" : "default";
+            return (
+              <Row
+                key={idx}
+                primary={
+                  <span>
+                    <Badge tone={severityTone} style={severityTone === "default" ? unfilledSurfaceStyle : undefined}>
+                      {String(f.severity ?? "info")}
+                    </Badge>
+                    <span style={{ marginLeft: 8 }}>{String(f.message ?? f.title ?? "(no description)")}</span>
+                  </span>
+                }
+                secondary={f.path ? <Mono>{String(f.path)}</Mono> : null}
+              />
+            );
+          })}
+        </CardBody>
+      </Card>
+      <Card style={unfilledSurfaceStyle}>
+        <CardHeader title="Recent lint runs" />
+        <CardBody padding={0}>
+          {recent.length === 0 ? <div style={{ padding: 12, color: tokens.muted, fontSize: 13 }}>No lint runs yet.</div> : recent.map((op) => (
+            <Row
+              key={op.id}
+              primary={<><Mono>op-{op.id.slice(0, 6)}</Mono> {op.hiddenIssueTitle ?? "Wiki lint"}</>}
+              secondary={formatTime(op.createdAt)}
+              right={<Badge tone={statusTone(op.status)}>{op.status}</Badge>}
+            />
+          ))}
+        </CardBody>
+      </Card>
+    </div>
+  );
+}
+
+function StatCard({ label, value, hint, tone }: { label: string; value: string; hint?: string; tone?: "danger" | "warn" }) {
+  const palette = tone === "danger" ? { color: "oklch(0.7 0.2 25)" } : tone === "warn" ? { color: "oklch(0.85 0.1 70)" } : { color: tokens.fg };
+  return (
+    <Card style={{ ...unfilledSurfaceStyle, padding: 14 }}>
+      <Tiny>{label.toUpperCase()}</Tiny>
+      <div style={{ fontSize: 22, fontWeight: 700, marginTop: 4, ...palette }}>{value}</div>
+      {hint ? <Tiny style={{ marginTop: 2 }}>{hint}</Tiny> : null}
+    </Card>
+  );
+}
+
+function aggregateLintFindings(findings: Record<string, unknown>[]): { total: number; critical: number; orphan: number; stale: number; index: number } {
+  const counts = { total: findings.length, critical: 0, orphan: 0, stale: 0, index: 0 };
+  for (const f of findings) {
+    const sev = String(f.severity ?? "");
+    if (sev === "critical") counts.critical += 1;
+    else if (sev === "orphan") counts.orphan += 1;
+    else if (sev === "stale") counts.stale += 1;
+    else if (sev === "index") counts.index += 1;
+  }
+  return counts;
+}
+
+// ---------------------------------------------------------------------------
+// History tab: native Paperclip issue table for recent LLM Wiki operation
+// issues. Each plugin run is represented by an issue, so the standard issue
+// history view is the right surface here.
+// ---------------------------------------------------------------------------
+
+function formatCostCents(cents: number): string {
+  if (!Number.isFinite(cents) || cents <= 0) return "$0.00";
+  return `$${(cents / 100).toFixed(2)}`;
+}
+
+function formatTimestamp(value: string | null | undefined): string {
+  if (!value) return "—";
+  const ms = Date.parse(value);
+  if (!Number.isFinite(ms)) return "—";
+  return new Date(ms).toLocaleString(undefined, { month: "short", day: "2-digit", hour: "2-digit", minute: "2-digit" });
+}
+
+function runStatusTone(status: string): Tone {
+  if (status === "running") return "running";
+  if (status === "succeeded" || status === "completed" || status === "done") return "done";
+  if (status === "failed" || status === "refused_cost_cap") return "failed";
+  if (status === "review_required") return "in_review";
+  if (status === "paused") return "paused";
+  if (status === "source_ready" || status === "queued") return "queued";
+  return "default";
+}
+
+function runStatusLabel(status: string): string {
+  switch (status) {
+    case "review_required":
+      return "review required";
+    case "refused_cost_cap":
+      return "cost capped";
+    case "source_ready":
+      return "source ready";
+    default:
+      return status.replace(/_/g, " ");
+  }
+}
+
+function HistoryTab({ context, overview }: { context: { companyId: string | null; companyPrefix?: string | null }; overview: OverviewData }) {
+  const isMobile = useIsMobileLayout();
+  const projectId = overview.managedProject.projectId;
+  const originKindPrefix = `plugin:${PLUGIN_ID}:operation`;
+
+  if (!context.companyId) {
+    return <div style={{ padding: isMobile ? 16 : 24, flex: 1 }}><Callout>Choose a company to view LLM Wiki history.</Callout></div>;
+  }
+
+  if (!projectId) {
+    return (
+      <div style={{ padding: isMobile ? 16 : 24, flex: 1 }}>
+        <Callout tone="warn">The LLM Wiki operations project is not resolved yet. Reconcile the managed project in Settings, then history will show its issues here.</Callout>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ flex: 1, minHeight: isMobile ? "auto" : 0, overflow: isMobile ? "visible" : "auto", padding: isMobile ? 12 : 0, minWidth: 0 }}>
+      <PluginIssuesList
+        companyId={context.companyId}
+        projectId={projectId}
+        filters={{ originKindPrefix }}
+        viewStateKey="paperclip:llm-wiki-history-issues-view"
+        searchWithinLoadedIssues
+      />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Settings (tab) and the standalone host SettingsPage share this body.
+// ---------------------------------------------------------------------------
+
+function SettingsTab({ context, initialSection = "root" }: { context: { companyId: string | null; companyPrefix?: string | null }; initialSection?: SettingsSectionKey }) {
+  const isMobile = useIsMobileLayout();
+  return (
+    <div style={{ flex: 1, minHeight: isMobile ? "auto" : 0, overflow: isMobile ? "visible" : "auto", padding: isMobile ? "16px" : "24px 28px", minWidth: 0 }}>
+      <SettingsBody context={context} initialSection={initialSection} />
+    </div>
+  );
+}
+
+const ROUTINE_FALLBACKS: Record<string, { title: string; cron: string }> = {
+  "cursor-window-processing": { title: "Process LLM Wiki updates", cron: "0 */6 * * *" },
+  "nightly-wiki-lint": { title: "Run LLM Wiki lint", cron: "0 3 * * *" },
+  "index-refresh": { title: "Refresh LLM Wiki index", cron: "0 * * * *" },
+};
+
+const MANAGED_SKILL_LABELS: Record<string, string> = {
+  "wiki-maintainer": "LLM Wiki Maintainer",
+  "wiki-ingest": "Wiki Ingest",
+  "wiki-query": "Wiki Query",
+  "wiki-lint": "Wiki Lint",
+  "paperclip-distill": "Paperclip Distill",
+  "index-refresh": "Index Refresh",
+};
+
+function routineFallbackFor(routine: ManagedRoutine) {
+  const key = routine.resourceKey?.split(":").pop() ?? "";
+  return ROUTINE_FALLBACKS[key] ?? { title: routine.resourceKey ?? "Managed routine", cron: "—" };
+}
+
+function managedRoutineStatus(routine: ManagedRoutine) {
+  return routine.routine?.status ?? routine.details?.status ?? (routine.routineId ? "paused" : "missing");
+}
+
+type RoutineHealthItem = {
+  label: string;
+  ok: boolean;
+  detail: string;
+};
+
+function routineResourceKey(routine: ManagedRoutine) {
+  return routine.resourceKey?.split(":").pop() ?? "";
+}
+
+function managedAgentIsReady(resource: ManagedAgent) {
+  return resource.source === "managed" && Boolean(resource.agentId);
+}
+
+function managedProjectIsReady(resource: ManagedProject) {
+  return resource.source === "managed" && Boolean(resource.projectId);
+}
+
+function managedSkillIsReady(resource: ManagedSkill) {
+  return resource.status !== "missing" && Boolean(resource.skillId);
+}
+
+function managedResourceKey(resourceKey?: string | null) {
+  return resourceKey?.split(":").pop() ?? "";
+}
+
+function skillLabel(resource: ManagedSkill) {
+  const declaredLabel = MANAGED_SKILL_LABELS[managedResourceKey(resource.resourceKey)];
+  return declaredLabel ?? resource.details?.name ?? resource.skill?.name ?? "Managed skill";
+}
+
+function buildAgentHealthItems(managedAgent: ManagedAgent): RoutineHealthItem[] {
+  const agentName = managedAgent.details?.name ?? "Wiki Maintainer";
+  return [{
+    label: agentName,
+    ok: managedAgentIsReady(managedAgent) && !managedAgent.defaultDrift?.changedFiles.length,
+    detail: managedAgent.source === "managed"
+      ? managedAgent.defaultDrift?.changedFiles.length
+        ? `The Wiki Maintainer instructions differ from the plugin default: ${managedAgent.defaultDrift.changedFiles.join(", ")}.`
+        : "The plugin-managed Wiki Maintainer exists with current default instructions."
+      : "The settings page is using a selected maintainer instead of the plugin-managed Wiki Maintainer.",
+  }];
+}
+
+function buildProjectHealthItems(managedProject: ManagedProject): RoutineHealthItem[] {
+  const projectName = managedProject.details?.name ?? "LLM Wiki";
+  return [{
+    label: projectName,
+    ok: managedProjectIsReady(managedProject),
+    detail: managedProject.source === "managed"
+      ? "The plugin-managed LLM Wiki project exists."
+      : "The settings page is using a selected project instead of the plugin-managed LLM Wiki project.",
+  }];
+}
+
+function buildSkillHealthItems(skills: ManagedSkill[]): RoutineHealthItem[] {
+  if (skills.length === 0) {
+    return [{
+      label: "Managed skill",
+      ok: false,
+      detail: "No plugin-managed skills are installed in the company skill library.",
+    }];
+  }
+  return skills.map((skill) => ({
+    label: skillLabel(skill),
+    ok: managedSkillIsReady(skill) && !skill.defaultDrift?.changedFiles.length,
+    detail: managedSkillIsReady(skill)
+      ? skill.defaultDrift?.changedFiles.length
+        ? `${skillLabel(skill)} differs from the plugin default: ${skill.defaultDrift.changedFiles.join(", ")}.`
+        : `${skillLabel(skill)} is installed in the company skill library.`
+      : `${skillLabel(skill)} is not installed in the company skill library.`,
+  }));
+}
+
+function buildRoutineHealthItems(
+  routines: ManagedRoutine[],
+  managedAgent: ManagedAgent,
+  managedProject: ManagedProject,
+): RoutineHealthItem[] {
+  const routineByKey = new Map(routines.map((routine) => [routineResourceKey(routine), routine]));
+  const expectedAgentId = managedAgent.source === "managed" ? managedAgent.agentId ?? null : null;
+  const expectedProjectId = managedProject.source === "managed" ? managedProject.projectId ?? null : null;
+  const items: RoutineHealthItem[] = [];
+
+  for (const [key, fallback] of Object.entries(ROUTINE_FALLBACKS)) {
+    const routine = routineByKey.get(key);
+    const routineAgentId = routine?.routine?.assigneeAgentId ?? null;
+    const routineProjectId = routine?.routine?.projectId ?? null;
+    const missingRefs = routine?.missingRefs ?? [];
+    const missing = !routine?.routineId || !routine.routine;
+    const wrongAgent = Boolean(expectedAgentId && routineAgentId && routineAgentId !== expectedAgentId);
+    const wrongProject = Boolean(expectedProjectId && routineProjectId && routineProjectId !== expectedProjectId);
+    const missingAgent = Boolean(expectedAgentId && !routineAgentId);
+    const missingProject = Boolean(expectedProjectId && !routineProjectId);
+    const blockedByManagedResources = !expectedAgentId || !expectedProjectId;
+    const ok = Boolean(routine && !missing && missingRefs.length === 0 && !wrongAgent && !wrongProject && !missingAgent && !missingProject && !blockedByManagedResources);
+    let detail = `${fallback.title} is installed with the Wiki Maintainer and LLM Wiki project.`;
+    if (missing) {
+      detail = `${fallback.title} is not installed.`;
+    } else if (missingRefs.length > 0) {
+      detail = `${fallback.title} cannot resolve ${missingRefs.map((ref) => `${ref.resourceKind}:${ref.resourceKey}`).join(", ")}.`;
+    } else if (blockedByManagedResources) {
+      detail = `${fallback.title} cannot be validated until the managed agent and project are restored.`;
+    } else if (wrongAgent || missingAgent) {
+      detail = `${fallback.title} is not assigned to the Wiki Maintainer.`;
+    } else if (wrongProject || missingProject) {
+      detail = `${fallback.title} is not attached to the LLM Wiki project.`;
+    }
+    items.push({ label: fallback.title, ok, detail });
+  }
+
+  return items;
+}
+
+function RoutineHealthChecklist({ items }: { items: RoutineHealthItem[] }) {
+  return (
+    <ManagedResourceHealthChecklist
+      items={items}
+      ariaLabel="Wiki routines health checklist"
+      heading="Routine health"
+    />
+  );
+}
+
+function ManagedResourceHealthChecklist({
+  items,
+  ariaLabel,
+  heading,
+}: {
+  items: RoutineHealthItem[];
+  ariaLabel: string;
+  heading: string;
+}) {
+  return (
+    <div style={{ display: "grid", gap: 8 }} aria-label={ariaLabel}>
+      <div style={{ fontSize: 12, fontWeight: 650, color: tokens.muted }}>{heading}</div>
+      <div role="list" style={{ position: "relative", display: "grid", gap: 0, padding: "2px 0" }}>
+        {items.length > 1 ? (
+          <span
+            aria-hidden
+            style={{
+              position: "absolute",
+              left: 8,
+              top: 12,
+              bottom: 12,
+              width: 1,
+              background: "oklch(0.38 0.09 145)",
+            }}
+          />
+        ) : null}
+        {items.map((item) => (
+          <div
+            key={item.label}
+            role="listitem"
+            title={item.detail}
+            style={{
+              display: "grid",
+              gridTemplateColumns: "18px minmax(0, 1fr)",
+              alignItems: "center",
+              gap: 10,
+              padding: "7px 0",
+              minWidth: 0,
+            }}
+          >
+            <span style={{ display: "inline-flex", justifyContent: "center", position: "relative", zIndex: 1, background: tokens.bg }}>
+              <StatusIcon status={item.ok ? "done" : "blocked"} />
+            </span>
+            <span style={{ fontSize: 13, fontWeight: 600, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", color: item.ok ? tokens.fg : "oklch(0.85 0.1 70)" }}>
+              {item.label}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function SkillHealthChecklist({ items }: { items: RoutineHealthItem[] }) {
+  return (
+    <ManagedResourceHealthChecklist
+      items={items}
+      ariaLabel="Wiki skills health checklist"
+      heading="Skill health"
+    />
+  );
+}
+
+type SettingsSectionKey = "root" | "spaces" | "distillation" | "routines" | "lint" | "events";
+
+const SETTINGS_SECTIONS: ReadonlyArray<{
+  key: SettingsSectionKey;
+  label: string;
+  description: string;
+}> = [
+  { key: "root", label: "Setup", description: "" },
+  { key: "spaces", label: "Spaces", description: "Destination spaces - folders, slugs, and folder health. Per-space Paperclip indexing is not configurable yet." },
+  { key: "distillation", label: "Distillation", description: "Paperclip -> default space. Cursors, caps, and routines for the company-wide distillation pipeline." },
+  { key: "routines", label: "Managed Routines", description: "Scheduled wiki maintenance." },
+  { key: "lint", label: "Lint", description: "Run checks and review wiki health findings." },
+  { key: "events", label: "Ingestion Settings", description: "Paperclip event capture into the default space (issues, comments, documents)." },
+];
+
+function SettingsSectionButton({
+  section,
+  active,
+  onSelect,
+}: {
+  section: (typeof SETTINGS_SECTIONS)[number];
+  active: boolean;
+  onSelect: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      aria-current={active ? "page" : undefined}
+      onClick={onSelect}
+      style={{
+        width: "100%",
+        border: `1px solid ${active ? tokens.border : "transparent"}`,
+        borderRadius: 6,
+        background: "transparent",
+        color: active ? tokens.fg : tokens.muted,
+        cursor: "pointer",
+        display: "grid",
+        gap: 2,
+        padding: "8px 10px",
+        textAlign: "left",
+        fontFamily: fontStack,
+      }}
+    >
+      <span style={{ fontSize: 13, fontWeight: 600, lineHeight: 1.3 }}>{section.label}</span>
+      {section.description ? (
+        <span style={{ fontSize: 11, lineHeight: 1.35, overflowWrap: "anywhere" }}>{section.description}</span>
+      ) : null}
+    </button>
+  );
+}
+
+function SettingsPanel({
+  title,
+  badge,
+  description,
+  children,
+}: {
+  title: ReactNode;
+  badge?: ReactNode;
+  description?: ReactNode;
+  children: ReactNode;
+}) {
+  return (
+    <section style={{ display: "grid", gap: 14, minWidth: 0 }}>
+      <header style={{ display: "grid", gap: 6, minWidth: 0 }}>
+        <div style={{ display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap", minWidth: 0 }}>
+          <h2 style={{ margin: 0, fontSize: 17, fontWeight: 650, overflowWrap: "anywhere" }}>{title}</h2>
+          {badge}
+        </div>
+        {description ? <Tiny>{description}</Tiny> : null}
+      </header>
+      <div style={{ minWidth: 0 }}>{children}</div>
+    </section>
+  );
+}
+
+function SetupSection({ title, children, separated = false }: { title: ReactNode; children: ReactNode; separated?: boolean }) {
+  return (
+    <section style={{ display: "grid", gap: 12, minWidth: 0, paddingTop: separated ? 22 : 0, borderTop: separated ? `1px solid ${tokens.border}` : "none" }}>
+      <h2 style={{ margin: 0, fontSize: 16, fontWeight: 650 }}>{title}</h2>
+      <div style={{ minWidth: 0 }}>{children}</div>
+    </section>
+  );
+}
+
+type PathPlatform = "mac" | "windows" | "linux";
+
+const PATH_PLATFORM_LABELS: Record<PathPlatform, string> = {
+  mac: "macOS",
+  windows: "Windows",
+  linux: "Linux",
+};
+
+const PATH_PLATFORM_STEPS: Record<PathPlatform, string[]> = {
+  mac: [
+    "Open Finder and navigate to the folder.",
+    "Control-click the folder.",
+    "Hold Option, choose Copy as Pathname, then paste it here.",
+  ],
+  windows: [
+    "Open File Explorer and navigate to the folder.",
+    "Click the address bar to reveal the full path.",
+    "Copy the path and paste it here.",
+  ],
+  linux: [
+    "Open a terminal in the directory.",
+    "Run pwd to print the full path.",
+    "Copy the output and paste it here.",
+  ],
+};
+
+function detectPathPlatform(): PathPlatform {
+  if (typeof navigator === "undefined") return "mac";
+  const agent = navigator.userAgent.toLowerCase();
+  if (agent.includes("win")) return "windows";
+  if (agent.includes("linux")) return "linux";
+  return "mac";
+}
+
+function PathInstructionsDialog({ open, onClose }: { open: boolean; onClose: () => void }) {
+  const [platform, setPlatform] = useState<PathPlatform>(detectPathPlatform);
+
+  useEffect(() => {
+    if (!open) return;
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") onClose();
+    }
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [onClose, open]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      role="presentation"
+      onClick={onClose}
+      style={{
+        position: "fixed",
+        inset: 0,
+        zIndex: 50,
+        background: "rgba(0, 0, 0, 0.48)",
+        display: "grid",
+        placeItems: "center",
+        padding: 18,
+      }}
+    >
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="wiki-path-help-title"
+        onClick={(event) => event.stopPropagation()}
+        style={{
+          width: "min(460px, 100%)",
+          border: `1px solid ${tokens.border}`,
+          borderRadius: 8,
+          background: tokens.card,
+          color: tokens.fg,
+          boxShadow: "0 24px 70px rgba(0, 0, 0, 0.45)",
+          padding: 18,
+          display: "grid",
+          gap: 14,
+        }}
+      >
+        <div style={{ display: "flex", justifyContent: "space-between", gap: 12, alignItems: "start" }}>
+          <div style={{ display: "grid", gap: 4 }}>
+            <h3 id="wiki-path-help-title" style={{ margin: 0, fontSize: 15, fontWeight: 650 }}>Get a full folder path</h3>
+            <Tiny>Paste an absolute path such as <Mono>/Users/you/company-wiki</Mono>.</Tiny>
+          </div>
+          <Button size="sm" variant="ghost" onClick={onClose} title="Close path help">Close</Button>
+        </div>
+        <div style={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 4, border: `1px solid ${tokens.border}`, borderRadius: 7, padding: 3 }}>
+          {(Object.keys(PATH_PLATFORM_LABELS) as PathPlatform[]).map((key) => (
+            <button
+              key={key}
+              type="button"
+              onClick={() => setPlatform(key)}
+              style={{
+                border: 0,
+                borderRadius: 5,
+                background: key === platform ? tokens.accent : "transparent",
+                color: key === platform ? tokens.fg : tokens.muted,
+                padding: "6px 8px",
+                cursor: "pointer",
+                fontSize: 12,
+                fontFamily: fontStack,
+              }}
+            >
+              {PATH_PLATFORM_LABELS[key]}
+            </button>
+          ))}
+        </div>
+        <ol style={{ margin: 0, paddingLeft: 20, display: "grid", gap: 8, fontSize: 13, lineHeight: 1.45 }}>
+          {PATH_PLATFORM_STEPS[platform].map((step) => <li key={step}>{step}</li>)}
+        </ol>
+      </div>
+    </div>
+  );
+}
+
+function FolderPathPicker({
+  value,
+  onChange,
+  onApply,
+  applyLabel,
+  busy,
+  disabled,
+  onRefresh,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  onApply: () => void;
+  applyLabel: string;
+  busy?: boolean;
+  disabled?: boolean;
+  onRefresh?: () => void;
+}) {
+  const [helpOpen, setHelpOpen] = useState(false);
+
+  return (
+    <div style={{
+      border: `1px solid ${tokens.border}`,
+      borderRadius: 8,
+      background: "oklch(0.18 0 0)",
+      overflow: "hidden",
+      minWidth: 0,
+    }}>
+      <div style={{ display: "flex", alignItems: "center", gap: 10, padding: "10px 12px", borderBottom: `1px solid ${tokens.border}` }}>
+        <span aria-hidden style={{
+          width: 28,
+          height: 28,
+          borderRadius: 7,
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          background: tokens.accent,
+          color: tokens.pluginFg,
+          flexShrink: 0,
+        }}>
+          <FolderOpenIcon />
+        </span>
+        <div style={{ display: "grid", gap: 2, minWidth: 0 }}>
+          <span style={{ fontSize: 13, fontWeight: 650 }}>Local wiki folder</span>
+          <Tiny>Absolute path on this machine</Tiny>
+        </div>
+      </div>
+      <div style={{ display: "flex", gap: 8, padding: 12, alignItems: "center", flexWrap: "wrap" }}>
+        <TextInput
+          value={value}
+          onChange={(event) => onChange(event.target.value)}
+          placeholder="/absolute/path/to/wiki-root"
+          style={{ flex: "1 1 320px", fontFamily: "ui-monospace, SFMono-Regular, monospace" }}
+        />
+        <Button size="sm" onClick={() => setHelpOpen(true)}><FolderOpenIcon size={13} /> Choose</Button>
+        <Button variant="primary" size="sm" onClick={onApply} loading={busy} disabled={disabled || !value.trim()}>{applyLabel}</Button>
+        {onRefresh ? <Button size="sm" variant="ghost" onClick={onRefresh}>Run health check</Button> : null}
+      </div>
+      <PathInstructionsDialog open={helpOpen} onClose={() => setHelpOpen(false)} />
+    </div>
+  );
+}
+
+type FolderHealthItem = {
+  label: string;
+  ok: boolean;
+};
+
+function folderHealthItems(folder: FolderStatus): FolderHealthItem[] {
+  return [
+    { label: "Path configured", ok: folder.configured },
+    { label: "Readable", ok: folder.readable },
+    { label: folder.access === "readWrite" ? "Writable" : "Read-only access", ok: folder.access === "read" || folder.writable },
+    { label: "Baseline files", ok: folder.missingFiles.length === 0 },
+    { label: "Wiki folders", ok: folder.missingDirectories.length === 0 },
+  ];
+}
+
+function FolderHealthChecklist({ folder }: { folder: FolderStatus }) {
+  const items = folderHealthItems(folder);
+  return (
+    <div style={{ display: "grid", gap: 8 }} aria-label="Wiki root health checklist">
+      <div style={{ fontSize: 12, fontWeight: 650, color: tokens.muted }}>Health check</div>
+      <div role="list" style={{ position: "relative", display: "grid", gap: 0, padding: "2px 0" }}>
+        {items.length > 1 ? (
+          <span
+            aria-hidden
+            style={{
+              position: "absolute",
+              left: 8,
+              top: 12,
+              bottom: 12,
+              width: 1,
+              background: "oklch(0.38 0.09 145)",
+            }}
+          />
+        ) : null}
+        {items.map((item) => (
+          <div
+            key={item.label}
+            role="listitem"
+            style={{
+              display: "grid",
+              gridTemplateColumns: "18px minmax(0, 1fr)",
+              alignItems: "center",
+              gap: 10,
+              padding: "7px 0",
+              minWidth: 0,
+            }}
+          >
+            <span style={{ display: "inline-flex", justifyContent: "center", position: "relative", zIndex: 1, background: tokens.bg }}>
+              <StatusIcon status={item.ok ? "done" : "blocked"} />
+            </span>
+            <span style={{ fontSize: 13, fontWeight: 600, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", color: item.ok ? tokens.fg : "oklch(0.85 0.1 70)" }}>
+              {item.label}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+type MaintainerAgentOption = SettingsData["agentOptions"][number];
+type ProjectOption = SettingsData["projectOptions"][number];
+
+function agentStatusLabel(status?: string | null) {
+  if (!status) return "unknown";
+  return status.replace(/_/g, " ");
+}
+
+function projectStatusLabel(status?: string | null) {
+  if (!status) return "unknown";
+  return status.replace(/_/g, " ");
+}
+
+function adapterTypeLabel(adapterType?: string | null) {
+  if (!adapterType) return "unknown adapter";
+  return adapterType.replace(/_/g, " ");
+}
+
+function agentAvatarGlyph(icon?: string | null, name?: string | null) {
+  if (icon === "book-open") return "📖";
+  return (name?.trim().charAt(0) || "A").toUpperCase();
+}
+
+function AgentAvatar({ agent, size = 30 }: { agent: Pick<MaintainerAgentOption, "name" | "icon">; size?: number }) {
+  return (
+    <span
+      aria-hidden
+      style={{
+        width: size,
+        height: size,
+        borderRadius: "50%",
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        flexShrink: 0,
+        border: `1px solid ${tokens.border}`,
+        background: tokens.accent,
+        color: tokens.fg,
+        fontSize: size > 28 ? 14 : 12,
+        fontWeight: 700,
+      }}
+    >
+      {agentAvatarGlyph(agent.icon, agent.name)}
+    </span>
+  );
+}
+
+function AgentOptionLabel({ agent, muted = false }: { agent: MaintainerAgentOption; muted?: boolean }) {
+  return (
+    <span style={{ display: "flex", alignItems: "center", gap: 8, minWidth: 0 }}>
+      <AgentAvatar agent={agent} />
+      <span style={{ display: "grid", gap: 1, minWidth: 0 }}>
+        <span style={{ fontSize: 13, fontWeight: 600, color: muted ? tokens.muted : tokens.fg, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+          {agent.name}
+        </span>
+        <span style={{ fontSize: 11, color: tokens.muted, textTransform: "capitalize" }}>
+          {agentStatusLabel(agent.status)} · {adapterTypeLabel(agent.adapterType)}
+        </span>
+      </span>
+    </span>
+  );
+}
+
+function MaintainerAgentLink({
+  agent,
+  hrefProps,
+}: {
+  agent: MaintainerAgentOption;
+  hrefProps?: Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "style">;
+}) {
+  return (
+    <a
+      {...hrefProps}
+      style={{
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 8,
+        maxWidth: "100%",
+        color: tokens.fg,
+        textDecoration: "none",
+      }}
+    >
+      <AgentAvatar agent={agent} />
+      <span style={{ display: "grid", gap: 1, minWidth: 0, textAlign: "left" }}>
+        <span style={{ fontSize: 13, fontWeight: 650, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+          Resolve agent wiki maintainer
+        </span>
+        <span style={{ fontSize: 11, color: tokens.muted, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+          {agent.name} · {agentStatusLabel(agent.status)} · {adapterTypeLabel(agent.adapterType)}
+        </span>
+      </span>
+    </a>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Distillation settings panel (configured + unconfigured states).
+// Source filters / cursor windows / model lanes / auto-apply / backfill.
+// Most controls render the current state; persistence is wired through
+// existing managed-routine and plugin-action endpoints.
+// ---------------------------------------------------------------------------
+
+function DistillationSettingsPanel({ context, settings }: { context: { companyId: string | null }; settings: SettingsData }) {
+  const overview = useDistillationOverview(context.companyId);
+  const distillNow = usePluginAction("distill-paperclip-now");
+  const enableActiveProjects = usePluginAction("enable-paperclip-distillation-active-projects");
+  const queueBackfill = usePluginAction("backfill-paperclip-distillation");
+  const toast = usePluginToast();
+  const isMobile = useIsMobileLayout();
+  const [busy, setBusy] = useState<string | null>(null);
+  const data = overview.data;
+  const cursors = data?.cursors ?? [];
+  const counts = data?.counts ?? { cursors: 0, runningRuns: 0, failedRuns24h: 0, reviewRequired: 0 };
+  const isConfigured = cursors.length > 0;
+  const autoApplyRestriction = settings.distillationPolicy?.autoApplyRestriction ?? null;
+  const [useCheapPath, setUseCheapPath] = useState(true);
+
+  const projectsCovered = useMemo(() => {
+    const set = new Set<string>();
+    for (const cursor of cursors) {
+      if (cursor.projectId) set.add(cursor.projectId);
+    }
+    return set.size;
+  }, [cursors]);
+
+  async function runDistillNow() {
+    if (!context.companyId) return;
+    if (cursors.length === 0) {
+      toast({ tone: "warn", title: "Distill now needs at least one cursor" });
+      return;
+    }
+    setBusy("distill-now");
+    try {
+      await distillNow({
+        companyId: context.companyId,
+        useCheapModelProfile: useCheapPath,
+        idempotencyKey: `manual:company:${Date.now()}`,
+      });
+      toast({
+        tone: "success",
+        title: "Distill now queued",
+        body: "Wiki Maintainer will scan changed projects in the company and write into the default wiki space.",
+      });
+      overview.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Distill now failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  async function enableForActiveProjects() {
+    if (!context.companyId) return;
+    setBusy("enable-active-projects");
+    try {
+      const result = await enableActiveProjects({ companyId: context.companyId, limit: 3 }) as {
+        selectedProjects?: Array<{ name?: string | null }>;
+      };
+      const count = result.selectedProjects?.length ?? 0;
+      toast({
+        tone: count > 0 ? "success" : "warn",
+        title: count > 0 ? "Distillation enabled" : "No active projects found",
+        body: count > 0
+          ? `${count} active project${count === 1 ? "" : "s"} added to the distillation cursor set.`
+          : "Create or resume a project, then enable distillation again.",
+      });
+      overview.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Enable distillation failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  async function runBackfill() {
+    if (!context.companyId || cursors.length === 0) return;
+    const target = cursors.find((cursor) => cursor.projectId) ?? cursors[0];
+    if (!target.projectId && !target.rootIssueId) {
+      toast({ tone: "warn", title: "Backfill needs a project or root issue scope" });
+      return;
+    }
+    setBusy("backfill");
+    try {
+      await queueBackfill({
+        companyId: context.companyId,
+        projectId: target.projectId ?? undefined,
+        rootIssueId: target.rootIssueId ?? undefined,
+        useCheapModelProfile: useCheapPath,
+      });
+      toast({ tone: "success", title: "Backfill queued", body: target.projectName ?? target.rootIssueIdentifier ?? "Selected scope" });
+      overview.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Backfill failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  if (overview.loading && !data) {
+    return <Tiny>Loading distillation overview…</Tiny>;
+  }
+
+  if (!isConfigured) {
+    return (
+      <div style={{ display: "grid", gap: 16, maxWidth: 720 }}>
+        <Card>
+          <CardBody padding={isMobile ? 18 : 26}>
+            <div style={{ display: "flex", flexDirection: "column", alignItems: "flex-start", gap: 12 }}>
+              <SparklesIcon size={36} />
+              <div>
+                <h3 style={{ margin: 0, fontSize: 17, fontWeight: 650 }}>Distillation is off</h3>
+                <Tiny style={{ marginTop: 6, fontSize: 13, color: tokens.fg, lineHeight: 1.55, maxWidth: 540 }}>
+                  When enabled, the Wiki Maintainer reads Paperclip issues, comments, and documents for this
+                  company and keeps <Mono>wiki/projects/&lt;slug&gt;/standup.md</Mono> plus <Mono>wiki/projects/&lt;slug&gt;/index.md</Mono> pages in the
+                  <strong> default wiki space</strong>. Pages stay marked stale until a cursor window succeeds -
+                  they never imply live state.
+                </Tiny>
+                <Tiny style={{ marginTop: 6, fontSize: 13, color: tokens.fg, lineHeight: 1.55, maxWidth: 540 }}>
+                  Other spaces do not receive Paperclip-derived pages yet. They stay on manual and raw-file
+                  ingest until per-space Paperclip ingestion profiles ship.
+                </Tiny>
+              </div>
+              <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
+                <Button variant="primary" size="md" onClick={enableForActiveProjects} loading={busy === "enable-active-projects"}>
+                  <SparklesIcon size={14} /> Enable for active projects
+                </Button>
+                <Button variant="default" size="md" onClick={() => overview.refresh()}>Configure manually</Button>
+              </div>
+              <Tiny>Suggested defaults: 3 active projects in the default space · all-section auto-apply where allowed · routines paused for 24h.</Tiny>
+            </div>
+          </CardBody>
+        </Card>
+
+        <div style={{ display: "grid", gap: 12, gridTemplateColumns: isMobile ? "1fr" : "1fr 1fr" }}>
+          <Card>
+            <CardHeader title="What gets created" />
+            <CardBody padding={14}>
+              <ul style={{ margin: 0, paddingLeft: 18, fontSize: 12.5, color: tokens.muted, lineHeight: 1.5 }}>
+                <li>Project overviews at <Mono>wiki/projects/&lt;slug&gt;/index.md</Mono></li>
+                <li>Executive standups at <Mono>wiki/projects/&lt;slug&gt;/standup.md</Mono></li>
+                <li>Decisions and history under <Mono>wiki/projects/&lt;slug&gt;/</Mono></li>
+                <li>Source bundles cached under <Mono>raw/distill/</Mono></li>
+              </ul>
+            </CardBody>
+          </Card>
+          <Card>
+            <CardHeader title="What it never does" />
+            <CardBody padding={14}>
+              <ul style={{ margin: 0, paddingLeft: 18, fontSize: 12.5, color: tokens.muted, lineHeight: 1.5 }}>
+                <li>Read across companies — strict per-company isolation.</li>
+                <li>Re-distill its own plugin operation issues.</li>
+                <li>Auto-apply patches when source hashes drift.</li>
+              </ul>
+            </CardBody>
+          </Card>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ display: "grid", gap: 16, minWidth: 0 }}>
+      {autoApplyRestriction ? (
+        <Callout tone="warn">
+          {autoApplyRestriction} The plugin ignores auto-apply requests from config and manual distill actions on this instance.
+        </Callout>
+      ) : null}
+      <Callout>
+        <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12, flexWrap: "wrap" }}>
+          <div style={{ display: "flex", alignItems: "center", gap: 10 }}>
+            <InfoIcon size={16} />
+            <strong style={{ fontSize: 13 }}>Active for {projectsCovered} project{projectsCovered === 1 ? "" : "s"} · {counts.cursors} cursor{counts.cursors === 1 ? "" : "s"} catching up · default space</strong>
+          </div>
+          <div style={{ display: "flex", gap: 8 }}>
+            <Button variant="ghost" size="sm" onClick={() => overview.refresh()}><RefreshIcon size={12} /> Refresh</Button>
+            <Button variant="primary" size="sm" onClick={runDistillNow} loading={busy === "distill-now"}><SparklesIcon size={12} /> Distill now</Button>
+          </div>
+        </div>
+        <Tiny style={{ marginTop: 6 }}>
+          Distillation runs on the assigned Wiki Maintainer agent and writes only into the default
+          space. Use the cheap path option when the agent exposes a cheap model profile.
+        </Tiny>
+      </Callout>
+
+      <Card>
+        <CardHeader title="Source filters" />
+        <CardBody padding={14}>
+          <div style={{ display: "grid", gridTemplateColumns: isMobile ? "1fr" : "1fr 1fr", gap: 16 }}>
+            <fieldset style={{ border: 0, padding: 0, margin: 0, display: "grid", gap: 6 }}>
+              <legend style={{ fontSize: 12, color: tokens.muted, marginBottom: 4 }}>Issue scope</legend>
+              <CheckboxRow label="Active projects" defaultChecked help="Cursors are created for projects with recent activity." />
+              <CheckboxRow label="Root issues marked distillable" defaultChecked />
+              <CheckboxRow label="All company issues" help="May create large source windows." />
+              <Tiny>
+                These filters narrow the Paperclip source scope. The destination is always the default
+                wiki space in Phase 1.
+              </Tiny>
+              <Tiny>Plugin-operation issues are always excluded to prevent feedback loops.</Tiny>
+            </fieldset>
+            <fieldset style={{ border: 0, padding: 0, margin: 0, display: "grid", gap: 6 }}>
+              <legend style={{ fontSize: 12, color: tokens.muted, marginBottom: 4 }}>Source kinds</legend>
+              <CheckboxRow label="Issue title + description" defaultChecked locked />
+              <CheckboxRow label="Comments (ranked, clipped)" defaultChecked />
+              <CheckboxRow label="Documents (plan, spec, report)" defaultChecked />
+              <CheckboxRow label="Work products / attachments" suffix="coming soon" />
+              <Tiny>Heartbeats and hidden documents are never included.</Tiny>
+            </fieldset>
+          </div>
+        </CardBody>
+      </Card>
+
+      <Card>
+        <CardHeader title="Cursor windows" />
+        <CardBody padding={14}>
+          <div style={{ display: "grid", gridTemplateColumns: isMobile ? "1fr" : "1fr 1fr", gap: 16 }}>
+            <SettingField label="Max source characters per project" hint="Source bundles above this size are clipped and the page warns 'source clipped'.">
+              <TextInput defaultValue="48000" />
+            </SettingField>
+            <SettingField label="Min source age before processing" hint="Debounces a hot project so a flurry of comments collapses into one cursor window.">
+              <SelectInput defaultValue="15" options={[["5", "5 min"], ["15", "15 min"], ["30", "30 min"], ["60", "1 hour"]]} />
+            </SettingField>
+            <SettingField label="Max cursor windows per routine run" hint="Routine runs that hit this cap split the remainder into the next routine fire.">
+              <TextInput defaultValue="6" />
+            </SettingField>
+            <SettingField label="Stale window threshold" hint="After this, project pages render a 'Stale' badge until a successful run advances the cursor.">
+              <SelectInput defaultValue="72" options={[["24", "24 h"], ["48", "48 h"], ["72", "72 h"], ["168", "7 days"]]} />
+            </SettingField>
+          </div>
+        </CardBody>
+      </Card>
+
+      <Card>
+        <CardHeader title="Agent execution" />
+        <CardBody padding={14}>
+          <div style={{ display: "grid", gridTemplateColumns: isMobile ? "1fr" : "1fr 1fr", gap: 16 }}>
+            <SettingField label="Assigned maintainer" hint="Model selection comes from the agent adapter and its runtime config. The plugin does not choose Claude/Codex/Gemini models here.">
+              <div style={{ minHeight: 34, display: "flex", alignItems: "center", border: `1px solid ${tokens.border}`, borderRadius: 6, padding: "6px 10px", fontSize: 13 }}>
+                {settings.managedAgent.details
+                  ? `${settings.managedAgent.details.name} · ${adapterTypeLabel(settings.managedAgent.details.adapterType)}`
+                  : "No maintainer agent resolved"}
+              </div>
+            </SettingField>
+            <SettingField label="Cheap path" hint="When enabled, manual distill and backfill operation issues request assigneeAdapterOverrides.modelProfile = cheap.">
+              <CheckboxRow
+                label="Request the assigned agent's cheap model profile for distillation tasks"
+                checked={useCheapPath}
+                onChange={setUseCheapPath}
+              />
+            </SettingField>
+          </div>
+        </CardBody>
+      </Card>
+
+      <Card>
+        <CardHeader title="Auto-apply policy" />
+        <CardBody padding={14}>
+          <div style={{ display: "grid", gap: 8 }}>
+            <RadioRow name="autoapply" value="never" label="Never — every patch goes to review-required." />
+            <RadioRow name="autoapply" value="status" label="Executive-status sections only — standup, current direction, and risks." />
+            <RadioRow name="autoapply" value="all" label="All sections — apply when source hash matches and confidence ≥ 0.8 (default)." defaultChecked />
+            <Tiny>Stale-hash collisions always fall through to review, regardless of policy.</Tiny>
+          </div>
+        </CardBody>
+      </Card>
+
+      <Card>
+        <CardHeader
+          title="Backfill"
+          right={<Button variant="default" size="sm" onClick={runBackfill} loading={busy === "backfill"}>Queue backfill</Button>}
+        />
+        <CardBody padding={14}>
+          <Tiny style={{ marginBottom: 6 }}>Backfills replay a bounded source window for a single scope so newly-enabled projects can catch up to fresh state.</Tiny>
+          <div style={{ display: "grid", gap: 8, fontSize: 13 }}>
+            <PropRow label="Default scope" value={cursors.find((c) => c.projectName)?.projectName ?? cursors[0]?.scopeKey ?? "—"} />
+            <PropRow label="Cursors active" value={String(counts.cursors)} />
+            <PropRow label="Runs in flight" value={String(counts.runningRuns)} />
+            <PropRow label="Failed (24h)" value={String(counts.failedRuns24h)} />
+            <PropRow label="Review queue" value={String(counts.reviewRequired)} />
+          </div>
+        </CardBody>
+      </Card>
+
+      <Tiny>
+        Active cursors:&nbsp;
+        {cursors.slice(0, 6).map((cursor, idx) => (
+          <span key={cursor.id}>
+            {idx > 0 ? " · " : ""}
+            {cursor.projectName ?? cursor.rootIssueIdentifier ?? cursor.scopeKey}
+          </span>
+        ))}
+        {cursors.length > 6 ? <span>{` +${cursors.length - 6} more`}</span> : null}
+      </Tiny>
+    </div>
+  );
+}
+
+function SettingField({ label, hint, children }: { label: ReactNode; hint?: ReactNode; children: ReactNode }) {
+  return (
+    <div style={{ display: "grid", gap: 6, minWidth: 0 }}>
+      <label style={{ fontSize: 12, color: tokens.muted }}>{label}</label>
+      {children}
+      {hint ? <Tiny>{hint}</Tiny> : null}
+    </div>
+  );
+}
+
+function CheckboxRow({
+  label,
+  help,
+  defaultChecked,
+  checked,
+  onChange,
+  locked,
+  suffix,
+}: {
+  label: string;
+  help?: string;
+  defaultChecked?: boolean;
+  checked?: boolean;
+  onChange?: (checked: boolean) => void;
+  locked?: boolean;
+  suffix?: string;
+}) {
+  return (
+    <label style={{ display: "flex", alignItems: "flex-start", gap: 8, fontSize: 13 }}>
+      <input
+        type="checkbox"
+        defaultChecked={checked === undefined ? defaultChecked : undefined}
+        checked={checked}
+        disabled={locked}
+        onChange={(event) => onChange?.(event.currentTarget.checked)}
+      />
+      <span>
+        {label}
+        {suffix ? <span style={{ marginLeft: 6, fontSize: 11, color: tokens.muted }}>({suffix})</span> : null}
+        {help ? <Tiny style={{ display: "block", marginTop: 2 }}>{help}</Tiny> : null}
+      </span>
+    </label>
+  );
+}
+
+function RadioRow({ name, value, label, defaultChecked }: { name: string; value: string; label: string; defaultChecked?: boolean }) {
+  return (
+    <label style={{ display: "flex", alignItems: "flex-start", gap: 8, fontSize: 13 }}>
+      <input type="radio" name={name} value={value} defaultChecked={defaultChecked} />
+      <span>{label}</span>
+    </label>
+  );
+}
+
+function SelectInput({ defaultValue, options }: { defaultValue: string; options: ReadonlyArray<readonly [string, string]> }) {
+  return (
+    <select
+      defaultValue={defaultValue}
+      style={{
+        background: "oklch(0.2 0 0)",
+        color: tokens.fg,
+        border: `1px solid ${tokens.border}`,
+        borderRadius: 6,
+        padding: "6px 10px",
+        fontSize: 13,
+      }}
+    >
+      {options.map(([value, label]) => <option key={value} value={value}>{label}</option>)}
+    </select>
+  );
+}
+
+function SettingsBody({ context, initialSection = "root" }: { context: { companyId: string | null; companyPrefix?: string | null }; initialSection?: SettingsSectionKey }) {
+  const settings = useSettings(context.companyId);
+  const hostNavigation = useHostNavigation();
+  const { pathname } = useHostLocation();
+  const isMobile = useIsMobileLayout();
+  const bootstrap = usePluginAction("bootstrap-root");
+  const updateEventIngestion = usePluginAction("update-event-ingestion-settings");
+  const resetAgent = usePluginAction("reset-managed-agent");
+  const resetProject = usePluginAction("reset-managed-project");
+  const resetRoutine = usePluginAction("reset-managed-routine");
+  const reconcileAgent = usePluginAction("reconcile-managed-agent");
+  const reconcileProject = usePluginAction("reconcile-managed-project");
+  const selectAgent = usePluginAction("select-managed-agent");
+  const selectProject = usePluginAction("select-managed-project");
+  const resetSkills = usePluginAction("reset-managed-skills");
+  const reconcileRoutines = usePluginAction("reconcile-managed-routines");
+  const updateRoutineStatus = usePluginAction("update-managed-routine-status");
+  const runManagedRoutine = usePluginAction("run-managed-routine");
+  const toast = usePluginToast();
+
+  const [folderPath, setFolderPath] = useState("");
+  const [folderBusy, setFolderBusy] = useState(false);
+  const [agentBusy, setAgentBusy] = useState(false);
+  const [projectBusy, setProjectBusy] = useState(false);
+  const [selectedAgentId, setSelectedAgentId] = useState("");
+  const [selectedProjectId, setSelectedProjectId] = useState("");
+  const [routineBusyKey, setRoutineBusyKey] = useState<string | null>(null);
+  const [routineRepairBusy, setRoutineRepairBusy] = useState(false);
+  const [skillBusy, setSkillBusy] = useState(false);
+  const [allRepairBusy, setAllRepairBusy] = useState(false);
+  const [eventPolicy, setEventPolicy] = useState<EventIngestionSettings | null>(null);
+  const [eventPolicyBusy, setEventPolicyBusy] = useState(false);
+  const [activeSettingsSection, setActiveSettingsSection] = useState<SettingsSectionKey>(initialSection);
+
+  useEffect(() => {
+    if (settings.data?.folder.path && !folderPath) setFolderPath(settings.data.folder.path);
+  }, [settings.data?.folder.path, folderPath]);
+  useEffect(() => { if (settings.data?.managedAgent.agentId) setSelectedAgentId(settings.data.managedAgent.agentId); }, [settings.data?.managedAgent.agentId]);
+  useEffect(() => { if (settings.data?.managedProject.projectId) setSelectedProjectId(settings.data.managedProject.projectId); }, [settings.data?.managedProject.projectId]);
+  useEffect(() => {
+    if (settings.data?.eventIngestion && eventPolicy === null) setEventPolicy(settings.data.eventIngestion);
+  }, [settings.data?.eventIngestion, eventPolicy]);
+  useEffect(() => {
+    setActiveSettingsSection(initialSection);
+  }, [initialSection]);
+
+  if (!context.companyId) return <Callout>Choose a company to view LLM Wiki settings.</Callout>;
+  if (settings.loading) return <Tiny>Loading settings…</Tiny>;
+  if (settings.error) return <Callout tone="danger">{settings.error.message}</Callout>;
+  if (!settings.data) return <Tiny>No settings available.</Tiny>;
+
+  const data = settings.data;
+  const maintainerFallbackAgent: MaintainerAgentOption | null = data.managedAgent.agentId
+    ? {
+        id: data.managedAgent.agentId,
+        name: data.managedAgent.details?.name ?? "Wiki Maintainer",
+        status: data.managedAgent.details?.status ?? data.managedAgent.status,
+        adapterType: data.managedAgent.details?.adapterType ?? null,
+        icon: data.managedAgent.details?.icon ?? "book-open",
+        urlKey: data.managedAgent.details?.urlKey ?? null,
+      }
+    : null;
+  const maintainerAgentOptions = maintainerFallbackAgent && !data.agentOptions.some((agent) => agent.id === maintainerFallbackAgent.id)
+    ? [maintainerFallbackAgent, ...data.agentOptions]
+    : data.agentOptions;
+  const effectiveSelectedAgentId = selectedAgentId || data.managedAgent.agentId || "";
+  const currentMaintainerAgent = maintainerAgentOptions.find((agent) => agent.id === effectiveSelectedAgentId) ?? maintainerFallbackAgent;
+  const savedCustomMaintainer = data.managedAgent.source === "selected";
+  const selectingDifferentMaintainer = Boolean(
+    data.managedAgent.source === "managed" &&
+    data.managedAgent.agentId &&
+    effectiveSelectedAgentId &&
+    effectiveSelectedAgentId !== data.managedAgent.agentId,
+  );
+  const showMaintainerWarning = savedCustomMaintainer || selectingDifferentMaintainer;
+  const maintainerPendingApproval = currentMaintainerAgent?.status === "pending_approval" || data.managedAgent.details?.status === "pending_approval";
+  const agentLink = currentMaintainerAgent?.id
+    ? `/agents/${currentMaintainerAgent.id}`
+    : null;
+  const projectLink = data.managedProject.projectId
+    ? `/projects/${data.managedProject.projectId}`
+    : null;
+  const managedRoutines = data.managedRoutines ?? (data.managedRoutine ? [data.managedRoutine] : []);
+  const agentHealthItems = buildAgentHealthItems(data.managedAgent);
+  const agentHealthWarnings = agentHealthItems.filter((item) => !item.ok);
+  const routineHealthItems = buildRoutineHealthItems(managedRoutines, data.managedAgent, data.managedProject);
+  const routineHealthWarnings = routineHealthItems.filter((item) => !item.ok);
+  const projectHealthItems = buildProjectHealthItems(data.managedProject);
+  const projectHealthWarnings = projectHealthItems.filter((item) => !item.ok);
+  const managedSkills = data.managedSkills ?? [];
+  const skillHealthItems = buildSkillHealthItems(managedSkills);
+  const skillHealthWarnings = skillHealthItems.filter((item) => !item.ok);
+  const configurationErrors = [
+    ...(!data.folder.healthy ? ["Wiki root folder"] : []),
+    ...(agentHealthWarnings.length > 0 ? ["Managed agents"] : []),
+    ...(skillHealthWarnings.length > 0 ? ["Managed skills"] : []),
+    ...(projectHealthWarnings.length > 0 ? ["Managed projects"] : []),
+    ...(routineHealthWarnings.length > 0 ? ["Managed routines"] : []),
+  ];
+  const hasConfigurationErrors = configurationErrors.length > 0;
+  const projectFallbackOption: ProjectOption | null = data.managedProject.projectId
+    ? {
+        id: data.managedProject.projectId,
+        name: data.managedProject.details?.name ?? "Current project",
+        status: data.managedProject.details?.status ?? data.managedProject.status,
+        color: data.managedProject.details?.color ?? null,
+      }
+    : null;
+  const projectOptions = projectFallbackOption && !data.projectOptions.some((project) => project.id === projectFallbackOption.id)
+    ? [projectFallbackOption, ...data.projectOptions]
+    : data.projectOptions;
+  const effectiveSelectedProjectId = selectedProjectId || data.managedProject.projectId || "";
+  const currentProjectOption = projectOptions.find((project) => project.id === effectiveSelectedProjectId) ?? projectFallbackOption;
+  const currentEventPolicy = eventPolicy ?? data.eventIngestion;
+  const managedRoutineItems: ManagedRoutinesListItem[] = managedRoutines.map((routine) => {
+    const fallback = routineFallbackFor(routine);
+    const key = routine.resourceKey ?? routine.routineId ?? fallback.title;
+    const status = managedRoutineStatus(routine);
+    const assigneeAgentId = routine.routine?.assigneeAgentId ?? routine.details?.assigneeAgentId ?? null;
+
+    return {
+      key,
+      title: routine.routine?.title ?? routine.details?.title ?? fallback.title,
+      status: status === "missing" || status === "missing_refs" ? "paused" : status,
+      routineId: routine.routineId ?? routine.routine?.id ?? null,
+      href: routine.routineId ? `/routines/${routine.routineId}` : null,
+      resourceKey: routine.resourceKey ?? null,
+      projectId: routine.routine?.projectId ?? null,
+      assigneeAgentId,
+      cronExpression: routine.details?.cronExpression ?? fallback.cron,
+      lastRunAt: routine.routine?.lastTriggeredAt ?? routine.details?.lastRunAt ?? null,
+      managedByPluginDisplayName: routine.routine?.managedByPlugin?.pluginDisplayName ?? "LLM Wiki",
+      missingRefs: routine.missingRefs?.map((ref) => ({
+        resourceKind: ref.resourceKind,
+        resourceKey: ref.resourceKey,
+      })),
+      defaultDrift: routine.defaultDrift
+        ? {
+            changedFields: routine.defaultDrift.changedFields,
+            defaultTitle: routine.defaultDrift.defaultTitle ?? null,
+            defaultDescription: routine.defaultDrift.defaultDescription ?? null,
+          }
+        : null,
+    };
+  });
+  const routineDefaultDriftItems = managedRoutineItems.filter((routine) => routine.defaultDrift?.changedFields.length);
+  const agentDefaultDrift = data.managedAgent.defaultDrift;
+  const activeSpaceSlug = readActiveSpaceSlugFromLocation(pathname);
+
+  function routineBusyKeyFor(prefix: string) {
+    const marker = `${prefix}:`;
+    return routineBusyKey?.startsWith(marker) ? routineBusyKey.slice(marker.length) : null;
+  }
+
+  async function changeFolder() {
+    if (!context.companyId || !folderPath.trim()) return;
+    setFolderBusy(true);
+    try {
+      await bootstrap({ companyId: context.companyId, path: folderPath.trim() });
+      toast({ tone: "success", title: "Folder updated" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Folder update failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setFolderBusy(false);
+    }
+  }
+
+  async function chooseAgent() {
+    const agentId = selectedAgentId || data.managedAgent.agentId;
+    if (!context.companyId || !agentId) return;
+    setAgentBusy(true);
+    try {
+      await selectAgent({ companyId: context.companyId, agentId });
+      toast({ tone: "success", title: "Maintainer agent selected" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Agent selection failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setAgentBusy(false);
+    }
+  }
+
+  async function chooseProject() {
+    const projectId = effectiveSelectedProjectId;
+    if (!context.companyId || !projectId) return;
+    setProjectBusy(true);
+    try {
+      await selectProject({ companyId: context.companyId, projectId });
+      toast({ tone: "success", title: "Project selected" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Project selection failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setProjectBusy(false);
+    }
+  }
+
+  async function saveEventPolicy() {
+    if (!context.companyId || !eventPolicy) return;
+    setEventPolicyBusy(true);
+    try {
+      const next = await updateEventIngestion({ companyId: context.companyId, ...eventPolicy }) as EventIngestionSettings;
+      setEventPolicy(next);
+      toast({ tone: "success", title: "Event ingestion controls saved" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Could not save event controls", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setEventPolicyBusy(false);
+    }
+  }
+
+  async function repairManagedRoutines() {
+    if (!context.companyId) return;
+    setRoutineRepairBusy(true);
+    try {
+      await reconcileRoutines({ companyId: context.companyId });
+      toast({ tone: "success", title: "Routines fixed" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Routine repair failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setRoutineRepairBusy(false);
+    }
+  }
+
+  async function resyncManagedSkills() {
+    if (!context.companyId) return;
+    setSkillBusy(true);
+    try {
+      await resetSkills({ companyId: context.companyId });
+      toast({ tone: "success", title: "Skills synced" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Skill sync failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setSkillBusy(false);
+    }
+  }
+
+  async function fixAllConfigurationErrors() {
+    if (!context.companyId || !hasConfigurationErrors) return;
+    const confirmed = typeof window === "undefined" || window.confirm(
+      "Fix all detected LLM Wiki configuration errors? This may recreate missing wiki baseline files and restore plugin-managed agents, projects, routines, and skills to their current defaults.",
+    );
+    if (!confirmed) return;
+
+    setAllRepairBusy(true);
+    try {
+      if (!data.folder.healthy) {
+        const path = folderPath.trim() || data.folder.path?.trim() || "";
+        if (!path && !data.folder.configured) {
+          throw new Error("Choose a wiki root folder path before fixing all configuration errors.");
+        }
+        await bootstrap(path ? { companyId: context.companyId, path } : { companyId: context.companyId });
+      }
+
+      if (skillHealthWarnings.length > 0) {
+        await resetSkills({ companyId: context.companyId });
+      }
+
+      const shouldResetAgent =
+        data.managedAgent.source !== "managed" ||
+        !managedAgentIsReady(data.managedAgent) ||
+        Boolean(data.managedAgent.defaultDrift?.changedFiles.length);
+      const shouldResetProject =
+        data.managedProject.source !== "managed" ||
+        !managedProjectIsReady(data.managedProject);
+
+      if (shouldResetAgent) {
+        await resetAgent({ companyId: context.companyId });
+      } else if (routineHealthWarnings.length > 0) {
+        await reconcileAgent({ companyId: context.companyId });
+      }
+
+      if (shouldResetProject) {
+        await resetProject({ companyId: context.companyId });
+      } else if (routineHealthWarnings.length > 0) {
+        await reconcileProject({ companyId: context.companyId });
+      }
+
+      if (routineHealthWarnings.length > 0) {
+        await reconcileRoutines({ companyId: context.companyId });
+      }
+
+      toast({ tone: "success", title: "Configuration errors fixed" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Fix all failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setAllRepairBusy(false);
+    }
+  }
+
+  async function toggleManagedRoutine(routine: ManagedRoutinesListItem, enabled: boolean) {
+    if (!context.companyId || !routine.resourceKey) return;
+    if (!enabled && !routine.assigneeAgentId) {
+      toast({ tone: "warn", title: "Default agent required", body: "Set a default maintainer before enabling this routine." });
+      return;
+    }
+    setRoutineBusyKey(`status:${routine.key}`);
+    try {
+      await updateRoutineStatus({ companyId: context.companyId, routineKey: routine.resourceKey, status: enabled ? "paused" : "active" });
+      toast({ tone: "success", title: enabled ? "Routine paused" : "Routine enabled" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Routine update failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setRoutineBusyKey(null);
+    }
+  }
+
+  async function runManagedRoutineNow(routine: ManagedRoutinesListItem) {
+    if (!context.companyId || !routine.resourceKey) return;
+    const assigneeAgentId = routine.assigneeAgentId ?? data.managedAgent.agentId ?? null;
+    const projectId = routine.projectId ?? data.managedProject.projectId ?? null;
+    if (!assigneeAgentId) {
+      toast({ tone: "warn", title: "Default agent required", body: "Set a default maintainer before running this routine." });
+      return;
+    }
+
+    setRoutineBusyKey(`run:${routine.key}`);
+    try {
+      await runManagedRoutine({
+        companyId: context.companyId,
+        routineKey: routine.resourceKey,
+        assigneeAgentId,
+        projectId,
+      });
+      toast({ tone: "success", title: "Routine run started" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Routine run failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setRoutineBusyKey(null);
+    }
+  }
+
+  async function resetManagedRoutineToDefaults(routine: ManagedRoutinesListItem) {
+    if (!context.companyId || !routine.resourceKey) return;
+    const changedFields = routine.defaultDrift?.changedFields ?? [];
+    const fieldList = changedFields.length > 0 ? changedFields.join(", ") : "managed defaults";
+    const confirmed = typeof window === "undefined" || window.confirm(
+      `Update "${routine.title}" to the current LLM Wiki plugin defaults? This replaces ${fieldList}. Cancel to keep the current custom routine text.`,
+    );
+    if (!confirmed) return;
+
+    const assigneeAgentId = routine.assigneeAgentId ?? data.managedAgent.agentId ?? null;
+    const projectId = routine.projectId ?? data.managedProject.projectId ?? null;
+    setRoutineBusyKey(`reset:${routine.key}`);
+    try {
+      await resetRoutine({
+        companyId: context.companyId,
+        routineKey: routine.resourceKey,
+        assigneeAgentId,
+        projectId,
+      });
+      toast({ tone: "success", title: "Routine defaults updated" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Routine reset failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setRoutineBusyKey(null);
+    }
+  }
+
+  async function resetManagedAgentToDefaults() {
+    if (!context.companyId) return;
+    const changedFiles = agentDefaultDrift?.changedFiles ?? [];
+    const fileList = changedFiles.length > 0 ? changedFiles.join(", ") : "managed instructions and defaults";
+    const confirmed = typeof window === "undefined" || window.confirm(
+      `Update the Wiki Maintainer to the current LLM Wiki plugin defaults? This replaces ${fileList}. Cancel to keep the current custom instructions.`,
+    );
+    if (!confirmed) return;
+
+    setAgentBusy(true);
+    try {
+      await resetAgent({ companyId: context.companyId });
+      toast({ tone: "success", title: "Agent reset to plugin defaults" });
+      settings.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Reset failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setAgentBusy(false);
+    }
+  }
+
+  const activeSettingsConfig =
+    SETTINGS_SECTIONS.find((section) => section.key === activeSettingsSection) ?? SETTINGS_SECTIONS[0];
+
+  return (
+    <div style={{
+      display: "flex",
+      flexDirection: isMobile ? "column" : "row",
+      gap: isMobile ? 16 : 24,
+      maxWidth: isMobile ? "none" : 1040,
+      minWidth: 0,
+    }}>
+      <aside style={{
+        width: isMobile ? "auto" : 230,
+        flexShrink: 0,
+        borderRight: isMobile ? "none" : `1px solid ${tokens.border}`,
+        borderBottom: isMobile ? `1px solid ${tokens.border}` : "none",
+        paddingRight: isMobile ? 0 : 16,
+        paddingBottom: isMobile ? 12 : 0,
+      }}>
+        <nav aria-label="LLM Wiki settings sections" style={{
+          display: "flex",
+          flexDirection: isMobile ? "row" : "column",
+          gap: 4,
+          overflowX: isMobile ? "auto" : "visible",
+          paddingBottom: isMobile ? 2 : 0,
+        }}>
+          {SETTINGS_SECTIONS.map((section) => (
+            <div key={section.key} style={{ minWidth: isMobile ? 190 : 0 }}>
+              <SettingsSectionButton
+                section={section}
+                active={activeSettingsSection === section.key}
+                onSelect={() => {
+                  setActiveSettingsSection(section.key);
+                  hostNavigation.navigate(buildSettingsSectionHref(section.key, activeSpaceSlug));
+                }}
+              />
+            </div>
+          ))}
+        </nav>
+      </aside>
+
+      <div style={{ flex: 1, minWidth: 0 }}>
+        {hasConfigurationErrors ? (
+          <div style={{ marginBottom: 18 }}>
+            <Callout tone="warn">
+              <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12, flexWrap: "wrap" }}>
+                <div style={{ display: "grid", gap: 4, minWidth: 0 }}>
+                  <strong>configuration errors detected, fix them all?</strong>
+                  <Tiny>
+                    {configurationErrors.join(", ")} {configurationErrors.length === 1 ? "needs" : "need"} attention.
+                  </Tiny>
+                </div>
+                <Button size="sm" variant="primary" onClick={fixAllConfigurationErrors} loading={allRepairBusy}>
+                  Fix them all
+                </Button>
+              </div>
+            </Callout>
+          </div>
+        ) : null}
+        {activeSettingsSection === "root" ? (
+          <section style={{ display: "grid", gap: 22, minWidth: 0 }}>
+            <h1 style={{ margin: 0, fontSize: isMobile ? 20 : 22, fontWeight: 700 }}>Setup</h1>
+            <SetupSection title="Base Folder">
+              <div style={{ display: "grid", gap: 12 }}>
+                <FolderPathPicker
+                  value={folderPath}
+                  onChange={setFolderPath}
+                  onApply={changeFolder}
+                  applyLabel="Apply path"
+                  busy={folderBusy}
+                  disabled={!folderPath.trim()}
+                  onRefresh={() => settings.refresh()}
+                />
+                <FolderHealthChecklist folder={data.folder} />
+                {data.folder.problems.length > 0 ? (
+                  <Callout tone="warn">{data.folder.problems.length} folder issue(s): {data.folder.problems.map((p) => p.message).join("; ")}</Callout>
+                ) : null}
+              </div>
+            </SetupSection>
+            <SetupSection title="Managed Agents" separated>
+              <div style={{ display: "grid", gap: 14, maxWidth: isMobile ? "none" : 620, minWidth: 0 }}>
+                <ManagedResourceHealthChecklist
+                  items={agentHealthItems}
+                  ariaLabel="Wiki agents health checklist"
+                  heading="Agent health"
+                />
+                {agentHealthWarnings.length > 0 ? (
+                  <Callout tone="warn">
+                    <div style={{ display: "grid", gap: 8 }}>
+                      <div>{agentHealthWarnings.length} agent issue(s) need attention.</div>
+                      <ul style={{ margin: 0, paddingLeft: 18 }}>
+                        {agentHealthWarnings.map((item) => <li key={item.label}>{item.detail}</li>)}
+                      </ul>
+                    </div>
+                  </Callout>
+                ) : null}
+                <div style={{ display: "grid", gap: 8 }}>
+                  <label style={{ fontSize: 12, color: tokens.muted }}>Maintainer</label>
+                  <fieldset
+                    disabled={agentBusy}
+                    style={{ border: 0, margin: 0, minWidth: 0, padding: 0 }}
+                  >
+                    <AssigneePicker
+                      companyId={context.companyId}
+                      value={effectiveSelectedAgentId ? `agent:${effectiveSelectedAgentId}` : ""}
+                      includeUsers={false}
+                      placeholder="Select maintainer"
+                      noneLabel="No maintainer"
+                      searchPlaceholder="Search agents..."
+                      emptyMessage="No agents found."
+                      onChange={(_value, selection) => {
+                        setSelectedAgentId(selection.assigneeAgentId ?? "");
+                      }}
+                    />
+                  </fieldset>
+                  <Tiny>
+                    Adapter: {adapterTypeLabel(currentMaintainerAgent?.adapterType ?? data.managedAgent.details?.adapterType ?? null)}
+                  </Tiny>
+                  {maintainerPendingApproval ? (
+                    <Callout tone="warn">
+                      The Wiki Maintainer is pending approval. Approve the agent before relying on wiki ingest, query, lint, or scheduled maintenance tasks.
+                    </Callout>
+                  ) : null}
+                  {showMaintainerWarning ? (
+                    <Callout tone="warn">
+                      This is not the Paperclip-provided Wiki Maintainer. Plugin operations and routines may miss the recommended wiki role, tools, and default instructions.
+                    </Callout>
+                  ) : null}
+                  {agentDefaultDrift?.changedFiles.length ? (
+                    <Callout tone="warn">
+                      Wiki Maintainer instruction defaults changed: {agentDefaultDrift.changedFiles.join(", ")}. Reset only if you want to replace current custom instructions with the plugin template.
+                    </Callout>
+                  ) : null}
+                  <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
+                    <Button
+                      size="sm"
+                      variant="primary"
+                      onClick={chooseAgent}
+                      loading={agentBusy}
+                      disabled={!effectiveSelectedAgentId || effectiveSelectedAgentId === data.managedAgent.agentId}
+                    >
+                      Save maintainer
+                    </Button>
+                    {agentLink ? <Button size="sm" onClick={() => hostNavigation.navigate(agentLink)}>Open agent ↗</Button> : null}
+                    <Button size="sm" variant="ghost" onClick={async () => {
+                      if (!context.companyId) return;
+                      setAgentBusy(true);
+                      try {
+                        await reconcileAgent({ companyId: context.companyId });
+                        toast({ tone: "success", title: "Agent reconciled" });
+                        settings.refresh();
+                      } catch (err) {
+                        toast({ tone: "error", title: "Reconcile failed", body: err instanceof Error ? err.message : String(err) });
+                      } finally {
+                        setAgentBusy(false);
+                      }
+                    }} loading={agentBusy}>Repair</Button>
+                    <Button size="sm" variant="ghost" onClick={resetManagedAgentToDefaults} loading={agentBusy}>Reset to defaults</Button>
+                  </div>
+                </div>
+              </div>
+            </SetupSection>
+            <SetupSection title="Managed Skills" separated>
+              <div style={{ display: "grid", gap: 12, maxWidth: isMobile ? "none" : 620, minWidth: 0 }}>
+                <SkillHealthChecklist items={skillHealthItems} />
+                {skillHealthWarnings.length > 0 ? (
+                  <Callout tone="warn">
+                    <div style={{ display: "grid", gap: 8 }}>
+                      <div>{skillHealthWarnings.length} skill issue(s) need attention.</div>
+                      <ul style={{ margin: 0, paddingLeft: 18 }}>
+                        {skillHealthWarnings.map((item) => <li key={item.label}>{item.detail}</li>)}
+                      </ul>
+                      <div>
+                        <Button size="sm" variant="primary" onClick={resyncManagedSkills} loading={skillBusy}>Re-sync skills</Button>
+                      </div>
+                    </div>
+                  </Callout>
+                ) : (
+                  <Callout>
+                    <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12, flexWrap: "wrap" }}>
+                      <span>LLM Wiki skills are installed in the company skill library.</span>
+                      <Button size="sm" variant="ghost" onClick={resyncManagedSkills} loading={skillBusy}>Re-sync skills</Button>
+                    </div>
+                  </Callout>
+                )}
+              </div>
+            </SetupSection>
+            <SetupSection title="Managed Projects" separated>
+              <div style={{ display: "grid", gap: 10, maxWidth: isMobile ? "none" : 620, minWidth: 0 }}>
+                <ManagedResourceHealthChecklist
+                  items={projectHealthItems}
+                  ariaLabel="Wiki projects health checklist"
+                  heading="Project health"
+                />
+                {projectHealthWarnings.length > 0 ? (
+                  <Callout tone="warn">
+                    <div style={{ display: "grid", gap: 8 }}>
+                      <div>{projectHealthWarnings.length} project issue(s) need attention.</div>
+                      <ul style={{ margin: 0, paddingLeft: 18 }}>
+                        {projectHealthWarnings.map((item) => <li key={item.label}>{item.detail}</li>)}
+                      </ul>
+                    </div>
+                  </Callout>
+                ) : null}
+                <div style={{ display: "grid", gap: 8 }}>
+                  <label style={{ fontSize: 12, color: tokens.muted }}>Use existing project</label>
+                  <fieldset
+                    disabled={projectBusy}
+                    style={{ border: 0, margin: 0, minWidth: 0, padding: 0 }}
+                  >
+                    <ProjectPicker
+                      companyId={context.companyId}
+                      value={effectiveSelectedProjectId}
+                      includeArchived
+                      placeholder="Project"
+                      noneLabel="No project"
+                      searchPlaceholder="Search projects..."
+                      emptyMessage="No projects found."
+                      onChange={setSelectedProjectId}
+                    />
+                  </fieldset>
+                  <Tiny>
+                    Status: {projectStatusLabel(currentProjectOption?.status ?? data.managedProject.details?.status ?? data.managedProject.status)}
+                  </Tiny>
+                  <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
+                    <Button size="sm" variant="primary" onClick={chooseProject} loading={projectBusy} disabled={!effectiveSelectedProjectId}>Save project</Button>
+                    {projectLink ? <Button size="sm" onClick={() => hostNavigation.navigate(projectLink)}>Open project ↗</Button> : null}
+                    <Button size="sm" variant="ghost" onClick={async () => {
+                      if (!context.companyId) return;
+                      setProjectBusy(true);
+                      try {
+                        await reconcileProject({ companyId: context.companyId });
+                        toast({ tone: "success", title: "Project reconciled" });
+                        settings.refresh();
+                      } catch (err) {
+                        toast({ tone: "error", title: "Reconcile failed", body: err instanceof Error ? err.message : String(err) });
+                      } finally {
+                        setProjectBusy(false);
+                      }
+                    }} loading={projectBusy}>Repair / reconcile</Button>
+                    <Button size="sm" variant="ghost" onClick={async () => {
+                      if (!context.companyId) return;
+                      setProjectBusy(true);
+                      try {
+                        await resetProject({ companyId: context.companyId });
+                        toast({ tone: "success", title: "Project reset to plugin defaults" });
+                        settings.refresh();
+                      } catch (err) {
+                        toast({ tone: "error", title: "Reset failed", body: err instanceof Error ? err.message : String(err) });
+                      } finally {
+                        setProjectBusy(false);
+                      }
+                    }} loading={projectBusy}>↺ Reset to plugin defaults</Button>
+                  </div>
+                </div>
+              </div>
+            </SetupSection>
+            <SetupSection title="Managed Routines" separated>
+              <div style={{ display: "grid", gap: 12, maxWidth: isMobile ? "none" : 620, minWidth: 0 }}>
+                <RoutineHealthChecklist items={routineHealthItems} />
+                {routineHealthWarnings.length > 0 ? (
+                  <Callout tone="warn">
+                    <div style={{ display: "grid", gap: 8 }}>
+                      <div>{routineHealthWarnings.length} routine issue(s) need attention.</div>
+                      <ul style={{ margin: 0, paddingLeft: 18 }}>
+                        {routineHealthWarnings.map((item) => <li key={item.label}>{item.detail}</li>)}
+                      </ul>
+                      <div>
+                        <Button size="sm" variant="primary" onClick={repairManagedRoutines} loading={routineRepairBusy}>Fix routines</Button>
+                      </div>
+                    </div>
+                  </Callout>
+                ) : routineDefaultDriftItems.length > 0 ? (
+                  <Callout tone="warn">
+                    <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12, flexWrap: "wrap" }}>
+                      <span>{routineDefaultDriftItems.length} routine default update{routineDefaultDriftItems.length === 1 ? "" : "s"} available.</span>
+                      <Button size="sm" variant="primary" onClick={() => {
+                        setActiveSettingsSection("routines");
+                        hostNavigation.navigate(buildSettingsSectionHref("routines", activeSpaceSlug));
+                      }}>Review defaults</Button>
+                    </div>
+                  </Callout>
+                ) : (
+                  <Tiny>Managed routines are installed with the Wiki Maintainer and LLM Wiki project.</Tiny>
+                )}
+              </div>
+            </SetupSection>
+          </section>
+        ) : activeSettingsSection === "distillation" ? (
+          <SettingsPanel
+            title="Distillation"
+            badge={<Badge tone="default">Default space only</Badge>}
+            description="Read Paperclip issues, comments, and documents for this company and write project pages into the default wiki space. Assets/attachments and work products stay metadata-only in Phase 5 and are excluded from source-text extraction. Other spaces cannot be selected as a destination yet - that lands with per-space Paperclip ingestion profiles."
+          >
+            <DistillationSettingsPanel context={context} settings={data} />
+          </SettingsPanel>
+        ) : activeSettingsSection === "routines" ? (
+          <SettingsPanel title="Managed Routines" description={activeSettingsConfig.description}>
+          <div style={{ display: "grid", gap: 12 }}>
+            {routineDefaultDriftItems.length > 0 ? (
+              <Callout tone="warn">
+                <div style={{ display: "grid", gap: 6 }}>
+                  <strong>Routine defaults changed.</strong>
+                  <span>
+                    Review rows marked with changed defaults. Reset a row to update it to the current LLM Wiki instructions, or leave it unchanged to keep custom routine text.
+                  </span>
+                </div>
+              </Callout>
+            ) : null}
+            {routineHealthWarnings.length > 0 ? (
+              <Callout tone="warn">
+                <div style={{ display: "flex", alignItems: "flex-start", justifyContent: "space-between", gap: 12, flexWrap: "wrap" }}>
+                  <div style={{ display: "grid", gap: 6, minWidth: 0 }}>
+                    <strong>Routine setup needs repair.</strong>
+                    <ul style={{ margin: 0, paddingLeft: 18 }}>
+                      {routineHealthWarnings.map((item) => <li key={item.label}>{item.detail}</li>)}
+                    </ul>
+                  </div>
+                  <Button size="sm" variant="primary" onClick={repairManagedRoutines} loading={routineRepairBusy}>Fix routines</Button>
+                </div>
+              </Callout>
+            ) : (
+              <Callout>
+                <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: 12, flexWrap: "wrap" }}>
+                  <span>Managed routines are installed with the Wiki Maintainer and LLM Wiki project.</span>
+                  <Button size="sm" disabled>Routines valid</Button>
+                </div>
+              </Callout>
+            )}
+            <PluginManagedRoutinesList
+              routines={managedRoutineItems}
+              agents={maintainerAgentOptions}
+              projects={projectOptions}
+              pluginDisplayName="LLM Wiki"
+              runningRoutineKey={routineBusyKeyFor("run")}
+              statusMutationRoutineKey={routineBusyKeyFor("status")}
+              resettingRoutineKey={routineBusyKeyFor("reset")}
+              onRunNow={runManagedRoutineNow}
+              onToggleEnabled={toggleManagedRoutine}
+              onReset={resetManagedRoutineToDefaults}
+            />
+          </div>
+          </SettingsPanel>
+        ) : activeSettingsSection === "lint" ? (
+          <SettingsLintPanel context={context} />
+        ) : activeSettingsSection === "spaces" ? (
+          <SpacesSettingsPanel context={context} description={activeSettingsConfig.description} />
+        ) : activeSettingsSection === "events" ? (
+          <SettingsPanel
+            title="Paperclip event ingestion"
+            badge={<Badge tone={currentEventPolicy.enabled ? "running" : "default"}>{currentEventPolicy.enabled ? "enabled" : "off by default"}</Badge>}
+            description={activeSettingsConfig.description}
+          >
+          <Tiny style={{ marginBottom: 10 }}>
+            Company-scoped Paperclip events can advance default-space cursors. Enable only the first-party text sources this wiki should observe for default-space distillation.
+          </Tiny>
+          <div style={{ display: "grid", gap: 10 }}>
+            <label style={{ display: "flex", gap: 8, alignItems: "center", fontSize: 13 }}>
+              <input
+                type="checkbox"
+                checked={currentEventPolicy.enabled}
+                onChange={(event) => setEventPolicy({ ...currentEventPolicy, enabled: event.currentTarget.checked })}
+              />
+              Enable event ingestion for this company
+            </label>
+            <div style={{ display: "grid", gap: 8, paddingLeft: isMobile ? 0 : 22 }}>
+              {([
+                ["issues", "Issues", "Capture issue title and description when issue events fire."],
+                ["comments", "Comments", "Capture comment body when comment-created events fire."],
+                ["documents", "Documents", "Capture document body when document-created or document-updated events fire."],
+              ] as const).map(([key, label, help]) => (
+                <label key={key} style={{ display: "grid", gridTemplateColumns: "auto 1fr", columnGap: 8, rowGap: 2, alignItems: "start", fontSize: 13 }}>
+                  <input
+                    type="checkbox"
+                    checked={currentEventPolicy.sources[key]}
+                    onChange={(event) => setEventPolicy({
+                      ...currentEventPolicy,
+                      sources: { ...currentEventPolicy.sources, [key]: event.currentTarget.checked },
+                    })}
+                  />
+                  <span>
+                    {label}
+                    <Tiny style={{ display: "block" }}>{help}</Tiny>
+                  </span>
+                </label>
+              ))}
+            </div>
+            <div style={{ display: "grid", gap: 6, maxWidth: isMobile ? "none" : 220 }}>
+              <label style={{ fontSize: 12, color: tokens.muted }}>Max characters per captured event</label>
+              <TextInput
+                value={String(currentEventPolicy.maxCharacters)}
+                onChange={(event) => {
+                  const parsed = Number(event.currentTarget.value);
+                  setEventPolicy({ ...currentEventPolicy, maxCharacters: Number.isFinite(parsed) ? parsed : currentEventPolicy.maxCharacters });
+                }}
+              />
+            </div>
+            <Callout tone="warn">
+              Event ingestion records selected Paperclip issue, comment, and document activity for the default wiki space. Assets/attachments and work products are excluded here: Phase 5 allows metadata-only references later, not blob reads or linked-content fetches. It never reads across companies or creates non-default space cursors.
+            </Callout>
+            <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
+              <Button size="sm" variant="primary" onClick={saveEventPolicy} loading={eventPolicyBusy}>Save controls</Button>
+              <Button size="sm" variant="ghost" onClick={() => setEventPolicy(data.eventIngestion)}>Revert</Button>
+            </div>
+          </div>
+          </SettingsPanel>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Spaces settings — list of spaces with sub-nav and a per-space edit panel.
+// Reachable via /wiki/settings/spaces or /wiki/settings/spaces/<slug>.
+// ---------------------------------------------------------------------------
+
+function SpacesSettingsPanel({ context, description }: { context: { companyId: string | null; companyPrefix?: string | null }; description: string }) {
+  const { pathname } = useHostLocation();
+  const hostNavigation = useHostNavigation();
+  const activeSpaceSlug = useMemo(() => readActiveSpaceSlugFromLocation(pathname), [pathname]);
+  const editingSlug = useMemo(() => readSettingsSpaceSlugFromLocation(pathname), [pathname]);
+  const isMobile = useIsMobileLayout();
+  const spacesQuery = useSpaces(context.companyId);
+  const spaces = useMemo(() => {
+    const list = spacesQuery.data?.spaces ?? [];
+    return activeWikiSpaces(list).sort(compareSpaces);
+  }, [spacesQuery.data]);
+  const [createOpen, setCreateOpen] = useState(false);
+
+  const focusedSpace = useMemo(() => {
+    if (editingSlug) return spaces.find((s) => s.slug === editingSlug) ?? null;
+    return spaces.find((s) => s.slug === activeSpaceSlug) ?? spaces.find((s) => s.slug === DEFAULT_SPACE_SLUG) ?? spaces[0] ?? null;
+  }, [editingSlug, spaces, activeSpaceSlug]);
+
+  return (
+    <SettingsPanel title="Shared spaces" description={description}>
+      <div style={{ display: "grid", gridTemplateColumns: isMobile ? "1fr" : "220px 1fr", gap: 18, alignItems: "flex-start" }}>
+        <aside style={{ display: "grid", gap: 4, minWidth: 0 }}>
+          {spaces.map((space) => {
+            const active = focusedSpace?.slug === space.slug;
+            return (
+              <button
+                key={space.slug}
+                type="button"
+                onClick={() => hostNavigation.navigate(buildSettingsSectionHref("spaces", activeSpaceSlug, space.slug))}
+                style={{
+                  textAlign: "left",
+                  background: active ? tokens.accent : "transparent",
+                  border: `1px solid ${active ? tokens.border : "transparent"}`,
+                  borderRadius: 6,
+                  padding: "8px 10px",
+                  color: tokens.fg,
+                  cursor: "pointer",
+                  fontFamily: fontStack,
+                  display: "grid",
+                  gap: 2,
+                }}
+              >
+                <span style={{ fontSize: 13, fontWeight: 600 }}>{space.displayName}</span>
+                <span style={{ fontSize: 11, color: tokens.muted, fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace" }}>{space.slug}</span>
+              </button>
+            );
+          })}
+          <button
+            type="button"
+            onClick={() => setCreateOpen(true)}
+            style={{
+              textAlign: "left",
+              background: "transparent",
+              border: `1px dashed ${tokens.border}`,
+              borderRadius: 6,
+              padding: "8px 10px",
+              color: "oklch(0.78 0.13 250)",
+              cursor: "pointer",
+              fontFamily: fontStack,
+              display: "flex",
+              alignItems: "center",
+              gap: 8,
+              fontSize: 13,
+              fontWeight: 600,
+              marginTop: 6,
+            }}
+          >
+            <PlusIcon size={14} />
+            Add space…
+          </button>
+        </aside>
+        <div style={{ minWidth: 0, display: "grid", gap: 14 }}>
+          {spacesQuery.loading && spaces.length === 0 ? <Tiny>Loading spaces…</Tiny> : null}
+          {spacesQuery.error ? <Callout tone="danger">Failed to load spaces: {spacesQuery.error.message}</Callout> : null}
+          {focusedSpace ? (
+            <SpaceEditCard
+              space={focusedSpace}
+              companyId={context.companyId}
+              isOnlySpace={spaces.length === 1}
+              refresh={spacesQuery.refresh}
+              onArchived={() => {
+                hostNavigation.navigate(buildSettingsSectionHref("spaces", activeSpaceSlug));
+              }}
+            />
+          ) : (
+            <Callout>Pick a space from the list, or create one with the “Add space…” button.</Callout>
+          )}
+        </div>
+      </div>
+      {createOpen && context.companyId ? (
+        <CreateSpaceModal
+          companyId={context.companyId}
+          existingSlugs={new Set(spaces.map((s) => s.slug))}
+          onClose={() => setCreateOpen(false)}
+          onCreated={(space) => {
+            setCreateOpen(false);
+            spacesQuery.refresh();
+            hostNavigation.navigate(buildSettingsSectionHref("spaces", activeSpaceSlug, space.slug));
+          }}
+        />
+      ) : null}
+    </SettingsPanel>
+  );
+}
+
+function SpaceEditCard({
+  space,
+  companyId,
+  isOnlySpace,
+  refresh,
+  onArchived,
+}: {
+  space: WikiSpace;
+  companyId: string | null;
+  isOnlySpace: boolean;
+  refresh: () => void;
+  onArchived: () => void;
+}) {
+  const updateSpace = usePluginAction("update-space");
+  const archiveSpace = usePluginAction("archive-space");
+  const bootstrapSpace = usePluginAction("bootstrap-space");
+  const folderStatusQuery = useSpaceFolderStatus(companyId, space.slug);
+  const toast = usePluginToast();
+  const isDefault = space.slug === DEFAULT_SPACE_SLUG;
+  const [displayName, setDisplayName] = useState(space.displayName);
+  const [busy, setBusy] = useState(false);
+  const [folderBusy, setFolderBusy] = useState(false);
+  const [archiveBusy, setArchiveBusy] = useState(false);
+
+  useEffect(() => {
+    setDisplayName(space.displayName);
+  }, [space.slug, space.displayName]);
+
+  const folder = folderStatusQuery.data?.folder ?? null;
+  const relativeRoot = folderStatusQuery.data?.relativeRoot ?? "";
+  const settingsRecord = (space.settings ?? {}) as Record<string, unknown>;
+  const folderModeLabel = space.folderMode === "managed_subfolder"
+    ? "New managed folder (under wiki root)"
+    : space.folderMode === "existing_local_folder"
+      ? "Existing folder under wiki root"
+      : space.folderMode;
+
+  async function saveName() {
+    if (!companyId || displayName.trim().length === 0 || displayName.trim() === space.displayName) return;
+    setBusy(true);
+    try {
+      await updateSpace({ companyId, spaceSlug: space.slug, displayName: displayName.trim() });
+      toast({ tone: "success", title: "Display name updated" });
+      refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Update failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function recreateBaseline() {
+    if (!companyId || folderBusy) return;
+    setFolderBusy(true);
+    try {
+      await bootstrapSpace({ companyId, spaceSlug: space.slug });
+      toast({ tone: "success", title: "Baseline restored", body: `Re-created the standard skeleton for ${space.displayName}.` });
+      folderStatusQuery.refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Bootstrap failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setFolderBusy(false);
+    }
+  }
+
+  async function archive() {
+    if (!companyId || isDefault || isOnlySpace || archiveBusy) return;
+    if (typeof window !== "undefined" && !window.confirm(`Archive ${space.displayName}? Pages stay on disk; you can restore later through the plugin API or by un-archiving from the database.`)) {
+      return;
+    }
+    setArchiveBusy(true);
+    try {
+      await archiveSpace({ companyId, spaceSlug: space.slug });
+      toast({ tone: "success", title: "Space archived", body: `${space.displayName} hidden from the sidebar.` });
+      refresh();
+      onArchived();
+    } catch (err) {
+      toast({ tone: "error", title: "Archive failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setArchiveBusy(false);
+    }
+  }
+
+  return (
+    <div style={{ display: "grid", gap: 12 }}>
+      <Card>
+        <CardHeader
+          title={
+            <span style={{ display: "flex", alignItems: "center", gap: 8 }}>
+              <FolderIcon size={16} />
+              <span>{space.displayName}</span>
+              <Badge tone="default" style={{ fontSize: 10 }}>{space.slug}</Badge>
+              <Badge tone={space.status === "active" ? "running" : "default"} style={{ fontSize: 10 }}>{space.status}</Badge>
+            </span>
+          }
+          right={
+            <span style={{ fontSize: 11, color: tokens.muted }}>
+              {space.spaceType} · {space.accessScope}
+            </span>
+          }
+        />
+        <CardBody>
+          <Tiny>
+            Stored under <Mono>{relativeRoot || (isDefault ? "(wiki root)" : `spaces/${space.slug}/`)}</Mono> within the configured wiki root.
+          </Tiny>
+        </CardBody>
+      </Card>
+
+      <Card>
+        <CardHeader title="Identity" />
+        <CardBody>
+          <div style={{ display: "grid", gap: 12 }}>
+            <FormField label="Display name">
+              <TextInput value={displayName} onChange={(event) => setDisplayName(event.target.value)} maxLength={120} />
+            </FormField>
+            <FormField label="Slug" help="Slug is locked once a space has indexed pages. Contact platform team to migrate.">
+              <TextInput value={space.slug} disabled style={{ fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace", opacity: 0.7 }} />
+            </FormField>
+            <FormField label="Type" help="(Cloud connectors coming soon)">
+              <TextInput value={space.spaceType === "managed" ? "Folder" : space.spaceType} disabled style={{ opacity: 0.7 }} />
+            </FormField>
+            <div>
+              <Button variant="primary" size="sm" onClick={saveName} disabled={busy || displayName.trim() === space.displayName} loading={busy}>Save name</Button>
+            </div>
+          </div>
+        </CardBody>
+      </Card>
+
+      <Card>
+        <CardHeader title="Folder source & health" />
+        <CardBody>
+          <div style={{ display: "grid", gap: 12 }}>
+            <FormField label="Mode">
+              <TextInput value={folderModeLabel} disabled style={{ opacity: 0.7 }} />
+            </FormField>
+            <FormField label="Path">
+              <TextInput value={folder?.path ?? folder?.realPath ?? relativeRoot ?? "(unconfigured)"} disabled style={{ fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace", opacity: 0.7 }} />
+            </FormField>
+            {folderStatusQuery.loading ? <Tiny>Loading folder status…</Tiny> : null}
+            {folderStatusQuery.error ? <Callout tone="danger">{folderStatusQuery.error.message}</Callout> : null}
+            {folder ? <SpaceFolderHealthChecklist folder={folder} /> : null}
+            <div>
+              <Button size="sm" onClick={recreateBaseline} loading={folderBusy}>Recreate baseline</Button>
+            </div>
+          </div>
+        </CardBody>
+      </Card>
+
+      <PaperclipIngestionSpaceCard companyId={companyId} space={space} refresh={refresh} />
+
+      <Card style={{ opacity: 0.56 }}>
+        <CardHeader title="Access" />
+        <CardBody>
+          <div aria-disabled="true" style={{ display: "grid", gap: 10 }}>
+            <div style={{ display: "flex", gap: 6, flexWrap: "wrap" }}>
+              <Badge tone="default" style={{ fontSize: 10 }}>{space.accessScope}</Badge>
+              <Badge tone="default" style={{ fontSize: 10 }}>Coming soon</Badge>
+            </div>
+            <Tiny>
+              Access scope is stored as metadata only. <Mono>shared</Mono>, <Mono>team</Mono>, and{" "}
+              <Mono>personal</Mono> are saved on the space record but do not currently enforce
+              read/write permissions, and they do not change which Paperclip sources reach this space.
+            </Tiny>
+            <FormField label="Owner user id">
+              <TextInput value={(settingsRecord.ownerUserHint as string | undefined) ?? space.ownerUserId ?? ""} disabled style={{ fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace" }} />
+            </FormField>
+            <FormField label="Owner team key">
+              <TextInput value={space.teamKey ?? ""} disabled style={{ fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace" }} />
+            </FormField>
+          </div>
+        </CardBody>
+      </Card>
+
+      <Card style={{ borderColor: "oklch(0.5 0.18 25)" }}>
+        <CardHeader
+          title={<span style={{ color: "oklch(0.78 0.18 25)" }}>Danger zone</span>}
+        />
+        <CardBody>
+          <div style={{ display: "grid", gap: 8 }}>
+            <Tiny>
+              {isDefault
+                ? "The default space cannot be archived because new operations and tools fall back to it."
+                : isOnlySpace
+                  ? "This is the only space in the company. Create another before archiving this one."
+                  : "Archiving hides the space from the sidebar and pauses scheduled lint/index. Pages remain on disk."}
+            </Tiny>
+            <div>
+              <Button
+                variant="destructive"
+                size="sm"
+                onClick={archive}
+                disabled={isDefault || isOnlySpace || archiveBusy}
+                loading={archiveBusy}
+                title={isDefault ? "Default space cannot be archived" : isOnlySpace ? "At least one space must remain" : undefined}
+              >
+                Archive this space
+              </Button>
+            </div>
+          </div>
+        </CardBody>
+      </Card>
+    </div>
+  );
+}
+
+function paperclipIngestionStateBadge(data: PaperclipIngestionProfileData | null): { tone: Tone; label: string } {
+  if (!data) return { tone: "default", label: "Loading" };
+  if (data.effectiveState === "policy_blocked") return { tone: "blocked", label: "Locked" };
+  if (data.effectiveState === "pending_approval") return { tone: "queued", label: "Pending approval" };
+  if (data.effectiveState === "enabled_no_scopes") return { tone: "failed", label: "Misconfigured" };
+  if (data.effectiveState === "enabled") return { tone: "running", label: `On · ${data.profile.sourceScopes.length} source${data.profile.sourceScopes.length === 1 ? "" : "s"}` };
+  return { tone: "default", label: data.historicalPageCount > 0 ? `Off · ${data.historicalPageCount} historical pages` : "Off" };
+}
+
+function PaperclipIngestionSpaceCard({ companyId, space, refresh }: { companyId: string | null; space: WikiSpace; refresh: () => void }) {
+  const profileQuery = usePaperclipIngestionProfile(companyId, space.slug);
+  const updateProfile = usePluginAction("update-paperclip-ingestion-profile");
+  const toast = usePluginToast();
+  const data = profileQuery.data ?? null;
+  const [draft, setDraft] = useState<PaperclipIngestionProfile | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  useEffect(() => {
+    setDraft(data?.profile ?? null);
+  }, [data?.space.slug, data?.profile]);
+
+  const badge = paperclipIngestionStateBadge(data);
+  const locked = data?.effectiveState === "policy_blocked";
+  const sourceScope = draft?.sourceScopes[0];
+  const activeProjectLimit = sourceScope?.kind === "active_projects" ? sourceScope.limit : 3;
+  const canSave = Boolean(companyId && draft && !busy && !locked);
+  const emptyScopes = Boolean(draft?.enabled && draft.sourceScopes.length === 0);
+
+  function patchDraft(patch: Partial<PaperclipIngestionProfile>) {
+    setDraft((current) => current ? { ...current, ...patch } : current);
+  }
+
+  function setSourceKind(key: WikiEventIngestionSource, value: boolean) {
+    setDraft((current) => current
+      ? { ...current, sourceKinds: { ...current.sourceKinds, [key]: value } }
+      : current);
+  }
+
+  function setActiveProjectsLimit(value: number) {
+    setDraft((current) => current
+      ? {
+          ...current,
+          sourceScopes: [{ kind: "active_projects", limit: Math.max(1, Math.floor(value || 1)) }],
+        }
+      : current);
+  }
+
+  async function save() {
+    if (!companyId || !draft || locked) return;
+    setBusy(true);
+    try {
+      await updateProfile({ companyId, spaceSlug: space.slug, profile: draft });
+      toast({ tone: "success", title: "Paperclip ingestion profile saved", body: `${space.displayName} will use the selected Paperclip sources.` });
+      profileQuery.refresh();
+      refresh();
+    } catch (err) {
+      toast({ tone: "error", title: "Profile save failed", body: err instanceof Error ? err.message : String(err) });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <Card>
+      <CardHeader
+        title={<span>Paperclip → {space.displayName}</span>}
+        right={<Badge tone={badge.tone} style={{ fontSize: 10 }}>{badge.label}</Badge>}
+      />
+      <CardBody>
+        <div style={{ display: "grid", gap: 12 }}>
+          {profileQuery.loading && !data ? <Tiny>Loading Paperclip ingestion profile…</Tiny> : null}
+          {profileQuery.error ? <Callout tone="danger">{profileQuery.error.message}</Callout> : null}
+          {locked ? (
+            <Callout tone="warn">
+              Locked — host permissions pending. Paperclip ingestion stays disabled on team and personal spaces until LLM Wiki enforces read/write permissions for non-shared spaces.
+            </Callout>
+          ) : null}
+          {data && data.historicalPageCount > 0 && data.effectiveState === "disabled" ? (
+            <Callout>
+              Off · {data.historicalPageCount} historical Paperclip page{data.historicalPageCount === 1 ? "" : "s"} still in this space. Disabling stops new observations but does not delete prior wiki pages.
+            </Callout>
+          ) : null}
+          {data && data.overlapCount > 0 ? (
+            <Callout>
+              {data.overlapCount} source overlap{data.overlapCount === 1 ? "" : "s"} with another enabled space. Duplicate destinations are allowed, but they are explicit.
+            </Callout>
+          ) : null}
+          {emptyScopes ? <Callout tone="warn">Pick at least one source scope before saving.</Callout> : null}
+          {draft ? (
+            <>
+              <label style={{ display: "flex", gap: 8, alignItems: "flex-start", fontSize: 13 }}>
+                <input
+                  type="checkbox"
+                  checked={draft.enabled}
+                  disabled={locked || busy}
+                  onChange={(event) => patchDraft({
+                    enabled: event.currentTarget.checked,
+                    sourceScopes: event.currentTarget.checked && draft.sourceScopes.length === 0
+                      ? [{ kind: "active_projects", limit: activeProjectLimit }]
+                      : draft.sourceScopes,
+                  })}
+                />
+                <span>
+                  Enable Paperclip ingestion for this destination space
+                  <Tiny style={{ display: "block" }}>Future Paperclip issue, comment, and document events can advance cursors in {space.displayName}. Existing pages are preserved when this is turned off.</Tiny>
+                </span>
+              </label>
+              <div style={{ display: "grid", gap: 8 }}>
+                <strong style={{ fontSize: 13 }}>Source scope</strong>
+                <label style={{ display: "grid", gap: 6, maxWidth: 260 }}>
+                  <Tiny>Recently active projects (auto)</Tiny>
+                  <TextInput
+                    value={String(activeProjectLimit)}
+                    disabled={locked || busy}
+                    onChange={(event) => setActiveProjectsLimit(Number(event.currentTarget.value))}
+                  />
+                </label>
+                <Tiny>Specific projects, issue trees, and company-wide ingestion use the same profile API; this first editor keeps the default auto-scope path visible and capped.</Tiny>
+              </div>
+              <div style={{ display: "grid", gap: 8 }}>
+                <strong style={{ fontSize: 13 }}>Source kinds</strong>
+                {([
+                  ["issues", "Issues"],
+                  ["comments", "Comments"],
+                  ["documents", "Documents"],
+                ] as const).map(([key, label]) => (
+                  <label key={key} style={{ display: "flex", gap: 8, alignItems: "center", fontSize: 13 }}>
+                    <input
+                      type="checkbox"
+                      checked={draft.sourceKinds[key]}
+                      disabled={locked || busy}
+                      onChange={(event) => setSourceKind(key, event.currentTarget.checked)}
+                    />
+                    {label}
+                  </label>
+                ))}
+                <Tiny>Attachments — locked, metadata only; no file contents. Future extraction needs separate review.</Tiny>
+                <Tiny>Work products — locked, metadata only; no artifact contents.</Tiny>
+              </div>
+              <div style={{ display: "grid", gap: 8 }}>
+                <strong style={{ fontSize: 13 }}>Caps</strong>
+                <Tiny>
+                  Defaults: {draft.cursor.maxWindowCharacters.toLocaleString()} chars/window · {draft.cursor.maxCharactersPerSource.toLocaleString()} chars/source.
+                </Tiny>
+              </div>
+              <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
+                <Button size="sm" variant="primary" onClick={save} loading={busy} disabled={!canSave || emptyScopes}>Save Paperclip profile</Button>
+                <Button size="sm" variant="ghost" onClick={() => setDraft(data?.profile ?? null)} disabled={busy}>Revert</Button>
+              </div>
+            </>
+          ) : null}
+        </div>
+      </CardBody>
+    </Card>
+  );
+}
+
+function SpaceFolderHealthChecklist({ folder }: { folder: FolderStatus }) {
+  const items = [
+    { key: "readable", label: "Folder readable", ok: folder.readable },
+    { key: "writable", label: "Folder writable", ok: folder.writable },
+    ...folder.requiredDirectories.map((dir) => ({
+      key: `dir-${dir}`,
+      label: `${dir}/ present`,
+      ok: !folder.missingDirectories.includes(dir),
+    })),
+    ...folder.requiredFiles.map((file) => ({
+      key: `file-${file}`,
+      label: `${file} present`,
+      ok: !folder.missingFiles.includes(file),
+    })),
+  ];
+
+  return (
+    <div role="list" aria-label="Space folder health checklist" style={{ position: "relative", display: "grid", gap: 0, padding: "2px 0" }}>
+      {items.length > 1 ? (
+        <span
+          aria-hidden
+          style={{
+            position: "absolute",
+            left: 8,
+            top: 12,
+            bottom: 12,
+            width: 1,
+            background: "oklch(0.38 0.09 145)",
+          }}
+        />
+      ) : null}
+      {items.map((item) => (
+        <div
+          key={item.key}
+          role="listitem"
+          style={{
+            display: "grid",
+            gridTemplateColumns: "18px minmax(0, 1fr)",
+            alignItems: "center",
+            gap: 10,
+            padding: "7px 0",
+            minWidth: 0,
+          }}
+        >
+          <span style={{ display: "inline-flex", justifyContent: "center", position: "relative", zIndex: 1, background: tokens.bg }}>
+            <StatusIcon status={item.ok ? "done" : "blocked"} />
+          </span>
+          <span style={{ fontSize: 13, fontWeight: 600, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", color: item.ok ? tokens.fg : "oklch(0.85 0.1 70)" }}>
+            {item.label}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}
diff --git a/packages/plugins/plugin-llm-wiki/src/ui/index.tsx b/packages/plugins/plugin-llm-wiki/src/ui/index.tsx
new file mode 100644
index 00000000..f8f8bf1f
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/src/ui/index.tsx
@@ -0,0 +1 @@
+export { SidebarLink, SettingsPage, WikiPage, WikiRouteSidebar } from "./app.js";
diff --git a/packages/plugins/plugin-llm-wiki/src/ui/issue-attachments.ts b/packages/plugins/plugin-llm-wiki/src/ui/issue-attachments.ts
new file mode 100644
index 00000000..7e399bc7
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/src/ui/issue-attachments.ts
@@ -0,0 +1,49 @@
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+
+export type IngestSourceActionResult = {
+  operation?: {
+    issue?: {
+      id?: unknown;
+    } | null;
+  } | null;
+};
+
+export function readIngestOperationIssueId(result: unknown): string {
+  const issueId = (result as IngestSourceActionResult | null)?.operation?.issue?.id;
+  if (typeof issueId === "string" && issueId.trim()) return issueId;
+  throw new Error("Ingest operation did not return an issue id; the dropped file could not be attached.");
+}
+
+async function readUploadError(response: Response): Promise<string> {
+  const body = await response.json().catch(() => null);
+  if (body && typeof body === "object") {
+    const error = (body as { error?: unknown; message?: unknown }).error;
+    if (typeof error === "string" && error.trim()) return error;
+    const message = (body as { error?: unknown; message?: unknown }).message;
+    if (typeof message === "string" && message.trim()) return message;
+  }
+  return `Attachment upload failed with HTTP ${response.status}.`;
+}
+
+export async function uploadIssueAttachmentFile(input: {
+  companyId: string;
+  issueId: string;
+  file: File;
+  fetchImpl?: FetchLike;
+}): Promise<unknown> {
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const form = new FormData();
+  form.append("file", input.file);
+  const response = await fetchImpl(
+    `/api/companies/${encodeURIComponent(input.companyId)}/issues/${encodeURIComponent(input.issueId)}/attachments`,
+    {
+      method: "POST",
+      credentials: "include",
+      body: form,
+    },
+  );
+  if (!response.ok) {
+    throw new Error(await readUploadError(response));
+  }
+  return response.json();
+}
diff --git a/packages/plugins/plugin-llm-wiki/src/wiki.ts b/packages/plugins/plugin-llm-wiki/src/wiki.ts
new file mode 100644
index 00000000..a1eddeac
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/src/wiki.ts
@@ -0,0 +1 @@
+export * from "./wiki/core.js";
diff --git a/packages/plugins/plugin-llm-wiki/src/wiki/core.ts b/packages/plugins/plugin-llm-wiki/src/wiki/core.ts
new file mode 100644
index 00000000..a969bd36
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/src/wiki/core.ts
@@ -0,0 +1,4980 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { Agent, AgentSessionEvent, Issue, IssueComment, PluginContext, PluginEvent, PluginLocalFolderEntry, Project, ToolResult } from "@paperclipai/plugin-sdk";
+import type { IssueDocument, PluginIssueOriginKind, PluginManagedRoutineResolution, PluginManagedSkillResolution } from "@paperclipai/plugin-sdk/types";
+import {
+  DEFAULT_MAX_SOURCE_BYTES,
+  DEFAULT_MAX_PAPERCLIP_CURSOR_WINDOW_CHARS,
+  DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS,
+  DEFAULT_MAX_PAPERCLIP_ROUTINE_RUN_CHARS,
+  DEFAULT_PAPERCLIP_COST_CENTS_PER_1K_CHARS,
+  PLUGIN_ID,
+  WIKI_MAINTAINER_AGENT_KEY,
+  WIKI_MANAGED_SKILL_KEYS,
+  WIKI_MAINTENANCE_ROUTINE_KEYS,
+  WIKI_PROJECT_KEY,
+  WIKI_ROOT_FOLDER_KEY,
+} from "../manifest.js";
+import {
+  BOOTSTRAP_FILES,
+  LINT_PROMPT,
+  QUERY_PROMPT,
+  REQUIRED_WIKI_DIRECTORIES,
+  REQUIRED_WIKI_FILES,
+} from "../templates.js";
+
+export const DEFAULT_WIKI_ID = "default";
+export const DEFAULT_SPACE_SLUG = "default";
+export const OPERATION_ORIGIN_KIND = `plugin:${PLUGIN_ID}:operation` as PluginIssueOriginKind;
+const EVENT_INGESTION_STATE_NAMESPACE = "llm-wiki";
+const EVENT_INGESTION_STATE_KEY = "event-ingestion";
+const EVENT_INGESTION_DEDUP_NAMESPACE = "llm-wiki-event-ingestion";
+const MAX_EVENT_SOURCE_CHARS = 20000;
+const MAX_PAPERCLIP_INGESTION_PROFILE_SOURCE_COUNT = 3;
+const MAX_PAPERCLIP_DISTILLATION_FAN_OUT = 25;
+const MAX_PAPERCLIP_PROFILE_SELECTED_PROJECTS = 25;
+const MAX_PAPERCLIP_PROFILE_ROOT_ISSUES = 25;
+const PROTECTED_WIKI_CONTROL_FILES = new Set(["AGENTS.md", "IDEA.md"]);
+export const PUBLIC_DISTILLATION_AUTO_APPLY_RESTRICTION =
+  "Authenticated/public deployments always require manual review before wiki writes.";
+
+export type WikiEventIngestionSource = "issues" | "comments" | "documents";
+export type PaperclipDistillationScope = "company" | "project" | "root_issue";
+export type PaperclipDistillationWorkItemKind = "manual" | "retry" | "backfill" | "priority_override" | "review_patch";
+
+export type WikiEventIngestionSettings = {
+  enabled: boolean;
+  sources: Record<WikiEventIngestionSource, boolean>;
+  wikiId: string;
+  maxCharacters: number;
+};
+
+export type WikiEventIngestionSettingsUpdate = Omit<Partial<WikiEventIngestionSettings>, "sources"> & {
+  sources?: Partial<Record<WikiEventIngestionSource, boolean>>;
+};
+
+export type PaperclipIngestionSourceScope =
+  | { kind: "active_projects"; limit: number; statuses?: Array<"in_progress" | "todo" | "done"> }
+  | { kind: "selected_projects"; projectIds: string[] }
+  | { kind: "root_issues"; issueIds: string[] }
+  | { kind: "company_all"; requiresBoardConfirmation: true };
+
+export type PaperclipIngestionProfileV1 = {
+  version: 1;
+  enabled: boolean;
+  sourceScopes: PaperclipIngestionSourceScope[];
+  sourceKinds: Record<WikiEventIngestionSource, boolean> & {
+    attachments: "off" | "metadata_only";
+    workProducts: "off" | "metadata_only";
+  };
+  cursor: {
+    maxWindowCharacters: number;
+    maxCharactersPerSource: number;
+    minSourceAgeMinutes: number;
+    maxWindowsPerRun: number;
+    staleAfterHours: number;
+  };
+  backfill: {
+    defaultStartAt?: string | null;
+    defaultEndAt?: string | null;
+    requireManualQueue: boolean;
+  };
+};
+
+export type PaperclipIngestionProfileEffectiveState =
+  | "enabled"
+  | "disabled"
+  | "policy_blocked"
+  | "pending_approval"
+  | "enabled_no_scopes";
+
+export type PaperclipIngestionProfileRead = {
+  wikiId: string;
+  space: Pick<WikiSpace, "id" | "slug" | "displayName" | "accessScope" | "status">;
+  profile: PaperclipIngestionProfileV1;
+  effectiveState: PaperclipIngestionProfileEffectiveState;
+  policyBlocks: string[];
+  historicalPageCount: number;
+  overlapCount: number;
+};
+
+export type DistillationAutoApplyRestriction = {
+  autoApplyAllowed: boolean;
+  autoApplyRestriction: string | null;
+  deploymentMode: "local_trusted" | "authenticated" | null;
+  deploymentExposure: "private" | "public" | null;
+};
+
+type PaperclipIngestionPolicyPurpose =
+  | "profile_read"
+  | "profile_update"
+  | "candidate_search"
+  | "queue"
+  | "execute"
+  | "event_routing";
+
+type PaperclipIngestionPolicyDecision =
+  | { allowed: true; space: WikiSpace }
+  | { allowed: false; space: WikiSpace; reason: "restricted_space" | "archived_space" | "profile_disabled" | "profile_empty"; message: string };
+
+type PaperclipIngestionCandidatesInput = SpaceInput & {
+  query?: string | null;
+};
+
+export type EnableActiveProjectDistillationResult = {
+  wikiId: string;
+  spaceSlug: string;
+  selectedProjects: Array<{
+    id: string;
+    name: string;
+    status: string;
+    observedAt: string | null;
+    cursorId: string;
+  }>;
+  eventIngestion: WikiEventIngestionSettings;
+};
+
+export const DEFAULT_EVENT_INGESTION_SETTINGS: WikiEventIngestionSettings = {
+  enabled: false,
+  sources: {
+    issues: false,
+    comments: false,
+    documents: false,
+  },
+  wikiId: DEFAULT_WIKI_ID,
+  maxCharacters: 12000,
+};
+
+export type WikiOverview = {
+  status: "ok";
+  checkedAt: string;
+  wikiId: string;
+  defaultSpace: WikiSpace;
+  folder: Awaited<ReturnType<PluginContext["localFolders"]["status"]>>;
+  managedAgent: WikiAgentResource;
+  managedProject: WikiProjectResource;
+  managedSkills: WikiSkillResource[];
+  operationCount: number;
+  eventIngestion: WikiEventIngestionSettings;
+  capabilities: readonly string[];
+  prompts: {
+    query: string;
+    lint: string;
+  };
+};
+
+export type WikiAgentResource = {
+  status: "missing" | "resolved" | "created" | "relinked" | "reset";
+  source: "managed" | "selected";
+  agentId: string | null;
+  resourceKey: string;
+  agent: Agent | null;
+  details: { name: string; status: string; adapterType: string | null; icon?: string | null; urlKey?: string | null } | null;
+  defaultDrift?: { entryFile: string; changedFiles: string[] } | null;
+};
+
+export type WikiProjectResource = {
+  status: "missing" | "resolved" | "created" | "relinked" | "reset";
+  source: "managed" | "selected";
+  projectId: string | null;
+  resourceKey: string;
+  project: Project | null;
+  details: { name: string; status: string; color: string | null } | null;
+};
+
+export type WikiSkillResource = {
+  status: "missing" | "resolved" | "created" | "relinked" | "reset";
+  skillId: string | null;
+  resourceKey: string;
+  skill: PluginManagedSkillResolution["skill"];
+  details: { name: string; key: string; description: string | null } | null;
+  defaultDrift?: { changedFiles: string[] } | null;
+};
+
+export type WikiResourceOption = {
+  id: string;
+  name: string;
+  status?: string | null;
+  adapterType?: string | null;
+  color?: string | null;
+  icon?: string | null;
+  urlKey?: string | null;
+};
+
+export type WikiSpace = {
+  id: string;
+  companyId: string;
+  wikiId: string;
+  slug: string;
+  displayName: string;
+  spaceType: string;
+  folderMode: string;
+  rootFolderKey: string;
+  pathPrefix: string | null;
+  configuredRootPath: string | null;
+  accessScope: string;
+  ownerUserId: string | null;
+  ownerAgentId: string | null;
+  teamKey: string | null;
+  settings: Record<string, unknown>;
+  status: "active" | "archived" | string;
+  createdAt: string | null;
+  updatedAt: string | null;
+};
+
+export type WikiSpaceWithFolderStatus = WikiSpace & {
+  relativeRoot: string;
+  folder: Awaited<ReturnType<PluginContext["localFolders"]["status"]>>;
+};
+
+type BootstrapInput = {
+  companyId: string;
+  path?: string | null;
+};
+
+type SpaceInput = {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+};
+
+type CreateSpaceInput = {
+  companyId: string;
+  wikiId?: string | null;
+  slug?: string | null;
+  displayName?: string | null;
+  folderMode?: "managed_subfolder" | "existing_local_folder" | null;
+  accessScope?: "shared" | "personal" | "team" | null;
+  settings?: Record<string, unknown> | null;
+};
+
+type UpdateSpaceInput = SpaceInput & {
+  displayName?: string | null;
+  settings?: Record<string, unknown> | null;
+  status?: "active" | "archived" | null;
+};
+
+type OperationInput = {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  operationType: "ingest" | "query" | "lint" | "file-as-page" | "index" | "distill" | "backfill";
+  title?: string | null;
+  prompt?: string | null;
+  useCheapModelProfile?: boolean;
+};
+
+type OperationSpaceContext = {
+  wikiId: string;
+  space: WikiSpace;
+  operationType: OperationInput["operationType"];
+  operationId: string;
+  prompt?: string | null;
+};
+
+type QuerySessionInput = {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  question: string;
+  title?: string | null;
+};
+
+type CaptureSourceInput = {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  sourceType?: string | null;
+  title?: string | null;
+  url?: string | null;
+  contents: string;
+  rawPath?: string | null;
+  metadata?: Record<string, unknown> | null;
+};
+
+type PaperclipSourceBundleInput = {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  projectId?: string | null;
+  rootIssueId?: string | null;
+  maxCharacters?: number | null;
+  maxCharactersPerSource?: number | null;
+  backfillStartAt?: string | null;
+  backfillEndAt?: string | null;
+  routineRun?: boolean;
+  includeComments?: boolean;
+  includeDocuments?: boolean;
+  workItemId?: string | null;
+  operationIssueId?: string | null;
+};
+
+type PaperclipSourceRef = {
+  kind: "issue" | "comment" | "document";
+  issueId: string;
+  issueIdentifier: string | null;
+  projectId: string | null;
+  title?: string | null;
+  commentId?: string;
+  documentId?: string;
+  documentKey?: string;
+  updatedAt?: string;
+  createdAt?: string;
+  redactionStatus?: "suppressed_sensitive_content";
+  redactionReasons?: string[];
+};
+
+type PaperclipSourceBundle = {
+  markdown: string;
+  sourceRefs: PaperclipSourceRef[];
+  sourceHash: string;
+  sourceWindowStart: string | null;
+  sourceWindowEnd: string | null;
+  clipped: boolean;
+  warnings: string[];
+};
+
+type PaperclipDistillationRunInput = PaperclipSourceBundleInput;
+
+type PaperclipDistillationOutcomeInput = {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  runId: string;
+  cursorId?: string | null;
+  status: "succeeded" | "failed" | "review_required";
+  sourceHash?: string | null;
+  sourceWindowEnd?: string | null;
+  warning?: string | null;
+  costCents?: number | null;
+  retryCount?: number | null;
+};
+
+type PaperclipDistillationWorkItemInput = {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  kind: PaperclipDistillationWorkItemKind;
+  projectId?: string | null;
+  rootIssueId?: string | null;
+  requestedByIssueId?: string | null;
+  priority?: "critical" | "high" | "medium" | "low" | null;
+  idempotencyKey?: string | null;
+  metadata?: Record<string, unknown> | null;
+};
+
+type PaperclipProjectPageDistillationInput = PaperclipSourceBundleInput & {
+  autoApply?: boolean;
+  expectedProjectPageHash?: string | null;
+  includeSupportingPages?: boolean;
+};
+
+type WritePageInput = {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  path: string;
+  contents: string;
+  expectedHash?: string | null;
+  summary?: string | null;
+  sourceRefs?: unknown;
+  operationId?: string | null;
+  writer?: "agent_tool" | "board_ui" | "plugin_internal";
+};
+
+type FileQueryAnswerInput = {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  querySessionId?: string | null;
+  question?: string | null;
+  answer?: string | null;
+  path: string;
+  title?: string | null;
+  contents?: string | null;
+  expectedHash?: string | null;
+};
+
+type ToolParams = Record<string, unknown>;
+type WikiResourceKind = "agent" | "project";
+type PaperclipDistillationPatchOperation =
+  | "standup_update"
+  | "project_page_distill"
+  | "decision_distill"
+  | "history_distill"
+  | "index_refresh"
+  | "log_append";
+type PaperclipDistillationPatch = {
+  pagePath: string;
+  operationType: PaperclipDistillationPatchOperation;
+  currentHash: string | null;
+  proposedHash: string;
+  proposedContents: string;
+  sourceHash: string;
+  sourceRefs: PaperclipSourceRef[];
+  cursorWindow: {
+    start: string | null;
+    end: string | null;
+  };
+  confidence: "high" | "medium" | "low";
+  warnings: string[];
+  humanReviewRequired: boolean;
+};
+type PaperclipEventIngestResult =
+  | { status: "skipped"; reason: "disabled" | "source_disabled" | "unsupported_event" | "missing_issue" | "missing_comment" | "missing_document" | "plugin_operation" | "already_ingested" }
+  | { status: "recorded"; sourceKind: WikiEventIngestionSource; sourceId: string; cursorId: string; issueId: string };
+
+type WikiResourceBinding = {
+  resolvedId: string | null;
+  metadata: Record<string, unknown>;
+};
+
+function stringField(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function requireString(value: unknown, name: string): string {
+  const field = stringField(value);
+  if (!field) throw new Error(`${name} is required`);
+  return field;
+}
+
+function normalizeWikiId(value: unknown): string {
+  return stringField(value) ?? DEFAULT_WIKI_ID;
+}
+
+export function normalizeSpaceSlug(value: unknown): string {
+  const raw = stringField(value) ?? DEFAULT_SPACE_SLUG;
+  const normalized = raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!normalized) throw new Error("spaceSlug is required");
+  if (normalized.length > 64) throw new Error("spaceSlug must be 64 characters or fewer");
+  return normalized;
+}
+
+async function requirePaperclipIngestionPolicy(
+  ctx: PluginContext,
+  input: { companyId: string; wikiId: string; spaceSlug?: string | null },
+  purpose: PaperclipIngestionPolicyPurpose,
+  options: { requireEnabledProfile?: boolean } = {},
+): Promise<WikiSpace> {
+  const space = await resolveSpace(ctx, {
+    companyId: input.companyId,
+    wikiId: input.wikiId,
+    spaceSlug: input.spaceSlug,
+  });
+  const profile = await profileForSpace(ctx, input.companyId, space);
+  const decision = evaluatePaperclipProfilePolicy({
+    space,
+    profile,
+    purpose,
+    requireEnabledProfile: options.requireEnabledProfile,
+  });
+  if (!decision.allowed) throw new Error(decision.message);
+  return decision.space;
+}
+
+function assertPaperclipSourceScopePayload(input: { projectId?: string | null; rootIssueId?: string | null }) {
+  if (input.projectId && input.rootIssueId) {
+    throw new Error("Paperclip source scope must specify either projectId or rootIssueId, not both.");
+  }
+}
+
+function assertRequestedCharacterLimit(name: string, value: unknown, max: number) {
+  if (value == null) return;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    throw new Error(`${name} must be a positive number.`);
+  }
+  if (Math.floor(value) > max) {
+    throw new Error(`${name} exceeds the hard Paperclip ingestion cap of ${max} characters.`);
+  }
+}
+
+function stableSpaceId(input: { companyId: string; wikiId: string; slug: string }): string {
+  const hex = createHash("md5")
+    .update(`${input.companyId}:${input.wikiId}:${input.slug}`)
+    .digest("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-8${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+
+function normalizeLimit(value: unknown, fallback: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(1, Math.min(max, Math.floor(value)));
+}
+
+function contentHash(contents: string): string {
+  return createHash("sha256").update(contents, "utf8").digest("hex");
+}
+
+function byteLength(contents: string): number {
+  return Buffer.byteLength(contents, "utf8");
+}
+
+function slugify(value: string): string {
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "source";
+}
+
+function jsonParam(value: unknown): string {
+  return JSON.stringify(value ?? {});
+}
+
+function jsonArrayParam(value: unknown): string {
+  return JSON.stringify(Array.isArray(value) ? value : []);
+}
+
+function isoString(value: unknown): string | null {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+  }
+  return null;
+}
+
+function normalizeBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function normalizeMaxSourceBytes(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_MAX_SOURCE_BYTES;
+  return Math.max(1, Math.floor(value));
+}
+
+function normalizeBundleLimit(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.max(1000, Math.floor(value));
+}
+
+function normalizeCostRate(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_PAPERCLIP_COST_CENTS_PER_1K_CHARS;
+  return Math.max(0, value);
+}
+
+type PaperclipDistillationLimits = {
+  maxCharacters: number;
+  maxCharactersPerSource: number;
+  maxRoutineRunCharacters: number;
+  costCentsPerThousandSourceCharacters: number;
+};
+
+const DISTILLATION_REDACTED_VALUE = "***REDACTED***";
+const DISTILLATION_JSON_SECRET_FIELD_TEXT_RE =
+  /((?:"|')?(?:api[-_]?key|access[-_]?token|auth(?:_?token)?|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)(?:"|')?\s*:\s*(?:"|'))[^"'`\r\n]+((?:"|'))/gi;
+const DISTILLATION_ESCAPED_JSON_SECRET_FIELD_TEXT_RE =
+  /((?:\\")?(?:api[-_]?key|access[-_]?token|auth(?:_?token)?|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)(?:\\")?\s*:\s*(?:\\"))[^\\\r\n]+((?:\\"))/gi;
+const DISTILLATION_ENV_SECRET_ASSIGNMENT_RE =
+  /(\b[A-Za-z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD|PASSWD|AUTHORIZATION|JWT)[A-Za-z0-9_]*\s*=\s*)[^\s"'`]+/gi;
+const DISTILLATION_AUTHORIZATION_BEARER_RE = /(\bAuthorization\s*:\s*Bearer\s+)[^\s"'`]+/gi;
+const DISTILLATION_OPENAI_KEY_RE = /\bsk-[A-Za-z0-9_-]{12,}\b/g;
+const DISTILLATION_GITHUB_TOKEN_RE = /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g;
+const DISTILLATION_JWT_RE =
+  /\b[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}(?:\.[A-Za-z0-9_-]{8,})?\b/g;
+const DISTILLATION_CONNECTION_STRING_RE =
+  /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqps?):\/\/[^\s"'`]+/gi;
+const DISTILLATION_PRIVATE_KEY_BLOCK_RE =
+  /-----BEGIN(?:[A-Z ]+)?PRIVATE KEY-----[\s\S]*?-----END(?:[A-Z ]+)?PRIVATE KEY-----/gi;
+const DISTILLATION_PRIVATE_KEY_BLOCK_TEST_RE =
+  /-----BEGIN(?:[A-Z ]+)?PRIVATE KEY-----[\s\S]*?-----END(?:[A-Z ]+)?PRIVATE KEY-----/i;
+
+type DistillationSourceProtectionResult = {
+  body: string;
+  warning: string | null;
+  refPatch: Pick<PaperclipSourceRef, "redactionStatus" | "redactionReasons">;
+};
+
+function redactDistillationSensitiveText(input: string): string {
+  return input
+    .replace(DISTILLATION_PRIVATE_KEY_BLOCK_RE, DISTILLATION_REDACTED_VALUE)
+    .replace(DISTILLATION_JSON_SECRET_FIELD_TEXT_RE, `$1${DISTILLATION_REDACTED_VALUE}$2`)
+    .replace(DISTILLATION_ESCAPED_JSON_SECRET_FIELD_TEXT_RE, `$1${DISTILLATION_REDACTED_VALUE}$2`)
+    .replace(DISTILLATION_ENV_SECRET_ASSIGNMENT_RE, `$1${DISTILLATION_REDACTED_VALUE}`)
+    .replace(DISTILLATION_AUTHORIZATION_BEARER_RE, `$1${DISTILLATION_REDACTED_VALUE}`)
+    .replace(DISTILLATION_CONNECTION_STRING_RE, DISTILLATION_REDACTED_VALUE)
+    .replace(DISTILLATION_OPENAI_KEY_RE, DISTILLATION_REDACTED_VALUE)
+    .replace(DISTILLATION_GITHUB_TOKEN_RE, DISTILLATION_REDACTED_VALUE)
+    .replace(DISTILLATION_JWT_RE, DISTILLATION_REDACTED_VALUE);
+}
+
+function protectDistillationSourceBody(input: {
+  issue: Issue;
+  sourceKind: "comment" | "document";
+  sourceId: string;
+  body: string;
+}): DistillationSourceProtectionResult {
+  const redactedBody = redactDistillationSensitiveText(input.body);
+  const reasons = [
+    DISTILLATION_PRIVATE_KEY_BLOCK_TEST_RE.test(input.body) ? "private_key_block" : null,
+    redactedBody !== input.body ? "secret_like_token" : null,
+  ].filter((reason): reason is string => Boolean(reason));
+  if (reasons.length === 0) {
+    return {
+      body: input.body,
+      warning: null,
+      refPatch: {},
+    };
+  }
+
+  return {
+    body: [
+      `[Suppressed by LLM Wiki distillation security policy for this ${input.sourceKind}.]`,
+      "",
+      `- Source ID: ${input.sourceId}`,
+      `- Redaction reasons: ${reasons.join(", ")}`,
+      "- Review the original Paperclip source directly if a human needs the unredacted material.",
+    ].join("\n"),
+    warning: `Suppressed ${input.sourceKind} content for ${sourceTitleForIssue(input.issue)} / ${input.sourceId}: ${reasons.join(", ")}.`,
+    refPatch: {
+      redactionStatus: "suppressed_sensitive_content",
+      redactionReasons: reasons,
+    },
+  };
+}
+
+async function resolvePaperclipDistillationLimits(
+  ctx: PluginContext,
+  input: Pick<PaperclipSourceBundleInput, "maxCharacters" | "maxCharactersPerSource" | "routineRun">,
+): Promise<PaperclipDistillationLimits> {
+  assertRequestedCharacterLimit("maxCharacters", input.maxCharacters, DEFAULT_MAX_PAPERCLIP_CURSOR_WINDOW_CHARS);
+  assertRequestedCharacterLimit("maxCharactersPerSource", input.maxCharactersPerSource, DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS);
+  const config = await ctx.config.get() as Record<string, unknown>;
+  const maxCharactersPerSource = Math.min(
+    normalizeBundleLimit(input.maxCharactersPerSource, DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS),
+    normalizeBundleLimit(config.maxPaperclipIssueSourceCharacters, DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS),
+  );
+  const cursorWindowCap = normalizeBundleLimit(
+    config.maxPaperclipCursorWindowCharacters,
+    DEFAULT_MAX_PAPERCLIP_CURSOR_WINDOW_CHARS,
+  );
+  const routineRunCap = normalizeBundleLimit(
+    config.maxPaperclipRoutineRunCharacters,
+    DEFAULT_MAX_PAPERCLIP_ROUTINE_RUN_CHARS,
+  );
+  const requestedMaxCharacters = normalizeBundleLimit(input.maxCharacters, cursorWindowCap);
+  const hardCharacterCap = input.routineRun ? Math.min(cursorWindowCap, routineRunCap) : cursorWindowCap;
+  return {
+    maxCharacters: Math.min(requestedMaxCharacters, hardCharacterCap),
+    maxCharactersPerSource,
+    maxRoutineRunCharacters: routineRunCap,
+    costCentsPerThousandSourceCharacters: normalizeCostRate(config.paperclipCostCentsPerThousandSourceCharacters),
+  };
+}
+
+async function resolvePaperclipDistillationLimitsForSpace(
+  ctx: PluginContext,
+  input: Pick<PaperclipSourceBundleInput, "companyId" | "maxCharacters" | "maxCharactersPerSource" | "routineRun"> & { space: WikiSpace },
+): Promise<PaperclipDistillationLimits> {
+  const [base, profile] = await Promise.all([
+    resolvePaperclipDistillationLimits(ctx, input),
+    profileForSpace(ctx, input.companyId, input.space),
+  ]);
+  return {
+    ...base,
+    maxCharacters: Math.min(base.maxCharacters, profile.cursor.maxWindowCharacters),
+    maxCharactersPerSource: Math.min(base.maxCharactersPerSource, profile.cursor.maxCharactersPerSource),
+  };
+}
+
+function estimateSourceCostCents(characters: number, costCentsPerThousandSourceCharacters: number): number {
+  if (characters <= 0 || costCentsPerThousandSourceCharacters <= 0) return 0;
+  return Math.ceil((characters / 1000) * costCentsPerThousandSourceCharacters);
+}
+
+async function assertSourceWithinConfiguredLimit(ctx: PluginContext, contents: string) {
+  const config = await ctx.config.get();
+  const maxSourceBytes = normalizeMaxSourceBytes(config.maxSourceBytes);
+  const sourceBytes = byteLength(contents);
+  if (sourceBytes > maxSourceBytes) {
+    throw new Error(`Source content is ${sourceBytes} bytes, which exceeds the configured LLM Wiki source limit of ${maxSourceBytes} bytes.`);
+  }
+}
+
+function normalizeEventIngestionSettings(value: unknown): WikiEventIngestionSettings {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { ...DEFAULT_EVENT_INGESTION_SETTINGS, sources: { ...DEFAULT_EVENT_INGESTION_SETTINGS.sources } };
+  }
+  const record = value as Record<string, unknown>;
+  const sources = record.sources && typeof record.sources === "object" && !Array.isArray(record.sources)
+    ? record.sources as Record<string, unknown>
+    : {};
+  const maxCharacters = typeof record.maxCharacters === "number" && Number.isFinite(record.maxCharacters)
+    ? Math.max(1000, Math.min(MAX_EVENT_SOURCE_CHARS, Math.floor(record.maxCharacters)))
+    : DEFAULT_EVENT_INGESTION_SETTINGS.maxCharacters;
+  return {
+    enabled: normalizeBoolean(record.enabled, DEFAULT_EVENT_INGESTION_SETTINGS.enabled),
+    sources: {
+      issues: normalizeBoolean(sources.issues, DEFAULT_EVENT_INGESTION_SETTINGS.sources.issues),
+      comments: normalizeBoolean(sources.comments, DEFAULT_EVENT_INGESTION_SETTINGS.sources.comments),
+      documents: normalizeBoolean(sources.documents, DEFAULT_EVENT_INGESTION_SETTINGS.sources.documents),
+    },
+    wikiId: normalizeWikiId(record.wikiId),
+    maxCharacters,
+  };
+}
+
+function defaultPaperclipIngestionProfile(input: {
+  space: Pick<WikiSpace, "slug">;
+  legacySettings?: WikiEventIngestionSettings | null;
+}): PaperclipIngestionProfileV1 {
+  const legacy = input.space.slug === DEFAULT_SPACE_SLUG ? input.legacySettings : null;
+  return {
+    version: 1,
+    enabled: legacy?.enabled ?? false,
+    sourceScopes: legacy?.enabled ? [{ kind: "company_all", requiresBoardConfirmation: true }] : [],
+    sourceKinds: {
+      issues: legacy?.sources.issues ?? true,
+      comments: legacy?.sources.comments ?? true,
+      documents: legacy?.sources.documents ?? true,
+      attachments: "off",
+      workProducts: "off",
+    },
+    cursor: {
+      maxWindowCharacters: DEFAULT_MAX_PAPERCLIP_CURSOR_WINDOW_CHARS,
+      maxCharactersPerSource: DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS,
+      minSourceAgeMinutes: 15,
+      maxWindowsPerRun: 6,
+      staleAfterHours: 72,
+    },
+    backfill: {
+      defaultStartAt: null,
+      defaultEndAt: null,
+      requireManualQueue: true,
+    },
+  };
+}
+
+function stringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.map((item) => stringField(item)).filter((item): item is string => Boolean(item)))];
+}
+
+function normalizePaperclipIngestionSourceScope(value: unknown): PaperclipIngestionSourceScope | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const kind = stringField(record.kind);
+  if (kind === "active_projects") {
+    const statuses = Array.isArray(record.statuses)
+      ? record.statuses.filter((status): status is "in_progress" | "todo" | "done" =>
+          status === "in_progress" || status === "todo" || status === "done")
+      : undefined;
+    return {
+      kind,
+      limit: normalizeLimit(record.limit, 3, MAX_PAPERCLIP_PROFILE_SELECTED_PROJECTS),
+      ...(statuses && statuses.length > 0 ? { statuses: [...new Set(statuses)] } : {}),
+    };
+  }
+  if (kind === "selected_projects") {
+    return { kind, projectIds: stringArray(record.projectIds).slice(0, MAX_PAPERCLIP_PROFILE_SELECTED_PROJECTS) };
+  }
+  if (kind === "root_issues") {
+    return { kind, issueIds: stringArray(record.issueIds).slice(0, MAX_PAPERCLIP_PROFILE_ROOT_ISSUES) };
+  }
+  if (kind === "company_all") {
+    return { kind, requiresBoardConfirmation: true };
+  }
+  return null;
+}
+
+function normalizePaperclipIngestionProfile(
+  value: unknown,
+  input: { space: Pick<WikiSpace, "slug">; legacySettings?: WikiEventIngestionSettings | null },
+): PaperclipIngestionProfileV1 {
+  const fallback = defaultPaperclipIngestionProfile(input);
+  if (!value || typeof value !== "object" || Array.isArray(value)) return fallback;
+  const record = value as Record<string, unknown>;
+  const sourceKinds = record.sourceKinds && typeof record.sourceKinds === "object" && !Array.isArray(record.sourceKinds)
+    ? record.sourceKinds as Record<string, unknown>
+    : {};
+  const cursor = record.cursor && typeof record.cursor === "object" && !Array.isArray(record.cursor)
+    ? record.cursor as Record<string, unknown>
+    : {};
+  const backfill = record.backfill && typeof record.backfill === "object" && !Array.isArray(record.backfill)
+    ? record.backfill as Record<string, unknown>
+    : {};
+  return {
+    version: 1,
+    enabled: normalizeBoolean(record.enabled, fallback.enabled),
+    sourceScopes: Array.isArray(record.sourceScopes)
+      ? record.sourceScopes.map(normalizePaperclipIngestionSourceScope).filter((scope): scope is PaperclipIngestionSourceScope => Boolean(scope))
+      : fallback.sourceScopes,
+    sourceKinds: {
+      issues: normalizeBoolean(sourceKinds.issues, fallback.sourceKinds.issues),
+      comments: normalizeBoolean(sourceKinds.comments, fallback.sourceKinds.comments),
+      documents: normalizeBoolean(sourceKinds.documents, fallback.sourceKinds.documents),
+      attachments: sourceKinds.attachments === "metadata_only" ? "metadata_only" : "off",
+      workProducts: sourceKinds.workProducts === "metadata_only" ? "metadata_only" : "off",
+    },
+    cursor: {
+      maxWindowCharacters: normalizeLimit(cursor.maxWindowCharacters, fallback.cursor.maxWindowCharacters, DEFAULT_MAX_PAPERCLIP_CURSOR_WINDOW_CHARS),
+      maxCharactersPerSource: normalizeLimit(cursor.maxCharactersPerSource, fallback.cursor.maxCharactersPerSource, DEFAULT_MAX_PAPERCLIP_ISSUE_SOURCE_CHARS),
+      minSourceAgeMinutes: normalizeLimit(cursor.minSourceAgeMinutes, fallback.cursor.minSourceAgeMinutes, 24 * 60),
+      maxWindowsPerRun: normalizeLimit(cursor.maxWindowsPerRun, fallback.cursor.maxWindowsPerRun, 25),
+      staleAfterHours: normalizeLimit(cursor.staleAfterHours, fallback.cursor.staleAfterHours, 24 * 30),
+    },
+    backfill: {
+      defaultStartAt: isoString(backfill.defaultStartAt),
+      defaultEndAt: isoString(backfill.defaultEndAt),
+      requireManualQueue: normalizeBoolean(backfill.requireManualQueue, fallback.backfill.requireManualQueue),
+    },
+  };
+}
+
+async function profileForSpace(ctx: PluginContext, companyId: string, space: WikiSpace): Promise<PaperclipIngestionProfileV1> {
+  const legacySettings = space.slug === DEFAULT_SPACE_SLUG ? await getEventIngestionSettings(ctx, companyId) : null;
+  return normalizePaperclipIngestionProfile(space.settings.paperclipIngestion, { space, legacySettings });
+}
+
+function eventIngestionStateKey(companyId: string) {
+  return {
+    scopeKind: "company" as const,
+    scopeId: companyId,
+    namespace: EVENT_INGESTION_STATE_NAMESPACE,
+    stateKey: EVENT_INGESTION_STATE_KEY,
+  };
+}
+
+function eventIngestionDedupKey(companyId: string, wikiId: string, spaceId: string, sourceKind: WikiEventIngestionSource, sourceId: string) {
+  return {
+    scopeKind: "company" as const,
+    scopeId: companyId,
+    namespace: EVENT_INGESTION_DEDUP_NAMESPACE,
+    stateKey: `${wikiId}:${spaceId}:${sourceKind}:${sourceId}`,
+  };
+}
+
+export async function getEventIngestionSettings(ctx: PluginContext, companyId: string): Promise<WikiEventIngestionSettings> {
+  return normalizeEventIngestionSettings(await ctx.state.get(eventIngestionStateKey(companyId)));
+}
+
+function evaluatePaperclipProfilePolicy(input: {
+  space: WikiSpace;
+  profile?: PaperclipIngestionProfileV1 | null;
+  purpose: PaperclipIngestionPolicyPurpose;
+  requireEnabledProfile?: boolean;
+}): PaperclipIngestionPolicyDecision {
+  const { space, profile, purpose } = input;
+  if (space.status !== "active") {
+    return {
+      allowed: false,
+      space,
+      reason: "archived_space",
+      message: `Paperclip ingestion policy denied ${purpose}: space "${space.slug}" is ${space.status}.`,
+    };
+  }
+  if (space.accessScope !== "shared") {
+    return {
+      allowed: false,
+      space,
+      reason: "restricted_space",
+      message: `Paperclip ingestion policy denied ${purpose}: ${space.accessScope} spaces cannot ingest Paperclip sources until host permissions are enforced.`,
+    };
+  }
+  if (input.requireEnabledProfile && space.slug !== DEFAULT_SPACE_SLUG && !profile?.enabled) {
+    return {
+      allowed: false,
+      space,
+      reason: "profile_disabled",
+      message: `Paperclip ingestion policy denied ${purpose}: Paperclip ingestion is not enabled for space "${space.slug}".`,
+    };
+  }
+  if (input.requireEnabledProfile && space.slug !== DEFAULT_SPACE_SLUG && profile?.enabled && profile.sourceScopes.length === 0) {
+    return {
+      allowed: false,
+      space,
+      reason: "profile_empty",
+      message: `Paperclip ingestion policy denied ${purpose}: space "${space.slug}" has no source scopes configured.`,
+    };
+  }
+  return { allowed: true, space };
+}
+
+export async function getPaperclipIngestionProfile(
+  ctx: PluginContext,
+  input: { companyId: string; wikiId?: string | null; spaceSlug?: string | null },
+): Promise<PaperclipIngestionProfileRead> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const profile = await profileForSpace(ctx, input.companyId, space);
+  const policy = evaluatePaperclipProfilePolicy({ space, profile, purpose: "profile_read" });
+  const historicalPageCount = await countPaperclipHistoricalPages(ctx, {
+    companyId: input.companyId,
+    wikiId,
+    spaceId: space.id,
+  });
+  const overlapCount = await countPaperclipProfileOverlaps(ctx, {
+    companyId: input.companyId,
+    wikiId,
+    space,
+    profile,
+  });
+  const effectiveState: PaperclipIngestionProfileEffectiveState = !policy.allowed
+    ? "policy_blocked"
+    : profile.enabled && profile.sourceScopes.length === 0
+      ? "enabled_no_scopes"
+      : profile.enabled
+        ? "enabled"
+        : "disabled";
+  return {
+    wikiId,
+    space: {
+      id: space.id,
+      slug: space.slug,
+      displayName: space.displayName,
+      accessScope: space.accessScope,
+      status: space.status,
+    },
+    profile,
+    effectiveState,
+    policyBlocks: policy.allowed ? [] : [policy.message],
+    historicalPageCount,
+    overlapCount,
+  };
+}
+
+async function countPaperclipHistoricalPages(ctx: PluginContext, input: { companyId: string; wikiId: string; spaceId: string }): Promise<number> {
+  const rows = await ctx.db.query<{ count: string | number }>(
+    `SELECT count(*)::text AS count
+       FROM ${pageBindingTable(ctx)}
+      WHERE company_id = $1 AND wiki_id = $2 AND space_id = $3`,
+    [input.companyId, input.wikiId, input.spaceId],
+  );
+  return Number(rows[0]?.count ?? 0) || 0;
+}
+
+function scopeIdentity(scope: PaperclipIngestionSourceScope): string[] {
+  if (scope.kind === "active_projects") return [`active_projects:${scope.limit}`];
+  if (scope.kind === "selected_projects") return scope.projectIds.map((id) => `project:${id}`);
+  if (scope.kind === "root_issues") return scope.issueIds.map((id) => `root_issue:${id}`);
+  return ["company_all"];
+}
+
+async function countPaperclipProfileOverlaps(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId: string;
+  space: WikiSpace;
+  profile: PaperclipIngestionProfileV1;
+}): Promise<number> {
+  if (!input.profile.enabled || input.profile.sourceScopes.length === 0) return 0;
+  const own = new Set(input.profile.sourceScopes.flatMap(scopeIdentity));
+  if (own.size === 0) return 0;
+  const { spaces } = await listSpaces(ctx, { companyId: input.companyId, wikiId: input.wikiId });
+  let overlaps = 0;
+  for (const space of spaces) {
+    if (space.id === input.space.id) continue;
+    const profile = await profileForSpace(ctx, input.companyId, space);
+    if (!profile.enabled) continue;
+    for (const key of profile.sourceScopes.flatMap(scopeIdentity)) {
+      if (own.has(key)) overlaps += 1;
+    }
+  }
+  return overlaps;
+}
+
+async function validatePaperclipIngestionProfile(ctx: PluginContext, input: {
+  companyId: string;
+  space: WikiSpace;
+  profile: PaperclipIngestionProfileV1;
+}) {
+  const policy = evaluatePaperclipProfilePolicy({
+    space: input.space,
+    profile: input.profile,
+    purpose: "profile_update",
+    requireEnabledProfile: input.profile.enabled && input.space.slug !== DEFAULT_SPACE_SLUG,
+  });
+  if (!policy.allowed) throw new Error(policy.message);
+  if (input.profile.enabled && input.profile.sourceScopes.length === 0) {
+    throw new Error("Paperclip ingestion profile must include at least one source scope before it can be enabled.");
+  }
+  if (input.profile.sourceScopes.length > MAX_PAPERCLIP_INGESTION_PROFILE_SOURCE_COUNT) {
+    throw new Error(`Paperclip ingestion profile sources exceed the hard cap of ${MAX_PAPERCLIP_INGESTION_PROFILE_SOURCE_COUNT}.`);
+  }
+  for (const scope of input.profile.sourceScopes) {
+    if (scope.kind === "company_all" && input.space.slug !== DEFAULT_SPACE_SLUG) {
+      throw new Error("Everything in the company is only available on the default wiki space.");
+    }
+    if (scope.kind === "selected_projects") {
+      if (scope.projectIds.length > MAX_PAPERCLIP_PROFILE_SELECTED_PROJECTS) {
+        throw new Error(`selected_projects exceeds the hard cap of ${MAX_PAPERCLIP_PROFILE_SELECTED_PROJECTS}.`);
+      }
+      for (const projectId of scope.projectIds) {
+        const project = await ctx.projects.get(projectId, input.companyId);
+        if (!project) throw new Error(`Project belongs to another company or does not exist: ${projectId}`);
+      }
+    }
+    if (scope.kind === "root_issues") {
+      if (scope.issueIds.length > MAX_PAPERCLIP_PROFILE_ROOT_ISSUES) {
+        throw new Error(`root_issues exceeds the hard cap of ${MAX_PAPERCLIP_PROFILE_ROOT_ISSUES}.`);
+      }
+      for (const issueId of scope.issueIds) {
+        const issue = await ctx.issues.get(issueId, input.companyId);
+        if (!issue) throw new Error(`Issue belongs to another company or does not exist: ${issueId}`);
+      }
+    }
+  }
+}
+
+export async function updatePaperclipIngestionProfile(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  profile: unknown;
+}): Promise<PaperclipIngestionProfileRead> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const current = await profileForSpace(ctx, input.companyId, space);
+  const profile = normalizePaperclipIngestionProfile(input.profile, { space, legacySettings: space.slug === DEFAULT_SPACE_SLUG ? await getEventIngestionSettings(ctx, input.companyId) : null });
+  await validatePaperclipIngestionProfile(ctx, { companyId: input.companyId, space, profile });
+  await updateSpace(ctx, {
+    companyId: input.companyId,
+    wikiId,
+    spaceSlug: space.slug,
+    settings: { paperclipIngestion: profile },
+  });
+  if (space.slug === DEFAULT_SPACE_SLUG) {
+    await ctx.state.set(eventIngestionStateKey(input.companyId), {
+      enabled: profile.enabled,
+      wikiId,
+      maxCharacters: profile.cursor.maxCharactersPerSource,
+      sources: {
+        issues: profile.sourceKinds.issues,
+        comments: profile.sourceKinds.comments,
+        documents: profile.sourceKinds.documents,
+      },
+    });
+  }
+  await ctx.activity.log({
+    companyId: input.companyId,
+    message: `Updated Paperclip ingestion profile for ${space.displayName}`,
+    entityType: "llm_wiki_space",
+    entityId: space.id,
+    metadata: {
+      type: "plugin.llm_wiki.paperclip_ingestion_profile_updated",
+      wikiId,
+      spaceSlug: space.slug,
+      beforeEnabled: current.enabled,
+      afterEnabled: profile.enabled,
+      sourceScopeKinds: profile.sourceScopes.map((scope) => scope.kind),
+      sourceKinds: profile.sourceKinds,
+      cursor: profile.cursor,
+    },
+  });
+  return getPaperclipIngestionProfile(ctx, { companyId: input.companyId, wikiId, spaceSlug: space.slug });
+}
+
+export async function listPaperclipIngestionCandidates(ctx: PluginContext, input: PaperclipIngestionCandidatesInput): Promise<{
+  projects: Array<{ id: string; name: string; status: string; updatedAt: string | null }>;
+  rootIssues: Array<{ id: string; identifier: string | null; title: string; status: string; projectId: string | null }>;
+}> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  await requirePaperclipIngestionPolicy(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug }, "candidate_search");
+  const query = stringField(input.query)?.toLowerCase() ?? "";
+  const projects = (await ctx.projects.list({ companyId: input.companyId, limit: 200 }))
+    .filter((project) => !project.archivedAt)
+    .filter((project) => !query || project.name.toLowerCase().includes(query))
+    .slice(0, 50)
+    .map((project) => ({
+      id: project.id,
+      name: project.name,
+      status: project.status,
+      updatedAt: isoString(project.updatedAt),
+    }));
+  const issues = (await ctx.issues.list({
+    companyId: input.companyId,
+    includePluginOperations: false,
+    limit: 200,
+  }))
+    .filter((issue) => !issue.parentId)
+    .filter((issue) => !query || issue.title.toLowerCase().includes(query) || issue.identifier?.toLowerCase().includes(query))
+    .slice(0, 50)
+    .map((issue) => ({
+      id: issue.id,
+      identifier: issue.identifier ?? null,
+      title: issue.title,
+      status: issue.status,
+      projectId: issue.projectId ?? null,
+    }));
+  return { projects, rootIssues: issues };
+}
+
+export async function updateEventIngestionSettings(
+  ctx: PluginContext,
+  input: { companyId: string; settings: WikiEventIngestionSettingsUpdate },
+): Promise<WikiEventIngestionSettings> {
+  await requirePaperclipIngestionPolicy(ctx, {
+    companyId: input.companyId,
+    wikiId: normalizeWikiId(input.settings.wikiId),
+    spaceSlug: DEFAULT_SPACE_SLUG,
+  }, "profile_update");
+  const sourceKeys = Object.keys(input.settings.sources ?? {});
+  if (sourceKeys.length > MAX_PAPERCLIP_INGESTION_PROFILE_SOURCE_COUNT) {
+    throw new Error(`Paperclip ingestion profile sources exceed the hard cap of ${MAX_PAPERCLIP_INGESTION_PROFILE_SOURCE_COUNT}.`);
+  }
+  assertRequestedCharacterLimit("maxCharacters", input.settings.maxCharacters, MAX_EVENT_SOURCE_CHARS);
+  const current = await getEventIngestionSettings(ctx, input.companyId);
+  const next = normalizeEventIngestionSettings({
+    ...current,
+    ...input.settings,
+    sources: {
+      ...current.sources,
+      ...(input.settings.sources ?? {}),
+    },
+  });
+  await ctx.state.set(eventIngestionStateKey(input.companyId), next);
+  const defaultSpace = await ensureDefaultSpace(ctx, { companyId: input.companyId, wikiId: next.wikiId });
+  const profile = normalizePaperclipIngestionProfile(
+    {
+      ...defaultPaperclipIngestionProfile({ space: defaultSpace, legacySettings: next }),
+      enabled: next.enabled,
+      sourceKinds: {
+        issues: next.sources.issues,
+        comments: next.sources.comments,
+        documents: next.sources.documents,
+        attachments: "off",
+        workProducts: "off",
+      },
+      cursor: {
+        ...defaultPaperclipIngestionProfile({ space: defaultSpace, legacySettings: next }).cursor,
+        maxCharactersPerSource: next.maxCharacters,
+      },
+    },
+    { space: defaultSpace, legacySettings: next },
+  );
+  await updateSpace(ctx, {
+    companyId: input.companyId,
+    wikiId: next.wikiId,
+    spaceSlug: DEFAULT_SPACE_SLUG,
+    settings: { paperclipIngestion: profile },
+  });
+  return next;
+}
+
+function assertWikiPath(path: string, options: { allowMetadata?: boolean } = {}): string {
+  const trimmed = path.trim().replace(/^\/+/, "");
+  if (
+    !trimmed ||
+    trimmed.includes("\\") ||
+    trimmed.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
+  ) {
+    throw new Error(`Invalid wiki path: ${path}`);
+  }
+  if (
+    trimmed !== ".gitignore" &&
+    trimmed !== "WIKI.md" &&
+    trimmed !== "AGENTS.md" &&
+    trimmed !== "IDEA.md" &&
+    trimmed !== "index.md" &&
+    trimmed !== "log.md" &&
+    !trimmed.startsWith("raw/") &&
+    !trimmed.startsWith("wiki/") &&
+    !(options.allowMetadata && trimmed.startsWith(".paperclip/"))
+  ) {
+    throw new Error(`Wiki path must stay inside AGENTS.md, IDEA.md, raw/, or wiki/: ${path}`);
+  }
+  return trimmed;
+}
+
+function assertPagePath(path: string): string {
+  const normalized = assertWikiPath(path);
+  if (normalized !== "index.md" && normalized !== "log.md" && normalized !== "WIKI.md" && normalized !== "AGENTS.md" && normalized !== "IDEA.md" && !normalized.startsWith("wiki/")) {
+    throw new Error(`Wiki page writes must target AGENTS.md, IDEA.md, or wiki/: ${path}`);
+  }
+  if (!normalized.endsWith(".md")) {
+    throw new Error(`Wiki page path must be a markdown file: ${path}`);
+  }
+  return normalized;
+}
+
+function assertPageWriteAllowed(path: string, writer: WritePageInput["writer"] = "agent_tool"): void {
+  if (writer !== "board_ui" && PROTECTED_WIKI_CONTROL_FILES.has(path)) {
+    throw new Error(`Refusing to overwrite protected wiki control file ${path}; board-managed edits must use the wiki UI.`);
+  }
+}
+
+function assertRawPath(path: string): string {
+  const normalized = assertWikiPath(path);
+  if (!normalized.startsWith("raw/")) {
+    throw new Error(`Source path must stay inside raw/: ${path}`);
+  }
+  return normalized;
+}
+
+function tableName(namespace: string, table: string): string {
+  return `${namespace}.${table}`;
+}
+
+function spaceTable(ctx: PluginContext): string {
+  return tableName(ctx.db.namespace, "wiki_spaces");
+}
+
+function bindingTable(ctx: PluginContext): string {
+  return tableName(ctx.db.namespace, "wiki_resource_bindings");
+}
+
+function distillationCursorTable(ctx: PluginContext): string {
+  return tableName(ctx.db.namespace, "paperclip_distillation_cursors");
+}
+
+function distillationRunTable(ctx: PluginContext): string {
+  return tableName(ctx.db.namespace, "paperclip_distillation_runs");
+}
+
+function sourceSnapshotTable(ctx: PluginContext): string {
+  return tableName(ctx.db.namespace, "paperclip_source_snapshots");
+}
+
+function distillationWorkItemTable(ctx: PluginContext): string {
+  return tableName(ctx.db.namespace, "paperclip_distillation_work_items");
+}
+
+function pageBindingTable(ctx: PluginContext): string {
+  return tableName(ctx.db.namespace, "paperclip_page_bindings");
+}
+
+function parseBindingMetadata(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+function parseJsonObject(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+type WikiSpaceRow = {
+  id: string;
+  company_id: string;
+  wiki_id: string;
+  slug: string;
+  display_name: string;
+  space_type: string;
+  folder_mode: string;
+  root_folder_key: string;
+  path_prefix: string | null;
+  configured_root_path: string | null;
+  access_scope: string;
+  owner_user_id: string | null;
+  owner_agent_id: string | null;
+  team_key: string | null;
+  settings: unknown;
+  status: string;
+  created_at: string | null;
+  updated_at: string | null;
+};
+
+function wikiSpaceFromRow(row: WikiSpaceRow): WikiSpace {
+  return {
+    id: row.id,
+    companyId: row.company_id,
+    wikiId: row.wiki_id,
+    slug: row.slug,
+    displayName: row.display_name,
+    spaceType: row.space_type,
+    folderMode: row.folder_mode,
+    rootFolderKey: row.root_folder_key,
+    pathPrefix: row.path_prefix,
+    configuredRootPath: row.configured_root_path,
+    accessScope: row.access_scope,
+    ownerUserId: row.owner_user_id,
+    ownerAgentId: row.owner_agent_id,
+    teamKey: row.team_key,
+    settings: parseJsonObject(row.settings),
+    status: row.status,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function fallbackDefaultSpace(input: { companyId: string; wikiId: string }): WikiSpace {
+  return {
+    id: stableSpaceId({ companyId: input.companyId, wikiId: input.wikiId, slug: DEFAULT_SPACE_SLUG }),
+    companyId: input.companyId,
+    wikiId: input.wikiId,
+    slug: DEFAULT_SPACE_SLUG,
+    displayName: DEFAULT_SPACE_SLUG,
+    spaceType: "local_folder",
+    folderMode: "managed_subfolder",
+    rootFolderKey: WIKI_ROOT_FOLDER_KEY,
+    pathPrefix: null,
+    configuredRootPath: null,
+    accessScope: "shared",
+    ownerUserId: null,
+    ownerAgentId: null,
+    teamKey: null,
+    settings: {},
+    status: "active",
+    createdAt: null,
+    updatedAt: null,
+  };
+}
+
+export async function ensureDefaultSpace(ctx: PluginContext, input: { companyId: string; wikiId?: string | null }): Promise<WikiSpace> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const id = stableSpaceId({ companyId: input.companyId, wikiId, slug: DEFAULT_SPACE_SLUG });
+  await ctx.db.execute(
+    `INSERT INTO ${spaceTable(ctx)} AS wiki_spaces
+       (id, company_id, wiki_id, slug, display_name, space_type, folder_mode, root_folder_key, path_prefix, access_scope, status, settings)
+     VALUES ($1, $2, $3, 'default', 'default', 'local_folder', 'managed_subfolder', $4, NULL, 'shared', 'active', '{}'::jsonb)
+     ON CONFLICT (company_id, wiki_id, slug)
+     DO UPDATE SET updated_at = wiki_spaces.updated_at`,
+    [id, input.companyId, wikiId, WIKI_ROOT_FOLDER_KEY],
+  );
+  const rows = await ctx.db.query<WikiSpaceRow>(
+    `SELECT id, company_id, wiki_id, slug, display_name, space_type, folder_mode, root_folder_key,
+            path_prefix, configured_root_path, access_scope, owner_user_id, owner_agent_id, team_key,
+            settings, status, created_at::text AS created_at, updated_at::text AS updated_at
+       FROM ${spaceTable(ctx)}
+      WHERE company_id = $1 AND wiki_id = $2 AND slug = 'default'
+      LIMIT 1`,
+    [input.companyId, wikiId],
+  );
+  return rows[0] ? wikiSpaceFromRow(rows[0]) : fallbackDefaultSpace({ companyId: input.companyId, wikiId });
+}
+
+export async function resolveSpace(ctx: PluginContext, input: SpaceInput): Promise<WikiSpace> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const slug = normalizeSpaceSlug(input.spaceSlug);
+  if (slug === DEFAULT_SPACE_SLUG) {
+    return ensureDefaultSpace(ctx, { companyId: input.companyId, wikiId });
+  }
+  const rows = await ctx.db.query<WikiSpaceRow>(
+    `SELECT id, company_id, wiki_id, slug, display_name, space_type, folder_mode, root_folder_key,
+            path_prefix, configured_root_path, access_scope, owner_user_id, owner_agent_id, team_key,
+            settings, status, created_at::text AS created_at, updated_at::text AS updated_at
+       FROM ${spaceTable(ctx)}
+      WHERE company_id = $1 AND wiki_id = $2 AND slug = $3 AND status <> 'archived'
+      LIMIT 1`,
+    [input.companyId, wikiId, slug],
+  );
+  if (!rows[0]) throw new Error(`LLM Wiki space not found: ${slug}`);
+  return wikiSpaceFromRow(rows[0]);
+}
+
+async function resolveSpaceAnyStatus(ctx: PluginContext, input: SpaceInput): Promise<WikiSpace> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const slug = normalizeSpaceSlug(input.spaceSlug);
+  if (slug === DEFAULT_SPACE_SLUG) {
+    return ensureDefaultSpace(ctx, { companyId: input.companyId, wikiId });
+  }
+  const rows = await ctx.db.query<WikiSpaceRow>(
+    `SELECT id, company_id, wiki_id, slug, display_name, space_type, folder_mode, root_folder_key,
+            path_prefix, configured_root_path, access_scope, owner_user_id, owner_agent_id, team_key,
+            settings, status, created_at::text AS created_at, updated_at::text AS updated_at
+       FROM ${spaceTable(ctx)}
+      WHERE company_id = $1 AND wiki_id = $2 AND slug = $3
+      LIMIT 1`,
+    [input.companyId, wikiId, slug],
+  );
+  if (!rows[0]) throw new Error(`LLM Wiki space not found: ${slug}`);
+  return wikiSpaceFromRow(rows[0]);
+}
+
+export async function listSpaces(ctx: PluginContext, input: { companyId: string; wikiId?: string | null }): Promise<{ spaces: WikiSpace[] }> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  await ensureDefaultSpace(ctx, { companyId: input.companyId, wikiId });
+  const rows = await ctx.db.query<WikiSpaceRow>(
+    `SELECT id, company_id, wiki_id, slug, display_name, space_type, folder_mode, root_folder_key,
+            path_prefix, configured_root_path, access_scope, owner_user_id, owner_agent_id, team_key,
+            settings, status, created_at::text AS created_at, updated_at::text AS updated_at
+       FROM ${spaceTable(ctx)}
+      WHERE company_id = $1 AND wiki_id = $2 AND status <> 'archived'
+      ORDER BY CASE WHEN slug = 'default' THEN 0 ELSE 1 END, display_name, slug`,
+    [input.companyId, wikiId],
+  );
+  const spaces = rows.length > 0 ? rows.map(wikiSpaceFromRow) : [fallbackDefaultSpace({ companyId: input.companyId, wikiId })];
+  return { spaces };
+}
+
+export async function createSpace(ctx: PluginContext, input: CreateSpaceInput): Promise<{ status: "created"; space: WikiSpace }> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const displayName = stringField(input.displayName) ?? stringField(input.slug) ?? "New space";
+  const slug = normalizeSpaceSlug(input.slug ?? displayName);
+  if (slug === DEFAULT_SPACE_SLUG) {
+    return { status: "created", space: await ensureDefaultSpace(ctx, { companyId: input.companyId, wikiId }) };
+  }
+  const folderMode = input.folderMode ?? "managed_subfolder";
+  if (folderMode !== "managed_subfolder") {
+    throw new Error("Only managed_subfolder spaces are supported until dynamic local folder bindings are available.");
+  }
+  const accessScope = input.accessScope ?? "shared";
+  const id = randomUUID();
+  const pathPrefix = `spaces/${slug}`;
+  await ctx.db.execute(
+    `INSERT INTO ${spaceTable(ctx)}
+       (id, company_id, wiki_id, slug, display_name, space_type, folder_mode, root_folder_key, path_prefix, access_scope, settings, status)
+     VALUES ($1, $2, $3, $4, $5, 'local_folder', $6, $7, $8, $9, $10::jsonb, 'active')`,
+    [
+      id,
+      input.companyId,
+      wikiId,
+      slug,
+      displayName,
+      folderMode,
+      WIKI_ROOT_FOLDER_KEY,
+      pathPrefix,
+      accessScope,
+      jsonParam(input.settings ?? {}),
+    ],
+  );
+  const space: WikiSpace = {
+    id,
+    companyId: input.companyId,
+    wikiId,
+    slug,
+    displayName,
+    spaceType: "local_folder",
+    folderMode,
+    rootFolderKey: WIKI_ROOT_FOLDER_KEY,
+    pathPrefix,
+    configuredRootPath: null,
+    accessScope,
+    ownerUserId: null,
+    ownerAgentId: null,
+    teamKey: null,
+    settings: input.settings ?? {},
+    status: "active",
+    createdAt: null,
+    updatedAt: null,
+  };
+  await bootstrapSpaceFiles(ctx, input.companyId, space);
+  await upsertWikiInstance(ctx, { companyId: input.companyId, wikiId });
+  return { status: "created", space };
+}
+
+export async function updateSpace(ctx: PluginContext, input: UpdateSpaceInput): Promise<{ status: "ok"; space: WikiSpace }> {
+  const nextStatus = input.status ?? null;
+  if (nextStatus !== null && nextStatus !== "active" && nextStatus !== "archived") {
+    throw new Error("LLM Wiki space status must be active or archived.");
+  }
+  const space = nextStatus === "active" ? await resolveSpaceAnyStatus(ctx, input) : await resolveSpace(ctx, input);
+  const nextDisplayName = stringField(input.displayName);
+  if (space.slug === DEFAULT_SPACE_SLUG && nextStatus === "archived") {
+    throw new Error("The default LLM Wiki space cannot be archived.");
+  }
+  await ctx.db.execute(
+    `UPDATE ${spaceTable(ctx)}
+        SET display_name = COALESCE($4, display_name),
+            settings = CASE WHEN $5::jsonb IS NULL THEN settings ELSE settings || $5::jsonb END,
+            status = COALESCE($6, status),
+            updated_at = now()
+      WHERE company_id = $1 AND wiki_id = $2 AND slug = $3`,
+    [
+      input.companyId,
+      space.wikiId,
+      space.slug,
+      nextDisplayName,
+      input.settings ? jsonParam(input.settings) : null,
+      nextStatus ?? null,
+    ],
+  );
+  if (nextStatus === "archived") {
+    return {
+      status: "ok",
+      space: {
+        ...space,
+        displayName: nextDisplayName ?? space.displayName,
+        settings: input.settings ? { ...space.settings, ...input.settings } : space.settings,
+        status: "archived",
+      },
+    };
+  }
+  return { status: "ok", space: await resolveSpace(ctx, { companyId: input.companyId, wikiId: space.wikiId, spaceSlug: space.slug }) };
+}
+
+export async function archiveSpace(ctx: PluginContext, input: SpaceInput): Promise<{ status: "archived"; space: WikiSpace }> {
+  const space = await resolveSpace(ctx, input);
+  if (space.slug === DEFAULT_SPACE_SLUG) throw new Error("The default LLM Wiki space cannot be archived.");
+  await ctx.db.execute(
+    `UPDATE ${spaceTable(ctx)}
+        SET status = 'archived', updated_at = now()
+      WHERE company_id = $1 AND wiki_id = $2 AND slug = $3`,
+    [input.companyId, space.wikiId, space.slug],
+  );
+  return { status: "archived", space: { ...space, status: "archived" } };
+}
+
+export function spaceRelativePath(space: Pick<WikiSpace, "pathPrefix">, path: string): string {
+  const normalized = path.replace(/^\/+/, "");
+  return space.pathPrefix ? `${space.pathPrefix}/${normalized}` : normalized;
+}
+
+function logicalPathFromSpacePath(space: Pick<WikiSpace, "pathPrefix">, path: string): string {
+  if (!space.pathPrefix) return path;
+  const prefix = `${space.pathPrefix}/`;
+  return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+
+export async function spaceFolderStatus(ctx: PluginContext, input: SpaceInput): Promise<WikiSpaceWithFolderStatus> {
+  const space = await resolveSpace(ctx, input);
+  const folder = await ctx.localFolders.status(input.companyId, WIKI_ROOT_FOLDER_KEY);
+  return {
+    ...space,
+    relativeRoot: space.pathPrefix ?? ".",
+    folder,
+  };
+}
+
+async function getResourceBinding(
+  ctx: PluginContext,
+  input: { companyId: string; wikiId: string; resourceKind: WikiResourceKind; resourceKey: string },
+): Promise<WikiResourceBinding | null> {
+  const rows = await ctx.db.query<{ resolved_id: string | null; metadata: unknown }>(
+    `SELECT resolved_id, metadata
+       FROM ${bindingTable(ctx)}
+      WHERE company_id = $1
+        AND wiki_id = $2
+        AND resource_kind = $3
+        AND resource_key = $4
+      LIMIT 1`,
+    [input.companyId, input.wikiId, input.resourceKind, input.resourceKey],
+  );
+  const row = rows[0];
+  return row ? { resolvedId: row.resolved_id, metadata: parseBindingMetadata(row.metadata) } : null;
+}
+
+async function upsertResourceBinding(
+  ctx: PluginContext,
+  input: { companyId: string; wikiId: string; resourceKind: WikiResourceKind; resourceKey: string; resolvedId: string; metadata?: Record<string, unknown> },
+) {
+  await ctx.db.execute(
+    `INSERT INTO ${bindingTable(ctx)} AS wiki_resource_bindings
+       (id, company_id, wiki_id, resource_kind, resource_key, resolved_id, metadata)
+     VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)
+     ON CONFLICT (company_id, wiki_id, resource_kind, resource_key)
+     DO UPDATE SET resolved_id = EXCLUDED.resolved_id,
+                   metadata = EXCLUDED.metadata,
+                   updated_at = now()`,
+    [
+      randomUUID(),
+      input.companyId,
+      input.wikiId,
+      input.resourceKind,
+      input.resourceKey,
+      input.resolvedId,
+      jsonParam(input.metadata ?? {}),
+    ],
+  );
+}
+
+function agentDetails(agent: Agent | null): WikiAgentResource["details"] {
+  return agent
+    ? { name: agent.name, status: agent.status, adapterType: agent.adapterType ?? null, icon: agent.icon ?? null, urlKey: agent.urlKey ?? null }
+    : null;
+}
+
+function projectDetails(project: Project | null): WikiProjectResource["details"] {
+  return project ? { name: project.name, status: project.status, color: project.color ?? null } : null;
+}
+
+function skillDetails(skill: PluginManagedSkillResolution["skill"]): WikiSkillResource["details"] {
+  return skill
+    ? { name: skill.name, key: skill.key, description: skill.description ?? null }
+    : null;
+}
+
+function agentResource(input: {
+  status: WikiAgentResource["status"];
+  source: WikiAgentResource["source"];
+  agent: Agent | null;
+  defaultDrift?: WikiAgentResource["defaultDrift"];
+}): WikiAgentResource {
+  return {
+    status: input.status,
+    source: input.source,
+    agentId: input.agent?.id ?? null,
+    resourceKey: `${PLUGIN_ID}:agent:${WIKI_MAINTAINER_AGENT_KEY}`,
+    agent: input.agent,
+    details: agentDetails(input.agent),
+    defaultDrift: input.defaultDrift ?? null,
+  };
+}
+
+function projectResource(input: {
+  status: WikiProjectResource["status"];
+  source: WikiProjectResource["source"];
+  project: Project | null;
+}): WikiProjectResource {
+  return {
+    status: input.status,
+    source: input.source,
+    projectId: input.project?.id ?? null,
+    resourceKey: `${PLUGIN_ID}:project:${WIKI_PROJECT_KEY}`,
+    project: input.project,
+    details: projectDetails(input.project),
+  };
+}
+
+function skillResource(resolved: PluginManagedSkillResolution): WikiSkillResource {
+  return {
+    status: resolved.status,
+    skillId: resolved.skillId,
+    resourceKey: resolved.resourceKey,
+    skill: resolved.skill,
+    details: skillDetails(resolved.skill),
+    defaultDrift: resolved.defaultDrift ?? null,
+  };
+}
+
+async function resolveSelectedAgent(ctx: PluginContext, companyId: string, binding: WikiResourceBinding | null) {
+  if (!binding?.resolvedId) return null;
+  const agent = await ctx.agents.get(binding.resolvedId, companyId);
+  return agent && agent.status !== "terminated" ? agent : null;
+}
+
+async function resolveSelectedProject(ctx: PluginContext, companyId: string, binding: WikiResourceBinding | null) {
+  if (!binding?.resolvedId) return null;
+  return ctx.projects.get(binding.resolvedId, companyId);
+}
+
+function inferTitle(path: string, contents: string): string {
+  const heading = contents.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  if (heading) return heading;
+  const filename = path.split("/").pop()?.replace(/\.md$/i, "") ?? path;
+  return filename.replace(/[-_]+/g, " ");
+}
+
+function inferPageType(path: string): string | null {
+  if (/^wiki\/projects\/[^/]+\/standup\.md$/.test(path)) return "project-standup";
+  const match = path.match(/^wiki\/([^/]+)\//);
+  return match?.[1] ?? (path === "index.md" || path === "wiki/index.md" ? "index" : path === "log.md" || path === "wiki/log.md" ? "log" : null);
+}
+
+function extractWikiLinks(contents: string): string[] {
+  const links = new Set<string>();
+  const markdownLinkPattern = /\[[^\]]+\]\(([^)]+)\)/g;
+  for (const match of contents.matchAll(markdownLinkPattern)) {
+    const target = match[1]?.split("#")[0]?.trim();
+    if (target && (target.startsWith("wiki/") || target === "index.md" || target === "log.md" || target === "AGENTS.md" || target === "IDEA.md")) {
+      links.add(target);
+    }
+  }
+  const wikiTokenPattern = /\bwiki\/[A-Za-z0-9._/-]+\.md\b/g;
+  for (const match of contents.matchAll(wikiTokenPattern)) {
+    links.add(match[0]);
+  }
+  return [...links].sort();
+}
+
+async function readCurrentWithHash(
+  ctx: PluginContext,
+  companyId: string,
+  path: string,
+  space: Pick<WikiSpace, "pathPrefix">,
+): Promise<{ contents: string | null; hash: string | null }> {
+  try {
+    const contents = await ctx.localFolders.readText(companyId, WIKI_ROOT_FOLDER_KEY, spaceRelativePath(space, path));
+    return { contents, hash: contentHash(contents) };
+  } catch {
+    return { contents: null, hash: null };
+  }
+}
+
+async function filterReadableRows<T>(
+  ctx: PluginContext,
+  companyId: string,
+  space: Pick<WikiSpace, "pathPrefix">,
+  rows: T[],
+  pathForRow: (row: T) => string,
+): Promise<T[]> {
+  const checks: Array<T | null> = await Promise.all(rows.map(async (row): Promise<T | null> => {
+    try {
+      await ctx.localFolders.readText(companyId, WIKI_ROOT_FOLDER_KEY, spaceRelativePath(space, pathForRow(row)));
+      return row;
+    } catch {
+      return null;
+    }
+  }));
+  return checks.filter((row): row is T => row != null);
+}
+
+async function listLocalFiles(ctx: PluginContext, input: { companyId: string; space: Pick<WikiSpace, "pathPrefix">; relativePath: "wiki" | "raw" }): Promise<PluginLocalFolderEntry[]> {
+  try {
+    const relativePath = spaceRelativePath(input.space, input.relativePath);
+    const listing = await ctx.localFolders.list(input.companyId, WIKI_ROOT_FOLDER_KEY, {
+      relativePath,
+      recursive: true,
+      maxEntries: LOCAL_BROWSE_FILE_LIMIT,
+    });
+    return listing.entries
+      .filter((entry) => entry.kind === "file")
+      .map((entry) => ({ ...entry, path: logicalPathFromSpacePath(input.space, entry.path) }));
+  } catch {
+    return [];
+  }
+}
+
+function mergeLocalPageRows(pages: WikiPageRow[], entries: PluginLocalFolderEntry[]): WikiPageRow[] {
+  const byPath = new Map(pages.map((page) => [page.path, page]));
+  for (const entry of entries) {
+    if (!entry.path.endsWith(".md") || byPath.has(entry.path)) continue;
+    byPath.set(entry.path, {
+      path: entry.path,
+      title: null,
+      pageType: inferPageType(entry.path),
+      backlinkCount: 0,
+      sourceCount: 0,
+      contentHash: null,
+      updatedAt: entry.modifiedAt ?? new Date(0).toISOString(),
+    });
+  }
+  return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function mergeLocalSourceRows(sources: WikiSourceRow[], entries: PluginLocalFolderEntry[]): WikiSourceRow[] {
+  const byPath = new Map(sources.map((source) => [source.rawPath, source]));
+  for (const entry of entries) {
+    if (!entry.path.endsWith(".md") || byPath.has(entry.path)) continue;
+    byPath.set(entry.path, {
+      rawPath: entry.path,
+      title: null,
+      sourceType: "local_file",
+      url: null,
+      status: "present",
+      createdAt: entry.modifiedAt ?? new Date(0).toISOString(),
+    });
+  }
+  return [...byPath.values()].sort((a, b) => a.rawPath.localeCompare(b.rawPath));
+}
+
+function assertExpectedHash(expectedHash: string | null | undefined, currentHash: string | null, path: string): void {
+  if (expectedHash && currentHash && expectedHash !== currentHash) {
+    throw new Error(`Refusing to overwrite ${path}: expected hash ${expectedHash} but current hash is ${currentHash}`);
+  }
+}
+
+async function upsertWikiInstance(ctx: PluginContext, input: { companyId: string; wikiId: string; rootPath?: string | null }) {
+  await ctx.db.execute(
+    `INSERT INTO ${tableName(ctx.db.namespace, "wiki_instances")} AS wiki_instances
+       (id, company_id, wiki_id, root_folder_key, configured_root_path, schema_version, settings, managed_agent_key, managed_project_key)
+     VALUES ($1, $2, $3, $4, $5, 1, '{}'::jsonb, $6, $7)
+     ON CONFLICT (company_id, wiki_id)
+     DO UPDATE SET configured_root_path = COALESCE(EXCLUDED.configured_root_path, wiki_instances.configured_root_path),
+                   managed_agent_key = EXCLUDED.managed_agent_key,
+                   managed_project_key = EXCLUDED.managed_project_key,
+                   updated_at = now()`,
+    [
+      randomUUID(),
+      input.companyId,
+      input.wikiId,
+      WIKI_ROOT_FOLDER_KEY,
+      input.rootPath ?? null,
+      WIKI_MAINTAINER_AGENT_KEY,
+      WIKI_PROJECT_KEY,
+    ],
+  );
+}
+
+async function upsertPageMetadata(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId: string;
+  spaceId: string;
+  path: string;
+  contents: string;
+  summary?: string | null;
+  sourceRefs?: unknown;
+  operationId?: string | null;
+}) {
+  const pageId = randomUUID();
+  const revisionId = randomUUID();
+  const hash = contentHash(input.contents);
+  const title = inferTitle(input.path, input.contents);
+  const pageType = inferPageType(input.path);
+  const backlinks = extractWikiLinks(input.contents);
+  const sourceRefs = Array.isArray(input.sourceRefs) ? input.sourceRefs : [];
+
+  await ctx.db.execute(
+    `INSERT INTO ${tableName(ctx.db.namespace, "wiki_pages")}
+       (id, company_id, wiki_id, space_id, path, title, page_type, frontmatter, source_refs, backlinks, content_hash, current_revision_id)
+     VALUES ($1, $2, $3, $11, $4, $5, $6, '{}'::jsonb, $7::jsonb, $8::jsonb, $9, $10)
+     ON CONFLICT (company_id, wiki_id, space_id, path)
+     DO UPDATE SET title = EXCLUDED.title,
+                   page_type = EXCLUDED.page_type,
+                   source_refs = EXCLUDED.source_refs,
+                   backlinks = EXCLUDED.backlinks,
+                   content_hash = EXCLUDED.content_hash,
+                   current_revision_id = EXCLUDED.current_revision_id,
+                   updated_at = now()`,
+    [
+      pageId,
+      input.companyId,
+      input.wikiId,
+      input.path,
+      title,
+      pageType,
+      jsonParam(sourceRefs),
+      jsonParam(backlinks),
+      hash,
+      revisionId,
+      input.spaceId,
+    ],
+  );
+
+  await ctx.db.execute(
+    `INSERT INTO ${tableName(ctx.db.namespace, "wiki_page_revisions")}
+       (id, company_id, wiki_id, space_id, page_id, operation_id, path, content_hash, summary, metadata)
+     VALUES ($1, $2, $3, $8, (SELECT id FROM ${tableName(ctx.db.namespace, "wiki_pages")} WHERE company_id = $2 AND wiki_id = $3 AND space_id = $8 AND path = $4), $7, $4, $5, $6, '{}'::jsonb)`,
+    [revisionId, input.companyId, input.wikiId, input.path, hash, input.summary ?? null, input.operationId ?? null, input.spaceId],
+  );
+
+  return { title, pageType, backlinks, hash, revisionId };
+}
+
+export async function writeWikiPage(ctx: PluginContext, input: WritePageInput) {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const path = assertPagePath(input.path);
+  assertPageWriteAllowed(path, input.writer);
+  const current = await readCurrentWithHash(ctx, input.companyId, path, space);
+  assertExpectedHash(input.expectedHash, current.hash, path);
+  await ctx.localFolders.writeTextAtomic(input.companyId, WIKI_ROOT_FOLDER_KEY, spaceRelativePath(space, path), input.contents);
+  const metadata = await upsertPageMetadata(ctx, {
+    companyId: input.companyId,
+    wikiId,
+    spaceId: space.id,
+    path,
+    contents: input.contents,
+    summary: input.summary,
+    sourceRefs: input.sourceRefs,
+    operationId: input.operationId,
+  });
+  await upsertWikiInstance(ctx, { companyId: input.companyId, wikiId });
+  return { status: "ok", wikiId, spaceSlug: space.slug, path, previousHash: current.hash, ...metadata };
+}
+
+export async function captureWikiSource(ctx: PluginContext, input: CaptureSourceInput) {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const title = stringField(input.title) ?? "Untitled source";
+  await assertSourceWithinConfiguredLimit(ctx, input.contents);
+  const hash = contentHash(input.contents);
+  const rawPath = input.rawPath
+    ? assertRawPath(input.rawPath)
+    : assertRawPath(`raw/${new Date().toISOString().slice(0, 10)}-${slugify(title)}-${hash.slice(0, 8)}.md`);
+  await ctx.localFolders.writeTextAtomic(input.companyId, WIKI_ROOT_FOLDER_KEY, spaceRelativePath(space, rawPath), input.contents);
+  await upsertWikiInstance(ctx, { companyId: input.companyId, wikiId });
+  const sourceId = randomUUID();
+  await ctx.db.execute(
+    `INSERT INTO ${tableName(ctx.db.namespace, "wiki_sources")}
+       (id, company_id, wiki_id, space_id, source_type, title, url, raw_path, content_hash, status, metadata)
+     VALUES ($1, $2, $3, $10, $4, $5, $6, $7, $8, 'captured', $9::jsonb)`,
+    [
+      sourceId,
+      input.companyId,
+      wikiId,
+      stringField(input.sourceType) ?? "text",
+      title,
+      stringField(input.url),
+      rawPath,
+      hash,
+      jsonParam(input.metadata ?? {}),
+      space.id,
+    ],
+  );
+  return { status: "ok", sourceId, wikiId, spaceSlug: space.slug, rawPath, hash, title };
+}
+
+export async function getOverview(ctx: PluginContext, companyId: string): Promise<WikiOverview> {
+  const [defaultSpace, folder, managedAgent, managedProject, managedSkills] = await Promise.all([
+    ensureDefaultSpace(ctx, { companyId, wikiId: DEFAULT_WIKI_ID }),
+    ctx.localFolders.status(companyId, WIKI_ROOT_FOLDER_KEY),
+    resolveWikiAgentResource(ctx, companyId),
+    resolveWikiProjectResource(ctx, companyId),
+    resolveWikiSkillResources(ctx, companyId),
+  ]);
+  const operationRows = await ctx.db.query<{ count: string }>(
+    `SELECT count(*)::text AS count FROM ${tableName(ctx.db.namespace, "wiki_operations")} WHERE company_id = $1`,
+    [companyId],
+  );
+  const operationCount = Number(operationRows[0]?.count ?? 0);
+  const eventIngestion = await getEventIngestionSettings(ctx, companyId);
+  return {
+    status: "ok",
+    checkedAt: new Date().toISOString(),
+    wikiId: DEFAULT_WIKI_ID,
+    defaultSpace,
+    folder,
+    managedAgent,
+    managedProject,
+    managedSkills,
+    operationCount,
+    eventIngestion,
+    capabilities: ctx.manifest.capabilities,
+    prompts: {
+      query: QUERY_PROMPT,
+      lint: LINT_PROMPT,
+    },
+  };
+}
+
+export async function resolveWikiAgentResource(
+  ctx: PluginContext,
+  companyId: string,
+  options: { reconcileMissing?: boolean } = {},
+): Promise<WikiAgentResource> {
+  const wikiId = DEFAULT_WIKI_ID;
+  const binding = await getResourceBinding(ctx, {
+    companyId,
+    wikiId,
+    resourceKind: "agent",
+    resourceKey: WIKI_MAINTAINER_AGENT_KEY,
+  });
+  const selectedAgent = await resolveSelectedAgent(ctx, companyId, binding);
+  if (selectedAgent) {
+    const source = binding?.metadata.source === "managed-default" ? "managed" : "selected";
+    const managedResolution = source === "managed"
+      ? await ctx.agents.managed.get(WIKI_MAINTAINER_AGENT_KEY, companyId)
+      : null;
+    return agentResource({
+      status: "resolved",
+      source,
+      agent: selectedAgent,
+      defaultDrift: managedResolution?.defaultDrift ?? null,
+    });
+  }
+  if (binding?.resolvedId && !options.reconcileMissing) {
+    return agentResource({ status: "missing", source: "selected", agent: null });
+  }
+
+  const resolved = options.reconcileMissing
+    ? await ctx.agents.managed.reconcile(WIKI_MAINTAINER_AGENT_KEY, companyId)
+    : await ctx.agents.managed.get(WIKI_MAINTAINER_AGENT_KEY, companyId);
+  if (resolved.agentId && options.reconcileMissing) {
+    await upsertResourceBinding(ctx, {
+      companyId,
+      wikiId,
+      resourceKind: "agent",
+      resourceKey: WIKI_MAINTAINER_AGENT_KEY,
+      resolvedId: resolved.agentId,
+      metadata: { source: "managed-default", updatedBy: "resolve" },
+    });
+  }
+  return agentResource({ status: resolved.status, source: "managed", agent: resolved.agent, defaultDrift: resolved.defaultDrift ?? null });
+}
+
+export async function resolveWikiProjectResource(
+  ctx: PluginContext,
+  companyId: string,
+  options: { reconcileMissing?: boolean } = {},
+): Promise<WikiProjectResource> {
+  const wikiId = DEFAULT_WIKI_ID;
+  const binding = await getResourceBinding(ctx, {
+    companyId,
+    wikiId,
+    resourceKind: "project",
+    resourceKey: WIKI_PROJECT_KEY,
+  });
+  const selectedProject = await resolveSelectedProject(ctx, companyId, binding);
+  if (selectedProject) {
+    return projectResource({
+      status: "resolved",
+      source: binding?.metadata.source === "managed-default" ? "managed" : "selected",
+      project: selectedProject,
+    });
+  }
+  if (binding?.resolvedId && !options.reconcileMissing) {
+    return projectResource({ status: "missing", source: "selected", project: null });
+  }
+
+  const resolved = options.reconcileMissing
+    ? await ctx.projects.managed.reconcile(WIKI_PROJECT_KEY, companyId)
+    : await ctx.projects.managed.get(WIKI_PROJECT_KEY, companyId);
+  if (resolved.projectId && options.reconcileMissing) {
+    await upsertResourceBinding(ctx, {
+      companyId,
+      wikiId,
+      resourceKind: "project",
+      resourceKey: WIKI_PROJECT_KEY,
+      resolvedId: resolved.projectId,
+      metadata: { source: "managed-default", updatedBy: "resolve" },
+    });
+  }
+  return projectResource({ status: resolved.status, source: "managed", project: resolved.project });
+}
+
+export async function resolveWikiSkillResources(
+  ctx: PluginContext,
+  companyId: string,
+  options: { reconcileMissing?: boolean } = {},
+): Promise<WikiSkillResource[]> {
+  return Promise.all(
+    WIKI_MANAGED_SKILL_KEYS.map(async (skillKey) => {
+      const resolved = options.reconcileMissing
+        ? await ctx.skills.managed.reconcile(skillKey, companyId)
+        : await ctx.skills.managed.get(skillKey, companyId);
+      return skillResource(resolved);
+    }),
+  );
+}
+
+export async function reconcileWikiAgentResource(ctx: PluginContext, companyId: string): Promise<WikiAgentResource> {
+  const resolved = await ctx.agents.managed.reconcile(WIKI_MAINTAINER_AGENT_KEY, companyId);
+  if (resolved.agentId) {
+    await upsertResourceBinding(ctx, {
+      companyId,
+      wikiId: DEFAULT_WIKI_ID,
+      resourceKind: "agent",
+      resourceKey: WIKI_MAINTAINER_AGENT_KEY,
+      resolvedId: resolved.agentId,
+      metadata: { source: "managed-default", updatedBy: "reconcile" },
+    });
+  }
+  return agentResource({ status: resolved.status, source: "managed", agent: resolved.agent, defaultDrift: resolved.defaultDrift ?? null });
+}
+
+export async function resetWikiAgentResource(ctx: PluginContext, companyId: string): Promise<WikiAgentResource> {
+  const resolved = await ctx.agents.managed.reset(WIKI_MAINTAINER_AGENT_KEY, companyId);
+  if (resolved.agentId) {
+    await upsertResourceBinding(ctx, {
+      companyId,
+      wikiId: DEFAULT_WIKI_ID,
+      resourceKind: "agent",
+      resourceKey: WIKI_MAINTAINER_AGENT_KEY,
+      resolvedId: resolved.agentId,
+      metadata: { source: "managed-default", updatedBy: "reset" },
+    });
+  }
+  return agentResource({ status: resolved.status, source: "managed", agent: resolved.agent, defaultDrift: resolved.defaultDrift ?? null });
+}
+
+export async function selectWikiAgentResource(ctx: PluginContext, input: { companyId: string; agentId: string }): Promise<WikiAgentResource> {
+  const agent = await ctx.agents.get(input.agentId, input.companyId);
+  if (!agent || agent.status === "terminated") {
+    throw new Error("Selected Wiki Maintainer agent was not found or is terminated.");
+  }
+  await upsertResourceBinding(ctx, {
+    companyId: input.companyId,
+    wikiId: DEFAULT_WIKI_ID,
+    resourceKind: "agent",
+    resourceKey: WIKI_MAINTAINER_AGENT_KEY,
+    resolvedId: agent.id,
+    metadata: { source: "selected-existing", updatedBy: "settings" },
+  });
+  return agentResource({ status: "resolved", source: "selected", agent });
+}
+
+export async function reconcileWikiProjectResource(ctx: PluginContext, companyId: string): Promise<WikiProjectResource> {
+  const resolved = await ctx.projects.managed.reconcile(WIKI_PROJECT_KEY, companyId);
+  if (resolved.projectId) {
+    await upsertResourceBinding(ctx, {
+      companyId,
+      wikiId: DEFAULT_WIKI_ID,
+      resourceKind: "project",
+      resourceKey: WIKI_PROJECT_KEY,
+      resolvedId: resolved.projectId,
+      metadata: { source: "managed-default", updatedBy: "reconcile" },
+    });
+  }
+  return projectResource({ status: resolved.status, source: "managed", project: resolved.project });
+}
+
+export async function resetWikiProjectResource(ctx: PluginContext, companyId: string): Promise<WikiProjectResource> {
+  const resolved = await ctx.projects.managed.reset(WIKI_PROJECT_KEY, companyId);
+  if (resolved.projectId) {
+    await upsertResourceBinding(ctx, {
+      companyId,
+      wikiId: DEFAULT_WIKI_ID,
+      resourceKind: "project",
+      resourceKey: WIKI_PROJECT_KEY,
+      resolvedId: resolved.projectId,
+      metadata: { source: "managed-default", updatedBy: "reset" },
+    });
+  }
+  return projectResource({ status: resolved.status, source: "managed", project: resolved.project });
+}
+
+export async function reconcileWikiSkillResources(ctx: PluginContext, companyId: string): Promise<WikiSkillResource[]> {
+  return resolveWikiSkillResources(ctx, companyId, { reconcileMissing: true });
+}
+
+export async function resetWikiSkillResources(ctx: PluginContext, companyId: string): Promise<WikiSkillResource[]> {
+  return Promise.all(
+    WIKI_MANAGED_SKILL_KEYS.map(async (skillKey) => {
+      return skillResource(await ctx.skills.managed.reset(skillKey, companyId));
+    }),
+  );
+}
+
+export async function reconcileWikiRoutineResources(
+  ctx: PluginContext,
+  companyId: string,
+): Promise<{
+  managedAgent: WikiAgentResource;
+  managedProject: WikiProjectResource;
+  managedRoutines: PluginManagedRoutineResolution[];
+}> {
+  const [managedAgent, managedProject] = await Promise.all([
+    reconcileWikiAgentResource(ctx, companyId),
+    reconcileWikiProjectResource(ctx, companyId),
+  ]);
+
+  const managedRoutines = await Promise.all(
+    WIKI_MAINTENANCE_ROUTINE_KEYS.map((routineKey) =>
+      ctx.routines.managed.reconcile(routineKey, companyId, {
+        assigneeAgentId: managedAgent.agentId,
+        projectId: managedProject.projectId,
+      })),
+  );
+
+  return { managedAgent, managedProject, managedRoutines };
+}
+
+export async function selectWikiProjectResource(ctx: PluginContext, input: { companyId: string; projectId: string }): Promise<WikiProjectResource> {
+  const project = await ctx.projects.get(input.projectId, input.companyId);
+  if (!project) {
+    throw new Error("Selected LLM Wiki project was not found.");
+  }
+  await upsertResourceBinding(ctx, {
+    companyId: input.companyId,
+    wikiId: DEFAULT_WIKI_ID,
+    resourceKind: "project",
+    resourceKey: WIKI_PROJECT_KEY,
+    resolvedId: project.id,
+    metadata: { source: "selected-existing", updatedBy: "settings" },
+  });
+  return projectResource({ status: "resolved", source: "selected", project });
+}
+
+export async function listWikiAgentOptions(ctx: PluginContext, companyId: string): Promise<WikiResourceOption[]> {
+  const agents = await ctx.agents.list({ companyId, limit: 200 });
+  return agents
+    .filter((agent) => agent.status !== "terminated")
+    .map((agent) => ({
+      id: agent.id,
+      name: agent.name,
+      status: agent.status,
+      adapterType: agent.adapterType ?? null,
+      icon: agent.icon ?? null,
+      urlKey: agent.urlKey ?? null,
+    }));
+}
+
+export async function listWikiProjectOptions(ctx: PluginContext, companyId: string): Promise<WikiResourceOption[]> {
+  const projects = await ctx.projects.list({ companyId, limit: 200 });
+  return projects.map((project) => ({ id: project.id, name: project.name, status: project.status, color: project.color ?? null }));
+}
+
+export async function bootstrapWikiRoot(ctx: PluginContext, input: BootstrapInput) {
+  const wikiId = DEFAULT_WIKI_ID;
+  const defaultSpace = await ensureDefaultSpace(ctx, { companyId: input.companyId, wikiId });
+  const configureFolder = (path: string) => ctx.localFolders.configure({
+      companyId: input.companyId,
+      folderKey: WIKI_ROOT_FOLDER_KEY,
+      path,
+      access: "readWrite",
+      requiredDirectories: [...REQUIRED_WIKI_DIRECTORIES],
+      requiredFiles: [...REQUIRED_WIKI_FILES],
+    });
+  const currentFolder = input.path
+    ? null
+    : await ctx.localFolders.status(input.companyId, WIKI_ROOT_FOLDER_KEY);
+  const folder = input.path
+    ? await configureFolder(input.path)
+    : currentFolder?.configured && currentFolder.path
+      ? await configureFolder(currentFolder.path)
+      : currentFolder ?? await ctx.localFolders.status(input.companyId, WIKI_ROOT_FOLDER_KEY);
+
+  const writtenFiles: string[] = [];
+  const preservedFiles: string[] = [];
+  for (const file of BOOTSTRAP_FILES) {
+    const path = assertWikiPath(file.path, { allowMetadata: true });
+    try {
+      await ctx.localFolders.readText(input.companyId, WIKI_ROOT_FOLDER_KEY, path);
+      preservedFiles.push(path);
+      continue;
+    } catch {
+      // Missing files are initialized below. Existing files are intentionally preserved.
+    }
+    await ctx.localFolders.writeTextAtomic(input.companyId, WIKI_ROOT_FOLDER_KEY, file.path, file.contents);
+    writtenFiles.push(path);
+  }
+
+  await upsertWikiInstance(ctx, { companyId: input.companyId, wikiId, rootPath: folder.path });
+  const managedSkills = await reconcileWikiSkillResources(ctx, input.companyId);
+  const [managedAgent, managedProject] = await Promise.all([
+    reconcileWikiAgentResource(ctx, input.companyId),
+    reconcileWikiProjectResource(ctx, input.companyId),
+  ]);
+  await ctx.state.set(
+    {
+      scopeKind: "company",
+      scopeId: input.companyId,
+      namespace: "llm-wiki",
+      stateKey: "last-bootstrap",
+    },
+    { at: new Date().toISOString(), path: folder.path },
+  );
+
+  return {
+    status: "ok",
+    folder,
+    wikiId,
+    space: defaultSpace,
+    managedAgent,
+    managedProject,
+    managedSkills,
+    writtenFiles,
+    preservedFiles,
+  };
+}
+
+export async function bootstrapSpace(ctx: PluginContext, input: SpaceInput) {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const { writtenFiles, preservedFiles } = await bootstrapSpaceFiles(ctx, input.companyId, space);
+  await upsertWikiInstance(ctx, { companyId: input.companyId, wikiId });
+  return {
+    status: "ok",
+    wikiId,
+    space,
+    writtenFiles,
+    preservedFiles,
+  };
+}
+
+async function bootstrapSpaceFiles(ctx: PluginContext, companyId: string, space: WikiSpace) {
+  const writtenFiles: string[] = [];
+  const preservedFiles: string[] = [];
+  for (const file of BOOTSTRAP_FILES) {
+    const path = assertWikiPath(file.path, { allowMetadata: true });
+    const physicalPath = spaceRelativePath(space, path);
+    try {
+      await ctx.localFolders.readText(companyId, WIKI_ROOT_FOLDER_KEY, physicalPath);
+      preservedFiles.push(path);
+      continue;
+    } catch {
+      // Missing files are initialized below. Existing files are intentionally preserved.
+    }
+    await ctx.localFolders.writeTextAtomic(companyId, WIKI_ROOT_FOLDER_KEY, physicalPath, file.contents);
+    writtenFiles.push(path);
+  }
+  return { writtenFiles, preservedFiles };
+}
+
+function operationSpaceRoot(space: WikiSpace): string {
+  return space.pathPrefix ? `${space.rootFolderKey}/${space.pathPrefix}` : `${space.rootFolderKey} root`;
+}
+
+function operationBillingContext(wikiId: string, space: WikiSpace): string {
+  return space.slug === DEFAULT_SPACE_SLUG
+    ? `plugin-llm-wiki:${wikiId} (space ${space.slug})`
+    : `plugin-llm-wiki:${wikiId}:${space.slug}`;
+}
+
+function operationBillingCode(wikiId: string, space: WikiSpace): string {
+  return space.slug === DEFAULT_SPACE_SLUG ? `plugin-llm-wiki:${wikiId}` : `plugin-llm-wiki:${wikiId}:${space.slug}`;
+}
+
+function operationIssueOriginId(input: { wikiId: string; space: WikiSpace; operationId: string }): string {
+  return input.space.slug === DEFAULT_SPACE_SLUG
+    ? `wiki:${input.wikiId}:operation:${input.operationId}`
+    : `wiki:${input.wikiId}:space:${input.space.slug}:operation:${input.operationId}`;
+}
+
+function operationTitleWithSpace(title: string, space: WikiSpace): string {
+  return `${title} [space: ${space.displayName} / ${space.slug}]`;
+}
+
+function operationPromptWithSpaceContext(input: OperationSpaceContext): string {
+  const paperclipDerived = input.operationType === "distill" || input.operationType === "backfill";
+  return [
+    `Plugin operation: ${input.operationType}`,
+    `Wiki ID: ${input.wikiId}`,
+    `Space: ${input.space.displayName} (${input.space.slug})`,
+    `Space root: ${operationSpaceRoot(input.space)}`,
+    `Billing context: ${operationBillingContext(input.wikiId, input.space)}`,
+    "",
+    "Space isolation requirement:",
+    `- Pass wikiId \`${input.wikiId}\` and spaceSlug \`${input.space.slug}\` on every LLM Wiki tool call.`,
+    "- Treat all paths in the prompt as relative to this space root.",
+    paperclipDerived
+      ? "- Paperclip-derived distill/backfill operations are default-space-only in Phase 1. Stop and comment if asked to write Paperclip-derived pages into a non-default space."
+      : "- Manual ingest, query, lint, index, and file-as-page operations follow the named destination space. Do not cross into another space unless the operation explicitly asks for a multi-space sweep.",
+    "",
+    input.prompt ?? "Created by the LLM Wiki plugin.",
+  ].join("\n");
+}
+
+function operationMetadata(input: OperationSpaceContext) {
+  return {
+    operationType: input.operationType,
+    operationId: input.operationId,
+    wikiId: input.wikiId,
+    spaceId: input.space.id,
+    spaceSlug: input.space.slug,
+    spaceName: input.space.displayName,
+    spaceRootFolderKey: input.space.rootFolderKey,
+    spacePathPrefix: input.space.pathPrefix,
+    spaceRoot: operationSpaceRoot(input.space),
+  };
+}
+
+export async function createOperationIssue(ctx: PluginContext, input: OperationInput) {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = input.operationType === "distill" || input.operationType === "backfill"
+    ? await requirePaperclipIngestionPolicy(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug }, "queue", { requireEnabledProfile: true })
+    : await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const managedAgent = await resolveWikiAgentResource(ctx, input.companyId, { reconcileMissing: true });
+  const managedProject = await resolveWikiProjectResource(ctx, input.companyId, { reconcileMissing: true });
+  const operationId = randomUUID();
+  const title = operationTitleWithSpace(input.title ?? `LLM Wiki ${input.operationType}`, space);
+  const originId = operationIssueOriginId({ wikiId, space, operationId });
+  const operationContext = { wikiId, space, operationType: input.operationType, operationId, prompt: input.prompt };
+  const assignableAgentId =
+    managedAgent.agent &&
+    managedAgent.agent.status !== "pending_approval" &&
+    managedAgent.agent.status !== "terminated"
+      ? managedAgent.agent.id
+      : undefined;
+  const issue = await ctx.issues.create({
+    companyId: input.companyId,
+    projectId: managedProject.projectId ?? undefined,
+    title,
+    description: operationPromptWithSpaceContext(operationContext),
+    status: "todo",
+    priority: input.operationType === "query" ? "medium" : "low",
+    assigneeAgentId: assignableAgentId,
+    assigneeAdapterOverrides: input.useCheapModelProfile ? { modelProfile: "cheap" } : null,
+    billingCode: operationBillingCode(wikiId, space),
+    surfaceVisibility: "plugin_operation",
+    originKind: `${OPERATION_ORIGIN_KIND}:${input.operationType}` as PluginIssueOriginKind,
+    originId,
+  });
+
+  await ctx.db.execute(
+    `INSERT INTO ${tableName(ctx.db.namespace, "wiki_operations")}
+       (id, company_id, wiki_id, space_id, operation_type, status, hidden_issue_id, project_id, run_ids, cost_cents, warnings, metadata)
+     VALUES ($1, $2, $3, $8, $4, $5, $6, $7, '[]'::jsonb, 0, '[]'::jsonb, $9::jsonb)`,
+    [
+      operationId,
+      input.companyId,
+      wikiId,
+      input.operationType,
+      "queued",
+      issue.id,
+      issue.projectId ?? null,
+      space.id,
+      jsonParam({
+        ...operationMetadata(operationContext),
+        issueOriginId: originId,
+        billingCode: operationBillingCode(wikiId, space),
+      }),
+    ],
+  );
+
+  return { operationId, wikiId, spaceSlug: space.slug, issue };
+}
+
+function isLlmWikiOperationIssue(issue: Issue): boolean {
+  return typeof issue.originKind === "string" && issue.originKind.startsWith(OPERATION_ORIGIN_KIND);
+}
+
+function paperclipDistillationScope(input: { projectId?: string | null; rootIssueId?: string | null }): PaperclipDistillationScope {
+  if (input.rootIssueId) return "root_issue";
+  if (input.projectId) return "project";
+  return "company";
+}
+
+function paperclipCursorScopeMetadata(input: { projectId?: string | null; rootIssueId?: string | null }) {
+  const sourceScope = paperclipDistillationScope(input);
+  const projectId = sourceScope === "project" ? input.projectId ?? null : null;
+  const rootIssueId = sourceScope === "root_issue" ? input.rootIssueId ?? null : null;
+  return {
+    sourceScope,
+    scopeKey: rootIssueId ?? projectId ?? "company",
+    projectId,
+    rootIssueId,
+  };
+}
+
+async function upsertPaperclipDistillationCursor(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId: string;
+  spaceId: string;
+  projectId?: string | null;
+  rootIssueId?: string | null;
+  observedAt?: string | null;
+  metadata?: Record<string, unknown>;
+}): Promise<string> {
+  const cursorId = randomUUID();
+  const scope = paperclipCursorScopeMetadata(input);
+  await ctx.db.execute(
+    `INSERT INTO ${distillationCursorTable(ctx)} AS paperclip_distillation_cursors
+       (id, company_id, wiki_id, space_id, source_scope, scope_key, project_id, root_issue_id, source_kind, last_observed_at, pending_event_count, metadata)
+     VALUES ($1, $2, $3, $11, $4, $5, $6, $7, 'paperclip_issue_history', $8::timestamptz, $9, $10::jsonb)
+     ON CONFLICT (company_id, wiki_id, space_id, source_scope, scope_key, source_kind)
+     DO UPDATE SET last_observed_at = GREATEST(
+                       COALESCE(paperclip_distillation_cursors.last_observed_at, EXCLUDED.last_observed_at),
+                       COALESCE(EXCLUDED.last_observed_at, paperclip_distillation_cursors.last_observed_at)
+                     ),
+                   pending_event_count = paperclip_distillation_cursors.pending_event_count + EXCLUDED.pending_event_count,
+                   metadata = paperclip_distillation_cursors.metadata || EXCLUDED.metadata,
+                   updated_at = now()`,
+    [
+      cursorId,
+      input.companyId,
+      input.wikiId,
+      scope.sourceScope,
+      scope.scopeKey,
+      scope.projectId,
+      scope.rootIssueId,
+      input.observedAt ?? null,
+      input.observedAt ? 1 : 0,
+      jsonParam(input.metadata ?? {}),
+      input.spaceId,
+    ],
+  );
+  const rows = await ctx.db.query<{ id: string }>(
+    `SELECT id
+       FROM ${distillationCursorTable(ctx)}
+      WHERE company_id = $1
+        AND wiki_id = $2
+        AND space_id = $3
+        AND source_scope = $4
+        AND scope_key = $5
+        AND source_kind = 'paperclip_issue_history'
+      LIMIT 1`,
+    [input.companyId, input.wikiId, input.spaceId, scope.sourceScope, scope.scopeKey],
+  );
+  return rows[0]?.id ?? cursorId;
+}
+
+function isActiveDistillationProject(project: Project): boolean {
+  if (project.status !== "in_progress") return false;
+  if (project.archivedAt) return false;
+  if (project.managedByPlugin?.pluginKey === PLUGIN_ID) return false;
+  if (project.managedByPlugin?.resourceKey === WIKI_PROJECT_KEY) return false;
+  return true;
+}
+
+function projectActivityTimestamp(project: Project): string {
+  return isoString(project.updatedAt) ?? new Date().toISOString();
+}
+
+export async function enableActiveProjectDistillation(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  limit?: number | null;
+}): Promise<EnableActiveProjectDistillationResult> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await requirePaperclipIngestionPolicy(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug }, "candidate_search", { requireEnabledProfile: true });
+  if (typeof input.limit === "number" && Number.isFinite(input.limit) && Math.floor(input.limit) > MAX_PAPERCLIP_DISTILLATION_FAN_OUT) {
+    throw new Error(`Paperclip ingestion fan-out exceeds the hard cap of ${MAX_PAPERCLIP_DISTILLATION_FAN_OUT} enabled profiles.`);
+  }
+  const limit = normalizeLimit(input.limit ?? 3, 3, 25);
+  const projects = await ctx.projects.list({ companyId: input.companyId, limit: 200 });
+  const activeProjects = projects
+    .filter(isActiveDistillationProject)
+    .sort((a, b) => projectActivityTimestamp(b).localeCompare(projectActivityTimestamp(a)))
+    .slice(0, limit);
+
+  const selectedProjects: EnableActiveProjectDistillationResult["selectedProjects"] = [];
+  for (const project of activeProjects) {
+    const observedAt = projectActivityTimestamp(project);
+    const cursorId = await upsertPaperclipDistillationCursor(ctx, {
+      companyId: input.companyId,
+      wikiId,
+      spaceId: space.id,
+      projectId: project.id,
+      rootIssueId: null,
+      observedAt,
+      metadata: {
+        configuredBy: "enable-active-projects",
+        projectName: project.name,
+        projectStatus: project.status,
+      },
+    });
+    selectedProjects.push({
+      id: project.id,
+      name: project.name,
+      status: project.status,
+      observedAt,
+      cursorId,
+    });
+  }
+
+  const eventIngestion = await updateEventIngestionSettings(ctx, {
+    companyId: input.companyId,
+    settings: {
+      enabled: true,
+      wikiId,
+      sources: {
+        issues: true,
+        comments: true,
+        documents: true,
+      },
+    },
+  });
+
+  return {
+    wikiId,
+    spaceSlug: space.slug,
+    selectedProjects,
+    eventIngestion,
+  };
+}
+
+function appendBoundedSection(input: {
+  lines: string[];
+  title: string;
+  body: string;
+  refs: PaperclipSourceRef[];
+  ref: PaperclipSourceRef;
+  remaining: { value: number };
+  perSourceLimit: number;
+  warnings: string[];
+}) {
+  if (input.remaining.value <= 0) {
+    input.warnings.push(`Skipped ${input.title}: source bundle character limit reached.`);
+    return;
+  }
+  const boundedBody = input.body.length > input.perSourceLimit
+    ? `${input.body.slice(0, input.perSourceLimit)}\n\n[Clipped at ${input.perSourceLimit} characters for this source.]`
+    : input.body;
+  const section = [`## ${input.title}`, "", boundedBody.trim() || "_No content._", ""].join("\n");
+  const clippedSection = section.length > input.remaining.value
+    ? `${section.slice(0, input.remaining.value)}\n\n[Source bundle clipped at configured limit.]\n`
+    : section;
+  input.lines.push(clippedSection);
+  input.refs.push(input.ref);
+  if (boundedBody.length !== input.body.length || clippedSection.length !== section.length) {
+    input.warnings.push(`Clipped ${input.title}.`);
+  }
+  input.remaining.value -= clippedSection.length;
+}
+
+function issueSortKey(issue: Issue): string {
+  return `${issue.identifier ?? ""}:${issue.title}:${issue.id}`;
+}
+
+function sourceRefUpdatedAt(ref: PaperclipSourceRef): string | null {
+  return ref.updatedAt ?? ref.createdAt ?? null;
+}
+
+function issueInBackfillWindow(issue: Issue, input: Pick<PaperclipSourceBundleInput, "backfillStartAt" | "backfillEndAt">): boolean {
+  const issueUpdatedAt = isoString(issue.updatedAt);
+  if (!issueUpdatedAt) return true;
+  const startAt = isoString(input.backfillStartAt);
+  const endAt = isoString(input.backfillEndAt);
+  if (startAt && issueUpdatedAt < startAt) return false;
+  if (endAt && issueUpdatedAt > endAt) return false;
+  return true;
+}
+
+async function listPaperclipBundleIssues(ctx: PluginContext, input: PaperclipSourceBundleInput): Promise<Issue[]> {
+  const filterAndSort = (issues: Issue[]) =>
+    issues
+      .filter((issue) => !isLlmWikiOperationIssue(issue))
+      .filter((issue) => issueInBackfillWindow(issue, input))
+      .sort((a, b) => issueSortKey(a).localeCompare(issueSortKey(b)));
+
+  if (input.rootIssueId) {
+    const subtree = await ctx.issues.getSubtree(input.rootIssueId, input.companyId, {
+      includeRoot: true,
+      includeRelations: true,
+      includeDocuments: true,
+      includeAssignees: true,
+    });
+    return filterAndSort(subtree.issues);
+  }
+
+  const issues = await ctx.issues.list({
+    companyId: input.companyId,
+    projectId: input.projectId ?? undefined,
+    includePluginOperations: false,
+    limit: 500,
+  });
+  return filterAndSort(issues);
+}
+
+export async function assemblePaperclipSourceBundle(ctx: PluginContext, input: PaperclipSourceBundleInput): Promise<PaperclipSourceBundle> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  assertPaperclipSourceScopePayload(input);
+  const space = await requirePaperclipIngestionPolicy(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug }, "execute", { requireEnabledProfile: true });
+  const limits = await resolvePaperclipDistillationLimitsForSpace(ctx, { ...input, space });
+  const maxCharacters = limits.maxCharacters;
+  const perSourceLimit = limits.maxCharactersPerSource;
+  const includeComments = input.includeComments !== false;
+  const includeDocuments = input.includeDocuments !== false;
+  const issues = await listPaperclipBundleIssues(ctx, input);
+  const scope = paperclipCursorScopeMetadata(input);
+  const sourceRefs: PaperclipSourceRef[] = [];
+  const warnings: string[] = [];
+  const lines = [
+    `# Paperclip source bundle`,
+    "",
+    "## Bundle Metadata",
+    "",
+    `- Company ID: ${input.companyId}`,
+    `- Wiki ID: ${wikiId}`,
+    `- Space: ${space.displayName} (${space.slug})`,
+    `- Source scope: ${scope.sourceScope}`,
+    scope.projectId ? `- Project ID: ${scope.projectId}` : null,
+    scope.rootIssueId ? `- Root issue ID: ${scope.rootIssueId}` : null,
+    input.backfillStartAt ? `- Backfill start: ${isoString(input.backfillStartAt) ?? input.backfillStartAt}` : null,
+    input.backfillEndAt ? `- Backfill end: ${isoString(input.backfillEndAt) ?? input.backfillEndAt}` : null,
+    `- Issue count: ${issues.length}`,
+    `- Source caps: ${maxCharacters} characters per window; ${perSourceLimit} characters per source`,
+    "",
+  ].filter((line): line is string => line !== null);
+  const remaining = { value: maxCharacters - lines.join("\n").length };
+
+  for (const issue of issues) {
+    const issueBody = [
+      `- Issue ID: ${issue.id}`,
+      issue.identifier ? `- Identifier: ${issue.identifier}` : null,
+      `- Status: ${issue.status}`,
+      `- Priority: ${issue.priority}`,
+      issue.parentId ? `- Parent issue ID: ${issue.parentId}` : null,
+      issue.projectId ? `- Project ID: ${issue.projectId}` : null,
+      `- Updated at: ${isoString(issue.updatedAt) ?? "unknown"}`,
+      "",
+      issue.description?.trim() ? issue.description.trim() : "_No issue description._",
+    ].filter((line): line is string => line !== null).join("\n");
+    appendBoundedSection({
+      lines,
+      title: `Issue: ${sourceTitleForIssue(issue)}`,
+      body: issueBody,
+      refs: sourceRefs,
+      ref: {
+        kind: "issue",
+        issueId: issue.id,
+        issueIdentifier: issue.identifier ?? null,
+        projectId: issue.projectId ?? null,
+        title: issue.title,
+        updatedAt: isoString(issue.updatedAt) ?? undefined,
+      },
+      remaining,
+      perSourceLimit,
+      warnings,
+    });
+
+    if (includeDocuments && remaining.value > 0) {
+      const documentSummaries = await ctx.issues.documents.list(issue.id, input.companyId);
+      for (const summary of [...documentSummaries].sort((a, b) => a.key.localeCompare(b.key))) {
+        const document = await ctx.issues.documents.get(issue.id, summary.key, input.companyId);
+        if (!document) continue;
+        const protectedDocument = protectDistillationSourceBody({
+          issue,
+          sourceKind: "document",
+          sourceId: document.key,
+          body: document.body,
+        });
+        if (protectedDocument.warning) warnings.push(protectedDocument.warning);
+        appendBoundedSection({
+          lines,
+          title: `Document: ${sourceTitleForIssue(issue)} / ${document.key}`,
+          body: [
+            `- Issue ID: ${issue.id}`,
+            issue.identifier ? `- Issue identifier: ${issue.identifier}` : null,
+            `- Document ID: ${document.id}`,
+            `- Document key: ${document.key}`,
+            `- Revision: ${document.latestRevisionNumber}`,
+            `- Updated at: ${isoString(document.updatedAt) ?? "unknown"}`,
+            "",
+            protectedDocument.body,
+          ].filter((line): line is string => line !== null).join("\n"),
+          refs: sourceRefs,
+          ref: {
+            kind: "document",
+            issueId: issue.id,
+            issueIdentifier: issue.identifier ?? null,
+            projectId: issue.projectId ?? null,
+            documentId: document.id,
+            documentKey: document.key,
+            updatedAt: isoString(document.updatedAt) ?? undefined,
+            ...protectedDocument.refPatch,
+          },
+          remaining,
+          perSourceLimit,
+          warnings,
+        });
+      }
+    }
+
+    if (includeComments && remaining.value > 0) {
+      const comments = await ctx.issues.listComments(issue.id, input.companyId);
+      for (const comment of [...comments].sort((a, b) => (isoString(a.createdAt) ?? "").localeCompare(isoString(b.createdAt) ?? ""))) {
+        const protectedComment = protectDistillationSourceBody({
+          issue,
+          sourceKind: "comment",
+          sourceId: comment.id,
+          body: comment.body,
+        });
+        if (protectedComment.warning) warnings.push(protectedComment.warning);
+        appendBoundedSection({
+          lines,
+          title: `Comment: ${sourceTitleForIssue(issue)} / ${comment.id}`,
+          body: [
+            `- Issue ID: ${issue.id}`,
+            issue.identifier ? `- Issue identifier: ${issue.identifier}` : null,
+            `- Comment ID: ${comment.id}`,
+            `- Created at: ${isoString(comment.createdAt) ?? "unknown"}`,
+            "",
+            protectedComment.body,
+          ].filter((line): line is string => line !== null).join("\n"),
+          refs: sourceRefs,
+          ref: {
+            kind: "comment",
+            issueId: issue.id,
+            issueIdentifier: issue.identifier ?? null,
+            projectId: issue.projectId ?? null,
+            commentId: comment.id,
+            createdAt: isoString(comment.createdAt) ?? undefined,
+            ...protectedComment.refPatch,
+          },
+          remaining,
+          perSourceLimit,
+          warnings,
+        });
+      }
+    }
+  }
+
+  const markdown = lines.join("\n").slice(0, maxCharacters);
+  const sourceDates = sourceRefs.map(sourceRefUpdatedAt).filter((date): date is string => Boolean(date)).sort();
+  return {
+    markdown,
+    sourceRefs,
+    sourceHash: contentHash(markdown),
+    sourceWindowStart: sourceDates[0] ?? null,
+    sourceWindowEnd: sourceDates[sourceDates.length - 1] ?? null,
+    clipped: warnings.some((warning) => warning.includes("Clipped") || warning.includes("Skipped")) || lines.join("\n").length > maxCharacters,
+    warnings,
+  };
+}
+
+export async function createPaperclipDistillationRun(ctx: PluginContext, input: PaperclipDistillationRunInput) {
+  const wikiId = normalizeWikiId(input.wikiId);
+  assertPaperclipSourceScopePayload(input);
+  const space = await requirePaperclipIngestionPolicy(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug }, "execute", { requireEnabledProfile: true });
+  const scope = paperclipCursorScopeMetadata(input);
+  const limits = await resolvePaperclipDistillationLimitsForSpace(ctx, { ...input, space });
+  const cursorId = await upsertPaperclipDistillationCursor(ctx, {
+    companyId: input.companyId,
+    wikiId,
+    spaceId: space.id,
+    projectId: scope.projectId,
+    rootIssueId: scope.rootIssueId,
+    metadata: { source: "source-bundle" },
+  });
+  const bundle = await assemblePaperclipSourceBundle(ctx, input);
+  const estimatedCostCents = estimateSourceCostCents(
+    bundle.markdown.length,
+    limits.costCentsPerThousandSourceCharacters,
+  );
+  const runId = randomUUID();
+  const snapshotId = randomUUID();
+
+  await ctx.db.execute(
+    `INSERT INTO ${distillationRunTable(ctx)}
+       (id, company_id, wiki_id, space_id, cursor_id, work_item_id, project_id, root_issue_id, source_window_start, source_window_end, source_hash, status, operation_issue_id, retry_count, cost_cents, warnings, metadata)
+     VALUES ($1, $2, $3, $15, $4, $5, $6, $7, $8::timestamptz, $9::timestamptz, $10, 'source_ready', $11, 0, $12, $13::jsonb, $14::jsonb)`,
+    [
+      runId,
+      input.companyId,
+      wikiId,
+      cursorId,
+      input.workItemId ?? null,
+      scope.projectId,
+      scope.rootIssueId,
+      bundle.sourceWindowStart,
+      bundle.sourceWindowEnd,
+      bundle.sourceHash,
+      input.operationIssueId ?? null,
+      estimatedCostCents,
+      jsonArrayParam(bundle.warnings),
+      jsonParam({
+        spaceSlug: space.slug,
+        sourceScope: scope.sourceScope,
+        limits,
+        backfillStartAt: isoString(input.backfillStartAt),
+        backfillEndAt: isoString(input.backfillEndAt),
+      }),
+      space.id,
+    ],
+  );
+  await ctx.db.execute(
+    `INSERT INTO ${sourceSnapshotTable(ctx)}
+       (id, company_id, wiki_id, space_id, distillation_run_id, project_id, root_issue_id, source_hash, max_characters, clipped, source_refs, bundle_markdown, metadata)
+     VALUES ($1, $2, $3, $13, $4, $5, $6, $7, $8, $9, $10::jsonb, $11, $12::jsonb)`,
+    [
+      snapshotId,
+      input.companyId,
+      wikiId,
+      runId,
+      scope.projectId,
+      scope.rootIssueId,
+      bundle.sourceHash,
+      limits.maxCharacters,
+      bundle.clipped,
+      jsonParam(bundle.sourceRefs),
+      bundle.markdown,
+      jsonParam({
+        spaceSlug: space.slug,
+        sourceScope: scope.sourceScope,
+        estimatedCostCents,
+        backfillStartAt: isoString(input.backfillStartAt),
+        backfillEndAt: isoString(input.backfillEndAt),
+      }),
+      space.id,
+    ],
+  );
+
+  return { status: "source_ready" as const, wikiId, spaceSlug: space.slug, cursorId, runId, snapshotId, bundle, estimatedCostCents };
+}
+
+export async function recordPaperclipDistillationOutcome(ctx: PluginContext, input: PaperclipDistillationOutcomeInput) {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await requirePaperclipIngestionPolicy(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug }, "execute", { requireEnabledProfile: true });
+  const warnings = input.warning ? [input.warning] : [];
+  await ctx.db.execute(
+    `UPDATE ${distillationRunTable(ctx)}
+        SET status = $4,
+            warnings = CASE WHEN $5::jsonb = '[]'::jsonb THEN warnings ELSE warnings || $5::jsonb END,
+            cost_cents = CASE WHEN $6::integer IS NULL THEN cost_cents ELSE $6::integer END,
+            retry_count = CASE WHEN $7::integer IS NULL THEN retry_count ELSE $7::integer END,
+            updated_at = now()
+      WHERE company_id = $1
+        AND wiki_id = $2
+        AND space_id = $8
+        AND id = $3`,
+    [
+      input.companyId,
+      wikiId,
+      input.runId,
+      input.status,
+      jsonArrayParam(warnings),
+      input.costCents ?? null,
+      input.retryCount ?? null,
+      space.id,
+    ],
+  );
+
+  if (input.status === "succeeded" && input.cursorId && input.sourceHash && input.sourceWindowEnd) {
+    await ctx.db.execute(
+      `UPDATE ${distillationCursorTable(ctx)}
+          SET last_processed_at = $4::timestamptz,
+              last_successful_run_id = $3,
+              last_source_hash = $5,
+              pending_event_count = 0,
+              updated_at = now()
+        WHERE company_id = $1
+          AND wiki_id = $2
+          AND space_id = $7
+          AND id = $6`,
+      [input.companyId, wikiId, input.runId, input.sourceWindowEnd, input.sourceHash, input.cursorId, space.id],
+    );
+  }
+
+  return {
+    status: input.status,
+    cursorAdvanced: input.status === "succeeded" && Boolean(input.cursorId && input.sourceHash && input.sourceWindowEnd),
+  };
+}
+
+export async function createPaperclipDistillationWorkItem(ctx: PluginContext, input: PaperclipDistillationWorkItemInput) {
+  const wikiId = normalizeWikiId(input.wikiId);
+  assertPaperclipSourceScopePayload(input);
+  const space = await requirePaperclipIngestionPolicy(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug }, "queue", { requireEnabledProfile: true });
+  const itemId = randomUUID();
+  const scope = paperclipCursorScopeMetadata(input);
+  if (input.kind === "backfill" && !scope.projectId && !scope.rootIssueId) {
+    throw new Error("Backfill work items must target a projectId or rootIssueId; whole-company backfill is not allowed.");
+  }
+  await ctx.db.execute(
+    `INSERT INTO ${distillationWorkItemTable(ctx)} AS paperclip_distillation_work_items
+       (id, company_id, wiki_id, space_id, work_item_kind, status, priority, project_id, root_issue_id, requested_by_issue_id, idempotency_key, metadata)
+     VALUES ($1, $2, $3, $11, $4, 'pending', $5, $6, $7, $8, $9, $10::jsonb)
+     ON CONFLICT (company_id, wiki_id, space_id, idempotency_key)
+     DO UPDATE SET priority = EXCLUDED.priority,
+                   metadata = paperclip_distillation_work_items.metadata || EXCLUDED.metadata,
+                   updated_at = now()`,
+    [
+      itemId,
+      input.companyId,
+      wikiId,
+      input.kind,
+      input.priority ?? "medium",
+      scope.projectId,
+      scope.rootIssueId,
+      input.requestedByIssueId ?? null,
+      input.idempotencyKey ?? null,
+      jsonParam({
+        spaceSlug: space.slug,
+        sourceScope: scope.sourceScope,
+        ...(input.metadata ?? {}),
+      }),
+      space.id,
+    ],
+  );
+  return { status: "pending", workItemId: itemId, wikiId, spaceSlug: space.slug, kind: input.kind, sourceScope: scope.sourceScope };
+}
+
+function sourceRefLabel(ref: PaperclipSourceRef): string {
+  const issue = ref.issueIdentifier ? issueReference(ref.issueIdentifier) : (ref.title ?? "Paperclip source");
+  if (ref.kind === "document") return `${issue} document:${ref.documentKey ?? "unknown"}`;
+  if (ref.kind === "comment") return `${issue} comment`;
+  return issue;
+}
+
+function sourceRefMarkdown(ref: PaperclipSourceRef): string {
+  const metadata = [
+    ref.redactionStatus ? `redaction=${ref.redactionStatus}` : null,
+    ref.redactionReasons?.length ? `redaction_reasons=${ref.redactionReasons.join("|")}` : null,
+  ].filter((part): part is string => Boolean(part)).join(", ");
+  return `- ${sourceRefLabel(ref)}${metadata ? ` (${metadata})` : ""}`;
+}
+
+function issueSourceRef(issue: Issue): PaperclipSourceRef {
+  return {
+    kind: "issue",
+    issueId: issue.id,
+    issueIdentifier: issue.identifier ?? null,
+    projectId: issue.projectId ?? null,
+    title: issue.title,
+    updatedAt: isoString(issue.updatedAt) ?? undefined,
+  };
+}
+
+function projectPageSlug(input: { project: Project | null; rootIssue: Issue | null }): string {
+  return slugify(input.project?.name ?? input.rootIssue?.title ?? "paperclip-project");
+}
+
+function issueDescription(issue: Issue): string {
+  return issue.description?.trim() ?? "";
+}
+
+function issueReference(identifier: string): string {
+  const prefix = identifier.match(/^([A-Z]+)-\d+$/)?.[1];
+  return prefix ? `[${identifier}](/${prefix}/issues/${identifier})` : identifier;
+}
+
+function issueReferenceFor(issue: Issue): string {
+  return issue.identifier ? issueReference(issue.identifier) : "source issue";
+}
+
+function issueConcept(issue: Issue): string {
+  const title = issue.title
+    .replace(/^\s*(implement|add|update|fix|ship|write|create|publish|review|validate|investigate|design|refactor|support|make)\s+/i, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  const words = title.split(" ").filter(Boolean).slice(0, 5).join(" ");
+  return words || issue.title;
+}
+
+function issueNarrative(issue: Issue, maxLength = 260): string {
+  const details = issueDescription(issue);
+  return excerpt(details || issue.title, maxLength);
+}
+
+function conceptBullet(issue: Issue): string {
+  return `- **${issueConcept(issue)}.** ${issueNarrative(issue)} (${issueReferenceFor(issue)})`;
+}
+
+function excerpt(value: string, maxLength = 240): string {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (normalized.length <= maxLength) return normalized;
+  return `${normalized.slice(0, maxLength - 1).trimEnd()}...`;
+}
+
+function hasDecisionSignal(value: string): boolean {
+  return /\b(accepted|approved|rejected|reversed|decided|decision|plan|proposal|approach|architecture|tradeoff)\b/i.test(value);
+}
+
+function hasRiskSignal(value: string): boolean {
+  return /\b(blocked|blocker|risk|warning|stale|conflict|failed|failure|regression)\b/i.test(value);
+}
+
+function hasDurableSignal(bundle: PaperclipSourceBundle, issues: Issue[]): boolean {
+  if (bundle.sourceRefs.some((ref) => ref.kind === "document" || ref.kind === "comment")) return true;
+  if (issues.some((issue) => issue.status !== "todo" || issueDescription(issue).length > 0)) return true;
+  return /\b(decision|approved|implemented|completed|blocked|risk|artifact|plan|handoff|merged|fixed)\b/i.test(bundle.markdown);
+}
+
+function standupPageContents(input: {
+  project: Project | null;
+  rootIssue: Issue | null;
+  issues: Issue[];
+  bundle: PaperclipSourceBundle;
+  pagePath: string;
+  durablePagePath: string;
+}): string {
+  const currentAsOf = input.bundle.sourceWindowEnd ?? new Date().toISOString();
+  const title = input.project?.name ?? input.rootIssue?.title ?? "Paperclip Project";
+  const activeIssues = input.issues.filter((issue) => !["done", "cancelled"].includes(issue.status));
+  const recentlyChanged = [...input.issues]
+    .sort((a, b) => (isoString(b.updatedAt) ?? "").localeCompare(isoString(a.updatedAt) ?? ""))
+    .slice(0, 6);
+  const completedIssues = recentlyChanged.filter((issue) => issue.status === "done");
+  const advancedIssues = recentlyChanged.filter((issue) => issue.status !== "done" && issue.status !== "cancelled");
+  const decisionIssues = input.issues.filter((issue) => hasDecisionSignal(`${issue.title}\n${issueDescription(issue)}`)).slice(0, 6);
+  const riskIssues = input.issues.filter((issue) => issue.status === "blocked" || hasRiskSignal(`${issue.title}\n${issueDescription(issue)}`)).slice(0, 6);
+  const nextActionIssues = activeIssues.slice(0, 6);
+  const lead = activeIssues[0] ?? recentlyChanged[0] ?? null;
+
+  return [
+    "---",
+    `title: ${JSON.stringify(`${title} Standup`)}`,
+    "type: project-standup",
+    `project: ${JSON.stringify(projectPageSlug(input))}`,
+    `current_as_of: ${JSON.stringify(currentAsOf)}`,
+    "sources: []",
+    "---",
+    "",
+    `# ${title} Standup`,
+    "",
+    "## Executive Readout",
+    "",
+    lead
+      ? `The current center of gravity is **${issueConcept(lead)}** (${issueReferenceFor(lead)}). ${input.bundle.clipped ? "The source window was clipped, so treat this as a bounded readout rather than the full live state." : "This is a high-level readout of the meaningful Paperclip work in the current source window."}`
+      : "No meaningful project movement was present in this source window.",
+    "",
+    "## What Changed",
+    "",
+    ...(completedIssues.length
+      ? completedIssues.map(conceptBullet)
+      : advancedIssues.length
+        ? advancedIssues.map(conceptBullet)
+        : ["- No material completed or advanced work was identified in this source window."]),
+    "",
+    "## Decisions",
+    "",
+    ...(decisionIssues.length
+      ? decisionIssues.map(conceptBullet)
+      : ["- No decision changed the project direction in this source window."]),
+    "",
+    "## Blockers / Risks",
+    "",
+    ...(riskIssues.length
+      ? riskIssues.map(conceptBullet)
+      : ["- No active blocker or material risk surfaced in this source window."]),
+    "",
+    "## Next Actions",
+    "",
+    ...(nextActionIssues.length
+      ? nextActionIssues.map((issue) => `- **${issueConcept(issue)}.** Continue the work represented by ${issueReferenceFor(issue)}; focus on the next concrete deliverable rather than routine status churn.`)
+      : ["- No next action inferred from this source window."]),
+    "",
+    "## Links",
+    "",
+    `- Durable project overview: [[${input.durablePagePath}]]`,
+    ...input.bundle.sourceRefs.slice(0, 12).map(sourceRefMarkdown),
+    "",
+  ].filter((line): line is string => line !== null).join("\n");
+}
+
+function projectPageContents(input: {
+  project: Project | null;
+  rootIssue: Issue | null;
+  issues: Issue[];
+  bundle: PaperclipSourceBundle;
+  pagePath: string;
+}): string {
+  const currentAsOf = input.bundle.sourceWindowEnd ?? new Date().toISOString();
+  const title = input.project?.name ?? input.rootIssue?.title ?? "Paperclip Project";
+  const description = input.project?.description?.trim() || input.rootIssue?.description?.trim() || "";
+  const activeIssues = input.issues.filter((issue) => !["done", "cancelled"].includes(issue.status));
+  const recentIssues = [...input.issues]
+    .sort((a, b) => (isoString(b.updatedAt) ?? "").localeCompare(isoString(a.updatedAt) ?? ""))
+    .slice(0, 8);
+  const decisionIssues = input.issues.filter((issue) => hasDecisionSignal(`${issue.title}\n${issueDescription(issue)}`)).slice(0, 8);
+  const riskIssues = input.issues.filter((issue) => issue.status === "blocked" || hasRiskSignal(`${issue.title}\n${issueDescription(issue)}`)).slice(0, 8);
+
+  return [
+    "---",
+    `title: ${JSON.stringify(title)}`,
+    "type: project",
+    `current_as_of: ${JSON.stringify(currentAsOf)}`,
+    "sources: []",
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    "## Overview",
+    "",
+    description ? excerpt(description, 700) : `This page synthesizes Paperclip issue history into a stable project brief for ${title}.`,
+    "",
+    "## Current Direction",
+    "",
+    activeIssues.length
+      ? `Work is currently organized around ${activeIssues.slice(0, 3).map((issue) => `**${issueConcept(issue)}** (${issueReferenceFor(issue)})`).join(", ")}. The useful project view is the concept being advanced, not the raw issue queue.`
+      : "The current source window does not show active project work.",
+    input.bundle.clipped ? "\nThe source window was clipped, so verify Paperclip before treating this as complete state." : null,
+    "",
+    "## Workstreams",
+    "",
+    ...(recentIssues.length
+      ? recentIssues.map(conceptBullet)
+      : ["- No meaningful workstream signal was identified in this source window."]),
+    "",
+    "## Decisions",
+    "",
+    ...(decisionIssues.length
+      ? decisionIssues.map(conceptBullet)
+      : ["- No durable decision signal was identified in this source window."]),
+    "",
+    "## Open Risks / Blockers",
+    "",
+    ...(riskIssues.length
+      ? riskIssues.map(conceptBullet)
+      : ["- No open risks or blockers identified in this source window."]),
+    "",
+    "## References",
+    "",
+    `- Current standup: [[${input.pagePath.replace(/\/index\.md$/, "/standup.md")}]]`,
+    ...input.bundle.sourceRefs.slice(0, 12).map(sourceRefMarkdown),
+    "",
+  ].filter((line): line is string => line !== null).join("\n");
+}
+
+function decisionsPageContents(input: { project: Project | null; rootIssue: Issue | null; issues: Issue[]; bundle: PaperclipSourceBundle }): string {
+  const title = input.project?.name ?? input.rootIssue?.title ?? "Paperclip Project";
+  const decisionIssues = input.issues.filter((issue) => hasDecisionSignal(`${issue.title}\n${issueDescription(issue)}`));
+  return [
+    `# ${title} Decisions`,
+    "",
+    "Durable project decisions grouped by concept. Use this as an editorial memory of why the project changed direction, not as an issue log.",
+    "",
+    ...(decisionIssues.length
+      ? decisionIssues.map((issue) => [
+        `## ${issueConcept(issue)}`,
+        "",
+        issueDescription(issue) ? excerpt(issueDescription(issue), 900) : "_No decision details beyond the issue title._",
+        "",
+        `Source: ${issueReferenceFor(issue)}`,
+        "",
+      ].join("\n"))
+      : ["No durable decisions identified in this source window.", ""]),
+    "## References",
+    "",
+    ...input.bundle.sourceRefs.slice(0, 40).map(sourceRefMarkdown),
+    "",
+  ].join("\n");
+}
+
+function historyPageContents(input: { project: Project | null; rootIssue: Issue | null; issues: Issue[]; bundle: PaperclipSourceBundle }): string {
+  const title = input.project?.name ?? input.rootIssue?.title ?? "Paperclip Project";
+  const timeline = [...input.issues]
+    .sort((a, b) => (isoString(a.updatedAt) ?? "").localeCompare(isoString(b.updatedAt) ?? ""))
+    .slice(-30);
+  return [
+    `# ${title} History`,
+    "",
+    "Narrative history of meaningful project movement. Group by what changed in the work, not by dates or metadata.",
+    "",
+    "## Meaningful Project Movement",
+    "",
+    ...(timeline.length
+      ? timeline.map(conceptBullet)
+      : ["- No source issues in this window."]),
+    "",
+    "## References",
+    "",
+    ...input.bundle.sourceRefs.slice(0, 40).map(sourceRefMarkdown),
+    "",
+  ].join("\n");
+}
+
+function updateProjectIndexContents(current: string | null, input: { pagePath: string; standupPath: string; title: string }): string {
+  const base = current?.trimEnd() || "# Index\n\n## Sources\n\n_(none yet)_\n\n## Projects\n\n_(none yet)_\n\n## Entities\n\n_(none yet)_\n\n## Concepts\n\n_(none yet)_\n\n## Synthesis\n\n_(none yet)_";
+  const entry = `- [[${input.pagePath}]] — ${input.title} project overview. Current executive standup: [[${input.standupPath}]].`;
+  const projectsMatch = base.match(/(^## Projects\n)([\s\S]*?)(?=^## |\s*$)/m);
+  if (!projectsMatch || projectsMatch.index == null) {
+    return `${base}\n\n## Projects\n\n${entry}\n`;
+  }
+  const start = projectsMatch.index + projectsMatch[1].length;
+  const end = start + projectsMatch[2].length;
+  const existingLines = projectsMatch[2]
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim() && line.trim() !== "_(none yet)_" && !line.includes(input.pagePath) && !line.includes(input.standupPath));
+  const nextLines = [...existingLines, entry].sort((a, b) => a.localeCompare(b));
+  return `${base.slice(0, start)}${nextLines.join("\n")}\n\n${base.slice(end).replace(/^\n+/, "")}`.trimEnd() + "\n";
+}
+
+function appendProjectLogContents(current: string | null, input: { standupPath: string; pagePath: string; runId: string; sourceHash: string; status: string; warnings: string[] }): string {
+  const base = current?.trimEnd() || "# Log\n\nAppend-only chronological record of wiki operations.";
+  const warningLines = input.warnings.length
+    ? input.warnings.map((warning) => `- warning: ${warning}`)
+    : ["- warnings: none"];
+  const entry = [
+    `## [${new Date().toISOString().slice(0, 10)}] paperclip-distill | ${input.status}`,
+    `- standup: \`${input.standupPath}\``,
+    `- page: \`${input.pagePath}\``,
+    `- run: \`${input.runId}\``,
+    `- source hash: \`${input.sourceHash}\``,
+    ...warningLines,
+  ].join("\n");
+  return `${base}\n\n${entry}\n`;
+}
+
+function patchForPage(input: {
+  path: string;
+  operationType: PaperclipDistillationPatchOperation;
+  currentHash: string | null;
+  contents: string;
+  bundle: PaperclipSourceBundle;
+  confidence: "high" | "medium" | "low";
+  warnings: string[];
+  humanReviewRequired: boolean;
+}): PaperclipDistillationPatch {
+  return {
+    pagePath: input.path,
+    operationType: input.operationType,
+    currentHash: input.currentHash,
+    proposedHash: contentHash(input.contents),
+    proposedContents: input.contents,
+    sourceHash: input.bundle.sourceHash,
+    sourceRefs: input.bundle.sourceRefs,
+    cursorWindow: {
+      start: input.bundle.sourceWindowStart,
+      end: input.bundle.sourceWindowEnd,
+    },
+    confidence: input.confidence,
+    warnings: input.warnings,
+    humanReviewRequired: input.humanReviewRequired,
+  };
+}
+
+async function readPageBinding(ctx: PluginContext, input: { companyId: string; wikiId: string; spaceId: string; pagePath: string }) {
+  const rows = await ctx.db.query<{ last_applied_source_hash: string | null }>(
+    `SELECT last_applied_source_hash
+       FROM ${pageBindingTable(ctx)}
+      WHERE company_id = $1
+        AND wiki_id = $2
+        AND space_id = $3
+        AND page_path = $4
+      LIMIT 1`,
+    [input.companyId, input.wikiId, input.spaceId, input.pagePath],
+  );
+  return rows[0] ?? null;
+}
+
+async function upsertPageBinding(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId: string;
+  spaceId: string;
+  spaceSlug: string;
+  projectId: string | null;
+  rootIssueId: string | null;
+  pagePath: string;
+  sourceHash: string;
+  runId: string;
+  metadata?: Record<string, unknown>;
+}) {
+  await ctx.db.execute(
+    `INSERT INTO ${pageBindingTable(ctx)} AS paperclip_page_bindings
+       (id, company_id, wiki_id, space_id, project_id, root_issue_id, page_path, last_applied_source_hash, last_distillation_run_id, metadata)
+     VALUES ($1, $2, $3, $10, $4, $5, $6, $7, $8, $9::jsonb)
+     ON CONFLICT (company_id, wiki_id, space_id, page_path)
+     DO UPDATE SET last_applied_source_hash = EXCLUDED.last_applied_source_hash,
+                   last_distillation_run_id = EXCLUDED.last_distillation_run_id,
+                   metadata = paperclip_page_bindings.metadata || EXCLUDED.metadata,
+                   updated_at = now()`,
+    [
+      randomUUID(),
+      input.companyId,
+      input.wikiId,
+      input.projectId,
+      input.rootIssueId,
+      input.pagePath,
+      input.sourceHash,
+      input.runId,
+      jsonParam({ spaceSlug: input.spaceSlug, ...(input.metadata ?? {}) }),
+      input.spaceId,
+    ],
+  );
+}
+
+async function autoApplyEnabled(ctx: PluginContext, requested: boolean | undefined): Promise<boolean> {
+  if (getDistillationAutoApplyRestriction().autoApplyRestriction) {
+    return false;
+  }
+  const config = await ctx.config.get();
+  const configured = (config as { autoApplyIngestPatches?: unknown }).autoApplyIngestPatches !== false;
+  return configured && requested !== false;
+}
+
+export function getDistillationAutoApplyRestriction(): DistillationAutoApplyRestriction {
+  const rawMode = process.env.PAPERCLIP_DEPLOYMENT_MODE;
+  const rawExposure = process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE;
+  const deploymentMode =
+    rawMode === "local_trusted" || rawMode === "authenticated" ? rawMode : null;
+  const deploymentExposure =
+    rawExposure === "private" || rawExposure === "public" ? rawExposure : null;
+  const blocked = deploymentMode === "authenticated" && deploymentExposure === "public";
+  return {
+    autoApplyAllowed: !blocked,
+    autoApplyRestriction: blocked ? PUBLIC_DISTILLATION_AUTO_APPLY_RESTRICTION : null,
+    deploymentMode,
+    deploymentExposure,
+  };
+}
+
+export async function distillPaperclipProjectPage(ctx: PluginContext, input: PaperclipProjectPageDistillationInput) {
+  if (!input.projectId && !input.rootIssueId) {
+    throw new Error("projectId or rootIssueId is required");
+  }
+  const wikiId = normalizeWikiId(input.wikiId);
+  assertPaperclipSourceScopePayload(input);
+  const space = await requirePaperclipIngestionPolicy(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug }, "execute", { requireEnabledProfile: true });
+  const scope = paperclipCursorScopeMetadata(input);
+  const issues = await listPaperclipBundleIssues(ctx, input);
+  const project = scope.projectId ? await ctx.projects.get(scope.projectId, input.companyId) : null;
+  const rootIssue = scope.rootIssueId ? await ctx.issues.get(scope.rootIssueId, input.companyId) : null;
+  const slug = projectPageSlug({ project, rootIssue });
+  const projectDir = `wiki/projects/${slug}`;
+  const standupPath = assertPagePath(`${projectDir}/standup.md`);
+  const pagePath = assertPagePath(`${projectDir}/index.md`);
+  const run = await createPaperclipDistillationRun(ctx, input);
+  const bundle = run.bundle;
+  const current = await readCurrentWithHash(ctx, input.companyId, pagePath, space);
+  assertExpectedHash(input.expectedProjectPageHash, current.hash, pagePath);
+
+  if (!hasDurableSignal(bundle, issues)) {
+    await recordPaperclipDistillationOutcome(ctx, {
+      companyId: input.companyId,
+      wikiId,
+      spaceSlug: space.slug,
+      runId: run.runId,
+      cursorId: run.cursorId,
+      status: "succeeded",
+      sourceHash: bundle.sourceHash,
+      sourceWindowEnd: bundle.sourceWindowEnd,
+      warning: "Skipped low-signal Paperclip source window.",
+    });
+    return {
+      status: "skipped",
+      reason: "low_signal",
+      wikiId,
+      runId: run.runId,
+      cursorId: run.cursorId,
+      sourceHash: bundle.sourceHash,
+      warnings: ["Skipped low-signal Paperclip source window."],
+      patches: [] as PaperclipDistillationPatch[],
+    };
+  }
+
+  const existingBinding = await readPageBinding(ctx, { companyId: input.companyId, wikiId, spaceId: space.id, pagePath });
+  if (existingBinding?.last_applied_source_hash === bundle.sourceHash) {
+    await recordPaperclipDistillationOutcome(ctx, {
+      companyId: input.companyId,
+      wikiId,
+      spaceSlug: space.slug,
+      runId: run.runId,
+      cursorId: run.cursorId,
+      status: "succeeded",
+      sourceHash: bundle.sourceHash,
+      sourceWindowEnd: bundle.sourceWindowEnd,
+      warning: "Skipped unchanged Paperclip source hash.",
+    });
+    return {
+      status: "skipped",
+      reason: "unchanged_source",
+      wikiId,
+      runId: run.runId,
+      cursorId: run.cursorId,
+      sourceHash: bundle.sourceHash,
+      warnings: ["Skipped unchanged Paperclip source hash."],
+      patches: [] as PaperclipDistillationPatch[],
+    };
+  }
+
+  const warnings = [...bundle.warnings];
+  const confidence: "high" | "medium" | "low" = bundle.clipped ? "medium" : "high";
+  const reviewRequired = bundle.clipped || warnings.length > 0;
+  const title = project?.name ?? rootIssue?.title ?? "Paperclip Project";
+  const standupCurrent = await readCurrentWithHash(ctx, input.companyId, standupPath, space);
+  const standupContents = standupPageContents({ project, rootIssue, issues, bundle, pagePath: standupPath, durablePagePath: pagePath });
+  const projectContents = projectPageContents({ project, rootIssue, issues, bundle, pagePath });
+  const indexCurrent = await readCurrentWithHash(ctx, input.companyId, "wiki/index.md", space);
+  const logCurrent = await readCurrentWithHash(ctx, input.companyId, "wiki/log.md", space);
+  const indexContents = updateProjectIndexContents(indexCurrent.contents, {
+    pagePath,
+    standupPath,
+    title,
+  });
+  const logContents = appendProjectLogContents(logCurrent.contents, {
+    standupPath,
+    pagePath,
+    runId: run.runId,
+    sourceHash: bundle.sourceHash,
+    status: "proposed",
+    warnings,
+  });
+  const patches: PaperclipDistillationPatch[] = [
+    patchForPage({ path: standupPath, operationType: "standup_update", currentHash: standupCurrent.hash, contents: standupContents, bundle, confidence, warnings, humanReviewRequired: reviewRequired }),
+    patchForPage({ path: pagePath, operationType: "project_page_distill", currentHash: current.hash, contents: projectContents, bundle, confidence, warnings, humanReviewRequired: reviewRequired }),
+    patchForPage({ path: "wiki/index.md", operationType: "index_refresh", currentHash: indexCurrent.hash, contents: indexContents, bundle, confidence: "high", warnings: [], humanReviewRequired: false }),
+    patchForPage({ path: "wiki/log.md", operationType: "log_append", currentHash: logCurrent.hash, contents: logContents, bundle, confidence: "high", warnings: [], humanReviewRequired: false }),
+  ];
+
+  if (input.includeSupportingPages !== false) {
+    const hasDecisions = issues.some((issue) => hasDecisionSignal(`${issue.title}\n${issueDescription(issue)}`));
+    if (hasDecisions) {
+      const decisionsPath = assertPagePath(`${projectDir}/decisions.md`);
+      const decisionsCurrent = await readCurrentWithHash(ctx, input.companyId, decisionsPath, space);
+      patches.push(patchForPage({
+        path: decisionsPath,
+        operationType: "decision_distill",
+        currentHash: decisionsCurrent.hash,
+        contents: decisionsPageContents({ project, rootIssue, issues, bundle }),
+        bundle,
+        confidence,
+        warnings,
+        humanReviewRequired: reviewRequired,
+      }));
+    }
+    const historyPath = assertPagePath(`${projectDir}/history.md`);
+    const historyCurrent = await readCurrentWithHash(ctx, input.companyId, historyPath, space);
+    patches.push(patchForPage({
+      path: historyPath,
+      operationType: "history_distill",
+      currentHash: historyCurrent.hash,
+      contents: historyPageContents({ project, rootIssue, issues, bundle }),
+      bundle,
+      confidence,
+      warnings,
+      humanReviewRequired: reviewRequired,
+    }));
+  }
+
+  const autoApplyRestriction = getDistillationAutoApplyRestriction();
+  const canAutoApply = await autoApplyEnabled(ctx, input.autoApply);
+  if (!canAutoApply || reviewRequired) {
+    const autoApplyWarning =
+      autoApplyRestriction.autoApplyRestriction
+      ?? "Auto-apply policy disabled; proposed patches require review.";
+    await recordPaperclipDistillationOutcome(ctx, {
+      companyId: input.companyId,
+      wikiId,
+      spaceSlug: space.slug,
+      runId: run.runId,
+      cursorId: run.cursorId,
+      status: "review_required",
+      sourceHash: bundle.sourceHash,
+      sourceWindowEnd: bundle.sourceWindowEnd,
+      warning: canAutoApply ? "Human review required by patch warnings." : autoApplyWarning,
+    });
+    return {
+      status: "review_required",
+      wikiId,
+      runId: run.runId,
+      cursorId: run.cursorId,
+      sourceHash: bundle.sourceHash,
+      patches,
+      appliedPages: [] as string[],
+      warnings: canAutoApply ? warnings : [autoApplyWarning, ...warnings],
+    };
+  }
+
+  const appliedPages: string[] = [];
+  for (const patch of patches) {
+    await writeWikiPage(ctx, {
+      companyId: input.companyId,
+      wikiId,
+      spaceSlug: space.slug,
+      path: patch.pagePath,
+      contents: patch.proposedContents,
+      expectedHash: patch.currentHash,
+      summary: `Paperclip distillation ${patch.operationType} from ${bundle.sourceHash}`,
+      sourceRefs: patch.sourceRefs,
+    });
+    await upsertPageBinding(ctx, {
+      companyId: input.companyId,
+      wikiId,
+      spaceId: space.id,
+      spaceSlug: space.slug,
+      projectId: scope.projectId,
+      rootIssueId: scope.rootIssueId,
+      pagePath: patch.pagePath,
+      sourceHash: bundle.sourceHash,
+      runId: run.runId,
+      metadata: { operationType: patch.operationType },
+    });
+    appliedPages.push(patch.pagePath);
+  }
+  await recordPaperclipDistillationOutcome(ctx, {
+    companyId: input.companyId,
+    wikiId,
+    spaceSlug: space.slug,
+    runId: run.runId,
+    cursorId: run.cursorId,
+    status: "succeeded",
+    sourceHash: bundle.sourceHash,
+    sourceWindowEnd: bundle.sourceWindowEnd,
+  });
+
+  return {
+    status: "applied",
+    wikiId,
+    runId: run.runId,
+    cursorId: run.cursorId,
+    sourceHash: bundle.sourceHash,
+    patches,
+    appliedPages,
+    warnings,
+  };
+}
+
+function truncateEventSource(contents: string, maxCharacters: number): string {
+  if (contents.length <= maxCharacters) return contents;
+  return `${contents.slice(0, maxCharacters)}\n\n[Truncated by LLM Wiki event ingestion policy at ${maxCharacters} characters.]\n`;
+}
+
+function eventPayload(event: PluginEvent): Record<string, unknown> {
+  return event.payload && typeof event.payload === "object" && !Array.isArray(event.payload)
+    ? event.payload as Record<string, unknown>
+    : {};
+}
+
+function sourceTitleForIssue(issue: Issue): string {
+  return issue.identifier ? `${issue.identifier} ${issue.title}` : issue.title;
+}
+
+function rawPathForPaperclipEvent(input: {
+  sourceKind: WikiEventIngestionSource;
+  issue: Issue;
+  label: string;
+  contents: string;
+  event: PluginEvent;
+}): string {
+  const identifier = input.issue.identifier ?? input.issue.id.slice(0, 8);
+  const eventDate = input.event.occurredAt.slice(0, 10);
+  return assertRawPath(`raw/paperclip/${input.sourceKind}/${eventDate}-${slugify(identifier)}-${slugify(input.label)}-${contentHash(input.contents).slice(0, 8)}.md`);
+}
+
+function formatIssueEventSource(issue: Issue, event: PluginEvent, maxCharacters: number): string {
+  return truncateEventSource([
+    `# Paperclip issue: ${sourceTitleForIssue(issue)}`,
+    "",
+    "## Provenance",
+    "",
+    `- Company ID: ${issue.companyId}`,
+    `- Issue ID: ${issue.id}`,
+    issue.identifier ? `- Issue identifier: ${issue.identifier}` : null,
+    `- Event type: ${event.eventType}`,
+    `- Event ID: ${event.eventId}`,
+    `- Event occurred at: ${event.occurredAt}`,
+    `- Status: ${issue.status}`,
+    `- Priority: ${issue.priority}`,
+    "",
+    "## Issue",
+    "",
+    issue.description?.trim() ? issue.description.trim() : "_No issue description._",
+  ].filter((line): line is string => line !== null).join("\n"), maxCharacters);
+}
+
+function formatCommentEventSource(issue: Issue, comment: IssueComment, event: PluginEvent, maxCharacters: number): string {
+  return truncateEventSource([
+    `# Paperclip comment on ${sourceTitleForIssue(issue)}`,
+    "",
+    "## Provenance",
+    "",
+    `- Company ID: ${issue.companyId}`,
+    `- Issue ID: ${issue.id}`,
+    issue.identifier ? `- Issue identifier: ${issue.identifier}` : null,
+    `- Comment ID: ${comment.id}`,
+    `- Event type: ${event.eventType}`,
+    `- Event ID: ${event.eventId}`,
+    `- Event occurred at: ${event.occurredAt}`,
+    "",
+    "## Comment",
+    "",
+    comment.body,
+  ].filter((line): line is string => line !== null).join("\n"), maxCharacters);
+}
+
+function formatDocumentEventSource(issue: Issue, document: IssueDocument, event: PluginEvent, maxCharacters: number): string {
+  return truncateEventSource([
+    `# Paperclip document: ${document.title ?? document.key}`,
+    "",
+    "## Provenance",
+    "",
+    `- Company ID: ${issue.companyId}`,
+    `- Issue ID: ${issue.id}`,
+    issue.identifier ? `- Issue identifier: ${issue.identifier}` : null,
+    `- Document ID: ${document.id}`,
+    `- Document key: ${document.key}`,
+    `- Event type: ${event.eventType}`,
+    `- Event ID: ${event.eventId}`,
+    `- Event occurred at: ${event.occurredAt}`,
+    `- Format: ${document.format}`,
+    `- Revision: ${document.latestRevisionNumber}`,
+    "",
+    "## Document",
+    "",
+    document.body,
+  ].filter((line): line is string => line !== null).join("\n"), maxCharacters);
+}
+
+async function recordPaperclipCursorObservation(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId: string;
+  space: WikiSpace;
+  sourceKind: WikiEventIngestionSource;
+  sourceId: string;
+  issue: Issue;
+  event: PluginEvent;
+}): Promise<Extract<PaperclipEventIngestResult, { status: "recorded" }>> {
+  const cursorId = await upsertPaperclipDistillationCursor(ctx, {
+    companyId: input.companyId,
+    wikiId: input.wikiId,
+    spaceId: input.space.id,
+    projectId: input.issue.projectId ?? null,
+    rootIssueId: null,
+    observedAt: input.event.occurredAt,
+    metadata: {
+      lastEventId: input.event.eventId,
+      lastEventType: input.event.eventType,
+      lastSourceKind: input.sourceKind,
+      lastSourceId: input.sourceId,
+      lastIssueId: input.issue.id,
+      lastIssueIdentifier: input.issue.identifier ?? null,
+    },
+  });
+  await ctx.state.set(eventIngestionDedupKey(input.companyId, input.wikiId, input.space.id, input.sourceKind, input.sourceId), {
+    eventId: input.event.eventId,
+    cursorId,
+    issueId: input.issue.id,
+    spaceSlug: input.space.slug,
+    observedAt: new Date().toISOString(),
+  });
+  return {
+    status: "recorded",
+    sourceKind: input.sourceKind,
+    sourceId: input.sourceId,
+    cursorId,
+    issueId: input.issue.id,
+  };
+}
+
+async function paperclipProfileIncludesIssue(ctx: PluginContext, input: {
+  companyId: string;
+  issue: Issue;
+  profile: PaperclipIngestionProfileV1;
+}): Promise<boolean> {
+  for (const scope of input.profile.sourceScopes) {
+    if (scope.kind === "company_all") return true;
+    if (scope.kind === "selected_projects" && input.issue.projectId && scope.projectIds.includes(input.issue.projectId)) {
+      return true;
+    }
+    if (scope.kind === "active_projects" && input.issue.projectId) {
+      const project = await ctx.projects.get(input.issue.projectId, input.companyId);
+      const statuses = scope.statuses ?? ["in_progress"];
+      if (project && statuses.includes(project.status as "in_progress" | "todo" | "done") && isActiveDistillationProject(project)) {
+        return true;
+      }
+    }
+    if (scope.kind === "root_issues") {
+      for (const rootIssueId of scope.issueIds) {
+        if (input.issue.id === rootIssueId) return true;
+        const subtree = await ctx.issues.getSubtree(rootIssueId, input.companyId, { includeRoot: true });
+        if (subtree.issues.some((issue) => issue.id === input.issue.id)) return true;
+      }
+    }
+  }
+  return false;
+}
+
+async function routePaperclipCursorObservation(ctx: PluginContext, input: {
+  companyId: string;
+  sourceKind: WikiEventIngestionSource;
+  sourceId: string;
+  issue: Issue;
+  event: PluginEvent;
+}): Promise<PaperclipEventIngestResult> {
+  const { spaces } = await listSpaces(ctx, { companyId: input.companyId, wikiId: DEFAULT_WIKI_ID });
+  const recorded: Array<Extract<PaperclipEventIngestResult, { status: "recorded" }>> = [];
+  let eligibleProfileCount = 0;
+  for (const space of spaces) {
+    const profile = await profileForSpace(ctx, input.companyId, space);
+    if (!profile.enabled) continue;
+    const policy = evaluatePaperclipProfilePolicy({ space, profile, purpose: "event_routing", requireEnabledProfile: true });
+    if (!policy.allowed) continue;
+    if (!profile.sourceKinds[input.sourceKind]) continue;
+    if (!(await paperclipProfileIncludesIssue(ctx, { companyId: input.companyId, issue: input.issue, profile }))) continue;
+    eligibleProfileCount += 1;
+    if (eligibleProfileCount > MAX_PAPERCLIP_DISTILLATION_FAN_OUT) {
+      throw new Error(`Paperclip ingestion fan-out exceeds the hard cap of ${MAX_PAPERCLIP_DISTILLATION_FAN_OUT} enabled profiles.`);
+    }
+    if (await ctx.state.get(eventIngestionDedupKey(input.companyId, space.wikiId, space.id, input.sourceKind, input.sourceId))) {
+      continue;
+    }
+    recorded.push(await recordPaperclipCursorObservation(ctx, {
+      ...input,
+      wikiId: space.wikiId,
+      space,
+    }));
+  }
+  return recorded[0] ?? { status: "skipped", reason: "source_disabled" };
+}
+
+export async function handlePaperclipEventIngestion(ctx: PluginContext, event: PluginEvent): Promise<PaperclipEventIngestResult> {
+  const companyId = event.companyId;
+
+  const issueId = stringField(event.entityId);
+  if (!issueId) return { status: "skipped", reason: "unsupported_event" };
+  const issue = await ctx.issues.get(issueId, companyId);
+  if (!issue) return { status: "skipped", reason: "missing_issue" };
+  if (isLlmWikiOperationIssue(issue)) return { status: "skipped", reason: "plugin_operation" };
+
+  const payload = eventPayload(event);
+  if (event.eventType === "issue.created" || event.eventType === "issue.updated") {
+    const sourceId = `${event.eventType}:${issue.id}:${event.eventId}`;
+    return routePaperclipCursorObservation(ctx, {
+      companyId,
+      sourceKind: "issues",
+      sourceId,
+      issue,
+      event,
+    });
+  }
+
+  if (event.eventType === "issue.comment.created") {
+    const commentId = stringField(payload.commentId);
+    if (!commentId) return { status: "skipped", reason: "missing_comment" };
+    const sourceId = `comment:${commentId}`;
+    return routePaperclipCursorObservation(ctx, {
+      companyId,
+      sourceKind: "comments",
+      sourceId,
+      issue,
+      event,
+    });
+  }
+
+  if (event.eventType === "issue.document.created" || event.eventType === "issue.document.updated") {
+    const documentKey = stringField(payload.key) ?? stringField(payload.documentKey);
+    if (!documentKey) return { status: "skipped", reason: "missing_document" };
+    const revision = stringField(payload.revisionId) ?? stringField(payload.latestRevisionId) ?? stringField(payload.revisionNumber) ?? event.eventId;
+    const sourceId = `document:${issue.id}:${documentKey}:revision:${revision}`;
+    return routePaperclipCursorObservation(ctx, {
+      companyId,
+      sourceKind: "documents",
+      sourceId,
+      issue,
+      event,
+    });
+  }
+
+  return { status: "skipped", reason: "unsupported_event" };
+}
+
+function queryStreamChannel(operationId: string): string {
+  return `llm-wiki:query:${operationId}`;
+}
+
+function buildQueryPrompt(input: { companyId: string; wikiId: string; space: WikiSpace; question: string }): string {
+  return [
+    QUERY_PROMPT,
+    `Company ID: ${input.companyId}`,
+    `Wiki ID: ${input.wikiId}`,
+    `Space: ${input.space.displayName} (${input.space.slug})`,
+    `Space root: ${operationSpaceRoot(input.space)}`,
+    `Tool arguments: always pass wikiId \`${input.wikiId}\` and spaceSlug \`${input.space.slug}\`.`,
+    "Use the LLM Wiki plugin tools against that space only. Read wiki/index.md first with wiki_read_page, then use wiki_search, wiki_read_page, wiki_list_sources, and wiki_read_source as needed.",
+    "Cite the wiki page paths and raw source paths you used. If the wiki does not contain enough evidence, say that directly.",
+    `Question: ${input.question}`,
+  ].join("\n\n");
+}
+
+async function markOperation(ctx: PluginContext, input: {
+  companyId: string;
+  operationId: string;
+  status: string;
+  runId?: string | null;
+  warning?: string | null;
+  affectedPages?: unknown[] | null;
+  metadata?: Record<string, unknown> | null;
+}) {
+  await ctx.db.execute(
+    `UPDATE ${tableName(ctx.db.namespace, "wiki_operations")}
+        SET status = $3,
+            run_ids = CASE WHEN $4::jsonb = '[]'::jsonb THEN run_ids ELSE run_ids || $4::jsonb END,
+            warnings = CASE WHEN $5::jsonb = '[]'::jsonb THEN warnings ELSE warnings || $5::jsonb END,
+            affected_pages = CASE WHEN $6::jsonb = '[]'::jsonb THEN affected_pages ELSE $6::jsonb END,
+            metadata = metadata || $7::jsonb,
+            updated_at = now()
+      WHERE company_id = $1 AND id = $2`,
+    [
+      input.companyId,
+      input.operationId,
+      input.status,
+      jsonArrayParam(input.runId ? [input.runId] : []),
+      jsonArrayParam(input.warning ? [input.warning] : []),
+      jsonArrayParam(input.affectedPages ?? []),
+      jsonParam(input.metadata ?? {}),
+    ],
+  );
+}
+
+function isTerminalSessionEvent(event: AgentSessionEvent): boolean {
+  return event.eventType === "done" || event.eventType === "error";
+}
+
+export async function startWikiQuerySession(ctx: PluginContext, input: QuerySessionInput) {
+  const question = requireString(input.question, "question");
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const operation = await createOperationIssue(ctx, {
+    companyId: input.companyId,
+    wikiId,
+    spaceSlug: space.slug,
+    operationType: "query",
+    title: input.title ?? `Query LLM Wiki: ${question.slice(0, 72)}`,
+    prompt: question,
+  });
+  const agentId = operation.issue.assigneeAgentId;
+  const channel = queryStreamChannel(operation.operationId);
+
+  if (!agentId) {
+    const warning = "No configured Wiki Maintainer agent is available for this company.";
+    await markOperation(ctx, {
+      companyId: input.companyId,
+      operationId: operation.operationId,
+      status: "blocked",
+      warning,
+    });
+    await ctx.issues.update(operation.issue.id, { status: "blocked" }, input.companyId);
+    await ctx.issues.createComment(operation.issue.id, warning, input.companyId);
+    throw new Error(warning);
+  }
+
+  const agent = await ctx.agents.get(agentId, input.companyId);
+  if (!agent || agent.status === "paused" || agent.status === "terminated" || agent.status === "pending_approval") {
+    const warning = agent
+      ? `Wiki Maintainer agent is not invokable while status is ${agent.status}.`
+      : "Wiki Maintainer agent could not be loaded.";
+    await markOperation(ctx, {
+      companyId: input.companyId,
+      operationId: operation.operationId,
+      status: "blocked",
+      warning,
+    });
+    await ctx.issues.update(operation.issue.id, { status: "blocked" }, input.companyId);
+    await ctx.issues.createComment(operation.issue.id, warning, input.companyId);
+    throw new Error(warning);
+  }
+
+  const session = await ctx.agents.sessions.create(agentId, input.companyId, {
+    taskKey: `plugin:${PLUGIN_ID}:session:wiki:${wikiId}:query:${operation.operationId}`,
+    reason: "LLM Wiki query session",
+  });
+  await ctx.db.execute(
+    `INSERT INTO ${tableName(ctx.db.namespace, "wiki_query_sessions")}
+       (id, company_id, wiki_id, space_id, hidden_issue_id, agent_session_id, status, filed_outputs)
+     VALUES ($1, $2, $3, $6, $4, $5, 'active', '[]'::jsonb)`,
+    [operation.operationId, input.companyId, wikiId, operation.issue.id, session.sessionId, space.id],
+  );
+
+  const prompt = buildQueryPrompt({ companyId: input.companyId, wikiId, space, question });
+  ctx.streams.open(channel, input.companyId);
+  ctx.streams.emit(channel, {
+    type: "query.started",
+    operationId: operation.operationId,
+    querySessionId: operation.operationId,
+    issueId: operation.issue.id,
+    sessionId: session.sessionId,
+    question,
+  });
+
+  let answer = "";
+  const sendResult = await ctx.agents.sessions.sendMessage(session.sessionId, input.companyId, {
+    prompt,
+    reason: "LLM Wiki query",
+    onEvent: (event) => {
+      if (event.eventType === "chunk" && event.stream !== "stderr" && event.message) {
+        answer += event.message;
+      }
+      ctx.streams.emit(channel, {
+        type: "agent.event",
+        operationId: operation.operationId,
+        querySessionId: operation.operationId,
+        eventType: event.eventType,
+        stream: event.stream,
+        message: event.message,
+        payload: event.payload,
+        runId: event.runId,
+        seq: event.seq,
+      });
+      if (isTerminalSessionEvent(event)) {
+        const finalStatus = event.eventType === "done" ? "done" : "failed";
+        ctx.streams.emit(channel, {
+          type: event.eventType === "done" ? "query.done" : "query.error",
+          operationId: operation.operationId,
+          querySessionId: operation.operationId,
+          issueId: operation.issue.id,
+          sessionId: session.sessionId,
+          runId: event.runId,
+          answer,
+          message: event.message,
+        });
+        ctx.streams.close(channel);
+        void markOperation(ctx, {
+          companyId: input.companyId,
+          operationId: operation.operationId,
+          status: finalStatus,
+          runId: event.runId,
+          warning: event.eventType === "error" ? event.message : null,
+          metadata: { answerLength: answer.length },
+        });
+        void ctx.db.execute(
+          `UPDATE ${tableName(ctx.db.namespace, "wiki_query_sessions")}
+              SET status = $3,
+                  updated_at = now()
+            WHERE company_id = $1 AND id = $2`,
+          [input.companyId, operation.operationId, finalStatus === "done" ? "completed" : "failed"],
+        );
+        void ctx.issues.createComment(
+          operation.issue.id,
+          event.eventType === "done"
+            ? `Query completed.\n\n${answer.trim() || "_No answer text was streamed._"}`
+            : `Query failed: ${event.message ?? "agent session ended with an error"}`,
+          input.companyId,
+        );
+        void ctx.issues.update(
+          operation.issue.id,
+          { status: event.eventType === "done" ? "done" : "blocked", originRunId: event.runId },
+          input.companyId,
+        );
+      }
+    },
+  });
+
+  await markOperation(ctx, {
+    companyId: input.companyId,
+    operationId: operation.operationId,
+    status: "running",
+    runId: sendResult.runId,
+  });
+  await ctx.issues.update(operation.issue.id, { originRunId: sendResult.runId }, input.companyId);
+
+  return {
+    status: "running",
+    wikiId,
+    spaceSlug: space.slug,
+    operationId: operation.operationId,
+    querySessionId: operation.operationId,
+    issue: operation.issue,
+    sessionId: session.sessionId,
+    runId: sendResult.runId,
+    channel,
+  };
+}
+
+export async function fileQueryAnswerAsPage(ctx: PluginContext, input: FileQueryAnswerInput) {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const path = assertPagePath(input.path);
+  const title = stringField(input.title) ?? inferTitle(path, input.contents ?? input.answer ?? "");
+  const answer = stringField(input.answer);
+  const contents = stringField(input.contents) ?? [
+    `# ${title}`,
+    "",
+    input.question ? `> Filed from query: ${input.question}` : null,
+    "",
+    answer ?? "",
+  ].filter((line): line is string => line !== null).join("\n").trimEnd() + "\n";
+  const operation = await createOperationIssue(ctx, {
+    companyId: input.companyId,
+    wikiId,
+    spaceSlug: space.slug,
+    operationType: "file-as-page",
+    title: `File LLM Wiki answer as ${path}`,
+    prompt: input.question ?? answer ?? `Write ${path}`,
+  });
+  const result = await writeWikiPage(ctx, {
+    companyId: input.companyId,
+    wikiId,
+    spaceSlug: space.slug,
+    path,
+    contents,
+    expectedHash: stringField(input.expectedHash),
+    summary: `Filed query answer as ${path}`,
+    sourceRefs: input.querySessionId ? [{ querySessionId: input.querySessionId }] : [],
+    operationId: operation.operationId,
+  });
+  const affectedPage = {
+    path,
+    title: result.title,
+    pageType: result.pageType,
+    revisionId: result.revisionId,
+  };
+  await markOperation(ctx, {
+    companyId: input.companyId,
+    operationId: operation.operationId,
+    status: "done",
+    affectedPages: [affectedPage],
+    metadata: { querySessionId: input.querySessionId ?? null },
+  });
+  await ctx.issues.update(operation.issue.id, { status: "done" }, input.companyId);
+  await ctx.issues.createComment(
+    operation.issue.id,
+    `Filed query answer as \`${path}\`.`,
+    input.companyId,
+  );
+
+  if (input.querySessionId) {
+    await ctx.db.execute(
+      `UPDATE ${tableName(ctx.db.namespace, "wiki_query_sessions")}
+          SET filed_outputs = filed_outputs || $3::jsonb,
+              updated_at = now()
+        WHERE company_id = $1 AND id = $2`,
+      [input.companyId, input.querySessionId, jsonArrayParam([affectedPage])],
+    );
+  }
+
+  return {
+    status: "ok",
+    wikiId,
+    spaceSlug: space.slug,
+    path,
+    operationId: operation.operationId,
+    issue: operation.issue,
+    page: affectedPage,
+  };
+}
+
+export async function registerWikiTools(ctx: PluginContext) {
+  ctx.tools.register("wiki_search", {
+    displayName: "Search Wiki",
+    description: "Search indexed wiki page and source metadata.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_search")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const companyId = requireString(input.companyId, "companyId");
+    const wikiId = normalizeWikiId(input.wikiId);
+    const space = await resolveSpace(ctx, { companyId, wikiId, spaceSlug: input.spaceSlug as string | null | undefined });
+    const query = requireString(input.query, "query");
+    const limit = normalizeLimit(input.limit, 20, 50);
+    const rows = await ctx.db.query<{ kind: string; path: string; title: string | null; match_text: string | null }>(
+      `SELECT 'page' AS kind, path, title, page_type AS match_text
+         FROM ${tableName(ctx.db.namespace, "wiki_pages")}
+        WHERE company_id = $1 AND wiki_id = $2 AND space_id = $5 AND (lower(path) LIKE lower($3) OR lower(coalesce(title, '')) LIKE lower($3))
+       UNION ALL
+       SELECT 'source' AS kind, raw_path AS path, title, source_type AS match_text
+         FROM ${tableName(ctx.db.namespace, "wiki_sources")}
+        WHERE company_id = $1 AND wiki_id = $2 AND space_id = $5 AND (lower(raw_path) LIKE lower($3) OR lower(coalesce(title, '')) LIKE lower($3) OR lower(coalesce(url, '')) LIKE lower($3))
+       ORDER BY kind, path
+       LIMIT $4`,
+      [companyId, wikiId, `%${query}%`, limit, space.id],
+    );
+    return {
+      content: rows.length ? rows.map((row) => `${row.kind}: ${row.path}${row.title ? ` - ${row.title}` : ""}`).join("\n") : "No wiki matches found.",
+      data: { companyId, wikiId, spaceSlug: space.slug, query, results: rows },
+    };
+  });
+
+  ctx.tools.register("wiki_read_page", {
+    displayName: "Read Wiki Page",
+    description: "Read a markdown wiki page from the configured local wiki root.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_read_page")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const companyId = requireString(input.companyId, "companyId");
+    const wikiId = normalizeWikiId(input.wikiId);
+    const space = await resolveSpace(ctx, { companyId, wikiId, spaceSlug: input.spaceSlug as string | null | undefined });
+    const path = assertPagePath(requireString(input.path, "path"));
+    const contents = await ctx.localFolders.readText(companyId, WIKI_ROOT_FOLDER_KEY, spaceRelativePath(space, path));
+    return { content: contents, data: { companyId, wikiId, spaceSlug: space.slug, path, hash: contentHash(contents) } };
+  });
+
+  ctx.tools.register("wiki_write_page", {
+    displayName: "Write Wiki Page",
+    description: "Atomically write a markdown wiki page after plugin path validation.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_write_page")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const result = await writeWikiPage(ctx, {
+      companyId: requireString(input.companyId, "companyId"),
+      wikiId: stringField(input.wikiId),
+      spaceSlug: stringField(input.spaceSlug),
+      path: requireString(input.path, "path"),
+      contents: requireString(input.contents, "contents"),
+      expectedHash: stringField(input.expectedHash),
+      summary: stringField(input.summary),
+      sourceRefs: input.sourceRefs,
+    });
+    return { content: `Wrote ${result.path}`, data: result };
+  });
+
+  ctx.tools.register("wiki_propose_patch", {
+    displayName: "Propose Wiki Patch",
+    description: "Return a structured proposed page write without changing files.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_propose_patch")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const companyId = requireString(input.companyId, "companyId");
+    const wikiId = normalizeWikiId(input.wikiId);
+    const space = await resolveSpace(ctx, { companyId, wikiId, spaceSlug: input.spaceSlug as string | null | undefined });
+    const path = assertPagePath(requireString(input.path, "path"));
+    const contents = requireString(input.contents, "contents");
+    const current = await readCurrentWithHash(ctx, companyId, path, space);
+    return {
+      content: `Proposed patch for ${path}`,
+      data: {
+        companyId,
+        wikiId,
+        spaceSlug: space.slug,
+        path,
+        summary: stringField(input.summary),
+        currentHash: current.hash,
+        proposedHash: contentHash(contents),
+        proposedContents: contents,
+      },
+    };
+  });
+
+  ctx.tools.register("wiki_list_sources", {
+    displayName: "List Wiki Sources",
+    description: "Return captured raw source metadata from the plugin index.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_list_sources")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const companyId = requireString(input.companyId, "companyId");
+    const wikiId = normalizeWikiId(input.wikiId);
+    const space = await resolveSpace(ctx, { companyId, wikiId, spaceSlug: input.spaceSlug as string | null | undefined });
+    const limit = normalizeLimit(input.limit, 50, 200);
+    const rows = await ctx.db.query<{ raw_path: string; title: string | null; source_type: string; url: string | null; content_hash: string }>(
+      `SELECT raw_path, title, source_type, url, content_hash
+         FROM ${tableName(ctx.db.namespace, "wiki_sources")}
+        WHERE company_id = $1 AND wiki_id = $2 AND space_id = $4
+        ORDER BY created_at DESC
+        LIMIT $3`,
+      [companyId, wikiId, limit, space.id],
+    );
+    return {
+      content: rows.length ? rows.map((row) => `${row.raw_path}${row.title ? ` - ${row.title}` : ""}`).join("\n") : "No sources captured yet.",
+      data: { companyId, wikiId, spaceSlug: space.slug, sources: rows },
+    };
+  });
+
+  ctx.tools.register("wiki_read_source", {
+    displayName: "Read Wiki Source",
+    description: "Read a captured raw source from the configured local wiki root.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_read_source")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const companyId = requireString(input.companyId, "companyId");
+    const wikiId = normalizeWikiId(input.wikiId);
+    const space = await resolveSpace(ctx, { companyId, wikiId, spaceSlug: input.spaceSlug as string | null | undefined });
+    const rawPath = assertRawPath(requireString(input.rawPath, "rawPath"));
+    const contents = await ctx.localFolders.readText(companyId, WIKI_ROOT_FOLDER_KEY, spaceRelativePath(space, rawPath));
+    return { content: contents, data: { companyId, wikiId, spaceSlug: space.slug, rawPath, hash: contentHash(contents) } };
+  });
+
+  ctx.tools.register("wiki_append_log", {
+    displayName: "Append Wiki Log",
+    description: "Append a maintenance note to wiki/log.md.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_append_log")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const companyId = requireString(input.companyId, "companyId");
+    const wikiId = normalizeWikiId(input.wikiId);
+    const space = await resolveSpace(ctx, { companyId, wikiId, spaceSlug: input.spaceSlug as string | null | undefined });
+    const entry = requireString(input.entry, "entry");
+    let current = "";
+    try {
+      current = await ctx.localFolders.readText(companyId, WIKI_ROOT_FOLDER_KEY, spaceRelativePath(space, "wiki/log.md"));
+    } catch {
+      current = "# Log\n\nAppend-only chronological record of wiki operations.\n";
+    }
+    const next = `${current.trimEnd()}\n\n- ${new Date().toISOString()} ${entry}\n`;
+    await ctx.localFolders.writeTextAtomic(companyId, WIKI_ROOT_FOLDER_KEY, spaceRelativePath(space, "wiki/log.md"), next);
+    await upsertPageMetadata(ctx, {
+      companyId,
+      wikiId,
+      spaceId: space.id,
+      path: "wiki/log.md",
+      contents: next,
+      summary: "Append log entry",
+    });
+    return { content: "Appended log entry", data: { companyId, wikiId, spaceSlug: space.slug, hash: contentHash(next) } };
+  });
+
+  ctx.tools.register("wiki_update_index", {
+    displayName: "Update Wiki Index",
+    description: "Atomically replace wiki/index.md with optional hash conflict checks.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_update_index")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const result = await writeWikiPage(ctx, {
+      companyId: requireString(input.companyId, "companyId"),
+      wikiId: stringField(input.wikiId),
+      spaceSlug: stringField(input.spaceSlug),
+      path: "wiki/index.md",
+      contents: requireString(input.contents, "contents"),
+      expectedHash: stringField(input.expectedHash),
+      summary: "Update index",
+    });
+    return { content: "Updated wiki/index.md", data: result };
+  });
+
+  ctx.tools.register("wiki_list_backlinks", {
+    displayName: "List Wiki Backlinks",
+    description: "Return indexed backlinks for a wiki page.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_list_backlinks")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const companyId = requireString(input.companyId, "companyId");
+    const wikiId = normalizeWikiId(input.wikiId);
+    const space = await resolveSpace(ctx, { companyId, wikiId, spaceSlug: input.spaceSlug as string | null | undefined });
+    const path = assertPagePath(requireString(input.path, "path"));
+    const rows = await ctx.db.query<{ path: string; title: string | null }>(
+      `SELECT path, title
+         FROM ${tableName(ctx.db.namespace, "wiki_pages")}
+        WHERE company_id = $1 AND wiki_id = $2 AND space_id = $4 AND backlinks ? $3
+        ORDER BY path
+        LIMIT 200`,
+      [companyId, wikiId, path, space.id],
+    );
+    return {
+      content: rows.length ? rows.map((row) => `${row.path}${row.title ? ` - ${row.title}` : ""}`).join("\n") : "No backlinks indexed.",
+      data: { companyId, wikiId, spaceSlug: space.slug, path, backlinks: rows },
+    };
+  });
+
+  ctx.tools.register("wiki_list_pages", {
+    displayName: "List Wiki Pages",
+    description: "Return the known page index from plugin metadata.",
+    parametersSchema: ctx.manifest.tools?.find((tool) => tool.name === "wiki_list_pages")?.parametersSchema ?? { type: "object" },
+  }, async (params: unknown): Promise<ToolResult> => {
+    const input = params as ToolParams;
+    const companyId = requireString(input.companyId, "companyId");
+    const wikiId = normalizeWikiId(input.wikiId);
+    const space = await resolveSpace(ctx, { companyId, wikiId, spaceSlug: input.spaceSlug as string | null | undefined });
+    const rows = await ctx.db.query<{ path: string; title: string | null; page_type: string | null }>(
+      `SELECT path, title, page_type FROM ${tableName(ctx.db.namespace, "wiki_pages")} WHERE company_id = $1 AND wiki_id = $2 AND space_id = $3 ORDER BY path LIMIT 200`,
+      [companyId, wikiId, space.id],
+    );
+    return {
+      content: rows.length ? rows.map((row) => `${row.path}${row.title ? ` - ${row.title}` : ""}`).join("\n") : "No pages indexed yet.",
+      data: { companyId, wikiId, spaceSlug: space.slug, pages: rows },
+    };
+  });
+}
+
+export function readCompanyIdFromParams(params: Record<string, unknown>): string {
+  return requireString(params.companyId, "companyId");
+}
+
+const TEMPLATE_FILES = ["AGENTS.md", "IDEA.md"] as const;
+type WikiTemplateFile = (typeof TEMPLATE_FILES)[number];
+
+function isTemplateFile(value: string): value is WikiTemplateFile {
+  return (TEMPLATE_FILES as readonly string[]).includes(value);
+}
+
+export type WikiPageRow = {
+  path: string;
+  title: string | null;
+  pageType: string | null;
+  backlinkCount: number;
+  sourceCount: number;
+  contentHash: string | null;
+  updatedAt: string;
+};
+
+export type WikiSourceRow = {
+  rawPath: string;
+  title: string | null;
+  sourceType: string;
+  url: string | null;
+  status: string;
+  createdAt: string;
+};
+
+const LOCAL_BROWSE_FILE_LIMIT = 2000;
+
+export type WikiOperationRow = {
+  id: string;
+  operationType: string;
+  status: string;
+  hiddenIssueId: string | null;
+  hiddenIssueIdentifier: string | null;
+  hiddenIssueTitle: string | null;
+  hiddenIssueStatus: string | null;
+  projectId: string | null;
+  runIds: unknown[];
+  costCents: number;
+  warnings: unknown[];
+  affectedPages: unknown[];
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export async function listPages(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  pageType?: string | null;
+  includeRaw?: boolean;
+  limit?: number | null;
+}): Promise<{ pages: WikiPageRow[]; sources: WikiSourceRow[] }> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const limit = normalizeLimit(input.limit, 500, LOCAL_BROWSE_FILE_LIMIT);
+  const params: unknown[] = [input.companyId, wikiId, space.id];
+  let pageFilter = "";
+  if (input.pageType) {
+    params.push(input.pageType);
+    pageFilter = ` AND page_type = $${params.length}`;
+  }
+  params.push(limit);
+  const limitIndex = params.length;
+  const pageRows = await ctx.db.query<{
+    path: string;
+    title: string | null;
+    page_type: string | null;
+    backlinks: unknown;
+    source_refs: unknown;
+    content_hash: string | null;
+    updated_at: string;
+  }>(
+    `SELECT path, title, page_type, backlinks, source_refs, content_hash, updated_at::text AS updated_at
+       FROM ${tableName(ctx.db.namespace, "wiki_pages")}
+      WHERE company_id = $1 AND wiki_id = $2 AND space_id = $3${pageFilter}
+      ORDER BY path
+      LIMIT $${limitIndex}`,
+    params,
+  );
+  const readablePageRows = await filterReadableRows(ctx, input.companyId, space, pageRows, (row) => row.path);
+  const pages: WikiPageRow[] = readablePageRows.map((row) => ({
+    path: row.path,
+    title: row.title,
+    pageType: row.page_type,
+    backlinkCount: Array.isArray(row.backlinks) ? row.backlinks.length : 0,
+    sourceCount: Array.isArray(row.source_refs) ? row.source_refs.length : 0,
+    contentHash: row.content_hash,
+    updatedAt: row.updated_at,
+  }));
+  let pagesWithLocalFiles = pages;
+  if (!input.pageType) {
+    const wikiFiles = await listLocalFiles(ctx, { companyId: input.companyId, space, relativePath: "wiki" });
+    pagesWithLocalFiles = mergeLocalPageRows(pages, wikiFiles);
+  }
+
+  let sources: WikiSourceRow[] = [];
+  if (input.includeRaw) {
+    sources = (await listSources(ctx, { companyId: input.companyId, wikiId, spaceSlug: space.slug, limit, onlyReadable: true })).sources;
+    sources = mergeLocalSourceRows(sources, await listLocalFiles(ctx, { companyId: input.companyId, space, relativePath: "raw" }));
+  }
+  return { pages: pagesWithLocalFiles, sources };
+}
+
+export async function listSources(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  limit?: number | null;
+  onlyReadable?: boolean;
+}): Promise<{ sources: WikiSourceRow[] }> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const limit = normalizeLimit(input.limit, 500, LOCAL_BROWSE_FILE_LIMIT);
+  const rows = await ctx.db.query<{ raw_path: string; title: string | null; source_type: string; url: string | null; status: string; created_at: string }>(
+    `SELECT raw_path, title, source_type, url, status, created_at::text AS created_at
+       FROM ${tableName(ctx.db.namespace, "wiki_sources")}
+      WHERE company_id = $1 AND wiki_id = $2 AND space_id = $4
+      ORDER BY created_at DESC
+      LIMIT $3`,
+    [input.companyId, wikiId, limit, space.id],
+  );
+  const sourceRows = input.onlyReadable
+    ? await filterReadableRows(ctx, input.companyId, space, rows, (row) => row.raw_path)
+    : rows;
+  return {
+    sources: sourceRows.map((row) => ({
+      rawPath: row.raw_path,
+      title: row.title,
+      sourceType: row.source_type,
+      url: row.url,
+      status: row.status,
+      createdAt: row.created_at,
+    })),
+  };
+}
+
+export async function readWikiPage(ctx: PluginContext, input: { companyId: string; wikiId?: string | null; spaceSlug?: string | null; path: string }) {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const path = assertWikiPath(input.path);
+  const contents = await ctx.localFolders.readText(input.companyId, WIKI_ROOT_FOLDER_KEY, spaceRelativePath(space, path));
+  const meta = await ctx.db.query<{ title: string | null; page_type: string | null; backlinks: unknown; source_refs: unknown; updated_at: string }>(
+    `SELECT title, page_type, backlinks, source_refs, updated_at::text AS updated_at
+       FROM ${tableName(ctx.db.namespace, "wiki_pages")}
+      WHERE company_id = $1 AND wiki_id = $2 AND space_id = $4 AND path = $3
+      LIMIT 1`,
+    [input.companyId, wikiId, path, space.id],
+  );
+  const row = meta[0] ?? null;
+  return {
+    wikiId,
+    spaceSlug: space.slug,
+    path,
+    contents,
+    title: row?.title ?? inferTitle(path, contents),
+    pageType: row?.page_type ?? inferPageType(path),
+    backlinks: Array.isArray(row?.backlinks) ? row?.backlinks : [],
+    sourceRefs: Array.isArray(row?.source_refs) ? row?.source_refs : [],
+    updatedAt: row?.updated_at ?? null,
+    hash: contentHash(contents),
+  };
+}
+
+export async function readTemplate(ctx: PluginContext, input: { companyId: string; path: string }) {
+  if (!isTemplateFile(input.path)) {
+    throw new Error(`template path must be one of ${TEMPLATE_FILES.join(", ")}`);
+  }
+  try {
+    const contents = await ctx.localFolders.readText(input.companyId, WIKI_ROOT_FOLDER_KEY, input.path);
+    return { path: input.path, contents, hash: contentHash(contents), exists: true };
+  } catch (error) {
+    return { path: input.path, contents: "", hash: null, exists: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export async function writeTemplate(ctx: PluginContext, input: { companyId: string; path: string; contents: string }) {
+  if (!isTemplateFile(input.path)) {
+    throw new Error(`template path must be one of ${TEMPLATE_FILES.join(", ")}`);
+  }
+  await ctx.localFolders.writeTextAtomic(input.companyId, WIKI_ROOT_FOLDER_KEY, input.path, input.contents);
+  return { status: "ok", path: input.path, hash: contentHash(input.contents) };
+}
+
+export type DistillationCursorRow = {
+  id: string;
+  sourceScope: string;
+  scopeKey: string;
+  projectId: string | null;
+  projectName: string | null;
+  projectColor: string | null;
+  rootIssueId: string | null;
+  rootIssueIdentifier: string | null;
+  rootIssueTitle: string | null;
+  lastProcessedAt: string | null;
+  lastObservedAt: string | null;
+  pendingEventCount: number;
+  lastSourceHash: string | null;
+  lastSuccessfulRunId: string | null;
+};
+
+export type DistillationRunRow = {
+  id: string;
+  cursorId: string | null;
+  workItemId: string | null;
+  projectId: string | null;
+  projectName: string | null;
+  rootIssueId: string | null;
+  rootIssueIdentifier: string | null;
+  sourceWindowStart: string | null;
+  sourceWindowEnd: string | null;
+  sourceHash: string | null;
+  status: string;
+  costCents: number;
+  retryCount: number;
+  warnings: string[];
+  metadata: Record<string, unknown>;
+  operationIssueId: string | null;
+  operationIssueIdentifier: string | null;
+  operationIssueTitle: string | null;
+  affectedPagePaths: string[];
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type DistillationWorkItemRow = {
+  id: string;
+  workItemKind: string;
+  status: string;
+  priority: string;
+  projectId: string | null;
+  rootIssueId: string | null;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type DistillationPageBindingRow = {
+  id: string;
+  pagePath: string;
+  projectId: string | null;
+  projectName: string | null;
+  rootIssueId: string | null;
+  lastAppliedSourceHash: string | null;
+  lastDistillationRunId: string | null;
+  lastRunStatus: string | null;
+  lastRunCompletedAt: string | null;
+  lastRunSourceWindowEnd: string | null;
+  lastRunSourceHash: string | null;
+  metadata: Record<string, unknown>;
+  updatedAt: string;
+};
+
+export type DistillationSourceSnapshotRow = {
+  id: string;
+  distillationRunId: string;
+  sourceHash: string;
+  maxCharacters: number;
+  clipped: boolean;
+  sourceRefs: unknown[];
+  metadata: Record<string, unknown>;
+  createdAt: string;
+};
+
+export type DistillationOverview = {
+  cursors: DistillationCursorRow[];
+  runs: DistillationRunRow[];
+  workItems: DistillationWorkItemRow[];
+  pageBindings: DistillationPageBindingRow[];
+  reviewWorkItems: DistillationWorkItemRow[];
+  counts: {
+    cursors: number;
+    runningRuns: number;
+    failedRuns24h: number;
+    reviewRequired: number;
+  };
+};
+
+function jsonObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function jsonArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function affectedPagePathsFromRunMetadata(metadata: Record<string, unknown>, fallbackBindings: DistillationPageBindingRow[], runId: string): string[] {
+  const explicit = jsonArray(metadata.affectedPages ?? metadata.pagePaths ?? metadata.affected_pages)
+    .map((entry) => {
+      if (typeof entry === "string") return entry;
+      if (entry && typeof entry === "object") {
+        const path = (entry as Record<string, unknown>).path;
+        return typeof path === "string" ? path : null;
+      }
+      return null;
+    })
+    .filter((value): value is string => Boolean(value));
+  if (explicit.length > 0) return Array.from(new Set(explicit));
+  const bindings = fallbackBindings
+    .filter((binding) => binding.lastDistillationRunId === runId)
+    .map((binding) => binding.pagePath);
+  return Array.from(new Set(bindings));
+}
+
+export async function getDistillationOverview(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  limit?: number | null;
+}): Promise<DistillationOverview> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const runLimit = normalizeLimit(input.limit ?? 25, 25, 200);
+  const cursorRows = await ctx.db.query<{
+    id: string;
+    source_scope: string;
+    scope_key: string;
+    project_id: string | null;
+    project_name: string | null;
+    project_color: string | null;
+    root_issue_id: string | null;
+    root_issue_identifier: string | null;
+    root_issue_title: string | null;
+    last_processed_at: string | null;
+    last_observed_at: string | null;
+    pending_event_count: number;
+    last_source_hash: string | null;
+    last_successful_run_id: string | null;
+  }>(
+    `SELECT cursor.id,
+            cursor.source_scope,
+            cursor.scope_key,
+            cursor.project_id,
+            project.name AS project_name,
+            project.color AS project_color,
+            cursor.root_issue_id,
+            issue.identifier AS root_issue_identifier,
+            issue.title AS root_issue_title,
+            cursor.last_processed_at::text AS last_processed_at,
+            cursor.last_observed_at::text AS last_observed_at,
+            cursor.pending_event_count,
+            cursor.last_source_hash,
+            cursor.last_successful_run_id
+       FROM ${distillationCursorTable(ctx)} cursor
+       LEFT JOIN public.projects project ON project.id = cursor.project_id
+       LEFT JOIN public.issues issue ON issue.id = cursor.root_issue_id
+      WHERE cursor.company_id = $1 AND cursor.wiki_id = $2 AND cursor.space_id = $3
+      ORDER BY cursor.updated_at DESC
+      LIMIT 200`,
+    [input.companyId, wikiId, space.id],
+  );
+
+  const runRows = await ctx.db.query<{
+    id: string;
+    cursor_id: string | null;
+    work_item_id: string | null;
+    project_id: string | null;
+    project_name: string | null;
+    root_issue_id: string | null;
+    root_issue_identifier: string | null;
+    source_window_start: string | null;
+    source_window_end: string | null;
+    source_hash: string | null;
+    status: string;
+    cost_cents: number;
+    retry_count: number;
+    warnings: unknown;
+    metadata: unknown;
+    operation_issue_id: string | null;
+    operation_issue_identifier: string | null;
+    operation_issue_title: string | null;
+    created_at: string;
+    updated_at: string;
+  }>(
+    `SELECT run.id,
+            run.cursor_id,
+            run.work_item_id,
+            run.project_id,
+            project.name AS project_name,
+            run.root_issue_id,
+            root_issue.identifier AS root_issue_identifier,
+            run.source_window_start::text AS source_window_start,
+            run.source_window_end::text AS source_window_end,
+            run.source_hash,
+            run.status,
+            run.cost_cents,
+            run.retry_count,
+            run.warnings,
+            run.metadata,
+            run.operation_issue_id,
+            op_issue.identifier AS operation_issue_identifier,
+            op_issue.title AS operation_issue_title,
+            run.created_at::text AS created_at,
+            run.updated_at::text AS updated_at
+       FROM ${distillationRunTable(ctx)} run
+       LEFT JOIN public.projects project ON project.id = run.project_id
+       LEFT JOIN public.issues root_issue ON root_issue.id = run.root_issue_id
+       LEFT JOIN public.issues op_issue ON op_issue.id = run.operation_issue_id
+      WHERE run.company_id = $1 AND run.wiki_id = $2 AND run.space_id = $4
+      ORDER BY run.created_at DESC
+      LIMIT $3`,
+    [input.companyId, wikiId, runLimit, space.id],
+  );
+
+  const workItemRows = await ctx.db.query<{
+    id: string;
+    work_item_kind: string;
+    status: string;
+    priority: string;
+    project_id: string | null;
+    root_issue_id: string | null;
+    metadata: unknown;
+    created_at: string;
+    updated_at: string;
+  }>(
+    `SELECT id, work_item_kind, status, priority, project_id, root_issue_id, metadata,
+            created_at::text AS created_at, updated_at::text AS updated_at
+       FROM ${distillationWorkItemTable(ctx)}
+      WHERE company_id = $1 AND wiki_id = $2 AND space_id = $3 AND status IN ('pending', 'review_required', 'in_progress', 'failed')
+      ORDER BY created_at DESC
+      LIMIT 100`,
+    [input.companyId, wikiId, space.id],
+  );
+
+  const bindingRows = await ctx.db.query<{
+    id: string;
+    page_path: string;
+    project_id: string | null;
+    project_name: string | null;
+    root_issue_id: string | null;
+    last_applied_source_hash: string | null;
+    last_distillation_run_id: string | null;
+    last_run_status: string | null;
+    last_run_completed_at: string | null;
+    last_run_source_window_end: string | null;
+    last_run_source_hash: string | null;
+    metadata: unknown;
+    updated_at: string;
+  }>(
+    `SELECT binding.id,
+            binding.page_path,
+            binding.project_id,
+            project.name AS project_name,
+            binding.root_issue_id,
+            binding.last_applied_source_hash,
+            binding.last_distillation_run_id,
+            run.status::text AS last_run_status,
+            run.updated_at::text AS last_run_completed_at,
+            run.source_window_end::text AS last_run_source_window_end,
+            run.source_hash AS last_run_source_hash,
+            binding.metadata,
+            binding.updated_at::text AS updated_at
+       FROM ${pageBindingTable(ctx)} binding
+       LEFT JOIN public.projects project ON project.id = binding.project_id
+       LEFT JOIN ${distillationRunTable(ctx)} run ON run.id = binding.last_distillation_run_id
+      WHERE binding.company_id = $1 AND binding.wiki_id = $2 AND binding.space_id = $3
+      ORDER BY binding.updated_at DESC
+      LIMIT 200`,
+    [input.companyId, wikiId, space.id],
+  );
+
+  const cursors: DistillationCursorRow[] = cursorRows.map((row) => ({
+    id: row.id,
+    sourceScope: row.source_scope,
+    scopeKey: row.scope_key,
+    projectId: row.project_id,
+    projectName: row.project_name,
+    projectColor: row.project_color,
+    rootIssueId: row.root_issue_id,
+    rootIssueIdentifier: row.root_issue_identifier,
+    rootIssueTitle: row.root_issue_title,
+    lastProcessedAt: row.last_processed_at,
+    lastObservedAt: row.last_observed_at,
+    pendingEventCount: Number(row.pending_event_count ?? 0),
+    lastSourceHash: row.last_source_hash,
+    lastSuccessfulRunId: row.last_successful_run_id,
+  }));
+
+  const pageBindings: DistillationPageBindingRow[] = bindingRows.map((row) => ({
+    id: row.id,
+    pagePath: row.page_path,
+    projectId: row.project_id,
+    projectName: row.project_name,
+    rootIssueId: row.root_issue_id,
+    lastAppliedSourceHash: row.last_applied_source_hash,
+    lastDistillationRunId: row.last_distillation_run_id,
+    lastRunStatus: row.last_run_status,
+    lastRunCompletedAt: row.last_run_completed_at,
+    lastRunSourceWindowEnd: row.last_run_source_window_end,
+    lastRunSourceHash: row.last_run_source_hash,
+    metadata: jsonObject(row.metadata),
+    updatedAt: row.updated_at,
+  }));
+
+  const runs: DistillationRunRow[] = runRows.map((row) => {
+    const metadata = jsonObject(row.metadata);
+    return {
+      id: row.id,
+      cursorId: row.cursor_id,
+      workItemId: row.work_item_id,
+      projectId: row.project_id,
+      projectName: row.project_name,
+      rootIssueId: row.root_issue_id,
+      rootIssueIdentifier: row.root_issue_identifier,
+      sourceWindowStart: row.source_window_start,
+      sourceWindowEnd: row.source_window_end,
+      sourceHash: row.source_hash,
+      status: row.status,
+      costCents: Number(row.cost_cents ?? 0),
+      retryCount: Number(row.retry_count ?? 0),
+      warnings: jsonArray(row.warnings).map((entry) => (typeof entry === "string" ? entry : JSON.stringify(entry))),
+      metadata,
+      operationIssueId: row.operation_issue_id,
+      operationIssueIdentifier: row.operation_issue_identifier,
+      operationIssueTitle: row.operation_issue_title,
+      affectedPagePaths: affectedPagePathsFromRunMetadata(metadata, pageBindings, row.id),
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    };
+  });
+
+  const workItems: DistillationWorkItemRow[] = workItemRows.map((row) => ({
+    id: row.id,
+    workItemKind: row.work_item_kind,
+    status: row.status,
+    priority: row.priority,
+    projectId: row.project_id,
+    rootIssueId: row.root_issue_id,
+    metadata: jsonObject(row.metadata),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  }));
+
+  const reviewWorkItems = workItems.filter((item) => item.status === "review_required" || item.workItemKind === "review");
+  const failedSince = Date.now() - 24 * 60 * 60 * 1000;
+  const failedRuns24h = runs.filter((run) => {
+    if (run.status !== "failed" && run.status !== "refused_cost_cap") return false;
+    const updatedAt = run.updatedAt ? Date.parse(run.updatedAt) : Number.NaN;
+    return Number.isFinite(updatedAt) ? updatedAt >= failedSince : true;
+  }).length;
+
+  return {
+    cursors,
+    runs,
+    workItems,
+    pageBindings,
+    reviewWorkItems,
+    counts: {
+      cursors: cursors.length,
+      runningRuns: runs.filter((run) => run.status === "running").length,
+      failedRuns24h,
+      reviewRequired: reviewWorkItems.length,
+    },
+  };
+}
+
+export async function getDistillationPageProvenance(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  pagePath: string;
+}): Promise<{
+  binding: DistillationPageBindingRow | null;
+  runs: DistillationRunRow[];
+  snapshot: DistillationSourceSnapshotRow | null;
+  cursor: DistillationCursorRow | null;
+}> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const overview = await getDistillationOverview(ctx, { companyId: input.companyId, wikiId, spaceSlug: space.slug });
+  const binding = overview.pageBindings.find((row) => row.pagePath === input.pagePath) ?? null;
+  if (!binding) {
+    return { binding: null, runs: [], snapshot: null, cursor: null };
+  }
+  const relatedRuns = overview.runs.filter((run) => {
+    if (binding.lastDistillationRunId === run.id) return true;
+    if (binding.projectId && run.projectId === binding.projectId) return true;
+    if (binding.rootIssueId && run.rootIssueId === binding.rootIssueId) return true;
+    return run.affectedPagePaths.includes(binding.pagePath);
+  });
+  const cursor = overview.cursors.find((row) => {
+    if (binding.rootIssueId && row.rootIssueId === binding.rootIssueId) return true;
+    if (binding.projectId && row.projectId === binding.projectId) return true;
+    return false;
+  }) ?? null;
+
+  let snapshot: DistillationSourceSnapshotRow | null = null;
+  if (binding.lastDistillationRunId) {
+    const snapshotRows = await ctx.db.query<{
+      id: string;
+      distillation_run_id: string;
+      source_hash: string;
+      max_characters: number;
+      clipped: boolean;
+      source_refs: unknown;
+      metadata: unknown;
+      created_at: string;
+    }>(
+      `SELECT id, distillation_run_id, source_hash, max_characters, clipped, source_refs, metadata, created_at::text AS created_at
+         FROM ${sourceSnapshotTable(ctx)}
+        WHERE company_id = $1 AND wiki_id = $2 AND space_id = $4 AND distillation_run_id = $3
+        ORDER BY created_at DESC
+        LIMIT 1`,
+      [input.companyId, wikiId, binding.lastDistillationRunId, space.id],
+    );
+    if (snapshotRows[0]) {
+      const row = snapshotRows[0];
+      snapshot = {
+        id: row.id,
+        distillationRunId: row.distillation_run_id,
+        sourceHash: row.source_hash,
+        maxCharacters: Number(row.max_characters ?? 0),
+        clipped: Boolean(row.clipped),
+        sourceRefs: jsonArray(row.source_refs),
+        metadata: jsonObject(row.metadata),
+        createdAt: row.created_at,
+      };
+    }
+  }
+
+  return { binding, runs: relatedRuns, snapshot, cursor };
+}
+
+export async function listOperations(ctx: PluginContext, input: {
+  companyId: string;
+  wikiId?: string | null;
+  spaceSlug?: string | null;
+  operationType?: string | null;
+  status?: string | null;
+  limit?: number | null;
+}): Promise<{ operations: WikiOperationRow[] }> {
+  const wikiId = normalizeWikiId(input.wikiId);
+  const space = await resolveSpace(ctx, { companyId: input.companyId, wikiId, spaceSlug: input.spaceSlug });
+  const limit = normalizeLimit(input.limit, 50, 500);
+  const params: unknown[] = [input.companyId, wikiId, space.id];
+  const filters: string[] = [];
+  if (input.operationType && input.operationType !== "all") {
+    params.push(input.operationType);
+    filters.push(`op.operation_type = $${params.length}`);
+  }
+  if (input.status && input.status !== "all") {
+    params.push(input.status);
+    filters.push(`op.status = $${params.length}`);
+  }
+  params.push(limit);
+  const filterSql = filters.length ? ` AND ${filters.join(" AND ")}` : "";
+  const rows = await ctx.db.query<{
+    id: string;
+    operation_type: string;
+    status: string;
+    hidden_issue_id: string | null;
+    hidden_issue_identifier: string | null;
+    hidden_issue_title: string | null;
+    hidden_issue_status: string | null;
+    project_id: string | null;
+    run_ids: unknown;
+    cost_cents: number;
+    warnings: unknown;
+    affected_pages: unknown;
+    metadata: unknown;
+    created_at: string;
+    updated_at: string;
+  }>(
+    `SELECT op.id, op.operation_type, op.status, op.hidden_issue_id, op.project_id,
+            op.run_ids, op.cost_cents, op.warnings, op.affected_pages, op.metadata,
+            op.created_at::text AS created_at, op.updated_at::text AS updated_at,
+            issue.identifier AS hidden_issue_identifier,
+            issue.title AS hidden_issue_title,
+            issue.status::text AS hidden_issue_status
+       FROM ${tableName(ctx.db.namespace, "wiki_operations")} op
+       LEFT JOIN public.issues issue ON issue.id = op.hidden_issue_id
+      WHERE op.company_id = $1 AND op.wiki_id = $2 AND op.space_id = $3${filterSql}
+      ORDER BY op.created_at DESC
+      LIMIT $${params.length}`,
+    params,
+  );
+  return {
+    operations: rows.map((row) => ({
+      id: row.id,
+      operationType: row.operation_type,
+      status: row.status,
+      hiddenIssueId: row.hidden_issue_id,
+      hiddenIssueIdentifier: row.hidden_issue_identifier,
+      hiddenIssueTitle: row.hidden_issue_title,
+      hiddenIssueStatus: row.hidden_issue_status,
+      projectId: row.project_id,
+      runIds: Array.isArray(row.run_ids) ? row.run_ids : [],
+      costCents: Number(row.cost_cents ?? 0),
+      warnings: Array.isArray(row.warnings) ? row.warnings : [],
+      affectedPages: Array.isArray(row.affected_pages) ? row.affected_pages : [],
+      metadata: jsonObject(row.metadata),
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    })),
+  };
+}
diff --git a/packages/plugins/plugin-llm-wiki/src/worker.ts b/packages/plugins/plugin-llm-wiki/src/worker.ts
new file mode 100644
index 00000000..0335b31b
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/src/worker.ts
@@ -0,0 +1,1081 @@
+import {
+  definePlugin,
+  runWorker,
+  type PluginApiRequestInput,
+  type PluginContext,
+  type PluginManagedRoutineDeclaration,
+  type PluginManagedRoutineResolution,
+} from "@paperclipai/plugin-sdk";
+import {
+  PAPERCLIP_DISTILL_SKILL_KEY,
+  WIKI_MAINTENANCE_ROUTINE_KEYS,
+  WIKI_ROOT_FOLDER_KEY,
+} from "./manifest.js";
+import {
+  bootstrapWikiRoot,
+  bootstrapSpace,
+  assemblePaperclipSourceBundle,
+  archiveSpace,
+  captureWikiSource,
+  createSpace,
+  createPaperclipDistillationRun,
+  createPaperclipDistillationWorkItem,
+  createOperationIssue,
+  distillPaperclipProjectPage,
+  enableActiveProjectDistillation,
+  fileQueryAnswerAsPage,
+  getDistillationOverview,
+  getDistillationPageProvenance,
+  getDistillationAutoApplyRestriction,
+  getEventIngestionSettings,
+  listPaperclipIngestionCandidates,
+  getPaperclipIngestionProfile,
+  getOverview,
+  listSpaces,
+  handlePaperclipEventIngestion,
+  listWikiAgentOptions,
+  listWikiProjectOptions,
+  listOperations,
+  listPages,
+  listSources,
+  readCompanyIdFromParams,
+  readTemplate,
+  readWikiPage,
+  recordPaperclipDistillationOutcome,
+  reconcileWikiAgentResource,
+  reconcileWikiProjectResource,
+  reconcileWikiRoutineResources,
+  reconcileWikiSkillResources,
+  registerWikiTools,
+  resetWikiSkillResources,
+  resetWikiAgentResource,
+  resetWikiProjectResource,
+  selectWikiAgentResource,
+  selectWikiProjectResource,
+  startWikiQuerySession,
+  spaceFolderStatus,
+  updateEventIngestionSettings,
+  updatePaperclipIngestionProfile,
+  updateSpace,
+  writeTemplate,
+  writeWikiPage,
+} from "./wiki.js";
+
+function stringField(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function routineKeyField(value: unknown): (typeof WIKI_MAINTENANCE_ROUTINE_KEYS)[number] {
+  const routineKey = stringField(value);
+  if (!routineKey) {
+    throw new Error(`routineKey is required; valid values: ${WIKI_MAINTENANCE_ROUTINE_KEYS.join(", ")}`);
+  }
+  if (!WIKI_MAINTENANCE_ROUTINE_KEYS.includes(routineKey as (typeof WIKI_MAINTENANCE_ROUTINE_KEYS)[number])) {
+    throw new Error(`Unknown managed routine: ${routineKey}`);
+  }
+  return routineKey as (typeof WIKI_MAINTENANCE_ROUTINE_KEYS)[number];
+}
+
+function routineOverridesFromParams(params: Record<string, unknown>) {
+  const overrides: { assigneeAgentId?: string; projectId?: string } = {};
+  const assigneeAgentId = stringField(params.assigneeAgentId);
+  const projectId = stringField(params.projectId);
+  if (assigneeAgentId) overrides.assigneeAgentId = assigneeAgentId;
+  if (projectId) overrides.projectId = projectId;
+  return overrides;
+}
+
+let activeContext: PluginContext | null = null;
+const PAPERCLIP_EVENT_INGESTION_EVENTS = [
+  "issue.created",
+  "issue.updated",
+  "issue.comment.created",
+  "issue.document.created",
+  "issue.document.updated",
+] as const;
+
+type ManagedRoutineDefaultDrift = {
+  changedFields: string[];
+  defaultTitle: string;
+  defaultDescription: string | null;
+};
+
+type ManagedRoutineSettingsResolution = PluginManagedRoutineResolution & {
+  defaultDrift: ManagedRoutineDefaultDrift | null;
+};
+
+function requireContext(): PluginContext {
+  if (!activeContext) throw new Error("LLM Wiki plugin has not been set up");
+  return activeContext;
+}
+
+function normalizeRoutineTemplateText(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const normalized = value.replace(/\r\n/g, "\n").trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function manualDistillScopeLabel(input: { projectId?: string | null; rootIssueId?: string | null }) {
+  if (input.rootIssueId) return "selected root issue";
+  if (input.projectId) return "selected project";
+  return "company-wide stale cursor scan";
+}
+
+function buildManualDistillPrompt(input: { companyId: string; projectId?: string | null; rootIssueId?: string | null }) {
+  const scopeLabel = manualDistillScopeLabel(input);
+  return [
+    "Manual LLM Wiki distillation requested outside recurring cadence.",
+    "",
+    "Prompt source: LLM Wiki plugin action `distill-paperclip-now` (`packages/plugins/plugin-llm-wiki/src/worker.ts`).",
+    `Required skill: use the installed \`${PAPERCLIP_DISTILL_SKILL_KEY}\` skill before changing wiki files.`,
+    "",
+    "Scope:",
+    `- Company ID: ${input.companyId}`,
+    `- Requested scope: ${scopeLabel}`,
+    input.projectId ? `- Source project ID: ${input.projectId}` : null,
+    input.rootIssueId ? `- Source root issue ID: ${input.rootIssueId}` : null,
+    !input.projectId && !input.rootIssueId
+      ? "- Do not hardcode a single project. Find non-plugin Paperclip issues/comments/documents that changed in any project after the last processed cursor and are old enough for the stale/debounce threshold."
+      : null,
+    "",
+    "Process:",
+    "1. Read the wiki root AGENTS.md, wiki/index.md, and recent wiki/log.md entries.",
+    "2. Assemble bounded Paperclip source bundles for every eligible project or root issue, excluding LLM Wiki plugin-operation issues.",
+    "3. Turn durable signal into project standups, wiki-insightful project pages, decisions, history, index, and log updates per the paperclip-distill skill.",
+    "4. Surface clipped, low-signal, stale-hash, or source-window warnings instead of hiding them.",
+  ].filter((line): line is string => line !== null).join("\n");
+}
+
+function withManagedRoutineDefaultDrift(
+  routine: PluginManagedRoutineResolution,
+  declaration: PluginManagedRoutineDeclaration | undefined,
+): ManagedRoutineSettingsResolution {
+  if (!routine.routine || !declaration) {
+    return { ...routine, defaultDrift: null };
+  }
+
+  const changedFields: string[] = [];
+  if (normalizeRoutineTemplateText(routine.routine.title) !== normalizeRoutineTemplateText(declaration.title)) {
+    changedFields.push("title");
+  }
+  if (normalizeRoutineTemplateText(routine.routine.description) !== normalizeRoutineTemplateText(declaration.description ?? null)) {
+    changedFields.push("description");
+  }
+  if (routine.routine.priority !== (declaration.priority ?? "medium")) {
+    changedFields.push("priority");
+  }
+  if (routine.routine.concurrencyPolicy !== (declaration.concurrencyPolicy ?? "coalesce_if_active")) {
+    changedFields.push("concurrency policy");
+  }
+  if (routine.routine.catchUpPolicy !== (declaration.catchUpPolicy ?? "skip_missed")) {
+    changedFields.push("catch-up policy");
+  }
+
+  return {
+    ...routine,
+    defaultDrift: changedFields.length > 0
+      ? {
+          changedFields,
+          defaultTitle: declaration.title,
+          defaultDescription: declaration.description ?? null,
+        }
+      : null,
+  };
+}
+
+const plugin = definePlugin({
+  async setup(ctx) {
+    activeContext = ctx;
+    await registerWikiTools(ctx);
+
+    for (const eventName of PAPERCLIP_EVENT_INGESTION_EVENTS) {
+      ctx.events.on(eventName, async (event) => {
+        const result = await handlePaperclipEventIngestion(ctx, event);
+        if (result.status === "recorded") {
+          ctx.logger.info("LLM Wiki recorded Paperclip event for cursor discovery", {
+            eventType: event.eventType,
+            companyId: event.companyId,
+            sourceKind: result.sourceKind,
+            sourceId: result.sourceId,
+            cursorId: result.cursorId,
+          });
+        }
+      });
+    }
+
+    ctx.data.register("overview", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      return getOverview(ctx, companyId);
+    });
+
+    ctx.data.register("health", async (params) => {
+      const companyId = stringField(params.companyId);
+      return companyId
+        ? getOverview(ctx, companyId)
+        : { status: "ok", checkedAt: new Date().toISOString(), message: "LLM Wiki worker is running" };
+    });
+
+    ctx.actions.register("bootstrap-root", async (params) => {
+      return bootstrapWikiRoot(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        path: stringField(params.path),
+      });
+    });
+
+    ctx.data.register("spaces", async (params) => {
+      return listSpaces(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+      });
+    });
+
+    ctx.data.register("space", async (params) => {
+      return spaceFolderStatus(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+      });
+    });
+
+    ctx.actions.register("create-space", async (params) => {
+      return createSpace(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        slug: stringField(params.slug),
+        displayName: stringField(params.displayName),
+        folderMode: stringField(params.folderMode) as "managed_subfolder" | "existing_local_folder" | null,
+        accessScope: stringField(params.accessScope) as "shared" | "personal" | "team" | null,
+        settings: typeof params.settings === "object" && params.settings != null ? params.settings as Record<string, unknown> : null,
+      });
+    });
+
+    ctx.actions.register("update-space", async (params) => {
+      return updateSpace(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        displayName: stringField(params.displayName),
+        status: stringField(params.status) as "active" | "archived" | null,
+        settings: typeof params.settings === "object" && params.settings != null ? params.settings as Record<string, unknown> : null,
+      });
+    });
+
+    ctx.actions.register("bootstrap-space", async (params) => {
+      return bootstrapSpace(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+      });
+    });
+
+    ctx.actions.register("archive-space", async (params) => {
+      return archiveSpace(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+      });
+    });
+
+    ctx.actions.register("create-operation", async (params) => {
+      const operationType = stringField(params.operationType);
+      if (
+        operationType !== "ingest" &&
+        operationType !== "query" &&
+        operationType !== "lint" &&
+        operationType !== "file-as-page" &&
+        operationType !== "index" &&
+        operationType !== "distill" &&
+        operationType !== "backfill"
+      ) {
+        throw new Error("operationType must be ingest, query, lint, file-as-page, index, distill, or backfill");
+      }
+      return createOperationIssue(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        operationType,
+        title: stringField(params.title),
+        prompt: stringField(params.prompt),
+        useCheapModelProfile: params.useCheapModelProfile === true,
+      });
+    });
+
+    ctx.actions.register("capture-source", async (params) => {
+      return captureWikiSource(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        sourceType: stringField(params.sourceType),
+        title: stringField(params.title),
+        url: stringField(params.url),
+        contents: typeof params.contents === "string" ? params.contents : "",
+        rawPath: stringField(params.rawPath),
+        metadata: typeof params.metadata === "object" && params.metadata != null ? params.metadata as Record<string, unknown> : null,
+      });
+    });
+
+    ctx.actions.register("write-page", async (params) => {
+      return writeWikiPage(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        path: stringField(params.path) ?? "",
+        contents: typeof params.contents === "string" ? params.contents : "",
+        expectedHash: stringField(params.expectedHash),
+        summary: stringField(params.summary),
+        sourceRefs: params.sourceRefs,
+        writer: "board_ui",
+      });
+    });
+
+    ctx.actions.register("write-template", async (params) => {
+      return writeTemplate(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        path: stringField(params.path) ?? "",
+        contents: typeof params.contents === "string" ? params.contents : "",
+      });
+    });
+
+    ctx.actions.register("update-event-ingestion-settings", async (params) => {
+      const requestedSources = typeof params.sources === "object" && params.sources != null && !Array.isArray(params.sources)
+        ? params.sources as Record<string, unknown>
+        : null;
+      const sources: { issues?: boolean; comments?: boolean; documents?: boolean } = {};
+      if (requestedSources && Object.prototype.hasOwnProperty.call(requestedSources, "issues")) {
+        sources.issues = requestedSources.issues === true;
+      }
+      if (requestedSources && Object.prototype.hasOwnProperty.call(requestedSources, "comments")) {
+        sources.comments = requestedSources.comments === true;
+      }
+      if (requestedSources && Object.prototype.hasOwnProperty.call(requestedSources, "documents")) {
+        sources.documents = requestedSources.documents === true;
+      }
+      const settings: {
+        enabled?: boolean;
+        wikiId?: string;
+        maxCharacters?: number;
+        sources?: typeof sources;
+      } = {
+        wikiId: stringField(params.wikiId) ?? undefined,
+        maxCharacters: typeof params.maxCharacters === "number" ? params.maxCharacters : undefined,
+      };
+      if (typeof params.enabled === "boolean") {
+        settings.enabled = params.enabled;
+      }
+      if (Object.keys(sources).length > 0) {
+        settings.sources = sources;
+      }
+      return updateEventIngestionSettings(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        settings,
+      });
+    });
+
+    ctx.data.register("paperclip-ingestion-profile", async (params) => {
+      return getPaperclipIngestionProfile(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+      });
+    });
+
+    ctx.data.register("paperclip-ingestion-candidates", async (params) => {
+      return listPaperclipIngestionCandidates(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        query: stringField(params.query),
+      });
+    });
+
+    ctx.actions.register("update-paperclip-ingestion-profile", async (params) => {
+      return updatePaperclipIngestionProfile(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        profile: params.profile,
+      });
+    });
+
+    ctx.actions.register("queue-paperclip-ingestion-backfill", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      const sourceScope = typeof params.sourceScope === "object" && params.sourceScope != null && !Array.isArray(params.sourceScope)
+        ? params.sourceScope as Record<string, unknown>
+        : {};
+      const sourceScopeKind = stringField(sourceScope.kind);
+      const projectIds = Array.isArray(sourceScope.projectIds) ? sourceScope.projectIds.map(stringField).filter((id): id is string => Boolean(id)) : [];
+      const issueIds = Array.isArray(sourceScope.issueIds) ? sourceScope.issueIds.map(stringField).filter((id): id is string => Boolean(id)) : [];
+      const scopes = sourceScopeKind === "selected_projects"
+        ? projectIds.map((projectId) => ({ projectId, rootIssueId: null as string | null }))
+        : sourceScopeKind === "root_issues"
+          ? issueIds.map((rootIssueId) => ({ projectId: null as string | null, rootIssueId }))
+          : [];
+      if (scopes.length === 0) {
+        return {
+          status: "refused_policy",
+          wikiId: stringField(params.wikiId) ?? "default",
+          spaceSlug: stringField(params.spaceSlug) ?? "default",
+          warnings: ["Backfill requires a selected project or root issue scope in Phase 4."],
+        };
+      }
+      const backfillStartAt = stringField(params.backfillStartAt);
+      const backfillEndAt = stringField(params.backfillEndAt);
+      const wikiId = stringField(params.wikiId);
+      const spaceSlug = stringField(params.spaceSlug);
+      const requestedByIssueId = stringField(params.requestedByIssueId);
+      const idempotencyKey = stringField(params.idempotencyKey);
+      const queued: Array<{ workItemId: string; issueId: string; projectId: string | null; rootIssueId: string | null }> = [];
+      for (const scope of scopes) {
+        const idempotencyScope = scope.rootIssueId ? `root:${scope.rootIssueId}` : `project:${scope.projectId}`;
+        const workItem = await createPaperclipDistillationWorkItem(ctx, {
+          companyId,
+          wikiId,
+          spaceSlug,
+          kind: "backfill",
+          projectId: scope.projectId,
+          rootIssueId: scope.rootIssueId,
+          requestedByIssueId,
+          priority: "low",
+          idempotencyKey: idempotencyKey && scopes.length === 1
+            ? idempotencyKey
+            : `${idempotencyKey ?? "profile-backfill"}:${idempotencyScope}:${backfillStartAt ?? "begin"}:${backfillEndAt ?? "now"}`,
+          metadata: { backfillStartAt, backfillEndAt, requestedFrom: "queue-paperclip-ingestion-backfill" },
+        });
+        const operation = await createOperationIssue(ctx, {
+          companyId,
+          wikiId,
+          spaceSlug,
+          operationType: "backfill",
+          title: scope.rootIssueId ? "Backfill Paperclip root issue wiki history" : "Backfill Paperclip project wiki history",
+          useCheapModelProfile: params.useCheapModelProfile === true,
+          prompt: [
+            "Backfill LLM Wiki distillation was queued from a per-space Paperclip ingestion profile.",
+            scope.projectId ? `Project ID: ${scope.projectId}` : null,
+            scope.rootIssueId ? `Root issue ID: ${scope.rootIssueId}` : null,
+            backfillStartAt ? `Start: ${backfillStartAt}` : null,
+            backfillEndAt ? `End: ${backfillEndAt}` : null,
+            "Process this bounded window through the profile destination space only.",
+          ].filter(Boolean).join("\n"),
+        });
+        queued.push({
+          workItemId: workItem.workItemId,
+          issueId: operation.issue.id,
+          projectId: scope.projectId,
+          rootIssueId: scope.rootIssueId,
+        });
+      }
+      const primary = queued[0];
+      return {
+        status: "queued",
+        wikiId: stringField(params.wikiId) ?? "default",
+        spaceSlug: stringField(params.spaceSlug) ?? "default",
+        workItemId: primary?.workItemId ?? null,
+        issueId: primary?.issueId ?? null,
+        workItems: queued,
+        warnings: [],
+      };
+    });
+
+    ctx.actions.register("ingest-source", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      const wikiId = stringField(params.wikiId);
+      const spaceSlug = stringField(params.spaceSlug);
+      const sourceType = stringField(params.sourceType) ?? "text";
+      const title = stringField(params.title) ?? sourceType.toUpperCase();
+      const contents = typeof params.contents === "string" ? params.contents : "";
+      const url = stringField(params.url);
+      const captured = await captureWikiSource(ctx, {
+        companyId,
+        wikiId,
+        spaceSlug,
+        sourceType,
+        title,
+        url,
+        contents,
+        rawPath: stringField(params.rawPath),
+        metadata: typeof params.metadata === "object" && params.metadata != null ? params.metadata as Record<string, unknown> : null,
+      });
+      const op = await createOperationIssue(ctx, {
+        companyId,
+        wikiId,
+        spaceSlug,
+        operationType: "ingest",
+        title: `Ingest ${sourceType}: ${title}`,
+        prompt: [
+          `Ingest a captured source from raw/${captured.rawPath.replace(/^raw\//, "")}.`,
+          url ? `Source URL: ${url}` : null,
+          "Follow the installed wiki-ingest skill: read the raw file end to end, summarise into wiki/sources/<slug>.md, update related entity/concept/synthesis pages, refresh wiki/index.md, and append wiki/log.md.",
+        ].filter(Boolean).join("\n"),
+      });
+      return { status: "ok", source: captured, operation: op };
+    });
+
+    ctx.actions.register("assemble-paperclip-source-bundle", async (params) => {
+      return assemblePaperclipSourceBundle(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        projectId: stringField(params.projectId),
+        rootIssueId: stringField(params.rootIssueId),
+        maxCharacters: typeof params.maxCharacters === "number" ? params.maxCharacters : null,
+        maxCharactersPerSource: typeof params.maxCharactersPerSource === "number" ? params.maxCharactersPerSource : null,
+        backfillStartAt: stringField(params.backfillStartAt),
+        backfillEndAt: stringField(params.backfillEndAt),
+        routineRun: params.routineRun === true,
+        includeComments: params.includeComments !== false,
+        includeDocuments: params.includeDocuments !== false,
+      });
+    });
+
+    ctx.actions.register("create-paperclip-distillation-run", async (params) => {
+      return createPaperclipDistillationRun(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        projectId: stringField(params.projectId),
+        rootIssueId: stringField(params.rootIssueId),
+        maxCharacters: typeof params.maxCharacters === "number" ? params.maxCharacters : null,
+        maxCharactersPerSource: typeof params.maxCharactersPerSource === "number" ? params.maxCharactersPerSource : null,
+        backfillStartAt: stringField(params.backfillStartAt),
+        backfillEndAt: stringField(params.backfillEndAt),
+        routineRun: params.routineRun === true,
+        includeComments: params.includeComments !== false,
+        includeDocuments: params.includeDocuments !== false,
+        workItemId: stringField(params.workItemId),
+        operationIssueId: stringField(params.operationIssueId),
+      });
+    });
+
+    ctx.actions.register("record-paperclip-distillation-outcome", async (params) => {
+      const status = stringField(params.status);
+      if (status !== "succeeded" && status !== "failed" && status !== "review_required") {
+        throw new Error("status must be succeeded, failed, or review_required");
+      }
+      const runId = stringField(params.runId);
+      if (!runId) throw new Error("runId is required");
+      return recordPaperclipDistillationOutcome(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        runId,
+        cursorId: stringField(params.cursorId),
+        status,
+        sourceHash: stringField(params.sourceHash),
+        sourceWindowEnd: stringField(params.sourceWindowEnd),
+        warning: stringField(params.warning),
+        costCents: typeof params.costCents === "number" ? params.costCents : null,
+        retryCount: typeof params.retryCount === "number" ? params.retryCount : null,
+      });
+    });
+
+    ctx.actions.register("distill-paperclip-project-page", async (params) => {
+      return distillPaperclipProjectPage(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        projectId: stringField(params.projectId),
+        rootIssueId: stringField(params.rootIssueId),
+        maxCharacters: typeof params.maxCharacters === "number" ? params.maxCharacters : null,
+        maxCharactersPerSource: typeof params.maxCharactersPerSource === "number" ? params.maxCharactersPerSource : null,
+        backfillStartAt: stringField(params.backfillStartAt),
+        backfillEndAt: stringField(params.backfillEndAt),
+        routineRun: params.routineRun === true,
+        includeComments: params.includeComments !== false,
+        includeDocuments: params.includeDocuments !== false,
+        workItemId: stringField(params.workItemId),
+        operationIssueId: stringField(params.operationIssueId),
+        autoApply: params.autoApply === true ? true : params.autoApply === false ? false : undefined,
+        expectedProjectPageHash: stringField(params.expectedProjectPageHash),
+        includeSupportingPages: params.includeSupportingPages !== false,
+      });
+    });
+
+    ctx.actions.register("distill-paperclip-now", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      const spaceSlug = stringField(params.spaceSlug);
+      const projectId = stringField(params.projectId);
+      const rootIssueId = stringField(params.rootIssueId);
+      const idempotencyScope = rootIssueId ? `root:${rootIssueId}` : projectId ? `project:${projectId}` : "company";
+      const workItem = await createPaperclipDistillationWorkItem(ctx, {
+        companyId,
+        wikiId: stringField(params.wikiId),
+        spaceSlug,
+        kind: "manual",
+        projectId,
+        rootIssueId,
+        requestedByIssueId: stringField(params.requestedByIssueId),
+        priority: "medium",
+        idempotencyKey: stringField(params.idempotencyKey) ?? `manual:${idempotencyScope}`,
+        metadata: { requestedFrom: "distill-paperclip-now" },
+      });
+      const operation = await createOperationIssue(ctx, {
+        companyId,
+        wikiId: stringField(params.wikiId),
+        spaceSlug,
+        operationType: "distill",
+        title: rootIssueId
+          ? "Distill Paperclip root issue into wiki"
+          : projectId
+            ? "Distill Paperclip project into wiki"
+            : "Distill Paperclip changes into wiki",
+        useCheapModelProfile: params.useCheapModelProfile === true,
+        prompt: buildManualDistillPrompt({ companyId, projectId, rootIssueId }),
+      });
+      return { status: "queued", workItem, operation };
+    });
+
+    ctx.actions.register("enable-paperclip-distillation-active-projects", async (params) => {
+      return enableActiveProjectDistillation(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        limit: typeof params.limit === "number" ? params.limit : null,
+      });
+    });
+
+    ctx.actions.register("backfill-paperclip-distillation", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      const spaceSlug = stringField(params.spaceSlug);
+      const projectId = stringField(params.projectId);
+      const rootIssueId = stringField(params.rootIssueId);
+      if (!projectId && !rootIssueId) throw new Error("projectId or rootIssueId is required");
+      const backfillStartAt = stringField(params.backfillStartAt);
+      const backfillEndAt = stringField(params.backfillEndAt);
+      const idempotencyScope = rootIssueId ? `root:${rootIssueId}` : `project:${projectId}`;
+      const workItem = await createPaperclipDistillationWorkItem(ctx, {
+        companyId,
+        wikiId: stringField(params.wikiId),
+        spaceSlug,
+        kind: "backfill",
+        projectId,
+        rootIssueId,
+        requestedByIssueId: stringField(params.requestedByIssueId),
+        priority: "low",
+        idempotencyKey: stringField(params.idempotencyKey) ?? `backfill:${idempotencyScope}:${backfillStartAt ?? "begin"}:${backfillEndAt ?? "now"}`,
+        metadata: { backfillStartAt, backfillEndAt, requestedFrom: "backfill-paperclip-distillation" },
+      });
+      const operation = await createOperationIssue(ctx, {
+        companyId,
+        wikiId: stringField(params.wikiId),
+        spaceSlug,
+        operationType: "backfill",
+        title: rootIssueId ? "Backfill Paperclip root issue wiki history" : "Backfill Paperclip project wiki history",
+        useCheapModelProfile: params.useCheapModelProfile === true,
+        prompt: [
+          "Backfill LLM Wiki distillation requested for a bounded Paperclip source window.",
+          projectId ? `Project ID: ${projectId}` : null,
+          rootIssueId ? `Root issue ID: ${rootIssueId}` : null,
+          backfillStartAt ? `Start: ${backfillStartAt}` : null,
+          backfillEndAt ? `End: ${backfillEndAt}` : null,
+          "Do not process whole-company history; stay within the selected project/root issue and date window.",
+        ].filter(Boolean).join("\n"),
+      });
+      const result = await distillPaperclipProjectPage(ctx, {
+        companyId,
+        wikiId: stringField(params.wikiId),
+        spaceSlug,
+        projectId,
+        rootIssueId,
+        maxCharacters: typeof params.maxCharacters === "number" ? params.maxCharacters : null,
+        maxCharactersPerSource: typeof params.maxCharactersPerSource === "number" ? params.maxCharactersPerSource : null,
+        backfillStartAt,
+        backfillEndAt,
+        routineRun: params.routineRun === true,
+        includeComments: params.includeComments !== false,
+        includeDocuments: params.includeDocuments !== false,
+        autoApply: params.autoApply === true ? true : params.autoApply === false ? false : undefined,
+        expectedProjectPageHash: stringField(params.expectedProjectPageHash),
+        includeSupportingPages: params.includeSupportingPages !== false,
+        workItemId: workItem.workItemId,
+        operationIssueId: operation.issue.id,
+      });
+      return { ...result, workItem, operation };
+    });
+
+    ctx.actions.register("create-paperclip-distillation-work-item", async (params) => {
+      const kind = stringField(params.kind);
+      if (
+        kind !== "manual" &&
+        kind !== "retry" &&
+        kind !== "backfill" &&
+        kind !== "priority_override" &&
+        kind !== "review_patch"
+      ) {
+        throw new Error("kind must be manual, retry, backfill, priority_override, or review_patch");
+      }
+      const priority = stringField(params.priority);
+      if (priority && priority !== "critical" && priority !== "high" && priority !== "medium" && priority !== "low") {
+        throw new Error("priority must be critical, high, medium, or low");
+      }
+      return createPaperclipDistillationWorkItem(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        kind,
+        projectId: stringField(params.projectId),
+        rootIssueId: stringField(params.rootIssueId),
+        requestedByIssueId: stringField(params.requestedByIssueId),
+        priority: priority as "critical" | "high" | "medium" | "low" | null,
+        idempotencyKey: stringField(params.idempotencyKey),
+        metadata: typeof params.metadata === "object" && params.metadata != null ? params.metadata as Record<string, unknown> : null,
+      });
+    });
+
+    ctx.actions.register("file-as-page", async (params) => {
+      return fileQueryAnswerAsPage(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        querySessionId: stringField(params.querySessionId),
+        question: stringField(params.question),
+        answer: stringField(params.answer),
+        path: stringField(params.path) ?? "",
+        title: stringField(params.title),
+        contents: stringField(params.contents),
+        expectedHash: stringField(params.expectedHash),
+      });
+    });
+
+    ctx.actions.register("start-query", async (params) => {
+      return startWikiQuerySession(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        question: stringField(params.question) ?? "",
+        title: stringField(params.title),
+      });
+    });
+
+    ctx.actions.register("reset-managed-agent", async (params) => {
+      return resetWikiAgentResource(ctx, readCompanyIdFromParams(params));
+    });
+
+    ctx.actions.register("reset-managed-project", async (params) => {
+      return resetWikiProjectResource(ctx, readCompanyIdFromParams(params));
+    });
+
+    ctx.actions.register("reconcile-managed-agent", async (params) => {
+      return reconcileWikiAgentResource(ctx, readCompanyIdFromParams(params));
+    });
+
+    ctx.actions.register("reconcile-managed-project", async (params) => {
+      return reconcileWikiProjectResource(ctx, readCompanyIdFromParams(params));
+    });
+
+    ctx.actions.register("reconcile-managed-skills", async (params) => {
+      return { managedSkills: await reconcileWikiSkillResources(ctx, readCompanyIdFromParams(params)) };
+    });
+
+    ctx.actions.register("reset-managed-skills", async (params) => {
+      return { managedSkills: await resetWikiSkillResources(ctx, readCompanyIdFromParams(params)) };
+    });
+
+    ctx.actions.register("select-managed-agent", async (params) => {
+      const agentId = stringField(params.agentId);
+      if (!agentId) throw new Error("agentId is required");
+      return selectWikiAgentResource(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        agentId,
+      });
+    });
+
+    ctx.actions.register("select-managed-project", async (params) => {
+      const projectId = stringField(params.projectId);
+      if (!projectId) throw new Error("projectId is required");
+      return selectWikiProjectResource(ctx, {
+        companyId: readCompanyIdFromParams(params),
+        projectId,
+      });
+    });
+
+    ctx.actions.register("reset-managed-routine", async (params) => {
+      return ctx.routines.managed.reset(
+        routineKeyField(params.routineKey),
+        readCompanyIdFromParams(params),
+        routineOverridesFromParams(params),
+      );
+    });
+
+    ctx.actions.register("reconcile-managed-routine", async (params) => {
+      return ctx.routines.managed.reconcile(
+        routineKeyField(params.routineKey),
+        readCompanyIdFromParams(params),
+        routineOverridesFromParams(params),
+      );
+    });
+
+    ctx.actions.register("reconcile-managed-routines", async (params) => {
+      return reconcileWikiRoutineResources(ctx, readCompanyIdFromParams(params));
+    });
+
+    ctx.actions.register("update-managed-routine-status", async (params) => {
+      const status = stringField(params.status);
+      if (!status) throw new Error("status is required");
+      return ctx.routines.managed.update(routineKeyField(params.routineKey), readCompanyIdFromParams(params), {
+        status,
+      });
+    });
+
+    ctx.actions.register("run-managed-routine", async (params) => {
+      return ctx.routines.managed.run(
+        routineKeyField(params.routineKey),
+        readCompanyIdFromParams(params),
+        routineOverridesFromParams(params),
+      );
+    });
+
+    ctx.data.register("pages", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      return listPages(ctx, {
+        companyId,
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        pageType: stringField(params.pageType),
+        includeRaw: params.includeRaw === true || params.includeRaw === "true",
+        limit: typeof params.limit === "number" ? params.limit : null,
+      });
+    });
+
+    ctx.data.register("sources", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      return listSources(ctx, { companyId, wikiId: stringField(params.wikiId), spaceSlug: stringField(params.spaceSlug), limit: typeof params.limit === "number" ? params.limit : null });
+    });
+
+    ctx.data.register("page-content", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      const path = stringField(params.path);
+      if (!path) throw new Error("path is required");
+      return readWikiPage(ctx, { companyId, wikiId: stringField(params.wikiId), spaceSlug: stringField(params.spaceSlug), path });
+    });
+
+    ctx.data.register("template", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      const path = stringField(params.path) ?? "AGENTS.md";
+      return readTemplate(ctx, { companyId, path });
+    });
+
+    ctx.data.register("operations", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      return listOperations(ctx, {
+        companyId,
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        operationType: stringField(params.operationType),
+        status: stringField(params.status),
+        limit: typeof params.limit === "number" ? params.limit : null,
+      });
+    });
+
+    ctx.data.register("distillation-overview", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      return getDistillationOverview(ctx, {
+        companyId,
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        limit: typeof params.limit === "number" ? params.limit : null,
+      });
+    });
+
+    ctx.data.register("distillation-page-provenance", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      const pagePath = stringField(params.pagePath);
+      if (!pagePath) {
+        return { binding: null, runs: [], snapshot: null, cursor: null };
+      }
+      return getDistillationPageProvenance(ctx, {
+        companyId,
+        wikiId: stringField(params.wikiId),
+        spaceSlug: stringField(params.spaceSlug),
+        pagePath,
+      });
+    });
+
+    ctx.data.register("settings", async (params) => {
+      const companyId = readCompanyIdFromParams(params);
+      const folder = await ctx.localFolders.status(companyId, WIKI_ROOT_FOLDER_KEY);
+      const overview = await getOverview(ctx, companyId);
+      const managedRoutines = await Promise.all(
+        WIKI_MAINTENANCE_ROUTINE_KEYS.map((routineKey) => ctx.routines.managed.get(routineKey, companyId)),
+      );
+      const managedRoutinesWithDefaultDrift = managedRoutines.map((routine) =>
+        withManagedRoutineDefaultDrift(
+          routine,
+          ctx.manifest.routines?.find((declaration) => declaration.routineKey === routine.resourceKey),
+        ),
+      );
+      return {
+        folder,
+        spaces: await listSpaces(ctx, { companyId }),
+        managedAgent: overview.managedAgent,
+        managedProject: overview.managedProject,
+        managedSkills: overview.managedSkills,
+        managedRoutine: managedRoutinesWithDefaultDrift[0],
+        managedRoutines: managedRoutinesWithDefaultDrift,
+        distillationPolicy: getDistillationAutoApplyRestriction(),
+        eventIngestion: await getEventIngestionSettings(ctx, companyId),
+        agentOptions: await listWikiAgentOptions(ctx, companyId),
+        projectOptions: await listWikiProjectOptions(ctx, companyId),
+        capabilities: ctx.manifest.capabilities,
+      };
+    });
+  },
+
+  async onApiRequest(input: PluginApiRequestInput) {
+    const ctx = requireContext();
+    if (input.routeKey === "overview") {
+      return { body: await getOverview(ctx, input.companyId) };
+    }
+
+    if (input.routeKey === "bootstrap") {
+      const body = input.body as Record<string, unknown> | null;
+      return {
+        status: 201,
+        body: await bootstrapWikiRoot(ctx, {
+          companyId: input.companyId,
+          path: stringField(body?.path),
+        }),
+      };
+    }
+
+    if (input.routeKey === "spaces") {
+      return {
+        body: await listSpaces(ctx, {
+          companyId: input.companyId,
+          wikiId: stringField(input.query.wikiId),
+        }),
+      };
+    }
+
+    if (input.routeKey === "create-space") {
+      const body = input.body as Record<string, unknown> | null;
+      return {
+        status: 201,
+        body: await createSpace(ctx, {
+          companyId: input.companyId,
+          wikiId: stringField(body?.wikiId),
+          slug: stringField(body?.slug),
+          displayName: stringField(body?.displayName),
+          folderMode: stringField(body?.folderMode) as "managed_subfolder" | "existing_local_folder" | null,
+          accessScope: stringField(body?.accessScope) as "shared" | "personal" | "team" | null,
+          settings: typeof body?.settings === "object" && body.settings != null ? body.settings as Record<string, unknown> : null,
+        }),
+      };
+    }
+
+    if (input.routeKey === "update-space") {
+      const body = input.body as Record<string, unknown> | null;
+      return {
+        body: await updateSpace(ctx, {
+          companyId: input.companyId,
+          wikiId: stringField(body?.wikiId),
+          spaceSlug: input.params.spaceSlug,
+          displayName: stringField(body?.displayName),
+          status: stringField(body?.status) as "active" | "archived" | null,
+          settings: typeof body?.settings === "object" && body.settings != null ? body.settings as Record<string, unknown> : null,
+        }),
+      };
+    }
+
+    if (input.routeKey === "bootstrap-space") {
+      const body = input.body as Record<string, unknown> | null;
+      return {
+        status: 201,
+        body: await bootstrapSpace(ctx, {
+          companyId: input.companyId,
+          wikiId: stringField(body?.wikiId),
+          spaceSlug: input.params.spaceSlug,
+        }),
+      };
+    }
+
+    if (input.routeKey === "archive-space") {
+      const body = input.body as Record<string, unknown> | null;
+      return {
+        body: await archiveSpace(ctx, {
+          companyId: input.companyId,
+          wikiId: stringField(body?.wikiId),
+          spaceSlug: input.params.spaceSlug,
+        }),
+      };
+    }
+
+    if (input.routeKey === "capture-source") {
+      const body = input.body as Record<string, unknown> | null;
+      return {
+        status: 201,
+        body: await captureWikiSource(ctx, {
+          companyId: input.companyId,
+          wikiId: stringField(body?.wikiId),
+          spaceSlug: stringField(body?.spaceSlug),
+          sourceType: stringField(body?.sourceType),
+          title: stringField(body?.title),
+          url: stringField(body?.url),
+          contents: typeof body?.contents === "string" ? body.contents : "",
+          rawPath: stringField(body?.rawPath),
+          metadata: typeof body?.metadata === "object" && body.metadata != null ? body.metadata as Record<string, unknown> : null,
+        }),
+      };
+    }
+
+    if (input.routeKey === "operations") {
+      return {
+        body: await listOperations(ctx, {
+          companyId: input.companyId,
+          wikiId: stringField(input.query.wikiId),
+          spaceSlug: stringField(input.query.spaceSlug),
+          operationType: stringField(input.query.operationType),
+          status: stringField(input.query.status),
+          limit: typeof input.query.limit === "string" ? Number(input.query.limit) : null,
+        }),
+      };
+    }
+
+    if (input.routeKey === "start-query") {
+      const body = input.body as Record<string, unknown> | null;
+      return {
+        status: 201,
+        body: await startWikiQuerySession(ctx, {
+          companyId: input.companyId,
+          wikiId: stringField(body?.wikiId),
+          spaceSlug: stringField(body?.spaceSlug),
+          question: stringField(body?.question) ?? "",
+          title: stringField(body?.title),
+        }),
+      };
+    }
+
+    if (input.routeKey === "file-as-page") {
+      const body = input.body as Record<string, unknown> | null;
+      return {
+        status: 201,
+        body: await fileQueryAnswerAsPage(ctx, {
+          companyId: input.companyId,
+          wikiId: stringField(body?.wikiId),
+          spaceSlug: stringField(body?.spaceSlug),
+          querySessionId: stringField(body?.querySessionId),
+          question: stringField(body?.question),
+          answer: stringField(body?.answer),
+          path: stringField(body?.path) ?? "",
+          title: stringField(body?.title),
+          contents: stringField(body?.contents),
+          expectedHash: stringField(body?.expectedHash),
+        }),
+      };
+    }
+
+    return { status: 404, body: { error: `Unknown LLM Wiki route: ${input.routeKey}` } };
+  },
+
+  async onHealth() {
+    return {
+      status: "ok",
+      message: "LLM Wiki plugin worker is running",
+      details: {
+        surfaces: ["page", "sidebar", "settings", "tools", "database", "local-folder"],
+      },
+    };
+  }
+});
+
+export default plugin;
+runWorker(plugin, import.meta.url);
diff --git a/packages/plugins/plugin-llm-wiki/templates/.gitignore b/packages/plugins/plugin-llm-wiki/templates/.gitignore
new file mode 100644
index 00000000..ef42c26d
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/templates/.gitignore
@@ -0,0 +1,3 @@
+.DS_Store
+.obsidian/workspace*
+.obsidian/cache
diff --git a/packages/plugins/plugin-llm-wiki/templates/AGENTS.md b/packages/plugins/plugin-llm-wiki/templates/AGENTS.md
new file mode 100644
index 00000000..3c2aa273
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/templates/AGENTS.md
@@ -0,0 +1,137 @@
+# AGENTS.md — LLM Wiki Schema
+
+You are the maintainer of this personal wiki. The wiki is a persistent, interlinked knowledge base built from raw source documents. You read sources, extract knowledge, and integrate it into evolving wiki pages. The user curates sources, directs analysis, and asks questions; you handle the bookkeeping.
+
+The underlying pattern is described in `IDEA.md` (Karpathy's "LLM Wiki" gist). Read it if you need the philosophy; this file is the operational schema.
+
+## Layout
+
+```
+.
+├── AGENTS.md         # this file — your operating instructions
+├── IDEA.md           # the pattern this wiki follows
+├── raw/              # immutable source documents (you read, never write)
+└── wiki/             # generated, owned by you
+    ├── index.md      # catalog of all pages
+    ├── log.md        # append-only timeline of operations
+    ├── sources/      # one summary page per source
+    ├── projects/     # Paperclip project overviews, standups, decisions, and history
+    │   └── <slug>/
+    │       ├── index.md
+    │       ├── standup.md
+    │       ├── decisions.md
+    │       └── history.md
+    ├── entities/     # people, organizations, products, places
+    ├── concepts/     # ideas, frameworks, definitions
+    └── synthesis/    # cross-cutting analysis, comparisons, theses
+```
+
+The subdirectories under `wiki/` are conventional, not enforced. Add new categories (e.g. `wiki/papers/`) as the domain demands — and update this file when you do.
+
+Paperclip project material lives only under `wiki/projects/<project-slug>/`. Do not create a top-level `projects/` directory.
+
+- `wiki/projects/<project-slug>/standup.md` is the executive-level project standup. It answers where the project stands today, what changed recently, current blockers/risks, and the next concrete actions.
+- `wiki/projects/<project-slug>/index.md` is the durable knowledge page. It explains what the project is, why it exists, decisions made, history, and long-lived context.
+- Keep the two linked. A standup should link to the durable project page, and the durable project page should point at the current standup for live status.
+- Update `standup.md` whenever Paperclip project, issue, plan, comment, blocker, approval, or status history materially changes the project's current state. Do not append endless dated sections; rewrite it as today's concise status.
+- Project writing should be editorial and concept-grouped. Do not dump issue queues, UUIDs, raw metadata, or date-heavy ledgers into project pages. Reference Paperclip tasks with human issue links where useful, but make headings and paragraphs explain the concepts, decisions, completed work, next work, and blockers in plain executive language.
+
+## Page conventions
+
+- **Filename:** kebab-case, `.md`. Treat filenames as stable; do not rename without updating backlinks.
+- **Frontmatter:** YAML at the top of every wiki page.
+  ```yaml
+  ---
+  title: Human-readable title
+  type: source | project | entity | concept | synthesis
+  tags: [tag-a, tag-b]
+  sources: [raw/doc.pdf]    # for source pages and synthesis pages
+  created: YYYY-MM-DD
+  updated: YYYY-MM-DD
+  ---
+  ```
+- **Cross-links:** Obsidian-style `[[wiki/entities/some-page]]` (or `[[some-page]]` when unambiguous). When you mention a concept or entity that has — or should have — its own page, link it.
+- **Citations:** cite the source inline whenever a claim comes from one: `(see [[wiki/sources/some-slug]])`.
+- **Voice:** terse, factual, neutral. The wiki is reference material, not narrative.
+
+## Operations
+
+### Ingest
+
+Triggered when the user drops a file in `raw/` and asks to process it (or just says "ingest").
+
+1. Read the source end to end.
+2. Briefly discuss key takeaways with the user before writing — confirm what to emphasize.
+3. Create `wiki/sources/<slug>.md`: a summary page (~300–800 words) covering the source's main claims, structure, and notable quotes or data.
+4. Update or create relevant pages in `entities/`, `concepts/`, `synthesis/`. A typical ingest touches 5–15 pages.
+5. Add any new pages to `wiki/index.md`.
+6. Append a log entry:
+   ```
+   ## [YYYY-MM-DD] ingest | <source title>
+   - source: raw/<filename>
+   - new pages: [[...]], [[...]]
+   - updated pages: [[...]], [[...]]
+   - notes: <one-line synthesis, contradiction flagged, or open question>
+   ```
+
+When new information contradicts an existing page, do **not** silently overwrite. Flag the contradiction on the page (a `> ⚠ contradicted by [[...]] (YYYY-MM-DD)` callout) and note it in the log.
+
+### Project updates
+
+Triggered when Paperclip project, issue, plan, comment, blocker, or status history is distilled into the wiki.
+
+1. Create or update `wiki/projects/<project-slug>/standup.md` first. Every Paperclip project represented in the wiki must have one. Keep stable sections for executive readout, what changed, decisions, blockers/risks, next actions, and links.
+2. Create or update `wiki/projects/<project-slug>/index.md` as the durable project overview. Keep stable sections for overview, current direction, workstreams, decisions, open risks/blockers, and references.
+3. Use `wiki/projects/<project-slug>/decisions.md` for accepted/rejected plans, architectural decisions, approval outcomes, and reversals when a project has enough decision history to warrant a separate page.
+4. Use `wiki/projects/<project-slug>/history.md` for compact narrative history of meaningful project movement. Group by phase or concept; do not mirror every issue comment.
+5. Always cite Paperclip source material with readable links to issue identifiers, document keys, issue documents, approvals, and raw/source pages. Do not put UUIDs in prose unless the UUID itself is the subject.
+6. Update `wiki/index.md` under Projects and append a `project` log entry to `wiki/log.md`.
+
+### Query
+
+The user asks a question. You:
+
+1. Read `wiki/index.md` to find candidate pages.
+2. Read those pages; follow links as needed.
+3. Answer with citations back to wiki pages, and ultimately to raw sources.
+4. If the answer is substantial (a comparison, analysis, new synthesis), offer to file it under `wiki/synthesis/` so the work compounds rather than disappearing into chat history.
+
+If the wiki lacks what the question needs, say so plainly and suggest sources to ingest or web searches to run.
+
+### Lint
+
+On request ("lint", "health check"), scan for:
+
+- contradictions across pages
+- claims a newer source has superseded
+- orphan pages (not linked from `index.md` or any other page)
+- concepts mentioned in multiple places but lacking a dedicated page
+- broken `[[wiki-links]]`
+- gaps where a web search or new source would help
+
+Report findings as a checklist and ask the user which to act on.
+
+## index.md format
+
+A catalog organized by category. Each line: `- [[path]] — one-line summary`. Keep it scannable; this is your primary navigation aid before opening pages.
+
+## log.md format
+
+Append new entries to the bottom. Every entry header follows:
+
+```
+## [YYYY-MM-DD] <op> | <subject>
+```
+
+so `grep "^## \[" wiki/log.md | tail -10` always returns recent activity. Operations: `ingest`, `query`, `lint`, `setup`, `refactor`.
+
+## Customization
+
+This schema is intentionally generic. As the wiki's domain becomes clear, evolve it:
+
+- add domain-specific page types and subdirectories
+- adjust frontmatter fields
+- specify preferred output formats for queries (Marp slides, charts, tables)
+- record workflow preferences (one-at-a-time vs batch ingest, level of human supervision)
+
+When you and the user agree on a convention, **write it into this file**. The schema is the wiki's source of truth for how the wiki is built.
diff --git a/packages/plugins/plugin-llm-wiki/templates/IDEA.md b/packages/plugins/plugin-llm-wiki/templates/IDEA.md
new file mode 100644
index 00000000..35ef0712
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/templates/IDEA.md
@@ -0,0 +1,75 @@
+# LLM Wiki
+
+A pattern for building personal knowledge bases using LLMs.
+
+This is an idea file, it is designed to be copy pasted to your own LLM Agent (e.g. OpenAI Codex, Claude Code, OpenCode / Pi, or etc.). Its goal is to communicate the high level idea, but your agent will build out the specifics in collaboration with you.
+
+## The core idea
+
+Most people's experience with LLMs and documents looks like RAG: you upload a collection of files, the LLM retrieves relevant chunks at query time, and generates an answer. This works, but the LLM is rediscovering knowledge from scratch on every question. There's no accumulation. Ask a subtle question that requires synthesizing five documents, and the LLM has to find and piece together the relevant fragments every time. Nothing is built up. NotebookLM, ChatGPT file uploads, and most RAG systems work this way.
+
+The idea here is different. Instead of just retrieving from raw documents at query time, the LLM **incrementally builds and maintains a persistent wiki** — a structured, interlinked collection of markdown files that sits between you and the raw sources. When you add a new source, the LLM doesn't just index it for later retrieval. It reads it, extracts the key information, and integrates it into the existing wiki — updating entity pages, revising topic summaries, noting where new data contradicts old claims, strengthening or challenging the evolving synthesis. The knowledge is compiled once and then *kept current*, not re-derived on every query.
+
+This is the key difference: **the wiki is a persistent, compounding artifact.** The cross-references are already there. The contradictions have already been flagged. The synthesis already reflects everything you've read. The wiki keeps getting richer with every source you add and every question you ask.
+
+You never (or rarely) write the wiki yourself — the LLM writes and maintains all of it. You're in charge of sourcing, exploration, and asking the right questions. The LLM does all the grunt work — the summarizing, cross-referencing, filing, and bookkeeping that makes a knowledge base actually useful over time. In practice, I have the LLM agent open on one side and Obsidian open on the other. The LLM makes edits based on our conversation, and I browse the results in real time — following links, checking the graph view, reading the updated pages. Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase.
+
+This can apply to a lot of different contexts. A few examples:
+
+- **Personal**: tracking your own goals, health, psychology, self-improvement — filing journal entries, articles, podcast notes, and building up a structured picture of yourself over time.
+- **Research**: going deep on a topic over weeks or months — reading papers, articles, reports, and incrementally building a comprehensive wiki with an evolving thesis.
+- **Reading a book**: filing each chapter as you go, building out pages for characters, themes, plot threads, and how they connect. By the end you have a rich companion wiki. Think of fan wikis like [Tolkien Gateway](https://tolkiengateway.net/wiki/Main_Page) — thousands of interlinked pages covering characters, places, events, languages, built by a community of volunteers over years. You could build something like that personally as you read, with the LLM doing all the cross-referencing and maintenance.
+- **Business/team**: an internal wiki maintained by LLMs, fed by Slack threads, meeting transcripts, project documents, customer calls. Possibly with humans in the loop reviewing updates. The wiki stays current because the LLM does the maintenance that no one on the team wants to do.
+- **Competitive analysis, due diligence, trip planning, course notes, hobby deep-dives** — anything where you're accumulating knowledge over time and want it organized rather than scattered.
+
+## Architecture
+
+There are three layers:
+
+**Raw sources** — your curated collection of source documents. Articles, papers, images, data files. These are immutable — the LLM reads from them but never modifies them. This is your source of truth.
+
+**The wiki** — a directory of LLM-generated markdown files. Summaries, entity pages, concept pages, comparisons, an overview, a synthesis. The LLM owns this layer entirely. It creates pages, updates them when new sources arrive, maintains cross-references, and keeps everything consistent. You read it; the LLM writes it.
+
+**The schema** — a document (e.g. AGENTS.md for Paperclip agents) that tells the LLM how the wiki is structured, what the conventions are, and what workflows to follow when ingesting sources, answering questions, or maintaining the wiki. This is the key configuration file — it's what makes the LLM a disciplined wiki maintainer rather than a generic chatbot. You and the LLM co-evolve this over time as you figure out what works for your domain.
+
+## Operations
+
+**Ingest.** You drop a new source into the raw collection and tell the LLM to process it. An example flow: the LLM reads the source, discusses key takeaways with you, writes a summary page in the wiki, updates the index, updates relevant entity and concept pages across the wiki, and appends an entry to the log. A single source might touch 10-15 wiki pages. Personally I prefer to ingest sources one at a time and stay involved — I read the summaries, check the updates, and guide the LLM on what to emphasize. But you could also batch-ingest many sources at once with less supervision. It's up to you to develop the workflow that fits your style and document it in the schema for future sessions.
+
+**Query.** You ask questions against the wiki. The LLM searches for relevant pages, reads them, and synthesizes an answer with citations. Answers can take different forms depending on the question — a markdown page, a comparison table, a slide deck (Marp), a chart (matplotlib), a canvas. The important insight: **good answers can be filed back into the wiki as new pages.** A comparison you asked for, an analysis, a connection you discovered — these are valuable and shouldn't disappear into chat history. This way your explorations compound in the knowledge base just like ingested sources do.
+
+**Lint.** Periodically, ask the LLM to health-check the wiki. Look for: contradictions between pages, stale claims that newer sources have superseded, orphan pages with no inbound links, important concepts mentioned but lacking their own page, missing cross-references, data gaps that could be filled with a web search. The LLM is good at suggesting new questions to investigate and new sources to look for. This keeps the wiki healthy as it grows.
+
+## Indexing and logging
+
+Two special files help the LLM (and you) navigate the wiki as it grows. They serve different purposes:
+
+**index.md** is content-oriented. It's a catalog of everything in the wiki — each page listed with a link, a one-line summary, and optionally metadata like date or source count. Organized by category (entities, concepts, sources, etc.). The LLM updates it on every ingest. When answering a query, the LLM reads the index first to find relevant pages, then drills into them. This works surprisingly well at moderate scale (~100 sources, ~hundreds of pages) and avoids the need for embedding-based RAG infrastructure.
+
+**log.md** is chronological. It's an append-only record of what happened and when — ingests, queries, lint passes. A useful tip: if each entry starts with a consistent prefix (e.g. `## [2026-04-02] ingest | Article Title`), the log becomes parseable with simple unix tools — `grep "^## \[" log.md | tail -5` gives you the last 5 entries. The log gives you a timeline of the wiki's evolution and helps the LLM understand what's been done recently.
+
+## Optional: CLI tools
+
+At some point you may want to build small tools that help the LLM operate on the wiki more efficiently. A search engine over the wiki pages is the most obvious one — at small scale the index file is enough, but as the wiki grows you want proper search. [qmd](https://github.com/tobi/qmd) is a good option: it's a local search engine for markdown files with hybrid BM25/vector search and LLM re-ranking, all on-device. It has both a CLI (so the LLM can shell out to it) and an MCP server (so the LLM can use it as a native tool). You could also build something simpler yourself — the LLM can help you vibe-code a naive search script as the need arises.
+
+## Tips and tricks
+
+- **Obsidian Web Clipper** is a browser extension that converts web articles to markdown. Very useful for quickly getting sources into your raw collection.
+- **Download images locally.** In Obsidian Settings → Files and links, set "Attachment folder path" to a fixed directory (e.g. `raw/assets/`). Then in Settings → Hotkeys, search for "Download" to find "Download attachments for current file" and bind it to a hotkey (e.g. Ctrl+Shift+D). After clipping an article, hit the hotkey and all images get downloaded to local disk. This is optional but useful — it lets the LLM view and reference images directly instead of relying on URLs that may break. Note that LLMs can't natively read markdown with inline images in one pass — the workaround is to have the LLM read the text first, then view some or all of the referenced images separately to gain additional context. It's a bit clunky but works well enough.
+- **Obsidian's graph view** is the best way to see the shape of your wiki — what's connected to what, which pages are hubs, which are orphans.
+- **Marp** is a markdown-based slide deck format. Obsidian has a plugin for it. Useful for generating presentations directly from wiki content.
+- **Dataview** is an Obsidian plugin that runs queries over page frontmatter. If your LLM adds YAML frontmatter to wiki pages (tags, dates, source counts), Dataview can generate dynamic tables and lists.
+- The wiki is just a git repo of markdown files. You get version history, branching, and collaboration for free.
+
+## Why this works
+
+The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Updating cross-references, keeping summaries current, noting when new data contradicts old claims, maintaining consistency across dozens of pages. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass. The wiki stays maintained because the cost of maintenance is near zero.
+
+The human's job is to curate sources, direct the analysis, ask good questions, and think about what it all means. The LLM's job is everything else.
+
+The idea is related in spirit to Vannevar Bush's Memex (1945) — a personal, curated knowledge store with associative trails between documents. Bush's vision was closer to this than to what the web became: private, actively curated, with the connections between documents as valuable as the documents themselves. The part he couldn't solve was who does the maintenance. The LLM handles that.
+
+
+## Note
+
+This document is intentionally abstract. It describes the idea, not a specific implementation. The exact directory structure, the schema conventions, the page formats, the tooling — all of that will depend on your domain, your preferences, and your LLM of choice. Everything mentioned above is optional and modular — pick what's useful, ignore what isn't. For example: your sources might be text-only, so you don't need image handling at all. Your wiki might be small enough that the index file is all you need, no search engine required. You might not care about slide decks and just want markdown pages. You might want a completely different set of output formats. The right way to use this is to share it with your LLM agent and work together to instantiate a version that fits your needs. The document's only job is to communicate the pattern. Your LLM can figure out the rest.
diff --git a/packages/plugins/plugin-llm-wiki/templates/raw/.gitkeep b/packages/plugins/plugin-llm-wiki/templates/raw/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/templates/wiki/concepts/.gitkeep b/packages/plugins/plugin-llm-wiki/templates/wiki/concepts/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/templates/wiki/entities/.gitkeep b/packages/plugins/plugin-llm-wiki/templates/wiki/entities/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/templates/wiki/index.md b/packages/plugins/plugin-llm-wiki/templates/wiki/index.md
new file mode 100644
index 00000000..54f1f8a3
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/templates/wiki/index.md
@@ -0,0 +1,23 @@
+# Index
+
+Catalog of durable wiki pages and linked project standups. Updated on every ingest or Paperclip distill.
+
+## Sources
+
+_(none yet)_
+
+## Projects
+
+_(none yet)_
+
+## Entities
+
+_(none yet)_
+
+## Concepts
+
+_(none yet)_
+
+## Synthesis
+
+_(none yet)_
diff --git a/packages/plugins/plugin-llm-wiki/templates/wiki/log.md b/packages/plugins/plugin-llm-wiki/templates/wiki/log.md
new file mode 100644
index 00000000..6b101ab1
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/templates/wiki/log.md
@@ -0,0 +1,10 @@
+# Log
+
+Append-only chronological record of wiki operations.
+
+## [2026-05-03] setup | wiki initialized
+- created `AGENTS.md` (schema)
+- created `raw/` for source documents
+- created `wiki/` skeleton: `index.md`, `log.md`, `sources/`, `projects/`, `entities/`, `concepts/`, `synthesis/`
+- created `wiki/projects/` for Paperclip project overviews and standups
+- pattern reference: `IDEA.md` (Karpathy "LLM Wiki" gist, https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
diff --git a/packages/plugins/plugin-llm-wiki/templates/wiki/projects/.gitkeep b/packages/plugins/plugin-llm-wiki/templates/wiki/projects/.gitkeep
new file mode 100644
index 00000000..8b137891
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/templates/wiki/projects/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/packages/plugins/plugin-llm-wiki/templates/wiki/sources/.gitkeep b/packages/plugins/plugin-llm-wiki/templates/wiki/sources/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/templates/wiki/synthesis/.gitkeep b/packages/plugins/plugin-llm-wiki/templates/wiki/synthesis/.gitkeep
new file mode 100644
index 00000000..e69de29b
diff --git a/packages/plugins/plugin-llm-wiki/tests/issue-attachments.spec.ts b/packages/plugins/plugin-llm-wiki/tests/issue-attachments.spec.ts
new file mode 100644
index 00000000..776348fa
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/tests/issue-attachments.spec.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { readIngestOperationIssueId, uploadIssueAttachmentFile } from "../src/ui/issue-attachments.js";
+
+describe("LLM Wiki issue attachment uploads", () => {
+  it("reads the ingest operation issue id from the action result", () => {
+    expect(readIngestOperationIssueId({
+      operation: {
+        issue: {
+          id: "issue-1",
+        },
+      },
+    })).toBe("issue-1");
+  });
+
+  it("rejects an ingest result that cannot identify the created issue", () => {
+    expect(() => readIngestOperationIssueId({ operation: { issue: null } }))
+      .toThrow("did not return an issue id");
+  });
+
+  it("uploads the original file to the created ingest task", async () => {
+    const file = new File(["hello"], "source notes.md", { type: "text/markdown" });
+    const calls: Array<{ input: string; init: RequestInit }> = [];
+    const fetchImpl = async (input: string, init: RequestInit) => {
+      calls.push({ input, init });
+      return new Response(JSON.stringify({ id: "attachment-1" }), {
+        status: 201,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+
+    await expect(uploadIssueAttachmentFile({
+      companyId: "company 1",
+      issueId: "issue/1",
+      file,
+      fetchImpl,
+    })).resolves.toEqual({ id: "attachment-1" });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.input).toBe("/api/companies/company%201/issues/issue%2F1/attachments");
+    expect(calls[0]?.init.method).toBe("POST");
+    expect(calls[0]?.init.credentials).toBe("include");
+    const body = calls[0]?.init.body;
+    expect(body).toBeInstanceOf(FormData);
+    expect((body as FormData).get("file")).toBe(file);
+  });
+
+  it("surfaces server upload errors", async () => {
+    const fetchImpl = async () => new Response(JSON.stringify({ error: "Attachment exceeds 10 bytes" }), {
+      status: 422,
+      headers: { "Content-Type": "application/json" },
+    });
+
+    await expect(uploadIssueAttachmentFile({
+      companyId: "company-1",
+      issueId: "issue-1",
+      file: new File(["hello"], "source.txt"),
+      fetchImpl,
+    })).rejects.toThrow("Attachment exceeds 10 bytes");
+  });
+});
diff --git a/packages/plugins/plugin-llm-wiki/tests/plugin.spec.ts b/packages/plugins/plugin-llm-wiki/tests/plugin.spec.ts
new file mode 100644
index 00000000..69dbf26b
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/tests/plugin.spec.ts
@@ -0,0 +1,3746 @@
+import { readFileSync } from "node:fs";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createTestHarness } from "@paperclipai/plugin-sdk/testing";
+import type { Agent, Issue, PluginManagedRoutineResolution, Project } from "@paperclipai/plugin-sdk";
+import manifest, {
+  CURSOR_WINDOW_ROUTINE_KEY,
+  INDEX_REFRESH_ROUTINE_KEY,
+  NIGHTLY_LINT_ROUTINE_KEY,
+  PAPERCLIP_DISTILL_SKILL_KEY,
+  WIKI_MAINTAINER_AGENT_KEY,
+  WIKI_MAINTAINER_SKILL_CANONICAL_KEY,
+  WIKI_MAINTAINER_SKILL_KEY,
+  WIKI_MANAGED_SKILL_CANONICAL_KEYS,
+  WIKI_MANAGED_SKILL_KEYS,
+  WIKI_MAINTENANCE_ROUTINE_KEYS,
+  WIKI_PROJECT_KEY,
+} from "../src/manifest.js";
+import {
+  DEFAULT_AGENT_INSTRUCTION_FILES,
+  DEFAULT_AGENT_INSTRUCTIONS,
+  DEFAULT_IDEA,
+  DEFAULT_INDEX,
+  DEFAULT_LOG,
+  DEFAULT_WIKI_SCHEMA,
+  KARPATHY_LLM_WIKI_GIST_URL,
+  LINT_PROMPT,
+  QUERY_PROMPT,
+} from "../src/templates.js";
+import { SettingsPage, SidebarLink, WikiPage, WikiRouteSidebar } from "../src/ui/index.js";
+import plugin from "../src/worker.js";
+import { OPERATION_ORIGIN_KIND, type WikiSkillResource } from "../src/wiki.js";
+
+const COMPANY_ID = "11111111-1111-4111-8111-111111111111";
+const OTHER_COMPANY_ID = "99999999-9999-4999-8999-999999999999";
+const ORIGINAL_DEPLOYMENT_MODE = process.env.PAPERCLIP_DEPLOYMENT_MODE;
+const ORIGINAL_DEPLOYMENT_EXPOSURE = process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE;
+type TestBridgeGlobal = typeof globalThis & {
+  __paperclipPluginBridge__?: {
+    sdkUi?: Record<string, unknown>;
+  };
+};
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+};
+const DEFAULT_MANAGED_SKILL = {
+  status: "resolved",
+  skillId: "skill-1",
+  resourceKey: WIKI_MAINTAINER_SKILL_KEY,
+  details: {
+    name: "LLM Wiki Maintainer",
+    key: WIKI_MAINTAINER_SKILL_CANONICAL_KEY,
+    description: "Use the LLM Wiki plugin tools to maintain a cited local company wiki.",
+  },
+  skill: {
+    id: "skill-1",
+    name: "LLM Wiki Maintainer",
+    key: WIKI_MAINTAINER_SKILL_CANONICAL_KEY,
+    description: "Use the LLM Wiki plugin tools to maintain a cited local company wiki.",
+  },
+};
+const DEFAULT_MANAGED_SKILLS = WIKI_MANAGED_SKILL_KEYS.map((skillKey, index) => ({
+  status: "resolved",
+  skillId: `skill-${index + 1}`,
+  resourceKey: skillKey,
+  details: skillKey === WIKI_MAINTAINER_SKILL_KEY
+    ? DEFAULT_MANAGED_SKILL.details
+    : {
+        name: skillKey.split("-").map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join(" "),
+        key: WIKI_MANAGED_SKILL_CANONICAL_KEYS[index],
+        description: null,
+      },
+  skill: skillKey === WIKI_MAINTAINER_SKILL_KEY
+    ? DEFAULT_MANAGED_SKILL.skill
+    : {
+        id: `skill-${index + 1}`,
+        name: skillKey.split("-").map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join(" "),
+        key: WIKI_MANAGED_SKILL_CANONICAL_KEYS[index],
+        description: null,
+      },
+}));
+
+let mockPathname = "/PAP/wiki";
+let mockSearch = "";
+let mockAutoSelectFile: string | null = null;
+let mockNavigatedTo: string | null = null;
+let mockOverviewFolder: Record<string, unknown> | null = null;
+let mockSettingsFolder: Record<string, unknown> | null = null;
+let mockSettingsManagedAgent: Record<string, unknown> | null = null;
+let mockSettingsManagedRoutines: Array<Record<string, unknown>> = [];
+let mockSettingsManagedSkills: Array<Record<string, unknown>> = [];
+let mockDistillationOverviewData: Record<string, unknown> | null = null;
+let mockPageContentsByPath: Record<string, string> = {};
+let mockPageMetadataByPath: Record<string, {
+  backlinks?: string[];
+  sourceRefs?: Array<Record<string, unknown> | string>;
+}> = {};
+
+beforeEach(() => {
+  if (ORIGINAL_DEPLOYMENT_MODE == null) {
+    delete process.env.PAPERCLIP_DEPLOYMENT_MODE;
+  } else {
+    process.env.PAPERCLIP_DEPLOYMENT_MODE = ORIGINAL_DEPLOYMENT_MODE;
+  }
+  if (ORIGINAL_DEPLOYMENT_EXPOSURE == null) {
+    delete process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE;
+  } else {
+    process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE = ORIGINAL_DEPLOYMENT_EXPOSURE;
+  }
+  mockPathname = "/PAP/wiki";
+  mockSearch = "";
+  mockAutoSelectFile = null;
+  mockNavigatedTo = null;
+  mockOverviewFolder = null;
+  mockSettingsFolder = null;
+  mockSettingsManagedAgent = null;
+  mockSettingsManagedRoutines = [];
+  mockSettingsManagedSkills = [];
+  mockDistillationOverviewData = null;
+  mockPageContentsByPath = {};
+  mockPageMetadataByPath = {};
+  (globalThis as TestBridgeGlobal).__paperclipPluginBridge__ = {
+    sdkUi: {
+      usePluginData: (key: string, params?: Record<string, unknown>) => {
+        if (key === "overview") {
+          return {
+            data: {
+              status: "ok",
+              checkedAt: new Date().toISOString(),
+              wikiId: "default",
+              folder: mockOverviewFolder ?? {
+                configured: true,
+                path: "/tmp/company-wiki",
+                realPath: "/tmp/company-wiki",
+                access: "readWrite",
+                readable: true,
+                writable: true,
+                requiredDirectories: [],
+                requiredFiles: [],
+                missingDirectories: [],
+                missingFiles: [],
+                healthy: true,
+                problems: [],
+                checkedAt: new Date().toISOString(),
+              },
+              managedAgent: { status: "resolved", source: "managed", agentId: "agent-1", resourceKey: "wiki-maintainer", details: { name: "Wiki Maintainer", status: "idle", adapterType: "claude_local", icon: "book-open", urlKey: "wiki-maintainer" } },
+              managedProject: { status: "resolved", projectId: "project-1", details: { name: "LLM Wiki", status: "in_progress" } },
+              managedSkills: DEFAULT_MANAGED_SKILLS,
+              operationCount: 0,
+              eventIngestion: {
+                enabled: false,
+                sources: { issues: false, comments: false, documents: false },
+                wikiId: "default",
+                maxCharacters: 12000,
+              },
+              capabilities: [],
+              prompts: { query: QUERY_PROMPT, lint: LINT_PROMPT },
+            },
+            loading: false,
+            error: null,
+            refresh: () => undefined,
+          };
+        }
+        if (key === "spaces") {
+          return {
+            data: {
+              spaces: [
+                {
+                  id: "space-default",
+                  companyId: COMPANY_ID,
+                  wikiId: "default",
+                  slug: "default",
+                  displayName: "default",
+                  spaceType: "managed",
+                  folderMode: "managed_subfolder",
+                  rootFolderKey: "wiki-root",
+                  pathPrefix: null,
+                  configuredRootPath: null,
+                  accessScope: "shared",
+                  ownerUserId: null,
+                  ownerAgentId: null,
+                  teamKey: null,
+                  settings: {},
+                  status: "active",
+                  createdAt: null,
+                  updatedAt: null,
+                },
+              ],
+            },
+            loading: false,
+            error: null,
+            refresh: () => undefined,
+          };
+        }
+        if (key === "pages") {
+          return {
+            data: {
+              pages: [
+                {
+                  path: "wiki/concepts/sidebar-navigation.md",
+                  title: "Sidebar navigation",
+                  pageType: "concepts",
+                  backlinkCount: 0,
+                  sourceCount: 0,
+                  contentHash: "abc123",
+                  updatedAt: new Date().toISOString(),
+                },
+              ],
+              sources: [
+                {
+                  rawPath: "raw/sidebar-notes.md",
+                  title: "Sidebar notes",
+                  sourceType: "text",
+                  url: null,
+                  status: "captured",
+                  createdAt: new Date().toISOString(),
+                },
+              ],
+            },
+            loading: false,
+            error: null,
+            refresh: () => undefined,
+          };
+        }
+        if (key === "settings") {
+          return {
+            data: {
+              status: "ok",
+              checkedAt: new Date().toISOString(),
+              wikiId: "default",
+              folder: mockSettingsFolder ?? {
+                configured: true,
+                path: "/tmp/company-wiki",
+                realPath: "/tmp/company-wiki",
+                access: "readWrite",
+                readable: true,
+                writable: true,
+                requiredDirectories: [],
+                requiredFiles: [],
+                missingDirectories: [],
+                missingFiles: [],
+                healthy: true,
+                problems: [],
+                checkedAt: new Date().toISOString(),
+              },
+              managedAgent: mockSettingsManagedAgent ?? { status: "resolved", source: "managed", agentId: "agent-1", resourceKey: "wiki-maintainer", details: { name: "Wiki Maintainer", status: "idle", adapterType: "claude_local", icon: "book-open", urlKey: "wiki-maintainer" } },
+              managedProject: { status: "resolved", source: "managed", projectId: "project-1", resourceKey: "llm-wiki", details: { name: "LLM Wiki", status: "in_progress" } },
+              managedSkills: mockSettingsManagedSkills.length > 0 ? mockSettingsManagedSkills : DEFAULT_MANAGED_SKILLS,
+              managedRoutines: mockSettingsManagedRoutines,
+              managedRoutine: mockSettingsManagedRoutines[0] ?? null,
+              eventIngestion: {
+                enabled: false,
+                sources: { issues: false, comments: false, documents: false },
+                wikiId: "default",
+                maxCharacters: 12000,
+              },
+              agentOptions: [{ id: "agent-1", name: "Wiki Maintainer", status: "idle", icon: "book-open", urlKey: "wiki-maintainer" }],
+              projectOptions: [{ id: "project-1", name: "LLM Wiki", status: "in_progress", color: "#2563eb" }],
+              capabilities: [],
+            },
+            loading: false,
+            error: null,
+            refresh: () => undefined,
+          };
+        }
+        if (key === "space") {
+          return {
+            data: {
+              id: "space-default",
+              companyId: COMPANY_ID,
+              wikiId: "default",
+              slug: "default",
+              displayName: "default",
+              spaceType: "managed",
+              folderMode: "managed_subfolder",
+              rootFolderKey: "wiki-root",
+              pathPrefix: null,
+              configuredRootPath: null,
+              accessScope: "shared",
+              ownerUserId: null,
+              ownerAgentId: null,
+              teamKey: null,
+              settings: {},
+              status: "active",
+              createdAt: null,
+              updatedAt: null,
+              relativeRoot: "",
+              folder: {
+                configured: true,
+                path: "/tmp/company-wiki",
+                realPath: "/tmp/company-wiki",
+                access: "readWrite",
+                readable: true,
+                writable: true,
+                requiredDirectories: ["raw", "wiki"],
+                requiredFiles: ["AGENTS.md"],
+                missingDirectories: [],
+                missingFiles: [],
+                healthy: true,
+                problems: [],
+                checkedAt: new Date().toISOString(),
+              },
+            },
+            loading: false,
+            error: null,
+            refresh: () => undefined,
+          };
+        }
+        if (key === "distillation-overview") {
+          return {
+            data: mockDistillationOverviewData,
+            loading: false,
+            error: null,
+            refresh: () => undefined,
+          };
+        }
+        if (key === "page-content") {
+          const path = typeof params?.path === "string" ? params.path : "wiki/index.md";
+          const contents = mockPageContentsByPath[path] ?? (path === "AGENTS.md"
+            ? DEFAULT_AGENT_INSTRUCTIONS
+            : path === "IDEA.md"
+              ? DEFAULT_IDEA
+              : `# ${path}\n`);
+          return {
+            data: {
+              wikiId: "default",
+              path,
+              contents,
+              title: path === "AGENTS.md" ? "LLM Wiki Maintainer" : path.replace(/\.md$/, ""),
+              pageType: path === "AGENTS.md" ? null : "index",
+              backlinks: mockPageMetadataByPath[path]?.backlinks ?? [],
+              sourceRefs: mockPageMetadataByPath[path]?.sourceRefs ?? [],
+              updatedAt: null,
+              hash: "abc123",
+            },
+            loading: false,
+            error: null,
+            refresh: () => undefined,
+          };
+        }
+        return { data: null, loading: false, error: null, refresh: () => undefined };
+      },
+      usePluginAction: () => async () => ({}),
+      usePluginToast: () => () => null,
+      useHostNavigation: () => ({
+        resolveHref: (to: string) => `/PAP${to.startsWith("/") ? to : `/${to}`}`,
+        navigate: (to: string) => { mockNavigatedTo = to; },
+        linkProps: (to: string) => ({
+          href: `/PAP${to.startsWith("/") ? to : `/${to}`}`,
+          onClick: () => undefined,
+        }),
+      }),
+      useHostLocation: () => ({
+        pathname: mockPathname,
+        search: mockSearch,
+        hash: "",
+      }),
+      FileTree: (props: {
+        nodes: Array<{ name: string; path: string; kind: string; children?: Array<{ name: string; path: string; kind: string }> }>;
+        selectedFile?: string | null;
+        ariaLabel?: string;
+        wrapLabels?: boolean;
+        fileBadges?: Record<string, unknown>;
+        onSelectFile?: (path: string) => void;
+      }) => {
+        if (mockAutoSelectFile) props.onSelectFile?.(mockAutoSelectFile);
+        return createElement(
+          "div",
+          {
+            role: "tree",
+            "aria-label": props.ariaLabel,
+            "data-selected-file": props.selectedFile ?? "",
+            "data-wrap-labels": String(props.wrapLabels),
+            "data-has-file-badges": String(Boolean(props.fileBadges && Object.keys(props.fileBadges).length > 0)),
+          },
+          props.nodes.map((node) => createElement("div", { key: node.path }, node.name)),
+        );
+      },
+      IssuesList: (props: {
+        projectId?: string | null;
+        filters?: { originKindPrefix?: string };
+      }) => createElement(
+        "div",
+        { "data-testid": "plugin-issues-list" },
+        `Issues table · ${props.projectId ?? "no-project"} · ${props.filters?.originKindPrefix ?? "no-origin-filter"}`,
+      ),
+      MarkdownBlock: ({ content }: { content: string }) => createElement("div", { "data-testid": "markdown-block" }, content),
+      MarkdownEditor: ({ value, onChange }: { value: string; onChange: (value: string) => void }) => createElement("textarea", {
+        "data-testid": "markdown-editor",
+        value,
+        onChange: (event: { currentTarget: { value: string } }) => onChange(event.currentTarget.value),
+      }),
+      AssigneePicker: (props: {
+        value: string;
+        placeholder?: string;
+        onChange: (value: string, selection: { assigneeAgentId: string | null; assigneeUserId: string | null }) => void;
+      }) => createElement(
+        "button",
+        {
+          type: "button",
+          "data-testid": "assignee-picker",
+          onClick: () => props.onChange("agent:agent-1", { assigneeAgentId: "agent-1", assigneeUserId: null }),
+        },
+        props.value === "agent:agent-1" ? "Wiki Maintainer" : (props.placeholder ?? "Select assignee"),
+      ),
+      ProjectPicker: (props: {
+        value: string;
+        placeholder?: string;
+        onChange: (projectId: string) => void;
+      }) => createElement(
+        "button",
+        {
+          type: "button",
+          "data-testid": "project-picker",
+          onClick: () => props.onChange("project-1"),
+        },
+        props.value === "project-1" ? "LLM Wiki" : (props.placeholder ?? "Project"),
+      ),
+      ManagedRoutinesList: (props: {
+        routines: Array<{
+          key: string;
+          title: string;
+          href?: string | null;
+          projectId?: string | null;
+          assigneeAgentId?: string | null;
+          defaultDrift?: { changedFields: string[] } | null;
+        }>;
+        agents?: Array<{ id: string; name: string }>;
+        projects?: Array<{ id: string; name: string }>;
+        onReset?: (routine: { key: string; title: string }) => void;
+      }) => createElement(
+        "div",
+        { "data-testid": "managed-routines-list" },
+        props.routines.map((routine) => {
+          const agent = props.agents?.find((item) => item.id === routine.assigneeAgentId);
+          const project = props.projects?.find((item) => item.id === routine.projectId);
+          return createElement(
+            "div",
+            { key: routine.key },
+            createElement("span", null, routine.title),
+            createElement("button", null, "Run now"),
+            createElement("button", { role: "switch" }, "On"),
+            routine.href ? createElement("a", { href: `/PAP${routine.href}` }, "Configure") : null,
+            routine.defaultDrift?.changedFields.length
+              ? createElement("span", null, `Plugin defaults changed: ${routine.defaultDrift.changedFields.join(", ")}`)
+              : null,
+            routine.defaultDrift?.changedFields.length && props.onReset
+              ? createElement("button", null, "Reset")
+              : null,
+            createElement("span", null, `${project?.name ?? "No project"} · ${agent?.name ?? "No default agent"}`),
+          );
+        }),
+      ),
+    },
+  };
+});
+
+afterEach(() => {
+  if (ORIGINAL_DEPLOYMENT_MODE == null) {
+    delete process.env.PAPERCLIP_DEPLOYMENT_MODE;
+  } else {
+    process.env.PAPERCLIP_DEPLOYMENT_MODE = ORIGINAL_DEPLOYMENT_MODE;
+  }
+  if (ORIGINAL_DEPLOYMENT_EXPOSURE == null) {
+    delete process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE;
+  } else {
+    process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE = ORIGINAL_DEPLOYMENT_EXPOSURE;
+  }
+  delete (globalThis as TestBridgeGlobal).__paperclipPluginBridge__;
+});
+
+function wikiMaintainerAgent(): Agent {
+  const now = new Date();
+  return {
+    id: "22222222-2222-4222-8222-222222222222",
+    companyId: COMPANY_ID,
+    name: "Wiki Maintainer",
+    urlKey: "wiki-maintainer",
+    role: "general",
+    title: "LLM Wiki Maintainer",
+    icon: "book-open",
+    status: "idle",
+    reportsTo: null,
+    capabilities: "Maintains the wiki",
+    adapterType: "claude_local",
+    adapterConfig: {},
+    runtimeConfig: {},
+    budgetMonthlyCents: 0,
+    spentMonthlyCents: 0,
+    pauseReason: null,
+    pausedAt: null,
+    permissions: { canCreateAgents: false },
+    lastHeartbeatAt: null,
+    metadata: {
+      paperclipManagedResource: {
+        pluginKey: manifest.id,
+        resourceKind: "agent",
+        resourceKey: "wiki-maintainer",
+      },
+    },
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function existingAgent(): Agent {
+  return {
+    ...wikiMaintainerAgent(),
+    id: "44444444-4444-4444-8444-444444444444",
+    name: "Existing Knowledge Agent",
+    urlKey: "existing-knowledge-agent",
+    title: "Knowledge Agent",
+    metadata: {},
+  };
+}
+
+function existingProject(): Project {
+  const now = new Date();
+  return {
+    id: "55555555-5555-4555-8555-555555555555",
+    companyId: COMPANY_ID,
+    urlKey: "existing-wiki-project",
+    goalId: null,
+    goalIds: [],
+    goals: [],
+    name: "Existing Wiki Project",
+    description: "Existing project selected for wiki operations.",
+    status: "in_progress",
+    leadAgentId: null,
+    targetDate: null,
+    color: "#0f766e",
+    env: null,
+    pauseReason: null,
+    pausedAt: null,
+    executionWorkspacePolicy: null,
+    codebase: {
+      workspaceId: null,
+      repoUrl: null,
+      repoRef: null,
+      defaultRef: null,
+      repoName: null,
+      localFolder: null,
+      managedFolder: "/tmp/existing-wiki-project",
+      effectiveLocalFolder: "/tmp/existing-wiki-project",
+      origin: "managed_checkout",
+    },
+    workspaces: [],
+    primaryWorkspace: null,
+    managedByPlugin: null,
+    archivedAt: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function paperclipIssue(overrides: Partial<Issue> = {}): Issue {
+  const now = new Date();
+  return {
+    id: "66666666-6666-4666-8666-666666666666",
+    companyId: COMPANY_ID,
+    projectId: null,
+    projectWorkspaceId: null,
+    goalId: null,
+    parentId: null,
+    title: "Design event ingestion controls",
+    description: "Decide which Paperclip issues, comments, and documents can be ingested into the wiki.",
+    status: "todo",
+    workMode: "standard",
+    priority: "medium",
+    assigneeAgentId: null,
+    assigneeUserId: null,
+    checkoutRunId: null,
+    executionRunId: null,
+    executionAgentNameKey: null,
+    executionLockedAt: null,
+    createdByAgentId: null,
+    createdByUserId: null,
+    issueNumber: 3204,
+    identifier: "PAP-3204",
+    originId: null,
+    originRunId: null,
+    originFingerprint: null,
+    requestDepth: 0,
+    billingCode: null,
+    assigneeAdapterOverrides: null,
+    executionPolicy: null,
+    executionState: null,
+    executionWorkspaceId: null,
+    executionWorkspacePreference: null,
+    executionWorkspaceSettings: null,
+    startedAt: null,
+    completedAt: null,
+    cancelledAt: null,
+    hiddenAt: null,
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+function wikiSpaceRow(space: Record<string, unknown>) {
+  return {
+    id: space.id,
+    company_id: space.companyId ?? COMPANY_ID,
+    wiki_id: space.wikiId ?? "default",
+    slug: space.slug,
+    display_name: space.displayName,
+    space_type: space.spaceType ?? "local_folder",
+    folder_mode: space.folderMode ?? "managed_subfolder",
+    root_folder_key: space.rootFolderKey ?? "wiki-root",
+    path_prefix: space.pathPrefix ?? `spaces/${space.slug}`,
+    configured_root_path: space.configuredRootPath ?? null,
+    access_scope: space.accessScope ?? "shared",
+    owner_user_id: space.ownerUserId ?? null,
+    owner_agent_id: space.ownerAgentId ?? null,
+    team_key: space.teamKey ?? null,
+    settings: space.settings ?? {},
+    status: space.status ?? "active",
+    created_at: space.createdAt ?? null,
+    updated_at: space.updatedAt ?? null,
+  };
+}
+
+function defaultWikiSpaceRow() {
+  return wikiSpaceRow({
+    id: "77777777-7777-4777-8777-7777777777d0",
+    companyId: COMPANY_ID,
+    wikiId: "default",
+    slug: "default",
+    displayName: "default",
+    pathPrefix: null,
+    accessScope: "shared",
+    settings: {},
+  });
+}
+
+function mockPersistedWikiSpace(harness: ReturnType<typeof createTestHarness>, space: Record<string, unknown>) {
+  const row = wikiSpaceRow(space);
+  const originalQuery = harness.ctx.db.query.bind(harness.ctx.db);
+  harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+    if (sql.includes("wiki_spaces") && params?.[2] === row.slug) {
+      return [row] as T[];
+    }
+    if (sql.includes("wiki_spaces") && sql.includes("ORDER BY CASE WHEN slug = 'default'")) {
+      return [defaultWikiSpaceRow(), row] as T[];
+    }
+    return originalQuery<T>(sql, params);
+  };
+}
+
+describe("LLM Wiki plugin scaffold", () => {
+  it("declares standalone plugin surfaces without core wiki coupling", () => {
+    expect(manifest.id).toBe("paperclipai.plugin-llm-wiki");
+    expect(manifest.entrypoints.worker).toBe("./dist/worker.js");
+    expect(manifest.entrypoints.ui).toBe("./dist/ui");
+    expect(manifest.database?.namespaceSlug).toBe("llm_wiki");
+    expect(manifest.localFolders?.[0]?.requiredDirectories).toContain("wiki/projects");
+    expect(manifest.localFolders?.[0]?.requiredDirectories).not.toContain("projects");
+    expect(manifest.localFolders?.[0]?.requiredFiles).toEqual([
+      "AGENTS.md",
+      "IDEA.md",
+      "wiki/index.md",
+      "wiki/log.md",
+    ]);
+    expect(manifest.agents?.[0]?.agentKey).toBe("wiki-maintainer");
+    expect(manifest.agents?.[0]?.adapterType).toBe("claude_local");
+    expect(manifest.agents?.[0]?.adapterConfig).toMatchObject({
+      dangerouslySkipPermissions: false,
+      dangerouslyBypassApprovalsAndSandbox: false,
+      sandbox: true,
+    });
+    expect(manifest.agents?.[0]?.instructions?.entryFile).toBe("AGENTS.md");
+    expect(manifest.agents?.[0]?.instructions?.content).toContain("You are the maintainer of this personal wiki");
+    expect(manifest.agents?.[0]?.instructions?.files?.["AGENTS.md"]).toContain("{{localFolders.wiki-root.path}}");
+    expect(manifest.agents?.[0]?.instructions?.assetPath).toBe("agents/wiki-maintainer");
+    expect(manifest.projects?.[0]?.projectKey).toBe("llm-wiki");
+    expect(manifest.routines?.map((routine) => routine.routineKey)).toEqual([
+      CURSOR_WINDOW_ROUTINE_KEY,
+      NIGHTLY_LINT_ROUTINE_KEY,
+      INDEX_REFRESH_ROUTINE_KEY,
+    ]);
+    expect(manifest.routines).toEqual(
+      WIKI_MAINTENANCE_ROUTINE_KEYS.map((routineKey) => expect.objectContaining({
+        routineKey,
+        assigneeRef: { resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY },
+        projectRef: { resourceKind: "project", resourceKey: WIKI_PROJECT_KEY },
+        concurrencyPolicy: "skip_if_active",
+        catchUpPolicy: "skip_missed",
+        issueTemplate: expect.objectContaining({
+          surfaceVisibility: "plugin_operation",
+          billingCode: expect.stringMatching(/^plugin-llm-wiki:/),
+        }),
+      })),
+    );
+    for (const routine of manifest.routines ?? []) {
+      expect(routine.description).toContain("Run procedure:");
+      expect(routine.description).toContain("Target space: default (slug: default)");
+      expect(routine.description).toContain("spaceSlug `default`");
+      expect(routine.description).toContain("AGENTS.md");
+      expect(routine.description).toContain("wiki/log.md");
+    }
+    expect(manifest.tools?.map((tool) => tool.name)).toEqual([
+      "wiki_search",
+      "wiki_read_page",
+      "wiki_write_page",
+      "wiki_propose_patch",
+      "wiki_list_sources",
+      "wiki_read_source",
+      "wiki_append_log",
+      "wiki_update_index",
+      "wiki_list_backlinks",
+      "wiki_list_pages",
+    ]);
+    expect(manifest.ui?.slots?.map((slot) => slot.type)).toEqual([
+      "sidebar",
+      "page",
+      "routeSidebar",
+    ]);
+    expect(manifest.capabilities).not.toContain("instance.settings.register");
+    expect(manifest.instanceConfigSchema).toBeUndefined();
+    const routeSidebarSlot = manifest.ui?.slots?.find((slot) => slot.type === "routeSidebar");
+    expect(routeSidebarSlot).toMatchObject({
+      id: "wiki-route-sidebar",
+      exportName: "WikiRouteSidebar",
+      routePath: "wiki",
+    });
+    expect(packageJson.dependencies).toBeUndefined();
+    expect(packageJson.devDependencies?.react).toBeUndefined();
+    expect(packageJson.devDependencies?.["react-dom"]).toBeDefined();
+    expect(packageJson.devDependencies?.["@types/react-dom"]).toBeDefined();
+    expect(packageJson.peerDependencies?.react).toBe(">=18");
+  });
+
+  it("renders a host-aligned sidebar link with an open-book icon", () => {
+    const markup = renderToStaticMarkup(createElement(SidebarLink, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain('href="/PAP/wiki"');
+    expect(markup).toContain("gap-2.5 px-3 py-2 text-[13px] font-medium");
+    expect(markup).toContain("hover:bg-accent/50 hover:text-foreground");
+    expect(markup).toContain("<svg");
+    expect(markup).toContain("M12 7v14");
+    expect(markup).not.toContain("Wiki plugin");
+    expect(markup).not.toContain("border-radius:999");
+    expect(markup).not.toContain("📖");
+  });
+
+  it("ships Karpathy-pattern schema and workflow prompts by default", () => {
+    expect(DEFAULT_WIKI_SCHEMA).toContain("You are the maintainer of this personal wiki");
+    expect(DEFAULT_WIKI_SCHEMA).toContain("raw/");
+    expect(DEFAULT_WIKI_SCHEMA).toContain("wiki/projects/<project-slug>/standup.md");
+    expect(DEFAULT_WIKI_SCHEMA).toContain("wiki/projects/<project-slug>/index.md");
+    expect(DEFAULT_WIKI_SCHEMA).toContain("Do not create a top-level `projects/` directory");
+    expect(DEFAULT_WIKI_SCHEMA).not.toContain("\n├── projects/");
+    expect(DEFAULT_WIKI_SCHEMA).toContain("wiki/");
+    expect(DEFAULT_WIKI_SCHEMA).toContain("AGENTS.md");
+    expect(DEFAULT_IDEA).toContain("persistent, compounding artifact");
+    expect(DEFAULT_AGENT_INSTRUCTIONS).toContain("You are the maintainer of this personal wiki");
+    expect(DEFAULT_AGENT_INSTRUCTIONS).toContain("ingest, query, lint, index, or maintenance work");
+    expect(DEFAULT_AGENT_INSTRUCTIONS).toContain("dedicated LLM Wiki skill installed on this agent");
+    expect(DEFAULT_AGENT_INSTRUCTIONS).not.toContain("skills/<name>/SKILL.md");
+    expect(DEFAULT_AGENT_INSTRUCTION_FILES["skills/wiki-ingest/SKILL.md"]).toBeUndefined();
+    expect(manifest.skills?.map((skill) => skill.skillKey)).toEqual([...WIKI_MANAGED_SKILL_KEYS]);
+    expect(manifest.agents?.[0]?.adapterConfig?.paperclipSkillSync).toEqual({
+      desiredSkills: WIKI_MANAGED_SKILL_CANONICAL_KEYS,
+    });
+    expect(QUERY_PROMPT).toContain("wiki-query skill");
+    expect(QUERY_PROMPT).not.toContain("skills/wiki-query/SKILL.md");
+    expect(QUERY_PROMPT).toContain("filed back into wiki/");
+    expect(LINT_PROMPT).toContain("wiki-lint skill");
+    expect(LINT_PROMPT).not.toContain("skills/wiki-lint/SKILL.md");
+    expect(LINT_PROMPT).toContain("severity");
+  });
+
+  it("renders the route-scoped Wiki sidebar with tool actions, page navigation, and a back link", () => {
+    const markup = renderToStaticMarkup(createElement(WikiRouteSidebar, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain('href="/PAP/dashboard"');
+    expect(markup).toContain("PAP");
+    expect(markup).toContain('href="/PAP/wiki/query"');
+    expect(markup).not.toContain('href="/PAP/wiki/lint"');
+    expect(markup).toContain('href="/PAP/wiki/history"');
+    expect(markup).toContain('href="/PAP/wiki/settings"');
+    expect(markup).not.toContain('href="/PAP/wiki/operations"');
+    // Add Content reuses the legacy /wiki/ingest route so deep links still work.
+    expect(markup).toContain('href="/PAP/wiki/ingest"');
+    expect(markup).toContain('aria-label="Wiki primary"');
+    expect(markup).toContain('aria-label="Wiki secondary"');
+    for (const label of ["Ask", "Add Content", "History", "Settings", "Shared Spaces", "default", "raw", "wiki", "AGENTS.md", "IDEA.md"]) {
+      expect(markup).toContain(label);
+    }
+    expect(markup).not.toContain(">Lint</span>");
+    expect(markup).not.toContain(">Ingest</span>");
+    expect(markup).not.toContain(">Operations</span>");
+    expect(markup).not.toContain('text-sm font-bold text-foreground">Wiki');
+    expect(markup).not.toContain("Browse");
+    expect(markup).not.toContain(">Query<");
+    expect(markup).toContain('role="tree"');
+    expect(markup).toContain('data-selected-file=""');
+    expect(markup).toContain('data-wrap-labels="false"');
+    expect(markup).toContain('data-has-file-badges="false"');
+  });
+
+  it("routes legacy Wiki operations URLs to the History issue table", () => {
+    mockPathname = "/PAP/wiki/operations";
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Issues table · project-1 · plugin:paperclipai.plugin-llm-wiki:operation");
+    expect(markup).not.toContain("Recent runs");
+    expect(markup).not.toContain(">Operations</h2>");
+  });
+
+  it("loads AGENTS.md from the Wiki page and exposes an edit affordance", () => {
+    mockPathname = "/PAP/wiki/page/templates/AGENTS.md";
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("AGENTS");
+    expect(markup).toContain(">AGENTS.md</h1>");
+    expect(markup).not.toContain(">LLM Wiki Maintainer</h1>");
+    expect(markup).toContain("You are the maintainer of this personal wiki");
+    expect(markup).toContain("wiki-root `AGENTS.md`");
+    expect(markup).toContain("Edit page");
+    expect(markup).toContain("Updated —");
+    expect(markup).not.toContain("0 backlinks");
+    expect(markup).not.toContain("0 sources");
+    expect(markup).not.toContain("abc123");
+    expect(markup).not.toContain("+ Ingest");
+    expect(markup).not.toContain("Folder healthy");
+  });
+
+  it("does not render page footer sources and backlinks", () => {
+    mockPathname = "/PAP/wiki/page/wiki/projects/control-plane/index.md";
+    mockPageContentsByPath["wiki/projects/control-plane/index.md"] = "# Control plane\n\nCurrent project state.";
+    mockPageMetadataByPath["wiki/projects/control-plane/index.md"] = {
+      backlinks: ["wiki/backlinks/hidden-footer-link.md"],
+      sourceRefs: [{ kind: "issue", issueIdentifier: "PAP-FOOTER-1" }],
+    };
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Current project state.");
+    expect(markup).not.toContain(">Sources</");
+    expect(markup).not.toContain(">Backlinks</");
+    expect(markup).not.toContain("PAP-FOOTER-1");
+    expect(markup).not.toContain("hidden-footer-link");
+  });
+
+  it("renders YAML frontmatter as foldable properties without duplicating title", () => {
+    mockPathname = "/PAP/wiki/page/wiki/concepts/sidebar-navigation.md";
+    mockPageContentsByPath["wiki/concepts/sidebar-navigation.md"] = `---
+title: Sidebar navigation
+type: concept
+tags: [paperclip, wiki]
+sources:
+  - raw/sidebar-notes.md
+created: 2026-05-04
+updated: 2026-05-04
+---
+# Sidebar navigation
+
+Route sidebar state stays attached to the selected wiki page.
+`;
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("<summary");
+    expect(markup).toContain("Properties");
+    expect(markup).toContain(">type</dt>");
+    expect(markup).toContain("concept");
+    expect(markup).toContain(">tags</dt>");
+    expect(markup).toContain("paperclip");
+    expect(markup).toContain("wiki");
+    expect(markup).toContain(">sources</dt>");
+    expect(markup).toContain("raw/sidebar-notes.md");
+    expect(markup).toContain("Route sidebar state");
+    expect(markup).not.toContain("title: Sidebar navigation");
+    expect(markup).not.toContain("title</dt>");
+    expect(markup).not.toContain("---");
+  });
+
+  it("renders a foldable on-this-page pane from wiki page headings", () => {
+    mockPathname = "/PAP/wiki/page/wiki/concepts/sidebar-navigation.md";
+    mockPageContentsByPath["wiki/concepts/sidebar-navigation.md"] = `# Sidebar navigation
+
+## Why it matters
+
+Route sidebar state stays attached to the selected wiki page.
+
+### Deep link behavior
+
+Wiki links preserve normal browser navigation.
+
+\`\`\`md
+## Ignored code heading
+\`\`\`
+
+## Why it matters
+
+Duplicate headings receive stable suffixes.
+`;
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain('aria-label="On this page"');
+    expect(markup).toContain('aria-expanded="true"');
+    expect(markup).toContain('aria-current="location"');
+    expect(markup).toContain('href="#why-it-matters"');
+    expect(markup).toContain('href="#deep-link-behavior"');
+    expect(markup).toContain('href="#why-it-matters-2"');
+    expect(markup).not.toContain('href="#ignored-code-heading"');
+    const tocMarkup = markup.slice(
+      markup.indexOf('aria-label="On this page"'),
+      markup.indexOf("</aside>", markup.indexOf('aria-label="On this page"')),
+    );
+    expect(tocMarkup).toContain("position:sticky");
+    expect(tocMarkup).toContain("top:88px");
+    expect(tocMarkup).not.toContain("background:color-mix");
+    expect(tocMarkup).not.toContain("border-radius");
+  });
+
+  it("shows folder repair instead of reading pages when the wiki root is stale", () => {
+    mockPathname = "/PAP/wiki/page/AGENTS.md";
+    mockOverviewFolder = {
+      configured: true,
+      path: "/tmp/deleted-wiki-root",
+      realPath: null,
+      access: "readWrite",
+      readable: false,
+      writable: false,
+      requiredDirectories: ["raw", "wiki"],
+      requiredFiles: ["AGENTS.md"],
+      missingDirectories: ["raw", "wiki"],
+      missingFiles: ["AGENTS.md"],
+      healthy: false,
+      problems: [
+        { code: "missing", message: "Configured local folder cannot be inspected.", path: "/tmp/deleted-wiki-root" },
+      ],
+      checkedAt: new Date().toISOString(),
+    };
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Repair wiki root folder");
+    expect(markup).toContain("/tmp/deleted-wiki-root");
+    expect(markup).toContain("Configured local folder cannot be inspected.");
+    expect(markup).toContain("Repair &amp; bootstrap");
+    expect(markup).not.toContain("Failed to read AGENTS.md");
+    expect(markup).not.toContain(">AGENTS.md</h1>");
+  });
+
+  it("serializes root template pages as regular path segments", () => {
+    mockAutoSelectFile = "AGENTS.md";
+    renderToStaticMarkup(createElement(WikiRouteSidebar, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(mockNavigatedTo).toBe("/wiki/page/AGENTS.md");
+  });
+
+  it("highlights Settings for legacy lint links after lint moved under Settings", () => {
+    mockPathname = "/PAP/wiki/lint";
+    const markup = renderToStaticMarkup(createElement(WikiRouteSidebar, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).not.toContain('href="/PAP/wiki/lint"');
+    const settingsAnchor = markup.match(/<a[^>]*href="\/PAP\/wiki\/settings"[^>]*>/);
+    expect(settingsAnchor?.[0]).toContain('aria-current="page"');
+    expect(settingsAnchor?.[0]).toContain("text-foreground");
+    expect(settingsAnchor?.[0]).not.toContain("bg-accent");
+    const askAnchor = markup.match(/<a[^>]*href="\/PAP\/wiki\/query"[^>]*>/);
+    expect(askAnchor?.[0]).not.toContain('aria-current="page"');
+  });
+
+  it("renders the maintainer settings without plugin metadata or inline AGENTS.md editing", () => {
+    mockPathname = "/PAP/wiki/settings/maintainer";
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Wiki Maintainer");
+    expect(markup).toContain("Adapter: claude local");
+    expect(markup).toContain("Maintainer");
+    expect(markup).toContain("Repair");
+    expect(markup).toContain("Reset to defaults");
+    expect(markup).not.toContain("Provided maintainer");
+    expect(markup).not.toContain("Managed by LLM Wiki");
+    expect(markup).not.toContain("Suggested default");
+    expect(markup).not.toContain("AGENT INSTRUCTIONS");
+    expect(markup).not.toContain("Stable key");
+    expect(markup).not.toContain("Plugin managed default");
+  });
+
+  it("recommends approval when the wiki maintainer is pending board approval", () => {
+    mockPathname = "/PAP/wiki/settings/maintainer";
+    mockSettingsManagedAgent = {
+      status: "created",
+      source: "managed",
+      agentId: "agent-1",
+      resourceKey: "wiki-maintainer",
+      details: { name: "Wiki Maintainer", status: "pending_approval", adapterType: "claude_local", icon: "book-open", urlKey: "wiki-maintainer" },
+    };
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("pending approval");
+    expect(markup).toContain("Approve the agent");
+    expect(markup).toContain("Adapter: claude local");
+  });
+
+  it("renders root settings as a compact health checklist with the shared path picker", () => {
+    mockPathname = "/PAP/wiki/settings";
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain(">Setup</");
+    expect(markup).toContain("Base Folder");
+    expect(markup).toContain("Managed Agents");
+    expect(markup).toContain("Managed Skills");
+    expect(markup).toContain("Managed Projects");
+    expect(markup).toContain("Managed Routines");
+    expect(markup.indexOf(">Managed Agents</h2>")).toBeLessThan(markup.indexOf(">Managed Skills</h2>"));
+    expect(markup.indexOf(">Managed Skills</h2>")).toBeLessThan(markup.indexOf(">Managed Projects</h2>"));
+    expect(markup.indexOf(">Managed Projects</h2>")).toBeLessThan(markup.indexOf(">Managed Routines</h2>"));
+    expect(markup).toContain("Adapter: claude local");
+    expect(markup).toContain("Status: in progress");
+    expect(markup).toContain("Wiki root health checklist");
+    expect(markup).toContain("Health check");
+    expect(markup).toContain("Wiki agents health checklist");
+    expect(markup).toContain("Wiki routines health checklist");
+    expect(markup).toContain("Wiki skills health checklist");
+    expect(markup).toContain("Wiki projects health checklist");
+    const routineChecklistStart = markup.indexOf('aria-label="Wiki routines health checklist"');
+    const routineChecklist = markup.slice(routineChecklistStart);
+    expect(routineChecklist).toContain("left:8px");
+    expect(routineChecklist).toContain("background:oklch(0.38 0.09 145)");
+    expect(routineChecklist).toContain("Process LLM Wiki updates");
+    expect(routineChecklist).toContain("Run LLM Wiki lint");
+    expect(routineChecklist).toContain("Refresh LLM Wiki index");
+    expect(routineChecklist).not.toContain("Wiki Maintainer");
+    expect(routineChecklist).not.toContain("LLM Wiki project");
+    const skillChecklistStart = markup.indexOf('aria-label="Wiki skills health checklist"');
+    const skillChecklist = markup.slice(skillChecklistStart, markup.indexOf('aria-label="Wiki projects health checklist"'));
+    expect(skillChecklist).toContain("left:8px");
+    expect(skillChecklist).toContain("background:oklch(0.38 0.09 145)");
+    for (const headline of ["Path configured", "Readable", "Writable", "Baseline files", "Wiki folders"]) {
+      expect(markup).toContain(headline);
+    }
+    expect(markup).toContain("Local wiki folder");
+    expect(markup).toContain("Choose");
+    expect(markup).toContain("Apply path");
+    expect(markup).not.toContain("AGENTS.md, IDEA.md");
+    expect(markup).not.toContain("Ready</span>");
+    expect(markup).not.toContain("Needs attention</span>");
+    expect(markup).not.toContain("wiki/sources/");
+    expect(markup).not.toContain("wiki/entities/");
+    expect(markup).not.toContain("Wiki root folder");
+    expect(markup).not.toContain("Provided maintainer");
+    expect(markup).not.toContain(">Project</span>");
+    expect(markup).toContain("Ingestion Settings");
+  });
+
+  it("shows a top-level fix-all banner when settings configuration has errors", () => {
+    mockPathname = "/PAP/wiki/settings";
+    mockSettingsFolder = {
+      configured: true,
+      path: "/tmp/company-wiki",
+      realPath: "/tmp/company-wiki",
+      access: "readWrite",
+      readable: true,
+      writable: true,
+      requiredDirectories: ["raw", "wiki"],
+      requiredFiles: ["AGENTS.md"],
+      missingDirectories: ["raw"],
+      missingFiles: ["AGENTS.md"],
+      healthy: false,
+      problems: [
+        { code: "missing_directory", message: "Required directory is missing.", path: "raw" },
+        { code: "missing_file", message: "Required file is missing.", path: "AGENTS.md" },
+      ],
+      checkedAt: new Date().toISOString(),
+    };
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("configuration errors detected, fix them all?");
+    expect(markup).toContain("Wiki root folder");
+    expect(markup).toContain("Managed routines");
+    expect(markup).toContain("need attention.");
+    expect(markup).toContain("Fix them all");
+    expect(markup.indexOf("configuration errors detected")).toBeLessThan(markup.indexOf(">Base Folder</"));
+  });
+
+  it("shows missing managed skills in setup health with a re-sync action", () => {
+    mockPathname = "/PAP/wiki/settings";
+    mockSettingsManagedSkills = [{
+      status: "missing",
+      skillId: null,
+      resourceKey: WIKI_MAINTAINER_SKILL_KEY,
+      details: {
+        name: "LLM Wiki Maintainer",
+        key: WIKI_MAINTAINER_SKILL_CANONICAL_KEY,
+        description: null,
+      },
+    }];
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Managed Skills");
+    expect(markup).toContain("skill issue(s) need attention");
+    expect(markup).toContain("LLM Wiki Maintainer is not installed in the company skill library.");
+    expect(markup).toContain("Re-sync skills");
+  });
+
+  it("shows managed skill default drift in setup health", () => {
+    mockPathname = "/PAP/wiki/settings";
+    mockSettingsManagedSkills = [{
+      status: "resolved",
+      skillId: "skill-1",
+      resourceKey: WIKI_MAINTAINER_SKILL_KEY,
+      defaultDrift: { changedFiles: ["SKILL.md"] },
+      details: {
+        name: "LLM Wiki Maintainer",
+        key: WIKI_MAINTAINER_SKILL_CANONICAL_KEY,
+        description: null,
+      },
+    }];
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("skill issue(s) need attention");
+    expect(markup).toContain("LLM Wiki Maintainer differs from the plugin default: SKILL.md.");
+    expect(markup).toContain("Re-sync skills");
+  });
+
+  it("renders host settings directly as the Setup page without an extra plugin heading", () => {
+    const markup = renderToStaticMarkup(createElement(SettingsPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain(">Setup</h1>");
+    expect(markup).toContain("Base Folder");
+    expect(markup).not.toContain("LLM Wiki Settings");
+    expect(markup).not.toContain("These settings live inside the plugin");
+  });
+
+  it("renders project settings as a project picker without managed-resource metadata", () => {
+    mockPathname = "/PAP/wiki/settings/project";
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Use existing project");
+    expect(markup).toContain("LLM Wiki");
+    expect(markup).toContain("Save project");
+    expect(markup).toContain("Open project");
+    expect(markup).toContain("Repair / reconcile");
+    expect(markup).toContain("Reset to plugin defaults");
+    expect(markup).not.toContain("Managed by LLM Wiki");
+    expect(markup).not.toContain("Operations project binding");
+    expect(markup).not.toContain("Stable key");
+    expect(markup).not.toContain("Resolved project");
+    expect(markup).toContain("Status: in progress");
+    expect(markup).not.toContain("Plugin managed default");
+  });
+
+  it("renders space settings with health line styling and disabled access controls", () => {
+    mockPathname = "/PAP/wiki/settings/spaces/default";
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Space folder health checklist");
+    expect(markup).toContain("left:8px");
+    expect(markup).toContain("background:oklch(0.38 0.09 145)");
+    expect(markup).toContain("Folder readable");
+    expect(markup).toContain("raw/ present");
+    expect(markup).toContain("Access");
+    expect(markup).toContain("Coming soon");
+    expect(markup).not.toContain("Future enforcement");
+    expect(markup).not.toContain("stored only");
+    expect(markup).not.toContain("Permissions are stored but not enforced");
+  });
+
+  it("renders distillation settings with assigned-agent model selection and cheap path without budget controls", () => {
+    mockPathname = "/PAP/wiki/settings/distillation";
+    mockDistillationOverviewData = {
+      counts: { cursors: 1, runningRuns: 0, failedRuns24h: 0, reviewRequired: 0 },
+      cursors: [{
+        id: "cursor-1",
+        projectId: "project-1",
+        rootIssueId: null,
+        projectName: "Existing Wiki Project",
+        rootIssueIdentifier: null,
+        sourceScope: "project",
+        scopeKey: "project-1",
+      }],
+      runs: [],
+    };
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Agent execution");
+    expect(markup).toContain("Assigned maintainer");
+    expect(markup).toContain("Wiki Maintainer · claude local");
+    expect(markup).toContain("Cheap path");
+    expect(markup).toContain("assigneeAdapterOverrides.modelProfile = cheap");
+    expect(markup).toContain("All sections — apply when source hash matches and confidence");
+    expect(markup).not.toContain("Per-task budget");
+    expect(markup).not.toContain("Project total budget");
+    expect(markup).not.toContain("/task");
+    expect(markup).not.toContain("Model lanes");
+    expect(markup).not.toContain("Claude Haiku");
+    expect(markup).not.toContain("Daily plugin cap");
+    expect(markup).not.toContain("Monthly plugin cap");
+  });
+
+  it("renders managed routines as normal routine rows with run, toggle, and configure controls", () => {
+    mockPathname = "/PAP/wiki/settings/routines";
+    mockSettingsManagedRoutines = [{
+      status: "resolved",
+      routineId: "routine-1",
+      resourceKey: "nightly-wiki-lint",
+      routine: {
+        id: "routine-1",
+        title: "Run LLM Wiki lint",
+        status: "active",
+        assigneeAgentId: "agent-1",
+        projectId: "project-1",
+        lastTriggeredAt: "2026-05-03T12:00:00Z",
+        managedByPlugin: { pluginDisplayName: "LLM Wiki", resourceKey: "nightly-wiki-lint" },
+      },
+      details: { cronExpression: "0 3 * * *" },
+    }];
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Run LLM Wiki lint");
+    expect(markup).toContain("Run now");
+    expect(markup).toContain("Configure");
+    expect(markup).toContain("role=\"switch\"");
+    expect(markup).toContain("LLM Wiki · Wiki Maintainer");
+    expect(markup).toContain("href=\"/PAP/routines/routine-1\"");
+  });
+
+  it("alerts when managed routine defaults changed and offers a reset path", () => {
+    mockPathname = "/PAP/wiki/settings/routines";
+    mockSettingsManagedRoutines = [{
+      status: "resolved",
+      routineId: "routine-1",
+      resourceKey: "nightly-wiki-lint",
+      defaultDrift: {
+        changedFields: ["description"],
+        defaultTitle: "Run LLM Wiki lint",
+        defaultDescription: "Updated instructions",
+      },
+      routine: {
+        id: "routine-1",
+        title: "Run LLM Wiki lint",
+        status: "active",
+        assigneeAgentId: "agent-1",
+        projectId: "project-1",
+        managedByPlugin: { pluginDisplayName: "LLM Wiki", resourceKey: "nightly-wiki-lint" },
+      },
+      details: { cronExpression: "0 3 * * *" },
+    }];
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Routine defaults changed");
+    expect(markup).toContain("Plugin defaults changed: description");
+    expect(markup).toContain(">Reset</button>");
+  });
+
+  it("shows managed agent instruction drift in the setup health check", () => {
+    mockPathname = "/PAP/wiki/settings";
+    mockSettingsManagedAgent = {
+      status: "resolved",
+      source: "managed",
+      agentId: "agent-1",
+      resourceKey: "wiki-maintainer",
+      defaultDrift: { entryFile: "AGENTS.md", changedFiles: ["AGENTS.md"] },
+      details: { name: "Wiki Maintainer", status: "idle", adapterType: "claude_local", icon: "book-open", urlKey: "wiki-maintainer" },
+    };
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Wiki Maintainer instructions differ from the plugin default: AGENTS.md.");
+    expect(markup).toContain("Wiki Maintainer instruction defaults changed: AGENTS.md");
+  });
+
+  it("shows one routine repair warning instead of per-routine reconcile controls", () => {
+    mockPathname = "/PAP/wiki/settings/routines";
+    mockSettingsManagedRoutines = [{
+      status: "resolved",
+      routineId: "routine-1",
+      resourceKey: "nightly-wiki-lint",
+      routine: {
+        id: "routine-1",
+        title: "Run LLM Wiki lint",
+        status: "active",
+        assigneeAgentId: "other-agent",
+        projectId: "project-1",
+        managedByPlugin: { pluginDisplayName: "LLM Wiki", resourceKey: "nightly-wiki-lint" },
+      },
+      details: { cronExpression: "0 3 * * *" },
+    }];
+
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Routine setup needs repair");
+    expect(markup).toContain("Fix routines");
+    expect(markup).toContain("not assigned to the Wiki Maintainer");
+    expect(markup).not.toContain("Plugin-managed routine defaults can be reconciled from here");
+    expect(markup).not.toContain(">Reconcile</button>");
+    expect(markup).not.toContain(">Reset</button>");
+  });
+
+  it("renders legacy lint routes inside the Wiki settings section", () => {
+    mockPathname = "/PAP/wiki/lint";
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("Run lint now");
+    expect(markup).toContain("Recent lint runs");
+    expect(markup).toContain("LLM Wiki settings sections");
+  });
+
+  it("does not expose IDEA.md pattern editing as a settings section", () => {
+    mockPathname = "/PAP/wiki/settings";
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("LLM Wiki settings sections");
+    expect(markup).not.toContain(">Pattern</span>");
+    expect(markup).not.toContain("Pattern · IDEA.md");
+    expect(markup).not.toContain("IDEA.md skeleton reference");
+  });
+
+  it("does not expose plugin capabilities as a settings section", () => {
+    mockPathname = "/PAP/wiki/settings";
+    const markup = renderToStaticMarkup(createElement(WikiPage, {
+      context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+    } as never));
+
+    expect(markup).toContain("LLM Wiki settings sections");
+    expect(markup).not.toContain("Plugin capabilities");
+    expect(markup).not.toContain("api.routes.register");
+  });
+
+  it("reconciles managed maintenance routines through stable agent and project refs", async () => {
+    const harness = createTestHarness({ manifest });
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+
+    const missing = await harness.performAction<PluginManagedRoutineResolution>("reconcile-managed-routine", {
+      companyId: COMPANY_ID,
+      routineKey: NIGHTLY_LINT_ROUTINE_KEY,
+    });
+    expect(missing.status).toBe("missing_refs");
+    expect(missing.missingRefs).toEqual([
+      expect.objectContaining({ resourceKind: "agent", resourceKey: WIKI_MAINTAINER_AGENT_KEY }),
+      expect.objectContaining({ resourceKind: "project", resourceKey: WIKI_PROJECT_KEY }),
+    ]);
+
+    await harness.performAction("bootstrap-root", { companyId: COMPANY_ID, path: "/tmp/company-wiki" });
+    const reconciled = await Promise.all(
+      WIKI_MAINTENANCE_ROUTINE_KEYS.map((routineKey) =>
+        harness.performAction<PluginManagedRoutineResolution>("reconcile-managed-routine", {
+          companyId: COMPANY_ID,
+          routineKey,
+        })),
+    );
+
+    expect(reconciled.map((routine) => routine.resourceKey)).toEqual([...WIKI_MAINTENANCE_ROUTINE_KEYS]);
+    expect(reconciled).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          resourceKey: NIGHTLY_LINT_ROUTINE_KEY,
+          routine: expect.objectContaining({
+            projectId: expect.any(String),
+            assigneeAgentId: expect.any(String),
+            managedByPlugin: expect.objectContaining({
+              defaultsJson: expect.objectContaining({
+                issueTemplate: expect.objectContaining({ surfaceVisibility: "plugin_operation" }),
+              }),
+            }),
+          }),
+        }),
+        expect.objectContaining({ resourceKey: INDEX_REFRESH_ROUTINE_KEY, routineId: expect.any(String) }),
+      ]),
+    );
+  });
+
+  it("requires an explicit managed routine key for single-routine actions", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+
+    await expect(harness.performAction("reconcile-managed-routine", {
+      companyId: COMPANY_ID,
+    })).rejects.toThrow("routineKey is required");
+  });
+
+  it("repairs all managed maintenance routines through one action", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+    await harness.performAction("bootstrap-root", { companyId: COMPANY_ID, path: "/tmp/company-wiki" });
+
+    const repaired = await harness.performAction<{
+      managedRoutines: PluginManagedRoutineResolution[];
+    }>("reconcile-managed-routines", { companyId: COMPANY_ID });
+
+    expect(repaired.managedRoutines).toHaveLength(WIKI_MAINTENANCE_ROUTINE_KEYS.length);
+    expect(repaired.managedRoutines.map((routine) => routine.resourceKey)).toEqual([...WIKI_MAINTENANCE_ROUTINE_KEYS]);
+    for (const routine of repaired.managedRoutines) {
+      expect(routine.routine).toEqual(expect.objectContaining({
+        assigneeAgentId: expect.any(String),
+        projectId: expect.any(String),
+      }));
+      expect(routine.missingRefs).toEqual([]);
+    }
+  });
+
+  it("installs and resets managed company skills through setup actions", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+
+    const before = await harness.getData<{ managedSkills: WikiSkillResource[] }>("settings", {
+      companyId: COMPANY_ID,
+    });
+    expect(before.managedSkills.map((skill) => skill.resourceKey)).toEqual([...WIKI_MANAGED_SKILL_KEYS]);
+    expect(before.managedSkills[0]).toMatchObject({
+      status: "missing",
+      skillId: null,
+    });
+
+    const repaired = await harness.performAction<{
+      managedSkills: WikiSkillResource[];
+    }>("reconcile-managed-skills", { companyId: COMPANY_ID });
+    expect(repaired.managedSkills).toHaveLength(WIKI_MANAGED_SKILL_KEYS.length);
+    expect(repaired.managedSkills[0]).toMatchObject({
+      status: "created",
+      skillId: expect.any(String),
+      resourceKey: WIKI_MAINTAINER_SKILL_KEY,
+      details: {
+        name: "LLM Wiki Maintainer",
+        key: WIKI_MAINTAINER_SKILL_CANONICAL_KEY,
+      },
+    });
+
+    const resolved = await harness.getData<{ managedSkills: WikiSkillResource[] }>("settings", {
+      companyId: COMPANY_ID,
+    });
+    expect(resolved.managedSkills[0]).toMatchObject({
+      status: "resolved",
+      resourceKey: WIKI_MAINTAINER_SKILL_KEY,
+      details: { key: WIKI_MAINTAINER_SKILL_CANONICAL_KEY },
+    });
+
+    const reset = await harness.performAction<{
+      managedSkills: WikiSkillResource[];
+    }>("reset-managed-skills", { companyId: COMPANY_ID });
+    expect(reset.managedSkills[0]).toMatchObject({
+      status: "reset",
+      skillId: expect.any(String),
+      resourceKey: WIKI_MAINTAINER_SKILL_KEY,
+    });
+  });
+
+  it("registers worker data, actions, and tools", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+
+    const overview = await harness.getData<{ status: string; operationCount: number; eventIngestion: { enabled: boolean } }>("overview", {
+      companyId: COMPANY_ID,
+    });
+    expect(overview.status).toBe("ok");
+    expect(overview.operationCount).toBe(0);
+    expect(overview.eventIngestion.enabled).toBe(false);
+
+    const pages = await harness.executeTool<{ content?: string }>("wiki_list_pages", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+    });
+    expect(pages.content).toBe("No pages indexed yet.");
+  });
+
+  it("filters stale page and raw source rows out of browse data", async () => {
+    const harness = createTestHarness({ manifest });
+    const files = new Map<string, string>([
+      ["wiki/concepts/live.md", "# Live Page\n"],
+      ["raw/live-source.md", "# Live Source\n"],
+    ]);
+    const now = new Date().toISOString();
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const contents = files.get(relativePath);
+      if (contents == null) throw new Error(`missing ${relativePath}`);
+      return contents;
+    };
+    harness.ctx.db.query = async <T = Record<string, unknown>>(sql: string, params?: unknown[]) => {
+      harness.dbQueries.push({ sql, params });
+      if (sql.includes("wiki_pages")) {
+        return [
+          {
+            path: "wiki/concepts/live.md",
+            title: "Live Page",
+            page_type: "concepts",
+            backlinks: [],
+            source_refs: [],
+            content_hash: "live",
+            updated_at: now,
+          },
+          {
+            path: "wiki/concepts/stale.md",
+            title: "Stale Page",
+            page_type: "concepts",
+            backlinks: [],
+            source_refs: [],
+            content_hash: "stale",
+            updated_at: now,
+          },
+        ] as T[];
+      }
+      if (sql.includes("wiki_sources")) {
+        return [
+          {
+            raw_path: "raw/missing-source.md",
+            title: "Missing Source",
+            source_type: "text",
+            url: null,
+            status: "captured",
+            created_at: now,
+          },
+          {
+            raw_path: "raw/live-source.md",
+            title: "Live Source",
+            source_type: "text",
+            url: null,
+            status: "captured",
+            created_at: now,
+          },
+        ] as T[];
+      }
+      return [];
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.getData<{
+      pages: Array<{ path: string }>;
+      sources: Array<{ rawPath: string }>;
+    }>("pages", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      includeRaw: true,
+    });
+
+    expect(result.pages.map((page) => page.path)).toEqual(["wiki/concepts/live.md"]);
+    expect(result.sources.map((source) => source.rawPath)).toEqual(["raw/live-source.md"]);
+  });
+
+  it("includes local wiki files in browse data before metadata is indexed", async () => {
+    const harness = createTestHarness({ manifest });
+    const modifiedAt = new Date().toISOString();
+    harness.ctx.localFolders.list = async (_companyId, folderKey, options) => ({
+      folderKey,
+      relativePath: options?.relativePath ?? null,
+      truncated: false,
+      entries: options?.relativePath === "wiki"
+        ? [
+            { path: "wiki/concepts/agent-memory-layer.md", name: "agent-memory-layer.md", kind: "file", size: 12, modifiedAt },
+            { path: "wiki/entities/paperclip.md", name: "paperclip.md", kind: "file", size: 10, modifiedAt },
+            { path: "wiki/projects/llm-wiki/standup.md", name: "standup.md", kind: "file", size: 16, modifiedAt },
+          ]
+        : [
+            { path: "raw/2026-04-09-thomas-gieselmann-fundraising-call.md", name: "2026-04-09-thomas-gieselmann-fundraising-call.md", kind: "file", size: 14, modifiedAt },
+          ],
+    });
+    harness.ctx.db.query = async <T = Record<string, unknown>>(sql: string, params?: unknown[]) => {
+      harness.dbQueries.push({ sql, params });
+      return [] as T[];
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.getData<{
+      pages: Array<{ path: string; title: string | null }>;
+      sources: Array<{ rawPath: string; title: string | null }>;
+    }>("pages", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      includeRaw: true,
+    });
+
+    expect(result.pages).toEqual([
+      expect.objectContaining({ path: "wiki/concepts/agent-memory-layer.md", title: null }),
+      expect.objectContaining({ path: "wiki/entities/paperclip.md", title: null }),
+      expect.objectContaining({ path: "wiki/projects/llm-wiki/standup.md", title: null }),
+    ]);
+    expect(result.sources).toEqual([
+      expect.objectContaining({ rawPath: "raw/2026-04-09-thomas-gieselmann-fundraising-call.md", title: null }),
+    ]);
+  });
+
+  it("does not ingest Paperclip events until operator controls enable them", async () => {
+    const harness = createTestHarness({ manifest });
+    const issue = paperclipIssue();
+    harness.seed({ issues: [issue] });
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    await harness.emit("issue.created", { identifier: issue.identifier }, {
+      companyId: COMPANY_ID,
+      entityId: issue.id,
+      entityType: "issue",
+      eventId: "event-disabled-issue-created",
+    });
+
+    expect(writes).toHaveLength(0);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_sources"))).toBe(false);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_operations"))).toBe(false);
+  });
+
+  it("records enabled Paperclip issue events as cursor observations without creating ingest operations", async () => {
+    const harness = createTestHarness({ manifest });
+    const issue = paperclipIssue();
+    harness.seed({ issues: [issue] });
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const policy = await harness.performAction<{ enabled: boolean; sources: { issues: boolean; comments: boolean; documents: boolean } }>(
+      "update-event-ingestion-settings",
+      {
+        companyId: COMPANY_ID,
+        enabled: true,
+        sources: { issues: true, comments: false, documents: false },
+      },
+    );
+    expect(policy).toMatchObject({ enabled: true, sources: { issues: true, comments: false, documents: false } });
+
+    await harness.emit("issue.created", { identifier: issue.identifier }, {
+      companyId: COMPANY_ID,
+      entityId: issue.id,
+      entityType: "issue",
+      eventId: "event-enabled-issue-created",
+    });
+
+    expect(writes).toHaveLength(0);
+    const operations = await harness.ctx.issues.list({
+      companyId: COMPANY_ID,
+      originKindPrefix: String(OPERATION_ORIGIN_KIND),
+    });
+    expect(operations).toHaveLength(0);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_sources"))).toBe(false);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_operations"))).toBe(false);
+    const cursorUpsert = harness.dbExecutes.find((execute) => execute.sql.includes("paperclip_distillation_cursors"));
+    expect(cursorUpsert?.params).toEqual(expect.arrayContaining([
+      COMPANY_ID,
+      "default",
+      "company",
+      null,
+      null,
+    ]));
+  });
+
+  it("preserves Paperclip event ingestion sources when only enabled changes", async () => {
+    const harness = createTestHarness({ manifest });
+
+    await plugin.definition.setup(harness.ctx);
+    await harness.performAction("update-event-ingestion-settings", {
+      companyId: COMPANY_ID,
+      enabled: true,
+      sources: { issues: true, comments: true, documents: true },
+    });
+
+    const disabled = await harness.performAction<{
+      enabled: boolean;
+      sources: { issues: boolean; comments: boolean; documents: boolean };
+    }>("update-event-ingestion-settings", {
+      companyId: COMPANY_ID,
+      enabled: false,
+    });
+    expect(disabled).toMatchObject({
+      enabled: false,
+      sources: { issues: true, comments: true, documents: true },
+    });
+
+    const reenabled = await harness.performAction<{
+      enabled: boolean;
+      sources: { issues: boolean; comments: boolean; documents: boolean };
+    }>("update-event-ingestion-settings", {
+      companyId: COMPANY_ID,
+      enabled: true,
+    });
+    expect(reenabled).toMatchObject({
+      enabled: true,
+      sources: { issues: true, comments: true, documents: true },
+    });
+  });
+
+  it("keeps Paperclip event cursor observations company scoped and ignores plugin-operation issues", async () => {
+    const harness = createTestHarness({ manifest });
+    const visibleIssue = paperclipIssue({ projectId: "77777777-7777-4777-8777-777777777777" });
+    const otherCompanyIssue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777778",
+      companyId: OTHER_COMPANY_ID,
+      projectId: "77777777-7777-4777-8777-777777777779",
+      identifier: "PAP-9999",
+    });
+    const operationIssue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777780",
+      originKind: `${OPERATION_ORIGIN_KIND}:ingest`,
+    });
+    harness.seed({ issues: [visibleIssue, otherCompanyIssue, operationIssue] });
+
+    await plugin.definition.setup(harness.ctx);
+    await harness.performAction("update-event-ingestion-settings", {
+      companyId: COMPANY_ID,
+      enabled: true,
+      sources: { issues: true, comments: true, documents: true },
+    });
+
+    await harness.emit("issue.updated", {}, {
+      companyId: COMPANY_ID,
+      entityId: visibleIssue.id,
+      entityType: "issue",
+      eventId: "event-visible",
+    });
+    await harness.emit("issue.updated", {}, {
+      companyId: OTHER_COMPANY_ID,
+      entityId: otherCompanyIssue.id,
+      entityType: "issue",
+      eventId: "event-other-company",
+    });
+    await harness.emit("issue.updated", {}, {
+      companyId: COMPANY_ID,
+      entityId: operationIssue.id,
+      entityType: "issue",
+      eventId: "event-plugin-operation",
+    });
+
+    const cursorWrites = harness.dbExecutes.filter((execute) => execute.sql.includes("paperclip_distillation_cursors"));
+    expect(cursorWrites).toHaveLength(1);
+    expect(cursorWrites[0].params).toEqual(expect.arrayContaining([
+      COMPANY_ID,
+      "default",
+      "project",
+      visibleIssue.projectId,
+    ]));
+  });
+
+  it("routes Paperclip issue, comment, and document event cursors only to the default space", async () => {
+    const harness = createTestHarness({ manifest });
+    const issue = paperclipIssue({ projectId: "77777777-7777-4777-8777-777777777777" });
+    harness.seed({ issues: [issue] });
+
+    await plugin.definition.setup(harness.ctx);
+    const created = await harness.performAction<{
+      space: { id: string; slug: string };
+    }>("create-space", {
+      companyId: COMPANY_ID,
+      displayName: "Team Research",
+    });
+    await harness.performAction("update-event-ingestion-settings", {
+      companyId: COMPANY_ID,
+      enabled: true,
+      sources: { issues: true, comments: true, documents: true },
+    });
+
+    await harness.emit("issue.created", {}, {
+      companyId: COMPANY_ID,
+      entityId: issue.id,
+      entityType: "issue",
+      eventId: "event-default-issue-created",
+    });
+    await harness.emit("issue.comment.created", { commentId: "comment-1" }, {
+      companyId: COMPANY_ID,
+      entityId: issue.id,
+      entityType: "issue",
+      eventId: "event-default-comment-created",
+    });
+    await harness.emit("issue.document.updated", { key: "plan", revisionId: "revision-1" }, {
+      companyId: COMPANY_ID,
+      entityId: issue.id,
+      entityType: "issue",
+      eventId: "event-default-document-updated",
+    });
+
+    const cursorWrites = harness.dbExecutes.filter((execute) => execute.sql.includes("paperclip_distillation_cursors"));
+    expect(cursorWrites).toHaveLength(3);
+    expect(cursorWrites.every((execute) => execute.params?.[10] !== created.space.id)).toBe(true);
+    expect(cursorWrites.map((execute) => execute.params?.[2])).toEqual(["default", "default", "default"]);
+    expect(String(cursorWrites[0].params?.[9])).toContain('"lastSourceKind":"issues"');
+    expect(String(cursorWrites[1].params?.[9])).toContain('"lastSourceKind":"comments"');
+    expect(String(cursorWrites[2].params?.[9])).toContain('"lastSourceKind":"documents"');
+  });
+
+  it("routes Paperclip events into an explicitly enabled shared non-default space", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const issue = paperclipIssue({ projectId: project.id });
+    harness.seed({ projects: [project], issues: [issue] });
+
+    await plugin.definition.setup(harness.ctx);
+    const created = await harness.performAction<{
+      space: { id: string; slug: string };
+    }>("create-space", {
+      companyId: COMPANY_ID,
+      displayName: "Engineering Wiki",
+      accessScope: "shared",
+    });
+    mockPersistedWikiSpace(harness, created.space as unknown as Record<string, unknown>);
+    const enabledProfile = {
+      version: 1,
+      enabled: true,
+      sourceScopes: [{ kind: "selected_projects", projectIds: [project.id] }],
+      sourceKinds: { issues: true, comments: true, documents: true, attachments: "off", workProducts: "off" },
+      cursor: { maxWindowCharacters: 60000, maxCharactersPerSource: 12000, minSourceAgeMinutes: 15, maxWindowsPerRun: 6, staleAfterHours: 72 },
+      backfill: { requireManualQueue: true },
+    };
+    await harness.performAction("update-paperclip-ingestion-profile", {
+      companyId: COMPANY_ID,
+      spaceSlug: created.space.slug,
+      profile: enabledProfile,
+    });
+    mockPersistedWikiSpace(harness, { ...(created.space as unknown as Record<string, unknown>), settings: { paperclipIngestion: enabledProfile } });
+
+    await harness.emit("issue.created", {}, {
+      companyId: COMPANY_ID,
+      entityId: issue.id,
+      entityType: "issue",
+      eventId: "event-non-default-enabled",
+    });
+
+    const cursorWrites = harness.dbExecutes.filter((execute) => execute.sql.includes("paperclip_distillation_cursors"));
+    expect(cursorWrites.some((execute) => execute.params?.[10] === created.space.id)).toBe(true);
+  });
+
+  it("stops new non-default observations after the per-space profile is disabled", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const issue = paperclipIssue({ projectId: project.id });
+    harness.seed({ projects: [project], issues: [issue] });
+
+    await plugin.definition.setup(harness.ctx);
+    const created = await harness.performAction<{
+      space: { id: string; slug: string };
+    }>("create-space", {
+      companyId: COMPANY_ID,
+      displayName: "Support Wiki",
+      accessScope: "shared",
+    });
+    mockPersistedWikiSpace(harness, created.space as unknown as Record<string, unknown>);
+    const enabledProfile = {
+      version: 1,
+      enabled: true,
+      sourceScopes: [{ kind: "selected_projects", projectIds: [project.id] }],
+      sourceKinds: { issues: true, comments: false, documents: false, attachments: "off", workProducts: "off" },
+      cursor: { maxWindowCharacters: 60000, maxCharactersPerSource: 12000, minSourceAgeMinutes: 15, maxWindowsPerRun: 6, staleAfterHours: 72 },
+      backfill: { requireManualQueue: true },
+    };
+    await harness.performAction("update-paperclip-ingestion-profile", {
+      companyId: COMPANY_ID,
+      spaceSlug: created.space.slug,
+      profile: enabledProfile,
+    });
+    mockPersistedWikiSpace(harness, { ...(created.space as unknown as Record<string, unknown>), settings: { paperclipIngestion: enabledProfile } });
+    await harness.emit("issue.created", {}, {
+      companyId: COMPANY_ID,
+      entityId: issue.id,
+      entityType: "issue",
+      eventId: "event-before-disable",
+    });
+    await harness.performAction("update-paperclip-ingestion-profile", {
+      companyId: COMPANY_ID,
+      spaceSlug: created.space.slug,
+      profile: { ...enabledProfile, enabled: false },
+    });
+    mockPersistedWikiSpace(harness, { ...(created.space as unknown as Record<string, unknown>), settings: { paperclipIngestion: { ...enabledProfile, enabled: false } } });
+    await harness.emit("issue.updated", {}, {
+      companyId: COMPANY_ID,
+      entityId: issue.id,
+      entityType: "issue",
+      eventId: "event-after-disable",
+    });
+
+    const nonDefaultCursorWrites = harness.dbExecutes.filter((execute) =>
+      execute.sql.includes("paperclip_distillation_cursors") && execute.params?.[10] === created.space.id);
+    expect(nonDefaultCursorWrites).toHaveLength(1);
+  });
+
+  it("assembles deterministic Paperclip source bundles with issue, document, and comment provenance", async () => {
+    const harness = createTestHarness({ manifest });
+    const root = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777781",
+      identifier: "PAP-4000",
+      title: "Root distillation issue",
+      projectId: "77777777-7777-4777-8777-777777777777",
+      updatedAt: new Date("2026-05-01T10:00:00Z"),
+    });
+    const child = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777782",
+      identifier: "PAP-4001",
+      title: "Child source issue",
+      parentId: root.id,
+      projectId: root.projectId,
+      description: "Child issue has a decision and implementation notes.",
+      updatedAt: new Date("2026-05-02T10:00:00Z"),
+    });
+    harness.seed({
+      issues: [root, child],
+      issueComments: [{
+        id: "77777777-7777-4777-8777-777777777783",
+        companyId: COMPANY_ID,
+        issueId: child.id,
+        authorType: "user",
+        authorAgentId: null,
+        authorUserId: null,
+        body: "Comment evidence for the source bundle.",
+        presentation: null,
+        metadata: null,
+        createdAt: new Date("2026-05-03T10:00:00Z"),
+        updatedAt: new Date("2026-05-03T10:00:00Z"),
+      }],
+    });
+
+    await plugin.definition.setup(harness.ctx);
+    await harness.ctx.issues.documents.upsert({
+      companyId: COMPANY_ID,
+      issueId: child.id,
+      key: "plan",
+      title: "Plan",
+      body: "Document evidence for the source bundle.",
+    });
+
+    const first = await harness.performAction<{
+      markdown: string;
+      sourceRefs: Array<{ kind: string; issueIdentifier: string | null; documentKey?: string; commentId?: string }>;
+      sourceHash: string;
+      sourceWindowEnd: string | null;
+    }>("assemble-paperclip-source-bundle", {
+      companyId: COMPANY_ID,
+      rootIssueId: root.id,
+      maxCharacters: 20000,
+    });
+    const second = await harness.performAction<typeof first>("assemble-paperclip-source-bundle", {
+      companyId: COMPANY_ID,
+      rootIssueId: root.id,
+      maxCharacters: 20000,
+    });
+
+    expect(second.sourceHash).toBe(first.sourceHash);
+    expect(first.markdown).toContain("Root distillation issue");
+    expect(first.markdown).toContain("Child issue has a decision");
+    expect(first.markdown).toContain("Document evidence for the source bundle.");
+    expect(first.markdown).toContain("Comment evidence for the source bundle.");
+    expect(first.sourceRefs).toEqual(expect.arrayContaining([
+      expect.objectContaining({ kind: "issue", issueIdentifier: "PAP-4001" }),
+      expect.objectContaining({ kind: "document", documentKey: "plan" }),
+      expect.objectContaining({ kind: "comment", commentId: "77777777-7777-4777-8777-777777777783" }),
+    ]));
+    expect(first.sourceWindowEnd).toEqual(expect.any(String));
+  });
+
+  it("suppresses secret-like comment and document bodies before storing distillation snapshots", async () => {
+    const harness = createTestHarness({ manifest });
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777784",
+      identifier: "PAP-4002",
+      title: "Sensitive source issue",
+      projectId: "77777777-7777-4777-8777-777777777777",
+      description: "Keep the project page current without copying credential material into the wiki.",
+      updatedAt: new Date("2026-05-04T10:00:00Z"),
+    });
+    harness.seed({
+      issues: [issue],
+      issueComments: [{
+        id: "77777777-7777-4777-8777-777777777785",
+        companyId: COMPANY_ID,
+        issueId: issue.id,
+        authorType: "user",
+        authorAgentId: null,
+        authorUserId: null,
+        body: "Authorization: Bearer ghp_supersecretcommenttoken1234567890",
+        presentation: null,
+        metadata: null,
+        createdAt: new Date("2026-05-04T11:00:00Z"),
+        updatedAt: new Date("2026-05-04T11:00:00Z"),
+      }],
+    });
+
+    await plugin.definition.setup(harness.ctx);
+    await harness.ctx.issues.documents.upsert({
+      companyId: COMPANY_ID,
+      issueId: issue.id,
+      key: "plan",
+      title: "Plan",
+      body: "OPENAI_API_KEY=sk-supersecretdocumentvalue1234567890",
+    });
+
+    const run = await harness.performAction<{
+      bundle: {
+        markdown: string;
+        warnings: string[];
+        sourceRefs: Array<Record<string, unknown>>;
+      };
+    }>("create-paperclip-distillation-run", {
+      companyId: COMPANY_ID,
+      projectId: issue.projectId,
+      maxCharacters: 20000,
+    });
+
+    expect(run.bundle.markdown).toContain("Suppressed by LLM Wiki distillation security policy");
+    expect(run.bundle.markdown).not.toContain("ghp_supersecretcommenttoken1234567890");
+    expect(run.bundle.markdown).not.toContain("sk-supersecretdocumentvalue1234567890");
+    expect(run.bundle.warnings).toEqual(expect.arrayContaining([
+      expect.stringContaining("Suppressed comment content"),
+      expect.stringContaining("Suppressed document content"),
+    ]));
+    expect(run.bundle.sourceRefs).toEqual(expect.arrayContaining([
+      expect.objectContaining({ kind: "comment", redactionStatus: "suppressed_sensitive_content" }),
+      expect.objectContaining({ kind: "document", redactionStatus: "suppressed_sensitive_content" }),
+    ]));
+
+    const snapshotInsert = harness.dbExecutes.find((execute) => execute.sql.includes("paperclip_source_snapshots"));
+    const storedSourceRefs = String(snapshotInsert?.params?.[9] ?? "");
+    const storedMarkdown = String(snapshotInsert?.params?.[10] ?? "");
+    expect(storedSourceRefs).toContain("suppressed_sensitive_content");
+    expect(storedMarkdown).toContain("Suppressed by LLM Wiki distillation security policy");
+    expect(storedMarkdown).not.toContain("ghp_supersecretcommenttoken1234567890");
+    expect(storedMarkdown).not.toContain("sk-supersecretdocumentvalue1234567890");
+  });
+
+  it("creates source snapshots and only advances cursors after successful distillation outcomes", async () => {
+    const harness = createTestHarness({ manifest });
+    const issue = paperclipIssue({
+      projectId: "77777777-7777-4777-8777-777777777777",
+      updatedAt: new Date("2026-05-02T10:00:00Z"),
+    });
+    harness.seed({ issues: [issue] });
+    await plugin.definition.setup(harness.ctx);
+
+    const run = await harness.performAction<{
+      runId: string;
+      cursorId: string;
+      snapshotId: string;
+      bundle: { sourceHash: string; sourceWindowEnd: string };
+    }>("create-paperclip-distillation-run", {
+      companyId: COMPANY_ID,
+      projectId: issue.projectId,
+    });
+    expect(run.snapshotId).toEqual(expect.any(String));
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("paperclip_source_snapshots"))).toBe(true);
+
+    const failed = await harness.performAction<{ cursorAdvanced: boolean }>("record-paperclip-distillation-outcome", {
+      companyId: COMPANY_ID,
+      runId: run.runId,
+      cursorId: run.cursorId,
+      status: "failed",
+      sourceHash: run.bundle.sourceHash,
+      sourceWindowEnd: run.bundle.sourceWindowEnd,
+      warning: "writer failed",
+    });
+    expect(failed.cursorAdvanced).toBe(false);
+    const cursorUpdatesAfterFailure = harness.dbExecutes.filter((execute) =>
+      execute.sql.trim().startsWith("UPDATE") && execute.sql.includes("paperclip_distillation_cursors"));
+    expect(cursorUpdatesAfterFailure).toHaveLength(0);
+
+    const succeeded = await harness.performAction<{ cursorAdvanced: boolean }>("record-paperclip-distillation-outcome", {
+      companyId: COMPANY_ID,
+      runId: run.runId,
+      cursorId: run.cursorId,
+      status: "succeeded",
+      sourceHash: run.bundle.sourceHash,
+      sourceWindowEnd: run.bundle.sourceWindowEnd,
+    });
+    expect(succeeded.cursorAdvanced).toBe(true);
+    const cursorSuccessUpdate = harness.dbExecutes.find((execute) =>
+      execute.sql.trim().startsWith("UPDATE") && execute.sql.includes("paperclip_distillation_cursors"));
+    expect(cursorSuccessUpdate?.params).toEqual(expect.arrayContaining([
+      COMPANY_ID,
+      "default",
+      run.runId,
+      run.bundle.sourceWindowEnd,
+      run.bundle.sourceHash,
+      run.cursorId,
+    ]));
+  });
+
+  it("uses the existing distillation cursor id after an upsert conflict", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777800",
+      identifier: "PAP-4099",
+      title: "Existing cursor target",
+      projectId: project.id,
+      status: "in_progress",
+    });
+    const existingCursorId = "77777777-7777-4777-8777-777777777899";
+    const originalQuery = harness.ctx.db.query.bind(harness.ctx.db);
+    harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+      if (sql.includes("SELECT id") && sql.includes("paperclip_distillation_cursors")) {
+        return [{ id: existingCursorId }] as T[];
+      }
+      return originalQuery<T>(sql, params);
+    };
+    harness.seed({ projects: [project], issues: [issue] });
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{ cursorId: string }>("create-paperclip-distillation-run", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+    });
+
+    expect(result.cursorId).toBe(existingCursorId);
+    const runInsert = harness.dbExecutes.find((execute) =>
+      execute.sql.includes("paperclip_distillation_runs") && execute.sql.includes("'source_ready'"));
+    expect(runInsert?.params?.[3]).toBe(existingCursorId);
+  });
+
+  it("creates explicit distillation work items for manual, retry, and backfill lanes", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+
+    await harness.performAction("create-paperclip-distillation-work-item", {
+      companyId: COMPANY_ID,
+      kind: "manual",
+      projectId: "77777777-7777-4777-8777-777777777777",
+      idempotencyKey: "manual:project:77777777-7777-4777-8777-777777777777",
+    });
+    await harness.performAction("create-paperclip-distillation-work-item", {
+      companyId: COMPANY_ID,
+      kind: "retry",
+      rootIssueId: "77777777-7777-4777-8777-777777777781",
+      priority: "high",
+      idempotencyKey: "retry:run:1",
+    });
+    await harness.performAction("create-paperclip-distillation-work-item", {
+      companyId: COMPANY_ID,
+      kind: "backfill",
+      projectId: "77777777-7777-4777-8777-777777777777",
+      priority: "low",
+      metadata: { window: "last-30-days" },
+      idempotencyKey: "backfill:last-30-days",
+    });
+
+    const workItemWrites = harness.dbExecutes.filter((execute) => execute.sql.includes("paperclip_distillation_work_items"));
+    expect(workItemWrites).toHaveLength(3);
+    expect(workItemWrites.map((write) => write.params?.[3])).toEqual(["manual", "retry", "backfill"]);
+    expect(String(workItemWrites[0].params?.[9])).toContain('"sourceScope":"project"');
+    expect(String(workItemWrites[1].params?.[9])).toContain('"sourceScope":"root_issue"');
+    expect(String(workItemWrites[2].params?.[9])).toContain('"sourceScope":"project"');
+
+    await expect(harness.performAction("create-paperclip-distillation-work-item", {
+      companyId: COMPANY_ID,
+      kind: "backfill",
+      idempotencyKey: "backfill:company",
+    })).rejects.toThrow("whole-company backfill is not allowed");
+  });
+
+  it("records estimated Paperclip distillation cost without refusing on legacy cost config", async () => {
+    const harness = createTestHarness({
+      manifest,
+      config: {
+        maxPaperclipRoutineRunCostCents: 1,
+        maxPaperclipDistillationTaskCostCents: 1,
+        maxPaperclipDistillationProjectCostCents: 1,
+        paperclipCostCentsPerThousandSourceCharacters: 100,
+      },
+    });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777795",
+      identifier: "PAP-4104",
+      title: "Large source bundle",
+      description: `Accepted plan. ${"Detailed implementation note. ".repeat(160)}`,
+      projectId: project.id,
+      status: "in_progress",
+    });
+    harness.seed({ projects: [project], issues: [issue] });
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{
+      status: string;
+      estimatedCostCents: number;
+      snapshotId: string | null;
+    }>("create-paperclip-distillation-run", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+      routineRun: true,
+    });
+
+    expect(result.status).toBe("source_ready");
+    expect(result.estimatedCostCents).toBeGreaterThan(1);
+    expect(result.snapshotId).toEqual(expect.any(String));
+    const readyRun = harness.dbExecutes.find((execute) =>
+      execute.sql.includes("paperclip_distillation_runs") && execute.sql.includes("'source_ready'"));
+    expect(readyRun?.params).toEqual(expect.arrayContaining([
+      COMPANY_ID,
+      "default",
+      expect.any(String),
+      expect.any(String),
+      null,
+      project.id,
+    ]));
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("paperclip_source_snapshots"))).toBe(true);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("refused_cost_cap"))).toBe(false);
+  });
+
+  it("queues visible manual distill operation issues for a company-wide stale cursor scan", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777796",
+      identifier: "PAP-4105",
+      title: "Manual distillation target",
+      description: "Implemented enough evidence to manually distill into the wiki.",
+      status: "done",
+      projectId: project.id,
+    });
+    harness.seed({ agents: [wikiMaintainerAgent()], projects: [project], issues: [issue] });
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{
+      status: string;
+      operation: { issue: { originKind: string; billingCode: string | null; assigneeAgentId: string | null; assigneeAdapterOverrides: { modelProfile?: string } | null; description: string | null } };
+      workItem: { kind: string; workItemId: string };
+    }>("distill-paperclip-now", {
+      companyId: COMPANY_ID,
+      autoApply: false,
+      useCheapModelProfile: true,
+      includeSupportingPages: false,
+    });
+
+    expect(result.status).toBe("queued");
+    expect(result.workItem.kind).toBe("manual");
+    expect(result.operation.issue.originKind).toBe(`${OPERATION_ORIGIN_KIND}:distill`);
+    expect(result.operation.issue.billingCode).toBe("plugin-llm-wiki:default");
+    expect(result.operation.issue.assigneeAgentId).toBe(wikiMaintainerAgent().id);
+    expect(result.operation.issue.assigneeAdapterOverrides).toEqual({ modelProfile: "cheap" });
+    expect(result.operation.issue.description).toContain("Prompt source: LLM Wiki plugin action `distill-paperclip-now`");
+    expect(result.operation.issue.description).toContain(`Required skill: use the installed \`${PAPERCLIP_DISTILL_SKILL_KEY}\` skill`);
+    expect(result.operation.issue.description).toContain("Do not hardcode a single project");
+    expect(result.operation.issue.description).not.toContain(`Source project ID: ${project.id}`);
+    const workItemInsert = harness.dbExecutes.find((execute) =>
+      execute.sql.includes("paperclip_distillation_work_items") && execute.params?.[3] === "manual");
+    expect(workItemInsert?.params).toEqual(expect.arrayContaining([
+      COMPANY_ID,
+      "default",
+      "manual",
+      "medium",
+      null,
+      null,
+    ]));
+    const runInsert = harness.dbExecutes.find((execute) =>
+      execute.sql.includes("paperclip_distillation_runs") && execute.sql.includes("operation_issue_id"));
+    expect(runInsert).toBeUndefined();
+  });
+
+  it("enables distillation cursors for the most recently active non-plugin projects", async () => {
+    const harness = createTestHarness({ manifest });
+    const recentProject = {
+      ...existingProject(),
+      id: "77777777-7777-4777-8777-777777777801",
+      name: "Recent Active Project",
+      status: "in_progress" as const,
+      updatedAt: new Date("2026-05-04T18:00:00Z"),
+    };
+    const olderProject = {
+      ...existingProject(),
+      id: "77777777-7777-4777-8777-777777777802",
+      name: "Older Active Project",
+      status: "in_progress" as const,
+      updatedAt: new Date("2026-05-03T18:00:00Z"),
+    };
+    const overflowProject = {
+      ...existingProject(),
+      id: "77777777-7777-4777-8777-777777777803",
+      name: "Overflow Active Project",
+      status: "in_progress" as const,
+      updatedAt: new Date("2026-05-02T18:00:00Z"),
+    };
+    const completedProject = {
+      ...existingProject(),
+      id: "77777777-7777-4777-8777-777777777804",
+      name: "Completed Project",
+      status: "completed" as const,
+      updatedAt: new Date("2026-05-04T19:00:00Z"),
+    };
+    const pluginProject = {
+      ...existingProject(),
+      id: "77777777-7777-4777-8777-777777777805",
+      name: "LLM Wiki",
+      status: "in_progress" as const,
+      updatedAt: new Date("2026-05-04T20:00:00Z"),
+      managedByPlugin: {
+        id: "77777777-7777-4777-8777-777777777806",
+        pluginId: "plugin-instance-1",
+        pluginKey: manifest.id,
+        pluginDisplayName: manifest.displayName,
+        resourceKind: "project" as const,
+        resourceKey: WIKI_PROJECT_KEY,
+        defaultsJson: {},
+        createdAt: new Date("2026-05-04T00:00:00Z"),
+        updatedAt: new Date("2026-05-04T00:00:00Z"),
+      },
+    };
+    harness.seed({ projects: [recentProject, olderProject, overflowProject, completedProject, pluginProject] });
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{
+      selectedProjects: Array<{ id: string; observedAt: string | null }>;
+      eventIngestion: { enabled: boolean; sources: { issues: boolean; comments: boolean; documents: boolean } };
+    }>("enable-paperclip-distillation-active-projects", {
+      companyId: COMPANY_ID,
+      limit: 2,
+    });
+
+    expect(result.selectedProjects.map((project) => project.id)).toEqual([recentProject.id, olderProject.id]);
+    expect(result.eventIngestion).toMatchObject({
+      enabled: true,
+      sources: { issues: true, comments: true, documents: true },
+    });
+    const cursorWrites = harness.dbExecutes.filter((execute) => execute.sql.includes("paperclip_distillation_cursors"));
+    expect(cursorWrites).toHaveLength(2);
+    expect(cursorWrites.map((execute) => execute.params?.[5])).toEqual([recentProject.id, olderProject.id]);
+    expect(cursorWrites.map((execute) => execute.params?.[8])).toEqual([1, 1]);
+    expect(String(cursorWrites[0]?.params?.[9])).toContain('"configuredBy":"enable-active-projects"');
+  });
+
+  it("backfills only the selected Paperclip project and date window", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const inWindow = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777797",
+      identifier: "PAP-4106",
+      title: "Backfill in-window decision",
+      description: "Accepted historical decision that should appear in the backfill page.",
+      status: "done",
+      projectId: project.id,
+      updatedAt: new Date("2026-04-15T12:00:00Z"),
+    });
+    const outOfWindow = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777798",
+      identifier: "PAP-4107",
+      title: "Backfill out-of-window decision",
+      description: "This old decision must not be included in the selected date window.",
+      status: "done",
+      projectId: project.id,
+      updatedAt: new Date("2026-03-01T12:00:00Z"),
+    });
+    const otherProject = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777799",
+      identifier: "PAP-4108",
+      title: "Other project decision",
+      description: "This issue belongs to a different project and must not be included.",
+      status: "done",
+      projectId: "88888888-8888-4888-8888-888888888888",
+      updatedAt: new Date("2026-04-16T12:00:00Z"),
+    });
+    harness.seed({ agents: [wikiMaintainerAgent()], projects: [project], issues: [inWindow, outOfWindow, otherProject] });
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{
+      status: string;
+      patches: Array<{ operationType: string; proposedContents: string }>;
+      workItem: { kind: string };
+      operation: { issue: { originKind: string } };
+    }>("backfill-paperclip-distillation", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+      backfillStartAt: "2026-04-01T00:00:00Z",
+      backfillEndAt: "2026-04-30T23:59:59Z",
+      autoApply: false,
+      includeSupportingPages: false,
+    });
+
+    expect(result.status).toBe("review_required");
+    expect(result.workItem.kind).toBe("backfill");
+    expect(result.operation.issue.originKind).toBe(`${OPERATION_ORIGIN_KIND}:backfill`);
+    const projectPatch = result.patches.find((patch) => patch.operationType === "project_page_distill");
+    expect(projectPatch?.proposedContents).toContain("PAP-4106");
+    expect(projectPatch?.proposedContents).not.toContain("PAP-4107");
+    expect(projectPatch?.proposedContents).not.toContain("PAP-4108");
+    const workItemInsert = harness.dbExecutes.find((execute) =>
+      execute.sql.includes("paperclip_distillation_work_items") && execute.params?.[3] === "backfill");
+    expect(String(workItemInsert?.params?.[9])).toContain('"backfillStartAt":"2026-04-01T00:00:00Z"');
+  });
+
+  it("generates review-required Paperclip project page patches with provenance, index, and log updates", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777791",
+      identifier: "PAP-4100",
+      title: "Approved project page distillation plan",
+      description: "Accepted plan: write stable project overview sections with source provenance.",
+      status: "in_progress",
+      projectId: project.id,
+      updatedAt: new Date("2026-05-03T10:00:00Z"),
+    });
+    const files = new Map<string, string>([
+      ["wiki/index.md", DEFAULT_INDEX],
+      ["wiki/log.md", DEFAULT_LOG],
+    ]);
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.seed({ projects: [project], issues: [issue] });
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const contents = files.get(relativePath);
+      if (contents == null) throw new Error(`missing ${relativePath}`);
+      return contents;
+    };
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      files.set(relativePath, contents);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{
+      status: string;
+      patches: Array<{ pagePath: string; operationType: string; currentHash: string | null; proposedContents: string; sourceRefs: Array<{ issueIdentifier: string | null }> }>;
+      warnings: string[];
+    }>("distill-paperclip-project-page", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+      autoApply: false,
+      maxCharacters: 20000,
+      includeSupportingPages: false,
+    });
+
+    expect(result.status).toBe("review_required");
+    expect(writes).toHaveLength(0);
+    expect(result.patches.map((patch) => patch.operationType)).toEqual([
+      "standup_update",
+      "project_page_distill",
+      "index_refresh",
+      "log_append",
+    ]);
+    const standupPatch = result.patches[0];
+    expect(standupPatch.pagePath).toBe("wiki/projects/existing-wiki-project/standup.md");
+    expect(standupPatch.proposedContents).toContain("## Executive Readout");
+    expect(standupPatch.proposedContents).toContain("## What Changed");
+    const projectPatch = result.patches[1];
+    expect(projectPatch.currentHash).toBeNull();
+    expect(projectPatch.pagePath).toBe("wiki/projects/existing-wiki-project/index.md");
+    expect(projectPatch.proposedContents).toContain("## Workstreams");
+    expect(projectPatch.proposedContents).toContain("PAP-4100");
+    expect(projectPatch.sourceRefs).toEqual([expect.objectContaining({ issueIdentifier: "PAP-4100" })]);
+    expect(result.patches[2].proposedContents).toContain("[[wiki/projects/existing-wiki-project/index.md]]");
+    expect(result.patches[2].proposedContents).toContain("[[wiki/projects/existing-wiki-project/standup.md]]");
+    expect(result.patches[3].proposedContents).toContain("paperclip-distill | proposed");
+    expect(result.warnings).toContain("Auto-apply policy disabled; proposed patches require review.");
+  });
+
+  it("keeps suppressed secret-like source content out of generated wiki patches", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777796",
+      identifier: "PAP-4104",
+      title: "Distill sanitized provenance",
+      description: "Publish enough project state for a reviewable project page without leaking credentials.",
+      status: "in_progress",
+      projectId: project.id,
+      updatedAt: new Date("2026-05-04T10:00:00Z"),
+    });
+    const files = new Map<string, string>([
+      ["wiki/index.md", DEFAULT_INDEX],
+      ["wiki/log.md", DEFAULT_LOG],
+    ]);
+    harness.seed({
+      projects: [project],
+      issues: [issue],
+      issueComments: [{
+        id: "77777777-7777-4777-8777-777777777797",
+        companyId: COMPANY_ID,
+        issueId: issue.id,
+        authorType: "user",
+        authorAgentId: null,
+        authorUserId: null,
+        body: "Authorization: Bearer ghp_patchsecretcommenttoken1234567890",
+        presentation: null,
+        metadata: null,
+        createdAt: new Date("2026-05-04T11:00:00Z"),
+        updatedAt: new Date("2026-05-04T11:00:00Z"),
+      }],
+    });
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const contents = files.get(relativePath);
+      if (contents == null) throw new Error(`missing ${relativePath}`);
+      return contents;
+    };
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      files.set(relativePath, contents);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    await harness.ctx.issues.documents.upsert({
+      companyId: COMPANY_ID,
+      issueId: issue.id,
+      key: "plan",
+      title: "Plan",
+      body: "OPENAI_API_KEY=sk-patchsecretdocumentvalue1234567890",
+    });
+
+    const result = await harness.performAction<{
+      status: string;
+      patches: Array<{ operationType: string; proposedContents: string }>;
+    }>("distill-paperclip-project-page", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+      maxCharacters: 20000,
+      includeSupportingPages: false,
+    });
+
+    expect(result.status).toBe("review_required");
+    const combinedPatchContents = result.patches.map((patch) => patch.proposedContents).join("\n");
+    expect(combinedPatchContents).toContain("redaction=suppressed_sensitive_content");
+    expect(combinedPatchContents).toContain("redaction_reasons=secret_like_token");
+    expect(combinedPatchContents).not.toContain("ghp_patchsecretcommenttoken1234567890");
+    expect(combinedPatchContents).not.toContain("sk-patchsecretdocumentvalue1234567890");
+  });
+
+  it("auto-applies Paperclip project page patches by default when policy allows and records page bindings", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777792",
+      identifier: "PAP-4101",
+      title: "Implement project page writer",
+      description: "Implementation completed enough to publish the generated project page.",
+      status: "done",
+      projectId: project.id,
+      updatedAt: new Date("2026-05-04T10:00:00Z"),
+    });
+    const files = new Map<string, string>([
+      ["wiki/index.md", DEFAULT_INDEX],
+      ["wiki/log.md", DEFAULT_LOG],
+    ]);
+    harness.seed({ projects: [project], issues: [issue] });
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const contents = files.get(relativePath);
+      if (contents == null) throw new Error(`missing ${relativePath}`);
+      return contents;
+    };
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      files.set(relativePath, contents);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{
+      status: string;
+      appliedPages: string[];
+      patches: Array<{ pagePath: string; sourceHash: string }>;
+    }>("distill-paperclip-project-page", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+      autoApply: true,
+      maxCharacters: 20000,
+      includeSupportingPages: false,
+    });
+
+    expect(result.status).toBe("applied");
+    expect(result.appliedPages).toEqual([
+      "wiki/projects/existing-wiki-project/standup.md",
+      "wiki/projects/existing-wiki-project/index.md",
+      "wiki/index.md",
+      "wiki/log.md",
+    ]);
+    expect(files.get("wiki/projects/existing-wiki-project/standup.md")).toContain("## Executive Readout");
+    expect(files.get("wiki/projects/existing-wiki-project/index.md")).toContain("## Current Direction");
+    expect(files.get("wiki/projects/existing-wiki-project/index.md")).toContain("## References");
+    expect(files.get("wiki/index.md")).toContain("wiki/projects/existing-wiki-project/index.md");
+    expect(files.get("wiki/log.md")).toContain("paperclip-distill | proposed");
+    const bindingWrites = harness.dbExecutes.filter((execute) => execute.sql.includes("paperclip_page_bindings"));
+    expect(bindingWrites).toHaveLength(4);
+    expect(bindingWrites[0].params).toEqual(expect.arrayContaining([
+      COMPANY_ID,
+      "default",
+      project.id,
+      null,
+      "wiki/projects/existing-wiki-project/standup.md",
+      result.patches[0].sourceHash,
+    ]));
+  });
+
+  it("refuses auto-apply Paperclip project page patches in authenticated/public deployments", async () => {
+    process.env.PAPERCLIP_DEPLOYMENT_MODE = "authenticated";
+    process.env.PAPERCLIP_DEPLOYMENT_EXPOSURE = "public";
+    const harness = createTestHarness({ manifest, config: { autoApplyIngestPatches: true } });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-77777777779a",
+      identifier: "PAP-4101",
+      title: "Implement project page writer",
+      description: "Implementation completed enough to publish the generated project page.",
+      status: "done",
+      projectId: project.id,
+      updatedAt: new Date("2026-05-04T10:00:00Z"),
+    });
+    const files = new Map<string, string>([
+      ["wiki/index.md", DEFAULT_INDEX],
+      ["wiki/log.md", DEFAULT_LOG],
+    ]);
+    const writes: string[] = [];
+    harness.seed({ projects: [project], issues: [issue] });
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const contents = files.get(relativePath);
+      if (contents == null) throw new Error(`missing ${relativePath}`);
+      return contents;
+    };
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push(relativePath);
+      files.set(relativePath, contents);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{
+      status: string;
+      appliedPages: string[];
+      warnings: string[];
+    }>("distill-paperclip-project-page", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+      autoApply: true,
+      maxCharacters: 20000,
+      includeSupportingPages: false,
+    });
+
+    expect(result.status).toBe("review_required");
+    expect(result.appliedPages).toEqual([]);
+    expect(writes).toHaveLength(0);
+    expect(result.warnings).toContain(
+      "Authenticated/public deployments always require manual review before wiki writes.",
+    );
+  });
+
+  it("refuses stale project page hashes before writing generated Paperclip pages", async () => {
+    const harness = createTestHarness({ manifest, config: { autoApplyIngestPatches: true } });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777793",
+      identifier: "PAP-4102",
+      title: "Publish project page",
+      description: "Ready to publish.",
+      status: "done",
+      projectId: project.id,
+    });
+    const files = new Map<string, string>([
+      ["wiki/projects/existing-wiki-project/index.md", "# Existing\n"],
+      ["wiki/index.md", DEFAULT_INDEX],
+      ["wiki/log.md", DEFAULT_LOG],
+    ]);
+    const writes: string[] = [];
+    harness.seed({ projects: [project], issues: [issue] });
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const contents = files.get(relativePath);
+      if (contents == null) throw new Error(`missing ${relativePath}`);
+      return contents;
+    };
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push(relativePath);
+      files.set(relativePath, contents);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    await expect(harness.performAction("distill-paperclip-project-page", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+      autoApply: true,
+      expectedProjectPageHash: "stale",
+      includeSupportingPages: false,
+    })).rejects.toThrow("Refusing to overwrite");
+    expect(writes).toHaveLength(0);
+  });
+
+  it("skips low-signal Paperclip source windows without proposing wiki writes", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-777777777794",
+      identifier: "PAP-4103",
+      title: "Routine heartbeat",
+      description: "",
+      status: "todo",
+      projectId: project.id,
+    });
+    const writes: string[] = [];
+    harness.seed({ projects: [project], issues: [issue] });
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push(relativePath);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{ status: string; reason: string; patches: unknown[] }>("distill-paperclip-project-page", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+      maxCharacters: 20000,
+    });
+
+    expect(result.status).toBe("skipped");
+    expect(result.reason).toBe("low_signal");
+    expect(result.patches).toEqual([]);
+    expect(writes).toHaveLength(0);
+  });
+
+  it("bootstraps required local wiki files through the local folder API", async () => {
+    const harness = createTestHarness({ manifest });
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{ writtenFiles: string[]; managedSkills: WikiSkillResource[] }>("bootstrap-root", {
+      companyId: COMPANY_ID,
+      path: "/tmp/company-wiki",
+    });
+
+    expect(result.writtenFiles).toContain("AGENTS.md");
+    expect(result.writtenFiles).toContain("IDEA.md");
+    expect(result.managedSkills[0]).toMatchObject({
+      status: "created",
+      resourceKey: WIKI_MAINTAINER_SKILL_KEY,
+      details: { key: WIKI_MAINTAINER_SKILL_CANONICAL_KEY },
+    });
+    expect(writes.map((write) => write.path)).toEqual([
+      ".gitignore",
+      "AGENTS.md",
+      "IDEA.md",
+      "wiki/index.md",
+      "wiki/log.md",
+      "raw/.gitkeep",
+      "wiki/sources/.gitkeep",
+      "wiki/projects/.gitkeep",
+      "wiki/entities/.gitkeep",
+      "wiki/concepts/.gitkeep",
+      "wiki/synthesis/.gitkeep",
+    ]);
+    expect(writes.find((write) => write.path === "AGENTS.md")?.contents).toContain("LLM Wiki Schema");
+    expect(writes.find((write) => write.path === "AGENTS.md")?.contents).toContain("wiki/projects/<project-slug>/index.md");
+    expect(writes.find((write) => write.path === "AGENTS.md")?.contents).toContain("wiki/projects/<project-slug>/standup.md");
+  });
+
+  it("creates a managed space with an immediately readable baseline skeleton", async () => {
+    const harness = createTestHarness({ manifest });
+    const files = new Map<string, string>();
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const value = files.get(relativePath);
+      if (value == null) throw new Error(`missing ${relativePath}`);
+      return value;
+    };
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      files.set(relativePath, contents);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const created = await harness.performAction<{
+      space: { slug: string; pathPrefix: string | null };
+    }>("create-space", {
+      companyId: COMPANY_ID,
+      displayName: "QA Space",
+    });
+
+    expect(created.space).toMatchObject({
+      slug: "qa-space",
+      pathPrefix: "spaces/qa-space",
+    });
+    await expect(harness.ctx.localFolders.readText(
+      COMPANY_ID,
+      "wiki-root",
+      "spaces/qa-space/AGENTS.md",
+    )).resolves.toContain("LLM Wiki Schema");
+    expect(files.get("spaces/qa-space/IDEA.md")).toBe(DEFAULT_IDEA);
+    expect(files.has("spaces/qa-space/raw/.gitkeep")).toBe(true);
+    expect(files.has("spaces/qa-space/projects/.gitkeep")).toBe(false);
+    expect(files.has("spaces/qa-space/wiki/projects/.gitkeep")).toBe(true);
+    expect(files.has("spaces/qa-space/wiki/index.md")).toBe(true);
+  });
+
+  it("prevents the default space from being archived through update-space", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+
+    await expect(harness.performAction("update-space", {
+      companyId: COMPANY_ID,
+      spaceSlug: "default",
+      status: "archived",
+    })).rejects.toThrow("The default LLM Wiki space cannot be archived.");
+    const defaultSpaceInsert = harness.dbExecutes.find((execute) =>
+      execute.sql.includes("INSERT INTO") && execute.sql.includes("wiki_spaces"));
+    expect(defaultSpaceInsert?.params?.[0]).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-8[0-9a-f]{3}-[0-9a-f]{12}$/);
+    expect(harness.dbExecutes.some((execute) =>
+      execute.sql.includes("UPDATE") &&
+      execute.sql.includes("wiki_spaces") &&
+      execute.params?.includes("archived"))).toBe(false);
+  });
+
+  it("archives a non-default space through update-space without re-resolving it as active", async () => {
+    const harness = createTestHarness({ manifest });
+    const spaceRow = wikiSpaceRow({
+      id: "77777777-7777-4777-8777-7777777777b1",
+      slug: "qa-space",
+      displayName: "QA Space",
+      pathPrefix: "spaces/qa-space",
+      status: "active",
+      settings: { owner: "qa" },
+    });
+    let archived = false;
+    const originalQuery = harness.ctx.db.query.bind(harness.ctx.db);
+    harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+      harness.dbQueries.push({ sql, params });
+      if (sql.includes("wiki_spaces") && params?.[2] === "qa-space") {
+        return archived && sql.includes("status <> 'archived'") ? [] as T[] : [spaceRow] as T[];
+      }
+      return originalQuery<T>(sql, params);
+    };
+    const originalExecute = harness.ctx.db.execute.bind(harness.ctx.db);
+    harness.ctx.db.execute = async (sql: string, params?: unknown[]) => {
+      if (sql.includes("UPDATE") && sql.includes("wiki_spaces") && params?.includes("archived")) archived = true;
+      return originalExecute(sql, params);
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const updated = await harness.performAction<{
+      status: string;
+      space: { slug: string; displayName: string; status: string; settings: Record<string, unknown> };
+    }>("update-space", {
+      companyId: COMPANY_ID,
+      spaceSlug: "qa-space",
+      displayName: "Archived QA",
+      settings: { archivedBy: "test" },
+      status: "archived",
+    });
+
+    expect(updated.status).toBe("ok");
+    expect(updated.space).toMatchObject({
+      slug: "qa-space",
+      displayName: "Archived QA",
+      status: "archived",
+      settings: { owner: "qa", archivedBy: "test" },
+    });
+    expect(archived).toBe(true);
+  });
+
+  it("restores an archived non-default space through update-space", async () => {
+    const harness = createTestHarness({ manifest });
+    const spaceRow = wikiSpaceRow({
+      id: "77777777-7777-4777-8777-7777777777b2",
+      slug: "qa-space",
+      displayName: "QA Space",
+      pathPrefix: "spaces/qa-space",
+      status: "archived",
+    });
+    let restored = false;
+    const originalQuery = harness.ctx.db.query.bind(harness.ctx.db);
+    harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+      harness.dbQueries.push({ sql, params });
+      if (sql.includes("wiki_spaces") && params?.[2] === "qa-space") {
+        if (!restored && sql.includes("status <> 'archived'")) return [] as T[];
+        return [{
+          ...spaceRow,
+          status: restored ? "active" : "archived",
+        }] as T[];
+      }
+      return originalQuery<T>(sql, params);
+    };
+    const originalExecute = harness.ctx.db.execute.bind(harness.ctx.db);
+    harness.ctx.db.execute = async (sql: string, params?: unknown[]) => {
+      if (sql.includes("UPDATE") && sql.includes("wiki_spaces") && params?.includes("active")) restored = true;
+      return originalExecute(sql, params);
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const updated = await harness.performAction<{
+      status: string;
+      space: { slug: string; status: string };
+    }>("update-space", {
+      companyId: COMPANY_ID,
+      spaceSlug: "qa-space",
+      status: "active",
+    });
+
+    expect(updated.status).toBe("ok");
+    expect(updated.space).toMatchObject({
+      slug: "qa-space",
+      status: "active",
+    });
+    expect(restored).toBe(true);
+  });
+
+  it("rejects unknown space statuses through update-space", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+
+    await expect(harness.performAction("update-space", {
+      companyId: COMPANY_ID,
+      spaceSlug: "default",
+      status: "suspended",
+    })).rejects.toThrow("LLM Wiki space status must be active or archived.");
+    expect(harness.dbExecutes.some((execute) =>
+      execute.sql.includes("UPDATE") &&
+      execute.sql.includes("wiki_spaces") &&
+      execute.params?.includes("suspended"))).toBe(false);
+  });
+
+  it("omits archived spaces from the spaces data API", async () => {
+    const harness = createTestHarness({ manifest });
+    const activeRow = wikiSpaceRow({
+      id: "77777777-7777-4777-8777-7777777777a1",
+      slug: "team-research",
+      displayName: "Team Research",
+      pathPrefix: "spaces/team-research",
+      status: "active",
+    });
+    const archivedRow = wikiSpaceRow({
+      id: "77777777-7777-4777-8777-7777777777a2",
+      slug: "qa-team-lock",
+      displayName: "QA Team Lock",
+      pathPrefix: "spaces/qa-team-lock",
+      status: "archived",
+    });
+    harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+      harness.dbQueries.push({ sql, params });
+      if (sql.includes("wiki_spaces") && sql.includes("ORDER BY CASE WHEN slug = 'default'")) {
+        const rows = [defaultWikiSpaceRow(), activeRow];
+        if (!sql.includes("status <> 'archived'")) rows.push(archivedRow);
+        return rows as T[];
+      }
+      if (sql.includes("wiki_spaces") && sql.includes("slug = 'default'")) {
+        return [defaultWikiSpaceRow()] as T[];
+      }
+      return [] as T[];
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.getData<{ spaces: Array<{ slug: string }> }>("spaces", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+    });
+
+    expect(result.spaces.map((space) => space.slug)).toEqual(["default", "team-research"]);
+    expect(harness.dbQueries.some((query) => query.sql.includes("status <> 'archived'"))).toBe(true);
+  });
+
+  it("captures raw sources into local files and plugin metadata", async () => {
+    const harness = createTestHarness({ manifest });
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{ rawPath: string; hash: string }>("capture-source", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      title: "Plugin Boundaries",
+      contents: "# Plugin Boundaries\n\nKeep wiki logic in the plugin.",
+    });
+
+    expect(result.rawPath).toMatch(/^raw\/\d{4}-\d{2}-\d{2}-plugin-boundaries-/);
+    expect(result.hash).toHaveLength(64);
+    expect(writes[0]).toMatchObject({ path: result.rawPath });
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_sources"))).toBe(true);
+  });
+
+  it("preserves manual source ingest for non-default spaces while refusing Paperclip distillation there", async () => {
+    const harness = createTestHarness({ manifest });
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+    harness.seed({
+      agents: [wikiMaintainerAgent()],
+      projects: [existingProject()],
+    });
+    const spaces = new Map<string, Record<string, unknown>>();
+    const originalQuery = harness.ctx.db.query.bind(harness.ctx.db);
+    harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+      if (sql.includes("wiki_spaces")) {
+        const slug = typeof params?.[2] === "string" ? params[2] : null;
+        if (slug && spaces.has(slug)) return [spaces.get(slug)] as T[];
+      }
+      return originalQuery<T>(sql, params);
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const created = await harness.performAction<{
+      space: { id: string; companyId: string; wikiId: string; slug: string; displayName: string; pathPrefix: string | null };
+    }>("create-space", {
+      companyId: COMPANY_ID,
+      displayName: "Team Research",
+    });
+    spaces.set(created.space.slug, {
+      id: created.space.id,
+      company_id: created.space.companyId,
+      wiki_id: created.space.wikiId,
+      slug: created.space.slug,
+      display_name: created.space.displayName,
+      space_type: "local_folder",
+      folder_mode: "managed_subfolder",
+      root_folder_key: "wiki-root",
+      path_prefix: created.space.pathPrefix,
+      configured_root_path: null,
+      access_scope: "shared",
+      owner_user_id: null,
+      owner_agent_id: null,
+      team_key: null,
+      settings: {},
+      status: "active",
+      created_at: null,
+      updated_at: null,
+    });
+
+    const source = await harness.performAction<{ rawPath: string; spaceSlug: string }>("capture-source", {
+      companyId: COMPANY_ID,
+      spaceSlug: created.space.slug,
+      title: "Team notes",
+      contents: "# Team notes\n\nManual source ingest still belongs to the selected space.",
+    });
+
+    expect(source.spaceSlug).toBe(created.space.slug);
+    expect(writes.map((write) => write.path)).toContain(`spaces/${created.space.slug}/${source.rawPath}`);
+    await expect(harness.performAction("distill-paperclip-now", {
+      companyId: COMPANY_ID,
+      spaceSlug: created.space.slug,
+      projectId: existingProject().id,
+    })).rejects.toThrow("Paperclip ingestion policy denied queue");
+  });
+
+  it("fails closed for direct Paperclip ingestion actions against restricted spaces", async () => {
+    const harness = createTestHarness({ manifest });
+    harness.seed({
+      agents: [wikiMaintainerAgent()],
+      projects: [existingProject()],
+    });
+
+    await plugin.definition.setup(harness.ctx);
+    const created = await harness.performAction<{
+      space: { slug: string; accessScope: string };
+    }>("create-space", {
+      companyId: COMPANY_ID,
+      displayName: "Private Notes",
+      accessScope: "personal",
+    });
+
+    expect(created.space.accessScope).toBe("personal");
+    const originalQuery = harness.ctx.db.query.bind(harness.ctx.db);
+    harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+      if (sql.includes("wiki_spaces") && params?.[2] === created.space.slug) {
+        return [{
+          id: "77777777-7777-4777-8777-7777777777b2",
+          company_id: COMPANY_ID,
+          wiki_id: "default",
+          slug: created.space.slug,
+          display_name: "Private Notes",
+          space_type: "local_folder",
+          folder_mode: "managed_subfolder",
+          root_folder_key: "wiki-root",
+          path_prefix: `spaces/${created.space.slug}`,
+          configured_root_path: null,
+          access_scope: "personal",
+          owner_user_id: null,
+          owner_agent_id: null,
+          team_key: null,
+          settings: {},
+          status: "active",
+          created_at: null,
+          updated_at: null,
+        }] as T[];
+      }
+      return originalQuery<T>(sql, params);
+    };
+    await expect(harness.performAction("distill-paperclip-now", {
+      companyId: COMPANY_ID,
+      spaceSlug: created.space.slug,
+      projectId: existingProject().id,
+    })).rejects.toThrow("Paperclip ingestion policy denied queue");
+
+    const operations = await harness.ctx.issues.list({
+      companyId: COMPANY_ID,
+      originKindPrefix: String(OPERATION_ORIGIN_KIND),
+    });
+    expect(operations).toHaveLength(0);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("paperclip_distillation_work_items"))).toBe(false);
+  });
+
+  it("re-checks Paperclip ingestion policy at execution time for queued work", async () => {
+    const harness = createTestHarness({ manifest });
+    const project = existingProject();
+    const issue = paperclipIssue({
+      id: "77777777-7777-4777-8777-7777777777b0",
+      identifier: "PAP-4111",
+      title: "Queued distillation source",
+      description: "Accepted queued work should not run after policy changes.",
+      projectId: project.id,
+      status: "done",
+    });
+    harness.seed({ agents: [wikiMaintainerAgent()], projects: [project], issues: [issue] });
+
+    await plugin.definition.setup(harness.ctx);
+    const queued = await harness.performAction<{ status: string }>("distill-paperclip-now", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+    });
+    expect(queued.status).toBe("queued");
+
+    const originalQuery = harness.ctx.db.query.bind(harness.ctx.db);
+    harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+      if (sql.includes("wiki_spaces") && sql.includes("slug = 'default'")) {
+        return [{
+          id: "77777777-7777-4777-8777-7777777777b1",
+          company_id: COMPANY_ID,
+          wiki_id: "default",
+          slug: "default",
+          display_name: "default",
+          space_type: "local_folder",
+          folder_mode: "managed_subfolder",
+          root_folder_key: "wiki-root",
+          path_prefix: null,
+          configured_root_path: null,
+          access_scope: "personal",
+          owner_user_id: null,
+          owner_agent_id: null,
+          team_key: null,
+          settings: {},
+          status: "active",
+          created_at: null,
+          updated_at: null,
+        }] as T[];
+      }
+      return originalQuery<T>(sql, params);
+    };
+
+    await expect(harness.performAction("create-paperclip-distillation-run", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+    })).rejects.toThrow("personal spaces cannot ingest Paperclip sources");
+    expect(harness.dbExecutes.some((execute) =>
+      execute.sql.includes("paperclip_distillation_runs") && execute.sql.includes("'source_ready'"))).toBe(false);
+  });
+
+  it("queues Paperclip ingestion backfills for every selected project scope", async () => {
+    const harness = createTestHarness({ manifest });
+    await plugin.definition.setup(harness.ctx);
+
+    const queued = await harness.performAction<{
+      status: string;
+      workItemId: string;
+      issueId: string;
+      workItems: Array<{ workItemId: string; issueId: string; projectId: string | null; rootIssueId: string | null }>;
+    }>("queue-paperclip-ingestion-backfill", {
+      companyId: COMPANY_ID,
+      sourceScope: {
+        kind: "selected_projects",
+        projectIds: [
+          "77777777-7777-4777-8777-7777777777a1",
+          "77777777-7777-4777-8777-7777777777a2",
+        ],
+      },
+      backfillStartAt: "2026-05-01T00:00:00.000Z",
+      backfillEndAt: "2026-05-02T00:00:00.000Z",
+    });
+
+    expect(queued.status).toBe("queued");
+    expect(queued.workItems).toHaveLength(2);
+    expect(queued.workItemId).toBe(queued.workItems[0]?.workItemId);
+    expect(queued.issueId).toBe(queued.workItems[0]?.issueId);
+    expect(queued.workItems.map((item) => item.projectId)).toEqual([
+      "77777777-7777-4777-8777-7777777777a1",
+      "77777777-7777-4777-8777-7777777777a2",
+    ]);
+    expect(harness.dbExecutes.filter((execute) => execute.sql.includes("paperclip_distillation_work_items"))).toHaveLength(2);
+  });
+
+  it("rejects oversized Paperclip ingestion profile and source-scope payloads", async () => {
+    const harness = createTestHarness({ manifest });
+
+    await plugin.definition.setup(harness.ctx);
+    await expect(harness.performAction("update-event-ingestion-settings", {
+      companyId: COMPANY_ID,
+      enabled: true,
+      maxCharacters: 20001,
+      sources: { issues: true },
+    })).rejects.toThrow("maxCharacters exceeds the hard Paperclip ingestion cap");
+
+    await expect(harness.performAction("enable-paperclip-distillation-active-projects", {
+      companyId: COMPANY_ID,
+      limit: 26,
+    })).rejects.toThrow("fan-out exceeds the hard cap");
+
+    await expect(harness.performAction("assemble-paperclip-source-bundle", {
+      companyId: COMPANY_ID,
+      projectId: "77777777-7777-4777-8777-777777777777",
+      rootIssueId: "77777777-7777-4777-8777-777777777778",
+    })).rejects.toThrow("either projectId or rootIssueId");
+
+    await expect(harness.performAction("assemble-paperclip-source-bundle", {
+      companyId: COMPANY_ID,
+      projectId: "77777777-7777-4777-8777-777777777777",
+      maxCharacters: 60001,
+    })).rejects.toThrow("maxCharacters exceeds the hard Paperclip ingestion cap");
+  });
+
+  it("keeps default-space files at the root and isolates managed spaces under slug prefixes", async () => {
+    const harness = createTestHarness({ manifest });
+    const files = new Map<string, string>();
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const value = files.get(relativePath);
+      if (value == null) throw new Error(`missing ${relativePath}`);
+      return value;
+    };
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      files.set(relativePath, contents);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+    const spaces = new Map<string, Record<string, unknown>>();
+    const originalQuery = harness.ctx.db.query.bind(harness.ctx.db);
+    harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+      if (sql.includes("wiki_spaces")) {
+        const slug = typeof params?.[2] === "string" ? params[2] : null;
+        if (slug && spaces.has(slug)) return [spaces.get(slug)] as T[];
+      }
+      return originalQuery<T>(sql, params);
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const created = await harness.performAction<{
+      space: { id: string; companyId: string; wikiId: string; slug: string; displayName: string; pathPrefix: string | null };
+    }>("create-space", {
+      companyId: COMPANY_ID,
+      displayName: "Research Space",
+    });
+    spaces.set(created.space.slug, {
+      id: created.space.id,
+      company_id: created.space.companyId,
+      wiki_id: created.space.wikiId,
+      slug: created.space.slug,
+      display_name: created.space.displayName,
+      space_type: "local_folder",
+      folder_mode: "managed_subfolder",
+      root_folder_key: "wiki-root",
+      path_prefix: created.space.pathPrefix,
+      configured_root_path: null,
+      access_scope: "shared",
+      owner_user_id: null,
+      owner_agent_id: null,
+      team_key: null,
+      settings: {},
+      status: "active",
+      created_at: null,
+      updated_at: null,
+    });
+    await harness.performAction("bootstrap-space", {
+      companyId: COMPANY_ID,
+      spaceSlug: created.space.slug,
+    });
+    await harness.performAction("write-page", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      path: "wiki/concepts/shared.md",
+      contents: "# Default Shared\n",
+    });
+    await harness.performAction("write-page", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      spaceSlug: created.space.slug,
+      path: "wiki/concepts/shared.md",
+      contents: "# Space Shared\n",
+    });
+    await harness.performAction("capture-source", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      rawPath: "raw/shared.md",
+      title: "Shared Source",
+      contents: "# Default Raw\n",
+    });
+    await harness.performAction("capture-source", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      spaceSlug: created.space.slug,
+      rawPath: "raw/shared.md",
+      title: "Shared Source",
+      contents: "# Space Raw\n",
+    });
+
+    expect(created.space).toMatchObject({
+      slug: "research-space",
+      pathPrefix: "spaces/research-space",
+    });
+    expect(files.get("wiki/concepts/shared.md")).toBe("# Default Shared\n");
+    expect(files.get("spaces/research-space/wiki/concepts/shared.md")).toBe("# Space Shared\n");
+    expect(files.get("raw/shared.md")).toBe("# Default Raw\n");
+    expect(files.get("spaces/research-space/raw/shared.md")).toBe("# Space Raw\n");
+    expect(writes.map((write) => write.path)).not.toContain("spaces/default/wiki/concepts/shared.md");
+
+    const pageWrites = harness.dbExecutes.filter((execute) => execute.sql.includes("wiki_pages"));
+    const sourceWrites = harness.dbExecutes.filter((execute) => execute.sql.includes("wiki_sources"));
+    expect(pageWrites.every((write) => write.sql.includes("space_id"))).toBe(true);
+    expect(sourceWrites.every((write) => write.sql.includes("space_id"))).toBe(true);
+  });
+
+  it("ingests source metadata and creates a hidden plugin-operation issue", async () => {
+    const harness = createTestHarness({ manifest });
+    harness.seed({ agents: [wikiMaintainerAgent()] });
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const result = await harness.performAction<{
+      source: { rawPath: string; title: string; hash: string };
+      operation: { operationId: string; issue: { originKind: string; originId: string | null; billingCode: string | null; assigneeAgentId: string | null } };
+    }>("ingest-source", {
+      companyId: COMPANY_ID,
+      wikiId: "engineering",
+      sourceType: "url",
+      title: "Standalone Plugin Notes",
+      url: "https://example.test/wiki",
+      contents: "# Standalone Plugin Notes\n\nKeep wiki behavior in the plugin package.",
+      rawPath: "raw/standalone-plugin-notes.md",
+      metadata: { importedBy: "alpha-verification" },
+    });
+
+    expect(result.source.rawPath).toBe("raw/standalone-plugin-notes.md");
+    expect(result.source.title).toBe("Standalone Plugin Notes");
+    expect(result.source.hash).toHaveLength(64);
+    expect(writes).toEqual([
+      expect.objectContaining({
+        path: "raw/standalone-plugin-notes.md",
+        contents: expect.stringContaining("Keep wiki behavior in the plugin package."),
+      }),
+    ]);
+    expect(result.operation.issue.originKind).toBe(`${OPERATION_ORIGIN_KIND}:ingest`);
+    expect(result.operation.issue.originId).toBe(`wiki:engineering:operation:${result.operation.operationId}`);
+    expect(result.operation.issue.billingCode).toBe("plugin-llm-wiki:engineering");
+    expect(result.operation.issue.assigneeAgentId).toBe(wikiMaintainerAgent().id);
+
+    const sourceInsert = harness.dbExecutes.find((execute) => execute.sql.includes("wiki_sources"));
+    expect(sourceInsert?.params).toEqual(expect.arrayContaining([
+      COMPANY_ID,
+      "engineering",
+      "url",
+      "Standalone Plugin Notes",
+      "https://example.test/wiki",
+      "raw/standalone-plugin-notes.md",
+      JSON.stringify({ importedBy: "alpha-verification" }),
+    ]));
+    const operationInsert = harness.dbExecutes.find((execute) => execute.sql.includes("wiki_operations"));
+    expect(operationInsert?.params).toEqual(expect.arrayContaining([
+      result.operation.operationId,
+      COMPANY_ID,
+      "engineering",
+      "ingest",
+      "queued",
+    ]));
+  });
+
+  it("rejects oversized source capture before raw writes or operation creation", async () => {
+    const harness = createTestHarness({ manifest, config: { maxSourceBytes: 16 } });
+    harness.seed({ agents: [wikiMaintainerAgent()] });
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    await expect(harness.performAction("ingest-source", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      sourceType: "text",
+      title: "Oversized source",
+      contents: "x".repeat(17),
+    })).rejects.toThrow("exceeds the configured LLM Wiki source limit");
+
+    expect(writes).toHaveLength(0);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_sources"))).toBe(false);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_operations"))).toBe(false);
+    const operations = await harness.ctx.issues.list({
+      companyId: COMPANY_ID,
+      originKindPrefix: String(OPERATION_ORIGIN_KIND),
+    });
+    expect(operations).toHaveLength(0);
+  });
+
+  it("writes pages atomically, records metadata, and rejects stale hashes", async () => {
+    const harness = createTestHarness({ manifest });
+    const files = new Map<string, string>([
+      ["wiki/concepts/plugin-boundaries.md", "# Old Title\n"],
+    ]);
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const value = files.get(relativePath);
+      if (value == null) throw new Error("missing");
+      return value;
+    };
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      files.set(relativePath, contents);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+    const staleWrite = harness.executeTool("wiki_write_page", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      path: "wiki/concepts/plugin-boundaries.md",
+      contents: "# New Title\n",
+      expectedHash: "stale",
+    });
+    await expect(staleWrite).rejects.toThrow("Refusing to overwrite");
+
+    const result = await harness.executeTool<{ data?: { hash: string } }>("wiki_write_page", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      path: "wiki/concepts/plugin-boundaries.md",
+      contents: "# Plugin Boundaries\n\nSee [Knowledge](wiki/areas/knowledge.md).",
+    });
+
+    expect(result.data?.hash).toHaveLength(64);
+    expect(files.get("wiki/concepts/plugin-boundaries.md")).toContain("Plugin Boundaries");
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_pages"))).toBe(true);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_page_revisions"))).toBe(true);
+  });
+
+  it("blocks agent-tool writes to AGENTS.md but allows explicit board edits", async () => {
+    const harness = createTestHarness({ manifest });
+    const files = new Map<string, string>([
+      ["AGENTS.md", "# LLM Wiki Maintainer\n\nOriginal instructions.\n"],
+    ]);
+    harness.ctx.localFolders.readText = async (_companyId, _folderKey, relativePath) => {
+      const value = files.get(relativePath);
+      if (value == null) throw new Error("missing");
+      return value;
+    };
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      files.set(relativePath, contents);
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+
+    await plugin.definition.setup(harness.ctx);
+
+    await expect(harness.executeTool("wiki_write_page", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      path: "AGENTS.md",
+      contents: "# LLM Wiki Maintainer\n\nCompromised instructions.\n",
+    })).rejects.toThrow("Refusing to overwrite protected wiki control file AGENTS.md");
+
+    const result = await harness.performAction<{ hash: string }>("write-page", {
+      companyId: COMPANY_ID,
+      wikiId: "default",
+      path: "AGENTS.md",
+      contents: "# LLM Wiki Maintainer\n\nBoard-updated instructions.\n",
+    });
+
+    expect(result.hash).toHaveLength(64);
+    expect(files.get("AGENTS.md")).toContain("Board-updated instructions.");
+  });
+
+  it("creates plugin-operation issues for LLM workflows", async () => {
+    const harness = createTestHarness({ manifest });
+    harness.seed({ agents: [wikiMaintainerAgent()] });
+    await plugin.definition.setup(harness.ctx);
+
+    const result = await harness.performAction<{ issue: { originKind: string; billingCode: string | null } }>(
+      "create-operation",
+      {
+        companyId: COMPANY_ID,
+        operationType: "query",
+        title: "Ask the wiki about plugin boundaries",
+        prompt: "Which files own wiki behavior?",
+      },
+    );
+
+    expect(result.issue.originKind).toBe(`${OPERATION_ORIGIN_KIND}:query`);
+    expect(result.issue.billingCode).toBe("plugin-llm-wiki:default");
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_resource_bindings"))).toBe(true);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_operations"))).toBe(true);
+  });
+
+  it("stamps resolved space context into hidden operation issues and operation metadata", async () => {
+    const harness = createTestHarness({ manifest });
+    harness.seed({ agents: [wikiMaintainerAgent()] });
+    const spaces = new Map<string, Record<string, unknown>>();
+    const originalQuery = harness.ctx.db.query.bind(harness.ctx.db);
+    harness.ctx.db.query = async <T,>(sql: string, params?: unknown[]) => {
+      if (sql.includes("wiki_spaces")) {
+        const slug = typeof params?.[2] === "string" ? params[2] : null;
+        if (slug && spaces.has(slug)) return [spaces.get(slug)] as T[];
+      }
+      return originalQuery<T>(sql, params);
+    };
+    await plugin.definition.setup(harness.ctx);
+
+    const created = await harness.performAction<{
+      space: { id: string; companyId: string; wikiId: string; slug: string; displayName: string; pathPrefix: string | null };
+    }>("create-space", {
+      companyId: COMPANY_ID,
+      displayName: "Research Space",
+    });
+    spaces.set(created.space.slug, {
+      id: created.space.id,
+      company_id: created.space.companyId,
+      wiki_id: created.space.wikiId,
+      slug: created.space.slug,
+      display_name: created.space.displayName,
+      space_type: "local_folder",
+      folder_mode: "managed_subfolder",
+      root_folder_key: "wiki-root",
+      path_prefix: created.space.pathPrefix,
+      configured_root_path: null,
+      access_scope: "shared",
+      owner_user_id: null,
+      owner_agent_id: null,
+      team_key: null,
+      settings: {},
+      status: "active",
+      created_at: null,
+      updated_at: null,
+    });
+
+    const result = await harness.performAction<{
+      operationId: string;
+      issue: { title: string; description: string | null; billingCode: string | null; originId: string | null };
+    }>("create-operation", {
+      companyId: COMPANY_ID,
+      operationType: "lint",
+      title: "Run LLM Wiki lint",
+      prompt: "Audit wiki structure.",
+      spaceSlug: created.space.slug,
+    });
+
+    expect(result.issue.title).toBe("Run LLM Wiki lint [space: Research Space / research-space]");
+    expect(result.issue.description).toContain("Space: Research Space (research-space)");
+    expect(result.issue.description).toContain("Space root: wiki-root/spaces/research-space");
+    expect(result.issue.description).toContain("Pass wikiId `default` and spaceSlug `research-space`");
+    expect(result.issue.description).toContain("Manual ingest, query, lint, index, and file-as-page operations follow the named destination space");
+    expect(result.issue.billingCode).toBe("plugin-llm-wiki:default:research-space");
+    expect(result.issue.originId).toBe(`wiki:default:space:research-space:operation:${result.operationId}`);
+    const operationInsert = harness.dbExecutes.find((execute) =>
+      execute.sql.includes("wiki_operations") && execute.params?.[0] === result.operationId);
+    const metadata = JSON.parse(String(operationInsert?.params?.[8]));
+    expect(metadata).toMatchObject({
+      operationType: "lint",
+      operationId: result.operationId,
+      wikiId: "default",
+      spaceId: created.space.id,
+      spaceSlug: "research-space",
+      spaceName: "Research Space",
+      spaceRoot: "wiki-root/spaces/research-space",
+      billingCode: "plugin-llm-wiki:default:research-space",
+    });
+  });
+
+  it("uses selected existing agent and project bindings for new operations", async () => {
+    const harness = createTestHarness({ manifest });
+    const agent = existingAgent();
+    const project = existingProject();
+    harness.seed({ agents: [agent], projects: [project] });
+    await plugin.definition.setup(harness.ctx);
+
+    const selectedAgent = await harness.performAction<{ source: string; agentId: string }>("select-managed-agent", {
+      companyId: COMPANY_ID,
+      agentId: agent.id,
+    });
+    const selectedProject = await harness.performAction<{ source: string; projectId: string }>("select-managed-project", {
+      companyId: COMPANY_ID,
+      projectId: project.id,
+    });
+
+    expect(selectedAgent).toMatchObject({ source: "selected", agentId: agent.id });
+    expect(selectedProject).toMatchObject({ source: "selected", projectId: project.id });
+    expect(harness.dbExecutes.filter((execute) => execute.sql.includes("wiki_resource_bindings"))).toHaveLength(2);
+
+    harness.ctx.db.query = async <T = Record<string, unknown>>(sql: string, params?: unknown[]) => {
+      harness.dbQueries.push({ sql, params });
+      if (sql.includes("wiki_resource_bindings") && params?.[2] === "agent") {
+        return [{ resolved_id: agent.id, metadata: { source: "selected-existing" } }] as T[];
+      }
+      if (sql.includes("wiki_resource_bindings") && params?.[2] === "project") {
+        return [{ resolved_id: project.id, metadata: { source: "selected-existing" } }] as T[];
+      }
+      if (sql.includes("wiki_operations")) return [{ count: "0" }] as T[];
+      return [];
+    };
+
+    const result = await harness.performAction<{
+      issue: { assigneeAgentId: string | null; projectId: string | null };
+    }>("create-operation", {
+      companyId: COMPANY_ID,
+      operationType: "lint",
+      title: "Lint selected wiki",
+    });
+
+    expect(result.issue.assigneeAgentId).toBe(agent.id);
+    expect(result.issue.projectId).toBe(project.id);
+  });
+
+  it("starts query sessions, records run ids, and forwards session events to plugin streams", async () => {
+    const harness = createTestHarness({ manifest });
+    harness.seed({ agents: [wikiMaintainerAgent()] });
+    const streamEvents: unknown[] = [];
+    harness.ctx.streams.emit = (_channel, event) => {
+      streamEvents.push(event);
+    };
+    await plugin.definition.setup(harness.ctx);
+
+    const result = await harness.performAction<{
+      operationId: string;
+      querySessionId: string;
+      sessionId: string;
+      runId: string;
+      channel: string;
+    }>("start-query", {
+      companyId: COMPANY_ID,
+      question: "Which files own wiki behavior?",
+    });
+
+    expect(result.querySessionId).toBe(result.operationId);
+    expect(result.channel).toBe(`llm-wiki:query:${result.operationId}`);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_query_sessions"))).toBe(true);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("run_ids"))).toBe(true);
+
+    harness.simulateSessionEvent(result.sessionId, {
+      runId: result.runId,
+      seq: 1,
+      eventType: "chunk",
+      stream: "stdout",
+      message: "Keep wiki behavior in the plugin.",
+      payload: null,
+    });
+    harness.simulateSessionEvent(result.sessionId, {
+      runId: result.runId,
+      seq: 2,
+      eventType: "done",
+      stream: "system",
+      message: "Run completed",
+      payload: null,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(streamEvents).toEqual(expect.arrayContaining([
+      expect.objectContaining({ type: "query.started", operationId: result.operationId }),
+      expect.objectContaining({ type: "agent.event", message: "Keep wiki behavior in the plugin." }),
+      expect.objectContaining({ type: "query.done", answer: "Keep wiki behavior in the plugin." }),
+    ]));
+    expect(harness.dbExecutes.some((execute) =>
+      execute.sql.includes("wiki_query_sessions") && execute.params?.includes("completed"),
+    )).toBe(true);
+  });
+
+  it("files a streamed query answer as a page through a hidden file-as-page operation", async () => {
+    const harness = createTestHarness({ manifest });
+    harness.seed({ agents: [wikiMaintainerAgent()] });
+    const writes: Array<{ path: string; contents: string }> = [];
+    harness.ctx.localFolders.writeTextAtomic = async (_companyId, _folderKey, relativePath, contents) => {
+      writes.push({ path: relativePath, contents });
+      return harness.ctx.localFolders.status(COMPANY_ID, "wiki-root");
+    };
+    await plugin.definition.setup(harness.ctx);
+
+    const result = await harness.performAction<{ path: string; operationId: string; page: { revisionId: string } }>(
+      "file-as-page",
+      {
+        companyId: COMPANY_ID,
+        querySessionId: "33333333-3333-4333-8333-333333333333",
+        question: "Where should wiki code live?",
+        answer: "Wiki-specific code lives in the standalone plugin package.",
+        path: "wiki/concepts/plugin-boundaries.md",
+        title: "Plugin Boundaries",
+      },
+    );
+
+    expect(result.path).toBe("wiki/concepts/plugin-boundaries.md");
+    expect(writes[0]).toMatchObject({ path: "wiki/concepts/plugin-boundaries.md" });
+    expect(writes[0]?.contents).toContain("Wiki-specific code lives in the standalone plugin package.");
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_operations"))).toBe(true);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("wiki_page_revisions"))).toBe(true);
+    expect(harness.dbExecutes.some((execute) => execute.sql.includes("filed_outputs"))).toBe(true);
+  });
+});
diff --git a/packages/plugins/plugin-llm-wiki/tests/screenshots/capture.mjs b/packages/plugins/plugin-llm-wiki/tests/screenshots/capture.mjs
new file mode 100644
index 00000000..4378127a
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/tests/screenshots/capture.mjs
@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+import { mkdirSync, copyFileSync, existsSync, readFileSync } from "node:fs";
+import { dirname, resolve, extname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import http from "node:http";
+import esbuild from "esbuild";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(__dirname, "..", "..");
+const outDir = resolve(pkgRoot, "dist", "screenshots");
+const screensDir = resolve(pkgRoot, "screenshots");
+
+mkdirSync(outDir, { recursive: true });
+mkdirSync(screensDir, { recursive: true });
+
+const entry = resolve(__dirname, "entry.tsx");
+
+const repoRoot = resolve(pkgRoot, "..", "..", "..");
+const reactPath = resolve(repoRoot, "node_modules/.pnpm/react@19.2.4/node_modules/react");
+const reactDomPath = resolve(repoRoot, "node_modules/.pnpm/react-dom@19.2.4_react@19.2.4/node_modules/react-dom");
+
+console.log("Bundling screenshot harness…");
+await esbuild.build({
+  entryPoints: [entry],
+  bundle: true,
+  format: "esm",
+  platform: "browser",
+  target: "es2022",
+  outfile: resolve(outDir, "bundle.js"),
+  jsx: "automatic",
+  loader: { ".tsx": "tsx", ".ts": "ts" },
+  define: { "process.env.NODE_ENV": '"production"' },
+  logLevel: "warning",
+  alias: {
+    "react": reactPath,
+    "react-dom": reactDomPath,
+    "react-dom/client": resolve(reactDomPath, "client.js"),
+    "react/jsx-runtime": resolve(reactPath, "jsx-runtime.js"),
+  },
+});
+
+copyFileSync(resolve(__dirname, "index.html"), resolve(outDir, "index.html"));
+
+const desktopViewport = { width: 1440, height: 920 };
+const mobileViewport = { width: 390, height: 844 };
+
+const desktopTargets = [
+  { slug: "01-wiki-browse", view: "wiki-sidebar", section: null },
+  { slug: "02-wiki-ingest", view: "wiki-sidebar", section: "ingest" },
+  { slug: "03-wiki-query", view: "wiki-sidebar", section: "query" },
+  { slug: "04-wiki-lint", view: "wiki-sidebar", section: "lint" },
+  { slug: "05-wiki-history", view: "wiki-sidebar", section: "history" },
+  { slug: "06-wiki-settings", view: "wiki-sidebar", section: "settings" },
+  { slug: "07-host-settings", view: "settings" },
+  { slug: "09-sidebar-link", view: "sidebar" },
+  { slug: "11-wiki-distillation-settings", view: "wiki-sidebar", section: "settings/distillation" },
+  { slug: "12-wiki-distillation-unconfigured", view: "wiki-sidebar", section: "settings/distillation", search: "unconfigured=1" },
+  { slug: "20-spaces-sidebar", view: "wiki-sidebar", section: null },
+  { slug: "21-spaces-ingest", view: "wiki-sidebar", section: "ingest" },
+  { slug: "21a-spaces-ingest-with-disclaimer", view: "wiki-sidebar", section: "ingest" },
+  { slug: "22-spaces-edit", view: "wiki-sidebar", section: "settings/spaces/team-research", scrollToText: "Paperclip ingestion" },
+  { slug: "22a-spaces-edit-default", view: "wiki-sidebar", section: "settings/spaces/default", scrollToText: "Paperclip ingestion" },
+  { slug: "23-spaces-non-default-route", view: "wiki-sidebar", section: "spaces/team-research" },
+  { slug: "24-spaces-create-modal", view: "wiki-sidebar", section: null, openCreateSpaceModal: true },
+];
+
+const mobileTargets = desktopTargets
+  .filter((target) => !target.openCreateSpaceModal)
+  .map((target) => ({
+    ...target,
+    slug: `mobile/${target.slug}`,
+    // In the production host, the route sidebar lives in the mobile drawer.
+    // The page body should therefore be checked without the desktop sidebar.
+    view: target.view === "wiki-sidebar" ? "wiki" : target.view,
+    viewport: mobileViewport,
+  }));
+
+const targets = [
+  ...desktopTargets.map((target) => ({ ...target, viewport: desktopViewport })),
+  ...mobileTargets,
+];
+
+const playwrightUrl = pathToFileURL(resolve(pkgRoot, "node_modules/playwright/index.mjs")).href;
+const playwrightFallback = resolve(pkgRoot, "..", "..", "..", "node_modules", ".pnpm", "playwright@1.58.2", "node_modules", "playwright", "index.mjs");
+let playwrightModuleHref = playwrightUrl;
+if (!existsSync(resolve(pkgRoot, "node_modules/playwright/index.mjs"))) {
+  if (existsSync(playwrightFallback)) {
+    playwrightModuleHref = pathToFileURL(playwrightFallback).href;
+  } else {
+    throw new Error("Cannot locate playwright module");
+  }
+}
+const { chromium } = await import(playwrightModuleHref);
+
+const mimeFor = (ext) => ({
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+})[ext] ?? "application/octet-stream";
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url ?? "/", "http://localhost");
+  const requestedPath = url.pathname === "/" ? "/index.html" : url.pathname;
+  const ext = extname(requestedPath);
+  const candidate = ext ? resolve(outDir, "." + requestedPath) : resolve(outDir, "./index.html");
+  try {
+    const body = readFileSync(candidate);
+    res.writeHead(200, { "Content-Type": mimeFor(extname(candidate)) });
+    res.end(body);
+  } catch {
+    res.writeHead(404);
+    res.end("Not found: " + candidate);
+  }
+});
+await new Promise((r) => server.listen(0, "127.0.0.1", r));
+const { port } = server.address();
+const baseUrl = `http://127.0.0.1:${port}`;
+
+const browser = await chromium.launch({ headless: true });
+const context = await browser.newContext({ viewport: desktopViewport, deviceScaleFactor: 2 });
+const page = await context.newPage();
+page.on("console", (msg) => console.log(`  [console.${msg.type()}]`, msg.text()));
+page.on("pageerror", (err) => console.error("  [pageerror]", err.message));
+
+for (const target of targets) {
+  const sectionPath = target.section ? `/${target.section}` : "";
+  const search = target.search ? `?${target.search}` : "";
+  const url = `${baseUrl}/PAP/wiki${sectionPath}${search}#${target.view}`;
+  console.log(`→ rendering ${target.slug} (${url})`);
+  await page.setViewportSize(target.viewport);
+  await page.goto(url, { waitUntil: "networkidle" });
+  await page.waitForTimeout(200);
+  if (target.slug === "09-sidebar-link") {
+    await page.addStyleTag({ content: "body { background: var(--sidebar); }" });
+  }
+  if (target.openCreateSpaceModal) {
+    await page.evaluate(() => {
+      const btn = document.querySelector('button[aria-label="Create space"]');
+      if (!btn) throw new Error("Create space button not found in DOM");
+      (btn).click();
+    });
+    await page.waitForSelector('[aria-labelledby="create-space-modal-title"]', { timeout: 5000 });
+    await page.waitForTimeout(150);
+  }
+  if (target.scrollToText) {
+    await page.getByText(target.scrollToText).first().scrollIntoViewIfNeeded();
+    await page.waitForTimeout(100);
+  }
+  const outFile = resolve(screensDir, `${target.slug}.png`);
+  mkdirSync(dirname(outFile), { recursive: true });
+  await page.screenshot({ path: outFile, fullPage: false });
+  const horizontalOverflow = await page.evaluate(() => {
+    const rootOverflow = document.documentElement.scrollWidth - document.documentElement.clientWidth;
+    const bodyOverflow = document.body.scrollWidth - window.innerWidth;
+    return Math.max(rootOverflow, bodyOverflow);
+  });
+  if (horizontalOverflow > 1) {
+    throw new Error(`${target.slug} has ${horizontalOverflow}px horizontal overflow at ${target.viewport.width}px`);
+  }
+  console.log(`  saved ${outFile}`);
+}
+
+await browser.close();
+server.close();
+console.log("Done. Screenshots in", screensDir);
diff --git a/packages/plugins/plugin-llm-wiki/tests/screenshots/entry.tsx b/packages/plugins/plugin-llm-wiki/tests/screenshots/entry.tsx
new file mode 100644
index 00000000..55c66cf1
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/tests/screenshots/entry.tsx
@@ -0,0 +1,6 @@
+import { createRoot } from "react-dom/client";
+import { App } from "./harness.js";
+
+const container = document.getElementById("root");
+if (!container) throw new Error("No #root in harness host");
+createRoot(container).render(<App />);
diff --git a/packages/plugins/plugin-llm-wiki/tests/screenshots/harness.tsx b/packages/plugins/plugin-llm-wiki/tests/screenshots/harness.tsx
new file mode 100644
index 00000000..63289500
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/tests/screenshots/harness.tsx
@@ -0,0 +1,1061 @@
+import { useEffect, useState } from "react";
+import { SettingsPage, SidebarLink, WikiPage, WikiRouteSidebar } from "../../src/ui/index.js";
+import type {
+  FileTreeNode,
+  FileTreeBadge,
+  FileTreeProps,
+  IssuesListProps,
+} from "@paperclipai/plugin-sdk/ui";
+
+// ---------------------------------------------------------------------------
+// Bridge mocks. The real SDK runtime hooks read from a global registry; we
+// inline an alternate registry here so the plugin UI can render with canned
+// data inside a screenshot harness.
+// ---------------------------------------------------------------------------
+
+const NOW = "2026-05-01T20:30:00.000Z";
+
+const FOLDER_HEALTHY = {
+  folderKey: "wiki-root",
+  configured: true,
+  path: "/Users/operator/work/wiki/engineering",
+  realPath: "/Users/operator/work/wiki/engineering",
+  access: "readWrite" as const,
+  readable: true,
+  writable: true,
+  requiredDirectories: ["raw", "wiki", "wiki/sources", "wiki/projects", "wiki/entities", "wiki/concepts", "wiki/synthesis"],
+  requiredFiles: ["AGENTS.md", "IDEA.md", "wiki/index.md", "wiki/log.md"],
+  missingDirectories: [],
+  missingFiles: [],
+  healthy: true,
+  problems: [],
+  checkedAt: NOW,
+};
+
+const MANAGED_AGENT = {
+  status: "active",
+  agentId: "agt-c14a-7b2f-4e90",
+  resourceKey: "paperclipai.plugin-llm-wiki:agent:wiki-maintainer",
+  details: { name: "Wiki Maintainer", status: "active", adapterType: "claude_local", icon: "book-open", urlKey: "wiki-maintainer" },
+};
+
+const MANAGED_PROJECT = {
+  status: "active",
+  projectId: "prj-llmw-7e1a",
+  resourceKey: "paperclipai.plugin-llm-wiki:project:llm-wiki",
+  details: { name: "LLM Wiki Operations", status: "in_progress" },
+};
+
+const MANAGED_ROUTINE = {
+  status: "active",
+  routineId: "rtn-llmw-night",
+  resourceKey: "paperclipai.plugin-llm-wiki:routine:nightly-wiki-lint",
+  routine: {
+    id: "rtn-llmw-night",
+    title: "Run LLM Wiki lint",
+    status: "active",
+    cronExpression: "0 3 * * *",
+    enabled: true,
+    assigneeAgentId: "agt-c14a-7b2f-4e90",
+    projectId: "prj-llmw-7e1a",
+    nextRunAt: "2026-05-02T03:00:00Z",
+    lastRunAt: "2026-05-01T03:00:00Z",
+  },
+  details: {
+    title: "Run LLM Wiki lint",
+    status: "active",
+    cronExpression: "0 3 * * *",
+    enabled: true,
+    assigneeAgentId: "agt-c14a-7b2f-4e90",
+    nextRunAt: "2026-05-02T03:00:00Z",
+    lastRunAt: "2026-05-01T03:00:00Z",
+  },
+};
+
+const MANAGED_ROUTINES = [
+  {
+    status: "active",
+    routineId: "rtn-llmw-cursor",
+    resourceKey: "paperclipai.plugin-llm-wiki:routine:cursor-window-processing",
+    routine: {
+      id: "rtn-llmw-cursor",
+      title: "Process LLM Wiki updates",
+      status: "active",
+      cronExpression: "0 */6 * * *",
+      enabled: true,
+      assigneeAgentId: "agt-c14a-7b2f-4e90",
+      projectId: "prj-llmw-7e1a",
+      lastRunAt: "2026-05-01T18:00:00Z",
+    },
+    details: {
+      title: "Process LLM Wiki updates",
+      status: "active",
+      cronExpression: "0 */6 * * *",
+      enabled: true,
+    },
+  },
+  MANAGED_ROUTINE,
+  {
+    status: "active",
+    routineId: "rtn-llmw-index",
+    resourceKey: "paperclipai.plugin-llm-wiki:routine:index-refresh",
+    routine: {
+      id: "rtn-llmw-index",
+      title: "Refresh LLM Wiki index",
+      status: "active",
+      cronExpression: "0 * * * *",
+      enabled: true,
+      assigneeAgentId: "agt-c14a-7b2f-4e90",
+      projectId: "prj-llmw-7e1a",
+      lastRunAt: "2026-05-01T20:00:00Z",
+    },
+    details: {
+      title: "Refresh LLM Wiki index",
+      status: "active",
+      cronExpression: "0 * * * *",
+      enabled: true,
+    },
+  },
+];
+
+const MANAGED_SKILL = {
+  status: "resolved",
+  skillId: "skl-llmw-maintainer",
+  resourceKey: "wiki-maintainer",
+  details: {
+    name: "LLM Wiki Maintainer",
+    key: "plugin/paperclipai-plugin-llm-wiki/wiki-maintainer",
+    description: "Use the LLM Wiki plugin tools to maintain a cited local company wiki.",
+  },
+};
+const MANAGED_SKILLS = [
+  MANAGED_SKILL,
+  { status: "resolved", skillId: "skl-llmw-ingest", resourceKey: "wiki-ingest", details: { name: "Wiki Ingest", key: "plugin/paperclipai-plugin-llm-wiki/wiki-ingest", description: null } },
+  { status: "resolved", skillId: "skl-llmw-query", resourceKey: "wiki-query", details: { name: "Wiki Query", key: "plugin/paperclipai-plugin-llm-wiki/wiki-query", description: null } },
+  { status: "resolved", skillId: "skl-llmw-lint", resourceKey: "wiki-lint", details: { name: "Wiki Lint", key: "plugin/paperclipai-plugin-llm-wiki/wiki-lint", description: null } },
+  { status: "resolved", skillId: "skl-llmw-distill", resourceKey: "paperclip-distill", details: { name: "Paperclip Distill", key: "plugin/paperclipai-plugin-llm-wiki/paperclip-distill", description: null } },
+  { status: "resolved", skillId: "skl-llmw-index", resourceKey: "index-refresh", details: { name: "Index Refresh", key: "plugin/paperclipai-plugin-llm-wiki/index-refresh", description: null } },
+];
+
+const OVERVIEW = {
+  status: "ok",
+  checkedAt: NOW,
+  wikiId: "default",
+  folder: FOLDER_HEALTHY,
+  managedAgent: MANAGED_AGENT,
+  managedProject: MANAGED_PROJECT,
+  managedSkills: MANAGED_SKILLS,
+  operationCount: 128,
+  capabilities: [
+    "api.routes.register",
+    "issues.create",
+    "issues.read",
+    "agents.managed",
+    "projects.managed",
+    "routines.managed",
+    "agent.tools.register",
+  ],
+  prompts: {
+    query: "Answer from the LLM Wiki.\n\nRead wiki/index.md first, inspect relevant pages and raw/source references, cite the pages used, and say when the wiki does not contain enough evidence.",
+    lint: "Lint the LLM Wiki for contradictions, stale claims, orphan pages, missing backlinks, weak provenance, and wiki/index.md / wiki/log.md drift.",
+  },
+  eventIngestion: {
+    enabled: false,
+    sources: { issues: false, comments: false, documents: false },
+    wikiId: "default",
+    maxCharacters: 12000,
+  },
+};
+
+const SETTINGS = {
+  folder: FOLDER_HEALTHY,
+  managedAgent: MANAGED_AGENT,
+  managedProject: MANAGED_PROJECT,
+  managedRoutine: MANAGED_ROUTINE,
+  managedRoutines: MANAGED_ROUTINES,
+  managedSkills: MANAGED_SKILLS,
+  agentOptions: [{ id: "agt-c14a-7b2f-4e90", name: "Wiki Maintainer", status: "active", icon: "book-open", urlKey: "wiki-maintainer" }],
+  projectOptions: [],
+  eventIngestion: OVERVIEW.eventIngestion,
+  capabilities: OVERVIEW.capabilities,
+};
+
+const PAGES = {
+  pages: [
+    { path: "wiki/areas/control-plane.md", title: "Control plane", pageType: "areas", backlinkCount: 5, sourceCount: 2, contentHash: "a1b2c3d4", updatedAt: "2026-05-01T18:00:00Z" },
+    { path: "wiki/areas/plugin-runtime.md", title: "Plugin runtime", pageType: "areas", backlinkCount: 4, sourceCount: 2, contentHash: "b1b2c3d4", updatedAt: "2026-05-01T16:00:00Z" },
+    { path: "wiki/concepts/managed-resources.md", title: "Managed resources", pageType: "concepts", backlinkCount: 7, sourceCount: 2, contentHash: "c1b2c3d4", updatedAt: "2026-05-01T19:30:00Z" },
+    { path: "wiki/concepts/origin-kind.md", title: "Origin kind", pageType: "concepts", backlinkCount: 3, sourceCount: 1, contentHash: "d1b2c3d4", updatedAt: "2026-05-01T15:00:00Z" },
+    { path: "wiki/concepts/heartbeat.md", title: "Agent heartbeat", pageType: "concepts", backlinkCount: 2, sourceCount: 1, contentHash: "e1b2c3d4", updatedAt: "2026-04-30T10:00:00Z" },
+    { path: "wiki/projects/llm-wiki/standup.md", title: "LLM Wiki plugin Standup", pageType: "project-standup", backlinkCount: 1, sourceCount: 3, contentHash: "s1b2c3d4", updatedAt: "2026-05-01T20:00:00Z" },
+    { path: "wiki/projects/llm-wiki/index.md", title: "LLM Wiki plugin", pageType: "projects", backlinkCount: 6, sourceCount: 3, contentHash: "f1b2c3d4", updatedAt: "2026-05-01T17:30:00Z" },
+    { path: "wiki/sources/karpathy-llm-wiki.md", title: "Karpathy LLM Wiki gist (summary)", pageType: "sources", backlinkCount: 3, sourceCount: 1, contentHash: "g1b2c3d4", updatedAt: "2026-05-01T11:30:00Z" },
+    { path: "wiki/index.md", title: "LLM Wiki Index", pageType: "index", backlinkCount: 0, sourceCount: 0, contentHash: "h1b2c3d4", updatedAt: "2026-05-01T19:30:00Z" },
+    { path: "wiki/log.md", title: "LLM Wiki Log", pageType: "log", backlinkCount: 0, sourceCount: 0, contentHash: "i1b2c3d4", updatedAt: "2026-05-01T19:30:00Z" },
+  ],
+  sources: [
+    { rawPath: "raw/karpathy-llm-wiki.md", title: "Karpathy LLM Wiki gist", sourceType: "url", url: "https://gist.github.com/karpathy/.../llm-wiki", status: "captured", createdAt: "2026-05-01T19:00:00Z" },
+    { rawPath: "raw/paperclip-v1-spec.md", title: "Paperclip V1 spec", sourceType: "file", url: null, status: "captured", createdAt: "2026-05-01T18:30:00Z" },
+    { rawPath: "raw/design-doc-2026-04.md", title: "Design doc — April 2026", sourceType: "file", url: null, status: "captured", createdAt: "2026-04-28T14:00:00Z" },
+  ],
+};
+
+const PAGE_CONTENT = {
+  wikiId: "default",
+  path: "wiki/concepts/managed-resources.md",
+  contents: `# Managed Resources
+
+A **plugin-managed resource** is a normal Paperclip resource (agent, routine, project) that a plugin has seeded with suggested defaults. The plugin marks ownership via a stable \`resourceKey\` so that installs, imports, and upgrades can find the resource even when UUIDs differ.
+
+The host treats managed resources as fully editable. The operator can rename, change adapter config, edit instructions, change schedule, etc. The plugin can offer a *reset to plugin defaults* action that re-applies the suggested values.
+
+## Why it matters
+
+- Stable references survive dev resets and re-imports.
+- Plugin upgrades don't clobber operator edits.
+- Operations remain inspectable through native Agents / Routines / Projects pages.
+`,
+  title: "Managed Resources",
+  pageType: "concepts",
+  backlinks: ["wiki/areas/plugin-runtime.md", "wiki/concepts/origin-kind.md", "wiki/projects/llm-wiki/index.md"],
+  sourceRefs: ["raw/karpathy-llm-wiki.md", "raw/paperclip-v1-spec.md"],
+  updatedAt: "2026-05-01T19:30:00Z",
+  hash: "deadbeefcafe1234",
+};
+
+const OPERATIONS = {
+  operations: [
+    { id: "2944aaaaaaaa", operationType: "ingest", status: "running", hiddenIssueId: "ii-2944", hiddenIssueIdentifier: "PAP-OP-2944", hiddenIssueTitle: "Ingest URL: karpathy/llm-wiki gist", hiddenIssueStatus: "in_progress", projectId: "prj-llmw-7e1a", costCents: 1, warnings: [], affectedPages: [], createdAt: "2026-05-01T20:29:48Z", updatedAt: "2026-05-01T20:29:48Z" },
+    { id: "2943bbbbbbbb", operationType: "query", status: "done", hiddenIssueId: "ii-2943", hiddenIssueIdentifier: "PAP-OP-2943", hiddenIssueTitle: "How do plugin-managed routines resolve their default agent…", hiddenIssueStatus: "done", projectId: "prj-llmw-7e1a", costCents: 1, warnings: [], affectedPages: [], createdAt: "2026-05-01T20:25:00Z", updatedAt: "2026-05-01T20:26:30Z" },
+    { id: "2942cccccccc", operationType: "file-as-page", status: "done", hiddenIssueId: "ii-2942", hiddenIssueIdentifier: "PAP-OP-2942", hiddenIssueTitle: "File answer as concepts/routine-agent-resolution.md", hiddenIssueStatus: "done", projectId: "prj-llmw-7e1a", costCents: 0, warnings: [], affectedPages: [{ path: "wiki/concepts/routine-agent-resolution.md" }], createdAt: "2026-05-01T20:25:30Z", updatedAt: "2026-05-01T20:25:35Z" },
+    { id: "2941dddddddd", operationType: "query", status: "done", hiddenIssueId: "ii-2941", hiddenIssueIdentifier: "PAP-OP-2941", hiddenIssueTitle: "Compare managed agent reset vs detach…", hiddenIssueStatus: "done", projectId: "prj-llmw-7e1a", costCents: 1, warnings: [], affectedPages: [], createdAt: "2026-05-01T20:18:00Z", updatedAt: "2026-05-01T20:18:30Z" },
+    { id: "2940eeeeeeee", operationType: "lint", status: "done", hiddenIssueId: "ii-2940", hiddenIssueIdentifier: "PAP-OP-2940", hiddenIssueTitle: "Nightly wiki lint · 17 findings (2 critical)", hiddenIssueStatus: "done", projectId: "prj-llmw-7e1a", costCents: 4, warnings: [
+      { severity: "critical", message: "Contradiction: managed-resources.md vs raw/karpathy-llm-wiki.md (run-time vs install-time resolution)", path: "wiki/concepts/managed-resources.md" },
+      { severity: "critical", message: "Conflicting claim about plugin manifest version", path: "wiki/concepts/origin-kind.md" },
+      { severity: "orphan", message: "people/aaron-norvig.md has no inbound backlinks", path: "wiki/people/aaron-norvig.md" },
+      { severity: "orphan", message: "concepts/sandboxing.md is referenced from raw/ only", path: "wiki/concepts/sandboxing.md" },
+      { severity: "stale", message: "areas/control-plane.md last source observed 41d ago", path: "wiki/areas/control-plane.md" },
+      { severity: "backlink", message: "Missing reverse links: managed-resources.md -> wiki/projects/llm-wiki/index.md" },
+      { severity: "index", message: "index.md does not list 5 pages created in last 24h" },
+    ], affectedPages: [], createdAt: "2026-05-01T18:00:00Z", updatedAt: "2026-05-01T18:02:30Z" },
+    { id: "2939ffffffff", operationType: "ingest", status: "done", hiddenIssueId: "ii-2939", hiddenIssueIdentifier: "PAP-OP-2939", hiddenIssueTitle: "paperclip-v1-spec.md · 3 pages created", hiddenIssueStatus: "done", projectId: "prj-llmw-7e1a", costCents: 2, warnings: [], affectedPages: [{ path: "wiki/areas/control-plane.md" }, { path: "wiki/concepts/managed-resources.md" }, { path: "wiki/concepts/origin-kind.md" }], createdAt: "2026-05-01T18:30:00Z", updatedAt: "2026-05-01T18:32:00Z" },
+    { id: "2934gggggggg", operationType: "ingest", status: "failed", hiddenIssueId: "ii-2934", hiddenIssueIdentifier: "PAP-OP-2934", hiddenIssueTitle: "Internal wiki dump (PDF) · outbound URL not on allowlist", hiddenIssueStatus: "blocked", projectId: "prj-llmw-7e1a", costCents: 0, warnings: [{ message: "outbound URL not on allowlist" }], affectedPages: [], createdAt: "2026-05-01T16:00:00Z", updatedAt: "2026-05-01T16:00:30Z" },
+  ],
+};
+
+const TEMPLATE_IDEA = {
+  path: "IDEA.md",
+  exists: true,
+  hash: "abc123",
+  contents: `# LLM Wiki
+
+A pattern for building personal knowledge bases using LLMs.
+`,
+};
+
+const TEMPLATE_AGENTS = {
+  path: "AGENTS.md",
+  exists: true,
+  hash: "def456",
+  contents: `# LLM Wiki Maintainer
+
+You maintain this wiki through Paperclip plugin tools.
+
+Before answering or editing:
+
+1. Read AGENTS.md.
+2. Read wiki/index.md.
+3. Cite raw sources or source pages for factual claims.
+4. Use proposed patches for substantial rewrites.
+5. Append a short note to wiki/log.md for maintenance changes.
+`,
+};
+
+const HOST_CONTEXT = {
+  companyId: "company-demo",
+  companyPrefix: "PAP",
+  projectId: null,
+  entityId: null,
+  entityType: null,
+  userId: "user-demo",
+  parentEntityId: null,
+};
+
+function fakeData<T>(value: T) {
+  return { data: value, loading: false, error: null, refresh: () => undefined };
+}
+
+const DISTILLATION_CURSOR = {
+  id: "cur-control-plane-1",
+  sourceScope: "project",
+  scopeKey: "prj-control-plane",
+  projectId: "prj-control-plane",
+  projectName: "Control plane",
+  projectColor: "#2563eb",
+  rootIssueId: null,
+  rootIssueIdentifier: null,
+  rootIssueTitle: null,
+  lastProcessedAt: "2026-05-04T15:00:00Z",
+  lastObservedAt: "2026-05-04T18:55:00Z",
+  pendingEventCount: 4,
+  lastSourceHash: "7f3a92041b210def",
+  lastSuccessfulRunId: "run-1",
+};
+
+const DISTILLATION_RUNS = [
+  {
+    id: "run-1",
+    cursorId: "cur-control-plane-1",
+    workItemId: null,
+    projectId: "prj-control-plane",
+    projectName: "Control plane",
+    rootIssueId: null,
+    rootIssueIdentifier: null,
+    sourceWindowStart: "2026-04-30T14:22:00Z",
+    sourceWindowEnd: "2026-05-04T15:01:00Z",
+    sourceHash: "7f3a92041b210def",
+    status: "succeeded",
+    costCents: 12,
+    retryCount: 0,
+    warnings: [],
+    metadata: {},
+    operationIssueId: "ii-op-3201",
+    operationIssueIdentifier: "PAP-OP-3201",
+    operationIssueTitle: "LLM Wiki distillation · Control plane",
+    affectedPagePaths: ["wiki/projects/control-plane/index.md"],
+    createdAt: "2026-05-04T15:01:00Z",
+    updatedAt: "2026-05-04T15:02:14Z",
+  },
+  {
+    id: "run-2",
+    cursorId: "cur-billing-1",
+    workItemId: null,
+    projectId: "prj-billing",
+    projectName: "Billing",
+    rootIssueId: null,
+    rootIssueIdentifier: null,
+    sourceWindowStart: "2026-05-03T08:00:00Z",
+    sourceWindowEnd: "2026-05-04T18:55:00Z",
+    sourceHash: "92d44102be7c08aa",
+    status: "review_required",
+    costCents: 8,
+    retryCount: 0,
+    warnings: ["Touches the Decisions section. Auto-apply policy is 'Status sections only'."],
+    metadata: {},
+    operationIssueId: "ii-op-3204",
+    operationIssueIdentifier: "PAP-OP-3204",
+    operationIssueTitle: "LLM Wiki distillation · Billing",
+    affectedPagePaths: ["wiki/projects/billing/index.md", "wiki/projects/billing/decisions.md"],
+    createdAt: "2026-05-04T18:55:00Z",
+    updatedAt: "2026-05-04T18:56:14Z",
+  },
+  {
+    id: "run-3",
+    cursorId: "cur-routines-1",
+    workItemId: null,
+    projectId: "prj-routines",
+    projectName: "Routine engine",
+    rootIssueId: null,
+    rootIssueIdentifier: null,
+    sourceWindowStart: "2026-05-04T11:00:00Z",
+    sourceWindowEnd: "2026-05-04T18:00:00Z",
+    sourceHash: "ab12dde98c3f0001",
+    status: "running",
+    costCents: 4,
+    retryCount: 0,
+    warnings: [],
+    metadata: {},
+    operationIssueId: "ii-op-3205",
+    operationIssueIdentifier: "PAP-OP-3205",
+    operationIssueTitle: "LLM Wiki distillation · Routine engine",
+    affectedPagePaths: [],
+    createdAt: "2026-05-04T18:58:00Z",
+    updatedAt: "2026-05-04T18:58:00Z",
+  },
+  {
+    id: "run-4",
+    cursorId: "cur-export-1",
+    workItemId: null,
+    projectId: "prj-exports",
+    projectName: "Exports",
+    rootIssueId: null,
+    rootIssueIdentifier: null,
+    sourceWindowStart: "2026-05-03T20:00:00Z",
+    sourceWindowEnd: "2026-05-04T03:00:00Z",
+    sourceHash: "ee01acd482211110",
+    status: "failed",
+    costCents: 0,
+    retryCount: 1,
+    warnings: ["model error: 429", "Source bundle clipped: 6 issues over 48k chars."],
+    metadata: {},
+    operationIssueId: "ii-op-3198",
+    operationIssueIdentifier: "PAP-OP-3198",
+    operationIssueTitle: "LLM Wiki distillation · Exports",
+    affectedPagePaths: [],
+    createdAt: "2026-05-04T03:01:00Z",
+    updatedAt: "2026-05-04T03:01:30Z",
+  },
+];
+
+const DISTILLATION_PAGE_BINDINGS = [
+  {
+    id: "bind-control-plane",
+    pagePath: "wiki/projects/control-plane/index.md",
+    projectId: "prj-control-plane",
+    projectName: "Control plane",
+    rootIssueId: null,
+    lastAppliedSourceHash: "7f3a92041b210def",
+    lastDistillationRunId: "run-1",
+    lastRunStatus: "succeeded",
+    lastRunCompletedAt: "2026-05-04T15:02:14Z",
+    lastRunSourceWindowEnd: "2026-05-04T15:01:00Z",
+    lastRunSourceHash: "7f3a92041b210def",
+    metadata: { sourceRefs: [{ id: "PAP-3416", kind: "issue", title: "Distillation kickoff" }, { id: "PAP-3416#c1", kind: "comment", title: "Comment" }] },
+    updatedAt: "2026-05-04T15:02:14Z",
+  },
+  {
+    id: "bind-billing",
+    pagePath: "wiki/projects/billing/index.md",
+    projectId: "prj-billing",
+    projectName: "Billing",
+    rootIssueId: null,
+    lastAppliedSourceHash: "11abf991a081ddff",
+    lastDistillationRunId: "run-2",
+    lastRunStatus: "review_required",
+    lastRunCompletedAt: "2026-05-04T18:56:14Z",
+    lastRunSourceWindowEnd: "2026-05-04T18:55:00Z",
+    lastRunSourceHash: "92d44102be7c08aa",
+    metadata: {},
+    updatedAt: "2026-05-04T18:56:14Z",
+  },
+];
+
+const DISTILLATION_OVERVIEW = {
+  cursors: [
+    DISTILLATION_CURSOR,
+    {
+      ...DISTILLATION_CURSOR,
+      id: "cur-billing-1",
+      scopeKey: "prj-billing",
+      projectId: "prj-billing",
+      projectName: "Billing",
+      lastProcessedAt: "2026-05-04T18:55:00Z",
+      lastObservedAt: "2026-05-04T18:55:00Z",
+      pendingEventCount: 0,
+      lastSuccessfulRunId: "run-2",
+    },
+    {
+      ...DISTILLATION_CURSOR,
+      id: "cur-routines-1",
+      scopeKey: "prj-routines",
+      projectId: "prj-routines",
+      projectName: "Routine engine",
+      lastProcessedAt: null,
+      lastObservedAt: "2026-05-04T18:00:00Z",
+      pendingEventCount: 11,
+      lastSuccessfulRunId: null,
+    },
+  ],
+  runs: DISTILLATION_RUNS,
+  workItems: [
+    { id: "wi-1", workItemKind: "review", status: "review_required", priority: "high", projectId: "prj-billing", rootIssueId: null, metadata: {}, createdAt: "2026-05-04T18:56:00Z", updatedAt: "2026-05-04T18:56:00Z" },
+  ],
+  pageBindings: DISTILLATION_PAGE_BINDINGS,
+  reviewWorkItems: [
+    { id: "wi-1", workItemKind: "review", status: "review_required", priority: "high", projectId: "prj-billing", rootIssueId: null, metadata: {}, createdAt: "2026-05-04T18:56:00Z", updatedAt: "2026-05-04T18:56:00Z" },
+  ],
+  counts: { cursors: 3, runningRuns: 1, failedRuns24h: 1, reviewRequired: 1 },
+};
+
+const DISTILLATION_OVERVIEW_UNCONFIGURED = {
+  cursors: [],
+  runs: [],
+  workItems: [],
+  pageBindings: [],
+  reviewWorkItems: [],
+  counts: { cursors: 0, runningRuns: 0, failedRuns24h: 0, reviewRequired: 0 },
+};
+
+const DISTILLATION_PROVENANCE = {
+  binding: DISTILLATION_PAGE_BINDINGS[0],
+  runs: [DISTILLATION_RUNS[0]],
+  snapshot: {
+    id: "snap-1",
+    distillationRunId: "run-1",
+    sourceHash: "7f3a92041b210def",
+    maxCharacters: 48000,
+    clipped: false,
+    sourceRefs: [
+      { id: "PAP-3416", kind: "issue", title: "How should we distill?" },
+      { id: "PAP-3416#c1", kind: "comment", title: "Approach: cursors" },
+      { id: "PAP-3416#doc:plan", kind: "document", title: "Plan v3" },
+    ],
+    metadata: { issueCount: 12, commentCount: 8, documentCount: 4 },
+    createdAt: "2026-05-04T15:01:00Z",
+  },
+  cursor: DISTILLATION_CURSOR,
+};
+
+const SPACES = {
+  spaces: [
+    {
+      id: "space-default",
+      companyId: HOST_CONTEXT.companyId,
+      wikiId: "default",
+      slug: "default",
+      displayName: "default",
+      spaceType: "managed",
+      folderMode: "managed_subfolder",
+      rootFolderKey: "wiki-root",
+      pathPrefix: null,
+      configuredRootPath: null,
+      accessScope: "shared",
+      ownerUserId: null,
+      ownerAgentId: null,
+      teamKey: null,
+      settings: {},
+      status: "active",
+      createdAt: "2026-04-12T08:00:00Z",
+      updatedAt: "2026-05-01T12:00:00Z",
+    },
+    {
+      id: "space-team-research",
+      companyId: HOST_CONTEXT.companyId,
+      wikiId: "default",
+      slug: "team-research",
+      displayName: "team-research",
+      spaceType: "managed",
+      folderMode: "managed_subfolder",
+      rootFolderKey: "wiki-root",
+      pathPrefix: "spaces/team-research",
+      configuredRootPath: null,
+      accessScope: "shared",
+      ownerUserId: null,
+      ownerAgentId: null,
+      teamKey: null,
+      settings: {},
+      status: "active",
+      createdAt: "2026-04-22T08:00:00Z",
+      updatedAt: "2026-05-01T11:00:00Z",
+    },
+    {
+      id: "space-customer-feedback",
+      companyId: HOST_CONTEXT.companyId,
+      wikiId: "default",
+      slug: "customer-feedback",
+      displayName: "customer-feedback",
+      spaceType: "managed",
+      folderMode: "managed_subfolder",
+      rootFolderKey: "wiki-root",
+      pathPrefix: "spaces/customer-feedback",
+      configuredRootPath: null,
+      accessScope: "shared",
+      ownerUserId: null,
+      ownerAgentId: null,
+      teamKey: null,
+      settings: {},
+      status: "active",
+      createdAt: "2026-04-25T08:00:00Z",
+      updatedAt: "2026-05-01T10:00:00Z",
+    },
+  ],
+};
+
+function dataResolver(key: string, params?: Record<string, unknown>) {
+  if (key === "overview") return fakeData(OVERVIEW);
+  if (key === "settings") return fakeData(SETTINGS);
+  if (key === "spaces") return fakeData(SPACES);
+  if (key === "space") {
+    const slug = typeof params?.spaceSlug === "string" ? params.spaceSlug : "default";
+    const space = SPACES.spaces.find((s) => s.slug === slug) ?? SPACES.spaces[0];
+    return fakeData({
+      ...space,
+      relativeRoot: space.pathPrefix ?? "",
+      folder: FOLDER_HEALTHY,
+    });
+  }
+  if (key === "pages") return fakeData(PAGES);
+  if (key === "page-content") return fakeData(PAGE_CONTENT);
+  if (key === "operations") {
+    const opType = typeof params?.operationType === "string" ? params.operationType : null;
+    const filtered = opType && opType !== "all"
+      ? OPERATIONS.operations.filter((op) => op.operationType === opType)
+      : OPERATIONS.operations;
+    return fakeData({ operations: filtered });
+  }
+  if (key === "distillation-overview") {
+    const flag = typeof window !== "undefined" ? window.location.search.includes("unconfigured=1") : false;
+    return fakeData(flag ? DISTILLATION_OVERVIEW_UNCONFIGURED : DISTILLATION_OVERVIEW);
+  }
+  if (key === "distillation-page-provenance") {
+    return fakeData(DISTILLATION_PROVENANCE);
+  }
+  if (key === "template" && params?.path === "IDEA.md") return fakeData(TEMPLATE_IDEA);
+  if (key === "template" && params?.path === "AGENTS.md") return fakeData(TEMPLATE_AGENTS);
+  return { data: null, loading: false, error: null, refresh: () => undefined };
+}
+
+function MockFileTree(props: FileTreeProps) {
+  const expanded = new Set(props.expandedPaths ?? []);
+  const badges = props.fileBadges ?? {};
+  const renderNodes = (nodes: FileTreeNode[], depth: number) => (
+    <ul style={{ listStyle: "none", margin: 0, padding: 0 }}>
+      {nodes.map((node) => {
+        const isExpanded = node.kind === "dir" && expanded.has(node.path);
+        const isSelected = node.kind === "file" && node.path === props.selectedFile;
+        const badge = badges[node.path] as FileTreeBadge | undefined;
+        return (
+          <li key={node.path}>
+            <button
+              type="button"
+              onClick={() => {
+                if (node.kind === "dir") props.onToggleDir?.(node.path);
+                else props.onSelectFile?.(node.path);
+              }}
+              style={{
+                display: "flex",
+                alignItems: "center",
+                gap: 6,
+                width: "100%",
+                border: "none",
+                background: isSelected ? "var(--accent, oklch(0.269 0 0))" : "transparent",
+                color: "var(--foreground, oklch(0.985 0 0))",
+                fontSize: 12,
+                textAlign: "left",
+                padding: `4px 8px 4px ${depth * 16 + 12}px`,
+                cursor: "pointer",
+                borderRadius: 4,
+                fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+              }}
+              aria-expanded={node.kind === "dir" ? isExpanded : undefined}
+              aria-selected={isSelected || undefined}
+            >
+              <span style={{ width: 12, color: "var(--muted-foreground, oklch(0.708 0 0))" }} aria-hidden>
+                {node.kind === "dir" ? (isExpanded ? "▾" : "▸") : ""}
+              </span>
+              <span style={{ flex: 1, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+                {node.kind === "dir" ? `📁 ${node.name}` : node.name}
+              </span>
+              {badge ? (
+                <span
+                  style={{
+                    fontSize: 10,
+                    padding: "1px 6px",
+                    borderRadius: 999,
+                    background: "color-mix(in oklab, var(--accent, oklch(0.4 0.04 250)) 50%, transparent)",
+                    color: "var(--foreground, oklch(0.985 0 0))",
+                    textTransform: "uppercase",
+                    letterSpacing: "0.04em",
+                  }}
+                  title={badge.tooltip}
+                >
+                  {badge.label}
+                </span>
+              ) : null}
+            </button>
+            {node.kind === "dir" && isExpanded ? renderNodes(node.children, depth + 1) : null}
+          </li>
+        );
+      })}
+    </ul>
+  );
+
+  if (props.loading) {
+    return <div style={{ padding: 12, fontSize: 12, color: "var(--muted-foreground, oklch(0.708 0 0))" }}>Loading…</div>;
+  }
+  if (props.error) {
+    return <div style={{ padding: 12, fontSize: 12, color: "var(--destructive, oklch(0.7 0.2 25))" }}>{props.error.message}</div>;
+  }
+  if (props.nodes.length === 0) {
+    return (
+      <div style={{ padding: 16, fontSize: 12, color: "var(--muted-foreground, oklch(0.708 0 0))" }}>
+        <div style={{ fontWeight: 600, color: "var(--foreground, oklch(0.985 0 0))" }}>{props.empty?.title ?? "No files"}</div>
+        <div>{props.empty?.description ?? "Nothing to show."}</div>
+      </div>
+    );
+  }
+  return <div role="tree" aria-label={props.ariaLabel ?? "Files"}>{renderNodes(props.nodes, 0)}</div>;
+}
+
+function MockIssuesList(props: IssuesListProps) {
+  const isNarrow = typeof window !== "undefined" && window.innerWidth < 700;
+  const rows = OPERATIONS.operations.map((op) => ({
+    id: op.hiddenIssueId ?? op.id,
+    identifier: op.hiddenIssueIdentifier ?? `op-${op.id.slice(0, 6)}`,
+    title: op.hiddenIssueTitle ?? `LLM Wiki ${op.operationType}`,
+    status: op.hiddenIssueStatus ?? op.status,
+    priority: op.operationType === "query" ? "medium" : "low",
+    updatedAt: op.updatedAt,
+    operationType: op.operationType,
+  }));
+  return (
+    <div style={{ display: "grid", gap: 10, padding: 18, fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif" }}>
+      <div style={{ display: "flex", alignItems: "center", gap: 10, flexWrap: "wrap" }}>
+        <strong style={{ fontSize: 14 }}>Issues</strong>
+        <span style={{ fontSize: 11, color: "var(--muted-foreground, oklch(0.708 0 0))" }}>
+          {rows.length} loaded · {props.filters?.originKindPrefix ?? props.projectId ?? "all"}
+        </span>
+      </div>
+      <div style={{ border: "1px solid var(--border, oklch(0.269 0 0))", borderRadius: 8, overflow: "hidden", background: "var(--card, oklch(0.205 0 0))" }}>
+        {rows.map((issue) => (
+          <div
+            key={issue.id}
+            style={{
+              display: "grid",
+              gridTemplateColumns: isNarrow ? "minmax(0, 1fr) auto" : "110px minmax(0, 1fr) 110px 90px",
+              gap: isNarrow ? "6px 10px" : 12,
+              alignItems: "center",
+              padding: "10px 12px",
+              borderBottom: "1px solid var(--border, oklch(0.269 0 0))",
+              fontSize: 13,
+            }}
+          >
+            <span style={{ fontFamily: "ui-monospace, SFMono-Regular, monospace", fontSize: 12, color: "var(--muted-foreground, oklch(0.708 0 0))" }}>{issue.identifier}</span>
+            {isNarrow ? null : <span style={{ minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{issue.title}</span>}
+            {isNarrow ? null : <span style={{ fontSize: 11, color: "var(--muted-foreground, oklch(0.708 0 0))" }}>{issue.operationType}</span>}
+            <span style={{ justifySelf: "end", maxWidth: "100%", overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", fontSize: 11, border: "1px solid var(--border, oklch(0.269 0 0))", borderRadius: 999, padding: "2px 8px" }}>{issue.status}</span>
+            {isNarrow ? (
+              <span style={{ gridColumn: "1 / -1", minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>{issue.title}</span>
+            ) : null}
+            {isNarrow ? (
+              <span style={{ gridColumn: "1 / -1", fontSize: 11, color: "var(--muted-foreground, oklch(0.708 0 0))" }}>{issue.operationType}</span>
+            ) : null}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function MockMarkdownBlock({ content, className }: { content: string; className?: string }) {
+  return (
+    <div
+      className={className}
+      style={{ whiteSpace: "pre-wrap", fontSize: 13, lineHeight: 1.65 }}
+    >
+      {content}
+    </div>
+  );
+}
+
+function MockMarkdownEditor({
+  value,
+  onChange,
+  placeholder,
+  className,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder?: string;
+  className?: string;
+}) {
+  return (
+    <textarea
+      className={className}
+      value={value}
+      placeholder={placeholder}
+      onChange={(event) => onChange(event.currentTarget.value)}
+      style={{
+        width: "100%",
+        minHeight: 260,
+        boxSizing: "border-box",
+        border: "1px solid var(--border, oklch(0.269 0 0))",
+        borderRadius: 8,
+        background: "var(--card, oklch(0.205 0 0))",
+        color: "var(--foreground, oklch(0.985 0 0))",
+        padding: 12,
+        font: "13px ui-sans-serif, system-ui, -apple-system, sans-serif",
+      }}
+    />
+  );
+}
+
+function MockAssigneePicker({
+  value,
+  placeholder,
+  onChange,
+}: {
+  value: string;
+  placeholder?: string;
+  onChange: (value: string, selection: { assigneeAgentId: string | null; assigneeUserId: string | null }) => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={() => onChange("agent:agt-c14a-7b2f-4e90", { assigneeAgentId: "agt-c14a-7b2f-4e90", assigneeUserId: null })}
+      style={{
+        width: "100%",
+        minHeight: 44,
+        border: "1px solid var(--border, oklch(0.269 0 0))",
+        borderRadius: 8,
+        background: "var(--card, oklch(0.205 0 0))",
+        color: "var(--foreground, oklch(0.985 0 0))",
+        padding: "8px 12px",
+        textAlign: "left",
+        font: "13px ui-sans-serif, system-ui, -apple-system, sans-serif",
+      }}
+    >
+      {value ? "Wiki Maintainer" : (placeholder ?? "Select maintainer")}
+    </button>
+  );
+}
+
+type MockManagedRoutinesListProps = {
+  routines: Array<{
+    key: string;
+    title: string;
+    status: string;
+    cronExpression?: string | null;
+    lastRunAt?: string | Date | null;
+    lastRunStatus?: string | null;
+    href?: string | null;
+    managedByPluginDisplayName?: string | null;
+    missingRefs?: Array<{ resourceKind: string; resourceKey: string }>;
+    defaultDrift?: { changedFields: string[] } | null;
+  }>;
+  agents?: Array<{ id: string; name: string }>;
+  projects?: Array<{ id: string; name: string }>;
+  pluginDisplayName?: string | null;
+  runningRoutineKey?: string | null;
+  statusMutationRoutineKey?: string | null;
+  resettingRoutineKey?: string | null;
+  onRunNow?: (routine: { key: string }) => void;
+  onToggleEnabled?: (routine: { key: string }, enabled: boolean) => void;
+  onReset?: (routine: { key: string }) => void;
+};
+
+function MockManagedRoutinesList(props: MockManagedRoutinesListProps) {
+  if (props.routines.length === 0) {
+    return (
+      <div style={{ padding: 16, fontSize: 12, color: "var(--muted-foreground, oklch(0.708 0 0))" }}>
+        No managed routines.
+      </div>
+    );
+  }
+  return (
+    <div
+      style={{
+        display: "grid",
+        gap: 0,
+        border: "1px solid var(--border, oklch(0.269 0 0))",
+        borderRadius: 8,
+        overflow: "hidden",
+        background: "var(--card, oklch(0.205 0 0))",
+        fontFamily: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+      }}
+    >
+      {props.routines.map((routine, index) => (
+        <div
+          key={routine.key}
+          style={{
+            display: "grid",
+            gridTemplateColumns: "minmax(0, 1fr) 110px 110px",
+            gap: 12,
+            alignItems: "center",
+            padding: "10px 14px",
+            borderTop: index === 0 ? "none" : "1px solid var(--border, oklch(0.269 0 0))",
+            fontSize: 13,
+          }}
+        >
+          <div style={{ display: "grid", gap: 2, minWidth: 0 }}>
+            <span style={{ fontWeight: 600, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+              {routine.title}
+            </span>
+            <span
+              style={{
+                fontSize: 11,
+                color: "var(--muted-foreground, oklch(0.708 0 0))",
+                fontFamily: "ui-monospace, SFMono-Regular, monospace",
+              }}
+            >
+              {routine.cronExpression ?? "—"}
+            </span>
+          </div>
+          <span
+            style={{
+              justifySelf: "start",
+              fontSize: 11,
+              border: "1px solid var(--border, oklch(0.269 0 0))",
+              borderRadius: 999,
+              padding: "2px 8px",
+            }}
+          >
+            {routine.status}
+          </span>
+          <div style={{ justifySelf: "end", display: "flex", gap: 6 }}>
+            <button
+              type="button"
+              style={{
+                fontSize: 11,
+                padding: "4px 8px",
+                borderRadius: 6,
+                border: "1px solid var(--border, oklch(0.269 0 0))",
+                background: "transparent",
+                color: "var(--foreground, oklch(0.985 0 0))",
+                cursor: "pointer",
+              }}
+              onClick={() => props.onRunNow?.({ key: routine.key })}
+            >
+              Run now
+            </button>
+            <button
+              type="button"
+              style={{
+                fontSize: 11,
+                padding: "4px 8px",
+                borderRadius: 6,
+                border: "1px solid var(--border, oklch(0.269 0 0))",
+                background: "transparent",
+                color: "var(--foreground, oklch(0.985 0 0))",
+                cursor: "pointer",
+              }}
+              onClick={() => props.onReset?.({ key: routine.key })}
+            >
+              Reset
+            </button>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function MockProjectPicker({
+  value,
+  placeholder,
+  onChange,
+}: {
+  value: string;
+  placeholder?: string;
+  onChange: (projectId: string) => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={() => onChange("prj-llmw-7e1a")}
+      style={{
+        width: "100%",
+        minHeight: 44,
+        border: "1px solid var(--border, oklch(0.269 0 0))",
+        borderRadius: 8,
+        background: "var(--card, oklch(0.205 0 0))",
+        color: "var(--foreground, oklch(0.985 0 0))",
+        padding: "8px 12px",
+        textAlign: "left",
+        font: "13px ui-sans-serif, system-ui, -apple-system, sans-serif",
+      }}
+    >
+      {value ? "LLM Wiki Operations" : (placeholder ?? "Project")}
+    </button>
+  );
+}
+
+// Captured at module load so we can flip it before render and trigger
+// re-renders via popstate when the hash/search changes.
+function readHostLocation() {
+  if (typeof window === "undefined") {
+    return { pathname: "/PAP/wiki", search: "", hash: "" };
+  }
+  return { pathname: window.location.pathname, search: window.location.search, hash: window.location.hash };
+}
+
+const hostLocationListeners = new Set<() => void>();
+
+function useHostLocationMock() {
+  const [snapshot, setSnapshot] = useState(readHostLocation);
+  useEffect(() => {
+    const update = () => setSnapshot(readHostLocation());
+    window.addEventListener("popstate", update);
+    window.addEventListener("hashchange", update);
+    hostLocationListeners.add(update);
+    return () => {
+      window.removeEventListener("popstate", update);
+      window.removeEventListener("hashchange", update);
+      hostLocationListeners.delete(update);
+    };
+  }, []);
+  return snapshot;
+}
+
+const sdkUi: Record<string, unknown> = {
+  usePluginData: dataResolver,
+  usePluginAction: () => async () => ({ status: "ok" }),
+  usePluginStream: () => ({ events: [], lastEvent: null, connecting: false, connected: false, error: null, close: () => undefined }),
+  usePluginToast: () => () => null,
+  useHostContext: () => HOST_CONTEXT,
+  useHostNavigation: () => ({
+    resolveHref: (to: string) => `/PAP${to.startsWith("/") ? to : `/${to}`}`,
+    navigate: (to: string) => {
+      const href = `/PAP${to.startsWith("/") ? to : `/${to}`}`;
+      window.history.pushState({}, "", href);
+      hostLocationListeners.forEach((fn) => fn());
+    },
+    linkProps: (to: string) => ({
+      href: `/PAP${to.startsWith("/") ? to : `/${to}`}`,
+      onClick: (event: { preventDefault: () => void }) => {
+        event.preventDefault();
+        const href = `/PAP${to.startsWith("/") ? to : `/${to}`}`;
+        window.history.pushState({}, "", href);
+        hostLocationListeners.forEach((fn) => fn());
+      },
+    }),
+  }),
+  useHostLocation: useHostLocationMock,
+  MarkdownBlock: MockMarkdownBlock,
+  MarkdownEditor: MockMarkdownEditor,
+  FileTree: MockFileTree,
+  IssuesList: MockIssuesList,
+  AssigneePicker: MockAssigneePicker,
+  ProjectPicker: MockProjectPicker,
+  ManagedRoutinesList: MockManagedRoutinesList,
+};
+
+(globalThis as { __paperclipPluginBridge__?: { sdkUi?: Record<string, unknown> } }).__paperclipPluginBridge__ = { sdkUi };
+
+// ---------------------------------------------------------------------------
+// Harness app: chooses which view to render based on a global hash. Playwright
+// flips the hash to switch views and path segments to drive Wiki sections.
+// ---------------------------------------------------------------------------
+
+type ViewKey = "wiki" | "wiki-sidebar" | "settings" | "sidebar";
+
+function useView() {
+  const [view, setView] = useState<ViewKey>(() => readView());
+  useEffect(() => {
+    const handler = () => setView(readView());
+    window.addEventListener("hashchange", handler);
+    return () => window.removeEventListener("hashchange", handler);
+  }, []);
+  return view;
+}
+
+function readView(): ViewKey {
+  if (typeof window === "undefined") return "wiki";
+  const hash = window.location.hash.replace(/^#/, "");
+  if (hash === "settings" || hash === "sidebar" || hash === "wiki-sidebar") return hash;
+  return "wiki";
+}
+
+export function App() {
+  const view = useView();
+  return (
+    <div style={{ height: "100vh", width: "100vw", overflow: "hidden", background: "var(--background, oklch(0.145 0 0))", color: "var(--foreground, oklch(0.985 0 0))" }}>
+      {view === "wiki-sidebar" ? (
+        <div style={{ display: "flex", height: "100vh" }}>
+          <WikiRouteSidebar context={HOST_CONTEXT as never} />
+          <div style={{ flex: 1 }}>
+            <WikiPage context={HOST_CONTEXT as never} />
+          </div>
+        </div>
+      ) : view === "sidebar" ? (
+        <aside style={{ width: 240, background: "var(--sidebar, oklch(0.145 0 0))", padding: 12, height: "100vh", borderRight: "1px solid var(--border, oklch(0.269 0 0))" }}>
+          <SidebarLink context={HOST_CONTEXT as never} />
+        </aside>
+      ) : view === "settings" ? (
+        <SettingsPage context={HOST_CONTEXT as never} />
+      ) : (
+        <WikiPage context={HOST_CONTEXT as never} />
+      )}
+    </div>
+  );
+}
diff --git a/packages/plugins/plugin-llm-wiki/tests/screenshots/index.html b/packages/plugins/plugin-llm-wiki/tests/screenshots/index.html
new file mode 100644
index 00000000..8167b10c
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/tests/screenshots/index.html
@@ -0,0 +1,84 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>LLM Wiki UI Harness</title>
+    <style>
+      :root {
+        --background: oklch(0.145 0 0);
+        --foreground: oklch(0.985 0 0);
+        --card: oklch(0.205 0 0);
+        --primary: oklch(0.985 0 0);
+        --primary-foreground: oklch(0.205 0 0);
+        --secondary: oklch(0.269 0 0);
+        --secondary-foreground: oklch(0.985 0 0);
+        --muted: oklch(0.269 0 0);
+        --muted-foreground: oklch(0.708 0 0);
+        --accent: oklch(0.269 0 0);
+        --accent-foreground: oklch(0.985 0 0);
+        --border: oklch(0.269 0 0);
+        --input: oklch(0.269 0 0);
+        --sidebar: oklch(0.145 0 0);
+      }
+      html, body, #root {
+        margin: 0;
+        padding: 0;
+        height: 100%;
+        background: var(--background);
+        color: var(--foreground);
+        font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+        font-size: 14px;
+      }
+
+      /* Minimal Tailwind utility shim — supports just the classes used by the */
+      /* plugin's WikiRouteSidebar so the screenshot harness renders something */
+      /* visually close to the production host (which compiles real Tailwind). */
+      .w-60 { width: 15rem; }
+      .h-full { height: 100%; }
+      .min-h-0 { min-height: 0; }
+      .border-r { border-right-width: 1px; border-right-style: solid; }
+      .border-t { border-top-width: 1px; border-top-style: solid; }
+      .border-border { border-color: var(--border); }
+      .bg-background { background: var(--background); }
+      .bg-accent { background: var(--accent); }
+      .flex { display: flex; }
+      .flex-col { flex-direction: column; }
+      .flex-1 { flex: 1; }
+      .items-center { align-items: center; }
+      .gap-0\.5 { gap: 0.125rem; }
+      .gap-1 { gap: 0.25rem; }
+      .gap-1\.5 { gap: 0.375rem; }
+      .gap-2 { gap: 0.5rem; }
+      .gap-2\.5 { gap: 0.625rem; }
+      .mb-2 { margin-bottom: 0.5rem; }
+      .mb-3 { margin-bottom: 0.75rem; }
+      .px-2 { padding-left: 0.5rem; padding-right: 0.5rem; }
+      .px-3 { padding-left: 0.75rem; padding-right: 0.75rem; }
+      .py-1 { padding-top: 0.25rem; padding-bottom: 0.25rem; }
+      .py-1\.5 { padding-top: 0.375rem; padding-bottom: 0.375rem; }
+      .py-2 { padding-top: 0.5rem; padding-bottom: 0.5rem; }
+      .py-3 { padding-top: 0.75rem; padding-bottom: 0.75rem; }
+      .shrink-0 { flex-shrink: 0; }
+      .text-xs { font-size: 0.75rem; line-height: 1rem; }
+      .text-sm { font-size: 0.875rem; line-height: 1.25rem; }
+      .text-\[11px\] { font-size: 11px; }
+      .text-\[13px\] { font-size: 13px; }
+      .font-medium { font-weight: 500; }
+      .font-semibold { font-weight: 600; }
+      .font-bold { font-weight: 700; }
+      .uppercase { text-transform: uppercase; }
+      .tracking-normal { letter-spacing: 0; }
+      .text-foreground { color: var(--foreground); }
+      .text-foreground\/80 { color: color-mix(in oklab, var(--foreground) 80%, transparent); }
+      .text-muted-foreground { color: var(--muted-foreground); }
+      .truncate { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+      .rounded-md { border-radius: 0.375rem; }
+      .transition-colors { transition: background-color 150ms, color 150ms; }
+      .overflow-y-auto { overflow-y: auto; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/bundle.js"></script>
+  </body>
+</html>
diff --git a/packages/plugins/plugin-llm-wiki/tests/wiki-route-sidebar-ui.spec.ts b/packages/plugins/plugin-llm-wiki/tests/wiki-route-sidebar-ui.spec.ts
new file mode 100644
index 00000000..fd52bfeb
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/tests/wiki-route-sidebar-ui.spec.ts
@@ -0,0 +1,781 @@
+// @vitest-environment jsdom
+
+import { createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { WikiPage, WikiRouteSidebar } from "../src/ui/index.js";
+
+const COMPANY_ID = "11111111-1111-4111-8111-111111111111";
+const EXPANDED_STORAGE_KEY = `paperclipai.plugin-llm-wiki:route-sidebar-expanded:v2:${COMPANY_ID}`;
+
+type BridgeGlobal = typeof globalThis & {
+  __paperclipPluginBridge__?: {
+    sdkUi?: Record<string, unknown>;
+  };
+};
+
+type FileTreeNodeLike = {
+  name: string;
+  path: string;
+  kind: string;
+  children?: FileTreeNodeLike[];
+};
+
+type FileTreePropsLike = {
+  nodes: FileTreeNodeLike[];
+  selectedFile?: string | null;
+  expandedPaths?: ReadonlySet<string> | readonly string[];
+  onToggleDir?: (path: string) => void;
+  onSelectFile?: (path: string) => void;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function createFileDragEvent(
+  type: string,
+  options: { files?: File[]; relatedTarget?: EventTarget | null } = {},
+) {
+  const event = new Event(type, { bubbles: true, cancelable: true });
+  Object.defineProperty(event, "dataTransfer", {
+    value: {
+      types: ["Files"],
+      files: options.files ?? [],
+      dropEffect: "none",
+    },
+  });
+  Object.defineProperty(event, "relatedTarget", {
+    value: options.relatedTarget ?? null,
+  });
+  return event;
+}
+
+function toArray(paths: FileTreePropsLike["expandedPaths"]): string[] {
+  if (!paths) return [];
+  return Array.isArray(paths) ? [...paths] : Array.from(paths);
+}
+
+function renderTreeButtons(
+  nodes: FileTreeNodeLike[],
+  options: Pick<FileTreePropsLike, "onSelectFile" | "onToggleDir">,
+): ReturnType<typeof createElement>[] {
+  const buttons: ReturnType<typeof createElement>[] = [];
+  for (const node of nodes) {
+    if (node.kind === "dir") {
+      buttons.push(
+        createElement("button", {
+          key: node.path,
+          type: "button",
+          "data-toggle-dir": node.path,
+          onClick: () => options.onToggleDir?.(node.path),
+        }, node.name),
+      );
+    } else {
+      buttons.push(
+        createElement("button", {
+          key: node.path,
+          type: "button",
+          "data-select-file": node.path,
+          onClick: () => options.onSelectFile?.(node.path),
+        }, node.name),
+      );
+    }
+    buttons.push(...renderTreeButtons(node.children ?? [], options));
+  }
+  return buttons;
+}
+
+describe("WikiRouteSidebar", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let hostLocation: { pathname: string; search: string; hash: string; state?: unknown };
+  let navigatedTo: { to: string; options?: unknown } | null;
+  let pluginDataCalls: Array<{ key: string; params?: Record<string, unknown> }>;
+  let pluginActionCalls: Array<{ key: string; params?: unknown }>;
+  let spacesRefreshCount: number;
+
+  beforeEach(() => {
+    window.localStorage.clear();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+    hostLocation = {
+      pathname: "/PAP/wiki/page/wiki/concepts/sidebar-navigation.md",
+      search: "",
+      hash: "",
+    };
+    navigatedTo = null;
+    pluginDataCalls = [];
+    pluginActionCalls = [];
+    spacesRefreshCount = 0;
+    (globalThis as BridgeGlobal).__paperclipPluginBridge__ = {
+      sdkUi: {
+        usePluginData: (key: string, params?: Record<string, unknown>) => {
+          pluginDataCalls.push({ key, params });
+          if (key === "spaces") {
+            return {
+              data: {
+                spaces: [
+                  {
+                    id: "space-default",
+                    companyId: COMPANY_ID,
+                    wikiId: "default",
+                    slug: "default",
+                    displayName: "default",
+                    spaceType: "managed",
+                    folderMode: "managed_subfolder",
+                    rootFolderKey: "wiki-root",
+                    pathPrefix: null,
+                    configuredRootPath: null,
+                    accessScope: "shared",
+                    ownerUserId: null,
+                    ownerAgentId: null,
+                    teamKey: null,
+                    settings: {},
+                    status: "active",
+                    createdAt: null,
+                    updatedAt: null,
+                  },
+                  {
+                    id: "space-engineering",
+                    companyId: COMPANY_ID,
+                    wikiId: "default",
+                    slug: "engineering",
+                    displayName: "Engineering",
+                    spaceType: "managed",
+                    folderMode: "managed_subfolder",
+                    rootFolderKey: "wiki-root",
+                    pathPrefix: "spaces/engineering",
+                    configuredRootPath: null,
+                    accessScope: "shared",
+                    ownerUserId: null,
+                    ownerAgentId: null,
+                    teamKey: null,
+                    settings: {},
+                    status: "active",
+                    createdAt: null,
+                    updatedAt: null,
+                  },
+                  {
+                    id: "space-archived",
+                    companyId: COMPANY_ID,
+                    wikiId: "default",
+                    slug: "qa-team-lock",
+                    displayName: "QA Team Lock",
+                    spaceType: "managed",
+                    folderMode: "managed_subfolder",
+                    rootFolderKey: "wiki-root",
+                    pathPrefix: "spaces/qa-team-lock",
+                    configuredRootPath: null,
+                    accessScope: "shared",
+                    ownerUserId: null,
+                    ownerAgentId: null,
+                    teamKey: null,
+                    settings: {},
+                    status: "archived",
+                    createdAt: null,
+                    updatedAt: null,
+                  },
+                ],
+              },
+              loading: false,
+              error: null,
+              refresh: () => {
+                spacesRefreshCount += 1;
+              },
+            };
+          }
+          if (key !== "pages") return { data: null, loading: false, error: null, refresh: () => undefined };
+          return {
+            data: {
+              pages: [
+                {
+                  path: "wiki/concepts/sidebar-navigation.md",
+                  title: "Sidebar navigation",
+                  pageType: "concepts",
+                  backlinkCount: 0,
+                  sourceCount: 0,
+                  contentHash: "abc123",
+                  updatedAt: new Date().toISOString(),
+                },
+              ],
+              sources: [],
+            },
+            loading: false,
+            error: null,
+            refresh: () => undefined,
+          };
+        },
+        usePluginAction: (key: string) => async (params?: unknown) => {
+          pluginActionCalls.push({ key, params });
+          return {};
+        },
+        usePluginToast: () => () => undefined,
+        useHostLocation: () => hostLocation,
+        useHostNavigation: () => ({
+          resolveHref: (to: string) => `/PAP${to.startsWith("/") ? to : `/${to}`}`,
+          navigate: (to: string, options?: unknown) => {
+            navigatedTo = { to, options };
+          },
+          linkProps: (to: string) => ({
+            href: `/PAP${to.startsWith("/") ? to : `/${to}`}`,
+            onClick: () => undefined,
+          }),
+        }),
+        FileTree: (props: FileTreePropsLike) => createElement(
+          "div",
+          {
+            role: "tree",
+            "data-selected-file": props.selectedFile ?? "",
+            "data-expanded-paths": toArray(props.expandedPaths).sort().join("|"),
+          },
+          renderTreeButtons(props.nodes, props),
+        ),
+      },
+    };
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+    window.localStorage.clear();
+    delete (globalThis as BridgeGlobal).__paperclipPluginBridge__;
+  });
+
+  it("defaults wiki categories open so local files are visible", () => {
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    const tree = container.querySelector("[role='tree']") as HTMLElement;
+    expect(tree.dataset.expandedPaths?.split("|")).toEqual([
+      "wiki",
+      "wiki/concepts",
+      "wiki/entities",
+      "wiki/projects",
+      "wiki/sources",
+      "wiki/synthesis",
+    ]);
+  });
+
+  it("renders Ask before Add Content in the primary sidebar tools", () => {
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    const primaryNavText = container.querySelector("nav[aria-label='Wiki primary']")?.textContent ?? "";
+    expect(primaryNavText.indexOf("Ask")).toBeLessThan(primaryNavText.indexOf("Add Content"));
+  });
+
+  it("collapses and expands the active space tree from the space row", () => {
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    expect(container.querySelector("[role='tree']")).not.toBeNull();
+
+    act(() => {
+      (container.querySelector("[aria-label='Collapse default space']") as HTMLElement).click();
+    });
+
+    expect(container.querySelector("[role='tree']")).toBeNull();
+
+    act(() => {
+      (container.querySelector("[aria-label='Expand default space']") as HTMLElement).click();
+    });
+
+    expect(container.querySelector("[role='tree']")).not.toBeNull();
+  });
+
+  it("omits redundant shared badges beside space names", () => {
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    expect(container.textContent).not.toContain("shared");
+  });
+
+  it("hides archived spaces from the sidebar", () => {
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    expect(container.textContent).toContain("Engineering");
+    expect(container.textContent).not.toContain("QA Team Lock");
+    expect(pluginDataCalls).not.toContainEqual({
+      key: "pages",
+      params: { companyId: COMPANY_ID, includeRaw: true, spaceSlug: "qa-team-lock" },
+    });
+  });
+
+  it("refreshes and leaves an archived active space after sidebar archive", async () => {
+    hostLocation = {
+      pathname: "/PAP/wiki/spaces/engineering",
+      search: "",
+      hash: "",
+    };
+    const confirm = vi.spyOn(window, "confirm").mockReturnValue(true);
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    act(() => {
+      (container.querySelector("[aria-label='Engineering space menu']") as HTMLButtonElement).click();
+    });
+    const archiveButton = Array.from(container.querySelectorAll("button"))
+      .find((button) => button.textContent?.includes("Archive space"));
+
+    await act(async () => {
+      archiveButton?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+      await Promise.resolve();
+    });
+
+    expect(pluginActionCalls).toContainEqual({
+      key: "archive-space",
+      params: { companyId: COMPANY_ID, spaceSlug: "engineering" },
+    });
+    expect(spacesRefreshCount).toBe(1);
+    expect(navigatedTo).toEqual({ to: "/wiki", options: undefined });
+    confirm.mockRestore();
+  });
+
+  it("persists folder expansion client-side", () => {
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    act(() => {
+      (container.querySelector("[data-toggle-dir='raw']") as HTMLButtonElement).click();
+    });
+
+    // Toggled paths are stored under the active space slug ("default::") so
+    // each space remembers its own expansion state. Legacy entries written
+    // before the spaces refactor stay un-prefixed and still resolve to default.
+    expect(JSON.parse(window.localStorage.getItem(EXPANDED_STORAGE_KEY) ?? "[]")).toEqual([
+      "default::raw",
+      "wiki",
+      "wiki/concepts",
+      "wiki/entities",
+      "wiki/projects",
+      "wiki/sources",
+      "wiki/synthesis",
+    ]);
+
+    act(() => {
+      root.unmount();
+    });
+    root = createRoot(container);
+
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    const tree = container.querySelector("[role='tree']") as HTMLElement;
+    expect(tree.dataset.expandedPaths).toBe("raw|wiki|wiki/concepts|wiki/entities|wiki/projects|wiki/sources|wiki/synthesis");
+  });
+
+  it("does not select a wiki-link destination from the route", () => {
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    const tree = () => container.querySelector("[role='tree']") as HTMLElement;
+    expect(tree().dataset.selectedFile).toBe("");
+  });
+
+  it("keeps sidebar tree selection scoped to sidebar navigation", () => {
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    const tree = () => container.querySelector("[role='tree']") as HTMLElement;
+
+    act(() => {
+      (container.querySelector("[data-select-file='wiki/concepts/sidebar-navigation.md']") as HTMLButtonElement).click();
+    });
+
+    expect(navigatedTo).toEqual({
+      to: "/wiki/page/wiki/concepts/sidebar-navigation.md",
+      options: { state: { paperclipWikiSidebarTreePath: "wiki/concepts/sidebar-navigation.md" } },
+    });
+    // The default space stays the active space, so its tree is rendered in the
+    // sidebar; non-default spaces only render their tree once activated.
+    expect(tree().dataset.selectedFile).toBe("wiki/concepts/sidebar-navigation.md");
+
+    hostLocation = {
+      pathname: "/PAP/wiki/page/wiki/entities/paperclip.md",
+      search: "",
+      hash: "",
+    };
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    expect(tree().dataset.selectedFile).toBe("wiki/concepts/sidebar-navigation.md");
+
+    act(() => {
+      (container.querySelector("[data-toggle-dir='wiki/concepts']") as HTMLButtonElement).click();
+    });
+
+    expect(tree().dataset.selectedFile).toBe("wiki/concepts/sidebar-navigation.md");
+    expect(tree().dataset.expandedPaths?.split("|")).not.toContain("wiki/concepts");
+  });
+
+  it("warms inactive space pages so sidebar space switches have data ready", () => {
+    act(() => {
+      root.render(createElement(WikiRouteSidebar, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    expect(pluginDataCalls).toContainEqual({
+      key: "pages",
+      params: { companyId: COMPANY_ID, includeRaw: true, spaceSlug: "engineering" },
+    });
+    expect(pluginDataCalls).toContainEqual({
+      key: "page-content",
+      params: { companyId: COMPANY_ID, path: "wiki/concepts/sidebar-navigation.md", spaceSlug: "engineering" },
+    });
+  });
+});
+
+describe("WikiPage", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let consoleError: ReturnType<typeof vi.spyOn>;
+  let hostLocation: { pathname: string; search: string; hash: string };
+  let navigatedTo: string | null;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+    consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    hostLocation = {
+      pathname: "/PAP/wiki/page/wiki/projects/control-plane/index.md",
+      search: "",
+      hash: "",
+    };
+    navigatedTo = null;
+    (globalThis as BridgeGlobal).__paperclipPluginBridge__ = {
+      sdkUi: {
+        usePluginData: (key: string) => {
+          if (key === "overview") {
+            return {
+              data: { folder: { healthy: true }, wikiId: "default" },
+              loading: false,
+              error: null,
+              refresh: () => undefined,
+            };
+          }
+          if (key === "spaces") {
+            return {
+              data: {
+                spaces: [
+                  {
+                    id: "space-default",
+                    companyId: COMPANY_ID,
+                    wikiId: "default",
+                    slug: "default",
+                    displayName: "default",
+                    spaceType: "managed",
+                    folderMode: "managed_subfolder",
+                    rootFolderKey: "wiki-root",
+                    pathPrefix: null,
+                    configuredRootPath: null,
+                    accessScope: "shared",
+                    ownerUserId: null,
+                    ownerAgentId: null,
+                    teamKey: null,
+                    settings: {},
+                    status: "active",
+                    createdAt: null,
+                    updatedAt: null,
+                  },
+                ],
+              },
+              loading: false,
+              error: null,
+              refresh: () => undefined,
+            };
+          }
+          if (key === "settings") {
+            return {
+              data: {
+                folder: {
+                  configured: true,
+                  path: "/tmp/company-wiki",
+                  realPath: "/tmp/company-wiki",
+                  access: "readWrite",
+                  readable: true,
+                  writable: true,
+                  requiredDirectories: [],
+                  requiredFiles: [],
+                  missingDirectories: [],
+                  missingFiles: [],
+                  healthy: true,
+                  problems: [],
+                  checkedAt: new Date().toISOString(),
+                },
+                managedAgent: {
+                  status: "resolved",
+                  source: "managed",
+                  agentId: "agent-1",
+                  resourceKey: "wiki-maintainer",
+                  details: { name: "Wiki Maintainer", status: "idle", adapterType: "claude_local", icon: "book-open", urlKey: "wiki-maintainer" },
+                },
+                managedProject: {
+                  status: "resolved",
+                  source: "managed",
+                  projectId: "project-1",
+                  resourceKey: "llm-wiki",
+                  details: { name: "LLM Wiki", status: "in_progress" },
+                },
+                managedSkills: [],
+                managedRoutines: [],
+                eventIngestion: {
+                  enabled: false,
+                  sources: { issues: false, comments: false, documents: false },
+                  wikiId: "default",
+                  maxCharacters: 12000,
+                },
+                agentOptions: [{ id: "agent-1", name: "Wiki Maintainer", status: "idle", icon: "book-open", urlKey: "wiki-maintainer" }],
+                projectOptions: [{ id: "project-1", name: "LLM Wiki", status: "in_progress", color: "#2563eb" }],
+                capabilities: [],
+              },
+              loading: false,
+              error: null,
+              refresh: () => undefined,
+            };
+          }
+          if (key === "pages") {
+            return {
+              data: {
+                pages: [
+                  {
+                    path: "wiki/projects/control-plane/index.md",
+                    title: "Control plane",
+                    pageType: "projects",
+                    backlinkCount: 0,
+                    sourceCount: 1,
+                    contentHash: "abc123",
+                    updatedAt: new Date().toISOString(),
+                  },
+                ],
+                sources: [],
+              },
+              loading: false,
+              error: null,
+              refresh: () => undefined,
+            };
+          }
+          if (key === "page-content") {
+            return {
+              data: {
+                wikiId: "default",
+                path: "wiki/projects/control-plane/index.md",
+                contents: "# Control plane\n\nCurrent project state.",
+                title: "Control plane",
+                pageType: "projects",
+                backlinks: [],
+                sourceRefs: [
+                  {
+                    kind: "issue",
+                    title: "Distillation kickoff",
+                    issueId: "issue-1",
+                    projectId: "project-1",
+                    updatedAt: "2026-05-04T15:01:00Z",
+                    issueIdentifier: "PAP-3416",
+                  },
+                ],
+                updatedAt: "2026-05-04T15:01:00Z",
+                hash: "def456",
+              },
+              loading: false,
+              error: null,
+              refresh: () => undefined,
+            };
+          }
+          if (key === "distillation-page-provenance") {
+            return { data: null, loading: false, error: null, refresh: () => undefined };
+          }
+          return { data: null, loading: false, error: null, refresh: () => undefined };
+        },
+        usePluginAction: () => async () => ({}),
+        usePluginToast: () => () => undefined,
+        useHostLocation: () => hostLocation,
+        useHostNavigation: () => ({
+          resolveHref: (to: string) => `/PAP${to.startsWith("/") ? to : `/${to}`}`,
+          navigate: (to: string) => {
+            navigatedTo = to;
+          },
+          linkProps: (to: string) => ({
+            href: `/PAP${to.startsWith("/") ? to : `/${to}`}`,
+            onClick: () => undefined,
+          }),
+        }),
+        MarkdownBlock: ({ content }: { content: string }) => createElement("div", {}, content),
+        MarkdownEditor: ({ value }: { value: string }) => createElement("textarea", { value, readOnly: true }),
+        AssigneePicker: () => createElement("div", { "data-testid": "assignee-picker" }),
+        ProjectPicker: () => createElement("div", { "data-testid": "project-picker" }),
+      },
+    };
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+    consoleError.mockRestore();
+    delete (globalThis as BridgeGlobal).__paperclipPluginBridge__;
+  });
+
+  it("renders structured Paperclip source refs as text", () => {
+    act(() => {
+      root.render(createElement(WikiPage, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    expect(container.textContent).toContain("PAP-3416 issue - Distillation kickoff");
+    const consoleOutput = consoleError.mock.calls.flat().join("\n");
+    expect(consoleOutput).not.toContain("Objects are not valid as a React child");
+    expect(consoleOutput).not.toContain("Each child in a list should have a unique \"key\" prop");
+  });
+
+  it("prioritizes file drop on the ingest page without recent ingest or cost copy", () => {
+    hostLocation = {
+      pathname: "/PAP/wiki/ingest",
+      search: "",
+      hash: "",
+    };
+
+    act(() => {
+      root.render(createElement(WikiPage, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    const text = container.textContent ?? "";
+    expect(text).toContain("Drop files anywhere on this page");
+    expect(text).not.toContain("Recent ingests");
+    expect(text).not.toContain("Why does this take a moment?");
+    expect(text).not.toContain("est. cost");
+
+    const separatorText = container.querySelector("[data-testid='llm-wiki-ingest-manual-separator']")?.textContent ?? "";
+    expect(separatorText).toBe("or");
+    expect(text.indexOf("Drop files anywhere on this page")).toBeLessThan(text.indexOf("Source title"));
+    expect(text.indexOf("Source title")).toBeLessThan(text.indexOf("URL"));
+    expect(text.indexOf("URL")).toBeLessThan(text.indexOf("Paste markdown / text"));
+  });
+
+  it("closes the page drop overlay when a file drag leaves without dropping files", () => {
+    act(() => {
+      root.render(createElement(WikiPage, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    const page = container.querySelector("main") as HTMLElement;
+    act(() => {
+      page.dispatchEvent(createFileDragEvent("dragenter"));
+    });
+
+    expect(container.querySelector("[data-testid='llm-wiki-page-drop-overlay']")).not.toBeNull();
+
+    act(() => {
+      page.dispatchEvent(createFileDragEvent("dragleave"));
+    });
+
+    expect(container.querySelector("[data-testid='llm-wiki-page-drop-overlay']")).toBeNull();
+    expect(container.querySelector("[data-testid='llm-wiki-ingest-modal']")).toBeNull();
+  });
+
+  it("keeps staged dropped files in the ingest modal after the drop overlay clears", () => {
+    act(() => {
+      root.render(createElement(WikiPage, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    const page = container.querySelector("main") as HTMLElement;
+    const file = new File(["source notes"], "source-notes.md", { type: "text/markdown" });
+
+    act(() => {
+      page.dispatchEvent(createFileDragEvent("dragenter"));
+      page.dispatchEvent(createFileDragEvent("drop", { files: [file] }));
+    });
+
+    expect(container.querySelector("[data-testid='llm-wiki-page-drop-overlay']")).toBeNull();
+    expect(container.querySelector("[data-testid='llm-wiki-ingest-modal']")).not.toBeNull();
+    expect(container.textContent).toContain("source-notes.md");
+  });
+
+  it("lets users close the page drop overlay directly", () => {
+    act(() => {
+      root.render(createElement(WikiPage, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    const page = container.querySelector("main") as HTMLElement;
+    act(() => {
+      page.dispatchEvent(createFileDragEvent("dragenter"));
+    });
+
+    const closeButton = container.querySelector("[aria-label='Close ingest drop overlay']") as HTMLButtonElement;
+    expect(closeButton).not.toBeNull();
+
+    act(() => {
+      closeButton.click();
+    });
+
+    expect(container.querySelector("[data-testid='llm-wiki-page-drop-overlay']")).toBeNull();
+  });
+
+  it("navigates settings tabs to their URL subpaths", () => {
+    hostLocation = {
+      pathname: "/PAP/wiki/settings",
+      search: "",
+      hash: "",
+    };
+
+    act(() => {
+      root.render(createElement(WikiPage, {
+        context: { companyId: COMPANY_ID, companyPrefix: "PAP" },
+      } as never));
+    });
+
+    act(() => {
+      (Array.from(container.querySelectorAll("button")).find((button) => button.textContent?.includes("Distillation")) as HTMLButtonElement).click();
+    });
+
+    expect(navigatedTo).toBe("/wiki/settings/distillation");
+  });
+});
diff --git a/packages/plugins/plugin-llm-wiki/tsconfig.json b/packages/plugins/plugin-llm-wiki/tsconfig.json
new file mode 100644
index 00000000..a697519e
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": [
+    "src",
+    "tests"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}
diff --git a/packages/plugins/plugin-llm-wiki/vitest.config.ts b/packages/plugins/plugin-llm-wiki/vitest.config.ts
new file mode 100644
index 00000000..649a293e
--- /dev/null
+++ b/packages/plugins/plugin-llm-wiki/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.spec.ts"],
+    environment: "node",
+  },
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/README.md b/packages/plugins/sandbox-providers/kubernetes/README.md
new file mode 100644
index 00000000..ddbfa759
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/README.md
@@ -0,0 +1,172 @@
+# @paperclipai/plugin-kubernetes (alpha)
+
+First-party Paperclip sandbox-provider plugin for Kubernetes.
+
+**Alpha:** the default backend (`sandbox-cr`) is built on `kubernetes-sigs/agent-sandbox` v1alpha1 — expect breaking changes as that CRD evolves toward Beta. A stable fallback backend (`job`, using `batch/v1` Job) is available for clusters without agent-sandbox installed, but it does NOT support multi-command exec (paperclip-server's adapter-install pattern requires sandbox-cr).
+
+## Prerequisites
+
+### For `sandbox-cr` backend (default, recommended)
+
+1. A Kubernetes cluster running k8s 1.27+
+2. [`kubernetes-sigs/agent-sandbox`](https://github.com/kubernetes-sigs/agent-sandbox) controller installed in the cluster (alpha — installs the `sandboxes.agents.x-k8s.io/v1alpha1` CRD and controller)
+3. Paperclip-server running with access to the cluster (in-cluster via `inCluster: true` or external via `kubeconfig`)
+
+### For `job` backend (stable fallback)
+
+1. A Kubernetes cluster running k8s 1.27+
+2. Paperclip-server with cluster access — no additional controllers or CRDs required
+
+## Installation
+
+```bash
+paperclipai plugin install @paperclipai/plugin-kubernetes
+```
+
+Or, for local development:
+
+```bash
+paperclipai plugin install --local /path/to/paperclip/packages/plugins/sandbox-providers/kubernetes
+```
+
+## Backends
+
+The plugin supports two backend modes, selected via the `backend` config field:
+
+| Backend | Default | Stability | Multi-command exec | Requires |
+|---|---|---|---|---|
+| `sandbox-cr` | Yes | Alpha | Yes | `kubernetes-sigs/agent-sandbox` controller |
+| `job` | No | Stable | No | Nothing beyond k8s 1.27+ |
+
+**`sandbox-cr` (default):** Creates a `Sandbox` CR (`agents.x-k8s.io/v1alpha1`) whose controller provisions a long-lived pod running `sleep infinity`. paperclip-server execs individual commands into the running pod — this is the multi-command adapter-install pattern. When you `releaseLease`, the Sandbox CR is deleted and the controller tears down the pod.
+
+**`job` (stable fallback):** Creates a `batch/v1` Job. The container entrypoint runs once and exits — no multi-command exec possible. Use this when you cannot install agent-sandbox, or when you need strictly stable Kubernetes APIs. Note: paperclip-server's adapter-install pattern will not work in job mode.
+
+### Migrating from `job` to `sandbox-cr`
+
+1. Install the agent-sandbox controller: `kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/install.yaml`
+2. Update your environment config to set `backend: "sandbox-cr"` (or remove `backend` since `sandbox-cr` is the default)
+3. New leases will use the Sandbox CR backend. Existing leases created with `job` mode continue to use job semantics until they are released.
+
+## Configuration
+
+Create a `sandbox` environment with `driver: kubernetes`. One of these auth fields is required:
+
+- `inCluster: true` — use the in-pod ServiceAccount credentials (when paperclip-server runs inside the same cluster).
+- `kubeconfig: <YAML>` — inline kubeconfig (stored as a company secret).
+- `kubeconfigSecretRef: <secret-uuid>` — reference to an existing Paperclip secret.
+
+Common optional fields:
+
+| Field | Default | Purpose |
+|---|---|---|
+| `backend` | `"sandbox-cr"` | `sandbox-cr` (alpha, requires agent-sandbox controller) or `job` (stable, one-shot entrypoint). |
+| `adapterType` | `"claude_local"` | One of the supported adapter types (claude_local, codex_local, gemini_local, cursor_local, opencode_local, acpx_local, pi_local). Determines runtime image + env keys + egress allow-list. |
+| `namespacePrefix` | `"paperclip-"` | Prefix for the per-company tenant namespace. |
+| `paperclipServerNamespace` | `"paperclip"` | Namespace where paperclip-server pods run. Generated egress policies use this so agent pods can call back to the server. |
+| `companySlug` | derived from companyId | Override the auto-derived company slug. |
+| `imageRegistry` | (none) | Override the default registry for agent runtime images. |
+| `imageAllowList` | `[]` | Glob patterns of allowed `target.imageOverride` values. Empty = no override permitted. |
+| `imagePullSecrets` | `[]` | Names of pre-created Docker image pull secrets in the tenant namespace. |
+| `egressAllowFqdns` | `[]` | Additional FQDNs (beyond adapter defaults like `api.anthropic.com`). |
+| `egressAllowCidrs` | `[]` | Additional CIDRs to allow HTTPS egress to. CIDR egress is restricted to TCP port 443. |
+| `egressMode` | `"standard"` | `standard` (NetworkPolicy + CIDRs, plus public HTTPS fallback when adapter FQDNs are configured) or `cilium` (CiliumNetworkPolicy + exact FQDN allow-list). |
+| `runtimeClassName` | (none) | e.g. `kata-fc` for Firecracker-backed microVMs. Cluster must have the RuntimeClass installed. |
+| `serviceAccountAnnotations` | `{}` | Annotations applied to per-tenant ServiceAccount (e.g. IRSA `eks.amazonaws.com/role-arn`). |
+| `jobTtlSecondsAfterFinished` | `900` | Seconds after a Job completes before garbage-collection. |
+| `podActivityDeadlineSec` | `3600` | Hard ceiling on a single run's wall-clock time. |
+
+Full JSON Schema in `src/manifest.ts`.
+
+## What gets created in your cluster
+
+For each company that runs agents (created lazily on first dispatch):
+
+```
+Namespace          paperclip-{companySlug}        (PSS: restricted enforce + audit)
+ServiceAccount     paperclip-tenant-sa
+Role               paperclip-tenant-role          (only get pods/log)
+RoleBinding        paperclip-tenant-rb
+ResourceQuota      paperclip-quota                (pods, requests/limits cpu+memory)
+LimitRange         paperclip-limits               (container max/min/default/defaultRequest)
+NetworkPolicy      paperclip-deny-all             (deny ingress + egress baseline)
+NetworkPolicy      paperclip-egress-allow         (DNS + paperclip-server callback + user CIDRs + public HTTPS fallback for adapter FQDNs)
+                   OR CiliumNetworkPolicy paperclip-egress-fqdn if egressMode=cilium
+```
+
+Standard Kubernetes NetworkPolicy cannot match FQDNs. In `egressMode: "standard"`, adapter-default FQDNs such as `api.anthropic.com` trigger a public IPv4 HTTPS fallback that excludes private and link-local ranges, so default agent runs can reach model APIs without opening intra-cluster/private-network egress. Use `egressMode: "cilium"` when you need exact FQDN enforcement.
+
+For each agent run (sandbox-cr backend):
+
+```
+Sandbox CR         pc-{ulid}                       (agents.x-k8s.io/v1alpha1; explicit delete on release)
+Pod                pc-{ulid}-{podSuffix}           (managed by Sandbox controller; torn down on CR delete)
+Secret             pc-{ulid}-env                   (owned by Sandbox CR; cascade-deleted)
+```
+
+## Fast workspace uploads
+
+The `sandbox-cr` backend recognizes the chunked base64 upload protocol emitted by `@paperclipai/adapter-utils` for workspace, skill, and config-seed file transfers. Instead of running one Kubernetes exec per base64 chunk, the plugin buffers the upload in worker memory and flushes the final payload through a single `head -c <bytes> | base64 -d` exec with stdin.
+
+The interceptor is intentionally narrow: only the exact `mkdir`/`printf`/`base64 -d` command shape generated by adapter-utils is optimized. Unknown commands and missing init state fall back to normal exec behavior. Uploads over the 100 MB buffer cap fail fast instead of falling back, because earlier chunks were already acknowledged without being written to the pod.
+
+For each agent run (job backend):
+
+```
+Job                pc-{ulid}                       (backoffLimit: 0, ttlSecondsAfterFinished from config)
+Pod                pc-{ulid}-{podSuffix}           (owned by Job; cascade-deleted)
+Secret             pc-{ulid}-env                   (owned by Job; cascade-deleted)
+```
+
+## Security baseline
+
+Every agent pod is:
+
+- non-root (`runAsUser: 1000`, `runAsGroup: 1000`, `runAsNonRoot: true`)
+- drops ALL Linux capabilities, `allowPrivilegeEscalation: false`
+- `readOnlyRootFilesystem: true` with explicit `emptyDir` mounts for `/workspace`, `/home/paperclip`, `/home/paperclip/.cache`, `/tmp`
+- `seccompProfile: RuntimeDefault`
+- Tini as PID 1 (reaps zombies, forwards signals)
+- `fsGroupChangePolicy: OnRootMismatch` (fast PVC startup; openclaw-operator lesson)
+- `automountServiceAccountToken: false`
+
+Plus per-namespace `pod-security.kubernetes.io/enforce: restricted` and a deny-all NetworkPolicy baseline with explicit egress allow-list (DNS, paperclip-server, CIDRs, and either Cilium FQDN rules or standard-mode public HTTPS fallback).
+
+The per-run Secret carrying the bootstrap token and adapter API keys has `ownerReferences` pointing at the owning Sandbox CR or Job, so releasing the lease cascades cleanly to the Pod and Secret.
+
+## Optional Kata-FC microVM isolation
+
+For stronger isolation, install [Kata Containers](https://github.com/kata-containers/kata-containers) with the Firecracker hypervisor, then set `runtimeClassName: kata-fc` in the plugin config. Each agent pod will run inside a Firecracker microVM. Requires nested-virt-capable nodes (bare-metal or specific cloud instance types).
+
+## Roadmap
+
+- **Phase A (done):** `sandbox-cr` backend — multi-command exec via agent-sandbox Sandbox CRD.
+- **Phase B:** Warm pool support — pre-provisioned Sandbox CRs for sub-second cold starts. The `SandboxOrchestrator` interface reserves optional `pause?`/`resume?` extension slots.
+- **Phase C:** Kata-FC + snapshots — `runtimeClassName: kata-fc` with VM snapshot for fast restore.
+- **Phase D:** Contribute back to agent-sandbox upstream if their Beta model diverges from our needs. The `SandboxOrchestrator` interface (`src/sandbox-orchestrator.ts`) is the clean swap point — a new implementation can be added without touching `plugin.ts` business logic.
+
+## Lessons learned (from openclaw-operator)
+
+This plugin adopts patterns from `openclaw-rocks/openclaw-operator`:
+
+- Tini PID 1 (issue #471 — zombie helper processes)
+- Read-only rootFS with explicit writable mounts (issue #456 — ~/.config not writable)
+- Strategic merge on reconcile (issue #446 — preserve third-party annotations)
+- Multi-storage-class testing (issue #448 — `local-path-provisioner` differences)
+- Image version compat matrix (issue #462 — runtime deps cannot resolve after upgrade)
+
+## Development
+
+```bash
+cd packages/plugins/sandbox-providers/kubernetes
+pnpm install --ignore-workspace
+pnpm test           # unit tests only (fast)
+pnpm typecheck
+pnpm build
+```
+
+To run the kind-cluster integration test (requires `kubectl --context kind-paperclip` and a pre-loaded alpine image; see `test/integration/end-to-end-run.test.ts`):
+
+```bash
+RUN_K8S_INTEGRATION_TESTS=1 pnpm test test/integration/end-to-end-run.test.ts
+```
diff --git a/packages/plugins/sandbox-providers/kubernetes/SMOKE.md b/packages/plugins/sandbox-providers/kubernetes/SMOKE.md
new file mode 100644
index 00000000..72b32e0b
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/SMOKE.md
@@ -0,0 +1,137 @@
+# Manual smoke test — `@paperclipai/plugin-kubernetes`
+
+Manual sanity check that the plugin works end-to-end against a real
+paperclip-server instance and a real Kubernetes cluster (kind for local
+dev). Future work may automate this in CI.
+
+## Prerequisites
+
+- A running kind cluster:
+  ```bash
+  kind create cluster --name paperclip
+  ```
+- `kubectl --context kind-paperclip get nodes` returns a node in `Ready` state.
+
+## Steps
+
+### 1. Build the plugin
+
+```bash
+cd packages/plugins/sandbox-providers/kubernetes
+pnpm install --ignore-workspace
+pnpm build
+```
+
+Expected: `dist/` populated with compiled `.js` and `.d.ts` files. No errors.
+
+### 2. Start paperclip-server in dev mode
+
+In a separate terminal:
+
+```bash
+cd /path/to/paperclip
+export PAPERCLIP_HOME=/tmp/paperclip-smoke
+export PAPERCLIP_INSTANCE_ID=smoke
+export PAPERCLIP_DEPLOYMENT_MODE=local_trusted
+pnpm --filter @paperclipai/server dev
+```
+
+Wait for `Server listening on 127.0.0.1:3100`.
+
+### 3. Install the plugin via the CLI
+
+```bash
+pnpm paperclipai plugin install \
+  --local /path/to/paperclip/packages/plugins/sandbox-providers/kubernetes \
+  --api-base http://127.0.0.1:3100
+```
+
+Expected: `✓ Installed paperclip.kubernetes-sandbox-provider v0.1.0 (ready)`.
+
+### 4. Create a company and a kubernetes sandbox environment
+
+```bash
+CO_ID=$(curl -s -X POST -H "Content-Type: application/json" \
+  -d '{"name":"SmokeCo"}' \
+  http://127.0.0.1:3100/api/companies | jq -r '.id')
+
+KUBECONFIG_CONTENT=$(cat ~/.kube/config | jq -Rs .)
+
+curl -s -X POST -H "Content-Type: application/json" \
+  -d "{
+    \"name\": \"k8s-sandbox\",
+    \"driver\": \"sandbox\",
+    \"config\": {
+      \"provider\": \"kubernetes\",
+      \"kubeconfig\": $KUBECONFIG_CONTENT,
+      \"companySlug\": \"smoke\",
+      \"adapterType\": \"claude_local\",
+      \"imageAllowList\": [\"ghcr.io/paperclipai/agent-runtime-claude:v1\"]
+    }
+  }" \
+  http://127.0.0.1:3100/api/companies/$CO_ID/environments | jq
+```
+
+Expected: HTTP 201 with the new environment row.
+
+### 5. Probe the environment
+
+```bash
+ENV_ID=$(curl -s http://127.0.0.1:3100/api/companies/$CO_ID/environments | jq -r '.[0].id')
+curl -s -X POST -d '{}' -H "Content-Type: application/json" \
+  http://127.0.0.1:3100/api/environments/$ENV_ID/probe | jq
+```
+
+Expected: `{"ok": true, ...}` with a summary mentioning the tenant namespace
+(`paperclip-smoke`). On first probe the namespace may not yet exist —
+the plugin treats a 404 on `listNamespacedPod` as a successful reachability
+check.
+
+### 6. Trigger an agent run
+
+Use the UI or the API to dispatch a run against the `k8s-sandbox` environment.
+The plugin's `onEnvironmentAcquireLease` will:
+
+1. `ensureTenant` — provision the `paperclip-smoke` namespace, SA, Role,
+   RoleBinding, ResourceQuota, LimitRange, NetworkPolicies
+2. `buildSandboxCrManifest` — render the security-hardened Sandbox CR manifest
+3. `createNamespacedCustomObject` — submit to `agents.x-k8s.io/v1alpha1`
+4. `createPerRunSecret` — owned by the Sandbox CR for cascade-delete
+5. Fast-upload workspace/config/skill payloads by collapsing adapter-utils chunked uploads into a single stdin-backed exec per file
+
+### 7. Verify the tenant resources
+
+```bash
+kubectl --context kind-paperclip get namespace paperclip-smoke
+kubectl --context kind-paperclip get all,networkpolicy,resourcequota,limitrange,sa,role,rolebinding -n paperclip-smoke
+```
+
+Expected:
+
+- Namespace `paperclip-smoke` exists with PSS labels
+  (`pod-security.kubernetes.io/enforce=restricted`)
+- ServiceAccount `paperclip-tenant-sa`
+- Role `paperclip-tenant-role`, RoleBinding `paperclip-tenant-rb`
+- ResourceQuota `paperclip-quota`, LimitRange `paperclip-limits`
+- NetworkPolicies `paperclip-deny-all` + `paperclip-egress-allow`
+- Sandbox `pc-{ulid}` and its managed Pod
+- Secret `pc-{ulid}-env` with `ownerReferences` pointing at the Sandbox CR
+- Run logs or plugin metadata include `fastUpload: "flush"` entries during workspace/config/skill upload
+
+### 8. Tear down
+
+```bash
+kubectl --context kind-paperclip delete namespace paperclip-smoke
+kill %1  # paperclip-server
+```
+
+### 9. Document the result
+
+In the PR description (or appended to this file as a dated section),
+record:
+
+- Date + git SHA
+- `kubectl version` server version
+- Output of `kubectl get all -n paperclip-smoke` after step 6
+- Probe response from step 5
+- Time-to-acquire-lease (target: <30s on kind for a cold tenant)
diff --git a/packages/plugins/sandbox-providers/kubernetes/manifests/operator-prerequisites.yaml b/packages/plugins/sandbox-providers/kubernetes/manifests/operator-prerequisites.yaml
new file mode 100644
index 00000000..1cb9c96a
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/manifests/operator-prerequisites.yaml
@@ -0,0 +1,22 @@
+# This plugin uses only stable Kubernetes APIs. No CRD installation is required.
+#
+# Minimum cluster version: Kubernetes 1.27+
+#   - batch/v1 Job (GA since k8s 1.21)
+#   - core/v1 Pod, Secret, Namespace, ServiceAccount, ResourceQuota, LimitRange (GA since k8s 1.0)
+#   - rbac.authorization.k8s.io/v1 Role, RoleBinding (GA since k8s 1.8)
+#   - networking.k8s.io/v1 NetworkPolicy (GA since k8s 1.7)
+#   - Pod Security Standards namespace labels (GA in k8s 1.25)
+#   - fsGroupChangePolicy: OnRootMismatch (GA in k8s 1.23)
+#   - seccompProfile.type: RuntimeDefault (GA in k8s 1.19)
+#
+# Optional CNI prerequisites for FQDN-based egress (egressMode: cilium):
+#   - Cilium >= 1.11 with hubble + DNS proxy enabled
+#   - cilium.io/v2 CiliumNetworkPolicy (provided by Cilium installation)
+#
+# Optional runtime class for microVM isolation (runtimeClassName: kata-fc):
+#   - kata-containers with Firecracker hypervisor
+#   - nested-virt-capable nodes
+#
+# Future backends (not currently required):
+#   - kubernetes-sigs/agent-sandbox (when it reaches v1beta1) as an alternative
+#     backend for warm pools / templates / pause-resume.
diff --git a/packages/plugins/sandbox-providers/kubernetes/package.json b/packages/plugins/sandbox-providers/kubernetes/package.json
new file mode 100644
index 00000000..4f6fdef6
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/package.json
@@ -0,0 +1,60 @@
+{
+  "name": "@paperclipai/plugin-kubernetes",
+  "version": "0.1.0",
+  "description": "Kubernetes sandbox provider plugin for Paperclip environments",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/plugins/sandbox-providers/kubernetes"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "files": ["dist", "manifests", "README.md"],
+  "paperclipPlugin": {
+    "manifest": "./dist/manifest.js",
+    "worker": "./dist/worker.js"
+  },
+  "keywords": [
+    "paperclip",
+    "plugin",
+    "sandbox",
+    "kubernetes"
+  ],
+  "scripts": {
+    "postinstall": "node ../../../../scripts/link-plugin-dev-sdk.mjs",
+    "prebuild": "pnpm -C ../../../.. --filter @paperclipai/plugin-sdk ensure-build-deps",
+    "build": "rm -rf dist && tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "pnpm -C ../../../.. --filter @paperclipai/plugin-sdk ensure-build-deps && tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "prepack": "rm -f package.dev.json && cp package.json package.dev.json && node ../../../../scripts/generate-plugin-package-json.mjs",
+    "postpack": "if [ -f package.dev.json ]; then mv package.dev.json package.json; fi"
+  },
+  "dependencies": {
+    "@kubernetes/client-node": "^1.0.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4"
+  }
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/adapter-defaults.ts b/packages/plugins/sandbox-providers/kubernetes/src/adapter-defaults.ts
new file mode 100644
index 00000000..149cb0d0
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/adapter-defaults.ts
@@ -0,0 +1,61 @@
+export interface AdapterDefaults {
+  runtimeImage: string;
+  envKeys: string[];
+  allowFqdns: string[];
+  probeCommand: string[];
+}
+
+const REGISTRY: Record<string, AdapterDefaults> = {
+  claude_local: {
+    runtimeImage: "ghcr.io/paperclipai/agent-runtime-claude:v1",
+    envKeys: ["ANTHROPIC_API_KEY"],
+    allowFqdns: ["api.anthropic.com"],
+    probeCommand: ["claude", "--version"],
+  },
+  codex_local: {
+    runtimeImage: "ghcr.io/paperclipai/agent-runtime-codex:v1",
+    envKeys: ["OPENAI_API_KEY"],
+    allowFqdns: ["api.openai.com"],
+    probeCommand: ["codex", "--version"],
+  },
+  gemini_local: {
+    runtimeImage: "ghcr.io/paperclipai/agent-runtime-gemini:v1",
+    envKeys: ["GOOGLE_API_KEY", "GEMINI_API_KEY"],
+    allowFqdns: ["generativelanguage.googleapis.com"],
+    probeCommand: ["gemini", "--version"],
+  },
+  cursor_local: {
+    runtimeImage: "ghcr.io/paperclipai/agent-runtime-cursor:v1",
+    envKeys: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+    allowFqdns: ["api.anthropic.com", "api.openai.com"],
+    probeCommand: ["cursor-agent", "--version"],
+  },
+  opencode_local: {
+    runtimeImage: "ghcr.io/paperclipai/agent-runtime-opencode:v1",
+    envKeys: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "OPENROUTER_API_KEY"],
+    allowFqdns: ["api.anthropic.com", "api.openai.com", "openrouter.ai"],
+    probeCommand: ["opencode", "--version"],
+  },
+  acpx_local: {
+    runtimeImage: "ghcr.io/paperclipai/agent-runtime-acpx:v1",
+    envKeys: ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+    allowFqdns: ["api.anthropic.com", "api.openai.com"],
+    probeCommand: ["acpx", "--version"],
+  },
+  pi_local: {
+    runtimeImage: "ghcr.io/paperclipai/agent-runtime-pi:v1",
+    envKeys: ["ANTHROPIC_API_KEY"],
+    allowFqdns: ["api.anthropic.com"],
+    probeCommand: ["pi", "--version"],
+  },
+};
+
+export const KNOWN_ADAPTER_TYPES: ReadonlySet<string> = new Set(Object.keys(REGISTRY));
+
+export function getAdapterDefaults(adapterType: string): AdapterDefaults {
+  const defaults = REGISTRY[adapterType];
+  if (!defaults) {
+    throw new Error(`Unknown adapter type: ${adapterType}`);
+  }
+  return defaults;
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/cilium-network-policy.ts b/packages/plugins/sandbox-providers/kubernetes/src/cilium-network-policy.ts
new file mode 100644
index 00000000..faaa466f
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/cilium-network-policy.ts
@@ -0,0 +1,69 @@
+export interface BuildCiliumNetworkPolicyInput {
+  namespace: string;
+  paperclipServerNamespace: string;
+  egressAllowFqdns: string[];
+  egressAllowCidrs: string[];
+}
+
+// Design note: no ingress rules are defined here. Paperclip-server does NOT
+// push to agent pods — agents make outbound (egress) callbacks to
+// paperclip-server on port 3100. If server→agent push is ever needed, add a
+// targeted ingress rule scoped to the paperclip-server endpoint selector.
+export function buildCiliumNetworkPolicyManifest(input: BuildCiliumNetworkPolicyInput): Record<string, unknown> {
+  const egress: Record<string, unknown>[] = [];
+
+  egress.push({
+    toEndpoints: [
+      { matchLabels: { "k8s:io.kubernetes.pod.namespace": "kube-system", "k8s-app": "kube-dns" } },
+    ],
+    toPorts: [
+      {
+        ports: [
+          { port: "53", protocol: "UDP" },
+          { port: "53", protocol: "TCP" },
+        ],
+        rules: { dns: [{ matchPattern: "*" }] },
+      },
+    ],
+  });
+
+  if (input.egressAllowFqdns.length > 0) {
+    egress.push({
+      toFQDNs: input.egressAllowFqdns.map((fqdn) => ({ matchName: fqdn })),
+      toPorts: [{ ports: [{ port: "443", protocol: "TCP" }] }],
+    });
+  }
+
+  egress.push({
+    toEndpoints: [
+      {
+        matchLabels: {
+          "k8s:io.kubernetes.pod.namespace": input.paperclipServerNamespace,
+          app: "paperclip-server",
+        },
+      },
+    ],
+    toPorts: [{ ports: [{ port: "3100", protocol: "TCP" }] }],
+  });
+
+  if (input.egressAllowCidrs.length > 0) {
+    egress.push({
+      toCIDRSet: input.egressAllowCidrs.map((cidr) => ({ cidr })),
+      toPorts: [{ ports: [{ port: "443", protocol: "TCP" }] }],
+    });
+  }
+
+  return {
+    apiVersion: "cilium.io/v2",
+    kind: "CiliumNetworkPolicy",
+    metadata: {
+      name: "paperclip-egress-fqdn",
+      namespace: input.namespace,
+      labels: { "paperclip.io/managed-by": "paperclip-k8s-plugin" },
+    },
+    spec: {
+      endpointSelector: { matchLabels: { "paperclip.io/role": "agent" } },
+      egress,
+    },
+  };
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/image-allowlist.ts b/packages/plugins/sandbox-providers/kubernetes/src/image-allowlist.ts
new file mode 100644
index 00000000..46cdaf61
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/image-allowlist.ts
@@ -0,0 +1,59 @@
+/**
+ * Glob matching for image references.
+ * - `*` matches any sequence of characters EXCEPT `/` (so a wildcard doesn't span path segments)
+ * - `?` matches exactly one character (excluding `/`)
+ */
+export function globMatch(pattern: string, value: string): boolean {
+  const re = new RegExp(
+    "^" +
+      pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]") +
+      "$",
+  );
+  return re.test(value);
+}
+
+export interface ResolveImageInput {
+  imageOverride?: string | null;
+}
+
+export interface ResolveImageDefaults {
+  runtimeImage: string;
+}
+
+export interface ResolveImageConfig {
+  imageAllowList: string[];
+  imageRegistry?: string;
+}
+
+export function resolveImage(
+  target: ResolveImageInput,
+  defaults: ResolveImageDefaults,
+  config: ResolveImageConfig,
+): string {
+  if (target.imageOverride) {
+    if (!config.imageAllowList.some((p) => globMatch(p, target.imageOverride!))) {
+      throw new Error(`Image override "${target.imageOverride}" is not in allowlist`);
+    }
+    return target.imageOverride;
+  }
+  if (config.imageRegistry) {
+    return rewriteRegistry(defaults.runtimeImage, config.imageRegistry);
+  }
+  return defaults.runtimeImage;
+}
+
+function rewriteRegistry(image: string, registry: string): string {
+  // image is like "ghcr.io/paperclipai/agent-runtime-claude:v1"
+  // we want to replace the first two path segments (host + org) with `registry`
+  const cleanRegistry = registry.replace(/\/+$/, "");
+  const colonIdx = image.lastIndexOf(":");
+  const tag = colonIdx >= 0 ? image.slice(colonIdx) : "";
+  const path = colonIdx >= 0 ? image.slice(0, colonIdx) : image;
+  const segments = path.split("/");
+  // Strip the host+org (first two segments), keep the image name
+  const imageName = segments.slice(2).join("/") || segments[segments.length - 1];
+  return `${cleanRegistry}/${imageName}${tag}`;
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/index.ts b/packages/plugins/sandbox-providers/kubernetes/src/index.ts
new file mode 100644
index 00000000..f7ce1cc1
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/index.ts
@@ -0,0 +1,2 @@
+export { default as manifest } from "./manifest.js";
+export { default as plugin } from "./plugin.js";
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/job-orchestrator.ts b/packages/plugins/sandbox-providers/kubernetes/src/job-orchestrator.ts
new file mode 100644
index 00000000..498302e4
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/job-orchestrator.ts
@@ -0,0 +1,129 @@
+import type { KubeClients } from "./kube-client.js";
+import type { SandboxOrchestrator, SandboxStatus } from "./sandbox-orchestrator.js";
+
+export class JobTimeoutError extends Error {
+  constructor(namespace: string, name: string, timeoutMs: number) {
+    super(`Job ${namespace}/${name} did not complete within ${timeoutMs}ms`);
+    this.name = "JobTimeoutError";
+  }
+}
+
+export async function createJob(
+  clients: KubeClients,
+  namespace: string,
+  manifest: Record<string, unknown>,
+): Promise<{ uid: string }> {
+  const result = await clients.batch.createNamespacedJob({ namespace, body: manifest as never });
+  const uid = (result as { metadata?: { uid?: string } }).metadata?.uid;
+  if (!uid) throw new Error("Job created without a UID");
+  return { uid };
+}
+
+export type JobStatus = SandboxStatus;
+
+export async function getJobStatus(
+  clients: KubeClients,
+  namespace: string,
+  name: string,
+): Promise<JobStatus> {
+  const result = await clients.batch.readNamespacedJobStatus({ namespace, name });
+  const body = (result as Record<string, unknown>) ?? {};
+  const status = (body.status as Record<string, unknown>) ?? {};
+  const active = (status.active as number) ?? 0;
+  const succeeded = (status.succeeded as number) ?? 0;
+  const failed = (status.failed as number) ?? 0;
+  const conditions = (status.conditions as { type: string; status: string; reason?: string; message?: string }[]) ?? [];
+  const completed = conditions.find((c) => c.type === "Complete" && c.status === "True");
+  const failedCond = conditions.find((c) => c.type === "Failed" && c.status === "True");
+  if (failedCond || failed > 0) {
+    return { phase: "Failed", complete: false, active, succeeded, failed, reason: failedCond?.reason, message: failedCond?.message };
+  }
+  if (completed || succeeded > 0) {
+    return { phase: "Succeeded", complete: true, active, succeeded, failed };
+  }
+  if (active > 0) {
+    return { phase: "Running", complete: false, active, succeeded, failed };
+  }
+  return { phase: "Pending", complete: false, active, succeeded, failed };
+}
+
+export async function findPodForJob(
+  clients: KubeClients,
+  namespace: string,
+  jobName: string,
+): Promise<string | null> {
+  const result = await clients.core.listNamespacedPod({
+    namespace,
+    labelSelector: `job-name=${jobName}`,
+  });
+  const items = ((result as { items?: { metadata?: { name?: string }; status?: { phase?: string } }[] }).items) ?? [];
+  const running = items.find((p) => p.status?.phase === "Running");
+  return (running ?? items[0])?.metadata?.name ?? null;
+}
+
+export async function streamPodLogs(
+  clients: KubeClients,
+  namespace: string,
+  podName: string,
+  onChunk: (stream: "stdout" | "stderr", text: string) => Promise<void>,
+): Promise<void> {
+  // V1 limitation: the Pod log API returns the container's combined log stream.
+  // Kubernetes does not preserve stdout/stderr channel separation after the
+  // container runtime writes logs, so the Job backend reports combined logs on
+  // stdout. The sandbox-cr backend uses exec and keeps streams separate.
+  const result = await clients.core.readNamespacedPodLog({ namespace, name: podName });
+  const text = readPodLogText(result);
+  if (text.length > 0) await onChunk("stdout", text);
+}
+
+function readPodLogText(result: unknown): string {
+  if (typeof result === "string") return result;
+  const body = (result as { body?: unknown })?.body;
+  return typeof body === "string" ? body : "";
+}
+
+export async function deleteJob(
+  clients: KubeClients,
+  namespace: string,
+  name: string,
+): Promise<void> {
+  await clients.batch.deleteNamespacedJob({
+    namespace,
+    name,
+    propagationPolicy: "Foreground",
+  });
+}
+
+export async function waitForJobCompletion(
+  clients: KubeClients,
+  namespace: string,
+  name: string,
+  opts: { timeoutMs: number; pollMs?: number } = { timeoutMs: 120_000, pollMs: 2000 },
+): Promise<JobStatus> {
+  const deadline = Date.now() + opts.timeoutMs;
+  const pollMs = opts.pollMs ?? 2000;
+  while (Date.now() < deadline) {
+    const status = await getJobStatus(clients, namespace, name);
+    if (status.phase === "Succeeded" || status.phase === "Failed") return status;
+    await sleep(pollMs);
+  }
+  throw new JobTimeoutError(namespace, name, opts.timeoutMs);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Job-backed conformance to SandboxOrchestrator. Plugin.ts imports THIS value
+ * (the swap point) — to use a different backend, swap this import for another
+ * module exposing a SandboxOrchestrator-shaped default export.
+ */
+export const jobOrchestrator: SandboxOrchestrator = {
+  claim: createJob,
+  getStatus: getJobStatus,
+  findPod: findPodForJob,
+  streamLogs: streamPodLogs,
+  release: deleteJob,
+  waitForCompletion: waitForJobCompletion,
+};
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/kube-client.ts b/packages/plugins/sandbox-providers/kubernetes/src/kube-client.ts
new file mode 100644
index 00000000..d66a9fc4
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/kube-client.ts
@@ -0,0 +1,44 @@
+import {
+  KubeConfig,
+  CoreV1Api,
+  BatchV1Api,
+  CustomObjectsApi,
+  NetworkingV1Api,
+  RbacAuthorizationV1Api,
+} from "@kubernetes/client-node";
+
+export interface CreateKubeConfigInput {
+  inCluster?: boolean;
+  kubeconfig?: string;
+}
+
+export function createKubeConfig(input: CreateKubeConfigInput): KubeConfig {
+  const kc = new KubeConfig();
+  if (input.inCluster) {
+    kc.loadFromCluster();
+    return kc;
+  }
+  if (input.kubeconfig && input.kubeconfig.trim().length > 0) {
+    kc.loadFromString(input.kubeconfig);
+    return kc;
+  }
+  throw new Error("createKubeConfig requires either inCluster=true or a kubeconfig string");
+}
+
+export interface KubeClients {
+  core: CoreV1Api;
+  batch: BatchV1Api;
+  custom: CustomObjectsApi;
+  networking: NetworkingV1Api;
+  rbac: RbacAuthorizationV1Api;
+}
+
+export function makeKubeClients(kc: KubeConfig): KubeClients {
+  return {
+    core: kc.makeApiClient(CoreV1Api),
+    batch: kc.makeApiClient(BatchV1Api),
+    custom: kc.makeApiClient(CustomObjectsApi),
+    networking: kc.makeApiClient(NetworkingV1Api),
+    rbac: kc.makeApiClient(RbacAuthorizationV1Api),
+  };
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/manifest.ts b/packages/plugins/sandbox-providers/kubernetes/src/manifest.ts
new file mode 100644
index 00000000..6b52476b
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/manifest.ts
@@ -0,0 +1,135 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+const PLUGIN_ID = "paperclip.kubernetes-sandbox-provider";
+const PLUGIN_VERSION = "0.1.0-alpha.1";
+
+const manifest: PaperclipPluginManifestV1 = {
+  id: PLUGIN_ID,
+  apiVersion: 1,
+  version: PLUGIN_VERSION,
+  displayName: "Kubernetes Sandbox (alpha)",
+  description:
+    "Built on kubernetes-sigs/agent-sandbox (v1alpha1). ALPHA — expect breaking changes as the upstream CRD evolves. Falls back to stable batch/v1 Job mode for clusters without agent-sandbox installed. First-party Paperclip sandbox-provider plugin for Kubernetes.",
+  author: "Paperclip",
+  categories: ["automation"],
+  capabilities: ["environment.drivers.register"],
+  entrypoints: {
+    worker: "./dist/worker.js",
+  },
+  environmentDrivers: [
+    {
+      driverKey: "kubernetes",
+      kind: "sandbox_provider",
+      displayName: "Kubernetes",
+      description:
+        "Dispatches agent runs in per-tenant Kubernetes namespaces. Default backend (sandbox-cr, alpha) uses kubernetes-sigs/agent-sandbox for multi-command exec; fallback backend (job) uses stable batch/v1 Job for clusters without agent-sandbox installed.",
+      configSchema: {
+        type: "object",
+        properties: {
+          inCluster: {
+            type: "boolean",
+            description:
+              "When true, the plugin uses the in-pod ServiceAccount credentials. Requires paperclip-server to be running inside the target cluster.",
+          },
+          kubeconfig: {
+            type: "string",
+            format: "secret-ref",
+            pattern: "\\S",
+            description:
+              "Inline kubeconfig YAML. Paste a kubeconfig or an existing Paperclip secret reference; pasted values are stored as company secrets.",
+          },
+          namespacePrefix: {
+            type: "string",
+            maxLength: 20,
+            description: "Prefix for the per-company tenant namespace (default: paperclip-).",
+          },
+          paperclipServerNamespace: {
+            type: "string",
+            maxLength: 63,
+            pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+            description:
+              "Namespace where paperclip-server pods run. Used by generated egress policies so agent pods can call back to the server (default: paperclip).",
+          },
+          companySlug: {
+            type: "string",
+            maxLength: 43,
+            description: "Override the auto-derived company slug used in the tenant namespace name.",
+          },
+          imageRegistry: {
+            type: "string",
+            description: "Override the default registry for agent runtime images (default: ghcr.io/paperclipai).",
+          },
+          imageAllowList: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Glob patterns of allowed `target.imageOverride` values. Empty list = no override permitted.",
+          },
+          imagePullSecrets: {
+            type: "array",
+            items: { type: "string" },
+            description: "Names of pre-created Docker image pull secrets in the tenant namespace.",
+          },
+          egressAllowFqdns: {
+            type: "array",
+            items: { type: "string" },
+            description:
+              "Additional FQDNs to allow egress to from agent pods. Adapter-default FQDNs (e.g. api.anthropic.com) are added automatically.",
+          },
+          egressAllowCidrs: {
+            type: "array",
+            items: { type: "string" },
+            description: "Additional CIDRs to allow HTTPS egress to from agent pods. CIDR egress is restricted to TCP port 443.",
+          },
+          egressMode: {
+            type: "string",
+            enum: ["standard", "cilium"],
+            description:
+              "Network policy mode. `standard` uses NetworkPolicy and allows public HTTPS when adapter FQDNs are configured; `cilium` enables exact FQDN egress filtering via CiliumNetworkPolicy.",
+          },
+          runtimeClassName: {
+            type: "string",
+            description:
+              "Optional RuntimeClass for pod isolation (e.g. `kata-fc` for Firecracker-backed microVMs). Cluster must have the RuntimeClass installed.",
+          },
+          serviceAccountAnnotations: {
+            type: "object",
+            additionalProperties: { type: "string" },
+            description:
+              "Annotations applied to the per-tenant ServiceAccount (e.g. `eks.amazonaws.com/role-arn` for IRSA).",
+          },
+          jobTtlSecondsAfterFinished: {
+            type: "integer",
+            minimum: 0,
+            description: "Seconds after a Job completes before it is garbage-collected (default: 900).",
+          },
+          podActivityDeadlineSec: {
+            type: "integer",
+            minimum: 1,
+            description: "Hard ceiling on a single run's wall-clock time (default: 3600).",
+          },
+          adapterType: {
+            type: "string",
+            description:
+              "The adapter type that Jobs in this environment will run (e.g. `claude_local`, `codex_local`). Defaults to `claude_local`. Each environment is bound to one adapter; create multiple environments for different adapters.",
+          },
+          backend: {
+            type: "string",
+            enum: ["sandbox-cr", "job"],
+            description:
+              "sandbox-cr (default, alpha — requires kubernetes-sigs/agent-sandbox installed) | job (stable fallback — batch/v1 Job, one-shot entrypoint, no multi-command exec)",
+          },
+        },
+        anyOf: [
+          {
+            properties: { inCluster: { const: true } },
+            required: ["inCluster"],
+          },
+          { required: ["kubeconfig"] },
+        ],
+      },
+    },
+  ],
+};
+
+export default manifest;
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/network-policy.ts b/packages/plugins/sandbox-providers/kubernetes/src/network-policy.ts
new file mode 100644
index 00000000..65e07f3e
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/network-policy.ts
@@ -0,0 +1,102 @@
+export interface BuildNetworkPolicyInput {
+  namespace: string;
+  paperclipServerNamespace: string;
+  egressAllowFqdns: string[];
+  egressAllowCidrs: string[];
+}
+
+const PUBLIC_IPV4_EXCEPTIONS = [
+  "10.0.0.0/8",
+  "100.64.0.0/10",
+  "127.0.0.0/8",
+  "169.254.0.0/16",
+  "172.16.0.0/12",
+  "192.168.0.0/16",
+];
+
+// Design note: the deny-all baseline blocks all ingress to agent pods.
+// Paperclip-server does NOT push to agent pods — the agent shim makes
+// outbound calls to paperclip-server via the egress allow-list (port 3100).
+// This pull/callback model means no ingress rule is needed. If a future
+// feature requires server→agent push (e.g. forced shutdown, live exec),
+// add a targeted ingress rule here scoped to the paperclip-server pod
+// selector.
+//
+// Standard Kubernetes NetworkPolicy cannot express FQDN allow-lists. When
+// adapter defaults require FQDN egress, keep runs functional by allowing public
+// IPv4 HTTPS while excluding private/link-local ranges. Operators who need
+// exact FQDN enforcement should use egressMode="cilium".
+export function buildNetworkPolicyManifests(input: BuildNetworkPolicyInput): Record<string, unknown>[] {
+  const fqdnsRequirePublicHttpsFallback = input.egressAllowFqdns.length > 0;
+  const denyAll = {
+    apiVersion: "networking.k8s.io/v1",
+    kind: "NetworkPolicy",
+    metadata: {
+      name: "paperclip-deny-all",
+      namespace: input.namespace,
+      labels: { "paperclip.io/managed-by": "paperclip-k8s-plugin" },
+    },
+    spec: {
+      podSelector: {},
+      policyTypes: ["Ingress", "Egress"],
+    },
+  };
+
+  const egressAllow: Record<string, unknown> = {
+    apiVersion: "networking.k8s.io/v1",
+    kind: "NetworkPolicy",
+    metadata: {
+      name: "paperclip-egress-allow",
+      namespace: input.namespace,
+      labels: { "paperclip.io/managed-by": "paperclip-k8s-plugin" },
+    },
+    spec: {
+      podSelector: { matchLabels: { "paperclip.io/role": "agent" } },
+      policyTypes: ["Egress"],
+      egress: [
+        {
+          to: [
+            {
+              namespaceSelector: { matchLabels: { "kubernetes.io/metadata.name": "kube-system" } },
+              podSelector: { matchLabels: { "k8s-app": "kube-dns" } },
+            },
+          ],
+          ports: [
+            { protocol: "UDP", port: 53 },
+            { protocol: "TCP", port: 53 },
+          ],
+        },
+        {
+          to: [
+            {
+              namespaceSelector: { matchLabels: { "kubernetes.io/metadata.name": input.paperclipServerNamespace } },
+              podSelector: { matchLabels: { app: "paperclip-server" } },
+            },
+          ],
+          ports: [{ protocol: "TCP", port: 3100 }],
+        },
+        ...(fqdnsRequirePublicHttpsFallback
+          ? [
+              {
+                to: [
+                  {
+                    ipBlock: {
+                      cidr: "0.0.0.0/0",
+                      except: PUBLIC_IPV4_EXCEPTIONS,
+                    },
+                  },
+                ],
+                ports: [{ protocol: "TCP", port: 443 }],
+              },
+            ]
+          : []),
+        ...input.egressAllowCidrs.map((cidr) => ({
+          to: [{ ipBlock: { cidr } }],
+          ports: [{ protocol: "TCP", port: 443 }],
+        })),
+      ],
+    },
+  };
+
+  return [denyAll, egressAllow];
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/plugin.ts b/packages/plugins/sandbox-providers/kubernetes/src/plugin.ts
new file mode 100644
index 00000000..03950e95
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/plugin.ts
@@ -0,0 +1,700 @@
+import { randomBytes } from "node:crypto";
+import { definePlugin } from "@paperclipai/plugin-sdk";
+import type {
+  PluginEnvironmentAcquireLeaseParams,
+  PluginEnvironmentExecuteParams,
+  PluginEnvironmentExecuteResult,
+  PluginEnvironmentLease,
+  PluginEnvironmentProbeParams,
+  PluginEnvironmentProbeResult,
+  PluginEnvironmentRealizeWorkspaceParams,
+  PluginEnvironmentRealizeWorkspaceResult,
+  PluginEnvironmentReleaseLeaseParams,
+  PluginEnvironmentValidateConfigParams,
+  PluginEnvironmentValidationResult,
+} from "@paperclipai/plugin-sdk";
+import {
+  kubernetesProviderConfigSchema,
+  type KubernetesProviderConfig,
+  type KubernetesLeaseMetadata,
+} from "./types.js";
+import { createKubeConfig, makeKubeClients } from "./kube-client.js";
+import { getAdapterDefaults } from "./adapter-defaults.js";
+import { resolveImage } from "./image-allowlist.js";
+import { buildJobManifest } from "./pod-spec-builder.js";
+import { buildSandboxCrManifest } from "./sandbox-cr-builder.js";
+import { ensureTenant } from "./tenant-orchestrator.js";
+import { createPerRunSecret } from "./secret-manager.js";
+import { FastUploadInterceptor } from "./upload-interceptor.js";
+import { jobOrchestrator, JobTimeoutError } from "./job-orchestrator.js";
+import {
+  sandboxCrOrchestrator,
+  SandboxCrTimeoutError,
+} from "./sandbox-cr-orchestrator.js";
+import { execInPod } from "./pod-exec.js";
+import { shellQuoteArg } from "./shell-utils.js";
+import {
+  deriveCompanySlug,
+  deriveNamespaceName,
+  newRunUlidDns,
+  paperclipLabels,
+} from "./utils.js";
+
+// Name of the ServiceAccount created inside each tenant namespace by ensureTenant.
+const TENANT_SERVICE_ACCOUNT = "paperclip-tenant-sa";
+
+// Resource quota defaults applied to every tenant namespace (M4b; tunable via
+// config in a future milestone).
+const DEFAULT_RESOURCE_QUOTA = {
+  pods: "20",
+  requestsCpu: "10",
+  requestsMemory: "20Gi",
+  limitsCpu: "20",
+  limitsMemory: "40Gi",
+};
+
+const uploadInterceptorsByLease = new Map<string, FastUploadInterceptor>();
+
+function getOrCreateUploadInterceptor(leaseId: string): FastUploadInterceptor {
+  let interceptor = uploadInterceptorsByLease.get(leaseId);
+  if (!interceptor) {
+    interceptor = new FastUploadInterceptor();
+    uploadInterceptorsByLease.set(leaseId, interceptor);
+  }
+  return interceptor;
+}
+
+function extractShellScript(
+  params: Pick<PluginEnvironmentExecuteParams, "args" | "command">,
+): string | null {
+  const command = typeof params.command === "string" ? params.command.trim() : "";
+  const args = Array.isArray(params.args) ? params.args : [];
+  const isShell = command === "sh" || command === "bash" || command.endsWith("/sh") || command.endsWith("/bash");
+  if (isShell && args[0] === "-c" && typeof args[1] === "string") {
+    return args[1];
+  }
+  return null;
+}
+
+function deriveTenantNamespace(config: KubernetesProviderConfig, companyId: string): string {
+  // TODO: future versions could thread companyName through AcquireLeaseParams
+  // to get a friendlier slug (e.g. "acme-corp") instead of the UUID-derived one.
+  const slug = config.companySlug ?? deriveCompanySlug(companyId);
+  return deriveNamespaceName(config.namespacePrefix, slug);
+}
+
+/**
+ * Reads adapter env keys (e.g. ANTHROPIC_API_KEY) from the current process
+ * environment. The plugin worker runs inside paperclip-server's pod, which has
+ * these vars injected at deploy time.
+ *
+ * M4b approach: env vars sourced from process.env at acquire time.
+ * TODO: future milestones may thread per-run secrets differently (e.g. via
+ * a secret store reference on the environment config).
+ */
+export function extractAdapterEnvFromProcess(
+  envKeys: string[],
+  warn: (message: string) => void = console.warn,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  const missing: string[] = [];
+  for (const k of envKeys) {
+    const v = process.env[k];
+    if (v !== undefined) {
+      out[k] = v;
+    } else {
+      missing.push(k);
+    }
+  }
+  if (missing.length > 0) {
+    warn(
+      `[plugin-kubernetes] adapter environment variable(s) missing from plugin worker process: ${missing.join(", ")}. Agent pods may fail provider authentication unless these keys are optional for the selected adapter.`,
+    );
+  }
+  return out;
+}
+
+export function buildSandboxExecCommand(
+  params: Pick<PluginEnvironmentExecuteParams, "args" | "command">,
+): string[] {
+  const command = typeof params.command === "string" ? params.command.trim() : "";
+  const args = Array.isArray(params.args) ? params.args : [];
+
+  if (command.length > 0 && args.length > 0) {
+    return [command, ...args];
+  }
+  if (command.length > 0) {
+    return ["/bin/sh", "-lc", command];
+  }
+  if (args.length > 0) {
+    return ["/bin/sh", "-lc", args.map(shellQuoteArg).join(" ")];
+  }
+  return ["/bin/sh", "-l"];
+}
+
+export function deriveUploadTargetDir(targetPath: string): string {
+  const slashIndex = targetPath.lastIndexOf("/");
+  return slashIndex >= 0 ? targetPath.slice(0, slashIndex) || "/" : ".";
+}
+
+export function buildSandboxExecShellCommand(
+  params: Pick<PluginEnvironmentExecuteParams, "args" | "command">,
+): string {
+  if (typeof params.command === "string" && params.command.trim().length > 0) {
+    return params.command;
+  }
+
+  return params.args?.map(shellQuoteArg).join(" ") ?? "";
+}
+
+function generateBootstrapToken(): string {
+  // TODO: paperclip-server's actual callback auth scheme is separate and is
+  // out of M4b scope. This per-run random token is stored in the per-run
+  // Secret and consumed by paperclip-agent-shim for initial registration.
+  return randomBytes(32).toString("hex");
+}
+
+const plugin = definePlugin({
+  async setup(ctx) {
+    ctx.logger.info("Kubernetes sandbox provider plugin ready");
+  },
+
+  async onHealth() {
+    return { status: "ok", message: "Kubernetes sandbox provider plugin healthy" };
+  },
+
+  async onEnvironmentValidateConfig(
+    params: PluginEnvironmentValidateConfigParams,
+  ): Promise<PluginEnvironmentValidationResult> {
+    const parsed = kubernetesProviderConfigSchema.safeParse(params.config);
+    if (!parsed.success) {
+      return {
+        ok: false,
+        errors: parsed.error.issues.map((i) => i.message),
+      };
+    }
+    const warnings: string[] = [];
+    const cfg = parsed.data;
+    const adapterDefaults = getAdapterDefaults(cfg.adapterType);
+    const totalFqdns = [...adapterDefaults.allowFqdns, ...cfg.egressAllowFqdns];
+    if (cfg.egressMode === "standard" && totalFqdns.length > 0) {
+      warnings.push(
+        `egressMode=standard cannot enforce FQDN-based egress rules for ${totalFqdns.join(", ")}. Agent pods will get public IPv4 HTTPS egress with private/link-local ranges excluded. Switch egressMode to "cilium" for exact FQDN enforcement.`,
+      );
+    }
+    return { ok: true, normalizedConfig: cfg as Record<string, unknown>, warnings: warnings.length > 0 ? warnings : undefined };
+  },
+
+  async onEnvironmentProbe(
+    params: PluginEnvironmentProbeParams,
+  ): Promise<PluginEnvironmentProbeResult> {
+    const parsed = kubernetesProviderConfigSchema.safeParse(params.config);
+    if (!parsed.success) {
+      return {
+        ok: false,
+        summary: "Invalid Kubernetes provider configuration.",
+        metadata: {
+          errors: parsed.error.issues.map((i) => i.message),
+        },
+      };
+    }
+    const config = parsed.data;
+    const namespace = deriveTenantNamespace(config, params.companyId);
+
+    try {
+      const kc = createKubeConfig({
+        inCluster: config.inCluster,
+        kubeconfig: config.kubeconfig,
+      });
+      const clients = makeKubeClients(kc);
+      // Reachability check: list pods in the tenant namespace. If the namespace
+      // doesn't exist yet this will throw a 404 which we treat as "reachable
+      // but namespace not provisioned" — still a successful probe.
+      try {
+        await clients.core.listNamespacedPod({ namespace });
+      } catch (err) {
+        const code = (err as { code?: number; statusCode?: number }).code
+          ?? (err as { code?: number; statusCode?: number }).statusCode;
+        if (code !== 404) throw err;
+        // 404 means namespace doesn't exist yet — cluster is reachable.
+      }
+      return {
+        ok: true,
+        summary: `Kubernetes cluster reachable. Tenant namespace: ${namespace}.`,
+        metadata: { namespace, provider: "kubernetes" },
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        summary: "Kubernetes cluster probe failed.",
+        metadata: {
+          namespace,
+          provider: "kubernetes",
+          error: err instanceof Error ? err.message : String(err),
+        },
+      };
+    }
+  },
+
+  async onEnvironmentAcquireLease(
+    params: PluginEnvironmentAcquireLeaseParams,
+  ): Promise<PluginEnvironmentLease> {
+    const config = kubernetesProviderConfigSchema.parse(params.config);
+    const namespace = deriveTenantNamespace(config, params.companyId);
+
+    // Emit a runtime warning if FQDNs are configured but egressMode=standard
+    // cannot enforce them. Mirrors the validateConfig warning so operators see
+    // it in paperclip-server logs even if they missed the validation step.
+    const adapterDefaultsForWarn = getAdapterDefaults(config.adapterType);
+    const totalFqdnsForWarn = [...adapterDefaultsForWarn.allowFqdns, ...config.egressAllowFqdns];
+    if (config.egressMode === "standard" && totalFqdnsForWarn.length > 0) {
+      // The SDK does not currently thread ctx.logger into environment hooks.
+      // Keep this explicit so operators still see the standard-mode egress
+      // trade-off in raw worker logs.
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[plugin-kubernetes] egressMode=standard cannot enforce FQDN-based egress rules for ${totalFqdnsForWarn.join(", ")}. Agent pods will get public IPv4 HTTPS egress with private/link-local ranges excluded. Switch egressMode to "cilium" for exact FQDN enforcement.`,
+      );
+    }
+
+    const kc = createKubeConfig({
+      inCluster: config.inCluster,
+      kubeconfig: config.kubeconfig,
+    });
+    const clients = makeKubeClients(kc);
+
+    // Ensure the tenant namespace and all its RBAC / network policy resources
+    // exist before we try to create the Job.
+    const adapterDefaults = getAdapterDefaults(config.adapterType);
+
+    await ensureTenant(clients, {
+      namespace,
+      companyId: params.companyId,
+      paperclipServerNamespace: config.paperclipServerNamespace,
+      serviceAccountAnnotations: config.serviceAccountAnnotations,
+      egressMode: config.egressMode,
+      egressAllowFqdns: [...adapterDefaults.allowFqdns, ...config.egressAllowFqdns],
+      egressAllowCidrs: config.egressAllowCidrs,
+      resourceQuota: DEFAULT_RESOURCE_QUOTA,
+    });
+
+    const jobName = `pc-${newRunUlidDns()}`;
+    const secretName = `${jobName}-env`;
+
+    // TODO: use params.runId as stand-in for agentId in labels; future
+    // versions will have a dedicated agentId on AcquireLeaseParams.
+    const labels = paperclipLabels({
+      runId: params.runId,
+      agentId: params.runId,
+      companyId: params.companyId,
+      adapterType: config.adapterType,
+    });
+
+    const image = resolveImage(
+      { imageOverride: null },
+      adapterDefaults,
+      { imageAllowList: config.imageAllowList, imageRegistry: config.imageRegistry },
+    );
+
+    // Pick the orchestrator and build the appropriate manifest based on backend.
+    const isSandboxCrBackend = config.backend === "sandbox-cr";
+    const orchestrator = isSandboxCrBackend ? sandboxCrOrchestrator : jobOrchestrator;
+
+    const manifest = isSandboxCrBackend
+      ? buildSandboxCrManifest({
+          namespace,
+          sandboxName: jobName,
+          adapterType: config.adapterType,
+          image,
+          envSecretName: secretName,
+          serviceAccountName: TENANT_SERVICE_ACCOUNT,
+          labels,
+          resources: config.defaultResources ?? {},
+          runtimeClassName: config.runtimeClassName,
+          imagePullSecrets: config.imagePullSecrets,
+        })
+      : buildJobManifest({
+          namespace,
+          jobName,
+          adapterType: config.adapterType,
+          image,
+          envSecretName: secretName,
+          serviceAccountName: TENANT_SERVICE_ACCOUNT,
+          labels,
+          resources: config.defaultResources ?? {},
+          runtimeClassName: config.runtimeClassName,
+          activeDeadlineSec: config.podActivityDeadlineSec,
+          ttlSecondsAfterFinished: config.jobTtlSecondsAfterFinished,
+          imagePullSecrets: config.imagePullSecrets,
+        });
+
+    const { uid: ownerUid } = await orchestrator.claim(clients, namespace, manifest);
+
+    // M4b: adapter env vars are sourced from the plugin worker's own process
+    // environment (paperclip-server pod has them injected at deploy time).
+    const adapterEnv = extractAdapterEnvFromProcess(adapterDefaults.envKeys);
+    const bootstrapToken = generateBootstrapToken();
+
+    // Secret ownerRef: for job backend, the Job owns the Secret (cascade delete).
+    // For sandbox-cr backend, the Sandbox CR owns the Secret.
+    // NOTE: For sandbox-cr, if the Secret outlives the Sandbox due to a cluster
+    // quirk, the release() call will still clean it up via namespace GC or
+    // explicit delete in a future milestone.
+    try {
+      await createPerRunSecret(clients, {
+        namespace,
+        secretName,
+        runId: params.runId,
+        ownerKind: isSandboxCrBackend ? "Sandbox" : "Job",
+        ownerApiVersion: isSandboxCrBackend ? "agents.x-k8s.io/v1alpha1" : "batch/v1",
+        ownerName: jobName,
+        ownerUid,
+        bootstrapToken,
+        adapterEnv,
+      });
+
+      const podName = await orchestrator.findPod(clients, namespace, jobName);
+
+      const leaseMetadata: KubernetesLeaseMetadata = {
+        namespace,
+        jobName,
+        podName,
+        secretName,
+        phase: "Pending",
+        backend: config.backend,
+      };
+
+      return {
+        providerLeaseId: jobName,
+        metadata: leaseMetadata as unknown as Record<string, unknown>,
+      };
+    } catch (err) {
+      try {
+        await orchestrator.release(clients, namespace, jobName);
+      } catch (cleanupErr) {
+        throw new Error(
+          `Kubernetes lease setup failed and cleanup also failed: ${cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)}`,
+          { cause: err },
+        );
+      }
+      throw err;
+    }
+  },
+
+  async onEnvironmentRealizeWorkspace(
+    params: PluginEnvironmentRealizeWorkspaceParams,
+  ): Promise<PluginEnvironmentRealizeWorkspaceResult> {
+    // The agent pod already has /workspace mounted as an emptyDir at pod
+    // scheduling time (see pod-spec-builder). Nothing to provision here —
+    // we just hand back the cwd. Honor a caller-supplied remotePath if set.
+    const cwd =
+      params.workspace.remotePath && params.workspace.remotePath.trim().length > 0
+        ? params.workspace.remotePath.trim()
+        : "/workspace";
+    return {
+      cwd,
+      metadata: {
+        provider: "kubernetes",
+        remoteCwd: cwd,
+      },
+    };
+  },
+
+  async onEnvironmentReleaseLease(
+    params: PluginEnvironmentReleaseLeaseParams,
+  ): Promise<void> {
+    if (!params.providerLeaseId) return;
+    const config = kubernetesProviderConfigSchema.parse(params.config);
+    const namespace =
+      typeof params.leaseMetadata?.namespace === "string"
+        ? params.leaseMetadata.namespace
+        : deriveTenantNamespace(config, params.companyId);
+
+    const kc = createKubeConfig({
+      inCluster: config.inCluster,
+      kubeconfig: config.kubeconfig,
+    });
+    const clients = makeKubeClients(kc);
+
+    const leaseBackend =
+      typeof params.leaseMetadata?.backend === "string"
+        ? (params.leaseMetadata.backend as "sandbox-cr" | "job")
+        : config.backend;
+    const releaseOrchestrator =
+      leaseBackend === "sandbox-cr" ? sandboxCrOrchestrator : jobOrchestrator;
+
+    uploadInterceptorsByLease.delete(params.providerLeaseId);
+
+    try {
+      await releaseOrchestrator.release(clients, namespace, params.providerLeaseId);
+    } catch (err) {
+      // If the resource is already gone (404), that's fine.
+      const code = (err as { code?: number; statusCode?: number }).code
+        ?? (err as { code?: number; statusCode?: number }).statusCode;
+      if (code !== 404) throw err;
+    }
+  },
+
+  async onEnvironmentExecute(
+    params: PluginEnvironmentExecuteParams,
+  ): Promise<PluginEnvironmentExecuteResult> {
+    const { lease, timeoutMs } = params;
+
+    if (!lease.providerLeaseId) {
+      return {
+        exitCode: 1,
+        timedOut: false,
+        stdout: "",
+        stderr: "No provider lease ID available for execution.",
+      };
+    }
+
+    const config = kubernetesProviderConfigSchema.parse(params.config);
+    const namespace =
+      typeof lease.metadata?.namespace === "string"
+        ? lease.metadata.namespace
+        : deriveTenantNamespace(config, params.companyId);
+
+    // Determine which backend this lease was created with.
+    const leaseBackend =
+      typeof lease.metadata?.backend === "string"
+        ? (lease.metadata.backend as "sandbox-cr" | "job")
+        : config.backend;
+
+    const kc = createKubeConfig({
+      inCluster: config.inCluster,
+      kubeconfig: config.kubeconfig,
+    });
+    const clients = makeKubeClients(kc);
+
+    const effectiveTimeoutMs =
+      typeof timeoutMs === "number" && timeoutMs > 0
+        ? timeoutMs
+        : config.podActivityDeadlineSec * 1000;
+
+    if (leaseBackend === "sandbox-cr") {
+      // ── Sandbox-CR backend ──────────────────────────────────────────────────
+      // 1. Ensure the Sandbox pod is Ready (wait if needed).
+      // 2. Exec the command into the running pod.
+      // 3. Return exec result directly (no log scraping needed).
+      const executeStartedAt = Date.now();
+
+      let podName =
+        typeof lease.metadata?.podName === "string" && lease.metadata.podName
+          ? lease.metadata.podName
+          : null;
+
+      // Wait for pod Ready if we don't have a pod name yet (or as a health check).
+      try {
+        await sandboxCrOrchestrator.waitForCompletion(
+          clients,
+          namespace,
+          lease.providerLeaseId,
+          { timeoutMs: effectiveTimeoutMs, pollMs: 2000 },
+        );
+      } catch (err) {
+        if (err instanceof SandboxCrTimeoutError) {
+          return {
+            exitCode: null,
+            timedOut: true,
+            stdout: "",
+            stderr: `Sandbox pod did not become Ready within ${effectiveTimeoutMs}ms`,
+            metadata: {
+              provider: "kubernetes",
+              backend: "sandbox-cr",
+              namespace,
+              sandboxName: lease.providerLeaseId,
+            },
+          };
+        }
+        throw err;
+      }
+
+      // Resolve pod name (may now be populated in Sandbox status).
+      if (!podName) {
+        podName = await sandboxCrOrchestrator.findPod(
+          clients,
+          namespace,
+          lease.providerLeaseId,
+        );
+      }
+
+      if (!podName) {
+        return {
+          exitCode: 1,
+          timedOut: false,
+          stdout: "",
+          stderr: "Sandbox pod is Ready but podName could not be resolved.",
+          metadata: {
+            provider: "kubernetes",
+            backend: "sandbox-cr",
+            namespace,
+            sandboxName: lease.providerLeaseId,
+          },
+        };
+      }
+
+      const remainingTimeoutMs = Math.max(1, effectiveTimeoutMs - (Date.now() - executeStartedAt));
+
+      const shellScript = extractShellScript(params);
+      if (shellScript) {
+        const decision = getOrCreateUploadInterceptor(lease.providerLeaseId).decide(shellScript);
+        if (decision.action === "ack") {
+          return {
+            exitCode: 0,
+            timedOut: false,
+            stdout: "",
+            stderr: "",
+            metadata: {
+              provider: "kubernetes",
+              backend: "sandbox-cr",
+              namespace,
+              sandboxName: lease.providerLeaseId,
+              podName,
+              fastUpload: "ack",
+            },
+          };
+        }
+        if (decision.action === "flush") {
+          const base64Body = decision.flush.payload.toString("base64");
+          const dir = deriveUploadTargetDir(decision.flush.targetPath);
+          const script =
+            `mkdir -p ${shellQuoteArg(dir)} && ` +
+            `base64 -d > ${shellQuoteArg(decision.flush.targetPath)}`;
+          const flushResult = await execInPod(
+            kc,
+            namespace,
+            podName,
+            "agent",
+            ["/bin/sh", "-c", script],
+            base64Body,
+            remainingTimeoutMs,
+          );
+          return {
+            exitCode: flushResult.exitCode,
+            timedOut: flushResult.timedOut,
+            stdout: flushResult.stdout,
+            stderr: flushResult.stderr,
+            metadata: {
+              provider: "kubernetes",
+              backend: "sandbox-cr",
+              namespace,
+              sandboxName: lease.providerLeaseId,
+              podName,
+              fastUpload: "flush",
+              uploadedBytes: decision.flush.payload.length,
+            },
+          };
+        }
+        if (decision.action === "error") {
+          return {
+            exitCode: 1,
+            timedOut: false,
+            stdout: "",
+            stderr: decision.message,
+            metadata: {
+              provider: "kubernetes",
+              backend: "sandbox-cr",
+              namespace,
+              sandboxName: lease.providerLeaseId,
+              podName,
+              fastUpload: "error",
+            },
+          };
+        }
+      }
+
+      const execCommand = buildSandboxExecCommand(params);
+      const execResult = await execInPod(
+        kc,
+        namespace,
+        podName,
+        "agent",
+        execCommand,
+        typeof params.stdin === "string" ? params.stdin : undefined,
+        remainingTimeoutMs,
+      );
+
+      return {
+        exitCode: execResult.exitCode,
+        timedOut: execResult.timedOut,
+        stdout: execResult.stdout,
+        stderr: execResult.stderr,
+        metadata: {
+          provider: "kubernetes",
+          backend: "sandbox-cr",
+          namespace,
+          sandboxName: lease.providerLeaseId,
+          podName,
+        },
+      };
+    } else {
+      // ── Job backend (legacy / stable fallback) ──────────────────────────────
+      // The container entrypoint is baked into the Job spec (Tini + paperclip-agent-shim).
+      // We do NOT re-exec command/args — instead we wait for the Job to finish
+      // and collect its logs.
+      //
+      // params.command / params.args / params.stdin are intentionally ignored.
+
+      let status;
+      let timedOut = false;
+      try {
+        status = await jobOrchestrator.waitForCompletion(
+          clients,
+          namespace,
+          lease.providerLeaseId,
+          { timeoutMs: effectiveTimeoutMs, pollMs: 2000 },
+        );
+      } catch (err) {
+        if (err instanceof JobTimeoutError) {
+          timedOut = true;
+          status = null;
+        } else {
+          throw err;
+        }
+      }
+
+      // Collect logs from the pod.
+      const podName =
+        typeof lease.metadata?.podName === "string"
+          ? lease.metadata.podName
+          : await jobOrchestrator.findPod(
+              clients,
+              namespace,
+              lease.providerLeaseId,
+            );
+
+      const stdoutChunks: string[] = [];
+      const stderrChunks: string[] = [];
+
+      if (podName) {
+        await jobOrchestrator.streamLogs(
+          clients,
+          namespace,
+          podName,
+          async (stream, text) => {
+            if (stream === "stdout") stdoutChunks.push(text);
+            else stderrChunks.push(text);
+          },
+        );
+      }
+
+      return {
+        exitCode: timedOut ? null : status?.phase === "Succeeded" ? 0 : 1,
+        timedOut,
+        stdout: stdoutChunks.join(""),
+        stderr: stderrChunks.join(""),
+        metadata: {
+          provider: "kubernetes",
+          backend: "job",
+          namespace,
+          jobName: lease.providerLeaseId,
+          podName: podName ?? null,
+          phase: status?.phase ?? null,
+        },
+      };
+    }
+  },
+});
+
+export default plugin;
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/pod-exec.ts b/packages/plugins/sandbox-providers/kubernetes/src/pod-exec.ts
new file mode 100644
index 00000000..41904008
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/pod-exec.ts
@@ -0,0 +1,186 @@
+/**
+ * Exec a command inside a running pod container using the Kubernetes exec API.
+ *
+ * Uses @kubernetes/client-node's Exec class, which opens a WebSocket to the
+ * kube-apiserver and streams stdout/stderr. The statusCallback receives a V1Status
+ * with status="Success" or status="Failure" + details.causes[{reason:"ExitCode"}].
+ *
+ * NOTE: tty=false so stdout and stderr arrive on separate channels. If tty=true
+ * were used, they would be merged onto stdout and the exit code would not be
+ * reliable from the status callback on older cluster versions.
+ */
+
+import { Exec } from "@kubernetes/client-node";
+import { PassThrough } from "node:stream";
+import type { KubeConfig } from "@kubernetes/client-node";
+import { shellQuoteArg } from "./shell-utils.js";
+
+type WebSocketLike = {
+  close(): void;
+  on(event: "close", listener: (code: number, reason: Buffer) => void): void;
+  on(event: "error", listener: (err: Error) => void): void;
+};
+
+export interface ExecInPodResult {
+  exitCode: number;
+  timedOut: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+export async function execInPod(
+  kc: KubeConfig,
+  namespace: string,
+  podName: string,
+  containerName: string,
+  command: string[],
+  stdin?: string | Buffer,
+  timeoutMs?: number,
+): Promise<ExecInPodResult> {
+  const exec = new Exec(kc);
+  const stdoutStream = new PassThrough();
+  const stderrStream = new PassThrough();
+
+  const stdinPayload: Buffer | null =
+    Buffer.isBuffer(stdin) ? stdin
+    : typeof stdin === "string" && stdin.length > 0 ? Buffer.from(stdin, "utf-8")
+    : null;
+  const stdinStream: PassThrough | null = stdinPayload ? new PassThrough() : null;
+  const effectiveCommand = stdinPayload
+    ? ["/bin/sh", "-c", `head -c ${stdinPayload.length} | ${command.map(shellQuoteArg).join(" ")}`]
+    : command;
+
+  let stdoutData = "";
+  let stderrData = "";
+
+  stdoutStream.on("data", (chunk: Buffer) => {
+    stdoutData += chunk.toString("utf-8");
+  });
+  stderrStream.on("data", (chunk: Buffer) => {
+    stderrData += chunk.toString("utf-8");
+  });
+  stdoutStream.on("error", () => {});
+  stderrStream.on("error", () => {});
+
+  return await new Promise<ExecInPodResult>(
+    (resolve, reject) => {
+      let ws: WebSocketLike | null = null;
+      let settled = false;
+      let pendingResult: Omit<ExecInPodResult, "stdout" | "stderr"> | null = null;
+      let stdoutEnded = false;
+      let stderrEnded = false;
+      const timeout =
+        typeof timeoutMs === "number" && timeoutMs > 0
+          ? setTimeout(() => {
+              finishWithTransportFailure(`Kubernetes exec timed out after ${timeoutMs}ms`, true);
+            }, timeoutMs)
+          : null;
+
+      const finish = (result: ExecInPodResult) => {
+        if (settled) return;
+        settled = true;
+        if (timeout) clearTimeout(timeout);
+        try {
+          ws?.close();
+        } catch {
+          // Ignore best-effort close failures.
+        }
+        resolve(result);
+      };
+      const finishWithTransportFailure = (message: string, timedOut = false) => {
+        const separator = stderrData.length > 0 && !stderrData.endsWith("\n") ? "\n" : "";
+        finish({
+          exitCode: 1,
+          timedOut,
+          stdout: stdoutData,
+          stderr: `${stderrData}${separator}${message}`,
+        });
+      };
+      const tryFinish = () => {
+        if (settled || !pendingResult || !stdoutEnded || !stderrEnded) return;
+        finish({
+          ...pendingResult,
+          stdout: stdoutData,
+          stderr: stderrData,
+        });
+      };
+      const endOutputStreams = () => {
+        if (!stdoutStream.writableEnded) stdoutStream.end();
+        if (!stderrStream.writableEnded) stderrStream.end();
+      };
+
+      stdoutStream.on("end", () => {
+        stdoutEnded = true;
+        tryFinish();
+      });
+      stderrStream.on("end", () => {
+        stderrEnded = true;
+        tryFinish();
+      });
+
+      const websocketPromise = exec
+        .exec(
+          namespace,
+          podName,
+          containerName,
+          effectiveCommand,
+          stdoutStream,
+          stderrStream,
+          stdinStream,
+          false, // tty=false: keep stdout/stderr on separate channels
+          (status) => {
+            // status.status is "Success" | "Failure"
+            if (status.status === "Success") {
+              pendingResult = { exitCode: 0, timedOut: false };
+              endOutputStreams();
+              tryFinish();
+              return;
+            }
+            // On failure, the exit code surfaces via
+            // status.details?.causes[].{reason:"ExitCode", message:"<N>"}
+            const causes = status.details?.causes ?? [];
+            const exitCodeCause = causes.find(
+              (c: { reason?: string; message?: string }) =>
+                c.reason === "ExitCode",
+            );
+            const exitCode = exitCodeCause?.message
+              ? Number(exitCodeCause.message)
+              : 1;
+            pendingResult = { exitCode, timedOut: false };
+            endOutputStreams();
+            tryFinish();
+          },
+        );
+
+      websocketPromise
+        .then((webSocket) => {
+          ws = webSocket as WebSocketLike;
+          if (settled) {
+            try {
+              ws.close();
+            } catch {
+              // Ignore best-effort close failures.
+            }
+            return;
+          }
+          if (stdinStream && stdinPayload) {
+            stdinStream.end(stdinPayload);
+          }
+          ws.on("close", (code: number, reason: Buffer) => {
+            if (settled || pendingResult) return;
+            const reasonText = reason.length > 0 ? `: ${reason.toString("utf-8")}` : "";
+            finishWithTransportFailure(`Kubernetes exec websocket closed before status frame (${code})${reasonText}`);
+          });
+          ws.on("error", (err: Error) => {
+            if (settled || pendingResult) return;
+            finishWithTransportFailure(`Kubernetes exec websocket failed before status frame: ${err.message}`);
+          });
+        })
+        .catch((err) => {
+          if (settled) return;
+          if (timeout) clearTimeout(timeout);
+          reject(err);
+        });
+    },
+  );
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/pod-spec-builder.ts b/packages/plugins/sandbox-providers/kubernetes/src/pod-spec-builder.ts
new file mode 100644
index 00000000..128a671c
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/pod-spec-builder.ts
@@ -0,0 +1,94 @@
+export interface BuildJobManifestInput {
+  namespace: string;
+  jobName: string;
+  adapterType: string;
+  image: string;
+  envSecretName: string;
+  serviceAccountName: string;
+  labels: Record<string, string>;
+  resources: {
+    requests?: { cpu?: string; memory?: string };
+    limits?: { cpu?: string; memory?: string };
+  };
+  runtimeClassName?: string;
+  activeDeadlineSec: number;
+  ttlSecondsAfterFinished: number;
+  imagePullSecrets?: string[];
+}
+
+export function buildJobManifest(input: BuildJobManifestInput): Record<string, unknown> {
+  const podLabels = {
+    ...input.labels,
+    "paperclip.io/role": "agent",
+  };
+  return {
+    apiVersion: "batch/v1",
+    kind: "Job",
+    metadata: {
+      name: input.jobName,
+      namespace: input.namespace,
+      labels: { ...input.labels },
+    },
+    spec: {
+      backoffLimit: 0,
+      ttlSecondsAfterFinished: input.ttlSecondsAfterFinished,
+      activeDeadlineSeconds: input.activeDeadlineSec,
+      template: {
+        metadata: { labels: podLabels },
+        spec: {
+          serviceAccountName: input.serviceAccountName,
+          // Agent containers call back to paperclip-server via HTTPS egress;
+          // they never call the Kubernetes API, so mounting an SA token is
+          // unnecessary attack surface.
+          automountServiceAccountToken: false,
+          restartPolicy: "Never",
+          ...(input.runtimeClassName ? { runtimeClassName: input.runtimeClassName } : {}),
+          ...(input.imagePullSecrets && input.imagePullSecrets.length > 0
+            ? { imagePullSecrets: input.imagePullSecrets.map((name) => ({ name })) }
+            : {}),
+          securityContext: {
+            runAsNonRoot: true,
+            runAsUser: 1000,
+            runAsGroup: 1000,
+            fsGroup: 1000,
+            fsGroupChangePolicy: "OnRootMismatch",
+            seccompProfile: { type: "RuntimeDefault" },
+          },
+          containers: [
+            {
+              name: "agent",
+              image: input.image,
+              imagePullPolicy: "IfNotPresent",
+              command: ["/usr/bin/tini", "--", "/usr/local/bin/paperclip-agent-shim"],
+              envFrom: [{ secretRef: { name: input.envSecretName } }],
+              securityContext: {
+                runAsNonRoot: true,
+                runAsUser: 1000,
+                runAsGroup: 1000,
+                readOnlyRootFilesystem: true,
+                allowPrivilegeEscalation: false,
+                capabilities: { drop: ["ALL"] },
+              },
+              resources: {
+                requests: input.resources.requests ?? { cpu: "250m", memory: "512Mi" },
+                limits: input.resources.limits ?? { cpu: "2", memory: "4Gi" },
+              },
+              volumeMounts: [
+                { name: "workspace", mountPath: "/workspace" },
+                { name: "home", mountPath: "/home/paperclip" },
+                { name: "cache", mountPath: "/home/paperclip/.cache" },
+                { name: "tmp", mountPath: "/tmp" },
+              ],
+            },
+          ],
+          volumes: [
+            { name: "workspace", emptyDir: { sizeLimit: "8Gi" } },
+            { name: "home", emptyDir: { sizeLimit: "1Gi" } },
+            { name: "cache", emptyDir: { sizeLimit: "1Gi" } },
+            { name: "tmp", emptyDir: { sizeLimit: "2Gi" } },
+          ],
+        },
+      },
+    },
+  };
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/sandbox-cr-builder.ts b/packages/plugins/sandbox-providers/kubernetes/src/sandbox-cr-builder.ts
new file mode 100644
index 00000000..fb3d7e6c
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/sandbox-cr-builder.ts
@@ -0,0 +1,136 @@
+/**
+ * Builds a kubernetes-sigs/agent-sandbox Sandbox CR manifest.
+ *
+ * The Sandbox CR creates a long-lived pod (sleep infinity entrypoint) into
+ * which paperclip-server can exec arbitrary commands. This solves the
+ * architectural mismatch with the batch/v1 Job backend, which only supports
+ * a single one-shot entrypoint — not the multi-command adapter-install pattern
+ * used by paperclip-server.
+ *
+ * Security baseline is identical to buildJobManifest (pod-spec-builder.ts):
+ * non-root, drop ALL caps, read-only rootFS, Tini PID 1, seccomp
+ * RuntimeDefault, fsGroupChangePolicy OnRootMismatch, automountSAToken=false.
+ *
+ * NOTE: paperclip-server runs OUTSIDE the cluster, so we cannot set ownerReferences
+ * on the Sandbox CR (the owner would need to be an in-cluster resource). The
+ * release path is explicit delete via sandboxCrOrchestrator.release().
+ */
+
+export interface BuildSandboxCrManifestInput {
+  namespace: string;
+  sandboxName: string;
+  adapterType: string;
+  image: string;
+  envSecretName: string;
+  serviceAccountName: string;
+  labels: Record<string, string>;
+  resources: {
+    requests?: { cpu?: string; memory?: string };
+    limits?: { cpu?: string; memory?: string };
+  };
+  runtimeClassName?: string;
+  imagePullSecrets?: string[];
+}
+
+export function buildSandboxCrManifest(
+  input: BuildSandboxCrManifestInput,
+): Record<string, unknown> {
+  const podLabels: Record<string, string> = {
+    ...input.labels,
+    "paperclip.io/role": "agent",
+  };
+  return {
+    apiVersion: "agents.x-k8s.io/v1alpha1",
+    kind: "Sandbox",
+    metadata: {
+      name: input.sandboxName,
+      namespace: input.namespace,
+      labels: { ...input.labels },
+      // No ownerReferences: paperclip-server is out-of-cluster. Release is
+      // explicit delete.
+    },
+    spec: {
+      podTemplate: {
+        metadata: {
+          labels: podLabels,
+        },
+        spec: {
+          serviceAccountName: input.serviceAccountName,
+          // Agent containers call back to paperclip-server via HTTPS egress;
+          // they never call the Kubernetes API, so mounting an SA token is
+          // unnecessary attack surface.
+          automountServiceAccountToken: false,
+          // Sandbox controller requires restartPolicy: Always so the pod
+          // stays running between exec calls.
+          restartPolicy: "Always",
+          ...(input.runtimeClassName
+            ? { runtimeClassName: input.runtimeClassName }
+            : {}),
+          ...(input.imagePullSecrets && input.imagePullSecrets.length > 0
+            ? {
+                imagePullSecrets: input.imagePullSecrets.map((name) => ({
+                  name,
+                })),
+              }
+            : {}),
+          securityContext: {
+            runAsNonRoot: true,
+            runAsUser: 1000,
+            runAsGroup: 1000,
+            fsGroup: 1000,
+            fsGroupChangePolicy: "OnRootMismatch",
+            seccompProfile: { type: "RuntimeDefault" },
+          },
+          containers: [
+            {
+              name: "agent",
+              image: input.image,
+              imagePullPolicy: "IfNotPresent",
+              // sleep infinity keeps the pod running; paperclip-server execs
+              // commands into it via Kubernetes exec API. Tini as PID 1 for
+              // proper signal forwarding and zombie reaping.
+              command: [
+                "/usr/bin/tini",
+                "--",
+                "/bin/sh",
+                "-c",
+                "sleep infinity",
+              ],
+              envFrom: [{ secretRef: { name: input.envSecretName } }],
+              securityContext: {
+                runAsNonRoot: true,
+                runAsUser: 1000,
+                runAsGroup: 1000,
+                readOnlyRootFilesystem: true,
+                allowPrivilegeEscalation: false,
+                capabilities: { drop: ["ALL"] },
+              },
+              resources: {
+                requests: input.resources.requests ?? {
+                  cpu: "250m",
+                  memory: "512Mi",
+                },
+                limits: input.resources.limits ?? {
+                  cpu: "2",
+                  memory: "4Gi",
+                },
+              },
+              volumeMounts: [
+                { name: "workspace", mountPath: "/workspace" },
+                { name: "home", mountPath: "/home/paperclip" },
+                { name: "cache", mountPath: "/home/paperclip/.cache" },
+                { name: "tmp", mountPath: "/tmp" },
+              ],
+            },
+          ],
+          volumes: [
+            { name: "workspace", emptyDir: { sizeLimit: "8Gi" } },
+            { name: "home", emptyDir: { sizeLimit: "1Gi" } },
+            { name: "cache", emptyDir: { sizeLimit: "1Gi" } },
+            { name: "tmp", emptyDir: { sizeLimit: "2Gi" } },
+          ],
+        },
+      },
+    },
+  };
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/sandbox-cr-orchestrator.ts b/packages/plugins/sandbox-providers/kubernetes/src/sandbox-cr-orchestrator.ts
new file mode 100644
index 00000000..b77a097b
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/sandbox-cr-orchestrator.ts
@@ -0,0 +1,291 @@
+/**
+ * SandboxOrchestrator implementation backed by the kubernetes-sigs/agent-sandbox
+ * Sandbox CRD (agents.x-k8s.io/v1alpha1).
+ *
+ * The Sandbox CR creates a long-lived pod that paperclip-server can exec into
+ * for multi-command adapter-install workflows — the key architectural win over
+ * the batch/v1 Job backend.
+ *
+ * Key semantic differences from jobOrchestrator:
+ * - claim() creates a Sandbox CR via CustomObjectsApi instead of a batch Job
+ * - getStatus() maps Sandbox phase (Pending|Ready|Terminating|Failed) to SandboxStatus
+ * - findPod() reads status.podName from the Sandbox CR (falls back to label query)
+ * - waitForCompletion() means "wait until pod is Ready to exec" NOT "wait until
+ *   workload finishes". The Sandbox pod runs sleep infinity; execution completion
+ *   is tracked by the individual execInPod() calls.
+ * - release() deletes the Sandbox CR with Foreground propagation (controller
+ *   tears down the underlying pod).
+ *
+ * NOTE: streamLogs() is provided for interface conformance but is limited —
+ * the sleep-infinity pod has no meaningful stdout. Callers in execute mode
+ * should use execInPod() and capture its stdout/stderr directly.
+ */
+
+import type { KubeClients } from "./kube-client.js";
+import type { SandboxOrchestrator, SandboxStatus } from "./sandbox-orchestrator.js";
+
+const SANDBOX_GROUP = "agents.x-k8s.io";
+const SANDBOX_VERSION = "v1alpha1";
+const SANDBOX_PLURAL = "sandboxes";
+
+export class SandboxCrTimeoutError extends Error {
+  constructor(namespace: string, name: string, timeoutMs: number) {
+    super(
+      `Sandbox ${namespace}/${name} did not reach Ready phase within ${timeoutMs}ms`,
+    );
+    this.name = "SandboxCrTimeoutError";
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Map a Sandbox CR status.phase value to our SandboxStatus shape.
+ * Sandbox phases: Pending | Ready | Terminating | Failed
+ */
+function mapSandboxPhase(
+  cr: Record<string, unknown>,
+): SandboxStatus {
+  const status = (cr.status as Record<string, unknown>) ?? {};
+  const phase = (status.phase as string) ?? "Pending";
+
+  switch (phase) {
+    case "Ready":
+      return {
+        phase: "Running", // SandboxStatus.phase uses Job semantics; "Running" = active pod
+        complete: false,
+        active: 1,
+        succeeded: 0,
+        failed: 0,
+      };
+    case "Terminating":
+      return {
+        phase: "Running",
+        complete: false,
+        active: 0,
+        succeeded: 0,
+        failed: 0,
+        reason: "Terminating",
+      };
+    case "Failed": {
+      const conditions = (status.conditions as { type?: string; reason?: string; message?: string }[]) ?? [];
+      const failedCond = conditions.find((c) => c.type === "Failed");
+      return {
+        phase: "Failed",
+        complete: false,
+        active: 0,
+        succeeded: 0,
+        failed: 1,
+        reason: failedCond?.reason,
+        message: failedCond?.message,
+      };
+    }
+    default:
+      // "Pending" or unknown
+      return {
+        phase: "Pending",
+        complete: false,
+        active: 0,
+        succeeded: 0,
+        failed: 0,
+      };
+  }
+}
+
+export async function createSandboxCr(
+  clients: KubeClients,
+  namespace: string,
+  manifest: Record<string, unknown>,
+): Promise<{ uid: string }> {
+  const result = await clients.custom.createNamespacedCustomObject({
+    group: SANDBOX_GROUP,
+    version: SANDBOX_VERSION,
+    namespace,
+    plural: SANDBOX_PLURAL,
+    body: manifest,
+  });
+  const uid = (result as { metadata?: { uid?: string } }).metadata?.uid;
+  if (!uid) throw new Error("Sandbox CR created without a UID");
+  return { uid };
+}
+
+export async function getSandboxCrStatus(
+  clients: KubeClients,
+  namespace: string,
+  name: string,
+): Promise<SandboxStatus> {
+  const result = await clients.custom.getNamespacedCustomObject({
+    group: SANDBOX_GROUP,
+    version: SANDBOX_VERSION,
+    namespace,
+    plural: SANDBOX_PLURAL,
+    name,
+  });
+  return mapSandboxPhase(result as Record<string, unknown>);
+}
+
+/**
+ * Returns the pod name backing a Sandbox CR.
+ * Primary: read status.podName from the CR (set by the controller once ready).
+ * Fallback: list pods in the namespace filtered by the paperclip.io/managed-by
+ * label and the sandbox name label set on the pod template.
+ */
+export async function findPodForSandbox(
+  clients: KubeClients,
+  namespace: string,
+  name: string,
+): Promise<string | null> {
+  // Primary: read status.podName from the Sandbox CR
+  const cr = await clients.custom.getNamespacedCustomObject({
+    group: SANDBOX_GROUP,
+    version: SANDBOX_VERSION,
+    namespace,
+    plural: SANDBOX_PLURAL,
+    name,
+  }) as Record<string, unknown>;
+
+  const status = (cr.status as Record<string, unknown>) ?? {};
+  const podName = status.podName as string | undefined;
+  if (podName && podName.trim().length > 0) {
+    return podName;
+  }
+
+  // Fallback: list pods with sandbox-name label (sandbox controller typically
+  // labels pods with the sandbox name)
+  const result = await clients.core.listNamespacedPod({
+    namespace,
+    labelSelector: `paperclip.io/managed-by=paperclip-k8s-plugin`,
+  });
+  const items =
+    (
+      (
+        result as {
+          items?: {
+            metadata?: { name?: string; labels?: Record<string, string> };
+            status?: { phase?: string };
+          }[];
+        }
+      ).items
+    ) ?? [];
+
+  // Filter to pods that belong to this sandbox by name prefix or label
+  const matching = items.filter((p) => {
+    const podMeta = p.metadata ?? {};
+    const labels = podMeta.labels ?? {};
+    // The sandbox controller may label pods differently; try matching by name prefix
+    return (
+      podMeta.name?.startsWith(name) ||
+      labels["agents.x-k8s.io/sandbox-name"] === name
+    );
+  });
+
+  const running = matching.find((p) => p.status?.phase === "Running");
+  return (running ?? matching[0])?.metadata?.name ?? null;
+}
+
+export async function streamSandboxLogs(
+  clients: KubeClients,
+  namespace: string,
+  podName: string,
+  onChunk: (stream: "stdout" | "stderr", text: string) => Promise<void>,
+): Promise<void> {
+  // V1 limitation: the Pod log API returns the container's combined log stream. The
+  // sleep-infinity pod will have minimal output; this is provided for interface
+  // conformance. For actual command output, use execInPod() directly.
+  const result = await clients.core.readNamespacedPodLog({
+    namespace,
+    name: podName,
+  });
+  const text =
+    typeof result === "string"
+      ? result
+      : typeof (result as { body?: unknown })?.body === "string"
+        ? (result as { body: string }).body
+        : "";
+  if (text.length > 0) await onChunk("stdout", text);
+}
+
+export async function deleteSandboxCr(
+  clients: KubeClients,
+  namespace: string,
+  name: string,
+): Promise<void> {
+  await clients.custom.deleteNamespacedCustomObject({
+    group: SANDBOX_GROUP,
+    version: SANDBOX_VERSION,
+    namespace,
+    plural: SANDBOX_PLURAL,
+    name,
+    propagationPolicy: "Foreground",
+  });
+}
+
+/**
+ * Wait until the Sandbox CR's pod reaches Ready phase (i.e., the pod is up and
+ * exec-able). This is NOT waiting for a workload to finish — the Sandbox pod
+ * runs sleep infinity indefinitely. Execution completion is tracked by the
+ * individual execInPod() calls.
+ *
+ * Throws SandboxCrTimeoutError if Ready is not reached within timeoutMs.
+ * Throws if the Sandbox transitions to Failed.
+ */
+export async function waitForSandboxReady(
+  clients: KubeClients,
+  namespace: string,
+  name: string,
+  opts: { timeoutMs: number; pollMs?: number } = {
+    timeoutMs: 120_000,
+    pollMs: 2000,
+  },
+): Promise<SandboxStatus> {
+  const deadline = Date.now() + opts.timeoutMs;
+  const pollMs = opts.pollMs ?? 2000;
+
+  while (Date.now() < deadline) {
+    const cr = await clients.custom.getNamespacedCustomObject({
+      group: SANDBOX_GROUP,
+      version: SANDBOX_VERSION,
+      namespace,
+      plural: SANDBOX_PLURAL,
+      name,
+    }) as Record<string, unknown>;
+
+    const status = (cr.status as Record<string, unknown>) ?? {};
+    const phase = (status.phase as string) ?? "Pending";
+
+    if (phase === "Ready") {
+      return mapSandboxPhase(cr);
+    }
+    if (phase === "Failed") {
+      const mapped = mapSandboxPhase(cr);
+      throw new Error(
+        `Sandbox ${namespace}/${name} failed: ${mapped.reason ?? "unknown reason"} — ${mapped.message ?? ""}`,
+      );
+    }
+    if (phase === "Terminating") {
+      throw new Error(`Sandbox ${namespace}/${name} is terminating before it became ready`);
+    }
+    // Pending or unknown — keep polling
+    await sleep(pollMs);
+  }
+
+  throw new SandboxCrTimeoutError(namespace, name, opts.timeoutMs);
+}
+
+/**
+ * Sandbox CR-backed conformance to SandboxOrchestrator.
+ *
+ * waitForCompletion semantics change: for this backend, "completion" means
+ * "pod is up and Ready to exec into" — NOT "workload finished". The actual
+ * command execution and its completion is handled by execInPod().
+ */
+export const sandboxCrOrchestrator: SandboxOrchestrator = {
+  claim: createSandboxCr,
+  getStatus: getSandboxCrStatus,
+  findPod: findPodForSandbox,
+  streamLogs: streamSandboxLogs,
+  release: deleteSandboxCr,
+  waitForCompletion: waitForSandboxReady,
+};
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/sandbox-orchestrator.ts b/packages/plugins/sandbox-providers/kubernetes/src/sandbox-orchestrator.ts
new file mode 100644
index 00000000..db4dbb72
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/sandbox-orchestrator.ts
@@ -0,0 +1,68 @@
+import type { KubeClients } from "./kube-client.js";
+
+export interface SandboxStatus {
+  phase: "Pending" | "Running" | "Succeeded" | "Failed";
+  complete: boolean;
+  active: number;
+  succeeded: number;
+  failed: number;
+  reason?: string;
+  message?: string;
+}
+
+/**
+ * Abstract interface over a sandbox runtime backend. The current implementation
+ * is Job-backed (job-orchestrator.ts). Future backends slot in by exporting an
+ * object conforming to this shape — e.g. a Kata-FC warm-pool backend that
+ * additionally implements the optional pause/resume slots, or a CRD-backed
+ * backend on kubernetes-sigs/agent-sandbox once it reaches Beta.
+ */
+export interface SandboxOrchestrator {
+  /** Provision the sandbox. Returns the runtime's stable UID. */
+  claim(
+    clients: KubeClients,
+    namespace: string,
+    manifest: Record<string, unknown>,
+  ): Promise<{ uid: string }>;
+
+  /** Read current lifecycle phase. */
+  getStatus(
+    clients: KubeClients,
+    namespace: string,
+    name: string,
+  ): Promise<SandboxStatus>;
+
+  /** Locate the pod backing this sandbox (or null if none exists yet). */
+  findPod(
+    clients: KubeClients,
+    namespace: string,
+    name: string,
+  ): Promise<string | null>;
+
+  /** Read logs from the sandbox's pod. V1: post-completion read. */
+  streamLogs(
+    clients: KubeClients,
+    namespace: string,
+    podName: string,
+    onChunk: (stream: "stdout" | "stderr", text: string) => Promise<void>,
+  ): Promise<void>;
+
+  /** Tear down the sandbox. Implementations MUST cascade-delete child resources. */
+  release(clients: KubeClients, namespace: string, name: string): Promise<void>;
+
+  /** Block until phase is Succeeded or Failed, or throw on timeout. */
+  waitForCompletion(
+    clients: KubeClients,
+    namespace: string,
+    name: string,
+    opts: { timeoutMs: number; pollMs?: number },
+  ): Promise<SandboxStatus>;
+
+  // Optional warm-pool / Kata-FC extension slots. Job-backed implementation
+  // does not provide these; runtimes that do (e.g. Kata-FC microVM pause)
+  // implement them and acquire the warm-pool capability.
+  // TODO: requires custom in-cluster controller for k8s — kubelet does not
+  // expose pause/resume at the pod level. Add when warm-pool design lands.
+  pause?(clients: KubeClients, namespace: string, name: string): Promise<void>;
+  resume?(clients: KubeClients, namespace: string, name: string): Promise<void>;
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/secret-manager.ts b/packages/plugins/sandbox-providers/kubernetes/src/secret-manager.ts
new file mode 100644
index 00000000..cbf2150b
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/secret-manager.ts
@@ -0,0 +1,52 @@
+import type { KubeClients } from "./kube-client.js";
+
+export interface CreatePerRunSecretInput {
+  namespace: string;
+  secretName: string;
+  runId: string;
+  ownerKind: string;
+  ownerApiVersion: string;
+  ownerName: string;
+  ownerUid: string;
+  bootstrapToken: string;
+  adapterEnv: Record<string, string>;
+}
+
+export async function createPerRunSecret(clients: KubeClients, input: CreatePerRunSecretInput): Promise<void> {
+  if (!input.ownerUid) {
+    throw new Error("createPerRunSecret requires a non-empty ownerUid");
+  }
+  if ("BOOTSTRAP_TOKEN" in input.adapterEnv) {
+    throw new Error("adapterEnv must not contain BOOTSTRAP_TOKEN (reserved key)");
+  }
+  await clients.core.createNamespacedSecret({
+    namespace: input.namespace,
+    body: {
+      apiVersion: "v1",
+      kind: "Secret",
+      type: "Opaque",
+      metadata: {
+        name: input.secretName,
+        namespace: input.namespace,
+        labels: {
+          "paperclip.io/run-id": input.runId,
+          "paperclip.io/managed-by": "paperclip-k8s-plugin",
+        },
+        ownerReferences: [
+          {
+            apiVersion: input.ownerApiVersion,
+            kind: input.ownerKind,
+            name: input.ownerName,
+            uid: input.ownerUid,
+            controller: true,
+            blockOwnerDeletion: true,
+          },
+        ],
+      },
+      stringData: {
+        BOOTSTRAP_TOKEN: input.bootstrapToken,
+        ...input.adapterEnv,
+      },
+    },
+  });
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/shell-utils.ts b/packages/plugins/sandbox-providers/kubernetes/src/shell-utils.ts
new file mode 100644
index 00000000..202b3750
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/shell-utils.ts
@@ -0,0 +1,3 @@
+export function shellQuoteArg(arg: string): string {
+  return "'" + arg.replace(/'/g, "'\\''") + "'";
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/tenant-orchestrator.ts b/packages/plugins/sandbox-providers/kubernetes/src/tenant-orchestrator.ts
new file mode 100644
index 00000000..29a3fc40
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/tenant-orchestrator.ts
@@ -0,0 +1,425 @@
+import type { KubeClients } from "./kube-client.js";
+import { buildNetworkPolicyManifests } from "./network-policy.js";
+import { buildCiliumNetworkPolicyManifest } from "./cilium-network-policy.js";
+
+export interface EnsureTenantInput {
+  namespace: string;
+  companyId: string;
+  paperclipServerNamespace: string;
+  serviceAccountAnnotations: Record<string, string>;
+  egressMode: "standard" | "cilium";
+  egressAllowFqdns: string[];
+  egressAllowCidrs: string[];
+  resourceQuota: {
+    pods: string;
+    requestsCpu: string;
+    requestsMemory: string;
+    limitsCpu: string;
+    limitsMemory: string;
+  };
+}
+
+const SERVICE_ACCOUNT_NAME = "paperclip-tenant-sa";
+const ROLE_NAME = "paperclip-tenant-role";
+const ROLE_BINDING_NAME = "paperclip-tenant-rb";
+const RESOURCE_QUOTA_NAME = "paperclip-quota";
+const LIMIT_RANGE_NAME = "paperclip-limits";
+
+/**
+ * Tenant provisioning reconciles the resources this plugin owns. Existing
+ * resources are replaced with the desired manifest so quota, RBAC, service
+ * account annotations, and egress policy changes take effect on the next run.
+ */
+export async function ensureTenant(clients: KubeClients, input: EnsureTenantInput): Promise<void> {
+  await ensureNamespace(clients, input);
+  await ensureServiceAccount(clients, input);
+  await ensureRole(clients, input);
+  await ensureRoleBinding(clients, input);
+  await ensureResourceQuota(clients, input);
+  await ensureLimitRange(clients, input);
+  await ensureNetworkPolicies(clients, input);
+}
+
+async function ensureNamespace(clients: KubeClients, input: EnsureTenantInput): Promise<void> {
+  const manifest = buildNamespaceManifest(input);
+  try {
+    const existing = await clients.core.readNamespace({ name: input.namespace });
+    await clients.core.replaceNamespace({
+      name: input.namespace,
+      body: withResourceVersion(buildNamespaceManifest(input, existing), existing) as never,
+    });
+    return;
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+  try {
+    await clients.core.createNamespace({ body: manifest });
+  } catch (err) {
+    if (!isAlreadyExists(err)) throw err;
+    const existing = await clients.core.readNamespace({ name: input.namespace });
+    await clients.core.replaceNamespace({
+      name: input.namespace,
+      body: withResourceVersion(buildNamespaceManifest(input, existing), existing) as never,
+    });
+  }
+}
+
+function buildNamespaceManifest(input: EnsureTenantInput, existing?: unknown): Record<string, unknown> {
+  const existingLabels = (existing as { metadata?: { labels?: Record<string, string> } })?.metadata?.labels ?? {};
+  return {
+    apiVersion: "v1",
+    kind: "Namespace",
+    metadata: {
+      name: input.namespace,
+      labels: {
+        ...existingLabels,
+        "paperclip.io/company-id": input.companyId,
+        "paperclip.io/managed-by": "paperclip-k8s-plugin",
+        "pod-security.kubernetes.io/enforce": "restricted",
+        "pod-security.kubernetes.io/audit": "restricted",
+        "pod-security.kubernetes.io/warn": "restricted",
+      },
+    },
+  };
+}
+
+async function ensureServiceAccount(clients: KubeClients, input: EnsureTenantInput): Promise<void> {
+  const manifest = {
+    apiVersion: "v1",
+    kind: "ServiceAccount",
+    metadata: {
+      name: SERVICE_ACCOUNT_NAME,
+      namespace: input.namespace,
+      annotations: input.serviceAccountAnnotations,
+      labels: { "paperclip.io/managed-by": "paperclip-k8s-plugin" },
+    },
+  };
+  try {
+    const existing = await clients.core.readNamespacedServiceAccount({ name: SERVICE_ACCOUNT_NAME, namespace: input.namespace });
+    await clients.core.replaceNamespacedServiceAccount({
+      name: SERVICE_ACCOUNT_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+    return;
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+  try {
+    await clients.core.createNamespacedServiceAccount({ namespace: input.namespace, body: manifest });
+  } catch (err) {
+    if (!isAlreadyExists(err)) throw err;
+    const existing = await clients.core.readNamespacedServiceAccount({ name: SERVICE_ACCOUNT_NAME, namespace: input.namespace });
+    await clients.core.replaceNamespacedServiceAccount({
+      name: SERVICE_ACCOUNT_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+  }
+}
+
+async function ensureRole(clients: KubeClients, input: EnsureTenantInput): Promise<void> {
+  const manifest = {
+    apiVersion: "rbac.authorization.k8s.io/v1",
+    kind: "Role",
+    metadata: { name: ROLE_NAME, namespace: input.namespace },
+    rules: [
+      { apiGroups: [""], resources: ["pods/log"], verbs: ["get"] },
+    ],
+  };
+  try {
+    const existing = await clients.rbac.readNamespacedRole({ name: ROLE_NAME, namespace: input.namespace });
+    await clients.rbac.replaceNamespacedRole({
+      name: ROLE_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+    return;
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+  try {
+    await clients.rbac.createNamespacedRole({ namespace: input.namespace, body: manifest });
+  } catch (err) {
+    if (!isAlreadyExists(err)) throw err;
+    const existing = await clients.rbac.readNamespacedRole({ name: ROLE_NAME, namespace: input.namespace });
+    await clients.rbac.replaceNamespacedRole({
+      name: ROLE_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+  }
+}
+
+async function ensureRoleBinding(clients: KubeClients, input: EnsureTenantInput): Promise<void> {
+  const manifest = {
+    apiVersion: "rbac.authorization.k8s.io/v1",
+    kind: "RoleBinding",
+    metadata: { name: ROLE_BINDING_NAME, namespace: input.namespace },
+    roleRef: { apiGroup: "rbac.authorization.k8s.io", kind: "Role", name: ROLE_NAME },
+    subjects: [{ kind: "ServiceAccount", name: SERVICE_ACCOUNT_NAME, namespace: input.namespace }],
+  };
+  try {
+    const existing = await clients.rbac.readNamespacedRoleBinding({ name: ROLE_BINDING_NAME, namespace: input.namespace });
+    await clients.rbac.replaceNamespacedRoleBinding({
+      name: ROLE_BINDING_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+    return;
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+  try {
+    await clients.rbac.createNamespacedRoleBinding({ namespace: input.namespace, body: manifest });
+  } catch (err) {
+    if (!isAlreadyExists(err)) throw err;
+    const existing = await clients.rbac.readNamespacedRoleBinding({ name: ROLE_BINDING_NAME, namespace: input.namespace });
+    await clients.rbac.replaceNamespacedRoleBinding({
+      name: ROLE_BINDING_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+  }
+}
+
+async function ensureResourceQuota(clients: KubeClients, input: EnsureTenantInput): Promise<void> {
+  const manifest = {
+    apiVersion: "v1",
+    kind: "ResourceQuota",
+    metadata: { name: RESOURCE_QUOTA_NAME, namespace: input.namespace },
+    spec: {
+      hard: {
+        pods: input.resourceQuota.pods,
+        "requests.cpu": input.resourceQuota.requestsCpu,
+        "requests.memory": input.resourceQuota.requestsMemory,
+        "limits.cpu": input.resourceQuota.limitsCpu,
+        "limits.memory": input.resourceQuota.limitsMemory,
+      },
+    },
+  };
+  try {
+    const existing = await clients.core.readNamespacedResourceQuota({ name: RESOURCE_QUOTA_NAME, namespace: input.namespace });
+    await clients.core.replaceNamespacedResourceQuota({
+      name: RESOURCE_QUOTA_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+    return;
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+  try {
+    await clients.core.createNamespacedResourceQuota({ namespace: input.namespace, body: manifest });
+  } catch (err) {
+    if (!isAlreadyExists(err)) throw err;
+    const existing = await clients.core.readNamespacedResourceQuota({ name: RESOURCE_QUOTA_NAME, namespace: input.namespace });
+    await clients.core.replaceNamespacedResourceQuota({
+      name: RESOURCE_QUOTA_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+  }
+}
+
+async function ensureLimitRange(clients: KubeClients, input: EnsureTenantInput): Promise<void> {
+  const manifest = {
+    apiVersion: "v1",
+    kind: "LimitRange",
+    metadata: { name: LIMIT_RANGE_NAME, namespace: input.namespace },
+    spec: {
+      limits: [
+        {
+          type: "Container",
+          max: { cpu: "4", memory: "8Gi" },
+          min: { cpu: "100m", memory: "128Mi" },
+          // The k8s client-node type names this `_default` but the actual
+          // Kubernetes API field is `default`. We produce a JSON-shape
+          // manifest so the cast is safe.
+          default: { cpu: "1", memory: "2Gi" },
+          defaultRequest: { cpu: "250m", memory: "512Mi" },
+        },
+      ],
+    },
+  };
+  try {
+    const existing = await clients.core.readNamespacedLimitRange({ name: LIMIT_RANGE_NAME, namespace: input.namespace });
+    await clients.core.replaceNamespacedLimitRange({
+      name: LIMIT_RANGE_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+    return;
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+  try {
+    await clients.core.createNamespacedLimitRange({
+      namespace: input.namespace,
+      body: manifest as never,
+    });
+  } catch (err) {
+    if (!isAlreadyExists(err)) throw err;
+    const existing = await clients.core.readNamespacedLimitRange({ name: LIMIT_RANGE_NAME, namespace: input.namespace });
+    await clients.core.replaceNamespacedLimitRange({
+      name: LIMIT_RANGE_NAME,
+      namespace: input.namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+  }
+}
+
+async function ensureNetworkPolicies(clients: KubeClients, input: EnsureTenantInput): Promise<void> {
+  const [denyAll, egressStd] = buildNetworkPolicyManifests({
+    namespace: input.namespace,
+    paperclipServerNamespace: input.paperclipServerNamespace,
+    egressAllowFqdns: input.egressAllowFqdns,
+    egressAllowCidrs: input.egressAllowCidrs,
+  });
+
+  await ensureNetworkPolicy(clients, input.namespace, denyAll);
+
+  if (input.egressMode === "cilium") {
+    const cnp = buildCiliumNetworkPolicyManifest({
+      namespace: input.namespace,
+      paperclipServerNamespace: input.paperclipServerNamespace,
+      egressAllowFqdns: input.egressAllowFqdns,
+      egressAllowCidrs: input.egressAllowCidrs,
+    });
+    await ensureCiliumNetworkPolicy(clients, input.namespace, cnp);
+    await deleteNetworkPolicyIfExists(clients, input.namespace, "paperclip-egress-allow");
+  } else {
+    await ensureNetworkPolicy(clients, input.namespace, egressStd);
+    await deleteCiliumNetworkPolicyIfExists(clients, input.namespace, "paperclip-egress-fqdn");
+  }
+}
+
+async function ensureNetworkPolicy(
+  clients: KubeClients,
+  namespace: string,
+  manifest: Record<string, unknown>,
+): Promise<void> {
+  const name = (manifest.metadata as { name: string }).name;
+  try {
+    const existing = await clients.networking.readNamespacedNetworkPolicy({ name, namespace });
+    await clients.networking.replaceNamespacedNetworkPolicy({
+      name,
+      namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+    return;
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+  try {
+    await clients.networking.createNamespacedNetworkPolicy({ namespace, body: manifest as never });
+  } catch (err) {
+    if (!isAlreadyExists(err)) throw err;
+    const existing = await clients.networking.readNamespacedNetworkPolicy({ name, namespace });
+    await clients.networking.replaceNamespacedNetworkPolicy({
+      name,
+      namespace,
+      body: withResourceVersion(manifest, existing) as never,
+    });
+  }
+}
+
+async function ensureCiliumNetworkPolicy(
+  clients: KubeClients,
+  namespace: string,
+  manifest: Record<string, unknown>,
+): Promise<void> {
+  const name = (manifest.metadata as { name: string }).name;
+  try {
+    const existing = await clients.custom.getNamespacedCustomObject({
+      group: "cilium.io",
+      version: "v2",
+      namespace,
+      plural: "ciliumnetworkpolicies",
+      name,
+    });
+    await clients.custom.replaceNamespacedCustomObject({
+      group: "cilium.io",
+      version: "v2",
+      namespace,
+      plural: "ciliumnetworkpolicies",
+      name,
+      body: withResourceVersion(manifest, existing),
+    });
+    return;
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+  try {
+    await clients.custom.createNamespacedCustomObject({
+      group: "cilium.io",
+      version: "v2",
+      namespace,
+      plural: "ciliumnetworkpolicies",
+      body: manifest,
+    });
+  } catch (err) {
+    if (!isAlreadyExists(err)) throw err;
+    const existing = await clients.custom.getNamespacedCustomObject({
+      group: "cilium.io",
+      version: "v2",
+      namespace,
+      plural: "ciliumnetworkpolicies",
+      name,
+    });
+    await clients.custom.replaceNamespacedCustomObject({
+      group: "cilium.io",
+      version: "v2",
+      namespace,
+      plural: "ciliumnetworkpolicies",
+      name,
+      body: withResourceVersion(manifest, existing),
+    });
+  }
+}
+
+async function deleteNetworkPolicyIfExists(clients: KubeClients, namespace: string, name: string): Promise<void> {
+  try {
+    await clients.networking.deleteNamespacedNetworkPolicy({ name, namespace });
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+}
+
+async function deleteCiliumNetworkPolicyIfExists(clients: KubeClients, namespace: string, name: string): Promise<void> {
+  try {
+    await clients.custom.deleteNamespacedCustomObject({
+      group: "cilium.io",
+      version: "v2",
+      namespace,
+      plural: "ciliumnetworkpolicies",
+      name,
+    });
+  } catch (err) {
+    if (!isNotFound(err)) throw err;
+  }
+}
+
+function withResourceVersion<T extends Record<string, unknown>>(manifest: T, existing: unknown): T {
+  const resourceVersion = (existing as { metadata?: { resourceVersion?: string } })?.metadata?.resourceVersion;
+  if (!resourceVersion) return manifest;
+  return {
+    ...manifest,
+    metadata: {
+      ...(manifest.metadata as Record<string, unknown>),
+      resourceVersion,
+    },
+  };
+}
+
+function isNotFound(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) return false;
+  const e = err as { code?: number; statusCode?: number };
+  return e.code === 404 || e.statusCode === 404;
+}
+
+function isAlreadyExists(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) return false;
+  const e = err as { code?: number; statusCode?: number };
+  return e.code === 409 || e.statusCode === 409;
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/types.ts b/packages/plugins/sandbox-providers/kubernetes/src/types.ts
new file mode 100644
index 00000000..26251b4e
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/types.ts
@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { KNOWN_ADAPTER_TYPES } from "./adapter-defaults.js";
+
+function isIpv4Cidr(value: string): boolean {
+  const [address, prefix, extra] = value.split("/");
+  if (!address || !prefix || extra !== undefined || !/^\d+$/.test(prefix)) {
+    return false;
+  }
+
+  const prefixNumber = Number(prefix);
+  if (prefixNumber < 0 || prefixNumber > 32) {
+    return false;
+  }
+
+  const octets = address.split(".");
+  return octets.length === 4 && octets.every((octet) => {
+    if (!/^\d+$/.test(octet)) {
+      return false;
+    }
+
+    const value = Number(octet);
+    return value >= 0 && value <= 255;
+  });
+}
+
+export const kubernetesProviderConfigSchema = z
+  .object({
+    inCluster: z.boolean().default(false),
+    kubeconfig: z.string().optional(),
+
+    namespacePrefix: z.string().regex(/^[a-z0-9-]{1,20}$/).default("paperclip-"),
+    paperclipServerNamespace: z
+      .string()
+      .min(1)
+      .max(63)
+      .regex(/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/)
+      .default("paperclip"),
+    companySlug: z.string().regex(/^[a-z0-9-]{1,43}$/).optional(),
+
+    imageRegistry: z.string().url().optional(),
+    imageAllowList: z.array(z.string()).default([]),
+    imagePullSecrets: z.array(z.string()).default([]),
+
+    egressAllowFqdns: z.array(z.string()).default([]),
+    egressAllowCidrs: z.array(z.string().refine(isIpv4Cidr, "Invalid CIDR")).default([]),
+    egressMode: z.enum(["cilium", "standard"]).default("standard"),
+
+    defaultResources: z
+      .object({
+        requests: z.object({ cpu: z.string(), memory: z.string() }).partial().optional(),
+        limits: z.object({ cpu: z.string(), memory: z.string() }).partial().optional(),
+      })
+      .optional(),
+
+    runtimeClassName: z.string().optional(),
+    serviceAccountAnnotations: z.record(z.string()).default({}),
+
+    jobTtlSecondsAfterFinished: z.number().int().nonnegative().default(900),
+    podActivityDeadlineSec: z.number().int().positive().default(3600),
+
+    /**
+     * The adapter type that Jobs in this environment will run.
+     * Each Kubernetes environment is bound to one adapter; create multiple
+     * environments for different adapters.
+     * Defaults to `"claude_local"`.
+     */
+    adapterType: z
+      .string()
+      .default("claude_local")
+      .refine((v) => KNOWN_ADAPTER_TYPES.has(v), {
+        message: "adapterType must be one of the known adapter types",
+      }),
+
+    /**
+     * The sandbox backend to use.
+     *
+     * - `"sandbox-cr"` (default, alpha) — uses the kubernetes-sigs/agent-sandbox
+     *   Sandbox CRD (agents.x-k8s.io/v1alpha1). Creates a long-lived pod that
+     *   paperclip-server can exec into for multi-command adapter-install workflows.
+     *   Requires the agent-sandbox controller to be installed in the cluster.
+     *
+     * - `"job"` — uses batch/v1 Job (stable fallback). One-shot entrypoint; does
+     *   NOT support multi-command exec. Use this for clusters without agent-sandbox
+     *   installed, or when you need stable (non-alpha) k8s APIs.
+     */
+    backend: z.enum(["sandbox-cr", "job"]).default("sandbox-cr"),
+  })
+  .refine(
+    (cfg) => cfg.inCluster || (typeof cfg.kubeconfig === "string" && cfg.kubeconfig.trim().length > 0),
+    {
+      message:
+        "kubernetes provider requires one of `inCluster` or `kubeconfig`",
+    },
+  );
+
+export type KubernetesProviderConfig = z.infer<typeof kubernetesProviderConfigSchema>;
+
+export function parseKubernetesProviderConfig(input: unknown): KubernetesProviderConfig {
+  return kubernetesProviderConfigSchema.parse(input);
+}
+
+export interface KubernetesLeaseMetadata {
+  namespace: string;
+  /** Name of the workload resource (Job name for job backend, Sandbox CR name for sandbox-cr backend). */
+  jobName: string;
+  podName: string | null;
+  secretName: string;
+  phase: "Pending" | "Running" | "Succeeded" | "Failed";
+  /** Which backend provisioned this lease. */
+  backend: "sandbox-cr" | "job";
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/upload-interceptor.ts b/packages/plugins/sandbox-providers/kubernetes/src/upload-interceptor.ts
new file mode 100644
index 00000000..54b657c5
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/upload-interceptor.ts
@@ -0,0 +1,154 @@
+/**
+ * Fast-upload interceptor for the chunked-shell file transfer protocol used by
+ * `@paperclipai/adapter-utils` command-managed runtimes.
+ *
+ * The normal path writes files through many shell execs:
+ *   1. mkdir/rm/touch `<target>.paperclip-upload.b64`
+ *   2. append many base64 chunks with printf
+ *   3. base64-decode the temp file into the final target
+ *
+ * On Kubernetes each exec is a new WebSocket round trip. This state machine
+ * recognizes that exact protocol, buffers the base64 chunks in the plugin
+ * worker, and lets the caller flush the final payload through one exec.
+ * Pattern drift or missing state falls through to the original exec path.
+ */
+import { posix as pathPosix } from "node:path";
+
+const INIT_RE =
+  /^mkdir -p '([^']+)' && rm -f '([^']+)\.paperclip-upload\.b64' && : > '\2\.paperclip-upload\.b64'$/;
+const CHUNK_RE =
+  /^printf '%s' '([A-Za-z0-9+/]+={0,2})' >> '([^']+)\.paperclip-upload\.b64'$/;
+const FINALIZE_RE =
+  /^base64 -d < '([^']+)\.paperclip-upload\.b64' > '\1' && rm -f '\1\.paperclip-upload\.b64'$/;
+
+const MAX_BUFFER_BYTES = 100 * 1024 * 1024;
+
+export interface FastUploadFlush {
+  targetPath: string;
+  payload: Buffer;
+}
+
+export type FastUploadDecision =
+  | { action: "ack"; reason: string }
+  | { action: "flush"; flush: FastUploadFlush }
+  | { action: "error"; message: string }
+  | { action: "passthrough"; reason: string };
+
+interface BufferedUpload {
+  targetPath: string;
+  chunks: string[];
+  totalBase64Chars: number;
+  sawPaddedChunk: boolean;
+}
+
+export class FastUploadInterceptor {
+  private readonly buffers = new Map<string, BufferedUpload>();
+
+  constructor(private readonly maxBufferBytes = MAX_BUFFER_BYTES) {}
+
+  decide(command: string): FastUploadDecision {
+    const initMatch = INIT_RE.exec(command);
+    if (initMatch) {
+      const dir = initMatch[1];
+      const targetPath = initMatch[2];
+      if (pathPosix.dirname(targetPath) !== dir) {
+        return { action: "passthrough", reason: "init dir/target mismatch" };
+      }
+
+      const tempPath = `${targetPath}.paperclip-upload.b64`;
+      if (this.buffers.has(tempPath)) {
+        this.buffers.delete(tempPath);
+        return {
+          action: "error",
+          message: `Fast upload already in progress for ${targetPath}; retry the upload from the beginning.`,
+        };
+      }
+
+      this.buffers.set(tempPath, {
+        targetPath,
+        chunks: [],
+        totalBase64Chars: 0,
+        sawPaddedChunk: false,
+      });
+      return { action: "ack", reason: `init upload to ${targetPath}` };
+    }
+
+    const chunkMatch = CHUNK_RE.exec(command);
+    if (chunkMatch) {
+      const base64Chunk = chunkMatch[1];
+      const targetPath = chunkMatch[2];
+      const tempPath = `${targetPath}.paperclip-upload.b64`;
+      const upload = this.buffers.get(tempPath);
+      if (!upload) {
+        return { action: "passthrough", reason: "chunk without prior init" };
+      }
+      if (upload.sawPaddedChunk) {
+        this.buffers.delete(tempPath);
+        return {
+          action: "error",
+          message: `Fast upload received data after a padded chunk for ${upload.targetPath}; retry the upload from the beginning.`,
+        };
+      }
+
+      if (upload.totalBase64Chars + base64Chunk.length > (this.maxBufferBytes * 4) / 3) {
+        this.buffers.delete(tempPath);
+        return {
+          action: "error",
+          message: `Fast upload buffer cap exceeded for ${upload.targetPath}; retry the upload with a smaller payload.`,
+        };
+      }
+
+      upload.chunks.push(base64Chunk);
+      upload.totalBase64Chars += base64Chunk.length;
+      upload.sawPaddedChunk = base64Chunk.endsWith("=");
+      return { action: "ack", reason: `buffered ${base64Chunk.length} base64 chars` };
+    }
+
+    const finalizeMatch = FINALIZE_RE.exec(command);
+    if (finalizeMatch) {
+      const targetPath = finalizeMatch[1];
+      const tempPath = `${targetPath}.paperclip-upload.b64`;
+      const upload = this.buffers.get(tempPath);
+      if (!upload) {
+        return { action: "passthrough", reason: "finalize without buffered state" };
+      }
+
+      this.buffers.delete(tempPath);
+      return {
+        action: "flush",
+        flush: {
+          targetPath: upload.targetPath,
+          payload: Buffer.from(upload.chunks.join(""), "base64"),
+        },
+      };
+    }
+
+    const activeUpload = this.findActiveUploadForCommand(command);
+    if (activeUpload) {
+      this.buffers.delete(activeUpload.tempPath);
+      return {
+        action: "error",
+        message: `Fast upload protocol violation for ${activeUpload.upload.targetPath}; retry the upload from the beginning.`,
+      };
+    }
+
+    return { action: "passthrough", reason: "no upload pattern" };
+  }
+
+  reset(): void {
+    this.buffers.clear();
+  }
+
+  get pendingCount(): number {
+    return this.buffers.size;
+  }
+
+  private findActiveUploadForCommand(command: string): { tempPath: string; upload: BufferedUpload } | null {
+    for (const [tempPath, upload] of this.buffers) {
+      if (command.includes(`'${tempPath}'`)) {
+        return { tempPath, upload };
+      }
+    }
+    return null;
+  }
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/utils.ts b/packages/plugins/sandbox-providers/kubernetes/src/utils.ts
new file mode 100644
index 00000000..63ca8b28
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/utils.ts
@@ -0,0 +1,49 @@
+import { randomBytes } from "node:crypto";
+
+const ULID_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
+
+export function deriveCompanySlug(input: string): string {
+  const slug = input
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32)
+    .replace(/-+$/, "");
+  return slug.length > 0 ? slug : "company";
+}
+
+export function deriveNamespaceName(prefix: string, slug: string): string {
+  return `${prefix}${slug}`;
+}
+
+export function newRunUlidDns(now: () => number = Date.now): string {
+  const timestamp = now();
+  let out = "";
+  let t = timestamp;
+  for (let i = 0; i < 10; i++) {
+    out = ULID_ALPHABET[t & 0x1f] + out;
+    t = Math.floor(t / 32);
+  }
+  const randBytes = randomBytes(16);
+  for (let i = 0; i < 16; i++) {
+    out += ULID_ALPHABET[randBytes[i] & 0x1f];
+  }
+  return out;
+}
+
+export interface LabelsInput {
+  runId: string;
+  agentId: string;
+  companyId: string;
+  adapterType: string;
+}
+
+export function paperclipLabels(input: LabelsInput): Record<string, string> {
+  return {
+    "paperclip.io/run-id": input.runId,
+    "paperclip.io/agent-id": input.agentId,
+    "paperclip.io/company-id": input.companyId,
+    "paperclip.io/adapter": input.adapterType,
+    "paperclip.io/managed-by": "paperclip-k8s-plugin",
+  };
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/src/worker.ts b/packages/plugins/sandbox-providers/kubernetes/src/worker.ts
new file mode 100644
index 00000000..1e156024
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/src/worker.ts
@@ -0,0 +1,5 @@
+import { runWorker } from "@paperclipai/plugin-sdk";
+import plugin from "./plugin.js";
+
+export default plugin;
+runWorker(plugin, import.meta.url);
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/integration/_kind-harness.ts b/packages/plugins/sandbox-providers/kubernetes/test/integration/_kind-harness.ts
new file mode 100644
index 00000000..a12000ca
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/integration/_kind-harness.ts
@@ -0,0 +1,22 @@
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const KIND_CONTEXT = "kind-paperclip";
+
+export function readKindKubeconfig(): string {
+  return readFileSync(join(homedir(), ".kube", "config"), "utf-8");
+}
+
+export function kubectl(args: string): string {
+  return execSync(`kubectl --context ${KIND_CONTEXT} ${args}`, { encoding: "utf-8" });
+}
+
+export function deleteNamespaceIfExists(namespace: string): void {
+  try {
+    kubectl(`delete namespace ${namespace} --wait=true --timeout=60s --ignore-not-found`);
+  } catch {
+    // ignore
+  }
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/integration/end-to-end-run.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/integration/end-to-end-run.test.ts
new file mode 100644
index 00000000..8fb64270
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/integration/end-to-end-run.test.ts
@@ -0,0 +1,205 @@
+/**
+ * End-to-end integration test against a local kind cluster.
+ *
+ * PREREQUISITES (operator must perform before running this test):
+ *   1. Create the kind cluster:
+ *        kind create cluster --name paperclip
+ *   2. Pre-load the alpine image so the Job can start without network access:
+ *        docker pull alpine:3.20
+ *        docker tag alpine:3.20 localhost/paperclip-agent:latest
+ *        kind load docker-image localhost/paperclip-agent:latest --name paperclip
+ *   3. For the sandbox-cr backend test, the agent-sandbox controller must be installed:
+ *        kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/install.yaml
+ *      And a tini-bearing image pre-loaded (e.g. the same localhost/paperclip-agent:latest
+ *      if it includes /usr/bin/tini and /bin/sh).
+ *   4. Set the env var and run:
+ *        RUN_K8S_INTEGRATION_TESTS=1 pnpm test
+ *
+ * The namespace is derived from companySlug ("spike-e2e") + namespacePrefix
+ * ("paperclip-"), resolving to "paperclip-spike-e2e".
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import plugin from "../../src/plugin.js";
+import { createKubeConfig } from "../../src/kube-client.js";
+import { execInPod } from "../../src/pod-exec.js";
+import { sandboxCrOrchestrator } from "../../src/sandbox-cr-orchestrator.js";
+import { deleteNamespaceIfExists, kubectl, readKindKubeconfig } from "./_kind-harness.js";
+
+const NAMESPACE = "paperclip-spike-e2e";
+
+describe("plugin-kubernetes end-to-end", () => {
+  beforeAll(() => {
+    if (process.env.RUN_K8S_INTEGRATION_TESTS !== "1") return;
+    deleteNamespaceIfExists(NAMESPACE);
+  });
+
+  afterAll(() => {
+    if (process.env.RUN_K8S_INTEGRATION_TESTS !== "1") return;
+    deleteNamespaceIfExists(NAMESPACE);
+  });
+
+  // ── Job backend (stable fallback) ─────────────────────────────────────────
+
+  it.runIf(process.env.RUN_K8S_INTEGRATION_TESTS === "1")(
+    "[job backend] acquireLease creates tenant + Job + supporting resources; releaseLease cascade-deletes them",
+    async () => {
+      const kubeconfig = readKindKubeconfig();
+      const config = {
+        inCluster: false,
+        kubeconfig,
+        companySlug: "spike-e2e",
+        adapterType: "claude_local",
+        backend: "job",
+        imageAllowList: [] as string[],
+        podActivityDeadlineSec: 60,
+        jobTtlSecondsAfterFinished: 60,
+      };
+
+      const lease = await plugin.definition.onEnvironmentAcquireLease!({
+        driverKey: "kubernetes",
+        config,
+        runId: "r-test-e2e-job",
+        companyId: "11111111-1111-1111-1111-111111111111",
+        environmentId: "env-test",
+      });
+
+      expect(lease.providerLeaseId).toMatch(/^pc-/);
+
+      // Verify the Job exists in the tenant namespace
+      const jobs = kubectl(`get jobs -n ${NAMESPACE} -o name`);
+      expect(jobs).toContain(`job.batch/${lease.providerLeaseId}`);
+
+      // Verify the tenant namespace has the expected supporting resources
+      const all = kubectl(
+        `get sa,role,rolebinding,resourcequota,limitrange,networkpolicy -n ${NAMESPACE} -o name`,
+      );
+      expect(all).toContain("serviceaccount/paperclip-tenant-sa");
+      expect(all).toContain("role.rbac.authorization.k8s.io/paperclip-tenant-role");
+      expect(all).toContain("rolebinding.rbac.authorization.k8s.io/paperclip-tenant-rb");
+      expect(all).toContain("resourcequota/paperclip-quota");
+      expect(all).toContain("limitrange/paperclip-limits");
+      expect(all).toContain("networkpolicy.networking.k8s.io/paperclip-deny-all");
+      expect(all).toContain("networkpolicy.networking.k8s.io/paperclip-egress-allow");
+
+      // Verify the namespace has PSS-restricted labels
+      const ns = kubectl(`get namespace ${NAMESPACE} -o jsonpath='{.metadata.labels}'`);
+      expect(ns).toContain("pod-security.kubernetes.io/enforce");
+      expect(ns).toContain("restricted");
+
+      // Verify the per-run Secret exists (owned by the Job for cascade deletion)
+      const secrets = kubectl(`get secrets -n ${NAMESPACE} -o name`);
+      expect(secrets).toContain(`secret/${lease.providerLeaseId}-env`);
+
+      // Release — deletes the Job with Foreground propagation, which cascade-deletes
+      // the owned Secret via owner references set at acquireLease time.
+      await plugin.definition.onEnvironmentReleaseLease!({
+        driverKey: "kubernetes",
+        config,
+        providerLeaseId: lease.providerLeaseId,
+        leaseMetadata: lease.metadata,
+        companyId: "11111111-1111-1111-1111-111111111111",
+        environmentId: "env-test",
+      });
+
+      // Allow a brief grace window for Foreground propagation to finish.
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+
+      const jobsAfter = kubectl(`get jobs -n ${NAMESPACE} -o name 2>&1 || true`);
+      expect(jobsAfter).not.toContain(`job.batch/${lease.providerLeaseId}`);
+    },
+    180_000,
+  );
+
+  // ── Sandbox-CR backend (alpha, requires agent-sandbox controller) ──────────
+
+  it.runIf(process.env.RUN_K8S_INTEGRATION_TESTS === "1")(
+    "[sandbox-cr backend] acquireLease creates Sandbox CR + supporting resources; pod becomes Ready; execInPod runs echo hello; releaseLease deletes CR",
+    async () => {
+      const kubeconfig = readKindKubeconfig();
+      const config = {
+        inCluster: false,
+        kubeconfig,
+        companySlug: "spike-e2e",
+        adapterType: "claude_local",
+        backend: "sandbox-cr",
+        imageAllowList: [] as string[],
+        podActivityDeadlineSec: 120,
+        jobTtlSecondsAfterFinished: 60,
+      };
+
+      const lease = await plugin.definition.onEnvironmentAcquireLease!({
+        driverKey: "kubernetes",
+        config,
+        runId: "r-test-e2e-sandbox-cr",
+        companyId: "22222222-2222-2222-2222-222222222222",
+        environmentId: "env-test-cr",
+      });
+
+      expect(lease.providerLeaseId).toMatch(/^pc-/);
+
+      // Verify the Sandbox CR exists in the tenant namespace
+      const sandboxes = kubectl(
+        `get sandboxes.agents.x-k8s.io -n ${NAMESPACE} -o name 2>&1`,
+      );
+      expect(sandboxes).toContain(`sandbox.agents.x-k8s.io/${lease.providerLeaseId}`);
+
+      // Verify the per-run Secret exists (owned by the Sandbox CR)
+      const secrets = kubectl(`get secrets -n ${NAMESPACE} -o name`);
+      expect(secrets).toContain(`secret/${lease.providerLeaseId}-env`);
+
+      // Wait for the Sandbox pod to become Ready
+      const kc = createKubeConfig({ inCluster: false, kubeconfig });
+      const { makeKubeClients } = await import("../../src/kube-client.js");
+      const clients = makeKubeClients(kc);
+
+      await sandboxCrOrchestrator.waitForCompletion(
+        clients,
+        NAMESPACE,
+        lease.providerLeaseId,
+        { timeoutMs: 90_000, pollMs: 3000 },
+      );
+
+      // Resolve the pod name
+      const podName = await sandboxCrOrchestrator.findPod(
+        clients,
+        NAMESPACE,
+        lease.providerLeaseId,
+      );
+      expect(podName).toBeTruthy();
+
+      // Exec a simple echo command into the running pod
+      const execResult = await execInPod(
+        kc,
+        NAMESPACE,
+        podName!,
+        "agent",
+        ["echo", "hello"],
+      );
+
+      expect(execResult.exitCode).toBe(0);
+      expect(execResult.stdout.trim()).toBe("hello");
+
+      // Release — deletes the Sandbox CR with Foreground propagation.
+      await plugin.definition.onEnvironmentReleaseLease!({
+        driverKey: "kubernetes",
+        config,
+        providerLeaseId: lease.providerLeaseId,
+        leaseMetadata: lease.metadata,
+        companyId: "22222222-2222-2222-2222-222222222222",
+        environmentId: "env-test-cr",
+      });
+
+      // Allow a brief grace window for Foreground propagation.
+      await new Promise((resolve) => setTimeout(resolve, 3000));
+
+      const sandboxesAfter = kubectl(
+        `get sandboxes.agents.x-k8s.io -n ${NAMESPACE} -o name 2>&1 || true`,
+      );
+      expect(sandboxesAfter).not.toContain(
+        `sandbox.agents.x-k8s.io/${lease.providerLeaseId}`,
+      );
+    },
+    300_000,
+  );
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/adapter-defaults.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/adapter-defaults.test.ts
new file mode 100644
index 00000000..02beb05c
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/adapter-defaults.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { getAdapterDefaults, KNOWN_ADAPTER_TYPES } from "../../src/adapter-defaults.js";
+
+describe("adapter-defaults", () => {
+  it("returns defaults for claude_local", () => {
+    const d = getAdapterDefaults("claude_local");
+    expect(d.runtimeImage).toBe("ghcr.io/paperclipai/agent-runtime-claude:v1");
+    expect(d.envKeys).toContain("ANTHROPIC_API_KEY");
+    expect(d.allowFqdns).toContain("api.anthropic.com");
+    expect(d.probeCommand).toEqual(["claude", "--version"]);
+  });
+
+  it("returns defaults for codex_local", () => {
+    const d = getAdapterDefaults("codex_local");
+    expect(d.runtimeImage).toBe("ghcr.io/paperclipai/agent-runtime-codex:v1");
+    expect(d.envKeys).toContain("OPENAI_API_KEY");
+    expect(d.probeCommand).toEqual(["codex", "--version"]);
+  });
+
+  it("throws on unknown adapter type", () => {
+    expect(() => getAdapterDefaults("nonexistent_local")).toThrow(/unknown adapter type/i);
+  });
+
+  it("KNOWN_ADAPTER_TYPES contains all 7 supported adapters", () => {
+    expect(KNOWN_ADAPTER_TYPES).toEqual(
+      new Set([
+        "claude_local",
+        "codex_local",
+        "gemini_local",
+        "cursor_local",
+        "opencode_local",
+        "acpx_local",
+        "pi_local",
+      ]),
+    );
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/cilium-network-policy.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/cilium-network-policy.test.ts
new file mode 100644
index 00000000..592393ac
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/cilium-network-policy.test.ts
@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { buildCiliumNetworkPolicyManifest } from "../../src/cilium-network-policy.js";
+
+describe("buildCiliumNetworkPolicyManifest", () => {
+  const baseInput = {
+    namespace: "paperclip-acme",
+    paperclipServerNamespace: "paperclip",
+    egressAllowFqdns: ["api.anthropic.com"],
+    egressAllowCidrs: [] as string[],
+  };
+
+  it("returns a CiliumNetworkPolicy with the correct apiVersion and kind", () => {
+    const cnp = buildCiliumNetworkPolicyManifest(baseInput);
+    expect(cnp.apiVersion).toBe("cilium.io/v2");
+    expect(cnp.kind).toBe("CiliumNetworkPolicy");
+  });
+
+  it("targets agent pods by role label", () => {
+    const cnp = buildCiliumNetworkPolicyManifest(baseInput);
+    expect(cnp.spec.endpointSelector.matchLabels["paperclip.io/role"]).toBe("agent");
+  });
+
+  it("includes an FQDN allow rule for each adapter FQDN", () => {
+    const cnp = buildCiliumNetworkPolicyManifest({
+      ...baseInput,
+      egressAllowFqdns: ["api.anthropic.com", "api.openai.com"],
+    });
+    const fqdnRule = cnp.spec.egress.find((e: { toFQDNs?: { matchName: string }[] }) => e.toFQDNs);
+    expect(fqdnRule).toBeDefined();
+    expect(fqdnRule.toFQDNs.map((f: { matchName: string }) => f.matchName).sort()).toEqual([
+      "api.anthropic.com",
+      "api.openai.com",
+    ]);
+  });
+
+  it("permits DNS to kube-dns explicitly so FQDN resolution can happen", () => {
+    const cnp = buildCiliumNetworkPolicyManifest(baseInput);
+    const dnsRule = cnp.spec.egress.find((e: { toPorts?: { ports: { port: string }[] }[] }) =>
+      e.toPorts?.some((tp) => tp.ports.some((p) => p.port === "53")),
+    );
+    expect(dnsRule).toBeDefined();
+  });
+
+  it("includes a rule for paperclip-server callback", () => {
+    const cnp = buildCiliumNetworkPolicyManifest(baseInput);
+    const cb = cnp.spec.egress.find((e: { toEndpoints?: { matchLabels: Record<string, string> }[] }) =>
+      e.toEndpoints?.some((ep) => ep.matchLabels.app === "paperclip-server"),
+    );
+    expect(cb).toBeDefined();
+  });
+
+  it("includes user-supplied CIDRs in toCIDRSet rule", () => {
+    const cnp = buildCiliumNetworkPolicyManifest({
+      ...baseInput,
+      egressAllowCidrs: ["10.0.0.0/8"],
+    });
+    const cidrRule = cnp.spec.egress.find((e: { toCIDRSet?: { cidr: string }[] }) => e.toCIDRSet);
+    expect(cidrRule.toCIDRSet[0].cidr).toBe("10.0.0.0/8");
+    expect(cidrRule.toPorts).toEqual([{ ports: [{ port: "443", protocol: "TCP" }] }]);
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/image-allowlist.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/image-allowlist.test.ts
new file mode 100644
index 00000000..61b6c5d7
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/image-allowlist.test.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { globMatch, resolveImage } from "../../src/image-allowlist.js";
+
+describe("globMatch", () => {
+  it("matches exact image", () => {
+    expect(globMatch("ghcr.io/paperclipai/agent-runtime-claude:v1", "ghcr.io/paperclipai/agent-runtime-claude:v1")).toBe(true);
+  });
+
+  it("matches single-character wildcard", () => {
+    expect(globMatch("ghcr.io/x:v?", "ghcr.io/x:v1")).toBe(true);
+    expect(globMatch("ghcr.io/x:v?", "ghcr.io/x:v12")).toBe(false);
+  });
+
+  it("matches multi-character wildcard", () => {
+    expect(globMatch("ghcr.io/paperclipai/*:v1", "ghcr.io/paperclipai/agent-runtime-claude:v1")).toBe(true);
+    expect(globMatch("ghcr.io/paperclipai/*:v1", "docker.io/other/img:v1")).toBe(false);
+  });
+
+  it("does not allow wildcard to span slashes by default", () => {
+    expect(globMatch("ghcr.io/*:v1", "ghcr.io/paperclipai/agent-runtime-claude:v1")).toBe(false);
+  });
+});
+
+describe("resolveImage", () => {
+  const defaults = { runtimeImage: "ghcr.io/paperclipai/agent-runtime-claude:v1" };
+
+  it("uses adapter default when no override", () => {
+    expect(resolveImage({ imageOverride: null }, defaults, { imageAllowList: [], imageRegistry: undefined })).toBe(
+      "ghcr.io/paperclipai/agent-runtime-claude:v1",
+    );
+  });
+
+  it("rewrites registry when imageRegistry is set", () => {
+    expect(
+      resolveImage(
+        { imageOverride: null },
+        defaults,
+        { imageAllowList: [], imageRegistry: "registry.example.com/paperclip" },
+      ),
+    ).toBe("registry.example.com/paperclip/agent-runtime-claude:v1");
+  });
+
+  it("accepts imageOverride when in allowlist", () => {
+    expect(
+      resolveImage(
+        { imageOverride: "registry.example.com/mine:v2" },
+        defaults,
+        { imageAllowList: ["registry.example.com/*:v2"], imageRegistry: undefined },
+      ),
+    ).toBe("registry.example.com/mine:v2");
+  });
+
+  it("rejects imageOverride not in allowlist", () => {
+    expect(() =>
+      resolveImage(
+        { imageOverride: "evil.io/img:latest" },
+        defaults,
+        { imageAllowList: ["registry.example.com/*"], imageRegistry: undefined },
+      ),
+    ).toThrow(/not in allowlist/);
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/job-orchestrator.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/job-orchestrator.test.ts
new file mode 100644
index 00000000..eab2c009
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/job-orchestrator.test.ts
@@ -0,0 +1,101 @@
+import { describe, it, expect, vi } from "vitest";
+import { createJob, deleteJob, getJobStatus, findPodForJob, JobTimeoutError, streamPodLogs, waitForJobCompletion } from "../../src/job-orchestrator.js";
+
+describe("createJob", () => {
+  it("calls batch.createNamespacedJob with the manifest", async () => {
+    const create = vi.fn().mockResolvedValue({ metadata: { uid: "abc-uid" } });
+    const clients = { batch: { createNamespacedJob: create } };
+    const jobManifest = { apiVersion: "batch/v1", kind: "Job", metadata: { name: "r-1", namespace: "ns" }, spec: { template: {} } };
+    const result = await createJob(clients as never, "ns", jobManifest);
+    expect(create).toHaveBeenCalledWith({ namespace: "ns", body: jobManifest });
+    expect(result.uid).toBe("abc-uid");
+  });
+});
+
+describe("getJobStatus", () => {
+  it("returns phase=Succeeded when succeeded count is 1", async () => {
+    const get = vi.fn().mockResolvedValue({ status: { succeeded: 1, conditions: [{ type: "Complete", status: "True" }] } });
+    const clients = { batch: { readNamespacedJobStatus: get } };
+    const status = await getJobStatus(clients as never, "ns", "r-1");
+    expect(status.phase).toBe("Succeeded");
+    expect(status.complete).toBe(true);
+  });
+
+  it("returns phase=Failed when failed count is >0", async () => {
+    const get = vi.fn().mockResolvedValue({ status: { failed: 1, conditions: [{ type: "Failed", status: "True", reason: "DeadlineExceeded" }] } });
+    const clients = { batch: { readNamespacedJobStatus: get } };
+    const status = await getJobStatus(clients as never, "ns", "r-1");
+    expect(status.phase).toBe("Failed");
+    expect(status.reason).toBe("DeadlineExceeded");
+  });
+
+  it("returns phase=Running when active count is >0", async () => {
+    const get = vi.fn().mockResolvedValue({ status: { active: 1 } });
+    const clients = { batch: { readNamespacedJobStatus: get } };
+    const status = await getJobStatus(clients as never, "ns", "r-1");
+    expect(status.phase).toBe("Running");
+  });
+
+  it("returns phase=Pending when no active/succeeded/failed counters set", async () => {
+    const get = vi.fn().mockResolvedValue({ status: {} });
+    const clients = { batch: { readNamespacedJobStatus: get } };
+    const status = await getJobStatus(clients as never, "ns", "r-1");
+    expect(status.phase).toBe("Pending");
+  });
+});
+
+describe("findPodForJob", () => {
+  it("lists pods by job-name label and returns the first running pod", async () => {
+    const list = vi.fn().mockResolvedValue({ items: [{ metadata: { name: "r-1-xyz" }, status: { phase: "Running" } }] });
+    const clients = { core: { listNamespacedPod: list } };
+    const podName = await findPodForJob(clients as never, "ns", "r-1");
+    expect(list).toHaveBeenCalledWith(expect.objectContaining({ namespace: "ns", labelSelector: "job-name=r-1" }));
+    expect(podName).toBe("r-1-xyz");
+  });
+
+  it("returns null when no pod is found", async () => {
+    const list = vi.fn().mockResolvedValue({ items: [] });
+    const clients = { core: { listNamespacedPod: list } };
+    const podName = await findPodForJob(clients as never, "ns", "r-1");
+    expect(podName).toBeNull();
+  });
+});
+
+describe("deleteJob", () => {
+  it("calls batch.deleteNamespacedJob with foreground propagation", async () => {
+    const del = vi.fn().mockResolvedValue({});
+    const clients = { batch: { deleteNamespacedJob: del } };
+    await deleteJob(clients as never, "ns", "r-1");
+    expect(del).toHaveBeenCalledWith(
+      expect.objectContaining({
+        namespace: "ns",
+        name: "r-1",
+        propagationPolicy: "Foreground",
+      }),
+    );
+  });
+});
+
+describe("streamPodLogs", () => {
+  it("emits pod log response bodies as stdout because Kubernetes pod logs are combined", async () => {
+    const readNamespacedPodLog = vi.fn().mockResolvedValue({ body: "hello\n" });
+    const clients = { core: { readNamespacedPodLog } };
+    const chunks: { stream: "stdout" | "stderr"; text: string }[] = [];
+    await streamPodLogs(clients as never, "ns", "pod-1", async (stream, text) => {
+      chunks.push({ stream, text });
+    });
+
+    expect(readNamespacedPodLog).toHaveBeenCalledWith({ namespace: "ns", name: "pod-1" });
+    expect(chunks).toEqual([{ stream: "stdout", text: "hello\n" }]);
+  });
+});
+
+describe("waitForJobCompletion", () => {
+  it("throws JobTimeoutError when the deadline is exceeded", async () => {
+    const get = vi.fn().mockResolvedValue({ status: { active: 1 } });
+    const clients = { batch: { readNamespacedJobStatus: get } };
+    await expect(
+      waitForJobCompletion(clients as never, "ns", "r-1", { timeoutMs: 50, pollMs: 10 }),
+    ).rejects.toBeInstanceOf(JobTimeoutError);
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/kube-client.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/kube-client.test.ts
new file mode 100644
index 00000000..55a1731e
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/kube-client.test.ts
@@ -0,0 +1,47 @@
+import { describe, it, expect, vi } from "vitest";
+import { KubeConfig } from "@kubernetes/client-node";
+import { createKubeConfig } from "../../src/kube-client.js";
+
+describe("createKubeConfig", () => {
+  it("loads from inline kubeconfig string", () => {
+    const yaml = `apiVersion: v1
+kind: Config
+clusters:
+  - name: test
+    cluster:
+      server: https://fake.example.com
+contexts:
+  - name: test
+    context:
+      cluster: test
+      user: test
+current-context: test
+users:
+  - name: test
+    user:
+      token: fake-token
+`;
+    const kc = createKubeConfig({ inCluster: false, kubeconfig: yaml });
+    expect(kc.getCurrentContext()).toBe("test");
+    expect(kc.getCurrentCluster()?.server).toBe("https://fake.example.com");
+  });
+
+  it("loads from-cluster config when inCluster=true", () => {
+    const spy = vi.spyOn(KubeConfig.prototype, "loadFromCluster").mockImplementation(function (this: KubeConfig) {
+      this.loadFromString(`apiVersion: v1
+kind: Config
+clusters: [{name: in-cluster, cluster: {server: 'https://kubernetes.default.svc'}}]
+contexts: [{name: in-cluster, context: {cluster: in-cluster, user: in-cluster}}]
+current-context: in-cluster
+users: [{name: in-cluster, user: {token: tok}}]`);
+    });
+    const kc = createKubeConfig({ inCluster: true });
+    expect(spy).toHaveBeenCalledOnce();
+    expect(kc.getCurrentContext()).toBe("in-cluster");
+    spy.mockRestore();
+  });
+
+  it("throws when neither inCluster nor kubeconfig string is provided", () => {
+    expect(() => createKubeConfig({ inCluster: false })).toThrow(/requires/i);
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/manifest.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/manifest.test.ts
new file mode 100644
index 00000000..ae44654b
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/manifest.test.ts
@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import manifest from "../../src/manifest.js";
+
+describe("manifest", () => {
+  const configSchema = manifest.environmentDrivers[0]?.configSchema as {
+    properties: Record<string, { const?: unknown; description?: string; maxLength?: number; pattern?: string }>;
+    anyOf: Array<{
+      properties?: Record<string, { const?: unknown }>;
+      required?: string[];
+    }>;
+  };
+
+  it("keeps namespace inputs within the Kubernetes DNS label length limit", () => {
+    expect(configSchema.properties.namespacePrefix.maxLength).toBe(20);
+    expect(configSchema.properties.paperclipServerNamespace.maxLength).toBe(63);
+    expect(configSchema.properties.paperclipServerNamespace.pattern).toBe(
+      "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+    );
+    expect(configSchema.properties.companySlug.maxLength).toBe(43);
+  });
+
+  it("requires real Kubernetes credentials instead of only inCluster key presence", () => {
+    expect(configSchema.properties.kubeconfig.pattern).toBe("\\S");
+    expect(configSchema.anyOf).toContainEqual({
+      properties: { inCluster: { const: true } },
+      required: ["inCluster"],
+    });
+    expect(configSchema.anyOf).toContainEqual({ required: ["kubeconfig"] });
+  });
+
+  it("documents that CIDR egress is HTTPS-only", () => {
+    expect(configSchema.properties.egressAllowCidrs.description).toContain("TCP port 443");
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/network-policy.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/network-policy.test.ts
new file mode 100644
index 00000000..aec46bb1
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/network-policy.test.ts
@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest";
+import { buildNetworkPolicyManifests } from "../../src/network-policy.js";
+
+describe("buildNetworkPolicyManifests", () => {
+  const baseInput = {
+    namespace: "paperclip-acme",
+    paperclipServerNamespace: "paperclip",
+    egressAllowFqdns: [] as string[],
+    egressAllowCidrs: [] as string[],
+  };
+
+  it("produces a deny-all + egress allow pair", () => {
+    const manifests = buildNetworkPolicyManifests(baseInput);
+    expect(manifests).toHaveLength(2);
+    expect(manifests[0].metadata.name).toBe("paperclip-deny-all");
+    expect(manifests[1].metadata.name).toBe("paperclip-egress-allow");
+  });
+
+  it("deny-all has no ingress/egress rules and applies to all pods", () => {
+    const [denyAll] = buildNetworkPolicyManifests(baseInput);
+    expect(denyAll.spec.podSelector).toEqual({});
+    expect(denyAll.spec.policyTypes).toEqual(["Ingress", "Egress"]);
+    expect(denyAll.spec.ingress).toBeUndefined();
+    expect(denyAll.spec.egress).toBeUndefined();
+  });
+
+  it("egress allow includes kube-dns and paperclip-server callback", () => {
+    const [, egress] = buildNetworkPolicyManifests(baseInput);
+    const rules = egress.spec.egress;
+    const dnsRule = rules.find((r: { ports?: { protocol: string; port: number }[] }) =>
+      r.ports?.some((p) => p.port === 53),
+    );
+    expect(dnsRule).toBeDefined();
+    const paperclipRule = rules.find((r: { to: { namespaceSelector?: { matchLabels?: Record<string, string> } }[] }) =>
+      r.to.some((t) => t.namespaceSelector?.matchLabels?.["kubernetes.io/metadata.name"] === "paperclip"),
+    );
+    expect(paperclipRule).toBeDefined();
+  });
+
+  it("includes user-supplied CIDRs in egress allow", () => {
+    const [, egress] = buildNetworkPolicyManifests({ ...baseInput, egressAllowCidrs: ["10.0.0.0/8"] });
+    const cidrRule = egress.spec.egress.find((r: { to: { ipBlock?: { cidr: string } }[]; ports?: { protocol: string; port: number }[] }) =>
+      r.to.some((t) => t.ipBlock?.cidr === "10.0.0.0/8"),
+    );
+    expect(cidrRule).toBeDefined();
+    expect(cidrRule?.ports).toEqual([{ protocol: "TCP", port: 443 }]);
+  });
+
+  it("adds a public HTTPS fallback when standard mode receives FQDN allow-list entries", () => {
+    const [, egress] = buildNetworkPolicyManifests({ ...baseInput, egressAllowFqdns: ["api.anthropic.com"] });
+    const publicHttpsRule = egress.spec.egress.find((r: { to: { ipBlock?: { cidr: string; except?: string[] } }[]; ports?: { port: number }[] }) =>
+      r.to.some((t) => t.ipBlock?.cidr === "0.0.0.0/0") && r.ports?.some((p) => p.port === 443),
+    );
+    expect(publicHttpsRule).toBeDefined();
+    expect(publicHttpsRule.to[0].ipBlock.except).toContain("10.0.0.0/8");
+  });
+
+  it("uses paperclip-server pod label selector for callback ingress to paperclip ns", () => {
+    const [, egress] = buildNetworkPolicyManifests(baseInput);
+    const callbackRule = egress.spec.egress.find((r: { to: { podSelector?: { matchLabels?: Record<string, string> } }[] }) =>
+      r.to.some((t) => t.podSelector?.matchLabels?.app === "paperclip-server"),
+    );
+    expect(callbackRule).toBeDefined();
+    expect(callbackRule.ports[0].port).toBe(3100);
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/plugin.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/plugin.test.ts
new file mode 100644
index 00000000..c70d67f1
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/plugin.test.ts
@@ -0,0 +1,189 @@
+import { describe, it, expect } from "vitest";
+import plugin, {
+  buildSandboxExecCommand,
+  buildSandboxExecShellCommand,
+  deriveUploadTargetDir,
+  extractAdapterEnvFromProcess,
+} from "../../src/plugin.js";
+
+describe("plugin", () => {
+  it("exports the kubernetes driver", () => {
+    expect(plugin.definition.onEnvironmentAcquireLease).toBeTypeOf("function");
+    expect(plugin.definition.onEnvironmentValidateConfig).toBeTypeOf("function");
+  });
+
+  it("validateConfig accepts inCluster=true config", async () => {
+    const result = await plugin.definition.onEnvironmentValidateConfig!({
+      driverKey: "kubernetes",
+      config: { inCluster: true },
+    });
+    expect(result.ok).toBe(true);
+  });
+
+  it("validateConfig rejects missing auth", async () => {
+    const result = await plugin.definition.onEnvironmentValidateConfig!({
+      driverKey: "kubernetes",
+      config: {},
+    });
+    expect(result.ok).toBe(false);
+    expect(result.errors?.[0]).toMatch(/requires one of `inCluster`/);
+  });
+
+  it("validateConfig normalizes defaults", async () => {
+    const result = await plugin.definition.onEnvironmentValidateConfig!({
+      driverKey: "kubernetes",
+      config: { inCluster: true },
+    });
+    expect(result.ok).toBe(true);
+    expect(result.normalizedConfig).toEqual(
+      expect.objectContaining({
+        namespacePrefix: "paperclip-",
+        egressMode: "standard",
+        paperclipServerNamespace: "paperclip",
+        jobTtlSecondsAfterFinished: 900,
+        podActivityDeadlineSec: 3600,
+        adapterType: "claude_local",
+        backend: "sandbox-cr", // new default
+      }),
+    );
+  });
+
+  it("validateConfig accepts backend=sandbox-cr explicitly", async () => {
+    const result = await plugin.definition.onEnvironmentValidateConfig!({
+      driverKey: "kubernetes",
+      config: { inCluster: true, backend: "sandbox-cr" },
+    });
+    expect(result.ok).toBe(true);
+    expect(result.normalizedConfig?.backend).toBe("sandbox-cr");
+  });
+
+  it("validateConfig accepts backend=job (stable fallback)", async () => {
+    const result = await plugin.definition.onEnvironmentValidateConfig!({
+      driverKey: "kubernetes",
+      config: { inCluster: true, backend: "job" },
+    });
+    expect(result.ok).toBe(true);
+    expect(result.normalizedConfig?.backend).toBe("job");
+  });
+
+  it("validateConfig rejects unknown backend value", async () => {
+    const result = await plugin.definition.onEnvironmentValidateConfig!({
+      driverKey: "kubernetes",
+      config: { inCluster: true, backend: "kata-fc" },
+    });
+    expect(result.ok).toBe(false);
+  });
+
+  it("onHealth returns ok", async () => {
+    const result = await plugin.definition.onHealth!();
+    expect(result.status).toBe("ok");
+  });
+
+  it("validateConfig warns about FQDN limitation in standard mode", async () => {
+    const result = await plugin.definition.onEnvironmentValidateConfig!({
+      driverKey: "kubernetes",
+      config: { inCluster: true, adapterType: "claude_local" },
+    });
+    expect(result.ok).toBe(true);
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings?.some((w) => w.includes("api.anthropic.com"))).toBe(true);
+  });
+
+  it("validateConfig does NOT warn when egressMode is cilium", async () => {
+    const result = await plugin.definition.onEnvironmentValidateConfig!({
+      driverKey: "kubernetes",
+      config: { inCluster: true, adapterType: "claude_local", egressMode: "cilium" },
+    });
+    expect(result.ok).toBe(true);
+    expect(result.warnings).toBeUndefined();
+  });
+
+  it("warns when adapter env keys are missing from the worker process", () => {
+    const warnMessages: string[] = [];
+    const originalPresent = process.env.PAPERCLIP_TEST_PRESENT_KEY;
+    const originalMissing = process.env.PAPERCLIP_TEST_MISSING_KEY;
+    process.env.PAPERCLIP_TEST_PRESENT_KEY = "secret-value";
+    delete process.env.PAPERCLIP_TEST_MISSING_KEY;
+    try {
+      const result = extractAdapterEnvFromProcess(
+        ["PAPERCLIP_TEST_PRESENT_KEY", "PAPERCLIP_TEST_MISSING_KEY"],
+        (message) => warnMessages.push(message),
+      );
+      expect(result).toEqual({ PAPERCLIP_TEST_PRESENT_KEY: "secret-value" });
+      expect(warnMessages).toHaveLength(1);
+      expect(warnMessages[0]).toContain("PAPERCLIP_TEST_MISSING_KEY");
+      expect(warnMessages[0]).not.toContain("secret-value");
+    } finally {
+      if (originalPresent === undefined) {
+        delete process.env.PAPERCLIP_TEST_PRESENT_KEY;
+      } else {
+        process.env.PAPERCLIP_TEST_PRESENT_KEY = originalPresent;
+      }
+      if (originalMissing === undefined) {
+        delete process.env.PAPERCLIP_TEST_MISSING_KEY;
+      } else {
+        process.env.PAPERCLIP_TEST_MISSING_KEY = originalMissing;
+      }
+    }
+  });
+
+  it("preserves intentionally empty adapter env values", () => {
+    const warnMessages: string[] = [];
+    const originalValue = process.env.PAPERCLIP_TEST_EMPTY_KEY;
+    process.env.PAPERCLIP_TEST_EMPTY_KEY = "";
+    try {
+      const result = extractAdapterEnvFromProcess(
+        ["PAPERCLIP_TEST_EMPTY_KEY"],
+        (message) => warnMessages.push(message),
+      );
+      expect(result).toEqual({ PAPERCLIP_TEST_EMPTY_KEY: "" });
+      expect(warnMessages).toHaveLength(0);
+    } finally {
+      if (originalValue === undefined) {
+        delete process.env.PAPERCLIP_TEST_EMPTY_KEY;
+      } else {
+        process.env.PAPERCLIP_TEST_EMPTY_KEY = originalValue;
+      }
+    }
+  });
+
+  it("quotes args before passing them to /bin/sh -lc", () => {
+    expect(
+      buildSandboxExecShellCommand({
+        args: ["git", "commit", "-m", "feat: add feature", "it's ready"],
+      }),
+    ).toBe("'git' 'commit' '-m' 'feat: add feature' 'it'\\''s ready'");
+  });
+
+  it("uses command verbatim when command is provided", () => {
+    expect(
+      buildSandboxExecShellCommand({
+        command: "pnpm test -- --runInBand",
+        args: ["ignored"],
+      }),
+    ).toBe("pnpm test -- --runInBand");
+  });
+
+  it("passes command and args directly to Kubernetes exec", () => {
+    expect(
+      buildSandboxExecCommand({
+        command: "sh",
+        args: ["-c", "printf '%s' ok"],
+      }),
+    ).toEqual(["sh", "-c", "printf '%s' ok"]);
+  });
+
+  it("wraps command-only execution in a login shell", () => {
+    expect(
+      buildSandboxExecCommand({
+        command: "pnpm test -- --runInBand",
+      }),
+    ).toEqual(["/bin/sh", "-lc", "pnpm test -- --runInBand"]);
+  });
+
+  it("derives upload target directories for root and nested paths", () => {
+    expect(deriveUploadTargetDir("/file")).toBe("/");
+    expect(deriveUploadTargetDir("/workspace/file")).toBe("/workspace");
+    expect(deriveUploadTargetDir("relative-file")).toBe(".");
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/pod-exec.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/pod-exec.test.ts
new file mode 100644
index 00000000..d9fb3c68
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/pod-exec.test.ts
@@ -0,0 +1,143 @@
+import { EventEmitter } from "node:events";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const execMock = vi.fn();
+
+vi.mock("@kubernetes/client-node", () => ({
+  Exec: vi.fn().mockImplementation(() => ({ exec: execMock })),
+}));
+
+const { execInPod } = await import("../../src/pod-exec.js");
+
+describe("execInPod", () => {
+  beforeEach(() => {
+    execMock.mockReset();
+  });
+
+  it("returns success when the Kubernetes exec status callback reports success", async () => {
+    execMock.mockImplementation((_namespace, _pod, _container, _command, stdout, _stderr, _stdin, _tty, statusCallback) => {
+      stdout.write("ok\n");
+      stdout.end();
+      _stderr.end();
+      statusCallback({ status: "Success" });
+      return Promise.resolve(new EventEmitter());
+    });
+
+    const result = await execInPod({} as never, "ns", "pod-1", "agent", ["echo", "ok"]);
+    expect(result).toEqual({ exitCode: 0, timedOut: false, stdout: "ok\n", stderr: "" });
+  });
+
+  it("finishes when Kubernetes reports status without ending output streams", async () => {
+    execMock.mockImplementation((_namespace, _pod, _container, _command, stdout, _stderr, _stdin, _tty, statusCallback) => {
+      stdout.write("ok\n");
+      statusCallback({ status: "Success" });
+      return Promise.resolve(new EventEmitter());
+    });
+
+    const result = await execInPod({} as never, "ns", "pod-1", "agent", ["echo", "ok"]);
+    expect(result).toEqual({ exitCode: 0, timedOut: false, stdout: "ok\n", stderr: "" });
+  });
+
+  it("handles output stream errors after status completion", async () => {
+    execMock.mockImplementation((_namespace, _pod, _container, _command, stdout, _stderr, _stdin, _tty, statusCallback) => {
+      statusCallback({ status: "Success" });
+      stdout.emit("error", new Error("write after end"));
+      return Promise.resolve(new EventEmitter());
+    });
+
+    const result = await execInPod({} as never, "ns", "pod-1", "agent", ["echo", "ok"]);
+    expect(result).toEqual({ exitCode: 0, timedOut: false, stdout: "", stderr: "" });
+  });
+
+  it("returns an execution failure if the websocket closes before a status frame", async () => {
+    const ws = new EventEmitter();
+    execMock.mockResolvedValue(ws);
+
+    const resultPromise = execInPod({} as never, "ns", "pod-1", "agent", ["sleep", "1"]);
+    await Promise.resolve();
+    ws.emit("close", 1006, Buffer.from("connection lost"));
+
+    await expect(resultPromise).resolves.toMatchObject({
+      exitCode: 1,
+      timedOut: false,
+      stderr: expect.stringContaining("websocket closed before status frame"),
+    });
+  });
+
+  it("returns an execution failure if the exec command exceeds its deadline", async () => {
+    execMock.mockResolvedValue(new EventEmitter());
+
+    const result = await execInPod({} as never, "ns", "pod-1", "agent", ["sleep", "60"], undefined, 5);
+
+    expect(result.exitCode).toBe(1);
+    expect(result.timedOut).toBe(true);
+    expect(result.stderr).toContain("Kubernetes exec timed out after 5ms");
+  });
+
+  it("clears the timeout when websocket setup rejects", async () => {
+    const clearTimeoutSpy = vi.spyOn(globalThis, "clearTimeout");
+    execMock.mockRejectedValue(new Error("network unreachable"));
+
+    await expect(
+      execInPod({} as never, "ns", "pod-1", "agent", ["echo", "ok"], undefined, 1000),
+    ).rejects.toThrow("network unreachable");
+    expect(clearTimeoutSpy).toHaveBeenCalled();
+    clearTimeoutSpy.mockRestore();
+  });
+
+  it("wraps stdin commands with a byte-counted head prefix", async () => {
+    let observedCommand: string[] | undefined;
+    let observedStdin = "";
+    let observedStdinFinished = false;
+
+    execMock.mockImplementation((_namespace, _pod, _container, command, stdout, stderr, stdin, _tty, statusCallback) => {
+      observedCommand = command;
+      stdin?.on("data", (chunk: Buffer) => {
+        observedStdin += chunk.toString("utf8");
+      });
+      stdin?.on("finish", () => {
+        observedStdinFinished = true;
+      });
+      stdout.end();
+      stderr.end();
+      statusCallback({ status: "Success" });
+      return Promise.resolve(new EventEmitter());
+    });
+
+    await execInPod({} as never, "ns", "pod-1", "agent", ["base64", "-d"], "abc");
+    await Promise.resolve();
+
+    expect(observedCommand).toEqual(["/bin/sh", "-c", "head -c 3 | 'base64' '-d'"]);
+    expect(observedStdin).toBe("abc");
+    expect(observedStdinFinished).toBe(true);
+  });
+
+  it("does not send stdin if the exec timed out before websocket setup completed", async () => {
+    let resolveWebsocket: ((ws: EventEmitter) => void) | undefined;
+    let observedStdin = "";
+    let observedStdinFinished = false;
+    const ws = Object.assign(new EventEmitter(), { close: vi.fn() });
+
+    execMock.mockImplementation((_namespace, _pod, _container, _command, _stdout, _stderr, stdin) => {
+      stdin?.on("data", (chunk: Buffer) => {
+        observedStdin += chunk.toString("utf8");
+      });
+      stdin?.on("finish", () => {
+        observedStdinFinished = true;
+      });
+      return new Promise<EventEmitter>((resolve) => {
+        resolveWebsocket = resolve;
+      });
+    });
+
+    const result = await execInPod({} as never, "ns", "pod-1", "agent", ["base64", "-d"], "abc", 5);
+    expect(result.timedOut).toBe(true);
+
+    resolveWebsocket?.(ws);
+    await Promise.resolve();
+
+    expect(ws.close).toHaveBeenCalled();
+    expect(observedStdin).toBe("");
+    expect(observedStdinFinished).toBe(false);
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/pod-spec-builder.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/pod-spec-builder.test.ts
new file mode 100644
index 00000000..75d1da3c
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/pod-spec-builder.test.ts
@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest";
+import { buildJobManifest } from "../../src/pod-spec-builder.js";
+
+const baseInput = {
+  namespace: "paperclip-acme",
+  jobName: "r-01h00000000000000000000000",
+  adapterType: "claude_local",
+  image: "ghcr.io/paperclipai/agent-runtime-claude:v1",
+  envSecretName: "r-01h00000000000000000000000-env",
+  serviceAccountName: "paperclip-tenant-sa",
+  labels: { "paperclip.io/run-id": "r1" },
+  resources: { requests: { cpu: "250m", memory: "512Mi" }, limits: { cpu: "2", memory: "4Gi" } },
+  runtimeClassName: undefined,
+  activeDeadlineSec: 3600,
+  ttlSecondsAfterFinished: 900,
+};
+
+describe("buildJobManifest", () => {
+  it("returns a Job manifest with the correct apiVersion and kind", () => {
+    const job = buildJobManifest(baseInput);
+    expect(job.apiVersion).toBe("batch/v1");
+    expect(job.kind).toBe("Job");
+  });
+
+  it("sets Job-level lifecycle controls: backoffLimit=0, ttlSecondsAfterFinished, activeDeadlineSeconds", () => {
+    const job = buildJobManifest({ ...baseInput, activeDeadlineSec: 1800, ttlSecondsAfterFinished: 600 });
+    expect(job.spec.backoffLimit).toBe(0);
+    expect(job.spec.ttlSecondsAfterFinished).toBe(600);
+    expect(job.spec.activeDeadlineSeconds).toBe(1800);
+  });
+
+  it("sets the security context to non-root, drop ALL caps, read-only rootFS, seccomp RuntimeDefault", () => {
+    const job = buildJobManifest(baseInput);
+    const podSec = job.spec.template.spec.securityContext;
+    expect(podSec.runAsNonRoot).toBe(true);
+    expect(podSec.runAsUser).toBe(1000);
+    expect(podSec.fsGroupChangePolicy).toBe("OnRootMismatch");
+    expect(podSec.seccompProfile.type).toBe("RuntimeDefault");
+
+    const container = job.spec.template.spec.containers[0];
+    expect(container.securityContext.runAsNonRoot).toBe(true);
+    expect(container.securityContext.readOnlyRootFilesystem).toBe(true);
+    expect(container.securityContext.allowPrivilegeEscalation).toBe(false);
+    expect(container.securityContext.capabilities.drop).toEqual(["ALL"]);
+  });
+
+  it("wraps the entrypoint in tini for PID 1", () => {
+    const job = buildJobManifest(baseInput);
+    const container = job.spec.template.spec.containers[0];
+    expect(container.command).toEqual(["/usr/bin/tini", "--", "/usr/local/bin/paperclip-agent-shim"]);
+  });
+
+  it("declares explicit writable emptyDir mounts for the standard agent paths", () => {
+    const job = buildJobManifest(baseInput);
+    const mounts = job.spec.template.spec.containers[0].volumeMounts;
+    const mountPaths = mounts.map((m: { mountPath: string }) => m.mountPath).sort();
+    expect(mountPaths).toEqual(["/home/paperclip", "/home/paperclip/.cache", "/tmp", "/workspace"]);
+
+    const volumes = job.spec.template.spec.volumes;
+    expect(volumes.every((v: { emptyDir?: unknown }) => v.emptyDir !== undefined)).toBe(true);
+  });
+
+  it("envFrom references the per-run secret", () => {
+    const job = buildJobManifest(baseInput);
+    const envFrom = job.spec.template.spec.containers[0].envFrom;
+    expect(envFrom[0].secretRef.name).toBe(baseInput.envSecretName);
+  });
+
+  it("applies runtimeClassName when set", () => {
+    const job = buildJobManifest({ ...baseInput, runtimeClassName: "kata-fc" });
+    expect(job.spec.template.spec.runtimeClassName).toBe("kata-fc");
+  });
+
+  it("does not set runtimeClassName when unset", () => {
+    const job = buildJobManifest(baseInput);
+    expect(job.spec.template.spec.runtimeClassName).toBeUndefined();
+  });
+
+  it("sets pod restartPolicy=Never (required for Job)", () => {
+    const job = buildJobManifest(baseInput);
+    expect(job.spec.template.spec.restartPolicy).toBe("Never");
+  });
+
+  it("disables automountServiceAccountToken to avoid exposing an unnecessary SA token", () => {
+    const job = buildJobManifest(baseInput);
+    expect(job.spec.template.spec.automountServiceAccountToken).toBe(false);
+  });
+
+  it("applies the provided labels to both Job metadata and pod template", () => {
+    const job = buildJobManifest(baseInput);
+    expect(job.metadata.labels["paperclip.io/run-id"]).toBe("r1");
+    expect(job.spec.template.metadata.labels["paperclip.io/run-id"]).toBe("r1");
+    expect(job.spec.template.metadata.labels["paperclip.io/role"]).toBe("agent");
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/sandbox-cr-builder.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/sandbox-cr-builder.test.ts
new file mode 100644
index 00000000..97beb8e9
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/sandbox-cr-builder.test.ts
@@ -0,0 +1,137 @@
+import { describe, it, expect } from "vitest";
+import { buildSandboxCrManifest } from "../../src/sandbox-cr-builder.js";
+
+const baseInput = {
+  namespace: "paperclip-acme",
+  sandboxName: "pc-01h00000000000000000000000",
+  adapterType: "claude_local",
+  image: "ghcr.io/paperclipai/agent-runtime-claude:v1",
+  envSecretName: "pc-01h00000000000000000000000-env",
+  serviceAccountName: "paperclip-tenant-sa",
+  labels: { "paperclip.io/run-id": "r1" },
+  resources: {
+    requests: { cpu: "250m", memory: "512Mi" },
+    limits: { cpu: "2", memory: "4Gi" },
+  },
+  runtimeClassName: undefined,
+};
+
+describe("buildSandboxCrManifest", () => {
+  it("returns a Sandbox CR with the correct apiVersion and kind", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    expect(cr.apiVersion).toBe("agents.x-k8s.io/v1alpha1");
+    expect(cr.kind).toBe("Sandbox");
+  });
+
+  it("sets metadata name and namespace correctly", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    expect(cr.metadata.name).toBe(baseInput.sandboxName);
+    expect(cr.metadata.namespace).toBe(baseInput.namespace);
+  });
+
+  it("does NOT set ownerReferences (out-of-cluster server, explicit release path)", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    expect(cr.metadata.ownerReferences).toBeUndefined();
+  });
+
+  it("sets restartPolicy=Always on the pod template (required for long-lived Sandbox pod)", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    expect(cr.spec.podTemplate.spec.restartPolicy).toBe("Always");
+  });
+
+  it("uses sleep-infinity entrypoint via Tini for multi-command exec", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    const container = cr.spec.podTemplate.spec.containers[0];
+    expect(container.command).toEqual([
+      "/usr/bin/tini",
+      "--",
+      "/bin/sh",
+      "-c",
+      "sleep infinity",
+    ]);
+  });
+
+  it("applies the same security baseline as Job backend (non-root, drop ALL, RO rootFS, seccomp)", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    const podSec = cr.spec.podTemplate.spec.securityContext;
+    expect(podSec.runAsNonRoot).toBe(true);
+    expect(podSec.runAsUser).toBe(1000);
+    expect(podSec.fsGroupChangePolicy).toBe("OnRootMismatch");
+    expect(podSec.seccompProfile.type).toBe("RuntimeDefault");
+
+    const container = cr.spec.podTemplate.spec.containers[0];
+    expect(container.securityContext.runAsNonRoot).toBe(true);
+    expect(container.securityContext.readOnlyRootFilesystem).toBe(true);
+    expect(container.securityContext.allowPrivilegeEscalation).toBe(false);
+    expect(container.securityContext.capabilities.drop).toEqual(["ALL"]);
+  });
+
+  it("disables automountServiceAccountToken", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    expect(cr.spec.podTemplate.spec.automountServiceAccountToken).toBe(false);
+  });
+
+  it("declares emptyDir volume mounts for standard agent paths", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    const mounts = cr.spec.podTemplate.spec.containers[0].volumeMounts;
+    const mountPaths = mounts
+      .map((m: { mountPath: string }) => m.mountPath)
+      .sort();
+    expect(mountPaths).toEqual([
+      "/home/paperclip",
+      "/home/paperclip/.cache",
+      "/tmp",
+      "/workspace",
+    ]);
+
+    const volumes = cr.spec.podTemplate.spec.volumes;
+    expect(
+      volumes.every((v: { emptyDir?: unknown }) => v.emptyDir !== undefined),
+    ).toBe(true);
+  });
+
+  it("envFrom references the per-run secret", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    const envFrom = cr.spec.podTemplate.spec.containers[0].envFrom;
+    expect(envFrom[0].secretRef.name).toBe(baseInput.envSecretName);
+  });
+
+  it("applies runtimeClassName when set", () => {
+    const cr = buildSandboxCrManifest({
+      ...baseInput,
+      runtimeClassName: "kata-fc",
+    });
+    expect(cr.spec.podTemplate.spec.runtimeClassName).toBe("kata-fc");
+  });
+
+  it("does not set runtimeClassName when unset", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    expect(cr.spec.podTemplate.spec.runtimeClassName).toBeUndefined();
+  });
+
+  it("applies provided labels to CR metadata and pod template labels (with role=agent added)", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    expect(cr.metadata.labels["paperclip.io/run-id"]).toBe("r1");
+    expect(
+      cr.spec.podTemplate.metadata.labels["paperclip.io/run-id"],
+    ).toBe("r1");
+    expect(cr.spec.podTemplate.metadata.labels["paperclip.io/role"]).toBe(
+      "agent",
+    );
+  });
+
+  it("applies imagePullSecrets when provided", () => {
+    const cr = buildSandboxCrManifest({
+      ...baseInput,
+      imagePullSecrets: ["my-pull-secret"],
+    });
+    expect(cr.spec.podTemplate.spec.imagePullSecrets).toEqual([
+      { name: "my-pull-secret" },
+    ]);
+  });
+
+  it("does not set imagePullSecrets when not provided", () => {
+    const cr = buildSandboxCrManifest(baseInput);
+    expect(cr.spec.podTemplate.spec.imagePullSecrets).toBeUndefined();
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/sandbox-cr-orchestrator.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/sandbox-cr-orchestrator.test.ts
new file mode 100644
index 00000000..9aff74e1
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/sandbox-cr-orchestrator.test.ts
@@ -0,0 +1,228 @@
+import { describe, it, expect, vi } from "vitest";
+import {
+  createSandboxCr,
+  deleteSandboxCr,
+  getSandboxCrStatus,
+  findPodForSandbox,
+  SandboxCrTimeoutError,
+  waitForSandboxReady,
+} from "../../src/sandbox-cr-orchestrator.js";
+
+const SANDBOX_GROUP = "agents.x-k8s.io";
+const SANDBOX_VERSION = "v1alpha1";
+const SANDBOX_PLURAL = "sandboxes";
+
+// Helpers to build mock CR objects with given phase
+function makeCr(phase: string, podName?: string): Record<string, unknown> {
+  return {
+    metadata: { uid: "sandbox-uid-123" },
+    status: {
+      phase,
+      ...(podName ? { podName } : {}),
+    },
+  };
+}
+
+describe("createSandboxCr", () => {
+  it("calls custom.createNamespacedCustomObject with the correct params", async () => {
+    const create = vi.fn().mockResolvedValue({ metadata: { uid: "test-uid" } });
+    const clients = { custom: { createNamespacedCustomObject: create } };
+    const manifest = {
+      apiVersion: "agents.x-k8s.io/v1alpha1",
+      kind: "Sandbox",
+      metadata: { name: "pc-abc", namespace: "paperclip-acme" },
+    };
+    const result = await createSandboxCr(clients as never, "paperclip-acme", manifest);
+    expect(create).toHaveBeenCalledWith({
+      group: SANDBOX_GROUP,
+      version: SANDBOX_VERSION,
+      namespace: "paperclip-acme",
+      plural: SANDBOX_PLURAL,
+      body: manifest,
+    });
+    expect(result.uid).toBe("test-uid");
+  });
+
+  it("throws if the API response has no UID", async () => {
+    const create = vi.fn().mockResolvedValue({ metadata: {} });
+    const clients = { custom: { createNamespacedCustomObject: create } };
+    await expect(
+      createSandboxCr(clients as never, "ns", {}),
+    ).rejects.toThrow("Sandbox CR created without a UID");
+  });
+});
+
+describe("getSandboxCrStatus", () => {
+  it("maps phase=Ready to SandboxStatus.phase=Running with active=1", async () => {
+    const get = vi.fn().mockResolvedValue(makeCr("Ready"));
+    const clients = { custom: { getNamespacedCustomObject: get } };
+    const status = await getSandboxCrStatus(clients as never, "ns", "pc-abc");
+    expect(status.phase).toBe("Running");
+    expect(status.active).toBe(1);
+    expect(status.complete).toBe(false);
+  });
+
+  it("maps phase=Pending to SandboxStatus.phase=Pending", async () => {
+    const get = vi.fn().mockResolvedValue(makeCr("Pending"));
+    const clients = { custom: { getNamespacedCustomObject: get } };
+    const status = await getSandboxCrStatus(clients as never, "ns", "pc-abc");
+    expect(status.phase).toBe("Pending");
+    expect(status.active).toBe(0);
+  });
+
+  it("maps phase=Failed to SandboxStatus.phase=Failed with failed=1", async () => {
+    const get = vi.fn().mockResolvedValue({
+      metadata: { uid: "uid-1" },
+      status: {
+        phase: "Failed",
+        conditions: [
+          { type: "Failed", reason: "ImagePullFailed", message: "no image" },
+        ],
+      },
+    });
+    const clients = { custom: { getNamespacedCustomObject: get } };
+    const status = await getSandboxCrStatus(clients as never, "ns", "pc-abc");
+    expect(status.phase).toBe("Failed");
+    expect(status.failed).toBe(1);
+    expect(status.reason).toBe("ImagePullFailed");
+  });
+
+  it("maps phase=Terminating to SandboxStatus.phase=Running with reason=Terminating", async () => {
+    const get = vi.fn().mockResolvedValue(makeCr("Terminating"));
+    const clients = { custom: { getNamespacedCustomObject: get } };
+    const status = await getSandboxCrStatus(clients as never, "ns", "pc-abc");
+    expect(status.phase).toBe("Running");
+    expect(status.reason).toBe("Terminating");
+  });
+});
+
+describe("findPodForSandbox", () => {
+  it("returns status.podName from the Sandbox CR when set", async () => {
+    const get = vi.fn().mockResolvedValue(makeCr("Ready", "pc-abc-pod-xyz"));
+    const clients = {
+      custom: { getNamespacedCustomObject: get },
+      core: { listNamespacedPod: vi.fn() },
+    };
+    const podName = await findPodForSandbox(clients as never, "ns", "pc-abc");
+    expect(podName).toBe("pc-abc-pod-xyz");
+    // Should NOT have called listNamespacedPod (primary path succeeded)
+    expect(clients.core.listNamespacedPod).not.toHaveBeenCalled();
+  });
+
+  it("falls back to pod listing when status.podName is absent", async () => {
+    const get = vi.fn().mockResolvedValue(makeCr("Pending")); // no podName
+    const list = vi.fn().mockResolvedValue({
+      items: [
+        {
+          metadata: { name: "pc-abc-001", labels: { "paperclip.io/managed-by": "paperclip-k8s-plugin" } },
+          status: { phase: "Running" },
+        },
+      ],
+    });
+    const clients = {
+      custom: { getNamespacedCustomObject: get },
+      core: { listNamespacedPod: list },
+    };
+    const podName = await findPodForSandbox(clients as never, "ns", "pc-abc");
+    // name starts with "pc-abc" → matched by prefix heuristic
+    expect(podName).toBe("pc-abc-001");
+  });
+
+  it("returns null when no pod is found in fallback", async () => {
+    const get = vi.fn().mockResolvedValue(makeCr("Pending"));
+    const list = vi.fn().mockResolvedValue({ items: [] });
+    const clients = {
+      custom: { getNamespacedCustomObject: get },
+      core: { listNamespacedPod: list },
+    };
+    const podName = await findPodForSandbox(clients as never, "ns", "pc-abc");
+    expect(podName).toBeNull();
+  });
+});
+
+describe("deleteSandboxCr", () => {
+  it("calls custom.deleteNamespacedCustomObject with Foreground propagation", async () => {
+    const del = vi.fn().mockResolvedValue({});
+    const clients = { custom: { deleteNamespacedCustomObject: del } };
+    await deleteSandboxCr(clients as never, "ns", "pc-abc");
+    expect(del).toHaveBeenCalledWith(
+      expect.objectContaining({
+        group: SANDBOX_GROUP,
+        version: SANDBOX_VERSION,
+        namespace: "ns",
+        plural: SANDBOX_PLURAL,
+        name: "pc-abc",
+        propagationPolicy: "Foreground",
+      }),
+    );
+  });
+});
+
+describe("waitForSandboxReady", () => {
+  it("resolves immediately when Sandbox is already Ready", async () => {
+    const get = vi.fn().mockResolvedValue(makeCr("Ready"));
+    const clients = { custom: { getNamespacedCustomObject: get } };
+    const status = await waitForSandboxReady(
+      clients as never,
+      "ns",
+      "pc-abc",
+      { timeoutMs: 5000, pollMs: 10 },
+    );
+    expect(status.phase).toBe("Running"); // Ready maps to Running
+    expect(get).toHaveBeenCalledTimes(1);
+  });
+
+  it("polls until Ready", async () => {
+    const get = vi
+      .fn()
+      .mockResolvedValueOnce(makeCr("Pending"))
+      .mockResolvedValueOnce(makeCr("Pending"))
+      .mockResolvedValueOnce(makeCr("Ready"));
+    const clients = { custom: { getNamespacedCustomObject: get } };
+    const status = await waitForSandboxReady(
+      clients as never,
+      "ns",
+      "pc-abc",
+      { timeoutMs: 5000, pollMs: 10 },
+    );
+    expect(status.phase).toBe("Running");
+    expect(get).toHaveBeenCalledTimes(3);
+  });
+
+  it("throws SandboxCrTimeoutError when deadline is exceeded", async () => {
+    const get = vi.fn().mockResolvedValue(makeCr("Pending"));
+    const clients = { custom: { getNamespacedCustomObject: get } };
+    await expect(
+      waitForSandboxReady(clients as never, "ns", "pc-abc", {
+        timeoutMs: 50,
+        pollMs: 10,
+      }),
+    ).rejects.toBeInstanceOf(SandboxCrTimeoutError);
+  });
+
+  it("throws an error describing the failure when Sandbox fails", async () => {
+    const get = vi.fn().mockResolvedValue({
+      metadata: { uid: "u1" },
+      status: { phase: "Failed", conditions: [{ type: "Failed", reason: "OOMKilled" }] },
+    });
+    const clients = { custom: { getNamespacedCustomObject: get } };
+    await expect(
+      waitForSandboxReady(clients as never, "ns", "pc-abc", {
+        timeoutMs: 5000,
+        pollMs: 10,
+      }),
+    ).rejects.toThrow(/failed.*OOMKilled/i);
+  });
+
+  it("fails fast when Sandbox starts terminating before it is ready", async () => {
+    const get = vi.fn().mockResolvedValue(makeCr("Terminating"));
+    const clients = { custom: { getNamespacedCustomObject: get } };
+    await expect(
+      waitForSandboxReady(clients as never, "ns", "pc-abc", {
+        timeoutMs: 5000,
+        pollMs: 10,
+      }),
+    ).rejects.toThrow(/terminating before it became ready/i);
+    expect(get).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/secret-manager.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/secret-manager.test.ts
new file mode 100644
index 00000000..b608c647
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/secret-manager.test.ts
@@ -0,0 +1,68 @@
+import { describe, it, expect, vi } from "vitest";
+import { createPerRunSecret } from "../../src/secret-manager.js";
+
+describe("createPerRunSecret", () => {
+  const baseInput = {
+    namespace: "paperclip-acme",
+    secretName: "r-abcd-env",
+    runId: "r-abcd",
+    ownerKind: "Job",
+    ownerApiVersion: "batch/v1",
+    ownerName: "r-abcd",
+    ownerUid: "11111111-1111-1111-1111-111111111111",
+    bootstrapToken: "tok-xyz",
+    adapterEnv: { ANTHROPIC_API_KEY: "sk-test" },
+  };
+
+  it("creates a Secret with the correct name and namespace", async () => {
+    const created: { body: Record<string, unknown> }[] = [];
+    const clients = {
+      core: { createNamespacedSecret: vi.fn(async (args: { body: Record<string, unknown> }) => { created.push(args); }) },
+    };
+    await createPerRunSecret(clients as never, baseInput);
+    expect(clients.core.createNamespacedSecret).toHaveBeenCalledOnce();
+    const body = created[0].body as { metadata: { name: string; namespace: string } };
+    expect(body.metadata.name).toBe("r-abcd-env");
+    expect(body.metadata.namespace).toBe("paperclip-acme");
+  });
+
+  it("includes BOOTSTRAP_TOKEN and adapter env keys in stringData", async () => {
+    const created: { body: Record<string, unknown> }[] = [];
+    const clients = {
+      core: { createNamespacedSecret: vi.fn(async (args: { body: Record<string, unknown> }) => { created.push(args); }) },
+    };
+    await createPerRunSecret(clients as never, baseInput);
+    const body = created[0].body as { stringData: Record<string, string> };
+    expect(body.stringData.BOOTSTRAP_TOKEN).toBe("tok-xyz");
+    expect(body.stringData.ANTHROPIC_API_KEY).toBe("sk-test");
+  });
+
+  it("sets ownerReferences to the owner resource for cascade delete", async () => {
+    const created: { body: Record<string, unknown> }[] = [];
+    const clients = {
+      core: { createNamespacedSecret: vi.fn(async (args: { body: Record<string, unknown> }) => { created.push(args); }) },
+    };
+    await createPerRunSecret(clients as never, baseInput);
+    const body = created[0].body as { metadata: { ownerReferences: { uid: string; controller: boolean }[] } };
+    expect(body.metadata.ownerReferences).toHaveLength(1);
+    expect(body.metadata.ownerReferences[0].uid).toBe("11111111-1111-1111-1111-111111111111");
+    expect(body.metadata.ownerReferences[0].controller).toBe(true);
+  });
+
+  it("throws if adapterEnv contains BOOTSTRAP_TOKEN", async () => {
+    const clients = { core: { createNamespacedSecret: vi.fn() } };
+    await expect(
+      createPerRunSecret(clients as never, {
+        ...baseInput,
+        adapterEnv: { BOOTSTRAP_TOKEN: "evil" },
+      }),
+    ).rejects.toThrow(/BOOTSTRAP_TOKEN/);
+  });
+
+  it("throws if ownerUid is empty", async () => {
+    const clients = { core: { createNamespacedSecret: vi.fn() } };
+    await expect(
+      createPerRunSecret(clients as never, { ...baseInput, ownerUid: "" }),
+    ).rejects.toThrow(/ownerUid/);
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/tenant-orchestrator.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/tenant-orchestrator.test.ts
new file mode 100644
index 00000000..4696fa1a
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/tenant-orchestrator.test.ts
@@ -0,0 +1,219 @@
+import { describe, it, expect, vi } from "vitest";
+import { ensureTenant } from "../../src/tenant-orchestrator.js";
+
+function makeMockClients() {
+  const calls: { kind: string; name: string; namespace?: string; body?: unknown }[] = [];
+  function track(kind: string) {
+    return vi.fn(async (...args: unknown[]) => {
+      const arg = (args[0] ?? {}) as { name?: string; namespace?: string; body?: unknown };
+      calls.push({ kind, name: arg.name ?? "", namespace: arg.namespace, body: arg.body });
+      return { body: arg.body };
+    });
+  }
+  return {
+    calls,
+    core: {
+      createNamespace: track("Namespace"),
+      readNamespacedServiceAccount: vi.fn().mockRejectedValue({ code: 404 }),
+      createNamespacedServiceAccount: track("ServiceAccount"),
+      replaceNamespacedServiceAccount: track("ServiceAccountReplace"),
+      readNamespacedResourceQuota: vi.fn().mockRejectedValue({ code: 404 }),
+      createNamespacedResourceQuota: track("ResourceQuota"),
+      replaceNamespacedResourceQuota: track("ResourceQuotaReplace"),
+      readNamespacedLimitRange: vi.fn().mockRejectedValue({ code: 404 }),
+      createNamespacedLimitRange: track("LimitRange"),
+      replaceNamespacedLimitRange: track("LimitRangeReplace"),
+      readNamespace: vi.fn().mockRejectedValue({ code: 404 }),
+      replaceNamespace: track("NamespaceReplace"),
+    },
+    rbac: {
+      readNamespacedRole: vi.fn().mockRejectedValue({ code: 404 }),
+      createNamespacedRole: track("Role"),
+      replaceNamespacedRole: track("RoleReplace"),
+      readNamespacedRoleBinding: vi.fn().mockRejectedValue({ code: 404 }),
+      createNamespacedRoleBinding: track("RoleBinding"),
+      replaceNamespacedRoleBinding: track("RoleBindingReplace"),
+    },
+    networking: {
+      readNamespacedNetworkPolicy: vi.fn().mockRejectedValue({ code: 404 }),
+      createNamespacedNetworkPolicy: track("NetworkPolicy"),
+      replaceNamespacedNetworkPolicy: track("NetworkPolicyReplace"),
+      deleteNamespacedNetworkPolicy: vi.fn().mockRejectedValue({ code: 404 }),
+    },
+    custom: {
+      getNamespacedCustomObject: vi.fn().mockRejectedValue({ code: 404 }),
+      createNamespacedCustomObject: track("CiliumNetworkPolicy"),
+      replaceNamespacedCustomObject: track("CiliumNetworkPolicyReplace"),
+      deleteNamespacedCustomObject: vi.fn().mockRejectedValue({ code: 404 }),
+    },
+  };
+}
+
+describe("ensureTenant", () => {
+  const baseInput = {
+    namespace: "paperclip-acme",
+    companyId: "11111111-1111-1111-1111-111111111111",
+    paperclipServerNamespace: "paperclip",
+    serviceAccountAnnotations: {},
+    egressMode: "standard" as const,
+    egressAllowFqdns: ["api.anthropic.com"],
+    egressAllowCidrs: [] as string[],
+    resourceQuota: { pods: "20", requestsCpu: "5", requestsMemory: "20Gi", limitsCpu: "20", limitsMemory: "80Gi" },
+  };
+
+  it("creates all required resources in the correct order on a fresh tenant", async () => {
+    const clients = makeMockClients();
+    await ensureTenant(clients as never, baseInput);
+    const order = clients.calls.map((c) => c.kind);
+    expect(order).toEqual([
+      "Namespace",
+      "ServiceAccount",
+      "Role",
+      "RoleBinding",
+      "ResourceQuota",
+      "LimitRange",
+      "NetworkPolicy",
+      "NetworkPolicy",
+    ]);
+  });
+
+  it("creates a CiliumNetworkPolicy instead of standard egress when egressMode=cilium", async () => {
+    const clients = makeMockClients();
+    await ensureTenant(clients as never, { ...baseInput, egressMode: "cilium" });
+    const cnpCall = clients.calls.find((c) => c.kind === "CiliumNetworkPolicy");
+    expect(cnpCall).toBeDefined();
+    const npCalls = clients.calls.filter((c) => c.kind === "NetworkPolicy");
+    expect(npCalls).toHaveLength(1);
+    expect((npCalls[0].body as { metadata: { name: string } }).metadata.name).toBe("paperclip-deny-all");
+  });
+
+  it("applies serviceAccountAnnotations to the ServiceAccount", async () => {
+    const clients = makeMockClients();
+    await ensureTenant(clients as never, {
+      ...baseInput,
+      serviceAccountAnnotations: { "eks.amazonaws.com/role-arn": "arn:aws:iam::123:role/paperclip" },
+    });
+    const saCall = clients.calls.find((c) => c.kind === "ServiceAccount");
+    const sa = saCall!.body as { metadata: { annotations: Record<string, string> } };
+    expect(sa.metadata.annotations["eks.amazonaws.com/role-arn"]).toBe("arn:aws:iam::123:role/paperclip");
+  });
+
+  it("reconciles a namespace that already exists", async () => {
+    const clients = makeMockClients();
+    clients.core.readNamespace.mockResolvedValue({
+      metadata: {
+        name: baseInput.namespace,
+        resourceVersion: "rv-namespace",
+        labels: { "operator.example.com/team": "infra" },
+      },
+    });
+    await ensureTenant(clients as never, baseInput);
+    expect(clients.core.createNamespace).not.toHaveBeenCalled();
+    expect(clients.core.replaceNamespace).toHaveBeenCalledWith({
+      name: baseInput.namespace,
+      body: expect.objectContaining({
+        metadata: expect.objectContaining({
+          resourceVersion: "rv-namespace",
+          labels: expect.objectContaining({
+            "operator.example.com/team": "infra",
+            "paperclip.io/company-id": baseInput.companyId,
+            "paperclip.io/managed-by": "paperclip-k8s-plugin",
+            "pod-security.kubernetes.io/enforce": "restricted",
+            "pod-security.kubernetes.io/audit": "restricted",
+            "pod-security.kubernetes.io/warn": "restricted",
+          }),
+        }),
+      }),
+    });
+  });
+
+  it("reconciles existing managed resources with the latest desired manifests", async () => {
+    const clients = makeMockClients();
+    const existing = { metadata: { resourceVersion: "rv-1" } };
+    clients.core.readNamespace.mockResolvedValue({ metadata: { name: baseInput.namespace, resourceVersion: "rv-ns" } });
+    clients.core.readNamespacedServiceAccount.mockResolvedValue(existing);
+    clients.rbac.readNamespacedRole.mockResolvedValue(existing);
+    clients.rbac.readNamespacedRoleBinding.mockResolvedValue(existing);
+    clients.core.readNamespacedResourceQuota.mockResolvedValue(existing);
+    clients.core.readNamespacedLimitRange.mockResolvedValue(existing);
+    clients.networking.readNamespacedNetworkPolicy.mockResolvedValue(existing);
+
+    await ensureTenant(clients as never, {
+      ...baseInput,
+      serviceAccountAnnotations: { "eks.amazonaws.com/role-arn": "arn:aws:iam::123:role/paperclip" },
+      resourceQuota: { ...baseInput.resourceQuota, pods: "25" },
+    });
+
+    expect(clients.core.replaceNamespacedServiceAccount).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: expect.objectContaining({
+          metadata: expect.objectContaining({
+            annotations: { "eks.amazonaws.com/role-arn": "arn:aws:iam::123:role/paperclip" },
+            resourceVersion: "rv-1",
+          }),
+        }),
+      }),
+    );
+    expect(clients.core.replaceNamespacedResourceQuota).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: expect.objectContaining({
+          metadata: expect.objectContaining({ resourceVersion: "rv-1" }),
+          spec: expect.objectContaining({ hard: expect.objectContaining({ pods: "25" }) }),
+        }),
+      }),
+    );
+    expect(clients.networking.replaceNamespacedNetworkPolicy).toHaveBeenCalled();
+    expect(clients.core.replaceNamespace).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: expect.objectContaining({
+          metadata: expect.objectContaining({
+            resourceVersion: "rv-ns",
+            labels: expect.objectContaining({
+              "pod-security.kubernetes.io/enforce": "restricted",
+            }),
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("removes stale standard egress NetworkPolicy when cilium mode is selected", async () => {
+    const clients = makeMockClients();
+    await ensureTenant(clients as never, { ...baseInput, egressMode: "cilium" });
+    expect(clients.networking.deleteNamespacedNetworkPolicy).toHaveBeenCalledWith({
+      namespace: baseInput.namespace,
+      name: "paperclip-egress-allow",
+    });
+  });
+
+  it("handles concurrent first-run create conflicts by rereading and replacing managed resources", async () => {
+    const clients = makeMockClients();
+    const existing = { metadata: { resourceVersion: "rv-race" } };
+    clients.core.createNamespace.mockRejectedValueOnce({ code: 409 });
+    clients.core.readNamespace
+      .mockRejectedValueOnce({ code: 404 })
+      .mockResolvedValue({ metadata: { resourceVersion: "rv-namespace-race" } });
+    clients.core.readNamespacedServiceAccount
+      .mockRejectedValueOnce({ code: 404 })
+      .mockResolvedValue(existing);
+    clients.core.createNamespacedServiceAccount.mockRejectedValueOnce({ code: 409 });
+
+    await ensureTenant(clients as never, baseInput);
+
+    expect(clients.core.createNamespace).toHaveBeenCalled();
+    expect(clients.core.replaceNamespace).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: expect.objectContaining({
+          metadata: expect.objectContaining({ resourceVersion: "rv-namespace-race" }),
+        }),
+      }),
+    );
+    expect(clients.core.replaceNamespacedServiceAccount).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: expect.objectContaining({
+          metadata: expect.objectContaining({ resourceVersion: "rv-race" }),
+        }),
+      }),
+    );
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/types.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/types.test.ts
new file mode 100644
index 00000000..4ac57443
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/types.test.ts
@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import { kubernetesProviderConfigSchema, parseKubernetesProviderConfig } from "../../src/types.js";
+
+describe("kubernetesProviderConfigSchema", () => {
+  it("accepts inCluster=true with no kubeconfig", () => {
+    const parsed = parseKubernetesProviderConfig({ inCluster: true });
+    expect(parsed.inCluster).toBe(true);
+    expect(parsed.namespacePrefix).toBe("paperclip-");
+    expect(parsed.paperclipServerNamespace).toBe("paperclip");
+    expect(parsed.imageAllowList).toEqual([]);
+    expect(parsed.egressMode).toBe("standard");
+    expect(parsed.jobTtlSecondsAfterFinished).toBe(900);
+  });
+
+  it("accepts inline kubeconfig", () => {
+    const parsed = parseKubernetesProviderConfig({
+      inCluster: false,
+      kubeconfig: "apiVersion: v1\nkind: Config\n",
+    });
+    expect(parsed.kubeconfig).toContain("apiVersion");
+  });
+
+  it("rejects when neither inCluster nor any kubeconfig source is set", () => {
+    expect(() => parseKubernetesProviderConfig({ inCluster: false })).toThrow(
+      /requires one of `inCluster` or `kubeconfig`/,
+    );
+  });
+
+  it("rejects invalid companySlug", () => {
+    expect(() =>
+      parseKubernetesProviderConfig({ inCluster: true, companySlug: "INVALID UPPER" }),
+    ).toThrow();
+  });
+
+  it("bounds namespacePrefix and companySlug so their combination fits a Kubernetes namespace", () => {
+    expect(() =>
+      parseKubernetesProviderConfig({ inCluster: true, namespacePrefix: "a".repeat(21) }),
+    ).toThrow();
+    expect(() =>
+      parseKubernetesProviderConfig({ inCluster: true, companySlug: "a".repeat(44) }),
+    ).toThrow();
+  });
+
+  it("accepts a custom paperclip-server namespace", () => {
+    const parsed = parseKubernetesProviderConfig({
+      inCluster: true,
+      paperclipServerNamespace: "paperclip-prod",
+    });
+    expect(parsed.paperclipServerNamespace).toBe("paperclip-prod");
+  });
+
+  it("rejects invalid paperclip-server namespace values", () => {
+    for (const namespace of ["Paperclip", "paperclip_", "-paperclip", "paperclip-"]) {
+      expect(() =>
+        parseKubernetesProviderConfig({
+          inCluster: true,
+          paperclipServerNamespace: namespace,
+        }),
+      ).toThrow();
+    }
+  });
+
+  it("rejects whitespace-only kubeconfig", () => {
+    expect(() =>
+      parseKubernetesProviderConfig({ inCluster: false, kubeconfig: "   " }),
+    ).toThrow(/requires one of `inCluster` or `kubeconfig`/);
+  });
+
+  it("rejects egressAllowCidrs entries that are not valid CIDR", () => {
+    expect(() =>
+      parseKubernetesProviderConfig({ inCluster: true, egressAllowCidrs: ["not-a-cidr"] }),
+    ).toThrow(/CIDR/i);
+  });
+
+  it("rejects CIDRs with invalid octets or prefixes", () => {
+    for (const cidr of ["999.0.0.0/8", "10.0.0.0/99", "10.0.0/24"]) {
+      expect(() =>
+        parseKubernetesProviderConfig({ inCluster: true, egressAllowCidrs: [cidr] }),
+      ).toThrow(/CIDR/i);
+    }
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/upload-interceptor.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/upload-interceptor.test.ts
new file mode 100644
index 00000000..e93ff3fb
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/upload-interceptor.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import { FastUploadInterceptor } from "../../src/upload-interceptor.js";
+
+describe("FastUploadInterceptor", () => {
+  it("collapses the adapter-utils chunked upload protocol into one flush", () => {
+    const interceptor = new FastUploadInterceptor();
+    const target = "/workspace/.paperclip-runtime/skills.tar";
+    const chunkA = Buffer.from("hello ").toString("base64").slice(0, 4);
+    const chunkB = Buffer.from("hello ").toString("base64").slice(4) + Buffer.from("world").toString("base64");
+
+    expect(
+      interceptor.decide(
+        `mkdir -p '/workspace/.paperclip-runtime' && rm -f '${target}.paperclip-upload.b64' && : > '${target}.paperclip-upload.b64'`,
+      ),
+    ).toMatchObject({ action: "ack" });
+    expect(interceptor.pendingCount).toBe(1);
+
+    expect(
+      interceptor.decide(`printf '%s' '${chunkA}' >> '${target}.paperclip-upload.b64'`),
+    ).toMatchObject({ action: "ack" });
+    expect(
+      interceptor.decide(`printf '%s' '${chunkB}' >> '${target}.paperclip-upload.b64'`),
+    ).toMatchObject({ action: "ack" });
+
+    const decision = interceptor.decide(
+      `base64 -d < '${target}.paperclip-upload.b64' > '${target}' && rm -f '${target}.paperclip-upload.b64'`,
+    );
+    expect(decision.action).toBe("flush");
+    if (decision.action !== "flush") throw new Error("expected flush");
+    expect(decision.flush.targetPath).toBe(target);
+    expect(decision.flush.payload.toString("utf8")).toBe("hello world");
+    expect(interceptor.pendingCount).toBe(0);
+  });
+
+  it("passes through chunks and finalizers without a matching init", () => {
+    const interceptor = new FastUploadInterceptor();
+    const target = "/workspace/file.bin";
+
+    expect(
+      interceptor.decide(`printf '%s' 'aGVsbG8=' >> '${target}.paperclip-upload.b64'`),
+    ).toMatchObject({ action: "passthrough", reason: "chunk without prior init" });
+    expect(
+      interceptor.decide(
+        `base64 -d < '${target}.paperclip-upload.b64' > '${target}' && rm -f '${target}.paperclip-upload.b64'`,
+      ),
+    ).toMatchObject({ action: "passthrough", reason: "finalize without buffered state" });
+  });
+
+  it("fails fast when an unrecognized command targets an active upload", () => {
+    const interceptor = new FastUploadInterceptor();
+    const target = "/workspace/file.bin";
+
+    expect(
+      interceptor.decide(
+        `mkdir -p '/workspace' && rm -f '${target}.paperclip-upload.b64' && : > '${target}.paperclip-upload.b64'`,
+      ),
+    ).toMatchObject({ action: "ack" });
+
+    const decision = interceptor.decide(`printf '%s' 'aGVs=bG8=' >> '${target}.paperclip-upload.b64'`);
+    expect(decision).toMatchObject({
+      action: "error",
+      message: expect.stringContaining("Fast upload protocol violation"),
+    });
+    expect(interceptor.pendingCount).toBe(0);
+  });
+
+  it("fails fast when data arrives after a padded chunk", () => {
+    const interceptor = new FastUploadInterceptor();
+    const target = "/workspace/file.bin";
+
+    expect(
+      interceptor.decide(
+        `mkdir -p '/workspace' && rm -f '${target}.paperclip-upload.b64' && : > '${target}.paperclip-upload.b64'`,
+      ),
+    ).toMatchObject({ action: "ack" });
+    expect(
+      interceptor.decide(`printf '%s' 'aGVs=' >> '${target}.paperclip-upload.b64'`),
+    ).toMatchObject({ action: "ack" });
+
+    const decision = interceptor.decide(`printf '%s' 'bG8=' >> '${target}.paperclip-upload.b64'`);
+    expect(decision).toMatchObject({
+      action: "error",
+      message: expect.stringContaining("received data after a padded chunk"),
+    });
+    expect(interceptor.pendingCount).toBe(0);
+  });
+
+  it("falls through when the init command does not match the target parent directory", () => {
+    const interceptor = new FastUploadInterceptor();
+
+    expect(
+      interceptor.decide(
+        "mkdir -p '/tmp' && rm -f '/workspace/file.bin.paperclip-upload.b64' && : > '/workspace/file.bin.paperclip-upload.b64'",
+      ),
+    ).toMatchObject({ action: "passthrough", reason: "init dir/target mismatch" });
+    expect(interceptor.pendingCount).toBe(0);
+  });
+
+  it("fails fast instead of falling through after acknowledged chunks exceed the buffer cap", () => {
+    const interceptor = new FastUploadInterceptor(1);
+    const target = "/workspace/file.bin";
+
+    expect(
+      interceptor.decide(
+        `mkdir -p '/workspace' && rm -f '${target}.paperclip-upload.b64' && : > '${target}.paperclip-upload.b64'`,
+      ),
+    ).toMatchObject({ action: "ack" });
+
+    const decision = interceptor.decide(`printf '%s' 'AAAA' >> '${target}.paperclip-upload.b64'`);
+    expect(decision).toMatchObject({
+      action: "error",
+      message: expect.stringContaining("Fast upload buffer cap exceeded"),
+    });
+    expect(interceptor.pendingCount).toBe(0);
+  });
+
+  it("fails fast when init repeats for an in-progress upload", () => {
+    const interceptor = new FastUploadInterceptor();
+    const target = "/workspace/file.bin";
+    const initCommand =
+      `mkdir -p '/workspace' && rm -f '${target}.paperclip-upload.b64' && : > '${target}.paperclip-upload.b64'`;
+
+    expect(interceptor.decide(initCommand)).toMatchObject({ action: "ack" });
+    expect(
+      interceptor.decide(`printf '%s' 'aGVsbG8=' >> '${target}.paperclip-upload.b64'`),
+    ).toMatchObject({ action: "ack" });
+
+    const decision = interceptor.decide(initCommand);
+    expect(decision).toMatchObject({
+      action: "error",
+      message: expect.stringContaining("Fast upload already in progress"),
+    });
+    expect(interceptor.pendingCount).toBe(0);
+  });
+
+  it("clears buffered uploads on reset", () => {
+    const interceptor = new FastUploadInterceptor();
+    const target = "/workspace/file.bin";
+
+    interceptor.decide(
+      `mkdir -p '/workspace' && rm -f '${target}.paperclip-upload.b64' && : > '${target}.paperclip-upload.b64'`,
+    );
+    expect(interceptor.pendingCount).toBe(1);
+
+    interceptor.reset();
+    expect(interceptor.pendingCount).toBe(0);
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/test/unit/utils.test.ts b/packages/plugins/sandbox-providers/kubernetes/test/unit/utils.test.ts
new file mode 100644
index 00000000..fd844a06
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/test/unit/utils.test.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect, vi } from "vitest";
+import { deriveCompanySlug, deriveNamespaceName, newRunUlidDns, paperclipLabels } from "../../src/utils.js";
+
+describe("deriveCompanySlug", () => {
+  it("lowercases and replaces non-alphanumerics", () => {
+    expect(deriveCompanySlug("Acme Co!")).toBe("acme-co");
+  });
+
+  it("truncates to 32 chars and strips trailing dashes", () => {
+    expect(deriveCompanySlug("A".repeat(50))).toBe("a".repeat(32));
+    expect(deriveCompanySlug("ab---")).toBe("ab");
+  });
+
+  it("falls back to 'company' on empty/zero-letter input", () => {
+    expect(deriveCompanySlug("!!!")).toBe("company");
+    expect(deriveCompanySlug("")).toBe("company");
+  });
+});
+
+describe("deriveNamespaceName", () => {
+  it("concatenates prefix and slug", () => {
+    expect(deriveNamespaceName("paperclip-", "acme-co")).toBe("paperclip-acme-co");
+  });
+});
+
+describe("newRunUlidDns", () => {
+  it("produces a DNS-safe 26-char lowercase id", () => {
+    const id = newRunUlidDns();
+    expect(id).toMatch(/^[a-z0-9]{26}$/);
+  });
+
+  it("does not use Math.random for the random suffix", () => {
+    const spy = vi.spyOn(Math, "random");
+    newRunUlidDns(() => 1);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe("paperclipLabels", () => {
+  it("returns canonical label map", () => {
+    const labels = paperclipLabels({ runId: "r1", agentId: "a1", companyId: "c1", adapterType: "claude_local" });
+    expect(labels["paperclip.io/run-id"]).toBe("r1");
+    expect(labels["paperclip.io/agent-id"]).toBe("a1");
+    expect(labels["paperclip.io/company-id"]).toBe("c1");
+    expect(labels["paperclip.io/adapter"]).toBe("claude_local");
+    expect(labels["paperclip.io/managed-by"]).toBe("paperclip-k8s-plugin");
+  });
+});
diff --git a/packages/plugins/sandbox-providers/kubernetes/tsconfig.json b/packages/plugins/sandbox-providers/kubernetes/tsconfig.json
new file mode 100644
index 00000000..000e3293
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2023"],
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}
diff --git a/packages/plugins/sandbox-providers/kubernetes/vitest.config.ts b/packages/plugins/sandbox-providers/kubernetes/vitest.config.ts
new file mode 100644
index 00000000..dc447fb7
--- /dev/null
+++ b/packages/plugins/sandbox-providers/kubernetes/vitest.config.ts
@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: [
+      "test/unit/**/*.test.ts",
+      ...(process.env.RUN_K8S_INTEGRATION_TESTS === "1" ? ["test/integration/**/*.test.ts"] : []),
+    ],
+    testTimeout: process.env.RUN_K8S_INTEGRATION_TESTS === "1" ? 120_000 : 5_000,
+    environment: "node",
+  },
+});
diff --git a/packages/plugins/sdk/src/ui/components.ts b/packages/plugins/sdk/src/ui/components.ts
index c148fc80..b075506c 100644
--- a/packages/plugins/sdk/src/ui/components.ts
+++ b/packages/plugins/sdk/src/ui/components.ts
@@ -420,6 +420,12 @@ export interface ManagedRoutineMissingRef {
   resourceKey: string;
 }
 
+export interface ManagedRoutineDefaultDrift {
+  changedFields: string[];
+  defaultTitle?: string | null;
+  defaultDescription?: string | null;
+}
+
 export interface ManagedRoutinesListItem {
   key: string;
   title: string;
@@ -434,6 +440,7 @@ export interface ManagedRoutinesListItem {
   lastRunStatus?: string | null;
   managedByPluginDisplayName?: string | null;
   missingRefs?: ManagedRoutineMissingRef[];
+  defaultDrift?: ManagedRoutineDefaultDrift | null;
 }
 
 export interface ManagedRoutinesListProps {
diff --git a/packages/plugins/sdk/src/worker-rpc-host.ts b/packages/plugins/sdk/src/worker-rpc-host.ts
index 81104fea..643f9b0d 100644
--- a/packages/plugins/sdk/src/worker-rpc-host.ts
+++ b/packages/plugins/sdk/src/worker-rpc-host.ts
@@ -34,6 +34,7 @@
  * @see PLUGIN_SPEC.md §14 — SDK Surface
  */
 
+import fs from "node:fs";
 import path from "node:path";
 import { createInterface, type Interface as ReadlineInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
@@ -175,6 +176,21 @@ interface EventRegistration {
 /** Default timeout for worker→host RPC calls. */
 const DEFAULT_RPC_TIMEOUT_MS = 30_000;
 
+function realpathOrResolvedPath(filePath: string): string {
+  const resolvedPath = path.resolve(filePath);
+  try {
+    return fs.realpathSync.native(resolvedPath);
+  } catch {
+    return resolvedPath;
+  }
+}
+
+export function isWorkerEntrypoint(entry: string, moduleUrl: string): boolean {
+  const thisFile = realpathOrResolvedPath(fileURLToPath(moduleUrl));
+  const entryPath = realpathOrResolvedPath(entry);
+  return thisFile === entryPath;
+}
+
 // ---------------------------------------------------------------------------
 // startWorkerRpcHost
 // ---------------------------------------------------------------------------
@@ -223,9 +239,7 @@ export function runWorker(
   }
   const entry = process.argv[1];
   if (typeof entry !== "string") return;
-  const thisFile = path.resolve(fileURLToPath(moduleUrl));
-  const entryPath = path.resolve(entry);
-  if (thisFile === entryPath) {
+  if (isWorkerEntrypoint(entry, moduleUrl)) {
     startWorkerRpcHost({ plugin });
   }
 }
diff --git a/packages/plugins/sdk/tests/worker-rpc-host.test.ts b/packages/plugins/sdk/tests/worker-rpc-host.test.ts
new file mode 100644
index 00000000..f8e0a38e
--- /dev/null
+++ b/packages/plugins/sdk/tests/worker-rpc-host.test.ts
@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { isWorkerEntrypoint } from "../src/worker-rpc-host.js";
+
+describe("isWorkerEntrypoint", () => {
+  const tempRoots: string[] = [];
+
+  afterEach(() => {
+    for (const tempRoot of tempRoots.splice(0)) {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  function createTempRoot(): string {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-sdk-worker-"));
+    tempRoots.push(tempRoot);
+    return tempRoot;
+  }
+
+  it("matches an entrypoint reached through a symlinked directory", () => {
+    const tempRoot = createTempRoot();
+    const realDir = path.join(tempRoot, "real");
+    const linkDir = path.join(tempRoot, "link");
+    fs.mkdirSync(realDir);
+    fs.symlinkSync(realDir, linkDir, "dir");
+
+    const workerPath = path.join(realDir, "worker.js");
+    fs.writeFileSync(workerPath, "");
+
+    expect(
+      isWorkerEntrypoint(
+        path.join(linkDir, "worker.js"),
+        pathToFileURL(workerPath).toString(),
+      ),
+    ).toBe(true);
+  });
+
+  it("does not match a different entrypoint", () => {
+    const tempRoot = createTempRoot();
+    const workerPath = path.join(tempRoot, "worker.js");
+    const otherPath = path.join(tempRoot, "other.js");
+    fs.writeFileSync(workerPath, "");
+    fs.writeFileSync(otherPath, "");
+
+    expect(
+      isWorkerEntrypoint(
+        otherPath,
+        pathToFileURL(workerPath).toString(),
+      ),
+    ).toBe(false);
+  });
+});
diff --git a/packages/plugins/sdk/vitest.config.ts b/packages/plugins/sdk/vitest.config.ts
new file mode 100644
index 00000000..faa6d98e
--- /dev/null
+++ b/packages/plugins/sdk/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["tests/**/*.test.ts"],
+  },
+});
diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.ts
index ea93a3b6..c2f8f807 100644
--- a/packages/shared/src/constants.ts
+++ b/packages/shared/src/constants.ts
@@ -215,6 +215,40 @@ export type IssueOriginKind = BuiltInIssueOriginKind | PluginIssueOriginKind;
 export const ISSUE_SURFACE_VISIBILITIES = ["default", "plugin_operation"] as const;
 export type IssueSurfaceVisibility = (typeof ISSUE_SURFACE_VISIBILITIES)[number];
 
+export const ISSUE_RECOVERY_ACTION_KINDS = [
+  "missing_disposition",
+  "stranded_assigned_issue",
+  "active_run_watchdog",
+  "issue_graph_liveness",
+] as const;
+export type IssueRecoveryActionKind = (typeof ISSUE_RECOVERY_ACTION_KINDS)[number];
+
+export const ISSUE_RECOVERY_ACTION_STATUSES = [
+  "active",
+  "escalated",
+  "resolved",
+  "cancelled",
+] as const;
+export type IssueRecoveryActionStatus = (typeof ISSUE_RECOVERY_ACTION_STATUSES)[number];
+
+export const ISSUE_RECOVERY_ACTION_OWNER_TYPES = [
+  "agent",
+  "user",
+  "board",
+  "system",
+] as const;
+export type IssueRecoveryActionOwnerType = (typeof ISSUE_RECOVERY_ACTION_OWNER_TYPES)[number];
+
+export const ISSUE_RECOVERY_ACTION_OUTCOMES = [
+  "restored",
+  "delegated",
+  "false_positive",
+  "blocked",
+  "escalated",
+  "cancelled",
+] as const;
+export type IssueRecoveryActionOutcome = (typeof ISSUE_RECOVERY_ACTION_OUTCOMES)[number];
+
 export function pluginOperationIssueOriginKind(pluginKey: string): PluginIssueOriginKind {
   return `plugin:${pluginKey}:operation`;
 }
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 1010c096..6f3dfe35 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -31,6 +31,10 @@ export {
   ISSUE_THREAD_INTERACTION_CONTINUATION_POLICIES,
   ISSUE_ORIGIN_KINDS,
   ISSUE_SURFACE_VISIBILITIES,
+  ISSUE_RECOVERY_ACTION_KINDS,
+  ISSUE_RECOVERY_ACTION_STATUSES,
+  ISSUE_RECOVERY_ACTION_OWNER_TYPES,
+  ISSUE_RECOVERY_ACTION_OUTCOMES,
   pluginOperationIssueOriginKind,
   isPluginOperationIssueOriginKind,
   ISSUE_RELATION_TYPES,
@@ -149,6 +153,10 @@ export {
   type PluginIssueOriginKind,
   type IssueOriginKind,
   type IssueSurfaceVisibility,
+  type IssueRecoveryActionKind,
+  type IssueRecoveryActionStatus,
+  type IssueRecoveryActionOwnerType,
+  type IssueRecoveryActionOutcome,
   type IssueRelationType,
   type IssueTreeControlMode,
   type IssueTreeHoldReleasePolicyStrategy,
@@ -371,8 +379,18 @@ export type {
   IssueBlockerAttention,
   IssueBlockerAttentionReason,
   IssueBlockerAttentionState,
+  IssueInboxAttentionKind,
+  IssueBlockedInboxAction,
+  IssueBlockedInboxAttention,
+  IssueBlockedInboxIssueRef,
+  IssueBlockedInboxOwner,
+  IssueBlockedInboxOwnerType,
+  IssueBlockedInboxReason,
+  IssueBlockedInboxSeverity,
+  IssueBlockedInboxState,
   IssueProductivityReview,
   IssueProductivityReviewTrigger,
+  IssueRecoveryAction,
   SuccessfulRunHandoffState,
   SuccessfulRunHandoffStateKind,
   IssueScheduledRetry,
@@ -753,9 +771,15 @@ export {
   createChildIssueSchema,
   resolveCreateIssueStatusDefault,
   createIssueLabelSchema,
+  issueBlockedInboxAttentionSchema,
+  issueBlockedInboxIssueRefSchema,
+  issueBlockedInboxReasonSchema,
+  issueBlockedInboxSeveritySchema,
+  issueBlockedInboxStateSchema,
   updateIssueSchema,
   issueExecutionPolicySchema,
   issueExecutionStateSchema,
+  resolveIssueRecoveryActionSchema,
   issueReviewRequestSchema,
   issueExecutionWorkspaceSettingsSchema,
   checkoutIssueSchema,
@@ -815,6 +839,7 @@ export {
   type CreateChildIssue,
   type CreateIssueLabel,
   type UpdateIssue,
+  type ResolveIssueRecoveryAction,
   type CheckoutIssue,
   type AddIssueComment,
   type CreateIssueThreadInteraction,
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
index b6c4e69e..5b80e35f 100644
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@@ -149,8 +149,18 @@ export type {
   IssueBlockerAttention,
   IssueBlockerAttentionReason,
   IssueBlockerAttentionState,
+  IssueInboxAttentionKind,
+  IssueBlockedInboxAction,
+  IssueBlockedInboxAttention,
+  IssueBlockedInboxIssueRef,
+  IssueBlockedInboxOwner,
+  IssueBlockedInboxOwnerType,
+  IssueBlockedInboxReason,
+  IssueBlockedInboxSeverity,
+  IssueBlockedInboxState,
   IssueProductivityReview,
   IssueProductivityReviewTrigger,
+  IssueRecoveryAction,
   SuccessfulRunHandoffState,
   SuccessfulRunHandoffStateKind,
   IssueScheduledRetry,
diff --git a/packages/shared/src/types/issue.ts b/packages/shared/src/types/issue.ts
index 827c259f..7bbdde36 100644
--- a/packages/shared/src/types/issue.ts
+++ b/packages/shared/src/types/issue.ts
@@ -15,6 +15,10 @@ import type {
   IssueExecutionStateStatus,
   IssueOriginKind,
   IssuePriority,
+  IssueRecoveryActionKind,
+  IssueRecoveryActionOutcome,
+  IssueRecoveryActionOwnerType,
+  IssueRecoveryActionStatus,
   IssueWorkMode,
   ModelProfileKey,
   IssueThreadInteractionContinuationPolicy,
@@ -131,6 +135,7 @@ export interface IssueRelationIssueSummary {
   assigneeAgentId: string | null;
   assigneeUserId: string | null;
   terminalBlockers?: IssueRelationIssueSummary[];
+  activeRecoveryAction?: IssueRecoveryAction | null;
 }
 
 export type IssueBlockerAttentionState = "none" | "covered" | "stalled" | "needs_attention";
@@ -153,6 +158,75 @@ export interface IssueBlockerAttention {
   sampleStalledBlockerIdentifier: string | null;
 }
 
+export type IssueInboxAttentionKind = "blocked";
+
+export type IssueBlockedInboxState =
+  | "needs_attention"
+  | "awaiting_decision"
+  | "external_wait"
+  | "recovery_open"
+  | "missing_disposition";
+
+export type IssueBlockedInboxSeverity = "critical" | "high" | "medium" | "low";
+
+export type IssueBlockedInboxReason =
+  | "blocked_by_unassigned_issue"
+  | "blocked_by_assigned_backlog_issue"
+  | "blocked_by_uninvokable_assignee"
+  | "blocked_by_cancelled_issue"
+  | "blocked_chain_stalled"
+  | "invalid_review_participant"
+  | "in_review_without_action_path"
+  | "missing_successful_run_disposition"
+  | "pending_board_decision"
+  | "pending_user_decision"
+  | "external_owner_action"
+  | "open_recovery_issue";
+
+export type IssueBlockedInboxOwnerType = "agent" | "user" | "board" | "external" | "unknown";
+
+export interface IssueBlockedInboxIssueRef {
+  id: string;
+  identifier: string | null;
+  title: string;
+  status: IssueStatus;
+  priority: IssuePriority;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+}
+
+export interface IssueBlockedInboxOwner {
+  type: IssueBlockedInboxOwnerType;
+  agentId: string | null;
+  userId: string | null;
+  label: string | null;
+}
+
+export interface IssueBlockedInboxAction {
+  label: string;
+  detail: string | null;
+}
+
+export interface IssueBlockedInboxAttention {
+  kind: IssueInboxAttentionKind;
+  state: IssueBlockedInboxState;
+  reason: IssueBlockedInboxReason;
+  severity: IssueBlockedInboxSeverity;
+  stoppedSinceAt: string | null;
+  owner: IssueBlockedInboxOwner;
+  action: IssueBlockedInboxAction;
+  sourceIssue: IssueBlockedInboxIssueRef | null;
+  leafIssue: IssueBlockedInboxIssueRef | null;
+  recoveryIssue: IssueBlockedInboxIssueRef | null;
+  approvalId: string | null;
+  interactionId: string | null;
+  sampleIssueIdentifier: string | null;
+  redaction: {
+    externalDetailsRedacted: boolean;
+    secretFieldsOmitted: true;
+  };
+}
+
 export type IssueProductivityReviewTrigger =
   | "no_comment_streak"
   | "long_active_duration"
@@ -169,6 +243,35 @@ export interface IssueProductivityReview {
   updatedAt: Date;
 }
 
+export interface IssueRecoveryAction {
+  id: string;
+  companyId: string;
+  sourceIssueId: string;
+  recoveryIssueId: string | null;
+  kind: IssueRecoveryActionKind;
+  status: IssueRecoveryActionStatus;
+  ownerType: IssueRecoveryActionOwnerType;
+  ownerAgentId: string | null;
+  ownerUserId: string | null;
+  previousOwnerAgentId: string | null;
+  returnOwnerAgentId: string | null;
+  cause: string;
+  fingerprint: string;
+  evidence: Record<string, unknown>;
+  nextAction: string;
+  wakePolicy: Record<string, unknown> | null;
+  monitorPolicy: Record<string, unknown> | null;
+  attemptCount: number;
+  maxAttempts: number | null;
+  timeoutAt: Date | string | null;
+  lastAttemptAt: Date | string | null;
+  outcome: IssueRecoveryActionOutcome | null;
+  resolutionNote: string | null;
+  resolvedAt: Date | string | null;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+}
+
 export type SuccessfulRunHandoffStateKind = "required" | "resolved" | "escalated";
 
 export interface SuccessfulRunHandoffState {
@@ -371,7 +474,9 @@ export interface Issue {
   blockedBy?: IssueRelationIssueSummary[];
   blocks?: IssueRelationIssueSummary[];
   blockerAttention?: IssueBlockerAttention;
+  blockedInboxAttention?: IssueBlockedInboxAttention | null;
   productivityReview?: IssueProductivityReview | null;
+  activeRecoveryAction?: IssueRecoveryAction | null;
   successfulRunHandoff?: SuccessfulRunHandoffState | null;
   scheduledRetry?: IssueScheduledRetry | null;
   relatedWork?: IssueRelatedWorkSummary;
@@ -399,6 +504,10 @@ export interface IssueComment {
   authorType: IssueCommentAuthorType;
   authorAgentId: string | null;
   authorUserId: string | null;
+  createdByRunId?: string | null;
+  derivedAuthorAgentId?: string | null;
+  derivedCreatedByRunId?: string | null;
+  derivedAuthorSource?: "run_log_comment_post" | null;
   body: string;
   presentation: IssueCommentPresentation | null;
   metadata: IssueCommentMetadata | null;
diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.ts
index 8ac8ba53..16a3eef6 100644
--- a/packages/shared/src/validators/index.ts
+++ b/packages/shared/src/validators/index.ts
@@ -155,9 +155,16 @@ export {
   createChildIssueSchema,
   resolveCreateIssueStatusDefault,
   createIssueLabelSchema,
+  issueBlockedInboxAttentionSchema,
+  issueBlockedInboxIssueRefSchema,
+  issueBlockedInboxReasonSchema,
+  issueBlockedInboxSeveritySchema,
+  issueBlockedInboxStateSchema,
   updateIssueSchema,
   issueExecutionPolicySchema,
   issueExecutionStateSchema,
+  issueRecoveryActionReadModelSchema,
+  resolveIssueRecoveryActionSchema,
   issueReviewRequestSchema,
   issueExecutionWorkspaceSettingsSchema,
   checkoutIssueSchema,
@@ -200,6 +207,8 @@ export {
   type CreateIssueLabel,
   type UpdateIssue,
   type IssueExecutionWorkspaceSettings,
+  type IssueRecoveryActionReadModel,
+  type ResolveIssueRecoveryAction,
   type CheckoutIssue,
   type AddIssueComment,
   type CreateIssueThreadInteraction,
diff --git a/packages/shared/src/validators/issue.test.ts b/packages/shared/src/validators/issue.test.ts
index ba5cd73c..0d8374ec 100644
--- a/packages/shared/src/validators/issue.test.ts
+++ b/packages/shared/src/validators/issue.test.ts
@@ -3,6 +3,8 @@ import { MAX_ISSUE_REQUEST_DEPTH } from "../index.js";
 import {
   addIssueCommentSchema,
   createIssueSchema,
+  issueBlockedInboxAttentionSchema,
+  resolveIssueRecoveryActionSchema,
   respondIssueThreadInteractionSchema,
   suggestedTaskDraftSchema,
   updateIssueSchema,
@@ -46,6 +48,70 @@ describe("issue validators", () => {
     expect(parsed.comment).toBe("Done\n\n- Verified the route");
   });
 
+  it("allows false-positive recovery resolutions to atomically restore the source issue status", () => {
+    expect(
+      resolveIssueRecoveryActionSchema.parse({
+        outcome: "false_positive",
+        sourceIssueStatus: "in_review",
+      }),
+    ).toMatchObject({
+      outcome: "false_positive",
+      sourceIssueStatus: "in_review",
+    });
+
+    expect(
+      resolveIssueRecoveryActionSchema.safeParse({
+        outcome: "false_positive",
+        sourceIssueStatus: "blocked",
+      }).success,
+    ).toBe(false);
+
+    expect(
+      resolveIssueRecoveryActionSchema.safeParse({
+        outcome: "false_positive",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("allows cancelled recovery resolutions to atomically restore the source issue status", () => {
+    expect(
+      resolveIssueRecoveryActionSchema.parse({
+        outcome: "cancelled",
+        sourceIssueStatus: "in_review",
+      }),
+    ).toMatchObject({
+      outcome: "cancelled",
+      sourceIssueStatus: "in_review",
+    });
+
+    expect(
+      resolveIssueRecoveryActionSchema.safeParse({
+        outcome: "cancelled",
+        sourceIssueStatus: "blocked",
+      }).success,
+    ).toBe(false);
+
+    expect(
+      resolveIssueRecoveryActionSchema.safeParse({
+        outcome: "cancelled",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects recovery outcomes that are not supported by the source-scoped resolution endpoint", () => {
+    expect(
+      resolveIssueRecoveryActionSchema.safeParse({
+        outcome: "delegated",
+      }).success,
+    ).toBe(false);
+
+    expect(
+      resolveIssueRecoveryActionSchema.safeParse({
+        outcome: "escalated",
+      }).success,
+    ).toBe(false);
+  });
+
   it("normalizes escaped line breaks in issue comment bodies", () => {
     const parsed = addIssueCommentSchema.parse({
       body: "Progress update\\r\\n\\r\\nNext action.",
@@ -153,6 +219,50 @@ describe("issue validators", () => {
     }).workMode).toBe("planning");
   });
 
+  it("validates blocked inbox attention payloads and requires redacted secret fields", () => {
+    const parsed = issueBlockedInboxAttentionSchema.parse({
+      kind: "blocked",
+      state: "needs_attention",
+      reason: "blocked_by_unassigned_issue",
+      severity: "critical",
+      stoppedSinceAt: "2026-05-09T12:00:00.000Z",
+      owner: { type: "unknown", agentId: null, userId: null, label: null },
+      action: { label: "Assign blocker", detail: "Assign the leaf blocker." },
+      sourceIssue: {
+        id: "11111111-1111-4111-8111-111111111111",
+        identifier: "PAP-1",
+        title: "Blocked source",
+        status: "blocked",
+        priority: "high",
+        assigneeAgentId: null,
+        assigneeUserId: null,
+      },
+      leafIssue: {
+        id: "22222222-2222-4222-8222-222222222222",
+        identifier: "PAP-2",
+        title: "Unassigned leaf",
+        status: "todo",
+        priority: "medium",
+        assigneeAgentId: null,
+        assigneeUserId: null,
+      },
+      recoveryIssue: null,
+      approvalId: null,
+      interactionId: null,
+      sampleIssueIdentifier: "PAP-2",
+      redaction: {
+        externalDetailsRedacted: false,
+        secretFieldsOmitted: true,
+      },
+    });
+
+    expect(parsed.redaction.secretFieldsOmitted).toBe(true);
+    expect(issueBlockedInboxAttentionSchema.safeParse({
+      ...parsed,
+      redaction: { externalDetailsRedacted: false, secretFieldsOmitted: false },
+    }).success).toBe(false);
+  });
+
   it("rejects unknown issue work modes", () => {
     expect(createIssueSchema.safeParse({ title: "Plan first", workMode: "normal" }).success).toBe(false);
     expect(suggestedTaskDraftSchema.safeParse({
diff --git a/packages/shared/src/validators/issue.ts b/packages/shared/src/validators/issue.ts
index 0f73f4d9..b39fe7f8 100644
--- a/packages/shared/src/validators/issue.ts
+++ b/packages/shared/src/validators/issue.ts
@@ -14,6 +14,10 @@ import {
   ISSUE_COMMENT_PRESENTATION_TONES,
   ISSUE_MONITOR_SCHEDULED_BY,
   ISSUE_PRIORITIES,
+  ISSUE_RECOVERY_ACTION_KINDS,
+  ISSUE_RECOVERY_ACTION_OUTCOMES,
+  ISSUE_RECOVERY_ACTION_OWNER_TYPES,
+  ISSUE_RECOVERY_ACTION_STATUSES,
   ISSUE_WORK_MODES,
   clampIssueRequestDepth,
   ISSUE_STATUSES,
@@ -24,6 +28,69 @@ import {
 } from "../constants.js";
 import { multilineTextSchema } from "./text.js";
 
+export const issueBlockedInboxStateSchema = z.enum([
+  "needs_attention",
+  "awaiting_decision",
+  "external_wait",
+  "recovery_open",
+  "missing_disposition",
+]);
+
+export const issueBlockedInboxSeveritySchema = z.enum(["critical", "high", "medium", "low"]);
+
+export const issueBlockedInboxReasonSchema = z.enum([
+  "blocked_by_unassigned_issue",
+  "blocked_by_assigned_backlog_issue",
+  "blocked_by_uninvokable_assignee",
+  "blocked_by_cancelled_issue",
+  "blocked_chain_stalled",
+  "invalid_review_participant",
+  "in_review_without_action_path",
+  "missing_successful_run_disposition",
+  "pending_board_decision",
+  "pending_user_decision",
+  "external_owner_action",
+  "open_recovery_issue",
+]);
+
+export const issueBlockedInboxIssueRefSchema = z.object({
+  id: z.string().uuid(),
+  identifier: z.string().nullable(),
+  title: z.string(),
+  status: z.enum(ISSUE_STATUSES),
+  priority: z.enum(ISSUE_PRIORITIES),
+  assigneeAgentId: z.string().uuid().nullable(),
+  assigneeUserId: z.string().nullable(),
+}).strict();
+
+export const issueBlockedInboxAttentionSchema = z.object({
+  kind: z.literal("blocked"),
+  state: issueBlockedInboxStateSchema,
+  reason: issueBlockedInboxReasonSchema,
+  severity: issueBlockedInboxSeveritySchema,
+  stoppedSinceAt: z.string().datetime().nullable(),
+  owner: z.object({
+    type: z.enum(["agent", "user", "board", "external", "unknown"]),
+    agentId: z.string().uuid().nullable(),
+    userId: z.string().nullable(),
+    label: z.string().nullable(),
+  }).strict(),
+  action: z.object({
+    label: z.string().trim().min(1),
+    detail: z.string().nullable(),
+  }).strict(),
+  sourceIssue: issueBlockedInboxIssueRefSchema.nullable(),
+  leafIssue: issueBlockedInboxIssueRefSchema.nullable(),
+  recoveryIssue: issueBlockedInboxIssueRefSchema.nullable(),
+  approvalId: z.string().uuid().nullable(),
+  interactionId: z.string().uuid().nullable(),
+  sampleIssueIdentifier: z.string().nullable(),
+  redaction: z.object({
+    externalDetailsRedacted: z.boolean(),
+    secretFieldsOmitted: z.literal(true),
+  }).strict(),
+}).strict();
+
 export const ISSUE_EXECUTION_WORKSPACE_PREFERENCES = [
   "inherit",
   "shared_workspace",
@@ -167,6 +234,89 @@ export const issueExecutionStateSchema = z.object({
   monitor: issueExecutionMonitorStateSchema.optional().nullable(),
 });
 
+export const issueRecoveryActionReadModelSchema = z.object({
+  id: z.string().uuid(),
+  companyId: z.string().uuid(),
+  sourceIssueId: z.string().uuid(),
+  recoveryIssueId: z.string().uuid().nullable(),
+  kind: z.enum(ISSUE_RECOVERY_ACTION_KINDS),
+  status: z.enum(ISSUE_RECOVERY_ACTION_STATUSES),
+  ownerType: z.enum(ISSUE_RECOVERY_ACTION_OWNER_TYPES),
+  ownerAgentId: z.string().uuid().nullable(),
+  ownerUserId: z.string().nullable(),
+  previousOwnerAgentId: z.string().uuid().nullable(),
+  returnOwnerAgentId: z.string().uuid().nullable(),
+  cause: z.string().min(1),
+  fingerprint: z.string().min(1),
+  evidence: z.record(z.unknown()),
+  nextAction: z.string().min(1),
+  wakePolicy: z.record(z.unknown()).nullable(),
+  monitorPolicy: z.record(z.unknown()).nullable(),
+  attemptCount: z.number().int().nonnegative(),
+  maxAttempts: z.number().int().positive().nullable(),
+  timeoutAt: z.union([z.date(), z.string().datetime()]).nullable(),
+  lastAttemptAt: z.union([z.date(), z.string().datetime()]).nullable(),
+  outcome: z.enum(ISSUE_RECOVERY_ACTION_OUTCOMES).nullable(),
+  resolutionNote: z.string().nullable(),
+  resolvedAt: z.union([z.date(), z.string().datetime()]).nullable(),
+  createdAt: z.union([z.date(), z.string().datetime()]),
+  updatedAt: z.union([z.date(), z.string().datetime()]),
+});
+
+export type IssueRecoveryActionReadModel = z.infer<typeof issueRecoveryActionReadModelSchema>;
+
+const RESOLVE_ISSUE_RECOVERY_ACTION_OUTCOMES = [
+  "restored",
+  "false_positive",
+  "blocked",
+  "cancelled",
+] as const;
+
+export const resolveIssueRecoveryActionSchema = z.object({
+  actionId: z.string().uuid().optional(),
+  outcome: z.enum(RESOLVE_ISSUE_RECOVERY_ACTION_OUTCOMES),
+  sourceIssueStatus: z.enum(["done", "in_review", "blocked"]),
+  resolutionNote: multilineTextSchema.optional().nullable(),
+}).strict().superRefine((value, ctx) => {
+  if (value.outcome === "restored") {
+    if (value.sourceIssueStatus !== "done" && value.sourceIssueStatus !== "in_review") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Restored recovery actions must move the source issue to done or in_review",
+        path: ["sourceIssueStatus"],
+      });
+    }
+    return;
+  }
+
+  if (value.outcome === "blocked") {
+    if (value.sourceIssueStatus !== "blocked") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Blocked recovery actions must move the source issue to blocked",
+        path: ["sourceIssueStatus"],
+      });
+    }
+    return;
+  }
+
+  if (value.outcome === "false_positive" || value.outcome === "cancelled") {
+    if (
+      value.sourceIssueStatus !== "done" &&
+      value.sourceIssueStatus !== "in_review"
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "This recovery outcome requires sourceIssueStatus to be done or in_review",
+        path: ["sourceIssueStatus"],
+      });
+    }
+    return;
+  }
+});
+
+export type ResolveIssueRecoveryAction = z.infer<typeof resolveIssueRecoveryActionSchema>;
+
 const issueRequestDepthInputSchema = z
   .number()
   .int()
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index eb6b8fbf..cbacb527 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -494,6 +494,49 @@ importers:
         specifier: ^3.2.4
         version: 3.2.4(@types/debug@4.1.12)(@types/node@24.12.0)(jiti@2.6.1)(jsdom@28.1.0(@noble/hashes@2.0.1))(lightningcss@1.30.2)(tsx@4.21.0)
 
+  packages/plugins/plugin-llm-wiki:
+    dependencies:
+      react:
+        specifier: '>=18'
+        version: 19.2.4
+    devDependencies:
+      '@paperclipai/plugin-sdk':
+        specifier: workspace:*
+        version: link:../sdk
+      '@rollup/plugin-node-resolve':
+        specifier: ^16.0.1
+        version: 16.0.3(rollup@4.60.1)
+      '@rollup/plugin-typescript':
+        specifier: ^12.1.2
+        version: 12.3.0(rollup@4.60.1)(tslib@2.8.1)(typescript@5.9.3)
+      '@types/node':
+        specifier: ^24.6.0
+        version: 24.12.0
+      '@types/react':
+        specifier: ^19.0.8
+        version: 19.2.14
+      '@types/react-dom':
+        specifier: ^19.0.3
+        version: 19.2.3(@types/react@19.2.14)
+      esbuild:
+        specifier: ^0.27.3
+        version: 0.27.3
+      react-dom:
+        specifier: ^19.0.0
+        version: 19.2.4(react@19.2.4)
+      rollup:
+        specifier: '>=4.59.0'
+        version: 4.60.1
+      tslib:
+        specifier: ^2.8.1
+        version: 2.8.1
+      typescript:
+        specifier: ^5.7.3
+        version: 5.9.3
+      vitest:
+        specifier: ^3.0.5
+        version: 3.2.4(@types/debug@4.1.12)(@types/node@24.12.0)(jiti@2.6.1)(jsdom@28.1.0(@noble/hashes@2.0.1))(lightningcss@1.30.2)(tsx@4.21.0)
+
   packages/plugins/sdk:
     dependencies:
       '@paperclipai/shared':
@@ -603,9 +646,15 @@ importers:
       hermes-paperclip-adapter:
         specifier: ^0.2.0
         version: 0.2.0
+      isomorphic-git:
+        specifier: ^1.38.0
+        version: 1.38.0
       jsdom:
         specifier: ^28.1.0
         version: 28.1.0(@noble/hashes@2.0.1)
+      memfs:
+        specifier: ^4.57.2
+        version: 4.57.2(tslib@2.8.1)
       multer:
         specifier: ^2.1.1
         version: 2.1.1
@@ -2203,6 +2252,126 @@ packages:
   '@jridgewell/trace-mapping@0.3.31':
     resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
 
+  '@jsonjoy.com/base64@1.1.2':
+    resolution: {integrity: sha512-q6XAnWQDIMA3+FTiOYajoYqySkO+JSat0ytXGSuRdq9uXE7o92gzuQwQM14xaCRlBLGq3v5miDGC4vkVTn54xA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/base64@17.67.0':
+    resolution: {integrity: sha512-5SEsJGsm15aP8TQGkDfJvz9axgPwAEm98S5DxOuYe8e1EbfajcDmgeXXzccEjh+mLnjqEKrkBdjHWS5vFNwDdw==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/buffers@1.2.1':
+    resolution: {integrity: sha512-12cdlDwX4RUM3QxmUbVJWqZ/mrK6dFQH4Zxq6+r1YXKXYBNgZXndx2qbCJwh3+WWkCSn67IjnlG3XYTvmvYtgA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/buffers@17.67.0':
+    resolution: {integrity: sha512-tfExRpYxBvi32vPs9ZHaTjSP4fHAfzSmcahOfNxtvGHcyJel+aibkPlGeBB+7AoC6hL7lXIE++8okecBxx7lcw==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/codegen@1.0.0':
+    resolution: {integrity: sha512-E8Oy+08cmCf0EK/NMxpaJZmOxPqM+6iSe2S4nlSBrPZOORoDJILxtbSUEDKQyTamm/BVAhIGllOBNU79/dwf0g==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/codegen@17.67.0':
+    resolution: {integrity: sha512-idnkUplROpdBOV0HMcwhsCUS5TRUi9poagdGs70A6S4ux9+/aPuKbh8+UYRTLYQHtXvAdNfQWXDqZEx5k4Dj2Q==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-core@4.57.2':
+    resolution: {integrity: sha512-SVjwklkpIV5wrynpYtuYnfYH1QF4/nDuLBX7VXdb+3miglcAgBVZb/5y0cOsehRV/9Vb+3UqhkMq3/NR3ztdkQ==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-fsa@4.57.2':
+    resolution: {integrity: sha512-fhO8+iR2I+OCw668ISDJdn1aArc9zx033sWejIyzQ8RBeXa9bDSaUeA3ix0poYOfrj1KdOzytmYNv2/uLDfV6g==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-node-builtins@4.57.2':
+    resolution: {integrity: sha512-xhiegylRmhw43Ki2HO1ZBL7DQ5ja/qpRsL29VtQ2xuUHiuDGbgf2uD4p9Qd8hJI5P6RCtGYD50IXHXVq/Ocjcg==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-node-to-fsa@4.57.2':
+    resolution: {integrity: sha512-18LmWTSONhoAPW+IWRuf8w/+zRolPFGPeGwMxlAhhfY11EKzX+5XHDBPAw67dBF5dxDErHJbl40U+3IXSDRXSQ==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-node-utils@4.57.2':
+    resolution: {integrity: sha512-rsPSJgekz43IlNbLyAM/Ab+ouYLWGp5DDBfYBNNEqDaSpsbXfthBn29Q4muFA9L0F+Z3mKo+CWlgSCXrf+mOyQ==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-node@4.57.2':
+    resolution: {integrity: sha512-nX2AdL6cOFwLdju9G4/nbRnYevmCJbh7N7hvR3gGm97Cs60uEjyd0rpR+YBS7cTg175zzl22pGKXR5USaQMvKg==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-print@4.57.2':
+    resolution: {integrity: sha512-wK9NSow48i4DbDl9F1CQE5TqnyZOJ04elU3WFG5aJ76p+YxO/ulyBBQvKsessPxdo381Bc2pcEoyPujMOhcRqQ==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-snapshot@4.57.2':
+    resolution: {integrity: sha512-GdduDZuoP5V/QCgJkx9+BZ6SC0EZ/smXAdTS7PfMqgMTGXLlt/bH/FqMYaqB9JmLf05sJPtO0XRbAwwkEEPbVw==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/json-pack@1.21.0':
+    resolution: {integrity: sha512-+AKG+R2cfZMShzrF2uQw34v3zbeDYUqnQ+jg7ORic3BGtfw9p/+N6RJbq/kkV8JmYZaINknaEQ2m0/f693ZPpg==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/json-pack@17.67.0':
+    resolution: {integrity: sha512-t0ejURcGaZsn1ClbJ/3kFqSOjlryd92eQY465IYrezsXmPcfHPE/av4twRSxf6WE+TkZgLY+71vCZbiIiFKA/w==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/json-pointer@1.0.2':
+    resolution: {integrity: sha512-Fsn6wM2zlDzY1U+v4Nc8bo3bVqgfNTGcn6dMgs6FjrEnt4ZCe60o6ByKRjOGlI2gow0aE/Q41QOigdTqkyK5fg==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/json-pointer@17.67.0':
+    resolution: {integrity: sha512-+iqOFInH+QZGmSuaybBUNdh7yvNrXvqR+h3wjXm0N/3JK1EyyFAeGJvqnmQL61d1ARLlk/wJdFKSL+LHJ1eaUA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/util@1.9.0':
+    resolution: {integrity: sha512-pLuQo+VPRnN8hfPqUTLTHk126wuYdXVxE6aDmjSeV4NCAgyxWbiOIeNJVtID3h1Vzpoi9m4jXezf73I6LgabgQ==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/util@17.67.0':
+    resolution: {integrity: sha512-6+8xBaz1rLSohlGh68D1pdw3AwDi9xydm8QNlAFkvnavCJYSze+pxoW2VKP8p308jtlMRLs5NTHfPlZLd4w7ew==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
   '@lexical/clipboard@0.35.0':
     resolution: {integrity: sha512-ko7xSIIiayvDiqjNDX6fgH9RlcM6r9vrrvJYTcfGVBor5httx16lhIi0QJZ4+RNPvGtTjyFv4bwRmsixRRwImg==}
 
@@ -4024,6 +4193,10 @@ packages:
   abbrev@1.1.1:
     resolution: {integrity: sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q==}
 
+  abort-controller@3.0.0:
+    resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
+    engines: {node: '>=6.5'}
+
   accepts@2.0.0:
     resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
     engines: {node: '>= 0.6'}
@@ -4131,6 +4304,9 @@ packages:
     resolution: {integrity: sha512-NW2cX8m1Q7KPA7a5M2ULQeZ2wR5qI5PAbw5L0UOMxdioVk9PMZ0h1TmyZEkPYrCvYjDlFICusOu1dlEKAAeXBw==}
     engines: {node: '>=0.12.0'}
 
+  async-lock@1.4.1:
+    resolution: {integrity: sha512-Az2ZTpuytrtqENulXwO3GGv1Bztugx6TT37NIo7imr/Qo0gsYiGtSdBa2B6fsXhTpVZDNfu1Qn3pk531e3q+nQ==}
+
   asynckit@0.4.0:
     resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
 
@@ -4138,6 +4314,10 @@ packages:
     resolution: {integrity: sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==}
     engines: {node: '>=8.0.0'}
 
+  available-typed-arrays@1.0.7:
+    resolution: {integrity: sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==}
+    engines: {node: '>= 0.4'}
+
   axe-core@4.11.3:
     resolution: {integrity: sha512-zBQouZixDTbo3jMGqHKyePxYxr1e5W8UdTmBQ7sNtaA9M2bE32daxxPLS/jojhKOHxQ7LWwPjfiwf/fhaJWzlg==}
     engines: {node: '>=4'}
@@ -4339,6 +4519,10 @@ packages:
     resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==}
     engines: {node: '>= 0.4'}
 
+  call-bind@1.0.9:
+    resolution: {integrity: sha512-a/hy+pNsFUTR+Iz8TCJvXudKVLAnz/DyeSUo10I5yvFDQJBFU2s9uqQpoSrJlroHUKoKqzg+epxyP9lqFdzfBQ==}
+    engines: {node: '>= 0.4'}
+
   call-bound@1.0.4:
     resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==}
     engines: {node: '>= 0.4'}
@@ -4394,6 +4578,9 @@ packages:
   classnames@2.5.1:
     resolution: {integrity: sha512-saHYOzhIQs6wy2sVxTM6bUDsQO4F50V9RQ22qBpEdCW+I+/Wmke2HOl6lS6dTpdxVhb88/I6+Hs+438c3lfUow==}
 
+  clean-git-ref@2.0.1:
+    resolution: {integrity: sha512-bLSptAy2P0s6hU4PzuIMKmMJJSE6gLXGH1cntDu7bWJUksvuM+7ReOK61mozULErYvP6a15rnYl0zFDef+pyPw==}
+
   clean-set@1.1.2:
     resolution: {integrity: sha512-cA8uCj0qSoG9e0kevyOWXwPaELRPVg5Pxp6WskLMwerx257Zfnh8Nl0JBH59d7wQzij2CK7qEfJQK3RjuKKIug==}
 
@@ -4507,6 +4694,11 @@ packages:
   cose-base@2.2.0:
     resolution: {integrity: sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==}
 
+  crc-32@1.2.2:
+    resolution: {integrity: sha512-ROmzCKrTnOwybPcJApAA6WBWij23HVfGVNKqqrZpuyZOHqK2CwHSvpGuyt/UNNvaIjEd8X5IFGp4Mh+Ie1IHJQ==}
+    engines: {node: '>=0.8'}
+    hasBin: true
+
   crelt@1.0.6:
     resolution: {integrity: sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g==}
 
@@ -4747,6 +4939,10 @@ packages:
     resolution: {integrity: sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw==}
     engines: {node: '>=18'}
 
+  define-data-property@1.1.4:
+    resolution: {integrity: sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==}
+    engines: {node: '>= 0.4'}
+
   define-lazy-prop@3.0.0:
     resolution: {integrity: sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==}
     engines: {node: '>=12'}
@@ -4790,6 +4986,9 @@ packages:
   dezalgo@1.0.4:
     resolution: {integrity: sha512-rXSP0bf+5n0Qonsb+SVVfNfIsimO4HEtmnIpPHY8Q1UCzKlQrDMfdobr8nJOOsRgWCyMRqeSBQzmWUMq7zvVig==}
 
+  diff3@0.0.3:
+    resolution: {integrity: sha512-iSq8ngPOt0K53A6eVr4d5Kn6GNrM2nQZtC740pzIriHtn4pOQ2lyzEXQMBeVcWERN0ye7fhBsk9PbLLQOnUx/g==}
+
   diff@5.2.2:
     resolution: {integrity: sha512-vtcDfH3TOjP8UekytvnHH1o1P4FcUdt4eQ1Y+Abap1tk/OB2MWQvcwS2ClCd1zuIhc3JKOx6p3kod8Vfys3E+A==}
     engines: {node: '>=0.3.1'}
@@ -5059,9 +5258,17 @@ packages:
   event-emitter@0.3.5:
     resolution: {integrity: sha512-D9rRn9y7kLPnJ+hMq7S/nhvoKwwvVJahBi2BPmx3bvbsEdK3W9ii8cBSGjP+72/LnM4n6fo3+dkCX5FeTQruXA==}
 
+  event-target-shim@5.0.1:
+    resolution: {integrity: sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==}
+    engines: {node: '>=6'}
+
   events-universal@1.0.1:
     resolution: {integrity: sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw==}
 
+  events@3.3.0:
+    resolution: {integrity: sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==}
+    engines: {node: '>=0.8.x'}
+
   eventsource-parser@3.0.6:
     resolution: {integrity: sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==}
     engines: {node: '>=18.0.0'}
@@ -5141,6 +5348,10 @@ packages:
     resolution: {integrity: sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==}
     engines: {node: '>= 18.0.0'}
 
+  for-each@0.3.5:
+    resolution: {integrity: sha512-dKx12eRCVIzqCxFGplyFKJMPvLEWgmNtUrpTiJIR5u97zEhRG8ySrtboPHZXx7daLxQVrl643cTzbab2tkQjxg==}
+    engines: {node: '>= 0.4'}
+
   form-data@4.0.5:
     resolution: {integrity: sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==}
     engines: {node: '>= 6'}
@@ -5215,6 +5426,12 @@ packages:
   github-from-package@0.0.0:
     resolution: {integrity: sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==}
 
+  glob-to-regex.js@1.2.0:
+    resolution: {integrity: sha512-QMwlOQKU/IzqMUOAZWubUOT8Qft+Y0KQWnX9nK3ch0CJg0tTp4TvGZsTfudYKv2NzoQSyPcnA6TYeIQ3jGichQ==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
   glob@13.0.6:
     resolution: {integrity: sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==}
     engines: {node: 18 || 20 || >=22}
@@ -5233,6 +5450,9 @@ packages:
   hachure-fill@0.5.2:
     resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
 
+  has-property-descriptors@1.0.2:
+    resolution: {integrity: sha512-55JNKuIW+vq4Ke1BjOTjM2YctQIvCT7GFzHwmfZPGo5wnrgkid0YQtnAleFSqumZm4az3n2BS+erby5ipJdgrg==}
+
   has-symbols@1.1.0:
     resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==}
     engines: {node: '>= 0.4'}
@@ -5298,6 +5518,10 @@ packages:
   humanize-ms@1.2.1:
     resolution: {integrity: sha512-Fl70vYtsAFb/C06PTS9dZBo7ihau+Tu/DNCk/OyHhea07S+aeMWpFFkUaXRa8fI+ScZbEI8dfSxwY7gxZ9SAVQ==}
 
+  hyperdyperid@1.2.0:
+    resolution: {integrity: sha512-Y93lCzHYgGWdrJ66yIktxiaGULYc6oGiABxhcO5AufBeOyoIdZF7bIfLaOrbM0iGIOXQQgxxRrFEnb+Y6w1n4A==}
+    engines: {node: '>=10.18'}
+
   iconv-lite@0.6.3:
     resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
     engines: {node: '>=0.10.0'}
@@ -5309,6 +5533,10 @@ packages:
   ieee754@1.2.1:
     resolution: {integrity: sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==}
 
+  ignore@5.3.2:
+    resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
+    engines: {node: '>= 4'}
+
   imurmurhash@0.1.4:
     resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
     engines: {node: '>=0.8.19'}
@@ -5362,6 +5590,10 @@ packages:
   is-alphanumerical@2.0.1:
     resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==}
 
+  is-callable@1.2.7:
+    resolution: {integrity: sha512-1BC0BVFhS/p0qtw6enp8e+8OD0UrK0oFLztSjNzhcKA3WDuJxxAPXzPuPtKkjEY9UUoEWlX/8fgKeu2S8i9JTA==}
+    engines: {node: '>= 0.4'}
+
   is-core-module@2.16.1:
     resolution: {integrity: sha512-UfoeMA6fIJ8wTYFEUjelnaGI67v6+N7qXJEvQuIGa99l4xsCruSYOVSQ0uPANn4dAzm8lkYPaKLrrijLq7x23w==}
     engines: {node: '>= 0.4'}
@@ -5406,13 +5638,25 @@ packages:
   is-promise@4.0.0:
     resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
 
+  is-typed-array@1.1.15:
+    resolution: {integrity: sha512-p3EcsicXjit7SaskXHs1hA91QxgTw46Fv6EFKKGS5DRFLD8yKnohjF3hxoju94b/OcMZoQukzpPpBE9uLVKzgQ==}
+    engines: {node: '>= 0.4'}
+
   is-wsl@3.1.1:
     resolution: {integrity: sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==}
     engines: {node: '>=16'}
 
+  isarray@2.0.5:
+    resolution: {integrity: sha512-xHjhDr3cNBK0BzdUJSPXZntQUx/mwMS5Rw4A7lPJ90XGAO6ISP/ePDNuo0vhqOZU+UD5JoodwCAAoZQd3FeAKw==}
+
   isexe@2.0.0:
     resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
 
+  isomorphic-git@1.38.0:
+    resolution: {integrity: sha512-gsBFnAT8Fxrpx+53ymG5kEOHSrUDVcSMFl7fCEGVnPpQbPS0aKti3UzZXR+3DKA0yyf+4z6CXJxULlQ5QPxDJw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
   isomorphic.js@0.2.5:
     resolution: {integrity: sha512-PIeMbHqMt4DnUP3MA/Flc0HElYjMXArsw1qwJZcm9sqR8mq3l8NYizFMty0pWwE/tzIGH3EKK5+jes5mAr85yw==}
 
@@ -5689,6 +5933,11 @@ packages:
     resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
     engines: {node: '>= 0.8'}
 
+  memfs@4.57.2:
+    resolution: {integrity: sha512-2nWzSsJzrukurSDna4Z0WywuScK4Id3tSKejgu74u8KCdW4uNrseKRSIDg75C6Yw5ZRqBe0F0EtMNlTbUq8bAQ==}
+    peerDependencies:
+      tslib: '2'
+
   merge-descriptors@2.0.0:
     resolution: {integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==}
     engines: {node: '>=18'}
@@ -5853,6 +6102,9 @@ packages:
   minimist@1.2.8:
     resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
 
+  minimisted@2.0.1:
+    resolution: {integrity: sha512-1oPjfuLQa2caorJUM8HV8lGgWCc0qqAO1MNv/k05G4qslmsndV/5WdNZrqCiyqiz3wohia2Ij2B7w2Dr7/IyrA==}
+
   minipass-collect@1.0.2:
     resolution: {integrity: sha512-6T6lH0H8OG9kITm/Jm6tdooIbogG9e0tLgpY6mphXSm/A9u8Nq1ryBG+Qspiub9LjWlBPsPS3tWQ/Botq4FdxA==}
     engines: {node: '>= 8'}
@@ -6001,6 +6253,9 @@ packages:
   package-manager-detector@1.6.0:
     resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
 
+  pako@1.0.11:
+    resolution: {integrity: sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==}
+
   parse-entities@4.0.2:
     resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
 
@@ -6083,6 +6338,10 @@ packages:
     resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==}
     engines: {node: '>=12'}
 
+  pify@4.0.1:
+    resolution: {integrity: sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==}
+    engines: {node: '>=6'}
+
   pino-abstract-transport@2.0.0:
     resolution: {integrity: sha512-F63x5tizV6WCh4R6RHyi2Ml+M70DNRXt/+HANowMflpgGFMAym/VKm6G7ZOQRjqN7XbGxK1Lg9t6ZrtzOaivMw==}
 
@@ -6126,6 +6385,10 @@ packages:
   points-on-path@0.2.1:
     resolution: {integrity: sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==}
 
+  possible-typed-array-names@1.1.0:
+    resolution: {integrity: sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg==}
+    engines: {node: '>= 0.4'}
+
   postcss-selector-parser@6.0.10:
     resolution: {integrity: sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==}
     engines: {node: '>=4'}
@@ -6175,6 +6438,10 @@ packages:
   process-warning@5.0.0:
     resolution: {integrity: sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA==}
 
+  process@0.11.10:
+    resolution: {integrity: sha512-cdGef/drWFoydD1JsMzuFf8100nZl+GT+yacc2bEced5f9Rjk4z+WtFUTBu9PhOi9j/jfmBPu0mMEY4wIdAF8A==}
+    engines: {node: '>= 0.6.0'}
+
   promise-inflight@1.0.1:
     resolution: {integrity: sha512-6zWPyEOFaQBJYcGMHBKTKJ3u6TBsnMFOIZSa6ce1e/ZrrsOlnHRHbabMjLiBYKp+n44X9eUI6VUPaukCXHuG4g==}
     peerDependencies:
@@ -6342,6 +6609,10 @@ packages:
     resolution: {integrity: sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==}
     engines: {node: '>= 6'}
 
+  readable-stream@4.7.0:
+    resolution: {integrity: sha512-oIGGmcpTLwPga8Bn6/Z75SVaH1z5dUut2ibSyAMVhmUggWpmDn2dapB0n7f8nwaSiRtepAsfJyfXIO5DCVAODg==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+
   readdirp@4.1.2:
     resolution: {integrity: sha512-GDhwkLfywWL2s6vEjyhri+eXmfH6j1L7JE27WhqLeYzoh/A3DBaYGEj2H/HFZCn/kMfim73FXxEJTw06WtxQwg==}
     engines: {node: '>= 14.18.0'}
@@ -6463,9 +6734,18 @@ packages:
   set-cookie-parser@2.7.2:
     resolution: {integrity: sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==}
 
+  set-function-length@1.2.2:
+    resolution: {integrity: sha512-pgRc4hJ4/sNjWCSS9AmnS40x3bNMDTknHgL5UaMBTMyJnU90EgWh1Rz+MC9eFu4BuN/UwZjKQuY/1v3rM7HMfg==}
+    engines: {node: '>= 0.4'}
+
   setprototypeof@1.2.0:
     resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
 
+  sha.js@2.4.12:
+    resolution: {integrity: sha512-8LzC5+bvI45BjpfXU8V5fdU2mfeKiQe1D1gIMn7XUlF3OTUrpdJpPPH4EMAnF0DsHHdSZqCdSss5qCmJKuiO3w==}
+    engines: {node: '>= 0.10'}
+    hasBin: true
+
   sharp@0.34.5:
     resolution: {integrity: sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
@@ -6687,6 +6967,12 @@ packages:
   text-decoder@1.2.7:
     resolution: {integrity: sha512-vlLytXkeP4xvEq2otHeJfSQIRyWxo/oZGEbXrtEEF9Hnmrdly59sUbzZ/QgyWuLYHctCHxFF4tRQZNQ9k60ExQ==}
 
+  thingies@2.6.0:
+    resolution: {integrity: sha512-rMHRjmlFLM1R96UYPvpmnc3LYtdFrT33JIB7L9hetGue1qAPfn1N2LJeEjxUSidu1Iku+haLZXDuEXUHNGO/lg==}
+    engines: {node: '>=10.18'}
+    peerDependencies:
+      tslib: ^2
+
   thread-stream@3.1.0:
     resolution: {integrity: sha512-OqyPZ9u96VohAyMfJykzmivOrY2wfMSf3C5TtFJVgN+Hm6aj+voFhlK+kZEIv2FBh1X6Xp3DlnCOfEQ3B2J86A==}
 
@@ -6726,6 +7012,10 @@ packages:
     resolution: {integrity: sha512-WiGwQjr0qYdNNG8KpMKlSvpxz652lqa3Rd+/hSaDcY4Uo6SKWZq2LAF+hsAhUewTtYhXlorBKgNF3Kk8hnjGoQ==}
     hasBin: true
 
+  to-buffer@1.2.2:
+    resolution: {integrity: sha512-db0E3UJjcFhpDhAF4tLo03oli3pwl3dbnzXOUIlRKrp+ldk/VUxzpWYZENsw2SZiuBjHAk7DfB0VU7NKdpb6sw==}
+    engines: {node: '>= 0.4'}
+
   toidentifier@1.0.1:
     resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
     engines: {node: '>=0.6'}
@@ -6738,6 +7028,12 @@ packages:
     resolution: {integrity: sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==}
     engines: {node: '>=20'}
 
+  tree-dump@1.1.0:
+    resolution: {integrity: sha512-rMuvhU4MCDbcbnleZTFezWsaZXRFemSqAM+7jPnzUl1fo9w3YEKOxAeui0fz3OI4EU4hf23iyA7uQRVko+UaBA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
   trim-lines@3.0.1:
     resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
 
@@ -6777,6 +7073,10 @@ packages:
   type@2.7.3:
     resolution: {integrity: sha512-8j+1QmAbPvLZow5Qpi6NCaN8FB60p/6x8/vfNqOk/hC+HuvFZhL4+WfekuhQLiqFZXOgQdrs3B+XxEmCc6b3FQ==}
 
+  typed-array-buffer@1.0.3:
+    resolution: {integrity: sha512-nAYYwfY3qnzX30IkA6AQZjVbtK6duGontcQm1WSG1MD94YLqK0515GNApXkoxKOWMusVssAHWLh9SeaoefYFGw==}
+    engines: {node: '>= 0.4'}
+
   typedarray@0.0.6:
     resolution: {integrity: sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==}
 
@@ -7083,6 +7383,10 @@ packages:
     resolution: {integrity: sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==}
     engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
 
+  which-typed-array@1.1.20:
+    resolution: {integrity: sha512-LYfpUkmqwl0h9A2HL09Mms427Q1RZWuOHsukfVcKRq9q95iQxdw0ix1JQrqbcDR9PH1QDwf5Qo8OZb5lksZ8Xg==}
+    engines: {node: '>= 0.4'}
+
   which@2.0.2:
     resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
     engines: {node: '>= 8'}
@@ -8817,6 +9121,133 @@ snapshots:
       '@jridgewell/resolve-uri': 3.1.2
       '@jridgewell/sourcemap-codec': 1.5.5
 
+  '@jsonjoy.com/base64@1.1.2(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/base64@17.67.0(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/buffers@1.2.1(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/buffers@17.67.0(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/codegen@1.0.0(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/codegen@17.67.0(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-core@4.57.2(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-node-builtins': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.57.2(tslib@2.8.1)
+      thingies: 2.6.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-fsa@4.57.2(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-core': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-builtins': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.57.2(tslib@2.8.1)
+      thingies: 2.6.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-node-builtins@4.57.2(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-node-to-fsa@4.57.2(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-fsa': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-builtins': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.57.2(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-node-utils@4.57.2(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-node-builtins': 4.57.2(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-node@4.57.2(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-core': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-builtins': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-print': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-snapshot': 4.57.2(tslib@2.8.1)
+      glob-to-regex.js: 1.2.0(tslib@2.8.1)
+      thingies: 2.6.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-print@4.57.2(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-node-utils': 4.57.2(tslib@2.8.1)
+      tree-dump: 1.1.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-snapshot@4.57.2(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/buffers': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/json-pack': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/util': 17.67.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/json-pack@1.21.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/base64': 1.1.2(tslib@2.8.1)
+      '@jsonjoy.com/buffers': 1.2.1(tslib@2.8.1)
+      '@jsonjoy.com/codegen': 1.0.0(tslib@2.8.1)
+      '@jsonjoy.com/json-pointer': 1.0.2(tslib@2.8.1)
+      '@jsonjoy.com/util': 1.9.0(tslib@2.8.1)
+      hyperdyperid: 1.2.0
+      thingies: 2.6.0(tslib@2.8.1)
+      tree-dump: 1.1.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/json-pack@17.67.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/base64': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/buffers': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/codegen': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/json-pointer': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/util': 17.67.0(tslib@2.8.1)
+      hyperdyperid: 1.2.0
+      thingies: 2.6.0(tslib@2.8.1)
+      tree-dump: 1.1.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/json-pointer@1.0.2(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/codegen': 1.0.0(tslib@2.8.1)
+      '@jsonjoy.com/util': 1.9.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/json-pointer@17.67.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/util': 17.67.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/util@1.9.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/buffers': 1.2.1(tslib@2.8.1)
+      '@jsonjoy.com/codegen': 1.0.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/util@17.67.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/buffers': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/codegen': 17.67.0(tslib@2.8.1)
+      tslib: 2.8.1
+
   '@lexical/clipboard@0.35.0':
     dependencies:
       '@lexical/html': 0.35.0
@@ -11003,6 +11434,10 @@ snapshots:
   abbrev@1.1.1:
     optional: true
 
+  abort-controller@3.0.0:
+    dependencies:
+      event-target-shim: 5.0.1
+
   accepts@2.0.0:
     dependencies:
       mime-types: 3.0.2
@@ -11108,10 +11543,16 @@ snapshots:
 
   async-exit-hook@2.0.1: {}
 
+  async-lock@1.4.1: {}
+
   asynckit@0.4.0: {}
 
   atomic-sleep@1.0.0: {}
 
+  available-typed-arrays@1.0.7:
+    dependencies:
+      possible-typed-array-names: 1.1.0
+
   axe-core@4.11.3: {}
 
   b4a@1.8.1: {}
@@ -11291,6 +11732,13 @@ snapshots:
       es-errors: 1.3.0
       function-bind: 1.1.2
 
+  call-bind@1.0.9:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-define-property: 1.0.1
+      get-intrinsic: 1.3.0
+      set-function-length: 1.2.2
+
   call-bound@1.0.4:
     dependencies:
       call-bind-apply-helpers: 1.0.2
@@ -11346,6 +11794,8 @@ snapshots:
 
   classnames@2.5.1: {}
 
+  clean-git-ref@2.0.1: {}
+
   clean-set@1.1.2: {}
 
   clean-stack@2.2.0:
@@ -11447,6 +11897,8 @@ snapshots:
     dependencies:
       layout-base: 2.0.1
 
+  crc-32@1.2.2: {}
+
   crelt@1.0.6: {}
 
   cross-env@10.1.0:
@@ -11705,6 +12157,12 @@ snapshots:
       bundle-name: 4.1.0
       default-browser-id: 5.0.1
 
+  define-data-property@1.1.4:
+    dependencies:
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
   define-lazy-prop@3.0.0: {}
 
   defu@6.1.4: {}
@@ -11739,6 +12197,8 @@ snapshots:
       asap: 2.0.6
       wrappy: 1.0.2
 
+  diff3@0.0.3: {}
+
   diff@5.2.2: {}
 
   doctrine@3.0.0:
@@ -12002,12 +12462,16 @@ snapshots:
       d: 1.0.2
       es5-ext: 0.10.64
 
+  event-target-shim@5.0.1: {}
+
   events-universal@1.0.1:
     dependencies:
       bare-events: 2.8.2
     transitivePeerDependencies:
       - bare-abort-controller
 
+  events@3.3.0: {}
+
   eventsource-parser@3.0.6: {}
 
   eventsource@3.0.7:
@@ -12107,6 +12571,10 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  for-each@0.3.5:
+    dependencies:
+      is-callable: 1.2.7
+
   form-data@4.0.5:
     dependencies:
       asynckit: 0.4.0
@@ -12186,6 +12654,10 @@ snapshots:
 
   github-from-package@0.0.0: {}
 
+  glob-to-regex.js@1.2.0(tslib@2.8.1):
+    dependencies:
+      tslib: 2.8.1
+
   glob@13.0.6:
     dependencies:
       minimatch: 10.2.5
@@ -12208,6 +12680,10 @@ snapshots:
 
   hachure-fill@0.5.2: {}
 
+  has-property-descriptors@1.0.2:
+    dependencies:
+      es-define-property: 1.0.1
+
   has-symbols@1.1.0: {}
 
   has-tostringtag@1.0.2:
@@ -12309,6 +12785,8 @@ snapshots:
       ms: 2.1.3
     optional: true
 
+  hyperdyperid@1.2.0: {}
+
   iconv-lite@0.6.3:
     dependencies:
       safer-buffer: 2.1.2
@@ -12319,6 +12797,8 @@ snapshots:
 
   ieee754@1.2.1: {}
 
+  ignore@5.3.2: {}
+
   imurmurhash@0.1.4:
     optional: true
 
@@ -12359,6 +12839,8 @@ snapshots:
       is-alphabetical: 2.0.1
       is-decimal: 2.0.1
 
+  is-callable@1.2.7: {}
+
   is-core-module@2.16.1:
     dependencies:
       hasown: 2.0.2
@@ -12389,12 +12871,32 @@ snapshots:
 
   is-promise@4.0.0: {}
 
+  is-typed-array@1.1.15:
+    dependencies:
+      which-typed-array: 1.1.20
+
   is-wsl@3.1.1:
     dependencies:
       is-inside-container: 1.0.0
 
+  isarray@2.0.5: {}
+
   isexe@2.0.0: {}
 
+  isomorphic-git@1.38.0:
+    dependencies:
+      async-lock: 1.4.1
+      clean-git-ref: 2.0.1
+      crc-32: 1.2.2
+      diff3: 0.0.3
+      ignore: 5.3.2
+      minimisted: 2.0.1
+      pako: 1.0.11
+      pify: 4.0.1
+      readable-stream: 4.7.0
+      sha.js: 2.4.12
+      simple-get: 4.0.1
+
   isomorphic.js@0.2.5: {}
 
   jiti@2.6.1: {}
@@ -12786,6 +13288,23 @@ snapshots:
 
   media-typer@1.1.0: {}
 
+  memfs@4.57.2(tslib@2.8.1):
+    dependencies:
+      '@jsonjoy.com/fs-core': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-fsa': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-builtins': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-to-fsa': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-print': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/fs-snapshot': 4.57.2(tslib@2.8.1)
+      '@jsonjoy.com/json-pack': 1.21.0(tslib@2.8.1)
+      '@jsonjoy.com/util': 1.9.0(tslib@2.8.1)
+      glob-to-regex.js: 1.2.0(tslib@2.8.1)
+      thingies: 2.6.0(tslib@2.8.1)
+      tree-dump: 1.1.0(tslib@2.8.1)
+      tslib: 2.8.1
+
   merge-descriptors@2.0.0: {}
 
   mermaid@11.12.3:
@@ -13132,6 +13651,10 @@ snapshots:
 
   minimist@1.2.8: {}
 
+  minimisted@2.0.1:
+    dependencies:
+      minimist: 1.2.8
+
   minipass-collect@1.0.2:
     dependencies:
       minipass: 3.3.6
@@ -13288,6 +13811,8 @@ snapshots:
 
   package-manager-detector@1.6.0: {}
 
+  pako@1.0.11: {}
+
   parse-entities@4.0.2:
     dependencies:
       '@types/unist': 2.0.11
@@ -13367,6 +13892,8 @@ snapshots:
 
   picomatch@4.0.3: {}
 
+  pify@4.0.1: {}
+
   pino-abstract-transport@2.0.0:
     dependencies:
       split2: 4.2.0
@@ -13437,6 +13964,8 @@ snapshots:
       path-data-parser: 0.1.0
       points-on-curve: 0.2.0
 
+  possible-typed-array-names@1.1.0: {}
+
   postcss-selector-parser@6.0.10:
     dependencies:
       cssesc: 3.0.0
@@ -13487,6 +14016,8 @@ snapshots:
 
   process-warning@5.0.0: {}
 
+  process@0.11.10: {}
+
   promise-inflight@1.0.1:
     optional: true
 
@@ -13720,6 +14251,14 @@ snapshots:
       string_decoder: 1.3.0
       util-deprecate: 1.0.2
 
+  readable-stream@4.7.0:
+    dependencies:
+      abort-controller: 3.0.0
+      buffer: 6.0.3
+      events: 3.3.0
+      process: 0.11.10
+      string_decoder: 1.3.0
+
   readdirp@4.1.2: {}
 
   real-require@0.2.0: {}
@@ -13897,8 +14436,23 @@ snapshots:
 
   set-cookie-parser@2.7.2: {}
 
+  set-function-length@1.2.2:
+    dependencies:
+      define-data-property: 1.1.4
+      es-errors: 1.3.0
+      function-bind: 1.1.2
+      get-intrinsic: 1.3.0
+      gopd: 1.2.0
+      has-property-descriptors: 1.0.2
+
   setprototypeof@1.2.0: {}
 
+  sha.js@2.4.12:
+    dependencies:
+      inherits: 2.0.4
+      safe-buffer: 5.2.1
+      to-buffer: 1.2.2
+
   sharp@0.34.5:
     dependencies:
       '@img/colour': 1.1.0
@@ -14221,6 +14775,10 @@ snapshots:
     transitivePeerDependencies:
       - react-native-b4a
 
+  thingies@2.6.0(tslib@2.8.1):
+    dependencies:
+      tslib: 2.8.1
+
   thread-stream@3.1.0:
     dependencies:
       real-require: 0.2.0
@@ -14250,6 +14808,12 @@ snapshots:
     dependencies:
       tldts-core: 7.0.26
 
+  to-buffer@1.2.2:
+    dependencies:
+      isarray: 2.0.5
+      safe-buffer: 5.2.1
+      typed-array-buffer: 1.0.3
+
   toidentifier@1.0.1: {}
 
   tough-cookie@6.0.1:
@@ -14260,6 +14824,10 @@ snapshots:
     dependencies:
       punycode: 2.3.1
 
+  tree-dump@1.1.0(tslib@2.8.1):
+    dependencies:
+      tslib: 2.8.1
+
   trim-lines@3.0.1: {}
 
   trough@2.2.0: {}
@@ -14300,6 +14868,12 @@ snapshots:
 
   type@2.7.3: {}
 
+  typed-array-buffer@1.0.3:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      is-typed-array: 1.1.15
+
   typedarray@0.0.6: {}
 
   typescript@5.9.3: {}
@@ -14674,6 +15248,16 @@ snapshots:
     transitivePeerDependencies:
       - '@noble/hashes'
 
+  which-typed-array@1.1.20:
+    dependencies:
+      available-typed-arrays: 1.0.7
+      call-bind: 1.0.9
+      call-bound: 1.0.4
+      for-each: 0.3.5
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      has-tostringtag: 1.0.2
+
   which@2.0.2:
     dependencies:
       isexe: 2.0.0
diff --git a/releases/v2026.511.0.md b/releases/v2026.512.0.md
similarity index 94%
rename from releases/v2026.511.0.md
rename to releases/v2026.512.0.md
index f5a60130..b893428e 100644
--- a/releases/v2026.511.0.md
+++ b/releases/v2026.512.0.md
@@ -1,6 +1,6 @@
-# v2026.511.0
+# v2026.512.0
 
-> Released: 2026-05-11
+> Released: 2026-05-12
 
 ## Highlights
 
@@ -9,9 +9,9 @@
 - **Routine revision history with restore** — Routines now keep an append-only revision log with a History tab on routine detail. Operators can preview prior revisions, see structured change summaries, diff descriptions, restore older definitions safely, and recover webhook secrets after restore. ([#5285](https://github.com/paperclipai/paperclip/pull/5285))
 - **Successful-run handoff and system notices** — When an agent run ends productively but the issue still needs a final disposition, the recovery service now opens an explicit handoff with first-class system notices rendered in the issue thread, so operators can see exactly why a run paused, escalated, or closed. ([#5289](https://github.com/paperclipai/paperclip/pull/5289))
 - **Expanded plugin host surface** — Plugins can now declare scoped database namespaces (with migration tracking), local project folders, managed agents, managed routines, scoped APIs, and reusable UI building blocks (file trees, resizable sidebars, route sidebars, managed-routine controls), all through documented contracts and validators. Follow-up host support landed for managed plugin skills and richer SDK types. ([#5205](https://github.com/paperclipai/paperclip/pull/5205), [#5597](https://github.com/paperclipai/paperclip/pull/5597))
+- **LLM Wiki plugin package** — Built on the new plugin host contracts, the `@paperclip/plugin-llm-wiki` package now ships in the monorepo with public entrypoints and Docker manifest coverage. ([#5716](https://github.com/paperclipai/paperclip/pull/5716))
 - **Secrets provider vaults with remote import** — Company secrets gain provider-vault configuration, AWS Secrets Manager remote-import preview/commit, binding usage tracking, access events, and rotation guards. The Secrets settings UI now exposes vault management and remote import, with CLI/API docs to match. ([#5429](https://github.com/paperclipai/paperclip/pull/5429))
 - **Cursor cloud adapter** — A new built-in `cursor_cloud` adapter drives Cursor's hosted-agent platform through `@cursor/sdk`, mapping Paperclip heartbeats to Cursor's durable-agent + per-run model with session reuse, streaming, and cancellation. ([#5664](https://github.com/paperclipai/paperclip/pull/5664))
-- **Daytona sandbox provider plugin** — A new `@paperclip/sandbox-provider-daytona` plugin uses `@daytonaio/sdk` for sandbox lifecycle, command execution, and shell detection, mirroring the existing E2B provider so operators can pick Daytona without touching core. ([#5580](https://github.com/paperclipai/paperclip/pull/5580), [#5586](https://github.com/paperclipai/paperclip/pull/5586))
 - **ACPX local adapter** — A new ACPX local adapter runtime can proxy Claude- and Codex-style execution with provider-aware model handling, a polished agent config form, and Storybook-covered model/provider behavior. ([#4893](https://github.com/paperclipai/paperclip/pull/4893), [#5290](https://github.com/paperclipai/paperclip/pull/5290))
 
 ## Improvements
@@ -37,9 +37,7 @@
 - **Issue comment presentation contract** — Issue comments grow optional `author_type`, `presentation`, and `metadata` fields so system-authored notices render as first-class thread messages without overloading regular comments. ([#5289](https://github.com/paperclipai/paperclip/pull/5289))
 - **Database backups cover non-system schemas** — Database backup support now covers non-system schemas and is hardened against schema drift. ([#4859](https://github.com/paperclipai/paperclip/pull/4859), [#4960](https://github.com/paperclipai/paperclip/pull/4960))
 - **Dedicated environment settings page** — Environments get their own settings page with a test-in-environment flow so operators can validate adapters before assigning work. ([#4798](https://github.com/paperclipai/paperclip/pull/4798))
-- **Cursor sandbox support** — Adds Cursor as a supported sandbox, alongside SSH workspace-sync fixes for remote setups. ([#4803](https://github.com/paperclipai/paperclip/pull/4803))
 - **E2B plugin configuration UX** — The E2B plugin gets a clearer configuration UX, longer-running execution support, and a default-template flag for example plugins. ([#4802](https://github.com/paperclipai/paperclip/pull/4802), [#4901](https://github.com/paperclipai/paperclip/pull/4901))
-- **Sandbox provider messaging** — Company environment settings call out the active sandbox provider more clearly so operators know which runtime backs each environment. ([#4902](https://github.com/paperclipai/paperclip/pull/4902))
 - **Sandbox callback bridge for remote envs** — Remote execution targets now reach the host environment through a scoped callback bridge with serialization against concurrent heartbeats, env sanitization at the boundary, an expanded allowlist for the documented heartbeat surface, optional proxy logging via `PAPERCLIP_BRIDGE_DEBUG`, and SSH-environment-callback migration. ([#4801](https://github.com/paperclipai/paperclip/pull/4801), [#5326](https://github.com/paperclipai/paperclip/pull/5326), [#5325](https://github.com/paperclipai/paperclip/pull/5325), [#5324](https://github.com/paperclipai/paperclip/pull/5324), [#5140](https://github.com/paperclipai/paperclip/pull/5140), [#5116](https://github.com/paperclipai/paperclip/pull/5116))
 - **Sandbox install/test surface** — Per-adapter sandbox install commands flow through both the test and execute paths, sandbox providers can declare shell defaults, explicit-environment adapter tests run on the requested target instead of falling back to the host, and remote provisioning now consults a runtime command spec from the adapter. ([#5280](https://github.com/paperclipai/paperclip/pull/5280), [#5277](https://github.com/paperclipai/paperclip/pull/5277), [#5141](https://github.com/paperclipai/paperclip/pull/5141), [#5114](https://github.com/paperclipai/paperclip/pull/5114))
 - **Polished board settings and skills workflow** — Board settings and the skills assignment flow are smoother to navigate. ([#4863](https://github.com/paperclipai/paperclip/pull/4863))
@@ -55,7 +53,6 @@
 - **Remote workspace environment shaping** — Remote workspace environment shaping now produces the right env for downstream commands. ([#5118](https://github.com/paperclipai/paperclip/pull/5118))
 - **SSH callback URL selection on LAN/private networks** — The SSH callback now picks a URL the remote can reach when the host is on a LAN or private network. ([#4799](https://github.com/paperclipai/paperclip/pull/4799))
 - **Harder remote workspace sync and restore** — Workspace export uses a per-import unique ref, restore goes through a new snapshot-aware merge that only writes files the remote actually changed, and every adapter threads a pre-run snapshot through sandbox/SSH paths to avoid trampling local state. ([#5444](https://github.com/paperclipai/paperclip/pull/5444))
-- **Cursor sandbox runtime resolution** — Cursor sandbox runtime resolution is more stable across adapter targets. ([#5446](https://github.com/paperclipai/paperclip/pull/5446))
 - **Runtime probes and Codex env tests** — Runtime probe behavior and Codex environment tests are stabilized so flakes no longer mask real adapter problems. ([#5445](https://github.com/paperclipai/paperclip/pull/5445))
 - **E2B sandbox executor reliability** — E2B sandboxes now run a real `command -v` probe and source login profiles before exec, stage stdin to a temp file so it is delivered reliably, and the gemini-local hello probe gets a 60-second timeout for SSH and E2B targets. ([#5279](https://github.com/paperclipai/paperclip/pull/5279), [#5278](https://github.com/paperclipai/paperclip/pull/5278), [#5322](https://github.com/paperclipai/paperclip/pull/5322))
 - **Runtime races and orphaned leases** — Fixes a runtime state race, workspace-sync gaps, plugin startup ordering, and orphaned execution leases. ([#4804](https://github.com/paperclipai/paperclip/pull/4804))
@@ -80,4 +77,4 @@ Nine new database migrations (`0075`–`0083`) run automatically on startup. All
 - `0082_dry_vision` — adds the secrets provider infrastructure: creates `company_secret_bindings` and `secret_access_events`, adds a stable `key` slug to `company_secrets` (backfilled and de-duplicated from existing names), and grows `company_secrets` / `company_secret_versions` with provider metadata, fingerprints, rotation timestamps, and soft-delete columns. Existing secrets get `managed_mode = 'paperclip_managed'`, `status = 'active'`, and a backfilled `last_rotated_at`.
 - `0083_company_secret_provider_configs` — creates `company_secret_provider_configs` and retypes `company_secrets.provider_config_id` from `text` to `uuid`. Any prior non-UUID values in that column are cleared to NULL before the type change, so make sure you have no production data relying on free-form provider config ids before upgrading. If you do, capture those values out-of-band and reconfigure secrets against a real provider config row after the migration.
 
-No application configuration changes are required to take this release. If you operate the Codex adapter against Codex CLI 0.122 or newer, the new apikey-mode `auth.json` is written automatically from your existing `OPENAI_API_KEY` configuration. The new `cursor_cloud` adapter and Daytona sandbox provider are opt-in — agents and environments continue to use whatever runtime/sandbox they were configured with.
+No application configuration changes are required to take this release. If you operate the Codex adapter against Codex CLI 0.122 or newer, the new apikey-mode `auth.json` is written automatically from your existing `OPENAI_API_KEY` configuration. The new `cursor_cloud` adapter is opt-in — agents continue to use whatever runtime they were configured with.
diff --git a/releases/v2026.513.0.md b/releases/v2026.513.0.md
new file mode 100644
index 00000000..d202ff83
--- /dev/null
+++ b/releases/v2026.513.0.md
@@ -0,0 +1,26 @@
+# v2026.513.0
+
+> Released: 2026-05-13
+
+## Highlights
+
+- **Source-scoped recovery actions** — Stalled or missing-disposition recovery now creates first-class recovery actions on the source issue itself, with owner, evidence, wake policy, and resolution outcome (`restored`, `blocked`, `cancelled`, or `false_positive`). Recovery indicators surface on issue rows, detail surfaces, active run panels, and blocker notices, and blocked resolutions require a real first-class blocker instead of a comment. ([#5599](https://github.com/paperclipai/paperclip/pull/5599))
+- **Blocked Inbox attention view** — A new Blocked Inbox tab surfaces blocked work alongside active assignments, with blocked-reason chips, filtering and search, deterministic urgency sorting, responsive layouts, and a backend blocker-attention contract so operators have a clear triage path for stalled tasks. ([#5603](https://github.com/paperclipai/paperclip/pull/5603))
+- **Local plugin development workflow** — `paperclipai plugin init` scaffolding now ships with a CLI-first authoring loop covering local-path installs, plugin key routing, dashboard capabilities, dev watcher startup and reload, and SDK worker entrypoint validation for symlinked package layouts. A new local plugin development guide and refreshed `paperclip-create-plugin` skill instructions document the full happy path. ([#5821](https://github.com/paperclipai/paperclip/pull/5821))
+
+## Improvements
+
+- **Ordered sub-issue navigation** — Issue detail footers now expose previous/next ordered navigation that walks siblings and continues into a parent's first ordered child, with hidden-issue filtering and dependency-aware ordering preserved. The quicklook blur/click race is also fixed so portaled link clicks complete reliably. ([#5938](https://github.com/paperclipai/paperclip/pull/5938))
+
+## Fixes
+
+- **Comment date binding regression** — Issue comment listing no longer fails with `ERR_INVALID_ARG_TYPE` when the derived-attribution heartbeat scan binds a `Date` into postgres-js. Window bounds are now bound as ISO timestamp strings with explicit `::timestamptz` casts so comments load on issues such as `PAP-9284` without weakening the conservative attribution recovery. ([#5919](https://github.com/paperclipai/paperclip/pull/5919))
+- **Remote sandbox host workspace resumes** — `claude_local` sessions now persist the host workspace cwd (not the remote sandbox cwd), reject saved cwds that point at system roots before falling back to the agent home workspace, skip sockets, FIFOs, devices, and other non-file entries during workspace restore snapshot capture, and pass only a small model-provider API-key allowlist to plugins that declare `environment.drivers.register`. ([#5922](https://github.com/paperclipai/paperclip/pull/5922))
+
+## Upgrade Guide
+
+One new database migration runs automatically on startup:
+
+- `0084_issue_recovery_actions` — adds the `issue_recovery_actions` table and supporting indexes for source-scoped recovery. The migration is idempotent so it is safe for anyone who previously applied an earlier branch-local recovery-action migration. Existing child recovery issue paths remain guarded; new source-scoped flows will surface recovery indicators in additional places on the board UI.
+
+No application configuration changes are required to take this release.
diff --git a/scripts/release-package-manifest.json b/scripts/release-package-manifest.json
index 954c258e..761065e6 100644
--- a/scripts/release-package-manifest.json
+++ b/scripts/release-package-manifest.json
@@ -94,6 +94,11 @@
     "name": "@paperclipai/plugin-daytona",
     "publishFromCi": true
   },
+  {
+    "dir": "packages/plugins/sandbox-providers/kubernetes",
+    "name": "@paperclipai/plugin-kubernetes",
+    "publishFromCi": false
+  },
   {
     "dir": "packages/plugins/sandbox-providers/exe-dev",
     "name": "@paperclipai/plugin-exe-dev",
diff --git a/scripts/run-vitest-stable.mjs b/scripts/run-vitest-stable.mjs
index 4ded9794..c85c48aa 100644
--- a/scripts/run-vitest-stable.mjs
+++ b/scripts/run-vitest-stable.mjs
@@ -14,6 +14,7 @@ const nonServerProjects = [
   "@paperclipai/adapter-acpx-local",
   "@paperclipai/adapter-codex-local",
   "@paperclipai/adapter-opencode-local",
+  "@paperclipai/plugin-sdk",
   "@paperclipai/ui",
   "paperclipai",
 ];
diff --git a/scripts/screenshot-blocked-inbox.mjs b/scripts/screenshot-blocked-inbox.mjs
new file mode 100644
index 00000000..277a6f8f
--- /dev/null
+++ b/scripts/screenshot-blocked-inbox.mjs
@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// Capture screenshots of the Blocked Inbox storybook stories.
+// Usage: node scripts/screenshot-blocked-inbox.mjs <storybook-static-dir> <output-dir>
+
+import http from "node:http";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { chromium } from "@playwright/test";
+
+async function main() {
+  const [, , staticDir, outDir] = process.argv;
+  if (!staticDir || !outDir) {
+    console.error("usage: node scripts/screenshot-blocked-inbox.mjs <storybook-static-dir> <output-dir>");
+    process.exit(1);
+  }
+  await fs.mkdir(outDir, { recursive: true });
+  const absStaticDir = path.resolve(staticDir);
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      let urlPath = decodeURIComponent((req.url || "/").split("?")[0]);
+      if (urlPath.endsWith("/")) urlPath += "iframe.html";
+      const filePath = path.resolve(absStaticDir, `.${urlPath}`);
+      if (!filePath.startsWith(absStaticDir + path.sep) && filePath !== absStaticDir) {
+        res.writeHead(403);
+        res.end("Forbidden");
+        return;
+      }
+      const buf = await fs.readFile(filePath);
+      const ext = path.extname(filePath).toLowerCase();
+      const mime = {
+        ".html": "text/html; charset=utf-8",
+        ".js": "application/javascript",
+        ".css": "text/css",
+        ".json": "application/json",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".woff": "font/woff",
+        ".woff2": "font/woff2",
+        ".map": "application/json",
+      }[ext] || "application/octet-stream";
+      res.writeHead(200, { "content-type": mime });
+      res.end(buf);
+    } catch (err) {
+      res.writeHead(404);
+      res.end(String(err));
+    }
+  });
+
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const port = server.address().port;
+  const baseUrl = `http://127.0.0.1:${port}/iframe.html`;
+
+  const browser = await chromium.launch();
+  try {
+    const stories = [
+      { id: "product-inbox-blocked-tab--desktop-loaded", file: "01-desktop-loaded.png", width: 1440, height: 1100, dark: false },
+      { id: "product-inbox-blocked-tab--desktop-loaded", file: "02-desktop-loaded-dark.png", width: 1440, height: 1100, dark: true },
+      { id: "product-inbox-blocked-tab--desktop-with-search", file: "03-desktop-with-search.png", width: 1440, height: 800, dark: false },
+      { id: "product-inbox-blocked-tab--mobile-layout", file: "04-mobile-layout.png", width: 390, height: 1100, dark: false },
+      { id: "product-inbox-blocked-tab--reason-chip-catalog", file: "05-reason-chip-catalog.png", width: 900, height: 600, dark: false },
+      { id: "product-inbox-blocked-tab--empty-state", file: "06-empty-state.png", width: 900, height: 500, dark: false },
+    ];
+
+    for (const story of stories) {
+      const ctx = await browser.newContext({
+        viewport: { width: story.width, height: story.height },
+        deviceScaleFactor: 2,
+        colorScheme: story.dark ? "dark" : "light",
+      });
+      const page = await ctx.newPage();
+      const url = `${baseUrl}?id=${story.id}&viewMode=story`;
+      await page.goto(url, { waitUntil: "networkidle" });
+      // Force light/dark class on <html> for tailwind dark mode tokens
+      await page.evaluate((dark) => {
+        const html = document.documentElement;
+        html.classList.toggle("dark", dark);
+        html.style.colorScheme = dark ? "dark" : "light";
+      }, story.dark);
+      await page.waitForTimeout(500);
+      const out = path.join(outDir, story.file);
+      await page.screenshot({ path: out, fullPage: true });
+      console.log("wrote", out);
+      await ctx.close();
+    }
+  } finally {
+    await browser.close();
+    server.close();
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
diff --git a/scripts/screenshot-recovery-card.cjs b/scripts/screenshot-recovery-card.cjs
new file mode 100644
index 00000000..6b2b0a27
--- /dev/null
+++ b/scripts/screenshot-recovery-card.cjs
@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const path = require("path");
+const fs = require("fs");
+
+const repoRoot = path.resolve(__dirname, "..");
+const playwright = require(path.join(
+  repoRoot,
+  "node_modules/.pnpm/playwright@1.58.2/node_modules/playwright/index.js",
+));
+
+const STORYBOOK_BASE = process.env.STORYBOOK_URL ?? "http://localhost:6006";
+const OUT_DIR = path.resolve(repoRoot, "tmp/pap-9134-recovery-screens");
+
+const VIEWPORTS = [
+  { name: "desktop", width: 1440, height: 900 },
+  { name: "mobile", width: 390, height: 844 },
+];
+
+const STORIES = [
+  {
+    id: "paperclip-source-issue-recovery--recovery-action-card-states",
+    label: "card-states",
+  },
+  {
+    id: "paperclip-source-issue-recovery--inbox-row-chips",
+    label: "inbox-rows",
+  },
+  {
+    id: "paperclip-source-issue-recovery--blocker-notice-recovery-indicators",
+    label: "blocker-notice",
+  },
+  {
+    id: "paperclip-source-issue-recovery--active-run-panel-recovery-chips",
+    label: "active-run-panel",
+  },
+];
+
+const THEMES = [
+  { name: "light", apply: () => document.documentElement.classList.remove("dark") },
+  { name: "dark", apply: () => document.documentElement.classList.add("dark") },
+];
+
+(async () => {
+  fs.mkdirSync(OUT_DIR, { recursive: true });
+  const browser = await playwright.chromium.launch();
+  try {
+    for (const viewport of VIEWPORTS) {
+      const context = await browser.newContext({
+        viewport: { width: viewport.width, height: viewport.height },
+        deviceScaleFactor: 2,
+      });
+      for (const story of STORIES) {
+        for (const theme of THEMES) {
+          const page = await context.newPage();
+          const url = `${STORYBOOK_BASE}/iframe.html?id=${story.id}&viewMode=story`;
+          await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30_000 });
+          await page.waitForLoadState("networkidle", { timeout: 30_000 }).catch(() => {});
+          await page.evaluate((darkTheme) => {
+            const html = document.documentElement;
+            if (darkTheme) {
+              html.classList.add("dark");
+            } else {
+              html.classList.remove("dark");
+            }
+          }, theme.name === "dark");
+          await page.waitForTimeout(400);
+          const outPath = path.join(
+            OUT_DIR,
+            `${story.label}_${viewport.name}_${theme.name}.png`,
+          );
+          await page.screenshot({ path: outPath, fullPage: true });
+          console.log(`Saved ${outPath}`);
+          await page.close();
+        }
+      }
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+  }
+})().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
diff --git a/server/package.json b/server/package.json
index 2ea875b8..0b677ba3 100644
--- a/server/package.json
+++ b/server/package.json
@@ -68,7 +68,9 @@
     "embedded-postgres": "^18.1.0-beta.16",
     "express": "^5.1.0",
     "hermes-paperclip-adapter": "^0.2.0",
+    "isomorphic-git": "^1.38.0",
     "jsdom": "^28.1.0",
+    "memfs": "^4.57.2",
     "multer": "^2.1.1",
     "open": "^11.0.0",
     "pino": "^9.6.0",
diff --git a/server/src/__tests__/agent-test-environment-routes.test.ts b/server/src/__tests__/agent-test-environment-routes.test.ts
index 3063fb70..d951a5ee 100644
--- a/server/src/__tests__/agent-test-environment-routes.test.ts
+++ b/server/src/__tests__/agent-test-environment-routes.test.ts
@@ -196,6 +196,15 @@ describe("agent test-environment route", () => {
       }),
       status: "failed",
     });
+    // Ad-hoc operator probes have no agent context — the route must pass
+    // agentId: null so plugin-backed providers don't accidentally scope the
+    // probe lease against some leftover agentId from the heartbeat path.
+    expect(mockEnvironmentRuntime.acquireRunLease).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agentId: null,
+        heartbeatRunId: null,
+      }),
+    );
   });
 
   it("returns a diagnostic result instead of probing the host when the requested environment is missing", async () => {
diff --git a/server/src/__tests__/claude-local-execute.test.ts b/server/src/__tests__/claude-local-execute.test.ts
index 60755a13..8cda4f0f 100644
--- a/server/src/__tests__/claude-local-execute.test.ts
+++ b/server/src/__tests__/claude-local-execute.test.ts
@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { runChildProcess } from "@paperclipai/adapter-utils/server-utils";
-import { execute } from "@paperclipai/adapter-claude-local/server";
+import { claudeSessionCwdMatchesExecutionTarget, execute } from "@paperclipai/adapter-claude-local/server";
 
 async function writeFailingClaudeCommand(
   commandPath: string,
@@ -580,7 +580,7 @@ describe("claude execute", () => {
     const remoteWorkspace = path.join(root, "sandbox-$HOME");
     const binDir = path.join(root, "bin");
     const commandPath = path.join(binDir, "claude");
-    const capturePath = path.join(remoteWorkspace, "capture.json");
+    const capturePath1 = path.join(remoteWorkspace, "capture-1.json");
     const claudeRoot = path.join(root, ".claude");
     const previousHome = process.env.HOME;
     const previousPath = process.env.PATH;
@@ -615,7 +615,7 @@ describe("claude execute", () => {
           command: commandPath,
           cwd: localWorkspace,
           env: {
-            PAPERCLIP_TEST_CAPTURE_PATH: capturePath,
+            PAPERCLIP_TEST_CAPTURE_PATH: capturePath1,
           },
           promptTemplate: "Follow the paperclip heartbeat.",
         },
@@ -635,7 +635,17 @@ describe("claude execute", () => {
       });
 
       expect(result.exitCode).toBe(0);
-      const capture = JSON.parse(await fs.readFile(capturePath, "utf8")) as CapturePayload;
+      expect(result.sessionParams).toMatchObject({
+        cwd: localWorkspace,
+        remoteExecution: {
+          transport: "sandbox",
+          providerKey: "e2b",
+          environmentId: "env-1",
+          leaseId: "lease-1",
+          remoteCwd: remoteWorkspace,
+        },
+      });
+      const capture = JSON.parse(await fs.readFile(capturePath1, "utf8")) as CapturePayload;
       expect(capture.argv).toContain("--allowedTools");
       expect(capture.argv).toContain(
         "Task AskUserQuestion Bash(*) CronCreate CronDelete CronList Edit EnterPlanMode EnterWorktree ExitPlanMode ExitWorktree Glob Grep Monitor NotebookEdit PushNotification Read RemoteTrigger ScheduleWakeup Skill TaskOutput TaskStop TodoWrite ToolSearch WebFetch WebSearch Write",
@@ -655,6 +665,19 @@ describe("claude execute", () => {
     }
   }, 10_000);
 
+  it("allows remote session resumes when saved cwd is the host workspace", () => {
+    expect(claudeSessionCwdMatchesExecutionTarget({
+      runtimeSessionCwd: "/host/workspace",
+      effectiveExecutionCwd: "/remote/workspace",
+      executionTargetIsRemote: true,
+    })).toBe(true);
+    expect(claudeSessionCwdMatchesExecutionTarget({
+      runtimeSessionCwd: "/host/workspace",
+      effectiveExecutionCwd: "/remote/workspace",
+      executionTargetIsRemote: false,
+    })).toBe(false);
+  });
+
   it("reuses a stable Paperclip-managed Claude prompt bundle across equivalent runs", async () => {
     const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-claude-execute-bundle-"));
     const workspace = path.join(root, "workspace");
diff --git a/server/src/__tests__/environment-run-orchestrator.test.ts b/server/src/__tests__/environment-run-orchestrator.test.ts
index c4dbb58b..93a91ff1 100644
--- a/server/src/__tests__/environment-run-orchestrator.test.ts
+++ b/server/src/__tests__/environment-run-orchestrator.test.ts
@@ -10,6 +10,8 @@ const mockBuildWorkspaceRealizationRequest = vi.hoisted(() => vi.fn());
 const mockUpdateLeaseMetadata = vi.hoisted(() => vi.fn());
 const mockUpdateExecutionWorkspace = vi.hoisted(() => vi.fn());
 const mockLogActivity = vi.hoisted(() => vi.fn());
+const mockEnvironmentsEnsureLocal = vi.hoisted(() => vi.fn());
+const mockEnvironmentsGetById = vi.hoisted(() => vi.fn());
 
 vi.mock("../services/environment-execution-target.js", () => ({
   resolveEnvironmentExecutionTarget: mockResolveEnvironmentExecutionTarget,
@@ -26,8 +28,8 @@ vi.mock("../services/workspace-realization.js", () => ({
 
 vi.mock("../services/environments.js", () => ({
   environmentService: vi.fn(() => ({
-    ensureLocalEnvironment: vi.fn(),
-    getById: vi.fn(),
+    ensureLocalEnvironment: mockEnvironmentsEnsureLocal,
+    getById: mockEnvironmentsGetById,
     acquireLease: vi.fn(),
     releaseLease: vi.fn(),
     updateLeaseMetadata: mockUpdateLeaseMetadata,
@@ -548,3 +550,75 @@ describe("environmentRunOrchestrator — realizeForRun", () => {
     expect(mockResolveEnvironmentExecutionTarget).not.toHaveBeenCalled();
   });
 });
+
+describe("environmentRunOrchestrator — acquireForRun threads agentId", () => {
+  const mockDb = {} as any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // selectedEnvironmentId !== defaultEnvironmentId in our inputs so the
+    // resolver goes through getById rather than ensureLocalEnvironment.
+    mockEnvironmentsGetById.mockResolvedValue(makeEnvironment("sandbox"));
+    mockResolveEnvironmentExecutionTarget.mockResolvedValue({
+      kind: "local",
+      environmentId: "env-1",
+      leaseId: "lease-1",
+    });
+    mockAdapterExecutionTargetToRemoteSpec.mockReturnValue(null);
+  });
+
+  function makeAcquireInput(overrides: { agentId?: string } = {}) {
+    return {
+      companyId: "company-1",
+      // distinct from defaultEnvironmentId so resolveEnvironment hits getById
+      selectedEnvironmentId: "env-1",
+      defaultEnvironmentId: "env-default",
+      adapterType: "claude_local",
+      issueId: null as string | null,
+      heartbeatRunId: "run-1",
+      agentId: overrides.agentId ?? "agent-uuid-abc",
+      persistedExecutionWorkspace: null,
+    };
+  }
+
+  it("passes agentId from acquireForRun's input through to runtime.acquireRunLease", async () => {
+    const runtime = makeMockRuntime({
+      acquireRunLease: vi.fn().mockResolvedValue({
+        lease: makeLease(),
+        leaseContext: { executionWorkspaceId: null, executionWorkspaceMode: null },
+      }),
+    });
+    const orchestrator = environmentRunOrchestrator(mockDb, { environmentRuntime: runtime });
+
+    await orchestrator.acquireForRun(makeAcquireInput({ agentId: "agent-uuid-abc" }));
+
+    expect(runtime.acquireRunLease).toHaveBeenCalledWith(
+      expect.objectContaining({
+        agentId: "agent-uuid-abc",
+        heartbeatRunId: "run-1",
+        companyId: "company-1",
+      }),
+    );
+  });
+
+  it("logs the lease-acquired activity with the same agentId it threads to the runtime", async () => {
+    const runtime = makeMockRuntime({
+      acquireRunLease: vi.fn().mockResolvedValue({
+        lease: makeLease(),
+        leaseContext: { executionWorkspaceId: null, executionWorkspaceMode: null },
+      }),
+    });
+    const orchestrator = environmentRunOrchestrator(mockDb, { environmentRuntime: runtime });
+
+    await orchestrator.acquireForRun(makeAcquireInput({ agentId: "agent-uuid-xyz" }));
+
+    expect(mockLogActivity).toHaveBeenCalledWith(
+      mockDb,
+      expect.objectContaining({
+        action: "environment.lease_acquired",
+        agentId: "agent-uuid-xyz",
+        actorId: "agent-uuid-xyz",
+      }),
+    );
+  });
+});
diff --git a/server/src/__tests__/environment-runtime.test.ts b/server/src/__tests__/environment-runtime.test.ts
index c850da81..3b8bf356 100644
--- a/server/src/__tests__/environment-runtime.test.ts
+++ b/server/src/__tests__/environment-runtime.test.ts
@@ -216,6 +216,7 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
 
     return {
       companyId,
+      agentId,
       environment: {
         id: environmentId,
         companyId,
@@ -1394,4 +1395,298 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
     expect(sshRelease).not.toHaveBeenCalled();
     expect(acquired.lease.metadata?.driver).toBe("local");
   });
+
+  // -------------------------------------------------------------------------
+  // agentId is threaded through plugin RPC params (see protocol.ts —
+  // PluginEnvironmentAcquireLeaseParams.agentId and
+  // PluginEnvironmentResumeLeaseParams.agentId). Plugin-backed sandbox
+  // providers can use this to scope lease state (subdirs, PVCs, etc.) per
+  // agent without callbacks or DB lookups. The runtime must forward it when
+  // present and omit it when null/undefined so older plugin SDKs that don't
+  // declare the field aren't surprised.
+  // -------------------------------------------------------------------------
+
+  it("plugin-driver acquireLease: forwards agentId in the RPC payload when present", async () => {
+    const pluginId = randomUUID();
+    const workerManager = {
+      isRunning: vi.fn(() => true),
+      call: vi.fn(async (_pluginId: string, method: string) => {
+        if (method === "environmentAcquireLease") {
+          return { providerLeaseId: "plugin-lease-agent", metadata: { remoteCwd: "/workspace" } };
+        }
+        return undefined;
+      }),
+    } as unknown as PluginWorkerManager;
+    const runtimeWithPlugin = environmentRuntimeService(db, { pluginWorkerManager: workerManager });
+    const { companyId, agentId, environment, runId } = await seedEnvironment({
+      driver: "plugin",
+      name: "Plugin agentId fwd",
+      config: {
+        pluginKey: "acme.environments",
+        driverKey: "fake-plugin",
+        driverConfig: { template: "base" },
+      },
+    });
+    await db.insert(plugins).values({
+      id: pluginId,
+      pluginKey: "acme.environments",
+      packageName: "@acme/paperclip-environments",
+      version: "1.0.0",
+      apiVersion: 1,
+      categories: ["automation"],
+      manifestJson: {
+        id: "acme.environments",
+        apiVersion: 1,
+        version: "1.0.0",
+        displayName: "Acme",
+        description: "Test",
+        author: "Acme",
+        categories: ["automation"],
+        capabilities: ["environment.drivers.register"],
+        entrypoints: { worker: "dist/worker.js" },
+        environmentDrivers: [{ driverKey: "fake-plugin", displayName: "Fake", configSchema: { type: "object" } }],
+      },
+      status: "ready",
+      installOrder: 1,
+      updatedAt: new Date(),
+    } as any);
+
+    await runtimeWithPlugin.acquireRunLease({
+      companyId,
+      environment,
+      issueId: null,
+      agentId,
+      heartbeatRunId: runId,
+      persistedExecutionWorkspace: null,
+    });
+
+    expect(workerManager.call).toHaveBeenCalledWith(
+      pluginId,
+      "environmentAcquireLease",
+      expect.objectContaining({ agentId }),
+    );
+  });
+
+  it("plugin-driver acquireLease: omits agentId from RPC payload when null", async () => {
+    const pluginId = randomUUID();
+    const workerManager = {
+      isRunning: vi.fn(() => true),
+      call: vi.fn(async (_pluginId: string, method: string) => {
+        if (method === "environmentAcquireLease") {
+          return { providerLeaseId: "plugin-lease-no-agent", metadata: { remoteCwd: "/workspace" } };
+        }
+        return undefined;
+      }),
+    } as unknown as PluginWorkerManager;
+    const runtimeWithPlugin = environmentRuntimeService(db, { pluginWorkerManager: workerManager });
+    const { companyId, environment, runId } = await seedEnvironment({
+      driver: "plugin",
+      name: "Plugin agentId null",
+      config: {
+        pluginKey: "acme.environments",
+        driverKey: "fake-plugin",
+        driverConfig: { template: "base" },
+      },
+    });
+    await db.insert(plugins).values({
+      id: pluginId,
+      pluginKey: "acme.environments",
+      packageName: "@acme/paperclip-environments",
+      version: "1.0.0",
+      apiVersion: 1,
+      categories: ["automation"],
+      manifestJson: {
+        id: "acme.environments",
+        apiVersion: 1,
+        version: "1.0.0",
+        displayName: "Acme",
+        description: "Test",
+        author: "Acme",
+        categories: ["automation"],
+        capabilities: ["environment.drivers.register"],
+        entrypoints: { worker: "dist/worker.js" },
+        environmentDrivers: [{ driverKey: "fake-plugin", displayName: "Fake", configSchema: { type: "object" } }],
+      },
+      status: "ready",
+      installOrder: 1,
+      updatedAt: new Date(),
+    } as any);
+
+    await runtimeWithPlugin.acquireRunLease({
+      companyId,
+      environment,
+      issueId: null,
+      agentId: null,
+      heartbeatRunId: runId,
+      persistedExecutionWorkspace: null,
+    });
+
+    const payload = (workerManager.call as ReturnType<typeof vi.fn>).mock.calls.find(
+      ([, method]) => method === "environmentAcquireLease",
+    )?.[2] as Record<string, unknown>;
+    expect(payload).toBeDefined();
+    expect(payload.agentId).toBeUndefined();
+    expect("agentId" in payload).toBe(false);
+  });
+
+  it("sandbox-provider acquireLease: forwards agentId when present", async () => {
+    const pluginId = randomUUID();
+    const workerManager = {
+      isRunning: vi.fn((id: string) => id === pluginId),
+      call: vi.fn(async (_pluginId: string, method: string) => {
+        if (method === "environmentAcquireLease") {
+          return { providerLeaseId: "sandbox-agent-1", metadata: { reuseLease: false } };
+        }
+        throw new Error(`Unexpected plugin method: ${method}`);
+      }),
+    } as unknown as PluginWorkerManager;
+    const runtimeWithPlugin = environmentRuntimeService(db, { pluginWorkerManager: workerManager });
+    const { companyId, agentId, environment, runId } = await seedEnvironment({
+      driver: "sandbox",
+      name: "Sandbox agentId fwd",
+      config: {
+        provider: "fake-plugin",
+        image: "fake:test",
+        timeoutMs: 30_000,
+        reuseLease: false,
+      },
+    });
+    await db.insert(plugins).values({
+      id: pluginId,
+      pluginKey: "acme.sandbox",
+      packageName: "@acme/paperclip-sandbox",
+      version: "1.0.0",
+      apiVersion: 1,
+      categories: ["automation"],
+      manifestJson: {
+        id: "acme.sandbox",
+        apiVersion: 1,
+        version: "1.0.0",
+        displayName: "Acme Sandbox",
+        description: "Test",
+        author: "Acme",
+        categories: ["automation"],
+        capabilities: ["environment.drivers.register"],
+        entrypoints: { worker: "dist/worker.js" },
+        environmentDrivers: [{
+          driverKey: "fake-plugin",
+          kind: "sandbox_provider",
+          displayName: "Fake",
+          configSchema: { type: "object" },
+        }],
+      },
+      status: "ready",
+      installOrder: 1,
+      updatedAt: new Date(),
+    } as any);
+
+    await runtimeWithPlugin.acquireRunLease({
+      companyId,
+      environment,
+      issueId: null,
+      agentId,
+      heartbeatRunId: runId,
+      persistedExecutionWorkspace: null,
+    });
+
+    expect(workerManager.call).toHaveBeenCalledWith(
+      pluginId,
+      "environmentAcquireLease",
+      expect.objectContaining({ agentId }),
+      expect.any(Number),
+    );
+  });
+
+  it("sandbox-provider resumeLease: forwards agentId when present", async () => {
+    const pluginId = randomUUID();
+    const calls: { method: string; params: Record<string, unknown> }[] = [];
+    const workerManager = {
+      isRunning: vi.fn((id: string) => id === pluginId),
+      call: vi.fn(async (_pluginId: string, method: string, params: Record<string, unknown>) => {
+        calls.push({ method, params });
+        if (method === "environmentAcquireLease") {
+          return { providerLeaseId: "sandbox-resume-1", metadata: { reuseLease: true } };
+        }
+        if (method === "environmentResumeLease") {
+          return { providerLeaseId: "sandbox-resume-1", metadata: { reuseLease: true } };
+        }
+        throw new Error(`Unexpected plugin method: ${method}`);
+      }),
+    } as unknown as PluginWorkerManager;
+    const runtimeWithPlugin = environmentRuntimeService(db, { pluginWorkerManager: workerManager });
+    const { companyId, agentId, environment, runId } = await seedEnvironment({
+      driver: "sandbox",
+      name: "Sandbox agentId resume",
+      config: {
+        provider: "fake-plugin",
+        image: "fake:test",
+        timeoutMs: 30_000,
+        reuseLease: true,
+      },
+    });
+    await db.insert(plugins).values({
+      id: pluginId,
+      pluginKey: "acme.sandbox",
+      packageName: "@acme/paperclip-sandbox",
+      version: "1.0.0",
+      apiVersion: 1,
+      categories: ["automation"],
+      manifestJson: {
+        id: "acme.sandbox",
+        apiVersion: 1,
+        version: "1.0.0",
+        displayName: "Acme Sandbox",
+        description: "Test",
+        author: "Acme",
+        categories: ["automation"],
+        capabilities: ["environment.drivers.register"],
+        entrypoints: { worker: "dist/worker.js" },
+        environmentDrivers: [{
+          driverKey: "fake-plugin",
+          kind: "sandbox_provider",
+          displayName: "Fake",
+          configSchema: { type: "object" },
+        }],
+      },
+      status: "ready",
+      installOrder: 1,
+      updatedAt: new Date(),
+    } as any);
+
+    // First acquire seeds a reusable lease row in DB
+    await runtimeWithPlugin.acquireRunLease({
+      companyId,
+      environment,
+      issueId: null,
+      agentId,
+      heartbeatRunId: runId,
+      persistedExecutionWorkspace: null,
+    });
+
+    // Second acquire on the same environment + reuseLease=true exercises the
+    // resume path (host's matcher finds the reusable lease, plugin's
+    // resumeLease is invoked).
+    const newRunId = randomUUID();
+    await db.insert(heartbeatRuns).values({
+      id: newRunId,
+      companyId,
+      agentId,
+      invocationSource: "manual",
+      status: "running",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    } as any);
+    await runtimeWithPlugin.acquireRunLease({
+      companyId,
+      environment,
+      issueId: null,
+      agentId,
+      heartbeatRunId: newRunId,
+      persistedExecutionWorkspace: null,
+    });
+
+    const resumeCall = calls.find((c) => c.method === "environmentResumeLease");
+    expect(resumeCall).toBeDefined();
+    expect(resumeCall?.params.agentId).toBe(agentId);
+  });
 });
diff --git a/server/src/__tests__/environment-selection-route-guards.test.ts b/server/src/__tests__/environment-selection-route-guards.test.ts
index 4c921143..524d58ba 100644
--- a/server/src/__tests__/environment-selection-route-guards.test.ts
+++ b/server/src/__tests__/environment-selection-route-guards.test.ts
@@ -80,6 +80,10 @@ vi.mock("../services/index.js", () => ({
     listApprovalsForIssue: vi.fn(),
     unlink: vi.fn(),
   }),
+  issueRecoveryActionService: () => ({
+    getActiveForIssue: vi.fn(async () => null),
+    listActiveForIssues: vi.fn(async () => new Map()),
+  }),
   documentService: () => ({}),
   routineService: () => ({}),
   workProductService: () => ({}),
diff --git a/server/src/__tests__/git-source.test.ts b/server/src/__tests__/git-source.test.ts
new file mode 100644
index 00000000..4ba1e335
--- /dev/null
+++ b/server/src/__tests__/git-source.test.ts
@@ -0,0 +1,336 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const listServerRefs = vi.fn();
+const cloneFn = vi.fn();
+const walkFn = vi.fn();
+const readBlobFn = vi.fn();
+const resolveRefFn = vi.fn();
+const treeFn = vi.fn((args: unknown) => ({ __tree: args }));
+
+vi.mock("isomorphic-git", () => ({
+  default: {
+    listServerRefs: (...args: unknown[]) => listServerRefs(...args),
+    clone: (...args: unknown[]) => cloneFn(...args),
+    walk: (...args: unknown[]) => walkFn(...args),
+    readBlob: (...args: unknown[]) => readBlobFn(...args),
+    resolveRef: (...args: unknown[]) => resolveRefFn(...args),
+    TREE: (...args: unknown[]) => treeFn(...args),
+  },
+}));
+
+vi.mock("isomorphic-git/http/node", () => ({
+  default: { request: vi.fn() },
+}));
+
+const { parseGitSourceUrl, resolveGitRef, openRepoSnapshot, buildCloneUrl } =
+  await import("../services/git-source.js");
+
+beforeEach(() => {
+  listServerRefs.mockReset();
+  cloneFn.mockReset();
+  walkFn.mockReset();
+  readBlobFn.mockReset();
+  resolveRefFn.mockReset();
+  treeFn.mockClear();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("parseGitSourceUrl", () => {
+  it("parses a bare github repo URL", () => {
+    expect(parseGitSourceUrl("https://github.com/anthropics/claude-code")).toMatchObject({
+      cloneUrl: "https://github.com/anthropics/claude-code.git",
+      hostname: "github.com",
+      owner: "anthropics",
+      repo: "claude-code",
+      ref: null,
+      basePath: "",
+      filePath: null,
+      explicitRef: false,
+    });
+  });
+
+  it("strips trailing .git from the repo segment", () => {
+    expect(parseGitSourceUrl("https://example.com/o/r.git")).toMatchObject({
+      cloneUrl: "https://example.com/o/r.git",
+      repo: "r",
+    });
+  });
+
+  it("parses a github tree URL with subpath", () => {
+    expect(
+      parseGitSourceUrl("https://github.com/o/r/tree/develop/sub/dir"),
+    ).toMatchObject({
+      ref: "develop",
+      basePath: "sub/dir",
+      filePath: null,
+      explicitRef: true,
+    });
+  });
+
+  it("parses a github blob URL as a file path", () => {
+    expect(
+      parseGitSourceUrl("https://github.com/o/r/blob/main/path/to/file.md"),
+    ).toMatchObject({
+      ref: "main",
+      basePath: "path/to",
+      filePath: "path/to/file.md",
+      explicitRef: true,
+    });
+  });
+
+  it("parses a gitea src/branch URL with subpath", () => {
+    expect(
+      parseGitSourceUrl("https://git.example.com/o/r/src/branch/main/skills"),
+    ).toMatchObject({
+      cloneUrl: "https://git.example.com/o/r.git",
+      ref: "main",
+      basePath: "skills",
+      filePath: null,
+      explicitRef: true,
+    });
+  });
+
+  it("parses a gitea src/tag URL", () => {
+    expect(
+      parseGitSourceUrl("https://git.example.com/o/r/src/tag/v1.2.3"),
+    ).toMatchObject({
+      ref: "v1.2.3",
+      basePath: "",
+      explicitRef: true,
+    });
+  });
+
+  it("parses a gitea src/commit URL with file", () => {
+    expect(
+      parseGitSourceUrl("https://git.example.com/o/r/src/commit/abc123/dir/SKILL.md"),
+    ).toMatchObject({
+      ref: "abc123",
+      basePath: "dir",
+      filePath: "dir/SKILL.md",
+    });
+  });
+
+  it("parses a gitlab tree URL", () => {
+    expect(
+      parseGitSourceUrl("https://gitlab.com/group/proj/-/tree/main/sub"),
+    ).toMatchObject({
+      cloneUrl: "https://gitlab.com/group/proj.git",
+      ref: "main",
+      basePath: "sub",
+      explicitRef: true,
+    });
+  });
+
+  it("parses a gitlab blob URL", () => {
+    expect(
+      parseGitSourceUrl("https://gitlab.com/group/proj/-/blob/main/sub/file.md"),
+    ).toMatchObject({
+      ref: "main",
+      filePath: "sub/file.md",
+      basePath: "sub",
+    });
+  });
+
+  it("rejects non-https URLs", () => {
+    expect(() => parseGitSourceUrl("http://github.com/o/r")).toThrow(/HTTPS/);
+  });
+
+  it("rejects URLs without owner/repo", () => {
+    expect(() => parseGitSourceUrl("https://github.com/o")).toThrow();
+  });
+
+  it("rejects malformed URLs", () => {
+    expect(() => parseGitSourceUrl("not a url")).toThrow();
+  });
+});
+
+describe("buildCloneUrl", () => {
+  it("produces a .git suffix URL on the given host", () => {
+    expect(buildCloneUrl("git.example.com", "o", "r")).toBe(
+      "https://git.example.com/o/r.git",
+    );
+  });
+});
+
+describe("resolveGitRef", () => {
+  it("passes through a 40-hex SHA without hitting the network", async () => {
+    const parsed = parseGitSourceUrl(
+      "https://github.com/o/r/tree/0123456789abcdef0123456789abcdef01234567",
+    );
+    const result = await resolveGitRef(parsed);
+    expect(result).toEqual({
+      pinnedSha: "0123456789abcdef0123456789abcdef01234567",
+      trackingRef: "0123456789abcdef0123456789abcdef01234567",
+    });
+    expect(listServerRefs).not.toHaveBeenCalled();
+  });
+
+  it("returns default branch via HEAD symref when ref is absent", async () => {
+    listServerRefs.mockResolvedValue([
+      { ref: "HEAD", oid: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", target: "refs/heads/main" },
+      { ref: "refs/heads/main", oid: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" },
+      { ref: "refs/heads/chore", oid: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" },
+    ]);
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r");
+    const result = await resolveGitRef(parsed);
+    expect(result).toEqual({
+      pinnedSha: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      trackingRef: "main",
+    });
+    expect(listServerRefs).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: "https://git.example.com/o/r.git",
+        symrefs: true,
+        protocolVersion: 2,
+      }),
+    );
+  });
+
+  it("resolves a named branch to its SHA", async () => {
+    listServerRefs.mockResolvedValue([
+      { ref: "HEAD", oid: "1111111111111111111111111111111111111111", target: "refs/heads/main" },
+      { ref: "refs/heads/main", oid: "1111111111111111111111111111111111111111" },
+      { ref: "refs/heads/develop", oid: "2222222222222222222222222222222222222222" },
+    ]);
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r/src/branch/develop");
+    const result = await resolveGitRef(parsed);
+    expect(result).toEqual({
+      pinnedSha: "2222222222222222222222222222222222222222",
+      trackingRef: "develop",
+    });
+  });
+
+  it("prefers a peeled annotated tag over the tag object", async () => {
+    listServerRefs.mockResolvedValue([
+      { ref: "refs/tags/v1.0", oid: "tttttttttttttttttttttttttttttttttttttttt" },
+      { ref: "refs/tags/v1.0^{}", oid: "cccccccccccccccccccccccccccccccccccccccc" },
+    ]);
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r/src/tag/v1.0");
+    const result = await resolveGitRef(parsed);
+    expect(result.pinnedSha).toBe("cccccccccccccccccccccccccccccccccccccccc");
+    expect(result.trackingRef).toBe("v1.0");
+  });
+
+  it("resolves a lightweight tag when no peeled entry exists", async () => {
+    listServerRefs.mockResolvedValue([
+      { ref: "refs/tags/v2.0", oid: "dddddddddddddddddddddddddddddddddddddddd" },
+    ]);
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r/src/tag/v2.0");
+    const result = await resolveGitRef(parsed);
+    expect(result.pinnedSha).toBe("dddddddddddddddddddddddddddddddddddddddd");
+  });
+
+  it("throws when an explicit ref does not exist", async () => {
+    listServerRefs.mockResolvedValue([
+      { ref: "HEAD", oid: "9999999999999999999999999999999999999999", target: "refs/heads/main" },
+      { ref: "refs/heads/main", oid: "9999999999999999999999999999999999999999" },
+    ]);
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r/src/branch/missing");
+    await expect(resolveGitRef(parsed)).rejects.toThrow(/Ref 'missing' not found/);
+  });
+
+  it("translates network errors into a user-facing message", async () => {
+    listServerRefs.mockRejectedValue(new Error("ENOTFOUND git.invalid"));
+    const parsed = parseGitSourceUrl("https://git.invalid/o/r");
+    await expect(resolveGitRef(parsed)).rejects.toThrow(/could not connect/i);
+  });
+
+  it("translates 401 errors into an auth message", async () => {
+    listServerRefs.mockRejectedValue(new Error("HTTP Error: 401 Unauthorized"));
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r");
+    await expect(resolveGitRef(parsed)).rejects.toThrow(/authentication/i);
+  });
+
+  it("translates 404 errors into a repo-not-found message", async () => {
+    listServerRefs.mockRejectedValue(new Error("HTTP Error: 404 Not Found"));
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r");
+    await expect(resolveGitRef(parsed)).rejects.toThrow(/repository not found/i);
+  });
+
+  it("sends an onAuth callback when a token is supplied", async () => {
+    listServerRefs.mockResolvedValue([
+      { ref: "HEAD", oid: "1111111111111111111111111111111111111111", target: "refs/heads/main" },
+      { ref: "refs/heads/main", oid: "1111111111111111111111111111111111111111" },
+    ]);
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r");
+    await resolveGitRef(parsed, "tok_abc");
+    const callArgs = listServerRefs.mock.calls[0]![0] as { onAuth: () => unknown };
+    expect(typeof callArgs.onAuth).toBe("function");
+    expect(callArgs.onAuth()).toEqual({ username: "tok_abc", password: "x-oauth-basic" });
+  });
+
+  it("omits onAuth when no token is supplied", async () => {
+    listServerRefs.mockResolvedValue([
+      { ref: "HEAD", oid: "1111111111111111111111111111111111111111", target: "refs/heads/main" },
+      { ref: "refs/heads/main", oid: "1111111111111111111111111111111111111111" },
+    ]);
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r");
+    await resolveGitRef(parsed);
+    const callArgs = listServerRefs.mock.calls[0]![0] as { onAuth?: unknown };
+    expect(callArgs.onAuth).toBeUndefined();
+  });
+});
+
+describe("openRepoSnapshot", () => {
+  it("clones at the tracking ref and walks the tree at the resolved SHA", async () => {
+    cloneFn.mockResolvedValue(undefined);
+    resolveRefFn.mockResolvedValue("ffffffffffffffffffffffffffffffffffffffff");
+    walkFn.mockImplementation(async ({ map }: { map: (filepath: string, entries: Array<{ type: () => Promise<string> }>) => Promise<void> }) => {
+      await map(".", [{ type: () => Promise.resolve("tree") }]);
+      await map("README.md", [{ type: () => Promise.resolve("blob") }]);
+      await map("skills/x/SKILL.md", [{ type: () => Promise.resolve("blob") }]);
+      await map("skills/x", [{ type: () => Promise.resolve("tree") }]);
+    });
+    readBlobFn.mockResolvedValue({ blob: new TextEncoder().encode("hello") });
+
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r");
+    const snap = await openRepoSnapshot(parsed, "main", "ffffffffffffffffffffffffffffffffffffffff", "tok");
+
+    expect(cloneFn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: "https://git.example.com/o/r.git",
+        ref: "main",
+        singleBranch: true,
+        depth: 1,
+        noCheckout: true,
+      }),
+    );
+    expect(snap.sha).toBe("ffffffffffffffffffffffffffffffffffffffff");
+
+    const files = await snap.listFiles();
+    expect(files).toEqual(["README.md", "skills/x/SKILL.md"]);
+
+    const content = await snap.readFile("README.md");
+    expect(content).toBe("hello");
+    expect(readBlobFn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        oid: "ffffffffffffffffffffffffffffffffffffffff",
+        filepath: "README.md",
+      }),
+    );
+  });
+
+  it("falls back to the expected SHA as ref when no tracking ref is known", async () => {
+    cloneFn.mockResolvedValue(undefined);
+    resolveRefFn.mockResolvedValue("abc1234567890abc1234567890abc1234567890a");
+    walkFn.mockImplementation(async () => {});
+
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r");
+    await openRepoSnapshot(parsed, null, "abc1234567890abc1234567890abc1234567890a");
+
+    expect(cloneFn).toHaveBeenCalledWith(
+      expect.objectContaining({ ref: "abc1234567890abc1234567890abc1234567890a" }),
+    );
+  });
+
+  it("surfaces a 404 from clone as repository-not-found", async () => {
+    cloneFn.mockRejectedValue(new Error("HTTP Error: 404 Not Found"));
+    const parsed = parseGitSourceUrl("https://git.example.com/o/r");
+    await expect(
+      openRepoSnapshot(parsed, "main", "1111111111111111111111111111111111111111"),
+    ).rejects.toThrow(/repository not found/i);
+  });
+});
diff --git a/server/src/__tests__/heartbeat-process-recovery.test.ts b/server/src/__tests__/heartbeat-process-recovery.test.ts
index 45842b42..58c86b96 100644
--- a/server/src/__tests__/heartbeat-process-recovery.test.ts
+++ b/server/src/__tests__/heartbeat-process-recovery.test.ts
@@ -20,6 +20,7 @@ import {
   heartbeatRuns,
   issueComments,
   issueDocuments,
+  issueRecoveryActions,
   issueRelations,
   issueTreeHoldMembers,
   issueTreeHolds,
@@ -328,6 +329,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     await db.delete(documentRevisions);
     await db.delete(documents);
     await db.delete(issueRelations);
+    await db.delete(issueRecoveryActions);
     await db.delete(issueTreeHoldMembers);
     await db.delete(issueTreeHolds);
     for (let attempt = 0; attempt < 5; attempt += 1) {
@@ -692,67 +694,76 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     return { companyId, agentId, issueId };
   }
 
-  async function expectStrandedRecoveryArtifacts(input: {
+  async function expectSourceScopedStrandedRecoveryAction(input: {
     companyId: string;
     agentId: string;
     issueId: string;
     runId: string;
     previousStatus: "todo" | "in_progress";
-    retryReason: "assignment_recovery" | "issue_continuation_needed";
+    retryReason?: "assignment_recovery" | "issue_continuation_needed" | null;
+    cause?: string;
+    kind?: string;
   }) {
-    const recovery = await waitForValue(async () =>
-      db.select().from(issues).where(
+    const action = await waitForValue(async () =>
+      db.select().from(issueRecoveryActions).where(
         and(
-          eq(issues.companyId, input.companyId),
-          eq(issues.originKind, "stranded_issue_recovery"),
-          eq(issues.originId, input.issueId),
+          eq(issueRecoveryActions.companyId, input.companyId),
+          eq(issueRecoveryActions.sourceIssueId, input.issueId),
         ),
       ).then((rows) => rows[0] ?? null),
     );
-    if (!recovery) throw new Error("Expected stranded issue recovery issue to be created");
+    if (!action) throw new Error("Expected source-scoped stranded recovery action to be created");
 
-    expect(recovery).toMatchObject({
+    expect(action).toMatchObject({
       companyId: input.companyId,
-      parentId: input.issueId,
-      assigneeAgentId: input.agentId,
-      originKind: "stranded_issue_recovery",
-      originId: input.issueId,
-      originRunId: input.runId,
-      priority: "medium",
-      assigneeAdapterOverrides: { modelProfile: "cheap" },
+      sourceIssueId: input.issueId,
+      recoveryIssueId: null,
+      kind: input.kind ?? "stranded_assigned_issue",
+      status: "active",
+      ownerType: "agent",
+      ownerAgentId: input.agentId,
+      previousOwnerAgentId: input.agentId,
+      returnOwnerAgentId: input.agentId,
+      cause: input.cause ?? "stranded_assigned_issue",
+      attemptCount: 1,
+      maxAttempts: null,
     });
-    expect(recovery.title).toContain("Recover stalled issue");
-    expect(recovery.description).toContain(`Previous source status: \`${input.previousStatus}\``);
-    expect(recovery.description).toContain(`Retry reason: \`${input.retryReason}\``);
-    expect(recovery.description).toContain("Fix the runtime/adapter problem");
+    expect(action.evidence).toMatchObject({
+      sourceIssueId: input.issueId,
+      previousStatus: input.previousStatus,
+      latestRunId: input.runId,
+      retryReason: input.retryReason ?? null,
+    });
+    expect(action.nextAction).toContain(
+      input.kind === "missing_disposition" ? "valid issue disposition" : "Restore a live execution path",
+    );
 
-    const relation = await db
+    const recoveryIssues = await db
       .select()
-      .from(issueRelations)
-      .where(
-        and(
-          eq(issueRelations.companyId, input.companyId),
-          eq(issueRelations.issueId, recovery.id),
-          eq(issueRelations.relatedIssueId, input.issueId),
-          eq(issueRelations.type, "blocks"),
-        ),
-      )
-      .then((rows) => rows[0] ?? null);
-    expect(relation).toBeTruthy();
+      .from(issues)
+      .where(and(
+        eq(issues.companyId, input.companyId),
+        eq(issues.originKind, "stranded_issue_recovery"),
+        eq(issues.originId, input.issueId),
+      ));
+    expect(recoveryIssues).toHaveLength(0);
 
-    const wakeups = await db
-      .select()
-      .from(agentWakeupRequests)
-      .where(eq(agentWakeupRequests.agentId, input.agentId));
-    const recoveryWakeup = wakeups.find((wakeup) => {
-      const payload = wakeup.payload as Record<string, unknown> | null;
-      return payload?.issueId === recovery.id &&
-        payload?.sourceIssueId === input.issueId &&
-        payload?.strandedRunId === input.runId;
+    const recoveryWakeup = await waitForValue(async () => {
+      const wakeups = await db
+        .select()
+        .from(agentWakeupRequests)
+        .where(eq(agentWakeupRequests.agentId, input.agentId));
+      return wakeups.find((wakeup) => {
+        const payload = wakeup.payload as Record<string, unknown> | null;
+        return payload?.issueId === input.issueId &&
+          payload?.sourceIssueId === input.issueId &&
+          payload?.recoveryActionId === action.id &&
+          payload?.strandedRunId === input.runId;
+      }) ?? null;
     });
     expect(recoveryWakeup).toMatchObject({
       companyId: input.companyId,
-      reason: "issue_assigned",
+      reason: "source_scoped_recovery_action",
       source: "assignment",
       payload: expect.objectContaining({ modelProfile: "cheap" }),
     });
@@ -765,15 +776,23 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
         .then((rows) => rows[0] ?? null)
       : null;
     expect(recoveryRun?.contextSnapshot).toMatchObject({
-      issueId: recovery.id,
-      taskId: recovery.id,
-      source: "stranded_issue_recovery",
+      issueId: input.issueId,
+      taskId: input.issueId,
+      source: "issue_recovery_action",
+      recoveryActionId: action.id,
       sourceIssueId: input.issueId,
       strandedRunId: input.runId,
       modelProfile: "cheap",
     });
+    await waitForHeartbeatIdle(db);
+    const sourceIssue = await db
+      .select()
+      .from(issues)
+      .where(eq(issues.id, input.issueId))
+      .then((rows) => rows[0] ?? null);
+    expect(sourceIssue?.status).toBe("blocked");
 
-    return recovery;
+    return action;
   }
 
   async function sourceBlockerIssueIds(companyId: string, sourceIssueId: string) {
@@ -1056,7 +1075,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     expect(blockedIssue?.checkoutRunId).toBeNull();
     if (!continuationRun?.id) throw new Error("Expected continuation recovery run to exist");
 
-    const recovery = await expectStrandedRecoveryArtifacts({
+    const recoveryAction = await expectSourceScopedStrandedRecoveryAction({
       companyId,
       agentId,
       issueId,
@@ -1065,17 +1084,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
       retryReason: "issue_continuation_needed",
     });
 
-    const blockerRelations = await db
-      .select()
-      .from(issueRelations)
-      .where(
-        and(
-          eq(issueRelations.companyId, companyId),
-          eq(issueRelations.relatedIssueId, issueId),
-          eq(issueRelations.type, "blocks"),
-        ),
-      );
-    expect(blockerRelations.map((relation) => relation.issueId)).toEqual([recovery.id]);
+    await expect(sourceBlockerIssueIds(companyId, issueId)).resolves.toEqual([]);
 
     const comments = await waitForValue(async () => {
       const rows = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));
@@ -1083,7 +1092,8 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     });
     expect(comments).toHaveLength(1);
     expect(comments[0]?.body).toContain("retried continuation");
-    expect(comments[0]?.body).toContain(`Recovery issue: [${recovery.identifier}]`);
+    expect(comments[0]?.body).toContain(`Recovery action: \`${recoveryAction.id}\``);
+    expect(comments[0]?.body).toContain("Recovery owner: [CodexCoder]");
   });
 
   it("blocks failed recovery work in place during immediate terminal-run cleanup", async () => {
@@ -1600,27 +1610,28 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     expect(result.successfulRunHandoffEscalated).toBe(1);
     expect(result.issueIds).toEqual([issueId]);
 
-    const recovery = await waitForValue(async () =>
-      db.select().from(issues).where(
-        and(
-          eq(issues.companyId, companyId),
-          eq(issues.originKind, "stranded_issue_recovery"),
-          eq(issues.originId, issueId),
-        ),
-      ).then((rows) => rows[0] ?? null),
-    );
-    expect(recovery?.assigneeAgentId).toBe(agentId);
-    expect(recovery?.title).toContain("Recover missing next step");
-    expect(recovery?.description).toContain("Normalized cause: `successful_run_missing_state`");
-    expect(recovery?.description).toContain("not a runtime/adapter crash report");
-    expect(recovery?.description).toContain(`Source run: [\`${sourceRunId}\`]`);
-    expect(recovery?.description).toContain("Missing disposition: `clear_next_step`");
-    expect(recovery?.description).toContain("Source assignee: [CodexCoder]");
-    expect(recovery?.description).not.toContain("sk-test-successful-handoff-secret");
+    const recoveryAction = await expectSourceScopedStrandedRecoveryAction({
+      companyId,
+      agentId,
+      issueId,
+      runId,
+      previousStatus: "in_progress",
+      retryReason: null,
+      cause: SUCCESSFUL_RUN_MISSING_STATE_REASON,
+      kind: "missing_disposition",
+    });
+    expect(recoveryAction.evidence).toMatchObject({
+      sourceRunId,
+      missingDisposition: "clear_next_step",
+      latestRunStatus: "failed",
+      latestRunErrorCode: "adapter_failed",
+      recoveryCause: SUCCESSFUL_RUN_MISSING_STATE_REASON,
+    });
+    expect(JSON.stringify(recoveryAction.evidence)).not.toContain("sk-test-successful-handoff-secret");
 
     const sourceIssue = await db.select().from(issues).where(eq(issues.id, issueId)).then((rows) => rows[0] ?? null);
     expect(sourceIssue?.status).toBe("blocked");
-    await expect(sourceBlockerIssueIds(companyId, issueId)).resolves.toEqual([recovery?.id]);
+    await expect(sourceBlockerIssueIds(companyId, issueId)).resolves.toEqual([]);
 
     const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));
     expect(comments[0]?.body).toBe(SUCCESSFUL_RUN_HANDOFF_EXHAUSTED_NOTICE_BODY);
@@ -1636,7 +1647,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
         expect.objectContaining({
           title: "Recovery owner",
           rows: expect.arrayContaining([
-            expect.objectContaining({ type: "issue_link", identifier: recovery?.identifier }),
+            expect.objectContaining({ type: "key_value", label: "Recovery action", value: recoveryAction.id }),
             expect.objectContaining({ type: "agent_link", label: "Recovery owner", name: "CodexCoder" }),
           ]),
         }),
@@ -1657,7 +1668,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
   });
 
   it("escalates an exhausted successful handoff run that still leaves no disposition", async () => {
-    const { companyId, runId, issueId } = await seedStrandedIssueFixture({
+    const { companyId, agentId, runId, issueId } = await seedStrandedIssueFixture({
       status: "in_progress",
       runStatus: "succeeded",
       livenessState: "advanced",
@@ -1687,17 +1698,21 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     expect(result.successfulContinuationObserved).toBe(0);
     expect(result.successfulRunHandoffEscalated).toBe(1);
 
-    const recovery = await waitForValue(async () =>
-      db.select().from(issues).where(
-        and(
-          eq(issues.companyId, companyId),
-          eq(issues.originKind, "stranded_issue_recovery"),
-          eq(issues.originId, issueId),
-        ),
-      ).then((rows) => rows[0] ?? null),
-    );
-    expect(recovery?.description).toContain("Latest handoff run status: `succeeded`");
-    expect(recovery?.description).toContain("Suggested");
+    const recoveryAction = await expectSourceScopedStrandedRecoveryAction({
+      companyId,
+      agentId,
+      issueId,
+      runId,
+      previousStatus: "in_progress",
+      retryReason: null,
+      cause: SUCCESSFUL_RUN_MISSING_STATE_REASON,
+      kind: "missing_disposition",
+    });
+    expect(recoveryAction.evidence).toMatchObject({
+      sourceRunId,
+      latestRunStatus: "succeeded",
+      missingDisposition: "clear_next_step",
+    });
   });
 
   it("clears the detached warning when the run reports activity again", async () => {
@@ -2063,7 +2078,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     const issue = await db.select().from(issues).where(eq(issues.id, issueId)).then((rows) => rows[0] ?? null);
     expect(issue?.status).toBe("blocked");
 
-    const recovery = await expectStrandedRecoveryArtifacts({
+    const recoveryAction = await expectSourceScopedStrandedRecoveryAction({
       companyId,
       agentId,
       issueId,
@@ -2071,13 +2086,14 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
       previousStatus: "todo",
       retryReason: "assignment_recovery",
     });
-    expect(recovery.description ?? "").not.toContain("sk-test-recovery-secret");
+    expect(JSON.stringify(recoveryAction.evidence)).not.toContain("sk-test-recovery-secret");
 
     const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));
     expect(comments).toHaveLength(1);
     expect(comments[0]?.body).toContain("retried dispatch");
     expect(comments[0]?.body).toContain("Latest retry failure details were withheld from the issue thread");
-    expect(comments[0]?.body).toContain(`Recovery issue: [${recovery.identifier}]`);
+    expect(comments[0]?.body).toContain(`Recovery action: \`${recoveryAction.id}\``);
+    expect(comments[0]?.body).toContain("Recovery owner: [CodexCoder]");
   });
 
   it("blocks an already stranded recovery issue without creating a recovery child", async () => {
@@ -2457,7 +2473,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     const issue = await db.select().from(issues).where(eq(issues.id, issueId)).then((rows) => rows[0] ?? null);
     expect(issue?.status).toBe("blocked");
 
-    const recovery = await expectStrandedRecoveryArtifacts({
+    const recoveryAction = await expectSourceScopedStrandedRecoveryAction({
       companyId,
       agentId,
       issueId,
@@ -2470,7 +2486,8 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     expect(comments).toHaveLength(1);
     expect(comments[0]?.body).toContain("retried continuation");
     expect(comments[0]?.body).toContain("Latest retry failure details were withheld from the issue thread");
-    expect(comments[0]?.body).toContain(`Recovery issue: [${recovery.identifier}]`);
+    expect(comments[0]?.body).toContain(`Recovery action: \`${recoveryAction.id}\``);
+    expect(comments[0]?.body).toContain("Recovery owner: [CodexCoder]");
   });
 
   it("redacts error-code-only stranded recovery failures in issue copy", async () => {
@@ -2486,7 +2503,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     const result = await heartbeat.reconcileStrandedAssignedIssues();
     expect(result.escalated).toBe(1);
 
-    const recovery = await expectStrandedRecoveryArtifacts({
+    const recoveryAction = await expectSourceScopedStrandedRecoveryAction({
       companyId,
       agentId,
       issueId,
@@ -2494,8 +2511,10 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
       previousStatus: "in_progress",
       retryReason: "issue_continuation_needed",
     });
-    expect(recovery.description).toContain("Latest retry failure details were withheld from the issue thread");
-    expect(recovery.description).not.toContain("- Failure: none recorded");
+    expect(recoveryAction.evidence).toMatchObject({
+      latestRunErrorCode: "adapter_exit_code",
+    });
+    expect(JSON.stringify(recoveryAction.evidence)).not.toContain("- Failure: none recorded");
 
     const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, issueId));
     expect(comments).toHaveLength(1);
@@ -2516,6 +2535,15 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     );
     expect(results.every((result) => result.status === "fulfilled")).toBe(true);
 
+    const actions = await db
+      .select()
+      .from(issueRecoveryActions)
+      .where(and(
+        eq(issueRecoveryActions.companyId, companyId),
+        eq(issueRecoveryActions.sourceIssueId, issueId),
+      ));
+    expect(actions).toHaveLength(1);
+    expect(actions[0]?.attemptCount).toBeGreaterThanOrEqual(1);
     const recoveries = await db
       .select()
       .from(issues)
@@ -2524,8 +2552,8 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
         eq(issues.originKind, "stranded_issue_recovery"),
         eq(issues.originId, issueId),
       ));
-    expect(recoveries).toHaveLength(1);
-    await expect(sourceBlockerIssueIds(companyId, issueId)).resolves.toEqual([recoveries[0]?.id]);
+    expect(recoveries).toHaveLength(0);
+    await expect(sourceBlockerIssueIds(companyId, issueId)).resolves.toEqual([]);
   });
 
   it("blocks stranded recovery issues in place instead of creating nested recovery issues", async () => {
@@ -2783,7 +2811,7 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     const issue = await db.select().from(issues).where(eq(issues.id, issueId)).then((rows) => rows[0] ?? null);
     expect(issue?.status).toBe("blocked");
 
-    const recovery = await expectStrandedRecoveryArtifacts({
+    const recoveryAction = await expectSourceScopedStrandedRecoveryAction({
       companyId,
       agentId,
       issueId,
@@ -2796,7 +2824,8 @@ describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
     expect(comments).toHaveLength(1);
     expect(comments[0]?.body).toContain("automatically retried continuation");
     expect(comments[0]?.body).toContain("still has no live execution path");
-    expect(comments[0]?.body).toContain(`Recovery issue: [${recovery.identifier}]`);
+    expect(comments[0]?.body).toContain(`Recovery action: \`${recoveryAction.id}\``);
+    expect(comments[0]?.body).toContain("Recovery owner: [CodexCoder]");
   });
 
   it("allows one productive-terminal recovery after regular continuation recovery made progress", async () => {
diff --git a/server/src/__tests__/issue-activity-events-routes.test.ts b/server/src/__tests__/issue-activity-events-routes.test.ts
index 14349614..6a6c3b92 100644
--- a/server/src/__tests__/issue-activity-events-routes.test.ts
+++ b/server/src/__tests__/issue-activity-events-routes.test.ts
@@ -89,6 +89,10 @@ function registerModuleMocks() {
     heartbeatService: () => mockHeartbeatService,
     instanceSettingsService: () => mockInstanceSettingsService,
     issueApprovalService: () => ({}),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueReferenceService: () => ({
       deleteDocumentSource: async () => undefined,
       diffIssueReferenceSummary: () => ({
diff --git a/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts b/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts
index 211c952c..a4d1d9f7 100644
--- a/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts
+++ b/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts
@@ -60,6 +60,9 @@ const mockIssueThreadInteractionService = vi.hoisted(() => ({
   expireRequestConfirmationsSupersededByComment: vi.fn(async () => []),
   expireStaleRequestConfirmationsForIssueDocument: vi.fn(async () => []),
 }));
+const mockIssueRecoveryActionService = vi.hoisted(() => ({
+  getActiveForIssue: vi.fn(async () => null),
+}));
 
 function registerRouteMocks() {
   vi.doMock("@paperclipai/shared/telemetry", () => ({
@@ -124,6 +127,7 @@ function registerRouteMocks() {
       listCompanyIds: vi.fn(async () => [companyId]),
     }),
     issueApprovalService: () => ({}),
+    issueRecoveryActionService: () => mockIssueRecoveryActionService,
     issueReferenceService: () => ({
       deleteDocumentSource: async () => undefined,
       diffIssueReferenceSummary: () => ({
@@ -259,6 +263,8 @@ describe("agent issue mutation checkout ownership", () => {
     mockIssueService.getWakeableParentAfterChildCompletion.mockReset();
     mockIssueService.listAttachments.mockReset();
     mockIssueService.listWakeableBlockedDependents.mockReset();
+    mockIssueRecoveryActionService.getActiveForIssue.mockReset();
+    mockIssueRecoveryActionService.getActiveForIssue.mockResolvedValue(null);
     mockIssueService.remove.mockReset();
     mockIssueService.removeAttachment.mockReset();
     mockIssueService.update.mockReset();
diff --git a/server/src/__tests__/issue-assigned-backlog-contract-routes.test.ts b/server/src/__tests__/issue-assigned-backlog-contract-routes.test.ts
index 81cb0598..a251181e 100644
--- a/server/src/__tests__/issue-assigned-backlog-contract-routes.test.ts
+++ b/server/src/__tests__/issue-assigned-backlog-contract-routes.test.ts
@@ -59,6 +59,10 @@ vi.mock("../services/index.js", () => ({
     listCompanyIds: vi.fn(async () => ["company-1"]),
   }),
   issueApprovalService: () => ({}),
+  issueRecoveryActionService: () => ({
+    getActiveForIssue: vi.fn(async () => null),
+    listActiveForIssues: vi.fn(async () => new Map()),
+  }),
   issueReferenceService: () => ({
     deleteDocumentSource: async () => undefined,
     diffIssueReferenceSummary: () => ({
diff --git a/server/src/__tests__/issue-attachment-routes.test.ts b/server/src/__tests__/issue-attachment-routes.test.ts
index 866f39d2..6a737903 100644
--- a/server/src/__tests__/issue-attachment-routes.test.ts
+++ b/server/src/__tests__/issue-attachment-routes.test.ts
@@ -81,6 +81,10 @@ function registerRouteMocks() {
       syncDocument: async () => undefined,
       syncIssue: async () => undefined,
     }),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueService: () => mockIssueService,
     logActivity: mockLogActivity,
     projectService: () => ({}),
diff --git a/server/src/__tests__/issue-blocker-attention.test.ts b/server/src/__tests__/issue-blocker-attention.test.ts
index 71e66c80..7fdb91e5 100644
--- a/server/src/__tests__/issue-blocker-attention.test.ts
+++ b/server/src/__tests__/issue-blocker-attention.test.ts
@@ -2,12 +2,16 @@ import { randomUUID } from "node:crypto";
 import { eq } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import {
+  activityLog,
   agents,
   agentWakeupRequests,
+  approvals,
   companies,
   createDb,
   heartbeatRuns,
+  issueApprovals,
   issueRelations,
+  issueThreadInteractions,
   issues,
 } from "@paperclipai/db";
 import {
@@ -15,6 +19,7 @@ import {
   startEmbeddedPostgresTestDatabase,
 } from "./helpers/embedded-postgres.js";
 import { issueService } from "../services/issues.js";
+import { buildIssueGraphLivenessIncidentKey } from "../services/recovery/origins.js";
 
 const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
 const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
@@ -37,6 +42,10 @@ describeEmbeddedPostgres("issue blocker attention", () => {
   }, 20_000);
 
   afterEach(async () => {
+    await db.delete(issueThreadInteractions);
+    await db.delete(issueApprovals);
+    await db.delete(approvals);
+    await db.delete(activityLog);
     await db.delete(heartbeatRuns);
     await db.delete(agentWakeupRequests);
     await db.delete(issueRelations);
@@ -52,20 +61,30 @@ describeEmbeddedPostgres("issue blocker attention", () => {
   async function createCompany(prefix = "PBA") {
     const companyId = randomUUID();
     const agentId = randomUUID();
+    const pausedAgentId = randomUUID();
     await db.insert(companies).values({
       id: companyId,
       name: `Company ${prefix}`,
       issuePrefix: prefix,
       requireBoardApprovalForNewAgents: false,
     });
-    await db.insert(agents).values({
-      id: agentId,
-      companyId,
-      name: `${prefix} Agent`,
-      role: "engineer",
-      status: "idle",
-    });
-    return { companyId, agentId };
+    await db.insert(agents).values([
+      {
+        id: agentId,
+        companyId,
+        name: `${prefix} Agent`,
+        role: "engineer",
+        status: "idle",
+      },
+      {
+        id: pausedAgentId,
+        companyId,
+        name: `${prefix} Paused`,
+        role: "engineer",
+        status: "paused",
+      },
+    ]);
+    return { companyId, agentId, pausedAgentId };
   }
 
   async function insertIssue(input: {
@@ -80,6 +99,8 @@ describeEmbeddedPostgres("issue blocker attention", () => {
     originKind?: string | null;
     originId?: string | null;
     originFingerprint?: string | null;
+    executionState?: Record<string, unknown> | null;
+    description?: string | null;
   }) {
     const id = input.id ?? randomUUID();
     await db.insert(issues).values({
@@ -95,6 +116,8 @@ describeEmbeddedPostgres("issue blocker attention", () => {
       originKind: input.originKind ?? "manual",
       originId: input.originId ?? null,
       originFingerprint: input.originFingerprint ?? "default",
+      executionState: input.executionState ?? null,
+      description: input.description ?? null,
     });
     return id;
   }
@@ -483,4 +506,192 @@ describeEmbeddedPostgres("issue blocker attention", () => {
       sampleBlockerIdentifier: "PBY-2",
     });
   });
+
+  it("returns blocked inbox attention for an unassigned blocker leaf and supports count/search", async () => {
+    const { companyId } = await createCompany("BIA");
+    const parentId = await insertIssue({ companyId, identifier: "BIA-1", title: "Blocked source", status: "blocked" });
+    const blockerId = await insertIssue({
+      companyId,
+      identifier: "BIA-2",
+      title: "Unassigned leaf",
+      status: "todo",
+    });
+    await block({ companyId, blockerIssueId: blockerId, blockedIssueId: parentId });
+
+    const rows = await svc.list(companyId, { attention: "blocked", q: "BIA-2" });
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.id).toBe(parentId);
+    expect(rows[0]?.blockedBy).toEqual([
+      expect.objectContaining({ id: blockerId, identifier: "BIA-2" }),
+    ]);
+    expect(rows[0]?.blockedInboxAttention).toMatchObject({
+      kind: "blocked",
+      state: "needs_attention",
+      reason: "blocked_by_unassigned_issue",
+      severity: "critical",
+      owner: { type: "unknown", agentId: null, userId: null },
+      action: { label: "Assign blocker" },
+      leafIssue: { id: blockerId, identifier: "BIA-2" },
+      redaction: { secretFieldsOmitted: true },
+    });
+    await expect(svc.count(companyId, { attention: "blocked" })).resolves.toBe(1);
+  });
+
+  it("redacts external wait details from blocked inbox payloads and search", async () => {
+    const { companyId } = await createCompany("BIX");
+    const owner = "Private Vendor Security Team";
+    const action = "Send the confidential access token for customer Alpha";
+    const issueId = await insertIssue({
+      companyId,
+      identifier: "BIX-1",
+      title: "Blocked on vendor",
+      status: "blocked",
+      description: [
+        "Public context stays visible.",
+        `external owner: ${owner}`,
+        `external action: ${action}`,
+        "Continue after the vendor confirms receipt.",
+      ].join("\n"),
+    });
+
+    const rows = await svc.list(companyId, { attention: "blocked" });
+    const issue = rows.find((row) => row.id === issueId);
+
+    expect(issue?.description).toContain("Public context stays visible.");
+    expect(issue?.description).toContain("Continue after the vendor confirms receipt.");
+    expect(issue?.description).not.toContain(owner);
+    expect(issue?.description).not.toContain(action);
+    expect(issue?.blockedInboxAttention).toMatchObject({
+      state: "external_wait",
+      reason: "external_owner_action",
+      owner: { type: "external", label: null },
+      action: { label: "External owner action", detail: null },
+      redaction: { externalDetailsRedacted: true, secretFieldsOmitted: true },
+    });
+    expect(JSON.stringify(issue?.blockedInboxAttention)).not.toContain(owner);
+    expect(JSON.stringify(issue?.blockedInboxAttention)).not.toContain(action);
+
+    await expect(svc.list(companyId, { attention: "blocked", q: owner })).resolves.toEqual([]);
+    await expect(svc.count(companyId, { attention: "blocked", q: action })).resolves.toBe(0);
+    await expect(svc.count(companyId, { attention: "blocked", q: "Public context" })).resolves.toBe(1);
+  });
+
+  it("excludes healthy active blockers from blocked inbox attention", async () => {
+    const { companyId, agentId } = await createCompany("BIB");
+    const parentId = await insertIssue({ companyId, identifier: "BIB-1", title: "Blocked source", status: "blocked" });
+    const blockerId = await insertIssue({
+      companyId,
+      identifier: "BIB-2",
+      title: "Running leaf",
+      status: "todo",
+      assigneeAgentId: agentId,
+    });
+    await block({ companyId, blockerIssueId: blockerId, blockedIssueId: parentId });
+    await activeRun({ companyId, agentId, issueId: blockerId });
+
+    expect(await svc.list(companyId, { attention: "blocked" })).toEqual([]);
+  });
+
+  it("classifies assigned backlog and invalid review leaves for blocked inbox attention", async () => {
+    const { companyId, agentId, pausedAgentId } = await createCompany("BIC");
+    const backlogParentId = await insertIssue({ companyId, identifier: "BIC-1", title: "Blocked by parked work", status: "blocked" });
+    const backlogLeafId = await insertIssue({
+      companyId,
+      identifier: "BIC-2",
+      title: "Parked blocker",
+      status: "backlog",
+      assigneeAgentId: agentId,
+    });
+    await block({ companyId, blockerIssueId: backlogLeafId, blockedIssueId: backlogParentId });
+
+    const reviewId = await insertIssue({
+      companyId,
+      identifier: "BIC-3",
+      title: "Invalid review",
+      status: "in_review",
+      assigneeAgentId: agentId,
+      executionState: {
+        status: "pending",
+        currentStageId: null,
+        currentStageIndex: null,
+        currentStageType: "review",
+        currentParticipant: { type: "agent", agentId: pausedAgentId },
+        returnAssignee: null,
+        reviewRequest: null,
+        completedStageIds: [],
+        lastDecisionId: null,
+        lastDecisionOutcome: null,
+      },
+    });
+
+    const rows = await svc.list(companyId, { attention: "blocked" });
+    const byId = new Map(rows.map((row) => [row.id, row]));
+
+    expect(byId.get(backlogParentId)?.blockedInboxAttention).toMatchObject({
+      reason: "blocked_by_assigned_backlog_issue",
+      severity: "high",
+      owner: { type: "agent", agentId },
+      leafIssue: { id: backlogLeafId },
+    });
+    expect(byId.get(reviewId)?.blockedInboxAttention).toMatchObject({
+      reason: "invalid_review_participant",
+      severity: "critical",
+      action: { label: "Repair review participant" },
+    });
+  });
+
+  it("classifies recovery issues and missing successful-run dispositions", async () => {
+    const { companyId, agentId } = await createCompany("BID");
+    const sourceId = await insertIssue({ companyId, identifier: "BID-1", title: "Stopped source", status: "blocked" });
+    const leafId = await insertIssue({ companyId, identifier: "BID-2", title: "Stopped leaf", status: "todo" });
+    const recoveryId = await insertIssue({
+      companyId,
+      identifier: "BID-3",
+      title: "Recovery issue",
+      status: "todo",
+      assigneeAgentId: agentId,
+      originKind: "harness_liveness_escalation",
+      originId: buildIssueGraphLivenessIncidentKey({
+        companyId,
+        issueId: sourceId,
+        state: "blocked_by_unassigned_issue",
+        blockerIssueId: leafId,
+      }),
+    });
+    const handoffId = await insertIssue({
+      companyId,
+      identifier: "BID-4",
+      title: "Needs disposition",
+      status: "in_progress",
+      assigneeAgentId: agentId,
+    });
+    await db.insert(activityLog).values({
+      companyId,
+      actorType: "system",
+      actorId: "system",
+      action: "issue.successful_run_handoff_required",
+      entityType: "issue",
+      entityId: handoffId,
+      agentId,
+      details: { sourceRunId: randomUUID(), detectedProgressSummary: "Progress was made" },
+    });
+
+    const rows = await svc.list(companyId, { attention: "blocked" });
+    const byId = new Map(rows.map((row) => [row.id, row]));
+
+    expect(byId.get(recoveryId)?.blockedInboxAttention).toMatchObject({
+      state: "recovery_open",
+      reason: "open_recovery_issue",
+      sourceIssue: { id: sourceId },
+      leafIssue: { id: leafId },
+      recoveryIssue: { id: recoveryId },
+    });
+    expect(byId.get(handoffId)?.blockedInboxAttention).toMatchObject({
+      state: "missing_disposition",
+      reason: "missing_successful_run_disposition",
+      owner: { type: "agent", agentId },
+      action: { label: "Choose disposition" },
+    });
+  });
 });
diff --git a/server/src/__tests__/issue-closed-workspace-routes.test.ts b/server/src/__tests__/issue-closed-workspace-routes.test.ts
index 8b4f7f6e..12181719 100644
--- a/server/src/__tests__/issue-closed-workspace-routes.test.ts
+++ b/server/src/__tests__/issue-closed-workspace-routes.test.ts
@@ -116,6 +116,10 @@ function registerServiceMocks() {
       syncDocument: async () => undefined,
       syncIssue: async () => undefined,
     }),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueService: () => mockIssueService,
     logActivity: mockLogActivity,
     projectService: () => mockProjectService,
diff --git a/server/src/__tests__/issue-comment-cancel-routes.test.ts b/server/src/__tests__/issue-comment-cancel-routes.test.ts
index e978ae14..be1315e3 100644
--- a/server/src/__tests__/issue-comment-cancel-routes.test.ts
+++ b/server/src/__tests__/issue-comment-cancel-routes.test.ts
@@ -86,6 +86,10 @@ function registerModuleMocks() {
     heartbeatService: () => mockHeartbeatService,
     instanceSettingsService: () => mockInstanceSettingsService,
     issueApprovalService: () => ({}),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueReferenceService: () => ({
       deleteDocumentSource: async () => undefined,
       diffIssueReferenceSummary: () => ({
diff --git a/server/src/__tests__/issue-comment-reopen-routes.test.ts b/server/src/__tests__/issue-comment-reopen-routes.test.ts
index 5eed5cc4..8a55d9db 100644
--- a/server/src/__tests__/issue-comment-reopen-routes.test.ts
+++ b/server/src/__tests__/issue-comment-reopen-routes.test.ts
@@ -67,6 +67,9 @@ const mockIssueThreadInteractionService = vi.hoisted(() => ({
   expireRequestConfirmationsSupersededByComment: vi.fn(async () => []),
   expireStaleRequestConfirmationsForIssueDocument: vi.fn(async () => []),
 }));
+const mockIssueRecoveryActionService = vi.hoisted(() => ({
+  getActiveForIssue: vi.fn(async () => null),
+}));
 const mockIssueTreeControlService = vi.hoisted(() => ({
   getActivePauseHoldGate: vi.fn(async () => null),
 }));
@@ -125,6 +128,7 @@ vi.mock("../services/index.js", () => ({
   heartbeatService: () => mockHeartbeatService,
   instanceSettingsService: () => mockInstanceSettingsService,
   issueApprovalService: () => ({}),
+  issueRecoveryActionService: () => mockIssueRecoveryActionService,
   issueReferenceService: () => ({
     deleteDocumentSource: async () => undefined,
     diffIssueReferenceSummary: () => ({
@@ -238,6 +242,7 @@ describe.sequential("issue comment reopen routes", () => {
     mockInstanceSettingsService.get.mockReset();
     mockInstanceSettingsService.listCompanyIds.mockReset();
     mockRoutineService.syncRunStatusForIssue.mockReset();
+    mockIssueRecoveryActionService.getActiveForIssue.mockReset();
     mockIssueTreeControlService.getActivePauseHoldGate.mockReset();
     mockTxInsertValues.mockReset();
     mockTxInsert.mockReset();
@@ -274,6 +279,7 @@ describe.sequential("issue comment reopen routes", () => {
     });
     mockInstanceSettingsService.listCompanyIds.mockResolvedValue(["company-1"]);
     mockRoutineService.syncRunStatusForIssue.mockResolvedValue(undefined);
+    mockIssueRecoveryActionService.getActiveForIssue.mockResolvedValue(null);
     mockIssueTreeControlService.getActivePauseHoldGate.mockResolvedValue(null);
     mockIssueService.addComment.mockResolvedValue({
       id: "comment-1",
diff --git a/server/src/__tests__/issue-dependency-wakeups-routes.test.ts b/server/src/__tests__/issue-dependency-wakeups-routes.test.ts
index 5991ae01..4abb18ee 100644
--- a/server/src/__tests__/issue-dependency-wakeups-routes.test.ts
+++ b/server/src/__tests__/issue-dependency-wakeups-routes.test.ts
@@ -61,6 +61,10 @@ vi.mock("../services/index.js", () => ({
     syncDocument: async () => undefined,
     syncIssue: async () => undefined,
   }),
+  issueRecoveryActionService: () => ({
+    getActiveForIssue: vi.fn(async () => null),
+    listActiveForIssues: vi.fn(async () => new Map()),
+  }),
   issueService: () => mockIssueService,
   logActivity: vi.fn(async () => undefined),
   projectService: () => ({
diff --git a/server/src/__tests__/issue-document-restore-routes.test.ts b/server/src/__tests__/issue-document-restore-routes.test.ts
index efe8916b..3938e06a 100644
--- a/server/src/__tests__/issue-document-restore-routes.test.ts
+++ b/server/src/__tests__/issue-document-restore-routes.test.ts
@@ -133,6 +133,10 @@ function registerModuleMocks() {
       syncDocument: async () => undefined,
       syncIssue: async () => undefined,
     }),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueService: () => mockIssueService,
     issueThreadInteractionService: () => mockIssueThreadInteractionService,
     logActivity: mockLogActivity,
diff --git a/server/src/__tests__/issue-execution-policy-routes.test.ts b/server/src/__tests__/issue-execution-policy-routes.test.ts
index ac809eed..1b0db770 100644
--- a/server/src/__tests__/issue-execution-policy-routes.test.ts
+++ b/server/src/__tests__/issue-execution-policy-routes.test.ts
@@ -82,6 +82,10 @@ function registerModuleMocks() {
       syncDocument: async () => undefined,
       syncIssue: async () => undefined,
     }),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueService: () => mockIssueService,
     issueThreadInteractionService: () => mockIssueThreadInteractionService,
     logActivity: mockLogActivity,
diff --git a/server/src/__tests__/issue-feedback-routes.test.ts b/server/src/__tests__/issue-feedback-routes.test.ts
index 4c7807b6..e52e5a84 100644
--- a/server/src/__tests__/issue-feedback-routes.test.ts
+++ b/server/src/__tests__/issue-feedback-routes.test.ts
@@ -93,6 +93,10 @@ function registerModuleMocks() {
     heartbeatService: () => mockHeartbeatService,
     issueApprovalService: () => ({}),
     issueReferenceService: () => mockIssueReferenceService,
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueService: () => mockIssueService,
     issueThreadInteractionService: () => mockIssueThreadInteractionService,
     logActivity: mockLogActivity,
diff --git a/server/src/__tests__/issue-recovery-actions.test.ts b/server/src/__tests__/issue-recovery-actions.test.ts
new file mode 100644
index 00000000..cc533998
--- /dev/null
+++ b/server/src/__tests__/issue-recovery-actions.test.ts
@@ -0,0 +1,767 @@
+import { randomUUID } from "node:crypto";
+import express from "express";
+import request from "supertest";
+import { and, eq } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  agents,
+  activityLog,
+  companies,
+  createDb,
+  issueComments,
+  issueRecoveryActions,
+  issueRelations,
+  issues,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { errorHandler } from "../middleware/index.js";
+import { issueRoutes } from "../routes/issues.js";
+import { issueRecoveryActionService } from "../services/issue-recovery-actions.js";
+import { recoveryService } from "../services/recovery/service.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+function makeRecoveryActionRow(overrides: Record<string, unknown> = {}) {
+  const now = new Date("2026-05-09T19:30:00.000Z");
+  return {
+    id: randomUUID(),
+    companyId: "company-1",
+    sourceIssueId: "source-1",
+    recoveryIssueId: null,
+    kind: "missing_disposition",
+    status: "active",
+    ownerType: "agent",
+    ownerAgentId: "agent-1",
+    ownerUserId: null,
+    previousOwnerAgentId: null,
+    returnOwnerAgentId: null,
+    cause: "successful_run_missing_issue_disposition",
+    fingerprint: "missing-disposition:fingerprint",
+    evidence: {},
+    nextAction: "Choose a valid issue disposition.",
+    wakePolicy: null,
+    monitorPolicy: null,
+    attemptCount: 1,
+    maxAttempts: null,
+    timeoutAt: null,
+    lastAttemptAt: now,
+    outcome: null,
+    resolutionNote: null,
+    resolvedAt: null,
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+describe("issueRecoveryActionService", () => {
+  it("does not reactivate an action resolved between the active read and update", async () => {
+    const existingRow = makeRecoveryActionRow({ id: "existing-action", attemptCount: 1 });
+    const createdRow = makeRecoveryActionRow({ id: "new-action", attemptCount: 1 });
+    const selectResults = [[existingRow], []];
+
+    const makeSelectQuery = (rows: unknown[]) => ({
+      from() {
+        return this;
+      },
+      where() {
+        return this;
+      },
+      orderBy() {
+        return this;
+      },
+      limit() {
+        return Promise.resolve(rows);
+      },
+    });
+
+    const fakeDb = {
+      select: vi.fn(() => makeSelectQuery(selectResults.shift() ?? [])),
+      update: vi.fn(() => ({
+        set: vi.fn(() => ({
+          where: vi.fn(() => ({
+            returning: vi.fn(async () => []),
+          })),
+        })),
+      })),
+      insert: vi.fn(() => ({
+        values: vi.fn(() => ({
+          returning: vi.fn(async () => [createdRow]),
+        })),
+      })),
+    };
+
+    const result = await issueRecoveryActionService(fakeDb as never).upsertSourceScoped({
+      companyId: "company-1",
+      sourceIssueId: "source-1",
+      kind: "missing_disposition",
+      ownerType: "agent",
+      ownerAgentId: "agent-1",
+      cause: "successful_run_missing_issue_disposition",
+      fingerprint: "missing-disposition:fingerprint",
+      nextAction: "Choose a valid issue disposition.",
+    });
+
+    expect(result).toMatchObject({ id: "new-action", status: "active" });
+    expect(fakeDb.update).toHaveBeenCalledTimes(1);
+    expect(fakeDb.insert).toHaveBeenCalledTimes(1);
+  });
+});
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres issue recovery action tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describeEmbeddedPostgres("issue recovery actions", () => {
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+  let db: ReturnType<typeof createDb>;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-issue-recovery-actions-");
+    db = createDb(tempDb.connectionString);
+  }, 30_000);
+
+  afterEach(async () => {
+    await db.delete(issueRecoveryActions);
+    await db.delete(issueComments);
+    await db.delete(activityLog);
+    await db.delete(issues);
+    await db.delete(agents);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  async function seedCompany() {
+    const companyId = randomUUID();
+    const managerId = randomUUID();
+    const coderId = randomUUID();
+    const sourceIssueId = randomUUID();
+    const prefix = `RA${companyId.replaceAll("-", "").slice(0, 6).toUpperCase()}`;
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Recovery Co",
+      issuePrefix: prefix,
+      requireBoardApprovalForNewAgents: false,
+    });
+    await db.insert(agents).values([
+      {
+        id: managerId,
+        companyId,
+        name: "CTO",
+        role: "cto",
+        status: "idle",
+        adapterType: "codex_local",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      },
+      {
+        id: coderId,
+        companyId,
+        name: "Coder",
+        role: "engineer",
+        status: "idle",
+        reportsTo: managerId,
+        adapterType: "codex_local",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      },
+    ]);
+    await db.insert(issues).values({
+      id: sourceIssueId,
+      companyId,
+      title: "Implement backend recovery",
+      status: "in_progress",
+      priority: "medium",
+      assigneeAgentId: coderId,
+      issueNumber: 1,
+      identifier: `${prefix}-1`,
+    });
+    const [sourceIssue] = await db.select().from(issues).where(eq(issues.id, sourceIssueId));
+    return { companyId, managerId, coderId, sourceIssueId, prefix, sourceIssue: sourceIssue! };
+  }
+
+  function createApp(actor: any = { type: "board", source: "local_implicit" }) {
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+      (req as any).actor = actor;
+      next();
+    });
+    app.use("/api", issueRoutes(db, {} as any));
+    app.use(errorHandler);
+    return app;
+  }
+
+  it("upserts one active source-scoped action per issue and keeps company scoping explicit", async () => {
+    const { companyId, managerId, sourceIssueId } = await seedCompany();
+    const svc = issueRecoveryActionService(db);
+
+    const first = await svc.upsertSourceScoped({
+      companyId,
+      sourceIssueId,
+      kind: "stranded_assigned_issue",
+      ownerType: "agent",
+      ownerAgentId: managerId,
+      cause: "stranded_assigned_issue",
+      fingerprint: "recovery:fingerprint",
+      evidence: { latestRunId: "run-1" },
+      nextAction: "Restore a live execution path.",
+      wakePolicy: { type: "wake_owner" },
+    });
+    const second = await svc.upsertSourceScoped({
+      companyId,
+      sourceIssueId,
+      kind: "stranded_assigned_issue",
+      ownerType: "agent",
+      ownerAgentId: managerId,
+      cause: "stranded_assigned_issue",
+      fingerprint: "recovery:fingerprint",
+      evidence: { latestRunId: "run-2" },
+      nextAction: "Restore a live execution path.",
+      wakePolicy: { type: "wake_owner" },
+    });
+
+    expect(second.id).toBe(first.id);
+    expect(second.attemptCount).toBe(2);
+    expect(second.evidence).toMatchObject({ latestRunId: "run-2" });
+    expect(await svc.getActiveForIssue(companyId, sourceIssueId)).toMatchObject({ id: first.id });
+    expect(await svc.getActiveForIssue(randomUUID(), sourceIssueId)).toBeNull();
+  });
+
+  it("escalates stranded assigned work into a source action instead of a recovery issue", async () => {
+    const { companyId, managerId, coderId, sourceIssue } = await seedCompany();
+    const enqueueWakeup = vi.fn(async () => null);
+    const recovery = recoveryService(db, { enqueueWakeup });
+    const latestRun = {
+      id: randomUUID(),
+      agentId: coderId,
+      status: "failed",
+      error: "adapter failed",
+      errorCode: "adapter_failed",
+      contextSnapshot: { retryReason: "issue_continuation_needed" },
+      livenessState: "needs_followup",
+    } as const;
+
+    await recovery.escalateStrandedAssignedIssue({
+      issue: sourceIssue,
+      previousStatus: "in_progress",
+      latestRun,
+      comment: "Automatic continuation recovery failed.",
+    });
+    await recovery.escalateStrandedAssignedIssue({
+      issue: sourceIssue,
+      previousStatus: "in_progress",
+      latestRun,
+      comment: "Automatic continuation recovery failed.",
+    });
+
+    const actionRows = await db
+      .select()
+      .from(issueRecoveryActions)
+      .where(eq(issueRecoveryActions.sourceIssueId, sourceIssue.id));
+    expect(actionRows).toHaveLength(1);
+    expect(actionRows[0]).toMatchObject({
+      companyId,
+      kind: "stranded_assigned_issue",
+      status: "active",
+      previousOwnerAgentId: coderId,
+      returnOwnerAgentId: coderId,
+      cause: "stranded_assigned_issue",
+      attemptCount: 2,
+    });
+
+    const [updatedIssue] = await db.select().from(issues).where(eq(issues.id, sourceIssue.id));
+    expect(updatedIssue).toMatchObject({
+      status: "blocked",
+    });
+    const recoveryIssues = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "stranded_issue_recovery")));
+    expect(recoveryIssues).toHaveLength(0);
+    expect(enqueueWakeup).toHaveBeenCalledTimes(2);
+    expect(enqueueWakeup.mock.calls[0]?.[1]?.payload).toMatchObject({
+      issueId: sourceIssue.id,
+      sourceIssueId: sourceIssue.id,
+      recoveryCause: "stranded_assigned_issue",
+    });
+  });
+
+  it("reuses the same source-scoped action when latest run IDs change while the cause stays the same", async () => {
+    const { companyId, managerId, coderId, sourceIssue } = await seedCompany();
+    const enqueueWakeup = vi.fn(async () => null);
+    const recovery = recoveryService(db, { enqueueWakeup });
+    const firstLatestRun = {
+      id: randomUUID(),
+      agentId: coderId,
+      status: "failed",
+      error: "adapter failed",
+      errorCode: "adapter_failed",
+      contextSnapshot: { retryReason: "issue_continuation_needed" },
+      livenessState: "needs_followup",
+    } as const;
+    const secondLatestRun = {
+      ...firstLatestRun,
+      id: randomUUID(),
+    };
+
+    await recovery.escalateStrandedAssignedIssue({
+      issue: sourceIssue,
+      previousStatus: "in_progress",
+      latestRun: firstLatestRun,
+      comment: "Automatic continuation recovery failed.",
+    });
+    await recovery.escalateStrandedAssignedIssue({
+      issue: sourceIssue,
+      previousStatus: "in_progress",
+      latestRun: secondLatestRun,
+      comment: "Automatic continuation recovery failed.",
+    });
+
+    const actionRows = await db
+      .select()
+      .from(issueRecoveryActions)
+      .where(eq(issueRecoveryActions.sourceIssueId, sourceIssue.id));
+    expect(actionRows).toHaveLength(1);
+    expect(actionRows[0]).toMatchObject({
+      companyId,
+      kind: "stranded_assigned_issue",
+      status: "active",
+      previousOwnerAgentId: coderId,
+      returnOwnerAgentId: coderId,
+      cause: "stranded_assigned_issue",
+      attemptCount: 2,
+    });
+    expect(actionRows[0]?.evidence).toMatchObject({ latestRunId: secondLatestRun.id });
+    expect(enqueueWakeup).toHaveBeenCalledTimes(2);
+    expect(enqueueWakeup.mock.calls[1]?.[1]?.payload).toMatchObject({
+      issueId: sourceIssue.id,
+      sourceIssueId: sourceIssue.id,
+      strandedRunId: secondLatestRun.id,
+      recoveryCause: "stranded_assigned_issue",
+    });
+  });
+
+  it("keeps the source issue blocked when source-scoped wakeup is claimed synchronously", async () => {
+    const { companyId, managerId, coderId, sourceIssue } = await seedCompany();
+    await db.update(agents).set({ status: "paused" }).where(eq(agents.id, managerId));
+    const enqueueWakeup = vi.fn(async () => {
+      await db
+        .update(issues)
+        .set({ status: "in_progress" })
+        .where(eq(issues.id, sourceIssue.id));
+      return null;
+    });
+    const recovery = recoveryService(db, { enqueueWakeup });
+    const firstLatestRun = {
+      id: randomUUID(),
+      agentId: coderId,
+      status: "failed",
+      error: "adapter failed",
+      errorCode: "adapter_failed",
+      contextSnapshot: { retryReason: "issue_continuation_needed" },
+      livenessState: "needs_followup",
+    } as const;
+
+    await recovery.escalateStrandedAssignedIssue({
+      issue: sourceIssue,
+      previousStatus: "in_progress",
+      latestRun: firstLatestRun,
+      comment: "Automatic continuation recovery failed.",
+    });
+
+    const [afterFirst] = await db.select().from(issues).where(eq(issues.id, sourceIssue.id));
+    expect(afterFirst?.status).toBe("blocked");
+    expect(afterFirst?.assigneeAgentId).toBe(coderId);
+
+    const secondLatestRun = {
+      ...firstLatestRun,
+      id: randomUUID(),
+    };
+    await recovery.escalateStrandedAssignedIssue({
+      issue: sourceIssue,
+      previousStatus: "in_progress",
+      latestRun: secondLatestRun,
+      comment: "Automatic continuation recovery failed.",
+    });
+
+    const actionRows = await db
+      .select()
+      .from(issueRecoveryActions)
+      .where(eq(issueRecoveryActions.sourceIssueId, sourceIssue.id));
+    expect(actionRows).toHaveLength(1);
+    expect(actionRows[0]).toMatchObject({
+      companyId,
+      kind: "stranded_assigned_issue",
+      status: "active",
+      previousOwnerAgentId: coderId,
+      returnOwnerAgentId: coderId,
+      cause: "stranded_assigned_issue",
+      attemptCount: 2,
+    });
+    const [afterSecond] = await db.select().from(issues).where(eq(issues.id, sourceIssue.id));
+    expect(afterSecond?.status).toBe("blocked");
+
+    const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, sourceIssue.id));
+    expect(comments).toHaveLength(1);
+    expect(comments[0]?.body).toContain("Recovery action:");
+  });
+
+  it("does not create nested recovery artifacts when issue-backed fallback work itself fails", async () => {
+    const { companyId, managerId, sourceIssueId, prefix } = await seedCompany();
+    const recoveryIssueId = randomUUID();
+    await db.insert(issues).values({
+      id: recoveryIssueId,
+      companyId,
+      title: "Recover stalled issue",
+      status: "in_progress",
+      priority: "medium",
+      assigneeAgentId: managerId,
+      parentId: sourceIssueId,
+      issueNumber: 2,
+      identifier: `${prefix}-2`,
+      originKind: "stranded_issue_recovery",
+      originId: sourceIssueId,
+      originFingerprint: `stranded_issue_recovery:${sourceIssueId}`,
+    });
+    const [recoveryIssue] = await db.select().from(issues).where(eq(issues.id, recoveryIssueId));
+    const recovery = recoveryService(db, { enqueueWakeup: vi.fn(async () => null) });
+
+    await recovery.escalateStrandedAssignedIssue({
+      issue: recoveryIssue!,
+      previousStatus: "in_progress",
+      latestRun: {
+        id: randomUUID(),
+        agentId: managerId,
+        status: "failed",
+        error: "adapter failed",
+        errorCode: "adapter_failed",
+        contextSnapshot: { retryReason: "issue_continuation_needed" },
+        livenessState: "needs_followup",
+      },
+    });
+
+    const actionRows = await db.select().from(issueRecoveryActions);
+    expect(actionRows).toHaveLength(0);
+    const recoveryIssues = await db
+      .select()
+      .from(issues)
+      .where(and(eq(issues.companyId, companyId), eq(issues.originKind, "stranded_issue_recovery")));
+    expect(recoveryIssues).toHaveLength(1);
+    expect(recoveryIssues[0]?.status).toBe("blocked");
+  });
+
+  it("exposes active recovery actions on the issue read API", async () => {
+    const { companyId, managerId, sourceIssueId } = await seedCompany();
+    const recoveryActionSvc = issueRecoveryActionService(db);
+    const action = await recoveryActionSvc.upsertSourceScoped({
+      companyId,
+      sourceIssueId,
+      kind: "missing_disposition",
+      ownerType: "agent",
+      ownerAgentId: managerId,
+      cause: "successful_run_missing_issue_disposition",
+      fingerprint: "missing-disposition:fingerprint",
+      evidence: { sourceRunId: "run-1" },
+      nextAction: "Choose a valid issue disposition.",
+      wakePolicy: { type: "wake_owner" },
+    });
+    const app = createApp();
+
+    const detail = await request(app).get(`/api/issues/${sourceIssueId}`).expect(200);
+    expect(detail.body.activeRecoveryAction).toMatchObject({
+      id: action.id,
+      sourceIssueId,
+      kind: "missing_disposition",
+      ownerAgentId: managerId,
+    });
+
+    const list = await request(app).get(`/api/issues/${sourceIssueId}/recovery-actions`).expect(200);
+    expect(list.body.active).toMatchObject({ id: action.id });
+    expect(list.body.actions).toHaveLength(1);
+  });
+
+  it("resolves an active recovery action and removes it from active projections", async () => {
+    const { companyId, managerId, sourceIssueId } = await seedCompany();
+    const recoveryActionSvc = issueRecoveryActionService(db);
+    const action = await recoveryActionSvc.upsertSourceScoped({
+      companyId,
+      sourceIssueId,
+      kind: "missing_disposition",
+      ownerType: "agent",
+      ownerAgentId: managerId,
+      cause: "successful_run_missing_issue_disposition",
+      fingerprint: "missing-disposition:fingerprint",
+      evidence: { sourceRunId: "run-1" },
+      nextAction: "Choose a valid issue disposition.",
+      wakePolicy: { type: "wake_owner" },
+    });
+    const app = createApp();
+
+    const resolved = await request(app)
+      .post(`/api/issues/${sourceIssueId}/recovery-actions/resolve`)
+      .send({
+        actionId: action.id,
+        outcome: "restored",
+        sourceIssueStatus: "done",
+        resolutionNote: "Operator confirmed the source issue is complete.",
+      })
+      .expect(200);
+
+    expect(resolved.body.issue).toMatchObject({
+      id: sourceIssueId,
+      status: "done",
+      activeRecoveryAction: null,
+    });
+    expect(resolved.body.recoveryAction).toMatchObject({
+      id: action.id,
+      status: "resolved",
+      outcome: "restored",
+      resolutionNote: "Operator confirmed the source issue is complete.",
+    });
+    expect(resolved.body.recoveryAction.resolvedAt).toBeTruthy();
+    expect(await recoveryActionSvc.getActiveForIssue(companyId, sourceIssueId)).toBeNull();
+
+    const detail = await request(app).get(`/api/issues/${sourceIssueId}`).expect(200);
+    expect(detail.body.activeRecoveryAction).toBeNull();
+
+    const activityRows = await db
+      .select()
+      .from(activityLog)
+      .where(eq(activityLog.entityId, sourceIssueId));
+    expect(activityRows.map((row) => row.action)).toEqual(
+      expect.arrayContaining(["issue.updated", "issue.recovery_action_resolved"]),
+    );
+  });
+
+  it("rejects blocked recovery resolution when the source issue has no first-class blockers", async () => {
+    const { companyId, managerId, sourceIssueId } = await seedCompany();
+    const recoveryActionSvc = issueRecoveryActionService(db);
+    const action = await recoveryActionSvc.upsertSourceScoped({
+      companyId,
+      sourceIssueId,
+      kind: "issue_graph_liveness",
+      ownerType: "agent",
+      ownerAgentId: managerId,
+      cause: "issue_graph_liveness",
+      fingerprint: "graph-liveness:blocked-without-blocker",
+      evidence: { latestIssueStatus: "in_progress" },
+      nextAction: "Choose a disposition with a live continuation path.",
+      wakePolicy: { type: "manual" },
+    });
+    const app = createApp();
+
+    const rejected = await request(app)
+      .post(`/api/issues/${sourceIssueId}/recovery-actions/resolve`)
+      .send({
+        actionId: action.id,
+        outcome: "blocked",
+        sourceIssueStatus: "blocked",
+      })
+      .expect(422);
+
+    expect(rejected.body.error).toContain("requires an unresolved first-class blocker");
+
+    const [sourceIssue] = await db.select().from(issues).where(eq(issues.id, sourceIssueId));
+    expect(sourceIssue?.status).toBe("in_progress");
+
+    const [actionRow] = await db
+      .select()
+      .from(issueRecoveryActions)
+      .where(eq(issueRecoveryActions.id, action.id));
+    expect(actionRow).toMatchObject({
+      status: "active",
+      outcome: null,
+      resolvedAt: null,
+    });
+  });
+
+  it("allows blocked recovery resolution when the source issue has an unresolved first-class blocker", async () => {
+    const { companyId, managerId, sourceIssueId, prefix } = await seedCompany();
+    const blockerIssueId = randomUUID();
+    await db.insert(issues).values({
+      id: blockerIssueId,
+      companyId,
+      title: "Unblock recovery disposition",
+      status: "todo",
+      priority: "medium",
+      assigneeAgentId: managerId,
+      issueNumber: 2,
+      identifier: `${prefix}-2`,
+    });
+    await db.insert(issueRelations).values({
+      companyId,
+      issueId: blockerIssueId,
+      relatedIssueId: sourceIssueId,
+      type: "blocks",
+    });
+    const recoveryActionSvc = issueRecoveryActionService(db);
+    const action = await recoveryActionSvc.upsertSourceScoped({
+      companyId,
+      sourceIssueId,
+      kind: "issue_graph_liveness",
+      ownerType: "agent",
+      ownerAgentId: managerId,
+      cause: "issue_graph_liveness",
+      fingerprint: "graph-liveness:blocked-with-blocker",
+      evidence: { latestIssueStatus: "in_progress" },
+      nextAction: "Wait for the blocker before continuing.",
+      wakePolicy: { type: "manual" },
+    });
+    const app = createApp();
+
+    const resolved = await request(app)
+      .post(`/api/issues/${sourceIssueId}/recovery-actions/resolve`)
+      .send({
+        actionId: action.id,
+        outcome: "blocked",
+        sourceIssueStatus: "blocked",
+        resolutionNote: "The source issue is explicitly blocked by a follow-up.",
+      })
+      .expect(200);
+
+    expect(resolved.body.issue).toMatchObject({
+      id: sourceIssueId,
+      status: "blocked",
+      activeRecoveryAction: null,
+    });
+    expect(resolved.body.recoveryAction).toMatchObject({
+      id: action.id,
+      status: "resolved",
+      outcome: "blocked",
+      resolutionNote: "The source issue is explicitly blocked by a follow-up.",
+    });
+    expect(await recoveryActionSvc.getActiveForIssue(companyId, sourceIssueId)).toBeNull();
+  });
+
+  it("rejects false-positive recovery resolution without an explicit source issue status", async () => {
+    const { companyId, managerId, sourceIssueId } = await seedCompany();
+    const recoveryActionSvc = issueRecoveryActionService(db);
+    const action = await recoveryActionSvc.upsertSourceScoped({
+      companyId,
+      sourceIssueId,
+      kind: "issue_graph_liveness",
+      ownerType: "agent",
+      ownerAgentId: managerId,
+      cause: "issue_graph_liveness",
+      fingerprint: "graph-liveness:fingerprint",
+      evidence: { latestIssueStatus: "in_progress" },
+      nextAction: "Confirm whether the issue is actually stranded.",
+      wakePolicy: { type: "manual" },
+    });
+    const app = createApp();
+
+    await request(app)
+      .post(`/api/issues/${sourceIssueId}/recovery-actions/resolve`)
+      .send({
+        actionId: action.id,
+        outcome: "false_positive",
+        resolutionNote: "The source issue still has a live execution path.",
+      })
+      .expect(400);
+
+    const [sourceIssue] = await db.select().from(issues).where(eq(issues.id, sourceIssueId));
+    expect(sourceIssue?.status).toBe("in_progress");
+
+    const [actionRow] = await db
+      .select()
+      .from(issueRecoveryActions)
+      .where(eq(issueRecoveryActions.id, action.id));
+    expect(actionRow).toMatchObject({
+      status: "active",
+      outcome: null,
+      resolutionNote: null,
+    });
+  });
+
+  it("allows false-positive recovery resolution to restore a blocked source issue in the same request", async () => {
+    const { companyId, managerId, sourceIssueId } = await seedCompany();
+    await db.update(issues).set({ status: "blocked" }).where(eq(issues.id, sourceIssueId));
+    const recoveryActionSvc = issueRecoveryActionService(db);
+    const action = await recoveryActionSvc.upsertSourceScoped({
+      companyId,
+      sourceIssueId,
+      kind: "issue_graph_liveness",
+      ownerType: "agent",
+      ownerAgentId: managerId,
+      cause: "issue_graph_liveness",
+      fingerprint: "graph-liveness:false-positive-unblock",
+      evidence: { latestIssueStatus: "blocked" },
+      nextAction: "Confirm whether the issue is actually stranded.",
+      wakePolicy: { type: "manual" },
+    });
+    const app = createApp();
+
+    const resolved = await request(app)
+      .post(`/api/issues/${sourceIssueId}/recovery-actions/resolve`)
+      .send({
+        actionId: action.id,
+        outcome: "false_positive",
+        sourceIssueStatus: "in_review",
+        resolutionNote: "Recovery signal was stale; return to review.",
+      })
+      .expect(200);
+
+    expect(resolved.body.issue).toMatchObject({
+      id: sourceIssueId,
+      status: "in_review",
+      activeRecoveryAction: null,
+    });
+    expect(resolved.body.recoveryAction).toMatchObject({
+      id: action.id,
+      status: "resolved",
+      outcome: "false_positive",
+      resolutionNote: "Recovery signal was stale; return to review.",
+    });
+  });
+
+  it("enforces company scope when resolving recovery actions", async () => {
+    const { companyId, managerId, sourceIssueId } = await seedCompany();
+    const recoveryActionSvc = issueRecoveryActionService(db);
+    const action = await recoveryActionSvc.upsertSourceScoped({
+      companyId,
+      sourceIssueId,
+      kind: "missing_disposition",
+      ownerType: "agent",
+      ownerAgentId: managerId,
+      cause: "successful_run_missing_issue_disposition",
+      fingerprint: "missing-disposition:fingerprint",
+      evidence: { sourceRunId: "run-1" },
+      nextAction: "Choose a valid issue disposition.",
+      wakePolicy: { type: "wake_owner" },
+    });
+    const app = createApp({
+      type: "agent",
+      agentId: randomUUID(),
+      companyId: randomUUID(),
+      runId: randomUUID(),
+      source: "agent_jwt",
+    });
+
+    await request(app)
+      .post(`/api/issues/${sourceIssueId}/recovery-actions/resolve`)
+      .send({
+        actionId: action.id,
+        outcome: "restored",
+        sourceIssueStatus: "done",
+      })
+      .expect(403);
+
+    const [actionRow] = await db
+      .select()
+      .from(issueRecoveryActions)
+      .where(eq(issueRecoveryActions.id, action.id));
+    expect(actionRow?.status).toBe("active");
+  });
+});
diff --git a/server/src/__tests__/issue-telemetry-routes.test.ts b/server/src/__tests__/issue-telemetry-routes.test.ts
index 36bd8e84..0fbf303c 100644
--- a/server/src/__tests__/issue-telemetry-routes.test.ts
+++ b/server/src/__tests__/issue-telemetry-routes.test.ts
@@ -58,6 +58,10 @@ function registerModuleMocks() {
       syncDocument: async () => undefined,
       syncIssue: async () => undefined,
     }),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueService: () => mockIssueService,
     logActivity: vi.fn(async () => undefined),
     projectService: () => ({}),
diff --git a/server/src/__tests__/issue-thread-interaction-routes.test.ts b/server/src/__tests__/issue-thread-interaction-routes.test.ts
index 0c82acfb..a5d9acd8 100644
--- a/server/src/__tests__/issue-thread-interaction-routes.test.ts
+++ b/server/src/__tests__/issue-thread-interaction-routes.test.ts
@@ -86,6 +86,10 @@ function registerModuleMocks() {
       syncDocument: async () => undefined,
       syncIssue: async () => undefined,
     }),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueService: () => mockIssueService,
     issueThreadInteractionService: () => mockInteractionService,
     logActivity: mockLogActivity,
diff --git a/server/src/__tests__/issue-update-comment-wakeup-routes.test.ts b/server/src/__tests__/issue-update-comment-wakeup-routes.test.ts
index ee22ed42..b0f04f97 100644
--- a/server/src/__tests__/issue-update-comment-wakeup-routes.test.ts
+++ b/server/src/__tests__/issue-update-comment-wakeup-routes.test.ts
@@ -73,6 +73,10 @@ vi.mock("../services/index.js", () => ({
     syncDocument: async () => undefined,
     syncIssue: async () => undefined,
   }),
+  issueRecoveryActionService: () => ({
+    getActiveForIssue: vi.fn(async () => null),
+    listActiveForIssues: vi.fn(async () => new Map()),
+  }),
   issueService: () => mockIssueService,
   issueThreadInteractionService: () => mockIssueThreadInteractionService,
   logActivity: vi.fn(async () => undefined),
@@ -131,6 +135,10 @@ function registerModuleMocks() {
       syncDocument: async () => undefined,
       syncIssue: async () => undefined,
     }),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueService: () => mockIssueService,
     issueThreadInteractionService: () => mockIssueThreadInteractionService,
     logActivity: vi.fn(async () => undefined),
diff --git a/server/src/__tests__/issue-workspace-command-authz.test.ts b/server/src/__tests__/issue-workspace-command-authz.test.ts
index 813410e7..e23c440d 100644
--- a/server/src/__tests__/issue-workspace-command-authz.test.ts
+++ b/server/src/__tests__/issue-workspace-command-authz.test.ts
@@ -115,6 +115,10 @@ function registerRouteMocks() {
       syncDocument: async () => undefined,
       syncIssue: async () => undefined,
     }),
+    issueRecoveryActionService: () => ({
+      getActiveForIssue: vi.fn(async () => null),
+      listActiveForIssues: vi.fn(async () => new Map()),
+    }),
     issueService: () => mockIssueService,
     logActivity: mockLogActivity,
     projectService: () => ({}),
diff --git a/server/src/__tests__/issues-goal-context-routes.test.ts b/server/src/__tests__/issues-goal-context-routes.test.ts
index 504714ab..2bdd6b1a 100644
--- a/server/src/__tests__/issues-goal-context-routes.test.ts
+++ b/server/src/__tests__/issues-goal-context-routes.test.ts
@@ -111,6 +111,10 @@ vi.mock("../services/index.js", () => ({
   heartbeatService: () => mockHeartbeatService,
   instanceSettingsService: () => mockInstanceSettingsService,
   issueApprovalService: () => ({}),
+  issueRecoveryActionService: () => ({
+    getActiveForIssue: vi.fn(async () => null),
+    listActiveForIssues: vi.fn(async () => new Map()),
+  }),
   issueReferenceService: () => mockIssueReferenceService,
   issueService: () => mockIssueService,
   logActivity: mockLogActivity,
diff --git a/server/src/__tests__/issues-service.test.ts b/server/src/__tests__/issues-service.test.ts
index 2c705495..44ac15e6 100644
--- a/server/src/__tests__/issues-service.test.ts
+++ b/server/src/__tests__/issues-service.test.ts
@@ -24,7 +24,12 @@ import {
   startEmbeddedPostgresTestDatabase,
 } from "./helpers/embedded-postgres.js";
 import { instanceSettingsService } from "../services/instance-settings.ts";
-import { clampIssueListLimit, ISSUE_LIST_MAX_LIMIT, issueService } from "../services/issues.ts";
+import {
+  clampIssueListLimit,
+  deriveIssueCommentRunLogAttribution,
+  ISSUE_LIST_MAX_LIMIT,
+  issueService,
+} from "../services/issues.ts";
 import { buildProjectMentionHref, MAX_ISSUE_REQUEST_DEPTH } from "@paperclipai/shared";
 
 const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
@@ -38,6 +43,69 @@ describe("issue list limit helpers", () => {
   });
 });
 
+describe("deriveIssueCommentRunLogAttribution", () => {
+  it("recovers agent attribution from run logs that printed the posted comment id", () => {
+    const commentId = randomUUID();
+    const runId = randomUUID();
+    const agentId = randomUUID();
+
+    const derived = deriveIssueCommentRunLogAttribution(
+      [
+        {
+          id: commentId,
+          authorAgentId: null,
+          authorUserId: "user-1",
+          createdByRunId: null,
+          createdAt: new Date("2026-05-11T18:55:40.090Z"),
+        },
+      ],
+      [
+        {
+          runId,
+          agentId,
+          createdAt: new Date("2026-05-11T18:51:56.246Z"),
+          startedAt: new Date("2026-05-11T18:51:56.257Z"),
+          finishedAt: new Date("2026-05-11T18:55:45.600Z"),
+          logContent: `comment id: ${commentId}\n`,
+        },
+      ],
+    );
+
+    expect(derived.get(commentId)).toEqual({
+      derivedAuthorAgentId: agentId,
+      derivedCreatedByRunId: runId,
+      derivedAuthorSource: "run_log_comment_post",
+    });
+  });
+
+  it("does not rewrite comments without exact run-log proof", () => {
+    const commentId = randomUUID();
+    const derived = deriveIssueCommentRunLogAttribution(
+      [
+        {
+          id: commentId,
+          authorAgentId: null,
+          authorUserId: "user-1",
+          createdByRunId: null,
+          createdAt: new Date("2026-05-11T18:55:40.090Z"),
+        },
+      ],
+      [
+        {
+          runId: randomUUID(),
+          agentId: randomUUID(),
+          createdAt: new Date("2026-05-11T18:51:56.246Z"),
+          startedAt: new Date("2026-05-11T18:51:56.257Z"),
+          finishedAt: new Date("2026-05-11T18:55:45.600Z"),
+          logContent: "posted results without echoing the comment id",
+        },
+      ],
+    );
+
+    expect(derived.has(commentId)).toBe(false);
+  });
+});
+
 async function ensureIssueRelationsTable(db: ReturnType<typeof createDb>) {
   await db.execute(sql.raw(`
     CREATE TABLE IF NOT EXISTS "issue_relations" (
@@ -82,6 +150,7 @@ describeEmbeddedPostgres("issueService.list participantAgentId", () => {
     await db.delete(projectWorkspaces);
     await db.delete(projects);
     await db.delete(goals);
+    await db.delete(heartbeatRuns);
     await db.delete(agents);
     await db.delete(instanceSettings);
     await db.delete(companies);
@@ -1091,6 +1160,68 @@ describeEmbeddedPostgres("issueService.list participantAgentId", () => {
     expect(comments.map((comment) => comment.id)).toEqual([firstCommentId]);
   });
 
+  it("lists user comments when derived run attribution scans a timestamp window", async () => {
+    const companyId = randomUUID();
+    const agentId = randomUUID();
+    const issueId = randomUUID();
+    const commentId = randomUUID();
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    await db.insert(agents).values({
+      id: agentId,
+      companyId,
+      name: "CodexCoder",
+      role: "engineer",
+      status: "active",
+      adapterType: "codex_local",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: {},
+    });
+
+    await db.insert(issues).values({
+      id: issueId,
+      companyId,
+      title: "Comments issue",
+      status: "todo",
+      priority: "medium",
+    });
+
+    await db.insert(heartbeatRuns).values({
+      id: randomUUID(),
+      companyId,
+      agentId,
+      contextSnapshot: { issueId },
+      createdAt: new Date("2026-05-12T22:58:00.000Z"),
+      startedAt: new Date("2026-05-12T22:58:00.000Z"),
+      finishedAt: new Date("2026-05-12T23:14:00.000Z"),
+    });
+
+    await db.insert(issueComments).values({
+      id: commentId,
+      companyId,
+      issueId,
+      authorUserId: "user-1",
+      body: "Comment should be visible",
+      createdAt: new Date("2026-05-12T23:00:00.000Z"),
+      updatedAt: new Date("2026-05-12T23:00:00.000Z"),
+    });
+
+    const comments = await svc.listComments(issueId, {
+      order: "desc",
+      limit: 50,
+    });
+
+    expect(comments.map((comment) => comment.id)).toEqual([commentId]);
+    expect(comments[0]?.body).toBe("Comment should be visible");
+  });
+
   it("includes blockedBy summaries on list rows in one batched pass", async () => {
     const companyId = randomUUID();
     const blockerId = randomUUID();
diff --git a/server/src/__tests__/plugin-database.test.ts b/server/src/__tests__/plugin-database.test.ts
index 6392b78e..5ae677e5 100644
--- a/server/src/__tests__/plugin-database.test.ts
+++ b/server/src/__tests__/plugin-database.test.ts
@@ -25,7 +25,7 @@ import {
   validatePluginRuntimeExecute,
   validatePluginRuntimeQuery,
 } from "../services/plugin-database.js";
-import { pluginLoader } from "../services/plugin-loader.js";
+import { buildPluginWorkerEnv, pluginLoader } from "../services/plugin-loader.js";
 
 const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
 const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
@@ -84,6 +84,48 @@ describe("plugin database SQL validation", () => {
   });
 });
 
+describe("buildPluginWorkerEnv", () => {
+  const instanceInfo = {
+    deploymentMode: "authenticated",
+    deploymentExposure: "public",
+  };
+
+  it("passes only model provider keys through to environment driver plugins", () => {
+    const env = buildPluginWorkerEnv({
+      manifest: { capabilities: ["environment.drivers.register"] },
+      instanceInfo,
+      processEnv: {
+        ANTHROPIC_API_KEY: "anthropic-token",
+        OPENAI_API_KEY: "openai-token",
+        GEMINI_API_KEY: " ",
+        AWS_SECRET_ACCESS_KEY: "aws-secret",
+      },
+    });
+
+    expect(env).toEqual({
+      PAPERCLIP_DEPLOYMENT_MODE: "authenticated",
+      PAPERCLIP_DEPLOYMENT_EXPOSURE: "public",
+      ANTHROPIC_API_KEY: "anthropic-token",
+      OPENAI_API_KEY: "openai-token",
+    });
+  });
+
+  it("does not pass provider keys to non-environment plugins", () => {
+    const env = buildPluginWorkerEnv({
+      manifest: { capabilities: ["ui.slots.register"] },
+      instanceInfo,
+      processEnv: {
+        OPENAI_API_KEY: "openai-token",
+      },
+    });
+
+    expect(env).toEqual({
+      PAPERCLIP_DEPLOYMENT_MODE: "authenticated",
+      PAPERCLIP_DEPLOYMENT_EXPOSURE: "public",
+    });
+  });
+});
+
 describeEmbeddedPostgres("plugin database namespaces", () => {
   let db!: ReturnType<typeof createDb>;
   let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
diff --git a/server/src/__tests__/plugin-dev-watcher.test.ts b/server/src/__tests__/plugin-dev-watcher.test.ts
index 75df3105..c6ffa742 100644
--- a/server/src/__tests__/plugin-dev-watcher.test.ts
+++ b/server/src/__tests__/plugin-dev-watcher.test.ts
@@ -1,12 +1,28 @@
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { EventEmitter } from "node:events";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { resolvePluginWatchTargets } from "../services/plugin-dev-watcher.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const chokidarMock = vi.hoisted(() => ({
+  watch: vi.fn(),
+}));
+
+vi.mock("chokidar", () => ({
+  default: chokidarMock,
+}));
+
+import { createPluginDevWatcher, resolvePluginWatchTargets } from "../services/plugin-dev-watcher.js";
 
 const tempDirs: string[] = [];
 
+beforeEach(() => {
+  vi.useRealTimers();
+  chokidarMock.watch.mockReset();
+});
+
 afterEach(() => {
+  vi.useRealTimers();
   while (tempDirs.length > 0) {
     const dir = tempDirs.pop();
     if (dir) rmSync(dir, { recursive: true, force: true });
@@ -19,25 +35,49 @@ function makeTempPluginDir(): string {
   return dir;
 }
 
+function writePluginPackage(pluginDir: string): void {
+  mkdirSync(path.join(pluginDir, "dist", "ui"), { recursive: true });
+  writeFileSync(
+    path.join(pluginDir, "package.json"),
+    JSON.stringify({
+      name: "@acme/example",
+      paperclipPlugin: {
+        manifest: "./dist/manifest.js",
+        worker: "./dist/worker.js",
+        ui: "./dist/ui",
+      },
+    }),
+  );
+  writeFileSync(path.join(pluginDir, "dist", "manifest.js"), "export default {};\n");
+  writeFileSync(path.join(pluginDir, "dist", "worker.js"), "export default {};\n");
+  writeFileSync(path.join(pluginDir, "dist", "ui", "index.js"), "export default {};\n");
+  writeFileSync(path.join(pluginDir, "dist", "ui", "index.css"), "body {}\n");
+}
+
+function createLifecycle() {
+  const emitter = new EventEmitter();
+  return Object.assign(emitter, {
+    restartWorker: vi.fn().mockResolvedValue(undefined),
+  });
+}
+
+function installMockFsWatcher() {
+  const handlers: Record<string, (...args: unknown[]) => void> = {};
+  const fakeWatcher = {
+    close: vi.fn(),
+    on: vi.fn((event: string, listener: (...args: unknown[]) => void) => {
+      handlers[event] = listener;
+      return fakeWatcher;
+    }),
+  };
+  chokidarMock.watch.mockReturnValue(fakeWatcher);
+  return { fakeWatcher, handlers };
+}
+
 describe("resolvePluginWatchTargets", () => {
   it("watches package metadata plus concrete declared runtime files", () => {
     const pluginDir = makeTempPluginDir();
-    mkdirSync(path.join(pluginDir, "dist", "ui"), { recursive: true });
-    writeFileSync(
-      path.join(pluginDir, "package.json"),
-      JSON.stringify({
-        name: "@acme/example",
-        paperclipPlugin: {
-          manifest: "./dist/manifest.js",
-          worker: "./dist/worker.js",
-          ui: "./dist/ui",
-        },
-      }),
-    );
-    writeFileSync(path.join(pluginDir, "dist", "manifest.js"), "export default {};\n");
-    writeFileSync(path.join(pluginDir, "dist", "worker.js"), "export default {};\n");
-    writeFileSync(path.join(pluginDir, "dist", "ui", "index.js"), "export default {};\n");
-    writeFileSync(path.join(pluginDir, "dist", "ui", "index.css"), "body {}\n");
+    writePluginPackage(pluginDir);
 
     const targets = resolvePluginWatchTargets(pluginDir);
 
@@ -66,3 +106,43 @@ describe("resolvePluginWatchTargets", () => {
     ]);
   });
 });
+
+describe("createPluginDevWatcher", () => {
+  it("starts watching local plugins announced by lifecycle events", async () => {
+    const pluginDir = makeTempPluginDir();
+    writePluginPackage(pluginDir);
+    installMockFsWatcher();
+    const lifecycle = createLifecycle();
+
+    const devWatcher = createPluginDevWatcher(
+      lifecycle as never,
+      async (pluginId) => (pluginId === "plugin-1" ? pluginDir : null),
+    );
+
+    lifecycle.emit("plugin.loaded", { pluginId: "plugin-1", pluginKey: "example" });
+
+    await vi.waitFor(() => expect(chokidarMock.watch).toHaveBeenCalledTimes(1));
+    const [watchedPaths] = chokidarMock.watch.mock.calls[0] ?? [];
+    expect(watchedPaths).toContain(path.join(pluginDir, "dist", "worker.js"));
+
+    devWatcher.close();
+  });
+
+  it("debounces watched file changes and restarts the plugin worker", async () => {
+    vi.useFakeTimers();
+    const pluginDir = makeTempPluginDir();
+    writePluginPackage(pluginDir);
+    const { handlers } = installMockFsWatcher();
+    const lifecycle = createLifecycle();
+
+    const devWatcher = createPluginDevWatcher(lifecycle as never);
+    devWatcher.watch("plugin-1", pluginDir);
+
+    handlers.all?.("change", path.join(pluginDir, "dist", "worker.js"));
+    await vi.advanceTimersByTimeAsync(500);
+
+    expect(lifecycle.restartWorker).toHaveBeenCalledWith("plugin-1");
+
+    devWatcher.close();
+  });
+});
diff --git a/server/src/__tests__/plugin-routes-authz.test.ts b/server/src/__tests__/plugin-routes-authz.test.ts
index 52e678b4..963d3cd1 100644
--- a/server/src/__tests__/plugin-routes-authz.test.ts
+++ b/server/src/__tests__/plugin-routes-authz.test.ts
@@ -224,6 +224,46 @@ describe.sequential("plugin install and upgrade authz", () => {
     expect(mockLifecycle.disable).not.toHaveBeenCalled();
   }, 20_000);
 
+  it("resolves plugin keys without probing the UUID id column for core plugin actions", async () => {
+    const pluginKey = "paperclipqa.hello-plugin";
+    const plugin = {
+      id: pluginId,
+      pluginKey,
+      version: "1.0.0",
+      status: "ready",
+    };
+    mockRegistry.getById.mockImplementation(() => {
+      throw new Error("getById should not be called for plugin keys");
+    });
+    mockRegistry.getByKey.mockResolvedValue(plugin);
+    mockLifecycle.unload.mockResolvedValue(plugin);
+    mockLifecycle.enable.mockResolvedValue(plugin);
+    mockLifecycle.disable.mockResolvedValue(plugin);
+
+    const { app } = await createApp({
+      type: "board",
+      userId: "admin-1",
+      source: "session",
+      isInstanceAdmin: true,
+      companyIds: [companyA],
+    });
+
+    const inspectRes = await request(app).get(`/api/plugins/${pluginKey}`);
+    const disableRes = await request(app).post(`/api/plugins/${pluginKey}/disable`).send({});
+    const enableRes = await request(app).post(`/api/plugins/${pluginKey}/enable`).send({});
+    const uninstallRes = await request(app).delete(`/api/plugins/${pluginKey}?purge=true`);
+
+    expect(inspectRes.status).toBe(200);
+    expect(disableRes.status).toBe(200);
+    expect(enableRes.status).toBe(200);
+    expect(uninstallRes.status).toBe(200);
+    expect(mockRegistry.getById).not.toHaveBeenCalled();
+    expect(mockRegistry.getByKey).toHaveBeenCalledWith(pluginKey);
+    expect(mockLifecycle.disable).toHaveBeenCalledWith(pluginId, undefined);
+    expect(mockLifecycle.enable).toHaveBeenCalledWith(pluginId);
+    expect(mockLifecycle.unload).toHaveBeenCalledWith(pluginId, true);
+  }, 20_000);
+
   it("rejects plugin config saves that contain secret refs even for instance admins", async () => {
     readyPlugin();
 
diff --git a/server/src/app.ts b/server/src/app.ts
index d94475af..d0377184 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -420,12 +420,10 @@ export async function createApp(
   void toolDispatcher.initialize().catch((err) => {
     logger.error({ err }, "Failed to initialize plugin tool dispatcher");
   });
-  const devWatcher = opts.uiMode === "vite-dev"
-    ? createPluginDevWatcher(
-      lifecycle,
-      async (pluginId) => (await pluginRegistry.getById(pluginId))?.packagePath ?? null,
-    )
-    : null;
+  const devWatcher = createPluginDevWatcher(
+    lifecycle,
+    async (pluginId) => (await pluginRegistry.getById(pluginId))?.packagePath ?? null,
+  );
   void loader.loadAll().then((result) => {
     if (!result) return;
     for (const loaded of result.results) {
diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.ts
index 0567bb80..5bf94567 100644
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -42,6 +42,7 @@ import {
   heartbeatService,
   ISSUE_LIST_DEFAULT_LIMIT,
   issueApprovalService,
+  issueRecoveryActionService,
   issueService,
   logActivity,
   syncInstructionsBundleConfigFromFilePath,
@@ -1742,16 +1743,18 @@ export function agentRoutes(
     }
 
     const issuesSvc = issueService(db);
+    const recoveryActionsSvc = issueRecoveryActionService(db);
     const rows = await issuesSvc.list(req.actor.companyId, {
       assigneeAgentId: req.actor.agentId,
       status: "todo,in_progress,blocked",
       includeRoutineExecutions: true,
       limit: ISSUE_LIST_DEFAULT_LIMIT,
     });
-    const dependencyReadiness = await issuesSvc.listDependencyReadiness(
-      req.actor.companyId,
-      rows.map((issue) => issue.id),
-    );
+    const issueIds = rows.map((issue) => issue.id);
+    const [dependencyReadiness, recoveryActionByIssue] = await Promise.all([
+      issuesSvc.listDependencyReadiness(req.actor.companyId, issueIds),
+      recoveryActionsSvc.listActiveForIssues(req.actor.companyId, issueIds),
+    ]);
 
     res.json(
       rows.map((issue) => ({
@@ -1765,6 +1768,7 @@ export function agentRoutes(
         parentId: issue.parentId,
         updatedAt: issue.updatedAt,
         activeRun: issue.activeRun,
+        activeRecoveryAction: recoveryActionByIssue.get(issue.id) ?? null,
         dependencyReady: dependencyReadiness.get(issue.id)?.isDependencyReady ?? true,
         unresolvedBlockerCount: dependencyReadiness.get(issue.id)?.unresolvedBlockerCount ?? 0,
         unresolvedBlockerIssueIds: dependencyReadiness.get(issue.id)?.unresolvedBlockerIssueIds ?? [],
diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.ts
index 1b7a5a7d..b0f61244 100644
--- a/server/src/routes/issues.ts
+++ b/server/src/routes/issues.ts
@@ -2,9 +2,16 @@ import { randomUUID } from "node:crypto";
 import { Router, type Request, type Response } from "express";
 import multer from "multer";
 import { z } from "zod";
-import { and, desc, eq, inArray } from "drizzle-orm";
+import { and, desc, eq, inArray, notInArray } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
-import { activityLog, executionWorkspaces, issueExecutionDecisions, projectWorkspaces } from "@paperclipai/db";
+import {
+  activityLog,
+  executionWorkspaces,
+  issueExecutionDecisions,
+  issueRelations,
+  issues as issueRows,
+  projectWorkspaces,
+} from "@paperclipai/db";
 import {
   addIssueCommentSchema,
   acceptIssueThreadInteractionSchema,
@@ -18,6 +25,7 @@ import {
   createChildIssueSchema,
   createIssueSchema,
   resolveCreateIssueStatusDefault,
+  resolveIssueRecoveryActionSchema,
   feedbackTargetTypeSchema,
   feedbackTraceStatusSchema,
   feedbackVoteValueSchema,
@@ -37,6 +45,7 @@ import {
   type CompanySearchQuery,
   type CompanySearchResponse,
   type ExecutionWorkspace,
+  type IssueRelationIssueSummary,
   type SuccessfulRunHandoffState,
 } from "@paperclipai/shared";
 import { trackAgentTaskCompleted } from "@paperclipai/shared/telemetry";
@@ -53,6 +62,7 @@ import {
   goalService,
   heartbeatService,
   issueApprovalService,
+  issueRecoveryActionService,
   issueThreadInteractionService,
   ISSUE_LIST_DEFAULT_LIMIT,
   ISSUE_LIST_MAX_LIMIT,
@@ -405,6 +415,47 @@ async function listSuccessfulRunHandoffStates(
   return states;
 }
 
+type RecoveryActionsLister = {
+  listActiveForIssues: (
+    companyId: string,
+    sourceIssueIds: string[],
+  ) => Promise<Map<string, NonNullable<IssueRelationIssueSummary["activeRecoveryAction"]>>>;
+};
+
+async function relationRecoveryActionMap(
+  recoveryActionsSvc: RecoveryActionsLister,
+  companyId: string,
+  relations: { blockedBy: IssueRelationIssueSummary[]; blocks: IssueRelationIssueSummary[] },
+): Promise<Map<string, NonNullable<IssueRelationIssueSummary["activeRecoveryAction"]>>> {
+  const candidates: IssueRelationIssueSummary[] = [];
+  const visit = (summary: IssueRelationIssueSummary) => {
+    candidates.push(summary);
+    for (const terminal of summary.terminalBlockers ?? []) {
+      visit(terminal);
+    }
+  };
+  for (const blocker of relations.blockedBy) visit(blocker);
+  for (const blocking of relations.blocks) visit(blocking);
+  if (candidates.length === 0) return new Map();
+  const ids = [...new Set(candidates.map((summary) => summary.id))];
+  return recoveryActionsSvc.listActiveForIssues(companyId, ids);
+}
+
+function withRecoveryActionsOnRelationSummaries(
+  relations: { blockedBy: IssueRelationIssueSummary[]; blocks: IssueRelationIssueSummary[] },
+  recoveryActionByIssueId: Map<string, NonNullable<IssueRelationIssueSummary["activeRecoveryAction"]>>,
+) {
+  const augment = (summary: IssueRelationIssueSummary): IssueRelationIssueSummary => ({
+    ...summary,
+    activeRecoveryAction: recoveryActionByIssueId.get(summary.id) ?? summary.activeRecoveryAction ?? null,
+    terminalBlockers: summary.terminalBlockers?.map(augment),
+  });
+  return {
+    blockedBy: relations.blockedBy.map(augment),
+    blocks: relations.blocks.map(augment),
+  };
+}
+
 const ACTIVE_REVIEW_APPROVAL_STATUSES = new Set(["pending", "revision_requested"]);
 
 const INVALID_AGENT_IN_REVIEW_DISPOSITION_MESSAGE =
@@ -787,6 +838,7 @@ export function issueRoutes(
   const projectsSvc = projectService(db);
   const goalsSvc = goalService(db);
   const issueApprovalsSvc = issueApprovalService(db);
+  const recoveryActionsSvc = issueRecoveryActionService(db);
   const executionWorkspacesSvc = executionWorkspaceServiceDirect(db);
   const workProductsSvc = workProductService(db);
   const documentsSvc = documentService(db);
@@ -1392,6 +1444,7 @@ export function issueRoutes(
     const parsedOffset = rawOffset !== undefined && /^\d+$/.test(rawOffset)
       ? Number.parseInt(rawOffset, 10)
       : null;
+    const attention = req.query.attention as string | undefined;
 
     if (assigneeUserFilterRaw === "me" && (!assigneeUserId || req.actor.type !== "board")) {
       res.status(403).json({ error: "assigneeUserId=me requires board authentication" });
@@ -1409,6 +1462,10 @@ export function issueRoutes(
       res.status(403).json({ error: "unreadForUserId=me requires board authentication" });
       return;
     }
+    if (attention !== undefined && attention !== "blocked") {
+      res.status(400).json({ error: "attention must be 'blocked' when provided" });
+      return;
+    }
     if (rawLimit !== undefined && (parsedLimit === null || !Number.isInteger(parsedLimit) || parsedLimit <= 0)) {
       res.status(400).json({ error: `limit must be a positive integer up to ${ISSUE_LIST_MAX_LIMIT}` });
       return;
@@ -1420,6 +1477,7 @@ export function issueRoutes(
     const offset = parsedOffset ?? 0;
 
     const result = await svc.list(companyId, {
+      attention: attention === "blocked" ? "blocked" : undefined,
       status: req.query.status as string | undefined,
       assigneeAgentId: req.query.assigneeAgentId as string | undefined,
       participantAgentId: req.query.participantAgentId as string | undefined,
@@ -1443,21 +1501,65 @@ export function issueRoutes(
       includePluginOperations:
         req.query.includePluginOperations === "true" || req.query.includePluginOperations === "1",
       includeBlockedBy: req.query.includeBlockedBy === "true" || req.query.includeBlockedBy === "1",
+      includeBlockedInboxAttention:
+        req.query.includeBlockedInboxAttention === "true" || req.query.includeBlockedInboxAttention === "1",
       q: req.query.q as string | undefined,
       limit,
       offset,
     });
-    const handoffStates = await listSuccessfulRunHandoffStates(
-      db,
-      companyId,
-      result.map((issue) => issue.id),
-    );
+    const issueIds = result.map((issue) => issue.id);
+    const [handoffStates, recoveryActionByIssue] = await Promise.all([
+      listSuccessfulRunHandoffStates(db, companyId, issueIds),
+      recoveryActionsSvc.listActiveForIssues(companyId, issueIds),
+    ]);
     res.json(result.map((issue) => ({
       ...issue,
       successfulRunHandoff: handoffStates.get(issue.id) ?? null,
+      activeRecoveryAction: recoveryActionByIssue.get(issue.id) ?? null,
     })));
   });
 
+  router.get("/companies/:companyId/issues/count", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    assertCompanyAccess(req, companyId);
+    const attention = req.query.attention as string | undefined;
+    if (attention !== "blocked") {
+      res.status(400).json({ error: "issues/count currently requires attention=blocked" });
+      return;
+    }
+    if (req.query.limit !== undefined || req.query.offset !== undefined) {
+      res.status(400).json({ error: "issues/count does not accept limit or offset" });
+      return;
+    }
+
+    const count = await svc.count(companyId, {
+      attention: "blocked",
+      status: req.query.status as string | undefined,
+      assigneeAgentId: req.query.assigneeAgentId as string | undefined,
+      participantAgentId: req.query.participantAgentId as string | undefined,
+      assigneeUserId: req.query.assigneeUserId as string | undefined,
+      projectId: req.query.projectId as string | undefined,
+      workspaceId: req.query.workspaceId as string | undefined,
+      executionWorkspaceId: req.query.executionWorkspaceId as string | undefined,
+      parentId: req.query.parentId as string | undefined,
+      descendantOf: req.query.descendantOf as string | undefined,
+      labelId: req.query.labelId as string | undefined,
+      originKind: req.query.originKind as string | undefined,
+      originKindPrefix: req.query.originKindPrefix as string | undefined,
+      originId: req.query.originId as string | undefined,
+      includeRoutineExecutions:
+        req.query.includeRoutineExecutions === "true" || req.query.includeRoutineExecutions === "1",
+      excludeRoutineExecutions:
+        req.query.excludeRoutineExecutions === "true" || req.query.excludeRoutineExecutions === "1",
+      includePluginOperations:
+        req.query.includePluginOperations === "true" || req.query.includePluginOperations === "1",
+      includeBlockedBy: true,
+      includeBlockedInboxAttention: true,
+      q: req.query.q as string | undefined,
+    });
+    res.json({ count });
+  });
+
   router.get("/companies/:companyId/labels", async (req, res) => {
     const companyId = req.params.companyId as string;
     assertCompanyAccess(req, companyId);
@@ -1541,6 +1643,7 @@ export function issueRoutes(
       attachments,
       continuationSummary,
       currentExecutionWorkspace,
+      activeRecoveryAction,
     ] =
       await Promise.all([
         resolveIssueProjectAndGoal(issue),
@@ -1554,7 +1657,17 @@ export function issueRoutes(
         svc.listAttachments(issue.id),
         documentsSvc.getIssueDocumentByKey(issue.id, ISSUE_CONTINUATION_SUMMARY_DOCUMENT_KEY),
         currentExecutionWorkspacePromise,
+        recoveryActionsSvc.getActiveForIssue(issue.companyId, issue.id),
       ]);
+    const recoveryActionsByRelationIssue = await relationRecoveryActionMap(
+      recoveryActionsSvc,
+      issue.companyId,
+      relations,
+    );
+    const relationsWithRecoveryActions = withRecoveryActionsOnRelationSummaries(
+      relations,
+      recoveryActionsByRelationIssue,
+    );
 
     res.json({
       issue: {
@@ -1567,12 +1680,13 @@ export function issueRoutes(
         ...(blockerAttention ? { blockerAttention } : {}),
         productivityReview,
         scheduledRetry,
+        activeRecoveryAction,
         priority: issue.priority,
         projectId: issue.projectId,
         goalId: goal?.id ?? issue.goalId,
         parentId: issue.parentId,
-        blockedBy: relations.blockedBy,
-        blocks: relations.blocks,
+        blockedBy: relationsWithRecoveryActions.blockedBy,
+        blocks: relationsWithRecoveryActions.blocks,
         assigneeAgentId: issue.assigneeAgentId,
         assigneeUserId: issue.assigneeUserId,
         originKind: issue.originKind,
@@ -1649,6 +1763,7 @@ export function issueRoutes(
       referenceSummary,
       successfulRunHandoffStates,
       scheduledRetry,
+      activeRecoveryAction,
     ] = await Promise.all([
       resolveIssueProjectAndGoal(issue),
       svc.getAncestors(issue.id),
@@ -1660,7 +1775,17 @@ export function issueRoutes(
       issueReferencesSvc.listIssueReferenceSummary(issue.id),
       listSuccessfulRunHandoffStates(db, issue.companyId, [issue.id]),
       svc.getCurrentScheduledRetry(issue.id),
+      recoveryActionsSvc.getActiveForIssue(issue.companyId, issue.id),
     ]);
+    const recoveryActionsByRelationIssue = await relationRecoveryActionMap(
+      recoveryActionsSvc,
+      issue.companyId,
+      relations,
+    );
+    const relationsWithRecoveryActions = withRecoveryActionsOnRelationSummaries(
+      relations,
+      recoveryActionsByRelationIssue,
+    );
     const mentionedProjects = mentionedProjectIds.length > 0
       ? await projectsSvc.listByIds(issue.companyId, mentionedProjectIds)
       : [];
@@ -1676,8 +1801,9 @@ export function issueRoutes(
       productivityReview,
       successfulRunHandoff: successfulRunHandoffStates.get(issue.id) ?? null,
       scheduledRetry,
-      blockedBy: relations.blockedBy,
-      blocks: relations.blocks,
+      activeRecoveryAction,
+      blockedBy: relationsWithRecoveryActions.blockedBy,
+      blocks: relationsWithRecoveryActions.blocks,
       relatedWork: referenceSummary,
       referencedIssueIdentifiers: referenceSummary.outbound.map((item) => item.issue.identifier ?? item.issue.id),
       ...documentPayload,
@@ -1689,6 +1815,148 @@ export function issueRoutes(
     });
   });
 
+  router.get("/issues/:id/recovery-actions", async (req, res) => {
+    const id = req.params.id as string;
+    const issue = await svc.getById(id);
+    if (!issue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, issue.companyId);
+    const active = await recoveryActionsSvc.getActiveForIssue(issue.companyId, issue.id);
+    res.json({
+      active,
+      actions: active ? [active] : [],
+    });
+  });
+
+  router.post("/issues/:id/recovery-actions/resolve", validate(resolveIssueRecoveryActionSchema), async (req, res) => {
+    const id = req.params.id as string;
+    const existing = await svc.getById(id);
+    if (!existing) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, existing.companyId);
+    if (!(await assertAgentIssueMutationAllowed(req, res, existing))) return;
+
+    const { actionId, outcome, sourceIssueStatus, resolutionNote } = req.body;
+    if (outcome === "false_positive" || outcome === "cancelled") {
+      assertBoard(req);
+    }
+
+    const actor = getActorInfo(req);
+    const updateFields = sourceIssueStatus ? { status: sourceIssueStatus } : {};
+    await assertAgentInReviewReviewPath({
+      existing,
+      updateFields,
+      actorType: req.actor.type,
+    });
+
+    const actionStatus = outcome === "cancelled" ? "cancelled" : "resolved";
+    const result = await db.transaction(async (tx) => {
+      let issue = existing;
+      if (outcome === "blocked") {
+        const unresolvedBlockers = await tx
+          .select({ id: issueRows.id })
+          .from(issueRelations)
+          .innerJoin(issueRows, eq(issueRelations.issueId, issueRows.id))
+          .where(
+            and(
+              eq(issueRelations.companyId, existing.companyId),
+              eq(issueRelations.relatedIssueId, existing.id),
+              eq(issueRelations.type, "blocks"),
+              notInArray(issueRows.status, ["done", "cancelled"]),
+            ),
+          )
+          .limit(1);
+        if (unresolvedBlockers.length === 0) {
+          throw unprocessable("Blocked recovery resolution requires an unresolved first-class blocker on the source issue");
+        }
+      }
+
+      if (sourceIssueStatus) {
+        const updatedIssue = await svc.update(
+          id,
+          {
+            status: sourceIssueStatus,
+            actorAgentId: actor.agentId ?? null,
+            actorUserId: actor.actorType === "user" ? actor.actorId : null,
+          },
+          tx,
+        );
+        if (!updatedIssue) throw notFound("Issue not found");
+        issue = updatedIssue;
+      }
+
+      const recoveryAction = await recoveryActionsSvc.resolveActiveForIssue(
+        {
+          companyId: existing.companyId,
+          sourceIssueId: existing.id,
+          actionId: actionId ?? null,
+          status: actionStatus,
+          outcome,
+          resolutionNote: resolutionNote ?? null,
+        },
+        tx,
+      );
+      if (!recoveryAction) throw notFound("Active recovery action not found");
+
+      return { issue, recoveryAction };
+    });
+
+    await routinesSvc.syncRunStatusForIssue(result.issue.id);
+
+    if (sourceIssueStatus && existing.status !== result.issue.status) {
+      await logActivity(db, {
+        companyId: result.issue.companyId,
+        actorType: actor.actorType,
+        actorId: actor.actorId,
+        agentId: actor.agentId,
+        runId: actor.runId,
+        action: "issue.updated",
+        entityType: "issue",
+        entityId: result.issue.id,
+        details: {
+          identifier: result.issue.identifier,
+          status: result.issue.status,
+          source: "recovery_action_resolution",
+          recoveryActionId: result.recoveryAction.id,
+          _previous: {
+            status: existing.status,
+          },
+        },
+      });
+    }
+
+    await logActivity(db, {
+      companyId: result.issue.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "issue.recovery_action_resolved",
+      entityType: "issue",
+      entityId: result.issue.id,
+      details: {
+        identifier: result.issue.identifier,
+        recoveryActionId: result.recoveryAction.id,
+        recoveryActionStatus: result.recoveryAction.status,
+        outcome: result.recoveryAction.outcome,
+        sourceIssueStatus: sourceIssueStatus ?? null,
+        resolutionNote: result.recoveryAction.resolutionNote,
+      },
+    });
+
+    res.json({
+      issue: {
+        ...result.issue,
+        activeRecoveryAction: null,
+      },
+      recoveryAction: result.recoveryAction,
+    });
+  });
+
   router.get("/issues/:id/work-products", async (req, res) => {
     const id = req.params.id as string;
     const issue = await svc.getById(id);
diff --git a/server/src/routes/plugins.ts b/server/src/routes/plugins.ts
index 75a206b1..44368518 100644
--- a/server/src/routes/plugins.ts
+++ b/server/src/routes/plugins.ts
@@ -199,9 +199,9 @@ function listBundledPluginExamples(): AvailablePluginExample[] {
  *
  * Lookup order:
  * - UUID-like IDs: getById first, then getByKey.
- * - Scoped package keys (e.g. "@scope/name"): getByKey only, never getById.
- * - Other non-UUID IDs: try getById first (test/memory registries may allow this),
- *   then fallback to getByKey. Any UUID parse error from getById is ignored.
+ * - All non-UUID values: getByKey only, never getById. The persisted plugin
+ *   ID column is a PostgreSQL UUID, so probing it with keys such as
+ *   "acme.plugin" raises a database cast error before a key lookup can happen.
  *
  * @param registry - The plugin registry service instance
  * @param pluginId - Either a database UUID or plugin key (manifest id)
@@ -212,27 +212,13 @@ async function resolvePlugin(
   pluginId: string,
 ) {
   const isUuid = UUID_REGEX.test(pluginId);
-  const isScopedPackageKey = pluginId.startsWith("@") || pluginId.includes("/");
 
-  // Scoped package IDs are valid plugin keys but invalid UUIDs.
-  // Skip getById() entirely to avoid Postgres uuid parse errors.
-  if (isScopedPackageKey && !isUuid) {
+  if (!isUuid) {
     return registry.getByKey(pluginId);
   }
 
-  try {
-    const byId = await registry.getById(pluginId);
-    if (byId) return byId;
-  } catch (error) {
-    const maybeCode =
-      typeof error === "object" && error !== null && "code" in error
-        ? (error as { code?: unknown }).code
-        : undefined;
-    // Ignore invalid UUID cast errors and continue with key lookup.
-    if (maybeCode !== "22P02") {
-      throw error;
-    }
-  }
+  const byId = await registry.getById(pluginId);
+  if (byId) return byId;
 
   return registry.getByKey(pluginId);
 }
diff --git a/server/src/services/company-skills.ts b/server/src/services/company-skills.ts
index 51c2ad0b..3dd8ca88 100644
--- a/server/src/services/company-skills.ts
+++ b/server/src/services/company-skills.ts
@@ -29,7 +29,7 @@ import type {
 import { normalizeAgentUrlKey } from "@paperclipai/shared";
 import { resolvePaperclipInstanceRoot } from "../home-paths.js";
 import { notFound, unprocessable } from "../errors.js";
-import { ghFetch, gitHubApiBase, inferGitHostFamily, resolveRawGitHubUrl } from "./github-fetch.js";
+import { openRepoSnapshot, parseGitSourceUrl, resolveGitRef, type ParsedGitSource, type RepoSnapshot } from "./git-source.js";
 import { agentService } from "./agents.js";
 import { projectService } from "./projects.js";
 import { secretService } from "./secrets.js";
@@ -541,106 +541,20 @@ function parseFrontmatterMarkdown(raw: string): { frontmatter: Record<string, un
   };
 }
 
-async function fetchText(url: string, authToken?: string) {
-  const response = await ghFetch(url, undefined, authToken);
+async function fetchPlainText(url: string) {
+  let response: Response;
+  try {
+    response = await fetch(url);
+  } catch {
+    const hostname = (() => { try { return new URL(url).hostname; } catch { return url; } })();
+    throw unprocessable(`Could not connect to ${hostname}`);
+  }
   if (!response.ok) {
     throw unprocessable(`Failed to fetch ${url}: ${response.status}`);
   }
   return response.text();
 }
 
-async function fetchJson<T>(url: string, authToken?: string): Promise<T> {
-  const response = await ghFetch(url, {
-    headers: {
-      accept: "application/vnd.github+json",
-    },
-  }, authToken);
-  if (!response.ok) {
-    throw unprocessable(`Failed to fetch ${url}: ${response.status}`);
-  }
-  return response.json() as Promise<T>;
-}
-
-
-async function resolveGitHubDefaultBranch(owner: string, repo: string, apiBase: string, authToken?: string) {
-  const response = await fetchJson<{ default_branch?: string }>(
-    `${apiBase}/repos/${owner}/${repo}`,
-    authToken,
-  );
-  return asString(response.default_branch) ?? "main";
-}
-
-async function resolveGitHubCommitSha(owner: string, repo: string, ref: string, apiBase: string, authToken?: string) {
-  const response = await fetchJson<{ sha?: string }>(
-    `${apiBase}/repos/${owner}/${repo}/commits/${encodeURIComponent(ref)}`,
-    authToken,
-  );
-  const sha = asString(response.sha);
-  if (!sha) {
-    throw unprocessable(`Failed to resolve ref ${ref}`);
-  }
-  return sha;
-}
-
-function parseGitHubSourceUrl(rawUrl: string) {
-  const url = new URL(rawUrl);
-  if (url.protocol !== "https:") {
-    throw unprocessable("Source URL must use HTTPS");
-  }
-  const parts = url.pathname.split("/").filter(Boolean);
-  if (parts.length < 2) {
-    throw unprocessable("Invalid git source URL");
-  }
-  const owner = parts[0]!;
-  const repo = parts[1]!.replace(/\.git$/i, "");
-  const family = inferGitHostFamily(url.hostname);
-  let ref = "main";
-  let basePath = "";
-  let filePath: string | null = null;
-  let explicitRef = false;
-  if (family === "github") {
-    if (parts[2] === "tree") {
-      ref = parts[3] ?? "main";
-      basePath = parts.slice(4).join("/");
-      explicitRef = true;
-    } else if (parts[2] === "blob") {
-      ref = parts[3] ?? "main";
-      filePath = parts.slice(4).join("/");
-      basePath = filePath ? path.posix.dirname(filePath) : "";
-      explicitRef = true;
-    }
-  } else if (parts[2] === "src" && (parts[3] === "branch" || parts[3] === "commit" || parts[3] === "tag")) {
-    // Gitea/Forgejo web URLs: /{owner}/{repo}/src/{branch|commit|tag}/{ref}/{path}
-    ref = parts[4] ?? "main";
-    const tail = parts.slice(5);
-    const tailJoined = tail.join("/");
-    if (tail.length > 0 && /\.[A-Za-z0-9]+$/.test(tail[tail.length - 1]!)) {
-      filePath = tailJoined;
-      basePath = path.posix.dirname(tailJoined);
-    } else {
-      basePath = tailJoined;
-    }
-    explicitRef = true;
-  }
-  return { hostname: url.hostname, owner, repo, ref, basePath, filePath, explicitRef };
-}
-
-async function resolveGitHubPinnedRef(parsed: ReturnType<typeof parseGitHubSourceUrl>, authToken?: string) {
-  const apiBase = gitHubApiBase(parsed.hostname);
-  if (/^[0-9a-f]{40}$/i.test(parsed.ref.trim())) {
-    return {
-      pinnedRef: parsed.ref,
-      trackingRef: parsed.explicitRef ? parsed.ref : null,
-    };
-  }
-
-  const trackingRef = parsed.explicitRef
-    ? parsed.ref
-    : await resolveGitHubDefaultBranch(parsed.owner, parsed.repo, apiBase, authToken);
-  const pinnedRef = await resolveGitHubCommitSha(parsed.owner, parsed.repo, trackingRef, apiBase, authToken);
-  return { pinnedRef, trackingRef };
-}
-
 
 function extractCommandTokens(raw: string) {
   const matches = raw.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
@@ -1081,20 +995,12 @@ async function readUrlSkillImports(
     return segments.length >= 2 && !parsed.pathname.endsWith(".md");
   } catch { return false; } })();
   if (looksLikeRepoUrl) {
-    const parsed = parseGitHubSourceUrl(url);
-    const apiBase = gitHubApiBase(parsed.hostname);
-    const { pinnedRef, trackingRef } = await resolveGitHubPinnedRef(parsed, authToken);
-    let ref = pinnedRef;
-    const tree = await fetchJson<{ tree?: Array<{ path: string; type: string }> }>(
-      `${apiBase}/repos/${parsed.owner}/${parsed.repo}/git/trees/${ref}?recursive=1`,
-      authToken,
-    ).catch(() => {
-      throw unprocessable(`Failed to read GitHub tree for ${url}`);
-    });
-    const allPaths = (tree.tree ?? [])
-      .filter((entry) => entry.type === "blob")
-      .map((entry) => entry.path)
-      .filter((entry): entry is string => typeof entry === "string");
+    const parsed = parseGitSourceUrl(url);
+    const resolved = await resolveGitRef(parsed, authToken);
+    const snapshot = await openRepoSnapshot(parsed, resolved.trackingRef, resolved.pinnedSha, authToken);
+    const ref = snapshot.sha;
+    const trackingRef = resolved.trackingRef;
+    const allPaths = await snapshot.listFiles();
     const basePrefix = parsed.basePath ? `${parsed.basePath.replace(/^\/+|\/+$/g, "")}/` : "";
     const scopedPaths = basePrefix
       ? allPaths.filter((entry) => entry.startsWith(basePrefix))
@@ -1108,13 +1014,13 @@ async function readUrlSkillImports(
     );
     if (skillPaths.length === 0) {
       throw unprocessable(
-        "No SKILL.md files were found in the provided GitHub source.",
+        "No SKILL.md files were found in the provided source.",
       );
     }
     const skills: ImportedSkill[] = [];
     for (const relativeSkillPath of skillPaths) {
       const repoSkillPath = basePrefix ? `${basePrefix}${relativeSkillPath}` : relativeSkillPath;
-      const markdown = await fetchText(resolveRawGitHubUrl(parsed.hostname, parsed.owner, parsed.repo, ref, repoSkillPath), authToken);
+      const markdown = await snapshot.readFile(repoSkillPath);
       const parsedMarkdown = parseFrontmatterMarkdown(markdown);
       const skillDir = path.posix.dirname(relativeSkillPath);
       const slug = deriveImportedSkillSlug(parsedMarkdown.frontmatter, path.posix.basename(skillDir));
@@ -1168,15 +1074,15 @@ async function readUrlSkillImports(
     if (skills.length === 0) {
       throw unprocessable(
         requestedSkillSlug
-          ? `Skill ${requestedSkillSlug} was not found in the provided GitHub source.`
-          : "No SKILL.md files were found in the provided GitHub source.",
+          ? `Skill ${requestedSkillSlug} was not found in the provided source.`
+          : "No SKILL.md files were found in the provided source.",
       );
     }
     return { skills, warnings };
   }
 
   if (url.startsWith("http://") || url.startsWith("https://")) {
-    const markdown = await fetchText(url, authToken);
+    const markdown = await fetchPlainText(url);
     const parsedMarkdown = parseFrontmatterMarkdown(markdown);
     const urlObj = new URL(url);
     const fileName = path.posix.basename(urlObj.pathname);
@@ -1801,9 +1707,18 @@ export function companySkillService(db: Db) {
     }
 
     const hostname = asString(metadata.hostname) || "github.com";
-    const apiBase = gitHubApiBase(hostname);
     const authToken = await resolveSkillAuthToken(companyId, skill);
-    const latestRef = await resolveGitHubCommitSha(owner, repo, trackingRef, apiBase, authToken);
+    const parsed: ParsedGitSource = {
+      cloneUrl: `https://${hostname}/${owner}/${repo}.git`,
+      hostname,
+      owner,
+      repo,
+      ref: trackingRef,
+      basePath: "",
+      filePath: null,
+      explicitRef: true,
+    };
+    const { pinnedSha: latestRef } = await resolveGitRef(parsed, authToken);
     return {
       supported: true,
       reason: null,
@@ -1843,13 +1758,25 @@ export function companySkillService(db: Db) {
       const repo = asString(metadata.repo);
       const hostname = asString(metadata.hostname) || "github.com";
       const ref = skill.sourceRef ?? asString(metadata.ref) ?? "main";
+      const trackingRef = asString(metadata.trackingRef);
       const repoSkillDir = normalizeGitHubSkillDirectory(asString(metadata.repoSkillDir), skill.slug);
       if (!owner || !repo) {
         throw unprocessable("Skill source metadata is incomplete.");
       }
       const authToken = await resolveSkillAuthToken(companyId, skill);
       const repoPath = normalizePortablePath(path.posix.join(repoSkillDir, normalizedPath));
-      content = await fetchText(resolveRawGitHubUrl(hostname, owner, repo, ref, repoPath), authToken);
+      const parsedSource: ParsedGitSource = {
+        cloneUrl: `https://${hostname}/${owner}/${repo}.git`,
+        hostname,
+        owner,
+        repo,
+        ref,
+        basePath: repoSkillDir,
+        filePath: null,
+        explicitRef: true,
+      };
+      const snapshot: RepoSnapshot = await openRepoSnapshot(parsedSource, trackingRef ?? null, ref, authToken);
+      content = await snapshot.readFile(repoPath);
     } else if (skill.sourceType === "url") {
       if (normalizedPath !== "SKILL.md") {
         throw notFound("This skill source only exposes SKILL.md");
diff --git a/server/src/services/environment-execution-target.ts b/server/src/services/environment-execution-target.ts
index 2a506d41..33ea7015 100644
--- a/server/src/services/environment-execution-target.ts
+++ b/server/src/services/environment-execution-target.ts
@@ -46,6 +46,7 @@ export async function resolveEnvironmentExecutionTarget(input: {
     }
 
     const parsed = await resolveEnvironmentDriverConfigForRuntime(input.db, input.companyId, {
+      id: input.environment.id,
       driver: input.environment.driver as "sandbox",
       config: parseObject(input.environment.config),
     });
@@ -119,6 +120,7 @@ export async function resolveEnvironmentExecutionTarget(input: {
   }
 
   const parsed = await resolveEnvironmentDriverConfigForRuntime(input.db, input.companyId, {
+    id: input.environment.id,
     driver: input.environment.driver as "ssh",
     config: parseObject(input.environment.config),
   });
diff --git a/server/src/services/git-source.ts b/server/src/services/git-source.ts
new file mode 100644
index 00000000..f52dce46
--- /dev/null
+++ b/server/src/services/git-source.ts
@@ -0,0 +1,243 @@
+import path from "path";
+import git from "isomorphic-git";
+import http from "isomorphic-git/http/node";
+import { Volume, createFsFromVolume } from "memfs";
+
+import { unprocessable } from "../errors.js";
+
+export type ParsedGitSource = {
+  cloneUrl: string;
+  hostname: string;
+  owner: string;
+  repo: string;
+  ref: string | null;
+  basePath: string;
+  filePath: string | null;
+  explicitRef: boolean;
+};
+
+export type RefResolution = {
+  pinnedSha: string;
+  trackingRef: string | null;
+};
+
+export type RepoSnapshot = {
+  sha: string;
+  listFiles(): Promise<string[]>;
+  readFile(repoPath: string): Promise<string>;
+};
+
+const SHA_REGEX = /^[0-9a-f]{40}$/i;
+
+export function buildCloneUrl(hostname: string, owner: string, repo: string): string {
+  return `https://${hostname}/${owner}/${repo}.git`;
+}
+
+export function parseGitSourceUrl(rawUrl: string): ParsedGitSource {
+  let url: URL;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw unprocessable("Invalid git source URL");
+  }
+  if (url.protocol !== "https:") {
+    throw unprocessable("Source URL must use HTTPS");
+  }
+  const segments = url.pathname.split("/").filter(Boolean);
+  if (segments.length < 2) {
+    throw unprocessable("Source URL must include an owner and repository");
+  }
+  const owner = segments[0]!;
+  const repo = segments[1]!.replace(/\.git$/i, "");
+
+  let ref: string | null = null;
+  let basePath = "";
+  let filePath: string | null = null;
+  let explicitRef = false;
+  let tail: string[] = [];
+
+  // Recognise common host-specific URL shapes so users can paste a tree/blob link.
+  if (segments[2] === "tree" || segments[2] === "blob") {
+    // github.com style
+    ref = segments[3] ?? null;
+    tail = segments.slice(4);
+    explicitRef = ref !== null;
+  } else if (segments[2] === "src" && (segments[3] === "branch" || segments[3] === "commit" || segments[3] === "tag")) {
+    // gitea / forgejo style
+    ref = segments[4] ?? null;
+    tail = segments.slice(5);
+    explicitRef = ref !== null;
+  } else if (segments[2] === "-" && (segments[3] === "tree" || segments[3] === "blob")) {
+    // gitlab style: /{owner}/{repo}/-/tree/{ref}/{path}
+    ref = segments[4] ?? null;
+    tail = segments.slice(5);
+    explicitRef = ref !== null;
+  } else if (segments[2] === "src" && segments.length >= 4) {
+    // bitbucket style: /{owner}/{repo}/src/{ref}/{path}
+    ref = segments[3] ?? null;
+    tail = segments.slice(4);
+    explicitRef = ref !== null;
+  }
+
+  if (segments[2] === "blob" || (segments[2] === "-" && segments[3] === "blob")) {
+    const joined = tail.join("/");
+    filePath = joined || null;
+    basePath = filePath ? path.posix.dirname(filePath) : "";
+    if (basePath === ".") basePath = "";
+  } else if (tail.length > 0) {
+    const joined = tail.join("/");
+    // Heuristic: if the last segment looks like a file (has an extension), treat as file
+    const last = tail[tail.length - 1]!;
+    if (/\.[A-Za-z0-9]+$/.test(last)) {
+      filePath = joined;
+      basePath = path.posix.dirname(joined);
+      if (basePath === ".") basePath = "";
+    } else {
+      basePath = joined;
+    }
+  }
+
+  return {
+    cloneUrl: buildCloneUrl(url.hostname, owner, repo),
+    hostname: url.hostname,
+    owner,
+    repo,
+    ref,
+    basePath,
+    filePath,
+    explicitRef,
+  };
+}
+
+function buildAuthCallback(authToken: string | undefined) {
+  if (!authToken) return undefined;
+  // Universal pattern: token-as-username works for GitHub PATs (classic and fine-grained),
+  // GitLab project/personal access tokens, Gitea/Forgejo tokens, and Bitbucket app passwords
+  // when used over the git smart-HTTP protocol.
+  return () => ({ username: authToken, password: "x-oauth-basic" });
+}
+
+async function withGitErrors<T>(label: string, fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/HTTP Error: 401/i.test(message)) {
+      throw unprocessable(`${label}: authentication required or token rejected`);
+    }
+    if (/HTTP Error: 403/i.test(message)) {
+      throw unprocessable(`${label}: access forbidden`);
+    }
+    if (/HTTP Error: 404/i.test(message) || /repository not found/i.test(message)) {
+      throw unprocessable(`${label}: repository not found`);
+    }
+    if (/ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT/i.test(message)) {
+      throw unprocessable(`${label}: could not connect to host`);
+    }
+    throw unprocessable(`${label}: ${message}`);
+  }
+}
+
+export async function resolveGitRef(
+  parsed: ParsedGitSource,
+  authToken?: string,
+): Promise<RefResolution> {
+  const onAuth = buildAuthCallback(authToken);
+
+  if (parsed.ref && SHA_REGEX.test(parsed.ref.trim())) {
+    return {
+      pinnedSha: parsed.ref.trim().toLowerCase(),
+      trackingRef: parsed.explicitRef ? parsed.ref.trim() : null,
+    };
+  }
+
+  const refs = await withGitErrors(`Resolve refs for ${parsed.cloneUrl}`, () =>
+    git.listServerRefs({
+      http,
+      url: parsed.cloneUrl,
+      onAuth,
+      symrefs: true,
+      protocolVersion: 2,
+    }),
+  );
+
+  const findExact = (fullRef: string) => refs.find((r) => r.ref === fullRef);
+
+  if (!parsed.ref) {
+    const head = refs.find((r) => r.ref === "HEAD");
+    if (!head?.oid) {
+      throw unprocessable(`Could not determine default branch for ${parsed.cloneUrl}`);
+    }
+    const target = head.target?.replace(/^refs\/heads\//, "") ?? null;
+    return { pinnedSha: head.oid, trackingRef: target };
+  }
+
+  const wanted = parsed.ref.replace(/^refs\/(heads|tags)\//, "");
+  const branch = findExact(`refs/heads/${wanted}`);
+  if (branch?.oid) return { pinnedSha: branch.oid, trackingRef: wanted };
+
+  // Prefer the peeled (annotated) tag oid when present, else the tag object oid.
+  const peeled = findExact(`refs/tags/${wanted}^{}`);
+  if (peeled?.oid) return { pinnedSha: peeled.oid, trackingRef: wanted };
+  const tag = findExact(`refs/tags/${wanted}`);
+  if (tag?.oid) return { pinnedSha: tag.oid, trackingRef: wanted };
+
+  throw unprocessable(`Ref '${parsed.ref}' not found in ${parsed.cloneUrl}`);
+}
+
+export async function openRepoSnapshot(
+  parsed: ParsedGitSource,
+  trackingRef: string | null,
+  expectedSha: string,
+  authToken?: string,
+): Promise<RepoSnapshot> {
+  const volume = new Volume();
+  const fs = createFsFromVolume(volume) as unknown as Parameters<typeof git.clone>[0]["fs"];
+  const dir = "/repo";
+  const onAuth = buildAuthCallback(authToken);
+
+  await withGitErrors(`Clone ${parsed.cloneUrl}`, async () => {
+    await git.clone({
+      fs,
+      http,
+      dir,
+      url: parsed.cloneUrl,
+      ref: trackingRef ?? expectedSha,
+      singleBranch: true,
+      depth: 1,
+      noCheckout: true,
+      onAuth,
+    });
+  });
+
+  // Re-resolve to the actual commit cloned. If upstream moved between resolveGitRef and
+  // clone, we trust what we cloned (snapshot is self-consistent).
+  const sha = await git.resolveRef({ fs, dir, ref: "HEAD" });
+
+  async function listFiles(): Promise<string[]> {
+    const out: string[] = [];
+    await git.walk({
+      fs,
+      dir,
+      trees: [git.TREE({ ref: sha })],
+      map: async (filepath, entries) => {
+        if (filepath === ".") return;
+        const entry = entries?.[0];
+        if (!entry) return;
+        const type = await entry.type();
+        if (type === "blob") {
+          out.push(filepath);
+        }
+      },
+    });
+    return out;
+  }
+
+  async function readFile(repoPath: string): Promise<string> {
+    const normalized = repoPath.replace(/^\/+/, "");
+    const { blob } = await git.readBlob({ fs, dir, oid: sha, filepath: normalized });
+    return new TextDecoder("utf-8").decode(blob);
+  }
+
+  return { sha, listFiles, readFile };
+}
diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.ts
index 109691dd..3fa574b7 100644
--- a/server/src/services/heartbeat.ts
+++ b/server/src/services/heartbeat.ts
@@ -163,6 +163,7 @@ import { extractSkillMentionIds } from "@paperclipai/shared";
 import { environmentService } from "./environments.js";
 import { environmentRuntimeService } from "./environment-runtime.js";
 import { environmentRunOrchestrator } from "./environment-run-orchestrator.js";
+import { isUnsafeSessionWorkspaceCwd } from "./session-workspace-cwd.js";
 import type { PluginWorkerManager } from "./plugin-worker-manager.js";
 
 const MAX_LIVE_LOG_CHUNK_BYTES = 8 * 1024;
@@ -1691,6 +1692,7 @@ function shouldAutoCheckoutIssueForWake(input: {
   const wakeReason = readNonEmptyString(input.contextSnapshot?.wakeReason);
   if (!wakeReason) return false;
   if (wakeReason === "issue_comment_mentioned") return false;
+  if (wakeReason === "source_scoped_recovery_action") return false;
   if (wakeReason.startsWith("execution_")) return false;
 
   return true;
@@ -3567,7 +3569,8 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
     }
 
     const sessionCwd = readNonEmptyString(previousSessionParams?.cwd);
-    if (sessionCwd) {
+    const sessionCwdLooksUnsafe = isUnsafeSessionWorkspaceCwd(sessionCwd);
+    if (sessionCwd && !sessionCwdLooksUnsafe) {
       const sessionCwdExists = await fs
         .stat(sessionCwd)
         .then((stats) => stats.isDirectory())
@@ -3589,7 +3592,11 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
     const cwd = resolveDefaultAgentWorkspaceDir(agent.id);
     await fs.mkdir(cwd, { recursive: true });
     const warnings: string[] = [];
-    if (sessionCwd) {
+    if (sessionCwd && sessionCwdLooksUnsafe) {
+      warnings.push(
+        `Saved session workspace "${sessionCwd}" points at a system temp root and was rejected as untrusted. Using fallback workspace "${cwd}" for this run.`,
+      );
+    } else if (sessionCwd) {
       warnings.push(
         `Saved session workspace "${sessionCwd}" is not available. Using fallback workspace "${cwd}" for this run.`,
       );
@@ -5883,8 +5890,10 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
 
     // Fix A (lazy locking): stamp executionRunId now that the run is actually running,
     // not at queue time. Guard is idempotent — safe if called more than once.
-    const claimedIssueId = readNonEmptyString(parseObject(claimed.contextSnapshot).issueId);
-    if (claimedIssueId) {
+    const claimedContext = parseObject(claimed.contextSnapshot);
+    const claimedIssueId = readNonEmptyString(claimedContext.issueId);
+    const claimedWakeReason = readNonEmptyString(claimedContext.wakeReason);
+    if (claimedIssueId && claimedWakeReason !== "source_scoped_recovery_action") {
       const claimedAgent = await getAgent(claimed.agentId);
       await db
         .update(issues)
@@ -7873,7 +7882,8 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})
         });
         const livenessRun = finalizedRun;
         await refreshContinuationSummaryForRun(livenessRun, agent);
-        if (issueId && outcome === "succeeded") {
+        const skipRunIssueComment = parseObject(livenessRun.contextSnapshot).skipIssueComment === true;
+        if (issueId && outcome === "succeeded" && !skipRunIssueComment) {
           try {
             const existingRunComment = await findRunIssueComment(livenessRun.id, livenessRun.companyId, issueId);
             if (!existingRunComment) {
diff --git a/server/src/services/index.ts b/server/src/services/index.ts
index 5cdf0a1d..2e7c6bcd 100644
--- a/server/src/services/index.ts
+++ b/server/src/services/index.ts
@@ -24,6 +24,7 @@ export { issueThreadInteractionService } from "./issue-thread-interactions.js";
 export { issueTreeControlService } from "./issue-tree-control.js";
 export { issueApprovalService } from "./issue-approvals.js";
 export { issueReferenceService } from "./issue-references.js";
+export { issueRecoveryActionService } from "./issue-recovery-actions.js";
 export { goalService } from "./goals.js";
 export { activityService, type ActivityFilters } from "./activity.js";
 export { approvalService } from "./approvals.js";
diff --git a/server/src/services/issue-recovery-actions.ts b/server/src/services/issue-recovery-actions.ts
new file mode 100644
index 00000000..cf6083e6
--- /dev/null
+++ b/server/src/services/issue-recovery-actions.ts
@@ -0,0 +1,295 @@
+import { and, desc, eq, inArray } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { issueRecoveryActions } from "@paperclipai/db";
+import type {
+  IssueRecoveryAction,
+  IssueRecoveryActionKind,
+  IssueRecoveryActionOwnerType,
+  IssueRecoveryActionOutcome,
+  IssueRecoveryActionStatus,
+} from "@paperclipai/shared";
+
+const ACTIVE_RECOVERY_ACTION_STATUSES = ["active", "escalated"] as const satisfies readonly IssueRecoveryActionStatus[];
+const MAX_UPSERT_RETRIES = 3;
+
+type IssueRecoveryActionRow = typeof issueRecoveryActions.$inferSelect;
+type DbTransaction = Parameters<Parameters<Db["transaction"]>[0]>[0];
+type DbOrTransaction = Db | DbTransaction;
+
+export type UpsertIssueRecoveryActionInput = {
+  companyId: string;
+  sourceIssueId: string;
+  recoveryIssueId?: string | null;
+  kind: IssueRecoveryActionKind;
+  ownerType?: IssueRecoveryActionOwnerType;
+  ownerAgentId?: string | null;
+  ownerUserId?: string | null;
+  previousOwnerAgentId?: string | null;
+  returnOwnerAgentId?: string | null;
+  cause: string;
+  fingerprint: string;
+  evidence?: Record<string, unknown>;
+  nextAction: string;
+  wakePolicy?: Record<string, unknown> | null;
+  monitorPolicy?: Record<string, unknown> | null;
+  maxAttempts?: number | null;
+  timeoutAt?: Date | null;
+  lastAttemptAt?: Date | null;
+};
+
+export type ResolveIssueRecoveryActionInput = {
+  companyId: string;
+  sourceIssueId: string;
+  actionId?: string | null;
+  status: Extract<IssueRecoveryActionStatus, "resolved" | "cancelled">;
+  outcome: IssueRecoveryActionOutcome;
+  resolutionNote?: string | null;
+};
+
+function toReadModel(row: IssueRecoveryActionRow): IssueRecoveryAction {
+  return {
+    id: row.id,
+    companyId: row.companyId,
+    sourceIssueId: row.sourceIssueId,
+    recoveryIssueId: row.recoveryIssueId,
+    kind: row.kind as IssueRecoveryAction["kind"],
+    status: row.status as IssueRecoveryAction["status"],
+    ownerType: row.ownerType as IssueRecoveryAction["ownerType"],
+    ownerAgentId: row.ownerAgentId,
+    ownerUserId: row.ownerUserId,
+    previousOwnerAgentId: row.previousOwnerAgentId,
+    returnOwnerAgentId: row.returnOwnerAgentId,
+    cause: row.cause,
+    fingerprint: row.fingerprint,
+    evidence: row.evidence,
+    nextAction: row.nextAction,
+    wakePolicy: row.wakePolicy,
+    monitorPolicy: row.monitorPolicy,
+    attemptCount: row.attemptCount,
+    maxAttempts: row.maxAttempts,
+    timeoutAt: row.timeoutAt,
+    lastAttemptAt: row.lastAttemptAt,
+    outcome: row.outcome as IssueRecoveryAction["outcome"],
+    resolutionNote: row.resolutionNote,
+    resolvedAt: row.resolvedAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function isUniqueRecoveryActionConflict(error: unknown) {
+  const maybe = error as { code?: string; constraint?: string; message?: string } | null;
+  return Boolean(
+    maybe &&
+      maybe.code === "23505" &&
+      (
+        maybe.constraint === "issue_recovery_actions_active_source_uq" ||
+        maybe.constraint === "issue_recovery_actions_active_fingerprint_uq" ||
+        typeof maybe.message === "string" && (
+          maybe.message.includes("issue_recovery_actions_active_source_uq") ||
+          maybe.message.includes("issue_recovery_actions_active_fingerprint_uq")
+        )
+      ),
+  );
+}
+
+export function issueRecoveryActionService(db: Db) {
+  const upsertQueues = new Map<string, Promise<void>>();
+
+  async function runExclusiveUpsert<T>(
+    input: UpsertIssueRecoveryActionInput,
+    task: () => Promise<T>,
+  ): Promise<T> {
+    const key = `${input.companyId}:${input.sourceIssueId}`;
+    const previous = upsertQueues.get(key) ?? Promise.resolve();
+    let release: () => void = () => {};
+    const current = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const next = previous.catch(() => undefined).then(() => current);
+    upsertQueues.set(key, next);
+
+    await previous.catch(() => undefined);
+    try {
+      return await task();
+    } finally {
+      release();
+      if (upsertQueues.get(key) === next) {
+        upsertQueues.delete(key);
+      }
+    }
+  }
+
+  async function getActiveForIssue(companyId: string, sourceIssueId: string): Promise<IssueRecoveryAction | null> {
+    const row = await db
+      .select()
+      .from(issueRecoveryActions)
+      .where(
+        and(
+          eq(issueRecoveryActions.companyId, companyId),
+          eq(issueRecoveryActions.sourceIssueId, sourceIssueId),
+          inArray(issueRecoveryActions.status, [...ACTIVE_RECOVERY_ACTION_STATUSES]),
+        ),
+      )
+      .orderBy(desc(issueRecoveryActions.updatedAt))
+      .limit(1)
+      .then((rows) => rows[0] ?? null);
+    return row ? toReadModel(row) : null;
+  }
+
+  async function listActiveForIssues(companyId: string, sourceIssueIds: string[]) {
+    if (sourceIssueIds.length === 0) return new Map<string, IssueRecoveryAction>();
+    const rows = await db
+      .select()
+      .from(issueRecoveryActions)
+      .where(
+        and(
+          eq(issueRecoveryActions.companyId, companyId),
+          inArray(issueRecoveryActions.sourceIssueId, [...new Set(sourceIssueIds)]),
+          inArray(issueRecoveryActions.status, [...ACTIVE_RECOVERY_ACTION_STATUSES]),
+        ),
+      )
+      .orderBy(desc(issueRecoveryActions.updatedAt));
+    const result = new Map<string, IssueRecoveryAction>();
+    for (const row of rows) {
+      if (!result.has(row.sourceIssueId)) result.set(row.sourceIssueId, toReadModel(row));
+    }
+    return result;
+  }
+
+  async function retryUpsertSourceScoped(
+    input: UpsertIssueRecoveryActionInput,
+    retryCount: number,
+    error?: unknown,
+  ): Promise<IssueRecoveryAction> {
+    if (retryCount >= MAX_UPSERT_RETRIES) {
+      if (error) throw error;
+      throw new Error(
+        `Failed to upsert active recovery action for issue ${input.sourceIssueId} after ${MAX_UPSERT_RETRIES} retries`,
+      );
+    }
+    return upsertSourceScopedUnlocked(input, retryCount + 1);
+  }
+
+  async function upsertSourceScopedUnlocked(
+    input: UpsertIssueRecoveryActionInput,
+    retryCount = 0,
+  ): Promise<IssueRecoveryAction> {
+    const existing = await getActiveForIssue(input.companyId, input.sourceIssueId);
+    const now = new Date();
+    const ownerType = input.ownerType ?? (input.ownerAgentId ? "agent" : "board");
+    if (existing) {
+      const [updated] = await db
+        .update(issueRecoveryActions)
+        .set({
+          recoveryIssueId: input.recoveryIssueId ?? null,
+          kind: input.kind,
+          status: "active",
+          ownerType,
+          ownerAgentId: input.ownerAgentId ?? null,
+          ownerUserId: input.ownerUserId ?? null,
+          previousOwnerAgentId: input.previousOwnerAgentId ?? existing.previousOwnerAgentId,
+          returnOwnerAgentId: input.returnOwnerAgentId ?? existing.returnOwnerAgentId,
+          cause: input.cause,
+          fingerprint: input.fingerprint,
+          evidence: input.evidence ?? existing.evidence,
+          nextAction: input.nextAction,
+          wakePolicy: input.wakePolicy ?? null,
+          monitorPolicy: input.monitorPolicy ?? null,
+          attemptCount: existing.attemptCount + 1,
+          maxAttempts: input.maxAttempts ?? null,
+          timeoutAt: input.timeoutAt ?? null,
+          lastAttemptAt: input.lastAttemptAt ?? now,
+          outcome: null,
+          resolutionNote: null,
+          resolvedAt: null,
+          updatedAt: now,
+        })
+        .where(
+          and(
+            eq(issueRecoveryActions.id, existing.id),
+            inArray(issueRecoveryActions.status, [...ACTIVE_RECOVERY_ACTION_STATUSES]),
+          ),
+        )
+        .returning();
+      if (!updated) {
+        return retryUpsertSourceScoped(input, retryCount);
+      }
+      return toReadModel(updated!);
+    }
+
+    try {
+      const [created] = await db
+        .insert(issueRecoveryActions)
+        .values({
+          companyId: input.companyId,
+          sourceIssueId: input.sourceIssueId,
+          recoveryIssueId: input.recoveryIssueId ?? null,
+          kind: input.kind,
+          status: "active",
+          ownerType,
+          ownerAgentId: input.ownerAgentId ?? null,
+          ownerUserId: input.ownerUserId ?? null,
+          previousOwnerAgentId: input.previousOwnerAgentId ?? null,
+          returnOwnerAgentId: input.returnOwnerAgentId ?? null,
+          cause: input.cause,
+          fingerprint: input.fingerprint,
+          evidence: input.evidence ?? {},
+          nextAction: input.nextAction,
+          wakePolicy: input.wakePolicy ?? null,
+          monitorPolicy: input.monitorPolicy ?? null,
+          attemptCount: 1,
+          maxAttempts: input.maxAttempts ?? null,
+          timeoutAt: input.timeoutAt ?? null,
+          lastAttemptAt: input.lastAttemptAt ?? now,
+        })
+        .returning();
+      return toReadModel(created!);
+    } catch (error) {
+      if (!isUniqueRecoveryActionConflict(error)) throw error;
+      return retryUpsertSourceScoped(input, retryCount, error);
+    }
+  }
+
+  async function upsertSourceScoped(
+    input: UpsertIssueRecoveryActionInput,
+  ): Promise<IssueRecoveryAction> {
+    return runExclusiveUpsert(input, () => upsertSourceScopedUnlocked(input));
+  }
+
+  async function resolveActiveForIssue(
+    input: ResolveIssueRecoveryActionInput,
+    dbOrTx: DbOrTransaction = db,
+  ): Promise<IssueRecoveryAction | null> {
+    const now = new Date();
+    const predicates = [
+      eq(issueRecoveryActions.companyId, input.companyId),
+      eq(issueRecoveryActions.sourceIssueId, input.sourceIssueId),
+      inArray(issueRecoveryActions.status, [...ACTIVE_RECOVERY_ACTION_STATUSES]),
+    ];
+    if (input.actionId) {
+      predicates.push(eq(issueRecoveryActions.id, input.actionId));
+    }
+
+    const [updated] = await dbOrTx
+      .update(issueRecoveryActions)
+      .set({
+        status: input.status,
+        outcome: input.outcome,
+        resolutionNote: input.resolutionNote ?? null,
+        resolvedAt: now,
+        updatedAt: now,
+      })
+      .where(and(...predicates))
+      .returning();
+
+    return updated ? toReadModel(updated) : null;
+  }
+
+  return {
+    getActiveForIssue,
+    listActiveForIssues,
+    resolveActiveForIssue,
+    upsertSourceScoped,
+  };
+}
diff --git a/server/src/services/issues.ts b/server/src/services/issues.ts
index 2d4ba3ff..e0a3f1a5 100644
--- a/server/src/services/issues.ts
+++ b/server/src/services/issues.ts
@@ -17,6 +17,7 @@ import {
   issueAttachments,
   issueInboxArchives,
   issueLabels,
+  issueRecoveryActions,
   issueRelations,
   issueComments,
   issueDocuments,
@@ -32,9 +33,12 @@ import type {
   IssueCommentMetadata,
   IssueCommentPresentation,
   IssueBlockerAttention,
+  IssueBlockedInboxAttention,
+  IssueBlockedInboxIssueRef,
   IssueProductivityReview,
   IssueProductivityReviewTrigger,
   IssueRelationIssueSummary,
+  SuccessfulRunHandoffState,
 } from "@paperclipai/shared";
 import {
   clampIssueRequestDepth,
@@ -59,7 +63,9 @@ import { mergeExecutionWorkspaceConfig } from "./execution-workspaces.js";
 import { buildInitialIssueMonitorFields, normalizeIssueExecutionPolicy } from "./issue-execution-policy.js";
 import { instanceSettingsService } from "./instance-settings.js";
 import { redactCurrentUserText } from "../log-redaction.js";
+import { redactSensitiveText } from "../redaction.js";
 import { resolveIssueGoalId, resolveNextIssueGoalId } from "./issue-goal-fallback.js";
+import { getRunLogStore } from "./run-log-store.js";
 import { getDefaultCompanyGoal } from "./goals.js";
 import {
   isVerifiedIssueTreeControlInteractionWake,
@@ -67,6 +73,7 @@ import {
   type ActiveIssueTreePauseHoldGate,
 } from "./issue-tree-control.js";
 import { parseIssueGraphLivenessIncidentKey } from "./recovery/origins.js";
+import { classifyIssueGraphLiveness, type IssueLivenessFinding } from "./recovery/issue-graph-liveness.js";
 
 const ALL_ISSUE_STATUSES = ["backlog", "todo", "in_progress", "in_review", "blocked", "done", "cancelled"];
 const MAX_ISSUE_COMMENT_PAGE_LIMIT = 500;
@@ -76,6 +83,10 @@ const ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE = 500;
 export const MAX_CHILD_ISSUES_CREATED_BY_HELPER = 25;
 const MAX_CHILD_COMPLETION_SUMMARIES = 20;
 const CHILD_COMPLETION_SUMMARY_BODY_MAX_CHARS = 500;
+const ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_LOG_BYTES = 2_000_000;
+const ISSUE_COMMENT_RUN_LOG_DERIVATION_CHUNK_BYTES = 256_000;
+const ISSUE_COMMENT_RUN_LOG_DERIVATION_END_SLACK_MS = 60_000;
+const ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_PARALLEL_READS = 8;
 function assertTransition(from: string, to: string) {
   if (from === to) return;
   if (!ALL_ISSUE_STATUSES.includes(to)) {
@@ -118,7 +129,88 @@ function buildReusedExecutionWorkspaceConfigPatchFromIssueSettings(
   };
 }
 
+function toTimestampMs(value: Date | string | null | undefined) {
+  if (!value) return null;
+  const date = value instanceof Date ? value : new Date(value);
+  const timestamp = date.getTime();
+  return Number.isFinite(timestamp) ? timestamp : null;
+}
+
+type IssueCommentRunLogAttributionCandidate = {
+  id: string;
+  createdAt: Date | string;
+  authorAgentId?: string | null;
+  authorUserId?: string | null;
+  createdByRunId?: string | null;
+};
+
+type IssueCommentRunLogAttributionRun = {
+  runId: string;
+  agentId: string;
+  createdAt: Date | string;
+  startedAt?: Date | string | null;
+  finishedAt?: Date | string | null;
+  logContent: string;
+};
+
+export function deriveIssueCommentRunLogAttribution(
+  comments: readonly IssueCommentRunLogAttributionCandidate[],
+  runs: readonly IssueCommentRunLogAttributionRun[],
+) {
+  const derivedByCommentId = new Map<string, {
+    derivedAuthorAgentId: string;
+    derivedCreatedByRunId: string;
+    derivedAuthorSource: "run_log_comment_post";
+  }>();
+
+  for (const comment of comments) {
+    if (comment.authorAgentId || !comment.authorUserId || comment.createdByRunId) continue;
+    const commentCreatedAtMs = toTimestampMs(comment.createdAt);
+    if (commentCreatedAtMs === null) continue;
+
+    let bestMatch:
+      | {
+        runId: string;
+        agentId: string;
+        distanceMs: number;
+      }
+      | null = null;
+
+    for (const run of runs) {
+      const runStartMs = toTimestampMs(run.startedAt ?? run.createdAt);
+      const runEndMs = toTimestampMs(run.finishedAt ?? run.createdAt);
+      if (runStartMs === null || runEndMs === null) continue;
+      if (
+        commentCreatedAtMs < runStartMs
+        || commentCreatedAtMs > runEndMs + ISSUE_COMMENT_RUN_LOG_DERIVATION_END_SLACK_MS
+      ) {
+        continue;
+      }
+      if (!run.logContent.includes(`comment id: ${comment.id}`)) continue;
+
+      const distanceMs = Math.abs(runEndMs - commentCreatedAtMs);
+      if (!bestMatch || distanceMs < bestMatch.distanceMs) {
+        bestMatch = {
+          runId: run.runId,
+          agentId: run.agentId,
+          distanceMs,
+        };
+      }
+    }
+
+    if (!bestMatch) continue;
+    derivedByCommentId.set(comment.id, {
+      derivedAuthorAgentId: bestMatch.agentId,
+      derivedCreatedByRunId: bestMatch.runId,
+      derivedAuthorSource: "run_log_comment_post",
+    });
+  }
+
+  return derivedByCommentId;
+}
+
 export interface IssueFilters {
+  attention?: "blocked";
   status?: string;
   assigneeAgentId?: string;
   participantAgentId?: string;
@@ -139,6 +231,7 @@ export interface IssueFilters {
   excludeRoutineExecutions?: boolean;
   includePluginOperations?: boolean;
   includeBlockedBy?: boolean;
+  includeBlockedInboxAttention?: boolean;
   q?: string;
   limit?: number;
   offset?: number;
@@ -1270,6 +1363,18 @@ async function listIssueBlockerAttentionMap(
       explicitWaitingIssueIds.add(parsed.issueId);
       explicitWaitingIssueIds.add(parsed.leafIssueId);
     }
+
+    const recoveryActionRows: Array<{ sourceIssueId: string }> = await dbOrTx
+      .select({ sourceIssueId: issueRecoveryActions.sourceIssueId })
+      .from(issueRecoveryActions)
+      .where(
+        and(
+          eq(issueRecoveryActions.companyId, companyId),
+          inArray(issueRecoveryActions.status, ["active", "escalated"]),
+          inArray(issueRecoveryActions.sourceIssueId, explicitWaitCandidateIds),
+        ),
+      );
+    for (const row of recoveryActionRows) explicitWaitingIssueIds.add(row.sourceIssueId);
   }
 
   const agentRows: IssueBlockerAttentionAgentRow[] = agentIds.size > 0
@@ -1679,6 +1784,925 @@ async function blockedByMapForIssues(
   return map;
 }
 
+const BLOCKED_INBOX_TERMINAL_STATUSES = ["done", "cancelled"] as const;
+const BLOCKED_INBOX_ACTIVE_RUN_STATUSES = ["queued", "running"] as const;
+const BLOCKED_INBOX_ACTIVE_WAKE_STATUSES = ["queued", "deferred_issue_execution"] as const;
+const BLOCKED_INBOX_PENDING_INTERACTION_STATUSES = ["pending"] as const;
+const BLOCKED_INBOX_PENDING_APPROVAL_STATUSES = ["pending", "revision_requested"] as const;
+const BLOCKED_INBOX_RECOVERY_ORIGIN_KINDS = ["harness_liveness_escalation", "stranded_issue_recovery"] as const;
+const BLOCKED_INBOX_SUCCESSFUL_RUN_HANDOFF_ACTIONS = [
+  "issue.successful_run_handoff_required",
+  "issue.successful_run_handoff_resolved",
+  "issue.successful_run_handoff_escalated",
+] as const;
+
+type BlockedInboxIssueRow = IssueRow & { labels?: IssueLabelRow[]; labelIds?: string[] };
+type BlockedInboxInteractionRow = {
+  id: string;
+  issueId: string;
+  kind: string;
+  createdAt: Date;
+};
+type BlockedInboxApprovalRow = {
+  approvalId: string;
+  issueId: string;
+  createdAt: Date;
+};
+
+function issueRef(row: Pick<IssueRow, "id" | "identifier" | "title" | "status" | "priority" | "assigneeAgentId" | "assigneeUserId"> | null | undefined): IssueBlockedInboxIssueRef | null {
+  if (!row) return null;
+  return {
+    id: row.id,
+    identifier: row.identifier,
+    title: row.title,
+    status: row.status as IssueBlockedInboxIssueRef["status"],
+    priority: row.priority as IssueBlockedInboxIssueRef["priority"],
+    assigneeAgentId: row.assigneeAgentId,
+    assigneeUserId: row.assigneeUserId,
+  };
+}
+
+function isoDate(value: Date | string | null | undefined): string | null {
+  if (!value) return null;
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+function attentionBase(input: {
+  state: IssueBlockedInboxAttention["state"];
+  reason: IssueBlockedInboxAttention["reason"];
+  severity: IssueBlockedInboxAttention["severity"];
+  stoppedSinceAt: Date | string | null | undefined;
+  owner: IssueBlockedInboxAttention["owner"];
+  action: IssueBlockedInboxAttention["action"];
+  sourceIssue: IssueBlockedInboxIssueRef | null;
+  leafIssue?: IssueBlockedInboxIssueRef | null;
+  recoveryIssue?: IssueBlockedInboxIssueRef | null;
+  approvalId?: string | null;
+  interactionId?: string | null;
+  sampleIssueIdentifier?: string | null;
+  externalDetailsRedacted?: boolean;
+}): IssueBlockedInboxAttention {
+  return {
+    kind: "blocked",
+    state: input.state,
+    reason: input.reason,
+    severity: input.severity,
+    stoppedSinceAt: isoDate(input.stoppedSinceAt),
+    owner: input.owner,
+    action: input.action,
+    sourceIssue: input.sourceIssue,
+    leafIssue: input.leafIssue ?? null,
+    recoveryIssue: input.recoveryIssue ?? null,
+    approvalId: input.approvalId ?? null,
+    interactionId: input.interactionId ?? null,
+    sampleIssueIdentifier:
+      input.sampleIssueIdentifier
+      ?? input.leafIssue?.identifier
+      ?? input.recoveryIssue?.identifier
+      ?? input.sourceIssue?.identifier
+      ?? null,
+    redaction: {
+      externalDetailsRedacted: input.externalDetailsRedacted ?? false,
+      secretFieldsOmitted: true,
+    },
+  };
+}
+
+function readSuccessfulRunHandoffFromActivity(row: {
+  action: string;
+  agentId: string | null;
+  runId: string | null;
+  details: Record<string, unknown> | null;
+  createdAt: Date;
+}): SuccessfulRunHandoffState | null {
+  const details = row.details ?? {};
+  const state =
+    row.action === "issue.successful_run_handoff_required"
+      ? "required"
+      : row.action === "issue.successful_run_handoff_resolved"
+        ? "resolved"
+        : row.action === "issue.successful_run_handoff_escalated"
+          ? "escalated"
+          : null;
+  if (!state) return null;
+
+  const detectedProgressSummary =
+    readStringFromRecord(details, "detectedProgressSummary")
+    ?? readStringFromRecord(details, "detected_progress_summary")
+    ?? null;
+
+  return {
+    state,
+    required: state === "required",
+    sourceRunId:
+      readStringFromRecord(details, "sourceRunId")
+      ?? readStringFromRecord(details, "source_run_id")
+      ?? readStringFromRecord(details, "resumeFromRunId")
+      ?? row.runId
+      ?? null,
+    correctiveRunId:
+      readStringFromRecord(details, "correctiveRunId")
+      ?? readStringFromRecord(details, "corrective_run_id")
+      ?? (state !== "required" ? row.runId : null),
+    assigneeAgentId:
+      readStringFromRecord(details, "assigneeAgentId")
+      ?? readStringFromRecord(details, "agentId")
+      ?? row.agentId
+      ?? null,
+    detectedProgressSummary: detectedProgressSummary ? redactSensitiveText(detectedProgressSummary) : null,
+    createdAt: row.createdAt,
+  };
+}
+
+async function listSuccessfulRunHandoffMapForIssues(
+  dbOrTx: any,
+  companyId: string,
+  issueIds: string[],
+): Promise<Map<string, SuccessfulRunHandoffState>> {
+  const uniqueIssueIds = [...new Set(issueIds)];
+  const states = new Map<string, SuccessfulRunHandoffState>();
+  if (uniqueIssueIds.length === 0) return states;
+
+  for (const issueIdChunk of chunkList(uniqueIssueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+    const rows = await dbOrTx
+      .select({
+        entityId: activityLog.entityId,
+        action: activityLog.action,
+        agentId: activityLog.agentId,
+        runId: activityLog.runId,
+        details: activityLog.details,
+        createdAt: activityLog.createdAt,
+      })
+      .from(activityLog)
+      .where(and(
+        eq(activityLog.companyId, companyId),
+        eq(activityLog.entityType, "issue"),
+        inArray(activityLog.entityId, issueIdChunk),
+        inArray(activityLog.action, [...BLOCKED_INBOX_SUCCESSFUL_RUN_HANDOFF_ACTIONS]),
+      ))
+      .orderBy(activityLog.entityId, desc(activityLog.createdAt), desc(activityLog.id));
+
+    for (const row of rows as Array<{
+      entityId: string;
+      action: string;
+      agentId: string | null;
+      runId: string | null;
+      details: Record<string, unknown> | null;
+      createdAt: Date;
+    }>) {
+      if (states.has(row.entityId)) continue;
+      const state = readSuccessfulRunHandoffFromActivity(row);
+      if (state) states.set(row.entityId, state);
+    }
+  }
+
+  return states;
+}
+
+function externalWaitFromDescription(description: string | null): { owner: string; action: string } | null {
+  if (!description) return null;
+  const owner = description.match(/^\s*external owner\s*:\s*(.+)$/im)?.[1]?.trim();
+  const action = description.match(/^\s*external action\s*:\s*(.+)$/im)?.[1]?.trim();
+  if (!owner || !action) return null;
+  return {
+    owner: owner.slice(0, 120),
+    action: action.slice(0, 240),
+  };
+}
+
+function escapeRegExp(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function redactExternalWaitDescription(
+  description: string | null | undefined,
+  external: { owner: string; action: string } | null,
+) {
+  if (!description) return null;
+  let redacted = description
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*external\s+(?:owner|action)\s*:/i.test(line))
+    .join("\n");
+
+  for (const value of [external?.owner, external?.action]) {
+    if (!value) continue;
+    redacted = redacted.replace(new RegExp(escapeRegExp(value), "gi"), "[redacted external wait detail]");
+  }
+
+  redacted = redacted.replace(/\n{3,}/g, "\n\n").trim();
+  return redacted.length > 0 ? redacted : null;
+}
+
+function blockedInboxResponseDescription(attention: IssueBlockedInboxAttention, row: BlockedInboxIssueRow) {
+  if (!attention.redaction.externalDetailsRedacted) return row.description;
+  return redactExternalWaitDescription(row.description, externalWaitFromDescription(row.description));
+}
+
+function blockedInboxSearchText(attention: IssueBlockedInboxAttention, row: BlockedInboxIssueRow) {
+  return [
+    row.identifier,
+    row.title,
+    blockedInboxResponseDescription(attention, row),
+    attention.sourceIssue?.identifier,
+    attention.sourceIssue?.title,
+    attention.leafIssue?.identifier,
+    attention.leafIssue?.title,
+    attention.recoveryIssue?.identifier,
+    attention.recoveryIssue?.title,
+    attention.action.label,
+    attention.action.detail,
+  ]
+    .filter((value): value is string => typeof value === "string" && value.length > 0)
+    .join(" ")
+    .toLowerCase();
+}
+
+function blockedInboxSeverityRank(severity: IssueBlockedInboxAttention["severity"]) {
+  switch (severity) {
+    case "critical":
+      return 0;
+    case "high":
+      return 1;
+    case "medium":
+      return 2;
+    case "low":
+      return 3;
+  }
+}
+
+function issuePriorityRank(priority: string) {
+  switch (priority) {
+    case "critical":
+      return 0;
+    case "high":
+      return 1;
+    case "medium":
+      return 2;
+    case "low":
+      return 3;
+    default:
+      return 4;
+  }
+}
+
+function compareBlockedInboxRows(
+  left: BlockedInboxIssueRow & { blockedInboxAttention: IssueBlockedInboxAttention; lastActivityAt?: Date | null },
+  right: BlockedInboxIssueRow & { blockedInboxAttention: IssueBlockedInboxAttention; lastActivityAt?: Date | null },
+) {
+  const leftAttention = left.blockedInboxAttention;
+  const rightAttention = right.blockedInboxAttention;
+  const severity = blockedInboxSeverityRank(leftAttention.severity)
+    - blockedInboxSeverityRank(rightAttention.severity);
+  if (severity !== 0) return severity;
+
+  const leftStopped = leftAttention.stoppedSinceAt
+    ? new Date(leftAttention.stoppedSinceAt).getTime()
+    : Number.POSITIVE_INFINITY;
+  const rightStopped = rightAttention.stoppedSinceAt
+    ? new Date(rightAttention.stoppedSinceAt).getTime()
+    : Number.POSITIVE_INFINITY;
+  if (leftStopped !== rightStopped) return leftStopped - rightStopped;
+
+  const priority = issuePriorityRank(left.priority) - issuePriorityRank(right.priority);
+  if (priority !== 0) return priority;
+
+  const leftActivity = left.lastActivityAt ? new Date(left.lastActivityAt).getTime() : new Date(left.updatedAt).getTime();
+  const rightActivity = right.lastActivityAt ? new Date(right.lastActivityAt).getTime() : new Date(right.updatedAt).getTime();
+  if (leftActivity !== rightActivity) return rightActivity - leftActivity;
+
+  return right.id.localeCompare(left.id);
+}
+
+async function listIssueBlockedInboxAttentionMap(
+  dbOrTx: any,
+  companyId: string,
+  issueRows: BlockedInboxIssueRow[],
+): Promise<Map<string, IssueBlockedInboxAttention>> {
+  const rowIssueIds = [...new Set(issueRows.map((row) => row.id))];
+  const result = new Map<string, IssueBlockedInboxAttention>();
+  if (rowIssueIds.length === 0) return result;
+
+  const [graphIssueRows, graphRelationRows, companyAgentRows] = await Promise.all([
+    dbOrTx
+      .select()
+      .from(issues)
+      .where(and(
+        eq(issues.companyId, companyId),
+        isNull(issues.hiddenAt),
+        notInArray(issues.status, [...BLOCKED_INBOX_TERMINAL_STATUSES]),
+      )),
+    dbOrTx
+      .select({
+        companyId: issueRelations.companyId,
+        blockerIssueId: issueRelations.issueId,
+        blockedIssueId: issueRelations.relatedIssueId,
+      })
+      .from(issueRelations)
+      .where(and(eq(issueRelations.companyId, companyId), eq(issueRelations.type, "blocks"))),
+    dbOrTx
+      .select({
+        id: agents.id,
+        companyId: agents.companyId,
+        name: agents.name,
+        role: agents.role,
+        title: agents.title,
+        status: agents.status,
+        reportsTo: agents.reportsTo,
+      })
+      .from(agents)
+      .where(eq(agents.companyId, companyId)),
+  ]);
+
+  const graphIssues = graphIssueRows as IssueRow[];
+  const graphRelations = graphRelationRows as Array<{ companyId: string; blockerIssueId: string; blockedIssueId: string }>;
+  const companyAgents = companyAgentRows as Array<{
+    id: string;
+    companyId: string;
+    name: string;
+    role: string;
+    title: string | null;
+    status: string;
+    reportsTo: string | null;
+  }>;
+  const graphIssueIds = graphIssues.map((issue) => issue.id);
+  const issuesById = new Map<string, IssueRow>(graphIssues.map((issue) => [issue.id, issue]));
+
+  const [activeRunRows, wakeRows, scheduledRetryRows, interactionRows, approvalRows, handoffMap] = await Promise.all([
+    graphIssueIds.length === 0
+      ? Promise.resolve([])
+      : dbOrTx
+          .select({
+            companyId: heartbeatRuns.companyId,
+            issueId: sql<string | null>`${heartbeatRuns.contextSnapshot} ->> 'issueId'`,
+            agentId: heartbeatRuns.agentId,
+            status: heartbeatRuns.status,
+          })
+          .from(heartbeatRuns)
+          .where(and(
+            eq(heartbeatRuns.companyId, companyId),
+            inArray(heartbeatRuns.status, [...BLOCKED_INBOX_ACTIVE_RUN_STATUSES]),
+            inArray(sql<string>`${heartbeatRuns.contextSnapshot} ->> 'issueId'`, graphIssueIds),
+          )),
+    graphIssueIds.length === 0
+      ? Promise.resolve([])
+      : dbOrTx
+          .select({
+            companyId: agentWakeupRequests.companyId,
+            issueId: sql<string | null>`${agentWakeupRequests.payload} ->> 'issueId'`,
+            agentId: agentWakeupRequests.agentId,
+            status: agentWakeupRequests.status,
+          })
+          .from(agentWakeupRequests)
+          .where(and(
+            eq(agentWakeupRequests.companyId, companyId),
+            inArray(agentWakeupRequests.status, [...BLOCKED_INBOX_ACTIVE_WAKE_STATUSES]),
+            sql`${agentWakeupRequests.runId} is null`,
+            inArray(sql<string>`${agentWakeupRequests.payload} ->> 'issueId'`, graphIssueIds),
+          )),
+    graphIssueIds.length === 0
+      ? Promise.resolve([])
+      : dbOrTx
+          .select({
+            companyId: heartbeatRuns.companyId,
+            issueId: sql<string | null>`${heartbeatRuns.contextSnapshot} ->> 'issueId'`,
+            agentId: heartbeatRuns.agentId,
+            status: heartbeatRuns.status,
+          })
+          .from(heartbeatRuns)
+          .where(and(
+            eq(heartbeatRuns.companyId, companyId),
+            eq(heartbeatRuns.status, "scheduled_retry"),
+            inArray(sql<string>`${heartbeatRuns.contextSnapshot} ->> 'issueId'`, graphIssueIds),
+          )),
+    graphIssueIds.length === 0
+      ? Promise.resolve([])
+      : dbOrTx
+          .select({
+            id: issueThreadInteractions.id,
+            issueId: issueThreadInteractions.issueId,
+            kind: issueThreadInteractions.kind,
+            createdAt: issueThreadInteractions.createdAt,
+          })
+          .from(issueThreadInteractions)
+          .where(and(
+            eq(issueThreadInteractions.companyId, companyId),
+            inArray(issueThreadInteractions.status, [...BLOCKED_INBOX_PENDING_INTERACTION_STATUSES]),
+            inArray(issueThreadInteractions.issueId, graphIssueIds),
+          )),
+    graphIssueIds.length === 0
+      ? Promise.resolve([])
+      : dbOrTx
+          .select({
+            approvalId: approvals.id,
+            issueId: issueApprovals.issueId,
+            createdAt: approvals.createdAt,
+          })
+          .from(issueApprovals)
+          .innerJoin(approvals, eq(issueApprovals.approvalId, approvals.id))
+          .where(and(
+            eq(issueApprovals.companyId, companyId),
+            eq(approvals.companyId, companyId),
+            inArray(approvals.status, [...BLOCKED_INBOX_PENDING_APPROVAL_STATUSES]),
+            inArray(issueApprovals.issueId, graphIssueIds),
+          )),
+    listSuccessfulRunHandoffMapForIssues(dbOrTx, companyId, rowIssueIds),
+  ]);
+
+  const pendingInteractions = (interactionRows as BlockedInboxInteractionRow[]).map((row) => ({
+    companyId,
+    issueId: row.issueId,
+    status: "pending",
+  }));
+  const pendingApprovals = (approvalRows as BlockedInboxApprovalRow[]).map((row) => ({
+    companyId,
+    issueId: row.issueId,
+    status: "pending",
+  }));
+
+  const openRecoveryIssues = graphIssues
+    .filter((issue) => BLOCKED_INBOX_RECOVERY_ORIGIN_KINDS.includes(issue.originKind as typeof BLOCKED_INBOX_RECOVERY_ORIGIN_KINDS[number]))
+    .flatMap((issue) => {
+      const entries = [{ companyId, issueId: issue.id, status: issue.status }];
+      if (issue.originKind === "harness_liveness_escalation") {
+        const parsed = parseIssueGraphLivenessIncidentKey(issue.originId);
+        if (parsed?.companyId === companyId) {
+          entries.push({ companyId, issueId: parsed.issueId, status: issue.status });
+          entries.push({ companyId, issueId: parsed.leafIssueId, status: issue.status });
+        }
+      } else if (issue.originKind === "stranded_issue_recovery" && issue.originId) {
+        entries.push({ companyId, issueId: issue.originId, status: issue.status });
+      }
+      return entries;
+    });
+
+  const findings = classifyIssueGraphLiveness({
+    issues: graphIssues.map((issue) => ({
+      id: issue.id,
+      companyId: issue.companyId,
+      identifier: issue.identifier,
+      title: issue.title,
+      status: issue.status,
+      projectId: issue.projectId,
+      goalId: issue.goalId,
+      parentId: issue.parentId,
+      assigneeAgentId: issue.assigneeAgentId,
+      assigneeUserId: issue.assigneeUserId,
+      createdByAgentId: issue.createdByAgentId,
+      createdByUserId: issue.createdByUserId,
+      executionPolicy: issue.executionPolicy,
+      executionState: issue.executionState,
+      monitorNextCheckAt: issue.monitorNextCheckAt,
+      monitorAttemptCount: issue.monitorAttemptCount,
+    })),
+    relations: graphRelations,
+    agents: companyAgents,
+    activeRuns: (activeRunRows as Array<{ companyId: string; issueId: string | null; agentId: string | null; status: string }>)
+      .flatMap((row) => row.issueId
+        ? [{ companyId: row.companyId, issueId: row.issueId, agentId: row.agentId, status: row.status }]
+        : []),
+    queuedWakeRequests: [
+      ...(wakeRows as Array<{ companyId: string; issueId: string | null; agentId: string | null; status: string }>),
+      ...(scheduledRetryRows as Array<{ companyId: string; issueId: string | null; agentId: string | null; status: string }>),
+    ]
+      .flatMap((row) => row.issueId
+        ? [{ companyId: row.companyId, issueId: row.issueId, agentId: row.agentId, status: row.status }]
+        : []),
+    pendingInteractions,
+    pendingApprovals,
+    openRecoveryIssues,
+    now: new Date(),
+  });
+  const findingByIssueId = new Map<string, IssueLivenessFinding>();
+  for (const finding of findings) {
+    if (!findingByIssueId.has(finding.issueId)) findingByIssueId.set(finding.issueId, finding);
+  }
+
+  const interactionByIssueId = new Map<string, BlockedInboxInteractionRow>();
+  for (const row of interactionRows as BlockedInboxInteractionRow[]) {
+    if (!interactionByIssueId.has(row.issueId)) interactionByIssueId.set(row.issueId, row);
+  }
+  const approvalByIssueId = new Map<string, BlockedInboxApprovalRow>();
+  for (const row of approvalRows as BlockedInboxApprovalRow[]) {
+    if (!approvalByIssueId.has(row.issueId)) approvalByIssueId.set(row.issueId, row);
+  }
+
+  for (const row of issueRows) {
+    if (row.companyId !== companyId || BLOCKED_INBOX_TERMINAL_STATUSES.includes(row.status as typeof BLOCKED_INBOX_TERMINAL_STATUSES[number]) || row.hiddenAt) {
+      continue;
+    }
+    const source = issueRef(row);
+    const handoff = handoffMap.get(row.id);
+    if (handoff && (handoff.required || handoff.state === "escalated")) {
+      result.set(row.id, attentionBase({
+        state: "missing_disposition",
+        reason: "missing_successful_run_disposition",
+        severity: "high",
+        stoppedSinceAt: handoff.createdAt ?? row.updatedAt,
+        owner: {
+          type: row.assigneeAgentId ? "agent" : row.assigneeUserId ? "user" : "unknown",
+          agentId: row.assigneeAgentId,
+          userId: row.assigneeUserId,
+          label: null,
+        },
+        action: {
+          label: "Choose disposition",
+          detail: "Choose exactly one final disposition: done, cancelled, review/input, blocked with owner, delegated follow-up, or queued continuation.",
+        },
+        sourceIssue: source,
+      }));
+      continue;
+    }
+
+    if (BLOCKED_INBOX_RECOVERY_ORIGIN_KINDS.includes(row.originKind as typeof BLOCKED_INBOX_RECOVERY_ORIGIN_KINDS[number])) {
+      let sourceIssue: IssueBlockedInboxIssueRef | null = null;
+      let leafIssue: IssueBlockedInboxIssueRef | null = null;
+      if (row.originKind === "harness_liveness_escalation") {
+        const parsed = parseIssueGraphLivenessIncidentKey(row.originId);
+        if (parsed?.companyId === companyId) {
+          sourceIssue = issueRef(issuesById.get(parsed.issueId));
+          leafIssue = issueRef(issuesById.get(parsed.leafIssueId));
+        }
+      } else if (row.originKind === "stranded_issue_recovery" && row.originId) {
+        sourceIssue = issueRef(issuesById.get(row.originId));
+      }
+      result.set(row.id, attentionBase({
+        state: "recovery_open",
+        reason: "open_recovery_issue",
+        severity: "high",
+        stoppedSinceAt: row.createdAt,
+        owner: {
+          type: row.assigneeAgentId ? "agent" : row.assigneeUserId ? "user" : "unknown",
+          agentId: row.assigneeAgentId,
+          userId: row.assigneeUserId,
+          label: null,
+        },
+        action: {
+          label: "Resolve recovery",
+          detail: "Restore a live path for the source work or record why this recovery issue is a false positive.",
+        },
+        sourceIssue: sourceIssue ?? source,
+        leafIssue,
+        recoveryIssue: source,
+      }));
+      continue;
+    }
+
+    const interaction = interactionByIssueId.get(row.id);
+    if (interaction) {
+      const isUserQuestion = interaction.kind === "ask_user_questions" && Boolean(row.assigneeUserId);
+      result.set(row.id, attentionBase({
+        state: "awaiting_decision",
+        reason: isUserQuestion ? "pending_user_decision" : "pending_board_decision",
+        severity: "medium",
+        stoppedSinceAt: interaction.createdAt,
+        owner: isUserQuestion
+          ? { type: "user", agentId: null, userId: row.assigneeUserId, label: null }
+          : { type: "board", agentId: null, userId: null, label: "Board" },
+        action: {
+          label: isUserQuestion ? "Answer question" : "Answer confirmation",
+          detail: "Respond to the pending issue-thread interaction so the assignee has a live next action.",
+        },
+        sourceIssue: source,
+        interactionId: interaction.id,
+      }));
+      continue;
+    }
+
+    const approval = approvalByIssueId.get(row.id);
+    if (approval) {
+      result.set(row.id, attentionBase({
+        state: "awaiting_decision",
+        reason: "pending_board_decision",
+        severity: "medium",
+        stoppedSinceAt: approval.createdAt,
+        owner: { type: "board", agentId: null, userId: null, label: "Board" },
+        action: {
+          label: "Decide approval",
+          detail: "Approve, reject, or request revision on the linked approval.",
+        },
+        sourceIssue: source,
+        approvalId: approval.approvalId,
+      }));
+      continue;
+    }
+
+    const finding = findingByIssueId.get(row.id);
+    if (finding) {
+      const leaf = finding.dependencyPath.length > 1
+        ? issuesById.get(finding.dependencyPath[finding.dependencyPath.length - 1]!.issueId)
+        : issuesById.get(finding.recoveryIssueId);
+      const ownerAgentId = finding.state === "blocked_by_unassigned_issue"
+        ? null
+        : finding.recommendedOwnerAgentId ?? row.assigneeAgentId ?? leaf?.assigneeAgentId ?? null;
+      result.set(row.id, attentionBase({
+        state: "needs_attention",
+        reason: finding.state as IssueBlockedInboxAttention["reason"],
+        severity: finding.state === "blocked_by_assigned_backlog_issue"
+          || finding.state === "in_review_without_action_path"
+          ? "high"
+          : finding.severity === "critical" ? "critical" : "high",
+        stoppedSinceAt: leaf?.updatedAt ?? row.updatedAt,
+        owner: {
+          type: ownerAgentId ? "agent" : leaf?.assigneeUserId ? "user" : "unknown",
+          agentId: ownerAgentId,
+          userId: leaf?.assigneeUserId ?? null,
+          label: null,
+        },
+        action: {
+          label: (() => {
+            switch (finding.state) {
+              case "blocked_by_unassigned_issue":
+                return "Assign blocker";
+              case "blocked_by_assigned_backlog_issue":
+                return "Resume parked blocker";
+              case "blocked_by_uninvokable_assignee":
+                return "Assign active owner";
+              case "blocked_by_cancelled_issue":
+                return "Replace blocker";
+              case "invalid_review_participant":
+                return "Repair review participant";
+              case "in_review_without_action_path":
+                return "Choose review path";
+            }
+          })(),
+          detail: finding.recommendedAction,
+        },
+        sourceIssue: source,
+        leafIssue: issueRef(leaf),
+        recoveryIssue: issueRef(issuesById.get(finding.recoveryIssueId)),
+        sampleIssueIdentifier: leaf?.identifier ?? finding.identifier,
+      }));
+      continue;
+    }
+
+    const hasMonitor = Boolean(row.monitorNextCheckAt && row.monitorNextCheckAt.getTime() > Date.now());
+    const external = row.status === "blocked" && !hasMonitor ? externalWaitFromDescription(row.description) : null;
+    if (external) {
+      result.set(row.id, attentionBase({
+        state: "external_wait",
+        reason: "external_owner_action",
+        severity: "medium",
+        stoppedSinceAt: row.updatedAt,
+        owner: { type: "external", agentId: null, userId: null, label: null },
+        action: {
+          label: "External owner action",
+          detail: null,
+        },
+        sourceIssue: source,
+        externalDetailsRedacted: true,
+      }));
+      continue;
+    }
+
+    const blockerAttention = await listIssueBlockerAttentionMap(dbOrTx, companyId, [row]);
+    const blockerState = blockerAttention.get(row.id);
+    if (row.status === "blocked" && (blockerState?.state === "needs_attention" || blockerState?.state === "stalled")) {
+      result.set(row.id, attentionBase({
+        state: "needs_attention",
+        reason: "blocked_chain_stalled",
+        severity: "high",
+        stoppedSinceAt: row.updatedAt,
+        owner: { type: "unknown", agentId: null, userId: null, label: null },
+        action: {
+          label: "Inspect blocker chain",
+          detail: "Inspect the stalled blocker or review leaf and make the next owner/action explicit.",
+        },
+        sourceIssue: source,
+        sampleIssueIdentifier: blockerState.sampleStalledBlockerIdentifier ?? blockerState.sampleBlockerIdentifier,
+      }));
+    }
+  }
+
+  return result;
+}
+
+async function blockedInboxIssueConditions(
+  dbOrTx: any,
+  companyId: string,
+  filters?: IssueFilters,
+) {
+  const conditions = [
+    eq(issues.companyId, companyId),
+    isNull(issues.hiddenAt),
+    notInArray(issues.status, [...BLOCKED_INBOX_TERMINAL_STATUSES]),
+  ];
+  const touchedByUserId = filters?.touchedByUserId?.trim() || undefined;
+  const inboxArchivedByUserId = filters?.inboxArchivedByUserId?.trim() || undefined;
+  const unreadForUserId = filters?.unreadForUserId?.trim() || undefined;
+  const contextUserId = unreadForUserId ?? touchedByUserId ?? inboxArchivedByUserId;
+
+  if (filters?.descendantOf) {
+    conditions.push(sql<boolean>`
+      ${issues.id} IN (
+        WITH RECURSIVE descendants(id) AS (
+          SELECT ${issues.id}
+          FROM ${issues}
+          WHERE ${issues.companyId} = ${companyId}
+            AND ${issues.parentId} = ${filters.descendantOf}
+          UNION
+          SELECT ${issues.id}
+          FROM ${issues}
+          JOIN descendants ON ${issues.parentId} = descendants.id
+          WHERE ${issues.companyId} = ${companyId}
+        )
+        SELECT id FROM descendants
+      )
+    `);
+  }
+  if (filters?.status) {
+    const statuses = filters.status.split(",").map((status) => status.trim()).filter(Boolean);
+    if (statuses.length > 0) {
+      conditions.push(statuses.length === 1 ? eq(issues.status, statuses[0]!) : inArray(issues.status, statuses));
+    }
+  }
+  if (filters?.assigneeAgentId) conditions.push(eq(issues.assigneeAgentId, filters.assigneeAgentId));
+  if (filters?.participantAgentId) conditions.push(participatedByAgentCondition(companyId, filters.participantAgentId));
+  if (filters?.assigneeUserId) conditions.push(eq(issues.assigneeUserId, filters.assigneeUserId));
+  if (touchedByUserId) conditions.push(touchedByUserCondition(companyId, touchedByUserId));
+  if (inboxArchivedByUserId) conditions.push(inboxVisibleForUserCondition(companyId, inboxArchivedByUserId));
+  if (unreadForUserId) conditions.push(unreadForUserCondition(companyId, unreadForUserId));
+  if (filters?.projectId) conditions.push(eq(issues.projectId, filters.projectId));
+  if (filters?.workspaceId) {
+    conditions.push(or(
+      eq(issues.executionWorkspaceId, filters.workspaceId),
+      eq(issues.projectWorkspaceId, filters.workspaceId),
+    )!);
+  }
+  if (filters?.executionWorkspaceId) conditions.push(eq(issues.executionWorkspaceId, filters.executionWorkspaceId));
+  if (filters?.parentId) conditions.push(eq(issues.parentId, filters.parentId));
+  if (filters?.originKind) conditions.push(eq(issues.originKind, filters.originKind));
+  if (filters?.originKindPrefix) conditions.push(like(issues.originKind, `${filters.originKindPrefix}%`));
+  if (filters?.originId) conditions.push(eq(issues.originId, filters.originId));
+  if (!shouldIncludePluginOperationIssues(filters)) conditions.push(nonPluginOperationIssueCondition());
+  if (filters?.labelId) {
+    const labeledIssueIds = await dbOrTx
+      .select({ issueId: issueLabels.issueId })
+      .from(issueLabels)
+      .where(and(eq(issueLabels.companyId, companyId), eq(issueLabels.labelId, filters.labelId)));
+    if (labeledIssueIds.length === 0) return { conditions: [sql<boolean>`false`], contextUserId };
+    conditions.push(inArray(issues.id, labeledIssueIds.map((row: { issueId: string }) => row.issueId)));
+  }
+  if (filters?.excludeRoutineExecutions && !filters?.originKind && !filters?.originId) {
+    conditions.push(ne(issues.originKind, "routine_execution"));
+  }
+
+  return { conditions, contextUserId };
+}
+
+async function listBlockedInboxIssues(
+  dbOrTx: any,
+  companyId: string,
+  filters?: IssueFilters,
+): Promise<Array<IssueWithLabelsAndRun & {
+  blockedBy?: IssueRelationIssueSummary[];
+  blockerAttention?: IssueBlockerAttention;
+  blockedInboxAttention: IssueBlockedInboxAttention;
+  productivityReview?: IssueProductivityReview | null;
+  lastActivityAt: Date;
+  myLastTouchAt?: Date | null;
+  lastExternalCommentAt?: Date | null;
+  isUnreadForMe?: boolean;
+}>> {
+  const { conditions, contextUserId } = await blockedInboxIssueConditions(dbOrTx, companyId, filters);
+
+  const rows = (await dbOrTx
+    .select(issueListSelect)
+    .from(issues)
+    .where(and(...conditions))
+    .orderBy(desc(issueCanonicalLastActivityAtExpr(companyId)), desc(issues.updatedAt), desc(issues.id)))
+    .map((row: any) => ({
+      ...row,
+      description: decodeDatabaseTextPreview(row.description, ISSUE_LIST_DESCRIPTION_MAX_CHARS),
+    }));
+  const withLabels = await withIssueLabels(dbOrTx, rows);
+  const withRuns = withActiveRuns(withLabels, await activeRunMapForIssues(dbOrTx, withLabels));
+  if (withRuns.length === 0) return [];
+
+  const issueIds = withRuns.map((row) => row.id);
+  const [
+    statsRows,
+    readRows,
+    lastActivityRows,
+    blockedByMap,
+    blockerAttentionByIssueId,
+    productivityReviewByIssueId,
+    blockedInboxAttentionByIssueId,
+  ] = await Promise.all([
+    contextUserId ? userCommentStatsForIssues(dbOrTx, companyId, contextUserId, issueIds) : Promise.resolve([]),
+    contextUserId ? userReadStatsForIssues(dbOrTx, companyId, contextUserId, issueIds) : Promise.resolve([]),
+    lastActivityStatsForIssues(dbOrTx, companyId, issueIds),
+    blockedByMapForIssues(dbOrTx, companyId, issueIds),
+    listIssueBlockerAttentionMap(dbOrTx, companyId, withRuns),
+    listIssueProductivityReviewMap(dbOrTx, companyId, issueIds),
+    listIssueBlockedInboxAttentionMap(dbOrTx, companyId, withRuns),
+  ]);
+
+  const rawSearchInput = filters?.q?.trim() ?? "";
+  const rawSearch = rawSearchInput.toLowerCase();
+  const commentSearchMatchIssueIds = new Set<string>();
+  if (rawSearchInput) {
+    const containsPattern = `%${escapeLikePattern(rawSearchInput)}%`;
+    for (const issueIdChunk of chunkList(issueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+      const rows = await dbOrTx
+        .select({ issueId: issueComments.issueId })
+        .from(issueComments)
+        .where(and(
+          eq(issueComments.companyId, companyId),
+          inArray(issueComments.issueId, issueIdChunk),
+          sql<boolean>`${issueComments.body} ILIKE ${containsPattern} ESCAPE '\\'`,
+        ));
+      for (const row of rows as Array<{ issueId: string }>) commentSearchMatchIssueIds.add(row.issueId);
+    }
+  }
+  const statsByIssueId = new Map(statsRows.map((row) => [row.issueId, row]));
+  const readByIssueId = new Map(readRows.map((row) => [row.issueId, row.myLastReadAt]));
+  const lastActivityByIssueId = new Map(lastActivityRows.map((row) => [row.issueId, row]));
+
+  const enriched = withRuns.flatMap((row) => {
+    const blockedInboxAttention = blockedInboxAttentionByIssueId.get(row.id);
+    if (!blockedInboxAttention) return [];
+    if (
+      rawSearch
+      && !blockedInboxSearchText(blockedInboxAttention, row).includes(rawSearch)
+      && !commentSearchMatchIssueIds.has(row.id)
+    ) return [];
+
+    const activity = lastActivityByIssueId.get(row.id);
+    const lastActivityAt = latestIssueActivityAt(
+      row.updatedAt,
+      activity?.latestCommentAt ?? null,
+      activity?.latestLogAt ?? null,
+    ) ?? row.updatedAt;
+    return [{
+      ...row,
+      description: blockedInboxResponseDescription(blockedInboxAttention, row),
+      blockedBy: blockedByMap.get(row.id) ?? [],
+      lastActivityAt,
+      ...(blockerAttentionByIssueId.has(row.id) ? { blockerAttention: blockerAttentionByIssueId.get(row.id) } : {}),
+      blockedInboxAttention,
+      ...(productivityReviewByIssueId.has(row.id)
+        ? { productivityReview: productivityReviewByIssueId.get(row.id) }
+        : {}),
+      ...(contextUserId
+        ? deriveIssueUserContext(row, contextUserId, {
+            myLastCommentAt: statsByIssueId.get(row.id)?.myLastCommentAt ?? null,
+            myLastReadAt: readByIssueId.get(row.id) ?? null,
+            lastExternalCommentAt: statsByIssueId.get(row.id)?.lastExternalCommentAt ?? null,
+          })
+        : {}),
+    }];
+  }).sort(compareBlockedInboxRows);
+
+  const offset = typeof filters?.offset === "number" && Number.isFinite(filters.offset)
+    ? Math.max(0, Math.floor(filters.offset))
+    : 0;
+  const limit = typeof filters?.limit === "number" && Number.isFinite(filters.limit)
+    ? Math.max(1, Math.floor(filters.limit))
+    : undefined;
+  return limit === undefined ? enriched.slice(offset) : enriched.slice(offset, offset + limit);
+}
+
+async function countBlockedInboxIssues(dbOrTx: any, companyId: string, filters?: IssueFilters): Promise<number> {
+  const { conditions } = await blockedInboxIssueConditions(dbOrTx, companyId, filters);
+  const rows = (await dbOrTx
+    .select()
+    .from(issues)
+    .where(and(...conditions))) as IssueRow[];
+  if (rows.length === 0) return 0;
+
+  const blockedInboxAttentionByIssueId = await listIssueBlockedInboxAttentionMap(dbOrTx, companyId, rows);
+  const rawSearchInput = filters?.q?.trim() ?? "";
+  const rawSearch = rawSearchInput.toLowerCase();
+  const commentSearchMatchIssueIds = new Set<string>();
+  if (rawSearchInput) {
+    const issueIds = rows.map((row) => row.id);
+    const containsPattern = `%${escapeLikePattern(rawSearchInput)}%`;
+    for (const issueIdChunk of chunkList(issueIds, ISSUE_LIST_RELATED_QUERY_CHUNK_SIZE)) {
+      const commentRows = await dbOrTx
+        .select({ issueId: issueComments.issueId })
+        .from(issueComments)
+        .where(and(
+          eq(issueComments.companyId, companyId),
+          inArray(issueComments.issueId, issueIdChunk),
+          sql<boolean>`${issueComments.body} ILIKE ${containsPattern} ESCAPE '\\'`,
+        ));
+      for (const row of commentRows as Array<{ issueId: string }>) commentSearchMatchIssueIds.add(row.issueId);
+    }
+  }
+
+  return rows.reduce((count: number, row: IssueRow) => {
+    const attention = blockedInboxAttentionByIssueId.get(row.id);
+    if (!attention) return count;
+    if (
+      rawSearch
+      && !blockedInboxSearchText(attention, row).includes(rawSearch)
+      && !commentSearchMatchIssueIds.has(row.id)
+    ) return count;
+    return count + 1;
+  }, 0);
+}
+
 export function issueService(db: Db) {
   const instanceSettings = instanceSettingsService(db);
   const treeControlSvc = issueTreeControlService(db);
@@ -1779,6 +2803,129 @@ export function issueService(db: Db) {
     };
   }
 
+  async function readRunLogText(run: {
+    logStore: string | null;
+    logRef: string | null;
+    logBytes: number | null;
+  }) {
+    if (run.logStore !== "local_file" || !run.logRef) return "";
+    const logBytes = Number(run.logBytes ?? 0);
+    if (!Number.isFinite(logBytes) || logBytes <= 0) return "";
+
+    const store = getRunLogStore();
+    let offset = 0;
+    let content = "";
+    let nextOffset: number | undefined = 0;
+
+    while (nextOffset !== undefined) {
+      const remainingBytes = ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_LOG_BYTES - Buffer.byteLength(content, "utf8");
+      if (remainingBytes <= 0) break;
+      const chunk = await store.read(
+        { store: "local_file", logRef: run.logRef },
+        {
+          offset,
+          limitBytes: Math.min(ISSUE_COMMENT_RUN_LOG_DERIVATION_CHUNK_BYTES, remainingBytes),
+        },
+      );
+      content += chunk.content;
+      nextOffset = chunk.nextOffset;
+      offset = chunk.nextOffset ?? 0;
+    }
+
+    return content;
+  }
+
+  async function enrichCommentsWithDerivedAgentAttribution<
+    T extends {
+      id: string;
+      companyId: string;
+      issueId: string;
+      authorAgentId?: string | null;
+      authorUserId?: string | null;
+      createdByRunId?: string | null;
+      createdAt: Date | string;
+    },
+  >(comments: readonly T[]) {
+    const candidates = comments.filter((comment) =>
+      !comment.authorAgentId
+      && !!comment.authorUserId
+      && !comment.createdByRunId,
+    );
+    if (candidates.length === 0) return comments;
+
+    const companyId = comments[0]?.companyId ?? null;
+    const issueId = comments[0]?.issueId ?? null;
+    if (!companyId || !issueId) return comments;
+
+    const minCommentCreatedAtMs = candidates.reduce<number | null>((min, comment) => {
+      const timestamp = toTimestampMs(comment.createdAt);
+      if (timestamp === null) return min;
+      return min === null ? timestamp : Math.min(min, timestamp);
+    }, null);
+    const maxCommentCreatedAtMs = candidates.reduce<number | null>((max, comment) => {
+      const timestamp = toTimestampMs(comment.createdAt);
+      if (timestamp === null) return max;
+      return max === null ? timestamp : Math.max(max, timestamp);
+    }, null);
+    if (minCommentCreatedAtMs === null || maxCommentCreatedAtMs === null) return comments;
+
+    const minCommentCreatedAt = new Date(minCommentCreatedAtMs).toISOString();
+    const maxCommentCreatedAt = new Date(
+      maxCommentCreatedAtMs + ISSUE_COMMENT_RUN_LOG_DERIVATION_END_SLACK_MS,
+    ).toISOString();
+
+    const runs = await db
+      .select({
+        runId: heartbeatRuns.id,
+        agentId: heartbeatRuns.agentId,
+        createdAt: heartbeatRuns.createdAt,
+        startedAt: heartbeatRuns.startedAt,
+        finishedAt: heartbeatRuns.finishedAt,
+        logStore: heartbeatRuns.logStore,
+        logRef: heartbeatRuns.logRef,
+        logBytes: heartbeatRuns.logBytes,
+      })
+      .from(heartbeatRuns)
+      .where(
+        and(
+          eq(heartbeatRuns.companyId, companyId),
+          or(
+            sql`${heartbeatRuns.contextSnapshot} ->> 'issueId' = ${issueId}`,
+            sql`exists (
+              select 1
+              from ${activityLog}
+              where ${activityLog.companyId} = ${companyId}
+                and ${activityLog.entityType} = 'issue'
+                and ${activityLog.entityId} = ${issueId}
+                and ${activityLog.runId} = ${heartbeatRuns.id}
+            )`,
+          ),
+          sql`coalesce(${heartbeatRuns.finishedAt}, ${heartbeatRuns.createdAt}) >= ${minCommentCreatedAt}::timestamptz`,
+          sql`coalesce(${heartbeatRuns.startedAt}, ${heartbeatRuns.createdAt}) <= ${maxCommentCreatedAt}::timestamptz`,
+        ),
+      )
+      .orderBy(desc(heartbeatRuns.createdAt));
+
+    if (runs.length === 0) return comments;
+
+    const runsWithLogs: Array<(typeof runs)[number] & { logContent: string }> = [];
+    for (let index = 0; index < runs.length; index += ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_PARALLEL_READS) {
+      const batch = runs.slice(index, index + ISSUE_COMMENT_RUN_LOG_DERIVATION_MAX_PARALLEL_READS);
+      const batchWithLogs = await Promise.all(batch.map(async (run) => ({
+        ...run,
+        logContent: await readRunLogText(run),
+      })));
+      runsWithLogs.push(...batchWithLogs);
+    }
+    const derivedByCommentId = deriveIssueCommentRunLogAttribution(candidates, runsWithLogs);
+    if (derivedByCommentId.size === 0) return comments;
+
+    return comments.map((comment) => {
+      const derived = derivedByCommentId.get(comment.id);
+      return derived ? { ...comment, ...derived } : comment;
+    });
+  }
+
   async function assertAssignableAgent(companyId: string, agentId: string) {
     const assignee = await db
       .select({
@@ -2226,6 +3373,14 @@ export function issueService(db: Db) {
     clearExecutionRunIfTerminal,
 
     list: async (companyId: string, filters?: IssueFilters) => {
+      if (filters?.attention === "blocked") {
+        return listBlockedInboxIssues(db, companyId, {
+          ...filters,
+          includeBlockedBy: true,
+          includeBlockedInboxAttention: true,
+        });
+      }
+
       const conditions = [eq(issues.companyId, companyId)];
       const limit = typeof filters?.limit === "number" && Number.isFinite(filters.limit)
         ? Math.max(1, Math.floor(filters.limit))
@@ -2238,6 +3393,7 @@ export function issueService(db: Db) {
       const unreadForUserId = filters?.unreadForUserId?.trim() || undefined;
       const contextUserId = unreadForUserId ?? touchedByUserId ?? inboxArchivedByUserId;
       const includeBlockedBy = filters?.includeBlockedBy === true;
+      const includeBlockedInboxAttention = filters?.includeBlockedInboxAttention === true;
       const rawSearch = filters?.q?.trim() ?? "";
       const hasSearch = rawSearch.length > 0;
       const escapedSearch = hasSearch ? escapeLikePattern(rawSearch) : "";
@@ -2390,9 +3546,16 @@ export function issueService(db: Db) {
       ]);
       const statsByIssueId = new Map(statsRows.map((row) => [row.issueId, row]));
       const lastActivityByIssueId = new Map(lastActivityRows.map((row) => [row.issueId, row]));
-      const [blockerAttentionByIssueId, productivityReviewByIssueId] = await Promise.all([
+      const [
+        blockerAttentionByIssueId,
+        productivityReviewByIssueId,
+        blockedInboxAttentionByIssueId,
+      ] = await Promise.all([
         listIssueBlockerAttentionMap(db, companyId, withRuns),
         listIssueProductivityReviewMap(db, companyId, issueIds),
+        includeBlockedInboxAttention
+          ? listIssueBlockedInboxAttentionMap(db, companyId, withRuns)
+          : Promise.resolve(new Map<string, IssueBlockedInboxAttention>()),
       ]);
 
       if (!contextUserId) {
@@ -2408,6 +3571,7 @@ export function issueService(db: Db) {
             ...(includeBlockedBy ? { blockedBy: blockedByMap.get(row.id) ?? [] } : {}),
             lastActivityAt,
             ...(blockerAttentionByIssueId.has(row.id) ? { blockerAttention: blockerAttentionByIssueId.get(row.id) } : {}),
+            ...(includeBlockedInboxAttention ? { blockedInboxAttention: blockedInboxAttentionByIssueId.get(row.id) ?? null } : {}),
             ...(productivityReviewByIssueId.has(row.id)
               ? { productivityReview: productivityReviewByIssueId.get(row.id) }
               : {}),
@@ -2429,6 +3593,7 @@ export function issueService(db: Db) {
           ...(includeBlockedBy ? { blockedBy: blockedByMap.get(row.id) ?? [] } : {}),
           lastActivityAt,
           ...(blockerAttentionByIssueId.has(row.id) ? { blockerAttention: blockerAttentionByIssueId.get(row.id) } : {}),
+          ...(includeBlockedInboxAttention ? { blockedInboxAttention: blockedInboxAttentionByIssueId.get(row.id) ?? null } : {}),
           ...(productivityReviewByIssueId.has(row.id)
             ? { productivityReview: productivityReviewByIssueId.get(row.id) }
             : {}),
@@ -2441,6 +3606,39 @@ export function issueService(db: Db) {
       });
     },
 
+    count: async (companyId: string, filters?: IssueFilters) => {
+      if (filters?.attention === "blocked") {
+        return countBlockedInboxIssues(db, companyId, filters);
+      }
+
+      const conditions = [eq(issues.companyId, companyId), isNull(issues.hiddenAt)];
+      if (filters?.status) {
+        const statuses = filters.status.split(",").map((status) => status.trim()).filter(Boolean);
+        if (statuses.length === 1) conditions.push(eq(issues.status, statuses[0]!));
+        else if (statuses.length > 1) conditions.push(inArray(issues.status, statuses));
+      }
+      if (filters?.assigneeAgentId) conditions.push(eq(issues.assigneeAgentId, filters.assigneeAgentId));
+      if (filters?.assigneeUserId) conditions.push(eq(issues.assigneeUserId, filters.assigneeUserId));
+      if (filters?.projectId) conditions.push(eq(issues.projectId, filters.projectId));
+      if (filters?.workspaceId) {
+        conditions.push(or(
+          eq(issues.executionWorkspaceId, filters.workspaceId),
+          eq(issues.projectWorkspaceId, filters.workspaceId),
+        )!);
+      }
+      if (filters?.executionWorkspaceId) conditions.push(eq(issues.executionWorkspaceId, filters.executionWorkspaceId));
+      if (filters?.parentId) conditions.push(eq(issues.parentId, filters.parentId));
+      if (filters?.originKind) conditions.push(eq(issues.originKind, filters.originKind));
+      if (filters?.originKindPrefix) conditions.push(like(issues.originKind, `${filters.originKindPrefix}%`));
+      if (filters?.originId) conditions.push(eq(issues.originId, filters.originId));
+      if (!shouldIncludePluginOperationIssues(filters)) conditions.push(nonPluginOperationIssueCondition());
+      const [row] = await db
+        .select({ count: sql<number>`count(*)` })
+        .from(issues)
+        .where(and(...conditions));
+      return Number(row?.count ?? 0);
+    },
+
     countUnreadTouchedByUser: async (companyId: string, userId: string, status?: string) => {
       const conditions = [
         eq(issues.companyId, companyId),
@@ -3778,7 +4976,8 @@ export function issueService(db: Db) {
 
       const comments = limit ? await query.limit(limit) : await query;
       const { censorUsernameInLogs } = await instanceSettings.getGeneral();
-      return comments.map((comment) => redactIssueComment(comment, censorUsernameInLogs));
+      const enrichedComments = await enrichCommentsWithDerivedAgentAttribution(comments);
+      return enrichedComments.map((comment) => redactIssueComment(comment, censorUsernameInLogs));
     },
 
     getCommentCursor: async (issueId: string) => {
@@ -3809,16 +5008,17 @@ export function issueService(db: Db) {
       };
     },
 
-    getComment: (commentId: string) =>
-      instanceSettings.getGeneral().then(({ censorUsernameInLogs }) =>
-        db
+    getComment: async (commentId: string) => {
+      const { censorUsernameInLogs } = await instanceSettings.getGeneral();
+      const comment = await db
         .select()
         .from(issueComments)
         .where(eq(issueComments.id, commentId))
-        .then((rows) => {
-          const comment = rows[0] ?? null;
-          return comment ? redactIssueComment(comment, censorUsernameInLogs) : null;
-        })),
+        .then((rows) => rows[0] ?? null);
+      if (!comment) return null;
+      const [enrichedComment] = await enrichCommentsWithDerivedAgentAttribution([comment]);
+      return redactIssueComment(enrichedComment ?? comment, censorUsernameInLogs);
+    },
 
     removeComment: async (commentId: string) => {
       const currentUserRedactionOptions = {
diff --git a/server/src/services/plugin-dev-watcher.ts b/server/src/services/plugin-dev-watcher.ts
index 76b258c4..ceba5d4e 100644
--- a/server/src/services/plugin-dev-watcher.ts
+++ b/server/src/services/plugin-dev-watcher.ts
@@ -164,6 +164,10 @@ export function createPluginDevWatcher(
   const watchers = new Map<string, FSWatcher>();
   const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
   const fileExists = fsDeps?.existsSync ?? existsSync;
+  log.info(
+    { resolvesInstalledPlugins: Boolean(resolvePluginPackagePath) },
+    "plugin-dev-watcher: initialized",
+  );
 
   function watchPlugin(pluginId: string, packagePath: string): void {
     // Don't double-watch
@@ -293,11 +297,23 @@ export function createPluginDevWatcher(
   }
 
   async function watchLocalPluginById(pluginId: string): Promise<void> {
-    if (!resolvePluginPackagePath) return;
+    if (!resolvePluginPackagePath) {
+      log.debug(
+        { pluginId },
+        "plugin-dev-watcher: no package path resolver configured, skipping lifecycle event",
+      );
+      return;
+    }
 
     try {
       const packagePath = await resolvePluginPackagePath(pluginId);
-      if (!packagePath) return;
+      if (!packagePath) {
+        log.debug(
+          { pluginId },
+          "plugin-dev-watcher: plugin is not a local-path install, skipping watch",
+        );
+        return;
+      }
       watchPlugin(pluginId, packagePath);
     } catch (err) {
       log.warn(
diff --git a/server/src/services/plugin-loader.ts b/server/src/services/plugin-loader.ts
index 073620b4..94b0a9f3 100644
--- a/server/src/services/plugin-loader.ts
+++ b/server/src/services/plugin-loader.ts
@@ -79,6 +79,37 @@ export const DEFAULT_LOCAL_PLUGIN_DIR = path.join(
 
 const DEV_TSX_LOADER_PATH = path.resolve(__dirname, "../../../cli/node_modules/tsx/dist/loader.mjs");
 
+const ADAPTER_ENV_PASSTHROUGH = [
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "GOOGLE_API_KEY",
+  "GEMINI_API_KEY",
+  "OPENROUTER_API_KEY",
+];
+
+export function buildPluginWorkerEnv(input: {
+  manifest: Pick<PaperclipPluginManifestV1, "capabilities">;
+  instanceInfo: { deploymentMode?: string | null; deploymentExposure?: string | null };
+  processEnv?: NodeJS.ProcessEnv;
+}): Record<string, string> {
+  const processEnv = input.processEnv ?? process.env;
+  const env: Record<string, string> = {
+    PAPERCLIP_DEPLOYMENT_MODE: input.instanceInfo.deploymentMode ?? "",
+    PAPERCLIP_DEPLOYMENT_EXPOSURE: input.instanceInfo.deploymentExposure ?? "",
+  };
+  const canRegisterEnvironmentDrivers = Array.isArray(input.manifest.capabilities)
+    && input.manifest.capabilities.includes("environment.drivers.register");
+  if (!canRegisterEnvironmentDrivers) return env;
+
+  for (const key of ADAPTER_ENV_PASSTHROUGH) {
+    const value = processEnv[key];
+    if (value && value.trim().length > 0) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
 // ---------------------------------------------------------------------------
 // Discovery result types
 // ---------------------------------------------------------------------------
@@ -1820,10 +1851,7 @@ export function pluginLoader(
         databaseNamespace,
         hostHandlers,
         autoRestart: true,
-        env: {
-          PAPERCLIP_DEPLOYMENT_MODE: instanceInfo.deploymentMode ?? "",
-          PAPERCLIP_DEPLOYMENT_EXPOSURE: instanceInfo.deploymentExposure ?? "",
-        },
+        env: buildPluginWorkerEnv({ manifest, instanceInfo }),
       };
 
       // Repo-local plugin installs can resolve workspace TS sources at runtime
diff --git a/server/src/services/recovery/service.ts b/server/src/services/recovery/service.ts
index d69e57dc..f94d5b52 100644
--- a/server/src/services/recovery/service.ts
+++ b/server/src/services/recovery/service.ts
@@ -12,10 +12,12 @@ import {
   agentWakeupRequests,
   approvals,
   companies,
+  issueComments,
   heartbeatRunEvents,
   heartbeatRunWatchdogDecisions,
   heartbeatRuns,
   issueApprovals,
+  issueRecoveryActions,
   issueRelations,
   issueThreadInteractions,
   issues,
@@ -29,6 +31,7 @@ import { redactSensitiveText } from "../../redaction.js";
 import { logActivity } from "../activity-log.js";
 import { budgetService } from "../budgets.js";
 import { instanceSettingsService } from "../instance-settings.js";
+import { issueRecoveryActionService } from "../issue-recovery-actions.js";
 import { issueTreeControlService } from "../issue-tree-control.js";
 import { issueService } from "../issues.js";
 import { getRunLogStore } from "../run-log-store.js";
@@ -37,6 +40,7 @@ import {
   FINISH_SUCCESSFUL_RUN_HANDOFF_REASON,
   SUCCESSFUL_RUN_MISSING_STATE_REASON,
   buildSuccessfulRunHandoffExhaustedNotice,
+  noticeMetadataReferencesRecoveryAction,
   type SuccessfulRunHandoffNotice,
 } from "./successful-run-handoff.js";
 import {
@@ -386,6 +390,7 @@ function buildLivenessOriginalIssueComment(finding: IssueLivenessFinding, escala
 
 export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup }) {
   const issuesSvc = issueService(db);
+  const recoveryActionsSvc = issueRecoveryActionService(db);
   const treeControlSvc = issueTreeControlService(db);
   const budgets = budgetService(db);
   const instanceSettings = instanceSettingsService(db);
@@ -1566,6 +1571,136 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
     return recovery;
   }
 
+  function strandedRecoveryActionKind(cause: StrandedRecoveryCause) {
+    return cause === SUCCESSFUL_RUN_MISSING_STATE_REASON
+      ? "missing_disposition" as const
+      : "stranded_assigned_issue" as const;
+  }
+
+  function strandedRecoveryActionFingerprint(input: {
+    issue: typeof issues.$inferSelect;
+    recoveryCause: StrandedRecoveryCause;
+  }) {
+    return [
+      "source_scoped_recovery",
+      input.issue.companyId,
+      input.issue.id,
+      input.recoveryCause,
+    ].join(":");
+  }
+
+  function buildStrandedRecoveryActionEvidence(input: {
+    issue: typeof issues.$inferSelect;
+    latestRun: LatestIssueRun;
+    previousStatus: "todo" | "in_progress";
+    recoveryCause: StrandedRecoveryCause;
+    successfulRunHandoffEvidence?: SuccessfulRunHandoffRecoveryEvidence | null;
+  }) {
+    const context = parseObject(input.latestRun?.contextSnapshot);
+    return {
+      sourceIssueId: input.issue.id,
+      sourceIdentifier: input.issue.identifier,
+      previousStatus: input.previousStatus,
+      latestIssueStatus: input.issue.status,
+      latestRunId: input.latestRun?.id ?? null,
+      latestRunStatus: input.latestRun?.status ?? null,
+      latestRunErrorCode: input.latestRun?.errorCode ?? null,
+      retryReason: readNonEmptyString(context.retryReason) ?? null,
+      recoveryCause: input.recoveryCause,
+      sourceRunId: input.successfulRunHandoffEvidence?.sourceRunId ?? null,
+      correctiveRunId: input.successfulRunHandoffEvidence?.correctiveRunId ?? null,
+      missingDisposition: input.successfulRunHandoffEvidence?.missingDisposition ?? null,
+      handoffAttempt: input.successfulRunHandoffEvidence?.handoffAttempt ?? null,
+      maxHandoffAttempts: input.successfulRunHandoffEvidence?.maxHandoffAttempts ?? null,
+    };
+  }
+
+  async function ensureSourceScopedStrandedRecoveryAction(input: {
+    issue: typeof issues.$inferSelect;
+    latestRun: LatestIssueRun;
+    previousStatus: "todo" | "in_progress";
+    recoveryCause?: StrandedRecoveryCause;
+    successfulRunHandoffEvidence?: SuccessfulRunHandoffRecoveryEvidence | null;
+  }) {
+    const recoveryCause = input.recoveryCause ?? "stranded_assigned_issue";
+    const ownerAgentId = await resolveStrandedIssueRecoveryOwnerAgentId(input.issue);
+    const now = new Date();
+    const action = await recoveryActionsSvc.upsertSourceScoped({
+      companyId: input.issue.companyId,
+      sourceIssueId: input.issue.id,
+      kind: strandedRecoveryActionKind(recoveryCause),
+      ownerType: ownerAgentId ? "agent" : "board",
+      ownerAgentId,
+      previousOwnerAgentId: input.issue.assigneeAgentId,
+      returnOwnerAgentId: input.issue.assigneeAgentId,
+      cause: recoveryCause,
+      fingerprint: strandedRecoveryActionFingerprint({
+        issue: input.issue,
+        recoveryCause,
+      }),
+      evidence: buildStrandedRecoveryActionEvidence({
+        issue: input.issue,
+        latestRun: input.latestRun,
+        previousStatus: input.previousStatus,
+        recoveryCause,
+        successfulRunHandoffEvidence: input.successfulRunHandoffEvidence,
+      }),
+      nextAction: recoveryCause === SUCCESSFUL_RUN_MISSING_STATE_REASON
+        ? "Choose and record a valid issue disposition without copying transcript content."
+        : "Restore a live execution path, fix the runtime/adapter failure, or record an intentional manual resolution.",
+      wakePolicy: ownerAgentId
+        ? {
+          type: "wake_owner",
+          reason: "source_scoped_recovery_action",
+          ownerAgentId,
+        }
+        : {
+          type: "board_escalation",
+          reason: "no_invokable_recovery_owner",
+        },
+      monitorPolicy: null,
+      maxAttempts: null,
+      lastAttemptAt: now,
+    });
+
+    return action;
+  }
+
+  async function enqueueSourceScopedStrandedRecoveryWake(input: {
+    action: Awaited<ReturnType<typeof recoveryActionsSvc.upsertSourceScoped>>;
+    issue: typeof issues.$inferSelect;
+    latestRun: LatestIssueRun;
+    recoveryCause: StrandedRecoveryCause;
+  }) {
+    if (!input.action.ownerAgentId) return;
+    await deps.enqueueWakeup(input.action.ownerAgentId, {
+      source: "assignment",
+      triggerDetail: "system",
+      reason: "source_scoped_recovery_action",
+      idempotencyKey: `source_scoped_recovery_action:${input.action.id}:${input.action.attemptCount}`,
+      payload: withRecoveryModelProfileHint({
+        issueId: input.issue.id,
+        sourceIssueId: input.issue.id,
+        recoveryActionId: input.action.id,
+        strandedRunId: input.latestRun?.id ?? null,
+        recoveryCause: input.recoveryCause,
+      }),
+      requestedByActorType: "system",
+      requestedByActorId: null,
+      contextSnapshot: withRecoveryModelProfileHint({
+        issueId: input.issue.id,
+        taskId: input.issue.id,
+        wakeReason: "source_scoped_recovery_action",
+        skipIssueComment: true,
+        source: "issue_recovery_action",
+        recoveryActionId: input.action.id,
+        sourceIssueId: input.issue.id,
+        strandedRunId: input.latestRun?.id ?? null,
+        recoveryCause: input.recoveryCause,
+      }),
+    });
+  }
+
   function buildRecoveryIssueInPlaceEscalationComment(input: {
     issue: typeof issues.$inferSelect;
     previousStatus: "todo" | "in_progress";
@@ -1682,29 +1817,32 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
     recoveryCause?: StrandedRecoveryCause;
     successfulRunHandoffEvidence?: SuccessfulRunHandoffRecoveryEvidence | null;
   }) {
-    const nestedRecoverySuppressed = isStrandedIssueRecoveryIssue(input.issue);
-    let recoveryIssue: typeof issues.$inferSelect | null = null;
-    if (!nestedRecoverySuppressed) {
-      recoveryIssue = await ensureStrandedIssueRecoveryIssue({
+    if (isStrandedIssueRecoveryIssue(input.issue)) {
+      return escalateStrandedRecoveryIssueInPlace({
         issue: input.issue,
         previousStatus: input.previousStatus,
         latestRun: input.latestRun,
-        recoveryCause: input.recoveryCause,
-        successfulRunHandoffEvidence: input.successfulRunHandoffEvidence,
       });
     }
+
+    const recoveryCause = input.recoveryCause ?? "stranded_assigned_issue";
+    const recoveryAction = await ensureSourceScopedStrandedRecoveryAction({
+      issue: input.issue,
+      previousStatus: input.previousStatus,
+      latestRun: input.latestRun,
+      recoveryCause,
+      successfulRunHandoffEvidence: input.successfulRunHandoffEvidence,
+    });
     const blockerIds = await existingUnresolvedBlockerIssueIds(input.issue.companyId, input.issue.id);
-    const nextBlockerIds = recoveryIssue
-      ? [...new Set([...blockerIds, recoveryIssue.id])]
-      : blockerIds;
     const updated = await issuesSvc.update(input.issue.id, {
       status: "blocked",
-      blockedByIssueIds: nextBlockerIds,
+      blockedByIssueIds: blockerIds,
+      assigneeAgentId: recoveryAction.ownerAgentId ?? input.issue.assigneeAgentId,
     });
     if (!updated) return null;
 
     const prefix = await getCompanyIssuePrefix(input.issue.companyId);
-    const recoveryOwner = recoveryIssue?.assigneeAgentId ? await getAgent(recoveryIssue.assigneeAgentId) : null;
+    const recoveryOwner = recoveryAction.ownerAgentId ? await getAgent(recoveryAction.ownerAgentId) : null;
     const sourceAssignee = input.issue.assigneeAgentId ? await getAgent(input.issue.assigneeAgentId) : null;
     let notice: SuccessfulRunHandoffNotice | null = null;
     if (input.recoveryCause === SUCCESSFUL_RUN_MISSING_STATE_REASON && input.successfulRunHandoffEvidence) {
@@ -1715,39 +1853,60 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
           : null,
         correctiveRun: input.latestRun ? { id: input.latestRun.id, status: input.latestRun.status } : null,
         sourceAssignee,
-        recoveryIssue,
+        recoveryIssue: null,
+        recoveryActionId: recoveryAction.id,
         recoveryOwner,
         latestIssueStatus: input.issue.status,
         latestHandoffRunStatus: input.latestRun?.status ?? "unknown",
         missingDisposition: input.successfulRunHandoffEvidence.missingDisposition,
       });
     }
-    let recoveryLine: string;
-    if (nestedRecoverySuppressed) {
-      recoveryLine = await buildNestedStrandedRecoveryLine(input.issue, prefix);
-    } else if (recoveryIssue) {
-      recoveryLine = [
+    const recoveryLine = recoveryAction.ownerAgentId
+      ? [
         "",
-        `- Recovery issue: ${issueUiLink({ identifier: recoveryIssue.identifier, id: recoveryIssue.id }, prefix)}`,
+        `- Recovery action: \`${recoveryAction.id}\``,
         `- Recovery owner: ${agentUiLink(recoveryOwner, prefix)}`,
-        "- Next action: the recovery owner should either restore a live execution path or record the manual resolution, then mark the recovery issue done.",
-      ].join("\n");
-    } else {
-      recoveryLine = [
+        "- Next action: the recovery owner should either restore a live execution path or record the manual resolution on the source issue.",
+      ].join("\n")
+      : [
         "",
-        "- Recovery issue: none created because Paperclip could not find an invokable manager, creator, or executive owner with budget available.",
+        `- Recovery action: \`${recoveryAction.id}\``,
+        "- Recovery owner: board escalation, because Paperclip could not find an invokable manager, creator, or executive owner with budget available.",
         "- Next action: a board operator should assign an invokable recovery owner, fix the agent/runtime state, or record an intentional manual resolution.",
       ].join("\n");
-    }
 
-    if (notice) {
-      await issuesSvc.addComment(input.issue.id, notice.body, {}, {
-        authorType: "system",
-        presentation: notice.presentation,
-        metadata: notice.metadata,
-      });
-    } else {
-      await issuesSvc.addComment(input.issue.id, `${input.comment ?? ""}${recoveryLine}`, {});
+    if (recoveryAction.attemptCount === 1) {
+      const escalationCommentMarker = `Recovery action: \`${recoveryAction.id}\``;
+
+      const hasEscalationComment = await db
+        .select({ id: issueComments.id, body: issueComments.body, metadata: issueComments.metadata })
+        .from(issueComments)
+        .where(
+          and(
+            eq(issueComments.issueId, input.issue.id),
+            eq(issueComments.authorType, "system"),
+          ),
+        )
+        .orderBy(desc(issueComments.createdAt))
+        .limit(50)
+        .then((rows) => rows.some((row) =>
+          (row.body ?? "").includes(escalationCommentMarker) ||
+          noticeMetadataReferencesRecoveryAction(row.metadata, recoveryAction.id),
+        ));
+
+      if (!hasEscalationComment) {
+        if (notice) {
+          await issuesSvc.addComment(input.issue.id, notice.body, {}, {
+            authorType: "system",
+            presentation: notice.presentation,
+            metadata: notice.metadata,
+          });
+        } else {
+          await issuesSvc.addComment(input.issue.id, `${input.comment ?? ""}${recoveryLine}`, {}, {
+            authorType: "system",
+          });
+        }
+      }
     }
 
     await logActivity(db, {
@@ -1772,12 +1931,44 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
         latestRunId: input.latestRun?.id ?? null,
         latestRunStatus: input.latestRun?.status ?? null,
         latestRunErrorCode: input.latestRun?.errorCode ?? null,
-        recoveryIssueId: recoveryIssue?.id ?? null,
-        nestedRecoverySuppressed,
-        blockerIssueIds: nextBlockerIds,
+        recoveryActionId: recoveryAction.id,
+        recoveryOwnerAgentId: recoveryAction.ownerAgentId,
+        previousOwnerAgentId: recoveryAction.previousOwnerAgentId,
+        returnOwnerAgentId: recoveryAction.returnOwnerAgentId,
+        blockerIssueIds: blockerIds,
       },
     });
 
+    await enqueueSourceScopedStrandedRecoveryWake({
+      action: recoveryAction,
+      issue: input.issue,
+      latestRun: input.latestRun,
+      recoveryCause,
+    });
+
+    if (recoveryAction.ownerAgentId && recoveryAction.ownerAgentId === input.issue.assigneeAgentId) {
+      const [currentIssue] = await db
+        .select({
+          status: issues.status,
+          assigneeAgentId: issues.assigneeAgentId,
+        })
+        .from(issues)
+        .where(eq(issues.id, input.issue.id))
+        .limit(1);
+      if (
+        currentIssue &&
+        (currentIssue.status !== "blocked" ||
+          currentIssue.assigneeAgentId !== recoveryAction.ownerAgentId)
+      ) {
+        const reblocked = await issuesSvc.update(input.issue.id, {
+          status: "blocked",
+          blockedByIssueIds: blockerIds,
+          assigneeAgentId: recoveryAction.ownerAgentId,
+        });
+        if (reblocked) return reblocked;
+      }
+    }
+
     return updated;
   }
 
@@ -2038,6 +2229,33 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
   }
 
   async function collectIssueGraphLivenessFindings() {
+    const issueRowsPromise = Promise.resolve(db
+      .select({
+        id: issues.id,
+        companyId: issues.companyId,
+        identifier: issues.identifier,
+        title: issues.title,
+        status: issues.status,
+        projectId: issues.projectId,
+        goalId: issues.goalId,
+        parentId: issues.parentId,
+        assigneeAgentId: issues.assigneeAgentId,
+        assigneeUserId: issues.assigneeUserId,
+        createdByAgentId: issues.createdByAgentId,
+        createdByUserId: issues.createdByUserId,
+        executionPolicy: issues.executionPolicy,
+        executionState: issues.executionState,
+        monitorNextCheckAt: issues.monitorNextCheckAt,
+        monitorAttemptCount: issues.monitorAttemptCount,
+      })
+      .from(issues)
+      .where(
+        and(
+          isNull(issues.hiddenAt),
+          notInArray(issues.originKind, [RECOVERY_ORIGIN_KINDS.issueGraphLivenessEscalation]),
+        ),
+      ));
+
     const [
       issueRows,
       relationRows,
@@ -2048,33 +2266,9 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
       interactionRows,
       approvalRows,
       recoveryIssueRows,
+      recoveryActionRows,
     ] = await Promise.all([
-      db
-        .select({
-          id: issues.id,
-          companyId: issues.companyId,
-          identifier: issues.identifier,
-          title: issues.title,
-          status: issues.status,
-          projectId: issues.projectId,
-          goalId: issues.goalId,
-          parentId: issues.parentId,
-          assigneeAgentId: issues.assigneeAgentId,
-          assigneeUserId: issues.assigneeUserId,
-          createdByAgentId: issues.createdByAgentId,
-          createdByUserId: issues.createdByUserId,
-          executionPolicy: issues.executionPolicy,
-          executionState: issues.executionState,
-          monitorNextCheckAt: issues.monitorNextCheckAt,
-          monitorAttemptCount: issues.monitorAttemptCount,
-        })
-        .from(issues)
-        .where(
-          and(
-            isNull(issues.hiddenAt),
-            notInArray(issues.originKind, [RECOVERY_ORIGIN_KINDS.issueGraphLivenessEscalation]),
-          ),
-        ),
+      issueRowsPromise,
       db
         .select({
           companyId: issueRelations.companyId,
@@ -2164,6 +2358,24 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
             notInArray(issues.status, ["done", "cancelled"]),
           ),
         ),
+      issueRowsPromise.then((rows) => {
+        const issueIdsUnderAnalysis = rows.map((row) => row.id);
+        return issueIdsUnderAnalysis.length === 0
+          ? []
+          : db
+            .select({
+              companyId: issueRecoveryActions.companyId,
+              issueId: issueRecoveryActions.sourceIssueId,
+              status: issueRecoveryActions.status,
+            })
+            .from(issueRecoveryActions)
+            .where(
+              and(
+                inArray(issueRecoveryActions.status, ["active", "escalated"]),
+                inArray(issueRecoveryActions.sourceIssueId, issueIdsUnderAnalysis),
+              ),
+            );
+      }),
     ]);
 
     const openRecoveryIssues = recoveryIssueRows.flatMap((row) => {
@@ -2217,7 +2429,7 @@ export function recoveryService(db: Db, deps: { enqueueWakeup: RecoveryWakeup })
       })),
       pendingInteractions: interactionRows,
       pendingApprovals: approvalRows,
-      openRecoveryIssues,
+      openRecoveryIssues: openRecoveryIssues.concat(recoveryActionRows),
       now: new Date(),
     });
   }
diff --git a/server/src/services/recovery/successful-run-handoff.test.ts b/server/src/services/recovery/successful-run-handoff.test.ts
index 727512f4..d11aaff5 100644
--- a/server/src/services/recovery/successful-run-handoff.test.ts
+++ b/server/src/services/recovery/successful-run-handoff.test.ts
@@ -10,6 +10,7 @@ import {
   decideSuccessfulRunHandoff,
   isIdempotentFinishSuccessfulRunHandoffWakeStatus,
   isSuccessfulRunHandoffRequiredNoticeBody,
+  noticeMetadataReferencesRecoveryAction,
 } from "./successful-run-handoff.js";
 
 const run = {
@@ -256,6 +257,7 @@ describe("successful run handoff decision", () => {
         title: "Recover missing next step PAP-1",
         status: "todo",
       } as any,
+      recoveryActionId: "77777777-7777-4777-8777-777777777777",
       recoveryOwner: { id: "66666666-6666-4666-8666-666666666666", name: "CTO" } as any,
       latestIssueStatus: "in_progress",
       latestHandoffRunStatus: "failed",
@@ -273,7 +275,7 @@ describe("successful run handoff decision", () => {
       expect.objectContaining({
         title: "Recovery owner",
         rows: expect.arrayContaining([
-          expect.objectContaining({ type: "issue_link", identifier: "PAP-2" }),
+          expect.objectContaining({ type: "key_value", label: "Recovery action", value: "77777777-7777-4777-8777-777777777777" }),
           expect.objectContaining({ type: "agent_link", label: "Recovery owner", name: "CTO" }),
         ]),
       }),
@@ -286,6 +288,8 @@ describe("successful run handoff decision", () => {
         ]),
       }),
     ]));
+    expect(noticeMetadataReferencesRecoveryAction(notice.metadata, "77777777-7777-4777-8777-777777777777")).toBe(true);
+    expect(noticeMetadataReferencesRecoveryAction(notice.metadata, "88888888-8888-4888-8888-888888888888")).toBe(false);
   });
 
   it("recognizes new notices and legacy markdown headings for fallback deduplication", () => {
diff --git a/server/src/services/recovery/successful-run-handoff.ts b/server/src/services/recovery/successful-run-handoff.ts
index 1b9bbe18..53ec9b64 100644
--- a/server/src/services/recovery/successful-run-handoff.ts
+++ b/server/src/services/recovery/successful-run-handoff.ts
@@ -61,6 +61,19 @@ export type SuccessfulRunHandoffNotice = {
   metadata: IssueCommentMetadata;
 };
 
+export function noticeMetadataReferencesRecoveryAction(
+  metadata: IssueCommentMetadata | null | undefined,
+  recoveryActionId: string,
+) {
+  return (metadata?.sections ?? []).some((section) =>
+    section.rows.some((row) =>
+      row.type === "key_value" &&
+      row.label === "Recovery action" &&
+      row.value === recoveryActionId,
+    ),
+  );
+}
+
 export type SuccessfulRunHandoffDecision =
   | {
       kind: "enqueue";
@@ -181,6 +194,7 @@ export function buildSuccessfulRunHandoffExhaustedNotice(input: {
   correctiveRun: NullableNoticeRun;
   sourceAssignee: NullableNoticeAgent;
   recoveryIssue: NullableNoticeIssue;
+  recoveryActionId?: string | null;
   recoveryOwner: NullableNoticeAgent;
   latestIssueStatus: string;
   latestHandoffRunStatus: string;
@@ -200,7 +214,9 @@ export function buildSuccessfulRunHandoffExhaustedNotice(input: {
           title: "Recovery owner",
           rows: [
             issueLinkRow("Source issue", input.issue),
-            issueLinkRow("Recovery issue", input.recoveryIssue),
+            input.recoveryActionId
+              ? keyValueRow("Recovery action", input.recoveryActionId)
+              : issueLinkRow("Recovery issue", input.recoveryIssue),
             agentLinkRow("Recovery owner", input.recoveryOwner),
             agentLinkRow("Source assignee", input.sourceAssignee),
             keyValueRow("Suggested action", "choose and record a valid issue disposition without copying transcript content"),
diff --git a/server/src/services/session-workspace-cwd.test.ts b/server/src/services/session-workspace-cwd.test.ts
new file mode 100644
index 00000000..92e3f28f
--- /dev/null
+++ b/server/src/services/session-workspace-cwd.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { isUnsafeSessionWorkspaceCwd } from "./session-workspace-cwd.js";
+
+describe("isUnsafeSessionWorkspaceCwd", () => {
+  it("rejects system roots that can poison remote sandbox session resumes", () => {
+    expect(isUnsafeSessionWorkspaceCwd("/")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/tmp")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/tmp/")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/private/tmp")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/var/tmp")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/var/run")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/proc")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/sys")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/dev")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/run")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/tmp/.")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/tmp/..")).toBe(true);
+    expect(isUnsafeSessionWorkspaceCwd("/var/./run")).toBe(true);
+  });
+
+  it("allows concrete workspace descendants", () => {
+    expect(isUnsafeSessionWorkspaceCwd("/tmp/paperclip-workspace")).toBe(false);
+    expect(isUnsafeSessionWorkspaceCwd("/Users/dotta/paperclip")).toBe(false);
+    expect(isUnsafeSessionWorkspaceCwd(null)).toBe(false);
+  });
+});
diff --git a/server/src/services/session-workspace-cwd.ts b/server/src/services/session-workspace-cwd.ts
new file mode 100644
index 00000000..b1efc543
--- /dev/null
+++ b/server/src/services/session-workspace-cwd.ts
@@ -0,0 +1,24 @@
+import path from "node:path";
+
+const SESSION_CWD_SYSTEM_ROOTS = new Set([
+  "/",
+  "/tmp",
+  "/var",
+  "/var/tmp",
+  "/var/run",
+  "/usr",
+  "/etc",
+  "/proc",
+  "/sys",
+  "/dev",
+  "/run",
+  "/private",
+  "/private/tmp",
+]);
+
+export function isUnsafeSessionWorkspaceCwd(cwd: string | null | undefined): boolean {
+  const value = typeof cwd === "string" && cwd.trim().length > 0 ? cwd.trim() : null;
+  if (!value) return false;
+  const normalized = path.normalize(value.replace(/\/+$/, "") || "/");
+  return SESSION_CWD_SYSTEM_ROOTS.has(normalized);
+}
diff --git a/skills/paperclip-create-plugin/SKILL.md b/skills/paperclip-create-plugin/SKILL.md
index b288a081..4dda697d 100644
--- a/skills/paperclip-create-plugin/SKILL.md
+++ b/skills/paperclip-create-plugin/SKILL.md
@@ -1,23 +1,34 @@
 ---
 name: paperclip-create-plugin
 description: >
-  Create new Paperclip plugins with the current alpha SDK/runtime. Use when
-  scaffolding a plugin package, adding a new example plugin, or updating plugin
-  authoring docs. Covers the supported worker/UI surface, route conventions,
-  scaffold flow, and verification steps.
+  Create and develop external Paperclip plugins with the CLI-first workflow.
+  Use when scaffolding a new plugin, working on a local plugin against a running
+  Paperclip instance, or updating plugin authoring docs. Covers `paperclipai
+  plugin init`, the local install loop via `paperclipai plugin install <path>`,
+  worker/UI rebuild and reload semantics, and the required success checklist.
 ---
 
-# Create a Paperclip Plugin
+# Create and develop a Paperclip plugin
 
-Use this skill when the task is to create, scaffold, or document a Paperclip plugin.
+Use this skill when the task is to create, scaffold, or iterate on a Paperclip plugin against a local Paperclip instance.
 
-## 1. Ground rules
+## 1. Default: build the plugin OUTSIDE Paperclip core
 
-Read these first when needed:
+Plugins are their own packages. Unless the task **explicitly** asks for a bundled in-repo example, do not add plugin source under `packages/plugins/` in this repo.
+
+- Scaffold the plugin into a directory outside the Paperclip checkout (e.g. `~/dev/paperclip-plugins/<name>`).
+- Install it into the running Paperclip instance by local absolute path.
+- Edit code in the external package; let Paperclip pick up rebuilt output.
+
+Only edit Paperclip core itself when the user asks to surface a plugin as a bundled example (`server/src/routes/plugins.ts`, in-repo example lists, docs).
+
+## 2. Ground rules
+
+Reference docs when you need detail:
 
 1. `doc/plugins/PLUGIN_AUTHORING_GUIDE.md`
 2. `packages/plugins/sdk/README.md`
-3. `doc/plugins/PLUGIN_SPEC.md` only for future-looking context
+3. `doc/plugins/PLUGIN_SPEC.md` — future-looking context only
 
 Current runtime assumptions:
 
@@ -28,38 +39,67 @@ Current runtime assumptions:
 - no host-provided shared plugin UI component kit yet
 - `ctx.assets` is not supported in the current runtime
 
-## 2. Preferred workflow
+## 3. CLI-first scaffold workflow
 
-Use the scaffold package instead of hand-writing the boilerplate:
+Use `paperclipai plugin init`. Do not invoke the scaffold package node entrypoint by hand unless the CLI command is unavailable in the environment.
 
 ```bash
-pnpm --filter @paperclipai/create-paperclip-plugin build
-node packages/plugins/create-paperclip-plugin/dist/index.js <npm-package-name> --output <target-dir>
+paperclipai plugin init @acme/my-plugin --output ~/dev/paperclip-plugins
 ```
 
-For a plugin that lives outside the Paperclip repo, pass `--sdk-path` and let the scaffold snapshot the local SDK/shared packages into `.paperclip-sdk/`:
+Useful flags (all optional):
+
+- `--output <dir>` — parent directory; the command creates `<dir>/<unscoped-name>/`. Defaults to the current directory.
+- `--template <default|connector|workspace|environment>` — starter template.
+- `--category <connector|workspace|automation|ui|environment>` — manifest category.
+- `--display-name <name>`, `--description <text>`, `--author <name>` — manifest metadata.
+- `--sdk-path <path>` — snapshot the local SDK from a Paperclip checkout into `.paperclip-sdk/` (useful when developing against an unreleased SDK).
+
+On success the command prints the exact next commands (`cd`, `pnpm install`, `pnpm dev`, `paperclipai plugin install <abs-path>`). Run them in order.
+
+If `paperclipai` is not on PATH in your environment, fall back to:
 
 ```bash
 pnpm --filter @paperclipai/create-paperclip-plugin build
-node packages/plugins/create-paperclip-plugin/dist/index.js @acme/plugin-name \
-  --output /absolute/path/to/plugin-repos \
+node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
+  --output /absolute/path \
   --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
 ```
 
-Recommended target inside this repo:
+## 4. Local install + rebuild loop
 
-- `packages/plugins/examples/` for example plugins
-- another `packages/plugins/<name>/` folder if it is becoming a real package
+In the scaffolded plugin folder:
 
-## 3. After scaffolding
+```bash
+pnpm install
+pnpm dev            # esbuild --watch: rebuilds dist/manifest.js, dist/worker.js, dist/ui/
+paperclipai plugin install /absolute/path/to/my-plugin
+```
 
-Check and adjust:
+Notes:
 
-- `src/manifest.ts`
-- `src/worker.ts`
-- `src/ui/index.tsx`
-- `tests/plugin.spec.ts`
-- `package.json`
+- `paperclipai plugin install` auto-detects local paths (absolute, `./`, `../`, `~`, or an existing relative folder) and forwards `isLocalPath: true` to the server. Pass `--local` to force local mode if the heuristic is ambiguous.
+- Paths are resolved to absolute paths before being sent to the server.
+- The server watches built outputs (`dist/`) for local-path plugins and restarts the plugin worker on rebuild — you do not need to reinstall after every edit.
+- UI hot reload via the SDK dev server (`pnpm dev:ui`, port `4177`) is optional and template-dependent; only mention it if the template wires `devUiUrl` and you verified it works end to end.
+- `--version` only applies to npm package installs. Combining it with a local path is an error.
+
+After install, inspect with:
+
+```bash
+paperclipai plugin list
+paperclipai plugin inspect <plugin-key>
+```
+
+## 5. After scaffolding, sanity-check the package
+
+Open and confirm:
+
+- `src/manifest.ts` — declared capabilities and slots
+- `src/worker.ts` — worker entry
+- `src/ui/index.tsx` — UI entry (if applicable)
+- `tests/plugin.spec.ts` — placeholder test
+- `package.json` — `paperclipPlugin` block points at `dist/manifest.js`, `dist/worker.js`, `dist/ui/`
 
 Make sure the plugin:
 
@@ -68,34 +108,47 @@ Make sure the plugin:
 - does not import host UI component stubs
 - keeps UI self-contained
 - uses `routePath` only on `page` slots
-- is installed into Paperclip from an absolute local path during development
 
-## 4. If the plugin should appear in the app
+## 6. Verification (run before declaring success)
 
-For bundled example/discoverable behavior, update the relevant host wiring:
-
-- bundled example list in `server/src/routes/plugins.ts`
-- any docs that list in-repo examples
-
-Only do this if the user wants the plugin surfaced as a bundled example.
-
-## 5. Verification
-
-Always run:
+From the plugin folder:
 
 ```bash
-pnpm --filter <plugin-package> typecheck
-pnpm --filter <plugin-package> test
-pnpm --filter <plugin-package> build
+pnpm typecheck
+pnpm test
+pnpm build
 ```
 
-If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
+If the plugin is already running under `pnpm dev`, you can keep the watcher up and run `pnpm typecheck` and `pnpm test` in a separate shell.
 
-## 6. Documentation expectations
+If you changed Paperclip SDK/host/plugin runtime code in addition to the plugin, also run the relevant Paperclip workspace checks.
+
+## 7. Success checklist (report this back)
+
+When you finish a local plugin task, report:
+
+- **Scaffold path** — absolute path of the created plugin folder.
+- **Commands run** — the exact `paperclipai plugin init`, `pnpm install`, `pnpm dev`, `paperclipai plugin install <path>` invocations (and any verification commands).
+- **Install status** — output of `paperclipai plugin list` / `plugin inspect` (plugin key, version, status). Note if `status` is anything other than `ready` and include `lastError`.
+- **Tests / build result** — `pnpm typecheck`, `pnpm test`, `pnpm build` pass/fail with the failing output if any.
+- **Reload limitations** — call out anything that did not hot-reload (e.g. manifest changes required a reinstall, UI dev server was not wired, etc.).
+
+If any item is missing, mark it as such — do not silently skip.
+
+## 8. When NOT to edit Paperclip core
+
+Do not add the plugin under `packages/plugins/` or update bundled-example wiring unless the user explicitly asks for a bundled example. Local-path installs are the supported development model; npm packages are the production deployment path.
+
+If the user does ask for a bundled example, also update:
+
+- `server/src/routes/plugins.ts` example list
+- any docs that enumerate in-repo example plugins
+
+## 9. Documentation expectations
 
 When authoring or updating plugin docs:
 
 - distinguish current implementation from future spec ideas
 - be explicit about the trusted-code model
 - do not promise host UI components or asset APIs
-- prefer npm-package deployment guidance over repo-local workflows for production
+- prefer local-path development + npm-package deployment guidance over repo-local workflows
diff --git a/ui/src/App.tsx b/ui/src/App.tsx
index 6e86c76d..09161d09 100644
--- a/ui/src/App.tsx
+++ b/ui/src/App.tsx
@@ -128,6 +128,7 @@ function boardRoutes() {
       <Route path="inbox/mine" element={<Inbox />} />
       <Route path="inbox/recent" element={<Inbox />} />
       <Route path="inbox/unread" element={<Inbox />} />
+      <Route path="inbox/blocked" element={<Inbox />} />
       <Route path="inbox/all" element={<Inbox />} />
       <Route path="inbox/requests" element={<JoinRequestQueue />} />
       <Route path="inbox/new" element={<Navigate to="/inbox/mine" replace />} />
diff --git a/ui/src/api/issues.test.ts b/ui/src/api/issues.test.ts
index 107f12b1..4013f67d 100644
--- a/ui/src/api/issues.test.ts
+++ b/ui/src/api/issues.test.ts
@@ -2,6 +2,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 
 const mockApi = vi.hoisted(() => ({
   get: vi.fn(),
+  post: vi.fn(),
 }));
 
 vi.mock("./client", () => ({
@@ -13,7 +14,9 @@ import { issuesApi } from "./issues";
 describe("issuesApi.list", () => {
   beforeEach(() => {
     mockApi.get.mockReset();
+    mockApi.post.mockReset();
     mockApi.get.mockResolvedValue([]);
+    mockApi.post.mockResolvedValue({});
   });
 
   it("passes parentId through to the company issues endpoint", async () => {
@@ -47,4 +50,21 @@ describe("issuesApi.list", () => {
       "/companies/company-1/issues?limit=500&offset=1500",
     );
   });
+
+  it("posts recovery action resolution to the source issue endpoint", async () => {
+    await issuesApi.resolveRecoveryAction("issue-1", {
+      actionId: "00000000-0000-0000-0000-0000000000aa",
+      outcome: "restored",
+      sourceIssueStatus: "done",
+    });
+
+    expect(mockApi.post).toHaveBeenCalledWith(
+      "/issues/issue-1/recovery-actions/resolve",
+      {
+        actionId: "00000000-0000-0000-0000-0000000000aa",
+        outcome: "restored",
+        sourceIssueStatus: "done",
+      },
+    );
+  });
 });
diff --git a/ui/src/api/issues.ts b/ui/src/api/issues.ts
index 10427c50..389699a4 100644
--- a/ui/src/api/issues.ts
+++ b/ui/src/api/issues.ts
@@ -12,6 +12,7 @@ import type {
   IssueComment,
   IssueDocument,
   IssueLabel,
+  IssueRecoveryAction,
   IssueRetryNowResponse,
   IssueThreadInteraction,
   IssueTreeControlPreview,
@@ -27,10 +28,16 @@ export type IssueUpdateResponse = Issue & {
   comment?: IssueComment | null;
 };
 
+export type ResolveRecoveryActionResponse = {
+  issue: Issue;
+  recoveryAction: IssueRecoveryAction;
+};
+
 export const issuesApi = {
   list: (
     companyId: string,
     filters?: {
+      attention?: "blocked";
       status?: string;
       projectId?: string;
       parentId?: string;
@@ -49,12 +56,14 @@ export const issuesApi = {
       descendantOf?: string;
       includeRoutineExecutions?: boolean;
       includeBlockedBy?: boolean;
+      includeBlockedInboxAttention?: boolean;
       q?: string;
       limit?: number;
       offset?: number;
     },
   ) => {
     const params = new URLSearchParams();
+    if (filters?.attention) params.set("attention", filters.attention);
     if (filters?.status) params.set("status", filters.status);
     if (filters?.projectId) params.set("projectId", filters.projectId);
     if (filters?.parentId) params.set("parentId", filters.parentId);
@@ -73,12 +82,35 @@ export const issuesApi = {
     if (filters?.descendantOf) params.set("descendantOf", filters.descendantOf);
     if (filters?.includeRoutineExecutions) params.set("includeRoutineExecutions", "true");
     if (filters?.includeBlockedBy) params.set("includeBlockedBy", "true");
+    if (filters?.includeBlockedInboxAttention) params.set("includeBlockedInboxAttention", "true");
     if (filters?.q) params.set("q", filters.q);
     if (filters?.limit) params.set("limit", String(filters.limit));
     if (filters?.offset !== undefined) params.set("offset", String(filters.offset));
     const qs = params.toString();
     return api.get<Issue[]>(`/companies/${companyId}/issues${qs ? `?${qs}` : ""}`);
   },
+  count: (
+    companyId: string,
+    filters: {
+      attention: "blocked";
+      status?: string;
+      assigneeAgentId?: string;
+      assigneeUserId?: string;
+      projectId?: string;
+      labelId?: string;
+      q?: string;
+    },
+  ) => {
+    const params = new URLSearchParams();
+    params.set("attention", filters.attention);
+    if (filters.status) params.set("status", filters.status);
+    if (filters.assigneeAgentId) params.set("assigneeAgentId", filters.assigneeAgentId);
+    if (filters.assigneeUserId) params.set("assigneeUserId", filters.assigneeUserId);
+    if (filters.projectId) params.set("projectId", filters.projectId);
+    if (filters.labelId) params.set("labelId", filters.labelId);
+    if (filters.q) params.set("q", filters.q);
+    return api.get<{ count: number }>(`/companies/${companyId}/issues/count?${params.toString()}`);
+  },
   listLabels: (companyId: string) => api.get<IssueLabel[]>(`/companies/${companyId}/labels`),
   createLabel: (companyId: string, data: { name: string; color: string }) =>
     api.post<IssueLabel>(`/companies/${companyId}/labels`, data),
@@ -94,6 +126,15 @@ export const issuesApi = {
     api.post<Issue>(`/companies/${companyId}/issues`, data),
   update: (id: string, data: Record<string, unknown>) =>
     api.patch<IssueUpdateResponse>(`/issues/${id}`, data),
+  resolveRecoveryAction: (
+    id: string,
+    data: {
+      actionId?: string;
+      outcome: "restored" | "false_positive" | "blocked" | "cancelled";
+      sourceIssueStatus: "done" | "in_review" | "blocked";
+      resolutionNote?: string | null;
+    },
+  ) => api.post<ResolveRecoveryActionResponse>(`/issues/${id}/recovery-actions/resolve`, data),
   previewTreeControl: (id: string, data: PreviewIssueTreeControl) =>
     api.post<IssueTreeControlPreview>(`/issues/${id}/tree-control/preview`, data),
   createTreeHold: (id: string, data: CreateIssueTreeHold) =>
diff --git a/ui/src/components/ActiveAgentsPanel.tsx b/ui/src/components/ActiveAgentsPanel.tsx
index 905c2147..4ff1c2ce 100644
--- a/ui/src/components/ActiveAgentsPanel.tsx
+++ b/ui/src/components/ActiveAgentsPanel.tsx
@@ -1,17 +1,44 @@
 import { memo, useMemo } from "react";
 import { Link } from "@/lib/router";
 import { useQueries, useQuery } from "@tanstack/react-query";
-import type { Issue } from "@paperclipai/shared";
+import type { Issue, IssueRecoveryAction } from "@paperclipai/shared";
 import { heartbeatsApi, type LiveRunForIssue } from "../api/heartbeats";
 import type { TranscriptEntry } from "../adapters";
 import { issuesApi } from "../api/issues";
 import { queryKeys } from "../lib/queryKeys";
 import { cn, relativeTime } from "../lib/utils";
+import {
+  deriveActiveRecoveryDisplayState,
+  RECOVERY_CHIP_DEFAULT_TONE,
+} from "../lib/recovery-display";
 import { ExternalLink } from "lucide-react";
 import { Identity } from "./Identity";
 import { RunChatSurface } from "./RunChatSurface";
 import { useLiveRunTranscripts } from "./transcript/useLiveRunTranscripts";
 
+function RunCardRecoveryChip({ action }: { action: IssueRecoveryAction }) {
+  const state = deriveActiveRecoveryDisplayState(action);
+  if (!state) return null;
+  const tone = RECOVERY_CHIP_DEFAULT_TONE[state];
+  const Icon = tone.icon;
+  return (
+    <span
+      data-testid="active-agent-run-recovery-indicator"
+      data-recovery-state={state}
+      role="status"
+      aria-label={tone.label}
+      title={`${tone.label} — open the source issue to act.`}
+      className={cn(
+        "inline-flex shrink-0 items-center gap-0.5 rounded-full border px-1.5 py-0.5 text-[10px] font-medium",
+        tone.className,
+      )}
+    >
+      <Icon className="h-2.5 w-2.5" aria-hidden />
+      {tone.label}
+    </span>
+  );
+}
+
 const MIN_DASHBOARD_RUNS = 4;
 const DASHBOARD_RUN_CARD_LIMIT = 4;
 const DASHBOARD_LOG_POLL_INTERVAL_MS = 15_000;
@@ -189,6 +216,11 @@ const AgentRunCard = memo(function AgentRunCard({
               {issue?.identifier ?? run.issueId.slice(0, 8)}
               {issue?.title ? ` - ${issue.title}` : ""}
             </Link>
+            {issue?.activeRecoveryAction ? (
+              <div className="mt-1.5">
+                <RunCardRecoveryChip action={issue.activeRecoveryAction} />
+              </div>
+            ) : null}
           </div>
         )}
       </div>
diff --git a/ui/src/components/BlockedInboxView.test.tsx b/ui/src/components/BlockedInboxView.test.tsx
new file mode 100644
index 00000000..328ceb91
--- /dev/null
+++ b/ui/src/components/BlockedInboxView.test.tsx
@@ -0,0 +1,329 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { Issue, IssueBlockedInboxAttention } from "@paperclipai/shared";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockIssuesApi = vi.hoisted(() => ({
+  list: vi.fn(),
+  count: vi.fn(),
+}));
+
+vi.mock("../api/issues", () => ({
+  issuesApi: mockIssuesApi,
+}));
+
+vi.mock("@/lib/router", () => ({
+  Link: ({
+    children,
+    className,
+    disableIssueQuicklook: _disableIssueQuicklook,
+    issuePrefetch: _issuePrefetch,
+    ...props
+  }: React.ComponentProps<"a"> & { disableIssueQuicklook?: boolean; issuePrefetch?: Issue | null }) => (
+    <a className={className} {...props}>
+      {children}
+    </a>
+  ),
+}));
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+import { BlockedInboxView } from "./BlockedInboxView";
+import { defaultIssueFilterState } from "../lib/issue-filters";
+
+function attention(
+  overrides: Partial<IssueBlockedInboxAttention> = {},
+): IssueBlockedInboxAttention {
+  return {
+    kind: "blocked",
+    state: "needs_attention",
+    reason: "blocked_chain_stalled",
+    severity: "medium",
+    stoppedSinceAt: "2026-05-08T10:00:00.000Z",
+    owner: { type: "agent", agentId: "agent-1", userId: null, label: null },
+    action: { label: "Resolve PAP-77", detail: null },
+    sourceIssue: null,
+    leafIssue: null,
+    recoveryIssue: null,
+    approvalId: null,
+    interactionId: null,
+    sampleIssueIdentifier: null,
+    redaction: { externalDetailsRedacted: false, secretFieldsOmitted: true },
+    ...overrides,
+  };
+}
+
+function makeIssue(
+  id: string,
+  identifier: string,
+  title: string,
+  attentionPayload: IssueBlockedInboxAttention,
+): Issue {
+  return {
+    id,
+    companyId: "company-1",
+    projectId: null,
+    projectWorkspaceId: null,
+    goalId: null,
+    parentId: null,
+    title,
+    description: null,
+    status: "in_progress",
+    workMode: "standard",
+    priority: "medium",
+    assigneeAgentId: "agent-1",
+    assigneeUserId: null,
+    checkoutRunId: null,
+    executionRunId: null,
+    executionAgentNameKey: null,
+    executionLockedAt: null,
+    createdByAgentId: null,
+    createdByUserId: null,
+    issueNumber: 1,
+    identifier,
+    requestDepth: 0,
+    billingCode: null,
+    assigneeAdapterOverrides: null,
+    executionWorkspaceId: null,
+    executionWorkspacePreference: null,
+    executionWorkspaceSettings: null,
+    startedAt: null,
+    completedAt: null,
+    cancelledAt: null,
+    hiddenAt: null,
+    blockedInboxAttention: attentionPayload,
+    createdAt: new Date("2026-05-09T00:00:00.000Z"),
+    updatedAt: new Date("2026-05-09T00:00:00.000Z"),
+  } as Issue;
+}
+
+function renderWithClient(node: React.ReactNode, container: HTMLDivElement) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false, staleTime: 0, gcTime: 0 } },
+  });
+  const root = createRoot(container);
+  act(() => {
+    root.render(<QueryClientProvider client={queryClient}>{node}</QueryClientProvider>);
+  });
+  return { root, queryClient };
+}
+
+const blockedViewProps = {
+  companyId: "company-1",
+  searchQuery: "",
+  agentNameById: new Map<string, string>(),
+  issueLinkState: null,
+  groupBy: "none" as const,
+  sortBy: "most_recent" as const,
+  issueFilters: defaultIssueFilterState,
+  currentUserId: "local-board",
+  liveIssueIds: new Set<string>(),
+  workspaceFilterContext: {},
+  showStatusColumn: true,
+  showIdentifierColumn: true,
+  showUpdatedColumn: true,
+};
+
+async function waitFor(predicate: () => boolean, attempts = 30): Promise<void> {
+  for (let i = 0; i < attempts; i += 1) {
+    if (predicate()) return;
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    });
+  }
+  throw new Error("waitFor predicate did not become true");
+}
+
+describe("BlockedInboxView", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    mockIssuesApi.list.mockReset();
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it("shows the empty state when no blocked issues are returned", async () => {
+    mockIssuesApi.list.mockResolvedValue([]);
+    const { root } = renderWithClient(
+      <BlockedInboxView
+        {...blockedViewProps}
+      />,
+      container,
+    );
+    await waitFor(() => container.querySelector('[data-testid="blocked-inbox-empty"]') !== null);
+    expect(container.querySelector('[data-testid="blocked-inbox-empty"]')).not.toBeNull();
+    act(() => root.unmount());
+  });
+
+  it("defaults to no grouping and orders rows by most recent stopped item first", async () => {
+    const issues: Issue[] = [
+      makeIssue(
+        "issue-low",
+        "PAP-1",
+        "External wait row",
+        attention({ reason: "external_owner_action", severity: "low" }),
+      ),
+      makeIssue(
+        "issue-stalled-high",
+        "PAP-2",
+        "Stalled chain row",
+        attention({
+          reason: "blocked_chain_stalled",
+          severity: "high",
+          stoppedSinceAt: "2026-05-09T01:00:00.000Z",
+          action: { label: "Resolve PAP-9", detail: null },
+        }),
+      ),
+      makeIssue(
+        "issue-stalled-critical",
+        "PAP-3",
+        "Critical stalled row",
+        attention({
+          reason: "blocked_chain_stalled",
+          severity: "critical",
+          stoppedSinceAt: "2026-05-09T05:00:00.000Z",
+          action: { label: "Resolve PAP-10", detail: null },
+        }),
+      ),
+      makeIssue(
+        "issue-decision",
+        "PAP-4",
+        "Pending board decision",
+        attention({
+          reason: "pending_board_decision",
+          severity: "medium",
+          owner: { type: "board", agentId: null, userId: null, label: "Board" },
+          action: { label: "Accept or reject", detail: null },
+        }),
+      ),
+    ];
+    mockIssuesApi.list.mockResolvedValue(issues);
+
+    const { root } = renderWithClient(
+      <BlockedInboxView
+        {...blockedViewProps}
+        agentNameById={new Map([["agent-1", "ClaudeCoder"]])}
+      />,
+      container,
+    );
+    await waitFor(() => container.querySelectorAll("a").length === 4);
+
+    expect(container.querySelectorAll('[data-testid^="blocked-inbox-group-"]')).toHaveLength(0);
+
+    const titles = Array.from(container.querySelectorAll("a")).map((a) => a.textContent ?? "");
+    expect(titles[0]).toContain("Critical stalled row");
+    expect(titles[1]).toContain("Stalled chain row");
+
+    expect(mockIssuesApi.list).toHaveBeenCalledWith("company-1", expect.objectContaining({
+      attention: "blocked",
+      includeBlockedInboxAttention: true,
+      includeBlockedBy: true,
+    }));
+
+    act(() => root.unmount());
+  });
+
+  it("places blocker reason chips with the title before owner and timestamp metadata", async () => {
+    mockIssuesApi.list.mockResolvedValue([
+      makeIssue(
+        "issue-decision",
+        "PAP-4",
+        "Pending board decision",
+        attention({
+          reason: "pending_board_decision",
+          severity: "medium",
+          owner: { type: "board", agentId: null, userId: null, label: "Board" },
+          action: { label: "Accept or reject", detail: null },
+        }),
+      ),
+    ]);
+
+    const { root } = renderWithClient(
+      <BlockedInboxView
+        {...blockedViewProps}
+      />,
+      container,
+    );
+    await waitFor(() => container.querySelector("a") !== null);
+
+    const rowText = container.querySelector("a")?.textContent ?? "";
+    expect(rowText.indexOf("Pending board decision")).toBeGreaterThanOrEqual(0);
+    expect(rowText.indexOf("Needs decision")).toBeGreaterThan(rowText.indexOf("Pending board decision"));
+    expect(rowText.indexOf("Board")).toBeGreaterThan(rowText.indexOf("Needs decision"));
+    expect(rowText).not.toContain("Accept or reject");
+    expect(container.querySelector('[data-testid="blocked-row-reason-column"]')?.textContent).toContain("Needs decision");
+
+    act(() => root.unmount());
+  });
+
+  it("filters rows by search query against title, identifier, owner and action", async () => {
+    const issues: Issue[] = [
+      makeIssue(
+        "issue-1",
+        "PAP-77",
+        "Resume parked work",
+        attention({
+          reason: "blocked_by_assigned_backlog_issue",
+          owner: { type: "agent", agentId: null, userId: null, label: "Charlie" },
+          action: { label: "Resume parked blocker", detail: null },
+        }),
+      ),
+      makeIssue(
+        "issue-2",
+        "PAP-99",
+        "Other unrelated thing",
+        attention({
+          reason: "external_owner_action",
+          owner: { type: "external", agentId: null, userId: null, label: "Vendor" },
+          action: { label: "Awaiting Vendor", detail: null },
+        }),
+      ),
+    ];
+    mockIssuesApi.list.mockResolvedValue(issues);
+
+    const { root } = renderWithClient(
+      <BlockedInboxView
+        {...blockedViewProps}
+        searchQuery="charlie"
+      />,
+      container,
+    );
+    await waitFor(() => container.querySelectorAll("a").length > 0);
+
+    const links = container.querySelectorAll("a");
+    const titles = Array.from(links).map((a) => a.textContent ?? "");
+    expect(titles.some((t) => t.includes("Resume parked work"))).toBe(true);
+    expect(titles.some((t) => t.includes("Other unrelated thing"))).toBe(false);
+
+    act(() => root.unmount());
+  });
+
+  it("renders the visible error banner with retry when the query fails", async () => {
+    mockIssuesApi.list.mockRejectedValue(new Error("network down"));
+
+    const { root } = renderWithClient(
+      <BlockedInboxView
+        {...blockedViewProps}
+      />,
+      container,
+    );
+    await waitFor(() =>
+      container.querySelector('[data-testid="blocked-inbox-error"]') !== null,
+    );
+
+    const banner = container.querySelector('[data-testid="blocked-inbox-error"]');
+    expect(banner).not.toBeNull();
+    expect(banner?.getAttribute("role")).toBe("alert");
+    expect(banner?.textContent).toContain("Couldn't load the Blocked tab");
+
+    act(() => root.unmount());
+  });
+});
diff --git a/ui/src/components/BlockedInboxView.tsx b/ui/src/components/BlockedInboxView.tsx
new file mode 100644
index 00000000..39764efa
--- /dev/null
+++ b/ui/src/components/BlockedInboxView.tsx
@@ -0,0 +1,386 @@
+import { useMemo, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { AlertTriangle, CheckCircle2 } from "lucide-react";
+import type { Issue } from "@paperclipai/shared";
+import { issuesApi } from "../api/issues";
+import { queryKeys } from "../lib/queryKeys";
+import { cn } from "../lib/utils";
+import { applyIssueFilters, type IssueFilterState, type IssueFilterWorkspaceContext } from "../lib/issue-filters";
+import {
+  blockedRowMatchesSearch,
+  buildBlockedInboxRows,
+  formatStoppedAge,
+  groupBlockedInboxRows,
+  sortBlockedInboxRows,
+  type BlockedInboxGroupBy,
+  type BlockedInboxIssueRow,
+  type BlockedInboxSort,
+} from "../lib/blockedInbox";
+import { BlockedReasonChip } from "./BlockedReasonChip";
+import { IssueGroupHeader } from "./IssueGroupHeader";
+import { IssueRow } from "./IssueRow";
+import { Identity } from "./Identity";
+import { StatusIcon } from "./StatusIcon";
+import { Button } from "@/components/ui/button";
+
+interface BlockedInboxViewProps {
+  companyId: string;
+  searchQuery: string;
+  agentNameById: ReadonlyMap<string, string>;
+  userLabelById?: ReadonlyMap<string, string>;
+  issueLinkState: unknown;
+  groupBy: BlockedInboxGroupBy;
+  sortBy: BlockedInboxSort;
+  issueFilters: IssueFilterState;
+  currentUserId: string | null;
+  liveIssueIds: ReadonlySet<string>;
+  workspaceFilterContext: IssueFilterWorkspaceContext;
+  showStatusColumn: boolean;
+  showIdentifierColumn: boolean;
+  showUpdatedColumn: boolean;
+}
+
+const BLOCKED_LIST_LIMIT = 200;
+
+export function BlockedInboxView({
+  companyId,
+  searchQuery,
+  agentNameById,
+  userLabelById,
+  issueLinkState,
+  groupBy,
+  sortBy,
+  issueFilters,
+  currentUserId,
+  liveIssueIds,
+  workspaceFilterContext,
+  showStatusColumn,
+  showIdentifierColumn,
+  showUpdatedColumn,
+}: BlockedInboxViewProps) {
+  const [collapsedVariants, setCollapsedVariants] = useState<Set<string>>(() => new Set());
+
+  const {
+    data: issues = [] as Issue[],
+    isLoading,
+    isFetching,
+    error,
+    refetch,
+  } = useQuery({
+    queryKey: queryKeys.issues.listBlockedAttention(companyId),
+    queryFn: () =>
+      issuesApi.list(companyId, {
+        attention: "blocked",
+        includeBlockedInboxAttention: true,
+        includeBlockedBy: true,
+        limit: BLOCKED_LIST_LIMIT,
+      }),
+  });
+
+  const allRows = useMemo(() => buildBlockedInboxRows(issues), [issues]);
+  const filteredRows = useMemo(
+    () => allRows.filter((row) => blockedRowMatchesSearch(row, searchQuery)),
+    [allRows, searchQuery],
+  );
+  const issueFilteredRows = useMemo(() => {
+    const visibleIssueIds = new Set(
+      applyIssueFilters(
+        filteredRows.map((row) => row.issue),
+        issueFilters,
+        currentUserId,
+        true,
+        liveIssueIds,
+        workspaceFilterContext,
+      ).map((issue) => issue.id),
+    );
+    return filteredRows.filter((row) => visibleIssueIds.has(row.issue.id));
+  }, [currentUserId, filteredRows, issueFilters, liveIssueIds, workspaceFilterContext]);
+  const sortedRows = useMemo(() => sortBlockedInboxRows(issueFilteredRows, sortBy), [issueFilteredRows, sortBy]);
+  const groups = useMemo(
+    () => groupBlockedInboxRows(issueFilteredRows, sortBy),
+    [issueFilteredRows, sortBy],
+  );
+
+  const toggleVariant = (variant: string) => {
+    setCollapsedVariants((prev) => {
+      const next = new Set(prev);
+      if (next.has(variant)) next.delete(variant);
+      else next.add(variant);
+      return next;
+    });
+  };
+
+  if (isLoading) {
+    return (
+      <div data-testid="blocked-inbox-loading" className="space-y-3" aria-busy="true">
+        {Array.from({ length: 3 }).map((_, groupIdx) => (
+          <div key={groupIdx} className="space-y-1">
+            <div className="h-4 w-40 animate-pulse rounded bg-muted/70" />
+            {Array.from({ length: 2 }).map((__, rowIdx) => (
+              <div
+                key={rowIdx}
+                className="flex items-center gap-3 border-b border-border/60 px-3 py-2.5 sm:px-4"
+              >
+                <div className="h-3.5 w-3.5 animate-pulse rounded-full bg-muted" />
+                <div className="h-4 w-16 animate-pulse rounded bg-muted/70" />
+                <div className="h-4 w-32 animate-pulse rounded-md bg-muted/70" />
+                <div className="h-4 flex-1 animate-pulse rounded bg-muted/60" />
+                <div className="hidden h-3 w-24 animate-pulse rounded bg-muted/60 sm:block" />
+              </div>
+            ))}
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  if (error) {
+    const message =
+      error instanceof Error ? error.message : "Couldn't load the Blocked tab.";
+    return (
+      <div
+        data-testid="blocked-inbox-error"
+        role="alert"
+        className="flex flex-col gap-2 rounded-md border border-amber-300/70 bg-amber-50/90 p-4 text-amber-900 dark:border-amber-500/40 dark:bg-amber-500/10 dark:text-amber-200"
+      >
+        <div className="flex items-start gap-2">
+          <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" aria-hidden="true" />
+          <div className="flex-1 space-y-1">
+            <p className="text-sm font-medium">Couldn't load the Blocked tab.</p>
+            <p className="text-xs opacity-80">
+              Other Inbox tabs still work. {message}
+            </p>
+          </div>
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="h-7 shrink-0 border-amber-400/70 bg-white/40 text-amber-900 hover:bg-white/70 dark:bg-amber-500/20 dark:text-amber-100"
+            onClick={() => void refetch()}
+            disabled={isFetching}
+          >
+            {isFetching ? "Trying…" : "Try again"}
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  if (allRows.length === 0) {
+    return (
+      <div
+        data-testid="blocked-inbox-empty"
+        className="flex flex-col items-center gap-3 rounded-lg border border-border/70 bg-card/40 px-6 py-10 text-center"
+      >
+        <span className="inline-flex h-10 w-10 items-center justify-center rounded-full bg-emerald-100 text-emerald-700 dark:bg-emerald-500/15 dark:text-emerald-300">
+          <CheckCircle2 className="h-5 w-5" aria-hidden="true" />
+        </span>
+        <div className="space-y-1">
+          <p className="text-sm font-medium text-foreground">No work is stopped.</p>
+          <p className="text-xs text-muted-foreground">
+            Issues that need a decision, recovery, or external action will appear here.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  if (groups.length === 0) {
+    return (
+      <div className="space-y-3">
+        <div
+          data-testid="blocked-inbox-no-search-results"
+          className="rounded-lg border border-border/70 bg-card/40 px-4 py-6 text-center text-sm text-muted-foreground"
+        >
+          No stopped items match your search.
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div data-testid="blocked-inbox" className="space-y-3">
+      <div className="overflow-hidden rounded-xl">
+        {groupBy === "none" ? (
+          sortedRows.map((row) => (
+            <BlockedInboxRow
+              key={row.issue.id}
+              row={row}
+              issueLinkState={issueLinkState}
+              agentNameById={agentNameById}
+              userLabelById={userLabelById}
+              showStatusColumn={showStatusColumn}
+              showIdentifierColumn={showIdentifierColumn}
+              showUpdatedColumn={showUpdatedColumn}
+            />
+          ))
+        ) : (
+          groups.map((group) => {
+            const isCollapsed = collapsedVariants.has(group.variant);
+            return (
+              <div key={group.variant} data-testid={`blocked-inbox-group-${group.variant}`}>
+                <div className="px-3 sm:px-4">
+                  <IssueGroupHeader
+                    label={`${group.label} · ${group.rows.length}`}
+                    collapsible
+                    collapsed={isCollapsed}
+                    onToggle={() => toggleVariant(group.variant)}
+                  />
+                </div>
+                {!isCollapsed && (
+                  <div>
+                    {group.rows.map((row) => (
+                      <BlockedInboxRow
+                        key={row.issue.id}
+                        row={row}
+                        issueLinkState={issueLinkState}
+                        agentNameById={agentNameById}
+                        userLabelById={userLabelById}
+                        showStatusColumn={showStatusColumn}
+                        showIdentifierColumn={showIdentifierColumn}
+                        showUpdatedColumn={showUpdatedColumn}
+                      />
+                    ))}
+                  </div>
+                )}
+              </div>
+            );
+          })
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface BlockedInboxRowProps {
+  row: BlockedInboxIssueRow;
+  issueLinkState: unknown;
+  agentNameById: ReadonlyMap<string, string>;
+  userLabelById?: ReadonlyMap<string, string>;
+  showStatusColumn: boolean;
+  showIdentifierColumn: boolean;
+  showUpdatedColumn: boolean;
+}
+
+function resolveOwnerName(
+  row: BlockedInboxIssueRow,
+  agentNameById: ReadonlyMap<string, string>,
+  userLabelById?: ReadonlyMap<string, string>,
+): { label: string | null; isAgent: boolean } {
+  const owner = row.attention.owner;
+  if (owner.label) return { label: owner.label, isAgent: owner.type === "agent" };
+  if (owner.agentId) {
+    return { label: agentNameById.get(owner.agentId) ?? null, isAgent: true };
+  }
+  if (owner.userId) {
+    return { label: userLabelById?.get(owner.userId) ?? null, isAgent: false };
+  }
+  return { label: null, isAgent: false };
+}
+
+function BlockedInboxRow({
+  row,
+  issueLinkState,
+  agentNameById,
+  userLabelById,
+  showStatusColumn,
+  showIdentifierColumn,
+  showUpdatedColumn,
+}: BlockedInboxRowProps) {
+  const { label: ownerName, isAgent } = resolveOwnerName(row, agentNameById, userLabelById);
+  const stoppedAge = formatStoppedAge(row.attention.stoppedSinceAt);
+
+  const desktopTrailing = (
+    <span className="flex shrink-0 items-center gap-3 text-xs">
+      <span
+        className="hidden w-[10.5rem] shrink-0 justify-start sm:inline-flex"
+        data-testid="blocked-row-reason-column"
+      >
+        <BlockedReasonChip
+          reason={row.attention.reason}
+          severity={row.attention.severity}
+          className="max-w-full"
+        />
+      </span>
+      {ownerName ? (
+        <span className="hidden w-[150px] min-w-0 items-center text-muted-foreground sm:inline-flex">
+          <Identity
+            name={ownerName}
+            size="xs"
+            className="max-w-full"
+          />
+        </span>
+      ) : (
+        <span className="hidden w-[150px] shrink-0 sm:inline-flex" aria-hidden="true" />
+      )}
+      {showUpdatedColumn ? (
+        <span className="hidden w-[5.75rem] text-right text-muted-foreground sm:inline" data-testid="blocked-row-age">
+          {stoppedAge}
+        </span>
+      ) : null}
+    </span>
+  );
+
+  const mobileMeta = (
+    <span className="flex flex-wrap items-center gap-x-1.5 gap-y-1 text-xs text-muted-foreground">
+      <span data-testid="blocked-row-age-mobile">{stoppedAge}</span>
+      {ownerName ? (
+        <>
+          <span aria-hidden="true">·</span>
+          <span
+            className={cn(isAgent ? "font-medium text-foreground/90" : null)}
+            data-testid="blocked-row-owner-mobile"
+          >
+            {ownerName}
+          </span>
+        </>
+      ) : null}
+    </span>
+  );
+
+  return (
+    <IssueRow
+      issue={row.issue}
+      issueLinkState={issueLinkState}
+      desktopMetaLeading={
+        <BlockedRowDesktopMeta
+          row={row}
+          showStatusColumn={showStatusColumn}
+          showIdentifierColumn={showIdentifierColumn}
+        />
+      }
+      mobileLeading={
+        <span className="flex shrink-0 items-center gap-1.5 pt-px">
+          <StatusIcon status={row.issue.status} blockerAttention={row.issue.blockerAttention} />
+        </span>
+      }
+      titleSuffix={
+        <BlockedReasonChip
+          reason={row.attention.reason}
+          severity={row.attention.severity}
+          className="ml-2 max-w-[12rem] align-middle sm:hidden"
+        />
+      }
+      mobileMeta={mobileMeta}
+      desktopTrailing={desktopTrailing}
+    />
+  );
+}
+
+function BlockedRowDesktopMeta({
+  row,
+  showStatusColumn,
+  showIdentifierColumn,
+}: {
+  row: BlockedInboxIssueRow;
+  showStatusColumn: boolean;
+  showIdentifierColumn: boolean;
+}) {
+  const identifier = row.issue.identifier ?? row.issue.id.slice(0, 8);
+  return (
+    <span className="hidden shrink-0 items-center gap-2 sm:inline-flex">
+      {showStatusColumn ? <StatusIcon status={row.issue.status} blockerAttention={row.issue.blockerAttention} /> : null}
+      {showIdentifierColumn ? <span className="font-mono text-xs text-muted-foreground">{identifier}</span> : null}
+    </span>
+  );
+}
diff --git a/ui/src/components/BlockedReasonChip.test.tsx b/ui/src/components/BlockedReasonChip.test.tsx
new file mode 100644
index 00000000..f056914c
--- /dev/null
+++ b/ui/src/components/BlockedReasonChip.test.tsx
@@ -0,0 +1,85 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { BlockedReasonChip } from "./BlockedReasonChip";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("BlockedReasonChip", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it("renders the canonical group label and exposes severity via aria-label", () => {
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        <BlockedReasonChip reason="pending_board_decision" severity="high" />,
+      );
+    });
+    const chip = container.querySelector('[data-testid="blocked-reason-chip"]');
+    expect(chip).not.toBeNull();
+    expect(chip?.getAttribute("data-variant")).toBe("needs_decision");
+    expect(chip?.getAttribute("data-severity")).toBe("high");
+    expect(chip?.getAttribute("aria-label")).toBe("Reason: Needs decision, severity high");
+    expect(chip?.textContent).toContain("Needs decision");
+    act(() => {
+      root.unmount();
+    });
+  });
+
+  it("includes a severity dot for critical and high but not medium/low", () => {
+    const cases: Array<["critical" | "high" | "medium" | "low", boolean]> = [
+      ["critical", true],
+      ["high", true],
+      ["medium", false],
+      ["low", false],
+    ];
+    for (const [severity, hasDot] of cases) {
+      const local = document.createElement("div");
+      document.body.appendChild(local);
+      const root = createRoot(local);
+      act(() => {
+        root.render(<BlockedReasonChip reason="blocked_chain_stalled" severity={severity} />);
+      });
+      const chip = local.querySelector('[data-testid="blocked-reason-chip"]');
+      const dot = chip?.querySelector('[aria-hidden="true"]');
+      if (hasDot) {
+        expect(dot).not.toBeNull();
+      } else {
+        // The first inner span (icon) is always aria-hidden, but the dot is the first child.
+        // Distinguish by class name presence of bg-red-500/bg-orange-500.
+        const classy = chip?.querySelector('span[class*="bg-red-500"], span[class*="bg-orange-500"]');
+        expect(classy).toBeNull();
+      }
+      act(() => {
+        root.unmount();
+      });
+      local.remove();
+    }
+  });
+
+  it("hides the icon when compact is true", () => {
+    const root = createRoot(container);
+    act(() => {
+      root.render(
+        <BlockedReasonChip reason="external_owner_action" severity="low" compact />,
+      );
+    });
+    const chip = container.querySelector('[data-testid="blocked-reason-chip"]');
+    const svg = chip?.querySelector("svg");
+    expect(svg).toBeNull();
+    act(() => {
+      root.unmount();
+    });
+  });
+});
diff --git a/ui/src/components/BlockedReasonChip.tsx b/ui/src/components/BlockedReasonChip.tsx
new file mode 100644
index 00000000..4efddc6d
--- /dev/null
+++ b/ui/src/components/BlockedReasonChip.tsx
@@ -0,0 +1,82 @@
+import { AlertTriangle, Clock, Pause, User, Wrench } from "lucide-react";
+import type { ComponentType } from "react";
+import type { IssueBlockedInboxSeverity } from "@paperclipai/shared";
+import { cn } from "../lib/utils";
+import {
+  blockedReasonVariant,
+  blockedVariantLabel,
+  type BlockedReasonVariant,
+} from "../lib/blockedInbox";
+import type { IssueBlockedInboxReason } from "@paperclipai/shared";
+
+interface BlockedReasonChipProps {
+  reason: IssueBlockedInboxReason;
+  severity: IssueBlockedInboxSeverity;
+  compact?: boolean;
+  className?: string;
+}
+
+type IconComponent = ComponentType<{ className?: string; "aria-hidden"?: boolean | "true" | "false" }>;
+
+const VARIANT_STYLES: Record<BlockedReasonVariant, string> = {
+  needs_decision:
+    "border-violet-300/70 bg-violet-50 text-violet-800 dark:border-violet-500/30 dark:bg-violet-500/10 dark:text-violet-300",
+  recovery_required:
+    "border-cyan-300/70 bg-cyan-50 text-cyan-800 dark:border-cyan-500/30 dark:bg-cyan-500/10 dark:text-cyan-300",
+  stalled:
+    "border-amber-400/70 bg-amber-100 text-amber-900 dark:border-amber-500/40 dark:bg-amber-500/15 dark:text-amber-200",
+  needs_attention:
+    "border-amber-300/70 bg-amber-50 text-amber-800 dark:border-amber-500/40 dark:bg-amber-500/10 dark:text-amber-300",
+  external_wait:
+    "border-slate-300 bg-slate-50 text-slate-700 dark:border-slate-500/30 dark:bg-slate-500/15 dark:text-slate-300",
+  owner_paused:
+    "border-red-300/70 bg-red-50 text-red-800 dark:border-red-500/30 dark:bg-red-500/10 dark:text-red-300",
+};
+
+const VARIANT_ICONS: Record<BlockedReasonVariant, IconComponent> = {
+  needs_decision: Clock,
+  recovery_required: Wrench,
+  stalled: AlertTriangle,
+  needs_attention: AlertTriangle,
+  external_wait: User,
+  owner_paused: Pause,
+};
+
+const SEVERITY_DOT: Partial<Record<IssueBlockedInboxSeverity, string>> = {
+  critical: "bg-red-500",
+  high: "bg-orange-500",
+};
+
+export function BlockedReasonChip({
+  reason,
+  severity,
+  compact = false,
+  className,
+}: BlockedReasonChipProps) {
+  const variant = blockedReasonVariant(reason);
+  const label = blockedVariantLabel(variant);
+  const Icon = VARIANT_ICONS[variant];
+  const dotClass = SEVERITY_DOT[severity];
+  return (
+    <span
+      data-testid="blocked-reason-chip"
+      data-variant={variant}
+      data-severity={severity}
+      aria-label={`Reason: ${label}, severity ${severity}`}
+      className={cn(
+        "inline-flex shrink-0 items-center gap-1 rounded-md border px-2 py-0.5 text-[10px] font-medium leading-tight sm:text-[11px]",
+        VARIANT_STYLES[variant],
+        className,
+      )}
+    >
+      {dotClass ? (
+        <span
+          aria-hidden="true"
+          className={cn("inline-block h-1.5 w-1.5 shrink-0 rounded-full", dotClass)}
+        />
+      ) : null}
+      {compact ? null : <Icon className="h-3 w-3 shrink-0" aria-hidden="true" />}
+      <span className="truncate">{label}</span>
+    </span>
+  );
+}
diff --git a/ui/src/components/IssueBlockedNotice.test.tsx b/ui/src/components/IssueBlockedNotice.test.tsx
index 725974bc..4dad91b1 100644
--- a/ui/src/components/IssueBlockedNotice.test.tsx
+++ b/ui/src/components/IssueBlockedNotice.test.tsx
@@ -2,8 +2,10 @@
 
 import { act } from "react";
 import { createRoot } from "react-dom/client";
-import type { AnchorHTMLAttributes, ReactElement } from "react";
+import type { AnchorHTMLAttributes, ReactElement, ReactNode } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { MemoryRouter } from "react-router-dom";
 import { IssueBlockedNotice } from "./IssueBlockedNotice";
 
 vi.mock("@/lib/router", () => ({
@@ -27,11 +29,20 @@ afterEach(() => {
   container = null;
 });
 
+function withProviders(node: ReactNode) {
+  const client = new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: 0, staleTime: 0 } } });
+  return (
+    <MemoryRouter>
+      <QueryClientProvider client={client}>{node}</QueryClientProvider>
+    </MemoryRouter>
+  );
+}
+
 function render(element: ReactElement) {
   container = document.createElement("div");
   document.body.appendChild(container);
   root = createRoot(container);
-  act(() => root?.render(element));
+  act(() => root?.render(withProviders(element)));
   return container;
 }
 
@@ -102,4 +113,58 @@ describe("IssueBlockedNotice", () => {
 
     expect(node.textContent).toBe("");
   });
+
+  it("renders a recovery indicator on a blocker chip when the blocker has an active recovery action", () => {
+    const node = render(
+      <IssueBlockedNotice
+        issueStatus="blocked"
+        blockers={[
+          {
+            id: "blocker-1",
+            identifier: "PAP-123",
+            title: "Build still red",
+            status: "in_progress",
+            priority: "medium",
+            assigneeAgentId: null,
+            assigneeUserId: null,
+            activeRecoveryAction: {
+              id: "rec-1",
+              companyId: "co-1",
+              sourceIssueId: "blocker-1",
+              recoveryIssueId: null,
+              kind: "missing_disposition",
+              status: "active",
+              ownerType: "agent",
+              ownerAgentId: "agent-cto",
+              ownerUserId: null,
+              previousOwnerAgentId: null,
+              returnOwnerAgentId: null,
+              cause: "successful_run_missing_state",
+              fingerprint: "fp-1",
+              evidence: {},
+              nextAction: "choose disposition",
+              wakePolicy: { type: "wake_owner" },
+              monitorPolicy: null,
+              attemptCount: 1,
+              maxAttempts: 3,
+              timeoutAt: null,
+              lastAttemptAt: null,
+              outcome: null,
+              resolutionNote: null,
+              resolvedAt: null,
+              createdAt: "2026-05-01T00:00:00.000Z",
+              updatedAt: "2026-05-01T00:00:00.000Z",
+            },
+          },
+        ]}
+      />,
+    );
+
+    const indicator = node.querySelector(
+      '[data-testid="issue-blocked-notice-recovery-indicator"]',
+    );
+    expect(indicator).not.toBeNull();
+    expect(indicator?.getAttribute("data-recovery-state")).toBe("needed");
+    expect(indicator?.textContent).toContain("Recovery needed");
+  });
 });
diff --git a/ui/src/components/IssueBlockedNotice.tsx b/ui/src/components/IssueBlockedNotice.tsx
index 2fa83d38..42f3cfa8 100644
--- a/ui/src/components/IssueBlockedNotice.tsx
+++ b/ui/src/components/IssueBlockedNotice.tsx
@@ -1,9 +1,38 @@
-import type { IssueBlockerAttention, IssueRelationIssueSummary, SuccessfulRunHandoffState } from "@paperclipai/shared";
+import type {
+  IssueBlockerAttention,
+  IssueRecoveryAction,
+  IssueRelationIssueSummary,
+  SuccessfulRunHandoffState,
+} from "@paperclipai/shared";
 import { AlertTriangle, Flag } from "lucide-react";
 import { Link } from "@/lib/router";
 import { createIssueDetailPath } from "../lib/issueDetailBreadcrumb";
 import { IssueLinkQuicklook } from "./IssueLinkQuicklook";
 import { isAssignedBacklogBlocker } from "../lib/issue-blockers";
+import {
+  deriveActiveRecoveryDisplayState,
+  RECOVERY_CHIP_DEFAULT_TONE,
+} from "../lib/recovery-display";
+
+function BlockerRecoveryIndicator({ action }: { action: IssueRecoveryAction }) {
+  const state = deriveActiveRecoveryDisplayState(action);
+  if (!state) return null;
+  const tone = RECOVERY_CHIP_DEFAULT_TONE[state];
+  const Icon = tone.icon;
+  return (
+    <span
+      data-testid="issue-blocked-notice-recovery-indicator"
+      data-recovery-state={state}
+      role="status"
+      aria-label={tone.label}
+      title={`${tone.label} — open the source issue to act.`}
+      className={`inline-flex shrink-0 items-center gap-0.5 rounded-full border px-1.5 py-0.5 text-[10px] font-medium ${tone.className}`}
+    >
+      <Icon className="h-2.5 w-2.5" aria-hidden />
+      {tone.label}
+    </span>
+  );
+}
 
 export function IssueBlockedNotice({
   issueStatus,
@@ -69,6 +98,7 @@ export function IssueBlockedNotice({
 
   const renderBlockerChip = (blocker: IssueRelationIssueSummary) => {
     const issuePathId = blocker.identifier ?? blocker.id;
+    const recoveryAction = blocker.activeRecoveryAction ?? null;
     return (
       <IssueLinkQuicklook
         key={blocker.id}
@@ -80,6 +110,7 @@ export function IssueBlockedNotice({
         <span className="max-w-[18rem] truncate font-sans text-[11px] text-amber-800 dark:text-amber-200">
           {blocker.title}
         </span>
+        {recoveryAction ? <BlockerRecoveryIndicator action={recoveryAction} /> : null}
       </IssueLinkQuicklook>
     );
   };
diff --git a/ui/src/components/IssueChatThread.test.tsx b/ui/src/components/IssueChatThread.test.tsx
index 3918b39b..3ad29546 100644
--- a/ui/src/components/IssueChatThread.test.tsx
+++ b/ui/src/components/IssueChatThread.test.tsx
@@ -346,6 +346,39 @@ describe("IssueChatThread", () => {
     });
   });
 
+  it("renders footer content inside the thread viewport before the bottom anchor", () => {
+    const root = createRoot(container);
+
+    act(() => {
+      root.render(
+        <MemoryRouter>
+          <IssueChatThread
+            comments={[]}
+            linkedRuns={[]}
+            timelineEvents={[]}
+            liveRuns={[]}
+            onAdd={async () => {}}
+            showComposer={false}
+            enableLiveTranscriptPolling={false}
+            footer={<div>Sibling footer</div>}
+          />
+        </MemoryRouter>,
+      );
+    });
+
+    const viewport = container.querySelector('[data-testid="thread-viewport"]');
+    const footer = container.querySelector('[data-testid="issue-chat-thread-footer"]');
+    expect(viewport).not.toBeNull();
+    expect(footer).not.toBeNull();
+    expect(footer?.textContent).toBe("Sibling footer");
+    expect(footer?.parentElement).toBe(viewport);
+    expect(footer?.nextElementSibling?.textContent).toBe("");
+
+    act(() => {
+      root.unmount();
+    });
+  });
+
   it("renders the composer in planning mode when the issue is in planning mode", () => {
     const root = createRoot(container);
 
diff --git a/ui/src/components/IssueChatThread.tsx b/ui/src/components/IssueChatThread.tsx
index 36cf2eb7..b25eb39f 100644
--- a/ui/src/components/IssueChatThread.tsx
+++ b/ui/src/components/IssueChatThread.tsx
@@ -36,6 +36,7 @@ import type {
   FeedbackVoteValue,
   IssueAttachment,
   IssueBlockerAttention,
+  IssueRecoveryAction,
   IssueRelationIssueSummary,
   SuccessfulRunHandoffState,
   IssueWorkMode,
@@ -134,6 +135,7 @@ import { Textarea } from "@/components/ui/textarea";
 import { AlertTriangle, ArrowRight, Brain, Check, ChevronDown, ClipboardList, Copy, Hammer, Loader2, MoreHorizontal, Paperclip, PauseCircle, Search, Square, ThumbsDown, ThumbsUp } from "lucide-react";
 import { IssueBlockedNotice } from "./IssueBlockedNotice";
 import { IssueAssignedBacklogNotice } from "./IssueAssignedBacklogNotice";
+import { IssueRecoveryActionCard, type RecoveryResolveOutcome } from "./IssueRecoveryActionCard";
 
 interface IssueChatMessageContext {
   feedbackDataSharingPreference: FeedbackDataSharingPreference;
@@ -297,6 +299,14 @@ interface IssueChatThreadProps {
   blockedBy?: IssueRelationIssueSummary[];
   blockerAttention?: IssueBlockerAttention | null;
   successfulRunHandoff?: SuccessfulRunHandoffState | null;
+  recoveryAction?: IssueRecoveryAction | null;
+  onResolveRecoveryAction?: (outcome: RecoveryResolveOutcome) => void;
+  canFalsePositiveRecoveryAction?: boolean;
+  legacyRecoverySourceIssue?: {
+    identifier: string | null;
+    href: string;
+    title?: string | null;
+  } | null;
   assigneeUserId?: string | null;
   onResumeFromBacklog?: () => Promise<void> | void;
   resumeFromBacklogPending?: boolean;
@@ -332,6 +342,7 @@ interface IssueChatThreadProps {
   showComposer?: boolean;
   showJumpToLatest?: boolean;
   emptyMessage?: string;
+  footer?: ReactNode;
   variant?: "full" | "embedded";
   enableLiveTranscriptPolling?: boolean;
   transcriptsByRunId?: ReadonlyMap<string, readonly IssueChatTranscriptEntry[]>;
@@ -3609,6 +3620,10 @@ export function IssueChatThread({
   blockedBy = [],
   blockerAttention = null,
   successfulRunHandoff = null,
+  recoveryAction = null,
+  onResolveRecoveryAction,
+  canFalsePositiveRecoveryAction = false,
+  legacyRecoverySourceIssue = null,
   companyId,
   projectId,
   issueStatus,
@@ -3636,6 +3651,7 @@ export function IssueChatThread({
   showComposer = true,
   showJumpToLatest,
   emptyMessage,
+  footer,
   variant = "full",
   enableLiveTranscriptPolling = true,
   transcriptsByRunId,
@@ -4244,11 +4260,49 @@ export function IssueChatThread({
                     onResume={onResumeFromBacklog}
                     resuming={resumeFromBacklogPending}
                   />
+                  {recoveryAction ? (
+                    <IssueRecoveryActionCard
+                      action={recoveryAction}
+                      agentMap={agentMap}
+                      onResolve={onResolveRecoveryAction}
+                      canFalsePositive={canFalsePositiveRecoveryAction}
+                    />
+                  ) : null}
+                  {legacyRecoverySourceIssue ? (
+                    <SystemNotice
+                      tone="info"
+                      label="Legacy recovery issue"
+                      body={
+                        <span>
+                          Legacy recovery issue. Newer recovery actions live on the source issue
+                          {legacyRecoverySourceIssue.identifier ? (
+                            <>
+                              {" — "}
+                              <Link
+                                to={legacyRecoverySourceIssue.href}
+                                className="underline-offset-2 hover:underline"
+                              >
+                                {legacyRecoverySourceIssue.identifier}
+                                {legacyRecoverySourceIssue.title ? (
+                                  <span className="text-muted-foreground">
+                                    {" "}
+                                    — {legacyRecoverySourceIssue.title}
+                                  </span>
+                                ) : null}
+                              </Link>
+                            </>
+                          ) : (
+                            "."
+                          )}
+                        </span>
+                      }
+                    />
+                  ) : null}
                   <IssueBlockedNotice
                     issueStatus={issueStatus}
                     blockers={unresolvedBlockers}
                     blockerAttention={blockerAttention}
-                    successfulRunHandoff={successfulRunHandoff}
+                    successfulRunHandoff={recoveryAction ? null : successfulRunHandoff}
                     agentName={
                       successfulRunHandoff?.assigneeAgentId
                         ? agentMap?.get(successfulRunHandoff.assigneeAgentId)?.name ?? null
@@ -4258,6 +4312,7 @@ export function IssueChatThread({
                   <IssueAssigneePausedNotice agent={assignedAgent} />
                 </div>
               ) : null}
+              {footer ? <div data-testid="issue-chat-thread-footer">{footer}</div> : null}
               <div ref={bottomAnchorRef} />
               {showComposer ? (
                 <div
diff --git a/ui/src/components/IssueLinkQuicklook.test.tsx b/ui/src/components/IssueLinkQuicklook.test.tsx
new file mode 100644
index 00000000..95cad42e
--- /dev/null
+++ b/ui/src/components/IssueLinkQuicklook.test.tsx
@@ -0,0 +1,136 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { MemoryRouter } from "react-router-dom";
+import type { Issue } from "@paperclipai/shared";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { IssueLinkQuicklook } from "./IssueLinkQuicklook";
+
+const mockIssuesApiGet = vi.hoisted(() => vi.fn());
+
+vi.mock("@/api/issues", () => ({
+  issuesApi: {
+    get: mockIssuesApiGet,
+  },
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function createIssue(overrides: Partial<Issue> = {}): Issue {
+  return {
+    id: "issue-1",
+    identifier: "PAP-1",
+    companyId: "company-1",
+    projectId: null,
+    projectWorkspaceId: null,
+    goalId: null,
+    parentId: null,
+    title: "Quicklook title",
+    description: "Quicklook description",
+    status: "todo",
+    priority: "medium",
+    assigneeAgentId: null,
+    assigneeUserId: null,
+    createdByAgentId: null,
+    createdByUserId: null,
+    issueNumber: 1,
+    requestDepth: 0,
+    billingCode: null,
+    assigneeAdapterOverrides: null,
+    executionWorkspaceId: null,
+    executionWorkspacePreference: null,
+    executionWorkspaceSettings: null,
+    checkoutRunId: null,
+    executionRunId: null,
+    executionAgentNameKey: null,
+    executionLockedAt: null,
+    startedAt: null,
+    completedAt: null,
+    cancelledAt: null,
+    hiddenAt: null,
+    createdAt: new Date("2026-05-01T00:00:00.000Z"),
+    updatedAt: new Date("2026-05-01T00:00:00.000Z"),
+    labels: [],
+    labelIds: [],
+    myLastTouchAt: null,
+    lastExternalCommentAt: null,
+    isUnreadForMe: false,
+    workMode: "standard",
+    ...overrides,
+  };
+}
+
+describe("IssueLinkQuicklook", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+        },
+      },
+    });
+    mockIssuesApiGet.mockResolvedValue(createIssue());
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    queryClient.clear();
+    container.remove();
+    vi.useRealTimers();
+    vi.clearAllMocks();
+  });
+
+  it("keeps portaled quicklook links mounted until after blur click handling", () => {
+    const issue = createIssue();
+
+    act(() => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <MemoryRouter>
+            <IssueLinkQuicklook
+              issuePathId="PAP-1"
+              issuePrefetch={issue}
+              to="/companies/company-1/issues/PAP-1"
+            >
+              PAP-1
+            </IssueLinkQuicklook>
+          </MemoryRouter>
+        </QueryClientProvider>,
+      );
+    });
+
+    const trigger = container.querySelector("a") as HTMLAnchorElement | null;
+    expect(trigger).not.toBeNull();
+
+    act(() => {
+      trigger?.focus();
+    });
+
+    expect(document.body.textContent).toContain("Quicklook title");
+
+    act(() => {
+      trigger?.blur();
+    });
+
+    expect(document.body.textContent).toContain("Quicklook title");
+
+    act(() => {
+      vi.runOnlyPendingTimers();
+    });
+
+    expect(document.body.textContent).not.toContain("Quicklook title");
+  });
+});
diff --git a/ui/src/components/IssueLinkQuicklook.tsx b/ui/src/components/IssueLinkQuicklook.tsx
index 16b16822..65a07b1f 100644
--- a/ui/src/components/IssueLinkQuicklook.tsx
+++ b/ui/src/components/IssueLinkQuicklook.tsx
@@ -75,6 +75,8 @@ export const IssueLinkQuicklook = React.forwardRef<
     issuePathId: string;
     disableIssueQuicklook?: boolean;
     issuePrefetch?: Issue | null;
+    issueQuicklookSide?: React.ComponentProps<typeof PopoverContent>["side"];
+    issueQuicklookAlign?: React.ComponentProps<typeof PopoverContent>["align"];
   }
 >(function IssueLinkQuicklookImpl(
   {
@@ -85,10 +87,13 @@ export const IssueLinkQuicklook = React.forwardRef<
     state,
     disableIssueQuicklook = false,
     issuePrefetch = null,
+    issueQuicklookSide = "top",
+    issueQuicklookAlign = "start",
     onClick,
     onClickCapture,
     onMouseEnter,
     onFocus,
+    onBlur,
     onTouchStart,
     ...props
   },
@@ -119,8 +124,14 @@ export const IssueLinkQuicklook = React.forwardRef<
       }}
       onFocus={(event) => {
         handlePrefetch();
+        setOpen(true);
         onFocus?.(event);
       }}
+      onBlur={(event) => {
+        // Let clicks inside the portaled quicklook content finish before closing.
+        setTimeout(() => setOpen(false), 0);
+        onBlur?.(event);
+      }}
       onTouchStart={(event) => {
         handlePrefetch();
         onTouchStart?.(event);
@@ -157,8 +168,8 @@ export const IssueLinkQuicklook = React.forwardRef<
       </PopoverTrigger>
       <PopoverContent
         className="w-72 p-3"
-        side="top"
-        align="start"
+        side={issueQuicklookSide}
+        align={issueQuicklookAlign}
         onMouseEnter={() => setOpen(true)}
         onMouseLeave={() => setOpen(false)}
         onOpenAutoFocus={(event) => event.preventDefault()}
diff --git a/ui/src/components/IssueRecoveryActionCard.test.tsx b/ui/src/components/IssueRecoveryActionCard.test.tsx
new file mode 100644
index 00000000..56953732
--- /dev/null
+++ b/ui/src/components/IssueRecoveryActionCard.test.tsx
@@ -0,0 +1,218 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import type { AnchorHTMLAttributes, ReactElement } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Agent, IssueRecoveryAction } from "@paperclipai/shared";
+import { IssueRecoveryActionCard, deriveRecoveryCardState } from "./IssueRecoveryActionCard";
+
+vi.mock("@/lib/router", () => ({
+  Link: ({ children, to, ...props }: AnchorHTMLAttributes<HTMLAnchorElement> & { to: string }) => (
+    <a href={to} {...props}>{children}</a>
+  ),
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+let root: ReturnType<typeof createRoot> | null = null;
+let container: HTMLDivElement | null = null;
+
+afterEach(() => {
+  if (root) {
+    act(() => root?.unmount());
+  }
+  root = null;
+  container?.remove();
+  container = null;
+});
+
+function render(element: ReactElement) {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  act(() => root?.render(element));
+  return container;
+}
+
+function click(element: Element | null) {
+  if (!element) throw new Error("Expected element to exist");
+  act(() => {
+    element.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+  });
+}
+
+const ownerAgent: Agent = {
+  id: "11111111-1111-1111-1111-111111111111",
+  companyId: "company-1",
+  name: "ClaudeCoder",
+  role: "engineer",
+  status: "idle",
+  adapterType: "claude_local",
+  adapterConfig: {},
+  runtimeConfig: {},
+  permissions: {},
+  urlKey: "claudecoder",
+} as unknown as Agent;
+
+const returnAgent: Agent = {
+  ...ownerAgent,
+  id: "22222222-2222-2222-2222-222222222222",
+  name: "CodexCoder",
+  urlKey: "codexcoder",
+} as Agent;
+
+function buildAction(overrides: Partial<IssueRecoveryAction> = {}): IssueRecoveryAction {
+  return {
+    id: "00000000-0000-0000-0000-0000000000aa",
+    companyId: "company-1",
+    sourceIssueId: "00000000-0000-0000-0000-0000000000ff",
+    recoveryIssueId: null,
+    kind: "missing_disposition",
+    status: "active",
+    ownerType: "agent",
+    ownerAgentId: ownerAgent.id,
+    ownerUserId: null,
+    previousOwnerAgentId: returnAgent.id,
+    returnOwnerAgentId: returnAgent.id,
+    cause: "missing_disposition",
+    fingerprint: "fp",
+    evidence: {
+      summary: "Run finished but no disposition was chosen.",
+      sourceRunId: "7accd7a4-c9ca-4db2-9233-3228a037cc09",
+    },
+    nextAction: "Choose and record a valid issue disposition.",
+    wakePolicy: { type: "wake_owner" },
+    monitorPolicy: null,
+    attemptCount: 1,
+    maxAttempts: 3,
+    timeoutAt: null,
+    lastAttemptAt: "2026-05-09T19:30:00.000Z",
+    outcome: null,
+    resolutionNote: null,
+    resolvedAt: null,
+    createdAt: "2026-05-09T19:30:00.000Z",
+    updatedAt: "2026-05-09T19:30:00.000Z",
+    ...overrides,
+  };
+}
+
+describe("deriveRecoveryCardState", () => {
+  it("maps active missing_disposition to needed", () => {
+    expect(deriveRecoveryCardState(buildAction())).toBe("needed");
+  });
+
+  it("maps active_run_watchdog to observe_only", () => {
+    expect(deriveRecoveryCardState(buildAction({ kind: "active_run_watchdog" }))).toBe("observe_only");
+  });
+
+  it("maps escalated status to escalated", () => {
+    expect(deriveRecoveryCardState(buildAction({ status: "escalated" }))).toBe("escalated");
+  });
+
+  it("maps resolved/cancelled to resolved", () => {
+    expect(deriveRecoveryCardState(buildAction({ status: "resolved" }))).toBe("resolved");
+    expect(deriveRecoveryCardState(buildAction({ status: "cancelled" }))).toBe("resolved");
+  });
+});
+
+describe("IssueRecoveryActionCard", () => {
+  it("renders required fields and an aria-label naming the state", () => {
+    const node = render(
+      <IssueRecoveryActionCard
+        action={buildAction()}
+        agentMap={new Map([
+          [ownerAgent.id, ownerAgent],
+          [returnAgent.id, returnAgent],
+        ])}
+        onResolve={() => {}}
+      />,
+    );
+    const section = node.querySelector("section[aria-label]");
+    expect(section?.getAttribute("aria-label")).toBe("Recovery action: needed");
+    expect(node.textContent).toContain("RECOVERY NEEDED");
+    expect(node.textContent).toContain("Missing Disposition");
+    expect(node.textContent).not.toContain("missing_disposition");
+    expect(node.textContent).toContain("This issue's run finished, but no next step was chosen.");
+    expect(node.textContent).toContain("ClaudeCoder");
+    expect(node.textContent).toContain("CodexCoder");
+    expect(node.textContent).toContain("Choose and record a valid issue disposition.");
+    expect(node.textContent).toContain("Corrective wake queued");
+  });
+
+  it("falls back to em dash when wake policy is absent", () => {
+    const node = render(
+      <IssueRecoveryActionCard action={buildAction({ wakePolicy: null })} />,
+    );
+    expect(node.textContent).toContain("—");
+  });
+
+  it("renders observe_only tone for active_run_watchdog", () => {
+    const node = render(
+      <IssueRecoveryActionCard action={buildAction({ kind: "active_run_watchdog" })} />,
+    );
+    const section = node.querySelector("section[aria-label]");
+    expect(section?.getAttribute("aria-label")).toBe("Recovery action: observing active run");
+    expect(node.textContent).toContain("OBSERVING ACTIVE RUN");
+  });
+
+  it("renders the resolved label and outcome when resolved", () => {
+    const node = render(
+      <IssueRecoveryActionCard action={buildAction({ status: "resolved", outcome: "restored", resolvedAt: "2026-05-09T19:35:00.000Z" })} />,
+    );
+    expect(node.textContent).toContain("RECOVERY RESOLVED");
+    expect(node.textContent).toContain("Resolved as restored");
+  });
+
+  it("calls resolve with done and does not offer delegated recovery", () => {
+    const onResolve = vi.fn();
+    const node = render(
+      <IssueRecoveryActionCard action={buildAction()} onResolve={onResolve} />,
+    );
+    click(node.querySelector("[data-testid='recovery-action-resolve-trigger']"));
+
+    expect(document.body.textContent).toContain("Mark issue done");
+    expect(document.body.textContent).not.toContain("Mark blocked");
+    expect(document.body.textContent).not.toContain("Delegate follow-up issue");
+    click([...document.body.querySelectorAll("button")].find((button) => button.textContent?.includes("Mark issue done")) ?? null);
+
+    expect(onResolve).toHaveBeenCalledWith("done");
+  });
+
+  it("does not offer blocked recovery resolution without a blocker selection flow", () => {
+    const node = render(
+      <IssueRecoveryActionCard action={buildAction()} onResolve={() => {}} canFalsePositive />,
+    );
+    click(node.querySelector("[data-testid='recovery-action-resolve-trigger']"));
+
+    expect(document.body.textContent).toContain("Mark issue done");
+    expect(document.body.textContent).toContain("Send for review");
+    expect(document.body.textContent).toContain("False positive, done");
+    expect(document.body.textContent).toContain("False positive, review");
+    expect(document.body.textContent).not.toContain("Mark blocked");
+  });
+
+  it("hides false-positive options unless canFalsePositive is set", () => {
+    const first = render(
+      <IssueRecoveryActionCard action={buildAction()} onResolve={() => {}} />,
+    );
+    click(first.querySelector("[data-testid='recovery-action-resolve-trigger']"));
+    expect(document.body.textContent).not.toContain("False positive");
+
+    act(() => root?.unmount());
+    root = null;
+    container?.remove();
+    container = null;
+
+    const onResolve = vi.fn();
+    const second = render(
+      <IssueRecoveryActionCard action={buildAction()} onResolve={onResolve} canFalsePositive />,
+    );
+    click(second.querySelector("[data-testid='recovery-action-resolve-trigger']"));
+    expect(document.body.textContent).toContain("False positive, done");
+    expect(document.body.textContent).toContain("False positive, review");
+    click([...document.body.querySelectorAll("button")].find((button) => button.textContent?.includes("False positive, done")) ?? null);
+    expect(onResolve).toHaveBeenCalledWith("false_positive_done");
+  });
+});
diff --git a/ui/src/components/IssueRecoveryActionCard.tsx b/ui/src/components/IssueRecoveryActionCard.tsx
new file mode 100644
index 00000000..88fdcebb
--- /dev/null
+++ b/ui/src/components/IssueRecoveryActionCard.tsx
@@ -0,0 +1,537 @@
+import { useMemo } from "react";
+import type {
+  Agent,
+  IssueRecoveryAction,
+  IssueRecoveryActionKind,
+  IssueRecoveryActionOutcome,
+  IssueRecoveryActionStatus,
+} from "@paperclipai/shared";
+import { Eye, OctagonAlert, RefreshCw, Sparkles, TriangleAlert } from "lucide-react";
+import { Link } from "@/lib/router";
+import { Button } from "@/components/ui/button";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { agentUrl } from "@/lib/utils";
+import { cn } from "@/lib/utils";
+import {
+  deriveRecoveryDisplayState,
+  type RecoveryDisplayState,
+} from "@/lib/recovery-display";
+
+export type RecoveryCardCardState = RecoveryDisplayState;
+export const deriveRecoveryCardState = deriveRecoveryDisplayState;
+
+export type RecoveryResolveOutcome =
+  | "done"
+  | "in_review"
+  | "false_positive_done"
+  | "false_positive_in_review";
+
+export interface IssueRecoveryActionCardProps {
+  action: IssueRecoveryAction;
+  agentMap?: ReadonlyMap<string, Agent>;
+  /** Preferred state hint (e.g. observe_only when watchdog tone is requested). Falls back to derived state. */
+  forcedState?: RecoveryCardCardState;
+  /** Optional click handler for resolve menu actions. If omitted, the buttons are not rendered. */
+  onResolve?: (outcome: RecoveryResolveOutcome) => void;
+  /** Whether the viewer can run destructive board-only actions (e.g. false-positive dismissal). */
+  canFalsePositive?: boolean;
+  className?: string;
+}
+
+const KIND_LABEL: Record<IssueRecoveryActionKind, string> = {
+  missing_disposition: "Missing Disposition",
+  stranded_assigned_issue: "Stranded Issue",
+  active_run_watchdog: "Active Watchdog",
+  issue_graph_liveness: "Graph Liveness",
+};
+
+const KIND_HEADLINE: Record<IssueRecoveryActionKind, string> = {
+  missing_disposition: "This issue's run finished, but no next step was chosen.",
+  stranded_assigned_issue:
+    "Paperclip retried this issue's last run and it still has no live execution path.",
+  active_run_watchdog:
+    "The active run has been silent. Recovery is observing without interrupting it.",
+  issue_graph_liveness:
+    "Paperclip detected this issue lost a live action path. A recovery owner needs to act.",
+};
+
+const STATE_TONE: Record<RecoveryCardCardState, {
+  label: string;
+  containerClass: string;
+  iconWrapClass: string;
+  iconClass: string;
+  labelClass: string;
+  Icon: typeof TriangleAlert;
+  divider: string;
+}> = {
+  needed: {
+    label: "RECOVERY NEEDED",
+    containerClass:
+      "border-amber-300/70 bg-amber-50/85 text-amber-950 dark:border-amber-500/40 dark:bg-amber-500/10 dark:text-amber-100",
+    iconWrapClass: "bg-amber-100 text-amber-800 dark:bg-amber-500/20 dark:text-amber-200",
+    iconClass: "text-amber-700 dark:text-amber-300",
+    labelClass: "text-amber-900 dark:text-amber-200",
+    Icon: TriangleAlert,
+    divider: "border-amber-300/60 dark:border-amber-500/30",
+  },
+  in_progress: {
+    label: "RECOVERY IN PROGRESS",
+    containerClass:
+      "border-sky-300/70 bg-sky-50/80 text-sky-950 dark:border-sky-500/40 dark:bg-sky-500/10 dark:text-sky-100",
+    iconWrapClass: "bg-sky-100 text-sky-800 dark:bg-sky-500/20 dark:text-sky-200",
+    iconClass: "text-sky-700 dark:text-sky-300",
+    labelClass: "text-sky-900 dark:text-sky-200",
+    Icon: RefreshCw,
+    divider: "border-sky-300/60 dark:border-sky-500/30",
+  },
+  observe_only: {
+    label: "OBSERVING ACTIVE RUN",
+    containerClass:
+      "border-border bg-muted/40 text-foreground dark:bg-muted/20",
+    iconWrapClass: "bg-muted text-foreground/70",
+    iconClass: "text-muted-foreground",
+    labelClass: "text-muted-foreground",
+    Icon: Eye,
+    divider: "border-border/70",
+  },
+  escalated: {
+    label: "RECOVERY ESCALATED",
+    containerClass:
+      "border-red-400/60 bg-red-50/85 text-red-950 dark:border-red-500/40 dark:bg-red-500/10 dark:text-red-100",
+    iconWrapClass: "bg-red-100 text-red-800 dark:bg-red-500/20 dark:text-red-200",
+    iconClass: "text-red-700 dark:text-red-300",
+    labelClass: "text-red-900 dark:text-red-200",
+    Icon: OctagonAlert,
+    divider: "border-red-400/50 dark:border-red-500/30",
+  },
+  resolved: {
+    label: "RECOVERY RESOLVED",
+    containerClass:
+      "border-emerald-300/70 bg-emerald-50/80 text-emerald-950 dark:border-emerald-500/40 dark:bg-emerald-500/10 dark:text-emerald-100",
+    iconWrapClass: "bg-emerald-100 text-emerald-800 dark:bg-emerald-500/20 dark:text-emerald-200",
+    iconClass: "text-emerald-700 dark:text-emerald-300",
+    labelClass: "text-emerald-900 dark:text-emerald-200",
+    Icon: Sparkles,
+    divider: "border-emerald-300/60 dark:border-emerald-500/30",
+  },
+};
+
+const OUTCOME_LABEL: Record<IssueRecoveryActionOutcome, string> = {
+  restored: "restored",
+  delegated: "delegated to follow-up",
+  false_positive: "false positive",
+  blocked: "blocked",
+  escalated: "escalated",
+  cancelled: "cancelled",
+};
+
+function readEvidenceString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.length > 240 ? `${trimmed.slice(0, 237)}…` : trimmed;
+}
+
+function pickEvidenceSummary(action: IssueRecoveryAction): string | null {
+  const evidence = action.evidence ?? {};
+  const candidates = [
+    "summary",
+    "detectedProgressSummary",
+    "missingDisposition",
+    "retryReason",
+    "latestRunErrorCode",
+    "latestRunStatus",
+    "latestIssueStatus",
+  ] as const;
+  for (const key of candidates) {
+    const next = readEvidenceString(evidence[key]);
+    if (next) return next;
+  }
+  return null;
+}
+
+function readEvidenceRunId(action: IssueRecoveryAction, key: "sourceRunId" | "correctiveRunId" | "latestRunId") {
+  const evidence = action.evidence ?? {};
+  const next = readEvidenceString(evidence[key]);
+  return next;
+}
+
+function readWakePolicySummary(action: IssueRecoveryAction): string | null {
+  const policy = action.wakePolicy;
+  if (!policy) return null;
+  const type = readEvidenceString(policy.type);
+  if (!type) return null;
+  if (type === "wake_owner") return "Corrective wake queued";
+  if (type === "board_escalation") return "Escalated to board";
+  if (type === "manual") return "Manual";
+  if (type === "monitor") {
+    const interval = readEvidenceString(policy.intervalLabel);
+    return interval ? `Monitor scheduled · ${interval}` : "Monitor scheduled";
+  }
+  return type.replaceAll("_", " ");
+}
+
+function formatTimeShort(value: string | Date | null | undefined): string | null {
+  if (!value) return null;
+  try {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) return null;
+    const now = Date.now();
+    const diffMs = date.getTime() - now;
+    const absMin = Math.round(Math.abs(diffMs) / 60_000);
+    if (absMin < 60) {
+      return diffMs >= 0 ? `in ${absMin}m` : `${absMin}m ago`;
+    }
+    return date.toLocaleString(undefined, {
+      month: "short",
+      day: "numeric",
+      hour: "numeric",
+      minute: "2-digit",
+    });
+  } catch {
+    return null;
+  }
+}
+
+function shortenRunId(runId: string | null | undefined) {
+  if (!runId) return null;
+  if (runId.length <= 12) return runId;
+  return runId.slice(0, 8);
+}
+
+function MetadataRow({
+  label,
+  children,
+}: {
+  label: string;
+  children: React.ReactNode;
+}) {
+  return (
+    <div className="grid grid-cols-[7.5rem_1fr] gap-x-3 gap-y-0 px-3 py-1.5 text-xs sm:px-4">
+      <dt className="truncate text-[11px] font-medium uppercase tracking-[0.08em] text-muted-foreground">
+        {label}
+      </dt>
+      <dd className="min-w-0 break-words text-foreground/90">{children}</dd>
+    </div>
+  );
+}
+
+function MissingValue() {
+  return <span className="text-muted-foreground">—</span>;
+}
+
+function AgentLink({
+  agentId,
+  agentMap,
+  fallback,
+}: {
+  agentId: string | null | undefined;
+  agentMap?: ReadonlyMap<string, Agent>;
+  fallback?: string | null;
+}) {
+  if (!agentId) {
+    return fallback ? <span>{fallback}</span> : <MissingValue />;
+  }
+  const agent = agentMap?.get(agentId);
+  const label = agent?.name ?? `agent ${agentId.slice(0, 8)}`;
+  if (agent) {
+    return (
+      <Link
+        to={agentUrl(agent)}
+        className="rounded-sm font-medium underline-offset-2 hover:underline"
+      >
+        {label}
+      </Link>
+    );
+  }
+  return <span className="font-medium">{label}</span>;
+}
+
+function RunChip({
+  runId,
+  agentId,
+  status,
+}: {
+  runId: string | null;
+  agentId: string | null | undefined;
+  status?: string | null;
+}) {
+  if (!runId) return <MissingValue />;
+  const short = shortenRunId(runId);
+  const inner = (
+    <>
+      <code className="rounded bg-background/80 px-1.5 py-0.5 font-mono text-[11px] text-foreground/80">
+        run {short}
+      </code>
+      {status ? (
+        <span className="font-sans text-[11px] text-muted-foreground">{status}</span>
+      ) : null}
+    </>
+  );
+  if (agentId) {
+    return (
+      <Link
+        to={`/agents/${agentId}/runs/${runId}`}
+        className="inline-flex items-center gap-2 rounded-sm underline-offset-2 hover:underline"
+      >
+        {inner}
+      </Link>
+    );
+  }
+  return <span className="inline-flex items-center gap-2">{inner}</span>;
+}
+
+const RESOLVE_OPTIONS: Array<{
+  outcome: RecoveryResolveOutcome;
+  label: string;
+  description: string;
+  destructive?: boolean;
+  boardOnly?: boolean;
+}> = [
+  {
+    outcome: "done",
+    label: "Mark issue done",
+    description: "Restore by recording the requested work as complete.",
+  },
+  {
+    outcome: "in_review",
+    label: "Send for review",
+    description: "Hand off to a reviewer with a real review path.",
+  },
+  {
+    outcome: "false_positive_done",
+    label: "False positive, done",
+    description: "Dismiss recovery and mark the source issue complete.",
+    destructive: true,
+    boardOnly: true,
+  },
+  {
+    outcome: "false_positive_in_review",
+    label: "False positive, review",
+    description: "Dismiss recovery and send the source issue for review.",
+    destructive: true,
+    boardOnly: true,
+  },
+];
+
+export function IssueRecoveryActionCard({
+  action,
+  agentMap,
+  forcedState,
+  onResolve,
+  canFalsePositive = false,
+  className,
+}: IssueRecoveryActionCardProps) {
+  const cardState: RecoveryCardCardState = forcedState ?? deriveRecoveryCardState(action);
+  const tone = STATE_TONE[cardState];
+  const ToneIcon = tone.Icon;
+
+  const headline = useMemo(() => {
+    if (cardState === "resolved" && action.outcome) {
+      return `Recovery resolved as ${OUTCOME_LABEL[action.outcome] ?? action.outcome}.`;
+    }
+    return KIND_HEADLINE[action.kind] ?? KIND_HEADLINE.missing_disposition;
+  }, [action.kind, action.outcome, cardState]);
+
+  const wakeSummary = readWakePolicySummary(action);
+  const evidenceSummary = pickEvidenceSummary(action);
+  const sourceRunId = readEvidenceRunId(action, "sourceRunId") ?? readEvidenceRunId(action, "latestRunId");
+  const correctiveRunId = readEvidenceRunId(action, "correctiveRunId");
+  const showAttempt = action.attemptCount > 1 && action.maxAttempts !== null;
+  const showTimeoutInline = (() => {
+    if (!action.timeoutAt) return false;
+    try {
+      const date = action.timeoutAt instanceof Date ? action.timeoutAt : new Date(action.timeoutAt);
+      const diffMs = date.getTime() - Date.now();
+      return diffMs > 0 && diffMs < 60 * 60 * 1000;
+    } catch {
+      return false;
+    }
+  })();
+  const updatedAtLabel = formatTimeShort(action.updatedAt);
+
+  const ariaState = ({
+    needed: "needed",
+    in_progress: "in progress",
+    observe_only: "observing active run",
+    escalated: "escalated",
+    resolved: "resolved",
+  } satisfies Record<RecoveryCardCardState, string>)[cardState];
+
+  const showResolveActions = onResolve !== undefined && cardState !== "resolved";
+  const visibleResolveOptions = RESOLVE_OPTIONS.filter((option) => {
+    if (option.boardOnly && !canFalsePositive) return false;
+    return true;
+  });
+
+  return (
+    <section
+      role="status"
+      aria-label={`Recovery action: ${ariaState}`}
+      data-recovery-state={cardState}
+      data-recovery-kind={action.kind}
+      className={cn(
+        "relative w-full overflow-hidden rounded-lg border text-sm shadow-[0_1px_0_rgba(15,23,42,0.02)]",
+        tone.containerClass,
+        className,
+      )}
+    >
+      <header className="flex items-start gap-3 px-3 py-2.5 sm:px-4">
+        <span
+          className={cn(
+            "mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-md",
+            tone.iconWrapClass,
+          )}
+          aria-hidden
+        >
+          <ToneIcon className={cn("h-4 w-4", tone.iconClass)} />
+        </span>
+        <div className="min-w-0 flex-1">
+          <div className="flex flex-wrap items-center gap-x-2 gap-y-0.5 text-[11px] font-semibold uppercase tracking-[0.14em]">
+            <span className={tone.labelClass}>{tone.label}</span>
+            <span className="text-muted-foreground/60" aria-hidden>·</span>
+            <code className="rounded bg-background/70 px-1.5 py-0.5 font-mono text-[11px] tracking-normal text-muted-foreground">
+              {KIND_LABEL[action.kind] ?? action.kind}
+            </code>
+            {updatedAtLabel ? (
+              <>
+                <span className="text-muted-foreground/60" aria-hidden>·</span>
+                <span className="font-medium normal-case tracking-normal text-muted-foreground">
+                  {updatedAtLabel}
+                </span>
+              </>
+            ) : null}
+          </div>
+          <p className="mt-1 text-[14px] leading-6">{headline}</p>
+        </div>
+      </header>
+      <dl className={cn("border-t bg-background/40 dark:bg-background/20", tone.divider)}>
+        <MetadataRow label="Owner">
+          <span className="inline-flex flex-wrap items-center gap-1.5">
+            {action.ownerType === "agent" && action.ownerAgentId ? (
+              <>
+                <span className="text-muted-foreground">Recovery:</span>
+                <AgentLink agentId={action.ownerAgentId} agentMap={agentMap} />
+              </>
+            ) : action.ownerType === "board" ? (
+              <span className="font-medium">Board</span>
+            ) : action.ownerType === "user" && action.ownerUserId ? (
+              <span className="font-medium">user {action.ownerUserId.slice(0, 6)}</span>
+            ) : action.ownerType === "system" ? (
+              <span className="font-medium">System</span>
+            ) : (
+              <span className="text-muted-foreground">unassigned — pick one to wake them</span>
+            )}
+            {action.returnOwnerAgentId ? (
+              <>
+                <span className="text-muted-foreground">→ Returns to:</span>
+                <AgentLink agentId={action.returnOwnerAgentId} agentMap={agentMap} />
+              </>
+            ) : null}
+          </span>
+        </MetadataRow>
+        <MetadataRow label="Source run">
+          <RunChip runId={sourceRunId} agentId={action.previousOwnerAgentId} />
+        </MetadataRow>
+        {correctiveRunId ? (
+          <MetadataRow label="Corrective run">
+            <RunChip runId={correctiveRunId} agentId={action.previousOwnerAgentId} />
+          </MetadataRow>
+        ) : null}
+        <MetadataRow label="Evidence">
+          {evidenceSummary ? (
+            <span className="break-words font-mono text-[11px] text-foreground/80">{evidenceSummary}</span>
+          ) : (
+            <MissingValue />
+          )}
+        </MetadataRow>
+        <MetadataRow label="Next action">
+          {action.nextAction ? <span>{action.nextAction}</span> : <MissingValue />}
+        </MetadataRow>
+        <MetadataRow label="Wake">
+          <span className="inline-flex flex-wrap items-center gap-1.5">
+            {wakeSummary ? <span>{wakeSummary}</span> : <MissingValue />}
+            {showAttempt ? (
+              <span className="rounded-md border border-border/50 bg-background/60 px-1.5 py-0.5 text-[11px] text-muted-foreground">
+                attempt {action.attemptCount} of {action.maxAttempts}
+              </span>
+            ) : null}
+            {showTimeoutInline ? (
+              <span className="rounded-md border border-border/50 bg-background/60 px-1.5 py-0.5 text-[11px] text-muted-foreground">
+                Times out {formatTimeShort(action.timeoutAt) ?? "soon"}
+              </span>
+            ) : null}
+          </span>
+        </MetadataRow>
+        {cardState === "resolved" && action.outcome ? (
+          <MetadataRow label="Resolution">
+            <span className={cn("font-medium", tone.labelClass)}>
+              Resolved as {OUTCOME_LABEL[action.outcome]}
+              {action.resolvedAt ? ` · ${formatTimeShort(action.resolvedAt) ?? ""}` : ""}
+            </span>
+          </MetadataRow>
+        ) : null}
+      </dl>
+      {showResolveActions ? (
+        <div className={cn("flex flex-wrap items-center gap-2 border-t px-3 py-2.5 sm:px-4", tone.divider)}>
+          <Popover>
+            <PopoverTrigger asChild>
+              <Button
+                type="button"
+                size="sm"
+                variant="default"
+                data-testid="recovery-action-resolve-trigger"
+                aria-label="Resolve recovery"
+              >
+                Resolve…
+              </Button>
+            </PopoverTrigger>
+            <PopoverContent
+              align="start"
+              sideOffset={6}
+              className="w-72 p-1.5"
+            >
+              <div className="px-2 py-1 text-[11px] font-semibold uppercase tracking-[0.12em] text-muted-foreground">
+                Resolve recovery
+              </div>
+              <div className="flex flex-col">
+                {visibleResolveOptions.map((option) => (
+                  <button
+                    key={option.outcome}
+                    type="button"
+                    onClick={() => onResolve?.(option.outcome)}
+                    className={cn(
+                      "flex flex-col items-start gap-0.5 rounded-md px-2 py-1.5 text-left text-sm transition-colors",
+                      "hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50",
+                      option.destructive ? "text-destructive" : null,
+                    )}
+                  >
+                    <span className="font-medium leading-5">{option.label}</span>
+                    <span className="text-[11px] leading-4 text-muted-foreground">{option.description}</span>
+                  </button>
+                ))}
+              </div>
+            </PopoverContent>
+          </Popover>
+          {cardState === "observe_only" ? (
+            <span className="text-[11px] text-muted-foreground">
+              Recovery is observing without interrupting the live run.
+            </span>
+          ) : (
+            <span className="text-[11px] text-muted-foreground">
+              The card stays open until an explicit decision is recorded.
+            </span>
+          )}
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
+export type { IssueRecoveryActionStatus };
+
+export default IssueRecoveryActionCard;
diff --git a/ui/src/components/IssueRow.tsx b/ui/src/components/IssueRow.tsx
index 7ca9827d..83873bb6 100644
--- a/ui/src/components/IssueRow.tsx
+++ b/ui/src/components/IssueRow.tsx
@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { Issue } from "@paperclipai/shared";
+import type { Issue, IssueRecoveryAction } from "@paperclipai/shared";
 import { Link } from "@/lib/router";
 import { Eye, Flag, X } from "lucide-react";
 import {
@@ -8,6 +8,7 @@ import {
   withIssueDetailHeaderSeed,
 } from "../lib/issueDetailBreadcrumb";
 import { cn } from "../lib/utils";
+import { deriveActiveRecoveryDisplayState, RECOVERY_CHIP_DEFAULT_TONE } from "../lib/recovery-display";
 import { StatusIcon } from "./StatusIcon";
 import { productivityReviewTriggerLabel } from "./ProductivityReviewBadge";
 import { hasAssignedBacklogBlocker } from "../lib/issue-blockers";
@@ -92,6 +93,8 @@ export function IssueRow({
       Planning
     </span>
   ) : null;
+  const recoveryAction = issue.activeRecoveryAction ?? null;
+  const recoveryIndicator = recoveryAction ? renderRecoveryChip(recoveryAction, selected) : null;
   const parkedBlockerIndicator = hasAssignedBacklogBlocker(issue.blockedBy) ? (
     <span
       data-testid="issue-row-parked-blocker"
@@ -125,6 +128,7 @@ export function IssueRow({
         {productivityReviewIndicator}
         {planningModeIndicator}
         {parkedBlockerIndicator}
+        {recoveryIndicator}
       </span>
       <span className="flex min-w-0 flex-1 flex-col gap-1 sm:contents">
         <span className={cn("line-clamp-2 text-sm sm:order-2 sm:min-w-0 sm:flex-1 sm:truncate sm:line-clamp-none", titleClassName)}>
@@ -151,6 +155,7 @@ export function IssueRow({
               </span>
               {planningModeIndicator}
               {parkedBlockerIndicator}
+              {recoveryIndicator}
             </>
           )}
           {mobileMeta ? (
@@ -230,3 +235,27 @@ export function IssueRow({
     </Link>
   );
 }
+
+function renderRecoveryChip(action: IssueRecoveryAction, selected: boolean): ReactNode {
+  const state = deriveActiveRecoveryDisplayState(action);
+  if (!state) return null;
+  const tone = RECOVERY_CHIP_DEFAULT_TONE[state];
+  const Icon = tone.icon;
+  return (
+    <span
+      data-testid="issue-row-recovery-indicator"
+      data-recovery-state={state}
+      role="status"
+      aria-label={tone.label}
+      className={cn(
+        "ml-1.5 inline-flex shrink-0 items-center gap-0.5 rounded-full border px-2 py-0.5 text-[10px] font-medium",
+        tone.className,
+        selected ? "!border-muted-foreground !text-muted-foreground" : null,
+      )}
+      title={`${tone.label} — open the source issue to act.`}
+    >
+      <Icon className="h-2.5 w-2.5" aria-hidden />
+      {tone.label}
+    </span>
+  );
+}
diff --git a/ui/src/components/IssueSiblingNavigation.test.tsx b/ui/src/components/IssueSiblingNavigation.test.tsx
new file mode 100644
index 00000000..d356fcfb
--- /dev/null
+++ b/ui/src/components/IssueSiblingNavigation.test.tsx
@@ -0,0 +1,130 @@
+// @vitest-environment jsdom
+
+import { act, type AnchorHTMLAttributes, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import type { Issue } from "@paperclipai/shared";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { IssueSiblingNavigation } from "./IssueSiblingNavigation";
+
+vi.mock("@/lib/router", () => ({
+  Link: ({
+    children,
+    to,
+    issueQuicklookAlign,
+    issueQuicklookSide,
+    issuePrefetch: _issuePrefetch,
+    state: _state,
+    ...props
+  }: AnchorHTMLAttributes<HTMLAnchorElement> & {
+    to: string;
+    issueQuicklookAlign?: string;
+    issueQuicklookSide?: string;
+    issuePrefetch?: unknown;
+    state?: unknown;
+    children?: ReactNode;
+  }) => (
+    <a
+      href={to}
+      data-quicklook-align={issueQuicklookAlign}
+      data-quicklook-side={issueQuicklookSide}
+      {...props}
+    >
+      {children}
+    </a>
+  ),
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function issue(id: string, overrides: Partial<Issue> = {}): Issue {
+  return {
+    id,
+    identifier: `PAP-${id}`,
+    title: `Sibling ${id}`,
+    status: "todo",
+    blockerAttention: null,
+    createdAt: new Date("2026-05-01T00:00:00.000Z"),
+    updatedAt: new Date("2026-05-01T00:00:00.000Z"),
+    ...overrides,
+  } as Issue;
+}
+
+let root: Root | null = null;
+let container: HTMLDivElement | null = null;
+
+afterEach(() => {
+  if (root) {
+    act(() => root?.unmount());
+  }
+  root = null;
+  container?.remove();
+  container = null;
+});
+
+function render(node: ReactNode) {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+  act(() => root?.render(node));
+  return container;
+}
+
+describe("IssueSiblingNavigation", () => {
+  it("renders the locked card anatomy for previous and next siblings", () => {
+    const node = render(
+      <IssueSiblingNavigation
+        navigation={{
+          previous: issue("1", { title: "Previous sibling title" }),
+          next: issue("3", { title: "Next sibling title" }),
+          currentIndex: 1,
+          totalCount: 3,
+        }}
+      />,
+    );
+
+    const nav = node.querySelector("nav");
+    expect(nav?.getAttribute("aria-label")).toBe("Sub-issue navigation");
+    expect(nav?.className).toContain("sm:grid-cols-2");
+    expect(nav?.className).not.toContain("border-t");
+
+    const links = Array.from(node.querySelectorAll("a"));
+    expect(links).toHaveLength(2);
+    expect(links[0].textContent).toContain("Previous");
+    expect(links[0].textContent).toContain("PAP-1");
+    expect(links[0].textContent).toContain("Previous sibling title");
+    expect(links[0].getAttribute("aria-label")).toBe("Previous sub-issue: PAP-1 - Previous sibling title");
+    expect(links[0].getAttribute("data-quicklook-align")).toBe("start");
+
+    expect(links[1].textContent).toContain("Next");
+    expect(links[1].textContent).toContain("PAP-3");
+    expect(links[1].textContent).toContain("Next sibling title");
+    expect(links[1].getAttribute("aria-label")).toBe("Next sub-issue: PAP-3 - Next sibling title");
+    expect(links[1].getAttribute("data-quicklook-align")).toBe("end");
+    expect(links[1].className).toContain("sm:text-right");
+
+    expect(links[0].className).toContain("rounded-lg");
+    expect(links[0].className).toContain("hover:bg-accent/50");
+    expect(links[0].className).toContain("focus-visible:ring-[3px]");
+    expect(node.querySelector(".truncate")?.textContent).toBe("Previous sibling title");
+  });
+
+  it("keeps a lone next card in the right desktop column", () => {
+    const node = render(
+      <IssueSiblingNavigation
+        navigation={{
+          previous: null,
+          next: issue("2"),
+          currentIndex: 0,
+          totalCount: 2,
+        }}
+      />,
+    );
+
+    const links = Array.from(node.querySelectorAll("a"));
+    expect(links).toHaveLength(1);
+    expect(links[0].textContent).toContain("Next");
+    expect(links[0].className).toContain("sm:col-start-2");
+    expect(node.textContent).not.toContain("Previous");
+  });
+});
diff --git a/ui/src/components/IssueSiblingNavigation.tsx b/ui/src/components/IssueSiblingNavigation.tsx
new file mode 100644
index 00000000..213dfe4d
--- /dev/null
+++ b/ui/src/components/IssueSiblingNavigation.tsx
@@ -0,0 +1,90 @@
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import type { Issue } from "@paperclipai/shared";
+import type { IssueSiblingNavigation as IssueSiblingNavigationState } from "@/lib/issue-detail-subissues";
+import { createIssueDetailPath, withIssueDetailHeaderSeed } from "@/lib/issueDetailBreadcrumb";
+import { cn } from "@/lib/utils";
+import { Link } from "@/lib/router";
+import { StatusIcon } from "./StatusIcon";
+
+type IssueSiblingNavigationProps = {
+  navigation: IssueSiblingNavigationState | null;
+  linkState?: unknown;
+};
+
+export function IssueSiblingNavigation({ navigation, linkState }: IssueSiblingNavigationProps) {
+  if (!navigation) return null;
+
+  return (
+    <nav
+      aria-label="Sub-issue navigation"
+      className="mt-4 flex flex-col gap-3 sm:mt-6 sm:grid sm:grid-cols-2"
+    >
+      {navigation.previous ? (
+        <SiblingLink direction="previous" issue={navigation.previous} linkState={linkState} />
+      ) : null}
+      {navigation.next ? (
+        <SiblingLink
+          direction="next"
+          issue={navigation.next}
+          linkState={linkState}
+          className={!navigation.previous ? "sm:col-start-2" : undefined}
+        />
+      ) : null}
+    </nav>
+  );
+}
+
+function SiblingLink({
+  direction,
+  issue,
+  linkState,
+  className,
+}: {
+  direction: "previous" | "next";
+  issue: Issue;
+  linkState?: unknown;
+  className?: string;
+}) {
+  const issuePathId = issue.identifier ?? issue.id;
+  const label = direction === "previous" ? "Previous" : "Next";
+  const ariaDirection = direction === "previous" ? "Previous sub-issue" : "Next sub-issue";
+  const identifier = issue.identifier ?? issue.id.slice(0, 8);
+  const Icon = direction === "previous" ? ChevronLeft : ChevronRight;
+
+  return (
+    <Link
+      to={createIssueDetailPath(issuePathId)}
+      state={withIssueDetailHeaderSeed(linkState, issue)}
+      issuePrefetch={issue}
+      issueQuicklookSide="top"
+      issueQuicklookAlign={direction === "previous" ? "start" : "end"}
+      aria-label={`${ariaDirection}: ${identifier} - ${issue.title}`}
+      className={cn(
+        "group min-w-0 rounded-lg border border-border bg-card px-3 py-2.5 text-left no-underline transition-colors hover:bg-accent/50 focus-visible:outline-none focus-visible:ring-[3px] focus-visible:ring-ring",
+        direction === "next" && "sm:text-right",
+        className,
+      )}
+    >
+      <div className="min-w-0 space-y-1.5">
+        <div className={cn(
+          "flex items-center gap-1.5 text-xs text-muted-foreground transition-colors group-hover:text-foreground",
+          direction === "next" && "sm:justify-end",
+        )}>
+          {direction === "previous" ? <Icon className="h-3.5 w-3.5 shrink-0" /> : null}
+          <span>{label}</span>
+          {direction === "next" ? <Icon className="h-3.5 w-3.5 shrink-0" /> : null}
+        </div>
+        <div className={cn(
+          "flex min-w-0 items-center gap-1.5 text-xs font-mono text-muted-foreground transition-colors group-hover:text-foreground",
+          direction === "next" && "sm:justify-end",
+        )}>
+          <StatusIcon status={issue.status} blockerAttention={issue.blockerAttention} />
+          <span className="shrink-0">{identifier}</span>
+        </div>
+        <div className="truncate text-sm text-foreground">
+          {issue.title}
+        </div>
+      </div>
+    </Link>
+  );
+}
diff --git a/ui/src/components/ManagedRoutinesList.tsx b/ui/src/components/ManagedRoutinesList.tsx
index 4b62b3de..0ac65812 100644
--- a/ui/src/components/ManagedRoutinesList.tsx
+++ b/ui/src/components/ManagedRoutinesList.tsx
@@ -23,6 +23,12 @@ export type ManagedRoutineMissingRef = {
   resourceKey: string;
 };
 
+export type ManagedRoutineDefaultDrift = {
+  changedFields: string[];
+  defaultTitle?: string | null;
+  defaultDescription?: string | null;
+};
+
 export type ManagedRoutinesListItem = {
   key: string;
   title: string;
@@ -37,6 +43,7 @@ export type ManagedRoutinesListItem = {
   lastRunStatus?: string | null;
   managedByPluginDisplayName?: string | null;
   missingRefs?: ManagedRoutineMissingRef[];
+  defaultDrift?: ManagedRoutineDefaultDrift | null;
 };
 
 export type ManagedRoutinesListProps = {
diff --git a/ui/src/lib/activity-format.ts b/ui/src/lib/activity-format.ts
index d5013c77..d1cd2b48 100644
--- a/ui/src/lib/activity-format.ts
+++ b/ui/src/lib/activity-format.ts
@@ -46,6 +46,9 @@ const ACTIVITY_ROW_VERBS: Record<string, string> = {
   "issue.successful_run_handoff_required": "flagged missing next step on",
   "issue.successful_run_handoff_resolved": "recorded next step chosen on",
   "issue.successful_run_handoff_escalated": "escalated missing next step on",
+  "issue.recovery_action_opened": "opened a recovery action on",
+  "issue.recovery_action_resolved": "resolved the recovery action on",
+  "issue.recovery_action_escalated": "escalated the recovery action on",
   "agent.created": "created",
   "agent.updated": "updated",
   "agent.paused": "paused",
@@ -98,6 +101,9 @@ const ISSUE_ACTIVITY_LABELS: Record<string, string> = {
   "issue.successful_run_handoff_required": "Run finished without a clear next step",
   "issue.successful_run_handoff_resolved": "Next step chosen",
   "issue.successful_run_handoff_escalated": "Run finished without a next step - recovery escalated",
+  "issue.recovery_action_opened": "Opened a source-scoped recovery action",
+  "issue.recovery_action_resolved": "Resolved the recovery action",
+  "issue.recovery_action_escalated": "Escalated the recovery action",
   "agent.created": "created an agent",
   "agent.updated": "updated the agent",
   "agent.paused": "paused the agent",
diff --git a/ui/src/lib/blockedInbox.test.ts b/ui/src/lib/blockedInbox.test.ts
new file mode 100644
index 00000000..33aa33cb
--- /dev/null
+++ b/ui/src/lib/blockedInbox.test.ts
@@ -0,0 +1,275 @@
+// @vitest-environment node
+
+import { describe, expect, it } from "vitest";
+import type {
+  Issue,
+  IssueBlockedInboxAttention,
+  IssueBlockedInboxReason,
+  IssueBlockedInboxSeverity,
+} from "@paperclipai/shared";
+import {
+  BLOCKED_REASON_VARIANT_ORDER,
+  blockedBadgeTone,
+  blockedReasonLabel,
+  blockedReasonVariant,
+  blockedRowMatchesSearch,
+  blockedSeverityRank,
+  blockedVariantLabel,
+  buildBlockedInboxRows,
+  compareBlockedAttention,
+  compareBlockedRows,
+  formatStoppedAge,
+  groupBlockedInboxRows,
+  sortBlockedInboxRows,
+  type BlockedInboxIssueRow,
+} from "./blockedInbox";
+
+function makeAttention(
+  overrides: Partial<IssueBlockedInboxAttention> = {},
+): IssueBlockedInboxAttention {
+  return {
+    kind: "blocked",
+    state: "needs_attention",
+    reason: "blocked_chain_stalled",
+    severity: "medium",
+    stoppedSinceAt: "2026-05-08T12:00:00.000Z",
+    owner: { type: "agent", agentId: null, userId: null, label: "QA" },
+    action: { label: "Resolve PAP-1", detail: null },
+    sourceIssue: null,
+    leafIssue: null,
+    recoveryIssue: null,
+    approvalId: null,
+    interactionId: null,
+    sampleIssueIdentifier: null,
+    redaction: { externalDetailsRedacted: false, secretFieldsOmitted: true },
+    ...overrides,
+  };
+}
+
+function makeIssue(
+  overrides: Partial<Issue> & { id: string },
+  attention: IssueBlockedInboxAttention | null = null,
+): Issue {
+  const { id, ...rest } = overrides;
+  return {
+    id,
+    companyId: "company-1",
+    projectId: null,
+    projectWorkspaceId: null,
+    goalId: null,
+    parentId: null,
+    title: "Title",
+    description: null,
+    status: "in_progress",
+    workMode: "standard",
+    priority: "medium",
+    assigneeAgentId: null,
+    assigneeUserId: null,
+    checkoutRunId: null,
+    executionRunId: null,
+    executionAgentNameKey: null,
+    executionLockedAt: null,
+    createdByAgentId: null,
+    createdByUserId: null,
+    issueNumber: 1,
+    identifier: "PAP-1",
+    requestDepth: 0,
+    billingCode: null,
+    assigneeAdapterOverrides: null,
+    executionWorkspaceId: null,
+    executionWorkspacePreference: null,
+    executionWorkspaceSettings: null,
+    startedAt: null,
+    completedAt: null,
+    cancelledAt: null,
+    hiddenAt: null,
+    blockedInboxAttention: attention,
+    createdAt: new Date("2026-05-09T00:00:00.000Z"),
+    updatedAt: new Date("2026-05-09T00:00:00.000Z"),
+    ...rest,
+  } as Issue;
+}
+
+describe("blockedInbox", () => {
+  it("maps every reason to a known variant and label", () => {
+    const reasons: IssueBlockedInboxReason[] = [
+      "pending_board_decision",
+      "pending_user_decision",
+      "missing_successful_run_disposition",
+      "blocked_chain_stalled",
+      "blocked_by_unassigned_issue",
+      "blocked_by_assigned_backlog_issue",
+      "blocked_by_cancelled_issue",
+      "blocked_by_uninvokable_assignee",
+      "in_review_without_action_path",
+      "invalid_review_participant",
+      "open_recovery_issue",
+      "external_owner_action",
+    ];
+    for (const reason of reasons) {
+      const variant = blockedReasonVariant(reason);
+      expect(BLOCKED_REASON_VARIANT_ORDER).toContain(variant);
+      expect(blockedVariantLabel(variant)).toBeTruthy();
+      expect(blockedReasonLabel(reason)).toBeTruthy();
+    }
+  });
+
+  it("ranks severity critical first and low last", () => {
+    const order: IssueBlockedInboxSeverity[] = ["critical", "high", "medium", "low"];
+    const ranks = order.map((s) => blockedSeverityRank(s));
+    expect([...ranks].sort((a, b) => a - b)).toEqual(ranks);
+  });
+
+  it("compares by severity first, then stoppedSinceAt", () => {
+    const a = makeAttention({
+      severity: "critical",
+      stoppedSinceAt: "2026-05-08T13:00:00.000Z",
+    });
+    const b = makeAttention({
+      severity: "high",
+      stoppedSinceAt: "2026-05-08T10:00:00.000Z",
+    });
+    const c = makeAttention({
+      severity: "high",
+      stoppedSinceAt: "2026-05-08T12:00:00.000Z",
+    });
+    expect(compareBlockedAttention(a, b)).toBeLessThan(0);
+    // both 'high', earlier stoppedSinceAt sorts first
+    expect(compareBlockedAttention(b, c)).toBeLessThan(0);
+  });
+
+  it("keeps equal unstopped attention comparisons deterministic", () => {
+    const a = makeAttention({ severity: "high", stoppedSinceAt: null });
+    const b = makeAttention({ severity: "high", stoppedSinceAt: null });
+    expect(compareBlockedAttention(a, b)).toBe(0);
+  });
+
+  it("buildBlockedInboxRows skips issues without attention", () => {
+    const issues = [
+      makeIssue({ id: "issue-1" }, makeAttention()),
+      makeIssue({ id: "issue-2" }, null),
+    ];
+    const rows = buildBlockedInboxRows(issues);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].issue.id).toBe("issue-1");
+  });
+
+  it("groupBlockedInboxRows orders groups by canonical variant order and sorts within group", () => {
+    const issues = [
+      makeIssue(
+        { id: "external-1" },
+        makeAttention({ reason: "external_owner_action", severity: "low" }),
+      ),
+      makeIssue(
+        { id: "stalled-1" },
+        makeAttention({
+          reason: "blocked_chain_stalled",
+          severity: "high",
+          stoppedSinceAt: "2026-05-09T01:00:00.000Z",
+        }),
+      ),
+      makeIssue(
+        { id: "stalled-2" },
+        makeAttention({
+          reason: "blocked_chain_stalled",
+          severity: "critical",
+          stoppedSinceAt: "2026-05-09T05:00:00.000Z",
+        }),
+      ),
+      makeIssue(
+        { id: "decision-1" },
+        makeAttention({ reason: "pending_board_decision", severity: "medium" }),
+      ),
+    ];
+    const groups = groupBlockedInboxRows(buildBlockedInboxRows(issues));
+    expect(groups.map((g) => g.variant)).toEqual([
+      "needs_decision",
+      "stalled",
+      "external_wait",
+    ]);
+    const stalled = groups.find((g) => g.variant === "stalled")!;
+    expect(stalled.rows.map((r) => r.issue.id)).toEqual(["stalled-2", "stalled-1"]);
+  });
+
+  it("sortBlockedInboxRows supports recent and longest-stopped ordering", () => {
+    const rows = buildBlockedInboxRows([
+      makeIssue(
+        { id: "old", title: "Old stopped" },
+        makeAttention({
+          severity: "low",
+          stoppedSinceAt: "2026-05-06T00:00:00.000Z",
+        }),
+      ),
+      makeIssue(
+        { id: "recent", title: "Recently stopped" },
+        makeAttention({
+          severity: "critical",
+          stoppedSinceAt: "2026-05-09T00:00:00.000Z",
+        }),
+      ),
+      makeIssue(
+        { id: "middle", title: "Middle stopped" },
+        makeAttention({
+          severity: "medium",
+          stoppedSinceAt: "2026-05-08T00:00:00.000Z",
+        }),
+      ),
+    ]);
+
+    expect(sortBlockedInboxRows(rows, "most_recent").map((row) => row.issue.id)).toEqual([
+      "recent",
+      "middle",
+      "old",
+    ]);
+    expect(sortBlockedInboxRows(rows, "longest_stopped").map((row) => row.issue.id)).toEqual([
+      "old",
+      "middle",
+      "recent",
+    ]);
+    expect(compareBlockedRows(rows[0], rows[1], "most_recent")).toBeGreaterThan(0);
+  });
+
+  it("blockedRowMatchesSearch matches title, identifier, owner, action and reason", () => {
+    const issue = makeIssue(
+      { id: "issue-1", identifier: "PAP-77", title: "Resume parked work" },
+      makeAttention({
+        reason: "blocked_by_assigned_backlog_issue",
+        owner: { type: "agent", agentId: null, userId: null, label: "Charlie" },
+        action: { label: "Resume parked blocker", detail: null },
+      }),
+    );
+    const row: BlockedInboxIssueRow = buildBlockedInboxRows([issue])[0];
+    expect(blockedRowMatchesSearch(row, "")).toBe(true);
+    expect(blockedRowMatchesSearch(row, "pap-77")).toBe(true);
+    expect(blockedRowMatchesSearch(row, "parked")).toBe(true);
+    expect(blockedRowMatchesSearch(row, "charlie")).toBe(true);
+    expect(blockedRowMatchesSearch(row, "no match")).toBe(false);
+  });
+
+  it("blockedBadgeTone reflects the highest severity present", () => {
+    const empty: BlockedInboxIssueRow[] = [];
+    expect(blockedBadgeTone(empty)).toBe("muted");
+
+    const issues = [
+      makeIssue({ id: "a" }, makeAttention({ severity: "low" })),
+      makeIssue({ id: "b" }, makeAttention({ severity: "high" })),
+    ];
+    expect(blockedBadgeTone(buildBlockedInboxRows(issues))).toBe("amber");
+
+    const critical = [
+      ...issues,
+      makeIssue({ id: "c" }, makeAttention({ severity: "critical" })),
+    ];
+    expect(blockedBadgeTone(buildBlockedInboxRows(critical))).toBe("red");
+  });
+
+  it("formatStoppedAge produces stable buckets", () => {
+    const now = new Date("2026-05-10T00:00:00.000Z").getTime();
+    expect(formatStoppedAge(null)).toBe("stopped");
+    expect(formatStoppedAge("2026-05-09T23:59:30.000Z", now)).toBe("stopped just now");
+    expect(formatStoppedAge("2026-05-09T23:30:00.000Z", now)).toBe("stopped 30m");
+    expect(formatStoppedAge("2026-05-09T20:00:00.000Z", now)).toBe("stopped 4h");
+    expect(formatStoppedAge("2026-05-07T00:00:00.000Z", now)).toBe("stopped 3d");
+    expect(formatStoppedAge("2026-04-15T00:00:00.000Z", now)).toBe("stopped 3w");
+  });
+});
diff --git a/ui/src/lib/blockedInbox.ts b/ui/src/lib/blockedInbox.ts
new file mode 100644
index 00000000..d14db461
--- /dev/null
+++ b/ui/src/lib/blockedInbox.ts
@@ -0,0 +1,275 @@
+import type {
+  Issue,
+  IssueBlockedInboxAttention,
+  IssueBlockedInboxReason,
+  IssueBlockedInboxSeverity,
+} from "@paperclipai/shared";
+
+export type BlockedReasonVariant =
+  | "needs_decision"
+  | "stalled"
+  | "needs_attention"
+  | "recovery_required"
+  | "external_wait"
+  | "owner_paused";
+
+const VARIANT_BY_REASON: Record<IssueBlockedInboxReason, BlockedReasonVariant> = {
+  pending_board_decision: "needs_decision",
+  pending_user_decision: "needs_decision",
+  missing_successful_run_disposition: "needs_decision",
+  blocked_chain_stalled: "stalled",
+  blocked_by_unassigned_issue: "needs_attention",
+  blocked_by_assigned_backlog_issue: "needs_attention",
+  blocked_by_cancelled_issue: "needs_attention",
+  in_review_without_action_path: "needs_attention",
+  invalid_review_participant: "needs_attention",
+  open_recovery_issue: "recovery_required",
+  external_owner_action: "external_wait",
+  blocked_by_uninvokable_assignee: "owner_paused",
+};
+
+export const BLOCKED_REASON_VARIANT_ORDER: BlockedReasonVariant[] = [
+  "needs_decision",
+  "stalled",
+  "needs_attention",
+  "recovery_required",
+  "external_wait",
+  "owner_paused",
+];
+
+export const BLOCKED_VARIANT_LABELS: Record<BlockedReasonVariant, string> = {
+  needs_decision: "Needs decision",
+  stalled: "Blocked chain stalled",
+  needs_attention: "Needs attention",
+  recovery_required: "Recovery required",
+  external_wait: "External wait",
+  owner_paused: "Owner paused",
+};
+
+const REASON_LABELS: Record<IssueBlockedInboxReason, string> = {
+  pending_board_decision: "Pending board decision",
+  pending_user_decision: "Pending user decision",
+  missing_successful_run_disposition: "Pick disposition",
+  blocked_chain_stalled: "Blocked chain stalled",
+  blocked_by_unassigned_issue: "Unassigned blocker",
+  blocked_by_assigned_backlog_issue: "Parked blocker",
+  blocked_by_cancelled_issue: "Cancelled blocker",
+  in_review_without_action_path: "Review without action path",
+  invalid_review_participant: "Invalid review participant",
+  open_recovery_issue: "Recovery in progress",
+  external_owner_action: "External owner action",
+  blocked_by_uninvokable_assignee: "Owner paused",
+};
+
+const SEVERITY_RANK: Record<IssueBlockedInboxSeverity, number> = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+};
+
+export type BlockedInboxBadgeTone = "muted" | "amber" | "red";
+
+export function blockedReasonVariant(reason: IssueBlockedInboxReason): BlockedReasonVariant {
+  return VARIANT_BY_REASON[reason] ?? "needs_attention";
+}
+
+export function blockedReasonLabel(reason: IssueBlockedInboxReason): string {
+  return REASON_LABELS[reason] ?? "Stopped";
+}
+
+export function blockedVariantLabel(variant: BlockedReasonVariant): string {
+  return BLOCKED_VARIANT_LABELS[variant];
+}
+
+export function blockedSeverityRank(severity: IssueBlockedInboxSeverity): number {
+  return SEVERITY_RANK[severity] ?? 9;
+}
+
+export function compareBlockedAttention(
+  a: IssueBlockedInboxAttention,
+  b: IssueBlockedInboxAttention,
+): number {
+  const sevDiff = blockedSeverityRank(a.severity) - blockedSeverityRank(b.severity);
+  if (sevDiff !== 0) return sevDiff;
+  const aSince = a.stoppedSinceAt ? new Date(a.stoppedSinceAt).getTime() : Number.POSITIVE_INFINITY;
+  const bSince = b.stoppedSinceAt ? new Date(b.stoppedSinceAt).getTime() : Number.POSITIVE_INFINITY;
+  const sinceDiff = aSince - bSince;
+  return Number.isFinite(sinceDiff) ? sinceDiff : 0;
+}
+
+export interface BlockedInboxIssueRow {
+  issue: Issue;
+  attention: IssueBlockedInboxAttention;
+  variant: BlockedReasonVariant;
+  reasonLabel: string;
+  stoppedAtMs: number | null;
+}
+
+export type BlockedInboxGroupBy = "blocker_type" | "none";
+export type BlockedInboxSort = "urgency" | "most_recent" | "longest_stopped";
+
+export const BLOCKED_GROUP_OPTIONS: readonly [BlockedInboxGroupBy, string][] = [
+  ["blocker_type", "Blocker type"],
+  ["none", "None"],
+];
+
+export const BLOCKED_SORT_OPTIONS: readonly [BlockedInboxSort, string][] = [
+  ["urgency", "Most urgent"],
+  ["most_recent", "Most recent"],
+  ["longest_stopped", "Longest stopped"],
+];
+
+export interface BlockedInboxGroup {
+  variant: BlockedReasonVariant;
+  label: string;
+  rows: BlockedInboxIssueRow[];
+}
+
+export function buildBlockedInboxRows(issues: readonly Issue[]): BlockedInboxIssueRow[] {
+  const rows: BlockedInboxIssueRow[] = [];
+  for (const issue of issues) {
+    const attention = issue.blockedInboxAttention;
+    if (!attention) continue;
+    rows.push({
+      issue,
+      attention,
+      variant: blockedReasonVariant(attention.reason),
+      reasonLabel: blockedReasonLabel(attention.reason),
+      stoppedAtMs: attention.stoppedSinceAt ? new Date(attention.stoppedSinceAt).getTime() : null,
+    });
+  }
+  return rows;
+}
+
+function issueTimestampMs(value: Date | string | null | undefined): number | null {
+  if (!value) return null;
+  const timestamp = new Date(value).getTime();
+  return Number.isFinite(timestamp) ? timestamp : null;
+}
+
+function blockedRowRecencyMs(row: BlockedInboxIssueRow): number {
+  return row.stoppedAtMs ?? issueTimestampMs(row.issue.updatedAt) ?? 0;
+}
+
+function compareBlockedRowsByTitle(a: BlockedInboxIssueRow, b: BlockedInboxIssueRow): number {
+  const byTitle = a.issue.title.localeCompare(b.issue.title);
+  if (byTitle !== 0) return byTitle;
+  return a.issue.id.localeCompare(b.issue.id);
+}
+
+export function compareBlockedRows(
+  a: BlockedInboxIssueRow,
+  b: BlockedInboxIssueRow,
+  sort: BlockedInboxSort = "urgency",
+): number {
+  if (sort === "most_recent") {
+    const recencyDiff = blockedRowRecencyMs(b) - blockedRowRecencyMs(a);
+    if (recencyDiff !== 0) return recencyDiff;
+    const attentionDiff = compareBlockedAttention(a.attention, b.attention);
+    if (attentionDiff !== 0) return attentionDiff;
+    return compareBlockedRowsByTitle(a, b);
+  }
+
+  if (sort === "longest_stopped") {
+    const aStopped = a.stoppedAtMs ?? Number.POSITIVE_INFINITY;
+    const bStopped = b.stoppedAtMs ?? Number.POSITIVE_INFINITY;
+    const stoppedDiff = aStopped - bStopped;
+    if (stoppedDiff !== 0) return stoppedDiff;
+    const severityDiff = blockedSeverityRank(a.attention.severity) - blockedSeverityRank(b.attention.severity);
+    if (severityDiff !== 0) return severityDiff;
+    return compareBlockedRowsByTitle(a, b);
+  }
+
+  const attentionDiff = compareBlockedAttention(a.attention, b.attention);
+  if (attentionDiff !== 0) return attentionDiff;
+  const recencyDiff = blockedRowRecencyMs(b) - blockedRowRecencyMs(a);
+  if (recencyDiff !== 0) return recencyDiff;
+  return compareBlockedRowsByTitle(a, b);
+}
+
+export function sortBlockedInboxRows(
+  rows: readonly BlockedInboxIssueRow[],
+  sort: BlockedInboxSort = "urgency",
+): BlockedInboxIssueRow[] {
+  return [...rows].sort((a, b) => compareBlockedRows(a, b, sort));
+}
+
+export function groupBlockedInboxRows(
+  rows: readonly BlockedInboxIssueRow[],
+  sort: BlockedInboxSort = "urgency",
+): BlockedInboxGroup[] {
+  const buckets = new Map<BlockedReasonVariant, BlockedInboxIssueRow[]>();
+  for (const row of rows) {
+    const list = buckets.get(row.variant) ?? [];
+    list.push(row);
+    buckets.set(row.variant, list);
+  }
+  const groups: BlockedInboxGroup[] = [];
+  for (const variant of BLOCKED_REASON_VARIANT_ORDER) {
+    const list = buckets.get(variant);
+    if (!list || list.length === 0) continue;
+    const sorted = sortBlockedInboxRows(list, sort);
+    groups.push({ variant, label: BLOCKED_VARIANT_LABELS[variant], rows: sorted });
+  }
+  return groups;
+}
+
+export function blockedRowMatchesSearch(row: BlockedInboxIssueRow, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (!q) return true;
+  const haystack = [
+    row.issue.title,
+    row.issue.identifier ?? "",
+    row.attention.owner.label ?? "",
+    row.attention.action.label,
+    row.attention.action.detail ?? "",
+    row.reasonLabel,
+    row.attention.leafIssue?.identifier ?? "",
+    row.attention.leafIssue?.title ?? "",
+    row.attention.recoveryIssue?.identifier ?? "",
+    row.attention.recoveryIssue?.title ?? "",
+  ]
+    .join(" ")
+    .toLowerCase();
+  return haystack.includes(q);
+}
+
+export function blockedBadgeTone(rows: readonly BlockedInboxIssueRow[]): BlockedInboxBadgeTone {
+  if (rows.length === 0) return "muted";
+  let highest: IssueBlockedInboxSeverity = "low";
+  for (const row of rows) {
+    if (blockedSeverityRank(row.attention.severity) < blockedSeverityRank(highest)) {
+      highest = row.attention.severity;
+    }
+  }
+  if (highest === "critical") return "red";
+  if (highest === "high") return "amber";
+  return "muted";
+}
+
+export function formatStoppedAge(stoppedSinceAt: string | null, now: number = Date.now()): string {
+  if (!stoppedSinceAt) return "stopped";
+  const then = new Date(stoppedSinceAt).getTime();
+  if (!Number.isFinite(then)) return "stopped";
+  const seconds = Math.max(0, Math.round((now - then) / 1000));
+  if (seconds < 60) return "stopped just now";
+  if (seconds < 3600) {
+    const m = Math.floor(seconds / 60);
+    return `stopped ${m}m`;
+  }
+  if (seconds < 86_400) {
+    const h = Math.floor(seconds / 3600);
+    return `stopped ${h}h`;
+  }
+  if (seconds < 86_400 * 7) {
+    const d = Math.floor(seconds / 86_400);
+    return `stopped ${d}d`;
+  }
+  if (seconds < 86_400 * 30) {
+    const w = Math.floor(seconds / (86_400 * 7));
+    return `stopped ${w}w`;
+  }
+  const mo = Math.floor(seconds / (86_400 * 30));
+  return `stopped ${mo}mo`;
+}
diff --git a/ui/src/lib/inbox.test.ts b/ui/src/lib/inbox.test.ts
index 97ba69bd..d0c11aff 100644
--- a/ui/src/lib/inbox.test.ts
+++ b/ui/src/lib/inbox.test.ts
@@ -1002,6 +1002,12 @@ describe("inbox helpers", () => {
     expect(loadLastInboxTab()).toBe("all");
   });
 
+  it("persists the blocked inbox tab", () => {
+    localStorage.clear();
+    saveLastInboxTab("blocked");
+    expect(loadLastInboxTab()).toBe("blocked");
+  });
+
   it("persists inbox filters per company", () => {
     saveInboxFilterPreferences("company-1", {
       allCategoryFilter: "approvals",
diff --git a/ui/src/lib/inbox.ts b/ui/src/lib/inbox.ts
index 6d623513..e33d5053 100644
--- a/ui/src/lib/inbox.ts
+++ b/ui/src/lib/inbox.ts
@@ -25,7 +25,7 @@ export const INBOX_NESTING_KEY = "paperclip:inbox:nesting";
 export const INBOX_GROUP_BY_KEY = "paperclip:inbox:group-by";
 export const INBOX_FILTER_PREFERENCES_KEY_PREFIX = "paperclip:inbox:filters";
 export const INBOX_COLLAPSED_GROUPS_KEY_PREFIX = "paperclip:inbox:collapsed-groups";
-export type InboxTab = "mine" | "recent" | "unread" | "all";
+export type InboxTab = "mine" | "recent" | "unread" | "blocked" | "all";
 export type InboxCategoryFilter =
   | "everything"
   | "issues_i_touched"
@@ -630,7 +630,13 @@ export function resolveInboxNestingEnabled(preferenceEnabled: boolean, isMobile:
 export function loadLastInboxTab(): InboxTab {
   try {
     const raw = localStorage.getItem(INBOX_LAST_TAB_KEY);
-    if (raw === "all" || raw === "unread" || raw === "recent" || raw === "mine") return raw;
+    if (
+      raw === "all"
+      || raw === "unread"
+      || raw === "recent"
+      || raw === "mine"
+      || raw === "blocked"
+    ) return raw;
     if (raw === "new") return "mine";
     return "mine";
   } catch {
diff --git a/ui/src/lib/issue-chat-messages.test.ts b/ui/src/lib/issue-chat-messages.test.ts
index 0e2a6e1c..4aa62a71 100644
--- a/ui/src/lib/issue-chat-messages.test.ts
+++ b/ui/src/lib/issue-chat-messages.test.ts
@@ -324,6 +324,72 @@ describe("buildIssueChatMessages", () => {
     });
   });
 
+  it("prefers derived agent attribution when a board-authored comment is proven to come from a run", () => {
+    const agentMap = new Map<string, Agent>([["agent-1", createAgent("agent-1", "Claude")]]);
+    const messages = buildIssueChatMessages({
+      comments: [
+        createComment({
+          authorUserId: "user-1",
+          derivedAuthorAgentId: "agent-1",
+          derivedCreatedByRunId: "run-1",
+        }),
+      ],
+      timelineEvents: [],
+      linkedRuns: [],
+      liveRuns: [],
+      agentMap,
+      currentUserId: "user-1",
+      userLabelMap: new Map([["user-1", "Dotta"]]),
+    });
+
+    expect(messages[0]).toMatchObject({
+      role: "assistant",
+      metadata: {
+        custom: {
+          authorName: "Claude",
+          authorType: "agent",
+          authorAgentId: "agent-1",
+          authorUserId: "user-1",
+          runId: "run-1",
+          runAgentId: "agent-1",
+        },
+      },
+    });
+  });
+
+  it("renders a comment as agent-authored when runAgentId is set from activity log", () => {
+    const agentMap = new Map<string, Agent>([["agent-1", createAgent("agent-1", "Claude")]]);
+    const messages = buildIssueChatMessages({
+      comments: [
+        createComment({
+          authorUserId: "user-1",
+          runId: "run-1",
+          runAgentId: "agent-1",
+        }),
+      ],
+      timelineEvents: [],
+      linkedRuns: [],
+      liveRuns: [],
+      agentMap,
+      currentUserId: "user-1",
+      userLabelMap: new Map([["user-1", "Dotta"]]),
+    });
+
+    expect(messages[0]).toMatchObject({
+      role: "assistant",
+      metadata: {
+        custom: {
+          authorName: "Claude",
+          authorType: "agent",
+          authorAgentId: "agent-1",
+          authorUserId: "user-1",
+          runId: "run-1",
+          runAgentId: "agent-1",
+        },
+      },
+    });
+  });
+
   it("orders events before comments and appends active live runs as running assistant messages", () => {
     const agentMap = new Map<string, Agent>([["agent-1", createAgent("agent-1", "CodexCoder")]]);
     const comments = [
diff --git a/ui/src/lib/issue-chat-messages.ts b/ui/src/lib/issue-chat-messages.ts
index 59d0ac90..2ff7cb8f 100644
--- a/ui/src/lib/issue-chat-messages.ts
+++ b/ui/src/lib/issue-chat-messages.ts
@@ -337,14 +337,32 @@ function createAssistantMetadata(custom: Record<string, unknown>) {
   } as const;
 }
 
+function effectiveCommentAuthorAgentId(comment: IssueChatComment) {
+  return comment.authorAgentId ?? comment.runAgentId ?? comment.derivedAuthorAgentId ?? null;
+}
+
+function effectiveCommentRunId(comment: IssueChatComment) {
+  return comment.runId ?? comment.derivedCreatedByRunId ?? null;
+}
+
+function effectiveCommentRunAgentId(comment: IssueChatComment) {
+  return comment.runAgentId ?? effectiveCommentAuthorAgentId(comment);
+}
+
+function effectiveCommentAuthorType(comment: IssueChatComment) {
+  return effectiveCommentAuthorAgentId(comment) ? "agent" : comment.authorType;
+}
+
 function authorNameForComment(
   comment: IssueChatComment,
   agentMap?: Map<string, Agent>,
   currentUserId?: string | null,
   userLabelMap?: ReadonlyMap<string, string> | null,
+  options?: { isSystemNotice?: boolean },
 ) {
-  if (comment.authorAgentId) {
-    return agentMap?.get(comment.authorAgentId)?.name ?? comment.authorAgentId.slice(0, 8);
+  const authorAgentId = effectiveCommentAuthorAgentId(comment);
+  if (authorAgentId) {
+    return agentMap?.get(authorAgentId)?.name ?? (options?.isSystemNotice ? "Paperclip" : authorAgentId.slice(0, 8));
   }
   const authorUserId = comment.authorUserId ?? null;
   if (!authorUserId) return "You";
@@ -367,20 +385,21 @@ function createCommentMessage(args: {
 }): ThreadMessage {
   const { comment, agentMap, currentUserId, userLabelMap, companyId, projectId } = args;
   const createdAt = toDate(comment.createdAt);
-  const authorName = authorNameForComment(comment, agentMap, currentUserId, userLabelMap);
   const isSystemNotice = comment.authorType === "system";
+  const authorAgentId = effectiveCommentAuthorAgentId(comment);
+  const authorName = authorNameForComment(comment, agentMap, currentUserId, userLabelMap, { isSystemNotice });
   const custom = {
     kind: isSystemNotice ? "system_notice" : "comment",
     commentId: comment.id,
     anchorId: `comment-${comment.id}`,
     authorName,
-    authorType: comment.authorType,
-    authorAgentId: comment.authorAgentId,
+    authorType: effectiveCommentAuthorType(comment),
+    authorAgentId,
     authorUserId: comment.authorUserId,
     companyId: companyId ?? comment.companyId,
     projectId: projectId ?? null,
-    runId: comment.runId ?? null,
-    runAgentId: comment.runAgentId ?? null,
+    runId: effectiveCommentRunId(comment),
+    runAgentId: effectiveCommentRunAgentId(comment),
     clientStatus: comment.clientStatus ?? null,
     queueState: comment.queueState ?? null,
     queueTargetRunId: comment.queueTargetRunId ?? null,
@@ -402,7 +421,7 @@ function createCommentMessage(args: {
     return message;
   }
 
-  if (comment.authorAgentId) {
+  if (authorAgentId) {
     const message: ThreadAssistantMessage = {
       id: comment.id,
       role: "assistant",
diff --git a/ui/src/lib/issue-detail-subissues.test.ts b/ui/src/lib/issue-detail-subissues.test.ts
index 611e677b..53b3ead5 100644
--- a/ui/src/lib/issue-detail-subissues.test.ts
+++ b/ui/src/lib/issue-detail-subissues.test.ts
@@ -3,6 +3,7 @@
 import { describe, expect, it } from "vitest";
 import type { Issue } from "@paperclipai/shared";
 import {
+  buildIssueSiblingNavigation,
   buildSubIssueProgressSummary,
   shouldRenderRichSubIssuesSection,
   shouldRenderSubIssueProgressSummary,
@@ -24,6 +25,21 @@ function issue(
   } as Issue;
 }
 
+function siblingIssue(
+  id: string,
+  createdAt: string,
+  blockedByIds: string[] = [],
+  overrides: Partial<Issue> = {},
+): Issue {
+  return {
+    ...issue(id, "todo", createdAt, blockedByIds),
+    parentId: "parent-1",
+    title: `Sibling ${id}`,
+    hiddenAt: null,
+    ...overrides,
+  } as Issue;
+}
+
 describe("shouldRenderRichSubIssuesSection", () => {
   it("shows the rich sub-issues section while child issues are loading", () => {
     expect(shouldRenderRichSubIssuesSection(true, 0)).toBe(true);
@@ -78,3 +94,112 @@ describe("buildSubIssueProgressSummary", () => {
     expect(summary.target?.issue.id).toBe("2");
   });
 });
+
+describe("buildIssueSiblingNavigation", () => {
+  it("orders linear blocker chains before selecting previous and next siblings", () => {
+    const current = siblingIssue("2", "2026-04-02T00:00:00.000Z", ["1"]);
+    const navigation = buildIssueSiblingNavigation(current, [
+      siblingIssue("3", "2026-04-03T00:00:00.000Z", ["2"]),
+      siblingIssue("1", "2026-04-01T00:00:00.000Z"),
+      current,
+    ]);
+
+    expect(navigation?.previous?.id).toBe("1");
+    expect(navigation?.next?.id).toBe("3");
+    expect(navigation?.currentIndex).toBe(1);
+    expect(navigation?.totalCount).toBe(3);
+  });
+
+  it("degrades branch and merge graphs to stable workflow order", () => {
+    const current = siblingIssue("3", "2026-04-03T00:00:00.000Z", ["1"]);
+    const navigation = buildIssueSiblingNavigation(current, [
+      siblingIssue("4", "2026-04-04T00:00:00.000Z", ["2", "3"]),
+      siblingIssue("2", "2026-04-02T00:00:00.000Z", ["1"]),
+      current,
+      siblingIssue("1", "2026-04-01T00:00:00.000Z"),
+    ]);
+
+    expect(navigation?.previous?.id).toBe("2");
+    expect(navigation?.next?.id).toBe("4");
+  });
+
+  it("falls back to created time and id when siblings have no direct blocker hints", () => {
+    const current = siblingIssue("2", "2026-04-01T00:00:00.000Z");
+    const navigation = buildIssueSiblingNavigation(current, [
+      siblingIssue("3", "2026-04-02T00:00:00.000Z"),
+      siblingIssue("1", "2026-04-01T00:00:00.000Z"),
+      current,
+    ]);
+
+    expect(navigation?.previous?.id).toBe("1");
+    expect(navigation?.next?.id).toBe("3");
+  });
+
+  it("hides navigation for root issues without children or hidden current issues", () => {
+    expect(buildIssueSiblingNavigation(siblingIssue("1", "2026-04-01T00:00:00.000Z", [], { parentId: null }), []))
+      .toBeNull();
+    expect(buildIssueSiblingNavigation(siblingIssue("1", "2026-04-01T00:00:00.000Z", [], { parentId: null }), [
+      siblingIssue("2", "2026-04-02T00:00:00.000Z", [], { parentId: null }),
+    ])).toBeNull();
+    expect(buildIssueSiblingNavigation(siblingIssue("1", "2026-04-01T00:00:00.000Z", [], { hiddenAt: new Date() }), []))
+      .toBeNull();
+  });
+
+  it("hides navigation when the current issue is the only visible child", () => {
+    const current = siblingIssue("1", "2026-04-01T00:00:00.000Z");
+    const navigation = buildIssueSiblingNavigation(current, [
+      current,
+      siblingIssue("2", "2026-04-02T00:00:00.000Z", [], { hiddenAt: new Date() }),
+    ]);
+
+    expect(navigation).toBeNull();
+  });
+
+  it("returns only next for the first sibling and only previous for the last sibling", () => {
+    const first = siblingIssue("1", "2026-04-01T00:00:00.000Z");
+    const last = siblingIssue("3", "2026-04-03T00:00:00.000Z");
+    const siblings = [
+      siblingIssue("2", "2026-04-02T00:00:00.000Z"),
+      last,
+      first,
+    ];
+
+    expect(buildIssueSiblingNavigation(first, siblings)).toMatchObject({
+      previous: null,
+      next: { id: "2" },
+    });
+    expect(buildIssueSiblingNavigation(last, siblings)).toMatchObject({
+      previous: { id: "2" },
+      next: null,
+    });
+  });
+
+  it("uses the first direct child as next when a root issue has no sibling next", () => {
+    const current = siblingIssue("1", "2026-04-01T00:00:00.000Z", [], { parentId: null });
+    const navigation = buildIssueSiblingNavigation(current, [], [
+      siblingIssue("3", "2026-04-03T00:00:00.000Z", ["2"], { parentId: "1" }),
+      siblingIssue("2", "2026-04-02T00:00:00.000Z", [], { parentId: "1" }),
+    ]);
+
+    expect(navigation).toMatchObject({
+      previous: null,
+      next: { id: "2" },
+    });
+  });
+
+  it("uses the first direct child as next when the current sibling is last", () => {
+    const current = siblingIssue("2", "2026-04-02T00:00:00.000Z");
+    const navigation = buildIssueSiblingNavigation(current, [
+      siblingIssue("1", "2026-04-01T00:00:00.000Z"),
+      current,
+    ], [
+      siblingIssue("4", "2026-04-04T00:00:00.000Z", ["3"], { parentId: "2" }),
+      siblingIssue("3", "2026-04-03T00:00:00.000Z", [], { parentId: "2" }),
+    ]);
+
+    expect(navigation).toMatchObject({
+      previous: { id: "1" },
+      next: { id: "3" },
+    });
+  });
+});
diff --git a/ui/src/lib/issue-detail-subissues.ts b/ui/src/lib/issue-detail-subissues.ts
index 379ca8c1..40274675 100644
--- a/ui/src/lib/issue-detail-subissues.ts
+++ b/ui/src/lib/issue-detail-subissues.ts
@@ -17,6 +17,13 @@ export type SubIssueProgressSummary = {
   target: SubIssueProgressTarget | null;
 };
 
+export type IssueSiblingNavigation = {
+  previous: Issue | null;
+  next: Issue | null;
+  currentIndex: number;
+  totalCount: number;
+};
+
 export function shouldRenderRichSubIssuesSection(childIssuesLoading: boolean, childIssueCount: number): boolean {
   return childIssuesLoading || childIssueCount > 0;
 }
@@ -56,6 +63,57 @@ export function buildSubIssueProgressSummary(issues: Issue[]): SubIssueProgressS
   };
 }
 
+export function buildIssueSiblingNavigation(
+  currentIssue: Issue,
+  siblingIssues: Issue[],
+  childIssues: Issue[] = [],
+): IssueSiblingNavigation | null {
+  if (currentIssue.hiddenAt) return null;
+
+  const byId = new Map<string, Issue>();
+  if (currentIssue.parentId) {
+    for (const issue of siblingIssues) {
+      if (issue.parentId !== currentIssue.parentId || issue.hiddenAt) continue;
+      byId.set(
+        issue.id,
+        issue.id === currentIssue.id
+          ? { ...issue, ...currentIssue, blockedBy: currentIssue.blockedBy ?? issue.blockedBy }
+          : issue,
+      );
+    }
+    if (!byId.has(currentIssue.id)) byId.set(currentIssue.id, currentIssue);
+  }
+
+  const ordered = workflowSort(Array.from(byId.values()));
+  const currentIndex = ordered.findIndex((issue) => issue.id === currentIssue.id);
+  const directChildren = workflowSort(
+    childIssues.filter((issue) => issue.parentId === currentIssue.id && !issue.hiddenAt),
+  );
+  const firstChild = directChildren[0] ?? null;
+
+  if (currentIndex < 0) {
+    return firstChild
+      ? {
+          previous: null,
+          next: firstChild,
+          currentIndex: 0,
+          totalCount: directChildren.length + 1,
+        }
+      : null;
+  }
+
+  const previous = currentIndex > 0 ? ordered[currentIndex - 1] : null;
+  const next = currentIndex < ordered.length - 1 ? ordered[currentIndex + 1] : firstChild;
+  if (!previous && !next) return null;
+
+  return {
+    previous,
+    next,
+    currentIndex,
+    totalCount: ordered.length,
+  };
+}
+
 function isActionableStatus(status: IssueStatus): boolean {
   return status !== "done" && status !== "cancelled" && status !== "blocked";
 }
diff --git a/ui/src/lib/queryKeys.ts b/ui/src/lib/queryKeys.ts
index 24aa097f..302199f6 100644
--- a/ui/src/lib/queryKeys.ts
+++ b/ui/src/lib/queryKeys.ts
@@ -38,6 +38,8 @@ export const queryKeys = {
     listMineByMe: (companyId: string) => ["issues", companyId, "mine-by-me"] as const,
     listTouchedByMe: (companyId: string) => ["issues", companyId, "touched-by-me"] as const,
     listUnreadTouchedByMe: (companyId: string) => ["issues", companyId, "unread-touched-by-me"] as const,
+    listBlockedAttention: (companyId: string) => ["issues", companyId, "blocked-attention"] as const,
+    countBlockedAttention: (companyId: string) => ["issues", companyId, "blocked-attention", "count"] as const,
     labels: (companyId: string) => ["issues", companyId, "labels"] as const,
     listByProject: (companyId: string, projectId: string) =>
       ["issues", companyId, "project", projectId] as const,
diff --git a/ui/src/lib/recovery-display.ts b/ui/src/lib/recovery-display.ts
new file mode 100644
index 00000000..8a5dc346
--- /dev/null
+++ b/ui/src/lib/recovery-display.ts
@@ -0,0 +1,57 @@
+import type { IssueRecoveryAction } from "@paperclipai/shared";
+import { Eye, OctagonAlert, RefreshCw, TriangleAlert } from "lucide-react";
+
+export type RecoveryDisplayState =
+  | "needed"
+  | "in_progress"
+  | "observe_only"
+  | "escalated"
+  | "resolved";
+
+export type ActiveRecoveryDisplayState = Exclude<RecoveryDisplayState, "resolved">;
+
+export const RECOVERY_CHIP_DEFAULT_TONE: Record<
+  ActiveRecoveryDisplayState,
+  { className: string; icon: typeof TriangleAlert; label: string }
+> = {
+  needed: {
+    className:
+      "border-amber-500/60 bg-amber-500/15 text-amber-700 dark:text-amber-300",
+    icon: TriangleAlert,
+    label: "Recovery needed",
+  },
+  in_progress: {
+    className:
+      "border-sky-500/60 bg-sky-500/15 text-sky-700 dark:text-sky-300",
+    icon: RefreshCw,
+    label: "Recovery in progress",
+  },
+  observe_only: {
+    className: "border-border bg-muted text-muted-foreground",
+    icon: Eye,
+    label: "Observing active run",
+  },
+  escalated: {
+    className: "border-red-500/60 bg-red-500/15 text-red-700 dark:text-red-300",
+    icon: OctagonAlert,
+    label: "Recovery escalated",
+  },
+};
+
+export function deriveRecoveryDisplayState(
+  action: Pick<IssueRecoveryAction, "status" | "kind" | "outcome">,
+): RecoveryDisplayState {
+  if (action.status === "resolved") return "resolved";
+  if (action.status === "escalated") return "escalated";
+  if (action.status === "cancelled") return "resolved";
+  if (action.kind === "active_run_watchdog") return "observe_only";
+  if (action.outcome === "delegated") return "in_progress";
+  return "needed";
+}
+
+export function deriveActiveRecoveryDisplayState(
+  action: Pick<IssueRecoveryAction, "status" | "kind" | "outcome">,
+): ActiveRecoveryDisplayState | null {
+  const state = deriveRecoveryDisplayState(action);
+  return state === "resolved" ? null : state;
+}
diff --git a/ui/src/lib/router.tsx b/ui/src/lib/router.tsx
index 0ec23ede..48891144 100644
--- a/ui/src/lib/router.tsx
+++ b/ui/src/lib/router.tsx
@@ -46,10 +46,19 @@ export * from "react-router-dom";
 type CompanyLinkProps = React.ComponentProps<typeof RouterDom.Link> & {
   disableIssueQuicklook?: boolean;
   issuePrefetch?: Issue | null;
+  issueQuicklookSide?: React.ComponentProps<typeof IssueLinkQuicklook>["issueQuicklookSide"];
+  issueQuicklookAlign?: React.ComponentProps<typeof IssueLinkQuicklook>["issueQuicklookAlign"];
 };
 
 export const Link = React.forwardRef<HTMLAnchorElement, CompanyLinkProps>(
-  function CompanyLink({ to, disableIssueQuicklook = false, issuePrefetch = null, ...props }, ref) {
+  function CompanyLink({
+    to,
+    disableIssueQuicklook = false,
+    issuePrefetch = null,
+    issueQuicklookSide,
+    issueQuicklookAlign,
+    ...props
+  }, ref) {
     const companyPrefix = useActiveCompanyPrefix();
     const resolvedTo = resolveTo(to, companyPrefix);
     const issuePathId = parseIssuePathIdFromPath(typeof resolvedTo === "string" ? resolvedTo : resolvedTo.pathname);
@@ -62,6 +71,8 @@ export const Link = React.forwardRef<HTMLAnchorElement, CompanyLinkProps>(
           issuePathId={issuePathId}
           disableIssueQuicklook={disableIssueQuicklook}
           issuePrefetch={issuePrefetch}
+          issueQuicklookSide={issueQuicklookSide}
+          issueQuicklookAlign={issueQuicklookAlign}
           {...props}
         />
       );
diff --git a/ui/src/pages/Inbox.test.tsx b/ui/src/pages/Inbox.test.tsx
index dcac90ee..a23af8e7 100644
--- a/ui/src/pages/Inbox.test.tsx
+++ b/ui/src/pages/Inbox.test.tsx
@@ -3,11 +3,124 @@
 import { act } from "react";
 import type { ComponentProps } from "react";
 import { createRoot } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import type { Issue } from "@paperclipai/shared";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { CompanyJoinRequest } from "../api/access";
+
+const routerMock = vi.hoisted(() => ({
+  location: { pathname: "/", search: "", hash: "" },
+  navigate: vi.fn(),
+}));
+
+const apiMocks = vi.hoisted(() => ({
+  approvalsList: vi.fn(),
+  joinRequestsList: vi.fn(),
+  userDirectoryList: vi.fn(),
+  authSession: vi.fn(),
+  dashboardSummary: vi.fn(),
+  executionWorkspaceSummaries: vi.fn(),
+  issuesList: vi.fn(),
+  issuesCount: vi.fn(),
+  issueLabels: vi.fn(),
+  agentsList: vi.fn(),
+  heartbeatRunsList: vi.fn(),
+  liveRunsForCompany: vi.fn(),
+  experimentalSettings: vi.fn(),
+  projectsList: vi.fn(),
+}));
+
+vi.mock("../api/approvals", () => ({
+  approvalsApi: { list: apiMocks.approvalsList },
+}));
+
+vi.mock("../api/access", async () => {
+  const actual = await vi.importActual<typeof import("../api/access")>("../api/access");
+  return {
+    ...actual,
+    accessApi: {
+      listJoinRequests: apiMocks.joinRequestsList,
+      listUserDirectory: apiMocks.userDirectoryList,
+    },
+  };
+});
+
+vi.mock("../api/auth", () => ({
+  authApi: { getSession: apiMocks.authSession },
+}));
+
+vi.mock("../api/dashboard", () => ({
+  dashboardApi: { summary: apiMocks.dashboardSummary },
+}));
+
+vi.mock("../api/execution-workspaces", () => ({
+  executionWorkspacesApi: { listSummaries: apiMocks.executionWorkspaceSummaries },
+}));
+
+vi.mock("../api/issues", () => ({
+  issuesApi: {
+    list: apiMocks.issuesList,
+    count: apiMocks.issuesCount,
+    listLabels: apiMocks.issueLabels,
+    markRead: vi.fn(),
+    markUnread: vi.fn(),
+    archiveFromInbox: vi.fn(),
+    unarchiveFromInbox: vi.fn(),
+  },
+}));
+
+vi.mock("../api/agents", () => ({
+  agentsApi: { list: apiMocks.agentsList },
+}));
+
+vi.mock("../api/heartbeats", () => ({
+  heartbeatsApi: {
+    list: apiMocks.heartbeatRunsList,
+    liveRunsForCompany: apiMocks.liveRunsForCompany,
+  },
+}));
+
+vi.mock("../api/instanceSettings", () => ({
+  instanceSettingsApi: { getExperimental: apiMocks.experimentalSettings },
+}));
+
+vi.mock("../api/projects", () => ({
+  projectsApi: { list: apiMocks.projectsList },
+}));
+
+vi.mock("../context/CompanyContext", () => ({
+  useCompany: () => ({ selectedCompanyId: "company-1" }),
+}));
+
+vi.mock("../context/BreadcrumbContext", () => ({
+  useBreadcrumbs: () => ({ setBreadcrumbs: vi.fn() }),
+}));
+
+vi.mock("../context/DialogContext", () => ({
+  useDialogActions: () => ({ openNewIssue: vi.fn() }),
+}));
+
+vi.mock("../context/SidebarContext", () => ({
+  useSidebar: () => ({ isMobile: false }),
+}));
+
+vi.mock("../context/GeneralSettingsContext", () => ({
+  useGeneralSettings: () => ({ keyboardShortcutsEnabled: false }),
+}));
+
+vi.mock("../hooks/useInboxBadge", () => ({
+  useDismissedInboxAlerts: () => ({ dismissed: new Set(), dismiss: vi.fn() }),
+  useInboxDismissals: () => ({ dismissedAtByKey: new Map(), dismiss: vi.fn() }),
+  useReadInboxItems: () => ({
+    readItems: new Set(),
+    markRead: vi.fn(),
+    markUnread: vi.fn(),
+  }),
+}));
+
 import {
   FailedRunInboxRow,
+  Inbox,
   InboxGroupHeader,
   InboxIssueMetaLeading,
   InboxIssueTrailingColumns,
@@ -18,8 +131,8 @@ vi.mock("@/lib/router", () => ({
   Link: ({ children, className, ...props }: ComponentProps<"a">) => (
     <a className={className} {...props}>{children}</a>
   ),
-  useLocation: () => ({ pathname: "/", search: "", hash: "" }),
-  useNavigate: () => () => {},
+  useLocation: () => routerMock.location,
+  useNavigate: () => routerMock.navigate,
 }));
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -108,6 +221,76 @@ function createJoinRequest(
   };
 }
 
+function resetInboxApiMocks() {
+  routerMock.location.pathname = "/";
+  routerMock.location.search = "";
+  routerMock.location.hash = "";
+  routerMock.navigate.mockReset();
+  apiMocks.approvalsList.mockResolvedValue([]);
+  apiMocks.joinRequestsList.mockResolvedValue([]);
+  apiMocks.userDirectoryList.mockResolvedValue({ users: [] });
+  apiMocks.authSession.mockResolvedValue({
+    user: { id: "local-board" },
+    session: { userId: "local-board" },
+  });
+  apiMocks.dashboardSummary.mockResolvedValue({
+    agents: { error: 0 },
+    costs: { monthBudgetCents: 0, monthUtilizationPercent: 0 },
+  });
+  apiMocks.executionWorkspaceSummaries.mockResolvedValue([]);
+  apiMocks.issuesList.mockResolvedValue([]);
+  apiMocks.issuesCount.mockResolvedValue({ count: 0 });
+  apiMocks.issueLabels.mockResolvedValue([]);
+  apiMocks.agentsList.mockResolvedValue([]);
+  apiMocks.heartbeatRunsList.mockResolvedValue([]);
+  apiMocks.liveRunsForCompany.mockResolvedValue([]);
+  apiMocks.experimentalSettings.mockResolvedValue({ enableIsolatedWorkspaces: false });
+  apiMocks.projectsList.mockResolvedValue([]);
+}
+
+describe("Inbox toolbar", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    resetInboxApiMocks();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it("shows blocked toolbar controls on the Blocked tab", async () => {
+    routerMock.location.pathname = "/inbox/blocked";
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false, staleTime: 0, gcTime: 0 } },
+    });
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <Inbox />
+        </QueryClientProvider>,
+      );
+    });
+
+    expect(container.querySelector('input[placeholder="Search inbox…"]')).not.toBeNull();
+    expect(container.querySelector('[data-testid="inbox-blocked-tab-badge"]')).toBeNull();
+    expect(container.querySelector('button[title="Filter"]')).not.toBeNull();
+    expect(container.querySelector('button[title="Group"]')).not.toBeNull();
+    expect(container.querySelector('button[title="Columns"]')).not.toBeNull();
+    expect(container.querySelector('button[title="Sort"]')).not.toBeNull();
+    expect(container.querySelector('button[title="Enable parent-child nesting"]')).toBeNull();
+    expect(container.textContent).not.toContain("Mark all as read");
+
+    act(() => {
+      root.unmount();
+    });
+  });
+});
+
 describe("FailedRunInboxRow", () => {
   let container: HTMLDivElement;
 
diff --git a/ui/src/pages/Inbox.tsx b/ui/src/pages/Inbox.tsx
index 0c8dbb3a..4c5a9574 100644
--- a/ui/src/pages/Inbox.tsx
+++ b/ui/src/pages/Inbox.tsx
@@ -13,6 +13,12 @@ import { agentsApi } from "../api/agents";
 import { heartbeatsApi } from "../api/heartbeats";
 import { instanceSettingsApi } from "../api/instanceSettings";
 import { projectsApi } from "../api/projects";
+import {
+  BLOCKED_GROUP_OPTIONS,
+  BLOCKED_SORT_OPTIONS,
+  type BlockedInboxGroupBy,
+  type BlockedInboxSort,
+} from "../lib/blockedInbox";
 import { useCompany } from "../context/CompanyContext";
 import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { useGeneralSettings } from "../context/GeneralSettingsContext";
@@ -54,6 +60,7 @@ import {
 } from "../components/IssueColumns";
 import { IssueFiltersPopover } from "../components/IssueFiltersPopover";
 import { IssueRow } from "../components/IssueRow";
+import { BlockedInboxView } from "../components/BlockedInboxView";
 import { SwipeToArchive } from "../components/SwipeToArchive";
 
 import { StatusIcon } from "../components/StatusIcon";
@@ -85,6 +92,7 @@ import {
   AlertTriangle,
   Check,
   ChevronRight,
+  ArrowUpDown,
   Layers,
   Plus,
   XCircle,
@@ -674,6 +682,8 @@ export function Inbox() {
     () => loadInboxFilterPreferences(selectedCompanyId),
   );
   const [groupBy, setGroupBy] = useState<InboxWorkItemGroupBy>(() => loadInboxWorkItemGroupBy());
+  const [blockedGroupBy, setBlockedGroupBy] = useState<BlockedInboxGroupBy>("none");
+  const [blockedSortBy, setBlockedSortBy] = useState<BlockedInboxSort>("most_recent");
   const [visibleIssueColumns, setVisibleIssueColumns] = useState<InboxIssueColumn[]>(loadInboxIssueColumns);
   const { dismissed: dismissedAlerts, dismiss: dismissAlert } = useDismissedInboxAlerts();
   const { dismissedAtByKey, dismiss: dismissInboxItem } = useInboxDismissals(selectedCompanyId);
@@ -682,7 +692,11 @@ export function Inbox() {
 
   const pathSegment = location.pathname.split("/").pop() ?? "mine";
   const tab: InboxTab =
-    pathSegment === "mine" || pathSegment === "recent" || pathSegment === "all" || pathSegment === "unread"
+    pathSegment === "mine"
+    || pathSegment === "recent"
+    || pathSegment === "all"
+    || pathSegment === "unread"
+    || pathSegment === "blocked"
       ? pathSegment
       : "mine";
   const canArchiveFromTab = isMineInboxTab(tab);
@@ -824,7 +838,6 @@ export function Inbox() {
     queryFn: () => heartbeatsApi.list(selectedCompanyId!, undefined, INBOX_HEARTBEAT_RUN_LIMIT),
     enabled: !!selectedCompanyId,
   });
-
   const { data: liveRuns } = useQuery({
     queryKey: queryKeys.liveRuns(selectedCompanyId!),
     queryFn: () => heartbeatsApi.liveRunsForCompany(selectedCompanyId!),
@@ -1902,6 +1915,7 @@ export function Inbox() {
     .map((issue) => issue.id);
   const canMarkAllRead = unreadIssueIds.length > 0;
   const activeIssueFilterCount = countActiveIssueFilters(issueFilters, true);
+  const showGeneralIssueToolbarControls = tab !== "blocked";
   return (
     <div className="space-y-6">
       <div className="space-y-2">
@@ -1947,6 +1961,7 @@ export function Inbox() {
                 label: "Recent",
               },
               { value: "unread", label: "Unread" },
+              { value: "blocked", label: "Blocked" },
               { value: "all", label: "All" },
             ]}
           />
@@ -1981,112 +1996,203 @@ export function Inbox() {
               data-page-search-target="true"
             />
           </div>
-          <Button
-            type="button"
-            variant="outline"
-            size="icon"
-            className={cn("hidden h-8 w-8 shrink-0 sm:inline-flex", nestingEnabled && "bg-accent")}
-            onClick={toggleNesting}
-            title={nestingEnabled ? "Disable parent-child nesting" : "Enable parent-child nesting"}
-          >
-            <ListTree className="h-3.5 w-3.5" />
-          </Button>
-          <IssueFiltersPopover
-            state={issueFilters}
-            onChange={updateIssueFilters}
-            activeFilterCount={activeIssueFilterCount}
-            agents={agents}
-            creators={creatorOptions}
-            projects={projects?.map((project) => ({ id: project.id, name: project.name }))}
-            labels={labels?.map((label) => ({ id: label.id, name: label.name, color: label.color }))}
-            currentUserId={currentUserId}
-            enableRoutineVisibilityFilter
-            buttonVariant="outline"
-            iconOnly
-            workspaces={isolatedWorkspacesEnabled ? executionWorkspaces.filter((w) => w.mode === "isolated_workspace").map((w) => ({ id: w.id, name: w.name })) : undefined}
-          />
-          <Popover>
-            <PopoverTrigger asChild>
-              <Button
-                type="button"
-                variant="outline"
-                size="icon"
-                className={cn("h-8 w-8 shrink-0", groupBy !== "none" && "bg-accent")}
-                title="Group"
-              >
-                <Layers className="h-3.5 w-3.5" />
-              </Button>
-            </PopoverTrigger>
-            <PopoverContent align="end" className="w-40 p-2">
-              <div className="space-y-0.5">
-                {([
-                  ["none", "None"],
-                  ["type", "Type"],
-                  ["assignee", "Assignee"],
-                  ["project", "Project"],
-                  ...(isolatedWorkspacesEnabled ? ([["workspace", "Workspace"]] as const) : []),
-                ] as const).map(([value, label]) => (
-                  <button
-                    key={value}
+          {tab === "blocked" ? (
+            <>
+              <IssueFiltersPopover
+                state={issueFilters}
+                onChange={updateIssueFilters}
+                activeFilterCount={activeIssueFilterCount}
+                agents={agents}
+                creators={creatorOptions}
+                projects={projects?.map((project) => ({ id: project.id, name: project.name }))}
+                labels={labels?.map((label) => ({ id: label.id, name: label.name, color: label.color }))}
+                currentUserId={currentUserId}
+                enableRoutineVisibilityFilter
+                buttonVariant="outline"
+                iconOnly
+                workspaces={isolatedWorkspacesEnabled ? executionWorkspaces.filter((w) => w.mode === "isolated_workspace").map((w) => ({ id: w.id, name: w.name })) : undefined}
+              />
+              <Popover>
+                <PopoverTrigger asChild>
+                  <Button
                     type="button"
-                    className={cn(
-                      "flex w-full items-center justify-between rounded-sm px-2 py-1.5 text-sm",
-                      groupBy === value ? "bg-accent/50 text-foreground" : "text-muted-foreground hover:bg-accent/50",
-                    )}
-                    onClick={() => updateGroupBy(value)}
+                    variant="outline"
+                    size="icon"
+                    className={cn("h-8 w-8 shrink-0", blockedGroupBy !== "none" && "bg-accent")}
+                    title="Group"
                   >
-                    <span>{label}</span>
-                    {groupBy === value ? <Check className="h-3.5 w-3.5" /> : null}
-                  </button>
-                ))}
-              </div>
-            </PopoverContent>
-          </Popover>
-          <IssueColumnPicker
-            availableColumns={availableIssueColumns}
-            visibleColumnSet={visibleIssueColumnSet}
-            onToggleColumn={toggleIssueColumn}
-            onResetColumns={() => setIssueColumns(DEFAULT_INBOX_ISSUE_COLUMNS)}
-            title="Choose which inbox columns stay visible"
-            iconOnly
-          />
-          {canMarkAllRead && (
+                    <Layers className="h-3.5 w-3.5" />
+                  </Button>
+                </PopoverTrigger>
+                <PopoverContent align="end" className="w-44 p-0">
+                  <div className="space-y-0.5 p-2">
+                    {BLOCKED_GROUP_OPTIONS.map(([value, label]) => (
+                      <button
+                        key={value}
+                        type="button"
+                        className={cn(
+                          "flex w-full items-center justify-between rounded-sm px-2 py-1.5 text-sm",
+                          blockedGroupBy === value ? "bg-accent/50 text-foreground" : "text-muted-foreground hover:bg-accent/50",
+                        )}
+                        onClick={() => setBlockedGroupBy(value)}
+                      >
+                        <span>{label}</span>
+                        {blockedGroupBy === value ? <Check className="h-3.5 w-3.5" /> : null}
+                      </button>
+                    ))}
+                  </div>
+                </PopoverContent>
+              </Popover>
+              <IssueColumnPicker
+                availableColumns={availableIssueColumns}
+                visibleColumnSet={visibleIssueColumnSet}
+                onToggleColumn={toggleIssueColumn}
+                onResetColumns={() => setIssueColumns(DEFAULT_INBOX_ISSUE_COLUMNS)}
+                title="Choose which inbox columns stay visible"
+                iconOnly
+              />
+              <Popover>
+                <PopoverTrigger asChild>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="icon"
+                    className="h-8 w-8 shrink-0"
+                    title="Sort"
+                  >
+                    <ArrowUpDown className="h-3.5 w-3.5" />
+                  </Button>
+                </PopoverTrigger>
+                <PopoverContent align="end" className="w-48 p-0">
+                  <div className="space-y-0.5 p-2">
+                    {BLOCKED_SORT_OPTIONS.map(([value, label]) => (
+                      <button
+                        key={value}
+                        type="button"
+                        className={cn(
+                          "flex w-full items-center justify-between rounded-sm px-2 py-1.5 text-sm",
+                          blockedSortBy === value ? "bg-accent/50 text-foreground" : "text-muted-foreground hover:bg-accent/50",
+                        )}
+                        onClick={() => setBlockedSortBy(value)}
+                      >
+                        <span>{label}</span>
+                        {blockedSortBy === value ? <Check className="h-3.5 w-3.5" /> : null}
+                      </button>
+                    ))}
+                  </div>
+                </PopoverContent>
+              </Popover>
+            </>
+          ) : showGeneralIssueToolbarControls ? (
             <>
               <Button
                 type="button"
                 variant="outline"
-                size="sm"
-                className="h-8 shrink-0"
-                onClick={() => setShowMarkAllReadConfirm(true)}
-                disabled={markAllReadMutation.isPending}
+                size="icon"
+                className={cn("hidden h-8 w-8 shrink-0 sm:inline-flex", nestingEnabled && "bg-accent")}
+                onClick={toggleNesting}
+                title={nestingEnabled ? "Disable parent-child nesting" : "Enable parent-child nesting"}
               >
-                {markAllReadMutation.isPending ? "Marking…" : "Mark all as read"}
+                <ListTree className="h-3.5 w-3.5" />
               </Button>
-              <Dialog open={showMarkAllReadConfirm} onOpenChange={setShowMarkAllReadConfirm}>
-                <DialogContent className="sm:max-w-md">
-                  <DialogHeader>
-                    <DialogTitle>Mark all as read?</DialogTitle>
-                    <DialogDescription>
-                      This will mark {unreadIssueIds.length} unread {unreadIssueIds.length === 1 ? "item" : "items"} as read.
-                    </DialogDescription>
-                  </DialogHeader>
-                  <DialogFooter>
-                    <Button variant="outline" onClick={() => setShowMarkAllReadConfirm(false)}>
-                      Cancel
-                    </Button>
-                    <Button
-                      onClick={() => {
-                        setShowMarkAllReadConfirm(false);
-                        markAllReadMutation.mutate(unreadIssueIds);
-                      }}
-                    >
-                      Mark all as read
-                    </Button>
-                  </DialogFooter>
-                </DialogContent>
-              </Dialog>
+              <IssueFiltersPopover
+                state={issueFilters}
+                onChange={updateIssueFilters}
+                activeFilterCount={activeIssueFilterCount}
+                agents={agents}
+                creators={creatorOptions}
+                projects={projects?.map((project) => ({ id: project.id, name: project.name }))}
+                labels={labels?.map((label) => ({ id: label.id, name: label.name, color: label.color }))}
+                currentUserId={currentUserId}
+                enableRoutineVisibilityFilter
+                buttonVariant="outline"
+                iconOnly
+                workspaces={isolatedWorkspacesEnabled ? executionWorkspaces.filter((w) => w.mode === "isolated_workspace").map((w) => ({ id: w.id, name: w.name })) : undefined}
+              />
+              <Popover>
+                <PopoverTrigger asChild>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="icon"
+                    className={cn("h-8 w-8 shrink-0", groupBy !== "none" && "bg-accent")}
+                    title="Group"
+                  >
+                    <Layers className="h-3.5 w-3.5" />
+                  </Button>
+                </PopoverTrigger>
+                <PopoverContent align="end" className="w-40 p-2">
+                  <div className="space-y-0.5">
+                    {([
+                      ["none", "None"],
+                      ["type", "Type"],
+                      ["assignee", "Assignee"],
+                      ["project", "Project"],
+                      ...(isolatedWorkspacesEnabled ? ([["workspace", "Workspace"]] as const) : []),
+                    ] as const).map(([value, label]) => (
+                      <button
+                        key={value}
+                        type="button"
+                        className={cn(
+                          "flex w-full items-center justify-between rounded-sm px-2 py-1.5 text-sm",
+                          groupBy === value ? "bg-accent/50 text-foreground" : "text-muted-foreground hover:bg-accent/50",
+                        )}
+                        onClick={() => updateGroupBy(value)}
+                      >
+                        <span>{label}</span>
+                        {groupBy === value ? <Check className="h-3.5 w-3.5" /> : null}
+                      </button>
+                    ))}
+                  </div>
+                </PopoverContent>
+              </Popover>
+              <IssueColumnPicker
+                availableColumns={availableIssueColumns}
+                visibleColumnSet={visibleIssueColumnSet}
+                onToggleColumn={toggleIssueColumn}
+                onResetColumns={() => setIssueColumns(DEFAULT_INBOX_ISSUE_COLUMNS)}
+                title="Choose which inbox columns stay visible"
+                iconOnly
+              />
+              {canMarkAllRead && (
+                <>
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    className="h-8 shrink-0"
+                    onClick={() => setShowMarkAllReadConfirm(true)}
+                    disabled={markAllReadMutation.isPending}
+                  >
+                    {markAllReadMutation.isPending ? "Marking…" : "Mark all as read"}
+                  </Button>
+                  <Dialog open={showMarkAllReadConfirm} onOpenChange={setShowMarkAllReadConfirm}>
+                    <DialogContent className="sm:max-w-md">
+                      <DialogHeader>
+                        <DialogTitle>Mark all as read?</DialogTitle>
+                        <DialogDescription>
+                          This will mark {unreadIssueIds.length} unread {unreadIssueIds.length === 1 ? "item" : "items"} as read.
+                        </DialogDescription>
+                      </DialogHeader>
+                      <DialogFooter>
+                        <Button variant="outline" onClick={() => setShowMarkAllReadConfirm(false)}>
+                          Cancel
+                        </Button>
+                        <Button
+                          onClick={() => {
+                            setShowMarkAllReadConfirm(false);
+                            markAllReadMutation.mutate(unreadIssueIds);
+                          }}
+                        >
+                          Mark all as read
+                        </Button>
+                      </DialogFooter>
+                    </DialogContent>
+                  </Dialog>
+                </>
+              )}
             </>
-          )}
+          ) : null}
         </div>
         </div>
       </div>
@@ -2131,11 +2237,30 @@ export function Inbox() {
       {approvalsError && <p className="text-sm text-destructive">{approvalsError.message}</p>}
       {actionError && <p className="text-sm text-destructive">{actionError}</p>}
 
-      {!allLoaded && visibleSections.length === 0 && (
+      {tab === "blocked" ? (
+        <BlockedInboxView
+          companyId={selectedCompanyId!}
+          searchQuery={searchQuery}
+          agentNameById={agentById}
+          userLabelById={companyUserLabelMap}
+          issueLinkState={issueLinkState}
+          groupBy={blockedGroupBy}
+          sortBy={blockedSortBy}
+          issueFilters={issueFilters}
+          currentUserId={currentUserId}
+          liveIssueIds={liveIssueIds}
+          workspaceFilterContext={inboxWorkspaceGrouping}
+          showStatusColumn={visibleIssueColumnSet.has("status") && availableIssueColumnSet.has("status")}
+          showIdentifierColumn={visibleIssueColumnSet.has("id") && availableIssueColumnSet.has("id")}
+          showUpdatedColumn={visibleIssueColumnSet.has("updated") && availableIssueColumnSet.has("updated")}
+        />
+      ) : null}
+
+      {tab !== "blocked" && !allLoaded && visibleSections.length === 0 && (
         <PageSkeleton variant="inbox" />
       )}
 
-      {allLoaded && visibleSections.length === 0 && (
+      {tab !== "blocked" && allLoaded && visibleSections.length === 0 && (
         <EmptyState
           icon={searchQuery.trim() ? Search : InboxIcon}
           message={
@@ -2152,7 +2277,7 @@ export function Inbox() {
         />
       )}
 
-      {showWorkItemsSection && (
+      {tab !== "blocked" && showWorkItemsSection && (
         <>
           {showSeparatorBefore("work_items") && <Separator />}
           <div>
diff --git a/ui/src/pages/IssueDetail.test.tsx b/ui/src/pages/IssueDetail.test.tsx
index 331d71ca..98f611d1 100644
--- a/ui/src/pages/IssueDetail.test.tsx
+++ b/ui/src/pages/IssueDetail.test.tsx
@@ -2,10 +2,10 @@
 
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import type { Agent, Issue, IssueTreeControlPreview, IssueTreeHold } from "@paperclipai/shared";
-import { act, type ButtonHTMLAttributes, type ReactNode } from "react";
+import { act, type AnchorHTMLAttributes, type ButtonHTMLAttributes, type ReactNode } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { IssueDetail } from "./IssueDetail";
+import { canBoardResolveRecoveryAction, IssueDetail } from "./IssueDetail";
 
 const mockIssuesApi = vi.hoisted(() => ({
   get: vi.fn(),
@@ -110,7 +110,24 @@ vi.mock("../api/instanceSettings", () => ({
 }));
 
 vi.mock("@/lib/router", () => ({
-  Link: ({ children, to }: { children?: ReactNode; to: string }) => <a href={to}>{children}</a>,
+  Link: ({
+    children,
+    to,
+    state: _state,
+    issuePrefetch: _issuePrefetch,
+    issueQuicklookSide: _issueQuicklookSide,
+    issueQuicklookAlign: _issueQuicklookAlign,
+    ...props
+  }: {
+    children?: ReactNode;
+    to: string;
+    state?: unknown;
+    issuePrefetch?: unknown;
+    issueQuicklookSide?: unknown;
+    issueQuicklookAlign?: unknown;
+  } & AnchorHTMLAttributes<HTMLAnchorElement>) => (
+    <a href={to} {...props}>{children}</a>
+  ),
   useLocation: () => ({ pathname: "/issues/PAP-1", search: "", hash: "", state: null }),
   useNavigate: () => mockNavigate,
   useNavigationType: () => "PUSH",
@@ -197,6 +214,7 @@ vi.mock("../components/IssueChatThread", () => ({
     onStopRun?: (runId: string) => Promise<void>;
     stopRunLabel?: string;
     stoppingRunLabel?: string;
+    footer?: ReactNode;
   }) => {
     mockIssueChatThreadRender(props);
     return (
@@ -207,6 +225,7 @@ vi.mock("../components/IssueChatThread", () => ({
             {props.stopRunLabel ?? "Stop run"}
           </button>
         ) : null}
+        {props.footer}
       </div>
     );
   },
@@ -839,6 +858,116 @@ describe("IssueDetail", () => {
     expect(consoleErrorSpy).not.toHaveBeenCalled();
   });
 
+  it("renders sibling previous and next navigation at the chat footer", async () => {
+    const issue = createIssue({
+      id: "issue-2",
+      identifier: "PAP-2",
+      issueNumber: 2,
+      parentId: "parent-1",
+      title: "Current sibling",
+      createdAt: new Date("2026-04-02T00:00:00.000Z"),
+    });
+    const previous = createIssue({
+      id: "issue-1",
+      identifier: "PAP-1",
+      issueNumber: 1,
+      parentId: "parent-1",
+      title: "Previous sibling",
+      status: "done",
+      createdAt: new Date("2026-04-01T00:00:00.000Z"),
+    });
+    const next = createIssue({
+      id: "issue-3",
+      identifier: "PAP-3",
+      issueNumber: 3,
+      parentId: "parent-1",
+      title: "Next sibling",
+      blockedBy: [{ id: "issue-2" }] as Issue["blockedBy"],
+      createdAt: new Date("2026-04-03T00:00:00.000Z"),
+    });
+
+    mockIssuesApi.get.mockResolvedValue(issue);
+    mockIssuesApi.list.mockImplementation((_companyId, filters?: { descendantOf?: string; parentId?: string }) => {
+      if (filters?.parentId === "parent-1") return Promise.resolve([next, previous, issue]);
+      return Promise.resolve([]);
+    });
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <IssueDetail />
+        </QueryClientProvider>,
+      );
+    });
+    await flushReact();
+    await flushReact();
+
+    expect(mockIssuesApi.list).toHaveBeenCalledWith("company-1", {
+      parentId: "parent-1",
+      includeBlockedBy: true,
+    });
+    expect(container.querySelector('a[aria-label="Previous sub-issue: PAP-1 - Previous sibling"]')).toBeTruthy();
+    expect(container.querySelector('a[aria-label="Next sub-issue: PAP-3 - Next sibling"]')).toBeTruthy();
+    expect(container.textContent).toContain("Previous");
+    expect(container.textContent).toContain("Previous sibling");
+    expect(container.textContent).toContain("Next");
+    expect(container.textContent).toContain("Next sibling");
+    expect(mockIssueChatThreadRender.mock.calls.at(-1)?.[0].footer).toBeTruthy();
+  });
+
+  it("uses the first child issue as next navigation for parent issues without a sibling next", async () => {
+    const parent = createIssue({
+      id: "issue-parent",
+      identifier: "PAP-10",
+      issueNumber: 10,
+      parentId: null,
+      title: "Plan parent",
+      createdAt: new Date("2026-04-01T00:00:00.000Z"),
+    });
+    const firstChild = createIssue({
+      id: "issue-child-1",
+      identifier: "PAP-11",
+      issueNumber: 11,
+      parentId: "issue-parent",
+      title: "First child",
+      createdAt: new Date("2026-04-02T00:00:00.000Z"),
+    });
+    const secondChild = createIssue({
+      id: "issue-child-2",
+      identifier: "PAP-12",
+      issueNumber: 12,
+      parentId: "issue-parent",
+      title: "Second child",
+      blockedBy: [{ id: "issue-child-1" }] as Issue["blockedBy"],
+      createdAt: new Date("2026-04-03T00:00:00.000Z"),
+    });
+
+    mockIssuesApi.get.mockResolvedValue(parent);
+    mockIssuesApi.list.mockImplementation((_companyId, filters?: { descendantOf?: string; parentId?: string }) => {
+      if (filters?.descendantOf === "issue-parent") return Promise.resolve([secondChild, firstChild]);
+      return Promise.resolve([]);
+    });
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <IssueDetail />
+        </QueryClientProvider>,
+      );
+    });
+    await flushReact();
+    await flushReact();
+
+    expect(mockIssuesApi.list).toHaveBeenCalledWith("company-1", {
+      descendantOf: "issue-parent",
+      includeBlockedBy: true,
+    });
+    expect(container.querySelector('a[aria-label="Next sub-issue: PAP-11 - First child"]')).toBeTruthy();
+    expect(container.textContent).toContain("Next");
+    expect(container.textContent).toContain("First child");
+    expect(mockIssueChatThreadRender.mock.calls.at(-1)?.[0].footer).toBeTruthy();
+  });
+
   it("passes blocker attention to the issue detail header status icon", async () => {
     mockIssuesApi.get.mockResolvedValue(createIssue({
       status: "blocked",
@@ -1447,3 +1576,39 @@ describe("IssueDetail", () => {
     expect(footer?.className).toContain("bg-background");
   });
 });
+
+describe("canBoardResolveRecoveryAction", () => {
+  it("falls back to companyIds when memberships are not populated", () => {
+    expect(
+      canBoardResolveRecoveryAction("company-1", {
+        companyIds: ["company-1"],
+        memberships: [],
+        isInstanceAdmin: false,
+        source: "session",
+        keyId: null,
+        user: null,
+        userId: "user-1",
+      }),
+    ).toBe(true);
+  });
+
+  it("uses populated memberships as the authoritative board access source", () => {
+    expect(
+      canBoardResolveRecoveryAction("company-1", {
+        companyIds: ["company-1"],
+        memberships: [
+          {
+            companyId: "company-1",
+            membershipRole: "viewer",
+            status: "active",
+          },
+        ],
+        isInstanceAdmin: false,
+        source: "session",
+        keyId: null,
+        user: null,
+        userId: "user-1",
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/ui/src/pages/IssueDetail.tsx b/ui/src/pages/IssueDetail.tsx
index 3663b4c8..95156440 100644
--- a/ui/src/pages/IssueDetail.tsx
+++ b/ui/src/pages/IssueDetail.tsx
@@ -1,4 +1,4 @@
-import { memo, useCallback, useEffect, useMemo, useRef, useState, type ChangeEvent, type DragEvent, type Ref } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState, type ChangeEvent, type DragEvent, type ReactNode, type Ref } from "react";
 import { pickTextColorForPillBg } from "@/lib/color-contrast";
 import { Link, useLocation, useNavigate, useNavigationType, useParams } from "@/lib/router";
 import { useInfiniteQuery, useQuery, useMutation, useQueryClient, type InfiniteData, type QueryClient } from "@tanstack/react-query";
@@ -8,7 +8,7 @@ import { approvalsApi } from "../api/approvals";
 import { activityApi, type RunForIssue } from "../api/activity";
 import { heartbeatsApi, type ActiveRunForIssue, type LiveRunForIssue } from "../api/heartbeats";
 import { instanceSettingsApi } from "../api/instanceSettings";
-import { accessApi } from "../api/access";
+import { accessApi, type CurrentBoardAccess } from "../api/access";
 import { agentsApi } from "../api/agents";
 import { authApi } from "../api/auth";
 import { projectsApi } from "../api/projects";
@@ -66,6 +66,7 @@ import { InlineEditor } from "../components/InlineEditor";
 import { IssueChatThread, type IssueChatComposerHandle } from "../components/IssueChatThread";
 import { IssueContinuationHandoff } from "../components/IssueContinuationHandoff";
 import { IssueDocumentsSection } from "../components/IssueDocumentsSection";
+import { IssueSiblingNavigation } from "../components/IssueSiblingNavigation";
 import { IssuesList } from "../components/IssuesList";
 import { AgentIcon } from "../components/AgentIconPicker";
 import { IssueReferenceActivitySummary } from "../components/IssueReferenceActivitySummary";
@@ -102,7 +103,7 @@ import {
 import { Textarea } from "@/components/ui/textarea";
 import { formatIssueActivityAction } from "@/lib/activity-format";
 import { buildIssuePropertiesPanelKey } from "../lib/issue-properties-panel-key";
-import { shouldRenderRichSubIssuesSection } from "../lib/issue-detail-subissues";
+import { buildIssueSiblingNavigation, shouldRenderRichSubIssuesSection } from "../lib/issue-detail-subissues";
 import { filterIssueDescendants } from "../lib/issue-tree";
 import { buildSubIssueDefaultsForViewer } from "../lib/subIssueDefaults";
 import {
@@ -157,6 +158,7 @@ import {
 
 type CommentReassignment = IssueCommentReassignment;
 type ActionableIssueThreadInteraction = SuggestTasksInteraction | RequestConfirmationInteraction;
+type ResolveRecoveryActionOutcome = "restored" | "false_positive" | "blocked" | "cancelled";
 type IssueDetailComment = (IssueComment | OptimisticIssueComment) & {
   runId?: string | null;
   runAgentId?: string | null;
@@ -211,6 +213,23 @@ function treeControlPreviewErrorCopy(error: unknown): string {
   return error instanceof Error ? error.message : "Unable to load preview.";
 }
 
+export function canBoardResolveRecoveryAction(
+  companyId: string | null | undefined,
+  boardAccess: CurrentBoardAccess | undefined,
+) {
+  if (!companyId || !boardAccess) return false;
+  if (boardAccess.source === "local_implicit" || boardAccess.isInstanceAdmin) return true;
+  if (!boardAccess.memberships || boardAccess.memberships.length === 0) {
+    return boardAccess.companyIds.includes(companyId);
+  }
+
+  const membership = boardAccess.memberships.find(
+    (item) => item.companyId === companyId && item.status === "active",
+  );
+  if (!membership) return false;
+  return membership.membershipRole !== "viewer" && membership.membershipRole !== null;
+}
+
 function resolveRunningIssueRun(
   activeRun: ActiveRunForIssue | null | undefined,
   liveRuns: readonly LiveRunForIssue[] | undefined,
@@ -598,6 +617,14 @@ type IssueDetailChatTabProps = {
   blockedBy: Issue["blockedBy"];
   blockerAttention: Issue["blockerAttention"] | null;
   successfulRunHandoff: Issue["successfulRunHandoff"] | null;
+  recoveryAction: Issue["activeRecoveryAction"];
+  onResolveRecoveryAction?: (outcome: import("../components/IssueRecoveryActionCard").RecoveryResolveOutcome) => void;
+  canFalsePositiveRecoveryAction?: boolean;
+  legacyRecoverySourceIssue?: {
+    identifier: string | null;
+    href: string;
+    title?: string | null;
+  } | null;
   comments: IssueDetailComment[];
   locallyQueuedCommentRunIds: ReadonlyMap<string, string>;
   interactions: IssueThreadInteraction[];
@@ -607,6 +634,7 @@ type IssueDetailChatTabProps = {
   onRefreshLatestComments: () => Promise<unknown> | void;
   onWorkModeChange?: (workMode: IssueWorkMode) => Promise<void> | void;
   composerRef: Ref<IssueChatComposerHandle>;
+  footer?: ReactNode;
   feedbackVotes?: FeedbackVote[];
   feedbackDataSharingPreference: "allowed" | "not_allowed" | "prompt";
   feedbackTermsUrl: string | null;
@@ -661,6 +689,10 @@ const IssueDetailChatTab = memo(function IssueDetailChatTab({
   blockedBy,
   blockerAttention,
   successfulRunHandoff,
+  recoveryAction,
+  onResolveRecoveryAction,
+  canFalsePositiveRecoveryAction,
+  legacyRecoverySourceIssue,
   comments,
   locallyQueuedCommentRunIds,
   interactions,
@@ -670,6 +702,7 @@ const IssueDetailChatTab = memo(function IssueDetailChatTab({
   onRefreshLatestComments,
   onWorkModeChange,
   composerRef,
+  footer,
   feedbackVotes,
   feedbackDataSharingPreference,
   feedbackTermsUrl,
@@ -867,6 +900,10 @@ const IssueDetailChatTab = memo(function IssueDetailChatTab({
         blockedBy={blockedBy ?? []}
         blockerAttention={blockerAttention}
         successfulRunHandoff={successfulRunHandoff}
+        recoveryAction={recoveryAction ?? null}
+        onResolveRecoveryAction={onResolveRecoveryAction}
+        canFalsePositiveRecoveryAction={canFalsePositiveRecoveryAction}
+        legacyRecoverySourceIssue={legacyRecoverySourceIssue ?? null}
         companyId={companyId}
         projectId={projectId}
         issueStatus={issueStatus}
@@ -912,6 +949,7 @@ const IssueDetailChatTab = memo(function IssueDetailChatTab({
         assigneeUserId={assigneeUserId}
         onResumeFromBacklog={onResumeFromBacklog}
         resumeFromBacklogPending={resumeFromBacklogPending}
+        footer={footer}
       />
     </div>
   );
@@ -1334,6 +1372,18 @@ export function IssueDetail() {
     enabled: !!resolvedCompanyId && !!issue?.id,
     placeholderData: keepPreviousDataForSameQueryTail<Issue[]>(issue?.id ?? "pending"),
   });
+  const {
+    data: rawSiblingIssues = [],
+    isLoading: siblingIssuesLoading,
+    isError: siblingIssuesError,
+  } = useQuery({
+    queryKey:
+      issue?.parentId && resolvedCompanyId
+        ? queryKeys.issues.listByParent(resolvedCompanyId, issue.parentId)
+        : ["issues", "siblings", "pending"],
+    queryFn: () => issuesApi.list(resolvedCompanyId!, { parentId: issue!.parentId!, includeBlockedBy: true }),
+    enabled: !!resolvedCompanyId && !!issue?.parentId,
+  });
   const { data: companyLiveRuns } = useQuery({
     queryKey: resolvedCompanyId ? queryKeys.liveRuns(resolvedCompanyId) : ["live-runs", "pending"],
     queryFn: () => heartbeatsApi.liveRunsForCompany(resolvedCompanyId!),
@@ -1374,6 +1424,7 @@ export function IssueDetail() {
     selectedCompanyId
     && boardAccess?.companyIds?.includes(selectedCompanyId),
   );
+  const canResolveBoardRecoveryAction = canBoardResolveRecoveryAction(selectedCompanyId, boardAccess);
   const { data: feedbackVotes } = useQuery({
     queryKey: queryKeys.issues.feedbackVotes(issueId!),
     queryFn: () => issuesApi.listFeedbackVotes(issueId!),
@@ -1502,6 +1553,12 @@ export function IssueDetail() {
     [issuePanelKey],
   );
   const showRichSubIssuesSection = shouldRenderRichSubIssuesSection(childIssuesLoading, childIssues.length);
+  const siblingNavigation = useMemo(
+    () => issue && !childIssuesLoading && !siblingIssuesLoading && !siblingIssuesError
+      ? buildIssueSiblingNavigation(issue, rawSiblingIssues, childIssues)
+      : null,
+    [childIssues, childIssuesLoading, issue, rawSiblingIssues, siblingIssuesError, siblingIssuesLoading],
+  );
   const openNewSubIssue = useCallback(() => {
     if (!issue) return;
     openNewIssue(buildSubIssueDefaultsForViewer(issue, currentUserId));
@@ -1709,6 +1766,34 @@ export function IssueDetail() {
       }
     },
   });
+  const resolveRecoveryAction = useMutation({
+    mutationFn: (data: {
+      actionId?: string;
+      outcome: ResolveRecoveryActionOutcome;
+      sourceIssueStatus: "done" | "in_review" | "blocked";
+      resolutionNote?: string | null;
+    }) => issuesApi.resolveRecoveryAction(issueId!, data),
+    onSuccess: ({ issue: nextIssue }) => {
+      const issueRefs = new Set<string>([issueId!, nextIssue.id]);
+      if (nextIssue.identifier) issueRefs.add(nextIssue.identifier);
+      mergeIssueResponseIntoCaches(issueRefs, nextIssue);
+      queryClient.invalidateQueries({ queryKey: queryKeys.issues.activity(issueId!) });
+      invalidateIssueCollections();
+    },
+    onError: (err) => {
+      pushToast({
+        title: "Recovery resolution failed",
+        body: err instanceof Error ? err.message : "Unable to resolve recovery action",
+        tone: "error",
+      });
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.issues.detail(issueId!) });
+      if (selectedCompanyId) {
+        queryClient.invalidateQueries({ queryKey: queryKeys.issues.list(selectedCompanyId) });
+      }
+    },
+  });
   const executeTreeControl = useMutation({
     mutationFn: async () => {
       if (treeControlMode === "resume") {
@@ -2909,6 +2994,28 @@ export function IssueDetail() {
   const handleResumeFromBacklog = useCallback(async () => {
     await updateIssue.mutateAsync({ status: "todo" });
   }, [updateIssue.mutateAsync]);
+  const activeRecoveryActionId = issue?.activeRecoveryAction?.id;
+  const handleResolveRecoveryAction = useCallback(
+    (outcome: import("../components/IssueRecoveryActionCard").RecoveryResolveOutcome) => {
+      const actionId = activeRecoveryActionId;
+      if (!actionId) return;
+      switch (outcome) {
+        case "done":
+          void resolveRecoveryAction.mutateAsync({ actionId, outcome: "restored", sourceIssueStatus: "done" });
+          return;
+        case "in_review":
+          void resolveRecoveryAction.mutateAsync({ actionId, outcome: "restored", sourceIssueStatus: "in_review" });
+          return;
+        case "false_positive_done":
+          void resolveRecoveryAction.mutateAsync({ actionId, outcome: "false_positive", sourceIssueStatus: "done" });
+          return;
+        case "false_positive_in_review":
+          void resolveRecoveryAction.mutateAsync({ actionId, outcome: "false_positive", sourceIssueStatus: "in_review" });
+          return;
+      }
+    },
+    [activeRecoveryActionId, resolveRecoveryAction.mutateAsync],
+  );
 
   const treePreviewAffectedIssues = useMemo(
     () => (treeControlPreview?.issues ?? []).filter((candidate) => !candidate.skipped),
@@ -2970,6 +3077,22 @@ export function IssueDetail() {
 
   // Ancestors are returned oldest-first from the server (root at end, immediate parent at start)
   const ancestors = issue.ancestors ?? [];
+  const legacyRecoverySourceIssue = (() => {
+    if (
+      issue.originKind !== "stranded_issue_recovery" &&
+      issue.originKind !== "stale_active_run_evaluation"
+    ) {
+      return null;
+    }
+    const parent = ancestors.length > 0 ? ancestors[0] : null;
+    if (!parent) return null;
+    const ref = parent.identifier ?? parent.id;
+    return {
+      identifier: parent.identifier ?? null,
+      title: parent.title ?? null,
+      href: createIssueDetailPath(ref),
+    };
+  })();
   const handleFilePicked = async (evt: ChangeEvent<HTMLInputElement>) => {
     const files = evt.target.files;
     if (!files || files.length === 0) return;
@@ -3787,6 +3910,10 @@ export function IssueDetail() {
               blockedBy={issue.blockedBy ?? []}
               blockerAttention={issue.blockerAttention ?? null}
               successfulRunHandoff={issue.successfulRunHandoff ?? null}
+              recoveryAction={issue.activeRecoveryAction ?? null}
+              onResolveRecoveryAction={handleResolveRecoveryAction}
+              canFalsePositiveRecoveryAction={canResolveBoardRecoveryAction}
+              legacyRecoverySourceIssue={legacyRecoverySourceIssue}
               comments={threadComments}
               locallyQueuedCommentRunIds={locallyQueuedCommentRunIds}
               interactions={interactions}
@@ -3795,6 +3922,14 @@ export function IssueDetail() {
               onLoadOlderComments={loadOlderComments}
               onRefreshLatestComments={refetchLatestComments}
               composerRef={commentComposerRef}
+              footer={
+                siblingNavigation ? (
+                  <IssueSiblingNavigation
+                    navigation={siblingNavigation}
+                    linkState={resolvedIssueDetailState ?? location.state}
+                  />
+                ) : null
+              }
               feedbackVotes={feedbackVotes}
               feedbackDataSharingPreference={feedbackDataSharingPreference}
               feedbackTermsUrl={FEEDBACK_TERMS_URL}
diff --git a/ui/storybook/stories/blocked-inbox.stories.tsx b/ui/storybook/stories/blocked-inbox.stories.tsx
new file mode 100644
index 00000000..031d1fb3
--- /dev/null
+++ b/ui/storybook/stories/blocked-inbox.stories.tsx
@@ -0,0 +1,303 @@
+import { useMemo } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { Issue, IssueBlockedInboxAttention } from "@paperclipai/shared";
+import { BlockedInboxView } from "@/components/BlockedInboxView";
+import { BlockedReasonChip } from "@/components/BlockedReasonChip";
+import { defaultIssueFilterState } from "@/lib/issue-filters";
+import { queryKeys } from "@/lib/queryKeys";
+import { storybookIssues } from "../fixtures/paperclipData";
+
+const companyId = "company-storybook";
+const blockedViewDefaults = {
+  groupBy: "none" as const,
+  sortBy: "most_recent" as const,
+  issueFilters: defaultIssueFilterState,
+  currentUserId: "local-board",
+  liveIssueIds: new Set<string>(),
+  workspaceFilterContext: {},
+  showStatusColumn: true,
+  showIdentifierColumn: true,
+  showUpdatedColumn: true,
+};
+
+function attention(
+  overrides: Partial<IssueBlockedInboxAttention> = {},
+): IssueBlockedInboxAttention {
+  return {
+    kind: "blocked",
+    state: "needs_attention",
+    reason: "blocked_chain_stalled",
+    severity: "medium",
+    stoppedSinceAt: new Date(Date.now() - 4 * 60 * 60 * 1000).toISOString(),
+    owner: { type: "agent", agentId: null, userId: null, label: "ClaudeCoder" },
+    action: { label: "Resolve PAP-12", detail: null },
+    sourceIssue: null,
+    leafIssue: null,
+    recoveryIssue: null,
+    approvalId: null,
+    interactionId: null,
+    sampleIssueIdentifier: null,
+    redaction: { externalDetailsRedacted: false, secretFieldsOmitted: true },
+    ...overrides,
+  };
+}
+
+const baseIssue = storybookIssues[0]!;
+
+const fixtureIssues: Issue[] = [
+  {
+    ...baseIssue,
+    id: "issue-decision-1",
+    identifier: "PAP-401",
+    title: "Approve plan: rewrite onboarding flow",
+    status: "in_review",
+    blockedInboxAttention: attention({
+      reason: "pending_board_decision",
+      state: "awaiting_decision",
+      severity: "medium",
+      stoppedSinceAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(),
+      owner: { type: "board", agentId: null, userId: null, label: "Board" },
+      action: { label: "Accept or reject", detail: null },
+    }),
+  },
+  {
+    ...baseIssue,
+    id: "issue-disposition-1",
+    identifier: "PAP-402",
+    title: "Pick disposition for completed migration",
+    status: "in_progress",
+    blockedInboxAttention: attention({
+      reason: "missing_successful_run_disposition",
+      state: "missing_disposition",
+      severity: "medium",
+      stoppedSinceAt: new Date(Date.now() - 30 * 60 * 1000).toISOString(),
+      owner: { type: "agent", agentId: null, userId: null, label: "QA" },
+      action: { label: "Pick disposition", detail: null },
+    }),
+  },
+  {
+    ...baseIssue,
+    id: "issue-stalled-critical",
+    identifier: "PAP-410",
+    title: "Ship invoice export — blocker is stalled",
+    status: "blocked",
+    blockedInboxAttention: attention({
+      reason: "blocked_chain_stalled",
+      state: "needs_attention",
+      severity: "critical",
+      stoppedSinceAt: new Date(Date.now() - 36 * 60 * 60 * 1000).toISOString(),
+      owner: { type: "agent", agentId: null, userId: null, label: "CodexCoder" },
+      action: { label: "Resolve PAP-411", detail: null },
+    }),
+  },
+  {
+    ...baseIssue,
+    id: "issue-stalled-high",
+    identifier: "PAP-412",
+    title: "Run nightly compaction",
+    status: "blocked",
+    blockedInboxAttention: attention({
+      reason: "blocked_chain_stalled",
+      severity: "high",
+      stoppedSinceAt: new Date(Date.now() - 8 * 60 * 60 * 1000).toISOString(),
+      owner: { type: "agent", agentId: null, userId: null, label: "QA" },
+      action: { label: "Resolve PAP-413", detail: null },
+    }),
+  },
+  {
+    ...baseIssue,
+    id: "issue-needs-attention",
+    identifier: "PAP-420",
+    title: "Resume parked permissions PR",
+    status: "blocked",
+    blockedInboxAttention: attention({
+      reason: "blocked_by_assigned_backlog_issue",
+      severity: "medium",
+      stoppedSinceAt: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+      owner: { type: "agent", agentId: null, userId: null, label: "ClaudeCoder" },
+      action: { label: "Resume parked blocker", detail: null },
+    }),
+  },
+  {
+    ...baseIssue,
+    id: "issue-recovery",
+    identifier: "PAP-430",
+    title: "Recover failed deploy run",
+    status: "blocked",
+    blockedInboxAttention: attention({
+      reason: "open_recovery_issue",
+      state: "recovery_open",
+      severity: "high",
+      stoppedSinceAt: new Date(Date.now() - 6 * 60 * 60 * 1000).toISOString(),
+      owner: { type: "agent", agentId: null, userId: null, label: "RecoveryAgent" },
+      action: { label: "Resolve PAP-431", detail: null },
+    }),
+  },
+  {
+    ...baseIssue,
+    id: "issue-external",
+    identifier: "PAP-440",
+    title: "Awaiting upstream provider response",
+    status: "blocked",
+    blockedInboxAttention: attention({
+      reason: "external_owner_action",
+      state: "external_wait",
+      severity: "low",
+      stoppedSinceAt: new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString(),
+      owner: { type: "external", agentId: null, userId: null, label: "Stripe" },
+      action: { label: "Awaiting Stripe", detail: null },
+    }),
+  },
+  {
+    ...baseIssue,
+    id: "issue-paused",
+    identifier: "PAP-450",
+    title: "Owner paused — budget exceeded",
+    status: "blocked",
+    blockedInboxAttention: attention({
+      reason: "blocked_by_uninvokable_assignee",
+      severity: "critical",
+      stoppedSinceAt: new Date(Date.now() - 12 * 60 * 60 * 1000).toISOString(),
+      owner: { type: "agent", agentId: null, userId: null, label: "PausedAgent" },
+      action: { label: "Reassign or unblock budget", detail: null },
+    }),
+  },
+];
+
+function PrimeBlockedFixtures({ children }: { children: React.ReactNode }) {
+  const queryClient = useQueryClient();
+  useMemo(() => {
+    queryClient.setQueryData(queryKeys.issues.listBlockedAttention(companyId), fixtureIssues);
+  }, [queryClient]);
+  return <>{children}</>;
+}
+
+function BlockedTabSurface({ search = "" }: { search?: string }) {
+  return (
+    <PrimeBlockedFixtures>
+      <div className="space-y-3">
+        <div className="text-xs uppercase tracking-wide text-muted-foreground">
+          Inbox / Blocked tab — desktop layout
+        </div>
+        <div className="rounded-lg border border-border bg-background p-4">
+          <BlockedInboxView
+            {...blockedViewDefaults}
+            companyId={companyId}
+            searchQuery={search}
+            agentNameById={new Map()}
+            issueLinkState={null}
+          />
+        </div>
+      </div>
+    </PrimeBlockedFixtures>
+  );
+}
+
+function BlockedTabSurfaceMobile() {
+  return (
+    <div className="mx-auto max-w-[390px] space-y-3">
+      <div className="text-xs uppercase tracking-wide text-muted-foreground">
+        Inbox / Blocked tab — 390px mobile width
+      </div>
+      <div className="rounded-lg border border-border bg-background p-2">
+        <BlockedTabSurface />
+      </div>
+    </div>
+  );
+}
+
+function BlockedReasonChipsCatalog() {
+  return (
+    <div className="grid gap-3 p-6 sm:grid-cols-2">
+      <div className="space-y-2">
+        <div className="text-xs uppercase tracking-wide text-muted-foreground">
+          Needs decision · medium
+        </div>
+        <BlockedReasonChip reason="pending_board_decision" severity="medium" />
+      </div>
+      <div className="space-y-2">
+        <div className="text-xs uppercase tracking-wide text-muted-foreground">
+          Blocked chain stalled · critical
+        </div>
+        <BlockedReasonChip reason="blocked_chain_stalled" severity="critical" />
+      </div>
+      <div className="space-y-2">
+        <div className="text-xs uppercase tracking-wide text-muted-foreground">
+          Needs attention · high
+        </div>
+        <BlockedReasonChip reason="blocked_by_assigned_backlog_issue" severity="high" />
+      </div>
+      <div className="space-y-2">
+        <div className="text-xs uppercase tracking-wide text-muted-foreground">
+          Recovery required · high
+        </div>
+        <BlockedReasonChip reason="open_recovery_issue" severity="high" />
+      </div>
+      <div className="space-y-2">
+        <div className="text-xs uppercase tracking-wide text-muted-foreground">
+          External wait · low (no severity dot)
+        </div>
+        <BlockedReasonChip reason="external_owner_action" severity="low" />
+      </div>
+      <div className="space-y-2">
+        <div className="text-xs uppercase tracking-wide text-muted-foreground">
+          Owner paused · critical
+        </div>
+        <BlockedReasonChip reason="blocked_by_uninvokable_assignee" severity="critical" />
+      </div>
+    </div>
+  );
+}
+
+function BlockedTabEmptyState() {
+  return (
+    <div className="rounded-lg border border-border bg-background p-4">
+      <BlockedInboxView
+        {...blockedViewDefaults}
+        companyId="company-empty"
+        searchQuery=""
+        agentNameById={new Map()}
+        issueLinkState={null}
+      />
+    </div>
+  );
+}
+
+const meta = {
+  title: "Product/Inbox/Blocked tab",
+  component: BlockedTabSurface,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Stopped-work triage Inbox tab. Rows group by reason variant and sort by severity → stoppedSinceAt. The reason chip + owner + action combo sits next to the issue title. No quick archive on this tab.",
+      },
+    },
+  },
+} satisfies Meta<typeof BlockedTabSurface>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const DesktopLoaded: Story = {
+  render: () => <BlockedTabSurface />,
+};
+
+export const DesktopWithSearch: Story = {
+  render: () => <BlockedTabSurface search="parked" />,
+};
+
+export const MobileLayout: Story = {
+  parameters: { viewport: { defaultViewport: "mobile1" } },
+  render: () => <BlockedTabSurfaceMobile />,
+};
+
+export const ReasonChipCatalog: Story = {
+  render: () => <BlockedReasonChipsCatalog />,
+};
+
+export const EmptyState: Story = {
+  render: () => <BlockedTabEmptyState />,
+};
diff --git a/ui/storybook/stories/source-issue-recovery.stories.tsx b/ui/storybook/stories/source-issue-recovery.stories.tsx
new file mode 100644
index 00000000..fd6257f5
--- /dev/null
+++ b/ui/storybook/stories/source-issue-recovery.stories.tsx
@@ -0,0 +1,381 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { ReactNode } from "react";
+import type { IssueRecoveryAction, IssueRelationIssueSummary } from "@paperclipai/shared";
+import { Eye, ExternalLink, OctagonAlert, RefreshCw, TriangleAlert } from "lucide-react";
+import { IssueRecoveryActionCard } from "@/components/IssueRecoveryActionCard";
+import { IssueRow } from "@/components/IssueRow";
+import { IssueBlockedNotice } from "@/components/IssueBlockedNotice";
+import { storybookAgentMap, storybookAgents, createIssue } from "../fixtures/paperclipData";
+
+const claudeAgent = storybookAgents.find((agent) => agent.name.toLowerCase().startsWith("claude")) ?? storybookAgents[0]!;
+const codexAgent = storybookAgents.find((agent) => agent.name.toLowerCase().startsWith("codex")) ?? storybookAgents[0]!;
+
+function StoryFrame({ title, description, children }: { title: string; description?: string; children: ReactNode }) {
+  return (
+    <main className="min-h-screen bg-background p-4 text-foreground sm:p-8">
+      <div className="mx-auto max-w-5xl space-y-5">
+        <header>
+          <div className="text-xs font-medium uppercase tracking-[0.2em] text-muted-foreground">
+            Source-issue recovery
+          </div>
+          <h1 className="mt-1 text-2xl font-semibold">{title}</h1>
+          {description ? (
+            <p className="mt-2 max-w-3xl text-sm text-muted-foreground">{description}</p>
+          ) : null}
+        </header>
+        {children}
+      </div>
+    </main>
+  );
+}
+
+function buildAction(overrides: Partial<IssueRecoveryAction> = {}): IssueRecoveryAction {
+  return {
+    id: "00000000-0000-0000-0000-0000000000aa",
+    companyId: "company-storybook",
+    sourceIssueId: "00000000-0000-0000-0000-0000000000ff",
+    recoveryIssueId: null,
+    kind: "missing_disposition",
+    status: "active",
+    ownerType: "agent",
+    ownerAgentId: claudeAgent.id,
+    ownerUserId: null,
+    previousOwnerAgentId: codexAgent.id,
+    returnOwnerAgentId: codexAgent.id,
+    cause: "missing_disposition",
+    fingerprint: "fp",
+    evidence: {
+      summary: "Run finished without picking a disposition. The PR has tests passing on CI.",
+      sourceRunId: "7accd7a4-c9ca-4db2-9233-3228a037cc09",
+      correctiveRunId: "2606404d-3859-4142-ba37-3228a037cc09",
+    },
+    nextAction: "Choose and record a valid issue disposition without copying transcript content.",
+    wakePolicy: { type: "wake_owner" },
+    monitorPolicy: null,
+    attemptCount: 1,
+    maxAttempts: 3,
+    timeoutAt: null,
+    lastAttemptAt: "2026-04-20T11:55:00.000Z",
+    outcome: null,
+    resolutionNote: null,
+    resolvedAt: null,
+    createdAt: "2026-04-20T11:55:00.000Z",
+    updatedAt: "2026-04-20T11:55:00.000Z",
+    ...overrides,
+  };
+}
+
+function CardPanel({ caption, action, forcedState, canFalsePositive }: {
+  caption: string;
+  action: IssueRecoveryAction;
+  forcedState?: React.ComponentProps<typeof IssueRecoveryActionCard>["forcedState"];
+  canFalsePositive?: boolean;
+}) {
+  return (
+    <section className="space-y-2">
+      <div className="text-[11px] font-semibold uppercase tracking-[0.16em] text-muted-foreground">
+        {caption}
+      </div>
+      <IssueRecoveryActionCard
+        action={action}
+        agentMap={storybookAgentMap}
+        forcedState={forcedState}
+        onResolve={() => {}}
+        canFalsePositive={canFalsePositive}
+      />
+    </section>
+  );
+}
+
+function AllStatesPanel() {
+  return (
+    <div className="grid gap-5 lg:grid-cols-1">
+      <CardPanel caption="State 1 · Recovery needed (default)" action={buildAction()} canFalsePositive />
+      <CardPanel
+        caption="State 2 · Recovery in progress"
+        action={buildAction({ outcome: "delegated", attemptCount: 2 })}
+        forcedState="in_progress"
+        canFalsePositive
+      />
+      <CardPanel
+        caption="State 3 · Observing active run (watchdog)"
+        action={buildAction({
+          kind: "active_run_watchdog",
+          wakePolicy: { type: "monitor", intervalLabel: "in 4m" },
+          evidence: { summary: "The active run has been silent for 7 minutes. Last log: 'continuing checks…'" },
+          nextAction: "Observe the active run; intervene only if the silence persists past timeout.",
+        })}
+      />
+      <CardPanel
+        caption="State 4 · Recovery escalated"
+        action={buildAction({
+          status: "escalated",
+          attemptCount: 3,
+          wakePolicy: { type: "board_escalation" },
+          evidence: {
+            summary: "Three corrective wakes failed. The recovery owner has not produced a disposition.",
+            sourceRunId: "7accd7a4-c9ca-4db2-9233-3228a037cc09",
+          },
+          nextAction: "Board operator: assign an invokable owner or record a manual resolution.",
+        })}
+        canFalsePositive
+      />
+      <CardPanel
+        caption="State 5 · Recovery resolved"
+        action={buildAction({
+          status: "resolved",
+          outcome: "restored",
+          resolvedAt: "2026-04-20T12:01:00.000Z",
+          nextAction: "Issue restored to a valid disposition.",
+        })}
+      />
+    </div>
+  );
+}
+
+function buildBlocker(
+  overrides: Partial<IssueRelationIssueSummary> = {},
+): IssueRelationIssueSummary {
+  return {
+    id: "blocker-1",
+    identifier: "PAP-9065",
+    title: "Add full company search page",
+    status: "in_progress",
+    priority: "medium",
+    assigneeAgentId: claudeAgent.id,
+    assigneeUserId: null,
+    ...overrides,
+  };
+}
+
+function BlockerNoticePanel() {
+  return (
+    <div className="space-y-4">
+      <IssueBlockedNotice
+        issueStatus="blocked"
+        blockers={[
+          buildBlocker({ activeRecoveryAction: buildAction() }),
+          buildBlocker({
+            id: "blocker-2",
+            identifier: "PAP-9099",
+            title: "Watchdog: PR review pipeline silent",
+            activeRecoveryAction: buildAction({ kind: "active_run_watchdog" }),
+          }),
+          buildBlocker({
+            id: "blocker-3",
+            identifier: "PAP-9073",
+            title: "Recovery escalated for stranded run",
+            status: "blocked",
+            activeRecoveryAction: buildAction({ status: "escalated" }),
+          }),
+          buildBlocker({
+            id: "blocker-4",
+            identifier: "PAP-9051",
+            title: "Bare blocker without recovery state",
+          }),
+        ]}
+      />
+    </div>
+  );
+}
+
+type RunCardRecoveryState = "needed" | "in_progress" | "observe_only" | "escalated";
+
+const RUN_CARD_RECOVERY_TONE: Record<RunCardRecoveryState, { icon: typeof TriangleAlert; label: string; className: string }> = {
+  needed: {
+    icon: TriangleAlert,
+    label: "Recovery needed",
+    className: "border-amber-500/60 bg-amber-500/15 text-amber-700 dark:text-amber-300",
+  },
+  in_progress: {
+    icon: RefreshCw,
+    label: "Recovery in progress",
+    className: "border-sky-500/60 bg-sky-500/15 text-sky-700 dark:text-sky-300",
+  },
+  observe_only: {
+    icon: Eye,
+    label: "Observing active run",
+    className: "border-border bg-muted text-muted-foreground",
+  },
+  escalated: {
+    icon: OctagonAlert,
+    label: "Recovery escalated",
+    className: "border-red-500/60 bg-red-500/15 text-red-700 dark:text-red-300",
+  },
+};
+
+function ActiveRunRecoveryChip({ state }: { state: RunCardRecoveryState }) {
+  const tone = RUN_CARD_RECOVERY_TONE[state];
+  const Icon = tone.icon;
+  return (
+    <span
+      className={`inline-flex shrink-0 items-center gap-0.5 rounded-full border px-1.5 py-0.5 text-[10px] font-medium ${tone.className}`}
+      role="status"
+      aria-label={tone.label}
+    >
+      <Icon className="h-2.5 w-2.5" aria-hidden />
+      {tone.label}
+    </span>
+  );
+}
+
+function ActiveRunCardMock({
+  identifier,
+  title,
+  recoveryState,
+}: {
+  identifier: string;
+  title: string;
+  recoveryState: RunCardRecoveryState;
+}) {
+  return (
+    <div className="flex h-[260px] w-full max-w-[320px] flex-col overflow-hidden rounded-xl border border-cyan-500/25 bg-cyan-500/[0.04] shadow-[0_16px_40px_rgba(6,182,212,0.08)]">
+      <div className="border-b border-border/60 px-3 py-3">
+        <div className="flex items-start justify-between gap-2">
+          <div className="min-w-0">
+            <div className="flex items-center gap-2">
+              <span className="relative flex h-2.5 w-2.5 shrink-0">
+                <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-cyan-400 opacity-70" />
+                <span className="relative inline-flex h-2.5 w-2.5 rounded-full bg-cyan-500" />
+              </span>
+              <span className="text-sm font-medium">CodexCoder</span>
+            </div>
+            <div className="mt-2 flex items-center gap-2 text-[11px] text-muted-foreground">
+              <span>Live now</span>
+            </div>
+          </div>
+          <span className="inline-flex items-center gap-1 rounded-full border border-border/70 bg-background/70 px-2 py-1 text-[10px] text-muted-foreground">
+            <ExternalLink className="h-2.5 w-2.5" />
+          </span>
+        </div>
+        <div className="mt-3 rounded-lg border border-border/60 bg-background/60 px-2.5 py-2 text-xs">
+          <span className="line-clamp-2 text-cyan-700 dark:text-cyan-300">
+            {identifier} - {title}
+          </span>
+          <div className="mt-1.5">
+            <ActiveRunRecoveryChip state={recoveryState} />
+          </div>
+        </div>
+      </div>
+      <div className="flex-1 px-3 py-2 text-[11px] text-muted-foreground">Live transcript…</div>
+    </div>
+  );
+}
+
+function ActiveRunPanel() {
+  return (
+    <div className="grid gap-4 sm:grid-cols-2">
+      <ActiveRunCardMock
+        identifier="PAP-9065"
+        title="Add full company search page"
+        recoveryState="needed"
+      />
+      <ActiveRunCardMock
+        identifier="PAP-9099"
+        title="Watchdog: PR review pipeline silent"
+        recoveryState="observe_only"
+      />
+      <ActiveRunCardMock
+        identifier="PAP-9073"
+        title="Recovery escalated for stranded run"
+        recoveryState="escalated"
+      />
+      <ActiveRunCardMock
+        identifier="PAP-9101"
+        title="Recovery in progress: delegated"
+        recoveryState="in_progress"
+      />
+    </div>
+  );
+}
+
+function InboxRowPanel() {
+  const baseIssue = createIssue();
+  return (
+    <div className="rounded-lg border border-border/70 bg-background/80">
+      <IssueRow
+        issue={{
+          ...baseIssue,
+          identifier: "PAP-9065",
+          title: "Add full company search page",
+          status: "in_progress",
+          activeRecoveryAction: buildAction(),
+        }}
+      />
+      <IssueRow
+        issue={{
+          ...baseIssue,
+          id: "issue-recovery-watch",
+          identifier: "PAP-9099",
+          title: "Watchdog: PR review pipeline silent",
+          status: "in_progress",
+          activeRecoveryAction: buildAction({ kind: "active_run_watchdog" }),
+        }}
+      />
+      <IssueRow
+        issue={{
+          ...baseIssue,
+          id: "issue-recovery-escalated",
+          identifier: "PAP-9073",
+          title: "Recovery escalated for stranded run",
+          status: "blocked",
+          activeRecoveryAction: buildAction({ status: "escalated" }),
+        }}
+      />
+    </div>
+  );
+}
+
+const meta = {
+  title: "Paperclip/Source Issue Recovery",
+  component: AllStatesPanel,
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof AllStatesPanel>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const RecoveryActionCardStates: Story = {
+  render: () => (
+    <StoryFrame
+      title="Recovery action card states"
+      description="Five states required by the source-issue recovery contract: needed, in progress, observe-only watchdog, escalated, resolved."
+    >
+      <AllStatesPanel />
+    </StoryFrame>
+  ),
+};
+
+export const InboxRowChips: Story = {
+  render: () => (
+    <StoryFrame
+      title="Inbox row recovery chips"
+      description="Source rows expose recovery state inline; no synthetic sibling row appears for source-scoped recovery."
+    >
+      <InboxRowPanel />
+    </StoryFrame>
+  ),
+};
+
+export const BlockerNoticeRecoveryIndicators: Story = {
+  render: () => (
+    <StoryFrame
+      title="Blocker notice recovery indicators"
+      description="Blocker chips inline a recovery indicator when the blocker has an active recovery action. Plain blockers stay clean."
+    >
+      <BlockerNoticePanel />
+    </StoryFrame>
+  ),
+};
+
+export const ActiveRunPanelRecoveryChips: Story = {
+  render: () => (
+    <StoryFrame
+      title="Active run panel recovery chips"
+      description="Active run cards on the dashboard expose recovery state on the linked source issue."
+    >
+      <ActiveRunPanel />
+    </StoryFrame>
+  ),
+};
diff --git a/vitest.config.ts b/vitest.config.ts
index 42b8e879..f27929e7 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -14,6 +14,7 @@ export default defineConfig({
       "packages/adapters/gemini-local",
       "packages/adapters/opencode-local",
       "packages/adapters/pi-local",
+      "packages/plugins/sdk",
       "server",
       "ui",
       "cli",