@awebai/oats 0.24.0 → 0.24.1

package/bin/oats.mjs

@@ -23,7 +23,7 @@ import { enableTmuxMouse, tmuxConfigPath, tmuxMouseEnabled } from "../lib/tmux-c
 import {
   LAYERS, WORK_MODES, LEGACY_HOME_CAPABILITIES_DIR, OATS_LOCK_FILE, OATS_VERSION, OAS_SCOPE_REMEDY, RETIRED_CAPABILITIES, detectOasScopes, retiredCapabilityReason, configChain, configCapabilityEntries, manifestOperations,
   acquireCapability, restoreCapabilities, marketplaceCapabilities,
-  capabilityManifests, capabilityManifest, capabilityMissingRequires, capabilityIntegrity, capabilityTrust, capabilityExecutablePath, activateCapturedScaffold, loadCapturedDispatch, prepareCapturedComposition, resolveCapturedHelper, capturedNativeSessionAvailability, scaffoldCapturedInstance, startCapturedInstanceSession, withCapturedBindingFile, withCapturedInvocationContextFile,
+  capabilityManifests, capabilityManifest, capabilityMissingRequires, capabilityIntegrity, capabilityTrust, capabilityExecutablePath, activateCapturedScaffold, loadCapturedDispatch, inspectPortableOnboarding, prepareCapturedComposition, resolveCapturedHelper, capturedNativeSessionAvailability, scaffoldCapturedInstance, startCapturedInstanceSession, withCapturedBindingFile, withCapturedInvocationContextFile,
   readCapabilityLocks, writeCapabilityLock, admitCapturedAction, beginCapturedIntent, settleCapturedIntent,
   parsePackageSource, inspectGitSourceRoot, acquirePackage, restorePackages, listInstalledPackages, readPackageLocks, readLockedConfigTemplates,
   officialCapabilityPackage, officialPackageCatalog,
@@ -95,6 +95,21 @@ const CLI_BIN = realpathSync(fileURLToPath(import.meta.url));
 const jsonFail = (code, message, details) => { console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message), ...(details !== undefined ? { details } : {}) } })); process.exit(1); };
 const jsonOk = (result) => { console.log(JSON.stringify({ schemaVersion: 1, ok: true, result })); };
 
