@hachej/boring-workspace 0.1.41 → 0.1.43

package/dist/app-server.d.ts

@@ -116,10 +116,11 @@ interface CreateWorkspaceAgentServerOptions extends WorkspaceAgentCreateOptions,
     /**
      * Install and advertise the boring plugin-authoring runtime.
      *
-     * Keep this off for production/hosted workspaces unless a plugin-editing
-     * experience is explicitly enabled. Remote sandboxes can support authoring,
-     * but the CLI should be provisioned only for that activated editing mode,
-     * not for every normal workspace boot.
+     * This option is ignored when `externalPlugins` is false. Keep it off for
+     * production/hosted workspaces unless a plugin-editing experience is
+     * explicitly enabled. Remote sandboxes can support authoring, but the CLI
+     * should be provisioned only for that activated editing mode, not for every
+     * normal workspace boot.
      *
      * Defaults to true for local/standalone strong-filesystem runtimes and false
      * for remote/best-effort runtimes. Core/full-app may choose a stricter
@@ -128,6 +129,14 @@ interface CreateWorkspaceAgentServerOptions extends WorkspaceAgentCreateOptions,
     installPluginAuthoring?: boolean;
     /** Optional host-owned front-target override for boring plugin list/event payloads. */
     boringPluginFrontTargetResolver?: BoringPluginFrontTargetResolver;
+    /**
+     * Single public-mode switch for user/global external plugins. When false,
+     * the server disables .pi/~/.pi/Pi-settings discovery, authoring CLI/prompt
+     * provisioning, plugin diagnostics, and external hot-reload resources. App/
+     * internal plugins from explicit `plugins`, `defaultPluginPackages`, and
+     * `additionalBoringPluginDirs` continue to work.
+     */
+    externalPlugins?: boolean;
 }
 declare const PLUGIN_AUTHORING_PROVISIONING_IDS: Set<string>;
 declare function omitPluginAuthoringProvisioning(plugins: WorkspaceRuntimeProvisioningInput[]): WorkspaceRuntimeProvisioningInput[];
@@ -145,7 +154,9 @@ interface CollectWorkspaceAgentServerPluginsOptions extends Pick<ServerBootstrap
     /** Whether to include built-in boring plugin-authoring provisioning/prompt resources. */
     installPluginAuthoring?: boolean;
 }
