@awebai/oats 0.24.0 → 0.24.2

package/docs/capabilities.md

@@ -4,6 +4,10 @@ A **capability package** is OATS's reusable distribution unit. It can contribute
 skills, instance instructions, requirements, namespaced commands, and approved
 lifecycle hooks. Configuration—not the package—decides which souls receive it.
 
+The [official marketplace policy](official-marketplace.md) defines the reviewed
+package list and its acceptance criteria. Finding an official capability does not
+install, activate or approve it; those remain explicit, separate choices.
+
 An **integration** is a capability package that implements one exclusive
 fundamental layer: `knowledge`, `messaging`, or `tasks`. General capabilities
 claim no layer and compose additively.

package/docs/design/2026-09-20-redesign-program-board.md

@@ -0,0 +1,83 @@
+# OATS redesign — program board
+
+**Purpose:** the one accurate view of every work stream in the redesign, what is on main, what is in flight, who owns it, and what blocks it. Lead: `oats-expert` (redesign lead). Updated whenever anything merges, is returned, or reality changes. Older per-lane boards are superseded by this file.
+
+**Last update:** 2026-09-21 04:10Z · main `feef2a2f`+ · **OATS v0.24.2 tagged (CI)** · OKF v2.1.1 · oats-framework/v1.1.1 · aweb v1.11.0 · oats-knowledge 8d67eab4
+
+Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
+
+## Streams at a glance
+
+| # | Stream | State | Owner | Next action |
+|---|---|---|---|---|
+| S1 | Knowledge capability contract rework (kernel↔provider boundary, OKF 2.x) | ✅ OATS 0.24.1 / OKF 2.1.1 published | P | done for this phase |
+| S2 | Workspace/Portable Souls adoption of the OATS repos | ✅ workspace + seven indexes + **six imports** (five experts @caa341f3, setup expert @0aad753c) · ✅ second-operator gate run · 🔄 five seams → L, target 0.24.3 | lead, L, Antares | seams PR; Antares re-run on 0.24.2 (aweb 1.11.0) |
+| S3 | Messaging capability readiness on the new infrastructure (aweb) | ✅ aweb 1.11.0 released · ✅ **catalog + six editions pin v1.11.0 (0.24.2)** · ⬜ second-operator re-run | P, lead | Antares re-run |
+| S4 | Official capabilities `oats.core` / `oats.setup` + explicit default + onboarding `oats-setup-expert` | ✅ D1, D2, **D3 merged (PR35)**: `oats onboard` verified live (acquire 1.1.1 → setup expert with both caps → scaffold composes the five capability skills, no legacy) · `oats.framework` 1.1.1 tagged | P, L | done; Desktop surfaces → S8 |
+| S5 | Official marketplace = reviewed list in oats repo | ✅ D4 merged · ✅ `oats.framework` 1.1.1 listed (`oats.core`, `oats.setup`, `oats.knowledge-theory` aliases) | M | Desktop view → S8 |
+| S6 | Five expert souls created in the oats repo (`souls/<name>/`) | ✅ five + `oats-setup-expert` on main, all declaring `oats.core`, exported + imported | M, L, lead | legacy `agents/` cutover after S7 proof |
+| S7 | Centralised per-soul knowledge in `oats-knowledge` (migration + PR-only learning) | ✅ **repo PUBLIC; PR #1 merged → main 8d67eab4, 25 accepted concepts**, owners = published souls, validator pinned OKF 2.1.1 · 🔄 fresh-reader proof assigned to Juan's side · ⬜ legacy in-soul knowledge decommission | lead, Antares/Juan | fresh-reader + PR-learning proof; then retire `agents/*/soul/knowledge` |
+| S8 | Desktop parity (marketplace view, soul creation with `oats.core`, onboarding flow) | ⬜ after D3 · **host offered: Juan's machine (has `claude`)** — accepted | fresh Desktop engineer on Juan's host | brief + spawn params after D3 |
+
+## S1 — Knowledge capability contract rework
+- ✅ Provider-neutral contract, binding wire v1, helper/input contract, retained execution: OATS 0.24.0 + OKF 2.1.0 (f20f8e57) published.
+- ✅ **oats-okf PR4 merged (9f90ee9) → OKF v2.1.1 (01b48dfc)**: Claude/Codex helpers with complete approved closure accepted; strict-Pi unchanged. Framework mirror/inventory finalized, catalog ref and `souls/oats-expert` source → v2.1.1 (16c5c939, 87292f40).
+- Open: strict-Pi "enriched profile" remains unqualified (documented, not hidden).
+
+## S2 — Workspace adoption of the OATS repos
+- ✅ **PR23 merged f6d5a89b**: `oats-workspace.yaml` (7 members, `imports: []`), `oats.yaml` (exports souls/oats-expert, oats-package, capabilities/oats-authoring), transitional `souls/oats-expert/` edition, `docs/workspace-adoption.md`, layout tests.
+- ✅ **PR24 merged da38e5a9**: deletion of `skills/oats-portable-setup` + `oats inspect --request` read-only seam (ACCEPTED as the public inspection route); full gate 1621/0.
+- ✅ Member `oats.yaml` merged to main: oats-okf #3 (fec78a20), oats-aweb #1 (069ea2f6), oats-authoring #1 (54183a6a), oats-jira #1 (2f855daf).
+- ✅ oats-dev#1 (main 6e164ee3) and oats-linear#1 (main a2121e48) merged after Juan granted write access — M's exact commits 0434f4ef / 8c183c37.
+- ⬜ `imports:` pin of `souls/oats-expert` at its published revision (after member indexes).
+- ⬜ Fresh local deployment from the shared definition (P1.5) — the real acceptance gate.
+
+## S2 — second-operator gate report (Antares, Juan's machine, 2026-09-20)
+Fresh dir, local `@awebai/oats@0.24.1`, no prior state. `inspect --request` → ready-for-preparation, membership eligible, source `souls/oats-kernel-expert@caa341f3`. `prepare` resolved and materialized `oats-package@caa341f3`, `oats.okf@v2.1.1`, `oats.aweb@v1.10.3`, `oats.core`, `oats.setup`, `oats.knowledge-theory` + soul; artifact-set approvals worked. Terminal: `needs-configuration` + `provider-not-qualified` (aweb 1.10.3 has no binding interface) — expected. Seams (assigned to L, one PR, priority):
+1. `inspect --request` requires `workTarget`; `prepare --request` refuses it (`buildFreshPreparationRequest` exists but the CLI never uses it).
+2. `prepare` on the absent deployment inspect blessed → raw `ENOENT` + host path through the JSON envelope.
+3. `prepare` writes lock v3; `oats trust <cap> --dir` rejects it (`unsupported lockfileVersion 3`) → dead end from `--help`.
+4. The working `trust --deployment --artifact-set <sha256>` route is absent from `--help`.
+5. Problems carry `origins: []` and no slot/capability; aweb's missing interface masks OKF diagnostics — a valid and a bogus `stores.oats` binding produce byte-identical output. **Fix first.**
+
+## S3 — Messaging (aweb) on the new infrastructure
+- ✅ **aweb PR3 merged → v1.11.0 (93f8ab96)**: `binding {normalize,bind,check}` on the existing wire; `check` = HOME-route operational custody only (explicit private team, `delivery: session`, kernel ≥0.24.2 via caller-owned `OATS_CLI_BIN`, retained `launchSelection` must be input-capable Claude/Codex; strict-Pi print → `needs-configuration`, never downgraded). Native adapter over existing `aw` commands with physical identity-dir custody and redacted tokens. Standalone 30/0; coupling 14/0 vs kernel b92f0d07. PR33 (launchSelection projection, OATS_CLI_BIN in codec env) merged b92f0d07.
+- Facts: released aweb 1.10.3 has no binding interface; broker refuses. aw 1.36.1 broker calls `oats session inspect/input --home H`; never restarts stopped runtime; strict-Pi print mode can't take session input.
+- 🔄 oats-aweb **PR2** codec (165b20e) + uncommitted `lib/captured-execution.mjs` (6/6).
+- ✅ Lead answered (d9d912a4): pilot primary = Pi strict print host explicit model; helper = Pi sole-OKF (Claude/Codex allowed by 2.1.1); authority = existing HOME route + L's custody fix, gated on `oats >=0.24.1`; no new grant mechanism. P delivers aweb 1.11.0 PR. 
+- ✅ **PR27 merged (5af848fc)**: HOME-only session route applies existing captured custody; refuses before transport on drift. Full gate 1626/1632 (2 pre-existing env failures reproduced on main). Ships in **v0.24.1** — the kernel floor the aweb adapter gates on.
+
+## S4 — `oats.core` / `oats.setup` / onboarding
+- ✅ **D3 merged PR35 (37c5c012)**: `oats onboard` classic local bootstrap; edition `souls/oats-setup-expert` (core+setup, provider defaults `none`, no knowledge owner). Full gate 1639/0. Live: onboard → acquire `oats.framework` 1.1.1 @0aad753c → soul declares both caps at that commit → scaffold-only spawn composes exactly `oats-operate, oats-souls, oats-config, oats-packages, oats-workspace-setup` + the `oats.core` injection, no legacy kernel skills. Baseline hygiene fixed on main (a96f24df).
+- ✅ **D1 merged PR28 (70b10822)**, distribution tag `oats-framework/v1.1.0` on 9930dcfb; **D2 merged PR29 (9930dcfb)** full gate 1634/0. Verified live: `oats create` writes `requires.capabilities.oats.core` with the catalog source; `oats install oats.framework` acquires all three capabilities from the tag.
+- ✅ Decision + plan D1–D4 on main 18af53be; docs reference as accepted-not-shipped.
+- 🔄 **D1** (P, started 16:29Z; package identity confirmed: rename distribution package to `oats.framework` 1.1.0, capabilities 1.0.0, `oats.knowledge-theory` unchanged) package `oats.core` (`oats-operate`, `oats-souls`, oats.md injection) and `oats.setup` (oats-config, oats-packages, adoption guidance) under `oats-package/capabilities/`. Owner P.
+- 🔄 **D2** (L, after custody fix) soul creation writes explicit `requires.capabilities.oats.core`; kernel skill list de-ambiented (one-release coexistence); checked-in souls updated. Owner L.
+- 🔄 **D3** (L, in progress) onboarding creates `oats-setup-expert` (edition in `souls/`); CLI verb **`oats onboard`** — `oats setup` is already the record capture-setup command and stays untouched.
+- Exit: fresh onboarding → running setup expert; created soul shows `oats.core`; kernel ships no ambient operational skill.
+
+## S5 — Official marketplace
+- ✅ Mechanism exists (`package-catalog.json`, `officialPackageCatalog()`); decision names it the official list.
+- ✅ **D4 merged PR26 (786490ae)**: `docs/official-marketplace.md`, `package-catalog.json` policy pointer (inert to the reader), README/packages/capabilities links, D3 sketch in adoption guide. ⬜ entries for `oats.core`/`oats.setup` at D1 release. Desktop view → S8.
+
+## S6 — Five expert souls in the oats repo
+- ✅ **PR30 merged (40a579dc)** + maintainer follow-up **caa341f3**: all five declare `oats.core: {source: repo:oats-package}`, oats.okf@v2.1.1; `oats.yaml` exports all five; `oats-workspace.yaml` imports all five at caa341f3 (375b9f42). Live inspection against published main resolves them.
+- Roster (decided): `oats-expert`, `oats-kernel-expert`, `oats-desktop-expert`, `market-research-expert`, `oats-assistant`.
+- 🟡 Candidate: `expert-roster` worktree (b5e233b9 + 519 uncommitted changes: five `agents/<name>/soul/` + legacy roster deletions). Reviewed earlier; NOT committed.
+- ✅ `souls/oats-expert` transitional edition on main already declares owns/reads for the five nodes.
+- 🔄 Assigned to M (17:05Z): create `souls/<name>/` editions for the other four from the candidate; each declares `oats.core` explicitly (S4 rule) + `oats.okf`/`oats.aweb` sources; export in `oats.yaml`. Legacy `agents/` roster retirement is a separate, later cutover.
+
+## S7 — Centralised knowledge in `oats-knowledge`
+- ✅ Juan made the repo PUBLIC (2026-09-20). Bootstrap history pushed to main; **PR #1 merged (8d67eab4)**: 25 curated concepts, roadmap re-verified to the 0.24.1 baseline and 2026-09-20 decisions, validator pinned to OKF v2.1.1, strict OKF 25/0/0, ownership tests 24/24.
+- 🟡 Curated corpus: 35 concepts (five nodes) on local `curation/expert-knowledge` in `/Users/pepe-reyero/OATS-workspace/oats-knowledge`, **uncommitted**. Bootstrap + one PR-only harvest already proven on `josep-reyero/oats-knowledge` (3 commits).
+- ⛔ Target `awebai/oats-knowledge` is EMPTY and PRIVATE; **visibility undecided** (stated requirement: public). Human decision needed before publishing.
+- ⬜ Then: push bootstrap + curation as PR to awebai; bind `stores.oats` in the pilot deployment; prove fresh-reader + Git-PR learning with the new souls; retire old in-soul knowledge (`agents/*/soul/knowledge`) as a final cutover.
+
+## S8 — Desktop parity
+- Finding (L, D2 audit): the Desktop server has **no soul-creation endpoint** today (roster reads, existing-soul edits/capability operations, instance spawn only). Soul creation with explicit `oats.core`, the marketplace view and the onboarding flow are new Desktop features, not wiring.
+- ⬜ After S4/S5: official marketplace view/search; soul creation showing `oats.core`; onboarding flow; redesign parity vs `Oats UX Redesign and Desktop Discovery (1)`.
+- ⛔ Fresh `oats-desktop-engineer` not spawned: `claude` not on PATH → choose Pi/Codex or install (human).
+
+## Blockers needing the human
+- ~~oats-knowledge visibility~~ → PUBLIC (Juan). ~~oats-dev/oats-linear access~~ → granted, indexes merged. ~~Desktop runtime~~ → Juan's machine hosts the Desktop lane (has `claude`).
+- None open at 23:10Z. Juan's side (Antares) takes: (a) fresh-deployment gate P1.5, (c) fresh-reader proof, (b) Desktop host after D3.

