fix(ui): hide scrollbar track background when sidebar is not hovered

The scrollbar-auto-hide utility was only hiding the thumb but left the
track background visible, creating a visible "well" even when idle.
Now both track and thumb are transparent by default, appearing only on
container hover.

Fixes PAP-374

Co-Authored-By: Paperclip <noreply@paperclip.ing>

cli/CHANGELOG.md

@@ -1,5 +1,23 @@
 # paperclipai
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+  - @paperclipai/adapter-claude-local@0.3.1
+  - @paperclipai/adapter-codex-local@0.3.1
+  - @paperclipai/adapter-cursor-local@0.3.1
+  - @paperclipai/adapter-gemini-local@0.3.1
+  - @paperclipai/adapter-openclaw-gateway@0.3.1
+  - @paperclipai/adapter-opencode-local@0.3.1
+  - @paperclipai/adapter-pi-local@0.3.1
+  - @paperclipai/db@0.3.1
+  - @paperclipai/shared@0.3.1
+  - @paperclipai/server@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclipai",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Paperclip CLI — orchestrate AI agent teams to run a business",
   "type": "module",
   "bin": {

cli/src/commands/client/plugin.ts

@@ -0,0 +1,374 @@
+import path from "node:path";
+import { Command } from "commander";
+import pc from "picocolors";
+import {
+  addCommonClientOptions,
+  handleCommandError,
+  printOutput,
+  resolveCommandContext,
+  type BaseClientOptions,
+} from "./common.js";
+
+// ---------------------------------------------------------------------------
+// Types mirroring server-side shapes
+// ---------------------------------------------------------------------------
+
+interface PluginRecord {
+  id: string;
+  pluginKey: string;
+  packageName: string;
+  version: string;
+  status: string;
+  displayName?: string;
+  lastError?: string | null;
+  installedAt: string;
+  updatedAt: string;
+}
+
+
+// ---------------------------------------------------------------------------
+// Option types
+// ---------------------------------------------------------------------------
+
+interface PluginListOptions extends BaseClientOptions {
+  status?: string;
+}
+
+interface PluginInstallOptions extends BaseClientOptions {
+  local?: boolean;
+  version?: string;
+}
+
+interface PluginUninstallOptions extends BaseClientOptions {
+  force?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a local path argument to an absolute path so the server can find the
+ * plugin on disk regardless of where the user ran the CLI.
+ */
+function resolvePackageArg(packageArg: string, isLocal: boolean): string {
+  if (!isLocal) return packageArg;
+  // Already absolute
+  if (path.isAbsolute(packageArg)) return packageArg;
+  // Expand leading ~ to home directory
+  if (packageArg.startsWith("~")) {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    return path.resolve(home, packageArg.slice(1).replace(/^[\\/]/, ""));
+  }
+  return path.resolve(process.cwd(), packageArg);
+}
+
+function formatPlugin(p: PluginRecord): string {
+  const statusColor =
+    p.status === "ready"
+      ? pc.green(p.status)
+      : p.status === "error"
+        ? pc.red(p.status)
+        : p.status === "disabled"
+          ? pc.dim(p.status)
+          : pc.yellow(p.status);
+
+  const parts = [
+    `key=${pc.bold(p.pluginKey)}`,
+    `status=${statusColor}`,
+    `version=${p.version}`,
+    `id=${pc.dim(p.id)}`,
+  ];
+
+  if (p.lastError) {
+    parts.push(`error=${pc.red(p.lastError.slice(0, 80))}`);
+  }
+
+  return parts.join("  ");
+}
+
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+
+export function registerPluginCommands(program: Command): void {
+  const plugin = program.command("plugin").description("Plugin lifecycle management");
+
+  // -------------------------------------------------------------------------
+  // plugin list
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("list")
+      .description("List installed plugins")
+      .option("--status <status>", "Filter by status (ready, error, disabled, installed, upgrade_pending)")
+      .action(async (opts: PluginListOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const qs = opts.status ? `?status=${encodeURIComponent(opts.status)}` : "";
+          const plugins = await ctx.api.get<PluginRecord[]>(`/api/plugins${qs}`);
+
+          if (ctx.json) {
+            printOutput(plugins, { json: true });
+            return;
+          }
+
+          const rows = plugins ?? [];
+          if (rows.length === 0) {
+            console.log(pc.dim("No plugins installed."));
+            return;
+          }
+
+          for (const p of rows) {
+            console.log(formatPlugin(p));
+          }
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin install <package-or-path>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("install <package>")
+      .description(
+        "Install a plugin from a local path or npm package.\n" +
+          "  Examples:\n" +
+          "    paperclipai plugin install ./my-plugin              # local path\n" +
+          "    paperclipai plugin install @acme/plugin-linear      # npm package\n" +
+          "    paperclipai plugin install @acme/plugin-linear@1.2  # pinned version",
+      )
+      .option("-l, --local", "Treat <package> as a local filesystem path", false)
+      .option("--version <version>", "Specific npm version to install (npm packages only)")
+      .action(async (packageArg: string, opts: PluginInstallOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+
+          // Auto-detect local paths: starts with . or / or ~ or is an absolute path
+          const isLocal =
+            opts.local ||
+            packageArg.startsWith("./") ||
+            packageArg.startsWith("../") ||
+            packageArg.startsWith("/") ||
+            packageArg.startsWith("~");
+
+          const resolvedPackage = resolvePackageArg(packageArg, isLocal);
+
+          if (!ctx.json) {
+            console.log(
+              pc.dim(
+                isLocal
+                  ? `Installing plugin from local path: ${resolvedPackage}`
+                  : `Installing plugin: ${resolvedPackage}${opts.version ? `@${opts.version}` : ""}`,
+              ),
+            );
+          }
+
+          const installedPlugin = await ctx.api.post<PluginRecord>("/api/plugins/install", {
+            packageName: resolvedPackage,
+            version: opts.version,
+            isLocalPath: isLocal,
+          });
+
+          if (ctx.json) {
+            printOutput(installedPlugin, { json: true });
+            return;
+          }
+
+          if (!installedPlugin) {
+            console.log(pc.dim("Install returned no plugin record."));
+            return;
+          }
+
+          console.log(
+            pc.green(
+              `✓ Installed ${pc.bold(installedPlugin.pluginKey)} v${installedPlugin.version} (${installedPlugin.status})`,
+            ),
+          );
+
+          if (installedPlugin.lastError) {
+            console.log(pc.red(`  Warning: ${installedPlugin.lastError}`));
+          }
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin uninstall <plugin-key-or-id>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("uninstall <pluginKey>")
+      .description(
+        "Uninstall a plugin by its plugin key or database ID.\n" +
+          "  Use --force to hard-purge all state and config.",
+      )
+      .option("--force", "Purge all plugin state and config (hard delete)", false)
+      .action(async (pluginKey: string, opts: PluginUninstallOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const purge = opts.force === true;
+          const qs = purge ? "?purge=true" : "";
+
+          if (!ctx.json) {
+            console.log(
+              pc.dim(
+                purge
+                  ? `Uninstalling and purging plugin: ${pluginKey}`
+                  : `Uninstalling plugin: ${pluginKey}`,
+              ),
+            );
+          }
+
+          const result = await ctx.api.delete<PluginRecord | null>(
+            `/api/plugins/${encodeURIComponent(pluginKey)}${qs}`,
+          );
+
+          if (ctx.json) {
+            printOutput(result, { json: true });
+            return;
+          }
+
+          console.log(pc.green(`✓ Uninstalled ${pc.bold(pluginKey)}${purge ? " (purged)" : ""}`));
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin enable <plugin-key-or-id>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("enable <pluginKey>")
+      .description("Enable a disabled or errored plugin")
+      .action(async (pluginKey: string, opts: BaseClientOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const result = await ctx.api.post<PluginRecord>(
+            `/api/plugins/${encodeURIComponent(pluginKey)}/enable`,
+          );
+
+          if (ctx.json) {
+            printOutput(result, { json: true });
+            return;
+          }
+
+          console.log(pc.green(`✓ Enabled ${pc.bold(pluginKey)} — status: ${result?.status ?? "unknown"}`));
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin disable <plugin-key-or-id>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("disable <pluginKey>")
+      .description("Disable a running plugin without uninstalling it")
+      .action(async (pluginKey: string, opts: BaseClientOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const result = await ctx.api.post<PluginRecord>(
+            `/api/plugins/${encodeURIComponent(pluginKey)}/disable`,
+          );
+
+          if (ctx.json) {
+            printOutput(result, { json: true });
+            return;
+          }
+
+          console.log(pc.dim(`Disabled ${pc.bold(pluginKey)} — status: ${result?.status ?? "unknown"}`));
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin inspect <plugin-key-or-id>
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("inspect <pluginKey>")
+      .description("Show full details for an installed plugin")
+      .action(async (pluginKey: string, opts: BaseClientOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const result = await ctx.api.get<PluginRecord>(
+            `/api/plugins/${encodeURIComponent(pluginKey)}`,
+          );
+
+          if (ctx.json) {
+            printOutput(result, { json: true });
+            return;
+          }
+
+          if (!result) {
+            console.log(pc.red(`Plugin not found: ${pluginKey}`));
+            process.exit(1);
+          }
+
+          console.log(formatPlugin(result));
+          if (result.lastError) {
+            console.log(`\n${pc.red("Last error:")}\n${result.lastError}`);
+          }
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  // -------------------------------------------------------------------------
+  // plugin examples
+  // -------------------------------------------------------------------------
+  addCommonClientOptions(
+    plugin
+      .command("examples")
+      .description("List bundled example plugins available for local install")
+      .action(async (opts: BaseClientOptions) => {
+        try {
+          const ctx = resolveCommandContext(opts);
+          const examples = await ctx.api.get<
+            Array<{
+              packageName: string;
+              pluginKey: string;
+              displayName: string;
+              description: string;
+              localPath: string;
+              tag: string;
+            }>
+          >("/api/plugins/examples");
+
+          if (ctx.json) {
+            printOutput(examples, { json: true });
+            return;
+          }
+
+          const rows = examples ?? [];
+          if (rows.length === 0) {
+            console.log(pc.dim("No bundled examples available."));
+            return;
+          }
+
+          for (const ex of rows) {
+            console.log(
+              `${pc.bold(ex.displayName)}  ${pc.dim(ex.pluginKey)}\n` +
+                `  ${ex.description}\n` +
+                `  ${pc.cyan(`paperclipai plugin install ${ex.localPath}`)}`,
+            );
+          }
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+}

cli/src/index.ts

@@ -18,6 +18,7 @@ import { registerDashboardCommands } from "./commands/client/dashboard.js";
 import { applyDataDirOverride, type DataDirOptionLike } from "./config/data-dir.js";
 import { loadPaperclipEnvFile } from "./config/env.js";
 import { registerWorktreeCommands } from "./commands/worktree.js";
+import { registerPluginCommands } from "./commands/client/plugin.js";
 
 const program = new Command();
 const DATA_DIR_OPTION_HELP =
@@ -136,6 +137,7 @@ registerApprovalCommands(program);
 registerActivityCommands(program);
 registerDashboardCommands(program);
 registerWorktreeCommands(program);
+registerPluginCommands(program);
 
 const auth = program.command("auth").description("Authentication and bootstrap utilities");
 

doc/plugins/PLUGIN_AUTHORING_GUIDE.md

@@ -108,6 +108,7 @@ Mount surfaces currently wired in the host include:
 - `detailTab`
 - `taskDetailView`
 - `projectSidebarItem`
+- `globalToolbarButton`
 - `toolbarButton`
 - `contextMenuItem`
 - `commentAnnotation`

packages/adapter-utils/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @paperclipai/adapter-utils
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

packages/adapter-utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-utils",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/claude-local/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @paperclipai/adapter-claude-local
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

packages/adapters/claude-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-claude-local",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

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

@@ -122,6 +122,7 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   const workspaceRepoRef = asString(workspaceContext.repoRef, "") || null;
   const workspaceBranch = asString(workspaceContext.branchName, "") || null;
   const workspaceWorktreePath = asString(workspaceContext.worktreePath, "") || null;
+  const agentHome = asString(workspaceContext.agentHome, "") || null;
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -216,6 +217,9 @@ async function buildClaudeRuntimeConfig(input: ClaudeExecutionInput): Promise<Cl
   if (workspaceWorktreePath) {
     env.PAPERCLIP_WORKSPACE_WORKTREE_PATH = workspaceWorktreePath;
   }
+  if (agentHome) {
+    env.AGENT_HOME = agentHome;
+  }
   if (workspaceHints.length > 0) {
     env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
   }

packages/adapters/codex-local/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @paperclipai/adapter-codex-local
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

packages/adapters/codex-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-codex-local",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

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

@@ -188,6 +188,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
   const workspaceBranch = asString(workspaceContext.branchName, "");
   const workspaceWorktreePath = asString(workspaceContext.worktreePath, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -293,6 +294,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceWorktreePath) {
     env.PAPERCLIP_WORKSPACE_WORKTREE_PATH = workspaceWorktreePath;
   }
+  if (agentHome) {
+    env.AGENT_HOME = agentHome;
+  }
   if (workspaceHints.length > 0) {
     env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
   }

packages/adapters/cursor-local/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @paperclipai/adapter-cursor-local
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

packages/adapters/cursor-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-cursor-local",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/cursor-local/src/server/execute.ts

@@ -157,6 +157,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceId = asString(workspaceContext.workspaceId, "");
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -230,6 +231,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceRepoRef) {
     env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
   }
+  if (agentHome) {
+    env.AGENT_HOME = agentHome;
+  }
   if (workspaceHints.length > 0) {
     env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
   }

packages/adapters/gemini-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-gemini-local",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/gemini-local/src/server/execute.ts

@@ -145,6 +145,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceId = asString(workspaceContext.workspaceId, "");
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
       (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -196,6 +197,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceId) env.PAPERCLIP_WORKSPACE_ID = workspaceId;
   if (workspaceRepoUrl) env.PAPERCLIP_WORKSPACE_REPO_URL = workspaceRepoUrl;
   if (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
+  if (agentHome) env.AGENT_HOME = agentHome;
   if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
 
   for (const [key, value] of Object.entries(envConfig)) {

packages/adapters/openclaw-gateway/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @paperclipai/adapter-openclaw-gateway
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

packages/adapters/openclaw-gateway/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-openclaw-gateway",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/opencode-local/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @paperclipai/adapter-opencode-local
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

packages/adapters/opencode-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-opencode-local",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/opencode-local/src/server/execute.ts

@@ -100,6 +100,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceId = asString(workspaceContext.workspaceId, "");
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -151,6 +152,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceId) env.PAPERCLIP_WORKSPACE_ID = workspaceId;
   if (workspaceRepoUrl) env.PAPERCLIP_WORKSPACE_REPO_URL = workspaceRepoUrl;
   if (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
+  if (agentHome) env.AGENT_HOME = agentHome;
   if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
 
   for (const [key, value] of Object.entries(envConfig)) {

packages/adapters/pi-local/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @paperclipai/adapter-pi-local
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

packages/adapters/pi-local/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-pi-local",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/adapters/pi-local/src/server/execute.ts

@@ -117,6 +117,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   const workspaceId = asString(workspaceContext.workspaceId, "");
   const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
   const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
   const workspaceHints = Array.isArray(context.paperclipWorkspaces)
     ? context.paperclipWorkspaces.filter(
         (value): value is Record<string, unknown> => typeof value === "object" && value !== null,
@@ -176,6 +177,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
   if (workspaceId) env.PAPERCLIP_WORKSPACE_ID = workspaceId;
   if (workspaceRepoUrl) env.PAPERCLIP_WORKSPACE_REPO_URL = workspaceRepoUrl;
   if (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
+  if (agentHome) env.AGENT_HOME = agentHome;
   if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
 
   for (const [key, value] of Object.entries(envConfig)) {

packages/db/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @paperclipai/db
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/shared@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

packages/db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/db",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/plugins/sdk/README.md

@@ -207,6 +207,7 @@ The same set of values is used as **slot types** (where a component mounts) and
 | `sidebarPanel` | Global | — |
 | `settingsPage` | Global | — |
 | `dashboardWidget` | Global | — |
+| `globalToolbarButton` | Global | — |
 | `detailTab` | Entity | `project`, `issue`, `agent`, `goal`, `run` |
 | `taskDetailView` | Entity | (task/issue context) |
 | `commentAnnotation` | Entity | `comment` |
@@ -253,9 +254,13 @@ A specialized slot rendered in the context of a task or issue detail view. Simil
 
 A link or small component rendered **once per project** under that project's row in the sidebar Projects list. Use this to add project-scoped navigation entries (e.g. "Files", "Linear Sync") that deep-link into a plugin detail tab: `/:company/projects/:projectRef?tab=plugin:<key>:<slotId>`. Receives `PluginProjectSidebarItemProps` with `context.companyId` set to the active company, `context.entityId` set to the project id, and `context.entityType` set to `"project"`. Use the optional `order` field in the manifest slot to control sort position. Requires the `ui.sidebar.register` capability.
 
+#### `globalToolbarButton`
+
+A button rendered in the global top bar (breadcrumb bar) that appears on every page. Use this for company-wide actions that are not scoped to a specific entity — for example, a universal search trigger, a global sync status indicator, or a floating action that applies across the whole workspace. Receives only `context.companyId` and `context.companyPrefix`; no entity context is available. Requires the `ui.action.register` capability.
+
 #### `toolbarButton`
 
-A button rendered in the toolbar of a host surface (e.g. project detail, issue detail). Use this for short-lived, contextual actions like triggering a sync, opening a picker, or running a quick command. The component can open a plugin-owned modal internally for confirmations or compact forms. Receives `context.companyId` set to the active company; entity context varies by host surface. Requires the `ui.action.register` capability.
+A button rendered in the toolbar of an entity page (e.g. project detail, issue detail). Use this for short-lived, contextual actions scoped to the current entity — like triggering a project sync, opening a picker, or running a quick command on that entity. The component can open a plugin-owned modal internally for confirmations or compact forms. Receives `context.companyId`, `context.entityId`, and `context.entityType`; declare `entityTypes` in the manifest to control which entity pages the button appears on. Requires the `ui.action.register` capability.
 
 #### `contextMenuItem`
 
@@ -481,7 +486,9 @@ Each slot type receives a typed props object with `context: PluginHostContext`.
 | `sidebar` | `PluginSidebarProps` | — |
 | `settingsPage` | `PluginSettingsPageProps` | — |
 | `dashboardWidget` | `PluginWidgetProps` | — |
+| `globalToolbarButton` | `PluginGlobalToolbarButtonProps` | — |
 | `detailTab` | `PluginDetailTabProps` | `entityId: string`, `entityType: string` |
+| `toolbarButton` | `PluginToolbarButtonProps` | `entityId: string`, `entityType: string` |
 | `commentAnnotation` | `PluginCommentAnnotationProps` | `entityId: string`, `entityType: "comment"`, `parentEntityId: string`, `projectId`, `companyPrefix` |
 | `commentContextMenuItem` | `PluginCommentContextMenuItemProps` | `entityId: string`, `entityType: "comment"`, `parentEntityId: string`, `projectId`, `companyPrefix` |
 | `projectSidebarItem` | `PluginProjectSidebarItemProps` | `entityId: string`, `entityType: "project"` |
@@ -521,7 +528,7 @@ V1 does not provide a dedicated `modal` slot. Plugins can either:
 - declare concrete UI mount points in `ui.slots`
 - declare host-rendered entry points in `ui.launchers`
 
-Supported launcher placement zones currently mirror the major host surfaces such as `projectSidebarItem`, `toolbarButton`, `detailTab`, `settingsPage`, and `contextMenuItem`. Plugins may still open their own local modal from those entry points when needed.
+Supported launcher placement zones currently mirror the major host surfaces such as `projectSidebarItem`, `globalToolbarButton`, `toolbarButton`, `detailTab`, `settingsPage`, and `contextMenuItem`. Plugins may still open their own local modal from those entry points when needed.
 
 Declarative launcher example:
 
@@ -597,7 +604,14 @@ Use optional `order` in the slot to sort among other project sidebar items. See
 
 ## Toolbar launcher with a local modal
 
-For short-lived actions, mount a `toolbarButton` and open a plugin-owned modal inside the component. Use `useHostContext()` to scope the action to the current company or project.
+Two toolbar slot types are available depending on where the button should appear:
+
+- **`globalToolbarButton`** — renders in the top bar on every page, scoped to the company. No entity context. Use for workspace-wide actions.
+- **`toolbarButton`** — renders on entity detail pages (project, issue, etc.). Receives `entityId` and `entityType`. Declare `entityTypes` to control which pages the button appears on.
+
+For short-lived actions, mount the appropriate slot type and open a plugin-owned modal inside the component. Use `useHostContext()` to scope the action to the current company or entity.
+
+Project-scoped example (appears only on project detail pages):
 
 ```json
 {
@@ -607,7 +621,8 @@ For short-lived actions, mount a `toolbarButton` and open a plugin-owned modal i
         "type": "toolbarButton",
         "id": "sync-toolbar-button",
         "displayName": "Sync",
-        "exportName": "SyncToolbarButton"
+        "exportName": "SyncToolbarButton",
+        "entityTypes": ["project"]
       }
     ]
   },

packages/shared/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @paperclipai/shared
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/shared",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

packages/shared/src/constants.ts

@@ -370,6 +370,7 @@ export const PLUGIN_UI_SLOT_TYPES = [
   "sidebar",
   "sidebarPanel",
   "projectSidebarItem",
+  "globalToolbarButton",
   "toolbarButton",
   "contextMenuItem",
   "commentAnnotation",
@@ -419,6 +420,7 @@ export const PLUGIN_LAUNCHER_PLACEMENT_ZONES = [
   "sidebar",
   "sidebarPanel",
   "projectSidebarItem",
+  "globalToolbarButton",
   "toolbarButton",
   "contextMenuItem",
   "commentAnnotation",

releases/v0.3.1.md

@@ -0,0 +1,54 @@
+# v0.3.1
+
+> Released: 2026-03-12
+
+## Highlights
+
+- **Gemini CLI adapter** — Full local adapter support for Google's Gemini CLI. Includes API-key detection, turn-limit handling, sandbox and approval modes, skill injection into `~/.gemini/`, and yolo-mode default. ([#452](https://github.com/paperclipai/paperclip/pull/452), [#656](https://github.com/paperclipai/paperclip/pull/656), @aaaaron)
+- **Run transcript polish** — Run transcripts render markdown, fold command stdout, redact home paths and user identities, and display humanized event labels across both detail and live surfaces. ([#648](https://github.com/paperclipai/paperclip/pull/648), [#695](https://github.com/paperclipai/paperclip/pull/695))
+- **Inbox refinements** — Improved tab behavior, badge counts aligned with visible unread items, better mobile layout, and smoother new-issue submit state. ([#613](https://github.com/paperclipai/paperclip/pull/613))
+- **Improved onboarding wizard** — Onboarding now shows Claude Code and Codex as recommended adapters, collapses other types, and features animated step transitions with clickable tabs. Adapter environment checks animate on success and show debug output only on failure. ([#700](https://github.com/paperclipai/paperclip/pull/700))
+
+## Improvements
+
+- **Instance heartbeat settings sidebar** — View and manage heartbeat configuration directly from the instance settings page with compact grouped run lists. ([#697](https://github.com/paperclipai/paperclip/pull/697))
+- **Project and agent configuration tabs** — New tabbed configuration UI for projects and agents, including execution workspace policy settings. ([#613](https://github.com/paperclipai/paperclip/pull/613))
+- **Agent runs tab** — Agent detail pages now include a dedicated runs tab.
+- **Configurable attachment content types** — The `PAPERCLIP_ALLOWED_ATTACHMENT_TYPES` env var lets operators control which file types can be uploaded. ([#495](https://github.com/paperclipai/paperclip/pull/495), @subhendukundu)
+- **Default max turns raised to 300** — Agents now default to 300 max turns instead of the previous limit. ([#701](https://github.com/paperclipai/paperclip/pull/701))
+- **Issue creator shown in sidebar** — The issue properties pane now displays who created each issue. ([#145](https://github.com/paperclipai/paperclip/pull/145), @cschneid)
+- **Company-aware 404 handling** — The UI now shows company-scoped not-found pages instead of a generic error.
+- **Tools for Worktree workflow for developers** — New `paperclipai worktree:make` command provisions isolated development instances with their own database, secrets, favicon branding, and git hooks. Worktrees support minimal seed mode, start-point selection, and automatic workspace rebinding. ([#496](https://github.com/paperclipai/paperclip/pull/496), [#530](https://github.com/paperclipai/paperclip/pull/530), [#545](https://github.com/paperclipai/paperclip/pull/545))
+
+## Fixes
+
+- **Gemini Docker build** — Include the Gemini adapter manifest in the Docker deps stage so production builds succeed. ([#706](https://github.com/paperclipai/paperclip/pull/706), @zvictor)
+- **Approval retries made idempotent** — Duplicate approval submissions no longer create duplicate records. ([#502](https://github.com/paperclipai/paperclip/pull/502), @davidahmann)
+- **Heartbeat cost recording** — Costs are now routed through `costService` instead of being recorded inline, fixing missing cost attribution. ([#386](https://github.com/paperclipai/paperclip/pull/386), @domocarroll)
+- **Claude Code env var leak** — Child adapter processes no longer inherit Claude Code's internal environment variables. ([#485](https://github.com/paperclipai/paperclip/pull/485), @jknair)
+- **`parentId` query filter** — The issues list endpoint now correctly applies the `parentId` filter. ([#491](https://github.com/paperclipai/paperclip/pull/491), @lazmo88)
+- **Remove `Cmd+1..9` shortcut** — The company-switch keyboard shortcut conflicted with browser tab switching and has been removed. ([#628](https://github.com/paperclipai/paperclip/pull/628), @STRML)
+- **IME composition Enter** — Pressing Enter during IME composition in the new-issue title no longer moves focus prematurely. ([#578](https://github.com/paperclipai/paperclip/pull/578), @kaonash)
+- **Restart hint after hostname change** — The CLI now reminds users to restart the server after changing allowed hostnames. ([#549](https://github.com/paperclipai/paperclip/pull/549), @mvanhorn)
+- **Default `dangerouslySkipPermissions` for unattended agents** — Agents running without a terminal now default to skipping permission prompts instead of hanging. ([#388](https://github.com/paperclipai/paperclip/pull/388), @ohld)
+- **Remove stale `paperclip` property from OpenClaw Gateway** — Cleaned up an invalid agent parameter that caused warnings. ([#626](https://github.com/paperclipai/paperclip/pull/626), @openagen)
+- **Issue description overflow** — Long descriptions no longer break the layout.
+- **Worktree JWT persistence** — Environment-sensitive JWT config is now correctly carried into worktree instances.
+- **Dev migration prompt** — Fixed embedded `db:migrate` flow for local development.
+- **Markdown link dialog positioning** — The link insertion dialog no longer renders off-screen.
+- **Pretty logger metadata** — Server log metadata stays on one line instead of wrapping.
+
+## Upgrade Guide
+
+Two new database migrations (`0026`, `0027`) will run automatically on startup:
+
+- **Migration 0026** adds the `workspace_runtime_services` table for worktree-aware runtime support.
+- **Migration 0027** adds `execution_workspace_settings` to issues and `execution_workspace_policy` to projects.
+
+Both are additive (new table and new columns) — no existing data is modified. Standard `paperclipai` startup will apply them automatically.
+
+## Contributors
+
+Thank you to everyone who contributed to this release!
+
+@aaaaron, @adamrobbie-nudge, @cschneid, @davidahmann, @domocarroll, @jknair, @kaonash, @lazmo88, @mvanhorn, @ohld, @openagen, @STRML, @subhendukundu, @zvictor

scripts/dev-runner.mjs

@@ -156,6 +156,24 @@ async function maybePreflightMigrations() {
 
 await maybePreflightMigrations();
 
+async function buildPluginSdk() {
+  console.log("[paperclip] building plugin sdk...");
+  const result = await runPnpm(
+    ["--filter", "@paperclipai/plugin-sdk", "build"],
+    { stdio: "inherit" },
+  );
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    return;
+  }
+  if (result.code !== 0) {
+    console.error("[paperclip] plugin sdk build failed");
+    process.exit(result.code);
+  }
+}
+
+await buildPluginSdk();
+
 if (mode === "watch") {
   env.PAPERCLIP_MIGRATION_PROMPT = "never";
 }

scripts/release-lib.sh

@@ -196,6 +196,36 @@ npm_version_exists() {
   [ "$resolved" = "$version" ]
 }
 
+npm_package_version_exists() {
+  local package_name="$1"
+  local version="$2"
+  local resolved
+
+  resolved="$(npm view "${package_name}@${version}" version 2>/dev/null || true)"
+  [ "$resolved" = "$version" ]
+}
+
+wait_for_npm_package_version() {
+  local package_name="$1"
+  local version="$2"
+  local attempts="${3:-12}"
+  local delay_seconds="${4:-5}"
+  local attempt=1
+
+  while [ "$attempt" -le "$attempts" ]; do
+    if npm_package_version_exists "$package_name" "$version"; then
+      return 0
+    fi
+
+    if [ "$attempt" -lt "$attempts" ]; then
+      sleep "$delay_seconds"
+    fi
+    attempt=$((attempt + 1))
+  done
+
+  return 1
+}
+
 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."

scripts/release.sh

@@ -181,10 +181,12 @@ for (const rel of roots) {
 rows.sort((a, b) => a[0].localeCompare(b[0]));
 
 for (const [dir, name] of rows) {
-  const key = `${dir}\t${name}`;
+  const pkgPath = path.join(root, dir, 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const key = `${dir}\t${name}\t${pkg.version}`;
   if (seen.has(key)) continue;
   seen.add(key);
-  process.stdout.write(`${dir}\t${name}\n`);
+  process.stdout.write(`${dir}\t${name}\t${pkg.version}\n`);
 }
 NODE
 }
@@ -356,6 +358,8 @@ if [ "$canary" = true ]; then
   fi
 fi
 
+VERSIONED_PACKAGE_INFO="$(list_public_package_info)"
+
 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."
@@ -403,6 +407,31 @@ else
     npx changeset publish
     release_info "  ✓ Published ${TARGET_PUBLISH_VERSION} under dist-tag latest"
   fi
+
+  release_info ""
+  release_info "==> Post-publish verification: Confirming npm package availability..."
+  VERIFY_ATTEMPTS="${NPM_PUBLISH_VERIFY_ATTEMPTS:-12}"
+  VERIFY_DELAY_SECONDS="${NPM_PUBLISH_VERIFY_DELAY_SECONDS:-5}"
+  MISSING_PUBLISHED_PACKAGES=""
+  while IFS=$'\t' read -r pkg_dir pkg_name pkg_version; do
+    [ -z "$pkg_name" ] && continue
+    release_info "  Checking $pkg_name@$pkg_version"
+    if wait_for_npm_package_version "$pkg_name" "$pkg_version" "$VERIFY_ATTEMPTS" "$VERIFY_DELAY_SECONDS"; then
+      release_info "    ✓ Found on npm"
+      continue
+    fi
+
+    if [ -n "$MISSING_PUBLISHED_PACKAGES" ]; then
+      MISSING_PUBLISHED_PACKAGES="${MISSING_PUBLISHED_PACKAGES}, "
+    fi
+    MISSING_PUBLISHED_PACKAGES="${MISSING_PUBLISHED_PACKAGES}${pkg_name}@${pkg_version}"
+  done <<< "$VERSIONED_PACKAGE_INFO"
+
+  if [ -n "$MISSING_PUBLISHED_PACKAGES" ]; then
+    release_fail "publish completed but npm never exposed: $MISSING_PUBLISHED_PACKAGES. Inspect the changeset publish output before treating this release as good."
+  fi
+
+  release_info "  ✓ Verified all versioned packages are available on npm"
 fi
 
 release_info ""

server/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @paperclipai/server
 
+## 0.3.1
+
+### Patch Changes
+
+- Stable release preparation for 0.3.1
+- Updated dependencies
+  - @paperclipai/adapter-utils@0.3.1
+  - @paperclipai/adapter-claude-local@0.3.1
+  - @paperclipai/adapter-codex-local@0.3.1
+  - @paperclipai/adapter-cursor-local@0.3.1
+  - @paperclipai/adapter-gemini-local@0.3.1
+  - @paperclipai/adapter-openclaw-gateway@0.3.1
+  - @paperclipai/adapter-opencode-local@0.3.1
+  - @paperclipai/adapter-pi-local@0.3.1
+  - @paperclipai/db@0.3.1
+  - @paperclipai/shared@0.3.1
+
 ## 0.3.0
 
 ### Minor Changes

server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/server",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

server/src/app.ts

@@ -37,6 +37,7 @@ import { pluginLifecycleManager } from "./services/plugin-lifecycle.js";
 import { createPluginJobCoordinator } from "./services/plugin-job-coordinator.js";
 import { buildHostServices, flushPluginLogBuffer } from "./services/plugin-host-services.js";
 import { createPluginEventBus } from "./services/plugin-event-bus.js";
+import { setPluginEventBus } from "./services/activity-log.js";
 import { createPluginDevWatcher } from "./services/plugin-dev-watcher.js";
 import { createPluginHostServiceCleanup } from "./services/plugin-host-service-cleanup.js";
 import { pluginRegistryService } from "./services/plugin-registry.js";
@@ -141,6 +142,7 @@ export async function createApp(
   const workerManager = createPluginWorkerManager();
   const pluginRegistry = pluginRegistryService(db);
   const eventBus = createPluginEventBus();
+  setPluginEventBus(eventBus);
   const jobStore = pluginJobStore(db);
   const lifecycle = pluginLifecycleManager(db, { workerManager });
   const scheduler = createPluginJobScheduler({

server/src/services/activity-log.ts

@@ -1,8 +1,25 @@
+import { randomUUID } from "node:crypto";
 import type { Db } from "@paperclipai/db";
 import { activityLog } from "@paperclipai/db";
+import { PLUGIN_EVENT_TYPES, type PluginEventType } from "@paperclipai/shared";
+import type { PluginEvent } from "@paperclipai/plugin-sdk";
 import { publishLiveEvent } from "./live-events.js";
 import { redactCurrentUserValue } from "../log-redaction.js";
 import { sanitizeRecord } from "../redaction.js";
+import { logger } from "../middleware/logger.js";
+import type { PluginEventBus } from "./plugin-event-bus.js";
+
+const PLUGIN_EVENT_SET: ReadonlySet<string> = new Set(PLUGIN_EVENT_TYPES);
+
+let _pluginEventBus: PluginEventBus | null = null;
+
+/** Wire the plugin event bus so domain events are forwarded to plugins. */
+export function setPluginEventBus(bus: PluginEventBus): void {
+  if (_pluginEventBus) {
+    logger.warn("setPluginEventBus called more than once, replacing existing bus");
+  }
+  _pluginEventBus = bus;
+}
 
 export interface LogActivityInput {
   companyId: string;
@@ -45,4 +62,27 @@ export async function logActivity(db: Db, input: LogActivityInput) {
       details: redactedDetails,
     },
   });
+
+  if (_pluginEventBus && PLUGIN_EVENT_SET.has(input.action)) {
+    const event: PluginEvent = {
+      eventId: randomUUID(),
+      eventType: input.action as PluginEventType,
+      occurredAt: new Date().toISOString(),
+      actorId: input.actorId,
+      actorType: input.actorType,
+      entityId: input.entityId,
+      entityType: input.entityType,
+      companyId: input.companyId,
+      payload: {
+        ...redactedDetails,
+        agentId: input.agentId ?? null,
+        runId: input.runId ?? null,
+      },
+    };
+    void _pluginEventBus.emit(event).then(({ errors }) => {
+      for (const { pluginId, error } of errors) {
+        logger.warn({ pluginId, eventType: event.eventType, err: error }, "plugin event handler failed");
+      }
+    }).catch(() => {});
+  }
 }

server/src/services/heartbeat.ts

@@ -1222,11 +1222,11 @@ export function heartbeatService(db: Db) {
     const staleThresholdMs = opts?.staleThresholdMs ?? 0;
     const now = new Date();
 
-    // Find all runs in "queued" or "running" state
+    // Find all runs stuck in "running" state (queued runs are legitimately waiting; resumeQueuedRuns handles them)
     const activeRuns = await db
       .select()
       .from(heartbeatRuns)
-      .where(inArray(heartbeatRuns.status, ["queued", "running"]));
+      .where(eq(heartbeatRuns.status, "running"));
 
     const reaped: string[] = [];
 
@@ -1523,6 +1523,7 @@ export function heartbeatService(db: Db) {
       repoRef: executionWorkspace.repoRef,
       branchName: executionWorkspace.branchName,
       worktreePath: executionWorkspace.worktreePath,
+      agentHome: resolveDefaultAgentWorkspaceDir(agent.id),
     };
     context.paperclipWorkspaces = resolvedWorkspace.workspaceHints;
     const runtimeServiceIntents = (() => {

server/src/services/plugin-capability-validator.ts

@@ -102,6 +102,7 @@ const UI_SLOT_CAPABILITIES: Record<PluginUiSlotType, PluginCapability> = {
   detailTab: "ui.detailTab.register",
   taskDetailView: "ui.detailTab.register",
   dashboardWidget: "ui.dashboardWidget.register",
+  globalToolbarButton: "ui.action.register",
   toolbarButton: "ui.action.register",
   contextMenuItem: "ui.action.register",
   commentAnnotation: "ui.commentAnnotation.register",
@@ -124,6 +125,7 @@ const LAUNCHER_PLACEMENT_CAPABILITIES: Record<
   sidebar: "ui.sidebar.register",
   sidebarPanel: "ui.sidebar.register",
   projectSidebarItem: "ui.sidebar.register",
+  globalToolbarButton: "ui.action.register",
   toolbarButton: "ui.action.register",
   contextMenuItem: "ui.action.register",
   commentAnnotation: "ui.commentAnnotation.register",

ui/src/components/BreadcrumbBar.tsx

@@ -2,6 +2,7 @@ import { Link } from "@/lib/router";
 import { Menu } from "lucide-react";
 import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { useSidebar } from "../context/SidebarContext";
+import { useCompany } from "../context/CompanyContext";
 import { Button } from "@/components/ui/button";
 import {
   Breadcrumb,
@@ -11,13 +12,45 @@ import {
   BreadcrumbPage,
   BreadcrumbSeparator,
 } from "@/components/ui/breadcrumb";
-import { Fragment } from "react";
+import { Fragment, useMemo } from "react";
+import { PluginSlotOutlet } from "@/plugins/slots";
+import { PluginLauncherOutlet } from "@/plugins/launchers";
 
 export function BreadcrumbBar() {
   const { breadcrumbs } = useBreadcrumbs();
   const { toggleSidebar, isMobile } = useSidebar();
+  const { selectedCompanyId, selectedCompany } = useCompany();
 
-  if (breadcrumbs.length === 0) return null;
+  const globalToolbarSlotContext = useMemo(
+    () => ({
+      companyId: selectedCompanyId ?? null,
+      companyPrefix: selectedCompany?.issuePrefix ?? null,
+    }),
+    [selectedCompanyId, selectedCompany?.issuePrefix],
+  );
+
+  const globalToolbarSlots = (
+    <div className="flex items-center gap-1 ml-auto shrink-0 pl-2">
+      <PluginSlotOutlet
+        slotTypes={["globalToolbarButton"]}
+        context={globalToolbarSlotContext}
+        className="flex items-center gap-1"
+      />
+      <PluginLauncherOutlet
+        placementZones={["globalToolbarButton"]}
+        context={globalToolbarSlotContext}
+        className="flex items-center gap-1"
+      />
+    </div>
+  );
+
+  if (breadcrumbs.length === 0) {
+    return (
+      <div className="border-b border-border px-4 md:px-6 h-12 shrink-0 flex items-center justify-end">
+        {globalToolbarSlots}
+      </div>
+    );
+  }
 
   const menuButton = isMobile && (
     <Button
@@ -34,40 +67,46 @@ export function BreadcrumbBar() {
   // Single breadcrumb = page title (uppercase)
   if (breadcrumbs.length === 1) {
     return (
-      <div className="border-b border-border px-4 md:px-6 h-12 shrink-0 flex items-center min-w-0 overflow-hidden">
+      <div className="border-b border-border px-4 md:px-6 h-12 shrink-0 flex items-center">
         {menuButton}
-        <h1 className="text-sm font-semibold uppercase tracking-wider truncate">
-          {breadcrumbs[0].label}
-        </h1>
+        <div className="min-w-0 overflow-hidden flex-1">
+          <h1 className="text-sm font-semibold uppercase tracking-wider truncate">
+            {breadcrumbs[0].label}
+          </h1>
+        </div>
+        {globalToolbarSlots}
       </div>
     );
   }
 
   // Multiple breadcrumbs = breadcrumb trail
   return (
-    <div className="border-b border-border px-4 md:px-6 h-12 shrink-0 flex items-center min-w-0 overflow-hidden">
+    <div className="border-b border-border px-4 md:px-6 h-12 shrink-0 flex items-center">
       {menuButton}
-      <Breadcrumb className="min-w-0 overflow-hidden">
-        <BreadcrumbList className="flex-nowrap">
-          {breadcrumbs.map((crumb, i) => {
-            const isLast = i === breadcrumbs.length - 1;
-            return (
-              <Fragment key={i}>
-                {i > 0 && <BreadcrumbSeparator />}
-                <BreadcrumbItem className={isLast ? "min-w-0" : "shrink-0"}>
-                  {isLast || !crumb.href ? (
-                    <BreadcrumbPage className="truncate">{crumb.label}</BreadcrumbPage>
-                  ) : (
-                    <BreadcrumbLink asChild>
-                      <Link to={crumb.href}>{crumb.label}</Link>
-                    </BreadcrumbLink>
-                  )}
-                </BreadcrumbItem>
-              </Fragment>
-            );
-          })}
-        </BreadcrumbList>
-      </Breadcrumb>
+      <div className="min-w-0 overflow-hidden flex-1">
+        <Breadcrumb className="min-w-0 overflow-hidden">
+          <BreadcrumbList className="flex-nowrap">
+            {breadcrumbs.map((crumb, i) => {
+              const isLast = i === breadcrumbs.length - 1;
+              return (
+                <Fragment key={i}>
+                  {i > 0 && <BreadcrumbSeparator />}
+                  <BreadcrumbItem className={isLast ? "min-w-0" : "shrink-0"}>
+                    {isLast || !crumb.href ? (
+                      <BreadcrumbPage className="truncate">{crumb.label}</BreadcrumbPage>
+                    ) : (
+                      <BreadcrumbLink asChild>
+                        <Link to={crumb.href}>{crumb.label}</Link>
+                      </BreadcrumbLink>
+                    )}
+                  </BreadcrumbItem>
+                </Fragment>
+              );
+            })}
+          </BreadcrumbList>
+        </Breadcrumb>
+      </div>
+      {globalToolbarSlots}
     </div>
   );
 }

ui/src/index.css

@@ -178,10 +178,16 @@
   background: oklch(0.5 0 0);
 }
 
-/* Auto-hide scrollbar: transparent by default, visible on container hover */
+/* Auto-hide scrollbar: fully transparent by default, visible on container hover */
+.scrollbar-auto-hide::-webkit-scrollbar-track {
+  background: transparent !important;
+}
 .scrollbar-auto-hide::-webkit-scrollbar-thumb {
   background: transparent !important;
 }
+.scrollbar-auto-hide:hover::-webkit-scrollbar-track {
+  background: oklch(0.205 0 0) !important;
+}
 .scrollbar-auto-hide:hover::-webkit-scrollbar-thumb {
   background: oklch(0.4 0 0) !important;
 }

ui/src/plugins/launchers.tsx

@@ -110,6 +110,7 @@ const entityScopedZones = new Set<PluginLauncherPlacementZone>([
   "commentAnnotation",
   "commentContextMenuItem",
   "projectSidebarItem",
+  "toolbarButton",
 ]);
 const focusableElementSelector = [
   "button:not([disabled])",

ui/src/plugins/slots.tsx

@@ -102,7 +102,7 @@ function buildRegistryKey(pluginKey: string, exportName: string): string {
 }
 
 function requiresEntityType(slotType: PluginUiSlotType): boolean {
-  return slotType === "detailTab" || slotType === "taskDetailView" || slotType === "contextMenuItem" || slotType === "commentAnnotation" || slotType === "commentContextMenuItem" || slotType === "projectSidebarItem";
+  return slotType === "detailTab" || slotType === "taskDetailView" || slotType === "contextMenuItem" || slotType === "commentAnnotation" || slotType === "commentContextMenuItem" || slotType === "projectSidebarItem" || slotType === "toolbarButton";
 }
 
 function getErrorMessage(error: unknown): string {