@zerwiz/ymir 0.1.31 → 0.1.33

package/.agents/agents/galdr.md

@@ -0,0 +1,159 @@
+---
+name: galdr
+description: Galdr — agent-CLI ergonomics and the master builder/maintainer of the Ymir (Brokk distro) runtime. Use when building, modifying, or reviewing any agent-facing CLI, or when building/maintaining any Ymir subsystem across harnesses (OpenCode, Pi, Claude Code, Cursor, Codex). Load its assets[] row for the task before editing a governed path.
+domain: brokkforge
+allowed-tools: read,write,bash,glob,grep
+---
+
+# galdr-ymirsystem — agent-CLI ergonomics — the master builder/maintainer of the runtime
+
+Lean TOON router. This file is a manifest — load only the asset that matches the
+task; never read the whole tree.
+
+```
+galdr[1]{role,operator,naming}:
+  "agent-CLI ergonomics + master builder/maintainer of the Brokk distro runtime","Allfather (Odin) — address directly; never named by an imported term","name every subsystem for the figure whose role matches its work"
+```
+
+## Surfaces
+
+Galdr is dual-surface: the same content loads as a skill (canonical) and as an
+agent (a symlink, so the two can never drift).
+
+```
+surfaces[2]{path,kind}:
+  ".agents/skills/galdr-ymirsystem/SKILL.md","skill (canonical)"
+  ".agents/agents/galdr.md","agent (symlink → the skill)"
+```
+
+## Mandate
+
+Galdr owns two things: the **10 principles** for agent-facing CLIs (TOON output,
+minimal schemas, self-correcting errors), and the **whole Ymir runtime** — how the
+Brokk distro boots under any harness, how Eindri workers are spawned, how the
+Nornir jobs run, and how it is all verified. A runtime change not reflected in
+`assets/` is an incomplete change.
+
+## Routing (load one row)
+
+```
+assets[24]{path,load_when}:
+  "assets/principles.md","the 10 CLI design principles (full doctrine)"
+  "assets/build-method.md","building/maintaining the runtime; forging a skill"
+  "assets/registry.md","skills, tools, commands, Eindri profiles, aett, schemas"
+  "assets/norse-naming.md","naming any component; the naming law + component map"
+  "assets/brokk-distro-runtime.md","the runtime spec (home, digest, lock, supervision, cron)"
+  "assets/runtime-components.md","every runtime component, interface, and env var"
+  "assets/local-models.md","Vog — local models: engines (llama.cpp, LM Studio, Ollama), detection, harness wiring, honest measurement"
+  "assets/runtime-compliance.md","runtime acceptance gates + runnable checklist"
+  "assets/memory-well.md","Mimirsbrunn/engram: the well, bridge, MCP, harness wiring, laws"
+  "assets/installation.md","first setup / install: the computed plan (bin/ymir-plan.sh), the home the operator chooses, the roots law (code in the package, the operator's things in the home), engines, hermes"
+  "assets/harness-integration/README.md","choosing a harness; adding one"
+  "assets/harness-integration/opencode.md","OpenCode adapter"
+  "assets/harness-integration/pi.md","Pi adapter"
+  "assets/harness-integration/claude-code.md","Claude Code adapter"
+  "assets/harness-integration/cursor.md","Cursor adapter"
+  "assets/harness-integration/codex.md","Codex adapter"
+  "assets/porting-upstream-to-norse.md","porting a validated upstream into Norse"
+  "assets/eindri-orchestration.md","spawn/brief/supervise Eindri workers"
+  "assets/nornir-jobs.md","the scheduler, jobs, and Runes ledger"
+  "assets/smidja.md","the smithy: install, roster/pi models, run, trace, visualizer ports, observer"
+  "assets/hlidskjalf-ui.md","any change under apps/hlidskjalf"
+  "assets/odrerir-hall.md","the Óðrerir Live Hall — apps/odrerir, :4322, its window, the planning snapshot feed (bin/hall-snapshot.sh)"
+  "assets/pi-boot-guide.md","the PI primary boot path"
+  "assets/README.md","the full asset index"
+```
+
+## Scripts (compliance + TOON)
+
+```
+scripts[2]{path,purpose}:
+  "scripts/toon-check.py","validate TOON blocks (header count/fields vs rows)"
+  "scripts/compliance-check.sh","run all gates: toon, naming, mocks, syntax, json, sync"
+```
+
+Run `bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh` before claiming any
+runtime or asset change done. Exit `1` on any FAIL.
+
+## The 10 principles (manifest)
+
+```
+principles[10]{id,name,gist}:
+  1,"TOON output","stdout TOON, ~40% under JSON; JSON internally"
+  2,"Minimal schemas","3-4 fields per list row, not 10"
+  3,"Content truncation","preview + total size + --full hint"
+  4,"Pre-computed aggregates","counts and derived state inline"
+  5,"Definitive empty states","state the zero with success context"
+  6,"Structured errors & exit codes","stdout errors, no prompts, fail loud"
+  7,"Ambient context via session integrations","hooks inject a compact dashboard"
+  8,"Content first","no-args shows live state, not help"
+  9,"Contextual disclosure","suggest the next command, parameterized"
+  10,"Consistent help","identify the tool; --help per subcommand; fast --version"
+channels[3]{stream,carries,agent_reads}:
+  "stdout","data, errors, suggestions","yes"
+  "stderr","debug, progress, diagnostics","no"
+  "exit","0 success/no-op, 1 error, 2 usage","yes"
+```
+
+Full rules, examples, and the `--version` fast path: `assets/principles.md`.
+
+## Harnesses (authoritative names)
+
+```
+harnesses[6]{harness,surface,tier,figures}:
+  "OpenCode","`.opencode/plugins/saga-sessionstart.js`, `syn-watch-arm.js`, `syn-turnend-guard.js`, `syn-pretool-check.js`, `syn-cd-check.js`","run","Sága+Sýn"
+  "Pi","`.pi/extensions/syn-turnend-guard.ts`, `gna-pi-watch.ts` (+ Vörðr supervisor)","run","Sága+Sýn+Gná+Vörðr"
+  "Claude Code","`.claude/settings.json` SessionStart + Stop","run","Sága+Sýn"
+  "Cursor","`.cursor/hooks.json` sessionStart + stop + preToolUse","run","Sága+Sýn"
+  "Codex","`.codex/hooks.json` SessionStart + PreToolUse + Stop (`[features].hooks=true`)","run","Sága+Sýn"
+  "Grok","not yet implemented","—","—"
+```
+
+Details and gotchas: `assets/harness-integration/`.
+
+## Build method (any harness, any component)
+
+```
+build[7]{id,step,detail}:
+  1,"Read the runtime spec","assets/brokk-distro-runtime.md"
+  2,"Read the harness guide","assets/harness-integration/<harness>.md"
+  3,"Reuse the runtime scripts","saga-*, syn-*, rodd-*, gleipnir-* — never reimplement"
+  4,"Wire the contract","session-open injection, watch arm, turn-end guard, pretool"
+  5,"Bind the lock to the live session","pass BROKK_SESSION_PID to Gleipnir"
+  6,"Fail closed","never launch on an unverified harness"
+  7,"Verify","bash -n, JSON parse, smoke, assets/runtime-compliance.md"
+```
+
+Full procedure, forge gates, and porting: `assets/build-method.md`.
+
+## Before you start
+
+Read the TOON specification and `AGENTS.md`. Then load the one `assets/` row the
+task needs. The operator is the **Allfather**; the house voice is Norse; an
+imported term never names a subsystem.
+
+## Acceptance (master builder)
+
+```
+acceptance[7]{id,gate}:
+  1,"Comprehensive & reusable — assets/README.md routes every task"
+  2,"Norse methodology enforced — role-matched names; operator is the Allfather"
+  3,"Every harness documented and wired"
+  4,"Runtime contract honored — injection, lock binding, guard inert-until-armed"
+  5,"Production, no mocks — no examples/placeholders in the shipped runtime"
+  6,"Verified — bash -n, JSON parse, smoke, compliance checklist"
+  7,"No drift — plan, code, and assets agree (Tyr judges)"
+```
+
+## Private data — Hodd (Rule 04)
+
+All private material lives in `hodd/` (secrets · docs · tenants · identity),
+untracked but for its guard and README. Read secrets by path with
+`bin/hodd.sh emit <file>` (`YMIR_HOARD`), never inline a value. When a governed
+path needs a secret, resolve it through Hodd. Law: `RULES/04-hoard.md`.
+
+## Operator runbooks
+
+Task-oriented guides live in `docs/runbooks/` (models · agents · Tailscale sync ·
+updates/migrations · secrets/Hodd), indexed by the `ymir` skill asset
+`assets/runbooks.md` and listed in `assets/registry.md`.

