diff --git a/doc/plugins/PLUGIN_SPEC.md b/doc/plugins/PLUGIN_SPEC.md
index 5c3d3993..896f5115 100644
--- a/doc/plugins/PLUGIN_SPEC.md
+++ b/doc/plugins/PLUGIN_SPEC.md
@@ -17,18 +17,25 @@ This spec covers:
 - trust model
 - capability system
 - UI extension surfaces
+- plugin settings UI
+- agent tool contributions
 - event, job, and webhook surfaces
-- workspace-oriented extension surfaces
+- plugin-to-plugin communication
+- local tooling approach for workspace plugins
 - Postgres persistence for extensions
+- uninstall and data lifecycle
+- plugin observability
+- plugin development and testing
 - operator workflows
-- compatibility and upgrade rules
+- hot plugin lifecycle (no server restart)
+- SDK versioning and compatibility rules
 
 This spec does not cover:
 
 - a public marketplace
 - cloud/SaaS multi-tenancy
 - arbitrary third-party schema migrations in the first plugin version
-- arbitrary frontend bundle injection in the first plugin version
+- iframe-sandboxed plugin UI in the first plugin version (plugins render as ES modules in host extension slots)
 
 ## 2. Core Assumptions
 
@@ -81,7 +88,7 @@ A first-class Paperclip business object inside the instance.
 ### 5.3 Project Workspace
 
 A workspace attached to a project through `project_workspaces`.
-This is the primary local runtime anchor for file, terminal, git, and process tooling.
+Plugins resolve workspace paths from this model to locate local directories for file, terminal, git, and process operations.
 
 ### 5.4 Platform Module
 
@@ -139,7 +146,6 @@ Platform module surfaces:
 - `registerStorageProvider()`
 - `registerSecretProvider()`
 - `registerRunLogStore()`
-- future `registerWorkspaceRuntime()` if needed
 
 Platform modules are the right place for:
 
@@ -167,7 +173,7 @@ Plugin categories:
 
 A plugin may declare more than one category.
 
-## 7. Project Workspaces Are The Local Tooling Anchor
+## 7. Project Workspaces
 
 Paperclip already has a concrete workspace model:
 
@@ -175,26 +181,8 @@ Paperclip already has a concrete workspace model:
 - projects expose `primaryWorkspace`
 - the database contains `project_workspaces`
 - project routes already manage workspaces
-- heartbeat resolution already prefers project workspaces before falling back to task-session or agent-home workspaces
 
-Therefore:
-
-1. File plugins should browse project workspaces first.
-2. Terminal sessions should launch against project workspaces by default.
-3. Git plugins should treat the selected project workspace as the repo root anchor.
-4. Process/server tracking should attach to project workspaces whenever possible.
-5. Issue and agent views may deep-link into project workspace context.
-
-Project workspaces may exist in two modes:
-
-- local directory mode: `cwd` is present
-- repo-only mode: `repoUrl` and optional `repoRef` exist, but there is no local `cwd`
-
-Plugins must handle repo-only workspaces explicitly:
-
-- they may show metadata
-- they may show sync state
-- they may not assume local file/PTY/git access until a real `cwd` exists
+Plugins that need local tooling (file browsing, git, terminals, process tracking) can resolve workspace paths through the project workspace APIs and then operate on the filesystem, spawn processes, and run git commands directly. The host does not wrap these operations — plugins own their own implementations.
 
 ## 8. Installation Model
 
@@ -263,16 +251,18 @@ Rules:
 
 - plugin contributions are additive by default
 - plugins may not override core routes or core actions by name collision
-- if two plugins contribute the same route slug or UI slot id, the host must reject startup or force the operator to resolve the collision explicitly
+- UI slot IDs are automatically namespaced by plugin ID (e.g. `@paperclip/plugin-linear:sync-health-widget`), so cross-plugin collisions are structurally impossible
+- if a single plugin declares duplicate slot IDs within its own manifest, the host must reject at install time
 
 ## 10. Package Contract
 
-Each plugin package must export a manifest and a worker entrypoint.
+Each plugin package must export a manifest, a worker entrypoint, and optionally a UI bundle.
 
 Suggested package layout:
 
 - `dist/manifest.js`
 - `dist/worker.js`
+- `dist/ui/` (optional, contains the plugin's frontend bundle)
 
 Suggested `package.json` keys:
 
@@ -282,7 +272,8 @@ Suggested `package.json` keys:
   "version": "0.1.0",
   "paperclipPlugin": {
     "manifest": "./dist/manifest.js",
-    "worker": "./dist/worker.js"
+    "worker": "./dist/worker.js",
+    "ui": "./dist/ui/"
   }
 }
 ```
@@ -303,11 +294,28 @@ export interface PaperclipPluginManifestV1 {
   capabilities: string[];
   entrypoints: {
     worker: string;
+    ui?: string;
   };
   instanceConfigSchema?: JsonSchema;
   jobs?: PluginJobDeclaration[];
   webhooks?: PluginWebhookDeclaration[];
-  ui?: PluginUiDeclaration;
+  tools?: Array<{
+    name: string;
+    displayName: string;
+    description: string;
+    parametersSchema: JsonSchema;
+  }>;
+  ui?: {
+    slots: Array<{
+      type: "page" | "detailTab" | "dashboardWidget" | "sidebar" | "settingsPage";
+      id: string;
+      displayName: string;
+      /** Which export name in the UI bundle provides this component */
+      exportName: string;
+      /** For detailTab: which entity types this tab appears on */
+      entityTypes?: Array<"project" | "issue" | "agent" | "goal" | "run">;
+    }>;
+  };
 }
 ```
 
@@ -318,10 +326,52 @@ Rules:
 - `apiVersion` must match the host-supported plugin API version
 - `capabilities` must be static and install-time visible
 - config schema must be JSON Schema compatible
+- `entrypoints.ui` points to the directory containing the built UI bundle
+- `ui.slots` declares which extension slots the plugin fills, so the host knows what to mount without loading the bundle eagerly; each slot references an `exportName` from the UI bundle
 
-## 11. Runtime Model
+## 11. Agent Tools
 
-## 11.1 Process Model
+Plugins may contribute tools that Paperclip agents can use during runs.
+
+### 11.1 Tool Declaration
+
+Plugins declare tools in their manifest:
+
+```ts
+tools?: Array<{
+  name: string;
+  displayName: string;
+  description: string;
+  parametersSchema: JsonSchema;
+}>;
+```
+
+Tool names are automatically namespaced by plugin ID at runtime (e.g. `linear:search-issues`), so plugins cannot shadow core tools or each other's tools.
+
+### 11.2 Tool Execution
+
+When an agent invokes a plugin tool during a run, the host routes the call to the plugin worker via a `executeTool` RPC method:
+
+- `executeTool(input)` — receives tool name, parsed parameters, and run context (agent ID, run ID, company ID, project ID)
+
+The worker executes the tool logic and returns a typed result. The host enforces capability gates — a plugin must declare `agent.tools.register` to contribute tools, and individual tools may require additional capabilities (e.g. `http.outbound` for tools that call external APIs).
+
+### 11.3 Tool Availability
+
+By default, plugin tools are available to all agents. The operator may restrict tool availability per agent or per project through plugin configuration.
+
+Plugin tools appear in the agent's tool list alongside core tools but are visually distinguished in the UI as plugin-contributed.
+
+### 11.4 Constraints
+
+- Plugin tools must not override or shadow core tools by name.
+- Plugin tools must be idempotent where possible.
+- Tool execution is subject to the same timeout and resource limits as other plugin worker calls.
+- Tool results are included in run logs.
+
+## 12. Runtime Model
+
+## 12.1 Process Model
 
 Third-party plugins run out-of-process by default.
 
@@ -338,7 +388,7 @@ This design provides:
 - easier resource limits
 - a cleaner trust boundary than arbitrary in-process execution
 
-## 11.2 Host Responsibilities
+## 12.2 Host Responsibilities
 
 The host is responsible for:
 
@@ -350,10 +400,9 @@ The host is responsible for:
 - webhook routing
 - activity log writes
 - secret resolution
-- workspace service enforcement
 - UI route registration
 
-## 11.3 Worker Responsibilities
+## 12.3 Worker Responsibilities
 
 The plugin worker is responsible for:
 
@@ -361,11 +410,11 @@ The plugin worker is responsible for:
 - handling domain events
 - handling scheduled jobs
 - handling webhooks
-- producing UI view models
+- serving data and handling actions for the plugin's own UI via `getData` and `performAction`
 - invoking host services through the SDK
 - reporting health information
 
-## 11.4 Failure Policy
+## 12.4 Failure Policy
 
 If a worker fails:
 
@@ -375,7 +424,20 @@ If a worker fails:
 - retry start with bounded backoff
 - do not drop other plugins or core services
 
-## 12. Host-Worker Protocol
+## 12.5 Graceful Shutdown Policy
+
+When the host needs to stop a plugin worker (for upgrade, uninstall, or instance shutdown):
+
+1. The host sends `shutdown()` to the worker.
+2. The worker has 10 seconds to finish in-flight work and exit cleanly.
+3. If the worker does not exit within the deadline, the host sends SIGTERM.
+4. If the worker does not exit within 5 seconds after SIGTERM, the host sends SIGKILL.
+5. Any in-flight job runs are marked `cancelled` with a note indicating forced shutdown.
+6. Any in-flight `getData` or `performAction` calls return an error to the bridge.
+
+The shutdown deadline should be configurable per-plugin in plugin config for plugins that need longer drain periods.
+
+## 13. Host-Worker Protocol
 
 The host must support the following worker RPC methods.
 
@@ -388,15 +450,15 @@ Required methods:
 Optional methods:
 
 - `validateConfig(input)`
+- `configChanged(input)`
 - `onEvent(input)`
 - `runJob(input)`
 - `handleWebhook(input)`
-- `getPageModel(input)`
-- `getWidgetModel(input)`
-- `getDetailTabModel(input)`
+- `getData(input)`
 - `performAction(input)`
+- `executeTool(input)`
 
-### 12.1 `initialize`
+### 13.1 `initialize`
 
 Called once on worker startup.
 
@@ -407,7 +469,7 @@ Input includes:
 - instance info
 - host API version
 
-### 12.2 `health`
+### 13.2 `health`
 
 Returns:
 
@@ -415,7 +477,7 @@ Returns:
 - current error if any
 - optional plugin-reported diagnostics
 
-### 12.3 `validateConfig`
+### 13.3 `validateConfig`
 
 Runs after config changes and startup.
 
@@ -425,7 +487,17 @@ Returns:
 - warnings
 - errors
 
