@zerwiz/ymir 0.1.4 → 0.1.5

package/bin/pi-local.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# pi-local.sh — run a Pi agent on a LOCAL model, reusable.
+#
+#   bin/pi-local.sh "<prompt>"                       # default local model
+#   bin/pi-local.sh -m <model> "<prompt>"            # another llama.cpp model
+#   PI_LOCAL_MODEL=... bin/pi-local.sh "<prompt>"
+#
+# The model id is the EXACT llama.cpp served id (…@quant). Defaults come from
+# config/agents.yaml resolution; override with -m/--model or the env vars.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+PROVIDER="${PI_LOCAL_PROVIDER:-llama-cpp}"
+MODEL="${PI_LOCAL_MODEL:-frontend-design-expert-8b@q4_k_m}"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -m|--model) MODEL=${2-}; shift 2 ;;
+    -p|--provider) PROVIDER=${2-}; shift 2 ;;
+    --) shift; break ;;
+    -*) printf 'error: unknown flag %s\n' "$1" >&2; exit 2 ;;
+    *) break ;;
+  esac
+done
+PROMPT="${*:-}"
+[ -n "$PROMPT" ] || { printf 'error: usage: bin/pi-local.sh [-m model] "<prompt>"\n' >&2; exit 2; }
+
+command -v pi >/dev/null 2>&1 || { printf 'error: pi is not on PATH\n' >&2; exit 1; }
+
+printf 'pi-local[1]{provider,model}:\n  "%s","%s"\n' "$PROVIDER" "$MODEL" >&2
+exec "$SCRIPT_DIR/local-model-lock.sh" pi --print --model "$PROVIDER/$MODEL" "$PROMPT"

package/bin/pi-seat.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# pi-seat.sh — seat a Pi agent in a VISIBLE herdr pane, optionally on a local
+# model. Reusable for Ymir features and users when the stack is running.
+#
+#   bin/pi-seat.sh                                   # pi + default local model, no task
+#   bin/pi-seat.sh --task "design a hero"            # seat, then prompt
+#   bin/pi-seat.sh -n sindri -m qwen3.6-35b-q4_k_s --task "..."
+#   bin/pi-seat.sh --tab --task "..."               # seat in a new tab
+#
+# Requires HERDR_ENV=1 (run inside a herdr pane). Splits a pane beside you,
+# starts pi with --model <provider>/<id>, and prints the pane + agent name.
+set -u
+
+VERSION="1.0.0"
+PROVIDER="${PI_LOCAL_PROVIDER:-llama-cpp}"
+MODEL="${PI_LOCAL_MODEL:-frontend-design-expert-8b@q4_k_m}"
+NAME="pi-local"; TASK=""; WHERE="--current"; DIR="$PWD"; MAIN=0
+
+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
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -n|--name) NAME=${2-}; shift 2 ;;
+    -m|--model) MODEL=${2-}; shift 2 ;;
+    -p|--provider) PROVIDER=${2-}; shift 2 ;;
+    --task) TASK=${2-}; shift 2 ;;
+    --dir) DIR=${2-}; shift 2 ;;
+    --tab) WHERE="--tab"; shift ;;
+    --main) MAIN=1; shift ;;
+    *) printf 'error: unknown arg %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+
+have() { command -v "$1" >/dev/null 2>&1; }
+[ "${HERDR_ENV:-}" = "1" ] || { printf 'error: not inside herdr (HERDR_ENV unset)\nhelp: run this from a herdr pane\n' >&2; exit 1; }
+have herdr || { printf 'error: herdr not on PATH\n' >&2; exit 1; }
+
+# Isolation is standard: seat in a Yggdrasil worktree, not the main tree, unless
+# the Allfather explicitly asks for main (--main).
+if [ "${MAIN:-0}" != 1 ] && [ -x "$SCRIPT_DIR/yggdrasil.sh" ] && git -C "$PWD" rev-parse --show-toplevel >/dev/null 2>&1; then
+  wt="$(git -C "$PWD" rev-parse --show-toplevel)/.yggdrasil/$NAME"
+  [ -d "$wt" ] || "$SCRIPT_DIR/yggdrasil.sh" create "$NAME" >/dev/null 2>&1
+  [ -d "$wt" ] && { DIR="$wt"; printf 'pi-seat[1]{isolation,worktree}:\n  "on","%s"\n' "$DIR" >&2; }
+fi
+
+# 1. a place to sit — a new tab, or a split beside the caller.
+if [ "$WHERE" = "--tab" ]; then
+  PANE="$(herdr tab create --cwd "$DIR" --label "pi:$NAME" 2>/dev/null | python3 -c 'import json,sys;print(json.load(sys.stdin)["result"]["root_pane"]["pane_id"])')"
+else
+  PANE="$(herdr pane split --current --direction right --cwd "$DIR" 2>/dev/null | python3 -c 'import json,sys;print(json.load(sys.stdin)["result"]["pane"]["pane_id"])')"
+fi
+[ -n "$PANE" ] || { printf 'error: could not create a pane\n' >&2; exit 1; }
+
+# 2. start pi on the chosen model in that pane.
+if ! herdr agent start "$NAME" --kind pi --pane "$PANE" -- --model "$PROVIDER/$MODEL" >/dev/null 2>&1; then
+  printf 'error: could not start pi in %s\nhelp: the pane must sit at an interactive shell prompt\n' "$PANE" >&2; exit 1
+fi
+
+# 3. optional first task.
+[ -n "$TASK" ] && herdr agent prompt "$NAME" "$TASK" >/dev/null 2>&1 || true
+
+printf 'pi-seat[1]{agent,pane,provider,model}:\n  "%s","%s","%s","%s"\n' "$NAME" "$PANE" "$PROVIDER" "$MODEL"

