@zerwiz/ymir 0.1.8 → 0.1.10

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

@@ -192,6 +192,99 @@ cloth_rules[4]{rule,why}:
 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*.
 
+### A clone and a package are one tree — `bin/app-lib.sh`
+
+The apps are the only thing that differs between the two shapes, and only in
+where they live:
+
+```
+surface            a clone                  an npm install
+---------------    ----------------------   ------------------------------------
+hlidskjalf         apps/hlidskjalf          node_modules/@zerwiz/hlidskjalf
+hlidskjalf-mobile  apps/hlidskjalf-mobile   node_modules/@zerwiz/hlidskjalf-mobile
+odrerir            apps/odrerir             node_modules/@zerwiz/odrerir
+sessrumnir         apps/sessrumnir          node_modules/@zerwiz/sessrumnir
+smidja             apps/smidja-factory      node_modules/@zerwiz/smidja-factory
+```
+
+`bin/app-lib.sh` answers for both — `app_dir <surface> <var>`, `app_pkg
+<surface>` — and **eighteen files** were converted to it: the raise path
+(`scripts/start.sh`), the windows (`scripts/electron.sh`), the invite door, the
+seat-hall trio, Eir, the icon mint, the desktop placement, the hall snapshot, and
+the installer's own SPA and shell steps. `bin/smidja-lib.sh` delegates to it, so
+there is **one** truth about where things live.
+
+**The trap that named itself.** `printf -v <name>` writes to the *function's*
+scope. A helper whose scratch variable shares the caller's requested name
+swallows the answer — `app_dir hlidskjalf c` returned nothing because the
+helper's own `local c` held the path. Every scratch name in the resolvers is
+function-prefixed (`_apd_c`, `_smd_c`, `_apr_root`) for exactly that reason, and a
+new resolver must follow the rule.
+
+**Why it matters beyond tidiness:** a packaged install shipped with eighteen
+scripts looking in `apps/`, so `ymir raise` died on
+`cd …/apps/hlidskjalf: No such file or directory` while every package had in fact
+arrived. A shape assumption is a bug that only shows itself on the *other* shape.
+
+### The hall answers on the port it was given
+
+`scripts/start.sh` raises the SPA, and the SPA must listen on
+`$HLIDSKJALF_PORT` (3888 by default) — every other door looks for it there. Two
+rules came out of a packaged install where it listened nowhere:
+
+```
+spa_serving[2]{shape,how}:
+  "a packaged install","serves its built ./dist with `vite preview --port $PORT --strictPort`"
+  "a clone","serves the dev server, but STILL on $PORT — `npm run dev -- --port $PORT --strictPort`"
+```
+
+A bare `npm run dev` lets Vite take 5173 and the hall silently answers on the
+wrong port; the raise now prints the log's last lines when the port stays silent
+rather than claiming success. Óðrerir resolves through `bin/app-lib.sh` like every
+other surface (it read as `missing apps/odrerir` on a packaged install).
+
+### The marks land on any desktop — not only Omarchy's
+
+`bin/desktop-place.sh` holds **two kinds of thing**, and they were behind one gate:
+
+```
+desktop_halves[2]{half,who_reads_it}:
+  "the window rules (numbered desktops, the Lua rule)","Hyprland / Omarchy only"
+  "the launcher entries and the rune icons","the freedesktop standard — GNOME, KDE, Hyprland alike"
+```
+
+A GNOME operator gets entries and icons and no window rules, which is the correct
+answer — and the reason a packaged install on GNOME placed *nothing* while the
+clone's marks already existed. `bin/desktop-place.sh entries` is the launcher half
+alone (any Linux desktop), the installer's `marks` step calls it, and both the
+desktop database and the icon cache are refreshed after.
+
+### What a user went from, and to
+
+`npm install -g` prints *"changed 266 packages"* and no versions. The CLI records
+the version it last ran in the home's state (`state/version`) and says the
+transition **once**, on the first run after an update:
+
+```
+  the tree moved  0.1.7 → 0.1.9
+  run `ymir eir` to see what stands, `ymir raise` to lift the hall
+```
+
+### The patience words — `style_patience`
+
+A long hour must say what it is doing. `bin/ymir-style.sh` carries the line, and
+the installer's long chain and the raise path's build open with it:
+
+```
+◆ much moves   the halls are being stood up for the first time
+      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.
+```
+
+Written in the house voice, kept under four lines (density), and shown on stderr
+with everything else the cloth renders.
+
 ### Two libs the packaged tree needs
 
 ```

package/.agents/skills/groa-update/SKILL.md

@@ -62,6 +62,15 @@ This touches only the Brokk repo and its own worktrees, never anything under `pr
    Summarize what landed without internal vocabulary: which parts of the fleet are now on the latest, and which were left as-is and why.
    Surface any skipped target whose reason needs the Allfather's attention (a home with un-landed changes, local edits).
 
