@zerwiz/ymir 0.1.7 → 0.1.8

package/bin/smidja-board.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# smidja-board.sh — Smíðja's board, by one name.
+#
+# The visualizer can live in two very different trees: a clone's
+# `apps/smidja-factory/apps/visualizer`, or the `@zerwiz/smidja-factory` package
+# a user got from npm. Its database lives in the HOME (`$YMIR_HOME/smidja/smidja.db`),
+# not in either tree. This door resolves all three so the operator never has to.
+#
+#   smidja-board.sh build     # install deps and build the UI (./dist)
+#   smidja-board.sh start     # raise the API + UI, detached, ready to answer
+#   smidja-board.sh stop
+#   smidja-board.sh status
+#   smidja-board.sh --version | --help
+#
+# The operator's door is `ymir smidja [build|start|stop|status]` — this is what
+# that door runs.
+#
+# Exit: 0 ok, 1 error, 2 usage.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
+
+# shellcheck source=bin/hoard-lib.sh
+. "$SCRIPT_DIR/hoard-lib.sh"
+ymir_home_root YMIR_HOME
+hoard_state_dir STATE
+# shellcheck source=bin/smidja-lib.sh
+. "$SCRIPT_DIR/smidja-lib.sh"
+
+PORT="${SMIDJA_VIZ_API_PORT:-8437}"
+PID_FILE="$STATE/smidja-viz-api.pid"
+LOG_FILE="$STATE/smidja-viz-api.log"
+
+# The database follows the HOME; SMIDJA_DB overrides. A tree-local copy is the
+# last resort, for a checkout that keeps its own.
+SMIDJA_DB_PATH="${SMIDJA_DB:-}"
+if [ -z "$SMIDJA_DB_PATH" ]; then
+  for _db in "$YMIR_HOME/smidja/smidja.db" "$ROOT/apps/smidja/smidja_data/smidja.db"; do
+    [ -f "$_db" ] && { SMIDJA_DB_PATH="$_db"; break; }
+  done
+fi
+
+viz_dir() {  # <result-var>
+  local result_var=${1-} v
+  [ -n "$result_var" ] || return 2
+  if smidja_visualizer_dir v; then printf -v "$result_var" '%s' "$v"; return 0; fi
+  printf -v "$result_var" '%s' ""; return 1
+}
+
+alive() { [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE" 2>/dev/null)" 2>/dev/null; }
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+ACTION="$1"
+
+VIZ=""
+if ! viz_dir VIZ; then
+  printf 'error: the visualizer is not installed in this tree\n'
+  printf 'help: npm i -g @zerwiz/ymir (the smithy arrives as @zerwiz/smidja-factory)\n'
+  exit 1
+fi
+
+case "$ACTION" in
+  build)
+    if ! command -v bun >/dev/null 2>&1; then
+      printf 'error: bun is needed to build the UI\nhelp: bin/prereq-ensure.sh bun\n' >&2; exit 1
+    fi
+    printf 'visualizer_build[1]{step,state}:\n'
+    if [ ! -d "$VIZ/node_modules" ]; then
+      if (cd "$VIZ" && bun install >/dev/null 2>&1); then printf '  "deps","installed"\n'
+      else printf '  "deps","FAILED — (cd %s && bun install)"\n' "$VIZ" >&2; exit 1; fi
+    else printf '  "deps","present"\n'; fi
+    if (cd "$VIZ" && bun run build >/dev/null 2>&1) || (cd "$VIZ" && bunx vite build >/dev/null 2>&1); then
+      printf '  "ui","%s/dist"\n' "$VIZ"
+    else
+      printf 'error: the UI build failed\nhelp: (cd %s && bun run build)\n' "$VIZ" >&2; exit 1
+    fi
+    ;;
+  start)
+    command -v bun >/dev/null 2>&1 || { printf 'error: bun is needed to run the visualizer\nhelp: bin/prereq-ensure.sh bun\n' >&2; exit 1; }
+    [ -n "$SMIDJA_DB_PATH" ] && [ -f "$SMIDJA_DB_PATH" ] || {
+      printf 'error: no smidja.db found\nhelp: bin/smidja-bootstrap.sh (creates $YMIR_HOME/smidja/smidja.db)\n' >&2; exit 1; }
+    [ -d "$VIZ/dist" ] || printf 'note: the UI is unbuilt — the API will answer and show no interface\nnote: mend it with: bin/ymir-visualizer.sh build\n' >&2
+    if alive; then
+      printf 'visualizer[1]{state,pid,url}:\n  "already running","%s","http://127.0.0.1:%s/"\n' "$(cat "$PID_FILE")" "$PORT"
+      exit 0
+    fi
+    mkdir -p "$STATE"
+    # ymir_detach PRINTS the pid it spawned (setsid/nohup is its business, not
+    # ours); reading $! here would read a variable the helper already consumed.
+    pid=""
+    if command -v ymir_detach >/dev/null 2>&1; then
+      pid="$(ymir_detach env CMD_DB="$SMIDJA_DB_PATH" PORT="$PORT" bun run "$VIZ/server/index.ts" 2>>"$LOG_FILE")"
+    fi
+    if [ -z "$pid" ]; then
+      ( cd "$VIZ" && exec env CMD_DB="$SMIDJA_DB_PATH" PORT="$PORT" bun run server/index.ts ) >>"$LOG_FILE" 2>&1 &
+      pid="$!"
+    fi
+    [ -n "$pid" ] && printf '%s\n' "$pid" >"$PID_FILE"
+    for _i in $(seq 1 20); do
+      curl -s -o /dev/null --max-time 1 "http://127.0.0.1:$PORT/api/health" 2>/dev/null && break
+      sleep 0.5
+    done
+    if curl -s --max-time 2 "http://127.0.0.1:$PORT/api/health" >/dev/null 2>&1; then
+      printf 'visualizer[1]{state,db,url}:\n  "up","%s","http://127.0.0.1:%s/"\n' "$SMIDJA_DB_PATH" "$PORT"
+    else
+      printf 'error: the visualizer did not answer on :%s\nhelp: see %s\n' "$PORT" "$LOG_FILE" >&2; exit 1
+    fi
+    ;;
+  stop)
+    if alive; then
+      kill "$(cat "$PID_FILE")" 2>/dev/null; rm -f "$PID_FILE"
+      printf 'visualizer[1]{state}:\n  "stopped"\n'
+    else
+      rm -f "$PID_FILE"
+      printf 'visualizer[1]{state}:\n  "not running"\n'
+    fi
+    ;;
+  status)
+    local_db="${SMIDJA_DB_PATH:-none}"
+    if alive && curl -s --max-time 2 "http://127.0.0.1:$PORT/api/health" >/dev/null 2>&1; then
+      printf 'visualizer[3]{state,pid,db,url}:\n  "up","%s","%s","http://127.0.0.1:%s/"\n' "$(cat "$PID_FILE")" "$local_db" "$PORT"
+    elif alive; then
+      printf 'visualizer[2]{state,pid,note}:\n  "starting or wedged","%s","answers nothing on :%s — see %s"\n' "$(cat "$PID_FILE")" "$PORT" "$LOG_FILE"
+      exit 1
+    else
+      printf 'visualizer[3]{state,tree,db,ui}:\n  "down","%s","%s","%s"\n' "$VIZ" "$local_db" "$([ -d "$VIZ/dist" ] && echo built || echo unbuilt)"
+    fi
+    ;;
+  *) printf 'error: unknown action %s\nhelp: bin/smidja-board.sh [build|start|stop|status]\n' "$ACTION" >&2; exit 2 ;;
+esac

