@awebai/oats 0.24.0 → 0.24.2

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

@@ -0,0 +1,21 @@
+# OATS v0.24.2 — `oats onboard`, official capabilities in a soul's definition, aweb 1.11.0 pairing
+
+Kernel/Pi/Desktop **0.24.2**. Publication is not deployment: every operator still installs, approves and qualifies locally.
+
+## What changed
+
+- **`oats onboard [--dir <deployment>] [--workspace <git:source[@rev]>] [--force-existing] [--json]`** — bootstrap a deployment with an **`oats-setup-expert`** soul that holds `oats.core` and `oats.setup`. Acquires the official `oats.framework` package through the existing engine (resources-only guard before commit, no catalog auto-trust), activates exactly those two capabilities for that soul, writes its definition with both pinned at the acquired immutable commit, and **prints** the spawn command — it never launches a model. Classic local bootstrap, not captured preparation. `oats setup` (record capture setup) is unchanged.
+- **Soul creation declares `oats.core` explicitly.** `oats create` and new local souls write `requires.capabilities.oats.core` resolved from the official catalog; `--no-oats-core` opts out; nothing is invented when the catalog has no entry. When a soul declares `oats.core` or `oats.setup`, the kernel composes **neither** the legacy kernel skills (`oats`, `oats-config`, `oats-packages`) nor the `kernel:oats` injection — the capability's skills are the operational curriculum. Souls without it keep legacy behavior; `oats doctor` prints an informational line.
+- **Official capabilities.** `oats.framework` **1.1.1** (tag `oats-framework/v1.1.1`) exports `oats.core` (`oats-operate`, `oats-souls`, "you run on OATS" briefing), `oats.setup` (`oats-config`, `oats-packages`, `oats-workspace-setup` — now documenting the operator request shape) and `oats.knowledge-theory`. Listed in the official catalog with capability aliases.
+- **Retained inspection projects `launchSelection`** (`{runtime, model}` or `null`) for the primary from the verified retained record; provider binding codecs receive the same-kernel `OATS_CLI_BIN` after the environment scrub. These are what a provider `check` needs to be truthful about the primary's profile.
+- **aweb 1.11.0 pairing.** The catalog and all framework soul editions pin `oats.aweb@v1.11.0`, which adds the portable binding interface (floor `>=0.24.2`). Its `check` qualifies HOME-route operational custody only: explicit private team, `delivery: session`, an input-capable Claude/Codex primary. A strict-Pi print primary reports `needs-configuration`; the requirement is never dropped.
+- **Six framework soul editions** exported and imported by `oats-workspace.yaml`: the five knowledge-owning experts (`oats-expert`, `oats-kernel-expert`, `oats-desktop-expert`, `market-research-expert`, `oats-assistant`) at `caa341f3` and `oats-setup-expert` at `0aad753c`. All six declare `oats.core` from the repository's own payload.
+- Baseline hygiene: golden fixtures use a genuinely empty catalog; the package check lazy-loads dev validators so syntax-only lanes work without `node_modules`.
+
+## Second-operator gate
+
+An independent operator on a fresh machine adopted the shared definition from public sources through `inspect` → `prepare` → approvals with 0.24.1: the whole graph (including `oats.core`/`oats.setup`) resolved and materialized; preparation stopped at aweb 1.10.3 as declared. Five usability seams were recorded (request-file mismatch between `inspect`/`prepare`, raw ENOENT on an absent deployment, `trust --dir` rejecting lock v3, `--artifact-set` missing from help, unattributed provider problems). **They are not fixed in this cut**; see the [program board](../design/2026-09-20-redesign-program-board.md).
+
+## Not in this cut
+
+Desktop marketplace view / soul creation UI, legacy `agents/` roster and in-soul knowledge decommission (after the fresh-reader proof against the public `oats-knowledge`), Pi session-input support.

package/docs/souls-and-instances.md

@@ -1,8 +1,19 @@
 # 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.
+Souls and instances are the two layers the OATS kernel owns. A soul defines a
+reusable specialisation. An instance is a named working incarnation, with its own
+ID, home, work view and lifecycle—not necessarily one task or chat session.
+
+An instance may be ephemeral, such as a developer or reviewer doing bounded work,
+or long-running, carrying planning, investigation and domain understanding across
+many tasks. Lifetime does not itself change the soul's identity. See the
+[canonical knowledge and specialisation model](knowledge-theory.md) for how skills,
+shared knowledge, working context and state differ.
+
+This operational guide includes the configuration-based soul and lifecycle forms.
+Portable source definitions and captured lifecycle have their own versioned scope;
+see the [0.24 release notes](release-notes/v0.24.0.md) rather than assuming every
+legacy example below applies to a captured instance.
 
 ## Soul anatomy
 
