Merge remote-tracking branch 'upstream/master' into dev

# Conflicts:
#	packages/shared/src/validators/company-skill.ts
#	packages/shared/src/validators/index.ts
#	server/src/__tests__/company-skills-routes.test.ts
#	server/src/routes/company-skills.ts
#	server/src/services/company-skills.ts
#	ui/src/pages/CompanySkills.tsx

packages/adapter-utils/README.md

@@ -0,0 +1,37 @@
+# @paperclipai/adapter-utils
+
+Shared utilities for Paperclip adapters: process spawning, environment
+injection, sandbox/SSH transport, workspace sync, and the round-trip helpers
+that move code between the local execution-workspace cwd and wherever the
+agent actually runs.
+
+For the adapter-author guide see
+[`docs/adapters/creating-an-adapter.md`](../../docs/adapters/creating-an-adapter.md)
+and the in-repo notes at [`packages/adapters/AUTHORING.md`](../adapters/AUTHORING.md).
+
+## No-remote-git contract
+
+The local execution-workspace cwd is the only persistence boundary across
+runs. No adapter may depend on a git remote for cross-run state.
+
+Adapters that run the agent on a different host should use the SSH round-trip
+helpers in [`src/ssh.ts`](./src/ssh.ts):
+
+- `prepareWorkspaceForSshExecution({ spec, localDir, remoteDir })` — bundles
+  the local cwd (tracked files, dirty edits, untracked additions, and the git
+  history needed to reconstruct it) to `remoteDir` before the run starts. Runs
+  with no `git remote` configured.
+- `restoreWorkspaceFromSshExecution({ spec, localDir, remoteDir, ... })` —
+  syncs the remote cwd back into `localDir` after the run, including any new
+  commits the agent created. Also runs with no `git remote` configured.
+
+`prepareRemoteManagedRuntime` in
+[`src/remote-managed-runtime.ts`](./src/remote-managed-runtime.ts) wraps both
+calls for adapters that want a per-run remote workspace and an automatic
+`restoreWorkspace()` finally hook.
+
+The invariant is pinned by the `no-remote-git contract` case in
+[`src/ssh-fixture.test.ts`](./src/ssh-fixture.test.ts), which asserts that a
+remote-only commit propagates to the local worktree through the
+prepare → restore round-trip with no git remote configured at any point. Do
+not regress that test.

packages/adapter-utils/src/server-utils.test.ts

@@ -6,6 +6,8 @@ import { describe, expect, it } from "vitest";
 import {
   applyPaperclipWorkspaceEnv,
   appendWithByteCap,
+  buildPersistentSkillSnapshot,
+  buildRuntimeMountedSkillSnapshot,
   buildInvocationEnvForLogs,
   DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
   materializePaperclipSkillCopy,
@@ -205,6 +207,186 @@ describe("materializePaperclipSkillCopy", () => {
   });
 });
 
