@zerwiz/ymir 0.1.5 → 0.1.8

package/.agents/skills/galdr-ymirsystem/assets/hlidskjalf-ui.md

@@ -28,6 +28,9 @@ Quick rules:
 ## Location & stack
 
 - App: `apps/hlidskjalf` — **React 19 + Vite + TypeScript**, state via **Zustand**.
+- The app lives in **its own repo** (`zerwiz/hlidskjalf`, registered in the home
+  registry) — the monorepo never tracks it; `bin/ymir-install.sh`'s `apps` step
+  clones it into `apps/hlidskjalf` at install, or fast-forwards a present clone.
 - Gate API: `apps/hlidskjalf/server/index.ts` — **Bun + `bun:sqlite`**, read-only,
   bound to the runtime and the smithy trace; Vite proxies `/api` → `:3889`.
 - Raise everything with the scripts (do not hand-start each process):
@@ -95,6 +98,13 @@ Rules that hold it honest:
 
 - `.shell` grid: `236px rail | 1fr`; rows `56px topbar · stage · stream`
   (the stream height is draggable, persisted in `streamHeight`).
+- The **Fleet graph** (`gates/Fleet.tsx`) lays the roster on a 100×100 canvas:
+  Brokk as the hub, everyone else in a square-ish grid fan (`cols =
+  ceil(sqrt(n))`, pitch ≥ one ring + label) so 20 agents never collide; rings
+  carry the house glyph from `DOMAINS[agent.domain]` with a `ymirlabs`
+  fallback, and the live cards come from `bin/hlidskjalf-agents.sh` — which
+  reads each figure's `domain:` frontmatter (never a hardcoded `ymirlabs` for
+  everyone).
 - `.rail` (brand · gates · tenants · status), `.topbar` (realm chip · search ·
   accent · density · trace index · account), `main.stage` (the gate), `.stream`
   (Ratatoskr + Runes, pausable).
@@ -156,6 +166,18 @@ router `:8080`, Bifrost `:4603`), never only the first — a dead engine falls
 through to a live one. Recall reads `.agents/memory/well/episodes.jsonl`
 directly, so restoring that file revives the chat's memory without a restart.
 
