@awebai/oats 0.24.0 → 0.24.1

package/docs/workspace-adoption.md

@@ -0,0 +1,285 @@
+# Adopt the OATS development workspace
+
+OATS hosts the shared `oats-workspace.yaml`. Its separate `oats.yaml` advertises
+source-complete exports and declares its own reciprocal membership. `oats-dev`
+remains a development-capability repository, including `oats.review`; membership
+neither activates that package nor replaces its existing configuration templates.
+
+This 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.
+The [phase plan](design/2026-09-20-workspace-and-portable-adoption-plan.md) and
+[knowledge model](knowledge-theory.md) retain those separate boundaries.
+
+## Shared versus local
+
+| Git-shared declaration | Operator-local input or evidence |
+| --- | --- |
+| Workspace membership candidates and reviewed source import pins | Local source access and qualified repository observations |
+| A repository's backlink and real package/soul export paths | Working checkout mappings and the explicitly chosen work target |
+| Intrinsic capability requirements and logical knowledge interests | Provider settings, explicit store binding, private human/team choices |
+| Complete immutable instructions and skill resources | Native harness/model/auth, backend endpoint, home and durable state |
+| A reviewed source revision | Exact executable approval, current readiness and deployment acceptance |
+
+No machine paths, credentials, private team identifiers, accepted-store locator or
+owner registry belongs in the public workspace. The uninitialized phase-2 knowledge
+repository is not advertised as a ready knowledge export. 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
+`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.
+
+- The setup expert will help the operator adopt repositories, select capabilities
+  and carry out the normal prepare/approve/scaffold/start steps. It bypasses no
+  executable approval, provider readiness, identity or permission boundary.
+- Every soul created by that flow will declare `requires.capabilities.oats.core`
+  and its source explicitly. The operator can remove or replace that dependency
+  by editing the authored definition, not a captured record; the kernel will not
+  silently reinsert an absent one.
+- The CLI/Desktop entry point 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.
+
+## What this first source commit establishes
+
+- `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.
+  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
+  requirements, not optional defaults. They are published starting revisions,
+  **not proof that their combined bindings/runtime profile is ready**. The provider
+  owner supplies that evidence and any subsequently reviewed compatible revision.
+  Do not replace either requirement with none or erase a read edge to launch.
+
+At these starting pins, the provider boundary is concrete:
+
+- Published OKF2.1.0 already 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.
+
+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.
+
+## Publish in this 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.
+2. In each of the six repositories, review a root `oats.yaml` against its actual
+   source head and actual `oats-package/oats-package.json`. The declaration is:
+
+   ```yaml
+   schemaVersion: 1
+   workspace:
+     source: git:github.com/awebai/oats
+   exports:
+     packages:
+       - path: oats-package
+   ```
+
+   Preserve payloads, versions, old tags and legacy templates. This does not
+   activate oats.dev, messaging or either optional task integration.
+3. In a subsequent reviewed framework commit, replace the empty imports list with
+   an import of the source commit from step 1:
+
+   ```yaml
+   imports:
+     - source: git:github.com/awebai/oats
+       soul: souls/oats-expert
+       revision: <actual-reviewed-published-source-commit>
+       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.
+4. Qualify reciprocal admission at the now-published observations. A missing
+   backlink, a fork's copied file or a stale workspace observation is not membership.
+   Cross-repository indexes may land separately; until both sides exist, report the
+   specific unqualified member rather than claim the whole graph is ready.
+
+Membership selectors and backlinks omit `revision` deliberately: the repository
+adapter observes the hosting provider's actual default branch, not a guessed
+`main`. Within one preparation, observations are frozen. In particular, the
+framework's self-member and workspace backlink must resolve to the **same commit**.
+A separately pinned older workspace with backlinks resolving to a later head is
+correctly stale; choose a fresh coherent observation, never rewrite an old retained
+record. Imports have their own immutable source revision and need not track each
+new workspace metadata commit.
+
+Importing the exported soul directly does **not** follow the publisher's workspace
+as adopter policy. A different workspace, or an explicitly standalone operator,
+may consume it without membership in the OATS development workspace.
+
+## Inspect source metadata before preparation
+
+The public source inspector 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.
+
+```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:
+
+```json
+{
+  "deployment": "/operator/deployments/oats-pilot",
+  "workTarget": "/operator/projects/oats",
+  "source": "oats-expert",
+  "origin": {
+    "kind": "operator",
+    "document": {"kind": "operator", "id": "workspace-adoption"},
+    "pointer": "/source"
+  },
+  "workspace": {
+    "source": "git:github.com/awebai/oats",
+    "origin": {
+      "kind": "operator",
+      "document": {"kind": "operator", "id": "workspace-adoption"},
+      "pointer": "/workspace"
+    }
+  },
+  "member": {
+    "source": "git:github.com/awebai/oats",
+    "origin": {
+      "kind": "operator",
+      "document": {"kind": "operator", "id": "workspace-adoption"},
+      "pointer": "/member"
+    }
+  }
+}
+```
+
+The paths are operator-selected examples, not host defaults or new grants.
+Independent adoption uses the full source/soul/revision/alias reference and an
+explicit standalone context instead of workspace/member. Do not mix this inspect
+mode with current-context flags or captured deployment/resolution selectors.
+
+The result is **non-authorizing metadata**, not provider readiness: even `ok:true`
+may carry `needs-configuration` or `separate-deployment-required`. A
+`ready-for-preparation` observation still has no approval or enrollment effect.
+Provider payloads and opaque adoption values are deliberately omitted. Preserve
+the original authored inputs; neither the result nor its inspection request is a
+preparation request or an issued mutation witness. In particular, `workTarget`
+and inspection catalog wrappers are not accepted preparation fields.
+
+The inspector owns transient repository scratch but writes no deployment state.
+Missing paths need explicit operator provisioning and reinspection, not automatic
+repair. Observing a project work target does not change the separate captured H/work
+placement. Existing retained inspect remains the later exact-record inspection.
+
+## Prepare a fresh local pilot only after the profile is qualified
+
+Use the selected installed compatible CLI. Do not turn this source check into a
+global install, a daemon start or a model/GUI test on another operator's machine.
+Keep native HOME/profile/auth and explicit permission choices; no credential copy
+or empty profile. Knowledge, messaging and tasks have distinct authority contracts.
+
+Before preparing, the integration lead must supply:
+
+- The published workspace/source observations and an explicit fresh physical
+  deployment/home placement. Do not copy old locks, retained records or identities.
+- An operator-owned nonsecret request with `workspace` (its source and origin),
+  `source: "oats-expert"` after the real import is published, and `mode: "directory"`.
+  Standalone callers instead give the complete `{source,soul,revision,alias}`
+  reference and an explicit standalone context; they do not inherit this workspace.
+- Explicit provider-specific settings and bindings. OKF preparation needs selected
+  absolute `bindings-file` and `state-dir`, `harvest-runtime`, and the `stores.oats`
+  binding; an omitted `harvest-model` preserves native-default intent. The parent-owned
+  acceptance fixture must supply an accepted node registry supporting the preserved
+  owner **and all four read nodes**. This is not accepted production KB publication;
+  Git destinations remain PR-only.
+- Actual messaging human/context inputs and the pilot's explicit **`delivery: session`**
+  setting (aweb's default is channel). Supply it in the complete supported
+  `operator.policy.messaging` selection: capability, matching selected source and
+  `settings: {delivery: session}`. Retain host requirements, session `ifInstalled`
+  minimums and any selected authoring requirements. Selecting session delivery neither
+  adds the missing1.10.3 binding adapter nor supplies captured wake/input authority.
+- A qualified primary/helper runtime/model/resource profile. Capture the intended
+  helper selection in `helperLaunches["oats.okf:memory-harvest"]`, not the legacy
+  `souls.memory-harvest` configuration. Do not replace retained intent to fit an easier
+  runtime profile. An old default-OKF-only learning gate does not qualify a combined
+  aweb profile. If provider or kernel support is missing, stop at that typed result;
+  do not bypass it with a legacy route, a dropped capability or a fabricated identity.
+
+The existing public routes are stepwise (D/R/H are returned or explicitly approved
+values, not names inferred from cwd):
+
+```sh
+oats prepare --request /absolute/operator-preparation.json --json
+# Review returned exact artifacts/problems; approve only explicitly authorized code.
+oats trust <capability-id> --deployment "$D" --artifact-set "$ARTIFACT_SET" --json
+oats prepare --request /absolute/operator-preparation.json --json
+oats inspect --deployment "$D" --resolution "$R" --composition --json
+oats spawn oats-expert --deployment "$D" --resolution "$R" --home "$H" --no-launch --json
+oats session start --deployment "$D" --resolution "$R" --home "$H" \
+  --request /absolute/approved-native-request.json --json
+```
+
+Do not mix other preparation flags into request-file mode. A needs-configuration or
+approval result is not a ready instance. A scaffold materializes resources and may
+run approved hooks; it is not a message exchange or model session. Actual dispatch,
+continuation, native capture, messaging and learning require the integration owner's
+qualified profile and receipts. 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.
+Consult the current installed public help and the provider's supported commands;
+this guide introduces no new CLI grammar. The source inspector above is a separate
+implementation dependency, not a change to the existing prepare request contract.
+
+## Local checks and limits
+
+`node --test test/workspace-repository-layout.test.mjs` checks the actual declarations
+against the shipped codecs/schemas, required providers and owner/read mapping, and
+contained source resources. An isolated native-Git fixture exercises source-before-
+import publication, host-default observations, reciprocal/self admission, refusal of
+missing/stale backlinks, and independent public source projection. Fixture member
+indexes are not evidence that the six real repositories are already published.
+
+Source and metadata checks do not enroll users, initialize the phase-2 store, register
+production writers or qualify private messaging. Parent alone coordinates publication,
+local operator approval and actual adoption. Full Desktop parity follows usable
+infrastructure adoption, not merely seven YAML files passing validation.

package/docs/workspaces.md

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

package/injects/oats-portable.md

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

package/lib/core.mjs

@@ -61,6 +61,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 { readLock3 } from "./portable-lock.mjs";
 import { portableScope, portableStateDirectory } from "./portable-state.mjs";
 import { objectAt } from "./portable-shape.mjs";
@@ -1194,6 +1195,31 @@ export function approveAvailableCapability(deployment, artifactSet, capability,
   return approveAvailableArtifact(deployment, artifactSet, capability, origin, loadRetainedManifest);
 }
 
+/** 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 = {} } = {}) {
+  canonicalJson(input);
+  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 }));
+  } catch (error) { primary = error; throw error; }
+  finally {
+    try {
+      repositories?.close();
+      const current = lstatSync(directory);
+      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("source-incomplete", "inspection scratch ownership changed");
+      removeOwnedStaging(directory);
+    } catch (cleanup) {
+      if (!primary) throw cleanup;
+      const error = new AggregateError([primary, cleanup], "inspection and owned scratch cleanup failed", { cause: primary });
+      error.code = primary.code; error.stagingPath = directory; throw error;
+    }
+  }
+}
+
 /** Explicit new-work preparation, with one frozen repository transaction.
  * This first adapter captures command/curriculum profiles; provider-owned
  * binding or distinct helper policy gaps return needs-configuration, never
@@ -7121,9 +7147,11 @@ function runtimeAuthorityOf(baseline) {
   return { launched: true, tmux: { session: tmux.session, window: tmux.window, socket: resolve(tmux.socket) } };
 }
 
-/** Session control uses the same independent endpoint receipt as retirement. */
+/** Session control uses the independent endpoint receipt and, for captured
+ * homes, its original incarnation's existing home/work custody. */
 function instanceSessionTarget(home) {
   if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
+  const requestedHome = home;
   home = realPathOrNearest(home);
   let baseline, meta;
   try {
@@ -7132,18 +7160,29 @@ function instanceSessionTarget(home) {
   } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`); }
   const authority = baseline.version === RETIRE_BASELINE_VERSION && baseline.home === home && runtimeAuthorityOf(baseline);
   if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
+  let io;
+  if ([baseline, meta].some(value => ["executionBinding", "incarnationId", "captured"].some(key => Object.hasOwn(value, key)))) {
+    // The independent receipt remains the anchor even if mutable home markers
+    // are removed. Missing/invalid captured evidence never falls back to legacy.
+    validateExecutionBinding(baseline.executionBinding);
+    const { row } = readCapturedInstanceAuthority(baseline.executionBinding.deployment, requestedHome);
+    if (row.incarnationId !== baseline.incarnationId || canonicalJson(row.executionBinding) !== canonicalJson(baseline.executionBinding)) {
+      throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "captured incarnation disagrees with independent session receipt");
+    }
+    io = { exec: (...args) => { assertCapturedInstanceCustody(row); return execFileSync(...args); } };
+  }
   const endpointAgrees = authority.sessionTarget
     ? !meta.tmux && ["backend", "binary", "socket", "workspaceId", "paneId", "terminalId", "protocol"].every((key) => meta.sessionTarget?.[key] === authority.sessionTarget[key])
     : !meta.sessionTarget && meta.tmux?.session === authority.tmux?.session && meta.tmux?.window === authority.tmux?.window && resolve(meta.tmux?.socket || ".") === authority.tmux?.socket;
   if (meta.launched !== authority.launched || (authority.launched && !endpointAgrees)) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
-  return { home, target: authority.launched ? authority.sessionTarget || { backend: "tmux", ...authority.tmux } : undefined };
+  return { home, target: authority.launched ? authority.sessionTarget || { backend: "tmux", ...authority.tmux } : undefined, io };
 }
 
 export function inspectInstanceSession(home) {
   if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped" };
   const s = instanceSessionTarget(home);
   if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched" };
-  try { return { home: s.home, ...inspectSessionTarget(s.target) }; }
+  try { return { home: s.home, ...inspectSessionTarget(s.target, s.io) }; }
   catch (e) { throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${e.message}`); }
 }
 