package/bin/prereq-ensure.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# prereq-ensure.sh — self-healing prerequisite engine for Ymir.
+#
+# The installer should not leave the operator to fix prerequisites by hand.
+# This helper provisions what it can, in USER SPACE (no sudo), and reports
+# clearly what it could not do. Every action is idempotent.
+#
+# Engine:
+#   bun       — installs via the official installer, then ~/.bun/bin on PATH
+#   uv        — installs via the official installer (used for Python provisioning)
+#   pip       — reported with a per-manager hint (needs a system package)
+#   mcp<2     — pip-installed into the user site
+#   pythonX.Y — fetched by uv in user space when a package needs another Python
+#
+# Usage:
+#   bin/prereq-ensure.sh bun | uv | mcp | python <X.Y> | all
+#   bin/prereq-ensure.sh status
+#   bin/prereq-ensure.sh --version
+#
+# Output: Galdr TOON. Exit 0 when the target is present afterwards, 1 otherwise.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/ymir-platform.sh
+[ -r "$SCRIPT_DIR/ymir-platform.sh" ] && . "$SCRIPT_DIR/ymir-platform.sh"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+BUN_HOME="${BUN_INSTALL:-$HOME/.bun}"
+
+add_path() { case ":$PATH:" in *":$1:"*) ;; *) PATH="$1:$PATH" ;; esac; }
+have() { command -v "$1" >/dev/null 2>&1; }
+say()  { printf 'prereq[1]{name,state,detail}:\n  "%s","%s","%s"\n' "$1" "$2" "$3"; }
+
+# ── the memory engine (engram) ───────────────────────────────────────────────
+# engram needs Python >=3.12,<3.14. A modern distro may ship something newer
+# (this box: 3.14), so the engine is installed into a COMPATIBLE interpreter and
+# that interpreter is recorded for the bridge to reuse. uv can supply one.
+ENGRAM_PY_FILE="${YMIR_ENGRAM_PY:-$HOME/.config/ymir/engram-python}"
+
+engram_python() {  # echo an interpreter that can (or could) run engram
+  local p
+  for p in "${YMIR_ENGRAM_PYTHON:-}" python3.12 python3.13; do
+    [ -n "$p" ] || continue
+    command -v "$p" >/dev/null 2>&1 && { printf '%s' "$p"; return 0; }
+  done
+  if command -v uv >/dev/null 2>&1; then
+    p="$(uv python find 3.12 2>/dev/null || uv python find 3.13 2>/dev/null || true)"
+    [ -n "$p" ] && { printf '%s' "$p"; return 0; }
+  fi
+  printf 'python3'
+}
+
+ensure_engram() {
+  local py; py="$(engram_python)"
+  if "$py" -c 'import engram' >/dev/null 2>&1; then
+    mkdir -p "$(dirname "$ENGRAM_PY_FILE")" 2>/dev/null
+    printf '%s\n' "$py" >"$ENGRAM_PY_FILE" 2>/dev/null
+    say engram present "importable under $py"
+    return 0
+  fi
+  # is the chosen interpreter even in engram's supported range?
+  if ! "$py" -c 'import sys; sys.exit(0 if sys.version_info >= (3,11) else 1)' >/dev/null 2>&1; then
+    if command -v uv >/dev/null 2>&1 && uv python install 3.12 >/dev/null 2>&1; then
+      py="$(uv python find 3.12 2>/dev/null || printf '%s' "$py")"
+    fi
+  fi
+  if "$py" -c 'import sys; sys.exit(0 if sys.version_info >= (3,11) else 1)' >/dev/null 2>&1 \
+     && "$py" -m pip install --user --break-system-packages -q engdbram >/dev/null 2>&1 \
+     && "$py" -c 'import engram' >/dev/null 2>&1; then
+    mkdir -p "$(dirname "$ENGRAM_PY_FILE")" 2>/dev/null
+    printf '%s\n' "$(command -v "$py" 2>/dev/null || printf '%s' "$py")" >"$ENGRAM_PY_FILE" 2>/dev/null
+    say engram installed "$py"
+    return 0
+  fi
+  say engram absent "install failed (engdbram needs Python >=3.11) — try: uv python install 3.12"
+  return 1
+}
+
+ensure_bun() {
+  add_path "$BUN_HOME/bin"
+  if have bun; then say bun present "$(bun --version 2>/dev/null)"; return 0; fi
+  if curl -fsSL https://bun.sh/install 2>/dev/null | bash >/dev/null 2>&1; then
+    add_path "$BUN_HOME/bin"
+    if have bun; then say bun installed "$(bun --version 2>/dev/null)"; return 0; fi
+  fi
+  say bun absent "install manually: https://bun.sh (or your package manager)"
+  return 1
+}
+
+ensure_uv() {
+  add_path "$HOME/.local/bin"
+  if have uv; then say uv present "$(uv --version 2>/dev/null | awk '{print $2}')"; return 0; fi
+  if curl -fsSL https://astral.sh/uv/install.sh 2>/dev/null | sh >/dev/null 2>&1; then
+    add_path "$HOME/.local/bin"
+    if have uv; then say uv installed "$(uv --version 2>/dev/null | awk '{print $2}')"; return 0; fi
+  fi
+  say uv absent "install manually: https://astral.sh/uv"
+  return 1
+}
+
+# Fetch a Python interpreter in user space via uv. Prints its path on success.
+ensure_python() {
+  local want="$1"
+  if have "python$want"; then
+    say "python$want" present "$(command -v "python$want")"
+    command -v "python$want"
+    return 0
+  fi
+  ensure_uv >/dev/null 2>&1 || true
+  if have uv; then
+    if uv python install "$want" >/dev/null 2>&1; then
+      local p
+      p="$(uv python find "$want" 2>/dev/null || true)"
+      if [ -n "$p" ]; then say "python$want" installed "$p"; printf '%s\n' "$p"; return 0; fi
+    fi
+  fi
+  say "python$want" absent "uv could not fetch it (offline?)"
+  return 1
+}
+
+ensure_mcp() {
+  if python3 -c "from mcp.server.fastmcp import FastMCP" >/dev/null 2>&1; then
+    say "mcp<2" present "importable"
+    return 0
+  fi
+  if python3 -m pip --version >/dev/null 2>&1; then
+    if python3 -m pip install --user --break-system-packages -q 'mcp<2' >/dev/null 2>&1 \
+       && python3 -c "from mcp.server.fastmcp import FastMCP" >/dev/null 2>&1; then
+      say "mcp<2" installed "user site"
+      return 0
+    fi
+  fi
+  say "mcp<2" absent "needs pip (a system package on this distro)"
+  return 1
+}
+
+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
+
+case "$1" in
+  bun)    ensure_bun ;;
+  uv)     ensure_uv ;;
+  mcp)    ensure_mcp ;;
+  engram) ensure_engram ;;
+  python) ensure_python "${2:?usage: prereq-ensure.sh python <X.Y>}" ;;
+  status)
+    engine="$(ymir_container_engine_name 2>/dev/null || true)"
+    printf 'prereq[6]{name,state,detail}:\n'
+    for c in git python3 bun gh uv; do
+      if have "$c"; then printf '  "%s","present","%s"\n' "$c" "$(command -v "$c")"
+      else printf '  "%s","absent","-"\n' "$c"; fi
+    done
+    # Docker or Podman — the one this host actually has.
+    if [ -n "$engine" ]; then printf '  "%s","present","%s"\n' "$engine" "$(command -v "$engine")"
+    else printf '  "docker/podman","absent","-"\n'; fi
+    ;;
+  all)
+    rc=0
+    ensure_bun || rc=1
+    ensure_uv  || rc=1
+    ensure_mcp || rc=1
+    exit $rc ;;
+  *) printf 'error: unknown target %s\nhelp: bin/prereq-ensure.sh [bun|uv|mcp|engram|python X.Y|status|all]\n' "$1" >&2; exit 2 ;;
+esac

