@jenga-ai/agent 3.2.0 → 3.4.0

package/skills/j-cloud-connect/scripts/configure-backend.sh

@@ -0,0 +1,267 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-cloud-connect/scripts/configure-backend.sh
+#
+# Core of the j-cloud-connect setup wizard (E60_S01_T02): dynamic backend
+# selection, that backend's own `rclone config create` flow, an explicit
+# wait for user confirmation of any auth step it produced, then independent
+# post-confirmation verification.
+#
+#   1. Backend menu is sourced LIVE from `rclone config providers` — never a
+#      hardcoded list. This is true for both the printed menu and the
+#      validation of a backend name passed as an argument.
+#   2. Once a backend type + remote name are known (from arguments, or from
+#      an interactive prompt driven by that same live menu), this script runs
+#      `rclone config create <remote> <backend>` with stdin/stdout/stderr
+#      fully inherited — no capturing, no re-formatting. Whatever that
+#      backend's own flow prints, including an OAuth auth URL, reaches the
+#      user exactly as rclone presents it. This script never parses or
+#      special-cases any backend's own prompts.
+#   3. After `config create` returns, this script explicitly asks the user to
+#      confirm they've completed setup/authorization before doing anything
+#      else — it never just detects "not configured" and stops, and it never
+#      infers completion on its own.
+#   4. Only after that confirmation, `rclone about <remote>:` is run to
+#      INDEPENDENTLY verify the remote actually works. The user's
+#      confirmation is never itself treated as success — a PASS/FAIL verdict
+#      always comes from this real check.
+#
+# The exact same code path runs regardless of which backend was selected;
+# there is no per-backend branch anywhere below beyond what rclone's own
+# `config create` already does internally per-backend.
+#
+# This script assumes `rclone` is already on PATH (see install-rclone.sh,
+# E60_S01_T01) and that `jq` is available (already a repo-wide dependency
+# used to parse rclone's JSON provider list).
+#
+# Invoked via `bash`, not executed directly — it intentionally ships without
+# the executable bit, matching the convention already documented in this
+# skill's install-rclone.sh and in skills/j-dashboard/scripts/resolve-app-dir.sh.
+# Whatever wires this into the j-cloud-connect skill (E60_S01_T03) should
+# invoke it as `bash skills/j-cloud-connect/scripts/configure-backend.sh`.
+#
+# Usage:
+#   configure-backend.sh --list
+#   configure-backend.sh [<backend-type> <remote-name>]
+#
+#   --list                     Print the live backend menu and exit. No side
+#                               effects.
+#   <backend-type> <remote-name>
+#                               Skip interactive selection; configure the
+#                               given backend under the given remote name.
+#                               <backend-type> is still validated against the
+#                               live provider list before use.
+#   (no arguments)              Print the live menu, prompt for a numeric
+#                               selection and a remote name, then proceed
+#                               through the same configure/confirm/verify
+#                               flow as the two-argument form above.
+#
+# Exit codes:
+#   0  --list succeeded, OR the remote was configured, confirmed, and
+#      independently verified working (rclone about succeeded).
+#   1  Any failure: rclone/jq missing, provider list unreadable, invalid
+#      backend/selection, `rclone config create` failed, the user declined
+#      to confirm setup was complete, or post-confirmation verification
+#      (`rclone about`) failed. A human-readable reason is always printed.
+# -----------------------------------------------------------------------------
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  configure-backend.sh --list
+  configure-backend.sh [<backend-type> <remote-name>]
+
+Sources a backend menu live from `rclone config providers`, runs the
+selected backend's own `rclone config create` flow (surfacing any auth URL
+it produces directly, with stdio fully inherited), waits for explicit user
+confirmation that setup/authorization is complete, then independently
+verifies the remote via `rclone about <remote>:` and reports PASS/FAIL.
+
+  --list                        Print the live backend menu and exit.
+  <backend-type> <remote-name>  Skip interactive selection.
+  (no arguments)                Prompt interactively for both.
+
+Exits 0 only once the remote is configured, confirmed, AND independently
+verified working. Exits 1 on any failure, including a declined confirmation
+or a failed post-confirmation verification — a user's confirmation alone is
+never treated as success.
+EOF
+}
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+# -----------------------------------------------------------------------------
+# Preflight — required tools.
+# -----------------------------------------------------------------------------
+
+require_rclone() {
+  command -v rclone >/dev/null 2>&1 || die "rclone is not on PATH. Install it first (see skills/j-cloud-connect/scripts/install-rclone.sh) and re-run."
+}
+
+require_jq() {
+  command -v jq >/dev/null 2>&1 || die "'jq' is required to parse rclone's provider list but is not on PATH. Install jq and re-run."
+}
+
+# -----------------------------------------------------------------------------
+# Live backend list — sourced from rclone itself, never hardcoded.
+# -----------------------------------------------------------------------------
+
+# Prints the raw `rclone config providers` JSON on stdout. Dies with rclone's
+# own captured output on any failure (command failure or non-array JSON).
+fetch_providers_json() {
+  local json
+  if ! json="$(rclone config providers 2>&1)"; then
+    die "'rclone config providers' failed: $json"
+  fi
+  if ! printf '%s' "$json" | jq -e 'type == "array"' >/dev/null 2>&1; then
+    die "'rclone config providers' did not return a valid JSON array of backends. Output: $json"
+  fi
+  printf '%s' "$json"
+}
+
+# print_backend_menu <providers-json>
+print_backend_menu() {
+  printf '%s' "$1" | jq -r 'to_entries[] | "\(.key + 1)) \(.value.Name) — \(.value.Description)"'
+}
+
+# backend_name_at_index <providers-json> <1-based-index>
+backend_name_at_index() {
+  local json="$1" index="$2"
+  printf '%s' "$json" | jq -r --argjson i "$((index - 1))" '.[$i].Name // empty'
+}
+
+# backend_exists <providers-json> <backend-name>
+backend_exists() {
+  local json="$1" name="$2"
+  printf '%s' "$json" | jq -e --arg n "$name" 'any(.[]; .Name == $n)' >/dev/null 2>&1
+}
+
+# -----------------------------------------------------------------------------
+# Argument parsing.
+# -----------------------------------------------------------------------------
+
+LIST_ONLY=0
+BACKEND_TYPE=""
+REMOTE_NAME=""
+
+case "${1:-}" in
+  -h|--help)
+    usage
+    exit 0
+    ;;
+  --list)
+    LIST_ONLY=1
+    if [ "$#" -gt 1 ]; then
+      usage >&2
+      die "unexpected extra arguments after --list"
+    fi
+    ;;
+  "")
+    ;;
+  *)
+    if [ "$#" -ne 2 ]; then
+      usage >&2
+      die "expected exactly two arguments (<backend-type> <remote-name>), got $#"
+    fi
+    BACKEND_TYPE="$1"
+    REMOTE_NAME="$2"
+    ;;
+esac
+
+require_rclone
+require_jq
+
+PROVIDERS_JSON="$(fetch_providers_json)"
+
+if [ "$LIST_ONLY" -eq 1 ]; then
+  echo "Backends supported by your installed rclone:"
+  print_backend_menu "$PROVIDERS_JSON"
+  exit 0
+fi
+
+# -----------------------------------------------------------------------------
+# Step 1 — Resolve a backend type and remote name (from args, or
+# interactively from the same live menu). Both paths converge below into the
+# identical configure/confirm/verify flow.
+# -----------------------------------------------------------------------------
+
+if [ -z "$BACKEND_TYPE" ]; then
+  echo "Select a cloud storage backend:"
+  print_backend_menu "$PROVIDERS_JSON"
+  SELECTION=""
+  read -r -p "Enter the number of the backend to configure: " SELECTION || die "no input provided for the backend selection prompt (unexpected end of input)."
+  case "$SELECTION" in
+    ''|*[!0-9]*) die "invalid selection '$SELECTION' — expected a number from the list above." ;;
+  esac
+  BACKEND_TYPE="$(backend_name_at_index "$PROVIDERS_JSON" "$SELECTION")"
+  [ -n "$BACKEND_TYPE" ] || die "invalid selection '$SELECTION' — no backend at that number."
+
+  REMOTE_NAME=""
+  read -r -p "Enter a name for this remote (e.g. 'gdrive'): " REMOTE_NAME || die "no input provided for the remote name prompt (unexpected end of input)."
+  [ -n "$REMOTE_NAME" ] || die "a remote name is required."
+else
+  backend_exists "$PROVIDERS_JSON" "$BACKEND_TYPE" || die "'$BACKEND_TYPE' is not a backend your installed rclone supports. Run this script with --list to see the current list."
+fi
+
+# -----------------------------------------------------------------------------
+# Step 2 — Run the backend's own `rclone config create` flow. stdio is fully
+# inherited (no capture, no suppression): any prompts or auth URL this
+# produces reach the user exactly as rclone presents them. Identical for
+# every backend — no per-backend branch here.
+# -----------------------------------------------------------------------------
+
+echo ""
+echo "Running: rclone config create $REMOTE_NAME $BACKEND_TYPE"
+echo "Follow any prompts below, including opening any authorization link shown,"
+echo "exactly as rclone presents them."
+echo ""
+
+CONFIG_EXIT=0
+rclone config create "$REMOTE_NAME" "$BACKEND_TYPE" || CONFIG_EXIT=$?
+if [ "$CONFIG_EXIT" -ne 0 ]; then
+  die "'rclone config create $REMOTE_NAME $BACKEND_TYPE' exited with status $CONFIG_EXIT. Remote was not configured — see rclone's output above for the reason."
+fi
+
+# -----------------------------------------------------------------------------
+# Step 3 — Wait for EXPLICIT user confirmation before proceeding any further.
+# Never inferred, never skipped.
+# -----------------------------------------------------------------------------
+
+echo ""
+echo "If rclone showed an authorization link above, open it now and complete the"
+echo "authorization before continuing."
+CONFIRM=""
+read -r -p "Have you finished completing setup/authorization for '$REMOTE_NAME'? [y/N] " CONFIRM || die "no input provided for the confirmation prompt (unexpected end of input)."
+case "$CONFIRM" in
+  [Yy]|[Yy][Ee][Ss])
+    ;;
+  *)
+    die "Setup was not confirmed complete. Re-run this script once you've finished authorization for '$REMOTE_NAME' — verification was skipped, so it has NOT been confirmed working."
+    ;;
+esac
+
+# -----------------------------------------------------------------------------
+# Step 4 — Independently verify the remote actually works. Confirmation
+# alone is NEVER treated as success — this real check decides PASS/FAIL.
+# -----------------------------------------------------------------------------
+
+echo ""
+echo "Verifying remote '$REMOTE_NAME'..."
+
+VERIFY_EXIT=0
+VERIFY_OUTPUT="$(rclone about "$REMOTE_NAME": 2>&1)" || VERIFY_EXIT=$?
+
+if [ "$VERIFY_EXIT" -eq 0 ]; then
+  echo "PASS: remote '$REMOTE_NAME' is configured and verified working."
+  echo "$VERIFY_OUTPUT"
+  exit 0
+else
+  echo "FAIL: remote '$REMOTE_NAME' did not verify — 'rclone about $REMOTE_NAME:' failed (exit $VERIFY_EXIT)." >&2
+  echo "$VERIFY_OUTPUT" >&2
+  exit 1
+fi

