@zerwiz/ymir 0.1.10 → 0.1.12

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

@@ -259,6 +259,35 @@ clone's marks already existed. `bin/desktop-place.sh entries` is the launcher ha
 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

package/CHANGELOG.md

@@ -1,4 +1,104 @@
 
+## 2026-09-17 — 0.1.12: the icons reach the live tree, and a missing surface is a failure
+
+- **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".
+
+## 2026-09-17 — the icons reach the live tree, and a missing surface is a failure
+
+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 skipped it
+  in another. Pinned to the exact version.
+
+Verified from his own install (`~/.npm-global`): Hlidskjalf `:3888`, Óðrerir
+`:4322`, the board `:8437`, the gate API `:3889` (401 — up, auth enforced), Nornir
+cron started, Bifrost and the well up, and the launcher entries naming the doors.
+
+## 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,

package/bin/app-lib.sh

@@ -38,7 +38,17 @@ app_dir() {  # <surface> <result-var> — a clone's apps/<x>, else the package
   _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
+  # Three shapes, and npm uses the third more than anyone expects:
+  #   a clone            apps/<surface>
+  #   a nested package   <pkg>/node_modules/@zerwiz/<package>
+  #   a SIBLING package  <prefix>/lib/node_modules/@zerwiz/<package> — beside ymir,
+  #                      where a global install puts a dependency it hoists out
+  # (the sibling is found through dirname, so no parent-climbing path is written)
+  for _apd_c in \
+    "$_apd_root/apps/$_apd_surface" \
+    "$_apd_root/node_modules/@zerwiz/$_apd_pkg" \
+    "$(dirname "$_apd_root")/$_apd_pkg"
+  do
     [ -d "$_apd_c" ] && { printf -v "$_apd_rv" '%s' "$_apd_c"; return 0; }
   done
   printf -v "$_apd_rv" '%s' ""

package/bin/design-icon.sh

@@ -43,11 +43,11 @@ ACTION="${1:-list}"; shift || true
 # dir|glyph|tint|says|icon-name|exec|wm-class
 # FIVE UI surfaces, FIVE DIFFERENT glyphs — no app borrows another's rune.
 APPS=(
-  "apps/hlidskjalf|ehwaz|#c9973f|the seat — Hlidskjalf, the high seat of the control plane|ymir-hlidskjalf|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf|Ymir · Hlidskjalf"
-  "apps/hlidskjalf-mobile|raidho|#c9973f|the road — the seat carried, Hlidskjalf on a phone|ymir-hlidskjalf-mobile|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf-mobile|Ymir · Hlidskjalf Mobile"
-  "apps/odrerir|ansuz|#c9973f|the mead — Óðrerir, the Live Hall (Odin's breath, inspiration)|ymir-odrerir|scripts/electron.sh start --view odrerir|ymir-odrerir|Ymir · Óðrerir"
-  "apps/sessrumnir|othala|#c9973f|the hall — Sessrúmnir, the seat that holds the cloth|ymir-sessrumnir|bin/sessrumnir.sh start|ymir-sessrumnir|Ymir · Sessrúmnir"
-  "apps/smidja-factory/apps/visualizer|kaunan|#f59e0b|the torch — the forge's eye, Smíðja's trace|ymir-smidja|scripts/electron.sh start --view smidja|ymir-smidja|Ymir · Smíðja"
+  "apps/hlidskjalf|ehwaz|#c9973f|the seat — Hlidskjalf, the high seat of the control plane|ymir-hlidskjalf|ymir hlidskjalf|ymir-hlidskjalf|Ymir · Hlidskjalf"
+  "apps/hlidskjalf-mobile|raidho|#c9973f|the road — the seat carried, Hlidskjalf on a phone|ymir-hlidskjalf-mobile|ymir hlidskjalf|ymir-hlidskjalf-mobile|Ymir · Hlidskjalf Mobile"
+  "apps/odrerir|ansuz|#c9973f|the mead — Óðrerir, the Live Hall (Odin's breath, inspiration)|ymir-odrerir|ymir odrerir|ymir-odrerir|Ymir · Óðrerir"
+  "apps/sessrumnir|othala|#c9973f|the hall — Sessrúmnir, the seat that holds the cloth|ymir-sessrumnir|ymir sessrumnir|ymir-sessrumnir|Ymir · Sessrúmnir"
+  "apps/smidja-factory/apps/visualizer|kaunan|#f59e0b|the torch — the forge's eye, Smíðja's trace|ymir-smidja|ymir smidja|ymir-smidja|Ymir · Smíðja"
 )
 
 list() {
@@ -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"
@@ -105,11 +115,11 @@ icons_dir="$data_home/icons/hicolor/scalable/apps"
 apps_dir="$data_home/applications"
 # app | entry name | Exec | StartupWMClass
 ENTRIES=(
-  "hlidskjalf|Ymir · Hlidskjalf|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf"
-  "odrerir|Ymir · Óðrerir|scripts/electron.sh start --view odrerir|ymir-odrerir"
-  "sessrumnir|Ymir · Sessrúmnir|bin/sessrumnir.sh start|ymir-sessrumnir"
-  "visualizer|Ymir · Smíðja|scripts/electron.sh start --view smidja|ymir-smidja"
-  "hlidskjalf-mobile|Ymir · Hlidskjalf Mobile|scripts/electron.sh start --view hlidskjalf|ymir-hlidskjalf-mobile"
+  "hlidskjalf|Ymir · Hlidskjalf|ymir hlidskjalf|ymir-hlidskjalf"
+  "odrerir|Ymir · Óðrerir|ymir odrerir|ymir-odrerir"
+  "sessrumnir|Ymir · Sessrúmnir|ymir sessrumnir|ymir-sessrumnir"
+  "visualizer|Ymir · Smíðja|ymir smidja|ymir-smidja"
+  "hlidskjalf-mobile|Ymir · Hlidskjalf Mobile|ymir hlidskjalf|ymir-hlidskjalf-mobile"
 )
 install_all() {
   # A phone app gets an icon for its own bundle, never a desktop entry.
@@ -139,7 +149,10 @@ install_all() {
       printf '[Desktop Entry]\nType=Application\nVersion=1.0\n'
       printf 'Name=%s\n' "$display"
       printf 'Comment=%s\n' "$says"
-      printf 'Exec=bash %s/%s\n' "$ROOT" "$exec"
+      # The door, never a path: a launcher entry outlives the tree that wrote it,
+      # and `ymir <door>` reaches whichever install is live. (The CLI is on PATH
+      # from npm's global bin, and from bin/ in a clone — ymir.js is a bin entry.)
+      printf 'Exec=%s\n' "$exec"
       printf 'Icon=%s\n' "$iconname"
       printf 'Terminal=false\nCategories=Development;Utility;\n'
       printf 'StartupWMClass=%s\nStartupNotify=true\n' "$klass"
@@ -147,7 +160,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/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,15 +670,15 @@ step_marks() {
     add marks OK "$n desktop app marks installed"
     return
   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.
+  # 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" ] && {
     ln -sfn "$ROOT/AGENTS.md" "$HOME/.pi/agent/AGENTS.md" 2>/dev/null || true
   }
@@ -727,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#* — }"

package/bin/ymir.js

@@ -54,8 +54,20 @@ const bold = wrap('1');
 // 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 noticeState(key) {
+  try {
+    const s = process.env.YMIR_SETTINGS_DIR
+      || path.join(process.env.YMIR_HOME || path.join(require('node:os').homedir(), 'Documents', 'Ymir'), 'config');
+    const f = path.join(s, 'notices.conf');
+    if (!fs.existsSync(f)) return 'on';
+    const line = fs.readFileSync(f, 'utf8').split('\n').find((l) => l.startsWith(key + '='));
+    return line ? line.slice(key.length + 1).trim() : 'on';
+  } catch { return 'on'; }
+}
+
 function versionNotice() {
   try {
+    if (noticeState('version') === 'off') return;
     const f = path.join(STATE_DIR, 'version');
     const seen = fs.existsSync(f) ? fs.readFileSync(f, 'utf8').trim() : '';
     if (seen === pkg.version) return;
@@ -64,7 +76,9 @@ function versionNotice() {
     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`));
+      faint(`  run \`ymir eir\` to see what stands, \`ymir raise\` to lift the hall\n`) +
+      (noticeState('hints') === 'off' ? '' : faint(`      (not again: ymir config notice version off)\n`)) +
+      '\n');
   } catch { /* a version notice must never break a door */ }
 }
 
@@ -83,6 +97,7 @@ const DOORS = {
   hlidskjalf: { script: 'scripts/electron.sh',    about: "the high seat's window", args: ['start', '--view', 'hlidskjalf'] },
   sessrumnir: { script: 'scripts/electron.sh',    about: "the seat-hall's window", args: ['start', '--view', 'sessrumnir'] },
   mimir:      { script: 'bin/mimir.sh',           about: 'the memory well' },
+  config:     { script: 'bin/ymir-config.sh',     about: 'your preferences — which notices are shown (stay silent with `notice <key> off`)' },
   sense:      { script: 'bin/host-sense.sh',      about: 'what THIS machine is' },
   plan:       { script: 'bin/ymir-plan.sh',       about: 'what an install would do here — writes nothing' },
   migrate:    { script: 'bin/ymir-migrate.sh',    about: "heal this home's structure forward (Gr\u00f3a's mend)" },

package/midgard/README.md

@@ -0,0 +1,16 @@
+# MIDGARD — Shared Design Assets
+
+Cross-tenant assets that are **public by design**: the design system and the
+shared libraries any realm may pull.
+
+**What does NOT belong here.** Company knowledge — policies, vision, specs,
+client names, wiki pages. That is tenant data, scoped per company, and lives at
+`$YMIR_HOME/hodd/identity/companies/`. This repo is public; a company wiki in it
+would publish that company's internals.
+
+## Contents
+- `design-system/` — shared UI components, design tokens, icon set
+- `shared-packages/` — internal npm/cargo/python libraries (public)
+- `infrastructure/` — shared Terraform / Docker / Kubernetes configs
+- `github_org_repos/` — central repositories
+  - `shared-core-api/` — example shared repo (with `.yggdrasil/` worktrees)

package/midgard/design-system/ember.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Type declarations for the shared hearth (ember.js).
+ *
+ * The implementation is plain JS so any surface — React, Vue, Astro, or a bare
+ * page — can import the same fire. These types keep TypeScript consumers honest
+ * without forcing the module itself into a build step.
+ */
+
+/** Start the hearth on <host> (a canvas, or an element to receive one). Returns a stop function. */
+export function startEmbers(host: Element | null): () => void;
+
+/** Light every element marked `data-ember`. Returns one stop function per hearth. */
+export function startAllEmbers(root?: ParentNode): Array<() => void>;