package/bin/private-guard.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# private-guard.sh — enforce the Hoard boundary (Rule 04). Nothing under a
+# private path may be TRACKED except its allowed guard/scaffold/example. Besides
+# secret-guard (values) and docs-guard (public docs/), this stops a private
+# path being committed — even by `git add -f` or a `git mv` that bypasses
+# .gitignore.
+#
+#   bin/private-guard.sh           # inspect the staged change
+#   bin/private-guard.sh --all     # inspect every tracked file
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Private roots — nothing here is public. These paths may exist locally
+# but MUST never be committed: they live at YMIR_HOME, env-driven.
+FORBID='^(hodd/|svartalfaheim/|state/|data/|workspace/(work|personal|memory|companies)/|workspace/config/|workspace/marketing/|workspace/INSTALL\.md|assets/reference/state/|\.a2a/|\.env)'
+# Allowed tracked exceptions inside those roots.
+ALLOW='^(hodd/(README\.md|\.gitignore|AGENTS\.example\.md|[^/]+\.example(\.md)?)$|svartalfaheim/.*(README\.md|\.gitkeep|\.gitignore|\.example(\.md)?)$|state/\.gitkeep$|data/[^/]+\.example$|assets/reference/state/[^/]+\.example$|\.env\.example|\.env\.sample)$'
+
+scan_list() {
+  local hit=0 f
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    if printf '%s\n' "$f" | grep -Eq "$FORBID" && ! printf '%s\n' "$f" | grep -Eq "$ALLOW"; then
+      printf 'private-guard: tracked private path: %s\n' "$f" >&2
+      hit=1
+    fi
+  done
+  return "$hit"
+}
+
+if [ "${1:-}" = "--all" ]; then
+  scan_list < <(git -C "$ROOT" ls-files)
+else
+  scan_list < <(git -C "$ROOT" diff --cached --name-only --diff-filter=ACM)
+fi || { printf 'private-guard: blocked — that path is private; keep it in the Hoard and untracked\n' >&2; exit 1; }
+exit 0

