@awebai/oats 0.24.1 → 0.24.3

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

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

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

@@ -0,0 +1,13 @@
+# OATS v0.24.3 — second-operator `prepare` seams
+
+Kernel/Pi/Desktop **0.24.3**. Fixes the five usability seams an independent second operator hit adopting the shared workspace definition on 0.24.1/0.24.2 (see the [program board](../design/2026-09-20-redesign-program-board.md)). No contract, schema or authority change.
+
+- **Attributed provider problems.** Every preparation problem now carries `slot`, `capability` and its `origins`, with kernel-fixed text that names the missing item (for example `oats.okf knowledge normalize binding could not be prepared` / `oats.aweb@1.10.3 declares no binding interface; messaging cannot be prepared`). One unqualified slot no longer masks another slot's diagnostics: every slot that has a binding interface is normalized, and the single resolver reports each invalid choice under its slot. Provider free text still never crosses the wire.
+- **`oats trust <capability> --dir <deployment>` on a lock v3 deployment** returns a typed problem with the exact working command (`oats trust <cap> --deployment <abs> --artifact-set <sha256-…>`) instead of `unsupported lockfileVersion 3`. No auto-approval.
+- **Help** documents `--artifact-set` and how `prepare`'s `selections[].artifactSet` / `approvalRequired[]` pair with it.
+- **`prepare` on an absent deployment path** returns a typed explicit-provisioning hold, not a raw `ENOENT` with a host path.
+- **One request file for both commands.** `prepare --request` accepts the explicit `workTarget` that `inspect --request` requires (explicit beats cwd; it never implies captured placement or current config), and `oats inspect --request <f> --emit-prepare-request <out>` writes the converted preparation request through the existing builder.
+
+The second operator's recorded requests and results are preserved verbatim as regression fixtures (`test/fixtures/second-operator/`). Their valid-vs-bogus `stores.oats` pair remains identical by design: both refused on missing OKF runtime settings (`bindings-file`, `state-dir`), which the messages now say.
+
+Setup guidance for those settings lands in the next `oats.framework` payload.

package/docs/souls-and-instances.md

@@ -54,6 +54,31 @@ in a soul bundle; see [knowledge](knowledge.md) for its prepared version scope.
 Future integrations may add expert-specific artifacts such as rule files or
 runtime-specific guidance, while keeping `AGENTS.md` canonical.
 
+## OATS operational knowledge is a capability
+
+New souls declare `requires.capabilities.oats.core` with a Git source resolved
+from the official package catalog. `oats create` and new local-soul scaffolds
+write that requirement; `--no-oats-core` explicitly omits it. If the catalog has
+no published revision yet, creation reports `needs-configuration` (also in JSON
+`notes`) and leaves the requirement absent rather than inventing a source.
+Declaring a capability is not acquiring, activating or approving it: those remain
+normal deployment/preparation steps. The Desktop server currently has no
+soul-creation endpoint; `oats soul set` edits existing definitions only.
+
+The dependency is visible and removable in `soul.yaml`. Updating an existing
+local soul preserves its requirements—including a deliberate removal—rather
+than applying the creation default again. For the one-release transition,
+a declaration of **either `oats.core` or `oats.setup`** suppresses the entire
+legacy kernel operational skill list (`oats`, `oats-config`, `oats-packages`)
+and `kernel:oats` injection. This also prevents setup's moved skill names from
+colliding with the kernel copies; no skill override is needed for this case.
+Without either declaration, legacy composition is unchanged.
+`oats doctor --soul <name>` reports an absent `oats.core` as an informational
+deprecation notice, not an error. Instance-boundary, work-mode and
+configuration-declared briefings remain kernel-owned. Existing captured records
+keep their retained resources; this does not migrate them or retire the kernel
+skill files yet.
+
 ## Instance anatomy
 
 An instance has a lifecycle, but need not be short-lived. It is the identity of

package/docs/workspace-adoption.md

@@ -5,12 +5,30 @@ source-complete exports and declares its own reciprocal membership. `oats-dev`
 remains a development-capability repository, including `oats.review`; membership
 neither activates that package nor replaces its existing configuration templates.
 
-This is phase 1: a shared repository graph and a transitional portable edition of
-**the existing oats-expert**. It is not the five-role rebuild, the curated knowledge
-cutover, a shared live runtime, a private-team enrollment or Desktop feature parity.
+This guide covers the shared repository graph and portable expert source editions,
+beginning with **the existing oats-expert**. Source publication is not a live
+five-role roster or curated knowledge cutover, a shared runtime, private-team
+enrollment or Desktop feature parity.
 The [phase plan](design/2026-09-20-workspace-and-portable-adoption-plan.md) and
 [knowledge model](knowledge-theory.md) retain those separate boundaries.
 