-### 12.4 `onEvent`
+### 13.4 `configChanged`
+
+Called when the operator updates the plugin's instance config at runtime.
+
+Input includes:
+
+- new resolved config
+
+If the worker implements this method, it applies the new config without restarting. If the worker does not implement this method, the host restarts the worker process with the new config (graceful shutdown then restart).
+
+### 13.5 `onEvent`
 
 Receives one typed Paperclip domain event.
 
@@ -436,7 +508,7 @@ Delivery semantics:
 - no global ordering guarantee across all event types
 - per-entity ordering is best effort but not guaranteed after retries
 
-### 12.5 `runJob`
+### 13.6 `runJob`
 
 Runs a declared scheduled job.
 
@@ -447,7 +519,7 @@ The host provides:
 - run id
 - schedule metadata
 
-### 12.6 `handleWebhook`
+### 13.7 `handleWebhook`
 
 Receives inbound webhook payload routed by the host.
 
@@ -459,19 +531,19 @@ The host provides:
 - parsed body if applicable
 - request id
 
-### 12.7 `getPageModel`
+### 13.8 `getData`
 
-Returns a schema-driven view model for the plugin's main page.
+Returns plugin data requested by the plugin's own UI components.
 
-### 12.8 `getWidgetModel`
+The plugin UI calls the host bridge, which forwards the request to the worker. The worker returns typed JSON that the plugin's own frontend components render.
 
-Returns a schema-driven view model for a dashboard widget.
+Input includes:
 
-### 12.9 `getDetailTabModel`
+- data key (plugin-defined, e.g. `"sync-health"`, `"issue-detail"`)
+- context (company id, project id, entity id, etc.)
+- optional query parameters
 
-Returns a schema-driven view model for a project, issue, agent, goal, or run detail tab.
-
-### 12.10 `performAction`
+### 13.9 `performAction`
 
 Runs an explicit plugin action initiated by the board UI.
 
@@ -482,11 +554,22 @@ Examples:
 - "create branch from issue"
 - "restart process"
 
-## 13. SDK Surface
+### 13.10 `executeTool`
+
+Runs a plugin-contributed agent tool during a run.
+
+The host provides:
+
+- tool name (without plugin namespace prefix)
+- parsed parameters matching the tool's declared schema
+- run context: agent ID, run ID, company ID, project ID
+
+The worker executes the tool and returns a typed result (string content, structured data, or error).
+
+## 14. SDK Surface
 
 Plugins do not talk to the DB directly.
 Plugins do not read raw secret material from persisted config.
-Plugins do not touch the filesystem directly outside the host services.
 
 The SDK exposed to workers must provide typed host clients.
 
@@ -505,12 +588,24 @@ Required SDK clients:
 - `ctx.issues`
 - `ctx.agents`
 - `ctx.goals`
-- `ctx.workspace`
+- `ctx.data`
+- `ctx.actions`
+- `ctx.tools`
 - `ctx.logger`
 
-## 13.1 Example SDK Shape
+`ctx.data` and `ctx.actions` register handlers that the plugin's own UI calls through the host bridge. `ctx.data.register(key, handler)` backs `usePluginData(key)` on the frontend. `ctx.actions.register(key, handler)` backs `usePluginAction(key)`.
+
+Plugins that need filesystem, git, terminal, or process operations handle those directly using standard Node APIs or libraries. The host provides project workspace metadata through `ctx.projects` so plugins can resolve workspace paths, but the host does not proxy low-level OS operations.
+
+## 14.1 Example SDK Shape
 
 ```ts
+/** Top-level helper for defining a plugin with type checking */
+export function definePlugin(definition: PluginDefinition): PaperclipPlugin;
+
+/** Re-exported from Zod for config schema definitions */
+export { z } from "zod";
+
 export interface PluginContext {
   manifest: PaperclipPluginManifestV1;
   config: {
@@ -518,6 +613,8 @@ export interface PluginContext {
   };
   events: {
     on(name: string, fn: (event: unknown) => Promise<void>): void;
+    on(name: string, filter: EventFilter, fn: (event: unknown) => Promise<void>): void;
+    emit(name: string, payload: unknown): Promise<void>;
   };
   jobs: {
     register(key: string, input: { cron: string }, fn: (job: PluginJobContext) => Promise<void>): void;
@@ -531,18 +628,39 @@ export interface PluginContext {
     upsert(input: PluginEntityUpsert): Promise<void>;
     list(input: PluginEntityQuery): Promise<PluginEntityRecord[]>;
   };
-  workspace: WorkspacePluginApi;
+  data: {
+    register(key: string, handler: (params: Record<string, unknown>) => Promise<unknown>): void;
+  };
+  actions: {
+    register(key: string, handler: (params: Record<string, unknown>) => Promise<unknown>): void;
+  };
+  tools: {
+    register(name: string, input: PluginToolDeclaration, fn: (params: unknown, runCtx: ToolRunContext) => Promise<ToolResult>): void;
+  };
+  logger: {
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+  };
+}
+
+export interface EventFilter {
+  projectId?: string;
+  companyId?: string;
+  agentId?: string;
+  [key: string]: unknown;
 }
 ```
 
-## 14. Capability Model
+## 15. Capability Model
 
 Capabilities are mandatory and static.
 Every plugin declares them up front.
 
 The host enforces capabilities in the SDK layer and refuses calls outside the granted set.
 
-## 14.1 Capability Categories
+## 15.1 Capability Categories
 
 ### Data Read
 
@@ -566,14 +684,24 @@ The host enforces capabilities in the SDK layer and refuses calls outside the gr
 - `activity.log.write`
 - `metrics.write`
 
+### Plugin State
+
+- `plugin.state.read`
+- `plugin.state.write`
+
 ### Runtime / Integration
 
 - `events.subscribe`
+- `events.emit`
 - `jobs.schedule`
 - `webhooks.receive`
 - `http.outbound`
 - `secrets.read-ref`
 
+### Agent Tools
+
+- `agent.tools.register`
+
 ### UI
 
 - `instance.settings.register`
@@ -583,33 +711,7 @@ The host enforces capabilities in the SDK layer and refuses calls outside the gr
 - `ui.dashboardWidget.register`
 - `ui.action.register`
 
-### Workspace
-
-- `workspace.fs.read`
-- `workspace.fs.write`
-- `workspace.fs.stat`
-- `workspace.fs.search`
-- `workspace.pty.open`
-- `workspace.pty.input`
-- `workspace.pty.resize`
-- `workspace.pty.terminate`
-- `workspace.pty.subscribe`
-- `workspace.git.status`
-- `workspace.git.diff`
-- `workspace.git.log`
-- `workspace.git.branch.create`
-- `workspace.git.commit`
-- `workspace.git.worktree.create`
-- `workspace.git.push`
-- `workspace.process.register`
-- `workspace.process.list`
-- `workspace.process.read`
-- `workspace.process.terminate`
-- `workspace.process.restart`
-- `workspace.process.logs.read`
-- `workspace.http.probe`
-
-## 14.2 Forbidden Capabilities
+## 15.2 Forbidden Capabilities
 
 The host must not expose capabilities for:
 
@@ -618,9 +720,8 @@ The host must not expose capabilities for:
 - auth bypass
 - issue checkout lock override
 - direct DB access
-- direct filesystem access outside approved workspace services
 
-## 14.3 Upgrade Rules
+## 15.3 Upgrade Rules
 
 If a plugin upgrade adds capabilities:
 
@@ -628,7 +729,7 @@ If a plugin upgrade adds capabilities:
 2. the operator must explicitly approve the new capability set
 3. the new version does not become `ready` until approval completes
 
-## 15. Event System
+## 16. Event System
 
 The host must emit typed domain events that plugins may subscribe to.
 
@@ -665,7 +766,38 @@ Each event must include:
 - primary entity metadata
 - typed payload
 
-## 16. Scheduled Jobs
+### 16.1 Event Filtering
+
+Plugins may provide an optional filter when subscribing to events. The filter is evaluated by the host before dispatching to the worker, so filtered-out events never cross the process boundary.
+
+Supported filter fields:
+
+- `projectId` — only receive events for a specific project
+- `companyId` — only receive events for a specific company
+- `agentId` — only receive events for a specific agent
+
+Filters are optional. If omitted, the plugin receives all events of the subscribed type. Filters may be combined (e.g. filter by both company and project).
+
+### 16.2 Plugin-to-Plugin Events
+
+Plugins may emit custom events using `ctx.events.emit(name, payload)`. Plugin-emitted events use a namespaced event type: `plugin.<pluginId>.<eventName>`.
+
+Other plugins may subscribe to these events using the same `ctx.events.on()` API:
+
+```ts
+ctx.events.on("plugin.@paperclip/plugin-git.push-detected", async (event) => {
+  // react to the git plugin detecting a push
+});
+```
+
+Rules:
+
+- Plugin events require the `events.emit` capability.
+- Plugin events are not core domain events — they do not appear in the core activity log unless the emitting plugin explicitly logs them.
+- Plugin events follow the same at-least-once delivery semantics as core events.
+- The host must not allow plugins to emit events in the core namespace (events without the `plugin.` prefix).
+
+## 17. Scheduled Jobs
 
 Plugins may declare scheduled jobs in their manifest.
 
@@ -677,7 +809,7 @@ Job rules:
 4. Every job run is recorded in Postgres.
 5. Failed jobs are retryable.
 
-## 17. Webhooks
+## 18. Webhooks
 
 Plugins may declare webhook endpoints in their manifest.
 
@@ -693,27 +825,117 @@ Rules:
 4. Every delivery is recorded.
 5. Webhook handling must be idempotent.
 
-## 18. UI Extension Model
+## 19. UI Extension Model
 
-The first plugin UI system is schema-driven.
+Plugins ship their own frontend UI as a bundled React module. The host loads plugin UI into designated extension slots and provides a bridge for the plugin frontend to communicate with its own worker backend and with host APIs.
 
-The host renders plugin data using built-in UI components.
-Plugins return view models, not arbitrary React bundles.
+### How Plugin UI Publishing Works In Practice
 
