@zerwiz/ymir 0.1.3 → 0.1.5

package/docs/runbooks/realm-onboarding.md

@@ -0,0 +1,60 @@
+# Runbook — Onboarding a Realm
+
+A realm (tenant) is an isolated shop floor under `svartalfaheim/`. Onboarding one
+creates its tree, secrets, persona, and registry row — and leaks nothing across
+boundaries.
+
+## Prerequisites
+
+- The operator (Allfather) has approved the new realm and named its house.
+- Git auth is good: `gh auth status`.
+
+## Steps
+
+1. **Create the realm tree.**
+
+   ```bash
+   realm=<realm>
+   mkdir -p svartalfaheim/"$realm"/{workspace/{company,marketing,development,life,memory/daily},projects,companies}
+   touch svartalfaheim/"$realm"/projects/.gitkeep
+   ```
+
+2. **Secrets.** Copy the example and fill it; never commit it.
+
+   ```bash
+   cp svartalfaheim/"$realm"/.env.realm.example svartalfaheim/"$realm"/.env.realm
+   chmod 600 svartalfaheim/"$realm"/.env.realm
+   ```
+
+   `.gitignore` already ignores `svartalfaheim/*/.env.realm`.
+
+3. **Persona.** Write `svartalfaheim/"$realm"/AGENTS.md` (or `Brokk.md`) — the
+   realm's operating brief and its house.
+
+4. **Houses & projects.** Add entity cards under
+   `svartalfaheim/"$realm"/companies/<house>/entity.md` using
+   [`.agents/assets/templates/company_entity.template.md`](../../.agents/assets/templates/company_entity.template.md).
+   Register the realm in `data/projects.md`.
+
+5. **Register the house accents** (if new) in `src/data/realms.ts` (Hlidskjalf) and
+   `midgard/design-system/tokens.css`.
+
+6. **Verify.**
+
+   ```bash
+   test -d svartalfaheim/"$realm"/workspace && echo tree-ok
+   bash bin/valknut-load.sh --status
+   bin/brokk status
+   bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh
+   ```
+
+## Rules
+
+- **Boundaries are sacred:** never read, write, or reference another realm.
+- **Secrets stay in `.env.realm`**, never in Markdown.
+- **Split or merge a house only by a new append-only entry** — never silently.
+
+## Done when
+
+The realm tree, `.env.realm`, persona, and entity cards exist; the realm is listed
+in `data/projects.md`; `bin/brokk status` and the compliance gate are green.

package/docs/runbooks/secrets-and-hoard.md

@@ -0,0 +1,60 @@
+# Runbook — secrets and the Hoard (Hodd)
+
+Everything private lives in **one** place: **YMIR_HOME**
+(`$HOME/Documents/Ymir` — secrets · docs · tenants · identity).
+The repo tracks only the guard and README at `hodd/`.
+Law: `RULES/04-hoard.md`.
+
+## Load a secret (never inline it)
+
+Secrets are **referenced by path**, never pasted into a tracked file.
+
+```bash
+bin/hodd.sh path                                   # the Hoard root (YMIR_HOARD)
+bin/hodd.sh ls                                     # what it holds (names, not values)
+bin/hodd.sh init                                   # create the layout
+
+# set an env file's vars in YOUR shell (quoting-safe):
+eval "$(bin/hodd.sh emit secrets/platform.env)"
+# a tenant's env (into that tenant's work only):
+eval "$(bin/hodd.sh emit tenants/<tenant>/.env)"   # or: bin/hodd.sh tenant <tenant>
+```
+`YMIR_HOARD` overrides the location.
+
+## The guards
+
+- **Outer ward** — `bin/secret-guard.sh`: blocks a commit that stages a private
+  env file or an obvious secret. Install once:
+  ```bash
+  bin/secret-guard.sh --install     # .git/hooks/pre-commit
+  bin/secret-guard.sh --all         # scan every tracked file (also runs in CI)
+  ```
+  Test fixtures that contain fake secret-shaped strings go in
+  `.secret-guardignore`.
+- **Inner ward** — `hodd/.gitignore` at the repo (tracks only the guard + README + `*.example`).
+  The real data lives at `$YMIR_HOME` (committed, shareable).
+
+## If a secret reaches a commit
+
+Rotation first — rewriting history does not un-leak a key.
+
+```bash
+# 1) revoke the key at the provider, mint a new one, update where it lives
+# 2) purge it from history:
+cd ~/Ymir && git status --porcelain          # must be empty
+bin/repo-scrub.sh --dry-run <paths…>
+bin/repo-scrub.sh --yes <paths…>             # mirrors a backup to /tmp, rewrites
+git remote add origin <url>                  # filter-repo drops origin
+git push --force --all && git push --force --tags
+bin/secret-guard.sh --all                    # expect CLEAN
+```
+Force-push rewrites the remote — any other clone must be re-cloned.
+
+## What belongs where
+
+| Path | Holds |
+|------|-------|
+| `$YMIR_HOME/secrets/` | env files, keys, tunnel tokens |
+| `$YMIR_HOME/docs/` | private strategy, plans |
+| `$YMIR_HOME/tenants/<t>/` | per-tenant private trees |
+| `$YMIR_HOME/identity/` | company/domain cards, portfolio, project registry |