+5. **Re-check where the apps live — an update can move the shape.**
+   `bin/app-lib.sh` resolves a surface in a clone (`apps/<surface>`) or in a
+   package (`node_modules/@zerwiz/<package>`); `bin/smidja-lib.sh` and
+   `bin/electron-lib.sh` do the same for the smithy and a shell's runtime. After a
+   fast-forward, run `bin/ymir-plan.sh --phase 5` — if a surface that stood
+   installed now reads `BLOCKED`, the layout assumption moved and the resolver
+   needs the new shape. A long update should also say so: `style_patience` from
+   `bin/ymir-style.sh` opens the slow part in the house's own voice.
+
 5. **Read the plan after an update — the new version may expect more of this host.**
    A tracked change can add a step, a root, or a setting the running machine has not
    met yet. After a fast-forward that moved the instruction surface, ask what the

package/.agents/skills/ymir-host/assets/install.md

@@ -48,6 +48,35 @@ To move an existing home to a new place, re-run the install with the new value:
 YMIR_HOME=/path/to/new-home bin/ymir-install.sh
 ```
 
+## The doors — what the operator types afterwards
+
+Two commands land on PATH (`ymir`, `ymir-install`); everything else is a door on
+`ymir`, named for the figure who does the work. `ymir --help` lists them all.
+
+```
+ymir raise | lower        lift the hall, or lay it down
+ymir hlidskjalf | sessrumnir   the two windows
+ymir smidja               the board on :8437 — build · start · stop · status
+ymir heimdall [invite]    the way in, and letting someone else in
+ymir eir                  what stands, and mend what does not
+ymir groa [migrate]       take the latest, and mend this home forward
+ymir mimir · sense · plan
+```
+
+## Both shapes — a clone and an npm install
+
+The operator may have cloned the tree or installed the package; the scripts must
+not care. `bin/app-lib.sh` resolves a surface either way (`apps/<surface>`, else
+`node_modules/@zerwiz/<package>`), `bin/smidja-lib.sh` resolves the smithy, and
+`bin/electron-lib.sh` verifies a shell's runtime. To exercise the *other* shape
+without a second machine:
+
+```bash
+YMIR_ROOT_DIR=/path/to/an/npm/@zerwiz/ymir bash bin/app-lib.sh   # resolve against it
+```
+
+That variable is how a resolver is tested against a package from a clone.
+
 ## Which root holds what
 
 ```

package/CHANGELOG.md

@@ -1,4 +1,100 @@
 
