@jmfederico/pi-web 1.202606.0 → 1.202606.2

package/docs/plugins.md

@@ -7,7 +7,8 @@ Plugins can currently:
 - add action-palette commands;
 - add workspace tools/panels next to Files, Git, and Terminal;
 - add compact workspace-label items in the workspace list, panel header, and status bar;
-- call browser APIs and PI WEB HTTP/WebSocket APIs available to the current browser session;
+- call browser APIs and documented PI WEB plugin context helpers;
+- read workspace files and start workspace terminal commands through documented helpers;
 - serve their own static assets from the plugin directory.
 
 They do **not** run in the session daemon, do not get a server-side hook API, and are not sandboxed.
@@ -17,11 +18,12 @@ They do **not** run in the session daemon, do not get a server-side hook API, an
 Plugins run as JavaScript in the browser app. Treat them as trusted code:
 
 - they can call browser APIs;
-- they can `fetch()` PI WEB API endpoints using the current browser access;
-- they can read workspace files through PI WEB's file endpoints if the UI can read them;
+- they can read workspace files and start terminal commands through documented plugin helpers;
 - they can render arbitrary Lit templates/custom elements in plugin contribution areas;
 - they should not be installed from untrusted sources.
 
+PI WEB's `/api/...` HTTP and WebSocket endpoints are internal implementation details. Plugin code should use the documented context helpers instead. Daring plugins can still reach private routes or runtime objects because they run in the browser, but those private surfaces are experimental: they may graduate into stable helpers, change shape, or disappear.
+
 ## What to ask AI to build
 
 Humans should not need to hand-code plugins. Give an AI agent a concrete UI goal and ask it to create or modify a local plugin.
