@blackbelt-technology/pi-agent-dashboard 0.5.2 → 0.5.4

package/AGENTS.md

@@ -145,8 +145,6 @@ See [docs/architecture.md](docs/architecture.md) for full details.
 npm install          # Install dependencies
 npm test             # Run all tests (vitest)
 npm run test:watch   # Watch mode
-npm run test:bootstrap       # Run the bootstrap resolution harness only
-npm run test:bootstrap:watch # Bootstrap harness in watch mode
 npm run build        # Build web client (Vite)
 npm run dev          # Start Vite dev server
 npm run reload       # Reload all connected pi sessions
@@ -278,6 +276,9 @@ This section lists only the **architectural backbone** — the files agents touc
 | `.pi/skills/openspec-shared/scripts/effective-status.sh` | Bash wrapper around `openspec status` applying R1/R2/R3 promotion |
 | `src/shared/state-replay.ts` | Synthesizes events from pi entries (shared, used by server + bridge) |
 | `src/shared/dashboard-plugin/slot-types.ts` | Frozen slot taxonomy: `SlotId`, `Multiplicity`, `PayloadTier`, `SLOT_DEFINITIONS` |
+| `src/shared/dashboard-plugin/ui-primitives.ts` | UI primitive registry contracts: `UI_PRIMITIVE_KEYS`, `UiPrimitiveMap`, per-primitive prop interfaces. See `docs/plugin-ui-primitives.md`. |
+| `packages/dashboard-plugin-runtime/src/ui-primitive-{registry,context}.tsx` | Registry runtime: `createUiPrimitiveRegistry`, `registerUiPrimitive`, `<UiPrimitiveProvider>`, `useUiPrimitive` (strict), `useUiPrimitiveOrNull` (soft). |
+| `packages/dashboard-plugin-runtime/src/test-support/withUiPrimitiveProvider.tsx` | Test helper that wraps a render in a UiPrimitiveProvider populated with mock impls. |
 | `src/shared/dashboard-plugin/manifest-types.ts` | `PluginManifest` and `PluginClaim` interfaces |
 | `src/shared/dashboard-plugin/slot-props.ts` | `SlotPropsMap` and `SlotProps<SlotId>` typed prop contracts per slot id |
 | `src/shared/dashboard-plugin/plugin-status.ts` | `PluginStatus` (for `/api/health`) and `PluginConfigUpdate` (WS payload) |
@@ -292,6 +293,8 @@ This section lists only the **architectural backbone** — the files agents touc
 | `packages/dashboard-plugin-runtime/src/server/server-context.ts` | `createServerPluginContext` — per-plugin scoped logger + config |
 | `packages/dashboard-plugin-runtime/src/server/config-validator.ts` | Ajv JSON-Schema 7 validation for plugin config writes |
 | `packages/dashboard-plugin-runtime/src/server/plugin-status-store.ts` | In-memory `PluginStatusStore` for `/api/health.plugins[]` |
+| `packages/dashboard-plugin-runtime/src/server/requirement-probes.ts` | Declarative requirement probes (piExtensions/binaries/services); 30s cache. See change: add-plugin-activation-ui. |
+| `src/server/routes/plugin-activation-routes.ts` | REST routes: GET /api/plugins, POST /api/plugins/:id/toggle. See change: add-plugin-activation-ui. |
 | `src/server/routes/plugin-config-routes.ts` | `POST /api/config/plugins/:id` — validates and merges plugin config (auth-gated) |
 | `packages/demo-plugin/` | Private fixture plugin exercising settings-section + tool-renderer slots |
 | `packages/dashboard-plugin-skill/` | Pi skill `dashboard-plugin-scaffold`. Modes: `new` (scaffold packages/<id>-plugin/), `augment` (inject manifest + src/dashboard/ into pi-extension at cwd). |
@@ -301,6 +304,7 @@ This section lists only the **architectural backbone** — the files agents touc
 | `src/server/routes/session-routes.ts` | REST routes: sessions, events, session-diff |
 | `src/server/routes/git-routes.ts` | REST routes: git branches, checkout, init, stash-pop |
 | `src/server/routes/file-routes.ts` | REST routes: file read, browse, browse-flags, browse-mkdir, readme, pinned-dirs |