@@ -7157,7 +7196,7 @@ export function inputInstanceSession(home, text) {
   if (typeof text !== "string" || !text.trim() || text.includes("\0") || Buffer.byteLength(text) > 256 * 1024) throw oatsError("E_BAD_ARGS", "session input must be nonempty text without NUL, at most 256 KiB");
   const s = instanceSessionTarget(home);
   if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
-  try { return { home: s.home, ...inputSessionTarget(s.target, text) }; }
+  try { return { home: s.home, ...inputSessionTarget(s.target, text, s.io) }; }
   catch (e) { throw oatsError("E_SESSION_INPUT_FAILED", `cannot submit session input: ${e.message}`); }
 }
 

package/lib/portable-onboarding.mjs

@@ -189,6 +189,25 @@ export function inspectPortableOnboarding(input, { repositories } = {}) {
   return result;
 }
 
+/** Metadata-only public view, NOT a serialized fresh-inspection witness or a
+ * preparation request. Provider payloads/adoption values have not gone through
+ * their owner's nonsecret classification and must not leak through inspection. */
+export function describePortableOnboarding(inspection) {
+  if (!issued.has(inspection)) throw oatsError("invalid-declaration", "inspection summary requires an issued onboarding view");
+  const reference = value => ({ source: value.source, soul: value.soul, revision: value.revision, alias: value.alias,
+    adoptionPresent: Object.hasOwn(value, "adoption") });
+  const { reference: selected, exports, ...source } = inspection.source;
+  return freezeJson({ ...inspection,
+    source: { ...source, adoptionPresent: Object.hasOwn(selected, "adoption"), exports: {
+      souls: (exports.souls ?? []).map(({ path, definition, description }) => ({ path, definition, ...(description === undefined ? {} : { description }) })),
+      packages: (exports.packages ?? []).map(({ path, description }) => ({ path, ...(description === undefined ? {} : { description }) })),
+      knowledge: (exports.knowledge ?? []).map(({ contract, version }) => ({ contract, version, payloadOmitted: true })),
+    } },
+    workspace: inspection.workspace ? { ...inspection.workspace, imports: inspection.workspace.imports.map(reference) } : null,
+    omitted: { providerPayloads: true, adoptionValues: true },
+  });
+}
+
 /** Ephemeral local root custody, not a new persistent authority/schema. Ordinary
  * project content changes are allowed; replacing the inspected directories or
  * provisioning a previously absent deployment requires a fresh inspection. */

