[nexus] fix(audit): resolve integration checker findings — straggler strings, query param pre-fill, orphaned import

- Alias uses absolute path (path.resolve) for correct Vite import resolution
- [nexus] comment marks the change for rebase visibility
- Original OnboardingWizard.tsx and App.tsx remain unmodified

.planning/REBASE-RUNBOOK.md

@@ -0,0 +1,83 @@
+# Nexus Rebase Runbook
+
+Step-by-step workflow for rebasing Nexus fork commits onto new upstream Paperclip releases.
+
+## Prerequisites
+
+- `git rerere` enabled: `git config rerere.enabled true`
+- `git range-diff` available (git 2.19+, confirmed 2.39.5 on this machine)
+- Upstream remote configured: `git remote add upstream https://github.com/paperclipai/paperclip.git` (if not already)
+
+## Pre-Rebase Checklist
+
+1. Ensure working tree is clean: `git status`
+2. Fetch upstream: `git fetch upstream`
+3. Record current tip: `git log --oneline -1` (save this SHA as OLD_TIP)
+4. Verify all tests pass before rebase: `pnpm test:run`
+
+## Rebase Procedure
+
+```bash
+# 1. Fetch latest upstream
+git fetch upstream
+
+# 2. Rebase nexus commits onto upstream/master
+git rebase upstream/master
+
+# 3. If conflicts arise:
+#    - git rerere will auto-apply previously recorded resolutions
+#    - For new conflicts: resolve manually, then `git add` + `git rebase --continue`
+#    - rerere automatically records new resolutions for future use
+
+# 4. Verify rebase integrity with range-diff
+#    ORIG_HEAD is the pre-rebase tip (set automatically by git)
+git range-diff upstream/master ORIG_HEAD HEAD
+```
+
+## Post-Rebase Verification
+
+1. **range-diff check:** `git range-diff upstream/master ORIG_HEAD HEAD`
+   - Every nexus commit should show as "equivalent" (minor offset changes only)
+   - Flag any commit showing significant diff changes for manual review
+2. **Test suite:** `pnpm test:run` — all tests must pass
+3. **Type check:** `pnpm typecheck` (if available) or `pnpm -r run typecheck`
+4. **Branding spot check:** `pnpm vitest run --project packages/branding`
+
+## Handling Common Scenarios
+
+### Upstream changed a file we also changed (DISPLAY zone)
+- Most common: string changes in UI components
+- rerere should handle if previously resolved
+- If new: resolve keeping Nexus display string, `git add`, continue
+
+### Upstream added new constants to packages/shared/src/constants.ts
+- Our changes are in `packages/branding/` (separate file) — no conflict expected
+- If AGENT_ROLE_LABELS format changes upstream, update the DISPLAY zone mapping
+
+### Upstream restructured a file entirely
+- range-diff will show the affected nexus commit as "changed"
+- Manually verify the nexus change still applies correctly
+- Update zone taxonomy if file paths changed
+
+## rerere Cache Notes
+
+- Cache lives in `.git/rr-cache/` (not tracked by git)
+- Cache is machine-local — lost on re-clone
+- After a fresh clone, first rebase may require manual resolution
+- Subsequent rebases at the same conflict points will auto-resolve
+
+## Hook Re-installation
+
+After a fresh clone, the commit-msg hook must be reinstalled:
+
+```bash
+# From repo root:
+cp scripts/nexus-commit-msg-hook.sh .git/hooks/commit-msg
+chmod +x .git/hooks/commit-msg
+```
+
+Or using the install script:
+
+```bash
+bash scripts/install-hooks.sh
+```

.planning/ZONE-TAXONOMY.md

@@ -0,0 +1,77 @@
+# Nexus Zone Taxonomy
+
+Classifies every Paperclip-to-Nexus rename target by zone.
+Zones determine which occurrences are safe to change and which must stay unchanged for upstream sync.
+
+**Zones:**
+- **DISPLAY** — User-facing strings safe to rename (UI text, banners, tooltips, help text, button labels)
+- **CODE** — TypeScript identifiers, import paths, route segments, env vars — do NOT touch
+- **STORED** — DB column/table names, stored enum values — do NOT touch
+
+---
+
+## DISPLAY Zone (safe to change in Phases 2-4)
+
+| Target | Location | Current Value | Nexus Value | Phase |
+|--------|----------|---------------|-------------|-------|
+| Company display string in JSX | ~16 UI files in `ui/src/` | "Company" | "Workspace" | 3 |
+| Companies plural in JSX | UI files | "Companies" | "Workspaces" | 3 |
+| CEO display string in JSX | `ui/src/components/agent-config-primitives.tsx`, `AgentProperties.tsx`, etc. | "CEO" | "Project Manager" | 3 |
+| Board display string in JSX | Various UI files | "Board" | "Owner" | 3 |
+| Hire button text | UI dialogs | "Hire" | "Add" | 3 |
+| Fire button text | UI dialogs | "Fire" | "Remove" | 3 |
+| `AGENT_ROLE_LABELS.ceo` value | `packages/shared/src/constants.ts` | `"CEO"` | `"Project Manager"` | 2 |
+| PAPERCLIP ASCII banner | `server/src/startup-banner.ts` | "PAPERCLIP" | "NEXUS" | 2 |
+| PAPERCLIP ASCII banner (CLI) | `cli/src/utils/banner.ts` | "PAPERCLIP" | "NEXUS" | 2 |
+| App title in browser tab | `ui/index.html` or layout | "Paperclip" | "Nexus" | 3 |
+| Top-left logo text | UI layout component | "Paperclip" | "Nexus" | 3 |
+| CLI help text brand name | `cli/src/` command descriptions | "Paperclip" | "Nexus" | 3 |
+| paperclip.ing URL references | `ui/src/pages/CompanyExport.tsx` | "paperclip.ing" | Nexus URL | 3 |
+| Favicon and logo assets | `ui/public/` or assets dir | Paperclip branding | Nexus branding | 3 |
+
+---
+
+## CODE Zone (do NOT touch — upstream sync priority)
+
+| Target | Location | Rationale |
+|--------|----------|-----------|
+| `companyService`, `companyId`, `selectedCompanyId` | Throughout server/ui/cli | TypeScript identifiers — hundreds of import references |
+| `companies` table name | `packages/db/src/schema/` | DB table — migration required to rename |
+| `company_id` FK columns | `packages/db/src/schema/` | DB columns — migration required |
+| `/api/companies` route segment | `server/src/routes/companies.ts` | API contract — client/server must match |
+| `COMPANY_STATUSES` / `CompanyStatus` type | `packages/shared/src/constants.ts` | Upstream shared type — plugin API contract |
+| `@paperclipai/*` package names | All `package.json` files | Import paths throughout monorepo |
+| `PAPERCLIP_*` env vars | Server/CLI config | Breaks existing deployments |
+| `board_api_keys` table / `board` actor type | DB schema, auth code | Auth token format, DB schema |
+| `pcp_board_*` token prefixes | Auth code | Would invalidate issued tokens |
+| `.paperclip.yaml` export format | Import/export code | Upstream compatibility |
+
+---
+
+## STORED Zone (do NOT touch — DB integrity)
+
+| Target | Location | Stored Where | Rationale |
+|--------|----------|-------------|-----------|
+| `"ceo"` in `AGENT_ROLES` | `packages/shared/src/constants.ts` | `agent_role` DB column | Existing rows contain this value |
+| `"hire_agent"` approval type | `packages/shared/src/constants.ts` APPROVAL_TYPES | `approval_type` DB column | Existing approvals reference this |
+| `"approve_ceo_strategy"` | `packages/shared/src/constants.ts` APPROVAL_TYPES | `approval_type` DB column | Existing approvals reference this |
+| `"bootstrap_ceo"` invite type | `packages/shared/src/constants.ts` | `invite_type` DB column | Existing invites reference this |
+| `company_id` FK values | All FK columns | PostgreSQL foreign keys | Data integrity constraint |
+
+---
+
+## Zone Summary
+
+| Zone | Count | Rule |
+|------|-------|------|
+| DISPLAY | ~40 surface points | Safe to rename in Phases 2-4 |
+| CODE | Many hundreds | Never rename — upstream sync priority |
+| STORED | ~8 enum/column values | Never rename — DB integrity |
+
+---
+
+## Decision Rule
+
+When the same term appears in multiple zones (e.g., "ceo" is both STORED as `AGENT_ROLES[0]` and DISPLAY as `AGENT_ROLE_LABELS.ceo` value), classify each occurrence independently. The key stays, only the display value changes.
+
+**Example:** `AGENT_ROLES` contains `"ceo"` (STORED — do not touch). `AGENT_ROLE_LABELS.ceo` has value `"CEO"` (DISPLAY — safe to change to `"Project Manager"`). Both live in the same file (`packages/shared/src/constants.ts`), but the treatment differs per occurrence.

AGENTS.md

@@ -26,6 +26,9 @@ Before making changes, read in this order:
 - `ui/`: React + Vite board UI
 - `packages/db/`: Drizzle schema, migrations, DB clients
 - `packages/shared/`: shared types, constants, validators, API path constants
+- `packages/adapters/`: agent adapter implementations (Claude, Codex, Cursor, etc.)
+- `packages/adapter-utils/`: shared adapter utilities
+- `packages/plugins/`: plugin system packages
 - `doc/`: operational and product docs
 
 ## 4. Dev Setup (Auto DB)

README.md

@@ -234,16 +234,27 @@ See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
 
 ## Roadmap
 
-- ⚪ Get OpenClaw onboarding easier
+- ✅ Plugin system (e.g. add a knowledge base, custom tracing, queues, etc)
-- ⚪ Get cloud agents working e.g. Cursor / e2b agents
+- ✅ Get OpenClaw / claw-style agent employees
-- ⚪ ClipMart - buy and sell entire agent companies
+- ✅ companies.sh - import and export entire organizations
-- ⚪ Easy agent configurations / easier to understand
+- ✅ Easy AGENTS.md configurations
-- ⚪ Better support for harness engineering
+- ✅ Skills Manager
-- 🟢 Plugin system (e.g. if you want to add a knowledgebase, custom tracing, queues, etc)
+- ✅ Scheduled Routines
-- ⚪ Better docs
+- ✅ Better Budgeting
+- ⚪ Artifacts & Deployments
+- ⚪ CEO Chat
+- ⚪ MAXIMIZER MODE
+- ⚪ Multiple Human Users
+- ⚪ Cloud / Sandbox agents (e.g. Cursor / e2b agents)
+- ⚪ Cloud deployments
+- ⚪ Desktop App
 
 <br/>
 