package/.agents/skills/groa-update/SKILL.md

@@ -121,6 +121,23 @@ npm_renewal[6]{step,how,why}:
   rewrite a manifest at publish time (that is how `vite.config.ts` went missing and
   every panel died on `Unexpected token '<'`).
 
+## The publish discipline — this cannot happen again
+
+Tonight cost seven publishes in an hour, one version thrown away, and a tag left on a
+build that did not carry the fix. Gróa holds four laws now:
+
+```
+publish_laws[4]{law,what_it_cost_us}:
+  "ONE version per sitting, at most","npm accepted 0.1.32 and never created it (404) — rapid publishes read as abuse, and a dropped publish looks exactly like a successful one"
+  "verify by the VERSION DOCUMENT","curl -s -o /dev/null -w '%{http_code}' …/@zerwiz/ymir/<version> — 200 or it did not happen; npm's success line is not evidence"
+  "unpack the TARBALL before calling it released","npm pack <version> and read install.sh / README.md from it: 0.1.31 was tagged latest and did NOT carry the installer fix"
+  "move the TAG, do not republish","npm dist-tag add @zerwiz/ymir@<good> latest — no new version, and every next install gets it"
+```
+
+**Why they are law:** the registry serves what was **published**, not what is on `main`.
+A publish that appears to succeed may reach no user at all; every check above tests the
+artefact — the only thing a user ever touches.
+
 ## Safety
 
 - **Fast-forward only.** Dirty, diverged, offline, or non-default-branch targets are skipped and reported, never forced or stashed. Nothing with unlanded work is ever discarded.

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## 2026-09-18 — the seat s chat left the repo, and no file names a home
+
+- **`chat/` was TRACKED in a public repo** — the seat s own conversations. It lives in the
+  home now (`$YMIR_HOME/state/chat/`, where the runtime reads it) and is gitignored: the
+  operator s words are the operator s (Rule 04).
+- **Seven files carried `/home/<user>`** — a username, in public. All seven read `$HOME` now,
+  verified by name: *zero* tracked files name a home path.
+
+## 2026-09-18 — a username was in a tracked file (corrected, not rewritten)
+
+- Two entries carried `$HOME/Ymir` — the operator s own username, in a public file.
+  They now read `$HOME`. The rule is absolute and already in the changelog: **no hardcoded
+  absolute file paths**, ever — a home path names a person, and this repo is public.
+
+## 2026-09-18 — the publish discipline, written into Gróa (this cannot happen again)
+
+- Seven publishes in an hour cost a version: npm accepted 0.1.32 and never created it
+  (404). Four laws are hers now: one version per sitting; verify by the VERSION document;
+  unpack the TARBALL before calling a release done (0.1.31 was tagged latest and did not
+  carry the installer fix); move the TAG rather than republishing.
+
+## 2026-09-18 — the one-liner writes the PATH first (it never reached .bashrc)
+
+- **The bug, exactly:** install.sh passed `"${@:-}"` to npm, which with no arguments is an
+  EMPTY argument — npm errored, and the script exited **before** the PATH block. So the
+  command was never added to .bashrc, on any machine without it already.
+- **The order is now right:** the PATH is written into the shell files FIRST, then the
+  package is installed with a proper argument array — so a failed install still leaves
+  the command reachable, and a second run picks up where the first left off.
+
 > **Frozen 2026-09-18.** This file is the historical record and is no longer
 > written to (Rule 06: a record is never rewritten). New work is recorded as fix
 > notes — one file per fix, per component — under `docs/fixes/`, written with
