@hachej/boring-workspace 0.1.17 → 0.1.20

package/docs/INTERFACES.md

@@ -2,7 +2,7 @@
 
 Last updated: 2026-05-02
 
-`@boring/workspace` is a workspace UI and bridge package. The app shell owns
+`@hachej/boring-workspace` is a workspace UI and bridge package. The app shell owns
 auth, routing, application persistence, and the concrete chat component.
 Workspace owns layout runtime, layout preferences, plugin registries, bridge
 commands, and default workspace plugins.
@@ -19,16 +19,17 @@ commands, and default workspace plugins.
   and no agent package imports.
 - `src/app/` hosts front/server composition helpers such as
   `WorkspaceAgentFront` and `createWorkspaceAgentServer`, where workspace app
-  code may compose with documented `@boring/agent/server` APIs.
+  code may compose with documented `@hachej/boring-agent/server` APIs.
 
 ## Core Contracts
 
-- Plugin outputs: `src/shared/plugins/types.ts`
-  - `panel`, `left-tab`, `command`, `catalog`, `binding`, `provider`,
-    `surface-resolver`, and `agent-tool`.
+- Plugin contributions: `src/shared/plugins/frontFactory.ts`
+  - Front plugins are authored with `definePlugin({ panels, leftTabs, commands,
+    catalogs, bindings, providers, surfaceResolvers })`. Agent tools belong to
+    Pi/server runtime paths, not front plugin contributions.
 - Surface opening: `src/shared/types/surface.ts`
   - `SurfaceOpenRequest { kind, target, meta }` is resolved by plugin
-    `surface-resolver` outputs into panel openings.
+    surface resolvers into panel openings.
 - UI bridge: `src/shared/ui-bridge.ts`
   - Agents and servers post `UiCommand` values. The front-end dispatches them
     against the workspace runtime.
@@ -42,8 +43,7 @@ commands, and default workspace plugins.
 - Server plugins: `src/server/plugins`
   - `defineServerPlugin()` validates tools, routes, provisioning, and native Pi
     package declarations.
-  - `composeServerPlugins()` combines smaller server plugin fragments.
-  - `piPackages` are passed to `@boring/agent` as in-memory Pi settings, so
+  - `piPackages` are passed to `@hachej/boring-agent` as in-memory Pi settings, so
     workspace adapters can depend on native Pi packages without requiring
     Boring-specific exports from those packages.
 
@@ -54,5 +54,5 @@ commands, and default workspace plugins.
   compatibility layer.
 - Use `openSurface` for domain targets that need resolver selection.
 - Use `openPanel` only when the caller intentionally names the concrete panel.
-- Front/shared workspace code does not value-import `@boring/agent`; app/server
+- Front/shared workspace code does not value-import `@hachej/boring-agent`; app/server
   composition may import documented agent server APIs.

package/docs/PLUGIN_STRUCTURE.md

@@ -1,162 +1,56 @@
-# Workspace Plugin Structure
+# Plugin Structure
 
-Last updated: 2026-05-01
+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).
 
-Workspace plugins use a small, predictable folder shape. The goal is
-ownership clarity, not ceremony: plugin domain behavior stays in the plugin,
-and workspace core stays a generic host.
+## Generated/runtime plugin
 
-See `INTERFACES.md` for the package-level contracts these plugins contribute
-to.
+Use the workspace-local CLI from inside the agent/runtime workspace:
 
