@zerwiz/ymir 0.1.3 → 0.1.5

package/docs/research/agent-harnesses.md

@@ -0,0 +1,290 @@
+# AI Agent Harnesses — Comparison Report
+
+**Date:** 2026-09-12
+**Author:** Brokk
+**Status:** researched, written
+
+---
+
+## 1. Scope
+
+This report surveys the major open-source and vendor AI agent harnesses as of September 2026. It covers frameworks that provide **agent orchestration**, **multi-agent collaboration**, **tool use**, **memory/state management**, and **workflow control** — the core primitives that define a harness.
+
+The report is organized by **archetype** rather than vendor, because the field has converged around a few distinct patterns.
+
+---
+
+## 2. Archetype Map
+
+| # | Archetype | What it does |
+|---|-----------|-------------|
+| A | **Graph orchestrators** | Low-level state machines / directed graphs for agent loops |
+| B | **Opinionated harnesses** | Batteries-included agents that work out of the box |
+| C | **Role-based crews** | Predefined agent roles with collaborative pipelines |
+| D | **Programming frameworks** | Declarative pipelines where code replaces prompts |
+| E | **Vendor SDKs** | Model-provider toolkits with agent primitives |
+| F | **Terminal agents** | IDE/terminal-bound coding agents |
+
+---
+
+## 3. Detailed Comparison
+
+### A. Graph Orchestrators
+
+#### LangGraph (LangChain)
+
+- **Repo:** `langchain-ai/langgraph` (Python + JS)
+- **License:** MIT
+- **Stars:** ~20k+
+- **Core idea:** Build agents as stateful directed graphs (nodes = steps, edges = transitions). Inspired by Pregel and Apache Beam.
+- **Key features:**
+  - Durable execution — agents persist through failures, resume from checkpoints
+  - Human-in-the-loop — interrupt and modify state at any point
+  - Comprehensive memory — short-term working memory + long-term persistence
+  - LangSmith integration — tracing, evaluation, deployment
+  - Subgraphs — compose complex graphs from smaller ones
+- **Strengths:** Deepest production story; best debugging/observability via LangSmith; most flexible for custom workflows
+- **Weaknesses:** Steep learning curve; requires understanding graph semantics; opinionated toward LangChain ecosystem
+- **Best for:** Teams building production-grade, long-running, stateful agent systems with complex control flows
+
+#### Microsoft Agent Framework (MAF)
+
+- **Repo:** `microsoft/agent-framework` (Python + .NET + Go)
+- **License:** MIT
+- **Stars:** ~5k+
+- **Core idea:** Enterprise-ready multi-agent orchestration with graph-based workflows (sequential, concurrent, handoff, group collaboration)
+- **Key features:**
+  - Multi-language: Python, C#/.NET, Go
+  - Middleware system for request/response processing
+  - Declarative agents (YAML definitions)
+  - Agent Skills — domain-specific knowledge bases
+  - Foundry-hosted agents — deploy to Microsoft Foundry
+  - OpenTelemetry observability
+  - Checkpointing, streaming, human-in-the-loop, time-travel
+  - A2A and MCP interoperability
+- **Strengths:** Enterprise-grade; multi-language; strong Microsoft ecosystem integration; successor to both AutoGen and Semantic Kernel
+- **Weaknesses:** Newer than LangGraph; smaller community; tied to Microsoft ecosystem for full value
+- **Best for:** Enterprise teams already in the Microsoft stack; teams needing multi-language support
+
+### B. Opinionated Harnesses
+
+#### Deep Agents (LangChain)
+
+- **Repo:** `langchain-ai/deepagents` (Python + JS)
+- **License:** MIT
+- **Stars:** ~1k+
+- **Core idea:** Opinionated, batteries-included agent harness inspired by Claude Code. Works out of the box for long-horizon, multi-step work.
+- **Key features:**
+  - Sub-agents with isolated context windows
+  - Filesystem abstraction (local, sandboxed, remote)
+  - Context management (summarize long threads, offload to disk)
+  - Shell access (run commands in sandbox)
+  - Persistent memory (pluggable backends)
+  - Human-in-the-loop (approve/edit/reject tool calls)
+  - Skills (reusable behaviors loaded on demand)
+  - Tools (BYO functions or any MCP server)
+- **Strengths:** Most "just works" experience; inspired by Claude Code's design; extensible without forking; model-agnostic
+- **Weaknesses:** Newer; smaller ecosystem than LangGraph; "trust the LLM" security model
+- **Best for:** Developers who want a coding agent experience without building from scratch; teams wanting to customize a solid default
+
+#### Ymir / Brokk (this project)
+
+- **Repo:** `Way-Of/ymir` (shell scripts + Python + JS)
+- **License:** MIT
+- **Core idea:** Single-operator executive partner harness with Norse-named subsystems. Covers development, marketing, business strategy, and life execution.
+- **Key features:**
+  - Yggdrasil worktree isolation (parallel branches, zero collision)
+  - Utgard sandboxes (CPU/RAM/timeout caps, no host root, no network)
+  - A2A 1.0 collaboration backbone (Ratatoskr)
+  - Session lock bound to live harness process
+  - Nornir cron (stateless spawn → inject → execute → write → exit)
+  - Mimirsbrunn memory engine (engram store + MCP)
+  - Hlidskjalf control plane (Electron desktop + Cloudflare tunnel)
+  - Galdr CLI ergonomics (agent-facing CLI across harnesses)
+  - Smiðja agent factory (Völundr orchestrator)
+- **Strengths:** Holistic — covers the full operator lifecycle; strong isolation; Norse naming aids mental model; open-source-first
+- **Weaknesses:** Custom stack (not a general-purpose library); steep onboarding; domain-specific (single-tenant)
+- **Best for:** Single-operator executive environments where isolation, audit, and full lifecycle coverage matter
+
+### C. Role-Based Crews
+
+#### CrewAI
+
+- **Repo:** `crewAIInc/crewAI` (Python)
+- **License:** MIT
+- **Stars:** ~15k+
+- **Core idea:** Role-based AI agents that collaborate through "Crews" with precise event-driven control via "Flows"
+- **Key features:**
+  - Crews — autonomous agents with specialized roles, goals, backstories
+  - Flows — event-driven workflows combining precise control + LLM calls + Crews
+  - JSON-first project scaffolding (`crewai create crew`)
+  - Knowledge files + skills + custom tools
+  - Sequential and hierarchical processes
+  - CrewAI AMP Suite (commercial control plane with observability, governance, security)
+  - Official skills for Claude Code, Cursor, Codex, Windsurf
+- **Strengths:** Easiest onboarding for multi-agent; strong community (100k+ certified); JSON-first config is developer-friendly; commercial option available
+- **Weaknesses:** Python-only; less flexible for complex state management; commercial features behind paywall
+- **Best for:** Teams building multi-agent automation pipelines; marketing/operations workflows; rapid prototyping
+
+### D. Programming Frameworks
+
+#### DSPy
+
+- **Repo:** `stanfordnlp/dspy` (Python)
+- **License:** MIT
+- **Stars:** ~15k+
+- **Core idea:** Programming — not prompting — language models. Declarative, self-improving Python pipelines.
+- **Key features:**
+  - Declarative pipelines (compositional Python code)
+  - Self-improving via teleprompters (optimize prompts automatically)
+  - Works for classifiers, RAG pipelines, and agent loops
+  - Compiled LM calls into self-improving pipelines
+  - Assertions as computational constraints
+- **Strengths:** Best for prompt optimization; research-backed; works with any LM; declarative approach reduces brittle prompting
+- **Weaknesses:** Not a full agent harness; focused on pipeline optimization rather than orchestration; steeper learning curve for the paradigm
+- **Best for:** Teams optimizing prompt quality; RAG pipelines; research teams; anyone tired of brittle prompt engineering
+
+### E. Vendor SDKs
+
+#### OpenAI Python SDK
+
+- **Repo:** `openai/openai-python` (Python)
+- **License:** MIT
+- **Core idea:** Official Python client for OpenAI REST API (Chat Completions + Responses API)
+- **Key features:**
+  - Responses API (new standard) + Chat Completions API (legacy)
+  - Async/sync clients
+  - Streaming responses (SSE)
+  - Realtime API (text/audio via WebSocket)
+  - Workload identity authentication (Kubernetes, Azure, GCP, X.509 mTLS)
+  - Vision support (image URLs + base64)
+- **Strengths:** Direct access to OpenAI models; best-in-class model quality; comprehensive auth options
+- **Weaknesses:** No agent orchestration; no multi-agent support; vendor lock-in
+- **Best for:** Teams building on OpenAI models; low-level API access; realtime applications
+
+#### Anthropic SDK (Python)
+
+- **Repo:** `anthropics/anthropic-sdk-python` (Python)
+- **License:** MIT
+- **Core idea:** Official Python client for Claude API
+- **Key features:**
+  - Messages API
+  - Tool use / function calling
+  - Streaming
+  - Vision support
+- **Strengths:** Direct access to Claude models; strong tool-use support; clean API
+- **Weaknesses:** No agent orchestration; no multi-agent support; vendor lock-in
+- **Best for:** Teams building on Claude models; tool-use applications
+
+### F. Terminal Agents
+
+#### Claude Code (Anthropic)
+
+- **Repo:** `anthropics/claude-code` (Node.js)
+- **License:** Proprietary (source-available)
+- **Core idea:** Agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster
+- **Key features:**
+  - Terminal-bound coding agent
+  - Codebase understanding
+  - Natural language commands
+  - Git workflow handling
+  - Plugin system
+  - IDE integration
+  - @claude tagging on GitHub
+- **Strengths:** Best-in-class coding experience; deep codebase understanding; strong Anthropic model integration
+- **Weaknesses:** Proprietary; Claude-only; no multi-agent orchestration; no self-hosting
+- **Best for:** Developers who want a coding agent in their terminal; teams already using Claude
+
+#### Cursor / Codex / Windsurf
+
+- These are IDE-bound coding agents that use various model providers
+- Not open-source frameworks; proprietary products
+- Focus on single-agent coding assistance
+- Plugin ecosystems for extension
+
+---
+
+## 4. Feature Matrix
+
+| Feature | LangGraph | MAF | CrewAI | Deep Agents | DSPy | OpenAI SDK | Anthropic SDK | Claude Code | Ymir/Brokk |
+|---------|-----------|-----|--------|-------------|------|------------|---------------|-------------|------------|
+| **Multi-agent** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Graph orchestration** | ✅ | ✅ | ⚠️ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Human-in-the-loop** | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ⚠️ | ✅ |
+| **Memory/state** | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Tool use** | ✅ | ✅ | ✅ | ✅ | ❌ | ⚠️ | ✅ | ✅ | ✅ |
+| **MCP support** | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **A2A protocol** | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Sandboxing** | ❌ | ❌ | ❌ | ⚠️ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Multi-language** | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Observability** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Self-hosting** | ✅ | ✅ | ⚠️ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
+| **Model-agnostic** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
+| **Terminal agent** | ❌ | ❌ | ❌ | ⚠️ | ❌ | ❌ | ❌ | ✅ | ✅ |
+| **Cron/scheduling** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| **Audit trail** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
+
+**Legend:** ✅ = full support, ⚠️ = partial/limited, ❌ = not available
+
+---
+
+## 5. Convergence Patterns
+
+The field has converged around these patterns:
+
+1. **Graph-based orchestration** is the dominant paradigm for complex workflows (LangGraph, MAF)
+2. **Human-in-the-loop** is becoming table stakes (all major harnesses now support it)
+3. **MCP (Model Context Protocol)** is emerging as the standard tool interface (MAF, Deep Agents, Ymir)
+4. **A2A (Agent-to-Agent) 1.0** is becoming the standard for cross-agent communication (MAF, Ymir)
+5. **Model-agnostic design** is expected — harnesses should work with any LLM provider
+6. **Observability** (tracing, evaluation, debugging) is critical for production
+7. **Sandboxing** is essential for untrusted code execution
+
+---
+
+## 6. Recommendations for Ymir
+
+Ymir's current architecture already aligns well with the convergence patterns:
+
+- **A2A 1.0** (Ratatoskr) — Ymir is ahead of the curve here
+- **MCP support** — Ymir's engram store provides unscoped MCP for all harnesses
+- **Sandboxing** (Utgard) — Ymir's Utgard is more robust than most competitors
+- **Audit trail** (Runes) — unique to Ymir; no competitor provides chained audit
+- **Cron/scheduling** (Nornir) — Ymir's stateless cron is more reliable than most
+
+**Gaps to consider:**
+
+1. **LangGraph-style durable execution** — Ymir's Nornir jobs are stateless; consider adding checkpointing for long-running tasks
+2. **Human-in-the-loop** — Ymir has human-in-the-loop for code merges; consider extending to agent task approval
+3. **Observability** — Ymir's Runes provide audit; consider adding distributed tracing (OpenTelemetry) for agent execution
+4. **Multi-language** — Ymir is shell/Python/JS; consider Go support for performance-critical components
+
+---
+
+## 7. Notable Mentions
+
+- **Google Agent SDK** — Google's open-source agent framework (not found in public repos as of 2026-09)
+- **LlamaIndex** — RAG-focused framework with agent primitives
+- **AutoGen Studio** — No-code GUI for AutoGen (now in maintenance mode)
+- **OpenDevin** — Open-source coding agent (competes with Claude Code)
+- **Smithy/Smidja** — Ymir's own agent factory (Völundr orchestrator)
+
+---
+
+## 8. Sources
+
+- `github.com/microsoft/autogen` — AutoGen (maintenance mode)
+- `github.com/microsoft/agent-framework` — Microsoft Agent Framework 1.0
+- `github.com/microsoft/semantic-kernel` — Semantic Kernel (being replaced by MAF)
+- `github.com/crewAIInc/crewAI` — CrewAI
+- `github.com/langchain-ai/langgraph` — LangGraph
+- `github.com/langchain-ai/langchain` — LangChain
+- `github.com/langchain-ai/deepagents` — Deep Agents
+- `github.com/stanfordnlp/dspy` — DSPy
+- `github.com/openai/openai-python` — OpenAI Python SDK
+- `github.com/anthropics/anthropic-sdk-python` — Anthropic SDK
+- `github.com/anthropics/claude-code` — Claude Code
+
+---
+
+*Report written by Brokk. All facts verified against live repository data.*

