@zerwiz/ymir 0.1.9 → 0.1.11

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

@@ -192,6 +192,128 @@ 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.
+
+### Every notice can be silenced — `ymir config`
+
+Some lines are information the first time and noise the tenth. A user must be able
+to say **not again**, once, and be believed. The preferences live in the operator's
+settings (`<home>/config/notices.conf`, one `key=on|off` per name) and the door is:
+
+```
+ymir config                          # what is shown, and what is not
+ymir config notice version off       # silence one; `on` restores it
+judgment[4]{key,what}:
+  "version","the line that says which version moved to which"
+  "patience","the long-hour words before a slow install or build"
+  "next","the where-to-go-from-here block at the end"
+  "hints","the one-line helpers that say how to hide a notice"
+```
+
+Every notice that can be silenced **says so once**, in the cloth's faint voice —
+`(not again: ymir config notice version off)` — so the way out is discoverable
+without a manual. Absent means on; a preference is honoured by the shell cloth
+(`notice_wanted`, `notice_hint`) and by the CLI alike. `ymir-install.sh`'s marks
+and the raise path honour it too.
+
+### Four surfaces, one raise
+
+`ymir raise` lifts the whole hall — the SPA (`:3888`), Óðrerir (`:4322`), the
+board (`:8437`), and the commit-hall Sessrúmnir rises in the same motion (it is an
+Electron app of its own, not a browser surface). `ymir-install.sh`'s desktop step
+opens **one window per surface** rather than a single "both".
+
+### 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,123 @@
 