package/bin/project-git.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# project-git.sh — resolve a project's GitHub block from the master registry
+# (`workspace/projects.yaml`). The runtime consumes this instead of guessing a
+# remote. Auth is a REFERENCE (app|pat|ssh|gh), never a value.
+#
+# Usage:
+#   project-git.sh <project-id> [--field host|owner|repo|remote|default_branch|auth]
+#   project-git.sh list
+#   project-git.sh --version
+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"
+hoard_root _hoard
+REG="${PROJECTS_YAML:-$_hoard/identity/projects.yaml}"
+[ -f "$REG" ] || REG="$ROOT/workspace/projects.yaml"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+ID="${1-}"; shift || true
+FIELD=""
+while [ $# -gt 0 ]; do case "$1" in --field) FIELD=${2-}; shift 2 ;; *) shift ;; esac; done
+[ -f "$REG" ] || { printf 'error: registry not found: %s\nhelp: run bin/ymir-install.sh\n' "$REG" >&2; exit 1; }
+
+if [ "$ID" = "list" ]; then
+  n=$(grep -cE '^\s*-\s+id:' "$REG" 2>/dev/null || echo 0)
+  printf 'projects[%s]{id}:\n' "$n"
+  grep -E '^\s*-\s+id:' "$REG" | sed -E 's/^\s*-\s+id:\s*/  "/; s/\s*$/" /'
+  exit 0
+fi
+[ -n "$ID" ] || { printf 'error: needs a project id\nhelp: bin/project-git.sh <project-id> [--field owner]\n' >&2; exit 2; }
+
+block="$(awk -v id="$ID" '
+  $0 ~ "^[[:space:]]*-[[:space:]]+id:[[:space:]]*"id"[[:space:]]*$" {f=1; next}
+  f && /^[[:space:]]*-[[:space:]]+id:/ {exit}
+  f {print}
+' "$REG")"
+[ -n "$block" ] || { printf 'error: project not found: %s\nhelp: bin/project-git.sh list\n' "$ID" >&2; exit 1; }
+
+gitline="$(printf '%s\n' "$block" | grep -m1 'git:')"
+val() { printf '%s' "$gitline" | sed -nE "s/.*[ {,]?$1:[[:space:]]*([^,}]+).*/\1/p" | tr -d ' '; }
+
+host="$(val host)"; owner="$(val owner)"; repo="$(val repo)"; remote="$(val remote)"; br="$(val default_branch)"; auth="$(val auth)"
+if [ -n "$FIELD" ]; then
+  case "$FIELD" in
+    host) printf '%s\n' "$host" ;; owner) printf '%s\n' "$owner" ;; repo) printf '%s\n' "$repo" ;;
+    remote) printf '%s\n' "$remote" ;; default_branch) printf '%s\n' "$br" ;; auth) printf '%s\n' "$auth" ;;
+    *) printf 'error: unknown field %s\n' "$FIELD" >&2; exit 2 ;;
+  esac
+  exit 0
+fi
+printf 'project[1]{id,host,owner,repo,remote,default_branch,auth}:\n'
+printf '  "%s","%s","%s","%s","%s","%s","%s"\n' "$ID" "$host" "$owner" "$repo" "$remote" "$br" "$auth"