+| `packages/server/src/routes/manifest-route.ts` | Dynamic `/manifest.json` route. Pure `stripPort` + `resolveManifestSource` + `buildManifestBody`; registered before fastify-static. |
 | `src/server/routes/openspec-routes.ts` | REST routes: openspec-archive, pi-resources, pi-resource-file |
 | `src/server/routes/system-routes.ts` | REST routes: config, health, shutdown, tunnel, editors |
 | `src/server/event-wiring.ts` | Pi gateway → browser gateway event forwarding; UI cache + activity stamping + unread trigger |
@@ -346,13 +350,8 @@ This section lists only the **architectural backbone** — the files agents touc
 | `src/shared/tool-registry/types.ts` | `ToolDefinition`, `Strategy`, `Resolution`, error classes |
 | `src/shared/tool-registry/index.ts` | Barrel export + `getDefaultRegistry()` singleton accessor |
 | `src/server/routes/tool-routes.ts` | REST routes for `/api/tools*` (list, rescan, override, diagnostics) |
-| `packages/shared/src/bootstrap-install.ts` | Shared bootstrap installer for pi/openspec/tsx into `~/.pi-dashboard/` |
-| `packages/server/src/bootstrap-state.ts` | In-memory bootstrap state store (status/progress/error/version/compatibility) |
-| `packages/server/src/routes/bootstrap-routes.ts` | REST routes: bootstrap status, upgrade-pi, retry |
-| `packages/server/src/bootstrap-queue.ts` | In-memory ticket queue, flushes on bootstrap-state ready transition |
-| `packages/server/src/pi-version-skew.ts` | Pi compatibility range reader + comparator + bootstrap compatibility writer |
-| `packages/client/src/hooks/useBootstrapStatus.ts` | Client hook for bootstrap state (fetch + WS subscribe) |
-| `packages/client/src/components/BootstrapBanner.tsx` | Banner above MobileShell for installing/failed/upgrade states |
+| `packages/server/src/pi-version-skew.ts` | Pure pi version compatibility helpers (`readPiCompatibility`, `computeCompatibility`) |
+| `packages/shared/src/legacy-managed-dir.ts` | `detectLegacyManagedDir({homedir?})` returns `{present, path, pkgCount, sizeMb}`; surface for Doctor advisory + server CLI startup log |
 | `src/client/lib/tools-api.ts` | Client-side fetch helpers for `/api/tools*` |
 | `src/client/components/ToolsSection.tsx` | Settings → General → Tools section (per-tool status/source/override UI) |
 | `src/server/npm-search-proxy.ts` | Cached proxy for npm registry search (`keywords:pi-package`) and README |
@@ -380,7 +379,6 @@ This section lists only the **architectural backbone** — the files agents touc
 | `src/shared/platform/node-spawn.ts` | Sole source of `node --import <loader> <entry>` argv construction |
 | `src/shared/__tests__/no-raw-node-import.test.ts` | Repo-lint: forbid raw `--import`/`--loader` argv outside `node-spawn.ts` |
 | `src/shared/__tests__/no-direct-process-kill.test.ts` | Repo-lint: forbid `process.kill(` outside `platform/` |
-| `src/shared/__tests__/bootstrap/` | In-memory bootstrap resolution harness (memfs-backed); 1080-cell scenario cube |
 | `src/server/editor-registry.ts` | Detects available native editors (running processes + CLI) |
 | `src/server/editor-manager.ts` | Lifecycle manager for code-server child processes |
 | `src/server/editor-proxy.ts` | Reverse proxy for `/editor/:id/*` to code-server instances |
