Merge remote-tracking branch 'public-gh/master' into openclawgateway

* public-gh/master:
  Enhance plugin architecture by introducing agent tool contributions and plugin-to-plugin communication. Update workspace plugin definitions for direct OS access and refine UI extension surfaces. Document new capabilities for plugin settings UI and lifecycle management.
  fix(server): serve cached index.html in SPA catch-all to prevent 500

.github/workflows/e2e.yml

@@ -1,44 +0,0 @@
-name: E2E Tests
-
-on:
-  workflow_dispatch:
-    inputs:
-      skip_llm:
-        description: "Skip LLM-dependent assertions (default: true)"
-        type: boolean
-        default: true
-
-jobs:
-  e2e:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    env:
-      PAPERCLIP_E2E_SKIP_LLM: ${{ inputs.skip_llm && 'true' || 'false' }}
-      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: pnpm
-
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm build
-      - run: npx playwright install --with-deps chromium
-
-      - name: Run e2e tests
-        run: pnpm run test:e2e
-
-      - uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: playwright-report
-          path: |
-            tests/e2e/playwright-report/
-            tests/e2e/test-results/
-          retention-days: 14

.github/workflows/pr-policy.yml

@@ -32,7 +32,6 @@ jobs:
           node-version: 20
 
       - name: Block manual lockfile edits
-        if: github.head_ref != 'chore/refresh-lockfile'
         run: |
           changed="$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}")"
           if printf '%s\n' "$changed" | grep -qx 'pnpm-lock.yaml'; then

.github/workflows/refresh-lockfile.yml

@@ -11,12 +11,11 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  refresh:
+  refresh_and_verify:
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 25
     permissions:
       contents: write
-      pull-requests: write
 
     steps:
       - name: Checkout repository
@@ -41,7 +40,6 @@ jobs:
         run: |
           changed="$(git status --porcelain)"
           if [ -z "$changed" ]; then
-            echo "Lockfile is already up to date."
             exit 0
           fi
           if printf '%s\n' "$changed" | grep -Fvq ' pnpm-lock.yaml'; then
@@ -50,32 +48,29 @@ jobs:
             exit 1
           fi
 
-      - name: Create or update pull request
-        env:
-          GH_TOKEN: ${{ github.token }}
+      - name: Commit refreshed lockfile
         run: |
           if git diff --quiet -- pnpm-lock.yaml; then
-            echo "Lockfile unchanged, nothing to do."
             exit 0
           fi
-
-          BRANCH="chore/refresh-lockfile"
           git config user.name "lockfile-bot"
           git config user.email "lockfile-bot@users.noreply.github.com"
-
-          git checkout -B "$BRANCH"
           git add pnpm-lock.yaml
           git commit -m "chore(lockfile): refresh pnpm-lock.yaml"
-          git push --force origin "$BRANCH"
+          git push || {
+            echo "Push failed because master moved during lockfile refresh."
+            echo "A later refresh run should recompute the lockfile from the newer master state."
+            exit 1
+          }
 
-          # Create PR if one doesn't already exist
-          existing=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number')
-          if [ -z "$existing" ]; then
-            gh pr create \
-              --head "$BRANCH" \
-              --title "chore(lockfile): refresh pnpm-lock.yaml" \
-              --body "Auto-generated lockfile refresh after dependencies changed on master. This PR only updates pnpm-lock.yaml."
-            echo "Created new PR."
-          else
-            echo "PR #$existing already exists, branch updated via force push."
-          fi
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm -r typecheck
+
+      - name: Run tests
+        run: pnpm test:run
+
+      - name: Build
+        run: pnpm build

.github/workflows/release.yml

@@ -1,132 +0,0 @@
-name: Release
-
-on:
-  workflow_dispatch:
-    inputs:
-      channel:
-        description: Release channel
-        required: true
-        type: choice
-        default: canary
-        options:
-          - canary
-          - stable
-      bump:
-        description: Semantic version bump
-        required: true
-        type: choice
-        default: patch
-        options:
-          - patch
-          - minor
-          - major
-      dry_run:
-        description: Preview the release without publishing
-        required: true
-        type: boolean
-        default: true
-
-concurrency:
-  group: release-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  verify:
-    if: startsWith(github.ref, 'refs/heads/release/')
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    permissions:
-      contents: read
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9.15.4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Typecheck
-        run: pnpm -r typecheck
-
-      - name: Run tests
-        run: pnpm test:run
-
-      - name: Build
-        run: pnpm build
-
-  publish:
-    if: startsWith(github.ref, 'refs/heads/release/')
-    needs: verify
-    runs-on: ubuntu-latest
-    timeout-minutes: 45
-    environment: npm-release
-    permissions:
-      contents: write
-      id-token: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9.15.4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Configure git author
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-
-      - name: Run release script
-        env:
-          GITHUB_ACTIONS: "true"
-        run: |
-          args=("${{ inputs.bump }}")
-          if [ "${{ inputs.channel }}" = "canary" ]; then
-            args+=("--canary")
-          fi
-          if [ "${{ inputs.dry_run }}" = "true" ]; then
-            args+=("--dry-run")
-          fi
-          ./scripts/release.sh "${args[@]}"
-
-      - name: Push stable release branch commit and tag
-        if: inputs.channel == 'stable' && !inputs.dry_run
-        run: git push origin "HEAD:${GITHUB_REF_NAME}" --follow-tags
-
-      - name: Create GitHub Release
-        if: inputs.channel == 'stable' && !inputs.dry_run
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          version="$(git tag --points-at HEAD | grep '^v' | head -1 | sed 's/^v//')"
-          if [ -z "$version" ]; then
-            echo "Error: no v* tag points at HEAD after stable release." >&2
-            exit 1
-          fi
-          ./scripts/create-github-release.sh "$version"

.gitignore

@@ -36,8 +36,4 @@ tmp/
 *.tmp
 .vscode/
 .claude/settings.local.json
-.paperclip-local/
-
-# Playwright
-tests/e2e/test-results/
-tests/e2e/playwright-report/
+.paperclip-local/

Dockerfile

@@ -18,8 +18,6 @@ COPY packages/adapters/codex-local/package.json packages/adapters/codex-local/
 COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/
 COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/
 COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/
-COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/
-
 RUN pnpm install --frozen-lockfile
 
 FROM base AS build
