@zerwiz/ymir 0.1.4 → 0.1.7

package/bin/nornir-job-nsr-compliance.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# nornir-job-nsr-compliance.sh — the NorthStar compliance round, nightly.
+#
+# Runs the deterministic NSR gates (.compliance/gates/check_*.sh — danger,
+# env, paths, platform, wiring) and carves one Rune with the verdict. A FAIL
+# is reported loudly in the Rune message — the morning briefing reads the
+# ledger, so a broken door is seen at sunrise, not found by accident.
+#
+# Stateless: run gates → write nothing but state/last + the Rune → exit.
+set -u
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${BROKK_ROOT_OVERRIDE:-$(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
+STATE="${BROKK_STATE_OVERRIDE:-$YMIR_STATE_DIR}"
+
+GATES_DIR="$ROOT/.compliance/gates"
+[ -d "$GATES_DIR" ] || { printf 'error: no NSR gates at %s\n' "$GATES_DIR"; exit 1; }
+
+passed=0; failed=0; failed_names=""
+for g in "$GATES_DIR"/check_*.sh; do
+  name=$(basename "$g" .sh)
+  if bash "$g" >/dev/null 2>&1; then
+    passed=$((passed+1))
+  else
+    failed=$((failed+1)); failed_names="$failed_names $name"
+  fi
+done
+
+printf 'nsr-compliance: gates=%d passed=%d failed=%d%s\n' \
+  "$((passed+failed))" "$passed" "$failed" "$failed_names"
+
+# shellcheck source=bin/runes-append.sh
+. "$ROOT/bin/runes-append.sh"
+if [ "$failed" = 0 ]; then
+  runes_append "nornir" "nsr.compliance" --message "NSR compliance: $passed/$passed gates passed" >/dev/null \
+    || printf 'nsr-compliance: rune append failed (non-fatal)\n'
+  exit 0
+else
+  runes_append "nornir" "nsr.compliance.failed" --message "NSR compliance FAIL: gates $failed_names FAILED — mend at sunrise" >/dev/null \
+    || printf 'nsr-compliance: rune append failed (non-fatal)\n'
+  exit 1
+fi

package/bin/nornir-job-observer.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# nornir-job-observer.sh - Huginn, the raven of observation.
+#
+# Read-only observation of the Ymir runtime into Runes. This job touches nothing
+# outside Ymir; every source below lives inside the repo (or the external worktree
+# root, which is read-only):
+#   docs/masterplan.md               open forge orders
+#   .agents/agents/*.md              the agent roster
+#   .agents/memory/well/             the well (episodes)
+#   workspace/memory/runes_audit.md  the ledger
+#   apps/smidja/smidja_data/smidja.db     Smíðja runs (read-only SQLite URI)
+#   ~/.treehouse                     external worktrees (read-only)
+#
+# CONTRACT: this job NEVER writes anywhere but state/observer.log and the Runes
+# ledger. It only reads manifests, SQLite databases in read-only mode, and small
+# state files. Every observation is carved as a Runes line and echoed to
+# state/observer.log. When a source is absent the job still carves an ABSENT
+# line — silence is never mistaken for health.
+#
+# Environment:
+#   BROKK_YGGDRASIL_ROOT  external worktree root to observe (default ~/.treehouse)
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+BROKK_HOME="${BROKK_HOME:-$ROOT}"
+STATE="${BROKK_STATE_OVERRIDE:-$BROKK_HOME/state}"
+# shellcheck source=bin/runes-append.sh
+. "$SCRIPT_DIR/runes-append.sh"
+
+WORKTREE_ROOT="${BROKK_YGGDRASIL_ROOT:-$HOME/.treehouse}"
+YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
+SMIDJA_DB="${YMIR_HOME:+$YMIR_HOME/smidja/smidja.db}"
+[ -z "${SMIDJA_DB:-}" ] || [ ! -f "$SMIDJA_DB" ] && SMIDJA_DB="$ROOT/apps/smidja/smidja_data/smidja.db"
+MASTERPLAN="$ROOT/docs/masterplan.md"
+WELL_DIR="$ROOT/.agents/memory/well"
+AGENTS_DIR="$ROOT/.agents/agents"
+RUNES_LEDGER="${YMIR_HOME:+$YMIR_HOME/memory/runes_audit.md}"
+[ -z "${RUNES_LEDGER:-}" ] || [ ! -r "$RUNES_LEDGER" ] && RUNES_LEDGER="$ROOT/workspace/memory/runes_audit.md"
+OBS_LOG="$STATE/observer.log"
+OBS_LAST="$STATE/observer.last"
+
+mkdir -p "$STATE"
+LOG_TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+observe() {  # <source> <message>
+  local source=$1 message=$2
+  printf '%s observer %s: %s\n' "$LOG_TS" "$source" "$message" >>"$OBS_LOG"
+  runes_append "huginn" "observer.$source" --message "$message" >/dev/null 2>&1 || true
+}
+
+printf 'OBSERVER - %s\n' "$LOG_TS"
+printf 'root=%s worktrees=%s\n' "$ROOT" "$WORKTREE_ROOT"
+
+# ---- ymir: forge orders (masterplan) -------------------------------------
+if [ -r "$MASTERPLAN" ]; then
+  open=$(grep -cE '^- Status: ADDED' "$MASTERPLAN" 2>/dev/null | tr -d '[:space:]')
+  working=$(grep -cE '^- Status:.*WORKING' "$MASTERPLAN" 2>/dev/null | tr -d '[:space:]')
+  done=$(grep -cE '\. \+ <[0-9]{4}' "$MASTERPLAN" 2>/dev/null | tr -d '[:space:]')
+  msg="masterplan readable; open=${open:-0} working=${working:-0} completed_notes=${done:-0}"
+  printf 'ymir.orders open=%s working=%s\n' "${open:-0}" "${working:-0}"
+else
+  msg="masterplan ABSENT at $MASTERPLAN"
+  printf 'ymir.orders ABSENT\n'
+fi
+observe "ymir.orders" "$msg"
+
+# ---- ymir: agent roster ---------------------------------------------------
+if [ -d "$AGENTS_DIR" ]; then
+  n=$(find "$AGENTS_DIR" -maxdepth 1 -name '*.md' 2>/dev/null | wc -l | tr -d '[:space:]')
+  msg="agent roster readable; agents=${n:-0}"
+  printf 'ymir.agents count=%s\n' "${n:-0}"
+else
+  msg="agent roster ABSENT at $AGENTS_DIR"
+  printf 'ymir.agents ABSENT\n'
+fi
+observe "ymir.agents" "$msg"
+
+# ---- ymir: the well (episodes) -------------------------------------------
+if [ -d "$WELL_DIR" ]; then
+  episodes=0
+  for f in "$WELL_DIR"/*.jsonl; do
+    [ -r "$f" ] || continue
+    c=$(wc -l <"$f" 2>/dev/null | tr -d '[:space:]')
+    episodes=$((episodes + ${c:-0}))
+  done
+  msg="well readable; episodes=${episodes}"
+  printf 'ymir.well episodes=%s\n' "$episodes"
+else
+  msg="well ABSENT at $WELL_DIR"
+  printf 'ymir.well ABSENT\n'
+fi
+observe "ymir.well" "$msg"
+
+# ---- ymir: the ledger -----------------------------------------------------
+if [ -r "$RUNES_LEDGER" ]; then
+  lines=$(wc -l <"$RUNES_LEDGER" 2>/dev/null | tr -d '[:space:]')
+  msg="runes ledger readable; lines=${lines:-0}"
+  printf 'ymir.runes lines=%s\n' "${lines:-0}"
+else
+  msg="runes ledger ABSENT at $RUNES_LEDGER"
+  printf 'ymir.runes ABSENT\n'
+fi
+observe "ymir.runes" "$msg"
+
+# ---- smidja: runs (smidja.db, read-only) ---------------------------------
+if [ -r "$SMIDJA_DB" ] && command -v python3 >/dev/null 2>&1; then
+  smidja_summary=$(python3 - "$SMIDJA_DB" 2>/dev/null <<'PY'
+import sqlite3, sys
+db = sys.argv[1]
+try:
+    c = sqlite3.connect('file:' + db + '?mode=ro', uri=True, timeout=3)
+except Exception as e:
+    print("open_failed=%s" % e)
+    sys.exit(0)
+def q(sql, default=None):
+    try:
+        return c.execute(sql).fetchone()[0]
+    except Exception:
+        return default
+sessions = q("select count(*) from sessions", 0)
+phases = q("select count(*) from phases", 0)
+gates = q("select count(*) from gate_results", 0)
+gate_fail = q("select count(*) from gate_results where passed=0", 0)
+print("sessions=%s phases=%s gates=%s gate_fail=%s" % (sessions, phases, gates, gate_fail))
+try:
+    rows = c.execute("select smidja_id,status from sessions order by rowid desc limit 3").fetchall()
+    print("recent=" + ",".join("%s:%s" % (r[0], r[1]) for r in rows))
+except Exception as e:
+    print("recent=unavailable(%s)" % e)
+try:
+    rows = c.execute("select status,count(*) from phases group by status order by 2 desc limit 5").fetchall()
+    print("phase_status=" + ",".join("%s:%s" % (r[0], r[1]) for r in rows))
+except Exception as e:
+    print("phase_status=unavailable(%s)" % e)
+c.close()
+PY
+)
+  first_line=$(printf '%s' "$smidja_summary" | head -n 1)
+  msg="smidja.db read-only: ${first_line:-unreadable}"
+  printf 'smidja.runs %s\n' "$msg"
+  printf '%s\n' "$smidja_summary" | tail -n +2 | sed 's/^/  /'
+else
+  if [ ! -r "$SMIDJA_DB" ]; then
+    msg="smidja.db ABSENT at $SMIDJA_DB"
+  else
+    msg="smidja.db present but python3 unavailable for read-only query"
+  fi
+  printf 'smidja.runs ABSENT/UNREADABLE\n'
+fi
+observe "smidja.runs" "$msg"
+
+# ---- worktrees (external, read-only) -------------------------------------
+if [ -d "$WORKTREE_ROOT" ]; then
+  wt_count=$(find "$WORKTREE_ROOT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d '[:space:]')
+  state_files=$(find "$WORKTREE_ROOT" -mindepth 2 -maxdepth 2 -name 'treehouse-state.json' 2>/dev/null | wc -l | tr -d '[:space:]')
+  msg="worktrees=${wt_count:-0} state_files=${state_files:-0}"
+  printf 'yggdrasil.worktrees trees=%s state_files=%s\n' "${wt_count:-0}" "${state_files:-0}"
+else
+  msg="worktree root ABSENT at $WORKTREE_ROOT"
+  printf 'yggdrasil.worktrees ABSENT\n'
+fi
+observe "yggdrasil.worktrees" "$msg"
+
+printf '%s\n' "observer summary written: $LOG_TS" >"$OBS_LAST"
+printf 'observer: observations carved (log=%s)\n' "$OBS_LOG"

package/bin/nornir-job-skillopt-sleep.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# nornir-job-skillopt-sleep.sh — SkillOpt overnight self-evolution.
+#
+# Runs SkillOpt-Sleep against Ymir's registered skills and Smíðja
+# prompt files. Harvests today's session trajectories, mines recurring
+# patterns, replays them, and consolidates validated skill edits behind
+# a held-out validation gate.
+#
+# OUTPUT: stages best_skill.md artifacts under .agents/skills/*/staging/
+#         — never auto-applies. Allfather reviews before merge.
+#
+# Environment:
+#   BROKK_HOME, BROKK_STATE_OVERRIDE
+#   SKILLOPT_PATH  path to the skillopt venv bin (default .venv/bin)
+#   SKILLOPT_SLEEP_OPTS  extra args to skillopt-sleep run
+#
+# Safety: writes only to staging dirs and Runes. Never touches
+# .agents/skills/*/SKILL.md directly. The Allfather approves adopted
+# skills before they go live.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+BROKK_HOME="${BROKK_HOME:-$ROOT}"
+STATE="${BROKK_STATE_OVERRIDE:-$BROKK_HOME/state}"
+SKILLOPT_PATH="${SKILLOPT_PATH:-$BROKK_HOME/.venv/bin}"
+SLEEP_OPTS="${SKILLOPT_SLEEP_OPTS:-}"
+
+# shellcheck source=bin/runes-append.sh
+. "$SCRIPT_DIR/runes-append.sh"
+
+STAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+STAGING="$BROKK_HOME/.agents/skills/skillopt-staging"
+
+mkdir -p "$STATE" "$STAGING" 2>/dev/null || true
+
+printf 'SKILLOPT-SLEEP - %s\n' "$STAMP"
+
+# ---- 1. Pre-flight ----------------------------------------------------
+if [ ! -x "$SKILLOPT_PATH/skillopt-sleep" ]; then
+  msg="skillopt-sleep not found at $SKILLOPT_PATH/skillopt-sleep — run bin/skillopt-setup.sh first"
+  printf 'skillopt: %s\n' "$msg"
+  runes_append "skillopt" "sleep.skipped" --message "$msg" >/dev/null 2>&1 || true
+  exit 0
+fi
+
+# ---- 2. Run SkillOpt-Sleep -------------------------------------------
+# Harvests sessions from ~/.claude and ~/.codex (if present),
+# mines recurring tasks, replays them, and stages best_skill.md.
+# --dry-run: report only. --auto-adopt: never set (human-in-the-loop).
+if [ -d "$BROKK_HOME/.claude" ] || [ -d "$BROKK_HOME/.codex" ]; then
+  "$SKILLOPT_PATH/skillopt-sleep" run \
+    --project "$BROKK_HOME" \
+    --scope all \
+    --source auto \
+    --lookback-hours 24 \
+    --max-sessions 50 \
+    --max-tasks 20 \
+    --target-skill-path "$STAGING/best_skill.md" \
+    --progress \
+    $SLEEP_OPTS 2>&1 | tee "$STATE/skillopt-sleep-$STAMP.log" || true
+else
+  msg="no Claude/Codex session dirs found at $BROKK_HOME — SkillOpt-Sleep needs agent transcripts"
+  printf 'skillopt: %s\n' "$msg"
+  runes_append "skillopt" "sleep.skipped" --message "$msg" >/dev/null 2>&1 || true
+fi
+
+# ---- 3. Stage report --------------------------------------------------
+if [ -f "$STAGING/best_skill.md" ]; then
+  size=$(wc -c <"$STAGING/best_skill.md" | tr -d '[:space:]')
+  msg="staged best_skill.md (${size} bytes) — review before adopt"
+else
+  msg="no new proposals this cycle"
+fi
+printf 'skillopt: %s\n' "$msg"
+runes_append "skillopt" "sleep.completed" --message "$msg" >/dev/null 2>&1 || true

package/bin/npm-publish.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# npm-publish.sh — publish through the HOARD's npm token, every single time.
+#
+# Why this exists: this machine once held two tokens, and the one in ~/.npmrc was
+# stale. A publish then failed with a 2FA refusal that looked like a policy
+# problem but was a credential problem, and a session was spent on it. The token
+# with bypass-2FA lives in the hoard. So the rule is: never trust ~/.npmrc — read
+# the token from the hoard, hand it to npm through a temporary userconfig, and
+# throw the file away.
+#
+#   bin/npm-publish.sh                 # the platform (the repo root manifest)
+#   bin/npm-publish.sh apps/hlidskjalf # one package
+#   bin/npm-publish.sh --all           # the platform + every app package
+#   bin/npm-publish.sh --whoami        # which account the hoard token is
+#   bin/npm-publish.sh --dry-run apps/odrerir
+#   bin/npm-publish.sh --unpublish @zerwiz/ymir@0.1.5     # take ONE version back
+#   bin/npm-publish.sh --unpublish @zerwiz/ymir@0.1.5 --dry-run
+#
+# Unpublish: npm allows ONE VERSION back for 72 hours after it was published;
+# past that only npm support can remove it, which is why this door names the
+# version and refuses anything vaguer. A whole package is not a one-word act —
+# that needs npm's own tooling and a deliberate decision, not a flag here.
+#
+# A prerelease version (0.1.8-alpha) is published under `--tag next` automatically
+# — npm refuses a prerelease on `latest`, which is the second half of the same
+# lesson. A scoped package always goes out with public access.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=bin/hoard-lib.sh
+. "$SCRIPT_DIR/hoard-lib.sh"
+
+DRY=0; WHO=0; ALL=0; UNPUBLISH=0; UNPUB_SPEC=""; TARGETS=()
+for a in "$@"; do
+  case "$a" in
+    --whoami) WHO=1 ;;
+    --dry-run) DRY=1 ;;
+    --all) ALL=1 ;;
+    --unpublish) UNPUBLISH=1 ;;
+    --unpublish=*) UNPUBLISH=1; UNPUB_SPEC="${a#*=}" ;;
+    -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+    -h|--help|"") sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -*) printf 'error: unknown flag %s\nhelp: bin/npm-publish.sh [--all|--whoami|--unpublish <spec>|--dry-run] [<package-dir>...]\n' "$a" >&2; exit 2 ;;
+    *) TARGETS+=("$a") ;;
+  esac
+done
+# --all is the platform plus every app package. The smithy's own repo is
+# cloned at apps/smidja-factory (the registry maps smidja there), so it is a
+# target like any other app: it publishes as @zerwiz/smidja.
+[ "$ALL" = 1 ] && TARGETS=("$ROOT" "$ROOT/apps/hlidskjalf" "$ROOT/apps/hlidskjalf-mobile" "$ROOT/apps/odrerir" "$ROOT/apps/sessrumnir" "$ROOT/apps/smidja-factory")
+[ "${#TARGETS[@]}" -eq 0 ] && [ "$WHO" = 0 ] && [ "$UNPUBLISH" = 0 ] && TARGETS=("$ROOT")
+# `--unpublish @scope/name@1.2.3` — the spec may also arrive positionally.
+[ "$UNPUBLISH" = 1 ] && UNPUB_SPEC="${UNPUB_SPEC:-${TARGETS[0]:-}}" 
+
+# ── the token, from the hoard ────────────────────────────────────────────────
+envfile=""; hoard_env envfile
+TOKEN=""
+if [ -r "$envfile" ]; then
+  TOKEN="$(sed -n 's/^NPM_TOKEN=//p' "$envfile" | head -1 | tr -d '"'"'"' ')"
+fi
+if [ -z "$TOKEN" ] && [ "$WHO" = 1 ]; then
+  printf 'npm[1]{token,state}:\n  "NPM_TOKEN","absent in %s"\n' "${envfile#"$HOME"/}"
+  exit 1
+fi
+if [ -z "$TOKEN" ]; then
+  printf 'error: the hoard holds no NPM_TOKEN\nhelp: add NPM_TOKEN=<granular token with bypass 2FA> to %s\n' "${envfile#"$HOME"/}" >&2
+  printf 'help: npmjs.com → Access Tokens → Generate → granular, scope @zerwiz, bypass 2FA on\n' >&2
+  exit 1
+fi
+
+cfg="$(mktemp)"; chmod 600 "$cfg"
+printf '//registry.npmjs.org/:_authToken=%s\n' "$TOKEN" >"$cfg"
+trap 'rm -f "$cfg"' EXIT
+
+if [ "$WHO" = 1 ]; then
+  who="$(npm whoami --userconfig "$cfg" 2>/dev/null || printf 'unknown')"
+  printf 'npm[2]{token,account}:\n  "source","%s"\n  "whoami","%s"\n' "${envfile#"$HOME"/}" "$who"
+  exit 0
+fi
+
+# ── unpublish ────────────────────────────────────────────────────────────────
+# Take ONE version back. npm permits it for 72 hours after publication; beyond
+# that it is npm support's door, not this one. The spec must name a version:
+# `@scope/name@1.2.3`, never a bare name.
+if [ "$UNPUBLISH" = 1 ]; then
+  case "$UNPUB_SPEC" in
+    *@*@*) ;;  # @scope/name@version
+    *@[0-9]*) ;;
+    *) printf 'error: --unpublish needs a package AND a version\nhelp: bin/npm-publish.sh --unpublish @scope/name@<version>\n' >&2; exit 2 ;;
+  esac
+  if [ "$DRY" = 1 ]; then
+    printf 'npm_unpublish[1]{spec,state}:\n  "%s","dry-run — nothing was removed"\n' "$UNPUB_SPEC"
+    exit 0
+  fi
+  out="$(npm unpublish "$UNPUB_SPEC" --force --userconfig "$cfg" 2>&1)"; rc=$?
+  if [ "$rc" = 0 ]; then
+    printf 'npm_unpublish[1]{spec,state}:\n  "%s","unpublished"\n' "$UNPUB_SPEC"
+    printf 'note: the registry CDN may serve the tarball for a while after this; publishing a\n'
+    printf 'note: newer version moves the "latest" tag off it at once.\n'
+  else
+    why="$(printf '%s' "$out" | grep -m1 -E 'npm error (code )?[A-Z0-9]+|E[0-9]{3}' | cut -c1-90)"
+    printf 'error: unpublish failed — %s\nhelp: is it inside the 72-hour window, and is the token the right account? (bin/npm-publish.sh --whoami)\n' "${why:-see npm log}" >&2
+    exit 1
+  fi
+  exit 0
+fi
+
+# ── publish ──────────────────────────────────────────────────────────────────
+printf 'npm_publish[%d]{package,version,tag,state}:\n' "${#TARGETS[@]}"
+failed=0
+for dir in "${TARGETS[@]}"; do
+  pkg="$dir/package.json"
+  if [ ! -f "$pkg" ]; then
+    printf '  "%s","-","-","SKIP (no package.json)"\n' "${dir#"$ROOT"/}"
+    continue
+  fi
+  name="$(sed -n 's/.*"name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$pkg" | head -1)"
+  ver="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$pkg" | head -1)"
+  case "$ver" in *-*) tag=next ;; *) tag=latest ;; esac   # a prerelease never rides `latest`
+  if [ "$DRY" = 1 ]; then
+    printf '  "%s","%s","%s","dry-run"\n' "$name" "$ver" "$tag"
+    continue
+  fi
+  out="$(cd "$dir" && npm publish --access public --tag "$tag" --userconfig "$cfg" 2>&1)"; rc=$?
+  if [ "$rc" = 0 ]; then
+    printf '  "%s","%s","%s","published"\n' "$name" "$ver" "$tag"
+  else
+    why="$(printf '%s' "$out" | grep -m1 -E 'npm error (code )?[A-Z0-9]+|E[0-9]{3}' | cut -c1-90)"
+    printf '  "%s","%s","%s","FAILED (%s)"\n' "$name" "$ver" "$tag" "${why:-see npm log}"
+    failed=$((failed+1))
+  fi
+done
+[ "$failed" = 0 ] || { printf 'error: %d package(s) did not publish\nhelp: bin/npm-publish.sh --whoami  (is the hoard token still the right account?)\n' "$failed" >&2; exit 1; }
+exit 0

