@zerwiz/ymir 0.1.7 → 0.1.9

package/bin/einherjar-spawn.sh

@@ -342,6 +342,12 @@ else
 fi
 
 # --- isolation resolution ----------------------------------------------------
+# A spawned Eindri is a MODEL-DRIVEN worker: it must reach a model endpoint to
+# think at all. Utgard runs with `--network none`, so a sandboxed agent cannot
+# reach either a cloud model (OpenCode Go) or a local one (llama.cpp) — it dies
+# silently at launch, leaving an empty pane and no status line. Utgard is for
+# untrusted CODE, not for the agent's own brain. So `auto` keeps the worker in
+# its worktree, and `on` is an explicit choice that warns.
 ISOLATION_EFFECTIVE=off
 case "$ISOLATION" in
   on)
@@ -351,14 +357,14 @@ case "$ISOLATION" in
       exit 1
     }
     ISOLATION_EFFECTIVE=on
+    echo "warning: Utgard runs with --network none — the worker's model endpoint must be reachable INSIDE the sandbox, or the agent dies silently. Pass --isolation off to run in the worktree." >&2
     ;;
   off) ISOLATION_EFFECTIVE=off ;;
   auto)
+    ISOLATION_EFFECTIVE=off
     if [ -n "$ENGINE" ] && "$ENGINE" image inspect utgard-runner:latest >/dev/null 2>&1; then
-      ISOLATION_EFFECTIVE=on
-      echo "isolation: on (Utgard image present; pass --isolation off to run in the worktree)" >&2
+      echo "isolation: off (Utgard image present, but a model-driven worker needs its endpoint and Utgard has no network — pass --isolation on only for a sandbox that can reach a model)" >&2
     else
-      ISOLATION_EFFECTIVE=off
       echo "isolation: off (no Utgard image; pass --isolation on after building it)" >&2
     fi
     ;;

package/bin/eir-doctor.sh

@@ -18,6 +18,22 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
 STATE="${BROKK_STATE_OVERRIDE:-$YMIR_HOME/state}"
 
+# 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 an app lives: apps/<surface> in a clone, node_modules/@zerwiz/<pkg> in an
+# npm install — both shapes, one resolver (bin/app-lib.sh).
+if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+  _ya="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yac in "$_ya/app-lib.sh" "$(dirname "$_ya")/bin/app-lib.sh"; do
+    [ -r "$_yac" ] && { . "$_yac"; YMIR_APP_LIB_LOADED=1; break; }
+  done
+  unset _ya _yac
+fi
+app_dir sessrumnir APP_SESSRUMNIR || APP_SESSRUMNIR=""
+
+
 case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
 ACTION="${1:-check}"; shift || true
 
@@ -25,7 +41,7 @@ have() { command -v "$1" >/dev/null 2>&1; }
 say_ok() { return 0; }
 
 # Each surface: `s_<name>` = healthy? (exit 0), `f_<name>` = the repair.
-SURFACES=(floors herdr a2abridge hermes sessrumnir well mcp lock migrations hoard)
+SURFACES=(floors herdr a2abridge hermes sessrumnir shells well mcp lock migrations hoard)
 
 s_floors()    { [ -x "$SCRIPT_DIR/prereq-ensure.sh" ] && "$SCRIPT_DIR/prereq-ensure.sh" status >/dev/null 2>&1; }
 f_floors()    { "$SCRIPT_DIR/prereq-ensure.sh" ensure --install >/dev/null 2>&1; }