package/docs/runbooks/updates-and-migrations.md

@@ -0,0 +1,110 @@
+# Runbook — updating the runtime and healing old homes
+
+## Update the code
+
+```bash
+bin/brokk-update.sh          # fast-forward this home + every registered Eindri-home
+```
+It never forces or stashes; it reports one row per target. After updating, run
+the structure migrations below.
+
+## Structure migrations (old homes heal forward)
+
+Versioned, idempotent scripts in `.agents/migrations/` transform an older home
+into the current layout (e.g. `0001-ymir-home` moves private material into
+`$YMIR_HOME`).
+
+```bash
+bin/ymir-migrate.sh status            # what exists / what is applied
+bin/ymir-migrate.sh apply --dry-run   # show what would run
+bin/ymir-migrate.sh apply             # apply pending, in order
+```
+Applied ids are recorded in `state/migrations` (private). Each migration must be
+idempotent — re-running is safe. `bin/ymir-install.sh` and `bin/brokk-update.sh`
+call `apply` after an update.
+
+## Add a migration
+
+1. Create `.agents/migrations/NNNN-<name>.sh` (next number), idempotent.
+2. It runs with `bash` from the repo; move/transform, print what it did.
+3. Test: `bin/ymir-migrate.sh apply --dry-run`, then `apply`.
+
+## First-time setup
+
+```bash
+bin/ymir-install.sh            # full setup (idempotent)
+bin/ymir-install.sh --check    # all steps OK/WARN
+```
+
+## Re-cloning a home whose history has diverged
+
+If `git push` from a home is rejected with "unrelated histories" — or
+`git merge-base HEAD origin/main` prints nothing — the working copy and the
+remote no longer share an ancestor. The home cannot be pushed. Clone fresh and
+move into it; do not try to reconcile the histories.
+
+**What a clone does NOT carry.** Plan for all of it before you switch:
+
+| Missing from a clone | Why it matters |
+|---|---|
+| `.env.local`, `state/`, `data/` | secrets and runtime state — the home cannot boot without them |
+| the realm tree, `workspace/` | the operator's private world (untracked by design) |
+| `YMIR_HOME` | the private hoard — committed to the private git repo, shareable |
+| local-only branches | **anything never pushed exists only here.** Check with `git branch` and compare against `git branch -r` |
+| `.yggdrasil/` worktrees | each is registered by **absolute path** to this home's `.git` |
+| `node_modules` | rebuildable — see `installation.md` for the postinstall trap |
+
+**Procedure**
+
+```bash
+# 1. Secure first. Everything below is cheap; the mistake is not.
+git bundle create /backup/branches.bundle $(git branch --format='%(refname:short)' | grep -v '^main$')
+git bundle create /backup/history.bundle --all
+tar czf /backup/essentials.tgz state .env.local data workspace svartalfaheim hodd
+tar czf /backup/yggdrasil.tgz .yggdrasil
+git diff > /backup/uncommitted.patch
+for w in .yggdrasil/*/; do git -C "$w" diff HEAD > "/backup/wt-$(basename $w).diff"; done
+
+# 2. Clone current, and prove the clone is behind-nothing before you move in.
+git clone <remote> ~/ymir-new && cd ~/ymir-new && git log --oneline -1
+
+# 3. Import the local-only branches, then carry the private paths across.
+git fetch /backup/branches.bundle 'refs/heads/*:refs/heads/*'
+cp -a ~/ymir/.env.local . && for d in state data svartalfaheim workspace; do cp -a ~/ymir/$d/. $d/; done
+cp -a ~/ymir/hodd . 2>/dev/null || true
+
+# 4. Swap, keeping the old home for rollback.
+mv ~/ymir ~/ymir-old && mv ~/ymir-new ~/ymir
+
+# 5. Re-create the worktrees from the imported branches, then restore their working state.
+git worktree prune
+for b in $(git branch --format='%(refname:short)' | grep '^yggdrasil/'); do
+  git worktree add ".yggdrasil/${b#yggdrasil/}" "$b"
+done
+
+# 6. Heal forward and verify.
+bin/ymir-migrate.sh status && bin/ymir-migrate.sh apply
+bin/ymir-install.sh --check
+```
+
+**Traps this procedure was learned from**
+
+- **Carrying private paths over a fresh clone can clobber newer tracked files.**
+  `cp -a workspace/.` overwrote a `workspace/README.md` that the remote had
+  evolved past. Carry the *untracked* private trees (`state`, `data`, `hodd`,
+  `.env.local`) and copy realm/workspace content only after checking
+  `git status` — then restore any tracked file the carry dirtied:
+  `git checkout -- <path>`.
+- **`tar` copies files, not absences.** A worktree with *staged deletions* comes
+  back with those files present again. Compare each restored worktree against its
+  pre-swap `git status --porcelain` record and replay the deletions
+  (`git rm -f <path>`), or apply the saved `git diff HEAD` patch.
+- **Worktree registrations are absolute.** Rename the home and every worktree
+  loses its `gitdir`, so `git` fails inside it until `git worktree prune` +
+  `git worktree add` rebuild the registration. The `.git` never has to move —
+  but if you move the home, expect to rebuild them.
+- **Verify the restore, do not assume it.** For each worktree, diff its current
+  `git status --porcelain` against the record taken before the swap. Everything
+  matching is the acceptance test.
+
+Rollback at any point: `mv ~/ymir ~/ymir-failed && mv ~/ymir-old ~/ymir`.