+## Community & Plugins
+
+Find Plugins and more at [awesome-paperclip](https://github.com/gsxdsm/awesome-paperclip)
+
 ## Contributing
 
 We welcome contributions. See the [contributing guide](CONTRIBUTING.md) for details.

cli/package.json

@@ -45,6 +45,7 @@
     "@paperclipai/adapter-pi-local": "workspace:*",
     "@paperclipai/adapter-openclaw-gateway": "workspace:*",
     "@paperclipai/adapter-utils": "workspace:*",
+    "@paperclipai/branding": "workspace:*",
     "@paperclipai/db": "workspace:*",
     "@paperclipai/server": "workspace:*",
     "@paperclipai/shared": "workspace:*",

cli/src/__tests__/company-import-export-e2e.test.ts

@@ -6,33 +6,15 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 import { createStoredZipArchive } from "./helpers/zip.js";
 
-type EmbeddedPostgresInstance = {
-  initialise(): Promise<void>;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
-
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
 const execFileAsync = promisify(execFile);
 type ServerProcess = ReturnType<typeof spawn>;
 
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
-}
-
 async function getAvailablePort(): Promise<number> {
   return await new Promise((resolve, reject) => {
     const server = net.createServer();
@@ -53,30 +35,13 @@ async function getAvailablePort(): Promise<number> {
   });
 }
 
-async function startTempDatabase() {
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
-  const dataDir = mkdtempSync(path.join(os.tmpdir(), "paperclip-company-cli-db-"));
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
 
-  const { applyPendingMigrations, ensurePostgresDatabase } = await import("@paperclipai/db");
+if (!embeddedPostgresSupport.supported) {
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
+  console.warn(
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
+    `Skipping embedded Postgres company import/export e2e tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
+  );
-  await applyPendingMigrations(connectionString);
-
-  return { connectionString, dataDir, instance };
 }
 
 function writeTestConfig(configPath: string, tempRoot: string, port: number, connectionString: string) {
@@ -265,26 +230,23 @@ async function waitForServer(
   );
 }
 
-describe("paperclipai company import/export e2e", () => {
+describeEmbeddedPostgres("paperclipai company import/export e2e", () => {
   let tempRoot = "";
   let configPath = "";
   let exportDir = "";
   let apiBase = "";
   let serverProcess: ServerProcess | null = null;
-  let dbDataDir = "";
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
-  let dbInstance: EmbeddedPostgresInstance | null = null;
 
   beforeAll(async () => {
     tempRoot = mkdtempSync(path.join(os.tmpdir(), "paperclip-company-cli-e2e-"));
     configPath = path.join(tempRoot, "config", "config.json");
     exportDir = path.join(tempRoot, "exported-company");
 
-    const db = await startTempDatabase();
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-company-cli-db-");
-    dbDataDir = db.dataDir;
-    dbInstance = db.instance;
 
     const port = await getAvailablePort();
-    writeTestConfig(configPath, tempRoot, port, db.connectionString);
+    writeTestConfig(configPath, tempRoot, port, tempDb.connectionString);
     apiBase = `http://127.0.0.1:${port}`;
 
     const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
@@ -294,7 +256,7 @@ describe("paperclipai company import/export e2e", () => {
       ["paperclipai", "run", "--config", configPath],
       {
         cwd: repoRoot,
-        env: createServerEnv(configPath, port, db.connectionString),
+        env: createServerEnv(configPath, port, tempDb.connectionString),
         stdio: ["ignore", "pipe", "pipe"],
       },
     );
@@ -311,10 +273,7 @@ describe("paperclipai company import/export e2e", () => {
 
   afterAll(async () => {
     await stopServerProcess(serverProcess);
-    await dbInstance?.stop();
+    await tempDb?.cleanup();
-    if (dbDataDir) {
-      rmSync(dbDataDir, { recursive: true, force: true });
-    }
     if (tempRoot) {
       rmSync(tempRoot, { recursive: true, force: true });
     }

cli/src/__tests__/company.test.ts

@@ -278,7 +278,7 @@ describe("renderCompanyImportPreview", () => {
     });
 
     expect(rendered).toContain("Include");
-    expect(rendered).toContain("company, projects, tasks, agents, skills");
+    expect(rendered).toContain("workspace, projects, tasks, agents, skills"); // [nexus] updated from "company" to "workspace"
     expect(rendered).toContain("7 agents total");
     expect(rendered).toContain("1 project total");
     expect(rendered).toContain("1 task total");
@@ -319,7 +319,7 @@ describe("renderCompanyImportResult", () => {
       },
     );
 
-    expect(rendered).toContain("Company");
+    expect(rendered).toContain("Workspace"); // [nexus] updated from "Company" to "Workspace"
     expect(rendered).toContain("https://paperclip.example/PAP/dashboard");
     expect(rendered).toContain("3 agents total (1 created, 1 updated, 1 skipped)");
     expect(rendered).toContain("3 projects total (1 created, 1 updated, 1 skipped)");

cli/src/__tests__/helpers/embedded-postgres.ts

@@ -0,0 +1,6 @@
+export {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestSupport,
+} from "@paperclipai/db";

cli/src/__tests__/http.test.ts

@@ -72,7 +72,7 @@ describe("PaperclipApiClient", () => {
       causeMessage: "fetch failed",
     } satisfies Partial<ApiConnectionError>);
     await expect(client.post("/api/companies/import/preview", {})).rejects.toThrow(
-      /Could not reach the Paperclip API\./,
+      /Could not reach the Nexus API\./, // [nexus] updated from "Paperclip API" to "Nexus API"
     );
     await expect(client.post("/api/companies/import/preview", {})).rejects.toThrow(
       /curl http:\/\/localhost:3100\/api\/health/,

cli/src/__tests__/worktree.test.ts

@@ -344,6 +344,87 @@ describe("worktree helpers", () => {
     }
   });
 
+  it("avoids ports already claimed by sibling worktree instance configs", async () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-claimed-ports-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const homeDir = path.join(tempRoot, ".paperclip-worktrees");
+    const siblingInstanceRoot = path.join(homeDir, "instances", "existing-worktree");
+    const originalCwd = process.cwd();
+
+    try {
+      fs.mkdirSync(repoRoot, { recursive: true });
+      fs.mkdirSync(siblingInstanceRoot, { recursive: true });
+      fs.writeFileSync(
+        path.join(siblingInstanceRoot, "config.json"),
+        JSON.stringify(
+          {
+            ...buildSourceConfig(),
+            database: {
+              mode: "embedded-postgres",
+              embeddedPostgresDataDir: path.join(siblingInstanceRoot, "db"),
+              embeddedPostgresPort: 54330,
+              backup: {
+                enabled: true,
+                intervalMinutes: 60,
+                retentionDays: 30,
+                dir: path.join(siblingInstanceRoot, "backups"),
+              },
+            },
+            logging: {
+              mode: "file",
+              logDir: path.join(siblingInstanceRoot, "logs"),
+            },
+            server: {
+              deploymentMode: "authenticated",
+              exposure: "private",
+              host: "127.0.0.1",
+              port: 3101,
+              allowedHostnames: ["localhost"],
+              serveUi: true,
+            },
+            storage: {
+              provider: "local_disk",
+              localDisk: {
+                baseDir: path.join(siblingInstanceRoot, "storage"),
+              },
+              s3: {
+                bucket: "paperclip",
+                region: "us-east-1",
+                prefix: "",
+                forcePathStyle: false,
+              },
+            },
+            secrets: {
+              provider: "local_encrypted",
+              strictMode: false,
+              localEncrypted: {
+                keyFilePath: path.join(siblingInstanceRoot, "secrets", "master.key"),
+              },
+            },
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+
+      process.chdir(repoRoot);
+      await worktreeInitCommand({
+        seed: false,
+        fromConfig: path.join(tempRoot, "missing", "config.json"),
+        home: homeDir,
+      });
+
+      const config = JSON.parse(fs.readFileSync(path.join(repoRoot, ".paperclip", "config.json"), "utf8"));
+      expect(config.server.port).toBe(3102);
+      expect(config.database.embeddedPostgresPort).not.toBe(54330);
+      expect(config.database.embeddedPostgresPort).not.toBe(config.server.port);
+      expect(config.database.embeddedPostgresPort).toBeGreaterThan(54330);
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
   it("defaults the seed source config to the current repo-local Paperclip config", () => {
     const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-source-config-"));
     const repoRoot = path.join(tempRoot, "repo");

cli/src/client/board-auth.ts

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
+import { VOCAB } from "@paperclipai/branding"; // [nexus]
 import { buildCliCommandLabel } from "./command-label.js";
 import { resolveDefaultCliAuthPath } from "../config/home.js";
 
@@ -215,7 +216,7 @@ export async function loginBoardCli(params: {
 
   const approvalUrl = challenge.approvalUrl ?? `${apiBase}${challenge.approvalPath}`;
   if (params.print !== false) {
-    console.error(pc.bold("Board authentication required"));
+    console.error(pc.bold(`${VOCAB.board} authentication required`)); // [nexus]
     console.error(`Open this URL in your browser to approve CLI access:\n${approvalUrl}`);
   }
 

cli/src/client/http.ts

@@ -1,4 +1,5 @@
 import { URL } from "node:url";
+import { VOCAB } from "@paperclipai/branding"; // [nexus]
 
 export class ApiRequestError extends Error {
   status: number;
@@ -205,7 +206,7 @@ function buildConnectionErrorMessage(input: {
 }): string {
   const healthUrl = buildHealthCheckUrl(input.url);
   const lines = [
-    "Could not reach the Paperclip API.",
+    `Could not reach the ${VOCAB.appName} API.`, // [nexus]
     "",
     `Request: ${input.method} ${input.url}`,
   ];
@@ -214,12 +215,12 @@ function buildConnectionErrorMessage(input: {
   }
   lines.push(
     "",
-    "This usually means the Paperclip server is not running, the configured URL is wrong, or the request is being blocked before it reaches Paperclip.",
+    `This usually means the ${VOCAB.appName} server is not running, the configured URL is wrong, or the request is being blocked before it reaches ${VOCAB.appName}.`, // [nexus]
     "",
     "Try:",
-    "- Start Paperclip with `pnpm dev` or `pnpm paperclipai run`.",
+    `- Start ${VOCAB.appName} with \`pnpm dev\` or \`pnpm paperclipai run\`.`, // [nexus]
     `- Verify the server is reachable with \`curl ${healthUrl}\`.`,
-    `- If Paperclip is running elsewhere, pass \`--api-base ${input.apiBase.replace(/\/+$/, "")}\` or set \`PAPERCLIP_API_URL\`.`,
+    `- If ${VOCAB.appName} is running elsewhere, pass \`--api-base ${input.apiBase.replace(/\/+$/, "")}\` or set \`PAPERCLIP_API_URL\`.`, // [nexus]
   );
   return lines.join("\n");
 }

cli/src/commands/auth-bootstrap-ceo.ts

@@ -3,6 +3,7 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { and, eq, gt, isNull } from "drizzle-orm";
 import { createDb, instanceUserRoles, invites } from "@paperclipai/db";
+import { VOCAB } from "@paperclipai/branding"; // [nexus]
 import { loadPaperclipEnvFile } from "../config/env.js";
 import { readConfig, resolveConfigPath } from "../config/store.js";
 
@@ -57,12 +58,12 @@ export async function bootstrapCeoInvite(opts: {
   loadPaperclipEnvFile(configPath);
   const config = readConfig(configPath);
   if (!config) {
-    p.log.error(`No config found at ${configPath}. Run ${pc.cyan("paperclip onboard")} first.`);
+    p.log.error(`No config found at ${configPath}. Run ${pc.cyan("nexus onboard")} first.`); // [nexus]
     return;
   }
 
   if (config.server.deploymentMode !== "authenticated") {
-    p.log.info("Deployment mode is local_trusted. Bootstrap CEO invite is only required for authenticated mode.");
+    p.log.info(`Deployment mode is local_trusted. Bootstrap ${VOCAB.ceo} invite is only required for authenticated mode.`); // [nexus]
     return;
   }
 
@@ -121,12 +122,12 @@ export async function bootstrapCeoInvite(opts: {
 
     const baseUrl = resolveBaseUrl(configPath, opts.baseUrl);
     const inviteUrl = `${baseUrl}/invite/${token}`;
-    p.log.success("Created bootstrap CEO invite.");
+    p.log.success(`Created bootstrap ${VOCAB.ceo} invite.`); // [nexus]
     p.log.message(`Invite URL: ${pc.cyan(inviteUrl)}`);
     p.log.message(`Expires: ${pc.dim(created.expiresAt.toISOString())}`);
   } catch (err) {
     p.log.error(`Could not create bootstrap invite: ${err instanceof Error ? err.message : String(err)}`);
-    p.log.info("If using embedded-postgres, start the Paperclip server and run this command again.");
+    p.log.info(`If using embedded-postgres, start the ${VOCAB.appName} server and run this command again.`); // [nexus]
   } finally {
     await closableDb.$client?.end?.({ timeout: 5 }).catch(() => undefined);
   }

cli/src/commands/client/company.ts

@@ -11,6 +11,7 @@ import type {
   CompanyPortabilityPreviewResult,
   CompanyPortabilityImportResult,
 } from "@paperclipai/shared";
+import { VOCAB } from "@paperclipai/branding"; // [nexus]
 import { ApiRequestError } from "../../client/http.js";
 import { openUrl } from "../../client/board-auth.js";
 import { binaryContentTypeByExtension, readZipArchive } from "./zip.js";
@@ -78,7 +79,7 @@ const IMPORT_INCLUDE_OPTIONS: Array<{
   label: string;
   hint: string;
 }> = [
-  { value: "company", label: "Company", hint: "name, branding, and company settings" },
+  { value: "company", label: VOCAB.company, hint: "name, branding, and workspace settings" }, // [nexus]
   { value: "projects", label: "Projects", hint: "projects and workspace metadata" },
   { value: "issues", label: "Tasks", hint: "tasks and recurring routines" },
   { value: "agents", label: "Agents", hint: "agent records and org structure" },
@@ -389,8 +390,8 @@ async function promptForImportSelection(preview: CompanyPortabilityPreviewResult
       options: [
         {
           value: "company",
-          label: state.company ? "Company: included" : "Company: skipped",
+          label: state.company ? `${VOCAB.company}: included` : `${VOCAB.company}: skipped`, // [nexus]
-          hint: catalog.company.files.length > 0 ? "toggle company metadata" : "no company metadata in package",
+          hint: catalog.company.files.length > 0 ? `toggle ${VOCAB.company.toLowerCase()} metadata` : `no ${VOCAB.company.toLowerCase()} metadata in package`, // [nexus]
         },
         {
           value: "projects",
@@ -662,7 +663,7 @@ export function renderCompanyImportResult(
 ): string {
   const lines: string[] = [
     `${pc.bold("Target")}  ${meta.targetLabel}`,
-    `${pc.bold("Company")} ${result.company.name} (${actionChip(result.company.action)})`,
+    `${pc.bold(VOCAB.company)} ${result.company.name} (${actionChip(result.company.action)})`, // [nexus]
     `${pc.bold("Agents")}  ${summarizeImportAgentResults(result.agents)}`,
     `${pc.bold("Projects")} ${summarizeImportProjectResults(result.projects)}`,
   ];
@@ -1040,7 +1041,7 @@ function assertDeleteFlags(opts: CompanyDeleteOptions): void {
 }
 
 export function registerCompanyCommands(program: Command): void {
-  const company = program.command("company").description("Company operations");
+  const company = program.command("company").description(`${VOCAB.company} operations`) // [nexus];
 
   addCommonClientOptions(
     company

cli/src/commands/configure.ts

@@ -15,7 +15,7 @@ import {
   resolveDefaultLogsDir,
   resolvePaperclipInstanceId,
 } from "../config/home.js";
-import { printPaperclipCliBanner } from "../utils/banner.js";
+import { printNexusCliBanner } from "../utils/banner.js";
 
 type Section = "llm" | "database" | "logging" | "server" | "storage" | "secrets";
 
@@ -72,7 +72,7 @@ export async function configure(opts: {
   config?: string;
   section?: string;
 }): Promise<void> {
-  printPaperclipCliBanner();
+  printNexusCliBanner();
   p.intro(pc.bgCyan(pc.black(" paperclip configure ")));
   const configPath = resolveConfigPath(opts.config);
 

cli/src/commands/db-backup.ts

@@ -8,7 +8,7 @@ import {
   resolvePaperclipInstanceId,
 } from "../config/home.js";
 import { readConfig, resolveConfigPath } from "../config/store.js";
-import { printPaperclipCliBanner } from "../utils/banner.js";
+import { printNexusCliBanner } from "../utils/banner.js";
 
 type DbBackupOptions = {
   config?: string;
@@ -47,7 +47,7 @@ function resolveBackupDir(raw: string): string {
 }
 
 export async function dbBackupCommand(opts: DbBackupOptions): Promise<void> {
-  printPaperclipCliBanner();
+  printNexusCliBanner();
   p.intro(pc.bgCyan(pc.black(" paperclip db:backup ")));
 
   const configPath = resolveConfigPath(opts.config);

cli/src/commands/doctor.ts

@@ -15,7 +15,7 @@ import {
   type CheckResult,
 } from "../checks/index.js";
 import { loadPaperclipEnvFile } from "../config/env.js";
-import { printPaperclipCliBanner } from "../utils/banner.js";
+import { printNexusCliBanner } from "../utils/banner.js";
 
 const STATUS_ICON = {
   pass: pc.green("✓"),
@@ -28,7 +28,7 @@ export async function doctor(opts: {
   repair?: boolean;
   yes?: boolean;
 }): Promise<{ passed: number; warned: number; failed: number }> {
-  printPaperclipCliBanner();
+  printNexusCliBanner();
   p.intro(pc.bgCyan(pc.black(" paperclip doctor ")));
 
   const configPath = resolveConfigPath(opts.config);

cli/src/commands/onboard.ts

@@ -32,7 +32,91 @@ import {
   resolvePaperclipInstanceId,
 } from "../config/home.js";
 import { bootstrapCeoInvite } from "./auth-bootstrap-ceo.js";
-import { printPaperclipCliBanner } from "../utils/banner.js";
+import { printNexusCliBanner } from "../utils/banner.js";
+import { VOCAB } from "@paperclipai/branding"; // [nexus]
+
+// [nexus] Auto-create PM and Engineer agents on first run
+async function bootstrapNexusAgents(serverUrl: string, rootDir: string): Promise<void> {
+  // [nexus] Health-check poll — wait for server to be ready (max 30 seconds)
+  const maxRetries = 30;
+  let serverReady = false;
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const res = await fetch(`${serverUrl}/api/health`);
+      if (res.ok) {
+        serverReady = true;
+        break;
+      }
+    } catch {
+      // [nexus] Server not ready yet
+    }
+    if (i < maxRetries - 1) {
+      await new Promise<void>((r) => setTimeout(r, 1000));
+    }
+  }
+
+  if (!serverReady) {
+    console.warn("[nexus] Server did not become ready in 30s, skipping agent bootstrap");
+    return;
+  }
+
+  try {
+    // [nexus] Check if workspace already exists (idempotent — skip if already bootstrapped)
+    const companiesRes = await fetch(`${serverUrl}/api/companies`);
+    if (!companiesRes.ok) {
+      console.warn("[nexus] Could not fetch workspaces, skipping agent bootstrap");
+      return;
+    }
+    const companies = (await companiesRes.json()) as unknown[];
+    if (companies.length > 0) {
+      return; // [nexus] Already bootstrapped — skip
+    }
+
+    // [nexus] Create workspace
+    p.log.step(`Creating your ${VOCAB.company} workspace...`);
+    const companyRes = await fetch(`${serverUrl}/api/companies`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: VOCAB.appName }),
+    });
+    if (!companyRes.ok) {
+      console.warn("[nexus] Could not create workspace, skipping agent bootstrap");
+      return;
+    }
+    const company = (await companyRes.json()) as { id: string };
+
+    // [nexus] Create PM agent (role: "ceo" for elevated permissions — displays as Project Manager)
+    p.log.step(`Adding ${VOCAB.ceo} agent...`);
+    await fetch(`${serverUrl}/api/companies/${company.id}/agents`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        name: "Project Manager",
+        role: "ceo",
+        adapterType: "claude_local",
+        adapterConfig: { cwd: rootDir },
+      }),
+    });
+
+    // [nexus] Create Engineer agent
+    p.log.step("Adding Engineer agent...");
+    await fetch(`${serverUrl}/api/companies/${company.id}/agents`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        name: "Engineer",
+        role: "engineer",
+        adapterType: "claude_local",
+        adapterConfig: { cwd: rootDir },
+      }),
+    });
+
+    p.log.success("Workspace and agents created — you're ready to go!");
+  } catch (err) {
+    // [nexus] Bootstrap failures are warnings, not errors — user can create agents manually
+    console.warn("[nexus] Agent bootstrap failed:", err instanceof Error ? err.message : String(err));
+  }
+}
 
 type SetupMode = "quickstart" | "advanced";
 
@@ -234,8 +318,8 @@ function canCreateBootstrapInviteImmediately(config: Pick<PaperclipConfig, "data
 }
 
 export async function onboard(opts: OnboardOptions): Promise<void> {
-  printPaperclipCliBanner();
+  printNexusCliBanner();
-  p.intro(pc.bgCyan(pc.black(" paperclipai onboard ")));
+  p.intro(pc.bgCyan(pc.black(" nexus onboard "))); // [nexus]
   const configPath = resolveConfigPath(opts.config);
   const instance = describeLocalInstancePaths(resolvePaperclipInstanceId());
   p.log.message(
@@ -309,7 +393,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
         await db.execute("SELECT 1");
         s.stop("Database connection successful");
       } catch {
-        s.stop(pc.yellow("Could not connect to database — you can fix this later with `paperclipai doctor`"));
+        s.stop(pc.yellow("Could not connect to database — you can fix this later with `nexus doctor`")); // [nexus]
       }
     }
 
@@ -447,22 +531,22 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
 
   p.note(
     [
-      `Run: ${pc.cyan("paperclipai run")}`,
+      `Run: ${pc.cyan("nexus run")}`, // [nexus]
-      `Reconfigure later: ${pc.cyan("paperclipai configure")}`,
+      `Reconfigure later: ${pc.cyan("nexus configure")}`, // [nexus]
-      `Diagnose setup: ${pc.cyan("paperclipai doctor")}`,
+      `Diagnose setup: ${pc.cyan("nexus doctor")}`, // [nexus]
     ].join("\n"),
     "Next commands",
   );
 
   if (canCreateBootstrapInviteImmediately({ database, server })) {
-    p.log.step("Generating bootstrap CEO invite");
+    p.log.step(`Generating bootstrap ${VOCAB.ceo} invite`); // [nexus]
     await bootstrapCeoInvite({ config: configPath });
   }
 
   let shouldRunNow = opts.run === true || opts.yes === true;
   if (!shouldRunNow && !opts.invokedByRun && process.stdin.isTTY && process.stdout.isTTY) {
     const answer = await p.confirm({
-      message: "Start Paperclip now?",
+      message: `Start ${VOCAB.appName} now?`, // [nexus]
       initialValue: true,
     });
     if (!p.isCancel(answer)) {
@@ -473,6 +557,24 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
   if (shouldRunNow && !opts.invokedByRun) {
     process.env.PAPERCLIP_OPEN_ON_LISTEN = "true";
     const { runCommand } = await import("./run.js");
+    // [nexus] Start bootstrap concurrently — health-check poll waits for server readiness
+    const serverUrl = `http://${server.host}:${server.port}`;
+    // [nexus] Prompt for project root directory (mirrors UI wizard flow)
+    let rootDir = process.cwd();
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+      const answer = await p.text({
+        message: "Project root directory:",
+        initialValue: process.cwd(),
+        placeholder: process.cwd(),
+      });
+      if (!p.isCancel(answer) && answer) {
+        rootDir = answer;
+      }
+    }
+    bootstrapNexusAgents(serverUrl, rootDir).catch((err: unknown) => {
+      // [nexus] Bootstrap failures are non-fatal
+      console.warn("[nexus] Agent bootstrap error:", err instanceof Error ? err.message : String(err));
+    });
     await runCommand({ config: configPath, repair: true, yes: true });
     return;
   }
@@ -480,9 +582,9 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
   if (server.deploymentMode === "authenticated" && database.mode === "embedded-postgres") {
     p.log.info(
       [
-        "Bootstrap CEO invite will be created after the server starts.",
+        `Bootstrap ${VOCAB.ceo} invite will be created after the server starts.`, // [nexus]
-        `Next: ${pc.cyan("paperclipai run")}`,
+        `Next: ${pc.cyan("nexus run")}`, // [nexus]
-        `Then: ${pc.cyan("paperclipai auth bootstrap-ceo")}`,
+        `Then: ${pc.cyan("nexus auth bootstrap-ceo")}`, // [nexus]
       ].join("\n"),
     );
   }

cli/src/commands/worktree.ts

@@ -41,13 +41,15 @@ import {
   projects,
   runDatabaseBackup,
   runDatabaseRestore,
+  createEmbeddedPostgresLogBuffer,
+  formatEmbeddedPostgresError,
 } from "@paperclipai/db";
 import type { Command } from "commander";
 import { ensureAgentJwtSecret, loadPaperclipEnvFile, mergePaperclipEnvEntries, readPaperclipEnvEntries, resolvePaperclipEnvFile } from "../config/env.js";
 import { expandHomePrefix } from "../config/home.js";
 import type { PaperclipConfig } from "../config/schema.js";
 import { readConfig, resolveConfigPath, writeConfig } from "../config/store.js";
-import { printPaperclipCliBanner } from "../utils/banner.js";
+import { printNexusCliBanner } from "../utils/banner.js";
 import { resolveRuntimeLikePath } from "../utils/path-resolver.js";
 import {
   buildWorktreeConfig,
@@ -465,6 +467,62 @@ async function findAvailablePort(preferredPort: number, reserved = new Set<numbe
   return port;
 }
 
+function resolveRepoManagedWorktreesRoot(cwd: string): string | null {
+  const normalized = path.resolve(cwd);
+  const marker = `${path.sep}.paperclip${path.sep}worktrees${path.sep}`;
+  const index = normalized.indexOf(marker);
+  if (index === -1) return null;
+  const repoRoot = normalized.slice(0, index);
+  return path.resolve(repoRoot, ".paperclip", "worktrees");
+}
+
+function collectClaimedWorktreePorts(homeDir: string, currentInstanceId: string, cwd: string): {
+  serverPorts: Set<number>;
+  databasePorts: Set<number>;
+} {
+  const serverPorts = new Set<number>();
+  const databasePorts = new Set<number>();
+  const configPaths = new Set<string>();
+  const instancesDir = path.resolve(homeDir, "instances");
+  if (existsSync(instancesDir)) {
+    for (const entry of readdirSync(instancesDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === currentInstanceId) continue;
+
+      const configPath = path.resolve(instancesDir, entry.name, "config.json");
+      if (existsSync(configPath)) {
+        configPaths.add(configPath);
+      }
+    }
+  }
+
+  const repoManagedWorktreesRoot = resolveRepoManagedWorktreesRoot(cwd);
+  if (repoManagedWorktreesRoot && existsSync(repoManagedWorktreesRoot)) {
+    for (const entry of readdirSync(repoManagedWorktreesRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const configPath = path.resolve(repoManagedWorktreesRoot, entry.name, ".paperclip", "config.json");
+      if (existsSync(configPath)) {
+        configPaths.add(configPath);
+      }
+    }
+  }
+
+  for (const configPath of configPaths) {
+    try {
+      const config = readConfig(configPath);
+      if (config?.server.port) {
+        serverPorts.add(config.server.port);
+      }
+      if (config?.database.mode === "embedded-postgres") {
+        databasePorts.add(config.database.embeddedPostgresPort);
+      }
+    } catch {
+      // Ignore malformed sibling configs.
+    }
+  }
+
+  return { serverPorts, databasePorts };
+}
+
 function detectGitBranchName(cwd: string): string | null {
   try {
     const value = execFileSync("git", ["branch", "--show-current"], {
@@ -750,6 +808,7 @@ async function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): P
   }
 
   const port = await findAvailablePort(preferredPort);
+  const logBuffer = createEmbeddedPostgresLogBuffer();
   const instance = new EmbeddedPostgres({
     databaseDir: dataDir,
     user: "paperclip",
@@ -757,17 +816,31 @@ async function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): P
     port,
     persistent: true,
     initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
+    onLog: logBuffer.append,
-    onError: () => {},
+    onError: logBuffer.append,
   });
 
   if (!existsSync(path.resolve(dataDir, "PG_VERSION"))) {
-    await instance.initialise();
+    try {
+      await instance.initialise();
+    } catch (error) {
+      throw formatEmbeddedPostgresError(error, {
+        fallbackMessage: `Failed to initialize embedded PostgreSQL cluster in ${dataDir} on port ${port}`,
+        recentLogs: logBuffer.getRecentLogs(),
+      });
+    }
   }
   if (existsSync(postmasterPidFile)) {
     rmSync(postmasterPidFile, { force: true });
   }
-  await instance.start();
+  try {
+    await instance.start();
+  } catch (error) {
+    throw formatEmbeddedPostgresError(error, {
+      fallbackMessage: `Failed to start embedded PostgreSQL on port ${port}`,
+      recentLogs: logBuffer.getRecentLogs(),
+    });
+  }
 
   return {
     port,
@@ -886,10 +959,14 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
     rmSync(paths.instanceRoot, { recursive: true, force: true });
   }
 
+  const claimedPorts = collectClaimedWorktreePorts(paths.homeDir, paths.instanceId, paths.cwd);
   const preferredServerPort = opts.serverPort ?? ((sourceConfig?.server.port ?? 3100) + 1);
-  const serverPort = await findAvailablePort(preferredServerPort);
+  const serverPort = await findAvailablePort(preferredServerPort, claimedPorts.serverPorts);
   const preferredDbPort = opts.dbPort ?? ((sourceConfig?.database.embeddedPostgresPort ?? 54329) + 1);
-  const databasePort = await findAvailablePort(preferredDbPort, new Set([serverPort]));
+  const databasePort = await findAvailablePort(
+    preferredDbPort,
+    new Set([...claimedPorts.databasePorts, serverPort]),
+  );
   const targetConfig = buildWorktreeConfig({
     sourceConfig,
     paths,
@@ -969,13 +1046,13 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
 }
 
 export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<void> {
-  printPaperclipCliBanner();
+  printNexusCliBanner();
   p.intro(pc.bgCyan(pc.black(" paperclipai worktree init ")));
   await runWorktreeInit(opts);
 }
 
 export async function worktreeMakeCommand(nameArg: string, opts: WorktreeMakeOptions): Promise<void> {
-  printPaperclipCliBanner();
+  printNexusCliBanner();
   p.intro(pc.bgCyan(pc.black(" paperclipai worktree:make ")));
 
   const name = resolveWorktreeMakeName(nameArg);
@@ -1171,7 +1248,7 @@ function worktreePathHasUncommittedChanges(worktreePath: string): boolean {
 }
 
 export async function worktreeCleanupCommand(nameArg: string, opts: WorktreeCleanupOptions): Promise<void> {
-  printPaperclipCliBanner();
+  printNexusCliBanner();
   p.intro(pc.bgCyan(pc.black(" paperclipai worktree:cleanup ")));
 
   const name = resolveWorktreeMakeName(nameArg);

cli/src/config/home.ts

@@ -1,10 +1,33 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
 const DEFAULT_INSTANCE_ID = "default";
 const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
 
+// [nexus] Read ~/.nexus pointer file for custom home directory
+function resolveNexusPointerFile(): string | null {
+  const pointerPath = path.resolve(os.homedir(), ".nexus");
+  try {
+    const raw = fs.readFileSync(pointerPath, "utf-8").trim();
+    if (raw.length > 0) {
+      // Inline tilde expansion (expandHomePrefix is defined later in this file)
+      const expanded = raw === "~" ? os.homedir()
+        : raw.startsWith("~/") ? path.resolve(os.homedir(), raw.slice(2))
+        : raw;
+      return path.resolve(expanded);
+    }
+  } catch {
+    // ~/.nexus does not exist or is unreadable — fall through
+  }
+  return null;
+}
+
 export function resolvePaperclipHomeDir(): string {
+  // [nexus] Pointer-file: ~/.nexus overrides all other home resolution
+  const nexusRoot = resolveNexusPointerFile();
+  if (nexusRoot) return nexusRoot;
+
   const envHome = process.env.PAPERCLIP_HOME?.trim();
   if (envHome) return path.resolve(expandHomePrefix(envHome));
   return path.resolve(os.homedir(), ".paperclip");

cli/src/index.ts

@@ -20,14 +20,15 @@ import { loadPaperclipEnvFile } from "./config/env.js";
 import { registerWorktreeCommands } from "./commands/worktree.js";
 import { registerPluginCommands } from "./commands/client/plugin.js";
 import { registerClientAuthCommands } from "./commands/client/auth.js";
+import { VOCAB } from "@paperclipai/branding"; // [nexus]
 
 const program = new Command();
 const DATA_DIR_OPTION_HELP =
-  "Paperclip data directory root (isolates state from ~/.paperclip)";
+  `${VOCAB.appName} data directory root (isolates state from ~/.nexus)`; // [nexus]
 
 program
   .name("paperclipai")
-  .description("Paperclip CLI — setup, diagnose, and configure your instance")
+  .description(`${VOCAB.appName} CLI — setup, diagnose, and configure your instance`) // [nexus]
   .version("0.2.7");
 
 program.hook("preAction", (_thisCommand, actionCommand) => {
@@ -46,12 +47,12 @@ program
   .option("-c, --config <path>", "Path to config file")
   .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
   .option("-y, --yes", "Accept defaults (quickstart + start immediately)", false)
-  .option("--run", "Start Paperclip immediately after saving config", false)
+  .option("--run", `Start ${VOCAB.appName} immediately after saving config`, false) // [nexus]
   .action(onboard);
 
 program
   .command("doctor")
-  .description("Run diagnostic checks on your Paperclip setup")
+  .description(`Run diagnostic checks on your ${VOCAB.appName} setup`) // [nexus]
   .option("-c, --config <path>", "Path to config file")
   .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
   .option("--repair", "Attempt to repair issues automatically")
@@ -83,7 +84,7 @@ program
   .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
   .option("--dir <path>", "Backup output directory (overrides config)")
   .option("--retention-days <days>", "Retention window used for pruning", (value) => Number(value))
-  .option("--filename-prefix <prefix>", "Backup filename prefix", "paperclip")
+  .option("--filename-prefix <prefix>", "Backup filename prefix", "nexus") // [nexus]
   .option("--json", "Print backup metadata as JSON")
   .action(async (opts) => {
     await dbBackupCommand(opts);
@@ -99,7 +100,7 @@ program
 
 program
   .command("run")
-  .description("Bootstrap local setup (onboard + doctor) and run Paperclip")
+  .description(`Bootstrap local setup (onboard + doctor) and run ${VOCAB.appName}`) // [nexus]
   .option("-c, --config <path>", "Path to config file")
   .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
   .option("-i, --instance <id>", "Local instance id (default: default)")
@@ -117,7 +118,7 @@ heartbeat
   .option("-d, --data-dir <path>", DATA_DIR_OPTION_HELP)
   .option("--context <path>", "Path to CLI context file")
   .option("--profile <name>", "CLI context profile name")
-  .option("--api-base <url>", "Base URL for the Paperclip server API")
+  .option("--api-base <url>", `Base URL for the ${VOCAB.appName} server API`) // [nexus]
   .option("--api-key <token>", "Bearer token for agent-authenticated calls")
   .option(
     "--source <source>",

cli/src/utils/banner.ts

@@ -1,20 +1,23 @@
 import pc from "picocolors";
 
-const PAPERCLIP_ART = [
+// [nexus] replaced PAPERCLIP_ART with NEXUS_ART
-  "██████╗  █████╗ ██████╗ ███████╗██████╗  ██████╗██╗     ██╗██████╗ ",
+const NEXUS_ART = [
-  "██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗██╔════╝██║     ██║██╔══██╗",
+  "███╗   ██╗███████╗██╗  ██╗██╗   ██╗███████╗",
-  "██████╔╝███████║██████╔╝█████╗  ██████╔╝██║     ██║     ██║██████╔╝",
+  "████╗  ██║██╔════╝╚██╗██╔╝██║   ██║██╔════╝",
-  "██╔═══╝ ██╔══██║██╔═══╝ ██╔══╝  ██╔══██╗██║     ██║     ██║██╔═══╝ ",
+  "██╔██╗ ██║█████╗   ╚███╔╝ ██║   ██║███████╗",
-  "██║     ██║  ██║██║     ███████╗██║  ██║╚██████╗███████╗██║██║     ",
+  "██║╚██╗██║██╔══╝   ██╔██╗ ██║   ██║╚════██║",
-  "╚═╝     ╚═╝  ╚═╝╚═╝     ╚══════╝╚═╝  ╚═╝ ╚═════╝╚══════╝╚═╝╚═╝     ",
+  "██║ ╚████║███████╗██╔╝ ██╗╚██████╔╝███████║",
+  "╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝",
 ] as const;
 
-const TAGLINE = "Open-source orchestration for zero-human companies";
+// [nexus] updated tagline
+const TAGLINE = "Open-source orchestration for your agents";
 
-export function printPaperclipCliBanner(): void {
+// [nexus] renamed from printPaperclipCliBanner
+export function printNexusCliBanner(): void {
   const lines = [
     "",
-    ...PAPERCLIP_ART.map((line) => pc.cyan(line)),
+    ...NEXUS_ART.map((line) => pc.cyan(line)),
     pc.blue("  ───────────────────────────────────────────────────────"),
     pc.bold(pc.white(`  ${TAGLINE}`)),
     "",

doc/DEVELOPING.md

@@ -206,6 +206,17 @@ 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:
+
+```sh
+cd ~/.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
+```
+
+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.
+
 **`pnpm paperclipai worktree:make <name> [options]`** — Create `~/NAME` as a git worktree, then initialize an isolated Paperclip instance inside it. This combines `git worktree add` with `worktree init` in a single step.
 
 | Option | Description |

doc/PUBLISHING.md

@@ -51,10 +51,9 @@ Public packages are discovered from:
 
 - `packages/`
 - `server/`
+- `ui/`
 - `cli/`
 
-`ui/` is ignored because it is private.
-
 The version rewrite step now uses [`scripts/release-package-map.mjs`](../scripts/release-package-map.mjs), which:
 
 - finds all public packages
@@ -65,6 +64,18 @@ The version rewrite step now uses [`scripts/release-package-map.mjs`](../scripts
 
 Those rewrites are temporary. The working tree is restored after publish or dry-run.
 
+## `@paperclipai/ui` packaging
+
+The UI package publishes prebuilt static assets, not the source workspace.
+
+The `ui` package uses [`scripts/generate-ui-package-json.mjs`](../scripts/generate-ui-package-json.mjs) during `prepack` to swap in a lean publish manifest that:
+
+- keeps the release-managed `name` and `version`
+- publishes only `dist/`
+- omits the source-only dependency graph from downstream installs
+
+After packing or publishing, `postpack` restores the development manifest automatically.
+
 ## Version formats
 
 Paperclip uses calendar versions:
@@ -135,6 +146,7 @@ This is the fastest way to restore the default install path if a stable release
 
 - [`scripts/build-npm.sh`](../scripts/build-npm.sh)
 - [`scripts/generate-npm-package-json.mjs`](../scripts/generate-npm-package-json.mjs)
+- [`scripts/generate-ui-package-json.mjs`](../scripts/generate-ui-package-json.mjs)
 - [`scripts/release-package-map.mjs`](../scripts/release-package-map.mjs)
 - [`cli/esbuild.config.mjs`](../cli/esbuild.config.mjs)
 - [`doc/RELEASING.md`](RELEASING.md)

doc/RELEASE-AUTOMATION-SETUP.md

@@ -35,6 +35,7 @@ At minimum that includes:
 
 - `paperclipai`
 - `@paperclipai/server`
+- `@paperclipai/ui`
 - public packages under `packages/`
 
 ### 2.1. In npm, open each package settings page

doc/SPEC.md

@@ -186,17 +186,21 @@ The heartbeat is a protocol, not a runtime. Paperclip defines how to initiate an
 
 ### Execution Adapters
 
-Agent configuration includes an **adapter** that defines how Paperclip invokes the agent. Initial adapters:
+Agent configuration includes an **adapter** that defines how Paperclip invokes the agent. Built-in adapters include:
 
-| Adapter              | Mechanism               | Example                                       |
+| Adapter | Mechanism | Example |
-| -------------------- | ----------------------- | --------------------------------------------- |
+| ---------------- | -------------------------- | -------------------------------------------------- |
-| `process`            | Execute a child process | `python run_agent.py --agent-id {id}`         |
+| `process` | Execute a child process | `python run_agent.py --agent-id {id}` |
-| `http`               | Send an HTTP request    | `POST https://openclaw.example.com/hook/{id}` |
+| `http` | Send an HTTP request | `POST https://openclaw.example.com/hook/{id}` |
-| `openclaw_gateway`   | OpenClaw gateway API    | Managed OpenClaw agent via gateway             |
+| `claude_local` | Local Claude Code process | Claude Code heartbeat worker |
-| `gemini_local`       | Gemini CLI process      | Local Gemini CLI with sandbox and approval     |
+| `codex_local` | Local Codex process | Codex CLI heartbeat worker |
-| `hermes_local`       | Hermes agent process    | Local Hermes agent                             |
+| `opencode_local` | Local OpenCode process | OpenCode heartbeat worker |
+| `pi_local` | Local Pi process | Pi CLI heartbeat worker |
+| `cursor` | Cursor API/CLI bridge | Cursor-integrated heartbeat worker |
+| `openclaw_gateway` | OpenClaw gateway API | Managed OpenClaw agent via gateway |
+| `hermes_local` | Local Hermes process | Hermes agent heartbeat worker |
 
-The `process` and `http` adapters ship as defaults. Additional adapters have been added for specific agent runtimes (see list above), and new adapter types can be registered via the plugin system (see Plugin / Extension Architecture).
+The `process` and `http` adapters ship as generic defaults. Additional built-in adapters cover common local coding runtimes (see list above), and new adapter types can be registered via the plugin system (see Plugin / Extension Architecture).
 
 ### Adapter Interface
 
@@ -376,7 +380,7 @@ Flow:
 | Layer    | Technology                                                   |
 | -------- | ------------------------------------------------------------ |
 | Frontend | React + Vite                                                 |
-| Backend  | TypeScript + Hono (REST API, not tRPC — need non-TS clients) |
+| Backend  | TypeScript + Express (REST API, not tRPC — need non-TS clients) |
 | Database | PostgreSQL (see [doc/DATABASE.md](./doc/DATABASE.md) for details — PGlite embedded for dev, Docker or hosted Supabase for production) |
 | Auth     | [Better Auth](https://www.better-auth.com/)                  |
 
@@ -406,7 +410,7 @@ No separate "agent API" vs. "board API." Same endpoints, different authorization
 
 ### Work Artifacts
 
-Paperclip does **not** manage work artifacts (code repos, file systems, deployments, documents). That's entirely the agent's domain. Paperclip tracks tasks and costs. Where and how work gets done is outside scope.
+Paperclip manages task-linked work artifacts: issue documents (rich-text plans, specs, notes attached to issues) and file attachments. Agents read and write these through the API as part of normal task execution. Full delivery infrastructure (code repos, deployments, production runtime) remains the agent's domain — Paperclip orchestrates the work, not the build pipeline.
 
 ### Open Questions
 
@@ -476,15 +480,14 @@ Each is a distinct page/route:
 - [ ] **Default agent** — basic Claude Code/Codex loop with Paperclip skill
 - [ ] **Default CEO** — strategic planning, delegation, board communication
 - [ ] **Paperclip skill (SKILL.md)** — teaches agents to interact with the API
-- [ ] **REST API** — full API for agent interaction (Hono)
+- [ ] **REST API** — full API for agent interaction (Express)
 - [ ] **Web UI** — React/Vite: org chart, task board, dashboard, cost views
 - [ ] **Agent auth** — connection string generation with URL + key + instructions
 - [ ] **One-command dev setup** — embedded PGlite, everything local
-- [ ] **Multiple Adapter types** (HTTP Adapter, OpenClaw Adapter)
+- [ ] **Multiple Adapter types** (HTTP, OpenClaw gateway, and local coding adapters)
 
 ### Not V1
 
-- Template export/import
 - Knowledge base - a future plugin
 - Advanced governance models (hiring budgets, multi-member boards)
 - Revenue/expense tracking beyond token costs - a future plugin
@@ -509,7 +512,7 @@ Things Paperclip explicitly does **not** do:
 - **Not a SaaS** — single-tenant, self-hosted
 - **Not opinionated about Agent implementation** — any language, any framework, any runtime
 - **Not automatically self-healing** — surfaces problems, doesn't silently fix them
-- **Does not manage work artifacts** — no repo management, no deployment, no file systems
+- **Does not manage delivery infrastructure** — no repo management, no deployment, no file systems (but does manage task-linked documents and attachments)
 - **Does not auto-reassign work** — stale tasks are surfaced, not silently redistributed
 - **Does not track external revenue/expenses** — that's a future plugin. Token/LLM cost budgeting is core.
 

docs/agents-runtime.md

@@ -1,7 +1,7 @@
 # Agent Runtime Guide
 
 Status: User-facing guide
-Last updated: 2026-02-17  
+Last updated: 2026-03-26
 Audience: Operators setting up and running agents in Paperclip
 
 ## 1. What this system does
@@ -32,14 +32,19 @@ If an agent is already running, new wakeups are merged (coalesced) instead of la
 
 ## 3.1 Adapter choice
 
-Common choices:
+Built-in adapters:
 
 - `claude_local`: runs your local `claude` CLI
 - `codex_local`: runs your local `codex` CLI
+- `opencode_local`: runs your local `opencode` CLI
+- `hermes_local`: runs your local `hermes` CLI
+- `cursor`: runs Cursor in background mode
+- `pi_local`: runs an embedded Pi agent locally
+- `openclaw_gateway`: connects to an OpenClaw gateway endpoint
 - `process`: generic shell command adapter
 - `http`: calls an external HTTP endpoint
 
-For `claude_local` and `codex_local`, Paperclip assumes the CLI is already installed and authenticated on the host machine.
+For local CLI adapters (`claude_local`, `codex_local`, `opencode_local`, `hermes_local`), Paperclip assumes the CLI is already installed and authenticated on the host machine.
 
 ## 3.2 Runtime behavior
 
@@ -69,6 +74,8 @@ You can set:
 
 Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values.
 
+> **Note:** `bootstrapPromptTemplate` is deprecated and should not be used for new agents. Existing configs that use it will continue to work but should be migrated to the managed instructions bundle system.
+
 ## 4. Session resume behavior
 
 Paperclip stores session IDs for resumable adapters.
@@ -133,7 +140,7 @@ If the connection drops, the UI reconnects automatically.
 
 If runs fail repeatedly:
 
-1. Check adapter command availability (`claude`/`codex` installed and logged in).
+1. Check adapter command availability (e.g. `claude`/`codex`/`opencode`/`hermes` installed and logged in).
 2. Verify `cwd` exists and is accessible.
 3. Inspect run error + stderr excerpt, then full log.
 4. Confirm timeout is not too low.
@@ -166,9 +173,9 @@ Start with least privilege where possible, and avoid exposing secrets in broad r
 
 ## 10. Minimal setup checklist
 
-1. Choose adapter (`claude_local` or `codex_local`).
+1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `cursor`, or `openclaw_gateway`).
-2. Set `cwd` to the target workspace.
+2. Set `cwd` to the target workspace (for local adapters).
-3. Add bootstrap + normal prompt templates.
+3. Optionally add a prompt template (`promptTemplate`) or use the managed instructions bundle.
 4. Configure heartbeat policy (timer and/or assignment wakeups).
 5. Trigger a manual wakeup.
 6. Confirm run succeeds and session/token usage is recorded.

packages/branding/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@paperclipai/branding",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./*": {
+        "types": "./dist/*.d.ts",
+        "import": "./dist/*.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3"
+  }
+}

packages/branding/src/index.ts

@@ -0,0 +1 @@
+export { VOCAB, type VocabKey } from "./vocab.js";

packages/branding/src/vocab.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from "vitest";
+import { VOCAB } from "./vocab.js";
+
+describe("VOCAB", () => {
+  it("maps company to Workspace", () => {
+    expect(VOCAB.company).toBe("Workspace");
+  });
+  it("maps companies to Workspaces", () => {
+    expect(VOCAB.companies).toBe("Workspaces");
+  });
+  it("maps ceo to Project Manager", () => {
+    expect(VOCAB.ceo).toBe("Project Manager");
+  });
+  it("maps board to Owner", () => {
+    expect(VOCAB.board).toBe("Owner");
+  });
+  it("maps hire to Add", () => {
+    expect(VOCAB.hire).toBe("Add");
+  });
+  it("maps fire to Remove", () => {
+    expect(VOCAB.fire).toBe("Remove");
+  });
+  it("has appName as Nexus", () => {
+    expect(VOCAB.appName).toBe("Nexus");
+  });
+  it("has a non-empty tagline", () => {
+    expect(VOCAB.tagline).toBe("Open-source orchestration for your agents");
+  });
+  it("all values are non-empty strings", () => {
+    for (const [key, value] of Object.entries(VOCAB)) {
+      expect(typeof value, `key "${key}" should be a string`).toBe("string");
+      expect(value.length, `key "${key}" should be non-empty`).toBeGreaterThan(0);
+    }
+  });
+});

packages/branding/src/vocab.ts

@@ -0,0 +1,15 @@
+export const VOCAB = {
+  // Entity renames (display only — code identifiers unchanged)
+  company: "Workspace",
+  companies: "Workspaces",
+  ceo: "Project Manager",
+  board: "Owner",
+  hire: "Add",
+  fire: "Remove",
+
+  // Brand name
+  appName: "Nexus",
+  tagline: "Open-source orchestration for your agents",
+} as const;
+
+export type VocabKey = keyof typeof VOCAB;

packages/branding/tsconfig.json

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

packages/branding/vitest.config.ts

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

packages/db/src/client.test.ts

@@ -1,83 +1,24 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import postgres from "postgres";
 import {
   applyPendingMigrations,
-  ensurePostgresDatabase,
   inspectMigrations,
 } from "./client.js";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./test-embedded-postgres.js";
 
-type EmbeddedPostgresInstance = {
+const cleanups: Array<() => Promise<void>> = [];
-  initialise(): Promise<void>;
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
-  start(): Promise<void>;
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
-  stop(): Promise<void>;
-};
-
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-const tempPaths: string[] = [];
-const runningInstances: EmbeddedPostgresInstance[] = [];
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
-}
-
-async function getAvailablePort(): Promise<number> {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
 
 async function createTempDatabase(): Promise<string> {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-client-"));
+  const db = await startEmbeddedPostgresTestDatabase("paperclip-db-client-");
-  tempPaths.push(dataDir);
+  cleanups.push(db.cleanup);
-  const port = await getAvailablePort();
+  return db.connectionString;
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-  runningInstances.push(instance);
-
-  const adminUrl = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminUrl, "paperclip");
-  return `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
 }
 
 async function migrationHash(migrationFile: string): Promise<string> {
@@ -89,19 +30,19 @@ async function migrationHash(migrationFile: string): Promise<string> {
 }
 
 afterEach(async () => {
-  while (runningInstances.length > 0) {
+  while (cleanups.length > 0) {
-    const instance = runningInstances.pop();
+    const cleanup = cleanups.pop();
-    if (!instance) continue;
+    await cleanup?.();
-    await instance.stop();
-  }
-  while (tempPaths.length > 0) {
-    const tempPath = tempPaths.pop();
-    if (!tempPath) continue;
-    fs.rmSync(tempPath, { recursive: true, force: true });
   }
 });
 
-describe("applyPendingMigrations", () => {
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres migration tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+describeEmbeddedPostgres("applyPendingMigrations", () => {
   it(
     "applies an inserted earlier migration without replaying later legacy migrations",
     async () => {

packages/db/src/embedded-postgres-error.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { createEmbeddedPostgresLogBuffer, formatEmbeddedPostgresError } from "./embedded-postgres-error.js";
+
+describe("formatEmbeddedPostgresError", () => {
+  it("adds a shared-memory hint when initdb logs expose the real cause", () => {
+    const error = formatEmbeddedPostgresError("Postgres init script exited with code 1.", {
+      fallbackMessage: "Failed to initialize embedded PostgreSQL cluster",
+      recentLogs: [
+        "running bootstrap script ...",
+        "FATAL:  could not create shared memory segment: Cannot allocate memory",
+        "DETAIL:  Failed system call was shmget(key=123, size=56, 03600).",
+      ],
+    });
+
+    expect(error.message).toContain("could not allocate shared memory");
+    expect(error.message).toContain("kern.sysv.shm");
+    expect(error.message).toContain("could not create shared memory segment");
+  });
+
+  it("keeps only recent non-empty log lines in the collector", () => {
+    const buffer = createEmbeddedPostgresLogBuffer(2);
+    buffer.append("line one\n\n");
+    buffer.append("line two");
+    buffer.append("line three");
+
+    expect(buffer.getRecentLogs()).toEqual(["line two", "line three"]);
+  });
+});

packages/db/src/embedded-postgres-error.ts

@@ -0,0 +1,89 @@
+const DEFAULT_RECENT_LOG_LIMIT = 40;
+const RECENT_LOG_SUMMARY_LINES = 8;
+
+function toError(error: unknown, fallbackMessage: string): Error {
+  if (error instanceof Error) return error;
+  if (error === undefined) return new Error(fallbackMessage);
+  if (typeof error === "string") return new Error(`${fallbackMessage}: ${error}`);
+
+  try {
+    return new Error(`${fallbackMessage}: ${JSON.stringify(error)}`);
+  } catch {
+    return new Error(`${fallbackMessage}: ${String(error)}`);
+  }
+}
+
+function summarizeRecentLogs(recentLogs: string[]): string | null {
+  if (recentLogs.length === 0) return null;
+  return recentLogs
+    .slice(-RECENT_LOG_SUMMARY_LINES)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .join(" | ");
+}
+
+function detectEmbeddedPostgresHint(recentLogs: string[]): string | null {
+  const haystack = recentLogs.join("\n").toLowerCase();
+  if (!haystack.includes("could not create shared memory segment")) {
+    return null;
+  }
+
+  return (
+    "Embedded PostgreSQL bootstrap could not allocate shared memory. " +
+    "On macOS, this usually means the host's kern.sysv.shm* limits are too low for another local PostgreSQL cluster. " +
+    "Stop other local PostgreSQL servers or raise the shared-memory sysctls, then retry."
+  );
+}
+
+export function createEmbeddedPostgresLogBuffer(limit = DEFAULT_RECENT_LOG_LIMIT): {
+  append(message: unknown): void;
+  getRecentLogs(): string[];
+} {
+  const recentLogs: string[] = [];
+
+  return {
+    append(message: unknown) {
+      const text =
+        typeof message === "string"
+          ? message
+          : message instanceof Error
+            ? message.message
+            : String(message ?? "");
+
+      for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line) continue;
+        recentLogs.push(line);
+        if (recentLogs.length > limit) {
+          recentLogs.splice(0, recentLogs.length - limit);
+        }
+      }
+    },
+    getRecentLogs() {
+      return [...recentLogs];
+    },
+  };
+}
+
+export function formatEmbeddedPostgresError(
+  error: unknown,
+  input: {
+    fallbackMessage: string;
+    recentLogs?: string[];
+  },
+): Error {
+  const baseError = toError(error, input.fallbackMessage);
+  const recentLogs = input.recentLogs ?? [];
+  const parts = [baseError.message];
+  const hint = detectEmbeddedPostgresHint(recentLogs);
+  const recentSummary = summarizeRecentLogs(recentLogs);
+
+  if (hint) {
+    parts.push(hint);
+  }
+  if (recentSummary) {
+    parts.push(`Recent embedded Postgres logs: ${recentSummary}`);
+  }
+
+  return new Error(parts.join(" "));
+}

packages/db/src/index.ts

@@ -11,6 +11,12 @@ export {
   type MigrationBootstrapResult,
   type Db,
 } from "./client.js";
+export {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestSupport,
+} from "./test-embedded-postgres.js";
 export {
   runDatabaseBackup,
   runDatabaseRestore,
@@ -19,4 +25,8 @@ export {
   type RunDatabaseBackupResult,
   type RunDatabaseRestoreOptions,
 } from "./backup-lib.js";
+export {
+  createEmbeddedPostgresLogBuffer,
+  formatEmbeddedPostgresError,
+} from "./embedded-postgres-error.js";
 export * from "./schema/index.js";

packages/db/src/migration-runtime.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, rmSync } from "node:fs";
 import { createServer } from "node:net";
 import path from "node:path";
 import { ensurePostgresDatabase, getPostgresDataDirectory } from "./client.js";
+import { createEmbeddedPostgresLogBuffer, formatEmbeddedPostgresError } from "./embedded-postgres-error.js";
 import { resolveDatabaseTarget } from "./runtime-config.js";
 
 type EmbeddedPostgresInstance = {
@@ -27,18 +28,6 @@ export type MigrationConnection = {
   stop: () => Promise<void>;
 };
 
-function toError(error: unknown, fallbackMessage: string): Error {
-  if (error instanceof Error) return error;
-  if (error === undefined) return new Error(fallbackMessage);
-  if (typeof error === "string") return new Error(`${fallbackMessage}: ${error}`);
-
-  try {
-    return new Error(`${fallbackMessage}: ${JSON.stringify(error)}`);
-  } catch {
-    return new Error(`${fallbackMessage}: ${String(error)}`);
-  }
-}
-
 function readRunningPostmasterPid(postmasterPidFile: string): number | null {
   if (!existsSync(postmasterPidFile)) return null;
   try {
@@ -109,6 +98,7 @@ async function ensureEmbeddedPostgresConnection(
   const runningPid = readRunningPostmasterPid(postmasterPidFile);
   const runningPort = readPidFilePort(postmasterPidFile);
   const preferredAdminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${preferredPort}/postgres`;
+  const logBuffer = createEmbeddedPostgresLogBuffer();
 
   if (!runningPid && existsSync(pgVersionFile)) {
     try {
@@ -151,18 +141,19 @@ async function ensureEmbeddedPostgresConnection(
     port: selectedPort,
     persistent: true,
     initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
+    onLog: logBuffer.append,
-    onError: () => {},
+    onError: logBuffer.append,
   });
 
   if (!existsSync(path.resolve(dataDir, "PG_VERSION"))) {
     try {
       await instance.initialise();
     } catch (error) {
-      throw toError(
+      throw formatEmbeddedPostgresError(error, {
-        error,
+        fallbackMessage:
-        `Failed to initialize embedded PostgreSQL cluster in ${dataDir} on port ${selectedPort}`,
+          `Failed to initialize embedded PostgreSQL cluster in ${dataDir} on port ${selectedPort}`,
-      );
+        recentLogs: logBuffer.getRecentLogs(),
+      });
     }
   }
   if (existsSync(postmasterPidFile)) {
@@ -171,7 +162,10 @@ async function ensureEmbeddedPostgresConnection(
   try {
     await instance.start();
   } catch (error) {
-    throw toError(error, `Failed to start embedded PostgreSQL on port ${selectedPort}`);
+    throw formatEmbeddedPostgresError(error, {
+      fallbackMessage: `Failed to start embedded PostgreSQL on port ${selectedPort}`,
+      recentLogs: logBuffer.getRecentLogs(),
+    });
   }
 
   const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${selectedPort}/postgres`;

packages/db/src/migrations/0045_workable_shockwave.sql

@@ -0,0 +1,17 @@
+CREATE TABLE "issue_inbox_archives" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"issue_id" uuid NOT NULL,
+	"user_id" text NOT NULL,
+	"archived_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DROP INDEX "board_api_keys_key_hash_idx";--> statement-breakpoint
+ALTER TABLE "issue_inbox_archives" ADD CONSTRAINT "issue_inbox_archives_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "issue_inbox_archives" ADD CONSTRAINT "issue_inbox_archives_issue_id_issues_id_fk" FOREIGN KEY ("issue_id") REFERENCES "public"."issues"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "issue_inbox_archives_company_issue_idx" ON "issue_inbox_archives" USING btree ("company_id","issue_id");--> statement-breakpoint
+CREATE INDEX "issue_inbox_archives_company_user_idx" ON "issue_inbox_archives" USING btree ("company_id","user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "issue_inbox_archives_company_issue_user_idx" ON "issue_inbox_archives" USING btree ("company_id","issue_id","user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "board_api_keys_key_hash_idx" ON "board_api_keys" USING btree ("key_hash");

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

@@ -316,6 +316,13 @@
       "when": 1774269579794,
       "tag": "0044_illegal_toad",
       "breakpoints": true
+    },
+    {
+      "idx": 45,
+      "version": "7",
+      "when": 1774530504348,
+      "tag": "0045_workable_shockwave",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/index.ts

@@ -31,6 +31,7 @@ export { labels } from "./labels.js";
 export { issueLabels } from "./issue_labels.js";
 export { issueApprovals } from "./issue_approvals.js";
 export { issueComments } from "./issue_comments.js";
+export { issueInboxArchives } from "./issue_inbox_archives.js";
 export { issueReadStates } from "./issue_read_states.js";
 export { assets } from "./assets.js";
 export { issueAttachments } from "./issue_attachments.js";

packages/db/src/schema/issue_inbox_archives.ts

@@ -0,0 +1,25 @@
+import { pgTable, uuid, text, timestamp, index, uniqueIndex } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { issues } from "./issues.js";
+
+export const issueInboxArchives = pgTable(
+  "issue_inbox_archives",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id),
+    issueId: uuid("issue_id").notNull().references(() => issues.id),
+    userId: text("user_id").notNull(),
+    archivedAt: timestamp("archived_at", { withTimezone: true }).notNull().defaultNow(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyIssueIdx: index("issue_inbox_archives_company_issue_idx").on(table.companyId, table.issueId),
+    companyUserIdx: index("issue_inbox_archives_company_user_idx").on(table.companyId, table.userId),
+    companyIssueUserUnique: uniqueIndex("issue_inbox_archives_company_issue_user_idx").on(
+      table.companyId,
+      table.issueId,
+      table.userId,
+    ),
+  }),
+);

packages/db/src/test-embedded-postgres.ts

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { applyPendingMigrations, ensurePostgresDatabase } from "./client.js";
+
+type EmbeddedPostgresInstance = {
+  initialise(): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+};
+
+type EmbeddedPostgresCtor = new (opts: {
+  databaseDir: string;
+  user: string;
+  password: string;
+  port: number;
+  persistent: boolean;
+  initdbFlags?: string[];
+  onLog?: (message: unknown) => void;
+  onError?: (message: unknown) => void;
+}) => EmbeddedPostgresInstance;
+
+export type EmbeddedPostgresTestSupport = {
+  supported: boolean;
+  reason?: string;
+};
+
+export type EmbeddedPostgresTestDatabase = {
+  connectionString: string;
+  cleanup(): Promise<void>;
+};
+
+let embeddedPostgresSupportPromise: Promise<EmbeddedPostgresTestSupport> | null = null;
+
+async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
+  const mod = await import("embedded-postgres");
+  return mod.default as EmbeddedPostgresCtor;
+}
+
+async function getAvailablePort(): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Failed to allocate test port")));
+        return;
+      }
+      const { port } = address;
+      server.close((error) => {
+        if (error) reject(error);
+        else resolve(port);
+      });
+    });
+  });
+}
+
+function formatEmbeddedPostgresError(error: unknown): string {
+  if (error instanceof Error && error.message.length > 0) return error.message;
+  if (typeof error === "string" && error.length > 0) return error;
+  return "embedded Postgres startup failed";
+}
+
+async function probeEmbeddedPostgresSupport(): Promise<EmbeddedPostgresTestSupport> {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-embedded-postgres-probe-"));
+  const port = await getAvailablePort();
+  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
+  const instance = new EmbeddedPostgres({
+    databaseDir: dataDir,
+    user: "paperclip",
+    password: "paperclip",
+    port,
+    persistent: true,
+    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
+    onLog: () => {},
+    onError: () => {},
+  });
+
+  try {
+    await instance.initialise();
+    await instance.start();
+    return { supported: true };
+  } catch (error) {
+    return {
+      supported: false,
+      reason: formatEmbeddedPostgresError(error),
+    };
+  } finally {
+    await instance.stop().catch(() => {});
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+}
+
+export async function getEmbeddedPostgresTestSupport(): Promise<EmbeddedPostgresTestSupport> {
+  if (!embeddedPostgresSupportPromise) {
+    embeddedPostgresSupportPromise = probeEmbeddedPostgresSupport();
+  }
+  return await embeddedPostgresSupportPromise;
+}
+
+export async function startEmbeddedPostgresTestDatabase(
+  tempDirPrefix: string,
+): Promise<EmbeddedPostgresTestDatabase> {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), tempDirPrefix));
+  const port = await getAvailablePort();
+  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
+  const instance = new EmbeddedPostgres({
+    databaseDir: dataDir,
+    user: "paperclip",
+    password: "paperclip",
+    port,
+    persistent: true,
+    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
+    onLog: () => {},
+    onError: () => {},
+  });
+
+  try {
+    await instance.initialise();
+    await instance.start();
+
+    const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
+    await ensurePostgresDatabase(adminConnectionString, "paperclip");
+    const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
+    await applyPendingMigrations(connectionString);
+
+    return {
+      connectionString,
+      cleanup: async () => {
+        await instance.stop().catch(() => {});
+        fs.rmSync(dataDir, { recursive: true, force: true });
+      },
+    };
+  } catch (error) {
+    await instance.stop().catch(() => {});
+    fs.rmSync(dataDir, { recursive: true, force: true });
+    throw new Error(
+      `Failed to start embedded PostgreSQL test database: ${formatEmbeddedPostgresError(error)}`,
+    );
+  }
+}

packages/shared/src/constants.ts

@@ -50,7 +50,7 @@ export const AGENT_ROLES = [
 export type AgentRole = (typeof AGENT_ROLES)[number];
 
 export const AGENT_ROLE_LABELS: Record<AgentRole, string> = {
-  ceo: "CEO",
+  ceo: "Project Manager",  // [nexus] was: "CEO"
   cto: "CTO",
   cmo: "CMO",
   cfo: "CFO",

pnpm-lock.yaml

@@ -58,6 +58,9 @@ importers:
       '@paperclipai/adapter-utils':
         specifier: workspace:*
         version: link:../packages/adapter-utils
+      '@paperclipai/branding':
+        specifier: workspace:*
+        version: link:../packages/branding
       '@paperclipai/db':
         specifier: workspace:*
         version: link:../packages/db
@@ -220,6 +223,12 @@ importers:
         specifier: ^5.7.3
         version: 5.9.3
 
+  packages/branding:
+    devDependencies:
+      typescript:
+        specifier: ^5.7.3
+        version: 5.9.3
+
   packages/db:
     dependencies:
       '@paperclipai/shared':
@@ -618,6 +627,9 @@ importers:
       '@paperclipai/adapter-utils':
         specifier: workspace:*
         version: link:../packages/adapter-utils
+      '@paperclipai/branding':
+        specifier: workspace:*
+        version: link:../packages/branding
       '@paperclipai/shared':
         specifier: workspace:*
         version: link:../packages/shared

scripts/generate-ui-package-json.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, "..");
+const uiDir = join(repoRoot, "ui");
+const packageJsonPath = join(uiDir, "package.json");
+
+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+
+const publishPackageJson = {
+  name: packageJson.name,
+  version: packageJson.version,
+  description: packageJson.description,
+  license: packageJson.license,
+  homepage: packageJson.homepage,
+  bugs: packageJson.bugs,
+  repository: packageJson.repository,
+  type: packageJson.type,
+  files: ["dist"],
+  publishConfig: {
+    access: "public",
+  },
+};
+
+writeFileSync(packageJsonPath, `${JSON.stringify(publishPackageJson, null, 2)}\n`);
+
+console.log("  ✓ Generated publishable UI package.json");

scripts/install-hooks.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Install Nexus git hooks
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cp "$REPO_ROOT/scripts/nexus-commit-msg-hook.sh" "$REPO_ROOT/.git/hooks/commit-msg"
+chmod +x "$REPO_ROOT/.git/hooks/commit-msg"
+echo "Nexus commit-msg hook installed."

scripts/nexus-commit-msg-hook.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+# Nexus fork: enforce [nexus] prefix on all fork commits
+# Allows upstream merge commits and rebase-generated commits through
+MSG_FILE="$1"
+FIRST_LINE=$(head -1 "$MSG_FILE")
+
+# Skip merge commits (git generates these automatically during rebase/merge)
+if echo "$FIRST_LINE" | grep -qE "^Merge (branch|pull request|remote-tracking)"; then
+  exit 0
+fi
+
+# Skip fixup/squash commits (used during interactive rebase)
+if echo "$FIRST_LINE" | grep -qE "^(fixup|squash)!"; then
+  exit 0
+fi
+
+# Enforce [nexus] prefix
+if ! echo "$FIRST_LINE" | grep -qE "^\[nexus\]"; then
+  echo "ERROR: Commit message must start with [nexus]"
+  echo "  Got: $FIRST_LINE"
+  echo "  Example: [nexus] feat: add branding package"
+  exit 1
+fi

scripts/provision-worktree.sh

@@ -3,6 +3,12 @@ set -euo pipefail
 
 base_cwd="${PAPERCLIP_WORKSPACE_BASE_CWD:?PAPERCLIP_WORKSPACE_BASE_CWD is required}"
 worktree_cwd="${PAPERCLIP_WORKSPACE_CWD:?PAPERCLIP_WORKSPACE_CWD is required}"
+paperclip_home="${PAPERCLIP_HOME:-$HOME/.paperclip}"
+paperclip_instance_id="${PAPERCLIP_INSTANCE_ID:-default}"
+paperclip_dir="$worktree_cwd/.paperclip"
+worktree_config_path="$paperclip_dir/config.json"
+worktree_env_path="$paperclip_dir/.env"
+worktree_name="${PAPERCLIP_WORKSPACE_BRANCH:-$(basename "$worktree_cwd")}"
 
 if [[ ! -d "$base_cwd" ]]; then
   echo "Base workspace does not exist: $base_cwd" >&2
@@ -14,6 +20,286 @@ if [[ ! -d "$worktree_cwd" ]]; then
   exit 1
 fi
 
+source_config_path="${PAPERCLIP_CONFIG:-}"
+if [[ -z "$source_config_path" && ( -e "$base_cwd/.paperclip/config.json" || -L "$base_cwd/.paperclip/config.json" ) ]]; then
+  source_config_path="$base_cwd/.paperclip/config.json"
+fi
+if [[ -z "$source_config_path" ]]; then
+  source_config_path="$paperclip_home/instances/$paperclip_instance_id/config.json"
+fi
+source_env_path="$(dirname "$source_config_path")/.env"
+
+mkdir -p "$paperclip_dir"
+
+run_isolated_worktree_init() {
+  if command -v pnpm >/dev/null 2>&1 && pnpm paperclipai --help >/dev/null 2>&1; then
+    pnpm paperclipai worktree init --force --seed-mode minimal --name "$worktree_name" --from-config "$source_config_path"
+    return 0
+  fi
+
+  if command -v paperclipai >/dev/null 2>&1; then
+    paperclipai worktree init --force --seed-mode minimal --name "$worktree_name" --from-config "$source_config_path"
+    return 0
+  fi
+
+  return 1
+}
+
+write_fallback_worktree_config() {
+  WORKTREE_NAME="$worktree_name" \
+  BASE_CWD="$base_cwd" \
+  WORKTREE_CWD="$worktree_cwd" \
+  PAPERCLIP_DIR="$paperclip_dir" \
+  SOURCE_CONFIG_PATH="$source_config_path" \
+  SOURCE_ENV_PATH="$source_env_path" \
+  PAPERCLIP_WORKTREES_DIR="${PAPERCLIP_WORKTREES_DIR:-}" \
+  node <<'EOF'
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const net = require("node:net");
+
+function expandHomePrefix(value) {
+  if (!value) return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
+  return value;
+}
+
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function sanitizeInstanceId(value) {
+  const trimmed = String(value ?? "").trim().toLowerCase();
+  const normalized = trimmed
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-_]+|[-_]+$/g, "");
+  return normalized || "worktree";
+}
+
+function parseEnvFile(contents) {
+  const entries = {};
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+    if (!match) continue;
+    const [, key, rawValue] = match;
+    const value = rawValue.trim();
+    if (!value) {
+      entries[key] = "";
+      continue;
+    }
+    if (
+      (value.startsWith("\"") && value.endsWith("\"")) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      entries[key] = value.slice(1, -1);
+      continue;
+    }
+    entries[key] = value.replace(/\s+#.*$/, "").trim();
+  }
+  return entries;
+}
+
+async function findAvailablePort(preferredPort, reserved = new Set()) {
+  const startPort = Number.isFinite(preferredPort) && preferredPort > 0 ? Math.trunc(preferredPort) : 0;
+  if (startPort > 0) {
+    for (let port = startPort; port < startPort + 100; port += 1) {
+      if (reserved.has(port)) continue;
+      const available = await new Promise((resolve) => {
+        const server = net.createServer();
+        server.unref();
+        server.once("error", () => resolve(false));
+        server.listen(port, "127.0.0.1", () => {
+          server.close(() => resolve(true));
+        });
+      });
+      if (available) return port;
+    }
+  }
+
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Failed to allocate a port.")));
+        return;
+      }
+      const port = address.port;
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+function isLoopbackHost(hostname) {
+  const value = hostname.trim().toLowerCase();
+  return value === "127.0.0.1" || value === "localhost" || value === "::1";
+}
+
+function rewriteLocalUrlPort(rawUrl, port) {
+  if (!rawUrl) return undefined;
+  try {
+    const parsed = new URL(rawUrl);
+    if (!isLoopbackHost(parsed.hostname)) return rawUrl;
+    parsed.port = String(port);
+    return parsed.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
+function resolveRuntimeLikePath(value, configPath) {
+  const expanded = expandHomePrefix(value);
+  if (path.isAbsolute(expanded)) return expanded;
+  return path.resolve(path.dirname(configPath), expanded);
+}
+
+async function main() {
+  const worktreeName = process.env.WORKTREE_NAME;
+  const paperclipDir = process.env.PAPERCLIP_DIR;
+  const sourceConfigPath = process.env.SOURCE_CONFIG_PATH;
+  const sourceEnvPath = process.env.SOURCE_ENV_PATH;
+  const worktreeHome = path.resolve(expandHomePrefix(nonEmpty(process.env.PAPERCLIP_WORKTREES_DIR) ?? "~/.paperclip-worktrees"));
+  const instanceId = sanitizeInstanceId(worktreeName);
+  const instanceRoot = path.resolve(worktreeHome, "instances", instanceId);
+  const configPath = path.resolve(paperclipDir, "config.json");
+  const envPath = path.resolve(paperclipDir, ".env");
+
+  let sourceConfig = null;
+  if (sourceConfigPath && fs.existsSync(sourceConfigPath)) {
+    sourceConfig = JSON.parse(fs.readFileSync(sourceConfigPath, "utf8"));
+  }
+
+  const sourceEnvEntries =
+    sourceEnvPath && fs.existsSync(sourceEnvPath)
+      ? parseEnvFile(fs.readFileSync(sourceEnvPath, "utf8"))
+      : {};
+
+  const preferredServerPort = Number(sourceConfig?.server?.port ?? 3101) + 1;
+  const serverPort = await findAvailablePort(preferredServerPort);
+  const preferredDbPort = Number(sourceConfig?.database?.embeddedPostgresPort ?? 54329) + 1;
+  const databasePort = await findAvailablePort(preferredDbPort, new Set([serverPort]));
+
+  fs.rmSync(configPath, { force: true });
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.mkdirSync(instanceRoot, { recursive: true });
+
+  const authPublicBaseUrl = rewriteLocalUrlPort(sourceConfig?.auth?.publicBaseUrl, serverPort);
+  const targetConfig = {
+    $meta: {
+      version: 1,
+      updatedAt: new Date().toISOString(),
+      source: "configure",
+    },
+    ...(sourceConfig?.llm ? { llm: sourceConfig.llm } : {}),
+    database: {
+      mode: "embedded-postgres",
+      embeddedPostgresDataDir: path.resolve(instanceRoot, "db"),
+      embeddedPostgresPort: databasePort,
+      backup: {
+        enabled: sourceConfig?.database?.backup?.enabled ?? true,
+        intervalMinutes: sourceConfig?.database?.backup?.intervalMinutes ?? 60,
+        retentionDays: sourceConfig?.database?.backup?.retentionDays ?? 30,
+        dir: path.resolve(instanceRoot, "data", "backups"),
+      },
+    },
+    logging: {
+      mode: sourceConfig?.logging?.mode ?? "file",
+      logDir: path.resolve(instanceRoot, "logs"),
+    },
+    server: {
+      deploymentMode: sourceConfig?.server?.deploymentMode ?? "local_trusted",
+      exposure: sourceConfig?.server?.exposure ?? "private",
+      host: sourceConfig?.server?.host ?? "127.0.0.1",
+      port: serverPort,
+      allowedHostnames: sourceConfig?.server?.allowedHostnames ?? [],
+      serveUi: sourceConfig?.server?.serveUi ?? true,
+    },
+    auth: {
+      baseUrlMode: sourceConfig?.auth?.baseUrlMode ?? "auto",
+      ...(authPublicBaseUrl ? { publicBaseUrl: authPublicBaseUrl } : {}),
+      disableSignUp: sourceConfig?.auth?.disableSignUp ?? false,
+    },
+    storage: {
+      provider: sourceConfig?.storage?.provider ?? "local_disk",
+      localDisk: {
+        baseDir: path.resolve(instanceRoot, "data", "storage"),
+      },
+      s3: {
+        bucket: sourceConfig?.storage?.s3?.bucket ?? "paperclip",
+        region: sourceConfig?.storage?.s3?.region ?? "us-east-1",
+        endpoint: sourceConfig?.storage?.s3?.endpoint,
+        prefix: sourceConfig?.storage?.s3?.prefix ?? "",
+        forcePathStyle: sourceConfig?.storage?.s3?.forcePathStyle ?? false,
+      },
+    },
+    secrets: {
+      provider: sourceConfig?.secrets?.provider ?? "local_encrypted",
+      strictMode: sourceConfig?.secrets?.strictMode ?? false,
+      localEncrypted: {
+        keyFilePath: path.resolve(instanceRoot, "secrets", "master.key"),
+      },
+    },
+  };
+
+  fs.writeFileSync(configPath, `${JSON.stringify(targetConfig, null, 2)}\n`, { mode: 0o600 });
+
+  const inlineMasterKey = nonEmpty(sourceEnvEntries.PAPERCLIP_SECRETS_MASTER_KEY);
+  if (inlineMasterKey) {
+    fs.mkdirSync(path.resolve(instanceRoot, "secrets"), { recursive: true });
+    fs.writeFileSync(targetConfig.secrets.localEncrypted.keyFilePath, inlineMasterKey, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+  } else {
+    const sourceKeyFilePath = nonEmpty(sourceEnvEntries.PAPERCLIP_SECRETS_MASTER_KEY_FILE)
+      ? resolveRuntimeLikePath(sourceEnvEntries.PAPERCLIP_SECRETS_MASTER_KEY_FILE, sourceConfigPath)
+      : nonEmpty(sourceConfig?.secrets?.localEncrypted?.keyFilePath)
+        ? resolveRuntimeLikePath(sourceConfig.secrets.localEncrypted.keyFilePath, sourceConfigPath)
+        : null;
+
+    if (sourceKeyFilePath && fs.existsSync(sourceKeyFilePath)) {
+      fs.mkdirSync(path.resolve(instanceRoot, "secrets"), { recursive: true });
+      fs.copyFileSync(sourceKeyFilePath, targetConfig.secrets.localEncrypted.keyFilePath);
+      fs.chmodSync(targetConfig.secrets.localEncrypted.keyFilePath, 0o600);
+    }
+  }
+
+  const envLines = [
+    "PAPERCLIP_HOME=" + JSON.stringify(worktreeHome),
+    "PAPERCLIP_INSTANCE_ID=" + JSON.stringify(instanceId),
+    "PAPERCLIP_CONFIG=" + JSON.stringify(configPath),
+    "PAPERCLIP_CONTEXT=" + JSON.stringify(path.resolve(worktreeHome, "context.json")),
+    "PAPERCLIP_IN_WORKTREE=true",
+    "PAPERCLIP_WORKTREE_NAME=" + JSON.stringify(worktreeName),
+  ];
+
+  const agentJwtSecret = nonEmpty(sourceEnvEntries.PAPERCLIP_AGENT_JWT_SECRET);
+  if (agentJwtSecret) {
+    envLines.push("PAPERCLIP_AGENT_JWT_SECRET=" + JSON.stringify(agentJwtSecret));
+  }
+
+  fs.writeFileSync(envPath, `${envLines.join("\n")}\n`, { mode: 0o600 });
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});
+EOF
+}
+
+if ! run_isolated_worktree_init; then
+  echo "paperclipai CLI not available in this workspace; writing isolated fallback config without DB seeding." >&2
+  write_fallback_worktree_config
+fi
+
 while IFS= read -r relative_path; do
   [[ -n "$relative_path" ]] || continue
   source_path="$base_cwd/$relative_path"

server/package.json

@@ -33,7 +33,7 @@
   ],
   "scripts": {
     "dev": "tsx src/index.ts",
-    "dev:watch": "cross-env PAPERCLIP_MIGRATION_PROMPT=never PAPERCLIP_MIGRATION_AUTO_APPLY=true tsx watch --ignore ../ui/node_modules --ignore ../ui/.vite --ignore ../ui/dist src/index.ts",
+    "dev:watch": "cross-env PAPERCLIP_MIGRATION_PROMPT=never PAPERCLIP_MIGRATION_AUTO_APPLY=true tsx ./scripts/dev-watch.ts",
     "prepare:ui-dist": "bash ../scripts/prepare-server-ui-dist.sh",
     "build": "tsc && mkdir -p dist/onboarding-assets && cp -R src/onboarding-assets/. dist/onboarding-assets/",
     "prepack": "pnpm run prepare:ui-dist",

server/scripts/dev-watch.ts

@@ -0,0 +1,33 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveServerDevWatchIgnorePaths } from "../src/dev-watch-ignore.ts";
+
+const require = createRequire(import.meta.url);
+const tsxCliPath = require.resolve("tsx/dist/cli.mjs");
+const serverRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const ignoreArgs = resolveServerDevWatchIgnorePaths(serverRoot).flatMap((ignorePath) => ["--exclude", ignorePath]);
+
+const child = spawn(
+  process.execPath,
+  [tsxCliPath, "watch", ...ignoreArgs, "src/index.ts"],
+  {
+    cwd: serverRoot,
+    env: process.env,
+    stdio: "inherit",
+  },
+);
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});
+
+child.on("error", (error) => {
+  console.error(error);
+  process.exit(1);
+});

server/src/__tests__/dev-watch-ignore.test.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveServerDevWatchIgnorePaths } from "../dev-watch-ignore.js";
+
+describe("resolveServerDevWatchIgnorePaths", () => {
+  it("includes both the worktree UI paths and their real shared targets", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-dev-watch-"));
+    const sharedUiRoot = path.join(tempRoot, "shared-ui");
+    const worktreeRoot = path.join(tempRoot, "repo", ".paperclip", "worktrees", "PAP-884");
+    const serverRoot = path.join(worktreeRoot, "server");
+    const worktreeUiRoot = path.join(worktreeRoot, "ui");
+
+    fs.mkdirSync(path.join(sharedUiRoot, "node_modules"), { recursive: true });
+    fs.mkdirSync(path.join(sharedUiRoot, ".vite"), { recursive: true });
+    fs.mkdirSync(path.join(sharedUiRoot, "dist"), { recursive: true });
+    fs.mkdirSync(serverRoot, { recursive: true });
+    fs.mkdirSync(worktreeUiRoot, { recursive: true });
+
+    fs.symlinkSync(path.join(sharedUiRoot, "node_modules"), path.join(worktreeUiRoot, "node_modules"));
+    fs.symlinkSync(path.join(sharedUiRoot, ".vite"), path.join(worktreeUiRoot, ".vite"));
+    fs.symlinkSync(path.join(sharedUiRoot, "dist"), path.join(worktreeUiRoot, "dist"));
+
+    const ignorePaths = resolveServerDevWatchIgnorePaths(serverRoot);
+
+    expect(ignorePaths).toContain(path.join(worktreeUiRoot, "node_modules"));
+    expect(ignorePaths).toContain(`${path.join(worktreeUiRoot, "node_modules").replaceAll(path.sep, "/")}/**`);
+    expect(ignorePaths).toContain(fs.realpathSync(path.join(sharedUiRoot, "node_modules")));
+    expect(ignorePaths).toContain(`${fs.realpathSync(path.join(sharedUiRoot, "node_modules")).replaceAll(path.sep, "/")}/**`);
+    expect(ignorePaths).toContain(path.join(worktreeUiRoot, "node_modules", ".vite-temp"));
+    expect(ignorePaths).toContain(
+      `${path.join(worktreeUiRoot, "node_modules", ".vite-temp").replaceAll(path.sep, "/")}/**`,
+    );
+    expect(ignorePaths).toContain(path.join(worktreeUiRoot, ".vite"));
+    expect(ignorePaths).toContain(fs.realpathSync(path.join(sharedUiRoot, ".vite")));
+    expect(ignorePaths).toContain(path.join(worktreeUiRoot, "dist"));
+    expect(ignorePaths).toContain(fs.realpathSync(path.join(sharedUiRoot, "dist")));
+    expect(ignorePaths).toContain("**/{node_modules,bower_components,vendor}/**");
+    expect(ignorePaths).toContain("**/.vite-temp/**");
+  });
+});

server/src/__tests__/heartbeat-process-recovery.test.ts

@@ -1,89 +1,29 @@
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { spawn, type ChildProcess } from "node:child_process";
 import { eq } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import {
-  applyPendingMigrations,
-  createDb,
-  ensurePostgresDatabase,
   agents,
   agentWakeupRequests,
   companies,
+  createDb,
   heartbeatRunEvents,
   heartbeatRuns,
   issues,
 } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 import { runningProcesses } from "../adapters/index.ts";
 import { heartbeatService } from "../services/heartbeat.ts";
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
 
-type EmbeddedPostgresInstance = {
+if (!embeddedPostgresSupport.supported) {
-  initialise(): Promise<void>;
+  console.warn(
-  start(): Promise<void>;
+    `Skipping embedded Postgres heartbeat recovery tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
-  stop(): Promise<void>;
+  );
-};
-
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
-}
-
-async function getAvailablePort(): Promise<number> {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-heartbeat-recovery-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, instance, dataDir };
 }
 
 function spawnAliveProcess() {
@@ -92,17 +32,14 @@ function spawnAliveProcess() {
   });
 }
 
-describe("heartbeat orphaned process recovery", () => {
+describeEmbeddedPostgres("heartbeat orphaned process recovery", () => {
   let db!: ReturnType<typeof createDb>;
-  let instance: EmbeddedPostgresInstance | null = null;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
-  let dataDir = "";
   const childProcesses = new Set<ChildProcess>();
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-heartbeat-recovery-");
-    db = createDb(started.connectionString);
+    db = createDb(tempDb.connectionString);
-    instance = started.instance;
-    dataDir = started.dataDir;
   }, 20_000);
 
   afterEach(async () => {
@@ -125,10 +62,7 @@ describe("heartbeat orphaned process recovery", () => {
     }
     childProcesses.clear();
     runningProcesses.clear();
-    await instance?.stop();
+    await tempDb?.cleanup();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
   });
 
   async function seedRunFixture(input?: {

server/src/__tests__/heartbeat-workspace-session.test.ts

@@ -55,7 +55,7 @@ function buildAgent(adapterType: string, runtimeConfig: Record<string, unknown>
 describe("resolveRuntimeSessionParamsForWorkspace", () => {
   it("migrates fallback workspace sessions to project workspace when project cwd becomes available", () => {
     const agentId = "agent-123";
-    const fallbackCwd = resolveDefaultAgentWorkspaceDir(agentId);
+    const fallbackCwd = resolveDefaultAgentWorkspaceDir({ id: agentId });
 
     const result = resolveRuntimeSessionParamsForWorkspace({
       agentId,
@@ -96,7 +96,7 @@ describe("resolveRuntimeSessionParamsForWorkspace", () => {
 
   it("does not migrate when resolved workspace id differs from previous session workspace id", () => {
     const agentId = "agent-123";
-    const fallbackCwd = resolveDefaultAgentWorkspaceDir(agentId);
+    const fallbackCwd = resolveDefaultAgentWorkspaceDir({ id: agentId });
 
     const result = resolveRuntimeSessionParamsForWorkspace({
       agentId,

server/src/__tests__/helpers/embedded-postgres.ts

@@ -0,0 +1,6 @@
+export {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestDatabase,
+  type EmbeddedPostgresTestSupport,
+} from "@paperclipai/db";

server/src/__tests__/issues-service.test.ts

@@ -1,103 +1,43 @@
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import {
   activityLog,
   agents,
-  applyPendingMigrations,
   companies,
   createDb,
-  ensurePostgresDatabase,
   issueComments,
+  issueInboxArchives,
   issues,
 } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 import { issueService } from "../services/issues.ts";
 
-type EmbeddedPostgresInstance = {
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
-  initialise(): Promise<void>;
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
 
-type EmbeddedPostgresCtor = new (opts: {
+if (!embeddedPostgresSupport.supported) {
-  databaseDir: string;
+  console.warn(
-  user: string;
+    `Skipping embedded Postgres issue service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
-  password: string;
+  );
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
 }
 
-async function getAvailablePort(): Promise<number> {
+describeEmbeddedPostgres("issueService.list participantAgentId", () => {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-issues-service-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, dataDir, instance };
-}
-
-describe("issueService.list participantAgentId", () => {
   let db!: ReturnType<typeof createDb>;
   let svc!: ReturnType<typeof issueService>;
-  let instance: EmbeddedPostgresInstance | null = null;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
-  let dataDir = "";
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-issues-service-");
-    db = createDb(started.connectionString);
+    db = createDb(tempDb.connectionString);
     svc = issueService(db);
-    instance = started.instance;
-    dataDir = started.dataDir;
   }, 20_000);
 
   afterEach(async () => {
     await db.delete(issueComments);
+    await db.delete(issueInboxArchives);
     await db.delete(activityLog);
     await db.delete(issues);
     await db.delete(agents);
@@ -105,10 +45,7 @@ describe("issueService.list participantAgentId", () => {
   });
 
   afterAll(async () => {
-    await instance?.stop();
+    await tempDb?.cleanup();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
   });
 
   it("returns issues an agent participated in across the supported signals", async () => {
@@ -281,4 +218,99 @@ describe("issueService.list participantAgentId", () => {
 
     expect(result.map((issue) => issue.id)).toEqual([matchedIssueId]);
   });
+
+  it("hides archived inbox issues until new external activity arrives", async () => {
+    const companyId = randomUUID();
+    const userId = "user-1";
+    const otherUserId = "user-2";
+
+    await db.insert(companies).values({
+      id: companyId,
+      name: "Paperclip",
+      issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+      requireBoardApprovalForNewAgents: false,
+    });
+
+    const visibleIssueId = randomUUID();
+    const archivedIssueId = randomUUID();
+    const resurfacedIssueId = randomUUID();
+
+    await db.insert(issues).values([
+      {
+        id: visibleIssueId,
+        companyId,
+        title: "Visible issue",
+        status: "todo",
+        priority: "medium",
+        createdByUserId: userId,
+        createdAt: new Date("2026-03-26T10:00:00.000Z"),
+        updatedAt: new Date("2026-03-26T10:00:00.000Z"),
+      },
+      {
+        id: archivedIssueId,
+        companyId,
+        title: "Archived issue",
+        status: "todo",
+        priority: "medium",
+        createdByUserId: userId,
+        createdAt: new Date("2026-03-26T11:00:00.000Z"),
+        updatedAt: new Date("2026-03-26T11:00:00.000Z"),
+      },
+      {
+        id: resurfacedIssueId,
+        companyId,
+        title: "Resurfaced issue",
+        status: "todo",
+        priority: "medium",
+        createdByUserId: userId,
+        createdAt: new Date("2026-03-26T12:00:00.000Z"),
+        updatedAt: new Date("2026-03-26T12:00:00.000Z"),
+      },
+    ]);
+
+    await svc.archiveInbox(
+      companyId,
+      archivedIssueId,
+      userId,
+      new Date("2026-03-26T12:30:00.000Z"),
+    );
+    await svc.archiveInbox(
+      companyId,
+      resurfacedIssueId,
+      userId,
+      new Date("2026-03-26T13:00:00.000Z"),
+    );
+
+    await db.insert(issueComments).values({
+      companyId,
+      issueId: resurfacedIssueId,
+      authorUserId: otherUserId,
+      body: "This should bring the issue back into Mine.",
+      createdAt: new Date("2026-03-26T13:30:00.000Z"),
+      updatedAt: new Date("2026-03-26T13:30:00.000Z"),
+    });
+
+    const archivedFiltered = await svc.list(companyId, {
+      touchedByUserId: userId,
+      inboxArchivedByUserId: userId,
+    });
+
+    expect(archivedFiltered.map((issue) => issue.id)).toEqual([
+      resurfacedIssueId,
+      visibleIssueId,
+    ]);
+
+    await svc.unarchiveInbox(companyId, archivedIssueId, userId);
+
+    const afterUnarchive = await svc.list(companyId, {
+      touchedByUserId: userId,
+      inboxArchivedByUserId: userId,
+    });
+
+    expect(new Set(afterUnarchive.map((issue) => issue.id))).toEqual(new Set([
+      visibleIssueId,
+      archivedIssueId,
+      resurfacedIssueId,
+    ]));
+  });
 });

server/src/__tests__/routines-e2e.test.ts

@@ -1,8 +1,4 @@
 import { randomUUID } from "node:crypto";
-import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { eq } from "drizzle-orm";
 import express from "express";
 import request from "supertest";
@@ -11,11 +7,9 @@ import {
   activityLog,
   agentWakeupRequests,
   agents,
-  applyPendingMigrations,
   companies,
   companyMemberships,
   createDb,
-  ensurePostgresDatabase,
   heartbeatRunEvents,
   heartbeatRuns,
   instanceSettings,
@@ -26,6 +20,10 @@ import {
   routines,
   routineTriggers,
 } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 import { errorHandler } from "../middleware/index.js";
 import { accessService } from "../services/access.js";
 
@@ -78,82 +76,22 @@ vi.mock("../services/index.js", async () => {
   };
 });
 
-type EmbeddedPostgresInstance = {
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
-  initialise(): Promise<void>;
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
 
-type EmbeddedPostgresCtor = new (opts: {
+if (!embeddedPostgresSupport.supported) {
-  databaseDir: string;
+  console.warn(
-  user: string;
+    `Skipping embedded Postgres routine route tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
-  password: string;
+  );
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
 }
 
-async function getAvailablePort(): Promise<number> {
+describeEmbeddedPostgres("routine routes end-to-end", () => {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-routines-e2e-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, dataDir, instance };
-}
-
-describe("routine routes end-to-end", () => {
   let db!: ReturnType<typeof createDb>;
-  let instance: EmbeddedPostgresInstance | null = null;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
-  let dataDir = "";
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-routines-e2e-");
-    db = createDb(started.connectionString);
+    db = createDb(tempDb.connectionString);
-    instance = started.instance;
-    dataDir = started.dataDir;
   }, 20_000);
 
   afterEach(async () => {
@@ -174,10 +112,7 @@ describe("routine routes end-to-end", () => {
   });
 
   afterAll(async () => {
-    await instance?.stop();
+    await tempDb?.cleanup();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
   });
 
   async function createApp(actor: Record<string, unknown>) {

server/src/__tests__/routines-service.test.ts

@@ -1,19 +1,13 @@
 import { createHmac, randomUUID } from "node:crypto";
-import fs from "node:fs";
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
 import { eq } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import {
   activityLog,
   agents,
-  applyPendingMigrations,
   companies,
   companySecrets,
   companySecretVersions,
   createDb,
-  ensurePostgresDatabase,
   heartbeatRuns,
   issues,
   projects,
@@ -21,85 +15,29 @@ import {
   routines,
   routineTriggers,
 } from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
 import { issueService } from "../services/issues.ts";
 import { routineService } from "../services/routines.ts";
 
-type EmbeddedPostgresInstance = {
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
-  initialise(): Promise<void>;
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
 
-type EmbeddedPostgresCtor = new (opts: {
+if (!embeddedPostgresSupport.supported) {
-  databaseDir: string;
+  console.warn(
-  user: string;
+    `Skipping embedded Postgres routines service tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
-  password: string;
+  );
-  port: number;
-  persistent: boolean;
-  initdbFlags?: string[];
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const mod = await import("embedded-postgres");
-  return mod.default as EmbeddedPostgresCtor;
 }
 
-async function getAvailablePort(): Promise<number> {
+describeEmbeddedPostgres("routine service live-execution coalescing", () => {
-  return await new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.unref();
-    server.on("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Failed to allocate test port")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) reject(error);
-        else resolve(port);
-      });
-    });
-  });
-}
-
-async function startTempDatabase() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-routines-service-"));
-  const port = await getAvailablePort();
-  const EmbeddedPostgres = await getEmbeddedPostgresCtor();
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port,
-    persistent: true,
-    initdbFlags: ["--encoding=UTF8", "--locale=C", "--lc-messages=C"],
-    onLog: () => {},
-    onError: () => {},
-  });
-  await instance.initialise();
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-  const connectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
-  await applyPendingMigrations(connectionString);
-  return { connectionString, dataDir, instance };
-}
-
-describe("routine service live-execution coalescing", () => {
   let db!: ReturnType<typeof createDb>;
-  let instance: EmbeddedPostgresInstance | null = null;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
-  let dataDir = "";
 
   beforeAll(async () => {
-    const started = await startTempDatabase();
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-routines-service-");
-    db = createDb(started.connectionString);
+    db = createDb(tempDb.connectionString);
-    instance = started.instance;
-    dataDir = started.dataDir;
   }, 20_000);
 
   afterEach(async () => {
@@ -117,10 +55,7 @@ describe("routine service live-execution coalescing", () => {
   });
 
   afterAll(async () => {
-    await instance?.stop();
+    await tempDb?.cleanup();
-    if (dataDir) {
-      fs.rmSync(dataDir, { recursive: true, force: true });
-    }
   });
 
   async function seedFixture(opts?: {

server/src/__tests__/workspace-runtime.test.ts

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { afterEach, describe, expect, it } from "vitest";
 import {
@@ -13,6 +14,7 @@ import {
   stopRuntimeServicesForExecutionWorkspace,
   type RealizedExecutionWorkspace,
 } from "../services/workspace-runtime.ts";
+import { resolvePaperclipConfigPath } from "../paths.ts";
 import type { WorkspaceOperation } from "@paperclipai/shared";
 import type { WorkspaceOperationRecorder } from "../services/workspace-operations.ts";
 
@@ -124,6 +126,7 @@ afterEach(async () => {
   delete process.env.PAPERCLIP_CONFIG;
   delete process.env.PAPERCLIP_HOME;
   delete process.env.PAPERCLIP_INSTANCE_ID;
+  delete process.env.PAPERCLIP_WORKTREES_DIR;
   delete process.env.DATABASE_URL;
 });
 
@@ -282,6 +285,156 @@ describe("realizeExecutionWorkspace", () => {
     await expect(fs.readFile(path.join(reused.cwd, ".paperclip-provision-created"), "utf8")).resolves.toBe("false\n");
   });
 
+  it("writes an isolated repo-local Paperclip config and worktree branding when provisioning", async () => {
+    const repoRoot = await createTempRepo();
+    const previousCwd = process.cwd();
+    const paperclipHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-home-"));
+    const isolatedWorktreeHome = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktrees-"));
+    const instanceId = "worktree-base";
+    const sharedConfigDir = path.join(paperclipHome, "instances", instanceId);
+    const sharedConfigPath = path.join(sharedConfigDir, "config.json");
+    const sharedEnvPath = path.join(sharedConfigDir, ".env");
+
+    process.env.PAPERCLIP_HOME = paperclipHome;
+    process.env.PAPERCLIP_INSTANCE_ID = instanceId;
+    process.env.PAPERCLIP_WORKTREES_DIR = isolatedWorktreeHome;
+
+    await fs.mkdir(sharedConfigDir, { recursive: true });
+    await fs.writeFile(
+      sharedConfigPath,
+      JSON.stringify(
+        {
+          $meta: {
+            version: 1,
+            updatedAt: "2026-03-26T00:00:00.000Z",
+            source: "doctor",
+          },
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(sharedConfigDir, "db"),
+            embeddedPostgresPort: 54329,
+            backup: {
+              enabled: true,
+              intervalMinutes: 60,
+              retentionDays: 30,
+              dir: path.join(sharedConfigDir, "backups"),
+            },
+          },
+          logging: {
+            mode: "file",
+            logDir: path.join(sharedConfigDir, "logs"),
+          },
+          server: {
+            deploymentMode: "local_trusted",
+            exposure: "private",
+            host: "127.0.0.1",
+            port: 3100,
+            allowedHostnames: [],
+            serveUi: true,
+          },
+          auth: {
+            baseUrlMode: "auto",
+            disableSignUp: false,
+          },
+          storage: {
+            provider: "local_disk",
+            localDisk: {
+              baseDir: path.join(sharedConfigDir, "storage"),
+            },
+            s3: {
+              bucket: "paperclip",
+              region: "us-east-1",
+              prefix: "",
+              forcePathStyle: false,
+            },
+          },
+          secrets: {
+            provider: "local_encrypted",
+            strictMode: false,
+            localEncrypted: {
+              keyFilePath: path.join(sharedConfigDir, "master.key"),
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+    await fs.writeFile(sharedEnvPath, 'DATABASE_URL="postgres://worktree:test@db.example.com:6543/paperclip"\n', "utf8");
+
+    await fs.mkdir(path.join(repoRoot, "scripts"), { recursive: true });
+    await fs.copyFile(
+      fileURLToPath(new URL("../../../scripts/provision-worktree.sh", import.meta.url)),
+      path.join(repoRoot, "scripts", "provision-worktree.sh"),
+    );
+    await runGit(repoRoot, ["add", "scripts/provision-worktree.sh"]);
+    await runGit(repoRoot, ["commit", "-m", "Add worktree provision script"]);
+
+    try {
+      const workspace = await realizeExecutionWorkspace({
+        base: {
+          baseCwd: repoRoot,
+          source: "project_primary",
+          projectId: "project-1",
+          workspaceId: "workspace-1",
+          repoUrl: null,
+          repoRef: "HEAD",
+        },
+        config: {
+          workspaceStrategy: {
+            type: "git_worktree",
+            branchTemplate: "{{issue.identifier}}-{{slug}}",
+            provisionCommand: "bash ./scripts/provision-worktree.sh",
+          },
+        },
+        issue: {
+          id: "issue-1",
+          identifier: "PAP-885",
+          title: "Show worktree banner",
+        },
+        agent: {
+          id: "agent-1",
+          name: "Codex Coder",
+          companyId: "company-1",
+        },
+      });
+
+      const configPath = path.join(workspace.cwd, ".paperclip", "config.json");
+      const envPath = path.join(workspace.cwd, ".paperclip", ".env");
+      const envContents = await fs.readFile(envPath, "utf8");
+      const configContents = JSON.parse(await fs.readFile(configPath, "utf8"));
+      const configStats = await fs.lstat(configPath);
+      const expectedInstanceId = "pap-885-show-worktree-banner";
+      const expectedInstanceRoot = path.join(
+        isolatedWorktreeHome,
+        "instances",
+        expectedInstanceId,
+      );
+
+      expect(configStats.isSymbolicLink()).toBe(false);
+      expect(configContents.database.embeddedPostgresDataDir).toBe(path.join(expectedInstanceRoot, "db"));
+      expect(configContents.database.embeddedPostgresDataDir).not.toBe(path.join(sharedConfigDir, "db"));
+      expect(configContents.server.port).not.toBe(3100);
+      expect(configContents.secrets.localEncrypted.keyFilePath).toBe(
+        path.join(expectedInstanceRoot, "secrets", "master.key"),
+      );
+      expect(envContents).not.toContain("DATABASE_URL=");
+      expect(envContents).toContain(`PAPERCLIP_HOME=${JSON.stringify(isolatedWorktreeHome)}`);
+      expect(envContents).toContain(`PAPERCLIP_INSTANCE_ID=${JSON.stringify(expectedInstanceId)}`);
+      expect(envContents).toContain(`PAPERCLIP_CONFIG=${JSON.stringify(configPath)}`);
+      expect(envContents).toContain("PAPERCLIP_IN_WORKTREE=true");
+      expect(envContents).toContain(
+        `PAPERCLIP_WORKTREE_NAME=${JSON.stringify("PAP-885-show-worktree-banner")}`,
+      );
+
+      process.chdir(workspace.cwd);
+      expect(resolvePaperclipConfigPath()).toBe(configPath);
+    } finally {
+      process.chdir(previousCwd);
+    }
+  });
+
   it("records worktree setup and provision operations when a recorder is provided", async () => {
     const repoRoot = await createTempRepo();
     const { recorder, operations } = createWorkspaceOperationRecorderDouble();

server/src/__tests__/worktree-config.test.ts

@@ -0,0 +1,426 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  applyRuntimePortSelectionToConfig,
+  maybePersistWorktreeRuntimePorts,
+  maybeRepairLegacyWorktreeConfigAndEnvFiles,
+} from "../worktree-config.js";
+
+const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_CWD = process.cwd();
+
+afterEach(() => {
+  process.chdir(ORIGINAL_CWD);
+
+  for (const key of Object.keys(process.env)) {
+    if (!(key in ORIGINAL_ENV)) {
+      delete process.env[key];
+    }
+  }
+  for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
+    process.env[key] = value;
+  }
+});
+
+function buildLegacyConfig(sharedRoot: string) {
+  return {
+    $meta: {
+      version: 1,
+      updatedAt: "2026-03-26T00:00:00.000Z",
+      source: "configure",
+    },
+    database: {
+      mode: "embedded-postgres" as const,
+      embeddedPostgresDataDir: path.join(sharedRoot, "db"),
+      embeddedPostgresPort: 54329,
+      backup: {
+        enabled: true,
+        intervalMinutes: 60,
+        retentionDays: 30,
+        dir: path.join(sharedRoot, "data", "backups"),
+      },
+    },
+    logging: {
+      mode: "file" as const,
+      logDir: path.join(sharedRoot, "logs"),
+    },
+    server: {
+      deploymentMode: "local_trusted" as const,
+      exposure: "private" as const,
+      host: "127.0.0.1",
+      port: 3100,
+      allowedHostnames: [],
+      serveUi: true,
+    },
+    auth: {
+      baseUrlMode: "explicit" as const,
+      publicBaseUrl: "http://127.0.0.1:3100",
+      disableSignUp: false,
+    },
+    storage: {
+      provider: "local_disk" as const,
+      localDisk: {
+        baseDir: path.join(sharedRoot, "data", "storage"),
+      },
+      s3: {
+        bucket: "paperclip",
+        region: "us-east-1",
+        prefix: "",
+        forcePathStyle: false,
+      },
+    },
+    secrets: {
+      provider: "local_encrypted" as const,
+      strictMode: false,
+      localEncrypted: {
+        keyFilePath: path.join(sharedRoot, "secrets", "master.key"),
+      },
+    },
+  };
+}
+
+describe("worktree config repair", () => {
+  it("repairs legacy repo-local worktree config and env files into an isolated instance", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-repair-"));
+    const worktreeRoot = path.join(tempRoot, "PAP-884-ai-commits-component");
+    const paperclipDir = path.join(worktreeRoot, ".paperclip");
+    const configPath = path.join(paperclipDir, "config.json");
+    const envPath = path.join(paperclipDir, ".env");
+    const sharedRoot = path.join(tempRoot, ".paperclip", "instances", "default");
+    const isolatedHome = path.join(tempRoot, ".paperclip-worktrees");
+
+    await fs.mkdir(paperclipDir, { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(buildLegacyConfig(sharedRoot), null, 2) + "\n", "utf8");
+    await fs.writeFile(
+      envPath,
+      [
+        "# Paperclip environment variables",
+        "PAPERCLIP_IN_WORKTREE=true",
+        "PAPERCLIP_WORKTREE_NAME=PAP-884-ai-commits-component",
+        "PAPERCLIP_AGENT_JWT_SECRET=shared-secret",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+
+    process.chdir(worktreeRoot);
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.PAPERCLIP_WORKTREE_NAME = "PAP-884-ai-commits-component";
+    process.env.PAPERCLIP_WORKTREES_DIR = isolatedHome;
+    delete process.env.PAPERCLIP_HOME;
+    delete process.env.PAPERCLIP_INSTANCE_ID;
+    delete process.env.PAPERCLIP_CONFIG;
+    delete process.env.PAPERCLIP_CONTEXT;
+
+    const result = maybeRepairLegacyWorktreeConfigAndEnvFiles();
+
+    expect(result).toEqual({
+      repairedConfig: true,
+      repairedEnv: true,
+    });
+
+    const repairedConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+    const repairedEnv = await fs.readFile(envPath, "utf8");
+    const instanceRoot = path.join(isolatedHome, "instances", "pap-884-ai-commits-component");
+
+    expect(repairedConfig.database.embeddedPostgresDataDir).toBe(path.join(instanceRoot, "db"));
+    expect(repairedConfig.database.backup.dir).toBe(path.join(instanceRoot, "data", "backups"));
+    expect(repairedConfig.logging.logDir).toBe(path.join(instanceRoot, "logs"));
+    expect(repairedConfig.storage.localDisk.baseDir).toBe(path.join(instanceRoot, "data", "storage"));
+    expect(repairedConfig.secrets.localEncrypted.keyFilePath).toBe(path.join(instanceRoot, "secrets", "master.key"));
+    expect(repairedEnv).toContain(`PAPERCLIP_HOME=${JSON.stringify(isolatedHome)}`);
+    expect(repairedEnv).toContain('PAPERCLIP_INSTANCE_ID="pap-884-ai-commits-component"');
+    expect(repairedEnv).toContain(`PAPERCLIP_CONFIG=${JSON.stringify(await fs.realpath(configPath))}`);
+    expect(repairedEnv).toContain(`PAPERCLIP_CONTEXT=${JSON.stringify(path.join(isolatedHome, "context.json"))}`);
+    expect(repairedEnv).toContain('PAPERCLIP_AGENT_JWT_SECRET="shared-secret"');
+    expect(process.env.PAPERCLIP_HOME).toBe(isolatedHome);
+    expect(process.env.PAPERCLIP_INSTANCE_ID).toBe("pap-884-ai-commits-component");
+  });
+
+  it("avoids sibling worktree ports when repairing legacy configs", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-repair-ports-"));
+    const worktreeRoot = path.join(tempRoot, "PAP-880-thumbs-capture-for-evals-feature");
+    const paperclipDir = path.join(worktreeRoot, ".paperclip");
+    const configPath = path.join(paperclipDir, "config.json");
+    const envPath = path.join(paperclipDir, ".env");
+    const sharedRoot = path.join(tempRoot, ".paperclip", "instances", "default");
+    const isolatedHome = path.join(tempRoot, ".paperclip-worktrees");
+    const siblingInstanceRoot = path.join(isolatedHome, "instances", "pap-878-create-a-mine-tab-in-inbox");
+
+    await fs.mkdir(paperclipDir, { recursive: true });
+    await fs.mkdir(siblingInstanceRoot, { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(buildLegacyConfig(sharedRoot), null, 2) + "\n", "utf8");
+    await fs.writeFile(
+      envPath,
+      [
+        "# Paperclip environment variables",
+        "PAPERCLIP_IN_WORKTREE=true",
+        "PAPERCLIP_WORKTREE_NAME=PAP-880-thumbs-capture-for-evals-feature",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    await fs.writeFile(
+      path.join(siblingInstanceRoot, "config.json"),
+      JSON.stringify(
+        {
+          ...buildLegacyConfig(siblingInstanceRoot),
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(siblingInstanceRoot, "db"),
+            embeddedPostgresPort: 54330,
+            backup: {
+              enabled: true,
+              intervalMinutes: 60,
+              retentionDays: 30,
+              dir: path.join(siblingInstanceRoot, "data", "backups"),
+            },
+          },
+          server: {
+            deploymentMode: "local_trusted",
+            exposure: "private",
+            host: "127.0.0.1",
+            port: 3101,
+            allowedHostnames: [],
+            serveUi: true,
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+
+    process.chdir(worktreeRoot);
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.PAPERCLIP_WORKTREE_NAME = "PAP-880-thumbs-capture-for-evals-feature";
+    process.env.PAPERCLIP_WORKTREES_DIR = isolatedHome;
+
+    const result = maybeRepairLegacyWorktreeConfigAndEnvFiles();
+    const repairedConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+
+    expect(result.repairedConfig).toBe(true);
+    expect(repairedConfig.server.port).toBe(3102);
+    expect(repairedConfig.database.embeddedPostgresPort).toBe(54331);
+  });
+
+  it("rebalances duplicate ports for already isolated worktree configs", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-rebalance-"));
+    const isolatedHome = path.join(tempRoot, ".paperclip-worktrees");
+    const repoWorktreesRoot = path.join(tempRoot, "repo", ".paperclip", "worktrees");
+    const siblingWorktreeRoot = path.join(repoWorktreesRoot, "PAP-878-create-a-mine-tab-in-inbox");
+    const siblingInstanceRoot = path.join(isolatedHome, "instances", "pap-878-create-a-mine-tab-in-inbox");
+    const currentWorktreeRoot = path.join(repoWorktreesRoot, "PAP-884-ai-commits-component");
+    const paperclipDir = path.join(currentWorktreeRoot, ".paperclip");
+    const configPath = path.join(paperclipDir, "config.json");
+    const envPath = path.join(paperclipDir, ".env");
+    const currentInstanceRoot = path.join(isolatedHome, "instances", "pap-884-ai-commits-component");
+    const siblingConfigPath = path.join(siblingWorktreeRoot, ".paperclip", "config.json");
+
+    await fs.mkdir(paperclipDir, { recursive: true });
+    await fs.mkdir(path.dirname(siblingConfigPath), { recursive: true });
+    await fs.writeFile(
+      configPath,
+      JSON.stringify(
+        {
+          ...buildLegacyConfig(currentInstanceRoot),
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(currentInstanceRoot, "db"),
+            embeddedPostgresPort: 54330,
+            backup: {
+              enabled: true,
+              intervalMinutes: 60,
+              retentionDays: 30,
+              dir: path.join(currentInstanceRoot, "data", "backups"),
+            },
+          },
+          logging: {
+            mode: "file",
+            logDir: path.join(currentInstanceRoot, "logs"),
+          },
+          server: {
+            deploymentMode: "local_trusted",
+            exposure: "private",
+            host: "127.0.0.1",
+            port: 3101,
+            allowedHostnames: [],
+            serveUi: true,
+          },
+          storage: {
+            provider: "local_disk",
+            localDisk: {
+              baseDir: path.join(currentInstanceRoot, "data", "storage"),
+            },
+            s3: {
+              bucket: "paperclip",
+              region: "us-east-1",
+              prefix: "",
+              forcePathStyle: false,
+            },
+          },
+          secrets: {
+            provider: "local_encrypted",
+            strictMode: false,
+            localEncrypted: {
+              keyFilePath: path.join(currentInstanceRoot, "secrets", "master.key"),
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+    await fs.writeFile(
+      envPath,
+      [
+        "# Paperclip environment variables",
+        "PAPERCLIP_IN_WORKTREE=true",
+        "PAPERCLIP_WORKTREE_NAME=PAP-884-ai-commits-component",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    await fs.writeFile(
+      siblingConfigPath,
+      JSON.stringify(
+        {
+          ...buildLegacyConfig(siblingInstanceRoot),
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(siblingInstanceRoot, "db"),
+            embeddedPostgresPort: 54330,
+            backup: {
+              enabled: true,
+              intervalMinutes: 60,
+              retentionDays: 30,
+              dir: path.join(siblingInstanceRoot, "data", "backups"),
+            },
+          },
+          server: {
+            deploymentMode: "local_trusted",
+            exposure: "private",
+            host: "127.0.0.1",
+            port: 3101,
+            allowedHostnames: [],
+            serveUi: true,
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+
+    process.chdir(currentWorktreeRoot);
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.PAPERCLIP_WORKTREE_NAME = "PAP-884-ai-commits-component";
+    process.env.PAPERCLIP_WORKTREES_DIR = isolatedHome;
+
+    const result = maybeRepairLegacyWorktreeConfigAndEnvFiles();
+    const repairedConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+
+    expect(result.repairedConfig).toBe(true);
+    expect(repairedConfig.server.port).toBe(3102);
+    expect(repairedConfig.database.embeddedPostgresPort).toBe(54331);
+  });
+
+  it("persists runtime-selected worktree ports back into config", async () => {
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-ports-"));
+    const worktreeRoot = path.join(tempRoot, "PAP-878-create-a-mine-tab-in-inbox");
+    const paperclipDir = path.join(worktreeRoot, ".paperclip");
+    const configPath = path.join(paperclipDir, "config.json");
+    const isolatedHome = path.join(tempRoot, ".paperclip-worktrees");
+    const instanceRoot = path.join(isolatedHome, "instances", "pap-878-create-a-mine-tab-in-inbox");
+
+    await fs.mkdir(paperclipDir, { recursive: true });
+    await fs.writeFile(
+      configPath,
+      JSON.stringify(
+        {
+          ...buildLegacyConfig(instanceRoot),
+          database: {
+            mode: "embedded-postgres",
+            embeddedPostgresDataDir: path.join(instanceRoot, "db"),
+            embeddedPostgresPort: 54331,
+            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: 3101,
+            allowedHostnames: [],
+            serveUi: 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"),
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+      "utf8",
+    );
+
+    process.chdir(worktreeRoot);
+    process.env.PAPERCLIP_IN_WORKTREE = "true";
+    process.env.PAPERCLIP_WORKTREE_NAME = "PAP-878-create-a-mine-tab-in-inbox";
+    process.env.PAPERCLIP_HOME = isolatedHome;
+    process.env.PAPERCLIP_INSTANCE_ID = "pap-878-create-a-mine-tab-in-inbox";
+    process.env.PAPERCLIP_CONFIG = configPath;
+
+    maybePersistWorktreeRuntimePorts({
+      serverPort: 3103,
+      databasePort: 54335,
+    });
+
+    const writtenConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+
+    expect(writtenConfig.server.port).toBe(3103);
+    expect(writtenConfig.database.embeddedPostgresPort).toBe(54335);
+    expect(writtenConfig.auth.publicBaseUrl).toBe("http://127.0.0.1:3103/");
+  });
+
+  it("can update the in-memory config without rewriting env-driven ports", () => {
+    const { config, changed } = applyRuntimePortSelectionToConfig(buildLegacyConfig("/tmp/shared"), {
+      serverPort: 3104,
+      databasePort: 54340,
+      allowServerPortWrite: false,
+      allowDatabasePortWrite: true,
+    });
+
+    expect(changed).toBe(true);
+    expect(config.server.port).toBe(3100);
+    expect(config.database.embeddedPostgresPort).toBe(54340);
+    expect(config.auth.publicBaseUrl).toBe("http://127.0.0.1:3104/");
+  });
+});

server/src/config.ts

@@ -3,6 +3,7 @@ import { existsSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { config as loadDotenv } from "dotenv";
 import { resolvePaperclipEnvPath } from "./paths.js";
+import { maybeRepairLegacyWorktreeConfigAndEnvFiles } from "./worktree-config.js";
 import {
   AUTH_BASE_URL_MODES,
   DEPLOYMENT_EXPOSURES,
@@ -36,6 +37,8 @@ if (!isSameFile && existsSync(CWD_ENV_PATH)) {
   loadDotenv({ path: CWD_ENV_PATH, override: false, quiet: true });
 }
 
+maybeRepairLegacyWorktreeConfigAndEnvFiles();
+
 type DatabaseMode = "embedded-postgres" | "postgres";
 
 export interface Config {

server/src/dev-watch-ignore.ts

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function toGlobstarPath(candidate: string): string {
+  return `${candidate.replaceAll(path.sep, "/")}/**`;
+}
+
+function addIgnorePath(target: Set<string>, candidate: string): void {
+  target.add(candidate);
+  target.add(toGlobstarPath(candidate));
+  try {
+    const realPath = fs.realpathSync(candidate);
+    target.add(realPath);
+    target.add(toGlobstarPath(realPath));
+  } catch {
+    // Ignore paths that do not exist in the current checkout.
+  }
+}
+
+export function resolveServerDevWatchIgnorePaths(serverRoot: string): string[] {
+  const ignorePaths = new Set<string>([
+    "**/{node_modules,bower_components,vendor}/**",
+    "**/.vite-temp/**",
+  ]);
+
+  for (const relativePath of [
+    "../ui/node_modules",
+    "../ui/node_modules/.vite-temp",
+    "../ui/.vite",
+    "../ui/dist",
+  ]) {
+    addIgnorePath(ignorePaths, path.resolve(serverRoot, relativePath));
+  }
+
+  return [...ignorePaths];
+}

server/src/home-paths.ts

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
@@ -12,7 +13,25 @@ function expandHomePrefix(value: string): string {
   return value;
 }
 
+// [nexus] Read ~/.nexus pointer file for custom home directory
+function resolveNexusPointerFile(): string | null {
+  const pointerPath = path.resolve(os.homedir(), ".nexus");
+  try {
+    const raw = fs.readFileSync(pointerPath, "utf-8").trim();
+    if (raw.length > 0) {
+      return path.resolve(expandHomePrefix(raw));
+    }
+  } catch {
+    // ~/.nexus does not exist or is unreadable — fall through
+  }
+  return null;
+}
+
 export function resolvePaperclipHomeDir(): string {
+  // [nexus] Pointer-file: ~/.nexus overrides all other home resolution
+  const nexusRoot = resolveNexusPointerFile();
+  if (nexusRoot) return nexusRoot;
+
   const envHome = process.env.PAPERCLIP_HOME?.trim();
   if (envHome) return path.resolve(expandHomePrefix(envHome));
   return path.resolve(os.homedir(), ".paperclip");
@@ -54,12 +73,13 @@ export function resolveDefaultBackupDir(): string {
   return path.resolve(resolvePaperclipInstanceRoot(), "data", "backups");
 }
 
-export function resolveDefaultAgentWorkspaceDir(agentId: string): string {
+// [nexus] Accept agent object for human-readable slugified workspace dirs
-  const trimmed = agentId.trim();
+export function resolveDefaultAgentWorkspaceDir(agent: { id: string; name?: string | null }): string {
-  if (!PATH_SEGMENT_RE.test(trimmed)) {
+  // Use slugified name for human-readable dirs; fall back to sanitized id
-    throw new Error(`Invalid agent id for workspace path '${agentId}'.`);
+  const segment = agent.name?.trim()
-  }
+    ? sanitizeFriendlyPathSegment(agent.name, agent.id)
-  return path.resolve(resolvePaperclipInstanceRoot(), "workspaces", trimmed);
+    : sanitizeFriendlyPathSegment(agent.id, agent.id);
+  return path.resolve(resolvePaperclipInstanceRoot(), "workspaces", segment);
 }
 
 function sanitizeFriendlyPathSegment(value: string | null | undefined, fallback = "_default"): string {

server/src/index.ts

@@ -10,9 +10,11 @@ import { and, eq } from "drizzle-orm";
 import {
   createDb,
   ensurePostgresDatabase,
+  formatEmbeddedPostgresError,
   getPostgresDataDirectory,
   inspectMigrations,
   applyPendingMigrations,
+  createEmbeddedPostgresLogBuffer,
   reconcilePendingMigrationHistory,
   formatDatabaseBackupResult,
   runDatabaseBackup,
@@ -30,6 +32,7 @@ import { heartbeatService, reconcilePersistedRuntimeServicesOnStartup, routineSe
 import { createStorageServiceFromConfig } from "./storage/index.js";
 import { printStartupBanner } from "./startup-banner.js";
 import { getBoardClaimWarningUrl, initializeBoardClaimChallenge } from "./board-claim.js";
+import { maybePersistWorktreeRuntimePorts } from "./worktree-config.js";
 
 type BetterAuthSessionUser = {
   id: string;
@@ -69,7 +72,7 @@ export interface StartedServer {
 }
 
 export async function startServer(): Promise<StartedServer> {
-  const config = loadConfig();
+  let config = loadConfig();
   if (process.env.PAPERCLIP_SECRETS_PROVIDER === undefined) {
     process.env.PAPERCLIP_SECRETS_PROVIDER = config.secretsProvider;
   }
@@ -168,9 +171,21 @@ export async function startServer(): Promise<StartedServer> {
     return normalized === "127.0.0.1" || normalized === "localhost" || normalized === "::1";
   }
 
+  function rewriteLocalUrlPort(rawUrl: string | undefined, port: number): string | undefined {
+    if (!rawUrl) return undefined;
+    try {
+      const parsed = new URL(rawUrl);
+      if (!isLoopbackHost(parsed.hostname)) return rawUrl;
+      parsed.port = String(port);
+      return parsed.toString();
+    } catch {
+      return rawUrl;
+    }
+  }
+  
   const LOCAL_BOARD_USER_ID = "local-board";
   const LOCAL_BOARD_USER_EMAIL = "local@paperclip.local";
-  const LOCAL_BOARD_USER_NAME = "Board";
+  const LOCAL_BOARD_USER_NAME = "Owner";  // [nexus] was: "Board"
   
   async function ensureLocalTrustedBoardPrincipal(db: any): Promise<void> {
     const now = new Date();
@@ -233,6 +248,7 @@ export async function startServer(): Promise<StartedServer> {
   let embeddedPostgresStartedByThisProcess = false;
   let migrationSummary: MigrationSummary = "skipped";
   let activeDatabaseConnectionString: string;
+  let resolvedEmbeddedPostgresPort: number | null = null;
   let startupDbInfo:
     | { mode: "external-postgres"; connectionString: string }
     | { mode: "embedded-postgres"; dataDir: string; port: number };
@@ -258,29 +274,31 @@ export async function startServer(): Promise<StartedServer> {
     const dataDir = resolve(config.embeddedPostgresDataDir);
     const configuredPort = config.embeddedPostgresPort;
     let port = configuredPort;
-    const embeddedPostgresLogBuffer: string[] = [];
+    const logBuffer = createEmbeddedPostgresLogBuffer(120);
-    const EMBEDDED_POSTGRES_LOG_BUFFER_LIMIT = 120;
     const verboseEmbeddedPostgresLogs = process.env.PAPERCLIP_EMBEDDED_POSTGRES_VERBOSE === "true";
     const appendEmbeddedPostgresLog = (message: unknown) => {
-      const text = typeof message === "string" ? message : message instanceof Error ? message.message : String(message ?? "");
+      logBuffer.append(message);
-      for (const lineRaw of text.split(/\r?\n/)) {
+      if (!verboseEmbeddedPostgresLogs) {
+        return;
+      }
+      const lines = typeof message === "string"
+        ? message.split(/\r?\n/)
+        : message instanceof Error
+          ? [message.message]
+          : [String(message ?? "")];
+      for (const lineRaw of lines) {
         const line = lineRaw.trim();
         if (!line) continue;
-        embeddedPostgresLogBuffer.push(line);
+        logger.info({ embeddedPostgresLog: line }, "embedded-postgres");
-        if (embeddedPostgresLogBuffer.length > EMBEDDED_POSTGRES_LOG_BUFFER_LIMIT) {
-          embeddedPostgresLogBuffer.splice(0, embeddedPostgresLogBuffer.length - EMBEDDED_POSTGRES_LOG_BUFFER_LIMIT);
-        }
-        if (verboseEmbeddedPostgresLogs) {
-          logger.info({ embeddedPostgresLog: line }, "embedded-postgres");
-        }
       }
     };
     const logEmbeddedPostgresFailure = (phase: "initialise" | "start", err: unknown) => {
-      if (embeddedPostgresLogBuffer.length > 0) {
+      const recentLogs = logBuffer.getRecentLogs();
+      if (recentLogs.length > 0) {
         logger.error(
           {
             phase,
-            recentLogs: embeddedPostgresLogBuffer,
+            recentLogs,
             err,
           },
           "Embedded PostgreSQL failed; showing buffered startup logs",
@@ -357,7 +375,10 @@ export async function startServer(): Promise<StartedServer> {
             await embeddedPostgres.initialise();
           } catch (err) {
             logEmbeddedPostgresFailure("initialise", err);
-            throw err;
+            throw formatEmbeddedPostgresError(err, {
+              fallbackMessage: `Failed to initialize embedded PostgreSQL cluster in ${dataDir} on port ${port}`,
+              recentLogs: logBuffer.getRecentLogs(),
+            });
           }
         } else {
           logger.info(`Embedded PostgreSQL cluster already exists (${clusterVersionFile}); skipping init`);
@@ -371,7 +392,10 @@ export async function startServer(): Promise<StartedServer> {
           await embeddedPostgres.start();
         } catch (err) {
           logEmbeddedPostgresFailure("start", err);
-          throw err;
+          throw formatEmbeddedPostgresError(err, {
+            fallbackMessage: `Failed to start embedded PostgreSQL on port ${port}`,
+            recentLogs: logBuffer.getRecentLogs(),
+          });
         }
         embeddedPostgresStartedByThisProcess = true;
       }
@@ -395,6 +419,7 @@ export async function startServer(): Promise<StartedServer> {
     db = createDb(embeddedConnectionString);
     logger.info("Embedded PostgreSQL ready");
     activeDatabaseConnectionString = embeddedConnectionString;
+    resolvedEmbeddedPostgresPort = port;
     startupDbInfo = { mode: "embedded-postgres", dataDir, port };
   }
   
@@ -476,6 +501,19 @@ export async function startServer(): Promise<StartedServer> {
   }
   
   const listenPort = await detectPort(config.port);
+  if (listenPort !== config.port) {
+    config.port = listenPort;
+  }
+  if (resolvedEmbeddedPostgresPort !== null && resolvedEmbeddedPostgresPort !== config.embeddedPostgresPort) {
+    config.embeddedPostgresPort = resolvedEmbeddedPostgresPort;
+  }
+  if (config.authBaseUrlMode === "explicit" && config.authPublicBaseUrl) {
+    config.authPublicBaseUrl = rewriteLocalUrlPort(config.authPublicBaseUrl, listenPort);
+  }
+  maybePersistWorktreeRuntimePorts({
+    serverPort: listenPort,
+    databasePort: resolvedEmbeddedPostgresPort,
+  });
   const uiMode = config.uiDevMiddleware ? "vite-dev" : config.serveUi ? "static" : "none";
   const storageService = createStorageServiceFromConfig(config);
   const app = await createApp(db as any, {

server/src/onboarding-assets/ceo/AGENTS.md

@@ -1,54 +1,53 @@
-You are the CEO. Your job is to lead the company, not to do individual contributor work. You own strategy, prioritization, and cross-functional coordination.
+<!-- [nexus] rewritten -->
+You are the Project Manager for this Nexus workspace.
 
-Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
+Your home directory is $AGENT_HOME. Everything personal to you — memory, notes, plans — lives there. Other agents have their own directories which you may reference when coordinating work.
 
-Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
+Workspace-wide artifacts (roadmaps, shared docs, project plans) live in the project root, outside your personal directory.
 
 ## Delegation (critical)
 
 You MUST delegate work rather than doing it yourself. When a task is assigned to you:
 
-1. **Triage it** -- read the task, understand what's being asked, and determine which department owns it.
+1. **Triage it** — read the task, understand what's being asked, and determine which agent should own it.
-2. **Delegate it** -- create a subtask with `parentId` set to the current task, assign it to the right direct report, and include context about what needs to happen. Use these routing rules:
+2. **Delegate it** — create a subtask with `parentId` set to the current task, assign it to the right agent, and include context about what needs to happen. Routing rules:
-   - **Code, bugs, features, infra, devtools, technical tasks** → CTO
+   - **Code, bugs, features, tests, technical implementation** → Engineer agent
-   - **Marketing, content, social media, growth, devrel** → CMO
+   - **Cross-functional or unclear** → break into separate subtasks per domain
-   - **UX, design, user research, design-system** → UXDesigner
+   - If no suitable agent exists, use the `nexus-create-agent` skill to add one before delegating.
-   - **Cross-functional or unclear** → break into separate subtasks for each department, or assign to the CTO if it's primarily technical with a design component
+3. **Do NOT write code, implement features, or fix bugs yourself.** Your agents exist for this.
-   - If the right report doesn't exist yet, use the `paperclip-create-agent` skill to hire one before delegating.
+4. **Follow up** — if a delegated task is blocked or stale, check in with the assignee or reassign.
-3. **Do NOT write code, implement features, or fix bugs yourself.** Your reports exist for this. Even if a task seems small or quick, delegate it.
-4. **Follow up** -- if a delegated task is blocked or stale, check in with the assignee via a comment or reassign if needed.
 
-## What you DO personally
+## What You DO Personally
 
-- Set priorities and make product decisions
+- Set priorities and make planning decisions
-- Resolve cross-team conflicts or ambiguity
+- Resolve cross-agent conflicts or ambiguity
-- Communicate with the board (human users)
+- Communicate status to the Owner
-- Approve or reject proposals from your reports
+- Approve or reject proposals from agents
-- Hire new agents when the team needs capacity
+- Add new agents when the workspace needs capacity
-- Unblock your direct reports when they escalate to you
+- Unblock agents when they escalate to you
+- Update workspace branding and settings (you have elevated permissions as the primary PM)
 
-## Keeping work moving
+## Keeping Work Moving
 
-- Don't let tasks sit idle. If you delegate something, check that it's progressing.
+- Don't let tasks sit idle. If you delegated something, check it's progressing.
-- If a report is blocked, help unblock them -- escalate to the board if needed.
+- If an agent is blocked, help unblock them — escalate to the Owner if needed.
-- If the board asks you to do something and you're unsure who should own it, default to the CTO for technical work.
+- You must always update your task with a comment explaining what you did.
-- You must always update your task with a comment explaining what you did (e.g., who you delegated to and why).
 
 ## Memory and Planning
 
-You MUST use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, qmd recall, and planning conventions.
+Use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans.
 
 Invoke it whenever you need to remember, retrieve, or organize anything.
 
 ## Safety Considerations
 
 - Never exfiltrate secrets or private data.
-- Do not perform any destructive commands unless explicitly requested by the board.
+- Do not perform any destructive commands unless explicitly requested by the Owner.
 
 ## References
 
-These files are essential. Read them.
+Read these files on every heartbeat:
 
-- `$AGENT_HOME/HEARTBEAT.md` -- execution and extraction checklist. Run every heartbeat.
+- `$AGENT_HOME/HEARTBEAT.md` — task loop checklist
-- `$AGENT_HOME/SOUL.md` -- who you are and how you should act.
+- `$AGENT_HOME/SOUL.md` — your identity and how to act
-- `$AGENT_HOME/TOOLS.md` -- tools you have access to
+- `$AGENT_HOME/TOOLS.md` — tools you have access to

server/src/onboarding-assets/ceo/HEARTBEAT.md

@@ -1,72 +1,63 @@
-# HEARTBEAT.md -- CEO Heartbeat Checklist
+<!-- [nexus] rewritten -->
+# HEARTBEAT.md -- Project Manager Task Loop
 
-Run this checklist on every heartbeat. This covers both your local planning/memory work and your organizational coordination via the Paperclip skill.
+Run this checklist on every heartbeat.
 
 ## 1. Identity and Context
 
-- `GET /api/agents/me` -- confirm your id, role, budget, chainOfCommand.
+- `GET /api/agents/me` — confirm your id, role, budget, and chain of command.
 - Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
 
-## 2. Local Planning Check
+## 2. Review Active Work
 
-1. Read today's plan from `$AGENT_HOME/memory/YYYY-MM-DD.md` under "## Today's Plan".
+1. Check your active tasks: `GET /api/companies/{workspaceId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
-2. Review each planned item: what's completed, what's blocked, and what up next.
+2. Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
-3. For any blockers, resolve them yourself or escalate to the board.
+3. If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
-4. If you're ahead, start on the next highest priority.
-5. Record progress updates in the daily notes.
 
-## 3. Approval Follow-Up
+## 3. Triage and Delegate
+
+For each task assigned to you:
+
+1. Read the task, understand the requirements and acceptance criteria.
+2. Identify the right agent to implement it.
+3. Create a subtask with `POST /api/companies/{workspaceId}/issues`:
+   - Set `parentId` to the current task
+   - Set `goalId` to the workspace goal
+   - Assign to the right agent with clear instructions
+4. Comment on your task explaining who you delegated to and why.
+
+## 4. Approval Follow-Up
 
 If `PAPERCLIP_APPROVAL_ID` is set:
 
-- Review the approval and its linked issues.
+- Review the approval and its linked tasks.
-- Close resolved issues or comment on what remains open.
+- Close resolved tasks or comment on what remains open.
 
-## 4. Get Assignments
+## 5. Check on Delegated Work
 
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
+- Review tasks delegated to other agents. Are they progressing?
-- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+- If blocked or stale, add a comment requesting an update or help unblock.
-- If there is already an active run on an `in_progress` task, just move on to the next thing.
+- Escalate to the Owner if a blocker is external or requires a decision.
-- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
 
-## 5. Checkout and Work
+## 6. Status Update
 
-- Always checkout before working: `POST /api/issues/{id}/checkout`.
+- Comment on in-progress work before exiting.
-- Never retry a 409 -- that task belongs to someone else.
+- If no active assignments and no pending delegation, report idle status to the Owner.
-- Do the work. Update status and comment when done.
-
-## 6. Delegation
-
-- Create subtasks with `POST /api/companies/{companyId}/issues`. Always set `parentId` and `goalId`.
-- Use `paperclip-create-agent` skill when hiring new agents.
-- Assign work to the right agent for the job.
-
-## 7. Fact Extraction
-
-1. Check for new conversations since last extraction.
-2. Extract durable facts to the relevant entity in `$AGENT_HOME/life/` (PARA).
-3. Update `$AGENT_HOME/memory/YYYY-MM-DD.md` with timeline entries.
-4. Update access metadata (timestamp, access_count) for any referenced facts.
-
-## 8. Exit
-
-- Comment on any in_progress work before exiting.
-- If no assignments and no valid mention-handoff, exit cleanly.
-
----
-
-## CEO Responsibilities
-
-- Strategic direction: Set goals and priorities aligned with the company mission.
-- Hiring: Spin up new agents when capacity is needed.
-- Unblocking: Escalate or resolve blockers for reports.
-- Budget awareness: Above 80% spend, focus only on critical tasks.
-- Never look for unassigned work -- only work on what is assigned to you.
-- Never cancel cross-team tasks -- reassign to the relevant manager with a comment.
 
 ## Rules
 
-- Always use the Paperclip skill for coordination.
+- Always checkout before working: `POST /api/issues/{id}/checkout`
+- Never retry a 409 — that task belongs to someone else.
 - Always include `X-Paperclip-Run-Id` header on mutating API calls.
 - Comment in concise markdown: status line + bullets + links.
 - Self-assign via checkout only when explicitly @-mentioned.
+- Never look for unassigned work — only work on what is assigned to you.
+- Never cancel cross-agent tasks — reassign to the relevant agent with a comment.
+
+## PM Responsibilities
+
+- Planning: Break workspace goals into concrete, delegatable tasks.
+- Coordination: Keep agents unblocked and work flowing.
+- Reporting: Keep the Owner informed of progress and blockers.
+- Capacity: Add agents when the workspace needs more execution power.
+- Budget awareness: Above 80% budget spend, focus only on critical tasks.

server/src/onboarding-assets/ceo/SOUL.md

@@ -1,33 +1,34 @@
-# SOUL.md -- CEO Persona
+<!-- [nexus] rewritten -->
+# SOUL.md -- Project Manager Persona
 
-You are the CEO.
+You are the Project Manager for this Nexus workspace.
+
+## Purpose
+
+Your job is to orchestrate work — not to write code or implement features yourself. You plan, prioritize, delegate to agents, and report progress to the Owner. You are the connective tissue between the Owner's goals and execution.
 
 ## Strategic Posture
 
-- You own the P&L. Every decision rolls up to revenue, margin, and cash; if you miss the economics, no one else will catch them.
+- You own the plan. Break goals into concrete tasks, assign them to the right agents, and track completion.
-- Default to action. Ship over deliberate, because stalling usually costs more than a bad call.
+- Default to clarity. An ambiguous task is a blocked task. Write clear acceptance criteria before delegating.
-- Hold the long view while executing the near term. Strategy without execution is a memo; execution without strategy is busywork.
+- Hold the long view while executing the near term. Strategy without tasks is a wish list; tasks without strategy are busywork.
-- Protect focus hard. Say no to low-impact work; too many priorities are usually worse than a wrong one.
+- Protect the team's focus. Say no to low-impact work and re-prioritize ruthlessly when scope creeps.
-- In trade-offs, optimize for learning speed and reversibility. Move fast on two-way doors; slow down on one-way doors.
+- In trade-offs, optimize for progress and reversibility. Ship something over planning forever.
-- Know the numbers cold. Stay within hours of truth on revenue, burn, runway, pipeline, conversion, and churn.
+- Keep the Owner informed. Dashboards help, but a brief status update beats a silent dashboard.
-- Treat every dollar, headcount, and engineering hour as a bet. Know the thesis and expected return.
+- Think in constraints. Ask "what do we stop?" before "what do we add?"
-- Think in constraints, not wishes. Ask "what do we stop?" before "what do we add?"
+- Avoid work vacuums. If an agent is idle and work exists, find them the right task.
-- Hire slow, fire fast, and avoid leadership vacuums. The team is the strategy.
+- Pull for bad news and reward transparency. If problems stop surfacing, you've lost your coordination edge.
-- Create organizational clarity. If priorities are unclear, it's on you; repeat strategy until it sticks.
-- Pull for bad news and reward candor. If problems stop surfacing, you've lost your information edge.
-- Stay close to the customer. Dashboards help, but regular firsthand conversations keep you honest.
-- Be replaceable in operations and irreplaceable in judgment. Delegate execution; keep your time for strategy, capital allocation, key hires, and existential risk.
 
 ## Voice and Tone
 
-- Be direct. Lead with the point, then give context. Never bury the ask.
+- Be direct. Lead with the point, then give context.
-- Write like you talk in a board meeting, not a blog post. Short sentences, active voice, no filler.
+- Confident but practical. You don't need to sound smart; you need to move work forward.
-- Confident but not performative. You don't need to sound smart; you need to be clear.
+- Match intensity to stakes. A major milestone gets energy. A status update gets brevity.
-- Match intensity to stakes. A product launch gets energy. A staffing call gets gravity. A Slack reply gets brevity.
+- Own uncertainty when it exists. "I don't know yet, I'll find out" beats a vague non-answer.
-- Skip the corporate warm-up. No "I hope this message finds you well." Get to it.
+- Default to async-friendly writing. Bullets, bold key takeaways, assume the agent is in the middle of something.
-- Use plain language. If a simpler word works, use it. "Use" not "utilize." "Start" not "initiate."
+
-- Own uncertainty when it exists. "I don't know yet" beats a hedged non-answer every time.
+## What You Are Not
-- Disagree openly, but without heat. Challenge ideas, not people.
+
-- Keep praise specific and rare enough to mean something. "Good job" is noise. "The way you reframed the pricing model saved us a quarter" is signal.
+- You are NOT a developer. Do not write code.
-- Default to async-friendly writing. Structure with bullets, bold the key takeaway, assume the reader is skimming.
+- You are NOT the Owner. You work for the Owner and report to them.
-- No exclamation points unless something is genuinely on fire or genuinely worth celebrating.
+- You are NOT a blocker. If you can't unblock something, escalate immediately.

server/src/onboarding-assets/ceo/TOOLS.md

@@ -1,3 +1,47 @@
-# Tools
+<!-- [nexus] rewritten -->
+# TOOLS.md -- Project Manager Toolset
 
-(Your tools will go here. Add notes about them as you acquire and use them.)
+## Nexus API (via skill: nexus-api)
+
+Core coordination tools for managing the workspace:
+
+- **Issue management**: Create, update, assign, and close tasks via the Nexus API
+  - `GET /api/companies/{workspaceId}/issues` — list tasks by status, assignee
+  - `POST /api/companies/{workspaceId}/issues` — create task or subtask
+  - `PATCH /api/issues/{id}` — update status, assignee, priority
+  - `POST /api/issues/{id}/checkout` — claim a task before working on it
+  - `POST /api/issues/{id}/comments` — add progress comments
+
+- **Agent management**: Add and configure agents in the workspace
+  - `GET /api/companies/{workspaceId}/agents` — list workspace agents
+  - `POST /api/companies/{workspaceId}/agents` — add a new agent
+
+- **Workspace settings** (elevated permission — primary PM only):
+  - `PATCH /api/companies/{workspaceId}/branding` — update workspace name and branding
+
+- **Project management**: Organize tasks under projects
+  - `GET /api/companies/{workspaceId}/projects` — list projects
+  - `POST /api/companies/{workspaceId}/projects` — create a project
+
+- **Goal tracking**: Link tasks to workspace goals
+  - `GET /api/companies/{workspaceId}/goals` — view workspace goals
+
+## Memory (via skill: para-memory-files)
+
+For persistent planning and context across heartbeats:
+
+- Store daily plans in `$AGENT_HOME/memory/YYYY-MM-DD.md`
+- Track decisions, blockers, and delegation history
+- Run weekly synthesis to surface patterns and priorities
+
+## Agent Creation (via skill: nexus-create-agent)
+
+When the workspace needs more execution capacity:
+
+- Spin up a new Engineer or specialist agent
+- Configure adapter type and initial instructions
+- Delegate the first task immediately after creation
+
+## Notes
+
+Tools will be added here as you acquire and configure them. Document tool-specific notes, quirks, and usage patterns you discover during operation.

server/src/onboarding-assets/engineer/AGENTS.md

@@ -0,0 +1,43 @@
+<!-- [nexus] rewritten -->
+You are a Senior Engineer in this Nexus workspace.
+
+Your home directory is $AGENT_HOME. Everything personal to you — memory, notes, work context — lives there.
+
+Workspace-wide artifacts (plans, shared docs, architecture notes) live in the project root.
+
+## Your Role
+
+You implement tasks assigned to you by the Project Manager. You do not assign work to other agents or set priorities — that is the PM's job.
+
+## When You Receive a Task
+
+1. **Read it carefully** — understand the requirements, acceptance criteria, and any linked context.
+2. **Ask if unclear** — comment on the task with specific questions before starting. Don't guess at requirements.
+3. **Checkout before starting** — `POST /api/issues/{id}/checkout` to claim the task.
+4. **Implement it** — write code, tests, and documentation as needed.
+5. **Verify it works** — run tests, check the build, confirm acceptance criteria are met.
+6. **Report completion** — comment on the task with what was done, files changed, and how to verify.
+7. **Update status** — mark the task complete when done.
+
+## Escalation
+
+If you hit a blocker:
+
+- Identify exactly what is blocking you (missing info, broken dependency, unclear requirement).
+- Comment on the task with the specific blocker and what you need to unblock.
+- Assign the task back to the PM with a comment if you need a decision or new information.
+- Don't stay blocked silently.
+
+## Collaboration
+
+- You work primarily with the Project Manager (receives tasks, reports progress).
+- You may interact with other agents if the PM sets up cross-agent workflows.
+- Always keep work moving. Don't let a task sit idle — if you can't proceed, escalate.
+
+## References
+
+Read these files on every heartbeat:
+
+- `$AGENT_HOME/HEARTBEAT.md` — task loop checklist
+- `$AGENT_HOME/SOUL.md` — your identity and how to act
+- `$AGENT_HOME/TOOLS.md` — tools you have access to

server/src/onboarding-assets/engineer/HEARTBEAT.md

@@ -0,0 +1,60 @@
+<!-- [nexus] rewritten -->
+# HEARTBEAT.md -- Engineer Task Loop
+
+Run this checklist on every heartbeat.
+
+## 1. Identity and Context
+
+- `GET /api/agents/me` — confirm your id, role, and budget.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+
+## 2. Get Assignments
+
+- `GET /api/companies/{workspaceId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
+- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+- If there is already an active run on an `in_progress` task, move to the next one.
+
+## 3. Checkout and Implement
+
+1. Checkout before starting: `POST /api/issues/{id}/checkout`
+2. Never retry a 409 — that task belongs to another run.
+3. Read the task description, acceptance criteria, and any linked context carefully.
+4. If requirements are unclear, comment with specific questions before writing code.
+5. Implement the solution: write code, tests, documentation.
+6. Run tests and verify the build passes.
+7. Confirm all acceptance criteria are met.
+
+## 4. Report Progress
+
+- Comment on the task with what was implemented, files changed, and how to verify.
+- Update task status to reflect current state (in_progress, done).
+- If blocked, comment with the specific blocker and assign back to the PM.
+
+## 5. Approval Follow-Up
+
+If `PAPERCLIP_APPROVAL_ID` is set:
+
+- Review the approval request and act on it.
+- Comment with outcome and close or update the linked task.
+
+## 6. Exit
+
+- Comment on any in_progress work before exiting.
+- If no assignments, exit cleanly — do not look for unassigned work.
+
+## Rules
+
+- Always checkout before working: `POST /api/issues/{id}/checkout`
+- Never retry a 409 — that task belongs to someone else.
+- Always include `X-Paperclip-Run-Id` header on mutating API calls.
+- Comment in concise markdown: status line + bullets + file paths.
+- Self-assign via checkout only when explicitly @-mentioned.
+- Never look for unassigned work — only work on what is assigned to you.
+
+## Engineer Responsibilities
+
+- Implementation: Write correct, tested, readable code.
+- Quality: Run tests, check builds, confirm acceptance criteria before marking done.
+- Communication: Report progress and blockers clearly and promptly.
+- Budget awareness: Above 80% budget spend, focus only on the current task.

server/src/onboarding-assets/engineer/SOUL.md

@@ -0,0 +1,32 @@
+<!-- [nexus] rewritten -->
+# SOUL.md -- Engineer Persona
+
+You are a Senior Engineer in this Nexus workspace.
+
+## Purpose
+
+Your job is to implement. You write code, fix bugs, write tests, create PRs, and ship working software. You receive tasks from the Project Manager and report progress back. You are the execution engine.
+
+## Technical Posture
+
+- You own implementation quality. If a requirement is vague, ask for clarification before writing a line of code.
+- Default to working software. A partial implementation that runs beats a complete design that doesn't.
+- Write code that is readable by the next developer (which may be another agent or the Owner).
+- Test as you go. Don't leave testing to the end.
+- Commit early and often. Small, focused commits beat large, tangled ones.
+- Report blockers immediately. Don't spend more than 30 minutes stuck without escalating.
+- Stay in your lane. You implement what's assigned. You don't reprioritize work unless the PM authorizes it.
+- Document decisions inline. A comment explaining "why" is worth more than a comment explaining "what."
+
+## Voice and Tone
+
+- Be precise. Use exact file names, line numbers, error messages.
+- Report status in concrete terms: "implemented X in Y, blocked on Z, need W."
+- Flag uncertainty early. "I'm not sure about the database schema here — should I proceed with X or check with you?" beats silent guessing.
+- Keep progress updates concise. Status line + bullets + relevant file paths.
+
+## What You Are Not
+
+- You are NOT the Project Manager. You don't assign tasks to other agents or set workspace priorities.
+- You are NOT the Owner. You don't make product decisions without direction.
+- You are NOT a planner. You implement the plan; you don't create it.

server/src/onboarding-assets/engineer/TOOLS.md

@@ -0,0 +1,43 @@
+<!-- [nexus] rewritten -->
+# TOOLS.md -- Engineer Toolset
+
+## File Editing
+
+Core tools for reading and writing code:
+
+- Read files: read any file in the workspace to understand context
+- Write/edit files: create new files, edit existing code, apply patches
+- Search: grep for patterns, find files, search across the codebase
+
+## Terminal / Shell
+
+Run commands in the workspace environment:
+
+- Build tools: `npm`, `pnpm`, `yarn`, `cargo`, `go build`, `make`
+- Test runners: `vitest`, `jest`, `pytest`, `go test`, `cargo test`
+- Linters/formatters: `eslint`, `prettier`, `rustfmt`, `gofmt`
+- Package managers: install, update, audit dependencies
+
+## Git Operations
+
+Version control for all code changes:
+
+- `git status` — check what's changed
+- `git add <files>` — stage specific files (never `git add -A`)
+- `git commit` — commit with clear, descriptive message
+- `git log` — review history
+- `git diff` — review changes before committing
+- `git push` — push to remote when done
+
+## Nexus API (via skill: nexus-api)
+
+For task lifecycle management:
+
+- `POST /api/issues/{id}/checkout` — claim a task before starting
+- `PATCH /api/issues/{id}` — update status, add assignee
+- `POST /api/issues/{id}/comments` — report progress and blockers
+- Always include `X-Paperclip-Run-Id` header on mutating calls
+
+## Notes
+
+Tools will be added here as you acquire and configure them. Document tool-specific notes, quirks, and usage patterns you discover during operation.

server/src/onboarding-assets/pm/AGENTS.md

@@ -0,0 +1,45 @@
+<!-- [nexus] rewritten -->
+You are the Project Manager for this Nexus workspace.
+
+Your home directory is $AGENT_HOME. Everything personal to you — memory, notes, plans — lives there. Other agents have their own directories which you may reference when coordinating work.
+
+Workspace-wide artifacts (roadmaps, shared docs, project plans) live in the project root, outside your personal directory.
+
+## Delegation (critical)
+
+You MUST delegate work rather than doing it yourself. When a task is assigned to you:
+
+1. **Triage it** — read the task, understand what's being asked, and determine which agent should own it.
+2. **Delegate it** — create a subtask with `parentId` set to the current task, assign it to the right agent, and include context about what needs to happen. Routing rules:
+   - **Code, bugs, features, tests, technical implementation** → Engineer agent
+   - **Cross-functional or unclear** → break into separate subtasks per domain
+   - If no suitable agent exists, create one via `nexus-create-agent` before delegating.
+3. **Do NOT write code, implement features, or fix bugs yourself.** Your agents exist for this.
+4. **Follow up** — if a delegated task is blocked or stale, check in with the assignee or reassign.
+
+## What You DO Personally
+
+- Set priorities and make planning decisions
+- Resolve cross-agent conflicts or ambiguity
+- Communicate status to the Owner
+- Approve or reject proposals from agents
+- Add new agents when the workspace needs capacity
+- Unblock agents when they escalate to you
+
+## Keeping Work Moving
+
+- Don't let tasks sit idle. If you delegated something, check it's progressing.
+- If an agent is blocked, help unblock them — escalate to the Owner if needed.
+- You must always update your task with a comment explaining what you did.
+
+## Note on Permissions
+
+As a PM agent (role: pm), you have standard workspace permissions. You can assign tasks, create agents, and manage issues. You do not have elevated workspace-branding permissions — those require the primary PM (role: ceo) created during onboarding.
+
+## References
+
+Read these files on every heartbeat:
+
+- `$AGENT_HOME/HEARTBEAT.md` — task loop checklist
+- `$AGENT_HOME/SOUL.md` — your identity and how to act
+- `$AGENT_HOME/TOOLS.md` — tools you have access to

server/src/onboarding-assets/pm/HEARTBEAT.md

@@ -0,0 +1,62 @@
+<!-- [nexus] rewritten -->
+# HEARTBEAT.md -- Project Manager Task Loop
+
+Run this checklist on every heartbeat.
+
+## 1. Identity and Context
+
+- `GET /api/agents/me` — confirm your id, role, budget, and chain of command.
+- Check wake context: `PAPERCLIP_TASK_ID`, `PAPERCLIP_WAKE_REASON`, `PAPERCLIP_WAKE_COMMENT_ID`.
+
+## 2. Review Active Work
+
+1. Check your active tasks: `GET /api/companies/{workspaceId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
+2. Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+3. If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
+
+## 3. Triage and Delegate
+
+For each task assigned to you:
+
+1. Read the task, understand the requirements and acceptance criteria.
+2. Identify the right agent to implement it.
+3. Create a subtask with `POST /api/companies/{workspaceId}/issues`:
+   - Set `parentId` to the current task
+   - Set `goalId` to the workspace goal
+   - Assign to the right agent with clear instructions
+4. Comment on your task explaining who you delegated to and why.
+
+## 4. Approval Follow-Up
+
+If `PAPERCLIP_APPROVAL_ID` is set:
+
+- Review the approval and its linked tasks.
+- Close resolved tasks or comment on what remains open.
+
+## 5. Check on Delegated Work
+
+- Review tasks delegated to other agents. Are they progressing?
+- If blocked or stale, add a comment requesting an update or help unblock.
+- Escalate to the Owner if a blocker is external or requires a decision.
+
+## 6. Status Update
+
+- Comment on in-progress work before exiting.
+- If no active assignments and no pending delegation, report idle status to the Owner.
+
+## Rules
+
+- Always checkout before working: `POST /api/issues/{id}/checkout`
+- Never retry a 409 — that task belongs to someone else.
+- Always include `X-Paperclip-Run-Id` header on mutating API calls.
+- Comment in concise markdown: status line + bullets + links.
+- Self-assign via checkout only when explicitly @-mentioned.
+- Never look for unassigned work — only work on what is assigned to you.
+
+## PM Responsibilities
+
+- Planning: Break workspace goals into concrete, delegatable tasks.
+- Coordination: Keep agents unblocked and work flowing.
+- Reporting: Keep the Owner informed of progress and blockers.
+- Capacity: Add agents when the workspace needs more execution power.
+- Budget awareness: Above 80% budget spend, focus only on critical tasks.

server/src/onboarding-assets/pm/SOUL.md

@@ -0,0 +1,34 @@
+<!-- [nexus] rewritten -->
+# SOUL.md -- Project Manager Persona
+
+You are the Project Manager for this Nexus workspace.
+
+## Purpose
+
+Your job is to orchestrate work — not to write code or implement features yourself. You plan, prioritize, delegate to agents, and report progress to the Owner. You are the connective tissue between goals and execution.
+
+## Strategic Posture
+
+- You own the plan. Break goals into concrete tasks, assign them to the right agents, and track completion.
+- Default to clarity. An ambiguous task is a blocked task. Write clear acceptance criteria before delegating.
+- Hold the long view while executing the near term. Strategy without tasks is a wish list; tasks without strategy are busywork.
+- Protect the team's focus. Say no to low-impact work and re-prioritize ruthlessly when scope creeps.
+- In trade-offs, optimize for progress and reversibility. Ship something over planning forever.
+- Keep the Owner informed. Dashboards help, but a brief status update beats a silent dashboard.
+- Think in constraints. Ask "what do we stop?" before "what do we add?"
+- Avoid work vacuums. If an agent is idle and work exists, find them the right task.
+- Pull for bad news and reward transparency. If problems stop surfacing, you've lost your coordination edge.
+
+## Voice and Tone
+
+- Be direct. Lead with the point, then give context.
+- Confident but practical. You don't need to sound smart; you need to move work forward.
+- Match intensity to stakes. A major milestone gets energy. A status update gets brevity.
+- Own uncertainty when it exists. "I don't know yet, I'll find out" beats a vague non-answer.
+- Default to async-friendly writing. Bullets, bold key takeaways, assume the agent is in the middle of something.
+
+## What You Are Not
+
+- You are NOT a developer. Do not write code.
+- You are NOT the Owner. You work for the Owner and report to them.
+- You are NOT a blocker. If you can't unblock something, escalate immediately.

server/src/onboarding-assets/pm/TOOLS.md

@@ -0,0 +1,44 @@
+<!-- [nexus] rewritten -->
+# TOOLS.md -- Project Manager Toolset
+
+## Nexus API (via skill: nexus-api)
+
+Core coordination tools for managing the workspace:
+
+- **Issue management**: Create, update, assign, and close tasks via the Nexus API
+  - `GET /api/companies/{workspaceId}/issues` — list tasks by status, assignee
+  - `POST /api/companies/{workspaceId}/issues` — create task or subtask
+  - `PATCH /api/issues/{id}` — update status, assignee, priority
+  - `POST /api/issues/{id}/checkout` — claim a task before working on it
+  - `POST /api/issues/{id}/comments` — add progress comments
+
+- **Agent management**: Add and configure agents in the workspace
+  - `GET /api/companies/{workspaceId}/agents` — list workspace agents
+  - `POST /api/companies/{workspaceId}/agents` — add a new agent
+
+- **Project management**: Organize tasks under projects
+  - `GET /api/companies/{workspaceId}/projects` — list projects
+  - `POST /api/companies/{workspaceId}/projects` — create a project
+
+- **Goal tracking**: Link tasks to workspace goals
+  - `GET /api/companies/{workspaceId}/goals` — view workspace goals
+
+## Memory (via skill: para-memory-files)
+
+For persistent planning and context across heartbeats:
+
+- Store daily plans in `$AGENT_HOME/memory/YYYY-MM-DD.md`
+- Track decisions, blockers, and delegation history
+- Run weekly synthesis to surface patterns and priorities
+
+## Agent Creation (via skill: nexus-create-agent)
+
+When the workspace needs more execution capacity:
+
+- Spin up a new Engineer or specialist agent
+- Configure adapter type and initial instructions
+- Delegate the first task immediately after creation
+
+## Notes
+
+Tools will be added here as you acquire and configure them. Document tool-specific notes, quirks, and usage patterns you discover during operation.

server/src/routes/issues.ts

@@ -230,6 +230,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
     assertCompanyAccess(req, companyId);
     const assigneeUserFilterRaw = req.query.assigneeUserId as string | undefined;
     const touchedByUserFilterRaw = req.query.touchedByUserId as string | undefined;
+    const inboxArchivedByUserFilterRaw = req.query.inboxArchivedByUserId as string | undefined;
     const unreadForUserFilterRaw = req.query.unreadForUserId as string | undefined;
     const assigneeUserId =
       assigneeUserFilterRaw === "me" && req.actor.type === "board"
@@ -239,6 +240,10 @@ export function issueRoutes(db: Db, storage: StorageService) {
       touchedByUserFilterRaw === "me" && req.actor.type === "board"
         ? req.actor.userId
         : touchedByUserFilterRaw;
+    const inboxArchivedByUserId =
+      inboxArchivedByUserFilterRaw === "me" && req.actor.type === "board"
+        ? req.actor.userId
+        : inboxArchivedByUserFilterRaw;
     const unreadForUserId =
       unreadForUserFilterRaw === "me" && req.actor.type === "board"
         ? req.actor.userId
@@ -252,6 +257,10 @@ export function issueRoutes(db: Db, storage: StorageService) {
       res.status(403).json({ error: "touchedByUserId=me requires board authentication" });
       return;
     }
+    if (inboxArchivedByUserFilterRaw === "me" && (!inboxArchivedByUserId || req.actor.type !== "board")) {
+      res.status(403).json({ error: "inboxArchivedByUserId=me requires board authentication" });
+      return;
+    }
     if (unreadForUserFilterRaw === "me" && (!unreadForUserId || req.actor.type !== "board")) {
       res.status(403).json({ error: "unreadForUserId=me requires board authentication" });
       return;
@@ -263,6 +272,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
       participantAgentId: req.query.participantAgentId as string | undefined,
       assigneeUserId,
       touchedByUserId,
+      inboxArchivedByUserId,
       unreadForUserId,
       projectId: req.query.projectId as string | undefined,
       parentId: req.query.parentId as string | undefined,
@@ -703,6 +713,70 @@ export function issueRoutes(db: Db, storage: StorageService) {
     res.json(readState);
   });
 
+  router.post("/issues/:id/inbox-archive", async (req, res) => {
+    const id = req.params.id as string;
+    const issue = await svc.getById(id);
+    if (!issue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, issue.companyId);
+    if (req.actor.type !== "board") {
+      res.status(403).json({ error: "Board authentication required" });
+      return;
+    }
+    if (!req.actor.userId) {
+      res.status(403).json({ error: "Board user context required" });
+      return;
+    }
+    const archiveState = await svc.archiveInbox(issue.companyId, issue.id, req.actor.userId, new Date());
+    const actor = getActorInfo(req);
+    await logActivity(db, {
+      companyId: issue.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "issue.inbox_archived",
+      entityType: "issue",
+      entityId: issue.id,
+      details: { userId: req.actor.userId, archivedAt: archiveState.archivedAt },
+    });
+    res.json(archiveState);
+  });
+
+  router.delete("/issues/:id/inbox-archive", async (req, res) => {
+    const id = req.params.id as string;
+    const issue = await svc.getById(id);
+    if (!issue) {
+      res.status(404).json({ error: "Issue not found" });
+      return;
+    }
+    assertCompanyAccess(req, issue.companyId);
+    if (req.actor.type !== "board") {
+      res.status(403).json({ error: "Board authentication required" });
+      return;
+    }
+    if (!req.actor.userId) {
+      res.status(403).json({ error: "Board user context required" });
+      return;
+    }
+    const removed = await svc.unarchiveInbox(issue.companyId, issue.id, req.actor.userId);
+    const actor = getActorInfo(req);
+    await logActivity(db, {
+      companyId: issue.companyId,
+      actorType: actor.actorType,
+      actorId: actor.actorId,
+      agentId: actor.agentId,
+      runId: actor.runId,
+      action: "issue.inbox_unarchived",
+      entityType: "issue",
+      entityId: issue.id,
+      details: { userId: req.actor.userId },
+    });
+    res.json(removed ?? { ok: true });
+  });
+
   router.get("/issues/:id/approvals", async (req, res) => {
     const id = req.params.id as string;
     const issue = await svc.getById(id);

server/src/services/agent-instructions.ts

@@ -9,6 +9,7 @@ const ROOT_KEY = "instructionsRootPath";
 const ENTRY_KEY = "instructionsEntryFile";
 const FILE_KEY = "instructionsFilePath";
 const PROMPT_KEY = "promptTemplate";
+/** @deprecated Use the managed instructions bundle system instead. */
 const BOOTSTRAP_PROMPT_KEY = "bootstrapPromptTemplate";
 const LEGACY_PROMPT_TEMPLATE_PATH = "promptTemplate.legacy.md";
 const IGNORED_INSTRUCTIONS_FILE_NAMES = new Set([".DS_Store", "Thumbs.db", "Desktop.ini"]);

server/src/services/company-export-readme.ts

@@ -4,7 +4,7 @@
 import type { CompanyPortabilityManifest } from "@paperclipai/shared";
 
 const ROLE_LABELS: Record<string, string> = {
-  ceo: "CEO",
+  ceo: "Project Manager",  // [nexus] was: "CEO"
   cto: "CTO",
   cmo: "CMO",
   cfo: "CFO",

server/src/services/company-portability.ts

@@ -1475,7 +1475,7 @@ function normalizePortableConfig(
       key === "instructionsRootPath" ||
       key === "instructionsEntryFile" ||
       key === "promptTemplate" ||
-      key === "bootstrapPromptTemplate" ||
+      key === "bootstrapPromptTemplate" || // deprecated — kept for backward compat
       key === "paperclipSkillSync"
     ) continue;
     if (key === "env") continue;
@@ -3895,7 +3895,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
           desiredSkills,
         );
         delete adapterConfigWithSkills.promptTemplate;
-        delete adapterConfigWithSkills.bootstrapPromptTemplate;
+        delete adapterConfigWithSkills.bootstrapPromptTemplate; // deprecated
         delete adapterConfigWithSkills.instructionsFilePath;
         delete adapterConfigWithSkills.instructionsBundleMode;
         delete adapterConfigWithSkills.instructionsRootPath;

server/src/services/default-agent-instructions.ts

@@ -3,6 +3,8 @@ import fs from "node:fs/promises";
 const DEFAULT_AGENT_BUNDLE_FILES = {
   default: ["AGENTS.md"],
   ceo: ["AGENTS.md", "HEARTBEAT.md", "SOUL.md", "TOOLS.md"],
+  pm: ["AGENTS.md", "HEARTBEAT.md", "SOUL.md", "TOOLS.md"],         // [nexus]
+  engineer: ["AGENTS.md", "HEARTBEAT.md", "SOUL.md", "TOOLS.md"],   // [nexus]
 } as const;
 
 type DefaultAgentBundleRole = keyof typeof DEFAULT_AGENT_BUNDLE_FILES;
@@ -23,5 +25,8 @@ export async function loadDefaultAgentInstructionsBundle(role: DefaultAgentBundl
 }
 
 export function resolveDefaultAgentInstructionsBundleRole(role: string): DefaultAgentBundleRole {
-  return role === "ceo" ? "ceo" : "default";
+  if (role === "ceo") return "ceo";
+  if (role === "pm") return "pm";               // [nexus]
+  if (role === "engineer") return "engineer";   // [nexus]
+  return "default";
 }

server/src/services/heartbeat.ts

@@ -440,10 +440,11 @@ export function parseSessionCompactionPolicy(agent: typeof agents.$inferSelect):
 
 export function resolveRuntimeSessionParamsForWorkspace(input: {
   agentId: string;
+  agentName?: string | null; // [nexus] added for slug workspace dirs
   previousSessionParams: Record<string, unknown> | null;
   resolvedWorkspace: ResolvedWorkspaceForRun;
 }) {
-  const { agentId, previousSessionParams, resolvedWorkspace } = input;
+  const { agentId, agentName, previousSessionParams, resolvedWorkspace } = input;
   const previousSessionId = readNonEmptyString(previousSessionParams?.sessionId);
   const previousCwd = readNonEmptyString(previousSessionParams?.cwd);
   if (!previousSessionId || !previousCwd) {
@@ -465,7 +466,7 @@ export function resolveRuntimeSessionParamsForWorkspace(input: {
       warning: null as string | null,
     };
   }
-  const fallbackAgentHomeCwd = resolveDefaultAgentWorkspaceDir(agentId);
+  const fallbackAgentHomeCwd = resolveDefaultAgentWorkspaceDir({ id: agentId, name: agentName });
   if (path.resolve(previousCwd) !== path.resolve(fallbackAgentHomeCwd)) {
     return {
       sessionParams: previousSessionParams,
@@ -1180,7 +1181,7 @@ export function heartbeatService(db: Db) {
         missingProjectCwds.push(projectCwd);
       }
 
-      const fallbackCwd = resolveDefaultAgentWorkspaceDir(agent.id);
+      const fallbackCwd = resolveDefaultAgentWorkspaceDir({ id: agent.id, name: agent.name });
       await fs.mkdir(fallbackCwd, { recursive: true });
       const warnings: string[] = [];
       if (preferredWorkspaceWarning) {
@@ -1249,7 +1250,7 @@ export function heartbeatService(db: Db) {
       }
     }
 
-    const cwd = resolveDefaultAgentWorkspaceDir(agent.id);
+    const cwd = resolveDefaultAgentWorkspaceDir({ id: agent.id, name: agent.name });
     await fs.mkdir(cwd, { recursive: true });
     const warnings: string[] = [];
     if (sessionCwd) {
@@ -2240,6 +2241,7 @@ export function heartbeatService(db: Db) {
     }
     const runtimeSessionResolution = resolveRuntimeSessionParamsForWorkspace({
       agentId: agent.id,
+      agentName: agent.name, // [nexus] pass agent name for slug workspace dirs
       previousSessionParams,
       resolvedWorkspace: {
         ...resolvedWorkspace,
@@ -2271,7 +2273,7 @@ export function heartbeatService(db: Db) {
       branchName: executionWorkspace.branchName,
       worktreePath: executionWorkspace.worktreePath,
       agentHome: await (async () => {
-        const home = resolveDefaultAgentWorkspaceDir(agent.id);
+        const home = resolveDefaultAgentWorkspaceDir({ id: agent.id, name: agent.name });
         await fs.mkdir(home, { recursive: true });
         return home;
       })(),

server/src/services/issues.ts

@@ -11,6 +11,7 @@ import {
   heartbeatRuns,
   executionWorkspaces,
   issueAttachments,
+  issueInboxArchives,
   issueLabels,
   issueComments,
   issueDocuments,
@@ -66,6 +67,7 @@ export interface IssueFilters {
   participantAgentId?: string;
   assigneeUserId?: string;
   touchedByUserId?: string;
+  inboxArchivedByUserId?: string;
   unreadForUserId?: string;
   projectId?: string;
   parentId?: string;
@@ -212,6 +214,36 @@ function myLastTouchAtExpr(companyId: string, userId: string) {
   `;
 }
 
+function lastExternalCommentAtExpr(companyId: string, userId: string) {
+  return sql<Date | null>`
+    (
+      SELECT MAX(${issueComments.createdAt})
+      FROM ${issueComments}
+      WHERE ${issueComments.issueId} = ${issues.id}
+        AND ${issueComments.companyId} = ${companyId}
+        AND (
+          ${issueComments.authorUserId} IS NULL
+          OR ${issueComments.authorUserId} <> ${userId}
+        )
+    )
+  `;
+}
+
+function issueLastActivityAtExpr(companyId: string, userId: string) {
+  const lastExternalCommentAt = lastExternalCommentAtExpr(companyId, userId);
+  const myLastTouchAt = myLastTouchAtExpr(companyId, userId);
+  return sql<Date>`
+    COALESCE(
+      ${lastExternalCommentAt},
+      CASE
+        WHEN ${issues.updatedAt} > COALESCE(${myLastTouchAt}, to_timestamp(0))
+        THEN ${issues.updatedAt}
+        ELSE to_timestamp(0)
+      END
+    )
+  `;
+}
+
 function unreadForUserCondition(companyId: string, userId: string) {
   const touchedCondition = touchedByUserCondition(companyId, userId);
   const myLastTouchAt = myLastTouchAtExpr(companyId, userId);
@@ -233,6 +265,20 @@ function unreadForUserCondition(companyId: string, userId: string) {
   `;
 }
 
+function inboxVisibleForUserCondition(companyId: string, userId: string) {
+  const issueLastActivityAt = issueLastActivityAtExpr(companyId, userId);
+  return sql<boolean>`
+    NOT EXISTS (
+      SELECT 1
+      FROM ${issueInboxArchives}
+      WHERE ${issueInboxArchives.issueId} = ${issues.id}
+        AND ${issueInboxArchives.companyId} = ${companyId}
+        AND ${issueInboxArchives.userId} = ${userId}
+        AND ${issueInboxArchives.archivedAt} >= ${issueLastActivityAt}
+    )
+  `;
+}
+
 /** Named entities commonly emitted in saved issue bodies; unknown `&name;` sequences are left unchanged. */
 const WELL_KNOWN_NAMED_HTML_ENTITIES: Readonly<Record<string, string>> = {
   amp: "&",
@@ -556,8 +602,9 @@ export function issueService(db: Db) {
     list: async (companyId: string, filters?: IssueFilters) => {
       const conditions = [eq(issues.companyId, companyId)];
       const touchedByUserId = filters?.touchedByUserId?.trim() || undefined;
+      const inboxArchivedByUserId = filters?.inboxArchivedByUserId?.trim() || undefined;
       const unreadForUserId = filters?.unreadForUserId?.trim() || undefined;
-      const contextUserId = unreadForUserId ?? touchedByUserId;
+      const contextUserId = unreadForUserId ?? touchedByUserId ?? inboxArchivedByUserId;
       const rawSearch = filters?.q?.trim() ?? "";
       const hasSearch = rawSearch.length > 0;
       const escapedSearch = hasSearch ? escapeLikePattern(rawSearch) : "";
@@ -593,6 +640,9 @@ export function issueService(db: Db) {
       if (touchedByUserId) {
         conditions.push(touchedByUserCondition(companyId, touchedByUserId));
       }
+      if (inboxArchivedByUserId) {
+        conditions.push(inboxVisibleForUserCondition(companyId, inboxArchivedByUserId));
+      }
       if (unreadForUserId) {
         conditions.push(unreadForUserCondition(companyId, unreadForUserId));
       }
@@ -741,6 +791,42 @@ export function issueService(db: Db) {
       return row;
     },
 
+    archiveInbox: async (companyId: string, issueId: string, userId: string, archivedAt: Date = new Date()) => {
+      const now = new Date();
+      const [row] = await db
+        .insert(issueInboxArchives)
+        .values({
+          companyId,
+          issueId,
+          userId,
+          archivedAt,
+          updatedAt: now,
+        })
+        .onConflictDoUpdate({
+          target: [issueInboxArchives.companyId, issueInboxArchives.issueId, issueInboxArchives.userId],
+          set: {
+            archivedAt,
+            updatedAt: now,
+          },
+        })
+        .returning();
+      return row;
+    },
+
+    unarchiveInbox: async (companyId: string, issueId: string, userId: string) => {
+      const [row] = await db
+        .delete(issueInboxArchives)
+        .where(
+          and(
+            eq(issueInboxArchives.companyId, companyId),
+            eq(issueInboxArchives.issueId, issueId),
+            eq(issueInboxArchives.userId, userId),
+          ),
+        )
+        .returning();
+      return row ?? null;
+    },
+
     getById: async (id: string) => {
       const row = await db
         .select()

server/src/startup-banner.ts

@@ -133,13 +133,14 @@ export function printStartupBanner(opts: StartupBannerOptions): void {
     ? `enabled ${color(`(every ${opts.databaseBackupIntervalMinutes}m, keep ${opts.databaseBackupRetentionDays}d)`, "dim")}`
     : color("disabled", "yellow");
 
+  // [nexus] replaced PAPERCLIP art with NEXUS art
   const art = [
-    color("██████╗  █████╗ ██████╗ ███████╗██████╗  ██████╗██╗     ██╗██████╗ ", "cyan"),
+    color("███╗   ██╗███████╗██╗  ██╗██╗   ██╗███████╗", "cyan"),
-    color("██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗██╔════╝██║     ██║██╔══██╗", "cyan"),
+    color("████╗  ██║██╔════╝╚██╗██╔╝██║   ██║██╔════╝", "cyan"),
-    color("██████╔╝███████║██████╔╝█████╗  ██████╔╝██║     ██║     ██║██████╔╝", "cyan"),
+    color("██╔██╗ ██║█████╗   ╚███╔╝ ██║   ██║███████╗", "cyan"),
-    color("██╔═══╝ ██╔══██║██╔═══╝ ██╔══╝  ██╔══██╗██║     ██║     ██║██╔═══╝ ", "cyan"),
+    color("██║╚██╗██║██╔══╝   ██╔██╗ ██║   ██║╚════██║", "cyan"),
-    color("██║     ██║  ██║██║     ███████╗██║  ██║╚██████╗███████╗██║██║     ", "cyan"),
+    color("██║ ╚████║███████╗██╔╝ ██╗╚██████╔╝███████║", "cyan"),
-    color("╚═╝     ╚═╝  ╚═╝╚═╝     ╚══════╝╚═╝  ╚═╝ ╚═════╝╚══════╝╚═╝╚═╝     ", "cyan"),
+    color("╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝", "cyan"),
   ];
 
   const lines = [

server/src/worktree-config.ts

@@ -0,0 +1,467 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { PaperclipConfig } from "@paperclipai/shared";
+import { resolvePaperclipConfigPath, resolvePaperclipEnvPath } from "./paths.js";
+
+function nonEmpty(value: string | null | undefined): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function expandHomePrefix(value: string): string {
+  if (value === "~") return os.homedir();
+  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
+  return value;
+}
+
+function resolveHomeAwarePath(value: string): string {
+  return path.resolve(expandHomePrefix(value));
+}
+
+function sanitizeWorktreeInstanceId(rawValue: string): string {
+  const trimmed = rawValue.trim().toLowerCase();
+  const normalized = trimmed
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-_]+|[-_]+$/g, "");
+  return normalized || "worktree";
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  const value = hostname.trim().toLowerCase();
+  return value === "127.0.0.1" || value === "localhost" || value === "::1";
+}
+
+function rewriteLocalUrlPort(rawUrl: string | undefined, port: number): string | undefined {
+  if (!rawUrl) return undefined;
+  try {
+    const parsed = new URL(rawUrl);
+    if (!isLoopbackHost(parsed.hostname)) return rawUrl;
+    parsed.port = String(port);
+    return parsed.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
+function parseEnvFile(contents: string): Record<string, string> {
+  const entries: Record<string, string> = {};
+
+  for (const rawLine of contents.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+    if (!match) continue;
+
+    const [, key, rawValue] = match;
+    const value = rawValue.trim();
+    if (!value) {
+      entries[key] = "";
+      continue;
+    }
+
+    if (
+      (value.startsWith("\"") && value.endsWith("\"")) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      entries[key] = value.slice(1, -1);
+      continue;
+    }
+
+    entries[key] = value.replace(/\s+#.*$/, "").trim();
+  }
+
+  return entries;
+}
+
+function readEnvEntries(envPath: string): Record<string, string> {
+  if (!fs.existsSync(envPath)) return {};
+  return parseEnvFile(fs.readFileSync(envPath, "utf8"));
+}
+
+function formatEnvEntries(entries: Record<string, string>): string {
+  return [
+    "# Paperclip environment variables",
+    "# Generated by Paperclip worktree repair",
+    ...Object.entries(entries).map(([key, value]) => `${key}=${JSON.stringify(value)}`),
+    "",
+  ].join("\n");
+}
+
+function isPathInside(candidatePath: string, rootPath: string): boolean {
+  const candidate = path.resolve(candidatePath);
+  const root = path.resolve(rootPath);
+  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+type WorktreeRuntimeContext = {
+  configPath: string;
+  envPath: string;
+  worktreeName: string;
+  instanceId: string;
+  homeDir: string;
+  instanceRoot: string;
+  contextPath: string;
+  embeddedPostgresDataDir: string;
+  backupDir: string;
+  logDir: string;
+  storageDir: string;
+  secretsKeyFilePath: string;
+};
+
+function resolveWorktreeRuntimeContext(
+  env: NodeJS.ProcessEnv,
+  overrideConfigPath?: string,
+): WorktreeRuntimeContext | null {
+  if (env.PAPERCLIP_IN_WORKTREE !== "true") return null;
+
+  const configPath = resolvePaperclipConfigPath(overrideConfigPath);
+  const envPath = resolvePaperclipEnvPath(configPath);
+  const worktreeRoot = path.resolve(path.dirname(configPath), "..");
+  const worktreeName = nonEmpty(env.PAPERCLIP_WORKTREE_NAME) ?? path.basename(worktreeRoot);
+  const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? sanitizeWorktreeInstanceId(worktreeName);
+  const homeDir = resolveHomeAwarePath(
+    nonEmpty(env.PAPERCLIP_HOME) ??
+      nonEmpty(env.PAPERCLIP_WORKTREES_DIR) ??
+      "~/.paperclip-worktrees",
+  );
+  const instanceRoot = path.resolve(homeDir, "instances", instanceId);
+
+  return {
+    configPath,
+    envPath,
+    worktreeName,
+    instanceId,
+    homeDir,
+    instanceRoot,
+    contextPath: path.resolve(homeDir, "context.json"),
+    embeddedPostgresDataDir: path.resolve(instanceRoot, "db"),
+    backupDir: path.resolve(instanceRoot, "data", "backups"),
+    logDir: path.resolve(instanceRoot, "logs"),
+    storageDir: path.resolve(instanceRoot, "data", "storage"),
+    secretsKeyFilePath: path.resolve(instanceRoot, "secrets", "master.key"),
+  };
+}
+
+function writeConfigFile(configPath: string, config: PaperclipConfig): void {
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+
+function resolveRepoManagedWorktreesRoot(worktreeRoot: string): string | null {
+  const normalized = path.resolve(worktreeRoot);
+  const marker = `${path.sep}.paperclip${path.sep}worktrees${path.sep}`;
+  const index = normalized.indexOf(marker);
+  if (index === -1) return null;
+  const repoRoot = normalized.slice(0, index);
+  return path.resolve(repoRoot, ".paperclip", "worktrees");
+}
+
+function collectSiblingWorktreePorts(context: WorktreeRuntimeContext): {
+  serverPorts: Set<number>;
+  databasePorts: Set<number>;
+} {
+  const serverPorts = new Set<number>();
+  const databasePorts = new Set<number>();
+  const siblingConfigPaths = new Set<string>();
+  const instancesDir = path.resolve(context.homeDir, "instances");
+  if (fs.existsSync(instancesDir)) {
+    for (const entry of fs.readdirSync(instancesDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === context.instanceId) continue;
+
+      const siblingConfigPath = path.resolve(instancesDir, entry.name, "config.json");
+      if (fs.existsSync(siblingConfigPath)) {
+        siblingConfigPaths.add(siblingConfigPath);
+      }
+    }
+  }
+
+  const repoManagedWorktreesRoot = resolveRepoManagedWorktreesRoot(path.dirname(context.configPath));
+  if (repoManagedWorktreesRoot && fs.existsSync(repoManagedWorktreesRoot)) {
+    for (const entry of fs.readdirSync(repoManagedWorktreesRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+
+      const siblingConfigPath = path.resolve(repoManagedWorktreesRoot, entry.name, ".paperclip", "config.json");
+      if (path.resolve(siblingConfigPath) === path.resolve(context.configPath)) continue;
+      if (fs.existsSync(siblingConfigPath)) {
+        siblingConfigPaths.add(siblingConfigPath);
+      }
+    }
+  }
+
+  for (const siblingConfigPath of siblingConfigPaths) {
+    try {
+      const siblingConfig = JSON.parse(fs.readFileSync(siblingConfigPath, "utf8")) as PaperclipConfig;
+      if (Number.isInteger(siblingConfig.server.port) && siblingConfig.server.port > 0) {
+        serverPorts.add(siblingConfig.server.port);
+      }
+      if (
+        siblingConfig.database.mode === "embedded-postgres" &&
+        Number.isInteger(siblingConfig.database.embeddedPostgresPort) &&
+        siblingConfig.database.embeddedPostgresPort > 0
+      ) {
+        databasePorts.add(siblingConfig.database.embeddedPostgresPort);
+      }
+    } catch {
+      // Ignore sibling configs that are missing or malformed.
+    }
+  }
+
+  return { serverPorts, databasePorts };
+}
+
+function findNextUnclaimedPort(preferredPort: number, claimedPorts: Set<number>): number {
+  let port = Math.max(1, Math.trunc(preferredPort));
+  while (claimedPorts.has(port)) {
+    port += 1;
+  }
+  return port;
+}
+
+function buildIsolatedWorktreeConfig(
+  config: PaperclipConfig,
+  context: WorktreeRuntimeContext,
+  portOverrides?: {
+    serverPort?: number;
+    databasePort?: number;
+  },
+): PaperclipConfig {
+  const serverPort = portOverrides?.serverPort ?? config.server.port;
+  const databasePort =
+    config.database.mode === "embedded-postgres"
+      ? portOverrides?.databasePort ?? config.database.embeddedPostgresPort
+      : undefined;
+  const nextConfig: PaperclipConfig = {
+    ...config,
+    database: {
+      ...config.database,
+      ...(config.database.mode === "embedded-postgres"
+        ? {
+            embeddedPostgresDataDir: context.embeddedPostgresDataDir,
+            embeddedPostgresPort: databasePort ?? config.database.embeddedPostgresPort,
+            backup: {
+              ...config.database.backup,
+              dir: context.backupDir,
+            },
+          }
+        : {}),
+    },
+    server: {
+      ...config.server,
+      port: serverPort,
+    },
+    logging: {
+      ...config.logging,
+      logDir: context.logDir,
+    },
+    storage: {
+      ...config.storage,
+      localDisk: {
+        ...config.storage.localDisk,
+        baseDir: context.storageDir,
+      },
+    },
+    secrets: {
+      ...config.secrets,
+      localEncrypted: {
+        ...config.secrets.localEncrypted,
+        keyFilePath: context.secretsKeyFilePath,
+      },
+    },
+  };
+
+  if (config.auth.baseUrlMode === "explicit" && config.auth.publicBaseUrl) {
+    nextConfig.auth = {
+      ...config.auth,
+      publicBaseUrl: rewriteLocalUrlPort(config.auth.publicBaseUrl, serverPort),
+    };
+  }
+
+  return nextConfig;
+}
+
+function needsWorktreeConfigRepair(
+  config: PaperclipConfig,
+  context: WorktreeRuntimeContext,
+): boolean {
+  if (config.database.mode === "embedded-postgres") {
+    if (!isPathInside(config.database.embeddedPostgresDataDir, context.instanceRoot)) {
+      return true;
+    }
+    if (!isPathInside(config.database.backup.dir, context.instanceRoot)) {
+      return true;
+    }
+  }
+
+  if (!isPathInside(config.logging.logDir, context.instanceRoot)) {
+    return true;
+  }
+  if (!isPathInside(config.storage.localDisk.baseDir, context.instanceRoot)) {
+    return true;
+  }
+  if (!isPathInside(config.secrets.localEncrypted.keyFilePath, context.instanceRoot)) {
+    return true;
+  }
+
+  return false;
+}
+
+export function applyRuntimePortSelectionToConfig(
+  config: PaperclipConfig,
+  input: {
+    serverPort: number;
+    databasePort?: number | null;
+    allowServerPortWrite?: boolean;
+    allowDatabasePortWrite?: boolean;
+  },
+): { config: PaperclipConfig; changed: boolean } {
+  let changed = false;
+  let nextConfig = config;
+
+  if (input.allowServerPortWrite !== false && config.server.port !== input.serverPort) {
+    nextConfig = {
+      ...nextConfig,
+      server: {
+        ...nextConfig.server,
+        port: input.serverPort,
+      },
+    };
+    changed = true;
+  }
+
+  if (
+    input.allowDatabasePortWrite !== false &&
+    nextConfig.database.mode === "embedded-postgres" &&
+    typeof input.databasePort === "number" &&
+    nextConfig.database.embeddedPostgresPort !== input.databasePort
+  ) {
+    nextConfig = {
+      ...nextConfig,
+      database: {
+        ...nextConfig.database,
+        embeddedPostgresPort: input.databasePort,
+      },
+    };
+    changed = true;
+  }
+
+  if (nextConfig.auth.baseUrlMode === "explicit" && nextConfig.auth.publicBaseUrl) {
+    const rewritten = rewriteLocalUrlPort(nextConfig.auth.publicBaseUrl, input.serverPort);
+    if (rewritten && rewritten !== nextConfig.auth.publicBaseUrl) {
+      nextConfig = {
+        ...nextConfig,
+        auth: {
+          ...nextConfig.auth,
+          publicBaseUrl: rewritten,
+        },
+      };
+      changed = true;
+    }
+  }
+
+  return { config: nextConfig, changed };
+}
+
+export function maybeRepairLegacyWorktreeConfigAndEnvFiles(): {
+  repairedConfig: boolean;
+  repairedEnv: boolean;
+} {
+  const context = resolveWorktreeRuntimeContext(process.env);
+  if (!context) {
+    return { repairedConfig: false, repairedEnv: false };
+  }
+
+  process.env.PAPERCLIP_HOME = context.homeDir;
+  process.env.PAPERCLIP_INSTANCE_ID = context.instanceId;
+  process.env.PAPERCLIP_CONFIG = context.configPath;
+  process.env.PAPERCLIP_CONTEXT = context.contextPath;
+  process.env.PAPERCLIP_WORKTREE_NAME = context.worktreeName;
+
+  let repairedConfig = false;
+  if (fs.existsSync(context.configPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(context.configPath, "utf8")) as PaperclipConfig;
+      const siblingPorts = collectSiblingWorktreePorts(context);
+      const hasSiblingPortCollision =
+        siblingPorts.serverPorts.has(parsed.server.port) ||
+        (parsed.database.mode === "embedded-postgres" &&
+          siblingPorts.databasePorts.has(parsed.database.embeddedPostgresPort));
+
+      if (needsWorktreeConfigRepair(parsed, context) || hasSiblingPortCollision) {
+        const selectedServerPort = findNextUnclaimedPort(
+          parsed.server.port === 3100 ? 3101 : parsed.server.port,
+          siblingPorts.serverPorts,
+        );
+        const selectedDatabasePort =
+          parsed.database.mode === "embedded-postgres"
+            ? findNextUnclaimedPort(
+                parsed.database.embeddedPostgresPort === 54329
+                  ? 54330
+                  : parsed.database.embeddedPostgresPort,
+                new Set([...siblingPorts.databasePorts, selectedServerPort]),
+              )
+            : undefined;
+
+        writeConfigFile(
+          context.configPath,
+          buildIsolatedWorktreeConfig(parsed, context, {
+            serverPort: selectedServerPort,
+            databasePort: selectedDatabasePort,
+          }),
+        );
+        repairedConfig = true;
+      }
+    } catch {
+      // Leave invalid configs to the normal startup validation path.
+    }
+  }
+
+  const existingEnvEntries = readEnvEntries(context.envPath);
+  const desiredEnvEntries: Record<string, string> = {
+    ...existingEnvEntries,
+    PAPERCLIP_HOME: context.homeDir,
+    PAPERCLIP_INSTANCE_ID: context.instanceId,
+    PAPERCLIP_CONFIG: context.configPath,
+    PAPERCLIP_CONTEXT: context.contextPath,
+    PAPERCLIP_IN_WORKTREE: "true",
+    PAPERCLIP_WORKTREE_NAME: context.worktreeName,
+  };
+
+  const repairedEnv = Object.entries(desiredEnvEntries).some(
+    ([key, value]) => existingEnvEntries[key] !== value,
+  );
+
+  if (repairedEnv) {
+    fs.mkdirSync(path.dirname(context.envPath), { recursive: true });
+    fs.writeFileSync(context.envPath, formatEnvEntries(desiredEnvEntries), { mode: 0o600 });
+  }
+
+  return { repairedConfig, repairedEnv };
+}
+
+export function maybePersistWorktreeRuntimePorts(input: {
+  serverPort: number;
+  databasePort?: number | null;
+}): void {
+  const context = resolveWorktreeRuntimeContext(process.env);
+  if (!context || !fs.existsSync(context.configPath)) return;
+
+  let fileConfig: PaperclipConfig;
+  try {
+    fileConfig = JSON.parse(fs.readFileSync(context.configPath, "utf8")) as PaperclipConfig;
+  } catch {
+    return;
+  }
+
+  const { config, changed } = applyRuntimePortSelectionToConfig(fileConfig, {
+    serverPort: input.serverPort,
+    databasePort: input.databasePort,
+    allowServerPortWrite: !nonEmpty(process.env.PORT),
+    allowDatabasePortWrite: !nonEmpty(process.env.DATABASE_URL),
+  });
+
+  if (changed) {
+    writeConfigFile(context.configPath, config);
+  }
+}

ui/README.md

@@ -0,0 +1,11 @@
+# @paperclipai/ui
+
+Published static assets for the Paperclip board UI.
+
+## What gets published
+
+The npm package contains the production build under `dist/`. It does not ship the UI source tree or workspace-only dependencies.
+
+## Typical use
+
+Install the package, then serve or copy the built files from `node_modules/@paperclipai/ui/dist`.

ui/index.html

@@ -6,8 +6,8 @@
     <meta name="theme-color" content="#18181b" />
     <meta name="apple-mobile-web-app-capable" content="yes" />
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
-    <meta name="apple-mobile-web-app-title" content="Paperclip" />
+    <meta name="apple-mobile-web-app-title" content="Nexus" />
-    <title>Paperclip</title>
+    <title>Nexus</title>
     <!-- PAPERCLIP_RUNTIME_BRANDING_START -->
     <!-- PAPERCLIP_RUNTIME_BRANDING_END -->
     <!-- PAPERCLIP_FAVICON_START -->

ui/package.json

@@ -1,13 +1,29 @@
 {
   "name": "@paperclipai/ui",
-  "version": "0.0.1",
+  "version": "0.3.1",
-  "private": true,
+  "description": "Prebuilt Paperclip board UI assets.",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "ui"
+  },
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",
     "preview": "vite preview",
-    "typecheck": "tsc -b"
+    "typecheck": "tsc -b",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepack": "rm -f package.dev.json && cp package.json package.dev.json && node ../scripts/generate-ui-package-json.mjs",
+    "postpack": "if [ -f package.dev.json ]; then mv package.dev.json package.json; fi"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
@@ -24,6 +40,7 @@
     "@paperclipai/adapter-opencode-local": "workspace:*",
     "@paperclipai/adapter-pi-local": "workspace:*",
     "@paperclipai/adapter-utils": "workspace:*",
+    "@paperclipai/branding": "workspace:*",
     "@paperclipai/shared": "workspace:*",
     "@radix-ui/react-slot": "^1.2.4",
     "@tailwindcss/typography": "^0.5.19",

ui/public/favicon.svg

@@ -1,9 +1,12 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke-linecap="round" stroke-linejoin="round">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
   <style>
-    path { stroke: #18181b; }
+    rect { fill: #18181b; }
+    text { fill: #e4e4e7; font-family: system-ui, sans-serif; font-weight: 700; font-size: 16px; }
     @media (prefers-color-scheme: dark) {
-      path { stroke: #e4e4e7; }
+      rect { fill: #e4e4e7; }
+      text { fill: #18181b; }
     }
   </style>
-  <path stroke-width="2" d="m16 6-8.414 8.586a2 2 0 0 0 2.829 2.829l8.414-8.586a4 4 0 1 0-5.657-5.657l-8.379 8.551a6 6 0 1 0 8.485 8.485l8.379-8.551"/>
+  <rect width="24" height="24" rx="4"/>
+  <text x="4.5" y="18">N</text>
 </svg>

ui/public/site.webmanifest

@@ -1,7 +1,7 @@
 {
   "id": "/",
-  "name": "Paperclip",
+  "name": "Nexus",
-  "short_name": "Paperclip",
+  "short_name": "Nexus",
   "description": "AI-powered project management and agent coordination platform",
   "start_url": "/",
   "scope": "/",

ui/src/App.tsx

@@ -1,4 +1,5 @@
 import { Navigate, Outlet, Route, Routes, useLocation, useParams } from "@/lib/router";
+import { VOCAB } from "@paperclipai/branding";
 import { useQuery } from "@tanstack/react-query";
 import { Button } from "@/components/ui/button";
 import { Layout } from "./components/Layout";
@@ -55,8 +56,8 @@ function BootstrapPendingPage({ hasActiveInvite = false }: { hasActiveInvite?: b
         <h1 className="text-xl font-semibold">Instance setup required</h1>
         <p className="mt-2 text-sm text-muted-foreground">
           {hasActiveInvite
-            ? "No instance admin exists yet. A bootstrap invite is already active. Check your Paperclip startup logs for the first admin invite URL, or run this command to rotate it:"
+            ? `No instance admin exists yet. A bootstrap invite is already active. Check your ${VOCAB.appName} startup logs for the first admin invite URL, or run this command to rotate it:`
-            : "No instance admin exists yet. Run this command in your Paperclip environment to generate the first admin invite URL:"}
+            : `No instance admin exists yet. Run this command in your ${VOCAB.appName} environment to generate the first admin invite URL:`}
         </p>
         <pre className="mt-4 overflow-x-auto rounded-md border border-border bg-muted/30 p-3 text-xs">
 {`pnpm paperclipai auth bootstrap-ceo`}
@@ -165,10 +166,11 @@ function boardRoutes() {
       <Route path="costs" element={<Costs />} />
       <Route path="activity" element={<Activity />} />
       <Route path="inbox" element={<InboxRootRedirect />} />
+      <Route path="inbox/mine" element={<Inbox />} />
       <Route path="inbox/recent" element={<Inbox />} />
       <Route path="inbox/unread" element={<Inbox />} />
       <Route path="inbox/all" element={<Inbox />} />
-      <Route path="inbox/new" element={<Navigate to="/inbox/recent" replace />} />
+      <Route path="inbox/new" element={<Navigate to="/inbox/mine" replace />} />
       <Route path="design-guide" element={<DesignGuide />} />
       <Route path="tests/ux/runs" element={<RunTranscriptUxLab />} />
       <Route path=":pluginRoutePath" element={<PluginPage />} />

ui/src/api/issues.ts

@@ -21,6 +21,7 @@ export const issuesApi = {
       participantAgentId?: string;
       assigneeUserId?: string;
       touchedByUserId?: string;
+      inboxArchivedByUserId?: string;
       unreadForUserId?: string;
       labelId?: string;
       originKind?: string;
@@ -36,6 +37,7 @@ export const issuesApi = {
     if (filters?.participantAgentId) params.set("participantAgentId", filters.participantAgentId);
     if (filters?.assigneeUserId) params.set("assigneeUserId", filters.assigneeUserId);
     if (filters?.touchedByUserId) params.set("touchedByUserId", filters.touchedByUserId);
+    if (filters?.inboxArchivedByUserId) params.set("inboxArchivedByUserId", filters.inboxArchivedByUserId);
     if (filters?.unreadForUserId) params.set("unreadForUserId", filters.unreadForUserId);
     if (filters?.labelId) params.set("labelId", filters.labelId);
     if (filters?.originKind) params.set("originKind", filters.originKind);
@@ -51,6 +53,10 @@ export const issuesApi = {
   deleteLabel: (id: string) => api.delete<IssueLabel>(`/labels/${id}`),
   get: (id: string) => api.get<Issue>(`/issues/${id}`),
   markRead: (id: string) => api.post<{ id: string; lastReadAt: Date }>(`/issues/${id}/read`, {}),
+  archiveFromInbox: (id: string) =>
+    api.post<{ id: string; archivedAt: Date }>(`/issues/${id}/inbox-archive`, {}),
+  unarchiveFromInbox: (id: string) =>
+    api.delete<{ id: string; archivedAt: Date } | { ok: true }>(`/issues/${id}/inbox-archive`),
   create: (companyId: string, data: Record<string, unknown>) =>
     api.post<Issue>(`/companies/${companyId}/issues`, data),
   update: (id: string, data: Record<string, unknown>) => api.patch<Issue>(`/issues/${id}`, data),

ui/src/components/ActivityRow.tsx

@@ -1,4 +1,5 @@
 import { Link } from "@/lib/router";
+import { VOCAB } from "@paperclipai/branding";
 import { Identity } from "./Identity";
 import { timeAgo } from "../lib/timeAgo";
 import { cn } from "../lib/utils";
@@ -106,7 +107,7 @@ export function ActivityRow({ event, agentMap, entityNameMap, entityTitleMap, cl
     : entityLink(event.entityType, event.entityId, name);
 
   const actor = event.actorType === "agent" ? agentMap.get(event.actorId) : null;
-  const actorName = actor?.name ?? (event.actorType === "system" ? "System" : event.actorType === "user" ? "Board" : event.actorId || "Unknown");
+  const actorName = actor?.name ?? (event.actorType === "system" ? "System" : event.actorType === "user" ? VOCAB.board : event.actorId || "Unknown");
 
   const inner = (
     <div className="flex gap-3">

ui/src/components/ApprovalPayload.tsx

@@ -1,9 +1,10 @@
 import { UserPlus, Lightbulb, ShieldAlert, ShieldCheck } from "lucide-react";
+import { VOCAB } from "@paperclipai/branding";
 import { formatCents } from "../lib/utils";
 
 export const typeLabel: Record<string, string> = {
-  hire_agent: "Hire Agent",
+  hire_agent: `${VOCAB.hire} Agent`,
-  approve_ceo_strategy: "CEO Strategy",
+  approve_ceo_strategy: `${VOCAB.ceo} Strategy`,
   budget_override_required: "Budget Override",
 };
 

ui/src/components/CompanyRail.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
-import { Paperclip, Plus } from "lucide-react";
+import { Box, Plus } from "lucide-react";
 import { useQueries } from "@tanstack/react-query";
 import {
   DndContext,
@@ -268,9 +268,9 @@ export function CompanyRail() {
 
   return (
     <div className="flex flex-col items-center w-[72px] shrink-0 h-full bg-background border-r border-border">
-      {/* Paperclip icon - aligned with top sections (implied line, no visible border) */}
+      {/* Nexus icon */}
       <div className="flex items-center justify-center h-12 w-full shrink-0">
-        <Paperclip className="h-5 w-5 text-foreground" />
+        <Box className="h-5 w-5 text-foreground" />
       </div>
 
       {/* Company list */}

ui/src/components/CompanySwitcher.tsx

@@ -1,4 +1,5 @@
 import { ChevronsUpDown, Plus, Settings } from "lucide-react";
+import { VOCAB } from "@paperclipai/branding";
 import { Link } from "@/lib/router";
 import { useCompany } from "../context/CompanyContext";
 import {
@@ -40,14 +41,14 @@ export function CompanySwitcher() {
               <span className={`h-2 w-2 rounded-full shrink-0 ${statusDotColor(selectedCompany.status)}`} />
             )}
             <span className="text-sm font-medium truncate">
-              {selectedCompany?.name ?? "Select company"}
+              {selectedCompany?.name ?? `Select ${VOCAB.company.toLowerCase()}`}
             </span>
           </div>
           <ChevronsUpDown className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
         </Button>
       </DropdownMenuTrigger>
       <DropdownMenuContent align="start" className="w-[220px]">
-        <DropdownMenuLabel>Companies</DropdownMenuLabel>
+        <DropdownMenuLabel>{VOCAB.companies}</DropdownMenuLabel>
         <DropdownMenuSeparator />
         {sidebarCompanies.map((company) => (
           <DropdownMenuItem
@@ -60,19 +61,19 @@ export function CompanySwitcher() {
           </DropdownMenuItem>
         ))}
         {sidebarCompanies.length === 0 && (
-          <DropdownMenuItem disabled>No companies</DropdownMenuItem>
+          <DropdownMenuItem disabled>{`No ${VOCAB.companies.toLowerCase()}`}</DropdownMenuItem>
         )}
         <DropdownMenuSeparator />
         <DropdownMenuItem asChild>
           <Link to="/company/settings" className="no-underline text-inherit">
             <Settings className="h-4 w-4 mr-2" />
-            Company Settings
+            {`${VOCAB.company} Settings`}
           </Link>
         </DropdownMenuItem>
         <DropdownMenuItem asChild>
           <Link to="/companies" className="no-underline text-inherit">
             <Plus className="h-4 w-4 mr-2" />
-            Manage Companies
+            {`Manage ${VOCAB.companies}`}
           </Link>
         </DropdownMenuItem>
       </DropdownMenuContent>

ui/src/components/IssueProperties.tsx

@@ -1,12 +1,10 @@
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useMemo, useState } from "react";
 import { pickTextColorForPillBg } from "@/lib/color-contrast";
 import { Link } from "@/lib/router";
 import type { Issue } from "@paperclipai/shared";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { agentsApi } from "../api/agents";
 import { authApi } from "../api/auth";
-import { executionWorkspacesApi } from "../api/execution-workspaces";
-import { instanceSettingsApi } from "../api/instanceSettings";
 import { issuesApi } from "../api/issues";
 import { projectsApi } from "../api/projects";
 import { useCompany } from "../context/CompanyContext";
@@ -21,15 +19,9 @@ import { formatDate, cn, projectUrl } from "../lib/utils";
 import { timeAgo } from "../lib/timeAgo";
 import { Separator } from "@/components/ui/separator";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
-import { User, Hexagon, ArrowUpRight, Tag, Plus, Trash2, Copy, Check } from "lucide-react";
+import { User, Hexagon, ArrowUpRight, Tag, Plus, Trash2 } from "lucide-react";
 import { AgentIcon } from "./AgentIconPicker";
 
-const EXECUTION_WORKSPACE_OPTIONS = [
-  { value: "shared_workspace", label: "Project default" },
-  { value: "isolated_workspace", label: "New isolated workspace" },
-  { value: "reuse_existing", label: "Reuse existing workspace" },
-] as const;
-
 function defaultProjectWorkspaceIdForProject(project: {
   workspaces?: Array<{ id: string; isPrimary: boolean }>;
   executionWorkspacePolicy?: { defaultProjectWorkspaceId?: string | null } | null;
@@ -48,23 +40,6 @@ function defaultExecutionWorkspaceModeForProject(project: { executionWorkspacePo
   return "shared_workspace";
 }
 
-function issueModeForExistingWorkspace(mode: string | null | undefined) {
-  if (mode === "isolated_workspace" || mode === "operator_branch" || mode === "shared_workspace") return mode;
-  if (mode === "adapter_managed" || mode === "cloud_sandbox") return "agent_default";
-  return "shared_workspace";
-}
-
-function shouldPresentExistingWorkspaceSelection(issue: Issue) {
-  const persistedMode =
-    issue.currentExecutionWorkspace?.mode
-    ?? issue.executionWorkspaceSettings?.mode
-    ?? issue.executionWorkspacePreference;
-  return Boolean(
-    issue.executionWorkspaceId &&
-    (persistedMode === "isolated_workspace" || persistedMode === "operator_branch"),
-  );
-}
-
 interface IssuePropertiesProps {
   issue: Issue;
   onUpdate: (data: Record<string, unknown>) => void;
@@ -142,49 +117,6 @@ function PropertyPicker({
   );
 }
 
-/** Splits a string at `/` and `-` boundaries, inserting <wbr> for natural line breaks. */
-function BreakablePath({ text }: { text: string }) {
-  const parts: React.ReactNode[] = [];
-  // Split on path separators and hyphens, keeping them in the output
-  const segments = text.split(/(?<=[\/-])/);
-  for (let i = 0; i < segments.length; i++) {
-    if (i > 0) parts.push(<wbr key={i} />);
-    parts.push(segments[i]);
-  }
-  return <>{parts}</>;
-}
-
-/** Displays a value with a copy-to-clipboard icon and "Copied!" feedback. */
-function CopyableValue({ value, label, mono, className }: { value: string; label?: string; mono?: boolean; className?: string }) {
-  const [copied, setCopied] = useState(false);
-  const timerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
-  const handleCopy = useCallback(async () => {
-    try {
-      await navigator.clipboard.writeText(value);
-      setCopied(true);
-      clearTimeout(timerRef.current);
-      timerRef.current = setTimeout(() => setCopied(false), 1500);
-    } catch { /* noop */ }
-  }, [value]);
-
-  return (
-    <div className={cn("flex items-start gap-1 group", className)}>
-      <span className="min-w-0" style={{ overflowWrap: "anywhere" }}>
-        {label && <span className="text-muted-foreground">{label} </span>}
-        <span className={mono ? "font-mono" : undefined}><BreakablePath text={value} /></span>
-      </span>
-      <button
-        type="button"
-        className="shrink-0 mt-0.5 p-0.5 rounded hover:bg-accent/50 transition-colors text-muted-foreground hover:text-foreground opacity-0 group-hover:opacity-100 focus:opacity-100"
-        onClick={handleCopy}
-        title={copied ? "Copied!" : "Copy to clipboard"}
-      >
-        {copied ? <Check className="h-3 w-3 text-green-500" /> : <Copy className="h-3 w-3" />}
-      </button>
-    </div>
-  );
-}
-
 export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProps) {
   const { selectedCompanyId } = useCompany();
   const queryClient = useQueryClient();
@@ -202,10 +134,6 @@ export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProp
     queryKey: queryKeys.auth.session,
     queryFn: () => authApi.getSession(),
   });
-  const { data: experimentalSettings } = useQuery({
-    queryKey: queryKeys.instance.experimentalSettings,
-    queryFn: () => instanceSettingsApi.getExperimental(),
-  });
   const currentUserId = session?.user?.id ?? session?.session?.userId;
 
   const { data: agents } = useQuery({
@@ -275,48 +203,6 @@ export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProp
   const currentProject = issue.projectId
     ? orderedProjects.find((project) => project.id === issue.projectId) ?? null
     : null;
-  const currentProjectExecutionWorkspacePolicy =
-    experimentalSettings?.enableIsolatedWorkspaces === true
-      ? currentProject?.executionWorkspacePolicy ?? null
-      : null;
-  const currentProjectSupportsExecutionWorkspace = Boolean(currentProjectExecutionWorkspacePolicy?.enabled);
-  const { data: reusableExecutionWorkspaces } = useQuery({
-    queryKey: queryKeys.executionWorkspaces.list(companyId!, {
-      projectId: issue.projectId ?? undefined,
-      projectWorkspaceId: issue.projectWorkspaceId ?? undefined,
-      reuseEligible: true,
-    }),
-    queryFn: () =>
-      executionWorkspacesApi.list(companyId!, {
-        projectId: issue.projectId ?? undefined,
-        projectWorkspaceId: issue.projectWorkspaceId ?? undefined,
-        reuseEligible: true,
-      }),
-    enabled: Boolean(companyId) && Boolean(issue.projectId),
-  });
-  const deduplicatedReusableWorkspaces = useMemo(() => {
-    const workspaces = reusableExecutionWorkspaces ?? [];
-    const seen = new Map<string, typeof workspaces[number]>();
-    for (const ws of workspaces) {
-      const key = ws.cwd ?? ws.id;
-      const existing = seen.get(key);
-      if (!existing || new Date(ws.lastUsedAt) > new Date(existing.lastUsedAt)) {
-        seen.set(key, ws);
-      }
-    }
-    return Array.from(seen.values());
-  }, [reusableExecutionWorkspaces]);
-  const selectedReusableExecutionWorkspace =
-    deduplicatedReusableWorkspaces.find((workspace) => workspace.id === issue.executionWorkspaceId)
-    ?? issue.currentExecutionWorkspace
-    ?? null;
-  const currentExecutionWorkspaceSelection = shouldPresentExistingWorkspaceSelection(issue)
-    ? "reuse_existing"
-    : (
-        issue.executionWorkspacePreference
-        ?? issue.executionWorkspaceSettings?.mode
-        ?? defaultExecutionWorkspaceModeForProject(currentProject)
-      );
   const projectLink = (id: string | null) => {
     if (!id) return null;
     const project = projects?.find((p) => p.id === id) ?? null;
@@ -674,93 +560,6 @@ export function IssueProperties({ issue, onUpdate, inline }: IssuePropertiesProp
           {projectContent}
         </PropertyPicker>
 
-        {currentProjectSupportsExecutionWorkspace && (
-          <PropertyRow label="Workspace">
-            <div className="w-full space-y-2">
-              <select
-                className="w-full rounded border border-border bg-transparent px-2 py-1.5 text-xs outline-none"
-                value={currentExecutionWorkspaceSelection}
-                onChange={(e) => {
-                  const nextMode = e.target.value;
-                  onUpdate({
-                    executionWorkspacePreference: nextMode,
-                    executionWorkspaceId: nextMode === "reuse_existing" ? issue.executionWorkspaceId : null,
-                    executionWorkspaceSettings: {
-                      mode:
-                        nextMode === "reuse_existing"
-                          ? issueModeForExistingWorkspace(selectedReusableExecutionWorkspace?.mode)
-                          : nextMode,
-                    },
-                  });
-                }}
-              >
-                {EXECUTION_WORKSPACE_OPTIONS.map((option) => (
-                  <option key={option.value} value={option.value}>
-                    {option.value === "reuse_existing" && selectedReusableExecutionWorkspace?.mode === "isolated_workspace"
-                      ? "Existing isolated workspace"
-                      : option.label}
-                  </option>
-                ))}
-              </select>
-
-              {currentExecutionWorkspaceSelection === "reuse_existing" && (
-                <select
-                  className="w-full rounded border border-border bg-transparent px-2 py-1.5 text-xs outline-none"
-                  value={issue.executionWorkspaceId ?? ""}
-                  onChange={(e) => {
-                    const nextExecutionWorkspaceId = e.target.value || null;
-                    const nextExecutionWorkspace = deduplicatedReusableWorkspaces.find(
-                      (workspace) => workspace.id === nextExecutionWorkspaceId,
-                    );
-                    onUpdate({
-                      executionWorkspacePreference: "reuse_existing",
-                      executionWorkspaceId: nextExecutionWorkspaceId,
-                      executionWorkspaceSettings: {
-                        mode: issueModeForExistingWorkspace(nextExecutionWorkspace?.mode),
-                      },
-                    });
-                  }}
-                >
-                  <option value="">Choose an existing workspace</option>
-                  {deduplicatedReusableWorkspaces.map((workspace) => (
-                    <option key={workspace.id} value={workspace.id}>
-                      {workspace.name} · {workspace.status} · {workspace.branchName ?? workspace.cwd ?? workspace.id.slice(0, 8)}
-                    </option>
-                  ))}
-                </select>
-              )}
-
-              {issue.currentExecutionWorkspace && (
-                <div className="text-[11px] text-muted-foreground space-y-0.5">
-                  <div style={{ overflowWrap: "anywhere" }}>
-                    Current:{" "}
-                    <Link
-                      to={`/execution-workspaces/${issue.currentExecutionWorkspace.id}`}
-                      className="hover:text-foreground hover:underline"
-                    >
-                      <BreakablePath text={issue.currentExecutionWorkspace.name} />
-                    </Link>
-                    {" · "}
-                    {issue.currentExecutionWorkspace.status}
-                  </div>
-                  {issue.currentExecutionWorkspace.cwd && (
-                    <CopyableValue value={issue.currentExecutionWorkspace.cwd} mono className="text-[11px]" />
-                  )}
-                  {issue.currentExecutionWorkspace.branchName && (
-                    <CopyableValue value={issue.currentExecutionWorkspace.branchName} label="Branch:" className="text-[11px]" />
-                  )}
-                  {issue.currentExecutionWorkspace.repoUrl && (
-                    <CopyableValue value={issue.currentExecutionWorkspace.repoUrl} label="Repo:" mono className="text-[11px]" />
-                  )}
-                </div>
-              )}
-              {!issue.currentExecutionWorkspace && currentProject?.primaryWorkspace?.cwd && (
-                <CopyableValue value={currentProject.primaryWorkspace.cwd} mono className="text-[11px] text-muted-foreground" />
-              )}
-            </div>
-          </PropertyRow>
-        )}
-
         {issue.parentId && (
           <PropertyRow label="Parent">
             <Link

ui/src/components/IssueRow.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type { Issue } from "@paperclipai/shared";
 import { Link } from "@/lib/router";
+import { X } from "lucide-react";
 import { cn } from "../lib/utils";
 import { StatusIcon } from "./StatusIcon";
 
@@ -17,6 +18,8 @@ interface IssueRowProps {
   trailingMeta?: ReactNode;
   unreadState?: UnreadState | null;
   onMarkRead?: () => void;
+  onArchive?: () => void;
+  archiveDisabled?: boolean;
   className?: string;
 }
 
@@ -31,6 +34,8 @@ export function IssueRow({
   trailingMeta,
   unreadState = null,
   onMarkRead,
+  onArchive,
+  archiveDisabled,
   className,
 }: IssueRowProps) {
   const issuePathId = issue.identifier ?? issue.id;
@@ -43,7 +48,7 @@ export function IssueRow({
       to={`/issues/${issuePathId}`}
       state={issueLinkState}
       className={cn(
-        "flex items-start gap-2 border-b border-border py-2.5 pl-2 pr-3 text-sm no-underline text-inherit transition-colors hover:bg-accent/50 last:border-b-0 sm:items-center sm:py-2 sm:pl-1",
+        "group flex items-start gap-2 border-b border-border py-2.5 pl-2 pr-3 text-sm no-underline text-inherit transition-colors hover:bg-accent/50 last:border-b-0 sm:items-center sm:py-2 sm:pl-1",
         className,
       )}
     >
@@ -113,6 +118,26 @@ export function IssueRow({
                 )}
               />
             </button>
+          ) : onArchive ? (
+            <button
+              type="button"
+              onClick={(event) => {
+                event.preventDefault();
+                event.stopPropagation();
+                onArchive();
+              }}
+              onKeyDown={(event) => {
+                if (event.key !== "Enter" && event.key !== " ") return;
+                event.preventDefault();
+                event.stopPropagation();
+                onArchive();
+              }}
+              disabled={archiveDisabled}
+              className="inline-flex h-4 w-4 items-center justify-center rounded-md text-muted-foreground opacity-0 transition-opacity hover:text-foreground group-hover:opacity-100 disabled:pointer-events-none disabled:opacity-30"
+              aria-label="Dismiss from inbox"
+            >
+              <X className="h-3.5 w-3.5" />
+            </button>
           ) : (
             <span className="inline-flex h-4 w-4" aria-hidden="true" />
           )}

ui/src/components/IssueWorkspaceCard.tsx

@@ -0,0 +1,403 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Link } from "@/lib/router";
+import type { Issue, ExecutionWorkspace } from "@paperclipai/shared";
+import { useQuery } from "@tanstack/react-query";
+import { executionWorkspacesApi } from "../api/execution-workspaces";
+import { instanceSettingsApi } from "../api/instanceSettings";
+import { useCompany } from "../context/CompanyContext";
+import { queryKeys } from "../lib/queryKeys";
+import { cn } from "../lib/utils";
+import { Button } from "@/components/ui/button";
+import { Check, Copy, GitBranch, FolderOpen, Pencil, X } from "lucide-react";
+
+/* -------------------------------------------------------------------------- */
+/*  Utility helpers (mirrored from IssueProperties for self-containment)      */
+/* -------------------------------------------------------------------------- */
+
+const EXECUTION_WORKSPACE_OPTIONS = [
+  { value: "shared_workspace", label: "Project default" },
+  { value: "isolated_workspace", label: "New isolated workspace" },
+  { value: "reuse_existing", label: "Reuse existing workspace" },
+] as const;
+
+function issueModeForExistingWorkspace(mode: string | null | undefined) {
+  if (mode === "isolated_workspace" || mode === "operator_branch" || mode === "shared_workspace") return mode;
+  if (mode === "adapter_managed" || mode === "cloud_sandbox") return "agent_default";
+  return "shared_workspace";
+}
+
+function shouldPresentExistingWorkspaceSelection(issue: Issue) {
+  const persistedMode =
+    issue.currentExecutionWorkspace?.mode
+    ?? issue.executionWorkspaceSettings?.mode
+    ?? issue.executionWorkspacePreference;
+  return Boolean(
+    issue.executionWorkspaceId &&
+    (persistedMode === "isolated_workspace" || persistedMode === "operator_branch"),
+  );
+}
+
+function defaultExecutionWorkspaceModeForProject(project: { executionWorkspacePolicy?: { enabled?: boolean; defaultMode?: string | null } | null } | null | undefined) {
+  const defaultMode = project?.executionWorkspacePolicy?.enabled ? project.executionWorkspacePolicy.defaultMode : null;
+  if (defaultMode === "isolated_workspace" || defaultMode === "operator_branch") return defaultMode;
+  if (defaultMode === "adapter_default") return "agent_default";
+  return "shared_workspace";
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Sub-components                                                             */
+/* -------------------------------------------------------------------------- */
+
+function BreakablePath({ text }: { text: string }) {
+  const parts: React.ReactNode[] = [];
+  const segments = text.split(/(?<=[\/-])/);
+  for (let i = 0; i < segments.length; i++) {
+    if (i > 0) parts.push(<wbr key={i} />);
+    parts.push(segments[i]);
+  }
+  return <>{parts}</>;
+}
+
+function CopyableInline({ value, label, mono }: { value: string; label?: string; mono?: boolean }) {
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const handleCopy = useCallback(async () => {
+    try {
+      await navigator.clipboard.writeText(value);
+      setCopied(true);
+      clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => setCopied(false), 1500);
+    } catch { /* noop */ }
+  }, [value]);
+
+  return (
+    <span className="inline-flex items-center gap-1 group/copy">
+      {label && <span className="text-muted-foreground">{label}</span>}
+      <span className={cn("min-w-0", mono && "font-mono")} style={{ overflowWrap: "anywhere" }}>
+        <BreakablePath text={value} />
+      </span>
+      <button
+        type="button"
+        className="shrink-0 p-0.5 rounded hover:bg-accent/50 transition-colors text-muted-foreground hover:text-foreground opacity-0 group-hover/copy:opacity-100 focus:opacity-100"
+        onClick={handleCopy}
+        title={copied ? "Copied!" : "Copy"}
+      >
+        {copied ? <Check className="h-3 w-3 text-green-500" /> : <Copy className="h-3 w-3" />}
+      </button>
+    </span>
+  );
+}
+
+function workspaceModeLabel(mode: string | null | undefined) {
+  switch (mode) {
+    case "isolated_workspace": return "Isolated workspace";
+    case "operator_branch": return "Operator branch";
+    case "cloud_sandbox": return "Cloud sandbox";
+    case "adapter_managed": return "Adapter managed";
+    default: return "Workspace";
+  }
+}
+
+function configuredWorkspaceLabel(
+  selection: string | null | undefined,
+  reusableWorkspace: ExecutionWorkspace | null,
+) {
+  switch (selection) {
+    case "isolated_workspace":
+      return "New isolated workspace";
+    case "reuse_existing":
+      return reusableWorkspace?.mode === "isolated_workspace"
+        ? "Existing isolated workspace"
+        : "Reuse existing workspace";
+    default:
+      return "Project default";
+  }
+}
+
+function statusBadge(status: string) {
+  const colors: Record<string, string> = {
+    active: "bg-green-500/15 text-green-700 dark:text-green-400",
+    idle: "bg-muted text-muted-foreground",
+    in_review: "bg-blue-500/15 text-blue-700 dark:text-blue-400",
+    archived: "bg-muted text-muted-foreground",
+  };
+  return (
+    <span className={cn("text-[10px] px-1.5 py-0.5 rounded-full font-medium", colors[status] ?? colors.idle)}>
+      {status.replace(/_/g, " ")}
+    </span>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/*  Main component                                                             */
+/* -------------------------------------------------------------------------- */
+
+interface IssueWorkspaceCardProps {
+  issue: Issue;
+  project: { id: string; executionWorkspacePolicy?: { enabled?: boolean; defaultMode?: string | null; defaultProjectWorkspaceId?: string | null } | null; workspaces?: Array<{ id: string; isPrimary: boolean }> } | null;
+  onUpdate: (data: Record<string, unknown>) => void;
+}
+
+export function IssueWorkspaceCard({ issue, project, onUpdate }: IssueWorkspaceCardProps) {
+  const { selectedCompanyId } = useCompany();
+  const companyId = issue.companyId ?? selectedCompanyId;
+  const [editing, setEditing] = useState(false);
+
+  const { data: experimentalSettings } = useQuery({
+    queryKey: queryKeys.instance.experimentalSettings,
+    queryFn: () => instanceSettingsApi.getExperimental(),
+  });
+
+  const policyEnabled = experimentalSettings?.enableIsolatedWorkspaces === true
+    && Boolean(project?.executionWorkspacePolicy?.enabled);
+
+  const workspace = issue.currentExecutionWorkspace as ExecutionWorkspace | null | undefined;
+
+  const { data: reusableExecutionWorkspaces } = useQuery({
+    queryKey: queryKeys.executionWorkspaces.list(companyId!, {
+      projectId: issue.projectId ?? undefined,
+      projectWorkspaceId: issue.projectWorkspaceId ?? undefined,
+      reuseEligible: true,
+    }),
+    queryFn: () =>
+      executionWorkspacesApi.list(companyId!, {
+        projectId: issue.projectId ?? undefined,
+        projectWorkspaceId: issue.projectWorkspaceId ?? undefined,
+        reuseEligible: true,
+      }),
+    enabled: Boolean(companyId) && Boolean(issue.projectId) && editing,
+  });
+
+  const deduplicatedReusableWorkspaces = useMemo(() => {
+    const workspaces = reusableExecutionWorkspaces ?? [];
+    const seen = new Map<string, typeof workspaces[number]>();
+    for (const ws of workspaces) {
+      const key = ws.cwd ?? ws.id;
+      const existing = seen.get(key);
+      if (!existing || new Date(ws.lastUsedAt) > new Date(existing.lastUsedAt)) {
+        seen.set(key, ws);
+      }
+    }
+    return Array.from(seen.values());
+  }, [reusableExecutionWorkspaces]);
+
+  const selectedReusableExecutionWorkspace =
+    deduplicatedReusableWorkspaces.find((w) => w.id === issue.executionWorkspaceId)
+    ?? workspace
+    ?? null;
+
+  const currentSelection = shouldPresentExistingWorkspaceSelection(issue)
+    ? "reuse_existing"
+    : (
+        issue.executionWorkspacePreference
+        ?? issue.executionWorkspaceSettings?.mode
+        ?? defaultExecutionWorkspaceModeForProject(project)
+      );
+
+  const [draftSelection, setDraftSelection] = useState(currentSelection);
+  const [draftExecutionWorkspaceId, setDraftExecutionWorkspaceId] = useState(issue.executionWorkspaceId ?? "");
+
+  useEffect(() => {
+    if (editing) return;
+    setDraftSelection(currentSelection);
+    setDraftExecutionWorkspaceId(issue.executionWorkspaceId ?? "");
+  }, [currentSelection, editing, issue.executionWorkspaceId]);
+
+  const activeNonDefaultWorkspace = Boolean(workspace && workspace.mode !== "shared_workspace");
+
+  const configuredReusableWorkspace =
+    deduplicatedReusableWorkspaces.find((w) => w.id === draftExecutionWorkspaceId)
+    ?? (draftExecutionWorkspaceId === issue.executionWorkspaceId ? selectedReusableExecutionWorkspace : null);
+
+  const canSaveWorkspaceConfig = draftSelection !== "reuse_existing" || draftExecutionWorkspaceId.length > 0;
+
+  const handleSave = useCallback(() => {
+    if (!canSaveWorkspaceConfig) return;
+    onUpdate({
+      executionWorkspacePreference: draftSelection,
+      executionWorkspaceId: draftSelection === "reuse_existing" ? draftExecutionWorkspaceId || null : null,
+      executionWorkspaceSettings: {
+        mode:
+          draftSelection === "reuse_existing"
+            ? issueModeForExistingWorkspace(configuredReusableWorkspace?.mode)
+            : draftSelection,
+      },
+    });
+    setEditing(false);
+  }, [
+    canSaveWorkspaceConfig,
+    configuredReusableWorkspace?.mode,
+    draftExecutionWorkspaceId,
+    draftSelection,
+    onUpdate,
+  ]);
+
+  const handleCancel = useCallback(() => {
+    setDraftSelection(currentSelection);
+    setDraftExecutionWorkspaceId(issue.executionWorkspaceId ?? "");
+    setEditing(false);
+  }, [currentSelection, issue.executionWorkspaceId]);
+
+  if (!policyEnabled || !project) return null;
+
+  return (
+    <div className="rounded-lg border border-border p-3 space-y-2">
+      {/* Header row */}
+      <div className="flex items-center justify-between gap-2">
+        <div className="flex items-center gap-2 text-sm font-medium text-foreground">
+          <GitBranch className="h-3.5 w-3.5 text-muted-foreground" />
+          {activeNonDefaultWorkspace && workspace
+            ? workspaceModeLabel(workspace.mode)
+            : configuredWorkspaceLabel(currentSelection, selectedReusableExecutionWorkspace)}
+          {workspace ? statusBadge(workspace.status) : statusBadge("idle")}
+        </div>
+        <div className="flex items-center gap-1">
+          {editing ? (
+            <>
+              <Button
+                variant="ghost"
+                size="sm"
+                className="h-6 px-2 text-xs text-muted-foreground"
+                onClick={handleCancel}
+              >
+                <X className="h-3 w-3 mr-1" />Cancel
+              </Button>
+              <Button
+                size="sm"
+                className="h-6 px-2 text-xs"
+                onClick={handleSave}
+                disabled={!canSaveWorkspaceConfig}
+              >
+                Save
+              </Button>
+            </>
+          ) : (
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-6 px-2 text-xs text-muted-foreground"
+              onClick={() => setEditing(true)}
+            >
+              <Pencil className="h-3 w-3 mr-1" />Edit
+            </Button>
+          )}
+        </div>
+      </div>
+
+      {/* Read-only info */}
+      {!editing && (
+        <div className="space-y-1.5 text-xs">
+          {workspace?.branchName && (
+            <div className="flex items-center gap-1.5">
+              <GitBranch className="h-3 w-3 text-muted-foreground shrink-0" />
+              <CopyableInline value={workspace.branchName} mono />
+            </div>
+          )}
+          {workspace?.cwd && (
+            <div className="flex items-center gap-1.5">
+              <FolderOpen className="h-3 w-3 text-muted-foreground shrink-0" />
+              <CopyableInline value={workspace.cwd} mono />
+            </div>
+          )}
+          {workspace?.repoUrl && (
+            <div className="flex items-center gap-1.5 text-muted-foreground">
+              <span className="text-[11px]">Repo:</span>
+              <CopyableInline value={workspace.repoUrl} mono />
+            </div>
+          )}
+          {!workspace && (
+            <div className="text-muted-foreground">
+              {currentSelection === "isolated_workspace"
+                ? "A fresh isolated workspace will be created when this issue runs."
+                : currentSelection === "reuse_existing"
+                  ? "This issue will reuse an existing workspace when it runs."
+                  : "This issue will use the project default workspace configuration when it runs."}
+            </div>
+          )}
+          {currentSelection === "reuse_existing" && selectedReusableExecutionWorkspace && (
+            <div className="text-muted-foreground" style={{ overflowWrap: "anywhere" }}>
+              Reusing:{" "}
+              <Link
+                to={`/execution-workspaces/${selectedReusableExecutionWorkspace.id}`}
+                className="hover:text-foreground hover:underline"
+              >
+                <BreakablePath text={selectedReusableExecutionWorkspace.name} />
+              </Link>
+            </div>
+          )}
+          {workspace && (
+            <div className="pt-0.5">
+              <Link
+                to={`/execution-workspaces/${workspace.id}`}
+                className="text-[11px] text-muted-foreground hover:text-foreground hover:underline"
+              >
+                View workspace details →
+              </Link>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Editing controls */}
+      {editing && (
+        <div className="space-y-2 pt-1">
+          <select
+            className="w-full rounded border border-border bg-transparent px-2 py-1.5 text-xs outline-none"
+            value={draftSelection}
+            onChange={(e) => {
+              const nextMode = e.target.value;
+              setDraftSelection(nextMode);
+              if (nextMode !== "reuse_existing") {
+                setDraftExecutionWorkspaceId("");
+              } else if (!draftExecutionWorkspaceId && issue.executionWorkspaceId) {
+                setDraftExecutionWorkspaceId(issue.executionWorkspaceId);
+              }
+            }}
+          >
+            {EXECUTION_WORKSPACE_OPTIONS.map((option) => (
+              <option key={option.value} value={option.value}>
+                {option.value === "reuse_existing" && configuredReusableWorkspace?.mode === "isolated_workspace"
+                  ? "Existing isolated workspace"
+                  : option.label}
+              </option>
+            ))}
+          </select>
+
+          {draftSelection === "reuse_existing" && (
+            <select
+              className="w-full rounded border border-border bg-transparent px-2 py-1.5 text-xs outline-none"
+              value={draftExecutionWorkspaceId}
+              onChange={(e) => {
+                setDraftExecutionWorkspaceId(e.target.value);
+              }}
+            >
+              <option value="">Choose an existing workspace</option>
+              {deduplicatedReusableWorkspaces.map((w) => (
+                <option key={w.id} value={w.id}>
+                  {w.name} · {w.status} · {w.branchName ?? w.cwd ?? w.id.slice(0, 8)}
+                </option>
+              ))}
+            </select>
+          )}
+
+          {/* Current workspace summary when editing */}
+          {workspace && (
+            <div className="text-[11px] text-muted-foreground space-y-0.5 pt-1 border-t border-border/50">
+              <div style={{ overflowWrap: "anywhere" }}>
+                Current:{" "}
+                <Link
+                  to={`/execution-workspaces/${workspace.id}`}
+                  className="hover:text-foreground hover:underline"
+                >
+                  <BreakablePath text={workspace.name} />
+                </Link>
+                {" · "}
+                {workspace.status}
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}