-## 18.1 Global Operator Routes
+A plugin's `dist/ui/` directory contains a built React bundle. The host serves this bundle and loads it into the page when the user navigates to a plugin surface (a plugin page, a detail tab, a dashboard widget, etc.).
+
+**The host provides, the plugin renders:**
+
+1. The host defines **extension slots** — designated mount points in the UI where plugin components can appear (pages, tabs, widgets, sidebar entries, action bars).
+2. The plugin's UI bundle exports named components for each slot it wants to fill.
+3. The host mounts the plugin component into the slot, passing it a **host bridge** object.
+4. The plugin component uses the bridge to fetch data from its own worker (via `getData`), call actions (via `performAction`), read host context (current company, project, entity), and use shared host UI primitives (design tokens, common components).
+
+**Concrete example: a Linear plugin ships a dashboard widget.**
+
+The plugin's UI bundle exports:
+
+```tsx
+// dist/ui/index.tsx
+import { usePluginData, usePluginAction, MetricCard, StatusBadge } from "@paperclipai/plugin-sdk/ui";
+
+export function DashboardWidget({ context }: PluginWidgetProps) {
+  const { data, loading } = usePluginData("sync-health", { companyId: context.companyId });
+  const resync = usePluginAction("resync");
+
+  if (loading) return <Spinner />;
+
+  return (
+    <div>
+      <MetricCard label="Synced Issues" value={data.syncedCount} trend={data.trend} />
+      {data.mappings.map(m => (
+        <StatusBadge key={m.id} label={m.label} status={m.status} />
+      ))}
+      <button onClick={() => resync({ companyId: context.companyId })}>Resync Now</button>
+    </div>
+  );
+}
+```
+
+**What happens at runtime:**
+
+1. User opens the dashboard. The host sees that the Linear plugin registered a `DashboardWidget` export.
+2. The host mounts the plugin's `DashboardWidget` component into the dashboard widget slot, passing `context` (current company, user, etc.) and the bridge.
+3. `usePluginData("sync-health", ...)` calls through the bridge → host → plugin worker's `getData` RPC → returns JSON → the plugin component renders it however it wants.
+4. When the user clicks "Resync Now", `usePluginAction("resync")` calls through the bridge → host → plugin worker's `performAction` RPC.
+
+**What the host controls:**
+
+- The host decides **where** plugin components appear (which slots exist and when they mount).
+- The host provides the **bridge** — plugin UI cannot make arbitrary network requests or access host internals directly.
+- The host enforces **capability gates** — if a plugin's worker does not have a capability, the bridge rejects the call even if the UI requests it.
+- The host provides **design tokens and shared components** via `@paperclipai/plugin-sdk/ui` so plugins can match the host's visual language without being forced to.
+
+**What the plugin controls:**
+
+- The plugin decides **how** to render its data — it owns its React components, layout, interactions, and state management.
+- The plugin decides **what data** to fetch and **what actions** to expose.
+- The plugin can use any React patterns (hooks, context, third-party component libraries) inside its bundle.
+
+### 19.0.1 Plugin UI SDK (`@paperclipai/plugin-sdk/ui`)
+
+The SDK includes a `ui` subpath export that plugin frontends import. This subpath provides:
+
+- **Bridge hooks**: `usePluginData(key, params)`, `usePluginAction(key)`, `useHostContext()`
+- **Design tokens**: colors, spacing, typography, shadows matching the host theme
+- **Shared components**: `MetricCard`, `StatusBadge`, `DataTable`, `LogView`, `ActionBar`, `Spinner`, etc.
+- **Type definitions**: `PluginPageProps`, `PluginWidgetProps`, `PluginDetailTabProps`
+
+Plugins are encouraged but not required to use the shared components. A plugin may render entirely custom UI as long as it communicates through the bridge.
+
+### 19.0.2 Bundle Isolation
+
+Plugin UI bundles are loaded as standard ES modules, not iframed. This gives plugins full rendering performance and access to the host's design tokens.
+
+Isolation rules:
+
+- Plugin bundles must not import from host internals. They may only import from `@paperclipai/plugin-sdk/ui` and their own dependencies.
+- Plugin bundles must not access `window.fetch` or `XMLHttpRequest` directly for host API calls. All host communication goes through the bridge.
+- The host may enforce Content Security Policy rules that restrict plugin network access to the bridge endpoint only.
+- Plugin bundles must be statically analyzable — no dynamic `import()` of URLs outside the plugin's own bundle.
+
+If stronger isolation is needed later, the host can move to iframe-based mounting for untrusted plugins without changing the plugin's source code (the bridge API stays the same).
+
+### 19.0.3 Bundle Serving
+
+Plugin UI bundles must be pre-built ESM. The host does not compile or transform plugin UI code at runtime.
+
+The host serves the plugin's `dist/ui/` directory as static assets under a namespaced path:
+
+- `/_plugins/:pluginId/ui/*`
+
+When the host renders an extension slot, it dynamically imports the plugin's UI entry module from this path, resolves the named export declared in `ui.slots[].exportName`, and mounts it into the slot.
+
+In development, the host may support a `devUiUrl` override in plugin config that points to a local dev server (e.g. Vite) so plugin authors can use hot-reload during development without rebuilding.
+
+## 19.1 Global Operator Routes
 
 - `/settings/plugins`
 - `/settings/plugins/:pluginId`
 
 These routes are instance-level.
 
-## 18.2 Company-Context Routes
+## 19.2 Company-Context Routes
 
 - `/:companyPrefix/plugins/:pluginId`
 
 These routes exist because the board UI is organized around companies even though plugin installation is global.
 
-## 18.3 Detail Tabs
+## 19.3 Detail Tabs
 
 Plugins may add tabs to:
 
@@ -727,103 +949,108 @@ Recommended route pattern:
 
 - `/:companyPrefix/<entity>/:id?tab=<plugin-tab-id>`
 
-## 18.4 Dashboard Widgets
+## 19.4 Dashboard Widgets
 
 Plugins may add cards or sections to the dashboard.
 
-## 18.5 Sidebar Entries
+## 19.5 Sidebar Entries
 
 Plugins may add sidebar links to:
 
 - global plugin settings
 - company-context plugin pages
 
-## 18.6 Allowed View Model Types
+## 19.6 Shared Components In `@paperclipai/plugin-sdk/ui`
 
-The host should support a limited set of schema-rendered components:
+The host SDK ships shared components that plugins can import to quickly build UIs that match the host's look and feel. These are convenience building blocks, not a requirement.
 
-- metric cards
-- status lists
-- tables
-- timeseries charts
-- markdown text
-- key/value blocks
-- action bars
-- log views
-- JSON/debug views
+| Component | What it renders | Typical use |
+|---|---|---|
+| `MetricCard` | Single number with label, optional trend/sparkline | KPIs, counts, rates |
+| `StatusBadge` | Inline status indicator (ok/warning/error/info) | Sync health, connection status |
+| `DataTable` | Rows and columns with optional sorting and pagination | Issue lists, job history, process lists |
+| `TimeseriesChart` | Line or bar chart with timestamped data points | Revenue trends, sync volume, error rates |
+| `MarkdownBlock` | Rendered markdown text | Descriptions, help text, notes |
+| `KeyValueList` | Label/value pairs in a definition-list layout | Entity metadata, config summary |
+| `ActionBar` | Row of buttons wired to `usePluginAction` | Resync, create branch, restart process |
+| `LogView` | Scrollable log output with timestamps | Webhook deliveries, job output, process logs |
+| `JsonTree` | Collapsible JSON tree for debugging | Raw API responses, plugin state inspection |
+| `Spinner` | Loading indicator | Data fetch states |
 
-Arbitrary frontend bundle injection is explicitly out of scope for the first plugin system.
+Plugins may also use entirely custom components. The shared components exist to reduce boilerplate and keep visual consistency, not to limit what plugins can render.
 
-## 19. Workspace Service APIs
+## 19.7 Error Propagation Through The Bridge
 
-Workspace service APIs are the foundation for local tooling plugins.
+The bridge hooks must return structured errors so plugin UI can handle failures gracefully.
 
-All workspace APIs must route through the host and validate against known project workspace roots.
+`usePluginData` returns:
 
-## 19.1 Project Workspace APIs
+```ts
+{
+  data: T | null;
+  loading: boolean;
+  error: PluginBridgeError | null;
+}
+```
 
-Required host APIs:
+`usePluginAction` returns an async function that either resolves with the result or throws a `PluginBridgeError`.
 
-- list project workspaces
-- get project primary workspace
-- resolve project workspace from issue
-- resolve current workspace from agent/run when available
+`PluginBridgeError` shape:
 
-## 19.2 File APIs
+```ts
+interface PluginBridgeError {
+  code: "WORKER_UNAVAILABLE" | "CAPABILITY_DENIED" | "WORKER_ERROR" | "TIMEOUT" | "UNKNOWN";
+  message: string;
+  /** Original error details from the worker, if available */
+  details?: unknown;
+}
+```
 
-- read file
-- write file
-- stat path
-- search path or filename
-- list directory
+Error codes:
 
-All file APIs take a resolved workspace anchor plus a relative path.
+- `WORKER_UNAVAILABLE` — the plugin worker is not running (crashed, shutting down, not yet started)
+- `CAPABILITY_DENIED` — the plugin does not have the required capability for this operation
+- `WORKER_ERROR` — the worker returned an error from its `getData` or `performAction` handler
+- `TIMEOUT` — the worker did not respond within the configured timeout
+- `UNKNOWN` — unexpected bridge-level failure
 
-## 19.3 PTY APIs
+The `@paperclipai/plugin-sdk/ui` subpath should also export an `ErrorBoundary` component that plugin authors can use to catch rendering errors without crashing the host page.
 
-- open terminal session
-- send input
-- resize
-- terminate
-- subscribe to output
+## 19.8 Plugin Settings UI
 
-PTY sessions should default to the selected project workspace when one exists.
+Each plugin that declares an `instanceConfigSchema` in its manifest gets an auto-generated settings form at `/settings/plugins/:pluginId`. The host renders the form from the JSON Schema.
 
-## 19.4 Git APIs
+The auto-generated form supports:
 
-- status
-- diff
-- log
-- branch create
-- worktree create
-- commit
-- push
+- text inputs, number inputs, toggles, select dropdowns derived from schema types and enums
+- nested objects rendered as fieldsets
+- arrays rendered as repeatable field groups with add/remove controls
+- secret ref fields: any schema property annotated with `"format": "secret-ref"` renders as a secret picker that resolves through the Paperclip secret provider system rather than a plain text input
+- validation messages derived from schema constraints (`required`, `minLength`, `pattern`, `minimum`, etc.)
+- a "Test Connection" action if the plugin declares a `validateConfig` RPC method — the host calls it and displays the result inline
 
-Git APIs require a local `cwd`.
-If the workspace is repo-only, the host must reject local git operations until a local checkout exists.
+For plugins that need richer settings UX beyond what JSON Schema can express, the plugin may declare a `settingsPage` slot in `ui.slots`. When present, the host renders the plugin's own React component instead of the auto-generated form. The plugin component communicates with its worker through the standard bridge to read and write config.
 
-## 19.5 Process APIs
+Both approaches coexist: a plugin can use the auto-generated form for simple config and add a custom settings page slot for advanced configuration or operational dashboards.
 