+## The five framework experts
+
+The indexed source editions are `oats-expert`, `oats-kernel-expert`,
+`oats-desktop-expert`, `market-research-expert` and `oats-assistant`. Each declares
+`owns` for its own same-named node and `reads` for the other four through logical
+store `oats`, preserving the reviewed owner UUIDs. These are knowledge-routing and
+context declarations, not access grants or proof of accepted knowledge. The parallel
+`souls/` editions neither replace the legacy `agents/` roster nor adopt the curated
+KB or change live instances; actual adoption still needs compatible providers and
+explicit bindings. All five now explicitly declare `oats.core` under
+`requires.capabilities`, with `source: repo:oats-package`. This retains the complete
+package from the same reviewed source revision.
+
+The dependency is visible and removable in the authored definition, not a change
+to existing captured records. An edited edition needs its own reviewed publication
+and import update; changing today's source does not rewrite an older pinned import.
+
 ## Shared versus local
 
 | Git-shared declaration | Operator-local input or evidence |
@@ -22,17 +40,18 @@ The [phase plan](design/2026-09-20-workspace-and-portable-adoption-plan.md) and
 | A reviewed source revision | Exact executable approval, current readiness and deployment acceptance |
 
 No machine paths, credentials, private team identifiers, accepted-store locator or
-owner registry belongs in the public workspace. The uninitialized phase-2 knowledge
-repository is not advertised as a ready knowledge export. Preserve the parked
+owner registry belongs in the public workspace. Knowledge publication and acceptance
+(S7) remain separate; no ready knowledge export is advertised. Preserve the parked
 roster/curation and every old home, lock, source, pending job, history and worktree.
 
 ## Planned onboarding: OATS Soul Setup (D3)
 
-**Not shipped in OATS 0.24.** The planned onboarding flow creates and instantiates
+**The D3 onboarding flow remains pending.** It will create and instantiate
 `oats-setup-expert`, declaring both `oats.core` and `oats.setup` from the
-[official marketplace](official-marketplace.md). Their package releases and this
-onboarding flow are future work, not existing catalog entries or a new command
-introduced by this guide.
+[official marketplace](official-marketplace.md). Those capabilities are now
+published in `oats.framework` 1.1.0 and listed; the separate setup-expert edition
+and onboarding entry point do not become available merely by listing the package.
+This flow was not shipped in the 0.24.0 or 0.24.1 kernel releases.
 
 - The setup expert will help the operator adopt repositories, select capabilities
   and carry out the normal prepare/approve/scaffold/start steps. It bypasses no
@@ -41,27 +60,29 @@ introduced by this guide.
   and its source explicitly. The operator can remove or replace that dependency
   by editing the authored definition, not a captured record; the kernel will not
   silently reinsert an absent one.
-- The CLI/Desktop entry point remains separately implemented and reviewed. Do not
-  invent a workspace init/adopt command, create a setup soul from this sketch, or
-  treat a planned package as installed. Existing instances and retained resources
-  are not rewritten by the plan.
+- The CLI/Desktop entry point still requires separate implementation and review.
+  Do not invent a workspace init/adopt command, create a setup soul from this
+  sketch, or treat a listed package as installed. Existing instances and retained
+  resources are not rewritten by the plan.
 
-## What this first source commit establishes
+## Stage two: published experts and pinned imports
 
 - `oats-workspace.yaml` explicitly admits `oats` and the six intended capability
   repositories: `oats-dev`, `oats-okf`, `oats-aweb`, `oats-authoring`, `oats-jira`
   and `oats-linear`. It activates no additional capability; tasks default to none.
-- `oats.yaml` advertises `souls/oats-expert` and the actual framework package roots
-  `oats-package` and `capabilities/oats-authoring`, not the npm root as a fictitious
-  OATS distribution. Its workspace backlink names the same framework repository.
-- `souls/oats-expert/` is parallel to, not a replacement for, the live `agents/`
-  source. It contains canonical instructions, `CLAUDE.md -> AGENTS.md`, and the
-  existing reviewed PR/release procedure closure. No durable KB is copied into it.
-- The role preserves its knowledge owner, owned node and four cross-read interests.
+- `oats.yaml` exports all five `souls/<name>` editions above and the actual package
+  roots `oats-package` (`oats.framework`) and `capabilities/oats-authoring`, not
+  the npm root as a fictitious OATS distribution. Its workspace backlink names
+  the same framework repository.
+- The editions are parallel to, not replacements for, the live `agents/` roster.
+  Each contains canonical instructions, `CLAUDE.md -> AGENTS.md`, and its reviewed
+  private procedures where applicable. No durable KB is copied into them; legacy
+  roster cutover remains deferred until S7 knowledge publication.
+- Each edition preserves its knowledge owner, owned node and four cross-reads.
   Store `oats` requires the explicit `stores.oats` binding; no publisher writer,
   production store or grants are supplied. An acceptance fixture is parent-owned
   and cannot be counted as production knowledge adoption.
