@awebai/oats 0.25.9 → 0.26.0

package/docs/schedules.md

@@ -3,16 +3,12 @@
 A schedule launches an agent, runs an oats command, or wakes an existing
 instance on a cron. Definitions belong to a scope and are committable; every
 `oats schedule` command run anywhere inside that scope, including from an
-instance home, reads and writes the same file. On a **workspace deployment**
-(0.25, [workspaces.md](workspaces.md)) the scope is the deployment directory
-— the one holding `oats-local.yaml` and the `agents/` root (the kernel derives
-it as the directory above the agents root; a leftover `oats-config.yaml` that
-declares `team:` would still win, so remove it); scheduled spawns there
-materialize exactly like `oats spawn`. On a classic 0.24 deployment the scope
-is the team workspace (the config level that declares the team, else the
-outermost `oats-config.yaml` level). Execution belongs to the host that holds
-the scope, so a schedule on a registered server keeps running while your laptop
-sleeps.
+instance home, reads and writes the same file. The scope is the deployment
+directory ([workspaces.md](workspaces.md)) — the one holding `oats-local.yaml`
+and the `agents/` root, found walking up; with none in reach, `oats schedule`
+is `E_LOCAL_MISSING`. Scheduled spawns materialize exactly like `oats spawn`.
+Execution belongs to the host that holds the scope, so a schedule on a
+registered server keeps running while your laptop sleeps.
 
 There is no daemon. One host timer (a launchd user agent on macOS, a systemd
 user timer on Linux) runs `oats schedule tick --host` once a minute; the tick
@@ -25,15 +21,9 @@ and no queue.
 ## Files
 
 - `<workspace>/oats-schedules.json` — the definitions (`{version: 1|2, jobs:
-  {<id>: ...}}`). Version 1 is the legacy format. Adding the first explicit
-  version-2 execution upgrades the whole document to version 2 so an older
-  scheduler refuses it instead of ignoring capture policy. Existing legacy
-  entries may remain visibly unmigrated; new entries in a v2 file must declare
-  their policy. Commit the file if you want the schedule shared with the team.
-  Automatic wake creation uses this same document-version gate. Remote captured
-  mutations require advertised numeric schedule API 2 before forwarding; the old
-  feature-only gate is insufficient. Unclassifiable remote spec files also require
-  API 2. Legacy inline specs/read operations remain compatible with older hosts.
+  {<id>: ...}}`). A new file is version 1. A version-2 file (written by 0.24–0.25
+  for captured definitions) is still read; it is never rewritten to version 1.
+  Commit the file if you want the schedule shared with the team.
 - `<workspace>/.agents/schedules/state.json` — last attempted minute and
   last run per job (gitignored), plus one lock directory per running job.
 - `~/.oats/schedules/registry.json` — the host registry: which scopes the
@@ -43,9 +33,8 @@ and no queue.
   with the directory to remove, and the holder removes its own lock on exit
   and on SIGINT/SIGTERM. Definition edits take a short per-scope lock.
 
-The existing Desktop adapter can inspect/manage supported API-2 schedules, but its
-legacy editor refuses captured policy fields rather than dropping them. Full captured
-editing UI remains later Desktop work; use the explicit CLI for those definitions.
+Captured (versioned) definitions are refused (the captured/portable path was removed in 0.26):
+see [Captured definitions](#captured-definitions-removed-in-026).
 
 ## Kinds
 
@@ -55,7 +44,10 @@ editing UI remains later Desktop work; use the explicit CLI for those definition
   options `oats spawn` takes. `agentsRoot` names the exact agents root that
   holds the soul (it must lie inside the workspace and defaults to the
   workspace's own root); it is what tells same-named souls in different
-  member repositories apart. `repo` is the work repository, as `--repo`. The task gets a trailing schedule block naming the job and the
+  member repositories apart. `repo` is the work repository, as `--repo`.
+  Each run is named `<agent>-<purpose or id>-<YYYYMMDDHHMM>`. Instance names
+  are at most 64 characters, so a definition whose run names would be longer
+  is refused when it is saved (`E_SCHEDULE_INVALID`, field `purpose` or `id`). The task gets a trailing schedule block naming the job and the
   minute and ending with `oats retire --self`. An optional `wake` object
   (`{cron, tz, message}`) attaches a wake schedule to each launched instance;
   nothing is attached unless you ask.
@@ -66,8 +58,8 @@ editing UI remains later Desktop work; use the explicit CLI for those definition
   from durable context; the job follows that worker until its home is gone.
   Command return is not task completion. Avoid binding durable work to a
   disposable source-home cwd; see [OKF v2 source jobs](#okf-v2-source-jobs).
-  New exact-record command definitions use the fields described in
-  [Captured execution and recurrence](#captured-execution-and-recurrence).
+  An argv carrying a captured selector (`--deployment`, `--resolution`,
+  `--artifact-set`) is refused when saved (`E_SCHEDULE_INVALID`, field `argv`).
 - **wake** `{id, enabled, cron, tz, kind: "wake", home, message}` — every
   due minute inspects the instance at `home` through its session receipts.
   Running: `message` is delivered once with `session input`. Not running
@@ -97,87 +89,28 @@ required IANA zone; both are evaluated by the croner library. `--wake-every
 N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07, ... :56 and
 then :00 again, so 1, 5, 10, 15 and 30 give an even cadence.
 
