@zerwiz/ymir 0.1.4 → 0.1.7

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

@@ -0,0 +1,69 @@
+# Install & plan the host — what this machine will become, and where its things live
+
+> **Purpose:** the host-side door to the install. Galdr's
+> `assets/installation.md` is the map of every step; this page is what the
+> *operator of the machine* needs: read the plan before anything changes, and know
+> which root holds what.
+
+## Read the plan before the install touches anything
+
+The install no longer asks with a recited paragraph — it prints a plan **probed on
+this host**, one row per step, each with its state and the reason for it.
+
+```bash
+bin/ymir-plan.sh                # the plan (TOON)
+bin/ymir-plan.sh --blocked      # only what cannot proceed, and why
+bin/ymir-plan.sh --json         # for automation
+bin/ymir-install.sh --plan      # the same, through the installer's door
+```
+
+```
+plan_states[5]{state,means}:
+  "DO","a change will be made"
+  "SKIP","already satisfied — nothing to do"
+  "INFO","a fact about this host, discovered"
+  "BLOCKED","cannot run — the reason names what is missing"
+  "CONSENT","needs the operator's word"
+```
+
+A `BLOCKED` row is a fact, not a failure: the plan exits 0 and prints it. The
+phase-1 `purity` row is the one to read first on a packaged install — it names
+anything of the operator's left in the code tree.
+
+## The home is the operator's to choose
+
+A real interactive install asks once, and records the answer as machine state:
+
+```bash
+~/.config/ymir/home      # the home chosen at installation (a path)
+```
+
+Resolution order, always through `bin/hoard-lib.sh`:
+`$YMIR_HOME` → the recorded choice → `$HOME/Documents/Ymir` (the one documented
+default). `--check` never writes. `--yes` takes what is recorded, else the default.
+
+To move an existing home to a new place, re-run the install with the new value:
+
+```bash
+YMIR_HOME=/path/to/new-home bin/ymir-install.sh
+```
+
+## Which root holds what
+
+```
+roots[6]{root,resolver,holds}:
+  "home","ymir_home_root","everything the operator owns"
+  "hoard","hoard_root","docs · secrets · identity · tenants · memory"
+  "records","hoard_data_dir","operator · fleet · machines · the host profile"
+  "state","hoard_state_dir","pids · logs · locks · caches (ephemeral)"
+  "settings","hoard_settings_dir","agents.yaml · cron.yaml · tailscale-sync · the wedge channel"
+  "credentials","hoard_local_env","$YMIR_HOME/.env.local — auth, OAuth keys, tokens"
+```
+
+**The law:** the package is the **code that runs the programs**. Everything the
+operator owns lives in the home. A packaged install replaces its tree on upgrade —
+so anything of theirs kept in the tree is kept at its peril, which is exactly what
+the plan's `purity` row exists to catch.
+
+**Rule for a new host feature:** resolve every path through `bin/hoard-lib.sh`;
+never name `$ROOT/data`, `$ROOT/state`, `$ROOT/config` or `$ROOT/.env.local`.

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