+describe("adapter skill snapshots", () => {
+  const requiredEntry = {
+    key: "paperclipai/paperclip/paperclip",
+    runtimeName: "paperclip",
+    source: "/runtime/paperclip",
+    required: true,
+    requiredReason: "Required for Paperclip heartbeats.",
+  };
+  const optionalEntry = {
+    key: "company/ascii-heart",
+    runtimeName: "ascii-heart",
+    source: "/runtime/ascii-heart",
+  };
+
+  it("reports runtime-mounted adapters as configured or missing without install state", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "codex_local",
+      availableEntries: [requiredEntry],
+      desiredSkills: [requiredEntry.key, "missing-skill"],
+      configuredDetail: "Mounted on next run.",
+    });
+
+    expect(snapshot).toMatchObject({
+      supported: true,
+      mode: "ephemeral",
+      desiredSkills: [requiredEntry.key, "missing-skill"],
+    });
+    expect(snapshot.entries).toEqual([
+      expect.objectContaining({
+        key: "missing-skill",
+        state: "missing",
+        origin: "external_unknown",
+        desired: true,
+      }),
+      expect.objectContaining({
+        key: requiredEntry.key,
+        state: "configured",
+        origin: "paperclip_required",
+        required: true,
+        detail: "Mounted on next run.",
+      }),
+    ]);
+  });
+
+  it("reports source-missing company runtime skills without orphan warnings", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "codex_local",
+      availableEntries: [{
+        key: "company/example/reflection-coach",
+        runtimeName: "reflection-coach--abc123",
+        source: "/paperclip/skills/example/__runtime__/reflection-coach--abc123",
+        sourceStatus: "missing",
+        missingDetail: "Company skill exists, but its local source is missing.",
+      }],
+      desiredSkills: ["company/example/reflection-coach"],
+      configuredDetail: "Mounted on next run.",
+    });
+
+    expect(snapshot.warnings).toEqual([]);
+    expect(snapshot.entries).toEqual([
+      expect.objectContaining({
+        key: "company/example/reflection-coach",
+        state: "missing",
+        origin: "company_managed",
+        sourcePath: null,
+        detail: "Company skill exists, but its local source is missing.",
+      }),
+    ]);
+  });
+
+  it("keeps unsupported runtime-mounted adapters in tracked-only state", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "acpx_local",
+      availableEntries: [requiredEntry],
+      desiredSkills: [requiredEntry.key],
+      configuredDetail: "Mounted on next run.",
+      mode: "unsupported",
+      unsupportedDetail: "Tracked only.",
+    });
+
+    expect(snapshot.supported).toBe(false);
+    expect(snapshot.mode).toBe("unsupported");
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: requiredEntry.key,
+      desired: true,
+      state: "available",
+      detail: "Tracked only.",
+    }));
+  });
+
+  it("can surface read-only external skills for runtime-mounted adapters", () => {
+    const snapshot = buildRuntimeMountedSkillSnapshot({
+      adapterType: "claude_local",
+      availableEntries: [requiredEntry],
+      desiredSkills: [requiredEntry.key],
+      configuredDetail: "Mounted on next run.",
+      externalInstalled: new Map([
+        ["crack-python", { targetPath: "/home/me/.claude/skills/crack-python", kind: "directory" }],
+      ]),
+      externalLocationLabel: "~/.claude/skills",
+      externalDetail: "Installed outside Paperclip management in the Claude skills home.",
+    });
+
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "crack-python",
+      runtimeName: "crack-python",
+      state: "external",
+      managed: false,
+      origin: "user_installed",
+      locationLabel: "~/.claude/skills",
+      readOnly: true,
+    }));
+  });
+
+  it("reports persistent adapter installed, stale, external, and missing states", () => {
+    const snapshot = buildPersistentSkillSnapshot({
+      adapterType: "cursor",
+      availableEntries: [requiredEntry, optionalEntry],
+      desiredSkills: [requiredEntry.key, "missing-skill"],
+      installed: new Map([
+        ["paperclip", { targetPath: "/runtime/paperclip", kind: "symlink" }],
+        ["ascii-heart", { targetPath: "/other/ascii-heart", kind: "directory" }],
+        ["old-managed", { targetPath: "/runtime/old-managed", kind: "symlink" }],
+      ]),
+      skillsHome: "/home/me/.cursor/skills",
+      locationLabel: "~/.cursor/skills",
+      installedDetail: "Installed in the Cursor skills home.",
+      missingDetail: "Configured but not linked.",
+      externalConflictDetail: "Name occupied externally.",
+      externalDetail: "Installed outside Paperclip management.",
+    });
+
+    expect(snapshot.mode).toBe("persistent");
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: requiredEntry.key,
+      state: "installed",
+      managed: true,
+      origin: "paperclip_required",
+    }));
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: optionalEntry.key,
+      state: "external",
+      managed: false,
+      detail: "Installed outside Paperclip management.",
+    }));
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "missing-skill",
+      state: "missing",
+      origin: "external_unknown",
+    }));
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: "old-managed",
+      state: "external",
+      origin: "user_installed",
+    }));
+  });
+
+  it("reports stale managed persistent skills when Paperclip owns an undesired available skill", () => {
+    const snapshot = buildPersistentSkillSnapshot({
+      adapterType: "cursor",
+      availableEntries: [optionalEntry],
+      desiredSkills: [],
+      installed: new Map([
+        ["ascii-heart", { targetPath: "/runtime/ascii-heart", kind: "symlink" }],
+      ]),
+      skillsHome: "/home/me/.cursor/skills",
+      missingDetail: "Configured but not linked.",
+      externalConflictDetail: "Name occupied externally.",
+      externalDetail: "Installed outside Paperclip management.",
+    });
+
+    expect(snapshot.entries).toContainEqual(expect.objectContaining({
+      key: optionalEntry.key,
+      desired: false,
+      state: "stale",
+      managed: true,
+    }));
+  });
+});
+
 describe("runChildProcess", () => {
   it("does not arm a timeout when timeoutSec is 0", async () => {
     const result = await runChildProcess(

packages/adapter-utils/src/server-utils.ts

@@ -133,6 +133,8 @@ export interface PaperclipSkillEntry {
   key: string;
   runtimeName: string;
   source: string;
+  sourceStatus?: "available" | "missing";
+  missingDetail?: string | null;
   required?: boolean;
   requiredReason?: string | null;
 }
@@ -161,6 +163,22 @@ interface PersistentSkillSnapshotOptions {
   warnings?: string[];
 }
 
+interface RuntimeMountedSkillSnapshotOptions {
+  adapterType: string;
+  availableEntries: PaperclipSkillEntry[];
+  desiredSkills: string[];
+  configuredDetail: string | ((entry: PaperclipSkillEntry) => string | null);
+  missingDetail?: string;
+  mode?: "ephemeral" | "unsupported";
+  supported?: boolean;
+  unsupportedDetail?: string | ((entry: PaperclipSkillEntry) => string | null);
+  warnings?: string[];
+  externalInstalled?: Map<string, InstalledSkillTarget>;
+  externalLocationLabel?: string | null;
+  externalDetail?: string;
+  skillsHome?: string;
+}
+
 function normalizePathSlashes(value: string): string {
   return value.replaceAll("\\", "/");
 }
@@ -193,6 +211,26 @@ function buildManagedSkillOrigin(entry: { required?: boolean }): Pick<
   };
 }
 
+function isPaperclipSkillSourceMissing(entry: PaperclipSkillEntry) {
+  return entry.sourceStatus === "missing";
+}
+
+function resolvePaperclipSkillMissingDetail(
+  entry: PaperclipSkillEntry,
+  fallback: string,
+) {
+  return entry.missingDetail?.trim() || fallback;
+}
+
+function resolveSkillDetail(
+  detail: string | ((entry: PaperclipSkillEntry) => string | null) | null | undefined,
+  entry: PaperclipSkillEntry,
+): string | null {
+  if (typeof detail === "function") return detail(entry);
+  if (typeof detail === "string") return detail;
+  return null;
+}
+
 function resolveInstalledEntryTarget(
   skillsHome: string,
   entryName: string,
@@ -1381,6 +1419,120 @@ export async function readInstalledSkillTargets(skillsHome: string): Promise<Map
   return out;
 }
 
+export function buildRuntimeMountedSkillSnapshot(
+  options: RuntimeMountedSkillSnapshotOptions,
+): AdapterSkillSnapshot {
+  const {
+    adapterType,
+    availableEntries,
+    desiredSkills,
+    configuredDetail,
+    missingDetail = "Paperclip cannot find this skill in the local runtime skills directory.",
+    mode = "ephemeral",
+    externalInstalled,
+    externalLocationLabel,
+    externalDetail = "Installed outside Paperclip management.",
+    skillsHome,
+  } = options;
+  const supported = options.supported ?? mode !== "unsupported";
+  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
+  const desiredSet = new Set(desiredSkills);
+  const entries: AdapterSkillEntry[] = [];
+  const warnings = [...(options.warnings ?? [])];
+
+  for (const available of availableEntries) {
+    const desired = desiredSet.has(available.key);
+    if (isPaperclipSkillSourceMissing(available)) {
+      entries.push({
+        key: available.key,
+        runtimeName: available.runtimeName,
+        desired,
+        managed: true,
+        state: "missing",
+        sourcePath: null,
+        targetPath: null,
+        detail: resolvePaperclipSkillMissingDetail(available, missingDetail),
+        required: Boolean(available.required),
+        requiredReason: available.requiredReason ?? null,
+        ...buildManagedSkillOrigin(available),
+      });
+      continue;
+    }
+
+    const configured = supported && mode === "ephemeral" && desired;
+    entries.push({
+      key: available.key,
+      runtimeName: available.runtimeName,
+      desired,
+      managed: true,
+      state: configured ? "configured" : "available",
+      sourcePath: available.source,
+      targetPath: null,
+      detail: desired
+        ? configured
+          ? resolveSkillDetail(configuredDetail, available)
+          : resolveSkillDetail(
+              options.unsupportedDetail
+                ?? "Desired state is stored in Paperclip only; this adapter cannot apply skills at runtime.",
+              available,
+            )
+        : null,
+      required: Boolean(available.required),
+      requiredReason: available.requiredReason ?? null,
+      ...buildManagedSkillOrigin(available),
+    });
+  }
+
+  for (const desiredSkill of desiredSkills) {
+    if (availableByKey.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      key: desiredSkill,
+      runtimeName: null,
+      desired: true,
+      managed: true,
+      state: "missing",
+      sourcePath: null,
+      targetPath: null,
+      detail: missingDetail,
+      origin: "external_unknown",
+      originLabel: "External or unavailable",
+      readOnly: false,
+    });
+  }
+
+  if (externalInstalled) {
+    for (const [name, installedEntry] of externalInstalled.entries()) {
+      if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
+      entries.push({
+        key: name,
+        runtimeName: name,
+        desired: false,
+        managed: false,
+        state: "external",
+        origin: "user_installed",
+        originLabel: "User-installed",
+        locationLabel: skillLocationLabel(externalLocationLabel),
+        readOnly: true,
+        sourcePath: null,
+        targetPath: installedEntry.targetPath ?? (skillsHome ? path.join(skillsHome, name) : null),
+        detail: externalDetail,
+      });
+    }
+  }
+
+  entries.sort((left, right) => left.key.localeCompare(right.key));
+
+  return {
+    adapterType,
+    supported,
+    mode,
+    desiredSkills,
+    entries,
+    warnings,
+  };
+}
+
 export function buildPersistentSkillSnapshot(
   options: PersistentSkillSnapshotOptions,
 ): AdapterSkillSnapshot {
@@ -1404,6 +1556,26 @@ export function buildPersistentSkillSnapshot(
   for (const available of availableEntries) {
     const installedEntry = installed.get(available.runtimeName) ?? null;
     const desired = desiredSet.has(available.key);
+    if (isPaperclipSkillSourceMissing(available)) {
+      entries.push({
+        key: available.key,
+        runtimeName: available.runtimeName,
+        desired,
+        managed: true,
+        state: "missing",
+        sourcePath: null,
+        targetPath: path.join(skillsHome, available.runtimeName),
+        detail: resolvePaperclipSkillMissingDetail(
+          available,
+          missingDetail,
+        ),
+        required: Boolean(available.required),
+        requiredReason: available.requiredReason ?? null,
+        ...buildManagedSkillOrigin(available),
+      });
+      continue;
+    }
+
     let state: AdapterSkillEntry["state"] = "available";
     let managed = false;
     let detail: string | null = null;
@@ -1496,6 +1668,11 @@ function normalizeConfiguredPaperclipRuntimeSkills(value: unknown): PaperclipSki
       key,
       runtimeName,
       source,
+      sourceStatus: entry.sourceStatus === "missing" ? "missing" : "available",
+      missingDetail:
+        typeof entry.missingDetail === "string" && entry.missingDetail.trim().length > 0
+          ? entry.missingDetail.trim()
+          : null,
       required: asBoolean(entry.required, false),
       requiredReason:
         typeof entry.requiredReason === "string" && entry.requiredReason.trim().length > 0

packages/adapter-utils/src/ssh-fixture.test.ts

@@ -451,6 +451,68 @@ describe("ssh env-lab fixture", () => {
     await expect(readFile(path.join(localRepo, "tracked.txt"), "utf8")).resolves.toBe("dirty remote\n");
   }, SSH_FIXTURE_TEST_TIMEOUT_MS);
 
+  it("propagates remote commits to the local worktree with no git remote configured (no-remote-git contract)", async () => {
+    // Locks in the architectural contract documented in
+    // packages/adapter-utils/README.md and packages/adapters/AUTHORING.md:
+    // the local execution-workspace cwd is the only persistence boundary
+    // across runs. No adapter may depend on a git remote for cross-run state.
+    const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
+    cleanupDirs.push(rootDir);
+    const statePath = path.join(rootDir, "state.json");
+    const localRepo = path.join(rootDir, "local-workspace");
+
+    await mkdir(localRepo, { recursive: true });
+    await git(localRepo, ["init"]);
+    await git(localRepo, ["checkout", "-b", "main"]);
+    await git(localRepo, ["config", "user.name", "Paperclip Test"]);
+    await git(localRepo, ["config", "user.email", "test@paperclip.dev"]);
+    await writeFile(path.join(localRepo, "tracked.txt"), "base\n", "utf8");
+    await git(localRepo, ["add", "tracked.txt"]);
+    await git(localRepo, ["commit", "-m", "initial"]);
+
+    // Assert there is no git remote configured before we begin, and verify
+    // that no point in the round-trip introduces one. `git remote` returns an
+    // empty string when no remotes exist (and exit code 0).
+    expect(await git(localRepo, ["remote"])).toBe("");
+
+    const started = await startSshEnvLabFixtureOrSkip(
+      statePath,
+      "no-remote-git contract test",
+    );
+    if (!started) return;
+    const config = await buildSshEnvLabFixtureConfig(started);
+    const spec = {
+      ...config,
+      remoteCwd: started.workspaceDir,
+    } as const;
+
+    const prepared = await prepareRemoteManagedRuntime({
+      spec,
+      runId: "run-no-remote",
+      adapterKey: "test-adapter",
+      workspaceLocalDir: localRepo,
+    });
+
+    // Remote commit lands a deliverable that must show up locally via
+    // sync-back alone — no `git push`, no fetch from any origin.
+    await runSshCommand(
+      config,
+      `cd ${JSON.stringify(prepared.workspaceRemoteDir)} && git config user.name "Paperclip SSH" && git config user.email "ssh@paperclip.dev" && printf "deliverable\\n" > tracked.txt && git add tracked.txt && git commit -m "remote-only commit" >/dev/null`,
+      { timeoutMs: 30_000, maxBuffer: 256 * 1024 },
+    );
+
+    await prepared.restoreWorkspace();
+
+    expect(await git(localRepo, ["log", "-1", "--pretty=%s"])).toBe(
+      "remote-only commit",
+    );
+    expect(await readFile(path.join(localRepo, "tracked.txt"), "utf8")).toBe(
+      "deliverable\n",
+    );
+    // Final assertion: still no git remote — restore did not silently add one.
+    expect(await git(localRepo, ["remote"])).toBe("");
+  }, SSH_FIXTURE_TEST_TIMEOUT_MS);
+
   it("merges concurrent remote commits through the managed runtime restore path", async () => {
     const rootDir = await mkdtemp(path.join(os.tmpdir(), "paperclip-ssh-fixture-"));
     cleanupDirs.push(rootDir);

packages/adapters/AUTHORING.md

@@ -0,0 +1,58 @@
+# Adapter Authoring Notes
+
+In-repo notes for adapter authors. The user-facing guide lives at
+[`docs/adapters/creating-an-adapter.md`](../../docs/adapters/creating-an-adapter.md);
+this file holds invariants that are easy to violate from inside the adapter
+package itself.
+
+## No-remote-git contract (cross-run persistence)
+
+The local execution-workspace cwd is the only persistence boundary across
+runs. No adapter may depend on a git remote for cross-run state.
+
+Why: Paperclip resolves a local execution workspace (a worktree) for each
+heartbeat. Code state is carried forward by syncing that local cwd to wherever
+the agent actually runs — over ssh, into a sandbox, into a managed runtime —
+and then syncing changes back when the run finishes. Treating a `git remote`
+as the source of truth (`git push` from inside the agent, fetch on the next
+wake) breaks dependent issues that are gated on the local worktree being
+caught up, and breaks isolated execution workspaces that have no remote
+configured at all.
+
+How to apply:
+
+- Never `git push` from adapter runtime code. Never assume the local worktree
+  has any `git remote` configured. If you need data from the previous run,
+  read it from the local cwd Paperclip handed you.
+- If your adapter runs the agent on a different host (ssh, sandbox, remote
+  container), use the round-trip helpers in `@paperclipai/adapter-utils`:
+  [`prepareWorkspaceForSshExecution`](../adapter-utils/src/ssh.ts) bundles the
+  local cwd to the remote dir before the run, and
+  [`restoreWorkspaceFromSshExecution`](../adapter-utils/src/ssh.ts) syncs
+  remote-side changes (including new git commits) back into the local cwd
+  after the run. Both run with no `git remote` configured.
+- If your adapter runs the agent locally, you can read and write the cwd
+  directly — same invariant applies: changes that future runs need must live
+  in the local cwd by the time `execute()` returns.
+- A failed sync-back is a run-level error. The heartbeat records
+  `workspace_finalize=failed` on the execution workspace, which gates
+  dependent issue wakes until the next successful finalize. Do not swallow
+  restore errors.
+
+The invariant is pinned by the `no-remote-git contract` case in
+[`packages/adapter-utils/src/ssh-fixture.test.ts`](../adapter-utils/src/ssh-fixture.test.ts),
+which asserts that a remote-only commit propagates to the local worktree
+through `prepareWorkspaceForSshExecution` → `restoreWorkspaceFromSshExecution`
+with no git remote configured at any point.
+
+A static check enforces the rule before runtime ever sees it:
+[`scripts/check-no-git-push.mjs`](../../scripts/check-no-git-push.mjs) scans
+adapter and runtime source (`packages/adapters/`, `packages/adapter-utils/`,
+`server/src/`, `cli/src/`) and fails the `policy` CI job if any unapproved
+`git push` invocation is added. If you are building an operator-configured
+path that legitimately must push, add a
+`// paperclip:allow-git-push: <reason>` comment on the line (or the line
+above) so the opt-in shows up in code review.
+
+For the architecture-level write-up of cross-run persistence, see
+[`docs/guides/board-operator/execution-workspaces-and-runtime-services.md`](../../docs/guides/board-operator/execution-workspaces-and-runtime-services.md#cross-run-persistence-no-remote-git-contract).

packages/adapters/acpx-local/src/server/skills.ts

@@ -2,10 +2,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -35,9 +35,7 @@ function unsupportedDetail(): string {
 async function buildAcpxSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
   const acpxAgent = normalizeAcpxSkillAgent(config);
   const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
-  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
   const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
-  const desiredSet = new Set(desiredSkills);
   const supported = acpxAgent !== "custom";
   const warnings: string[] = supported
     ? []
@@ -45,53 +43,16 @@ async function buildAcpxSkillSnapshot(config: Record<string, unknown>): Promise<
         "Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",
       ];
 
-  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => {
-    const desired = desiredSet.has(entry.key);
-    return {
-      key: entry.key,
-      runtimeName: entry.runtimeName,
-      desired,
-      managed: true,
-      state: desired ? "configured" : "available",
-      origin: entry.required ? "paperclip_required" : "company_managed",
-      originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
-      readOnly: false,
-      sourcePath: entry.source,
-      targetPath: null,
-      detail: desired ? (supported ? configuredDetail(acpxAgent) : unsupportedDetail()) : null,
-      required: Boolean(entry.required),
-      requiredReason: entry.requiredReason ?? null,
-    };
-  });
-
-  for (const desiredSkill of desiredSkills) {
-    if (availableByKey.has(desiredSkill)) continue;
-    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
-    entries.push({
-      key: desiredSkill,
-      runtimeName: null,
-      desired: true,
-      managed: true,
-      state: "missing",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: null,
-      targetPath: null,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "acpx_local",
+    availableEntries,
+    desiredSkills,
     supported,
     mode: supported ? "ephemeral" : "unsupported",
-    desiredSkills,
-    entries,
+    configuredDetail: configuredDetail(acpxAgent),
+    unsupportedDetail: unsupportedDetail(),
     warnings,
-  };
+  });
 }
 
 export async function listAcpxSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

packages/adapters/claude-local/src/index.ts

@@ -6,6 +6,7 @@ export const label = "Claude Code (local)";
 export const SANDBOX_INSTALL_COMMAND = "npm install -g @anthropic-ai/claude-code";
 
 export const models = [
+  { id: "claude-opus-4-8", label: "Claude Opus 4.8" },
   { id: "claude-opus-4-7", label: "Claude Opus 4.7" },
   { id: "claude-opus-4-6", label: "Claude Opus 4.6" },
   { id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6" },

packages/adapters/claude-local/src/server/index.ts

@@ -1,6 +1,6 @@
 export { claudeSessionCwdMatchesExecutionTarget, execute, runClaudeLogin } from "./execute.js";
 export { listClaudeSkills, syncClaudeSkills } from "./skills.js";
-export { listClaudeModels } from "./models.js";
+export { listClaudeModels, refreshClaudeModels, resetClaudeModelsCacheForTests } from "./models.js";
 export { testEnvironment } from "./test.js";
 export {
   parseClaudeStreamJson,

packages/adapters/claude-local/src/server/models.ts

@@ -1,13 +1,22 @@
+import { createHash } from "node:crypto";
 import type { AdapterModel } from "@paperclipai/adapter-utils";
 import { models as DIRECT_MODELS } from "../index.js";
 
+const ANTHROPIC_MODELS_ENDPOINT = "/v1/models";
+const ANTHROPIC_MODELS_TIMEOUT_MS = 5000;
+const ANTHROPIC_MODELS_CACHE_TTL_MS = 60_000;
+const ANTHROPIC_API_VERSION = "2023-06-01";
+
 /** AWS Bedrock model IDs — region-qualified identifiers required by the Bedrock API. */
 const BEDROCK_MODELS: AdapterModel[] = [
+  { id: "us.anthropic.claude-opus-4-8-v1", label: "Bedrock Opus 4.8" },
   { id: "us.anthropic.claude-opus-4-6-v1", label: "Bedrock Opus 4.6" },
   { id: "us.anthropic.claude-sonnet-4-5-20250929-v2:0", label: "Bedrock Sonnet 4.5" },
   { id: "us.anthropic.claude-haiku-4-5-20251001-v1:0", label: "Bedrock Haiku 4.5" },
 ];
 
+let cached: { keyFingerprint: string; baseUrl: string; expiresAt: number; models: AdapterModel[] } | null = null;
+
 function isBedrockEnv(): boolean {
   return (
     process.env.CLAUDE_CODE_USE_BEDROCK === "1" ||
@@ -17,13 +26,134 @@ function isBedrockEnv(): boolean {
   );
 }
 
+function fingerprint(apiKey: string): string {
+  const digest = createHash("sha256").update(apiKey).digest("base64url").slice(0, 16);
+  return `${apiKey.length}:${digest}`;
+}
+
+function dedupeModels(models: AdapterModel[]): AdapterModel[] {
+  const seen = new Set<string>();
+  const deduped: AdapterModel[] = [];
+  for (const model of models) {
+    const id = model.id.trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    deduped.push({ id, label: model.label.trim() || id });
+  }
+  return deduped;
+}
+
+function mergedWithFallback(models: AdapterModel[]): AdapterModel[] {
+  return dedupeModels([
+    ...models,
+    ...DIRECT_MODELS,
+  ]);
+}
+
+function resolveAnthropicApiKey(): string | null {
+  const apiKey = process.env.ANTHROPIC_API_KEY?.trim();
+  return apiKey && apiKey.length > 0 ? apiKey : null;
+}
+
+function resolveAnthropicBaseUrl(): string {
+  const baseUrl = process.env.ANTHROPIC_BASE_URL?.trim();
+  return baseUrl && baseUrl.length > 0 ? baseUrl.replace(/\/+$/, "") : "https://api.anthropic.com";
+}
+
+async function fetchAnthropicModels(apiKey: string, baseUrl: string): Promise<AdapterModel[]> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), ANTHROPIC_MODELS_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${baseUrl}${ANTHROPIC_MODELS_ENDPOINT}`, {
+      headers: {
+        "anthropic-version": ANTHROPIC_API_VERSION,
+        "x-api-key": apiKey,
+      },
+      signal: controller.signal,
+    });
+    if (!response.ok) return [];
+
+    const payload = (await response.json()) as { data?: unknown };
+    const data = Array.isArray(payload.data) ? payload.data : [];
+    const models: AdapterModel[] = [];
+    for (const item of data) {
+      if (typeof item !== "object" || item === null) continue;
+      const record = item as { id?: unknown; display_name?: unknown };
+      if (typeof record.id !== "string" || record.id.trim().length === 0) continue;
+      const displayName =
+        typeof record.display_name === "string" && record.display_name.trim().length > 0
+          ? record.display_name
+          : record.id;
+      models.push({
+        id: record.id,
+        label: displayName,
+      });
+    }
+    return dedupeModels(models);
+  } catch (error) {
+    console.warn("[paperclip] Claude model discovery failed", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return [];
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function loadClaudeModels(options?: { forceRefresh?: boolean }): Promise<AdapterModel[]> {
+  if (isBedrockEnv()) return dedupeModels(BEDROCK_MODELS);
+
+  const fallback = dedupeModels(DIRECT_MODELS);
+  const apiKey = resolveAnthropicApiKey();
+  if (!apiKey) return fallback;
+
+  const now = Date.now();
+  const baseUrl = resolveAnthropicBaseUrl();
+  const keyFingerprint = fingerprint(apiKey);
+  if (
+    options?.forceRefresh !== true &&
+    cached &&
+    cached.keyFingerprint === keyFingerprint &&
+    cached.baseUrl === baseUrl &&
+    cached.expiresAt > now
+  ) {
+    return cached.models;
+  }
+
+  const fetched = await fetchAnthropicModels(apiKey, baseUrl);
+  if (fetched.length > 0) {
+    const merged = mergedWithFallback(fetched);
+    cached = {
+      keyFingerprint,
+      baseUrl,
+      expiresAt: now + ANTHROPIC_MODELS_CACHE_TTL_MS,
+      models: merged,
+    };
+    return merged;
+  }
+
+  if (cached && cached.keyFingerprint === keyFingerprint && cached.baseUrl === baseUrl && cached.models.length > 0) {
+    return cached.models;
+  }
+
+  return fallback;
+}
+
 /**
  * Return the model list appropriate for the current auth mode.
  * When Bedrock env vars are detected, returns Bedrock-native model IDs;
  * otherwise returns standard Anthropic API model IDs.
  */
 export async function listClaudeModels(): Promise<AdapterModel[]> {
-  return isBedrockEnv() ? BEDROCK_MODELS : DIRECT_MODELS;
+  return loadClaudeModels();
+}
+
+export async function refreshClaudeModels(): Promise<AdapterModel[]> {
+  return loadClaudeModels({ forceRefresh: true });
+}
+
+export function resetClaudeModelsCacheForTests() {
+  cached = null;
 }
 
 /** Check whether a model ID is a Bedrock-native identifier (not an Anthropic API short name). */

packages/adapters/claude-local/src/server/skills.ts

@@ -3,10 +3,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   readInstalledSkillTargets,
   resolvePaperclipDesiredSkillNames,
@@ -30,76 +30,19 @@ function resolveClaudeSkillsHome(config: Record<string, unknown>) {
 
 async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
   const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
-  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
   const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
-  const desiredSet = new Set(desiredSkills);
   const skillsHome = resolveClaudeSkillsHome(config);
   const installed = await readInstalledSkillTargets(skillsHome);
-  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
-    key: entry.key,
-    runtimeName: entry.runtimeName,
-    desired: desiredSet.has(entry.key),
-    managed: true,
-    state: desiredSet.has(entry.key) ? "configured" : "available",
-    origin: entry.required ? "paperclip_required" : "company_managed",
-    originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
-    readOnly: false,
-    sourcePath: entry.source,
-    targetPath: null,
-    detail: desiredSet.has(entry.key)
-      ? "Will be materialized into the stable Paperclip-managed Claude prompt bundle on the next run."
-      : null,
-    required: Boolean(entry.required),
-    requiredReason: entry.requiredReason ?? null,
-  }));
-  const warnings: string[] = [];
-
-  for (const desiredSkill of desiredSkills) {
-    if (availableByKey.has(desiredSkill)) continue;
-    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
-    entries.push({
-      key: desiredSkill,
-      runtimeName: null,
-      desired: true,
-      managed: true,
-      state: "missing",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: undefined,
-      targetPath: undefined,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  for (const [name, installedEntry] of installed.entries()) {
-    if (availableEntries.some((entry) => entry.runtimeName === name)) continue;
-    entries.push({
-      key: name,
-      runtimeName: name,
-      desired: false,
-      managed: false,
-      state: "external",
-      origin: "user_installed",
-      originLabel: "User-installed",
-      locationLabel: "~/.claude/skills",
-      readOnly: true,
-      sourcePath: null,
-      targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
-      detail: "Installed outside Paperclip management in the Claude skills home.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "claude_local",
-    supported: true,
-    mode: "ephemeral",
+    availableEntries,
     desiredSkills,
-    entries,
-    warnings,
-  };
+    configuredDetail: "Will be materialized into the stable Paperclip-managed Claude prompt bundle on the next run.",
+    externalInstalled: installed,
+    externalLocationLabel: "~/.claude/skills",
+    externalDetail: "Installed outside Paperclip management in the Claude skills home.",
+    skillsHome,
+  });
 }
 
 export async function listClaudeSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

packages/adapters/codex-local/src/server/skills.ts

@@ -2,10 +2,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -16,56 +16,13 @@ async function buildCodexSkillSnapshot(
   config: Record<string, unknown>,
 ): Promise<AdapterSkillSnapshot> {
   const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
-  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
   const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
-  const desiredSet = new Set(desiredSkills);
-  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
-    key: entry.key,
-    runtimeName: entry.runtimeName,
-    desired: desiredSet.has(entry.key),
-    managed: true,
-    state: desiredSet.has(entry.key) ? "configured" : "available",
-    origin: entry.required ? "paperclip_required" : "company_managed",
-    originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
-    readOnly: false,
-    sourcePath: entry.source,
-    targetPath: null,
-    detail: desiredSet.has(entry.key)
-      ? "Will be linked into the effective CODEX_HOME/skills/ directory on the next run."
-      : null,
-    required: Boolean(entry.required),
-    requiredReason: entry.requiredReason ?? null,
-  }));
-  const warnings: string[] = [];
-
-  for (const desiredSkill of desiredSkills) {
-    if (availableByKey.has(desiredSkill)) continue;
-    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
-    entries.push({
-      key: desiredSkill,
-      runtimeName: null,
-      desired: true,
-      managed: true,
-      state: "missing",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: null,
-      targetPath: null,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "codex_local",
-    supported: true,
-    mode: "ephemeral",
+    availableEntries,
     desiredSkills,
-    entries,
-    warnings,
-  };
+    configuredDetail: "Will be linked into the effective CODEX_HOME/skills/ directory on the next run.",
+  });
 }
 
 export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

packages/adapters/grok-local/src/server/skills.ts

@@ -2,10 +2,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
   AdapterSkillContext,
-  AdapterSkillEntry,
   AdapterSkillSnapshot,
 } from "@paperclipai/adapter-utils";
 import {
+  buildRuntimeMountedSkillSnapshot,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
 } from "@paperclipai/adapter-utils/server-utils";
@@ -16,56 +16,13 @@ async function buildGrokSkillSnapshot(
   config: Record<string, unknown>,
 ): Promise<AdapterSkillSnapshot> {
   const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
-  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
   const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
-  const desiredSet = new Set(desiredSkills);
-  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
-    key: entry.key,
-    runtimeName: entry.runtimeName,
-    desired: desiredSet.has(entry.key),
-    managed: true,
-    state: desiredSet.has(entry.key) ? "configured" : "available",
-    origin: entry.required ? "paperclip_required" : "company_managed",
-    originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
-    readOnly: false,
-    sourcePath: entry.source,
-    targetPath: null,
-    detail: desiredSet.has(entry.key)
-      ? "Will be copied into `.claude/skills` in the execution workspace on the next run."
-      : null,
-    required: Boolean(entry.required),
-    requiredReason: entry.requiredReason ?? null,
-  }));
-  const warnings: string[] = [];
-
-  for (const desiredSkill of desiredSkills) {
-    if (availableByKey.has(desiredSkill)) continue;
-    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
-    entries.push({
-      key: desiredSkill,
-      runtimeName: null,
-      desired: true,
-      managed: true,
-      state: "missing",
-      origin: "external_unknown",
-      originLabel: "External or unavailable",
-      readOnly: false,
-      sourcePath: null,
-      targetPath: null,
-      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
-    });
-  }
-
-  entries.sort((left, right) => left.key.localeCompare(right.key));
-
-  return {
+  return buildRuntimeMountedSkillSnapshot({
     adapterType: "grok_local",
-    supported: true,
-    mode: "ephemeral",
+    availableEntries,
     desiredSkills,
-    entries,
-    warnings,
-  };
+    configuredDetail: "Will be copied into `.claude/skills` in the execution workspace on the next run.",
+  });
 }
 
 export async function listGrokSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {

packages/adapters/openclaw-gateway/README.md

@@ -70,3 +70,16 @@ Structured gateway event logs use:
 - `[openclaw-gateway:event] run=<id> stream=<stream> data=<json>` for `event agent` frames
 
 UI/CLI parsers consume these lines to render transcript updates.
+
+## No-remote-git contract
+
+Like every Paperclip adapter, this one must treat the local execution-workspace
+cwd as the only persistence boundary across runs — no `git push` from runtime
+code, no assuming a `git remote` exists. The gateway transport here doesn't
+touch the workspace directly, but if you extend the adapter to ship code to
+the OpenClaw side, use the round-trip helpers in `@paperclipai/adapter-utils`
+(`prepareWorkspaceForSshExecution` → `restoreWorkspaceFromSshExecution`)
+rather than reaching for a git remote. See
+[`packages/adapters/AUTHORING.md`](../AUTHORING.md#no-remote-git-contract-cross-run-persistence)
+for the full contract and the pinning test at
+[`packages/adapter-utils/src/ssh-fixture.test.ts`](../../adapter-utils/src/ssh-fixture.test.ts).

packages/db/src/migrations/0091_old_swarm.sql

@@ -0,0 +1,189 @@
+CREATE TABLE IF NOT EXISTS "document_annotation_threads" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"issue_id" uuid NOT NULL,
+	"document_id" uuid NOT NULL,
+	"document_key" text NOT NULL,
+	"status" text DEFAULT 'open' NOT NULL,
+	"anchor_state" text DEFAULT 'active' NOT NULL,
+	"original_revision_id" uuid,
+	"original_revision_number" integer NOT NULL,
+	"current_revision_id" uuid,
+	"current_revision_number" integer NOT NULL,
+	"selected_text" text NOT NULL,
+	"prefix_text" text DEFAULT '' NOT NULL,
+	"suffix_text" text DEFAULT '' NOT NULL,
+	"normalized_start" integer NOT NULL,
+	"normalized_end" integer NOT NULL,
+	"markdown_start" integer NOT NULL,
+	"markdown_end" integer NOT NULL,
+	"anchor_confidence" text DEFAULT 'exact' NOT NULL,
+	"anchor_selector" jsonb NOT NULL,
+	"created_by_agent_id" uuid,
+	"created_by_user_id" text,
+	"resolved_by_agent_id" uuid,
+	"resolved_by_user_id" 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
+CREATE TABLE IF NOT EXISTS "document_annotation_comments" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"thread_id" uuid NOT NULL,
+	"issue_id" uuid NOT NULL,
+	"document_id" uuid NOT NULL,
+	"body" text NOT NULL,
+	"author_type" text NOT NULL,
+	"author_agent_id" uuid,
+	"author_user_id" text,
+	"created_by_run_id" uuid,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "document_annotation_anchor_snapshots" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"thread_id" uuid NOT NULL,
+	"document_id" uuid NOT NULL,
+	"from_revision_id" uuid,
+	"from_revision_number" integer,
+	"to_revision_id" uuid,
+	"to_revision_number" integer NOT NULL,
+	"previous_anchor" jsonb NOT NULL,
+	"next_anchor" jsonb,
+	"anchor_state" text NOT NULL,
+	"anchor_confidence" text NOT NULL,
+	"failure_reason" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'document_annotation_threads_company_id_companies_id_fk') THEN
+		ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_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 = 'document_annotation_threads_issue_id_issues_id_fk') THEN
+		ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_issue_id_issues_id_fk" FOREIGN KEY ("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 = 'document_annotation_threads_document_id_documents_id_fk') THEN
+		ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_document_id_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."documents"("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 = 'document_annotation_threads_original_revision_id_document_revisions_id_fk') THEN
+		ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_original_revision_id_document_revisions_id_fk" FOREIGN KEY ("original_revision_id") REFERENCES "public"."document_revisions"("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 = 'document_annotation_threads_current_revision_id_document_revisions_id_fk') THEN
+		ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_current_revision_id_document_revisions_id_fk" FOREIGN KEY ("current_revision_id") REFERENCES "public"."document_revisions"("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 = 'document_annotation_threads_created_by_agent_id_agents_id_fk') THEN
+		ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_created_by_agent_id_agents_id_fk" FOREIGN KEY ("created_by_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 = 'document_annotation_threads_resolved_by_agent_id_agents_id_fk') THEN
+		ALTER TABLE "document_annotation_threads" ADD CONSTRAINT "document_annotation_threads_resolved_by_agent_id_agents_id_fk" FOREIGN KEY ("resolved_by_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 = 'document_annotation_comments_company_id_companies_id_fk') THEN
+		ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_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 = 'document_annotation_comments_thread_id_document_annotation_threads_id_fk') THEN
+		ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_thread_id_document_annotation_threads_id_fk" FOREIGN KEY ("thread_id") REFERENCES "public"."document_annotation_threads"("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 = 'document_annotation_comments_issue_id_issues_id_fk') THEN
+		ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_issue_id_issues_id_fk" FOREIGN KEY ("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 = 'document_annotation_comments_document_id_documents_id_fk') THEN
+		ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_document_id_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."documents"("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 = 'document_annotation_comments_author_agent_id_agents_id_fk') THEN
+		ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_author_agent_id_agents_id_fk" FOREIGN KEY ("author_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 = 'document_annotation_comments_created_by_run_id_heartbeat_runs_id_fk') THEN
+		ALTER TABLE "document_annotation_comments" ADD CONSTRAINT "document_annotation_comments_created_by_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("created_by_run_id") REFERENCES "public"."heartbeat_runs"("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 = 'document_annotation_anchor_snapshots_company_id_companies_id_fk') THEN
+		ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_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 = 'document_annotation_anchor_snapshots_thread_id_document_annotation_threads_id_fk') THEN
+		ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_thread_id_document_annotation_threads_id_fk" FOREIGN KEY ("thread_id") REFERENCES "public"."document_annotation_threads"("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 = 'document_annotation_anchor_snapshots_document_id_documents_id_fk') THEN
+		ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_document_id_documents_id_fk" FOREIGN KEY ("document_id") REFERENCES "public"."documents"("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 = 'document_annotation_anchor_snapshots_from_revision_id_document_revisions_id_fk') THEN
+		ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_from_revision_id_document_revisions_id_fk" FOREIGN KEY ("from_revision_id") REFERENCES "public"."document_revisions"("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 = 'document_annotation_anchor_snapshots_to_revision_id_document_revisions_id_fk') THEN
+		ALTER TABLE "document_annotation_anchor_snapshots" ADD CONSTRAINT "document_annotation_anchor_snapshots_to_revision_id_document_revisions_id_fk" FOREIGN KEY ("to_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE set null ON UPDATE no action;
+	END IF;
+END $$;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_threads_company_document_status_idx" ON "document_annotation_threads" USING btree ("company_id","document_id","status");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_threads_company_issue_status_idx" ON "document_annotation_threads" USING btree ("company_id","issue_id","status");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_threads_company_current_revision_open_idx" ON "document_annotation_threads" USING btree ("company_id","document_id","current_revision_id","status");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_threads_company_anchor_state_idx" ON "document_annotation_threads" USING btree ("company_id","anchor_state");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_comments_company_thread_created_at_idx" ON "document_annotation_comments" USING btree ("company_id","thread_id","created_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_comments_company_issue_created_at_idx" ON "document_annotation_comments" USING btree ("company_id","issue_id","created_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_comments_company_document_created_at_idx" ON "document_annotation_comments" USING btree ("company_id","document_id","created_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_comments_body_search_idx" ON "document_annotation_comments" USING gin ("body" gin_trgm_ops);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_anchor_snapshots_company_thread_created_at_idx" ON "document_annotation_anchor_snapshots" USING btree ("company_id","thread_id","created_at");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "document_annotation_anchor_snapshots_company_document_revision_idx" ON "document_annotation_anchor_snapshots" USING btree ("company_id","document_id","to_revision_number");

packages/db/src/migrations/0092_mighty_puma.sql

@@ -0,0 +1,28 @@
+CREATE TABLE "issue_plan_decompositions" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"source_issue_id" uuid NOT NULL,
+	"accepted_plan_revision_id" uuid NOT NULL,
+	"accepted_interaction_id" uuid,
+	"status" text DEFAULT 'in_flight' NOT NULL,
+	"request_fingerprint" text NOT NULL,
+	"requested_child_count" integer DEFAULT 0 NOT NULL,
+	"requested_children" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"child_issue_ids" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"owner_agent_id" uuid,
+	"owner_user_id" text,
+	"owner_run_id" uuid,
+	"completed_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
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_source_issue_id_issues_id_fk" FOREIGN KEY ("source_issue_id") REFERENCES "public"."issues"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_accepted_plan_revision_id_document_revisions_id_fk" FOREIGN KEY ("accepted_plan_revision_id") REFERENCES "public"."document_revisions"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_accepted_interaction_id_issue_thread_interactions_id_fk" FOREIGN KEY ("accepted_interaction_id") REFERENCES "public"."issue_thread_interactions"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_owner_agent_id_agents_id_fk" FOREIGN KEY ("owner_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_plan_decompositions" ADD CONSTRAINT "issue_plan_decompositions_owner_run_id_heartbeat_runs_id_fk" FOREIGN KEY ("owner_run_id") REFERENCES "public"."heartbeat_runs"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "issue_plan_decompositions_company_source_status_idx" ON "issue_plan_decompositions" USING btree ("company_id","source_issue_id","status");--> statement-breakpoint
+CREATE INDEX "issue_plan_decompositions_active_owner_idx" ON "issue_plan_decompositions" USING btree ("company_id","owner_agent_id") WHERE "issue_plan_decompositions"."status" = 'in_flight';--> statement-breakpoint
+CREATE UNIQUE INDEX "issue_plan_decompositions_source_revision_uq" ON "issue_plan_decompositions" USING btree ("company_id","source_issue_id","accepted_plan_revision_id");

packages/db/src/migrations/0093_giant_green_goblin.sql

@@ -0,0 +1,6 @@
+ALTER TABLE "execution_workspaces" DROP CONSTRAINT "execution_workspaces_company_id_companies_id_fk";
+--> statement-breakpoint
+ALTER TABLE "workspace_operations" DROP CONSTRAINT "workspace_operations_company_id_companies_id_fk";
+--> statement-breakpoint
+ALTER TABLE "execution_workspaces" ADD CONSTRAINT "execution_workspaces_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "workspace_operations" ADD CONSTRAINT "workspace_operations_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;

packages/db/src/migrations/meta/_journal.json

@@ -638,6 +638,27 @@
       "when": 1779573019125,
       "tag": "0090_resource_memberships",
       "breakpoints": true
+    },
+    {
+      "idx": 91,
+      "version": "7",
+      "when": 1778810394522,
+      "tag": "0091_old_swarm",
+      "breakpoints": true
+    },
+    {
+      "idx": 92,
+      "version": "7",
+      "when": 1779999768200,
+      "tag": "0092_mighty_puma",
+      "breakpoints": true
+    },
+    {
+      "idx": 93,
+      "version": "7",
+      "when": 1780040470886,
+      "tag": "0093_giant_green_goblin",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/src/schema/document_annotation_anchor_snapshots.ts

@@ -0,0 +1,42 @@
+import type {
+  DocumentAnnotationAnchorConfidence,
+  DocumentAnnotationAnchorSnapshot,
+  DocumentAnnotationAnchorState,
+} from "@paperclipai/shared";
+import { index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { documentAnnotationThreads } from "./document_annotation_threads.js";
+import { documentRevisions } from "./document_revisions.js";
+import { documents } from "./documents.js";
+
+export const documentAnnotationAnchorSnapshots = pgTable(
+  "document_annotation_anchor_snapshots",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    threadId: uuid("thread_id").notNull().references(() => documentAnnotationThreads.id, { onDelete: "cascade" }),
+    documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+    fromRevisionId: uuid("from_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
+    fromRevisionNumber: integer("from_revision_number"),
+    toRevisionId: uuid("to_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
+    toRevisionNumber: integer("to_revision_number").notNull(),
+    previousAnchor: jsonb("previous_anchor").$type<DocumentAnnotationAnchorSnapshot>().notNull(),
+    nextAnchor: jsonb("next_anchor").$type<DocumentAnnotationAnchorSnapshot | null>(),
+    anchorState: text("anchor_state").$type<DocumentAnnotationAnchorState>().notNull(),
+    anchorConfidence: text("anchor_confidence").$type<DocumentAnnotationAnchorConfidence>().notNull(),
+    failureReason: text("failure_reason"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyThreadCreatedAtIdx: index("document_annotation_anchor_snapshots_company_thread_created_at_idx").on(
+      table.companyId,
+      table.threadId,
+      table.createdAt,
+    ),
+    companyDocumentRevisionIdx: index("document_annotation_anchor_snapshots_company_document_revision_idx").on(
+      table.companyId,
+      table.documentId,
+      table.toRevisionNumber,
+    ),
+  }),
+);

packages/db/src/schema/document_annotation_comments.ts

@@ -0,0 +1,44 @@
+import type { IssueCommentAuthorType } from "@paperclipai/shared";
+import { index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+import { documentAnnotationThreads } from "./document_annotation_threads.js";
+import { documents } from "./documents.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+import { issues } from "./issues.js";
+
+export const documentAnnotationComments = pgTable(
+  "document_annotation_comments",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    threadId: uuid("thread_id").notNull().references(() => documentAnnotationThreads.id, { onDelete: "cascade" }),
+    issueId: uuid("issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
+    documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+    body: text("body").notNull(),
+    authorType: text("author_type").$type<IssueCommentAuthorType>().notNull(),
+    authorAgentId: uuid("author_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    authorUserId: text("author_user_id"),
+    createdByRunId: uuid("created_by_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyThreadCreatedAtIdx: index("document_annotation_comments_company_thread_created_at_idx").on(
+      table.companyId,
+      table.threadId,
+      table.createdAt,
+    ),
+    companyIssueCreatedAtIdx: index("document_annotation_comments_company_issue_created_at_idx").on(
+      table.companyId,
+      table.issueId,
+      table.createdAt,
+    ),
+    companyDocumentCreatedAtIdx: index("document_annotation_comments_company_document_created_at_idx").on(
+      table.companyId,
+      table.documentId,
+      table.createdAt,
+    ),
+    bodySearchIdx: index("document_annotation_comments_body_search_idx").using("gin", table.body.op("gin_trgm_ops")),
+  }),
+);

packages/db/src/schema/document_annotation_threads.ts

@@ -0,0 +1,70 @@
+import type {
+  DocumentAnnotationAnchorConfidence,
+  DocumentAnnotationAnchorSelector,
+  DocumentAnnotationAnchorState,
+  DocumentAnnotationThreadStatus,
+} from "@paperclipai/shared";
+import { index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+import { documentRevisions } from "./document_revisions.js";
+import { documents } from "./documents.js";
+import { issues } from "./issues.js";
+
+export const documentAnnotationThreads = pgTable(
+  "document_annotation_threads",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    issueId: uuid("issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
+    documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
+    documentKey: text("document_key").notNull(),
+    status: text("status").$type<DocumentAnnotationThreadStatus>().notNull().default("open"),
+    anchorState: text("anchor_state").$type<DocumentAnnotationAnchorState>().notNull().default("active"),
+    originalRevisionId: uuid("original_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
+    originalRevisionNumber: integer("original_revision_number").notNull(),
+    currentRevisionId: uuid("current_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
+    currentRevisionNumber: integer("current_revision_number").notNull(),
+    selectedText: text("selected_text").notNull(),
+    prefixText: text("prefix_text").notNull().default(""),
+    suffixText: text("suffix_text").notNull().default(""),
+    normalizedStart: integer("normalized_start").notNull(),
+    normalizedEnd: integer("normalized_end").notNull(),
+    markdownStart: integer("markdown_start").notNull(),
+    markdownEnd: integer("markdown_end").notNull(),
+    anchorConfidence: text("anchor_confidence")
+      .$type<DocumentAnnotationAnchorConfidence>()
+      .notNull()
+      .default("exact"),
+    anchorSelector: jsonb("anchor_selector").$type<DocumentAnnotationAnchorSelector>().notNull(),
+    createdByAgentId: uuid("created_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    createdByUserId: text("created_by_user_id"),
+    resolvedByAgentId: uuid("resolved_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    resolvedByUserId: text("resolved_by_user_id"),
+    resolvedAt: timestamp("resolved_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyDocumentStatusIdx: index("document_annotation_threads_company_document_status_idx").on(
+      table.companyId,
+      table.documentId,
+      table.status,
+    ),
+    companyIssueStatusIdx: index("document_annotation_threads_company_issue_status_idx").on(
+      table.companyId,
+      table.issueId,
+      table.status,
+    ),
+    companyCurrentRevisionOpenIdx: index("document_annotation_threads_company_current_revision_open_idx").on(
+      table.companyId,
+      table.documentId,
+      table.currentRevisionId,
+      table.status,
+    ),
+    companyAnchorStateIdx: index("document_annotation_threads_company_anchor_state_idx").on(
+      table.companyId,
+      table.anchorState,
+    ),
+  }),
+);

packages/db/src/schema/execution_workspaces.ts

@@ -16,7 +16,7 @@ export const executionWorkspaces = pgTable(
   "execution_workspaces",
   {
     id: uuid("id").primaryKey().defaultRandom(),
-    companyId: uuid("company_id").notNull().references(() => companies.id),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
     projectId: uuid("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
     projectWorkspaceId: uuid("project_workspace_id").references(() => projectWorkspaces.id, { onDelete: "set null" }),
     sourceIssueId: uuid("source_issue_id").references((): AnyPgColumn => issues.id, { onDelete: "set null" }),

packages/db/src/schema/index.ts

@@ -32,6 +32,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 { issuePlanDecompositions } from "./issue_plan_decompositions.js";
 export { issueRecoveryActions } from "./issue_recovery_actions.js";
 export { issueReferenceMentions } from "./issue_reference_mentions.js";
 export { issueRelations } from "./issue_relations.js";
@@ -55,6 +56,9 @@ export { issueAttachments } from "./issue_attachments.js";
 export { documents } from "./documents.js";
 export { documentRevisions } from "./document_revisions.js";
 export { issueDocuments } from "./issue_documents.js";
+export { documentAnnotationThreads } from "./document_annotation_threads.js";
+export { documentAnnotationComments } from "./document_annotation_comments.js";
+export { documentAnnotationAnchorSnapshots } from "./document_annotation_anchor_snapshots.js";
 export { heartbeatRuns } from "./heartbeat_runs.js";
 export { heartbeatRunEvents } from "./heartbeat_run_events.js";
 export { heartbeatRunWatchdogDecisions } from "./heartbeat_run_watchdog_decisions.js";

packages/db/src/schema/issue_plan_decompositions.ts

@@ -0,0 +1,48 @@
+import { sql } from "drizzle-orm";
+import { pgTable, uuid, text, integer, timestamp, jsonb, index, uniqueIndex } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+import { documentRevisions } from "./document_revisions.js";
+import { heartbeatRuns } from "./heartbeat_runs.js";
+import { issueThreadInteractions } from "./issue_thread_interactions.js";
+import { issues } from "./issues.js";
+
+export const issuePlanDecompositions = pgTable(
+  "issue_plan_decompositions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    sourceIssueId: uuid("source_issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
+    acceptedPlanRevisionId: uuid("accepted_plan_revision_id")
+      .notNull()
+      .references(() => documentRevisions.id, { onDelete: "cascade" }),
+    acceptedInteractionId: uuid("accepted_interaction_id")
+      .references(() => issueThreadInteractions.id, { onDelete: "set null" }),
+    status: text("status").notNull().default("in_flight"),
+    requestFingerprint: text("request_fingerprint").notNull(),
+    requestedChildCount: integer("requested_child_count").notNull().default(0),
+    requestedChildren: jsonb("requested_children").$type<Record<string, unknown>[]>().notNull().default(sql`'[]'::jsonb`),
+    childIssueIds: jsonb("child_issue_ids").$type<string[]>().notNull().default(sql`'[]'::jsonb`),
+    ownerAgentId: uuid("owner_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    ownerUserId: text("owner_user_id"),
+    ownerRunId: uuid("owner_run_id").references(() => heartbeatRuns.id, { onDelete: "set null" }),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companySourceStatusIdx: index("issue_plan_decompositions_company_source_status_idx").on(
+      table.companyId,
+      table.sourceIssueId,
+      table.status,
+    ),
+    activeOwnerIdx: index("issue_plan_decompositions_active_owner_idx")
+      .on(table.companyId, table.ownerAgentId)
+      .where(sql`${table.status} = 'in_flight'`),
+    sourceRevisionUq: uniqueIndex("issue_plan_decompositions_source_revision_uq").on(
+      table.companyId,
+      table.sourceIssueId,
+      table.acceptedPlanRevisionId,
+    ),
+  }),
+);

packages/db/src/schema/workspace_operations.ts

@@ -17,7 +17,7 @@ export const workspaceOperations = pgTable(
   "workspace_operations",
   {
     id: uuid("id").primaryKey().defaultRandom(),
-    companyId: uuid("company_id").notNull().references(() => companies.id),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
     executionWorkspaceId: uuid("execution_workspace_id").references(() => executionWorkspaces.id, {
       onDelete: "set null",
     }),

packages/plugins/create-paperclip-plugin/README.md

@@ -34,7 +34,7 @@ Inside this repo, the generated package uses `@paperclipai/plugin-sdk` via `work
 Outside this repo, the scaffold snapshots `@paperclipai/plugin-sdk` from your local Paperclip checkout into a `.paperclip-sdk/` tarball and points the generated package at that local file by default. You can override the SDK source explicitly:
 
 ```bash
-node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
+node packages/plugins/create-paperclip-plugin/dist/bin.js @acme/my-plugin \
   --output /absolute/path/to/plugins \
   --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
 ```

packages/plugins/create-paperclip-plugin/package.json

@@ -13,7 +13,7 @@
   },
   "type": "module",
   "bin": {
-    "create-paperclip-plugin": "./dist/index.js"
+    "create-paperclip-plugin": "./dist/bin.js"
   },
   "exports": {
     ".": "./src/index.ts"
@@ -21,7 +21,7 @@
   "publishConfig": {
     "access": "public",
     "bin": {
-      "create-paperclip-plugin": "./dist/index.js"
+      "create-paperclip-plugin": "./dist/bin.js"
     },
     "exports": {
       ".": {
@@ -38,6 +38,7 @@
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
+    "test": "pnpm -w exec vitest run --root packages/plugins/create-paperclip-plugin --config vitest.config.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

packages/plugins/create-paperclip-plugin/src/bin.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { scaffoldPluginProject, type ScaffoldPluginOptions } from "./index.js";
+
+interface RunCliDeps {
+  cwd?: string;
+  stdout?: (message: string) => void;
+  stderr?: (message: string) => void;
+  exit?: (code: number) => never;
+}
+
+function parseArg(argv: string[], name: string): string | undefined {
+  const index = argv.indexOf(name);
+  if (index === -1) return undefined;
+  return argv[index + 1];
+}
+
+/** Convert `@scope/name` to an output directory basename (`name`). */
+function packageToDirName(pluginName: string): string {
+  return pluginName.replace(/^@[^/]+\//, "");
+}
+
+/** CLI wrapper for `scaffoldPluginProject`. */
+export function runCli(argv = process.argv, deps: RunCliDeps = {}): string | undefined {
+  const pluginName = argv[2];
+  const stderr = deps.stderr ?? console.error;
+  const stdout = deps.stdout ?? console.log;
+  const exit = deps.exit ?? process.exit;
+
+  if (!pluginName) {
+    stderr("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>] [--sdk-path <paperclip-sdk-path>]");
+    exit(1);
+  }
+
+  const template = (parseArg(argv, "--template") ?? "default") as ScaffoldPluginOptions["template"];
+  const outputRoot = parseArg(argv, "--output") ?? deps.cwd ?? process.cwd();
+  const targetDir = path.resolve(outputRoot, packageToDirName(pluginName));
+
+  const out = scaffoldPluginProject({
+    pluginName,
+    outputDir: targetDir,
+    template,
+    displayName: parseArg(argv, "--display-name"),
+    description: parseArg(argv, "--description"),
+    author: parseArg(argv, "--author"),
+    category: parseArg(argv, "--category") as ScaffoldPluginOptions["category"] | undefined,
+    sdkPath: parseArg(argv, "--sdk-path"),
+  });
+
+  stdout(`Created plugin scaffold at ${out}`);
+  return out;
+}
+
+function isMainModule(): boolean {
+  const entrypoint = process.argv[1];
+  return entrypoint ? import.meta.url === pathToFileURL(entrypoint).href : false;
+}
+
+if (isMainModule()) {
+  runCli();
+}

packages/plugins/create-paperclip-plugin/src/entrypoints.test.ts

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+const tempDirs: string[] = [];
+
+function makeTempDir(): string {
+  const dir = fs.mkdtempSync(path.join(process.cwd(), ".tmp-create-paperclip-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("create-paperclip-plugin entrypoints", () => {
+  it("keeps src/index.ts import-safe when process.argv points at another bundled CLI", async () => {
+    const originalArgv = process.argv;
+    const outputRoot = makeTempDir();
+
+    try {
+      process.argv = [process.execPath, path.resolve("cli/dist/index.js"), "demo-plugin", "--output", outputRoot];
+      const library = await import("./index.js");
+
+      expect(library.scaffoldPluginProject).toBeTypeOf("function");
+      expect(fs.existsSync(path.join(outputRoot, "demo-plugin"))).toBe(false);
+    } finally {
+      process.argv = originalArgv;
+    }
+  });
+
+  it("runs scaffolding from src/bin.ts", async () => {
+    const { runCli } = await import("./bin.js");
+    const outputRoot = makeTempDir();
+    const stdout: string[] = [];
+    const outputDir = path.join(outputRoot, "demo-plugin");
+
+    const result = runCli(
+      [
+        process.execPath,
+        "create-paperclip-plugin",
+        "demo-plugin",
+        "--output",
+        outputRoot,
+        "--sdk-path",
+        path.resolve("packages/plugins/sdk"),
+      ],
+      {
+        stdout: (message) => stdout.push(message),
+        stderr: (message) => {
+          throw new Error(message);
+        },
+        exit: (code) => {
+          throw new Error(`unexpected exit ${code}`);
+        },
+      },
+    );
+
+    expect(result).toBe(outputDir);
+    expect(stdout).toEqual([`Created plugin scaffold at ${outputDir}`]);
+    expect(JSON.parse(fs.readFileSync(path.join(outputDir, "package.json"), "utf8"))).toMatchObject({
+      name: "demo-plugin",
+      paperclipPlugin: {
+        manifest: "./dist/manifest.js",
+        worker: "./dist/worker.js",
+        ui: "./dist/ui/",
+      },
+    });
+  });
+});

packages/plugins/create-paperclip-plugin/src/index.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
@@ -699,41 +698,3 @@ paperclipai plugin install ${shellQuote(toPosixPath(outputDir))}
 
   return outputDir;
 }
-
-function parseArg(name: string): string | undefined {
-  const index = process.argv.indexOf(name);
-  if (index === -1) return undefined;
-  return process.argv[index + 1];
-}
-
-/** CLI wrapper for `scaffoldPluginProject`. */
-function runCli() {
-  const pluginName = process.argv[2];
-  if (!pluginName) {
-    // eslint-disable-next-line no-console
-    console.error("Usage: create-paperclip-plugin <name> [--template default|connector|workspace] [--output <dir>] [--sdk-path <paperclip-sdk-path>]");
-    process.exit(1);
-  }
-
-  const template = (parseArg("--template") ?? "default") as PluginTemplate;
-  const outputRoot = parseArg("--output") ?? process.cwd();
-  const targetDir = path.resolve(outputRoot, packageToDirName(pluginName));
-
-  const out = scaffoldPluginProject({
-    pluginName,
-    outputDir: targetDir,
-    template,
-    displayName: parseArg("--display-name"),
-    description: parseArg("--description"),
-    author: parseArg("--author"),
-    category: parseArg("--category") as ScaffoldPluginOptions["category"] | undefined,
-    sdkPath: parseArg("--sdk-path"),
-  });
-
-  // eslint-disable-next-line no-console
-  console.log(`Created plugin scaffold at ${out}`);
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runCli();
-}

packages/plugins/create-paperclip-plugin/tsconfig.json

@@ -5,5 +5,6 @@
     "rootDir": "src",
     "types": ["node"]
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
 }

packages/plugins/create-paperclip-plugin/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});

packages/plugins/sandbox-providers/exe-dev/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/plugin-exe-dev",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "exe.dev sandbox provider plugin for Paperclip environments",
   "license": "MIT",
   "homepage": "https://github.com/paperclipai/paperclip",

packages/plugins/sandbox-providers/exe-dev/src/manifest.ts

@@ -1,7 +1,7 @@
 import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
 
 const PLUGIN_ID = "paperclip.exe-dev-sandbox-provider";
-const PLUGIN_VERSION = "0.1.0";
+const PLUGIN_VERSION = "0.1.1";
 
 const manifest: PaperclipPluginManifestV1 = {
   id: PLUGIN_ID,
@@ -26,106 +26,150 @@ const manifest: PaperclipPluginManifestV1 = {
       configSchema: {
         type: "object",
         properties: {
+          // ---- Essentials (always visible, in this order) ----
           apiKey: {
             type: "string",
             format: "secret-ref",
             description:
-              "Environment-specific exe.dev API token. Needs `/exec` permission for at least `new`, `ls`, and `rm`. Paste a token or an existing Paperclip secret reference; saved environments store pasted values as company secrets. Falls back to EXE_API_KEY if omitted.",
-          },
-          apiUrl: {
-            type: "string",
-            description:
-              "Optional exe.dev HTTPS API base URL or /exec endpoint. Defaults to https://exe.dev/exec.",
-          },
-          namePrefix: {
-            type: "string",
-            description: "Optional prefix used when generating VM names.",
-            default: "paperclip",
-          },
-          image: {
-            type: "string",
-            description: "Optional container image to use when creating the VM.",
-          },
-          command: {
-            type: "string",
-            description: "Optional container command passed to `exe.dev new --command`.",
-          },
-          cpu: {
-            type: "number",
-            description: "Optional CPU count passed to `exe.dev new --cpu`.",
-          },
-          memory: {
-            type: "string",
-            description: "Optional memory size such as `4GB`.",
-          },
-          disk: {
-            type: "string",
-            description: "Optional disk size such as `20GB`.",
-          },
-          comment: {
-            type: "string",
-            description: "Optional short note attached to created VMs.",
-          },
-          env: {
-            type: "object",
-            description: "Optional environment variables applied at VM creation time.",
-            additionalProperties: { type: "string" },
-          },
-          integrations: {
-            type: "array",
-            description: "Optional exe.dev integrations to attach during VM creation.",
-            items: { type: "string" },
-          },
-          tags: {
-            type: "array",
-            description: "Optional tags to apply during VM creation.",
-            items: { type: "string" },
-          },
-          setupScript: {
-            type: "string",
-            description: "Optional first-boot setup script passed to `exe.dev new --setup-script`.",
-          },
-          prompt: {
-            type: "string",
-            description: "Optional Shelley prompt passed to `exe.dev new --prompt`.",
-          },
-          timeoutMs: {
-            type: "number",
-            description: "Timeout for VM lifecycle and SSH operations in milliseconds.",
-            default: 300000,
-          },
-          reuseLease: {
-            type: "boolean",
-            description:
-              "Whether to keep the VM alive between runs instead of deleting it on release.",
-            default: false,
-          },
-          sshUser: {
-            type: "string",
-            description: "Optional SSH username for direct VM access.",
+              "Paste your exe.dev API token, or pick a saved Paperclip secret. Create one at exe.dev → Settings → API tokens with `/exec` scope (`new`, `ls`, `rm`).",
           },
           sshPrivateKey: {
             type: "string",
             format: "secret-ref",
-            maxLength: 4096,
+            maxLength: 8192,
             description:
-              "Optional exe.dev-registered SSH private key. Paste the private key or an existing Paperclip secret reference; saved environments store pasted values as company secrets. If omitted, Paperclip falls back to sshIdentityFile, then the host's default SSH agent/keychain.",
+              "Paste the SSH private key you registered with exe.dev, or pick a saved secret. Leave blank to fall back to an on-host key (see Advanced → SSH access).",
+          },
+          // ---- Advanced: SSH access ----
+          sshUser: {
+            type: "string",
+            description:
+              "Login user on the VM. Leave blank to use the image default, usually `root`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "SSH access",
           },
           sshIdentityFile: {
             type: "string",
             description:
-              "Optional absolute path to the SSH private key the Paperclip host should use for VM access when sshPrivateKey is omitted. Leave both blank to rely on the host's default SSH agent/keychain.",
+              "Absolute path to a private key on the Paperclip host. Used only when SSH Private Key is empty.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "SSH access",
           },
           sshPort: {
             type: "number",
             description: "SSH port for direct VM access.",
             default: 22,
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "SSH access",
           },
           strictHostKeyChecking: {
             type: "string",
             description:
               "Host key policy passed to ssh via StrictHostKeyChecking. Typical values are `accept-new`, `yes`, or `no`.",
             default: "accept-new",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "SSH access",
+          },
+          // ---- Advanced: VM resources ----
+          image: {
+            type: "string",
+            description: "Optional container image to use when creating the VM.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          cpu: {
+            type: "number",
+            description: "Optional CPU count passed to `exe.dev new --cpu`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          memory: {
+            type: "string",
+            description: "Optional memory size such as `4GB`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          disk: {
+            type: "string",
+            description: "Optional disk size such as `20GB`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM resources",
+          },
+          // ---- Advanced: VM creation ----
+          command: {
+            type: "string",
+            description: "Optional container command passed to `exe.dev new --command`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          env: {
+            type: "object",
+            description: "Optional environment variables applied at VM creation time.",
+            additionalProperties: { type: "string" },
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          integrations: {
+            type: "array",
+            description: "Optional exe.dev integrations to attach during VM creation.",
+            items: { type: "string" },
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          tags: {
+            type: "array",
+            description: "Optional tags to apply during VM creation.",
+            items: { type: "string" },
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          setupScript: {
+            type: "string",
+            description: "Optional first-boot setup script passed to `exe.dev new --setup-script`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          prompt: {
+            type: "string",
+            description: "Optional Shelley prompt passed to `exe.dev new --prompt`.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          comment: {
+            type: "string",
+            description: "Optional short note attached to created VMs.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          namePrefix: {
+            type: "string",
+            description: "Optional prefix used when generating VM names.",
+            default: "paperclip",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "VM creation",
+          },
+          // ---- Advanced: API + runtime ----
+          apiUrl: {
+            type: "string",
+            description:
+              "Optional exe.dev HTTPS API base URL or /exec endpoint. Defaults to https://exe.dev/exec.",
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "API + runtime",
+          },
+          timeoutMs: {
+            type: "number",
+            description: "Timeout for VM lifecycle and SSH operations in milliseconds.",
+            default: 300000,
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "API + runtime",
+          },
+          reuseLease: {
+            type: "boolean",
+            description:
+              "Whether to keep the VM alive between runs instead of deleting it on release.",
+            default: false,
+            "x-paperclip-advanced": true,
+            "x-paperclip-group": "API + runtime",
           },
         },
       },

packages/plugins/sandbox-providers/exe-dev/src/plugin.test.ts

@@ -14,7 +14,7 @@ vi.mock("node:child_process", async () => {
   };
 });
 
-import plugin from "./plugin.js";
+import plugin, { validateSshPrivateKey } from "./plugin.js";
 
 class MockChildProcess extends EventEmitter {
   stdout = new EventEmitter();
@@ -165,6 +165,117 @@ describe("exe.dev sandbox provider plugin", () => {
     });
   });
 
+  describe("sshPrivateKey validation", () => {
+    const VALID_OPENSSH = [
+      "-----BEGIN OPENSSH PRIVATE KEY-----",
+      "b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gt",
+      "ZWQyNTUxOQAAACBPzMxQp4Y6XCfDV2t6oWmqHkKx0K7C7w7q9F6gQ3jPbgAAAJjJ8jjE",
+      "yfI4xAAAAAtzc2gtZWQyNTUxOQAAACBPzMxQp4Y6XCfDV2t6oWmqHkKx0K7C7w7q9F6g",
+      "Q3jPbgAAAEDqLhB4kV1tw8m4gE9oNCkF2cJv0YnHQ8E5sHU3xKnD5k/MzFCnhjpcJ8NX",
+      "a3qhaaoeQrHQrsLvDur0XqBDeM9uAAAAFXVzZXJAaG9zdAECAwQ=",
+      "-----END OPENSSH PRIVATE KEY-----",
+    ].join("\n");
+    const VALID_RSA_PEM = [
+      "-----BEGIN RSA PRIVATE KEY-----",
+      "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6Ppy1tPf9Cnzj4p4WGeKLs1Pt8Qu",
+      "KUpRKfFLfRYC9AIKjbJTWit+CqvjWYzvQwECAwEAAQJAIJLixBy2qpFoS4DSmoEm",
+      "o3qGy0t6z5tZbcgvflRslzu1HxXLpwYqQq2gMNw9UQAoHs3rDl+EzBjF6trBV5wF",
+      "wQIhANwiwDR7TVlIRk5kbgPMd2dDgY8mAU1cQ8KbWvjVMmKxAiEAxYTUyVjwhfQy",
+      "VJoR7T0n4XdR1n+W8Eth7AEPxnHfaQECIB5cNuqB9F1qC2pSyf6e+UAyl9rmKQXp",
+      "-----END RSA PRIVATE KEY-----",
+    ].join("\n");
+
+    it("accepts a valid OpenSSH PEM block", () => {
+      expect(validateSshPrivateKey(VALID_OPENSSH)).toBeNull();
+    });
+
+    it("accepts a valid PKCS#1 RSA PEM block", () => {
+      expect(validateSshPrivateKey(VALID_RSA_PEM)).toBeNull();
+    });
+
+    it("accepts UUID-like secret reference values from the save-time schema stage", async () => {
+      process.env.EXE_API_KEY = "host-key";
+
+      const result = await plugin.definition.onEnvironmentValidateConfig?.({
+        driverKey: "exe-dev",
+        config: {
+          apiKey: "api-key",
+          sshPrivateKey: "11111111-1111-4111-8111-111111111111",
+        },
+      });
+
+      expect(result).toMatchObject({
+        ok: true,
+        normalizedConfig: {
+          sshPrivateKey: "11111111-1111-4111-8111-111111111111",
+        },
+      });
+      expect(result?.errors ?? []).toEqual([]);
+    });
+
+    it("treats empty / whitespace-only input as valid (falls back to on-host key)", () => {
+      expect(validateSshPrivateKey("")).toBeNull();
+      expect(validateSshPrivateKey("   \n\n  ")).toBeNull();
+    });
+
+    it("rejects a pasted public key", () => {
+      expect(
+        validateSshPrivateKey("ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE+gT9 user@host"),
+      ).toMatch(/looks like a PUBLIC key/);
+    });
+
+    it("rejects a PuTTY PPK file paste", () => {
+      const ppk = [
+        "PuTTY-User-Key-File-3: ssh-ed25519",
+        "Encryption: none",
+        "Comment: imported-openssh-key",
+        "Public-Lines: 2",
+        "AAAAC3NzaC1lZDI1NTE5AAAAIE+gT9zMxQp4Y6XCfDV2t6oWmqHkKx0K7C7w7q9F6g",
+        "Q3jP",
+      ].join("\n");
+      expect(validateSshPrivateKey(ppk)).toMatch(/PuTTY \.ppk/);
+    });
+
+    it("rejects a missing END marker (truncated paste)", () => {
+      const truncated = VALID_OPENSSH.split("\n").slice(0, -1).join("\n");
+      expect(validateSshPrivateKey(truncated)).toMatch(/missing its '-----END/);
+    });
+
+    it("rejects a body with non-base64 characters", () => {
+      const garbled = [
+        "-----BEGIN OPENSSH PRIVATE KEY-----",
+        "this is not base64!!",
+        "-----END OPENSSH PRIVATE KEY-----",
+      ].join("\n");
+      expect(validateSshPrivateKey(garbled)).toMatch(/non-base64/);
+    });
+
+    it("rejects a header/footer label mismatch", () => {
+      const mismatched = [
+        "-----BEGIN OPENSSH PRIVATE KEY-----",
+        "Zm9vYmFy",
+        "-----END RSA PRIVATE KEY-----",
+      ].join("\n");
+      expect(validateSshPrivateKey(mismatched)).toMatch(/header\/footer mismatch/);
+    });
+
+    it("returns the sshPrivateKey error from onEnvironmentValidateConfig on save", async () => {
+      process.env.EXE_API_KEY = "host-key";
+
+      const result = await plugin.definition.onEnvironmentValidateConfig?.({
+        driverKey: "exe-dev",
+        config: {
+          sshPrivateKey: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE+gT9 user@host",
+        },
+      });
+
+      expect(result?.ok).toBe(false);
+      expect(result?.errors ?? []).toEqual(
+        expect.arrayContaining([expect.stringMatching(/sshPrivateKey looks like a PUBLIC key/)]),
+      );
+    });
+  });
+
   it("acquires a lease by creating a VM and preparing the SSH workspace", async () => {
     fetchMock.mockResolvedValueOnce(
       new Response(JSON.stringify({
@@ -346,6 +457,38 @@ describe("exe.dev sandbox provider plugin", () => {
     expect(String(fetchMock.mock.calls[1]?.[1]?.body ?? "")).toBe("rm --json 'paperclip-env-run'");
   });
 
+  it("surfaces invalid SSH key-format guidance during lease acquisition", async () => {
+    fetchMock.mockResolvedValueOnce(
+      new Response(JSON.stringify({
+        vm_name: "paperclip-env-run",
+        ssh_dest: "paperclip-env-run.exe.xyz",
+        https_url: "https://paperclip-env-run.exe.xyz",
+        status: "running",
+      }), { status: 200 }),
+    );
+    fetchMock.mockResolvedValueOnce(new Response("{}", { status: 200 }));
+    queueSpawnResult({
+      code: 255,
+      stderr: 'Load key "/tmp/paperclip-exe-dev-ssh-abc/id_ed25519": invalid format\n',
+    });
+
+    await expect(plugin.definition.onEnvironmentAcquireLease?.({
+      driverKey: "exe-dev",
+      companyId: "company-1",
+      environmentId: "env-1",
+      runId: "run-1",
+      config: {
+        apiKey: "api-key",
+        sshPrivateKey: "not-actually-a-key",
+        timeoutMs: 300000,
+      },
+    })).rejects.toThrow(
+      "the configured SSH private key isn't an OpenSSH-format private key",
+    );
+
+    expect(String(fetchMock.mock.calls[1]?.[1]?.body ?? "")).toBe("rm --json 'paperclip-env-run'");
+  });
+
   it("redacts sensitive lifecycle flags in API errors", async () => {
     fetchMock.mockResolvedValueOnce(new Response("upstream boom", { status: 500 }));
 

packages/plugins/sandbox-providers/exe-dev/src/plugin.ts

@@ -68,6 +68,8 @@ const SSH_SIGKILL_GRACE_MS = 250;
 const MAX_VM_RECORD_DEPTH = 4;
 const EXE_DEV_SSH_ONBOARDING_MARKER = "Please complete registration by running: ssh exe.dev";
 const EXE_DEV_SSH_EMAIL_PROMPT = "Please enter your email address:";
+const EXE_DEV_SSH_INVALID_KEY_FORMAT = /Load key [^\n]*invalid format/i;
+const UUID_SECRET_REF_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 // exe.dev's `--setup-script` runs at VM init as the unprivileged `exedev` user, which
 // has passwordless sudo. The Paperclip sandbox callback bridge is a Node script, so
@@ -139,6 +141,74 @@ function isValidUrl(value: string): boolean {
   }
 }
 
+function isSecretRef(value: string): boolean {
+  return UUID_SECRET_REF_RE.test(value);
+}
+
+// Catch the SSH-key paste failure modes we've seen in the wild (wrong file,
+// PPK export, truncated paste) before the user pays the cost of provisioning a
+// VM and getting a cryptic SSH error. Inline parse — no `ssh-keygen` dependency
+// — so this also works on hosts where openssh-client isn't installed.
+export function validateSshPrivateKey(rawKey: string): string | null {
+  const trimmed = rawKey.trim();
+  if (!trimmed) return null;
+
+  if (/^PuTTY-User-Key-File-\d/m.test(trimmed)) {
+    return "sshPrivateKey looks like a PuTTY .ppk file. Convert it to OpenSSH format (PuTTYgen → Conversions → Export OpenSSH key) and paste the resulting PEM.";
+  }
+
+  if (
+    /^(?:ssh-(?:rsa|dss|ed25519)|ecdsa-sha2-[a-z0-9-]+|sk-(?:ssh-ed25519|ecdsa-sha2-[a-z0-9-]+)@openssh\.com)\s+\S/.test(
+      trimmed,
+    )
+  ) {
+    return "sshPrivateKey looks like a PUBLIC key. Paste the matching private key (the file without the .pub extension).";
+  }
+
+  const headerMatch = trimmed.match(/^-----BEGIN ([A-Z0-9 ]*)PRIVATE KEY-----/m);
+  if (!headerMatch) {
+    return "sshPrivateKey must be a PEM-encoded private key starting with a line like '-----BEGIN OPENSSH PRIVATE KEY-----'.";
+  }
+
+  const footerMatch = trimmed.match(/^-----END ([A-Z0-9 ]*)PRIVATE KEY-----\s*$/m);
+  if (!footerMatch) {
+    return "sshPrivateKey is missing its '-----END … PRIVATE KEY-----' footer. Make sure you copied the whole file, including the final line.";
+  }
+
+  const headerLabel = headerMatch[1].trim();
+  const footerLabel = footerMatch[1].trim();
+  if (headerLabel !== footerLabel) {
+    return `sshPrivateKey header/footer mismatch (BEGIN ${headerLabel || "(none)"} vs END ${footerLabel || "(none)"}). The file is likely truncated or two keys are concatenated.`;
+  }
+
+  const headerLineEnd = trimmed.indexOf("\n", headerMatch.index ?? 0);
+  const footerStart = trimmed.lastIndexOf(footerMatch[0]);
+  if (headerLineEnd < 0 || footerStart <= headerLineEnd) {
+    return "sshPrivateKey appears to be empty between its BEGIN and END markers.";
+  }
+
+  const bodyLines = trimmed
+    .slice(headerLineEnd + 1, footerStart)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  if (bodyLines.length === 0) {
+    return "sshPrivateKey appears to be empty between its BEGIN and END markers.";
+  }
+
+  // PEM bodies are base64 lines, optionally preceded by `Header: value` lines
+  // on encrypted PKCS#1 keys (`Proc-Type:`, `DEK-Info:`).
+  const base64Line = /^[A-Za-z0-9+/=]+$/;
+  const pemHeaderLine = /^[A-Za-z][A-Za-z0-9-]*:\s.+$/;
+  for (const line of bodyLines) {
+    if (!base64Line.test(line) && !pemHeaderLine.test(line)) {
+      return "sshPrivateKey body contains non-base64 characters. The key may have been corrupted by line-wrapping or copy-paste.";
+    }
+  }
+
+  return null;
+}
+
 function normalizeApiUrl(value: string | null): string {
   if (!value) return DEFAULT_API_URL;
   const trimmed = value.trim();
@@ -498,6 +568,13 @@ function formatSshFailure(
     ].join(" ");
   }
 
+  if (EXE_DEV_SSH_INVALID_KEY_FORMAT.test(combinedOutput)) {
+    return [
+      `Failed to ${action} exe.dev VM ${vmName}: the configured SSH private key isn't an OpenSSH-format private key.`,
+      "Confirm the secret starts with `-----BEGIN … PRIVATE KEY-----` and isn't the `.pub` file or a PuTTY `.ppk` export.",
+    ].join(" ");
+  }
+
   return `Failed to ${action} exe.dev VM ${vmName}: ${result.stderr.trim() || result.stdout.trim() || "unknown error"}`;
 }
 
@@ -686,6 +763,10 @@ const plugin = definePlugin({
     ) {
       errors.push("strictHostKeyChecking cannot be empty.");
     }
+    if (config.sshPrivateKey && !isSecretRef(config.sshPrivateKey)) {
+      const sshKeyError = validateSshPrivateKey(config.sshPrivateKey);
+      if (sshKeyError) errors.push(sshKeyError);
+    }
 
     warnings.push(
       "The Paperclip host must have SSH access to the created exe.dev VM, and its SSH key must be registered with exe.dev. The API token only covers provisioning.",

packages/shared/src/constants.ts

@@ -281,6 +281,22 @@ export function isSystemIssueDocumentKey(key: string): key is SystemIssueDocumen
 export const ISSUE_REFERENCE_SOURCE_KINDS = ["title", "description", "comment", "document"] as const;
 export type IssueReferenceSourceKind = (typeof ISSUE_REFERENCE_SOURCE_KINDS)[number];
 
+export const DOCUMENT_ANNOTATION_THREAD_STATUSES = ["open", "resolved"] as const;
+export type DocumentAnnotationThreadStatus = (typeof DOCUMENT_ANNOTATION_THREAD_STATUSES)[number];
+
+export const DOCUMENT_ANNOTATION_ANCHOR_STATES = ["active", "stale", "orphaned"] as const;
+export type DocumentAnnotationAnchorState = (typeof DOCUMENT_ANNOTATION_ANCHOR_STATES)[number];
+
+export const DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES = [
+  "exact",
+  "duplicate",
+  "fuzzy",
+  "ambiguous",
+  "missing",
+] as const;
+export type DocumentAnnotationAnchorConfidence =
+  (typeof DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES)[number];
+
 export const ISSUE_EXECUTION_POLICY_MODES = ["normal", "auto"] as const;
 export type IssueExecutionPolicyMode = (typeof ISSUE_EXECUTION_POLICY_MODES)[number];
 

packages/shared/src/document-anchors.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import {
+  createDocumentAnchorSelector,
+  projectMarkdownToText,
+  remapDocumentAnchor,
+  resolveProjectionRange,
+  verifyDocumentAnchorSelector,
+} from "./document-anchors.js";
+
+function selectorFor(markdown: string, quote: string) {
+  const projection = projectMarkdownToText(markdown);
+  const start = projection.text.indexOf(quote);
+  expect(start).toBeGreaterThanOrEqual(0);
+  const range = resolveProjectionRange(projection, start, start + quote.length);
+  expect(range).not.toBeNull();
+  return createDocumentAnchorSelector(projection, range!);
+}
+
+describe("document text projection", () => {
+  it("projects markdown into normalized rendered text with source ranges", () => {
+    const markdown = [
+      "# Heading",
+      "",
+      "- Ship **bold** [link text](https://example.com) and `code span`.",
+      "| Name | Value |",
+      "| --- | --- |",
+      "| Alpha | Beta |",
+    ].join("\n");
+
+    const projection = projectMarkdownToText(markdown);
+
+    expect(projection.text).toContain("Heading");
+    expect(projection.text).toContain("Ship bold link text and code span.");
+    expect(projection.text).toContain("Name Value");
+    expect(projection.text).toContain("Alpha Beta");
+    expect(projection.text).not.toContain("https://example.com");
+    expect(projection.positions).toHaveLength(projection.text.length);
+
+    const linkStart = projection.text.indexOf("link text");
+    const range = resolveProjectionRange(projection, linkStart, linkStart + "link text".length);
+    expect(range?.markdownStart).toBe(markdown.indexOf("link text"));
+    expect(range?.markdownEnd).toBe(markdown.indexOf("link text") + "link text".length);
+  });
+
+  it("normalizes whitespace while retaining markdown offsets", () => {
+    const markdown = "First   line\n\nSecond\t\tline";
+    const projection = projectMarkdownToText(markdown);
+
+    expect(projection.text).toBe("First line Second line");
+    const range = resolveProjectionRange(projection, projection.text.indexOf("Second"), projection.text.length);
+    expect(range?.markdownStart).toBe(markdown.indexOf("Second"));
+    expect(range?.markdownEnd).toBe(markdown.length);
+  });
+
+  it("preserves non-link punctuation", () => {
+    const markdown = "Keep (parenthetical) [plain brackets] visible.";
+    const projection = projectMarkdownToText(markdown);
+
+    expect(projection.text).toBe("Keep (parenthetical) [plain brackets] visible.");
+  });
+});
+
+describe("document anchor verification and remapping", () => {
+  it("verifies a selector against its base revision", () => {
+    const markdown = "Intro text with **selected text** inside.";
+    const selector = selectorFor(markdown, "selected text");
+
+    const result = verifyDocumentAnchorSelector({ markdown, selector });
+
+    expect(result.ok).toBe(true);
+    expect(result.anchor?.selectedText).toBe("selected text");
+    expect(result.anchor?.markdownStart).toBe(markdown.indexOf("selected text"));
+  });
+
+  it("remaps exact anchors after surrounding text moves", () => {
+    const selector = selectorFor("Alpha paragraph.\n\nTarget sentence here.\n\nOmega paragraph.", "Target sentence here.");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: selector.quote.prefix,
+      suffixText: selector.quote.suffix,
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const result = remapDocumentAnchor({
+      previousAnchor,
+      nextMarkdown: "Omega paragraph.\n\nAlpha paragraph.\n\nTarget sentence here.",
+    });
+
+    expect(result.anchorState).toBe("active");
+    expect(result.confidence).toBe("exact");
+    expect(result.anchor?.selectedText).toBe("Target sentence here.");
+  });
+
+  it("uses context and proximity to disambiguate duplicate quotes", () => {
+    const selector = selectorFor("One apple near the start.\n\nTwo apple near the end.", "apple");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: selector.quote.prefix,
+      suffixText: selector.quote.suffix,
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const result = remapDocumentAnchor({
+      previousAnchor,
+      nextMarkdown: "Zero apple elsewhere.\n\nOne apple near the start.\n\nTwo apple near the end.",
+    });
+
+    expect(result.anchorState).toBe("active");
+    expect(result.confidence).toBe("duplicate");
+    expect(result.anchor?.prefixText).toContain("One");
+  });
+
+  it("marks duplicate anchors ambiguous when context cannot distinguish them", () => {
+    const selector = selectorFor("apple apple", "apple");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: "",
+      suffixText: "",
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const result = remapDocumentAnchor({ previousAnchor, nextMarkdown: "apple apple" });
+
+    expect(result.anchorState).toBe("stale");
+    expect(result.confidence).toBe("ambiguous");
+  });
+
+  it("keeps edited anchors as stale fuzzy matches", () => {
+    const selector = selectorFor("We rely on an important launch assumption for scope.", "important launch assumption");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: selector.quote.prefix,
+      suffixText: selector.quote.suffix,
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const result = remapDocumentAnchor({
+      previousAnchor,
+      nextMarkdown: "We rely on an important product launch assumption for scope.",
+    });
+
+    expect(result.anchorState).toBe("stale");
+    expect(result.confidence).toBe("fuzzy");
+    expect(result.anchor?.selectedText).toBe("important product launch assumption");
+  });
+
+  it("marks deleted anchors orphaned and allows future remapping from the latest known anchor", () => {
+    const selector = selectorFor("Keep this reviewed phrase in mind.", "reviewed phrase");
+    const previousAnchor = {
+      selectedText: selector.quote.exact,
+      prefixText: selector.quote.prefix,
+      suffixText: selector.quote.suffix,
+      normalizedStart: selector.position.normalizedStart,
+      normalizedEnd: selector.position.normalizedEnd,
+      markdownStart: selector.position.markdownStart,
+      markdownEnd: selector.position.markdownEnd,
+    };
+
+    const missing = remapDocumentAnchor({ previousAnchor, nextMarkdown: "The target disappeared." });
+    const recovered = remapDocumentAnchor({
+      previousAnchor,
+      nextMarkdown: "The target came back: reviewed phrase.",
+    });
+
+    expect(missing.anchorState).toBe("orphaned");
+    expect(missing.confidence).toBe("missing");
+    expect(missing.anchor).toBeNull();
+    expect(recovered.anchorState).toBe("active");
+    expect(recovered.anchor?.selectedText).toBe("reviewed phrase");
+  });
+});

packages/shared/src/document-anchors.ts

@@ -0,0 +1,464 @@
+import type {
+  DocumentAnnotationAnchorConfidence,
+  DocumentAnnotationAnchorState,
+} from "./constants.js";
+import type {
+  DocumentAnnotationAnchorSelector,
+  DocumentAnnotationAnchorSnapshot,
+  DocumentTextPosition,
+  DocumentTextProjection,
+  DocumentTextRange,
+} from "./types/document-annotation.js";
+
+export interface CreateDocumentAnchorSelectorOptions {
+  contextLength?: number;
+}
+
+export interface VerifyDocumentAnchorSelectorInput {
+  markdown: string;
+  selector: DocumentAnnotationAnchorSelector;
+  contextLength?: number;
+}
+
+export interface VerifyDocumentAnchorSelectorResult {
+  ok: boolean;
+  anchor: DocumentAnnotationAnchorSnapshot | null;
+  projection: DocumentTextProjection;
+  reason: "verified" | "quote_mismatch" | "position_mismatch" | "invalid_range";
+}
+
+export interface RemapDocumentAnchorInput {
+  previousAnchor: DocumentAnnotationAnchorSnapshot;
+  nextMarkdown: string;
+  contextLength?: number;
+}
+
+export interface RemapDocumentAnchorResult {
+  anchorState: DocumentAnnotationAnchorState;
+  confidence: DocumentAnnotationAnchorConfidence;
+  anchor: DocumentAnnotationAnchorSnapshot | null;
+  projection: DocumentTextProjection;
+  reason: "exact" | "duplicate" | "fuzzy" | "ambiguous" | "missing";
+}
+
+interface Candidate {
+  start: number;
+  end: number;
+  score: number;
+  reason: RemapDocumentAnchorResult["reason"];
+}
+
+const DEFAULT_CONTEXT_LENGTH = 48;
+
+export function normalizeAnchorText(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+export function projectMarkdownToText(markdown: string): DocumentTextProjection {
+  const builder = new ProjectionBuilder(markdown);
+  const lines = markdown.match(/[^\n]*(?:\n|$)/g) ?? [markdown];
+  let offset = 0;
+  let inFence = false;
+
+  for (const rawLine of lines) {
+    if (rawLine === "") continue;
+    const hasNewline = rawLine.endsWith("\n");
+    const line = hasNewline ? rawLine.slice(0, -1) : rawLine;
+    const fenceMatch = line.match(/^\s*(```+|~~~+)/);
+
+    if (fenceMatch) {
+      inFence = !inFence;
+      offset += rawLine.length;
+      builder.addSeparator(offset - (hasNewline ? 1 : 0));
+      continue;
+    }
+
+    if (inFence) {
+      builder.addText(line, offset);
+      builder.addSeparator(offset + line.length);
+      offset += rawLine.length;
+      continue;
+    }
+
+    const { text, sourceOffset } = stripBlockSyntax(line, offset);
+    addInlineMarkdownText(builder, text, sourceOffset);
+    builder.addSeparator(offset + line.length);
+    offset += rawLine.length;
+  }
+
+  return builder.toProjection();
+}
+
+export function resolveProjectionRange(
+  projection: DocumentTextProjection,
+  normalizedStart: number,
+  normalizedEnd: number,
+): DocumentTextRange | null {
+  if (
+    normalizedStart < 0
+    || normalizedEnd <= normalizedStart
+    || normalizedEnd > projection.text.length
+    || normalizedStart >= projection.positions.length
+    || normalizedEnd - 1 >= projection.positions.length
+  ) {
+    return null;
+  }
+
+  return {
+    text: projection.text.slice(normalizedStart, normalizedEnd),
+    normalizedStart,
+    normalizedEnd,
+    markdownStart: projection.positions[normalizedStart]?.sourceStart ?? 0,
+    markdownEnd: projection.positions[normalizedEnd - 1]?.sourceEnd ?? 0,
+  };
+}
+
+export function createDocumentAnchorSelector(
+  projection: DocumentTextProjection,
+  range: DocumentTextRange,
+  options: CreateDocumentAnchorSelectorOptions = {},
+): DocumentAnnotationAnchorSelector {
+  const contextLength = options.contextLength ?? DEFAULT_CONTEXT_LENGTH;
+  return {
+    quote: {
+      exact: range.text,
+      prefix: projection.text.slice(Math.max(0, range.normalizedStart - contextLength), range.normalizedStart),
+      suffix: projection.text.slice(range.normalizedEnd, range.normalizedEnd + contextLength),
+    },
+    position: {
+      normalizedStart: range.normalizedStart,
+      normalizedEnd: range.normalizedEnd,
+      markdownStart: range.markdownStart,
+      markdownEnd: range.markdownEnd,
+    },
+  };
+}
+
+export function selectorToAnchorSnapshot(selector: DocumentAnnotationAnchorSelector): DocumentAnnotationAnchorSnapshot {
+  return {
+    selectedText: selector.quote.exact,
+    prefixText: selector.quote.prefix,
+    suffixText: selector.quote.suffix,
+    normalizedStart: selector.position.normalizedStart,
+    normalizedEnd: selector.position.normalizedEnd,
+    markdownStart: selector.position.markdownStart,
+    markdownEnd: selector.position.markdownEnd,
+  };
+}
+
+export function anchorSnapshotToSelector(anchor: DocumentAnnotationAnchorSnapshot): DocumentAnnotationAnchorSelector {
+  return {
+    quote: {
+      exact: anchor.selectedText,
+      prefix: anchor.prefixText,
+      suffix: anchor.suffixText,
+    },
+    position: {
+      normalizedStart: anchor.normalizedStart,
+      normalizedEnd: anchor.normalizedEnd,
+      markdownStart: anchor.markdownStart,
+      markdownEnd: anchor.markdownEnd,
+    },
+  };
+}
+
+export function verifyDocumentAnchorSelector(
+  input: VerifyDocumentAnchorSelectorInput,
+): VerifyDocumentAnchorSelectorResult {
+  const projection = projectMarkdownToText(input.markdown);
+  const range = resolveProjectionRange(
+    projection,
+    input.selector.position.normalizedStart,
+    input.selector.position.normalizedEnd,
+  );
+  if (!range) {
+    return { ok: false, anchor: null, projection, reason: "invalid_range" };
+  }
+
+  if (normalizeAnchorText(range.text) !== normalizeAnchorText(input.selector.quote.exact)) {
+    return { ok: false, anchor: null, projection, reason: "quote_mismatch" };
+  }
+
+  if (
+    range.markdownStart !== input.selector.position.markdownStart
+    || range.markdownEnd !== input.selector.position.markdownEnd
+  ) {
+    return { ok: false, anchor: null, projection, reason: "position_mismatch" };
+  }
+
+  const selector = createDocumentAnchorSelector(projection, range, {
+    contextLength: input.contextLength ?? DEFAULT_CONTEXT_LENGTH,
+  });
+  return { ok: true, anchor: selectorToAnchorSnapshot(selector), projection, reason: "verified" };
+}
+
+export function remapDocumentAnchor(input: RemapDocumentAnchorInput): RemapDocumentAnchorResult {
+  const projection = projectMarkdownToText(input.nextMarkdown);
+  const contextLength = input.contextLength ?? DEFAULT_CONTEXT_LENGTH;
+  const quote = normalizeAnchorText(input.previousAnchor.selectedText);
+  if (!quote) {
+    return { anchorState: "orphaned", confidence: "missing", anchor: null, projection, reason: "missing" };
+  }
+
+  const exactCandidates = findOccurrences(projection.text, quote).map((start) => scoreCandidate({
+    projection,
+    start,
+    end: start + quote.length,
+    previousAnchor: input.previousAnchor,
+    reason: "exact",
+    contextLength,
+  }));
+
+  if (exactCandidates.length > 0) {
+    exactCandidates.sort((a, b) => b.score - a.score);
+    const [best, second] = exactCandidates;
+    if (exactCandidates.length > 1 && (!second || Math.abs(best.score - second.score) < 0.05)) {
+      return {
+        anchorState: "stale",
+        confidence: "ambiguous",
+        anchor: buildAnchorSnapshot(projection, best.start, best.end, contextLength),
+        projection,
+        reason: "ambiguous",
+      };
+    }
+    return {
+      anchorState: "active",
+      confidence: exactCandidates.length === 1 ? "exact" : "duplicate",
+      anchor: buildAnchorSnapshot(projection, best.start, best.end, contextLength),
+      projection,
+      reason: exactCandidates.length === 1 ? "exact" : "duplicate",
+    };
+  }
+
+  const fuzzy = findFuzzyCandidate(projection, input.previousAnchor, contextLength);
+  if (fuzzy && fuzzy.score >= 0.58) {
+    return {
+      anchorState: "stale",
+      confidence: "fuzzy",
+      anchor: buildAnchorSnapshot(projection, fuzzy.start, fuzzy.end, contextLength),
+      projection,
+      reason: "fuzzy",
+    };
+  }
+
+  return { anchorState: "orphaned", confidence: "missing", anchor: null, projection, reason: "missing" };
+}
+
+function stripBlockSyntax(line: string, absoluteOffset: number): { text: string; sourceOffset: number } {
+  const blockMatch = line.match(/^\s{0,3}(?:(#{1,6})\s+|(?:[-+*]|\d+[.)])\s+|>\s?)/);
+  if (!blockMatch) return { text: line, sourceOffset: absoluteOffset };
+  return { text: line.slice(blockMatch[0].length), sourceOffset: absoluteOffset + blockMatch[0].length };
+}
+
+function addInlineMarkdownText(builder: ProjectionBuilder, text: string, sourceOffset: number): void {
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index] ?? "";
+    const absolute = sourceOffset + index;
+    const rest = text.slice(index);
+
+    const image = rest.match(/^!\[([^\]]*)\]\(([^)]*)\)/);
+    if (image) {
+      const altStart = absolute + 2;
+      builder.addText(image[1] ?? "", altStart);
+      index += image[0].length - 1;
+      continue;
+    }
+
+    const link = rest.match(/^\[([^\]]+)\]\(([^)]*)\)/);
+    if (link) {
+      const labelStart = absolute + 1;
+      builder.addText(link[1] ?? "", labelStart);
+      index += link[0].length - 1;
+      continue;
+    }
+
+    if (char === "`") {
+      const closing = text.indexOf("`", index + 1);
+      if (closing > index + 1) {
+        builder.addText(text.slice(index + 1, closing), absolute + 1);
+        index = closing;
+        continue;
+      }
+    }
+
+    if (char === "|" || char === "\t") {
+      builder.addSeparator(absolute);
+      continue;
+    }
+
+    if (isMarkdownFormattingChar(char, text, index)) continue;
+
+    builder.addChar(char, absolute, absolute + 1);
+  }
+}
+
+function isMarkdownFormattingChar(char: string, text: string, index: number): boolean {
+  if (char === "*" || char === "_" || char === "~") return true;
+  if (char === "\\" && index + 1 < text.length) return true;
+  return false;
+}
+
+function findOccurrences(text: string, quote: string): number[] {
+  const starts: number[] = [];
+  let start = text.indexOf(quote);
+  while (start !== -1) {
+    starts.push(start);
+    start = text.indexOf(quote, start + 1);
+  }
+  return starts;
+}
+
+function scoreCandidate(args: {
+  projection: DocumentTextProjection;
+  start: number;
+  end: number;
+  previousAnchor: DocumentAnnotationAnchorSnapshot;
+  reason: Candidate["reason"];
+  contextLength: number;
+}): Candidate {
+  const before = args.projection.text.slice(Math.max(0, args.start - args.contextLength), args.start);
+  const after = args.projection.text.slice(args.end, args.end + args.contextLength);
+  const prefixScore = suffixOverlapScore(args.previousAnchor.prefixText, before);
+  const suffixScore = prefixOverlapScore(args.previousAnchor.suffixText, after);
+  const distance = Math.abs(args.start - args.previousAnchor.normalizedStart);
+  const proximity = 1 / (1 + distance / 200);
+  return {
+    start: args.start,
+    end: args.end,
+    score: prefixScore * 0.35 + suffixScore * 0.35 + proximity * 0.3,
+    reason: args.reason,
+  };
+}
+
+function findFuzzyCandidate(
+  projection: DocumentTextProjection,
+  previousAnchor: DocumentAnnotationAnchorSnapshot,
+  contextLength: number,
+): Candidate | null {
+  const words = normalizeAnchorText(previousAnchor.selectedText).split(" ").filter(Boolean);
+  if (words.length === 0) return null;
+  const textWords = [...projection.text.matchAll(/\S+/g)].map((match) => ({
+    text: match[0],
+    start: match.index ?? 0,
+    end: (match.index ?? 0) + match[0].length,
+  }));
+  const windowSizes = new Set([words.length - 1, words.length, words.length + 1, words.length + 2].filter((n) => n > 0));
+  let best: Candidate | null = null;
+
+  for (const size of windowSizes) {
+    for (let index = 0; index + size <= textWords.length; index += 1) {
+      const window = textWords.slice(index, index + size);
+      const candidateText = window.map((word) => word.text).join(" ");
+      const similarity = similarityScore(normalizeAnchorText(previousAnchor.selectedText), candidateText);
+      if (similarity < 0.45) continue;
+      const scored = scoreCandidate({
+        projection,
+        start: window[0]?.start ?? 0,
+        end: window[window.length - 1]?.end ?? 0,
+        previousAnchor,
+        reason: "fuzzy",
+        contextLength,
+      });
+      scored.score = scored.score * 0.35 + similarity * 0.65;
+      if (!best || scored.score > best.score) best = scored;
+    }
+  }
+
+  return best;
+}
+
+function buildAnchorSnapshot(
+  projection: DocumentTextProjection,
+  normalizedStart: number,
+  normalizedEnd: number,
+  contextLength: number,
+): DocumentAnnotationAnchorSnapshot {
+  const range = resolveProjectionRange(projection, normalizedStart, normalizedEnd);
+  if (!range) {
+    return {
+      selectedText: "",
+      prefixText: "",
+      suffixText: "",
+      normalizedStart,
+      normalizedEnd,
+      markdownStart: 0,
+      markdownEnd: 0,
+    };
+  }
+  const selector = createDocumentAnchorSelector(projection, range, { contextLength });
+  return selectorToAnchorSnapshot(selector);
+}
+
+function prefixOverlapScore(expectedPrefix: string, actualPrefix: string): number {
+  const expected = normalizeAnchorText(expectedPrefix);
+  const actual = normalizeAnchorText(actualPrefix);
+  if (!expected) return 0.5;
+  for (let size = Math.min(expected.length, actual.length); size > 0; size -= 1) {
+    if (expected.slice(0, size) === actual.slice(0, size)) return size / expected.length;
+  }
+  return 0;
+}
+
+function suffixOverlapScore(expectedPrefix: string, actualPrefix: string): number {
+  const expected = normalizeAnchorText(expectedPrefix);
+  const actual = normalizeAnchorText(actualPrefix);
+  if (!expected) return 0.5;
+  for (let size = Math.min(expected.length, actual.length); size > 0; size -= 1) {
+    if (expected.slice(-size) === actual.slice(-size)) return size / expected.length;
+  }
+  return 0;
+}
+
+function similarityScore(left: string, right: string): number {
+  if (left === right) return 1;
+  const leftWords = new Set(left.toLowerCase().split(/\s+/).filter(Boolean));
+  const rightWords = new Set(right.toLowerCase().split(/\s+/).filter(Boolean));
+  const intersection = [...leftWords].filter((word) => rightWords.has(word)).length;
+  const union = new Set([...leftWords, ...rightWords]).size || 1;
+  const jaccard = intersection / union;
+  const lengthRatio = Math.min(left.length, right.length) / Math.max(left.length, right.length, 1);
+  return jaccard * 0.75 + lengthRatio * 0.25;
+}
+
+class ProjectionBuilder {
+  private text = "";
+  private positions: DocumentTextPosition[] = [];
+  private pendingSpace: DocumentTextPosition | null = null;
+
+  constructor(private readonly source: string) {}
+
+  addText(text: string, sourceOffset: number): void {
+    for (let index = 0; index < text.length; index += 1) {
+      this.addChar(text[index] ?? "", sourceOffset + index, sourceOffset + index + 1);
+    }
+  }
+
+  addSeparator(sourceOffset: number): void {
+    this.addChar(" ", sourceOffset, sourceOffset + 1);
+  }
+
+  addChar(char: string, sourceStart: number, sourceEnd: number): void {
+    if (/\s/.test(char)) {
+      if (this.text.length > 0 && !this.pendingSpace) {
+        this.pendingSpace = { sourceStart, sourceEnd };
+      }
+      return;
+    }
+
+    if (this.pendingSpace && this.text.length > 0) {
+      this.text += " ";
+      this.positions.push(this.pendingSpace);
+    }
+    this.pendingSpace = null;
+    this.text += char;
+    this.positions.push({ sourceStart, sourceEnd });
+  }
+
+  toProjection(): DocumentTextProjection {
+    return {
+      source: this.source,
+      text: this.text,
+      positions: this.positions,
+    };
+  }
+}

packages/shared/src/index.ts

@@ -45,6 +45,9 @@ export {
   SYSTEM_ISSUE_DOCUMENT_KEYS,
   isSystemIssueDocumentKey,
   ISSUE_REFERENCE_SOURCE_KINDS,
+  DOCUMENT_ANNOTATION_THREAD_STATUSES,
+  DOCUMENT_ANNOTATION_ANCHOR_STATES,
+  DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES,
   ISSUE_EXECUTION_POLICY_MODES,
   ISSUE_EXECUTION_STAGE_TYPES,
   ISSUE_MONITOR_SCHEDULED_BY,
@@ -164,6 +167,9 @@ export {
   type IssueTreeHoldStatus,
   type SystemIssueDocumentKey,
   type IssueReferenceSourceKind,
+  type DocumentAnnotationThreadStatus,
+  type DocumentAnnotationAnchorState,
+  type DocumentAnnotationAnchorConfidence,
   type IssueExecutionPolicyMode,
   type IssueExecutionStageType,
   type IssueMonitorScheduledBy,
@@ -290,6 +296,13 @@ export type {
   CompanySkillUsageAgent,
   CompanySkillDetail,
   CompanySkillUpdateStatus,
+  CompanySkillAuditSeverity,
+  CompanySkillAuditVerdict,
+  CompanySkillUpdateHoldReason,
+  CompanySkillAuditFinding,
+  CompanySkillAuditResult,
+  CompanySkillInstallUpdateRequest,
+  CompanySkillResetRequest,
   CompanySkillImportRequest,
   CompanySkillImportResult,
   CompanySkillProjectScanRequest,
@@ -299,6 +312,14 @@ export type {
   CompanySkillCreateRequest,
   CompanySkillFileDetail,
   CompanySkillFileUpdateRequest,
+  CatalogSkillKind,
+  CatalogSkillFileKind,
+  CatalogSkillFile,
+  CatalogSkill,
+  CatalogSkillListQuery,
+  CatalogSkillFileDetail,
+  CompanySkillInstallCatalogRequest,
+  CompanySkillInstallCatalogResult,
   AgentSkillSyncMode,
   AgentSkillState,
   AgentSkillOrigin,
@@ -376,6 +397,20 @@ export type {
   IssueWorkProductProvider,
   IssueWorkProductStatus,
   IssueWorkProductReviewState,
+  CreateDocumentAnnotationCommentRequest,
+  CreateDocumentAnnotationThreadRequest,
+  DocumentAnnotationAnchorRemapSnapshot,
+  DocumentAnnotationAnchorSelector,
+  DocumentAnnotationAnchorSnapshot,
+  DocumentAnnotationComment,
+  DocumentAnnotationTextPositionSelector,
+  DocumentAnnotationTextQuoteSelector,
+  DocumentAnnotationThread,
+  DocumentAnnotationThreadWithComments,
+  DocumentTextPosition,
+  DocumentTextProjection,
+  DocumentTextRange,
+  UpdateDocumentAnnotationThreadRequest,
   Issue,
   IssueAssigneeAdapterOverrides,
   IssueBlockerAttention,
@@ -438,6 +473,12 @@ export type {
   RequestConfirmationTarget,
   RequestConfirmationPayload,
   RequestConfirmationResult,
+  AcceptedPlanDecompositionStatus,
+  AcceptedPlanDecompositionChild,
+  AcceptedPlanDecomposition,
+  AcceptedPlanDecompositionResult,
+  AcceptedPlanDecompositionChildIssue,
+  AcceptedPlanDecompositionSummary,
   IssueThreadInteractionBase,
   SuggestTasksInteraction,
   AskUserQuestionsInteraction,
@@ -655,6 +696,22 @@ export {
   type IssueReferenceMatch,
 } from "./issue-references.js";
 
+export {
+  anchorSnapshotToSelector,
+  createDocumentAnchorSelector,
+  normalizeAnchorText,
+  projectMarkdownToText,
+  remapDocumentAnchor,
+  resolveProjectionRange,
+  selectorToAnchorSnapshot,
+  verifyDocumentAnchorSelector,
+  type CreateDocumentAnchorSelectorOptions,
+  type RemapDocumentAnchorInput,
+  type RemapDocumentAnchorResult,
+  type VerifyDocumentAnchorSelectorInput,
+  type VerifyDocumentAnchorSelectorResult,
+} from "./document-anchors.js";
+
 export {
   sidebarOrderPreferenceSchema,
   upsertSidebarOrderPreferenceSchema,
@@ -796,6 +853,18 @@ export {
   type CreateProjectWorkspace,
   type UpdateProjectWorkspace,
   projectExecutionWorkspacePolicySchema,
+  createDocumentAnnotationCommentSchema,
+  createDocumentAnnotationThreadSchema,
+  documentAnnotationAnchorConfidenceSchema,
+  documentAnnotationAnchorSelectorSchema,
+  documentAnnotationAnchorStateSchema,
+  documentAnnotationTextPositionSelectorSchema,
+  documentAnnotationTextQuoteSelectorSchema,
+  documentAnnotationThreadStatusSchema,
+  updateDocumentAnnotationThreadSchema,
+  type CreateDocumentAnnotationComment,
+  type CreateDocumentAnnotationThread,
+  type UpdateDocumentAnnotationThread,
   companySearchQuerySchema,
   COMPANY_SEARCH_DEFAULT_LIMIT,
   COMPANY_SEARCH_MAX_LIMIT,
@@ -806,6 +875,7 @@ export {
   createIssueSchema,
   createIssueInputSchema,
   createChildIssueSchema,
+  createAcceptedPlanDecompositionSchema,
   resolveCreateIssueStatusDefault,
   createIssueLabelSchema,
   issueBlockedInboxAttentionSchema,
@@ -874,6 +944,7 @@ export {
   releaseIssueTreeHoldSchema,
   type CreateIssue,
   type CreateChildIssue,
+  type CreateAcceptedPlanDecomposition,
   type CreateIssueLabel,
   type UpdateIssue,
   type ResolveIssueRecoveryAction,
@@ -1013,6 +1084,8 @@ export {
   companySkillUsageAgentSchema,
   companySkillDetailSchema,
   companySkillUpdateStatusSchema,
+  companySkillAuditFindingSchema,
+  companySkillAuditResultSchema,
   companySkillImportSchema,
   companySkillUpdateAuthSchema,
   companySkillProjectScanRequestSchema,
@@ -1022,6 +1095,15 @@ export {
   companySkillCreateSchema,
   companySkillFileDetailSchema,
   companySkillFileUpdateSchema,
+  catalogSkillKindSchema,
+  catalogSkillFileSchema,
+  catalogSkillSchema,
+  catalogSkillListQuerySchema,
+  catalogSkillFileDetailSchema,
+  companySkillInstallCatalogSchema,
+  companySkillInstallCatalogResultSchema,
+  companySkillInstallUpdateSchema,
+  companySkillResetSchema,
   portabilityIncludeSchema,
   portabilityEnvInputSchema,
   portabilityCompanyManifestEntrySchema,

packages/shared/src/types/company-skill.ts

@@ -51,6 +51,10 @@ export interface CompanySkillListItem {
   sourceLabel: string | null;
   sourceBadge: CompanySkillSourceBadge;
   sourcePath: string | null;
+  catalogKind: "bundled" | "optional" | null;
+  originHash: string | null;
+  packageName: string | null;
+  packageVersion: string | null;
 }
 
 export interface CompanySkillUsageAgent {
@@ -84,6 +88,49 @@ export interface CompanySkillUpdateStatus {
   currentRef: string | null;
   latestRef: string | null;
   hasUpdate: boolean;
+  installedHash: string | null;
+  originHash: string | null;
+  userModifiedAt: string | null;
+  updateHoldReason: CompanySkillUpdateHoldReason | null;
+  auditVerdict: CompanySkillAuditVerdict | null;
+  auditCodes: string[];
+}
+
+export type CompanySkillAuditSeverity = "warning" | "error";
+
+export type CompanySkillAuditVerdict = "pass" | "warning" | "fail";
+
+export type CompanySkillUpdateHoldReason =
+  | "local_modifications"
+  | "audit_hard_stop"
+  | "origin_unavailable"
+  | "compatibility_invalid"
+  | "operator_hold";
+
+export interface CompanySkillAuditFinding {
+  code: string;
+  severity: CompanySkillAuditSeverity;
+  message: string;
+  path: string | null;
+}
+
+export interface CompanySkillAuditResult {
+  skillId: string;
+  installedHash: string | null;
+  originHash: string | null;
+  verdict: CompanySkillAuditVerdict;
+  codes: string[];
+  findings: CompanySkillAuditFinding[];
+  scannedAt: string;
+  scanVersion: string;
+}
+
+export interface CompanySkillInstallUpdateRequest {
+  force?: boolean;
+}
+
+export interface CompanySkillResetRequest {
+  force?: boolean;
 }
 
 export interface CompanySkillImportRequest {
@@ -155,3 +202,64 @@ export interface CompanySkillFileUpdateRequest {
   path: string;
   content: string;
 }
+
+export type CatalogSkillKind = "bundled" | "optional";
+
+export type CatalogSkillFileKind = CompanySkillFileInventoryEntry["kind"];
+
+export interface CatalogSkillFile {
+  path: string;
+  kind: CatalogSkillFileKind;
+  sizeBytes: number;
+  sha256: string;
+}
+
+export interface CatalogSkill {
+  id: string;
+  key: string;
+  kind: CatalogSkillKind;
+  category: string;
+  slug: string;
+  name: string;
+  description: string;
+  path: string;
+  entrypoint: "SKILL.md";
+  trustLevel: CompanySkillTrustLevel;
+  compatibility: CompanySkillCompatibility;
+  defaultInstall: boolean;
+  recommendedForRoles: string[];
+  requires: string[];
+  tags: string[];
+  files: CatalogSkillFile[];
+  contentHash: string;
+  packageName?: string;
+  packageVersion?: string;
+}
+
+export interface CatalogSkillListQuery {
+  kind?: CatalogSkillKind;
+  category?: string;
+  q?: string;
+}
+
+export interface CatalogSkillFileDetail {
+  catalogSkillId: string;
+  path: string;
+  kind: CatalogSkillFileKind;
+  content: string;
+  language: string | null;
+  markdown: boolean;
+}
+
+export interface CompanySkillInstallCatalogRequest {
+  catalogSkillId: string;
+  slug?: string | null;
+  force?: boolean;
+}
+
+export interface CompanySkillInstallCatalogResult {
+  action: "created" | "updated" | "unchanged";
+  skill: CompanySkill;
+  catalogSkill: CatalogSkill;
+  warnings: string[];
+}

packages/shared/src/types/document-annotation.ts

@@ -0,0 +1,134 @@
+import type {
+  DocumentAnnotationAnchorConfidence,
+  DocumentAnnotationAnchorState,
+  DocumentAnnotationThreadStatus,
+  IssueCommentAuthorType,
+} from "../constants.js";
+
+export interface DocumentTextPosition {
+  sourceStart: number;
+  sourceEnd: number;
+}
+
+export interface DocumentTextProjection {
+  source: string;
+  text: string;
+  positions: DocumentTextPosition[];
+}
+
+export interface DocumentTextRange {
+  text: string;
+  normalizedStart: number;
+  normalizedEnd: number;
+  markdownStart: number;
+  markdownEnd: number;
+}
+
+export interface DocumentAnnotationTextQuoteSelector {
+  exact: string;
+  prefix: string;
+  suffix: string;
+}
+
+export interface DocumentAnnotationTextPositionSelector {
+  normalizedStart: number;
+  normalizedEnd: number;
+  markdownStart: number;
+  markdownEnd: number;
+}
+
+export interface DocumentAnnotationAnchorSelector {
+  quote: DocumentAnnotationTextQuoteSelector;
+  position: DocumentAnnotationTextPositionSelector;
+}
+
+export interface DocumentAnnotationAnchorSnapshot {
+  selectedText: string;
+  prefixText: string;
+  suffixText: string;
+  normalizedStart: number;
+  normalizedEnd: number;
+  markdownStart: number;
+  markdownEnd: number;
+}
+
+export interface DocumentAnnotationThread {
+  id: string;
+  companyId: string;
+  issueId: string;
+  documentId: string;
+  documentKey: string;
+  status: DocumentAnnotationThreadStatus;
+  anchorState: DocumentAnnotationAnchorState;
+  anchorConfidence: DocumentAnnotationAnchorConfidence;
+  originalRevisionId: string | null;
+  originalRevisionNumber: number;
+  currentRevisionId: string | null;
+  currentRevisionNumber: number;
+  selectedText: string;
+  prefixText: string;
+  suffixText: string;
+  normalizedStart: number;
+  normalizedEnd: number;
+  markdownStart: number;
+  markdownEnd: number;
+  anchorSelector: DocumentAnnotationAnchorSelector;
+  createdByAgentId: string | null;
+  createdByUserId: string | null;
+  resolvedByAgentId: string | null;
+  resolvedByUserId: string | null;
+  resolvedAt: Date | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface DocumentAnnotationComment {
+  id: string;
+  companyId: string;
+  threadId: string;
+  issueId: string;
+  documentId: string;
+  body: string;
+  authorType: IssueCommentAuthorType;
+  authorAgentId: string | null;
+  authorUserId: string | null;
+  createdByRunId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface DocumentAnnotationAnchorRemapSnapshot {
+  id: string;
+  companyId: string;
+  threadId: string;
+  documentId: string;
+  fromRevisionId: string | null;
+  fromRevisionNumber: number | null;
+  toRevisionId: string | null;
+  toRevisionNumber: number;
+  previousAnchor: DocumentAnnotationAnchorSnapshot;
+  nextAnchor: DocumentAnnotationAnchorSnapshot | null;
+  anchorState: DocumentAnnotationAnchorState;
+  anchorConfidence: DocumentAnnotationAnchorConfidence;
+  failureReason: string | null;
+  createdAt: Date;
+}
+
+export interface DocumentAnnotationThreadWithComments extends DocumentAnnotationThread {
+  comments: DocumentAnnotationComment[];
+}
+
+export interface CreateDocumentAnnotationThreadRequest {
+  baseRevisionId: string;
+  baseRevisionNumber: number;
+  selector: DocumentAnnotationAnchorSelector;
+  body: string;
+}
+
+export interface CreateDocumentAnnotationCommentRequest {
+  body: string;
+}
+
+export interface UpdateDocumentAnnotationThreadRequest {
+  status?: DocumentAnnotationThreadStatus;
+}

packages/shared/src/types/index.ts

@@ -51,6 +51,13 @@ export type {
   CompanySkillUsageAgent,
   CompanySkillDetail,
   CompanySkillUpdateStatus,
+  CompanySkillAuditSeverity,
+  CompanySkillAuditVerdict,
+  CompanySkillUpdateHoldReason,
+  CompanySkillAuditFinding,
+  CompanySkillAuditResult,
+  CompanySkillInstallUpdateRequest,
+  CompanySkillResetRequest,
   CompanySkillImportRequest,
   CompanySkillImportResult,
   CompanySkillProjectScanRequest,
@@ -60,6 +67,14 @@ export type {
   CompanySkillCreateRequest,
   CompanySkillFileDetail,
   CompanySkillFileUpdateRequest,
+  CatalogSkillKind,
+  CatalogSkillFileKind,
+  CatalogSkillFile,
+  CatalogSkill,
+  CatalogSkillListQuery,
+  CatalogSkillFileDetail,
+  CompanySkillInstallCatalogRequest,
+  CompanySkillInstallCatalogResult,
 } from "./company-skill.js";
 export type {
   AgentSkillSyncMode,
@@ -89,6 +104,22 @@ export type {
   AdapterEnvironmentTestResult,
 } from "./agent.js";
 export type { AssetImage } from "./asset.js";
+export type {
+  CreateDocumentAnnotationCommentRequest,
+  CreateDocumentAnnotationThreadRequest,
+  DocumentAnnotationAnchorRemapSnapshot,
+  DocumentAnnotationAnchorSelector,
+  DocumentAnnotationAnchorSnapshot,
+  DocumentAnnotationComment,
+  DocumentAnnotationTextPositionSelector,
+  DocumentAnnotationTextQuoteSelector,
+  DocumentAnnotationThread,
+  DocumentAnnotationThreadWithComments,
+  DocumentTextPosition,
+  DocumentTextProjection,
+  DocumentTextRange,
+  UpdateDocumentAnnotationThreadRequest,
+} from "./document-annotation.js";
 export type { Project, ProjectCodebase, ProjectCodebaseOrigin, ProjectGoalRef, ProjectManagedByPlugin, ProjectWorkspace } from "./project.js";
 export type {
   CompanySearchHighlight,
@@ -207,6 +238,12 @@ export type {
   RequestConfirmationTarget,
   RequestConfirmationPayload,
   RequestConfirmationResult,
+  AcceptedPlanDecompositionStatus,
+  AcceptedPlanDecompositionChild,
+  AcceptedPlanDecomposition,
+  AcceptedPlanDecompositionResult,
+  AcceptedPlanDecompositionChildIssue,
+  AcceptedPlanDecompositionSummary,
   IssueThreadInteractionBase,
   SuggestTasksInteraction,
   AskUserQuestionsInteraction,

packages/shared/src/types/instance.ts

@@ -29,6 +29,7 @@ export interface InstanceGeneralSettings {
 export interface InstanceExperimentalSettings {
   enableEnvironments: boolean;
   enableIsolatedWorkspaces: boolean;
+  enableIssuePlanDecompositions: boolean;
   enableCloudSync: boolean;
   autoRestartDevServerWhenIdle: boolean;
   enableIssueGraphLivenessAutoRecovery: boolean;

packages/shared/src/types/issue.ts

@@ -129,6 +129,71 @@ export interface LegacyPlanDocument {
   source: "issue_description";
 }
 
+export type AcceptedPlanDecompositionStatus = "in_flight" | "completed";
+
+export interface AcceptedPlanDecompositionChild {
+  projectId?: string | null;
+  projectWorkspaceId?: string | null;
+  goalId?: string | null;
+  blockedByIssueIds?: string[];
+  title: string;
+  description?: string | null;
+  status: IssueStatus;
+  workMode: IssueWorkMode;
+  priority: IssuePriority;
+  assigneeAgentId?: string | null;
+  assigneeUserId?: string | null;
+  requestDepth?: number;
+  billingCode?: string | null;
+  assigneeAdapterOverrides?: IssueAssigneeAdapterOverrides | null;
+  executionPolicy?: IssueExecutionPolicy | null;
+  executionWorkspaceId?: string | null;
+  executionWorkspacePreference?: string | null;
+  executionWorkspaceSettings?: IssueExecutionWorkspaceSettings | null;
+  labelIds?: string[];
+  acceptanceCriteria?: string[];
+  blockParentUntilDone?: boolean;
+}
+
+export interface AcceptedPlanDecomposition {
+  id: string;
+  companyId: string;
+  sourceIssueId: string;
+  acceptedPlanRevisionId: string;
+  acceptedInteractionId: string | null;
+  status: AcceptedPlanDecompositionStatus;
+  requestFingerprint: string;
+  requestedChildCount: number;
+  childIssueIds: string[];
+  ownerAgentId: string | null;
+  ownerUserId: string | null;
+  ownerRunId: string | null;
+  completedAt: Date | string | null;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+}
+
+export interface AcceptedPlanDecompositionResult {
+  decomposition: AcceptedPlanDecomposition;
+  childIssueIds: string[];
+  newlyCreatedChildIssueIds: string[];
+}
+
+export interface AcceptedPlanDecompositionChildIssue {
+  id: string;
+  identifier: string | null;
+  title: string;
+  status: IssueStatus;
+  priority: IssuePriority;
+  assigneeAgentId: string | null;
+  assigneeUserId: string | null;
+}
+
+export interface AcceptedPlanDecompositionSummary extends AcceptedPlanDecomposition {
+  acceptedPlanRevisionNumber: number | null;
+  childIssues: AcceptedPlanDecompositionChildIssue[];
+}
+
 export interface IssueRelationIssueSummary {
   id: string;
   identifier: string | null;

packages/shared/src/types/plugin.ts

@@ -38,8 +38,24 @@ import type { Routine, RoutineTrigger, RoutineVariable } from "./routine.js";
 /**
  * A JSON Schema object used for plugin config schemas and tool parameter schemas.
  * Plugins provide these as plain JSON Schema compatible objects.
+ *
+ * The Paperclip extension keywords below are recognised by the Paperclip UI
+ * but are otherwise ignored by standard JSON Schema validators.
  */
-export type JsonSchema = Record<string, unknown>;
+export type JsonSchema = {
+  /**
+   * When true, the Paperclip config UI hides this property behind an
+   * "Advanced options" disclosure. Defaults to false (always visible).
+   */
+  "x-paperclip-advanced"?: boolean;
+  /**
+   * Optional sub-section heading used to group advanced properties inside
+   * the disclosure (e.g. "SSH access", "VM resources"). Ignored when
+   * `x-paperclip-advanced` is not true.
+   */
+  "x-paperclip-group"?: string;
+  [key: string]: unknown;
+};
 
 export type {
   PluginDatabaseCoreReadTable,

packages/shared/src/types/workspace-operation.ts

@@ -2,7 +2,8 @@ export type WorkspaceOperationPhase =
   | "worktree_prepare"
   | "workspace_provision"
   | "workspace_teardown"
-  | "worktree_cleanup";
+  | "worktree_cleanup"
+  | "workspace_finalize";
 
 export type WorkspaceOperationStatus = "running" | "succeeded" | "failed" | "skipped";
 

packages/shared/src/validators/company-skill.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from "vitest";
+import {
+  catalogSkillFileDetailSchema,
+  catalogSkillListQuerySchema,
+  companySkillAuditResultSchema,
+  companySkillInstallCatalogResultSchema,
+  companySkillInstallCatalogSchema,
+  companySkillInstallUpdateSchema,
+  companySkillResetSchema,
+  companySkillUpdateStatusSchema,
+} from "./company-skill.js";
+
+const catalogSkill = {
+  id: "paperclipai:bundled:software-development:review",
+  key: "paperclipai/bundled/software-development/review",
+  kind: "bundled",
+  category: "software-development",
+  slug: "review",
+  name: "review",
+  description: "Review code",
+  path: "catalog/bundled/software-development/review",
+  entrypoint: "SKILL.md",
+  trustLevel: "markdown_only",
+  compatibility: "compatible",
+  defaultInstall: false,
+  recommendedForRoles: ["engineer"],
+  requires: [],
+  tags: ["review"],
+  files: [{ path: "SKILL.md", kind: "skill", sizeBytes: 8, sha256: "abc" }],
+  contentHash: "sha256:abc",
+};
+
+const companySkill = {
+  id: "00000000-0000-4000-8000-000000000001",
+  companyId: "00000000-0000-4000-8000-000000000002",
+  key: catalogSkill.key,
+  slug: catalogSkill.slug,
+  name: catalogSkill.name,
+  description: catalogSkill.description,
+  markdown: "# Review\n",
+  sourceType: "catalog",
+  sourceLocator: "/tmp/review",
+  sourceRef: catalogSkill.contentHash,
+  trustLevel: "markdown_only",
+  compatibility: "compatible",
+  fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+  metadata: {
+    sourceKind: "catalog",
+    catalogId: catalogSkill.id,
+    originHash: catalogSkill.contentHash,
+  },
+  createdAt: "2026-05-26T00:00:00.000Z",
+  updatedAt: "2026-05-26T00:00:00.000Z",
+};
+
+describe("company skill catalog validators", () => {
+  it("accepts catalog list and install request shapes", () => {
+    expect(catalogSkillListQuerySchema.parse({
+      kind: "bundled",
+      category: "software-development",
+      q: "review",
+    })).toEqual({
+      kind: "bundled",
+      category: "software-development",
+      q: "review",
+    });
+
+    expect(companySkillInstallCatalogSchema.parse({
+      catalogSkillId: catalogSkill.id,
+      slug: "team-review",
+      force: true,
+    })).toEqual({
+      catalogSkillId: catalogSkill.id,
+      slug: "team-review",
+      force: true,
+    });
+  });
+
+  it("rejects invalid catalog filter and install payloads", () => {
+    expect(() => catalogSkillListQuerySchema.parse({ kind: "external" })).toThrow();
+    expect(() => companySkillInstallCatalogSchema.parse({ force: true })).toThrow();
+  });
+
+  it("accepts catalog file and install result responses", () => {
+    expect(catalogSkillFileDetailSchema.parse({
+      catalogSkillId: catalogSkill.id,
+      path: "SKILL.md",
+      kind: "skill",
+      content: "# Review\n",
+      language: "markdown",
+      markdown: true,
+    })).toMatchObject({
+      catalogSkillId: catalogSkill.id,
+      path: "SKILL.md",
+    });
+
+    expect(companySkillInstallCatalogResultSchema.parse({
+      action: "created",
+      skill: companySkill,
+      catalogSkill,
+      warnings: [],
+    })).toMatchObject({
+      action: "created",
+      skill: {
+        key: catalogSkill.key,
+        sourceType: "catalog",
+      },
+      catalogSkill: {
+        id: catalogSkill.id,
+      },
+    });
+  });
+
+  it("accepts update status, audit, update, and reset contract shapes", () => {
+    expect(companySkillUpdateStatusSchema.parse({
+      supported: true,
+      reason: null,
+      trackingRef: catalogSkill.id,
+      currentRef: "sha256:old",
+      latestRef: catalogSkill.contentHash,
+      hasUpdate: true,
+      installedHash: "sha256:installed",
+      originHash: catalogSkill.contentHash,
+      userModifiedAt: "2026-05-26T00:00:00.000Z",
+      updateHoldReason: "local_modifications",
+      auditVerdict: "warning",
+      auditCodes: ["local_modifications"],
+    })).toMatchObject({
+      supported: true,
+      updateHoldReason: "local_modifications",
+      auditVerdict: "warning",
+    });
+
+    expect(companySkillAuditResultSchema.parse({
+      skillId: companySkill.id,
+      installedHash: "sha256:installed",
+      originHash: catalogSkill.contentHash,
+      verdict: "fail",
+      codes: ["remote_fetch_exec"],
+      findings: [{
+        code: "remote_fetch_exec",
+        severity: "error",
+        message: "Remote-fetch or dynamic execution pattern is not allowed.",
+        path: "SKILL.md",
+      }],
+      scannedAt: "2026-05-26T00:00:00.000Z",
+      scanVersion: "skills-audit-v1",
+    })).toMatchObject({
+      verdict: "fail",
+      codes: ["remote_fetch_exec"],
+    });
+
+    expect(companySkillInstallUpdateSchema.parse(undefined)).toEqual({});
+    expect(companySkillInstallUpdateSchema.parse({ force: true })).toEqual({ force: true });
+    expect(companySkillResetSchema.parse(undefined)).toEqual({});
+    expect(companySkillResetSchema.parse({ force: true })).toEqual({ force: true });
+  });
+});

packages/shared/src/validators/company-skill.ts

@@ -35,6 +35,10 @@ export const companySkillListItemSchema = companySkillSchema.extend({
   editableReason: z.string().nullable(),
   sourceLabel: z.string().nullable(),
   sourceBadge: companySkillSourceBadgeSchema,
+  catalogKind: z.enum(["bundled", "optional"]).nullable(),
+  originHash: z.string().nullable(),
+  packageName: z.string().nullable(),
+  packageVersion: z.string().nullable(),
 });
 
 export const companySkillUsageAgentSchema = z.object({
@@ -64,15 +68,48 @@ export const companySkillUpdateStatusSchema = z.object({
   currentRef: z.string().nullable(),
   latestRef: z.string().nullable(),
   hasUpdate: z.boolean(),
+  installedHash: z.string().nullable(),
+  originHash: z.string().nullable(),
+  userModifiedAt: z.string().nullable(),
+  updateHoldReason: z.enum([
+    "local_modifications",
+    "audit_hard_stop",
+    "origin_unavailable",
+    "compatibility_invalid",
+    "operator_hold",
+  ]).nullable(),
+  auditVerdict: z.enum(["pass", "warning", "fail"]).nullable(),
+  auditCodes: z.array(z.string()),
 });
 
+export const companySkillAuditFindingSchema = z.object({
+  code: z.string().min(1),
+  severity: z.enum(["warning", "error"]),
+  message: z.string().min(1),
+  path: z.string().nullable(),
+});
+
+export const companySkillAuditResultSchema = z.object({
+  skillId: z.string().uuid(),
+  installedHash: z.string().nullable(),
+  originHash: z.string().nullable(),
+  verdict: z.enum(["pass", "warning", "fail"]),
+  codes: z.array(z.string()),
+  findings: z.array(companySkillAuditFindingSchema),
+  scannedAt: z.string().min(1),
+  scanVersion: z.string().min(1),
+});
+
+export const companySkillInstallUpdateSchema = z.object({
+  force: z.boolean().optional(),
+}).default({});
+
+export const companySkillResetSchema = z.object({
+  force: z.boolean().optional(),
+}).default({});
+
 export const companySkillImportSchema = z.object({
   source: z.string().min(1),
-  authToken: z.string().min(1).optional(),
-});
-
-export const companySkillUpdateAuthSchema = z.object({
-  authToken: z.string().min(1).nullable(),
 });
 
 export const companySkillProjectScanRequestSchema = z.object({
@@ -136,8 +173,70 @@ export const companySkillFileUpdateSchema = z.object({
   content: z.string(),
 });
 
+export const catalogSkillKindSchema = z.enum(["bundled", "optional"]);
+
+export const catalogSkillFileSchema = z.object({
+  path: z.string().min(1),
+  kind: z.enum(["skill", "markdown", "reference", "script", "asset", "other"]),
+  sizeBytes: z.number().int().nonnegative(),
+  sha256: z.string().min(1),
+});
+
+export const catalogSkillSchema = z.object({
+  id: z.string().min(1),
+  key: z.string().min(1),
+  kind: catalogSkillKindSchema,
+  category: z.string().min(1),
+  slug: z.string().min(1),
+  name: z.string().min(1),
+  description: z.string(),
+  path: z.string().min(1),
+  entrypoint: z.literal("SKILL.md"),
+  trustLevel: companySkillTrustLevelSchema,
+  compatibility: companySkillCompatibilitySchema,
+  defaultInstall: z.boolean(),
+  recommendedForRoles: z.array(z.string()),
+  requires: z.array(z.string()),
+  tags: z.array(z.string()),
+  files: z.array(catalogSkillFileSchema),
+  contentHash: z.string().min(1),
+  packageName: z.string().min(1).optional(),
+  packageVersion: z.string().min(1).optional(),
+});
+
+export const catalogSkillListQuerySchema = z.object({
+  kind: catalogSkillKindSchema.optional(),
+  category: z.string().min(1).optional(),
+  q: z.string().min(1).optional(),
+});
+
+export const catalogSkillFileDetailSchema = z.object({
+  catalogSkillId: z.string().min(1),
+  path: z.string().min(1),
+  kind: z.enum(["skill", "markdown", "reference", "script", "asset", "other"]),
+  content: z.string(),
+  language: z.string().nullable(),
+  markdown: z.boolean(),
+});
+
+export const companySkillInstallCatalogSchema = z.object({
+  catalogSkillId: z.string().min(1),
+  slug: z.string().min(1).nullable().optional(),
+  force: z.boolean().optional(),
+});
+
+export const companySkillInstallCatalogResultSchema = z.object({
+  action: z.enum(["created", "updated", "unchanged"]),
+  skill: companySkillSchema,
+  catalogSkill: catalogSkillSchema,
+  warnings: z.array(z.string()),
+});
+
 export type CompanySkillImport = z.infer<typeof companySkillImportSchema>;
 export type CompanySkillProjectScan = z.infer<typeof companySkillProjectScanRequestSchema>;
 export type CompanySkillCreate = z.infer<typeof companySkillCreateSchema>;
 export type CompanySkillFileUpdate = z.infer<typeof companySkillFileUpdateSchema>;
-export type CompanySkillUpdateAuth = z.infer<typeof companySkillUpdateAuthSchema>;
+export type CatalogSkillListQuery = z.infer<typeof catalogSkillListQuerySchema>;
+export type CompanySkillInstallCatalog = z.infer<typeof companySkillInstallCatalogSchema>;
+export type CompanySkillInstallUpdate = z.infer<typeof companySkillInstallUpdateSchema>;
+export type CompanySkillReset = z.infer<typeof companySkillResetSchema>;

packages/shared/src/validators/document-annotation.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import {
+  DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES,
+  DOCUMENT_ANNOTATION_ANCHOR_STATES,
+  DOCUMENT_ANNOTATION_THREAD_STATUSES,
+} from "../constants.js";
+import { multilineTextSchema } from "./text.js";
+
+export const documentAnnotationThreadStatusSchema = z.enum(DOCUMENT_ANNOTATION_THREAD_STATUSES);
+export const documentAnnotationAnchorStateSchema = z.enum(DOCUMENT_ANNOTATION_ANCHOR_STATES);
+export const documentAnnotationAnchorConfidenceSchema = z.enum(DOCUMENT_ANNOTATION_ANCHOR_CONFIDENCES);
+
+export const documentAnnotationTextQuoteSelectorSchema = z.object({
+  exact: z.string().min(1).max(10_000),
+  prefix: z.string().max(1_000).default(""),
+  suffix: z.string().max(1_000).default(""),
+}).strict();
+
+export const documentAnnotationTextPositionSelectorSchema = z.object({
+  normalizedStart: z.number().int().nonnegative(),
+  normalizedEnd: z.number().int().nonnegative(),
+  markdownStart: z.number().int().nonnegative(),
+  markdownEnd: z.number().int().nonnegative(),
+}).strict().superRefine((value, ctx) => {
+  if (value.normalizedEnd <= value.normalizedStart) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "normalizedEnd must be greater than normalizedStart",
+      path: ["normalizedEnd"],
+    });
+  }
+  if (value.markdownEnd <= value.markdownStart) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: "markdownEnd must be greater than markdownStart",
+      path: ["markdownEnd"],
+    });
+  }
+});
+
+export const documentAnnotationAnchorSelectorSchema = z.object({
+  quote: documentAnnotationTextQuoteSelectorSchema,
+  position: documentAnnotationTextPositionSelectorSchema,
+}).strict();
+
+export const createDocumentAnnotationThreadSchema = z.object({
+  baseRevisionId: z.string().uuid(),
+  baseRevisionNumber: z.number().int().positive(),
+  selector: documentAnnotationAnchorSelectorSchema,
+  body: multilineTextSchema.pipe(z.string().min(1).max(20_000)),
+}).strict();
+
+export const createDocumentAnnotationCommentSchema = z.object({
+  body: multilineTextSchema.pipe(z.string().min(1).max(20_000)),
+}).strict();
+
+export const updateDocumentAnnotationThreadSchema = z.object({
+  status: documentAnnotationThreadStatusSchema.optional(),
+}).strict().refine((value) => value.status != null, {
+  message: "At least one field must be provided",
+});
+
+export type CreateDocumentAnnotationThread = z.infer<typeof createDocumentAnnotationThreadSchema>;
+export type CreateDocumentAnnotationComment = z.infer<typeof createDocumentAnnotationCommentSchema>;
+export type UpdateDocumentAnnotationThread = z.infer<typeof updateDocumentAnnotationThreadSchema>;

packages/shared/src/validators/index.ts

@@ -67,8 +67,9 @@ export {
   companySkillUsageAgentSchema,
   companySkillDetailSchema,
   companySkillUpdateStatusSchema,
+  companySkillAuditFindingSchema,
+  companySkillAuditResultSchema,
   companySkillImportSchema,
-  companySkillUpdateAuthSchema,
   companySkillProjectScanRequestSchema,
   companySkillProjectScanSkippedSchema,
   companySkillProjectScanConflictSchema,
@@ -76,11 +77,23 @@ export {
   companySkillCreateSchema,
   companySkillFileDetailSchema,
   companySkillFileUpdateSchema,
+  catalogSkillKindSchema,
+  catalogSkillFileSchema,
+  catalogSkillSchema,
+  catalogSkillListQuerySchema,
+  catalogSkillFileDetailSchema,
+  companySkillInstallCatalogSchema,
+  companySkillInstallCatalogResultSchema,
+  companySkillInstallUpdateSchema,
+  companySkillResetSchema,
   type CompanySkillImport,
   type CompanySkillProjectScan,
   type CompanySkillCreate,
   type CompanySkillFileUpdate,
-  type CompanySkillUpdateAuth,
+  type CatalogSkillListQuery,
+  type CompanySkillInstallCatalog,
+  type CompanySkillInstallUpdate,
+  type CompanySkillReset,
 } from "./company-skill.js";
 export {
   agentSkillStateSchema,
@@ -154,10 +167,26 @@ export {
   type ProjectExecutionWorkspacePolicy,
 } from "./project.js";
 
+export {
+  createDocumentAnnotationCommentSchema,
+  createDocumentAnnotationThreadSchema,
+  documentAnnotationAnchorConfidenceSchema,
+  documentAnnotationAnchorSelectorSchema,
+  documentAnnotationAnchorStateSchema,
+  documentAnnotationTextPositionSelectorSchema,
+  documentAnnotationTextQuoteSelectorSchema,
+  documentAnnotationThreadStatusSchema,
+  updateDocumentAnnotationThreadSchema,
+  type CreateDocumentAnnotationComment,
+  type CreateDocumentAnnotationThread,
+  type UpdateDocumentAnnotationThread,
+} from "./document-annotation.js";
+
 export {
   createIssueSchema,
   createIssueInputSchema,
   createChildIssueSchema,
+  createAcceptedPlanDecompositionSchema,
   resolveCreateIssueStatusDefault,
   createIssueLabelSchema,
   issueBlockedInboxAttentionSchema,
@@ -209,6 +238,7 @@ export {
   restoreIssueDocumentRevisionSchema,
   type CreateIssue,
   type CreateChildIssue,
+  type CreateAcceptedPlanDecomposition,
   type CreateIssueLabel,
   type UpdateIssue,
   type IssueExecutionWorkspaceSettings,

packages/shared/src/validators/instance.ts

@@ -38,6 +38,7 @@ export const patchInstanceGeneralSettingsSchema = instanceGeneralSettingsSchema.
 export const instanceExperimentalSettingsSchema = z.object({
   enableEnvironments: z.boolean().default(false),
   enableIsolatedWorkspaces: z.boolean().default(false),
+  enableIssuePlanDecompositions: z.boolean().default(false),
   enableCloudSync: z.boolean().default(false),
   autoRestartDevServerWhenIdle: z.boolean().default(false),
   enableIssueGraphLivenessAutoRecovery: z.boolean().default(false),

packages/shared/src/validators/issue.ts

@@ -412,6 +412,13 @@ export const createChildIssueSchema = withCreateIssueStatusDefault(createIssueBa
 
 export type CreateChildIssue = z.infer<typeof createChildIssueSchema>;
 
+export const createAcceptedPlanDecompositionSchema = z.object({
+  acceptedPlanRevisionId: z.string().uuid(),
+  children: z.array(createChildIssueSchema).min(1).max(25),
+});
+
+export type CreateAcceptedPlanDecomposition = z.infer<typeof createAcceptedPlanDecompositionSchema>;
+
 export const createIssueLabelSchema = z.object({
   name: z.string().trim().min(1).max(48),
   color: z.string().regex(/^#(?:[0-9a-fA-F]{6})$/, "Color must be a 6-digit hex value"),

packages/skills-catalog/catalog/bundled/docs/doc-maintenance/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: doc-maintenance
+description: Keep project docs aligned with recent code and feature changes — detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.
+key: paperclipai/bundled/docs/doc-maintenance
+recommendedForRoles:
+  - engineer
+  - product
+  - devrel
+tags:
+  - docs
+  - documentation
+  - release-notes
+---
+
+# Doc Maintenance
+
+Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes".
+
+## When to use
+
+- A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions.
+- A user-reported bug traced back to outdated documentation.
+- A release is being cut and the docs need a pass against the merged commits.
+- A new feature shipped but only the engineer's PR description describes how to use it.
+
+## When not to use
+
+- The change is internal-only (private helper rename, refactor) with no user-visible impact.
+- You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first.
+
+## The pass
+
+1. **Establish the baseline.** Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR).
+2. **Enumerate user-visible changes.** Read commits and PR descriptions. List, for each change, what a user can now do differently.
+3. **Map changes to docs.** For each change, find every page that mentions the affected concept. Common targets: README, CLI reference, API reference, configuration reference, migration guide, FAQ, examples.
+4. **Update precisely.** Edit only the lines that need to change. Do not rewrap paragraphs you did not modify — it pollutes the diff.
+5. **Add new entries where needed.** New CLI flag → CLI reference entry. New env var → configuration reference entry. New endpoint → API reference entry. Don't only add it to the changelog.
+6. **Update examples and snippets.** Code blocks in docs are wrong faster than prose. Re-run any example that touches new behavior.
+7. **Write the release note.** One sentence per user-visible change. Group by Added / Changed / Fixed / Deprecated / Removed. Link to the relevant PRs and docs section.
+8. **Cross-check.** Search the docs for the old behavior wording and remove or update stragglers.
+
+## Style baseline
+
+- Voice: second person ("you can pass `--json` to ..."). Avoid "we" except in narrative pages.
+- Tense: present, not future. The behavior exists once shipped.
+- Headings: imperative ("Configure the cache") or noun-phrase ("Cache configuration"), match the surrounding page.
+- Code blocks: include the language tag so syntax highlighting works.
+- Cross-links: link the first mention of a concept on each page; do not link every occurrence.
+- Avoid promising future behavior. If something is unreleased, mark it `experimental` or omit it.
+
+## Drift detection
+
+A doc page is drifting if any of these are true:
+
+- It documents a flag, key, or endpoint that no longer exists.
+- An example does not run as written.
+- A default value in the docs does not match the code.
+- A supported-versions list excludes a version the project actually supports, or includes one it dropped.
+- A "Coming soon" section references a feature that shipped or was cancelled.
+
+When you find drift, fix it in the same pass and note it in the release note's `Fixed` group.
+
+## Release-note rules
+
+- One sentence per item. If two sentences are needed, the item is likely two items.
+- User impact first, internal cause second. `Faster cold start (avoid full bundle download on first run)` beats `Refactor bootstrap loader`.
+- Link the PR for engineering readers and the docs page for users.
+- Mark breaking changes explicitly: `**Breaking:**` prefix. Include migration steps inline or via link.
+
+## Anti-patterns
+
+- Massive doc PRs that bundle stylistic rewrites with real updates. Reviewers cannot tell which lines reflect actual behavior changes.
+- "Updated docs" commit messages with no detail. Make the commit say what changed and why.
+- Adding to the changelog without updating the reference docs the changelog points to.
+- Marking a feature as available before its code lands. Documentation must follow behavior, not promise it.

packages/skills-catalog/catalog/bundled/paperclip-operations/issue-triage/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: issue-triage
+description: Triage Paperclip inbox issues that are stale, blocked, in-review, or assigned-but-not-progressing, and decide a single next action per issue (resume, reassign, unblock, escalate, or close).
+key: paperclipai/bundled/paperclip-operations/issue-triage
+recommendedForRoles:
+  - manager
+  - ceo
+  - engineer
+tags:
+  - paperclip
+  - triage
+  - inbox
+  - workflow
+---
+
+# Issue Triage
+
+Convert a noisy inbox into a small set of clear next actions. Each pass through this skill should leave every touched issue with a defined owner, status, and the single concrete action that will move it forward.
+
+## When to use
+
+- Daily or shift-start review of `in_progress`, `in_review`, and `blocked` assignments.
+- An inbox has many open assignments and no clear priority.
+- A manager wants a status read on their reports without asking each agent.
+- You are woken by a comment that suggests an old issue stalled.
+
+## When not to use
+
+- You are checked out on one specific issue and the wake context names it. Work that issue, do not triage the whole inbox.
+- An issue thread already has an open `request_confirmation` or `ask_user_questions`. Wait for the response — re-triage is noise.
+
+## Inputs
+
+- `GET /api/agents/me/inbox-lite` for the compact assignment list.
+- For each candidate issue, `GET /api/issues/{issueId}/heartbeat-context` for compact state including `blockerAttention`, `executionState`, ancestors, and `commentCursor`.
+- Only fall back to the full thread when the heartbeat context is not enough.
+
+## Per-issue triage decision
+
+For each issue, classify into exactly one of:
+
+1. **Resume** — execution path is alive. Confirm the assignee is set and let the heartbeat continue. Do not comment.
+2. **Wake-needed** — assignee is stalled with no live continuation. Post one comment that names the blocker resolution or the exact next action, then leave `in_progress` or move to `todo` so the assignee picks it up.
+3. **Reassign** — the assignee is not the right specialty. Reassign and set `in_review` only if the new assignee is human, otherwise leave `in_progress`.
+4. **Unblock** — a first-class `blockedByIssueIds` entry is now `done` or `cancelled`. If `cancelled`, replace or remove it from `blockedByIssueIds`. The blockers-resolved wake will fire automatically when all are `done`.
+5. **Escalate** — the issue needs board, CTO, or user input. Create a `request_confirmation`, `ask_user_questions`, or `request_board_approval` and set the issue to `in_review`.
+6. **Close** — work is complete, duplicate, or no longer relevant. Set `done` or `cancelled` with a one-line reason.
+
+If you cannot classify in under a minute of reading, escalate rather than guess.
+
+## Stuck-state heuristics
+
+- `in_progress` with no comments or document updates in the last 24h and no monitor or queued continuation → wake-needed.
+- `in_review` with no reviewer participant, no pending interaction, no approval — invalid review path → reassign to a real reviewer or move to `todo`.
+- `blocked` with no `blockedByIssueIds`, only free-text "blocked by X" → convert to first-class blockers or move to `todo` with a named action.
+- `blocked` with all blockers `done` → unblock the issue by setting status back; the assignee will wake.
+- Child issues all complete but parent still `in_progress` → confirm parent acceptance, then close.
+
+## Don't-do list
+
+- Do not @-mention agents during triage; mentions cost budget. Use direct reassignment instead.
+- Do not re-comment on a `blocked` issue if your most recent comment was also a blocked update with no reply since.
+- Do not cancel cross-team issues. Reassign to the responsible manager with a comment.
+- Do not change status without a comment that explains the change.
+
+## Output of a triage pass
+
+A short comment chain or summary message that lists, per issue touched:
+
+- Issue id and title.
+- Verdict (resume / wake-needed / reassign / unblock / escalate / close).
+- The one action you took or asked for.
+
+This is the bar for "the triage is done."

packages/skills-catalog/catalog/bundled/paperclip-operations/task-planning/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: task-planning
+description: Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document.
+key: paperclipai/bundled/paperclip-operations/task-planning
+recommendedForRoles:
+  - manager
+  - engineer
+  - product
+tags:
+  - paperclip
+  - planning
+  - issues
+  - delegation
+---
+
+# Task Planning
+
+Produce implementation plans that the Paperclip executor can actually run: explicit child issues, real blockers, named owners, and a defined acceptance bar. Avoid plans that read well but cannot be split into work.
+
+## When to use
+
+- An issue asks you to "plan", "scope", "break down", "design the rollout", "propose the work", or similar.
+- A user wants a written plan before approving implementation.
+- A manager needs to delegate non-trivial work and the shape of the work is not obvious yet.
+- You inherited an issue too large to deliver in one heartbeat and need to split it.
+
+## When not to use
+
+- The issue is a single small change you can ship in the same heartbeat. Just ship it.
+- The issue is forensic ("why did this break"). Use a diagnosis skill first; plan only after the root cause is named.
+- A current `plan` document already exists and the change is minor. Update that document; do not start fresh.
+
+## Outputs
+
+1. An updated issue document with key `plan` (markdown).
+2. A short comment on the issue that links to the plan document and names the next action.
+3. Where the plan requires approval, an issue-thread interaction of kind `request_confirmation` bound to the latest plan revision.
+
+Do not create implementation subtasks until the plan is accepted.
+
+## Plan structure
+
+Required sections, in order:
+
+1. **Goal** — one paragraph. What changes for the user, the operator, or the system once this work lands.
+2. **Context reviewed** — bullet list of documents, files, and prior issues you read. Lets reviewers spot missing inputs.
+3. **Constraints and non-goals** — what must hold (compatibility, security, performance) and what this plan deliberately will not do.
+4. **Approach** — the chosen path, with a short rationale. If you considered alternatives, name them and why you rejected them.
+5. **Work breakdown** — ordered list of child issues. Each child has:
+   - Title in imperative form.
+   - Owner specialty (Engineer, QA, Designer, Security, DevRel, Manager, etc.).
+   - Scope and deliverables.
+   - Acceptance criteria.
+   - Blocks/blocked-by relationships expressed by phase letter or child title.
+6. **Acceptance** — the bar for the parent issue. How the user knows the whole thing is done.
+7. **Risks and mitigations** — short list. Skip if there are none.
+8. **Deferrals** — what is intentionally pushed to follow-up issues, with why.
+
+## Rules of thumb for splitting
+
+- One child issue, one specialty. If two specialties have to coordinate inside the same issue, split it.
+- One child issue, one acceptance verdict. If a reviewer would say "this is half done", split it.
+- A child must be checkout-able by the owner from its title and description alone. Reviewers should not have to re-read the parent plan to understand a child.
+- Order children by real blocker chains, not by author preference. Parallel children should explicitly say `blockers: none`.
+- Avoid `polish` or `cleanup` child issues without acceptance criteria — they never close.
+
+## Filing the plan
+
+Use the Paperclip API to write the plan document, then comment:
+
+- `PUT /api/issues/{issueId}/documents/plan` with the markdown body. If `plan` already exists, include the latest `baseRevisionId`.
+- `POST /api/issues/{issueId}/comments` with a short summary that links the plan: `/<prefix>/issues/<issue-id>#document-plan`.
+- If approval is required: `POST /api/issues/{issueId}/interactions` with `kind: request_confirmation`, `targetRevisionId` set to the new plan revision, `continuationPolicy: wake_assignee`, and `idempotencyKey: "confirmation:{issueId}:plan:{revisionId}"`.
+- Set the issue to `in_review` after creating the confirmation. Stay assigned so the acceptance wakes the planner.
+
+When the plan is accepted, see the companion skill for converting accepted plans into Paperclip executable tasks.
+
+## Anti-patterns
+
+- Plan disguised as a description edit. Use the `plan` document.
+- "Phases A–Z" with no work breakdown inside the phases.
+- Children with descriptions that say "see parent" — they fail at delegation time.
+- Acceptance written as "code review approval". Reviewers need a behavior bar, not a process bar.
+- Plans that bury blocker chains in prose. Use explicit blocked-by lines.

packages/skills-catalog/catalog/bundled/quality/qa-acceptance/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: qa-acceptance
+description: Produce QA acceptance criteria and a manual validation plan for a feature change — golden path, edge cases, error states, performance limits, and explicit pass/fail evidence.
+key: paperclipai/bundled/quality/qa-acceptance
+recommendedForRoles:
+  - qa
+  - engineer
+  - product
+tags:
+  - qa
+  - acceptance
+  - validation
+  - testing
+---
+
+# QA Acceptance
+
+Write acceptance criteria that a reviewer can run against the running app and decide pass or fail without asking the author. The criteria are the contract — automated tests cover correctness, QA covers feature-level behavior.
+
+## When to use
+
+- A feature change is heading to QA and needs a written validation plan.
+- A reviewer is asked to verify a PR that touches user-visible behavior.
+- An incident postmortem requires a regression check before reopen-prevention.
+- A release candidate needs a pre-cut smoke pass.
+
+## When not to use
+
+- The change is unit-test-only (utility refactor, internal naming). Acceptance criteria are unnecessary churn.
+- You are asked to write tests against API contracts. Use contract testing, not feature QA.
+
+## Acceptance criteria format
+
+Each criterion is a single, independently-verifiable statement:
+
+```md
+- **Given** <starting state>, **when** <action>, **then** <observable outcome>.
+```
+
+Example:
+
+```md
+- **Given** a CSV export with 0 rows, **when** the user clicks Export, **then** the file downloads with only the header row and the UI shows "Exported 0 rows".
+```
+
+Avoid criteria that combine multiple `when`s or `then`s. Split them.
+
+## What every plan must cover
+
+1. **Golden path.** The most common successful flow, end to end.
+2. **Empty and minimum states.** Zero items, one item, missing optional inputs.
+3. **Boundary inputs.** Max length strings, max numeric values, unicode, RTL text where applicable.
+4. **Error states.** Network failure, permission denied, validation failures, conflict (409), not found (404).
+5. **Concurrency and ordering.** Two users acting at once, race against background jobs, refresh during mutation.
+6. **Performance envelope.** The largest realistic input the change must handle without UI hangs or timeouts.
+7. **Backward compatibility.** Existing data, existing URLs, persisted user preferences continue to work.
+8. **Telemetry and audit.** Events, logs, or activity entries the change is supposed to emit.
+
+If a section is genuinely not applicable, write "N/A: <why>" — do not silently omit.
+
+## Evidence
+
+Each criterion needs evidence on the verification pass:
+
+- Screenshot or short clip for UI behavior.
+- Copied console / network output for API behavior.
+- Log snippet or activity row for telemetry.
+- Timing measurement for performance criteria.
+
+"Looks good to me" without evidence is not a pass.
+
+## Quarantine and follow-up
+
+- A failing criterion blocks acceptance unless explicitly waived by the owner with a tracked follow-up issue.
+- "Known issue" without a linked follow-up is not a waiver.
+- If you add a new criterion mid-pass, restart the pass — partial coverage hides regressions.
+
+## Handoff back to the author
+
+Return the validation plan with three sections:
+
+- **Pass.** Criteria that passed, with one-line evidence summaries.
+- **Fail.** Criteria that failed, with the exact reproduction.
+- **Blocked.** Criteria you could not run, with why.
+
+The author owns turning failures into either fixes or accepted deferrals.
+
+## Anti-patterns
+
+- Acceptance phrased as test plan ("write a Cypress test for X"). Acceptance is what is true after the change ships; tests are how you check.
+- Criteria that depend on inspecting implementation details (selectors, query plans). Stay observable.
+- Long checklists with no priority. Mark must-pass criteria distinctly from nice-to-have.
+- Validation reports that say "passed" with no evidence. Reviewers cannot audit those.

packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: github-pr-workflow
+description: Prepare a GitHub pull request from a feature branch — branch hygiene, commit shape, title/body, verification notes, screenshots for UI work, and replies to review comments.
+key: paperclipai/bundled/software-development/github-pr-workflow
+recommendedForRoles:
+  - engineer
+tags:
+  - github
+  - pull-requests
+  - code-review
+  - release
+---
+
+# GitHub Pull Request Workflow
+
+Ship a PR a reviewer can land without follow-up clarifying questions. The aim is high signal in the title and body, evidence the change works, and clean replies when feedback comes in.
+
+## When to use
+
+- You are about to open a PR for a change that is functionally complete.
+- A reviewer left comments and you need to respond and push fixes.
+- A PR has been open more than a day and needs to be brought back into shape (stale conflicts, missing description, missing verification).
+
+## When not to use
+
+- The change is not yet functionally complete. Finish the work first; draft PRs that bounce on review are noise.
+- The repository uses a non-GitHub forge. Adjust to that forge's conventions; do not force GitHub-isms.
+
+## Branch hygiene before opening
+
+- Rebase or merge from the target base so the diff is current.
+- Squash WIP commits into reviewable units. Prefer one commit per logical change; do not force one-commit-per-PR if the work is genuinely multi-step.
+- Confirm tests, typecheck, and lint pass locally. Note any deliberate skips in the PR body.
+- Remove debug prints, commented-out code, and `TODO` markers that are not tracked.
+
+## PR title
+
+- Imperative mood, under 70 characters.
+- Lead with the user-visible change, not the file touched. `Allow CSV export from reports table` beats `Update reports.tsx`.
+- If the repo uses an issue prefix convention (`PAP-1234:`, `[security]`), follow it.
+- No trailing period.
+
+## PR body
+
+Use this structure:
+
+```md
+## Summary
+- 1–3 bullets describing what changed and why.
+
+## Implementation notes
+- Anything non-obvious in the diff: trade-offs, dropped alternatives, gotchas.
+- Migration or config implications.
+
+## Verification
+- The exact commands or steps you ran.
+- Screenshots or short clips for UI changes (required if pixels moved).
+- Edge cases you exercised by hand.
+
+## Risk and rollback
+- What breaks if this is reverted, and how to revert cleanly.
+```
+
+Skip the `Risk and rollback` section only for clearly trivial PRs (typos, docs).
+
+## Verification evidence
+
+- Tests passing in CI is necessary, not sufficient. Reviewers also need to know the change behaves correctly end to end.
+- For UI work, include screenshots of the golden path and one edge case. Tag dark and light mode if the project supports both.
+- For migrations, include a dry-run plan and reversal steps.
+- For performance changes, include a before/after measurement, not adjectives.
+
+## Replying to review comments
+
+- Reply on every comment, even with just "fixed in <commit-sha>" — silent fixes leave the reviewer guessing.
+- Push fixes as new commits while review is active; do not amend during review unless the reviewer agrees.
+- If you disagree with feedback, say so with one sentence of rationale and let the reviewer decide. Don't escalate over comments.
+- Re-request review explicitly after pushing changes.
+
+## Merge checklist
+
+- All required checks green.
+- All review comments resolved.
+- PR title/body still accurate (update if scope changed mid-review).
+- Linked issue moves to `in_review` or `done` per project convention.
+- Delete the branch after merge unless it is a long-lived integration branch.
+
+## Anti-patterns
+
+- PR description that says "see commits". Reviewers should not need to read the log.
+- Mixing refactor and behavior change in the same PR with no separation in the body.
+- "Address feedback" commits that bundle unrelated edits. One commit per round of feedback is fine; one commit for everything in flight is not.
+- Force-pushing during active review without telling the reviewer.

packages/skills-catalog/catalog/optional/browser/agent-browser/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: agent-browser
+description: Drive a real browser to inspect or interact with a web page or app — navigate, take screenshots, read console and network, fill simple forms — for verification tasks, not unattended automation.
+key: paperclipai/optional/browser/agent-browser
+recommendedForRoles:
+  - qa
+  - engineer
+  - researcher
+tags:
+  - browser
+  - puppeteer
+  - playwright
+  - verification
+---
+
+# Agent Browser
+
+Use a controlled browser to verify behavior, capture evidence, or extract information from web pages that a static fetch cannot reach (SPAs, login-gated pages, dynamic content). This skill is about supervised verification, not unattended scraping.
+
+## When to use
+
+- You need a screenshot of a deployed page or a local dev server to confirm a UI change.
+- You need to read JavaScript-rendered content that `curl`/`wget` will not see.
+- A user reports a UI bug and you need to reproduce it interactively to capture console errors, network requests, or layout state.
+- You need to walk through a short flow (load page, click, observe) to verify acceptance criteria.
+
+## When not to use
+
+- The page is reachable as static HTML. Use `curl`/HTTP fetch — it is cheaper, faster, and more reliable.
+- The task is unattended large-scale scraping. That belongs to a dedicated scraper with rate limits, robots.txt handling, and a real user agent policy — not this skill.
+- The site is behind authentication you do not own credentials for, or whose terms of service prohibit automation.
+- The site involves sensitive accounts (banking, healthcare, government) where automation risks lockout or compliance issues.
+
+## Before launching the browser
+
+- Confirm the URL and what state should be true after navigation.
+- Decide what evidence is needed: full-page screenshot, viewport screenshot, console log, network trace, HTML snapshot, extracted text.
+- Decide the viewport size that matters for the task (mobile vs desktop). Default to a desktop size unless the task is mobile-specific.
+- For local dev servers, confirm the server is running and the port is what you expect.
+
+## Driving the browser
+
+A typical verification session:
+
+1. **Launch with a real-looking user agent** when the target is the public internet; an unrealistic UA flags automation traffic.
+2. **Set a sane viewport** (e.g., 1366×768 desktop, 390×844 iPhone-ish).
+3. **Navigate and wait for the right signal.** Prefer waiting for a specific selector or network-idle over arbitrary sleeps.
+4. **Capture evidence immediately** after the wait condition succeeds, before any interaction perturbs the state.
+5. **Interact deliberately.** One click at a time, with a wait between actions; re-screenshot after each meaningful state change.
+6. **Read the console and network panels** for unexpected errors, 4xx/5xx responses, or slow requests.
+7. **Close the browser cleanly** when done. Long-running browser sessions leak memory and hold ports.
+
+## What evidence to record
+
+For a verification task, deliver:
+
+- A full-page or viewport screenshot of each meaningful state.
+- The console log, filtered to warnings/errors.
+- Any non-2xx network response with the URL, status, and a short response body excerpt.
+- A short narration: "Navigated to X, observed Y, clicked Z, observed W."
+
+For a UI bug repro, also record:
+
+- The exact reproduction steps the user can follow.
+- Viewport size and (where relevant) device pixel ratio.
+- Whether the bug reproduces on first load vs after interaction.
+
+## Login-gated pages
+
+- Prefer programmatic auth (API token, magic link) over UI login.
+- If UI login is the only path, the user must provide credentials explicitly for this run. Never reuse credentials outside the session.
+- Do not store credentials in the session log, screenshot, or returned output.
+
+## Performance and politeness
+
+- Throttle to one navigation per few seconds when touching shared infra.
+- Respect `robots.txt` for public sites you are inspecting at any volume.
+- Cancel navigations if a page exceeds a reasonable timeout (e.g., 30s); the page is broken or rate-limiting you.
+- Do not retry forever on failure. Retry once with a longer timeout, then escalate.
+
+## Common failure modes
+
+- **Selector not found.** Page changed, or you are waiting before render. Take a screenshot to see actual state; adjust the selector.
+- **Click does nothing.** The element is offscreen, covered by a modal, or in a shadow DOM. Scroll into view or pierce the shadow root.
+- **Headless detection.** Some sites detect headless Chrome and serve a different page. Use a non-headless mode or a fingerprint-realistic configuration only when authorized.
+- **Cross-origin iframe blocking.** Iframes you do not own cannot be inspected; the page must offer the data outside the iframe or the task is infeasible.
+
+## Anti-patterns
+
+- Long unsupervised browser sessions that drift from the original task.
+- Scraping behind authentication you do not own.
+- Captioning a screenshot with "looks good" without saying what state was loaded and what selectors confirmed it.
+- Treating a passing screenshot as proof of correctness across viewports you did not actually test.

packages/skills-catalog/catalog/optional/content/release-announcement/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: release-announcement
+description: Write a release announcement — changelog, blog post, in-app note, or social post — that leads with user impact, names the audience, and includes upgrade/migration steps without filler.
+key: paperclipai/optional/content/release-announcement
+recommendedForRoles:
+  - devrel
+  - product
+  - writer
+tags:
+  - release
+  - changelog
+  - announcement
+  - communication
+---
+
+# Release Announcement
+
+Write the channel-appropriate announcement for a release without churn. Different surfaces need different shapes: a changelog entry is not a blog post is not a social card. The bar is: a reader of the chosen surface can decide in under 30 seconds whether this release affects them, and if so what to do.
+
+## When to use
+
+- A version, feature, or fix is shipping and needs writeup for at least one surface.
+- A previously private feature is going GA.
+- A breaking change needs broadcast before users hit it.
+
+## When not to use
+
+- An internal-only change with no user impact. Update internal docs; do not announce.
+- The release is incomplete (still in active development). Wait until it ships, even if marketing wants the post.
+
+## Determine the audience and channel first
+
+| Audience | Best channel | Tone |
+|---|---|---|
+| Existing power users | Changelog, in-app note | Terse, factual, links |
+| Engineering teams adopting your API | Release notes, dev blog | Examples, migration steps, version pins |
+| Prospective customers | Landing page, marketing blog | Story arc, problem → solution, social proof |
+| Broad audience | Social post, email newsletter | One-sentence pitch, link to depth |
+| Internal team | Slack/Discord post | What changed, who to ping if it breaks |
+
+Pick the audience for *this* writeup. One release often needs several writeups; do not blend them.
+
+## Universal structure
+
+Whatever the channel, lead with:
+
+1. **What changed.** One sentence in the user's vocabulary.
+2. **Who it affects.** Which user role / use case.
+3. **What to do.** Migrate now / opt-in / no action needed.
+
+Everything else is depth that supports those three.
+
+## Channel templates
+
+### Changelog entry (terse)
+
+```md
+## v1.42.0 — 2026-05-26
+
+### Added
+- <feature> — <one-line user benefit>. ([#1234](link))
+
+### Changed
+- <change> — <one-line impact>. ([#1235](link))
+
+### Fixed
+- <bug> — <one-line user-visible symptom>. ([#1236](link))
+
+### Deprecated
+- <thing>. Replaced by <thing>. Removal planned for v<x>.
+
+### Breaking
+- <change>. **Migration:** <one-line> or <link to guide>.
+```
+
+### Release notes (for adopters)
+
+Same as changelog, plus:
+
+- Migration guide section with before/after code.
+- Compatibility table (versions, runtimes, OS).
+- Known issues and workarounds.
+- Acknowledgements (contributors, reporters of fixed bugs).
+
+### Dev blog post (300–800 words)
+
+- **Hook (1 paragraph):** the problem the release solves, in a real-world scenario.
+- **What's new (3–5 bullets with sub-paragraphs):** features, with one code or screenshot example each.
+- **Upgrade (1 paragraph):** how to upgrade, what to check.
+- **What's next:** one sentence about the next direction. Avoid promises.
+
+### In-app note
+
+- 1 sentence.
+- 1 link.
+- Dismiss after seen.
+
+### Social post
+
+- 1 sentence pitch.
+- 1 link.
+- 1 image or short clip.
+- No threadbait. If it needs a thread, write a blog post instead.
+
+## Writing rules
+
+- Lead with the user, not the team. `You can now export to CSV` beats `We've added CSV export`.
+- Numbers beat adjectives. `60% faster cold start` beats `much faster`. Cite the methodology.
+- Show, don't just tell. One code snippet, one screenshot — more is noise.
+- Date the post. Undated release content rots fastest.
+- Link the migration path explicitly. Do not bury it.
+- Mark breaking changes with `**Breaking:**` prefix. Repeat in the email/social channel.
+
+## Avoid
+
+- "We are excited to announce" filler.
+- Lists of changes that mix user-visible and internal items.
+- Marketing claims without a way to verify.
+- Promised dates for unshipped work.
+- Pre-announcing something the team has not yet committed to ship.
+
+## Post-publish checklist
+
+- Changelog is in source control alongside the release.
+- Blog post date matches actual ship date.
+- All links work (release tag, PRs, docs sections).
+- Breaking changes are also in the upgrade guide, not only the post.
+- Internal team is notified before the public post goes live, not after.

packages/skills-catalog/catalog/optional/product/design-critique/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: design-critique
+description: Give a structured product design critique — user job clarity, hierarchy, affordance, error states, accessibility, and consistency — focused on what to change, in what order, and why.
+key: paperclipai/optional/product/design-critique
+recommendedForRoles:
+  - designer
+  - product
+  - engineer
+tags:
+  - design
+  - product
+  - ux
+  - review
+---
+
+# Product Design Critique
+
+A structured critique pass for a screen, flow, or component. The output is a prioritized list of changes a designer or engineer can act on — not adjectives. Critique is not redesign; recommend, do not rebuild.
+
+## When to use
+
+- A designer or engineer asks for feedback on a screen, mock, or live UI.
+- A feature is shipping and someone wants a final UX read.
+- A flow is suspected of causing user drop-off and you want a pre-research read before instrumentation.
+
+## When not to use
+
+- The user wants a redesign. That is a design project, not a critique.
+- The work is so early that no concrete artifact exists. Sketch with them instead of critiquing air.
+- You have no context on the user job. Ask for it first; design critique without user context devolves into taste.
+
+## Pre-critique context
+
+Before opening a screen, get:
+
+- **Who is the user.** Specific role and competence, not "users".
+- **What job they are doing on this screen.** One sentence.
+- **What success looks like.** What the user can do after this screen that they could not before.
+- **Where this screen sits in the larger flow.** What precedes and follows.
+
+If any of these is missing, ask. Critique without these is opinion.
+
+## The pass (in order)
+
+1. **Clarity of the user job.**
+   - Within 3 seconds of opening, is it obvious what this screen is for?
+   - Does the primary action match the user's actual job, or a designer's preferred path?
+
+2. **Visual hierarchy.**
+   - The most important thing on the screen should be the most prominent (size, weight, position, color).
+   - Secondary actions should look secondary. Tertiary should be findable but not loud.
+   - Headings should chunk content into the right groups for the task.
+
+3. **Affordance and signifiers.**
+   - Clickable things look clickable.
+   - Disabled things look disabled and explain why on hover/focus.
+   - Drag, scroll, or swipe interactions are discoverable, not hidden.
+
+4. **States.**
+   - Empty state (no data) is designed, not a blank rectangle.
+   - Loading state communicates progress, not just spins.
+   - Error states say what went wrong and what to do next, in the user's words.
+   - Success state confirms without celebrating banal actions.
+
+5. **Inputs and forms.**
+   - Labels visible, not just placeholders.
+   - Validation runs at the right time (on blur, not on every keystroke unless the user is in a known-format field).
+   - Required fields marked.
+   - Field order matches the user's mental order, not the database order.
+
+6. **Accessibility.**
+   - Sufficient color contrast (WCAG AA at minimum; AAA where reasonable).
+   - Focus order is logical for keyboard navigation.
+   - Interactive elements are reachable without a mouse.
+   - Critical information is not color-only (icons, text, position back it up).
+   - Touch targets at least 44×44 px on mobile.
+
+7. **Consistency.**
+   - Tokens, components, and patterns match the rest of the product.
+   - "Borrowed" patterns from other products are intentional, not accidental drift.
+
+8. **Copy.**
+   - Buttons are verbs that name the outcome ("Save changes" beats "Submit").
+   - Microcopy explains, does not decorate.
+   - Tone matches the product voice.
+
+9. **Edge cases.**
+   - Long content (long names, many items, RTL languages).
+   - Tiny content (one item, zero items).
+   - Slow network and offline behavior.
+   - Permissions denied.
+
+## Output format
+
+Group findings by severity, then by category. Each finding is one issue and one suggested fix.
+
+```md
+## Design critique: <screen name>
+
+### Must-fix (blocks ship)
+- **<category>:** <one-line issue>. **Try:** <one-line suggestion>.
+
+### Should-fix (before broader rollout)
+- **<category>:** <one-line issue>. **Try:** <one-line suggestion>.
+
+### Nice-to-fix (when there's room)
+- **<category>:** <one-line issue>. **Try:** <one-line suggestion>.
+
+### Strengths to keep
+- <one-line thing the design got right>
+```
+
+Always include the "strengths to keep" section. It is not flattery — it is signal to the designer about what not to change in the next round.
+
+## Anti-patterns
+
+- "I would do it differently" without saying what or why. That is preference, not critique.
+- Long critiques that bury must-fix items under nice-to-haves.
+- Suggesting net-new features under the guise of a critique.
+- Ignoring user context and grading on taste.
+- Treating a critique as approval. State approval explicitly if asked; otherwise critique is feedback, not sign-off.

packages/skills-catalog/generated/catalog.json

@@ -0,0 +1,285 @@
+{
+  "schemaVersion": 1,
+  "packageName": "@paperclipai/skills-catalog",
+  "packageVersion": "0.3.1",
+  "generatedAt": "2026-05-28T03:02:49.579Z",
+  "skills": [
+    {
+      "id": "paperclipai:bundled:docs:doc-maintenance",
+      "key": "paperclipai/bundled/docs/doc-maintenance",
+      "kind": "bundled",
+      "category": "docs",
+      "slug": "doc-maintenance",
+      "name": "doc-maintenance",
+      "description": "Keep project docs aligned with recent code and feature changes — detect drift, update affected pages, and add release-relevant notes without rewriting unchanged sections.",
+      "path": "catalog/bundled/docs/doc-maintenance",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "engineer",
+        "product",
+        "devrel"
+      ],
+      "requires": [],
+      "tags": [
+        "docs",
+        "documentation",
+        "release-notes"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4478,
+          "sha256": "fb0353386c5e5e5e13bcbb3233f044e3dccecf371f429d6328f26c26d7cb6169"
+        }
+      ],
+      "contentHash": "sha256:2e02299210fd17c1fe1867b4ee8c144a11b6fe1fe481f83b8268cfbaaf10f9aa"
+    },
+    {
+      "id": "paperclipai:bundled:paperclip-operations:issue-triage",
+      "key": "paperclipai/bundled/paperclip-operations/issue-triage",
+      "kind": "bundled",
+      "category": "paperclip-operations",
+      "slug": "issue-triage",
+      "name": "issue-triage",
+      "description": "Triage Paperclip inbox issues that are stale, blocked, in-review, or assigned-but-not-progressing, and decide a single next action per issue (resume, reassign, unblock, escalate, or close).",
+      "path": "catalog/bundled/paperclip-operations/issue-triage",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "manager",
+        "ceo",
+        "engineer"
+      ],
+      "requires": [],
+      "tags": [
+        "paperclip",
+        "triage",
+        "inbox",
+        "workflow"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4042,
+          "sha256": "df5bdc8bf5e017b7ba5f70a4b5323fad51d0c323278f386580f26cf43ad09160"
+        }
+      ],
+      "contentHash": "sha256:88dc13560371fb364963782cb4f6eeb4090fcde92ee3774479428ed6b90e11c1"
+    },
+    {
+      "id": "paperclipai:bundled:paperclip-operations:task-planning",
+      "key": "paperclipai/bundled/paperclip-operations/task-planning",
+      "kind": "bundled",
+      "category": "paperclip-operations",
+      "slug": "task-planning",
+      "name": "task-planning",
+      "description": "Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document.",
+      "path": "catalog/bundled/paperclip-operations/task-planning",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "manager",
+        "engineer",
+        "product"
+      ],
+      "requires": [],
+      "tags": [
+        "paperclip",
+        "planning",
+        "issues",
+        "delegation"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4649,
+          "sha256": "2ff61e12dfaa4cf8cc548529fd176f55f1b1f5292ff9dd3eb2cb331417ab5e4e"
+        }
+      ],
+      "contentHash": "sha256:4fb46a4bcefad4fd46fae48c433ee497112509a8e19fb8a7745ead44d219b498"
+    },
+    {
+      "id": "paperclipai:bundled:quality:qa-acceptance",
+      "key": "paperclipai/bundled/quality/qa-acceptance",
+      "kind": "bundled",
+      "category": "quality",
+      "slug": "qa-acceptance",
+      "name": "qa-acceptance",
+      "description": "Produce QA acceptance criteria and a manual validation plan for a feature change — golden path, edge cases, error states, performance limits, and explicit pass/fail evidence.",
+      "path": "catalog/bundled/quality/qa-acceptance",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "qa",
+        "engineer",
+        "product"
+      ],
+      "requires": [],
+      "tags": [
+        "qa",
+        "acceptance",
+        "validation",
+        "testing"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 3861,
+          "sha256": "c631b437ab26d104af6cdb963d8f679a9341439041b3cb3ec8835f4ff551b378"
+        }
+      ],
+      "contentHash": "sha256:32372dacaf62e93454b9855968c4eec96456ba78b509f450b3dfaa48e31ef356"
+    },
+    {
+      "id": "paperclipai:bundled:software-development:github-pr-workflow",
+      "key": "paperclipai/bundled/software-development/github-pr-workflow",
+      "kind": "bundled",
+      "category": "software-development",
+      "slug": "github-pr-workflow",
+      "name": "github-pr-workflow",
+      "description": "Prepare a GitHub pull request from a feature branch — branch hygiene, commit shape, title/body, verification notes, screenshots for UI work, and replies to review comments.",
+      "path": "catalog/bundled/software-development/github-pr-workflow",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "engineer"
+      ],
+      "requires": [],
+      "tags": [
+        "github",
+        "pull-requests",
+        "code-review",
+        "release"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 3970,
+          "sha256": "f498ec4ebb1779dea37adeb1db8a8b22316282798e35ee02e2fc5ff627d7e261"
+        }
+      ],
+      "contentHash": "sha256:90f278c89aa0711be150c1cd2456ca25620d02f36995b113ca9837d756a37f6c"
+    },
+    {
+      "id": "paperclipai:optional:browser:agent-browser",
+      "key": "paperclipai/optional/browser/agent-browser",
+      "kind": "optional",
+      "category": "browser",
+      "slug": "agent-browser",
+      "name": "agent-browser",
+      "description": "Drive a real browser to inspect or interact with a web page or app — navigate, take screenshots, read console and network, fill simple forms — for verification tasks, not unattended automation.",
+      "path": "catalog/optional/browser/agent-browser",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "qa",
+        "engineer",
+        "researcher"
+      ],
+      "requires": [],
+      "tags": [
+        "browser",
+        "puppeteer",
+        "playwright",
+        "verification"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 5133,
+          "sha256": "362f7b9d02297782bc6f0c093f495b8a0304a75bcf4b42e5c280a42b1f757b7d"
+        }
+      ],
+      "contentHash": "sha256:eabb2c9f7b5e1a27ebb1e05a711d61433a266478154cd671a685e99e67aadea2"
+    },
+    {
+      "id": "paperclipai:optional:content:release-announcement",
+      "key": "paperclipai/optional/content/release-announcement",
+      "kind": "optional",
+      "category": "content",
+      "slug": "release-announcement",
+      "name": "release-announcement",
+      "description": "Write a release announcement — changelog, blog post, in-app note, or social post — that leads with user impact, names the audience, and includes upgrade/migration steps without filler.",
+      "path": "catalog/optional/content/release-announcement",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "devrel",
+        "product",
+        "writer"
+      ],
+      "requires": [],
+      "tags": [
+        "release",
+        "changelog",
+        "announcement",
+        "communication"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4416,
+          "sha256": "062810ac34e9edc89efa701fec2eee60f16949d1944cc2cae49803cb91e8cbf4"
+        }
+      ],
+      "contentHash": "sha256:f22a9ed696e6614c6db2757a149f48b3295e81f78c27d065d9cb164cf4f8a9bd"
+    },
+    {
+      "id": "paperclipai:optional:product:design-critique",
+      "key": "paperclipai/optional/product/design-critique",
+      "kind": "optional",
+      "category": "product",
+      "slug": "design-critique",
+      "name": "design-critique",
+      "description": "Give a structured product design critique — user job clarity, hierarchy, affordance, error states, accessibility, and consistency — focused on what to change, in what order, and why.",
+      "path": "catalog/optional/product/design-critique",
+      "entrypoint": "SKILL.md",
+      "trustLevel": "markdown_only",
+      "compatibility": "compatible",
+      "defaultInstall": false,
+      "recommendedForRoles": [
+        "designer",
+        "product",
+        "engineer"
+      ],
+      "requires": [],
+      "tags": [
+        "design",
+        "product",
+        "ux",
+        "review"
+      ],
+      "files": [
+        {
+          "path": "SKILL.md",
+          "kind": "skill",
+          "sizeBytes": 4851,
+          "sha256": "022e619baf6cc25725946279cb8052d22af090dd6cd6dc8c20f17867f71a5d8e"
+        }
+      ],
+      "contentHash": "sha256:429f94df398a0697042b5bbe4755b1ff1a230aa5f41d99118ad37493ac65d21c"
+    }
+  ]
+}

packages/skills-catalog/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@paperclipai/skills-catalog",
+  "version": "0.3.1",
+  "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/skills-catalog"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./catalog.json": "./generated/catalog.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/src/index.d.ts",
+        "import": "./dist/src/index.js"
+      },
+      "./types": {
+        "types": "./dist/src/types.d.ts",
+        "import": "./dist/src/types.js"
+      },
+      "./catalog.json": "./dist/generated/catalog.json"
+    },
+    "main": "./dist/src/index.js",
+    "types": "./dist/src/index.d.ts"
+  },
+  "files": [
+    "catalog",
+    "dist",
+    "generated"
+  ],
+  "scripts": {
+    "build": "pnpm run build:manifest && tsc -p tsconfig.json",
+    "build:manifest": "node ../../cli/node_modules/tsx/dist/cli.mjs scripts/build-catalog-manifest.ts",
+    "clean": "rm -rf dist",
+    "test": "pnpm -w exec vitest run --root packages/skills-catalog --config vitest.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate": "node ../../cli/node_modules/tsx/dist/cli.mjs scripts/validate-catalog.ts"
+  }
+}

packages/skills-catalog/scripts/build-catalog-manifest.ts

@@ -0,0 +1,15 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { writeCatalogManifest } from "../src/catalog-builder.js";
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const result = await writeCatalogManifest(packageDir);
+
+if (result.errors.length > 0) {
+  for (const error of result.errors) {
+    console.error(`- ${error}`);
+  }
+  process.exitCode = 1;
+} else {
+  console.log(`Wrote generated/catalog.json with ${result.manifest.skills.length} catalog skills.`);
+}

packages/skills-catalog/scripts/validate-catalog.ts

@@ -0,0 +1,15 @@
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { validateCatalog } from "../src/catalog-builder.js";
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const result = await validateCatalog(packageDir);
+
+if (result.errors.length > 0) {
+  for (const error of result.errors) {
+    console.error(`- ${error}`);
+  }
+  process.exitCode = 1;
+} else {
+  console.log(`Catalog manifest is valid with ${result.manifest.skills.length} catalog skills.`);
+}

packages/skills-catalog/src/catalog-builder.test.ts

@@ -0,0 +1,165 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  buildCatalogManifest,
+  formatCatalogManifest,
+  validateCatalog,
+} from "./catalog-builder.js";
+
+const tempDirs: string[] = [];
+
+describe("skills catalog manifest", () => {
+  afterEach(async () => {
+    await Promise.all(tempDirs.splice(0).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+  });
+
+  it("builds stable manifest entries from catalog skill directories", async () => {
+    const packageDir = await createCatalogPackage();
+    await writeSkill(packageDir, "bundled", "software-development", "github-pr-workflow", {
+      frontmatter: [
+        "name: GitHub PR Workflow",
+        "description: Prepare pull requests and verification notes.",
+        "key: paperclipai/bundled/software-development/github-pr-workflow",
+        "recommendedForRoles:",
+        "  - engineer",
+        "tags:",
+        "  - github",
+        "  - pull-requests",
+      ],
+      files: {
+        "references/checklist.md": "# Checklist\n",
+      },
+    });
+
+    const result = await buildCatalogManifest({
+      packageDir,
+      generatedAt: "2026-05-26T00:00:00.000Z",
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.manifest.skills).toHaveLength(1);
+    expect(result.manifest.skills[0]).toMatchObject({
+      id: "paperclipai:bundled:software-development:github-pr-workflow",
+      key: "paperclipai/bundled/software-development/github-pr-workflow",
+      kind: "bundled",
+      category: "software-development",
+      slug: "github-pr-workflow",
+      name: "GitHub PR Workflow",
+      trustLevel: "markdown_only",
+      compatibility: "compatible",
+      recommendedForRoles: ["engineer"],
+      tags: ["github", "pull-requests"],
+    });
+    expect(result.manifest.skills[0]!.files.map((file) => file.path)).toEqual([
+      "SKILL.md",
+      "references/checklist.md",
+    ]);
+    expect(result.manifest.skills[0]!.contentHash).toMatch(/^sha256:[a-f0-9]{64}$/);
+  });
+
+  it("reports frontmatter, directory, uniqueness, and inventory errors together", async () => {
+    const packageDir = await createCatalogPackage();
+    await writeSkill(packageDir, "bundled", "Bad_Category", "duplicate", {
+      frontmatter: [
+        "name: Duplicate",
+        "key: paperclipai/bundled/software-development/other",
+        "recommendedForRoles: engineer",
+      ],
+    });
+    await writeSkill(packageDir, "optional", "software-development", "duplicate", {
+      frontmatter: [
+        "name: Duplicate Optional",
+        "description: Optional duplicate slug.",
+      ],
+    });
+    await fs.mkdir(path.join(packageDir, "catalog", "bundled", "software-development", "missing-skill"), {
+      recursive: true,
+    });
+    await fs.mkdir(path.join(packageDir, "catalog", "misc"), { recursive: true });
+    await fs.writeFile(path.join(packageDir, "catalog", "misc", "SKILL.md"), "# Misplaced\n", "utf8");
+
+    const result = await buildCatalogManifest({
+      packageDir,
+      generatedAt: "2026-05-26T00:00:00.000Z",
+    });
+
+    expect(result.errors).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("catalog/misc/SKILL.md is not under catalog/<bundled|optional>/<category>/<slug>/SKILL.md"),
+        expect.stringContaining("catalog/bundled/software-development/missing-skill is missing SKILL.md"),
+        expect.stringContaining("has invalid category"),
+        expect.stringContaining("frontmatter must include description"),
+        expect.stringContaining("key must be paperclipai/bundled/Bad_Category/duplicate"),
+        expect.stringContaining("field recommendedForRoles must be an array of strings"),
+        expect.stringContaining("Duplicate catalog slug \"duplicate\""),
+      ]),
+    );
+  });
+
+  it("detects stale generated manifests", async () => {
+    const packageDir = await createCatalogPackage();
+    await writeSkill(packageDir, "bundled", "software-development", "review", {
+      frontmatter: [
+        "name: Review",
+        "description: Review implementation work.",
+      ],
+    });
+    await fs.mkdir(path.join(packageDir, "generated"), { recursive: true });
+    await fs.writeFile(
+      path.join(packageDir, "generated", "catalog.json"),
+      formatCatalogManifest({
+        schemaVersion: 1,
+        packageName: "@paperclipai/skills-catalog",
+        packageVersion: "0.3.1",
+        generatedAt: "2026-05-26T00:00:00.000Z",
+        skills: [],
+      }),
+      "utf8",
+    );
+
+    const result = await validateCatalog(packageDir);
+
+    expect(result.errors).toContain(
+      "generated/catalog.json is stale. Run pnpm --filter @paperclipai/skills-catalog build:manifest.",
+    );
+  });
+});
+
+async function createCatalogPackage() {
+  const packageDir = await fs.mkdtemp(path.join(os.tmpdir(), "skills-catalog-"));
+  tempDirs.push(packageDir);
+  await fs.mkdir(path.join(packageDir, "catalog", "bundled"), { recursive: true });
+  await fs.mkdir(path.join(packageDir, "catalog", "optional"), { recursive: true });
+  await fs.writeFile(
+    path.join(packageDir, "package.json"),
+    JSON.stringify({ version: "0.3.1" }),
+    "utf8",
+  );
+  return packageDir;
+}
+
+async function writeSkill(
+  packageDir: string,
+  kind: "bundled" | "optional",
+  category: string,
+  slug: string,
+  options: {
+    frontmatter: string[];
+    files?: Record<string, string>;
+  },
+) {
+  const skillDir = path.join(packageDir, "catalog", kind, category, slug);
+  await fs.mkdir(skillDir, { recursive: true });
+  await fs.writeFile(
+    path.join(skillDir, "SKILL.md"),
+    `---\n${options.frontmatter.join("\n")}\n---\n\nUse this skill.\n`,
+    "utf8",
+  );
+  for (const [relativePath, content] of Object.entries(options.files ?? {})) {
+    const filePath = path.join(skillDir, relativePath);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, "utf8");
+  }
+}

packages/skills-catalog/src/catalog-builder.ts

@@ -0,0 +1,443 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  asBoolean,
+  asString,
+  asStringArray,
+  parseFrontmatterMarkdown,
+} from "./frontmatter.js";
+import type {
+  CatalogManifest,
+  CatalogSkill,
+  CatalogSkillFile,
+  CatalogSkillFileKind,
+  CatalogSkillKind,
+  CatalogTrustLevel,
+} from "./types.js";
+
+const CATALOG_PACKAGE_NAME = "@paperclipai/skills-catalog";
+const CATALOG_SCHEMA_VERSION = 1;
+const SKILL_ENTRYPOINT = "SKILL.md";
+const MAX_CATALOG_FILE_BYTES = 1024 * 1024;
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CATALOG_KINDS = new Set<CatalogSkillKind>(["bundled", "optional"]);
+
+interface SkillCandidate {
+  kind: CatalogSkillKind;
+  category: string;
+  slug: string;
+  absolutePath: string;
+}
+
+interface BuildCatalogManifestOptions {
+  packageDir: string;
+  generatedAt?: string;
+}
+
+interface BuildCatalogManifestResult {
+  manifest: CatalogManifest;
+  errors: string[];
+}
+
+export function formatCatalogManifest(manifest: CatalogManifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+export async function buildExpectedCatalogManifest(
+  packageDir: string,
+): Promise<BuildCatalogManifestResult> {
+  const existing = await readExistingManifest(packageDir);
+  const firstPass = await buildCatalogManifest({
+    packageDir,
+    generatedAt: existing?.generatedAt ?? new Date().toISOString(),
+  });
+
+  if (existing && sameManifestExceptGeneratedAt(existing, firstPass.manifest)) {
+    return firstPass;
+  }
+
+  return buildCatalogManifest({
+    packageDir,
+    generatedAt: new Date().toISOString(),
+  });
+}
+
+export async function buildCatalogManifest(
+  options: BuildCatalogManifestOptions,
+): Promise<BuildCatalogManifestResult> {
+  const packageDir = path.resolve(options.packageDir);
+  const packageJson = await readPackageJson(packageDir);
+  const errors: string[] = [];
+  const candidates = await discoverSkillCandidates(packageDir, errors);
+  const skills: CatalogSkill[] = [];
+
+  collectCandidateUniquenessErrors(candidates, errors);
+
+  for (const candidate of candidates) {
+    const skill = await buildCatalogSkill(packageDir, candidate, errors);
+    if (skill) skills.push(skill);
+  }
+
+  skills.sort((a, b) => a.id.localeCompare(b.id));
+  collectUniquenessErrors(skills, errors);
+
+  return {
+    manifest: {
+      schemaVersion: CATALOG_SCHEMA_VERSION,
+      packageName: CATALOG_PACKAGE_NAME,
+      packageVersion: packageJson.version,
+      generatedAt: options.generatedAt ?? new Date().toISOString(),
+      skills,
+    },
+    errors,
+  };
+}
+
+export async function validateCatalog(packageDir: string): Promise<BuildCatalogManifestResult> {
+  const expected = await buildExpectedCatalogManifest(packageDir);
+  const generatedPath = path.join(packageDir, "generated", "catalog.json");
+  const errors = [...expected.errors];
+
+  let generatedText: string | null = null;
+  try {
+    generatedText = await fs.readFile(generatedPath, "utf8");
+    JSON.parse(generatedText);
+  } catch (error) {
+    errors.push(`generated/catalog.json is missing or invalid: ${errorMessage(error)}`);
+  }
+
+  if (generatedText !== null) {
+    const expectedText = formatCatalogManifest(expected.manifest);
+    if (generatedText !== expectedText) {
+      errors.push("generated/catalog.json is stale. Run pnpm --filter @paperclipai/skills-catalog build:manifest.");
+    }
+  }
+
+  return {
+    manifest: expected.manifest,
+    errors,
+  };
+}
+
+export async function writeCatalogManifest(packageDir: string) {
+  const result = await buildExpectedCatalogManifest(packageDir);
+  if (result.errors.length > 0) return result;
+
+  const generatedDir = path.join(packageDir, "generated");
+  await fs.mkdir(generatedDir, { recursive: true });
+  await fs.writeFile(path.join(generatedDir, "catalog.json"), formatCatalogManifest(result.manifest), "utf8");
+  return result;
+}
+
+async function readPackageJson(packageDir: string) {
+  const packageJsonPath = path.join(packageDir, "package.json");
+  const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8")) as { version?: unknown };
+  const version = asString(packageJson.version);
+  if (!version) throw new Error(`${packageJsonPath} must declare a package version.`);
+  return { version };
+}
+
+async function readExistingManifest(packageDir: string): Promise<CatalogManifest | null> {
+  try {
+    return JSON.parse(await fs.readFile(path.join(packageDir, "generated", "catalog.json"), "utf8")) as CatalogManifest;
+  } catch {
+    return null;
+  }
+}
+
+async function discoverSkillCandidates(packageDir: string, errors: string[]) {
+  const catalogDir = path.join(packageDir, "catalog");
+  const candidates: SkillCandidate[] = [];
+
+  if (!existsSync(catalogDir)) {
+    errors.push("catalog directory is missing.");
+    return candidates;
+  }
+
+  await collectMisplacedSkillFiles(catalogDir, errors);
+
+  for (const kind of ["bundled", "optional"] as const) {
+    const kindDir = path.join(catalogDir, kind);
+    if (!existsSync(kindDir)) continue;
+
+    for (const categoryEntry of await sortedDirEntries(kindDir)) {
+      if (!categoryEntry.isDirectory()) continue;
+      const category = categoryEntry.name;
+      const categoryDir = path.join(kindDir, category);
+
+      for (const slugEntry of await sortedDirEntries(categoryDir)) {
+        if (!slugEntry.isDirectory()) continue;
+        const slug = slugEntry.name;
+        const skillDir = path.join(categoryDir, slug);
+        if (!existsSync(path.join(skillDir, SKILL_ENTRYPOINT))) {
+          errors.push(`${relativePackagePath(packageDir, skillDir)} is missing SKILL.md.`);
+          continue;
+        }
+        candidates.push({ kind, category, slug, absolutePath: skillDir });
+      }
+    }
+  }
+
+  return candidates;
+}
+
+async function collectMisplacedSkillFiles(catalogDir: string, errors: string[]) {
+  async function visit(dir: string) {
+    for (const entry of await sortedDirEntries(dir)) {
+      const absolutePath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await visit(absolutePath);
+        continue;
+      }
+      if (entry.name !== SKILL_ENTRYPOINT) continue;
+
+      const relativePath = toPosixPath(path.relative(catalogDir, absolutePath));
+      const parts = relativePath.split("/");
+      const kind = parts[0];
+      if (parts.length !== 4 || !CATALOG_KINDS.has(kind as CatalogSkillKind)) {
+        errors.push(`catalog/${relativePath} is not under catalog/<bundled|optional>/<category>/<slug>/SKILL.md.`);
+      }
+    }
+  }
+
+  await visit(catalogDir);
+}
+
+async function buildCatalogSkill(
+  packageDir: string,
+  candidate: SkillCandidate,
+  errors: string[],
+): Promise<CatalogSkill | null> {
+  const prefix = relativePackagePath(packageDir, candidate.absolutePath);
+  validateSlug("category", candidate.category, prefix, errors);
+  validateSlug("slug", candidate.slug, prefix, errors);
+
+  const id = `paperclipai:${candidate.kind}:${candidate.category}:${candidate.slug}`;
+  const key = `paperclipai/${candidate.kind}/${candidate.category}/${candidate.slug}`;
+  const skillMarkdownPath = path.join(candidate.absolutePath, SKILL_ENTRYPOINT);
+  const parsed = parseFrontmatterMarkdown(await fs.readFile(skillMarkdownPath, "utf8"));
+
+  if (!parsed.hasFrontmatter) {
+    errors.push(`${prefix}/SKILL.md must start with YAML frontmatter.`);
+  }
+
+  const name = asString(parsed.frontmatter.name);
+  if (!name) errors.push(`${prefix}/SKILL.md frontmatter must include name.`);
+
+  const description = asString(parsed.frontmatter.description);
+  if (!description) errors.push(`${prefix}/SKILL.md frontmatter must include description.`);
+
+  const explicitKey = asString(parsed.frontmatter.key);
+  if (explicitKey && explicitKey !== key) {
+    errors.push(`${prefix}/SKILL.md key must be ${key}.`);
+  }
+
+  const explicitSlug = asString(parsed.frontmatter.slug);
+  if (explicitSlug && explicitSlug !== candidate.slug) {
+    errors.push(`${prefix}/SKILL.md slug must be ${candidate.slug}.`);
+  }
+
+  const defaultInstall = asBoolean(parsed.frontmatter.defaultInstall) ?? false;
+  const recommendedForRoles = readStringArrayField(parsed.frontmatter.recommendedForRoles, "recommendedForRoles", prefix, errors);
+  const requires = readStringArrayField(parsed.frontmatter.requires, "requires", prefix, errors);
+  const tags = readStringArrayField(parsed.frontmatter.tags, "tags", prefix, errors);
+  const files = await collectSkillFiles(packageDir, candidate.absolutePath, prefix, errors);
+
+  if (!name || !description) return null;
+
+  return {
+    id,
+    key,
+    kind: candidate.kind,
+    category: candidate.category,
+    slug: candidate.slug,
+    name,
+    description,
+    path: toPosixPath(path.relative(packageDir, candidate.absolutePath)),
+    entrypoint: SKILL_ENTRYPOINT,
+    trustLevel: deriveTrustLevel(files),
+    compatibility: "compatible",
+    defaultInstall,
+    recommendedForRoles,
+    requires,
+    tags,
+    files,
+    contentHash: buildContentHash(files),
+  };
+}
+
+async function collectSkillFiles(
+  packageDir: string,
+  skillDir: string,
+  prefix: string,
+  errors: string[],
+): Promise<CatalogSkillFile[]> {
+  const files: CatalogSkillFile[] = [];
+  const skillRoot = await fs.realpath(skillDir);
+
+  async function visit(dir: string) {
+    for (const entry of await sortedDirEntries(dir)) {
+      const absolutePath = path.join(dir, entry.name);
+      const lstat = await fs.lstat(absolutePath);
+      let stat = lstat;
+      let realPath = absolutePath;
+
+      if (lstat.isSymbolicLink()) {
+        try {
+          realPath = await fs.realpath(absolutePath);
+          stat = await fs.stat(absolutePath);
+        } catch {
+          errors.push(`${relativePackagePath(packageDir, absolutePath)} is a broken symlink.`);
+          continue;
+        }
+        if (!isPathInside(skillRoot, realPath)) {
+          errors.push(`${relativePackagePath(packageDir, absolutePath)} points outside its skill directory.`);
+          continue;
+        }
+        if (stat.isDirectory()) {
+          errors.push(`${relativePackagePath(packageDir, absolutePath)} is a directory symlink; copy files into the skill directory instead.`);
+          continue;
+        }
+      }
+
+      if (stat.isDirectory()) {
+        await visit(absolutePath);
+        continue;
+      }
+      if (!stat.isFile()) continue;
+
+      const relativePath = toPosixPath(path.relative(skillDir, absolutePath));
+      if (path.isAbsolute(relativePath) || relativePath.split("/").includes("..")) {
+        errors.push(`${prefix}/${relativePath} has an invalid inventory path.`);
+        continue;
+      }
+      if (stat.size > MAX_CATALOG_FILE_BYTES) {
+        errors.push(`${prefix}/${relativePath} exceeds ${MAX_CATALOG_FILE_BYTES} bytes.`);
+      }
+
+      const contents = await fs.readFile(absolutePath);
+      files.push({
+        path: relativePath,
+        kind: classifyCatalogFile(relativePath),
+        sizeBytes: stat.size,
+        sha256: sha256(contents),
+      });
+    }
+  }
+
+  await visit(skillDir);
+  files.sort((a, b) => {
+    if (a.path === SKILL_ENTRYPOINT) return -1;
+    if (b.path === SKILL_ENTRYPOINT) return 1;
+    return a.path.localeCompare(b.path);
+  });
+
+  if (!files.some((file) => file.path === SKILL_ENTRYPOINT && file.kind === "skill")) {
+    errors.push(`${prefix} inventory does not contain SKILL.md.`);
+  }
+
+  return files;
+}
+
+function readStringArrayField(
+  value: unknown,
+  field: string,
+  prefix: string,
+  errors: string[],
+) {
+  const parsed = asStringArray(value);
+  if (!parsed) {
+    errors.push(`${prefix}/SKILL.md frontmatter field ${field} must be an array of strings.`);
+    return [];
+  }
+  return parsed;
+}
+
+function classifyCatalogFile(relativePath: string): CatalogSkillFileKind {
+  if (relativePath === SKILL_ENTRYPOINT) return "skill";
+  if (relativePath.startsWith("references/")) return "reference";
+  if (relativePath.startsWith("scripts/")) return "script";
+  if (relativePath.startsWith("assets/")) return "asset";
+  if (relativePath.endsWith(".md") || relativePath.endsWith(".mdx")) return "markdown";
+  return "other";
+}
+
+function deriveTrustLevel(files: CatalogSkillFile[]): CatalogTrustLevel {
+  if (files.some((file) => file.kind === "script")) return "scripts_executables";
+  if (files.some((file) => file.kind === "asset" || file.kind === "other")) return "assets";
+  return "markdown_only";
+}
+
+function buildContentHash(files: CatalogSkillFile[]) {
+  const hashInput = files.map((file) => ({
+    path: file.path,
+    sha256: file.sha256,
+  }));
+  return `sha256:${sha256(Buffer.from(JSON.stringify(hashInput)))}`;
+}
+
+function collectUniquenessErrors(skills: CatalogSkill[], errors: string[]) {
+  collectDuplicateErrors(skills, "id", errors);
+  collectDuplicateErrors(skills, "key", errors);
+  collectDuplicateErrors(skills, "slug", errors);
+}
+
+function collectCandidateUniquenessErrors(candidates: SkillCandidate[], errors: string[]) {
+  const projected = candidates.map((candidate) => ({
+    id: `paperclipai:${candidate.kind}:${candidate.category}:${candidate.slug}`,
+    key: `paperclipai/${candidate.kind}/${candidate.category}/${candidate.slug}`,
+    slug: candidate.slug,
+    path: toPosixPath(path.join("catalog", candidate.kind, candidate.category, candidate.slug)),
+  })) as CatalogSkill[];
+  collectUniquenessErrors(projected, errors);
+}
+
+function collectDuplicateErrors(fieldSkills: CatalogSkill[], field: "id" | "key" | "slug", errors: string[]) {
+  const seen = new Map<string, string>();
+  for (const skill of fieldSkills) {
+    const value = skill[field];
+    const first = seen.get(value);
+    if (first) {
+      errors.push(`Duplicate catalog ${field} "${value}" in ${first} and ${skill.path}.`);
+      continue;
+    }
+    seen.set(value, skill.path);
+  }
+}
+
+function validateSlug(label: string, value: string, prefix: string, errors: string[]) {
+  if (!SLUG_PATTERN.test(value)) {
+    errors.push(`${prefix} has invalid ${label} "${value}"; use lowercase URL slugs.`);
+  }
+}
+
+async function sortedDirEntries(dir: string) {
+  return (await fs.readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function sameManifestExceptGeneratedAt(a: CatalogManifest, b: CatalogManifest) {
+  return JSON.stringify({ ...a, generatedAt: "" }) === JSON.stringify({ ...b, generatedAt: "" });
+}
+
+function sha256(contents: Buffer) {
+  return createHash("sha256").update(contents).digest("hex");
+}
+
+function relativePackagePath(packageDir: string, absolutePath: string) {
+  return toPosixPath(path.relative(packageDir, absolutePath));
+}
+
+function toPosixPath(input: string) {
+  return input.split(path.sep).join("/");
+}
+
+function isPathInside(parent: string, child: string) {
+  const relativePath = path.relative(parent, child);
+  return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+
+function errorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}

packages/skills-catalog/src/frontmatter.ts

@@ -0,0 +1,154 @@
+export interface MarkdownDoc {
+  frontmatter: Record<string, unknown>;
+  body: string;
+  hasFrontmatter: boolean;
+}
+
+export function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function asString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function asBoolean(value: unknown): boolean | null {
+  return typeof value === "boolean" ? value : null;
+}
+
+export function asStringArray(value: unknown): string[] | null {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return null;
+
+  const out: string[] = [];
+  for (const item of value) {
+    const text = asString(item);
+    if (!text) return null;
+    out.push(text);
+  }
+  return out;
+}
+
+export function parseFrontmatterMarkdown(raw: string): MarkdownDoc {
+  const normalized = raw.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return { frontmatter: {}, body: normalized.trim(), hasFrontmatter: false };
+  }
+
+  const closing = normalized.indexOf("\n---\n", 4);
+  if (closing < 0) {
+    return { frontmatter: {}, body: normalized.trim(), hasFrontmatter: false };
+  }
+
+  const frontmatterRaw = normalized.slice(4, closing).trim();
+  const body = normalized.slice(closing + 5).trim();
+  return {
+    frontmatter: parseYamlFrontmatter(frontmatterRaw),
+    body,
+    hasFrontmatter: true,
+  };
+}
+
+function parseYamlFrontmatter(raw: string): Record<string, unknown> {
+  const prepared = prepareYamlLines(raw);
+  if (prepared.length === 0) return {};
+  const parsed = parseYamlBlock(prepared, 0, prepared[0]!.indent);
+  return isPlainRecord(parsed.value) ? parsed.value : {};
+}
+
+function prepareYamlLines(raw: string) {
+  return raw
+    .split("\n")
+    .map((line) => ({
+      indent: line.match(/^ */)?.[0].length ?? 0,
+      content: line.trim(),
+    }))
+    .filter((line) => line.content.length > 0 && !line.content.startsWith("#"));
+}
+
+function parseYamlBlock(
+  lines: Array<{ indent: number; content: string }>,
+  startIndex: number,
+  indentLevel: number,
+): { value: unknown; nextIndex: number } {
+  let index = startIndex;
+  if (index >= lines.length || lines[index]!.indent < indentLevel) {
+    return { value: {}, nextIndex: index };
+  }
+
+  const isArray = lines[index]!.indent === indentLevel && lines[index]!.content.startsWith("-");
+  if (isArray) {
+    const values: unknown[] = [];
+    while (index < lines.length) {
+      const line = lines[index]!;
+      if (line.indent < indentLevel) break;
+      if (line.indent !== indentLevel || !line.content.startsWith("-")) break;
+
+      const remainder = line.content.slice(1).trim();
+      index += 1;
+      if (!remainder) {
+        const nested = parseYamlBlock(lines, index, indentLevel + 2);
+        values.push(nested.value);
+        index = nested.nextIndex;
+        continue;
+      }
+
+      values.push(parseYamlScalar(remainder));
+    }
+    return { value: values, nextIndex: index };
+  }
+
+  const record: Record<string, unknown> = {};
+  while (index < lines.length) {
+    const line = lines[index]!;
+    if (line.indent < indentLevel) break;
+    if (line.indent !== indentLevel) {
+      index += 1;
+      continue;
+    }
+
+    const separatorIndex = line.content.indexOf(":");
+    if (separatorIndex <= 0) {
+      index += 1;
+      continue;
+    }
+
+    const key = line.content.slice(0, separatorIndex).trim();
+    const remainder = line.content.slice(separatorIndex + 1).trim();
+    index += 1;
+    if (!remainder) {
+      const nested = parseYamlBlock(lines, index, indentLevel + 2);
+      record[key] = nested.value;
+      index = nested.nextIndex;
+      continue;
+    }
+    record[key] = parseYamlScalar(remainder);
+  }
+
+  return { value: record, nextIndex: index };
+}
+
+function parseYamlScalar(rawValue: string): unknown {
+  const trimmed = rawValue.trim();
+  if (trimmed === "") return "";
+  if (trimmed === "null" || trimmed === "~") return null;
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "[]") return [];
+  if (trimmed === "{}") return {};
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  if (
+    trimmed.startsWith("\"") ||
+    trimmed.startsWith("[") ||
+    trimmed.startsWith("{")
+  ) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return trimmed;
+    }
+  }
+  return trimmed;
+}

packages/skills-catalog/src/index.ts

@@ -0,0 +1,37 @@
+import catalogManifestJson from "../generated/catalog.json" with { type: "json" };
+import type { CatalogManifest, CatalogSkill } from "./types.js";
+
+export type {
+  CatalogCompatibility,
+  CatalogManifest,
+  CatalogSkill,
+  CatalogSkillFile,
+  CatalogSkillFileKind,
+  CatalogSkillKind,
+  CatalogTrustLevel,
+  CatalogValidationResult,
+} from "./types.js";
+
+export const catalogManifest = catalogManifestJson as CatalogManifest;
+
+export const catalogSkills: CatalogSkill[] = catalogManifest.skills;
+
+const skillsById = new Map(catalogSkills.map((skill) => [skill.id, skill]));
+const skillsByKey = new Map(catalogSkills.map((skill) => [skill.key, skill]));
+
+export function getCatalogSkill(id: string): CatalogSkill | null {
+  return skillsById.get(id) ?? null;
+}
+
+export function resolveCatalogSkillRef(ref: string): CatalogSkill | null {
+  const normalized = ref.trim();
+  if (normalized.length === 0) return null;
+
+  const exactMatch = skillsById.get(normalized) ?? skillsByKey.get(normalized);
+  if (exactMatch) return exactMatch;
+
+  const slugMatches = catalogSkills.filter((skill) => skill.slug === normalized);
+  if (slugMatches.length === 1) return slugMatches[0]!;
+
+  return null;
+}

packages/skills-catalog/src/shipped-catalog.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { catalogManifest, catalogSkills, resolveCatalogSkillRef } from "./index.js";
+import type { CatalogSkill } from "./types.js";
+
+const EXPECTED_BUNDLED_KEYS = [
+  "paperclipai/bundled/docs/doc-maintenance",
+  "paperclipai/bundled/paperclip-operations/issue-triage",
+  "paperclipai/bundled/paperclip-operations/task-planning",
+  "paperclipai/bundled/quality/qa-acceptance",
+  "paperclipai/bundled/software-development/github-pr-workflow",
+];
+
+const EXPECTED_OPTIONAL_KEYS = [
+  "paperclipai/optional/browser/agent-browser",
+  "paperclipai/optional/content/release-announcement",
+  "paperclipai/optional/product/design-critique",
+];
+
+describe("shipped skills catalog", () => {
+  it("ships the expected bundled and optional skill set", () => {
+    const bundledKeys = catalogSkills
+      .filter((skill) => skill.kind === "bundled")
+      .map((skill) => skill.key)
+      .sort();
+    const optionalKeys = catalogSkills
+      .filter((skill) => skill.kind === "optional")
+      .map((skill) => skill.key)
+      .sort();
+
+    expect(bundledKeys).toEqual(EXPECTED_BUNDLED_KEYS);
+    expect(optionalKeys).toEqual(EXPECTED_OPTIONAL_KEYS);
+  });
+
+  it("keeps every shipped skill markdown-only until a script-bearing skill clears security review", () => {
+    const scriptBearing = catalogSkills.filter((skill) => skill.trustLevel !== "markdown_only");
+    expect(scriptBearing, formatViolations("script-bearing skills require security review", scriptBearing)).toEqual([]);
+  });
+
+  it("populates browse/search-relevant fields for every shipped skill", () => {
+    const issues: string[] = [];
+    for (const skill of catalogSkills) {
+      if (skill.compatibility !== "compatible") {
+        issues.push(`${skill.key} compatibility=${skill.compatibility}`);
+      }
+      if (!skill.description || skill.description.length < 40) {
+        issues.push(`${skill.key} description must be at least 40 characters for catalog browse/search`);
+      }
+      if (skill.recommendedForRoles.length === 0) {
+        issues.push(`${skill.key} must list recommendedForRoles`);
+      }
+      if (skill.tags.length === 0) {
+        issues.push(`${skill.key} must list tags`);
+      }
+    }
+    expect(issues).toEqual([]);
+  });
+
+  it("uses canonical paperclipai keys derived from kind/category/slug", () => {
+    const violations: string[] = [];
+    for (const skill of catalogSkills) {
+      const expectedKey = `paperclipai/${skill.kind}/${skill.category}/${skill.slug}`;
+      const expectedId = `paperclipai:${skill.kind}:${skill.category}:${skill.slug}`;
+      if (skill.key !== expectedKey) violations.push(`${skill.key} should be ${expectedKey}`);
+      if (skill.id !== expectedId) violations.push(`${skill.id} should be ${expectedId}`);
+    }
+    expect(violations).toEqual([]);
+  });
+
+  it("exposes a stable manifest header for downstream consumers", () => {
+    expect(catalogManifest.schemaVersion).toBe(1);
+    expect(catalogManifest.packageName).toBe("@paperclipai/skills-catalog");
+    expect(catalogSkills.length).toBe(EXPECTED_BUNDLED_KEYS.length + EXPECTED_OPTIONAL_KEYS.length);
+  });
+
+  it("resolves shipped skills by id, key, and unique slug", () => {
+    const sample = catalogSkills.find((skill) => skill.key === "paperclipai/bundled/software-development/github-pr-workflow");
+    expect(sample, "expected github-pr-workflow to ship in the bundled catalog").toBeDefined();
+    if (!sample) return;
+
+    expect(resolveCatalogSkillRef(sample.id)).toMatchObject({ key: sample.key });
+    expect(resolveCatalogSkillRef(sample.key)).toMatchObject({ key: sample.key });
+    expect(resolveCatalogSkillRef(sample.slug)).toMatchObject({ key: sample.key });
+  });
+});
+
+function formatViolations(label: string, skills: CatalogSkill[]) {
+  if (skills.length === 0) return label;
+  const detail = skills.map((skill) => `${skill.key} (${skill.trustLevel})`).join(", ");
+  return `${label}: ${detail}`;
+}

packages/skills-catalog/src/types.ts

@@ -0,0 +1,48 @@
+export type CatalogSkillKind = "bundled" | "optional";
+
+export type CatalogTrustLevel = "markdown_only" | "assets" | "scripts_executables";
+
+export type CatalogCompatibility = "compatible" | "unknown" | "invalid";
+
+export type CatalogSkillFileKind = "skill" | "markdown" | "reference" | "script" | "asset" | "other";
+
+export interface CatalogSkillFile {
+  path: string;
+  kind: CatalogSkillFileKind;
+  sizeBytes: number;
+  sha256: string;
+}
+
+export interface CatalogSkill {
+  id: string;
+  key: string;
+  kind: CatalogSkillKind;
+  category: string;
+  slug: string;
+  name: string;
+  description: string;
+  path: string;
+  entrypoint: "SKILL.md";
+  trustLevel: CatalogTrustLevel;
+  compatibility: CatalogCompatibility;
+  defaultInstall: boolean;
+  recommendedForRoles: string[];
+  requires: string[];
+  tags: string[];
+  files: CatalogSkillFile[];
+  contentHash: string;
+}
+
+export interface CatalogManifest {
+  schemaVersion: 1;
+  packageName: "@paperclipai/skills-catalog";
+  packageVersion: string;
+  generatedAt: string;
+  skills: CatalogSkill[];
+}
+
+export interface CatalogValidationResult {
+  valid: boolean;
+  errors: string[];
+  manifest: CatalogManifest;
+}

packages/skills-catalog/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": ["generated/**/*.json", "scripts/**/*.ts", "src/**/*.ts"]
+}

packages/skills-catalog/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});