@@ -414,7 +444,7 @@ npm path alone to be true.
   directory` — every package had arrived, and eighteen scripts were looking in the
   clone's `apps/`. `bin/app-lib.sh` resolves a surface in either shape now.
 - **A clone and a package are one tree to the scripts.** Proven against both: the
-  five surfaces resolve from `/home/zerwiz/Ymir` and from an npm-installed
+  five surfaces resolve from `$HOME/Ymir` and from an npm-installed
   package, and `ymir raise` against a packaged tree fetches the app's
   dependencies, raises the gate API, starts Nornir cron, and brings up Bifrost and
   the well.
@@ -434,7 +464,7 @@ npm path alone to be true.
   the invite door, the seat-hall, Eir, the icons, the placement, the hall snapshot
   and the installer's own SPA and shell steps. `bin/smidja-lib.sh` delegates to it
   now, so there is one truth about where things live.
-- **Proven in both trees**: all five surfaces resolve from `/home/zerwiz/Ymir`
+- **Proven in both trees**: all five surfaces resolve from `$HOME/Ymir`
   (a clone) and from an npm-installed package. And `ymir raise` run against the
   packaged tree no longer dies — it fetches the app's dependencies, raises the
   gate API, **starts Nornir cron**, and brings up Bifrost and the well.

package/assets/reference/docs/plans/agentic-factory-implementation-plan.md

@@ -158,7 +158,7 @@
 ## Phase 1: Planning & Execution Pipeline Updates (Week 2)
 
 ### 1.1 Update `create-plan` Skill
-**File**: `/home/zerwiz/firstmate/.agents/skills/create-plan/` (or wherever it lives)
+**File**: `$HOME/firstmate/.agents/skills/create-plan/` (or wherever it lives)
 
 **Changes**:
 - Add **Layer 1 (Product)** section template: problem, metrics, announcement post, HTML mockups
@@ -177,7 +177,7 @@
 ---
 
 ### 1.2 Update `ticket-executor` Skill
-**File**: `/home/zerwiz/firstmate/.agents/skills/ticket-executor/`
+**File**: `$HOME/firstmate/.agents/skills/ticket-executor/`
 
 **Changes**:
 - **Phase 0 (NEW)**: Program Design + Vertical Slice Definition
@@ -198,7 +198,7 @@
 ---
 
 ### 1.3 Update `validate-implementation` Skill
-**File**: `/home/zerwiz/firstmate/.agents/skills/validate-implementation/`
+**File**: `$HOME/firstmate/.agents/skills/validate-implementation/`
 
 **Changes**:
 - **Live dev environment testing**: integrate with orbs/portals/preview deployments
@@ -265,7 +265,7 @@
   **Timeframe**: [e.g., 14 days post-deploy]
   **Rollback Threshold**: [e.g., < 11% for 48h]
   ```