@@ -414,6 +412,7 @@ This section lists only the **architectural backbone** — the files agents touc
 | `src/extension/provider-register.ts` | Reads `providers.json`, calls `pi.registerProvider`, hot-reload on credentials change |
 | `src/client/lib/providers-api.ts` | Client fetch helper for `/api/providers/test` connection probe |
 | `src/client/components/ProviderAuthSection.tsx` | Settings section: OAuth login buttons, device-code modal, API key inputs |
+| `packages/client/src/components/PluginsSection.tsx` | Settings ▸ Plugins activation list; toggle + missing-requirement install. See change: add-plugin-activation-ui. |
 | `src/server/auth-plugin.ts` | Fastify plugin: auth routes, onRequest hook, WS upgrade validation |
 | `src/server/config-api.ts` | Config REST API: read (redacted), write (partial merge), secret preservation |
 | `src/client/components/SettingsPanel.tsx` | Settings UI: all dashboard config fields, grouped form, save to server |
@@ -455,20 +454,18 @@ This section lists only the **architectural backbone** — the files agents touc
 | `.pi/skills/browser-visual-debug/SKILL.md` | Skill: visual debugging with a real browser via pi-agent-browser |
 | `.pi/skills/browser-visual-debug/references/` | Dashboard recipes, responsive presets, agent-browser cheatsheet |
 | `.pi/skills/browser-visual-debug/scripts/detect-dashboard.sh` | Auto-detect dashboard URL, mode, Vite dev server status |
-| `packages/electron/src/main.ts` | Electron main: single-instance, wizard, server launch, loading page, tray |
+| `packages/electron/src/main.ts` | Electron main: 6-state startup machine (check-health → attach \| wizard → spawn → health-wait → done \| loading-page-error); single-instance, tray |
 | `packages/electron/src/lib/link-handling.ts` | Pure `isSameOriginUrl` + OAuth-aware `decideWillNavigate` for external-link guard |
 | `packages/client/src/components/MarkdownContent.tsx` | ReactMarkdown renderer (chat/thinking/READMEs/previews); external-link hardening + KaTeX math + `pi-asset:` image scheme |
 | `packages/client/src/lib/SessionAssetsContext.tsx` | Per-session image-asset registry context resolving `pi-asset:<hash>` srcs in `MarkdownContent` |
 | `packages/extension/src/markdown-image-inliner.ts` | Bridge helper rewriting assistant `![alt](path)` → `![alt](pi-asset:<hash>)` (SHA-256/16, MIME allowlist, 5 MB/img + 20 MB/msg caps) |
 | `packages/client/src/__tests__/no-bare-external-anchor.test.ts` | Repo-lint: forbid bare `<a href="http(s)://">` without `target="_blank"` |
-| `packages/electron/src/lib/pick-node.ts` | Pure `pickNodeForServer` — prefer system Node when version-safe, else bundled |
-| `packages/electron/src/lib/ensure-windows-path.ts` | `ensureWindowsSystemPath` — prepend System32/npm/Git dirs on Windows; no-op on POSIX |
-| `packages/electron/src/lib/server-lifecycle.ts` | Health check → server spawn; `setSpawnedPid` + `decideShutdownOnQuit` for V2 ownership rule |
-| `packages/electron/src/lib/launch-source.ts` | `selectLaunchSource()` resolver: attach→devMonorepo→piExtension→npmGlobal→extracted; `spawnFromSource` |
-| `packages/electron/src/lib/bundle-extract.ts` | `needsExtraction`, `migrateConfigs`, `extractBundle` with survive-extract whitelist for `~/.pi-dashboard/` |
-| `packages/shared/src/installable-list.ts` | `InstallablePackage`/`InstallableList` types; `readInstallableList`, `writeInstallableList`, `mergeInstallableList` |
-| `packages/server/src/bootstrap-install-from-list.ts` | Per-package reconcile loop reading `~/.pi/dashboard/installable.json`; no-op when file absent |
+| `packages/electron/src/lib/pick-node.ts` | `pickNodeForServer` — 2 strategies: bundled → execpath-fallback (corrupted-install signal) |
+| `packages/electron/src/lib/ensure-windows-path.ts` | Re-export shim of shared `ensureWindowsSystemPath` (prepends System32/Wbem/PowerShell/OpenSSH/WindowsApps on Win; no-op on POSIX) |
+| `packages/electron/src/lib/server-lifecycle.ts` | Thin `selectLaunchSource + spawnFromSource` shim; `setSpawnedPid` + `decideShutdownOnQuit` ownership rule |
+| `packages/electron/src/lib/launch-source.ts` | `selectLaunchSource()` resolver — 3 strategies: attach \| devMonorepo \| bundled; `spawnFromSource` |
 | `packages/shared/src/bridge-register.ts` | Shared bridge registration: `findBundledExtension(baseDir)` + `registerBridgeExtension(path)`; non-destructive cleanup, AppImage guard. Used by server startup and Electron wizard. |
