From 90062af85f8ae600bb24179d8655129c0eeb9f88 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Sat, 9 May 2026 21:35:17 -0500
Subject: [PATCH] Add LLM Wiki host support

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 Dockerfile                                    |   1 +
 cli/src/__tests__/home-paths.test.ts          |  11 +-
 cli/src/__tests__/onboard.test.ts             |  39 ++
 cli/src/__tests__/spaces.test.ts              | 218 +++++++++
 cli/src/commands/configure.ts                 |   4 +
 cli/src/commands/onboard.ts                   |   7 +-
 cli/src/commands/spaces.ts                    | 269 +++++++++++
 cli/src/config/home.ts                        |  73 +--
 cli/src/index.ts                              |   2 +
 doc/CLI.md                                    |  78 +++-
 doc/DATABASE.md                               |  10 +-
 doc/DEVELOPING.md                             |  55 ++-
 doc/SPEC-implementation.md                    |   6 +-
 ...-llm-wiki-paperclip-asset-security-gate.md | 135 ++++++
 packages/adapter-utils/src/server-utils.ts    | 118 ++++-
 .../adapters/acpx-local/src/server/execute.ts |   7 +-
 .../claude-local/src/server/claude-config.ts  |  14 +-
 .../claude-local/src/server/prompt-cache.ts   |  21 +-
 .../codex-local/src/server/codex-home.ts      |  14 +-
 packages/db/src/backup.ts                     |  36 +-
 packages/db/src/runtime-config.test.ts        |  20 +
 packages/db/src/runtime-config.ts             |  47 +-
 .../plugin-bookmarks-example/.gitignore       |   3 +
 .../plugin-bookmarks-example/README.md        |  53 +++
 .../esbuild.config.mjs                        |  17 +
 .../migrations/001_bookmarks.sql              |  16 +
 .../plugin-bookmarks-example/package.json     |  48 ++
 .../rollup.config.mjs                         |  28 ++
 .../plugin-bookmarks-example/src/manifest.ts  | 102 +++++
 .../plugin-bookmarks-example/src/ui/index.tsx | 359 +++++++++++++++
 .../plugin-bookmarks-example/src/worker.ts    | 421 ++++++++++++++++++
 .../tests/plugin.spec.ts                      | 370 +++++++++++++++
 .../plugin-bookmarks-example/tsconfig.json    |  27 ++
 .../plugin-bookmarks-example/vitest.config.ts |   8 +
 .../plugins/sdk/src/host-client-factory.ts    |  26 ++
 packages/plugins/sdk/src/index.ts             |   5 +
 packages/plugins/sdk/src/protocol.ts          |  20 +-
 packages/plugins/sdk/src/testing.ts           | 142 +++++-
 packages/plugins/sdk/src/types.ts             |  28 +-
 packages/plugins/sdk/src/worker-rpc-host.ts   |  20 +-
 packages/shared/src/config-schema.ts          |  20 +-
 packages/shared/src/constants.ts              |   1 +
 packages/shared/src/index.ts                  |   3 +
 packages/shared/src/space-paths.test.ts       |  74 +++
 packages/shared/src/space-paths.ts            | 247 ++++++++++
 packages/shared/src/types/index.ts            |   3 +
 packages/shared/src/types/plugin.ts           |  49 +-
 packages/shared/src/validators/index.ts       |   4 +
 packages/shared/src/validators/plugin.test.ts |  37 +-
 packages/shared/src/validators/plugin.ts      |  61 ++-
 pnpm-workspace.yaml                           |   3 +
 .../__tests__/plugin-managed-skills.test.ts   | 262 +++++++++++
 server/src/home-paths.ts                      |  69 ++-
 server/src/routes/plugins.ts                  |   8 +
 server/src/services/agent-instructions.ts     |   4 +-
 server/src/services/company-skills.ts         |   4 +-
 server/src/services/feedback.ts               |   4 +-
 server/src/services/plugin-host-services.ts   |  36 ++
 server/src/services/plugin-local-folders.ts   |  48 ++
 server/src/services/plugin-managed-agents.ts  |  74 ++-
 server/src/services/plugin-managed-skills.ts  | 342 ++++++++++++++
 server/src/services/run-log-store.ts          |   4 +-
 .../services/workspace-operation-log-store.ts |   4 +-
 63 files changed, 4003 insertions(+), 236 deletions(-)
 create mode 100644 cli/src/__tests__/spaces.test.ts
 create mode 100644 cli/src/commands/spaces.ts
 create mode 100644 doc/plans/2026-05-06-llm-wiki-paperclip-asset-security-gate.md
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/.gitignore
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/README.md
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/esbuild.config.mjs
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/migrations/001_bookmarks.sql
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/package.json
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/rollup.config.mjs
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/src/manifest.ts
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/src/ui/index.tsx
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/src/worker.ts
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/tests/plugin.spec.ts
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/tsconfig.json
 create mode 100644 packages/plugins/examples/plugin-bookmarks-example/vitest.config.ts
 create mode 100644 packages/shared/src/space-paths.test.ts
 create mode 100644 packages/shared/src/space-paths.ts
 create mode 100644 server/src/__tests__/plugin-managed-skills.test.ts
 create mode 100644 server/src/services/plugin-managed-skills.ts

diff --git a/Dockerfile b/Dockerfile
index 6fa685d935f..ec82a186f03 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -31,6 +31,7 @@ COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-
 COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/
 COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/
 COPY packages/plugins/sdk/package.json packages/plugins/sdk/