+## 2026-09-17 — 0.1.11: four surfaces, their marks, and a door that mends
+
+- **All four surfaces rise from one npm install** — Hlidskjalf `:3888`, Óðrerir
+  `:4322`, the board `:8437`, and Sessrúmnir in its own window; the installer's
+  desktop step opens one window per surface.
+- **All four launcher marks land** — the rune glyphs ship in the package
+  (`midgard/design-system/`), the mint resolves a packaged app, the apps'
+  templates are written before the rune marks so the themed name stands, and a
+  retired name is swept from the launcher.
+- **`ymir hlidskjalf` mends the Electron runtime itself** before refusing, because
+  npm gates install scripts and a fresh user could otherwise have no window at all.
+- **Every notice can be silenced once and remembered** — `ymir config notice
+  version|patience|next|hints off`.
+- **Óðrerir serves its build** from a package, and says what failed when it cannot.
+
+## 2026-09-17 — the sweep, and the door that mends itself
+
+- **A retired name is swept from the launcher.** `ymir-visualizer.desktop` and its
+  icon pointed at a glyph nobody ships — a blank square for anyone who knew the old
+  name. `design-icon.sh install` removes retired entries now (`ymir-visualizer`,
+  and `ymir-hlidskjalf-mobile` where that app is not installed).
+- **`ymir hlidskjalf` mends the Electron runtime itself.** npm gates install
+  scripts by default, so a fresh install can build the web app perfectly and have
+  no window. The door now runs the repair it used to *describe*
+  (`npm install-scripts approve electron` + `npm rebuild electron`), and only then
+  refuses — with both the manual command and the honest alternative
+  (`ymir install --no-desktop`).
+- **Two faults are provably in the app repos, not here** (recorded so nobody hunts
+  them in Ymir again):
+  - **the fourth hall** — the landing's list is a hardcoded SPA component
+    (`HallsSwitcher`; the bundle says *"three halls of Ymir — one seat, three
+    roofs"*), not data from the gate API. Óðrerir must be added in
+    `zerwiz/hlidskjalf` and the SPA rebuilt.
+  - **the ember glow** — the seat ships `emberBootTheme` in its built renderer but
+    no themed cloth beside it; the house's framework-neutral
+    `midgard/design-system/ember.js` exists precisely so every surface can share
+    one fire, and the seat must be told to light it (`zerwiz/sessrumnir`).
+
+## 2026-09-17 — "not again", and four surfaces in one raise
+
+- **Every notice can be silenced.** A line is information once and noise the
+  tenth: the version that moved, the long-hour words, the next-steps block, the
+  hints. Each now says so **once** in the cloth's faint voice — *not again:
+  `ymir config notice version off`* — and the preference is recorded in the
+  operator's settings, honoured by the shell cloth and the CLI alike. `ymir config
+  show` is the door; four keys: `version · patience · next · hints`.
+- **The package carries the design system.** It never shipped `midgard/`, so the
+  rune glyphs — the icons themselves — were absent and every mark failed with
+  *no glyph ansuz*. `midgard/design-system/` is in `files[]` now: 30 files, 22
+  glyphs.
+- **The marks are written in the right order.** The apps' own launcher templates
+  landed *after* the rune marks and overwrote the themed name with an absolute
+  `.png`; the templates go first now and the rune marks stand over them.
+- **Óðrerir rises from a package.** Its published tarball carries `dist` and a
+  `dev` command that calls a script it does not carry, so `npm run dev` could never
+  work from a package — the hall serves its **build** (`astro preview`) where there
+  is one, exactly as the SPA does. And its dependencies' absence is no longer
+  silent: the hall says what failed and why.
+- **Four surfaces, one raise.** `ymir raise` lifts the SPA, Óðrerir, the board and
+  Sessrúmnir together; the installer's desktop step opens **one window per
+  surface**, not a single "both".
+- **A library must not end a function on a failing test.** `style_init` did, and
+  `scripts/start.sh` runs under `set -e` — so the cloth took the whole raise down
+  with it, silently. `return 0`, and the reason is written beside it.
+
+## 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,

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/design-icon.sh

@@ -75,8 +75,18 @@ mint() {  # <app-dir> <glyph> <tint> <label>
   local path
   path="$(sed -n 's/.*<path d="\([^"]*\)".*/\1/p' "$g" | head -1)"
   [ -n "$path" ] || { printf 'error: %s carries no <path> to reuse\n' "$glyph" >&2; return 1; }
-  local outdir="$ROOT/$dir/public"
-  [ -d "$(dirname "$outdir")" ] || { printf '  "%s","SKIP (no such app)"\n' "$dir"; return 0; }
+  # A clone keeps the app at $ROOT/apps/<name>; a package keeps it under
+  # node_modules/@zerwiz/<package>. The mint resolves both, so a packaged install
+  # gets its favicon too — the same resolver every other script uses.
+  local base outdir surface
+  base="$ROOT/$dir"
+  if [ ! -d "$base" ]; then
+    surface="$(basename "$dir")"
+    case "$surface" in smidja-factory) surface=smidja ;; esac
+    app_dir "$surface" base 2>/dev/null || base=""
+  fi
+  [ -n "$base" ] && [ -d "$base" ] || { printf '  "%s","SKIP (no such app)"\n' "$dir"; return 0; }
+  outdir="$base/public"
   mkdir -p "$outdir"
   {
     printf '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="%s">\n' "$label"
@@ -147,7 +157,12 @@ install_all() {
     printf '  "%s","%s.svg","%s.desktop"\n' "$iconname" "$iconname" "$iconname"
   done
   [ -f "$apps_dir/ymir-smidja.desktop" ] && rm -f "$apps_dir/ymir-smidja.desktop"
-  for stale in ymir-hlidskjalf-mobile; do rm -f "$apps_dir/$stale.desktop" "$icons_dir/$stale.svg"; done
+  # Names we have retired, swept on every install: a launcher entry that points at
+  # an icon nobody ships is a blank square, and the naming law does not let an old
+  # name linger beside the new one. (ymir-visualizer → ymir-smidja.)
+  for stale in ymir-hlidskjalf-mobile ymir-visualizer; do
+    rm -f "$apps_dir/$stale.desktop" "$icons_dir/$stale.svg"
+  done
   command -v update-desktop-database >/dev/null 2>&1 && update-desktop-database "$apps_dir" >/dev/null 2>&1 || true
 }
 

package/bin/desktop-place.sh

@@ -51,12 +51,17 @@ 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=("$APP_HLIDSKJALF/electron" "$APP_SESSRUMNIR/resources" "$APP_ODRERIR/electron")
@@ -195,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/ymir-config.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# ymir-config.sh — the operator's own preferences, honoured and remembered.
+#
+# Some lines a script prints are information the first time and noise the tenth:
+# the version that moved, the long-hour words, the hints. A user must be able to
+# say "not again" — once — and be believed. That is what this door is for.
+#
+#   ymir-config.sh show                       # every preference and its state
+#   ymir-config.sh notice <key> off|on        # silence or restore one notice
+#   ymir-config.sh notice <key>               # what it is now
+#
+# The store is the operator's settings, in the home they chose — never the code
+# tree (Rule 04) — one `key=on|off` line per name:
+#
+#   <home>/config/notices.conf
+#
+#   keys: version   the "the tree moved x → y" line
+#         patience  the long-hour words before a slow install or build
+#         next      the "where to go from here" block
+#         hints     the one-line helpers ("hide this next time: …")
+#
+# Exit: 0 ok, 2 usage.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/hoard-lib.sh
+. "$SCRIPT_DIR/hoard-lib.sh"
+hoard_settings_dir SETTINGS
+STORE="$SETTINGS/notices.conf"
+KNOWN="version patience next hints"
+
+usage() { sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'; }
+
+state_of() {  # <key> → on|off (absent = on)
+  local key="$1" line
+  [ -r "$STORE" ] || { printf 'on'; return 0; }
+  line="$(grep -m1 "^${key}=" "$STORE" 2>/dev/null || true)"
+  [ -n "$line" ] && printf '%s' "${line#*=}" || printf 'on'
+}
+
+set_state() {  # <key> <on|off>
+  local key="$1" value="$2" tmp
+  case "$value" in on|off) ;; *) printf 'error: %s is not on or off\nhelp: ymir config notice %s off\n' "$value" "$key" >&2; exit 2 ;; esac
+  mkdir -p "$SETTINGS" 2>/dev/null || { printf 'error: cannot write %s\n' "$SETTINGS" >&2; exit 1; }
+  tmp="$(mktemp)"; chmod 600 "$tmp"
+  if [ -r "$STORE" ]; then grep -v "^${key}=" "$STORE" >"$tmp" 2>/dev/null || true; fi
+  printf '%s=%s\n' "$key" "$value" >>"$tmp"
+  mv "$tmp" "$STORE"
+}
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+  show)
+    printf 'notices[%d]{key,state,what}:\n' 4
+    printf '  "version","%s","the line that says which version moved to which"\n' "$(state_of version)"
+    printf '  "patience","%s","the long-hour words before a slow install or build"\n' "$(state_of patience)"
+    printf '  "next","%s","the where-to-go-from-here block at the end"\n' "$(state_of next)"
+    printf '  "hints","%s","the one-line helpers that say how to hide a notice"\n' "$(state_of hints)"
+    printf 'store[1]{path}:\n  "%s"\n' "$STORE"
+    ;;
+  notice)
+    key="${2-}"; value="${3-}"
+    [ -n "$key" ] || { printf 'error: which notice?\nhelp: ymir config notice <version|patience|next|hints> off\n' >&2; exit 2; }
+    case " $KNOWN " in *" $key "*) ;; *) printf 'error: unknown notice %s\nhelp: one of: %s\n' "$key" "$KNOWN" >&2; exit 2 ;; esac
+    if [ -z "$value" ]; then
+      printf 'notices[1]{key,state}:\n  "%s","%s"\n' "$key" "$(state_of "$key")"
+    else
+      set_state "$key" "$value"
+      printf 'notices[1]{key,state}:\n  "%s","%s"\n' "$key" "$value"
+      [ "$value" = off ] && printf 'this notice will not be shown again — restore it with: ymir config notice %s on\n' "$key"
+    fi
+    ;;
+  *) printf 'error: unknown action %s\nhelp: bin/ymir-config.sh [show|notice <key> on|off]\n' "$1" >&2; exit 2 ;;
+esac

package/bin/ymir-install.sh

@@ -670,6 +670,13 @@ step_marks() {
     add marks OK "$n desktop app marks installed"
     return
   fi
+  # The apps' own launcher templates land first (the freedesktop half of desktop
+  # integration, for ANY Linux desktop), and the rune marks are minted and
+  # installed over them — so the themed rune name wins for the surfaces that have
+  # one, instead of a template's absolute .png.
+  if [ -x "$SCRIPT_DIR/desktop-place.sh" ]; then
+    "$SCRIPT_DIR/desktop-place.sh" entries >/dev/null 2>&1 || true
+  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
   [ -r "$HOME/.pi/agent/AGENTS.md" ] || [ -d "$HOME/.pi/agent" ] && {
@@ -720,10 +727,16 @@ step_desktop() {
     add desktop WARN "the Electron runtime is PARTIAL for:$partial — the web surfaces stand; approve and rebuild to launch the shells"
     return 0
   fi
-  if "$ROOT/scripts/electron.sh" start --both >/dev/null 2>&1; then
-    add desktop OK "raised Hlidskjalf + Smíðja"
+  # One window per surface that is here: the halls are not one app.
+  raised=0
+  for _v in hlidskjalf smidja odrerir; do
+    "$ROOT/scripts/electron.sh" start --view "$_v" >/dev/null 2>&1 && raised=$((raised+1))
+  done
+  [ -x "$ROOT/bin/sessrumnir.sh" ] && "$ROOT/bin/sessrumnir.sh" start >/dev/null 2>&1 && raised=$((raised+1))
+  if [ "$raised" -ge 2 ]; then
+    add desktop OK "raised $raised window(s) — Hlidskjalf · Smíðja · Óðrerir · Sessrúmnir"
   else
-    add desktop WARN "could not raise the desktop apps — run scripts/electron.sh start --both"
+    add desktop WARN "could not raise the desktop apps — ymir hlidskjalf | smidja | sessrumnir"
   fi
 }
 

package/bin/ymir-style.sh

@@ -38,6 +38,10 @@ style_init() {
   fi
   C_OFF=""
   [ "$STYLE_ON" = 1 ] && C_OFF=$'\033[0m'
+  # A sourced library must never end a function on a FAILING test: callers run
+  # under `set -e` (scripts/start.sh does), and the last command's status becomes
+  # the function's — so a caller raised the whole hall and died at the cloth.
+  return 0
 }
 
 # The forge's marks, one per state a thing can be in.
@@ -64,6 +68,23 @@ style_colour() {  # <state> → the colour for it
   esac
 }
 
+# --- preferences: a user must be able to say "not again", once --------------
+# The store is the operator's settings (see bin/ymir-config.sh); absent means on.
+notice_state() {  # <key> → on|off
+  local key="$1" store line
+  if [ -n "${YMIR_SETTINGS_DIR:-}" ]; then store="$YMIR_SETTINGS_DIR/notices.conf"
+  else store="${YMIR_HOME:-$HOME/Documents/Ymir}/config/notices.conf"; fi
+  [ -r "$store" ] || { printf 'on'; return 0; }
+  line="$(grep -m1 "^${key}=" "$store" 2>/dev/null || true)"
+  [ -n "$line" ] && printf '%s' "${line#*=}" || printf 'on'
+}
+notice_wanted() { [ "$(notice_state "${1-}")" != off ]; }
+notice_hint() {  # <key> — said once, and never when the hints are silenced
+  [ "$(notice_state hints)" = off ] && return 0
+  printf '%s
+' "${C_FAINT}      (not again: ymir config notice ${1-} off)${C_OFF}" >&2
+}
+
 # --- the pieces -------------------------------------------------------------
 
 # The mark: four lines at most. The WORDS show even in a pipe — only the colour
@@ -99,18 +120,21 @@ style_heading() { printf '\n%s%s%s\n' "$C_BRONZE" "$1" "$C_OFF" >&2; }
 # 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]
+  notice_wanted patience || return 0
   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."
+  notice_hint patience
   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"
+  notice_wanted next || return 0
   printf '\n%s\n' "${C_BOLD}Where to go from here${C_OFF}" >&2
   while [ $# -gt 0 ]; do
     local cmd="${1%% — *}" what="${1#* — }"