-- Knowledge **oats.okf@2.1.1** and messaging **oats.aweb@1.10.3** are explicit hard
+- Knowledge **oats.okf@2.1.1** and messaging **oats.aweb@1.11.0** are explicit hard
   requirements, not optional defaults. They are published starting revisions,
   **not proof that their combined bindings/runtime profile is ready**. The provider
   owner supplies that evidence and any subsequently reviewed compatible revision.
@@ -69,38 +90,41 @@ introduced by this guide.
 
 At these starting pins, the provider boundary is concrete:
 
-- Published OKF2.1.0 already supports `inherit: stores.oats`, normalized to
+- Published OKF2.1.1 supports `inherit: stores.oats`, normalized to
   `/bindings/knowledge/stores/oats`. The explicit `destination: oats` preserves
   routing; omitting it would instead require `write.default`. No new schema,
   owner or production locator is needed for this declaration.
-- Released aweb1.10.3 (`24efa6f9`) has **no mandatory portable binding interface**,
-  so it currently blocks this pilot's portable preparation. Candidate
-  [aweb PR2](https://github.com/awebai/oats-aweb/pull/2), `165b20e7`, adds codecs;
-  it is not a reviewed/published successor or native lifecycle qualification.
-  Human/native-principal, private-context, admin/grant and admitted-lifecycle
-  requirements remain provider/integration-owner work.
-- Published OKF2.1.0's captured worker profile retains its strict Pi,
-  explicit-model and sole-OKF limitation. Candidate
-  [OKF PR4](https://github.com/awebai/oats-okf/pull/4), `7cff887c`, preserves retained
-  Claude/Codex/null-model intent and the approved helper capability closure;
-  review is pending, not published2.1.0 behavior. Pi plus messaging is still
-  unqualified. Do not silently switch runtimes, force a model, or drop capabilities.
+- aweb 1.10.3 (`24efa6f9`) has no portable binding interface; **aweb 1.11.0**
+  (`v1.11.0`, OATS >=0.24.2) adds it and the five editions now pin it. Its `check`
+  qualifies only an input-capable Claude/Codex primary with an explicit private team
+  and `delivery: session`; strict-Pi print reports `needs-configuration`. Status is on
+  the [program board](design/2026-09-20-redesign-program-board.md). Qualification
+  is HOME-route operational custody only: not human/native-principal delegation,
+  private grants, broker delivery or model consumption.
+- Published OKF2.1.1 accepts retained Claude/Codex helpers with the complete approved
+  capability closure and native-default model intent. Strict Pi still requires an
+  explicit model and the sole-OKF profile; Pi plus messaging remains unqualified.
+  This provider release alone is not combined-profile acceptance. Do not silently
+  switch runtimes, force a model, or drop capabilities.
 
 These are explicit readiness holds, not reasons to weaken the source. Parent must
 select reviewed compatible provider revisions and update the source pin deliberately
 before claiming an operational pilot; metadata-only repository indexes change none
 of these runtime facts.
 
-The workspace intentionally starts with **`imports: []`**. A source cannot pin a
-future commit containing itself. This first commit is publishable source metadata,
-not an already usable/adopted pilot graph or a phase-1 exit verdict.
+Stage one used an empty imports list until source publication. Stage two is now
+committed: all five imports pin **`caa341f34009e37006567419a983d5a743037a79`**, the
+published edition revision containing explicit core requirements and the package.
+The later workspace commit `375b9f42` added those imports. Live source inspection
+against published main resolved all five as `ready-for-preparation`; this is
+metadata readiness, not provider binding, approval, enrollment or a running pilot.
 
-## Publish in this order
+## Preserve source-before-import publication order
 
-1. Review and publish this source/export commit to the framework repository. Save
-   the **actual reviewed immutable source commit** containing the complete soul.
-   Do not put an invented SHA, a mutable branch or an unreviewed local candidate
-   in the workspace import and describe it as the accepted source.
+1. Publish complete, reviewed source editions before pinning them. The current
+   source is `caa341f34009e37006567419a983d5a743037a79`; future revisions must likewise
+   exist before their workspace import update. Never use an invented SHA, a mutable
+   branch or an unreviewed local candidate as the accepted source.
 2. In each of the six repositories, review a root `oats.yaml` against its actual
    source head and actual `oats-package/oats-package.json`. The declaration is:
 
@@ -114,21 +138,25 @@ not an already usable/adopted pilot graph or a phase-1 exit verdict.
    ```
 
    Preserve payloads, versions, old tags and legacy templates. This does not
-   activate oats.dev, messaging or either optional task integration.
-3. In a subsequent reviewed framework commit, replace the empty imports list with
-   an import of the source commit from step 1:
+   activate oats.dev, messaging or either optional task integration. Indexes are
+   published on `main` in all six capability repositories (oats-okf, oats-aweb,
+   oats-authoring, oats-jira, oats-dev, oats-linear); their publication proceeded
+   separately from the framework's own source imports.
+3. A subsequent workspace commit pins the published source, never itself or a
+   future commit. The current first import is:
 
    ```yaml
    imports:
      - source: git:github.com/awebai/oats
        soul: souls/oats-expert
-       revision: <actual-reviewed-published-source-commit>
+       revision: caa341f34009e37006567419a983d5a743037a79
        alias: oats-expert
    ```
 
-   The placeholder is explanatory text, never a value to commit. Update the
-   staged-import test with that real publication evidence at this step. Do not
-   change the stable export path or owner merely because the workspace advances.
+   The [actual workspace](../oats-workspace.yaml) contains all five imports at that
+   same revision; this excerpt is not a replacement for the full list. The layout
+   test now checks stage-two imports and source-document declarations. Do not
+   change stable export paths or owners merely because the workspace advances.
 4. Qualify reciprocal admission at the now-published observations. A missing
    backlink, a fork's copied file or a stale workspace observation is not membership.
    Cross-repository indexes may land separately; until both sides exist, report the
@@ -149,19 +177,18 @@ may consume it without membership in the OATS development workspace.
 
 ## Inspect source metadata before preparation
 
-The public source inspector is implemented in **PR24, commit
-`bc598c484fd097fc5707fd4a33b7877ca00e5da3`**. Use this section only after the
-integration owner supplies a reviewed CLI containing that implementation. It is
-**not a command supported by the original 0.24.0 release**: that older inspect
-route can ignore the request flag and consult ambient classic configuration.
-Do not infer availability from the version floor of a capability.
+The public source inspector ships in [OATS 0.24.1](release-notes/v0.24.1.md),
+following PR24 integration. Use an installed CLI containing that implementation.
+It is **not supported by the original 0.24.0 release**: that older inspect route
+can ignore the request flag and consult ambient classic configuration. Do not
+infer command availability from a capability's version floor or today's catalog.
 
 ```sh
 oats inspect --request /absolute/inspection.json --json
 ```
 
-After the real workspace import from publication step 3 exists, the authored
-inspection input may use the same repository for workspace, member and source:
+With the stage-two imports published, the authored inspection input can use the
+same repository for workspace, member and source:
 
 ```json
 {
@@ -222,7 +249,7 @@ Before preparing, the integration lead must supply:
 - The published workspace/source observations and an explicit fresh physical
   deployment/home placement. Do not copy old locks, retained records or identities.
 - An operator-owned nonsecret request with `workspace` (its source and origin),
-  `source: "oats-expert"` after the real import is published, and `mode: "directory"`.
+  `source: "oats-expert"` (or another published expert alias), and `mode: "directory"`.
   Standalone callers instead give the complete `{source,soul,revision,alias}`
   reference and an explicit standalone context; they do not inherit this workspace.
 - Explicit provider-specific settings and bindings. OKF preparation needs selected
@@ -236,7 +263,7 @@ Before preparing, the integration lead must supply:
   `operator.policy.messaging` selection: capability, matching selected source and
   `settings: {delivery: session}`. Retain host requirements, session `ifInstalled`
   minimums and any selected authoring requirements. Selecting session delivery neither
-  adds the missing1.10.3 binding adapter nor supplies captured wake/input authority.
+  makes a strict-Pi print primary input-capable nor supplies captured wake authority.
 - A qualified primary/helper runtime/model/resource profile. Capture the intended
   helper selection in `helperLaunches["oats.okf:memory-harvest"]`, not the legacy
   `souls.memory-harvest` configuration. Do not replace retained intent to fit an easier
@@ -262,10 +289,12 @@ Do not mix other preparation flags into request-file mode. A needs-configuration
 approval result is not a ready instance. A scaffold materializes resources and may
 run approved hooks; it is not a message exchange or model session. Actual dispatch,
 continuation, native capture, messaging and learning require the integration owner's
-qualified profile and receipts. Captured wake/input and public captured retirement
-remain unsupported; a stopped-home observation is not delivery or retirement authority.
-A session-delivered messaging profile therefore cannot pass on start-only evidence.
-Do not route it through legacy input/retire or remove the messaging requirement.
+qualified profile and receipts. OATS 0.24.1 adds captured custody checks to the
+existing HOME-only session inspect/input route; it does not supply the missing
+messaging adapter or qualify every lifecycle route. Verify wake/input/retirement
+support for the exact route and runtime. A stopped-home observation is not delivery
+or retirement authority, and a messaging profile cannot pass on start-only evidence.
+Do not bypass custody with a legacy fallback or remove the messaging requirement.
 Consult the current installed public help and the provider's supported commands;
 this guide introduces no new CLI grammar. The source inspector above is a separate
 implementation dependency, not a change to the existing prepare request contract.
@@ -282,4 +311,4 @@ indexes are not evidence that the six real repositories are already published.
 Source and metadata checks do not enroll users, initialize the phase-2 store, register
 production writers or qualify private messaging. Parent alone coordinates publication,
 local operator approval and actual adoption. Full Desktop parity follows usable
-infrastructure adoption, not merely seven YAML files passing validation.
+infrastructure adoption, not merely source metadata passing validation.

package/injects/oats-portable.md

@@ -9,6 +9,10 @@ configuration cascade, package lock, similarly named capability, or source path.
 Load **oats-portable** before invoking or reasoning about captured OATS commands.
 Load **oats-portable-artifacts** for exact retained inspection and approval. Do not load the legacy **oats**,
 **oats-config**, or **oats-packages** procedures to fill a captured input.
+If this retained composition includes **oats.core**, its **oats-operate** and
+**oats-souls** skills are capability resources, not implicit kernel additions.
+Use only the resources actually included; a missing capability is not permission
+to fetch or substitute a current version.
 
 Captured start/restart use exact retained launch inputs and supported native
 endpoints. Captured wake/retire, unqualified runtime contributions and non-directory

package/lib/core.mjs

@@ -51,6 +51,7 @@ import { buildCapturedInvocationContext, withCapturedInvocationContextFile } fro
 import { readCapturedInstanceIndex, readCapturedInstanceMetadata, readCapturedInstanceAuthority, assertCapturedInstanceCustody,
   recordCapturedCustodyFailure, markCapturedNativeScaffold, failCapturedNativeIntent, observeCapturedNativeTarget, setCapturedInstanceStatus, admitCapturedInstanceAction, beginCapturedIntent, settleCapturedIntent } from "./captured-instance-index.mjs";
 import { validateExecutionBinding } from "./schedule-capsule.mjs";
+import { parsePortableSource } from "./source-spec.mjs";
 import { validateIntentRef } from "./captured-admission-shape.mjs";
 export { readCapturedInstanceIndex, readCapturedInstanceMetadata, beginCapturedIntent, settleCapturedIntent };
 export { buildCapturedInvocationContext, withCapturedInvocationContextFile };
@@ -61,7 +62,7 @@ import { validateCapturedLaunchRequest } from "./captured-launch-request.mjs";
 import { validateCapabilityInputDeclarations } from "./capability-inputs.mjs";
 import { validateCapturedSessionBackend, validateCapturedSessionTarget, assertCapturedSessionPlacement } from "./captured-session-backend.mjs";
 import { createRepositoryTransaction } from "./repository-observation.mjs";
-import { inspectPortableOnboarding as inspectOnboarding, describePortableOnboarding } from "./portable-onboarding.mjs";
+import { inspectPortableOnboarding as inspectOnboarding, describePortableOnboarding, buildFreshPreparationRequest, inspectWorkTarget } from "./portable-onboarding.mjs";
 import { readLock3 } from "./portable-lock.mjs";
 import { portableScope, portableStateDirectory } from "./portable-state.mjs";
 import { objectAt } from "./portable-shape.mjs";
@@ -112,6 +113,18 @@ export const OATS_VERSION = JSON.parse(readFileSync(join(PKG_ROOT, "package.json
 /** Skills shipped with the kernel. Only oats-getting-started is ambient; spawn composes selected skills locally. */
 export const PACKAGED_SKILLS_DIR = join(PKG_ROOT, "skills");
 
+function soulRequirements(soulDir) {
+  const file = soulDir && join(soulDir, "soul.yaml");
+  return file && existsSync(file) ? withConfigFile(file, () => parseYamlNested(readFileSync(file, "utf8"))).requires : undefined;
+}
+function declaredOperationalCapabilities(soulDir) {
+  const capabilities = soulRequirements(soulDir)?.capabilities ?? {};
+  return ["oats.core", "oats.setup"].filter(id => Object.hasOwn(capabilities, id));
+}
+function legacyOperationalSkills(soulDir) {
+  return declaredOperationalCapabilities(soulDir).length ? [] : ["oats", "oats-config", "oats-packages"].map(name => ({ id: "kernel", path: join(PACKAGED_SKILLS_DIR, name) }));
+}
+
 // ---------- shell helpers ----------
 function sh(cmdline) { return execSync(cmdline, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
 function shTry(cmdline) { try { return sh(cmdline); } catch { return undefined; } }
@@ -1198,13 +1211,17 @@ export function approveAvailableCapability(deployment, artifactSet, capability,
 /** Public read-only source/workspace inspection through the existing facade.
  * Owns only transient repository scratch, never deployment state, provisioning,
  * provider code, approvals or a serialized mutation witness. */
-export function inspectPortableOnboarding(input, { repositoryOptions = {} } = {}) {
+export function inspectPortableOnboarding(input, { repositoryOptions = {}, includePrepareRequest = false } = {}) {
   canonicalJson(input);
+  if (typeof includePrepareRequest !== "boolean") throw oatsError("invalid-declaration", "request conversion requires an explicit boolean option");
   const directory = mkdtempSync(join(realpathSync(tmpdir()), "oats-source-inspection-")), owned = lstatSync(directory);
   let repositories, primary;
   try {
     repositories = createRepositoryTransaction({ ...repositoryOptions, directory, accessContextKey: repositoryOptions.accessContextKey ?? "native" });
-    return describePortableOnboarding(inspectOnboarding(input, { repositories }));
+    const inspection = inspectOnboarding(input, { repositories }), result = describePortableOnboarding(inspection);
+    // Opt-in data export, not a serialized custody witness or executable grant.
+    // Default metadata continues to omit unclassified adoption/provider values.
+    return includePrepareRequest ? { ...result, prepareRequest: buildFreshPreparationRequest(inspection).preparation } : result;
   } catch (error) { primary = error; throw error; }
   finally {
     try {
@@ -1226,21 +1243,28 @@ export function inspectPortableOnboarding(input, { repositoryOptions = {} } = {}
  * a fabricated complete record. No lifecycle side effects run here. */
 export function prepareCapturedComposition(input, { repositoryOptions = {} } = {}) {
   canonicalJson(input);
-  objectAt(input, ["deployment", "source", "origin", "workspace", "member", "operator", "mode", "allowLocalPaths", "standaloneContextKey", "launch", "helperLaunches"], ["deployment", "source"]);
+  objectAt(input, ["deployment", "workTarget", "source", "origin", "workspace", "member", "operator", "mode", "allowLocalPaths", "standaloneContextKey", "launch", "helperLaunches"], ["deployment", "source"]);
   if (input.launch !== undefined) validateCapturedLaunchRequest(input.launch, validateLaunchConfig);
   if (input.helperLaunches !== undefined) {
     objectAt(input.helperLaunches, null, []);
     for (const request of Object.values(input.helperLaunches)) validateCapturedLaunchRequest(request, validateLaunchConfig);
   }
   if (input.mode !== undefined && !WORK_MODES.includes(input.mode)) throw oatsError("invalid-declaration", "invalid preparation work mode");
-  const deployment = portableScope(input.deployment);
+  const { workTarget, ...preparationInput } = input;
+  const target = Object.hasOwn(input, "workTarget") ? inspectWorkTarget(workTarget) : null;
+  let deployment;
+  try { deployment = portableScope(input.deployment); }
+  catch (error) {
+    if (error.code === "ENOENT") throw oatsError("needs-configuration", "deployment directory is absent; provision the explicitly selected directory and inspect again before preparation");
+    throw error;
+  }
   const previous = readLock3(deployment); // Old state refuses before scratch/fetch.
   const directory = mkdtempSync(join(portableStateDirectory(deployment, true), ".prepare-")), owned = lstatSync(directory);
   const origin = input.origin ?? { kind: "operator", document: { kind: "operator", id: "oats-prepare" }, pointer: "/source" };
   let repositories, primary, catalog;
   try {
     repositories = createRepositoryTransaction({ ...repositoryOptions, directory, accessContextKey: repositoryOptions.accessContextKey ?? "native" });
-    return prepareComposition({ ...input, deployment, origin, directory }, { repositories, previous, kernel: {
+    const result = prepareComposition({ ...preparationInput, deployment, origin, directory }, { repositories, previous, kernel: {
       loadPackageManifestAt, capabilityCompatibility, assertPlatformInvariantLocks, materializeCapability,
       manifest: loadRetainedManifest,
       binding: runCapturedProviderBinding,
@@ -1253,6 +1277,8 @@ export function prepareCapturedComposition(input, { repositoryOptions = {} } = {
         settings: assertCapabilitySettingValues, skills: skillEntriesIn, hooks: manifestHookDeclarations,
         validateLaunchConfig, runtimeRequirements: applicableRequirements }),
     } });
+    // Explicit work context never selects source/config, cwd, or H/work placement.
+    return target ? { ...result, workTarget: target } : result;
   } catch (error) { primary = error; throw error; }
   finally {
     try {
@@ -4083,6 +4109,10 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
   if (!existsSync(agentsMd)) throw new Error(`canonical soul instructions missing: ${agentsMd}`);
   const resolved = resolveOatsConfig(contextDir, soulName);
   const wanted = [];
+  const declaredOperations = declaredOperationalCapabilities(soulDir);
+  const oatsCoreDeclared = declaredOperations.includes("oats.core");
+  if (declaredOperations.length) resolved.kernelInjection = { inject: undefined,
+    provenance: `declared ${declaredOperations.join(", ")} ${declaredOperations.length === 1 ? "capability" : "capabilities"}` };
   const kernelInject = resolved.kernelInjection?.inject;
   if (kernelInject && existsSync(kernelInject)) wanted.push(["kernel:oats", kernelInject]);
   if (kind === "local") {
@@ -4104,7 +4134,7 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
   }
   for (const inj of resolved.injects) wanted.push([`config:${inj.source}`, inj.file]);
   const blocks = wanted.map(([source, file]) => ({ source, file, content: readFileSync(file, "utf8").trim() }));
-  return { text: renderInstructionText(readFileSync(agentsMd, "utf8"), blocks), blocks, resolved };
+  return { text: renderInstructionText(readFileSync(agentsMd, "utf8"), blocks), blocks, resolved, oatsCoreDeclared };
 }
 
 /** The skill entries a tree contributes — THE discovery rule, shared by preflight
@@ -4162,7 +4192,7 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
     }
   };
 
-  for (const path of [join(PACKAGED_SKILLS_DIR, "oats"), join(PACKAGED_SKILLS_DIR, "oats-config"), join(PACKAGED_SKILLS_DIR, "oats-packages")]) {
+  for (const { path } of legacyOperationalSkills(soulDir)) {
     add({ type: "skill-tree", source: "kernel", declared: basename(path), path: existsSync(path) ? path : undefined });
   }
   const soulSkills = soulDir && join(soulDir, "skills");
@@ -5110,15 +5140,31 @@ export function resolveYolo(value) {
   throw new Error("yolo must be true or false");
 }
 
-export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo, description, type, instructions }) {
+/** Creation chooses a declared source, never acquisition/activation or a made-up
+ * future release. Existing definitions (including deliberate removal) are kept. */
+function defaultOatsCoreRequirement() {
+  const mapping = officialCapabilityPackage("oats.core");
+  const entry = mapping.available && mapping.migratedCapability === "oats.core" && officialPackageCatalog()[mapping.package];
+  if (entry && typeof entry.url === "string" && typeof entry.ref === "string" && entry.ref) {
+    const parsed = parsePortableSource(`git:${entry.url}@${entry.ref}#${entry.path ?? DEFAULT_PACKAGE_PATH}`);
+    return { requires: { capabilities: { "oats.core": { source: `${parsed.source}#${parsed.path}` } } }, notes: [] };
+  }
+  return { requires: undefined, notes: [{ code: "needs-configuration", message: "oats.core has no published revision in the official package catalog; no source was invented. Add its explicit requirement after the catalog entry is available, or use --no-oats-core to opt out at creation." }] };
+}
+
+export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo, description, type, instructions, oatsCore = true }) {
   yolo = resolveYolo(yolo);
+  if (typeof oatsCore !== "boolean") throw oatsError("E_BAD_ARGS", "oatsCore must be a boolean");
   const agentDir = agentDirOf(root, name, kind);
-  const soulDir = soulOf(agentDir);
+  const soulDir = soulOf(agentDir), soulFile = join(soulDir, "soul.yaml");
+  const { requires, notes } = existsSync(soulFile)
+    ? { requires: soulRequirements(soulDir), notes: [] }
+    : oatsCore ? defaultOatsCoreRequirement() : { requires: undefined, notes: [] };
   mkdirSync(soulDir, { recursive: true });
   mkdirSync(join(agentDir, "instances"), { recursive: true });
-  writeFileSync(join(soulDir, "soul.yaml"), yamlFlat({
+  writeFileSync(soulFile, yamlFlat({
     name, kind, description, type, repo, work: work || "checkout", runtime: runtime || "pi", model, yolo,
-  }));
+  }) + (requires === undefined ? "" : `requires: ${JSON.stringify(requires)}\n`));
   const agentsMd = join(soulDir, "AGENTS.md");
   if (instructions !== undefined || !existsSync(agentsMd)) {
     writeFileSync(agentsMd, instructions ?? defaultSoulAgentsMd(name, description));
@@ -5132,7 +5178,7 @@ export function writeSoul(root, { name, kind, repo, work, runtime, model, yolo,
     home: soulDir, instance: name, agentName: name, soulDir,
     contextDir: ctx, workspaceDir: workspaceOf(root), rootDir: root, resolved,
   });
-  return { agentDir, soulDir };
+  return { agentDir, soulDir, ...(notes.length ? { notes } : {}) };
 }
 function defaultSoulAgentsMd(name, description) {
   return `# ${name}
@@ -5154,8 +5200,8 @@ export function createAgent(root, o) {
   // kind: "local" → a FULL soul (memory, skills, instances) under the scope's
   // local-agents/ — uncommitted by contract; otherwise a committed persistent soul.
   const kind = o.local || o.kind === "local" ? "local" : "persistent";
-  const { agentDir } = writeSoul(root, { ...o, name, kind });
-  return { agent: name, kind, soul: soulOf(agentDir) };
+  const { agentDir, notes } = writeSoul(root, { ...o, name, kind });
+  return { agent: name, kind, soul: soulOf(agentDir), ...(notes ? { notes } : {}) };
 }
 
 /** Upsert a local agent soul (from raw instructions or a Claude-style def file).
@@ -5182,13 +5228,13 @@ export function upsertLocalAgent(root, o) {
   const existing = findAgent(root, name);
   if (existing && existing.kind !== "local") throw new Error(`"${name}" is a persistent agent — spawn it instead`);
   if (!existing && instructions === undefined) throw new Error(`local agent "${name}" needs instructions (none on disk yet)`);
-  writeSoul(root, {
-    name, kind: "local",
+  const { notes } = writeSoul(root, {
+    name, kind: "local", oatsCore: o.oatsCore,
     repo: repo ?? existing?.repo, work: work ?? existing?.work,
     runtime: runtime ?? existing?.runtime, model: model ?? existing?.model, yolo: yolo ?? existing?.yolo,
     description: description ?? existing?.description, instructions,
   });
-  return findAgent(root, name);
+  return { ...findAgent(root, name), ...(notes ? { notes } : {}) };
 }
 /** Back-compat alias: older installed capabilities (oats-okf ≤1.3.x) call this. */
 export const upsertTmpAgent = upsertLocalAgent;
@@ -6136,7 +6182,7 @@ export function spawnInstance(root, agent, o = {}) {
   symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
 
   // Runtime-neutral exact skill materialization. No harness receives ambient workspace/package skills.
-  const sources = [{ id: "kernel", path: join(PACKAGED_SKILLS_DIR, "oats") }, { id: "kernel", path: join(PACKAGED_SKILLS_DIR, "oats-config") }, { id: "kernel", path: join(PACKAGED_SKILLS_DIR, "oats-packages") }];
+  const sources = legacyOperationalSkills(soulDir);
   const soulSkills = join(soulDir, "skills");
   if (existsSync(soulSkills)) sources.push({ id: "soul", path: soulSkills });
   for (const cap of resolvedCfg.capabilities) for (const path of cap.skills || []) sources.push({ id: cap.id, path });

package/lib/portable-onboarding.mjs

@@ -108,7 +108,7 @@ export function preflightFreshDeployment({ deployment, maxEntries = 4096 }) {
   return result;
 }
 
-function workTarget(path) {
+export function inspectWorkTarget(path) {
   const canonical = canonicalExistingDirectory(path, "work target"), marker = present(join(canonical, ".git"));
   return { path: canonical, state: "existing", git: marker ? { present: true, kind: marker.isDirectory() ? "directory" : marker.isFile() ? "file" : "other" } : { present: false, kind: null } };
 }
@@ -146,7 +146,7 @@ export function inspectPortableOnboarding(input, { repositories } = {}) {
   validateOrigin(input.origin);
   const standalone = explicitContext(input);
   const deployment = preflightFreshDeployment({ deployment: input.deployment });
-  const target = workTarget(input.workTarget), discovery = createWorkspaceDiscovery(repositories);
+  const target = inspectWorkTarget(input.workTarget), discovery = createWorkspaceDiscovery(repositories);
   const witness = { deployment: preflightWitnesses.get(deployment), work: directoryIdentity(target.path) };
   const workspace = Object.hasOwn(input, "workspace") ? discovery.readWorkspace(input.workspace) : null;
   const selected = typeof input.source === "string" ? sourceOrigin(workspace, input.source) : { reference: input.source, origin: input.origin };
@@ -236,7 +236,7 @@ export function buildFreshPreparationRequest(inspection, options = {}) {
   const { operator, mode, allowLocalPaths = false } = options;
   if (typeof allowLocalPaths !== "boolean") throw oatsError("invalid-declaration", "allowLocalPaths must be boolean");
   if (mode !== undefined && (typeof mode !== "string" || !mode.trim())) throw oatsError("invalid-declaration", "preparation mode must be non-empty text");
-  const input = { deployment: inspection.deployment.deployment.path,
+  const input = { deployment: inspection.deployment.deployment.path, workTarget: inspection.workTarget.path,
     source: inspection.source.reference,
     origin: inspection.source.revision.provenance[0], allowLocalPaths,
     ...(inspection.workspace ? { workspace: inspection.workspace.request } : { standaloneContextKey: inspection.context.key }),