package/docs/design/2026-09-20-workspace-and-portable-adoption-plan.md

@@ -0,0 +1,287 @@
+# OATS adoption plan: workspace first, knowledge and experts second
+
+**Date:** 2026-09-20
+
+**Status:** Phase1 implementation authorised by the human, using the existing developers under lead supervision/review. The workspace home is confirmed as `oats`; `oats-dev` remains development capabilities. This does not claim completed conversion or authorise unspecified new contracts, credential operations or live deployment mutations.
+
+## Goal and order
+
+1. Put OATS development onto the Git-workspace and Portable Souls architecture: a real shared workspace definition, qualified repository exports, by-reference sources and usable local deployments.
+2. Centralise the curated knowledge and adopt the five expertise souls on that foundation.
+3. Complete Desktop design/feature parity against the resulting supported flows.
+
+A distribution work package (below, D1–D4) accompanies phase1: the kernel's operational skills become the official capabilities `oats.core` and `oats.setup`, every soul declares `oats.core` explicitly by default, onboarding creates an `oats-setup-expert`, and the official marketplace is the reviewed list in this repository.
+
+The second phase does not run as an unrelated bulk migration while the first is still changing underneath it. Necessary generic knowledge/provider boundary fixes belong in phase1; default OKF behavior and the actual corpus/roster cutover belong in phase2.
+
+## Target arrangement
+
+Approved repository responsibilities following the framework-hosted workspace choice. The two-phase order is unchanged:
+
+| Repository | Role in the new setup |
+|---|---|
+| `oats` | Kernel, adapters, Desktop and portable soul exports through `oats.yaml`; hosts the shared development workspace in `oats-workspace.yaml`; ships the official capabilities `oats.core` and `oats.setup` and the reviewed official package list (`package-catalog.json`) |
+| `oats-dev` | Reusable OATS development capabilities, including selected review skills/behavior; no longer responsible for defining the new workspace through a package template |
+| `oats-okf` | Reference knowledge capability and its complete reading/capture/judgment/delivery behavior |
+| `oats-aweb` | Messaging capability and its provider-owned identity/team/wake behavior |
+| `oats-authoring` | Reusable authoring support |
+| `oats-jira`, `oats-linear` | Optional task capabilities; workspace membership does not activate them |
+| `oats-knowledge` | Curated accepted expertise, not executable soul definitions, working transcripts or a copy of framework documentation |
+
+A workspace is a logical role and does not require a dedicated repository. The human has selected co-hosting in `oats`, preserving `oats-dev`'s capability purpose. Keep the `oats.dev` package where its reusable behavior is useful; separately review compatibility and the legacy template. Preserve published tags/payloads and exact restores. Merely adopting the workspace does not activate every capability.
+
+`oats-workspace.yaml` and `oats.yaml` have separate contracts even when co-located. Admit the framework repository explicitly if it participates as a member, and verify matching reciprocal observations. Importing a public OATS soul or installing the framework must NOT implicitly select or enroll an adopter in the framework's development workspace. A separate workspace repository remains an option if independent permissions or lifecycle become necessary.
+
+The shared workspace is **not a shared live runtime**. Each operator retains local deployment mappings, runtime/authentication, state and explicit approvals. Config and nonsecret lock/template provenance can be Git-shared where supported; credentials and live instance state cannot. Git access, organizational admission, executable approval and messaging enrollment remain distinct.
+
+## Verified starting point
+
+- Kernel/Pi/Desktop0.24.0 and OKF2.1.0 are released. Workspace/source codecs, discovery, retained composition and scoped execution/provider machinery already exist. This is not a kernel rewrite from zero.
+- A read-only September20 inventory found no root `oats-workspace.yaml` in either `oats` or `oats-dev` and no root `oats.yaml` in the framework or the six inspected capability/development repositories. The selected knowledge repository is not yet initialized. These observations must be refreshed against exact heads before editing.
+- The default development package still supplies a legacy config template and `oats.review`; these are capability/template exports, not a Git workspace definition.
+- The checked-in roster remains legacy. A five-role candidate and curated corpus are preserved but not validly published/adopted as the new portable setup.
+- Earlier live native/directory-learning evidence is valuable but does not prove our actual Git workspace, two-operator deployment, private messaging or Git-PR learning cutover.
+- Current source contains the approved forward correction of the accidentally integrated held record patch. Preserve repaired history and its active-content exclusion; do not reopen that incident or repeat closed test matrices.
+
+# Phase 1 — adopt the workspace and Portable Souls architecture
+
+## P1.1 — freeze the repository, source and runtime map
+
+**Owner:** integration lead, with kernel/provider/deployment owners.
+
+Produce one bounded implementation checklist from the actual current code and chosen package revisions:
+
+- Exact workspace repository and intended member repositories; external consumption is not membership.
+- Source/export locations for the necessary transitional roles and the eventual five experts. Recommended reusable soul editions remain in the framework repository, separate from live legacy `agents/` sources.
+- Compatible package/source revisions, required capabilities and operator-selectable bindings.
+- Actual runtime/backend and messaging-delivery profiles to support, including intentional local differences. Do not replace native credentials/profiles or copy one operator's raw configuration to another.
+- Existing support versus declaration/resource drift versus provider work versus genuinely missing kernel/CLI seams. Every missing generic field or authority change gets a concrete proposal; reuse the current parser/resolver/invocation engine.
+
+**Deliverable:** an exact repository/change/owner matrix and a small gap list, not another open-ended architecture investigation.
+
+## P1.2 — author the real workspace
+
+**Owner:** workspace/deployment owner, reviewed by the integration lead.
+
+Add `oats-workspace.yaml` to the confirmed workspace home `oats` using the shipped schema, alongside that repository's separate `oats.yaml` export index:
+
+- Intended members, selected source imports with real reviewed revisions and aliases.
+- Shared defaults bounded by soul requirements, not a new repository-level policy hierarchy.
+- Provider-owned knowledge declarations and team aliases only where meaningful and safe to publish.
+- Explicit discovery/catalog references if needed, not an OATS-hosted registry.
+
+Do not advertise a planned source export or uninitialized knowledge base as usable. Do not commit secrets, private runtime state or machine-specific execution paths into the public workspace. The phase2 knowledge destination can remain deliberately unresolved until it is initialized and approved.
+
+**Deliverable:** validated, reviewable workspace definition and a short explanation of shared versus operator-local choices.
+
+## P1.3 — publish repository indexes and reciprocal admission
+
+**Owner:** each repository/package owner, coordinated by the integration lead.
+
+For every intended member:
+
+- Add `oats.yaml` with the correct workspace backlink and actual exports.
+- Advertise package roots containing real `oats-package.json` files, not arbitrary npm roots.
+- Advertise only source-complete souls with explicit definition paths; imported souls remain references, not adopter-owned copies.
+- Add knowledge exports only when the provider declaration/base actually exists. A metadata-only bootstrap of the knowledge repository must not masquerade as corpus migration or a ready store.
+- Preserve package identities, compatible version floors, immutable releases and old locked revisions.
+
+Coordinate publication of backlinks and workspace admission. One side alone is not membership. Resolve the existing contract's default-branch observations and explicit revisions honestly; do not invent mutually dependent future commit pins or guess `main` when the host's default branch is required.
+
+**Deliverable:** discovery can qualify intended membership and enumerate real exports across repositories without requiring every source checkout to be present locally.
+
+## P1.4 — make the declared setup operational
+
+**Owner:** kernel/lifecycle owner and the owners of the selected capabilities.
+
+This is **adoption and validation first**, not a mandate to write new runtime code. Exercise the already shipped paths with correct declarations and inputs before changing them. A new inspection convenience is not automatically an adoption blocker; preserve it as a separate proposal unless necessity is demonstrated. Provider adaptation must identify the minimum usable completion path, not merely replace one refusal with a later refusal.
+
+Close only demonstrated gaps needed by the chosen workspace/profile:
+
+- Public inspection/preparation, explicit artifact approval, retained resolution, scaffold and native start through supported CLI/API paths.
+- Complete source/skill/capability closure; independent source, deployment and work-target identities.
+- Actual provider bindings, required hooks and their truthful readiness. A parsed team/store declaration is not enrollment or a working provider.
+- Required continuation, capture and applicable wake/retire/recovery behavior for the selected profile. A path that is still unsupported must be named and resolved, not hidden behind successful start-only evidence.
+- Version-correct operational skills and guidance, including known stale claims that public request/context/launch inputs are unavailable.
+- Any minimal Desktop compatibility needed to observe/refuse operations truthfully; full redesign parity is later.
+
+Use an explicitly agreed transitional edition of an existing role for the pilot, not a new fictitious owner or bootstrap host. Retain its actual requirements. Any temporary acceptance store/profile must be explicitly scoped and must not be counted as production knowledge adoption. Do not silently remove messaging, knowledge, plugins or other requirements to make it launch.
+
+New package defaults or executable changes require appropriate release/pinning/approval. Adding metadata does not itself require replacing stable runtime components, but a real runtime change is not deployed merely because it reached main.
+
+**Deliverable:** one reproducible operator path from the shared Git definition to a genuinely usable, retained portable instance under the chosen profile.
+
+## P1.5 — adopt fresh local deployments without disturbing existing work
+
+**Owner:** each local operator; coordinated readiness/evidence review by the integration lead.
+
+- Use a fresh explicit deployment location where existing managed state conflicts. Preserve old configs, locks, knowledge, identities, sessions, worktrees and pending jobs.
+- Map local repositories/work targets deliberately; operators need not have identical directory layouts.
+- Review exact software and restore/acquire through supported tooling. Keep native auth and deliberately chosen model/delivery behavior local.
+- Verify source discovery, reciprocal admission, imported identity, retained composition and actual start/continuation on the approved test host.
+- Check the second operator's declarations/readiness and an actual message/reply through its own identity without requesting model or GUI tests on that machine. Existing legacy connectivity is not automatically new-profile qualification.
+- Exercise relevant source-unavailability/update safeguards using owned test fixtures, never by deleting working source repositories or modifying retained artifacts.
+
+### Phase1 exit gate
+
+The shared workspace and repository declarations are published and discoverable; a fresh deployment can select a real portable source and complete the supported prepare/approve/scaffold/start path with its declared requirements. Required lifecycle/provider limitations are resolved or explicitly constrain the qualified profile. Both operators understand the same shared definition and their own local differences. Old live deployments remain preserved.
+
+**Seven YAML files alone do not satisfy this gate.** Nor does an isolated fixture establish production provider readiness. No claim that the five new knowledge-backed experts are adopted is made yet.
+
+# Distribution — official capabilities and the official marketplace
+
+**Status:** direction accepted by the human on 2026-09-20 (decision `agents/oats-expert/soul/knowledge/decisions/official-capabilities-oats-core-setup-and-marketplace.md`). Runs alongside phase1 once the current lanes' PRs are integrated; it changes how OATS itself is distributed and must be in place before phase2 souls are published, since those souls declare their capabilities explicitly.
+
+Today the skills that teach an agent to operate OATS (`oats`, `oats-config`, `oats-packages`) and the "you run on OATS" injection are ambient kernel content. Under Portable Souls a soul declares its capabilities and their sources, so this knowledge must be packaged as capabilities a soul can declare, remove or replace.
+
+## D1 — package `oats.core` and `oats.setup` from the oats repository
+
+**Owner:** capability/provider owner (packaging), reviewed by the integration lead.
+
+- `oats.core` — day-to-day operation, present on every soul by default: skill `oats-operate` (status, spawn, retire, doctor, lifecycle, instance layout) and skill `oats-souls` (soul discovery, spawn relations/linkage, roster, workspace-member souls), plus the former `injects/oats.md` injection.
+- `oats.setup` — deployment and workspace configuration ("OATS Soul Setup"): the former `oats-config` and `oats-packages` skills, workspace adoption guidance and package acquisition/trust/lock knowledge.
+- Both live under the framework's `oats-package/capabilities/` beside `oats-knowledge-theory`, are exported through the repository package manifest and `oats.yaml`, and are versioned/locked like any package. Content is moved from the existing skills, not re-authored; stale claims are corrected in the move.
+- The `instance-boundary` injection, work-mode briefings and config-declared injections **stay kernel-owned** — they describe the layout the kernel itself creates.
+
+**Deliverable:** two installable capabilities with manifests and focused inventory tests; the kernel unchanged except for registering nothing new.
+
+## D2 — explicit default `oats.core` on every soul; kernel skills de-ambiented
+
+**Owner:** kernel/lifecycle owner.
+
+- Every soul-creation path (CLI, Desktop, setup guidance) writes `requires.capabilities.oats.core` with its source into the soul definition. It is visible in the file and the user can remove it.
+- The kernel does **not** inject `oats.core` when absent; `oats doctor` reports a soul that has neither `oats.core` nor a deliberate opt-out note, as information, not an error.
+- The hard-coded kernel skill list and the `kernel:oats` injection are retired once souls carry `oats.core`. Transition: both coexist for one release, with existing kernel-listed skills marked deprecated in favor of the capability.
+- Existing checked-in souls in this repository are updated to declare `oats.core` explicitly as part of the same change.
+
+**Deliverable:** soul definitions are honest about OATS operational knowledge; no hidden kernel dependency.
+
+## D3 — onboarding creates and instantiates `oats-setup-expert`
+
+**Owner:** kernel/lifecycle owner, with the workspace/source owner for the soul edition.
+
+- Onboarding a new workspace (or a fresh deployment of one) produces a soul `oats-setup-expert` whose definition declares **both** `oats.core` and `oats.setup`, prepares/approves its artifacts under the normal approval bar, and instantiates it.
+- The setup expert then drives adoption: declaring/adopting member repositories, selecting fundamental-layer capabilities, creating further souls (each with explicit `oats.core`), and walking the operator through trust/approval steps. Setup becomes a conversation with a competent soul, not a wall of flags.
+- No new bootstrap authority: prepare/approve/scaffold/start remain the shipped path; onboarding only chooses the first soul and its capabilities. The entry point (CLI verb, Desktop flow, or both) and its relation to the version-scoped `oats init`/`oats use` compatibility path is proposed and reviewed separately; do not document a command before it exists.
+- The soul edition itself is source-complete and exported from the oats repository like the other framework souls.
+
+**Deliverable:** one reproducible path from "empty workspace" to a running `oats-setup-expert` that can configure the rest.
+
+## D4 — the official marketplace is the reviewed list in the oats repository
+
+**Owner:** workspace/source owner (list and docs); Desktop owner for the view in the parity phase.
+
+- `package-catalog.json` in `awebai/oats` (read today by `officialPackageCatalog()`) **is** the official marketplace. Listing = official. Do not build a second registry.
+- Officialness is granted by a reviewed PR to that file — for external packages too. That review is the safety gate: we control what is called official even when we do not host the code. Document the acceptance criteria (source-complete package, pinned immutable ref, payload root, trust posture, maintainer contact).
+- First entries: `oats.core`, `oats.setup`, `oats.okf`, `oats.aweb`, `oats.authoring`, `oats.jira`, `oats.linear`, `oats.dev`, `oats.knowledge-theory` (the fundamentals are already listed; add the two new ones once released).
+- Discovery is universal (CLI and Desktop marketplace view/search present official packages as assignable to a soul); installation still goes through acquisition, lock and per-capability executable trust. Discoverable is not installed; installed is not approved.
+
+**Deliverable:** documented official-list policy and seeded list; Desktop view tracked under phase3 parity.
+
+### Distribution exit gate
+
+A fresh workspace onboarding yields an `oats-setup-expert` whose definition shows `oats.core` and `oats.setup` resolved from the official list; a soul created by that expert shows `oats.core` explicitly and still runs after the user removes it; the kernel ships no ambient operational skill. Framework souls in this repository declare `oats.core`.
+
+# Phase 2 — centralise knowledge and adopt the five expert souls
+
+## P2.1 — align the reference knowledge profile
+
+**Owner:** OKF owner, with kernel review only for demonstrated generic-boundary gaps.
+
+Apply the accepted knowledge model to actual runtime instructions, skills, bindings and behavior:
+
+- Centralised per-soul homes with stable identity and explicit cross-reads.
+- Capability-owned organisation, placement, reading, capture, judgment and delivery—not a kernel-owned mandatory knowledge pipeline.
+- Distinct accepted knowledge, local evidence/working state and immutable execution artifacts.
+- Supported reading/refresh/capture for both short- and long-running instances; no automatic active-context synchronisation or silent curriculum replacement.
+- Independent promotion, reference doctrine and PR-only Git delivery, distinguishing proposal, accepted merge and reader visibility.
+
+Do not implement automatic speciation, redirects, whole-session cloning, a permanent maintenance agent or every alternative provider as prerequisites. Preserve their architectural possibility without claiming them shipped.
+
+## P2.2 — curate and publish the shared knowledge base
+
+**Owner:** knowledge steward, with human publication/visibility decision.
+
+- Confirm public/private visibility and access before publishing corpus or exposing private locators in the workspace.
+- Reuse the existing curation and disposition records. Add a focused freshness pass for subsequent accepted decisions and discoveries; do not redo the entire audit or bulk-copy legacy folders.
+- Preserve useful expertise, rationale, limitations and maintained slow state. Keep formal contracts/code navigation in docs, repeatable procedures in skills, and task residue/transcripts in local evidence.
+- Give each accepted concept one canonical home, valid cross-links and appropriate provenance/freshness.
+- Separate administrative repository/bootstrap scaffolding from corpus acceptance. Deliver the corpus through reviewed changes; ongoing runtime Git learning remains PR-only.
+
+**Deliverable:** a small, current, reviewed knowledge base with an explicit owner/read mapping, not merely a passing validator over relocated text.
+
+## P2.3 — publish and adopt the five expertise souls
+
+**Owner:** soul/source maintainer, reviewed by the integration lead and knowledge steward.
+
+The five permanent expertise roles are:
+
+1. `oats-expert` — overall direction and cross-cutting architectural judgment.
+2. `oats-kernel-expert` — kernel/capability contract rationale and technical expertise.
+3. `oats-desktop-expert` — Desktop/product/interaction expertise.
+4. `market-research-expert` — sourced research and positioning evidence.
+5. `oats-assistant` — user-facing adoption and onboarding help.
+
+Use source-complete portable declarations, canonical `AGENTS.md` and the `CLAUDE.md` alias, reviewed procedures, explicit capability requirements and stable knowledge bindings. Final export paths must be deliberately chosen before pinning imports. New adopters' learning must not silently default to the source publisher's writer.
+
+The optional knowledge-theory authoring expert is not a sixth mandatory runtime role. The public assistant must work through a real supported adoption path, not only as a maintainer-local role. A distinct cold-bootstrap helper protocol, if needed, requires its own scoped decision; do not invent a persistent owner to bypass helper authority.
+
+**Deliverable:** five indexed reusable sources, imported by the workspace at real compatible revisions, with the intended expertise/reading boundaries—not renamed engineer charters.
+
+## P2.4 — demonstrate learning, then switch writers/readers
+
+**Owner:** integration lead and OKF owner, with local operators.
+
+Use a small real end-to-end path:
+
+1. An expert obtains its accepted foundation and relevant cross-role context.
+2. A working instance captures a useful new finding.
+3. An independent worker judges it and delivers a Git PR.
+4. Authorised review/merge accepts it.
+5. A different/fresh instance obtains that accepted learning through the supported reader/refresh path.
+
+Do not seed the conclusion and call that learning. Check representative questions and source/binding correctness for all five roles without running five redundant full matrices.
+
+Then cut over the workspace imports/bindings deliberately. Reconcile or hold outstanding old harvests rather than retarget their frozen destinations; avoid duplicate old/new writers. Do not rename live homes or borrow identities. Keep original knowledge and work recoverable. Retirement/removal of superseded sources is a separately verified cleanup after unfinished work is safe.
+
+### Phase2 exit gate
+
+The five experts run from portable sources in the shared workspace, consult the curated common knowledge, and demonstrate actual reviewed Git learning visible to a subsequent reader. Publication, access, writer ownership and local runtime configuration are known. The old setup is preserved until this is true.
+
+# Execution and review discipline
+
+The initial implementation lanes are deliberately disjoint:
+
+| Lane | Owns | Does not own |
+|---|---|---|
+| Workspace/source declarations | Framework workspace/member indexes, transitional `souls/oats-expert/` edition preserving its existing logical owner, setup guide and metadata tests; other capability repositories' root `oats.yaml` only | Kernel or provider runtime, provider README/tests, framework mirrors, corpus migration |
+| Kernel/onboarding | Public preparation/lifecycle glue, same-repository workspace regression coverage and portable-setup skill | Root workspace/member indexes, soul editions, provider payloads, record optimisation |
+| Capability/provider readiness | Canonical OKF/aweb payloads, manifests, skills/docs/tests and actual profile-readiness facts | Kernel/record, root member indexes, soul editions, framework mirrors/catalog |
+| Integration lead | Scope/interface arbitration, exact review/integration, shared stewardship, release coordination and combined deployment acceptance | Unilateral changes to another operator's credentials, identity or local deployment |
+
+Distribution lanes (D1–D4) map onto the same owners: capability/provider readiness packages the two capabilities (D1); kernel/onboarding owns the explicit default, kernel de-ambienting and the setup-expert onboarding (D2, D3); workspace/source declarations own the official list and its policy docs (D4). They are assigned only after the current phase1 PRs are integrated, to avoid overlapping edits in `lib/core.mjs` and the skills tree.
+
+The phase1 transitional source is an edition of the existing overall expert, not the full five-role rebuild or an invented bootstrap owner. Source publication precedes workspace import pinning to its actual approved revision. An owner reports a precise cross-lane seam rather than patching another lane's files. No new review agents or per-edit permission loops are required for agreed work.
+
+- One redesign lead owns the cross-repository plan, dependency order, scope questions and integration picture. Contributors deliver bounded agreed work and exact diffs/PRs; no wholesale branch merges that import unrelated or held work.
+- Workspace/source metadata and compatibility work can proceed in parallel once their shared identities/contracts are agreed. Provider changes are reviewed against concrete missing seams, not speculative replacement architectures.
+- Local operator approval remains necessary for installation, executable trust, identity/team changes, deployment cutover and disclosure. Lead coordination is not authority over unrelated deployments.
+- Use focused changed-path checks while developing, then one coherent acceptance gate per usable increment. Keep original failed evidence and distinguish author reports, independent checks, installed bytes and real execution.
+- Preserve normal native harness auth and explicit permissions. No implicit credential handling, safety bypasses, source/identity borrowing or model/GUI testing on another operator's machine.
+- Publish updated versions only where code/payload changes require them; never move existing tags. Record delivery and actual adoption separately.
+
+# Decisions to settle at the appropriate boundary
+
+- Workspace home is settled: `oats` hosts it and `oats-dev` remains development capabilities. Phase1 authorises the parallel existing-role edition at `souls/oats-expert/`; preserve its logical owner and settle any remaining source-policy details before publishing. Final five-role publication/cutover remains phase2, not permission to replace the live roster now.
+- Confirm knowledge visibility and public-safe content before phase2 publication; this need not block the phase1 contract inventory.
+- Agree the exact pilot/provider/runtime profile and its supported lifecycle. No hidden fallback to an easier profile.
+- Review any newly identified generic contract or bootstrap authority change explicitly. Existing accepted constraints do not need repeated approval.
+
+# References
+
+- [Portable source/workspace declarations](2026-09-15-portable-declarations.md)
+- [Workspace schema](../oats-workspace.schema.json) and [repository index schema](../oats-member.schema.json)
+- [Fresh onboarding boundary](2026-09-16-portable-onboarding.md) — read historical pending statements with the actual current public routes and release scope
+- [Released0.24 scope](../release-notes/v0.24.0.md)
+- [Canonical knowledge theory](../knowledge-theory.md)
+- [Generic knowledge/capability boundary](2026-09-16-knowledge-capability-contract.md)

