Dashboard — Local Launch & Single-File Snapshot Export

Purpose

E05–E09 built a working local dashboard (Express API + Vite/React UI under project/app/api and project/app/ui), already reachable via npm run dashboard:start / npm run dashboard:open at the repo root (which shell into project/app/ui/scripts/dashboard-start.cjs). This skill is a thin, session-level entry point to those same scripts — it introduces no new server-launch, health-check, or build logic of its own. All actual implementation lives in the .cjs script this skill wraps; do not duplicate it here or in scripts/launch.sh.

--snapshot (E47_S04_T02/T03) is a second, independent mode: it captures the API's /v1/board, /v1/history, and /v1/architecture responses once, bakes that data inline into the UI build, and inlines all JS/CSS into a single, fully self-contained HTML file (default jenga.html) — viewable via file:// with no running server, so it can be handed to someone on another device. It does not start a long-running server and does not open a browser; it is a one-shot export. --data-url (E47_S04_T04) is an additive delivery mode for --snapshot: since the output file is already fully self-contained, it can be base64-encoded into a data:text/html;base64,... URI that any browser can open directly — no shared filesystem, hosting, or git round-trip needed, which matters when the agent is running remotely (e.g. a cloud/remote session) and cannot hand the user a local path.

Instructions

1. Parse the invocation. This skill accepts either:

   • The default/launch form: an optional first word — start or open — and an optional --port <n> flag (forwarded unchanged to the underlying npm script). start launches the API and serves the UI. open does the same and also opens the dashboard in the browser. Either accepts --api-only to launch the API without the UI (not combined with open).
   • The snapshot/export form: --snapshot, optionally with --out <path> (default jenga.html in the current working directory).

   If the user's phrasing already makes the intent unambiguous (e.g. "start the dashboard", "open the dashboard in my browser", "launch the dashboard and open it", "start the dashboard API only", "export a snapshot of the dashboard"), map it directly and skip the prompt in step 2.

2. No explicit mode given — ask. If intent isn't already clear from the invocation, use CLAUDE.md's standard Interaction Pattern rather than guessing:

   What would you like to do?
   1. Start the dashboard (API + UI) (npm run dashboard:start)
   2. Start the dashboard and open it in your browser (npm run dashboard:open)
   3. Export a single-file snapshot (--snapshot) — a portable, offline-viewable HTML file
   4. Other (describe below)

   Map option 1 -> start, option 2 -> open, option 3 -> --snapshot.

3. Default/launch form — run the wrapper script. Invoke skills/j-dashboard/scripts/launch.sh <mode> [--port <n>] [--api-only] with the resolved mode and any forwarded flags. The script:
   • Delegates to npm run dashboard:start / npm run dashboard:open inside project/app — the same underlying commands npm run dashboard:start / dashboard:open at the repo root run. Flags are forwarded unchanged; the UI is served unless --api-only is given.
   • Resolves project/app via the shared resolve-app-dir.sh, which checks this package's own root, the git repo root, and node_modules/@jenga-ai/agent/project/app — the last of these is where the dashboard actually lives in a consumer install, and assuming the repo root (as this script originally did) broke j.dashboard on every consumer.
   • Exits non-zero with a clear message if no project/app can be resolved, or if the underlying npm script itself fails (e.g. --port validation, missing dependencies).
4. --snapshot form — run the snapshot script. Invoke skills/j-dashboard/scripts/snapshot.sh [--out <path>] [--data-url]. The script:
   • Captures the invoking directory (before any internal cd) so data is resolved against the invoking project, per E47_S02's generalized data-source resolution — not this repo's own data, unless that happens to be the invoking project.
   • Runs E47_S04_T02's capture step (project/app/api/scripts/capture-snapshot.js) to collect /v1/board, /v1/history, and /v1/architecture into one JSON artifact.
   • Runs project/app/ui/scripts/build-snapshot-html.cjs, which inlines the built dist/ (JS + CSS) into a single index.html and embeds that JSON as a <script id="jenga-dashboard-data"> tag. It has zero dependencies, so it behaves identically here and in a consumer install — which only ever receives the prebuilt dist/. Where the UI sources and node_modules are present, dist/ is rebuilt first so a snapshot is never taken from a stale build. In a dev checkout where dist/ is missing or older than the UI sources and node_modules/vite is not installed, the script runs npm install and npm run build in project/app/ui itself first, so no manual install-and-rebuild step is needed; a fresh dist/ skips both. Consumer installs, which ship only the prebuilt dist/, never trigger either. (This replaced a vite build --mode snapshot step that could only ever run inside this monorepo; the tarball ships no vite and no UI sources, so --snapshot previously failed on 100% of consumer installs.)
   • Copies the result to the final output path (default jenga.html in the invoking directory, overridable via --out <path>).
   • Fails loudly with no output file written if either the capture or bundling step fails — never a partial/broken snapshot.
   • With --data-url (E47_S04_T04): after the copy step above, base64-encodes the output file and also prints a data:text/html;base64,... URI to stdout — additive to, not a replacement for, the plain-path report. Refuses (non-zero exit, no URI printed) if the encoded size exceeds a ~25MB threshold rather than silently emitting an oversized URI.

5. Relay output — pick the delivery mode based on filesystem sharing. Before invoking the snapshot script, judge whether this session can assume a shared filesystem with the user:

   • Shared filesystem (default — a normal local/IDE session): run snapshot.sh [--out <path>] without --data-url and report the local file path exactly as the script prints it (e.g. "Snapshot dashboard written to: <path>") — the user can open that path directly.
   • No shared filesystem assumable (e.g. a remote/cloud agent session): run snapshot.sh [--out <path>] --data-url and relay the printed data:text/html;base64,... URI back to the user as a clickable markdown link, e.g. [Open dashboard snapshot](data:text/html;base64,...), since the user has no way to fetch the file's bytes off this session's filesystem otherwise. If the script refuses due to the size threshold, relay that refusal message as-is rather than falling back to the plain path silently — the plain path is not reachable by this user in this scenario either.

   In both cases, print the rest of the script's stdout/stderr back to the user as-is — do not reinterpret, summarize away, or suppress error output from the underlying scripts; they already produce user-facing messages (e.g. "Dashboard API running at http://localhost:3001", "Snapshot dashboard written to: <path>").

6. start and open are long-running. dashboard:start and dashboard:open run a foreground server process that does not exit on its own. When running either as part of an interactive session, make sure the user understands the command will keep running until stopped (Ctrl-C) — don't silently block the conversation waiting on it. --snapshot is a one-shot export and always terminates.

Out of Scope

• Any change to project/app/package.json's dashboard:start/dashboard:open scripts or to dashboard-start.cjs — this skill only invokes them. Fixes or feature changes to the dashboard itself belong to those files' own epics (E05-E09, E47), not here.
• Resolving dashboard data against a consumer project's own project/ directory rather than this monorepo's — that's E47_S02's scope (already reused, not duplicated, by both launch.sh and snapshot.sh's capture step).
• Any new capture/bundling logic beyond invoking capture-snapshot.js and build-snapshot-html.cjs — those live in project/app/api/scripts/capture-snapshot.js and project/app/ui/scripts/build-snapshot-html.cjs respectively.