+## 2026-09-17 — 0.1.10: the hall answers on its port, and the marks land
+
+- **The SPA listens where it is asked.** A bare `npm run dev` let Vite take 5173,
+  so `:3888` answered nothing in either shape; a packaged tree now serves its built
+  `./dist` and every shape passes `--port "$HLIDSKJALF_PORT" --strictPort`.
+- **Óðrerir resolves** through `bin/app-lib.sh` instead of the clone's `apps/`.
+- **The launcher entries and rune icons land on any Linux desktop** — the
+  freedesktop half of desktop integration is no longer behind Omarchy's gate, so a
+  GNOME operator gets marks at all.
+- **The version a user went from and to** is said once, on the first run after an
+  update: *the tree moved 0.1.9 → 0.1.10*.
+
+## 2026-09-17 — npm-only: the hall answers on its own port, and the marks land on any desktop
+
+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 the transition
+  once: *the tree moved 0.1.7 → 0.1.9 · run `ymir eir` to see what stands*.
+
+## 2026-09-17 — the doors, written down where a user will find them
+
+- **`README.md` gains "After it installs — the doors"**: the two commands on PATH,
+  the twelve doors on `ymir`, the lawless name that answers once and points at the
+  lawful one, the patience words in full, and a section on **both shapes** — a
+  clone and a package, with one resolver and one rule (colour for the eye, TOON
+  for the pipe).
+- **The skills that must know are taught.** Galdr's `assets/installation.md` gains
+  the shape table, the eighteen converted call sites, and the trap that named
+  itself (`printf -v` writes to the function's scope — scratch names are
+  function-prefixed for that reason). The `ymir-host` skill's `assets/install.md`
+  gains the doors and how to exercise the *other* shape without a second machine
+  (`YMIR_ROOT_DIR`). The `groa-update` skill gains the step that matters after
+  every update: **re-check where the apps live** — a shape assumption is a bug
+  that only shows itself on the other shape — and say the long hour in the house's
+  voice.
+
+## 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

package/README.md

@@ -666,3 +666,57 @@ packages (Hlidskjalf, Óðrerir, Sessrúmnir, Smíðja) — one per app.
 Private data never touches npm — all user data lives at `$YMIR_HOME` (the hoard
 at `hodd/` and the realms at `svartalfaheim/`) and syncs via the user's
 **private** GitHub repo, never a public one.
+
+### After it installs — the doors
+
+`npm install -g @zerwiz/ymir` puts **two** commands on your PATH: `ymir` and
+`ymir-install`. Everything else is a door on `ymir`, named for the figure whose
+work it does — because a great many doors either open or they do not, and a name
+that says whose hand is on it is the difference between guessing and knowing.
+
+```
+ymir                     first setup: the plan, then your word
+ymir raise | lower       lift the hall, or lay it down
+ymir hlidskjalf          the high seat's window
+ymir smidja              the smithy's board (:8437) — build · start · stop · status
+ymir sessrumnir          the seat-hall's window
+ymir heimdall            the way in — your credential (status · set · github)
+ymir invite              let someone else in — mint · list · revoke
+ymir eir                 what stands, and mend what does not
+ymir groa [migrate]      take the latest, and mend this home forward
+ymir mimir · sense · plan
+```
+
+A name the law has not given a home still answers, once, and tells you the name
+that has it: `ymir doctor` replies *the door is named `ymir eir` now*.
+
+**A long hour says so, in its own voice.** The installer opens with the plan and,
+when the work will take a while, tells you plainly:
+
+```
+◆ much moves   the halls are being stood up for the first time
+      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.
+```
+
+### Both shapes — a clone and a package are one tree
+
+Ymir runs the same whether you **cloned** it or **installed** it from npm. The
+apps are the difference, and only in where they live:
+
+| | a clone | an npm install |
+|---|---|---|
+| the surfaces | `apps/hlidskjalf` · `odrerir` · `sessrumnir` · `smidja-factory` | `node_modules/@zerwiz/hlidskjalf` · `odrerir` · `sessrumnir` · `smidja-factory` |
+| how they got there | the registry's `repo: apps/<path>` block clones each | declared as dependencies of the distro |
+
+One resolver (`bin/app-lib.sh`) answers for both, so a script never has to care
+which shape it woke in — and the same is true of the smithy (`bin/smidja-lib.sh`)
+and of a desktop shell's runtime (`bin/electron-lib.sh`). The plan tells you which
+surfaces are present, which are declared but not yet fetched, and which have no
+package at all.
+
+**Colour is for the eye, never for the pipe.** `bin/ymir-style.sh` renders in the
+halls' own cloth — bone for words, bronze for what acts, steel for what stands,
+blood for what is wrong — and only when a human is watching (a terminal, no
+`NO_COLOR`). What a pipeline reads on stdout stays plain TOON.

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"
 

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.
@@ -38,15 +51,20 @@ CLASS_smidja="ymir-smidja"
 CLASS_sessrumnir="sessrumnir"
 CLASS_odrerir="ymir-odrerir"
 
