@zerwiz/ymir 0.1.9 → 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,58 @@
 
+## 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/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-install.sh

@@ -672,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
   }

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.9",
+  "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/start.sh

@@ -31,6 +31,7 @@ if [ -z "${YMIR_APP_LIB_LOADED:-}" ]; then
   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).
@@ -196,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"
@@ -211,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.
@@ -227,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}/"
@@ -241,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