@zerwiz/ymir 0.1.5 → 0.1.8

package/bin/ui-truth-check.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# ui-truth-check.sh — the panel's number must equal the machine's number.
+#
+# The wiring order's last row, and the one that makes the rest trustworthy: a
+# board can render beautifully and still lie. This compares what the UI is SERVED
+# against what the machine actually holds, per source, and FAILS on a mismatch.
+#
+#   bin/ui-truth-check.sh          # compare, TOON, exit 0/1
+#   bin/ui-truth-check.sh --help
+#
+# It reads endpoints as the DESKTOP SEAT (loopback + the marker), which is the
+# trusted seat rule 09 allows — the web door would answer 401 and prove nothing
+# about the data.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+GATE="${HLIDSKJALF_API_PORT:-3889}"
+# shellcheck source=bin/hoard-lib.sh
+. "$SCRIPT_DIR/hoard-lib.sh"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help) sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+have() { command -v "$1" >/dev/null 2>&1; }
+have curl || { printf 'error: curl is required\nhelp: install curl\n' >&2; exit 1; }
+
+json_len() { python3 -c 'import json,sys
+try: print(len(json.load(sys.stdin)))
+except Exception: print(0)' 2>/dev/null || echo 0; }
+
+verdict="PASS"; details=""
+
+# ── the fleet: herdr vs the connector vs the endpoint ─────────────────────────
+SRC_JSON="$("$SCRIPT_DIR/hlidskjalf-agents.sh" 2>/dev/null || printf '[]')"
+src_n=$(printf '%s' "$SRC_JSON" | json_len)
+UI_JSON="$(curl -s --max-time 8 -H 'x-ymir-surface: desktop' "http://127.0.0.1:${GATE}/api/agents" 2>/dev/null || printf '[]')"
+ui_n=$(printf '%s' "$UI_JSON" | json_len)
+if have "${HERDR_BIN_PATH:-herdr}"; then
+  herd_n="$("${HERDR_BIN_PATH:-herdr}" pane list 2>/dev/null | python3 -c 'import json,sys
+try: d=json.load(sys.stdin)
+except Exception: print(0); raise SystemExit
+panes=(d.get("result") or {}).get("panes") or d.get("panes") or []
+print(sum(1 for p in panes if p.get("agent")))' 2>/dev/null || echo 0)"
+else
+  herd_n="unknown"
+fi
+[ "$src_n" = "$ui_n" ] || { verdict="FAIL"; details="$details fleet:connector=$src_n,served=$ui_n"; }
+# The connector is ROSTER-FIRST: it reports the agents (the who) and the seats (the
+# where), so its total legitimately exceeds the pane count. What must not happen is
+# FEWER entries than panes - a standing seat hidden from the board. Panes are a subset.
+[ "$herd_n" = "unknown" ] || [ "$src_n" -ge "$herd_n" ] || { verdict="FAIL"; details="$details fleet:connector=$src_n,herdr=$herd_n"; }
+
+# ── the ledger: the hoard's, against what the gate serves ─────────────────────
+hoard_root _hoard
+LEDGER="$_hoard/memory/runes_audit.md"
+ledger_n=0
+[ -r "$LEDGER" ] && ledger_n=$(grep -c '^[[:space:]]*{' "$LEDGER" 2>/dev/null || echo 0)
+UI_RUNES="$(curl -s --max-time 8 -H 'x-ymir-surface: desktop' "http://127.0.0.1:${GATE}/api/runes" 2>/dev/null || printf '[]')"
+ui_runes_n=$(printf '%s' "$UI_RUNES" | json_len)
+[ "$ledger_n" = "$ui_runes_n" ] || { verdict="FAIL"; details="$details ledger=$ledger_n,served=$ui_runes_n"; }
+
+printf 'ui_truth[6]{source,count,note}:\n'
+printf '  "herdr panes","%s","what the machine holds"\n' "$herd_n"
+printf '  "the connector","%s","bin/hlidskjalf-agents.sh"\n' "$src_n"
+printf '  "the endpoint","%s","/api/agents as the desktop seat"\n' "$ui_n"
+printf '  "ledger entries","%s","the hoard'"'"'s ledger"\n' "$ledger_n"
+printf '  "ledger served","%s","/api/runes as the desktop seat"\n' "$ui_runes_n"
+printf '  "verdict","%s","%s"\n' "$verdict" "$([ -n "$details" ] && printf 'mismatch:%s' "$details" || printf 'the board may be believed')"
+
+[ "$verdict" = "PASS" ] || { printf 'error: the UI and the machine disagree\nhelp: %s\n' "${details:-see the rows above}" >&2; exit 1; }
+exit 0

package/bin/valknut-load.sh

@@ -26,7 +26,7 @@ PI_GLOBAL="${HOME}/.pi/agent/agents"
 # seated. This loader DEPLOYS that source into the single home.
 PI_EXT_SRC="$ROOT/.pi/shared/extensions"
 PI_EXT_HOME="${HOME}/.pi/agent/extensions"
-OC_LOCAL="$ROOT/.opencode/agent"
+OC_LOCAL="$ROOT/.opencode/agents"
 SKILLS="$ROOT/.agents/skills"
 
 usage() {
@@ -167,6 +167,18 @@ fi
 
 if [ "$MODE_OPENCODE" = 1 ]; then
   add opencode-config "$ROOT/opencode.json" "$(config_out "$ROOT/opencode.json.example" "$ROOT/opencode.json")"
+  # OpenCode reads `.opencode/agents/` (PLURAL). The singular `.opencode/agent/`
+  # was never read by the harness at all — twenty correct symlinks in a directory
+  # no loader opens, which is why only the agents declared by hand in
+  # opencode.json ever appeared. Migrate a legacy singular dir forward so an old
+  # home heals instead of silently keeping its agents invisible.
+  if [ -d "$ROOT/.opencode/agent" ] && [ ! -e "$ROOT/.opencode/agents" ]; then
+    mv "$ROOT/.opencode/agent" "$ROOT/.opencode/agents" 2>/dev/null \
+      && add opencode-migrate "$ROOT/.opencode/agents" "legacy .opencode/agent/ moved to .opencode/agents/" \
+      || add opencode-migrate "$ROOT/.opencode/agents" "ERROR could not migrate"
+  fi
+  # Count what is bound here; the binding itself happens further down, after
+  # `link_agents` is defined (this block runs before that definition).
   if [ -d "$OC_LOCAL" ]; then
     n=$(ls "$OC_LOCAL"/*.md 2>/dev/null | wc -l | tr -d ' ')
     add opencode "$OC_LOCAL" "native ($n agents)"
@@ -190,6 +202,17 @@ if [ "$MODE_PI" = 1 ]; then
   # Deploy the shared extensions into their single home. Copy, not link: a
   # broken link would silently disable a tool, and pi reads the file directly.
   # Idempotent — identical files are left untouched.
+  # The CONTRACT, deployed globally: pi reads an AGENTS.md from its agent home in
+  # every session, whatever the workspace. Without this, Sessrumnir (or any pi
+  # session) started in another project loads THAT project's rules and knows
+  # nothing of Ymir - no Brokk, no laws, no lore. Symlink, so the tree stays the
+  # single source and an update is picked up with no re-install.
+  if [ -d "$HOME/.pi/agent" ]; then
+    ln -sfn "$ROOT/AGENTS.md" "$HOME/.pi/agent/AGENTS.md" 2>/dev/null \
+      && add pi-global-contract "$HOME/.pi/agent/AGENTS.md" "the Ymir contract, loaded in every pi session" \
+      || add pi-global-contract "$HOME/.pi/agent/AGENTS.md" "ERROR"
+  fi
+
   if [ -d "$PI_EXT_SRC" ]; then
     mkdir -p "$PI_EXT_HOME" 2>/dev/null
     dep_n=0
@@ -199,7 +222,22 @@ if [ "$MODE_PI" = 1 ]; then
       if [ -f "$PI_EXT_HOME/$b" ] && cmp -s "$f" "$PI_EXT_HOME/$b"; then continue; fi
       cp -f "$f" "$PI_EXT_HOME/$b" && dep_n=$((dep_n+1))
     done
-    add pi-extensions "$PI_EXT_HOME" "$dep_n deployed (shared single home)"
+    # Their supporting modules are one level away, under the extensions' own lib:
+    # the shared extensions require sibling lib modules, and deploying the
+    # top-level files ALONE ships extensions that cannot load. That is exactly
+    # what pi reported: Failed to load extension, Cannot find module ./lib/....
+    # A deploy that copies a file but not the module it imports is not a deploy.
+    PI_EXT_LIB="$ROOT/.pi/extensions/lib"
+    if [ -d "$PI_EXT_LIB" ]; then
+      mkdir -p "$PI_EXT_HOME/lib" 2>/dev/null
+      for f in "$PI_EXT_LIB"/*; do
+        [ -e "$f" ] || continue
+        b=$(basename "$f")
+        if [ -f "$PI_EXT_HOME/lib/$b" ] && cmp -s "$f" "$PI_EXT_HOME/lib/$b"; then continue; fi
+        cp -f "$f" "$PI_EXT_HOME/lib/$b" && dep_n=$((dep_n+1))
+      done
+    fi
+    add pi-extensions "$PI_EXT_HOME" "$dep_n deployed (shared single home, lib included)"
   fi
 fi
 
@@ -248,8 +286,8 @@ if [ "$MODE_STATUS" = 0 ]; then
     add "${hd#.}-agents" "$ROOT/$hd/agents" "bound ($n)"
   done
   if [ -d "$ROOT/.opencode" ]; then
-    n=$(link_agents "$ROOT/.opencode/agent" short) || n=0
-    add opencode-agents "$ROOT/.opencode/agent" "bound ($n)"
+    n=$(link_agents "$OC_LOCAL" short) || n=0
+    add opencode-agents "$OC_LOCAL" "bound ($n)"
   fi
 fi
 

package/bin/wedge-notify.sh

@@ -20,7 +20,20 @@ CHANNEL="${1:-unknown}"
 SUMMARY="${2:-}"
 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/wedge-alarm.log"
 
 # "discard" is the library-mode default so no test posts a real notification.

package/bin/workspace-rag.sh

@@ -16,8 +16,21 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# 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
 STORE="$ROOT/.agents/memory/well/workspace.jsonl"
-REALM_FILE="$ROOT/data/realm.md"
+REALM_FILE="$YMIR_DATA_DIR/realm.md"
 DEFAULT_REALM="$(head -n1 "$REALM_FILE" 2>/dev/null | tr -d '[:space:]')"
 # Never assume the company's slug: resolve the operator's realm neutrally.
 if [ -z "$DEFAULT_REALM" ]; then . "$SCRIPT_DIR/realm-lib.sh"; ymir_active_realm "$ROOT" DEFAULT_REALM; fi

package/bin/ymir-install.sh

@@ -6,13 +6,17 @@
 #
 # 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
 #
-# Consent: a real install (not --check) asks the operator to accept the plan
-# before any change is made. Non-interactive callers must pass --yes.
+# The consent a real install asks for is not a recited paragraph: it is the PLAN
+# printed by bin/ymir-plan.sh — probed on THIS host, one row per step, each with
+# its state and the reason for it. A paragraph drifts behind the code; a plan is
+# computed from it every run.
 #
-# Exit: 0 all good (or --check), 1 a step failed, 2 usage, 3 declined.
+# Exit: 0 all good (or --check/--plan), 1 a step failed, 2 usage, 3 declined.
 set -u
 
 # --- portability shim: bin/ymir-platform.sh --------------------------------
@@ -27,30 +31,72 @@ fi
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
-WORKSPACE="${YMIR_WORKSPACE:-$YMIR_HOME/workspaces}"
+
+# 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
+# must never sit in a tree that ships (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_settings_dir YMIR_SETTINGS_DIR
+hoard_local_env YMIR_ENV_FILE
+# The home is the OPERATOR's to choose, never ours to assume. Resolution:
+# $YMIR_HOME (explicit) → the choice recorded at a previous installation →
+# the one documented default. An interactive run ASKS and RECORDS the answer
+# (step_home); --check never writes, --yes takes what is recorded.
 # The hoard resolves through the shared lib, so the installer can never disagree
 # with bin/hodd.sh about where private data lives — and never points inside the
 # repo (Rule 04).
 # 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"
 
-CHECK=0; SKIP_ENGINES=0; SKIP_SERVICES=0; ASSUME_YES=0; NO_DESKTOP=0
-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
+CHECK=0; SKIP_ENGINES=0; SKIP_SERVICES=0; ASSUME_YES=0; NO_DESKTOP=0; PLAN_ONLY=0; PLAN_ARGS=()
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help) sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
 while [ $# -gt 0 ]; do
   case "$1" in
     --check) CHECK=1; shift ;;
+    --plan|--dry-run) PLAN_ONLY=1; 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|--skip-engines|--skip-services|--no-desktop|--yes]\n' "$1" >&2; exit 2 ;;
+    *) 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
 done
 
+# The plan is a question, not a change: it prints and exits without writing.
+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.
@@ -62,33 +108,28 @@ TOON="install[0]{step,status,detail}:"
 # ── consent ──────────────────────────────────────────────────────────────
 # Show exactly what will change and require explicit acceptance. A real
 # install touches the machine (packages, a docker image, raised services),
-# so it never proceeds on silence.
+# so it never proceeds on silence. The plan is COMPUTED here (bin/ymir-plan.sh
+# probes this host) — never a paragraph that can drift behind the code.
 confirm_install() {
   [ "$ASSUME_YES" = 1 ] && return 0
   if [ ! -t 0 ]; then
-    printf 'error: refusing a non-interactive install without --yes\nhelp: re-run with --yes to accept non-interactively, or --check to preview\n' >&2
+    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 — this will make the following changes:
-
-  • install in USER SPACE (no sudo): bun, uv  — and 'mcp<2>' via pip
-  • create the workspace tree (work/ · personal/ · companies · registries)
-  • install the OSS engines: treehouse, no-mistakes (+ sandcastle if present)
-  • ensure the Hermes worker runtime
-  • ensure a terminal backend (herdr — Þjazi — preferred, else tmux)
-  • learn this machine (Omarchy version, packages, configs, monitors, scale)
-  • place the desktop apps on their own numbered desktops
-  • build the Utgard sandbox image 'utgard-runner:latest' (needs docker access)
-  • create the Smiðja database and build the visualizer UI
-  • load agents/skills and write workspace/INSTALL.md
-  • install the git delivery gates (secret · branch · changelog)
-  • raise the runtime services (Hlidskjalf SPA + gate API + bridges)
-  • open BOTH desktop apps so you see them: Hlidskjalf + Smíðja
-  • verify the running system and report what stands
+Each row is a phase, a step, its state, and why.
+
+  DO        a change will be made
+  SKIP      already satisfied — nothing to do
+  INFO      a fact about this host; no change implied
+  BLOCKED   cannot run — the reason names what is missing
+  CONSENT   needs your word (a credential, an invite, the desktop shells)
 
 Nothing is deleted. Every step is idempotent.
 PLAN
+  printf '\n'
+  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
@@ -197,6 +238,112 @@ YAML
   add tree OK "workspace/{personal} · companies · registries · hoard (outside the repo) (created $created)"
 }
 
+# ── 2a. the home the operator chooses ────────────────────────────────────────
+# Everything private — docs, secrets, identity, projects, workspaces, memory —
+# lives in ONE place the operator owns, and it is the operator's to name. A real
+# interactive run asks once and records the answer under ~/.config/ymir/home, so
+# every later script resolves the same home without being told again. --check
+# never writes; --yes takes what is already recorded (or the documented default).
+step_home() {
+  local rec="" chosen=""
+  ymir_home_record rec
+  if [ -n "${YMIR_HOME:-}" ] && [ "$CHECK" = 1 ]; then add home OK "home: $YMIR_HOME"; return; fi
+  if [ -n "$rec" ]; then
+    add home OK "home: $YMIR_HOME (the choice recorded at installation)"
+    return
+  fi
+  if [ "$ASSUME_YES" = 1 ] || [ ! -t 0 ]; then
+    if ymir_home_record_set "$YMIR_HOME" 2>/dev/null; then
+      add home OK "home: $YMIR_HOME (default recorded — change it any time with YMIR_HOME=<path> bin/ymir-install.sh)"
+    else
+      add home WARN "home: $YMIR_HOME (could not record the choice under $YMIR_CONFIG_DIR — pass YMIR_HOME=<path> to every run)"
+    fi
+    return
+  fi
+  printf '\nWhere shall your home live?\n'
+  printf 'Everything private is kept there — docs, secrets, identity, projects,\n'
+  printf 'workspaces, memory — never in the code tree, never in this package.\n'
+  printf 'Home [%s]: ' "$YMIR_HOME"
+  IFS= read -r chosen || true
+  [ -n "$chosen" ] && YMIR_HOME="${chosen/#\~/$HOME}"
+  if [ -e "$YMIR_HOME" ]; then
+    printf 'using %s — what is already there is kept; nothing is deleted.\n' "$YMIR_HOME"
+  fi
+  # Re-resolve the roots the choice moved: the hoard within the home, and the
+  # workspace tree beneath it. A second run finds the record and never asks again.
+  hoard_root HOARD
+  WORKSPACE="${YMIR_WORKSPACE:-$YMIR_HOME/workspaces}"
+  if ymir_home_record_set "$YMIR_HOME"; then
+    add home OK "home: $YMIR_HOME (recorded — later runs need not ask)"
+  else
+    add home WARN "home: $YMIR_HOME (could not record the choice; pass YMIR_HOME=<path> to every run)"
+  fi
+}
+
+# ── 2b. app repos (the app split) ────────────────────────────────────────────
+# The apps live in their OWN repos (zerwiz/hlidskjalf · hlidskjalf-mobile ·
+# odrerir · sessrumnir · smidja), registered in the home registry with a
+# `repo: apps/<path>` block. The monorepo never tracks them; installation
+# clones each into the tree — never guessing a remote, always reading the
+# registry. A present repo is fast-forwarded; a missing one cloned. The smithy
+# engine (apps/smidja) is stamped from the cloned factory's templates, exactly
+# as install.py does for a target repo.
+step_apps() {
+  local reg="$HOARD/identity/projects.yaml"
+  if [ ! -r "$reg" ]; then
+    add apps SKIP "no registry — no app repos to pull ($reg)"
+    return 0
+  fi
+  # Parse blocks that carry `repo: apps/<path>` and a `git:` inline dict.
+  local entries
+  entries=$(awk '
+    /^  - id:/ { repo="" }
+    /^    repo: apps\// { repo=substr($2, 6) }
+    /^    git: / {
+      line=$0; host=""; owner=""; grepo=""
+      if (match(line, /host: [A-Za-z0-9._-]+/)) host=substr(line, RSTART+6, RLENGTH-6)
+      if (match(line, /owner: [A-Za-z0-9_-]+/)) owner=substr(line, RSTART+7, RLENGTH-7)
+      if (match(line, /repo: [A-Za-z0-9._-]+/)) grepo=substr(line, RSTART+6, RLENGTH-6)
+      if (repo != "" && owner != "" && grepo != "") print repo "|" host "|" owner "|" grepo
+      repo=""
+    }' "$reg")
+  if [ -z "$entries" ]; then
+    add apps OK "no apps/ projects registered — nothing to pull"
+    return 0
+  fi
+  local ok=0 skip=0 fail=0 missing=0
+  while IFS='|' read -r rel host owner grepo; do
+    [ -n "$rel" ] || continue
+    local path="$ROOT/apps/$rel"
+    if [ "$CHECK" = 1 ]; then
+      if [ -d "$path/.git" ]; then add apps OK "$rel present ($owner/$grepo)"; ok=$((ok+1));
+      elif [ -d "$path" ]; then add apps WARN "$rel present but not a git clone — re-install to replace"; skip=$((skip+1));
+      else add apps WARN "$rel absent — a full run clones $owner/$grepo"; missing=$((missing+1)); fi
+      continue
+    fi
+    if [ -d "$path/.git" ]; then
+      if (cd "$path" && git fetch origin 2>/dev/null && git merge --ff-only origin/main >/dev/null 2>&1); then add apps OK "$rel up to date ($owner/$grepo)"; ok=$((ok+1));
+      else add apps OK "$rel present ($owner/$grepo; pull refused — local changes?)"; skip=$((skip+1)); fi
+    elif [ -d "$path" ]; then
+      add apps WARN "$rel present but not a git clone — move $path aside and re-run"; skip=$((skip+1))
+    else
+      local url="https://github.com/$owner/$grepo.git"
+      if git clone -q "$url" "$path" 2>/dev/null; then add apps OK "$rel cloned ($owner/$grepo)"; ok=$((ok+1));
+      else add apps WARN "$rel clone failed — run: git clone $url $path"; fail=$((fail+1)); fi
+    fi
+  done <<< "$entries"
+  # The smithy engine: apps/smidja is stamped from the cloned factory's
+  # templates (the monorepo tracks neither). The config template follows.
+  local factory="$ROOT/apps/smidja-factory" eng="$ROOT/apps/smidja"
+  if [ "$CHECK" = 0 ] && [ -d "$factory/templates/smidja" ] && [ ! -e "$eng/smidja_modules" ]; then
+    mkdir -p "$eng"
+    cp -rn "$factory/templates/smidja/." "$eng/" 2>/dev/null
+    [ -f "$factory/templates/smidja.config.yaml" ] && { mkdir -p "$eng/smidja_smidja_config"; cp -n "$factory/templates/smidja.config.yaml" "$eng/smidja_smidja_config/smidja.config.yaml" 2>/dev/null; }
+    add apps OK "smidja engine stamped into apps/smidja"
+  fi
+  if [ "$fail" -gt 0 ]; then add apps WARN "$fail app clone(s) failed (offline?)"; fi
+}
+
 # ── 3. engines ───────────────────────────────────────────────────────────────
 step_engines() {
   [ "$SKIP_ENGINES" = 1 ] && { add engines SKIP "--skip-engines"; return; }
@@ -240,7 +387,6 @@ step_models() {
     if [ ! -f "$HOME/.pi/agent/models.json" ]; then
       "$SCRIPT_DIR/models-detect.sh" --write >/dev/null 2>&1 && add models OK "seeded ~/.pi/agent/models.json (was absent)"
     fi
-    printf 'models: local-model testing is first-class — load the modeltesting skill; llama.cpp (llama-server/llama-swap) is fastest on the GPU; research your hardware best settings online; for coding use >= 80000 context.\n'
   fi
   if [ -x "$SCRIPT_DIR/model-hardware.sh" ]; then
     "$SCRIPT_DIR/model-hardware.sh" >/dev/null 2>&1 && add models OK "profiled this machine (data/local-models.md; online research left for Brokk)"
@@ -323,35 +469,37 @@ step_omarchy() {
 }
 
 step_host() {
-  # Core host learning: record THIS machine so the agent helps with the real one.
-  # The Omarchy-specific extras (desktop placement, the post-update hook, the
-  # plugin offer, the desktop alarm channel) belong to the Omarchy layer and are
-  # applied by step_omarchy; nothing here assumes Omarchy.
-  local learned=no
-  if [ "$CHECK" = 1 ]; then
-    if [ -x "$SCRIPT_DIR/omarchy-sense.sh" ]; then
-      local snap; snap="$("$SCRIPT_DIR/omarchy-sense.sh" status 2>&1 | sed -n '2p' | tr -d '"' | cut -c1-60)"
-      learned="${snap:-no snapshot yet}"
-    fi
-    add host OK "host snapshot: ${learned}"
-  else
-    if [ -x "$SCRIPT_DIR/omarchy-sense.sh" ]; then
-      "$SCRIPT_DIR/omarchy-sense.sh" observe --quiet >/dev/null 2>&1 && learned=yes
-    fi
-    add host OK "host learnt=${learned}"
+  # Core host learning: sense THIS machine on EVERY host with the portable
+  # sensor (Rule 05). The Omarchy-specific RECORDING (omarchy-sense observe), the
+  # post-update hook, desktop placement, the plugin offer, and the desktop alarm
+  # channel belong to the Omarchy layer and are applied by step_omarchy; nothing
+  # here assumes Omarchy.
+  local seen="unknown"
+  if [ -x "$SCRIPT_DIR/host-sense.sh" ]; then
+    # host-sense TOON row 2 is: os, id, family, session, desktop
+    local row; row="$("$SCRIPT_DIR/host-sense.sh" 2>/dev/null | sed -n '2p')"
+    [ -n "$row" ] && seen="$(printf '%s' "$row" | sed -E 's/^[[:space:]]*"//; s/"[[:space:]]*$//; s/","/ \/ /g')"
   fi
-
-  # The Allfather's own agent setup, seeded from the tracked template. Idempotent:
-  # config/agents.yaml is private and is never overwritten once set. --check never
-  # writes, so it only reports.
-  if [ -e "$ROOT/config/agents.yaml" ]; then
+  add host OK "host sensed: ${seen}"
+
+  # The operator's own agent setup, seeded from the tracked template into the
+  # home's settings dir — settings are the operator's, never the package's.
+  # Idempotent: the seeded file is private and is never overwritten once set.
+  # --check writes nothing, so it only reports. The template is code, so it is
+  # read from wherever the tree keeps it: `config/` in a clone (a symlink the
+  # npm tarball cannot carry), else `.agents/config/`.
+  if [ -e "$YMIR_SETTINGS_DIR/agents.yaml" ]; then
     add agents-config OK "kept (private, never overwritten)"
-  elif [ "$CHECK" = 1 ]; then
-    add agents-config WARN "not seeded (run without --check)"
-  elif [ -r "$ROOT/config/agents.yaml.example" ] && cp "$ROOT/config/agents.yaml.example" "$ROOT/config/agents.yaml" 2>/dev/null; then
-    add agents-config OK "seeded from the template"
+    return 0
+  fi
+  local tpl="$ROOT/config/agents.yaml.example"
+  [ -r "$tpl" ] || tpl="$ROOT/.agents/config/agents.yaml.example"
+  if [ "$CHECK" = 1 ]; then
+    add agents-config WARN "not seeded yet — a real run writes $YMIR_SETTINGS_DIR/agents.yaml"
+  elif [ -r "$tpl" ] && mkdir -p "$YMIR_SETTINGS_DIR" && cp "$tpl" "$YMIR_SETTINGS_DIR/agents.yaml" 2>/dev/null; then
+    add agents-config OK "seeded $YMIR_SETTINGS_DIR/agents.yaml from the template"
   else
-    add agents-config WARN "could not seed config/agents.yaml"
+    add agents-config WARN "could not seed $YMIR_SETTINGS_DIR/agents.yaml"
   fi
 }
 
@@ -398,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
@@ -414,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)"
@@ -487,12 +635,44 @@ step_gates() {
     else
       add gates WARN "hooks not installed — bin/secret-guard.sh --install && bin/changelog-guard.sh --install"
     fi
+    # The home repo is where the private data lives, so its ward matters more
+    # than this repo's four. Report it separately so a dormant vault is visible.
+    local hh; hh="${YMIR_HOME:-$HOME/Documents/Ymir}/.git/hooks/pre-commit"
+    if [ -x "$hh" ]; then add hoard-gate OK "home pre-commit seated";
+    else add hoard-gate WARN "home hooks not installed — bin/hoard-guard.sh --install"; fi
     return
   fi
   [ -x "$SCRIPT_DIR/secret-guard.sh" ] && "$SCRIPT_DIR/secret-guard.sh" --install >/dev/null 2>&1 || true
   [ -x "$SCRIPT_DIR/changelog-guard.sh" ] && "$SCRIPT_DIR/changelog-guard.sh" --install >/dev/null 2>&1 || true
+  # Seat the ward on the PRIVATE home too — every install layer, every machine.
+  [ -x "$SCRIPT_DIR/hoard-guard.sh" ] && "$SCRIPT_DIR/hoard-guard.sh" --install >/dev/null 2>&1 || true
   if [ -x "$pre_commit" ] && [ -x "$pre_push" ]; then add gates OK "pre-commit + pre-push installed"
   else add gates WARN "could not write .git/hooks — gates are dormant"; fi
+  local hh; hh="${YMIR_HOME:-$HOME/Documents/Ymir}/.git/hooks/pre-commit"
+  if [ -x "$hh" ]; then add hoard-gate OK "home pre-commit seated";
+  else add hoard-gate WARN "home hooks not seated — bin/hoard-guard.sh --install"; fi
+}
+
+# ── 6c. desktop marks (the rune, the entry, the contract) ────────────────────
+#
+# Every app wears its OWN rune in the operator's desktop: the icon into the icon
+# theme, the .desktop entry into their applications dir (so every app is
+# dockable and pinnable), and the Ymir contract deployed into pi's agent home so
+# every session - in ANY folder - loads Brokk. Idempotent, and it writes to the
+# operator's real data dir, never a sandbox one.
+step_marks() {
+  if [ ! -x "$SCRIPT_DIR/design-icon.sh" ]; then add marks SKIP "no design-icon.sh"; return; fi
+  if [ "$CHECK" = 1 ]; then
+    n=$(ls "$HOME/.local/share"/applications/ymir-*.desktop 2>/dev/null | wc -l | tr -d ' ')
+    add marks OK "$n desktop app marks installed"
+    return
+  fi
+  "$SCRIPT_DIR/design-icon.sh" mint --all >/dev/null 2>&1 || true
+  n=$("$SCRIPT_DIR/design-icon.sh" install 2>/dev/null | grep -c '"ymir-') || n=0
+  [ -r "$HOME/.pi/agent/AGENTS.md" ] || [ -d "$HOME/.pi/agent" ] && {
+    ln -sfn "$ROOT/AGENTS.md" "$HOME/.pi/agent/AGENTS.md" 2>/dev/null || true
+  }
+  add marks OK "$n app marks (rune icon + entry) · Ymir contract in the pi agent home"
 }
 
 # ── 7. services ──────────────────────────────────────────────────────────────
@@ -521,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
@@ -624,7 +820,11 @@ step_panes() {
 # Ask before touching the machine; --check only previews and never asks.
 [ "$CHECK" = 0 ] && confirm_install
 
-step_panes; step_prereqs; step_tree; 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; bin/ymir-migrate.sh apply >/dev/null 2>&1 || true; step_auth; step_invite; step_register
+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.
+# Only a real run heals the home forward; the preview leaves it untouched.
+if [ "$CHECK" = 0 ]; then bin/ymir-migrate.sh apply >/dev/null 2>&1 || true; fi
+step_auth; step_invite; step_register
 [ "$CHECK" = 0 ] && step_services
 [ "$CHECK" = 0 ] && step_desktop
 [ "$CHECK" = 0 ] && step_validate