@awebai/oats 0.25.8 → 0.26.0

package/skills/oats/SKILL.md

@@ -1,162 +0,0 @@
----
-name: oats
-description: >-
-  Use only for operating a legacy uncaptured OATS deployment through its current
-  config chain: legacy status, spawn, retire, doctor, capability commands, and
-  instance layout. Triggers: "legacy OATS", "uncaptured instance", or an
-  instance without executionBinding. For a captured portable composition, load
-  oats-portable instead; never use this skill to fill missing captured inputs.
----
-
-# Operating legacy uncaptured OATS
-
-> **Legacy-only procedure.** This skill documents the current config-chain
-> engine for instances without a captured execution binding. A portable instance
-> must use **oats-portable** and explicit deployment/resolution authority. Never
-> apply the config cascade, agent types, or team-scoped lookup below to complete
-> or override a captured record.
-
-A **soul** is a durable specialized agent. An **instance** is one disposable,
-resumable incarnation. A **capability package** distributes reusable skills,
-instructions, commands, and approved lifecycle hooks. An **integration** is a
-capability selected for one exclusive knowledge, messaging, or tasks layer.
-
-## Instance home
-
-| Path | Meaning |
-|---|---|
-| `TASK.md` | briefing and task |
-| `soul/` | linked canonical soul |
-| `AGENTS.md` | generated canonical soul + active capability instructions |
-| `CLAUDE.md -> AGENTS.md` | compatibility view |
-| `.agents/skills/` | exact runtime skill set |
-| `work/` | all repository work happens here |
-| `instance.json` | repo, branch, capabilities, skills, instruction sources, trust, hooks |
-
-Memory files exist only when the selected knowledge integration creates them.
-Follow their injected protocol.
-
-## Lifecycle and roster
-
-```bash
-oats status [--json]
-oats status --team [--json]   # whole-team roster when config declares team: (all repos in the team scope)
-# with the aweb messaging integration active, `oats aweb roster` adds the
-# cross-machine view: aweb team members, where OATS aliases are instance names
-oats create <name> [--description ...] [--type <agent-type>] [--repo ...] [--work worktree|checkout|attached|workspace|directory]
-# directory mode = owned execution directory; repo is config context (no Git
-# required); --work-dir and --branch are rejected; retirement preserves work.
-# workspace mode = cross-repo coordinator: ./work is the whole team scope; read
-# all member repos, edit none; if a knowledge layer is active, IT defines how
-# soul updates are delivered (see that capability's own instructions)
-oats spawn <agent> [--task ...] [--purpose ...] [--relation child|sibling|parent|unrelated --relative-to <instance>] [--parent <instance>] [--no-launch] [--json]
-# lineage is explicit: agents spawning sub-agents declare their RELATION to the
-# new instance with --relation + --relative-to (--parent X is sugar for
-# --relative-to X --relation child). Without a relation the spawn is
-# operator-origin and appears top-level. Attached-mode spawns are ALWAYS
-# children of the work-tree owner (relation flags are rejected there).
-# when config declares team:, spawn/retire also resolve souls and instances
-# defined in sibling repos of the team scope (unique match wins; the instance
-# homes with its owning repo, works in that repo, resolves that repo's config)
-oats retire <instance> [--delete-branch]
-```
-
-### Spawn relations — choosing how the new instance relates to you
-
-When you spawn, declare what the new instance IS to you — the workspace is
-viewed as clusters of related agents, and the relation is how clusters form:
-
-- **child** (`--relation child --relative-to <you>`, or `--parent <you>`) —
-  the new instance works FOR you and nests under you. Example: a coordinator
-  spawning the developers of its feature.
-- **parent** (`--relation parent --relative-to <you>`) — the new instance
-  oversees YOU: your recorded lineage is re-pointed so it becomes your parent.
-  Example: spawning a maintainer of your own PR — the maintainer sits
-  above you. When it later retires, lineage is spliced automatically: you
-  return to your previous parent (or top-level).
-- **sibling** (`--relation sibling --relative-to <you>`) — a peer at your
-  level, in your cluster. Example: enlisting a peer coordinator in another
-  repo, or an architecture coordinator helping you.
-- **unrelated** (default, no flags) — no link. Example: work with no
-  connection to yours.
-
-Exception: **attached** work mode implies child-of-owner — an attached agent
-shares its owner's work tree and is always that owner's child; relation flags
-are rejected there.
-
-This is judgment, not mandate: every workspace differs, and a soul's own
-explicit relation instructions (in its AGENTS.md or task briefing) take
-precedence over these defaults. When unsure which relation fits, check with
-the human.
-
-Do not spawn on your own judgment. Spawn when the human asks or a documented
-workflow requires it.
-
-### Instance naming
-
-Name an instance for both **who it is** and **what this incarnation does** by
-spawning with `oats spawn <soul> --purpose <descriptive-role>`. OATS constructs
-`<full-soul-name>-<descriptive-role>`; use a short, lowercase kebab-case role
-suffix (for example, `desktop-ux` or `terminal-safety`), not an opaque number
-or generic word. The current spawn command always retains the full soul name,
-so shorten the purpose—not the soul prefix—when the result would be unwieldy.
-Do **not** use `oats create` to name an incarnation: it creates a new persistent
-soul. Never put secrets, user data, or volatile task details in an instance
-name.
-
-To self-retire, first finish memory/commit/reporting requirements, report final
-status, then run `oats retire <own-instance> --self`. That returns at once and
-a detached completion retires you a few seconds later exactly as an external
-`oats retire` would (quiesce, preserve work, hooks, remove the home). If the
-completion fails, your window stays, the failure shows in `oats status` with
-the retry command, and an operator retries. Never retire merely to clean up;
-retirement deletes the instance home.
-
-## Canonical versus generated
-
-Edit `soul/AGENTS.md` for durable role instructions. Instance `AGENTS.md` is a
-generated view; marked blocks name their source. Config changes do not mutate
-the committed soul. Preview a fresh composition with:
-
-```bash
-oats doctor /path/to/context --soul <name>
-```
-
-The instance's `.agents/skills/` holds the exact OATS-composed set (kernel +
-soul + active capabilities); `.claude/skills` mirrors it. Harness-ambient
-skills (user-level, packages, work tree) coexist with this set. Duplicate
-names *within* the OATS set fail spawn unless `skill-overrides` explicitly
-chooses a source.
-
-## Configuration
-
-Deployments are configured in scoped `oats-config.yaml` files (laptop /
-workspace / repository) declaring capability packages, exclusive
-knowledge/messaging/tasks layers, agent types, targeting, and injection
-overrides. The CLI is the config author (`oats init`, `oats use`, `oats type`,
-`oats inject eject`). **Load the `oats-config` skill for all configuration
-work** — this skill covers operating, not configuring.
-
-## Commands and doctor
-
-Operational namespaces run only when their package is active in the current
-context/instance:
-
-```bash
-oats okf harvest
-oats linear issue list ...
-```
-
-Package-management commands remain global. Use doctor first when something is
-missing:
-
-```bash
-oats doctor [context] [--soul <name>] [--json]
-```
-
-It shows config chain, acquired/active packages, layer selection, target and
-settings provenance, requirements, trust, skill sources, instruction blocks,
-and—with `--soul`—final composed text.
-
-Infrastructure faults should be reported to the spawner/human, not repaired by
-an instance ad hoc.

