@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/skills/galdr-ymirsystem/assets/installation.md

@@ -0,0 +1,571 @@
+# Installation & First Setup — stand the whole system up
+
+> **Purpose:** Everything Galdr must know to install, provision, and repair
+> Ymir for an operator who does not have it. The code is authoritative; this
+> page is the map.
+
+One command sets up the whole system for the user; it self-heals what it can and
+reports what it cannot. It **asks for consent first** (accept the plan, or pass
+`--yes` for non-interactive use), and it **validates at the end** that what it
+claims is actually running.
+
+```
+bin/ymir-install.sh               # the first setup (idempotent; asks to proceed)
+bin/ymir-install.sh --check       # report only, no writes, no prompt
+bin/ymir-install.sh --yes         # non-interactive (accept the plan)
+bin/ymir-install.sh --skip-engines --skip-services
+bin/ymir-install.sh --no-desktop  # don't open the desktop apps at the end
+bin/ymir-install.sh --status      # alias of --check
+```
+
+## The steps
+
+```
+install[20]{step,what,self-heals}:
+  "panes","the run shown in a herdr pane","bin/herdr-run.sh sits a pane beside the caller when inside herdr; inline otherwise — a pane that cannot be raised never loses the work"
+  "prereqs","git python3 bun docker|podman gh · mcp<2","bin/prereq-ensure.sh installs bun+uv+mcp in user space; engram is an honest optional SKIP"
+  "memory-well","the engram engine (Mimirsbrunn)","optional; reported with the exact next command, never a fake fix"
+  "tree","workspace/{work,personal}/<domains>, companies/, workspaces.yaml, projects.yaml, and the hoard OUTSIDE the repo (secrets/ · docs/ · identity/ · tenants/ at $YMIR_HOARD, else $YMIR_HOME)","creates if missing; hoard_root resolves through bin/hoard-lib.sh so no script can point the hoard inside the checkout (Rule 04), and an empty secrets/platform.env (0600) is seeded so bin/hodd.sh emit resolves"
+  "engines","treehouse · sandcastle · no-mistakes","installs treehouse + no-mistakes from their installers"
+  "hermes","the Nous Research agent runtime","installs via bin/hermes-ensure.sh when absent"
+  "sessrumnir","the Sessrúmnir desktop GUI (vendored pi-desktop at apps/sessrumnir)","bin/sessrumnir-ensure.sh installs deps + builds on first run (deps are never committed); launch via bin/sessrumnir.sh"
+  "backend","Þjazi — herdr (protocol 14+) or tmux","bin/herdr-ensure.sh detects/tests version, installs via the pinned installer or falls back to tmux"
+  "host","this machine — learnt on EVERY host","bin/omarchy-sense.sh learns the setup, bin/desktop-place.sh places the apps, the Omarchy post-update hook (when Omarchy), the wedge-alarm channel, and (on Omarchy) an OFFER of the suggested shell plugins — listed, never installed unbidden; seeds the private config/agents.yaml from its example"
+  "sandbox","utgard-runner:latest image","builds via bin/utgard.sh build on Docker or rootless Podman; distinguishes an unreachable engine from a build failure"
+  "memory","engram store + harness MCP registrations","raises the bridge; reports MCP coverage"
+  "smidja","smidja/smidja_data/smidja.db","bin/smidja-bootstrap.sh creates it from the tracer schema + a bootstrap session"
+  "visualizer","the Smíðja visualizer UI (Vue, served on :8437)","builds ./dist with bun when absent — the API serves the UI from dist, and without it the API answers but shows no interface"
+  "loaders","agents/skills into the harnesses","runs bin/valknut-load.sh"
+  "gates","the git delivery gates — secret-guard (pre-commit), branch-guard + changelog-guard (pre-push)","bin/secret-guard.sh --install and bin/changelog-guard.sh --install seat the versioned guards into .git/hooks, so the gate is live from the first commit of a fresh clone; idempotent"
+  "invite","the way in for anyone else — an invite code","bin/ymir-invite.sh ensure mints one only when nothing is live, so the step is idempotent; the code is printed at the end of the run and again in workspace/INSTALL.md"
+  "register","workspace/INSTALL.md","writes the record"
+  "services","gate API, SPA, Nornir, bridges, visualizer","raises via scripts/start.sh (which builds the visualizer UI when ./dist is absent)"
+  "desktop","Hlidskjalf + Smíðja desktop apps","bin/desktop-place.sh puts each on its OWN numbered desktop (preferring EMPTY ones); scripts/electron.sh start --both self-heals the Electron binary"
+  "validate","the running system","bin/ymir-validate.sh — live port/store/process checks"
+```
+
+**22** `step_*` functions are defined. A step is not a row: one step may emit
+several. `prereqs` also emits `memory-well`, `host` also emits `agents-config`,
+`smidja` also emits `visualizer`, and `spa` also emits `hlidskjalf`. `--check`
+skips the runtime-only steps (`services`, `desktop`, `validate`), which have
+nothing to report when the runtime is not raised, so a real run prints those
+three in addition. The exact set is whatever the host honestly has — never
+assume the count:
+
+```bash
+bash bin/ymir-install.sh --check | grep -cE '^  "'   # the honest count, on your host
+```
+
+## Configuration is never hardcoded (Rule 07)
+
+Every port, host, endpoint, path, and credential is resolved from env/config with
+**one documented default** — never a literal in shipped runtime. Ports read
+`HLIDSKJALF_PORT` / `HLIDSKJALF_API_PORT` / `SMIDJA_VIZ_API_PORT`, the SPA bind
+host reads `HLIDSKJALF_HOST`, and a deployment overrides them in its env file
+(Quadlet/Compose), never by patching the core. Law: `RULES/07-config.md`.
+
+## Container engine: Docker **or** rootless Podman
+
+The core never assumes an engine binary. `bin/ymir-platform.sh` resolves whichever
+this host can reach (`YMIR_CONTAINER_ENGINE` forces one) and exposes:
+
+- `ymir_container_engine` / `ymir_container_engine_name` — `docker` or `podman`.
+- `ymir_engine_is_podman` — true even when a `docker` binary fronts Podman (the
+  podman-docker shim).
+- `ymir_volume_suffix` — `:Z` whenever SELinux is enforcing (Docker and Podman
+  both need the relabel), else empty.
+- `ymir_rootless_podman` — rootless Podman needs `--userns=keep-id` so a bind
+  mount lands owned by the invoking user.
+
+`bin/utgard.sh`, `bin/einherjar-spawn.sh`, `bin/valhalla.sh`, `bin/ymir-validate.sh`,
+this installer, and `bin/prereq-ensure.sh` all use these; none names an engine
+directly. **Quadlet**-managed containers (Podman + systemd) surface as
+`systemd --user` units, which the process hall lists. A host-managed deployment
+layer (Quadlet, compose, bare) sits **over** this agnostic core — never inside it.
+
+## The visualizer UI
+
+The Smíðja visualizer **API** runs on `:8437` and serves its **UI** from
+`apps/visualizer/dist`. A fresh clone has no `dist`, so the API answers but shows
+"No ./dist build found" — an install gap. The installer (and `scripts/start.sh`)
+now build it when absent:
+
+```bash
+(cd .agents/skills/smidja-factory/apps/visualizer && bun run build)   # vue-tsc + vite
+```
+
+`bin/ymir-validate.sh` reports `visualizer` FAIL when `./dist` is missing, so the
+gap cannot silently return.
+
+## Desktop placement (Omarchy desktops, not monitors)
+
+On Omarchy the numbered **desktops** (1 2 3 4 5 …) are the "screens" an operator
+switches between. `bin/desktop-place.sh` gives each Ymir app its **own** desktop,
+**preferring an empty one**, so the apps open separated and reachable with
+`Super+<n>` rather than stacking on the active desktop.
+
+```
+bin/desktop-place.sh plan            # which desktop each app would take
+bin/desktop-place.sh apply           # write the rules + hyprctl reload
+bin/desktop-place.sh status          # what is installed
+```
+
+It writes `~/.config/hypr/ymir-desktops.lua` using Omarchy's own idiom —
+`o.window({ class = "^ymir-hlidskjalf$" }, { workspace = "2" })` — and adds one
+`require("hypr.ymir-desktops")` line to the user's `hyprland.lua`. It **never**
+touches `/usr/share/omarchy/`. Verify with `hyprctl configerrors` (must be empty).
+On a non-Omarchy host the step is a clean SKIP.
+
+## The Þjazi backend (herdr-first)
+
+Ymir spawns agents into terminal panes, so a terminal backend must exist. Ymir is
+**herdr-first**: `herdr` (Þjazi) is preferred, `tmux` is the accepted reference
+backend, and a missing backend is reported — never a silent fallback.
+
+```
+backend_priority[3]{rank,backend,note}:
+  "1","herdr","preferred; protocol 14+ for panes, 0.8.0+ for presentation spaces"
+  "2","tmux","verified reference backend; always acceptable"
+  "3","none","spawn is refused with a plain reason"
+```
+
+```
+bin/herdr-ensure.sh status            # what is present, and does it meet the floor
+bin/herdr-ensure.sh ensure --install  # install via the pinned, SHA-verified installer
+```
+
+`ensure` installs through `.agents/backend/fm-install-herdr.sh` (exact version +
+protocol check), and falls back to reporting `tmux` when herdr cannot be fetched.
+Selection order for the running system: `config/backend` → `BROKK_BACKEND` →
+`HERDR_ENV=1` → else tmux. Full reference: the `ymir` skill, `assets/thjazi.md`.
+
+## Suggested Omarchy plugins (offered, never forced)
+
+Omarchy's shell is plugin-shaped, and a few registry plugins are Ymir's own organs
+rendered on the desktop. `bin/omarchy-plugins.sh` suggests them and installs only
+what the Allfather accepts.
+
+```
+bin/omarchy-plugins.sh list        # what Ymir suggests, and why
+bin/omarchy-plugins.sh installed   # reads omarchy's own plugin list
+bin/omarchy-plugins.sh suggest     # the offer (no install)
+bin/omarchy-plugins.sh add <id>    # install one, with consent
+```
+
+The core three are Ymir's organs: **Herdr Watch** (Þjazi in the bar), **Hermes
+Deck** (our worker runtime), **Skill Manager** (the Galdr family across harnesses).
+Installation uses Omarchy's own verb — `omarchy plugin add <repo> --enable` — never
+a raw clone.
+
+**These run unsandboxed inside the shell.** The registry "validates listings, not
+plugin security", so nothing installs without an explicit yes (`--yes` for
+non-interactive callers; without it a non-interactive `add` refuses with exit 3).
+The installer only *offers*.
+
+## Consent
+A real install prints its plan and waits for `[y/N]`. Declining changes nothing
+(exit 3). `--check` never prompts. A non-interactive caller without `--yes` is
+refused rather than silently proceeding.
+
+The plan names every change, including the terminal backend (herdr/tmux), the
+host learning, and the desktop placement — so the operator accepts what is
+actually done, not a shorter list that drifted behind the code.
+
+## The operator's way in (auth) — `bin/ymir-setup-auth.sh`
+
+A fresh checkout seeds **no credential**, so the gate has no way in until the
+operator sets one. `step_auth` (interactive install prompts; `--yes`/non-tty
+defers) covers two doors:
+
+```bash
+bin/ymir-setup-auth.sh status            # which door (if any) is configured
+bin/ymir-setup-auth.sh set [--user U]    # a local password -> HLIDSKJALF_AUTH in .env.local
+bin/ymir-setup-auth.sh github            # GitHub sign-in -> GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRET
+```
+
+Both write `.env.local` (0600, gitignored); a secret is never printed or put in a
+child process's argv. The gate reads `HLIDSKJALF_AUTH` (`user:pass`) and the
+GitHub OAuth keys (`/api/auth/github`; sign-in names a login but never grants
+access on its own — an account/invite is still required). Restart the gate after
+setting a credential. One login is meant to cover every surface — see the shared
+session below.
+
+## Letting someone else in (invites)
+
+One operator owns the instance. The installer mints an **invite code**
+(`step_invite`) and prints it at the end of the run; share that code and someone
+else can create their own account at the gate login screen. Registration is
+closed unless a live code exists, so an instance is never accidentally open.
+
+```bash
+bin/ymir-invite.sh mint [--limit N]   # a new code (default ceiling 5 accounts)
+bin/ymir-invite.sh list               # every code, what is spent, who is in
+bin/ymir-invite.sh revoke <CODE>      # take one back, now
+bin/ymir-invite.sh where              # where the accounts live on this machine
+```
+
+Accounts are stored in `~/.config/ymir/accounts.json` (mode `0600`), machine
+state that never enters the repo, with argon2id hashes only. The operator's own
+credentials stay `HLIDSKJALF_AUTH` in `.env.local` — invites are for everyone
+*else*. Full surface: the galdr `hlidskjalf-ui.md` asset.
+
+## Validation
+
+After the runtime is up, `bin/ymir-validate.sh` observes the result: prerequisites,
+the Utgard image, the gate API (`:3889`), the SPA (`:3888`), Bifrost (`:4603`),
+Nornir cron, `smidja.db`, the desktop apps, the well (`:4602`), and the audit
+ledger. A FAIL means the install is not usable; a WARN means a documented-optional
+part is off. `--json` for machine consumption.
+
+## What the system adopts (engines)
+
+| Engine | Norse shell | Role |
+|---|---|---|
+| **treehouse** (`kunchenguid/treehouse`) | Yggdrasil | reusable worktree pool |
+| **sandcastle** (`mattpocock/sandcastle`) | Utgard | Docker/Podman/Vercel sandboxes |
+| **no-mistakes** (`kunchenguid/no-mistakes`) | Mjollnir · Glitnir | clean-PR validation gate |
+| **Hermes** (`NousResearch/hermes-agent`, MIT) | — (product name) | worker agent runtime: own brain, memory, skills, subagents, sandbox backends |
+| **pi-desktop** (`FaqFirebase/pi-desktop`, Apache-2.0) | **Sessrúmnir** (vendored at `apps/sessrumnir`) | desktop GUI for the Pi/OMP coding agents — the seat-hall, themed with the Ymir way-of palette |
+
+## Missing dependencies
+
+- **Fixable in user space** (no sudo): `bun`, `uv`, `mcp<2>` — via
+  `bin/prereq-ensure.sh`. `treehouse`, `no-mistakes`, **Hermes**, and the **Þjazi
+  backend** (herdr, or tmux) are installed by their own ensure/steps.
+- **Needs a system package** (reported with the exact command): `git`,
+  `python3`, `docker`, `gh`.
+- **Optional, honest SKIP:** the `engram` memory engine. The published PyPI
+  `engram` is **not** Ymir's engine (it is an unrelated scientific package), so
+  the installer reports the well as off rather than installing the wrong thing.
+- **Offline:** engine/Hermes/herdr installers fail gracefully and are reported;
+  re-run when the network returns.
+
+## Hermes specifically (`bin/hermes-ensure.sh`)
+
+```
+hermes-ensure.sh status           # hermes[1]{installed,version,path,method}
+hermes-ensure.sh ensure --install # install if absent, then report
+hermes-ensure.sh install          # curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+```
+
+A user who lacks Hermes gets it at setup (`hermes` step). Config/identity
+(`hermes setup`, auth) stays the user's own; Ymir guarantees only the runtime.
+
+## Sessrúmnir specifically (`bin/sessrumnir-ensure.sh`, `bin/sessrumnir.sh`)
+
+```
+sessrumnir-ensure.sh status           # sessrumnir[1]{dir,deps,built,electron}
+sessrumnir-ensure.sh ensure --install # install deps + build when absent, then report
+sessrumnir-ensure.sh install          # npm install + electron-binary heal + npm run build
+sessrumnir.sh start [path]            # launch the seat-hall (deps installed on first run)
+sessrumnir.sh status | stop
+```
+
+Deps are never committed; the ensure step installs them on first run, exactly as
+`scripts/electron.sh` does for the other desktop apps. The external engine keeps
+its product name `pi-desktop`; the GUI the user sees is Sessrúmnir, themed with
+Ymir's deep-navy palette. The Omarchy launcher entry is rendered from
+`apps/sessrumnir/resources/ymir-sessrumnir.desktop.in` by `bin/desktop-place.sh`
+(placement + `SUPER+B`).
+
+## Neutral tenant defaults — a fresh Ymir is a distro, not the company
+
+A fresh install ships **no company of its own**. `bin/ymir-install.sh` seeds one
+`personal` workspace and an **empty** projects registry (a commented example
+only); it never writes a company slug, a company remote, or a `work (company: …)`
+line. The runtime resolves the active realm **neutrally** through
+`bin/realm-lib.sh` (`ymir_active_realm`): `data/realm.md` (first line) → the first
+non-example tenant under `svartalfaheim/` → `default`. **No script may fall back
+to a company slug.** The reference tenant the distro was built for lives at
+`svartalfaheim/examples/wayof/` — an example to copy, never the default. A `work`
+workspace must name its own company: `workspace-provision.sh` requires
+`--company <slug>`.
+
+## Per-workspace provisioning
+
+```
+bin/workspace-provision.sh <name> --kind work|personal [--domains a,b,c] [--company <slug>]
+```
+
+Creates `workspace/<name>/<domains>/`, registers it in `workspaces.yaml`, and
+for a **work** workspace attaches it to the tenant container
+`svartalfaheim/<company>/`. `--company` is required for a work workspace — the
+company is the operator's to name; Ymir ships no default.
+
+## Verify
+
+```
+bin/ymir-install.sh --check          # all steps OK/WARN
+bin/ymir-validate.sh                 # the running system actually works
+bin/herdr-ensure.sh status           # the Þjazi backend and its protocol floor
+bin/omarchy-sense.sh status          # what Ymir has learnt about this host
+bin/saga-session-start.sh            # the session digest
+bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh
+```
+
+On an **Omarchy** host the installer also learns the machine
+(`bin/omarchy-sense.sh`) and installs a `post-update` hook so Ymir re-learns it
+every time Omarchy updates. On a non-Omarchy host that step is a clean SKIP.
+
+Rule: the installer is **idempotent** — running it again changes nothing but
+fills gaps. It never overwrites real user data.
+
+## Node dependencies in a fresh clone — the postinstall trap
+
+A clone never carries `node_modules`. Two components need them, and each has its
+own package manager:
+
+```bash
+# Hlidskjalf (npm + package-lock.json) — what scripts/start.sh runs
+cd apps/hlidskjalf && npm install --no-audit --no-fund
+npm run typecheck && npm run build          # dist/ is what the SPA serves
+
+# Smiðja visualizer (bun + bun.lock)
+cd .agents/skills/smidja-factory/apps/visualizer && bun install && bun run build
+```
+
+The visualizer's `dist/` is not optional: its API serves the UI from `./dist`,
+and without a build it answers the API but prints *"No ./dist build found"*.
+
+### The trap: install scripts can be skipped silently
+
+Newer npm versions gate package install scripts (`allowScripts`). When a script
+is not approved the install still reports success, so you get a **half-broken
+tree that passes its own build**:
+
+```
+2 packages have install scripts not yet covered by allowScripts:
+  electron@33.4.11 (postinstall: node install.js)
+  esbuild@0.25.12  (postinstall: node install.js)
+```
+
+- `esbuild` survives it (its binary arrives through the platform-specific
+  package), so `npm run build` succeeds and everything looks healthy.
+- **`electron` does not.** Its postinstall downloads the ~100 MB runtime; without
+  it `node_modules/electron/dist/` is left partial and `path.txt` is never
+  written, so the desktop shell cannot start — while the web app builds perfectly.
+
+Detect it:
+
+```bash
+npm install-scripts ls                                        # what is unapproved
+node_modules/electron/dist/electron --version                  # fails if skipped
+cat node_modules/electron/path.txt                             # absent if skipped
+```
+
+Fix it:
+
+```bash
+npm install-scripts approve electron esbuild
+npm rebuild electron
+```
+
+If the rebuild still exits **silently** and `dist/` stays partial, the download
+is cached but was not re-extracted — complete it by hand, which is all the
+package's own installer does:
+
+```bash
+ZIP=$(ls ~/.cache/electron/*/electron-v*-linux-x64.zip | head -1)
+rm -rf node_modules/electron/dist && mkdir -p node_modules/electron/dist
+unzip -q -o "$ZIP" -d node_modules/electron/dist
+printf 'electron' > node_modules/electron/path.txt     # the linux binary name
+chmod +x node_modules/electron/dist/electron
+```
+
+**Verify the install as a whole**, not just that a build passed: the electron and
+esbuild binaries report versions, both `dist/` directories exist, and
+`bin/ymir-install.sh --check` reports the visualizer and smidja green.
+
+## Platform support — Linux, macOS, Windows
+
+Ymir runs on Linux (native), macOS (native) and Windows (through **WSL2**, with
+MSYS/Git Bash as best-effort). The runtime is bash, so Windows means a POSIX
+shell: WSL2 is the supported path, and it is also the only one where the Linux
+GPU and service paths behave normally.
+
+### One place knows the difference
+
+`bin/ymir-platform.sh` is the portability layer. It defines functions only and is
+sourced, never executed:
+
+```bash
+. "$ROOT/bin/ymir-platform.sh"     # scripts already do this via the shim block
+```
+
+| Need | Function | Why it exists |
+|---|---|---|
+| Which OS | `ymir_os` → `linux` \| `macos` \| `wsl` \| `msys` | branching, once |
+| CPU count | `ymir_nproc` | `nproc` is GNU; macOS uses `sysctl -n hw.ncpu` |
+| Resolve a path | `ymir_readlink_f` | BSD `readlink` has no `-f`; mirrors GNU semantics including the "parent must exist" rule |
+| File facts | `ymir_stat_mtime`, `ymir_stat_size`, `ymir_stat_id`, `ymir_stat_birth`, `ymir_stat_mode` | GNU `stat -c` vs BSD `stat -f`, and birth time exists on both but differently |
+| Timing | `ymir_epoch_ns` | BSD `date` has no `%N` |
+| A pid's command line | `ymir_pid_cmdline`, `ymir_pid_matches` | `/proc` is Linux-only; falls back to `ps -o command=` |
+| Signal a process by pattern | `ymir_kill_matching` | `pkill` is absent on some MSYS/WSL images; falls back to `ps` + `kill` |
+| Detach a process | `ymir_detach` | `setsid` is absent on macOS; falls back to `nohup` |
+| Exclusive lock | `ymir_lock` | `flock` is Linux; falls back to an atomic `mkdir` lock |
+| Services | `ymir_service_backend`, `ymir_service_active` | `systemd` on Linux, `launchd` on macOS, neither elsewhere |
+| GPUs | `ymir_gpu_name`, `ymir_gpu_mem_used` | never assume NVIDIA: `nvidia-smi`, then `rocm-smi`, then Apple's unified memory |
+| Paths | `ymir_tmp`, `ymir_expand_tilde` | `TMPDIR`/`TEMP` vary; a leading `~` must be expanded explicitly |
+
+Scripts that need any of these carry a short shim block near the top that finds
+and sources the library, then marks it loaded so a second source is a no-op:
+
+```bash
+if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
+  _ymir_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+  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
+```
+
+### Rules for new code
+
+1. **Never call `readlink -f`, `stat -c`, `nproc`, `setsid`, `flock`, `date +%N`
+   or read `/proc` directly.** Use the shim.
+2. **Never assume NVIDIA.** Ask the shim; a machine may be AMD, Intel or Apple.
+3. **Never hardcode a home directory.** Use `$HOME`, or `ymir_expand_tilde` for a
+   user-supplied path, and keep machine-specific values in generated config
+   rather than in the tree.
+4. **Never assume a desktop.** `.desktop` files, `systemctl` and window managers
+   are Linux-shaped; a launcher must be generated for the host, not shipped as
+   one file for all.
+5. **Test the fallback, not just the happy path.** Most of these functions exist
+   because the Linux path already worked; the risk is the other branch.
+
+Standalone tools that ship outside a Ymir checkout (for example
+`.agents/skills/galdr-ymirsystem/scripts/bench-one.sh`) carry their own small portable
+helpers instead of sourcing the library, so they run anywhere on their own.
+
+### Machine config is rendered, never shipped
+
+Two files must contain **absolute** paths (the engram MCP server's binary and its
+database), so a tracked copy would hand every operator the previous one's home —
+exactly what `/home/<user>/...` did in this tree. They follow the `.env.example`
+pattern instead:
+
+| Shipped (tracked) | Rendered (gitignored) |
+|---|---|
+| `opencode.json.example` | `opencode.json` |
+| `.pi/mcp.json.example` | `.pi/mcp.json` |
+
+Placeholders `__YMIR_HOME__` and `__YMIR_ROOT__` are substituted with `$HOME` and
+the checkout root by `bin/valknut-load.sh` (its `render_config`, run for both
+`--pi` and `--opencode`). It is idempotent: identical content is left alone and
+reported as `unchanged`.
+
+Rule: **if a config must hold an absolute path, it is generated from an
+`.example`, not committed.** The same applies to launchers — a `.desktop` file
+is one OS's answer and must be produced for the host, not shipped for all.
+
+## Omarchy-first: the core is portable, the desktop is Omarchy's
+
+Ymir is an **Omarchy-first** system. That is a design statement, not a
+restriction — it says which desktop integration is first-class, not which
+machines may run the runtime.
+
+**Two layers, deliberately separate:**
+
+| Layer | Runs on | What it owns |
+|---|---|---|
+| **Portable core** | Linux, macOS, Windows (WSL2; MSYS best-effort) | the runtime — session digest, lock, watch, cron, skills — the installer's user-space prerequisites, the capability shim, generated machine config |
+| **Omarchy layer** | Omarchy only | learning the host (`omarchy-sense`), placing each app on its own numbered Hyprland desktop (`desktop-place`), the launcher entries (`.desktop`), the suggested shell plugins, the post-update hook |
+
+The core never grows a Hyprland branch, and the Omarchy layer is never stretched
+into pretending it is portable. An Omarchy-specific step is gated on the host and
+reports a clean skip anywhere else:
+
+```bash
+[ -d /usr/share/omarchy ] && ... || add host OK "... (not an Omarchy host)"
+```
+
+That is why `step_host` and `step_desktop` are the only steps that mention
+Omarchy: everywhere else, the same code path runs on any host.
+
+### What the Omarchy layer installs
+
+```bash
+bin/omarchy-sense.sh observe          # learn packages, configs, Omarchy version
+bin/omarchy-plugins.sh add            # the suggested shell plugins (never forced)
+bin/omarchy-hook-install.sh install   # re-learn after every `omarchy update`
+bin/desktop-place.sh apply            # Hyprland desktops + launcher entries
+```
+
+`desktop-place.sh apply` does both halves of the desktop integration: it writes
+the Hyprland window rules that give each Ymir app its own numbered desktop, and
+it renders the launcher templates into `~/.local/share/applications/`. The
+templates (`apps/hlidskjalf/electron/*.desktop.in`) carry `__YMIR_ROOT__` rather
+than an absolute path, because where the checkout lives is a fact about the
+machine, not about Ymir.
+
+**Rule:** `RULES/05-platforms.md` — a core change updates every
+platform layer in the same change.
+
+**Rule for a new desktop feature:** if it is Omarchy-specific, it belongs in the
+Omarchy layer and is gated; if it is core, it must work on every platform. Do not
+blur the two — a branch of Hyprland logic inside a core script is how a portable
+runtime stops being portable.
+
+### A move must carry the memory, not just the code
+
+Rule 06 makes this explicit, because a home swap here dropped
+`docs/append-only-log.md`, `docs/masterplan.md`, `docs/plans/` and the private
+business set: the backup carried `state`, `.env.local`, `data`, the realm and
+`workspace` — but not `docs/` or `assets/`. The code arrived; the memory did not.
+
+Before and after any migration, re-clone or swap, check the sets **by name**:
+
+```bash
+for f in CHANGELOG.md docs/append-only-log.md workspace/memory/runes_audit.md; do
+  [ -e "$f" ] || echo "MISSING append-only artifact: $f"
+done
+ls "$YMIR_HOARD/docs" "$YMIR_HOARD/identity" 2>/dev/null    # the private set
+```
+
+A backup is only as good as its file list. If a directory is not named in the
+backup, it is not carried.
+
+### The memory engine is provisioned, not hinted (2026-09-12)
+
+`bin/ymir-install.sh` used to *check* for the well engine and, failing, print
+`SKIP "optional — install engine then run bin/mimir-bridge.sh"`. A SKIP never
+blocks, so the well was silently down on every install — and the hint named the
+wrong package, so following it made things worse.
+
+Now the installer provisions it: `bin/prereq-ensure.sh engram` installs
+**`engdbram`** (the distribution; the *module* is `engram`) into an interpreter
+that can run it (>=3.11; uv supplies 3.12 when the distro's Python is unsuitable),
+and records that interpreter in `~/.config/ymir/engram-python`. `bin/mimir-bridge.sh`
+reads the same file, so the installer and the bridge always agree.
+
+```bash
+bin/prereq-ensure.sh engram        # install and record the interpreter
+bin/mimir-bridge.sh --start        # the :4602 face over the engine
+curl -s 127.0.0.1:4602/health      # {"status": "up", "store": ".agents/memory/kaia.engram"}
+```
+
+**Never `pip install engram`.** PyPI's `engram` is an unrelated rendering library
+(mitsuba/drjit/torch) whose install pulls gigabytes of CUDA wheels and still
+leaves Ymir with no engine. The prerequisite target exists so nobody has to know
+that: `bin/prereq-ensure.sh engram`.
+
+### The rename sweep broke governed paths, not just prose (2026-09-12)
+
+The `smidja` → `smidja-factory` rename left `smidja-factory-factory` behind in
+**seven** places — `scripts/start.sh` (`VIZ_DIR`), `bin/ymir-validate.sh`,
+`bin/ymir-install.sh` (twice: the dist probe and the build dir),
+`bin/saga-session-start.sh` (the governed-path TOON row), `AGENTS.md` (the
+`governed[]` table, twice) and the guard's own `asset_for` pattern.
+
+The damage was not cosmetic: a governed path that does not exist makes the
+pretool guard stop matching, so the smidja rule protected nothing while every
+check still passed. A `governed` check now exists in
+`compliance-check.sh` for exactly this class (see `runtime-compliance.md` §G13);
+it reports `all 25 governed paths exist`.
+
+`bin/ymir-install.sh` and `bin/ymir-validate.sh` are the two files of this asset
+that the sweep corrected. The visualizer path is
+`.agents/skills/smidja-factory/apps/visualizer` — **not** a doubled
+`smidja-factory-factory`, and not the abandoned `.agents/skills/smidja/` tree
+(stale build output, moved aside).

package/.agents/skills/galdr-ymirsystem/assets/local-models/HOST-DATA.example.md

@@ -0,0 +1,72 @@
+# HOST-DATA.example — the shape of a host record (Vog)
+
+Vog weighs a local model on a machine; this is the shape of the record it keeps.
+
+A host record is **private to the machine it describes** and lives in that
+machine's Hoard: `hodd/docs/vog/`. This file is the tracked `*.example`
+shape (Rule 04) so a new operator knows what belongs there without inheriting
+anyone's data.
+
+Copy this skeleton into the Hoard and fill it in per host.
+
+---
+
+## `<hostname>` — `<device summary>`
+
+| | |
+|---|---|
+| Serving GPU | `<vendor model, VRAM, link>` |
+| Other GPU(s) | `<device, role>` |
+| System RAM | `<size>` |
+| Driver / runtime | `<versions>` |
+| Model directory | `<path>` where the weights actually live |
+
+## Serving stack on this host
+
+| Part | Path / endpoint |
+|---|---|
+| Registry (single source of truth) | `<path>` |
+| Launcher / engine | `<path>` |
+| Router / gateway | `<path>` `:<port>` |
+| Secondary endpoint (other device/backend) | `<path>` `:<port>` |
+| Autostart | `<systemd unit or equivalent>` |
+| Client wiring | `<pi / editor / other>` |
+
+## Models on this host, verified
+
+One row per model. `ctx` is the **verified** window — the largest value that
+survived a real request — never the file's maximum.
+
+| Model | quant | weights | KV bytes/token | ctx | prefill t/s | decode t/s | peak memory | alias |
+|---|---|---|---|---|---|---|---|---|
+| `<name>` | `<quant>` | `<GiB>` | `<KiB>` | `<ctx>` | `<n>` | `<n>` | `<MiB>` | `<alias>` |
+
+## Configurations tried and rejected
+
+The most useful part of the record. Keep what failed and why.
+
+| Config | Result | Cause |
+|---|---|---|
+| `<ctx / kv / batch / device>` | `<load failure, crash on request, etc.>` | `<measured cause>` |
+
+## Measured rules this host produced
+
+Short, falsifiable statements, each traceable to a table above. For example:
+"a smaller context ceiling changes memory and not speed — measured identical
+decode at two ceilings" or "KV size, not weight size, decides how much context
+fits on this device".
+
+## Traps specific to this host
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `<observable>` | `<mechanism>` | `<what to do>` |
+
+## Reference points for a new model on this host
+
+The budget formula with this box's numbers filled in, so the next model can be
+sized before it is downloaded:
+
+```
+usable_context = (free_memory - weights - compute_buffer) / kv_bytes_per_token
+```