package/lib/prepared-resources.mjs

@@ -23,7 +23,7 @@ export function completePreparedResources({ seed, plan, manifests, mode, deploym
   }
   if (problems.length) return { record: null, problems };
   const snapshot = join(directory, "kernel-resources"); mkdirSync(snapshot); mkdirSync(join(snapshot, "injects"));
-  const kernelSkills = ["oats-portable", "oats-portable-setup", "oats-portable-artifacts"];
+  const kernelSkills = ["oats-portable", "oats-portable-artifacts"];
   const workInjection = (workMode) => workMode === "directory" ? "portable-work-directory.md" : `work-${workMode}.md`;
   const injectionFiles = ["oats-portable.md", "portable-instance-boundary.md", ...kernel.workModes.map(workInjection)];
   // Only known kernel resources, never a sweep of the checkout/node_modules,

package/package-catalog.json

@@ -1,8 +1,9 @@
 {
+  "policy": "docs/official-marketplace.md",
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v2.1.0",
+      "ref": "v2.1.1",
       "path": "oats-package"
     },
     "oats.aweb": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",

package/skills/oats-config/SKILL.md

@@ -4,17 +4,16 @@ description: >-
   Use only for configuring a legacy uncaptured OATS deployment with the current
   oats-config.yaml cascade, including legacy activation, agent types, targeting,
   overrides, and templates. Triggers: "legacy oats-config", "uncaptured config",
-  "oats use", or "agent type". For portable source/workspace preparation, load
-  oats-portable-setup instead; this legacy policy never fills a captured record.
+  "oats use", or "agent type". This legacy policy is not a portable preparation
+  authority and never fills a captured record.
 ---
 
 # Configuring legacy uncaptured OATS
 
 > **Legacy-only procedure.** The cascading scopes, agent-type targeting and
 > closest-team rules below are compatibility behavior for uncaptured instances.
-> They are not portable composition authorities. Use **oats-portable-setup** for
-> the source/workspace two-authority model and never consult this cascade as a
-> fallback during captured preparation or dispatch.
+> They are not portable composition authorities. Never consult this cascade as
+> a fallback during captured preparation or dispatch.
 
 Config lives in `oats-config.yaml` at laptop (`~`), workspace, and repository
 levels; resolution walks from a soul's repository outward, closest scope wins.

package/skills/oats-portable/SKILL.md

@@ -112,5 +112,4 @@ still refuse. Do not strip selectors or call legacy forms as a workaround. A sca
 may contain external hook effects; preserve it and escalate rather than deleting
 it. A scaffold marked `spawned-launch-pending` is not a running instance.
 
-Use **oats-portable-setup** for preparation and context choices. Use
-**oats-portable-artifacts** for exact approval and retained A/B diagnostics.
+Use **oats-portable-artifacts** for exact approval and retained A/B diagnostics.