@zerwiz/ymir 0.1.7 → 0.1.8

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,218 @@
 
+## 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 +273,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 +743,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/design-icon.sh

@@ -30,16 +30,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/einherjar-spawn.sh

@@ -342,6 +342,12 @@ else
 fi
 
 # --- isolation resolution ----------------------------------------------------
+# A spawned Eindri is a MODEL-DRIVEN worker: it must reach a model endpoint to
+# think at all. Utgard runs with `--network none`, so a sandboxed agent cannot
+# reach either a cloud model (OpenCode Go) or a local one (llama.cpp) — it dies
+# silently at launch, leaving an empty pane and no status line. Utgard is for
+# untrusted CODE, not for the agent's own brain. So `auto` keeps the worker in
+# its worktree, and `on` is an explicit choice that warns.
 ISOLATION_EFFECTIVE=off
 case "$ISOLATION" in
   on)
@@ -351,14 +357,14 @@ case "$ISOLATION" in
       exit 1
     }
     ISOLATION_EFFECTIVE=on
+    echo "warning: Utgard runs with --network none — the worker's model endpoint must be reachable INSIDE the sandbox, or the agent dies silently. Pass --isolation off to run in the worktree." >&2
     ;;
   off) ISOLATION_EFFECTIVE=off ;;
   auto)
+    ISOLATION_EFFECTIVE=off
     if [ -n "$ENGINE" ] && "$ENGINE" image inspect utgard-runner:latest >/dev/null 2>&1; then
-      ISOLATION_EFFECTIVE=on
-      echo "isolation: on (Utgard image present; pass --isolation off to run in the worktree)" >&2
+      echo "isolation: off (Utgard image present, but a model-driven worker needs its endpoint and Utgard has no network — pass --isolation on only for a sandbox that can reach a model)" >&2
     else
-      ISOLATION_EFFECTIVE=off
       echo "isolation: off (no Utgard image; pass --isolation on after building it)" >&2
     fi
     ;;

package/bin/eir-doctor.sh

@@ -18,6 +18,11 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
 STATE="${BROKK_STATE_OVERRIDE:-$YMIR_HOME/state}"
 
+# The cloth: colour and marks for the human reading this report; the TOON rows on
+# stdout stay the data (bin/ymir-style.sh).
+if [ -z "${YMIR_STYLE_LOADED:-}" ]; then . "$SCRIPT_DIR/ymir-style.sh"; YMIR_STYLE_LOADED=1; fi
+style_init
+
 case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
 ACTION="${1:-check}"; shift || true
 
@@ -25,7 +30,7 @@ have() { command -v "$1" >/dev/null 2>&1; }
 say_ok() { return 0; }
 
 # Each surface: `s_<name>` = healthy? (exit 0), `f_<name>` = the repair.
-SURFACES=(floors herdr a2abridge hermes sessrumnir well mcp lock migrations hoard)
+SURFACES=(floors herdr a2abridge hermes sessrumnir shells well mcp lock migrations hoard)
 
 s_floors()    { [ -x "$SCRIPT_DIR/prereq-ensure.sh" ] && "$SCRIPT_DIR/prereq-ensure.sh" status >/dev/null 2>&1; }
 f_floors()    { "$SCRIPT_DIR/prereq-ensure.sh" ensure --install >/dev/null 2>&1; }
