@jenga-ai/agent 3.2.0 → 3.4.0

package/skills/j-dashboard/scripts/launch.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-dashboard/scripts/launch.sh
+#
+# Thin wrapper around project/app's existing `dashboard:start` / `dashboard:open`
+# npm scripts (which themselves shell into
+# project/app/ui/scripts/dashboard-start.cjs / dashboard-open.cjs). This script
+# introduces NO server-launch, health-check, or browser-open logic of its own —
+# it only resolves paths and forwards flags to those existing scripts, per
+# E47_S04_T01's scope (the default, no-`--snapshot` launch mode of `j.dashboard`).
+#
+# Usage:
+#   launch.sh start [--port <n>] [--serve-app]
+#   launch.sh open  [--port <n>]
+#   launch.sh both  [--port <n>] [--serve-app]
+#
+# `both` starts the server in the background (it is long-running / blocking by
+# design — see dashboard-start.cjs), waits briefly, then runs `open`, which
+# itself health-checks before opening the browser and always exits 0 regardless
+# of outcome (dashboard-open.cjs's own documented contract).
+#
+# Same symlink-resolution + repo-root derivation pattern used elsewhere in this
+# skill library (e.g. skills/j-mirror-public/scripts/compute-publicize-diff.sh),
+# so this script behaves identically whether invoked directly or via a symlink,
+# and whether run from this monorepo or a mirrored/distributed copy.
+# -----------------------------------------------------------------------------
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: launch.sh <start|open|both> [--port <n>] [--serve-app]
+
+  start       Run `npm run dashboard:start` in project/app.
+  open        Run `npm run dashboard:open` in project/app.
+  both        Start the server in the background, then open the browser.
+
+  --port <n>       Forwarded unchanged to the underlying npm script.
+  --serve-app      Forwarded unchanged to `dashboard:start` only (ignored by `open`).
+EOF
+}
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+if [ $# -lt 1 ]; then
+  usage >&2
+  die "missing mode argument"
+fi
+
+MODE="$1"
+shift
+
+case "$MODE" in
+  start|open|both) ;;
+  -h|--help) usage; exit 0 ;;
+  *) usage >&2; die "unknown mode: $MODE (expected start|open|both)" ;;
+esac
+
+# -----------------------------------------------------------------------------
+# Locate script + repo root (symlink-resolved SCRIPT_DIR -> SKILL_DIR -> REPO_ROOT)
+# -----------------------------------------------------------------------------
+
+SCRIPT_PATH="${BASH_SOURCE[0]}"
+while [ -h "$SCRIPT_PATH" ]; do
+  LINK_TARGET="$(readlink "$SCRIPT_PATH")"
+  case "$LINK_TARGET" in
+    /*) SCRIPT_PATH="$LINK_TARGET" ;;
+    *)  SCRIPT_PATH="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)/$LINK_TARGET" ;;
+  esac
+done
+SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# project/app is NOT always at the repo root: in a consumer install it ships
+# inside the package, under node_modules/@jenga-ai/agent/. resolve-app-dir.sh
+# owns that whole search (and is shared with snapshot.sh) — see its header.
+# Invoked via `bash`, not executed directly: a shipped script losing its
+# executable bit is exactly the packaging defect this change also fixes, and
+# resolving the app dir must not be the thing that breaks when it happens.
+APP_DIR="$(bash "$SCRIPT_DIR/resolve-app-dir.sh" --marker "package.json" --from "$(pwd)")" \
+  || die "could not locate the dashboard app directory (see message above)"
+
+# Remaining args (--port <n>, --serve-app) are forwarded verbatim via the
+# "${EXTRA_ARGS[@]:-}" default-expansion form, not the bare "${EXTRA_ARGS[@]}"
+# form. On bash < 4.4 — notably including macOS's stock /bin/bash 3.2, which
+# `#!/usr/bin/env bash` resolves to by default on that platform — expanding
+# an empty array under `set -u` ("nounset") throws "unbound variable"; the
+# `:-` default (even though the default itself is empty) is an explicit,
+# nounset-safe form that keeps `set -u` in force everywhere in this script.
+# This preserves the `-- ` separator unconditionally (npm run <script> --
+# with nothing after it is a harmless no-op, and always including it avoids
+# reintroducing the nested-npm-run flag-forwarding bug this epic already hit
+# once — see epic E47's own history) rather than branching on argument count.
+EXTRA_ARGS=("$@")
+
+run_start() {
+  (cd "$APP_DIR" && npm run dashboard:start -- "${EXTRA_ARGS[@]:-}")
+}
+
+run_open() {
+  (cd "$APP_DIR" && npm run dashboard:open -- "${EXTRA_ARGS[@]:-}")
+}
+
+case "$MODE" in
+  start)
+    run_start
+    ;;
+  open)
+    run_open
+    ;;
+  both)
+    run_start &
+    START_PID=$!
+    echo "Started dashboard server in background (pid $START_PID)."
+    sleep 1
+    run_open
+    ;;
+esac

package/skills/j-dashboard/scripts/resolve-app-dir.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-dashboard/scripts/resolve-app-dir.sh
+#
+# Prints the absolute path of the dashboard's `project/app` directory, or exits
+# non-zero with a clear message if it cannot be found.
+#
+# Why this script exists
+# ----------------------
+# launch.sh and snapshot.sh both used to hard-code
+#
+#     APP_DIR="$(git rev-parse --show-toplevel)/project/app"
+#
+# which is only ever correct inside this monorepo. In a CONSUMER install the
+# dashboard does not live at the consumer repo root at all — it ships inside the
+# package, at <consumer>/node_modules/@jenga-ai/agent/project/app — so both
+# scripts died with "capture script not found" / "dashboard app not found" on
+# every consumer, no matter how well the package was built. Centralizing the
+# resolution here means that fallback exists once, for both callers, instead of
+# being duplicated (or, as it was, missing entirely).
+#
+# Resolution order — first candidate whose <candidate>/<marker> exists wins:
+#
+#   1. Package-root-relative: this script lives at
+#      <root>/skills/j-dashboard/scripts/, so <root>/project/app is three
+#      levels up. Covers the monorepo invoked directly AND the package invoked
+#      in place from node_modules/@jenga-ai/agent/skills/j-dashboard/scripts/.
+#   2. Git repo root: covers the monorepo invoked through a mirrored copy under
+#      .claude/skills/ or .agents/skills/, where (1) resolves to the mirror
+#      directory rather than the repo root.
+#   3. Git repo root + node_modules/@jenga-ai/agent: the consumer install case —
+#      the skill was mirrored into <consumer>/.claude/skills/ by postinstall, so
+#      neither (1) nor (2) can see the packaged app.
+#   4. Walk up from --from (default: cwd), checking both project/app and
+#      node_modules/@jenga-ai/agent/project/app at each level. Covers consumers
+#      that are not git repositories at all, where (2) and (3) are unavailable.
+#
+# Usage:
+#   resolve-app-dir.sh --marker <relative-path> [--from <dir>]
+#
+#   --marker <relative-path>  File that must exist under project/app for a
+#                             candidate to be accepted. Callers pass whatever
+#                             they actually need, so a half-shipped package is
+#                             rejected here rather than failing later with a
+#                             confusing error: launch.sh passes `package.json`,
+#                             snapshot.sh passes `api/scripts/capture-snapshot.js`.
+#   --from <dir>              Starting directory for the walk-up candidate.
+#                             Default: the current working directory.
+#
+# Exit codes: 0 (path printed to stdout), 2 (bad usage), 1 (not found).
+# -----------------------------------------------------------------------------
+
+set -euo pipefail
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+MARKER=""
+START_DIR=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --marker)
+      [ $# -ge 2 ] || { echo "Error: --marker requires a value" >&2; exit 2; }
+      MARKER="$2"
+      shift 2
+      ;;
+    --from)
+      [ $# -ge 2 ] || { echo "Error: --from requires a value" >&2; exit 2; }
+      START_DIR="$2"
+      shift 2
+      ;;
+    -h|--help)
+      sed -n '/^# Usage:/,/^# Exit codes/p' "$0" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *)
+      echo "Error: unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+[ -n "$MARKER" ] || { echo "Error: --marker is required" >&2; exit 2; }
+[ -n "$START_DIR" ] || START_DIR="$(pwd)"
+
+# -----------------------------------------------------------------------------
+# Locate this script (symlink-resolved), matching launch.sh/snapshot.sh's own
+# pattern so behavior is identical however the skill directory was reached.
+# -----------------------------------------------------------------------------
+
+SCRIPT_PATH="${BASH_SOURCE[0]}"
+while [ -h "$SCRIPT_PATH" ]; do
+  LINK_TARGET="$(readlink "$SCRIPT_PATH")"
+  case "$LINK_TARGET" in
+    /*) SCRIPT_PATH="$LINK_TARGET" ;;
+    *)  SCRIPT_PATH="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)/$LINK_TARGET" ;;
+  esac
+done
+SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)"
+
+# The installed package name, kept in one place so a rename only touches here.
+PKG_SUBPATH="node_modules/@jenga-ai/agent"
+
+# Accepts a candidate base directory if <base>/project/app/<marker> exists.
+# Prints the resolved app dir and returns 0; returns 1 otherwise.
+try_base() {
+  local base="$1"
+  [ -n "$base" ] || return 1
+  local app="$base/project/app"
+  [ -f "$app/$MARKER" ] || return 1
+  (cd "$app" && pwd)
+}
+
+CANDIDATES_TRIED=()
+
+# ── 1. Package-root-relative (monorepo direct, or package invoked in place) ────
+PKG_ROOT="$(cd "$SCRIPT_DIR/../../.." 2>/dev/null && pwd || true)"
+if [ -n "$PKG_ROOT" ]; then
+  CANDIDATES_TRIED+=("$PKG_ROOT/project/app")
+  if RESOLVED="$(try_base "$PKG_ROOT")"; then
+    echo "$RESOLVED"
+    exit 0
+  fi
+fi
+
+# ── 2 & 3. Git repo root, then the package inside it (consumer install) ───────
+REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -n "$REPO_ROOT" ]; then
+  CANDIDATES_TRIED+=("$REPO_ROOT/project/app" "$REPO_ROOT/$PKG_SUBPATH/project/app")
+  if RESOLVED="$(try_base "$REPO_ROOT")"; then
+    echo "$RESOLVED"
+    exit 0
+  fi
+  if RESOLVED="$(try_base "$REPO_ROOT/$PKG_SUBPATH")"; then
+    echo "$RESOLVED"
+    exit 0
+  fi
+fi
+
+# ── 4. Walk up from --from, for consumers that are not git repositories ───────
+# Bounded by reaching "/" so it always terminates, and checks the packaged
+# location at every level because node_modules may sit above the invoking dir.
+#
+# Deliberately checks ONLY $PKG_SUBPATH/project/app here, never a bare
+# project/app. An installed package is unambiguous evidence that this dashboard
+# belongs to this project; a bare project/app in some ancestor directory is not
+# — it is just as likely to be an unrelated checkout that happens to sit higher
+# up the tree, and silently rendering THAT project's board would be worse than
+# failing. Bare project/app is only ever accepted via candidates 1 and 2, which
+# are anchored to this script's own location rather than the caller's cwd.
+DIR="$(cd "$START_DIR" 2>/dev/null && pwd || true)"
+while [ -n "$DIR" ]; do
+  if RESOLVED="$(try_base "$DIR/$PKG_SUBPATH")"; then
+    echo "$RESOLVED"
+    exit 0
+  fi
+  [ "$DIR" = "/" ] && break
+  DIR="$(dirname "$DIR")"
+done
+
+die "dashboard app not found (looked for project/app/$MARKER). Tried: ${CANDIDATES_TRIED[*]:-none}, and walked up from $START_DIR checking both project/app and $PKG_SUBPATH/project/app. If this is a consumer install, reinstall @jenga-ai/agent with install scripts enabled (npm approve-scripts @jenga-ai/agent) so the dashboard is present."

package/skills/j-dashboard/scripts/snapshot.sh

@@ -0,0 +1,267 @@
+#!/usr/bin/env bash
+# -----------------------------------------------------------------------------
+# skills/j-dashboard/scripts/snapshot.sh
+#
+# Orchestrates `j.dashboard --snapshot` (E47_S04_T03): runs E47_S04_T02's capture
+# step, then bundles the UI into a single self-contained HTML file with that
+# captured data embedded inline, and reports the final output path.
+#
+# Step 1 — capture: node project/app/api/scripts/capture-snapshot.js writes a
+#   single JSON artifact ({schema_version, captured_at, project_root, routes})
+#   by calling /v1/board, /v1/history, /v1/architecture exactly once each via a
+#   short-lived ad-hoc server. Run from the ORIGINAL invocation directory
+#   (captured before any `cd` below) so its own resolveProjectRoot() walk-up
+#   resolves the *invoking* project's root (E47_S02's contract) — not this
+#   framework repo's, and not project/app/ui's.
+#
+# Step 2 — bundle: project/app/ui/scripts/build-snapshot-html.cjs inlines the
+#   built dist/ (JS + CSS) into a single index.html and injects the captured
+#   JSON as an inline <script id="jenga-dashboard-data"> tag. Zero dependencies
+#   and no build tooling, so it behaves identically in this monorepo and in a
+#   consumer install, which only ever receives the prebuilt dist/. Where the UI
+#   sources and node_modules are available, dist/ is rebuilt first so a
+#   snapshot is never taken from a stale build.
+#
+# project/app itself is located by resolve-app-dir.sh, which also knows to look
+#   inside node_modules/@jenga-ai/agent — this script previously assumed the
+#   repo root, which is wrong for every consumer install.
+#
+# Either step failing hard-fails this script (set -e) with no output file
+# written — matching capture-snapshot.js's own "no partial artifact" contract.
+#
+# --data-url (E47_S04_T04): remote-delivery mode for sessions that cannot
+#   assume a shared filesystem with the user. After the existing build/copy
+#   step, base64-encodes the final output HTML and prints a
+#   `data:text/html;base64,...` URI to stdout, additive to (not a replacement
+#   for) the existing "Snapshot dashboard written to: <path>" line. Refuses
+#   (hard-fail, no partial output) if the post-encoding size exceeds
+#   MAX_DATA_URL_BYTES (default ~25MB, overridable via
+#   SNAPSHOT_MAX_DATA_URL_BYTES for testing/tuning). No effect at all on the
+#   plain-path behavior when --data-url is not passed.
+#
+# Usage:
+#   snapshot.sh [--out <path>] [--project-root <path>] [--data-url]
+#
+#   --out <path>            Final output HTML path. Default: <cwd>/jenga.html
+#                            (cwd at invocation time, i.e. the invoking project's
+#                            own directory — same directory --project-root would
+#                            otherwise need to point at).
+#   --project-root <path>   Forwarded unchanged to capture-snapshot.js's own
+#                            --project-root override. Default: let
+#                            capture-snapshot.js resolve it from the invocation
+#                            cwd (no override).
+#   --data-url               After writing --out, also print a
+#                            `data:text/html;base64,...` URI of the same file
+#                            to stdout. Refuses (non-zero exit, no URI printed)
+#                            if the base64-encoded size exceeds
+#                            SNAPSHOT_MAX_DATA_URL_BYTES (default ~25MB).
+# -----------------------------------------------------------------------------
+
+set -euo pipefail
+
+# Post-encoding size threshold for --data-url, in bytes. Overridable via
+# SNAPSHOT_MAX_DATA_URL_BYTES (used by tests to exercise the refusal path
+# without generating a real multi-megabyte fixture).
+MAX_DATA_URL_BYTES="${SNAPSHOT_MAX_DATA_URL_BYTES:-26214400}" # 25 * 1024 * 1024
+
+usage() {
+  cat <<'EOF'
+Usage: snapshot.sh [--out <path>] [--project-root <path>] [--data-url]
+
+  --out <path>            Final output HTML path. Default: <cwd>/jenga.html
+  --project-root <path>   Forwarded to capture-snapshot.js's --project-root override.
+  --data-url              Also print a data:text/html;base64,... URI of the
+                          output file to stdout (for remote/no-shared-filesystem
+                          sessions). Refuses if the encoded size exceeds ~25MB
+                          (SNAPSHOT_MAX_DATA_URL_BYTES).
+EOF
+}
+
+die() {
+  echo "Error: $*" >&2
+  exit 1
+}
+
+OUT_PATH=""
+PROJECT_ROOT_ARG=""
+DATA_URL=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --out)
+      [ $# -ge 2 ] || die "--out requires a value"
+      OUT_PATH="$2"
+      shift 2
+      ;;
+    --project-root)
+      [ $# -ge 2 ] || die "--project-root requires a value"
+      PROJECT_ROOT_ARG="$2"
+      shift 2
+      ;;
+    --data-url)
+      DATA_URL=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      usage >&2
+      die "unknown argument: $1"
+      ;;
+  esac
+done
+
+# Capture the invocation cwd BEFORE any `cd` below — this is what
+# capture-snapshot.js's own resolveProjectRoot() walk-up must see, per E47_S02's
+# "resolve against the invoking project, not this repo" contract.
+ORIG_CWD="$(pwd)"
+
+if [ -z "$OUT_PATH" ]; then
+  OUT_PATH="$ORIG_CWD/jenga.html"
+fi
+# Resolve OUT_PATH to an absolute path up front, since later steps `cd` elsewhere
+# and a relative --out would otherwise silently resolve against the wrong directory.
+case "$OUT_PATH" in
+  /*) ;;
+  *) OUT_PATH="$ORIG_CWD/$OUT_PATH" ;;
+esac
+
+# -----------------------------------------------------------------------------
+# Locate script + repo root (symlink-resolved SCRIPT_DIR -> SKILL_DIR -> REPO_ROOT)
+# Same pattern as launch.sh — behaves identically whether invoked directly or
+# via a symlink, and whether run from this monorepo or a mirrored/distributed copy.
+# -----------------------------------------------------------------------------
+
+SCRIPT_PATH="${BASH_SOURCE[0]}"
+while [ -h "$SCRIPT_PATH" ]; do
+  LINK_TARGET="$(readlink "$SCRIPT_PATH")"
+  case "$LINK_TARGET" in
+    /*) SCRIPT_PATH="$LINK_TARGET" ;;
+    *)  SCRIPT_PATH="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)/$LINK_TARGET" ;;
+  esac
+done
+SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# project/app is NOT always at the repo root: in a consumer install it ships
+# inside the package, under node_modules/@jenga-ai/agent/. resolve-app-dir.sh
+# owns that whole search (and is shared with launch.sh) — see its header.
+# Invoked via `bash`, not executed directly: a shipped script losing its
+# executable bit is exactly the packaging defect this change also fixes, and
+# resolving the app dir must not be the thing that breaks when it happens.
+APP_DIR="$(bash "$SCRIPT_DIR/resolve-app-dir.sh" --marker "api/scripts/capture-snapshot.js" --from "$ORIG_CWD")" \
+  || die "could not locate the dashboard app directory (see message above)"
+
+API_DIR="$APP_DIR/api"
+UI_DIR="$APP_DIR/ui"
+
+[ -f "$API_DIR/scripts/capture-snapshot.js" ] || die "capture script not found at $API_DIR/scripts/capture-snapshot.js"
+# The built UI, not its sources: bundling no longer needs vite (see Step 2).
+[ -f "$UI_DIR/dist/index.html" ] || die "dashboard UI has not been built — no $UI_DIR/dist/index.html. In this monorepo run: npm run ui:build --prefix project/app. In a consumer install this means the package shipped without project/app/ui/dist (a packaging regression)."
+
+# -----------------------------------------------------------------------------
+# Scratch workspace — always cleaned up, success or failure.
+# -----------------------------------------------------------------------------
+
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+SNAPSHOT_JSON="$TMP_DIR/dashboard-snapshot-data.json"
+SNAPSHOT_DIST="$TMP_DIR/dist-snapshot"
+
+# -----------------------------------------------------------------------------
+# Step 1 — capture (from ORIG_CWD, not REPO_ROOT/UI_DIR — see header comment)
+# -----------------------------------------------------------------------------
+
+CAPTURE_ARGS=(--out "$SNAPSHOT_JSON")
+if [ -n "$PROJECT_ROOT_ARG" ]; then
+  CAPTURE_ARGS+=(--project-root "$PROJECT_ROOT_ARG")
+fi
+
+(cd "$ORIG_CWD" && node "$API_DIR/scripts/capture-snapshot.js" "${CAPTURE_ARGS[@]}")
+
+[ -f "$SNAPSHOT_JSON" ] || die "capture step reported success but no artifact was written to $SNAPSHOT_JSON"
+
+# -----------------------------------------------------------------------------
+# Step 2 — bundle: single-file build with the captured data embedded inline.
+#
+# Two sub-steps, deliberately split so the second one is identical everywhere:
+#
+#   2a. If the UI sources AND its node_modules are present (i.e. this monorepo,
+#       or a dev checkout), refresh dist/ first so a snapshot never silently
+#       ships a stale build. Skipped entirely in a consumer install, which has
+#       only the prebuilt dist/ the package shipped — and needs nothing more.
+#       If sources are present but node_modules/vite isn't (so the rebuild
+#       above can't run), a dev checkout still refuses to bundle a dist/ that
+#       looks older than its own sources — see the staleness check below.
+#   2b. Inline that dist/ into one self-contained HTML file with the captured
+#       JSON embedded, via the dependency-free build-snapshot-html.cjs.
+#
+# This used to be `npm run build:snapshot` (vite build --mode snapshot), which
+# only ever worked here: the tarball ships dist/ and scripts/ but no
+# package.json, vite.config.js, or src/, so there was no vite to run on any
+# consumer. Inlining a prebuilt dist needs no build tooling, so one code path
+# now serves both — and every local run exercises the consumer path too.
+# -----------------------------------------------------------------------------
+
+if [ -f "$UI_DIR/package.json" ] && [ -d "$UI_DIR/node_modules/vite" ]; then
+  (cd "$UI_DIR" && npm run build)
+  [ -f "$UI_DIR/dist/index.html" ] || die "UI rebuild reported success but produced no $UI_DIR/dist/index.html"
+elif [ -d "$UI_DIR/src" ]; then
+  # This is a dev checkout (it has UI sources, unlike a consumer install which
+  # only ships prebuilt dist/ + scripts/), but node_modules/vite isn't present
+  # right now to rebuild with -- e.g. `npm install` hasn't been (re-)run for
+  # this package. The rebuild above was skipped, so dist/ may already be
+  # stale relative to src/. A stale snapshot must never ship silently (this is
+  # exactly how a fixed bug re-appeared in a previously-generated jenga.html):
+  # fail loudly instead of trusting an on-disk dist/ of unknown age.
+  STALE_SRC="$(find "$UI_DIR/src" -type f -newer "$UI_DIR/dist/index.html" -print -quit 2>/dev/null)"
+  if [ -n "$STALE_SRC" ]; then
+    die "$UI_DIR/dist is older than UI sources (e.g. $STALE_SRC) and node_modules/vite is not installed here to rebuild it -- refusing to bundle a possibly-stale snapshot. Run 'npm install' in $UI_DIR (or otherwise rebuild dist/), then retry."
+  fi
+fi
+
+mkdir -p "$SNAPSHOT_DIST"
+node "$UI_DIR/scripts/build-snapshot-html.cjs" \
+  --dist "$UI_DIR/dist" \
+  --data "$SNAPSHOT_JSON" \
+  --out "$SNAPSHOT_DIST/index.html"
+
+[ -f "$SNAPSHOT_DIST/index.html" ] || die "bundling step reported success but no index.html was produced in $SNAPSHOT_DIST"
+
+# -----------------------------------------------------------------------------
+# Step 3 — place the final artifact and report its path.
+# -----------------------------------------------------------------------------
+
+mkdir -p "$(dirname "$OUT_PATH")"
+cp "$SNAPSHOT_DIST/index.html" "$OUT_PATH"
+
+echo "Snapshot dashboard written to: $OUT_PATH"
+
+# -----------------------------------------------------------------------------
+# Step 4 — optional data: URL delivery mode (E47_S04_T04).
+#
+# For sessions that cannot assume a shared filesystem with the user (e.g. a
+# remote/cloud agent session), base64-encode the just-written output file and
+# print a data:text/html;base64,... URI any browser can open directly — no
+# hosting, third-party service, or git round-trip required. Additive to the
+# plain-path report above, never a replacement for it.
+# -----------------------------------------------------------------------------
+
+if [ "$DATA_URL" -eq 1 ]; then
+  [ -f "$OUT_PATH" ] || die "--data-url: expected output file missing at $OUT_PATH after write step"
+
+  # `base64` without newline-wrapping flags (GNU's -w0 and BSD/macOS's -b are
+  # not portable across each other), then strip embedded newlines with `tr` --
+  # portable everywhere and avoids the platform-specific flag entirely.
+  ENCODED="$(base64 <"$OUT_PATH" | tr -d '\n')"
+  ENCODED_BYTES="${#ENCODED}"
+
+  if [ "$ENCODED_BYTES" -gt "$MAX_DATA_URL_BYTES" ]; then
+    die "--data-url: encoded size ($ENCODED_BYTES bytes) for $OUT_PATH exceeds the $MAX_DATA_URL_BYTES-byte threshold; refusing to emit an oversized data: URI. Use the plain --out file path instead, or raise SNAPSHOT_MAX_DATA_URL_BYTES if you understand the tradeoff."
+  fi
+
+  echo "data:text/html;base64,${ENCODED}"
+fi

package/skills/j-dashboard-share/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: j.dashboard-share
+description: Snapshot the project dashboard and upload it to a configured cloud storage remote in one step, by sequencing j-dashboard's snapshot script and E47_S05_T01's rclone upload script.
+keywords:
+  - dashboard share
+  - share dashboard
+  - upload dashboard
+  - cloud share snapshot
+  - dashboard to drive
+  - snapshot upload
+examples:
+  - "share the dashboard snapshot to the cloud"
+  - "upload a dashboard snapshot"
+  - "j.dashboard-share"
+  - "send the dashboard snapshot to my google drive"
+  - "snapshot and upload the dashboard"
+---
+
+# Dashboard Share — Snapshot + Cloud Upload
+
+## Purpose
+
+`E47_S05` chains two already-implemented, independently-scoped capabilities into one step: capturing
+a point-in-time dashboard snapshot and uploading it to a configured cloud storage remote. Both halves
+already exist as standalone scripts — `skills/j-dashboard/scripts/snapshot.sh` (`E47_S04_T02`/`T03`,
+capture + single-file bundle) and `skills/j-dashboard-share/scripts/upload-snapshot.sh`
+(`E47_S05_T01`, templated-path `rclone copyto` upload). Per this repo's "Scripts Over Inline Logic"
+principle (`CLAUDE.md`), this `SKILL.md` introduces **no new capture or upload logic of its own** — it
+only sequences those two scripts and relays their output, plus the minimal remote-selection judgment
+call described in step 2 below (interpreting `rclone listremotes` output and presenting a choice to
+the user, not reimplementing any config/upload behavior).
+
+This is **upload only** — this skill never runs `rclone link` or any other share-link-creating
+command, matching the story's explicit, deliberate scope decision (see `E47_S05`'s Purpose section in
+`PROJECT_SUMMARY.md`): upload and link-creation are two distinct actions with a real permission
+consequence, and creating a public link stays a separate, manual, deliberate step the user takes on
+their own, never something this skill chains automatically.
+
+## Instructions
+
+1. **Capture the snapshot.** Invoke:
+
+   ```
+   bash skills/j-dashboard/scripts/snapshot.sh [--out <path>]
+   ```
+
+   Forward `--out <path>` only if the user explicitly requested a specific local output path;
+   otherwise let it default. Relay the script's own stdout/stderr as-is if it fails — do not
+   reinterpret its error output. On success, read the local snapshot file's path from its documented
+   `Snapshot dashboard written to: <path>` line (the exact line `snapshot.sh` emits on completion) —
+   do not guess or re-derive the path any other way. If this step fails (non-zero exit), stop here;
+   do not proceed to step 2 or 3.
+
+2. **Determine which remote to upload to.** `upload-snapshot.sh` (step 3) requires an explicit
+   `--remote <name>` naming an already-configured rclone remote — it does not pick one on its own.
+   Resolve this before invoking it:
+   - If the user's request already names a specific remote (e.g. "upload it to my gdrive remote"),
+     use that name directly and skip straight to step 3.
+   - Otherwise, run `rclone listremotes` to see what's currently configured (a plain read-only
+     enumeration — not upload or config logic, so it stays within this repo's inline-judgment
+     carve-out for interpreting output and presenting results to the user):
+     - **Zero remotes configured:** tell the user to run `j.cloud-connect` first to configure one,
+       and stop here — do not invoke `upload-snapshot.sh` at all in this case (it would only
+       reproduce the same "not configured" message after the fact).
+     - **Exactly one remote configured:** use it automatically, no prompt needed.
+     - **More than one remote configured:** ask the user which one to use, following CLAUDE.md's
+       standard Interaction Pattern (numbered list of the configured remote names, "Other" as the
+       final option).
+
+3. **Upload the snapshot.** Invoke:
+
+   ```
+   bash skills/j-dashboard-share/scripts/upload-snapshot.sh --file <path-from-step-1> --remote <name-from-step-2>
+   ```
+
+   Relay its stdout/stderr to the user as-is, including the final printed destination path on
+   success (`JengaAI/<repo-directory-name>/<datetime>-board-snapshot.html` on the chosen remote) or
+   its own actionable error message on failure (e.g. it independently re-checks the remote is
+   configured and points at `j.cloud-connect` if not, in case that state changed between step 2's
+   enumeration and this call). Do not reinterpret, summarize away, or suppress its output.
+
+## Out of Scope
+
+- Any new dashboard capture, HTML bundling, or single-file export logic — that is entirely
+  `skills/j-dashboard/scripts/snapshot.sh`'s scope (`E47_S04`). Do not duplicate or reimplement any
+  part of it here.
+- Any new `rclone copyto` invocation, destination-path templating, or "remote not configured"
+  detection logic — that is entirely `skills/j-dashboard-share/scripts/upload-snapshot.sh`'s scope
+  (`E47_S05_T01`). This `SKILL.md` only decides *which* configured remote name to pass to it (step 2
+  above); it never re-derives the destination path or re-implements the configured-remote check.
+- Running `rclone link` or any other share-link-creating command, automatically or on request routed
+  through this skill — that is a deliberate, permanent scope exclusion for `E47_S05` (see Purpose
+  above), not a gap to close later.
+- `rclone` installation, backend configuration, or OAuth authentication — that is entirely
+  `j.cloud-connect`'s scope (`E60_S01`). This skill only points the user at it when no remote is
+  configured; it does not run any part of that flow itself.