package/bin/public-guard.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# public-guard.sh — every PUBLIC, user-facing file must be free of operator
+# private content (tenant names, personal handles, domains, /home paths, secret
+# shapes). Supersedes agents-guard (root AGENTS.md is just one public file).
+#
+#   bin/public-guard.sh          # inspect the staged change (pre-commit)
+#   bin/public-guard.sh --all    # inspect every tracked public file
+#
+# Two lessons are baked in here (2026-09-12):
+#   1. The scan used to cover only root docs, so `apps/`, `bin/`, `scripts/` and
+#      `.agents/` shipped unchecked — and a personal domain, a personal bundle id
+#      and a live tunnel credential path sat in them for months.
+#   2. Append-only records are HISTORY. Rewriting one to hide a name would
+#      falsify the ledger, so they are exempt from the sweep by design and named
+#      here rather than quietly skipped.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The public tree scanned for private markers: shipped code, agent surfaces, docs.
+PUBLIC='^(apps/|bin/|scripts/|config/|midgard/|\.agents/|\.pi/|\.opencode/|AGENTS\.md|README\.md|TODO\.md|Structure\.md|CONTRIBUTING\.md|SECURITY\.md|NOTICE|docs/)'
+# Append-only records and archived reference material: history, never rewritten.
+APPEND_ONLY='(^CHANGELOG\.md$|^docs/append-only-log\.md$|^docs/plans/|^assets/reference/|^.agents/state/)'
+# Operator-private markers that must never appear in a public file.
+# Note: the public owner identity — "zerwiz" the repo holder, its public domains,
+# and the project's own repo forms — is intentionally NOT private. What stays
+# guarded: other personal names, real /home paths, tenants, and secret shapes.
+PATTERNS='(josef|lindbom|/home/zerwiz|(ghp|gho|ghs|ghr)_[A-Za-z0-9]{36}|sk-[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]+|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----)'
+# Legitimate exceptions, named explicitly rather than by widening the pattern:
+#   - the public owner identity (the repo's full URL, the short owner/repo form,
+#     and the owner's public homepage — the copyright holder on every licence);
+#   - AWS's documented dummy key, which is a fixture, not a credential.
+ALLOW='github\.com/zerwiz/|zerwiz/ymir|zerwiz\.org|akka://|AKIAIOSFODNN7EXAMPLE|AKIA[A-Z0-9]*EXAMPLE'
+
+leaks() {  # stdin → prints masked hits, returns 1 on any
+  grep -En "$PATTERNS" \
+    | grep -Ev "$ALLOW" \
+    | sed -E 's/(sk-|ghp_|AKIA|xox[a-z]*-)[A-Za-z0-9-]+/\1…/g; s#/home/zerwiz#/home/<user>#g' \
+    | head -5
+}
+
+scan_one() {  # $1 = path in the index; prints a finding, returns 1 when clean
+  local f="$1" out
+  # This file necessarily contains the patterns it looks for; scanning it would
+  # always fail. Exempt by name, and keep the patterns here honest.
+  case "$f" in bin/public-guard.sh|bin/secret-guard.sh) return 0 ;; esac
+  printf '%s\n' "$f" | grep -Eq "$PUBLIC" || return 0
+  printf '%s\n' "$f" | grep -Eq "$APPEND_ONLY" && return 0
+  out="$(git -C "$ROOT" show ":$f" 2>/dev/null | leaks)" || true
+  if [ -n "$out" ]; then
+    printf 'public-guard: %s\n%s\n' "$f" "$out" >&2
+    return 1
+  fi
+  return 0
+}
+
+hit=0
+if [ "${1:-}" = "--all" ]; then
+  while IFS= read -r f; do
+    scan_one "$f" || hit=1
+  done < <(git -C "$ROOT" ls-files)
+else
+  while IFS= read -r f; do
+    scan_one "$f" || hit=1
+  done < <(git -C "$ROOT" diff --cached --name-only --diff-filter=ACM)
+fi
+
+[ "$hit" = 0 ] || { printf 'public-guard: blocked — that is private; move it to $YMIR_HOME (Rule 04)\n' >&2; exit 1; }
+exit 0

