@zerwiz/ymir 0.1.7 → 0.1.9

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,121 @@
+#!/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; }
+
+# For a long hour: say what is happening and why it takes a while. A user who
+# knows the halls are being set right waits; a user watching a silent cursor
+# wonders whether it has broken.
+style_patience() {  # [what is being set right]
+  local what="${1:-the halls are being set right}"
+  printf '\n' >&2
+  style_line DO "much moves" "$what"
+  style_hint "      this hour is long, and nothing of yours is lost in it —"
+  style_hint "      roots come home, shapes are re-cut, names are set true again."
+  style_hint "      Your patience is noted, and it is earned."
+  printf '\n' >&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

package/bin/ymir.js

@@ -1,19 +1,32 @@
 #!/usr/bin/env node
 /**
- * ymir — the CLI the npm package publishes.
+ * ymir — the CLI the npm package publishes, and the operator's front door.
  *
  * It is a thin, honest wrapper: the real work lives in the shell scripts under
- * bin/, which are the same scripts a git clone runs. This file exists because
- * npm needs a Node entry point (`bin: ymir`) and because a package user should
- * not have to know where the checkout landed.
+ * bin/ and scripts/ — the same scripts a git clone runs. This file exists
+ * because npm needs a Node entry point (`bin: ymir`) and because an operator
+ * should never have to know where the package landed.
  *
- *   ymir                 # the same as `ymir install`
- *   ymir install [--yes] # first setup (idempotent, self-healing)
- *   ymir sense           # what THIS machine is
- *   ymir validate        # prove what stands
- *   ymir migrate         # heal an older home forward
+ * The doors are named for the figure whose work they do (the naming law):
+ * Eir heals, Gróa renews, Heimdall keeps the way in, Smíðja is the smithy and
+ * its board, Hlidskjalf the high seat, Sessrúmnir the seat-hall, Mímir the well.
+ *
+ *   ymir                 first setup (the same as `ymir install`)
+ *   ymir install [...]   first setup, idempotent and self-healing
+ *   ymir raise / lower   lift the hall, or lay it down
+ *   ymir eir             what stands, and mend what does not
+ *   ymir groa            take the latest, and mend this home forward
+ *   ymir heimdall        the way in: your credential, and invites
+ *   ymir smidja          the smithy's board (:8437) — build · start · stop · status
+ *   ymir hlidskjalf      the high seat's window
+ *   ymir sessrumnir      the seat-hall's window
+ *   ymir mimir           the memory well
+ *   ymir sense           what THIS machine is
  *   ymir --version
  *
+ * Colour appears only where a human is watching (a TTY, no NO_COLOR); the data
+ * on stdout is always plain TOON.
+ *
  * Exit codes follow the scripts: 0 ok, 1 error, 2 usage.
  */
 'use strict';
@@ -27,32 +40,65 @@ const pkg = (() => {
   try { return require(path.join(ROOT, 'package.json')); } catch { return { version: '0.0.0' }; }
 })();
 
-const TASKS = {
-  install: 'ymir-install.sh',
-  validate: 'ymir-validate.sh',
-  migrate: 'ymir-migrate.sh',
-  sense: 'host-sense.sh',
+// ── the cloth (the same palette as bin/ymir-style.sh, cut from the tokens) ───
+const colour = process.stderr.isTTY && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+const wrap = (code) => (s) => (colour ? `\u001b[${code}m${s}\u001b[0m` : `${s}`);
+const bone = wrap('38;2;207;195;169');
+const bronze = wrap('38;2;201;151;79');
+const faint = wrap('38;2;107;98;80');
+const blood = wrap('38;2;194;88;74');
+const bold = wrap('1');
+
+// ── the doors ────────────────────────────────────────────────────────────────
+// verb → { script, args } — args are prepended to whatever the operator passes,
+// so a verb can be a doorway to a sub-verb of a script that has several.
+const DOORS = {
+  install:    { script: 'bin/ymir-install.sh',    about: 'first setup (idempotent, self-healing)' },
+  raise:      { script: 'scripts/start.sh',       about: 'lift the hall — SPA, gate API, Nornir, bridges, the board' },
+  lower:      { script: 'scripts/stop.sh',        about: 'lay the hall down' },
+  eir:        { script: 'bin/eir-doctor.sh',      about: 'diagnose every surface; mend what is broken' },
+  groa:       { script: 'bin/groa-update.sh',     about: 'take the latest, then mend this home forward' },
+  heimdall:   { script: 'bin/ymir-setup-auth.sh', about: 'the way in — your credential (status · set · github)' },
+  invite:     { script: 'bin/ymir-invite.sh',     about: 'let someone else in (mint · list · revoke)' },
+  smidja:     { script: 'bin/smidja-board.sh',    about: "the smithy's board on :8437 (build · start · stop · status)" },
+  hlidskjalf: { script: 'scripts/electron.sh',    about: "the high seat's window", args: ['start', '--view', 'hlidskjalf'] },
+  sessrumnir: { script: 'scripts/electron.sh',    about: "the seat-hall's window", args: ['start', '--view', 'sessrumnir'] },
+  mimir:      { script: 'bin/mimir.sh',           about: 'the memory well' },
+  sense:      { script: 'bin/host-sense.sh',      about: 'what THIS machine is' },
+  plan:       { script: 'bin/ymir-plan.sh',       about: 'what an install would do here — writes nothing' },
+  migrate:    { script: 'bin/ymir-migrate.sh',    about: "heal this home's structure forward (Gr\u00f3a's mend)" },
+  validate:   { script: 'bin/ymir-validate.sh',   about: 'alias of `ymir eir`' },
 };
 
+// Names the law has not given a home are kept for a while, so a muscle memory
+// built yesterday still works — and says what to type instead.
+const RENAMED = { validate: 'eir', auth: 'heimdall', desktop: 'hlidskjalf', doctor: 'eir', update: 'groa' };
+
 function usage() {
-  process.stdout.write(
-    `ymir ${pkg.version} — the single-tenant agent operating system\n\n` +
-    'Usage:\n' +
-    '  ymir                 first setup (same as `ymir install`)\n' +
-    '  ymir install [--yes] first setup, idempotent and self-healing\n' +
-    '  ymir sense           report THIS machine (distro, session, desktop, capabilities)\n' +
-    '  ymir validate        verify the running system\n' +
-    '  ymir migrate         heal an older home forward\n' +
-    '  ymir --version\n\n' +
-    'Output is TOON. The scripts are the source of truth; this CLI only points at them.\n'
-  );
+  const lines = [];
+  lines.push('');
+  lines.push(`  ${bronze('\u16c9')}  ${bold('Ymir')} ${faint(pkg.version)}`);
+  lines.push(`     ${faint('the single-tenant agent operating system')}`);
+  lines.push('');
+  lines.push(bold('  The doors'));
+  for (const [verb, d] of Object.entries(DOORS)) {
+    lines.push(`    ${bronze(verb.padEnd(11))} ${faint(d.about)}`);
+  }
+  lines.push('');
+  lines.push(bold('  Composed by hand'));
+  lines.push(`    ${bronze('ymir groa migrate'.padEnd(11))} ${faint("heal this home's structure (run by groa / install)")}`);
+  lines.push(`    ${bronze('ymir heimdall set'.padEnd(11))} ${faint('set the operator password (or `github`)')}`);
+  lines.push('');
+  lines.push(faint('  A bare `ymir` runs the first setup. Output is TOON; colour only on a TTY.'));
+  lines.push('');
+  process.stdout.write(lines.join('\n') + '\n');
 }
 
 function run(script, args) {
-  const file = path.join(ROOT, 'bin', script);
+  const file = path.join(ROOT, script);
   if (!fs.existsSync(file)) {
-    process.stderr.write(`error: ${path.relative(ROOT, file)} is missing from this install\n`);
-    process.stderr.write('help: reinstall — npm i -g @zerwiz/ymir, or git clone the distro\n');
+    process.stderr.write(`${blood('error:')} ${script} is missing from this install\n`);
+    process.stderr.write(`${faint('help: reinstall — npm i -g @zerwiz/ymir, or git clone the distro')}\n`);
     process.exit(1);
   }
   const r = spawnSync('bash', [file, ...args], { stdio: 'inherit' });
@@ -62,17 +108,19 @@ function run(script, args) {
 const argv = process.argv.slice(2);
 const first = argv[0];
 
-if (!first) run(TASKS.install, []);
+if (!first) run(DOORS.install.script, []);
 if (first === '--version' || first === '-v' || first === '-V') {
   process.stdout.write(`${pkg.version}\n`);
   process.exit(0);
 }
 if (first === '--help' || first === '-h' || first === 'help') { usage(); process.exit(0); }
 
-const script = TASKS[first];
-if (!script) {
-  process.stderr.write(`error: unknown command ${first}\n`);
-  process.stderr.write('help: ymir [install|sense|validate|migrate|--version]\n');
+let door = DOORS[first];
+if (!door) {
+  const replacement = RENAMED[first];
+  process.stderr.write(`${blood('error:')} unknown door ${bold(first)}\n`);
+  if (replacement) process.stderr.write(`${faint(`help: the door is named \`ymir ${replacement}\` now (the naming law — a figure does the work)`)}\n`);
+  process.stderr.write(`${faint('help: `ymir --help` lists every door')}\n`);
   process.exit(2);
 }
-run(script, argv.slice(1));
+run(door.script, [...(door.args || []), ...argv.slice(1)]);

package/docs/design.md

@@ -226,7 +226,7 @@ everywhere; never put bronze text on bronze.
 - **Runecoded, not emoji.** A minimal, hand-drawn-style rune set replaces emoji
   in all UI: 16×16 and 24×24 grid, 2px stroke, chisel bevel on primary.
 - System subsystems each carry one rune-glyph (reuse Algiz-family geometry:
-  Bifrost gate, Ratatoskr squirrel, the Well). Map is in `midgard/design-system/icons.md` (TBD) — created from this doc.
+  Bifrost gate, Ratatoskr squirrel, the Well). Map is in `midgard/design-system/icons.md` and the library in `midgard/design-system/runes.md`.
 - Status dot: filled rune ring (ok) / half-ring (warn) / broken ring (danger), never color-only.
 
 ### 4.5 Surface & texture
@@ -345,7 +345,7 @@ All components read tokens from `tokens.css`; color-only states are forbidden
 
 - `docs/design.md` — this document (master).
 - `midgard/design-system/tokens.css` — the consumable design tokens.
-- `midgard/design-system/icons.md` — rune-glyph map (to create).
+- `midgard/design-system/icons.md` — rune-glyph map (21 glyphs, drawn in `icons/*.svg`).
 - `docs/ymir-rut.md` Part 3 — the original Rut design-system specification this
   document implements.
 - `docs/lore.md` §VI — house lineage behind the house accents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerwiz/ymir",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Ymir \u2014 the single-tenant agent operating system. Omarchy-first, host-aware, self-healing.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/zerwiz/ymir",

package/scripts/electron.sh

@@ -26,6 +26,19 @@ fi
 VERSION="1.1.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 hlidskjalf APP_HLIDSKJALF || APP_HLIDSKJALF=""
+app_dir odrerir APP_ODRERIR || APP_ODRERIR=""
+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
@@ -39,8 +52,8 @@ if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
 fi
 hoard_state_dir YMIR_STATE_DIR
 hoard_data_dir YMIR_DATA_DIR
-APP="$ROOT/apps/hlidskjalf"
-Odrerir_app="$ROOT/apps/odrerir"
+APP="$APP_HLIDSKJALF"
+Odrerir_app="$APP_ODRERIR"
 NO_INSTALL=0
 VIEW="${YMIR_DESKTOP_VIEW:-hlidskjalf}"
 VIEWS=(hlidskjalf smidja odrerir)

package/scripts/start.sh

@@ -17,6 +17,33 @@ if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
 fi
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# The cloth (bin/ymir-style.sh) — colour and words for the human watching.
+if [ -z "${YMIR_STYLE_LOADED:-}" ] && [ -r "$ROOT/bin/ymir-style.sh" ]; then
+  . "$ROOT/bin/ymir-style.sh"; YMIR_STYLE_LOADED=1; style_init
+fi
+# 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=""
+
+# 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
+
 
 # The operator's settings and secrets live in the home they chose, never in the
 # code tree — a packaged install replaces its tree on upgrade, and a credential
@@ -36,7 +63,7 @@ hoard_data_dir YMIR_DATA_DIR
 # 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).
-APP="$ROOT/apps/hlidskjalf"
+APP="$APP_HLIDSKJALF"
 RUN="$ROOT/.run"
 PID_FILE="$RUN/hlidskjalf.pid"
 LOG="$RUN/hlidskjalf.log"
@@ -68,7 +95,8 @@ else
 fi
 
 if [[ ! -d "$APP/node_modules" ]]; then
-  echo "Installing dependencies…"
+  style_patience "the seat's own dependencies are being fetched, then the hall is raised"
+echo "Installing dependencies…"
   (cd "$APP" && npm install --no-audit --no-fund)
 fi
 
@@ -116,7 +144,7 @@ fi
 # Smíðja's eye — the Vue trace visualizer (API :8437, UI :8438). Reads the repo's
 # own smidja.db and exposes the Sessions/Trace/Decisions/Stats views behind the
 # Hlidskjalf Sessions gate's "Open visualizer" button.
-VIZ_DIR="$ROOT/.agents/skills/smidja-factory/apps/visualizer"
+VIZ_DIR="${SMIDJA_VIZ:-}"
 VIZ_API_PORT="${SMIDJA_VIZ_API_PORT:-8437}"
 VIZ_UI_PORT="${SMIDJA_VIZ_UI_PORT:-8438}"
 VIZ_API_PID_FILE="$RUN/smidja-viz-api.pid"