@@ -37,6 +53,34 @@ s_hermes()    { [ -x "$SCRIPT_DIR/hermes-ensure.sh" ] && "$SCRIPT_DIR/hermes-ens
 f_hermes()    { "$SCRIPT_DIR/hermes-ensure.sh" ensure --install >/dev/null 2>&1; }
 s_sessrumnir(){ [ -x "$SCRIPT_DIR/sessrumnir-ensure.sh" ] && "$SCRIPT_DIR/sessrumnir-ensure.sh" status >/dev/null 2>&1; }
 f_sessrumnir(){ "$SCRIPT_DIR/sessrumnir-ensure.sh" ensure --install >/dev/null 2>&1; }
+# The desktop shells: absent is healthy (the web surfaces stand alone), PARTIAL is
+# not — npm gated the Electron postinstall, so the window cannot open while every
+# build still passes (bin/electron-lib.sh).
+shell_dirs() {
+  local a d
+  for a in hlidskjalf odrerir sessrumnir; do
+    for d in "$ROOT/apps/$a" "$ROOT/node_modules/@zerwiz/$a"; do
+      [ -d "$d" ] && { printf '%s\n' "$d"; break; }
+    done
+  done
+}
+s_shells() {
+  local d state
+  while IFS= read -r d; do
+    state="$(electron_runtime_state "$d" 2>/dev/null || true)"
+    [ "$state" = partial ] && return 1
+  done < <(shell_dirs)
+  return 0
+}
+f_shells() {
+  printf 'eir: the shells need YOUR hand — npm gated the runtime download:\n' >&2
+  electron_remedy >&2
+  return 1
+}
+if [ -z "${YMIR_ELECTRON_LIB_LOADED:-}" ] && [ -r "$SCRIPT_DIR/electron-lib.sh" ]; then
+  . "$SCRIPT_DIR/electron-lib.sh"; YMIR_ELECTRON_LIB_LOADED=1
+fi
+
 s_well()      { [ -x "$SCRIPT_DIR/mimir.sh" ] && "$SCRIPT_DIR/mimir.sh" health >/dev/null 2>&1; }
 f_well()      { "$SCRIPT_DIR/mimir.sh" start >/dev/null 2>&1; }
 # MCP: both A2A servers wired into opencode + pi.
@@ -121,11 +165,12 @@ detail() { # <name> -> one short fact
     herdr)     "have herdr && herdr --version 2>/dev/null | head -1 || echo 'herdr absent'" ;;
     a2abridge) "have a2abridge && a2abridge --version 2>/dev/null | head -1 || echo 'engine absent'" ;;
     hermes)    "have hermes && echo present || echo absent" ;;
-    sessrumnir)"[ -d $ROOT/apps/sessrumnir/out ] && echo built || echo 'not built'" ;;
+    sessrumnir)"[ -d $APP_SESSRUMNIR/out ] && echo built || echo 'not built'" ;;
     well)      "echo 'engram :4602'" ;;
     mcp)       "echo 'a2abridge + engram'" ;;
     lock)      "cat $STATE/.lock 2>/dev/null | tr -d '[:space:]' | sed 's/^/pid /' || echo none" ;;
     migrations)"echo 'structure'" ;;
+    shells)    'shell_dirs | while IFS= read -r d; do printf "%s %s; " "$(basename "$d")" "$(electron_runtime_state "$d" 2>/dev/null || true)"; done' ;;
     hoard)     "printf 'hoard %s' \"$(_hoard_root)\" ; [ -d \"$YMIR_HOME/identity\" ] && printf ' +flat-duplicate' ; printf '\\n'" ;;
   esac
 }
@@ -151,6 +196,14 @@ done
 printf 'eir[1]{action,root,broken}:\n  "%s","%s",%s\n' "$ACTION" "$ROOT" "$broken"
 printf 'health[%d]{surface,state,detail}:\n' "$count"
 printf '%b' "$rows"
+# For the eye, on stderr: marks and colour; for the pipe, the TOON above.
+if [ -t 2 ]; then
+  printf '\n' >&2
+  while IFS='|' read -r surface state detail; do
+    [ -n "$surface" ] || continue
+    style_line "$state" "$surface" "$detail"
+  done <<<"$(printf '%b' "$rows" | sed 's/^  //; s/"//g; s/,/|/; s/,/|/')"
+fi
 if [ "$broken" != 0 ]; then
   printf 'eir: %s surface(s) need mending — run: bin/eir-doctor.sh fix\n' "$broken"
   exit 1

package/bin/electron-lib.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# electron-lib.sh — is a desktop shell's runtime actually there?
+#
+# The trap this exists for: npm blocks a package's install scripts by default
+# (npm 11.16+ warns, npm 12 refuses), and Electron's postinstall is what downloads
+# its ~100 MB runtime. Without it the install still reports SUCCESS and the web app
+# still builds — `node_modules/electron/dist/` is simply partial and `path.txt` is
+# never written. So the shell fails to launch while every check says healthy, and
+# nobody is told.
+#
+# Ymir refuses that silence: a shell is only "ready" when the runtime verifies.
+# Source-safe, functions only.
+#
+#   electron_runtime_state <app-dir>   ok | partial | absent   (exit 0 only for ok)
+#   electron_remedy                    the exact command that mends a partial one
+set -u
+
+electron_runtime_state() {  # <app-dir>
+  local dir="${1-}"
+  [ -n "$dir" ] && [ -d "$dir" ] || { printf 'absent'; return 1; }
+  [ -d "$dir/node_modules/electron" ] || { printf 'absent'; return 1; }
+  # path.txt is written by the postinstall; dist/electron is what it points at.
+  if [ -f "$dir/node_modules/electron/path.txt" ] \
+     && [ -x "$dir/node_modules/electron/dist/electron" ]; then
+    printf 'ok'; return 0
+  fi
+  printf 'partial'; return 1
+}
+
+electron_remedy() {
+  printf 'the runtime download was skipped by npm — approve and rebuild:\n'
+  printf '  npm install-scripts approve electron && npm rebuild electron\n'
+  printf 'yonder: bin/ymir-install.sh --no-desktop if the web surfaces are enough'
+}