package/docs/design/2026-09-20-workspace-onboarding-public.md

@@ -0,0 +1,124 @@
+# Public source inspection for same-repository workspace onboarding
+
+This increment supplies the missing public adapter around the EXISTING portable
+onboarding facade. It does not define another workspace format, parser, resolver,
+registry, identity or permission. Source/member declarations remain separately
+owned; production capability/profile readiness is not established by the fixture.
+
+## Read-only entry
+
+```sh
+oats inspect --request /absolute/inspection.json --json
+```
+
+This mode accepts only one request file and `--json`. Explicit captured selectors
+or current-context flags conflict before file reads; inherited captured environment
+is not new-work input. Other existing inspect modes are unchanged. The shared
+bounded strict JSON request reader feeds the existing inspection validator intact:
+unknown fields are not dropped, and no missing context comes from current config.
+
+The public core export `inspectPortableOnboarding(input, {repositoryOptions}?)`
+owns one transient repository transaction and its guarded cleanup. Its input is
+the existing facade contract:
+
+```json
+{
+  "deployment": "/operator/deployments/example",
+  "workTarget": "/operator/projects/example",
+  "source": "advertised-alias",
+  "origin": {"kind":"operator","document":{"kind":"operator","id":"setup"},"pointer":"/source"},
+  "workspace": {
+    "source": "git:https://example.org/team/framework.git",
+    "origin": {"kind":"operator","document":{"kind":"operator","id":"setup"},"pointer":"/workspace"}
+  },
+  "member": {
+    "source": "git:https://example.org/team/framework.git",
+    "origin": {"kind":"operator","document":{"kind":"operator","id":"setup"},"pointer":"/member"}
+  }
+}
+```
+
+These paths/references are placeholders. Workspace and member may identify the
+SAME repository. They still require explicit workspace admission, a member
+backlink and matching observed commits. Omitted repository revisions observe the
+hosting default branch; they do not guess `main` or create circular future pins.
+
+Independent adoption replaces workspace/member with an explicit source reference
+`{source, soul, revision, alias}` and explicit `standaloneContextKey` (opaque string
+or null). It does not follow the source publisher's workspace backlink or inherit
+its development defaults/teams. A member check is optional; without one, import
+reports `not-requested` membership, never enrollment.
+
+## Metadata is not authority or provider readiness
+
+Normal JSON envelope `result` retains schemaVersion1 and the existing statuses:
+`ready-for-preparation`, `needs-configuration`, `separate-deployment-required`.
+`ok:true` means the observation succeeded, including a truthful hold. Separate
+fields expose source identity/revision/export metadata, deployment/work paths,
+workspace identity/import locators, reciprocal observations, declared teams and
+non-effect claims. Inspection executes no provider, hook, approval or native
+backend and writes no deployment state; repository scratch is transient.
+
+The public projection deliberately does NOT expose `source.reference` as a
+reusable mutation input. Opaque adoption values and provider declaration payloads
+have not been classified by their owner and are omitted. Import summaries expose
+`adoptionPresent`; knowledge export summaries expose contract/version and
+`payloadOmitted`. Top-level `omitted:{providerPayloads:true,adoptionValues:true}`
+states that this is a metadata view, not a lossless request or a safe-payload claim.
+It is not an issued `buildFreshPreparationRequest` witness, even in the same
+process. Keep the original authored input for an explicit preparation request.
+
+Existing managed deployment state is preserved and reported, not repaired or
+migrated. An absent selected path requires explicit operator provisioning and
+reinspection. The serialized inspection does not lock the filesystem or authorize
+later mutation; preparation retains its own existing validation/custody rules.
+The inspected work target does not become source identity or an implied placement
+choice. Supported captured directory scaffolds own their separate H/work.
+
+## Existing preparation and retained execution
+
+`oats prepare --request` already accepts deployment/source/origin, workspace/member
+OR standalone context, operator policy/bindings, mode/local-input authorization,
+launch and helperLaunches. Do not pass the inspection result or workTarget/catalog
+wrapper. Exact executable approval is separate. A required provider whose binding
+code is unapproved may return `needs-configuration` with an `approval-required`
+problem and exact artifact-set/capability requests, before any record exists:
+
+```sh
+oats trust <capability> --deployment <D> --artifact-set <returned-id> --json
+oats prepare --request /absolute/preparation.json --json
+oats inspect --deployment <D> --resolution <R> --composition --json
+oats spawn <subject> --deployment <D> --resolution <R> --home <new-H> --no-launch --json
+oats session start --deployment <D> --resolution <R> --home <H> --request /absolute/native.json --json
+```
+
+Repreparation after explicit approval is ordinary continuation in the selected,
+now-managed deployment; do not delete its state to make fresh preflight pass.
+Required hooks still run under their admitted custody with `--no-launch`; a parsed
+binding or team declaration is not proof of an enrolled/ready native provider.
+Native request version1 supplies backend/task/optional stopGraceMs, not a new
+model or current launch selection. Complete OATS home resources remain composed.
+Native auth stays native and permission bypass requires explicit user opt-in.
+
+## Limits and focused evidence
+
+`test/workspace-onboarding-public.test.mjs` uses current public CLI/core, actual
+Git and a bounded local SSH upload-pack fixture, contract-shaped inert provider
+codecs/hooks, and inert native/backend executables. It covers self-membership,
+reciprocal stale observations, independent adoption, non-effect/opaque-output
+boundaries, exact approval, full retained resources, source deletion/current
+config poison, required-provider failure BEFORE native admission/backend effects,
+and original-incarnation native dispatch plus receipt-based stopped observation.
+No production provider/SDK/model/server or host installation is exercised.
+
+Captured input/wake and public captured retirement remain explicit unsupported
+boundaries; a stopped terminal observation is not permission to deliver a captured
+message or retire through legacy fallback. Session-delivered messaging must retain
+its required wake contract; a start-only fixture does not qualify that profile.
+Non-directory placement is not supplied by inspecting a Git work target. These
+limits go to their owners as precise seams, not silent requirement removal.
+
+The user requested removal of `oats-portable-setup` and no new skills in this
+increment. Fresh kernel composition no longer selects that skill; existing
+retained snapshots are unchanged. This document and CLI help describe the public
+adapter, not a replacement skill or a claim of completed workspace deployment.