package/skills/oats-config/SKILL.md

@@ -1,164 +0,0 @@
----
-name: oats-config
-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". 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. 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.
-Prefer the CLI for config edits (`oats init`, `oats use`, `oats type`,
-`oats inject eject`, `oats create --type`); hand-editing is valid but the CLI
-writes the canonical shape.
-
-## Shape
-
-```yaml
-team:                          # deployment boundary (typically workspace scope)
-  name: lfx-engineering
-  # id: lfx-engineering:example.com   # provider team id (aweb <name>:<namespace>)
-agent-types:
-  developers:
-    description: Agents that build the service
-capabilities:
-  layers:                      # exclusive fundamental slots
-    knowledge:
-      capability: oats.okf
-      from: installed            # enforced provenance: installed|owned|path:<dir>
-      # injection-override: .agents/injections/capabilities/oats.okf.md
-    messaging: none            # explicit none suppresses inherited integrations
-    tasks: none
-  additive:                    # non-exclusive packages
-    vendor.review:
-      from: installed
-      agent-types:
-        developers:
-          enabled: true
-          settings: {depth: normal}
-      souls:
-        api-expert:
-          enabled: true
-          settings: {depth: exhaustive}
-```
-
-`global` means every soul governed by the declaring level. Bindings can also
-target **agent types** (families — declared in config via `oats type add`,
-joined via `type: <name>` in each soul.yaml) and individual souls. Matching
-global + agent-type + soul bindings compose. Settings precedence is
-soul > agent-type > global, then closer config. Equal-specificity conflicts
-error. `false`/`enabled: false` is an explicit exclusion and follows the same
-precedence. V1 does not target instances or use tags/selectors.
-
-The closest `team:` declaration marks the deployment boundary: all repos
-under it share one team (identity + `oats status --team` discovery + the
-messaging provider's team). Declare it once at the workspace scope. With
-aweb messaging active, `oats aweb setup` walks the onboarding (aw CLI →
-workspace init → team create/join) and `oats aweb roster` shows the
-cross-machine member directory.
-
-```bash
-oats type add <name> [--description <d>] [--dir <level>]
-oats type list
-```
-
-## Injection overrides
-
-Capability entries and the `oats:` kernel block take an
-`injection-override: <path>|none|default`. Work-mode briefings are packaged
-and NOT overridable; the only work-mode key is `setup:` (env bootstrap run in
-each new worktree). The clean path is ejecting:
-
-```bash
-oats inject eject <capability-id|oats> [--dir <level>]
-```
-
-It copies the packaged default to the conventional
-`.agents/injections/{capabilities/<id>.md, oats-defaults/oats.md}` path and
-sets the override — the file then stops
-tracking package updates, deliberately. Overrides are **not allowed** on
-`from: owned`/`path:` capabilities: the scope owns the package source, so
-edit `.agents/capabilities/owned/<id>/injects/` directly.
-
-## Activate
-
-Acquisition, trust, and package lifecycle → the **oats-packages** skill. The
-config side is activation and targeting of already-acquired capabilities
-(acquired or catalog availability never implies activation):
-
-```bash
-oats use <capability> --global [--dir <level>]
-oats use <capability> --type <agent-type> [--disable]
-oats use <capability> --soul <name> [--settings k=v [k2=v2 ...]]
-```
-
-`oats init` creates config and activates only explicit defaults.
-
-## Package config templates
-
-A distribution package can ship reference **config templates**. Adopting one
-writes it as this scope's ordinary `oats-config.yaml` and records the exact
-template as a commit-safe **adopted base** — provenance, never live inheritance.
-Installing the package alone adopts no template.
-
-```bash
-oats init --package <id|path|git-url> [--config <name>]   # acquire + adopt one template
-oats config diff                                          # report drift; never merges
-oats config sync [--accept <regionId>=local|package]      # apply upstream; keep local edits
-oats config sync --reset --yes                            # discard local; take the template verbatim
-oats config adopt <package> [--config <name>]             # switch to a different base
-```
-
-The config is yours: retarget, disable, re-set, or replace anything the template
-enabled; nested repository configs override it per the normal cascade; package
-updates never rewrite it or the adopted base. `oats config sync` preserves your
-untouched bytes, comments, and formatting, and a region changed both locally and
-upstream is a conflict you must resolve explicitly. See docs/packages.md for the
-full adoption and sync UX.
-
-## Fundamental layers
-
-Knowledge, messaging, and tasks are formal exclusive contracts. A package
-manifest declaring one `layer` is an integration. Two active integrations for
-the same layer error; a closer scope's entry (or `none`) overrides outer ones.
-
-| Layer | Bundled | Requirement |
-|---|---|---|
-| knowledge | `oats.okf` | none |
-| messaging | `oats.aweb` | `aw` CLI |
-| tasks | none by default; `oats.jira` or `oats.linear` available | provider-specific |
-
-Activation uses the manifest-declared layer — `oats use` writes the entry
-under `capabilities.layers.<layer>` automatically:
-
-```bash
-oats use <capability> --global|--type <agent-type>|--soul <name>
-oats use none --layer <layer>
-```
-
-`capabilities` is the only activation map: fundamental integrations under
-`capabilities.layers.<layer>` (entry or explicit `none`), everything else
-under `capabilities.additive`.
-
-Rare hand-edited keys: `skill-overrides:` (names the winning source on
-duplicate skill names), the top-level `agents-md-injection:` map (extra
-unconditional instruction blocks), `templates:` (named init seeds).
-
-## Verify
-
-```bash
-oats doctor [context] [--soul <name>] [--json]
-```
-
-Doctor shows config chain, acquired/active packages, layer selection, target
-and settings provenance, requirements, trust, skill sources, instruction
-blocks, and — with `--soul` — the final composed AGENTS.md.

package/skills/oats-packages/SKILL.md

@@ -1,184 +0,0 @@
----
-name: oats-packages
-description: >-
-  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.
----
-
-# 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
-activation unit) and optional config templates. Acquiring a package activates
-NOTHING — activation stays in `oats-config.yaml` (see the oats-config skill).
-Never hand-edit `oats-lock.json` or the stores; every operation below is a CLI
-command, and all of them take `--json` (one stdout envelope, stable error
-codes) and `--dir <scope>`.
-
-## Sources
-
-```
-oats install git:github.com/org/repo@v1.0.0    # git shorthand (ref optional; resolved once, exact-locked)
-oats install https://host/org/repo.git@v1.0.0  # raw HTTPS/SSH git URL
-oats install ../my-package                     # local path (dev escape hatch)
-oats install <catalog-id>                      # official catalog short id (identity only — no auto-trust)
-```
-
-### Which directory in the repo is the package?
-
-A git repository CONTAINS a package; it is not one. The package root is the
-directory carrying `oats-package.json`, and a git source selects it with a
-`#<path>` fragment after any `@ref`:
-
-```
-oats install git:github.com/org/repo@v1.0.0            # → repo's oats-package/   (the DEFAULT)
-oats install git:github.com/org/repo@v1.0.0#dist/oats   # → repo's dist/oats/
-oats install git:github.com/org/repo@v1.0.0#.          # → the repository ROOT
-```
-
-- **Omit it and you get `oats-package/`.** Every official example, scaffold and
-  convention uses `oats-package/` — never a generic `package/`. A repo whose
-  manifest sits at the root needs `#.`; the error message says so.
-- **Only the selected subtree is installed and hashed.** Repository docs, CI
-  config, owner souls and sibling packages never become installed bytes and
-  never affect `integrity` — so editing them cannot invalidate approvals, and
-  editing the payload (including a nested capability-agent soul) always does.
-- **One repo can ship several packages** at different paths; install each by
-  its own source. Two contained roots claiming the SAME package identity still
-  fail with `duplicate-package-identity`.
-- **Catalog ids take no fragment** — the catalog entry carries `path` itself.
-- **Local paths take no fragment either**: `oats install /repo/custom-root`
-  treats that exact directory as the package root whatever it is named. There
-  is no `oats-package` default for local sources.
-
-The lock records the selected root in its own `path` field, in canonical form
-(`.` for a root selection). A bare `oats install` restores the locked
-source + commit + **path** + integrity even if upstream moved the directory or
-the catalog repointed; only `oats update <package>` may adopt a new path, and it
-reports the move. Attempting to move it with a plain `oats install` is refused
-with `integrity-drift`.
-
-Local capability development is untouched by all of this:
-`.agents/capabilities/owned/<id>` (`from: owned`) and `from: path:<dir>` are
-not package sources and are never routed through package paths.
-
-Installing a package MATERIALIZES each capability it exports into
-`<scope>/.agents/capabilities/installed/<id>/` (gitignored). There is no
-persistent package store. Dependencies declared in `oats-package.json` must be
-pinnable (official selector, tag/commit, or path). The whole closure is
-exact-locked in the scope's `oats-lock.json` (`lockfileVersion: 2`), which
-records two maps: `packages` (source, exact commit, selected path, payload
-integrity, dependencies) and `capabilities` (each artifact's version, provider
-package, path, integrity, trust).
-
-## Everyday operations
-
-```
-oats install                    # bare: EXACT restore of this chain's locks (never advances refs)
-oats list [--json]              # packages, exported capabilities, scopes, trust state
-oats update <package>           # transactional: temp fetch, closure validation, diff,
-                               # artifact+lock replaced together; approvals of every
-                               # CHANGED-integrity package are invalidated (unchanged
-                               # packages in the closure keep theirs)
-oats remove <package>           # refuses while config or dependent packages reference it
-```
-
-## Trust
-
-Executable surfaces (commands/hooks) are blocked until approved at each
-capability artifact's EXACT integrity:
-
-```
-oats trust <capability>                     # approve only that capability
-oats trust <package> --all-capabilities     # explicit bulk; prints the full executable surface first
-```
-
-Any artifact integrity change (update, drift) resets that capability's trust —
-re-review, then re-trust. Skill/instruction/config-only capabilities need lock
-integrity but no approval. Official-catalog identity is NOT executable trust.
-
-## Runtime dependencies
-
-A capability may check in `package.json` + `package-lock.json`; OATS materializes
-it with `npm ci --omit=dev --omit=peer --ignore-scripts` — production tree only,
-no lifecycle scripts. The package payload hash EXCLUDES `node_modules`. The
-materialized `node_modules` is instead part of that capability's own artifact
-integrity, so tampering with materialized deps resets the capability's trust
-just like source drift, and restore re-verifies it. Closures must be
-platform-invariant. Host peer APIs are reached only through the supported
-runtime boundary, never auto-installed.
-
-## Migration from v1 locks
-
-```
-oats migrate --dry-run          # plan: which v1 capability locks map to packages
-oats migrate                    # convert this scope to revised v2 — all-or-nothing
-```
-
-`oats migrate` is all-or-nothing per scope. It converts a scope to the revised v2
-lock only when EVERY entry maps to a package. If any entry cannot be mapped yet
-(a marketplace id the catalog does not resolve, an unknown source), the whole
-scope stays byte-identical v1 and keeps working — re-run when it can map. A
-successful run writes a fresh v2 lock for the scope. There is NO residue
-container: a converted lock never carries leftover v1 entries. Approvals never
-carry over — re-trust after migrating.
-
-### Upgrading a 0.18 deployment (bundled official capabilities → packages)
-
-```
-oats migrate --official --recursive --dry-run --dir <team-root>   # plan every scope
-oats migrate --official --recursive --dir <team-root>             # apply, scope by scope
-```
-
-Guided mode for existing users. It plans every visible lock-owning scope first
-(ancestor chain incl. outer/laptop locks, team boundary, pruned descendants;
-path order, ancestors first), then applies each scope transactionally.
-
-- Which package supplies a legacy capability is CATALOG data: identity by
-  default, plus aliases (`oats.review` → package `oats.dev`). Never a hardcoded
-  URL or tag, and no ref is guessed from the v1 capability version.
-- Config files are never rewritten — exported ids are unchanged, so activation,
-  layers, targets, settings and exclusions stay valid.
-- No mapping yet at a scope → that scope is HELD and left byte-identical v1
-  (nonzero exit, `--dry-run` included); legacy capabilities keep working. A
-  converting scope moves whole to revised v2 — there is no residue container, so
-  a converted lock never carries leftover v1 entries.
-- `git:`/`path:`/unknown entries are never acquired by guided mode. A scope
-  containing only those entries is skipped with their IDs under `retained`; a
-  scope mixing them with official capabilities is blocked whole and stays v1.
-  Plain `oats migrate` can convert custom sources only when every entry maps.
-- After it runs: `oats trust <capability> --dir <scope>` for each executable
-  surface it names (approvals never transfer), then `oats install --dir <scope>`
-  — already-installed host requirements verify, nothing is reinstalled.
-- `--json` emits one envelope; an aggregate failure is `ok:false` with
-  `error.code = E_MIGRATE_FAILED` and the complete per-scope report (including
-  the scopes that DID migrate) under `error.details`.
-
-`oats doctor` detects the upgradeable state and prints the exact command
-(`officialMigration` in `--json`), or says migration is not available yet while
-confirming the legacy capabilities remain supported.
-
-## Troubleshooting
-
-`oats doctor [dir] [--json]` distinguishes: missing locked package (run
-`oats install`), integrity drift (reacquire/update explicitly — approvals are
-already invalid), a capability whose `.oats-installation.json` disagrees with
-the lock, untrusted executable surface (`oats trust <capability>`), and a legacy
-v1 lock pending migration (`legacyLockFiles[]` plus `officialMigration`
-readiness). A refused lock — including the superseded transitional v2 shape —
-is reported as the single `lockError` diagnosis and is never partially
-interpreted.
-
-Source of truth beyond this skill: `oats --help` output,
-`docs/oats-package.schema.json`, `docs/oats-lock.schema.json`, and
-`docs/design/package-engine-contract.md` (+ `package-runtime-api.md`) in the
-framework repo; `docs/capabilities.md` for the user-level walkthrough.

package/skills/oats-portable/SKILL.md

@@ -1,115 +0,0 @@
----
-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.