@blackbelt-technology/pi-agent-dashboard 0.4.5 → 0.5.0

package/README.md

@@ -21,6 +21,7 @@ A web-based dashboard for monitoring and interacting with [pi](https://github.co
 - [Configuration](#configuration)
 - [Usage](#usage)
 - [Recommended extensions](#recommended-extensions)
+- [Authoring a dashboard plugin](#authoring-a-dashboard-plugin)
 - [Troubleshooting](#troubleshooting)
 - [Architecture](#architecture)
 - [Monitoring](#monitoring)
@@ -47,6 +48,10 @@ Download a pre-built installer from [GitHub Releases](https://github.com/BlackBe
 
 On first launch a setup wizard walks you through mode selection (standalone vs. power-user), API key / OAuth sign-in, and [recommended extensions](#recommended-extensions). The standalone mode bundles Node.js and auto-installs pi + dashboard + openspec into `~/.pi-dashboard/` — **no terminal, npm, or Node.js required**.
 
+**Picking the right macOS DMG:** run `uname -m` in Terminal — `arm64` means Apple Silicon (M1/M2/M3/M4), `x86_64` means Intel. Or open   Apple menu → About This Mac and read the chip name. Download the matching DMG; if you grab the wrong one macOS will refuse to launch the app with a "cannot be opened" error.
+
+> **Note:** A future release will rename the macOS DMGs to `PI-Dashboard-darwin-arm64-<ver>.dmg` and `PI-Dashboard-darwin-x64-<ver>.dmg` (previously a single `PI Dashboard.dmg` was produced and silently overwrote one arch on each release). Direct download links pointing at the unsuffixed filename will 404 from that release onward; please link to the [Releases page](https://github.com/BlackBeltTechnology/pi-agent-dashboard/releases) instead. See OpenSpec change `fix-darwin-dmg-arch-collision`.
+
 ### B — pi package (recommended for CLI users)
 
 ```bash
@@ -98,6 +103,7 @@ Remove with `pi remove /path/to/pi-agent-dashboard`. Alternatively, add the pack
 - **Command autocomplete** — `/` prefix triggers a filtering dropdown
 - **Mobile-friendly** — responsive layout with swipe drawer, touch targets, and mobile action menus
 - **Markdown preview** — rendered markdown views with search, mermaid diagrams, syntax highlighting, and safe handling for raw HTML `ref` attributes
+- **Local-image inlining + LaTeX math in chat** — agents can reference local screenshots inline as `![alt](/abs/path.png)` or `![alt](./relative.png)` and they render in chat (the bridge inlines bytes via a streaming-safe `pi-asset:<hash>` channel — each unique image's bytes ride exactly once per session, no matter how many streaming chunks repeat the token). Math expressions — inline `$x = \beta$` and display `$$\sum_i^n i$$` (block-level) — are typeset via KaTeX. PNG / JPEG / GIF / WebP / SVG / AVIF / BMP supported with a 5 MB-per-image, 20 MB-per-message cap; oversized or unreadable references render as a visible placeholder rather than a broken-image glyph. The dashboard server adds zero new HTTP routes.
 - **Searchable select dialogs** — keyboard-navigable picker with real-time filtering (OpenSpec changes, flow commands)
 
 **Integrations**
@@ -111,8 +117,9 @@ Remove with `pi remove /path/to/pi-agent-dashboard`. Alternatively, add the pack
 
 **Dev tools**
 - **Integrated terminal** — full browser-based terminal emulator (xterm.js + node-pty) with ANSI colors, scrollback, and keep-alive
-- **Diff viewer** — side-by-side and unified diff views with file tree navigation
+- **Diff viewer** — side-by-side and unified diff views with file tree navigation. In Jujutsu workspaces the diff is regime-aware: shows the cumulative changes since the workspace's branch point, not just the working-copy delta.
 - **Editor integration** — open files in VS Code, Cursor, etc. directly from tool call cards
+- **Jujutsu workspaces (optional)** — when `jj` is on PATH and the session is inside a `.jj/` repo, the dashboard surfaces a workspace badge, a `+ Workspace` action that creates `jj workspace add` + spawns a fresh agent in it, and a `Fold back` action that drives the [`jj-workspace-fold-back`](.pi/skills/jj-workspace-fold-back/SKILL.md) skill (jj-native rebase + push, never `git commit`/`git merge`). Activates silently — zero UI when `jj` is not installed. See [docs/architecture.md](docs/architecture.md#jujutsu-workspaces) for the data flow.
 
 **Networking & distribution**
 - **Network discovery** — mDNS-based auto-discovery of other dashboard servers on the local network
@@ -161,6 +168,7 @@ CLI flags → environment variables → config file → built-in defaults.
 | — | — | `spawnStrategy` | `"headless"` | Session spawn mode: `"headless"` or `"tmux"` |
 | — | — | `reattachPlacement` | `"always"` | After a dashboard restart, where re-registering bridges land in folder lists. `"always"` (top), `"streaming-only"` (only mid-completion), `"preserve"` (legacy: keep prior drag order) |
 | — | — | `devBuildOnReload` | `false` | Rebuild client + restart server on `/reload` |
+| — | — | `askUserPromptTimeoutSeconds` | `300` | `ask_user` prompt timeout in seconds. `≤ 0` (e.g. `-1`) = wait indefinitely |
 
 The bridge also honours `PI_DASHBOARD_URL=ws://host:port` to point at a remote server instead of localhost.
 
@@ -176,6 +184,7 @@ The bridge also honours `PI_DASHBOARD_URL=ws://host:port` to point at a remote s
   "spawnStrategy": "headless",
   "tunnel": { "enabled": true, "reservedToken": "auto-created-on-first-run" },
   "devBuildOnReload": false,
+  "askUserPromptTimeoutSeconds": 300,
   "openspec": {
     "pollIntervalSeconds": 30,
     "maxConcurrentSpawns": 3,
@@ -213,6 +222,8 @@ OAuth2 authentication guards external (tunnel) access. Localhost is always ungua
 
 **Callback URL:** register `https://<tunnel-url>/auth/callback/<provider>` in your OAuth provider settings. The tunnel URL is stable across restarts (reserved shares are auto-created).
 
+> **Security note:** `/api/spawn-failures` is reachable to any caller on deployments without auth; entries contain `cwd` paths. Enable auth before exposing via tunnel.
+
 ### Tunnel (zrok)
 
 The dashboard auto-connects a [zrok](https://zrok.io/) tunnel on start when `tunnel.enabled` is `true`. Install with `brew install zrok` (macOS) and run `zrok enable <token>` to enrol — the dashboard reads zrok's own config (`~/.zrok2/environment.json`), no keys are stored in the dashboard. Reserved shares provide persistent URLs across restarts.
@@ -258,6 +269,10 @@ The file is deliberately separate from `config.json` so machine-specific paths d
 
 The bridge extension **automatically starts the dashboard server** when pi launches if it's not already running. Disable with `"autoStart": false` in `~/.pi/dashboard/config.json`.
 
+In the Electron app, if the initial launch attempts fail (or the server is stopped externally), the **loading page exposes a Start server button**, an **Open Doctor link**, and a collapsible **Server log** panel showing the last 20 lines of `~/.pi/dashboard/server.log`. The system tray menu also includes a **Start server / Restart server** item that reflects current server state. All entry points share a single idempotent launch routine in the Electron main process.
+
+**Doctor diagnostics.** Help → Doctor (or the loading-page link) opens a styled `BrowserWindow` (`doctor.html`) that runs the same checks the Electron app already performed — grouped into sections (Runtime, Pi, Server, Bundles, Diagnostics) with status pills, paths, and per-row suggestion callouts; toolbar offers Re-run, Copy as Markdown / Plain, Open server log, Open doctor log, Run setup wizard. The web client exposes the portable subset at **Settings → Diagnostics**, which fetches `/api/doctor` and renders the same sections (Electron-only rows omitted). Both surfaces share `packages/shared/src/doctor-core.ts`, so a check defined once shows up everywhere.
+
 ### Daemon mode
 
 ```bash
@@ -360,6 +375,29 @@ Authoritative source: `packages/shared/src/recommended-extensions.ts`. Descripti
 
 ---
 
+## Authoring a dashboard plugin
+
+The dashboard's UI is composed of named **slots** that plugins claim with React components. To create a new plugin, install the scaffolding skill:
+
+```bash
+npm i -g @blackbelt-technology/pi-dashboard-plugin-skill
+```
+
+Then, from any pi session:
+
+```
+/skill dashboard-plugin-scaffold
+```
+
+The skill has two modes:
+
+- **`new`** — scaffold a fresh `packages/<id>-plugin/` inside this monorepo. Pick which of the 10 React slots to claim (`session-card-badge`, `content-view`, `settings-section`, `tool-renderer`, …); the skill renders package.json (with `pi-dashboard-plugin` manifest), `src/client.tsx` with stubs, optional `src/server/index.ts`, optional `src/bridge/index.ts`, `configSchema.json`, and tests.
+- **`augment`** — retrofit an existing pi-extension project on disk. The skill greps for TUI surface (`ctx.ui.*`, `pi.registerTool`, …), drives the agent through a canonical mapping table, asks per-callsite what to port, then injects a manifest field into `package.json` and adds `src/dashboard/`. Purely additive — your existing TUI keeps working in pure-pi sessions.
+
+For the slot taxonomy, the manifest schema, and the plugin context API, see the skill's reference docs (or the runtime: [`@blackbelt-technology/dashboard-plugin-runtime`](https://www.npmjs.com/package/@blackbelt-technology/dashboard-plugin-runtime)). The reference fixture is [`packages/demo-plugin/`](packages/demo-plugin/).
+
+---
+
 ## Troubleshooting
 
 ### Dashboard server doesn't start
@@ -615,6 +653,16 @@ npm run electron:build -- --windows          # Windows .exe (NSIS) only
 npm run electron:build -- --linux --windows  # Both, skip native
 ```
 
+### Building both macOS DMGs locally (`--mac-both`)
+
+On an Apple Silicon mac, produce both the arm64 and Intel x64 DMGs in one invocation:
+
+```bash
+npm run electron:build -- --mac-both
+```
+
+Requires Rosetta 2 (`softwareupdate --install-rosetta --agree-to-license`) so node-pty's x64 prebuilt binary can be unpacked during the cross-arch run. The script wipes per-arch caches between the two builds (`resources/.last-arch` sentinel) so back-to-back runs don't accidentally ship arm64 binaries inside an x64 DMG. Intel macs cannot cross-build arm64 locally (Rosetta is one-way) — use CI for arm64 validation.
+
 Docker builds use a Node 22 Debian container with NSIS installed for Windows cross-compilation. Output goes to `packages/electron/out/make/`.
 
 ### Electron dev mode
@@ -666,7 +714,8 @@ This runs CI, publishes to npm with `--provenance` for supply-chain transparency
 
 | Runner | Platform | Outputs |
 |--------|----------|---------|
-| `macos-14` | macOS arm64 | `.dmg` |
+| `macos-14` | macOS arm64 | `.dmg` (Apple Silicon) |
+| `macos-15-intel` | macOS x64 | `.dmg` (Intel; last GitHub-hosted x86_64 image, EOL 2027-08) |
 | `ubuntu-latest` | Linux x64 | `.deb` + `.AppImage` |
 | `ubuntu-24.04-arm` | Linux arm64 | `.deb` |
 | `windows-latest` | Windows x64 | `.exe` (NSIS) + `.zip` + portable |