@zerwiz/ymir 0.1.26 → 0.1.28

package/docs/fixes/install/unversioned-2026-09-11-smooth-install-provider-choice-no-forced-key-real-prereq.md

@@ -0,0 +1,22 @@
+## install · unversioned · 2026-09-11 — Smooth install: provider choice, no forced key, real prereqs
+
+### Why
+- **Model provider is now the operator's choice** (`YMIR_MODEL_PROVIDER`):
+  `opencode-go` (needs a key), `lmstudio` (keyless local), or
+  `openai-compatible`. The bridge no longer forces `OPENCODE_GO_API_KEY`;
+  with no key it auto-selects the keyless local provider so a fresh install works.
+- **New:** `.agents/backend/model-bridge.py` (provider-aware, keyless-capable);
+  `opencode-go-bridge.py` kept as a delegating shim so existing references work.
+- **`bin/bifrost-bridge.sh` v2:** `--provider`, provider auto-selection, no hard
+  env-file requirement, actionable errors per provider.
+- **`bin/ymir-install.sh`:** installs `bun` for real (user-space, then a package
+  hint); installs `mcp<2`; `engram` is now an honest `SKIP` with the Python
+  version reason instead of a permanent WARN; distinguishes docker-group
+  permission from a build failure.
+- **`scripts/start.sh`:** fixed the early exit that skipped the gate API and all
+  services whenever the SPA was already running.
+- **Verified:** compliance 8/8; bridge relays models + chat + 404s; keyless
+  start confirmed; `start.sh` raises Gate API, Nornir, Bifrost, visualizer.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-16-apodex-joins-the-weave-research-planning-provider.md

@@ -0,0 +1,27 @@
+## install · unversioned · 2026-09-16 — Apodex joins the Weave (research/planning provider)
+
+### Why
+- **Apodex provider.** Apodex-1.0-mini-Q4_K_M climbs into the machine as
+  the research/planning GGUF on `http://127.0.0.1:1234/v1`, seated
+  alongside llama.cpp coding models on :8080. LM Studio is retired; its
+  :1234 port belongs to Apodex now.
+- **Env template.** `.env.example` gains the `APODEX_*` block; the LM
+  Studio block is marked RETIRED with its port claim corrected.
+- **Smoke test.** `bin/apodex-smoke-test.sh` — probe or serve-and-test an
+  Apodex seat; exits 0=pass, 1=fail, 2=unavailable. Never mutates config.
+- **Research worker.** `bin/huginn-research-worker.sh` (Apodex-powered
+  Eindri): takes a brief, recalls from Mimirsbrunn, dispatches to the
+  Apodex chat/completions seat, writes a structured verdict, observes it
+  back into the well. Wears the name **Huginn** per the naming law (the
+  research seat; Gungnir stays the skill-synthesis engine).
+- **Agents hall.** `.agents/agents/huginn-researcher.md` binds Huginn to
+  the apodex model; `config/agents.yaml.example` registers the apodex
+  provider and Huginn's seat; `opencode.json` carries the apodex provider
+  block alongside llama.cpp; `bin/models-detect.sh` probes and emits the
+  apodex provider for the Pi model file (`~/.pi/agent/models.json`).
+- **Install seams.** Apodex rides the existing seams: models-detect merges
+  it into the Pi models file at install; agents-config applies it into
+  opencode.json. Mo
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-16-icons-the-operator-can-pin-and-one-pair-of-hands-for-the.md