package/bin/omarchy-hook-install.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# omarchy-hook-install.sh — let Ymir notice when Omarchy updates.
+#
+# Omarchy runs `~/.config/omarchy/hooks/post-update.d/*` after `omarchy update`
+# applies packages and migrations. Installing our sensor there means Ymir learns
+# the machine again the moment Omarchy moves — no polling, no cron.
+#
+# This writes only into ~/.config/omarchy/hooks/ (user config, per the Omarchy
+# skill: never /usr/share/omarchy/).
+#
+# Usage:
+#   bin/omarchy-hook-install.sh install|status|remove
+#   bin/omarchy-hook-install.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+HOOK_DIR="$HOME/.config/omarchy/hooks/post-update.d"
+HOOK="$HOOK_DIR/ymir-omarchy-sense.sh"
+
+is_omarchy() { [ -d /usr/share/omarchy ]; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+ACTION="${1:-status}"
+
+case "$ACTION" in
+  status)
+    if [ -f "$HOOK" ]; then
+      printf 'omarchy-hook[1]{hook,state}:\n  "%s","installed"\n' "$HOOK"
+    else
+      printf 'omarchy-hook[1]{hook,state}:\n  "%s","absent"\n' "$HOOK"
+    fi
+    ;;
+  install)
+    if ! is_omarchy; then
+      printf 'omarchy-hook[1]{state,detail}:\n  "skipped","not an Omarchy host (/usr/share/omarchy absent)"\n'
+      exit 0
+    fi
+    mkdir -p "$HOOK_DIR"
+    cat >"$HOOK" <<EOF
+#!/usr/bin/env bash
+# Installed by Ymir (bin/omarchy-hook-install.sh). Re-learns the machine after
+# an Omarchy update so the agent stays current with this user's setup.
+exec "$ROOT/bin/omarchy-sense.sh" observe --quiet
+EOF
+    chmod +x "$HOOK"
+    printf 'omarchy-hook[1]{hook,state}:\n  "%s","installed"\n' "$HOOK"
+    ;;
+  remove)
+    rm -f "$HOOK"
+    printf 'omarchy-hook[1]{hook,state}:\n  "%s","removed"\n' "$HOOK"
+    ;;
+  *) printf 'error: unknown action %s\nhelp: bin/omarchy-hook-install.sh [install|status|remove]\n' "$ACTION" >&2; exit 2 ;;
+esac