-# ── launcher entries (Omarchy / Linux desktop only) ──────────────────────────
+# ── launcher entries (ANY Linux desktop — GNOME, KDE, Hyprland) ──────────────
+# Two halves live in this file, and they are not the same kind of thing:
+#   · the WINDOW RULES are Hyprland's (Omarchy) — numbered desktops, a Lua rule;
+#   · the LAUNCHER ENTRIES and the app icons are the freedesktop standard, which
+#     GNOME, KDE and Hyprland all read from the same place.
+# A GNOME operator gets entries and icons and no window rules, which is the
+# correct answer — and the reason a packaged install on GNOME had no icons at
+# all, because both halves lived behind the Omarchy gate.
+#
 # The .desktop files are templates (__YMIR_ROOT__, not an absolute path), because
-# where this checkout lives is a fact about the machine, not about Ymir. They are
-# rendered into the user's applications directory. This is DESKTOP INTEGRATION —
-# Omarchy/Hyprland is the supported environment; another OS needs its own launcher,
-# not a branch of this one.
+# where this checkout lives is a fact about the machine, not about Ymir.
 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
@@ -182,6 +200,16 @@ include_launchers_file() {
 }
 
 case "$ACTION" in
+  entries)
+    # The launcher half on its own: any Linux desktop, no Hyprland required.
+    install_entries
+    if command -v update-desktop-database >/dev/null 2>&1; then
+      update-desktop-database "$HOME/.local/share/applications" >/dev/null 2>&1 || true
+    fi
+    if command -v gtk-update-icon-cache >/dev/null 2>&1 && [ -d "$HOME/.local/share/icons/hicolor" ]; then
+      gtk-update-icon-cache -q -t -f "$HOME/.local/share/icons/hicolor" >/dev/null 2>&1 || true
+    fi
+    ;;
   plan)
     plan="$(plan_desktops)"
     printf 'desktop-place[%d]{app,desktop}:\n' "$(printf '%s\n' "$plan" | grep -c .)"

package/bin/eir-doctor.sh

@@ -22,6 +22,17 @@ STATE="${BROKK_STATE_OVERRIDE:-$YMIR_HOME/state}"
 # 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
+# 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=""
+
 
 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
@@ -154,7 +165,7 @@ detail() { # <name> -> one short fact
     herdr)     "have herdr && herdr --version 2>/dev/null | head -1 || echo 'herdr absent'" ;;
     a2abridge) "have a2abridge && a2abridge --version 2>/dev/null | head -1 || echo 'engine absent'" ;;
     hermes)    "have hermes && echo present || echo absent" ;;
-    sessrumnir)"[ -d $ROOT/apps/sessrumnir/out ] && echo built || echo 'not built'" ;;
+    sessrumnir)"[ -d $APP_SESSRUMNIR/out ] && echo built || echo 'not built'" ;;
     well)      "echo 'engram :4602'" ;;
     mcp)       "echo 'a2abridge + engram'" ;;
     lock)      "cat $STATE/.lock 2>/dev/null | tr -d '[:space:]' | sed 's/^/pid /' || echo none" ;;

package/bin/hall-snapshot.sh

@@ -16,6 +16,17 @@
 #   (the Live Hall's own deck; the merged public site takes it from its build).
 set -u
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && 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 odrerir APP_ODRERIR || APP_ODRERIR=""
+
 ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
 
 # The operator's settings and secrets live in the home they chose, never in the
@@ -37,7 +48,7 @@ hoard_data_dir YMIR_DATA_DIR
 # runtime state belong to the home the operator chose at installation, never in
 # the tree — a packaged install replaces its tree on upgrade (Rule 04).
 STATE="${BROKK_STATE_OVERRIDE:-$YMIR_STATE_DIR}"
-OUT="${1:-$ROOT/apps/odrerir/public/livehall.json}"
+OUT="${1:-$APP_ODRERIR/public/livehall.json}"
 
 runes_file="${BROKK_RUNES_FILE:-${YMIR_HOME:-$HOME/Documents/Ymir}/hodd/memory/runes_audit.md}"
 PROJECTS_FILE="${YMIR_HOME:-$HOME/Documents/Ymir}/hodd/identity/projects.yaml"