package/docs/runbooks/worktrees-isolation.md

@@ -0,0 +1,72 @@
+# Runbook — worktrees and isolation
+
+Every Eindri works in an **isolated Yggdrasil worktree**, never the main tree
+(law *ygg1*). This keeps parallel workers from colliding and keeps your checkout
+clean. Working in main is possible only when you ask for it.
+
+## The rule
+
+```
+isolation[3]{road,default,opt_out}:
+  "bin/eindri-start.sh \"<task>\"","secure worktree .yggdrasil/<id>","--main"
+  "bin/pi-seat.sh --task \"<task>\"","secure worktree","--main"
+  "bin/einherjar-spawn.sh <id>","secure worktree","—"
+```
+
+- **Default = isolated.** The dispatcher creates (or reuses) `.yggdrasil/<id>`
+  and seats the agent there. If it cannot make a worktree it **refuses** to seat
+  in main (`exit 4`) — it never silently falls back to your checkout.
+- **`--main` = work in the main tree**, only when you deliberately want the agent
+  to help in main:
+  ```bash
+  bin/eindri-start.sh "fix the typo in README" --main
+  ```
+
+## Managing worktrees
+
+```bash
+bin/yggdrasil.sh create <id>      # create .yggdrasil/<id> on branch yggdrasil/<id>
+bin/yggdrasil.sh list             # every worktree: id · branch · path · head
+bin/yggdrasil.sh status <id>      # one worktree's state
+bin/yggdrasil.sh merge  <id>      # merge yggdrasil/<id> into main  (human-gated)
+bin/yggdrasil.sh cleanup <id>     # remove the worktree after merge
+```
+A worktree lives at `<repo>/.yggdrasil/<id>/` on its own branch `yggdrasil/<id>`.
+
+## Seeing them in Hlidskjalf
+
+Open the **Worktrees** gate (rail). It reads `GET /api/worktrees` (backed by
+`git worktree list`) and shows every tree:
+
+```
+Worktrees
+id      branch             agent   head      path
+bragi   yggdrasil/bragi    bragi   f709bb1   /home/…/Ymir/.yggdrasil/bragi
+(main)  main               -       3283188   /home/…/Ymir
+```
+
+So the **Fleet** gate shows the agents and **Worktrees** shows the trees they
+work in — including the artifact each produced.
+
+## Bringing work home
+
+The work does **not** auto-return. When an Eindri finishes:
+
+1. Inspect it in the Worktrees gate (or `bin/yggdrasil.sh status <id>`).
+2. **Merge on approval** (law 4 — human-gated):
+   ```bash
+   bin/yggdrasil.sh merge <id>
+   ```
+3. `bin/yggdrasil.sh cleanup <id>` once merged.
+
+## Troubleshooting
+
+- **`could not create a Yggdrasil worktree; refusing to seat`** — the worktree
+  couldn't be made (usually already exists under a different state, or the repo
+  isn't a git worktree). Check `bin/yggdrasil.sh list`; the seat **reuses** an
+  existing `.yggdrasil/<id>`.
+- **An agent wrote to `~/Ymir/...` (main)** — that was pre-isolation, or `--main`
+  was passed. Check the Worktrees gate: an isolated run's files live under
+  `.yggdrasil/<id>/`, not the main tree.
+- **`git worktree list` shows a missing path** — prune with
+  `git worktree prune`, then re-list.

package/docs/session-start.md