-## Captured execution and recurrence
-
-A new captured command definition is explicitly versioned and chooses its
-recurrence policy. Its containing schedule document is version 2:
-
-```json
-{
-  "id": "retained-job",
-  "definitionVersion": 2,
-  "recurrencePolicy": "capture",
-  "kind": "command",
-  "cwd": "/absolute/workspace",
-  "argv": [
-    "oats", "example-action", "run",
-    "--deployment", "/absolute/deployment",
-    "--resolution", "sha256-...",
-    "--", "--provider-argument", "--json"
-  ],
-  "responsibleHuman": null,
-  "cron": "0 * * * *",
-  "tz": "UTC"
-}
-```
-
-The admitted-attempt wire is published as
-[`execution-capsule.schema.json`](execution-capsule.schema.json). Runtime
-validation checks selector/target agreement. A canonical `oats.json.v1` digest
-of all fields except `executionId` is the separate content witness;
-`executionId` itself is opaque admission identity.
-
-`capture` requires the explicit deployment/resolution selector pair and
-`--json` in the **saved argv**. The scheduler never appends an unrecorded
-protocol argument to a captured target. Adding or updating the definition
-derives an immutable `execution` template containing that exact target,
-resolution, input references and explicitly supplied responsible-human value.
-It contains no execution ID; `executionStatus.contentIntegrity` exposes its
-canonical content witness. At each due tick the
-scheduler verifies the retained action first, then mints a fresh opaque
-`executionId`, writes the resulting capsule into the attempt before reserving a
-slot, and only then invokes the CLI. Thus two attempts with identical content
-have the same capsule digest but remain different intents. Definition edits
-affect later admissions only; an unknown attempt, `run`, or reconciliation never
-replaces its capsule with the edited definition or today's config/lock. Captured
-attempts carry their own `schemaVersion:1`; their launch-slot lock names the same
-`executionId`. A mismatching lock or malformed/unknown attempt version stays
-unresolved and cannot dispatch. Scheduler launch also scrubs ambient
-`OATS_DEPLOYMENT` and `OATS_RESOLUTION`; only the saved argv is authority.
-
-`prepare-on-tick` is a distinct explicit policy for a genuinely new command
-tick. Its `preparation` object maps directly to the generic
-`prepareCapturedComposition({deployment,source,workspace?,member?,operator?,mode?})`
-input; scheduler code does not parse source/workspace policy itself. Production
-uses the core adapter and tests may inject the same contract. Direct-source and
-workspace-alias requests are supported; `mode` is a work-mode string, not a nested
-launch object. A complete result must preserve the requested deployment and
-returned resolution, and contain `executionBinding` and an explicit
-`responsibleHuman` (`null` means messaging was actually disabled). The scheduler
-then inserts the exact selector pair before `--`, verifies the captured action,
-mints and persists the attempt, and dispatches. Missing adapters and incomplete
-results return typed `migration-required`/`needs-configuration` with no attempt.
-A dry run never invokes preparation or mints intent. There is no current-context
-fallback. Captured spawn and
-operation definitions remain unavailable until their public captured consumer
-adapters exist. A captured wake definition is accepted only when its target
-`instance.json` has an exact `executionBinding`; the binding is copied into the
-execution template and checked again at admission without consulting source or
-configuration. Actual captured wake delivery/start remains blocked with
-`migration-required` until the parent-owned lifecycle consumer lands. Legacy
-wakes continue through the old lifecycle boundary in this release.
-
-Definitions without `definitionVersion`/`recurrencePolicy` are legacy v1
-definitions. They retain the old release behavior during migration and are not
-reported as captured execution. `list`/`show` report their `executionStatus` as
-`{kind:"legacy",capture:"unknown",migrationRequired:true}`. A captured definition
-reports only `capture:"recorded"` until action admission verifies the retained
-record and current exact approval; it does not claim launch readiness. While an
-attempt is unresolved or its confirmed launched work still holds a slot,
-`executionStatus.intent` separately reports captured, legacy-unknown or invalid
-authority, so editing a future definition cannot hide an older admitted capsule.
-Partial, malformed or unsupported versioned
-definitions/attempts are invalid or blocked, never reinterpreted as legacy.
+## Captured definitions (removed in 0.26)
+
+0.24–0.25 could save captured command definitions: `definitionVersion`,
+`recurrencePolicy` (`capture` or `prepare-on-tick`), an `execution` template and a
+`preparation` request, run against a captured deployment/resolution. That path
+was removed in 0.26:
+
+- `add` and `update` refuse any of those four keys (`E_SCHEDULE_INVALID`, the
+  key as `field`), locally and, with `--server`, before anything is forwarded.
+- A stored captured definition is invalid on its own job: every tick reports it
+  (`invalid`, "captured schedules are refused (the captured/portable path was removed in 0.26) …") and never runs it;
+  the rest of the scope's jobs continue. `list`/`show` report its
+  `executionStatus` as `{kind:"invalid", …, reason}`.
+- A captured attempt or job lock left mid-run by 0.25 is reported on that job
+  (`executionStatus.intent`, `reconcile` refuses with `E_SCHEDULE_INVALID`) and is
+  never run, adopted or released. A held captured lock keeps its launch slot
+  until the job is gone: remove it with `oats schedule remove --force <id>`, or
+  re-add it without the captured keys.
+
+Every other definition is a plain one; `list`/`show` report its `executionStatus`
+as `{kind:"legacy",capture:"unknown",migrationRequired:true}` (a released wire,
+kept as it was).
 
 ## Commands
 
