@awebai/oats 0.23.2 → 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

@@ -0,0 +1,16 @@
+## You run on a captured OATS composition
+
+You are an instance of a retained soul/helper composition selected by
+`instance.json.executionBinding`. Managed instructions, skills, capabilities,
+settings, provider bindings, and executable resources come from that exact
+`deployment` + `resolution`; do not replace them with a current checkout,
+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.
+
+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/injects/portable-instance-boundary.md

@@ -0,0 +1,39 @@
+## Captured instance: home, source and work
+
+**Your instance home** is the specific OATS instance directory supplied as
+`OATS_INSTANCE_HOME`, not your user home, source repository or work target.
+`instance.json.executionBinding` names the explicit captured **deployment and
+resolution**. Home-bound actions must also match this owned home's incarnation
+and recorded custody. Do not invent, copy or rewrite those identifiers to make
+another home or composition appear authorized.
+
+- **Home holds composed instructions and instance state.** `AGENTS.md` is the
+  canonical composed instruction file; `CLAUDE.md -> AGENTS.md` is its relative
+  compatibility alias, not a second instruction source. Preserve the generated
+  instructions, aliases and metadata; do not hand-edit them to change authority.
+  Task material and provider-managed state belong where their owning contract
+  specifies. The selected capabilities define any knowledge or memory protocol.
+- **`./soul` is a read-only retained source link, not your edit surface.** Reading
+  it must not depend on the publisher's current checkout. Never write through it
+  or modify retained artifacts. If a task authorizes source changes, use its
+  explicitly authorized tracked work surface and review path instead.
+- **`./work` is the task's work surface.** The work-mode instructions determine
+  whether it is an owned directory or another permitted repository view. Make
+  task edits only on that authorized surface, not in deployment stores or a
+  convenient source checkout. Reading an external input is not permission to
+  modify it or its owner.
+
+For supported captured commands, keep the explicit `--deployment` and
+`--resolution` pair from the recorded binding; supply the exact owned home when
+an action requires one. Running from home preserves the invocation's working
+location, but **cwd and a recorded `repo` path never select configuration or
+execution authority**. Source location, deployment, work target and team
+membership are separate facts. Do not fill missing inputs from a config cascade,
+a current lock, an alias match or another instance's environment.
+
+Load **oats-portable** for the running kernel's supported captured operations.
+A no-launch scaffold or `launchPending` receipt is not a running agent. Where
+captured launch, start/restart/wake/retire or recovery is unsupported, stop and
+report the limitation; do not strip selectors or use a legacy command as a
+workaround. Preserve work, knowledge, native history, identities and outstanding
+cleanup receipts. Missing authority is a hold, never permission to erase state.

package/injects/portable-work-directory.md

@@ -0,0 +1,29 @@
+## Portable work mode: owned directory
+
+Your `./work` is an **instance-owned execution directory**, not a Git worktree,
+a checkout, or a link to the source, deployment or another instance. No Git
+repository or branch is created by this mode. Do not initialize a fake repository
+to satisfy a workflow; a containing Git repository does not grant authority over
+its contents.
+
+- Do task work inside `./work`. External inputs and delivery destinations require
+  explicit task/capability authorization. Neither a source link nor a recorded
+  `repo` or work-target path grants permission to edit that external directory.
+- Execution uses the explicit captured deployment/resolution and, for home-bound
+  actions, the matching owned home/incarnation binding. Cwd does not resolve
+  configuration or select a provider; do not rebind from a current checkout,
+  config cascade, package lock or another instance.
+- Preserve home/work separation and canonical instruction aliases:
+  `AGENTS.md` in home, `CLAUDE.md -> AGENTS.md`, and the generated skill aliases.
+  The home's `./soul` link and retained software are read-only, not edit surfaces.
+- Deliver results using the task and selected capability's supported protocol.
+  This mode imposes no knowledge layout, harvester, storage backend or publication
+  policy. A recovery copy, if independently verified, is not publication or
+  accepted delivery.
+
+Keep nonempty work and its custody evidence intact. This mode does not promise
+implemented captured launch, start/restart/wake/retire or automatic recovery.
+Before any supported, explicitly authorized teardown, require verified
+preservation of outstanding work and receipts; if that capability is unavailable,
+hold and report rather than deleting or moving the home/work yourself. A
+`launchPending` result means runtime launch remains pending.