@@ -0,0 +1,29 @@
+## install · unversioned · 2026-09-16 — icons the operator can pin, and one pair of hands for the shells
+
+### Why
+**"Fail, no icons" — and the cause was a trap I had already been bitten by.**
+`bin/design-icon.sh install` writes an app's rune into the icon theme and a
+`.desktop` entry into the applications dir. It used `XDG_DATA_HOME`, and this
+agent session exports that as a **sandbox** (`…/opencode-rd`), so the icons went
+somewhere no desktop can see. It now targets the operator's real data dir
+(`$HOME/.local/share`, with `YMIR_DESKTOP_DATA_HOME` for a throwaway test) — the
+same class of bug that once hid `gh` from this session.
+
+Installed now, for **every** app: hlidskjalf, **odrerir**, **sessrumnir**, the
+Smíðja visualizer and hlidskjalf-mobile — each with its rune icon and a dockable
+entry. Óðrerir and Sessrúmnir had **none**, which is exactly why they could not
+be pinned. The stale `ymir-smidja.desktop` (pointing at a repo PNG) is folded
+into the rune's own entry.
+
+**One pair of hands for two lifecycles.** `scripts/start.sh` and
+`scripts/stop.sh` manage the web; `scripts/electron.sh` manages the shells — and
+they never met, which is why "the electrons are not running" was true while 28
+processes stood, and why a restart could leave a shell watching a dead port.
+`scripts/raise.sh` / `scripts/lower.sh` own both: lower takes the windows down
+**first**, so none is left watching a port that just vanished.
+
+**A bug the restart surfaced:** `scripts/electron.sh stop` used `local` outside a
+fu
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-16-the-desktop-never-dials-out-cloudflare-stays-outside-ele.md

@@ -0,0 +1,25 @@
+## install · unversioned · 2026-09-16 — the desktop never dials out: Cloudflare stays outside Electron
+
+### Why
+The Allfather's rule: **"electron should never have anything with cloudflare to
+do."** It was not quite true — three doors stood open:
+
+- **Sessrúmnir's "To the Hall"** preferred the local hall and, when it did not
+  answer, fell back to `https://hall.ymir.zerwiz.org`. A desktop seat that
+  reaches for a public hostname when its own machine is quiet is a seat that
+  leaves the building to do its errands. It is now **local only** — when the hall
+  is not running, the seat says so.
+- **Hlidskjalf's shell** took `HLIDSKJALF_URL` and `SMIDJA_URL` from the
+  environment, and **Óðrerir's** took `HALL_URL` — each able to point a desktop
+  window at a tunnel with one exported variable.
+- Both now pass their URL through a **loopback guard**: anything that is not
+  `127.0.0.1`, `localhost` or `::1` is refused with a warning and replaced by the
+  local default. The shell loads the machine, never the internet.
+
+**Why this is the same fight as the bridge:** a desktop app that dials out is a
+desktop app whose failures belong to somebody else's edge. The bridge disguised a
+cloud endpoint as `127.0.0.1` and cost a night; these three would have disguised a
+tunnel as a local seat.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-0-1-12-the-icons-reach-the-live-tree-and-a-missing-surfa.md

@@ -0,0 +1,10 @@
+## install · unversioned · 2026-09-17 — 0.1.12: the icons reach the live tree, and a missing surface is a failure
+
+### Why
+- **The launcher entries name the door** (`Exec=ymir hlidskjalf`, …) instead of an absolute path into whichever tree minted them — the fault that made every icon do nothing.
+- **All three npm shapes resolve**: a clone (`apps/<app>`), a nested package, and a **sibling** package (`<prefix>/lib/node_modules/@zerwiz/<app>`), which is where a global install puts a dependency it hoists out of the distro.
+- **@zerwiz/sessrumnir pinned exact** — a prerelease range resolved in one prefix and was skipped in another.
+- **A missing surface is a FAILURE with the remedy**, never "skipped".
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-0-1-8-the-day-s-work-reaches-npm.md

@@ -0,0 +1,25 @@
+## install · unversioned · 2026-09-17 — 0.1.8: the day's work reaches npm
+
+### Why
+- **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.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-a-stale-install-cannot-hide-and-the-one-liner-cannot-be-.md

@@ -0,0 +1,9 @@
+## install · unversioned · 2026-09-17 — a stale install cannot hide, and the one-liner cannot be stranded
+
+### Why
+- **The fault the Allfather hit:** `npm install -g @zerwiz/ymir` reported *"changed 200 packages"* and changed nothing — npm resolved a **cached `latest`**, saw the same version, and left the old build in place. The installed copy stayed 0.1.14 while the registry served 0.1.26, and nothing told the user. With 750+ downloads, that is not a detail.
+- **The CLI now says when it is out of date** — once a day, on a terminal, silenced by the same `ymir config notice version off` as every other notice: *"a newer Ymir is on npm 0.1.14 → 0.1.26 · update: npm i -g @zerwiz/ymir"*.
+- **The one-liner is cache-proof**: it installs `@latest` with `--prefer-online`, so a stale packument cannot strand a fresh machine.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-both-shapes-a-clone-and-an-npm-install-and-the-patience-.md