package/bin/ratatoskr.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# ratatoskr.sh — Ymir's front door to the A2A engine (`a2abridge`).
+#
+#   bin/ratatoskr.sh status            # engine + directory health + served agents
+#   bin/ratatoskr.sh doctor            # a2abridge's full health-check
+#   bin/ratatoskr.sh directory start|stop|status   # the local discovery daemon
+#   bin/ratatoskr.sh service ...       # systemd-user / launchd service management
+#   bin/ratatoskr.sh cert ...          # ed25519 cert+key for cross-machine federation
+#   bin/ratatoskr.sh version
+#
+# The engine is the authority; this is a Ymir-shaped, fail-safe wrapper.
+set -u
+
+VERSION="1.0.0"
+A2AB="${A2ABRIDGE_BIN:-$HOME/.a2abridge/bin/a2abridge}"
+DIR_URL="${A2A_DIRECTORY:-http://127.0.0.1:7777}"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+ACTION="${1:-status}"; shift || true
+
+have() { command -v "$1" >/dev/null 2>&1; }
+[ -x "$A2AB" ] || A2AB="$(command -v a2abridge 2>/dev/null || true)"
+[ -n "$A2AB" ] && [ -x "$A2AB" ] || { printf 'error: a2abridge not found\nhelp: %s\n' "$A2AB" >&2; exit 1; }
+
+case "$ACTION" in
+  status)
+    printf 'ratatoskr[1]{engine,version}:\n  "%s","%s"\n' "$A2AB" "$("$A2AB" version 2>/dev/null | head -1)"
+    printf 'directory[1]{url,state,agents}:\n'
+    body="$(curl -s --max-time 4 "$DIR_URL/" 2>/dev/null)"
+    if [ -n "$body" ]; then
+      printf '  "%s","up","%s"\n' "$DIR_URL" "$(printf '%s' "$body" | python3 -c 'import json,sys
+try:
+    d=json.load(sys.stdin); print(",".join(a.get("name","") for a in d.get("served_agents",[])) or "none")
+except Exception: print("?")' 2>/dev/null)"
+    else
+      printf '  "%s","down","none"\n' "$DIR_URL"
+    fi ;;
+  doctor) exec "$A2AB" doctor ;;
+  directory)
+    sub="${1:-status}"
+    case "$sub" in
+      start) exec "$A2AB" directory & ;;
+      stop|status) exec "$A2AB" service "$sub" ;;
+      *) printf 'error: directory start|stop|status\n' >&2; exit 2 ;;
+    esac ;;
+  service|cert|worker|install|uninstall|update|completion) exec "$A2AB" "$ACTION" "$@" ;;
+  *) printf 'error: unknown action %s\nhelp: bin/ratatoskr.sh [status|doctor|directory|service|cert|version]\n' "$ACTION" >&2; exit 2 ;;
+esac

