@awebai/oats 0.23.2 → 0.24.1

package/skills/oats-packages/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: oats-packages
 description: >-
-  How to acquire, lock, restore, trust, update, remove, and migrate OATS
-  distribution packages with the oats CLI. Use for package sources (git/local/
-  official catalog), oats-lock.json v2, all-or-nothing scope migration, exact restore,
-  per-capability executable trust, runtime dependency closures, or package
-  doctor failures. Triggers: "install a package", "oats install", "oats list",
-  "oats update", "oats remove", "oats migrate", "oats trust", "lockfileVersion",
-  "integrity drift", "package won't restore".
+  Use only for legacy uncaptured OATS package acquisition and mutable installed
+  store operations: oats install/update/remove, lock v1/v2, restore, migration,
+  and legacy trust. Triggers: "legacy package", "uncaptured oats install",
+  "oats-lock v2", or "legacy migration". For retained artifact-set/resolution
+  approval and diagnostics, load oats-portable-artifacts instead.
 ---
 
-# OATS distribution packages
+# Legacy uncaptured OATS distribution packages
+
+> **Legacy-only procedure.** The mutable installed store and lock v1/v2 flows
+> below prepare uncaptured deployments. They are not authority for an existing
+> captured resolution. Use **oats-portable-artifacts** for exact retained
+> inspection/approval; never restore or advance captured code through today's
+> lock or installed capability directory.
 
 A **package** is the install/update/review unit: one git repo (or local dir)
 with an `oats-package.json` exporting one or more **capabilities** (the

package/skills/oats-portable/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: oats-portable
+description: >-
+  Use when operating a newly prepared captured OATS instance, invoking an exact
+  retained command or provider operation, inspecting its immutable composition,
+  creating an explicit fresh scaffold, or starting its captured native session.
+  Triggers: "captured OATS",
+  "portable soul", "resolution ID", "exact retained command", "fresh captured
+  spawn". Do not use for legacy config-chain deployments.
+---
+
+# Operating a captured OATS instance
+
+A captured instance executes one immutable managed composition identified by an
+explicit deployment and resolution. Its source soul, adopter alias, capability
+artifacts, settings, provider bindings, curriculum, helpers, and executable
+resources come from that record—not from the current checkout or config chain.
+Credentials, provider readiness, memberships, knowledge contents, the work target,
+and host tools remain separately checked mutable inputs.
+
+## Authority checklist
+
+1. Read `instance.json.executionBinding` for the exact deployment and resolution.
+2. Pass both selectors together. Never infer either from cwd, a source path, a
+   package lock, an OS user, or another instance.
+3. If the record, retained resource, approval, binding, or host requirement is
+   missing or invalid, stop. Do not retry through an unqualified legacy command.
+4. Treat `responsibleHuman: null` only as explicit messaging-disabled state. It
+   is not an anonymous human or a private-team identity.
+
+## Implemented commands
+
+```bash
+oats inspect --deployment <absolute-deployment> --resolution <sha256-id> --json
+oats inspect --deployment <absolute-deployment> --resolution <sha256-id> --composition --json
+oats <namespace> <command> --deployment <absolute-deployment> --resolution <sha256-id> -- [provider-args]
+oats operation run <knowledge|messaging|tasks>:<name> \
+  --deployment <absolute-deployment> --resolution <sha256-id> \
+  [--home <absolute-instance-home>] [--arg name=value ...] --json
+```
+
+For capability helpers, inspect the source's captured helper map and resolve one
+exact key before selecting a helper record:
+
+```bash
+oats inspect --deployment <source-deployment> --resolution <source-id> \
+  --helper <exact-map-key> --composition --json
+```
+
+Keep `sourceExecutionBinding` for provider completion commands and the returned
+`executionBinding` for the helper. Do not complete through a worker's inherited
+selector or use legacy helper-name discovery. Helper inspection is not worker
+launch; use the staged public start below and retain its actual dispatch result.
+
+A fresh captured directory scaffold is available only with explicit placement
+and no launch:
+
+```bash
+oats spawn <captured-subject> \
+  --deployment <absolute-deployment> --resolution <sha256-id> \
+  --home <absolute-new-home> --no-launch --json
+```
+
+The subject must match the retained soul alias or helper name. The home must be
+new and its parent physical. This command materializes retained instructions and
+skills, creates owned directory work, and runs captured spawn hooks. It does not
+select a work repository, launch a model, or infer a team.
+
+## Start the owned captured home
+
+After the explicit scaffold/hooks stage, start using the same retained authority:
+
+```bash
+oats session start --deployment <absolute-deployment> --resolution <sha256-id> \
+  --home <owned-home> --request <absolute-native-request-json> --json
+```
+
+The native request is a closed object, for example:
+
+```json
+{"schemaVersion":1,"backend":{"backend":"tmux","binary":"/absolute/tmux","socket":"/absolute/socket","session":"captured"},"task":"Explicit task"}
+```
+
+For Herdr, replace only `backend` with
+`{"backend":"herdr","binary":"/absolute/herdr","socket":"/absolute/herdr.sock","protocol":20}`.
+Use an explicit existing operator-managed socket; this route never starts a
+Herdr daemon or falls back to tmux. Actual workspace/pane/terminal IDs arrive in
+the receipt after allocation, never from caller naming. API discovery advertises
+`oats.captured-session@2` with both backends and `readiness:not-checked`.
+
+Runtime/model/yolo come from the capture, never this request. Optional
+`stopGraceMs` is bounded 1–300000. No env/io/credential/provider/config fields.
+For an already scaffolded helper, pass the SOURCE selectors and add
+`--helper <exact-map-key>`; the home must match the returned dedicated helper
+binding. This revalidates the edge, not just a helper name.
+
+Use `session restart` for a distinct restart request in the same incarnation.
+Once stored, task/backend can be omitted to use owned values. Use
+`--retry-intent <saved-executionId>` only for an explicit replay/retry of that
+same logical request. An unknown Herdr allocation must remain held under its
+saved intent; never repeat workspace creation or guess its IDs from a label.
+Preserve `error.details.nativeCustody` and the indexed
+pending identity on uncertainty; never allocate another home/ID to disguise it.
+`dispatchAccepted` means native dispatch, not task completion/model health or
+privacy. A completed receipt replay may return `replayed:true` instead.
+
+## Current refusal boundary
+
+Captured wake/retire, unqualified managed runtime packages/contributions, extra
+native arguments, non-directory work targets and backends other than tmux/Herdr
+still refuse. Do not strip selectors or call legacy forms as a workaround. A scaffold marked `spawn-failed-cleanup-required`
+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-artifacts** for exact approval and retained A/B diagnostics.

package/skills/oats-portable-artifacts/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: oats-portable-artifacts
+description: >-
+  Use when inspecting or approving exact retained artifacts for a portable OATS
+  composition, reviewing approval-required preparation, comparing retained A/B
+  revisions, or diagnosing missing and damaged captured resources. Triggers:
+  "artifact set", "captured approval", "available unapproved", "retained
+  resolution", "source deleted". Do not use legacy mutable installed-store trust
+  as captured execution authority.
+---
+
+# Captured artifacts and approvals
+
+Retention, selection, and approval are distinct:
+
+- Retention keeps exact source, capability, and resource trees.
+- A captured resolution selects one immutable managed composition.
+- Approval authorizes an exact executable capability artifact revision.
+- Current provider/credential/host readiness is checked again per action.
+
+Artifact presence is never approval. A newer available artifact does not replace
+an existing captured instance's artifact, and "available" does not mean latest,
+approved, or selected.
+
+## Implemented inspection and approval
+
+Inspect one exact record without executing capability code:
+
+```bash
+oats inspect --deployment <absolute-deployment> --resolution <sha256-id> --json
+oats inspect --deployment <absolute-deployment> --resolution <sha256-id> --composition --json
+```
+
+Approve a capability already selected by a complete captured record:
+
+```bash
+oats trust <capability-id> \
+  --deployment <absolute-deployment> --resolution <sha256-id> --json
+```
+
+When preparation cannot complete because provider codec execution itself needs
+approval, approve the exact prospective artifact set:
+
+```bash
+oats trust <capability-id> \
+  --deployment <absolute-deployment> --artifact-set <sha256-id> --json
+```
+
+Both selectors are explicit local deployment addresses. Never look up a captured
+artifact by capability ID in today's lock, current installed directory, catalog,
+or source checkout.
+
+## Failure posture
+
+- Missing retained input and damaged retained input are different failures.
+- Damaged state is never repaired during dispatch.
+- Approval cannot cross integrity formats or revisions.
+- Source/config deletion must not change an existing record's selected bytes.
+- Partial or unknown historical evidence is inspectable but never executable.
+- No unattended approval, background refresh, or automatic advancement exists.
+
+Use `oats prepare --help` for new preparation inputs and **oats-portable** to
+invoke the resulting exact record.