@@ -202,27 +135,23 @@ running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`.
 
 ## What a run reports
 
-`launched` (spawn or command returned), `blocked` (versioned execution
-admission refused before a launch slot or child process), `active` (the instance is running;
+`launched` (spawn or command returned), `active` (the instance is running;
 a home whose retirement is pending still counts, its runtime may be alive),
 `ended` (its home is gone), `stopped` (home present, nothing running: needs
 attention, never removed for you), `launch-failed`, `unknown`, and for wake
 jobs `delivered`, `started` or `skipped`. The kernel never claims a task
 succeeded.
 
-`blocked` includes an unavailable exact record/approval or incomplete new-work
-preparation, including not-yet-qualified provider bindings. The result preserves the typed
-`errorCode`; no attempt capsule or launch lock is created.
+A run recorded by 0.24–0.25 may also read `blocked` (a captured admission that
+refused before a launch slot); 0.26 never produces it.
 
 `unknown` means the launch's side effects are unconfirmed: a command timed
 out or answered no envelope, an envelope named an instance the roster
 cannot place, or an attempt was never recorded. The job keeps its slot and
 is skipped until `oats schedule reconcile <id>`. Reconcile adopts only an
-attributable receipt: a legacy spawn job's instance is named deterministically
-for its minute. A captured command requires the SAME admitted execution ID and
-content witness, plus its explicitly recorded home and matching instance metadata;
-current-config roster lookup or a previous attempt's name cannot establish it.
-Nothing is inferred from file times. Observation validates custody before releasing
+attributable receipt: a spawn job's instance is named deterministically for its
+minute; a command job's, only the instance its answer named. Nothing is inferred
+from file times. Observation validates custody before releasing
 slots, and unresolved attempts remain held even in the crash gap before a lock
 exists. Ordinary removal refuses those attempts; force-forget remains explicit. A command whose answer named nothing stays
 unknown; check the roster and the host by hand, then
@@ -244,9 +173,8 @@ continues.
 
 `disable` never stops anything. `update` never touches a running instance,
 and while a job holds a slot or has an unresolved attempt its complete
-execution identity (including a versioned capsule), kind and target cannot
-change; cron, tz and enabled can. Legacy definitions retain their narrower
-compatibility behavior until migrated. A cold wake persists its slot before
+execution identity, kind and target cannot
+change; cron, tz and enabled can. A cold wake persists its slot before
 the session start runs and keeps it on any start exception, whatever its code
 (the kernel can refuse while recording, after the session exists); the next
 observation releases it once the runtime is proven stopped or absent, one tick
@@ -262,13 +190,7 @@ listed with its skipped reason.
 saves a wake job `wake-<instance>` bound to the new home after the spawn
 succeeded. If the spawn succeeds but the save fails, the spawn result still
 carries the full instance receipt, plus `wakeScheduleError` and a warning;
-the instance is neither hidden nor spawned again. When the spawning consumer
-supplies both the returned `executionBinding` and `responsibleHuman`,
-`saveWakeForHome` creates a version-2 captured wake from the matching binding in
-the new home. Supplying only one, or a result binding that differs from the
-home, refuses. The current parent-owned spawn caller still needs to pass these
-fields when its captured lifecycle path lands; omission retains explicit legacy
-behavior rather than inventing a binding.
+the instance is neither hidden nor spawned again.
 
 ## OKF v2 source jobs
 

package/docs/soul.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://oats.dev/schemas/soul-v2.json",
   "title": "Soul declaration v2 (soul.yaml)",
-  "description": "Authored shape only. A soul names each capability WITH WHERE IT COMES FROM (`from: here | <repo key> | package`) — a location, never a version. Provider payloads (knowledge, messaging, tasks) are opaque to the kernel; `none` empties the slot. Membership, privacy and team semantics are enforced by discovery/resolution, not here.",
+  "description": "Authored shape only. A soul names each capability WITH WHERE IT COMES FROM (`from: here | <repo key> | package`) — a location, never a version. Core-capability payloads (knowledge, messaging, tasks) are opaque to the kernel; `none` empties the slot. Membership, privacy and team semantics are enforced by discovery/resolution, not here.",
   "type": "object",
   "required": ["schemaVersion", "name", "description", "work"],
   "additionalProperties": false,
@@ -11,8 +11,9 @@
     "name": { "$ref": "#/$defs/slug" },
     "description": { "type": "string" },
     "work": { "enum": ["worktree", "checkout", "directory", "workspace"] },
-    "team": { "$ref": "#/$defs/label", "description": "Team label; overrides the repo's default from oats-membership.yaml." },
-    "private": { "type": "boolean", "description": "true → not discoverable in the workspace; usable only from its own repo." },
+    "team": { "$ref": "#/$defs/teamLabels", "description": "Team label, or a non-empty list of distinct labels (the first is the primary); overrides the repo's default from oats-membership.yaml. Each label's messaging payload reaches the provider as an eligible team (OATS_TEAMS); joining is the provider's explicit act." },
+    "private": { "type": "boolean", "deprecated": true,
+      "description": "Ignored since 0.26.0: souls have no private mode. Every soul of a confirmed member is listed and spawnable; discovery warns soul-private-ignored. Accepted so existing files still validate; remove it." },
     "capabilities": {
       "type": "object",
       "propertyNames": { "$ref": "#/$defs/capabilityName" },
@@ -31,6 +32,12 @@
   "$defs": {
     "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
     "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "teamLabels": {
+      "anyOf": [
+        { "$ref": "#/$defs/label" },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/label" } }
+      ]
+    },
     "capabilityName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
     "repoKey": { "type": "string", "pattern": "^[^\\s@/][^\\s@]*/[^\\s@]+$" },
     "fromLocation": {
@@ -49,7 +56,7 @@
     "capabilityChoice": { "anyOf": [{ "$ref": "#/$defs/capabilityRef" }, { "const": "off" }] },
     "slotPayload": {
       "anyOf": [{ "const": "none" }, { "type": "object" }],
-      "description": "Opaque provider payload, or `none` to leave the slot empty."
+      "description": "Opaque payload for the slot's core capability, or `none` to leave the slot empty."
     }
   }
 }

package/docs/souls-and-instances.md

@@ -40,7 +40,6 @@ name: release-manager                     # must equal the directory name
 description: Cuts, verifies and announces releases.
 work: worktree                            # worktree | checkout | directory | workspace
 team: engineering                         # optional label; else the repo's default (oats-membership.yaml); else unassigned
-private: true                             # optional: not discoverable; spawnable only from this repo
 
 capabilities:                             # WHERE each capability comes from — a location, never a version
   acme-release-tooling: { from: here }    # here = this soul's own repo
@@ -62,16 +61,19 @@ compatibility:                            # optional floors on PACKAGE versions
 | Key | Meaning |
 |---|---|
 | `name`, `description`, `work` | Required. `work` is the work mode below. |
-| `team` | A label declared in the workspace's `teams:`; may add `defaults.byTeam` capabilities. Never gates or restricts. |
-| `private` | `true` keeps the soul out of workspace discovery; its own repo can still spawn it. |
+| `team` | A label, or a list of labels (the first the primary), declared in the workspace's `teams:`; each may add `defaults.byTeam` capabilities and is an eligible messaging team. Never gates or restricts. |
+| `private` | **Ignored since 0.26.0:** souls have no private mode. Every soul of a confirmed member is listed and spawnable; a soul that still carries the field gets a `soul-private-ignored` warning. Remove it. |
 | `capabilities` | `<cap>: { from: here \| <repo key> \| package }` or `<cap>: off`. Composed over `defaults.<slot>` ⊕ `defaults.capabilities` ⊕ `defaults.byTeam[team]`; the soul wins. |
 | `knowledge` / `messaging` / `tasks` | The slot's provider payload (true of every instance of the soul), or `none`. Merged with `oats-local.yaml` `settings.<cap>` and `spawn --provider <cap>`; the provider's `binding` contract validates the result — and refuses keys it does not declare. For `oats.okf` 2.1.3 the admitted keys are its settings (`bindings-file`, `state-dir`, `harvest-runtime`, `harvest-model`); the soul's `owns`/`reads` live in `souls/<name>/okf.json`, which OKF reads from the soul directory. |
 | `compatibility` | `<cap>: <semver range>` checked against the locked package version (`E_COMPATIBILITY`). |
 
 Schema: [`soul.schema.json`](soul.schema.json). Not in v2: `kind`, `type`,
-`repo`, `runtime`, `model`, `requires`, `source:`, `stores.inherit`. Model and
-runtime are spawn-time / launch-configuration choices (`--runtime`, `--model`,
-`--launch-config`), not soul identity: a soul is model-agnostic as an artifact.
+`repo`, `runtime`, `model`, `backend`, `yolo`, `launch-config`, `children`,
+`requires`, `source:`, `stores.inherit`. Runtime, model, backend, yolo and the
+launch configuration are spawn-time host choices (`--runtime`, `--model`,
+`--backend`, `--yolo`, `--launch-config`, or a launch configuration in
+`oats-local.yaml`), not soul identity: a soul is model-agnostic as an artifact.
+A child-spawn policy is a spawn flag too (`--no-child-spawns`).
 
 A soul never runs by itself. It is incarnated as an instance. Editing a soul
 is a code change, reviewed in its repo.
@@ -84,9 +86,10 @@ souls — is ordinary capability content: **`oats.core`** (package
 `defaults.capabilities: { oats.core: { from: package } }`; a soul may say
 `oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
 knowledge an onboarding expert needs. Neither is kernel magic; the kernel still
