@awebai/oats 0.23.1 → 0.24.0

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,116 @@
+---
+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-setup** for preparation and context choices. 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-portable-setup** to create a new preparation transaction. Use
+**oats-portable** to invoke the resulting exact record.

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

@@ -0,0 +1,69 @@
+---
+name: oats-portable-setup
+description: >-
+  Use when preparing a source-complete portable soul for a fresh deployment,
+  selecting a workspace-advertised import, or reasoning about source,
+  deployment, work target, team, adoption, and provider-binding inputs. Triggers:
+  "oats prepare", "portable setup", "import soul by reference", "fresh OATS
+  deployment". Do not use legacy oats-config.yaml cascading as portable policy.
+---
+
+# Preparing portable souls
+
+Portable preparation has two policy authorities and one resolver:
+
+1. The soul supplies intrinsic hard requirements and rebindable defaults.
+2. The workspace supplies admission, workspace defaults, imports/adoption,
+   stores, team references, and catalogs.
+3. Explicit operator choices may rebind defaults and bindings but cannot erase
+   hard requirements.
+
+There is no repository-default tier and no agent-type precedence in this model.
+A package source, soul source, deployment/install location, work target, and team
+membership are separate facts. Never derive one from another.
+
+## Implemented preparation
+
+Prepare an explicit source export by reference:
+
+```bash
+oats prepare \
+  --dir <absolute-deployment> \
+  --source <git-repository> --revision <selector> \
+  --export <exported-soul-path> --alias <local-alias> \
+  [--work directory] --json
+```
+
+Prepare an alias advertised by an explicit workspace:
+
+```bash
+oats prepare \
+  --dir <absolute-deployment> \
+  --workspace <git-repository> [--workspace-revision <selector>] \
+  --alias <advertised-alias> [--work directory] --json
+```
+
+Preparation resolves one source observation, retains the required source and
+software trees, resolves provider-owned nonsecret bindings through the same
+choice engine, prepares dedicated compatible helpers, and publishes a complete
+record before returning a resolution. It does not launch, enroll identities,
+create teams, approve executables, or infer a publisher workspace.
+
+## Read the result correctly
+
+- `resolution: null` means no executable captured record was published.
+- `needs-configuration` identifies missing bindings/provider inputs; do not fill
+  them from current config.
+- `approval-required` can accompany a complete retained record; approval remains
+  a separate explicit action.
+- `responsibleHuman: null` means messaging is explicitly disabled.
+- Helper-authored software, knowledge, team, or resource policy currently
+  requires dedicated preparation and refuses instead of inheriting the parent.
+
+## Not yet a public input
+
+An explicit standalone context key, onboarding inspection facade, non-directory
+work-target placement/setup, and managed launch/runtime capture are still being
+integrated. Do not invent flags or derive a standalone key from a path, username,
+source alias, or machine identity. A workspace context and standalone context are
+mutually exclusive.