-## Standard Layout
-
-Start from `packages/workspace/templates/plugin/` when creating a new plugin,
-then delete the files the plugin does not need.
-
-```txt
-<plugin>/
-  front/
-    index.tsx            # front plugin factory and public front exports
-    panels.tsx           # panel definitions
-    catalogs.ts          # catalog outputs/config helpers
-    surfaceResolver.ts   # openSurface target -> panel resolution
-    bindings.tsx         # React side-effect bindings, if needed
-    data/                # plugin-owned client data API/hooks/cache
-  server/
-    index.ts             # server plugin factory and public server exports
-    tools.ts             # agent tools, if needed
-    routes.ts            # server routes, if needed
-  shared/
-    constants.ts         # plugin id, catalog ids, surface kinds
-    types.ts             # platform-neutral shared types, if needed
-```
-
-Use only the files a plugin actually needs. Large component families may live
-in subfolders such as `file-tree/`, `code-editor/`, or `empty-file-panel/`.
-
-## Ownership Rules
-
-- `front/index.tsx` composes front outputs; large behavior belongs in focused files.
-- `server/index.ts` composes server outputs with `defineServerPlugin()`.
-- Shared files must stay platform-neutral. Do not import plugin `front/` or
-  `server/` code from `shared/`.
-- Domain search belongs in `front/catalogs.ts`.
-- Domain open behavior belongs in `front/surfaceResolver.ts`.
-- Domain event names live in `shared/events.ts` when both layers need the
-  contract; event names must be keyed by plugin id.
-- Plugin data clients/hooks live in `front/data/`, not package `front/data`.
-- Server prompts/tools/routes/provisioning live under `server/`, not mixed
-  with client code.
-- Workspace core may host registries, providers, event transport, and bridge
-  dispatch only. It must not hardcode plugin panel ids or plugin domain rules.
-- Catalog selection and plugin-owned routing should prefer `openSurface`.
-  `openPanel` remains available for explicit app-level panel opens.
-- Executable agent tools should be server plugin contributions. The legacy
-  front `agentTools` field remains for migration only.
-
-## Composed Plugins
-
-Use `composePlugins()` when a front plugin is easier to build from smaller
-front fragments. The composed plugin flattens child panels, commands,
-catalogs, bindings, and outputs into one normal `WorkspaceFrontPlugin`.
-
-Default behavior adopts child ownership to the parent plugin id. Use
-`adoptOutputs: false` only when registry ownership must stay attached to the
-child fragment for diagnostics or selective unregister behavior.
-
-```ts
-const macroPlugin = composePlugins({
-  id: "boring-macro",
-  label: "Macro",
-  plugins: [macroPanelsPlugin, macroSurfacesPlugin, macroSeriesExplorerPlugin],
-})
+```bash
+boring-ui scaffold-plugin <name>
+boring-ui verify-plugin <name>
 ```
 
-Use `composeServerPlugins()` for the matching server side. It concatenates
-child tools, prompt text, pi package declarations, provisioning, and routes
-into one normal `WorkspaceServerPlugin`.
+Default shape:
 
-```ts
-const macroServerPlugin = composeServerPlugins({
-  id: "boring-macro",
-  label: "Macro",
-  plugins: [macroToolsPlugin, macroRoutesPlugin],
-})
+```txt
+.pi/extensions/<name>/
+  package.json          # boring.front and/or pi.*; no boring.server by default
+  front/index.tsx       # default-export definePlugin({ ... })
+  README.md
 ```
 
-## Pi Package Adapters
+Generated plugins are hot-reloaded with `/reload` for front/Pi resources. They
+should stay route-free: no `server/index.ts`, no Fastify routes, and no dynamic
+backend registration.
 
-Treat pi packages as implementation dependencies. The app-facing contract is a
-workspace adapter plugin that wraps the pi package and optionally adds front
-integration.
+## App/internal publishable package plugin
 
-Do not require pi packages to export Boring-specific adapters. The pi ecosystem
-already has its own shape, such as `package.json` `pi.extensions` entries and
-extension functions that call `pi.registerCommand(...)`. Workspace adapters
-should adapt to that shape.
-
-Declare native pi package dependencies on the server plugin:
-
-```ts
-defineServerPlugin({
-  id: "markdown-preview",
-  piPackages: ["npm:pi-markdown-preview@0.9.7"],
-})
-```
-
-Workspace passes these declarations to `@boring/agent` as in-memory Pi
-settings. This enables Pi's native package loader without mutating
-`.pi/settings.json`.
+Use [`packages/cli/templates/plugin`](../../../packages/cli/templates/plugin/) as the reference
+shape when building a trusted package composed by an app shell:
 
 ```txt
-src/plugins/markdownPreview/
-  shared/
-    constants.ts        # workspace ids, surface kinds, command names
-  server/
-    index.ts            # defineServerPlugin(), pi package dependency wrapper
-    routes.ts           # optional workspace-native render/preview routes
-  front/
-    index.tsx           # defineFrontPlugin()
-    panels.tsx          # workspace-native preview panel
-    surfaceResolver.ts  # markdown-preview.open -> panel resolution
+plugins/<name>/
+  package.json          # boring.front + optional boring.server
+  src/front/index.ts    # definePlugin({ ... })
+  src/server/index.ts   # defineServerPlugin({ ... }) when needed
+  src/shared/*          # browser-safe shared constants/types
+  tsup.config.ts
+  vitest.config.ts
 ```
 