package/bin/realm-lib.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# realm-lib.sh — resolve the ACTIVE realm (tenant) without assuming the company's.
+#
+# A fresh Ymir is a distro, not the company that built it: nothing may default to
+# a company slug. Resolution order:
+#   1. data/realm.md (first line) — the operator's chosen realm, if set;
+#   2. the first shipped realm scaffold under svartalfaheim/ (examples/ excluded);
+#   3. "default".
+# Source-safe. Usage: ymir_active_realm <root> [result-var]
+set -u
+
+ymir_active_realm() {  # <root> [result-var]
+  local root="${1-}" result_var="${2-}" realm
+  if [ -z "$root" ]; then
+    root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+  fi
+  # The operator's root is $YMIR_HOME (default $HOME/Documents/Ymir) — never the
+  # checkout, so a realm can never be resolved inside the repo. The realm marker
+  # lives in the hoard; the realms themselves live beside it under svartalfaheim/.
+  root="${YMIR_HOME:-$HOME/Documents/Ymir}"
+  realm="$(head -n1 "$root/hodd/data/realm.md" 2>/dev/null | tr -d '[:space:]')"
+  if [ -z "$realm" ] && [ -d "$root/svartalfaheim" ]; then
+    realm="$(find "$root/svartalfaheim" -mindepth 1 -maxdepth 1 -type d \
+      ! -name 'examples' ! -name '.*' -printf '%f\n' 2>/dev/null | sort | head -n1)"
+  fi
+  realm="${realm:-default}"
+  if [ -n "$result_var" ]; then
+    printf -v "$result_var" '%s' "$realm"
+  else
+    printf '%s' "$realm"
+  fi
+}