-composes its own instance-boundary and work-mode briefings — and, when
-`oats.core` resolves as a module, leaves the "You run on OATS" briefing to the
-module's inject (one block, not two; 0.25.2).
+composes its own instance-boundary and work-mode briefings, and the "You run
+on OATS" briefing is `oats.core`'s inject (the kernel ships no copy since 0.26:
+a soul without `oats.core` gets no OATS operating instructions, and
+`oats doctor --soul` says so).
 
 ## Instance anatomy
 
@@ -102,7 +105,6 @@ full copy** of every capability the soul resolved to:
 
 ```text
 <agents-root>/<soul>/instances/<instance>/
-  soul → ../../soul                # the soul, for reference (read-only)
   AGENTS.md                        # generated: soul AGENTS.md + kernel/work-mode blocks + each module's inject
   CLAUDE.md → AGENTS.md
   .agents/skills/                  # canonical skill tree — soul skills + <capability>/<skill>/ full copies
@@ -111,7 +113,7 @@ full copy** of every capability the soul resolved to:
   .oats/modules/<capability>/      # the whole capability: oats.json, bin/, injects/, skills/ (hooks run from here)
   work/                            # worktree, checkout symlink, attached tree, or private directory
   TASK.md                          # briefing and task
-  instance.json                    # provenance (below)
+  instance.json                    # provenance (below); `soulDir` = the soul directory hooks get as OATS_SOUL
   STATE.md, log.md, notes/         # optional, from the knowledge capability
 ```
 