@@ -0,0 +1,26 @@
+## install · unversioned · 2026-09-17 — both shapes: a clone and an npm install, and the patience words
+
+### Why
+- **`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/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 shoul
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-gr-a-knows-the-npm-half-how-to-renew-the-published-packa.md

@@ -0,0 +1,9 @@
+## install · unversioned · 2026-09-17 — Gróa knows the npm half: how to renew the published packages
+
+### Why
+- **Her skill gains the whole procedure** — choose the number from the registry (never from memory: it can be ahead of main), land the bump by PR, publish through the vault, verify by the *version document* (the packument lags), and move the four apps pins in the same release.
+- **And the traps, each of which cost a night:** a stale cached `latest` makes `npm i -g` a silent no-op that still prints success; npm gates Electron s postinstall so windows need `npm rebuild electron`; and a package must declare its own `name`/`files`/privacy where it lives rather than having a manifest rewritten at publish time.
+- The token lives in the encrypted vault; when a tool reports it absent, the DOOR is broken, not the key — and `age -d -i hodd/secrets/age.key hodd/secrets/platform.env.age` opens it while `bin/hodd.sh emit` does not.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-npm-only-the-hall-answers-on-its-own-port-and-the-marks-.md

@@ -0,0 +1,27 @@
+## install · unversioned · 2026-09-17 — npm-only: the hall answers on its own port, and the marks land on any desktop
+
+### Why
+The Allfather turned off every service running from the clone and asked for the
+npm path alone to be true.
+
+- **The SPA never listened on `:3888`.** `scripts/start.sh` raised it with a bare
+  `npm run dev`, so Vite took 5173 — then 5174 — while `ymir-validate.sh` and
+  every door looked for `:3888`. The port is now our decision
+  (`--port "$HLIDSKJALF_PORT" --strictPort`), a packaged install serves its built
+  `./dist` through `vite preview` instead of a dev server, and the raise prints
+  the last lines of the log when the port does not answer instead of claiming
+  success.
+- **Óðrerir was skipped on a packaged install** — `HALL_DIR="$ROOT/apps/odrerir"`,
+  the clone's layout again. It resolves through `bin/app-lib.sh` now
+  (`app_dir odrerir`), like every other surface.
+- **The launcher entries and the icons are the freedesktop half, not Omarchy's.**
+  Both halves of `bin/desktop-place.sh` sat behind the Omarchy gate, so a GNOME
+  operator got *nothing* — no entries, no rune icons — which is why the desktop
+  marks from the clone existed and the ones from npm never appeared. `entries` is
+  its own verb now (any Linux desktop), the installer's `marks` step calls it, and
+  the desktop database and icon cache are refreshed afterwards.
+- **A user can see what moved.** `npm install -g` says *"changed 266 packages"* and
+  no versions. The CLI records the version it last ran and says
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-apps-leave-the-monorepo-installation-pulls-them-from.md

@@ -0,0 +1,23 @@
+## install · unversioned · 2026-09-17 — the apps leave the monorepo; installation pulls them from their own repos
+
+### Why
+- **The app split lands in the installer.** The five apps (hlidskjalf,
+  hlidskjalf-mobile, odrerir, sessrumnir, smidja) now live in their own repos
+  registered in the home registry (`$HOARD/identity/projects.yaml`) — the
+  monorepo never tracks them, and **`step_apps`** clones or fast-forwards each
+  `apps/<path>` from its registered `git{}` block (never guessing a remote,
+  always reading the registry). The smithy engine (`apps/smidja`) is stamped
+  from the cloned factory's `templates/smidja`, exactly as `install.py` does
+  for a target repo — so a fresh clone still gets a working smithy.
+- **The vendored app trees leave the index.** `apps/{hlidskjalf,
+  hlidskjalf-mobile,odrerir,sessrumnir,smidja,smidja-factory}` are gitignored
+  and `git rm --cached`-ed (751 files, 135k lines); `apps/README.md` stays.
+  A dir present that is not a git clone is reported (`move it aside and
+  re-run`) rather than silently replaced.
+
+galdr-reread: `.agents/skills/galdr-ymirsystem/assets/installation.md` — the
+step table (`22 steps`, `24` `step_*` functions), the new `apps` row, and the
+Sessrúmnir rows now say "its own repo", not "vendored".
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-doors-the-cloth-and-the-icons-that-were-not-there.md

@@ -0,0 +1,27 @@
+## install · unversioned · 2026-09-17 — the doors, the cloth, and the icons that were not there
+
+### Why
+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_modul
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-editor-stops-being-banished-to-its-own-desktop.md

@@ -0,0 +1,18 @@
+## install · unversioned · 2026-09-17 — the editor stops being banished to its own desktop
+
+### Why
+- **`bin/editor-place.sh` pinned the editor to its own desktop with
+  `no_focus = true`** — VS Code mapped onto a different workspace than the one
+  the Allfather worked on and never took focus, so nothing inside it was
+  clickable. The rule was written by Ymir itself into
+  `~/.config/hypr/ymir-desktops.lua`.
+- **The editor is now UNMANAGED by default**: it opens on the active desktop,
+  focused and clickable, like any other app. The old pin remains reachable
+  explicitly with `YMIR_EDITOR_PIN=1 bin/editor-place.sh apply`.
+- Live desk healed: the `code` windowrule was removed from
+  `~/.config/hypr/ymir-desktops.lua` (backup kept alongside), Hyprland reloaded
+  with no config errors, and the stranded VS Code windows were moved to the
+  active desktop and focused.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-four-surfaces-arrive-by-npm-and-an-old-tree-gives-up.md

@@ -0,0 +1,24 @@
+## install · unversioned · 2026-09-17 — the four surfaces arrive by npm, and an old tree gives up what it holds
+
+### Why
+- **The app packages arrive with the distro.** `@zerwiz/ymir` now depends on the
+  surfaces as their own packages — `@zerwiz/hlidskjalf`, `@zerwiz/odrerir`,
+  `@zerwiz/sessrumnir` (live on the registry) and `@zerwiz/smiddja` (published at
+  0.1.0 today). 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.
+  **Proven**: a global install from the packed tarball lands the core plus all
+  three live apps, 330 packages, and the bin answers `0.1.6`. A local install
+  hoists them to `node_modules/@zerwiz/<app>`; a global one nests them under the
+  distro's own `node_modules` — the plan checks both shapes.
+- **The plan tells the shapes apart.** "Declared as a dependency but not fetched"
+  is a `DO`; "no package and no dependency" is a `BLOCKED`. All four surfaces read
+  `DO` on a machine that has the distro but not yet the apps.
+- **Migration 0005 — the operator's things leave the code tree.** It carries this
+  machine's records, the runtime state (pids · logs · locks · the applied-marker),
+  the operator's credentials, and the settings git does not track. Run on the
+  Allfather's machine: **44 carried, 3 stale twins kept, 1 identical duplicate
+  removed, 0 refused** — the tree left holding `.gitkeep` and the distro's ow
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-house-gains-an-unpublish-door.md

@@ -0,0 +1,19 @@
+## install · unversioned · 2026-09-17 — the house gains an unpublish door
+
+### Why
+- **`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.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-icons-reach-the-live-tree-and-a-missing-surface-is-a.md