@@ -37,6 +42,34 @@ s_hermes()    { [ -x "$SCRIPT_DIR/hermes-ensure.sh" ] && "$SCRIPT_DIR/hermes-ens
 f_hermes()    { "$SCRIPT_DIR/hermes-ensure.sh" ensure --install >/dev/null 2>&1; }
 s_sessrumnir(){ [ -x "$SCRIPT_DIR/sessrumnir-ensure.sh" ] && "$SCRIPT_DIR/sessrumnir-ensure.sh" status >/dev/null 2>&1; }
 f_sessrumnir(){ "$SCRIPT_DIR/sessrumnir-ensure.sh" ensure --install >/dev/null 2>&1; }
+# The desktop shells: absent is healthy (the web surfaces stand alone), PARTIAL is
+# not — npm gated the Electron postinstall, so the window cannot open while every
+# build still passes (bin/electron-lib.sh).
+shell_dirs() {
+  local a d
+  for a in hlidskjalf odrerir sessrumnir; do
+    for d in "$ROOT/apps/$a" "$ROOT/node_modules/@zerwiz/$a"; do
+      [ -d "$d" ] && { printf '%s\n' "$d"; break; }
+    done
+  done
+}
+s_shells() {
+  local d state
+  while IFS= read -r d; do
+    state="$(electron_runtime_state "$d" 2>/dev/null || true)"
+    [ "$state" = partial ] && return 1
+  done < <(shell_dirs)
+  return 0
+}
+f_shells() {
+  printf 'eir: the shells need YOUR hand — npm gated the runtime download:\n' >&2
+  electron_remedy >&2
+  return 1
+}
+if [ -z "${YMIR_ELECTRON_LIB_LOADED:-}" ] && [ -r "$SCRIPT_DIR/electron-lib.sh" ]; then
+  . "$SCRIPT_DIR/electron-lib.sh"; YMIR_ELECTRON_LIB_LOADED=1
+fi
+
 s_well()      { [ -x "$SCRIPT_DIR/mimir.sh" ] && "$SCRIPT_DIR/mimir.sh" health >/dev/null 2>&1; }
 f_well()      { "$SCRIPT_DIR/mimir.sh" start >/dev/null 2>&1; }
 # MCP: both A2A servers wired into opencode + pi.
@@ -126,6 +159,7 @@ detail() { # <name> -> one short fact
     mcp)       "echo 'a2abridge + engram'" ;;
     lock)      "cat $STATE/.lock 2>/dev/null | tr -d '[:space:]' | sed 's/^/pid /' || echo none" ;;
     migrations)"echo 'structure'" ;;
+    shells)    'shell_dirs | while IFS= read -r d; do printf "%s %s; " "$(basename "$d")" "$(electron_runtime_state "$d" 2>/dev/null || true)"; done' ;;
     hoard)     "printf 'hoard %s' \"$(_hoard_root)\" ; [ -d \"$YMIR_HOME/identity\" ] && printf ' +flat-duplicate' ; printf '\\n'" ;;
   esac
 }
@@ -151,6 +185,14 @@ done
 printf 'eir[1]{action,root,broken}:\n  "%s","%s",%s\n' "$ACTION" "$ROOT" "$broken"
 printf 'health[%d]{surface,state,detail}:\n' "$count"
 printf '%b' "$rows"
+# For the eye, on stderr: marks and colour; for the pipe, the TOON above.
+if [ -t 2 ]; then
+  printf '\n' >&2
+  while IFS='|' read -r surface state detail; do
+    [ -n "$surface" ] || continue
+    style_line "$state" "$surface" "$detail"
+  done <<<"$(printf '%b' "$rows" | sed 's/^  //; s/"//g; s/,/|/; s/,/|/')"
+fi
 if [ "$broken" != 0 ]; then
   printf 'eir: %s surface(s) need mending — run: bin/eir-doctor.sh fix\n' "$broken"
   exit 1

package/bin/electron-lib.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# electron-lib.sh — is a desktop shell's runtime actually there?
+#
+# The trap this exists for: npm blocks a package's install scripts by default
+# (npm 11.16+ warns, npm 12 refuses), and Electron's postinstall is what downloads
+# its ~100 MB runtime. Without it the install still reports SUCCESS and the web app
+# still builds — `node_modules/electron/dist/` is simply partial and `path.txt` is
+# never written. So the shell fails to launch while every check says healthy, and
+# nobody is told.
+#
+# Ymir refuses that silence: a shell is only "ready" when the runtime verifies.
+# Source-safe, functions only.
+#
+#   electron_runtime_state <app-dir>   ok | partial | absent   (exit 0 only for ok)
+#   electron_remedy                    the exact command that mends a partial one
+set -u
+
+electron_runtime_state() {  # <app-dir>
+  local dir="${1-}"
+  [ -n "$dir" ] && [ -d "$dir" ] || { printf 'absent'; return 1; }
+  [ -d "$dir/node_modules/electron" ] || { printf 'absent'; return 1; }
+  # path.txt is written by the postinstall; dist/electron is what it points at.
+  if [ -f "$dir/node_modules/electron/path.txt" ] \
+     && [ -x "$dir/node_modules/electron/dist/electron" ]; then
+    printf 'ok'; return 0
+  fi
+  printf 'partial'; return 1
+}
+
+electron_remedy() {
+  printf 'the runtime download was skipped by npm — approve and rebuild:\n'
+  printf '  npm install-scripts approve electron && npm rebuild electron\n'
+  printf 'yonder: bin/ymir-install.sh --no-desktop if the web surfaces are enough'
+}