package/docs/design/README.md

@@ -0,0 +1,42 @@
+# Design documents — navigation
+
+Dated design documents record how decisions were reached and what each implementation slice was bounded to. They are **history with current pointers**: the current architecture is explained in [workspaces](../workspaces.md), [contracts](../layers.md), [souls and instances](../souls-and-instances.md) and [knowledge theory](../knowledge-theory.md); readiness is stated in the [release notes](../release-notes/). When a dated document and a current page disagree, the current page wins.
+
+## Current plan
+
+- [Redesign program board](2026-09-20-redesign-program-board.md) — live status of every work stream (knowledge contract, workspace adoption, messaging readiness, official capabilities, marketplace, five souls, centralised knowledge, Desktop), owners and blockers.
+- [Workspace-first adoption plan (2026-09-20)](2026-09-20-workspace-and-portable-adoption-plan.md) — phase order, lane ownership, distribution work packages (`oats.core`, `oats.setup`, official marketplace), exit gates.
+
+## Portable Souls and Git workspaces — the architecture
+
+- [Portable Souls explainer](2026-09-14-portable-souls-explainer.md) — the short version.
+- [Portable souls and Git-backed workspaces](2026-09-14-portable-souls-and-git-workspaces.md) — the accepted architecture.
+- [Contract amendments (14 Sep)](2026-09-14-portable-souls-contract-amendments.md) · [portable declarations](2026-09-15-portable-declarations.md) · [portable data/digest contract](2026-09-15-portable-data-contract.md) · [source observation](2026-09-15-source-observation.md).
+- [Fresh-install-first rollout](2026-09-16-fresh-install-first-rollout.md) · [fresh operator walkthrough](2026-09-16-fresh-operator-walkthrough.md) · [portable onboarding and discovery](2026-09-16-portable-onboarding.md) · [migration evidence](2026-09-16-portable-migration-evidence.md).
+
+## Retained execution — artifacts, approval, capture
+
+- [Artifact retention](2026-09-14-artifact-retention-contract.md) · [selection lock and approval](2026-09-15-selection-lock-and-approval.md) · [captured resolution records](2026-09-15-captured-resolution-records.md).
+- [Package preparation](2026-09-15-package-preparation.md) · [command/curriculum preparation](2026-09-16-command-profile-preparation.md) · [prepare request transport](2026-09-16-prepare-request-transport.md) · [public prepare request](2026-09-17-public-prepare-request.md).
+- [Captured dispatch](2026-09-15-captured-dispatch.md) · [captured admission](2026-09-16-captured-admission.md) · [retained helper dispatch](2026-09-16-captured-helper-dispatch.md) · [retained launch inputs](2026-09-16-captured-launch-inputs.md).
+- [Boundary resources](2026-09-17-portable-boundary-resources.md) · [boundary hookup](2026-09-17-portable-boundary-hookup.md) · [captured native start](2026-09-17-captured-native-start.md) · [public captured start](2026-09-17-public-captured-start.md).
+- [Backend parity: tmux and Herdr](2026-09-17-captured-backend-parity.md) · [Herdr protocol compatibility](2026-09-18-herdr-protocol-compatibility.md) · [captured Pi print host](2026-09-18-captured-pi-host.md).
+- [First-cut release checklist](2026-09-18-first-cut-release-checklist.md).
+- Implementation records: [implementation](2026-09-15-portable-souls-implementation.md) · [handoff](2026-09-15-portable-souls-handoff.md).
+
+## Capabilities and providers
+
+- [Package engine contract](package-engine-contract.md) · [package-runtime API](package-runtime-api.md) · [operations contract](operations-contract.md) · [launch configurations](launch-configurations.md).
+- [Provider binding wire v1](2026-09-16-provider-binding-wire.md) · [provider binding codecs](2026-09-16-provider-binding-codecs.md) · [capability helper/input contract](2026-09-17-capability-helper-input-contract.md).
+- [Knowledge capability contract](2026-09-16-knowledge-capability-contract.md) · [messaging capability contract](2026-09-16-messaging-capability-contract.md).
+
+## Knowledge and memory
+
+- [Knowledge and memory direction](2026-09-13-knowledge-and-memory-direction.md) · [knowledge location contract](2026-09-13-knowledge-location-contract.md) · [knowledge implementation plan](2026-09-13-knowledge-implementation.md) · [OKF mirror provenance](okf-mirror-provenance.md).
+
+## Product direction and Desktop
+
+- [Architecture reassessment](2026-09-07-architecture-reassessment.md) · [expert-assisted deployment](2026-09-08-expert-assisted-deployment-proposal.md).
+- [Desktop UX plan](desktop-ux-plan.md) · [souls and capabilities in Desktop](2026-09-07-desktop-souls-capabilities.md) · [mobile management proposal](2026-09-07-mobile-agent-management-proposal.md).
+
+Adding a design doc: date-prefix it, state its status in the first lines, and add it here under the right theme.