@@ -0,0 +1,26 @@
+## install · unversioned · 2026-09-17 — the icons reach the live tree, and a missing surface is a failure
+
+### Why
+The Allfather clicked the launcher icons and nothing happened. Both faults were
+mine, and both are the same mistake wearing different clothes: **something named a
+path where it should have named a door.**
+
+- **The entry launched a temp directory.** Every `.desktop` file carried
+  `Exec=bash <the tree that minted it>/scripts/electron.sh …` — and I had minted
+  from `/tmp/opencode/…` while testing, so every icon on his launcher pointed into
+  a scratch tree. Entries now name the **door**: `Exec=ymir hlidskjalf`, resolved
+  from PATH, so a click reaches whichever install is live. A launcher entry must
+  outlive the tree that wrote it.
+- **The fourth surface was missing and the raise shrugged.** `Sessrúmnir — skipped
+  (the sessrumnir surface is not present)` and the raise carried on. It was a
+  **sibling**: npm put it at `<prefix>/lib/node_modules/@zerwiz/sessrumnir`, beside
+  ymir, not inside it. The resolver knew a clone (`apps/<app>`) and a nested
+  package (`<pkg>/node_modules/@zerwiz/<app>`) but not that third shape — which is
+  the one a **global** install uses when it hoists a dependency out of the distro.
+  All three are resolved now, and a surface that is absent is a **FAILURE with the
+  exact remedy**, never a shrug.
+- **A dependency must resolve every time.** `@zerwiz/sessrumnir` was declared as a
+  prerelease range (`^0.1.8-alpha`): npm resolved it in one prefix and sk
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-install-asks-with-a-plan-and-the-operator-s-things-l.md