@@ -187,6 +189,11 @@ oats spawn release-manager --preview --json                        # decide ever
 oats spawn release-manager --provider oats.aweb identity.source=/abs/path/to/retained/.aw   # instance-level payload
 ```
 
+An instance is named `<soul>-<purpose>` by default, or exactly `--name <slug>`.
+Names are unique per deployment (a workspace-model deployment has one agents
+root): a derived name in use gets `-2`, `-3`…; an explicit `--name` in use is
+refused (`E_INSTANCE_NAME_TAKEN`).
+
 From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
 discovers the workspace over its remotes and confirms membership → finds the
 soul among the confirmed members (or `external:`; an ambiguous bare name is
@@ -194,7 +201,7 @@ soul among the confirmed members (or `external:`; an ambiguous bare name is
 `<agents-root>/<soul>/souls/<commit12>/` at its commit (the home links that
 directory; `<agents-root>/<soul>/soul` points at the current one) → resolves
 every capability by
-`from:` (member = latest, package = locked + approved) → creates the home →
+`from:` (member = latest, package = locked) → creates the home →
 **materializes each module whole** into `.oats/modules/` and copies its skills
 into `.agents/skills/` (a transaction: any failure leaves nothing behind) →
 composes `AGENTS.md` → records `modules`/`providers`/`workspace` in
@@ -282,9 +289,9 @@ 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
+If the workspace has a messaging capability 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.
+tasks capability can provide shared work state while messaging provides conversation.
 
 ### Retire
 
@@ -316,7 +323,7 @@ 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
+  holds the brain (the composed `AGENTS.md`; there is no soul link), 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,
@@ -325,9 +332,11 @@ instructions state first (`injects/instance-boundary.md`):
 - `<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/` under the applicable review rules. OKF v2 harvest edits external
+- The home has no soul link: the composed `AGENTS.md` already carries the
+  soul's instructions, and `instance.json` `soulDir` records the (read-only,
+  per-commit) soul directory every hook and dispatched command receives as
+  `OATS_SOUL`. Durable soul edits go through tracked paths under `work/` under
+  the applicable review rules. OKF v2 harvest edits external
   owned knowledge, not canonical soul files or skills.
 
 Agents move between the two as the task needs; the boundary is what each
@@ -472,8 +481,7 @@ 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
+The canonical deployment (the agents root and the instance homes under it) **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
@@ -486,33 +494,38 @@ something the kernel can close from inside.
 Default layout:
 
 ```text
