@zerwiz/ymir 0.1.5 → 0.1.8

package/bin/ymir-plan.sh

@@ -0,0 +1,390 @@
+#!/usr/bin/env bash
+# ymir-plan.sh — THE INSTALL PLAN. Probe this machine, print what would change,
+# change nothing.
+#
+# The consent a real install asks for used to be a hardcoded paragraph, and a
+# paragraph cannot know the host: it named an Omarchy version on a Mac, promised
+# a workspace tree that already stood, and never mentioned that no application
+# had been installed at all. This is the replacement: a plan COMPUTED from the
+# same host the install will act on, one row per step, each row carrying its
+# state and the reason for it.
+#
+#   DO        a change will be made
+#   SKIP      already satisfied — nothing to do
+#   DO ·      (with a note) the step is available but conditional
+#   BLOCKED   cannot run; the reason names what is missing
+#   CONSENT   needs the operator's word before it may run
+#   INFO      a fact about this host, discovered — no change implied
+#
+# Usage:
+#   bin/ymir-plan.sh                 # the plan (TOON)
+#   bin/ymir-plan.sh --json          # the same, as JSON, for automation
+#   bin/ymir-plan.sh --phase 5       # one phase
+#   bin/ymir-plan.sh --blocked       # only what cannot proceed, and why
+#
+# Exit: 0 the plan was printed (a BLOCKED row is a fact, not a failure), 1 error,
+# 2 usage.
+set -u
+
+# --- portability shim: bin/ymir-platform.sh --------------------------------
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  _ymir_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+  for _ymir_c in "$_ymir_dir/ymir-platform.sh" "$(dirname "$_ymir_dir")/bin/ymir-platform.sh"; do
+    [ -r "$_ymir_c" ] && { . "$_ymir_c"; YMIR_PLATFORM_LOADED=1; break; }
+  done
+  unset _ymir_dir _ymir_c
+fi
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# Whether the home was named explicitly matters: a home that was chosen is not
+# the same as one we defaulted to, and the plan says which.
+YMIR_HOME_WAS_SET=0; [ -n "${YMIR_HOME:-}" ] && YMIR_HOME_WAS_SET=1
+# shellcheck source=bin/hoard-lib.sh
+. "$SCRIPT_DIR/hoard-lib.sh"
+ymir_home_root YMIR_HOME
+hoard_root HOARD
+
+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 ;;
+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|--colour] [--phase N] [--blocked]\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+declare -a P_N P_NAME P_STEP P_STATE P_WHY
+emit() { P_N+=("$1"); P_NAME+=("$2"); P_STEP+=("$3"); P_STATE+=("$4"); P_WHY+=("$5"); }
+
+have() { command -v "$1" >/dev/null 2>&1; }
+port_up() {  # <port>
+  if have curl; then curl -s -o /dev/null --max-time 1 "http://127.0.0.1:$1/" 2>/dev/null && return 0; fi
+  if have ss; then ss -ltn 2>/dev/null | grep -q ":$1 " && return 0; fi
+  return 1
+}
+# 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.
+# 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
+}
+
+# ── phase 0 · resolve — where this runs, and against what ────────────────────
+resolve_phase() {
+  local os="" desk="terminal"
+  os="$(ymir_os 2>/dev/null || printf unknown)"
+  [ -n "${WAYLAND_DISPLAY:-}" ] && desk="wayland"
+  [ -n "${DISPLAY:-}" ] && desk="x11"
+  [ -d /usr/share/omarchy ] && desk="$desk · omarchy first-class"
+  case "$os" in
+    wsl) desk="$desk · wsl2" ;;
+    msys) desk="$desk · msys (best-effort)" ;;
+  esac
+  emit 0 resolve os INFO "$os · $desk"
+
+  local eng=""
+  if command -v ymir_container_engine >/dev/null 2>&1; then eng="$(ymir_container_engine_name 2>/dev/null || true)"; fi
+  [ -z "$eng" ] && have docker && eng=docker
+  [ -z "$eng" ] && have podman && eng=podman
+  if [ -n "$eng" ]; then emit 0 resolve engine INFO "$eng"
+  else emit 0 resolve engine BLOCKED "no docker or podman on PATH — the Utgard image cannot be built"; fi
+
+  case "$ROOT" in
+    */node_modules/*) emit 0 resolve code INFO "$ROOT — a package install (read-only at runtime)" ;;
+    *) emit 0 resolve code INFO "$ROOT — a source checkout" ;;
+  esac
+
+  case "$HOARD" in
+    "$ROOT"/*) emit 0 resolve home BLOCKED "the home ($HOARD) sits inside the code tree — private data would live in the package" ;;
+    *) emit 0 resolve home INFO "$HOARD (the home = $YMIR_HOME)" ;;
+  esac
+
+  # The home is the OPERATOR's to choose. Until they have, it is only a default,
+  # and the install will ask — so the plan says so rather than pretending.
+  local rec=""
+  ymir_home_record rec
+  if [ -n "$rec" ]; then
+    emit 0 resolve chosen SKIP "the home was chosen at installation: $rec"
+  elif [ "$YMIR_HOME_WAS_SET" = 1 ]; then
+    emit 0 resolve chosen SKIP "the home is set by \$YMIR_HOME: $YMIR_HOME"
+  else
+    emit 0 resolve chosen CONSENT "no home chosen yet — the install asks, then records it (default $YMIR_HOME_DEFAULT)"
+  fi
+}
+
+# ── phase 1 · code — the tree itself, and its purity ────────────────────────
+code_phase() {
+  local n=0
+  [ -x "$ROOT/bin/ymir-install.sh" ] && n=$(find "$ROOT/bin" -maxdepth 1 -name '*.sh' 2>/dev/null | wc -l)
+  if [ "$n" -gt 0 ] && [ -d "$ROOT/.agents/skills" ] && [ -d "$ROOT/RULES" ]; then
+    emit 1 code integrity SKIP "tree intact — $n scripts, .agents/skills, RULES/"
+  else
+    emit 1 code integrity BLOCKED "bin/, .agents/skills or RULES/ is missing — reinstall the package or re-clone"
+  fi
+
+  # The law this row enforces: the package is the code that RUNS the programs.
+  # Everything the operator owns — their records, their state, their settings,
+  # their credentials — lives in the home they chose. A packaged install replaces
+  # its tree on upgrade, so anything of theirs kept here is kept at its peril.
+  # A settings file GIT TRACKS is not theirs: that is the distro's shipped
+  # default, and it stays where the code ships it.
+  local leaked="" f n
+  n="$(ls -A "$ROOT/data" 2>/dev/null | grep -vc '^\.gitkeep$' || true)"
+  [ -d "$ROOT/data" ] && [ "${n:-0}" -gt 0 ] && leaked="$leaked data/"
+  n="$(ls -A "$ROOT/state" 2>/dev/null | grep -vc '^\.gitkeep$' || true)"
+  [ -d "$ROOT/state" ] && [ "${n:-0}" -gt 0 ] && leaked="$leaked state/"
+  for f in config/agents.yaml config/cron.yaml config/tailscale-sync.yaml config/wedge-alarm .env.local; do
+    [ -e "$ROOT/$f" ] || continue
+    # `config` is a symlink into .agents/config, and git tracks the REAL path —
+    # ask it about the name the index holds, not the link the tree shows.
+    local ask="$f"
+    case "$f" in config/*) [ -L "$ROOT/config" ] && ask=".agents/config/${f#config/}" ;; esac
+    if command -v git >/dev/null 2>&1 && git -C "$ROOT" ls-files --error-unmatch "$ask" >/dev/null 2>&1; then
+      continue    # the distro ships this one — code, not the operator's own
+    fi
+    leaked="$leaked $f"
+  done
+  if [ -n "$leaked" ]; then
+    emit 1 code purity DO "the operator's own things sit in the code tree ($leaked) — they belong in $YMIR_HOME, or the next upgrade will erase them"
+  else
+    emit 1 code purity SKIP "nothing of the operator's is written into the code tree"
+  fi
+}
+
+# ── phase 2 · home — the operator's world, outside the tree ─────────────────
+home_phase() {
+  if [ -d "$HOARD/identity" ] && [ -d "$HOARD/secrets" ]; then
+    emit 2 home hoard SKIP "hodd/{identity,secrets,memory} present"
+  else
+    emit 2 home hoard DO "create hodd/{identity,secrets,docs,tenants,memory} — all private data lives here"
+  fi
+  if [ -d "$YMIR_HOME/workspaces" ]; then
+    emit 2 home workspaces SKIP "$YMIR_HOME/workspaces present"
+  else
+    emit 2 home workspaces DO "create workspaces/{work,personal} and the registries"
+  fi
+  # Settings are the operator's: they live in the home, never in the package.
+  local settings; hoard_settings_dir settings
+  if [ -e "$settings/agents.yaml" ]; then
+    emit 2 home agents-config SKIP "the agent set is seeded ($settings/agents.yaml)"
+  else
+    emit 2 home agents-config DO "seed the private agent set into $settings/agents.yaml (harness + model per agent)"
+  fi
+}
+
+# ── phase 3 · runtimes — every one proven by a probe, never assumed ─────────
+runtimes_phase() {
+  local missing=""
+  for c in git python3; do have "$c" || missing="$missing $c"; done
+  if [ -n "$missing" ]; then
+    emit 3 runtimes system BLOCKED "missing$missing — a system package (apt/dnf/brew), not user space"
+  else
+    emit 3 runtimes system SKIP "git and python3 present"
+  fi
+
+  local user=""
+  for c in bun uv; do have "$c" || user="$user $c"; done
+  if [ -n "$user" ]; then emit 3 runtimes userspace DO "install in user space (no sudo):$user"
+  else emit 3 runtimes userspace SKIP "bun and uv present"; fi
+
+  if have mcp; then emit 3 runtimes mcp SKIP "mcp<2> present"; else emit 3 runtimes mcp DO "install mcp<2> via pip"; fi
+  if have pi; then emit 3 runtimes pi SKIP "the Pi harness present"; else emit 3 runtimes pi DO "install the Pi harness"; fi
+  if have hermes; then emit 3 runtimes hermes SKIP "the Hermes worker runtime present"; else emit 3 runtimes hermes DO "install the Hermes worker runtime"; fi
+
+  if have herdr; then emit 3 runtimes backend SKIP "herdr — Þjazi (the preferred terminal backend)"
+  elif have tmux; then emit 3 runtimes backend SKIP "tmux — the accepted reference backend"
+  else emit 3 runtimes backend DO "install herdr (Þjazi), else tmux — without a backend no Eindri can be seated"; fi
+}
+
+# ── phase 4 · engines — the OSS anvils Ymir wraps ───────────────────────────
+engine_row() {  # <bin> <label>
+  if have "$1"; then emit 4 engines "$1" SKIP "$2 present"
+  else emit 4 engines "$1" DO "install $2 ($1)"; fi
+}
+engines_phase() {
+  engine_row treehouse "Yggdrasil (the worktree engine)"
+  engine_row no-mistakes "the clean-PR gate (Mjollnir · Glitnir)"
+  if have sandcastle; then emit 4 engines sandcastle SKIP "Utgard present"
+  else emit 4 engines sandcastle DO "install sandcastle (Utgard) if available"; fi
+
+  if have docker || have podman; then
+    local img
+    if have docker && docker image inspect utgard-runner:latest >/dev/null 2>&1; then
+      emit 4 engines utgard-image SKIP "utgard-runner:latest present"
+    elif have podman && podman image exists utgard-runner:latest >/dev/null 2>&1; then
+      emit 4 engines utgard-image SKIP "utgard-runner:latest present (podman)"
+    else
+      emit 4 engines utgard-image DO "build the sandbox image utgard-runner:latest"
+    fi
+  else
+    emit 4 engines utgard-image BLOCKED "no container engine — the sandbox cannot be built"
+  fi
+}
+
+# ── 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() {  # <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/$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/$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)" smidja-factory
+
+  # 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 [ -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' 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
+    emit 5 apps electron CONSENT "build the desktop shells? each pulls a ~100 MB Electron runtime — the web surfaces need none of it"
+  fi
+}
+
+# ── phase 6 · wire — the way in, and the agent set ──────────────────────────
+wire_phase() {
+  local door="none"
+  if [ -x "$ROOT/bin/ymir-setup-auth.sh" ]; then
+    door="$(bash "$ROOT/bin/ymir-setup-auth.sh" status 2>/dev/null | sed -n '2p' | cut -d, -f1 | tr -d ' "')"
+  fi
+  if [ -n "$door" ] && [ "$door" != none ]; then
+    emit 6 wire auth SKIP "an operator credential is set ($door)"
+  else
+    emit 6 wire auth CONSENT "no credential — a password or GitHub sign-in; without it the gate has no door"
+  fi
+
+  local codes=""
+  [ -x "$ROOT/bin/ymir-invite.sh" ] && codes="$(bash "$ROOT/bin/ymir-invite.sh" list 2>/dev/null | grep -c '^  "' || true)"
+  if [ "${codes:-0}" -gt 0 ]; then emit 6 wire invite SKIP "a live invite code exists"
+  else emit 6 wire invite CONSENT "mint an invite code — how anyone else is let in (registration stays closed without one)"; fi
+
+  if [ -d /usr/share/omarchy ]; then
+    emit 6 wire launchers DO "place each app on its own numbered desktop + write the launcher entries"
+  else
+    emit 6 wire launchers SKIP "not an Omarchy host — the Omarchy layer skips cleanly (Rule 05)"
+  fi
+}
+
+# ── phase 7 · raise — the services, then what the operator sees ─────────────
+raise_phase() {
+  local down="" p
+  for p in 3888:Hlidskjalf 3889:gate-API 4603:Bifrost 8437:Smidja-visualizer; do
+    port_up "${p%%:*}" || down="$down ${p#*:}"
+  done
+  if [ -n "$down" ]; then emit 7 raise services DO "raise:$down"
+  else emit 7 raise services SKIP "every service is listening (SPA · gate API · Bifrost · visualizer)"; fi
+  if have hermes; then emit 7 raise well INFO "the memory well (engram) is provisioned by its own step"; fi
+  emit 7 raise desktop CONSENT "open the desktop apps so they are seen, not merely installed"
+}
+
+# ── phase 8 · verify — what stands, honestly ────────────────────────────────
+verify_phase() {
+  if [ -x "$SCRIPT_DIR/ymir-validate.sh" ]; then
+    emit 8 verify validate DO "observe the result: ports, stores, processes, the sandbox image"
+  else
+    emit 8 verify validate BLOCKED "bin/ymir-validate.sh is absent — the install could not be proven"
+  fi
+}
+
+resolve_phase; code_phase; home_phase; runtimes_phase; engines_phase; apps_phase; wire_phase; raise_phase; verify_phase
+
+# ── output ──────────────────────────────────────────────────────────────────
+if [ "$JSON" = 1 ]; then
+  printf '['
+  local_i=0
+  for i in "${!P_STEP[@]}"; do
+    [ -n "$ONLY_PHASE" ] && [ "${P_N[$i]}" != "$ONLY_PHASE" ] && continue
+    [ "$ONLY_BLOCKED" = 1 ] && [ "${P_STATE[$i]}" != BLOCKED ] && continue
+    [ "$local_i" -gt 0 ] && printf ','
+    printf '\n  {"phase":%s,"name":"%s","step":"%s","state":"%s","why":"%s"}' \
+      "${P_N[$i]}" "${P_NAME[$i]}" "${P_STEP[$i]}" "${P_STATE[$i]}" "${P_WHY[$i]}"
+    local_i=$((local_i+1))
+  done
+  [ "$local_i" -gt 0 ] && printf '\n'
+  printf ']\n'
+  exit 0
+fi
+
+shown=0
+for i in "${!P_STEP[@]}"; do
+  [ -n "$ONLY_PHASE" ] && [ "${P_N[$i]}" != "$ONLY_PHASE" ] && continue
+  [ "$ONLY_BLOCKED" = 1 ] && [ "${P_STATE[$i]}" != BLOCKED ] && continue
+  shown=$((shown+1))
+done
+
+if [ "$shown" -eq 0 ]; then
+  if [ "$ONLY_BLOCKED" = 1 ]; then printf 'plan: 0 blocked steps — nothing is holding the install back\n'
+  else printf 'plan: 0 rows for phase %s\n' "$ONLY_PHASE"; fi
+  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
+  [ "$ONLY_BLOCKED" = 1 ] && [ "${P_STATE[$i]}" != BLOCKED ] && continue
+  printf '  "%s","%s","%s","%s","%s"\n' "${P_N[$i]}" "${P_NAME[$i]}" "${P_STEP[$i]}" "${P_STATE[$i]}" "${P_WHY[$i]}"
+done
+exit 0

package/bin/ymir-say.sh

@@ -24,7 +24,20 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-STATE_DIR="${BROKK_STATE_OVERRIDE:-$ROOT/state}"
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+STATE_DIR="${BROKK_STATE_OVERRIDE:-$YMIR_STATE_DIR}"
 LOG="$STATE_DIR/ymir-said.log"
 
 case "${1-}" in

package/bin/ymir-setup-auth.sh

@@ -18,7 +18,18 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-ENV_FILE="${YMIR_ENV_FILE:-$ROOT/.env.local}"
+
+# The operator's credentials are theirs and live in the HOME they chose — never
+# in the code tree, which a packaged install replaces on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_local_env _YMIR_ENV_DEFAULT
+ENV_FILE="${YMIR_ENV_FILE:-$_YMIR_ENV_DEFAULT}"
 
 usage() { sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; }
 die() { printf 'error: %s\n' "$1" >&2; exit 1; }

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.
@@ -99,21 +117,35 @@ else
 fi
 
 # ── 7. smidja db (visualizer readiness) ─────────────────────────────────────
+# The same pair scripts/start.sh and bin/smidja-bootstrap.sh resolve: an existing
+# $YMIR_HOME/smidja/smidja.db first, then an in-repo copy.
 YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
-SMIDJA_DB_PATH="${YMIR_HOME:+$YMIR_HOME/smidja/smidja.db}"
-SMIDJA_DB_PATH="${SMIDJA_DB_PATH:-$ROOT/apps/smidja/smidja_data/smidja.db}"
+SMIDJA_DB_PATH="${SMIDJA_DB:-}"
+if [ -z "$SMIDJA_DB_PATH" ]; then
+  for c in "$YMIR_HOME/smidja/smidja.db" "$ROOT/apps/smidja/smidja_data/smidja.db"; do
+    [ -f "$c" ] && { SMIDJA_DB_PATH="$c"; break; }
+  done
+  SMIDJA_DB_PATH="${SMIDJA_DB_PATH:-$YMIR_HOME/smidja/smidja.db}"
+fi
 if [ -f "$SMIDJA_DB_PATH" ]; then
   add smidja-db PASS "smidja.db present"
 else
   add smidja-db FAIL "smidja.db missing — run bin/smidja-bootstrap.sh"
 fi
 
-# ── 7b. visualizer UI (the API serves it from ./dist) ───────────────────
-VIZ="$ROOT/.agents/skills/smidja-factory/apps/visualizer"
-if [ -d "$VIZ/dist" ]; then
-  add visualizer PASS "UI built and served on :8437"
-elif [ -d "$VIZ" ]; then
+# ── 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="${SMIDJA_VIZ:-}"
+VIZ_PORT="${SMIDJA_VIZ_API_PORT:-8437}"
+if [ ! -d "$VIZ" ]; then
+  add visualizer SKIP "no visualizer tree at $VIZ"
+elif [ ! -d "$VIZ/dist" ]; then
   add visualizer FAIL "UI not built (./dist missing) — (cd $VIZ && bun run build)"
+elif port_open "$VIZ_PORT"; then
+  add visualizer PASS "UI built and served on :$VIZ_PORT"
+else
+  add visualizer FAIL "UI built but no API listening on :$VIZ_PORT — run scripts/start.sh"
 fi
 
 # ── 8. desktop apps (both Electron windows) ─────────────────────────────────
@@ -133,8 +165,14 @@ if port_open 4602; then add memory PASS "Mimir bridge up on :4602"
 else add memory WARN "well off (:4602) — needs the engram engine; platform runs without it"; fi
 
 # ── 10. audit ledger intact ─────────────────────────────────────────────────
-RUNES_LEDGER="${YMIR_HOME:+$YMIR_HOME/memory/runes_audit.md}"
-RUNES_LEDGER="${RUNES_LEDGER:-$ROOT/workspace/memory/runes_audit.md}"
+RUNES_LEDGER=""
+# The ledger follows the hoard (Rule 06): 0004-hoard-and-realms moved it under
+# hodd/memory/. Try the hoard first, then the pre-move locations.
+for c in "${YMIR_HOME:+${YMIR_HOARD:-$YMIR_HOME/hodd}/memory/runes_audit.md}" \
+         "${YMIR_HOME:+$YMIR_HOME/memory/runes_audit.md}" \
+         "$ROOT/workspace/memory/runes_audit.md"; do
+  [ -n "$c" ] && [ -r "$c" ] && { RUNES_LEDGER="$c"; break; }
+done
 if [ -r "$RUNES_LEDGER" ]; then
   add runes PASS "audit ledger readable ($(wc -l <"$RUNES_LEDGER" | tr -d ' ') lines)"
 else
@@ -162,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