@@ -0,0 +1,24 @@
+## install · unversioned · 2026-09-17 — the install asks with a plan, and the operator's things leave the code tree
+
+### Why
+- **The consent a real install asks for is now computed, not recited.** The old
+  prompt was a hardcoded paragraph, and a paragraph cannot know the host: it 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`
+  probes this machine and prints one row per step with its state and the reason —
+  `DO · SKIP · INFO · BLOCKED · CONSENT` — across nine phases (resolve · code ·
+  home · runtimes · engines · apps · wire · raise · verify). `ymir-install.sh`
+  prints it at the consent prompt; `--plan` / `--dry-run` prints it and writes
+  nothing; `--json`, `--phase N` and `--blocked` are there for automation and for
+  reading what is holding an install back.
+- **The four app surfaces are named in the plan.** hlidskjalf, odrerir, sessrumnir
+  and smidja each get a row: whether the source is present, whether the web build
+  exists, and — when it is absent — the honest reason (`no apps/<name> and no
+  @zerwiz/<name> package`). The Electron shells are a `CONSENT` row, not a silent
+  download: three shells each pull a ~100 MB runtime the web surfaces do not need.
+- **The home is the operator's to choose.** `step_home` asks once, records the
+  answer as machine state under `~/.config/ymir/home`, and every later script
+  resolves it through `bin/hoard-lib.sh` (`$YMIR_HOME` → the r
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-installer-actually-installs-the-whole-platform-then-.md

@@ -0,0 +1,9 @@
+## install · unversioned · 2026-09-17 — the installer actually installs (the whole platform, then proves it)
+
+### Why
+- **Why pi.dev and opencode just work and Ymir did not.** They are one binary: JS only, no Electron, no build step, no services, no windows — and their `curl|sh` installer puts the command on PATH *and* runs onboarding. The npm path is the side door. Ymir is a platform: its install must place a CLI, four apps, their dependencies, four Electron runtimes (which npm gates), two SPA builds, desktop entries and icons, the services, and a home — eight things to go wrong, and npm fights half of them.
+- **So the one-liner now finishes the job**, the way theirs does: it installs the command, then runs **the first setup**, then **proves what stands** and names the next door. `YMIR_SKIP_SETUP=1` installs the command alone, for anyone who wants the old behaviour.
+- An installer that stops at a binary leaves the user with a tool that does nothing yet.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-installer-has-a-design-of-its-own.md

@@ -0,0 +1,9 @@
+## install · unversioned · 2026-09-17 — the installer has a design of its own
+
+### Why
+- **The result is rendered, not dumped.** The plan got the cloth and the install did not: twenty-nine raw TOON rows and a poem, which the Allfather rightly called zero design. Now the same rows are rendered for the eye on stderr — a rule, a verdict (*"it stands — 22 steps done · 7 warned · 1 skipped"*), every warning with its reason, and the skips in one line. The TOON stays the data on stdout; the design is for the person.
+- **The consent shows the plan again.** `--colour` renders on stderr and I had sent *both* streams to `/dev/null`, so the plan was invisible at the very moment it was being accepted.
+- **The seat can mend its own runtime**, and says why when it cannot — npm gates Electron postinstall, so a fresh install otherwise ends with a window that cannot open.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-npm-door-stands-the-surfaces.md

@@ -0,0 +1,13 @@
+## install · unversioned · 2026-09-17 — the npm door stands the surfaces
+
+### Why
+- **`@zerwiz/ymir` now depends on its surfaces**: `@zerwiz/{hlidskjalf,
+  odrerir, sessrumnir, smidja-factory}` are declared dependencies (bump
+  `0.1.14` → `0.1.15`), so `npm i -g @zerwiz/ymir` (or a packaged install)
+  delivers the app shells under `node_modules/@zerwiz/*`, which `app-lib`
+  resolves. The audit's one gap — the platform carried no apps — is closed.
+- **`@zerwiz/smidja-factory` `0.1.1` → `0.1.2`**: the visualizer's nanoid fix
+  and the eye's-home SKILL line reach npm.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-the-one-liner-the-readme-promised-and-it-sets-the-path.md

@@ -0,0 +1,9 @@
+## install · unversioned · 2026-09-17 — the one-liner the README promised, and it sets the PATH
+
+### Why
+- **`install.sh` did not exist.** The README's first door (\`curl -fsSL …/install.sh | bash\`) led nowhere — which is how a user on another machine ends up typing \`ymir\` in every combination and getting nothing.
+- **It exists now, and it removes the whole class of failure:** a prefix the user owns (no \`sudo\`, no \`EACCES\`), the \`export PATH\` written into the shell's rc so it survives the session, and then it **proves the door** with \`ymir --version\` rather than promising it.
+- The command was never missing from the package — the published tarball ships \`bin/ymir.js\` and declares \`bin: {ymir, ymir-install}\`. **The shell simply was not looking where npm put it**, and that is the most common "it does not work" in the Node ecosystem.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-17-ymir-command-not-found-is-a-path-fault-and-here-is-the-c.md

@@ -0,0 +1,8 @@
+## install · unversioned · 2026-09-17 — "ymir: command not found" is a PATH fault, and here is the cure
+
+### Why
+- **The command is installed; the shell is not looking.** The published manifest carries `bin: {ymir, ymir-install}`, so the file is there — in npm's global bin directory, which an ordinary Linux install puts under `~/.npm-global` and a shell profile often never adds.
+- **The README answers it where a stuck user looks**: `npm prefix -g`, the `ls` that proves the command exists, the one-line `export PATH`, and the `EACCES` cure that sets a prefix the user owns instead of reaching for `sudo`.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/install/unversioned-2026-09-18-the-readme-leads-with-the-doors-that-work.md

@@ -0,0 +1,13 @@
+## install · unversioned · 2026-09-18 — the README leads with the doors that work
+
+### Why
+- **The npm page and GitHub both render `README.md`**, so a user meets it first — and
+  it buried the door that always works (`npx @zerwiz/ymir`) and the PATH cure inside
+  a later section. It now opens with the one-liner (install into a prefix you own, PATH
+  written, setup run, door proven), names `npx` second, and answers *"ymir: command not
+  found"* and the stale-install trap where they happen.
+- The three doors and their honest reasons: `npx` needs no PATH at all; the one-liner
+  sets it once; `npm install -g` works wherever npm's global bin is on PATH.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/odrerir/unversioned-2026-09-14-rerir-forged-eindri-odrerir-pane-w3-p7.md

@@ -0,0 +1,12 @@
+## odrerir · unversioned · 2026-09-14 — Óðrerir forged (Eindri odrerir, pane w3:p7)
+
+### Why
+- The Live Hall carved on the landing per PLAN.md §14: dealt slate pile,
+  choices + recommended marks, freeform, queue + limit guard, thread ledger,
+  live tally, four empty states, fail-closed, keyboard, reveal, mobile (390px,
+  zero overflow); cloth check green; §12 scan clean. Deployed plan for the
+  public hall: hall.ymir.zerwiz.org via a second Caddy site :4322 (deploy/
+  setup-hall.sh + tunnel-ingress.sh, idempotent, live provisioning untested).
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/odrerir/unversioned-2026-09-17-the-live-hall-s-board-becomes-true-the-snapshot-lands-on.md

@@ -0,0 +1,18 @@
+## odrerir · unversioned · 2026-09-17 — the Live Hall's board becomes true: the snapshot lands on the loom
+
+### Why
+- **The Hall was a glass with nothing behind it.** The Óðrerir page reads
+  `apps/odrerir/public/livehall.json` same-origin, but nothing wrote it on a
+  schedule — the board showed the saga's own static count and said so.
+  `bin/nornir-job-hall-snapshot.sh` (08:00, after the 06:00 observer and the
+  07:00 briefing) now drives `bin/hall-snapshot.sh` from real state — runes,
+  projects, the cron gauge, the wake queue, standing smiths, armed when-
+  sources, landed errands — and carves Rune `odrerir / hall.snapshot`.
+- The snapshot is runtime, never repo: `apps/odrerir/public/livehall.json` is
+  gitignored, so the job never dirties a branch.
+
+galdr-reread: `.agents/skills/galdr-ymirsystem/assets/nornir-jobs.md` — new
+§3.5 row (reads/writes table, idempotence note).
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/runtime/unversioned-2026-09-11-gleipnir-lock-pid-binding-fix.md

@@ -0,0 +1,17 @@
+## runtime · unversioned · 2026-09-11 — Gleipnir lock PID binding fix
+
+### Why
+- **Problem:** The session lock (`state/.lock`) was written with the digest
+  helper's PID (a short-lived child) instead of the live Pi harness PID. The
+  harness adapter (`gna-pi-watch.ts`) reported "no live session holds the lock"
+  and refused to arm the watcher.
+- **Root cause:** `BROKK_SESSION_PID` was never injected into the spawn chain.
+  `gleipnir_lock_acquire` fell back to `$$` (helper PID).
+- **Fix:** `.pi/extensions/syn-turnend-guard.ts` and
+  `.pi/extensions/gna-pi-watch.ts` now pass `BROKK_SESSION_PID: String(process.pid)`
+  in the spawn env, so the lock binds to the live Pi process.
+- **Impact:** Session lock reclamation works on next Pi session start/reload.
+  The stale lock (dead PID) is overwritten by the live PID.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/runtime/unversioned-2026-09-11-hardcoded-per-page-feeds-header-stream.md

@@ -0,0 +1,19 @@
+## runtime · unversioned · 2026-09-11 — Hardcoded per-page feeds (header + stream)
+
+### Why
+- **New:** every gate has its own hardcoded, domain-appropriate rolling feed
+  (16 pools, `src/data/feeds.ts`) — Fleet, Tasks, Well, Runes, Reviews,
+  Processes (Valhalla), Files, Chat, Forge, Runtime, Cron, Sessions, Trace,
+  Decisions, Stats, Profile. Extra Kaia “oracle by the well” lines for the chat
+  page.
+- **Header:** a live `PageFeed` now sits in the page header of every gate
+  (glyph + hint on the left, the current page's latest 3 messages on the
+  right), rolling.
+- **Stream:** the bottom Stream keeps each page's last **40** domain messages,
+  with the fleet-wide feed as fallback. A generator tops it up every 2.4s and
+  the page is seeded on first visit so it is never cold.
+- **Verified:** `tsc` + `vite build` green, SPA 200, compliance 8/8, smoke 8/8,
+  lint 4/4.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/runtime/unversioned-2026-09-11-per-page-rolling-40-message-feeds.md

@@ -0,0 +1,13 @@
+## runtime · unversioned · 2026-09-11 — Per-page rolling 40 message feeds
+
+### Why
+- **Change:** the bottom stream is no longer one global 120-line feed. Every gate
+  keeps its own rolling window of the **last 40** messages, and events are routed
+  to the page they belong to (module → gate: `well`, `sessions`, `forge`,
+  `runes`, `cron`, `reviews`, `processes`), with the fleet-wide feed as fallback.
+  The stream header shows the current page. `STREAM_WINDOW = 40`, matching the
+  chat's `CHAT_WINDOW = 40`.
+- **Verified:** `tsc` + `vite build` green, SPA 200.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/runtime/unversioned-2026-09-11-smi-ja-views-are-repo-local.md

@@ -0,0 +1,17 @@
+## runtime · unversioned · 2026-09-11 — Smiðja views are repo-local
+
+### Why
+- **Change:** Removed the last external dependency. `bin/factory-observe.sh`
+  (which defaulted to `~/command/factory/factory_data/factory.db`) is gone;
+  `bin/smidja-observe.sh` reads the repo's own
+  `smidja/smidja_data/smidja.db` read-only and reports absence honestly.
+- **API:** `/api/factory` replaced by `/api/smidja/{health,sessions,sessions/:id,decisions,stats}`
+  (`bun:sqlite`, read-only).
+- **UI:** four Hlidskjalf gates added — Sessions, Trace, Decisions, Stats —
+  reading the smithy's trace. No `command`/`factory` references remain in the
+  runtime or portal.
+- **Verified:** `tsc` + `vite build` green, SPA 200, endpoints honest-absent,
+  Galdr compliance 8/8, smoke 8/8.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/runtime/unversioned-2026-09-11-stats-1-1-kaia-chat-forge-prompts.md

@@ -0,0 +1,23 @@
+## runtime · unversioned · 2026-09-11 — Stats 1:1, Kaia chat, Forge prompts
+
+### Why
+- **Stats:** ported the full Smiðja `StatsResponse` 1:1 into the gate API and
+  the Stats gate — runs/success/fail/running/rate, token optimization
+  (input/output/cache_read/cache_write, cache-hit ratio, avg CHR/run),
+  local-vs-online provider split with per-model table, 40-model commercial
+  catalog (cached/total/savings/%), by-chain and by-workflow. A real run
+  renders live.
+- **Chat (Kaia):** per-session JSONL store (`state/chat/`), list/history/delete
+  endpoints, a rolling **40-message** window, query-grounded well recall before
+  every dispatch, an animated "Kaia is thinking…" indicator, a session sidebar
+  (new/switch/delete), a connected-model datalist (314 models) with free-type,
+  and Eindri lane toggles.
+- **Forge:** a Prompts mode to read/edit the smithy's
+  `prompt_engineering/<agent>/{system,user}.md` (path-guarded save) and a
+  connected-model datalist for agent models.
+- **Verified:** `tsc` + `vite build` green, live chat via local model with
+  recall on, prompt roundtrip + traversal guard, compliance 8/8, smoke 8/8,
+  lint 4/4.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/runtime/unversioned-2026-09-11-the-well-is-real-mimirsbrunn-engram.md

@@ -0,0 +1,21 @@
+## runtime · unversioned · 2026-09-11 — The well is real (Mimirsbrunn / engram)
+
+### Why
+- **New:** `bin/mimir-bridge.py` + `bin/mimir-bridge.sh` — the `:4602` HTTP face
+  the supervision tree named but that upstream never shipped (engram exposes a
+  CLI + MCP server only). Endpoints: `/health`, `/recall`, `/recent`,
+  `/timeline`, `/inspect`, `/observe`.
+- **New:** repo-local store `.agents/memory/kaia.engram`, seeded from the
+  368-episode JSONL well.
+- **Wired:** gate API `/api/well` now does semantic recall via the bridge (local
+  file fallback) and `/api/mimir/health` is live; the Well gate's Bridge tile
+  and timeline read real data (mock removed).
+- **Harnesses:** the engram MCP server is registered for OpenCode, Pi, Claude,
+  Cursor, and Codex; requires the `mcp<2` SDK (`engram-mcp` breaks on mcp 2.x).
+- **Lifecycle:** the bridge is raised by `scripts/start.sh` and
+  `bin/saga-session-start.sh`; the stale `engram.server` command was corrected.
+- **Verified:** bridge up (370 episodes), semantic recall, MCP handshake
+  (engram 1.30), compliance 8/8, smoke 8/8.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*