package/bin/smidja-lib.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# smidja-lib.sh — where the smithy's parts actually live.
+#
+# Two installs, one name. In a clone the smithy sits at `apps/smidja-factory`
+# (the registry's `repo: apps/<path>` block clones it there), and
+# `.agents/skills/smidja-factory` is a symlink to it. In a packaged install the
+# tree has no `apps/` at all: the smithy arrives as a dependency, at
+# `node_modules/@zerwiz/smidja-factory`, and that symlink dangles.
+#
+# Every script that needs the visualizer resolves it HERE, so the two shapes can
+# never disagree (Rule 07). Source-safe; defines functions only.
+#
+#   smidja_factory_dir    <result-var>   the smithy: skill, skills/, templates/, apps/
+#   smidja_visualizer_dir <result-var>   the board: its server, its UI source, its dist
+set -u
+
+# A surface has a name the operator knows and a package has a name npm serves;
+# they are not always the same, and the smithy is the pair that proves it.
+SMIDJA_SURFACE="smidja"
+SMIDJA_PACKAGE="smidja-factory"
+
+smidja_factory_dir() {  # <result-var> — the smithy's directory, or empty
+  local result_var=${1-} root="${YMIR_ROOT_DIR:-}" c
+  [ -n "$result_var" ] || return 2
+  if [ -z "$root" ]; then
+    root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+  fi
+  for c in \
+    "$root/apps/$SMIDJA_PACKAGE" \
+    "$root/node_modules/@zerwiz/$SMIDJA_PACKAGE" \
+    "$root/.agents/skills/$SMIDJA_PACKAGE"
+  do
+    # A dangling symlink is not a home: the visualizer must be readable there.
+    [ -d "$c/apps/visualizer" ] && { printf -v "$result_var" '%s' "$c"; return 0; }
+  done
+  printf -v "$result_var" '%s' ""
+  return 1
+}
+
+smidja_visualizer_dir() {  # <result-var> — the visualizer (server · UI source · dist)
+  local result_var=${1-} factory
+  [ -n "$result_var" ] || return 2
+  if smidja_factory_dir factory; then
+    printf -v "$result_var" '%s' "$factory/apps/visualizer"
+    return 0
+  fi
+  printf -v "$result_var" '%s' ""
+  return 1
+}