+| `packages/shared/src/pi-package-resolver.ts` | Resolves pi `packages[]` (npm/git/https/abs/rel) to install dir + entry path. Tier-2 fallback for plugin peer imports across npm/git/local installs. See change: add-shared-pi-package-resolver. |
 | `packages/electron/src/lib/doctor.ts` | Doctor diagnostic: checks all binaries, versions, server status, offers setup |
 | `packages/shared/src/doctor-core.ts` | Shared doctor primitives: types, SECTION_OF, SUGGESTIONS, safeExec/safeCheck/assumedMandatory, runSharedChecks, formatDoctorReportMarkdown |
 | `packages/electron/src/lib/doctor-bridge-contract.ts` | Typed `DoctorBridge` interface + frozen `DOCTOR_IPC_CHANNELS` (channel-name-drift lint) |
@@ -480,23 +477,15 @@ This section lists only the **architectural backbone** — the files agents touc
 | `packages/client/src/components/DiagnosticsSection.tsx` | Settings → Diagnostics — fetch, sections, suggestions, copy-to-clipboard with textarea fallback |
 | `packages/electron/src/lib/app-menu.ts` | App menu with About dialog and Doctor on all platforms |
 | `packages/electron/src/lib/tray.ts` | System tray with platform-specific icons |
-| `packages/electron/src/lib/dependency-installer.ts` | Async npm install of pi/openspec/tsx into `~/.pi-dashboard/` (Windows-hardened) |
-| `packages/electron/src/lib/dependency-detector.ts` | Detects pi/openspec/Node on PATH and managed install (AppImage + Win-ext guards) |
+| `packages/electron/src/lib/dependency-detector.ts` | Detects pi/openspec/Node on PATH (AppImage + Win-ext guards) |
 | `packages/electron/src/lib/bundled-node.ts` | Resolves bundled Node.js/npm paths in Electron resources |
-| `packages/electron/src/lib/wizard-window.ts` | First-run setup wizard window with preload bridge |
+| `packages/electron/src/lib/wizard-window.ts` | Single-window factory for the slim welcome wizard |
+| `packages/electron/src/renderer/wizard.html` | 179-LOC welcome card + `[Launch dashboard]` CTA + Advanced disclosure |
 | `packages/electron/forge.config.ts` | Electron Forge config: DMG/DEB/AppImage/NSIS makers; arch-tagged DMG; macOS 10.15 floor |
 | `packages/electron/scripts/build-installer.sh` | Build script: native + Docker cross-platform; `--mac-both` arm64+x64 sequence |
 | `packages/electron/scripts/docker-make.sh` | Docker entrypoint: bundles server, native deps, runs Forge make |
 | `packages/electron/scripts/Dockerfile.build` | Docker image for cross-platform builds (node:22-bookworm-slim) |