package/skills/j-cloud-connect/scripts/install-rclone.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-cloud-connect/scripts/install-rclone.sh
+#
+# Detects whether `rclone` is already on PATH and, if not, installs it
+# automatically for the current OS:
+#   - macOS: via `brew install rclone` (requires Homebrew already installed)
+#   - Linux: via rclone's official install script
+#     (`curl https://rclone.org/install.sh | sudo bash`)
+#
+# This is standalone install-detection/automation ONLY (E60_S01_T01's scope).
+# It does NOT configure any remote and does NOT run any auth flow — that is
+# E60_S01_T02's scope, layered on top of this script later.
+#
+# Every failure path (unsupported OS, no package manager, sudo unavailable,
+# network failure) exits non-zero with an actionable message. Success is
+# NEVER reported without re-verifying, post-install, that `rclone` is both on
+# PATH and actually runnable (`rclone version` succeeds) — this script never
+# takes a package manager's reported success at face value.
+#
+# Invoked via `bash`, not executed directly: this script intentionally ships
+# without the executable bit, matching the same convention documented in
+# skills/j-dashboard/scripts/resolve-app-dir.sh's header — a shipped script
+# losing its executable bit (e.g. during packaging/distribution) is exactly
+# the class of failure this avoids by never depending on it in the first
+# place. Whatever wires this into the j-cloud-connect skill (E60_S01_T03)
+# should invoke it as `bash skills/j-cloud-connect/scripts/install-rclone.sh`.
+#
+# Usage:
+#   install-rclone.sh
+#
+# Exit codes:
+#   0  rclone is on PATH and runnable (already present, or freshly installed
+#      and re-verified).
+#   1  Installation could not proceed or could not be verified afterward.
+#      A human-readable reason is always printed to stderr.
+# -----------------------------------------------------------------------------
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: install-rclone.sh
+
+Detects whether `rclone` is on PATH. If missing, installs it automatically:
+  - macOS: `brew install rclone` (requires Homebrew)
+  - Linux: rclone's official install script (requires curl + sudo)
+
+Exits 0 only once `rclone` is confirmed on PATH and runnable. Exits 1 with an
+actionable message on every failure path (unsupported OS, no package manager,
+sudo/curl unavailable, network failure, or post-install re-verification
+failure).
+EOF
+}
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+case "${1:-}" in
+  -h|--help) usage; exit 0 ;;
+  "") ;;
+  *) usage >&2; die "unknown argument: $1" ;;
+esac
+
+# -----------------------------------------------------------------------------
+# Step 1 — Detection: skip installation entirely if rclone is already present.
+# -----------------------------------------------------------------------------
+
+if command -v rclone >/dev/null 2>&1; then
+  RCLONE_PATH="$(command -v rclone)"
+  RCLONE_VERSION="$(rclone version 2>/dev/null | head -n 1 || echo "unknown version")"
+  echo "rclone is already installed at $RCLONE_PATH ($RCLONE_VERSION) — skipping install."
+  exit 0
+fi
+
+echo "rclone not found on PATH. Attempting automatic install..."
+
+# -----------------------------------------------------------------------------
+# Step 2 — Post-install re-verification (defined up front, used by both OS
+# branches below). Never report success without this check actually passing.
+# -----------------------------------------------------------------------------
+
+verify_install() {
+  if ! command -v rclone >/dev/null 2>&1; then
+    die "install step ran but 'rclone' is still not on PATH. Installation did not succeed — see output above for details."
+  fi
+
+  local rclone_bin
+  rclone_bin="$(command -v rclone)"
+
+  if ! rclone version >/dev/null 2>&1; then
+    die "'rclone' was found on PATH at $rclone_bin after install, but 'rclone version' failed to run. The binary is present but not usable — installation did not succeed."
+  fi
+
+  local rclone_version
+  rclone_version="$(rclone version 2>/dev/null | head -n 1 || echo "unknown version")"
+  echo "rclone installed and verified successfully: $rclone_bin ($rclone_version)"
+}
+
+# -----------------------------------------------------------------------------
+# Step 3 — OS detection and OS-specific install.
+# -----------------------------------------------------------------------------
+
+OS_NAME="$(uname -s)"
+
+case "$OS_NAME" in
+  Darwin)
+    if ! command -v brew >/dev/null 2>&1; then
+      die "rclone is not installed and Homebrew ('brew') is not available on this macOS machine, so it cannot be installed automatically. Install Homebrew (https://brew.sh) and re-run, or install rclone manually from https://rclone.org/downloads/."
+    fi
+
+    echo "Installing rclone via Homebrew ('brew install rclone')..."
+    if ! brew install rclone; then
+      die "'brew install rclone' failed. This is commonly a network failure or a Homebrew environment issue — check the output above, then re-run. You can also install rclone manually from https://rclone.org/downloads/."
+    fi
+    ;;
+
+  Linux)
+    if ! command -v curl >/dev/null 2>&1; then
+      die "rclone is not installed and 'curl' is not available on this Linux machine, so the official install script cannot be downloaded. Install curl (e.g. 'apt install curl' / 'yum install curl') and re-run, or install rclone manually from https://rclone.org/downloads/."
+    fi
+    if ! command -v sudo >/dev/null 2>&1; then
+      die "rclone is not installed and 'sudo' is not available on this Linux machine, but is required by rclone's official install script. Install rclone manually (as a privileged user) from https://rclone.org/downloads/, or make sudo available and re-run."
+    fi
+
+    echo "Installing rclone via the official install script (curl https://rclone.org/install.sh | sudo bash)..."
+
+    INSTALL_SCRIPT_TMP="$(mktemp)"
+    trap 'rm -f "$INSTALL_SCRIPT_TMP"' EXIT
+
+    if ! curl --fail --silent --show-error https://rclone.org/install.sh -o "$INSTALL_SCRIPT_TMP"; then
+      die "failed to download rclone's official install script from https://rclone.org/install.sh. This usually indicates no network access. Check your connection and re-run, or install rclone manually from https://rclone.org/downloads/."
+    fi
+
+    INSTALL_EXIT_CODE=0
+    sudo bash "$INSTALL_SCRIPT_TMP" || INSTALL_EXIT_CODE=$?
+    if [ "$INSTALL_EXIT_CODE" -ne 0 ]; then
+      die "rclone's official install script downloaded successfully but failed to run (exit status $INSTALL_EXIT_CODE). This may indicate a sudo/permission issue or an unsupported Linux environment — check the output above. You can also install rclone manually from https://rclone.org/downloads/."
+    fi
+    ;;
+
+  *)
+    die "unsupported OS '$OS_NAME' — this script only automates rclone install on macOS (via brew) and Linux (via rclone's official install script). Install rclone manually from https://rclone.org/downloads/."
+    ;;
+esac
+
+# -----------------------------------------------------------------------------
+# Step 4 — Re-verify before ever reporting success.
+# -----------------------------------------------------------------------------
+
+verify_install