package/bin/sessrumnir-ensure.sh

@@ -20,7 +20,18 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-APP="$ROOT/apps/sessrumnir"
+# 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=""
+
+APP="$APP_SESSRUMNIR"
 
 case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
 CMD="${1-}"; shift || true

package/bin/sessrumnir-sync.sh

@@ -24,7 +24,18 @@
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-APP="$ROOT/apps/sessrumnir"
+# 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=""
+
+APP="$APP_SESSRUMNIR"
 FORK="$APP/fork"
 UPSTREAM_REPO="${SESSRUMNIR_UPSTREAM:-https://github.com/zerwiz/pi-desktop.git}"
 OWNED_JSON="$FORK/owned.json"

package/bin/sessrumnir.sh

@@ -14,6 +14,17 @@ 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=""
+
 
 # The roots that live OUTSIDE the code tree: this machine's records and the
 # runtime state belong to the home the operator chose at installation, never in
@@ -27,7 +38,7 @@ if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
 fi
 hoard_state_dir YMIR_STATE_DIR
 hoard_data_dir YMIR_DATA_DIR
-APP="$ROOT/apps/sessrumnir"
+APP="$APP_SESSRUMNIR"
 PID_FILE="$YMIR_STATE_DIR/sessrumnir.pid"
 LOG_FILE="$YMIR_STATE_DIR/sessrumnir.log"
 

package/bin/smidja-lib.sh

@@ -20,20 +20,21 @@ SMIDJA_SURFACE="smidja"
 SMIDJA_PACKAGE="smidja-factory"
 
 smidja_factory_dir() {  # <result-var> — the smithy's directory, or empty
-  local result_var=${1-} root="${YMIR_ROOT_DIR:-}" c
-  [ -n "$result_var" ] || return 2
-  if [ -z "$root" ]; then
-    root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+  # The general resolver (bin/app-lib.sh) knows both shapes; the smithy is one
+  # surface among them. The old skill symlink is the last resort, and a dangling
+  # one is not a home — the visualizer must be readable there.
+  local _smd_rv=${1-} _smd_c
+  [ -n "$_smd_rv" ] || return 2
+  if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
+    local _sl; _sl="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    [ -r "$_sl/app-lib.sh" ] && { . "$_sl/app-lib.sh"; YMIR_APP_LIB_LOADED=1; }
   fi
-  for c in \
-    "$root/apps/$SMIDJA_PACKAGE" \
-    "$root/node_modules/@zerwiz/$SMIDJA_PACKAGE" \
-    "$root/.agents/skills/$SMIDJA_PACKAGE"
-  do
-    # A dangling symlink is not a home: the visualizer must be readable there.
-    [ -d "$c/apps/visualizer" ] && { printf -v "$result_var" '%s' "$c"; return 0; }
-  done
-  printf -v "$result_var" '%s' ""
+  if app_dir smidja _smd_c 2>/dev/null && [ -d "$_smd_c/apps/visualizer" ]; then
+    printf -v "$_smd_rv" '%s' "$_smd_c"; return 0
+  fi
+  _smd_c="${YMIR_ROOT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/.agents/skills/$SMIDJA_PACKAGE"
+  [ -d "$_smd_c/apps/visualizer" ] && { printf -v "$_smd_rv" '%s' "$_smd_c"; return 0; }
+  printf -v "$_smd_rv" '%s' ""
   return 1
 }
 

package/bin/ymir-install.sh

@@ -53,6 +53,8 @@ hoard_local_env YMIR_ENV_FILE
 # repo (Rule 04).
 # shellcheck source=bin/hoard-lib.sh
 . "$SCRIPT_DIR/hoard-lib.sh"
+# shellcheck source=bin/app-lib.sh
+. "$SCRIPT_DIR/app-lib.sh"
 ymir_home_root YMIR_HOME
 # Where the smithy's parts live: apps/smidja-factory in a clone, or the
 # @zerwiz/smidja-factory package in an npm install (bin/smidja-lib.sh).