@@ -43,12 +54,39 @@ in a soul bundle; see [knowledge](knowledge.md) for its prepared version scope.
 Future integrations may add expert-specific artifacts such as rule files or
 runtime-specific guidance, while keeping `AGENTS.md` canonical.
 
+## OATS operational knowledge is a capability
+
+New souls declare `requires.capabilities.oats.core` with a Git source resolved
+from the official package catalog. `oats create` and new local-soul scaffolds
+write that requirement; `--no-oats-core` explicitly omits it. If the catalog has
+no published revision yet, creation reports `needs-configuration` (also in JSON
+`notes`) and leaves the requirement absent rather than inventing a source.
+Declaring a capability is not acquiring, activating or approving it: those remain
+normal deployment/preparation steps. The Desktop server currently has no
+soul-creation endpoint; `oats soul set` edits existing definitions only.
+
+The dependency is visible and removable in `soul.yaml`. Updating an existing
+local soul preserves its requirements—including a deliberate removal—rather
+than applying the creation default again. For the one-release transition,
+a declaration of **either `oats.core` or `oats.setup`** suppresses the entire
+legacy kernel operational skill list (`oats`, `oats-config`, `oats-packages`)
+and `kernel:oats` injection. This also prevents setup's moved skill names from
+colliding with the kernel copies; no skill override is needed for this case.
+Without either declaration, legacy composition is unchanged.
+`oats doctor --soul <name>` reports an absent `oats.core` as an informational
+deprecation notice, not an error. Instance-boundary, work-mode and
+configuration-declared briefings remain kernel-owned. Existing captured records
+keep their retained resources; this does not migrate them or retire the kernel
+skill files yet.
+
 ## 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 lifecycle, but need not be short-lived. It is the identity of
+one instantiated soul while its assignment is alive. Supported session continuations,
+compactions and restarts can preserve that continuity. Model or harness changes must
+follow the selected execution profile; they are not permission to reinterpret a
+captured recipe. Retirement should account for valuable context and unfinished work,
+not assume an experienced instance is cheap to replace.
 
 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

package/docs/workspace-adoption.md

