@awebai/oats 0.29.4 → 0.30.1

package/docs/design/operations-contract.md

@@ -1,141 +0,0 @@
-# Provider operations and inspection contract
-
-Implemented 2026-09-07 on the existing capability engine. The kernel
-resolves providers; a GUI reads one answer and calls the commands below.
-Nothing here names a provider: what a knowledge, messaging or tasks
-capability offers is what its manifest declares.
-
-## Manifest: operations
-
-```json
-"operations": {
-  "harvest": { "kind": "action", "command": "harvest", "context": "home", "description": "Promote this instance's notes into its soul" },
-  "inspect": { "kind": "view",   "command": "inspect", "context": "home", "description": "Show this instance's working knowledge" }
-}
-```
-
-`command` names one of the manifest's `commands`. `kind` is `action`
-(default) or `view`. `context` is `home` (default; runs in an instance
-home) or `scope` (runs in the config scope). Optional `args` declare
-`{name, flag, required, description}`; the runner passes `--arg name=value`
-pairs as those flags and refuses unknown or missing required ones. A view
-must answer `{ documents: [{ label, kind: "markdown"|"text", path?, text? }],
-summary? }`; the kernel validates that shape and relays it. Paths are
-provenance for the reader; the kernel reads nothing for a view. Validation
-happens when the manifest loads (`docs/capability-manifest.schema.json`).
-
-## oats inspect
-
-`oats inspect [--dir <scope>] [--soul <name> [--agents-root <abs>]] [--home
-<abs>] [--server <id>] --json` answers, in one envelope: `scope` (context,
-workspace, team, chain, agentsRoots); `souls` (persistent, local and
-packaged, each with runtime defaults, `editable {fields, instructions,
-reason}`, instances, and for the selected soul its `instructions {file,
-text, sha256, bytes, truncated, error}` capped at 256 KiB of bytes on a
-character boundary); `layers` (effective provider per layer); `capabilities`
-(installed state and `health` from the package engine, `missingRequires`,
-and separately `activation {enabled, source, target, level, provenance,
-settings, declaredAt}` plus `operations` with `available` and a `reason`);
-`knowledge` (the effective knowledge provider's operations); `snapshot` and
-`currentConfig` with `--home`; `problems`.
-
-A `--home` answer is authoritative for that home: activation, settings,
-layers and operation availability come from the home's captured bindings
-with the currently acquired manifests and current trust, marked `source:
-"snapshot"`; the live config is `currentConfig`, and `snapshot.drift`
-lists activation, settings and integrity differences. The home selects its
-own soul under its own agents root (its recorded work repository may be
-another repository); `--dir`, if given, must be the recorded repository or
-the workspace of that root, and `--agents-root` must be that root
-(`E_HOME_MISMATCH`). Without a home, `--dir` is the config context and
-same-named souls under two member roots need `--agents-root`
-(`E_SOUL_AMBIGUOUS`). The ambient `PI_AGENTS_ROOT` never redirects these
-commands. Integrity scanning happens only in this command.
-
-## oats operation run
-
-`oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir
-<scope>] [--agents-root <abs>]) [--arg k=v ...] --json` resolves the
-provider that fills `<layer>` for the home (captured bindings and settings)
-or for the soul in the scope (config), requires the operation to be declared
-(`E_OPERATION_UNKNOWN`), a provider to exist (`E_OPERATION_UNAVAILABLE`,
-also for a home-context operation without `--home`), the executable surface
-to be trusted (`E_CAPABILITY_BLOCKED`) and its `requires` to be on PATH
-(`E_CAPABILITY_REQUIRES`), then runs the provider's own command exactly as
-`oats <ns> <cmd>` would, with cwd and identity set to the selected target
-(`OATS_HOME`, `OATS_INSTANCE`, `OATS_AGENT`, `OATS_SOUL`, `OATS_ROOT`,
-`OATS_CONTEXT`, `OATS_WORKSPACE`, `OATS_OPERATION`, `OATS_SETTINGS`,
-`OATS_CLI_BIN`, team variables) and every ambient identity of the invoking
-process removed. The answer is `{ operation, capability, version, argv,
-cwd, target: {home, instance}|null, result, instance?, home? }`; top-level
-`instance`/`home` appear only when the provider's answer names something it
-launched, never the source home.
-
-The receipt must be exactly one JSON-v1 envelope on stdout from a process
-that exits 0. Otherwise the outcome is unconfirmed: `E_OPERATION_TIMEOUT`
-(240 s, below every wrapper) or `E_OPERATION_RESULT` (no valid envelope,
-contaminated output, or a success envelope contradicted by the exit
-status), with `error.details {unconfirmed: true, exit, envelope?, stderr?}`
-carrying what was observed. A provider's own `ok: false` is relayed with
-its code.
-
-## Schedules
-
-Kind `operation` `{operation: "<layer>:<name>", home}` runs `oats operation
-run <op> --home <home>` as a command job: same admission, tracking and
-reconciliation. An unconfirmed outcome keeps the slot as unknown and any
-name the provider answered is kept for `oats schedule reconcile`.
-
-## Mutations
-
-*(0.24 only — `oats use` was removed by the workspace model v2; activation is the soul's `capabilities:` + workspace defaults. Kept for history.)*
-`oats use ... --json` answers `{ capability, action: enable|disable|
-layer-none|inherit, target, layer, level, file, settings, before, after
-{..., effective}, remaining?, note?, missingRequires }`. `--inherit`
-removes only the addressed target at this level; other bindings stay and
-are listed. `use none --layer l` is a level statement and takes no soul or
-type. A layer bound to another capability at a level is never overwritten
-(`E_LAYER_BOUND` with the exact remedy).
-
-*(0.24/0.25 only — `oats soul set` was removed in 0.26.0: a soul is edited in its member repository, then `oats sync`. Kept for history.)*
-`oats soul set <name> [--dir] [--agents-root] [--runtime] [--model |
---no-model] [--yolo | --no-yolo] [--backend] [--description |
---no-description] [--instructions-file <path>] --json` edited only the given
-`soul.yaml` lines and replaced `AGENTS.md`; packaged souls were refused
-(`E_SOUL_READONLY`). The receipt carried before/after and sha256s.
-
-## Remote
-
-`inspect` and `operation` route with `--server <id>` through
-the saved route. The gate is the destination's `features` list containing
-`operations` and its `operationsApi: 1` (`E_REMOTE_INCOMPATIBLE` before
-anything is sent): `features` describes what a kernel can do locally, which
-is what runs on the host. The probe's `remote` list describes what a CLI
-can ROUTE to a server and is what a GUI checks on the local CLI before
-offering remote actions; it is not a gate on the destination. An explicit `--dir` is the exact member context and
-travels as is; `--home` is its own context; otherwise the registered
-workspace is the scope.
-
-## Replaceability
-
-`test/operation.test.mjs` runs the real CLI on the Northwind fixture and
-replaces the provider in a spawned home's module copy (what `operation run
---home` executes) with a recording provider of its own: the runner is generic
-and assumes nothing about the official provider's operations.
-
-## Workspace model (0.26.0)
-
-On a workspace deployment, and for a home whose `instance.json` records
-`modules`, `oats inspect`, `oats readiness` and `oats operation run` read the
-workspace model's own records instead of the config chain:
-- the subject is `--home` (instance.json plus its module copies) or `--soul`
-  (the soul resolved as its spawn would be), never a scope;
-- `operationsApi` is 2 (also on the run result), and each soul row carries
-  `soulsApi: 2`;
-- there is no trust gate (`E_CAPABILITY_BLOCKED` is gone);
-- no `scope`, `chain`, `activation`, `snapshot` or `currentConfig` block.
-
-The payloads are specified in
-[desktop-cli-api.md](../desktop-cli-api.md#inspect-readiness-and-operation-run-on-the-workspace-model-operationsapi-2-soulsapi-2-readinessapi-2-oats-0260).
-The sections above describe the classic path, which is removed with the classic
-config chain.

package/docs/oats-member.schema.json

@@ -1,38 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://oats.dev/schemas/member-v1.json",
-  "title": "Portable repository export index v1",
-  "description": "oats.yaml advertises definitions; a backlink is not admission or permission. Public external export indexes may omit workspace.",
-  "type": "object",
-  "required": ["schemaVersion", "exports"],
-  "additionalProperties": false,
-  "properties": {
-    "schemaVersion": { "const": 1 },
-    "workspace": { "$ref": "https://oats.dev/schemas/workspace-v1.json#/$defs/repository" },
-    "exports": {
-      "type": "object", "additionalProperties": false,
-      "properties": {
-        "souls": {
-          "type": "array", "items": {
-            "type": "object", "required": ["path", "definition"], "additionalProperties": false,
-            "properties": {
-              "path": { "$ref": "https://oats.dev/schemas/workspace-v1.json#/$defs/path" },
-              "definition": { "$ref": "https://oats.dev/schemas/workspace-v1.json#/$defs/path" },
-              "description": { "type": "string" }
-            }
-          }
-        },
-        "packages": {
-          "type": "array", "items": {
-            "type": "object", "required": ["path"], "additionalProperties": false,
-            "properties": {
-              "path": { "$ref": "https://oats.dev/schemas/workspace-v1.json#/$defs/path" },
-              "description": { "type": "string" }
-            }
-          }
-        },
-        "knowledge": { "type": "array", "items": { "$ref": "https://oats.dev/schemas/soul-v1.json#/properties/knowledge" } }
-      }
-    }
-  }
-}

package/skills/integration-authoring/SKILL.md

@@ -1,84 +0,0 @@
----
-name: integration-authoring
-description: >-
-  Route custom OATS capability-package and integration work to the framework's
-  integrations expert. Use when building, adapting, or debugging a reusable
-  capability, new tasks/messaging/knowledge core capability, oats.json manifest,
-  lifecycle hook, or operational command—not merely activating an existing
-  package. Triggers: "custom integration", "capability package", "integrate
-  our tracker", "new messaging integration", "write an oats.json".
----
-
-# Capability and integration authoring — delegate
-
-A capability package may ship skills, instance instructions, requirements,
-namespaced commands, and declared hooks. A core capability is the constrained
-kind that fills one of the knowledge, messaging or tasks positions (its
-manifest's `layer` field names which). Building either requires
-manifest, security, targeting-boundary, collision, and probe discipline; use
-the framework's **integrations-expert** soul rather than improvising.
-
-If the user only wants an existing package, declare it and give it to souls;
-no build is needed:
-
-```yaml
-# oats-workspace.yaml (host repository): declaring the package is the trust decision
-packages:
-  vendor.review: git:github.com/vendor/review@v1.0.0
-# a soul's soul.yaml, or the workspace defaults: a capability the package exports
-# (a package may export several; the soul names each one it wants)
-capabilities:
-  vendor.review: { from: package }
-```
-
-Then run `oats sync` (fetch, verify integrity, lock). The oats.setup
-capability's **oats-package-pins** skill has the procedure.
-
-## 1. Verify the expert is available
-
-Run `oats souls` in the deployment and confirm it resolves the
-`integrations-expert` soul (a member repository or package provides it). If it
-is absent, ask the human which OATS deployment owns reusable package work;
-never locate or import private kernel files.
-
-## 2. Spawn the expert against the package's repository
-
-The package lives in its own repository. Make that repository a member of the
-workspace (or use the member that already holds it), then spawn the expert on
-it:
-
-```bash
-oats spawn integrations-expert --preview \
-  --purpose <package-slug> \
-  --repo <member clone of the package repository> \
-  --work worktree \
-  --task '<capability intent; layer if any; skills/instructions/commands/hooks; external tools; which souls should get it; distribution path>'
-# review the preview, then run the same command without --preview
-```
-
-Use `--relation child --relative-to <your-instance>` only when the documented
-workflow makes the expert your child; otherwise leave the spawn unrelated. A
-package is distributed from its own repository as `oats-package/` with a
-version tag; a framework contribution belongs in the framework's repository.
-
-## 3. Brief the design boundary
-
-Tell the expert:
-
-- whether it is additive or implements exactly one of knowledge/messaging/tasks;
-- external requirements and executable surfaces (commands, hooks);
-- intended distribution and version/compatibility;
-- which souls or workspace defaults should receive it, and its settings; and
-- expected skill/instruction collisions (a duplicate skill name fails the spawn).
-
-Which souls get a capability is declared by the workspace (`defaults`) and the
-souls (`soul.yaml` `capabilities`), never in the manifest. The expert must
-test exact pi/Claude/Codex instance materialization, generated instructions,
-command gating, deterministic hooks, and the lock's integrity check as
-applicable.
-
-## 4. Hand off
-
-Report the new instance (`oats status`). The expert follows its
-package/integration craft, runs a preview-only probe, and leaves the
-`packages:` pin and the `oats sync` for the user.

package/skills/oats-support/SKILL.md

@@ -1,79 +0,0 @@
----
-name: oats-support
-description: >-
-  Route deep OATS framework questions to the framework's own expert agent.
-  Use when a user asks how OATS works beyond the basics in the oats-operate skill, why
-  the framework behaves a certain way, wants framework changes or roadmap
-  context, or hits framework bugs — the answer is to instantiate the
-  oats-expert soul from the OATS framework repo and delegate. Triggers: "ask
-  the OATS experts", "why does OATS do X", "is this an OATS bug", "OATS
-  architecture question", "who maintains this framework".
----
-
-# OATS support — delegate to the framework's expert
-
-The OATS framework repo carries its own agents. The **oats-expert** soul holds
-the framework's architecture record, decisions, and roadmap — knowledge no
-generic session has. For deep questions, instantiate it and let the user
-talk to it directly. Do not guess at framework internals yourself.
-
-## 1. Find the OATS framework repo locally
-
-Check in this order. Verify a hit by remote URL — it must point at
-`awebai/oats`:
-
-```bash
-# a) an existing pi install from a local path IS the repo
-python3 -c "import json,os; [print(p if isinstance(p,str) else p.get('source','')) for p in json.load(open(os.path.expanduser('~/.pi/agent/settings.json'))).get('packages',[])]"
-# b) common spots
-ls -d ~/oats ~/oats-framework 2>/dev/null
-# c) verify any candidate
-git -C <candidate> remote get-url origin   # expect awebai/oats
-```
-
-**Do not use a pi-managed git clone** (`~/.pi/agent/git/...`) as the home
-for agent instantiation. `pi update` resets and cleans those clones, which
-would wipe the souls' accumulated knowledge.
-
-## 2. If not found, ask the user where to clone
-
-Never pick a location silently. Suggest `~/oats` or a sibling of
-their workspace, then:
-
-```bash
-git clone https://github.com/awebai/oats <chosen-path>
-```
-
-## 3. Instantiate the oats-expert soul
-
-Spawn from the repo's own agents root (`--dir` targets it regardless of
-where your session runs):
-
-```bash
-oats spawn oats-expert --dir <repo> --purpose <short-slug> \
-  --task "<the user question, plus their workspace path and any config context>"
-```
-
-Do NOT pass `--parent` here: `--dir <repo>` targets a DIFFERENT deployment's
-agents root, and lineage is deployment-local — your instance is not
-discoverable (or renderable) in the target's hierarchy, so the spawn is
-correctly operator-origin/top-level there. Pass `--parent "$OATS_INSTANCE"`
-only when spawning within your own deployment.
-
-Include in the task briefing: the user's actual question, their workspace
-path, and relevant `oats doctor` output. The expert reads its soul knowledge
-and answers with citations.
-
-## 4. Hand off
-
-Tell the user the instance is running and how to reach it:
-`tmux attach -t pi-agents`, then pick the window. Report the window name.
-Retirement is the user's call (or yours if they delegate it) — retiring
-harvests the instance's notes back into the expert's soul.
-
-## Scope note
-
-Quick questions (home layout, roster, lifecycle, doctor) are already
-answered by the **oats-operate** skill (the `oats.core` capability) — use that first. Delegate to the expert for
-architecture, design rationale, roadmap, and anything you would otherwise
-guess about.

package/skills/skill-craft/SKILL.md

@@ -1,109 +0,0 @@
----
-name: skill-craft
-description: >-
-  How to create, evaluate, and maintain agent skills (SKILL.md files per the
-  Agent Skills standard). Use when writing a new skill, improving or debugging
-  an existing one (skill not triggering, agent ignoring instructions, skill too
-  long), turning a repeated procedure or correction into a skill, deciding
-  whether knowledge belongs in a skill versus the knowledge base versus
-  AGENTS.md, bundling scripts into skills, or evaluating whether a skill
-  actually helps. Based on the agentskills.io creator guides and Anthropic
-  best practices.
----
-
-# Skill craft — create, evaluate, maintain
-
-A skill is a directory with a `SKILL.md` (YAML frontmatter + markdown body),
-optionally `scripts/`, `references/`, `assets/`. Agents load only `name` +
-`description` at startup; the body loads **only when the description matches
-the task** — the description carries the entire burden of triggering.
-
-## Where does this knowledge belong? (decide first)
-
-- **Repeatable procedure** ("how to do X, again and again") → **skill**.
-- **Declarative fact/decision/lesson** ("what is true and why") → **OKF
-  concept** in the knowledge base (see `okf` skill). Skills may reference
-  concepts for the why.
-- **Applies to every session of this agent** (role, boundaries, core workflow)
-  → **AGENTS.md** (see `soul-craft`). Rule of thumb: AGENTS.md is loaded
-  always — keep it minimal; skills load on demand — put domain workflows there.
-
-## Creating a skill
-
-**Ground it in real expertise — never generate from thin air.** The valuable
-content is what a capable model *doesn't* already know: your APIs, your
-conventions, the corrections you had to make. Best sources: a hands-on task
-you just completed (extract the steps that worked, the corrections given, the
-formats used), runbooks, review comments, real failures and their fixes. A
-skill with generic content ("handle errors appropriately") is worthless — cut
-or ground it.
-
-**Frontmatter rules** (spec + hard-won):
-- `name`: lowercase alphanum + hyphens, ≤64 chars, **must match the directory
-  name**, no leading/trailing/double hyphens.
-- `description`: ≤1024 chars, non-empty. ⚠️ **Use a `>-` block scalar if it
-  contains any `: ` colon-space** — an unquoted colon breaks YAML parsing and
-  the skill silently fails to load. Verify new skills actually load.
-
-**Write the description for triggering** (it's the only thing the agent sees
-before deciding):
-- Imperative: "Use when..." not "This skill does...".
-- Name the **user intents** it serves, not the implementation. Include
-  trigger phrases users actually say, and cover cases where they don't name
-  the domain ("even if they don't mention X").
-- Precise beats broad: an over-broad description fires on near-miss tasks
-  and pollutes context.
-
-**Write the body for a loaded context window** — it competes with everything
-else once loaded:
-- **Only what the agent would get wrong without it.** For every line ask:
-  "would removing this cause mistakes?" No → cut.
-- ≤500 lines / ~5k tokens. Larger → move detail to `references/` and tell the
-  agent **when** to load each file ("read references/errors.md if the API
-  returns non-200"), not just that it exists.
-- **Defaults, not menus**: pick one tool/approach, mention alternatives in
-  one line. Match prescriptiveness to fragility: fragile sequences get exact
-  commands ("run exactly this"); judgment tasks get goals + why.
-- Procedures over answers: teach the approach that generalizes, with one
-  concrete worked example.
-- **Gotchas section** — often the highest-value part: concrete corrections to
-  mistakes the agent *will* make ("the /health endpoint lies; use /ready").
-- For multi-step workflows: an explicit checklist. For fragile output: a
-  template (agents pattern-match better than they follow prose). For
-  correctness-critical work: a validation loop (do → validate → fix → repeat)
-  or plan-validate-execute with a validator script.
-
-**Scripts**: when you see an agent reinventing the same logic across runs,
-write it once, test it, bundle it in `scripts/`, and reference it from the
-body with exact invocations. Prefer zero-dependency scripts; pin versions for
-`npx`/`uvx` one-offs. Scripts should print errors an agent can self-correct
-from ("field X not found — available: a, b, c").
-
-## Evaluating (before trusting)
-
-- **Trigger check**: draft ~10 realistic prompts that *should* fire the skill
-  (varied phrasing, some not naming the domain) and ~10 near-misses that
-  *shouldn't* (share keywords, need something else). Run them; the skill
-  triggered if its body was loaded. Fix the description, not the body, for
-  trigger failures.
-- **Output check**: run 2-3 real tasks **with and without** the skill. If
-  with-skill isn't clearly better, the skill isn't earning its context — cut
-  or sharpen it. Read execution traces, not just outputs: wasted steps mean
-  vague instructions, inapplicable instructions being followed, or menus
-  without defaults.
-
-## Maintaining
-
-- **Every correction is a candidate gotcha.** When a human (or reviewer)
-  corrects an agent following the skill, add the correction to the gotchas —
-  this is the single best maintenance loop.
-- Treat skills like code: prune on every edit; if the agent ignores a rule,
-  the skill is probably too long and the rule is drowning. Test behavior
-  changes by observing runs, not by rereading the text.
-- Never let a skill grow past one coherent unit of work — split like you'd
-  split a function.
-- Log skill changes in the soul's `knowledge/log.md` (`**Update**: skills/x —
-  added gotcha about …`) so knowledge history and skill history stay one
-  timeline. Knowledge maintenance and skill maintenance are the same duty:
-  declarative lessons go to OKF concepts, procedural lessons go to skills,
-  and each should link to the other.

package/skills/soul-craft/SKILL.md

@@ -1,116 +0,0 @@
----
-name: soul-craft
-description: >-
-  How to author and maintain an agent's soul — its AGENTS.md/CLAUDE.md
-  operating doc, soul.yaml config, and the balance between AGENTS.md, skills,
-  and the OKF knowledge base. Use when creating a new agent (writing its first
-  AGENTS.md), refining an existing soul that underperforms (agent ignores
-  instructions, drifts from its role, bloated operating doc), reviewing a
-  soul's setup, or deciding what goes in AGENTS.md versus a skill versus
-  knowledge. Based on the agents.md standard and Anthropic CLAUDE.md guidance.
----
-
-# Soul craft — author and maintain agent operating docs
-
-A soul's `AGENTS.md` is loaded **every session of
-every instance**. It is the most expensive real estate in the agent's context:
-everything in it taxes every task, relevant or not. The craft is keeping it
-minimal and pushing everything else to on-demand layers.
-
-**Canonical files:** `AGENTS.md` and `.agents/skills/` are the canonical
-sources; `CLAUDE.md` and `.claude/skills` must always be relative symlinks to
-them, never independent files (the spawner creates these links — if you find a
-real CLAUDE.md file diverging from AGENTS.md, that's a defect: merge and relink).
-
-## The three-layer rule
-
-| Layer | Loaded | Belongs there |
-|---|---|---|
-| **AGENTS.md** | always | Role, boundaries, the default workflow, memory pointers — only what applies to *every* session |
-| **skills/** | on demand (description match) | Domain workflows, repeatable procedures ("how") — see `skill-craft` |
-| **knowledge/** | on demand (index-first) | Facts, decisions, lessons ("what/why") — format per the knowledge capability (default okf) |
-
-The test for every AGENTS.md line: **"would removing this cause mistakes in
-most sessions?"** No → move it to a skill or a knowledge concept, or cut it.
-Bloated operating docs cause agents to ignore the rules that matter — a rule
-being ignored is usually a symptom of too many rules.
-
-## Writing a soul's AGENTS.md
-
-Structure that works (keep the whole thing short — a screen or two):
-
-1. **Role, one paragraph.** Who this agent is, what it owns, where it stops.
-   Boundaries beat capabilities: "you never merge", "you never modify the
-   assignee", "UI belongs to the ui agent" prevent more damage than feature
-   lists add value.
-2. **Operating loop.** The default shape of a work session — for a developer:
-   read ticket → plan in STATE.md → implement in ./work → verify → commit →
-   review loop → hand off. Concrete, not aspirational.
-3. **Verification.** How this agent checks its own work: the build/test/lint
-   commands that must pass, what "done" means. An agent with a check it can
-   run closes its own loop; without one, "looks done" is the only signal.
-   Include exact commands the agent can't guess (`make test-unit`, not
-   "run the tests").
-4. **Memory pointers.** Where its knowledge and state live (knowledge base
-   index, STATE.md discipline). Point, don't duplicate — the protocol lives
-   with your knowledge capability (default okf: the memory-harvest skill).
-5. **Escalation.** When to stop and ask the human or coordinator: the
-   human-gate triggers (security, authz, migrations, contract breaks),
-   plus "report to your spawner, don't self-fix" for infrastructure faults.
-
-Style rules (from the agents.md standard + field experience):
-- Write commands, not prose: `pnpm vitest run -t "<name>"` beats "run the
-  relevant test".
-- Include only what can't be inferred from the repo: conventions that differ
-  from defaults, env quirks, etiquette (branch naming, PR format).
-- Exclude: standard language conventions, file-by-file codebase tours, API
-  docs (link instead), anything that changes weekly (that's knowledge),
-  self-evident advice ("write clean code").
-- Emphasis (**IMPORTANT**, YOU MUST) sparingly — it works, and it stops
-  working when everything is emphasized.
-- The repo's own AGENTS.md (in ./work) covers repo mechanics — the soul doc
-  covers the *role*. Don't duplicate the repo doc; instruct reading it.
-
-## soul.yaml
-
-Keep honest: `description` (one line; shows in rosters and pickers), `work`
-(`worktree` for builders, `checkout` for reviewers/coordinators, `directory`
-or `workspace` where the role needs them), and the capabilities the role
-actually uses (`capabilities: { <cap>: { from: package | here | <repo key> } }`,
-plus `knowledge` / `messaging` / `tasks` slots; `none` empties one). The
-soul lives in its member repository, which is also what it works on.
-
-Runtime, model and permission bypass are not soul fields: they are chosen at
-spawn (`--harness`, `--model`, `--yolo`) or by a host's named launch
-configuration, so the same soul runs on any harness a host provides. Check a
-soul with `oats spawn <soul> --preview` before committing it.
-
-## Maintaining a soul
-
-- **Change AGENTS.md rarely and deliberately** — it defines the agent. The
-  bar: a change in how the agent fundamentally operates, proven by instance
-  experience. Day-to-day lessons go to knowledge; procedures to skills.
-- When an instance repeatedly misbehaves, diagnose in order: (1) is the rule
-  drowning in a bloated doc? → prune the doc; (2) is it ambiguous? → sharpen
-  with a command or example; (3) is it missing? → add it, minimally. Test by
-  observing the next instance's behavior, not by rereading.
-- **Prune on every edit.** Adding a line? Look for two to cut.
-- Log every soul change in `knowledge/log.md` (`**Update**: AGENTS.md — …`)
-  so the soul's evolution is reconstructible.
-- Agents never rewrite their own role or safety boundaries; soul changes that
-  alter behavior go through the human (or a documented review workflow).
-- Periodic review (worth doing when spawning feels off): does the role still
-  match reality? Do skills cover the recurring procedures? Is the knowledge
-  index current? Are the verification commands still correct?
-
-## Bootstrapping a new soul
-
-Fastest path to a *grounded* soul (never write one from imagination):
-1. Do (or supervise) the role's work once in a plain session, noting
-   corrections, commands, and conventions as you go.
-2. Distill: role/boundaries/loop/verification/escalation → AGENTS.md;
-   repeated procedures → first skills; facts and decisions → first knowledge
-   concepts.
-3. Spawn an instance on a real task; watch where it stumbles; fold the
-   corrections back (doc, skill gotcha, or concept — per the three-layer rule).
-Two rounds of this beat any amount of upfront authoring.