-<scope>/
-  agents/              # committed souls
-    docs-expert/
-      soul/
+<deployment>/
+  oats-local.yaml
+  agents/
+    docs-expert/         # a workspace soul, defined in a member repository's
+      souls/<commit12>/  #   souls/docs-expert/ and copied here per commit
       instances/
-  local-agents/        # local souls — same shape, never committed
-    scratch-agent/
-      soul/
+    memory-harvest/      # a capability-defined agent: only instances/, no soul
       instances/
 ```
 
-`local-agents/` sits BESIDE `agents/` at the scope level and holds **full local
-souls**: complete definitions with instructions, skills, capability declarations
-and instances, 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. That concerns soul artifacts, not a knowledge
-provider's custody: a local soul using OKF v2 still reads external bases and
-uses PR-only delivery for any Git base.
+A capability-defined agent (declared by a package or member module, such as
+the OKF harvester) homes under the agents root exactly like a soul; its
+directory holds only `instances/`. A name that is both a workspace soul and a
+capability agent is ambiguous (`E_SOUL_AMBIGUOUS`).
+
+There are no local souls. A soul is a member repository's `souls/<name>`
+(`soul.yaml` + `AGENTS.md`); author it there and run `oats sync`. OATS 0.25
+and earlier kept local souls and capability-agent homes under
+`<scope>/local-agents/`: this kernel never reads, spawns into or retires from
+that directory; it only detects it. Onboarding refuses into a directory that
+holds one, and `oats status` and `oats doctor` report it once, as the
+`legacy-local-agents` problem naming the instances found there; retire them
+with the 0.25 kernel, or delete the directory once they are stopped.
+
+A *captured home* (spawned through 0.24–0.25's captured path, removed in 0.26:
+its `instance.json` records `executionBinding`, `incarnationId` or `captured`) is
+reported by `oats status` and `oats doctor` as the `legacy-captured-home`
+problem. It has no 0.26 runtime: start, restart, inspect/readiness/operation
+`--home` and its in-home commands refuse it (`E_UNSUPPORTED_MODE`). `oats retire`
+still works; it warns once per capability whose retire hook did NOT run, since
+identities and memberships those capabilities created are not revoked — remove
+them with the provider's own tooling. Re-spawn the soul from the deployment.
 
 Alternative agents-root layouts are planned but not built. Today the default
 layout is the only implemented layout.