@@ -0,0 +1,314 @@
+# Adopt the OATS development workspace
+
+OATS hosts the shared `oats-workspace.yaml`. Its separate `oats.yaml` advertises
+source-complete exports and declares its own reciprocal membership. `oats-dev`
+remains a development-capability repository, including `oats.review`; membership
+neither activates that package nor replaces its existing configuration templates.
+
+This guide covers the shared repository graph and portable expert source editions,
+beginning with **the existing oats-expert**. Source publication is not a live
+five-role roster or curated knowledge cutover, a shared runtime, private-team
+enrollment or Desktop feature parity.
+The [phase plan](design/2026-09-20-workspace-and-portable-adoption-plan.md) and
+[knowledge model](knowledge-theory.md) retain those separate boundaries.
+
+## The five framework experts
+
+The indexed source editions are `oats-expert`, `oats-kernel-expert`,
+`oats-desktop-expert`, `market-research-expert` and `oats-assistant`. Each declares
+`owns` for its own same-named node and `reads` for the other four through logical
+store `oats`, preserving the reviewed owner UUIDs. These are knowledge-routing and
+context declarations, not access grants or proof of accepted knowledge. The parallel
+`souls/` editions neither replace the legacy `agents/` roster nor adopt the curated
+KB or change live instances; actual adoption still needs compatible providers and
+explicit bindings. All five now explicitly declare `oats.core` under
+`requires.capabilities`, with `source: repo:oats-package`. This retains the complete
+package from the same reviewed source revision.
+
+The dependency is visible and removable in the authored definition, not a change
+to existing captured records. An edited edition needs its own reviewed publication
+and import update; changing today's source does not rewrite an older pinned import.
+
+## Shared versus local
+
+| Git-shared declaration | Operator-local input or evidence |
+| --- | --- |
+| Workspace membership candidates and reviewed source import pins | Local source access and qualified repository observations |
+| A repository's backlink and real package/soul export paths | Working checkout mappings and the explicitly chosen work target |
+| Intrinsic capability requirements and logical knowledge interests | Provider settings, explicit store binding, private human/team choices |
+| Complete immutable instructions and skill resources | Native harness/model/auth, backend endpoint, home and durable state |
+| A reviewed source revision | Exact executable approval, current readiness and deployment acceptance |
+
+No machine paths, credentials, private team identifiers, accepted-store locator or
+owner registry belongs in the public workspace. Knowledge publication and acceptance
+(S7) remain separate; no ready knowledge export is advertised. Preserve the parked
+roster/curation and every old home, lock, source, pending job, history and worktree.
+
+## Planned onboarding: OATS Soul Setup (D3)
+
+**The D3 onboarding flow remains pending.** It will create and instantiate
+`oats-setup-expert`, declaring both `oats.core` and `oats.setup` from the
+[official marketplace](official-marketplace.md). Those capabilities are now
+published in `oats.framework` 1.1.0 and listed; the separate setup-expert edition
+and onboarding entry point do not become available merely by listing the package.
+This flow was not shipped in the 0.24.0 or 0.24.1 kernel releases.
+
+- The setup expert will help the operator adopt repositories, select capabilities
+  and carry out the normal prepare/approve/scaffold/start steps. It bypasses no
+  executable approval, provider readiness, identity or permission boundary.
+- Every soul created by that flow will declare `requires.capabilities.oats.core`
+  and its source explicitly. The operator can remove or replace that dependency
+  by editing the authored definition, not a captured record; the kernel will not
+  silently reinsert an absent one.
+- The CLI/Desktop entry point still requires separate implementation and review.
+  Do not invent a workspace init/adopt command, create a setup soul from this
+  sketch, or treat a listed package as installed. Existing instances and retained
+  resources are not rewritten by the plan.
+
+## Stage two: published experts and pinned imports
+
+- `oats-workspace.yaml` explicitly admits `oats` and the six intended capability
+  repositories: `oats-dev`, `oats-okf`, `oats-aweb`, `oats-authoring`, `oats-jira`
+  and `oats-linear`. It activates no additional capability; tasks default to none.
+- `oats.yaml` exports all five `souls/<name>` editions above and the actual package
+  roots `oats-package` (`oats.framework`) and `capabilities/oats-authoring`, not
+  the npm root as a fictitious OATS distribution. Its workspace backlink names
+  the same framework repository.
+- The editions are parallel to, not replacements for, the live `agents/` roster.
+  Each contains canonical instructions, `CLAUDE.md -> AGENTS.md`, and its reviewed
+  private procedures where applicable. No durable KB is copied into them; legacy
+  roster cutover remains deferred until S7 knowledge publication.
+- Each edition preserves its knowledge owner, owned node and four cross-reads.
+  Store `oats` requires the explicit `stores.oats` binding; no publisher writer,
+  production store or grants are supplied. An acceptance fixture is parent-owned
+  and cannot be counted as production knowledge adoption.
+- Knowledge **oats.okf@2.1.1** and messaging **oats.aweb@1.11.0** are explicit hard
+  requirements, not optional defaults. They are published starting revisions,
+  **not proof that their combined bindings/runtime profile is ready**. The provider
+  owner supplies that evidence and any subsequently reviewed compatible revision.
+  Do not replace either requirement with none or erase a read edge to launch.
+
+At these starting pins, the provider boundary is concrete:
+
+- Published OKF2.1.1 supports `inherit: stores.oats`, normalized to
+  `/bindings/knowledge/stores/oats`. The explicit `destination: oats` preserves
+  routing; omitting it would instead require `write.default`. No new schema,
+  owner or production locator is needed for this declaration.
+- aweb 1.10.3 (`24efa6f9`) has no portable binding interface; **aweb 1.11.0**
+  (`v1.11.0`, OATS >=0.24.2) adds it and the five editions now pin it. Its `check`
+  qualifies only an input-capable Claude/Codex primary with an explicit private team
+  and `delivery: session`; strict-Pi print reports `needs-configuration`. Status is on
+  the [program board](design/2026-09-20-redesign-program-board.md). Qualification
+  is HOME-route operational custody only: not human/native-principal delegation,
+  private grants, broker delivery or model consumption.
+- Published OKF2.1.1 accepts retained Claude/Codex helpers with the complete approved
+  capability closure and native-default model intent. Strict Pi still requires an
+  explicit model and the sole-OKF profile; Pi plus messaging remains unqualified.
+  This provider release alone is not combined-profile acceptance. Do not silently
+  switch runtimes, force a model, or drop capabilities.
+
+These are explicit readiness holds, not reasons to weaken the source. Parent must
+select reviewed compatible provider revisions and update the source pin deliberately
+before claiming an operational pilot; metadata-only repository indexes change none
+of these runtime facts.
+
+Stage one used an empty imports list until source publication. Stage two is now
+committed: all five imports pin **`caa341f34009e37006567419a983d5a743037a79`**, the
+published edition revision containing explicit core requirements and the package.
+The later workspace commit `375b9f42` added those imports. Live source inspection
+against published main resolved all five as `ready-for-preparation`; this is
+metadata readiness, not provider binding, approval, enrollment or a running pilot.
+
+## Preserve source-before-import publication order
+
+1. Publish complete, reviewed source editions before pinning them. The current
+   source is `caa341f34009e37006567419a983d5a743037a79`; future revisions must likewise
+   exist before their workspace import update. Never use an invented SHA, a mutable
+   branch or an unreviewed local candidate as the accepted source.
+2. In each of the six repositories, review a root `oats.yaml` against its actual
+   source head and actual `oats-package/oats-package.json`. The declaration is:
+
+   ```yaml
+   schemaVersion: 1
+   workspace:
+     source: git:github.com/awebai/oats
+   exports:
+     packages:
+       - path: oats-package
+   ```
+
+   Preserve payloads, versions, old tags and legacy templates. This does not
+   activate oats.dev, messaging or either optional task integration. Indexes are
+   published on `main` in all six capability repositories (oats-okf, oats-aweb,
+   oats-authoring, oats-jira, oats-dev, oats-linear); their publication proceeded
+   separately from the framework's own source imports.
+3. A subsequent workspace commit pins the published source, never itself or a
+   future commit. The current first import is:
+
+   ```yaml
+   imports:
+     - source: git:github.com/awebai/oats
+       soul: souls/oats-expert
+       revision: caa341f34009e37006567419a983d5a743037a79
+       alias: oats-expert
+   ```
+
+   The [actual workspace](../oats-workspace.yaml) contains all five imports at that
+   same revision; this excerpt is not a replacement for the full list. The layout
+   test now checks stage-two imports and source-document declarations. Do not
+   change stable export paths or owners merely because the workspace advances.
+4. Qualify reciprocal admission at the now-published observations. A missing
+   backlink, a fork's copied file or a stale workspace observation is not membership.
+   Cross-repository indexes may land separately; until both sides exist, report the
+   specific unqualified member rather than claim the whole graph is ready.
+
+Membership selectors and backlinks omit `revision` deliberately: the repository
+adapter observes the hosting provider's actual default branch, not a guessed
+`main`. Within one preparation, observations are frozen. In particular, the
+framework's self-member and workspace backlink must resolve to the **same commit**.
+A separately pinned older workspace with backlinks resolving to a later head is
+correctly stale; choose a fresh coherent observation, never rewrite an old retained
+record. Imports have their own immutable source revision and need not track each
+new workspace metadata commit.
+
+Importing the exported soul directly does **not** follow the publisher's workspace
+as adopter policy. A different workspace, or an explicitly standalone operator,
+may consume it without membership in the OATS development workspace.
+
+## Inspect source metadata before preparation
+
+The public source inspector ships in [OATS 0.24.1](release-notes/v0.24.1.md),
+following PR24 integration. Use an installed CLI containing that implementation.
+It is **not supported by the original 0.24.0 release**: that older inspect route
+can ignore the request flag and consult ambient classic configuration. Do not
+infer command availability from a capability's version floor or today's catalog.
+
+```sh
+oats inspect --request /absolute/inspection.json --json
+```
+
+With the stage-two imports published, the authored inspection input can use the
+same repository for workspace, member and source:
+
+```json
+{
+  "deployment": "/operator/deployments/oats-pilot",
+  "workTarget": "/operator/projects/oats",
+  "source": "oats-expert",
+  "origin": {
+    "kind": "operator",
+    "document": {"kind": "operator", "id": "workspace-adoption"},
+    "pointer": "/source"
+  },
+  "workspace": {
+    "source": "git:github.com/awebai/oats",
+    "origin": {
+      "kind": "operator",
+      "document": {"kind": "operator", "id": "workspace-adoption"},
+      "pointer": "/workspace"
+    }
+  },
+  "member": {
+    "source": "git:github.com/awebai/oats",
+    "origin": {
+      "kind": "operator",
+      "document": {"kind": "operator", "id": "workspace-adoption"},
+      "pointer": "/member"
+    }
+  }
+}
+```
+
+The paths are operator-selected examples, not host defaults or new grants.
+Independent adoption uses the full source/soul/revision/alias reference and an
+explicit standalone context instead of workspace/member. Do not mix this inspect
+mode with current-context flags or captured deployment/resolution selectors.
+
+The result is **non-authorizing metadata**, not provider readiness: even `ok:true`
+may carry `needs-configuration` or `separate-deployment-required`. A
+`ready-for-preparation` observation still has no approval or enrollment effect.
+Provider payloads and opaque adoption values are deliberately omitted. Preserve
+the original authored inputs; neither the result nor its inspection request is a
+preparation request or an issued mutation witness. In particular, `workTarget`
+and inspection catalog wrappers are not accepted preparation fields.
+
+The inspector owns transient repository scratch but writes no deployment state.
+Missing paths need explicit operator provisioning and reinspection, not automatic
+repair. Observing a project work target does not change the separate captured H/work
+placement. Existing retained inspect remains the later exact-record inspection.
+
+## Prepare a fresh local pilot only after the profile is qualified
+
+Use the selected installed compatible CLI. Do not turn this source check into a
+global install, a daemon start or a model/GUI test on another operator's machine.
+Keep native HOME/profile/auth and explicit permission choices; no credential copy
+or empty profile. Knowledge, messaging and tasks have distinct authority contracts.
+
+Before preparing, the integration lead must supply:
+
+- The published workspace/source observations and an explicit fresh physical
+  deployment/home placement. Do not copy old locks, retained records or identities.
+- An operator-owned nonsecret request with `workspace` (its source and origin),
+  `source: "oats-expert"` (or another published expert alias), and `mode: "directory"`.
+  Standalone callers instead give the complete `{source,soul,revision,alias}`
+  reference and an explicit standalone context; they do not inherit this workspace.
+- Explicit provider-specific settings and bindings. OKF preparation needs selected
+  absolute `bindings-file` and `state-dir`, `harvest-runtime`, and the `stores.oats`
+  binding; an omitted `harvest-model` preserves native-default intent. The parent-owned
+  acceptance fixture must supply an accepted node registry supporting the preserved
+  owner **and all four read nodes**. This is not accepted production KB publication;
+  Git destinations remain PR-only.
+- Actual messaging human/context inputs and the pilot's explicit **`delivery: session`**
+  setting (aweb's default is channel). Supply it in the complete supported
+  `operator.policy.messaging` selection: capability, matching selected source and
+  `settings: {delivery: session}`. Retain host requirements, session `ifInstalled`
+  minimums and any selected authoring requirements. Selecting session delivery neither
+  makes a strict-Pi print primary input-capable nor supplies captured wake authority.
+- A qualified primary/helper runtime/model/resource profile. Capture the intended
+  helper selection in `helperLaunches["oats.okf:memory-harvest"]`, not the legacy
+  `souls.memory-harvest` configuration. Do not replace retained intent to fit an easier
+  runtime profile. An old default-OKF-only learning gate does not qualify a combined
+  aweb profile. If provider or kernel support is missing, stop at that typed result;
+  do not bypass it with a legacy route, a dropped capability or a fabricated identity.
+
+The existing public routes are stepwise (D/R/H are returned or explicitly approved
+values, not names inferred from cwd):
+
+```sh
+oats prepare --request /absolute/operator-preparation.json --json
+# Review returned exact artifacts/problems; approve only explicitly authorized code.
+oats trust <capability-id> --deployment "$D" --artifact-set "$ARTIFACT_SET" --json
+oats prepare --request /absolute/operator-preparation.json --json
+oats inspect --deployment "$D" --resolution "$R" --composition --json
+oats spawn oats-expert --deployment "$D" --resolution "$R" --home "$H" --no-launch --json
+oats session start --deployment "$D" --resolution "$R" --home "$H" \
+  --request /absolute/approved-native-request.json --json
+```
+
+Do not mix other preparation flags into request-file mode. A needs-configuration or
+approval result is not a ready instance. A scaffold materializes resources and may
+run approved hooks; it is not a message exchange or model session. Actual dispatch,
+continuation, native capture, messaging and learning require the integration owner's
+qualified profile and receipts. OATS 0.24.1 adds captured custody checks to the
+existing HOME-only session inspect/input route; it does not supply the missing
+messaging adapter or qualify every lifecycle route. Verify wake/input/retirement
+support for the exact route and runtime. A stopped-home observation is not delivery
+or retirement authority, and a messaging profile cannot pass on start-only evidence.
+Do not bypass custody with a legacy fallback or remove the messaging requirement.
+Consult the current installed public help and the provider's supported commands;
+this guide introduces no new CLI grammar. The source inspector above is a separate
+implementation dependency, not a change to the existing prepare request contract.
+
+## Local checks and limits
+
+`node --test test/workspace-repository-layout.test.mjs` checks the actual declarations
+against the shipped codecs/schemas, required providers and owner/read mapping, and
+contained source resources. An isolated native-Git fixture exercises source-before-
+import publication, host-default observations, reciprocal/self admission, refusal of
+missing/stale backlinks, and independent public source projection. Fixture member
+indexes are not evidence that the six real repositories are already published.
+
+Source and metadata checks do not enroll users, initialize the phase-2 store, register
+production writers or qualify private messaging. Parent alone coordinates publication,
+local operator approval and actual adoption. Full Desktop parity follows usable
+infrastructure adoption, not merely source metadata passing validation.

package/docs/workspaces.md

@@ -0,0 +1,154 @@
+# Workspaces, repositories and portable souls
+
+A **workspace definition** describes a shared agent setup in Git. A **local deployment** is one operator's realization of it. A **portable soul** declares its role, requirements and software sources independently of either operator's directory layout.
+
+This is the current OATS architecture. Start here for the model, then use [first-team onboarding](first-team.md) and the version-scoped [configuration](configuration.md) and [packages](packages.md) guides for operations. The [0.24 release notes](release-notes/v0.24.0.md) distinguish shipped foundations from unqualified profiles; an accepted architecture is not proof that every capability is ready.
+
+## Four independent things
+
+| Thing | What it decides | What it does not imply |
+|---|---|---|
+| Workspace | Intended repository membership, shared defaults, source imports and provider declarations | Installed software, executable approval, messaging enrollment or a shared live session |
+| Source repository | The soul/package/store definitions it actually exports | Membership of every consumer in the publisher's workspace |
+| Local deployment | Local mappings, retained artifacts/resolutions, operator inputs and execution state | Permission to change source requirements or copy another operator's credentials |
+| Work target | Where an instance is assigned to work | Where its soul must be published, where knowledge must live or which team it joins |
+
+A workspace needs no OATS account, registry or OATS-operated control plane. Git hosting, messaging and model providers retain their own access and authentication requirements.
+
+## The three declaration files
+
+### `oats-workspace.yaml` — the shared workspace
+
+The workspace names intended members and may provide defaults, knowledge-store declarations, team aliases, catalogs and external soul imports. Omitted lists admit or activate nothing.
+
+A workspace is a role, not a requirement for a separate repository. It can live in a dedicated repository or beside project code. For OATS development, the selected home is the `oats` framework repository; `oats-dev` remains a development-capability repository.
+
+This schematic example uses placeholder sources, not a runnable published team:
+
+```yaml
+schemaVersion: 1
+name: example-development
+members:
+  - source: git:github.com/example/service
+imports:
+  - source: git:github.com/example/experts
+    soul: souls/domain-expert
+    revision: reviewed-source-ref
+    alias: domain-expert
+```
+
+Use actual reviewed source revisions when preparing work. When a repository reference omits its optional revision, discovery observes the hosting provider's intended default branch; it must not guess `main` or silently reuse unrelated local branch state.
+
+### `oats.yaml` — a repository's advertised exports
+
+A repository advertises the souls, package roots and provider-owned knowledge declarations it actually supplies. A member also points back to its workspace:
+
+```yaml
+schemaVersion: 1
+workspace:
+  source: git:github.com/example/workspace
+exports:
+  souls:
+    - path: souls/domain-expert
+      definition: souls/domain-expert/soul.yaml
+  packages:
+    - path: oats-package
+```
+
+Only include exports that exist at the selected revision. A repository need not export every kind. A package export identifies a real directory containing `oats-package.json`; it is not an arbitrary npm package directory.
+
+`oats-workspace.yaml` and `oats.yaml` may coexist. If the workspace host also participates as a member, it is explicitly admitted and has a matching backlink just like another member.
+
+### `soul.yaml` — a source-complete specialist
+
+A portable soul is an authored definition, not a dependency on whatever happens to be installed on its publisher's machine. It contains canonical `AGENTS.md`, a relative `CLAUDE.md` alias, its reviewed skill/resource closure and a versioned declaration.
+
+For example, this declaration excerpt requires a particular knowledge capability **and names where it comes from**:
+
+```yaml
+schemaVersion: 1
+name: domain-expert
+requires:
+  knowledge:
+    capability: oats.okf
+    source: git:github.com/awebai/oats-okf@v2.1.1#oats-package
+```
+
+This illustrates software selection, not complete OKF provisioning: the chosen capability also needs its own valid knowledge declaration, bindings and accepted base.
+
+- `requires` expresses hard requirements. A fundamental provider can be required by presence or as a concrete capability/source selection.
+- `defaults` supplies choices that remain rebindable within those requirements.
+- Additive capabilities are named under `requires.capabilities` or `defaults.capabilities`; each concrete selection has a `source`, with optional provider-owned settings.
+- `git:` selects versioned software from a repository/package root. `repo:` refers to a contained path in the declaring source repository, not the caller's working directory. `path:` is an explicitly authorised local development choice, not a remotely portable ambient fallback.
+- Capability IDs alone do not establish software origin. An old `from: installed` config entry is not a substitute for a portable source declaration.
+- A source may contain authored knowledge snapshots or resources, but retained artifacts are not writable knowledge stores. Learning locations and procedures belong to the selected capability.
+
+See the [soul schema](soul.schema.json) and [declaration contract](design/2026-09-15-portable-declarations.md). Classic fields such as `kind`, `type` and a machine-local `repo` are not portable declaration fields; do not relabel an old file without validating it.
+
+## Membership and adoption are different
+
+**Repository membership is reciprocal:** the workspace admits the repository and the repository's `oats.yaml` points back to that workspace. Both observations must have compatible identity, access context and revision evidence. A copied backlink, neighbouring folder or URL is not admission.
+
+**Source adoption is by reference:** an import identifies `source`, exported `soul` path, `revision` and a local `alias`. It may carry supported adoption choices. Importing does not create an adopter-maintained copy of the soul or automatically follow the publisher's workspace backlink.
+
+A team can therefore use a public expert without joining its publisher's organization. One source can serve several workspaces or an explicit standalone context, with different legitimate work targets and knowledge bindings.
+
+Publish source/export revisions before pinning imports to them. Do not use invented future SHAs or require two repositories to contain each other's not-yet-created commit IDs.
+
+## How requirements and defaults meet
+
+The kernel uses one resolver:
+
+- Workspace defaults establish shared fallback choices.
+- The soul's own defaults can specialise them.
+- Explicit adoption/operator choices select supported alternatives or supply missing inputs.
+- Hard source requirements remain constraints; a conflicting override is an error, not a reason to discard the requirement.
+
+Provider-owned declarations remain opaque to the kernel until the selected provider interprets them through its contract. There is no portable repository-level capability policy tier silently inherited from the publisher, and no mandatory agent-type hierarchy replacing a soul's own requirements.
+
+Repository briefing/worktree setup remains work-target behavior with its own supported authority. Merely placing a repository `AGENTS.md` nearby does not guarantee it is composed into every harness's instructions.
+
+## From a definition to a running instance
+
+1. Select an explicit workspace or standalone context, source reference, deployment location and work target.
+2. Observe actual source identities/revisions and check requested reciprocal membership.
+3. Resolve requirements, defaults and operator inputs; retain the selected source and software closure.
+4. Review and approve exact executable artifacts before provider code runs.
+5. Obtain honest provider readiness and a retained resolution; missing configuration or unsupported behavior remains visible.
+6. Scaffold and start through the supported captured lifecycle. Preserve the exact source/resources and evidence needed for continuation.
+
+An existing instance does not silently adopt a new upstream commit, changed workspace default or different curriculum. Updates prepare new choices deliberately; required knowledge refresh and native credential rotation are separate from rewriting its retained software.
+
+A successful lookup is not execution, an accepted dispatch is not completed work, and a declared knowledge destination is not accepted learning.
+
+## What each operator shares or keeps local
+
+Share reviewed definitions, relevant nonsecret configuration/provenance, published source references and accepted knowledge through their chosen Git repositories. Keep credentials, private runtime evidence, instance homes and machine-specific realization local. A messaging roster does not replicate any of these.
+
+An adopted package config template is an editable local snapshot, not live inheritance from the package. Updating the kernel or package does not rewrite it, migrate a knowledge base or update a running instance's loaded instructions.
+
+## Compatibility and current readiness
+
+Classic `oats-config.yaml` scopes, `oats init`, `oats use`, local `agents/` lookup and lock-v2 package restore still have their own supported contracts. They are not renamed portable workspace commands. See [configuration](configuration.md) and [packages](packages.md) for that compatibility surface; do not apply classic lifecycle commands blindly to captured instances.
+
+At the documented0.24 baseline, workspace/declaration/retained-execution foundations are shipped. The released `oats.aweb`1.10.3 package lacks the captured provider-binding interface, so its legacy messaging success does not qualify a new captured profile requiring it. Capability adaptation is implementation work, not a YAML setting that can honestly turn readiness green. Follow current [release scope](release-notes/v0.24.0.md) and the provider's actual version/readiness rather than removing requirements.
+
+The project's [adoption plan](design/2026-09-20-workspace-and-portable-adoption-plan.md) puts workspace/source adoption first, centralised knowledge and five experts second, and full Desktop parity afterward.
+
+## How a soul knows OATS (accepted direction, not yet shipped)
+
+An agent's knowledge of OATS itself — how to check status, spawn and retire, find other souls — is ordinary capability content, not kernel magic:
+
+- **`oats.core`** carries day-to-day operation (skills `oats-operate`, `oats-souls`, the "you run on OATS" briefing). Every soul gets it **by default at creation, written explicitly into its definition**; you can remove or replace it.
+- **`oats.setup`** carries deployment/workspace configuration and package knowledge ("OATS Soul Setup"). Onboarding a workspace creates and starts an **`oats-setup-expert`** soul with both, which then adopts repositories and creates the team's other souls.
+- The **official marketplace** is the reviewed package list in the `oats` repository; a package becomes official through an approved PR to that list, and official packages are discoverable from the CLI and Desktop. Discoverable is not installed; installed is not approved.
+
+At the0.24 baseline these skills still ship inside the kernel. Work packages D1–D4 of the [adoption plan](design/2026-09-20-workspace-and-portable-adoption-plan.md) track the move.
+
+## Related references
+
+- [Souls and instances](souls-and-instances.md)
+- [Capability contracts](layers.md) and [capability authoring/distribution](capabilities.md)
+- [Knowledge model](knowledge-theory.md) and [version-scoped operations](knowledge.md)
+- [Workspace schema](oats-workspace.schema.json) and [repository export schema](oats-member.schema.json)
+- [Design/contract navigation](design/README.md)

package/injects/oats-portable.md

@@ -7,11 +7,14 @@ settings, provider bindings, and executable resources come from that exact
 configuration cascade, package lock, similarly named capability, or source path.
 
 Load **oats-portable** before invoking or reasoning about captured OATS commands.
-Load **oats-portable-setup** for fresh by-reference preparation and explicit
-source/workspace/deployment/work/team choices. Load **oats-portable-artifacts**
-for exact retained inspection and approval. Do not load the legacy **oats**,
+Load **oats-portable-artifacts** for exact retained inspection and approval. Do not load the legacy **oats**,
 **oats-config**, or **oats-packages** procedures to fill a captured input.
+If this retained composition includes **oats.core**, its **oats-operate** and
+**oats-souls** skills are capability resources, not implicit kernel additions.
+Use only the resources actually included; a missing capability is not permission
+to fetch or substitute a current version.
 
-Captured start/restart/wake/retire, managed launch/runtime and non-directory work
-are not yet public. If a command is unsupported or retained authority is missing,
+Captured start/restart use exact retained launch inputs and supported native
+endpoints. Captured wake/retire, unqualified runtime contributions and non-directory
+work remain held. If a command is unsupported or retained authority is missing,
 stop and report it; never remove selectors or fall back to ambient configuration.