-For example, a wrapper around `pi-markdown-preview` can depend on that package,
-read or invoke its pi extension behavior on the server side, and expose a
-workspace-native `markdown-preview.open` surface on the front side. The agent
-prompt should teach the model to use workspace `openSurface` when a Boring app
-is present, even if the underlying pi package also provides terminal/browser
-slash commands.
-
-
-## Current Plugins
-
-- `packages/workspace/src/plugins/filesystemPlugin`
-- Data catalog package: `@hachej/boring-data-catalog` (`plugins/data-catalog/src`)
-- `apps/workspace-playground/src/plugins/playgroundDataCatalog`
-- Macro plugin example: `hachej/boring-macro` (`src/plugins/macro`)
-
-## Invariants
-
-Run:
-
-```sh
-pnpm --filter @boring/workspace run lint:plugin-invariants
-```
+App/internal plugins may expose boot-time server contributions such as routes,
+agent tools, system prompts, provisioning, and Pi resources. Server changes
+require restarting the workspace process.
 
-The scan rejects:
+## Import boundaries
 
-- `filePatterns`, `fileFallback`, `PanelRegistry.resolve`, and file-handler
-  routing metadata in source.
-- `front/data` imports or path references in source.
-- `@boring/agent` imports from `workspace/src/shared/plugins`.
-- `front`/`server` imports from production `workspace/src/shared/plugins`.
-- Production plugin `front/`, `server/`, and `shared/` layers importing across
-  the wrong layer boundary.
-- TypeScript source files directly under a plugin root instead of
-  `front/`, `server/`, or `shared/`.
-- Plugin-domain imports from production `workspace/src/front/chrome`, `events`,
-  and `hooks`.
-- Legacy plugin file names such as `catalog.ts`, `surfaceTargets.ts`,
-  root-level `client.ts`, or root-level `server.ts`.
+- Front plugin code imports from `@hachej/boring-workspace/plugin`.
+- Trusted server plugin code imports from `@hachej/boring-workspace/server`.
+- App shells use `@hachej/boring-workspace/app/front` and
+  `@hachej/boring-workspace/app/server`.
+- Runtime/generated plugins should avoid broad host/workspace internals and use
+  documented primitives only.

package/docs/PLUGIN_SYSTEM.md