package/bin/repo-scrub.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# repo-scrub.sh — purge private paths from ALL git history before going public.
+#
+#   bin/repo-scrub.sh --dry-run          # list what history still holds
+#   bin/repo-scrub.sh --yes              # back up, then rewrite history
+#   bin/repo-scrub.sh --yes <path> ...   # add extra paths to purge
+#
+# Rewrites every commit. A mirror backup is written to /tmp first. git-filter-repo
+# drops the `origin` remote, so re-add it after. ALWAYS rotate any exposed key
+# first — history rewriting does not un-leak a secret.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+DEFAULT_PATHS=(assets/reference/state "${YMIR_HOME:-$HOME/Documents/Ymir}/hodd/memory")   # the ledger moved into the hoard
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,11p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+
+MODE=dry; PATHS=()
+for a in "$@"; do
+  case "$a" in
+    --yes) MODE=yes ;;
+    --dry-run) MODE=dry ;;
+    -*) printf 'error: unknown flag %s\n' "$a" >&2; exit 2 ;;
+    *) PATHS+=("$a") ;;
+  esac
+done
+[ "${#PATHS[@]}" -gt 0 ] || PATHS=("${DEFAULT_PATHS[@]}")
+
+git -C "$ROOT" rev-parse --git-dir >/dev/null 2>&1 || { printf 'error: not a git repo: %s\n' "$ROOT" >&2; exit 1; }
+
+if [ "$MODE" = dry ]; then
+  printf 'repo-scrub[%d]{path,files_in_history}:\n' "${#PATHS[@]}"
+  for p in "${PATHS[@]}"; do
+    n="$(git -C "$ROOT" log --all --name-only --pretty=format: -- "$p" 2>/dev/null | grep -c . || true)"
+    printf '  "%s",%s\n' "$p" "${n:-0}"
+  done
+  printf 'help: bin/repo-scrub.sh --yes  (backs up to /tmp, then rewrites history)\n'
+  exit 0
+fi
+
+command -v git-filter-repo >/dev/null 2>&1 || { printf 'error: git-filter-repo not installed\nhelp: pipx install git-filter-repo  (or pacman -S git-filter-repo)\n' >&2; exit 1; }
+[ -z "$(git -C "$ROOT" status --porcelain)" ] || { printf 'error: working tree not clean — commit or stash first\n' >&2; exit 1; }
+
+# A private, unpredictable backup dir — never a predictable path in world-writable
+# /tmp (a symlink/race there could capture or clobber the pre-scrub mirror).
+backup_dir="$(mktemp -d "${TMPDIR:-/tmp}/ymir-scrub-XXXXXX")" || { printf 'error: could not create backup dir\n' >&2; exit 1; }
+chmod 700 "$backup_dir"
+backup="$backup_dir/ymir-backup.git"
+git clone --mirror "$ROOT" "$backup" >/dev/null 2>&1 || { printf 'error: backup clone failed\n' >&2; exit 1; }
+
+args=(); for p in "${PATHS[@]}"; do args+=(--path "$p"); done
+git -C "$ROOT" filter-repo --invert-paths "${args[@]}" --force || { printf 'error: filter-repo failed; backup at %s\n' "$backup" >&2; exit 1; }
+
+printf 'repo-scrub[1]{action,backup,remote}:\n  "purged","%s","origin removed — re-add it"\n' "$backup"
+printf 'next[4]{step,command}:\n'
+printf '  "re-add remote","git remote add origin <url>"\n'
+printf '  "force-push","git push --force --all && git push --force --tags"\n'
+printf '  "re-verify","bin/secret-guard.sh --all"\n'
+printf '  "rotate key","rotate sk-LJcx… and any other exposed credential NOW"\n'