package/bin/omarchy-install.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# omarchy-install.sh — the Omarchy installation layer (Rule 05).
+#
+# Ymir is **Omarchy-first**: this is the first-class desktop layer. It owns
+# everything that is true of Omarchy and not of the core — learning the host, the
+# post-update hook, the suggested shell plugins, each app's numbered Hyprland
+# desktop, the launcher entries, the editor's own desktop, the away-mode alarm
+# channel, and the terminal backend Ymir needs.
+#
+# The core installer (bin/ymir-install.sh) is portable and runs on any platform;
+# it calls THIS only when the host is Omarchy. Every step here therefore detects
+# its host and reports a clean skip elsewhere — the layer is never assumed.
+#
+# Usage:
+#   bin/omarchy-install.sh            # apply (idempotent)
+#   bin/omarchy-install.sh --check    # report state only, change nothing
+#   bin/omarchy-install.sh --list     # the steps, in order
+#   bin/omarchy-install.sh --version
+#
+# Output: Galdr TOON. Exit 0 ok, 1 a step failed, 2 usage.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# 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
+
+# portability shim (bin/ymir-platform.sh)
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  _ymir_dir="$SCRIPT_DIR"
+  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
+
+CHECK=0
+for a in "$@"; do
+  case "$a" in
+    --check)   CHECK=1 ;;
+    --list)    printf 'omarchy-steps[7]{order,step,owns}:\n'
+               printf '  1,"sense","learn the host: packages, configs, monitors, scale, Omarchy version"\n'
+               printf '  2,"hook","re-learn after every `omarchy update` (post-update.d)"\n'
+               printf '  3,"plugins","offer the shell plugins that render Ymir'"'"'s organs; never forced"\n'
+               printf '  4,"desktops","one numbered Hyprland desktop per app + the launcher entries"\n'
+               printf '  5,"editor","the editor opens on its own desktop"\n'
+               printf '  6,"alarm","the away-mode alarm channel and the crash sensor"\n'
+               printf '  7,"backend","the terminal backend Ymir needs (herdr 0.14+/0.8.0+, else tmux)"\n'
+               exit 0 ;;
+    --version|-v) printf '%s\n' "$VERSION"; exit 0 ;;
+    -h|--help) sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) printf 'error: unknown flag %s\nhelp: bin/omarchy-install.sh [--check|--list]\n' "$a" >&2; exit 2 ;;
+  esac
+done
+
+declare -a T S D
+add() { T+=("$1"); S+=("$2"); D+=("$3"); }
+isfail=0
+
+have() { command -v "$1" >/dev/null 2>&1; }
+is_omarchy() { [ -d /usr/share/omarchy ] && return 0; [ "$(ymir_os 2>/dev/null)" = linux ] && [ -d "$HOME/.config/omarchy" ]; }
+
+# ── the gate ─────────────────────────────────────────────────────────────────
+if ! is_omarchy; then
+  printf 'omarchy[1]{step,status,detail}:\n'
+  printf '  "layer","SKIP","not an Omarchy host — the core runs without this layer"\n'
+  exit 0
+fi
+
+run() {  # <step> <label> <cmd...>
+  local step=$1 label=$2; shift 2
+  if [ "$CHECK" = 1 ]; then add "$step" OK "$label (check)"; return 0; fi
+  if "$@" >/dev/null 2>&1; then add "$step" OK "$label"; else add "$step" WARN "$label — command reported failure"; fi
+}
+
+# ── 1. learn the host ────────────────────────────────────────────────────────
+if [ -x "$SCRIPT_DIR/omarchy-sense.sh" ]; then
+  if [ "$CHECK" = 1 ]; then
+    snap="$("$SCRIPT_DIR/omarchy-sense.sh" status 2>&1 | sed -n '2p' | tr -d '"' | cut -c1-60)"
+    add sense OK "${snap:-no snapshot yet}"
+  else
+    "$SCRIPT_DIR/omarchy-sense.sh" observe --quiet >/dev/null 2>&1 && add sense OK "host recorded" || add sense WARN "could not record the host"
+  fi
+else
+  add sense SKIP "no omarchy-sense.sh"
+fi
+
+# ── 2. the post-update hook ──────────────────────────────────────────────────
+if [ "$CHECK" = 1 ]; then
+  [ -e "$HOME/.config/omarchy/hooks/post-update.d/ymir-omarchy-sense.sh" ] && add hook OK "installed" || add hook WARN "not installed (run without --check)"
+else
+  run hook "installed" "$SCRIPT_DIR/omarchy-hook-install.sh" install
+fi
+
+# ── 3. the suggested shell plugins (offered, never forced) ───────────────────
+if [ "$CHECK" = 1 ]; then
+  add plugins OK "offered via bin/omarchy-plugins.sh add"
+else
+  "$SCRIPT_DIR/omarchy-plugins.sh" suggest >/dev/null 2>&1 && add plugins OK "offered (add with: bin/omarchy-plugins.sh add)" || add plugins WARN "could not list the plugins"
+fi
+
+# ── 4. desktops + launcher entries ───────────────────────────────────────────
+if [ "$CHECK" = 1 ]; then
+  add desktops OK "would place each app on its own numbered desktop + install the entries"
+else
+  if [ -x "$SCRIPT_DIR/desktop-place.sh" ]; then
+    if "$SCRIPT_DIR/desktop-place.sh" apply >/dev/null 2>&1; then
+      n=$(ls "$HOME/.local/share/applications"/ymir-*.desktop 2>/dev/null | wc -l | tr -d ' ')
+      add desktops OK "numbered desktops placed; $n launcher entr(y|ies) installed"
+    else
+      add desktops WARN "desktop-place.sh reported failure"; isfail=1
+    fi
+  else
+    add desktops SKIP "no desktop-place.sh"
+  fi
+fi
+
+# ── 5. the editor's own desktop ──────────────────────────────────────────────
+if [ -x "$SCRIPT_DIR/editor-place.sh" ]; then
+  run editor "the editor opens on its own desktop" "$SCRIPT_DIR/editor-place.sh" apply
+else
+  add editor SKIP "no editor-place.sh"
+fi
+
+# ── 6. the away-mode alarm channel + the crash sensor ────────────────────────
+if [ -e "$YMIR_SETTINGS_DIR/wedge-alarm" ]; then
+  add alarm OK "channel kept"
+elif [ "$CHECK" = 1 ]; then
+  add alarm WARN "channel not written (run without --check)"
+elif mkdir -p "$YMIR_SETTINGS_DIR" 2>/dev/null && \
+     printf '# The channel the away-mode wedge alarm fires on when an escalation\n# cannot be delivered into the pane. See bin/wedge-notify.sh.\ndesktop\n' >"$YMIR_SETTINGS_DIR/wedge-alarm" 2>/dev/null; then
+  add alarm OK "channel written ($YMIR_SETTINGS_DIR/wedge-alarm)"
+else
+  add alarm WARN "could not write $YMIR_SETTINGS_DIR/wedge-alarm"
+fi
+
+# ── 7. the terminal backend Ymir needs ───────────────────────────────────────
+if [ "$CHECK" = 1 ]; then
+  if have herdr || have tmux; then add backend OK "present"; else add backend WARN "no herdr and no tmux"; fi
+elif [ -x "$SCRIPT_DIR/herdr-ensure.sh" ]; then
+  if "$SCRIPT_DIR/herdr-ensure.sh" >/dev/null 2>&1 || have tmux; then add backend OK "herdr or tmux ready"; else add backend WARN "no terminal backend — bin/herdr-ensure.sh"; fi
+else
+  add backend SKIP "no herdr-ensure.sh"
+fi
+
+printf 'omarchy[%s]{step,status,detail}:\n' "${#T[@]}"
+for i in "${!T[@]}"; do printf '  "%s","%s","%s"\n' "${T[$i]}" "${S[$i]}" "${D[$i]}"; done
+[ "$isfail" = 1 ] && exit 1
+exit 0