-| `packages/electron/scripts/bundle-server.mjs` | Bundles dashboard server + workspace deps into `resources/server/` (Node-native ESM) |
-| `packages/electron/offline-packages.json` | Pinned versions of pi/openspec/tsx for offline npm cacache |
-| `packages/electron/scripts/bundle-offline-packages.sh` | Build-time script: pack pinned versions into cacache tarball with SHA-256 |
-| `packages/electron/resources/offline-packages/manifest.json` | Offline-cache manifest consumed at runtime by `dependency-installer.ts` |
-| `packages/electron/resources/offline-packages/npm-cache.tar.gz` | gzipped npm cacache for first-run offline install |
-| `packages/electron/src/lib/offline-packages.ts` | Pure offline-cache helpers (parse, resolve, verify SHA-256, extract) |
-| `packages/electron/scripts/bundle-recommended-extensions.sh` | Opt-in: clone bundled-extension ids with SPDX allowlist + 15MB budget |
-| `packages/electron/src/lib/dependency-installer.ts` → `installBundledExtensions` | First-run activation of pre-bundled extensions into pi git cache |
-| `packages/electron/src/lib/wizard-badge.ts` | Pure `classifyProgressBadge(output)` (`bundled`/`system`/null) |
+| `packages/electron/scripts/bundle-server.mjs` | Bundles server + workspace deps into `resources/server/`. Runs `npm install --omit=dev`. Phase 1 GO/NO-GO guard asserts node-pty prebuild triples |
 | `packages/shared/src/recommended-extensions.ts` → `BUNDLED_EXTENSION_IDS` | Single source of truth for bundled extension ids in Electron installer |
 | `packages/electron/scripts/test-server-launch.sh` | Docker-based test for server launch on clean Linux |
 | `packages/electron/scripts/test-electron-install.sh` | Full e2e Docker test: install, wizard, server launch, health check |

package/README.md