package/bin/ymir-install.sh

@@ -7,6 +7,7 @@
 # Usage:
 #   bin/ymir-install.sh [--check] [--skip-engines] [--skip-services] [--no-desktop] [--yes]
 #   bin/ymir-install.sh --plan [--json]     # the plan, computed — changes nothing
+#   bin/ymir-install.sh --yes | --non-interactive | --accept-all-defaults
 #   bin/ymir-install.sh --status
 #   bin/ymir-install.sh --version
 #
@@ -53,6 +54,18 @@ hoard_local_env YMIR_ENV_FILE
 # shellcheck source=bin/hoard-lib.sh
 . "$SCRIPT_DIR/hoard-lib.sh"
 ymir_home_root YMIR_HOME
+# Where the smithy's parts live: apps/smidja-factory in a clone, or the
+# @zerwiz/smidja-factory package in an npm install (bin/smidja-lib.sh).
+if [ -z "${YMIR_SMIDJA_LIB_LOADED:-}" ]; then
+  _ys="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_ys/smidja-lib.sh" "$(dirname "$_ys")/bin/smidja-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_SMIDJA_LIB_LOADED=1; break; }
+  done
+  unset _ys _yc
+fi
+smidja_visualizer_dir SMIDJA_VIZ
+smidja_factory_dir SMIDJA_FACTORY
+
 WORKSPACE="${YMIR_WORKSPACE:-$YMIR_HOME/workspaces}"
 hoard_root HOARD
 DOMAINS="company marketing development life me"
@@ -63,11 +76,12 @@ while [ $# -gt 0 ]; do
   case "$1" in
     --check) CHECK=1; shift ;;
     --plan|--dry-run) PLAN_ONLY=1; shift ;;
-    --json) PLAN_ARGS+=(--json); shift ;;
+    --json|--blocked) PLAN_ARGS+=("$1"); shift ;;
+    --phase) PLAN_ARGS+=("$1" "${2-}"); shift 2 ;;   # --phase carries its number
     --skip-engines) SKIP_ENGINES=1; shift ;;
     --skip-services) SKIP_SERVICES=1; shift ;;
     --no-desktop) NO_DESKTOP=1; shift ;;
-    --yes|-y) ASSUME_YES=1; shift ;;
+    --yes|-y|--non-interactive|--accept-all-defaults) ASSUME_YES=1; shift ;;
     --status) exec "$SCRIPT_DIR/ymir-install.sh" --check ;;
     *) printf 'error: unknown flag %s\nhelp: bin/ymir-install.sh [--check|--plan|--skip-engines|--skip-services|--no-desktop|--yes]\n' "$1" >&2; exit 2 ;;
   esac