@@ -0,0 +1,297 @@
+---
+name: ymir-omarchy
+description: >-
+  Omarchy-native operation for Ymir. REQUIRED whenever the task touches the host
+  desktop: Hyprland, the Omarchy shell/bar, themes, monitors, window rules,
+  keybindings, idle/lock, night light, screenshots, reminders, or any file under
+  ~/.config/hypr/ or ~/.config/omarchy/. Also use when placing the Ymir desktop
+  apps (Hlidskjalf / Smíðja) on a screen, when a native crash involves the GPU or
+  Wayland, and to help the Allfather set up or tune the Omarchy machine Ymir runs
+  on. Load this before editing any ~/.config/ file on an Omarchy host.
+allowed-tools: read,write,bash,glob,grep
+---
+
+# Ymir on Omarchy
+
+Ymir runs *on* Omarchy — an opinionated Arch Linux + Hyprland distribution. On an
+Omarchy host, the desktop is not a detail: it decides where our windows land, how
+they render, and whether the GPU process survives. This skill is how Ymir is a
+good citizen of that machine.
+
+**Router:** `.agents/skills/galdr-ymirsystem/SKILL.md`. **Upstream skill (authoritative for
+Omarchy itself):** `/usr/share/omarchy/default/agents/skills/omarchy/SKILL.md` and
+`~/.pi/agent/skills/omarchy/`. Read that one for pure Omarchy work; this one adds
+the Ymir integration and the hard-won facts below.
+
+## The two laws
+
+```
+omarchy_laws[2]{id,law}:
+  "1","Never edit anything under /usr/share/omarchy/ — it is package-owned and overwritten on update. Reading it is safe and encouraged. Edit ~/.config/ instead."
+  "2","Hyprland owns window placement, not the app. Let the compositor place windows; the app must not fight it."
+```
+
+## Detecting the host
+
+```bash
+# Are we on Omarchy at all? (never assume)
+[ -d /usr/share/omarchy ] && echo "Omarchy host"
+omarchy version 2>/dev/null || true
+hyprctl monitors -j 2>/dev/null | head -c 200
+```
+
+Ymir must work on a non-Omarchy host too. Every Omarchy-specific behaviour is
+gated on `[ -d /usr/share/omarchy ]`; nothing here may break a plain Arch box.
+
+## Monitors, scale, and the coordinate trap
+
+**The fact that costs the most time:** on Omarchy the panel may run at a
+fractional scale (e.g. a 1920×1200 panel at `scale 1.5` is a **1280×800 logical**
+desktop). An app that computes window geometry from *physical* pixels will be
+wrong by the scale factor and will fill the whole screen.
+
+```bash
+hyprctl monitors -j        # name, id, width, height, scale, focused, x, y
+```
+
+- `hyprctl` reports **physical** width/height **and** `scale`.
+- Electron's `screen` API reports **logical** (already-scaled) bounds.
+- Logical = physical / scale. Never mix the two.
+
+### Placing the Ymir desktop apps
+
+Hlidskjalf and Smíðja are dashboards the Allfather keeps *beside* his work, so
+they belong on a **non-primary** display when one is attached, and on the primary
+when it is not (the laptop case). Two rules:
+
+1. **Prefer a secondary display**, never the focused/primary one, when
+   `screen.getAllDisplays().length > 1`.
+2. **Clamp to the display's work area** in *logical* units, and center there. A
+   window wider than the logical desktop must be shrunk, not pushed off-screen.
+
+Identity of a display is its `id`; `screen.getPrimaryDisplay()` is the one to
+avoid. If only one display exists, do nothing clever — center it and move on.
+
+## The GPU / Wayland crash (amdgpu)
+
+Observed on this class of machine (AMD Cezanne iGPU with a **512 MB** VRAM
+carve-out, plus a discrete NVIDIA card):
+
+```
+kernel: amdgpu 0000:08:00.0: [drm] *ERROR* Not enough memory for command submission!
+electron[PID]: segfault at 0 error 4 in electron
+```
+
+Electron's `--type=gpu-process` dies with `SIGSEGV` when the iGPU cannot satisfy a
+command submission. It is **not** an Electron bug in our code and **not** an OOM
+(it happens with plenty of system RAM). Diagnose it properly:
+
+```bash
+coredumpctl list | grep electron          # a pattern, or a one-off?
+journalctl --since "<t-1min>" --until "<t+1min>" | grep -i 'amdgpu\|drm\|segfault'
+cat /sys/class/drm/card*/device/mem_info_vram_used   # VRAM actually in use
+```
+
+**Mitigation for dashboards** (they are not 3D apps):
+
+```bash
+YMIR_DESKTOP_DISABLE_GPU=1 scripts/electron.sh start --both   # software rendering
+```
+
+`scripts/electron.sh` reads that variable and adds `--disable-gpu
+--disable-gpu-compositing`. Use it on a small-VRAM iGPU; leave GPU on where the
+discrete card drives the display.
+
+## Starting the Ymir apps
+
+```bash
+scripts/electron.sh start --both        # Hlidskjalf + Smíðja, separate apps
+scripts/electron.sh status              # is each one REALLY running?
+scripts/electron.sh stop
+```
+
+**Do not track an Electron app by the pid returned from `.bin/electron`** — that
+is a node shim which *spawns* the real binary, so the pid is wrong and a second
+launch will stack on the first. Track it by its own command line (the per-view
+`--user-data-dir` is the stable identity), which is what `electron.sh` does.
+
+## Safe customisation (the short version)
+
+| Want | Do |
+|---|---|
+| Bar / widgets / idle | edit `~/.config/omarchy/shell.json`, then `omarchy restart shell` |
+| Keybindings, gaps, monitors | edit `~/.config/hypr/*.lua`, then `hyprctl reload` + `hyprctl configerrors` |
+| Theme | `omarchy theme set <name>`; customise in `~/.config/omarchy/themes/<name>/` |
+| Reminder | `omarchy reminder <minutes> "text"` |
+| Screenshot / record | `omarchy capture screenshot` · `omarchy screenrecord --fullscreen` |
+| Night light | `omarchy toggle nightlight` |
+| Lock after idle | `idle.lock` in `~/.config/omarchy/shell.json` |
+| Install a package | `omarchy pkg add <pkg>` (AUR: `omarchy pkg aur add <pkg>`) |
+| Debug | `omarchy debug --no-sudo --print` (always these flags) |
+
+Always back up a config before editing it: `cp f f.bak.$(date +%s)`.
+
+## Discovery
+
+```bash
+omarchy commands                 # every documented command
+omarchy <group> --help           # omarchy theme|refresh|restart|toggle|bar|...
+omarchy commands --json          # machine-readable
+cat $(which omarchy-theme-set)   # read a command's source (safe)
+```
+
+## Being useful to an Omarchy user
+
+When the Allfather wants his machine set up or tuned, Ymir should *help* rather
+than merely not-break: report the monitor layout and scale, propose a sane window
+placement for the dashboards, offer the GPU mitigation when the iGPU is small,
+and use `omarchy` commands rather than raw edits wherever one exists. Offer a
+backup before every config change, and never run `omarchy refresh <x>` (which
+resets config) without explicit confirmation.
+
+## The editor (Pi's `/edit`)
+
+Pi ships a user-facing **Open Editor** extension (`.pi/extensions/open-editor.ts`) that
+opens files from the working directory in the Allfather's own editor. It is
+**strictly his** — no LLM tool is registered, because agents already have `read`
+and `edit`. Know it, name it when he would reach for it, and never try to drive it
+yourself.
+
+```
+editor_surface[2]{key,what}:
+  "/edit [path]","slash command with tab-completion over cwd files; no path opens the directory itself"
+  "ctrl+shift+e","file picker over cwd"
+```
+
+**How the editor resolves:** `$VISUAL` → `$EDITOR` → **the first editor that
+actually exists** on the host, tried in this order: `code cursor zed subl nvim vim
+hx helix nano micro emacs vi`. A **terminal** editor (nvim, vim, helix, nano,
+emacs) blocks Pi while open — the TUI suspends and resumes on exit. A **GUI**
+editor (code, cursor, zed, subl) launches detached, so Pi stays interactive.
+
+**Why the existence check matters off Omarchy:** the old fallback was a bare `vi`,
+and `vi` is **absent on this very machine** — as it is on many minimal hosts. A
+configured editor that is not installed no longer poisons the chain: the extension
+probes `$PATH` and falls through to one that is real. So `/edit` works on a plain
+Arch box, a Debian box, or anything else where Omarchy's launcher does not exist.
+
+### Choosing the editor (Omarchy forces its own)
+
+Omarchy **hard-sets** `EDITOR` twice — `${EDITOR:-omarchy-launch-editor --inline}`
+in `default/bash/envs`, and a forced value in `default/uwsm/default`. A user
+override therefore goes in the uwsm user dir, which is sourced **after** the
+defaults:
+
+```
+~/.config/uwsm/env.d/10-ymir-editor:
+  export EDITOR="code"       # a GUI editor, so no --wait: it launches detached
+  export VISUAL="code"
+```
+
+(`--wait` is wrong for a GUI editor — VS Code hands the file to the running
+instance and exits, so waiting holds nothing.) Changes need a session restart.
+
+### The editor gets its own desktop
+
+The editor must not open on the desktop the Allfather is reading. Hyprland applies
+window rules **at map time**, so the window never appears there at all:
+
+```
+bin/editor-place.sh plan      # which desktop it would take
+bin/editor-place.sh apply     # write the rule + hyprctl reload
+```
+
+It writes into the SAME `~/.config/hypr/ymir-desktops.lua` the apps use (so one
+file owns every Ymir window placement) and re-derives the app rules rather than
+clobbering them:
+
+```lua
+o.window({ class = "^code$" }, { workspace = "7", no_focus = true })
+```
+
+**`no_focus = true` is the load-bearing half.** Without it the window is placed on
+the right desktop but **the focus follows it** — the Allfather is dragged off his
+own desk. Omarchy's own `default/hypr/windows.lua` uses the same idiom. Always
+verify with `hyprctl configerrors` (must be empty) after a reload.
+
+**The dispatch road does NOT work here.** This Hyprland (0.56) replaced the classic
+dispatch interface with a Lua API: `hyprctl dispatch movetoworkspacesilent
+5,class:...` fails outright, and `keyword` reports "can't work with non-legacy
+parsers — use eval". The map-time rule file is the road that holds.
+
+When the Allfather wants to *look at* a file rather than have it read aloud, the
+answer is `/edit <path>` — say so plainly instead of pasting its contents.
+
+## Ymir speaks on the desktop
+
+Ymir works for hours unwatched, so when something is worth knowing it says so
+where the Allfather already is. `bin/ymir-say.sh` is the **single owner** of that
+manner — anything with news calls it, so the voice cannot drift.
+
+```
+bin/ymir-say.sh "<headline>" ["<body>"]            # a plain note
+bin/ymir-say.sh --mark-done  "<what>" ["<detail>"] # a job finished (low urgency)
+bin/ymir-say.sh --mark-alarm "<what>" ["<detail>"] # needs his word (critical)
+bin/ymir-say.sh --mark-fail  "<what>" ["<detail>"] # something broke (critical)
+bin/ymir-say.sh status                              # what has been said
+```
+
+It speaks through Omarchy's own notifier (`omarchy-notification-send`) when
+present, else `notify-send`, and always records the line in
+`state/ymir-said.log` — so a popup missed is a line still found. On a host with
+neither, the line is recorded and it says "record only"; a silent host is never a
+lost message.
+
+**Who speaks through it:** the wedge alarm (`bin/wedge-notify.sh`, when an
+escalation cannot reach a wedged pane) and the crash watcher (`bin/crash-sense.sh`, a
+new `coredumpctl` entry). Both route to `ymir-say.sh` so urgency, glyph, and app
+identity stay one voice.
+
+## Maintaining this
+
+- **Owner:** Brokk. **Router:** `.agents/skills/galdr-ymirsystem/SKILL.md`.
+- Upstream Omarchy skill is authoritative for Omarchy itself; keep only Ymir's
+  integration facts and this machine's hard-won lessons here.
+- When the desktop behaviour changes, update this asset and
+  `assets/hlidskjalf-ui.md` together.
+
+## Platform layers (Rule 05)
+
+Ymir is **Omarchy-first**, not Omarchy-only. The core is portable; Omarchy is the
+first-class installation layer on top of it. Anything below that assumes Hyprland
+or `/usr/share/omarchy` is this layer's business and is gated on the host — on a
+Mac or on WSL those steps report a clean skip and the core still runs.
+
+When a core feature changes, this layer is updated in the same change
+(`RULES/05-platforms.md`). Details: `galdr-ymirsystem/assets/installation.md`.
+
+### Electron GPU-process crashes on the shared-memory iGPU
+
+Both dashboards can look healthy while `coredumpctl` fills with SIGSEGV cores
+from `electron --type=gpu-process` and the kernel logs `amdgpu … Not enough
+memory for command submission`. Only the GPU process dies, so the failure is
+easy to miss.
+
+The iGPU backs its graphics memory with system RAM (GTT), and a local model
+served on that same iGPU holds several GiB of it — after which the driver fails
+the desktop's command submissions. `scripts/electron.sh` now detects a small VRAM
+carve-out (`igpu_vram_small()`, threshold `YMIR_IGPU_VRAM_SMALL_MIB`, default
+2048) and runs the dashboards on software rendering; `YMIR_DESKTOP_DISABLE_GPU`
+forces either path. Detail and the evidence: `galdr-ymirsystem/assets/hlidskjalf-ui.md`.
+
+### Speed-starts for the Ymir apps
+
+The launcher entries alone are not a speed start: reaching Hlidskjalf meant
+opening the app menu. Two keys now raise them, generated by
+`bin/desktop-place.sh apply` into `~/.config/hypr/ymir-launchers.lua` and
+required from `hyprland.lua` like the placement rules:
+
+| Key | App |
+|---|---|
+| **SUPER + Y** | Ymir Hlidskjalf |
+| **SUPER + M** | Ymir Smiðja |
+
+They live in their own file on purpose: `editor-place.sh` regenerates
+`ymir-desktops.lua` and preserves only window rules, so binds placed there would
+be dropped. Both keys were verified free before use (`omarchy menu keybindings
+--print`), and the behaviour is a plain Omarchy `o.bind(label, command)`.

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