+### The EmberBackground hearth (the shared fire)
+
+The animated glow behind the shell, the login, and Sessrúmnir's chat comes from
+**one** hearth, not four copies: `midgard/design-system/ember.js` (`startEmbers`),
+with Sessrúmnir's `ember-background.tsx` as its React port. Both draw the same
+embers + haze, respect reduced-motion, and — since the Sep 17 mend — re-seed
+via **ResizeObserver on the container**, not just `window.resize`: a split pane
+or toggled sidebar changes the chat column's size without a window resize, and a
+canvas that sized itself once at a stale dimension never shows the fire. The
+shared module watches the host; the port watches its parent; re-seeding fires
+only when the measured size actually changed (never per-frame).
+
 ### The gate API reads cheaply (added 2026-09-16)
 
 The gate reads append-only ledgers (Runes, the well's `episodes.jsonl`, masterplan
@@ -201,7 +223,10 @@ API on the same port (`scripts/start.sh` raises it). Details: `assets/smidja.md`
 ## Agents, skills & mythological naming
 
 - The Forge gate (`src/gates/Forge.tsx`) creates/edits **Eindri** and **skills**,
-  and reads/edits the smithy's prompts.
+  and reads/edits the smithy's prompts. The skill list shows each skill's own
+  text: the name + aett rune on the head row, and the description line
+  underneath (`forge-item-desc`, dimmed until hover) — the description comes
+  from the live `/api/skills` index, truncated to 240 chars by the gate API.
 - Naming law: `src/data/mythology.ts` maps a craft/capability → the Norse figure
   whose myth matches it (smith→Sindri, skald→Bragi, sage→Huginn, judge→Tyr,
   forger→Brokk …). Skills take an **aett** prefix.
@@ -253,6 +278,17 @@ npm run build            # must be green
 - When the shell, tokens, gates, or the gate API change, update this asset and
   `docs/design.md` together.
 
+### The agent path the Fleet gate reads (2026-09-17)
+
+`server/index.ts` decides whether a figure is *registered* by testing for its
+profile in the OpenCode agent directory. That directory is **`.opencode/agents/`
+— PLURAL**, which is what OpenCode actually loads. The singular
+`.opencode/agent/` was never read by the harness, so twenty correct symlinks sat
+in a directory no loader opened and the gate reported figures unregistered while
+the tree held them all. Any code that resolves an agent profile must use the
+plural path; the loader (`bin/valknut-load.sh`) migrates a legacy singular dir
+forward and binds the plural one.
+
 ## Domains, not houses (Rule 01/03)
 
 The eight Labs are **domains (Greinar)** — the knowledge axes — not houses. A
@@ -292,6 +328,13 @@ the password comes from `HLIDSKJALF_AUTH` in `.env.local`, never inline. A
 hardcoded name here is both a leak into the public tree and wrong for any other
 operator — `bin/public-guard.sh` exists to catch exactly that class of mistake.
 
+**The gate must actually receive it.** `scripts/start.sh` loads `.env.local`
+(mode `0600`, gitignored) into the environment before raising the gate, because
+the bun process reads `process.env.HLIDSKJALF_AUTH` and nothing else was loading
+it — so a credential set by `bin/ymir-setup-auth.sh` never took effect, and an
+empty `GATE_AUTH` makes the gate treat every request as authenticated. After
+setting a credential, restart the gate: `scripts/stop.sh; scripts/start.sh`.
+
 ### One login, and it is the one with the lore (2026-09-12)
 
 There used to be **two** ways in, and the second was a mistake:

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

@@ -5,12 +5,13 @@
 > 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
+reports what it cannot. It **asks for consent first** — with a plan it computes on
+this host, not a recited paragraph — 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 --plan        # the plan, probed — changes nothing (--json too)
 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
@@ -18,25 +19,267 @@ bin/ymir-install.sh --no-desktop  # don't open the desktop apps at the end
 bin/ymir-install.sh --status      # alias of --check
 ```
 
+## The plan comes first — `bin/ymir-plan.sh`
+
+The consent a real install asks for is a **computed plan**, one row per step, each
+carrying its state and the reason for it. A hardcoded paragraph cannot know the
+host: the old one named an Omarchy version on a Mac, promised a workspace tree that
+already stood, and never mentioned that no application had been installed at all.
+
+```
+bin/ymir-plan.sh              # the plan (TOON)
+bin/ymir-plan.sh --json       # the same, for automation
+bin/ymir-plan.sh --phase 5    # one phase
+bin/ymir-plan.sh --blocked    # only what cannot proceed, and why
+```
+
+```
+plan_states[5]{state,means}:
+  "DO","a change will be made"
+  "SKIP","already satisfied — nothing to do"
+  "INFO","a fact about this host, discovered; no change implied"
+  "BLOCKED","cannot run — the reason names what is missing"
+  "CONSENT","needs the operator's word (a credential, an invite, the shells)"
+```
+
+```
+plan_phases[9]{n,name,gate}:
+  "0","resolve","this host, the container engine, the code root, and the home"
+  "1","code","the tree is intact — and holds nothing of the operator's"
+  "2","home","the operator's world, outside the tree"
+  "3","runtimes","git/python3 · bun/uv/mcp<2> · pi · hermes · the terminal backend"
+  "4","engines","treehouse · no-mistakes · sandcastle · the Utgard image"
+  "5","apps","hlidskjalf · odrerir · sessrumnir · smidja — web build required, shell gated"
+  "6","wire","the way in (auth · invite) and the launcher entries"
+  "7","raise","every port listening, then the desktop apps"
+  "8","verify","what stands, honestly"
+```
+
+`ymir-install.sh` prints the plan at the consent prompt; `--plan`/`--dry-run` prints
+it and exits without writing. The plan is recomputed on every run, so it cannot
+drift behind the code the way a paragraph did. `bin/ymir-plan.sh` is the ward for
+the law below: its phase-1 `purity` row names any of the operator's things found in
+the code tree.
+
+## Where things live — the package is code, the home is the operator's
+
+**Law (Rule 04):** the package carries the **core systems** — everything needed to
+run the programs. Everything the **operator** owns goes to `$YMIR_HOME`: their
+info, their records, their documents, their settings, their state, their
+credentials. A packaged install (npm) treats its tree as read-only; the next
+upgrade replaces it, so anything of theirs kept there is kept at its peril.
+
+```
+roots[5]{root,resolves_from,holds}:
+  "ymir_home_root","$YMIR_HOME → the choice recorded at installation → one documented default","everything private the operator owns"
+  "hoard_root","$YMIR_HOARD → <home>/hodd","docs · secrets · identity · tenants · memory"
+  "hoard_data_dir","$YMIR_DATA_DIR → <hoard>/data","this machine's records: operator, fleet, machines, the host profile"
+  "hoard_state_dir","$YMIR_STATE_DIR → <home>/state","runtime state: pids, logs, locks, caches"
+  "hoard_settings_dir","$YMIR_SETTINGS_DIR → <home>/config","settings: agents.yaml, cron.yaml, tailscale-sync, the wedge channel"
+```
+
+Plus `hoard_local_env` → `$YMIR_HOME/.env.local`: the operator's **credentials**
+(`HLIDSKJALF_AUTH`, OAuth keys, tokens), never in the tree.
+
+**The home is chosen, not assumed.** A real interactive install asks once
+(`step_home`), records the answer as machine state under `~/.config/ymir/home`
+(the same place `engram-python` and `accounts.json` live), and every later script
+resolves it through `bin/hoard-lib.sh`. `--check` never writes; `--yes` takes what
+is recorded, else the documented default.
+
+```bash
+bin/hoard-lib.sh                     # the lib (source-safe; functions only)
+ymir_home_root   HOME                # → the home
+hoard_settings_dir SETTINGS          # → <home>/config
+hoard_local_env  ENVFILE             # → <home>/.env.local
+```
+
+**Rule for new code:** never write `$ROOT/data`, `$ROOT/state`, `$ROOT/config`,
+`$ROOT/.env.local` or `$ROOT/workspace`. Resolve the root through the lib. A script
+that points an operator's thing into the tree is the bug the `purity` row exists to
+catch.
+
+### Carrying an existing tree home — migration 0005
+
+Every *writer* resolves the home now, but an installation made before this change
+still holds the operator's things in the tree. `.agents/migrations/0005-roots-out-of-tree.sh`
+carries them:
+
+```
+what moves           from                    to
+------------------   ---------------------   ----------------------------
+this machine's       data/                   <hoard>/data
+  records
+runtime state        state/                  <home>/state
+  (pids · logs ·     (including the          (running services keep their open
+   locks · the        applied-migrations      fds across the move — `mv` keeps
+   applied-marker)    marker)                 the inode)
+credentials          the local env file      $YMIR_HOME/.env.local (0600)
+settings             .agents/config/*        <home>/config
+                     that git does NOT track
+```
+
+One name, two files — the migration decides by evidence, never by assumption:
+
+```
+collision[3]{case,what_happens,nothing_lost}:
+  "identical content","the tree's copy is removed","the content is provably at home already"
+  "different content","the home's keeps the name; the tree's is carried beside it as <name>.stale-<UTC>","both are real, so both are kept — never merged, never discarded"
+  "not a plain file","left in place and reported","a directory is not silently swallowed"
+```
+
+Templates and defaults never move: `*.example` (and `*.example.*`), `.gitkeep`, and
+any settings file **git tracks** — that is the distro's shipped default, not the
+operator's. The plan's `purity` row applies the same rule, asking git about the
+real path (the tree's `config` is a symlink into `.agents/config`, and git tracks
+what the index holds, not the link). Idempotent: a second run changes nothing.
+
+```bash
+bin/ymir-migrate.sh status            # pending / applied
+bin/ymir-migrate.sh apply --dry-run   # name the migration, touch nothing
+bin/ymir-migrate.sh apply             # carry it
+```
+
+Stop the runtime first if you want no stale pid files; nothing is lost either way.
+
+## Operating it afterwards — the doors, the cloth, and the shapes
+
+### The doors (the CLI), named for the figure who does the work
+
+`npm install -g @zerwiz/ymir` puts **two** commands on PATH: `ymir` (the front
+door) and `ymir-install` (the bare installer). Everything else the operator
+needs is a door on `ymir` — never a script path inside `node_modules`.
+
+```
+doors[14]{verb,door,what}:
+  "ymir","first setup (a bare call installs)","the plan, then consent, then the work"
+  "ymir install [...]","bin/ymir-install.sh","the same, said out loud"
+  "ymir plan","bin/ymir-plan.sh","what an install would do here — writes nothing"
+  "ymir raise / lower","scripts/start.sh · stop.sh","lift the hall, or lay it down"
+  "ymir eir","bin/eir-doctor.sh","what stands, and mend what does not (the healer)"
+  "ymir groa","bin/groa-update.sh","take the latest, then mend this home forward"
+  "ymir groa migrate","bin/ymir-migrate.sh","heal this home's structure"
+  "ymir heimdall","bin/ymir-setup-auth.sh","the way in — status · set · github (the guardian)"
+  "ymir invite","bin/ymir-invite.sh","let someone else in — mint · list · revoke"
+  "ymir smidja","bin/smidja-board.sh","the smithy's board on :8437 — build · start · stop · status"
+  "ymir hlidskjalf","scripts/electron.sh start --view hlidskjalf","the high seat's window"
+  "ymir sessrumnir","scripts/electron.sh start --view sessrumnir","the seat-hall's window"
+  "ymir mimir","bin/mimir.sh","the memory well"
+  "ymir sense","bin/host-sense.sh","what THIS machine is"
+```
+
+A name the law has not given a home is still answered, once, with the name that
+has it: `ymir doctor` → *the door is named `ymir eir` now*. Colour appears only
+where a human watches.
+
+### The cloth — `bin/ymir-style.sh`
+
+Ymir had correct output and no design. The cloth is cut from the same stone as
+the halls (`midgard/design-system/tokens.css`): **bone** `#cfc3a9` for words,
+**bronze** `#c9973f` for what acts, **steel** `#96a0a8` for what stands, **blood**
+`#c2584a` for what is wrong, and a mark per state (`◆` do · `·` already · `—`
+fact · `✕` blocked · `?` needs your word · `✓` proved).
+
+```
+cloth_rules[4]{rule,why}:
+  "colour and marks only when stderr is a terminal and NO_COLOR is unset","a pipeline never parses a decoration"
+  "data on stdout, the human rendering on stderr","the TOON row is the data; the coloured line is for the eye"
+  "the words are never conditional — only the colour is","hiding information to save colour is the wrong trade"
+  "no banner over four lines, no rule longer than its text","density first (Monoline TUI · cli-guidelines)"
+```
+
+`bin/ymir-plan.sh --colour` renders the plan in the cloth on stderr while the
+TOON stays on stdout. The installer prints it at the consent, and ends with the
+next steps — *a reaction for every action, a next step for every ending*.
+
+### Two libs the packaged tree needs
+
+```
+libs[2]{path,resolves}:
+  "bin/smidja-lib.sh","the smithy: apps/smidja-factory in a clone, node_modules/@zerwiz/smidja-factory in a package — `smidja_factory_dir`, `smidja_visualizer_dir`"
+  "bin/electron-lib.sh","whether a shell's runtime VERIFIES: `electron_runtime_state` (ok · partial · absent) and the exact remedy"
+```
+
+**Why they exist.** A packaged tree has no `apps/`: the smithy arrives as a
+dependency and the skill symlink dangles. Four call sites assumed the clone's
+layout, so the visualizer read as unbuildable in a package. They resolve through
+`bin/smidja-lib.sh` now.
+
+**And a shell is never declared ready on a directory's presence.** npm gates
+install scripts; a skipped Electron postinstall leaves `dist/` partial and
+`path.txt` unwritten, so the web app builds, every check passes, and the window
+never opens. `electron_runtime_state` verifies, and the plan's `electron` row
+says *the runtime is PARTIAL* with the command that mends it.
+
+## The app packages — how the four surfaces arrive
+
+The distro depends on the surfaces as their own npm packages, so one
+`npm install -g @zerwiz/ymir` fetches them into the tree:
+
+```
+app_packages[4]{package,repo,what}:
+  "@zerwiz/hlidskjalf","zerwiz/hlidskjalf","the control plane — dist/ ships built, served on :3888"
+  "@zerwiz/odrerir","zerwiz/odrerir","the live hall — dist/ ships built"
+  "@zerwiz/sessrumnir","zerwiz/sessrumnir","the seat-hall desktop — out/ ships built (a fork of pi-desktop)"
+  "@zerwiz/smidja-factory","zerwiz/smidja","the smithy and its visualizer — the factory plus the UI's source, built at install"
+```
+
+They are **optionalDependencies**, deliberately: a broken app package must never
+stop the CORE from installing, and a package not yet on the registry is skipped by
+npm and starts arriving the moment it is published. The plan's phase-5 rows report
+each surface separately — installed, declared-but-not-fetched, or no package at all
+— so a silent skip cannot hide.
+
+A global install nests them under the distro's own `node_modules`
+(`<prefix>/lib/node_modules/@zerwiz/ymir/node_modules/@zerwiz/<app>`); a local one
+hoists them to `node_modules/@zerwiz/<app>`. The plan checks both shapes.
+
+```
+bin/npm-publish.sh                       # the platform only
+bin/npm-publish.sh --all                 # the platform + every app package
+bin/npm-publish.sh --dry-run --all       # what would go out, and from where
+bin/npm-publish.sh --unpublish @zerwiz/ymir@0.1.5   # take ONE version back
+```
+
+**A version can be taken back, and the window is short.** npm permits unpublishing
+**one version for 72 hours** after it was published; past that it is npm support's
+door. So `--unpublish` demands a spec that names the version — never a bare name —
+and the row says where the CDN may still serve the tarball for a while afterwards.
+Publishing a newer version is the other half of the repair: it moves the `latest`
+tag off the bad build at once, even before the removal propagates.
+
+**A `files[]` entry that names a directory overrides `.gitignore`.** This is how
+`@zerwiz/ymir@0.1.5` shipped the memory well: `files: [".agents/"]` packed that
+subtree *including* the gitignored stores, and the repo stayed clean while the
+artefact did not. Name what ships, exclude what must not, and prove it with
+`npm pack --dry-run` — the repo's cleanliness says nothing about the tarball.
+
+The app repos are cloned into `apps/` by the install's `apps` step (from the
+registry's `repo: apps/<path>` blocks), which is where `--all` reads their
+manifests. The token comes from the hoard, never from `~/.npmrc`.
+
 ## The steps
 
 ```
-install[20]{step,what,self-heals}:
+install[23]{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"
+  "home","the home the operator CHOOSES, recorded under ~/.config/ymir/home","asks once, records the answer; --check never writes, --yes takes what is recorded, else the documented default"
+  "tree","workspace/{work,personal}/<domains>, companies/, workspaces.yaml, projects.yaml, and the hoard OUTSIDE the repo (secrets/ · docs/ · identity/ · tenants/ at the hoard root under the chosen 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"
+  "apps","the app repos (the app split) — hlidskjalf · hlidskjalf-mobile · odrerir · sessrumnir · smidja","reads $HOARD/identity/projects.yaml (never guesses a remote); clones a missing apps/<path> from its registered git{} block, fast-forwards a present one, and stamps the smithy engine (apps/smidja) from the cloned factory's templates"
   "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"
+  "sessrumnir","the Sessrúmnir desktop GUI (its own repo; lands via the `apps` step 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"
+  "host","this machine — sensed on EVERY host","bin/host-sense.sh senses the setup on ANY host (Rule 05); the Omarchy layer then RECORDS it (bin/omarchy-sense.sh observe), places the apps (bin/desktop-place.sh), installs the post-update hook and the wedge-alarm channel, and (on Omarchy) offers 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"
+  "marks","each app's rune icon + .desktop entry into the operator's own desktop, and the Ymir contract into pi's agent home","bin/design-icon.sh mint --all + install writes to $HOME/.local/share (never a session sandbox), so every app is dockable and pinnable; the contract symlink means every pi session, in ANY folder, loads Brokk"
   "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)"
@@ -44,7 +287,7 @@ install[20]{step,what,self-heals}:
   "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
+**25** `step_*` functions are defined (`home` asks, `tree` builds). 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
@@ -94,8 +337,10 @@ now build it when absent:
 (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.
+`bin/ymir-validate.sh` reports `visualizer` FAIL when `./dist` is missing **and**
+when the build exists but nothing is listening on `:8437`. A PASS means the UI is
+built *and* the API is up — so a built-but-dead visualizer (a bad `CMD_DB`, a
+crashed API) can no longer read as green.
 
 ## Desktop placement (Omarchy desktops, not monitors)
 
@@ -163,13 +408,25 @@ 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.
+A real install prints **the plan it computed** (`bin/ymir-plan.sh`) and waits for
+`[y/N]`. Declining changes nothing (exit 3). `--check` and `--plan` never prompt.
+A non-interactive caller without `--yes` is refused rather than silently
+proceeding.
+
+The plan names every step with its state and the reason for it — including the
+home the operator is asked to choose, the four app surfaces and whether each can
+be installed at all, the terminal backend, and what will be skipped and why. The
+state vocabulary is `DO · SKIP · INFO · BLOCKED · CONSENT`.
+
+`--check` writes nothing — and that includes the migrations. `bin/ymir-migrate.sh
+apply` **moves private data**, so the step chain runs it only on a real run;
+a preview leaves the home exactly as it found it. (It used to apply them even
+under `--check`, which moved a home during a "report only" pass.)
+
+`--check` writes nothing — and that includes the migrations. `bin/ymir-migrate.sh
+apply` **moves private data**, so the step chain runs it only on a real run;
+a preview leaves the home exactly as it found it. (It used to apply them even
+under `--check`, which moved a home during a "report only" pass.)
 
 ## The operator's way in (auth) — `bin/ymir-setup-auth.sh`
 
@@ -225,7 +482,7 @@ part is off. `--json` for machine consumption.
 | **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 |
+| **pi-desktop** (`FaqFirebase/pi-desktop`, Apache-2.0) | **Sessrúmnir** (cloned from its own repo to `apps/sessrumnir` at install) | desktop GUI for the Pi/OMP coding agents — the seat-hall, themed with the Ymir way-of palette |
 
 ## Missing dependencies
 
@@ -298,14 +555,16 @@ company is the operator's to name; Ymir ships no default.
 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/host-sense.sh                    # sense THIS machine (any host)
+bin/omarchy-sense.sh status          # the Omarchy recording (Omarchy hosts)
 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.
+On **every** host the installer senses the machine with `bin/host-sense.sh`. On
+an **Omarchy** host the layer also *records* it (`bin/omarchy-sense.sh observe`)
+and installs a `post-update` hook so Ymir re-learns it every time Omarchy
+updates. On a non-Omarchy host that layer step is a clean SKIP.
 
 Rule: the installer is **idempotent** — running it again changes nothing but
 fills gaps. It never overwrites real user data.
@@ -470,7 +729,7 @@ machines may run the runtime.
 | 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 |
+| **Omarchy layer** | Omarchy only | recording the host (`omarchy-sense observe`), 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
@@ -480,8 +739,15 @@ reports a clean skip anywhere else:
 [ -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.
+That is why the only Omarchy branches left in the core installer are the ones
+that call the layer (`step_omarchy`) and desktop placement (`step_desktop`):
+`step_host` senses the host portably with `host-sense`, and everywhere else the
+same code path runs on any host.
+
+The **consent preamble** the installer prints before it acts says the same thing —
+*"learn this machine (OS, desktop, packages, configs, monitors, scale — Omarchy
+hosts recorded first-class)"* — so the operator is told what will happen in the
+portable terms the code now uses, not the Omarchy-only terms it used before.
 
 ### What the Omarchy layer installs
 

package/.agents/skills/galdr-ymirsystem/assets/memory-well.md

@@ -154,7 +154,9 @@ hardcoded timeline is gone.
 - **First `observe` slow (~20–30 s)** → the embedding model is warming; later
   writes are instant.
 - **Bridge down / `COLD`** → `bin/mimir-bridge.sh --start`; check
-  `state/mimir-bridge.log`.
+  `$YMIR_STATE_DIR/mimir-bridge.log` — runtime state lives in the home the
+  operator chose (`hoard_state_dir` via `bin/hoard-lib.sh`), never in the code
+  tree: a packaged install replaces its tree on upgrade.
 
 **Portability.** The bridge signals processes through `ymir_kill_matching` from
 `bin/ymir-platform.sh` rather than calling `pkill` directly, because `pkill` is

package/.agents/skills/galdr-ymirsystem/assets/nornir-jobs.md

@@ -62,7 +62,7 @@ same day. That is deliberate: cron is idempotent-by-date, not retrying-by-failur
 |---|---|---|
 | `BROKK_ROOT_OVERRIDE` | script's parent | Root when `BROKK_HOME` unset. |
 | `BROKK_HOME` | `$ROOT` | Home owning the jobs and state. |
-| `BROKK_STATE_OVERRIDE` | `$BROKK_HOME/state` | Scheduler state directory. |
+| `BROKK_STATE_OVERRIDE` | `$YMIR_STATE_DIR` (`<home>/state`, via `bin/hoard-lib.sh`) | Scheduler state directory — in the home the operator chose, never in the code tree. |
 | `BROKK_CONFIG_OVERRIDE` | `$BROKK_HOME/config` | Where `cron.yaml` lives. |
 | `BROKK_CRON_LOG_MAX_BYTES` | `1048576` | Rotation threshold. |
 | `BROKK_REALM` | `""` | Realm exported to jobs (jobs also fall back to `data/realm.md`). |
@@ -153,6 +153,44 @@ removed and the failure is reported plainly.
 | `BROKK_MEMORY_PRUNE` | `0` (disabled) |
 | `BROKK_MEMORY_PRUNE_DAYS` | `7` |
 
+### 3.5 Óðrerir — Live Hall snapshot (`bin/nornir-job-hall-snapshot.sh`, 08:00)
+
+The Live Hall is a glass: it reads `apps/odrerir/public/livehall.json`
+(same-origin, `cache: no-store`). This job writes that snapshot from real state
+via `bin/hall-snapshot.sh` — runes, the project registry, the cron gauge, the
+wake queue, standing smiths, armed `when-` sources, and the landed errands —
+then carves Rune `odrerir / hall.snapshot`. Scheduled at 08:00 so it follows
+the 06:00 observer and the 07:00 briefing: the morning board carries the day's
+fresh runes.
+
+| Reads | Writes |
+|---|---|
+| runes ledger · `hodd/identity/projects.yaml` · `config/cron.yaml` · `state/.wake-queue` · herdr agent list · armed when-sources · `state/eindri-reports/archive/` | `apps/odrerir/public/livehall.json` (gitignored runtime) · Rune `odrerir / hall.snapshot` |
+
+- The snapshot is **runtime, never repo**: `apps/odrerir/public/livehall.json`
+  is gitignored, so the job never dirties a branch.
+- Absent `livehall.json` on the Hall is *not* a build failure — the page paints
+  the saga's own count and says so. This job is what makes the board true.
+- Idempotent by nature: each run rewrites the same snapshot from the same
+  inputs; the cron date-guard suppresses repeat dispatch within a day.
+
+### 3.6 Tyr — NSR compliance round (`bin/nornir-job-nsr-compliance.sh`, 02:30)
+
+The NorthStar deterministic gate, run nightly in the quiet hours so sunrise
+finds the doors mended or the Rune already says which broke. Runs every
+`.compliance/gates/check_*.sh` (danger · env · paths · platform · wiring)
+and carves one Rune with the verdict — `nornir / nsr.compliance` on a clean
+round, `nornir / nsr.compliance.failed` (exit 1) naming the failed gates.
+
+| Reads | Writes |
+|---|---|
+| `.compliance/gates/check_*.sh` (deterministic, no network) | Rune `nornir / nsr.compliance[.failed]` · `state/last` line |
+
+- The morning briefing reads the ledger, so a FAIL is seen at 07:00, not
+  found by accident.
+- Idempotent: gates are pure checks; the cron date-guard suppresses repeat
+  dispatch within a day; safe to invoke by hand (`bash bin/nornir-job-nsr-compliance.sh`).
+
 ### 3.4 Yggdrasil — git sync (`bin/nornir-job-git-sync.sh`, 00:00)
 
 The world-tree kept in order. Two modes, both non-destructive:

package/.agents/skills/galdr-ymirsystem/assets/odrerir-hall.md

@@ -110,6 +110,10 @@ snapshot[1]{command,out}:
 - **Ports are sacred:** `:4322` is Óðrerir's alone. Do not move it into a
   Hlidskjalf route or a launcher call — its door is a plain anchor in a new tab
   (`.hall-btn`, rune **ᛟ**, "To the Hall") and its own window.
+- **`.astro/dev.json` is runtime state, never tracked.** Astro rewrites it on
+  every start with the live `pid` and the host's own addresses (LAN + tailnet),
+  so committing it leaks a private IP per run. It is gitignored; the generated
+  types beside it (`content.d.ts`, `types.d.ts`) stay tracked.
 
 ## 5. Files you will touch
 

package/.agents/skills/galdr-ymirsystem/assets/pi-boot/pi-profile.yml

@@ -1,4 +1,9 @@
-# PI Profile — Default Brokk Harness Profile for Ymir
+# PI Profile — the SHAPE of the Brokk harness profile, not a machine's values.
+#
+# Rule 07A: a model id is the USER's, not the repo's. Every operator's differ, so
+# this template carries a placeholder; the live values come from the user's own
+# roster at $YMIR_HOME/hodd/config/agents.yaml, resolved through
+# bin/agents-config.sh. Never commit a real model id here.
 
 profile:
   name: "pi"
@@ -6,7 +11,7 @@ profile:
   version: "1.0.0"
 
 agent:
-  model: "lmstudio/qwen3.6-35b-a3b"
+  model: "<your-model-id>"        # resolved from $YMIR_HOME/hodd/config/agents.yaml
   temperature: 0.7
   max_tokens: 8192
   system_prompt: "BROKK — SYSTEM OPERATING MANUAL (see .opencode/agents/brokk.md)"

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

@@ -292,7 +292,7 @@ The house law lives in `RULES/`; Galdr must know it (Rule 01/02/03):
 
 - **Eindri are the specialists** (marketer, builder, researcher, planner,
   reviewer, documenter, scout, …); each names its **domain** and its **craft**.
-- **Agents live only in `.agents/agents/*.md`.** `.opencode/agent` and
+- **Agents live only in `.agents/agents/*.md`.** `.opencode/agents` and
   `.pi/agents` are **symlinks** to the canonical profiles — never edit them;
   edit `.agents/agents/<profile>.md` and run `bin/valknut-load.sh --all`.
 - **No mock agents.** Ids, names, domains, models, status are real and sourced;

package/.agents/skills/galdr-ymirsystem/assets/runtime-compliance.md

@@ -32,7 +32,7 @@ siblings of this file (`eindri-orchestration.md`, `nornir-jobs.md`). The runtime
 | 11 | Secrets never committed | secret scan + ignore audit | No secret literal; ignore rules cover env files. |
 | 12 | Governed assets current | `compliance-check.sh` (`assets` check) | A governed path changed in the working tree has its owning asset changed too. |
 | 13 | **Governed paths resolve** | `compliance-check.sh` (`governed` check) | Every path in `AGENTS.md`'s `governed[]` table exists (or its glob matches something). |
-| 14 | **Harness surfaces resolve** | `compliance-check.sh` (`harnesses` check) | Every link in `.claude/agents`, `.codex/agents`, `.cursor/agents`, `.pi/agents`, `.opencode/agent` lands (one hop) in `.agents/agents/`, and no nested `SKILL.md` carries frontmatter — a phantom skill. |
+| 14 | **Harness surfaces resolve** | `compliance-check.sh` (`harnesses` check) | Every link in `.claude/agents`, `.codex/agents`, `.cursor/agents`, `.pi/agents`, `.opencode/agents` lands (one hop) in `.agents/agents/`, and no nested `SKILL.md` carries frontmatter — a phantom skill. |
 | 15 | **Skill index true** | `compliance-check.sh` (`skillindex` check) | Every real skill dir is named in `.agents/skills/README.md`, and every `.agents/skills/<name>` path the assets cite exists. |
 
 ### Governed paths — load the asset before you edit
@@ -88,7 +88,7 @@ Two failures hide in the harness layer, and neither is visible from the code:
 
 1. **A symlink that no longer resolves.** Rule 02 says `.agents/agents` is
    canonical and every harness dir (`.claude/agents`, `.codex/agents`,
-   `.cursor/agents`, `.pi/agents`, `.opencode/agent`) is a link into it. The
+   `.cursor/agents`, `.pi/agents`, `.opencode/agents`) is a link into it. The
    `galdr-cli` → `galdr-ymirsystem` rename left `.agents/agents/galdr.md`
    dangling, so Galdr's agent surface did not exist in *any* harness — and
    nothing failed loudly; the harness simply had no such agent.