@@ -78,6 +92,11 @@ if [ "$PLAN_ONLY" = 1 ]; then
   exec "$SCRIPT_DIR/ymir-plan.sh" ${PLAN_ARGS[@]+"${PLAN_ARGS[@]}"}
 fi
 
+# The cloth (bin/ymir-style.sh): colour, marks and spacing for the human, while
+# every row of data stays TOON on stdout.
+. "$SCRIPT_DIR/ymir-style.sh"
+style_init
+
 declare -a IDS STATUS DETAIL
 # The code minted for this install, reported at the end so it is not lost in the
 # step table. Empty on --check, and when no code could be minted.
@@ -97,8 +116,8 @@ confirm_install() {
     printf 'error: refusing a non-interactive install without --yes\nhelp: re-run with --yes to accept non-interactively, or --plan / --check to preview\n' >&2
     exit 3
   fi
+  style_title "Ymir first setup" "the plan below is probed on this machine, not recited"
   cat <<'PLAN'
-Ymir first setup — the plan below is probed on THIS machine, not recited.
 Each row is a phase, a step, its state, and why.
 
   DO        a change will be made
@@ -110,7 +129,7 @@ Each row is a phase, a step, its state, and why.
 Nothing is deleted. Every step is idempotent.
 PLAN
   printf '\n'
-  bash "$SCRIPT_DIR/ymir-plan.sh" 2>&1 || true
+  bash "$SCRIPT_DIR/ymir-plan.sh" --colour >/dev/null 2>&1 || true
   printf '\nProceed with the install? [y/N] '
   read -r reply || reply=""
   case "$reply" in
@@ -527,7 +546,7 @@ step_smidja() {
     if [ "$CHECK" = 1 ]; then
       local dbok vizok
       [ -f "$YMIR_HOME/smidja/smidja.db" ] && dbok=present || dbok=missing
-      [ -d "$ROOT/.agents/skills/smidja-factory/apps/visualizer/dist" ] && vizok=built || vizok=unbuilt
+      [ -n "${SMIDJA_VIZ:-}" ] && [ -d "$SMIDJA_VIZ/dist" ] && vizok=built || vizok=unbuilt
       if [ "$dbok" = missing ]; then
         add smidja WARN "smidja.db missing — a full run (without --check) creates it and seeds one bootstrap session"
       else
@@ -543,7 +562,7 @@ step_smidja() {
   else add smidja SKIP "no smidja-bootstrap.sh"; fi
   # The visualizer API serves its UI from ./dist — without a build it answers
   # the API but shows "No ./dist build found". Build it once when absent.
-  local viz="$ROOT/.agents/skills/smidja-factory/apps/visualizer"
+  local viz="${SMIDJA_VIZ:-}"; [ -n "$viz" ] || return 0
   [ -d "$viz" ] || return 0
   if [ -d "$viz/dist" ]; then
     add visualizer OK "UI built (served on :8437)"
@@ -682,6 +701,22 @@ step_desktop() {
   fi
   # Placement is the Omarchy layer's job and has already run (step_omarchy runs
   # before this step), so here we only launch.
+  # Verify the runtime before claiming anything: a skipped Electron postinstall
+  # leaves a partial runtime that fails to launch while every build still passes.
+  if [ -z "${YMIR_ELECTRON_LIB_LOADED:-}" ] && [ -r "$SCRIPT_DIR/electron-lib.sh" ]; then
+    . "$SCRIPT_DIR/electron-lib.sh"; YMIR_ELECTRON_LIB_LOADED=1
+  fi
+  local shell partial=""
+  for shell in hlidskjalf odrerir sessrumnir; do
+    local dir="$ROOT/apps/$shell" d
+    [ -d "$dir" ] || dir="$(cd "$ROOT" && npm root 2>/dev/null)/@zerwiz/$shell"
+    d="$(electron_runtime_state "$dir" 2>/dev/null || true)"
+    [ "$d" = partial ] && partial="$partial $shell"
+  done
+  if [ -n "$partial" ]; then
+    add desktop WARN "the Electron runtime is PARTIAL for:$partial — the web surfaces stand; approve and rebuild to launch the shells"
+    return 0
+  fi
   if "$ROOT/scripts/electron.sh" start --both >/dev/null 2>&1; then
     add desktop OK "raised Hlidskjalf + Smíðja"
   else

package/bin/ymir-plan.sh

@@ -46,7 +46,7 @@ YMIR_HOME_WAS_SET=0; [ -n "${YMIR_HOME:-}" ] && YMIR_HOME_WAS_SET=1
 ymir_home_root YMIR_HOME
 hoard_root HOARD
 
-JSON=0; ONLY_PHASE=""; ONLY_BLOCKED=0
+JSON=0; COLOUR=0; ONLY_PHASE=""; ONLY_BLOCKED=0
 case "${1-}" in
   -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
   -h|--help) sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
@@ -54,9 +54,10 @@ esac
 while [ $# -gt 0 ]; do
   case "$1" in
     --json) JSON=1; shift ;;
+    --colour|--color) COLOUR=1; shift ;;
     --phase) ONLY_PHASE="${2-}"; shift 2 ;;
     --blocked) ONLY_BLOCKED=1; shift ;;