package/bin/hall-snapshot.sh

@@ -16,6 +16,17 @@
 #   (the Live Hall's own deck; the merged public site takes it from its build).
 set -u
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Where an app lives: apps/<surface> in a clone, node_modules/@zerwiz/<pkg> in an
+# npm install — both shapes, one resolver (bin/app-lib.sh).
+if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+  _ya="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yac in "$_ya/app-lib.sh" "$(dirname "$_ya")/bin/app-lib.sh"; do
+    [ -r "$_yac" ] && { . "$_yac"; YMIR_APP_LIB_LOADED=1; break; }
+  done
+  unset _ya _yac
+fi
+app_dir odrerir APP_ODRERIR || APP_ODRERIR=""
+
 ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
 
 # The operator's settings and secrets live in the home they chose, never in the
@@ -37,7 +48,7 @@ hoard_data_dir YMIR_DATA_DIR
 # 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).
 STATE="${BROKK_STATE_OVERRIDE:-$YMIR_STATE_DIR}"
-OUT="${1:-$ROOT/apps/odrerir/public/livehall.json}"
+OUT="${1:-$APP_ODRERIR/public/livehall.json}"
 
 runes_file="${BROKK_RUNES_FILE:-${YMIR_HOME:-$HOME/Documents/Ymir}/hodd/memory/runes_audit.md}"
 PROJECTS_FILE="${YMIR_HOME:-$HOME/Documents/Ymir}/hodd/identity/projects.yaml"

package/bin/sessrumnir-ensure.sh

@@ -20,7 +20,18 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-APP="$ROOT/apps/sessrumnir"
+# Where an app lives: apps/<surface> in a clone, node_modules/@zerwiz/<pkg> in an
+# npm install — both shapes, one resolver (bin/app-lib.sh).
+if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+  _ya="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yac in "$_ya/app-lib.sh" "$(dirname "$_ya")/bin/app-lib.sh"; do
+    [ -r "$_yac" ] && { . "$_yac"; YMIR_APP_LIB_LOADED=1; break; }
+  done
+  unset _ya _yac
+fi
+app_dir sessrumnir APP_SESSRUMNIR || APP_SESSRUMNIR=""
+
+APP="$APP_SESSRUMNIR"
 
 case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
 CMD="${1-}"; shift || true

package/bin/sessrumnir-sync.sh

@@ -24,7 +24,18 @@
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-APP="$ROOT/apps/sessrumnir"
+# Where an app lives: apps/<surface> in a clone, node_modules/@zerwiz/<pkg> in an
+# npm install — both shapes, one resolver (bin/app-lib.sh).
+if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+  _ya="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yac in "$_ya/app-lib.sh" "$(dirname "$_ya")/bin/app-lib.sh"; do
+    [ -r "$_yac" ] && { . "$_yac"; YMIR_APP_LIB_LOADED=1; break; }
+  done
+  unset _ya _yac
+fi
+app_dir sessrumnir APP_SESSRUMNIR || APP_SESSRUMNIR=""
+
+APP="$APP_SESSRUMNIR"
 FORK="$APP/fork"
 UPSTREAM_REPO="${SESSRUMNIR_UPSTREAM:-https://github.com/zerwiz/pi-desktop.git}"
 OWNED_JSON="$FORK/owned.json"

package/bin/sessrumnir.sh

@@ -14,6 +14,17 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# Where an app lives: apps/<surface> in a clone, node_modules/@zerwiz/<pkg> in an
+# npm install — both shapes, one resolver (bin/app-lib.sh).
+if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+  _ya="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yac in "$_ya/app-lib.sh" "$(dirname "$_ya")/bin/app-lib.sh"; do
+    [ -r "$_yac" ] && { . "$_yac"; YMIR_APP_LIB_LOADED=1; break; }
+  done
+  unset _ya _yac
+fi
+app_dir sessrumnir APP_SESSRUMNIR || APP_SESSRUMNIR=""
+
 
 # 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
@@ -27,7 +38,7 @@ if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
 fi
 hoard_state_dir YMIR_STATE_DIR
 hoard_data_dir YMIR_DATA_DIR