@@ -585,7 +587,8 @@ step_smidja() {
 # Hlidskjalf installs with npm (its own lockfile), not bun, and its API serves the
 # UI from ./dist. Without this step a fresh clone has no SPA and no build.
 step_spa() {
-  local app="$ROOT/apps/hlidskjalf"
+  local app; app_dir hlidskjalf app || app=""
+  local app_ok="$app"
   [ -d "$app" ] || { add hlidskjalf SKIP "no apps/hlidskjalf"; return 0; }
   if [ "$CHECK" = 0 ]; then
     if ! have npm; then
@@ -669,6 +672,13 @@ step_marks() {
   fi
   "$SCRIPT_DIR/design-icon.sh" mint --all >/dev/null 2>&1 || true
   n=$("$SCRIPT_DIR/design-icon.sh" install 2>/dev/null | grep -c '"ymir-') || n=0
+  # The launcher entries are the freedesktop half of desktop integration, and they
+  # belong to ANY Linux desktop — not only to Omarchy's window rules. A GNOME
+  # operator gets entries and icons and no window rules; before this, both halves
+  # sat behind the Omarchy gate and a packaged install placed nothing at all.
+  if [ -x "$SCRIPT_DIR/desktop-place.sh" ]; then
+    "$SCRIPT_DIR/desktop-place.sh" entries >/dev/null 2>&1 || true
+  fi
   [ -r "$HOME/.pi/agent/AGENTS.md" ] || [ -d "$HOME/.pi/agent" ] && {
     ln -sfn "$ROOT/AGENTS.md" "$HOME/.pi/agent/AGENTS.md" 2>/dev/null || true
   }
@@ -708,8 +718,8 @@ step_desktop() {
   fi
   local shell partial=""
   for shell in hlidskjalf odrerir sessrumnir; do
-    local dir="$ROOT/apps/$shell" d
-    [ -d "$dir" ] || dir="$(cd "$ROOT" && npm root 2>/dev/null)/@zerwiz/$shell"
+    local dir d
+    app_dir "$shell" dir || continue
     d="$(electron_runtime_state "$dir" 2>/dev/null || true)"
     [ "$d" = partial ] && partial="$partial $shell"
   done
@@ -819,6 +829,7 @@ step_panes() {
 
 # Ask before touching the machine; --check only previews and never asks.
 [ "$CHECK" = 0 ] && confirm_install
+[ "$CHECK" = 0 ] && style_patience "the halls are being stood up for the first time"
 
 step_panes; step_prereqs; step_home; step_tree; step_apps; step_engines; step_models; step_hermes; step_sessrumnir; step_backend; step_host; step_sandbox; step_memory; step_smidja; step_spa; step_omarchy; step_loaders; step_gates; step_marks
 # Migrations MOVE private data — that is a write, and `--check` promises none.

package/bin/ymir-invite.sh

@@ -16,8 +16,19 @@
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-MODULE="$ROOT/apps/hlidskjalf/server/accounts.ts"
-STORE="$ROOT/apps/hlidskjalf/server/accounts.ts" # absolute: one definition of an account, wherever this is run from
+# 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=""
+
+MODULE="$APP_HLIDSKJALF/server/accounts.ts"
+STORE="$APP_HLIDSKJALF/server/accounts.ts" # absolute: one definition of an account, wherever this is run from
 
 die() { printf 'ymir-invite: %s\n' "$1" >&2; exit 1; }
 
@@ -25,7 +36,7 @@ command -v bun >/dev/null 2>&1 || die "bun is required (bin/ymir-install.sh inst
 
 # A tiny bun program per action — the module is the single source of truth.
 accounts() {
-  ( cd "$ROOT/apps/hlidskjalf" && bun -e "$1" )
+  ( cd "$APP_HLIDSKJALF" && bun -e "$1" )
 }
 
 [ -f "$MODULE" ] || die "the account store module is missing: $MODULE"

package/bin/ymir-style.sh

@@ -95,6 +95,19 @@ style_line() {  # <state> <name> <detail> — the one line per thing
 
 style_heading() { printf '\n%s%s%s\n' "$C_BRONZE" "$1" "$C_OFF" >&2; }
 
+# For a long hour: say what is happening and why it takes a while. A user who
+# knows the halls are being set right waits; a user watching a silent cursor
+# wonders whether it has broken.
+style_patience() {  # [what is being set right]
+  local what="${1:-the halls are being set right}"
+  printf '\n' >&2
+  style_line DO "much moves" "$what"
+  style_hint "      this hour is long, and nothing of yours is lost in it —"
+  style_hint "      roots come home, shapes are re-cut, names are set true again."
+  style_hint "      Your patience is noted, and it is earned."
+  printf '\n' >&2
+}
+
 # The ending: what stands, then exactly what to type next. Every CLI deserves
 # to leave the operator with the next step and nothing else to guess.
 style_next() {  # one command per line, as "verb — what it does"

package/bin/ymir.js

@@ -49,6 +49,25 @@ const faint = wrap('38;2;107;98;80');
 const blood = wrap('38;2;194;88;74');
 const bold = wrap('1');
 
+// ── what a user went from, and to ────────────────────────────────────────────
+// `npm install -g` prints "changed 266 packages" and no versions, so an operator
+// cannot see what moved. We can: record the version we last ran, and say the
+// transition once, on the first run after an update.
+const STATE_DIR = process.env.YMIR_STATE_DIR || path.join(process.env.YMIR_HOME || path.join(require('node:os').homedir(), 'Documents', 'Ymir'), 'state');
+function versionNotice() {
+  try {
+    const f = path.join(STATE_DIR, 'version');
+    const seen = fs.existsSync(f) ? fs.readFileSync(f, 'utf8').trim() : '';
+    if (seen === pkg.version) return;
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(f, pkg.version + '\n');
+    if (!seen) return;                       // a first install has nothing to compare
+    process.stderr.write(
+      bone(`  the tree moved  `) + faint(`${seen} → `) + bronze(`${pkg.version}`) + '\n' +
+      faint(`  run \`ymir eir\` to see what stands, \`ymir raise\` to lift the hall\n\n`));
+  } catch { /* a version notice must never break a door */ }
+}
+
 // ── the doors ────────────────────────────────────────────────────────────────
 // verb → { script, args } — args are prepended to whatever the operator passes,
 // so a verb can be a doorway to a sub-verb of a script that has several.
@@ -108,6 +127,7 @@ function run(script, args) {
 const argv = process.argv.slice(2);
 const first = argv[0];
 
+versionNotice();
 if (!first) run(DOORS.install.script, []);
 if (first === '--version' || first === '-v' || first === '-V') {
   process.stdout.write(`${pkg.version}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerwiz/ymir",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Ymir \u2014 the single-tenant agent operating system. Omarchy-first, host-aware, self-healing.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/zerwiz/ymir",

package/scripts/electron.sh

@@ -26,6 +26,19 @@ fi
 VERSION="1.1.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 odrerir APP_ODRERIR || APP_ODRERIR=""
+app_dir sessrumnir APP_SESSRUMNIR || APP_SESSRUMNIR=""
+
 
 # The roots that live OUTSIDE the code tree: this machine's records and the
 # runtime state belong to the home the operator chose at installation, never in
@@ -39,8 +52,8 @@ if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
 fi
 hoard_state_dir YMIR_STATE_DIR
 hoard_data_dir YMIR_DATA_DIR
-APP="$ROOT/apps/hlidskjalf"
-Odrerir_app="$ROOT/apps/odrerir"
+APP="$APP_HLIDSKJALF"
+Odrerir_app="$APP_ODRERIR"
 NO_INSTALL=0
 VIEW="${YMIR_DESKTOP_VIEW:-hlidskjalf}"
 VIEWS=(hlidskjalf smidja odrerir)

package/scripts/start.sh

@@ -17,6 +17,22 @@ if [ -z "${YMIR_PLATFORM_LOADED:-}" ]; then
 fi
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# The cloth (bin/ymir-style.sh) — colour and words for the human watching.
+if [ -z "${YMIR_STYLE_LOADED:-}" ] && [ -r "$ROOT/bin/ymir-style.sh" ]; then
+  . "$ROOT/bin/ymir-style.sh"; YMIR_STYLE_LOADED=1; style_init
+fi
+# 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 odrerir HALL_DIR || HALL_DIR=""
+
 # Where the smithy's parts live: apps/smidja-factory in a clone, or the
 # @zerwiz/smidja-factory package in an npm install (bin/smidja-lib.sh).
 if [ -z "${YMIR_SMIDJA_LIB_LOADED:-}" ]; then
@@ -48,7 +64,7 @@ hoard_data_dir YMIR_DATA_DIR
 # The roots that live OUTSIDE the code tree: this machine's records and the
 # runtime state belong to the home the operator chose at installation, never in
 # the tree — a packaged install replaces its tree on upgrade (Rule 04).
-APP="$ROOT/apps/hlidskjalf"
+APP="$APP_HLIDSKJALF"
 RUN="$ROOT/.run"
 PID_FILE="$RUN/hlidskjalf.pid"
 LOG="$RUN/hlidskjalf.log"
@@ -80,7 +96,8 @@ else
 fi
 
 if [[ ! -d "$APP/node_modules" ]]; then
-  echo "Installing dependencies…"
+  style_patience "the seat's own dependencies are being fetched, then the hall is raised"
+echo "Installing dependencies…"
   (cd "$APP" && npm install --no-audit --no-fund)
 fi
 
@@ -180,7 +197,7 @@ fi
 
 # Óðrerir — the Live Hall. Its own Astro board on :4322, the carved planning
 # glass every hall door opens. Raised before the SPA so a window never waits.
-HALL_DIR="$ROOT/apps/odrerir"
+app_dir odrerir HALL_DIR || HALL_DIR=""
 HALL_PORT="${ODRERIR_PORT:-4322}"
 HALL_PID_FILE="$RUN/odrerir.pid"
 HALL_LOG="$RUN/odrerir.log"
@@ -195,13 +212,14 @@ if [ -d "$HALL_DIR" ]; then
     echo "Óðrerir — Live Hall raised (pid $(cat "$HALL_PID_FILE")) → http://127.0.0.1:${HALL_PORT}/"
   fi
 else
-  echo "Óðrerir — Live Hall skipped (missing apps/odrerir)." >&2
+  echo "Óðrerir — Live Hall skipped (the odrerir surface is not present)." >&2
 fi
 
 cd "$APP"
 
 if [[ "${1:-}" == "--foreground" ]]; then
-  exec npm run dev
+  if [ -d "$APP/dist" ]; then exec npx --no-install vite preview --port "$PORT" --strictPort --host
+  else exec npm run dev -- --port "$PORT" --strictPort --host; fi
 fi
 
 # The SPA is already serving — nothing more for us to raise here.
@@ -211,11 +229,18 @@ if [[ "$SPA_UP" == "1" ]]; then
 fi
 
 # New session so we can signal the whole process group on stop.
-ymir_detach npm run dev >"$LOG" 2>&1
+# The port is OUR decision, not Vite's: a bare `npm run dev` takes 5173 and the
+# hall never answers on the port every other door expects. A packaged install
+# ships ./dist, so it is served; a clone gets the dev server — both on $PORT.
+if [ -d "$APP/dist" ]; then
+  ymir_detach bash -c "cd '$APP' && exec npx --no-install vite preview --port '$PORT' --strictPort --host" >"$LOG" 2>&1
+else
+  ymir_detach bash -c "cd '$APP' && exec npm run dev -- --port '$PORT' --strictPort --host" >"$LOG" 2>&1
+fi
 PID=$!
 echo "$PID" > "$PID_FILE"
 
-# Wait for the port to answer (max ~15s).
+# Wait for the port to answer (max ~15s), then say what is true.
 for _ in $(seq 1 30); do
   if curl -s -o /dev/null "http://127.0.0.1:${PORT}/"; then
     echo "Hlidskjalf raised (pid $PID) → http://127.0.0.1:${PORT}/"
@@ -225,5 +250,6 @@ for _ in $(seq 1 30); do
   sleep 0.5
 done
 
-echo "Hlidskjalf started (pid $PID) but the port did not answer yet — check $LOG" >&2
+echo "Hlidskjalf started (pid $PID) but :${PORT} did not answer — see $LOG" >&2
+tail -5 "$LOG" >&2 2>/dev/null || true
 exit 1