@@ -32,10 +30,8 @@ RUN test -f server/dist/index.js || (echo "ERROR: server build output missing" &
 
 FROM base AS production
 WORKDIR /app
-COPY --chown=node:node --from=build /app /app
-RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest opencode-ai \
-  && mkdir -p /paperclip \
-  && chown node:node /paperclip
+COPY --from=build /app /app
+RUN npm install --global --omit=dev @anthropic-ai/claude-code@latest @openai/codex@latest
 
 ENV NODE_ENV=production \
   HOME=/paperclip \
@@ -51,5 +47,4 @@ ENV NODE_ENV=production \
 VOLUME ["/paperclip"]
 EXPOSE 3100
 
-USER node
 CMD ["node", "--import", "./server/node_modules/tsx/dist/loader.mjs", "server/dist/index.js"]

cli/src/__tests__/allowed-hostname.test.ts

@@ -42,7 +42,6 @@ function writeBaseConfig(configPath: string) {
     },
     auth: {
       baseUrlMode: "auto",
-      disableSignUp: false,
     },
     storage: {
       provider: "local_disk",

cli/src/client/http.ts

@@ -104,10 +104,8 @@ export class PaperclipApiClient {
 
 function buildUrl(apiBase: string, path: string): string {
   const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-  const [pathname, query] = normalizedPath.split("?");
   const url = new URL(apiBase);
-  url.pathname = `${url.pathname.replace(/\/+$/, "")}${pathname}`;
-  if (query) url.search = query;
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}${normalizedPath}`;
   return url.toString();
 }
 

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

@@ -3,7 +3,6 @@ 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 { loadPaperclipEnvFile } from "../config/env.js";
 import { readConfig, resolveConfigPath } from "../config/store.js";
 
 function hashToken(token: string) {
@@ -14,8 +13,7 @@ function createInviteToken() {
   return `pcp_bootstrap_${randomBytes(24).toString("hex")}`;
 }
 
-function resolveDbUrl(configPath?: string, explicitDbUrl?: string) {
-  if (explicitDbUrl) return explicitDbUrl;
+function resolveDbUrl(configPath?: string) {
   const config = readConfig(configPath);
   if (process.env.DATABASE_URL) return process.env.DATABASE_URL;
   if (config?.database.mode === "postgres" && config.database.connectionString) {
@@ -51,10 +49,8 @@ export async function bootstrapCeoInvite(opts: {
   force?: boolean;
   expiresHours?: number;
   baseUrl?: string;
-  dbUrl?: string;
 }) {
   const configPath = resolveConfigPath(opts.config);
-  loadPaperclipEnvFile(configPath);
   const config = readConfig(configPath);
   if (!config) {
     p.log.error(`No config found at ${configPath}. Run ${pc.cyan("paperclip onboard")} first.`);
@@ -66,7 +62,7 @@ export async function bootstrapCeoInvite(opts: {
     return;
   }
 
-  const dbUrl = resolveDbUrl(configPath, opts.dbUrl);
+  const dbUrl = resolveDbUrl(configPath);
   if (!dbUrl) {
     p.log.error(
       "Could not resolve database connection for bootstrap.",
@@ -75,11 +71,6 @@ export async function bootstrapCeoInvite(opts: {
   }
 
   const db = createDb(dbUrl);
-  const closableDb = db as typeof db & {
-    $client?: {
-      end?: (options?: { timeout?: number }) => Promise<void>;
-    };
-  };
   try {
     const existingAdminCount = await db
       .select()
@@ -127,7 +118,5 @@ export async function bootstrapCeoInvite(opts: {
   } 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.");
-  } finally {
-    await closableDb.$client?.end?.({ timeout: 5 }).catch(() => undefined);
   }
 }

cli/src/commands/configure.ts

@@ -61,7 +61,6 @@ function defaultConfig(): PaperclipConfig {
     },
     auth: {
       baseUrlMode: "auto",
-      disableSignUp: false,
     },
     storage: defaultStorageConfig(),
     secrets: defaultSecretsConfig(),

cli/src/commands/doctor.ts

@@ -14,7 +14,6 @@ import {
   storageCheck,
   type CheckResult,
 } from "../checks/index.js";
-import { loadPaperclipEnvFile } from "../config/env.js";
 import { printPaperclipCliBanner } from "../utils/banner.js";
 
 const STATUS_ICON = {
@@ -32,7 +31,6 @@ export async function doctor(opts: {
   p.intro(pc.bgCyan(pc.black(" paperclip doctor ")));
 
   const configPath = resolveConfigPath(opts.config);
-  loadPaperclipEnvFile(configPath);
   const results: CheckResult[] = [];
 
   // 1. Config check (must pass before others)

cli/src/commands/onboard.ts

@@ -185,7 +185,6 @@ function quickstartDefaultsFromEnv(): {
     },
     auth: {
       baseUrlMode: authBaseUrlMode,
-      disableSignUp: false,
       ...(authPublicBaseUrl ? { publicBaseUrl: authPublicBaseUrl } : {}),
     },
     storage: {
@@ -229,10 +228,6 @@ function quickstartDefaultsFromEnv(): {
   return { defaults, usedEnvKeys, ignoredEnvKeys };
 }
 
-function canCreateBootstrapInviteImmediately(config: Pick<PaperclipConfig, "database" | "server">): boolean {
-  return config.server.deploymentMode === "authenticated" && config.database.mode !== "embedded-postgres";
-}
-
 export async function onboard(opts: OnboardOptions): Promise<void> {
   printPaperclipCliBanner();
   p.intro(pc.bgCyan(pc.black(" paperclipai onboard ")));
@@ -454,7 +449,7 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     "Next commands",
   );
 
-  if (canCreateBootstrapInviteImmediately({ database, server })) {
+  if (server.deploymentMode === "authenticated") {
     p.log.step("Generating bootstrap CEO invite");
     await bootstrapCeoInvite({ config: configPath });
   }
@@ -477,15 +472,5 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
     return;
   }
 
-  if (server.deploymentMode === "authenticated" && database.mode === "embedded-postgres") {
-    p.log.info(
-      [
-        "Bootstrap CEO invite will be created after the server starts.",
-        `Next: ${pc.cyan("paperclipai run")}`,
-        `Then: ${pc.cyan("paperclipai auth bootstrap-ceo")}`,
-      ].join("\n"),
-    );
-  }
-
   p.outro("You're all set!");
 }

cli/src/commands/run.ts

@@ -3,13 +3,9 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { bootstrapCeoInvite } from "./auth-bootstrap-ceo.js";
 import { onboard } from "./onboard.js";
 import { doctor } from "./doctor.js";
-import { loadPaperclipEnvFile } from "../config/env.js";
 import { configExists, resolveConfigPath } from "../config/store.js";
-import type { PaperclipConfig } from "../config/schema.js";
-import { readConfig } from "../config/store.js";
 import {
   describeLocalInstancePaths,
   resolvePaperclipHomeDir,
@@ -23,13 +19,6 @@ interface RunOptions {
   yes?: boolean;
 }
 
-interface StartedServer {
-  apiUrl: string;
-  databaseUrl: string;
-  host: string;
-  listenPort: number;
-}
-
 export async function runCommand(opts: RunOptions): Promise<void> {
   const instanceId = resolvePaperclipInstanceId(opts.instance);
   process.env.PAPERCLIP_INSTANCE_ID = instanceId;
@@ -42,7 +31,6 @@ export async function runCommand(opts: RunOptions): Promise<void> {
 
   const configPath = resolveConfigPath(opts.config);
   process.env.PAPERCLIP_CONFIG = configPath;
-  loadPaperclipEnvFile(configPath);
 
   p.intro(pc.bgCyan(pc.black(" paperclipai run ")));
   p.log.message(pc.dim(`Home: ${paths.homeDir}`));
@@ -72,41 +60,8 @@ export async function runCommand(opts: RunOptions): Promise<void> {
     process.exit(1);
   }
 
-  const config = readConfig(configPath);
-  if (!config) {
-    p.log.error(`No config found at ${configPath}.`);
-    process.exit(1);
-  }
-
   p.log.step("Starting Paperclip server...");
-  const startedServer = await importServerEntry();
-
-  if (shouldGenerateBootstrapInviteAfterStart(config)) {
-    p.log.step("Generating bootstrap CEO invite");
-    await bootstrapCeoInvite({
-      config: configPath,
-      dbUrl: startedServer.databaseUrl,
-      baseUrl: resolveBootstrapInviteBaseUrl(config, startedServer),
-    });
-  }
-}
-
-function resolveBootstrapInviteBaseUrl(
-  config: PaperclipConfig,
-  startedServer: StartedServer,
-): string {
-  const explicitBaseUrl =
-    process.env.PAPERCLIP_PUBLIC_URL ??
-    process.env.PAPERCLIP_AUTH_PUBLIC_BASE_URL ??
-    process.env.BETTER_AUTH_URL ??
-    process.env.BETTER_AUTH_BASE_URL ??
-    (config.auth.baseUrlMode === "explicit" ? config.auth.publicBaseUrl : undefined);
-
-  if (typeof explicitBaseUrl === "string" && explicitBaseUrl.trim().length > 0) {
-    return explicitBaseUrl.trim().replace(/\/+$/, "");
-  }
-
-  return startedServer.apiUrl.replace(/\/api$/, "");
+  await importServerEntry();
 }
 
 function formatError(err: unknown): string {
@@ -146,20 +101,19 @@ function maybeEnableUiDevMiddleware(entrypoint: string): void {
   }
 }
 
-async function importServerEntry(): Promise<StartedServer> {
+async function importServerEntry(): Promise<void> {
   // Dev mode: try local workspace path (monorepo with tsx)
   const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
   const devEntry = path.resolve(projectRoot, "server/src/index.ts");
   if (fs.existsSync(devEntry)) {
     maybeEnableUiDevMiddleware(devEntry);
-    const mod = await import(pathToFileURL(devEntry).href);
-    return await startServerFromModule(mod, devEntry);
+    await import(pathToFileURL(devEntry).href);
+    return;
   }
 
   // Production mode: import the published @paperclipai/server package
   try {
-    const mod = await import("@paperclipai/server");
-    return await startServerFromModule(mod, "@paperclipai/server");
+    await import("@paperclipai/server");
   } catch (err) {
     const missingSpecifier = getMissingModuleSpecifier(err);
     const missingServerEntrypoint = !missingSpecifier || missingSpecifier === "@paperclipai/server";
@@ -176,15 +130,3 @@ async function importServerEntry(): Promise<StartedServer> {
     );
   }
 }
-
-function shouldGenerateBootstrapInviteAfterStart(config: PaperclipConfig): boolean {
-  return config.server.deploymentMode === "authenticated" && config.database.mode === "embedded-postgres";
-}
-
-async function startServerFromModule(mod: unknown, label: string): Promise<StartedServer> {
-  const startServer = (mod as { startServer?: () => Promise<StartedServer> }).startServer;
-  if (typeof startServer !== "function") {
-    throw new Error(`Paperclip server entrypoint did not export startServer(): ${label}`);
-  }
-  return await startServer();
-}

cli/src/config/env.ts

@@ -36,10 +36,6 @@ export function resolveAgentJwtEnvFile(configPath?: string): string {
   return resolveEnvFilePath(configPath);
 }
 
-export function loadPaperclipEnvFile(configPath?: string): void {
-  loadAgentJwtEnvFile(resolveEnvFilePath(configPath));
-}
-
 export function loadAgentJwtEnvFile(filePath = resolveEnvFilePath()): void {
   if (loadedEnvFiles.has(filePath)) return;
 

cli/src/prompts/server.ts

@@ -113,7 +113,7 @@ export async function promptServer(opts?: {
   }
 
   const port = Number(portStr) || 3100;
-  let auth: AuthConfig = { baseUrlMode: "auto", disableSignUp: false };
+  let auth: AuthConfig = { baseUrlMode: "auto" };
   if (deploymentMode === "authenticated" && exposure === "public") {
     const urlInput = await p.text({
       message: "Public base URL",
@@ -139,13 +139,11 @@ export async function promptServer(opts?: {
     }
     auth = {
       baseUrlMode: "explicit",
-      disableSignUp: false,
       publicBaseUrl: urlInput.trim().replace(/\/+$/, ""),
     };
   } else if (currentAuth?.baseUrlMode === "explicit" && currentAuth.publicBaseUrl) {
     auth = {
       baseUrlMode: "explicit",
-      disableSignUp: false,
       publicBaseUrl: currentAuth.publicBaseUrl,
     };
   }

cli/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../tsconfig.base.json",
+  "extends": "../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

doc/DOCKER.md

@@ -122,7 +122,5 @@ Notes:
 - Container runtime user id defaults to your local `id -u` so the mounted data dir stays writable while avoiding root runtime.
 - Smoke script defaults to `authenticated/private` mode so `HOST=0.0.0.0` can be exposed to the host.
 - Smoke script defaults host port to `3131` to avoid conflicts with local Paperclip on `3100`.
-- Smoke script also defaults `PAPERCLIP_PUBLIC_URL` to `http://localhost:<HOST_PORT>` so bootstrap invite URLs and auth callbacks use the reachable host port instead of the container's internal `3100`.
-- In authenticated mode, the smoke script defaults `SMOKE_AUTO_BOOTSTRAP=true` and drives the real bootstrap path automatically: it signs up a real user, runs `paperclipai auth bootstrap-ceo` inside the container to mint a real bootstrap invite, accepts that invite over HTTP, and verifies board session access.
 - Run the script in the foreground to watch the onboarding flow; stop with `Ctrl+C` after validation.
 - The image definition is in `Dockerfile.onboard-smoke`.

doc/PUBLISHING.md

@@ -1,121 +1,196 @@
 # Publishing to npm
 
-Low-level reference for how Paperclip packages are built for npm.
+This document covers how to build and publish the `paperclipai` CLI package to npm.
 
-For the maintainer release workflow, use [doc/RELEASING.md](RELEASING.md). This document is only about packaging internals and the scripts that produce publishable artifacts.
+## Prerequisites
 
-## Current Release Entry Points
+- Node.js 20+
+- pnpm 9.15+
+- An npm account with publish access to the `paperclipai` package
+- Logged in to npm: `npm login`
 
-Use these scripts instead of older one-off publish commands:
+## One-Command Publish
 
-- [`scripts/release-start.sh`](../scripts/release-start.sh) to create or resume `release/X.Y.Z`
-- [`scripts/release-preflight.sh`](../scripts/release-preflight.sh) before any canary or stable release
-- [`scripts/release.sh`](../scripts/release.sh) for canary and stable npm publishes
-- [`scripts/rollback-latest.sh`](../scripts/rollback-latest.sh) to repoint `latest` during rollback
-- [`scripts/create-github-release.sh`](../scripts/create-github-release.sh) after pushing the stable branch tag
+The fastest way to publish — bumps version, builds, publishes, restores, commits, and tags in one shot:
 
-## Why the CLI needs special packaging
+```bash
+./scripts/bump-and-publish.sh patch          # 0.1.1 → 0.1.2
+./scripts/bump-and-publish.sh minor          # 0.1.1 → 0.2.0
+./scripts/bump-and-publish.sh major          # 0.1.1 → 1.0.0
+./scripts/bump-and-publish.sh 2.0.0          # set explicit version
+./scripts/bump-and-publish.sh patch --dry-run # everything except npm publish
+```
 
-The CLI package, `paperclipai`, imports code from workspace packages such as:
+The script runs all 6 steps below in order. It requires a clean working tree and an active `npm login` session (unless `--dry-run`). After it finishes, push:
 
-- `@paperclipai/server`
-- `@paperclipai/db`
-- `@paperclipai/shared`
-- adapter packages under `packages/adapters/`
+```bash
+git push && git push origin v<version>
+```
 
-Those workspace references use `workspace:*` during development. npm cannot install those references directly for end users, so the release build has to transform the CLI into a publishable standalone package.
+## Manual Step-by-Step
 
-## `build-npm.sh`
+If you prefer to run each step individually:
 
-Run:
+### Quick Reference
+
+```bash
+# Bump version
+./scripts/version-bump.sh patch      # 0.1.0 → 0.1.1
+
+# Build
+./scripts/build-npm.sh
+
+# Preview what will be published
+cd cli && npm pack --dry-run
+
+# Publish
+cd cli && npm publish --access public
+
+# Restore dev package.json
+mv cli/package.dev.json cli/package.json
+```
+
+## Step-by-Step
+
+### 1. Bump the version
+
+```bash
+./scripts/version-bump.sh <patch|minor|major|X.Y.Z>
+```
+
+This updates the version in two places:
+
+- `cli/package.json` — the source of truth
+- `cli/src/index.ts` — the Commander `.version()` call
+
+Examples:
+
+```bash
+./scripts/version-bump.sh patch    # 0.1.0 → 0.1.1
+./scripts/version-bump.sh minor    # 0.1.0 → 0.2.0
+./scripts/version-bump.sh major    # 0.1.0 → 1.0.0
+./scripts/version-bump.sh 1.2.3   # set explicit version
+```
+
+### 2. Build
 
 ```bash
 ./scripts/build-npm.sh
 ```
 
-This script does six things:
+The build script runs five steps:
 
-1. Runs the forbidden token check unless `--skip-checks` is supplied
-2. Runs `pnpm -r typecheck`
-3. Bundles the CLI entrypoint with esbuild into `cli/dist/index.js`
-4. Verifies the bundled entrypoint with `node --check`
-5. Rewrites `cli/package.json` into a publishable npm manifest and stores the dev copy as `cli/package.dev.json`
-6. Copies the repo `README.md` into `cli/README.md` for npm package metadata
+1. **Forbidden token check** — scans tracked files for tokens listed in `.git/hooks/forbidden-tokens.txt`. If the file is missing (e.g. on a contributor's machine), the check passes silently. The script never prints which tokens it's searching for.
+2. **TypeScript type-check** — runs `pnpm -r typecheck` across all workspace packages.
+3. **esbuild bundle** — bundles the CLI entry point (`cli/src/index.ts`) and all workspace package code (`@paperclipai/*`) into a single file at `cli/dist/index.js`. External npm dependencies (express, postgres, etc.) are kept as regular imports.
+4. **Generate publishable package.json** — replaces `cli/package.json` with a version that has real npm dependency ranges instead of `workspace:*` references (see [package.dev.json](#packagedevjson) below).
+5. **Summary** — prints the bundle size and next steps.
 
-`build-npm.sh` is used by the release script so that npm users install a real package rather than unresolved workspace dependencies.
-
-## Publishable CLI layout
-
-During development, [`cli/package.json`](../cli/package.json) contains workspace references.
-
-During release preparation:
-
-- `cli/package.json` becomes a publishable manifest with external npm dependency ranges
-- `cli/package.dev.json` stores the development manifest temporarily
-- `cli/dist/index.js` contains the bundled CLI entrypoint
-- `cli/README.md` is copied in for npm metadata
-
-After release finalization, the release script restores the development manifest and removes the temporary README copy.
-
-## Package discovery
-
-The release tooling scans the workspace for public packages under:
-
-- `packages/`
-- `server/`
-- `cli/`
-
-`ui/` remains ignored for npm publishing because it is private.
-
-This matters because all public packages are versioned and published together as one release unit.
-
-## Canary packaging model
-
-Canaries are published as semver prereleases such as:
-
-- `1.2.3-canary.0`
-- `1.2.3-canary.1`
-
-They are published under the npm dist-tag `canary`.
-
-This means:
-
-- `npx paperclipai@canary onboard` can install them explicitly
-- `npx paperclipai onboard` continues to resolve `latest`
-- the stable changelog can stay at `releases/v1.2.3.md`
-
-## Stable packaging model
-
-Stable releases publish normal semver versions such as `1.2.3` under the npm dist-tag `latest`.
-
-The stable publish flow also creates the local release commit and git tag on `release/X.Y.Z`. Pushing that branch commit/tag, creating the GitHub Release, and merging the release branch back to `master` happen afterward as separate maintainer steps.
-
-## Rollback model
-
-Rollback does not unpublish packages.
-
-Instead, the maintainer should move the `latest` dist-tag back to the previous good stable version with:
+To skip the forbidden token check (e.g. in CI without the token list):
 
 ```bash
-./scripts/rollback-latest.sh <stable-version>
+./scripts/build-npm.sh --skip-checks
 ```
 
-That keeps history intact while restoring the default install path quickly.
+### 3. Preview (optional)
 
-## Notes for CI
+See what npm will publish:
 
-The repo includes a manual GitHub Actions release workflow at [`.github/workflows/release.yml`](../.github/workflows/release.yml).
+```bash
+cd cli && npm pack --dry-run
+```
 
-Recommended CI release setup:
+### 4. Publish
 
-- use npm trusted publishing via GitHub OIDC
-- require approval through the `npm-release` environment
-- run releases from `release/X.Y.Z`
-- use canary first, then stable
+```bash
+cd cli && npm publish --access public
+```
 
-## Related Files
+### 5. Restore dev package.json
 
-- [`scripts/build-npm.sh`](../scripts/build-npm.sh)
-- [`scripts/generate-npm-package-json.mjs`](../scripts/generate-npm-package-json.mjs)
-- [`cli/esbuild.config.mjs`](../cli/esbuild.config.mjs)
-- [`doc/RELEASING.md`](RELEASING.md)
+After publishing, restore the workspace-aware `package.json`:
+
+```bash
+mv cli/package.dev.json cli/package.json
+```
+
+### 6. Commit and tag
+
+```bash
+git add cli/package.json cli/src/index.ts
+git commit -m "chore: bump version to X.Y.Z"
+git tag vX.Y.Z
+```
+
+## package.dev.json
+
+During development, `cli/package.json` contains `workspace:*` references like:
+
+```json
+{
+  "dependencies": {
+    "@paperclipai/server": "workspace:*",
+    "@paperclipai/db": "workspace:*"
+  }
+}
+```
+
+These tell pnpm to resolve those packages from the local monorepo. This is great for development but **npm doesn't understand `workspace:*`** — publishing with these references would cause install failures for users.
+
+The build script solves this with a two-file swap:
+
+1. **Before building:** `cli/package.json` has `workspace:*` refs (the dev version).
+2. **During build (`build-npm.sh` step 4):**
+   - The dev `package.json` is copied to `package.dev.json` as a backup.
+   - `generate-npm-package-json.mjs` reads every workspace package's `package.json`, collects all their external npm dependencies, and writes a new `cli/package.json` with those real dependency ranges — no `workspace:*` refs.
+3. **After publishing:** you restore the dev version with `mv package.dev.json package.json`.
+
+The generated publishable `package.json` looks like:
+
+```json
+{
+  "name": "paperclipai",
+  "version": "0.1.0",
+  "bin": { "paperclipai": "./dist/index.js" },
+  "dependencies": {
+    "express": "^5.1.0",
+    "postgres": "^3.4.5",
+    "commander": "^13.1.0"
+  }
+}
+```
+
+`package.dev.json` is listed in `.gitignore` — it only exists temporarily on disk during the build/publish cycle.
+
+## How the bundle works
+
+The CLI is a monorepo package that imports code from `@paperclipai/server`, `@paperclipai/db`, `@paperclipai/shared`, and several adapter packages. These workspace packages don't exist on npm.
+
+**esbuild** bundles all workspace TypeScript code into a single `dist/index.js` file (~250kb). External npm packages (express, postgres, zod, etc.) are left as normal `import` statements — they get installed by npm when a user runs `npx paperclipai onboard`.
+
+The esbuild configuration lives at `cli/esbuild.config.mjs`. It automatically reads every workspace package's `package.json` to determine which dependencies are external (real npm packages) vs. internal (workspace code to bundle).
+
+## Forbidden token enforcement
+
+The build process includes the same forbidden-token check used by the git pre-commit hook. This catches any accidentally committed tokens before they reach npm.
+
+- Token list: `.git/hooks/forbidden-tokens.txt` (one token per line, `#` comments supported)
+- The file lives inside `.git/` and is never committed
+- If the file is missing, the check passes — contributors without the list can still build
+- The script never prints which tokens are being searched for
+- Matches are printed so you know which files to fix, but not which token triggered it
+
+Run the check standalone:
+
+```bash
+pnpm check:tokens
+```
+
+## npm scripts reference
+
+| Script | Command | Description |
+|---|---|---|
+| `bump-and-publish` | `pnpm bump-and-publish <type>` | One-command bump + build + publish + commit + tag |
+| `build:npm` | `pnpm build:npm` | Full build (check + typecheck + bundle + package.json) |
+| `version:bump` | `pnpm version:bump <type>` | Bump CLI version |
+| `check:tokens` | `pnpm check:tokens` | Run forbidden token check only |

doc/RELEASING.md

@@ -1,422 +0,0 @@
-# Releasing Paperclip
-
-Maintainer runbook for shipping a full Paperclip release across npm, GitHub, and the website-facing changelog surface.
-
-The release model is branch-driven:
-
-1. Start a release train on `release/X.Y.Z`
-2. Draft the stable changelog on that branch
-3. Publish one or more canaries from that branch
-4. Publish stable from that same branch head
-5. Push the branch commit and tag
-6. Create the GitHub Release
-7. Merge `release/X.Y.Z` back to `master` without squash or rebase
-
-## Release Surfaces
-
-Every release has four separate surfaces:
-
-1. **Verification** — the exact git SHA passes typecheck, tests, and build
-2. **npm** — `paperclipai` and public workspace packages are published
-3. **GitHub** — the stable release gets a git tag and GitHub Release
-4. **Website / announcements** — the stable changelog is published externally and announced
-
-A release is done only when all four surfaces are handled.
-
-## Core Invariants
-
-- Canary and stable for `X.Y.Z` must come from the same `release/X.Y.Z` branch.
-- The release scripts must run from the matching `release/X.Y.Z` branch.
-- Once `vX.Y.Z` exists locally, on GitHub, or on npm, that release train is frozen.
-- Do not squash-merge or rebase-merge a release branch PR back to `master`.
-- The stable changelog is always `releases/vX.Y.Z.md`. Never create canary changelog files.
-
-The reason for the merge rule is simple: the tag must keep pointing at the exact published commit. Squash or rebase breaks that property.
-
-## TL;DR
-
-### 1. Start the release train
-
-Use this to compute the next version, create or resume the branch, create or resume a dedicated worktree, and push the branch to GitHub.
-
-```bash
-./scripts/release-start.sh patch
-```
-
-That script:
-
-- fetches the release remote and tags
-- computes the next stable version from the latest `v*` tag
-- creates or resumes `release/X.Y.Z`
-- creates or resumes a dedicated worktree
-- pushes the branch to the remote by default
-- refuses to reuse a frozen release train
-
-### 2. Draft the stable changelog
-
-From the release worktree:
-
-```bash
-VERSION=X.Y.Z
-claude --print --output-format stream-json --verbose --dangerously-skip-permissions --model claude-opus-4-6 "Use the release-changelog skill to draft or update releases/v${VERSION}.md for Paperclip. Read doc/RELEASING.md and skills/release-changelog/SKILL.md, then generate the stable changelog for v${VERSION} from commits since the last stable tag. Do not create a canary changelog."
-```
-
-### 3. Verify and publish a canary
-
-```bash
-./scripts/release-preflight.sh canary patch
-./scripts/release.sh patch --canary --dry-run
-./scripts/release.sh patch --canary
-PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
-```
-
-Users install canaries with:
-
-```bash
-npx paperclipai@canary onboard
-```
-
-### 4. Publish stable
-
-```bash
-./scripts/release-preflight.sh stable patch
-./scripts/release.sh patch --dry-run
-./scripts/release.sh patch
-git push public-gh HEAD --follow-tags
-./scripts/create-github-release.sh X.Y.Z
-```
-
-Then open a PR from `release/X.Y.Z` to `master` and merge without squash or rebase.
-
-## Release Branches
-
-Paperclip uses one release branch per target stable version:
-
-- `release/0.3.0`
-- `release/0.3.1`
-- `release/1.0.0`
-
-Do not create separate per-canary branches like `canary/0.3.0-1`. A canary is just a prerelease snapshot of the same stable train.
-
-## Script Entry Points
-
-- [`scripts/release-start.sh`](../scripts/release-start.sh) — create or resume the release train branch/worktree
-- [`scripts/release-preflight.sh`](../scripts/release-preflight.sh) — validate branch, version plan, git/npm state, and verification gate
-- [`scripts/release.sh`](../scripts/release.sh) — publish canary or stable from the release branch
-- [`scripts/create-github-release.sh`](../scripts/create-github-release.sh) — create or update the GitHub Release after pushing the tag
-- [`scripts/rollback-latest.sh`](../scripts/rollback-latest.sh) — repoint `latest` to the last good stable version
-
-## Detailed Workflow
-
-### 1. Start or resume the release train
-
-Run:
-
-```bash
-./scripts/release-start.sh <patch|minor|major>
-```
-
-Useful options:
-
-```bash
-./scripts/release-start.sh patch --dry-run
-./scripts/release-start.sh minor --worktree-dir ../paperclip-release-0.4.0
-./scripts/release-start.sh patch --no-push
-```
-
-The script is intentionally idempotent:
-
-- if `release/X.Y.Z` already exists locally, it reuses it
-- if the branch already exists on the remote, it resumes it locally
-- if the branch is already checked out in another worktree, it points you there
-- if `vX.Y.Z` already exists locally, remotely, or on npm, it refuses to reuse that train
-
-### 2. Write the stable changelog early
-
-Create or update:
-
-- `releases/vX.Y.Z.md`
-
-That file is for the eventual stable release. It should not include `-canary` in the filename or heading.
-
-Recommended structure:
-
-- `Breaking Changes` when needed
-- `Highlights`
-- `Improvements`
-- `Fixes`
-- `Upgrade Guide` when needed
-- `Contributors` — @-mention every contributor by GitHub username (no emails)
-
-Package-level `CHANGELOG.md` files are generated as part of the release mechanics. They are not the main release narrative.
-
-### 3. Run release preflight
-
-From the `release/X.Y.Z` worktree:
-
-```bash
-./scripts/release-preflight.sh canary <patch|minor|major>
-# or
-./scripts/release-preflight.sh stable <patch|minor|major>
-```
-
-The preflight script now checks all of the following before it runs the verification gate:
-
-- the worktree is clean, including untracked files
-- the current branch matches the computed `release/X.Y.Z`
-- the release train is not frozen
-- the target version is still free on npm
-- the target tag does not already exist locally or remotely
-- whether the remote release branch already exists
-- whether `releases/vX.Y.Z.md` is present
-
-Then it runs:
-
-```bash
-pnpm -r typecheck
-pnpm test:run
-pnpm build
-```
-
-### 4. Publish one or more canaries
-
-Run:
-
-```bash
-./scripts/release.sh <patch|minor|major> --canary --dry-run
-./scripts/release.sh <patch|minor|major> --canary
-```
-
-Result:
-
-- npm gets a prerelease such as `1.2.3-canary.0` under dist-tag `canary`
-- `latest` is unchanged
-- no git tag is created
-- no GitHub Release is created
-- the worktree returns to clean after the script finishes
-
-Guardrails:
-
-- the script refuses to run from the wrong branch
-- the script refuses to publish from a frozen train
-- the canary is always derived from the next stable version
-- if the stable notes file is missing, the script warns before you forget it
-
-Concrete example:
-
-- if the latest stable is `0.2.7`, a patch canary targets `0.2.8-canary.0`
-- `0.2.7-canary.N` is invalid because `0.2.7` is already stable
-
-### 5. Smoke test the canary
-
-Run the actual install path in Docker:
-
-```bash
-PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
-```
-
-Useful isolated variants:
-
-```bash
-HOST_PORT=3232 DATA_DIR=./data/release-smoke-canary PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
-HOST_PORT=3233 DATA_DIR=./data/release-smoke-stable PAPERCLIPAI_VERSION=latest ./scripts/docker-onboard-smoke.sh
-```
-
-If you want to exercise onboarding from the current committed ref instead of npm, use:
-
-```bash
-./scripts/clean-onboard-ref.sh
-PAPERCLIP_PORT=3234 ./scripts/clean-onboard-ref.sh
-./scripts/clean-onboard-ref.sh HEAD
-```
-
-Minimum checks:
-
-- `npx paperclipai@canary onboard` installs
-- onboarding completes without crashes
-- the server boots
-- the UI loads
-- basic company creation and dashboard load work
-
-If smoke testing fails:
-
-1. stop the stable release
-2. fix the issue on the same `release/X.Y.Z` branch
-3. publish another canary
-4. rerun smoke testing
-
-### 6. Publish stable from the same release branch
-
-Once the branch head is vetted, run:
-
-```bash
-./scripts/release.sh <patch|minor|major> --dry-run
-./scripts/release.sh <patch|minor|major>
-```
-
-Stable publish:
-
-- publishes `X.Y.Z` to npm under `latest`
-- creates the local release commit
-- creates the local tag `vX.Y.Z`
-
-Stable publish refuses to proceed if:
-
-- the current branch is not `release/X.Y.Z`
-- the remote release branch does not exist yet
-- the stable notes file is missing
-- the target tag already exists locally or remotely
-- the stable version already exists on npm
-
-Those checks intentionally freeze the train after stable publish.
-
-### 7. Push the stable branch commit and tag
-
-After stable publish succeeds:
-
-```bash
-git push public-gh HEAD --follow-tags
-./scripts/create-github-release.sh X.Y.Z
-```
-
-The GitHub Release notes come from:
-
-- `releases/vX.Y.Z.md`
-
-### 8. Merge the release branch back to `master`
-
-Open a PR:
-
-- base: `master`
-- head: `release/X.Y.Z`
-
-Merge rule:
-
-- allowed: merge commit or fast-forward
-- forbidden: squash merge
-- forbidden: rebase merge
-
-Post-merge verification:
-
-```bash
-git fetch public-gh --tags
-git merge-base --is-ancestor "vX.Y.Z" "public-gh/master"
-```
-
-That command must succeed. If it fails, the published tagged commit is not reachable from `master`, which means the merge strategy was wrong.
-
-### 9. Finish the external surfaces
-
-After GitHub is correct:
-
-- publish the changelog on the website
-- write and send the announcement copy
-- ensure public docs and install guidance point to the stable version
-
-## GitHub Actions Release
-
-There is also a manual workflow at [`.github/workflows/release.yml`](../.github/workflows/release.yml).
-
-Use it from the Actions tab on the relevant `release/X.Y.Z` branch:
-
-1. Choose `Release`
-2. Choose `channel`: `canary` or `stable`
-3. Choose `bump`: `patch`, `minor`, or `major`
-4. Choose whether this is a `dry_run`
-5. Run it from the release branch, not from `master`
-
-The workflow:
-
-- reruns `typecheck`, `test:run`, and `build`
-- gates publish behind the `npm-release` environment
-- can publish canaries without touching `latest`
-- can publish stable, push the stable branch commit and tag, and create the GitHub Release
-
-It does not merge the release branch back to `master` for you.
-
-## Release Checklist
-
-### Before any publish
-
-- [ ] The release train exists on `release/X.Y.Z`
-- [ ] The working tree is clean, including untracked files
-- [ ] If package manifests changed, the CI-owned `pnpm-lock.yaml` refresh is already merged on `master` before the train is cut
-- [ ] The required verification gate passed on the exact branch head you want to publish
-- [ ] The bump type is correct for the user-visible impact
-- [ ] The stable changelog file exists or is ready at `releases/vX.Y.Z.md`
-- [ ] You know which previous stable version you would roll back to if needed
-
-### Before a stable
-
-- [ ] The candidate has already passed smoke testing
-- [ ] The remote `release/X.Y.Z` branch exists
-- [ ] You are ready to push the stable branch commit and tag immediately after npm publish
-- [ ] You are ready to create the GitHub Release immediately after the push
-- [ ] You are ready to open the PR back to `master`
-
-### After a stable
-
-- [ ] `npm view paperclipai@latest version` matches the new stable version
-- [ ] The git tag exists on GitHub
-- [ ] The GitHub Release exists and uses `releases/vX.Y.Z.md`
-- [ ] `vX.Y.Z` is reachable from `master`
-- [ ] The website changelog is updated
-- [ ] Announcement copy matches the stable release, not the canary
-
-## Failure Playbooks
-
-### If the canary publishes but the smoke test fails
-
-Do not publish stable.
-
-Instead:
-
-1. fix the issue on `release/X.Y.Z`
-2. publish another canary
-3. rerun smoke testing
-
-### If stable npm publish succeeds but push or GitHub release creation fails
-
-This is a partial release. npm is already live.
-
-Do this immediately:
-
-1. fix the git or GitHub issue from the same checkout
-2. push the stable branch commit and tag
-3. create the GitHub Release
-
-Do not republish the same version.
-
-### If `latest` is broken after stable publish
-
-Preview:
-
-```bash
-./scripts/rollback-latest.sh X.Y.Z --dry-run
-```
-
-Roll back:
-
-```bash
-./scripts/rollback-latest.sh X.Y.Z
-```
-
-This does not unpublish anything. It only moves the `latest` dist-tag back to the last good stable release.
-
-Then fix forward with a new patch release.
-
-### If the GitHub Release notes are wrong
-
-Re-run:
-
-```bash
-./scripts/create-github-release.sh X.Y.Z
-```
-
-If the release already exists, the script updates it.
-
-## Related Docs
-
-- [doc/PUBLISHING.md](PUBLISHING.md) — low-level npm build and packaging internals
-- [skills/release/SKILL.md](../skills/release/SKILL.md) — agent release coordination workflow
-- [skills/release-changelog/SKILL.md](../skills/release-changelog/SKILL.md) — stable changelog drafting workflow

package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "scripts": {
     "dev": "node scripts/dev-runner.mjs watch",
-    "dev:watch": "cross-env PAPERCLIP_MIGRATION_PROMPT=never node scripts/dev-runner.mjs watch",
+    "dev:watch": "PAPERCLIP_MIGRATION_PROMPT=never node scripts/dev-runner.mjs watch",
     "dev:once": "node scripts/dev-runner.mjs dev",
     "dev:server": "pnpm --filter @paperclipai/server dev",
     "dev:ui": "pnpm --filter @paperclipai/ui dev",
@@ -18,25 +18,17 @@
     "db:backup": "./scripts/backup-db.sh",
     "paperclipai": "node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts",
     "build:npm": "./scripts/build-npm.sh",
-    "release:start": "./scripts/release-start.sh",
     "release": "./scripts/release.sh",
-    "release:preflight": "./scripts/release-preflight.sh",
-    "release:github": "./scripts/create-github-release.sh",
-    "release:rollback": "./scripts/rollback-latest.sh",
     "changeset": "changeset",
     "version-packages": "changeset version",
     "check:tokens": "node scripts/check-forbidden-tokens.mjs",
     "docs:dev": "cd docs && npx mintlify dev",
     "smoke:openclaw-join": "./scripts/smoke/openclaw-join.sh",
     "smoke:openclaw-docker-ui": "./scripts/smoke/openclaw-docker-ui.sh",
-    "smoke:openclaw-sse-standalone": "./scripts/smoke/openclaw-sse-standalone.sh",
-    "test:e2e": "npx playwright test --config tests/e2e/playwright.config.ts",
-    "test:e2e:headed": "npx playwright test --config tests/e2e/playwright.config.ts --headed"
+    "smoke:openclaw-sse-standalone": "./scripts/smoke/openclaw-sse-standalone.sh"
   },
   "devDependencies": {
     "@changesets/cli": "^2.30.0",
-    "cross-env": "^10.1.0",
-    "@playwright/test": "^1.58.2",
     "esbuild": "^0.27.3",
     "typescript": "^5.7.3",
     "vitest": "^3.0.5"

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

@@ -15,11 +15,6 @@ interface RunningProcess {
   graceSec: number;
 }
 
-interface SpawnTarget {
-  command: string;
-  args: string[];
-}
-
 type ChildProcessWithEvents = ChildProcess & {
   on(event: "error", listener: (err: Error) => void): ChildProcess;
   on(
@@ -130,78 +125,6 @@ export function defaultPathForPlatform() {
   return "/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin";
 }
 
-function windowsPathExts(env: NodeJS.ProcessEnv): string[] {
-  return (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
-}
-
-async function pathExists(candidate: string) {
-  try {
-    await fs.access(candidate, process.platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function resolveCommandPath(command: string, cwd: string, env: NodeJS.ProcessEnv): Promise<string | null> {
-  const hasPathSeparator = command.includes("/") || command.includes("\\");
-  if (hasPathSeparator) {
-    const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
-    return (await pathExists(absolute)) ? absolute : null;
-  }
-
-  const pathValue = env.PATH ?? env.Path ?? "";
-  const delimiter = process.platform === "win32" ? ";" : ":";
-  const dirs = pathValue.split(delimiter).filter(Boolean);
-  const exts = process.platform === "win32" ? windowsPathExts(env) : [""];
-  const hasExtension = process.platform === "win32" && path.extname(command).length > 0;
-
-  for (const dir of dirs) {
-    const candidates =
-      process.platform === "win32"
-        ? hasExtension
-          ? [path.join(dir, command)]
-          : exts.map((ext) => path.join(dir, `${command}${ext}`))
-        : [path.join(dir, command)];
-    for (const candidate of candidates) {
-      if (await pathExists(candidate)) return candidate;
-    }
-  }
-
-  return null;
-}
-
-function quoteForCmd(arg: string) {
-  if (!arg.length) return '""';
-  const escaped = arg.replace(/"/g, '""');
-  return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
-}
-
-async function resolveSpawnTarget(
-  command: string,
-  args: string[],
-  cwd: string,
-  env: NodeJS.ProcessEnv,
-): Promise<SpawnTarget> {
-  const resolved = await resolveCommandPath(command, cwd, env);
-  const executable = resolved ?? command;
-
-  if (process.platform !== "win32") {
-    return { command: executable, args };
-  }
-
-  if (/\.(cmd|bat)$/i.test(executable)) {
-    const shell = env.ComSpec || process.env.ComSpec || "cmd.exe";
-    const commandLine = [quoteForCmd(executable), ...args.map(quoteForCmd)].join(" ");
-    return {
-      command: shell,
-      args: ["/d", "/s", "/c", commandLine],
-    };
-  }
-
-  return { command: executable, args };
-}
-
 export function ensurePathInEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   if (typeof env.PATH === "string" && env.PATH.length > 0) return env;
   if (typeof env.Path === "string" && env.Path.length > 0) return env;
@@ -246,12 +169,36 @@ export async function ensureAbsoluteDirectory(
 }
 
 export async function ensureCommandResolvable(command: string, cwd: string, env: NodeJS.ProcessEnv) {
-  const resolved = await resolveCommandPath(command, cwd, env);
-  if (resolved) return;
-  if (command.includes("/") || command.includes("\\")) {
+  const hasPathSeparator = command.includes("/") || command.includes("\\");
+  if (hasPathSeparator) {
     const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
-    throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
+    try {
+      await fs.access(absolute, fsConstants.X_OK);
+    } catch {
+      throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
+    }
+    return;
   }
+
+  const pathValue = env.PATH ?? env.Path ?? "";
+  const delimiter = process.platform === "win32" ? ";" : ":";
+  const dirs = pathValue.split(delimiter).filter(Boolean);
+  const windowsExt = process.platform === "win32"
+    ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""];
+
+  for (const dir of dirs) {
+    for (const ext of windowsExt) {
+      const candidate = path.join(dir, process.platform === "win32" ? `${command}${ext}` : command);
+      try {
+        await fs.access(candidate, fsConstants.X_OK);
+        return;
+      } catch {
+        // continue scanning PATH
+      }
+    }
+  }
+
   throw new Error(`Command not found in PATH: "${command}"`);
 }
 
@@ -273,82 +220,78 @@ export async function runChildProcess(
 
   return new Promise<RunProcessResult>((resolve, reject) => {
     const mergedEnv = ensurePathInEnv({ ...process.env, ...opts.env });
-    void resolveSpawnTarget(command, args, opts.cwd, mergedEnv)
-      .then((target) => {
-        const child = spawn(target.command, target.args, {
-          cwd: opts.cwd,
-          env: mergedEnv,
-          shell: false,
-          stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
-        }) as ChildProcessWithEvents;
+    const child = spawn(command, args, {
+      cwd: opts.cwd,
+      env: mergedEnv,
+      shell: false,
+      stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
+    }) as ChildProcessWithEvents;
 
-        if (opts.stdin != null && child.stdin) {
-          child.stdin.write(opts.stdin);
-          child.stdin.end();
-        }
+    if (opts.stdin != null && child.stdin) {
+      child.stdin.write(opts.stdin);
+      child.stdin.end();
+    }
 
-        runningProcesses.set(runId, { child, graceSec: opts.graceSec });
+    runningProcesses.set(runId, { child, graceSec: opts.graceSec });
 
-        let timedOut = false;
-        let stdout = "";
-        let stderr = "";
-        let logChain: Promise<void> = Promise.resolve();
+    let timedOut = false;
+    let stdout = "";
+    let stderr = "";
+    let logChain: Promise<void> = Promise.resolve();
 
-        const timeout =
-          opts.timeoutSec > 0
-            ? setTimeout(() => {
-                timedOut = true;
-                child.kill("SIGTERM");
-                setTimeout(() => {
-                  if (!child.killed) {
-                    child.kill("SIGKILL");
-                  }
-                }, Math.max(1, opts.graceSec) * 1000);
-              }, opts.timeoutSec * 1000)
-            : null;
+    const timeout =
+      opts.timeoutSec > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => {
+              if (!child.killed) {
+                child.kill("SIGKILL");
+              }
+            }, Math.max(1, opts.graceSec) * 1000);
+          }, opts.timeoutSec * 1000)
+        : null;
 
-        child.stdout?.on("data", (chunk: unknown) => {
-          const text = String(chunk);
-          stdout = appendWithCap(stdout, text);
-          logChain = logChain
-            .then(() => opts.onLog("stdout", text))
-            .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
+    child.stdout?.on("data", (chunk: unknown) => {
+      const text = String(chunk);
+      stdout = appendWithCap(stdout, text);
+      logChain = logChain
+        .then(() => opts.onLog("stdout", text))
+        .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
+    });
+
+    child.stderr?.on("data", (chunk: unknown) => {
+      const text = String(chunk);
+      stderr = appendWithCap(stderr, text);
+      logChain = logChain
+        .then(() => opts.onLog("stderr", text))
+        .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
+    });
+
+    child.on("error", (err: Error) => {
+      if (timeout) clearTimeout(timeout);
+      runningProcesses.delete(runId);
+      const errno = (err as NodeJS.ErrnoException).code;
+      const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
+      const msg =
+        errno === "ENOENT"
+          ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).`
+          : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
+      reject(new Error(msg));
+    });
+
+    child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
+      if (timeout) clearTimeout(timeout);
+      runningProcesses.delete(runId);
+      void logChain.finally(() => {
+        resolve({
+          exitCode: code,
+          signal,
+          timedOut,
+          stdout,
+          stderr,
         });
-
-        child.stderr?.on("data", (chunk: unknown) => {
-          const text = String(chunk);
-          stderr = appendWithCap(stderr, text);
-          logChain = logChain
-            .then(() => opts.onLog("stderr", text))
-            .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
-        });
-
-        child.on("error", (err: Error) => {
-          if (timeout) clearTimeout(timeout);
-          runningProcesses.delete(runId);
-          const errno = (err as NodeJS.ErrnoException).code;
-          const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
-          const msg =
-            errno === "ENOENT"
-              ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).`
-              : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
-          reject(new Error(msg));
-        });
-
-        child.on("close", (code: number | null, signal: NodeJS.Signals | null) => {
-          if (timeout) clearTimeout(timeout);
-          runningProcesses.delete(runId);
-          void logChain.finally(() => {
-            resolve({
-              exitCode: code,
-              signal,
-              timedOut,
-              stdout,
-              stderr,
-            });
-          });
-        });
-      })
-      .catch(reject);
+      });
+    });
   });
 }

packages/adapter-utils/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

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

@@ -3,8 +3,6 @@ export const label = "Claude Code (local)";
 
 export const models = [
   { id: "claude-opus-4-6", label: "Claude Opus 4.6" },
-  { id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6" },
-  { id: "claude-haiku-4-6", label: "Claude Haiku 4.6" },
   { id: "claude-sonnet-4-5-20250929", label: "Claude Sonnet 4.5" },
   { id: "claude-haiku-4-5-20251001", label: "Claude Haiku 4.5" },
 ];

packages/adapters/claude-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/codex-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/cursor-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src",

packages/adapters/openclaw-gateway/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/opencode-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/adapters/pi-local/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/db/src/client.ts

@@ -2,13 +2,12 @@ import { createHash } from "node:crypto";
 import { drizzle as drizzlePg } from "drizzle-orm/postgres-js";
 import { migrate as migratePg } from "drizzle-orm/postgres-js/migrator";
 import { readFile, readdir } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
 import postgres from "postgres";
 import * as schema from "./schema/index.js";
 
-const MIGRATIONS_FOLDER = fileURLToPath(new URL("./migrations", import.meta.url));
+const MIGRATIONS_FOLDER = new URL("./migrations", import.meta.url).pathname;
 const DRIZZLE_MIGRATIONS_TABLE = "__drizzle_migrations";
-const MIGRATIONS_JOURNAL_JSON = fileURLToPath(new URL("./migrations/meta/_journal.json", import.meta.url));
+const MIGRATIONS_JOURNAL_JSON = new URL("./migrations/meta/_journal.json", import.meta.url).pathname;
 
 function isSafeIdentifier(value: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
@@ -703,7 +702,8 @@ export async function migratePostgresIfEmpty(url: string): Promise<MigrationBoot
     }
 
     const db = drizzlePg(sql);
-    await migratePg(db, { migrationsFolder: MIGRATIONS_FOLDER });
+    const migrationsFolder = new URL("./migrations", import.meta.url).pathname;
+    await migratePg(db, { migrationsFolder });
 
     return { migrated: true, reason: "migrated-empty-db", tableCount: 0 };
   } finally {

packages/db/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

packages/shared/src/config-schema.ts

@@ -55,7 +55,6 @@ export const serverConfigSchema = z.object({
 export const authConfigSchema = z.object({
   baseUrlMode: z.enum(AUTH_BASE_URL_MODES).default("auto"),
   publicBaseUrl: z.string().url().optional(),
-  disableSignUp: z.boolean().default(false),
 });
 
 export const storageLocalDiskConfigSchema = z.object({
@@ -104,7 +103,6 @@ export const paperclipConfigSchema = z
     server: serverConfigSchema,
     auth: authConfigSchema.default({
       baseUrlMode: "auto",
-      disableSignUp: false,
     }),
     storage: storageConfigSchema.default({
       provider: "local_disk",

packages/shared/src/constants.ts

@@ -48,20 +48,6 @@ export const AGENT_ROLES = [
 ] as const;
 export type AgentRole = (typeof AGENT_ROLES)[number];
 
-export const AGENT_ROLE_LABELS: Record<AgentRole, string> = {
-  ceo: "CEO",
-  cto: "CTO",
-  cmo: "CMO",
-  cfo: "CFO",
-  engineer: "Engineer",
-  designer: "Designer",
-  pm: "PM",
-  qa: "QA",
-  devops: "DevOps",
-  researcher: "Researcher",
-  general: "General",
-};
-
 export const AGENT_ICON_NAMES = [
   "bot",
   "cpu",

packages/shared/src/index.ts

@@ -6,7 +6,6 @@ export {
   AGENT_STATUSES,
   AGENT_ADAPTER_TYPES,
   AGENT_ROLES,
-  AGENT_ROLE_LABELS,
   AGENT_ICON_NAMES,
   ISSUE_STATUSES,
   ISSUE_PRIORITIES,

packages/shared/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

pnpm-lock.yaml

@@ -11,9 +11,6 @@ importers:
       '@changesets/cli':
         specifier: ^2.30.0
         version: 2.30.0(@types/node@25.2.3)
-      '@playwright/test':
-        specifier: ^1.58.2
-        version: 1.58.2
       esbuild:
         specifier: ^0.27.3
         version: 0.27.3
@@ -38,6 +35,9 @@ importers:
       '@paperclipai/adapter-cursor-local':
         specifier: workspace:*
         version: link:../packages/adapters/cursor-local
+      '@paperclipai/adapter-openclaw':
+        specifier: workspace:*
+        version: link:../packages/adapters/openclaw
       '@paperclipai/adapter-openclaw-gateway':
         specifier: workspace:*
         version: link:../packages/adapters/openclaw-gateway
@@ -139,6 +139,22 @@ importers:
         specifier: ^5.7.3
         version: 5.9.3
 
+  packages/adapters/openclaw:
+    dependencies:
+      '@paperclipai/adapter-utils':
+        specifier: workspace:*
+        version: link:../../adapter-utils
+      picocolors:
+        specifier: ^1.1.1
+        version: 1.1.1
+    devDependencies:
+      '@types/node':
+        specifier: ^24.6.0
+        version: 24.12.0
+      typescript:
+        specifier: ^5.7.3
+        version: 5.9.3
+
   packages/adapters/openclaw-gateway:
     dependencies:
       '@paperclipai/adapter-utils':
@@ -245,6 +261,9 @@ importers:
       '@paperclipai/adapter-cursor-local':
         specifier: workspace:*
         version: link:../packages/adapters/cursor-local
+      '@paperclipai/adapter-openclaw':
+        specifier: workspace:*
+        version: link:../packages/adapters/openclaw
       '@paperclipai/adapter-openclaw-gateway':
         specifier: workspace:*
         version: link:../packages/adapters/openclaw-gateway
@@ -360,6 +379,9 @@ importers:
       '@paperclipai/adapter-cursor-local':
         specifier: workspace:*
         version: link:../packages/adapters/cursor-local
+      '@paperclipai/adapter-openclaw':
+        specifier: workspace:*
+        version: link:../packages/adapters/openclaw
       '@paperclipai/adapter-openclaw-gateway':
         specifier: workspace:*
         version: link:../packages/adapters/openclaw-gateway
@@ -1674,11 +1696,6 @@ packages:
   '@pinojs/redact@0.4.0':
     resolution: {integrity: sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==}
 
-  '@playwright/test@1.58.2':
-    resolution: {integrity: sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA==}
-    engines: {node: '>=18'}
-    hasBin: true
-
   '@radix-ui/colors@3.0.0':
     resolution: {integrity: sha512-FUOsGBkHrYJwCSEtWRCIfQbZG7q1e6DgxCIOe1SUQzDe/7rXXeA47s8yCn6fuTNQAj1Zq4oTFi9Yjp3wzElcxg==}
 
@@ -3995,11 +4012,6 @@ packages:
     resolution: {integrity: sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==}
     engines: {node: '>=6 <7 || >=8'}
 
-  fsevents@2.3.2:
-    resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==}
-    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
-    os: [darwin]
-
   fsevents@2.3.3:
     resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
     engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
@@ -4786,16 +4798,6 @@ packages:
   pkg-types@1.3.1:
     resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==}
 
-  playwright-core@1.58.2:
-    resolution: {integrity: sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==}
-    engines: {node: '>=18'}
-    hasBin: true
-
-  playwright@1.58.2:
-    resolution: {integrity: sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==}
-    engines: {node: '>=18'}
-    hasBin: true
-
   points-on-curve@0.2.0:
     resolution: {integrity: sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==}
 
@@ -7392,10 +7394,6 @@ snapshots:
 
   '@pinojs/redact@0.4.0': {}
 
-  '@playwright/test@1.58.2':
-    dependencies:
-      playwright: 1.58.2
-
   '@radix-ui/colors@3.0.0': {}
 
   '@radix-ui/number@1.1.1': {}
@@ -9874,9 +9872,6 @@ snapshots:
       jsonfile: 4.0.0
       universalify: 0.1.2
 
-  fsevents@2.3.2:
-    optional: true
-
   fsevents@2.3.3:
     optional: true
 
@@ -10928,14 +10923,6 @@ snapshots:
       mlly: 1.8.1
       pathe: 2.0.3
 
-  playwright-core@1.58.2: {}
-
-  playwright@1.58.2:
-    dependencies:
-      playwright-core: 1.58.2
-    optionalDependencies:
-      fsevents: 2.3.2
-
   points-on-curve@0.2.0: {}
 
   points-on-path@0.2.1:

releases/v0.3.0.md

@@ -1,53 +0,0 @@
-# v0.3.0
-
-> Released: 2026-03-09
-
-## Highlights
-
-- **New adapters: Cursor, OpenCode, and Pi** — Paperclip now supports three additional local coding agents. Cursor and OpenCode integrate as first-class adapters with model discovery, run-log streaming, and skill injection. Pi adds a local RPC mode with cost tracking. All three appear in the onboarding wizard alongside Claude Code and Codex. ([#62](https://github.com/paperclipai/paperclip/pull/62), [#141](https://github.com/paperclipai/paperclip/pull/141), [#240](https://github.com/paperclipai/paperclip/pull/240), [#183](https://github.com/paperclipai/paperclip/pull/183), @aaaaron, @Konan69, @richardanaya)
-- **OpenClaw gateway adapter** — A new gateway-only OpenClaw flow replaces the legacy adapter. It uses strict SSE streaming, supports device-key pairing, and handles invite-based onboarding with join-token validation. ([#270](https://github.com/paperclipai/paperclip/pull/270))
-- **Inbox and unread semantics** — Issues now track per-user read state. Unread indicators appear in the inbox, dashboard, and browser tab (blue dot). The inbox badge includes join requests and approvals, and inbox ordering is alert-focused. ([#196](https://github.com/paperclipai/paperclip/pull/196), @hougangdev)
-- **PWA support** — The UI ships as an installable Progressive Web App with a service worker and enhanced manifest. The service worker uses a network-first strategy to prevent stale content.
-- **Agent creation wizard** — A new choice modal and full-page configuration flow make it easier to add agents. The sidebar AGENTS header now has a quick-add button.
-
-## Improvements
-
-- **Mermaid diagrams in markdown** — Fenced `mermaid` blocks render as diagrams in issue comments and descriptions.
-- **Live run output** — Run detail pages stream output over WebSocket in real time, with coalesced deltas and deduplicated feed items.
-- **Copy comment as Markdown** — Each comment header has a one-click copy-as-markdown button.
-- **Retry failed runs** — Failed and timed-out runs now show a Retry button on the run detail page.
-- **Project status clickable** — The status chip in the project properties pane is now clickable for quick updates.
-- **Scroll-to-bottom button** — Issue detail and run pages show a floating scroll-to-bottom button when you scroll up.
-- **Database backup CLI** — `paperclipai db:backup` lets you snapshot the database on demand, with optional automatic scheduling.
-- **Disable sign-up** — A new `auth.disableSignUp` config option (and `AUTH_DISABLE_SIGNUP` env var) lets operators lock registration. ([#279](https://github.com/paperclipai/paperclip/pull/279), @JasonOA888)
-- **Deduplicated shortnames** — Agent and project shortnames are now auto-deduplicated on create and update instead of rejecting duplicates. ([#264](https://github.com/paperclipai/paperclip/pull/264), @mvanhorn)
-- **Human-readable role labels** — The agent list and properties pane show friendly role names. ([#263](https://github.com/paperclipai/paperclip/pull/263), @mvanhorn)
-- **Assignee picker sorting** — Recent selections appear first, then alphabetical.
-- **Mobile layout polish** — Unified GitHub-style issue rows across issues, inbox, and dashboard. Improved popover scrolling, command palette centering, and property toggles on mobile. ([#118](https://github.com/paperclipai/paperclip/pull/118), @MumuTW)
-- **Invite UX improvements** — Invite links auto-copy to clipboard, snippet-only flow in settings, 10-minute invite TTL, and clearer network-host guidance.
-- **Permalink anchors on comments** — Each comment has a stable anchor link and a GET-by-ID API endpoint.
-- **Docker deployment hardening** — Authenticated deployment mode by default, named data volume, `PAPERCLIP_PUBLIC_URL` and `PAPERCLIP_ALLOWED_HOSTNAMES` exposed in compose files, health-check DB wait, and Node 24 base image. ([#400](https://github.com/paperclipai/paperclip/pull/400), [#283](https://github.com/paperclipai/paperclip/pull/283), [#284](https://github.com/paperclipai/paperclip/pull/284), @AiMagic5000, @mingfang)
-- **Updated model lists** — Added `claude-sonnet-4-6`, `claude-haiku-4-6`, and `gpt-5.4` to adapter model constants. ([#293](https://github.com/paperclipai/paperclip/pull/293), [#110](https://github.com/paperclipai/paperclip/pull/110), @cpfarhood, @artokun)
-- **Playwright e2e tests** — New end-to-end test suite covering the onboarding wizard flow.
-
-## Fixes
-
-- **Secret redaction in run logs** — Env vars sourced from secrets are now redacted by provenance, with consistent `secretKeys` tracking. ([#261](https://github.com/paperclipai/paperclip/pull/261), @mvanhorn)
-- **SPA catch-all 500s** — The server serves cached `index.html` in the catch-all route and uses `root` in `sendFile`, preventing 500 errors on dotfile paths and SPA refreshes. ([#269](https://github.com/paperclipai/paperclip/pull/269), [#78](https://github.com/paperclipai/paperclip/pull/78), @mvanhorn, @MumuTW)
-- **Unmatched API routes return 404 JSON** — Previously fell through to the SPA handler. ([#269](https://github.com/paperclipai/paperclip/pull/269), @mvanhorn)
-- **Agent wake logic** — Agents wake when issues move out of backlog, skip self-wake on own comments, and skip wakeup for backlog-status changes. Pending-approval agents are excluded from heartbeat timers. ([#159](https://github.com/paperclipai/paperclip/pull/159), [#154](https://github.com/paperclipai/paperclip/pull/154), [#267](https://github.com/paperclipai/paperclip/pull/267), [#72](https://github.com/paperclipai/paperclip/pull/72), @Logesh-waran2003, @cschneid, @mvanhorn, @STRML)
-- **Run log fd leak** — Fixed a file-descriptor leak in log append that caused `spawn EBADF` errors. ([#266](https://github.com/paperclipai/paperclip/pull/266), @mvanhorn)
-- **500 error logging** — Error logs now include the actual error message and request context instead of generic pino-http output.
-- **Boolean env parsing** — `parseBooleanFromEnv` no longer silently treats common truthy values as false. ([#91](https://github.com/paperclipai/paperclip/pull/91), @zvictor)
-- **Onboarding env defaults** — `onboard` now correctly derives secrets from env vars and reports ignored exposure settings in `local_trusted` mode. ([#91](https://github.com/paperclipai/paperclip/pull/91), @zvictor)
-- **Windows path compatibility** — Migration paths use `fileURLToPath` for Windows-safe resolution. ([#265](https://github.com/paperclipai/paperclip/pull/265), [#413](https://github.com/paperclipai/paperclip/pull/413), @mvanhorn, @online5880)
-- **Secure cookies on HTTP** — Disabled secure cookie flag for plain HTTP deployments to prevent auth failures. ([#376](https://github.com/paperclipai/paperclip/pull/376), @dalestubblefield)
-- **URL encoding** — `buildUrl` splits path and query to prevent `%3F` encoding issues. ([#260](https://github.com/paperclipai/paperclip/pull/260), @mvanhorn)
-- **Auth trusted origins** — Effective trusted origins and allowed hostnames are now applied correctly in public mode. ([#99](https://github.com/paperclipai/paperclip/pull/99), @zvictor)
-- **UI stability** — Fixed blank screen when prompt templates are emptied, search URL sync causing re-renders, issue title overflow in inbox, and sidebar badge counts including approvals. ([#262](https://github.com/paperclipai/paperclip/pull/262), [#196](https://github.com/paperclipai/paperclip/pull/196), [#423](https://github.com/paperclipai/paperclip/pull/423), @mvanhorn, @hougangdev, @RememberV)
-
-## Contributors
-
-Thank you to everyone who contributed to this release!
-
-@aaaaron, @AiMagic5000, @artokun, @cpfarhood, @cschneid, @dalestubblefield, @Dotta, @eltociear, @fahmmin, @gsxdsm, @hougangdev, @JasonOA888, @Konan69, @Logesh-waran2003, @mingfang, @MumuTW, @mvanhorn, @numman-ali, @online5880, @RememberV, @richardanaya, @STRML, @tylerwince, @zvictor

scripts/clean-onboard-git.sh

@@ -7,7 +7,7 @@ mkdir -p "$PC_HOME" "$PC_CACHE" "$PC_DATA"
 echo "PC_TEST_ROOT: $PC_TEST_ROOT"
 echo "PC_HOME: $PC_HOME"
 cd $PC_TEST_ROOT
-git clone https://github.com/paperclipai/paperclip.git repo
+git clone github.com:paperclipai/paperclip.git repo
 cd repo
 pnpm install
 env HOME="$PC_HOME" npm_config_cache="$PC_CACHE" npm_config_userconfig="$PC_HOME/.npmrc" \

scripts/clean-onboard-ref.sh

@@ -1,86 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-TARGET_REF="${1:-HEAD}"
-
-usage() {
-  cat <<'EOF'
-Usage:
-  ./scripts/clean-onboard-ref.sh [git-ref]
-
-Examples:
-  ./scripts/clean-onboard-ref.sh
-  ./scripts/clean-onboard-ref.sh HEAD
-  ./scripts/clean-onboard-ref.sh v0.2.7
-
-Environment overrides:
-  KEEP_TEMP=1                 Keep the temp directory and detached worktree for debugging
-  PC_TEST_ROOT=/tmp/custom    Base temp directory to use
-  PC_DATA=/tmp/data           Paperclip data dir to use
-  PAPERCLIP_HOST=127.0.0.1    Host passed to the onboarded server
-  PAPERCLIP_PORT=3232         Port passed to the onboarded server
-
-Notes:
-  - Defaults to the current committed ref (HEAD), not uncommitted local edits.
-  - Creates an isolated temp HOME, npm cache, data dir, and detached git worktree.
-EOF
-}
-
-if [ $# -gt 1 ]; then
-  usage
-  exit 1
-fi
-
-if [ $# -eq 1 ] && [[ "$1" =~ ^(-h|--help)$ ]]; then
-  usage
-  exit 0
-fi
-
-TARGET_COMMIT="$(git -C "$REPO_ROOT" rev-parse --verify "${TARGET_REF}^{commit}")"
-
-export KEEP_TEMP="${KEEP_TEMP:-0}"
-export PC_TEST_ROOT="${PC_TEST_ROOT:-$(mktemp -d /tmp/paperclip-clean-ref.XXXXXX)}"
-export PC_HOME="${PC_HOME:-$PC_TEST_ROOT/home}"
-export PC_CACHE="${PC_CACHE:-$PC_TEST_ROOT/npm-cache}"
-export PC_DATA="${PC_DATA:-$PC_TEST_ROOT/paperclip-data}"
-export PC_REPO="${PC_REPO:-$PC_TEST_ROOT/repo}"
-export PAPERCLIP_HOST="${PAPERCLIP_HOST:-127.0.0.1}"
-export PAPERCLIP_PORT="${PAPERCLIP_PORT:-3100}"
-export PAPERCLIP_OPEN_ON_LISTEN="${PAPERCLIP_OPEN_ON_LISTEN:-false}"
-
-cleanup() {
-  if [ "$KEEP_TEMP" = "1" ]; then
-    return
-  fi
-
-  git -C "$REPO_ROOT" worktree remove --force "$PC_REPO" >/dev/null 2>&1 || true
-  rm -rf "$PC_TEST_ROOT"
-}
-
-trap cleanup EXIT
-
-mkdir -p "$PC_HOME" "$PC_CACHE" "$PC_DATA"
-
-echo "TARGET_REF: $TARGET_REF"
-echo "TARGET_COMMIT: $TARGET_COMMIT"
-echo "PC_TEST_ROOT: $PC_TEST_ROOT"
-echo "PC_HOME: $PC_HOME"
-echo "PC_DATA: $PC_DATA"
-echo "PC_REPO: $PC_REPO"
-echo "PAPERCLIP_HOST: $PAPERCLIP_HOST"
-echo "PAPERCLIP_PORT: $PAPERCLIP_PORT"
-
-git -C "$REPO_ROOT" worktree add --detach "$PC_REPO" "$TARGET_COMMIT"
-
-cd "$PC_REPO"
-pnpm install
-
-env \
-  HOME="$PC_HOME" \
-  npm_config_cache="$PC_CACHE" \
-  npm_config_userconfig="$PC_HOME/.npmrc" \
-  HOST="$PAPERCLIP_HOST" \
-  PORT="$PAPERCLIP_PORT" \
-  PAPERCLIP_OPEN_ON_LISTEN="$PAPERCLIP_OPEN_ON_LISTEN" \
-  pnpm paperclipai onboard --yes --data-dir "$PC_DATA"

scripts/create-github-release.sh

@@ -1,89 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-# shellcheck source=./release-lib.sh
-. "$REPO_ROOT/scripts/release-lib.sh"
-
-dry_run=false
-version=""
-
-usage() {
-  cat <<'EOF'
-Usage:
-  ./scripts/create-github-release.sh <version> [--dry-run]
-
-Examples:
-  ./scripts/create-github-release.sh 1.2.3
-  ./scripts/create-github-release.sh 1.2.3 --dry-run
-
-Notes:
-  - Run this after pushing the stable release branch and tag.
-  - If the release already exists, this script updates its title and notes.
-EOF
-}
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --dry-run) dry_run=true ;;
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    *)
-      if [ -n "$version" ]; then
-        echo "Error: only one version may be provided." >&2
-        exit 1
-      fi
-      version="$1"
-      ;;
-  esac
-  shift
-done
-
-if [ -z "$version" ]; then
-  usage
-  exit 1
-fi
-
-if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-  echo "Error: version must be a stable semver like 1.2.3." >&2
-  exit 1
-fi
-
-tag="v$version"
-notes_file="$REPO_ROOT/releases/${tag}.md"
-PUBLISH_REMOTE="$(resolve_release_remote)"
-
-if ! command -v gh >/dev/null 2>&1; then
-  echo "Error: gh CLI is required to create GitHub releases." >&2
-  exit 1
-fi
-
-if [ ! -f "$notes_file" ]; then
-  echo "Error: release notes file not found at $notes_file." >&2
-  exit 1
-fi
-
-if ! git -C "$REPO_ROOT" rev-parse "$tag" >/dev/null 2>&1; then
-  echo "Error: local git tag $tag does not exist." >&2
-  exit 1
-fi
-
-if [ "$dry_run" = true ]; then
-  echo "[dry-run] gh release create $tag --title $tag --notes-file $notes_file"
-  exit 0
-fi
-
-if ! git -C "$REPO_ROOT" ls-remote --exit-code --tags "$PUBLISH_REMOTE" "refs/tags/$tag" >/dev/null 2>&1; then
-  echo "Error: remote tag $tag was not found on $PUBLISH_REMOTE. Push the release commit and tag first." >&2
-  exit 1
-fi
-
-if gh release view "$tag" >/dev/null 2>&1; then
-  gh release edit "$tag" --title "$tag" --notes-file "$notes_file"
-  echo "Updated GitHub Release $tag"
-else
-  gh release create "$tag" --title "$tag" --notes-file "$notes_file"
-  echo "Created GitHub Release $tag"
-fi

scripts/dev-runner.mjs

@@ -47,7 +47,7 @@ const serverScript = mode === "watch" ? "dev:watch" : "dev";
 const child = spawn(
   pnpmBin,
   ["--filter", "@paperclipai/server", serverScript, ...forwardedArgs],
-  { stdio: "inherit", env, shell: process.platform === "win32" },
+  { stdio: "inherit", env },
 );
 
 child.on("exit", (code, signal) => {

scripts/docker-onboard-smoke.sh

@@ -9,199 +9,14 @@ DATA_DIR="${DATA_DIR:-$REPO_ROOT/data/docker-onboard-smoke}"
 HOST_UID="${HOST_UID:-$(id -u)}"
 PAPERCLIP_DEPLOYMENT_MODE="${PAPERCLIP_DEPLOYMENT_MODE:-authenticated}"
 PAPERCLIP_DEPLOYMENT_EXPOSURE="${PAPERCLIP_DEPLOYMENT_EXPOSURE:-private}"
-PAPERCLIP_PUBLIC_URL="${PAPERCLIP_PUBLIC_URL:-http://localhost:${HOST_PORT}}"
-SMOKE_AUTO_BOOTSTRAP="${SMOKE_AUTO_BOOTSTRAP:-true}"
-SMOKE_ADMIN_NAME="${SMOKE_ADMIN_NAME:-Smoke Admin}"
-SMOKE_ADMIN_EMAIL="${SMOKE_ADMIN_EMAIL:-smoke-admin@paperclip.local}"
-SMOKE_ADMIN_PASSWORD="${SMOKE_ADMIN_PASSWORD:-paperclip-smoke-password}"
-CONTAINER_NAME="${IMAGE_NAME//[^a-zA-Z0-9_.-]/-}"
-LOG_PID=""
-COOKIE_JAR=""
-TMP_DIR=""
+DOCKER_TTY_ARGS=()
+
+if [[ -t 0 && -t 1 ]]; then
+  DOCKER_TTY_ARGS=(-it)
+fi
 
 mkdir -p "$DATA_DIR"
 
-cleanup() {
-  if [[ -n "$LOG_PID" ]]; then
-    kill "$LOG_PID" >/dev/null 2>&1 || true
-  fi
-  docker stop "$CONTAINER_NAME" >/dev/null 2>&1 || true
-  if [[ -n "$TMP_DIR" && -d "$TMP_DIR" ]]; then
-    rm -rf "$TMP_DIR"
-  fi
-}
-
-trap cleanup EXIT INT TERM
-
-wait_for_http() {
-  local url="$1"
-  local attempts="${2:-60}"
-  local sleep_seconds="${3:-1}"
-  local i
-  for ((i = 1; i <= attempts; i += 1)); do
-    if curl -fsS "$url" >/dev/null 2>&1; then
-      return 0
-    fi
-    sleep "$sleep_seconds"
-  done
-  return 1
-}
-
-generate_bootstrap_invite_url() {
-  local bootstrap_output
-  local bootstrap_status
-  if bootstrap_output="$(
-    docker exec \
-      -e PAPERCLIP_DEPLOYMENT_MODE="$PAPERCLIP_DEPLOYMENT_MODE" \
-      -e PAPERCLIP_DEPLOYMENT_EXPOSURE="$PAPERCLIP_DEPLOYMENT_EXPOSURE" \
-      -e PAPERCLIP_PUBLIC_URL="$PAPERCLIP_PUBLIC_URL" \
-      -e PAPERCLIP_HOME="/paperclip" \
-      "$CONTAINER_NAME" bash -lc \
-      'timeout 20s npx --yes "paperclipai@${PAPERCLIPAI_VERSION}" auth bootstrap-ceo --data-dir "$PAPERCLIP_HOME" --base-url "$PAPERCLIP_PUBLIC_URL"' \
-      2>&1
-  )"; then
-    bootstrap_status=0
-  else
-    bootstrap_status=$?
-  fi
-
-  if [[ $bootstrap_status -ne 0 && $bootstrap_status -ne 124 ]]; then
-    echo "Smoke bootstrap failed: could not run bootstrap-ceo inside container" >&2
-    printf '%s\n' "$bootstrap_output" >&2
-    return 1
-  fi
-
-  local invite_url
-  invite_url="$(
-    printf '%s\n' "$bootstrap_output" \
-      | grep -o 'https\?://[^[:space:]]*/invite/pcp_bootstrap_[[:alnum:]]*' \
-      | tail -n 1
-  )"
-
-  if [[ -z "$invite_url" ]]; then
-    echo "Smoke bootstrap failed: bootstrap-ceo did not print an invite URL" >&2
-    printf '%s\n' "$bootstrap_output" >&2
-    return 1
-  fi
-
-  if [[ $bootstrap_status -eq 124 ]]; then
-    echo "    Smoke bootstrap: bootstrap-ceo timed out after printing invite URL; continuing" >&2
-  fi
-
-  printf '%s\n' "$invite_url"
-}
-
-post_json_with_cookies() {
-  local url="$1"
-  local body="$2"
-  local output_file="$3"
-  curl -sS \
-    -o "$output_file" \
-    -w "%{http_code}" \
-    -c "$COOKIE_JAR" \
-    -b "$COOKIE_JAR" \
-    -H "Content-Type: application/json" \
-    -H "Origin: $PAPERCLIP_PUBLIC_URL" \
-    -X POST \
-    "$url" \
-    --data "$body"
-}
-
-get_with_cookies() {
-  local url="$1"
-  curl -fsS \
-    -c "$COOKIE_JAR" \
-    -b "$COOKIE_JAR" \
-    -H "Accept: application/json" \
-    "$url"
-}
-
-sign_up_or_sign_in() {
-  local signup_response="$TMP_DIR/signup.json"
-  local signup_status
-  signup_status="$(post_json_with_cookies \
-    "$PAPERCLIP_PUBLIC_URL/api/auth/sign-up/email" \
-    "{\"name\":\"$SMOKE_ADMIN_NAME\",\"email\":\"$SMOKE_ADMIN_EMAIL\",\"password\":\"$SMOKE_ADMIN_PASSWORD\"}" \
-    "$signup_response")"
-  if [[ "$signup_status" =~ ^2 ]]; then
-    echo "    Smoke bootstrap: created admin user $SMOKE_ADMIN_EMAIL"
-    return 0
-  fi
-
-  local signin_response="$TMP_DIR/signin.json"
-  local signin_status
-  signin_status="$(post_json_with_cookies \
-    "$PAPERCLIP_PUBLIC_URL/api/auth/sign-in/email" \
-    "{\"email\":\"$SMOKE_ADMIN_EMAIL\",\"password\":\"$SMOKE_ADMIN_PASSWORD\"}" \
-    "$signin_response")"
-  if [[ "$signin_status" =~ ^2 ]]; then
-    echo "    Smoke bootstrap: signed in existing admin user $SMOKE_ADMIN_EMAIL"
-    return 0
-  fi
-
-  echo "Smoke bootstrap failed: could not sign up or sign in admin user" >&2
-  echo "Sign-up response:" >&2
-  cat "$signup_response" >&2 || true
-  echo >&2
-  echo "Sign-in response:" >&2
-  cat "$signin_response" >&2 || true
-  echo >&2
-  return 1
-}
-
-auto_bootstrap_authenticated_smoke() {
-  local health_url="$PAPERCLIP_PUBLIC_URL/api/health"
-  local health_json
-  health_json="$(curl -fsS "$health_url")"
-  if [[ "$health_json" != *'"deploymentMode":"authenticated"'* ]]; then
-    return 0
-  fi
-
-  sign_up_or_sign_in
-
-  if [[ "$health_json" == *'"bootstrapStatus":"ready"'* ]]; then
-    echo "    Smoke bootstrap: instance already ready"
-  else
-    local invite_url
-    invite_url="$(generate_bootstrap_invite_url)"
-    echo "    Smoke bootstrap: generated bootstrap invite via auth bootstrap-ceo"
-
-    local invite_token="${invite_url##*/}"
-    local accept_response="$TMP_DIR/accept.json"
-    local accept_status
-    accept_status="$(post_json_with_cookies \
-      "$PAPERCLIP_PUBLIC_URL/api/invites/$invite_token/accept" \
-      '{"requestType":"human"}' \
-      "$accept_response")"
-    if [[ ! "$accept_status" =~ ^2 ]]; then
-      echo "Smoke bootstrap failed: bootstrap invite acceptance returned HTTP $accept_status" >&2
-      cat "$accept_response" >&2 || true
-      echo >&2
-      return 1
-    fi
-    echo "    Smoke bootstrap: accepted bootstrap invite"
-  fi
-
-  local session_json
-  session_json="$(get_with_cookies "$PAPERCLIP_PUBLIC_URL/api/auth/get-session")"
-  if [[ "$session_json" != *'"userId"'* ]]; then
-    echo "Smoke bootstrap failed: no authenticated session after bootstrap" >&2
-    echo "$session_json" >&2
-    return 1
-  fi
-
-  local companies_json
-  companies_json="$(get_with_cookies "$PAPERCLIP_PUBLIC_URL/api/companies")"
-  if [[ "${companies_json:0:1}" != "[" ]]; then
-    echo "Smoke bootstrap failed: board companies endpoint did not return JSON array" >&2
-    echo "$companies_json" >&2
-    return 1
-  fi
-
-  echo "    Smoke bootstrap: board session verified"
-  echo "    Smoke admin credentials: $SMOKE_ADMIN_EMAIL / $SMOKE_ADMIN_PASSWORD"
-}
-
 echo "==> Building onboard smoke image"
 docker build \
   --build-arg PAPERCLIPAI_VERSION="$PAPERCLIPAI_VERSION" \
@@ -212,38 +27,16 @@ docker build \
 
 echo "==> Running onboard smoke container"
 echo "    UI should be reachable at: http://localhost:$HOST_PORT"
-echo "    Public URL: $PAPERCLIP_PUBLIC_URL"
-echo "    Smoke auto-bootstrap: $SMOKE_AUTO_BOOTSTRAP"
 echo "    Data dir: $DATA_DIR"
 echo "    Deployment: $PAPERCLIP_DEPLOYMENT_MODE/$PAPERCLIP_DEPLOYMENT_EXPOSURE"
 echo "    Live output: onboard banner and server logs stream in this terminal (Ctrl+C to stop)"
-
-docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
-
-docker run -d --rm \
-  --name "$CONTAINER_NAME" \
+docker run --rm \
+  "${DOCKER_TTY_ARGS[@]}" \
+  --name "${IMAGE_NAME//[^a-zA-Z0-9_.-]/-}" \
   -p "$HOST_PORT:3100" \
   -e HOST=0.0.0.0 \
   -e PORT=3100 \
   -e PAPERCLIP_DEPLOYMENT_MODE="$PAPERCLIP_DEPLOYMENT_MODE" \
   -e PAPERCLIP_DEPLOYMENT_EXPOSURE="$PAPERCLIP_DEPLOYMENT_EXPOSURE" \
-  -e PAPERCLIP_PUBLIC_URL="$PAPERCLIP_PUBLIC_URL" \
   -v "$DATA_DIR:/paperclip" \
-  "$IMAGE_NAME" >/dev/null
-
-docker logs -f "$CONTAINER_NAME" &
-LOG_PID=$!
-
-TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/paperclip-onboard-smoke.XXXXXX")"
-COOKIE_JAR="$TMP_DIR/cookies.txt"
-
-if ! wait_for_http "$PAPERCLIP_PUBLIC_URL/api/health" 90 1; then
-  echo "Smoke bootstrap failed: server did not become ready at $PAPERCLIP_PUBLIC_URL/api/health" >&2
-  exit 1
-fi
-
-if [[ "$SMOKE_AUTO_BOOTSTRAP" == "true" && "$PAPERCLIP_DEPLOYMENT_MODE" == "authenticated" ]]; then
-  auto_bootstrap_authenticated_smoke
-fi
-
-wait "$LOG_PID"
+  "$IMAGE_NAME"

scripts/prepare-server-ui-dist.sh

@@ -1,21 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# prepare-server-ui-dist.sh — Build the UI and copy it into server/ui-dist.
-# This keeps @paperclipai/server publish artifacts self-contained for static UI serving.
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-UI_DIST="$REPO_ROOT/ui/dist"
-SERVER_UI_DIST="$REPO_ROOT/server/ui-dist"
-
-echo "  -> Building @paperclipai/ui..."
-pnpm --dir "$REPO_ROOT" --filter @paperclipai/ui build
-
-if [ ! -f "$UI_DIST/index.html" ]; then
-  echo "Error: UI build output missing at $UI_DIST/index.html"
-  exit 1
-fi
-
-rm -rf "$SERVER_UI_DIST"
-cp -r "$UI_DIST" "$SERVER_UI_DIST"
-echo "  -> Copied ui/dist to server/ui-dist"

scripts/release-lib.sh

@@ -1,222 +0,0 @@
-#!/usr/bin/env bash
-
-if [ -z "${REPO_ROOT:-}" ]; then
-  REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-fi
-
-release_info() {
-  echo "$@"
-}
-
-release_warn() {
-  echo "Warning: $*" >&2
-}
-
-release_fail() {
-  echo "Error: $*" >&2
-  exit 1
-}
-
-git_remote_exists() {
-  git -C "$REPO_ROOT" remote get-url "$1" >/dev/null 2>&1
-}
-
-resolve_release_remote() {
-  local remote="${RELEASE_REMOTE:-${PUBLISH_REMOTE:-}}"
-
-  if [ -n "$remote" ]; then
-    git_remote_exists "$remote" || release_fail "git remote '$remote' does not exist."
-    printf '%s\n' "$remote"
-    return
-  fi
-
-  if git_remote_exists public-gh; then
-    printf 'public-gh\n'
-    return
-  fi
-
-  if git_remote_exists origin; then
-    printf 'origin\n'
-    return
-  fi
-
-  release_fail "no git remote found. Configure RELEASE_REMOTE or PUBLISH_REMOTE."
-}
-
-fetch_release_remote() {
-  git -C "$REPO_ROOT" fetch "$1" --prune --tags
-}
-
-get_last_stable_tag() {
-  git -C "$REPO_ROOT" tag --list 'v*' --sort=-version:refname | head -1
-}
-
-get_current_stable_version() {
-  local tag
-  tag="$(get_last_stable_tag)"
-  if [ -z "$tag" ]; then
-    printf '0.0.0\n'
-  else
-    printf '%s\n' "${tag#v}"
-  fi
-}
-
-compute_bumped_version() {
-  node - "$1" "$2" <<'NODE'
-const current = process.argv[2];
-const bump = process.argv[3];
-const match = current.match(/^(\d+)\.(\d+)\.(\d+)$/);
-
-if (!match) {
-  throw new Error(`invalid semver version: ${current}`);
-}
-
-let [major, minor, patch] = match.slice(1).map(Number);
-
-if (bump === 'patch') {
-  patch += 1;
-} else if (bump === 'minor') {
-  minor += 1;
-  patch = 0;
-} else if (bump === 'major') {
-  major += 1;
-  minor = 0;
-  patch = 0;
-} else {
-  throw new Error(`unsupported bump type: ${bump}`);
-}
-
-process.stdout.write(`${major}.${minor}.${patch}`);
-NODE
-}
-
-next_canary_version() {
-  local stable_version="$1"
-  local versions_json
-
-  versions_json="$(npm view paperclipai versions --json 2>/dev/null || echo '[]')"
-
-  node - "$stable_version" "$versions_json" <<'NODE'
-const stable = process.argv[2];
-const versionsArg = process.argv[3];
-
-let versions = [];
-try {
-  const parsed = JSON.parse(versionsArg);
-  versions = Array.isArray(parsed) ? parsed : [parsed];
-} catch {
-  versions = [];
-}
-
-const pattern = new RegExp(`^${stable.replace(/\./g, '\\.')}-canary\\.(\\d+)$`);
-let max = -1;
-
-for (const version of versions) {
-  const match = version.match(pattern);
-  if (!match) continue;
-  max = Math.max(max, Number(match[1]));
-}
-
-process.stdout.write(`${stable}-canary.${max + 1}`);
-NODE
-}
-
-release_branch_name() {
-  printf 'release/%s\n' "$1"
-}
-
-release_notes_file() {
-  printf '%s/releases/v%s.md\n' "$REPO_ROOT" "$1"
-}
-
-default_release_worktree_path() {
-  local version="$1"
-  local parent_dir
-  local repo_name
-
-  parent_dir="$(cd "$REPO_ROOT/.." && pwd)"
-  repo_name="$(basename "$REPO_ROOT")"
-  printf '%s/%s-release-%s\n' "$parent_dir" "$repo_name" "$version"
-}
-
-git_current_branch() {
-  git -C "$REPO_ROOT" symbolic-ref --quiet --short HEAD 2>/dev/null || true
-}
-
-git_local_branch_exists() {
-  git -C "$REPO_ROOT" show-ref --verify --quiet "refs/heads/$1"
-}
-
-git_remote_branch_exists() {
-  git -C "$REPO_ROOT" ls-remote --exit-code --heads "$2" "refs/heads/$1" >/dev/null 2>&1
-}
-
-git_local_tag_exists() {
-  git -C "$REPO_ROOT" show-ref --verify --quiet "refs/tags/$1"
-}
-
-git_remote_tag_exists() {
-  git -C "$REPO_ROOT" ls-remote --exit-code --tags "$2" "refs/tags/$1" >/dev/null 2>&1
-}
-
-npm_version_exists() {
-  local version="$1"
-  local resolved
-
-  resolved="$(npm view "paperclipai@${version}" version 2>/dev/null || true)"
-  [ "$resolved" = "$version" ]
-}
-
-require_clean_worktree() {
-  if [ -n "$(git -C "$REPO_ROOT" status --porcelain)" ]; then
-    release_fail "working tree is not clean. Commit, stash, or remove changes before releasing."
-  fi
-}
-
-git_worktree_path_for_branch() {
-  local branch_ref="refs/heads/$1"
-
-  git -C "$REPO_ROOT" worktree list --porcelain | awk -v branch_ref="$branch_ref" '
-    $1 == "worktree" { path = substr($0, 10) }
-    $1 == "branch" && $2 == branch_ref { print path; exit }
-  '
-}
-
-path_is_worktree_for_branch() {
-  local path="$1"
-  local branch="$2"
-  local current_branch
-
-  [ -d "$path" ] || return 1
-  current_branch="$(git -C "$path" symbolic-ref --quiet --short HEAD 2>/dev/null || true)"
-  [ "$current_branch" = "$branch" ]
-}
-
-ensure_release_branch_for_version() {
-  local stable_version="$1"
-  local current_branch
-  local expected_branch
-
-  current_branch="$(git_current_branch)"
-  expected_branch="$(release_branch_name "$stable_version")"
-
-  if [ -z "$current_branch" ]; then
-    release_fail "release work must run from branch $expected_branch, but HEAD is detached."
-  fi
-
-  if [ "$current_branch" != "$expected_branch" ]; then
-    release_fail "release work must run from branch $expected_branch, but current branch is $current_branch."
-  fi
-}
-
-stable_release_exists_anywhere() {
-  local stable_version="$1"
-  local remote="$2"
-  local tag="v$stable_version"
-
-  git_local_tag_exists "$tag" || git_remote_tag_exists "$tag" "$remote" || npm_version_exists "$stable_version"
-}
-
-release_train_is_frozen() {
-  stable_release_exists_anywhere "$1" "$2"
-}

scripts/release-preflight.sh

@@ -1,201 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-# shellcheck source=./release-lib.sh
-. "$REPO_ROOT/scripts/release-lib.sh"
-export GIT_PAGER=cat
-
-channel=""
-bump_type=""
-
-usage() {
-  cat <<'EOF'
-Usage:
-  ./scripts/release-preflight.sh <canary|stable> <patch|minor|major>
-
-Examples:
-  ./scripts/release-preflight.sh canary patch
-  ./scripts/release-preflight.sh stable minor
-
-What it does:
-  - verifies the git worktree is clean, including untracked files
-  - verifies you are on the matching release/X.Y.Z branch
-  - shows the last stable tag and the target version(s)
-  - shows the git/npm/GitHub release-train state
-  - shows commits since the last stable tag
-  - highlights migration/schema/breaking-change signals
-  - runs the verification gate:
-      pnpm -r typecheck
-      pnpm test:run
-      pnpm build
-EOF
-}
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    *)
-      if [ -z "$channel" ]; then
-        channel="$1"
-      elif [ -z "$bump_type" ]; then
-        bump_type="$1"
-      else
-        echo "Error: unexpected argument: $1" >&2
-        exit 1
-      fi
-      ;;
-  esac
-  shift
-done
-
-if [ -z "$channel" ] || [ -z "$bump_type" ]; then
-  usage
-  exit 1
-fi
-
-if [[ ! "$channel" =~ ^(canary|stable)$ ]]; then
-  usage
-  exit 1
-fi
-
-if [[ ! "$bump_type" =~ ^(patch|minor|major)$ ]]; then
-  usage
-  exit 1
-fi
-
-RELEASE_REMOTE="$(resolve_release_remote)"
-fetch_release_remote "$RELEASE_REMOTE"
-
-LAST_STABLE_TAG="$(get_last_stable_tag)"
-CURRENT_STABLE_VERSION="$(get_current_stable_version)"
-TARGET_STABLE_VERSION="$(compute_bumped_version "$CURRENT_STABLE_VERSION" "$bump_type")"
-TARGET_CANARY_VERSION="$(next_canary_version "$TARGET_STABLE_VERSION")"
-EXPECTED_RELEASE_BRANCH="$(release_branch_name "$TARGET_STABLE_VERSION")"
-CURRENT_BRANCH="$(git_current_branch)"
-RELEASE_TAG="v$TARGET_STABLE_VERSION"
-NOTES_FILE="$(release_notes_file "$TARGET_STABLE_VERSION")"
-
-require_clean_worktree
-
-if [ "$TARGET_STABLE_VERSION" = "$CURRENT_STABLE_VERSION" ]; then
-  echo "Error: next stable version matches the current stable version." >&2
-  exit 1
-fi
-
-if [[ "$TARGET_CANARY_VERSION" == "${CURRENT_STABLE_VERSION}-canary."* ]]; then
-  echo "Error: canary target was derived from the current stable version, which is not allowed." >&2
-  exit 1
-fi
-
-ensure_release_branch_for_version "$TARGET_STABLE_VERSION"
-
-REMOTE_BRANCH_EXISTS="no"
-REMOTE_TAG_EXISTS="no"
-LOCAL_TAG_EXISTS="no"
-NPM_STABLE_EXISTS="no"
-
-if git_remote_branch_exists "$EXPECTED_RELEASE_BRANCH" "$RELEASE_REMOTE"; then
-  REMOTE_BRANCH_EXISTS="yes"
-fi
-
-if git_local_tag_exists "$RELEASE_TAG"; then
-  LOCAL_TAG_EXISTS="yes"
-fi
-
-if git_remote_tag_exists "$RELEASE_TAG" "$RELEASE_REMOTE"; then
-  REMOTE_TAG_EXISTS="yes"
-fi
-
-if npm_version_exists "$TARGET_STABLE_VERSION"; then
-  NPM_STABLE_EXISTS="yes"
-fi
-
-if [ "$LOCAL_TAG_EXISTS" = "yes" ] || [ "$REMOTE_TAG_EXISTS" = "yes" ] || [ "$NPM_STABLE_EXISTS" = "yes" ]; then
-  echo "Error: release train $EXPECTED_RELEASE_BRANCH is frozen because $RELEASE_TAG already exists locally, remotely, or version $TARGET_STABLE_VERSION is already on npm." >&2
-  exit 1
-fi
-
-echo ""
-echo "==> Release preflight"
-echo "  Remote: $RELEASE_REMOTE"
-echo "  Channel: $channel"
-echo "  Bump: $bump_type"
-echo "  Current branch: ${CURRENT_BRANCH:-<detached>}"
-echo "  Expected branch: $EXPECTED_RELEASE_BRANCH"
-echo "  Last stable tag: ${LAST_STABLE_TAG:-<none>}"
-echo "  Current stable version: $CURRENT_STABLE_VERSION"
-echo "  Next stable version: $TARGET_STABLE_VERSION"
-if [ "$channel" = "canary" ]; then
-  echo "  Next canary version: $TARGET_CANARY_VERSION"
-  echo "  Guard: canaries are always derived from the next stable version, never ${CURRENT_STABLE_VERSION}-canary.N"
-fi
-
-echo ""
-echo "==> Working tree"
-echo "  ✓ Clean"
-echo "  ✓ Branch matches release train"
-
-echo ""
-echo "==> Release train state"
-echo "  Remote branch exists: $REMOTE_BRANCH_EXISTS"
-echo "  Local stable tag exists: $LOCAL_TAG_EXISTS"
-echo "  Remote stable tag exists: $REMOTE_TAG_EXISTS"
-echo "  Stable version on npm: $NPM_STABLE_EXISTS"
-if [ -f "$NOTES_FILE" ]; then
-  echo "  Release notes: present at $NOTES_FILE"
-else
-  echo "  Release notes: missing at $NOTES_FILE"
-fi
-
-if [ "$REMOTE_BRANCH_EXISTS" = "no" ]; then
-  echo "  Warning: remote branch $EXPECTED_RELEASE_BRANCH does not exist on $RELEASE_REMOTE yet."
-fi
-
-echo ""
-echo "==> Commits since last stable tag"
-if [ -n "$LAST_STABLE_TAG" ]; then
-  git -C "$REPO_ROOT" --no-pager log "${LAST_STABLE_TAG}..HEAD" --oneline --no-merges || true
-else
-  git -C "$REPO_ROOT" --no-pager log --oneline --no-merges || true
-fi
-
-echo ""
-echo "==> Migration / breaking change signals"
-if [ -n "$LAST_STABLE_TAG" ]; then
-  echo "-- migrations --"
-  git -C "$REPO_ROOT" --no-pager diff --name-only "${LAST_STABLE_TAG}..HEAD" -- packages/db/src/migrations/ || true
-  echo "-- schema --"
-  git -C "$REPO_ROOT" --no-pager diff "${LAST_STABLE_TAG}..HEAD" -- packages/db/src/schema/ || true
-  echo "-- breaking commit messages --"
-  git -C "$REPO_ROOT" --no-pager log "${LAST_STABLE_TAG}..HEAD" --format="%s" | grep -E 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true
-else
-  echo "No stable tag exists yet. Review the full current tree manually."
-fi
-
-echo ""
-echo "==> Verification gate"
-cd "$REPO_ROOT"
-pnpm -r typecheck
-pnpm test:run
-pnpm build
-
-echo ""
-echo "==> Release preflight summary"
-echo "  Remote: $RELEASE_REMOTE"
-echo "  Channel: $channel"
-echo "  Bump: $bump_type"
-echo "  Release branch: $EXPECTED_RELEASE_BRANCH"
-echo "  Last stable tag: ${LAST_STABLE_TAG:-<none>}"
-echo "  Current stable version: $CURRENT_STABLE_VERSION"
-echo "  Next stable version: $TARGET_STABLE_VERSION"
-if [ "$channel" = "canary" ]; then
-  echo "  Next canary version: $TARGET_CANARY_VERSION"
-  echo "  Guard: canaries are always derived from the next stable version, never ${CURRENT_STABLE_VERSION}-canary.N"
-fi
-
-echo ""
-echo "Preflight passed for $channel release."

scripts/release-start.sh

@@ -1,182 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-# shellcheck source=./release-lib.sh
-. "$REPO_ROOT/scripts/release-lib.sh"
-
-dry_run=false
-push_branch=true
-bump_type=""
-worktree_path=""
-
-usage() {
-  cat <<'EOF'
-Usage:
-  ./scripts/release-start.sh <patch|minor|major> [--dry-run] [--no-push] [--worktree-dir PATH]
-
-Examples:
-  ./scripts/release-start.sh patch
-  ./scripts/release-start.sh minor --dry-run
-  ./scripts/release-start.sh major --worktree-dir ../paperclip-release-1.0.0
-
-What it does:
-  - fetches the release remote and tags
-  - computes the next stable version from the latest stable tag
-  - creates or resumes branch release/X.Y.Z
-  - creates or resumes a dedicated worktree for that branch
-  - pushes the release branch to the remote by default
-
-Notes:
-  - Stable publishes freeze a release train. If vX.Y.Z already exists locally,
-    remotely, or on npm, this script refuses to reuse release/X.Y.Z.
-  - Use --no-push only if you intentionally do not want the release branch on
-    GitHub yet.
-EOF
-}
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --dry-run) dry_run=true ;;
-    --no-push) push_branch=false ;;
-    --worktree-dir)
-      shift
-      [ $# -gt 0 ] || release_fail "--worktree-dir requires a path."
-      worktree_path="$1"
-      ;;
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    *)
-      if [ -n "$bump_type" ]; then
-        release_fail "only one bump type may be provided."
-      fi
-      bump_type="$1"
-      ;;
-  esac
-  shift
-done
-
-if [[ ! "$bump_type" =~ ^(patch|minor|major)$ ]]; then
-  usage
-  exit 1
-fi
-
-release_remote="$(resolve_release_remote)"
-fetch_release_remote "$release_remote"
-
-last_stable_tag="$(get_last_stable_tag)"
-current_stable_version="$(get_current_stable_version)"
-target_stable_version="$(compute_bumped_version "$current_stable_version" "$bump_type")"
-target_canary_version="$(next_canary_version "$target_stable_version")"
-release_branch="$(release_branch_name "$target_stable_version")"
-release_tag="v$target_stable_version"
-
-if [ -z "$worktree_path" ]; then
-  worktree_path="$(default_release_worktree_path "$target_stable_version")"
-fi
-
-if stable_release_exists_anywhere "$target_stable_version" "$release_remote"; then
-  release_fail "release train $release_branch is frozen because $release_tag already exists locally, remotely, or version $target_stable_version is already on npm."
-fi
-
-branch_exists_local=false
-branch_exists_remote=false
-branch_worktree_path=""
-created_worktree=false
-created_branch=false
-pushed_branch=false
-
-if git_local_branch_exists "$release_branch"; then
-  branch_exists_local=true
-fi
-
-if git_remote_branch_exists "$release_branch" "$release_remote"; then
-  branch_exists_remote=true
-fi
-
-branch_worktree_path="$(git_worktree_path_for_branch "$release_branch")"
-if [ -n "$branch_worktree_path" ]; then
-  worktree_path="$branch_worktree_path"
-fi
-
-if [ -e "$worktree_path" ] && ! path_is_worktree_for_branch "$worktree_path" "$release_branch"; then
-  release_fail "path $worktree_path already exists and is not a worktree for $release_branch."
-fi
-
-if [ -z "$branch_worktree_path" ]; then
-  if [ "$dry_run" = true ]; then
-    if [ "$branch_exists_local" = true ] || [ "$branch_exists_remote" = true ]; then
-      release_info "[dry-run] Would add worktree $worktree_path for existing branch $release_branch"
-    else
-      release_info "[dry-run] Would create branch $release_branch from $release_remote/master"
-      release_info "[dry-run] Would add worktree $worktree_path"
-    fi
-  else
-    if [ "$branch_exists_local" = true ]; then
-      git -C "$REPO_ROOT" worktree add "$worktree_path" "$release_branch"
-    elif [ "$branch_exists_remote" = true ]; then
-      git -C "$REPO_ROOT" branch --track "$release_branch" "$release_remote/$release_branch"
-      git -C "$REPO_ROOT" worktree add "$worktree_path" "$release_branch"
-      created_branch=true
-    else
-      git -C "$REPO_ROOT" worktree add -b "$release_branch" "$worktree_path" "$release_remote/master"
-      created_branch=true
-    fi
-    created_worktree=true
-  fi
-fi
-
-if [ "$dry_run" = false ] && [ "$push_branch" = true ] && [ "$branch_exists_remote" = false ]; then
-  git -C "$worktree_path" push -u "$release_remote" "$release_branch"
-  pushed_branch=true
-fi
-
-if [ "$dry_run" = false ] && [ "$branch_exists_remote" = true ]; then
-  git -C "$worktree_path" branch --set-upstream-to "$release_remote/$release_branch" "$release_branch" >/dev/null 2>&1 || true
-fi
-
-release_info ""
-release_info "==> Release train"
-release_info "  Remote: $release_remote"
-release_info "  Last stable tag: ${last_stable_tag:-<none>}"
-release_info "  Current stable version: $current_stable_version"
-release_info "  Bump: $bump_type"
-release_info "  Target stable version: $target_stable_version"
-release_info "  Next canary version: $target_canary_version"
-release_info "  Branch: $release_branch"
-release_info "  Tag (reserved until stable publish): $release_tag"
-release_info "  Worktree: $worktree_path"
-release_info "  Release notes path: $worktree_path/releases/v${target_stable_version}.md"
-
-release_info ""
-release_info "==> Status"
-if [ -n "$branch_worktree_path" ]; then
-  release_info "  ✓ Reusing existing worktree for $release_branch"
-elif [ "$dry_run" = true ]; then
-  release_info "  ✓ Dry run only; no branch or worktree created"
-else
-  [ "$created_branch" = true ] && release_info "  ✓ Created branch $release_branch"
-  [ "$created_worktree" = true ] && release_info "  ✓ Created worktree $worktree_path"
-fi
-
-if [ "$branch_exists_remote" = true ]; then
-  release_info "  ✓ Remote branch already exists on $release_remote"
-elif [ "$dry_run" = true ] && [ "$push_branch" = true ]; then
-  release_info "  [dry-run] Would push $release_branch to $release_remote"
-elif [ "$push_branch" = true ] && [ "$pushed_branch" = true ]; then
-  release_info "  ✓ Pushed $release_branch to $release_remote"
-elif [ "$push_branch" = false ]; then
-  release_warn "release branch was not pushed. Stable publish will later refuse until the branch exists on $release_remote."
-fi
-
-release_info ""
-release_info "Next steps:"
-release_info "  cd $worktree_path"
-release_info "  Draft or update releases/v${target_stable_version}.md"
-release_info "  ./scripts/release-preflight.sh canary $bump_type"
-release_info "  ./scripts/release.sh $bump_type --canary"
-release_info ""
-release_info "Merge rule:"
-release_info "  Merge $release_branch back to master without squash or rebase so tag $release_tag remains reachable from master."

scripts/release.sh

@@ -1,446 +1,422 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# release.sh — Prepare and publish a Paperclip release.
+# release.sh — One-command version bump, build, and publish via Changesets.
 #
-# Stable release:
-#   ./scripts/release.sh patch
-#   ./scripts/release.sh minor --dry-run
+# Usage:
+#   ./scripts/release.sh patch                  # 0.2.0 → 0.2.1
+#   ./scripts/release.sh minor                  # 0.2.0 → 0.3.0
+#   ./scripts/release.sh major                  # 0.2.0 → 1.0.0
+#   ./scripts/release.sh patch --dry-run        # everything except npm publish
+#   ./scripts/release.sh patch --canary          # publish under @canary tag, no commit/tag
+#   ./scripts/release.sh patch --canary --dry-run
+#   ./scripts/release.sh --promote 0.2.8        # promote canary to @latest + commit/tag
+#   ./scripts/release.sh --promote 0.2.8 --dry-run
 #
-# Canary release:
-#   ./scripts/release.sh patch --canary
-#   ./scripts/release.sh minor --canary --dry-run
+# Steps (normal):
+#   1. Preflight checks (clean tree, npm login)
+#   2. Auto-create a changeset for all public packages
+#   3. Run changeset version (bumps versions, generates CHANGELOGs)
+#   4. Build all packages
+#   5. Build CLI bundle (esbuild)
+#   6. Publish to npm via changeset publish (unless --dry-run)
+#   7. Commit and tag
 #
-# Canary releases publish prerelease versions such as 1.2.3-canary.0 under the
-# npm dist-tag "canary". Stable releases publish 1.2.3 under "latest".
+# --canary: Steps 1-5 unchanged, Step 6 publishes with --tag canary, Step 7 skipped.
+# --promote: Skips Steps 1-6, promotes canary to latest, then commits and tags.
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-# shellcheck source=./release-lib.sh
-. "$REPO_ROOT/scripts/release-lib.sh"
 CLI_DIR="$REPO_ROOT/cli"
-TEMP_CHANGESET_FILE="$REPO_ROOT/.changeset/release-bump.md"
-TEMP_PRE_FILE="$REPO_ROOT/.changeset/pre.json"
+
+# ── Helper: create GitHub Release ────────────────────────────────────────────
+create_github_release() {
+  local version="$1"
+  local is_dry_run="$2"
+  local release_notes="$REPO_ROOT/releases/v${version}.md"
+
+  if [ "$is_dry_run" = true ]; then
+    echo "  [dry-run] gh release create v$version"
+    return
+  fi
+
+  if ! command -v gh &>/dev/null; then
+    echo "  ⚠ gh CLI not found — skipping GitHub Release"
+    return
+  fi
+
+  local gh_args=(gh release create "v$version" --title "v$version")
+  if [ -f "$release_notes" ]; then
+    gh_args+=(--notes-file "$release_notes")
+  else
+    gh_args+=(--generate-notes)
+  fi
+
+  if "${gh_args[@]}"; then
+    echo "  ✓ Created GitHub Release v$version"
+  else
+    echo "  ⚠ GitHub Release creation failed (non-fatal)"
+  fi
+}
+
+# ── Parse args ────────────────────────────────────────────────────────────────
 
 dry_run=false
 canary=false
+promote=false
+promote_version=""
 bump_type=""
 
-cleanup_on_exit=false
-
-usage() {
-  cat <<'EOF'
-Usage:
-  ./scripts/release.sh <patch|minor|major> [--canary] [--dry-run]
-
-Examples:
-  ./scripts/release.sh patch
-  ./scripts/release.sh minor --dry-run
-  ./scripts/release.sh patch --canary
-  ./scripts/release.sh minor --canary --dry-run
-
-Notes:
-  - Canary publishes prerelease versions like 1.2.3-canary.0 under the npm
-    dist-tag "canary".
-  - Stable publishes 1.2.3 under the npm dist-tag "latest".
-  - Run this from branch release/X.Y.Z matching the computed target version.
-  - Dry runs leave the working tree clean.
-EOF
-}
-
 while [ $# -gt 0 ]; do
   case "$1" in
     --dry-run) dry_run=true ;;
     --canary) canary=true ;;
-    -h|--help)
-      usage
-      exit 0
-      ;;
     --promote)
-      echo "Error: --promote was removed. Re-run a stable release from the vetted commit instead."
-      exit 1
-      ;;
-    *)
-      if [ -n "$bump_type" ]; then
-        echo "Error: only one bump type may be provided."
+      promote=true
+      shift
+      if [ $# -eq 0 ] || [[ "$1" == --* ]]; then
+        echo "Error: --promote requires a version argument (e.g. --promote 0.2.8)"
         exit 1
       fi
-      bump_type="$1"
+      promote_version="$1"
       ;;
+    *) bump_type="$1" ;;
   esac
   shift
 done
 
-if [[ ! "$bump_type" =~ ^(patch|minor|major)$ ]]; then
-  usage
+if [ "$promote" = true ] && [ "$canary" = true ]; then
+  echo "Error: --canary and --promote cannot be used together"
   exit 1
 fi
 
-restore_publish_artifacts() {
-  if [ -f "$CLI_DIR/package.dev.json" ]; then
-    mv "$CLI_DIR/package.dev.json" "$CLI_DIR/package.json"
+if [ "$promote" = false ]; then
+  if [ -z "$bump_type" ]; then
+    echo "Usage: $0 <patch|minor|major> [--dry-run] [--canary]"
+    echo "       $0 --promote <version> [--dry-run]"
+    exit 1
   fi
 
-  rm -f "$CLI_DIR/README.md"
-  rm -rf "$REPO_ROOT/server/ui-dist"
+  if [[ ! "$bump_type" =~ ^(patch|minor|major)$ ]]; then
+    echo "Error: bump type must be patch, minor, or major (got '$bump_type')"
+    exit 1
+  fi
+fi
 
+# ── Promote mode (skips Steps 1-6) ───────────────────────────────────────────
+
+if [ "$promote" = true ]; then
+  NEW_VERSION="$promote_version"
+  echo ""
+  echo "==> Promote mode: promoting v$NEW_VERSION from canary to latest..."
+
+  # Get all publishable package names
+  PACKAGES=$(node -e "
+const { readFileSync } = require('fs');
+const { resolve } = require('path');
+const root = '$REPO_ROOT';
+const dirs = ['packages/shared', 'packages/adapter-utils', 'packages/db',
+  'packages/adapters/claude-local', 'packages/adapters/codex-local', 'packages/adapters/opencode-local', 'packages/adapters/openclaw-gateway',
+  'server', 'cli'];
+const names = [];
+for (const d of dirs) {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(root, d, 'package.json'), 'utf8'));
+    if (!pkg.private) names.push(pkg.name);
+  } catch {}
+}
+console.log(names.join('\n'));
+")
+
+  echo ""
+  echo "  Promoting packages to @latest:"
+  while IFS= read -r pkg; do
+    if [ "$dry_run" = true ]; then
+      echo "  [dry-run] npm dist-tag add ${pkg}@${NEW_VERSION} latest"
+    else
+      npm dist-tag add "${pkg}@${NEW_VERSION}" latest
+      echo "  ✓ ${pkg}@${NEW_VERSION} → latest"
+    fi
+  done <<< "$PACKAGES"
+
+  # Restore CLI dev package.json if present
+  if [ -f "$CLI_DIR/package.dev.json" ]; then
+    mv "$CLI_DIR/package.dev.json" "$CLI_DIR/package.json"
+    echo "  ✓ Restored workspace dependencies in cli/package.json"
+  fi
+
+  # Remove the README copied for npm publishing
+  if [ -f "$CLI_DIR/README.md" ]; then
+    rm "$CLI_DIR/README.md"
+  fi
+
+  # Remove temporary build artifacts
+  rm -rf "$REPO_ROOT/server/ui-dist"
   for pkg_dir in server packages/adapters/claude-local packages/adapters/codex-local; do
     rm -rf "$REPO_ROOT/$pkg_dir/skills"
   done
-}
 
-cleanup_release_state() {
-  restore_publish_artifacts
-
-  rm -f "$TEMP_CHANGESET_FILE" "$TEMP_PRE_FILE"
-
-  tracked_changes="$(git -C "$REPO_ROOT" diff --name-only; git -C "$REPO_ROOT" diff --cached --name-only)"
-  if [ -n "$tracked_changes" ]; then
-    printf '%s\n' "$tracked_changes" | sort -u | while IFS= read -r path; do
-      [ -z "$path" ] && continue
-      git -C "$REPO_ROOT" checkout -q HEAD -- "$path" || true
-    done
-  fi
-
-  untracked_changes="$(git -C "$REPO_ROOT" ls-files --others --exclude-standard)"
-  if [ -n "$untracked_changes" ]; then
-    printf '%s\n' "$untracked_changes" | while IFS= read -r path; do
-      [ -z "$path" ] && continue
-      if [ -d "$REPO_ROOT/$path" ]; then
-        rm -rf "$REPO_ROOT/$path"
-      else
-        rm -f "$REPO_ROOT/$path"
-      fi
-    done
-  fi
-}
-
-if [ "$cleanup_on_exit" = true ]; then
-  trap cleanup_release_state EXIT
-fi
-
-set_cleanup_trap() {
-  cleanup_on_exit=true
-  trap cleanup_release_state EXIT
-}
-
-require_npm_publish_auth() {
+  # Stage release files, commit, and tag
+  echo ""
+  echo "  Committing and tagging v$NEW_VERSION..."
   if [ "$dry_run" = true ]; then
-    return
+    echo "  [dry-run] git add + commit + tag v$NEW_VERSION"
+  else
+    git add \
+      .changeset/ \
+      '**/CHANGELOG.md' \
+      '**/package.json' \
+      cli/src/index.ts
+    git commit -m "chore: release v$NEW_VERSION"
+    git tag "v$NEW_VERSION"
+    echo "  ✓ Committed and tagged v$NEW_VERSION"
   fi
 
-  if npm whoami >/dev/null 2>&1; then
-    release_info "  ✓ Logged in to npm as $(npm whoami)"
-    return
+  create_github_release "$NEW_VERSION" "$dry_run"
+
+  echo ""
+  if [ "$dry_run" = true ]; then
+    echo "Dry run complete for promote v$NEW_VERSION."
+    echo "  - Would promote all packages to @latest"
+    echo "  - Would commit and tag v$NEW_VERSION"
+    echo "  - Would create GitHub Release"
+  else
+    echo "Promoted all packages to @latest at v$NEW_VERSION"
+    echo ""
+    echo "Verify: npm view paperclipai@latest version"
+    echo ""
+    echo "To push:"
+    echo "  git push && git push origin v$NEW_VERSION"
   fi
+  exit 0
+fi
 
-  if [ "${GITHUB_ACTIONS:-}" = "true" ]; then
-    release_info "  ✓ npm publish auth will be provided by GitHub Actions trusted publishing"
-    return
+# ── Step 1: Preflight checks ─────────────────────────────────────────────────
+
+echo ""
+echo "==> Step 1/7: Preflight checks..."
+
+if [ "$dry_run" = false ]; then
+  if ! npm whoami &>/dev/null; then
+    echo "Error: Not logged in to npm. Run 'npm login' first."
+    exit 1
   fi
+  echo "  ✓ Logged in to npm as $(npm whoami)"
+fi
 
-  release_fail "npm publish auth is not available. Use 'npm login' locally or run from the GitHub release workflow."
+if ! git -C "$REPO_ROOT" diff --quiet || ! git -C "$REPO_ROOT" diff --cached --quiet; then
+  echo "Error: Working tree has uncommitted changes. Commit or stash them first."
+  exit 1
+fi
+echo "  ✓ Working tree is clean"
+
+# ── Step 2: Auto-create changeset ────────────────────────────────────────────
+
+echo ""
+echo "==> Step 2/7: Creating changeset ($bump_type bump for all packages)..."
+
+# Get all publishable (non-private) package names
+PACKAGES=$(node -e "
+const { readdirSync, readFileSync } = require('fs');
+const { resolve } = require('path');
+const root = '$REPO_ROOT';
+const wsYaml = readFileSync(resolve(root, 'pnpm-workspace.yaml'), 'utf8');
+const dirs = ['packages/shared', 'packages/adapter-utils', 'packages/db',
+  'packages/adapters/claude-local', 'packages/adapters/codex-local', 'packages/adapters/opencode-local', 'packages/adapters/openclaw-gateway',
+  'server', 'cli'];
+const names = [];
+for (const d of dirs) {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(root, d, 'package.json'), 'utf8'));
+    if (!pkg.private) names.push(pkg.name);
+  } catch {}
 }
+console.log(names.join('\n'));
+")
 
-list_public_package_info() {
-  node - "$REPO_ROOT" <<'NODE'
-const fs = require('fs');
-const path = require('path');
-
-const root = process.argv[2];
-const roots = ['packages', 'server', 'ui', 'cli'];
-const seen = new Set();
-const rows = [];
-
-function walk(relDir) {
-  const absDir = path.join(root, relDir);
-  const pkgPath = path.join(absDir, 'package.json');
-
-  if (fs.existsSync(pkgPath)) {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    if (!pkg.private) {
-      rows.push([relDir, pkg.name]);
-    }
-    return;
-  }
-
-  if (!fs.existsSync(absDir)) {
-    return;
-  }
-
-  for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;
-    walk(path.join(relDir, entry.name));
-  }
-}
-
-for (const rel of roots) {
-  walk(rel);
-}
-
-rows.sort((a, b) => a[0].localeCompare(b[0]));
-
-for (const [dir, name] of rows) {
-  const key = `${dir}\t${name}`;
-  if (seen.has(key)) continue;
-  seen.add(key);
-  process.stdout.write(`${dir}\t${name}\n`);
-}
-NODE
-}
-
-replace_version_string() {
-  local from_version="$1"
-  local to_version="$2"
-
-  node - "$REPO_ROOT" "$from_version" "$to_version" <<'NODE'
-const fs = require('fs');
-const path = require('path');
-
-const root = process.argv[2];
-const fromVersion = process.argv[3];
-const toVersion = process.argv[4];
-
-const roots = ['packages', 'server', 'ui', 'cli'];
-const targets = new Set(['package.json', 'CHANGELOG.md']);
-const extraFiles = [path.join('cli', 'src', 'index.ts')];
-
-function rewriteFile(filePath) {
-  if (!fs.existsSync(filePath)) return;
-  const current = fs.readFileSync(filePath, 'utf8');
-  if (!current.includes(fromVersion)) return;
-  fs.writeFileSync(filePath, current.split(fromVersion).join(toVersion));
-}
-
-function walk(relDir) {
-  const absDir = path.join(root, relDir);
-  if (!fs.existsSync(absDir)) return;
-
-  for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {
-    if (entry.isDirectory()) {
-      if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;
-      walk(path.join(relDir, entry.name));
-      continue;
-    }
-
-    if (targets.has(entry.name)) {
-      rewriteFile(path.join(absDir, entry.name));
-    }
-  }
-}
-
-for (const rel of roots) {
-  walk(rel);
-}
-
-for (const relFile of extraFiles) {
-  rewriteFile(path.join(root, relFile));
-}
-NODE
-}
-
-PUBLISH_REMOTE="$(resolve_release_remote)"
-fetch_release_remote "$PUBLISH_REMOTE"
-
-LAST_STABLE_TAG="$(get_last_stable_tag)"
-CURRENT_STABLE_VERSION="$(get_current_stable_version)"
-
-TARGET_STABLE_VERSION="$(compute_bumped_version "$CURRENT_STABLE_VERSION" "$bump_type")"
-TARGET_PUBLISH_VERSION="$TARGET_STABLE_VERSION"
-CURRENT_BRANCH="$(git_current_branch)"
-EXPECTED_RELEASE_BRANCH="$(release_branch_name "$TARGET_STABLE_VERSION")"
-NOTES_FILE="$(release_notes_file "$TARGET_STABLE_VERSION")"
-RELEASE_TAG="v$TARGET_STABLE_VERSION"
-
-if [ "$canary" = true ]; then
-  TARGET_PUBLISH_VERSION="$(next_canary_version "$TARGET_STABLE_VERSION")"
-fi
-
-if [ "$TARGET_STABLE_VERSION" = "$CURRENT_STABLE_VERSION" ]; then
-  release_fail "next stable version matches the current stable version. Refusing to publish."
-fi
-
-if [[ "$TARGET_PUBLISH_VERSION" == "${CURRENT_STABLE_VERSION}-canary."* ]]; then
-  release_fail "canary versions must be derived from the next stable version, never ${CURRENT_STABLE_VERSION}-canary.N."
-fi
-
-require_clean_worktree
-ensure_release_branch_for_version "$TARGET_STABLE_VERSION"
-
-if git_local_tag_exists "$RELEASE_TAG" || git_remote_tag_exists "$RELEASE_TAG" "$PUBLISH_REMOTE"; then
-  release_fail "release train $EXPECTED_RELEASE_BRANCH is frozen because tag $RELEASE_TAG already exists locally or on $PUBLISH_REMOTE."
-fi
-
-if npm_version_exists "$TARGET_STABLE_VERSION"; then
-  release_fail "stable version $TARGET_STABLE_VERSION is already published on npm. Refusing to reuse release train $EXPECTED_RELEASE_BRANCH."
-fi
-
-if [ "$canary" = false ] && [ ! -f "$NOTES_FILE" ]; then
-  release_fail "stable release notes file is required at $NOTES_FILE before publishing stable."
-fi
-
-if [ "$canary" = true ] && [ ! -f "$NOTES_FILE" ]; then
-  release_warn "stable release notes file is missing at $NOTES_FILE. Draft it before you finalize stable."
-fi
-
-if ! git_remote_branch_exists "$EXPECTED_RELEASE_BRANCH" "$PUBLISH_REMOTE"; then
-  if [ "$canary" = false ] && [ "$dry_run" = false ]; then
-    release_fail "remote branch $EXPECTED_RELEASE_BRANCH does not exist on $PUBLISH_REMOTE. Run ./scripts/release-start.sh $bump_type first or push the branch before stable publish."
-  fi
-  release_warn "remote branch $EXPECTED_RELEASE_BRANCH does not exist on $PUBLISH_REMOTE yet."
-fi
-
-PUBLIC_PACKAGE_INFO="$(list_public_package_info)"
-PUBLIC_PACKAGE_NAMES="$(printf '%s\n' "$PUBLIC_PACKAGE_INFO" | cut -f2)"
-PUBLIC_PACKAGE_DIRS="$(printf '%s\n' "$PUBLIC_PACKAGE_INFO" | cut -f1)"
-
-if [ -z "$PUBLIC_PACKAGE_INFO" ]; then
-  release_fail "no public packages were found in the workspace."
-fi
-
-release_info ""
-release_info "==> Release plan"
-release_info "  Remote: $PUBLISH_REMOTE"
-release_info "  Current branch: ${CURRENT_BRANCH:-<detached>}"
-release_info "  Expected branch: $EXPECTED_RELEASE_BRANCH"
-release_info "  Last stable tag: ${LAST_STABLE_TAG:-<none>}"
-release_info "  Current stable version: $CURRENT_STABLE_VERSION"
-if [ "$canary" = true ]; then
-  release_info "  Target stable version: $TARGET_STABLE_VERSION"
-  release_info "  Canary version: $TARGET_PUBLISH_VERSION"
-  release_info "  Guard: canary is derived from next stable version, not ${CURRENT_STABLE_VERSION}-canary.N"
-else
-  release_info "  Stable version: $TARGET_STABLE_VERSION"
-fi
-
-release_info ""
-release_info "==> Step 1/7: Preflight checks..."
-release_info "  ✓ Working tree is clean"
-release_info "  ✓ Branch matches release train"
-require_npm_publish_auth
-
-if [ "$dry_run" = true ] || [ "$canary" = true ]; then
-  set_cleanup_trap
-fi
-
-release_info ""
-release_info "==> Step 2/7: Creating release changeset..."
+# Write a changeset file
+CHANGESET_FILE="$REPO_ROOT/.changeset/release-bump.md"
 {
   echo "---"
-  while IFS= read -r pkg_name; do
-    [ -z "$pkg_name" ] && continue
-    echo "\"$pkg_name\": $bump_type"
-  done <<< "$PUBLIC_PACKAGE_NAMES"
+  while IFS= read -r pkg; do
+    echo "\"$pkg\": $bump_type"
+  done <<< "$PACKAGES"
   echo "---"
   echo ""
-  if [ "$canary" = true ]; then
-    echo "Canary release preparation for $TARGET_STABLE_VERSION"
-  else
-    echo "Stable release preparation for $TARGET_STABLE_VERSION"
-  fi
-} > "$TEMP_CHANGESET_FILE"
-release_info "  ✓ Created release changeset for $(printf '%s\n' "$PUBLIC_PACKAGE_NAMES" | sed '/^$/d' | wc -l | xargs) packages"
+  echo "Version bump ($bump_type)"
+} > "$CHANGESET_FILE"
 
-release_info ""
-release_info "==> Step 3/7: Versioning packages..."
+echo "  ✓ Created changeset for $(echo "$PACKAGES" | wc -l | xargs) packages"
+
+# ── Step 3: Version packages ─────────────────────────────────────────────────
+
+echo ""
+echo "==> Step 3/7: Running changeset version..."
 cd "$REPO_ROOT"
-if [ "$canary" = true ]; then
-  npx changeset pre enter canary
-fi
 npx changeset version
+echo "  ✓ Versions bumped and CHANGELOGs generated"
 
-if [ "$canary" = true ]; then
-  BASE_CANARY_VERSION="${TARGET_STABLE_VERSION}-canary.0"
-  if [ "$TARGET_PUBLISH_VERSION" != "$BASE_CANARY_VERSION" ]; then
-    replace_version_string "$BASE_CANARY_VERSION" "$TARGET_PUBLISH_VERSION"
-  fi
+# Read the new version from the CLI package
+NEW_VERSION=$(node -e "console.log(require('$CLI_DIR/package.json').version)")
+echo "  New version: $NEW_VERSION"
+
+# Update the version string in cli/src/index.ts
+CURRENT_VERSION_IN_SRC=$(sed -n 's/.*\.version("\([^"]*\)".*/\1/p' "$CLI_DIR/src/index.ts" | head -1)
+if [ -n "$CURRENT_VERSION_IN_SRC" ] && [ "$CURRENT_VERSION_IN_SRC" != "$NEW_VERSION" ]; then
+  sed -i '' "s/\.version(\"$CURRENT_VERSION_IN_SRC\")/\.version(\"$NEW_VERSION\")/" "$CLI_DIR/src/index.ts"
+  echo "  ✓ Updated cli/src/index.ts version to $NEW_VERSION"
 fi
 
-VERSION_IN_CLI_PACKAGE="$(node -e "console.log(require('$CLI_DIR/package.json').version)")"
-if [ "$VERSION_IN_CLI_PACKAGE" != "$TARGET_PUBLISH_VERSION" ]; then
-  release_fail "versioning drift detected. Expected $TARGET_PUBLISH_VERSION but found $VERSION_IN_CLI_PACKAGE."
-fi
-release_info "  ✓ Versioned workspace to $TARGET_PUBLISH_VERSION"
+# ── Step 4: Build packages ───────────────────────────────────────────────────
 
-release_info ""
-release_info "==> Step 4/7: Building workspace artifacts..."
+echo ""
+echo "==> Step 4/7: Building all packages..."
 cd "$REPO_ROOT"
-pnpm build
-bash "$REPO_ROOT/scripts/prepare-server-ui-dist.sh"
+
+# Build packages in dependency order (excluding CLI)
+pnpm --filter @paperclipai/shared build
+pnpm --filter @paperclipai/adapter-utils build
+pnpm --filter @paperclipai/db build
+pnpm --filter @paperclipai/adapter-claude-local build
+pnpm --filter @paperclipai/adapter-codex-local build
+pnpm --filter @paperclipai/adapter-opencode-local build
+pnpm --filter @paperclipai/adapter-openclaw-gateway build
+pnpm --filter @paperclipai/server build
+
+# Build UI and bundle into server package for static serving
+pnpm --filter @paperclipai/ui build
+rm -rf "$REPO_ROOT/server/ui-dist"
+cp -r "$REPO_ROOT/ui/dist" "$REPO_ROOT/server/ui-dist"
+
+# Bundle skills into packages that need them (adapters + server)
 for pkg_dir in server packages/adapters/claude-local packages/adapters/codex-local; do
   rm -rf "$REPO_ROOT/$pkg_dir/skills"
   cp -r "$REPO_ROOT/skills" "$REPO_ROOT/$pkg_dir/skills"
 done
-release_info "  ✓ Workspace build complete"
+echo "  ✓ All packages built (including UI + skills)"
 
-release_info ""
-release_info "==> Step 5/7: Building publishable CLI bundle..."
+# ── Step 5: Build CLI bundle ─────────────────────────────────────────────────
+
+echo ""
+echo "==> Step 5/7: Building CLI bundle..."
+cd "$REPO_ROOT"
 "$REPO_ROOT/scripts/build-npm.sh" --skip-checks
-release_info "  ✓ CLI bundle ready"
+echo "  ✓ CLI bundled"
+
+# ── Step 6: Publish ──────────────────────────────────────────────────────────
 
-release_info ""
 if [ "$dry_run" = true ]; then
-  release_info "==> Step 6/7: Previewing publish payloads (--dry-run)..."
-  while IFS= read -r pkg_dir; do
-    [ -z "$pkg_dir" ] && continue
-    release_info "  --- $pkg_dir ---"
-    cd "$REPO_ROOT/$pkg_dir"
+  echo ""
+  if [ "$canary" = true ]; then
+    echo "==> Step 6/7: Skipping publish (--dry-run, --canary)"
+  else
+    echo "==> Step 6/7: Skipping publish (--dry-run)"
+  fi
+  echo ""
+  echo "  Preview what would be published:"
+  for dir in packages/shared packages/adapter-utils packages/db \
+             packages/adapters/claude-local packages/adapters/codex-local packages/adapters/opencode-local packages/adapters/openclaw-gateway \
+             server cli; do
+    echo "  --- $dir ---"
+    cd "$REPO_ROOT/$dir"
     npm pack --dry-run 2>&1 | tail -3
-  done <<< "$PUBLIC_PACKAGE_DIRS"
+  done
   cd "$REPO_ROOT"
   if [ "$canary" = true ]; then
-    release_info "  [dry-run] Would publish ${TARGET_PUBLISH_VERSION} under dist-tag canary"
-  else
-    release_info "  [dry-run] Would publish ${TARGET_PUBLISH_VERSION} under dist-tag latest"
+    echo ""
+    echo "  [dry-run] Would publish with: npx changeset publish --tag canary"
   fi
 else
+  echo ""
   if [ "$canary" = true ]; then
-    release_info "==> Step 6/7: Publishing canary to npm..."
-    npx changeset publish
-    release_info "  ✓ Published ${TARGET_PUBLISH_VERSION} under dist-tag canary"
+    echo "==> Step 6/7: Publishing to npm (canary)..."
+    cd "$REPO_ROOT"
+    npx changeset publish --tag canary
+    echo "  ✓ Published all packages under @canary tag"
   else
-    release_info "==> Step 6/7: Publishing stable release to npm..."
+    echo "==> Step 6/7: Publishing to npm..."
+    cd "$REPO_ROOT"
     npx changeset publish
-    release_info "  ✓ Published ${TARGET_PUBLISH_VERSION} under dist-tag latest"
+    echo "  ✓ Published all packages"
   fi
 fi
 
-release_info ""
-if [ "$dry_run" = true ]; then
-  release_info "==> Step 7/7: Cleaning up dry-run state..."
-  release_info "  ✓ Dry run leaves the working tree unchanged"
-elif [ "$canary" = true ]; then
-  release_info "==> Step 7/7: Cleaning up canary state..."
-  release_info "  ✓ Canary state will be discarded after publish"
+# ── Step 7: Restore CLI dev package.json and commit ──────────────────────────
+
+echo ""
+if [ "$canary" = true ]; then
+  echo "==> Step 7/7: Skipping commit and tag (canary mode — promote later)..."
 else
-  release_info "==> Step 7/7: Finalizing stable release commit..."
-  restore_publish_artifacts
+  echo "==> Step 7/7: Restoring dev package.json, committing, and tagging..."
+fi
+cd "$REPO_ROOT"
 
-  git -C "$REPO_ROOT" add -u .changeset packages server cli
-  if [ -f "$REPO_ROOT/releases/v${TARGET_STABLE_VERSION}.md" ]; then
-    git -C "$REPO_ROOT" add "releases/v${TARGET_STABLE_VERSION}.md"
-  fi
-
-  git -C "$REPO_ROOT" commit -m "chore: release v$TARGET_STABLE_VERSION"
-  git -C "$REPO_ROOT" tag "v$TARGET_STABLE_VERSION"
-  release_info "  ✓ Created commit and tag v$TARGET_STABLE_VERSION"
+# Restore the dev package.json (build-npm.sh backs it up)
+if [ -f "$CLI_DIR/package.dev.json" ]; then
+  mv "$CLI_DIR/package.dev.json" "$CLI_DIR/package.json"
+  echo "  ✓ Restored workspace dependencies in cli/package.json"
 fi
 
-release_info ""
-if [ "$dry_run" = true ]; then
-  if [ "$canary" = true ]; then
-    release_info "Dry run complete for canary ${TARGET_PUBLISH_VERSION}."
+# Remove the README copied for npm publishing
+if [ -f "$CLI_DIR/README.md" ]; then
+  rm "$CLI_DIR/README.md"
+fi
+
+# Remove temporary build artifacts before committing (these are only needed during publish)
+rm -rf "$REPO_ROOT/server/ui-dist"
+for pkg_dir in server packages/adapters/claude-local packages/adapters/codex-local; do
+  rm -rf "$REPO_ROOT/$pkg_dir/skills"
+done
+
+if [ "$canary" = false ]; then
+  # Stage only release-related files (avoid sweeping unrelated changes with -A)
+  git add \
+    .changeset/ \
+    '**/CHANGELOG.md' \
+    '**/package.json' \
+    cli/src/index.ts
+  git commit -m "chore: release v$NEW_VERSION"
+  git tag "v$NEW_VERSION"
+  echo "  ✓ Committed and tagged v$NEW_VERSION"
+fi
+
+if [ "$canary" = false ]; then
+  create_github_release "$NEW_VERSION" "$dry_run"
+fi
+
+# ── Done ──────────────────────────────────────────────────────────────────────
+
+echo ""
+if [ "$canary" = true ]; then
+  if [ "$dry_run" = true ]; then
+    echo "Dry run complete for canary v$NEW_VERSION."
+    echo "  - Versions bumped, built, and previewed"
+    echo "  - Dev package.json restored"
+    echo "  - No commit or tag (canary mode)"
+    echo ""
+    echo "To actually publish canary, run:"
+    echo "  ./scripts/release.sh $bump_type --canary"
   else
-    release_info "Dry run complete for stable v${TARGET_STABLE_VERSION}."
+    echo "Published canary at v$NEW_VERSION"
+    echo ""
+    echo "Verify: npm view paperclipai@canary version"
+    echo ""
+    echo "To promote to latest:"
+    echo "  ./scripts/release.sh --promote $NEW_VERSION"
   fi
-elif [ "$canary" = true ]; then
-  release_info "Published canary ${TARGET_PUBLISH_VERSION}."
-  release_info "Install with: npx paperclipai@canary onboard"
-  release_info "Stable version remains: $CURRENT_STABLE_VERSION"
+elif [ "$dry_run" = true ]; then
+  echo "Dry run complete for v$NEW_VERSION."
+  echo "  - Versions bumped, built, and previewed"
+  echo "  - Dev package.json restored"
+  echo "  - Commit and tag created (locally)"
+  echo "  - Would create GitHub Release"
+  echo ""
+  echo "To actually publish, run:"
+  echo "  ./scripts/release.sh $bump_type"
 else
-  release_info "Published stable v${TARGET_STABLE_VERSION}."
-  release_info "Next steps:"
-  release_info "  git push ${PUBLISH_REMOTE} HEAD --follow-tags"
-  release_info "  ./scripts/create-github-release.sh $TARGET_STABLE_VERSION"
-  release_info "  Open a PR from ${EXPECTED_RELEASE_BRANCH} to master and merge without squash or rebase"
+  echo "Published all packages at v$NEW_VERSION"
+  echo ""
+  echo "To push:"
+  echo "  git push && git push origin v$NEW_VERSION"
+  echo ""
+  echo "GitHub Release: https://github.com/cryppadotta/paperclip/releases/tag/v$NEW_VERSION"
 fi

scripts/rollback-latest.sh

@@ -1,111 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-
-dry_run=false
-version=""
-
-usage() {
-  cat <<'EOF'
-Usage:
-  ./scripts/rollback-latest.sh <stable-version> [--dry-run]
-
-Examples:
-  ./scripts/rollback-latest.sh 1.2.2
-  ./scripts/rollback-latest.sh 1.2.2 --dry-run
-
-Notes:
-  - This repoints the npm dist-tag "latest" for every public package.
-  - It does not unpublish anything.
-EOF
-}
-
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --dry-run) dry_run=true ;;
-    -h|--help)
-      usage
-      exit 0
-      ;;
-    *)
-      if [ -n "$version" ]; then
-        echo "Error: only one version may be provided." >&2
-        exit 1
-      fi
-      version="$1"
-      ;;
-  esac
-  shift
-done
-
-if [ -z "$version" ]; then
-  usage
-  exit 1
-fi
-
-if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-  echo "Error: version must be a stable semver like 1.2.2." >&2
-  exit 1
-fi
-
-if [ "$dry_run" = false ] && ! npm whoami >/dev/null 2>&1; then
-  echo "Error: npm publish rights are required. Run 'npm login' first." >&2
-  exit 1
-fi
-
-list_public_package_names() {
-  node - "$REPO_ROOT" <<'NODE'
-const fs = require('fs');
-const path = require('path');
-
-const root = process.argv[2];
-const roots = ['packages', 'server', 'ui', 'cli'];
-const seen = new Set();
-
-function walk(relDir) {
-  const absDir = path.join(root, relDir);
-  const pkgPath = path.join(absDir, 'package.json');
-
-  if (fs.existsSync(pkgPath)) {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    if (!pkg.private && !seen.has(pkg.name)) {
-      seen.add(pkg.name);
-      process.stdout.write(`${pkg.name}\n`);
-    }
-    return;
-  }
-
-  if (!fs.existsSync(absDir)) {
-    return;
-  }
-
-  for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;
-    walk(path.join(relDir, entry.name));
-  }
-}
-
-for (const rel of roots) {
-  walk(rel);
-}
-NODE
-}
-
-package_names="$(list_public_package_names)"
-
-if [ -z "$package_names" ]; then
-  echo "Error: no public packages were found in the workspace." >&2
-  exit 1
-fi
-
-while IFS= read -r package_name; do
-  [ -z "$package_name" ] && continue
-  if [ "$dry_run" = true ]; then
-    echo "[dry-run] npm dist-tag add ${package_name}@${version} latest"
-  else
-    npm dist-tag add "${package_name}@${version}" latest
-    echo "Updated latest -> ${package_name}@${version}"
-  fi
-done <<< "$package_names"

server/package.json

@@ -23,11 +23,8 @@
   ],
   "scripts": {
     "dev": "tsx src/index.ts",
-    "dev:watch": "cross-env PAPERCLIP_MIGRATION_PROMPT=never tsx watch --ignore ../ui/node_modules --ignore ../ui/.vite --ignore ../ui/dist src/index.ts",
-    "prepare:ui-dist": "bash ../scripts/prepare-server-ui-dist.sh",
+    "dev:watch": "PAPERCLIP_MIGRATION_PROMPT=never tsx watch --ignore ../ui/node_modules --ignore ../ui/.vite --ignore ../ui/dist src/index.ts",
     "build": "tsc",
-    "prepack": "pnpm run prepare:ui-dist",
-    "postpack": "rm -rf ui-dist",
     "clean": "rm -rf dist",
     "start": "node dist/index.js",
     "typecheck": "tsc --noEmit"
@@ -64,7 +61,6 @@
     "@types/node": "^24.6.0",
     "@types/supertest": "^6.0.2",
     "@types/ws": "^8.18.1",
-    "cross-env": "^10.1.0",
     "supertest": "^7.0.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3",

server/src/__tests__/codex-local-adapter-environment.test.ts

@@ -4,8 +4,6 @@ import os from "node:os";
 import path from "node:path";
 import { testEnvironment } from "@paperclipai/adapter-codex-local/server";
 
-const itWindows = process.platform === "win32" ? it : it.skip;
-
 describe("codex_local environment diagnostics", () => {
   it("creates a missing working directory when cwd is absolute", async () => {
     const cwd = path.join(
@@ -31,45 +29,4 @@ describe("codex_local environment diagnostics", () => {
     expect(stats.isDirectory()).toBe(true);
     await fs.rm(path.dirname(cwd), { recursive: true, force: true });
   });
-
-  itWindows("runs the hello probe when Codex is available via a Windows .cmd wrapper", async () => {
-    const root = path.join(
-      os.tmpdir(),
-      `paperclip-codex-local-probe-${Date.now()}-${Math.random().toString(16).slice(2)}`,
-    );
-    const binDir = path.join(root, "bin");
-    const cwd = path.join(root, "workspace");
-    const fakeCodex = path.join(binDir, "codex.cmd");
-    const script = [
-      "@echo off",
-      "echo {\"type\":\"thread.started\",\"thread_id\":\"test-thread\"}",
-      "echo {\"type\":\"item.completed\",\"item\":{\"type\":\"agent_message\",\"text\":\"hello\"}}",
-      "echo {\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":1,\"cached_input_tokens\":0,\"output_tokens\":1}}",
-      "exit /b 0",
-      "",
-    ].join("\r\n");
-
-    try {
-      await fs.mkdir(binDir, { recursive: true });
-      await fs.writeFile(fakeCodex, script, "utf8");
-
-      const result = await testEnvironment({
-        companyId: "company-1",
-        adapterType: "codex_local",
-        config: {
-          command: "codex",
-          cwd,
-          env: {
-            OPENAI_API_KEY: "test-key",
-            PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ""}`,
-          },
-        },
-      });
-
-      expect(result.status).toBe("pass");
-      expect(result.checks.some((check) => check.code === "codex_hello_probe_passed")).toBe(true);
-    } finally {
-      await fs.rm(root, { recursive: true, force: true });
-    }
-  });
 });

server/src/auth/better-auth.ts

@@ -70,9 +70,6 @@ export function createBetterAuthInstance(db: Db, config: Config, trustedOrigins?
   const secret = process.env.BETTER_AUTH_SECRET ?? process.env.PAPERCLIP_AGENT_JWT_SECRET ?? "paperclip-dev-secret";
   const effectiveTrustedOrigins = trustedOrigins ?? deriveAuthTrustedOrigins(config);
 
-  const publicUrl = process.env.PAPERCLIP_PUBLIC_URL ?? baseUrl;
-  const isHttpOnly = publicUrl ? publicUrl.startsWith("http://") : false;
-
   const authConfig = {
     baseURL: baseUrl,
     secret,
@@ -89,9 +86,7 @@ export function createBetterAuthInstance(db: Db, config: Config, trustedOrigins?
     emailAndPassword: {
       enabled: true,
       requireEmailVerification: false,
-      disableSignUp: config.authDisableSignUp,
     },
-    ...(isHttpOnly ? { advanced: { useSecureCookies: false } } : {}),
   };
 
   if (!baseUrl) {

server/src/config.ts

@@ -37,7 +37,6 @@ export interface Config {
   allowedHostnames: string[];
   authBaseUrlMode: AuthBaseUrlMode;
   authPublicBaseUrl: string | undefined;
-  authDisableSignUp: boolean;
   databaseMode: DatabaseMode;
   databaseUrl: string | undefined;
   embeddedPostgresDataDir: string;
@@ -143,11 +142,6 @@ export function loadConfig(): Config {
     authBaseUrlModeFromEnv ??
     fileConfig?.auth?.baseUrlMode ??
     (authPublicBaseUrl ? "explicit" : "auto");
-  const disableSignUpFromEnv = process.env.PAPERCLIP_AUTH_DISABLE_SIGN_UP;
-  const authDisableSignUp: boolean =
-    disableSignUpFromEnv !== undefined
-      ? disableSignUpFromEnv === "true"
-      : (fileConfig?.auth?.disableSignUp ?? false);
   const allowedHostnamesFromEnvRaw = process.env.PAPERCLIP_ALLOWED_HOSTNAMES;
   const allowedHostnamesFromEnv = allowedHostnamesFromEnvRaw
     ? allowedHostnamesFromEnvRaw
@@ -209,7 +203,6 @@ export function loadConfig(): Config {
     allowedHostnames,
     authBaseUrlMode,
     authPublicBaseUrl,
-    authDisableSignUp,
     databaseMode: fileDatabaseMode,
     databaseUrl: process.env.DATABASE_URL ?? fileDbUrl,
     embeddedPostgresDataDir: resolveHomeAwarePath(

server/src/routes/agents.ts

@@ -245,7 +245,7 @@ export function agentRoutes(db: Db) {
     adapterConfig: Record<string, unknown>,
   ) {
     if (adapterType !== "opencode_local") return;
-    const { config: runtimeConfig } = await secretsSvc.resolveAdapterConfigForRuntime(companyId, adapterConfig);
+    const runtimeConfig = await secretsSvc.resolveAdapterConfigForRuntime(companyId, adapterConfig);
     const runtimeEnv = asRecord(runtimeConfig.env) ?? {};
     try {
       await ensureOpenCodeModelConfiguredAndAvailable({
@@ -420,7 +420,7 @@ export function agentRoutes(db: Db) {
         inputAdapterConfig,
         { strictMode: strictSecretsMode },
       );
-      const { config: runtimeAdapterConfig } = await secretsSvc.resolveAdapterConfigForRuntime(
+      const runtimeAdapterConfig = await secretsSvc.resolveAdapterConfigForRuntime(
         companyId,
         normalizedAdapterConfig,
       );
@@ -1264,7 +1264,7 @@ export function agentRoutes(db: Db) {
     }
 
     const config = asRecord(agent.adapterConfig) ?? {};
-    const { config: runtimeConfig } = await secretsSvc.resolveAdapterConfigForRuntime(agent.companyId, config);
+    const runtimeConfig = await secretsSvc.resolveAdapterConfigForRuntime(agent.companyId, config);
     const result = await runClaudeLogin({
       runId: `claude-login-${randomUUID()}`,
       agent: {

server/src/routes/health.ts

@@ -1,7 +1,7 @@
 import { Router } from "express";
 import type { Db } from "@paperclipai/db";
-import { and, count, eq, gt, isNull, sql } from "drizzle-orm";
-import { instanceUserRoles, invites } from "@paperclipai/db";
+import { count, sql } from "drizzle-orm";
+import { instanceUserRoles } from "@paperclipai/db";
 import type { DeploymentExposure, DeploymentMode } from "@paperclipai/shared";
 
 export function healthRoutes(
@@ -27,7 +27,6 @@ export function healthRoutes(
     }
 
     let bootstrapStatus: "ready" | "bootstrap_pending" = "ready";
-    let bootstrapInviteActive = false;
     if (opts.deploymentMode === "authenticated") {
       const roleCount = await db
         .select({ count: count() })
@@ -35,23 +34,6 @@ export function healthRoutes(
         .where(sql`${instanceUserRoles.role} = 'instance_admin'`)
         .then((rows) => Number(rows[0]?.count ?? 0));
       bootstrapStatus = roleCount > 0 ? "ready" : "bootstrap_pending";
-
-      if (bootstrapStatus === "bootstrap_pending") {
-        const now = new Date();
-        const inviteCount = await db
-          .select({ count: count() })
-          .from(invites)
-          .where(
-            and(
-              eq(invites.inviteType, "bootstrap_ceo"),
-              isNull(invites.revokedAt),
-              isNull(invites.acceptedAt),
-              gt(invites.expiresAt, now),
-            ),
-          )
-          .then((rows) => Number(rows[0]?.count ?? 0));
-        bootstrapInviteActive = inviteCount > 0;
-      }
     }
 
     res.json({
@@ -60,7 +42,6 @@ export function healthRoutes(
       deploymentExposure: opts.deploymentExposure,
       authReady: opts.authReady,
       bootstrapStatus,
-      bootstrapInviteActive,
       features: {
         companyDeletionEnabled: opts.companyDeletionEnabled,
       },

server/src/routes/issues.ts

@@ -575,10 +575,6 @@ export function issueRoutes(db: Db, storage: StorageService) {
     }
 
     const assigneeChanged = assigneeWillChange;
-    const statusChangedFromBacklog =
-      existing.status === "backlog" &&
-      issue.status !== "backlog" &&
-      req.body.status !== undefined;
 
     // Merge all wakeups from this update into one enqueue per agent to avoid duplicate runs.
     void (async () => {
@@ -596,18 +592,6 @@ export function issueRoutes(db: Db, storage: StorageService) {
         });
       }
 
-      if (!assigneeChanged && statusChangedFromBacklog && issue.assigneeAgentId) {
-        wakeups.set(issue.assigneeAgentId, {
-          source: "automation",
-          triggerDetail: "system",
-          reason: "issue_status_changed",
-          payload: { issueId: issue.id, mutation: "update" },
-          requestedByActorType: actor.actorType,
-          requestedByActorId: actor.actorId,
-          contextSnapshot: { issueId: issue.id, source: "issue.status_change" },
-        });
-      }
-
       if (commentBody && comment) {
         let mentionedIds: string[] = [];
         try {

server/src/services/agents.ts

@@ -341,17 +341,13 @@ export function agentService(db: Db) {
         await ensureManager(companyId, data.reportsTo);
       }
 
-      const existingAgents = await db
-        .select({ id: agents.id, name: agents.name, status: agents.status })
-        .from(agents)
-        .where(eq(agents.companyId, companyId));
-      const uniqueName = deduplicateAgentName(data.name, existingAgents);
+      await assertCompanyShortnameAvailable(companyId, data.name);
 
       const role = data.role ?? "general";
       const normalizedPermissions = normalizeAgentPermissions(data.permissions, role);
       const created = await db
         .insert(agents)
-        .values({ ...data, name: uniqueName, companyId, role, permissions: normalizedPermissions })
+        .values({ ...data, companyId, role, permissions: normalizedPermissions })
         .returning()
         .then((rows) => rows[0]);
 

server/src/services/heartbeat.ts

@@ -1240,16 +1240,11 @@ export function heartbeatService(db: Db) {
       const mergedConfig = issueAssigneeOverrides?.adapterConfig
         ? { ...config, ...issueAssigneeOverrides.adapterConfig }
         : config;
-      const { config: resolvedConfig, secretKeys } = await secretsSvc.resolveAdapterConfigForRuntime(
+      const resolvedConfig = await secretsSvc.resolveAdapterConfigForRuntime(
         agent.companyId,
         mergedConfig,
       );
       const onAdapterMeta = async (meta: AdapterInvocationMeta) => {
-        if (meta.env && secretKeys.size > 0) {
-          for (const key of secretKeys) {
-            if (key in meta.env) meta.env[key] = "***REDACTED***";
-          }
-        }
         await appendRunEvent(currentRun, seq++, {
           eventType: "adapter.invoke",
           stream: "system",

server/src/services/run-log-store.ts

@@ -2,7 +2,6 @@ import { createReadStream, promises as fs } from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
 import { notFound } from "../errors.js";
-import { resolvePaperclipInstanceRoot } from "../home-paths.js";
 
 export type RunLogStoreType = "local_file";
 
@@ -149,7 +148,7 @@ let cachedStore: RunLogStore | null = null;
 
 export function getRunLogStore() {
   if (cachedStore) return cachedStore;
-  const basePath = process.env.RUN_LOG_BASE_PATH ?? path.resolve(resolvePaperclipInstanceRoot(), "data", "run-logs");
+  const basePath = process.env.RUN_LOG_BASE_PATH ?? path.resolve(process.cwd(), "data/run-logs");
   cachedStore = createLocalFileRunLogStore(basePath);
   return cachedStore;
 }

server/src/services/secrets.ts

@@ -308,11 +308,10 @@ export function secretService(db: Db) {
       return normalized;
     },
 
-    resolveEnvBindings: async (companyId: string, envValue: unknown): Promise<{ env: Record<string, string>; secretKeys: Set<string> }> => {
+    resolveEnvBindings: async (companyId: string, envValue: unknown) => {
       const record = asRecord(envValue);
-      if (!record) return { env: {} as Record<string, string>, secretKeys: new Set<string>() };
+      if (!record) return {} as Record<string, string>;
       const resolved: Record<string, string> = {};
-      const secretKeys = new Set<string>();
 
       for (const [key, rawBinding] of Object.entries(record)) {
         if (!ENV_KEY_RE.test(key)) {
@@ -327,22 +326,20 @@ export function secretService(db: Db) {
           resolved[key] = binding.value;
         } else {
           resolved[key] = await resolveSecretValue(companyId, binding.secretId, binding.version);
-          secretKeys.add(key);
         }
       }
-      return { env: resolved, secretKeys };
+      return resolved;
     },
 
-    resolveAdapterConfigForRuntime: async (companyId: string, adapterConfig: Record<string, unknown>): Promise<{ config: Record<string, unknown>; secretKeys: Set<string> }> => {
+    resolveAdapterConfigForRuntime: async (companyId: string, adapterConfig: Record<string, unknown>) => {
       const resolved = { ...adapterConfig };
-      const secretKeys = new Set<string>();
       if (!Object.prototype.hasOwnProperty.call(adapterConfig, "env")) {
-        return { config: resolved, secretKeys };
+        return resolved;
       }
       const record = asRecord(adapterConfig.env);
       if (!record) {
         resolved.env = {};
-        return { config: resolved, secretKeys };
+        return resolved;
       }
       const env: Record<string, string> = {};
       for (const [key, rawBinding] of Object.entries(record)) {
@@ -358,11 +355,10 @@ export function secretService(db: Db) {
           env[key] = binding.value;
         } else {
           env[key] = await resolveSecretValue(companyId, binding.secretId, binding.version);
-          secretKeys.add(key);
         }
       }
       resolved.env = env;
-      return { config: resolved, secretKeys };
+      return resolved;
     },
   };
 }

server/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../tsconfig.base.json",
+  "extends": "../tsconfig.json",
   "compilerOptions": {
     "outDir": "dist",
     "rootDir": "src"

skills/release-changelog/SKILL.md

@@ -1,178 +1,363 @@
 ---
 name: release-changelog
 description: >
-  Generate the stable Paperclip release changelog at releases/v{version}.md by
-  reading commits, changesets, and merged PR context since the last stable tag.
+  Generate user-facing release changelogs for Paperclip. Reads git history,
+  merged PRs, and changeset files since the last release tag. Detects breaking
+  changes, categorizes changes, and outputs structured markdown to
+  releases/v{version}.md. Use when preparing a release or when asked to
+  generate a changelog.
 ---
 
 # Release Changelog Skill
 
-Generate the user-facing changelog for the **stable** Paperclip release.
+Generate a user-facing changelog for a new Paperclip release. This skill reads
+the commit history, changeset files, and merged PRs since the last release tag,
+detects breaking changes, categorizes everything, and writes a structured
+release notes file.
 
-Output:
+**Output:** `releases/v{version}.md` in the repo root.
+**Review required:** Always present the draft for human sign-off before
+finalizing. Never auto-publish.
 
-- `releases/v{version}.md`
-
-Important rule:
-
-- even if there are canary releases such as `1.2.3-canary.0`, the changelog file stays `releases/v1.2.3.md`
+---
 
 ## Step 0 — Idempotency Check
 
-Before generating anything, check whether the file already exists:
+Before generating anything, check if a changelog already exists for this version:
 
 ```bash
 ls releases/v{version}.md 2>/dev/null
 ```
 
-If it exists:
+**If the file already exists:**
 
-1. read it first
-2. present it to the reviewer
-3. ask whether to keep it, regenerate it, or update specific sections
-4. never overwrite it silently
+1. Read the existing changelog and present it to the reviewer.
+2. Ask: "A changelog for v{version} already exists. Do you want to (a) keep it
+   as-is, (b) regenerate from scratch, or (c) update specific sections?"
+3. If the reviewer says keep it → **stop here**. Do not overwrite. This skill is
+   done.
+4. If the reviewer says regenerate → back up the existing file to
+   `releases/v{version}.md.prev`, then proceed from Step 1.
+5. If the reviewer says update → read the existing file, proceed through Steps
+   1-4 to gather fresh data, then merge changes into the existing file rather
+   than replacing it wholesale. Preserve any manual edits the reviewer previously
+   made.
 
-## Step 1 — Determine the Stable Range
+**If the file does not exist:** Proceed normally from Step 1.
 
-Find the last stable tag:
+**Critical rule:** This skill NEVER triggers a version bump. It only reads git
+history and writes a markdown file. The `release.sh` script is the only thing
+that bumps versions, and it is called separately by the `release` coordination
+skill. Running this skill multiple times is always safe — worst case it
+overwrites a draft changelog (with reviewer permission).
+
+---
+
+## Step 1 — Determine the Release Range
+
+Find the last release tag and the planned version:
 
 ```bash
-git tag --list 'v*' --sort=-version:refname | head -1
-git log v{last}..HEAD --oneline --no-merges
+# Last release tag (most recent semver tag)
+git tag --sort=-version:refname | head -1
+# e.g. v0.2.7
+
+# All commits since that tag
+git log v0.2.7..HEAD --oneline --no-merges
 ```
 
-The planned stable version comes from one of:
+If no tag exists yet, use the initial commit as the base.
 
-- an explicit maintainer request
-- the chosen bump type applied to the last stable tag
-- the release plan already agreed in `doc/RELEASING.md`
+The new version number comes from one of:
+- An explicit argument (e.g. "generate changelog for v0.3.0")
+- The bump type (patch/minor/major) applied to the last tag
+- The version already set in `cli/package.json` if `scripts/release.sh` has been run
 
-Do not derive the changelog version from a canary tag or prerelease suffix.
+---
 
-## Step 2 — Gather the Raw Inputs
+## Step 2 — Gather Raw Change Data
 
-Collect release data from:
+Collect changes from three sources, in priority order:
 
-1. git commits since the last stable tag
-2. `.changeset/*.md` files
-3. merged PRs via `gh` when available
-
-Useful commands:
+### 2a. Git Commits
 
 ```bash
 git log v{last}..HEAD --oneline --no-merges
-git log v{last}..HEAD --format="%H %s" --no-merges
+git log v{last}..HEAD --format="%H %s" --no-merges   # full SHAs for file diffs
+```
+
+### 2b. Changeset Files
+
+Look for unconsumed changesets in `.changeset/`:
+
+```bash
 ls .changeset/*.md | grep -v README.md
+```
+
+Each changeset file has YAML frontmatter with package names and bump types
+(`patch`, `minor`, `major`), followed by a description. Parse these — the bump
+type is a strong categorization signal, and the description may contain
+user-facing summaries.
+
+### 2c. Merged PRs (when available)
+
+If GitHub access is available via `gh`:
+
+```bash
 gh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels
 ```
 
+PR titles and bodies are often the best source of user-facing descriptions.
+Prefer PR descriptions over raw commit messages when both are available.
+
+---
+
 ## Step 3 — Detect Breaking Changes
 
-Look for:
+Scan for breaking changes using these signals. **Any match flags the release as
+containing breaking changes**, which affects version bump requirements and
+changelog structure.
 
-- destructive migrations
-- removed or changed API fields/endpoints
-- renamed or removed config keys
-- `major` changesets
-- `BREAKING:` or `BREAKING CHANGE:` commit signals
+### 3a. Migration Files
 
-Key commands:
+Check for new migration files since the last tag:
 
 ```bash
 git diff --name-only v{last}..HEAD -- packages/db/src/migrations/
+```
+
+- **New migration files exist** = DB migration required in upgrade.
+- Inspect migration content: look for `DROP`, `ALTER ... DROP`, `RENAME` to
+  distinguish destructive vs. additive migrations.
+- Additive-only migrations (new tables, new nullable columns, new indexes) are
+  safe but should still be mentioned.
+- Destructive migrations (column drops, type changes, table drops) = breaking.
+
+### 3b. Schema Changes
+
+```bash
 git diff v{last}..HEAD -- packages/db/src/schema/
+```
+
+Look for:
+- Removed or renamed columns/tables
+- Changed column types
+- Removed default values or nullable constraints
+- These indicate breaking DB changes even if no explicit migration file exists
+
+### 3c. API Route Changes
+
+```bash
 git diff v{last}..HEAD -- server/src/routes/ server/src/api/
-git log v{last}..HEAD --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true
 ```
 
-If the requested bump is lower than the minimum required bump, flag that before the release proceeds.
+Look for:
+- Removed endpoints
+- Changed request/response shapes (removed fields, type changes)
+- Changed authentication requirements
 
-## Step 4 — Categorize for Users
+### 3d. Config Changes
 
-Use these stable changelog sections:
-
-- `Breaking Changes`
-- `Highlights`
-- `Improvements`
-- `Fixes`
-- `Upgrade Guide` when needed
-
-Exclude purely internal refactors, CI changes, and docs-only work unless they materially affect users.
-
-Guidelines:
-
-- group related commits into one user-facing entry
-- write from the user perspective
-- keep highlights short and concrete
-- spell out upgrade actions for breaking changes
-
-### Inline PR and contributor attribution
-
-When a bullet item clearly maps to a merged pull request, add inline attribution at the
-end of the entry in this format:
-
-```
-- **Feature name** — Description. ([#123](https://github.com/paperclipai/paperclip/pull/123), @contributor1, @contributor2)
+```bash
+git diff v{last}..HEAD -- cli/src/config/ packages/*/src/*config*
 ```
 
-Rules:
+Look for renamed, removed, or restructured configuration keys.
 
-- Only add a PR link when you can confidently trace the bullet to a specific merged PR.
-  Use merge commit messages (`Merge pull request #N from user/branch`) to map PRs.
-- List the contributor(s) who authored the PR. Use GitHub usernames, not real names or emails.
-- If multiple PRs contributed to a single bullet, list them all: `([#10](url), [#12](url), @user1, @user2)`.
-- If you cannot determine the PR number or contributor with confidence, omit the attribution
-  parenthetical — do not guess.
-- Core maintainer commits that don't have an external PR can omit the parenthetical.
+### 3e. Changeset Severity
 
-## Step 5 — Write the File
+Any `.changeset/*.md` file with a `major` bump = explicitly flagged breaking.
 
-Template:
+### 3f. Commit Conventions
+
+Scan commit messages for:
+- `BREAKING:` or `BREAKING CHANGE:` prefix
+- `!` after the type in conventional commits (e.g. `feat!:`, `fix!:`)
+
+### Version Bump Rules
+
+| Condition | Minimum Bump |
+|---|---|
+| Destructive migration (DROP, RENAME) | `major` |
+| Removed API endpoints or fields | `major` |
+| Any `major` changeset or `BREAKING:` commit | `major` |
+| New (additive) migration | `minor` |
+| New features (`feat:` commits, `minor` changesets) | `minor` |
+| Bug fixes only | `patch` |
+
+If the planned bump is lower than the minimum required, **warn the reviewer**
+and recommend the correct bump level.
+
+---
+
+## Step 4 — Categorize Changes
+
+Assign every meaningful change to one of these categories:
+
+| Category | What Goes Here | Shows in User Notes? |
+|---|---|---|
+| **Breaking Changes** | Anything requiring user action to upgrade | Yes (top, with warning) |
+| **Highlights** | New user-visible features, major behavioral changes | Yes (with 1-2 sentence descriptions) |
+| **Improvements** | Enhancements to existing features | Yes (bullet list) |
+| **Fixes** | Bug fixes | Yes (bullet list) |
+| **Internal** | Refactoring, deps, CI, tests, docs | No (dev changelog only) |
+
+### Categorization Heuristics
+
+Use these signals to auto-categorize. When signals conflict, prefer the
+higher-visibility category and flag for human review.
+
+| Signal | Category |
+|---|---|
+| Commit touches migration files, schema changes | Breaking Change (if destructive) |
+| Changeset marked `major` | Breaking Change |
+| Commit message has `BREAKING:` or `!:` | Breaking Change |
+| New UI components, new routes, new API endpoints | Highlight |
+| Commit message starts with `feat:` or `add:` | Highlight or Improvement |
+| Changeset marked `minor` | Highlight |
+| Commit message starts with `fix:` or `bug:` | Fix |
+| Changeset marked `patch` | Fix or Improvement |
+| Commit message starts with `chore:`, `refactor:`, `ci:`, `test:`, `docs:` | Internal |
+| PR has detailed body with user-facing description | Use PR body as the description |
+
+### Writing Good Descriptions
+
+- **Highlights** get 1-2 sentence descriptions explaining the user benefit.
+  Write from the user's perspective ("You can now..." not "Added a component that...").
+- **Improvements and Fixes** are concise bullet points.
+- **Breaking Changes** get detailed descriptions including what changed,
+  why, and what the user needs to do.
+- Group related commits into a single changelog entry. Five commits implementing
+  one feature = one Highlight entry, not five bullets.
+- Omit purely internal changes from user-facing notes entirely.
+
+---
+
+## Step 5 — Write the Changelog
+
+Output the changelog to `releases/v{version}.md` using this template:
 
 ```markdown
 # v{version}
 
 > Released: {YYYY-MM-DD}
 
+{If breaking changes detected, include this section:}
+
 ## Breaking Changes
 
+> **Action required before upgrading.** Read the Upgrade Guide below.
+
+- **{Breaking change title}** — {What changed and why. What the user needs to do.}
+
 ## Highlights
 
+- **{Feature name}** — {1-2 sentence description of what it does and why it matters.}
+
 ## Improvements
 
+- {Concise description of improvement}
+
 ## Fixes
 
+- {Concise description of fix}
+
+---
+
+{If breaking changes detected, include this section:}
+
 ## Upgrade Guide
 
-## Contributors
+### Before You Update
 
-Thank you to everyone who contributed to this release!
+1. **Back up your database.**
+   - SQLite: `cp paperclip.db paperclip.db.backup`
+   - Postgres: `pg_dump -Fc paperclip > paperclip-pre-{version}.dump`
+2. **Note your current version:** `paperclip --version`
 
-@username1, @username2, @username3
+### After Updating
+
+{Specific steps: run migrations, update configs, etc.}
+
+### Rolling Back
+
+If something goes wrong:
+1. Restore your database backup
+2. `npm install @paperclipai/server@{previous-version}`
 ```
 
-Omit empty sections except `Highlights`, `Improvements`, and `Fixes`, which should usually exist.
+### Template Rules
 
-The `Contributors` section should always be included. List every person who authored
-commits in the release range, @-mentioning them by their **GitHub username** (not their
-real name or email). To find GitHub usernames:
+- Omit any empty section entirely (don't show "## Fixes" with no bullets).
+- The Breaking Changes section always comes first when present.
+- The Upgrade Guide always comes last when present.
+- Use `**bold**` for feature/change names, regular text for descriptions.
+- Keep the entire changelog scannable — a busy user should get the gist from
+  headings and bold text alone.
 
-1. Extract usernames from merge commit messages: `git log v{last}..HEAD --oneline --merges` — the branch prefix (e.g. `from username/branch`) gives the GitHub username.
-2. For noreply emails like `user@users.noreply.github.com`, the username is the part before `@`.
-3. For contributors whose username is ambiguous, check `gh api users/{guess}` or the PR page.
+---
 
-**Never expose contributor email addresses.** Use `@username` only.
+## Step 6 — Present for Review
 
-Exclude bot accounts (e.g. `lockfile-bot`, `dependabot`) from the list. List contributors
-in alphabetical order by GitHub username (case-insensitive).
+After generating the draft:
 
-## Step 6 — Review Before Release
+1. **Show the full changelog** to the reviewer (CTO or whoever triggered the release).
+2. **Flag ambiguous items** — commits you weren't sure how to categorize, or
+   items that might be breaking but aren't clearly signaled.
+3. **Flag version bump mismatches** — if the planned bump is lower than what
+   the changes warrant.
+4. **Wait for approval** before considering the changelog final.
 
-Before handing it off:
+If the reviewer requests edits, update `releases/v{version}.md` accordingly.
 
-1. confirm the heading is the stable version only
-2. confirm there is no `-canary` language in the title or filename
-3. confirm any breaking changes have an upgrade path
-4. present the draft for human sign-off
+Do not proceed to publishing, website updates, or social announcements. Those
+are handled by the `release` coordination skill (separate from this one).
 
-This skill never publishes anything. It only prepares the stable changelog artifact.
+---
+
+## Directory Convention
+
+Release changelogs live in `releases/` at the repo root:
+
+```
+releases/
+  v0.2.7.md
+  v0.3.0.md
+  ...
+```
+
+Each file is named `v{version}.md` matching the git tag. This directory is
+committed to the repo and serves as the source of truth for release history.
+
+The `releases/` directory should be created with a `.gitkeep` if it doesn't
+exist yet.
+
+---
+
+## Quick Reference
+
+```bash
+# Full workflow summary:
+
+# 1. Find last tag
+LAST_TAG=$(git tag --sort=-version:refname | head -1)
+
+# 2. Commits since last tag
+git log $LAST_TAG..HEAD --oneline --no-merges
+
+# 3. Files changed (for breaking change detection)
+git diff --name-only $LAST_TAG..HEAD
+
+# 4. Migration changes specifically
+git diff --name-only $LAST_TAG..HEAD -- packages/db/src/migrations/
+
+# 5. Schema changes
+git diff $LAST_TAG..HEAD -- packages/db/src/schema/
+
+# 6. Unconsumed changesets
+ls .changeset/*.md | grep -v README.md
+
+# 7. Merged PRs (if gh available)
+gh pr list --state merged --search "merged:>=$(git log -1 --format=%aI $LAST_TAG)" \
+  --json number,title,body,labels
+```

skills/release/SKILL.md

@@ -1,261 +1,402 @@
 ---
 name: release
 description: >
-  Coordinate a full Paperclip release across engineering verification, npm,
-  GitHub, website publishing, and announcement follow-up. Use when leadership
-  asks to ship a release, not merely to discuss version bumps.
+  Coordinate a full Paperclip release across engineering, website publishing,
+  and social announcement. Use when CTO/CEO requests "do a release" or
+  "release vX.Y.Z". Runs pre-flight checks, generates changelog via
+  release-changelog, executes npm release, creates cross-project follow-up
+  tasks, and posts a release wrap-up.
 ---
 
 # Release Coordination Skill
 
-Run the full Paperclip release as a maintainer workflow, not just an npm publish.
+Run the full Paperclip release process as an organizational workflow, not just
+an npm publish.
 
 This skill coordinates:
+- User-facing changelog generation (`release-changelog` skill)
+- Canary publish to npm (`scripts/release.sh --canary`)
+- Docker smoke test of the canary (`scripts/docker-onboard-smoke.sh`)
+- Promotion to `latest` after canary is verified
+- Website publishing task creation
+- CMO announcement task creation
+- Final release summary with links
 
-- stable changelog drafting via `release-changelog`
-- release-train setup via `scripts/release-start.sh`
-- prerelease canary publishing via `scripts/release.sh --canary`
-- Docker smoke testing via `scripts/docker-onboard-smoke.sh`
-- stable publishing via `scripts/release.sh`
-- pushing the stable branch commit and tag
-- GitHub Release creation via `scripts/create-github-release.sh`
-- website / announcement follow-up tasks
+---
 
 ## Trigger
 
 Use this skill when leadership asks for:
-
 - "do a release"
-- "ship the next patch/minor/major"
+- "release {patch|minor|major}"
 - "release vX.Y.Z"
 
+---
+
 ## Preconditions
 
 Before proceeding, verify all of the following:
 
 1. `skills/release-changelog/SKILL.md` exists and is usable.
-2. The repo working tree is clean, including untracked files.
-3. There are commits since the last stable tag.
-4. The release SHA has passed the verification gate or is about to.
-5. If package manifests changed, the CI-owned `pnpm-lock.yaml` refresh is already merged on `master` before the release branch is cut.
-6. npm publish rights are available locally, or the GitHub release workflow is being used with trusted publishing.
-7. If running through Paperclip, you have issue context for status updates and follow-up task creation.
+2. The `release-changelog` dependency work is complete/reviewed before running this flow.
+3. App repo working tree is clean.
+4. There are commits since the last release tag.
+5. You have release permissions (`npm whoami` succeeds for real publish).
+6. If running via Paperclip, you have issue context for posting status updates.
 
 If any precondition fails, stop and report the blocker.
 
+---
+
 ## Inputs
 
 Collect these inputs up front:
 
-- requested bump: `patch`, `minor`, or `major`
-- whether this run is a dry run or live release
-- whether the release is being run locally or from GitHub Actions
-- release issue / company context for website and announcement follow-up
+- Release request source issue (if in Paperclip)
+- Requested bump (`patch|minor|major`) or explicit version (`vX.Y.Z`)
+- Whether this run is dry-run or live publish
+- Company/project context for follow-up issue creation
 
-## Step 0 — Release Model
+---
 
-Paperclip now uses this release model:
+## Step 0 — Idempotency Guards
 
-1. Start or resume `release/X.Y.Z`
-2. Draft the **stable** changelog as `releases/vX.Y.Z.md`
-3. Publish one or more **prerelease canaries** such as `X.Y.Z-canary.0`
-4. Smoke test the canary via Docker
-5. Publish the stable version `X.Y.Z`
-6. Push the stable branch commit and tag
-7. Create the GitHub Release
-8. Merge `release/X.Y.Z` back to `master` without squash or rebase
-9. Complete website and announcement surfaces
+Each step in this skill is designed to be safely re-runnable. Before executing
+any step, check whether it has already been completed:
 
-Critical consequence:
+| Step | How to Check | If Already Done |
+|---|---|---|
+| Changelog | `releases/v{version}.md` exists | Read it, ask reviewer to confirm or update. Do NOT regenerate without asking. |
+| Canary publish | `npm view paperclipai@{version}` succeeds | Skip canary publish. Proceed to smoke test. |
+| Smoke test | Manual or scripted verification | If canary already verified, proceed to promote. |
+| Promote | `git tag v{version}` exists | Skip promotion entirely. A tag means the version is already promoted to latest. |
+| Website task | Search Paperclip issues for "Publish release notes for v{version}" | Skip creation. Link the existing task. |
+| CMO task | Search Paperclip issues for "release announcement tweet for v{version}" | Skip creation. Link the existing task. |
 
-- Canaries do **not** use promote-by-dist-tag anymore.
-- The changelog remains stable-only. Do not create `releases/vX.Y.Z-canary.N.md`.
+**The golden rule:** If a git tag `v{version}` already exists, the release is
+fully promoted. Only post-publish tasks (website, CMO, wrap-up) should proceed.
+If the version exists on npm but there's no git tag, the canary was published but
+not yet promoted — resume from smoke test.
 
-## Step 1 — Decide the Stable Version
+**Iterating on changelogs:** You can re-run this skill with an existing changelog
+to refine it _before_ the npm publish step. The `release-changelog` skill has
+its own idempotency check and will ask the reviewer what to do with an existing
+file. This is the expected workflow for iterating on release notes.
 
-Start the release train first:
+---
+
+## Step 1 - Pre-flight and Version Decision
+
+Run pre-flight in the App repo root:
 
 ```bash
-./scripts/release-start.sh {patch|minor|major}
+LAST_TAG=$(git tag --sort=-version:refname | head -1)
+git diff --quiet && git diff --cached --quiet
+git log "${LAST_TAG}..HEAD" --oneline --no-merges | head -50
 ```
 
-Then run release preflight:
+Then detect minimum required bump:
 
 ```bash
-./scripts/release-preflight.sh canary {patch|minor|major}
-# or
-./scripts/release-preflight.sh stable {patch|minor|major}
-```
-
-Then use the last stable tag as the base:
-
-```bash
-LAST_TAG=$(git tag --list 'v*' --sort=-version:refname | head -1)
-git log "${LAST_TAG}..HEAD" --oneline --no-merges
+# migrations
 git diff --name-only "${LAST_TAG}..HEAD" -- packages/db/src/migrations/
+
+# schema deltas
 git diff "${LAST_TAG}..HEAD" -- packages/db/src/schema/
+
+# breaking commit conventions
 git log "${LAST_TAG}..HEAD" --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true
 ```
 
 Bump policy:
+- Destructive migration/API removal/major changeset/breaking commit -> `major`
+- Additive migrations or clear new features -> at least `minor`
+- Fixes-only -> `patch`
 
-- destructive migrations, removed APIs, breaking config changes -> `major`
-- additive migrations or clearly user-visible features -> at least `minor`
-- fixes only -> `patch`
+If requested bump is lower than required minimum, escalate bump and explain why.
 
-If the requested bump is too low, escalate it and explain why.
+---
 
-## Step 2 — Draft the Stable Changelog
+## Step 2 - Generate Changelog Draft
 
-Invoke `release-changelog` and generate:
+First, check if `releases/v{version}.md` already exists. If it does, the
+`release-changelog` skill will detect this and ask the reviewer whether to keep,
+regenerate, or update it. **Do not silently overwrite an existing changelog.**
 
-- `releases/vX.Y.Z.md`
+Invoke the `release-changelog` skill and produce:
+- `releases/v{version}.md`
+- Sections ordered as: Breaking Changes (if any), Highlights, Improvements, Fixes, Upgrade Guide (if any)
 
-Rules:
+Required behavior:
+- Present the draft for human review.
+- Flag ambiguous categorization items.
+- Flag bump mismatches before publish.
+- Do not publish until reviewer confirms.
 
-- review the draft with a human before publish
-- preserve manual edits if the file already exists
-- keep the heading and filename stable-only, for example `v1.2.3`
-- do not create a separate canary changelog file
+---
 
-## Step 3 — Verify the Release SHA
+## Step 3 — Publish Canary
 
-Run the standard gate:
+The canary is the gatekeeper: every release goes to npm as a canary first. The
+`latest` tag is never touched until the canary passes smoke testing.
+
+**Idempotency check:** Before publishing, check if this version already exists
+on npm:
 
 ```bash
-pnpm -r typecheck
-pnpm test:run
-pnpm build
+# Check if canary is already published
+npm view paperclipai@{version} version 2>/dev/null && echo "ALREADY_PUBLISHED" || echo "NOT_PUBLISHED"
+
+# Also check git tag
+git tag -l "v{version}"
 ```
 
-If the release will be run through GitHub Actions, the workflow can rerun this gate. Still report whether the local tree currently passes.
+- If a git tag exists → the release is already fully promoted. Skip to Step 6.
+- If the version exists on npm but no git tag → canary was published but not yet
+  promoted. Skip to Step 4 (smoke test).
+- If neither exists → proceed with canary publish.
 
-The GitHub Actions release workflow installs with `pnpm install --frozen-lockfile`. Treat that as a release invariant, not a nuisance: if manifests changed and the lockfile refresh PR has not landed yet, stop and wait for `master` to contain the committed lockfile before shipping.
+### Publishing the canary
 
-## Step 4 — Publish a Canary
-
-Run from the `release/X.Y.Z` branch:
+Use `release.sh` with the `--canary` flag (see script changes below):
 
 ```bash
+# Dry run first
 ./scripts/release.sh {patch|minor|major} --canary --dry-run
+
+# Publish canary (after dry-run review)
 ./scripts/release.sh {patch|minor|major} --canary
 ```
 
-What this means:
+This publishes all packages to npm with the `canary` dist-tag. The `latest` tag
+is **not** updated. Users running `npx paperclipai onboard` still get the
+previous stable version.
 
-- npm receives `X.Y.Z-canary.N` under dist-tag `canary`
-- `latest` remains unchanged
-- no git tag is created
-- the script cleans the working tree afterward
-
-Guard:
-
-- if the current stable is `0.2.7`, the next patch canary is `0.2.8-canary.0`
-- the tooling must never publish `0.2.7-canary.N` after `0.2.7` is already stable
-
-After publish, verify:
+After publish, verify the canary is accessible:
 
 ```bash
 npm view paperclipai@canary version
+# Should show the new version
 ```
 
-The user install path is:
+**How `--canary` works in release.sh:**
+- Steps 1-5 are the same (preflight, changeset, version, build, CLI bundle)
+- Step 6 uses `npx changeset publish --tag canary` instead of `npx changeset publish`
+- Step 7 does NOT commit or tag — the commit and tag happen later in the promote
+  step, only after smoke testing passes
 
-```bash
-npx paperclipai@canary onboard
-```
+**Script changes required:** Add `--canary` support to `scripts/release.sh`:
+- Parse `--canary` flag alongside `--dry-run`
+- When `--canary`: pass `--tag canary` to `changeset publish`
+- When `--canary`: skip the git commit and tag step (Step 7)
+- When NOT `--canary`: behavior is unchanged (backwards compatible)
 
-## Step 5 — Smoke Test the Canary
+---
 
-Run:
+## Step 4 — Smoke Test the Canary
+
+Run the canary in a clean Docker environment to verify `npx paperclipai onboard`
+works end-to-end.
+
+### Automated smoke test
+
+Use the existing Docker smoke test infrastructure with the canary version:
 
 ```bash
 PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
 ```
 
-Confirm:
+This builds a clean Ubuntu container, installs `paperclipai@canary` via npx, and
+runs the onboarding flow. The UI is accessible at `http://localhost:3131`.
 
-1. install succeeds
-2. onboarding completes
-3. server boots
-4. UI loads
-5. basic company/dashboard flow works
+### What to verify
 
-If smoke testing fails:
+At minimum, confirm:
 
-- stop the stable release
-- fix the issue
-- publish another canary
-- repeat the smoke test
+1. **Container starts** — no npm install errors, no missing dependencies
+2. **Onboarding completes** — the wizard runs through without crashes
+3. **Server boots** — UI is accessible at the expected port
+4. **Basic operations** — can create a company, view the dashboard
 
-Each retry should create a higher canary ordinal, while the stable target version can stay the same.
+For a more thorough check (stretch goal — can be automated later):
 
-## Step 6 — Publish Stable
+5. **Browser automation** — script Playwright/Puppeteer to walk through onboard
+   in the Docker container's browser and verify key pages render
 
-Once the SHA is vetted, run:
+### If smoke test fails
+
+- Do NOT promote the canary.
+- Fix the issue, publish a new canary (re-run Step 3 — idempotency guards allow
+  this since there's no git tag yet).
+- Re-run the smoke test.
+
+### If smoke test passes
+
+Proceed to Step 5 (promote).
+
+---
+
+## Step 5 — Promote Canary to Latest
+
+Once the canary passes smoke testing, promote it to `latest` so that
+`npx paperclipai onboard` picks up the new version.
+
+### Promote on npm
 
 ```bash
-./scripts/release.sh {patch|minor|major} --dry-run
-./scripts/release.sh {patch|minor|major}
+# For each published package, move the dist-tag from canary to latest
+npm dist-tag add paperclipai@{version} latest
+npm dist-tag add @paperclipai/server@{version} latest
+npm dist-tag add @paperclipai/cli@{version} latest
+npm dist-tag add @paperclipai/shared@{version} latest
+npm dist-tag add @paperclipai/db@{version} latest
+npm dist-tag add @paperclipai/adapter-utils@{version} latest
+npm dist-tag add @paperclipai/adapter-claude-local@{version} latest
+npm dist-tag add @paperclipai/adapter-codex-local@{version} latest
+npm dist-tag add @paperclipai/adapter-openclaw-gateway@{version} latest
 ```
 
-Stable publish does this:
+**Script option:** Add `./scripts/release.sh --promote {version}` to automate
+the dist-tag promotion for all packages.
 
-- publishes `X.Y.Z` to npm under `latest`
-- creates the local release commit
-- creates the local git tag `vX.Y.Z`
+### Commit and tag
 
-Stable publish does **not** push the release for you.
-
-## Step 7 — Push and Create GitHub Release
-
-After stable publish succeeds:
+After promotion, finalize in git (this is what `release.sh` Step 7 normally
+does, but was deferred during canary publish):
 
 ```bash
-git push public-gh HEAD --follow-tags
-./scripts/create-github-release.sh X.Y.Z
+git add .
+git commit -m "chore: release v{version}"
+git tag "v{version}"
 ```
 
-Use the stable changelog file as the GitHub Release notes source.
+### Verify promotion
 
-Then open the PR from `release/X.Y.Z` back to `master` and merge without squash or rebase.
+```bash
+npm view paperclipai@latest version
+# Should now show the new version
 
-## Step 8 — Finish the Other Surfaces
+# Final sanity check
+npx --yes paperclipai@latest --version
+```
 
-Create or verify follow-up work for:
+---
 
-- website changelog publishing
-- launch post / social announcement
-- any release summary in Paperclip issue context
+## Step 6 - Create Cross-Project Follow-up Tasks
 
-These should reference the stable release, not the canary.
+**Idempotency check:** Before creating tasks, search for existing ones:
+
+```
+GET /api/companies/{companyId}/issues?q=release+notes+v{version}
+GET /api/companies/{companyId}/issues?q=announcement+tweet+v{version}
+```
+
+If matching tasks already exist (check title contains the version), skip
+creation and link the existing tasks instead. Do not create duplicates.
+
+Create at least two tasks in Paperclip (only if they don't already exist):
+
+1. Website task: publish changelog for `v{version}`
+2. CMO task: draft announcement tweet for `v{version}`
+
+When creating tasks:
+- Set `parentId` to the release issue id.
+- Carry over `goalId` from the parent issue when present.
+- Include `billingCode` for cross-team work when required by company policy.
+- Mark website task `high` priority if release has breaking changes.
+
+Suggested payloads:
+
+```json
+POST /api/companies/{companyId}/issues
+{
+  "projectId": "{websiteProjectId}",
+  "parentId": "{releaseIssueId}",
+  "goalId": "{goalId-or-null}",
+  "billingCode": "{billingCode-or-null}",
+  "title": "Publish release notes for v{version}",
+  "priority": "medium",
+  "status": "todo",
+  "description": "Publish /changelog entry for v{version}. Include full markdown from releases/v{version}.md and prominent upgrade guide if breaking changes exist."
+}
+```
+
+```json
+POST /api/companies/{companyId}/issues
+{
+  "projectId": "{workspaceProjectId}",
+  "parentId": "{releaseIssueId}",
+  "goalId": "{goalId-or-null}",
+  "billingCode": "{billingCode-or-null}",
+  "title": "Draft release announcement tweet for v{version}",
+  "priority": "medium",
+  "status": "todo",
+  "description": "Draft launch tweet with top 1-2 highlights, version number, and changelog URL. If breaking changes exist, include an explicit upgrade-guide callout."
+}
+```
+
+---
+
+## Step 7 - Wrap Up the Release Issue
+
+Post a concise markdown update linking:
+- Release issue
+- Changelog file (`releases/v{version}.md`)
+- npm package URL (both `@canary` and `@latest` after promotion)
+- Canary smoke test result (pass/fail, what was tested)
+- Website task
+- CMO task
+- Final changelog URL (once website publishes)
+- Tweet URL (once published)
+
+Completion rules:
+- Keep issue `in_progress` until canary is promoted AND website + social tasks
+  are done.
+- Mark `done` only when all required artifacts are published and linked.
+- If waiting on another team, keep open with clear owner and next action.
+
+---
+
+## Release Flow Summary
+
+The full release lifecycle is now:
+
+```
+1. Generate changelog      → releases/v{version}.md (review + iterate)
+2. Publish canary           → npm @canary dist-tag (latest untouched)
+3. Smoke test canary        → Docker clean install verification
+4. Promote to latest        → npm @latest dist-tag + git tag + commit
+5. Create follow-up tasks   → website changelog + CMO tweet
+6. Wrap up                  → link everything, close issue
+```
+
+At any point you can re-enter the flow — idempotency guards detect which steps
+are already done and skip them. The changelog can be iterated before or after
+canary publish. The canary can be re-published if the smoke test reveals issues
+(just fix + re-run Step 3). Only after smoke testing passes does `latest` get
+updated.
+
+---
+
+## Paperclip API Notes (When Running in Agent Context)
+
+Use:
+- `GET /api/companies/{companyId}/projects` to resolve website/workspace project IDs.
+- `POST /api/companies/{companyId}/issues` to create follow-up tasks.
+- `PATCH /api/issues/{issueId}` with comments for release progress.
+
+For issue-modifying calls, include:
+- `Authorization: Bearer $PAPERCLIP_API_KEY`
+- `X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID`
+
+---
 
 ## Failure Handling
 
-If the canary is bad:
+If blocked, update the release issue explicitly with:
+- what failed
+- exact blocker
+- who must act next
+- whether any release artifacts were partially published
 
-- publish another canary, do not ship stable
-
-If stable npm publish succeeds but push or GitHub release creation fails:
-
-- fix the git/GitHub issue immediately from the same checkout
-- do not republish the same version
-
-If `latest` is bad after stable publish:
-
-```bash
-./scripts/rollback-latest.sh <last-good-version>
-```
-
-Then fix forward with a new patch release.
-
-## Output
-
-When the skill completes, provide:
-
-- stable version and, if relevant, the final canary version tested
-- verification status
-- npm status
-- git tag / GitHub Release status
-- website / announcement follow-up status
-- rollback recommendation if anything is still partially complete
+Never silently fail mid-release.

tests/e2e/onboarding.spec.ts

@@ -1,172 +0,0 @@
-import { test, expect } from "@playwright/test";
-
-/**
- * E2E: Onboarding wizard flow (skip_llm mode).
- *
- * Walks through the 4-step OnboardingWizard:
- *   Step 1 — Name your company
- *   Step 2 — Create your first agent (adapter selection + config)
- *   Step 3 — Give it something to do (task creation)
- *   Step 4 — Ready to launch (summary + open issue)
- *
- * By default this runs in skip_llm mode: we do NOT assert that an LLM
- * heartbeat fires. Set PAPERCLIP_E2E_SKIP_LLM=false to enable LLM-dependent
- * assertions (requires a valid ANTHROPIC_API_KEY).
- */
-
-const SKIP_LLM = process.env.PAPERCLIP_E2E_SKIP_LLM !== "false";
-
-const COMPANY_NAME = `E2E-Test-${Date.now()}`;
-const AGENT_NAME = "CEO";
-const TASK_TITLE = "E2E test task";
-
-test.describe("Onboarding wizard", () => {
-  test("completes full wizard flow", async ({ page }) => {
-    // Navigate to root — should auto-open onboarding when no companies exist
-    await page.goto("/");
-
-    // If the wizard didn't auto-open (company already exists), click the button
-    const wizardHeading = page.locator("h3", { hasText: "Name your company" });
-    const newCompanyBtn = page.getByRole("button", { name: "New Company" });
-
-    // Wait for either the wizard or the start page
-    await expect(
-      wizardHeading.or(newCompanyBtn)
-    ).toBeVisible({ timeout: 15_000 });
-
-    if (await newCompanyBtn.isVisible()) {
-      await newCompanyBtn.click();
-    }
-
-    // -----------------------------------------------------------
-    // Step 1: Name your company
-    // -----------------------------------------------------------
-    await expect(wizardHeading).toBeVisible({ timeout: 5_000 });
-    await expect(page.locator("text=Step 1 of 4")).toBeVisible();
-
-    const companyNameInput = page.locator('input[placeholder="Acme Corp"]');
-    await companyNameInput.fill(COMPANY_NAME);
-
-    // Click Next
-    const nextButton = page.getByRole("button", { name: "Next" });
-    await nextButton.click();
-
-    // -----------------------------------------------------------
-    // Step 2: Create your first agent
-    // -----------------------------------------------------------
-    await expect(
-      page.locator("h3", { hasText: "Create your first agent" })
-    ).toBeVisible({ timeout: 10_000 });
-    await expect(page.locator("text=Step 2 of 4")).toBeVisible();
-
-    // Agent name should default to "CEO"
-    const agentNameInput = page.locator('input[placeholder="CEO"]');
-    await expect(agentNameInput).toHaveValue(AGENT_NAME);
-
-    // Claude Code adapter should be selected by default
-    await expect(
-      page.locator("button", { hasText: "Claude Code" }).locator("..")
-    ).toBeVisible();
-
-    // Select the "Process" adapter to avoid needing a real CLI tool installed
-    await page.locator("button", { hasText: "Process" }).click();
-
-    // Fill in process adapter fields
-    const commandInput = page.locator('input[placeholder="e.g. node, python"]');
-    await commandInput.fill("echo");
-    const argsInput = page.locator(
-      'input[placeholder="e.g. script.js, --flag"]'
-    );
-    await argsInput.fill("hello");
-
-    // Click Next (process adapter skips environment test)
-    await page.getByRole("button", { name: "Next" }).click();
-
-    // -----------------------------------------------------------
-    // Step 3: Give it something to do
-    // -----------------------------------------------------------
-    await expect(
-      page.locator("h3", { hasText: "Give it something to do" })
-    ).toBeVisible({ timeout: 10_000 });
-    await expect(page.locator("text=Step 3 of 4")).toBeVisible();
-
-    // Clear default title and set our test title
-    const taskTitleInput = page.locator(
-      'input[placeholder="e.g. Research competitor pricing"]'
-    );
-    await taskTitleInput.clear();
-    await taskTitleInput.fill(TASK_TITLE);
-
-    // Click Next
-    await page.getByRole("button", { name: "Next" }).click();
-
-    // -----------------------------------------------------------
-    // Step 4: Ready to launch
-    // -----------------------------------------------------------
-    await expect(
-      page.locator("h3", { hasText: "Ready to launch" })
-    ).toBeVisible({ timeout: 10_000 });
-    await expect(page.locator("text=Step 4 of 4")).toBeVisible();
-
-    // Verify summary displays our created entities
-    await expect(page.locator("text=" + COMPANY_NAME)).toBeVisible();
-    await expect(page.locator("text=" + AGENT_NAME)).toBeVisible();
-    await expect(page.locator("text=" + TASK_TITLE)).toBeVisible();
-
-    // Click "Open Issue"
-    await page.getByRole("button", { name: "Open Issue" }).click();
-
-    // Should navigate to the issue page
-    await expect(page).toHaveURL(/\/issues\//, { timeout: 10_000 });
-
-    // -----------------------------------------------------------
-    // Verify via API that entities were created
-    // -----------------------------------------------------------
-    const baseUrl = page.url().split("/").slice(0, 3).join("/");
-
-    // List companies and find ours
-    const companiesRes = await page.request.get(`${baseUrl}/api/companies`);
-    expect(companiesRes.ok()).toBe(true);
-    const companies = await companiesRes.json();
-    const company = companies.find(
-      (c: { name: string }) => c.name === COMPANY_NAME
-    );
-    expect(company).toBeTruthy();
-
-    // List agents for our company
-    const agentsRes = await page.request.get(
-      `${baseUrl}/api/companies/${company.id}/agents`
-    );
-    expect(agentsRes.ok()).toBe(true);
-    const agents = await agentsRes.json();
-    const ceoAgent = agents.find(
-      (a: { name: string }) => a.name === AGENT_NAME
-    );
-    expect(ceoAgent).toBeTruthy();
-    expect(ceoAgent.role).toBe("ceo");
-    expect(ceoAgent.adapterType).toBe("process");
-
-    // List issues for our company
-    const issuesRes = await page.request.get(
-      `${baseUrl}/api/companies/${company.id}/issues`
-    );
-    expect(issuesRes.ok()).toBe(true);
-    const issues = await issuesRes.json();
-    const task = issues.find(
-      (i: { title: string }) => i.title === TASK_TITLE
-    );
-    expect(task).toBeTruthy();
-    expect(task.assigneeAgentId).toBe(ceoAgent.id);
-
-    if (!SKIP_LLM) {
-      // LLM-dependent: wait for the heartbeat to transition the issue
-      await expect(async () => {
-        const res = await page.request.get(
-          `${baseUrl}/api/issues/${task.id}`
-        );
-        const issue = await res.json();
-        expect(["in_progress", "done"]).toContain(issue.status);
-      }).toPass({ timeout: 120_000, intervals: [5_000] });
-    }
-  });
-});

tests/e2e/playwright.config.ts

@@ -1,35 +0,0 @@
-import { defineConfig } from "@playwright/test";
-
-const PORT = Number(process.env.PAPERCLIP_E2E_PORT ?? 3100);
-const BASE_URL = `http://127.0.0.1:${PORT}`;
-
-export default defineConfig({
-  testDir: ".",
-  testMatch: "**/*.spec.ts",
-  timeout: 60_000,
-  retries: 0,
-  use: {
-    baseURL: BASE_URL,
-    headless: true,
-    screenshot: "only-on-failure",
-    trace: "on-first-retry",
-  },
-  projects: [
-    {
-      name: "chromium",
-      use: { browserName: "chromium" },
-    },
-  ],
-  // The webServer directive starts `paperclipai run` before tests.
-  // Expects `pnpm paperclipai` to be runnable from repo root.
-  webServer: {
-    command: `pnpm paperclipai run --yes`,
-    url: `${BASE_URL}/api/health`,
-    reuseExistingServer: !!process.env.CI,
-    timeout: 120_000,
-    stdout: "pipe",
-    stderr: "pipe",
-  },
-  outputDir: "./test-results",
-  reporter: [["list"], ["html", { open: "never", outputFolder: "./playwright-report" }]],
-});

tsconfig.base.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2023",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "esModuleInterop": true,
-    "strict": true,
-    "skipLibCheck": true,
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true
-  }
-}

tsconfig.json

@@ -1,18 +1,18 @@
 {
-  "extends": "./tsconfig.base.json",
-  "files": [],
-  "references": [
-    { "path": "./packages/adapter-utils" },
-    { "path": "./packages/shared" },
-    { "path": "./packages/db" },
-    { "path": "./packages/adapters/claude-local" },
-    { "path": "./packages/adapters/codex-local" },
-    { "path": "./packages/adapters/cursor-local" },
-    { "path": "./packages/adapters/openclaw-gateway" },
-    { "path": "./packages/adapters/opencode-local" },
-    { "path": "./packages/adapters/pi-local" },
-    { "path": "./server" },
-    { "path": "./ui" },
-    { "path": "./cli" }
-  ]
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  }
 }

ui/src/App.tsx

@@ -32,15 +32,14 @@ import { queryKeys } from "./lib/queryKeys";
 import { useCompany } from "./context/CompanyContext";
 import { useDialog } from "./context/DialogContext";
 
-function BootstrapPendingPage({ hasActiveInvite = false }: { hasActiveInvite?: boolean }) {
+function BootstrapPendingPage() {
   return (
     <div className="mx-auto max-w-xl py-10">
       <div className="rounded-lg border border-border bg-card p-6">
         <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. Run this command in your Paperclip environment to generate the first admin invite URL:"}
+          No instance admin exists yet. Run this command in your Paperclip 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`}
@@ -56,15 +55,6 @@ function CloudAccessGate() {
     queryKey: queryKeys.health,
     queryFn: () => healthApi.get(),
     retry: false,
-    refetchInterval: (query) => {
-      const data = query.state.data as
-        | { deploymentMode?: "local_trusted" | "authenticated"; bootstrapStatus?: "ready" | "bootstrap_pending" }
-        | undefined;
-      return data?.deploymentMode === "authenticated" && data.bootstrapStatus === "bootstrap_pending"
-        ? 2000
-        : false;
-    },
-    refetchIntervalInBackground: true,
   });
 
   const isAuthenticatedMode = healthQuery.data?.deploymentMode === "authenticated";
@@ -88,7 +78,7 @@ function CloudAccessGate() {
   }
 
   if (isAuthenticatedMode && healthQuery.data?.bootstrapStatus === "bootstrap_pending") {
-    return <BootstrapPendingPage hasActiveInvite={healthQuery.data.bootstrapInviteActive} />;
+    return <BootstrapPendingPage />;
   }
 
   if (isAuthenticatedMode && !sessionQuery.data) {

ui/src/api/health.ts

@@ -4,7 +4,6 @@ export type HealthStatus = {
   deploymentExposure?: "private" | "public";
   authReady?: boolean;
   bootstrapStatus?: "ready" | "bootstrap_pending";
-  bootstrapInviteActive?: boolean;
   features?: {
     companyDeletionEnabled?: boolean;
   };

ui/src/components/AgentConfigForm.tsx

@@ -441,7 +441,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {
                     "promptTemplate",
                     String(config.promptTemplate ?? ""),
                   )}
-                  onChange={(v) => mark("adapterConfig", "promptTemplate", v ?? "")}
+                  onChange={(v) => mark("adapterConfig", "promptTemplate", v || undefined)}
                   placeholder="You are agent {{ agent.name }}. Your role is {{ agent.role }}..."
                   contentClassName="min-h-[88px] text-sm font-mono"
                   imageUploadHandler={async (file) => {

ui/src/components/AgentProperties.tsx

@@ -1,6 +1,6 @@
 import { useQuery } from "@tanstack/react-query";
 import { Link } from "@/lib/router";
-import { AGENT_ROLE_LABELS, type Agent, type AgentRuntimeState } from "@paperclipai/shared";
+import type { Agent, AgentRuntimeState } from "@paperclipai/shared";
 import { agentsApi } from "../api/agents";
 import { useCompany } from "../context/CompanyContext";
 import { queryKeys } from "../lib/queryKeys";
@@ -24,8 +24,6 @@ const adapterLabels: Record<string, string> = {
   http: "HTTP",
 };
 
-const roleLabels = AGENT_ROLE_LABELS as Record<string, string>;
-
 function PropertyRow({ label, children }: { label: string; children: React.ReactNode }) {
   return (
     <div className="flex items-center gap-3 py-1.5">
@@ -53,7 +51,7 @@ export function AgentProperties({ agent, runtimeState }: AgentPropertiesProps) {
           <StatusBadge status={agent.status} />
         </PropertyRow>
         <PropertyRow label="Role">
-          <span className="text-sm">{roleLabels[agent.role] ?? agent.role}</span>
+          <span className="text-sm">{agent.role}</span>
         </PropertyRow>
         {agent.title && (
           <PropertyRow label="Title">

ui/src/components/IssuesList.tsx

@@ -7,7 +7,6 @@ import { issuesApi } from "../api/issues";
 import { queryKeys } from "../lib/queryKeys";
 import { groupBy } from "../lib/groupBy";
 import { formatDate, cn } from "../lib/utils";
-import { timeAgo } from "../lib/timeAgo";
 import { StatusIcon } from "./StatusIcon";
 import { PriorityIcon } from "./PriorityIcon";
 import { EmptyState } from "./EmptyState";
@@ -18,7 +17,7 @@ import { Input } from "@/components/ui/input";
 import { Popover, PopoverTrigger, PopoverContent } from "@/components/ui/popover";
 import { Checkbox } from "@/components/ui/checkbox";
 import { Collapsible, CollapsibleTrigger, CollapsibleContent } from "@/components/ui/collapsible";
-import { CircleDot, Plus, Filter, ArrowUpDown, Layers, Check, X, ChevronRight, List, Columns3, User, Search } from "lucide-react";
+import { CircleDot, Plus, Filter, ArrowUpDown, Layers, Check, X, ChevronRight, List, Columns3, User, Search, ArrowDown } from "lucide-react";
 import { KanbanBoard } from "./KanbanBoard";
 import type { Issue } from "@paperclipai/shared";
 
@@ -234,6 +233,24 @@ export function IssuesList({
 
   const activeFilterCount = countActiveFilters(viewState);
 
+  const [showScrollBottom, setShowScrollBottom] = useState(false);
+  useEffect(() => {
+    const el = document.getElementById("main-content");
+    if (!el) return;
+    const check = () => {
+      const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+      setShowScrollBottom(distanceFromBottom > 300);
+    };
+    check();
+    el.addEventListener("scroll", check, { passive: true });
+    return () => el.removeEventListener("scroll", check);
+  }, [filtered.length]);
+
+  const scrollToBottom = useCallback(() => {
+    const el = document.getElementById("main-content");
+    if (el) el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
+  }, []);
+
   const groupedContent = useMemo(() => {
     if (viewState.groupBy === "none") {
       return [{ key: "__all", label: null as string | null, items: filtered }];
@@ -591,163 +608,149 @@ export function IssuesList({
                 <Link
                   key={issue.id}
                   to={`/issues/${issue.identifier ?? issue.id}`}
-                  className="flex items-start gap-2 py-2.5 pl-2 pr-3 text-sm border-b border-border last:border-b-0 cursor-pointer hover:bg-accent/50 transition-colors no-underline text-inherit sm:items-center sm:py-2 sm:pl-1"
+                  className="flex items-center gap-2 py-2 pl-1 pr-3 text-sm border-b border-border last:border-b-0 cursor-pointer hover:bg-accent/50 transition-colors no-underline text-inherit"
                 >
-                  {/* Status icon - left column on mobile, inline on desktop */}
-                  <span className="shrink-0 pt-px sm:hidden" onClick={(e) => { e.preventDefault(); e.stopPropagation(); }}>
+                  {/* Spacer matching caret width so status icon aligns with group title (hidden on mobile) */}
+                  <div className="w-3.5 shrink-0 hidden sm:block" />
+                  <div className="shrink-0" onClick={(e) => { e.preventDefault(); e.stopPropagation(); }}>
                     <StatusIcon
                       status={issue.status}
                       onChange={(s) => onUpdateIssue(issue.id, { status: s })}
                     />
+                  </div>
+                  <span className="text-sm text-muted-foreground font-mono shrink-0">
+                    {issue.identifier ?? issue.id.slice(0, 8)}
                   </span>
-
-                  {/* Right column on mobile: title + metadata stacked */}
-                  <span className="flex min-w-0 flex-1 flex-col gap-1 sm:contents">
-                    {/* Title line */}
-                    <span className="line-clamp-2 text-sm sm:order-2 sm:flex-1 sm:min-w-0 sm:line-clamp-none sm:truncate">
-                      {issue.title}
-                    </span>
-
-                    {/* Metadata line */}
-                    <span className="flex items-center gap-2 sm:order-1 sm:shrink-0">
-                      {/* Spacer matching caret width so status icon aligns with group title (hidden on mobile) */}
-                      <span className="w-3.5 shrink-0 hidden sm:block" />
-                      <span className="hidden sm:inline-flex"><PriorityIcon priority={issue.priority} /></span>
-                      <span className="hidden shrink-0 sm:inline-flex" onClick={(e) => { e.preventDefault(); e.stopPropagation(); }}>
-                        <StatusIcon
-                          status={issue.status}
-                          onChange={(s) => onUpdateIssue(issue.id, { status: s })}
-                        />
-                      </span>
-                      <span className="text-xs text-muted-foreground font-mono shrink-0">
-                        {issue.identifier ?? issue.id.slice(0, 8)}
-                      </span>
-                      {liveIssueIds?.has(issue.id) && (
-                        <span className="inline-flex items-center gap-1 sm:gap-1.5 px-1.5 sm:px-2 py-0.5 rounded-full bg-blue-500/10">
-                          <span className="relative flex h-2 w-2">
-                            <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-blue-400 opacity-75" />
-                            <span className="relative inline-flex rounded-full h-2 w-2 bg-blue-500" />
-                          </span>
-                          <span className="text-[11px] font-medium text-blue-600 dark:text-blue-400 hidden sm:inline">Live</span>
-                        </span>
-                      )}
-                      <span className="text-xs text-muted-foreground sm:hidden">&middot;</span>
-                      <span className="text-xs text-muted-foreground sm:hidden">
-                        {timeAgo(issue.updatedAt)}
-                      </span>
-                    </span>
-                  </span>
-
-                  {/* Desktop-only trailing content */}
-                  <span className="hidden sm:flex sm:order-3 items-center gap-2 sm:gap-3 shrink-0 ml-auto">
-                    {(issue.labels ?? []).length > 0 && (
-                      <span className="hidden md:flex items-center gap-1 max-w-[240px] overflow-hidden">
-                        {(issue.labels ?? []).slice(0, 3).map((label) => (
-                          <span
-                            key={label.id}
-                            className="inline-flex items-center rounded-full border px-1.5 py-0.5 text-[10px] font-medium"
-                            style={{
-                              borderColor: label.color,
-                              color: label.color,
-                              backgroundColor: `${label.color}1f`,
-                            }}
-                          >
-                            {label.name}
-                          </span>
-                        ))}
-                        {(issue.labels ?? []).length > 3 && (
-                          <span className="text-[10px] text-muted-foreground">+{(issue.labels ?? []).length - 3}</span>
-                        )}
-                      </span>
-                    )}
-                    <Popover
-                      open={assigneePickerIssueId === issue.id}
-                      onOpenChange={(open) => {
-                        setAssigneePickerIssueId(open ? issue.id : null);
-                        if (!open) setAssigneeSearch("");
-                      }}
-                    >
-                      <PopoverTrigger asChild>
-                        <button
-                          className="flex w-[180px] shrink-0 items-center rounded-md px-2 py-1 hover:bg-accent/50 transition-colors"
-                          onClick={(e) => {
-                            e.preventDefault();
-                            e.stopPropagation();
+                  <span className="truncate flex-1 min-w-0">{issue.title}</span>
+                  {(issue.labels ?? []).length > 0 && (
+                    <div className="hidden md:flex items-center gap-1 max-w-[240px] overflow-hidden">
+                      {(issue.labels ?? []).slice(0, 3).map((label) => (
+                        <span
+                          key={label.id}
+                          className="inline-flex items-center rounded-full border px-1.5 py-0.5 text-[10px] font-medium"
+                          style={{
+                            borderColor: label.color,
+                            color: label.color,
+                            backgroundColor: `${label.color}1f`,
                           }}
                         >
-                          {issue.assigneeAgentId && agentName(issue.assigneeAgentId) ? (
-                            <Identity name={agentName(issue.assigneeAgentId)!} size="sm" />
-                          ) : (
-                            <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
-                              <span className="inline-flex h-5 w-5 items-center justify-center rounded-full border border-dashed border-muted-foreground/35 bg-muted/30">
-                                <User className="h-3 w-3" />
-                              </span>
-                              Assignee
-                            </span>
-                          )}
-                        </button>
-                      </PopoverTrigger>
-                      <PopoverContent
-                        className="w-56 p-1"
-                        align="end"
-                        onClick={(e) => e.stopPropagation()}
-                        onPointerDownOutside={() => setAssigneeSearch("")}
+                          {label.name}
+                        </span>
+                      ))}
+                      {(issue.labels ?? []).length > 3 && (
+                        <span className="text-[10px] text-muted-foreground">+{(issue.labels ?? []).length - 3}</span>
+                      )}
+                    </div>
+                  )}
+                  <div className="flex items-center gap-2 sm:gap-3 shrink-0 ml-auto">
+                    {liveIssueIds?.has(issue.id) && (
+                      <span className="inline-flex items-center gap-1 sm:gap-1.5 px-1.5 sm:px-2 py-0.5 rounded-full bg-blue-500/10">
+                        <span className="relative flex h-2 w-2">
+                          <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-blue-400 opacity-75" />
+                          <span className="relative inline-flex rounded-full h-2 w-2 bg-blue-500" />
+                        </span>
+                        <span className="text-[11px] font-medium text-blue-600 dark:text-blue-400 hidden sm:inline">Live</span>
+                      </span>
+                    )}
+                    <div className="hidden sm:block">
+                      <Popover
+                        open={assigneePickerIssueId === issue.id}
+                        onOpenChange={(open) => {
+                          setAssigneePickerIssueId(open ? issue.id : null);
+                          if (!open) setAssigneeSearch("");
+                        }}
                       >
-                        <input
-                          className="w-full px-2 py-1.5 text-xs bg-transparent outline-none border-b border-border mb-1 placeholder:text-muted-foreground/50"
-                          placeholder="Search agents..."
-                          value={assigneeSearch}
-                          onChange={(e) => setAssigneeSearch(e.target.value)}
-                          autoFocus
-                        />
-                        <div className="max-h-48 overflow-y-auto overscroll-contain">
+                        <PopoverTrigger asChild>
                           <button
-                            className={cn(
-                              "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50",
-                              !issue.assigneeAgentId && "bg-accent"
-                            )}
+                            className="flex w-[180px] shrink-0 items-center rounded-md px-2 py-1 hover:bg-accent/50 transition-colors"
                             onClick={(e) => {
                               e.preventDefault();
                               e.stopPropagation();
-                              assignIssue(issue.id, null);
                             }}
                           >
-                            No assignee
+                            {issue.assigneeAgentId && agentName(issue.assigneeAgentId) ? (
+                              <Identity name={agentName(issue.assigneeAgentId)!} size="sm" />
+                            ) : (
+                              <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
+                                <span className="inline-flex h-5 w-5 items-center justify-center rounded-full border border-dashed border-muted-foreground/35 bg-muted/30">
+                                  <User className="h-3 w-3" />
+                                </span>
+                                Assignee
+                              </span>
+                            )}
                           </button>
-                          {(agents ?? [])
-                            .filter((agent) => {
-                              if (!assigneeSearch.trim()) return true;
-                              return agent.name.toLowerCase().includes(assigneeSearch.toLowerCase());
-                            })
-                            .map((agent) => (
-                              <button
-                                key={agent.id}
-                                className={cn(
-                                  "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50 text-left",
-                                  issue.assigneeAgentId === agent.id && "bg-accent"
-                                )}
-                                onClick={(e) => {
-                                  e.preventDefault();
-                                  e.stopPropagation();
-                                  assignIssue(issue.id, agent.id);
-                                }}
-                              >
-                                <Identity name={agent.name} size="sm" className="min-w-0" />
-                              </button>
-                            ))}
-                        </div>
-                      </PopoverContent>
-                    </Popover>
-                    <span className="text-xs text-muted-foreground">
+                        </PopoverTrigger>
+                        <PopoverContent
+                          className="w-56 p-1"
+                          align="end"
+                          onClick={(e) => e.stopPropagation()}
+                          onPointerDownOutside={() => setAssigneeSearch("")}
+                        >
+                          <input
+                            className="w-full px-2 py-1.5 text-xs bg-transparent outline-none border-b border-border mb-1 placeholder:text-muted-foreground/50"
+                            placeholder="Search agents..."
+                            value={assigneeSearch}
+                            onChange={(e) => setAssigneeSearch(e.target.value)}
+                            autoFocus
+                          />
+                          <div className="max-h-48 overflow-y-auto overscroll-contain">
+                            <button
+                              className={cn(
+                                "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50",
+                                !issue.assigneeAgentId && "bg-accent"
+                              )}
+                              onClick={(e) => {
+                                e.preventDefault();
+                                e.stopPropagation();
+                                assignIssue(issue.id, null);
+                              }}
+                            >
+                              No assignee
+                            </button>
+                            {(agents ?? [])
+                              .filter((agent) => {
+                                if (!assigneeSearch.trim()) return true;
+                                return agent.name.toLowerCase().includes(assigneeSearch.toLowerCase());
+                              })
+                              .map((agent) => (
+                                <button
+                                  key={agent.id}
+                                  className={cn(
+                                    "flex items-center gap-2 w-full px-2 py-1.5 text-xs rounded hover:bg-accent/50 text-left",
+                                    issue.assigneeAgentId === agent.id && "bg-accent"
+                                  )}
+                                  onClick={(e) => {
+                                    e.preventDefault();
+                                    e.stopPropagation();
+                                    assignIssue(issue.id, agent.id);
+                                  }}
+                                >
+                                  <Identity name={agent.name} size="sm" className="min-w-0" />
+                                </button>
+                              ))}
+                          </div>
+                        </PopoverContent>
+                      </Popover>
+                    </div>
+                    <span className="text-xs text-muted-foreground hidden sm:inline">
                       {formatDate(issue.createdAt)}
                     </span>
-                  </span>
+                  </div>
                 </Link>
               ))}
             </CollapsibleContent>
           </Collapsible>
         ))
       )}
+      {showScrollBottom && (
+        <button
+          onClick={scrollToBottom}
+          className="fixed bottom-6 right-6 z-40 flex h-9 w-9 items-center justify-center rounded-full border border-border bg-background shadow-md hover:bg-accent transition-colors"
+          aria-label="Scroll to bottom"
+        >
+          <ArrowDown className="h-4 w-4" />
+        </button>
+      )}
     </div>
   );
 }

ui/src/components/NewIssueDialog.tsx

@@ -831,7 +831,7 @@ export function NewIssueDialog() {
             placeholder="Add description..."
             bordered={false}
             mentions={mentionOptions}
-            contentClassName={cn("text-sm text-muted-foreground pb-12", expanded ? "min-h-[220px]" : "min-h-[120px]")}
+            contentClassName={cn("text-sm text-muted-foreground", expanded ? "min-h-[220px]" : "min-h-[120px]")}
             imageUploadHandler={async (file) => {
               const asset = await uploadDescriptionImage.mutateAsync(file);
               return asset.contentPath;

ui/src/components/OnboardingWizard.tsx

@@ -500,6 +500,10 @@ export function OnboardingWizard() {
     setLoading(false);
     reset();
     closeOnboarding();
+    if (createdCompanyPrefix && createdIssueRef) {
+      navigate(`/${createdCompanyPrefix}/issues/${createdIssueRef}`);
+      return;
+    }
     if (createdCompanyPrefix) {
       navigate(`/${createdCompanyPrefix}/dashboard`);
       return;

ui/src/components/ScrollToBottom.tsx

@@ -1,40 +0,0 @@
-import { useCallback, useEffect, useState } from "react";
-import { ArrowDown } from "lucide-react";
-
-/**
- * Floating scroll-to-bottom button that appears when the user is far from the
- * bottom of the `#main-content` scroll container. Hides when within 300px of
- * the bottom. Positioned to avoid the mobile bottom nav.
- */
-export function ScrollToBottom() {
-  const [visible, setVisible] = useState(false);
-
-  useEffect(() => {
-    const el = document.getElementById("main-content");
-    if (!el) return;
-    const check = () => {
-      const distance = el.scrollHeight - el.scrollTop - el.clientHeight;
-      setVisible(distance > 300);
-    };
-    check();
-    el.addEventListener("scroll", check, { passive: true });
-    return () => el.removeEventListener("scroll", check);
-  }, []);
-
-  const scroll = useCallback(() => {
-    const el = document.getElementById("main-content");
-    if (el) el.scrollTo({ top: el.scrollHeight, behavior: "smooth" });
-  }, []);
-
-  if (!visible) return null;
-
-  return (
-    <button
-      onClick={scroll}
-      className="fixed bottom-[calc(1.5rem+5rem+env(safe-area-inset-bottom))] right-6 z-40 flex h-9 w-9 items-center justify-center rounded-full border border-border bg-background shadow-md hover:bg-accent transition-colors md:bottom-6"
-      aria-label="Scroll to bottom"
-    >
-      <ArrowDown className="h-4 w-4" />
-    </button>
-  );
-}

ui/src/components/agent-config-primitives.tsx

@@ -15,7 +15,6 @@ import {
 import { Button } from "@/components/ui/button";
 import { HelpCircle, ChevronDown, ChevronRight } from "lucide-react";
 import { cn } from "../lib/utils";
-import { AGENT_ROLE_LABELS } from "@paperclipai/shared";
 
 /* ---- Help text for (?) tooltips ---- */
 export const help: Record<string, string> = {
@@ -60,7 +59,11 @@ export const adapterLabels: Record<string, string> = {
   http: "HTTP",
 };
 
-export const roleLabels = AGENT_ROLE_LABELS as Record<string, string>;
+export const roleLabels: Record<string, string> = {
+  ceo: "CEO", cto: "CTO", cmo: "CMO", cfo: "CFO",
+  engineer: "Engineer", designer: "Designer", pm: "PM",
+  qa: "QA", devops: "DevOps", researcher: "Researcher", general: "General",
+};
 
 /* ---- Primitive components ---- */
 

ui/src/pages/AgentDetail.tsx

@@ -24,7 +24,6 @@ import { CopyText } from "../components/CopyText";
 import { EntityRow } from "../components/EntityRow";
 import { Identity } from "../components/Identity";
 import { PageSkeleton } from "../components/PageSkeleton";
-import { ScrollToBottom } from "../components/ScrollToBottom";
 import { formatCents, formatDate, relativeTime, formatTokens } from "../lib/utils";
 import { cn } from "../lib/utils";
 import { Button } from "@/components/ui/button";
@@ -1748,7 +1747,6 @@ function RunDetail({ run, agentRouteId, adapterType }: { run: HeartbeatRun; agen
 
       {/* Log viewer */}
       <LogViewer run={run} adapterType={adapterType} />
-      <ScrollToBottom />
     </div>
   );
 }

ui/src/pages/Agents.tsx

@@ -18,7 +18,7 @@ import { PageTabBar } from "../components/PageTabBar";
 import { Tabs } from "@/components/ui/tabs";
 import { Button } from "@/components/ui/button";
 import { Bot, Plus, List, GitBranch, SlidersHorizontal } from "lucide-react";
-import { AGENT_ROLE_LABELS, type Agent } from "@paperclipai/shared";
+import type { Agent } from "@paperclipai/shared";
 
 const adapterLabels: Record<string, string> = {
   claude_local: "Claude",
@@ -30,7 +30,11 @@ const adapterLabels: Record<string, string> = {
   http: "HTTP",
 };
 
-const roleLabels = AGENT_ROLE_LABELS as Record<string, string>;
+const roleLabels: Record<string, string> = {
+  ceo: "CEO", cto: "CTO", cmo: "CMO", cfo: "CFO",
+  engineer: "Engineer", designer: "Designer", pm: "PM",
+  qa: "QA", devops: "DevOps", researcher: "Researcher", general: "General",
+};
 
 type FilterTab = "all" | "active" | "paused" | "error";
 
@@ -226,7 +230,7 @@ export function Agents() {
               <EntityRow
                 key={agent.id}
                 title={agent.name}
-                subtitle={`${roleLabels[agent.role] ?? agent.role}${agent.title ? ` - ${agent.title}` : ""}`}
+                subtitle={`${agent.role}${agent.title ? ` - ${agent.title}` : ""}`}
                 to={agentUrl(agent)}
                 leading={
                   <span className="relative flex h-2.5 w-2.5">

ui/src/pages/Dashboard.tsx

@@ -313,36 +313,26 @@ export function Dashboard() {
                     <Link
                       key={issue.id}
                       to={`/issues/${issue.identifier ?? issue.id}`}
-                      className="px-4 py-3 text-sm cursor-pointer hover:bg-accent/50 transition-colors no-underline text-inherit block"
+                      className="px-4 py-2 text-sm cursor-pointer hover:bg-accent/50 transition-colors no-underline text-inherit block"
                     >
-                      <div className="flex items-start gap-2 sm:items-center sm:gap-3">
-                        {/* Status icon - left column on mobile */}
-                        <span className="shrink-0 sm:hidden">
-                          <StatusIcon status={issue.status} />
-                        </span>
-
-                        {/* Right column on mobile: title + metadata stacked */}
-                        <span className="flex min-w-0 flex-1 flex-col gap-1 sm:contents">
-                          <span className="line-clamp-2 text-sm sm:order-2 sm:flex-1 sm:min-w-0 sm:line-clamp-none sm:truncate">
-                            {issue.title}
-                          </span>
-                          <span className="flex items-center gap-2 sm:order-1 sm:shrink-0">
-                            <span className="hidden sm:inline-flex"><PriorityIcon priority={issue.priority} /></span>
-                            <span className="hidden sm:inline-flex"><StatusIcon status={issue.status} /></span>
-                            <span className="text-xs font-mono text-muted-foreground">
-                              {issue.identifier ?? issue.id.slice(0, 8)}
-                            </span>
+                      <div className="flex gap-3">
+                        <div className="flex items-start gap-2 min-w-0 flex-1">
+                          <div className="flex items-center gap-2 shrink-0 mt-0.5">
+                            <PriorityIcon priority={issue.priority} />
+                            <StatusIcon status={issue.status} />
+                          </div>
+                          <p className="min-w-0 flex-1 truncate">
+                            <span>{issue.title}</span>
                             {issue.assigneeAgentId && (() => {
                               const name = agentName(issue.assigneeAgentId);
                               return name
-                                ? <span className="hidden sm:inline-flex"><Identity name={name} size="sm" /></span>
+                                ? <span className="hidden sm:inline"><Identity name={name} size="sm" className="ml-2 inline-flex" /></span>
                                 : null;
                             })()}
-                            <span className="text-xs text-muted-foreground sm:hidden">&middot;</span>
-                            <span className="text-xs text-muted-foreground shrink-0 sm:order-last">
-                              {timeAgo(issue.updatedAt)}
-                            </span>
-                          </span>
+                          </p>
+                        </div>
+                        <span className="text-xs text-muted-foreground shrink-0 pt-0.5">
+                          {timeAgo(issue.updatedAt)}
                         </span>
                       </div>
                     </Link>

ui/src/pages/Inbox.tsx

@@ -841,44 +841,38 @@ export function Inbox() {
               {staleIssues.map((issue) => (
                 <div
                   key={issue.id}
-                  className="group/stale relative flex items-start gap-2 overflow-hidden px-3 py-3 transition-colors hover:bg-accent/50 sm:items-center sm:gap-3 sm:px-4"
+                  className="group/stale relative flex items-center gap-3 px-4 py-3 transition-colors hover:bg-accent/50"
                 >
-                  {/* Status icon - left column on mobile; Clock icon on desktop */}
-                  <span className="shrink-0 sm:hidden">
-                    <StatusIcon status={issue.status} />
-                  </span>
-                  <Clock className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground hidden sm:block sm:mt-0" />
-
                   <Link
                     to={`/issues/${issue.identifier ?? issue.id}`}
-                    className="flex min-w-0 flex-1 cursor-pointer flex-col gap-1 no-underline text-inherit sm:flex-row sm:items-center sm:gap-3"
+                    className="flex flex-1 cursor-pointer items-center gap-3 no-underline text-inherit"
                   >
-                    <span className="line-clamp-2 text-sm sm:order-2 sm:flex-1 sm:min-w-0 sm:line-clamp-none sm:truncate">
-                      {issue.title}
+                    <Clock className="h-4 w-4 shrink-0 text-muted-foreground" />
+                    <PriorityIcon priority={issue.priority} />
+                    <StatusIcon status={issue.status} />
+                    <span className="text-xs font-mono text-muted-foreground">
+                      {issue.identifier ?? issue.id.slice(0, 8)}
                     </span>
-                    <span className="flex items-center gap-2 sm:order-1 sm:shrink-0">
-                      <span className="hidden sm:inline-flex"><PriorityIcon priority={issue.priority} /></span>
-                      <span className="hidden sm:inline-flex"><StatusIcon status={issue.status} /></span>
-                      <span className="shrink-0 text-xs font-mono text-muted-foreground">
-                        {issue.identifier ?? issue.id.slice(0, 8)}
-                      </span>
-                      {issue.assigneeAgentId &&
-                        (() => {
-                          const name = agentName(issue.assigneeAgentId);
-                          return name ? (
-                            <span className="hidden sm:inline-flex"><Identity name={name} size="sm" /></span>
-                          ) : null;
-                        })()}
-                      <span className="text-xs text-muted-foreground sm:hidden">&middot;</span>
-                      <span className="shrink-0 text-xs text-muted-foreground sm:order-last">
-                        updated {timeAgo(issue.updatedAt)}
-                      </span>
+                    <span className="flex-1 truncate text-sm">{issue.title}</span>
+                    {issue.assigneeAgentId &&
+                      (() => {
+                        const name = agentName(issue.assigneeAgentId);
+                        return name ? (
+                          <Identity name={name} size="sm" />
+                        ) : (
+                          <span className="font-mono text-xs text-muted-foreground">
+                            {issue.assigneeAgentId.slice(0, 8)}
+                          </span>
+                        );
+                      })()}
+                    <span className="shrink-0 text-xs text-muted-foreground">
+                      updated {timeAgo(issue.updatedAt)}
                     </span>
                   </Link>
                   <button
                     type="button"
                     onClick={() => dismiss(`stale:${issue.id}`)}
-                    className="mt-0.5 rounded-md p-1 text-muted-foreground opacity-0 transition-opacity hover:bg-accent hover:text-foreground group-hover/stale:opacity-100 sm:mt-0"
+                    className="rounded-md p-1 text-muted-foreground opacity-0 transition-opacity hover:bg-accent hover:text-foreground group-hover/stale:opacity-100"
                     aria-label="Dismiss"
                   >
                     <X className="h-3.5 w-3.5" />
@@ -902,94 +896,47 @@ export function Inbox() {
                 const isUnread = issue.isUnreadForMe && !fadingOutIssues.has(issue.id);
                 const isFading = fadingOutIssues.has(issue.id);
                 return (
-                  <Link
+                  <div
                     key={issue.id}
-                    to={`/issues/${issue.identifier ?? issue.id}`}
-                    className="flex min-w-0 cursor-pointer items-start gap-2 px-3 py-3 no-underline text-inherit transition-colors hover:bg-accent/50 sm:items-center sm:gap-3 sm:px-4"
+                    className="flex items-center gap-3 px-4 py-3 transition-colors hover:bg-accent/50"
                   >
-                    {/* Status icon - left column on mobile, inline on desktop */}
-                    <span className="shrink-0 sm:hidden">
-                      <StatusIcon status={issue.status} />
-                    </span>
-
-                    {/* Right column on mobile: title + metadata stacked */}
-                    <span className="flex min-w-0 flex-1 flex-col gap-1 sm:contents">
-                      <span className="line-clamp-2 text-sm sm:order-2 sm:flex-1 sm:min-w-0 sm:line-clamp-none sm:truncate">
-                        {issue.title}
-                      </span>
-                      <span className="flex items-center gap-2 sm:order-1 sm:shrink-0">
-                        {(isUnread || isFading) ? (
-                          <span
-                            role="button"
-                            tabIndex={0}
-                            onClick={(e) => {
-                              e.preventDefault();
-                              e.stopPropagation();
-                              markReadMutation.mutate(issue.id);
-                            }}
-                            onKeyDown={(e) => {
-                              if (e.key === "Enter" || e.key === " ") {
-                                e.preventDefault();
-                                e.stopPropagation();
-                                markReadMutation.mutate(issue.id);
-                              }
-                            }}
-                            className="hidden sm:inline-flex h-4 w-4 shrink-0 cursor-pointer items-center justify-center rounded-full transition-colors hover:bg-blue-500/20"
-                            aria-label="Mark as read"
-                          >
-                            <span
-                              className={`h-2 w-2 rounded-full bg-blue-600 dark:bg-blue-400 transition-opacity duration-300 ${
-                                isFading ? "opacity-0" : "opacity-100"
-                              }`}
-                            />
-                          </span>
-                        ) : (
-                          <span className="hidden sm:inline-flex h-4 w-4 shrink-0" />
-                        )}
-                        <span className="hidden sm:inline-flex"><PriorityIcon priority={issue.priority} /></span>
-                        <span className="hidden sm:inline-flex"><StatusIcon status={issue.status} /></span>
-                        <span className="text-xs font-mono text-muted-foreground">
-                          {issue.identifier ?? issue.id.slice(0, 8)}
-                        </span>
-                        <span className="text-xs text-muted-foreground sm:hidden">
-                          &middot;
-                        </span>
-                        <span className="text-xs text-muted-foreground sm:order-last">
-                          {issue.lastExternalCommentAt
-                            ? `commented ${timeAgo(issue.lastExternalCommentAt)}`
-                            : `updated ${timeAgo(issue.updatedAt)}`}
-                        </span>
-                      </span>
-                    </span>
-
-                    {/* Unread dot - right side, vertically centered (mobile only; desktop keeps inline) */}
-                    {(isUnread || isFading) && (
-                      <span
-                        role="button"
-                        tabIndex={0}
-                        onClick={(e) => {
-                          e.preventDefault();
-                          e.stopPropagation();
-                          markReadMutation.mutate(issue.id);
-                        }}
-                        onKeyDown={(e) => {
-                          if (e.key === "Enter" || e.key === " ") {
+                    <span className="flex w-4 shrink-0 justify-center">
+                      {(isUnread || isFading) && (
+                        <button
+                          type="button"
+                          onClick={(e) => {
                             e.preventDefault();
                             e.stopPropagation();
                             markReadMutation.mutate(issue.id);
-                          }
-                        }}
-                        className="shrink-0 self-center cursor-pointer sm:hidden"
-                        aria-label="Mark as read"
-                      >
-                        <span
-                          className={`block h-2 w-2 rounded-full bg-blue-600 dark:bg-blue-400 transition-opacity duration-300 ${
-                            isFading ? "opacity-0" : "opacity-100"
-                          }`}
-                        />
+                          }}
+                          className="group/dot flex h-4 w-4 items-center justify-center rounded-full transition-colors hover:bg-blue-500/20"
+                          aria-label="Mark as read"
+                        >
+                          <span
+                            className={`h-2.5 w-2.5 rounded-full bg-blue-600 dark:bg-blue-400 transition-opacity duration-300 ${
+                              isFading ? "opacity-0" : "opacity-100"
+                            }`}
+                          />
+                        </button>
+                      )}
+                    </span>
+                    <Link
+                      to={`/issues/${issue.identifier ?? issue.id}`}
+                      className="flex flex-1 min-w-0 cursor-pointer items-center gap-3 no-underline text-inherit"
+                    >
+                      <PriorityIcon priority={issue.priority} />
+                      <StatusIcon status={issue.status} />
+                      <span className="text-xs font-mono text-muted-foreground">
+                        {issue.identifier ?? issue.id.slice(0, 8)}
                       </span>
-                    )}
-                  </Link>
+                      <span className="flex-1 truncate text-sm">{issue.title}</span>
+                      <span className="shrink-0 text-xs text-muted-foreground">
+                        {issue.lastExternalCommentAt
+                          ? `commented ${timeAgo(issue.lastExternalCommentAt)}`
+                          : `updated ${timeAgo(issue.updatedAt)}`}
+                      </span>
+                    </Link>
+                  </div>
                 );
               })}
             </div>

ui/src/pages/IssueDetail.tsx

@@ -18,7 +18,6 @@ import { CommentThread } from "../components/CommentThread";
 import { IssueProperties } from "../components/IssueProperties";
 import { LiveRunWidget } from "../components/LiveRunWidget";
 import type { MentionOption } from "../components/MarkdownEditor";
-import { ScrollToBottom } from "../components/ScrollToBottom";
 import { StatusIcon } from "../components/StatusIcon";
 import { PriorityIcon } from "../components/PriorityIcon";
 import { StatusBadge } from "../components/StatusBadge";
@@ -927,7 +926,6 @@ export function IssueDetail() {
           </ScrollArea>
         </SheetContent>
       </Sheet>
-      <ScrollToBottom />
     </div>
   );
 }

ui/src/pages/OrgChart.tsx

@@ -10,7 +10,7 @@ import { EmptyState } from "../components/EmptyState";
 import { PageSkeleton } from "../components/PageSkeleton";
 import { AgentIcon } from "../components/AgentIconPicker";
 import { Network } from "lucide-react";
-import { AGENT_ROLE_LABELS, type Agent } from "@paperclipai/shared";
+import type { Agent } from "@paperclipai/shared";
 
 // Layout constants
 const CARD_W = 200;
@@ -421,7 +421,11 @@ export function OrgChart() {
   );
 }
 
-const roleLabels = AGENT_ROLE_LABELS as Record<string, string>;
+const roleLabels: Record<string, string> = {
+  ceo: "CEO", cto: "CTO", cmo: "CMO", cfo: "CFO",
+  engineer: "Engineer", designer: "Designer", pm: "PM",
+  qa: "QA", devops: "DevOps", researcher: "Researcher", general: "General",
+};
 
 function roleLabel(role: string): string {
   return roleLabels[role] ?? role;