@awebai/oats 0.22.0

package/docs/release-notes/v0.22.0.md

@@ -0,0 +1,180 @@
+# OATS v0.22.0
+
+OATS v0.22.0 is the first release under the OATS name. The framework release
+includes `@awebai/oats@0.22.0`, `@awebai/oats-pi@0.22.0`, and OATS Desktop
+0.22.0.
+
+The version number sits above every release of the OAS line (`@oas-framework/oas`
+0.21.2 is the latest as of this release) so that "OATS is at least OAS" holds
+numerically. This release includes the OAS 0.20.1, 0.21.1, and 0.21.2
+corrections, ported with their original authorship preserved; it does not
+include the OAS 0.21.0 remote catalog fetch (see "Not included" below).
+
+## The rename: OAS is now OATS
+
+Everything previously published as **OAS** (`@oas-framework/oas`,
+`@oas-framework/pi`, the OAS Desktop) continues as **OATS** (`@awebai/oats`,
+`@awebai/oats-pi`, OATS Desktop). The rename is a clean break: this kernel
+recognizes no `oas-*` file name, no `oas:` config key, and no `oas.*`
+capability id.
+
+Deployments created by OAS must migrate, and now can:
+
+```bash
+oats migrate --from-oas --dry-run --dir <scope>   # full plan, touches nothing
+oats migrate --from-oas --dir <scope>             # convert this scope
+```
+
+One transaction per scope: file renames (`oas-config.yaml`,
+`oas-lock.json`, capability `oas.json` manifests, soul scaffold-owner
+files), the `oas:` config key, and capability ids, then the guided package
+conversion, so the scope ends on `lockfileVersion: 2` official packages.
+Any failure restores the original OAS bytes; a second run is a no-op.
+Executable trust is re-earned after conversion. See
+[docs/migration-from-oas.md](../migration-from-oas.md).
+
+Un-migrated OAS scopes are also **loud** now: `oats doctor` names them with
+the remedy, and every `oats migrate` form exits nonzero instead of
+reporting "nothing to migrate" on a scope that is actually a pre-rename
+deployment.
+
+The migration was verified against OAS 0.20.x deployments. OAS 0.21.x scopes
+use the same file names, config keys, and capability ids, but the official
+packages they lock may be the OAS v2.0.0 line, which the OATS catalog does not
+yet carry; run the dry run first and read its plan.
+
+## Scope of the 0.18 upgrade guarantee, corrected
+
+Earlier notes said existing valid v1 locks and installed capabilities
+continue to work after a kernel upgrade. That claim holds for **OATS-named
+scopes only** (`oats-config.yaml` / `oats-lock.json`). It was never true
+for OAS-named deployments, whose files this kernel does not read; that is
+exactly what `oats migrate --from-oas` is for.
+
+## Corrections ported from OAS 0.20.1, 0.21.1, and 0.21.2
+
+These land here with the same behavior as in the OAS line, renamed.
+
+- **Own-property config handling and `__proto__` rejection.** Config
+  parsing and diagnostics no longer consult inherited `Object.prototype`
+  properties anywhere: key dispatch, capability binding, command-owner lookup,
+  skill overrides, and shape validation are own-property. YAML keys named
+  `__proto__` are refused with the typed failure `unsafe-config-key`, and
+  the offending file is named.
+- **Internal annotations cannot arrive from disk.** Underscore-prefixed
+  engine annotations (`_capabilityLock`, `_soulDir`, `_origin`, ...) are
+  stripped from every manifest and soul reader before the kernel annotates
+  them, so an on-disk document cannot assert its own provenance or silence
+  doctor's orphan warning.
+- **Config writes fail closed.** Text that would change the shape of a
+  written config is refused with `unsafe-config-value` or
+  `unsafe-config-key` instead of being written: line breaks (including
+  U+0085, U+2028, U+2029), embedded `" #"`, empty values, leading YAML
+  structure indicators, and `:` or `#` in keys. This includes the scaffolded
+  `name:` line: `oats init`, and the first `oats use` or `oats type add` in a
+  fresh scope, refuse to run in a directory whose basename cannot be stored
+  as one YAML scalar. Home directories containing `$&`-style sequences are
+  expanded literally on every write path.
+- **Typed CLI failure boundary.** `unsafe-config-key`, `unsafe-config-value`,
+  and `E_NO_CONFIG` render as one `oats:` line or one `--json` envelope
+  instead of a raw stack. Configless `oats use` reports `E_NO_CONFIG` with
+  the `oats init --raw` remedy instead of a misleading `acquired: none`.
+  Spawn no longer re-badges these as `E_SPAWN_FAILED`.
+- **Scope-exact doctor and trust.** `oats doctor` judges each installed
+  artifact against the lock of the scope that installed it, reading revised-v2
+  `capabilities` rows directly instead of the merged chain, so a chain that
+  holds one package id at two scopes with different source spellings is no
+  longer reported as `invalid-lock`, and v2-locked capabilities are no longer
+  reported as orphans. Trust evaluation reads the row from the artifact's own
+  scope.
+- **Desktop parity.** The Desktop deployment reader reads revised-v2
+  capability locks, refuses every lock shape the kernel refuses, and its
+  legacy-v1 artifact digest counts `.git` and nested lock files exactly as the
+  kernel does.
+- **Package payload is never a deployment scope.** Bare `oats install` at a
+  team scope no longer reconciles config templates that live under a package
+  manifest (`oats-package.json`) as if they were live deployments, so a
+  workspace that develops packages stops failing reconciliation for
+  directories no operator could act on. The same walk backs
+  `oats migrate --official --recursive`.
+
+## The turn record: `oats capture | recall | setup`
+
+The kernel now carries the turn record (`packages/record`): every
+conversation an agent has, Claude Code, pi, and Codex sessions plus aw
+mail and chat logs, captured as content-addressed turns in append-only,
+owner-write journals, searchable with exact provenance.
+
+```bash
+oats setup            # install capture hooks + a background watcher, idempotent
+oats capture          # one reconciliation pass (--watch, --status, --install-hint)
+oats recall <query>   # full-text search over everything captured, with provenance
+```
+
+The normative v1 format specification and its cross-language conformance
+vectors ship inside the package (`packages/record/docs/`,
+`packages/record/test/vectors/`).
+
+`oats experimental <dress|spawn|segments|mind>` exists in the repo checkout
+only, and deliberately never in this published package: the synthesis layer
+above the record is unproven by design, and its absence from the tarball is
+exactly its status.
+
+## Contract changes
+
+- `oats migrate --dry-run --json` on a scope where `oas-config.yaml` /
+  `oas-lock.json` are visible now returns `ok: false` with code
+  `oas-scope-unmigrated` instead of `ok: true` with an empty plan. OATS-named
+  scopes see no change.
+- `oats doctor --json` gains `oasScopes`, `oasRemedy`, and per-package
+  scope-exact rows. The exit code stays 0; automation gating on deployment
+  health should key on the fields, not the exit code.
+- Guided migration plan rows gain `migratesTo`, and applied rows gain
+  `migratedTo`: the package catalog's capability aliases may carry a rename
+  (`"oas.okf": { "package": "oats.okf", "capability": "oats.okf" }`). All
+  seven ids published by OAS 0.20 are mapped.
+- New typed failures: `unsafe-config-key`, `unsafe-config-value`, and
+  `E_NO_CONFIG` from configless `oats use`. Scripts matching error text
+  should match the typed codes.
+- `oats init` and first-write commands refuse directory basenames that
+  cannot be stored as one YAML scalar (see above). Earlier releases wrote
+  such names verbatim.
+
+## Desktop
+
+OATS Desktop 0.22.0 accepts a kernel with `desktopApi: 1` in the semver
+range `>=0.22.0 <0.23.0`, probing `@awebai/oats`. The old OAS Desktop
+probes for `@oas-framework/oas`; the old app and this CLI are mutually
+invisible, so upgrade the CLI and the Desktop together. macOS arm64/x64
+and Linux x64 installers are published on the GitHub Release with
+checksums and provenance; macOS builds are ad-hoc signed (not notarized).
+See [docs/desktop.md](../desktop.md) for the Gatekeeper steps.
+
+## Repository
+
+- A `LICENSE` file (MIT) now ships with the kernel; `package.json` had
+  declared MIT without one.
+- Root `npm test` is correct on a checkout without the Desktop's own
+  dependencies: it runs the Desktop suites when they are installed and
+  otherwise prints an unmissable notice with the install command.
+- A runnerless release lane (`scripts/release-lane.mjs`) mirrors the release
+  workflow off GitHub Actions, so registry publish and hosted assets never
+  depend permanently on a runner.
+
+## Not included
+
+- The OAS 0.21.0 **remote official catalog** (the kernel fetching
+  `package-catalog.json` from GitHub at resolution time). OATS resolves the
+  bundled catalog only. Held for a separate decision.
+- The `@oas-framework/*` packages are **not deprecated** by this release;
+  that action belongs to their maintainer.
+
+## Install
+
+```bash
+npm install -g @awebai/oats@latest
+pi install npm:@awebai/oats-pi@latest
+```
+
+Install matching kernel/adapter versions; they publish in lockstep from
+one tag.

