@zerwiz/ymir 0.1.5 → 0.1.7

package/README.md

@@ -243,7 +243,7 @@ Utgard sandbox on a Yggdrasil worktree.
 | **Kvasir** | the knowing | scout | reconnaissance — changes nothing |
 
 Profiles live in [`.agents/agents/`](.agents/agents/) and are bound to each tool by
-`bin/valknut-load.sh` (OpenCode reads `.opencode/agent/`; Pi links resolve under
+`bin/valknut-load.sh` (OpenCode reads `.opencode/agents/`; Pi links resolve under
 `.pi/agents/`).
 
 ---

package/RULES/02-agents.md

@@ -8,9 +8,9 @@ Agent profiles live **only** in **`.agents/agents/*.md`**. That directory is the
 source of truth; everything else binds to it.
 
 - Harness directories are **symlinks**, never copies:
-  - OpenCode: `.opencode/agent/<name>.md` → `../../.agents/agents/<profile>.md`
+  - OpenCode: `.opencode/agents/<name>.md` → `../../.agents/agents/<profile>.md`
   - Pi: `.pi/agents/<profile>.md` → the same canonical files
-- **Never edit** `.opencode/agent` or `.pi/agents` — they are links. Edit
+- **Never edit** `.opencode/agents` or `.pi/agents` — they are links. Edit
   `.agents/agents/<profile>.md` and re-run `bin/valknut-load.sh --all`.
 
 ## 2. The two kinds of agent

package/RULES/04-hoard.md

@@ -63,3 +63,35 @@ read. Operator-private documents — plans, strategy, roadmaps, the masterplan,
 `bin/docs-guard.sh` blocks a commit that stages such a document under `docs/`
 (wired into the pre-commit hook beside `secret-guard.sh`). When it fires, move
 the file to `$YMIR_HOME/docs/` in the private repo.
+
+---
+
+## Correction — 2026-09-17: hodd/ *is* the YMIR_HOME data path
+
+*Appended, citing the sections above; nothing above is rewritten.*
+
+The mapping table above ("What lives at YMIR_HOME") implies a **flat** layout —
+`hodd/identity/` → `$YMIR_HOME/identity/`, `data/` → `$YMIR_HOME/data/` — i.e.
+that the repo-side `hodd/` and the data path are two different locations. On a
+real home that reading produced **two parallel stores**: a flat
+`$YMIR_HOME/identity/` and `$YMIR_HOME/data/` alongside `$YMIR_HOME/hodd/identity/`
+and `$YMIR_HOME/hodd/data/`. They drifted, and the flat pair went stale.
+
+The truth on a live home, and the intent of this rule:
+
+- **`$YMIR_HOME/hodd/` *is* the private data path.** There is no second, flat
+  copy. `identity/`, `data/`, `docs/`, `secrets/`, `tenants/`, and the memory
+  well live **under `hodd/`**.
+- **`bin/hoard-lib.sh` is the single source of truth** for that path: it
+  resolves `${YMIR_HOARD:-${YMIR_HOME:-$HOME/Documents/Ymir}/hodd}`. A script
+  that needs the hoard calls `hoard_root`, never a hardcoded path.
+- **`.ymir-layout.yaml` records the real layout** and must name only paths that
+  exist. A layout entry pointing at a nonexistent directory is stale, and a
+  stale map is what let private work land outside the hoard.
+- The three-way reading in the section above (`hodd/x/` → `$YMIR_HOME/x/`) is
+  **superseded**: read every row as `$YMIR_HOME/hodd/x/`.
+- The "docs/ is public" section's closing line ("move the file to
+  `$YMIR_HOME/docs/`") is likewise read as **`$YMIR_HOME/hodd/docs/`**.
+
+Confirmed by the Allfather 2026-09-17. Drift of this kind is caught by
+`bin/eir-doctor.sh`'s hoard placement check.

package/RULES/06-append-only.md

@@ -56,3 +56,53 @@ are always named.
 
 **Related:** `RULES/04-hoard.md` (where private records live), `AGENTS.md`,
 `.agents/skills/galdr-ymirsystem/assets/installation.md` (the move procedure).
+
+## Amendment — the changelog writes through fragments (2026-09-17)
+
+Appended, not rewritten; the clause above stands.
+
+**The problem this amendment answers.** `CHANGELOG.md` is one file, and every
+branch appends at the same position — the top. Git sees two branches inserting
+different lines at the same spot and calls it a conflict, so **every merge
+re-conflicts every open branch**. With N branches that is O(N²) conflicts, all of
+them meaningless: both entries belong, and neither is wrong. Sixteen open PRs
+were each resolved by hand for this reason alone.
+
+**The amendment.** A change tells its story through a **fragment**:
+
+```
+CHANGELOG.d/<YYYY-MM-DD>-<slug>.md     the entry, beginning with its `## YYYY-MM-DD — title` heading
+```
+
+- **A fragment is a new file with a unique name.** Two branches never touch the
+  same one, so the collision cannot occur. This is the whole point.
+- **`bin/changelog-assemble.sh` folds fragments into `CHANGELOG.md`** — newest
+  first, above everything already recorded. Folding is an **append**: the ledger's
+  existing entries are copied verbatim, never reordered, never rewritten.
+- **The pre-push hook runs the assembler first**, so the ledger is never behind
+  what the fragments already tell. A push that would leave unfolded fragments
+  behind is refused with the instruction to commit the fold and push again.
+- **The guard accepts either form.** A push satisfies the duty by appending to
+  `CHANGELOG.md` **or** by adding a fragment. Appending directly still works and
+  is still valid; the fragment is simply the form that cannot conflict.
+
+**Why this obeys the clause above, not contradicts it.** Append, never rewrite —
+a fragment is a *new file*, and the ledger only ever grows. Never truncate —
+fragments are folded in, never dropped. Never lose one in a move — **`CHANGELOG.d/`
+joins the append-only set**, so a move must carry it exactly as it carries
+`CHANGELOG.md`. A correction is a new entry citing the old — a fragment may cite;
+nothing is edited.
+
+**The append-only set is now:**
+
+```
+append_only[7]{artifact,why}:
+  "$YMIR_HOME/memory/runes_audit.md","the Runes ledger — checksum-chained"
+  "$YMIR_HOME/docs/append-only-log.md","the decision log"
+  "CHANGELOG.md","the assembled chronological ledger; folded from fragments, never hand-rewritten"
+  "CHANGELOG.d/","pending entries — one file per change; folded in, never dropped"
+  "RULES/*.md","house law"
+  "$YMIR_HOME/**","the private record"
+  "*.jsonl / branch outcomes / session logs","event streams"
+```
+

package/RULES/07-config.md

@@ -43,3 +43,59 @@ Hardcoding is how a substrate written on one machine breaks on another, or
 collides with a neighbour's port on a shared server — the exact failure a
 host-agnostic core exists to prevent. This rule is the companion of Rule 05: Rule
 05 keeps *behaviour* portable; Rule 07 keeps *configuration* portable.
+
+## Amendment — models, providers, and paths are the user's, in the hoard (2026-09-17)
+
+Appended, not rewritten; the clauses above stand.
+
+### A. Models and providers live in the hoard, per user, read from YAML
+
+**Every user's models and providers differ.** One operator runs local llama.cpp
+on a 16 GB card; another runs hosted models; a third runs both. There is therefore
+**no such thing as a global model or provider** — a shipped default that names a
+model is a claim about someone else's machine.
+
+- **The one source.** A user's models and providers live in **`$YMIR_HOME/hodd/`**
+  — the user's own workspace, their private hoard — and are read from a **YAML
+  file there** (`hodd/config/agents.yaml`). Nothing else owns them.
+- **No global.** A model id or provider name must not appear in shipped runtime
+  code, in a tracked config, or in any repo file as a *value*. The repo ships a
+  **template** (`config/agents.yaml.example`) with placeholders; the live file is
+  the user's, and it is private (Rule 04).
+- **Resolve, never restate.** Code reads a model or provider through the resolver
+  (`bin/model-resolve.sh`, `bin/agents-config.sh`) or from env. It never embeds
+  the id.
+- **A comment may name an example; code may not.** A usage line in a header
+  (`#   bin/pi-seat.sh -m <model>`) is documentation. A literal assigned to a
+  variable, written into a config, or passed as a default is a violation.
+
+### B. No hardcoded absolute file paths
+
+**A path that names a user, or a machine's layout, is not portable.**
+
+- **User-agnostic.** No `/home/<user>/…`, no `/Users/<user>/…`, no `C:\Users\…`,
+  no baked-in username anywhere in shipped code, config, or docs.
+- **Relative or resolved.** A path is relative to a resolved root
+  (`$YMIR_HOME`, `$YMIR_HOARD`, `$ROOT`, `$SCRIPT_DIR`), or comes from env/config
+  with one documented default. Never a literal absolute path.
+- **The home is resolved, not assumed.** `$YMIR_HOME` resolves through
+  `bin/hoard-lib.sh` (`hoard_root`) — never a hardcoded `~/Documents/Ymir`, never
+  another user's home.
+- **A test may use a temp dir; it may not use a real home.** `mktemp -d` and
+  `$TMPDIR` are correct. A fixture that names a real user's home is a violation
+  that will fail on every other machine.
+
+### Enforcement
+
+`compliance-check.sh` gains the **`config`** gate, which fails on:
+
+```
+config_gate[3]{class,what_it_catches}:
+  "model","a model id or provider name used as a VALUE in shipped code or a tracked config"
+  "path","an absolute path naming a user (/home/<user>, /Users/<user>, C:\\Users\\<user>)"
+  "hoard","a model/provider config outside $YMIR_HOME/hodd/"
+```
+
+Comments, templates (`*.example`), `CHANGELOG*`, and `assets/reference/`
+(provenance) are exempt by intent — they document, they do not configure.
+

package/RULES/09-electron.md

@@ -0,0 +1,58 @@
+# Rule 09 — Electron is a Local Seat
+
+A desktop window is the machine talking to itself. Every rule below follows from
+that one sentence.
+
+## 09.1 Local connections only
+
+**An Electron shell loads loopback and nothing else.** A URL that is not
+`127.0.0.1`, `localhost` or `::1` is refused, with a warning, and replaced by the
+local default. If a shell is handed a public hostname — a tunnel, a `*.zerwiz.org`
+name — it must **not** honour it.
+
+Why the law, not a preference: a desktop app that dials out is a desktop app whose
+failures belong to somebody else's edge. A bridge that dressed a cloud endpoint as
+`127.0.0.1` cost a night of "the agents never start"; a shell that reaches for a
+public hall when its own machine is quiet is the same mistake wearing different
+clothes.
+
+**Cloudflare has nothing to do with Electron.** Tunnels exist for the *web* door,
+so a person elsewhere can reach the apps. The desktop is already where the apps
+live.
+
+## 09.2 No login in the desktop seat
+
+The web door has exactly one login; the desktop seat does not have one at all. The
+shell is a local, trusted seat — its preload marks its requests, and the gate
+honours that marker **only from loopback**. A login prompt inside an Electron
+window means the surface has been mistaken for the web.
+
+## 09.3 A service that is down says so
+
+When a local service is not answering, the shell reports it — it does not fall
+back to a remote copy, a cached one, or a public hostname. A wrong answer from
+the wrong server is worse than no answer.
+
+## 09.4 The shell carries the house mark
+
+Every app ships its own **rune** icon (see `midgard/design-system/runes.md`), and
+installation writes both the icon into the user's icon theme and the `.desktop`
+entry into their applications directory — with this machine's root rendered in, so
+the entry works and the operator can pin it. An app nobody can pin is an app half
+installed.
+
+## 09.5 One lifecycle for the web and the windows
+
+`scripts/raise.sh` and `scripts/lower.sh` own both. Lowering takes the **windows
+down first**, so no shell is left watching a port that has just vanished.
+
+## 09.6 References
+
+- `apps/hlidskjalf/electron/`, `apps/odrerir/electron/`, `apps/sessrumnir/src/main/`
+- `scripts/electron.sh` — the shell lifecycle; `scripts/raise.sh` / `scripts/lower.sh`
+- `bin/design-icon.sh` — the rune and the entry, installed
+- Rule 05 (platforms), Rule 07 (config resolves from env, never a literal)
+
+---
+
+*Append-only. A correction is a new entry citing the old one.*

package/RULES/README.md

@@ -18,3 +18,5 @@ rules_index[9]{file,subject}:
 ```
 
 Keep each rule short and unambiguous; reference it from code where it bites.
+
+| 09 | `09-electron.md` | Electron is a local seat: local connections only, no login, the rune icon and entry installed, one lifecycle with the web. |

package/bin/a2a-mcp.sh

@@ -39,9 +39,26 @@ ENGRAM_BIN="${ENGRAM_BIN:-$HOME/.local/bin/engram-mcp}"
 YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
 ENGRAM_DB="${ENGRAM_DB:-$YMIR_HOME/memory/kaia.engram}"
 
-python3 - "$ROOT" "$PI_MCP" "$OC" "$A2AB" "$DIR" "$ADVERT" "$WOTES" "$ACTION" "$ENGRAM_BIN" "$ENGRAM_DB" <<'PY'
+# The Teams plane (WayOfTeams) and Anchor memory are REMOTE MCP servers, named by
+# URL. The URL is credential-ish, so it comes from the environment — never the
+# tracked tree. Pi has no remote transport, so it reaches them through the
+# `mcp-remote` stdio bridge; OpenCode speaks `type: remote` natively.
+# The environment wins; else the private platform env, so no caller must export.
+platform_env_val() {  # <KEY>
+  local k=$1 f v
+  for f in "${YMIR_HOARD:-$YMIR_HOME/hodd}/secrets/platform.env" "$YMIR_HOME/hodd/secrets/platform.env" "$YMIR_HOME/secrets/platform.env"; do
+    [ -r "$f" ] || continue
+    v="$(grep -E "^$k=" "$f" 2>/dev/null | tail -1 | cut -d= -f2-)"
+    [ -n "$v" ] && { printf '%s' "$v"; return 0; }
+  done
+}
+TEAMS_URL="${WAYOFTEAMS_MCP_URL:-}";  [ -n "$TEAMS_URL" ]  || TEAMS_URL="$(platform_env_val WAYOFTEAMS_MCP_URL)"
+ANCHOR_URL="${ANCHOR_MCP_URL:-}";     [ -n "$ANCHOR_URL" ] || ANCHOR_URL="$(platform_env_val ANCHOR_MCP_URL)"
+
+python3 - "$ROOT" "$PI_MCP" "$OC" "$A2AB" "$DIR" "$ADVERT" "$WOTES" "$ACTION" "$ENGRAM_BIN" "$ENGRAM_DB" "$TEAMS_URL" "$ANCHOR_URL" <<'PY'
 import sys, os, json
-root, pi_path, oc_path, a2ab, durl, advert, wotes, action, engram_bin, engram_db = sys.argv[1:11]
+(root, pi_path, oc_path, a2ab, durl, advert, wotes, action, engram_bin, engram_db,
+ teams_url, anchor_url) = sys.argv[1:13]
 
 def load(p, default):
     try: return json.load(open(p))
@@ -59,20 +76,38 @@ ones = {
         "oc":  {"type": "local", "command": [engram_bin, "--db", engram_db], "environment": {}},
     },
 }
-if wotes:
+# The Teams plane: a URL (remote) wins over a local `wayofteams-mcp` binary.
+if teams_url:
+    ones["wayofteams"] = {
+        "pi":  {"command": "npx", "args": ["-y", "mcp-remote", teams_url]},
+        "oc":  {"type": "remote", "url": teams_url},
+    }
+elif wotes:
     ones["wayofteams"] = {
         "pi":  {"command": wotes, "args": ["--stdio"], "env": {"WOTEAMS_URL": os.environ.get("WOTEAMS_URL","")}},
         "oc":  {"type": "local", "command": [wotes, "--stdio"], "environment": {"WOTEAMS_URL": os.environ.get("WOTEAMS_URL","")}},
     }
 
+# Anchor — the memory plane, remote by URL.
+if anchor_url:
+    ones["way-of-anchor-sse"] = {
+        "pi":  {"command": "npx", "args": ["-y", "mcp-remote", anchor_url]},
+        "oc":  {"type": "remote", "url": anchor_url},
+    }
+
 if action == "show":
     pi = load(pi_path, {}).get("mcpServers", {})
     oc = load(oc_path, {}).get("mcp", {})
-    print(f"a2a-mcp[{len(ones)}]{{server,in_pi,in_opencode}}:")
-    for name in ones:
+    # Report what is ACTUALLY wired, not a fixed list: a key may come from an
+    # earlier install, a hand edit, or a server this script does not itself add.
+    names = sorted(set(ones) | set(pi) | set(oc))
+    print(f"a2a-mcp[{len(names)}]{{server,in_pi,in_opencode}}:")
+    for name in names:
         print(f'  "{name}","{"yes" if name in pi else "no"}","{"yes" if name in oc else "no"}"')
-    if not wotes:
-        print('help: wayofteams-mcp not on PATH — install it to enable the Teams plane')
+    if not wotes and not teams_url:
+        print('help: set WAYOFTEAMS_MCP_URL (or install wayofteams-mcp) to enable the Teams plane')
+    if not anchor_url:
+        print('help: set ANCHOR_MCP_URL to enable the Anchor memory plane')
     sys.exit(0)
 
 if action != "install":

package/bin/agents-config.sh

@@ -18,9 +18,21 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
-CFG="${YMIR_AGENTS_YAML:-$YMIR_HOME/config/agents.yaml}"
-RESOLVED="${YMIR_STATE_DIR:-$YMIR_HOME/state}/agents-resolved.json"
+
+# The operator's settings and secrets live in the home they chose, never in the
+# code tree — a packaged install replaces its tree on upgrade, and a credential
+# must never sit in a tree that ships (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_settings_dir YMIR_SETTINGS_DIR
+hoard_local_env YMIR_ENV_FILE
+CFG="${YMIR_AGENTS_YAML:-$YMIR_SETTINGS_DIR/agents.yaml}"
+RESOLVED="${YMIR_STATE_DIR}/agents-resolved.json"
 
 case "${1-}" in
   -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
@@ -35,6 +47,7 @@ if [ "$ACTION" = init ]; then
     exit 0
   fi
   TPL="$ROOT/config/agents.yaml.example"
+  [ -r "$TPL" ] || TPL="$ROOT/.agents/config/agents.yaml.example"
   [ -r "$TPL" ] || { printf 'error: template missing: %s\n' "$TPL" >&2; exit 1; }
   mkdir -p "$(dirname "$CFG")" 2>/dev/null || true
   cp "$TPL" "$CFG" || { printf 'error: could not write %s\n' "$CFG" >&2; exit 1; }
@@ -211,12 +224,22 @@ if os.path.exists(oc):
         changed.append(f"provider:{name}")
     ablock = d.setdefault("agent", {})
     for a in agents:
+        # opencode.json is OpenCode's file: only OpenCode agents belong in it. A
+        # pi (or hermes) agent's model is that harness's id — e.g.
+        # `llamacpp/qwen3.5-9b` — which OpenCode cannot resolve, so writing it
+        # here would hand OpenCode an agent it cannot run. Skip them.
+        if harness_of(a) != "opencode":
+            continue
         m = resolve_model(model_of(a))
-        if a in ablock:
-            if ablock[a].get("model") != m:
-                ablock[a]["model"] = m; changed.append(f"oc:{a}")
+        # The roster DECLARES every figure it names. Before this, `apply` only
+        # touched an agent already present in opencode.json (`if a in ablock`),
+        # so a figure the roster knew but the config had never seen stayed
+        # undeclared — and OpenCode never loaded it. The roster is the source of
+        # truth; a name in it must reach the harness config.
+        entry = ablock.setdefault(a, {})
+        if entry.get("model") != m:
+            entry["model"] = m; changed.append(f"oc:{a}")
         if spec_of(a).get("primary"):
-            entry = ablock.setdefault(a, {})
             entry["mode"] = "primary"
             entry["model"] = m
             entry.setdefault("description", f"{a} — primary (from config/agents.yaml)")

package/bin/apodex-smoke-test.sh

@@ -15,8 +15,21 @@ set -u
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
+# The operator's settings and secrets live in the home they chose, never in the
+# code tree — a packaged install replaces its tree on upgrade, and a credential
+# must never sit in a tree that ships (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_settings_dir YMIR_SETTINGS_DIR
+hoard_local_env YMIR_ENV_FILE
+
 # Source env if available (project .env.local first, then the private hoard).
-for f in "$ROOT/.env.local" "${YMIR_HOARD:-$HOME/Documents/Ymir}/.env.local"; do
+for f in "$YMIR_ENV_FILE" "${YMIR_HOARD:-$HOME/Documents/Ymir}/.env.local"; do
   [ -f "$f" ] && . "$f" 2>/dev/null || true
 done
 

package/bin/bifrost-bridge.sh

@@ -25,11 +25,30 @@ fi
 VERSION="2.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# The operator's settings and secrets live in the home they chose, never in the
+# code tree — a packaged install replaces its tree on upgrade, and a credential
+# must never sit in a tree that ships (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_settings_dir YMIR_SETTINGS_DIR
+hoard_local_env YMIR_ENV_FILE
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
 BRIDGE="$ROOT/.agents/backend/model-bridge.py"
-ENV_FILE="${BROKK_ENV_FILE:-$ROOT/.env.local}"
+ENV_FILE="${BROKK_ENV_FILE:-$YMIR_ENV_FILE}"
 PORT="${OPENCODE_GO_BRIDGE_PORT:-4603}"
-PID_FILE="$ROOT/state/model-bridge.pid"
-LOG_FILE="$ROOT/state/model-bridge.log"
+PID_FILE="$YMIR_STATE_DIR/model-bridge.pid"
+LOG_FILE="$YMIR_STATE_DIR/model-bridge.log"
 PROVIDER="${YMIR_MODEL_PROVIDER:-}"
 
 case "${1-}" in
@@ -40,8 +59,8 @@ ACTION="start"
 while [ $# -gt 0 ]; do
   case "$1" in
     --start|"") ACTION=start; shift ;;
-    --stop) ACTION=stop; shift ;;
-    --status) ACTION=status; shift ;;
+    --stop|stop) ACTION=stop; shift ;;
+    --status|status) ACTION=status; shift ;;
     --port) PORT=${2-}; shift 2 ;;
     --provider) PROVIDER=${2-}; shift 2 ;;
     *) printf 'error: unknown flag %s\nhelp: bin/bifrost-bridge.sh [--start|--stop|--status|--port|--provider]\n' "$1" >&2; exit 2 ;;
@@ -95,7 +114,7 @@ if [ -z "$PROVIDER" ]; then
 fi
 
 # A missing env file is fine for keyless providers; the bridge reads what it can.
-mkdir -p "$ROOT/state"
+mkdir -p "$YMIR_STATE_DIR"
 nohup python3 "$BRIDGE" --port "$PORT" --env "$ENV_FILE" --provider "$PROVIDER" >"$LOG_FILE" 2>&1 &
 echo $! >"$PID_FILE"
 sleep 2

package/bin/bootstrap-macos.sh

@@ -25,7 +25,12 @@ VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 VM="ymir"; CHECK=0; REPO=""
-VM_HOME="${YMIR_HOME:-/home/ubuntu/Documents/Ymir}"
+# The VM's home is resolved, never assumed (Rule 07B). Inside the Lima VM the
+# operator is `ubuntu`, but that is the VM's fact, not this script's — it comes
+# from env with one documented default, and the guest user is overridable so a
+# host that provisions a different user still works.
+VM_USER="${YMIR_VM_USER:-ubuntu}"
+VM_HOME="${YMIR_HOME:-/home/${VM_USER}/Documents/Ymir}"
 
 while [ $# -gt 0 ]; do
   case "$1" in

package/bin/brokk-send.sh

@@ -10,7 +10,20 @@ set -u
 VERSION="1.0.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
-REG="${BROKK_EINDRI_HOMES:-$ROOT/data/eindri-homes.md}"
+
+# The roots that live OUTSIDE the code tree: this machine's records and the
+# runtime state belong to the home the operator chose at installation, never in
+# the tree — a packaged install replaces its tree on upgrade (Rule 04).
+if [ -z "${YMIR_HOARD_LIB_LOADED:-}" ]; then
+  _yr="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  for _yc in "$_yr/hoard-lib.sh" "$(dirname "$_yr")/bin/hoard-lib.sh"; do
+    [ -r "$_yc" ] && { . "$_yc"; YMIR_HOARD_LIB_LOADED=1; break; }
+  done
+  unset _yr _yc
+fi
+hoard_state_dir YMIR_STATE_DIR
+hoard_data_dir YMIR_DATA_DIR
+REG="${BROKK_EINDRI_HOMES:-$YMIR_DATA_DIR/eindri-homes.md}"
 
 case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
 ID="${1-}"; shift || true

package/bin/changelog-assemble.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# changelog-assemble.sh — fold CHANGELOG.d/ fragments into CHANGELOG.md.
+#
+# WHY THIS EXISTS
+#   CHANGELOG.md is one file, and every branch appends at the same position — the
+#   top. Git sees two branches inserting different lines at the same spot and
+#   calls it a conflict, so every merge re-conflicts every open branch. With N
+#   branches that is O(N^2) conflicts, all of them meaningless.
+#
+#   A fragment directory removes the collision at the root: each change adds ONE
+#   file with a UNIQUE name, so two branches never touch the same file and can
+#   never conflict. This script folds the fragments into the ledger.
+#
+# THE LAW (RULES/06-append-only.md)
+#   Append, never rewrite. Never truncate. Never lose one in a move.
+#   A fragment is a new file; the ledger only ever grows. Folding is an append.
+#   CHANGELOG.d/ joins the append-only set, so a move must carry it.
+#
+# FRAGMENT FORMAT
+#   CHANGELOG.d/<YYYY-MM-DD>-<slug>.md — the entry exactly as it should appear in
+#   CHANGELOG.md, starting with its `## YYYY-MM-DD — title` heading.
+#
+# USAGE
+#   bin/changelog-assemble.sh              # fold every fragment, newest first
+#   bin/changelog-assemble.sh --dry-run    # report what would fold
+#   bin/changelog-assemble.sh --check      # exit 1 if fragments are unfolded
+#
+# Exit: 0 ok, 1 error (or --check with fragments present), 2 usage.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+FRAG_DIR="$ROOT/CHANGELOG.d"
+LEDGER="$ROOT/CHANGELOG.md"
+
+DRY=0; CHECK=0
+for a in "$@"; do
+  case "$a" in
+    --dry-run) DRY=1 ;;
+    --check)   CHECK=1 ;;
+    -h|--help) sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) printf 'error: unknown flag %s\nhelp: bin/changelog-assemble.sh [--dry-run|--check]\n' "$a" >&2; exit 2 ;;
+  esac
+done
+
+[ -f "$LEDGER" ] || { printf 'error: no ledger at %s\n' "$LEDGER" >&2; exit 1; }
+
+# One python block owns the whole fold: regex, ordering, and the ledger's
+# structure are all easier to get right in one language than split across awk,
+# sed and shell — and an awk interval regex silently matched nothing, which
+# duplicated the entire ledger.
+ROOT="$ROOT" FRAG_DIR="$FRAG_DIR" LEDGER="$LEDGER" DRY="$DRY" CHECK="$CHECK" python3 - <<'PY'
+import os, re, sys, glob
+
+root = os.environ["ROOT"]
+frag_dir = os.environ["FRAG_DIR"]
+ledger = os.environ["LEDGER"]
+dry = os.environ["DRY"] == "1"
+check = os.environ["CHECK"] == "1"
+
+HEADING = re.compile(r"^## (\d{4}-\d{2}-\d{2}) ")
+
+# --- fragments -------------------------------------------------------------
+frags = []
+if os.path.isdir(frag_dir):
+    for p in sorted(glob.glob(os.path.join(frag_dir, "*.md"))):
+        if os.path.basename(p) == "README.md":
+            continue
+        frags.append(p)
+
+if not frags:
+    if check:
+        sys.exit(0)
+    print('changelog-assemble[1]{fragments,folded,state}:')
+    print('  "0","0","none pending"')
+    sys.exit(0)
+
+# A fragment must begin with its dated heading, or folding it would corrupt the
+# ledger's structure.
+bad = []
+for p in frags:
+    first = open(p, encoding="utf-8").readline()
+    if not HEADING.match(first):
+        bad.append(os.path.relpath(p, root))
+if bad:
+    for b in bad:
+        print(f'error: fragment has no dated heading: {b}', file=sys.stderr)
+    print('help: first line must be "## YYYY-MM-DD — title"', file=sys.stderr)
+    sys.exit(1)
+
+def frag_date(p):
+    m = re.match(r"^(\d{4}-\d{2}-\d{2})", os.path.basename(p))
+    return m.group(1) if m else "0000-00-00"
+
+# newest first; ties broken by name for determinism
+frags.sort(key=lambda p: (frag_date(p), os.path.basename(p)), reverse=True)
+
+if check:
+    print(f'changelog-assemble[{len(frags)}]{{fragment,state}}:')
+    for p in frags:
+        print(f'  "{os.path.relpath(p, root)}","unfolded"')
+    print(f'error: {len(frags)} changelog fragment(s) not folded into CHANGELOG.md', file=sys.stderr)
+    print('help: run bin/changelog-assemble.sh', file=sys.stderr)
+    sys.exit(1)
+
+if dry:
+    print(f'changelog-assemble[{len(frags)}]{{fragment,date}}:')
+    for p in frags:
+        print(f'  "{os.path.relpath(p, root)}","{frag_date(p)}"')
+    print('changelog-assemble: dry run — nothing written')
+    sys.exit(0)
+
+# --- the ledger ------------------------------------------------------------
+text = open(ledger, encoding="utf-8").read()
+lines = text.split("\n")
+
+# preamble = everything before the first dated entry (the `# CHANGELOG` head)
+split = None
+for i, ln in enumerate(lines):
+    if HEADING.match(ln):
+        split = i
+        break
+if split is None:
+    preamble = lines[:]          # no dated entry yet: the whole file is preamble
+    existing = []
+else:
+    preamble = lines[:split]
+    existing = lines[split:]
+
+# trim trailing blanks from the preamble, then one blank separator
+while preamble and preamble[-1].strip() == "":
+    preamble.pop()
+
+# --- assemble: fragments first (newest at top), then the existing ledger ----
+out = list(preamble)
+out.append("")
+for p in frags:
+    body = open(p, encoding="utf-8").read().rstrip("\n").split("\n")
+    out.extend(body)
+    out.append("")
+    out.append("")
+out.extend(existing)
+
+# collapse runs of 3+ blank lines to two (entry separation only — never content)
+t = "\n".join(out)
+t = re.sub(r"\n{3,}", "\n\n", t).rstrip("\n") + "\n"
+
+open(ledger, "w", encoding="utf-8").write(t)
+for p in frags:
+    os.remove(p)
+
+print('changelog-assemble[1]{fragments,folded,ledger}:')
+print(f'  "{len(frags)}","{len(frags)}","CHANGELOG.md"')
+PY