-- `bin/measurable-goal-validate.sh` — checks goal is quantitative, not descriptive (at `/home/zerwiz/CodeP/wayofmono/bin/measurable-goal-validate.sh`)
+- `bin/measurable-goal-validate.sh` — checks goal is quantitative, not descriptive (at `$HOME/CodeP/wayofmono/bin/measurable-goal-validate.sh`)
 
 **Integration Points (DONE)**:
 - `ticket-manager`: Added `measurable_goal` to frontmatter schema + Production-Ready Standard
@@ -283,7 +283,7 @@
 ### 2.3 `logic-retention-guard` Skill (NEW)
 **Purpose**: Periodic codebase logic quizzes / agent-educates-human during long tasks
 
-**Location**: `/home/zerwiz/firstmate/.agents/skills/logic-retention-guard/`
+**Location**: `$HOME/firstmate/.agents/skills/logic-retention-guard/`
 
 **Deliverables**:
 - `SKILL.md` — trigger: long-running tasks (>30 min), after major structural changes
@@ -304,7 +304,7 @@
 ### 2.4 `multi-model-review` Skill (NEW)
 **Purpose**: Parallel Codex + Opus review for high-stakes changes
 
-**Location**: `/home/zerwiz/firstmate/.agents/skills/multi-model-review/`
+**Location**: `$HOME/firstmate/.agents/skills/multi-model-review/`
 
 **Deliverables**:
 - `SKILL.md` — trigger: PR validation for high-stakes changes (configurable: security, payments, core infra)
@@ -325,7 +325,7 @@
 ## Phase 3: Factory-Wide Integration & Polish (Week 4)
 
 ### 3.1 Update `fm-brief.sh` — Master Scaffold
-**File**: `/home/zerwiz/firstmate/bin/fm-brief.sh`
+**File**: `$HOME/firstmate/bin/fm-brief.sh`
 
 **Changes**:
 - Scaffold includes ALL four layers as mandatory sections:
@@ -344,7 +344,7 @@
 ---
 
 ### 3.2 Update `fm-session-start.sh` — Context Budget Init