-- register process
-- list processes
-- read process metadata
-- terminate
-- restart
-- read logs
-- probe health endpoint
+## 20. Local Tooling
 
-Process tracking should attach to `project_workspace` when possible.
+Plugins that need filesystem, git, terminal, or process operations implement those directly. The host does not wrap or proxy these operations.
 
-## 20. Persistence And Postgres
+The host provides workspace metadata through `ctx.projects` (list workspaces, get primary workspace, resolve workspace from issue or agent/run). Plugins use this metadata to resolve local paths and then operate on the filesystem, spawn processes, shell out to `git`, or open PTY sessions using standard Node APIs or any libraries they choose.
 
-## 20.1 Database Principles
+This keeps the host lean — it does not need to maintain a parallel API surface for every OS-level operation a plugin might need. Plugins own their own logic for file browsing, git workflows, terminal sessions, and process management.
+
+## 21. Persistence And Postgres
+
+## 21.1 Database Principles
 
 1. Core Paperclip data stays in first-party tables.
 2. Most plugin-owned data starts in generic extension tables.
 3. Plugin data should scope to existing Paperclip objects before new tables are introduced.
 4. Arbitrary third-party schema migrations are out of scope for the first plugin system.
 
-## 20.2 Core Table Reuse
+## 21.2 Core Table Reuse
 
 If data becomes part of the actual Paperclip product model, it should become a first-party table.
 
@@ -832,7 +1059,7 @@ Examples:
 - `project_workspaces` is already first-party
 - if Paperclip later decides git state is core product data, it should become a first-party table too
 
-## 20.3 Required Tables
+## 21.3 Required Tables
 
 ### `plugins`
 
@@ -859,7 +1086,7 @@ Indexes:
 - `id` uuid pk
 - `plugin_id` uuid fk `plugins.id` unique not null
 - `config_json` jsonb not null
-- `installed_at` timestamptz not null
+- `created_at` timestamptz not null
 - `updated_at` timestamptz not null
 - `last_error` text null
 
@@ -969,7 +1196,7 @@ Use cases:
 - plugin-owned process records
 - plugin-owned external metric bindings
 
-## 20.4 Activity Log Changes
+## 21.4 Activity Log Changes
 
 The activity log should extend `actor_type` to include `plugin`.
 
@@ -985,13 +1212,13 @@ Plugin-originated mutations should write:
 - `actor_type = plugin`
 - `actor_id = <plugin-id>`
 
-## 20.5 Plugin Migrations
+## 21.5 Plugin Migrations
 
 The first plugin system does not allow arbitrary third-party migrations.
 
 Later, if custom tables become necessary, the system may add a trusted-module-only migration path.
 
-## 21. Secrets
+## 22. Secrets
 
 Plugin config must never persist raw secret values.
 
@@ -1006,7 +1233,7 @@ Rules:
    - webhook delivery rows
    - error messages
 
-## 22. Auditing
+## 23. Auditing
 
 All plugin-originated mutating actions must be auditable.
 
@@ -1018,9 +1245,9 @@ Minimum requirements:
 - plugin health page
 - install/upgrade history in `plugins`
 
-## 23. Operator UX
+## 24. Operator UX
 
-## 23.1 Global Settings
+## 24.1 Global Settings
 
 Global plugin settings page must show:
 
@@ -1031,7 +1258,7 @@ Global plugin settings page must show:
 - current errors
 - install/upgrade/remove actions
 
-## 23.2 Plugin Settings Page
+## 24.2 Plugin Settings Page
 
 Each plugin may expose:
 
@@ -1045,7 +1272,7 @@ Route:
 
 - `/settings/plugins/:pluginId`
 
-## 23.3 Company-Context Plugin Page
+## 24.3 Company-Context Plugin Page
 
 Each plugin may expose a company-context main page:
 
@@ -1053,7 +1280,198 @@ Each plugin may expose a company-context main page:
 
 This page is where board users do most day-to-day work.
 
-## 24. Example Mappings
+## 25. Uninstall And Data Lifecycle
+
+When a plugin is uninstalled, the host must handle plugin-owned data explicitly.
+
+### 25.1 Uninstall Process
+
+1. The host sends `shutdown()` to the worker and follows the graceful shutdown policy.
+2. The host marks the plugin status `uninstalled` in the `plugins` table (soft delete).
+3. Plugin-owned data (`plugin_state`, `plugin_entities`, `plugin_jobs`, `plugin_job_runs`, `plugin_webhook_deliveries`, `plugin_config`) is retained for a configurable grace period (default: 30 days).
+4. During the grace period, the operator can reinstall the same plugin and recover its state.
+5. After the grace period, the host purges all plugin-owned data for the uninstalled plugin.
+6. The operator may force-purge immediately via CLI: `pnpm paperclipai plugin purge <plugin-id>`.
+
+### 25.2 Upgrade Data Considerations
+
+Plugin upgrades do not automatically migrate plugin state. If a plugin's `value_json` shape changes between versions:
+
+- The plugin worker is responsible for migrating its own state on first access after upgrade.
+- The host does not run plugin-defined schema migrations.
+- Plugins should version their state keys or use a schema version field inside `value_json` to detect and handle format changes.
+
+### 25.3 Upgrade Lifecycle
+
+When upgrading a plugin:
+
+1. The host sends `shutdown()` to the old worker.
+2. The host waits for the old worker to drain in-flight work (respecting the shutdown deadline).
+3. Any in-flight jobs that do not complete within the deadline are marked `cancelled`.
+4. The host installs the new version and starts the new worker.
+5. If the new version adds capabilities, the plugin enters `upgrade_pending` and the operator must approve before the new worker becomes `ready`.
+
+### 25.4 Hot Plugin Lifecycle
+
+Plugin install, uninstall, upgrade, and config changes **must** take effect without restarting the Paperclip server. This is a normative requirement, not optional.
+
+The architecture already supports this — plugins run as out-of-process workers with dynamic ESM imports, IPC bridges, and host-managed routing tables. This section makes the requirement explicit so implementations do not regress.
+
+#### 25.4.1 Hot Install
+
+When a plugin is installed at runtime:
+
+1. The host resolves and validates the manifest without stopping existing services.
+2. The host spawns a new worker process for the plugin.
+3. The host registers the plugin's event subscriptions, job schedules, webhook endpoints, and agent tool declarations in the live routing tables.
+4. The host loads the plugin's UI bundle path into the extension slot registry so the frontend can discover it on the next navigation or via a live notification.
+5. The plugin enters `ready` status (or `upgrade_pending` if capability approval is required).
+
+No other plugin or host service is interrupted.
+
+#### 25.4.2 Hot Uninstall
+
+When a plugin is uninstalled at runtime:
+
+1. The host sends `shutdown()` and follows the graceful shutdown policy (Section 12.5).
+2. The host removes the plugin's event subscriptions, job schedules, webhook endpoints, and agent tool declarations from the live routing tables.
+3. The host removes the plugin's UI bundle from the extension slot registry. Any currently mounted plugin UI components are unmounted and replaced with a placeholder or removed entirely.
+4. The host marks the plugin `uninstalled` and starts the data retention grace period (Section 25.1).
+
+No server restart is needed.
+
+#### 25.4.3 Hot Upgrade
+
+When a plugin is upgraded at runtime:
+
+1. The host follows the upgrade lifecycle (Section 25.3) — shut down old worker, start new worker.
+2. If the new version changes event subscriptions, job schedules, webhook endpoints, or agent tools, the host atomically swaps the old registrations for the new ones.
+3. If the new version ships an updated UI bundle, the host invalidates any cached bundle assets and notifies the frontend to reload plugin UI components. Active users see the updated UI on next navigation or via a live refresh notification.
+4. If the manifest `apiVersion` is unchanged and no new capabilities are added, the upgrade completes without operator interaction.
+
+#### 25.4.4 Hot Config Change
+
+When an operator updates a plugin's instance config at runtime:
+
+1. The host writes the new config to `plugin_config`.
+2. The host sends a `configChanged` notification to the running worker via IPC.
+3. The worker receives the new config through `ctx.config` and applies it without restarting. If the plugin needs to re-initialize connections (e.g. a new API token), it does so internally.
+4. If the plugin does not handle `configChanged`, the host restarts the worker process with the new config (graceful shutdown then restart).
+
+#### 25.4.5 Frontend Cache Invalidation
+
+The host must version plugin UI bundle URLs (e.g. `/_plugins/:pluginId/ui/:version/*` or content-hash-based paths) so that browser caches do not serve stale bundles after upgrade or reinstall.
+
+The host should emit a `plugin.ui.updated` event that the frontend listens for to trigger re-import of updated plugin modules without a full page reload.
+
+#### 25.4.6 Worker Process Management
+
+The host's plugin process manager must support:
+
+- starting a worker for a newly installed plugin without affecting other workers
+- stopping a worker for an uninstalled plugin without affecting other workers
+- replacing a worker during upgrade (stop old, start new) atomically from the routing table's perspective
+- restarting a worker after crash without operator intervention (with backoff)
+
+Each worker process is independent. There is no shared process pool or batch restart mechanism.
+
+## 26. Plugin Observability
+
+### 26.1 Logging
+
+Plugin workers use `ctx.logger` to emit structured logs. The host captures these logs and stores them in a queryable format.
+
+Log storage rules:
+
+- Plugin logs are stored in a `plugin_logs` table or appended to a log file under the plugin's data directory.
+- Each log entry includes: plugin ID, timestamp, level, message, and optional structured metadata.
+- Logs are queryable from the plugin settings page in the UI.
+- Logs have a configurable retention period (default: 7 days).
+- The host captures `stdout` and `stderr` from the worker process as fallback logs even if the worker does not use `ctx.logger`.
+
+### 26.2 Health Dashboard
+
+The plugin settings page must show:
+
+- current worker status (running, error, stopped)
+- uptime since last restart
+- recent log entries
+- job run history with success/failure rates
+- webhook delivery history with success/failure rates
+- last health check result and diagnostics
+- resource usage if available (memory, CPU)
+
+### 26.3 Alerting
+
+The host should emit internal events when plugin health degrades. These use the `plugin.*` namespace (not core domain events) and do not appear in the core activity log:
+
+- `plugin.health.degraded` — worker reporting errors or failing health checks
+- `plugin.health.recovered` — worker recovered from error state
+- `plugin.worker.crashed` — worker process exited unexpectedly
+- `plugin.worker.restarted` — worker restarted after crash
+
+These events can be consumed by other plugins (e.g. a notification plugin) or surfaced in the dashboard.
+
+## 27. Plugin Development And Testing
+
+### 27.1 `@paperclipai/plugin-test-harness`
+
+The host should publish a test harness package that plugin authors use for local development and testing.
+
+The test harness provides:
+
+- a mock host that implements the full SDK interface (`ctx.config`, `ctx.events`, `ctx.state`, etc.)
+- ability to send synthetic events and verify handler responses
+- ability to trigger job runs and verify side effects
+- ability to simulate `getData` and `performAction` calls as if coming from the UI bridge
+- ability to simulate `executeTool` calls as if coming from an agent run
+- in-memory state and entity stores for assertions
+- configurable capability sets for testing capability denial paths
+
+Example usage:
+
+```ts
+import { createTestHarness } from "@paperclipai/plugin-test-harness";
+import manifest from "../dist/manifest.js";
+import { register } from "../dist/worker.js";
+
+const harness = createTestHarness({ manifest, capabilities: manifest.capabilities });
+await register(harness.ctx);
+
+// Simulate an event
+await harness.emit("issue.created", { issueId: "iss-1", projectId: "proj-1" });
+
+// Verify state was written
+const state = await harness.state.get({ pluginId: manifest.id, scopeKind: "issue", scopeId: "iss-1", namespace: "sync", stateKey: "external-id" });
+expect(state).toBeDefined();
+
+// Simulate a UI data request
+const data = await harness.getData("sync-health", { companyId: "comp-1" });
+expect(data.syncedCount).toBeGreaterThan(0);
+```
+
+### 27.2 Local Plugin Development
+
+For developing a plugin against a running Paperclip instance:
+
+- The operator installs the plugin from a local path: `pnpm paperclipai plugin install ./path/to/plugin`
+- The host watches the plugin directory for changes and restarts the worker on rebuild.
+- `devUiUrl` in plugin config can point to a local Vite dev server for UI hot-reload.
+- The plugin settings page shows real-time logs from the worker for debugging.
+
+### 27.3 Plugin Starter Template
+
+The host should publish a starter template (`create-paperclip-plugin`) that scaffolds:
+
+- `package.json` with correct `paperclipPlugin` keys
+- manifest with placeholder values
+- worker entry with SDK type imports and example event handler
+- UI entry with example `DashboardWidget` using bridge hooks
+- test file using the test harness
+- build configuration (esbuild or similar) for both worker and UI bundles
+- `.gitignore` and `tsconfig.json`
+
+## 28. Example Mappings
 
 This spec directly supports the following plugin types:
 