-    *) printf 'error: unknown flag %s\nhelp: bin/ymir-plan.sh [--json] [--phase N] [--blocked]\n' "$1" >&2; exit 2 ;;
+    *) printf 'error: unknown flag %s\nhelp: bin/ymir-plan.sh [--json|--colour] [--phase N] [--blocked]\n' "$1" >&2; exit 2 ;;
   esac
 done
 
@@ -71,9 +72,12 @@ port_up() {  # <port>
 }
 # An app is ours by one of two shapes: a source checkout under apps/, or a
 # published package under node_modules/@zerwiz/. Neither is guessed.
-app_dir() {  # <name> -> path, or empty
-  local n="$1" c
-  for c in "$ROOT/apps/$n" "$ROOT/node_modules/@zerwiz/$n"; do
+# A surface has a name the operator knows and a PACKAGE has a name npm serves;
+# they are not always the same (the smithy is `smidja` to us and
+# `@zerwiz/smidja-factory` on the registry). <surface> [<package>]
+app_dir() {
+  local n="$1" pkg="${2:-$1}" c
+  for c in "$ROOT/apps/$n" "$ROOT/node_modules/@zerwiz/$pkg"; do
     [ -d "$c" ] && { printf '%s' "$c"; return 0; }
   done
   return 1
@@ -234,35 +238,48 @@ engines_phase() {
 # ── phase 5 · apps — the surfaces the operator actually sees ────────────────
 # Four surfaces, one shape each: web build required, Electron shell gated.
 # The apps are their own packages (@zerwiz/<app>) — the distro depends on them.
-app_row() {  # <name> <about>
-  local name="$1" about="$2" dir
-  if dir="$(app_dir "$name")"; then
+app_row() {  # <surface> <about> [<package>]
+  local name="$1" about="$2" pkg="${3:-$1}" dir
+  if dir="$(app_dir "$name" "$pkg")"; then
     if [ -d "$dir/dist" ] || [ -d "$dir/out" ]; then
       emit 5 apps "$name" SKIP "$about — installed, and its build shipped with it"
     else
       emit 5 apps "$name" DO "$about — installed from source; the web build is still to make"
     fi
-  elif grep -q "\"@zerwiz/$name\"" "$ROOT/package.json" 2>/dev/null; then
+  elif grep -q "\"@zerwiz/$pkg\"" "$ROOT/package.json" 2>/dev/null; then
     # Declared as a dependency of the distro but not present: the package exists,
     # the tree simply has not fetched it. That is a DO, not a dead end.
     emit 5 apps "$name" DO "$about — declared as a dependency but not fetched (npm i -g @zerwiz/ymir fetches it)"
   else
-    emit 5 apps "$name" BLOCKED "$about — no apps/$name, no @zerwiz/$name package, and the distro does not depend on it"
+    emit 5 apps "$name" BLOCKED "$about — no apps/$name, no @zerwiz/$pkg package, and the distro does not depend on it"
   fi
 }
 apps_phase() {
   app_row hlidskjalf "the control plane (the high seat), served on :3888"
   app_row odrerir "the live hall (chat + council)"
   app_row sessrumnir "the seat-hall desktop"
-  app_row smidja "the smithy and its visualizer (:8437)"
+  app_row smidja "the smithy and its visualizer (:8437)" smidja-factory
 
-  local shells=0 d
+  # A shell is ready only when its runtime VERIFIES: npm gates install scripts,
+  # and a skipped Electron postinstall leaves a partial runtime that still builds
+  # the web app and still reports success (bin/electron-lib.sh).
+  if [ -z "${YMIR_ELECTRON_LIB_LOADED:-}" ]; then
+    for c in "$SCRIPT_DIR/electron-lib.sh"; do [ -r "$c" ] && { . "$c"; YMIR_ELECTRON_LIB_LOADED=1; }; done
+  fi
+  local shells=0 partial="" missing=0 d
   for d in hlidskjalf odrerir sessrumnir; do
     dir="$(app_dir "$d" 2>/dev/null || true)"
-    if [ -n "$dir" ] && [ -d "$dir/node_modules/electron/dist" ]; then shells=$((shells+1)); fi
+    if [ -z "$dir" ]; then missing=$((missing+1)); continue; fi
+    case "$(electron_runtime_state "$dir" 2>/dev/null || true)" in
+      ok) shells=$((shells+1)) ;;
+      partial) partial="$partial $d" ;;
+      *) missing=$((missing+1)) ;;
+    esac
   done
   if [ "$shells" -ge 3 ]; then
-    emit 5 apps electron SKIP "the three desktop shells are built (electron runtime present)"
+    emit 5 apps electron SKIP "the three desktop shells' runtimes verify"
+  elif [ -n "$partial" ]; then
+    emit 5 apps electron DO "the runtime is PARTIAL for:$partial — npm skipped the Electron postinstall; the web surfaces stand, the shells will not launch"
   elif [ "${YMIR_NO_DESKTOP:-0}" = 1 ]; then
     emit 5 apps electron SKIP "declined (--no-desktop) — the web surfaces stand without the shells"
   else
@@ -347,6 +364,23 @@ if [ "$shown" -eq 0 ]; then
   exit 0
 fi
 
+# A human sees the same rows, rendered in the cloth, on stderr — the TOON below
+# stays the data on stdout, so a pipeline never parses a decoration.
+if [ "$COLOUR" = 1 ]; then
+  . "$SCRIPT_DIR/ymir-style.sh"
+  style_init
+  last_phase=""
+  for i in "${!P_STEP[@]}"; do
+    [ -n "$ONLY_PHASE" ] && [ "${P_N[$i]}" != "$ONLY_PHASE" ] && continue
+    [ "$ONLY_BLOCKED" = 1 ] && [ "${P_STATE[$i]}" != BLOCKED ] && continue
+    if [ "${P_N[$i]}" != "$last_phase" ]; then
+      style_heading "${P_NAME[$i]}"
+      last_phase="${P_N[$i]}"
+    fi
+    style_line "${P_STATE[$i]}" "${P_STEP[$i]}" "${P_WHY[$i]}"
+  done
+fi
+
 printf 'plan[%d]{phase,name,step,state,why}:\n' "$shown"
 for i in "${!P_STEP[@]}"; do
   [ -n "$ONLY_PHASE" ] && [ "${P_N[$i]}" != "$ONLY_PHASE" ] && continue

package/bin/ymir-style.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# ymir-style.sh — the cloth of the terminal halls.
+#
+# Ymir had no design for its own command line: correct output, no experience.
+# This is the cloth — cut from the same stone as the halls
+# (midgard/design-system/tokens.css): bone for words, bronze for what acts,
+# steel for what stands, blood for what is wrong, and the forge's marks for the
+# states a plan can be in.
+#
+# The rules it obeys (cli-guidelines, clig.dev, Monospace TUI):
+#   · colour, marks and motion only when a human is present — never in a pipe,
+#     never when NO_COLOR is set, never on a dumb terminal, never for --no-color
+#   · data goes to stdout, the human's rendering goes to stderr, so a pipeline
+#     never has to parse a decoration
+#   · a reaction for every action, and a next step for every ending
+#   · density first: no banner bigger than four lines, no rule longer than the text
+#
+# Source-safe; functions only. Nothing here writes a byte of data.
+set -u
+
+# --- the palette, from the tokens (truecolor → 256 → none) ------------------
+style_init() {
+  STYLE_ON=0
+  # A human must be present: stderr is a terminal and nobody said no.
+  if [ -t 2 ] && [ -z "${NO_COLOR:-}" ] && [ "${TERM:-dumb}" != dumb ] && [ "${YMIR_NO_COLOR:-0}" != 1 ]; then
+    STYLE_ON=1
+  fi
+  if [ "$STYLE_ON" = 1 ] && { [ "${COLORTERM:-}" = truecolor ] || [ "${COLORTERM:-}" = 24bit ]; }; then
+    C_BONE=$'\033[38;2;207;195;169m'; C_BRONZE=$'\033[38;2;201;151;79m'
+    C_STEEL=$'\033[38;2;150;160;168m'; C_BLOOD=$'\033[38;2;194;88;74m'
+    C_FAINT=$'\033[38;2;107;98;80m'; C_BOLD=$'\033[1m'
+  elif [ "$STYLE_ON" = 1 ]; then
+    C_BONE=$'\033[38;5;187m'; C_BRONZE=$'\033[38;5;179m'
+    C_STEEL=$'\033[38;5;109m'; C_BLOOD=$'\033[38;5;167m'
+    C_FAINT=$'\033[38;5;101m'; C_BOLD=$'\033[1m'
+  else
+    C_BONE=""; C_BRONZE=""; C_STEEL=""; C_BLOOD=""; C_FAINT=""; C_BOLD=""
+  fi
+  C_OFF=""
+  [ "$STYLE_ON" = 1 ] && C_OFF=$'\033[0m'
+}
+
+# The forge's marks, one per state a thing can be in.
+style_mark() {  # <state> → a glyph
+  case "${1:-}" in
+    DO|do)             printf '%s' '◆' ;;
+    SKIP|skip|already) printf '%s' '·' ;;
+    INFO|info)         printf '%s' '—' ;;
+    BLOCKED|blocked)   printf '%s' '✕' ;;
+    CONSENT|consent)   printf '%s' '?' ;;
+    OK|ok)             printf '%s' '✓' ;;
+    WARN|warn)         printf '%s' '·' ;;
+    FAIL|fail)         printf '%s' '✕' ;;
+    *)                 printf '%s' '·' ;;
+  esac
+}
+
+style_colour() {  # <state> → the colour for it
+  case "${1:-}" in
+    DO|CONSENT|WARN|warn|do|consent) printf '%s' "$C_BRONZE" ;;
+    OK|SKIP|INFO|ok|skip|info)       printf '%s' "$C_STEEL" ;;
+    FAIL|BLOCKED|fail|blocked)       printf '%s' "$C_BLOOD" ;;
+    *)                               printf '%s' "$C_FAINT" ;;
+  esac
+}
+
+# --- the pieces -------------------------------------------------------------
+
+# The mark: four lines at most. The WORDS show even in a pipe — only the colour
+# is conditional, because colour is decoration and the name is information.
+style_title() {  # <name> <claim>
+  printf '%s\n' "${C_BRONZE}   ᛉ  ${C_BOLD}${1}${C_OFF}" >&2
+  printf '%s\n' "${C_FAINT}      ${2}${C_OFF}" >&2
+  printf '\n' >&2
+}
+
+style_rule() {  # a hairline, no wider than the words it separates
+  local width="${1:-52}"
+  [ "$STYLE_ON" = 1 ] || return 0
+  local line=""; local i=0
+  while [ "$i" -lt "$width" ]; do line="$line─"; i=$((i+1)); done
+  printf '%s\n' "${C_FAINT}${line}${C_OFF}" >&2
+}
+
+style_say()  { printf '%s\n' "${C_BONE}$*${C_OFF}" >&2; }
+style_hint() { printf '%s\n' "${C_FAINT}$*${C_OFF}" >&2; }
+
+style_line() {  # <state> <name> <detail> — the one line per thing
+  local state="$1" name="$2" detail="${3:-}"
+  printf '  %s%s%s %-12s %s%s\n' \
+    "$(style_colour "$state")" "$(style_mark "$state")" "$C_OFF" \
+    "$name" "$(style_colour "$state")" "$detail" >&2
+  printf '%s' "$C_OFF" >/dev/null
+}
+
+style_heading() { printf '\n%s%s%s\n' "$C_BRONZE" "$1" "$C_OFF" >&2; }
+
+# The ending: what stands, then exactly what to type next. Every CLI deserves
+# to leave the operator with the next step and nothing else to guess.
+style_next() {  # one command per line, as "verb — what it does"
+  printf '\n%s\n' "${C_BOLD}Where to go from here${C_OFF}" >&2
+  while [ $# -gt 0 ]; do
+    local cmd="${1%% — *}" what="${1#* — }"
+    printf '  %s%-22s%s %s\n' "$C_BRONZE" "$cmd" "$C_OFF" "$(printf '%s' "$what" | sed "s/^/$C_FAINT/;s/$/$C_OFF/")" >&2
+    shift
+  done
+  printf '\n' >&2
+}

package/bin/ymir-validate.sh

@@ -16,6 +16,24 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# The cloth: colour and marks for the human reading this report; the TOON rows on
+# stdout stay the data (bin/ymir-style.sh).
+if [ -z "${YMIR_STYLE_LOADED:-}" ]; then
+  . "$SCRIPT_DIR/ymir-style.sh"; YMIR_STYLE_LOADED=1
+fi
+style_init
+# Where the smithy's parts live: apps/smidja-factory in a clone, or the
+# @zerwiz/smidja-factory package in an npm install (bin/smidja-lib.sh).
+if [ -z "${YMIR_SMIDJA_LIB_LOADED:-}" ]; then
+  _ys="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_ys/smidja-lib.sh" "$(dirname "$_ys")/bin/smidja-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_SMIDJA_LIB_LOADED=1; break; }
+  done
+  unset _ys _yc
+fi
+smidja_visualizer_dir SMIDJA_VIZ
+smidja_factory_dir SMIDJA_FACTORY
+
 # shellcheck source=bin/ymir-platform.sh
 . "$SCRIPT_DIR/ymir-platform.sh"
 # Docker or rootless Podman (Fedora), whichever is present.
@@ -118,7 +136,7 @@ fi
 # ── 7b. visualizer (built ./dist AND its API actually listening) ────────────
 # A PASS must mean the thing is UP. Probe the port, not just the build: a
 # built-but-dead visualizer (a bad CMD_DB, a crashed API) is a FAIL, not green.
-VIZ="$ROOT/.agents/skills/smidja-factory/apps/visualizer"
+VIZ="${SMIDJA_VIZ:-}"
 VIZ_PORT="${SMIDJA_VIZ_API_PORT:-8437}"
 if [ ! -d "$VIZ" ]; then
   add visualizer SKIP "no visualizer tree at $VIZ"
@@ -182,12 +200,27 @@ else
   for i in "${!IDS[@]}"; do
     say "  \"${IDS[$i]}\",\"${STATES[$i]}\",\"${DETAILS[$i]}\""
   done
+  # The same rows, rendered for the eye, on stderr: a human reads marks and
+  # colour, a pipeline reads the TOON above, and neither parses the other.
+  if [ "$QUIET" != 1 ]; then
+    printf '\n' >&2
+    for i in "${!IDS[@]}"; do
+      style_line "${STATES[$i]}" "${IDS[$i]}" "${DETAILS[$i]}"
+    done
+  fi
 fi
 
 if [ "$fails" -gt 0 ]; then
-  [ "$QUIET" = 1 ] || printf '\n%s required check(s) failed — the install is not fully usable\n' "$fails"
+  [ "$QUIET" = 1 ] || {
+    style_rule 52
+    style_line FAIL "not usable" "$fails required check(s) failed, $warns warning(s)"
+    style_hint "mend it: ymir eir   (diagnose every surface, then mend what is broken)"
+  }
   printf 'help: %s required check(s) failed, %s warning(s)\n' "$fails" "$warns" >&2
   exit 1
 fi
-[ "$QUIET" = 1 ] || printf '\nall required checks pass (%s warning(s))\n' "$warns"
+[ "$QUIET" = 1 ] || {
+  style_rule 52
+  style_line OK "stands" "every required check passes ($warns warning(s))"
+}
 exit 0