@zerwiz/ymir 0.1.4 → 0.1.7

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 zerwiz
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/NOTICE

@@ -0,0 +1,63 @@
+Ymir
+Copyright 2026 zerwiz
+
+This product includes software developed by the Ymir project
+(https://github.com/zerwiz/ymir).
+
+Provenance — firstmate
+Ymir is a Norse-named derivative of the "firstmate" agent distro
+(https://github.com/kunchenguid/firstmate), Copyright (c) kunchenguid and
+contributors, licensed under the MIT License
+(https://github.com/kunchenguid/firstmate/blob/main/LICENSE). Portions of this
+product are derived from firstmate; its copyright and permission notice are
+retained here as that license requires. Firstmate's own names survive only as
+provenance (see .agents/skills/galdr-ymirsystem/assets/porting-upstream-to-norse.md).
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+--------------------------------------------------------------------------
+Third-party components
+--------------------------------------------------------------------------
+
+Ymir adopts validated open-source engines under its own Norse shells. Each
+component below remains under its own licence; its copyright belongs to its
+authors. Ymir does not relicense them.
+
+MIT
+  treehouse            https://github.com/kunchenguid/treehouse
+                       powers Yggdrasil (git worktrees)
+  sandcastle           https://github.com/mattpocock/sandcastle
+                       powers Utgard (ephemeral sandboxes)
+  no-mistakes          https://github.com/kunchenguid/no-mistakes
+                       powers the clean-PR gate
+  hermes-agent         https://github.com/NousResearch/hermes-agent
+                       the Hermes worker runtime
+  pi                   https://github.com/earendil-works/pi
+                       the coding harness surface
+  oh-my-pi             https://github.com/can1357/oh-my-pi
+                       prior art for the pi surface (studied)
+
+   firstmate            https://github.com/kunchenguid/firstmate
+                        the fleet — one agent, a crew
+   axi                  https://github.com/kunchenguid/axi
+                        agent-ergonomics design principles
+   lavish-axi           https://github.com/kunchenguid/lavish-axi
+                        the HTML-artifact editor (Lavish)
+   SkillOpt             https://github.com/zerwiz/SkillOpt
+                        **Gunnlöð** — skill optimization (MIT, © zerwiz)
+
+Apache License 2.0
+  pi-desktop           https://github.com/FaqFirebase/pi-desktop  (v0.1.7-alpha,
+                       commit 4a5601b)
+                       vendored and re-themed as apps/sessrumnir (Sessrumnir).
+                       Copyright 2026 Pi Desktop GUI Contributors.
+                       This is a MODIFIED fork; the changes and the upstream
+                       notice are recorded in apps/sessrumnir/NOTICE.
+  a2aproject/a2a       https://github.com/a2aproject/a2a
+                       the A2A 1.0 protocol (Apache-2.0); see its LICENSE.
+
+Studied as reference only (no code shipped): oh-my-pi, microsoft/agent-framework,
+langchain-ai/langgraph, crewAIInc/crewAI, anthropics/claude-code, openai/openai-python,
+stanfordnlp/dspy.
+
+Full licence texts and compliance status: THIRD-PARTY-LICENSES

package/README.md

@@ -1,4 +1,4 @@
-# @zerwiz/ymir
+# YMIR — The Single-Tenant Agent Operating System
 
 
 ---
@@ -10,48 +10,6 @@
 
 ---
 
-> **The front door to Ymir** — a single-operator, self-hosted, multi-agent AI runtime.
-> One command stands it up on your own machine. No hosting, no accounts.
-
-```bash
-# 1 · curl — fetch the bootstrap and run it
-curl -fsSL https://raw.githubusercontent.com/zerwiz/ymir-release/main/install.sh | bash
-
-# 2 · npx — no install, run once
-npx @zerwiz/ymir                 # add --check (report only) or --yes (unattended)
-
-# 3 · npm global — install the command, then run it
-npm i -g @zerwiz/ymir
-ymir
-
-# 4 · clone the distro and run its installer directly
-git clone https://github.com/zerwiz/ymir.git ~/.ymir
-bash ~/.ymir/bin/ymir-install.sh
-```
-
-> All four run the **same installer**. It is idempotent — run it again and it heals
-> forward. `--check` shows the plan without writing anything.
-
-This npm package is only the **bootstrap** (install.sh + a thin `ymir` bin): it
-fetches the Ymir distro and runs its installer, which provisions, self-heals and
-**validates** what it claims is running. It carries no secrets.
-
-> **Alpha** — the forge is hot and the anvil works, but expect rough edges, and do
-> not expose it as a public service yet.
-
-
----
-
-> **Who can install this today.** The Ymir distro is **private** while it is young —
-> so `curl`, `npx` and `git clone` work for **the author and invited users**, not for
-> the public (an unknown clone returns 404). If you would like access, ask:
-> [zerwiz.org](https://zerwiz.org). When the distro opens, this note goes away and
-> the four commands above become open to everyone.
-
----
-
-# YMIR — The Single-Tenant Agent Operating System
-
 > **One operator. One repo. A whole business, run by a Norse-named agent fleet.**
 
 ![Ymir — the single-tenant agent OS](assets/ymir-banner-03.png)
@@ -219,10 +177,18 @@ installable by anyone running pi.
 | Issue→PR | **Mjollnir** | autonomous fixes & PRs |
 | Process monitor | **Valhalla** | PM2/Docker supervision |
 | Skill synthesis | **Gungnir** | dynamic skill creation |
+| Skill optimization | **Gunnlöð** | trajectory-driven skill refinement |
+| Smíðja | **Smíðja** | the smithy — roster, phases, trace |
 | Session digest | **Sága** | the context injected at session open |
 | Watch / supervision | **Sýn** | watcher, guard, seat continuity |
 | Session lock | **Gleipnir** | one live session per home |
 | Scheduled jobs | **Nornir** | the fates who govern time |
+| Control-plane hub | **Vingólf** | coordination, identity, sync across substrates |
+| Live hall board | **Óðrerir** | fleet planning glass (:4322) |
+| Multi-tenant domains | **Svartalfaheim** | scoped tenant workspaces |
+| Agent ergonomics | **Galdr** | TOON output, 10 design principles |
+| Smíðja orchestrator | **Völundr** | runs Smíðja (Kaia's seat inside) |
+| MCP/A2A composition | **Hermóðr** | MCP vertical (agent→tools) + A2A horizontal |
 | Host desktop (Omarchy) | **Omarchy** | the machine Ymir runs on: monitors, scale, themes, hooks |
 | Terminal backend | **Þjazi** | agent panes — herdr (protocol 14+) or tmux |
 | Harness surface | **pi** | extensions, skills, prompt templates, packages |
@@ -253,10 +219,11 @@ the master builder; Tyr judges compliance.
 | `syn-recovery` | Sýn | stuck-worker recovery playbook |
 | `ymir` | Ymir | operate the host: update · Omarchy · Þjazi |
 | `hamr` | Hamr | per-harness adapter reference (OpenCode, Pi, Claude, Cursor, Codex) |
+| `gunnlod` | Gunnlöð | skill optimization — trajectory-driven refinement via SkillOpt |
 
 The Galdr family enforces the 10 ergonomic principles (TOON output, minimal schemas,
 self-correcting errors) and the runtime acceptance gates; run
-`bash .agents/skills/galdr-cli/scripts/compliance-check.sh` before claiming done.
+`bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh` before claiming done.
 
 ---
 
@@ -276,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/`).
 
 ---
@@ -363,7 +330,44 @@ freedom of being native to all three rather than portable to none.
 
 Point a harness (OpenCode, Pi, Claude Code, Cursor, Codex) at the repo and it takes
 the seat as **Brokk**. Read [`AGENTS.md`](AGENTS.md) for the operating laws and
-[`docs/masterplan.md`](docs/masterplan.md) for the forge orders.
+`$YMIR_HOME/docs/masterplan.md` for the forge orders.
+
+### Bringing your own machine — Windows, macOS, Linux
+
+Ymir is **Omarchy-first**: the Omarchy layer is first-class. But *first* is not
+*only*. The core is portable, and every other host gets a layer of its own.
+`bin/host-sense.sh` is the one place that looks before anything acts — distro,
+kernel, session (Wayland/X11), desktop, and what that desktop can actually do:
+
+```bash
+bin/host-sense.sh                     # THIS machine, as TOON
+bin/host-sense.sh capability tray     # yes | partial | no — for scripting
+```
+
+```
+hosts[4]{host,how_you_get_it,what_it_is}:
+  "Omarchy","bin/ymir-install.sh","the first-class layer: numbered desktops, launcher entries, the post-update hook"
+  "other Linux (Ubuntu · Fedora · Debian · Arch)","bin/ymir-install.sh","the portable core; the Omarchy layer skips cleanly, never faked"
+  "Windows","Ymir-Setup.exe — or bin/bootstrap-windows.ps1","Ubuntu on WSL2 is the host; Ymir installs inside it"
+  "macOS","Ymir Installer.command (or the .pkg) — or bin/bootstrap-macos.sh","Ubuntu in a Lima VM is the host; Ymir installs inside it"
+```
+
+Windows and macOS do not run Ymir natively: what Ymir installs is a Linux
+runtime, so those layers raise a Linux host and hand the work to
+`bin/ymir-install.sh` inside it. Each is gated on its host and skips cleanly
+everywhere else — no layer asserts a machine it is not standing on.
+
+**Build the installers** — neither needs a matching host:
+
+```bash
+packaging/build.sh --check     # what this machine can build, and with what
+packaging/build.sh --exe       # Ymir-Setup-<version>.exe   (NSIS: apt-get install nsis)
+packaging/build.sh --mac       # Ymir-<version>.pkg         (pkgbuild — Apple-only)
+```
+
+CI builds both (`.github/workflows/ymir-installers.yml`): NSIS on an Ubuntu
+runner, pkgbuild on a macOS runner. Signing and notarisation need the operator's
+own Apple and Windows credentials, so the artefacts ship unsigned.
 
 ---
 
@@ -427,7 +431,7 @@ ymir/
 ├── svartalfaheim/             # company container root (zerwiz) — future multi-user
 ├── workspace/                 # THE SINGLE TENANT: work/ · personal/ · companies/ ·
 │                              #   workspaces.yaml · projects.yaml · memory/ · INSTALL.md
-├── smidja/                    # the smithy engine + smidja.db (runs, stats, trace)
+├── apps/smidja/                 # the smithy engine + smidja.db (runs, stats, trace)
 ├── state/                     # runtime state: lock, chat/, bridges, cron
 ├── scripts/start.sh stop.sh   # raise/lower the whole system
 ├── assets/                    # art, the OS diagram, reference material
@@ -524,7 +528,17 @@ Every subsystem, component, and process is named for the figure whose role match
 its work; the operator is the **Allfather** (Odin). The house voice is Norse-natural;
 flavor may season a line, but an imported term never names a subsystem. The full
 component map lives in
-[`.agents/skills/galdr-cli/assets/norse-naming.md`](.agents/skills/galdr-cli/assets/norse-naming.md).
+[`.agents/skills/galdr-ymirsystem/assets/norse-naming.md`](.agents/skills/galdr-ymirsystem/assets/norse-naming.md).
+
+---
+
+## Built on
+
+Ymir is a Norse-named derivative of the **firstmate** agent distro
+([github.com/kunchenguid/firstmate](https://github.com/kunchenguid/firstmate),
+MIT License, © kunchenguid). Ymir adopts and retargets firstmate's mechanism under
+its open-source-first law; upstream names survive only as provenance. See
+[`NOTICE`](NOTICE).
 
 ---
 
@@ -570,17 +584,6 @@ the full day's ledger.
 
 ---
 
----
-
-## Contributing
-
-Ymir is a hobby project, and contributions are genuinely welcome — a bug report, a
-docs fix, a new skill, a whole adapter. **Please fork, branch, and open a Pull
-Request**: `main` is protected, so nothing lands without review. See
-[CONTRIBUTING.md](CONTRIBUTING.md) for the whole of it.
-
-*Be kind, keep it small, and name your subsystem true.*
-
 ## With gratitude — the people we stand on
 
 Ymir is a Norse shell over other people's excellent work. We did not build the
@@ -601,9 +604,10 @@ follow them, star them, learn from them.
 | [firstmate](https://github.com/kunchenguid/firstmate) | kunchenguid | MIT | the fleet |
 | [axi](https://github.com/kunchenguid/axi) | kunchenguid | MIT | agent-ergonomics principles |
 | [lavish-axi](https://github.com/kunchenguid/lavish-axi) | kunchenguid | MIT | the HTML-artifact editor |
+| [SkillOpt](https://github.com/zerwiz/SkillOpt) | zerwiz | MIT | **Gunnlöð** — skill optimization (trajectory-driven refinement) |
 
 Their full licence texts are bundled in [THIRD-PARTY-LICENSES](THIRD-PARTY-LICENSES),
-and the audit of every demand is in [docs/third-party-audit.md](docs/third-party-audit.md).
+and their attribution in [NOTICE](NOTICE).
 If we have benefited from your work and missed you here, tell us — we will fix it,
 loudly.
 
@@ -612,3 +616,53 @@ Thank you all. The forge is hot because you lit it.
 _Where a maker teaches on YouTube we link the channel — Matt Pocock's is
 [youtube.com/@mattpocockuk](https://www.youtube.com/@mattpocockuk). If you make a
 tutorial for a project we use, tell us and we will link yours too._
+
+---
+
+## GitHub
+
+The public repository lives at **zerwiz/ymir** on GitHub:
+[github.com/zerwiz/ymir](https://github.com/zerwiz/ymir).
+
+- **Issues** — report bugs, request features, or ask questions.
+- **Pull Requests** — all changes ship via PR; every PR requires
+  explicit Allfather approval before merge. No force-pushes. No auto-merge.
+- **Projects** — the board tracks every workstream across the hall.
+- **Actions** — CI runs `bin/secret-guard.sh` and `bin/docs-guard.sh`
+  on every push and PR. A violation blocks the build.
+
+Your own login is always your own: **never** share a token, never
+commit credentials, never use a shared account. All secrets are
+resolved from `$YMIR_HOME/secrets/platform.env` at runtime.
+
+---
+
+## Install — the four doors
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/zerwiz/ymir/main/install.sh | bash
+npx @zerwiz/ymir install          # no global install
+git clone https://github.com/zerwiz/ymir.git ~/Ymir && cd ~/Ymir && bin/ymir-install.sh
+npm install -g @zerwiz/ymir       # the CLI, global
+```
+
+**Who can install this today.** The Ymir distro is private while it is young —
+so `curl`, `npx` and `git clone` work for the author and invited users, not for
+the public (an unknown clone returns 404). If you would like access, ask:
+**zerwiz.org**. When the distro opens, this note goes away and the four commands
+above become open to everyone.
+
+**Early adopters and contributors can install now — but it is rough.** Expect
+sharp edges: the installer is honest about what it cannot do, and says so rather
+than pretending. Bring a Linux host (or let the Windows/macOS bootstraps give
+you one — see *Bringing your own machine* above), and read what the installer
+prints before you trust it.
+
+The npm package carries the runtime's `bin/` scripts and the installer; every
+`npm update -g @zerwiz/ymir` re-runs the same self-healing setup that provisions
+prerequisites, engines, and the Hlidskjalf seat. `@zerwiz/*` are the app
+packages (Hlidskjalf, Óðrerir, Sessrúmnir, Smíðja) — one per app.
+
+Private data never touches npm — all user data lives at `$YMIR_HOME` (the hoard
+at `hodd/` and the realms at `svartalfaheim/`) and syncs via the user's
+**private** GitHub repo, never a public one.

package/RULES/01-domains.md

@@ -0,0 +1,51 @@
+# Rule 01 — Domains, Houses, and Eindri
+
+**Status:** law. This rule governs every other: how the work of the house is
+divided, and who does it.
+
+## 1. A house is a company — and only that
+
+A **house** is a **company**. Nothing else is a house. **WayOf** is a house (a
+company). Use "house" and "company" interchangeably; never use "house" for a
+field of knowledge.
+
+## 2. A domain is a field of knowledge
+
+A **domain** is an area of knowledge. The Norse word for a domain is **Grein**
+(plural **Greinar**) — a *branch* or *discipline*; one grein, many greinar. Use
+“domain” and “Grein” interchangeably. A domain is named for the figure whose
+craft it is. There are eight Greinar:
+
+| Domain | Id | Covers |
+|---|---|---|
+| **Ymir Labs** | `ymirlabs` | the system itself — agents knowledgeable about Ymir |
+| **Brokk Forge** | `brokkforge` | engineering & build tooling |
+| **Runestone Labs** | `runestone` | records & compliance |
+| **Muninn Labs** | `muninn` | memory & knowledge |
+| **Dvalin** | `dvalin` | crafted tools |
+| **Utgard Studios** | `utgard` | creative |
+| **Askr** | `askr` | human-centered products |
+| **Mannheim** | `mannheim` | holding — allocated when a venture claims it |
+
+A domain is **not** a company and **not** a workspace. Domains are the axes of
+knowledge; workspaces (`personal` · `work`) are the scopes a person runs.
+
+## 3. Eindri are the specialists
+
+**Eindri** are the workers — a marketer, a builder, a researcher, a planner, a
+reviewer, a documenter, a scout, and their kin. Every Eindri names **two**
+things: its **domain** (which field it belongs to) and its **craft** (what it
+does). An Eindri is never a domain and never a house.
+
+- Agents knowledgeable about the **system itself** belong to **Ymir Labs**.
+- A marketer belongs to a knowledge/market domain; a builder to the forge; a
+  researcher to the well; and so on — by craft.
+
+## 4. The counting rule
+
+```
+one_house   = many companies?  no — a house IS a company.
+one_domain  = many Eindri.
+one_eindri  = exactly one domain.
+one_project = one workspace (company) + many domains.
+```

package/RULES/02-agents.md

@@ -0,0 +1,78 @@
+# Rule 02 — Agents (Brokk, the Eindri, and where they live)
+
+**Status:** law. Read with Rule 01 (domains · houses · Eindri).
+
+## 1. One home for agents
+
+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/agents/<name>.md` → `../../.agents/agents/<profile>.md`
+  - Pi: `.pi/agents/<profile>.md` → the same canonical files
+- **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
+
+| Kind | Who | Where |
+|---|---|---|
+| **Primary** | **Brokk** — the bellows; sole contact with the Allfather | `.agents/agents/brokk.md` |
+| **Eindri** | the workers — isolated smiths in Utgard on Yggdrasil worktrees | `.agents/agents/<name>-<craft>.md` |
+
+Every **Eindri** is a **specialist**: a marketer, a builder, a researcher, a
+planner, a reviewer, a documenter, a scout, and their kin. An Eindri is never a
+domain and never a house (Rule 01).
+
+## 3. The profile contract
+
+Every profile carries, in frontmatter:
+
+```
+name        the agent id (short, lowercase)      e.g. sindri
+norse_name  the figure the craft is named for    e.g. Sindri
+descriptor  the craft in a word                  e.g. smith
+domain      the field it belongs to (Rule 01)    e.g. brokkforge
+role        the functional role                  e.g. developer
+capabilities  the skills list
+tools       the allowed tools
+mode/model/permission   the harness binding (OpenCode) — from the canonical
+```
+
+- **Name for the role, never the mood.** The Norse figure must match the craft
+  (Sindri smiths, Bragi sings, Mímir remembers, Förseti judges).
+- **Domains:** agents knowledgeable about the **system itself** belong to
+  **Ymir Labs** (`ymirlabs`).
+- The file name is `<name>-<craft>.md`; the harness link is `<name>.md`.
+
+## 4. No mock agents
+
+- Agent ids, names, domains, models, and status must be **real** and sourced
+  (from the profile, the harness config, or live signals). **Never fabricate**
+  status, traceability, task counts, or uptime.
+- The **demo** roster (`apps/hlidskjalf/src/data/mock.ts`) is the single, clearly
+  labelled mock and appears only in demo mode; it never stands in for live data.
+
+## 5. Changing an agent
+
+1. Edit `.agents/agents/<name>-<craft>.md`.
+2. Run `bin/valknut-load.sh --all` to rebind the harness symlinks.
+3. If a governed path changed, update the owning Galdr asset in the same change
+   (compliance gate `assets`).
+
+## Permissions — bash is the hole
+
+- A profile's `permission:` block is law for that agent over the tools.
+- **A flat `bash: allow` is a total shell and overrides every `edit`/`write`
+  deny.** A read-only agent with `edit: deny` but `bash: allow` can still write,
+  delete, and reach the network. Never give a read-only agent a flat
+  `bash: allow`; give it a **pattern map** — only the read commands it needs are
+  `allow`, everything else is `ask` or `deny`.
+- Network commands (`curl`, `wget`, `ssh`, arbitrary binaries) are `ask` at
+  least. Code you do not fully trust belongs in **Utgard** (no host root, no
+  network), not on the host behind a permissive shell.
+- `mode: all` (runnable) plus a full shell is the widest door — usually not what
+  you want.
+- `bin/perm-guard.sh` flags any profile with a flat `bash: allow`
+  (`--strict` exits 1). Run it before claiming an agent change done; see the
+  runbook `docs/runbooks/agent-permissions.md`.

package/RULES/03-houses.md

@@ -0,0 +1,61 @@
+# Rule 03 — Houses (companies)
+
+**Status:** law. Read with Rule 01 (domains · houses · Eindri).
+
+## 1. A house is a company — nothing else
+
+A **house** is a **company**. The two words are the same thing; use them
+interchangeably. **WayOf is a house (a company).**
+
+A house is **not** a domain (Rule 01), **not** a workspace, and **not** a
+subsystem. The eight “Labs” — Ymir Labs, Brokk Forge, Runestone Labs, Muninn
+Labs, Dvalin, Utgard Studios, Askr, Mannheim — are **domains**, never houses.
+
+## 2. What a house owns
+
+- A house **owns projects**. Every project belongs to exactly **one** house and
+  may span many **domains** (Rule 01).
+- A house has **members**, each with a role: `owner` · `admin` · `member`.
+- A house has **products** and a **repo** (a single master registry entry,
+  `workspace/projects.yaml`).
+
+## 3. The house record
+
+Each house has one entity card:
+
+```
+companies/<house>/entity.md
+  name        the company name (the house)        e.g. WayOf
+  type        company | personal
+  owner       the owning operator                 e.g. zerwiz
+  realm       the scope it runs in
+  domains     the fields it works across          (Rule 01 ids)
+  products    what it ships
+  repo        git remote or local path
+  status      active | holding | paused | retired
+  lore_line   the one line that names the venture
+```
+
+The card lives inside the company container (`svartalfaheim/<company>/`), which
+becomes the company's Docker boundary. A work workspace mounts that container.
+
+## 4. Naming and boundaries
+
+- A house is named for the **company** (WayOf). Never name a house after a
+  domain, a subsystem, or a person.
+- **House boundaries are sacred.** A house's data never reaches across to
+  another house without explicit Allfather approval.
+- Single tenant today: the **Allfather** owns the house (WayOf); the eight
+  domains are how its knowledge is divided, not extra companies.
+
+## 5. Do not conflate
+
+```
+house   = company            (WayOf)
+domain  = field of knowledge, a Grein (the eight Labs)
+workspace = a running scope  (personal | work)
+brand   = a domain's label   (Ymir Labs, Brokk Forge, …)
+```
+
+Anything that treats a domain as a house, or a house as a domain, is a
+violation and must be corrected here first.

package/RULES/04-hoard.md

@@ -0,0 +1,97 @@
+# Rule 04 — Hodd, the private hoard, and YMIR_HOME
+
+Every private thing the Allfather holds lives in **one** place: **Hodd**
+(`hodd/`) at the repo, and **YMIR_HOME** (`$HOME/Documents/Ymir/`) as the
+shareable private repo. *Hodd* is Old Norse for a hoard — guarded, and
+never shown. The repo holds the **framework** (scaffolds, guards,
+templates); the data lives at **YMIR_HOME**, committed and pushed to a
+private GitHub repo so it can be shared between machines.
+
+## What belongs in Hodd (at the repo)
+
+Only **scaffolds and guards** live at the repo path `hodd/`:
+
+- **Guards** — `hodd/.gitignore` (inner ward, tracks only itself, README,
+  and `*.example` shapes)
+- **README** — `hodd/README.md` (this map of the hoard)
+- **Scaffolds** — `hodd/AGENTS.example.md`, `hodd/**/*.example` (templates
+  so a new operator knows what belongs)
+
+## What lives at YMIR_HOME (the real hoard)
+
+All private data is committed to the **private YMIR_HOME git repo** and
+pushed to a **private GitHub repo** for multi-machine sync. It is **NOT**
+gitignored — the user owns it and shares it between computers:
+
+| Repo location | YMIR_HOME location |
+|---|---|
+| `hodd/docs/` | `$YMIR_HOME/docs/` |
+| `hodd/secrets/` | `$YMIR_HOME/secrets/` |
+| `hodd/identity/` | `$YMIR_HOME/identity/` |
+| `hodd/tenants/` | `$YMIR_HOME/tenants/` |
+| `data/` | `$YMIR_HOME/data/` |
+| `memory/kaia.engram*` | `$YMIR_HOME/memory/` |
+
+## The law
+
+- **Hodd at the repo is untracked.** `hodd/.gitignore` tracks only the guard
+  and the README; everything beneath is private on every clone. A clone
+  must never inherit another operator's hoard.
+- **YMIR_HOME is committed.** All private data at YMIR_HOME is committed
+  to the user's **private** git repo and pushed to a private GitHub repo
+  for sync between machines. It is never gitignored (except runtime
+  ephemera like `*.wal`, `*.shm`, `smidja/`, `state/`).
+- **Secrets are referenced, never inlined.** Read them by path — `YMIR_HOARD`
+  (default `$YMIR_HOME`), `bin/hodd.sh emit <file>` to set them in a shell. A
+  value never enters a tracked file, a commit, or a document.
+- **Two wards.** `bin/secret-guard.sh` is the outer ward (pre-commit + CI);
+  `hodd/.gitignore` is the inner one. Nothing leaves without passing both.
+- **Realm boundaries are sacred.** Private data at YMIR_HOME is
+  scoped per operator; a clone must never inherit another's hoard.
+- **The public tree keeps only the framework** (lore, architecture, scaffold)
+  and `*.example` shapes.
+- A change that contradicts this rule must change the rule first (append-only;
+  never silently rewritten).
+
+## docs/ is public — plans are not
+
+`docs/` is the **public, user-facing** tree: it holds what a user of Ymir may
+read. Operator-private documents — plans, strategy, roadmaps, the masterplan,
+`append-only-log`, and project planning — belong in `hodd/docs/` at the repo
+(never `docs/`), or live at `$YMIR_HOME/docs/` in the private repo.
+
+`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.