+COPY packages/plugins/plugin-llm-wiki/package.json packages/plugins/plugin-llm-wiki/
 COPY --parents packages/plugins/sandbox-providers/./*/package.json packages/plugins/sandbox-providers/
 COPY packages/plugins/paperclip-plugin-fake-sandbox/package.json packages/plugins/paperclip-plugin-fake-sandbox/
 COPY patches/ patches/
diff --git a/cli/src/__tests__/home-paths.test.ts b/cli/src/__tests__/home-paths.test.ts
index 1d9c654eeef..53ae028a4aa 100644
--- a/cli/src/__tests__/home-paths.test.ts
+++ b/cli/src/__tests__/home-paths.test.ts
@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
@@ -16,13 +17,15 @@ describe("home path resolution", () => {
   });
 
   it("defaults to ~/.paperclip and default instance", () => {
-    delete process.env.PAPERCLIP_HOME;
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-home-paths-"));
+    process.env.PAPERCLIP_HOME = home;
     delete process.env.PAPERCLIP_INSTANCE_ID;
 
     const paths = describeLocalInstancePaths();
-    expect(paths.homeDir).toBe(path.resolve(os.homedir(), ".paperclip"));
+    expect(paths.homeDir).toBe(home);
     expect(paths.instanceId).toBe("default");
-    expect(paths.configPath).toBe(path.resolve(os.homedir(), ".paperclip", "instances", "default", "config.json"));
+    expect(paths.activeSpaceId).toBe("default");
+    expect(paths.configPath).toBe(path.resolve(home, "instances", "default", "spaces", "default", "config.json"));
   });
 
   it("supports PAPERCLIP_HOME and explicit instance ids", () => {
@@ -34,7 +37,7 @@ describe("home path resolution", () => {
   });
 
   it("rejects invalid instance ids", () => {
-    expect(() => resolvePaperclipInstanceId("bad/id")).toThrow(/Invalid instance id/);
+    expect(() => resolvePaperclipInstanceId("bad/id")).toThrow(/Invalid PAPERCLIP_INSTANCE_ID/);
   });
 
   it("expands ~ prefixes", () => {
diff --git a/cli/src/__tests__/onboard.test.ts b/cli/src/__tests__/onboard.test.ts
index b66c20fa8c1..851d476e17c 100644
--- a/cli/src/__tests__/onboard.test.ts
+++ b/cli/src/__tests__/onboard.test.ts
@@ -6,6 +6,7 @@ import { onboard } from "../commands/onboard.js";
 import type { PaperclipConfig } from "../config/schema.js";
 
 const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_CWD = process.cwd();
 
 function createExistingConfigFixture() {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-"));
@@ -85,10 +86,19 @@ describe("onboard", () => {
     delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
     delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
     delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+    delete process.env.PAPERCLIP_HOME;
+    delete process.env.PAPERCLIP_CONFIG;
+    delete process.env.PAPERCLIP_INSTANCE_ID;
+    delete process.env.PAPERCLIP_SPACE_ID;
+    delete process.env.PAPERCLIP_BIND;
+    delete process.env.PAPERCLIP_BIND_HOST;
+    delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+    delete process.env.HOST;
   });
 
   afterEach(() => {
     process.env = { ...ORIGINAL_ENV };
+    process.chdir(ORIGINAL_CWD);
   });
 
   it("preserves an existing config when rerun without flags", async () => {
@@ -125,6 +135,35 @@ describe("onboard", () => {
     expect(raw.server.host).toBe("127.0.0.1");
   });
 
+  it("creates default-space config and data paths for a fresh PAPERCLIP_HOME", async () => {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-space-"));
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-cwd-"));
+    process.chdir(cwd);
+    process.env.PAPERCLIP_HOME = home;
+
+    await onboard({ yes: true, invokedByRun: true });
+
+    const instanceRoot = path.join(home, "instances", "default");
+    const spaceRoot = path.join(instanceRoot, "spaces", "default");
+    const configPath = path.join(spaceRoot, "config.json");
+    const registryPath = path.join(instanceRoot, "config.json");
+    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
+    const registry = JSON.parse(fs.readFileSync(registryPath, "utf8")) as { activeSpaceId?: string };
+
+    expect(registry.activeSpaceId).toBe("default");
+    expect(raw.database.embeddedPostgresDataDir).toBe(path.join(spaceRoot, "db"));
+    expect(raw.database.backup.dir).toBe(path.join(spaceRoot, "data", "backups"));
+    expect(raw.logging.logDir).toBe(path.join(spaceRoot, "logs"));
+    expect(raw.storage.localDisk.baseDir).toBe(path.join(spaceRoot, "data", "storage"));
+    expect(raw.secrets.localEncrypted.keyFilePath).toBe(path.join(spaceRoot, "secrets", "master.key"));
+    expect(fs.existsSync(path.join(spaceRoot, ".env"))).toBe(true);
+    expect(fs.existsSync(path.join(spaceRoot, "secrets", "master.key"))).toBe(true);
+
+    for (const rootName of ["db", "data", "secrets", "logs", "workspaces", "projects", "companies"]) {
+      expect(fs.existsSync(path.join(instanceRoot, rootName))).toBe(false);
+    }
+  });
+
   it("supports authenticated/private quickstart bind presets", async () => {
     const configPath = createFreshConfigPath();
     process.env.PAPERCLIP_TAILNET_BIND_HOST = "100.64.0.8";
diff --git a/cli/src/__tests__/spaces.test.ts b/cli/src/__tests__/spaces.test.ts
new file mode 100644
index 00000000000..7cb200aed4a
--- /dev/null
+++ b/cli/src/__tests__/spaces.test.ts
@@ -0,0 +1,218 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { defaultServerRunningCheck, migrateDefaultSpaceInstall } from "../commands/spaces.js";
+import { readConfig, resolveConfigPath } from "../config/store.js";
+import type { PaperclipConfig } from "../config/schema.js";
+
+const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_CWD = process.cwd();
+
+function writeJson(filePath: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+
+function writeText(filePath: string, value: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, value);
+}
+
+function createLegacyInstallFixture() {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-space-migrate-home-"));
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-space-migrate-cwd-"));
+  process.chdir(cwd);
+  process.env.PAPERCLIP_HOME = home;
+  delete process.env.PAPERCLIP_CONFIG;
+  delete process.env.PAPERCLIP_INSTANCE_ID;
+  delete process.env.PAPERCLIP_SPACE_ID;
+
+  const instanceRoot = path.join(home, "instances", "default");
+  const spaceRoot = path.join(instanceRoot, "spaces", "default");
+  const config: PaperclipConfig = {
+    $meta: {
+      version: 1,
+      updatedAt: "2026-05-09T00:00:00.000Z",
+      source: "onboard",
+    },
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: path.join(instanceRoot, "db"),
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(instanceRoot, "data", "backups"),
+      },
+    },
+    logging: {
+      mode: "file",
+      logDir: path.join(instanceRoot, "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted",
+      exposure: "private",
+      host: "127.0.0.1",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "auto",
+      disableSignUp: false,
+    },
+    telemetry: {
+      enabled: true,
+    },
+    storage: {
+      provider: "local_disk",
+      localDisk: {
+        baseDir: path.join(instanceRoot, "data", "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted",
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(instanceRoot, "secrets", "master.key"),
+      },
+    },
+  };
+
+  writeJson(path.join(instanceRoot, "config.json"), config);
+  writeText(path.join(instanceRoot, ".env"), "PAPERCLIP_AGENT_JWT_SECRET=test-secret\n");
+  writeText(path.join(instanceRoot, "db", "PG_VERSION"), "17\n");
+  writeText(path.join(instanceRoot, "data", "storage", "hello.txt"), "hello\n");
+  writeText(path.join(instanceRoot, "logs", "server.log"), "log\n");
+  writeText(path.join(instanceRoot, "secrets", "master.key"), "01234567890123456789012345678901");
+  writeText(path.join(instanceRoot, "workspaces", "agent-1", "README.md"), "workspace\n");
+  writeText(path.join(instanceRoot, "projects", "company", "project", "repo", "README.md"), "project\n");
+  writeText(path.join(instanceRoot, "companies", "company-1", "codex-home", "config.toml"), "model=\"x\"\n");
+  writeText(path.join(instanceRoot, "codex-home", "config.toml"), "model=\"shared\"\n");
+
+  return { instanceRoot, spaceRoot };
+}
+
+beforeEach(() => {
+  process.env = { ...ORIGINAL_ENV };
+});
+
+afterEach(() => {
+  process.env = { ...ORIGINAL_ENV };
+  process.chdir(ORIGINAL_CWD);
+  vi.unstubAllGlobals();
+});
+
+describe("spaces migrate-default", () => {
+  it("moves a legacy root-shaped install into spaces/default and rewrites config paths", async () => {
+    const fixture = createLegacyInstallFixture();
+
+    const result = await migrateDefaultSpaceInstall({
+      serverRunningCheck: async () => false,
+    });
+
+    expect(result.status).toBe("migrated");
+    expect(result.movedPaths).toEqual([
+      "config.json",
+      ".env",
+      "db",
+      "data",
+      "logs",
+      "secrets",
+      "workspaces",
+      "projects",
+      "companies",
+      "codex-home",
+    ]);
+
+    expect(fs.existsSync(path.join(fixture.instanceRoot, "db"))).toBe(false);
+    expect(fs.readFileSync(path.join(fixture.spaceRoot, ".env"), "utf8")).toContain("PAPERCLIP_AGENT_JWT_SECRET");
+    expect(fs.readFileSync(path.join(fixture.spaceRoot, "db", "PG_VERSION"), "utf8")).toBe("17\n");
+    expect(fs.readFileSync(path.join(fixture.spaceRoot, "data", "storage", "hello.txt"), "utf8")).toBe("hello\n");
+    expect(fs.readFileSync(path.join(fixture.spaceRoot, "companies", "company-1", "codex-home", "config.toml"), "utf8")).toContain("model");
+    expect(fs.readFileSync(path.join(fixture.spaceRoot, "codex-home", "config.toml"), "utf8")).toContain("shared");
+
+    const migratedConfig = JSON.parse(fs.readFileSync(path.join(fixture.spaceRoot, "config.json"), "utf8")) as PaperclipConfig;
+    expect(migratedConfig.database.embeddedPostgresDataDir).toBe(path.join(fixture.spaceRoot, "db"));
+    expect(migratedConfig.database.backup.dir).toBe(path.join(fixture.spaceRoot, "data", "backups"));
+    expect(migratedConfig.logging.logDir).toBe(path.join(fixture.spaceRoot, "logs"));
+    expect(migratedConfig.storage.localDisk.baseDir).toBe(path.join(fixture.spaceRoot, "data", "storage"));
+    expect(migratedConfig.secrets.localEncrypted.keyFilePath).toBe(path.join(fixture.spaceRoot, "secrets", "master.key"));
+
+    const marker = JSON.parse(fs.readFileSync(path.join(fixture.instanceRoot, "config.json"), "utf8")) as {
+      activeSpaceId?: string;
+      defaultSpaceMigration?: { sourceRoot?: string; destinationRoot?: string; movedPaths?: string[] };
+    };
+    expect(marker.activeSpaceId).toBe("default");
+    expect(marker.defaultSpaceMigration).toMatchObject({
+      sourceRoot: fixture.instanceRoot,
+      destinationRoot: fixture.spaceRoot,
+      movedPaths: result.movedPaths,
+    });
+
+    expect(resolveConfigPath()).toBe(path.join(fixture.spaceRoot, "config.json"));
+    expect(readConfig()?.database.embeddedPostgresDataDir).toBe(path.join(fixture.spaceRoot, "db"));
+  });
+
+  it("refuses to merge when destination data already exists", async () => {
+    const fixture = createLegacyInstallFixture();
+    writeText(path.join(fixture.spaceRoot, "db", "PG_VERSION"), "existing\n");
+
+    await expect(migrateDefaultSpaceInstall({
+      serverRunningCheck: async () => false,
+    })).rejects.toThrow(/destination paths already exist:[\s\S]*db/);
+
+    expect(fs.readFileSync(path.join(fixture.instanceRoot, "db", "PG_VERSION"), "utf8")).toBe("17\n");
+    expect(fs.readFileSync(path.join(fixture.spaceRoot, "db", "PG_VERSION"), "utf8")).toBe("existing\n");
+  });
+
+  it("refuses to migrate when the server appears to be running", async () => {
+    const fixture = createLegacyInstallFixture();
+
+    await expect(migrateDefaultSpaceInstall({
+      serverRunningCheck: async () => true,
+    })).rejects.toThrow(/server appears to be running/);
+
+    expect(fs.existsSync(path.join(fixture.instanceRoot, "config.json"))).toBe(true);
+    expect(fs.existsSync(path.join(fixture.spaceRoot, "config.json"))).toBe(false);
+  });
+
+  it("checks the destination space config when the instance root only has a space registry", async () => {
+    const fixture = createLegacyInstallFixture();
+    const destinationConfig = JSON.parse(fs.readFileSync(path.join(fixture.instanceRoot, "config.json"), "utf8")) as PaperclipConfig;
+    fs.rmSync(path.join(fixture.instanceRoot, "config.json"));
+    writeJson(path.join(fixture.instanceRoot, "config.json"), {
+      $meta: { version: 1, updatedAt: "2026-05-10T00:00:00.000Z", source: "system" },
+      activeSpaceId: "default",
+      spaces: [{ id: "default", root: "spaces/default", createdAt: "2026-05-10T00:00:00.000Z" }],
+    });
+    writeJson(path.join(fixture.spaceRoot, "config.json"), {
+      ...destinationConfig,
+      server: {
+        ...destinationConfig.server,
+        port: 43210,
+      },
+    });
+    const fetchMock = vi.fn(async () => ({ status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(defaultServerRunningCheck({
+      instanceId: "default",
+      sourceRoot: fixture.instanceRoot,
+      destinationRoot: fixture.spaceRoot,
+      legacyRuntimeConfig: false,
+      sourcePathNames: [],
+      conflicts: [],
+    })).resolves.toBe(true);
+
+    expect(fetchMock).toHaveBeenCalledWith("http://127.0.0.1:43210/api/health", expect.any(Object));
+  });
+});
diff --git a/cli/src/commands/configure.ts b/cli/src/commands/configure.ts
index b7d2dcbc07d..4b96d10a3f0 100644
--- a/cli/src/commands/configure.ts
+++ b/cli/src/commands/configure.ts
@@ -15,6 +15,7 @@ import {
   resolveDefaultLogsDir,
   resolvePaperclipInstanceId,
 } from "../config/home.js";
+import { ensureDefaultSpaceRegistry } from "@paperclipai/shared/space-paths";
 import { printPaperclipCliBanner } from "../utils/banner.js";
 
 type Section = "llm" | "database" | "logging" | "server" | "storage" | "secrets";
@@ -177,6 +178,9 @@ export async function configure(opts: {
     config.$meta.updatedAt = new Date().toISOString();
     config.$meta.source = "configure";
 
+    if (configPath === resolveConfigPath()) {
+      ensureDefaultSpaceRegistry({ source: "configure" });
+    }
     writeConfig(config, opts.config);
     p.log.success(`${SECTION_LABELS[section]} configuration updated.`);
 
diff --git a/cli/src/commands/onboard.ts b/cli/src/commands/onboard.ts
index 62158e05bbf..c0f409092ee 100644
--- a/cli/src/commands/onboard.ts
+++ b/cli/src/commands/onboard.ts
@@ -36,6 +36,7 @@ import {
   resolveDefaultLogsDir,
   resolvePaperclipInstanceId,
 } from "../config/home.js";
+import { ensureDefaultSpaceRegistry } from "@paperclipai/shared/space-paths";
 import { bootstrapCeoInvite } from "./auth-bootstrap-ceo.js";
 import { printPaperclipCliBanner } from "../utils/banner.js";
 import {
@@ -333,7 +334,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
   const instance = describeLocalInstancePaths(resolvePaperclipInstanceId());
   p.log.message(
     pc.dim(
-      `Local home: ${instance.homeDir} | instance: ${instance.instanceId} | config: ${configPath}`,
+      `Local home: ${instance.homeDir} | instance: ${instance.instanceId} | space: ${instance.activeSpaceId} | config: ${configPath}`,
     ),
   );
 
@@ -625,6 +626,10 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     p.log.message(pc.dim(`Using existing local secrets key file at ${keyResult.path}`));
   }
 
+  if (configPath === resolveConfigPath()) {
+    ensureDefaultSpaceRegistry({ source: "onboard" });
+  }
+
   writeConfig(config, opts.config);
 
   if (tc) trackInstallCompleted(tc, {
diff --git a/cli/src/commands/spaces.ts b/cli/src/commands/spaces.ts
new file mode 100644
index 00000000000..d443f650532
--- /dev/null
+++ b/cli/src/commands/spaces.ts
@@ -0,0 +1,269 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import pc from "picocolors";
+import {
+  DEFAULT_PAPERCLIP_SPACE_ID,
+  DEFAULT_SPACE_ADAPTER_LOCAL_PATH_NAMES,
+  DEFAULT_SPACE_OWNED_PATH_NAMES,
+  createDefaultSpaceRegistry,
+  expandHomePrefix,
+  isPaperclipRuntimeConfig,
+  resolvePaperclipInstanceConfigPath,
+  resolvePaperclipInstanceId,
+  resolvePaperclipInstanceRoot,
+  resolvePaperclipSpacesRoot,
+} from "@paperclipai/shared/space-paths";
+
+type JsonObject = Record<string, unknown>;
+
+export interface DefaultSpaceMigrationPlan {
+  instanceId: string;
+  sourceRoot: string;
+  destinationRoot: string;
+  legacyRuntimeConfig: boolean;
+  sourcePathNames: string[];
+  conflicts: Array<{ pathName: string; sourcePath: string; destinationPath: string }>;
+}
+
+export interface DefaultSpaceMigrationResult {
+  status: "migrated" | "noop" | "dry_run";
+  plan: DefaultSpaceMigrationPlan;
+  movedPaths: string[];
+  markerPath: string | null;
+}
+
+export interface MigrateDefaultSpaceOptions {
+  instanceId?: string;
+  dryRun?: boolean;
+  skipServerCheck?: boolean;
+  serverRunningCheck?: (plan: DefaultSpaceMigrationPlan) => Promise<boolean>;
+}
+
+const MIGRATION_PATH_NAMES = [
+  ...DEFAULT_SPACE_OWNED_PATH_NAMES,
+  ...DEFAULT_SPACE_ADAPTER_LOCAL_PATH_NAMES,
+] as const;
+
+function readJsonIfPresent(filePath: string): unknown | null {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPathWithin(rootPath: string, candidatePath: string): boolean {
+  const root = path.resolve(rootPath);
+  const candidate = path.resolve(candidatePath);
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function rewriteSpaceRootString(value: string, sourceRoot: string, destinationRoot: string): string {
+  const resolved = path.resolve(expandHomePrefix(value));
+  if (!isPathWithin(sourceRoot, resolved)) return value;
+  const relative = path.relative(path.resolve(sourceRoot), resolved);
+  return path.resolve(destinationRoot, relative);
+}
+
+function rewriteConfigPaths(value: unknown, sourceRoot: string, destinationRoot: string): unknown {
+  if (typeof value === "string") return rewriteSpaceRootString(value, sourceRoot, destinationRoot);
+  if (Array.isArray(value)) return value.map((entry) => rewriteConfigPaths(entry, sourceRoot, destinationRoot));
+  if (!isObject(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, entry]) => [key, rewriteConfigPaths(entry, sourceRoot, destinationRoot)]),
+  );
+}
+
+function writeJson(filePath: string, value: unknown, mode = 0o600): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { mode });
+}
+
+function atomicWriteJson(filePath: string, value: unknown, mode = 0o600): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.tmp`);
+  writeJson(tmpPath, value, mode);
+  fs.renameSync(tmpPath, filePath);
+}
+
+export function buildDefaultSpaceMigrationPlan(options: Pick<MigrateDefaultSpaceOptions, "instanceId"> = {}): DefaultSpaceMigrationPlan {
+  const instanceId = resolvePaperclipInstanceId(options.instanceId);
+  const sourceRoot = resolvePaperclipInstanceRoot({ instanceId });
+  const destinationRoot = path.resolve(resolvePaperclipSpacesRoot({ instanceId }), DEFAULT_PAPERCLIP_SPACE_ID);
+  const instanceConfigPath = resolvePaperclipInstanceConfigPath({ instanceId });
+  const legacyRuntimeConfig = isPaperclipRuntimeConfig(readJsonIfPresent(instanceConfigPath));
+
+  const sourcePathNames = MIGRATION_PATH_NAMES.filter((pathName) => {
+    if (pathName === "config.json" && !legacyRuntimeConfig) return false;
+    return fs.existsSync(path.join(sourceRoot, pathName));
+  });
+
+  const conflicts = sourcePathNames
+    .map((pathName) => ({
+      pathName,
+      sourcePath: path.join(sourceRoot, pathName),
+      destinationPath: path.join(destinationRoot, pathName),
+    }))
+    .filter((entry) => fs.existsSync(entry.destinationPath));
+
+  return {
+    instanceId,
+    sourceRoot,
+    destinationRoot,
+    legacyRuntimeConfig,
+    sourcePathNames,
+    conflicts,
+  };
+}
+
+function readServerEndpointFromConfig(configPath: string): { host: string; port: number } | null {
+  const parsed = readJsonIfPresent(configPath);
+  if (!isObject(parsed)) return null;
+  const server = parsed.server;
+  if (!isObject(server)) return null;
+  const rawHost = typeof server.host === "string" && server.host.trim().length > 0
+    ? server.host.trim()
+    : "127.0.0.1";
+  const host = rawHost === "0.0.0.0" || rawHost === "::" ? "127.0.0.1" : rawHost;
+  const port = typeof server.port === "number" && Number.isInteger(server.port) ? server.port : 3100;
+  if (port <= 0 || port > 65535) return null;
+  return { host, port };
+}
+
+export async function defaultServerRunningCheck(plan: DefaultSpaceMigrationPlan): Promise<boolean> {
+  const endpoint =
+    readServerEndpointFromConfig(path.join(plan.sourceRoot, "config.json")) ??
+    readServerEndpointFromConfig(path.join(plan.destinationRoot, "config.json"));
+  if (!endpoint) return false;
+
+  const host = endpoint.host.includes(":") ? `[${endpoint.host}]` : endpoint.host;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 500);
+  try {
+    const response = await fetch(`http://${host}:${endpoint.port}/api/health`, {
+      signal: controller.signal,
+    });
+    return response.status >= 200 && response.status < 500;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function assertMigrationPreflight(plan: DefaultSpaceMigrationPlan): void {
+  if (plan.conflicts.length === 0) return;
+  const details = plan.conflicts
+    .map((conflict) => `- ${conflict.pathName}: ${conflict.sourcePath} -> ${conflict.destinationPath}`)
+    .join("\n");
+  throw new Error(`Cannot migrate default space because destination paths already exist:\n${details}`);
+}
+
+function moveConfigWithRewrittenPaths(sourcePath: string, destinationPath: string, sourceRoot: string, destinationRoot: string): void {
+  const parsed = JSON.parse(fs.readFileSync(sourcePath, "utf8")) as unknown;
+  const rewritten = rewriteConfigPaths(parsed, sourceRoot, destinationRoot);
+  atomicWriteJson(destinationPath, rewritten);
+  fs.unlinkSync(sourcePath);
+}
+
+function writeMigrationMarker(plan: DefaultSpaceMigrationPlan, movedPaths: string[]): string {
+  const migratedAt = new Date().toISOString();
+  const registry = createDefaultSpaceRegistry("system");
+  registry.$meta.updatedAt = migratedAt;
+  registry.defaultSpaceMigration = {
+    migratedAt,
+    sourceRoot: plan.sourceRoot,
+    destinationRoot: plan.destinationRoot,
+    movedPaths,
+  };
+
+  const markerPath = path.join(plan.sourceRoot, "config.json");
+  writeJson(markerPath, registry);
+  return markerPath;
+}
+
+export async function migrateDefaultSpaceInstall(
+  options: MigrateDefaultSpaceOptions = {},
+): Promise<DefaultSpaceMigrationResult> {
+  const plan = buildDefaultSpaceMigrationPlan(options);
+
+  if (plan.sourcePathNames.length === 0) {
+    return { status: "noop", plan, movedPaths: [], markerPath: null };
+  }
+
+  assertMigrationPreflight(plan);
+
+  const serverRunningCheck = options.serverRunningCheck ?? defaultServerRunningCheck;
+  if (!options.skipServerCheck && await serverRunningCheck(plan)) {
+    throw new Error(
+      `Cannot migrate default space while a Paperclip server appears to be running for ${plan.sourceRoot}. Stop Paperclip and retry.`,
+    );
+  }
+
+  if (options.dryRun) {
+    return { status: "dry_run", plan, movedPaths: plan.sourcePathNames, markerPath: null };
+  }
+
+  fs.mkdirSync(plan.destinationRoot, { recursive: true });
+  const movedPaths: string[] = [];
+
+  for (const pathName of plan.sourcePathNames) {
+    const sourcePath = path.join(plan.sourceRoot, pathName);
+    const destinationPath = path.join(plan.destinationRoot, pathName);
+    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+
+    if (pathName === "config.json") {
+      moveConfigWithRewrittenPaths(sourcePath, destinationPath, plan.sourceRoot, plan.destinationRoot);
+    } else {
+      fs.renameSync(sourcePath, destinationPath);
+    }
+    movedPaths.push(pathName);
+  }
+
+  const markerPath = writeMigrationMarker(plan, movedPaths);
+  return { status: "migrated", plan, movedPaths, markerPath };
+}
+
+function printMigrationResult(result: DefaultSpaceMigrationResult): void {
+  if (result.status === "noop") {
+    console.log(pc.dim(`No legacy default-space data found under ${result.plan.sourceRoot}.`));
+    return;
+  }
+
+  const verb = result.status === "dry_run" ? "Would migrate" : "Migrated";
+  console.log(`${pc.green(verb)} default space:`);
+  console.log(`  ${pc.dim("from")} ${result.plan.sourceRoot}`);
+  console.log(`  ${pc.dim("to")}   ${result.plan.destinationRoot}`);
+  for (const pathName of result.movedPaths) {
+    console.log(`  ${pc.dim("-")} ${pathName}`);
+  }
+  if (result.markerPath) {
+    console.log(`  ${pc.dim("marker")} ${result.markerPath}`);
+  }
+}
+
+export function registerSpacesCommands(program: Command): void {
+  const spaces = program.command("spaces").description("Manage local Paperclip spaces");
+
+  spaces
+    .command("migrate-default")
+    .description("Offline migration from legacy root-shaped instance data into spaces/default")
+    .option("-i, --instance <id>", "Local instance id (default: default)")
+    .option("--dry-run", "Show the migration plan without moving files", false)
+    .option("--skip-server-check", "Skip the local /api/health preflight", false)
+    .action(async (opts: { instance?: string; dryRun?: boolean; skipServerCheck?: boolean }) => {
+      const result = await migrateDefaultSpaceInstall({
+        instanceId: opts.instance,
+        dryRun: opts.dryRun,
+        skipServerCheck: opts.skipServerCheck,
+      });
+      printMigrationResult(result);
+    });
+}
diff --git a/cli/src/config/home.ts b/cli/src/config/home.ts
index ef4d8e09386..0b93a70ed26 100644
--- a/cli/src/config/home.ts
+++ b/cli/src/config/home.ts
@@ -1,32 +1,38 @@
-import os from "node:os";
 import path from "node:path";
+import {
+  expandHomePrefix,
+  resolveDefaultBackupDir as resolveSharedDefaultBackupDir,
+  resolveDefaultEmbeddedPostgresDir as resolveSharedDefaultEmbeddedPostgresDir,
+  resolveDefaultLogsDir as resolveSharedDefaultLogsDir,
+  resolveDefaultSecretsKeyFilePath as resolveSharedDefaultSecretsKeyFilePath,
+  resolveDefaultStorageDir as resolveSharedDefaultStorageDir,
+  resolveHomeAwarePath,
+  resolvePaperclipConfigPathForInstance,
+  resolvePaperclipHomeDir,
+  resolvePaperclipInstanceId,
+  resolvePaperclipInstanceRoot as resolveSharedPaperclipInstanceRoot,
+  resolvePaperclipSpaceId,
+  resolvePaperclipSpaceRoot as resolveSharedPaperclipSpaceRoot,
+} from "@paperclipai/shared/space-paths";
 
-const DEFAULT_INSTANCE_ID = "default";
-const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
-
-export function resolvePaperclipHomeDir(): string {
-  const envHome = process.env.PAPERCLIP_HOME?.trim();
-  if (envHome) return path.resolve(expandHomePrefix(envHome));
-  return path.resolve(os.homedir(), ".paperclip");
-}
-
-export function resolvePaperclipInstanceId(override?: string): string {
-  const raw = override?.trim() || process.env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_INSTANCE_ID;
-  if (!INSTANCE_ID_RE.test(raw)) {
-    throw new Error(
-      `Invalid instance id '${raw}'. Allowed characters: letters, numbers, '_' and '-'.`,
-    );
-  }
-  return raw;
-}
+export {
+  expandHomePrefix,
+  resolveHomeAwarePath,
+  resolvePaperclipHomeDir,
+  resolvePaperclipInstanceId,
+  resolvePaperclipSpaceId,
+};
 
 export function resolvePaperclipInstanceRoot(instanceId?: string): string {
-  const id = resolvePaperclipInstanceId(instanceId);
-  return path.resolve(resolvePaperclipHomeDir(), "instances", id);
+  return resolveSharedPaperclipInstanceRoot({ instanceId });
+}
+
+export function resolvePaperclipSpaceRoot(instanceId?: string): string {
+  return resolveSharedPaperclipSpaceRoot({ instanceId });
 }
 
 export function resolveDefaultConfigPath(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "config.json");
+  return resolvePaperclipConfigPathForInstance({ instanceId });
 }
 
 export function resolveDefaultContextPath(): string {
@@ -38,38 +44,39 @@ export function resolveDefaultCliAuthPath(): string {
 }
 
 export function resolveDefaultEmbeddedPostgresDir(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "db");
+  return resolveSharedDefaultEmbeddedPostgresDir({ instanceId });
 }
 
 export function resolveDefaultLogsDir(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "logs");
+  return resolveSharedDefaultLogsDir({ instanceId });
 }
 
 export function resolveDefaultSecretsKeyFilePath(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "secrets", "master.key");
+  return resolveSharedDefaultSecretsKeyFilePath({ instanceId });
 }
 
 export function resolveDefaultStorageDir(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "data", "storage");
+  return resolveSharedDefaultStorageDir({ instanceId });
 }
 
 export function resolveDefaultBackupDir(instanceId?: string): string {
-  return path.resolve(resolvePaperclipInstanceRoot(instanceId), "data", "backups");
-}
-
-export function expandHomePrefix(value: string): string {
-  if (value === "~") return os.homedir();
-  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
-  return value;
+  return resolveSharedDefaultBackupDir({ instanceId });
 }
 
 export function describeLocalInstancePaths(instanceId?: string) {
   const resolvedInstanceId = resolvePaperclipInstanceId(instanceId);
   const instanceRoot = resolvePaperclipInstanceRoot(resolvedInstanceId);
+  const activeSpaceId = resolvePaperclipSpaceId({ instanceId: resolvedInstanceId });
+  const activeSpaceRoot = resolveSharedPaperclipSpaceRoot({
+    instanceId: resolvedInstanceId,
+    spaceId: activeSpaceId,
+  });
   return {
     homeDir: resolvePaperclipHomeDir(),
     instanceId: resolvedInstanceId,
     instanceRoot,
+    activeSpaceId,
+    activeSpaceRoot,
     configPath: resolveDefaultConfigPath(resolvedInstanceId),
     embeddedPostgresDataDir: resolveDefaultEmbeddedPostgresDir(resolvedInstanceId),
     backupDir: resolveDefaultBackupDir(resolvedInstanceId),
diff --git a/cli/src/index.ts b/cli/src/index.ts
index f1a2084a727..a718f02e409 100644
--- a/cli/src/index.ts
+++ b/cli/src/index.ts
@@ -25,6 +25,7 @@ import { initTelemetryFromConfigFile, flushTelemetry } from "./telemetry.js";
 import { registerWorktreeCommands } from "./commands/worktree.js";
 import { registerPluginCommands } from "./commands/client/plugin.js";
 import { registerClientAuthCommands } from "./commands/client/auth.js";
+import { registerSpacesCommands } from "./commands/spaces.js";
 import { cliVersion } from "./version.js";
 
 const program = new Command();
@@ -152,6 +153,7 @@ registerSecretCommands(program);
 registerWorktreeCommands(program);
 registerEnvLabCommands(program);
 registerPluginCommands(program);
+registerSpacesCommands(program);
 
 const auth = program.command("auth").description("Authentication and bootstrap utilities");
 
diff --git a/doc/CLI.md b/doc/CLI.md
index 29c494e3bed..bbc4bb871f4 100644
--- a/doc/CLI.md
+++ b/doc/CLI.md
@@ -204,20 +204,84 @@ pnpm paperclipai heartbeat run --agent-id <agent-id> [--api-base http://localhos
 
 ## Local Storage Defaults
 
-Default local instance root is `~/.paperclip/instances/default`:
+Local Paperclip data is split between an instance root and one or more spaces inside it. The default install creates a single space called `default` under `spaces/default`.
 
-- config: `~/.paperclip/instances/default/config.json`
-- embedded db: `~/.paperclip/instances/default/db`
-- logs: `~/.paperclip/instances/default/logs`
-- storage: `~/.paperclip/instances/default/data/storage`
-- secrets key: `~/.paperclip/instances/default/secrets/master.key`
+```text
+~/.paperclip/                                     # PAPERCLIP_HOME
+└── instances/
+    └── default/                                  # instance root (PAPERCLIP_INSTANCE_ID)
+        ├── config.json                           # space registry (activeSpaceId, known spaces)
+        └── spaces/
+            └── default/                          # active space root (PAPERCLIP_SPACE_ID)
+                ├── config.json                   # runtime config for this space
+                ├── .env                          # space-scoped env file
+                ├── db/                           # embedded PostgreSQL data
+                ├── data/
+                │   ├── storage/                  # local_disk uploads
+                │   └── backups/                  # automatic DB backups
+                ├── logs/
+                ├── secrets/
+                │   └── master.key                # local_encrypted master key
+                ├── workspaces/                   # default agent workspaces
+                ├── projects/                     # project execution workspaces
+                ├── companies/                    # per-company adapter homes (e.g. codex-home)
+                └── codex-home/                   # per-instance codex home (when not company-scoped)
+```
 
-Override base home or instance with env vars:
+Default paths for the canonical install:
+
+- instance registry: `~/.paperclip/instances/default/config.json`
+- space config: `~/.paperclip/instances/default/spaces/default/config.json`
+- embedded db: `~/.paperclip/instances/default/spaces/default/db`
+- logs: `~/.paperclip/instances/default/spaces/default/logs`
+- storage: `~/.paperclip/instances/default/spaces/default/data/storage`
+- secrets key: `~/.paperclip/instances/default/spaces/default/secrets/master.key`
+
+The instance root holds only cross-space metadata. All runtime state — database, storage, secrets, logs, agent workspaces — lives inside the active space.
+
+Override base home, instance, or active space with env vars:
 
 ```sh
 PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
+PAPERCLIP_SPACE_ID=staging pnpm paperclipai run        # use an alternate space inside the same instance
 ```
 
+`PAPERCLIP_SPACE_ID` overrides whatever `activeSpaceId` is recorded in the instance registry. When unset, Paperclip resolves the active space from `instances/<id>/config.json` and falls back to `default`.
+
+## Migrating a Legacy Default-Space Install
+
+Earlier Paperclip versions stored default-space data directly at the instance root (for example `~/.paperclip/instances/default/db`). Those installs continue to start through a compatibility resolver, but new code paths assume `spaces/default`. Migrate explicitly with:
+
+```sh
+# Stop Paperclip first; the migration refuses to run while a local server is up.
+pnpm paperclipai spaces migrate-default
+
+# Preview the move without touching files.
+pnpm paperclipai spaces migrate-default --dry-run
+
+# Operate on a non-default instance.
+pnpm paperclipai spaces migrate-default --instance dev
+```
+
+The command:
+
+- detects a legacy root-shaped install by inspecting `instances/<id>/config.json`
+- preflight-checks `http://<server.host>:<server.port>/api/health` and refuses to run when the server responds
+- refuses to merge if the destination already contains conflicting paths under `spaces/default/`
+- moves only known space-owned paths: `config.json`, `.env`, `db`, `data`, `logs`, `secrets`, `workspaces`, `projects`, `companies`, and the legacy top-level `codex-home`
+- rewrites absolute paths inside the migrated `config.json` from the instance root to the new space root (`embeddedPostgresDataDir`, backup `dir`, `logging.logDir`, `storage.localDisk.baseDir`, `secrets.localEncrypted.keyFilePath`)
+- writes the registry/marker back at `instances/<id>/config.json` recording `activeSpaceId`, the migration timestamp, and the moved paths
+
+Available flags:
+
+| Option | Description |
+|---|---|
+| `-i, --instance <id>` | Local instance id (default: `default`) |
+| `--dry-run` | Show the migration plan without moving files |
+| `--skip-server-check` | Skip the `/api/health` preflight (only for offline installs) |
+
+Restart Paperclip after a successful migration. Subsequent commands resolve the active space root from the new registry automatically.
+
 ## Storage Configuration
 
 Configure storage provider and settings:
diff --git a/doc/DATABASE.md b/doc/DATABASE.md
index 2e0ad661358..65886a62e7e 100644
--- a/doc/DATABASE.md
+++ b/doc/DATABASE.md
@@ -12,12 +12,12 @@ pnpm dev
 
 That's it. On first start the server:
 
-1. Creates a `~/.paperclip/instances/default/db/` directory for storage
+1. Creates a `~/.paperclip/instances/default/spaces/default/db/` directory for storage
 2. Ensures the `paperclip` database exists
 3. Runs migrations automatically for empty databases
 4. Starts serving requests
 
-Data persists across restarts in `~/.paperclip/instances/default/db/`. To reset local dev data, delete that directory.
+Data persists across restarts in `~/.paperclip/instances/default/spaces/default/db/`. To reset local dev data, delete that directory. Older installs that still keep data at `~/.paperclip/instances/default/db/` continue to start through the legacy resolver — see [Migrating a Legacy Default-Space Install](CLI.md#migrating-a-legacy-default-space-install).
 
 If you need to apply pending migrations manually, run:
 
@@ -137,7 +137,7 @@ The database mode is controlled by `DATABASE_URL`:
 
 | `DATABASE_URL` | Mode |
 |---|---|
-| Not set | Embedded PostgreSQL (`~/.paperclip/instances/default/db/`) |
+| Not set | Embedded PostgreSQL (`~/.paperclip/instances/default/spaces/default/db/`) |
 | `postgres://...localhost...` | Local Docker PostgreSQL |
 | `postgres://...supabase.com...` | Hosted Supabase |
 
@@ -169,8 +169,8 @@ Paperclip stores secret metadata and versions in:
 For local/default installs, the active provider is `local_encrypted`:
 
 - Secret material is encrypted at rest with a local master key.
-- Default key file: `~/.paperclip/instances/default/secrets/master.key` (auto-created if missing).
-- CLI config location: `~/.paperclip/instances/default/config.json` under `secrets.localEncrypted.keyFilePath`.
+- Default key file: `~/.paperclip/instances/default/spaces/default/secrets/master.key` (auto-created if missing).
+- CLI config location: `~/.paperclip/instances/default/spaces/default/config.json` under `secrets.localEncrypted.keyFilePath`. (The instance-level `~/.paperclip/instances/default/config.json` is the cross-space registry that records which space is active.)
 - Backup/restore requires both the database metadata and the local master key file; either artifact alone is insufficient.
 - The server best-effort enforces `0600` key file permissions and provider health reports permission warnings.
 
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.md
index c9a2a19414c..eff89e061ae 100644
--- a/doc/DEVELOPING.md
+++ b/doc/DEVELOPING.md
@@ -157,17 +157,44 @@ See `doc/DOCKER.md` for API key wiring (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY`)
 
 For a separate review-oriented container that keeps `codex`/`claude` login state in Docker volumes and checks out PRs into an isolated scratch workspace, see `doc/UNTRUSTED-PR-REVIEW.md`.
 
+## Local Instance Layout
+
+Every local install nests instance metadata, the active space, and runtime state under `~/.paperclip/`:
+
+```text
+~/.paperclip/instances/default/                  # instance root (cross-space metadata only)
+  config.json                                    # space registry (activeSpaceId, known spaces)
+  spaces/
+    default/                                     # active space root
+      config.json                                # space runtime config
+      .env                                       # space-scoped env file
+      db/                                        # embedded PostgreSQL data
+      data/
+        storage/                                 # local_disk uploads
+        backups/                                 # automatic DB backups
+      logs/
+      secrets/master.key                         # local_encrypted master key
+      workspaces/<agent-id>/                     # default agent workspaces
+      projects/                                  # project execution workspaces
+      companies/<company-id>/codex-home/         # per-company codex_local home
+```
+
+The instance root no longer doubles as the default space. New installs created by `paperclipai onboard`, `paperclipai run`, and `paperclipai configure` always write the registry at `instances/<id>/config.json` and put runtime data under `spaces/default/`. To migrate an older root-shaped install in place, see [Migrating a Legacy Default-Space Install](CLI.md#migrating-a-legacy-default-space-install).
+
+`PAPERCLIP_HOME`, `PAPERCLIP_INSTANCE_ID`, and `PAPERCLIP_SPACE_ID` override the home root, instance id, and active space respectively. `paperclipai onboard` echoes the resolved values in its banner (`Local home: <home> | instance: <id> | space: <id> | config: <path>`) so you can confirm where state will land before continuing.
+
 ## Database in Dev (Auto-Handled)
 
 For local development, leave `DATABASE_URL` unset.
 The server will automatically use embedded PostgreSQL and persist data at:
 
-- `~/.paperclip/instances/default/db`
+- `~/.paperclip/instances/default/spaces/default/db`
 
-Override home and instance:
+Override home, instance, or space:
 
 ```sh
 PAPERCLIP_HOME=/custom/path PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run
+PAPERCLIP_SPACE_ID=staging pnpm paperclipai run
 ```
 
 No Docker or external database is required for this mode.
@@ -176,7 +203,7 @@ No Docker or external database is required for this mode.
 
 For local development, the default storage provider is `local_disk`, which persists uploaded images/attachments at:
 
-- `~/.paperclip/instances/default/data/storage`
+- `~/.paperclip/instances/default/spaces/default/data/storage`
 
 Configure storage provider/settings:
 
@@ -186,15 +213,15 @@ pnpm paperclipai configure --section storage
 
 ## Default Agent Workspaces
 
-When a local agent run has no resolved project/session workspace, Paperclip falls back to an agent home workspace under the instance root:
+When a local agent run has no resolved project/session workspace, Paperclip falls back to an agent home workspace under the active space:
 
-- `~/.paperclip/instances/default/workspaces/<agent-id>`
+- `~/.paperclip/instances/default/spaces/default/workspaces/<agent-id>`
 
-This path honors `PAPERCLIP_HOME` and `PAPERCLIP_INSTANCE_ID` in non-default setups.
+This path honors `PAPERCLIP_HOME`, `PAPERCLIP_INSTANCE_ID`, and `PAPERCLIP_SPACE_ID` in non-default setups.
 
-For `codex_local`, Paperclip also manages a per-company Codex home under the instance root and seeds it from the shared Codex login/config home (`$CODEX_HOME` or `~/.codex`):
+For `codex_local`, Paperclip also manages a per-company Codex home under the active space and seeds it from the shared Codex login/config home (`$CODEX_HOME` or `~/.codex`):
 
-- `~/.paperclip/instances/default/companies/<company-id>/codex-home`
+- `~/.paperclip/instances/default/spaces/default/companies/<company-id>/codex-home`
 
 If the `codex` CLI is not installed or not on `PATH`, `codex_local` agent runs fail at execution time with a clear adapter error. Quota polling uses a short-lived `codex app-server` subprocess: when `codex` cannot be spawned, that provider reports `ok: false` in aggregated quota results and the API server keeps running (it must not exit on a missing binary).
 
@@ -280,13 +307,13 @@ paperclipai worktree init --from-data-dir ~/.paperclip
 paperclipai worktree init --force
 ```
 
-Repair an already-created repo-managed worktree and reseed its isolated instance from the main default install:
+Repair an already-created repo-managed worktree and reseed its isolated instance from the main default install. Point `--from-config` at the active space config (`spaces/default/config.json` for post-migration installs; the legacy `~/.paperclip/instances/default/config.json` still works on root-shaped installs that haven't run `paperclipai spaces migrate-default` yet):
 
 ```sh
 cd /path/to/paperclip/.paperclip/worktrees/PAP-884-ai-commits-component
 pnpm paperclipai worktree init --force --seed-mode minimal \
   --name PAP-884-ai-commits-component \
-  --from-config ~/.paperclip/instances/default/config.json
+  --from-config ~/.paperclip/instances/default/spaces/default/config.json
 ```
 
 That rewrites the worktree-local `.paperclip/config.json` + `.paperclip/.env`, recreates the isolated instance under `~/.paperclip-worktrees/instances/<worktree-id>/`, and preserves the git worktree contents themselves.
@@ -411,10 +438,12 @@ Expected:
 To wipe local dev data and start fresh:
 
 ```sh
-rm -rf ~/.paperclip/instances/default/db
+rm -rf ~/.paperclip/instances/default/spaces/default/db
 pnpm dev
 ```
 
+If you migrated from a legacy root-shaped install and still have a stale `~/.paperclip/instances/default/db`, remove that too — but only after confirming `paperclipai spaces migrate-default` ran and the active database lives under `spaces/default/`.
+
 ## Optional: Use External Postgres
 
 If you set `DATABASE_URL`, the server will use that instead of embedded PostgreSQL.
@@ -428,7 +457,7 @@ schemas. Defaults:
 - enabled
 - every 60 minutes
 - retain 30 days
-- backup dir: `~/.paperclip/instances/default/data/backups`
+- backup dir: `~/.paperclip/instances/default/spaces/default/data/backups`
 
 Configure these in:
 
@@ -459,7 +488,7 @@ those providers are enabled.
 
 Agent env vars now support secret references. By default, secret values are stored with local encryption and only secret refs are persisted in agent config.
 
-- Default local key path: `~/.paperclip/instances/default/secrets/master.key`
+- Default local key path: `~/.paperclip/instances/default/spaces/default/secrets/master.key`
 - Override key material directly: `PAPERCLIP_SECRETS_MASTER_KEY`
 - Override key file path: `PAPERCLIP_SECRETS_MASTER_KEY_FILE`
 - Back up the key file and database together; either one alone is not enough to restore local encrypted secrets.
diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md
index 22075e0453a..8ae2df78d66 100644
--- a/doc/SPEC-implementation.md
+++ b/doc/SPEC-implementation.md
@@ -93,11 +93,11 @@ V1 implementation extends this baseline into a company-centric, governance-aware
 ## 6.2 Data Stores
 
 - Primary: PostgreSQL
-- Local default: embedded PostgreSQL at `~/.paperclip/instances/default/db`
+- Local default: embedded PostgreSQL at `~/.paperclip/instances/default/spaces/default/db`
 - Optional local prod-like: Docker Postgres
 - Optional hosted: Supabase/Postgres-compatible
 - File/object storage:
-  - local default: `~/.paperclip/instances/default/data/storage` (`local_disk`)
+  - local default: `~/.paperclip/instances/default/spaces/default/data/storage` (`local_disk`)
   - cloud: S3-compatible object storage (`s3`)
 
 ## 6.3 Background Processing
@@ -785,7 +785,7 @@ Required UX behaviors:
 
 - Node 20+
 - `DATABASE_URL` optional
-- if unset, auto-use embedded PostgreSQL under `~/.paperclip/instances/default/db`
+- if unset, auto-use embedded PostgreSQL under `~/.paperclip/instances/default/spaces/default/db`
 
 ## 15.2 Migrations
 
diff --git a/doc/plans/2026-05-06-llm-wiki-paperclip-asset-security-gate.md b/doc/plans/2026-05-06-llm-wiki-paperclip-asset-security-gate.md
new file mode 100644
index 00000000000..cb527ae7ad3
--- /dev/null
+++ b/doc/plans/2026-05-06-llm-wiki-paperclip-asset-security-gate.md
@@ -0,0 +1,135 @@
+# LLM Wiki Paperclip Asset And Work-Product Security Gate
+
+Status: accepted Phase 5 policy
+Date: 2026-05-06
+Owner: Security engineering
+Scope: Paperclip-derived ingestion into the LLM Wiki before any asset or work-product content indexing ships
+
+## Decision
+
+Phase 5 remains **fail-closed** for Paperclip assets and work products.
+
+- Paperclip-derived **text extraction is allowed only** for issue titles/descriptions, issue comments, and issue documents.
+- Paperclip **assets/attachments** and **issue work products** are **metadata-only** in Phase 5.
+- **Linked summaries** and **content extraction** for assets/work products are **not approved** in Phase 5.
+- No implementation may fetch `/api/assets/:id/content`, dereference a work-product `url`, scrape preview pages, or embed binary/blob content into source bundles or source snapshots.
+
+This keeps the secure path easier than the insecure one and avoids broadening the wiki into a second content-distribution channel.
+
+## Allowed Source Kinds
+
+These source kinds may contribute body text to Paperclip-derived source bundles:
+
+| Source kind | Allowed body fields | Reason |
+| --- | --- | --- |
+| Issue | `title`, `description`, identifier/status metadata | First-party Paperclip text under company ACL |
+| Comment | `body` | First-party Paperclip text under company ACL |
+| Document | `body`, `title`, `key`, revision metadata | First-party Paperclip text under company ACL |
+
+## Assets And Work Products
+
+### Assets / attachments
+
+Allowed in Phase 5:
+
+- metadata-only references built from allowlisted structured fields already stored in Paperclip
+- recommended fields: `issueId`, `issueCommentId`, `attachmentId`, `assetId`, `originalFilename`, `contentType`, `byteSize`, `sha256`, `createdAt`, `createdByAgentId`, `createdByUserId`
+
+Disallowed in Phase 5:
+
+- fetching asset bytes from `/api/assets/:id/content`
+- parsing any blob body, including `text/plain`, `text/markdown`, `application/json`, images, SVG, PDFs, archives, or office formats
+- storing `contentPath` in wiki source bundles or source snapshots
+- model summarization of attachment bodies
+
+### Work products
+
+Allowed in Phase 5:
+
+- metadata-only references built from allowlisted structured fields already stored in Paperclip
+- recommended fields: `issueId`, `workProductId`, `type`, `provider`, `title`, `status`, `reviewState`, `healthStatus`, `externalId`, `isPrimary`, `createdAt`, `updatedAt`
+- optional boolean/derived metadata such as `hasUrl: true`
+
+Disallowed in Phase 5:
+
+- fetching or crawling the work-product `url`
+- scraping preview pages, artifacts, pull requests, branches, commits, or custom provider targets through the wiki ingestion path
+- storing raw `url` values in wiki source bundles or source snapshots
+- model-authored linked summaries derived from off-record content
+
+## MIME Allowlists And Size Caps
+
+No MIME allowlist is approved for asset content extraction in Phase 5 because **no asset body extraction is approved at all**.
+
+- Every asset MIME type is treated as opaque for Paperclip-derived indexing.
+- Existing upload limits remain storage concerns, not ingestion approvals.
+- Work-product destinations are also opaque regardless of MIME type or size.
+
+Any future issue that wants blob parsing must define:
+
+- a positive MIME allowlist
+- per-type parser strategy
+- per-source size caps
+- sandbox/isolation requirements
+- prompt-injection handling
+- regression tests for refusal paths
+
+## Redaction Rules
+
+Metadata-only means **structured facts only**, not capability-bearing links.
+
+- Do not persist `contentPath` for assets.
+- Do not persist raw work-product `url` values.
+- Do not persist query strings, fragments, signed URL tokens, or userinfo.
+- Prefer stable identifiers (`assetId`, `workProductId`, `externalId`) over links.
+
+This addresses Sensitive Information Disclosure, Unsafe Consumption of APIs, and Insecure Output Handling risks.
+
+## Provenance Rules
+
+Every metadata-only reference must preserve enough provenance to explain where it came from without reading the underlying content:
+
+- `companyId`
+- `issueId`
+- attachment/work-product id
+- producer identity when available
+- timestamps
+- an explicit `metadata_only` marker in any future reference/snapshot schema
+
+## Review-Required Behavior
+
+Human review is **not** required for plain metadata-only references that stay inside the allowlisted fields above.
+
+Human review **is required**, with a separate security sign-off issue, before enabling any of the following:
+
+- asset body extraction
+- work-product URL fetching
+- linked summaries generated from asset/work-product content
+- storing raw blob links or raw remote URLs in wiki source material
+- non-default-space routing for Paperclip-derived asset/work-product references
+
+## Security Rationale
+
+This gate exists because the current host surfaces have different trust properties:
+
+- issue/comment/document text is first-party Paperclip content already exposed through company-scoped issue/document APIs
+- asset content is a blob download surface (`/api/assets/:id/content`) and can carry prompt-injection or parser-risk payloads
+- work products can point at arbitrary destinations through `url`, which reintroduces SSRF, token leakage, and prompt-injection risk if dereferenced automatically
+
+Relevant threat classes:
+
+- OWASP LLM Top 10: Prompt Injection, Sensitive Information Disclosure, Insecure Output Handling, Excessive Agency
+- OWASP API Top 10: SSRF, Unsafe Consumption of APIs, Broken Object Property Level Authorization
+- Saltzer & Schroeder: Least Privilege, Fail Securely, Complete Mediation, Secure Defaults
+
+## Follow-Up Implementation Scope
+
+A follow-up implementation issue is justified only for **metadata-only references**.
+
+That implementation must:
+
+- keep assets/work products out of source-bundle body text
+- never fetch blob bytes or remote URLs
+- redact capability-bearing link fields
+- mark references as `metadata_only`
+- ship tests proving source bundles/snapshots never contain `contentPath` or raw work-product `url` fields
diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.ts
index bc3bc4a4cea..ee172e3122f 100644
--- a/packages/adapter-utils/src/server-utils.ts
+++ b/packages/adapter-utils/src/server-utils.ts
@@ -1,6 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { constants as fsConstants, promises as fs, type Dirent } from "node:fs";
+import { constants as fsConstants, existsSync, promises as fs, readFileSync, type Dirent } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
 import { buildSshSpawnTarget, type SshRemoteExecutionSpec } from "./ssh.js";
@@ -78,6 +79,121 @@ export const runningProcesses = new Map<string, RunningProcess>();
 export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
 export const MAX_EXCERPT_BYTES = 32 * 1024;
 const TERMINAL_RESULT_SCAN_OVERLAP_CHARS = 64 * 1024;
+const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
+const DEFAULT_PAPERCLIP_SPACE_ID = "default";
+const PAPERCLIP_CONFIG_BASENAME = "config.json";
+const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
+
+function expandHomePrefix(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
+  return value;
+}
+
+function resolvePaperclipHomeDirForAdapter(homeOverride?: string, env: NodeJS.ProcessEnv = process.env): string {
+  const raw = homeOverride?.trim() || env.PAPERCLIP_HOME?.trim();
+  if (raw) return path.resolve(expandHomePrefix(raw));
+  return path.resolve(os.homedir(), ".paperclip");
+}
+
+function resolvePaperclipInstanceIdForAdapter(instanceIdOverride?: string, env: NodeJS.ProcessEnv = process.env): string {
+  const raw = instanceIdOverride?.trim() || env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_PAPERCLIP_INSTANCE_ID;
+  if (!PATH_SEGMENT_RE.test(raw)) {
+    throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
+  }
+  return raw;
+}
+
+function resolvePaperclipInstanceRootForAdapter(input: {
+  homeDir?: string;
+  instanceId?: string;
+  env?: NodeJS.ProcessEnv;
+} = {}): string {
+  return path.resolve(
+    resolvePaperclipHomeDirForAdapter(input.homeDir, input.env),
+    "instances",
+    resolvePaperclipInstanceIdForAdapter(input.instanceId, input.env),
+  );
+}
+
+function resolvePaperclipInstanceConfigPathForAdapter(input: {
+  homeDir?: string;
+  instanceId?: string;
+  env?: NodeJS.ProcessEnv;
+} = {}): string {
+  return path.resolve(resolvePaperclipInstanceRootForAdapter(input), PAPERCLIP_CONFIG_BASENAME);
+}
+
+function readJsonIfPresent(filePath: string): unknown | null {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPaperclipRuntimeConfig(value: unknown): boolean {
+  return isObject(value) && isObject(value.database) && isObject(value.server);
+}
+
+function readActiveSpaceIdFromRegistry(instanceConfigPath: string): string | null {
+  const parsed = readJsonIfPresent(instanceConfigPath);
+  if (!isObject(parsed) || isPaperclipRuntimeConfig(parsed)) return null;
+  const activeSpaceId = parsed.activeSpaceId;
+  return typeof activeSpaceId === "string" && PATH_SEGMENT_RE.test(activeSpaceId) ? activeSpaceId : null;
+}
+
+function hasLegacyDefaultSpaceInstall(input: {
+  homeDir?: string;
+  instanceId?: string;
+  env?: NodeJS.ProcessEnv;
+} = {}): boolean {
+  return isPaperclipRuntimeConfig(readJsonIfPresent(resolvePaperclipInstanceConfigPathForAdapter(input)));
+}
+
+function resolvePaperclipSpaceIdForAdapter(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+  env?: NodeJS.ProcessEnv;
+} = {}): string {
+  const raw =
+    input.spaceId?.trim() ||
+    input.env?.PAPERCLIP_SPACE_ID?.trim() ||
+    process.env.PAPERCLIP_SPACE_ID?.trim() ||
+    readActiveSpaceIdFromRegistry(resolvePaperclipInstanceConfigPathForAdapter(input)) ||
+    DEFAULT_PAPERCLIP_SPACE_ID;
+  if (!PATH_SEGMENT_RE.test(raw)) {
+    throw new Error(`Invalid PAPERCLIP_SPACE_ID '${raw}'.`);
+  }
+  return raw;
+}
+
+function resolvePaperclipSpacesRootForAdapter(input: {
+  homeDir?: string;
+  instanceId?: string;
+  env?: NodeJS.ProcessEnv;
+} = {}): string {
+  return path.resolve(resolvePaperclipInstanceRootForAdapter(input), "spaces");
+}
+
+export function resolvePaperclipSpaceRootForAdapter(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+  env?: NodeJS.ProcessEnv;
+} = {}): string {
+  const spaceId = resolvePaperclipSpaceIdForAdapter(input);
+  if (spaceId === DEFAULT_PAPERCLIP_SPACE_ID && hasLegacyDefaultSpaceInstall(input)) {
+    return resolvePaperclipInstanceRootForAdapter(input);
+  }
+  return path.resolve(resolvePaperclipSpacesRootForAdapter(input), spaceId);
+}
 const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
 const REDACTED_LOG_VALUE = "***REDACTED***";
 const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
diff --git a/packages/adapters/acpx-local/src/server/execute.ts b/packages/adapters/acpx-local/src/server/execute.ts
index 3450cb9e586..f1d0d637bfe 100644
--- a/packages/adapters/acpx-local/src/server/execute.ts
+++ b/packages/adapters/acpx-local/src/server/execute.ts
@@ -22,6 +22,7 @@ import {
   renderPaperclipWakePrompt,
   renderTemplate,
   resolvePaperclipDesiredSkillNames,
+  resolvePaperclipSpaceRootForAdapter,
   rewriteWorkspaceCwdEnvVarsForExecution,
   shapePaperclipWorkspaceEnvForExecution,
   stringifyPaperclipWakePayload,
@@ -115,7 +116,11 @@ function shortHash(value: unknown): string {
 function defaultPaperclipInstanceDir(): string {
   const home = process.env.PAPERCLIP_HOME?.trim() || path.join(os.homedir(), ".paperclip");
   const instanceId = process.env.PAPERCLIP_INSTANCE_ID?.trim() || "default";
-  return path.join(home, "instances", instanceId);
+  return resolvePaperclipSpaceRootForAdapter({
+    homeDir: home,
+    instanceId,
+    spaceId: process.env.PAPERCLIP_SPACE_ID?.trim() || undefined,
+  });
 }
 
 function defaultStateDir(companyId: string, agentId: string): string {
diff --git a/packages/adapters/claude-local/src/server/claude-config.ts b/packages/adapters/claude-local/src/server/claude-config.ts
index 5e4f22788a0..b323f6cc073 100644
--- a/packages/adapters/claude-local/src/server/claude-config.ts
+++ b/packages/adapters/claude-local/src/server/claude-config.ts
@@ -3,8 +3,8 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+import { resolvePaperclipSpaceRootForAdapter } from "@paperclipai/adapter-utils/server-utils";
 
-const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
 const SEEDED_SHARED_FILES = [
   ".credentials.json",
   "credentials.json",
@@ -92,11 +92,15 @@ export function resolveManagedClaudeConfigSeedDir(
   env: NodeJS.ProcessEnv,
   companyId?: string,
 ): string {
-  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
-  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
+  const spaceRoot = resolvePaperclipSpaceRootForAdapter({
+    homeDir: nonEmpty(env.PAPERCLIP_HOME) ?? undefined,
+    instanceId: nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? undefined,
+    spaceId: nonEmpty(env.PAPERCLIP_SPACE_ID) ?? undefined,
+    env,
+  });
   return companyId
-    ? path.resolve(paperclipHome, "instances", instanceId, "companies", companyId, "claude-config-seed")
-    : path.resolve(paperclipHome, "instances", instanceId, "claude-config-seed");
+    ? path.resolve(spaceRoot, "companies", companyId, "claude-config-seed")
+    : path.resolve(spaceRoot, "claude-config-seed");
 }
 
 export async function prepareClaudeConfigSeed(
diff --git a/packages/adapters/claude-local/src/server/prompt-cache.ts b/packages/adapters/claude-local/src/server/prompt-cache.ts
index ce719799979..91a1ad6f515 100644
--- a/packages/adapters/claude-local/src/server/prompt-cache.ts
+++ b/packages/adapters/claude-local/src/server/prompt-cache.ts
@@ -1,12 +1,13 @@
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { createHash, type Hash } from "node:crypto";
 import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
-import { ensurePaperclipSkillSymlink, type PaperclipSkillEntry } from "@paperclipai/adapter-utils/server-utils";
-
-const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
+import {
+  ensurePaperclipSkillSymlink,
+  resolvePaperclipSpaceRootForAdapter,
+  type PaperclipSkillEntry,
+} from "@paperclipai/adapter-utils/server-utils";
 
 type SkillEntry = PaperclipSkillEntry;
 
@@ -25,12 +26,14 @@ function resolveManagedClaudePromptCacheRoot(
   env: NodeJS.ProcessEnv,
   companyId: string,
 ): string {
-  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
-  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
+  const spaceRoot = resolvePaperclipSpaceRootForAdapter({
+    homeDir: nonEmpty(env.PAPERCLIP_HOME) ?? undefined,
+    instanceId: nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? undefined,
+    spaceId: nonEmpty(env.PAPERCLIP_SPACE_ID) ?? undefined,
+    env,
+  });
   return path.resolve(
-    paperclipHome,
-    "instances",
-    instanceId,
+    spaceRoot,
     "companies",
     companyId,
     "claude-prompt-cache",
diff --git a/packages/adapters/codex-local/src/server/codex-home.ts b/packages/adapters/codex-local/src/server/codex-home.ts
index 10b3ae96b4b..be9213e3326 100644
--- a/packages/adapters/codex-local/src/server/codex-home.ts
+++ b/packages/adapters/codex-local/src/server/codex-home.ts
@@ -2,11 +2,11 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+import { resolvePaperclipSpaceRootForAdapter } from "@paperclipai/adapter-utils/server-utils";
 
 const TRUTHY_ENV_RE = /^(1|true|yes|on)$/i;
 const COPIED_SHARED_FILES = ["config.json", "config.toml", "instructions.md"] as const;
 const SYMLINKED_SHARED_FILES = ["auth.json"] as const;
-const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
 
 function nonEmpty(value: string | undefined): string | null {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
@@ -31,11 +31,15 @@ export function resolveManagedCodexHomeDir(
   env: NodeJS.ProcessEnv,
   companyId?: string,
 ): string {
-  const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
-  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
+  const spaceRoot = resolvePaperclipSpaceRootForAdapter({
+    homeDir: nonEmpty(env.PAPERCLIP_HOME) ?? undefined,
+    instanceId: nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? undefined,
+    spaceId: nonEmpty(env.PAPERCLIP_SPACE_ID) ?? undefined,
+    env,
+  });
   return companyId
-    ? path.resolve(paperclipHome, "instances", instanceId, "companies", companyId, "codex-home")
-    : path.resolve(paperclipHome, "instances", instanceId, "codex-home");
+    ? path.resolve(spaceRoot, "companies", companyId, "codex-home")
+    : path.resolve(spaceRoot, "codex-home");
 }
 
 async function ensureParentDir(target: string): Promise<void> {
diff --git a/packages/db/src/backup.ts b/packages/db/src/backup.ts
index c11822c9503..40ab3e134e4 100644
--- a/packages/db/src/backup.ts
+++ b/packages/db/src/backup.ts
@@ -1,7 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { formatDatabaseBackupResult, runDatabaseBackup } from "./backup-lib.js";
+import {
+  expandHomePrefix,
+  resolveDefaultBackupDir,
+  resolvePaperclipConfigPathForInstance,
+} from "@paperclipai/shared/space-paths";
 
 type PartialConfig = {
   database?: {
@@ -15,30 +19,6 @@ type PartialConfig = {
   };
 };
 
-function expandHomePrefix(value: string): string {
-  if (value === "~") return os.homedir();
-  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
-  return value;
-}
-
-function resolvePaperclipHomeDir(): string {
-  const envHome = process.env.PAPERCLIP_HOME?.trim();
-  if (envHome) return path.resolve(expandHomePrefix(envHome));
-  return path.resolve(os.homedir(), ".paperclip");
-}
-
-function resolvePaperclipInstanceId(): string {
-  const raw = process.env.PAPERCLIP_INSTANCE_ID?.trim() || "default";
-  if (!/^[a-zA-Z0-9_-]+$/.test(raw)) {
-    throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
-  }
-  return raw;
-}
-
-function resolveDefaultConfigPath(): string {
-  return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "config.json");
-}
-
 function readConfig(configPath: string): PartialConfig | null {
   if (!existsSync(configPath)) return null;
   try {
@@ -72,10 +52,6 @@ function resolveConnectionString(config: PartialConfig | null): string {
   return `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
 }
 
-function resolveDefaultBackupDir(): string {
-  return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "data", "backups");
-}
-
 function resolveBackupDir(config: PartialConfig | null): string {
   const raw = config?.database?.backup?.dir;
   if (typeof raw === "string" && raw.trim().length > 0) {
@@ -89,7 +65,7 @@ function resolveRetentionDays(config: PartialConfig | null): number {
 }
 
 async function main() {
-  const configPath = resolveDefaultConfigPath();
+  const configPath = resolvePaperclipConfigPathForInstance();
   const config = readConfig(configPath);
   const connectionString = resolveConnectionString(config);
   const backupDir = resolveBackupDir(config);
diff --git a/packages/db/src/runtime-config.test.ts b/packages/db/src/runtime-config.test.ts
index 4627e6918d0..8e853d17709 100644
--- a/packages/db/src/runtime-config.test.ts
+++ b/packages/db/src/runtime-config.test.ts
@@ -105,4 +105,24 @@ describe("resolveDatabaseTarget", () => {
       source: "embedded-postgres@55444",
     });
   });
+
+  it("uses spaces/default for a fresh default embedded postgres target", () => {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-space-"));
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-cwd-"));
+    process.chdir(cwd);
+    process.env.PAPERCLIP_HOME = home;
+    delete process.env.PAPERCLIP_CONFIG;
+    delete process.env.DATABASE_URL;
+
+    const target = resolveDatabaseTarget();
+
+    expect(target).toMatchObject({
+      mode: "embedded-postgres",
+      dataDir: path.join(home, "instances", "default", "spaces", "default", "db"),
+      port: 54329,
+      source: "embedded-postgres@54329",
+      configPath: path.join(home, "instances", "default", "spaces", "default", "config.json"),
+      envPath: path.join(home, "instances", "default", "spaces", "default", ".env"),
+    });
+  });
 });
diff --git a/packages/db/src/runtime-config.ts b/packages/db/src/runtime-config.ts
index c6c64a38fa0..6e8740ef78d 100644
--- a/packages/db/src/runtime-config.ts
+++ b/packages/db/src/runtime-config.ts
@@ -1,11 +1,13 @@
 import { existsSync, readFileSync } from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import {
+  expandHomePrefix,
+  resolveDefaultEmbeddedPostgresDir,
+  resolvePaperclipConfigPathForInstance,
+  resolvePaperclipEnvPathForConfig,
+} from "@paperclipai/shared/space-paths";
 
-const DEFAULT_INSTANCE_ID = "default";
 const CONFIG_BASENAME = "config.json";
-const ENV_BASENAME = ".env";
-const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
 
 type PartialConfig = {
   database?: {
@@ -35,39 +37,6 @@ export type ResolvedDatabaseTarget =
       envPath: string;
     };
 
-function expandHomePrefix(value: string): string {
-  if (value === "~") return os.homedir();
-  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
-  return value;
-}
-
-function resolvePaperclipHomeDir(): string {
-  const envHome = process.env.PAPERCLIP_HOME?.trim();
-  if (envHome) return path.resolve(expandHomePrefix(envHome));
-  return path.resolve(os.homedir(), ".paperclip");
-}
-
-function resolvePaperclipInstanceId(): string {
-  const raw = process.env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_INSTANCE_ID;
-  if (!INSTANCE_ID_RE.test(raw)) {
-    throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
-  }
-  return raw;
-}
-
-function resolveDefaultConfigPath(): string {
-  return path.resolve(
-    resolvePaperclipHomeDir(),
-    "instances",
-    resolvePaperclipInstanceId(),
-    CONFIG_BASENAME,
-  );
-}
-
-function resolveDefaultEmbeddedPostgresDir(): string {
-  return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "db");
-}
-
 function resolveHomeAwarePath(value: string): string {
   return path.resolve(expandHomePrefix(value));
 }
@@ -89,11 +58,11 @@ function resolvePaperclipConfigPath(): string {
   if (process.env.PAPERCLIP_CONFIG?.trim()) {
     return path.resolve(process.env.PAPERCLIP_CONFIG.trim());
   }
-  return findConfigFileFromAncestors(process.cwd()) ?? resolveDefaultConfigPath();
+  return findConfigFileFromAncestors(process.cwd()) ?? resolvePaperclipConfigPathForInstance();
 }
 
 function resolvePaperclipEnvPath(configPath: string): string {
-  return path.resolve(path.dirname(configPath), ENV_BASENAME);
+  return resolvePaperclipEnvPathForConfig(configPath);
 }
 
 function parseEnvFile(contents: string): Record<string, string> {
diff --git a/packages/plugins/examples/plugin-bookmarks-example/.gitignore b/packages/plugins/examples/plugin-bookmarks-example/.gitignore
new file mode 100644
index 00000000000..0430cc35608
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/.gitignore
@@ -0,0 +1,3 @@
+dist
+node_modules
+.paperclip-sdk
diff --git a/packages/plugins/examples/plugin-bookmarks-example/README.md b/packages/plugins/examples/plugin-bookmarks-example/README.md
new file mode 100644
index 00000000000..17c48182f45
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/README.md
@@ -0,0 +1,53 @@
+# @paperclipai/plugin-bookmarks-example
+
+A first-party example plugin that adds a small but real product surface to Paperclip: a
+company-scoped bookmark library backed by a plugin database namespace and a local markdown
+folder.
+
+The package is a follow-up to the core plugin host surface work and is intended as a
+focused reference for plugin authors. The orchestration smoke example remains the
+acceptance fixture for the orchestration APIs; this plugin is the user-facing
+counterpart that exercises the broader UI + storage surface.
+
+## Surfaces exercised
+
+- **Plugin database namespace.** A migration creates a `bookmarks` table inside the
+  plugin's restricted Postgres schema. The worker reads and writes only that
+  namespace; the restricted SQL helpers prevent cross-namespace access.
+- **Local folders.** A `bookmarks-root` folder declaration is configured by the
+  operator and atomically receives one markdown file per bookmark via
+  `ctx.localFolders.writeTextAtomic`. The DB row remains the source of truth so
+  list and delete operations stay correct even when the folder is unconfigured
+  or the disk write fails.
+- **Scoped API routes.** Three plugin-owned routes (`list`, `create`, `delete`)
+  declare board-or-agent auth and resolve the company from query/body
+  parameters before the worker sees them.
+- **UI extension slots.** A full plugin page, a sidebar entry, a dashboard
+  widget, and a settings page are all wired up to the same worker handlers via
+  `usePluginData` / `usePluginAction`.
+
+## Install
+
+```sh
+pnpm --filter @paperclipai/plugin-bookmarks-example build
+pnpm paperclipai plugin install ./packages/plugins/examples/plugin-bookmarks-example
+```
+
+After install, configure the plugin's `bookmarks-root` local folder under the
+plugin's Folders settings to enable the markdown sidecar files. The plugin works
+without it (rows live in the database namespace), but operators that want
+shareable, file-backed snapshots should point the folder at a checked-in
+directory.
+
+## Development
+
+```sh
+pnpm --filter @paperclipai/plugin-bookmarks-example test
+pnpm --filter @paperclipai/plugin-bookmarks-example typecheck
+pnpm --filter @paperclipai/plugin-bookmarks-example build
+```
+
+The worker code uses module-scoped handler closures populated in `setup()`,
+mirroring the orchestration smoke example, so the handlers can be invoked from
+both `ctx.data` / `ctx.actions` (UI) and `onApiRequest` (HTTP) without
+duplicating logic.
diff --git a/packages/plugins/examples/plugin-bookmarks-example/esbuild.config.mjs b/packages/plugins/examples/plugin-bookmarks-example/esbuild.config.mjs
new file mode 100644
index 00000000000..b5cfd36ed95
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import esbuild from "esbuild";
+import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
+
+const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
+const watch = process.argv.includes("--watch");
+
+const workerCtx = await esbuild.context(presets.esbuild.worker);
+const manifestCtx = await esbuild.context(presets.esbuild.manifest);
+const uiCtx = await esbuild.context(presets.esbuild.ui);
+
+if (watch) {
+  await Promise.all([workerCtx.watch(), manifestCtx.watch(), uiCtx.watch()]);
+  console.log("esbuild watch mode enabled for worker, manifest, and ui");
+} else {
+  await Promise.all([workerCtx.rebuild(), manifestCtx.rebuild(), uiCtx.rebuild()]);
+  await Promise.all([workerCtx.dispose(), manifestCtx.dispose(), uiCtx.dispose()]);
+}
diff --git a/packages/plugins/examples/plugin-bookmarks-example/migrations/001_bookmarks.sql b/packages/plugins/examples/plugin-bookmarks-example/migrations/001_bookmarks.sql
new file mode 100644
index 00000000000..c326e11dab6
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/migrations/001_bookmarks.sql
@@ -0,0 +1,16 @@
+CREATE TABLE plugin_bookmarks_b34a9f8617.bookmarks (
+  id uuid PRIMARY KEY,
+  company_id uuid NOT NULL,
+  slug text NOT NULL,
+  url text NOT NULL,
+  title text NOT NULL,
+  notes text NOT NULL DEFAULT '',
+  tags text[] NOT NULL DEFAULT '{}',
+  file_path text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT bookmarks_company_slug_uq UNIQUE (company_id, slug)
+);
+
+CREATE INDEX bookmarks_company_idx
+  ON plugin_bookmarks_b34a9f8617.bookmarks (company_id, created_at DESC);
diff --git a/packages/plugins/examples/plugin-bookmarks-example/package.json b/packages/plugins/examples/plugin-bookmarks-example/package.json
new file mode 100644
index 00000000000..be68a4b2e03
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/package.json
@@ -0,0 +1,48 @@
+{
+  "name": "@paperclipai/plugin-bookmarks-example",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "description": "First-party example plugin: company-scoped bookmark library backed by a plugin database namespace and a local markdown folder.",
+  "scripts": {
+    "prebuild": "pnpm --filter @paperclipai/plugin-sdk ensure-build-deps",
+    "build": "node ./esbuild.config.mjs",
+    "build:rollup": "rollup -c",
+    "dev": "node ./esbuild.config.mjs --watch",
+    "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4178",
+    "test": "vitest run --config ./vitest.config.ts",
+    "typecheck": "pnpm --filter @paperclipai/plugin-sdk ensure-build-deps && tsc --noEmit"
+  },
+  "paperclipPlugin": {
+    "manifest": "./dist/manifest.js",
+    "worker": "./dist/worker.js",
+    "ui": "./dist/ui/"
+  },
+  "keywords": [
+    "paperclip",
+    "plugin",
+    "example",
+    "bookmarks",
+    "knowledge"
+  ],
+  "author": "Paperclip",
+  "license": "MIT",
+  "dependencies": {
+    "@paperclipai/plugin-sdk": "workspace:*"
+  },
+  "devDependencies": {
+    "@paperclipai/shared": "workspace:*",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.0.8",
+    "esbuild": "^0.27.3",
+    "rollup": "^4.38.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}
diff --git a/packages/plugins/examples/plugin-bookmarks-example/rollup.config.mjs b/packages/plugins/examples/plugin-bookmarks-example/rollup.config.mjs
new file mode 100644
index 00000000000..ccee40a7443
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/rollup.config.mjs
@@ -0,0 +1,28 @@
+import { nodeResolve } from "@rollup/plugin-node-resolve";
+import typescript from "@rollup/plugin-typescript";
+import { createPluginBundlerPresets } from "@paperclipai/plugin-sdk/bundlers";
+
+const presets = createPluginBundlerPresets({ uiEntry: "src/ui/index.tsx" });
+
+function withPlugins(config) {
+  if (!config) return null;
+  return {
+    ...config,
+    plugins: [
+      nodeResolve({
+        extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs"],
+      }),
+      typescript({
+        tsconfig: "./tsconfig.json",
+        declaration: false,
+        declarationMap: false,
+      }),
+    ],
+  };
+}
+
+export default [
+  withPlugins(presets.rollup.manifest),
+  withPlugins(presets.rollup.worker),
+  withPlugins(presets.rollup.ui),
+].filter(Boolean);
diff --git a/packages/plugins/examples/plugin-bookmarks-example/src/manifest.ts b/packages/plugins/examples/plugin-bookmarks-example/src/manifest.ts
new file mode 100644
index 00000000000..402efb51369
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/src/manifest.ts
@@ -0,0 +1,102 @@
+import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
+
+export const PLUGIN_ID = "paperclipai.plugin-bookmarks-example";
+export const BOOKMARKS_FOLDER_KEY = "bookmarks-root";
+
+const manifest: PaperclipPluginManifestV1 = {
+  id: PLUGIN_ID,
+  apiVersion: 1,
+  version: "0.1.0",
+  displayName: "Bookmarks (Example)",
+  description:
+    "First-party example plugin: company-scoped bookmark library backed by a plugin database namespace and a local markdown folder. Demonstrates scoped API routes, local folders, dashboard widget, and a plugin page.",
+  author: "Paperclip",
+  categories: ["workspace", "ui"],
+  capabilities: [
+    "api.routes.register",
+    "database.namespace.migrate",
+    "database.namespace.read",
+    "database.namespace.write",
+    "local.folders",
+    "companies.read",
+    "ui.dashboardWidget.register",
+    "ui.page.register",
+    "ui.sidebar.register",
+    "instance.settings.register",
+  ],
+  entrypoints: {
+    worker: "./dist/worker.js",
+    ui: "./dist/ui",
+  },
+  database: {
+    namespaceSlug: "bookmarks",
+    migrationsDir: "migrations",
+  },
+  localFolders: [
+    {
+      folderKey: BOOKMARKS_FOLDER_KEY,
+      displayName: "Bookmarks root",
+      description:
+        "Company-scoped local folder that stores one markdown file per bookmark. Each file uses YAML frontmatter for url, title, tags, and notes.",
+      access: "readWrite",
+      requiredDirectories: ["bookmarks"],
+    },
+  ],
+  apiRoutes: [
+    {
+      routeKey: "list",
+      method: "GET",
+      path: "/bookmarks",
+      auth: "board-or-agent",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" },
+    },
+    {
+      routeKey: "create",
+      method: "POST",
+      path: "/bookmarks",
+      auth: "board-or-agent",
+      capability: "api.routes.register",
+      companyResolution: { from: "body", key: "companyId" },
+    },
+    {
+      routeKey: "delete",
+      method: "DELETE",
+      path: "/bookmarks/:slug",
+      auth: "board-or-agent",
+      capability: "api.routes.register",
+      companyResolution: { from: "query", key: "companyId" },
+    },
+  ],
+  ui: {
+    slots: [
+      {
+        type: "page",
+        id: "bookmarks-page",
+        displayName: "Bookmarks",
+        exportName: "BookmarksPage",
+        routePath: "bookmarks",
+      },
+      {
+        type: "sidebar",
+        id: "bookmarks-sidebar-link",
+        displayName: "Bookmarks",
+        exportName: "BookmarksSidebarLink",
+      },
+      {
+        type: "dashboardWidget",
+        id: "bookmarks-widget",
+        displayName: "Bookmarks",
+        exportName: "BookmarksDashboardWidget",
+      },
+      {
+        type: "settingsPage",
+        id: "bookmarks-settings",
+        displayName: "Bookmarks",
+        exportName: "BookmarksSettingsPage",
+      },
+    ],
+  },
+};
+
+export default manifest;
diff --git a/packages/plugins/examples/plugin-bookmarks-example/src/ui/index.tsx b/packages/plugins/examples/plugin-bookmarks-example/src/ui/index.tsx
new file mode 100644
index 00000000000..b832006df25
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/src/ui/index.tsx
@@ -0,0 +1,359 @@
+import {
+  usePluginAction,
+  usePluginData,
+  type PluginPageProps,
+  type PluginSettingsPageProps,
+  type PluginSidebarProps,
+  type PluginWidgetProps,
+} from "@paperclipai/plugin-sdk/ui";
+import { useMemo, useState, type CSSProperties, type FormEvent } from "react";
+
+interface BookmarkRecord {
+  id: string;
+  companyId: string;
+  slug: string;
+  url: string;
+  title: string;
+  notes: string;
+  tags: string[];
+  filePath: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface BookmarkListResult {
+  databaseNamespace: string;
+  bookmarks: BookmarkRecord[];
+}
+
+const containerStyle: CSSProperties = {
+  display: "grid",
+  gap: 16,
+  font: "13px system-ui, sans-serif",
+  color: "#111827",
+  padding: 16,
+  maxWidth: 760,
+};
+
+const cardStyle: CSSProperties = {
+  border: "1px solid #e5e7eb",
+  borderRadius: 8,
+  padding: 12,
+  background: "#fff",
+};
+
+const inputStyle: CSSProperties = {
+  border: "1px solid #d1d5db",
+  borderRadius: 6,
+  padding: "6px 8px",
+  font: "inherit",
+  width: "100%",
+};
+
+const buttonStyle: CSSProperties = {
+  border: "1px solid #1f2937",
+  background: "#111827",
+  color: "#fff",
+  borderRadius: 6,
+  padding: "6px 10px",
+  font: "inherit",
+  cursor: "pointer",
+};
+
+const subtleButtonStyle: CSSProperties = {
+  border: "1px solid #d1d5db",
+  background: "#fff",
+  color: "#111827",
+  borderRadius: 6,
+  padding: "4px 8px",
+  font: "inherit",
+  cursor: "pointer",
+};
+
+const tagStyle: CSSProperties = {
+  display: "inline-block",
+  border: "1px solid #cbd5f5",
+  background: "#eef2ff",
+  color: "#3730a3",
+  borderRadius: 999,
+  padding: "1px 8px",
+  marginRight: 4,
+  fontSize: 11,
+};
+
+function parseTagInput(raw: string): string[] {
+  return raw
+    .split(/[\s,]+/)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function formatDate(value: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleString();
+}
+
+function BookmarksList({
+  result,
+  onDelete,
+  loading,
+}: {
+  result: BookmarkListResult | null;
+  onDelete: (slug: string) => Promise<void>;
+  loading: boolean;
+}) {
+  if (loading) return <div>Loading bookmarks…</div>;
+  if (!result) return null;
+  if (result.bookmarks.length === 0) {
+    return <div style={{ color: "#6b7280" }}>No bookmarks yet.</div>;
+  }
+  return (
+    <div style={{ display: "grid", gap: 10 }}>
+      {result.bookmarks.map((bookmark) => (
+        <div key={bookmark.id} style={cardStyle}>
+          <div style={{ display: "flex", justifyContent: "space-between", gap: 12 }}>
+            <a
+              href={bookmark.url}
+              target="_blank"
+              rel="noreferrer"
+              style={{ color: "#1d4ed8", fontWeight: 600 }}
+            >
+              {bookmark.title}
+            </a>
+            <button
+              type="button"
+              style={subtleButtonStyle}
+              onClick={() => {
+                void onDelete(bookmark.slug);
+              }}
+            >
+              Delete
+            </button>
+          </div>
+          <div style={{ color: "#6b7280", fontSize: 12, wordBreak: "break-all" }}>{bookmark.url}</div>
+          {bookmark.tags.length > 0 ? (
+            <div style={{ marginTop: 6 }}>
+              {bookmark.tags.map((tag) => (
+                <span key={tag} style={tagStyle}>
+                  {tag}
+                </span>
+              ))}
+            </div>
+          ) : null}
+          {bookmark.notes ? (
+            <div style={{ marginTop: 6, whiteSpace: "pre-wrap" }}>{bookmark.notes}</div>
+          ) : null}
+          <div style={{ marginTop: 6, color: "#9ca3af", fontSize: 11 }}>
+            Added {formatDate(bookmark.createdAt)} · {bookmark.filePath}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function BookmarksSurface({ companyId }: { companyId: string }) {
+  const [search, setSearch] = useState("");
+  const [tag, setTag] = useState("");
+  const [url, setUrl] = useState("");
+  const [title, setTitle] = useState("");
+  const [tagsRaw, setTagsRaw] = useState("");
+  const [notes, setNotes] = useState("");
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  const listParams = useMemo(
+    () => ({ companyId, search: search.trim() || null, tag: tag.trim() || null }),
+    [companyId, search, tag],
+  );
+
+  const { data, loading, error, refresh } = usePluginData<BookmarkListResult>("list", listParams);
+  const create = usePluginAction("create");
+  const remove = usePluginAction("delete");
+
+  async function handleCreate(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setErrorMessage(null);
+    try {
+      await create({
+        companyId,
+        url,
+        title: title || null,
+        notes: notes || null,
+        tags: parseTagInput(tagsRaw),
+      });
+      setUrl("");
+      setTitle("");
+      setNotes("");
+      setTagsRaw("");
+      refresh();
+    } catch (cause) {
+      setErrorMessage(cause instanceof Error ? cause.message : "Failed to add bookmark");
+    }
+  }
+
+  async function handleDelete(slug: string) {
+    setErrorMessage(null);
+    try {
+      await remove({ companyId, slug });
+      refresh();
+    } catch (cause) {
+      setErrorMessage(cause instanceof Error ? cause.message : "Failed to delete bookmark");
+    }
+  }
+
+  return (
+    <div style={containerStyle}>
+      <header style={{ display: "grid", gap: 4 }}>
+        <h1 style={{ fontSize: 20, margin: 0 }}>Bookmarks</h1>
+        <div style={{ color: "#6b7280" }}>
+          Company-scoped bookmark library backed by a plugin database namespace and a local markdown
+          folder.
+        </div>
+      </header>
+
+      <form onSubmit={handleCreate} style={{ ...cardStyle, display: "grid", gap: 8 }}>
+        <strong>Add bookmark</strong>
+        <input
+          style={inputStyle}
+          required
+          type="url"
+          placeholder="https://example.com"
+          value={url}
+          onChange={(event) => setUrl(event.target.value)}
+        />
+        <input
+          style={inputStyle}
+          placeholder="Title (defaults to URL)"
+          value={title}
+          onChange={(event) => setTitle(event.target.value)}
+        />
+        <input
+          style={inputStyle}
+          placeholder="Tags (comma or space separated)"
+          value={tagsRaw}
+          onChange={(event) => setTagsRaw(event.target.value)}
+        />
+        <textarea
+          style={{ ...inputStyle, minHeight: 60, resize: "vertical" }}
+          placeholder="Notes (optional)"
+          value={notes}
+          onChange={(event) => setNotes(event.target.value)}
+        />
+        <div>
+          <button type="submit" style={buttonStyle}>
+            Save
+          </button>
+        </div>
+        {errorMessage ? <div style={{ color: "#b91c1c" }}>{errorMessage}</div> : null}
+      </form>
+
+      <div style={{ ...cardStyle, display: "grid", gap: 8 }}>
+        <strong>Search</strong>
+        <div style={{ display: "flex", gap: 8 }}>
+          <input
+            style={inputStyle}
+            placeholder="Search title, url, or notes"
+            value={search}
+            onChange={(event) => setSearch(event.target.value)}
+          />
+          <input
+            style={{ ...inputStyle, maxWidth: 180 }}
+            placeholder="Filter by tag"
+            value={tag}
+            onChange={(event) => setTag(event.target.value)}
+          />
+        </div>
+      </div>
+
+      {error ? <div style={{ color: "#b91c1c" }}>{error.message}</div> : null}
+      <BookmarksList result={data ?? null} onDelete={handleDelete} loading={loading} />
+    </div>
+  );
+}
+
+function MissingCompanyNotice({ surface }: { surface: string }) {
+  return (
+    <div style={containerStyle}>
+      <div style={cardStyle}>
+        <strong>{surface}</strong>
+        <div style={{ color: "#6b7280", marginTop: 4 }}>
+          Open this plugin from a company workspace — bookmarks are scoped per company.
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function BookmarksPage({ context }: PluginPageProps) {
+  if (!context.companyId) return <MissingCompanyNotice surface="Bookmarks" />;
+  return <BookmarksSurface companyId={context.companyId} />;
+}
+
+export function BookmarksSettingsPage({ context }: PluginSettingsPageProps) {
+  const companyId = context.companyId ?? "";
+  const { data, loading, error } = usePluginData<BookmarkListResult>(
+    "list",
+    companyId ? { companyId, limit: 1 } : undefined,
+  );
+  if (!companyId) return <MissingCompanyNotice surface="Bookmarks settings" />;
+  return (
+    <div style={containerStyle}>
+      <h1 style={{ fontSize: 18, margin: 0 }}>Bookmarks settings</h1>
+      <div style={cardStyle}>
+        <div style={{ display: "grid", gap: 4 }}>
+          <div>
+            <strong>Database namespace:</strong>{" "}
+            <code>{loading ? "…" : (data?.databaseNamespace ?? "not configured")}</code>
+          </div>
+          <div>
+            Configure the <code>bookmarks-root</code> local folder under the plugin Folders settings
+            so new bookmarks can be persisted to disk in addition to the database namespace.
+          </div>
+          {error ? <div style={{ color: "#b91c1c" }}>{error.message}</div> : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function BookmarksDashboardWidget({ context }: PluginWidgetProps) {
+  const companyId = context.companyId;
+  const { data, loading, error } = usePluginData<BookmarkListResult>(
+    "list",
+    companyId ? { companyId, limit: 5 } : undefined,
+  );
+
+  if (!companyId) return null;
+  if (loading) return <div style={{ font: "12px system-ui, sans-serif" }}>Loading bookmarks…</div>;
+  if (error) return <div style={{ color: "#b91c1c" }}>Bookmarks error: {error.message}</div>;
+  const bookmarks = data?.bookmarks ?? [];
+
+  return (
+    <div style={{ display: "grid", gap: 6, font: "13px system-ui, sans-serif" }}>
+      <strong>Recent bookmarks</strong>
+      {bookmarks.length === 0 ? (
+        <div style={{ color: "#6b7280" }}>No bookmarks yet.</div>
+      ) : (
+        <ul style={{ margin: 0, paddingLeft: 18 }}>
+          {bookmarks.map((bookmark) => (
+            <li key={bookmark.id}>
+              <a
+                href={bookmark.url}
+                target="_blank"
+                rel="noreferrer"
+                style={{ color: "#1d4ed8" }}
+              >
+                {bookmark.title}
+              </a>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+export function BookmarksSidebarLink(_props: PluginSidebarProps) {
+  return <span>Bookmarks</span>;
+}
diff --git a/packages/plugins/examples/plugin-bookmarks-example/src/worker.ts b/packages/plugins/examples/plugin-bookmarks-example/src/worker.ts
new file mode 100644
index 00000000000..ce35410df50
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/src/worker.ts
@@ -0,0 +1,421 @@
+import { randomUUID } from "node:crypto";
+import {
+  definePlugin,
+  runWorker,
+  type PluginApiRequestInput,
+  type PluginApiResponse,
+  type PluginContext,
+} from "@paperclipai/plugin-sdk";
+import { BOOKMARKS_FOLDER_KEY } from "./manifest.js";
+
+export interface BookmarkRecord {
+  id: string;
+  companyId: string;
+  slug: string;
+  url: string;
+  title: string;
+  notes: string;
+  tags: string[];
+  filePath: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface BookmarkInput {
+  url: string;
+  title?: string | null;
+  notes?: string | null;
+  tags?: string[] | null;
+  slug?: string | null;
+}
+
+export interface BookmarkListResult {
+  databaseNamespace: string;
+  bookmarks: BookmarkRecord[];
+}
+
+const SLUG_RESERVED = new Set(["", ".", "..", "_"]);
+const MAX_TAGS = 16;
+const MAX_TAG_LENGTH = 32;
+const MAX_TITLE_LENGTH = 200;
+const MAX_NOTES_LENGTH = 4000;
+const MAX_BOOKMARKS_PER_LIST = 200;
+
+function tableName(namespace: string): string {
+  return `${namespace}.bookmarks`;
+}
+
+function asNonEmptyString(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizeUrl(value: unknown): string {
+  const raw = asNonEmptyString(value);
+  if (!raw) {
+    throw new Error("`url` is required");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error("`url` must be a valid absolute URL");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("`url` must use http or https");
+  }
+  return parsed.toString();
+}
+
+function normalizeTitle(value: unknown, fallback: string): string {
+  const raw = asNonEmptyString(value);
+  const candidate = raw ?? fallback;
+  return candidate.length > MAX_TITLE_LENGTH ? candidate.slice(0, MAX_TITLE_LENGTH) : candidate;
+}
+
+function normalizeNotes(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value !== "string") {
+    throw new Error("`notes` must be a string when provided");
+  }
+  if (value.length > MAX_NOTES_LENGTH) {
+    throw new Error(`\`notes\` must be ${MAX_NOTES_LENGTH} characters or fewer`);
+  }
+  return value;
+}
+
+function normalizeTags(value: unknown): string[] {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error("`tags` must be an array of strings when provided");
+  }
+  const seen = new Set<string>();
+  const tags: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") {
+      throw new Error("`tags` must contain only strings");
+    }
+    const cleaned = entry.trim().toLowerCase();
+    if (!cleaned) continue;
+    if (cleaned.length > MAX_TAG_LENGTH) {
+      throw new Error(`tag "${entry}" exceeds ${MAX_TAG_LENGTH} characters`);
+    }
+    if (!/^[a-z0-9][a-z0-9_-]*$/.test(cleaned)) {
+      throw new Error(`tag "${entry}" must use lowercase letters, digits, hyphens, or underscores`);
+    }
+    if (seen.has(cleaned)) continue;
+    seen.add(cleaned);
+    tags.push(cleaned);
+    if (tags.length > MAX_TAGS) {
+      throw new Error(`bookmarks accept at most ${MAX_TAGS} tags`);
+    }
+  }
+  return tags;
+}
+
+export function deriveSlugCandidate(url: string, title: string | null): string {
+  const titleSource = title?.trim();
+  if (titleSource) {
+    const slug = slugify(titleSource);
+    if (slug) return slug;
+  }
+  try {
+    const parsed = new URL(url);
+    const base = `${parsed.hostname}${parsed.pathname}`;
+    const slug = slugify(base);
+    if (slug) return slug;
+  } catch {
+    // fall through
+  }
+  return "bookmark";
+}
+
+function slugify(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+}
+
+function normalizeSlug(value: unknown, fallback: string): string {
+  const raw = asNonEmptyString(value);
+  if (!raw) {
+    if (SLUG_RESERVED.has(fallback)) return "bookmark";
+    return fallback;
+  }
+  const cleaned = slugify(raw);
+  if (!cleaned || SLUG_RESERVED.has(cleaned)) {
+    throw new Error("`slug` must contain at least one alphanumeric character");
+  }
+  return cleaned;
+}
+
+function bookmarkFilePath(slug: string): string {
+  return `bookmarks/${slug}.md`;
+}
+
+export function renderBookmarkMarkdown(bookmark: BookmarkRecord): string {
+  const frontmatter = [
+    "---",
+    `slug: ${bookmark.slug}`,
+    `url: ${bookmark.url}`,
+    `title: ${escapeFrontmatterValue(bookmark.title)}`,
+    `tags: [${bookmark.tags.map((tag) => JSON.stringify(tag)).join(", ")}]`,
+    `created_at: ${bookmark.createdAt}`,
+    `updated_at: ${bookmark.updatedAt}`,
+    "---",
+    "",
+  ].join("\n");
+  if (bookmark.notes.length === 0) return frontmatter;
+  return `${frontmatter}\n${bookmark.notes.trimEnd()}\n`;
+}
+
+function escapeFrontmatterValue(value: string): string {
+  if (/^[A-Za-z0-9 _.,:'/()&-]+$/.test(value) && !value.startsWith(" ")) {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
+interface BookmarkRow {
+  id: string;
+  company_id: string;
+  slug: string;
+  url: string;
+  title: string;
+  notes: string;
+  tags: string[];
+  file_path: string;
+  created_at: string | Date;
+  updated_at: string | Date;
+}
+
+function rowToBookmark(row: BookmarkRow): BookmarkRecord {
+  return {
+    id: row.id,
+    companyId: row.company_id,
+    slug: row.slug,
+    url: row.url,
+    title: row.title,
+    notes: row.notes,
+    tags: Array.isArray(row.tags) ? [...row.tags] : [],
+    filePath: row.file_path,
+    createdAt: typeof row.created_at === "string" ? row.created_at : row.created_at.toISOString(),
+    updatedAt: typeof row.updated_at === "string" ? row.updated_at : row.updated_at.toISOString(),
+  };
+}
+
+async function listBookmarks(
+  ctx: PluginContext,
+  companyId: string,
+  search: string | null,
+  tag: string | null,
+  limit: number,
+): Promise<BookmarkRecord[]> {
+  const params: unknown[] = [companyId];
+  let where = "company_id = $1";
+  if (search) {
+    params.push(`%${search.toLowerCase()}%`);
+    const idx = params.length;
+    where += ` AND (lower(title) LIKE $${idx} OR lower(url) LIKE $${idx} OR lower(notes) LIKE $${idx})`;
+  }
+  if (tag) {
+    params.push(tag);
+    where += ` AND $${params.length} = ANY(tags)`;
+  }
+  params.push(Math.min(Math.max(limit, 1), MAX_BOOKMARKS_PER_LIST));
+  const rows = await ctx.db.query<BookmarkRow>(
+    `SELECT id, company_id, slug, url, title, notes, tags, file_path, created_at, updated_at
+     FROM ${tableName(ctx.db.namespace)}
+     WHERE ${where}
+     ORDER BY created_at DESC
+     LIMIT $${params.length}`,
+    params,
+  );
+  return rows.map(rowToBookmark);
+}
+
+export async function createBookmark(
+  ctx: PluginContext,
+  companyId: string,
+  input: BookmarkInput,
+): Promise<BookmarkRecord> {
+  const url = normalizeUrl(input.url);
+  const inputTitle = asNonEmptyString(input.title);
+  const title = inputTitle ? normalizeTitle(inputTitle, url) : url;
+  const notes = normalizeNotes(input.notes);
+  const tags = normalizeTags(input.tags);
+  const fallbackSlug = deriveSlugCandidate(url, inputTitle);
+  const slug = input.slug != null
+    ? normalizeSlug(input.slug, fallbackSlug)
+    : (SLUG_RESERVED.has(fallbackSlug) ? "bookmark" : fallbackSlug);
+  const id = randomUUID();
+  const filePath = bookmarkFilePath(slug);
+  const now = new Date().toISOString();
+
+  const insert = await ctx.db.execute(
+    `INSERT INTO ${tableName(ctx.db.namespace)}
+       (id, company_id, slug, url, title, notes, tags, file_path, created_at, updated_at)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $9)
+     ON CONFLICT (company_id, slug) DO NOTHING`,
+    [id, companyId, slug, url, title, notes, tags, filePath, now],
+  );
+  if (insert.rowCount === 0) {
+    throw new Error(`Bookmark with slug "${slug}" already exists`);
+  }
+
+  const bookmark: BookmarkRecord = {
+    id,
+    companyId,
+    slug,
+    url,
+    title,
+    notes,
+    tags,
+    filePath,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  try {
+    await ctx.localFolders.writeTextAtomic(
+      companyId,
+      BOOKMARKS_FOLDER_KEY,
+      filePath,
+      renderBookmarkMarkdown(bookmark),
+    );
+  } catch (error) {
+    ctx.logger.warn("Failed to write bookmark markdown to local folder; row kept", {
+      slug,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+
+  return bookmark;
+}
+
+export async function deleteBookmark(
+  ctx: PluginContext,
+  companyId: string,
+  slug: string,
+): Promise<{ deleted: boolean; slug: string }> {
+  const result = await ctx.db.execute(
+    `DELETE FROM ${tableName(ctx.db.namespace)} WHERE company_id = $1 AND slug = $2`,
+    [companyId, slug],
+  );
+  if (result.rowCount > 0) {
+    try {
+      await ctx.localFolders.deleteFile(companyId, BOOKMARKS_FOLDER_KEY, bookmarkFilePath(slug));
+    } catch (error) {
+      ctx.logger.warn("Failed to delete bookmark markdown from local folder; row was removed", {
+        slug,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return { deleted: result.rowCount > 0, slug };
+}
+
+let listHandler: ((companyId: string, search: string | null, tag: string | null, limit: number) => Promise<BookmarkListResult>) | null = null;
+let createHandler: ((companyId: string, input: BookmarkInput) => Promise<BookmarkRecord>) | null = null;
+let deleteHandler: ((companyId: string, slug: string) => Promise<{ deleted: boolean; slug: string }>) | null = null;
+
+const plugin = definePlugin({
+  async setup(ctx) {
+    listHandler = (companyId, search, tag, limit) =>
+      listBookmarks(ctx, companyId, search, tag, limit).then((bookmarks) => ({
+        databaseNamespace: ctx.db.namespace,
+        bookmarks,
+      }));
+    createHandler = (companyId, input) => createBookmark(ctx, companyId, input);
+    deleteHandler = (companyId, slug) => deleteBookmark(ctx, companyId, slug);
+
+    ctx.data.register("list", async (params) => {
+      const companyId = asNonEmptyString(params.companyId);
+      if (!companyId) throw new Error("companyId is required");
+      const search = asNonEmptyString(params.search)?.toLowerCase() ?? null;
+      const tag = asNonEmptyString(params.tag)?.toLowerCase() ?? null;
+      const limit = typeof params.limit === "number" ? params.limit : 50;
+      if (!listHandler) throw new Error("Bookmarks plugin not ready");
+      return listHandler(companyId, search, tag, limit);
+    });
+
+    ctx.actions.register("create", async (params) => {
+      const companyId = asNonEmptyString(params.companyId);
+      if (!companyId) throw new Error("companyId is required");
+      if (!createHandler) throw new Error("Bookmarks plugin not ready");
+      return createHandler(companyId, {
+        url: typeof params.url === "string" ? params.url : "",
+        title: typeof params.title === "string" ? params.title : null,
+        notes: typeof params.notes === "string" ? params.notes : null,
+        tags: Array.isArray(params.tags) ? (params.tags as unknown[] as string[]) : null,
+        slug: typeof params.slug === "string" ? params.slug : null,
+      });
+    });
+
+    ctx.actions.register("delete", async (params) => {
+      const companyId = asNonEmptyString(params.companyId);
+      const slug = asNonEmptyString(params.slug);
+      if (!companyId || !slug) throw new Error("companyId and slug are required");
+      if (!deleteHandler) throw new Error("Bookmarks plugin not ready");
+      return deleteHandler(companyId, slug);
+    });
+  },
+
+  async onApiRequest(input: PluginApiRequestInput): Promise<PluginApiResponse> {
+    switch (input.routeKey) {
+      case "list": {
+        if (!listHandler) return { status: 503, body: { error: "Bookmarks plugin not ready" } };
+        const search = asNonEmptyString(input.query.search)?.toLowerCase() ?? null;
+        const tag = asNonEmptyString(input.query.tag)?.toLowerCase() ?? null;
+        const limitRaw = asNonEmptyString(input.query.limit);
+        const parsedLimit = limitRaw ? Number.parseInt(limitRaw, 10) : 50;
+        const limit = Number.isFinite(parsedLimit) ? parsedLimit : 50;
+        return { body: await listHandler(input.companyId, search, tag, limit) };
+      }
+      case "create": {
+        if (!createHandler) return { status: 503, body: { error: "Bookmarks plugin not ready" } };
+        const body = (input.body ?? {}) as Record<string, unknown>;
+        try {
+          const bookmark = await createHandler(input.companyId, {
+            url: typeof body.url === "string" ? body.url : "",
+            title: typeof body.title === "string" ? body.title : null,
+            notes: typeof body.notes === "string" ? body.notes : null,
+            tags: Array.isArray(body.tags) ? (body.tags as unknown[] as string[]) : null,
+            slug: typeof body.slug === "string" ? body.slug : null,
+          });
+          return { status: 201, body: bookmark };
+        } catch (error) {
+          return {
+            status: 400,
+            body: { error: error instanceof Error ? error.message : "Invalid bookmark" },
+          };
+        }
+      }
+      case "delete": {
+        if (!deleteHandler) return { status: 503, body: { error: "Bookmarks plugin not ready" } };
+        const slug = input.params.slug;
+        if (!slug) return { status: 400, body: { error: "slug is required" } };
+        const result = await deleteHandler(input.companyId, slug);
+        return { status: result.deleted ? 200 : 404, body: result };
+      }
+      default:
+        return { status: 404, body: { error: `Unknown bookmarks route: ${input.routeKey}` } };
+    }
+  },
+
+  async onHealth() {
+    return {
+      status: "ok",
+      message: "Bookmarks plugin worker is running",
+      details: {
+        surfaces: ["scoped-api-route", "database-namespace", "local-folder", "page", "dashboard-widget"],
+      },
+    };
+  },
+});
+
+export default plugin;
+runWorker(plugin, import.meta.url);
diff --git a/packages/plugins/examples/plugin-bookmarks-example/tests/plugin.spec.ts b/packages/plugins/examples/plugin-bookmarks-example/tests/plugin.spec.ts
new file mode 100644
index 00000000000..0812a980339
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/tests/plugin.spec.ts
@@ -0,0 +1,370 @@
+import { describe, expect, it, vi } from "vitest";
+import { pluginManifestV1Schema } from "@paperclipai/shared";
+import { createTestHarness } from "@paperclipai/plugin-sdk/testing";
+import manifest, { BOOKMARKS_FOLDER_KEY, PLUGIN_ID } from "../src/manifest.js";
+import plugin, {
+  type BookmarkListResult,
+  type BookmarkRecord,
+  deriveSlugCandidate,
+  renderBookmarkMarkdown,
+} from "../src/worker.js";
+
+interface BookmarkRow {
+  id: string;
+  company_id: string;
+  slug: string;
+  url: string;
+  title: string;
+  notes: string;
+  tags: string[];
+  file_path: string;
+  created_at: string;
+  updated_at: string;
+}
+
+function makeInMemoryBookmarksDb() {
+  const rows: BookmarkRow[] = [];
+  return {
+    rows,
+    namespace: "plugin_bookmarks_test",
+    async query<T>(sql: string, params?: unknown[]): Promise<T[]> {
+      if (!sql.includes("FROM plugin_bookmarks_test.bookmarks")) return [];
+      const companyId = params?.[0] as string;
+      let filtered = rows.filter((row) => row.company_id === companyId);
+      if (sql.includes("LIKE $2")) {
+        const like = (params?.[1] as string) ?? "";
+        const needle = like.replace(/%/g, "").toLowerCase();
+        filtered = filtered.filter((row) =>
+          row.title.toLowerCase().includes(needle) ||
+          row.url.toLowerCase().includes(needle) ||
+          row.notes.toLowerCase().includes(needle));
+      }
+      const tagParamIndex = sql.match(/\$(\d+) = ANY\(tags\)/)?.[1];
+      if (tagParamIndex) {
+        const tag = params?.[Number(tagParamIndex) - 1] as string;
+        filtered = filtered.filter((row) => row.tags.includes(tag));
+      }
+      filtered = [...filtered].sort((a, b) => b.created_at.localeCompare(a.created_at));
+      const limitParamIndex = sql.match(/LIMIT \$(\d+)/)?.[1];
+      if (limitParamIndex) {
+        const limit = params?.[Number(limitParamIndex) - 1] as number;
+        filtered = filtered.slice(0, limit);
+      }
+      return filtered as unknown as T[];
+    },
+    async execute(sql: string, params?: unknown[]): Promise<{ rowCount: number }> {
+      if (sql.startsWith("INSERT INTO plugin_bookmarks_test.bookmarks")) {
+        const [id, companyId, slug, url, title, notes, tags, filePath, createdAt] =
+          params as [string, string, string, string, string, string, string[], string, string];
+        if (rows.some((row) => row.company_id === companyId && row.slug === slug)) {
+          return { rowCount: 0 };
+        }
+        rows.push({
+          id,
+          company_id: companyId,
+          slug,
+          url,
+          title,
+          notes,
+          tags: [...tags],
+          file_path: filePath,
+          created_at: createdAt,
+          updated_at: createdAt,
+        });
+        return { rowCount: 1 };
+      }
+      if (sql.startsWith("DELETE FROM plugin_bookmarks_test.bookmarks")) {
+        const [companyId, slug] = params as [string, string];
+        const before = rows.length;
+        for (let i = rows.length - 1; i >= 0; i -= 1) {
+          if (rows[i]!.company_id === companyId && rows[i]!.slug === slug) rows.splice(i, 1);
+        }
+        return { rowCount: before - rows.length };
+      }
+      return { rowCount: 0 };
+    },
+  };
+}
+
+function makeHarness() {
+  const harness = createTestHarness({ manifest });
+  const db = makeInMemoryBookmarksDb();
+  harness.ctx.db = db;
+  return { harness, db };
+}
+
+function localFolderStatus(folderKey = BOOKMARKS_FOLDER_KEY) {
+  return {
+    folderKey,
+    configured: true,
+    path: "/tmp/bookmarks",
+    realPath: "/tmp/bookmarks",
+    access: "readWrite" as const,
+    readable: true,
+    writable: true,
+    requiredDirectories: [],
+    requiredFiles: [],
+    missingDirectories: [],
+    missingFiles: [],
+    healthy: true,
+    problems: [],
+    checkedAt: "2026-05-10T00:00:00.000Z",
+  };
+}
+
+describe("plugin-bookmarks-example manifest", () => {
+  it("declares the expected core surface capabilities", () => {
+    const parsed = pluginManifestV1Schema.parse(manifest);
+    expect(parsed.id).toBe(PLUGIN_ID);
+    expect(parsed.capabilities).toEqual(
+      expect.arrayContaining([
+        "api.routes.register",
+        "database.namespace.migrate",
+        "database.namespace.read",
+        "database.namespace.write",
+        "local.folders",
+        "ui.page.register",
+        "ui.dashboardWidget.register",
+      ]),
+    );
+    expect(parsed.database).toMatchObject({
+      namespaceSlug: "bookmarks",
+      migrationsDir: "migrations",
+    });
+    expect(parsed.localFolders).toEqual([
+      expect.objectContaining({
+        folderKey: BOOKMARKS_FOLDER_KEY,
+        access: "readWrite",
+      }),
+    ]);
+    expect(parsed.apiRoutes).toEqual([
+      expect.objectContaining({ routeKey: "list", method: "GET" }),
+      expect.objectContaining({ routeKey: "create", method: "POST" }),
+      expect.objectContaining({ routeKey: "delete", method: "DELETE" }),
+    ]);
+    expect(parsed.ui?.slots ?? []).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ id: "bookmarks-page", type: "page" }),
+        expect.objectContaining({ id: "bookmarks-widget", type: "dashboardWidget" }),
+      ]),
+    );
+  });
+});
+
+describe("deriveSlugCandidate", () => {
+  it("prefers the title when one is provided", () => {
+    expect(deriveSlugCandidate("https://example.com", "My Favorite Link")).toBe("my-favorite-link");
+  });
+
+  it("falls back to host + path when title is missing", () => {
+    expect(deriveSlugCandidate("https://example.com/blog/my-post", null)).toBe("example-com-blog-my-post");
+  });
+
+  it("returns a default slug for invalid URLs without a title", () => {
+    expect(deriveSlugCandidate("not-a-url", null)).toBe("bookmark");
+  });
+});
+
+describe("renderBookmarkMarkdown", () => {
+  it("emits stable YAML frontmatter and trims trailing notes whitespace", () => {
+    const bookmark: BookmarkRecord = {
+      id: "00000000-0000-0000-0000-000000000001",
+      companyId: "11111111-1111-1111-1111-111111111111",
+      slug: "example",
+      url: "https://example.com/page",
+      title: "Example",
+      notes: "Hello\nworld\n\n",
+      tags: ["docs", "demo"],
+      filePath: "bookmarks/example.md",
+      createdAt: "2026-05-07T10:00:00.000Z",
+      updatedAt: "2026-05-07T10:00:00.000Z",
+    };
+    expect(renderBookmarkMarkdown(bookmark)).toBe(
+      [
+        "---",
+        "slug: example",
+        "url: https://example.com/page",
+        "title: Example",
+        'tags: ["docs", "demo"]',
+        "created_at: 2026-05-07T10:00:00.000Z",
+        "updated_at: 2026-05-07T10:00:00.000Z",
+        "---",
+        "",
+        "Hello",
+        "world\n",
+      ].join("\n"),
+    );
+  });
+
+  it("emits an empty body when there are no notes", () => {
+    const bookmark: BookmarkRecord = {
+      id: "id",
+      companyId: "company",
+      slug: "no-notes",
+      url: "https://example.com/",
+      title: "No notes",
+      notes: "",
+      tags: [],
+      filePath: "bookmarks/no-notes.md",
+      createdAt: "2026-05-07T10:00:00.000Z",
+      updatedAt: "2026-05-07T10:00:00.000Z",
+    };
+    const rendered = renderBookmarkMarkdown(bookmark);
+    expect(rendered.endsWith("---\n")).toBe(true);
+    expect(rendered).toContain("tags: []");
+  });
+});
+
+describe("plugin-bookmarks-example worker", () => {
+  it("creates, lists, and deletes bookmarks via registered handlers", async () => {
+    const companyId = "22222222-2222-2222-2222-222222222222";
+    const { harness } = makeHarness();
+    const writtenFiles: string[] = [];
+    const deletedFiles: string[] = [];
+    harness.ctx.localFolders.writeTextAtomic = vi.fn(async (_companyId, folderKey, relativePath) => {
+      writtenFiles.push(relativePath);
+      return localFolderStatus(folderKey);
+    });
+    harness.ctx.localFolders.deleteFile = vi.fn(async (_companyId, folderKey, relativePath) => {
+      deletedFiles.push(relativePath);
+      return localFolderStatus(folderKey);
+    });
+    await plugin.definition.setup(harness.ctx);
+
+    const created = await harness.performAction<BookmarkRecord>("create", {
+      companyId,
+      url: "https://example.com/one",
+      title: "Example One",
+      tags: ["Docs", "Demo", "demo"],
+      notes: "Initial note",
+    });
+    expect(created.companyId).toBe(companyId);
+    expect(created.slug).toBe("example-one");
+    expect(created.tags).toEqual(["docs", "demo"]);
+    expect(created.filePath).toBe("bookmarks/example-one.md");
+    expect(writtenFiles).toContain("bookmarks/example-one.md");
+
+    const second = await harness.performAction<BookmarkRecord>("create", {
+      companyId,
+      url: "https://example.com/two",
+      title: "Example Two",
+      tags: ["demo"],
+    });
+
+    const allListed = await harness.getData<BookmarkListResult>("list", { companyId });
+    expect(allListed.databaseNamespace).toBe("plugin_bookmarks_test");
+    expect(allListed.bookmarks.map((b) => b.slug).sort()).toEqual(["example-one", "example-two"]);
+
+    const filtered = await harness.getData<BookmarkListResult>("list", {
+      companyId,
+      tag: "docs",
+    });
+    expect(filtered.bookmarks.map((b) => b.slug)).toEqual(["example-one"]);
+
+    const searched = await harness.getData<BookmarkListResult>("list", {
+      companyId,
+      search: "two",
+    });
+    expect(searched.bookmarks.map((b) => b.slug)).toEqual(["example-two"]);
+
+    const deletion = await harness.performAction<{ deleted: boolean; slug: string }>("delete", {
+      companyId,
+      slug: second.slug,
+    });
+    expect(deletion).toEqual({ deleted: true, slug: "example-two" });
+    expect(deletedFiles).toEqual(["bookmarks/example-two.md"]);
+
+    const after = await harness.getData<BookmarkListResult>("list", { companyId });
+    expect(after.bookmarks.map((b) => b.slug)).toEqual(["example-one"]);
+  });
+
+  it("rejects URLs without an http(s) scheme", async () => {
+    const { harness } = makeHarness();
+    await plugin.definition.setup(harness.ctx);
+    await expect(
+      harness.performAction("create", {
+        companyId: "33333333-3333-3333-3333-333333333333",
+        url: "ftp://example.com",
+      }),
+    ).rejects.toThrow(/http or https/);
+  });
+
+  it("rejects duplicate slugs for the same company", async () => {
+    const companyId = "44444444-4444-4444-4444-444444444444";
+    const { harness } = makeHarness();
+    await plugin.definition.setup(harness.ctx);
+    await harness.performAction("create", {
+      companyId,
+      url: "https://example.com/one",
+      title: "Example One",
+    });
+    await expect(
+      harness.performAction("create", {
+        companyId,
+        url: "https://example.com/two",
+        title: "Example One",
+      }),
+    ).rejects.toThrow(/already exists/);
+  });
+
+  it("validates malformed tags before touching the database", async () => {
+    const { harness, db } = makeHarness();
+    await plugin.definition.setup(harness.ctx);
+    await expect(
+      harness.performAction("create", {
+        companyId: "55555555-5555-5555-5555-555555555555",
+        url: "https://example.com",
+        tags: ["good", "Bad Tag!!!"],
+      }),
+    ).rejects.toThrow(/lowercase letters, digits, hyphens, or underscores/);
+    expect(db.rows).toHaveLength(0);
+  });
+
+  it("dispatches the scoped API routes through the same handlers", async () => {
+    const companyId = "66666666-6666-6666-6666-666666666666";
+    const { harness } = makeHarness();
+    await plugin.definition.setup(harness.ctx);
+
+    const created = await plugin.definition.onApiRequest?.({
+      routeKey: "create",
+      method: "POST",
+      path: "/bookmarks",
+      params: {},
+      query: {},
+      body: { companyId, url: "https://example.com/api" },
+      actor: { actorType: "user", actorId: "board", userId: "board", agentId: null, runId: null },
+      companyId,
+      headers: {},
+    });
+    expect(created).toMatchObject({ status: 201 });
+    expect(created?.body).toMatchObject({ slug: "example-com-api" });
+
+    const listed = await plugin.definition.onApiRequest?.({
+      routeKey: "list",
+      method: "GET",
+      path: "/bookmarks",
+      params: {},
+      query: { search: "api" },
+      body: null,
+      actor: { actorType: "user", actorId: "board", userId: "board", agentId: null, runId: null },
+      companyId,
+      headers: {},
+    });
+    expect(listed?.body).toMatchObject({
+      bookmarks: [expect.objectContaining({ slug: "example-com-api" })],
+    });
+
+    const removed = await plugin.definition.onApiRequest?.({
+      routeKey: "delete",
+      method: "DELETE",
+      path: "/bookmarks/example-com-api",
+      params: { slug: "example-com-api" },
+      query: {},
+      body: null,
+      actor: { actorType: "user", actorId: "board", userId: "board", agentId: null, runId: null },
+      companyId,
+      headers: {},
+    });
+    expect(removed).toMatchObject({ status: 200, body: { deleted: true } });
+  });
+});
diff --git a/packages/plugins/examples/plugin-bookmarks-example/tsconfig.json b/packages/plugins/examples/plugin-bookmarks-example/tsconfig.json
new file mode 100644
index 00000000000..a697519ed9d
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": [
+      "ES2022",
+      "DOM"
+    ],
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": [
+    "src",
+    "tests"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules"
+  ]
+}
diff --git a/packages/plugins/examples/plugin-bookmarks-example/vitest.config.ts b/packages/plugins/examples/plugin-bookmarks-example/vitest.config.ts
new file mode 100644
index 00000000000..649a293ef95
--- /dev/null
+++ b/packages/plugins/examples/plugin-bookmarks-example/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.spec.ts"],
+    environment: "node",
+  },
+});
diff --git a/packages/plugins/sdk/src/host-client-factory.ts b/packages/plugins/sdk/src/host-client-factory.ts
index 13f0a5925de..603ecd4fc89 100644
--- a/packages/plugins/sdk/src/host-client-factory.ts
+++ b/packages/plugins/sdk/src/host-client-factory.ts
@@ -98,6 +98,7 @@ export interface HostServices {
     list(params: WorkerToHostMethods["localFolders.list"][0]): Promise<WorkerToHostMethods["localFolders.list"][1]>;
     readText(params: WorkerToHostMethods["localFolders.readText"][0]): Promise<WorkerToHostMethods["localFolders.readText"][1]>;
     writeTextAtomic(params: WorkerToHostMethods["localFolders.writeTextAtomic"][0]): Promise<WorkerToHostMethods["localFolders.writeTextAtomic"][1]>;
+    deleteFile(params: WorkerToHostMethods["localFolders.deleteFile"][0]): Promise<WorkerToHostMethods["localFolders.deleteFile"][1]>;
   };
 
   /** Provides `state.get`, `state.set`, `state.delete`. */