-**File**: `/home/zerwiz/firstmate/bin/fm-session-start.sh`
+**File**: `$HOME/firstmate/bin/fm-session-start.sh`
 
 **Changes**:
 - Initialize context budget tracking per task
@@ -354,7 +354,7 @@
 ---
 
 ### 3.3 Update `fm-teardown.sh` — Goal Validation
-**File**: `/home/zerwiz/firstmate/bin/fm-teardown.sh`
+**File**: `$HOME/firstmate/bin/fm-teardown.sh`
 
 **Changes**:
 - Require measurable goal validation before teardown (for ship tasks)
@@ -364,7 +364,7 @@
 ---
 
 ### 3.4 Update `data/backlog.md` Schema
-**File**: `/home/zerwiz/firstmate/.tasks.toml` + backlog items
+**File**: `$HOME/firstmate/.tasks.toml` + backlog items
 
 **Changes**:
 - Add fields to task metadata:

package/assets/reference/docs/plans/phase-1-layer3-program-design.md

@@ -69,7 +69,7 @@ Added validation checks for Layer 3 (section 1e):
 Verdict: ❌ REJECTED if Layer 3 missing or incomplete.
 
 ### 3. Updated Global Plan Template
-**Location**: `/home/zerwiz/CodeP/wayofmono/thoughts/global/templates/plan-template.md` (rewritten)
+**Location**: `$HOME/CodeP/wayofmono/thoughts/global/templates/plan-template.md` (rewritten)
 
 Complete rewrite including:
 - Linked Ticket section

package/assets/reference/docs/plans/phase-3-measurable-goals.md

@@ -13,7 +13,7 @@ Dex Horthy: "An agent given a number to move will go much further than one given
 
 ## Current State
 
-- Ticket template at `/home/zerwiz/.pi/thoughts/global/templates/ticket-template.md` has Acceptance Criteria (checkboxes)
+- Ticket template at `$HOME/.pi/thoughts/global/templates/ticket-template.md` has Acceptance Criteria (checkboxes)
 - Ticket frontmatter in `ticket-manager/SKILL.md` has no `measurable_goal` field
 - Plans have "Success Criteria" but they're descriptive, not quantitative
 - No validation that goals are measurable vs descriptive

package/bin/public-guard.sh

@@ -26,7 +26,7 @@ APPEND_ONLY='(^CHANGELOG\.md$|^docs/append-only-log\.md$|^docs/plans/|^assets/re
 # Note: the public owner identity — "zerwiz" the repo holder, its public domains,
 # and the project's own repo forms — is intentionally NOT private. What stays
 # guarded: other personal names, real /home paths, tenants, and secret shapes.
-PATTERNS='(josef|lindbom|/home/zerwiz|(ghp|gho|ghs|ghr)_[A-Za-z0-9]{36}|sk-[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]+|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----)'
+PATTERNS='(josef|lindbom|$HOME|(ghp|gho|ghs|ghr)_[A-Za-z0-9]{36}|sk-[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]+|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----)'
 # Legitimate exceptions, named explicitly rather than by widening the pattern:
 #   - the public owner identity (the repo's full URL, the short owner/repo form,
 #     and the owner's public homepage — the copyright holder on every licence);
@@ -36,7 +36,7 @@ ALLOW='github\.com/zerwiz/|zerwiz/ymir|zerwiz\.org|akka://|AKIAIOSFODNN7EXAMPLE|
 leaks() {  # stdin → prints masked hits, returns 1 on any
   grep -En "$PATTERNS" \
     | grep -Ev "$ALLOW" \
-    | sed -E 's/(sk-|ghp_|AKIA|xox[a-z]*-)[A-Za-z0-9-]+/\1…/g; s#/home/zerwiz#/home/<user>#g' \
+    | sed -E 's/(sk-|ghp_|AKIA|xox[a-z]*-)[A-Za-z0-9-]+/\1…/g; s#$HOME#/home/<user>#g' \
     | head -5
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerwiz/ymir",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "description": "Ymir — the single-tenant agent operating system. One command: curl -fsSL https://raw.githubusercontent.com/zerwiz/ymir/main/install.sh | bash  ·  or: npx @zerwiz/ymir  ·  or: npm i -g @zerwiz/ymir (if `ymir` is not found, the README has the three-line PATH cure)",
   "license": "Apache-2.0",
   "homepage": "https://github.com/zerwiz/ymir",