package/docs/first-team.md

@@ -42,6 +42,48 @@ For several repositories initialize their common workspace, then select the
 repository owning the soul with `--dir /path/to/workspace/project` for
 create/spawn/retire. A team roster does not select a work repository for spawn.
 
+## Onboarding with the setup expert
+
+For a kernel build that includes `oats onboard` (check `oats onboard --help`),
+start in an explicit empty deployment:
+
+```bash
+oats onboard --dir /absolute/new-deployment --json
+```
+
+This command is **not present in the published 0.24.0/0.24.1 kernels**. It is a
+classic local bootstrap, not captured preparation or workspace enrollment. It
+acquires `oats.framework` from the official catalog, exact-locks its artifacts,
+selects only `oats.core` and `oats.setup` for the new local `oats-setup-expert`,
+and prints the exact next spawn command. Review and run the returned
+`result.next.command` when ready; it addresses this same kernel and deployment.
+Onboarding itself never launches a model, changes native authentication or
+installs capture hooks/services. **`oats setup` remains the separate record
+capture-setup command**, not an alias for onboarding.
+
+The expert receives `oats-operate`, `oats-souls`, `oats-config`, `oats-packages`
+and `oats-workspace-setup`, without duplicate legacy kernel skill copies. It has
+no hard knowledge/messaging dependency, so it can help select and configure those
+providers afterward. Catalog identity grants no executable trust: the bootstrap
+uses resource-only core/setup capabilities and refuses unexpected executable
+surfaces instead of auto-approving them.
+
+An existing roster is refused unless `--force-existing` is explicit. That flag
+permits adding the new soul, not overwriting an existing setup expert or disabling
+providers for other souls. Failures report partial acquisition/creation rather
+than claiming atomic captured preparation. Preserve that evidence before retrying.
+
+Optional `--workspace git:host/org/repository[@revision]` reads the selected
+repository through ordinary discovery: use its pinned `oats-setup-expert` import
+when present, otherwise its own advertised `souls/oats-setup-expert` edition at
+the observed revision. Missing or incompatible explicit sources refuse; they do
+not fall back to the packaged default. The copied edition's package must match
+the official acquisition; workspace policy, teams and provider adoption values
+are not silently adopted. Without this option, only the packaged definition and
+instruction text are used—no knowledge corpus is bundled.
+
+The manual path below retains its stated older integration/version scope.
+
 ## Configure explicit knowledge and optional messaging
 
 Edit the existing entries in `oats-config.yaml`; do not append a second
@@ -212,4 +254,4 @@ oats recall "a phrase from your completed task"
 ```
 
 Capture respects privacy exclusions. Native turns are content-addressed; signed
-aweb messages retain their source signatures. See [the turn record](../README.md#the-turn-record).
+aweb messages retain their source signatures. See [where the turn record fits](2026-09-03-architecture-proposal.md#where-the-turn-record-fits).