-APP="$ROOT/apps/sessrumnir"
+APP="$APP_SESSRUMNIR"
 PID_FILE="$YMIR_STATE_DIR/sessrumnir.pid"
 LOG_FILE="$YMIR_STATE_DIR/sessrumnir.log"
 

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,50 @@
+#!/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
+  # The general resolver (bin/app-lib.sh) knows both shapes; the smithy is one
+  # surface among them. The old skill symlink is the last resort, and a dangling
+  # one is not a home — the visualizer must be readable there.
+  local _smd_rv=${1-} _smd_c
+  [ -n "$_smd_rv" ] || return 2
+  if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+    local _sl; _sl="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    [ -r "$_sl/app-lib.sh" ] && { . "$_sl/app-lib.sh"; YMIR_APP_LIB_LOADED=1; }
+  fi
+  if app_dir smidja _smd_c 2>/dev/null && [ -d "$_smd_c/apps/visualizer" ]; then
+    printf -v "$_smd_rv" '%s' "$_smd_c"; return 0
+  fi
+  _smd_c="${YMIR_ROOT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/.agents/skills/$SMIDJA_PACKAGE"
+  [ -d "$_smd_c/apps/visualizer" ] && { printf -v "$_smd_rv" '%s' "$_smd_c"; return 0; }
+  printf -v "$_smd_rv" '%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
 #
@@ -52,7 +53,21 @@ hoard_local_env YMIR_ENV_FILE
 # repo (Rule 04).
 # shellcheck source=bin/hoard-lib.sh
 . "$SCRIPT_DIR/hoard-lib.sh"
+# shellcheck source=bin/app-lib.sh
+. "$SCRIPT_DIR/app-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 +78,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 +94,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 +118,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 +131,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 +548,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 +564,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)"
@@ -566,7 +587,8 @@ step_smidja() {
 # Hlidskjalf installs with npm (its own lockfile), not bun, and its API serves the
 # UI from ./dist. Without this step a fresh clone has no SPA and no build.
 step_spa() {
-  local app="$ROOT/apps/hlidskjalf"
+  local app; app_dir hlidskjalf app || app=""
+  local app_ok="$app"
   [ -d "$app" ] || { add hlidskjalf SKIP "no apps/hlidskjalf"; return 0; }
   if [ "$CHECK" = 0 ]; then
     if ! have npm; then
@@ -682,6 +704,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 d
+    app_dir "$shell" dir || continue
+    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
@@ -784,6 +822,7 @@ step_panes() {
 
 # Ask before touching the machine; --check only previews and never asks.
 [ "$CHECK" = 0 ] && confirm_install
+[ "$CHECK" = 0 ] && style_patience "the halls are being stood up for the first time"
 
 step_panes; step_prereqs; step_home; step_tree; step_apps; step_engines; step_models; step_hermes; step_sessrumnir; step_backend; step_host; step_sandbox; step_memory; step_smidja; step_spa; step_omarchy; step_loaders; step_gates; step_marks
 # Migrations MOVE private data — that is a write, and `--check` promises none.

package/bin/ymir-invite.sh

@@ -16,8 +16,19 @@
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-MODULE="$ROOT/apps/hlidskjalf/server/accounts.ts"
-STORE="$ROOT/apps/hlidskjalf/server/accounts.ts" # absolute: one definition of an account, wherever this is run from
+# Where an app lives: apps/<surface> in a clone, node_modules/@zerwiz/<pkg> in an
+# npm install — both shapes, one resolver (bin/app-lib.sh).
+if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+  _ya="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yac in "$_ya/app-lib.sh" "$(dirname "$_ya")/bin/app-lib.sh"; do
+    [ -r "$_yac" ] && { . "$_yac"; YMIR_APP_LIB_LOADED=1; break; }
+  done
+  unset _ya _yac
+fi
+app_dir hlidskjalf APP_HLIDSKJALF || APP_HLIDSKJALF=""
+
+MODULE="$APP_HLIDSKJALF/server/accounts.ts"
+STORE="$APP_HLIDSKJALF/server/accounts.ts" # absolute: one definition of an account, wherever this is run from
 
 die() { printf 'ymir-invite: %s\n' "$1" >&2; exit 1; }
 
@@ -25,7 +36,7 @@ command -v bun >/dev/null 2>&1 || die "bun is required (bin/ymir-install.sh inst
 
 # A tiny bun program per action — the module is the single source of truth.
 accounts() {
-  ( cd "$ROOT/apps/hlidskjalf" && bun -e "$1" )
+  ( cd "$APP_HLIDSKJALF" && bun -e "$1" )
 }
 
 [ -f "$MODULE" ] || die "the account store module is missing: $MODULE"