@@ -0,0 +1,355 @@
+# Plugin / Agent Layer
+
+Normative spec for `@hachej/boring-workspace`'s current plugin + agent
+layer. Code comments and tests cite section numbers in this file (for
+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`.
+
+## Contents
+
+1. [Glossary](#1-glossary)
+2. [End-to-end behaviour](#2-end-to-end-behaviour)
+3. [Architecture](#3-architecture)
+4. [Public API](#4-public-api)
+5. [Key algorithms](#5-key-algorithms)
+6. [Gotchas](#6-gotchas)
+7. [Non-goals](#7-non-goals)
+8. [Risk register](#8-risk-register)
+
+---
+
+## 1. Glossary
+
+| 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 scaffold-plugin`. 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. |
+| **Asset manager** | `BoringPluginAssetManager`. Scans plugin dirs, computes signatures, tracks revisions, emits `boring.plugin.{load,unload,error}` events, and backs `/api/v1/agent-plugins`. |
+| **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. |
+
+---
+
+## 2. End-to-end behaviour
+
+### App/internal package plugin
+
+1. App installs or references a plugin package.
+2. App declares it through `defaultPluginPackages`, `appPackageJsonPath`, or
+   explicit `plugins` passed to `createWorkspaceAgentServer`.
+3. Workspace resolves the package at boot.
+4. `boring.front` is exposed through the asset manager and front hot-load
+   path in dev.
+5. `boring.server` is imported and boot-composed once; routes and agent
+   tools are registered with the Fastify/agent process.
+6. Server changes require process restart. `/reload` may diagnose the drift,
+   but it does not rewire routes/tools in-place.
+
+### Runtime/generated plugin
+
+1. Agent/user runs the workspace-local CLI:
+
+   ```bash
+   boring-ui scaffold-plugin <name>
+   boring-ui verify-plugin <name>
+   ```
+
+2. The plugin lives under `.pi/extensions/<name>/`.
+3. `/reload` scans plugin manifests, refreshes Pi resources, and emits SSE
+   load/unload/error events.
+4. Browser dynamic-imports `boring.front` with revision + salt query params
+   and atomically replaces that plugin's registry entries.
+5. Previous working UI remains live when a front import/register fails.
+6. Generated plugins should omit `boring.server`; backend-like work should use
+   Pi extensions/tools today and future brokered sandbox tools/RPC later.
+
+---
+
+## 3. Architecture
+
+```
+App package.json / createWorkspaceAgentServer options
+        │
+        ▼
+resolve default plugin package dirs + explicit plugin entries
+        │
+        ├─ bootstrapServer(...)          trusted boot-time server plugins
+        │     ├─ routes                  Fastify app.register at boot
+        │     ├─ agentTools              passed to createAgentApp at boot
+        │     ├─ systemPromptAppend      static prompt addendum
+        │     ├─ pi packages/skills/exts static Pi resources
+        │     └─ provisioning            runtime workspace materialization
+        │
+        ├─ BoringPluginAssetManager      manifest scan + signatures + SSE
+        │     ├─ /api/v1/agent-plugins
+        │     ├─ /api/v1/agent-plugins/events
+        │     └─ /api/v1/agent-plugins/:id/error
+        │
+        └─ createAgentApp(...)
+              ├─ beforeReload: asset scan + diagnostics + caller hook
+              ├─ systemPromptDynamic: plugin `pi.systemPrompt`
+              └─ pi.getHotReloadableResources: plugin skills/extensions/packages
+
+Browser WorkspaceAgentFront
+        │
+        └─ useAgentPluginHotReload
+              ├─ EventSource to /api/v1/agent-plugins/events
+              ├─ dynamic import(frontUrl?v=<revision>&t=<salt>)
+              └─ registry.replaceByPluginId(...) per output kind
+```
+
+Subpath intent:
+
+| Subpath | Audience | Contents |
+| --- | --- | --- |
+| `/plugin` | Front plugin authors | `definePlugin`, front API/types, manifest validators, panel/surface contracts. |
+| `/server` | Trusted server plugin authors/hosts | `defineServerPlugin`, server plugin types, asset manager helpers. |
+| `/app/server` | App shells | `createWorkspaceAgentServer` and orchestration options. |
+| `/app/front` | App shells | `WorkspaceAgentFront`. |
+| `/shared` | Runtime-agnostic contracts | Shared types only. |
+
+---
+
+## 4. Public API
+
+### 4.1 Plugin `package.json`
+
+```jsonc
+{
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "boring": {
+    "label": "My Plugin",
+    "front": "front/index.tsx",
+    "server": "server/index.ts" // app/internal only; omit for generated plugins
+  },
+  "pi": {
+    "systemPrompt": "Short guidance for the agent.",
+    "extensions": ["agent/index.ts"],
+    "skills": ["skills/my-skill"],
+    "packages": ["."]
+  }
+}
+```
+
+Rules:
+
+- `boring.front`, `boring.server`, `pi.extensions`, and `pi.skills` are safe
+  relative paths contained by the package root.
+- `boring.server: true` is invalid. Use a string path or omit it.
+- Plugin id is derived from `package.json#name`; `boring.id` is rejected.
+- Runtime/generated plugins should include `boring.front` and/or `pi.*` and
+  omit `boring.server`.
+
+### 4.2 App `package.json`
+
+```jsonc
+{
+  "boring": {
+    "defaultPluginPackages": [
+      "@hachej/boring-ask-user",
+      "./src/plugins/playgroundDataCatalog"
+    ]
+  }
+}
+```
+
+Relative entries resolve against the app package.json when
+`appPackageJsonPath` is supplied. Explicit `defaultPluginPackages` passed to
+`createWorkspaceAgentServer` are merged with manifest entries.
+
+### 4.3 Front authoring (`@hachej/boring-workspace/plugin`)
+
+Use the declarative object form:
+
+```ts
+import { definePlugin } from "@hachej/boring-workspace/plugin"
+
+export default definePlugin({
+  id: "my-plugin",
+  label: "My Plugin",
+  panels: [
+    {
+      id: "my-plugin.panel",
+      label: "My Panel",
+      placement: "center",
+      component: MyPanel,
+    },
+  ],
+  commands: [
+    { id: "my-plugin.open", title: "Open My Plugin", panelId: "my-plugin.panel" },
+  ],
+  surfaceResolvers: [myResolver],
+})
+```
+
+The legacy positional form `definePlugin(id, factory, options?)` is not
+supported. For advanced composition, use `setup(api) { ... }` inside the
+config object.
+
+### 4.4 Server authoring (`@hachej/boring-workspace/server`)
+
+Trusted app/internal packages may export a server plugin:
+
+```ts
+import { defineServerPlugin } from "@hachej/boring-workspace/server"
+
+export default defineServerPlugin({
+  id: "my-plugin",
+  systemPrompt: "Use My Plugin when ...",
+  agentTools: [tool],
+  routes: async (app) => {
+    app.get("/api/my-plugin/health", async () => ({ ok: true }))
+  },
+})
+```
+
+This is boot-time composition. Routes and tools are not hot-wired into a
+running Fastify/agent process by `/reload`.
+
+### 4.5 Hot-reload coverage and partial-failure tolerance
+
+| Surface | Runtime `.pi/extensions` | App/internal package plugin | Notes |
+| --- | --- | --- | --- |
+| `pi.systemPrompt` | `/reload`, next turn | `/reload` in dev when discovered; static in production if hot reload disabled | Appended by `systemPromptDynamic`. |
+| `pi.extensions` | `/reload` through Pi session reload | `/reload` when discovered as package resources | File paths are re-read from manifest. |
+| `pi.skills` / `pi.packages` | `/reload` through dynamic resource getter | `/reload` in dev; boot snapshot when `pluginHotReload=false` | `verify-plugin` checks declared local skill paths. |
+| `boring.front` panels/commands/catalogs/surface resolvers | `/reload` + SSE + browser dynamic import | `/reload` in dev when front URL is served by the app/Vite | Previous version stays live on import/register failure. |
+| `boring.server` routes/agentTools | Not supported for generated plugins | Boot-time only | `/reload` can warn `requiresRestart`. Restart process to apply. |
+| Providers/bindings from hot-loaded front factories | Skipped | Static composition only | Dynamic provider tree mounting is intentionally not implemented yet. |
+
+Partial-failure rule: a failed plugin scan/import/register must not abort the
+whole reload. Healthy plugins still update; failing plugins emit diagnostics,
+write/read `.error` state, and keep their previous live UI where possible.
+
+### 4.6 CLI authoring path
+
+Generated plugin authoring uses the provisioned workspace-local CLI:
+
+```bash
+boring-ui scaffold-plugin <name>
+boring-ui verify-plugin <name>
+```
+
+Do not teach agents to copy `packages/cli/templates/plugin` for generated runtime
+plugins. That template is an app/internal publishable package example.
+
+### 4.7 `pluginHotReload`
+
+`createWorkspaceAgentServer({ pluginHotReload })` controls runtime plugin
+reload endpoints and dynamic Pi/package refresh.
+
+- `true` (default): registers `/api/boring.reload`, keeps
+  `/api/v1/agent-plugins/events` active, and refreshes discovered plugin Pi
+  resources on `/api/v1/agent/reload`.
+- `false`: static discovery/listing remains available, but package resources
+  are snapped once at boot and the developer reload endpoint is disabled.
+
+---
+
+## 5. Key algorithms
+
+### 5.1 Manifest scan
+
+`scanBoringPlugins(pluginDirs)` discovers plugin package roots, validates
+manifest shape, resolves contained entry paths, detects duplicate ids, and
+returns `BoringServerPluginManifest[]` plus preflight diagnostics.
+
+### 5.2 Signatures and revisions
+
+`BoringPluginAssetManager` hashes manifest fields, front/server file
+signatures, relevant front/server/shared directories, and Pi resource paths.
+When a signature changes, the plugin revision increments and a load/unload/error
+event is emitted.
+
+### 5.3 Front import cache busting
+
+Browser imports append both revision and salt:
+
+```ts
+import(`${frontUrl}?v=${revision}&t=${Date.now()}`)
+```
+
+The salt avoids stale Vite/browser module graph reuse across repeated reloads
+or dev-server restarts.
+
+### 5.4 Atomic registry replacement
+
+Front factories are first captured into an in-memory API. The captured panels,
+commands, catalogs, and surface resolvers are then installed with
+`replaceByPluginId` per registry. DockView and registry subscribers should not
+see an intermediate empty state.
+
+### 5.5 Server drift warnings
+
+When a plugin had a server entry in a previous revision and that server file
+changes, the load event carries `requiresRestart: ["routes", "agentTools"]`.
+The chat reload response also includes restart warnings so users know `/reload`
+updated front/Pi resources but not boot-wired server code.
+
+### 5.6 Path containment
+
+Manifest paths are lexically safe relative paths and are checked with realpath
+containment so symlink escapes are rejected. Runtime workspace provisioning
+template targets are also constrained to remain inside the workspace root.
+
+### 5.7 Output ownership and collision detection
+
+Plugin-owned outputs carry `pluginId`. Hot reload uses that ownership to replace
+only the current plugin's outputs. Cross-plugin id collisions are rejected with
+`PLUGIN_OUTPUT_ID_COLLISION`; intra-plugin duplicate output ids are rejected
+while capturing the front factory.
+
+---
+
+## 6. Gotchas
+
+1. `/reload` is the runtime plugin refresh boundary. Vite HMR should not
+   directly hot-update `.pi/extensions` modules into the host tree.
+2. Native `EventSource` cannot send Authorization headers. When bearer auth is
+   required and no token-query fallback exists, front plugin hot reload is
+   disabled rather than silently unauthenticated.
+3. Dynamic providers/bindings are not mounted for hot-loaded runtime plugins;
+   use static app composition for provider trees.
+4. `boring.server` in a runtime plugin may verify as a valid file path but it is
+   not dynamically registered by `/reload`.
+5. The asset manager is scan/hash/emit. Server route/tool import and
+   composition happen through app/server orchestration.
+6. Keep generated plugins route-free; use Pi extensions/tools and workspace file
+   APIs instead.
+7. Use surface resolvers for file visualizers. Do not hard-code extension logic
+   in the file tree.
+
+---
+
+## 7. Non-goals
+
+- Hot-registering Fastify routes or static `agentTools` from generated plugins
+  into a live server process.
+- Loading untrusted hosted plugin JavaScript directly into the host React tree.
+- Replacing app/internal domain APIs (for example Macro routes) with runtime
+  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.
+
+---
+
+## 8. Risk register
+
+| Risk | Current mitigation |
+| --- | --- |
+| Broken generated front import | Browser import/register error is surfaced; previous version remains live. |
+| Stale server code after `/reload` | Restart warnings for server-path drift; docs state boot-time-only semantics. |
+| Bad plugin blocks all reloads | Partial-failure tolerance; diagnostics per plugin. |
+| Path escape via manifest entries | Safe relative path validation + realpath containment. |
+| Path escape via runtime provisioning templates | Template targets are constrained to workspace-root descendants. |
+| Duplicate output ids | Cross-plugin and intra-plugin collision checks. |
+| Agent writes plugin into wrong cwd | Workspace-local `boring-ui` shim exports `BORING_AGENT_WORKSPACE_ROOT`; verifier prints scanned path. |

package/docs/README.md

@@ -5,8 +5,13 @@ 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.
-- `PLUGIN_STRUCTURE.md` - plugin folder shape and invariant scans.
 - `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.

package/docs/plans/README.md

@@ -4,6 +4,7 @@ Active ownership records live in this folder.
 
 - `ASK_USER_QUESTIONS_PLUGIN_SPEC.md` - blocking ask-user tool + Questions workspace plugin spec.
 - `PANE_TO_AGENT_CHAT_ACTIONS_SPEC.md` - pane/plugin to active agent chat action bridge spec.
+- `HOT_RELOADABLE_AGENT_PLUGINS_PLAN.md` - current package-json plugin, reload, Pi, and front-factory architecture.
 - `GENERIC_EXPLORER_PLUGIN_PLAN.md` - generic explorer plugin shape and front/plugin ownership audit.
 - `MACRO_PLUGIN_GENERIC_HELPERS_AUDIT.md` - macro plugin audit for reusable explorer/surface/event helper extraction.
 - `PLUGIN_OUTPUTS_ISOLATION_PLAN.md` - plugin ownership and isolation plan.