package/skills/j-dashboard/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: j.dashboard
+description: Launch the local Jenga project dashboard (API + UI) by delegating to project/app's existing npm scripts — no new server or build logic. Also supports --snapshot, a single self-contained HTML export with a point-in-time data snapshot baked in, and --data-url for remote/no-shared-filesystem delivery.
+keywords:
+  - dashboard
+  - launch dashboard
+  - start dashboard
+  - open dashboard
+  - project dashboard
+  - snapshot dashboard
+  - export dashboard
+examples:
+  - "open the dashboard"
+  - "launch the project dashboard"
+  - "j.dashboard"
+  - "start the dashboard on port 4000"
+  - "export a snapshot of the dashboard"
+  - "j.dashboard --snapshot"
+  - "j.dashboard --snapshot --data-url"
+---
+
+# 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` /
+`dashboard-open.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 two `.cjs` scripts 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`, `open`, or `both` — and an
+     optional `--port <n>` flag (forwarded unchanged to whichever underlying npm script runs).
+     `start` additionally accepts `--serve-app` (forwarded unchanged; has no effect on `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", "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 server (npm run dashboard:start)
+   2. Open the dashboard in your browser (npm run dashboard:open) — assumes it's already running
+   3. Both — start the server, then open the browser
+   4. Export a single-file snapshot (--snapshot) — a portable, offline-viewable HTML file
+   5. Other (describe below)
+   ```
+
+   Map option 1 -> `start`, option 2 -> `open`, option 3 -> `both`, option 4 -> `--snapshot`.
+
+3. **Default/launch form — run the wrapper script.** Invoke `skills/j-dashboard/scripts/launch.sh
+   <mode> [--port <n>] [--serve-app]` with the resolved mode and any forwarded flags. The script:
+   - Delegates to `npm run dashboard:start` / `npm run dashboard:open` inside `project/app` — the
+     exact same commands `npm run dashboard:start` / `dashboard:open` at the repo root already run.
+   - For `both`, backgrounds the (long-running) server, waits briefly, then runs `open` — which
+     itself health-checks before opening the browser and always exits `0` regardless of outcome
+     (that is `dashboard-open.cjs`'s own documented contract, unchanged by this skill).
+   - 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. (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",
+   "⚠ Warning: Dashboard server does not appear to be running at ...", "Snapshot dashboard written
+   to: <path>").
+
+6. **`start` mode is long-running.** `dashboard:start` runs a foreground server process that does
+   not exit on its own. When running `start` (not `both`) 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,
+  `dashboard-start.cjs`, or `dashboard-open.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.