package/docs/runbooks/README.md

@@ -0,0 +1,19 @@
+# Runbooks
+
+Task-oriented guides for operating a Ymir home. Each is written for the
+operator, not just the maintainer.
+
+```
+runbooks[8]{file,subject}:
+  "models.md","choose models per agent; local (llama.cpp) vs hosted; per-machine overlays"
+  "agents.md","Eindri profiles: where they live, how to add/run/dispatch one"
+  "agent-permissions.md","set what each agent may do — the bash gap and recommended postures"
+  "updates-and-migrations.md","update the runtime; heal old homes (bin/ymir-migrate.sh)"
+  "secrets-and-hoard.md","Hodd: secrets by path, secret-guard, rotation + history scrub"
+  "worktrees-isolation.md","Yggdrasil worktrees: isolated by default, --main opt-out, see them in Hlidskjalf, merge"
+  "a2a.md","Ratatoskr — talk between agents over A2A: engine, MCPs, addressing, injection, registration"
+  "realm-onboarding.md","onboarding a realm/tenant"
+```
+
+Related: `.agents/skills/galdr-ymirsystem/assets/installation.md` (first setup),
+`.agents/skills/galdr-ymirsystem/assets/registry.md` (inventory).

package/docs/runbooks/a2a.md

@@ -0,0 +1,91 @@
+# Runbook — A2A (Ratatoskr), talking between agents
+
+Ratatoskr is Ymir's A2A/MCP mesh: agents discover each other and exchange tasks
+over the open **A2A 1.0** protocol (JSON-RPC + SSE, Agent Cards), locally and
+across machines over Tailscale. **Way of Teams** rides the same mesh as the
+control plane.
+
+## The pieces
+
+```
+a2a[4]{piece,what,path}:
+  "engine","a2abridge — directory (discovery) · bridge (announce) · service · cert · doctor","~/.a2abridge/bin/a2abridge"
+  "MCP (mesh)","a2abridge — a2a_* tools for the agents","~/.pi/agent/mcp.json, opencode.json"
+  "MCP (control plane)","wayofteams-* — tickets, plans, memory, knowledge (NEEDS AUTH)","WOTEAMS_URL / WOTEAMS_TOKEN"
+  "Ymir front door","bin/ratatoskr.sh, bin/a2a-mcp.sh","bin/"
+```
+
+## Setup
+
+```bash
+bin/a2a-mcp.sh install     # wires the MCP servers into pi + opencode
+bin/ratatoskr.sh status    # engine + directory + served agents
+bin/ratatoskr.sh doctor    # health-check
+```
+`bin/ymir-install.sh` and `bin/brokk-update.sh` run the migration that does this.
+
+**The control plane needs auth.** In an MCP host you may see:
+```
+wayofteams-agents  Needs auth
+wayofteams-core    Needs auth
+```
+Set `WOTEAMS_URL` and `WOTEAMS_TOKEN` (from `.env.local` / your Hoard) to
+connect them. `a2abridge` should read **Connected**.
+
+## Talking
+
+**From an agent** (pi — tools come from the `a2abridge` MCP + `Way-Of/pi-a2a-adaptor`;
+the `ratatoskr-a2a` skill teaches their use):
+
+```bash
+a2a-agents                              # list peers {name,url,skills}
+a2a_call agent_url="http://host:7777/" text="…"   # task a peer; reply returns
+a2a_inbox                               # your incoming queue
+a2a_complete_task task_id="…" text="…"  # answer a task
+```
+
+**From Brokk / scripts:** `bin/a2a-talk.sh agents` and
+`bin/a2a-talk.sh send <peer> "<text>"`.
+
+## Rules that bite
+
+- **Names are NOT URLs.** `a2a_call` wants a **URL**; a peer name fails
+  `Invalid URL`. Resolve first with `a2a-agents`, then use its `url`.
+- **Delivery = injection.** An A2A task that only reaches the bridge is never
+  read; the inbound text must be **injected into the agent's chat**
+  (`herdr agent prompt <agent> "<text>"`), and the reply read back
+  (`herdr agent read`). Without injection an Eindri will not read the a2a.
+- **All four, or it fails:** transport + a live peer + delivery (injection) +
+  return. Missing any one shows as a timeout.
+
+## Reachability (registering an Eindri)
+
+An agent must **announce to the directory** to appear in `a2a-agents`:
+
+```bash
+a2abridge bridge -name <agent> -model <model> -skills <s1,s2> \
+  -directory http://127.0.0.1:7777 -advertise-host <tailnet-ip> -id <stable>
+```
+`-advertise-host` must be the machine's **Tailscale IP** (never 127.0.0.1) for
+cross-machine reach. If a peer is missing from `a2a-agents`, the bridge announced
+to the wrong directory — fix the **config/skill**, not new code.
+
+## Troubleshooting
+
+- **`Invalid URL`** — you passed a name; resolve with `a2a-agents`, then `a2a_call`.
+- **`Task … exceeded max attempts (N)`** — addressed right, never completed: no
+  live receiving agent / injection / return. Check the peer is in `a2a-agents`
+  and a receiving agent is running its bridge.
+- **No reply at all** — transport carried it; the **return path** is missing.
+- **`wayofteams-* Needs auth`** — set `WOTEAMS_TOKEN`; the mesh still works
+  standalone without it.
+
+## Status
+
+```
+a2a-today[3]{piece,state}:
+  "transport","works (messaged hermes -> reply)"
+  "delivery (injection)","works (an agent reads an injected task and answers)"
+  "directory registration + return","OPEN — a served Eindri is not yet listed in the directory"
+```
+See the private plan `$YMIR_HOME/docs/ratatoskr.md` for the registration spec.