@@ -189,6 +190,13 @@ export interface HostServices {
     managedRun(params: WorkerToHostMethods["routines.managed.run"][0]): Promise<WorkerToHostMethods["routines.managed.run"][1]>;
   };
 
+  /** Provides `skills.managed.*`. */
+  skills: {
+    managedGet(params: WorkerToHostMethods["skills.managed.get"][0]): Promise<WorkerToHostMethods["skills.managed.get"][1]>;
+    managedReconcile(params: WorkerToHostMethods["skills.managed.reconcile"][0]): Promise<WorkerToHostMethods["skills.managed.reconcile"][1]>;
+    managedReset(params: WorkerToHostMethods["skills.managed.reset"][0]): Promise<WorkerToHostMethods["skills.managed.reset"][1]>;
+  };
+
   /** Provides issue read/write, relation, checkout, wakeup, summary, comment methods. */
   issues: {
     list(params: WorkerToHostMethods["issues.list"][0]): Promise<WorkerToHostMethods["issues.list"][1]>;
@@ -313,6 +321,7 @@ const METHOD_CAPABILITY_MAP: Record<WorkerToHostMethodName, PluginCapability | n
   "localFolders.list": "local.folders",
   "localFolders.readText": "local.folders",
   "localFolders.writeTextAtomic": "local.folders",
+  "localFolders.deleteFile": "local.folders",
 
   // State
   "state.get": "plugin.state.read",
@@ -367,6 +376,9 @@ const METHOD_CAPABILITY_MAP: Record<WorkerToHostMethodName, PluginCapability | n
     "routines.managed.reset": "routines.managed",
     "routines.managed.update": "routines.managed",
     "routines.managed.run": "routines.managed",
+    "skills.managed.get": "skills.managed",
+    "skills.managed.reconcile": "skills.managed",
+    "skills.managed.reset": "skills.managed",
 
   // Issues
   "issues.list": "issues.read",
@@ -501,6 +513,9 @@ export function createHostClientHandlers(
     "localFolders.writeTextAtomic": gated("localFolders.writeTextAtomic", async (params) => {
       return services.localFolders.writeTextAtomic(params);
     }),
+    "localFolders.deleteFile": gated("localFolders.deleteFile", async (params) => {
+      return services.localFolders.deleteFile(params);
+    }),
 
     // State
     "state.get": gated("state.get", async (params) => {
@@ -620,6 +635,17 @@ export function createHostClientHandlers(
       return services.routines.managedRun(params);
     }),
 
+    // Skills
+    "skills.managed.get": gated("skills.managed.get", async (params) => {
+      return services.skills.managedGet(params);
+    }),
+    "skills.managed.reconcile": gated("skills.managed.reconcile", async (params) => {
+      return services.skills.managedReconcile(params);
+    }),
+    "skills.managed.reset": gated("skills.managed.reset", async (params) => {
+      return services.skills.managedReset(params);
+    }),
+
     // Issues
     "issues.list": gated("issues.list", async (params) => {
       return services.issues.list(params);
diff --git a/packages/plugins/sdk/src/index.ts b/packages/plugins/sdk/src/index.ts
index 3d0bd07e19e..2753d72c93e 100644
--- a/packages/plugins/sdk/src/index.ts
+++ b/packages/plugins/sdk/src/index.ts
@@ -197,6 +197,7 @@ export type {
   PluginStateClient,
   PluginEntitiesClient,
   PluginProjectsClient,
+  PluginSkillsClient,
   PluginCompaniesClient,
   PluginIssuesClient,
   PluginIssueMutationActor,
@@ -268,6 +269,10 @@ export type {
   PluginManagedProjectResolution,
   PluginManagedRoutineDeclaration,
   PluginManagedRoutineResolution,
+  PluginManagedSkillDeclaration,
+  PluginManagedSkillFileDeclaration,
+  PluginManagedSkillResolution,
+  CompanySkill,
   PluginManagedResourceKind,
   PluginManagedResourceRef,
   PluginUiSlotDeclaration,
diff --git a/packages/plugins/sdk/src/protocol.ts b/packages/plugins/sdk/src/protocol.ts
index 843f479ba8e..c297c6b04b2 100644
--- a/packages/plugins/sdk/src/protocol.ts
+++ b/packages/plugins/sdk/src/protocol.ts
@@ -27,11 +27,13 @@ import type {
   IssueComment,
   IssueDocument,
   IssueDocumentSummary,
+  IssueAssigneeAdapterOverrides,
   IssueThreadInteraction,
   CreateIssueThreadInteraction,
   PluginManagedAgentResolution,
   PluginManagedProjectResolution,
   PluginManagedRoutineResolution,
+  PluginManagedSkillResolution,
   Routine,
   RoutineRun,
   Agent,
@@ -611,6 +613,10 @@ export interface WorkerToHostMethods {
     },
     result: PluginLocalFolderStatus,
   ];
+  "localFolders.deleteFile": [
+    params: { companyId: string; folderKey: string; relativePath: string },
+    result: PluginLocalFolderStatus,
+  ];
 
   // State
   "state.get": [
@@ -821,6 +827,18 @@ export interface WorkerToHostMethods {
     },
     result: RoutineRun,
   ];
+  "skills.managed.get": [
+    params: { skillKey: string; companyId: string },
+    result: PluginManagedSkillResolution,
+  ];
+  "skills.managed.reconcile": [
+    params: { skillKey: string; companyId: string },
+    result: PluginManagedSkillResolution,
+  ];
+  "skills.managed.reset": [
+    params: { skillKey: string; companyId: string },
+    result: PluginManagedSkillResolution,
+  ];
 
   // Issues
   "issues.list": [
@@ -852,12 +870,12 @@ export interface WorkerToHostMethods {
       title: string;
       description?: string;
       status?: string;
-      workMode?: string;
       priority?: string;
       assigneeAgentId?: string;
       assigneeUserId?: string | null;
       requestDepth?: number;
       billingCode?: string | null;
+      assigneeAdapterOverrides?: IssueAssigneeAdapterOverrides | null;
       surfaceVisibility?: string | null;
       originKind?: string | null;
       originId?: string | null;
diff --git a/packages/plugins/sdk/src/testing.ts b/packages/plugins/sdk/src/testing.ts
index fdc81f1c2a6..5bee4e3305b 100644
--- a/packages/plugins/sdk/src/testing.ts
+++ b/packages/plugins/sdk/src/testing.ts
@@ -7,6 +7,8 @@ import type {
   PluginIssueOriginKind,
   PluginManagedAgentResolution,
   PluginManagedRoutineResolution,
+  PluginManagedSkillResolution,
+  CompanySkill,
   Company,
   Project,
   Routine,
@@ -609,6 +611,25 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
           checkedAt: new Date().toISOString(),
         };
       },
+      async deleteFile(_companyId, folderKey) {
+        requireCapability(manifest, capabilitySet, "local.folders");
+        return {
+          folderKey,
+          configured: false,
+          path: null,
+          realPath: null,
+          access: "readWrite",
+          readable: false,
+          writable: false,
+          requiredDirectories: [],
+          requiredFiles: [],
+          missingDirectories: [],
+          missingFiles: [],
+          healthy: false,
+          problems: [{ code: "not_configured", message: "No local folder path is configured." }],
+          checkedAt: new Date().toISOString(),
+        };
+      },
     },
     events: {
       on(name: PluginEventType | `plugin.${string}`, filterOrFn: EventFilter | ((event: PluginEvent) => Promise<void>), maybeFn?: (event: PluginEvent) => Promise<void>): () => void {
@@ -991,14 +1012,14 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
             concurrencyPolicy: declaration.concurrencyPolicy ?? "coalesce_if_active",
             catchUpPolicy: declaration.catchUpPolicy ?? "skip_missed",
             variables: declaration.variables ?? [],
+            latestRevisionId: null,
+            latestRevisionNumber: 1,
             createdByAgentId: null,
             createdByUserId: null,
             updatedByAgentId: null,
             updatedByUserId: null,
             lastTriggeredAt: null,
             lastEnqueuedAt: null,
-            latestRevisionId: null,
-            latestRevisionNumber: 1,
             createdAt: now,
             updatedAt: now,
             managedByPlugin: {
@@ -1087,6 +1108,119 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
         },
       },
     },
+    skills: {
+      managed: {
+        async get(skillKey, companyId) {
+          requireCapability(manifest, capabilitySet, "skills.managed");
+          const declaration = manifest.skills?.find((skill) => skill.skillKey === skillKey);
+          if (!declaration) {
+            return {
+              pluginKey: manifest.id,
+              resourceKind: "skill",
+              resourceKey: skillKey,
+              companyId,
+              skillId: null,
+              skill: null,
+              status: "missing",
+              defaultDrift: null,
+            } satisfies PluginManagedSkillResolution;
+          }
+          const externalId = `${manifest.id}:skill:${skillKey}`;
+          const existingEntity = [...entities.values()].find((entity) =>
+            entity.entityType === "managed_resource"
+            && entity.scopeKind === "company"
+            && entity.scopeId === companyId
+            && entity.externalId === externalId
+          );
+          const existingSkill = existingEntity?.data?.skill as CompanySkill | undefined;
+          if (existingSkill && existingSkill.companyId === companyId) {
+            return {
+              pluginKey: manifest.id,
+              resourceKind: "skill",
+              resourceKey: skillKey,
+              companyId,
+              skillId: existingSkill.id,
+              skill: existingSkill,
+              status: "resolved",
+              defaultDrift: null,
+            } satisfies PluginManagedSkillResolution;
+          }
+          return {
+            pluginKey: manifest.id,
+            resourceKind: "skill",
+            resourceKey: skillKey,
+            companyId,
+            skillId: null,
+            skill: null,
+            status: "missing",
+            defaultDrift: null,
+          } satisfies PluginManagedSkillResolution;
+        },
+        async reconcile(skillKey, companyId) {
+          const existing = await this.get(skillKey, companyId);
+          if (existing.skill) return existing;
+          const declaration = manifest.skills?.find((skill) => skill.skillKey === skillKey);
+          if (!declaration) return existing;
+          const now = new Date();
+          const skill = {
+            id: randomUUID(),
+            companyId,
+            key: `plugin/${manifest.id.replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}/${skillKey}`,
+            slug: declaration.slug ?? skillKey,
+            name: declaration.displayName,
+            description: declaration.description ?? null,
+            markdown: declaration.markdown ?? `# ${declaration.displayName}\n`,
+            sourceType: "catalog",
+            sourceLocator: null,
+            sourceRef: null,
+            trustLevel: "markdown_only",
+            compatibility: "compatible",
+            fileInventory: [{ path: "SKILL.md", kind: "skill" }],
+            metadata: {
+              sourceKind: "catalog",
+              pluginManagedResource: {
+                pluginKey: manifest.id,
+                resourceKind: "skill",
+                resourceKey: skillKey,
+              },
+            },
+            createdAt: now,
+            updatedAt: now,
+          } satisfies CompanySkill;
+          const nowIso = now.toISOString();
+          const record: PluginEntityRecord = {
+            id: randomUUID(),
+            entityType: "managed_resource",
+            scopeKind: "company",
+            scopeId: companyId,
+            externalId: `${manifest.id}:skill:${skillKey}`,
+            title: declaration.displayName,
+            status: null,
+            data: { resourceKind: "skill", resourceKey: skillKey, skillId: skill.id, skill },
+            createdAt: nowIso,
+            updatedAt: nowIso,
+          };
+          entities.set(record.id, record);
+          return {
+            pluginKey: manifest.id,
+            resourceKind: "skill",
+            resourceKey: skillKey,
+            companyId,
+            skillId: skill.id,
+            skill,
+            status: "created",
+            defaultDrift: null,
+          } satisfies PluginManagedSkillResolution;
+        },
+        async reset(skillKey, companyId) {
+          const resolved = await this.reconcile(skillKey, companyId);
+          return {
+            ...resolved,
+            status: resolved.skill ? "reset" : resolved.status,
+          } satisfies PluginManagedSkillResolution;
+        },
+      },
+    },
     companies: {
       async list(input) {
         requireCapability(manifest, capabilitySet, "companies.read");
@@ -1147,7 +1281,7 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
           title: input.title,
           description: input.description ?? null,
           status: input.status ?? "todo",
-          workMode: input.workMode ?? "standard",
+          workMode: "standard",
           priority: input.priority ?? "medium",
           assigneeAgentId: input.assigneeAgentId ?? null,
           assigneeUserId: input.assigneeUserId ?? null,
@@ -1164,7 +1298,7 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
           originRunId: input.originRunId ?? null,
           requestDepth: input.requestDepth ?? 0,
           billingCode: input.billingCode ?? null,
-          assigneeAdapterOverrides: null,
+          assigneeAdapterOverrides: input.assigneeAdapterOverrides ?? null,
           executionWorkspaceId: input.executionWorkspaceId ?? null,
           executionWorkspacePreference: input.executionWorkspacePreference ?? null,
           executionWorkspaceSettings: input.executionWorkspaceSettings ?? null,
diff --git a/packages/plugins/sdk/src/types.ts b/packages/plugins/sdk/src/types.ts
index a7b7a1685c3..bb9b86d330f 100644
--- a/packages/plugins/sdk/src/types.ts
+++ b/packages/plugins/sdk/src/types.ts
@@ -22,6 +22,7 @@ import type {
   IssueDocument,
   IssueDocumentSummary,
   IssueRelationIssueSummary,
+  IssueAssigneeAdapterOverrides,
   IssueThreadInteraction,
   SuggestTasksInteraction,
   AskUserQuestionsInteraction,
@@ -32,6 +33,8 @@ import type {
   PluginManagedAgentResolution,
   PluginManagedProjectResolution,
   PluginManagedRoutineResolution,
+  PluginManagedSkillResolution,
+  CompanySkill,
   Routine,
   RoutineRun,
   Agent,
@@ -54,6 +57,10 @@ export type {
   PluginManagedProjectResolution,
   PluginManagedRoutineDeclaration,
   PluginManagedRoutineResolution,
+  PluginManagedSkillDeclaration,
+  PluginManagedSkillFileDeclaration,
+  PluginManagedSkillResolution,
+  CompanySkill,
   Routine,
   RoutineRun,
   PluginLocalFolderDeclaration,
@@ -450,6 +457,8 @@ export interface PluginLocalFoldersClient {
     relativePath: string,
     contents: string,
   ): Promise<PluginLocalFolderStatus>;
+  /** Delete a file below a configured folder after containment checks. Missing files are treated as already deleted. */
+  deleteFile(companyId: string, folderKey: string, relativePath: string): Promise<PluginLocalFolderStatus>;
 }
 
 /**
@@ -840,6 +849,19 @@ export interface PluginRoutinesClient {
   };
 }
 
+/**
+ * `ctx.skills` — resolve and reconcile plugin-managed company skills.
+ *
+ * Requires `skills.managed` capability.
+ */
+export interface PluginSkillsClient {
+  managed: {
+    get(skillKey: string, companyId: string): Promise<PluginManagedSkillResolution>;
+    reconcile(skillKey: string, companyId: string): Promise<PluginManagedSkillResolution>;
+    reset(skillKey: string, companyId: string): Promise<PluginManagedSkillResolution>;
+  };
+}
+
 /**
  * `ctx.data` — register `getData` handlers that back `usePluginData()` in the
  * plugin's frontend components.
@@ -1257,12 +1279,12 @@ export interface PluginIssuesClient {
     title: string;
     description?: string;
     status?: Issue["status"];
-    workMode?: Issue["workMode"];
     priority?: Issue["priority"];
     assigneeAgentId?: string;
     assigneeUserId?: string | null;
     requestDepth?: number;
     billingCode?: string | null;
+    assigneeAdapterOverrides?: IssueAssigneeAdapterOverrides | null;
     surfaceVisibility?: IssueSurfaceVisibility;
     originKind?: PluginIssueOriginKind;
     originId?: string | null;
@@ -1281,7 +1303,6 @@ export interface PluginIssuesClient {
       | "title"
       | "description"
       | "status"
-      | "workMode"
       | "priority"
       | "assigneeAgentId"
       | "assigneeUserId"
@@ -1624,6 +1645,9 @@ export interface PluginContext {
   /** Resolve and reconcile plugin-managed routines. Requires `routines.managed`. */
   routines: PluginRoutinesClient;
 
+  /** Resolve and reconcile plugin-managed company skills. Requires `skills.managed`. */
+  skills: PluginSkillsClient;
+
   /** Read company metadata. Requires `companies.read`. */
   companies: PluginCompaniesClient;
 
diff --git a/packages/plugins/sdk/src/worker-rpc-host.ts b/packages/plugins/sdk/src/worker-rpc-host.ts
index ad578d609c6..81104fea8fe 100644
--- a/packages/plugins/sdk/src/worker-rpc-host.ts
+++ b/packages/plugins/sdk/src/worker-rpc-host.ts
@@ -430,6 +430,10 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
             contents,
           });
         },
+
+        async deleteFile(companyId: string, folderKey: string, relativePath: string) {
+          return callHost("localFolders.deleteFile", { companyId, folderKey, relativePath });
+        },
       },
 
       events: {
@@ -671,6 +675,20 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
         },
       },
 
+      skills: {
+        managed: {
+          async get(skillKey: string, companyId: string) {
+            return callHost("skills.managed.get", { skillKey, companyId });
+          },
+          async reconcile(skillKey: string, companyId: string) {
+            return callHost("skills.managed.reconcile", { skillKey, companyId });
+          },
+          async reset(skillKey: string, companyId: string) {
+            return callHost("skills.managed.reset", { skillKey, companyId });
+          },
+        },
+      },
+
       companies: {
         async list(input) {
           return callHost("companies.list", {
@@ -714,12 +732,12 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
             title: input.title,
             description: input.description,
             status: input.status,
-            workMode: input.workMode,
             priority: input.priority,
             assigneeAgentId: input.assigneeAgentId,
             assigneeUserId: input.assigneeUserId,
             requestDepth: input.requestDepth,
             billingCode: input.billingCode,
+            assigneeAdapterOverrides: input.assigneeAdapterOverrides,
             surfaceVisibility: input.surfaceVisibility,
             originKind: input.originKind,
             originId: input.originId,
diff --git a/packages/shared/src/config-schema.ts b/packages/shared/src/config-schema.ts
index efa1bdee1d8..0264d5f6d08 100644
--- a/packages/shared/src/config-schema.ts
+++ b/packages/shared/src/config-schema.ts
@@ -24,25 +24,25 @@ export const databaseBackupConfigSchema = z.object({
   enabled: z.boolean().default(true),
   intervalMinutes: z.number().int().min(1).max(7 * 24 * 60).default(60),
   retentionDays: z.number().int().min(1).max(3650).default(7),
-  dir: z.string().default("~/.paperclip/instances/default/data/backups"),
+  dir: z.string().default("~/.paperclip/instances/default/spaces/default/data/backups"),
 });
 
 export const databaseConfigSchema = z.object({
   mode: z.enum(["embedded-postgres", "postgres"]).default("embedded-postgres"),
   connectionString: z.string().optional(),
-  embeddedPostgresDataDir: z.string().default("~/.paperclip/instances/default/db"),
+  embeddedPostgresDataDir: z.string().default("~/.paperclip/instances/default/spaces/default/db"),
   embeddedPostgresPort: z.number().int().min(1).max(65535).default(54329),
   backup: databaseBackupConfigSchema.default({
     enabled: true,
     intervalMinutes: 60,
     retentionDays: 7,
-    dir: "~/.paperclip/instances/default/data/backups",
+    dir: "~/.paperclip/instances/default/spaces/default/data/backups",
   }),
 });
 
 export const loggingConfigSchema = z.object({
   mode: z.enum(["file", "cloud"]),
-  logDir: z.string().default("~/.paperclip/instances/default/logs"),
+  logDir: z.string().default("~/.paperclip/instances/default/spaces/default/logs"),
 });
 
 export const serverConfigSchema = z.object({
@@ -63,7 +63,7 @@ export const authConfigSchema = z.object({
 });
 
 export const storageLocalDiskConfigSchema = z.object({
-  baseDir: z.string().default("~/.paperclip/instances/default/data/storage"),
+  baseDir: z.string().default("~/.paperclip/instances/default/spaces/default/data/storage"),
 });
 
 export const storageS3ConfigSchema = z.object({
@@ -77,7 +77,7 @@ export const storageS3ConfigSchema = z.object({
 export const storageConfigSchema = z.object({
   provider: z.enum(STORAGE_PROVIDERS).default("local_disk"),
   localDisk: storageLocalDiskConfigSchema.default({
-    baseDir: "~/.paperclip/instances/default/data/storage",
+    baseDir: "~/.paperclip/instances/default/spaces/default/data/storage",
   }),
   s3: storageS3ConfigSchema.default({
     bucket: "paperclip",
@@ -88,14 +88,14 @@ export const storageConfigSchema = z.object({
 });
 
 export const secretsLocalEncryptedConfigSchema = z.object({
-  keyFilePath: z.string().default("~/.paperclip/instances/default/secrets/master.key"),
+  keyFilePath: z.string().default("~/.paperclip/instances/default/spaces/default/secrets/master.key"),
 });
 
 export const secretsConfigSchema = z.object({
   provider: z.enum(SECRET_PROVIDERS).default("local_encrypted"),
   strictMode: z.boolean().default(false),
   localEncrypted: secretsLocalEncryptedConfigSchema.default({
-    keyFilePath: "~/.paperclip/instances/default/secrets/master.key",
+    keyFilePath: "~/.paperclip/instances/default/spaces/default/secrets/master.key",
   }),
 });
 
@@ -118,7 +118,7 @@ export const paperclipConfigSchema = z
     storage: storageConfigSchema.default({
       provider: "local_disk",
       localDisk: {
-        baseDir: "~/.paperclip/instances/default/data/storage",
+        baseDir: "~/.paperclip/instances/default/spaces/default/data/storage",
       },
       s3: {
         bucket: "paperclip",
@@ -131,7 +131,7 @@ export const paperclipConfigSchema = z
       provider: "local_encrypted",
       strictMode: false,
       localEncrypted: {
-        keyFilePath: "~/.paperclip/instances/default/secrets/master.key",
+        keyFilePath: "~/.paperclip/instances/default/spaces/default/secrets/master.key",
       },
     }),
   })
diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.ts
index 640f7563c05..3b0183714bf 100644
--- a/packages/shared/src/constants.ts
+++ b/packages/shared/src/constants.ts
@@ -715,6 +715,7 @@ export const PLUGIN_CAPABILITIES = [
   "issue.documents.write",
   "projects.managed",
   "routines.managed",
+  "skills.managed",
   "agents.pause",
   "agents.resume",
   "agents.invoke",
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 2239bbf4cb7..a8b7c48620c 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -581,10 +581,13 @@ export type {
   PluginManagedAgentDeclaration,
   PluginManagedProjectDeclaration,
   PluginManagedRoutineDeclaration,
+  PluginManagedSkillDeclaration,
+  PluginManagedSkillFileDeclaration,
   PluginLocalFolderDeclaration,
   PluginManagedAgentResolution,
   PluginManagedProjectResolution,
   PluginManagedRoutineResolution,
+  PluginManagedSkillResolution,
   PluginManagedResourceKind,
   PluginManagedResourceRef,
   PluginUiSlotDeclaration,
diff --git a/packages/shared/src/space-paths.test.ts b/packages/shared/src/space-paths.test.ts
new file mode 100644
index 00000000000..bc213f02c4b
--- /dev/null
+++ b/packages/shared/src/space-paths.test.ts
@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  createDefaultSpaceRegistry,
+  resolveDefaultEmbeddedPostgresDir,
+  resolvePaperclipConfigPathForInstance,
+  resolvePaperclipInstanceConfigPath,
+  resolvePaperclipInstanceRoot,
+  resolvePaperclipSpaceRoot,
+} from "./space-paths.js";
+
+const ORIGINAL_ENV = { ...process.env };
+
+function writeJson(filePath: string, value: unknown) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+afterEach(() => {
+  process.env = { ...ORIGINAL_ENV };
+});
+
+describe("space path resolution", () => {
+  it("resolves default-space config and data under spaces/default for fresh installs", () => {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-space-paths-"));
+    process.env.PAPERCLIP_HOME = home;
+    delete process.env.PAPERCLIP_INSTANCE_ID;
+    delete process.env.PAPERCLIP_SPACE_ID;
+
+    expect(resolvePaperclipConfigPathForInstance()).toBe(
+      path.join(home, "instances", "default", "spaces", "default", "config.json"),
+    );
+    expect(resolveDefaultEmbeddedPostgresDir()).toBe(
+      path.join(home, "instances", "default", "spaces", "default", "db"),
+    );
+  });
+
+  it("uses the active space pointer from the instance registry", () => {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-space-registry-"));
+    process.env.PAPERCLIP_HOME = home;
+    process.env.PAPERCLIP_INSTANCE_ID = "default";
+    delete process.env.PAPERCLIP_SPACE_ID;
+    writeJson(resolvePaperclipInstanceConfigPath(), {
+      ...createDefaultSpaceRegistry("system"),
+      activeSpaceId: "dev",
+      spaces: [{ id: "dev", root: "spaces/dev", createdAt: "2026-05-09T00:00:00.000Z" }],
+    });
+
+    expect(resolvePaperclipSpaceRoot()).toBe(path.join(home, "instances", "default", "spaces", "dev"));
+    expect(resolvePaperclipConfigPathForInstance()).toBe(
+      path.join(home, "instances", "default", "spaces", "dev", "config.json"),
+    );
+  });
+
+  it("treats legacy root-shaped default installs as the active default space", () => {
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-space-legacy-"));
+    process.env.PAPERCLIP_HOME = home;
+    process.env.PAPERCLIP_INSTANCE_ID = "default";
+    delete process.env.PAPERCLIP_SPACE_ID;
+    const legacyConfigPath = path.join(home, "instances", "default", "config.json");
+    writeJson(legacyConfigPath, {
+      database: {},
+      server: {},
+    });
+
+    expect(resolvePaperclipSpaceRoot()).toBe(resolvePaperclipInstanceRoot());
+    expect(resolvePaperclipConfigPathForInstance()).toBe(legacyConfigPath);
+    expect(resolveDefaultEmbeddedPostgresDir()).toBe(
+      path.join(home, "instances", "default", "db"),
+    );
+  });
+});
diff --git a/packages/shared/src/space-paths.ts b/packages/shared/src/space-paths.ts
new file mode 100644
index 00000000000..ba03ff236a7
--- /dev/null
+++ b/packages/shared/src/space-paths.ts
@@ -0,0 +1,247 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
+export const DEFAULT_PAPERCLIP_SPACE_ID = "default";
+export const PAPERCLIP_CONFIG_BASENAME = "config.json";
+export const PAPERCLIP_ENV_FILENAME = ".env";
+export const DEFAULT_SPACE_OWNED_PATH_NAMES = [
+  PAPERCLIP_CONFIG_BASENAME,
+  PAPERCLIP_ENV_FILENAME,
+  "db",
+  "data",
+  "logs",
+  "secrets",
+  "workspaces",
+  "projects",
+  "companies",
+] as const;
+export const DEFAULT_SPACE_ADAPTER_LOCAL_PATH_NAMES = ["codex-home"] as const;
+
+const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
+
+export interface PaperclipSpaceRegistry {
+  $meta: {
+    version: 1;
+    updatedAt: string;
+    source: "onboard" | "configure" | "doctor" | "system";
+  };
+  activeSpaceId: string;
+  spaces: Array<{
+    id: string;
+    root: string;
+    createdAt: string;
+  }>;
+  defaultSpaceMigration?: {
+    migratedAt: string;
+    sourceRoot: string;
+    destinationRoot: string;
+    movedPaths: string[];
+  };
+}
+
+export function expandHomePrefix(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
+  return value;
+}
+
+export function resolvePaperclipHomeDir(homeOverride?: string): string {
+  const raw = homeOverride?.trim() || process.env.PAPERCLIP_HOME?.trim();
+  if (raw) return path.resolve(expandHomePrefix(raw));
+  return path.resolve(os.homedir(), ".paperclip");
+}
+
+export function resolvePaperclipInstanceId(instanceIdOverride?: string): string {
+  const raw = instanceIdOverride?.trim() || process.env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_PAPERCLIP_INSTANCE_ID;
+  if (!PATH_SEGMENT_RE.test(raw)) {
+    throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
+  }
+  return raw;
+}
+
+export function resolvePaperclipInstanceRoot(input: {
+  homeDir?: string;
+  instanceId?: string;
+} = {}): string {
+  return path.resolve(resolvePaperclipHomeDir(input.homeDir), "instances", resolvePaperclipInstanceId(input.instanceId));
+}
+
+export function resolvePaperclipInstanceConfigPath(input: {
+  homeDir?: string;
+  instanceId?: string;
+} = {}): string {
+  return path.resolve(resolvePaperclipInstanceRoot(input), PAPERCLIP_CONFIG_BASENAME);
+}
+
+function readJsonIfPresent(filePath: string): unknown | null {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isPaperclipRuntimeConfig(value: unknown): boolean {
+  return isObject(value) && isObject(value.database) && isObject(value.server);
+}
+
+function readActiveSpaceIdFromRegistry(instanceConfigPath: string): string | null {
+  const parsed = readJsonIfPresent(instanceConfigPath);
+  if (!isObject(parsed) || isPaperclipRuntimeConfig(parsed)) return null;
+  const activeSpaceId = parsed.activeSpaceId;
+  return typeof activeSpaceId === "string" && PATH_SEGMENT_RE.test(activeSpaceId)
+    ? activeSpaceId
+    : null;
+}
+
+export function hasLegacyDefaultSpaceInstall(input: {
+  homeDir?: string;
+  instanceId?: string;
+} = {}): boolean {
+  return isPaperclipRuntimeConfig(readJsonIfPresent(resolvePaperclipInstanceConfigPath(input)));
+}
+
+export function resolvePaperclipSpaceId(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+} = {}): string {
+  const raw =
+    input.spaceId?.trim() ||
+    process.env.PAPERCLIP_SPACE_ID?.trim() ||
+    readActiveSpaceIdFromRegistry(resolvePaperclipInstanceConfigPath(input)) ||
+    DEFAULT_PAPERCLIP_SPACE_ID;
+  if (!PATH_SEGMENT_RE.test(raw)) {
+    throw new Error(`Invalid PAPERCLIP_SPACE_ID '${raw}'.`);
+  }
+  return raw;
+}
+
+export function resolvePaperclipSpacesRoot(input: {
+  homeDir?: string;
+  instanceId?: string;
+} = {}): string {
+  return path.resolve(resolvePaperclipInstanceRoot(input), "spaces");
+}
+
+export function resolvePaperclipSpaceRoot(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+} = {}): string {
+  const spaceId = resolvePaperclipSpaceId(input);
+  if (spaceId === DEFAULT_PAPERCLIP_SPACE_ID && hasLegacyDefaultSpaceInstall(input)) {
+    return resolvePaperclipInstanceRoot(input);
+  }
+  return path.resolve(resolvePaperclipSpacesRoot(input), spaceId);
+}
+
+export function resolvePaperclipSpaceConfigPath(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+} = {}): string {
+  return path.resolve(resolvePaperclipSpaceRoot(input), PAPERCLIP_CONFIG_BASENAME);
+}
+
+export function resolvePaperclipConfigPathForInstance(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+} = {}): string {
+  const spaceConfigPath = resolvePaperclipSpaceConfigPath(input);
+  if (fs.existsSync(spaceConfigPath)) return spaceConfigPath;
+
+  const instanceConfigPath = resolvePaperclipInstanceConfigPath(input);
+  if (isPaperclipRuntimeConfig(readJsonIfPresent(instanceConfigPath))) return instanceConfigPath;
+
+  return spaceConfigPath;
+}
+
+export function resolvePaperclipEnvPathForConfig(configPath: string): string {
+  return path.resolve(path.dirname(configPath), PAPERCLIP_ENV_FILENAME);
+}
+
+export function resolveDefaultEmbeddedPostgresDir(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+} = {}): string {
+  return path.resolve(resolvePaperclipSpaceRoot(input), "db");
+}
+
+export function resolveDefaultLogsDir(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+} = {}): string {
+  return path.resolve(resolvePaperclipSpaceRoot(input), "logs");
+}
+
+export function resolveDefaultSecretsKeyFilePath(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+} = {}): string {
+  return path.resolve(resolvePaperclipSpaceRoot(input), "secrets", "master.key");
+}
+
+export function resolveDefaultStorageDir(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+} = {}): string {
+  return path.resolve(resolvePaperclipSpaceRoot(input), "data", "storage");
+}
+
+export function resolveDefaultBackupDir(input: {
+  homeDir?: string;
+  instanceId?: string;
+  spaceId?: string;
+} = {}): string {
+  return path.resolve(resolvePaperclipSpaceRoot(input), "data", "backups");
+}
+
+export function createDefaultSpaceRegistry(source: PaperclipSpaceRegistry["$meta"]["source"]): PaperclipSpaceRegistry {
+  const now = new Date().toISOString();
+  return {
+    $meta: {
+      version: 1,
+      updatedAt: now,
+      source,
+    },
+    activeSpaceId: DEFAULT_PAPERCLIP_SPACE_ID,
+    spaces: [
+      {
+        id: DEFAULT_PAPERCLIP_SPACE_ID,
+        root: path.join("spaces", DEFAULT_PAPERCLIP_SPACE_ID),
+        createdAt: now,
+      },
+    ],
+  };
+}
+
+export function ensureDefaultSpaceRegistry(input: {
+  source: PaperclipSpaceRegistry["$meta"]["source"];
+  homeDir?: string;
+  instanceId?: string;
+}): string {
+  const registryPath = resolvePaperclipInstanceConfigPath(input);
+  if (fs.existsSync(registryPath)) return registryPath;
+  fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+  fs.writeFileSync(registryPath, `${JSON.stringify(createDefaultSpaceRegistry(input.source), null, 2)}\n`, {
+    mode: 0o600,
+  });
+  return registryPath;
+}
+
+export function resolveHomeAwarePath(value: string): string {
+  return path.resolve(expandHomePrefix(value));
+}
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
index 39ad1993c95..758f22e3c23 100644
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@@ -373,10 +373,13 @@ export type {
   PluginManagedAgentDeclaration,
   PluginManagedProjectDeclaration,
   PluginManagedRoutineDeclaration,
+  PluginManagedSkillDeclaration,
+  PluginManagedSkillFileDeclaration,
   PluginLocalFolderDeclaration,
   PluginManagedAgentResolution,
   PluginManagedProjectResolution,
   PluginManagedRoutineResolution,
+  PluginManagedSkillResolution,
   PluginManagedResourceKind,
   PluginManagedResourceRef,
   PluginUiSlotDeclaration,
diff --git a/packages/shared/src/types/plugin.ts b/packages/shared/src/types/plugin.ts
index d5231aadff5..6f9629122cc 100644
--- a/packages/shared/src/types/plugin.ts
+++ b/packages/shared/src/types/plugin.ts
@@ -27,6 +27,7 @@ import type {
   IssueSurfaceVisibility,
 } from "../constants.js";
 import type { Agent } from "./agent.js";
+import type { CompanySkill } from "./company-skill.js";
 import type { Project } from "./project.js";
 import type { Routine, RoutineTrigger, RoutineVariable } from "./routine.js";
 
@@ -164,6 +165,7 @@ export interface PluginManagedAgentDeclaration {
   instructions?: {
     entryFile?: string;
     content?: string;
+    files?: Record<string, string>;
     assetPath?: string;
   };
 }
@@ -208,7 +210,33 @@ export interface PluginManagedProjectDeclaration {
   settings?: Record<string, unknown>;
 }
 
-export type PluginManagedResourceKind = "agent" | "project" | "routine";
+export interface PluginManagedSkillFileDeclaration {
+  /** Relative path inside the skill folder, for example `references/guide.md`. */
+  path: string;
+  /** File contents written when the skill is installed or reset. */
+  content: string;
+}
+
+/**
+ * Declares a company skill that a plugin can install into each company's
+ * skills library and later resolve by stable key.
+ */
+export interface PluginManagedSkillDeclaration {
+  /** Stable identifier for this managed skill, unique within the plugin. */
+  skillKey: string;
+  /** Suggested visible skill name. */
+  displayName: string;
+  /** Suggested skill slug. Defaults to `skillKey`. */
+  slug?: string;
+  /** Suggested skill description. */
+  description?: string | null;
+  /** Full `SKILL.md` contents. Defaults to generated markdown from display metadata. */
+  markdown?: string;
+  /** Additional files installed with the skill. */
+  files?: PluginManagedSkillFileDeclaration[];
+}
+
+export type PluginManagedResourceKind = "agent" | "project" | "routine" | "skill";
 
 export interface PluginManagedResourceRef {
   pluginKey?: string;
@@ -258,6 +286,10 @@ export interface PluginManagedAgentResolution {
   agent: Agent | null;
   status: "missing" | "resolved" | "created" | "relinked" | "reset";
   approvalId?: string | null;
+  defaultDrift?: {
+    entryFile: string;
+    changedFiles: string[];
+  } | null;
 }
 
 export interface PluginManagedProjectResolution {
@@ -281,6 +313,19 @@ export interface PluginManagedRoutineResolution {
   missingRefs?: PluginManagedResourceRef[];
 }
 
+export interface PluginManagedSkillResolution {
+  pluginKey: string;
+  resourceKind: "skill";
+  resourceKey: string;
+  companyId: string;
+  skillId: string | null;
+  skill: CompanySkill | null;
+  status: "missing" | "resolved" | "created" | "relinked" | "reset";
+  defaultDrift?: {
+    changedFiles: string[];
+  } | null;
+}
+
 /**
  * Declares a UI extension slot the plugin fills with a React component.
  *
@@ -496,6 +541,8 @@ export interface PaperclipPluginManifestV1 {
   projects?: PluginManagedProjectDeclaration[];
   /** Suggested company-scoped routines this plugin can provision and resolve by stable key. */
   routines?: PluginManagedRoutineDeclaration[];
+  /** Suggested company skills this plugin can install and resolve by stable key. */
+  skills?: PluginManagedSkillDeclaration[];
   /** Trusted local folders this plugin can configure and access by stable key. */
   localFolders?: PluginLocalFolderDeclaration[];
   /**
diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.ts
index 14b30989d17..ae0f289b729 100644
--- a/packages/shared/src/validators/index.ts
+++ b/packages/shared/src/validators/index.ts
@@ -394,6 +394,8 @@ export {
   pluginLauncherRenderDeclarationSchema,
   pluginLauncherDeclarationSchema,
   pluginDatabaseDeclarationSchema,
+  pluginManagedSkillFileDeclarationSchema,
+  pluginManagedSkillDeclarationSchema,
   pluginApiRouteDeclarationSchema,
   pluginManifestV1Schema,
   installPluginSchema,
@@ -413,6 +415,8 @@ export {
   type PluginLauncherRenderDeclarationInput,
   type PluginLauncherDeclarationInput,
   type PluginDatabaseDeclarationInput,
+  type PluginManagedSkillFileDeclarationInput,
+  type PluginManagedSkillDeclarationInput,
   type PluginApiRouteDeclarationInput,
   type PluginManifestV1Input,
   type InstallPlugin,
diff --git a/packages/shared/src/validators/plugin.test.ts b/packages/shared/src/validators/plugin.test.ts
index 7de0c31687c..ccea0d6a3f6 100644
--- a/packages/shared/src/validators/plugin.test.ts
+++ b/packages/shared/src/validators/plugin.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { PLUGIN_CAPABILITIES } from "../constants.js";
-import { pluginManagedRoutineDeclarationSchema, pluginUiSlotDeclarationSchema } from "./plugin.js";
+import { pluginManagedRoutineDeclarationSchema, pluginManifestV1Schema, pluginUiSlotDeclarationSchema } from "./plugin.js";
 
 describe("plugin capability constants", () => {
   it("exposes each capability once", () => {
@@ -30,6 +30,41 @@ describe("plugin managed routine validators", () => {
   });
 });
 
+describe("plugin managed skill validators", () => {
+  const baseManifest = {
+    id: "paperclip.test-managed-skills",
+    apiVersion: 1,
+    version: "0.1.0",
+    displayName: "Managed Skills",
+    description: "Managed skills test plugin.",
+    author: "Paperclip",
+    categories: ["automation"],
+    entrypoints: { worker: "./dist/worker.js" },
+  } as const;
+
+  it("requires skills.managed when managed skills are declared", () => {
+    const parsed = pluginManifestV1Schema.safeParse({
+      ...baseManifest,
+      capabilities: [],
+      skills: [{ skillKey: "wiki-maintainer", displayName: "Wiki Maintainer" }],
+    });
+
+    expect(parsed.success).toBe(false);
+    if (parsed.success) return;
+    expect(parsed.error.issues.some((issue) => issue.message.includes("skills.managed"))).toBe(true);
+  });
+
+  it("accepts managed skills with the skills.managed capability", () => {
+    const parsed = pluginManifestV1Schema.parse({
+      ...baseManifest,
+      capabilities: ["skills.managed"],
+      skills: [{ skillKey: "wiki-maintainer", displayName: "Wiki Maintainer" }],
+    });
+
+    expect(parsed.skills?.[0]?.skillKey).toBe("wiki-maintainer");
+  });
+});
+
 describe("plugin UI slot validators", () => {
   it("accepts route-scoped sidebar slots with a routePath", () => {
     const parsed = pluginUiSlotDeclarationSchema.parse({
diff --git a/packages/shared/src/validators/plugin.ts b/packages/shared/src/validators/plugin.ts
index 336620a0acb..8d4016cd704 100644
--- a/packages/shared/src/validators/plugin.ts
+++ b/packages/shared/src/validators/plugin.ts
@@ -151,6 +151,7 @@ export const pluginManagedAgentDeclarationSchema = z.object({
   instructions: z.object({
     entryFile: z.string().min(1).max(200).optional(),
     content: z.string().max(200_000).optional(),
+    files: z.record(z.string().max(200_000)).optional(),
     assetPath: z.string().min(1).max(500).optional(),
   }).optional(),
 });
@@ -172,7 +173,7 @@ export type PluginManagedProjectDeclarationInput = z.infer<typeof pluginManagedP
 
 const pluginManagedResourceRefSchema = z.object({
   pluginKey: z.string().min(1).max(100).optional(),
-  resourceKind: z.enum(["agent", "project", "routine"]),
+  resourceKind: z.enum(["agent", "project", "routine", "skill"]),
   resourceKey: z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9._:-]*$/, {
     message: "resourceKey must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, colons, underscores, or hyphens",
   }),
@@ -232,6 +233,41 @@ export const pluginLocalFolderDeclarationSchema = z.object({
 
 export type PluginLocalFolderDeclarationInput = z.infer<typeof pluginLocalFolderDeclarationSchema>;
 
+export const pluginManagedSkillFileDeclarationSchema = z.object({
+  path: pluginLocalFolderRelativePathSchema.refine(
+    (value) => value.toLowerCase() !== "skill.md",
+    { message: "managed skill files cannot replace SKILL.md; use markdown for the main skill file" },
+  ),
+  content: z.string().max(200_000),
+});
+
+export type PluginManagedSkillFileDeclarationInput = z.infer<typeof pluginManagedSkillFileDeclarationSchema>;
+
+export const pluginManagedSkillDeclarationSchema = z.object({
+  skillKey: z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9._:-]*$/, {
+    message: "skillKey must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, colons, underscores, or hyphens",
+  }),
+  displayName: z.string().min(1).max(100),
+  slug: z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9._:-]*$/, {
+    message: "slug must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, colons, underscores, or hyphens",
+  }).optional(),
+  description: z.string().max(2000).nullable().optional(),
+  markdown: z.string().max(200_000).optional(),
+  files: z.array(pluginManagedSkillFileDeclarationSchema).max(50).optional(),
+}).superRefine((value, ctx) => {
+  const paths = (value.files ?? []).map((file) => file.path);
+  const duplicates = paths.filter((path, index) => paths.indexOf(path) !== index);
+  if (duplicates.length > 0) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `Duplicate managed skill file paths: ${[...new Set(duplicates)].join(", ")}`,
+      path: ["files"],
+    });
+  }
+});
+
+export type PluginManagedSkillDeclarationInput = z.infer<typeof pluginManagedSkillDeclarationSchema>;
+
 /**
  * Validates a {@link PluginUiSlotDeclaration} — a UI extension slot the plugin
  * fills with a React component. Includes `superRefine` checks for slot-specific
@@ -589,6 +625,7 @@ export const pluginManifestV1Schema = z.object({
   agents: z.array(pluginManagedAgentDeclarationSchema).optional(),
   projects: z.array(pluginManagedProjectDeclarationSchema).optional(),
   routines: z.array(pluginManagedRoutineDeclarationSchema).optional(),
+  skills: z.array(pluginManagedSkillDeclarationSchema).optional(),
   localFolders: z.array(pluginLocalFolderDeclarationSchema).optional(),
   launchers: z.array(pluginLauncherDeclarationSchema).optional(),
   ui: z.object({
@@ -678,6 +715,16 @@ export const pluginManifestV1Schema = z.object({
     }
   }
 
+  if (manifest.skills && manifest.skills.length > 0) {
+    if (!manifest.capabilities.includes("skills.managed")) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Capability 'skills.managed' is required when managed skills are declared",
+        path: ["capabilities"],
+      });
+    }
+  }
+
   if (manifest.localFolders && manifest.localFolders.length > 0) {
     if (!manifest.capabilities.includes("local.folders")) {
       ctx.addIssue({
@@ -871,6 +918,18 @@ export const pluginManifestV1Schema = z.object({
     }
   }
 
+  if (manifest.skills) {
+    const skillKeys = manifest.skills.map((skill) => skill.skillKey);
+    const duplicates = skillKeys.filter((key, i) => skillKeys.indexOf(key) !== i);
+    if (duplicates.length > 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Duplicate managed skill keys: ${[...new Set(duplicates)].join(", ")}`,
+        path: ["skills"],
+      });
+    }
+  }
+
   // UI slot ids must be unique within the plugin (namespaced at runtime)
   if (manifest.ui) {
     if (manifest.ui.slots) {
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 5bc8038cf95..a512cca6a52 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -9,6 +9,9 @@ packages:
   # Keep this smoke fixture installable as a local plugin example without
   # forcing PRs to commit pnpm-lock.yaml for a new workspace importer.
   - "!packages/plugins/examples/plugin-orchestration-smoke-example"
+  # Same treatment for the bookmarks example: published as a bundled plugin,
+  # not a workspace importer, so its pnpm-lock.yaml entries are managed by CI.
+  - "!packages/plugins/examples/plugin-bookmarks-example"
   - server
   - ui
   - cli
diff --git a/server/src/__tests__/plugin-managed-skills.test.ts b/server/src/__tests__/plugin-managed-skills.test.ts
new file mode 100644
index 00000000000..0cb6ddf89ad
--- /dev/null
+++ b/server/src/__tests__/plugin-managed-skills.test.ts
@@ -0,0 +1,262 @@
+import { randomUUID } from "node:crypto";
+import { eq } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+  activityLog,
+  companies,
+  companySkills,
+  createDb,
+  pluginManagedResources,
+  plugins,
+} from "@paperclipai/db";
+import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { buildHostServices } from "../services/plugin-host-services.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+function createEventBusStub() {
+  return {
+    forPlugin() {
+      return {
+        emit: async () => {},
+        subscribe: () => {},
+      };
+    },
+  } as any;
+}
+
+function issuePrefix(id: string) {
+  return `T${id.replace(/-/g, "").slice(0, 6).toUpperCase()}`;
+}
+
+function manifest(): PaperclipPluginManifestV1 {
+  return {
+    id: "paperclip.managed-skills-test",
+    apiVersion: 1,
+    version: "0.1.0",
+    displayName: "Managed Skills Test",
+    description: "Test plugin",
+    author: "Paperclip",
+    categories: ["automation"],
+    capabilities: ["skills.managed"],
+    entrypoints: { worker: "./dist/worker.js" },
+    skills: [{
+      skillKey: "wiki-maintainer",
+      displayName: "Wiki Maintainer Skill",
+      description: "Use LLM Wiki tools to maintain company knowledge.",
+      files: [{
+        path: "references/wiki-style.md",
+        content: "# Wiki style\n\nKeep pages cited and terse.\n",
+      }],
+    }],
+  };
+}
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres plugin-managed skill tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describeEmbeddedPostgres("plugin-managed skills", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-plugin-managed-skills-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(activityLog);
+    await db.delete(pluginManagedResources);
+    await db.delete(companySkills);
+    await db.delete(plugins);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  async function seedCompanyAndPlugin(pluginManifest = manifest()) {
+    const companyId = randomUUID();
+    const pluginId = randomUUID();
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: issuePrefix(companyId),
+    });
+    await db.insert(plugins).values({
+      id: pluginId,
+      pluginKey: pluginManifest.id,
+      packageName: "@paperclipai/plugin-managed-skills-test",
+      version: pluginManifest.version,
+      apiVersion: pluginManifest.apiVersion,
+      categories: pluginManifest.categories,
+      manifestJson: pluginManifest,
+      status: "ready",
+      installOrder: 1,
+    });
+    const services = buildHostServices(db, pluginId, pluginManifest.id, createEventBusStub(), undefined, {
+      manifest: pluginManifest,
+    });
+    return { companyId, pluginId, pluginManifest, services };
+  }
+
+  it("installs and resolves managed company skills by stable resource key", async () => {
+    const { companyId, services } = await seedCompanyAndPlugin();
+
+    const created = await services.skills.managedReconcile({
+      companyId,
+      skillKey: "wiki-maintainer",
+    });
+
+    expect(created.status).toBe("created");
+    expect(created.skill).toMatchObject({
+      name: "Wiki Maintainer Skill",
+      key: "plugin/paperclip-managed-skills-test/wiki-maintainer",
+      sourceType: "catalog",
+      fileInventory: expect.arrayContaining([
+        expect.objectContaining({ path: "SKILL.md", kind: "skill" }),
+        expect.objectContaining({ path: "references/wiki-style.md", kind: "reference" }),
+      ]),
+    });
+
+    const resolved = await services.skills.managedGet({
+      companyId,
+      skillKey: "wiki-maintainer",
+    });
+    expect(resolved.status).toBe("resolved");
+    expect(resolved.skillId).toBe(created.skillId);
+
+    const [binding] = await db.select().from(pluginManagedResources);
+    expect(binding).toMatchObject({
+      companyId,
+      resourceKind: "skill",
+      resourceKey: "wiki-maintainer",
+      resourceId: created.skillId,
+    });
+  });
+
+  it("preserves operator edits during reconcile and restores manifest defaults on reset", async () => {
+    const { companyId, services } = await seedCompanyAndPlugin();
+    const created = await services.skills.managedReconcile({ companyId, skillKey: "wiki-maintainer" });
+    expect(created.skillId).toBeTruthy();
+
+    await db
+      .update(companySkills)
+      .set({
+        name: "Custom Wiki Skill",
+        markdown: "# Custom instructions\n",
+        updatedAt: new Date(),
+      })
+      .where(eq(companySkills.id, created.skillId!));
+
+    const reconciled = await services.skills.managedReconcile({ companyId, skillKey: "wiki-maintainer" });
+    expect(reconciled.status).toBe("resolved");
+    expect(reconciled.skill).toMatchObject({
+      name: "Custom Wiki Skill",
+      markdown: "# Custom instructions\n",
+    });
+
+    const reset = await services.skills.managedReset({ companyId, skillKey: "wiki-maintainer" });
+    expect(reset.status).toBe("reset");
+    expect(reset.skill).toMatchObject({
+      name: "Wiki Maintainer Skill",
+      description: "Use LLM Wiki tools to maintain company knowledge.",
+    });
+    expect(reset.skill?.markdown).toContain("key: \"plugin/paperclip-managed-skills-test/wiki-maintainer\"");
+  });
+
+  it("relinks an existing canonical skill without overwriting operator edits", async () => {
+    const { companyId, services } = await seedCompanyAndPlugin();
+    const created = await services.skills.managedReconcile({ companyId, skillKey: "wiki-maintainer" });
+    expect(created.skillId).toBeTruthy();
+
+    await db.delete(pluginManagedResources).where(eq(pluginManagedResources.resourceId, created.skillId!));
+    await db
+      .update(companySkills)
+      .set({
+        name: "Existing Customized Wiki Skill",
+        markdown: "# Existing customized instructions\n",
+        updatedAt: new Date(),
+      })
+      .where(eq(companySkills.id, created.skillId!));
+
+    const relinked = await services.skills.managedReconcile({ companyId, skillKey: "wiki-maintainer" });
+
+    expect(relinked.status).toBe("relinked");
+    expect(relinked.skillId).toBe(created.skillId);
+    expect(relinked.skill).toMatchObject({
+      name: "Existing Customized Wiki Skill",
+      markdown: "# Existing customized instructions\n",
+    });
+    expect(relinked.defaultDrift).toEqual({ changedFiles: ["SKILL.md"] });
+
+    const [binding] = await db.select().from(pluginManagedResources);
+    expect(binding).toMatchObject({
+      companyId,
+      resourceKind: "skill",
+      resourceKey: "wiki-maintainer",
+      resourceId: created.skillId,
+    });
+  });
+
+  it("reports drift when installed skill files differ from plugin defaults", async () => {
+    const { companyId, services } = await seedCompanyAndPlugin();
+    const created = await services.skills.managedReconcile({ companyId, skillKey: "wiki-maintainer" });
+    expect(created.defaultDrift).toBeNull();
+
+    await db
+      .update(companySkills)
+      .set({
+        markdown: "# Custom instructions\n",
+        updatedAt: new Date(),
+      })
+      .where(eq(companySkills.id, created.skillId!));
+
+    const drifted = await services.skills.managedReconcile({ companyId, skillKey: "wiki-maintainer" });
+    expect(drifted.status).toBe("resolved");
+    expect(drifted.defaultDrift).toEqual({ changedFiles: ["SKILL.md"] });
+
+    const reset = await services.skills.managedReset({ companyId, skillKey: "wiki-maintainer" });
+    expect(reset.defaultDrift).toBeNull();
+  });
+
+  it("adds the canonical managed key to manifest-provided markdown skills", async () => {
+    const pluginManifest = manifest();
+    pluginManifest.skills = [
+      ...(pluginManifest.skills ?? []),
+      {
+        skillKey: "markdown-skill",
+        displayName: "Markdown Skill",
+        markdown: [
+          "---",
+          "name: markdown-skill",
+          "description: Markdown source without a key.",
+          "---",
+          "",
+          "# Markdown Skill",
+          "",
+          "Follow the managed markdown.",
+        ].join("\n"),
+      },
+    ];
+    const { companyId, services } = await seedCompanyAndPlugin(pluginManifest);
+
+    const created = await services.skills.managedReconcile({ companyId, skillKey: "markdown-skill" });
+
+    expect(created.status).toBe("created");
+    expect(created.skill).toMatchObject({
+      key: "plugin/paperclip-managed-skills-test/markdown-skill",
+      name: "markdown-skill",
+    });
+    expect(created.skill?.markdown).toContain("key: \"plugin/paperclip-managed-skills-test/markdown-skill\"");
+  });
+});
diff --git a/server/src/home-paths.ts b/server/src/home-paths.ts
index f1174bbb484..f12464d1fe8 100644
--- a/server/src/home-paths.ts
+++ b/server/src/home-paths.ts
@@ -1,57 +1,52 @@
-import os from "node:os";
 import path from "node:path";
-
-const DEFAULT_INSTANCE_ID = "default";
-const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
 const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
 const FRIENDLY_PATH_SEGMENT_RE = /[^a-zA-Z0-9._-]+/g;
+import {
+  expandHomePrefix,
+  resolveDefaultBackupDir as resolveSharedDefaultBackupDir,
+  resolveDefaultEmbeddedPostgresDir as resolveSharedDefaultEmbeddedPostgresDir,
+  resolveDefaultLogsDir as resolveSharedDefaultLogsDir,
+  resolveDefaultSecretsKeyFilePath as resolveSharedDefaultSecretsKeyFilePath,
+  resolveDefaultStorageDir as resolveSharedDefaultStorageDir,
+  resolveHomeAwarePath,
+  resolvePaperclipConfigPathForInstance,
+  resolvePaperclipHomeDir,
+  resolvePaperclipInstanceId,
+  resolvePaperclipInstanceRoot,
+  resolvePaperclipSpaceRoot,
+} from "@paperclipai/shared/space-paths";
 
-function expandHomePrefix(value: string): string {
-  if (value === "~") return os.homedir();
-  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
-  return value;
-}
-
-export function resolvePaperclipHomeDir(): string {
-  const envHome = process.env.PAPERCLIP_HOME?.trim();
-  if (envHome) return path.resolve(expandHomePrefix(envHome));
-  return path.resolve(os.homedir(), ".paperclip");
-}
-
-export function resolvePaperclipInstanceId(): string {
-  const raw = process.env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_INSTANCE_ID;
-  if (!INSTANCE_ID_RE.test(raw)) {
-    throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
-  }
-  return raw;
-}
-
-export function resolvePaperclipInstanceRoot(): string {
-  return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId());
-}
+export {
+  expandHomePrefix,
+  resolveHomeAwarePath,
+  resolvePaperclipHomeDir,
+  resolvePaperclipInstanceId,
+  resolvePaperclipInstanceRoot,
+  resolvePaperclipSpaceRoot,
+};
 
 export function resolveDefaultConfigPath(): string {
-  return path.resolve(resolvePaperclipInstanceRoot(), "config.json");
+  return resolvePaperclipConfigPathForInstance();
 }
 
 export function resolveDefaultEmbeddedPostgresDir(): string {
-  return path.resolve(resolvePaperclipInstanceRoot(), "db");
+  return resolveSharedDefaultEmbeddedPostgresDir();
 }
 
 export function resolveDefaultLogsDir(): string {
-  return path.resolve(resolvePaperclipInstanceRoot(), "logs");
+  return resolveSharedDefaultLogsDir();
 }
 
 export function resolveDefaultSecretsKeyFilePath(): string {
-  return path.resolve(resolvePaperclipInstanceRoot(), "secrets", "master.key");
+  return resolveSharedDefaultSecretsKeyFilePath();
 }
 
 export function resolveDefaultStorageDir(): string {
-  return path.resolve(resolvePaperclipInstanceRoot(), "data", "storage");
+  return resolveSharedDefaultStorageDir();
 }
 
 export function resolveDefaultBackupDir(): string {
-  return path.resolve(resolvePaperclipInstanceRoot(), "data", "backups");
+  return resolveSharedDefaultBackupDir();
 }
 
 export function resolveDefaultAgentWorkspaceDir(agentId: string): string {
@@ -59,7 +54,7 @@ export function resolveDefaultAgentWorkspaceDir(agentId: string): string {
   if (!PATH_SEGMENT_RE.test(trimmed)) {
     throw new Error(`Invalid agent id for workspace path '${agentId}'.`);
   }
-  return path.resolve(resolvePaperclipInstanceRoot(), "workspaces", trimmed);
+  return path.resolve(resolvePaperclipSpaceRoot(), "workspaces", trimmed);
 }
 
 function sanitizeFriendlyPathSegment(value: string | null | undefined, fallback = "_default"): string {
@@ -82,14 +77,10 @@ export function resolveManagedProjectWorkspaceDir(input: {
     throw new Error("Managed project workspace path requires companyId and projectId.");
   }
   return path.resolve(
-    resolvePaperclipInstanceRoot(),
+    resolvePaperclipSpaceRoot(),
     "projects",
     sanitizeFriendlyPathSegment(companyId, "company"),
     sanitizeFriendlyPathSegment(projectId, "project"),
     sanitizeFriendlyPathSegment(input.repoName, "_default"),
   );
 }
-
-export function resolveHomeAwarePath(value: string): string {
-  return path.resolve(expandHomePrefix(value));
-}
diff --git a/server/src/routes/plugins.ts b/server/src/routes/plugins.ts
index 75a206b154b..17f5eef5c6e 100644
--- a/server/src/routes/plugins.ts
+++ b/server/src/routes/plugins.ts
@@ -184,6 +184,14 @@ const BUNDLED_PLUGIN_EXAMPLES: AvailablePluginExample[] = [
     localPath: "packages/plugins/examples/plugin-orchestration-smoke-example",
     tag: "example",
   },
+  {
+    packageName: "@paperclipai/plugin-bookmarks-example",
+    pluginKey: "paperclipai.plugin-bookmarks-example",
+    displayName: "Bookmarks (Example)",
+    description: "Company-scoped bookmark library backed by a plugin database namespace and a local markdown folder. Demonstrates scoped API routes, local folders, dashboard widget, and a plugin page.",
+    localPath: "packages/plugins/examples/plugin-bookmarks-example",
+    tag: "example",
+  },
 ];
 
 function listBundledPluginExamples(): AvailablePluginExample[] {
diff --git a/server/src/services/agent-instructions.ts b/server/src/services/agent-instructions.ts
index 6dcbb38f047..b6d3490e213 100644
--- a/server/src/services/agent-instructions.ts
+++ b/server/src/services/agent-instructions.ts
@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { notFound, unprocessable } from "../errors.js";
-import { resolveHomeAwarePath, resolvePaperclipInstanceRoot } from "../home-paths.js";
+import { resolveHomeAwarePath, resolvePaperclipSpaceRoot } from "../home-paths.js";
 
 const ENTRY_FILE_DEFAULT = "AGENTS.md";
 const MODE_KEY = "instructionsBundleMode";
@@ -132,7 +132,7 @@ function resolvePathWithinRoot(rootPath: string, relativePath: string): string {
 
 function resolveManagedInstructionsRoot(agent: AgentLike): string {
   return path.resolve(
-    resolvePaperclipInstanceRoot(),
+    resolvePaperclipSpaceRoot(),
     "companies",
     agent.companyId,
     "agents",
diff --git a/server/src/services/company-skills.ts b/server/src/services/company-skills.ts
index 0f5af2db4bb..b5a66a7a1f7 100644
--- a/server/src/services/company-skills.ts
+++ b/server/src/services/company-skills.ts
@@ -27,7 +27,7 @@ import type {
   CompanySkillUsageAgent,
 } from "@paperclipai/shared";
 import { normalizeAgentUrlKey } from "@paperclipai/shared";
-import { resolvePaperclipInstanceRoot } from "../home-paths.js";
+import { resolvePaperclipSpaceRoot } from "../home-paths.js";
 import { notFound, unprocessable } from "../errors.js";
 import { ghFetch, gitHubApiBase, resolveRawGitHubUrl } from "./github-fetch.js";
 import { agentService } from "./agents.js";
@@ -1383,7 +1383,7 @@ export async function findMissingLocalSkillIds(
 }
 
 function resolveManagedSkillsRoot(companyId: string) {
-  return path.resolve(resolvePaperclipInstanceRoot(), "skills", companyId);
+  return path.resolve(resolvePaperclipSpaceRoot(), "skills", companyId);
 }
 
 function resolveLocalSkillFilePath(skill: CompanySkill, relativePath: string) {
diff --git a/server/src/services/feedback.ts b/server/src/services/feedback.ts
index 4df0ca625b4..befbb0ec864 100644
--- a/server/src/services/feedback.ts
+++ b/server/src/services/feedback.ts
@@ -35,7 +35,7 @@ import {
   type FeedbackTraceTargetSummary,
   type FeedbackVoteValue,
 } from "@paperclipai/shared";
-import { resolveHomeAwarePath, resolvePaperclipInstanceRoot } from "../home-paths.js";
+import { resolveHomeAwarePath, resolvePaperclipSpaceRoot } from "../home-paths.js";
 import { notFound, unprocessable } from "../errors.js";
 import { agentInstructionsService } from "./agent-instructions.js";
 import {
@@ -391,7 +391,7 @@ async function buildCodexTraceFiles(input: {
   }
 
   const managedRoot = path.join(
-    resolvePaperclipInstanceRoot(),
+    resolvePaperclipSpaceRoot(),
     "companies",
     input.companyId,
     "codex-home",
diff --git a/server/src/services/plugin-host-services.ts b/server/src/services/plugin-host-services.ts
index e97ab8d0a8c..3465a804b52 100644
--- a/server/src/services/plugin-host-services.ts
+++ b/server/src/services/plugin-host-services.ts
@@ -44,10 +44,12 @@ import { pluginStateStore } from "./plugin-state-store.js";
 import { pluginDatabaseService } from "./plugin-database.js";
 import { pluginManagedAgentService } from "./plugin-managed-agents.js";
 import { pluginManagedRoutineService } from "./plugin-managed-routines.js";
+import { pluginManagedSkillService } from "./plugin-managed-skills.js";
 import {
   assertConfiguredLocalFolder,
   assertWritableConfiguredLocalFolder,
   getStoredLocalFolders,
+  deletePluginLocalFolderFile,
   inspectPluginLocalFolder,
   listPluginLocalFolderEntries,
   preparePluginLocalFolder,
@@ -509,6 +511,11 @@ export function buildHostServices(
     manifest: options.manifest,
     pluginWorkerManager: options.pluginWorkerManager,
   });
+  const managedSkills = pluginManagedSkillService(db, {
+    pluginId,
+    pluginKey,
+    manifest: options.manifest,
+  });
   const heartbeat = heartbeatService(db, {
     pluginWorkerManager: options.pluginWorkerManager,
   });
@@ -888,6 +895,17 @@ export function buildHostServices(
         await writePluginLocalFolderTextAtomic(status.realPath!, params.relativePath, params.contents);
         return inspectStoredLocalFolder(companyId, params.folderKey);
       },
+
+      async deleteFile(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        const status = await inspectStoredLocalFolder(companyId, params.folderKey);
+        assertWritableConfiguredLocalFolder(status);
+        if (status.access !== "readWrite" || !status.writable) {
+          throw new Error("Local folder is not configured for writes");
+        }
+        await deletePluginLocalFolderFile(status.realPath!, params.relativePath);
+        return inspectStoredLocalFolder(companyId, params.folderKey);
+      },
     },
 
     state: {
@@ -1224,6 +1242,24 @@ export function buildHostServices(
       },
     },
 
+    skills: {
+      async managedGet(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return managedSkills.get(params.skillKey, companyId);
+      },
+      async managedReconcile(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return managedSkills.reconcile(params.skillKey, companyId);
+      },
+      async managedReset(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return managedSkills.reset(params.skillKey, companyId);
+      },
+    },
+
     issues: {
       async list(params) {
         const companyId = ensureCompanyId(params.companyId);
diff --git a/server/src/services/plugin-local-folders.ts b/server/src/services/plugin-local-folders.ts
index 8aa590d7bbe..93548baea62 100644
--- a/server/src/services/plugin-local-folders.ts
+++ b/server/src/services/plugin-local-folders.ts
@@ -538,6 +538,54 @@ export async function writePluginLocalFolderTextAtomic(
   });
 }
 
+export async function deletePluginLocalFolderFile(
+  rootPath: string,
+  relativePath: string,
+) {
+  const rootRealPath = await fs.realpath(rootPath);
+  let resolved: Awaited<ReturnType<typeof resolvePluginLocalFolderPath>>;
+  try {
+    resolved = await resolvePluginLocalFolderPath(rootRealPath, relativePath, {
+      mustExist: true,
+      allowMissingLeaf: true,
+    });
+  } catch (error) {
+    const code = typeof error === "object" && error && "code" in error ? String((error as { code?: unknown }).code) : "";
+    if (code !== "ENOENT") throw error;
+    return inspectPluginLocalFolder({
+      folderKey: "delete-result",
+      storedConfig: {
+        path: rootPath,
+        access: "readWrite",
+      },
+    });
+  }
+
+  if (resolved.exists) {
+    const stat = await fs.lstat(resolved.absolutePath);
+    if (stat.isDirectory()) {
+      throw badRequest("Local folder delete target must be a file");
+    }
+    await fs.rm(resolved.absolutePath, { force: true });
+    if (process.platform !== "win32") {
+      const dirHandle = await fs.open(path.dirname(resolved.absolutePath), "r");
+      try {
+        await dirHandle.sync();
+      } finally {
+        await dirHandle.close();
+      }
+    }
+  }
+
+  return inspectPluginLocalFolder({
+    folderKey: "delete-result",
+    storedConfig: {
+      path: rootPath,
+      access: "readWrite",
+    },
+  });
+}
+
 export function defaultLocalFolderBasePath(pluginKey: string, companyId: string) {
   return path.join(os.homedir(), ".paperclip", "plugin-data", companyId, pluginKey);
 }
diff --git a/server/src/services/plugin-managed-agents.ts b/server/src/services/plugin-managed-agents.ts
index 84a55c3a318..ea95b59ce8c 100644
--- a/server/src/services/plugin-managed-agents.ts
+++ b/server/src/services/plugin-managed-agents.ts
@@ -126,6 +126,33 @@ function applyInstructionTemplateVariables(
   return next;
 }
 
+function declaredInstructionFiles(
+  declaration: PluginManagedAgentDeclaration,
+  variables: Record<string, string | null | undefined>,
+) {
+  const instructionDeclaration = declaration.instructions;
+  if (!instructionDeclaration?.content && !instructionDeclaration?.files) return null;
+
+  const entryFile = instructionDeclaration.entryFile ?? "AGENTS.md";
+  const files = { ...(instructionDeclaration.files ?? {}) };
+  if (instructionDeclaration.content !== undefined) {
+    files[entryFile] = instructionDeclaration.content;
+  }
+  if (files[entryFile] === undefined) {
+    files[entryFile] = "";
+  }
+
+  return {
+    entryFile,
+    files: Object.fromEntries(
+      Object.entries(files).map(([filePath, content]) => [
+        filePath,
+        applyInstructionTemplateVariables(content, variables),
+      ]),
+    ),
+  };
+}
+
 function rowIsManagedAgent(
   row: typeof agents.$inferSelect,
   pluginKey: string,
@@ -299,19 +326,18 @@ export function pluginManagedAgentService(
     companyId: string,
     agent: Agent,
     declaration: PluginManagedAgentDeclaration,
-    options: { replaceExisting: boolean },
+    materializeOptions: { replaceExisting: boolean },
   ): Promise<Agent> {
-    const instructionDeclaration = declaration.instructions;
-    if (!instructionDeclaration?.content) return agent;
-
-    const entryFile = instructionDeclaration.entryFile ?? "AGENTS.md";
     const variables = await optionsForInstructionVariables(companyId);
+    const declared = declaredInstructionFiles(declaration, variables);
+    if (!declared) return agent;
+
     const materialized = await instructions.materializeManagedBundle(
       agent,
-      { [entryFile]: applyInstructionTemplateVariables(instructionDeclaration.content, variables) },
+      declared.files,
       {
-        entryFile,
-        replaceExisting: options.replaceExisting,
+        entryFile: declared.entryFile,
+        replaceExisting: materializeOptions.replaceExisting,
         clearLegacyPromptTemplate: true,
       },
     );
@@ -325,6 +351,33 @@ export function pluginManagedAgentService(
     return (updated as Agent | null) ?? { ...agent, adapterConfig: materialized.adapterConfig };
   }
 
+  async function managedInstructionDefaultDrift(
+    companyId: string,
+    agent: Agent | null,
+    declaration: PluginManagedAgentDeclaration,
+  ): Promise<PluginManagedAgentResolution["defaultDrift"]> {
+    if (!agent) return null;
+    const variables = await optionsForInstructionVariables(companyId);
+    const declared = declaredInstructionFiles(declaration, variables);
+    if (!declared) return null;
+
+    let exported: Awaited<ReturnType<typeof instructions.exportFiles>>;
+    try {
+      exported = await instructions.exportFiles(agent);
+    } catch {
+      return { entryFile: declared.entryFile, changedFiles: [declared.entryFile] };
+    }
+
+    const paths = new Set([...Object.keys(declared.files), ...Object.keys(exported.files)]);
+    const changedFiles = [...paths]
+      .filter((filePath) => (exported.files[filePath] ?? null) !== (declared.files[filePath] ?? null))
+      .sort((left, right) => left.localeCompare(right));
+    if (exported.entryFile !== declared.entryFile && !changedFiles.includes(declared.entryFile)) {
+      changedFiles.unshift(declared.entryFile);
+    }
+    return changedFiles.length > 0 ? { entryFile: declared.entryFile, changedFiles } : null;
+  }
+
   async function optionsForInstructionVariables(companyId: string) {
     return options.instructionTemplateVariables ? options.instructionTemplateVariables(companyId) : {};
   }
@@ -333,13 +386,13 @@ export function pluginManagedAgentService(
     return options.pluginKey;
   }
 
-  function resolution(
+  async function resolution(
     companyId: string,
     declaration: PluginManagedAgentDeclaration,
     agent: Agent | null,
     status: PluginManagedAgentResolution["status"],
     approvalId?: string | null,
-  ): PluginManagedAgentResolution {
+  ): Promise<PluginManagedAgentResolution> {
     return {
       pluginKey: options.pluginKey,
       resourceKind: "agent",
@@ -349,6 +402,7 @@ export function pluginManagedAgentService(
       agent,
       status,
       approvalId: approvalId ?? null,
+      defaultDrift: await managedInstructionDefaultDrift(companyId, agent, declaration),
     };
   }
 
diff --git a/server/src/services/plugin-managed-skills.ts b/server/src/services/plugin-managed-skills.ts
new file mode 100644
index 00000000000..6610f6cb464
--- /dev/null
+++ b/server/src/services/plugin-managed-skills.ts
@@ -0,0 +1,342 @@
+import { and, eq } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import {
+  pluginManagedResources,
+} from "@paperclipai/db";
+import { normalizeAgentUrlKey } from "@paperclipai/shared";
+import type {
+  CompanySkill,
+  PaperclipPluginManifestV1,
+  PluginManagedSkillDeclaration,
+  PluginManagedSkillResolution,
+} from "@paperclipai/shared";
+import { notFound } from "../errors.js";
+import { logActivity } from "./activity-log.js";
+import { companySkillService } from "./company-skills.js";
+
+const MANAGED_SKILL_RESOURCE_KIND = "skill";
+
+interface PluginManagedSkillServiceOptions {
+  pluginId: string;
+  pluginKey: string;
+  manifest?: PaperclipPluginManifestV1 | null;
+}
+
+function pluginKeySlug(pluginKey: string) {
+  return normalizeAgentUrlKey(pluginKey) ?? "plugin";
+}
+
+function canonicalSkillKey(pluginKey: string, skillKey: string) {
+  return `plugin/${pluginKeySlug(pluginKey)}/${skillKey}`;
+}
+
+function yamlString(value: string) {
+  return JSON.stringify(value);
+}
+
+function buildDefaultMarkdown(
+  pluginKey: string,
+  declaration: PluginManagedSkillDeclaration,
+) {
+  const description = declaration.description?.trim() || `${declaration.displayName} plugin skill.`;
+  return [
+    "---",
+    `name: ${yamlString(declaration.displayName)}`,
+    `description: ${yamlString(description)}`,
+    `key: ${yamlString(canonicalSkillKey(pluginKey, declaration.skillKey))}`,
+    "---",
+    "",
+    `# ${declaration.displayName}`,
+    "",
+    description,
+    "",
+  ].join("\n");
+}
+
+function withManagedSkillKey(markdown: string, canonicalKey: string) {
+  const keyLine = `key: ${yamlString(canonicalKey)}`;
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  const frontmatter = /^---\n([\s\S]*?)\n---(\n?)/.exec(normalized);
+  if (!frontmatter) {
+    return [
+      "---",
+      keyLine,
+      "---",
+      "",
+      normalized,
+    ].join("\n");
+  }
+
+  const currentBody = frontmatter[1] ?? "";
+  const nextBody = /^key\s*:/m.test(currentBody)
+    ? currentBody.replace(/^key\s*:.*$/m, keyLine)
+    : [currentBody, keyLine].filter(Boolean).join("\n");
+  return `---\n${nextBody}\n---${frontmatter[2] ?? ""}${normalized.slice(frontmatter[0].length)}`;
+}
+
+function buildPackageFiles(
+  pluginKey: string,
+  declaration: PluginManagedSkillDeclaration,
+) {
+  const root = declaration.skillKey;
+  const canonicalKey = canonicalSkillKey(pluginKey, declaration.skillKey);
+  const files: Record<string, string> = {
+    [`${root}/SKILL.md`]: declaration.markdown?.trim()
+      ? withManagedSkillKey(declaration.markdown, canonicalKey)
+      : buildDefaultMarkdown(pluginKey, declaration),
+  };
+  for (const file of declaration.files ?? []) {
+    files[`${root}/${file.path}`] = file.content;
+  }
+  return files;
+}
+
+function buildDeclaredSkillFiles(
+  pluginKey: string,
+  declaration: PluginManagedSkillDeclaration,
+) {
+  const packageFiles = buildPackageFiles(pluginKey, declaration);
+  const root = declaration.skillKey;
+  const prefix = `${root}/`;
+  const files: Record<string, string> = {};
+  for (const [filePath, content] of Object.entries(packageFiles)) {
+    files[filePath.startsWith(prefix) ? filePath.slice(prefix.length) : filePath] = content;
+  }
+  return files;
+}
+
+function buildSkillDefaults(
+  pluginKey: string,
+  declaration: PluginManagedSkillDeclaration,
+) {
+  return {
+    skillKey: declaration.skillKey,
+    displayName: declaration.displayName,
+    slug: declaration.slug ?? declaration.skillKey,
+    description: declaration.description ?? null,
+    canonicalKey: canonicalSkillKey(pluginKey, declaration.skillKey),
+    files: [
+      "SKILL.md",
+      ...(declaration.files ?? []).map((file) => file.path),
+    ],
+  };
+}
+
+function resolution(
+  pluginKey: string,
+  companyId: string,
+  declaration: PluginManagedSkillDeclaration,
+  skill: CompanySkill | null,
+  status: PluginManagedSkillResolution["status"],
+  defaultDrift: PluginManagedSkillResolution["defaultDrift"] = null,
+): PluginManagedSkillResolution {
+  return {
+    pluginKey,
+    resourceKind: "skill",
+    resourceKey: declaration.skillKey,
+    companyId,
+    skillId: skill?.id ?? null,
+    skill,
+    status,
+    defaultDrift,
+  };
+}
+
+export function pluginManagedSkillService(
+  db: Db,
+  options: PluginManagedSkillServiceOptions,
+) {
+  const skills = companySkillService(db);
+
+  function declarationFor(skillKey: string) {
+    const declaration = options.manifest?.skills?.find((skill) => skill.skillKey === skillKey);
+    if (!declaration) {
+      throw notFound(`Managed skill declaration not found: ${skillKey}`);
+    }
+    return declaration;
+  }
+
+  async function getBinding(companyId: string, skillKey: string) {
+    return db
+      .select()
+      .from(pluginManagedResources)
+      .where(and(
+        eq(pluginManagedResources.companyId, companyId),
+        eq(pluginManagedResources.pluginId, options.pluginId),
+        eq(pluginManagedResources.resourceKind, MANAGED_SKILL_RESOURCE_KIND),
+        eq(pluginManagedResources.resourceKey, skillKey),
+      ))
+      .then((rows) => rows[0] ?? null);
+  }
+
+  async function upsertBinding(
+    companyId: string,
+    declaration: PluginManagedSkillDeclaration,
+    skillId: string,
+  ) {
+    const defaultsJson = buildSkillDefaults(options.pluginKey, declaration);
+    const existing = await getBinding(companyId, declaration.skillKey);
+    if (existing) {
+      return db
+        .update(pluginManagedResources)
+        .set({
+          resourceId: skillId,
+          defaultsJson,
+          updatedAt: new Date(),
+        })
+        .where(eq(pluginManagedResources.id, existing.id))
+        .returning()
+        .then((rows) => rows[0]);
+    }
+    return db
+      .insert(pluginManagedResources)
+      .values({
+        companyId,
+        pluginId: options.pluginId,
+        pluginKey: options.pluginKey,
+        resourceKind: MANAGED_SKILL_RESOURCE_KIND,
+        resourceKey: declaration.skillKey,
+        resourceId: skillId,
+        defaultsJson,
+      })
+      .returning()
+      .then((rows) => rows[0]);
+  }
+
+  async function getSkill(companyId: string, skillId: string) {
+    return skills.getById(companyId, skillId);
+  }
+
+  async function managedSkillDefaultDrift(
+    companyId: string,
+    skill: CompanySkill | null,
+    declaration: PluginManagedSkillDeclaration,
+  ): Promise<PluginManagedSkillResolution["defaultDrift"]> {
+    if (!skill) return null;
+    const declaredFiles = buildDeclaredSkillFiles(options.pluginKey, declaration);
+    const currentFiles: Record<string, string | null> = {};
+    const paths = new Set([
+      ...Object.keys(declaredFiles),
+      ...skill.fileInventory.map((entry) => entry.path),
+    ]);
+
+    for (const filePath of paths) {
+      if (filePath === "SKILL.md") {
+        currentFiles[filePath] = skill.markdown;
+        continue;
+      }
+      try {
+        currentFiles[filePath] = (await skills.readFile(companyId, skill.id, filePath))?.content ?? null;
+      } catch {
+        currentFiles[filePath] = null;
+      }
+    }
+
+    const changedFiles = [...paths]
+      .filter((filePath) => (currentFiles[filePath] ?? null) !== (declaredFiles[filePath] ?? null))
+      .sort((left, right) => left.localeCompare(right));
+    return changedFiles.length > 0 ? { changedFiles } : null;
+  }
+
+  async function resolvedSkill(
+    companyId: string,
+    declaration: PluginManagedSkillDeclaration,
+    skill: CompanySkill | null,
+    status: PluginManagedSkillResolution["status"],
+  ) {
+    return resolution(
+      options.pluginKey,
+      companyId,
+      declaration,
+      skill,
+      status,
+      await managedSkillDefaultDrift(companyId, skill, declaration),
+    );
+  }
+
+  async function importDeclaredSkill(
+    companyId: string,
+    declaration: PluginManagedSkillDeclaration,
+    mode: "reconcile" | "reset",
+  ) {
+    const beforeByKey = mode === "reconcile"
+      ? await skills.getByKey(companyId, canonicalSkillKey(options.pluginKey, declaration.skillKey))
+      : null;
+    if (beforeByKey) {
+      await upsertBinding(companyId, declaration, beforeByKey.id);
+      return { skill: beforeByKey, status: "relinked" as const };
+    }
+    const results = await skills.importPackageFiles(
+      companyId,
+      buildPackageFiles(options.pluginKey, declaration),
+      { onConflict: "replace" },
+    );
+    const imported = results.find((result) =>
+      result.skill.key === canonicalSkillKey(options.pluginKey, declaration.skillKey)
+      || result.originalSlug === (declaration.slug ?? declaration.skillKey)
+      || result.originalSlug === declaration.skillKey
+    )?.skill ?? results[0]?.skill ?? null;
+    if (!imported) {
+      throw notFound(`Managed skill was not imported: ${declaration.skillKey}`);
+    }
+    await upsertBinding(companyId, declaration, imported.id);
+    const status: PluginManagedSkillResolution["status"] = mode === "reset" ? "reset" : "created";
+    return { skill: imported, status };
+  }
+
+  async function get(skillKey: string, companyId: string) {
+    const declaration = declarationFor(skillKey);
+    const binding = await getBinding(companyId, skillKey);
+    if (!binding) return resolvedSkill(companyId, declaration, null, "missing");
+    const skill = await getSkill(companyId, binding.resourceId);
+    return resolvedSkill(companyId, declaration, skill, skill ? "resolved" : "missing");
+  }
+
+  async function reconcile(skillKey: string, companyId: string) {
+    const declaration = declarationFor(skillKey);
+    const current = await get(skillKey, companyId);
+    if (current.skill) {
+      await upsertBinding(companyId, declaration, current.skill.id);
+      return current;
+    }
+    const imported = await importDeclaredSkill(companyId, declaration, "reconcile");
+    await logActivity(db, {
+      companyId,
+      actorType: "plugin",
+      actorId: options.pluginId,
+      action: "plugin.managed_skill.reconciled",
+      entityType: "company_skill",
+      entityId: imported.skill.id,
+      details: {
+        sourcePluginKey: options.pluginKey,
+        managedResourceKey: declaration.skillKey,
+        status: imported.status,
+      },
+    });
+    return resolvedSkill(companyId, declaration, imported.skill, imported.status);
+  }
+
+  async function reset(skillKey: string, companyId: string) {
+    const declaration = declarationFor(skillKey);
+    const imported = await importDeclaredSkill(companyId, declaration, "reset");
+    await logActivity(db, {
+      companyId,
+      actorType: "plugin",
+      actorId: options.pluginId,
+      action: "plugin.managed_skill.reset",
+      entityType: "company_skill",
+      entityId: imported.skill.id,
+      details: {
+        sourcePluginKey: options.pluginKey,
+        managedResourceKey: declaration.skillKey,
+      },
+    });
+    return resolvedSkill(companyId, declaration, imported.skill, "reset");
+  }
+
+  return {
+    get,
+    reconcile,
+    reset,
+  };
+}
diff --git a/server/src/services/run-log-store.ts b/server/src/services/run-log-store.ts
index 9c6a814287d..c00d33a418f 100644
--- a/server/src/services/run-log-store.ts
+++ b/server/src/services/run-log-store.ts
@@ -2,7 +2,7 @@ import { createReadStream, promises as fs } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { notFound } from "../errors.js";
-import { resolvePaperclipInstanceRoot } from "../home-paths.js";
+import { resolvePaperclipSpaceRoot } from "../home-paths.js";
 
 export type RunLogStoreType = "local_file";
 
@@ -151,7 +151,7 @@ let cachedStore: RunLogStore | null = null;
 
 export function getRunLogStore() {
   if (cachedStore) return cachedStore;
-  const basePath = process.env.RUN_LOG_BASE_PATH ?? path.resolve(resolvePaperclipInstanceRoot(), "data", "run-logs");
+  const basePath = process.env.RUN_LOG_BASE_PATH ?? path.resolve(resolvePaperclipSpaceRoot(), "data", "run-logs");
   cachedStore = createLocalFileRunLogStore(basePath);
   return cachedStore;
 }
diff --git a/server/src/services/workspace-operation-log-store.ts b/server/src/services/workspace-operation-log-store.ts
index 379dab62d2c..4695014fe52 100644
--- a/server/src/services/workspace-operation-log-store.ts
+++ b/server/src/services/workspace-operation-log-store.ts
@@ -2,7 +2,7 @@ import { createReadStream, promises as fs } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { notFound } from "../errors.js";
-import { resolvePaperclipInstanceRoot } from "../home-paths.js";
+import { resolvePaperclipSpaceRoot } from "../home-paths.js";
 
 export type WorkspaceOperationLogStoreType = "local_file";
 
@@ -150,7 +150,7 @@ let cachedStore: WorkspaceOperationLogStore | null = null;
 export function getWorkspaceOperationLogStore() {
   if (cachedStore) return cachedStore;
   const basePath = process.env.WORKSPACE_OPERATION_LOG_BASE_PATH
-    ?? path.resolve(resolvePaperclipInstanceRoot(), "data", "workspace-operation-logs");
+    ?? path.resolve(resolvePaperclipSpaceRoot(), "data", "workspace-operation-logs");
   cachedStore = createLocalFileWorkspaceOperationLogStore(basePath);
   return cachedStore;
 }