-declare function buildWorkspaceContextPrompt(): string;
+declare function buildWorkspaceContextPrompt(options?: {
+    pluginAuthoringEnabled?: boolean;
+}): string;
 declare function collectWorkspaceAgentServerPlugins(opts?: CollectWorkspaceAgentServerPluginsOptions): WorkspaceAgentServerPluginCollection;
 declare function provisionWorkspaceAgentServer(opts: {
     workspaceRoot: string;

package/dist/app-server.js

@@ -1070,7 +1070,7 @@ var BoringPluginAssetManager = class {
       additionalSkillPaths: [...new Set(plugins.flatMap((plugin) => plugin.skillPaths ?? []).map(skillPathForPiLoader))],
       packages: compactPiPackages(normalizeBoringPluginPiPackages(plugins)),
       extensionPaths: plugins.flatMap((plugin) => plugin.extensionPaths ?? []),
-      ...prompts.length > 0 ? { systemPromptAppend: `# Loaded boring-ui plugin context
+      ...prompts.length > 0 ? { systemPromptAppend: `# Loaded app-provided context
 
 ${prompts.join("\n\n")}` } : {}
     };
@@ -1824,7 +1824,7 @@ async function runtimeBackendGateway(app, opts) {
 function aggregatePluginPrompts(manager) {
   const prompts = manager.list().map((plugin) => plugin.pi?.systemPrompt?.trim()).filter((prompt) => Boolean(prompt));
   if (prompts.length === 0) return void 0;
-  return `# Loaded boring-ui plugin context
+  return `# Loaded app-provided context
 
 ${prompts.join("\n\n")}`;
 }
@@ -2182,14 +2182,14 @@ function createExecUiTool(uiBridge, opts = {}) {
       "                          params:{seriesId:'GDPC1'}}}",
       "",
       "  openSurface  params: { kind: string, target: string, meta?: object }",
-      "               \u2014 Open a plugin-owned target through the workspace",
-      "                 surface resolver registry. Use this when a plugin",
+      "               \u2014 Open an app-owned target through the workspace",
+      "                 surface resolver registry. Use this when the app",
       "                 defines the mapping from domain target to panel",
       "                 component, for example a catalog row.",
       "                 Example: {kind:'openSurface', params:{",
-      "                          kind:'my-plugin.open-row',",
+      "                          kind:'catalog.open-row',",
       "                          target:'orders_daily',",
-      "                          meta:{catalogId:'my-plugin'}}}",
+      "                          meta:{catalogId:'data-catalog'}}}",
       "",
       "  closePanel   params: { id: string }",
       "  closeWorkbenchLeftPane params: {}",
@@ -2721,13 +2721,18 @@ function resolveBoringPiSkillPaths(workspaceRoot) {
   const skillFile = join7(root, "skills", "boring-plugin-authoring", "SKILL.md");
   return existsSync7(skillFile) ? [skillFile] : [];
 }
-function buildWorkspaceContextPrompt() {
+function buildWorkspaceContextPrompt(options = {}) {
   return [
     "## Workspace",
     "- Root: `$BORING_AGENT_WORKSPACE_ROOT` (exported into every bash invocation)",
-    "- Generated plugin skills: `$BORING_AGENT_WORKSPACE_ROOT/.boring-agent/skills/` \u2014 readable with normal file tools",
     "- User workspace skills: `$BORING_AGENT_WORKSPACE_ROOT/.agents/skills/`",
-    "- Runtime CLIs (`boring-ui-plugin`, `bm`, `python`, `pip`, `uv`) come from `.boring-agent/node`, `.boring-agent/venv`, and `.boring-agent/sdk/uv` and are already on PATH"
+    ...options.pluginAuthoringEnabled ? [
+      "- Generated plugin skills: `$BORING_AGENT_WORKSPACE_ROOT/.boring-agent/skills/` \u2014 readable with normal file tools",
+      "- Runtime CLIs (`boring-ui-plugin`, `bm`, `python`, `pip`, `uv`) come from `.boring-agent/node`, `.boring-agent/venv`, and `.boring-agent/sdk/uv` and are already on PATH"
+    ] : [
+      "- Runtime CLIs (`bm`, `python`, `pip`, `uv`) come from `.boring-agent/node`, `.boring-agent/venv`, and `.boring-agent/sdk/uv` when provisioned",
+      "- This public app does not expose Boring plugin creation or installation. If asked about Boring plugins, do not explain how to create/install them; say that this app does not expose that feature and continue with normal workspace tasks."
+    ]
   ].join("\n");
 }
 function collectWorkspaceAgentServerPlugins(opts = {}) {
@@ -2821,7 +2826,7 @@ function readPiSettingsBoringPluginSources(settingsPath, workspaceId) {
     }))
   );
 }
-function collectBoringPluginSources(workspaceRoot, pluginCollection, additionalPluginDirs = []) {
+function collectBoringPluginSources(workspaceRoot, pluginCollection, additionalPluginDirs = [], externalPluginsEnabled = true) {
   const extensionPaths = pluginCollection.agentOptions.pi?.extensionPaths ?? [];
   const pluginRoots = extensionPaths.flatMap((path) => {
     try {
@@ -2830,13 +2835,16 @@ function collectBoringPluginSources(workspaceRoot, pluginCollection, additionalP
       return [];
     }
   });
-  return uniquePluginSources([
+  const externalSources = externalPluginsEnabled ? [
     { rootDir: join7(workspaceRoot, ".pi", "extensions"), kind: "external", workspaceId: workspaceRoot },
     { rootDir: join7(workspaceRoot, ".pi", "npm"), kind: "external", workspaceId: workspaceRoot },
     { rootDir: join7(workspaceRoot, ".pi", "git"), kind: "external", workspaceId: workspaceRoot },
     { rootDir: join7(homedir(), ".pi", "agent", "extensions"), kind: "external" },
     ...readPiSettingsBoringPluginSources(join7(workspaceRoot, ".pi", "settings.json"), workspaceRoot),
-    ...readPiSettingsBoringPluginSources(join7(homedir(), ".pi", "agent", "settings.json")),
+    ...readPiSettingsBoringPluginSources(join7(homedir(), ".pi", "agent", "settings.json"))
+  ] : [];
+  return uniquePluginSources([
+    ...externalSources,
     ...pluginRoots.map((rootDir) => ({ rootDir, kind: "internal" })),
     ...additionalPluginDirs.map((entry) => typeof entry === "string" ? { rootDir: entry, kind: "internal" } : entry)
   ]);
@@ -2886,7 +2894,7 @@ function readWorkspacePluginPackageRuntimePlugins(pluginDirs) {
 function aggregatePluginSystemPromptsFromScan(scan) {
   const prompts = scan.plugins.map((plugin) => plugin.pi?.systemPrompt?.trim()).filter((prompt) => Boolean(prompt));
   if (prompts.length === 0) return void 0;
-  return `# Loaded boring-ui plugin context
+  return `# Loaded app-provided context
 
 ${prompts.join("\n\n")}`;
 }
@@ -2919,6 +2927,7 @@ async function createWorkspaceAgentServer(opts = {}) {
   const modeAdapter = opts.runtimeModeAdapter ?? resolveMode(resolvedMode);
   const workspaceFsCapability = modeAdapter.workspaceFsCapability ?? "best-effort";
   const validateUiPaths = opts.validateUiPaths ?? workspaceFsCapability === "strong";
+  const externalPluginsEnabled = opts.externalPlugins !== false;
   const uiTools = createWorkspaceUiTools(bridge, {
     workspaceRoot: validateUiPaths ? workspaceRoot : void 0
   });
@@ -2936,7 +2945,7 @@ async function createWorkspaceAgentServer(opts = {}) {
   const resolvedPlugins = await Promise.all(
     allPluginEntries.map((entry) => resolveOnePluginEntry(entry, ctx))
   );
-  const pluginAuthoringEnabled = (opts.installPluginAuthoring ?? workspaceFsCapability === "strong") && !(opts.excludeDefaults ?? []).includes("boring-ui-plugin-cli-package");
+  const pluginAuthoringEnabled = externalPluginsEnabled && (opts.installPluginAuthoring ?? workspaceFsCapability === "strong") && !(opts.excludeDefaults ?? []).includes("boring-ui-plugin-cli-package");
   const pluginCollection = collectWorkspaceAgentServerPlugins({
     ...opts,
     plugins: resolvedPlugins,
@@ -2956,7 +2965,7 @@ async function createWorkspaceAgentServer(opts = {}) {
   const refreshBoringPluginDirs = () => {
     const next = uniquePluginSources([
       ...defaultPluginPackagePaths.map((rootDir) => ({ rootDir, kind: "internal" })),
-      ...collectBoringPluginSources(workspaceRoot, pluginCollection, opts.additionalBoringPluginDirs)
+      ...collectBoringPluginSources(workspaceRoot, pluginCollection, opts.additionalBoringPluginDirs, externalPluginsEnabled)
     ]);
     boringPluginDirs.splice(0, boringPluginDirs.length, ...next);
     return boringPluginDirs;
@@ -3022,13 +3031,14 @@ async function createWorkspaceAgentServer(opts = {}) {
     ...opts,
     mode: resolvedMode,
     workspaceRoot,
+    externalPlugins: externalPluginsEnabled,
     extraTools: [
       ...opts.extraTools ?? [],
       ...uiTools,
       ...pluginCollection.agentOptions.extraTools ?? []
     ],
     systemPromptAppend: [
-      workspaceFsCapability === "strong" ? buildWorkspaceContextPrompt() : void 0,
+      workspaceFsCapability === "strong" ? buildWorkspaceContextPrompt({ pluginAuthoringEnabled }) : void 0,
       // `boring-ui-plugin` resolves via PATH from the provisioned workspace
       // runtime. It is the slim setup component for agent-authored plugins;
       // do not route plugin authoring through the full human-facing CLI.

package/dist/server.js

@@ -508,14 +508,14 @@ function createExecUiTool(uiBridge, opts = {}) {
       "                          params:{seriesId:'GDPC1'}}}",
       "",
       "  openSurface  params: { kind: string, target: string, meta?: object }",
-      "               \u2014 Open a plugin-owned target through the workspace",
-      "                 surface resolver registry. Use this when a plugin",
+      "               \u2014 Open an app-owned target through the workspace",
+      "                 surface resolver registry. Use this when the app",
       "                 defines the mapping from domain target to panel",
       "                 component, for example a catalog row.",
       "                 Example: {kind:'openSurface', params:{",
-      "                          kind:'my-plugin.open-row',",
+      "                          kind:'catalog.open-row',",
       "                          target:'orders_daily',",
-      "                          meta:{catalogId:'my-plugin'}}}",
+      "                          meta:{catalogId:'data-catalog'}}}",
       "",
       "  closePanel   params: { id: string }",
       "  closeWorkbenchLeftPane params: {}",
@@ -1700,7 +1700,7 @@ var BoringPluginAssetManager = class {
       additionalSkillPaths: [...new Set(plugins.flatMap((plugin) => plugin.skillPaths ?? []).map(skillPathForPiLoader))],
       packages: compactPiPackages(normalizeBoringPluginPiPackages(plugins)),
       extensionPaths: plugins.flatMap((plugin) => plugin.extensionPaths ?? []),
-      ...prompts.length > 0 ? { systemPromptAppend: `# Loaded boring-ui plugin context
+      ...prompts.length > 0 ? { systemPromptAppend: `# Loaded app-provided context
 
 ${prompts.join("\n\n")}` } : {}
     };
@@ -1968,7 +1968,7 @@ async function boringPluginRoutes(app, opts) {
 function aggregatePluginPrompts(manager) {
   const prompts = manager.list().map((plugin) => plugin.pi?.systemPrompt?.trim()).filter((prompt) => Boolean(prompt));
   if (prompts.length === 0) return void 0;
-  return `# Loaded boring-ui plugin context
+  return `# Loaded app-provided context
 
 ${prompts.join("\n\n")}`;
 }

package/dist/testing.js

@@ -1,7 +1,7 @@
 import { jsx as Ba } from "react/jsx-runtime";
 import * as Pa from "react";
 import { createElement as is, useMemo as wn, useLayoutEffect as us, isValidElement as ss, cloneElement as ds, useSyncExternalStore as Gi } from "react";
-import { h as cs, q as fs, o as ps } from "./WorkspaceProvider-B6P8ANTL.js";
+import { h as cs, q as fs, o as ps } from "./WorkspaceProvider-DkZAxsYo.js";
 import { d as ms } from "./panel-DnvDNQac.js";
 import * as bs from "react-dom/test-utils";
 import ka from "react-dom";

package/dist/workspace.js

@@ -1,17 +1,17 @@
 var V = Object.defineProperty;
 var X = (e, t, r) => t in e ? V(e, t, { enumerable: !0, configurable: !0, writable: !0, value: r }) : e[t] = r;
 var T = (e, t, r) => X(e, typeof t != "symbol" ? t + "" : t, r);
-import { u as K, p as Q, a as Y, b as Z, D as ee } from "./WorkspaceProvider-B6P8ANTL.js";
-import { A as Je, C as Ge, c as Ve, d as Xe, e as Qe, F as Ye, f as Ze, M as et, g as tt, P as rt, h as at, i as nt, j as st, k as ot, R as it, S as lt, l as ct, m as dt, T as ut, U as pt, W as ft, n as mt, o as ht, q as gt, r as bt, s as yt, t as vt, v as xt, w as kt, x as wt, y as Pt, z as St, B as Ct, E as Nt, G as Et, H as Rt, I as Tt, J as It, K as Ot, L as Ft, N as Lt, O as Mt, Q as Bt, V as Wt, X as Dt, Y as Kt, Z as $t, _ as jt, $ as zt, a0 as Ht, a1 as Ut, a2 as _t, a3 as qt, a4 as At, a5 as Jt, a6 as Gt, a7 as Vt, a8 as Xt, a9 as Qt, aa as Yt, ab as Zt, ac as er, ad as tr, ae as rr, af as ar, ag as nr, ah as sr, ai as or, aj as ir, ak as lr, al as cr, am as dr, an as ur, ao as pr, ap as fr, aq as mr, ar as hr, as as gr } from "./WorkspaceProvider-B6P8ANTL.js";
+import { u as K, p as Q, a as Y, b as Z, D as ee } from "./WorkspaceProvider-DkZAxsYo.js";
+import { A as Je, C as Ge, c as Ve, d as Xe, e as Qe, F as Ye, f as Ze, M as et, g as tt, P as rt, h as at, i as nt, j as st, k as ot, R as it, S as lt, l as ct, m as dt, T as ut, U as pt, W as ft, n as mt, o as ht, q as gt, r as bt, s as yt, t as vt, v as xt, w as kt, x as wt, y as Pt, z as St, B as Ct, E as Nt, G as Et, H as Rt, I as Tt, J as It, K as Ot, L as Ft, N as Lt, O as Mt, Q as Bt, V as Wt, X as Dt, Y as Kt, Z as $t, _ as jt, $ as zt, a0 as Ht, a1 as Ut, a2 as _t, a3 as qt, a4 as At, a5 as Jt, a6 as Gt, a7 as Vt, a8 as Xt, a9 as Qt, aa as Yt, ab as Zt, ac as er, ad as tr, ae as rr, af as ar, ag as nr, ah as sr, ai as or, aj as ir, ak as lr, al as cr, am as dr, an as ur, ao as pr, ap as fr, aq as mr, ar as hr, as as gr } from "./WorkspaceProvider-DkZAxsYo.js";
 import { c as C } from "./utils-B6yFEsav.js";
-import { C as yr, T as vr, W as xr, b as kr } from "./WorkspaceLoadingState-BdtTzpsu.js";
+import { C as yr, T as vr, W as xr, b as kr } from "./WorkspaceLoadingState-yp4vNmrT.js";
 import { jsx as a, jsxs as g, Fragment as te } from "react/jsx-runtime";
 import { Button as P, Sheet as re, SheetContent as ae, SheetHeader as ne, SheetTitle as se, SheetDescription as oe, EmptyState as ie, Kbd as I, ErrorState as le, IconButton as O } from "@hachej/boring-ui-kit";
 import { Toaster as Pr, dismissToast as Sr, toast as Cr } from "@hachej/boring-ui-kit";
 import { useSyncExternalStore as $, useState as N, useEffect as k, useRef as S, useCallback as b, useMemo as w, Suspense as ce, Component as de } from "react";
 import { C as Er, c as Rr } from "./CodeEditor-DQqOn4xz.js";
-import { FileTree as Ir } from "./FileTree-CdvCFi6P.js";
-import { MarkdownEditor as Fr } from "./MarkdownEditor-D6W7J3qC.js";
+import { FileTree as Ir } from "./FileTree-CVsvICGP.js";
+import { MarkdownEditor as Fr } from "./MarkdownEditor-BvaGmzWP.js";
 import { MenuIcon as ue, PanelLeftOpenIcon as pe, PanelLeftCloseIcon as fe, PinIcon as me, CheckIcon as he, CopyIcon as ge } from "lucide-react";
 import { d as Mr } from "./panel-DnvDNQac.js";
 function We() {

package/docs/INTERFACES.md

@@ -1,6 +1,6 @@
 # Workspace Interfaces
 
-Last updated: 2026-05-02
+Last updated: 2026-06-12
 
 `@hachej/boring-workspace` is a workspace UI and bridge package. The app shell owns
 auth, routing, application persistence, and the concrete chat component.

package/docs/PLUGIN_STRUCTURE.md

@@ -1,9 +1,9 @@
 # Plugin Structure
 
 Canonical quick reference for boring-ui plugin layouts. For the full current
-contract, see [`PLUGIN_SYSTEM.md`](./PLUGIN_SYSTEM.md). For future hosted/runtime
-architecture, see the repo-level
-[`docs/runtime-plugin-v2-hot-reload-plan.md`](../../../docs/runtime-plugin-v2-hot-reload-plan.md).
+contract, see [`PLUGIN_SYSTEM.md`](./PLUGIN_SYSTEM.md). For the historical
+hosted/runtime architecture exploration, see the archived repo-level
+[`docs/plans/archive/runtime-plugin-v2-hot-reload-plan.md`](../../../docs/plans/archive/runtime-plugin-v2-hot-reload-plan.md).
 
 ## Generated/runtime plugin
 

package/docs/PLUGIN_SYSTEM.md

@@ -6,8 +6,9 @@ example `PLUGIN_SYSTEM.md §4.5`), so keep headings stable when editing.
 
 This document describes the implementation as it exists now. Historical
 implementation plans live under `packages/workspace/docs/plans/archive/`.
-For future generated/hosted runtime-plugin architecture, see the repo-level
-`docs/runtime-plugin-v2-hot-reload-plan.md`.
+For the historical generated/hosted runtime-plugin architecture exploration,
+see the archived repo-level
+`docs/plans/archive/runtime-plugin-v2-hot-reload-plan.md`.
 
 ## Contents
 
@@ -27,7 +28,7 @@ For future generated/hosted runtime-plugin architecture, see the repo-level
 | Term | Definition |
 | --- | --- |
 | **App/internal plugin** | Trusted package composed by the app at boot. May export `boring.server`, Fastify routes, agent tools, providers, catalogs, and domain APIs. Server changes require restart/redeploy. |
-| **Runtime/generated plugin** | Workspace-local plugin under `.pi/extensions/<id>/`, usually produced by `boring-ui-plugin scaffold`. It is hot-loaded for front/Pi resources, but must not rely on dynamic backend routes. |
+| **Runtime/generated plugin** | Workspace-local plugin under `.pi/extensions/<id>/`, usually produced by `boring-ui-plugin scaffold`. Also called an **external** plugin in trust-model terms. It is hot-loaded for front/Pi resources, but must not rely on dynamic backend routes. |
 | **Boring plugin package** | Node package with `package.json#boring` and/or `package.json#pi`. App-default packages are declared in `package.json#boring.defaultPluginPackages` or passed to `createWorkspaceAgentServer`. |
 | **Boring front factory** | Default export of `boring.front`: `(api: BoringFrontAPI) => void | Promise<void>`. Usually created with `definePlugin({ ... })`. |
 | **Workspace server plugin** | Trusted boot-time server contribution returned by `defineServerPlugin({ ... })` or a compatible object. May include routes, tools, system prompt, Pi resources, and provisioning. |
@@ -35,6 +36,25 @@ For future generated/hosted runtime-plugin architecture, see the repo-level
 | **Revision** | Per-plugin monotonic integer. It bumps on signature changes and is appended to browser front imports for cache busting. |
 | **Surface resolver** | Front contribution that maps a typed request such as `open-path` to a panel id/title/params. File opens should route through this path. |
 
+### 1.1 Trust model (internal vs external)
+
+The two tiers differ by **provenance and trust**, not just lifecycle:
+
+| | App/internal plugin | Runtime/generated ("external") plugin |
+| --- | --- | --- |
+| Provenance | App-owned package, composed at boot | Workspace-local `.pi/extensions/`, often agent-generated |
+| Trust | Trusted app module | Trusted **only** as local developer/workspace code |
+| Front | Native React in the host tree | Native React (local trusted context) |
+| Server/routes/tools | Full power: Fastify routes, static `agentTools`, providers, domain APIs | Route-free; no `boring.server`; backend work goes through Pi tools |
+| Reload | Restart/redeploy | `/reload` hot-swaps front + Pi resources |
+
+Plugin tools' `execute()` run in the **host Node process and bypass the
+sandbox by design**; plugin loading is local-mode-only (skipped under
+`vercel-sandbox`). Hosted/marketplace plugins — untrusted external code that
+would need iframe fronts and sandbox-proxied tools — are **not implemented**;
+that provenance/permission model is a future phase (see §7 and the archived
+repo-level `docs/plans/archive/runtime-plugin-trust-modes-plan.md`).
+
 ---
 
 ## 2. End-to-end behaviour
@@ -241,6 +261,27 @@ boring-ui-plugin verify <name>
 Do not teach agents to copy `packages/plugin-cli/templates/plugin` for generated runtime
 plugins. That template is an app/internal publishable package example.
 
+### 4.7 Chat slash commands
+
+Plugins can contribute **chat `/slash` commands** — a separate surface from the
+command-palette `commands` output. There is no `!` bang-command; the composer
+parses `/name args` only.
+
+- **Front registry** (`packages/agent/src/front/slashCommands/registry.ts`):
+  `SlashCommand { name, description, kind?, source?, sourcePlugin?, handler }`.
+  `kind: 'local'` runs in the browser; `kind: 'skill'` is forwarded to the Pi
+  agent as `skill: <name>\n\n<args>`. The chat composer (`PiChatPanel`)
+  intercepts `/` input before it reaches the harness.
+- **Server commands** are listed from the harness via
+  `GET /api/v1/agent/commands` (consumed by `useServerCommands`) and executed
+  via `POST /api/v1/agent/commands/execute` — this route **bypasses the
+  harness chat loop**; Pi executes the command natively. `source`
+  (`extension`/`prompt`/`skill`) and `sourcePlugin` tag where a command came
+  from in the picker.
+- **How a plugin contributes one**: ship a Pi extension/prompt/skill in its
+  `package.json#pi` block — Pi-sourced commands appear automatically. No
+  harness changes required.
+
 ---
 
 ## 5. Key algorithms
@@ -327,7 +368,8 @@ while capturing the front factory.
   plugin RPC for purity.
 - Dynamic provider/binding trees for runtime hot-loaded plugins in this PR.
 - Marketplace signing/provenance/permissions. Those belong to the next runtime
-  plugin architecture phase.
+  plugin architecture phase. Promotion (external → internal) is designed as an
+  explicit admin action with pinned provenance + restart — not implemented yet.
 
 ---
 

package/docs/README.md

@@ -1,24 +1,87 @@
 # Workspace Docs
 
-Current package docs live here. Active ownership plans stay in `docs/plans/`.
-Older implementation plans live in `docs/plans/archive/`.
-
-## Current References
-
-- `PLUGIN_SYSTEM.md` - current normative spec for the plugin / agent layer:
-  package manifest fields, public API for front + server authoring,
-  hot-reload coverage table, prompt-location guidance, and key algorithms.
-  Code cites it as `Per PLUGIN_SYSTEM.md §X`.
-- `PLUGIN_STRUCTURE.md` - quick layout guide for generated/runtime plugins vs
-  app/internal publishable package plugins.
-- `INTERFACES.md` - package boundaries and public abstractions.
-- `plans/PLUGIN_OUTPUTS_ISOLATION_PLAN.md` - latest plugin ownership plan.
-- `plans/UI_BRIDGE_OWNERSHIP_REFACTOR.md` - UI bridge ownership decision.
-- `plans/archive/` - superseded implementation plans.
-
-## Rules
-
-- Keep root package markdown to `README.md` and `CHANGELOG.md`.
-- Prefer short current-reference docs over long status reports.
-- Move old plans into `plans/archive/` instead of keeping them beside active
-  ownership plans.
+`@hachej/boring-workspace` is the workspace UI, layout, plugin, and bridge layer
+for boring-ui apps. It composes chat, files, catalogs, editors, and app-specific
+panes into an IDE-style workbench. The app shell owns auth, routing, persistence,
+and the concrete chat component; the workspace owns the layout runtime, the
+plugin registries, and the typed agent-to-browser bridge.
+
+This folder holds the current normative docs. Read this index first, then jump to
+the doc that matches your task.
+
+## Architecture at a glance
+
+- **Layout runtime** — Dockview-based panes (`IdeLayout`, `ChatLayout`,
+  `ResponsiveDockviewShell`) mounted by `WorkspaceProvider`. Panels open in the
+  center/right/bottom; left-tabs stay docked in the sidebar.
+- **Plugin host** — `WorkspaceProvider` runs `bootstrap(plugins)` to populate the
+  panel, command, catalog, and surface-resolver registries. Lazy panel factories
+  are auto-wrapped in `React.lazy + Suspense + ErrorBoundary`.
+- **UI bridge** — Agents/servers post `UiCommand` values (`src/shared/ui-bridge.ts`);
+  the front-end dispatches them against the workspace runtime over SSE with an
+  HTTP poll fallback.
+- **Surface resolvers** — Decouple agent "open X" requests from concrete panel
+  ids. A `SurfaceOpenRequest { kind, target, meta }` is resolved by plugin
+  surface resolvers into panel openings (`src/shared/types/surface.ts`).
+- **Two plugin tiers** — App/internal package plugins (trusted, boot-time, may add
+  routes/agent tools/Pi resources) and runtime/generated `.pi/extensions` plugins
+  (a.k.a. *external* plugins: hot-reloaded for front/Pi, route-free, and loaded
+  only in local/direct-style host runtime contexts — not `vercel-sandbox`). See
+  `PLUGIN_SYSTEM.md` §1.1 for the trust model.
+
+## Key abstractions
+
+| Abstraction | Where | What it is |
+| --- | --- | --- |
+| `WorkspaceProvider` | `src/front/provider` | Root provider; boots plugins, layout, bridge. |
+| `definePlugin()` | `@hachej/boring-workspace/plugin` | Declarative front plugin: panels, leftTabs, commands, catalogs, bindings, providers, surfaceResolvers. |
+| `defineServerPlugin()` | `@hachej/boring-workspace/server` | Trusted boot-time server plugin: routes, agent tools, system prompt, Pi packages, provisioning. |
+| `PaneProps<T>` | `src/shared/types/panel.ts` | Props every panel/left-tab component receives (`params`, `api`, `containerApi`). |
+| `UiCommand` / `UiBridge` | `src/shared/ui-bridge.ts` | Typed agent→browser command contract. |
+| `SurfaceOpenRequest` | `src/shared/types/surface.ts` | Domain open request resolved to a panel. |
+| `BoringPluginAssetManager` | `src/server/agentPlugins` | Scans plugin dirs, hashes signatures, emits load/unload/error events, backs `/api/v1/agent-plugins`. |
+
+## Architectural decisions
+
+- **App shell owns auth/routing/persistence/chat; workspace owns chrome.** Keeps
+  the workspace package reusable and the chat component injected, not hardcoded.
+- **Front/shared workspace code does not value-import `@hachej/boring-agent`.** The
+  dependency is inverted via the injected `chatPanel`, so the workbench builds and
+  ships without the agent package. Only `src/app/*` composition may import
+  documented agent server APIs.
+- **Agents open domain targets through `openSurface`, not `openPanel`.** Surface
+  resolvers map requests to panels so workspace chrome never hardcodes plugin
+  panel ids or domain rules. Use `openPanel` only when the caller intentionally
+  names a concrete panel.
+- **Plugin data APIs live under the owning plugin.** There is no shared
+  `front/data` compatibility layer; e.g. the filesystem client/hooks/events are
+  plugin-owned (`src/plugins/filesystemPlugin/front/data`).
+- **Generated runtime plugins stay route-free; server changes are boot-time only.**
+  `/reload` refreshes front/Pi resources and tolerates per-plugin failures, but
+  does not hot-wire Fastify routes or agent tools. Server-file drift surfaces a
+  `requiresRestart` warning.
+- **Chat-first boot.** `WorkspaceAgentFront` mounts immediately while readiness
+  warms in the background; workbench surfaces are locally gated by warmup state.
+- **Style isolation.** Workspace owns public `--boring-*` tokens and Tailwind base
+  reset; agent consumes them under `[data-boring-agent]`. See
+  [`docs/TAILWIND-V4-STYLE-ISOLATION.md`](../../../docs/TAILWIND-V4-STYLE-ISOLATION.md).
+
+## Docs
+
+Authoring:
+- [`PLUGIN_STRUCTURE.md`](./PLUGIN_STRUCTURE.md) — quick layout guide for
+  generated/runtime plugins vs app/internal publishable package plugins.
+- [`PLUGIN_SYSTEM.md`](./PLUGIN_SYSTEM.md) — normative spec for the plugin/agent
+  layer: manifest fields, front + server authoring API, hot-reload coverage,
+  and key algorithms. Code and tests cite it as `Per PLUGIN_SYSTEM.md §X`, so its
+  section numbering is stable.
+
+Boundaries / contracts:
+- [`INTERFACES.md`](./INTERFACES.md) — package boundaries, core contracts, and
+  ownership rules across `src/front`, `src/server`, `src/shared`, `src/plugins`,
+  and `src/app`.
+
+History:
+- [`plans/archive/`](./plans/archive/) — superseded implementation plans and specs
+  kept for historical context. Not normative; current behavior is described in the
+  docs above and verified against source.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-workspace",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "type": "module",
   "license": "MIT",
   "description": "Workspace UI, plugin, and bridge package for composing chat, files, catalogs, editors, and app-specific panes.",
@@ -135,9 +135,9 @@
     "tailwind-merge": "^2.0.0",
     "zod": "^3.23.0",
     "zustand": "^5.0.0",
-    "@hachej/boring-agent": "0.1.41",
-    "@hachej/boring-ui-plugin-cli": "0.1.41",
-    "@hachej/boring-ui-kit": "0.1.41"
+    "@hachej/boring-ui-kit": "0.1.43",
+    "@hachej/boring-agent": "0.1.43",
+    "@hachej/boring-ui-plugin-cli": "0.1.43"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.0.0",