@@ -100,11 +102,11 @@ Module shape excerpt:
 export default {
   apiVersion: 1,
   name: "Info Plugin",
-  activate: ({ html }) => ({
+  activate: ({ html, svg }) => ({
     contributions: {
       actions: [/* action definitions */],
       workspaceLabels: [/* compact label definitions */],
-      workspacePanels: [/* panel definitions using html */],
+      workspacePanels: [/* panel definitions using html, optional icons using svg */],
     },
   }),
 };
@@ -112,7 +114,7 @@ export default {
 
 When copying the Info plugin, choose a new plugin id so it does not conflict with the bundled `info` plugin.
 
-PI WEB also ships a `pi-web` status plugin that demonstrates dynamic `visible` and `badge` callbacks for tabs that only appear when the host has status messages or needs extra install visibility.
+PI WEB also ships an `updates` plugin that demonstrates dynamic `visible` and `badge` callbacks for tabs that only appear when the host has status messages or needs extra install visibility.
 
 ## Local plugin usage
 
@@ -127,30 +129,135 @@ ln -s /path/to/plugin-folder ~/.pi-web/plugins/plugin-id
 
 Reload the PI WEB browser tab. PI WEB serves plugin modules with an mtime-based `?v=` cache buster. After editing a plugin, hard reload the browser if you do not see changes.
 
-## First-party separate plugin packages
+## Remote machine plugins
 
-First-party plugins that are published as their own npm packages can live in this repository under `plugins/*` as npm workspaces. These packages are **not bundled** into the main `@jmfederico/pi-web` npm package automatically; they are separate packages that share CI, tests, and local development tooling with the main repo.
+When [machine federation](https://pi-web.dev/machines.html) is enabled, PI WEB also loads discovered plugins from the selected remote machine. Remote plugins are trusted browser-side code like local plugins, but their contributions are machine-scoped:
 
-A separate plugin package should:
+- actions, workspace panels, and workspace labels only appear while that machine is selected;
+- plugin file and terminal helpers run against that machine;
+- plugin code is loaded best-effort through the current gateway and cached for the browser page lifetime;
+- if the gateway and remote machine both have an enabled plugin with the same original id, `machineSpecific` metadata decides whether the gateway copy is reused or only the selected machine's copy can appear;
+- remote theme contributions are ignored for now because themes are app-wide;
+- mixed PI WEB versions across federated machines are best-effort and not guaranteed compatible.
 
-- use type-only imports from `@jmfederico/pi-web/plugin-api` when it needs shared PI WEB plugin interfaces; this subpath is currently a `.d.ts`-only dogfooding surface, not a runtime JavaScript module;
-- keep its PI WEB metadata in its own `package.json` with `piWeb.plugins` entries pointing at built JavaScript in `dist/`;
-- include a package-level `build` script and `prepack` script so `npm pack --workspace <package>` and `npm publish --workspace <package>` produce a usable plugin package;
-- use a local symlink into `~/.pi-web/plugins/<plugin-id>` while developing;
-- document any private PI WEB APIs it dogfoods until those APIs become stable plugin runtime helpers.
+Remote plugin enablement is controlled by the remote machine's PI WEB plugin config. To edit or disable a remote machine plugin, open that machine directly or update its config file.
 
-Typical local development loop from this repository:
+Plugin package metadata may set `machineSpecific: true` when the plugin's meaning is tied to the selected PI WEB machine:
 
-```bash
-npm run dev
-curl http://127.0.0.1:8504/pi-web-plugins/manifest.json
+- Omitted or `false`: use the gateway copy when the same plugin id is also present on a remote machine. This is best for portable UI plugins whose helpers already route through the selected machine.
+- `true`: the gateway copy only appears for the local machine. When a remote machine is selected, only that remote machine's copy can appear; if the remote machine does not expose the plugin, the plugin is hidden. This is best for plugins that report machine-local PI WEB status or depend on machine-local plugin code.
+
+For portable plugin assets, prefer URLs relative to the plugin module, for example:
+
+```js
+const url = new URL("./asset.json", import.meta.url);
+```
+
+If a remote plugin constructs absolute asset URLs, it should use the `pluginId` from `activate()` because PI WEB gives remote plugins a gateway-scoped runtime id. Hard-coded `/pi-web-plugins/<original-id>/...` URLs may point at the gateway instead of the remote machine.
+
+## Manage plugins
+
+Open **Settings → Plugins** to review discovered bundled, local, dev, and Pi package plugins for the PI WEB gateway you opened. PI WEB can disable any discovered gateway plugin before the browser imports it. Core app contributions such as the built-in command palette, base workspace tools, and themes are not managed through this plugin list.
+
+Plugin preferences are stored under the top-level `plugins` config key in the PI WEB config file:
+
+```json
+{
+  "plugins": {
+    "workspace-tasks": {
+      "enabled": true,
+      "settings": {}
+    },
+    "info": {
+      "enabled": false
+    }
+  }
+}
+```
+
+Plugins are enabled by default. Set `enabled` to `false` to remove a plugin from `/pi-web-plugins/manifest.json` so the browser will not import or activate it on the next page load. The optional `settings` object is reserved for plugin-specific settings.
+
+After changing plugin enablement, reload the PI WEB browser tab. Already-loaded plugin JavaScript is not unloaded from the current page.
+
+## Built-in plugins
+
+PI WEB ships core, discoverable plugins in the main `@jmfederico/pi-web` npm package. No separate `pi install` step is required: update PI WEB, reload the browser tab, and the bundled plugins appear in `/pi-web-plugins/manifest.json`.
+
+Built-in plugins can be managed from **Settings → Plugins** or with the top-level `plugins` config key.
+
+### Updates
+
+**Plugin id:** `updates`
+**What it does:** adds a conditional **Updates** workspace tab with PI WEB update, restart, and installed-service guidance.
+
+Updates is enabled by default. It declares `machineSpecific: true` so the gateway Updates tab only appears for the local machine; while a remote machine is selected, that remote machine's Updates plugin is used if available. To hide it, disable `updates` in **Settings → Plugins** or set:
+
+```json
+{
+  "plugins": {
+    "updates": { "enabled": false }
+  }
+}
 ```
 
-The main PI WEB `dev` command watches bundled plugins in `pi-web-plugins/`, builds/watches separate plugin packages in `plugins/*`, and discovers those source-checkout plugin packages without symlinking them into `~/.pi-web/plugins`.
+### Workspace Tasks
+
+**Plugin id:** `workspace-tasks`
+**Config file:** `.pi-web/tasks.json`
+**What it does:** adds a **Tasks** workspace tab for running configured shell commands in dedicated PI WEB terminals.
+
+Workspace Tasks is enabled by default. To hide it, disable `workspace-tasks` in **Settings → Plugins** or set:
+
+```json
+{
+  "plugins": {
+    "workspace-tasks": { "enabled": false }
+  }
+}
+```
+
+Configure workspace tasks in `.pi-web/tasks.json`:
+
+```json
+{
+  "version": 1,
+  "tasks": [
+    {
+      "id": "docker.start",
+      "title": "Start Docker",
+      "group": "Docker",
+      "description": "Start the local Docker Compose environment.",
+      "command": "./docker/scripts/docker-compose-dev up -d"
+    },
+    {
+      "id": "db.reset",
+      "title": "Reset DB",
+      "group": "Database",
+      "command": "go -C klingit-go run ./cli db reset",
+      "confirm": true
+    }
+  ]
+}
+```
+
+Open a workspace, choose the **Tasks** tab, and click **Run** next to a task. Commands run in the workspace root because PI WEB creates the terminal for that workspace.
+
+Task fields:
+
+- `version`: must be `1`.
+- `tasks`: array of task definitions.
+- `id`: stable task id, matching `^[a-z][a-z0-9.-]*$`.
+- `title`: button label.
+- `command`: literal shell command sent to the terminal.
+- `description`: optional explanatory text.
+- `group`: optional group heading.
+- `confirm`: optional boolean. When true, the browser asks before dispatching the command.
+
+Review task configs before running them, especially in shared projects. Workspace Tasks runs trusted shell commands from your repositories.
 
 ## Discovery and packaging
 
-PI WEB builds `/pi-web-plugins/manifest.json` from these sources:
+PI WEB builds the gateway `/pi-web-plugins/manifest.json` from these sources:
 
 1. Bundled plugins in the PI WEB package:
 
@@ -168,6 +275,8 @@ PI WEB builds `/pi-web-plugins/manifest.json` from these sources:
 
 3. Installed Pi packages that expose PI WEB plugin metadata. Pi packages may be user or project scoped.
 
+Remote machines expose their own manifests through the gateway at `/api/machines/<machine-id>/pi-web-plugins/manifest.json`. Those plugin modules are rewritten to gateway-scoped asset URLs and registered under machine-scoped runtime ids so duplicate plugin ids on different machines do not collide.
+
 Plugin package directory names and plugin ids must be valid identifiers:
 
 ```text
@@ -182,7 +291,7 @@ A package can expose one or more PI WEB plugin modules. There is exactly one sup
   "piWeb": {
     "plugins": [
       { "id": "review", "module": "dist/review.js" },
-      { "id": "dashboard", "module": "dist/dashboard.js" }
+      { "id": "dashboard", "module": "dist/dashboard.js", "machineSpecific": true }
     ]
   }
 }
@@ -194,6 +303,7 @@ Rules:
 - Each entry must have an explicit `id` and `module`.
 - `id` must match `^[a-z][a-z0-9.-]*$`.
 - `module` must be a safe relative path inside the plugin package root.
+- `machineSpecific` is optional and must be a boolean; omit it for the default portable gateway behavior.
 - Duplicate plugin ids are not auto-renamed; later duplicates are skipped.
 - Legacy shortcuts such as `piWeb.plugin`, string entries in `piWeb.plugins`, `piWeb.id` fallback ids, and no-`package.json` fallbacks are not supported.
 
@@ -208,13 +318,14 @@ The manifest contains each discovered plugin module:
       "id": "my-plugin",
       "module": "/pi-web-plugins/my-plugin/pi-web-plugin.js?v=1234567890",
       "source": "local",
-      "scope": "local"
+      "scope": "local",
+      "machineSpecific": false
     }
   ]
 }
 ```
 
-`source` describes where the plugin came from (`bundled`, `local`, or the Pi package source). `scope` is `bundled`, `local`, `user`, or `project`.
+`source` describes where the plugin came from (`bundled`, `local`, or the Pi package source). `scope` is `bundled`, `local`, `user`, or `project`. `machineSpecific` controls whether the gateway copy is valid for remote machines or only each selected machine's own copy can appear.
 
 A plugin can fetch its own static assets with URLs under:
 
@@ -239,6 +350,7 @@ interface PluginActivationContext {
   apiVersion: 1;
   pluginId: string;
   html: typeof import("lit").html;
+  svg: typeof import("lit").svg;
 }
 
 interface PluginActivationResult {
@@ -325,6 +437,7 @@ interface PluginRuntimeContext {
   state: {
     selectedWorkspace?: Workspace;
     selectedSession?: unknown;
+    piWebStatus?: PiWebStatusResponse;
   };
   openActionPalette: () => void;
   focusPrompt: () => void;
@@ -344,12 +457,12 @@ interface PluginRuntimeContext {
 Notes:
 
 - `state` is a snapshot of current UI state when actions are built.
-- Only `state.selectedWorkspace` and `state.selectedSession` are documented as stable for plugin authors.
-- Other `state` fields may exist at runtime, but they are PI WEB internals and can change quickly.
+- The stable state fields are `state.selectedWorkspace`, `state.selectedSession`, and `state.piWebStatus`. `state.piWebStatus` describes the currently selected machine's PI WEB runtime, or the gateway/local runtime when the local machine is selected.
+- Other `state` fields may exist at runtime, but they are private PI WEB internals that may graduate into stable helpers, change shape, or disappear.
 - `enabled` is evaluated when the action palette asks for actions.
 - `selectWorkspaceTool()` expects a qualified panel id such as `my-plugin:workspace.info`.
 - `openTerminal()` switches to the built-in terminal panel. Pass `{ terminalId }` to deep-link to a specific terminal.
-- Only fields documented here and declared in `plugin-api.d.ts` are stable public plugin API. PI WEB may attach `piWebInternal` fields at runtime for first-party dogfooding; plugins should not depend on those fields because they can change or disappear without notice.
+- Only fields documented here and declared in `plugin-api.d.ts` are stable public plugin API. Anything else is experimental: it may become public API later, change shape, or disappear.
 
 #### Keyboard shortcuts
 
@@ -369,6 +482,13 @@ workspacePanels: [
   {
     id: "workspace.info",
     title: "Info",
+    icon: svg`
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <circle cx="12" cy="12" r="9"></circle>
+        <path d="M12 10v6"></path>
+        <path d="M12 7h.01"></path>
+      </svg>
+    `,
     order: 100,
     visible: ({ workspace }) => workspace.isGitRepo,
     render: ({ workspace }) => html`
@@ -388,23 +508,50 @@ Panel type:
 interface WorkspacePanelContribution {
   id: string;
   title: string;
+  icon?: TemplateResult;
   order?: number;
-  visible?: (context: { workspace: Workspace }) => boolean;
+  visible?: (context: WorkspacePanelContext) => boolean;
   badge?: (context: WorkspacePanelContext) => string | number | TemplateResult | undefined;
   render: (context: WorkspacePanelContext) => TemplateResult;
 }
 
 interface WorkspacePanelContext {
+  machine: PluginMachine;
   workspace: Workspace;
-  openTerminal: (options?: { terminalId?: string }) => void;
+  state?: PluginRuntimeState;
+  files: {
+    readFile(path: string): Promise<FileContentResponse>;
+  };
+  terminal: {
+    open(options?: { terminalId?: string }): void;
+    runCommand(input: {
+      title: string;
+      command: string;
+      metadata?: Record<string, string>;
+      open?: boolean;
+    }): Promise<TerminalCommandRunHandle>;
+  };
+  host: {
+    requestRender(): void;
+  };
 }
 ```
 
-`workspace` and `openTerminal()` are documented as stable for panel callbacks. Other fields may exist at runtime, but they are PI WEB internals and can change quickly. If a panel needs file, git, terminal, or session data beyond the helpers documented here, prefer explicit `fetch()` calls and keep them isolated.
+`icon` is optional and is used in the compact mobile tab bar. Prefer an SVG rendered with the `svg` helper from `PluginActivationContext`; use `currentColor` so PI WEB themes can style it. If `icon` is omitted, mobile tabs fall back to initials from the panel title, or to the full title when initials collide.
+
+`machine`, `workspace`, `files`, `terminal`, and `host` are documented as stable for panel callbacks. Use `terminal.open()` to switch to the built-in terminal panel; pass `{ terminalId }` to deep-link to a specific terminal. Call `host.requestRender()` when async plugin-owned state changes should make PI WEB re-evaluate panel callbacks such as `badge`, `visible`, or `render`.
 
-Useful workspace shape:
+For compatibility, PI WEB still provides the old `context.openTerminal()` workspace-panel helper at runtime. It is deprecated, intentionally omitted from the public TypeScript declarations, and planned for removal in v2. Existing JavaScript plugins keep working, while typed plugins should migrate to `context.terminal.open()`.
+
+Useful workspace and machine shapes:
 
 ```ts
+interface PluginMachine {
+  id: string;
+  name: string;
+  kind: "local" | "remote";
+}
+
 interface Workspace {
   id: string;
   projectId: string;
@@ -417,6 +564,8 @@ interface Workspace {
 }
 ```
 
+`machine.id` is included in panel contexts so plugins can keep caches machine-scoped. Do not infer the selected machine from global browser state.
+
 Use existing classes such as `toolbar`, `viewer`, `empty`, and `muted` for panel content when possible. Do not assume a panel owns the whole page; keep layout contained.
 
 ### Workspace labels
@@ -453,13 +602,21 @@ interface WorkspaceLabelContribution {
 }
 
 interface WorkspaceLabelContext {
+  machine: PluginMachine;
   workspace: Workspace;
+  state?: PluginRuntimeState;
+  files: {
+    readFile(path: string): Promise<FileContentResponse>;
+  };
+  host: {
+    requestRender(): void;
+  };
 }
 ```
 
-Only `workspace` is documented as stable for label callbacks. Other fields may exist at runtime, but they are PI WEB internals and can change quickly.
+`machine`, `workspace`, `files`, and `host` are documented as stable for label callbacks. Include `machine.id` in any label caches that depend on workspace data. Call `host.requestRender()` when async plugin-owned state changes should make PI WEB re-evaluate label `visible` or `items` callbacks.
 
-Items are sorted by `order` and then id. Return an empty array to render nothing.
+Items are sorted by `order` and then id. Return an empty array to render nothing. Keep callbacks synchronous and lightweight; start async work from the callback, return cached items, then call `host.requestRender()` when the cache changes.
 
 #### Text items
 
@@ -519,55 +676,105 @@ export default {
 
 ## Reading workspace files
 
-Plugins can use existing PI WEB endpoints. For example, to read a file in a workspace:
+Workspace panels and workspace labels can read files through the documented `files` helper. PI WEB binds this helper to the callback's machine and workspace, so it works the same for local and federated machines.
 
 ```js
-async function readWorkspaceFile(workspace, path) {
-  const url =
-    `/api/projects/${encodeURIComponent(workspace.projectId)}` +
-    `/workspaces/${encodeURIComponent(workspace.id)}` +
-    `/file?path=${encodeURIComponent(path)}`;
-
-  const response = await fetch(url, { cache: "no-store" });
-  if (!response.ok) throw new Error(`Failed to read ${path}: ${response.status}`);
-  return await response.json();
+workspacePanels: [
+  {
+    id: "workspace.env",
+    title: "Env",
+    render: ({ files }) => html`
+      <my-env-viewer .files=${files}></my-env-viewer>
+    `,
+  },
+]
+
+class MyEnvViewer extends HTMLElement {
+  set files(value) {
+    this._files = value;
+    void this.load();
+  }
+
+  async load() {
+    try {
+      const file = await this._files.readFile(".env.example");
+      this.textContent = file.binary ? "Binary file" : file.content;
+    } catch (error) {
+      this.textContent = error instanceof Error ? error.message : String(error);
+    }
+  }
 }
 ```
 
-The file response includes fields such as `path`, `content`, `truncated`, and `binary`, but endpoint response shapes are private PI WEB implementation details for now and can change between releases.
+Labels should use the same helper through a plugin-owned cache because `items()` itself must return synchronously:
 
-Be careful with sensitive files such as `.env`: plugins are trusted browser code, and file contents are exposed to the plugin.
-
-## Other useful PI WEB APIs
+```js
+const envCache = new Map();
 
-Plugins may call any endpoint available to the browser, but these HTTP endpoints are considered private PI WEB implementation APIs for now. They can change quickly between releases. Prefer plugin runtime context helpers when they cover the interaction, and keep any direct HTTP usage small and isolated.
+function envKey(machine, workspace) {
+  return `${machine.id}:${workspace.id}:docker/development.be-go.local.env`;
+}
 
-Common read endpoints:
+function loadEnvLabel(context) {
+  const key = envKey(context.machine, context.workspace);
+  const cached = envCache.get(key);
+  if (cached !== undefined) return cached;
+
+  const pending = { status: "loading", label: undefined };
+  envCache.set(key, pending);
+  context.files.readFile("docker/development.be-go.local.env")
+    .then((file) => {
+      pending.status = "ready";
+      pending.label = file.content.match(/^DEV_URL=(.+)$/m)?.[1];
+      context.host.requestRender();
+    })
+    .catch(() => {
+      pending.status = "missing";
+      context.host.requestRender();
+    });
+  return pending;
+}
 
-```text
-GET /api/projects
-GET /api/projects/:projectId/workspaces
-GET /api/projects/:projectId/workspaces/:workspaceId/tree?path=<dir>
-GET /api/projects/:projectId/workspaces/:workspaceId/file?path=<file>
-GET /api/projects/:projectId/workspaces/:workspaceId/git/status
-GET /api/projects/:projectId/workspaces/:workspaceId/git/diff?path=<file>&staged=true|false
-GET /api/sessions?cwd=<workspace-path>
-GET /api/sessions/:sessionId/status
-GET /api/sessions/:sessionId/messages?before=<cursor>&limit=<n>
+workspaceLabels: [
+  {
+    id: "dev-url",
+    items: (context) => {
+      const cached = loadEnvLabel(context);
+      return cached.label === undefined ? [] : [{
+        type: "link",
+        text: cached.label,
+        href: cached.label,
+        target: "_blank",
+      }];
+    },
+  },
+]
 ```
 
-Common write/action endpoints:
+The file response includes fields such as `path`, `content`, `truncated`, and `binary`. Be careful with sensitive files such as `.env`: plugins are trusted browser code, and file contents are exposed to the plugin.
 
-```text
-POST /api/sessions                 { "cwd": "/path/to/workspace" }
-POST /api/sessions/:id/prompt      { "text": "...", "streamingBehavior": "steer" | "followUp" }
-POST /api/sessions/:id/shell       { "text": "..." }
-POST /api/sessions/:id/stop
-POST /api/sessions/:id/archive
-POST /api/sessions/:id/restore
+## Running workspace terminal commands
+
+Workspace panels can start terminal commands through the documented `terminal` helper. Commands run in the current workspace on the panel's machine.
+
+```js
+render: ({ terminal }) => html`
+  <button @click=${() => terminal.runCommand({
+    title: "Build",
+    command: "npm run build",
+    open: true,
+    metadata: { "my-plugin.task": "build" },
+  })}>Build</button>
+`
 ```
 
-Prefer runtime context helpers (`startSession`, `stopActiveWork`, `refreshFiles`, `refreshGit`, etc.) when they cover the interaction. Use direct HTTP calls only for plugin-specific data or behavior, and expect to update them as PI WEB evolves.
+Review command strings carefully. They are trusted shell commands executed in the workspace terminal.
+
+## Private and experimental PI WEB APIs
+
+PI WEB's `/api/...` HTTP and WebSocket routes and runtime-only fields are private implementation details. They exist because plugins are trusted browser code, and because some capabilities may be evaluated there before they are designed as stable helpers.
+
+That is allowed, but outside the v1 compatibility promise: URLs, response shapes, runtime fields, and machine-federation routing may graduate into stable APIs, change shape, or disappear. The stable public plugin API is only the documented helpers and declarations in `plugin-api.d.ts`. Prefer those whenever they exist; if you rely on private surfaces, keep the dependency local to the plugin and expect to revisit it after PI WEB upgrades.
 
 ## Async data and caching
 
@@ -576,7 +783,7 @@ PI WEB does not provide a plugin cache/invalidation framework. Keep host callbac
 - simple contributions should be synchronous and cheap;
 - expensive or async work should live inside the plugin;
 - custom elements in `type: "render"` label items or panels are a good place to own async loading;
-- dedupe fetches and avoid unbounded polling;
+- dedupe async reads/commands and avoid unbounded polling;
 - clean up intervals/event listeners in custom elements' `disconnectedCallback()`.
 
 ## Agent implementation checklist
@@ -584,7 +791,7 @@ PI WEB does not provide a plugin cache/invalidation framework. Keep host callbac
 If you are an AI agent building or editing a PI WEB plugin, follow this checklist:
 
 1. Create or update a plugin folder with `package.json` and a JavaScript module such as `pi-web-plugin.js`.
-2. Use the single supported package metadata shape: `piWeb.plugins` array with `{ id, module }` entries.
+2. Use the single supported package metadata shape: `piWeb.plugins` array with `{ id, module, machineSpecific? }` entries.
 3. Default-export `{ apiVersion: 1, name, activate }` from the module.
 4. Return `{ contributions: { actions, workspacePanels, workspaceLabels } }` from `activate()`.
 5. Use ids matching `^[a-z][a-z0-9.-]*$`.
@@ -594,8 +801,8 @@ If you are an AI agent building or editing a PI WEB plugin, follow this checklis
 9. Add workspace panels for larger workspace UI.
 10. Add workspace labels for compact inline metadata.
 11. Return arrays from workspace label `items()`; return an empty array to render nothing.
-12. Use stable context fields first; only `workspace`, `state.selectedWorkspace`, and `state.selectedSession` are documented as stable.
-13. Use `fetch()` against PI WEB APIs only for plugin-specific behavior not provided by runtime context helpers, and isolate those calls because HTTP endpoints are private for now.
+12. Use documented context helpers first: `files`, `terminal`, `host.requestRender`, `workspace`, `machine`, `state.selectedWorkspace`, `state.selectedSession`, and `state.piWebStatus`.
+13. Do not fetch PI WEB `/api/...` endpoints directly unless you intentionally accept private API churn; prefer documented helpers.
 14. Treat plugins as trusted code and avoid reading or displaying secrets unless intentional.
 15. After local edits, tell the user to hard reload the browser and check the console for plugin errors.
 

package/package.json

@@ -1,14 +1,10 @@
 {
   "name": "@jmfederico/pi-web",
-  "version": "1.202606.0",
+  "version": "1.202606.2",
   "description": "Remote web UI and browser control plane for persistent Pi Coding Agent sessions.",
   "license": "MIT",
   "author": "Federico Jaramillo Martinez",
   "type": "module",
-  "workspaces": [
-    ".",
-    "plugins/*"
-  ],
   "bin": {
     "pi-web": "dist/cli.js",
     "pi-web-server": "dist/server/index.js",
@@ -22,26 +18,26 @@
     "extensions",
     "docs/plugins.md",
     "docs/assets",
-    "plugin-api.d.ts"
+    "plugin-api.d.ts",
+    "plugin-api/unstable.d.ts"
   ],
   "scripts": {
     "dev": "bash -c 'trap \"kill 0\" EXIT; npm run dev:sessiond & npm run dev:web & npm run dev:client & wait'",
     "dev:sessiond": "tsx watch src/server/sessiond.ts",
-    "dev:web": "bash -c 'set -e; npm run build:plugins; npm run build:plugin-packages; trap \"kill 0\" EXIT; npm run dev:plugins & npm run dev:plugin-packages & tsx watch src/server/index.ts & wait'",
+    "dev:web": "bash -c 'set -e; npm run build:plugins; trap \"kill 0\" EXIT; npm run dev:plugins & tsx watch src/server/index.ts & wait'",
     "dev:server": "npm run dev:web",
     "dev:client": "vite --host 0.0.0.0",
     "dev:plugins": "node scripts/build-plugins.mjs --watch",
-    "dev:plugin-packages": "node scripts/dev-plugin-packages.mjs",
-    "build": "tsc -p tsconfig.build.json && npm run build:plugins && npm run build:plugin-packages && vite build",
+    "build": "tsc -p tsconfig.build.json && npm run build:plugin-api && npm run build:plugins && vite build",
+    "build:plugin-api": "tsc -p tsconfig.plugin-api.json",
     "build:plugins": "tsc -p tsconfig.plugins.json && node scripts/build-plugins.mjs",
-    "build:plugin-packages": "bash -c 'set -e; shopt -s nullglob; for package in plugins/*/package.json; do dir=${package%/package.json}; (cd \"$dir\" && npm run build --if-present); done'",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint \"src/**/*.ts\" \"extensions/**/*.ts\" \"pi-web-plugins/**/*.ts\" \"plugins/**/*.ts\" vite.config.ts vitest.config.ts",
+    "lint": "eslint \"src/**/*.ts\" \"extensions/**/*.ts\" \"pi-web-plugins/**/*.ts\" vite.config.ts vitest.config.ts",
     "test": "vitest run --config vitest.config.ts",
     "verify": "npm run typecheck && npm run lint && npm test",
     "start": "tsx src/server/index.ts",
     "start:sessiond": "tsx src/server/sessiond.ts",
-    "clean": "rm -rf dist plugins/*/dist",
+    "clean": "rm -rf dist",
     "prepack": "npm run build",
     "pack:dry": "npm pack --dry-run",
     "prepublishOnly": "npm run verify",

package/plugin-api/unstable.d.ts

@@ -0,0 +1 @@
+export * from "../dist/plugin-api/unstable.js";