@@ -1066,18 +1484,66 @@ This spec directly supports the following plugin types:
 - `@paperclip/plugin-runtime-processes`
 - `@paperclip/plugin-stripe`
 
-## 25. Compatibility And Versioning
+## 29. Compatibility And Versioning
 
-Rules:
+### 29.1 API Version Rules
 
 1. Host supports one or more explicit plugin API versions.
 2. Plugin manifest declares exactly one `apiVersion`.
 3. Host rejects unsupported versions at install time.
-4. SDK packages are versioned with the host protocol.
-5. Plugin upgrades are explicit operator actions.
-6. Capability expansion requires explicit operator approval.
+4. Plugin upgrades are explicit operator actions.
+5. Capability expansion requires explicit operator approval.
 
-## 26. Recommended Delivery Order
+### 29.2 SDK Versioning
+
+The host publishes a single SDK package for plugin authors:
+
+- `@paperclipai/plugin-sdk` — the complete plugin SDK
+
+The package uses subpath exports to separate worker and UI concerns:
+
+- `@paperclipai/plugin-sdk` — worker-side SDK (context, events, state, tools, logger, `definePlugin`, `z`)
+- `@paperclipai/plugin-sdk/ui` — frontend SDK (bridge hooks, shared components, design tokens)
+
+A single package simplifies dependency management for plugin authors — one dependency, one version, one changelog. The subpath exports keep bundle separation clean: worker code imports from the root, UI code imports from `/ui`. Build tools tree-shake accordingly so the worker bundle does not include React components and the UI bundle does not include worker-only code.
+
+Versioning rules:
+
+1. **Semver**: The SDK follows strict semantic versioning. Major version bumps indicate breaking changes to either the worker or UI surface; minor versions add new features backwards-compatibly; patch versions are bug fixes only.
+2. **Tied to API version**: Each major SDK version corresponds to exactly one plugin `apiVersion`. When `@paperclipai/plugin-sdk@2.x` ships, it targets `apiVersion: 2`. Plugins built with SDK 1.x continue to declare `apiVersion: 1`.
+3. **Host multi-version support**: The host must support at least the current and one previous `apiVersion` simultaneously. This means plugins built against the previous SDK major version continue to work without modification. The host maintains separate IPC protocol handlers for each supported API version.
+4. **Minimum SDK version in manifest**: Plugins declare `sdkVersion` in the manifest as a semver range (e.g. `">=1.4.0 <2.0.0"`). The host validates this at install time and warns if the plugin's declared range is outside the host's supported SDK versions.
+5. **Deprecation timeline**: When a new `apiVersion` ships, the previous version enters a deprecation period of at least 6 months. During this period:
+   - The host continues to load plugins targeting the deprecated version.
+   - The host logs a deprecation warning at plugin startup.
+   - The plugin settings page shows a banner indicating the plugin should be upgraded.
+   - After the deprecation period ends, the host may drop support for the old version in a future release.
+6. **SDK changelog and migration guides**: Each major SDK release must include a migration guide documenting every breaking change, the new API surface, and a step-by-step upgrade path for plugin authors.
+7. **UI surface stability**: Breaking changes to shared UI components (removing a component, changing required props) or design tokens require a major version bump just like worker API changes. The single-package model means both surfaces are versioned together, avoiding drift between worker and UI compatibility.
+
+### 29.3 Version Compatibility Matrix
+
+The host should publish a compatibility matrix:
+
+| Host Version | Supported API Versions | SDK Range |
+|---|---|---|
+| 1.0 | 1 | 1.x |
+| 2.0 | 1, 2 | 1.x, 2.x |
+| 3.0 | 2, 3 | 2.x, 3.x |
+
+This matrix is published in the host docs and queryable via `GET /api/plugins/compatibility`.
+
+### 29.4 Plugin Author Workflow
+
+When a new SDK version is released:
+
+1. Plugin author updates `@paperclipai/plugin-sdk` dependency.
+2. Plugin author follows the migration guide to update code.
+3. Plugin author updates `apiVersion` and `sdkVersion` in the manifest.
+4. Plugin author publishes a new plugin version.
+5. Operators upgrade the plugin on their instances. The old version continues to work until explicitly upgraded.
+
+## 30. Recommended Delivery Order
 
 ## Phase 1
 
@@ -1091,7 +1557,20 @@ Rules:
 - jobs
 - webhooks
 - settings page
-- dashboard widget/page/tab schema rendering
+- plugin UI bundle loading, host bridge, and `@paperclipai/plugin-sdk/ui`
+- extension slot mounting for pages, tabs, widgets, sidebar entries
+- bridge error propagation (`PluginBridgeError`)
+- auto-generated settings form from `instanceConfigSchema`
+- plugin-contributed agent tools
+- plugin-to-plugin events (`plugin.<pluginId>.*` namespace)
+- event filtering
+- graceful shutdown with configurable deadlines
+- plugin logging and health dashboard
+- `@paperclipai/plugin-test-harness`
+- `create-paperclip-plugin` starter template
+- uninstall with data retention grace period
+- hot plugin lifecycle (install, uninstall, upgrade, config change without server restart)
+- SDK versioning with multi-version host support and deprecation policy
 
 This phase is enough for:
 
@@ -1099,32 +1578,22 @@ This phase is enough for:
 - GitHub Issues
 - Grafana
 - Stripe
-
-## Phase 2
-
-- project workspace service built on `project_workspaces`
-- file APIs
-- PTY APIs
-- git APIs
-- process APIs
-- project-context tabs for plugin pages
-
-This phase is enough for:
-
 - file browser
 - terminal
 - git workflow
 - process/server tracking
 
-## Phase 3
+Workspace plugins (file browser, terminal, git, process tracking) do not require additional host APIs — they resolve workspace paths through `ctx.projects` and handle filesystem, git, PTY, and process operations directly.
+
+## Phase 2
 
 - optional `plugin_entities`
 - richer action systems
 - trusted-module migration path if truly needed
-- optional richer frontend extension model
+- iframe-based isolation for untrusted plugin UI bundles
 - plugin ecosystem/distribution work
 
-## 27. Final Design Decision
+## 31. Final Design Decision
 
 Paperclip should not implement a generic in-process hook bag modeled directly after local coding tools.
 
@@ -1132,9 +1601,17 @@ Paperclip should implement:
 
 - trusted platform modules for low-level host integration
 - globally installed out-of-process plugins for additive instance-wide capabilities
-- schema-driven UI contributions
-- project workspace-based local tooling
+- plugin-contributed agent tools (namespaced, capability-gated)
+- plugin-shipped UI bundles rendered in host extension slots via a typed bridge with structured error propagation
+- auto-generated settings UI from config schema, with custom settings pages as an option
+- plugin-to-plugin events for cross-plugin coordination
+- server-side event filtering for efficient event routing
+- plugins own their local tooling logic (filesystem, git, terminal, processes) directly
 - generic extension tables for most plugin state
+- graceful shutdown, uninstall data lifecycle, and plugin observability
+- hot plugin lifecycle — install, uninstall, upgrade, and config changes without server restart
+- SDK versioning with multi-version host support and a clear deprecation policy
+- test harness and starter template for low authoring friction
 - strict preservation of core governance and audit rules
 
 That is the complete target design for the Paperclip plugin system.
diff --git a/doc/plugins/ideas-from-opencode.md b/doc/plugins/ideas-from-opencode.md
index ac4077f7..fcef3c62 100644
--- a/doc/plugins/ideas-from-opencode.md
+++ b/doc/plugins/ideas-from-opencode.md
@@ -26,12 +26,13 @@ The main conclusion is:
 - Paperclip should use multiple extension classes instead of one generic plugin bag:
   - trusted in-process modules for low-level platform concerns like agent adapters, storage providers, secret providers, and possibly run-log backends
   - out-of-process plugins for most third-party integrations like Linear, GitHub Issues, Grafana, Stripe, and schedulers
-  - schema-driven UI contributions for dashboard widgets, settings panels, and company pages
-  - a typed event bus plus scheduled jobs for automation
+  - plugin-contributed agent tools (namespaced, not override-by-collision)
+  - plugin-shipped React UI loaded into host extension slots via a typed bridge
+  - a typed event bus with server-side filtering and plugin-to-plugin events, plus scheduled jobs for automation
 
 If Paperclip does this well, the examples you listed become straightforward:
 