@@ -0,0 +1,105 @@
+# Session Start & Seating — Sága, the digest
+
+When a harness opens in `$YMIR_ROOT`, Brokk must take the high seat
+**before the first turn**: the session context is injected, the model bridge is
+raised, the Nornir jobs start, and the session lock binds to the live process.
+This document records how that mechanism works, how it compares to the validated
+upstream agent-distro it was ported from, and how to verify it. The runtime spec
+is `docs/plans/29-brokk-distro-runtime.md`; the lore is `docs/lore.md` §XII.
+
+## The two tiers
+
+A harness either **runs** the digest and has its output gated into model context,
+or is **nudged** to run it. The tier is a property of the harness surface.
+
+```
+tiers[2]{tier,mechanism,harnesses}:
+  "Run","the adapter runs the digest before the first turn and injects its stdout as a context message","Claude Code, Codex exec, Pi, Cursor"
+  "Nudge","the adapter asks the agent to run the digest","Grok, OpenCode"
+```
+
+The nudge tier can only ask; an agent may defer. The run tier removes that
+discretion, which is why it is preferred wherever the harness supports it.
+
+## The Pi run-tier flow
+
+```
+pi_flow[6]{id,step,owner}:
+  1,"Pi fires session_start with a reason (startup|new|resume|fork)","Pi"
+  2,"the extension maps the reason to a Sága source and starts one digest generation","syn-turnend-guard.ts"
+  3,"the digest runs under a bounded child supervisor","vordr-sessionstart-supervisor.mjs -> bin/saga-sessionstart-run.sh"
+  4,"before_agent_start awaits the generation and returns one persistent message","syn-turnend-guard.ts"
+  5,"the message is Rödd-encoded (customType brokk-sessionstart-nudge) and delivered","Rödd"
+  6,"compaction re-emits; shutdown retires the generation","syn-turnend-guard.ts"
+```
+
+Source routing (owned by `bin/saga-sessionstart-run.sh`):
+
+```
+sources[4]{source,action}:
+  "startup, new","full digest"
+  "clear, compact","re-emit after a proven complete startup, else full digest"
+  "resume, reload, fork","delegate to the nudge (prior context restored)"
+  "unrecognized","full digest (taking the seat twice is cheap; not taking it is the bug)"
+```
+
+## The digest (Sága)
+
+`bin/saga-session-start.sh` prints one ordered digest. It starts the runtime
+pieces the session owns:
+
+```
+saga_stages[8]{stage,does}:
+  "LOCK","acquires the per-home lock; a refused lock is read-only"
+  "BOOTSTRAP","tool floors; raises the Bifrost model bridge; realm env check"
+  "WAKE QUEUE","presents durable wakes and open decisions"
+  "SUPERVISION","the operating note for the detected harness"
+  "FLEET DIGEST","state metadata and open forge orders"
+  "CONTEXT DIGEST","realm, operator, projects, learnings (ABSENT explicit)"
+  "CRON START","starts the Nornir schedule if stopped"
+  "NEXT STEP","the closing pointer"
+```
+
+## Why it can look like "no injection"
+
+The digest is delivered as a **custom context message with `display: false`** —
+the same as the upstream distro. It is present in model context but never
+rendered in the transcript, and it does not make the model visibly act. A first
+reply of "Greetings, Allfather" is a model choosing to greet, not evidence the
+digest is missing. The cron and the lock are the observable side-effects.
+
+## Verify it
+
+```
+verify[4]{check,how}:
+  "injection happened","the session JSONL has a custom_message with customType brokk-sessionstart-nudge"
+  "lock bound","state/.lock holds the live harness pid"
+  "digest ran","state/.session-start-complete exists for this lock"
+  "cron started","bash bin/nornir-cron-start.sh --status prints running"
+```
+
+One-liners:
+
+```bash
+rg -n "brokk-sessionstart-nudge|CRON START" ~/.pi/agent/sessions/--home-zerwiz-Ymir--/*.jsonl | tail
+cat state/.lock; cat state/.session-start-complete
+bash bin/nornir-cron-start.sh --status
+```
+
+## Make it visible or auto-arm (optional divergence)
+
+The upstream distro and Ymir both keep the injection hidden and leave watcher
+arming to the agent (OpenCode arms on `session.idle`; Pi arms through the
+watch-arm tool). To diverge:
+
+```
+options[2]{change,effect}:
+  "display=true or a `/saga` command","show a one-line marker at session start"
+  "arm Sýn on boot in syn-turnend-guard.ts","supervision is live without the agent acting"
+```
+
+## Provenance
+
+Ported from the validated upstream agent-distro (read-only reference) for
+[plan 29](plans/29-brokk-distro-runtime.md); the Norse names and the Brokk/Allfather
+substitutions are ours. The upstream's own contract is its `docs/sessionstart-nudge.md`.