@zerwiz/ymir 0.1.7 → 0.1.9

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

@@ -142,6 +142,75 @@ 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
@@ -354,6 +423,11 @@ 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`
 
 A fresh checkout seeds **no credential**, so the gate has no way in until the

package/CHANGELOG.md

@@ -1,4 +1,260 @@
 
+## 2026-09-17 — 0.1.9: both shapes reach the registry
+
+- **`ymir raise` works on a packaged install.** 0.1.8 shipped before the resolver,
+  so a user who installed from npm hit `cd …/apps/hlidskjalf: No such file or
+  directory` — every package had arrived, and eighteen scripts were looking in the
+  clone's `apps/`. `bin/app-lib.sh` resolves a surface in either shape now.
+- **A clone and a package are one tree to the scripts.** Proven against both: the
+  five surfaces resolve from `/home/zerwiz/Ymir` and from an npm-installed
+  package, and `ymir raise` against a packaged tree fetches the app's
+  dependencies, raises the gate API, starts Nornir cron, and brings up Bifrost and
+  the well.
+- **The patience words** — `style_patience` — open the installer's long chain and
+  the raise path's build, so a long hour says what it is doing.
+
+## 2026-09-17 — both shapes: a clone and an npm install, and the patience words
+
+- **`ymir raise` failed on a packaged install** — and the reason was ours, not
+  npm's. Every package had arrived; the scripts looked for the apps in the clone's
+  `apps/`, where a package keeps nothing. `scripts/start.sh` died on
+  `cd …/apps/hlidskjalf: No such file or directory`. **Eighteen files assumed the
+  clone's layout.**
+- **One resolver, both shapes:** `bin/app-lib.sh` — `apps/<surface>` in a clone,
+  `node_modules/@zerwiz/<package>` in a package, with the surface→package map
+  (`smidja` → `@zerwiz/smidja-factory`). Wired into the raise path, the windows,
+  the invite door, the seat-hall, Eir, the icons, the placement, the hall snapshot
+  and the installer's own SPA and shell steps. `bin/smidja-lib.sh` delegates to it
+  now, so there is one truth about where things live.
+- **Proven in both trees**: all five surfaces resolve from `/home/zerwiz/Ymir`
+  (a clone) and from an npm-installed package. And `ymir raise` run against the
+  packaged tree no longer dies — it fetches the app's dependencies, raises the
+  gate API, **starts Nornir cron**, and brings up Bifrost and the well.
+- **A trap worth naming:** `printf -v <name>` writes to the *function's* scope, so
+  a helper whose scratch variable shares the caller's requested name swallows the
+  answer. Every scratch name in the resolvers is function-prefixed for that
+  reason.
+- **The patience words.** A long install should say what it is doing and why it
+  takes a while. `style_patience` — the cloth's own line — now opens the
+  installer's long chain and the raise path's build:
+  *much moves · the halls are being set right · this hour is long, and nothing of
+  yours is lost in it — roots come home, shapes are re-cut, names are set true
+  again. Your patience is noted, and it is earned.*
+
+## 2026-09-17 — 0.1.8: the day's work reaches npm
+
+- **The doors.** `ymir` now carries the operator's verbs, each named for the
+  figure who does the work: `raise` · `lower` · `eir` (heal) · `groa` (renew) ·
+  `heimdall` (the way in) · `invite` · `smidja` (the board) · `hlidskjalf` ·
+  `sessrumnir` · `mimir` · `sense` · `plan`. Before this, the package put two
+  commands on PATH and neither could raise the app or the board.
+- **The cloth.** `bin/ymir-style.sh` — colour and marks cut from the halls' own
+  tokens (bone · bronze · steel · blood), shown only where a human watches, with
+  the data left as TOON on stdout. The plan, the installer, the validate report
+  and Eir all wear it.
+- **The shapes.** `bin/smidja-lib.sh` tells a clone's smithy from a packaged one;
+  `bin/smidja-board.sh` is the board's own door (`ymir smidja`), built and served
+  from an npm install; `bin/electron-lib.sh` verifies a shell's runtime so a
+  skipped npm install script cannot pass as a launch.
+- **The icons.** One truth where three maps disagreed, and no claim of a glyph
+  nobody drew: Óðrerir wears ansuz, Sessrúmnir othala, the smithy's icon is named
+  for the smithy.
+- **The repair.** `4dd7273`'s hand-merge left `bin/ymir-install.sh` and
+  `scripts/start.sh` unparseable on main; both restored. Every runtime script
+  parses again.
+
+## 2026-09-17 — main is repaired, and the report wears the cloth
+
+- **Main was broken and nobody had noticed.** A merge resolved by hand
+  (`4dd7273`, from a parallel branch) kept *both* sides of a conflict in
+  `bin/ymir-install.sh` and `scripts/start.sh`: a stray `<`, a duplicated step
+  line, orphaned comments, an `if` with no `fi`. The installer could not parse at
+  all — `bash -n` failed on main — and PR #53's merge carried the breakage
+  forward. Both files are restored from the last revision that parses (`5b7fc66`),
+  with the two fixes that revision predated re-applied: the `--phase` value is
+  consumed, and `--yes | --non-interactive | --accept-all-defaults` are one thing.
+  Every runtime script parses again; the installer's plan runs.
+- **The lesson worth keeping:** a merge is not a place to guess. When both sides
+  of a conflict are real, the resolution is a decision — and `bash -n` on every
+  runtime script is cheap enough to be part of it.
+- **The validate report wears the cloth** — the same rows rendered for the eye on
+  stderr (marks, colour, and a verdict with the next step) while the TOON stays
+  the data on stdout. It found real drift while it was being written: the SPA down
+  on `:3888`, Nornir cron stopped, `sessrumnir`, `mcp` and `hoard` broken.
+- **Eir watches the shells.** A new surface reports the desktop shells' runtime
+  through `bin/electron-lib.sh` — a *partial* Electron runtime is exactly the
+  quiet failure Eir exists for — and her rows render in the cloth too.
+
+## 2026-09-17 — the house gains an unpublish door
+
+- **`bin/npm-publish.sh --unpublish @scope/name@<version>`.** Publishing had a
+  door in this house and unpublishing had none, so the act was done by hand on a
+  machine whose `~/.npmrc` holds a stale token — the very reason the door exists.
+  The new mode resolves the token from the hoard exactly as publishing does,
+  demands a spec that names the version (a whole package is not a one-word act),
+  supports `--dry-run`, and says plainly that the registry's CDN may serve the
+  tarball for a while after the removal.
+- **The window is 72 hours.** npm allows one version back within 72 hours of its
+  publication; past that only npm support can remove it. The help text says so,
+  because a door that does not name its own clock invites a late knock.
+- **`@zerwiz/ymir@0.1.5` was unpublished** — the version that carried the memory
+  well. Publishing the clean 0.1.7 moves the `latest` tag off the tainted build at
+  once, which is the half of the repair that does not wait for propagation.
+
+## 2026-09-17 — the plan learns the smithy's package name, and the install forwards its flags
+
+Two defects the first real end-to-end npm install surfaced — which is what an
+end-to-end test is for.
+
+- **A surface's name is not its package's name.** The plan looked for
+  `apps/smidja` or `@zerwiz/smidja`, but npm serves the smithy as
+  `@zerwiz/smidja-factory` — so the row read `BLOCKED` on a machine where the
+  smithy was installed and standing. `app_dir`/`app_row` now take the surface
+  name and the package name separately, and the row tells the truth: installed,
+  with the visualizer's UI still to build (the tarball ships its source, never a
+  stale build).
+- **`ymir install --plan` forwarded only `--json`.** `--phase` and `--blocked`
+  were dropped on the way through the installer's door, so `--blocked` answered
+  *unknown flag*. Every plan flag is forwarded now.
+
+**The install this came out of:** `npm install -g @zerwiz/ymir` from the registry
+— `@zerwiz/ymir@0.1.7`, 331 packages, and all four surfaces
+(`hlidskjalf` · `odrerir` · `sessrumnir` · `smidja-factory`) arrived inside the
+distro. The tarball carries no memory store — the leak is closed in the artefact
+as well as in the repo.
+
+## 2026-09-17 — the package shipped the memory well (one version, now excluded)
+
+- **The exposure.** `@zerwiz/ymir@0.1.5` carries five files that are nobody's but
+  the operator's: `.agents/memory/kaia.engram`, its `-shm` and `-wal` sidecars, and
+  `.agents/memory/well/{episodes,workspace}.jsonl`. A public npm tarball contained
+  the live memory well — the store and the episodes. Verified by fetching the
+  published artefact and listing it; `0.1.0`–`0.1.4` are clean, and this branch's
+  build is clean.
+- **The cause, and it is a trap worth naming.** `.gitignore` excludes
+  `.agents/memory/kaia.engram*` and `.agents/memory/well/*.jsonl`, and the repo is
+  clean — but **npm does not consult `.gitignore` when `files[]` names a whole
+  directory.** `files: [".agents/"]` packs that subtree *including* the ignored
+  files. Nothing warned: the leak travelled in the artefact, not the repo.
+- **The fix.** The manifest excludes them explicitly, because a `files[]` list
+  cannot rely on the ignore file it overrides:
+  `!.agents/memory/kaia.engram*`, `!.agents/memory/well/*.jsonl`,
+  `!.agents/memory/*.db`, plus `!**/__pycache__/` and `!**/*.pyc` for the compiled
+  junk that was travelling the same way. Verified: `npm pack --dry-run` carries
+  864 files and **no** memory store — the memory README and the ledger's scaffold
+  header are all that remain, as they should be.
+- **The rule for every future package:** a `files[]` entry that names a directory
+  overrides `.gitignore` for everything beneath it. Name what ships, or exclude
+  what must not — and verify with a dry-run pack, never by assumption.
+- **Remediation.** `@zerwiz/ymir@0.1.5` should be unpublished (it is inside npm's
+  window); the clean build publishes as 0.1.7 and supersedes it.
+
+## 2026-09-17 — the doors, the cloth, and the icons that were not there
+
+Four things the operator met and could not use: doors that never opened, output
+with no design, a board that could not be built from a package, and an icon map
+that named a glyph nobody had drawn.
+
+- **The doors are named for the figure who does the work.** `ymir` put two
+  commands on PATH and could neither start the app nor raise the board. It now
+  carries the doors: **raise · lower · eir** (heal) · **groa** (renew) ·
+  **heimdall** (the way in) · **invite** · **smidja** (the board) ·
+  **hlidskjalf** · **sessrumnir** · **mimir** · **sense** · **plan**. A name the
+  law has not given a home — `doctor`, `validate`, `auth` — still answers, once,
+  with the name that has it.
+- **The cloth: `bin/ymir-style.sh`.** Ymir had correct output and no design. The
+  palette is cut from the halls' own tokens — bone for words, bronze for what
+  acts, steel for what stands, blood for what is wrong — with a mark per state
+  (`◆ · — ✕ ? ✓`). Colour and marks appear only where a human is watching
+  (stderr a TTY, `NO_COLOR` unset); the data on stdout stays TOON, and **the
+  words are never conditional, only the colour is**. The plan renders in the
+  cloth on stderr while the TOON stays pipeable; the installer opens with it and
+  ends with the next steps.
+- **The packaged tree is told apart from a clone.** `bin/smidja-lib.sh` resolves
+  the smithy — `apps/smidja-factory` in a clone, `node_modules/@zerwiz/smidja-factory`
+  in a package — and four call sites that assumed the clone now resolve through
+  it. `bin/smidja-board.sh` is the board's own door (`build · start · stop ·
+  status`), which `ymir smidja` runs; built and served end to end from an npm
+  install: `{"ok":true,"sessions":1}`, `GET / → 200`.
+- **A shell's runtime is verified, never assumed.** npm gates install scripts, so
+  a skipped Electron postinstall leaves a partial runtime that still builds the
+  web app and still reports success. `bin/electron-lib.sh` answers `ok · partial
+  · absent`, the plan's `electron` row says **PARTIAL** with the exact remedy, and
+  `step_desktop` refuses to claim a launch it cannot make.
+- **The icons now name glyphs that exist.** Three maps disagreed: `runes.md` gave
+  Óðrerir the rune `wunjo` — **a glyph nobody had drawn** — and tinted Sessrúmnir
+  with a violet that is not in the tokens; `icons.md` gave `othala` to Óðrerir
+  *and* Sessrúmnir; `design-icon.sh` minted `valhalla` for Óðrerir. One truth now:
+  **Óðrerir → ansuz** (Odin's breath, the mead of poetry — what Óðrerir *is*),
+  Sessrúmnir → othala, Valhalla keeps `ᚹ` (drawn in `valhalla.svg`, named Wunjo),
+  Sowilo no longer claimed twice, every tint a house accent from the tokens, and
+  the smithy's icon named `ymir-smidja` rather than `ymir-visualizer`. All 22
+  glyphs parse; every claim resolves to a file. `docs/design.md` stopped calling
+  a living map *"to create"*.
+
+## 2026-09-17 — the house gains an unpublish door
+
+- **`bin/npm-publish.sh --unpublish @scope/name@<version>`.** Publishing had a
+  door in this house and unpublishing had none, so the act was done by hand on a
+  machine whose `~/.npmrc` holds a stale token — the very reason the door exists.
+  The new mode resolves the token from the hoard exactly as publishing does,
+  demands a spec that names the version (a whole package is not a one-word act),
+  supports `--dry-run`, and says plainly that the registry's CDN may serve the
+  tarball for a while after the removal.
+- **The window is 72 hours.** npm allows one version back within 72 hours of its
+  publication; past that only npm support can remove it. The help text says so,
+  because a door that does not name its own clock invites a late knock.
+- **`@zerwiz/ymir@0.1.5` was unpublished** — the version that carried the memory
+  well. Publishing the clean 0.1.7 moves the `latest` tag off the tainted build at
+  once, which is the half of the repair that does not wait for propagation.
+
+## 2026-09-17 — the plan learns the smithy's package name, and the install forwards its flags
+
+Two defects the first real end-to-end npm install surfaced — which is what an
+end-to-end test is for.
+
+- **A surface's name is not its package's name.** The plan looked for
+  `apps/smidja` or `@zerwiz/smidja`, but npm serves the smithy as
+  `@zerwiz/smidja-factory` — so the row read `BLOCKED` on a machine where the
+  smithy was installed and standing. `app_dir`/`app_row` now take the surface
+  name and the package name separately, and the row tells the truth: installed,
+  with the visualizer's UI still to build (the tarball ships its source, never a
+  stale build).
+- **`ymir install --plan` forwarded only `--json`.** `--phase` and `--blocked`
+  were dropped on the way through the installer's door, so `--blocked` answered
+  *unknown flag*. Every plan flag is forwarded now.
+
+**The install this came out of:** `npm install -g @zerwiz/ymir` from the registry
+— `@zerwiz/ymir@0.1.7`, 331 packages, and all four surfaces
+(`hlidskjalf` · `odrerir` · `sessrumnir` · `smidja-factory`) arrived inside the
+distro. The tarball carries no memory store — the leak is closed in the artefact
+as well as in the repo.
+
+## 2026-09-17 — the package shipped the memory well (one version, now excluded)
+
+- **The exposure.** `@zerwiz/ymir@0.1.5` carries five files that are nobody's but
+  the operator's: `.agents/memory/kaia.engram`, its `-shm` and `-wal` sidecars, and
+  `.agents/memory/well/{episodes,workspace}.jsonl`. A public npm tarball contained
+  the live memory well — the store and the episodes. Verified by fetching the
+  published artefact and listing it; `0.1.0`–`0.1.4` are clean, and this branch's
+  build is clean.
+- **The cause, and it is a trap worth naming.** `.gitignore` excludes
+  `.agents/memory/kaia.engram*` and `.agents/memory/well/*.jsonl`, and the repo is
+  clean — but **npm does not consult `.gitignore` when `files[]` names a whole
+  directory.** `files: [".agents/"]` packs that subtree *including* the ignored
+  files. Nothing warned: the leak travelled in the artefact, not the repo.
+- **The fix.** The manifest excludes them explicitly, because a `files[]` list
+  cannot rely on the ignore file it overrides:
+  `!.agents/memory/kaia.engram*`, `!.agents/memory/well/*.jsonl`,
+  `!.agents/memory/*.db`, plus `!**/__pycache__/` and `!**/*.pyc` for the compiled
+  junk that was travelling the same way. Verified: `npm pack --dry-run` carries
+  864 files and **no** memory store — the memory README and the ledger's scaffold
+  header are all that remain, as they should be.
+- **The rule for every future package:** a `files[]` entry that names a directory
+  overrides `.gitignore` for everything beneath it. Name what ships, or exclude
+  what must not — and verify with a dry-run pack, never by assumption.
+- **Remediation.** `@zerwiz/ymir@0.1.5` should be unpublished (it is inside npm's
+  window); the clean build publishes as 0.1.7 and supersedes it.
 
 ## 2026-09-17 — the house gains an unpublish door
 
@@ -59,7 +315,6 @@
   plan's phase-5 row is what says so out loud.
 - **`@zerwiz/ymir` 0.1.7** — the version published once this lands.
 
-
 ## 2026-09-17 — the four surfaces arrive by npm, and an old tree gives up what it holds
 
 - **The app packages arrive with the distro.** `@zerwiz/ymir` now depends on the
@@ -530,6 +785,122 @@ EmberBackground hearth section (shared module + ResizeObserver mend).
 
 # CHANGELOG
 
+## 2026-09-16 — a sandboxed worker cannot think: `auto` stops killing agents
+
+Spawning an Eindri with the default `--isolation auto` produced an **empty pane
+and no status line**. The cause: `auto` chose Utgard whenever the image existed,
+and Utgard runs with `--network none` — so the worker could reach neither its
+cloud model (OpenCode Go) nor a local one (llama.cpp) and died at launch, silently.
+
+- **`auto` now keeps the worker in its worktree.** A spawned Eindri is a
+  model-driven worker: it must reach a model endpoint to think. Utgard is for
+  untrusted *code*, not for the agent's own brain, so the automatic choice is
+  `off`, and it says why.
+- **`--isolation on` warns loudly.** It stays available for a sandbox that can
+  actually reach a model, but it now prints that Utgard has no network and the
+  agent will die silently without one.
+
+## 2026-09-16 — the roster's effect lands, and the backend pin stops being committable
+
+Applying the private roster (`bin/agents-config.sh apply`) writes the resolved
+model into each agent's canonical profile. Flipping the two local agents to Pi
+made that visible — and surfaced a small ignore hole.
+
+- **Profiles follow the roster.** `sindri-developer.md` and `kvasir-scout.md`
+  now carry their **Pi** ids (`llamacpp-coder/qwen3-coder-30b`,
+  `llamacpp/qwen3.5-9b`), and `huginn-researcher.md` its declared model — the
+  output of `apply` against the operator's roster. These profiles are what the
+  harnesses load, so the local agents now run on Pi rather than through OpenCode.
+- **`.agents/config/backend` is ignored.** The pinned terminal backend is
+  machine-local, but `config` is a **symlink** to `.agents/config`, so the
+  `config/*` rule never matched it and the pin was committable. The file is named
+  in `.gitignore` instead.
+
+## 2026-09-16 — the roster can finally run an agent on Pi
+
+`bin/agents-config.sh apply` wrote **every** agent's model into `opencode.json`'s
+agent block, whatever harness that agent used. So an agent set to run on **Pi**
+(native local models) would have had its Pi model id —
+`llamacpp/qwen3.5-9b` — written into OpenCode's config, which cannot resolve it.
+That is why the roster's two local agents were pinned to `harness: opencode` with
+opencode-style ids: there was no working way to put an agent on Pi.
+
+- **`apply` is now harness-aware.** Only `opencode`-harness agents are written
+  into `opencode.json`; a `pi` (or `hermes`) agent is left out, its model id going
+  to the resolve cache that `bin/agent-run.sh` reads. The providers block is
+  unchanged — a provider's endpoint is a real fact OpenCode may still want.
+- The way this is meant to be used: declare a local agent's model as its **Pi**
+  id (`llamacpp/qwen3.5-9b`, `llamacpp-coder/qwen3-coder-30b` — the ids `pi
+  --list-models` reports) with `harness: pi`; the roster is then Pi-driven with no
+  per-machine hand-editing.
+- `galdr-reread`: `assets/harness-integration/README.md` — the two writers of
+  `opencode.json`, and the rule that only OpenCode agents belong in it.
+
+## 2026-09-16 — the visualizer finds its DB, and the seat-hall actually builds
+
+Two more readers left behind — both discovered by *starting the apps*, not by any
+gate. Each failed silently in its own way.
+
+- **`scripts/start.sh` pointed the smithy at a repo path that no longer holds the
+  DB.** `0003-private-data-separation` moved it to `$YMIR_HOME/smidja/smidja.db`,
+  but the starter still passed `CMD_DB=<repo>/apps/smidja/smidja_data/smidja.db`
+  — so the visualizer API died on boot with `smidja.db not found` and `:8437`
+  answered nothing. It now resolves the same pair `bin/smidja-bootstrap.sh` does
+  (home first, in-repo fallback, `SMIDJA_DB` override). The asset already
+  *described* this resolution; the code now implements it.
+- **`bin/sessrumnir-ensure.sh` never built the app.** `[ "$built_present" ]` tests
+  a **literal, non-empty string** — always true — so `ensure --install` skipped
+  `build_app` and reported `built: no` with exit 0. Sessrúmnir only built when the
+  build was run by hand. Now `built_present` (the function) is called.
+- `galdr-reread`: `.agents/skills/galdr-ymirsystem/assets/smidja.md` — the DB
+  path, the `scripts/start.sh` DB resolution, and the observer's read list.
+
+## 2026-09-16 — the credential reaches the gate, and the hall stops leaking an IP
+
+Setting the operator password had **no effect**. This is the bug that made that
+true, and the runtime state that leaked a private address.
+
+- **`scripts/start.sh` never loaded the platform env for the gate.** The gate is
+  `bun run apps/hlidskjalf/server/index.ts`, and the server reads
+  `process.env.HLIDSKJALF_AUTH` — but the launcher passed only `PORT`, and nothing
+  sourced `.env.local`. So a credential written by `bin/ymir-setup-auth.sh`
+  (correctly: `0600`, gitignored) never arrived, and because the gate treats an
+  empty `GATE_AUTH` as authenticated (`authed: GATE_AUTH ? … : true`) the gate
+  stayed **open**. `start.sh` now loads `.env.local` once, before the ports, for
+  every service it raises — the gate, Bifrost and Mimir.
+- **`apps/odrerir/.astro/dev.json` was tracked.** Astro rewrites it on every
+  start with the live `pid` and the host's own addresses (LAN + tailnet) — a
+  private-IP leak into a public tree. It is now untracked and gitignored; the
+  generated types beside it stay tracked.
+- `galdr-reread`: `assets/hlidskjalf-ui.md` (the gate must receive the credential)
+  and `assets/odrerir-hall.md` (`.astro/dev.json` is runtime state).
+
+## 2026-09-16 — four readers that still pointed at the pre-split world
+
+The app split and the hoard migration moved things; four readers never followed.
+None failed loudly — each reported a clean PASS, a wrong SKIP, or a silent loss.
+
+- **`bin/ymir-install.sh` wrote during `--check`.** The step chain ran
+  `bin/ymir-migrate.sh apply` unconditionally, so a preview that promises *"report
+  only, no writes"* actually **moved private data**. Migrations now apply only on
+  a real run: `if [ "$CHECK" = 0 ]; then ... apply; fi`.
+- **`.agents/migrations/0003-private-data-separation.sh` skipped every directory.**
+  It pre-creates its target dirs, then its `copy` refused any target that already
+  existed — so `data/` (and every other directory source) was silently dropped.
+  The realm declaration never arrived and `0004` fell back to a neutral realm.
+  `copy` now **merges** a directory into its target (never overwriting a file) and
+  copies a single file only when it is absent.
+- **`bin/smidja-bootstrap.sh` looked for the smithy at the old root.** `sys.path`
+  pointed at `smidja/`, but the split moved it to `apps/smidja/`, so the DB seed
+  died with `ModuleNotFoundError: No module named 'smidja_modules'`. It now
+  searches `apps/smidja` then `smidja`, so either layout works.
+- **`bin/ymir-validate.sh` read the ledger from the pre-move path.** It looked at
+  `$YMIR_HOME/memory/`, but `0004-hoard-and-realms` put the ledger at
+  `$YMIR_HOME/hodd/memory/` — a false `runes FAIL` on a healthy home. It now tries
+  the hoard first, then the pre-move locations.
+- `galdr-reread`: `.agents/skills/galdr-ymirsystem/assets/smidja.md` — the
+  protected-paths gotcha and the `smidja/` → `apps/smidja/` move.
+
 ## 2026-09-17 — Pi gets its agents, and a dead extension comes back
 
 - **Pi has no agent loader.** Agent loading in Pi is a *package* (`pi-agents`,

package/bin/app-lib.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# app-lib.sh — where an app actually lives.
+#
+# Two installs, one name. In a clone the apps sit at `apps/<surface>` (the
+# registry's `repo: apps/<path>` block clones them there). In a packaged install
+# the tree has no `apps/` at all: each surface arrives as a dependency, at
+# `node_modules/@zerwiz/<package>`.
+#
+#            surface            package
+#            ----------------   ---------------------
+#            hlidskjalf         hlidskjalf
+#            hlidskjalf-mobile  hlidskjalf-mobile
+#            odrerir            odrerir
+#            sessrumnir         sessrumnir
+#            smidja             smidja-factory
+#
+# A surface's name is not always its package's name — and a path is not a name at
+# all. Every script that needs an app resolves it HERE, so the two shapes can
+# never disagree (Rule 07). Source-safe; functions only.
+#
+#   app_dir <surface> <result-var>   the app's directory (empty + exit 1 if absent)
+#   app_pkg <surface>                the npm package name for that surface
+set -u
+
+app_pkg() {  # <surface> → the package name npm serves
+  case "${1-}" in
+    smidja) printf '%s' 'smidja-factory' ;;
+    *)      printf '%s' "${1-}" ;;
+  esac
+}
+
+app_dir() {  # <surface> <result-var> — a clone's apps/<x>, else the package
+  # Scratch names are function-prefixed on purpose: `printf -v <name>` writes to THIS
+  # function's scope, so a scratch variable sharing the caller's requested name
+  # would swallow the answer (a caller asking for "c" or "root" would get nothing).
+  local _apd_surface="${1-}" _apd_rv="${2-}" _apd_root _apd_pkg _apd_c
+  [ -n "$_apd_surface" ] && [ -n "$_apd_rv" ] || return 2
+  _apd_root="${YMIR_ROOT_DIR:-}"
+  if [ -z "$_apd_root" ]; then _apd_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"; fi
+  _apd_pkg="$(app_pkg "$_apd_surface")"
+  for _apd_c in "$_apd_root/apps/$_apd_surface" "$_apd_root/node_modules/@zerwiz/$_apd_pkg"; do
+    [ -d "$_apd_c" ] && { printf -v "$_apd_rv" '%s' "$_apd_c"; return 0; }
+  done
+  printf -v "$_apd_rv" '%s' ""
+  return 1
+}
+
+# Some callers need the directory a mint writes INTO (an app's public/, electron/,
+# dist/…). A packaged app is read-only in spirit, so the clone's apps/ is preferred
+# when it exists; otherwise the package is the only truth there is.
+app_root() {  # <result-var> — where apps live in THIS tree
+  local _apr_rv="${1-}" _apr_root
+  [ -n "$_apr_rv" ] || return 2
+  _apr_root="${YMIR_ROOT_DIR:-}"
+  if [ -z "$_apr_root" ]; then _apr_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"; fi
+  if [ -d "$_apr_root/apps" ]; then printf -v "$_apr_rv" '%s' "$_apr_root/apps"; return 0; fi
+  printf -v "$_apr_rv" '%s' "$_apr_root/node_modules/@zerwiz"
+}

package/bin/design-check.sh

@@ -19,8 +19,19 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# Where an app lives: apps/<surface> in a clone, node_modules/@zerwiz/<pkg> in an
+# npm install — both shapes, one resolver (bin/app-lib.sh).
+if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+  _ya="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yac in "$_ya/app-lib.sh" "$(dirname "$_ya")/bin/app-lib.sh"; do
+    [ -r "$_yac" ] && { . "$_yac"; YMIR_APP_LIB_LOADED=1; break; }
+  done
+  unset _ya _yac
+fi
+app_dir sessrumnir APP_SESSRUMNIR || APP_SESSRUMNIR=""
+
 TOKENS="$ROOT/midgard/design-system/tokens.css"
-SEEDS="$ROOT/apps/sessrumnir/src/renderer/src/themes/fensalir.json"
+SEEDS="$APP_SESSRUMNIR/src/renderer/src/themes/fensalir.json"
 
 case "${1-}" in
   -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;

package/bin/design-icon.sh

@@ -16,6 +16,21 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# Where an app lives: apps/<surface> in a clone, node_modules/@zerwiz/<pkg> in an
+# npm install — both shapes, one resolver (bin/app-lib.sh).
+if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+  _ya="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yac in "$_ya/app-lib.sh" "$(dirname "$_ya")/bin/app-lib.sh"; do
+    [ -r "$_yac" ] && { . "$_yac"; YMIR_APP_LIB_LOADED=1; break; }
+  done
+  unset _ya _yac
+fi
+app_dir hlidskjalf APP_HLIDSKJALF || APP_HLIDSKJALF=""
+app_dir hlidskjalf-mobile APP_HLIDSKJALF_MOBILE || APP_HLIDSKJALF_MOBILE=""
+app_dir odrerir APP_ODRERIR || APP_ODRERIR=""
+app_dir sessrumnir APP_SESSRUMNIR || APP_SESSRUMNIR=""
+app_dir smidja-factory APP_SMIDJA_FACTORY || APP_SMIDJA_FACTORY=""
+
 ICONS="$ROOT/midgard/design-system/icons"
 STONE="#0e0c09"
 
@@ -30,16 +45,19 @@ ACTION="${1:-list}"; shift || true
 APPS=(
   "apps/hlidskjalf|ehwaz|#c9973f|the seat — Hlidskjalf, the high seat of the control plane|ymir-hlidskjalf|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf|Ymir · Hlidskjalf"
   "apps/hlidskjalf-mobile|raidho|#c9973f|the road — the seat carried, Hlidskjalf on a phone|ymir-hlidskjalf-mobile|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf-mobile|Ymir · Hlidskjalf Mobile"
-  "apps/odrerir|valhalla|#c9973f|the hall — Óðrerir, the Live Hall|ymir-odrerir|scripts/electron.sh start --view odrerir|ymir-odrerir|Ymir · Óðrerir"
+  "apps/odrerir|ansuz|#c9973f|the mead — Óðrerir, the Live Hall (Odin's breath, inspiration)|ymir-odrerir|scripts/electron.sh start --view odrerir|ymir-odrerir|Ymir · Óðrerir"
   "apps/sessrumnir|othala|#c9973f|the hall — Sessrúmnir, the seat that holds the cloth|ymir-sessrumnir|bin/sessrumnir.sh start|ymir-sessrumnir|Ymir · Sessrúmnir"
-  "apps/smidja-factory/apps/visualizer|kaunan|#f59e0b|the torch — the forge's eye, Smíðja's trace|ymir-visualizer|scripts/electron.sh start --view smidja|ymir-smidja|Ymir · Smíðja"
+  "apps/smidja-factory/apps/visualizer|kaunan|#f59e0b|the torch — the forge's eye, Smíðja's trace|ymir-smidja|scripts/electron.sh start --view smidja|ymir-smidja|Ymir · Smíðja"
 )
 
 list() {
   printf 'app_icons[%d]{app,rune,tint,says}:\n' "${#APPS[@]}"
   for row in "${APPS[@]}"; do
-    IFS='|' read -r dir glyph tint says _icon _exec _klass _name <<<"$row"
-    printf '  "%s","%s","%s","%s"\n' "$(basename "$dir")" "$glyph" "$tint" "$says"
+    IFS='|' read -r dir glyph tint says icon _exec _klass _name <<<"$row"
+    # The surface's name is the one the desktop knows it by (ymir-smidja →
+    # smidja), never the directory's leaf — a path is not a name (the naming law).
+    surface="${icon#ymir-}"
+    printf '  "%s","%s","%s","%s"\n' "$surface" "$glyph" "$tint" "$says"
   done
   printf 'runes[6]{glyph,name,meaning}:\n'
   printf '  "algiz","ᛉ","the Ymir emblem — the platform itself"\n'

package/bin/desktop-place.sh

@@ -29,6 +29,19 @@ fi
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# Where an app lives: apps/<surface> in a clone, node_modules/@zerwiz/<pkg> in an
+# npm install — both shapes, one resolver (bin/app-lib.sh).
+if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+  _ya="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yac in "$_ya/app-lib.sh" "$(dirname "$_ya")/bin/app-lib.sh"; do
+    [ -r "$_yac" ] && { . "$_yac"; YMIR_APP_LIB_LOADED=1; break; }
+  done
+  unset _ya _yac
+fi
+app_dir hlidskjalf APP_HLIDSKJALF || APP_HLIDSKJALF=""
+app_dir sessrumnir APP_SESSRUMNIR || APP_SESSRUMNIR=""
+app_dir odrerir APP_ODRERIR || APP_ODRERIR=""
+
 HYPR_DIR="$HOME/.config/hypr"
 RULE_FILE="$HYPR_DIR/ymir-desktops.lua"
 # The three Ymir surfaces, in the order they should claim desktops.
@@ -46,7 +59,7 @@ CLASS_odrerir="ymir-odrerir"
 # not a branch of this one.
 install_entries() {
   local dst="$HOME/.local/share/applications" n=0
-  local dirs=("$ROOT/apps/hlidskjalf/electron" "$ROOT/apps/sessrumnir/resources" "$ROOT/apps/odrerir/electron")
+  local dirs=("$APP_HLIDSKJALF/electron" "$APP_SESSRUMNIR/resources" "$APP_ODRERIR/electron")
   if [ "$(ymir_os)" != linux ] && [ "$(ymir_os)" != wsl ]; then
     printf 'skip: desktop entries are Omarchy/Linux-shaped; this host is %s\n' "$(ymir_os)" >&2
     return 0