-- file browser / terminal / git workflow / child process tracking become workspace-runtime plugins built on first-party primitives
+- file browser / terminal / git workflow / child process tracking become workspace plugins that resolve paths from the host and handle OS operations directly
 - Linear / GitHub / Grafana / Stripe become connector plugins
 - future knowledge base and accounting features can also fit the same model
 
@@ -193,6 +194,8 @@ The most aggressive part of the design:
 That is very powerful for a local coding assistant.
 It is too dangerous for Paperclip core actions.
 
+However, the concept of plugins contributing agent-usable tools is very valuable for Paperclip — as long as plugin tools are namespaced (cannot shadow core tools) and capability-gated.
+
 ## 7. Auth is also a plugin surface
 
 `opencode` allows plugins to register auth methods for providers.
@@ -400,8 +403,8 @@ Use distinct plugin classes with different trust models.
 |---|---|---|---|---|
 | Platform module | agent adapters, storage providers, secret providers, run-log backends | in-process | highly trusted | tight integration, performance, low-level APIs |
 | Connector plugin | Linear, GitHub Issues, Grafana, Stripe | out-of-process worker or sidecar | medium | external sync, safer isolation, clearer failure boundary |
-| Workspace plugin | file browser, terminal, git workflow, child process/server tracking | mixed: core workspace services plus plugin descriptors | high | needs local OS/workspace primitives but should reuse core services |
-| UI contribution | dashboard widgets, settings forms, company panels | schema-driven first, remote React later if needed | medium | safer than arbitrary frontend code |
+| Workspace plugin | file browser, terminal, git workflow, child process/server tracking | out-of-process, direct OS access | medium | resolves workspace paths from host, owns filesystem/git/PTY/process logic directly |
+| UI contribution | dashboard widgets, settings forms, company panels | plugin-shipped React bundles in host extension slots via bridge | medium | plugins own their rendering; host controls slot placement and bridge access |
 | Automation plugin | alerts, schedulers, sync jobs, webhook processors | out-of-process | medium | event-driven automation is a natural plugin fit |
 
 This split is the most important design recommendation in this report.
@@ -427,10 +430,12 @@ This avoids trying to force Stripe, a PTY terminal, and a new agent adapter into
 
 For third-party plugins, the primary API should be:
 
-- subscribe to typed domain events
+- subscribe to typed domain events (with optional server-side filtering)
+- emit plugin-namespaced events for cross-plugin communication
 - read instance state, including company-bound business records when relevant
 - register webhooks
 - run scheduled jobs
+- contribute tools that agents can use during runs
 - write plugin-owned state
 - add additive UI surfaces
 - invoke explicit Paperclip actions through the API
@@ -444,25 +449,32 @@ Do not make third-party plugins responsible for:
 
 Those are core invariants.
 
-## 4. Start with schema-driven UI contributions
+## 4. Plugins ship their own UI
 
-Arbitrary third-party React bundles inside the board UI are possible later, but they should not be the first version.
+Plugins ship their own React UI as a bundled module inside `dist/ui/`. The host loads plugin components into designated **extension slots** (pages, tabs, widgets, sidebar entries) and provides a **bridge** for the plugin frontend to talk to its own worker backend and to access host context.
 
-First version should let plugins contribute:
+**How it works:**
 
-- settings sections defined by JSON schema
-- dashboard widgets with server-provided data
-- sidebar entries with fixed shell rendering
-- detail-page tabs that render plugin data through core UI components
+1. The plugin's UI exports named components for each slot it fills (e.g. `DashboardWidget`, `IssueDetailTab`, `SettingsPage`).
+2. The host mounts the plugin component into the correct slot, passing a bridge object with hooks like `usePluginData(key, params)` and `usePluginAction(key)`.
+3. The plugin component fetches data from its own worker via the bridge and renders it however it wants.
+4. The host enforces capability gates through the bridge — if the worker doesn't have a capability, the bridge rejects the call.
 
-Why:
+**What the host controls:** where plugin components appear, the bridge API, capability enforcement, and shared UI primitives (`@paperclipai/plugin-sdk/ui`) with design tokens and common components.
 
-- simpler to secure
-- easier to keep visually coherent
-- easier to preserve context and auditability
-- easier to test
+**What the plugin controls:** how to render its data, what data to fetch, what actions to expose, and whether to use the host's shared components or build entirely custom UI.
 
-Later, if needed, Paperclip can support richer frontend extensions through versioned remote modules.
+First version extension slots:
+
+- dashboard widgets
+- settings pages
+- detail-page tabs (project, issue, agent, goal, run)
+- sidebar entries
+- company-context plugin pages
+
+The host SDK ships shared components (MetricCard, DataTable, StatusBadge, LogView, etc.) for visual consistency, but these are optional.
+
+Later, if untrusted third-party plugins become common, the host can move to iframe-based isolation without changing the plugin's source code (the bridge API stays the same).
 
 ## 5. Make installation global and keep mappings/config separate
 
@@ -500,6 +512,102 @@ In other words:
 - `project_workspace` is the local runtime anchor
 - plugins should build on that instead of creating an unrelated workspace model first
 
+## 7. Let plugins contribute agent tools
+
+`opencode` makes tools a first-class extension point. This is one of the highest-value surfaces for Paperclip too.
+
+A Linear plugin should be able to contribute a `search-linear-issues` tool that agents use during runs. A git plugin should contribute `create-branch` and `get-diff`. A file browser plugin should contribute `read-file` and `list-directory`.
+
+The key constraints:
+
+- plugin tools are namespaced by plugin ID (e.g. `linear:search-issues`) so they cannot shadow core tools
+- plugin tools require the `agent.tools.register` capability
+- tool execution goes through the same worker RPC boundary as everything else
+- tool results appear in run logs
+
+This is a natural fit — the plugin already has the SDK context, the external API credentials, and the domain logic. Wrapping that in a tool definition is minimal additional work for the plugin author.
+
+## 8. Support plugin-to-plugin events
+
+Plugins should be able to emit custom events that other plugins can subscribe to. For example, the git plugin detects a push and emits `plugin.@paperclip/plugin-git.push-detected`. The GitHub Issues plugin subscribes to that event and updates PR links.
+
+This avoids plugins needing to coordinate through shared state or external channels. The host routes plugin events through the same event bus with the same delivery semantics as core events.
+
+Plugin events use a `plugin.<pluginId>.*` namespace so they cannot collide with core events.
+
+## 9. Auto-generate settings UI from config schema
+
+Plugins that declare an `instanceConfigSchema` should get an auto-generated settings form for free. The host renders text inputs, dropdowns, toggles, arrays, and secret-ref pickers directly from the JSON Schema.
+
+For plugins that need richer settings UX, they can declare a `settingsPage` extension slot and ship a custom React component. Both approaches coexist.
+
+This matters because settings forms are boilerplate that every plugin needs. Auto-generating them from the schema that already exists removes a significant chunk of authoring friction.
+
+## 10. Design for graceful shutdown and upgrade
+
+The spec should be explicit about what happens when a plugin worker stops — during upgrades, uninstalls, or instance restarts.
+
+The recommended policy:
+
+- send `shutdown()` with a configurable deadline (default 10 seconds)
+- SIGTERM after deadline, SIGKILL after 5 more seconds
+- in-flight jobs marked `cancelled`
+- in-flight bridge calls return structured errors to the UI
+
+For upgrades specifically: the old worker drains, the new worker starts. If the new version adds capabilities, it enters `upgrade_pending` until the operator approves.
+
+## 11. Define uninstall data lifecycle
+
+When a plugin is uninstalled, its data (`plugin_state`, `plugin_entities`, `plugin_jobs`, etc.) should be retained for a grace period (default 30 days), not immediately deleted. The operator can reinstall within the grace period and recover state, or force-purge via CLI.
+
+This matters because accidental uninstalls should not cause irreversible data loss.
+
+## 12. Invest in plugin observability
+
+Plugin logs via `ctx.logger` should be stored and queryable from the plugin settings page. The host should also capture raw `stdout`/`stderr` from the worker process as fallback.
+
+The plugin health dashboard should show: worker status, uptime, recent logs, job success/failure rates, webhook delivery rates, and resource usage. The host should emit internal events (`plugin.health.degraded`, `plugin.worker.crashed`) that other plugins or dashboards can consume.
+
+This is critical for operators. Without observability, debugging plugin issues requires SSH access and manual log tailing.
+
+## 13. Ship a test harness and starter template
+
+A `@paperclipai/plugin-test-harness` package should provide a mock host with in-memory stores, synthetic event emission, and `getData`/`performAction`/`executeTool` simulation. Plugin authors should be able to write unit tests without a running Paperclip instance.
+
+A `create-paperclip-plugin` CLI should scaffold a working plugin with manifest, worker, UI bundle, test file, and build config.
+
+Low authoring friction was called out as one of `opencode`'s best qualities. The test harness and starter template are how Paperclip achieves the same.
+
+## 14. Support hot plugin lifecycle
+
+Plugin install, uninstall, upgrade, and config changes should take effect without restarting the Paperclip server. This is critical for developer workflow and operator experience.
+
+The out-of-process worker architecture makes this natural:
+
+- **Hot install**: spawn a new worker, register its event subscriptions, job schedules, webhook endpoints, and agent tools in live routing tables, load its UI bundle into the extension slot registry.
+- **Hot uninstall**: graceful shutdown of the worker, remove all registrations from routing tables, unmount UI components, start data retention grace period.
+- **Hot upgrade**: shut down old worker, start new worker, atomically swap routing table entries, invalidate UI bundle cache so the frontend loads the updated bundle.
+- **Hot config change**: write new config to `plugin_config`, notify the running worker via IPC (`configChanged`). The worker applies the change without restarting. If it doesn't handle `configChanged`, the host restarts just that worker.
+
+Frontend cache invalidation uses versioned or content-hashed bundle URLs and a `plugin.ui.updated` event that triggers re-import without a full page reload.
+
+Each worker process is independent — starting, stopping, or replacing one worker never affects any other plugin or the host itself.
+
+## 15. Define SDK versioning and compatibility
+
+`opencode` does not have a formal SDK versioning story because plugins run in-process and are effectively pinned to the current runtime. Paperclip's out-of-process model means plugins may be built against one SDK version and run on a host that has moved forward. This needs explicit rules.
+
+Recommended approach:
+
+- **Single SDK package**: `@paperclipai/plugin-sdk` with subpath exports — root for worker code, `/ui` for frontend code. One dependency, one version, one changelog.
+- **SDK major version = API version**: `@paperclipai/plugin-sdk@2.x` targets `apiVersion: 2`. Plugins built with SDK 1.x declare `apiVersion: 1` and continue to work.
+- **Host multi-version support**: The host supports at least the current and one previous `apiVersion` simultaneously with separate IPC protocol handlers per version.
+- **`sdkVersion` in manifest**: Plugins declare a semver range (e.g. `">=1.4.0 <2.0.0"`). The host validates this at install time.
+- **Deprecation timeline**: Previous API versions get at least 6 months of continued support after a new version ships. The host logs deprecation warnings and shows a banner on the plugin settings page.
+- **Migration guides**: Each major SDK release ships with a step-by-step migration guide covering every breaking change.
+- **UI surface versioned with worker**: Both worker and UI surfaces are in the same package, so they version together. Breaking changes to shared UI components require a major version bump just like worker API changes.
+- **Published compatibility matrix**: The host publishes a matrix of supported API versions and SDK ranges, queryable via API.
+
 ## A Concrete SDK Shape For Paperclip
 
 An intentionally narrow first pass could look like this:
@@ -510,13 +618,13 @@ import { definePlugin, z } from "@paperclipai/plugin-sdk";
 export default definePlugin({
   id: "@paperclip/plugin-linear",
   version: "0.1.0",
-  kind: ["connector", "ui"],
+  categories: ["connector", "ui"],
   capabilities: [
     "events.subscribe",
     "jobs.schedule",
     "http.outbound",
-    "instance.settings",
-    "dashboard.widget",
+    "instance.settings.register",
+    "ui.dashboardWidget.register",
     "secrets.read-ref",
   ],
   instanceConfigSchema: z.object({
@@ -534,28 +642,73 @@ export default definePlugin({
       // sync Linear issues into plugin-owned state or explicit Paperclip entities
     });
 
-    ctx.events.on("issue.created", async (event) => {
-      // optional outbound sync
+    // subscribe with optional server-side filter
+    ctx.events.on("issue.created", { projectId: "proj-1" }, async (event) => {
+      // only receives issue.created events for project proj-1
     });
 
-    ctx.ui.registerDashboardWidget({
-      id: "linear-health",
-      title: "Linear",
-      loader: async ({ companyId }) => ({ status: "ok" }),
+    // subscribe to events from another plugin
+    ctx.events.on("plugin.@paperclip/plugin-git.push-detected", async (event) => {
+      // react to the git plugin detecting a push
+    });
+
+    // contribute a tool that agents can use during runs
+    ctx.tools.register("search-linear-issues", {
+      displayName: "Search Linear Issues",
+      description: "Search for Linear issues by query",
+      parametersSchema: { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
+    }, async (params, runCtx) => {
+      // search Linear API and return results
+      return { content: JSON.stringify(results) };
+    });
+
+    // getData is called by the plugin's own UI components via the host bridge
+    ctx.data.register("sync-health", async ({ companyId }) => {
+      // return typed JSON that the plugin's DashboardWidget component renders
+      return { syncedCount: 142, trend: "+12 today", mappings: [...] };
+    });
+
+    ctx.actions.register("resync", async ({ companyId }) => {
+      // run sync logic
     });
   },
 });
 ```
 
+The plugin's UI bundle (separate from the worker) might look like:
+
+```tsx
+// dist/ui/index.tsx
+import { usePluginData, usePluginAction, MetricCard, ErrorBoundary } from "@paperclipai/plugin-sdk/ui";
+
+export function DashboardWidget({ context }: PluginWidgetProps) {
+  const { data, loading, error } = usePluginData("sync-health", { companyId: context.companyId });
+  const resync = usePluginAction("resync");
+
+  if (loading) return <Spinner />;
+  if (error) return <div>Plugin error: {error.message} ({error.code})</div>;
+
+  return (
+    <ErrorBoundary fallback={<div>Widget failed to render</div>}>
+      <MetricCard label="Synced Issues" value={data.syncedCount} trend={data.trend} />
+      <button onClick={() => resync({ companyId: context.companyId })}>Resync Now</button>
+    </ErrorBoundary>
+  );
+}
+```
+
 The important point is not the exact syntax.
 The important point is the contract shape:
 
 - typed manifest
 - explicit capabilities
 - explicit global config with optional company mappings
-- event subscriptions
+- event subscriptions with optional server-side filtering
+- plugin-to-plugin events via namespaced event types
+- agent tool contributions
 - jobs
-- additive UI contributions
+- plugin-shipped UI that communicates with its worker through the host bridge
+- structured error propagation from worker to UI
 
 ## Recommended Core Extension Surfaces
 
@@ -569,7 +722,6 @@ Candidates:
 - `registerStorageProvider()`
 - `registerSecretProvider()`
 - `registerRunLogStore()`
-- maybe `registerWorkspaceRuntime()` later
 
 These are trusted platform modules, not casual plugins.
 
@@ -596,9 +748,7 @@ Examples:
 
 ## 3. Workspace-runtime surfaces
 
-Your local-ops examples need first-party primitives plus plugin contributions.
-
-Examples:
+Workspace plugins handle local tooling directly:
 
 - file browser
 - terminal
@@ -606,42 +756,9 @@ Examples:
 - child process tracking
 - local dev server tracking
 
-These should not be arbitrary third-party code directly poking the host filesystem and PTY layer through ad-hoc hooks.
-Instead, Paperclip should add first-party services such as:
+Plugins resolve workspace paths through host APIs (`ctx.projects` provides workspace metadata including `cwd`, `repoUrl`, etc.) and then operate on the filesystem, spawn processes, shell out to `git`, or open PTY sessions using standard Node APIs or any libraries they choose.
 
-- project workspace service built on `project_workspaces`
-- PTY session service
-- process registry
-- git service
-- dev-server registry
-
-Then plugins can add:
-
-- UI panels on top of those services
-- automations
-- annotations
-- external sync logic
-
-This keeps sensitive local-machine behavior centralized and auditable.
-
-## 4. UI contribution surfaces
-
-Recommended first version:
-
-- dashboard widgets
-- settings panels
-- detail-page tabs
-- sidebar sections
-- action buttons that invoke plugin routes
-
-Recommended later version:
-
-- richer remote UI modules
-
-Recommended never or only with extreme caution:
-
-- arbitrary override of core pages
-- arbitrary replacement of routing/auth/layout logic
+The host does not wrap or proxy these operations. This keeps the core lean — no need to maintain a parallel API surface for every OS-level operation a plugin might need. Plugins own their own implementations.
 
 ## Governance And Safety Requirements
 
@@ -666,15 +783,16 @@ Every plugin declares a static capability set such as:
 - `issues.read`
 - `issues.write`
 - `events.subscribe`
+- `events.emit`
 - `jobs.schedule`
 - `http.outbound`
 - `webhooks.receive`
 - `assets.read`
 - `assets.write`
-- `workspace.pty`
-- `workspace.fs.read`
-- `workspace.fs.write`
 - `secrets.read-ref`
+- `agent.tools.register`
+- `plugin.state.read`
+- `plugin.state.write`
 
 The board/operator sees this before installation.
 
@@ -685,12 +803,10 @@ If it needs mappings over specific Paperclip objects, those are plugin data, not
 
 ## 3. Activity logging
 
-Plugin-originated mutations should flow through the same activity log mechanism, with actor identity like:
+Plugin-originated mutations should flow through the same activity log mechanism, with a dedicated `plugin` actor type:
 
-- `actor_type = system`
-- `actor_id = plugin:@paperclip/plugin-linear`
-
-or a dedicated `plugin` actor type if you want stronger semantics later.
+- `actor_type = plugin`
+- `actor_id = <plugin-id>` (e.g. `@paperclip/plugin-linear`)
 
 ## 4. Health and failure reporting
 
@@ -787,7 +903,7 @@ Suggested fields:
 - `id`
 - `package_name`
 - `version`
-- `kind`
+- `categories`
 - `manifest_json`
 - `installed_at`
 - `status`
@@ -801,7 +917,7 @@ Suggested fields:
 - `id`
 - `plugin_id`
 - `config_json`
-- `installed_at`
+- `created_at`
 - `updated_at`
 - `last_error`
 
@@ -886,16 +1002,16 @@ This is a useful middle ground:
 
 ## How The Requested Examples Map To This Model
 
-| Use case | Best fit | Core primitives needed | Notes |
+| Use case | Best fit | Host primitives needed | Notes |
 |---|---|---|---|
-| File browser | workspace plugin + schema UI | project workspaces, file API, audit rules | best anchored on project detail pages |
-| Terminal | workspace plugin + PTY service | project workspaces, PTY/session service, process limits, audit events | should launch against a project workspace by default |
-| Git workflow | workspace plugin | project workspaces, git service, repo/worktree model | project workspace is the natural repo anchor |
+| File browser | workspace plugin | project workspace metadata | plugin owns filesystem ops directly |
+| Terminal | workspace plugin | project workspace metadata | plugin spawns PTY sessions directly |
+| Git workflow | workspace plugin | project workspace metadata | plugin shells out to git directly |
 | Linear issue tracking | connector plugin | jobs, webhooks, secret refs, issue sync API | very strong plugin candidate |
 | GitHub issue tracking | connector plugin | jobs, webhooks, secret refs | very strong plugin candidate |
-| Grafana metrics | connector plugin + dashboard widget | outbound HTTP, widget API | probably read-only first |
-| Child process/server tracking | workspace plugin | project workspaces, process registry, server heartbeat model | should attach processes to project workspaces when possible |
-| Stripe revenue tracking | connector plugin | secret refs, scheduled sync, company metrics API | strong plugin candidate and aligns with future spec direction |
+| Grafana metrics | connector plugin + dashboard widget | outbound HTTP | probably read-only first |
+| Child process/server tracking | workspace plugin | project workspace metadata | plugin manages processes directly |
+| Stripe revenue tracking | connector plugin | secret refs, scheduled sync, company metrics API | strong plugin candidate |
 
 # Plugin Examples
 
@@ -965,25 +1081,17 @@ Recommended capabilities and extension points:
 - `ui.detailTab.register` for `project`, `issue`, and `agent`
 - `projects.read`
 - `project.workspaces.read`
-- `workspace.fs.read`
-- optional `workspace.fs.write`
-- `workspace.fs.stat`
-- `workspace.fs.search`
 - optional `assets.write`
 - `activity.log.write`
 
+The plugin resolves workspace paths through `ctx.projects` and handles all filesystem operations (read, write, stat, search, list directory) directly using Node APIs.
+
 Optional event subscriptions:
 
 - `events.subscribe(agent.run.started)`
 - `events.subscribe(agent.run.finished)`
 - `events.subscribe(issue.attachment.created)`
 
-Important constraint:
-
-- the plugin should never read arbitrary host paths directly
-- it should treat project workspaces as the canonical local file roots when a project is present
-- it should only use first-party workspace/file APIs that enforce approved workspace roots
-
 ## Workspace Terminal
 
 Package idea: `@paperclip/plugin-terminal`
@@ -1045,25 +1153,16 @@ Recommended capabilities and extension points:
 - `ui.detailTab.register` for `project`, `agent`, and `run`
 - `projects.read`
 - `project.workspaces.read`
-- `workspace.pty.open`
-- `workspace.pty.input`
-- `workspace.pty.resize`
-- `workspace.pty.terminate`
-- `workspace.pty.subscribe`
-- `workspace.process.read`
 - `activity.log.write`
 
+The plugin resolves workspace paths through `ctx.projects` and handles PTY session management (open, input, resize, terminate, subscribe) directly using Node PTY libraries.
+
 Optional event subscriptions:
 
 - `events.subscribe(agent.run.started)`
 - `events.subscribe(agent.run.failed)`
 - `events.subscribe(agent.run.cancelled)`
 
-Important constraint:
-
-- shell spawning must stay in a first-party PTY service
-- the plugin should orchestrate and render sessions, not spawn raw host processes by itself
-
 ## Git Workflow
 
 Package idea: `@paperclip/plugin-git`
@@ -1132,24 +1231,21 @@ Recommended capabilities and extension points:
 - `ui.action.register`
 - `projects.read`
 - `project.workspaces.read`
-- `workspace.git.status`
-- `workspace.git.diff`
-- `workspace.git.log`
-- `workspace.git.branch.create`
-- optional `workspace.git.commit`
-- optional `workspace.git.worktree.create`
-- optional `workspace.git.push`
+- optional `agent.tools.register` (e.g. `create-branch`, `get-diff`, `get-status`)
+- optional `events.emit` (e.g. `plugin.@paperclip/plugin-git.push-detected`)
 - `activity.log.write`
 
+The plugin resolves workspace paths through `ctx.projects` and handles all git operations (status, diff, log, branch create, commit, worktree create, push) directly using git CLI or a git library.
+
 Optional event subscriptions:
 
 - `events.subscribe(issue.created)`
 - `events.subscribe(issue.updated)`
 - `events.subscribe(agent.run.finished)`
 
-Important constraint:
+The git plugin can emit `plugin.@paperclip/plugin-git.push-detected` events that other plugins (e.g. GitHub Issues) subscribe to for cross-plugin coordination.
 
-- GitHub/GitLab PR creation should likely live in a separate connector plugin rather than overloading the local git plugin
+Note: GitHub/GitLab PR creation should likely live in a separate connector plugin rather than overloading the local git plugin.
 
 ## Linear Issue Tracking
 
@@ -1223,6 +1319,7 @@ Recommended capabilities and extension points:
 - optional `issues.create`
 - optional `issues.update`
 - optional `issue.comments.create`
+- optional `agent.tools.register` (e.g. `search-linear-issues`, `get-linear-issue`)
 - `activity.log.write`
 
 Important constraint:
@@ -1290,6 +1387,7 @@ Recommended capabilities and extension points:
 - `events.subscribe(issue.created)`
 - `events.subscribe(issue.updated)`
 - `events.subscribe(issue.comment.created)`
+- `events.subscribe(plugin.@paperclip/plugin-git.push-detected)` (cross-plugin coordination)
 - `jobs.schedule`
 - `webhooks.receive`
 - `http.outbound`
@@ -1303,7 +1401,7 @@ Recommended capabilities and extension points:
 
 Important constraint:
 
-- keep "local git state" and "remote GitHub issue state" in separate plugins even if they work together
+- keep "local git state" and "remote GitHub issue state" in separate plugins even if they work together — cross-plugin events handle coordination
 
 ## Grafana Metrics
 
@@ -1422,7 +1520,7 @@ Main screens and interactions:
 
 Core workflows:
 
-- An agent starts a dev server; the first-party process service registers it and the plugin renders it.
+- An agent starts a dev server; the plugin detects and tracks it.
 - Board opens a project and immediately sees the processes attached to that project's workspace.
 - Board sees a crashed process on the dashboard and restarts it from the plugin page.
 - Board attaches process logs to an issue when debugging a failure.
@@ -1438,28 +1536,16 @@ Recommended capabilities and extension points:
 - `ui.detailTab.register` for `project` and `agent`
 - `projects.read`
 - `project.workspaces.read`
-- `workspace.process.register`
-- `workspace.process.list`
-- `workspace.process.read`
-- optional `workspace.process.terminate`
-- optional `workspace.process.restart`
-- `workspace.process.logs.read`
-- optional `workspace.http.probe`
 - `plugin.state.read`
 - `plugin.state.write`
 - `activity.log.write`
 
+The plugin resolves workspace paths through `ctx.projects` and handles process management (register, list, terminate, restart, read logs, health probes) directly using Node APIs.
+
 Optional event subscriptions:
 
 - `events.subscribe(agent.run.started)`
 - `events.subscribe(agent.run.finished)`
-- `events.subscribe(process.started)`
-- `events.subscribe(process.exited)`
-
-Important constraint:
-
-- this should be built on a first-party process registry
-- the plugin should not own raw child-process spawning on its own
 
 ## Stripe Revenue Tracking
 
@@ -1519,7 +1605,7 @@ Recommended capabilities and extension points:
 - `secrets.read-ref`
 - `plugin.state.read`
 - `plugin.state.write`
-- `company.metrics.write`
+- `metrics.write`
 - optional `issues.create`
 - `activity.log.write`
 
@@ -1536,9 +1622,13 @@ Important constraint:
 - deterministic load order and precedence
 - very small authoring API
 - typed schemas for plugin inputs/config/tools
+- tools as a first-class plugin extension point (namespaced, not override-by-collision)
 - internal extensions using the same registration shapes as external ones when reasonable
 - plugin load errors isolated from host startup when possible
 - explicit community-facing plugin docs and example templates
+- test harness and starter template for low authoring friction
+- hot plugin lifecycle without server restart (enabled by out-of-process workers)
+- formal SDK versioning with multi-version host support
 
 ## Adapt, not copy
 
@@ -1577,7 +1667,19 @@ Build:
 - scheduled jobs
 - webhook endpoints
 - activity logging helpers
-- dashboard widget and settings-panel contributions
+- plugin UI bundle loading, host bridge, `@paperclipai/plugin-sdk/ui`
+- extension slot mounting for pages, tabs, widgets, sidebar entries
+- auto-generated settings form from `instanceConfigSchema`
+- bridge error propagation (`PluginBridgeError`)
+- plugin-contributed agent tools
+- plugin-to-plugin events (`plugin.<pluginId>.*` namespace)
+- event filtering (server-side, per-subscription)
+- graceful shutdown with configurable deadlines
+- plugin logging and health dashboard
+- uninstall with data retention grace period
+- `@paperclipai/plugin-test-harness` and `create-paperclip-plugin` starter template
+- hot plugin lifecycle (install, uninstall, upgrade, config change without server restart)
+- SDK versioning with multi-version host support and deprecation policy
 
 This phase would immediately cover:
 
@@ -1585,31 +1687,18 @@ This phase would immediately cover:
 - GitHub
 - Grafana
 - Stripe
-
-## Phase 2: Add workspace services and workspace plugins
-
-Build first-party primitives:
-
-- project workspace service built on `project_workspaces`
-- PTY/session service
-- file service
-- git service
-- process/service tracker
-
-Then expose additive plugin/UI surfaces on top.
-
-This phase covers:
-
 - file browser
 - terminal
 - git workflow
 - child process/server tracking
 
-## Phase 3: Consider richer UI and plugin packaging
+Workspace plugins do not require additional host APIs — they resolve workspace paths through `ctx.projects` and handle filesystem, git, PTY, and process operations directly.
 
-Only after phases 1 and 2 are stable:
+## Phase 2: Consider richer UI and plugin packaging
 
-- richer frontend extension support
+Only after Phase 1 is stable:
+
+- iframe-based isolation for untrusted third-party plugin UI bundles
 - signed/verified plugin packages
 - plugin marketplace
 - optional custom plugin storage backends or migrations
@@ -1623,8 +1712,14 @@ Paperclip should implement "a plugin platform with multiple trust tiers":
 
 - trusted platform modules for low-level runtime integration
 - typed out-of-process plugins for instance-wide integrations and automation
-- schema-driven UI contributions
+- plugin-contributed agent tools (namespaced, capability-gated)
+- plugin-shipped UI bundles rendered in host extension slots via a typed bridge with structured error propagation
+- plugin-to-plugin events for cross-plugin coordination
+- auto-generated settings UI from config schema
 - core-owned invariants that plugins can observe and act around, but not replace
+- plugin observability, graceful lifecycle management, and a test harness for low authoring friction
+- hot plugin lifecycle — no server restart for install, uninstall, upgrade, or config changes
+- SDK versioning with multi-version host support and clear deprecation policy
 
 That gets the upside of `opencode`'s extensibility without importing the wrong threat model.
 
@@ -1632,6 +1727,12 @@ That gets the upside of `opencode`'s extensibility without importing the wrong t
 
 1. Write a short extension architecture RFC that formalizes the distinction between `platform modules` and `plugins`.
 2. Introduce a small plugin manifest type in `packages/shared` and a `plugins` install/config section in the instance config.
-3. Build a typed domain event bus around existing activity/live-event patterns, but keep core invariants non-hookable.
-4. Implement connector-plugin MVP only: global install/config, secret refs, jobs, webhooks, settings panel, dashboard widget.
-5. Treat workspace features as a separate track that starts by building core workspace primitives, not raw plugin hooks.
+3. Build a typed domain event bus around existing activity/live-event patterns, with server-side event filtering and a `plugin.*` namespace for cross-plugin events. Keep core invariants non-hookable.
+4. Implement plugin MVP: global install/config, secret refs, jobs, webhooks, plugin UI bundles, extension slots, auto-generated settings forms, bridge error propagation.
+5. Add agent tool contributions — plugins register namespaced tools that agents can call during runs.
+6. Add plugin observability: structured logging via `ctx.logger`, health dashboard, internal health events.
+7. Add graceful shutdown policy and uninstall data lifecycle with retention grace period.
+8. Ship `@paperclipai/plugin-test-harness` and `create-paperclip-plugin` starter template.
+9. Implement hot plugin lifecycle — install, uninstall, upgrade, and config changes without server restart.
+10. Define SDK versioning policy — semver, multi-version host support, deprecation timeline, migration guides, published compatibility matrix.
+11. Build workspace plugins (file browser, terminal, git, process tracking) that resolve workspace paths from the host and handle OS-level operations directly.