package/lib/artifact-approvals.mjs

@@ -0,0 +1,120 @@
+/** Exact-artifact local approval authority. Presence/catalog/legacy trust and
+ * captured booleans never grant approval. No current selection-lock lookup. */
+import { join } from "node:path";
+import { canonicalJson, parseStrictJson } from "./portable-values.mjs";
+import { jsonIntegrity } from "./portable-digest.mjs";
+import { objectAt, versionAt } from "./portable-shape.mjs";
+import { validateArtifactRef, validateOrigin } from "./resolution-shape.mjs";
+import { verifyResolutionInputs, verifyRetainedCapability } from "./captured-resolutions.mjs";
+import { verifyPortableArtifact } from "./portable-artifacts.mjs";
+import { readLock3 } from "./portable-lock.mjs";
+import { executableSurfaceOf, hasExecutableSurface } from "./capability-execution.mjs";
+import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
+import { readPortableBytes } from "./portable-files.mjs";
+import { portableStateDirectory, withPortableStateWrite, writeGuardedPortableDocument } from "./portable-state.mjs";
+import { oatsError } from "./errors.mjs";
+
+const emptyLedger = () => ({ schemaVersion: 1, capabilities: Object.create(null) });
+const invalid = (message) => { throw oatsError("invalid-approval", message); };
+export function artifactApprovalKey(artifact) {
+  validateArtifactRef(artifact);
+  if (artifact.kind !== "capability") invalid("capability approval cannot authorize an unrelated resource bundle");
+  return `${artifact.integrity.format}:${artifact.integrity.value}`;
+}
+export function validateApprovalLedger(ledger) {
+  canonicalJson(ledger);
+  objectAt(ledger, ["schemaVersion", "capabilities"], ["schemaVersion", "capabilities"]);
+  versionAt(ledger.schemaVersion); objectAt(ledger.capabilities, null, []);
+  for (const [id, entries] of Object.entries(ledger.capabilities)) {
+    if (!isMaterializedCapabilityId(id)) invalid("invalid approval capability identity");
+    objectAt(entries, null, []);
+    for (const [key, entry] of Object.entries(entries)) {
+      objectAt(entry, ["artifact", "approved", "provenance"], ["artifact", "approved", "provenance"]);
+      if (artifactApprovalKey(entry.artifact) !== key || entry.artifact.capability !== id || entry.approved !== true) invalid("approval key, artifact or capability differs");
+      if (!Array.isArray(entry.provenance) || !entry.provenance.length) invalid("approval requires explicit operator provenance");
+      for (const origin of entry.provenance) {
+        validateOrigin(origin);
+        if (origin.kind !== "operator" || origin.document.kind !== "operator") invalid("approval cannot inherit source or legacy authority");
+      }
+    }
+  }
+  return ledger;
+}
+export function readApprovalLedger(scope) {
+  const root = portableStateDirectory(scope);
+  const bytes = root === null ? null : readPortableBytes(join(root, "approvals.json"), { allowMissing: true, invalidCode: "invalid-approval" });
+  if (bytes === null) return { ledger: emptyLedger(), integrity: null };
+  const ledger = parseStrictJson(bytes);
+  validateApprovalLedger(ledger);
+  if (!bytes.equals(Buffer.from(canonicalJson(ledger)))) invalid("approval ledger must use canonical JSON bytes");
+  return { ledger, integrity: jsonIntegrity(ledger) };
+}
+function approved(ledger, artifact) {
+  const key = artifactApprovalKey(artifact);
+  return Object.hasOwn(ledger.capabilities, artifact.capability) && Object.hasOwn(ledger.capabilities[artifact.capability], key);
+}
+function manifestFor(verified, id) {
+  return verified.manifests.get(id);
+}
+
+/** Diagnostic projection for this record's capabilities, not an action permit.
+ * Dedicated helper records get their own approval check when used. */
+export function inspectCapturedApprovals(scope, reference) {
+  const verified = verifyResolutionInputs(scope, reference), { ledger } = readApprovalLedger(scope);
+  return { reference, capabilities: evaluateCapturedApprovals(verified, ledger) };
+}
+
+/** Shared evaluation over already verified inputs and a freshly read ledger.
+ * This remains data; the action loader decides which surfaces the action uses. */
+export function evaluateCapturedApprovals(verified, ledger) {
+  validateApprovalLedger(ledger);
+  return Object.entries(verified.record.artifacts.capabilities).map(([id, row]) => {
+    const manifest = manifestFor(verified, id), required = hasExecutableSurface(manifest);
+    return { artifact: row.artifact, required, surface: executableSurfaceOf(manifest),
+      status: !required ? "not-required" : approved(ledger, row.artifact) ? "approved" : "approval-required" };
+  });
+}
+
+function grantApproval(context, artifact, manifest, origin) {
+  const key = artifactApprovalKey(artifact), id = artifact.capability;
+  const { ledger, integrity } = readApprovalLedger(context.deployment);
+  if (!hasExecutableSurface(manifest)) return { artifact, status: "not-required" };
+  if (approved(ledger, artifact)) return { artifact, status: "already-approved" };
+  if (!Object.hasOwn(ledger.capabilities, id)) ledger.capabilities[id] = Object.create(null);
+  ledger.capabilities[id][key] = { artifact, approved: true, provenance: [origin] };
+  validateApprovalLedger(ledger);
+  writeGuardedPortableDocument(context, join(context.root, "approvals.json"), ledger, { absent: integrity === null });
+  return { artifact, status: "approved" };
+}
+
+/** Prospective approval must be possible BEFORE running an executable provider
+ * codec to complete a resolution. Address an exact retained artifact set, never
+ * today's selected capability ID or a fabricated partial resolution. */
+export function approveAvailableCapability(scope, setKey, id, origin, validateManifest) {
+  validateOrigin(origin);
+  if (origin.kind !== "operator" || origin.document.kind !== "operator") invalid("approval requires an explicit operator input");
+  if (typeof setKey !== "string" || !/^sha256-[a-f0-9]{64}$/.test(setKey) || typeof id !== "string") invalid("invalid artifact-set approval target");
+  if (typeof validateManifest !== "function") throw new TypeError("prospective approval requires the complete kernel manifest codec");
+  return withPortableStateWrite(scope, (context) => {
+    const { lock } = readLock3(context.deployment);
+    const set = lock?.artifactSets[setKey];
+    if (!set || !Object.hasOwn(set.capabilities, id)) invalid("capability is not in that exact retained artifact set");
+    const artifact = set.capabilities[id].artifact;
+    const root = verifyPortableArtifact(context.deployment, artifact).dir;
+    const manifest = verifyRetainedCapability(root, set, id, validateManifest(root));
+    return grantApproval(context, artifact, manifest, origin);
+  });
+}
+
+/** Explicit approval writer. Called by the explicit operator approval operation,
+ * not preparation/discovery. Approval still does not qualify provider/host readiness
+ * or replace full manifest/launch compilation at the eventual action boundary. */
+export function approveCapturedCapability(scope, reference, id, origin) {
+  validateOrigin(origin);
+  if (origin.kind !== "operator" || origin.document.kind !== "operator") invalid("approval requires an explicit operator input");
+  return withPortableStateWrite(scope, (context) => {
+    const verified = verifyResolutionInputs(context.deployment, reference);
+    if (typeof id !== "string" || !Object.hasOwn(verified.record.artifacts.capabilities, id)) invalid("approval capability is not selected in this captured record");
+    return grantApproval(context, verified.record.artifacts.capabilities[id].artifact, manifestFor(verified, id), origin);
+  });
+}