+function inspectOnboardingCmd() {
+  const fail = (code, message) => JSON_MODE ? jsonFail(code, message) : die(message);
+  let file;
+  for (let index = 1; index < args.length; index++) {
+    if (args[index] === "--json") continue;
+    if (args[index] !== "--request" || file !== undefined || !args[index + 1] || args[index + 1].startsWith("--")) fail("E_BAD_ARGS", "source inspection accepts one --request <absolute-json> and --json only");
+    file = args[++index];
+  }
+  try {
+    const input = readPortablePreparationRequest({ file });
+    const result = inspectPortableOnboarding(input);
+    if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
+  } catch (error) { fail(error.code || "E_INSPECT_FAILED", error.message); }
+}
+
 function prepareCmd() {
   const fail = (code, message, details) => JSON_MODE ? jsonFail(code, message, details) : die(message);
   const values = new Map(), allowed = new Set(["request", "dir", "source", "revision", "export", "alias", "workspace", "workspace-revision", "work"]);
@@ -4867,6 +4882,16 @@ catch (error) {
   if (JSON_MODE) jsonFail(error.code || "E_BAD_ARGS", error.message);
   die(error.message);
 }
+const sourceInspection = (cmd === "inspect" || captured?.args[0] === "inspect")
+  && args.some(arg => arg === "--request" || arg.startsWith("--request="));
+if (sourceInspection) {
+  if (captured) {
+    if (JSON_MODE) jsonFail("E_BAD_ARGS", "source inspection is explicit new work and cannot use captured selectors");
+    die("source inspection is explicit new work and cannot use captured selectors");
+  }
+  if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
+  inspectOnboardingCmd(); process.exit(0);
+}
 if (cmd === "prepare" || captured?.args[0] === "prepare") {
   if (captured) {
     if (JSON_MODE) jsonFail("E_BAD_ARGS", "prepare is explicit new work and cannot use captured selectors");
@@ -5184,6 +5209,9 @@ The turn record (core — every conversation captured, searchable, replicated):
                                             design, repo checkout only; see
                                             packages/experimental/README.md
 
+  oats inspect --request <absolute-json-file> [--json]
+                                            read-only fresh source/workspace/member metadata;
+                                            no current config, provider execution or preparation authority
   oats prepare --request <absolute-json-file> [--json]
                                             complete public preparation input; no mixed flags,
                                             inherited binding, implicit setup or launch authority

package/capabilities/oats-okf/lib/captured-worker.mjs

@@ -61,11 +61,19 @@ export function validateWorkerSelection(source,context,request,inspected){
   if(h?.key!==CAPTURED_WORKER_KEY||h.name!=='memory-harvest'||subject?.kind!=='helper'||subject.name!==h.name||subject.provider?.kind!=='capability'||subject.provider.capability!=='oats.okf'||!same(subject.provider,subject.definition?.owner))fail('E_CAPTURED_HELPER','wrong qualified helper identity');
   const api={schemaVersion:1,api:{contract:'oats.captured-session',version:2,available:true,backends:['tmux','herdr']},readiness:{status:'not-checked'}};
   if(!same(selected.launch,api)||!same(inspected.nativeSession,api))fail('E_CAPTURED_HELPER','unknown captured native public API');
-  // Exact retained model/runtime data is required; API availability alone is
-  // never qualification. Missing public selection stays closed, no private read.
+  // Preserve the exact retained selection. Ordinary Claude/Codex may select
+  // null to use their own native model configuration; Pi's strict SDK slice
+  // still needs an explicit model and its previously qualified sole-OKF profile.
+  // API availability/approval is NOT native readiness. The unchanged public
+  // scaffold/start path enforces the entire retained resource/hook closure.
   const launch=selected.launchSelection;
-  if(!obj(launch)||launch.runtime!==source.execution.runtime||launch.runtime!=='pi'||typeof launch.model!=='string'||!launch.model.trim()||(source.execution.model!==null&&launch.model!==source.execution.model))fail('E_CAPTURED_HELPER','retained helper launch runtime/model missing or mismatched');
-  if(!Array.isArray(inspected.capabilities)||inspected.capabilities.length!==1||inspected.capabilities[0].id!=='oats.okf'||inspected.capabilities[0].approval!=='approved')fail('E_CAPTURED_HELPER','only the exact approved default-OKF helper profile is qualified in this slice');
+  if(!obj(launch)||launch.runtime!==source.execution.runtime||!['pi','claude','codex'].includes(launch.runtime)
+    || !(launch.model===null?launch.runtime!=='pi':typeof launch.model==='string'&&!!launch.model.trim())
+    || (source.execution.model!==null&&launch.model!==source.execution.model))fail('E_CAPTURED_HELPER','retained helper launch runtime/model missing or mismatched');
+  const capabilities=inspected.capabilities;
+  if(!Array.isArray(capabilities)||!capabilities.length||capabilities.some(c=>!obj(c)||typeof c.id!=='string'||!/^(?:@?[a-z0-9][a-z0-9._-]*[./])[a-z0-9][a-z0-9._/-]*$/.test(c.id)||!['approved','not-required'].includes(c.approval))
+    || new Set(capabilities.map(c=>c.id)).size!==capabilities.length||!capabilities.some(c=>c.id==='oats.okf'&&c.approval==='approved'))fail('E_CAPTURED_HELPER','complete selected helper capability closure requires current approval');
+  if(launch.runtime==='pi'&&capabilities.length!==1)fail('E_CAPTURED_HELPER','enriched strict-Pi helper profile is not qualified; required capabilities were not removed');
   if(binding(selected.executionBinding).deployment!==source.executionBinding.deployment||!same(inspected.resolution,selected.executionBinding.resolution))fail('E_CAPTURED_HELPER','helper inspection resolution/deployment differs');
   return {schemaVersion:1,sourceBinding:JSON.parse(JSON.stringify(source.executionBinding)),helperBinding:JSON.parse(JSON.stringify(selected.executionBinding)),helper:JSON.parse(JSON.stringify(h)),request,requestHash:hash(request),sourceIntent:JSON.parse(JSON.stringify(context.intent)),sourceIncarnationId:context.instance.incarnationId,launchSelection:JSON.parse(JSON.stringify(launch))};
 }

package/capabilities/oats-okf/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "compatibility": {
     "oats": ">=0.24.0"
   },

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,70 @@
+# 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-20 17:40Z · main `87292f40` · OKF `v2.1.1`
+
+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) | ✅ shipped 0.24 / **OKF 2.1.1 released** (PR4 merged; mirror, catalog ref, soul source bumped) | P | done for this phase; OATS 0.24.1 cut after L's custody fix |
+| S2 | Workspace/Portable Souls adoption of the OATS repos | ✅ PR23 + PR24 merged · ✅ member `oats.yaml` on main in oats-okf/aweb/authoring/jira · ⛔ oats-dev, oats-linear (no push access, human) | M, L, lead | human grants access → push 0434f4ef/8c183c37; then pin imports; then fresh deployment gate |
+| S3 | Messaging capability readiness on the new infrastructure (aweb) | 🔄 codec PR2 + custody WIP · needs profile pin | P | lead pins pilot profile + answers authority question |
+| S4 | Official capabilities `oats.core` / `oats.setup` + explicit default + onboarding `oats-setup-expert` | 🔄 D1 in progress (P, `feat/d1-oats-core-setup`, package → `oats.framework` 1.1.0) · 🔄 D2 in progress (L) · ⬜ D3 | P (D1), L (D2, D3) | review D1/D2 PRs; assign D3 after D2 |
+| S5 | Official marketplace = reviewed list in oats repo | ✅ D4 merged PR26 (`docs/official-marketplace.md`, policy pointer) · ⬜ `oats.core`/`oats.setup` entries after D1 release | M | add entries at D1 release |
+| S6 | Five expert souls created in the oats repo (`souls/<name>/`) | 🔄 assigned to M (`feat/s6-expert-soul-editions`) from the reviewed candidate; `souls/oats-expert` on main | M | review PR; `oats.core` follow-up after D1 |
+| S7 | Centralised per-soul knowledge in `oats-knowledge` (migration + PR-only learning) | 🟡 35 curated concepts uncommitted on local `curation/expert-knowledge`; bootstrap proven on personal repo; `awebai/oats-knowledge` EMPTY, private | lead + human (visibility) | decide visibility; publish curation as PR; point souls' `stores.oats` at it |
+| S8 | Desktop parity (marketplace view, soul creation with `oats.core`, onboarding flow) | ⬜ after S4/S5 | fresh Desktop engineer (blocked: `claude` absent) | pick runtime; spawn |
+
+## 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 (0434f4ef) and oats-linear (8c183c37): neither M nor the lead's GitHub account has push — **human must grant access or push**.
+- ⬜ `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.
+
+## S3 — Messaging (aweb) on the new infrastructure
+- 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. 
+- 🔄 L finding c21e36ff accepted; fix assigned (L, `fix/home-route-captured-custody`): reuse `readCapturedInstanceAuthority` on the HOME-only route, refuse before transport.
+
+## S4 — `oats.core` / `oats.setup` / onboarding
+- ✅ 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** onboarding creates + instantiates `oats-setup-expert` (edition in `souls/`). Owner L (+M edition).
+- 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
+- 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`
+- 🟡 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
+- ⬜ 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
+1. `awebai/oats-knowledge` visibility (public vs private) — gates S7 publication.
+2. Push access to `awebai/oats-dev` and `awebai/oats-linear` for `josep-reyero` (or human pushes M's exact commits 0434f4ef / 8c183c37 as `oats.yaml`) — gates S2 completion.
+3. Desktop engineer runtime (Claude absent) — gates S8.

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.