@@ -75,6 +75,16 @@ On first launch a setup wizard walks you through mode selection (standalone vs.
 
 ### B — pi package (recommended for CLI users)
 
+If you don't have pi yet, you can install the dashboard directly via npm — pi/openspec/tsx ship as regular npm dependencies, so a single install brings everything in:
+
+```bash
+npm install -g @blackbelt-technology/pi-agent-dashboard
+pi-dashboard
+# open http://localhost:8000
+```
+
+If pi is already installed, the bridge-extension flow is equivalent:
+
 ```bash
 pi install npm:@blackbelt-technology/pi-agent-dashboard
 pi
@@ -88,16 +98,60 @@ The bridge extension auto-starts the dashboard server on first launch:
 
 Open **http://localhost:8000** in any browser. All active pi sessions appear automatically. See [Prerequisites](#prerequisites) for Node.js / build-tool requirements.
 
+#### Windows install (PowerShell, Administrator)
+
+Windows has a few extra one-time setup steps. Run the following in an **Administrator** PowerShell session:
+
+```powershell
+# 1. Enable long paths (required — npm node_modules nesting exceeds 260 chars)
+reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
+
+# 2. Install Node.js LTS 22 via winget (ships >= 22.18 so no node-guard refusal)
+winget install -e --id OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements
+
+# 3. CLOSE this PowerShell, open a NEW one as Administrator (PATH refresh)
+
+# 4. Verify
+node --version    # expect v22.18+ (any 22.x >= 22.18, NOT v22.0–v22.17)
+npm --version     # expect 10.x
+
+# 5. Install
+npm install -g @blackbelt-technology/pi-agent-dashboard
+
+# 6. Start (foreground first time so you can see any errors)
+pi-dashboard start
+
+# 7. From the browser
+start http://localhost:8000
+```
+
+C++ build tools are typically **not** required — `node-pty` ships a Windows x64 prebuild. Install Visual Studio Build Tools only if the prebuild fails to load. See [docs/installation-windows.md](docs/installation-windows.md) for more detail (offline / tarball / nvm-windows caveats).
+
 ### C — From source (contributors)
 
 ```bash
 git clone https://github.com/BlackBeltTechnology/pi-agent-dashboard.git
 cd pi-agent-dashboard
 npm install
+npm run build                              # one-time client build
 pi install /path/to/pi-agent-dashboard     # global
 # or: pi install -l /path/to/pi-agent-dashboard   # project-local only
 ```
 
+#### Use the local checkout as the global `pi-dashboard` command
+
+By default, `pi-dashboard` on your PATH refers to whatever copy was installed globally (via `npm i -g` or the Electron bundle). To make it point at your working tree instead — so every edit is live and bridge auto-start uses your changes — link the workspace:
+
+```bash
+npm run link:local      # symlinks `pi-dashboard` on PATH to packages/server/bin/pi-dashboard.mjs
+pi-dashboard status
+npm run unlink:local    # restore (removes the global symlink)
+```
+
+The link survives across shells. Every invocation — including `pi`'s bridge auto-spawn — runs `packages/server/src/cli.ts` via jiti, so you don't need to rebuild the server on edits. The client still requires `npm run build` (or `npm run dev` for HMR).
+
+> **Windows note:** symlink creation needs an admin shell or Windows Developer Mode enabled. Everything else works the same as POSIX.
+
 To try the extension in a single pi session without registering it:
 
 ```bash
@@ -408,7 +462,7 @@ The dashboard integrates tightly with a small, curated set of pi extensions —
 | Extension | Source | Status | Unlocks |
 |---|---|---|---|
 | `pi-anthropic-messages` | `git@github.com:BlackBeltTechnology/pi-anthropic-messages.git` | **required** | Tool calls on Claude-model Anthropic OAuth / 9Router `cc/*` / pi-model-proxy providers. Without it, tool calls fall back to Claude Code's built-in `bash_ide` sandbox and fail. |
-| `@tintinweb/pi-subagents` | `npm:@tintinweb/pi-subagents` | strongly suggested | `Agent` tool card UI, subagent activity badge, `get_subagent_result` / `steer_subagent` renderers |
+| `pi-dashboard-subagents` | `https://github.com/BlackBeltTechnology/pi-dashboard-subagents.git` | optional (bundled) | `Agent` tool card UI, subagent inspector (inline expand + popout), agent-md path display |
 | `pi-flows` | `git@github.com:BlackBeltTechnology/pi-flows.git` | strongly suggested | Flow dashboard, role aliases (`@planning`, `@coding`, …), subagent / flow_write / flow_results / agent_write / ask_user / skill_read / finish tools |
 | `pi-web-access` | `npm:pi-web-access` | strongly suggested | `web_search`, `code_search`, `fetch_content`, `get_search_content` |
 | `pi-agent-browser` | `npm:pi-agent-browser` | optional | `browser` tool (open, snapshot, click, screenshot) |
@@ -765,6 +819,20 @@ This runs CI, publishes to npm with `--provenance` for supply-chain transparency
 
 All artifacts are uploaded to a **draft GitHub Release**. Release notes are extracted automatically from the matching `## [<version>]` section of [`CHANGELOG.md`](CHANGELOG.md).
 
+### On-demand Electron build (CI dispatch)
+
+Build a one-off installer for a feature branch. No release, no publish, no tag.
+
+Workflow: [`.github/workflows/ci-electron.yml`](.github/workflows/ci-electron.yml). Trigger from GitHub Actions tab → **CI Electron (on-demand)** → **Run workflow** button.
+
+Optional `legs` input narrows the matrix (default `all`; accepts `darwin`, `linux`, `win32`, or comma-list like `darwin-arm64,linux-x64` for cheap iteration).
+
+Version slug: `<base>-ci.<UTC-stamp>.<branch-slug>.<sha7>` (e.g. `0.5.3-ci.20260525-143000.feature-foo-bar.abc1234`). Prerelease segment SemVer-ranks below `<base>`.
+
+Download installers from the Actions run page → **Artifacts** section. 14-day retention.
+
+Safe by construction: no npm publish, no GitHub Release, no auto-update impact. `electron-updater` default `allowPrerelease: false` skips `-ci.` slugs — installed users unaffected.
+
 ### Trusted Publisher (OIDC) setup
 
 The publish workflow uses **[npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers)** over OIDC — **no `NPM_TOKEN` secret required**. Short-lived, workflow-scoped credentials are exchanged between GitHub and npm at publish time, and every release carries automatic [npm provenance](https://docs.npmjs.com/generating-provenance-statements) tying the published artifact to the exact workflow run.