package/docs/souls-and-instances.md

@@ -0,0 +1,344 @@
+# Souls and instances
+
+Souls and instances are the two layers the OATS kernel owns. A soul is the
+expert. An instance is a named incarnation of that expert, with its own ID,
+home, worktree, and lifecycle. It is not the same thing as one chat session.
+
+## Soul anatomy
+
+A soul is durable and committed. It is the part you review, improve, and keep.
+
+```text
+<agents-root>/<agent>/soul/
+  soul.yaml            # name, repo, work mode, runtime, model
+  AGENTS.md            # canonical operating doc
+  CLAUDE.md → AGENTS.md
+  skills/              # skills specific to this expert
+  knowledge/           # optional, created by the knowledge integration
+```
+
+`soul.yaml` keys:
+
+| Key | Meaning |
+|---|---|
+| `name` | Agent name. |
+| `kind` | `persistent` for committed agents, `local` for full local souls under `local-agents/` (legacy `tmp` reads as `local`). |
+| `description` | Short role description. |
+| `repo` | Target repo, absolute or relative to the agents root's parent. |
+| `work` | `worktree` or `checkout`. |
+| `runtime` | `pi` or `claude` — the harness new instances launch on; a spawn can override with `--runtime`. For `claude`, the binary is `claude` unless a local-only `oats-claude-config` file (closest one walking up from the repo; one line naming the binary, e.g. `claude-personal`) selects another — a personal machine preference for account selection, never committed. With the aweb messaging integration active, claude sessions get the `aweb-channel` plugin wired at spawn for real-time push events. |
+| `model` | Optional default model — a `provider/id[:thinking]` pattern or a comma-separated preference list (`github-copilot/x:high, anthropic/x:high`); at spawn the first entry whose provider/model is available wins (pi models probed via `pi --list-models`). For the `claude` runtime the value is translated to what the claude CLI accepts: `anthropic/<id>[:thinking]` becomes the bare `<id>`, aliases and bare `claude-*` ids pass through, other providers' entries are dropped, and nothing usable falls back to claude's own default. A spawn can override it. |
+
+A soul is model-agnostic as an artifact. Its files are plain operating docs,
+skills, and knowledge. `model` is only the default choice for new instances,
+not part of the expert's identity.
+
+A soul never runs by itself. It is incarnated as an instance. Editing a soul
+is a code change.
+
+Today the core soul artifacts are `AGENTS.md`, `skills/`, and any knowledge
+bundle the knowledge integration creates. Future integrations may add other
+expert-specific artifacts, such as Claude Code-like rule files or
+runtime-specific guidance, while keeping `AGENTS.md` canonical.
+
+## Instance anatomy
+
+An instance is transient, but it is not a single chat session. It is the
+identity of one instantiated soul while that work is alive. Several sessions,
+compactions, restarts, or model switches can happen inside the same instance
+before it is retired.
+
+An instance has a home directory, a task, and a worktree when the work mode
+needs one. Its runtime setup is composed from the canonical soul plus
+capabilities selected for that soul by the config scopes governing it.
+
+A soul can have as many instances as people need. Instances are transient and
+normally gitignored (`agents/*/instances/`). That matters for large or open
+source repos: the expert souls can travel with the repo, while different
+engineering teams instantiate those souls into their own local agent teams.
+Their instance homes, logs, notes, branches, and messaging identities do not
+collide because they are local runtime state, not shared soul state.
+
+```text
+<agents-root>/<agent>/instances/<instance>/
+  soul → <agent>/soul/             # the agent setup for this instance
+  AGENTS.md                        # generated: canonical soul + selected blocks
+  CLAUDE.md → AGENTS.md
+  .agents/skills/                  # exact soul + active capability set
+  .claude/skills → ../.agents/skills
+  work/                            # worktree, checkout symlink, or attached tree
+  TASK.md                          # briefing and task
+  instance.json                    # repo/branch, spawn lineage, capabilities, skills, instructions, trust
+  STATE.md, log.md, notes/         # optional, from the knowledge integration
+```
+
+Why some knowledge belongs in the soul (incarnation-invariant) and some in
+the instance (this task, this branch, now) — regardless of which integration
+or format you use — is covered in [knowledge theory](knowledge-theory.md).
+
+The kernel does not define memory files. If the config resolves `knowledge:
+okf`, the okf integration creates `STATE.md`, `log.md`, and `notes/`. If the
+config resolves `knowledge: none`, those files do not exist.
+
+## Lifecycle
+
+### Spawn
+
+The kernel creates the home, links the soul for reference, resolves capability
+targets, generates instance instructions, materializes the exact local skill
+set, prepares `work/`, runs active capability hooks, writes `TASK.md`, and
+launches a full coding agent session in tmux. The committed soul is unchanged.
+This is not a Claude Code subagent call; it is a normal agent process with its
+own home and tools.
+
+Examples of spawn hooks:
+
+- `oats-okf` creates episodic memory files.
+- `oats-aweb` mints a messaging identity.
+
+### Work
+
+The instance works in `./work`. With oats-okf it also keeps `STATE.md` current,
+appends milestones to `log.md`, and captures non-obvious insights in
+`notes/`.
+
+After committing with pending notes, the instance runs `oats okf harvest`
+(its okf briefing says so). oats-okf spawns a memory-harvest agent attached to
+the same work tree. The harvester promotes, merges, or drops notes, commits a
+`memory-harvest:` change, deletes processed notes, and retires itself. This is
+how long-lived instances feed their souls while still alive.
+
+### Spawning and coordinating with other agents
+
+OATS agents can run `oats spawn` when their instructions or the
+human ask them to create another expert instance. The spawned agent is another
+full OATS instance, with its own soul, home, worktree, and lifecycle.
+
+Spawn lineage is **explicit** and relation-based:
+`oats spawn --relation child|sibling|parent|unrelated --relative-to <instance>`
+declares what the new instance IS to an existing one (`--parent <instance>` is
+sugar for `--relative-to <instance> --relation child`):
+
+- **child** — nests under the anchor: `parentInstance` = anchor,
+  `spawnOrigin: instance`.
+- **parent** — the NEW instance becomes the anchor's parent: it inherits the
+  anchor's old lineage slot, and the anchor's `instance.json` is re-pointed so
+  its `parentInstance` is the new instance (a reviewer/maintainer of your work
+  sits above you). Retirement splices lineage: when any instance retires,
+  instances pointing at it (parent or sibling links) inherit its COMPLETE
+  surviving lineage — both its parent and sibling links, whichever edge type
+  pointed at it — so a retired parent-relation maintainer hands its children
+  back to the parent it displaced (restoring absorbed sibling links too), and
+  no instance is left pointing at a missing one. The splice scans every agents
+  root in the team scope, since relations can cross member repos.
+- **sibling** — a peer in the anchor's cluster: it shares the anchor's parent
+  when one exists; when the anchor is a root, the new instance records an
+  explicit `siblingInstance` link so the cluster is still derivable from
+  `oats status --json` (`parentInstance` + `siblingInstance` edges).
+- **unrelated** (default) — no link, operator-origin, top-level.
+
+Attached-mode spawns are ALWAYS children of the owner of the shared work tree
+(design decision: an attached agent serves that owner); relation flags other
+than a redundant child-of-owner are rejected. Any other spawn — including one
+from a shell that inherited
+an agent's environment variables — is operator-origin and appears top-level.
+Agents spawning sub-agents should pass `--parent "$OATS_INSTANCE"` (or the
+relation that fits).
+
+If the workspace has a messaging integration such as aweb, spawned instances
+can also receive identities and coordinate with each other automatically. The
+task layer can provide shared work state while messaging provides conversation.
+
+### Retire
+
+Retirement runs active capability retire hooks in reverse spawn order before the home disappears. The aweb
+integration self-deletes the instance identity here. For oats-okf, retirement
+is a knowledge no-op because harvest already happens after commits.
+
+`oats retire <instance> --self` lets an instance retire itself when the human
+or briefing says it is done. It runs hooks and removes the home first, then
+delays the tmux window kill for a few seconds so the instance can report
+final status.
+
+## Work modes
+
+A work mode decides what `./work` points at and what discipline the agent must
+follow. Every mode sits inside the same home/work boundary, which the generated
+instructions state first (`injects/instance-boundary.md`):
+
+- `<instance-home>` — the gitignored instance directory, `$OATS_INSTANCE_HOME` —
+  holds the brain (`AGENTS.md`, `soul/`), the task, the provenance
+  (`instance.json`) and the episodic state (`STATE.md`, `log.md`, `notes/`), and
+  is where OATS operational/lifecycle commands — and the commands of whatever
+  capabilities are active, `aw` among them when aweb messaging is — are run,
+  because they resolve scope from the working directory (`--dir <path>` to
+  target another one deliberately).
+- `<instance-home>/work` — the repository or workspace view — is where
+  repository reading, editing, building, testing, git and commits happen, to the
+  extent the mode below permits.
+- The home's `soul` link is to be treated as read-only: writes through it bypass
+  the branch and review path. Durable soul edits go through tracked paths under
+  `work/`, or through the harvester when the soul lives outside the repo.
+
+Agents move between the two as the task needs; the boundary is what each
+directory is for, not a place to settle in.
+
+### `worktree` — isolated branch
+
+`work/` is a git worktree on the instance's own branch, by default
+`agents/<instance>`.
+
+Use this for agents that will edit code or docs independently.
+
+Rules:
+
+- Build, test, and commit from `work/`, on your own branch.
+- Never run git from the repo's main checkout — it resolves to the wrong branch
+  and skips review.
+- Do not create extra worktrees. Ask for another instance if parallel work is
+  needed.
+
+A config may define `work-modes.worktree.setup`. The kernel runs that command
+inside each fresh worktree. Failures warn but do not block spawn.
+
+### `checkout` — shared current branch
+
+`work/` is a symlink to the repo checkout itself.
+
+Use this for maintainers, coordinators, auditors, or agents working on the
+repo's current state.
+
+Rules:
+
+- Stay on the currently checked-out branch.
+- Do not switch branches unless explicitly asked.
+- Avoid destructive git operations unless the human explicitly asks.
+
+### `attached` — another instance's tree
+
+`work/` points at **another instance's work tree** — same branch, same
+uncommitted state. Spawning attached requires `workDir` (the owning
+instance's `<home>/work`); it is usually a spawn-time choice for service
+agents (the memory-harvest agent uses it so its promotion commit lands on
+the source instance's branch), but a soul whose role is always-attached
+service work may declare it as identity too.
+
+Attached agents are guests: never switch branches or rewrite history, touch
+only what the briefing names, keep commits small and attributable. Retiring
+an attached instance never removes the shared tree. The packaged
+`work-attached` instruction source carries this discipline into each generated instance AGENTS.md.
+
+### `workspace` — cross-repo coordinator
+
+`work/` is a symlink to the **whole workspace** (the team scope declared by
+`team:`, else the workspace-scope config directory) — not a repo. Every
+member repo is read-context; the instance's product is coordination:
+routing, analysis, task-writing, messaging, spawning specialists.
+
+Use this for free agents that support cross-repo work but are not tied to
+any one repo — coordinators, dispatchers, architects. The soul itself still
+lives in (and is committed to) its home repo (e.g. a workspace's
+`lfx-agents/` repo); where the soul lives and where it works are decoupled.
+
+Rules:
+
+- Read freely across member repos; **never edit or commit inside them** —
+  route changes to the owning repo's agents or the human.
+- No git state operations in any member repo.
+- The one exception is the soul's own home repo: knowledge promotion writes
+  there via the knowledge layer's harvest, **as a PR on a branch**, never a
+  direct push (the OKF integration does this automatically for
+  workspace-mode instances).
+
+Spawning workspace mode requires a declared boundary (a `team:` block or a
+workspace-scope config); the instance records no branch — the workspace is
+not a git tree.
+
+## Agents root
+
+The agents root is the nearest `agents/` directory walking upward from the
+current directory. `PI_AGENTS_ROOT` overrides the search.
+
+**Where instances are stored is a separate question from where you invoked
+OATS.** Discovery finds the root from your current directory, but instance homes
+always live in the **soul-owning repo's primary checkout**: when the root you
+discovered is inside a *linked git worktree*, storage maps to the equivalent
+path in that repository's primary checkout, so homes survive the worktree, stay
+visible to the whole deployment, and never depend on where a command happened to
+run. An agent that spawns after `cd work/` reaches the same home as one spawning
+from the deployment root.
+
+Three things stay independent, and are meant to:
+
+- **Invocation** — where you ran the command;
+- **Config/package scope** — resolved from the context directory, and steerable
+  with an explicit `--dir <path>`;
+- **`work/`** — the instance's repository view, which may well be a linked
+  worktree; only *storage* is redirected, never your work tree.
+
+Roots that Git does not own are unaffected: a non-Git agents root stores
+instances exactly where it sits.
+
+Every instance is told its own home as **`OATS_INSTANCE_HOME`** (absolute), and
+instructions refer to it as `<instance-home>`. The two environments differ, so
+they are stated separately:
+
+- **Runtime session**: `OATS_INSTANCE_HOME` and `PI_AGENT_HOME` (plus
+  `OATS_INSTANCE`/`PI_AGENT_INSTANCE`). The `PI_`-prefixed names are
+  compatibility aliases for the separately published pi extension.
+- **Lifecycle hooks**: `OATS_INSTANCE_HOME` and `OATS_HOME`, alongside the rest of
+  the hook contract. `OATS_HOME` predates `OATS_INSTANCE_HOME` and is kept because
+  shipped capability hooks read it; it is **not** exported to runtime sessions.
+
+Neither is `OATS_HOME_DIR`, which is the package store root — do not conflate
+them.
+
+When placement cannot be established — Git owns the location but the repository
+cannot be read, a linked worktree whose primary checkout is missing, or a
+resolved destination outside the agent's own directory — the spawn fails closed
+with **`E_NO_CANONICAL_ROOT`** and creates nothing.
+
+### Deployment prerequisite: the agents directory must be operator-owned
+
+The canonical deployment (the agents root, `local-agents/`, and the instance
+homes under them) **must be owned by the operator and not writable by untrusted
+users or processes.** OATS validates resolved destinations and re-checks the home
+immediately before creating anything in it, but it cannot defeat a concurrent
+local attacker who already has write access there: Node offers no
+`openat`/`O_NOFOLLOW`-relative directory creation, so a path can in principle be
+swapped between the check and the creation. Anyone with that access also
+controls souls, generated instructions, hook declarations and instance state, so
+this is a deployment prerequisite — filesystem ownership and permissions — not
+something the kernel can close from inside.
+
+Default layout:
+
+```text
+<scope>/
+  agents/              # committed souls
+    docs-expert/
+      soul/
+      instances/
+  local-agents/        # local souls — same shape, never committed
+    scratch-agent/
+      soul/
+      instances/
+```
+
+`local-agents/` sits BESIDE `agents/` at the scope level and holds **full local
+souls**: complete souls (memory, skills, knowledge, instances) that are not
+committed to the repo. `oats create <name> --local` creates one — the directory
+is created on first use, and when the scope is a git repo the kernel adds
+`local-agents/` to its `.gitignore` automatically. A scope with only
+`local-agents/` is fully operable: people can use OATS with local agents alone.
+Ad hoc agents from `oats spawn --instructions-file`/`--def-file` land here too.
+Legacy nested `agents/local-agents/` and `agents/tmp-agents/` are still read
+for compatibility.
+
+Instances of a local soul receive a `local-soul` briefing: work and commits
+are normal, but soul updates are plain file edits (nothing to commit), and
+durability is the machine's — promote the soul to `agents/` when it starts to
+matter beyond one machine.
+
+Alternative agents-root layouts are planned but not built. Today the default
+layout is the only implemented layout.

package/injects/framework-workspace.md

@@ -0,0 +1,7 @@
+## OATS framework workspace (sticky)
+
+You are an OATS framework agent. The framework's generic skills govern your work:
+**okf** (knowledge bundles), **memory-harvest** (promotion judgment),
+**skill-craft** and **soul-craft** (creating/maintaining skills and souls).
+The implementation you steward lives in this repo (`extension/`, `skills/`, `injects/`), installed via `pi install`.
+Changes to the framework are proposed to the human before landing.

package/injects/instance-boundary.md

@@ -0,0 +1,43 @@
+## Your two directories
+
+**`<instance-home>` is where this session starts** — the specific gitignored OATS
+instance directory you woke up in, given to your runtime and to every lifecycle
+hook as `$OATS_INSTANCE_HOME`. It is not your user home (`~`), not the repository
+root, and not the work tree. Anything that says "your home" means this directory.
+
+- **Your brain and your state live here**: `AGENTS.md` (your composed
+  instructions), `soul/` (your durable knowledge), `TASK.md` (this task),
+  `instance.json` (what you were given and from where), and whatever working
+  state your role keeps — your knowledge layer names those files, if you have
+  one. They belong here, not in the work tree.
+- **Run OATS operational/lifecycle commands, and commands from active
+  capabilities, from instance home** — `oats status`, `oats doctor`, `oats spawn`,
+  `oats retire`, and whatever your own capabilities add; for example, when the
+  aweb messaging capability is active, run `aw` there too. They resolve their
+  scope from the directory you run them in, so running them from the work tree
+  points them at the wrong deployment. To act on a different package or config
+  scope deliberately, pass an explicit resolved path: `oats <cmd> --dir <path>`.
+- **The home's `soul` link is not your edit surface.** It is there so you can
+  READ your durable knowledge. Writing through it changes durable state outside
+  your branch, where no review sees it and nothing records what changed or why.
+  If your TASK is to change soul content that lives in this repository, that is
+  ordinary code work — do it on tracked paths under `work/`, reviewed like the
+  rest. How your own learnings reach your soul is your knowledge layer's
+  business, and its instructions below say so if you have one.
+
+**`<instance-home>/work` is your repository or workspace view** — whatever your
+work mode grants you of the code.
+
+- **Repository work happens there and only there**: reading, editing, building,
+  testing, git and commits, on repository content. Never from the main checkout
+  or from your home root.
+- **What your mode permits is the mode block's call**, immediately below. Some
+  modes are read-only, some share a tree with others, and that block is the
+  authority on which operations are yours to perform.
+- This is about where the *repository's* content lives, not a ban on writing
+  anywhere else: the episodic files above, and whatever artifacts your role
+  calls for (a report written to a temp file before mailing it, a scratch
+  script), go where your task and tooling direct.
+
+Move between the two as the task needs — the boundary is what each directory is
+*for*, not a place to settle in.

package/injects/local-soul.md

@@ -0,0 +1,19 @@
+## Local soul (uncommitted)
+
+You are a **local agent**: a full OATS soul that lives in your deployment's
+`local-agents/` directory, beside the committed `agents/` roster. The only
+difference from a committed soul is custody: **your soul is not committed to
+any repo** — it exists only on this machine, ignored by version control.
+
+What this changes — and what it does not:
+
+- **Work is unchanged.** Your `./work`, branches, commits, and task flow are
+  exactly those of any other instance. Commit your repository work normally.
+- **Custody changes delivery, not your job.** Whatever updates your soul writes
+  here directly — no git commit, no PR, because this directory is not
+  version-controlled — and the change takes effect for every future instance of
+  this soul on this machine immediately. There is no branch to review it on,
+  which is the reason the `soul` link is not yours to edit by hand.
+- **Durability is your machine's.** Your soul has no remote backup; if it
+  matters long-term, tell your human it deserves promotion to a committed
+  soul in `agents/`.

package/injects/oats.md

@@ -0,0 +1,11 @@
+## You run on OATS
+
+You are an agent instance in the OATS (Open Agent Team Specification) framework.
+You incarnate a durable soul (`./soul/`), you work in `./work/`, and you can
+be retired when your task ends. The **oats** skill teaches the essentials —
+your home layout, the agent roster (`oats status`), spawning and
+retiring instances (only when instructed), inspecting your configuration
+(`oats doctor`, `./instance.json`), and your lifecycle. **Load the oats skill
+before your first `oats` command of a session** and any time you reason about
+agents, spawning, or the framework itself — do not guess `oats` flags or
+subcommands from memory.

package/injects/work-attached.md

@@ -0,0 +1,16 @@
+## Work mode: attached
+
+Your `./work` is a symlink to **another instance's work tree** — you share
+their branch and their uncommitted state. You are a guest in their workspace.
+
+- **Never switch branches, never rebase, never reset** — the tree belongs to
+  its owner; your job is focused additions on top of their current state.
+- Keep your changes and commits **small and clearly attributable** (your
+  instance name in commit messages where ambiguity is possible).
+- Do not touch files the owner is mid-editing unless your task says so; when
+  in doubt, coordinate through your messaging layer or your spawner.
+- Retiring you never removes the shared tree — cleanup of the tree is the
+  owner's concern, not yours.
+
+This mode fits service agents (harvesters, reviewers, fixers) that operate
+on a live instance's work in flight.

package/injects/work-checkout.md

@@ -0,0 +1,12 @@
+## Work mode: checkout
+
+Your `./work` is a symlink to the repo's **shared checkout** — you are working
+in the same tree as the human and possibly other agents.
+
+- **Work on the currently checked-out branch; never switch branches unless
+  explicitly asked.**
+- No destructive git operations (reset --hard, rebase, force-push, checkout
+  of another branch) without an explicit human instruction.
+- This mode fits integrator/coordinator/advisory roles operating on the
+  repo's *current state*; if your task needs its own branch, ask your human
+  for a worktree-mode instance instead.

package/injects/work-workspace.md

@@ -0,0 +1,22 @@
+## Work mode: workspace
+
+Your `./work` is the **whole workspace** (the deployment/team scope), not a
+single repo. Every member repo under it is visible context. You are a
+cross-repo coordinator: your product is routing, analysis, and coordination —
+not code changes.
+
+- **Read freely across all member repos; never edit or commit inside them.**
+  Repo changes are routed to that repo's own agents (see `oats status --team`,
+  your task layer, or messaging) or to the human.
+- No git state operations in any member repo: no branch switching, no
+  commits, no worktrees, no resets.
+- Your own working state lives in your instance home, not in any member repo,
+  and needs no git ceremony.
+- If one of your capabilities delivers durable updates into a repo, its own
+  instructions define where and how — including whether anything is committed at
+  all, and by whom. That is its business, not an exception you take into a
+  member repo yourself.
+
+This mode fits coordinators, dispatchers, architects, and analysts whose
+scope is the workspace itself; if a task needs actual edits in one repo, ask
+for (or route to) a worktree-mode instance of that repo's agent instead.