@@ -0,0 +1,15 @@
+# Operator runbooks
+
+Task-oriented guides under `docs/runbooks/`, written for the operator:
+
+```
+runbooks[5]{path,load_when}:
+  "docs/runbooks/models.md","choose models per agent; local vs hosted; per-machine overlays"
+  "docs/runbooks/agents.md","Eindri profiles: home, add, run, dispatch"
+  "docs/runbooks/tailscale-sync.md","sync pi data across your own machines over Tailscale"
+  "docs/runbooks/updates-and-migrations.md","update the runtime; heal old homes (ymir-migrate)"
+  "docs/runbooks/secrets-and-hoard.md","Hodd: secrets by path, secret-guard, rotation + scrub"
+```
+
+Index: `docs/runbooks/README.md`. When a host task has an operator-facing
+procedure, add a runbook there and a row here.

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

@@ -0,0 +1,220 @@
+---
+name: ymir-thjazi
+description: >-
+  Þjazi — the terminal backend that hosts Ymir's agent panes. Use when spawning,
+  supervising, or debugging Eindri workers and presentation spaces, when choosing
+  or verifying the herdr/tmux backend, when herdr is missing or too old to install
+  or upgrade it, or when presentation spaces (herdr 0.8.0+) are involved. Load
+  before changing backend selection, pane layout, or spawn behaviour.
+allowed-tools: read,write,bash,glob,grep
+---
+
+# Þjazi — the terminal backend
+
+Þjazi is the giant who carries the gods' errands across the mountains; the backend
+that carries Ymir's agents across terminal panes. In the code it is **herdr** (and
+its verified reference sibling **tmux**). This skill is how Ymir is a
+herdr-first system without breaking on a tmux-only host.
+
+**Router:** `.agents/skills/galdr-ymirsystem/SKILL.md`.
+
+## Raising an Eindri (the two roads)
+
+An **Eindri** is a delegated hand (AGENTS.md; `docs/lore.md` §II — Brokk works the
+bellows, Eitri/Eindri works the craft). Two roads seat one, and each fits its own
+country. `bin/herdr-run.sh` is the runner; `bin/eindri-role.sh` names the smith.
+
+```
+herdr_roads[2]{road,shape,use_when}:
+  "tab","one tab in this home's workspace (durable, the default)","the work outlasts the moment — a task with an artifact"
+  "space","a disposable workspace holding exactly this one errand, gone when it ends","the errand should leave no trace in the workspace you are living in"
+```
+
+**A tab is a tab, not a pane split.** Brokk's grain — and now ours — is that a
+worker takes its **own tab in the home's workspace**, never a slice of yours. Your
+pane keeps its width; the smith sits beside your tabs, reachable with a tab switch.
+
+```
+bin/herdr-run.sh available                      # reach herdr? which session/workspace?
+bin/herdr-run.sh worth-a-smith "<errand>"       # THE FIRST LAW (see below)
+bin/herdr-run.sh eindri -- "<task>"             # the RIGHT smith, seated in a TAB
+bin/herdr-run.sh eindri --space -- "<task>"     # ...or in a disposable WORKSPACE
+bin/herdr-run.sh eindri sindri -- "<task>"      # name the smith explicitly
+bin/herdr-run.sh eindri --role huginn -- "<task>"
+bin/herdr-run.sh run <name> -- <command...>     # a command in a tab (not an agent)
+bin/herdr-run.sh agent-status                   # who stands, and in what state
+bin/herdr-run.sh status                         # what seats we recorded
+bin/herdr-run.sh close-all                      # clear the tabs/workspaces we made
+```
+
+**Quoting into a pane.** A pane runs its command through a *shell*, so `run`
+quotes every argument on the way in (`printf '%q'`). Without that, an argument
+containing spaces reached the pane as separate words and the command died on its
+own second word — `--brief "the whole task"` arrived as `--brief the whole task`
+and the worker answered `error: unknown arg: the`. Quote normally at the call
+site; the bridge preserves it.
+
+### The first law — a short errand is done in hand
+
+A smith costs a context, a seat, and the Allfather's attention. So an errand is
+weighed before it is seated:
+
+- **A question is answered in hand.** "What is the pid?" "Why did it fail?" —
+  answered directly, never seated.
+- **A one-line check is done in hand.** Brevity is not a task.
+- **A task earns a smith** — work with an artifact: build, fix, implement, port,
+  research, audit, plan, document, review.
+
+`worth-a-smith` decides, and `eindri` refuses to seat a smith for a question or a
+trifle. Ask it first when you are unsure.
+
+### The projection floor
+
+A disposable workspace needs **herdr 0.8.0+** (protocol 19). Below that floor a
+workspace-emptying close can steal the active workspace, so `--space` falls back
+to a tab and says so, rather than risking your focus. `available` reports
+`space_ok` for the running release.
+
+### The law of the runner
+
+Inside herdr the work is shown in its own tab or workspace; outside herdr it runs
+**inline — the same result, no seats** — and if a seat cannot be raised the
+command runs in place, so no work is ever lost to the theatre.
+`YMIR_HERDR_PANES=0` forces inline anywhere.
+
+### Session routing (a trap worth naming)
+
+`HERDR_SESSION` alone is **not** a reliable router: with another herdr server
+bound on the machine, a command silently reaches the wrong one. The runner always
+passes the trailing `--session <name>` flag, which routes correctly. (Brokk's
+`docs/herdr-backend.md` owns the evidence.)
+
+## The right smith for the right task
+
+An Eindri is a delegated hand (AGENTS.md; `docs/lore.md` §II: Brokk works the
+bellows, Eitri/Eindri works the craft). The wrong smith for the metal produces
+bad work, so the role is chosen deliberately:
+
+```
+eindri_roles[8]{role,craft}:
+  "sindri","code — build, refactor, fix, test"
+  "bragi","content — marketing, SEO, social"
+  "huginn","research — search, analyse, discover"
+  "kvasir","scout — recon a codebase before work"
+  "mimir","plan — design the approach"
+  "snotra","document — prose, guides, references"
+  "forseti","review — judge the work"
+  "galdr","runtime — the Ymir distro itself"
+```
+
+```
+bin/eindri-role.sh list                 # the roster
+bin/eindri-role.sh choose "<task text>" # the craft that fits
+bin/eindri-role.sh for <role>           # exact lookup
+```
+
+A named role wins; otherwise the craft is read from the errand itself ("write a
+blog post" → `bragi`; "fix the login bug" → `sindri`). Several may stand at once.
+
+## Ymir is herdr-first
+
+At install, Ymir guarantees a terminal backend exists. The order is:
+
+```
+backend_priority[3]{rank,backend,note}:
+  "1","herdr","Þjazi — preferred; carries protocol + presentation spaces"
+  "2","tmux","the verified reference backend; always acceptable"
+  "3","none","spawn is refused with a plain reason — never a silent fallback"
+```
+
+Selection is by config/env, in this order:
+
+```bash
+config/backend          # repo-level choice, if present
+BROKK_BACKEND           # env override
+HERDR_ENV=1             # set inside a herdr pane
+# else: tmux when available
+```
+
+## Verify before you trust
+
+```bash
+command -v herdr && herdr --version          # e.g. herdr 0.8.2
+echo "$BROKK_BACKEND"                         # explicit choice, if any
+```
+
+**Protocol floors** — check the version, not just the presence:
+
+| Capability | Minimum |
+|---|---|
+| Agent panes (spawn/supervise) | Þjazi protocol **14+** |
+| Presentation spaces | herdr **0.8.0+** |
+
+A present-but-too-old herdr is a **failure**, not a fallback: refuse the capability
+with a plain reason rather than degrading silently.
+
+## Installing and upgrading
+
+`bin/herdr-ensure.sh` (when present) is the single owner of provisioning; it
+detects, installs when absent, and verifies the reported version. The pinned,
+SHA-verified installer for the CI lane is `.agents/backend/fm-install-herdr.sh`
+— it installs an **exact** version from official release assets, verifies SHA-256,
+and refuses to finish unless the binary reports the pinned version and the
+required protocol. Never install a floating "latest" for the pinned lane.
+
+```bash
+# CI/pinned lane (exact version + protocol check) — signature: <destination-dir>
+.agents/backend/fm-install-herdr.sh "$HOME/.local/bin"
+
+# User-space, if the helper is present
+bin/herdr-ensure.sh status
+bin/herdr-ensure.sh ensure --install
+```
+
+Opting out of presentation spaces (they are presentation-only, never correctness)
+is done with `config/herdr-presentation-spaces` — see AGENTS.md.
+
+## What the backend actually does
+
+- **Spawn** carries an Eindri into an isolated pane, on top of an isolated
+  Yggdrasil worktree, optionally inside Utgard. It prints one line:
+  `spawned <id> harness=<h> kind=<ship|scout> [mode=<m> yolo=<y>] backend=<b> target=<t> worktree=<wt> isolation=<on|off>`
+- **Supervision** keeps one pane per worker and observes it; the Pi/OpenCode
+  extensions own continuity — never background the watcher arm by hand.
+- **Presentation spaces** (herdr 0.8.0+) give a worker a shareable view; they are
+  presentation, not a control channel.
+
+## Debugging
+
+```bash
+scripts/electron.sh status        # if the app surface is the question
+bin/backend/* or bin/einherjar-spawn.sh --help    # spawn contract
+# one pane, one worker: a second spawn for the same id must be refused
+```
+
+If workers vanish, compare the spawn line's `backend=` against the intended
+backend selection above — a tmux fallback on a herdr-first host is a
+misconfiguration, not a mystery.
+
+## Maintaining this
+
+- **Owner:** Brokk. **Router:** `.agents/skills/galdr-ymirsystem/SKILL.md`.
+- Source of truth for the backend spec: `assets/brokk-distro-runtime.md` (backends)
+  and `assets/pi-boot-guide.md` (pane supervision). Keep this skill's floors in
+  sync with those when the protocol advances.
+
+## The seat hierarchy (panes · tabs · spaces)
+
+herdr is `Session > Workspace > Tab > Pane`. An Eindri can be seated at each rung,
+chosen by `bin/eindri-start.sh` / `bin/herdr-run.sh eindri`:
+
+| flag | rung | road | when |
+|------|------|------|------|
+| *(default)* | **pane** | `herdr pane split <pane> --direction right` | the companion — an Eindri beside the work; splits the current pane inside herdr, else this home's active pane |
+| `--tab` | **tab** | `herdr tab create` | a separate view in this workspace |
+| `--space` | **workspace** | `herdr workspace create` | a disposable space for one errand (needs the 0.8.0 floor) |
+
+All three roads then `herdr agent start <name> --kind <kind> --pane <pane>` and
+`herdr agent prompt`. Use panes by default so agents are visible side by side,
+tabs to group parallel work, spaces to isolate an errand. `herdr-run.sh close-all`
+tears the recorded seats down.

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

@@ -0,0 +1,64 @@
+---
+name: ymir-update
+description: >-
+  Self-update a running Brokk and its eindri-homes to the latest from origin.
+  Use when the Allfather invokes /updateBrokk (e.g. "/updateBrokk", "update Brokk", "pull the latest Brokk").
+  Fast-forwards this Brokk repo's default branch and every local or remote Eindri-home through its guarded update path (never forced, never disruptive), then re-reads AGENTS.md and nudges each updated Eindri-home to do the same, so the whole tree runs the latest bin/ and instructions.
+user-invocable: true
+metadata:
+  internal: true
+---
+
+# updateBrokk
+
+Self-update Brokk in place.
+Brokk is its own repo, behind the same no-mistakes gate as any project, so new tracked material (`AGENTS.md`, `bin/`, `.agents/skills/`, and public `skills/`) reaches `main` and then sits there until each running Brokk pulls it.
+Only `AGENTS.md`, `bin/`, and `.agents/skills/` are a running Brokk instruction surface; public `skills/` is installer-facing and is not loaded by Brokk.
+This skill performs that pull for the running main Brokk and every Eindri-home, without disturbing any in-flight work.
+
+The update is **fast-forward only** - the same sanctioned self-write as the fleet sync Brokk already runs.
+For a remote route, it updates the configured Brokk code root on that host from its own origin, then guardedly fast-forwards the persistent home to that code-root commit.
+It never forces, never creates a merge commit, never stashes, and advances a target only on a clean fast-forward; anything dirty, diverged, offline, or on the wrong branch is skipped and reported.
+A tracked-files fast-forward leaves the gitignored operational dirs (data/, state/, config/, projects/, .no-mistakes/) untouched, so a Eindri-home's in-flight work is never disrupted.
+This touches only the Brokk repo and its own worktrees, never anything under `projects/`.
+
+## What it does
+
+1. **Run the updater:**
+   ```sh
+   bin/brokk-update.sh
+   ```
+   It fast-forwards this Brokk repo's default branch from origin, then updates every registered local or remote Eindri-home home through its placement-specific guarded path.
+   It prints one status line per target (`updated <old>..<new>` / `already current` / `skipped: <reason>`), followed by two action lines that tell you exactly what to do next:
+   - `reread-Brokk: yes|no`
+   - `nudge-eindri-homes: <id> ...|none`
+
+2. **Re-read AGENTS.md if your own instructions changed.**
+   When the updater printed `reread-Brokk: yes`, the tracked instruction surface (`AGENTS.md`, `bin/`, or `.agents/skills/`) just advanced under you.
+   **Read `AGENTS.md` now** (CLAUDE.md is a real `@AGENTS.md` pointer to it) to refresh your operating instructions before doing anything else, so you are acting on the new instructions rather than the stale ones you were started with.
+   When it printed `reread-Brokk: no`, nothing changed for you - skip the re-read.
+
+3. **Nudge each updated live Eindri-home.**
+   For every target listed on the `nudge-eindri-homes:` line (do nothing when it says `none`), send a one-line re-read nudge so that Eindri-home picks up its new instructions too:
+   ```sh
+   BROKK_HOME=<this-Brokk-home> bin/brokk-send.sh <id> 'Brokk was updated to the latest - please re-read your AGENTS.md to pick up the new instructions.'
+   ```
+   Include `BROKK_HOME=<this-Brokk-home>` unless `BROKK_HOME` is already set to the active Brokk home.
+   This is a gentle steer, not an interruption: the Eindri-home already got a safe tracked-files fast-forward, and the nudge never forces, tears down, or discards its work.
+   A Eindri-home that was skipped, already current, or has no live metadata is not on the list and needs no nudge.
+
+4. **Report to the Allfather in plain outcomes.**
+   Summarize what landed under `AGENTS.md` section 9 without Brokk's internal vocabulary: which parts of the fleet are now on the latest, and which were left as-is and why.
+   For example: "Allfather, Brokk and both Eindri-homes are now on the latest."
+   Surface any skipped target whose reason needs the Allfather's attention - for instance a home with its own un-landed changes (diverged) or local edits (dirty), which were left untouched on purpose.
+
+## Safety
+
+- **Fast-forward only.**
+  A target that has diverged, is dirty, is offline, or is on a non-default branch is skipped and reported, never forced or stashed.
+  Nothing with unlanded work is ever discarded - this is prime directive #3.
+- **Only the Brokk repo and its worktrees** are touched, never `projects/`.
+  It is the same sanctioned self-write as the fleet sync.
+- **Eindri-homes are never disrupted.**
+  A local or remote Eindri-home gets a tracked-files fast-forward only when its own checkout is safe to advance, plus a gentle re-read nudge when it changed.
+  It is never torn down, interrupted, or forced.