package/docs/runbooks/agent-permissions.md

@@ -0,0 +1,99 @@
+# Runbook — setting an agent's permissions
+
+Every agent profile declares what it may do. Permissions are **law for that
+agent** — set them deliberately. The default that ships is a starting point, not
+a recommendation.
+
+## Where permissions live
+
+In the profile's frontmatter: `.agents/agents/<name>-<craft>.md`.
+
+```yaml
+---
+name: kvasir
+mode: subagent
+permission:
+  read: allow
+  glob: allow
+  grep: allow
+  edit: deny
+  write: deny
+  bash:
+    "*": ask            # everything else asks first
+    "ls *": allow
+    "rg *": allow
+    "cat *": allow
+    "git status*": allow
+    "git diff*": allow
+  skill: allow
+  webfetch: deny
+---
+```
+
+After editing, rebind:
+
+```bash
+bin/valknut-load.sh --all
+```
+
+## The one rule that matters most
+
+**A flat `bash: allow` overrides every other restriction.** An agent with
+`edit: deny` but `bash: allow` can still write files (`sed -i`, `cat > f`),
+delete them, or reach the network (`curl`, `ssh`). `edit`/`write: deny` only
+stops the *edit tool*, not the shell.
+
+So: **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`.
+
+## What each key does
+
+| Key | Controls |
+|-----|----------|
+| `read` | reading files |
+| `glob` / `grep` | finding files / searching content |
+| `edit` | the edit tool (in-place changes) |
+| `write` | creating/overwriting files |
+| `bash` | the shell — `allow` is total; prefer a pattern map |
+| `skill` | loading skills |
+| `webfetch` / `websearch` | outbound network from tools |
+| `task` | dispatching subagents |
+
+Values: `allow`, `ask`, `deny`. `bash` may also be a map of command patterns.
+
+## Recommended postures
+
+```
+postures[4]{role,read,edit/write,bash,notes}:
+  "read-only (scout, researcher, reviewer)","allow","deny","pattern map: ls/rg/cat/git-status allow, \"*\": ask","never flat allow; no curl/wget/ssh"
+  "builder (developer)","allow","allow","pattern map: package manager + build + git allow, \"*\": ask","the widest real need; still ask on unknown"
+  "content (marketer)","allow","allow","* ask; allow the editor/crawl commands only","network only where the task truly needs it"
+  "designer","allow","allow","* ask; allow the design CLI only","keep the shell narrow even when runnable"
+```
+
+## Modes
+
+`mode:` decides how an agent can be reached:
+
+- `primary` — run directly as a top-level agent.
+- `subagent` — dispatched by another agent (Task tool).
+- `all` — both. Widest; pair it with a narrow `bash`.
+
+A runnable (`all`) agent with a full shell is the biggest door — usually not
+what you want.
+
+## Network and untrusted work
+
+- Treat `curl`, `wget`, `ssh`, and arbitrary binaries as `ask` at least.
+- Code you do not fully trust belongs in **Utgard** (no host root, no network),
+  not on the host with a permissive shell.
+
+## Check your posture
+
+```bash
+bin/perm-guard.sh          # flags a flat bash:allow, especially with edit/write denied
+bin/valknut-load.sh --all  # rebind after edits
+```
+
+The rule of thumb: **grant the narrowest shell that does the job.**

package/docs/runbooks/agents.md

@@ -0,0 +1,57 @@
+# Runbook — setting up agents
+
+An **Eindri** is a worker profile. Profiles live in one canonical place and are
+symlinked into each harness.
+
+## Where agents live
+
+- **Canonical:** `.agents/agents/<name>-<craft>.md` (edit these only).
+- **Bindings:** `.opencode/agent/*.md` and `.pi/agents/*.md` are symlinks.
+
+Rebind after any change:
+
+```bash
+bin/valknut-load.sh --all
+```
+
+## A profile's frontmatter
+
+```yaml
+---
+mode: all            # primary | subagent | all  (all = runnable AND dispatchable)
+model: llama.cpp/frontend-design-expert-8b
+domain: utgard       # one of the eight Greinar (see RULES/01-domains.md)
+name: hnoss
+description: "..."
+permission:          # read/write/edit/glob/grep/bash/skill: allow|deny
+  read: allow
+  edit: allow
+ymir_tools:          # Ymir capabilities (NOT opencode built-ins; never `tools:`)
+  - opendesign
+---
+```
+
+OpenCode rejects `tools:` as a list — Ymir capabilities go under **`ymir_tools:`**.
+
+## Add an agent
+
+1. Write `.agents/agents/<name>-<craft>.md` (copy a neighbour).
+2. Give it a `model` (or leave it to inherit `default_model`) and a `domain`.
+3. `bin/valknut-load.sh --all` to bind it into OpenCode + Pi.
+4. Register it in `.agents/skills/galdr-ymirsystem/assets/registry.md` if it is durable.
+
+## Run an agent
+
+```bash
+bin/agent-run.sh hnoss "design a compact hero"   # harness+model from agents.yaml
+```
+
+Local models run through `pi`, hosted through `opencode` (see the **models**
+runbook). `mode: all` lets an agent be dispatched *and* driven directly.
+
+## Dispatch to a live pane (herdr)
+
+```bash
+bin/eindri-start.sh "design a landing page"       # one command: role -> seat -> run
+bin/eindri-start.sh "…" --pane | --tab | --space  # seat a pane / tab / workspace
+```

package/docs/runbooks/models.md

@@ -0,0 +1,69 @@
+# Runbook — setting up models
+
+Ymir runs each agent on a model you choose. **Local models run through `pi`,
+hosted models through `opencode`** — the syncer derives this, you just pick the
+model.
+
+## The one place you choose
+
+`config/agents.yaml` (private; from `config/agents.yaml.example`):
+
+```yaml
+harness:
+  local: pi
+  online: opencode
+  local_providers: [llama.cpp, llama-cpp, lmstudio]
+  providers:
+    llama.cpp: { pi: llama-cpp }      # same server, renamed per harness
+
+default_model: opencode-go/deepseek-v4.1-flash
+
+providers:
+  llama.cpp:
+    npm: "@ai-sdk/openai-compatible"
+    name: "llama-server (local)"
+    base_url: "http://127.0.0.1:8080/v1"
+    models:
+      - frontend-design-expert-8b     # bare alias; apply resolves the exact id
+
+agents:
+  hnoss: { model: "llama.cpp/frontend-design-expert-8b", primary: true }
+  brokk: { model: opencode-go/deepseek-v4.1-flash }
+```
+
+## Local models (llama.cpp)
+
+1. Start a server (llama.cpp `llama-server`) — e.g. `:8080`. Check it:
+   ```bash
+   curl -s http://127.0.0.1:8080/v1/models | head
+   ```
+2. A llama.cpp **router needs the exact served id**, e.g.
+   `frontend-design-expert-8b@q4_k_m`. Put the bare alias in the YAML; `apply`
+   asks the server and fills in the exact id.
+3. `pi` must know the provider. Verify: `pi --list-models | grep llama`.
+
+## Apply and use
+
+```bash
+bin/agents-config.sh init        # seed from template (once)
+bin/agents-config.sh resolve     # show bare alias -> exact id
+bin/agents-config.sh show        # the live combination (agent, harness, model)
+bin/agents-config.sh apply       # write into profiles + opencode.json
+bin/agent-run.sh hnoss "design a hero section"
+```
+
+## Different models on different machines
+
+Keep a per-machine overlay `config/agents.<hostname>.yaml`; it deep-merges over
+the base. Example: `config/agents.machine.example.yaml`. Override the host with
+`YMIR_AGENTS_MACHINE=omarchy-1`.
+
+## Hosted models
+
+Add the provider key to `.env.local` (e.g. `OPENCODE_GO_API_KEY`) — never inline
+a key. Models named `opencode-go/...` run through `opencode`.
+
+## Adding a model
+
+Add it under `providers.<name>.models` (or a new `providers` entry). If it's a
+new server, add the id to `.agents/skills/galdr-ymirsystem/assets/registry.md`.